openone-workflow-kit 0.1.0

package/workflow/core/capabilities/contract-tracer.md

@@ -0,0 +1,53 @@
+# Capability: contract-tracer
+
+- **Tier**: essential
+- **Stage**: `/03`, `/05`
+- **Purpose**: 追踪跨服务、跨层或前后端契约，防止只看 DTO、方法签名或兼容注解就结束审查。
+
+## 为什么需要
+
+字段、状态、金额、身份、权限等契约可能在入口层看似兼容，但在下游过滤、默认值、持久化或页面展示处发生偏移。关键契约必须从入口追到真实终点。
+
+## 输入
+
+- PRD 和技术方案
+- 真实 Git diff
+- 受影响模块的调用链、引用关系或静态分析结果
+- team-profile 中登记的跨仓、前后端或外部接口边界
+
+## 输出
+
+```yaml
+result: PASS | WARN | BLOCK
+contracts:
+  - name: "<contract>"
+    upstream_entry: "<file:line>"
+    downstream_terminals:
+      - "<file:line>"
+    predicates:
+      - "<file:line applies rule>"
+    verdict: pass | drift | block
+missing_traces:
+  - "<无法追到终点的契约>"
+```
+
+## 阻断规则
+
+- 涉及金额、身份、权限、订单、状态等关键字段但无法追到终点时阻断。
+- 两个入口声称兼容但下游过滤、默认值或错误语义不同步时阻断。
+- 追踪停止在第三方库或黑盒能力时，必须记录缺口并降级为 WARN。
+
+## Adapter 示例
+
+- **L0**: 规定关键契约不能只看 DTO。
+- **L1**: prompt 要求贴出入口到终点的调用链。
+- **L2**: slash command 生成契约追踪表。
+- **L3**: 静态分析 hook 暴露引用链。
+- **L4**: subagent 跨文件追踪终点并给出结论。
+
+## 反模式
+
+- 停在 DTO 或方法签名。
+- 相信“兼容”字样而不查两条路径。
+- 默认数据层过滤与入口层一致。
+- 用单测通过替代端到端契约追踪。

package/workflow/core/capabilities/data-change-safety-checker.md

@@ -0,0 +1,52 @@
+# Capability: data-change-safety-checker
+
+- **Tier**: recommended
+- **Stage**: `/03`, `/05`, `/07`
+- **Purpose**: 管理 DDL、DML、数据修复和迁移脚本的交付位置、预检查、后检查、幂等性和回滚口径。
+
+## 为什么需要
+
+数据变更一旦混在业务源码目录或缺少执行前后校验，容易在发布时丢失、重复执行或影响错误数据。工作流需要把数据变更当作独立交付资产管理，而不是临时 SQL 片段。
+
+## 输入
+
+- 需求的数据影响说明
+- 数据库 / 表 / 字段 / 索引 / 初始化数据变更清单
+- 目标项目定义的 release artifact 目录或数据库变更流程
+- 执行前查询、执行后校验和回滚策略
+
+## 输出
+
+```yaml
+result: PASS | WARN | BLOCK
+data_changes:
+  - type: DDL | DML | migration | repair
+    asset_path: "<交付脚本路径>"
+    target_scope: "<目标库表或数据范围>"
+    precheck: "<执行前检查>"
+    postcheck: "<执行后验证>"
+    idempotency: "<可重复执行风险>"
+    rollback: "<回滚口径>"
+```
+
+## 阻断规则
+
+- 数据脚本放在业务源码目录且 team-profile 未授权该位置时，阻断交付。
+- 缺少执行前范围确认、执行后验证或回滚说明时，阻断上线结论。
+- DML / 数据修复只依据估算行数时，必须补同条件 `COUNT` 或等价核查；否则降级为 WARN 或 BLOCK。
+- 只检查数据库列类型、不检查应用实体 / 映射类型时，不能关闭类型兼容风险。
+
+## Adapter 示例
+
+- **L0**: 在架构和审查模板中固定数据变更表。
+- **L1**: prompt 要求补齐 precheck、postcheck、rollback。
+- **L2**: slash command 扫描 diff 中的 SQL / migration 文件并生成清单。
+- **L3**: hook 阻止未登记的数据脚本进入完成状态。
+- **L4**: subagent 专门做数据变更安全审查。
+
+## 反模式
+
+- 把 SQL 临时放进业务仓根目录。
+- 没有目标范围就执行数据修复。
+- 只写“可回滚”，没有回滚 SQL 或业务口径。
+- 用构建通过替代数据兼容验证。

package/workflow/core/capabilities/definition-lint.md

@@ -0,0 +1,81 @@
+# Definition Lint
+
+## Purpose
+
+Gate contract freezing on an eight-dimension completeness check, and compensate for a solo developer's knowledge blind spots with a per-project-type "definition interview" question bank. A contract that has not passed this lint (or received explicit user waivers) must not be frozen, and implementation must not start on it.
+
+## Sources
+
+- `features/{feature}/00-完成合同.md` draft and its upstream stage documents
+- `workflow/constitution.md`, `workflow/standards/`, workspace-level `specs/`
+- `workflow/core/templates/completion-contract.md`
+
+## The Eight Dimensions
+
+| # | 维度 | 通过标准 |
+| --- | --- | --- |
+| 1 | 数据流确定性 | 写清数据来源、去向、唯一真相源；关键实体有状态机与不变量；无"数据大概存一下"式描述 |
+| 2 | 失败路径闭环 | 失败路径表覆盖弱网/超时重试与幂等、并发冲突、进程中断、配额耗尽、非法输入、依赖故障；不适用项写明理由 |
+| 3 | 质量预算 | 性能/资源/成本/依赖/安全至少各有一条硬数字或显式"无约束+理由"；无"性能要好"式描述 |
+| 4 | Oracle 可复现 | 每条目标 ≥1 条 Oracle 覆盖；每条 Oracle 有可复现验证方法；auto 优先；≥1 条 blocking；manual 带步骤与判定标准 |
+| 5 | 歧义消融 | 模糊词（快/流畅/稳定/好用/优雅/高性能/健壮/无缝/及时/大量）全部绑定数字或可观察行为；术语表覆盖有歧义风险的词；无未解决 `[待澄清]` |
+| 6 | 体验质量线 | 有 UI 的需求：三态（空/错/载）、感知性能、可访问性最低线有可检查表述，且保留 ≥1 条 manual 体验 Oracle（S 档或纯后端可豁免） |
+| 7 | 北极星挂钩 | 存在 `business/{product}/` 基线时，写明预期移动的漏斗指标；无基线时记录缺口而非编造 |
+| 8 | 影响边界 | 允许改/禁止碰清单明确；引用 constitution 与 standards 适用条款；受影响契约对照 `specs/` 列出 |
+
+清单可扩展：项目发现新维度时，在合同 Lint 表追加行并在复盘时提议回流本能力文件。
+
+## Definition Interview（按项目类型的拷问清单）
+
+逐题回答"已定义 / 不适用+理由 / 待澄清"，不允许跳过。目的：开发者不懂重试、幂等、内存模型没关系——问题清单逼着把它们变成合同条款或显式假设。
+
+**通用（所有类型必问）**
+- 最大输入是什么（大小/数量/长度）？超过时发生什么？
+- 操作可以被安全地重复执行吗（幂等）？重复会造成什么？
+- 进程/页面在操作中途被杀，重启后状态是什么？
+- 哪些数据丢了无法恢复？备份/导出口径是什么？
+- 单用户/单请求的成本上限是多少？被滥用时怎么止损？
+
+**Web 应用 / API 服务**
+- 弱网与超时：客户端重试吗？服务端如何去重？
+- 并发写同一资源：最后写赢、锁、还是合并？用户看到什么？
+- 鉴权失效瞬间正在进行的操作如何收场？
+- P95 延迟与首屏目标是多少？在什么设备/网络下测？
+
+**CLI 工具**
+- 非交互环境（CI、管道）下行为如何？退出码约定？
+- 中断（Ctrl+C）后留下什么状态？能续跑吗？
+- 破坏性操作有没有 dry-run 和确认？
+
+**浏览器扩展**
+- 页面结构变化（选择器失效）时的降级行为？
+- 权限最小集是什么？商店审核红线检查过吗？
+- 存储配额满、跨设备同步冲突怎么办？
+
+**移动应用**
+- 离线/弱网下哪些功能可用？数据何时同步、冲突怎么解？
+- 被系统杀进程后恢复到哪一步？推送权限被拒的替代路径？
+- 冷启动时间与包体上限是多少？
+
+**MCP / Agent 服务**
+- 工具调用是否幂等？部分成功如何表达？
+- 上游模型/服务超时与限流的重试和退避策略？
+- 长任务的进度、取消与状态查询口径？
+
+**静态站点 / 内容**
+- 构建失败或数据源缺失时发布什么？
+- SEO 元数据与结构化数据的验收标准？
+
+## Rules
+
+- Lint runs before freezing; every dimension gets an explicit conclusion in the contract's Lint table: 通过 / 未过+缺口 / 豁免+用户确认。
+- A waiver requires the user's explicit confirmation and a recorded risk note; the agent must not self-waive.
+- Interview answers that surface new constraints must be written back into the contract sections, not left in chat.
+- S-tier contracts lint only the ★ sections plus dimension 4 and 5 (oracles and ambiguity are never skippable).
+
+## Failure Modes
+
+- Rubber-stamping: marking dimensions 通过 without quoting the contract text that satisfies them.
+- Freezing with unresolved `[待澄清]` items "to save time".
+- Writing quality budgets as aspirations ("尽量快") instead of numbers.
+- Treating the interview as a form to fill instead of constraints to encode into oracles.

package/workflow/core/capabilities/deployment-readiness-checker.md

@@ -0,0 +1,57 @@
+# Capability: deployment-readiness-checker
+
+- **Tier**: recommended
+- **Stage**: `/07`, `/08`, `/09`
+- **Purpose**: 区分构建成功、启动成功、部署生效和路由可达，避免把任一单点成功误写成“已上线可用”。
+
+## 为什么需要
+
+常见误判是：构建通过就认为部署成功，或测试环境无报错就认为新代码已经生效。部署有效性必须拆成至少四层证据：构建产物、进程 / 实例启动、目标环境加载到新版本、代表性入口可达。
+
+## 输入
+
+- `workflow/team-profile.yaml#repos[*]`
+- 发布或测试目标环境说明
+- 构建、启动、部署、路由或健康检查命令
+- `/07-测试执行`、`/08-发布准备` 或 `/09-发布执行` 的执行证据
+
+## 输出
+
+```yaml
+result: PASS | WARN | BLOCK
+checks:
+  - name: build_artifact
+    status: pass | fail | not-run
+    evidence: "<命令、日志或产物路径>"
+  - name: instance_started
+    status: pass | fail | not-run
+    evidence: "<启动日志、健康检查或进程证据>"
+  - name: deployed_version_effective
+    status: pass | fail | not-run
+    evidence: "<版本、commit、包名或页面资源证据>"
+  - name: representative_route_reachable
+    status: pass | fail | not-run
+    evidence: "<API、页面、静态资源或探针结果>"
+blocked_reason: "..."
+```
+
+## 阻断规则
+
+- 新接口、新页面或新任务没有任何可达性证据时，阻断上线结论。
+- 构建成功但启动失败、实例未替换、路由未命中或版本无法确认时，不得写“部署已生效”。
+- 只能做人工验证时，必须记录执行人、步骤、时间和观察结果；否则降级为 WARN。
+
+## Adapter 示例
+
+- **L0**: 在上线检查清单中固定四层证据。
+- **L1**: prompt 要求用户粘贴构建、启动、版本和可达性结果。
+- **L2**: slash command 根据 team-profile 生成环境检查表。
+- **L3**: hook 阻止缺少可达性证据的上线状态变更。
+- **L4**: subagent 专门整理部署证据并给出 Go / No-Go。
+
+## 反模式
+
+- 把 `build success` 写成“部署成功”。
+- 只看旧接口可达，不检查新入口。
+- 404 时只猜测代码问题，不区分未部署、路由未配置、上下文路径错误和权限拦截。
+- 没有版本证据就声称目标环境已加载新代码。

package/workflow/core/capabilities/impact-scope-analyzer.md

@@ -0,0 +1,50 @@
+# Capability: impact-scope-analyzer
+
+- **Tier**: recommended
+- **Stage**: `/03`
+- **Purpose**: 扫描需求影响面，覆盖仓库、API、UI、数据、配置、任务、消息、测试和发布资产。
+
+## 为什么需要
+
+需求遗漏通常不是单点代码问题，而是影响面没画全。架构阶段必须把调用链、仓库边界、数据边界和验证边界列清楚，后续实现和审查才有依据。
+
+## 输入
+
+- PRD、需求讨论和技术方案
+- 本地代码、文档和 team-profile 中登记的项目资料
+- 用户补充的影响端、影响仓库或接口说明
+
+## 输出
+
+```yaml
+result: PASS | WARN
+scope:
+  repos: ["..."]
+  apis: ["..."]
+  ui_surfaces: ["..."]
+  data_changes: ["..."]
+  config_changes: ["..."]
+  jobs_or_messages: ["..."]
+  tests: ["..."]
+unknowns:
+  - "<需确认的影响面>"
+```
+
+## 阻断规则
+
+本能力通常不直接阻断，但高影响未知项必须在文档中显式记录。若未知项涉及数据写入、鉴权、安全、发布或生产配置，应交给对应高风险能力处理。
+
+## Adapter 示例
+
+- **L0**: 在 `/03` 中固定影响面矩阵。
+- **L1**: prompt 按层级提问。
+- **L2**: slash command 结合代码搜索生成草稿。
+- **L3**: hook 检查 04 前是否存在影响面矩阵。
+- **L4**: subagent 跨仓补全影响面。
+
+## 反模式
+
+- 只写“改后端”或“改前端”，没有仓库和文件级边界。
+- 架构阶段记录一次后，后续 diff 变化不回看。
+- 忽略配置、数据脚本、定时任务和发布资产。
+- 未知项不写入文档。

package/workflow/core/capabilities/knowledge-capture-maintainer.md

@@ -0,0 +1,32 @@
+# Knowledge Capture Maintainer
+
+## Purpose
+
+Keep durable knowledge in a maintained Markdown layer instead of scattering high-value lessons across chats and one-off notes.
+
+## Sources
+
+- `features/{feature}/10-复盘总结.md`
+- Project README / CHANGELOG / release notes when intended to be public.
+- `llm-wiki-pilot/wiki/` or another user-designated Markdown wiki.
+- Obsidian Vault notes when the user explicitly asks to use that vault.
+
+## Rules
+
+- Raw source material remains the source of truth; wiki pages are summaries and decision records.
+- Update index and log files together when the target wiki has that convention.
+- Do not ingest secrets, personal tokens, private URLs, payment details, ticket IDs, QR codes, receipt identifiers, or private chat text.
+- Preserve provenance by linking or naming the local source file that supports each reusable lesson.
+- Keep project docs and workflow docs under `features/<feature>/` unless they are intentionally public code-facing docs.
+
+## Suggested Outputs
+
+- A concise "Reusable Rules" section in the retrospective.
+- A wiki page update for stable lessons that will be useful across projects.
+- A follow-up issue or TODO for unstable lessons that need more evidence.
+
+## Failure Modes
+
+- Treating a wiki summary as stronger than the source code, tests, or release evidence.
+- Importing raw private content instead of extracting task-relevant lessons.
+- Updating a wiki page without updating its index or maintenance log.

package/workflow/core/capabilities/market-evidence-grader.md

@@ -0,0 +1,33 @@
+# Market Evidence Grader
+
+## Purpose
+
+Keep market, competitor, and customer conclusions anchored to graded evidence instead of fabricated or unsourced claims, so solo developers do not build positioning, pricing, or channel plans on invented data.
+
+## Sources
+
+- `business/{product}/B1-业务定位.md` through `B9-策略复盘.md` drafts
+- User interviews, support threads, and usage analytics owned by the user
+- Public competitor pages, pricing pages, changelogs, and community discussions
+- Public reports and search or trend data
+
+## Rules
+
+- Grade every market claim as first-hand (own interviews or data), second-hand (public sources), or inference; unlabeled claims are treated as inference.
+- Every second-hand claim carries a source name and collection date; every first-hand claim carries sample size and time range.
+- Never fabricate market size, user quotes, competitor prices, reviews, or channel benchmarks; unknown stays unknown and goes to the evidence-gap list.
+- Order-of-magnitude market estimates are allowed only with the estimation method and inputs written out.
+- Downgrade or re-verify conclusions when evidence is stale; check capture dates before reusing claims across stages.
+- PMF, ICP, pricing, and channel decisions must cite the evidence rows they depend on.
+
+## Suggested Outputs
+
+- An evidence table (claim, grade, source, date, confidence) inside the stage document.
+- An explicit evidence-gap and unvalidated-assumption list feeding `/B3-PMF与客户画像` and `/B9-策略复盘`.
+
+## Failure Modes
+
+- Writing "the market is huge" style conclusions with no source or method.
+- Treating one enthusiastic user quote as PMF evidence.
+- Copying competitor pricing without a capture date, then reusing it after it changed.
+- Backfilling numbers to justify a channel or budget decision that was already made.

package/workflow/core/capabilities/memory-curator.md

@@ -0,0 +1,48 @@
+# Capability: memory-curator
+
+- **Tier**: optional
+- **Stage**: `/10`
+- **Purpose**: 从复盘中提取可复用经验，脱敏后沉淀为结构化记忆，避免经验只留在单个项目里。
+
+## 为什么需要
+
+复盘如果只写事件经过，很难复用。可复用记忆应抽象为：现象、根因、防护规则、触发条件和适用边界，并移除公司、客户、仓库、URL、日志、SQL 等私有信息。
+
+## 输入
+
+- `10-复盘总结.md`
+- 当前个人项目的记忆索引或知识库
+- 脱敏词表和对外分发边界
+
+## 输出
+
+```yaml
+result: PASS | WARN
+memories:
+  - phenomenon: "<现象>"
+    root_cause: "<根因>"
+    prevention: "<预防规则>"
+    trigger: "<何时适用>"
+    redaction: "<已脱敏内容>"
+questions:
+  - "<需要人工确认是否固化为规则的问题>"
+```
+
+## 阻断规则
+
+本能力不直接阻断交付。任何记忆写入前都必须完成脱敏检查；是否进入个人规则、项目 wiki 或公开文档由用户确认。
+
+## Adapter 示例
+
+- **L0**: 复盘模板固定“可复用经验”章节。
+- **L1**: prompt 输出结构化记忆候选。
+- **L2**: slash command 写入待审记忆文件。
+- **L3**: hook 扫描私有词。
+- **L4**: subagent 专门做复盘抽象和脱敏。
+
+## 反模式
+
+- 直接复制事故原文。
+- 记录真实客户、仓库、URL、日志或 SQL。
+- 只写长段感想，没有规则候选。
+- 把一次性特例升级成通用硬规则。

package/workflow/core/capabilities/personal-git-operator.md

@@ -0,0 +1,41 @@
+# Personal Git Operator
+
+## Purpose
+
+Allow agents to handle routine local Git mechanics for personal projects without importing team-scale manual-only constraints.
+
+## Applies When
+
+- The target repository is owned and used by the personal developer.
+- The task scope is already recorded in the current workflow stage.
+- The working tree state has been inspected.
+- The operation is local: branch naming/creation, commit, tag, local merge, or worktree creation.
+
+## Agent-Allowed Local Actions
+
+- Create a local branch from `prod`, usually `feature/<short-name>`, `fix/<short-name>`, or `chore/<short-name>`.
+- Create an isolated local worktree for same-repo parallel implementation.
+- Stage and commit scoped changes after review and verification.
+- Create local annotated tags such as `vX.Y.Z` after `/08-发布准备` records version evidence.
+- Merge a completed development branch into local `main`, and promote local `main` into local `prod`, when tests and release readiness are recorded.
+
+## Actions Requiring Explicit User Authorization
+
+- `git fetch`, `git pull`, `git push`, `git remote add/set-url`, remote branch creation/deletion, remote tag push, GitHub release creation, npm publish, app store submission, deployment, database write, and production config write.
+- Rewriting history, deleting branches, force pushing, or deleting tags.
+- Any operation touching a repo that is not clearly personal.
+
+## Checks
+
+1. Inspect `git status --short --branch`.
+2. Confirm the current branch and target branch match `workflow/team-profile.yaml#branch_model`.
+3. Confirm no unrelated user changes would be staged or overwritten.
+4. Run relevant tests/builds before commit, tag, local merge, or release preparation.
+5. Record the exact branch/tag/commit in `features/{feature}/`.
+
+## Failure Modes
+
+- Treating "personal project" as permission to push or deploy without authorization.
+- Staging unrelated user changes because the working tree was not inspected.
+- Creating tags before version, artifact, and release notes are aligned.
+- Using a `test` branch when `main` is already the personal integration branch.

package/workflow/core/capabilities/personal-release-checklist.md

@@ -0,0 +1,49 @@
+# Personal Release Checklist
+
+## Purpose
+
+Capture the independent-developer release discipline migrated from the local gstack guide: local integration, version alignment, tags, artifacts, channel-specific checks, documentation, and rollback.
+
+## Required Evidence
+
+- Release scope and excluded changes.
+- Clean or intentionally staged working tree.
+- Release candidate commit.
+- Test/build/lint/browser or platform-specific verification.
+- Version number and tag plan.
+- Artifact path, package path, or deployment target.
+- Rollback point and rollback command.
+
+## Branch And Tag Model
+
+- `prod`: production or last-published branch.
+- `main`: integration/testing branch.
+- Development branch: created from `prod`, usually `feature/<short-name>` or `fix/<short-name>`.
+- Tag: annotated `vX.Y.Z`, aligned with package, app, extension, or store version.
+
+## Channel Checks
+
+### Web / SaaS
+
+- Build and smoke test the production bundle.
+- Confirm environment variables and secrets are not committed.
+- Record deployment provider, preview URL, production URL, and rollback method.
+
+### Browser Extension
+
+- Bump `manifest.json` version.
+- Validate permissions and host permissions.
+- Ensure 16 / 48 / 128 icons exist.
+- Package a zip whose root contains `manifest.json`.
+- Exclude `.git`, `node_modules`, tests, docs, zip files, `.DS_Store`, and private notes.
+- Prepare store listing, screenshots, privacy statement, and "no remote code" answer when true.
+
+### CLI / Desktop / Mobile
+
+- Align binary/app version, release notes, and tag.
+- Record packaging command and artifact checksum when practical.
+- Record notarization, signing, app store, or platform-specific pending review state.
+
+## Authorization Boundary
+
+Agents may prepare local artifacts and local tags for personal projects. Remote push, release creation, store submission, deployment, and production config writes require explicit user authorization in the current task.

package/workflow/core/capabilities/prd-code-diff-checker.md

@@ -0,0 +1,53 @@
+# Capability: prd-code-diff-checker
+
+- **Tier**: essential
+- **Stage**: `/04`, `/04A`, `/04B`, `/05`
+- **Purpose**: 对比 PRD、技术方案和真实 diff，确保“文档说要做的”和“代码实际改的”一致。
+
+## 为什么需要
+
+只看 diff 容易漏掉产品目标，只看 PRD 又容易忽略实际代码越界。实现结束和审查阶段必须双向核对：需求项是否都有代码落点，代码改动是否都有需求或技术依据。
+
+## 输入
+
+- `02-产品文档.md`
+- `03-技术架构.md`
+- `04/04A/04B` 实现记录
+- 真实 Git diff 或用户提供的变更清单
+- 测试和验证结果
+
+## 输出
+
+```yaml
+result: PASS | WARN | BLOCK
+requirements:
+  - id: "<PRD item>"
+    expected: "<预期行为>"
+    implementation: "<file:line 或 diff 摘要>"
+    verdict: covered | partial | missing
+extra_diffs:
+  - file: "<file>"
+    reason: "<为何不在 PRD 范围内>"
+blocked_reason: "..."
+```
+
+## 阻断规则
+
+- P0/P1 需求项没有实现落点且无明确延期说明时阻断。
+- 真实 diff 包含 PRD 和技术方案均未覆盖的业务行为变更时阻断。
+- 测试只覆盖新增代码但不覆盖需求验收口径时降级为 WARN 或 BLOCK。
+
+## Adapter 示例
+
+- **L0**: 审查模板固定 PRD-diff 对照表。
+- **L1**: prompt 要求逐项列出需求、文件和验证。
+- **L2**: slash command 生成对照表草稿。
+- **L3**: hook 检查 05 文档是否记录 diff 覆盖结果。
+- **L4**: subagent 独立做 PRD 和 diff 的双向比对。
+
+## 反模式
+
+- 只审 diff，不回看 PRD。
+- 只复述 PRD，不读取真实改动。
+- 把“代码能跑”当成“需求已覆盖”。
+- 对额外改动不解释来源。

package/workflow/core/capabilities/protocol-state-machine-checker.md

@@ -0,0 +1,57 @@
+# Capability: protocol-state-machine-checker
+
+- **Tier**: recommended
+- **Stage**: `/03`, `/05`, `/07`
+- **Purpose**: 对第三方接口、异步回调、支付 / 账务 / 审批等多步协议建立状态机，明确前置条件、终态语义、幂等和失败处理。
+
+## 为什么需要
+
+多步协议最容易出现“HTTP 成功但业务未完成”“本地字段被当成权威事实”“失败关键字先于幂等成功判断”等问题。状态机能把每一步的输入、输出、可重试性和终态定义清楚。
+
+## 输入
+
+- 协议文档、样例报文或真实联调样例
+- 当前实现 diff 和状态字段
+- 本地记录与外部权威记录的关系说明
+- 可执行的单测、模拟器或人工验证证据
+
+## 输出
+
+```yaml
+result: PASS | WARN | BLOCK
+states:
+  - name: "<状态>"
+    meaning: "<业务含义>"
+    terminal: true | false
+    retryable: true | false
+transitions:
+  - from: "<状态>"
+    event: "<事件>"
+    to: "<状态>"
+    idempotency: "<幂等规则>"
+    authority: local | external | mixed
+blocking_gaps:
+  - "<缺少样例、终态或幂等说明>"
+```
+
+## 阻断规则
+
+- 没有真实样例或明确协议口径时，不得把关键状态逻辑标记为已验收；只能写待联调或待补证据。
+- HTTP / RPC 成功不能直接等同于业务终态成功。
+- 外部系统是权威账本或权威状态源时，本地错误原因、备注或缓存只能作为展示线索，不能作为修复依据。
+- 幂等成功、重复通知、已处理完成等语义必须先于泛化失败关键字判断。
+
+## Adapter 示例
+
+- **L0**: 在 `/03` 固定状态机表格。
+- **L1**: prompt 要求补齐状态、事件、终态、幂等、权威来源。
+- **L2**: slash command 从协议说明和 diff 中生成初始状态机。
+- **L3**: hook 检查关键状态字段是否有测试或人工证据。
+- **L4**: subagent 专门审查协议状态机和异常路径。
+
+## 反模式
+
+- 只按字段名猜测业务语义。
+- 把本地失败原因当成外部权威结果。
+- 没有真实样例就写“联调通过”。
+- 只测正常路径，不测重复通知、超时、逆序和部分成功。