The spec is a mini app. 规格，本身就是一个 Mini App。

Documents drift. Evidence doesn't.文档会漂移，证据不会。

A hardened implementation of Matt Rickard's The Unreasonable Effectiveness of Mini Apps as Specs — the spec ships as a tiny app stakeholders click through, annotate, and hold the implementation accountable to. On top of the essay, four things a document can't have:

Matt Rickard 的 The Unreasonable Effectiveness of Mini Apps as Specs 的加固实现——规格以小应用的形态交付，评审者点着看、钉着批、拿它问责实现。在原文思想之上，补齐文档做不到的四件事：

One file, four views — all real, all from the live demo一个文件、四个视图——全部真实截图，来自在线 Demo

Every screenshot below is the actual artifact produced by the pipeline for a fixture feature (an export-watermark toggle — no real product data). Open it and click around.

下面每张截图都来自管线为一个虚构功能（导出水印开关，无任何真实业务数据）生成的真实产物。打开它随便点。

Flow overview — an infinite canvas state machine流总览——无限画布上的状态机

Each flow renders as a pannable, zoomable SVG state machine straight from the contract.

每条流按合同直接渲染为可拖拽、可缩放的 SVG 状态机。

• Solid = default path, dashed = guard branches, double frame = terminal
• 实线=default 主路径，虚线=guard 分支，双框=终态
• Risk tier / core / alignment badges per flow; click a node to jump into the prototype
• 每流带风险档 / core / 对齐徽标；点节点直接跳进原型对应状态
• Open issues surface right below — undecided questions never hide
• 未决 issues 就列在正下方——没拍板的问题永远藏不住

Flow Map view

A living prototype — not a slide deck活的原型——不是幻灯片

One persistent screen per flow. Drag the slider and the watermark reacts through a CSS variable — zero re-render, values survive state switches.

一条流一块持久屏。拖动滑竿，水印透明度经 CSS 变量实时联动——零重建，状态切换控件值不丢。

• State machine chips highlight where you are, in real time
• 状态机徽标实时高亮当前位置
• Memory-state vs persisted-state dataflow panels + event log
• 「内存态 vs 已落库」数据流面板 + 事件日志
• Numbered callout pins explain regions in-picture; cloud callbacks simulated by timed auto-transitions
• 数字标注钉在画面里讲解区域；云端回调用定时自动转移模拟

Living Prototype view

Scenario acceptance — BDD cards that stay honest场景验收——不说谎的 BDD 卡片

Given/When/Then straight from the contract, each with its verification kind and a derived status no one can hand-edit.

Given/When/Then 直接来自合同，每条挂着验证方式与推导状态——没人能手改。

• passed only ever comes from evidence; the manual scenario honestly shows not-run
• passed 只可能来自证据；manual 场景老老实实显示 not-run
• ▶ jumps into the prototype at the scenario's anchored state, with auto-play walkthroughs
• ▶ 一键跳进场景锚定的原型状态，支持自动演示走查
• Requirement tracing shows which scenarios cover which requirement
• 需求追踪显示每条需求被哪些场景覆盖

Scenario Acceptance view

Run evidence — every claim carries its receipt运行证据——每个结论都带小票

Runs are executed by the tool itself, never reported by the agent. Each carries exit code, git head, hashed output and evidence files.

运行由工具亲自执行、绝不听 agent 转述。每条带退出码、git head、哈希输出与证据文件。

• 适用 (applicable) vs 历史 (historical): change a Then and old evidence silently invalidates
• 适用 vs 历史：改了 Then，旧证据自动失效
• dirty badges when the working tree wasn't clean — visible, not hidden
• 工作区不干净就打 dirty 徽标——可见，不藏
• Secret-safe grep judge counts matches without ever logging matched values
• grep 判定器只计数、绝不落匹配值——密钥安全

Run Evidence view

Three layers, one file三层架构，一个文件

The HTML is the database. spec.mjs is the only write path — if the validator fails, nothing is written. The render engine is stateless and business-agnostic.

HTML 是数据库；spec.mjs 是唯一写入口——validator 不过，什么都写不进去；渲染引擎无状态、与业务无关。

mini-app-spec.html              ← the deliverable: double-click to open, no server
├── render engine               (stateless · versioned · business-agnostic)
├── <script id="mini-app-contract">   ← machine contract = SSOT
├── <script id="mini-app-ledger">     ← runs / evidence / annotations / acceptances
├── <script id="mini-app-stamp">      ← envelope: per-block hashes + revision chain
└── <template id="ui-ST-*">           ← declarative, zero-JS prototype screens

Four iron laws, mechanically enforced四条防糊弄铁律，机械执行

Threat model: careless mistakes, lazy shortcuts and hallucination — the last line of defense is always a human looking at evidence.

威胁模型：防误操作、防偷懒、防幻觉——最后一道防线永远是人亲眼看证据。

Two hard stops, per-flow soft stops两个硬停点 + 逐流软停

collect sources → map flows ─🛑 STOP ① user confirms flow list & risk tiers
     ↓
align flow-by-flow (states / transitions / scenarios / prototype)  ⏸ user reviews each flow
     ↓
implementation happens outside this skill
     ↓
freeze commands → record-run per scenario ─🛑 STOP ② user inspects evidence → accept收集来源 → 建流图 ─🛑 停点① 用户确认流清单与风险分档
     ↓
逐流对齐（状态 / 转移 / 场景 / 原型）  ⏸ 每流交用户评审
     ↓
实现（在本 skill 之外进行）
     ↓
冻结验证命令 → 逐场景 record-run ─🛑 停点② 用户亲阅证据 → accept

Pairs best with mattpocock/skills: explore with wayfinder → interrogate the idea into a doc with grill-with-docs → feed doc + Figma (via Figma MCP) into mini-app-spec → escalate high-impact decision strings to grill-me. Without them, it degrades gracefully to built-in leaning multiple-choice questions.

与 mattpocock/skills 搭配最佳：wayfinder 探索 → grill-with-docs 审问出需求文档 → 文档 + Figma（经 Figma MCP）喂给 mini-app-spec → 成串高影响决策升级给 grill-me。一个不装也能优雅退化为内置带倾向选择题。

One line. Then make it prove itself.一行安装，然后让它自证。

For LLM agents — paste this to any agentFor LLM——整段复制给任意 agent

Install and verify the "mini-app-spec" agent skill:

1. Run: npx skills add wohsj110/mini-app-spec --yes
2. Verify — both self-test suites must print ALL PASS:
     node <install-dir>/scripts/run-fixtures.mjs      # 20 cases
     node <install-dir>/scripts/run-injections.mjs    # 32 cases
3. Read <install-dir>/SKILL.md before first use:
   - Artifacts live at docs/mini-app-spec/<feature>/mini-app-spec.html, inside a git repo.
   - All writes go through: node <install-dir>/scripts/spec.mjs <command> …
   - Never hand-edit the artifact HTML; edit via extract → modify JSON → save.

Requirements: Node ≥ 18 and git. Zero runtime dependencies. MIT licensed. README in English · 简体中文 · 日本語 · 한국어.

要求：Node ≥ 18 与 git。零运行时依赖。MIT 协议。README 提供 English · 简体中文 · 日本語 · 한국어。