TDD 测试先行

<!-- @include templates/prompts/iron-law.md（已内联于下方，无需另读） --> ⛔ IRON LAW · 不可违反的硬门禁

以下规则为不可协商的执行约束：

1. 文件必须落盘：所有带编号（功能ID / 缺陷ID）的文档，必须作为实际文件写入磁盘，不可仅在对话中输出。
2. 阶段必须落章：每个阶段完成后必须在状态机 docs/.pdlc-state/<feature-id>.json 追加 history，不可跳过。
3. 测试必须存在：进入 /pdlc-implement 前，对应测试必须存在且处于红灯状态。违反则中止。
4. 自检必须执行：段二自检为强制步骤，不得以"已经很好了"为由跳过。
5. 防循环：段三修复为单次，不递归。无法自动修复的问题记录到报告，继续往下走。
6. 状态必推进：成功执行某 phase 后 current_stage 必须变更。收尾时若发现 current_stage 未推进，视为失败并报错，不得静默返回（防止外层循环拿滞后的状态空转烧额度）。唯一例外：命中人工点主动 block 时，current_stage 保持不变但必须写 last_phase_result.ok=false + blocked_reason。

违反任一条 = 立即中止当前命令，输出违规详情，等待人工介入。 <!-- @include-end templates/prompts/iron-law.md --> <!-- @include templates/prompts/noninteractive.md（已内联于下方，无需另读） -->

非交互模式（--autonomous）

若本命令的参数含 --autonomous，本命令进入无人值守模式，按以下规则处理原本需要人应答的交互点。参数是唯一真源：不带 --autonomous 即为交互模式，一切照旧正常询问用户；绝不回读状态机 run_mode 兜底（「掉出 autonomous」是安全的失败方向）。

1. 流程性确认（如「测试已绿是否继续」「是否覆盖已有文件」）→ 不询问，按预设默认前进，并把决策追加到状态机 history[].auto_decisions[]

（写状态机的命令：推进时给状态推进脚本传 --decision "<确认点描述>=<所选默认>"，可重复；脚本写成下面的样子）：

   { "point": "<确认点描述>", "chose": "<所选默认>", "at": "<ISO 8601>" }

1. 真需人判断（PRD 关键取舍、评审「需人工确认」项、真实循环依赖、测试与设计 / PRD 矛盾等无法安全默认的点）→ 不猜。

改测试、改检查命令让它变绿，永远不是「流程性默认」，不能记成 --decision：

• current_stage 保持不变（不推进）
• 写 last_phase_result.ok = false 且 blocked_reason = "<原因>"（写状态机的命令：给状态推进脚本传 --blocked "<原因>"）
• 末行输出哨兵：<<<PDLC blocked reason="<原因>">>>
• 立即结束命令，交还人类
• 守卫拦截也走这一条：前置守卫（缺设计文档、缺测试、测试没红等）在 --autonomous 下拦住本命令时，

不能只输出 ⛔ 就停——同样写 ok=false + blocked_reason（写明哪条守卫、缺什么）并输出哨兵。 否则状态机里仍是上一阶段的 ok=true，循环驱动只看到 current_stage 没动，会把「被拦」误报成「卡住」，真实原因丢失。

1. 破坏性操作（发布 / 部署 / 打 tag / 触发 CI / DROP / force-push 等不可逆·外发操作）→ --autonomous 无效，仍必须人工显式确认。
2. 顺手的 sidecar 产物（如缺失时创建 CHANGELOG.md、补全文档 PDLC-TRACE 的创建时间等本阶段职责内、可安全默认的辅助改动）→ 视为流程性默认，直接做并记入 `auto_decisions[]`；这类改动不新增外部副作用，不属破坏性操作。

进入 autonomous 模式时，在状态机顶层写 run_mode: "autonomous" 仅供留痕（复盘区分人工 vs 循环产出）。

<!-- @include-end templates/prompts/noninteractive.md -->

根据设计文档，先编写测试用例，再实现代码。严格遵循 TDD 工作流。

<!-- @include templates/prompts/artifact-lookup.md（已内联于下方，无需另读） -->

定位上游产物：先查状态机，再按关键词搜

守卫要找的上游文档（PRD、设计文档、评审记录等），按下面的顺序定位，命中即停：

1. 输入是功能ID / 缺陷ID（F… / B…）且 docs/.pdlc-state/<ID>.json 存在 → 读它 history[].produced 里记下的路径，取所需类型的文档。这是上游阶段亲手记的，最可靠
2. 没有状态机、或 `produced` 里没有所需文档 → 在对应目录下搜：文件名含该 ID 或功能名关键词，或文件顶部 PDLC 追溯头的 功能ID 等于该 ID
3. 命中多份 → 不要随手挑一份：交互模式下列出来请人选；--autonomous 下优先取文件名含该 ID 的，仍不止一份则按「真需人判断」阻塞（写 blocked_reason，列出候选）

找到后从文件名或追溯头取功能ID，后续产出一律沿用它，不另分配新 ID。 <!-- @include-end templates/prompts/artifact-lookup.md -->

PDLC 前置检查（必须执行，不可跳过）

1. 从用户输入中提取功能ID或功能名称关键词
2. 按上面的顺序找本功能的设计文档（docs/02_design/ 下 api/、architecture/、database/、ui-ux/ 任一）与 PRD（docs/01_requirements/prd/）
3. PRD 或设计文档任一找到即可继续：

• 有设计文档 → 以设计为准写测试，PRD 用来核对验收标准
• 只有 PRD（设计按需跳过的小功能、纯前端 / 配置类改动）→ 直接按 PRD 验收标准写测试，并在测试计划里注明「无设计文档，依据 PRD」

1. 两者都没有 → 输出以下信息后立即停止，不继续执行：

   ⛔ PDLC 守卫：未找到与「<功能名>」相关的 PRD 或设计文档。
   测试用例必须有需求依据。请先运行：
   👉 /pdlc-prd <需求描述>（或 /pdlc-design <设计目标>）

1. 找到 → 提取功能ID（如 F20260326-090000），读取文档内容，继续执行

工作流程

1. 阅读设计文档: 阅读找到的设计文档（只有 PRD 时读 PRD），全面理解接口/架构/数据模型与验收标准
2. 阅读编码规范: 阅读 docs/00_standards/coding/ 目录了解编码规范（未命中 → 提示 consider /pdlc-standard add coding/<topic>）
3. 编写测试计划: 在 docs/04_testing/unit-tests/ 下创建测试计划文档

• 使用模板: 本 skill 目录下的 assets/test-plan-template.md
• 文件名格式: <功能ID>-<功能名>-test-plan.md（如 F20260326-090000-user-auth-test-plan.md）
• 文档顶部必须包含 PDLC 追溯头：

     <!-- PDLC-TRACE -->
     <!-- 功能ID: F20260326-090000 -->
     <!-- 功能名称: user-auth -->
     <!-- 阶段: 测试 -->
     <!-- 前置文档: docs/02_design/api/F20260326-090000-user-auth-api.md -->

1. 编写测试代码: 写到项目既有的测试布局里，按下面的规则定位；

不要为迎合某种预设结构新造一套平行的测试目录。

<!-- @include templates/prompts/test-location.md（已内联于下方，无需另读） -->

测试代码在哪（布局无关的定位规则）

⚠️ 这条规则的要害：红灯守卫必须区分「项目没有测试」和「测试不在我预期的位置」。 前者才该拦；后者拦了就是误伤——真实项目的测试布局千差万别（单体 backend/tests/、 根级 tests/、Go 同包 *_test.go、Node 与源码同目录的 *.test.tsx…）， 按一份写死的路径清单去找、找不到就拦，会让 pdlc 在大量正常项目上直接卡死。

核心原则：优先问 runner，其次翻文件。 测试框架自己最清楚有哪些测试—— 让它报比我们去猜文件位置准得多，也和 pdlc「信退出码、不信目视检查」的哲学一致。 尤其测试写在源文件里的语言（见下），翻文件根本找不到。

按下列顺序定位，命中即停：

1. 项目自己的声明 + 向 runner 查询（最高优先级）

若存在 docs/00_standards/test-commands.yml，它的 unit / e2e 命令就是权威—— 项目已经明确告诉你测试怎么跑。用它去问 runner，而不是去翻目录：

查询结果为空 = 该功能没有测试（这是行为证据，比"我没找到文件"可靠得多）。

2. 测试写在源文件里的语言（必须靠内容匹配，文件名扫描无效）⭐

这类语言没有独立测试文件，只能按代码内标记搜：

⚠️ Rust 尤其要注意：单元测试几乎总在源文件的 #[cfg(test)] mod tests 里， tests/ 目录按 Cargo 约定只放集成测试。所以「tests/ 目录不存在」在 Rust 项目里 完全不能推出「没有单元测试」——照文件清单判红会稳定误伤所有 Rust 项目。

3. 常见布局约定（按项目实际技术栈挑，不要全试）

4. 文件名兜底扫描

前三步都没命中时，按文件名模式全仓搜（*test* / *spec*，排除 node_modules、 .venv、vendor、dist、build、target、.git），再按功能关键词筛。

5. 判定

• 任一步找到相关测试 → 通过，进入下一步（pdlc-implement 还需确认红灯）
• 四步走完确实找不到任何测试 → 这才是真红灯，按各命令的守卫规则中止
• 找到测试但与本功能无关 → 按「本功能无测试」处理（同样是真红灯），但报告里要说明

「项目有测试，只是没覆盖本功能」，别让用户以为项目裸奔

• 无法判定（如 runner 装不上、语言不认识）→ 不要默认放行，也不要假装找到了：

如实报「无法确认本功能是否有测试」并交还人类。「我判断不了」绝不等于「没问题」。

写测试时（pdlc-tdd）同样按本规则决定写到哪：跟随项目既有布局与惯例—— Rust 单测就写进源文件的 #[cfg(test)] mod tests，不要为了迎合某种预设结构 新造一套平行的测试目录。

<!-- @include-end templates/prompts/test-location.md -->

1. 测试计划自审与自动修复（编写完成后、运行前执行，不可跳过）：

• 重新阅读测试计划和测试代码，对照设计文档和 PRD 逐项检查以下质量门禁：

验收标准覆盖度：

• [ ] PRD 中每条验收标准是否至少有一个对应的测试用例
• [ ] 设计文档中每个接口是否至少有正常流程 + 异常流程的测试

场景完备性：

• [ ] 正常流程：核心业务路径是否全部覆盖
• [ ] 边界条件：空值/null、空字符串、最大值/最小值、零值、超长输入
• [ ] 异常场景：无权限、资源不存在（404）、重复操作（409）、参数校验失败（400）
• [ ] 并发场景：是否考虑了同时操作的冲突（如适用）
• [ ] 幂等性：重复提交同一请求是否有对应测试（如适用）

测试质量：

• [ ] 测试方法命名是否清晰描述场景（如 should_return_404_when_user_not_found）
• [ ] 每个测试是否只验证一个行为（单一断言原则）
• [ ] 测试数据是否有意义（非 test1、abc123 等无意义数据）

自动修复：

• 缺失的验收标准测试：自动补充对应的测试用例骨架
• 缺失的边界条件测试：自动添加空值、超长输入、类型错误等测试
• 缺失的异常场景测试：根据 API 错误码自动补充 401/403/404/409 等场景测试
• 命名不规范的测试方法：自动重命名为描述性命名
• 修复后在测试计划文档末尾追加审查记录：

     ## 自审记录
     - 审查时间：<ISO 8601>
     - 对照 PRD 验收标准：X 条，已覆盖：X 条
     - 对照 API 接口：X 个，已覆盖：X 个
     - 发现问题：X 项
     - 自动修复：X 项
     - 修复明细：
       - [已修复] <问题描述>

1. 确认测试失败: 运行 bash scripts/pdlc-checks.sh --red <项目根> 看红灯——它跑 docs/00_standards/test-commands.yml 的 unit。判定方向与 tests_pass 相反——这里失败才是要的结果。收尾时 scripts/pdlc-advance.sh 会再跑一次、据此写 red_verified 并决定推不推进，你不用手写 checks：

• 非 0，且失败来自断言（新写的测试在报错）→ 红灯成立，red_verified=true，推进到 tdd
• 非 0，但失败来自编译 / 导入错误（如被测函数还不存在）→ 也算红灯，但在报告里写明是哪一种；runner 能区分时优先让测试以断言失败的形式红
• `127` / `command not found` / 命令为空 → 命令跑不了，不是红灯：脚本写 red_verified=null 并拒绝推进；报告里写明测试命令跑不了（多为 test-commands.yml 过期）
• 意外全绿（新写的测试一条都没失败）→ 测试没有约束住待实现的行为（或代码早已存在）：脚本拒绝推进；报告里写明哪些测试意外通过，交给人判断
• 项目没有 `test-commands.yml` → 脚本无法客观验红灯（checks 写 {}）。按项目约定的测试命令手工跑：确认是红灯才推进；意外全绿就带 --blocked "<哪些测试意外通过>"
• 收尾推进时 --produced 列出本阶段写的测试文件：脚本记下它们的指纹，实现阶段改了它们会被拦下

⛔ 本阶段不写实现代码，也不重构。实现是 /pdlc-implement 的事：本阶段若让测试转绿， 下游 implement 会看到全绿而跳过整段实现，红灯验证也就没有意义了。

要求

<!-- @include templates/prompts/output-language.md（已内联于下方，无需另读） --> 🌐 Output language for generated artifacts

All generated artifacts (PRDs, design docs, code comments, review reports, test plans, deployment manuals, changelog entries, etc.) follow this policy:

1. Default — match the conversation language exactly:

• 用户用中文与 Claude 对话 → 产中文文档、中文代码注释、中文报告
• User talks to Claude in English → produce English artifacts
• User talks in another language → produce artifacts in that language
• Never silently default to a fixed language regardless of the user's input.

1. Explicit override always wins: when the user specifies a language for

an artifact (e.g. "write the PRD in English", "用英文写 API 设计文档", "output the deploy doc in Japanese"), use that language for that artifact, regardless of conversation language.

1. Mixed-language requirements: if the user wants some artifacts in one

language and others in a different language (common: Chinese PRD + English API docs for partners), honour each per-artifact instruction.

1. Uncertain: if you cannot reliably detect the conversation language,

ask once before producing the first artifact.

This policy applies to content (prose, comments, headings). It does not override technical conventions like English variable names, English git commit subjects, or English error codes when the project's conventions require them. <!-- @include-end templates/prompts/output-language.md -->

• 测试用例必须覆盖：正常流程、边界条件、异常场景
• 测试方法命名清晰描述测试场景
• 单元测试覆盖率：覆盖率达标线以项目配置为准：优先取 docs/00_standards/test-commands.yml 的 coverage 命令阈值参数（那才是强制点，退出码即判定），其次 quality-targets.yml；两者都没有时按 >= 80% 兜底。

目标功能: $ARGUMENTS

<!-- @include templates/prompts/check-commands.md（已内联于下方，无需另读） -->

跑 check 命令：退出码的三态语义

用脚本跑，不要手写 `checks`：

bash scripts/pdlc-checks.sh --only <本阶段要的项，如 unit,lint> <项目根>

脚本是本 skill 自带的 scripts/pdlc-checks.sh。它读 docs/00_standards/test-commands.yml（唯一真源），逐条真跑，按下表映射，stdout 只有一行 JSON—— 原样写进 last_phase_result.checks，不改键名、不改值、不补不删。每条命令的退出码与输出末尾回显在 stderr，报告里引用那几行即可。脚本退出码 2（没有 yml 等）= 没有可跑的 check → checks: {}。

为什么不手写：键名、布尔类型、三态这几件事是确定性的，交给模型写，真机上同一份项目轮与轮之间就换一种错法 （键名照抄 yml 的 unit、值写成 "4 passed, 1 failed"、127 写成 false）。 环境里没有 bash 时才按下表手工映射。

脚本按退出码分三态——不是两态。这是 IRON LAW「checks 只认客观事实」在执行层的落法：

⛔ 唯一的红线是不许写 `false`：那是会误导人的虚报——它说的是"检查失败了"， 于是有人去查代码，但真正的问题是配置过期，代码可能完全没毛病。

>

省略键与 `null` 等价，两种都可以：对消费方而言无法区分（jq '.checks.lint_clean' 在两种情况下都返回 null）。null 甚至更明确——省略是歧义的（"没看"还是"看了判不出"）， null 明说"看了，判不出"。别在这上面纠结，力气花在不写 `false` 上。

>

这与「没有检查命令可跑的阶段 → checks: {}」同源。

「跑不了」＝ test-commands.yml 过期信号（顺带检测，零额外成本）

命令跑不起来，几乎总意味着这份 yml 已经跟不上项目了——脚本改名、runner 换了、 工具从依赖里移除、子项目路径调整。真实项目里这类漂移是常态（例如某前端框架升级后 移除了内置 lint 子命令，而 yml 里那条命令还在）。

由于各阶段本来就在跑这些命令，这个信号是白捡的。检测到时：

1. 在本阶段的报告里单列一条：「`test-commands.yml` 疑似过期」，写明是哪一项、

观察到什么（退出码 / 报错原文）、以及为什么判定为"跑不了"而非"没通过"。

1. 提示补救：/pdlc-test-setup --refresh（重新探测并给出 diff）。
2. 不要自作主张改 yml——本阶段的职责是干活，不是改配置；只报告，不动手。

变更方向决定自动化程度（--refresh 时适用）

更新这份 yml 等于改变"通过"的定义，所以按方向区别对待：

⚠️ 这条方向规则是防「自动修复把闸门修没了」：lint 命令坏掉时，把它留空是最省事的 "修法"，结果闸门悄悄松了、报告还是绿的——比不更新更危险。 变严可以自动，变松必须由人签字。

<!-- @include-end templates/prompts/check-commands.md --> <!-- pdlc:meta 由 frontmatter 生成（adapters/sync_skills.py），勿手改 -->

本命令的状态机取值：阶段短名 tdd（写进 history[].stage 与 last_phase_result.stage）；下一跳 pdlc-implement（写进 next_step，交接时提示）。

<!-- pdlc:meta-end --> <!-- @include templates/prompts/state-update.md（已内联于下方，无需另读） -->

状态机更新（段四必须执行）

本命令完成主产出后，必须推进状态机文件 docs/.pdlc-state/<feature-id>.json。

用脚本推进，不要手写状态 JSON

bash scripts/pdlc-advance.sh <功能ID> --stage <本阶段短名> --next <下一跳命令名|null> \
  [--produced <产物路径，逗号分隔>] [--autonomous] [--decision "<确认点>=<所选默认>"]... \
  [--name <kebab-case>（状态文件还不存在时）] <项目根>

• 脚本是本 skill 自带的 scripts/pdlc-advance.sh。阶段短名与下一跳就是本命令正文里「本命令的状态机取值」那两个值；带了 --autonomous 就照传
• 检查由脚本自己跑：它按阶段调用同目录的 scripts/pdlc-checks.sh（tdd 验红灯；impl / fix / refactor 跑 unit、coverage、lint；

review 再加 e2e；e2e 只跑 e2e；文档类阶段不跑），据此判 ok、整段写入 history 与 last_phase_result， 写完调用 scripts/pdlc-state-lint.sh 体检。不要自己先写 checks，也不要挑检查项

• tdd 阶段的 --produced 必须列出写的测试文件：脚本记下它们的指纹，之后 impl / refactor / review 推进时比对
• 主动交还人类（命中人工点、评审有阻塞项、测试本身有矛盾等）→ 加 --blocked "<原因>"：脚本照跑检查、如实记录，但不推进，原因写进 blocked_reason
• /pdlc-ship 写 ship_done、/pdlc-deploy 写 deploy_done → 加 --done（只有这两个命令能用）

脚本的退出码决定怎么收尾：

退出码 3 且原因是「tdd 阶段写的测试被改动」：实现阶段不改测试。测试是否真的写错了（与设计 / PRD 矛盾），只有人能判断： - 交互模式：先把矛盾讲清楚、问人；人同意后再带 --tests-changed "<理由>" 重跑，理由记进 auto_decisions - --autonomous：没有人可问，不要改测试，带 --blocked "<矛盾在哪>" 收尾。自主模式下带 --tests-changed 脚本也不推进

>

项目开了 PDLC 护栏（docs/00_standards/pdlc-hooks.yml）时，用 Write / Edit 直接写状态文件会被拦下。

状态文件格式（读状态时参考；只有脚本跑不了时才照它手写）

{
  "feature_id": "<F/B ID>",
  "feature_name": "<kebab-case>",
  "created_at": "<首次创建时间 ISO 8601>",
  "current_stage": "<当前阶段名>",
  "run_mode": "interactive | autonomous",
  "history": [
    {
      "stage": "<阶段名>",
      "done_at": "<ISO 8601>",
      "produced": ["<相对路径 1>", "<相对路径 2>"],
      "self_audit": { "passed": <N>, "failed": <N>, "manual": <N> },
      "auto_decisions": [
        { "point": "<autonomous 下自动前进的确认点>", "chose": "<所选默认>", "at": "<ISO 8601>" }
      ]
    }
  ],
  "last_phase_result": {
    "stage": "<本次阶段名>",
    "ok": true,
    "advanced_to": "<推进到的下一阶段 | null>",
    "checks": {},
    "self_audit": { "failed": 0 },
    "blocked_reason": null,
    "run_mode": "interactive | autonomous",
    "at": "<ISO 8601>"
  },
  "relations": {
    "extends": [],
    "depends_on": [],
    "supersedes": [],
    "resolves": [],
    "conflicts_with": [],
    "relates_to": [],
    "_updated_at": "<ISO 8601 | 省略>"
  },
  "next_step": "<下一跳命令名，如 pdlc-design；若流程结束则为 null>"
}

⛔ 示例里的 "checks": {} 是「本阶段没有命令可跑」的样子，不是键名示范——键名与取值见下方 §1。

`relations` 块（RFC#6，Phase 1 可选，Phase 2 推荐）：6 个 key 对应 6 种关系类型，各为 ID 数组，存出边。其中 conflicts_with / relates_to 是对称类型，两端都要写；其余四种有向，只写在源 feature 上。拿不准时用 /pdlc-relate set 写入，它会按规则校验。旧状态文件无此块时视为全空，向后兼容。入边由 /pdlc-relate rebuild 派生到 _relations.json，不在此块手维护。

⛔ 写状态机的四条硬约束——读侧（/pdlc-status、/pdlc-retro、/pdlc-relate）会逐条体检， 违反的每一处都会出现在它们输出的最前面：

>

1. 实例里不写 `terminal_state`。skill frontmatter 的 terminal_state: 是「这个命令走完后应到达的终态名」， 不是状态字段。判终态只看 current_stage 是否以 _done 结尾。 2. `history[].stage` 写本命令的阶段短名（见本命令正文里「本命令的状态机取值」）——pdlc-implement 写 impl， 不写 implement / implementation；pdlc-prd 写 requirements，不写 prd。 3. 时间戳必须带时刻：created_at / done_at / at 一律写完整 ISO 8601（如 2026-07-28T10:40:00+08:00）。 只写日期，同一天内的阶段耗时就全部算成 0——读侧只能记「不可测」。 4. `next_step` 只写命令名或 `null`，不附说明文字（如「pdlc-ship（等评审通过）」）。 要说明原因，阻塞时写进 last_phase_result.blocked_reason。

⛔ `_done` 的含义是「已发布」，只由 `/pdlc-ship`（写 `ship_done`）与 `/pdlc-deploy`（写 `deploy_done`）写入。 其它命令的 current_stage 一律写本命令的阶段短名，走完整条链路的编排命令（/pdlc-feature）也一样—— 它收尾时 current_stage 是最后一个阶段的短名，next_step 是 pdlc-ship。

>

- 「评审通过、等待发布」就是 current_stage 为 review 且 next_step 为 pdlc-ship（/pdlc-e2e 在评审之前，它的下一跳是 pdlc-review）。 循环相关文档里说的 review_done 指的就是这个状态，不是要写进 current_stage 的值。 - 为什么：读侧判「已抵达终态」只看 current_stage 是否以 _done 结尾。评审通过就写 _done， /pdlc-ship 就分不清哪些功能已经发布过，发布说明会重复或漏收。 - 旧版本写入的 feature_done / fix_done / review_done 分不清是否已发布，/pdlc-ship 会列出来请人确认。

手写回退（仅脚本退出码 2 且无法修正时）

1. 文件不存在 → 创建文件，写入初始结构（history 为含当前阶段的数组）
2. 文件存在 → 读取 JSON，追加当前阶段到 history，更新 current_stage 和 next_step
3. 写回文件：用 jq 或等效工具保持格式化
4. 写完体检：运行 bash scripts/pdlc-state-lint.sh <项目根>，属于本功能状态文件的偏差当场改正。退出码 2（缺 jq 等）= 没体检，报告里写明「未体检」，不得当作通过。

⚠️ 若更新失败（文件损坏/权限问题），必须中止命令并在最终报告中报错。状态机不可跳过。

last_phase_result（机器可读阶段结果；脚本按下面的规则写，手写回退时照做）

顶层 last_phase_result 是循环判停的唯一真源，外层只需 jq '.last_phase_result.ok' 即可决定 继续 / 停止 / 交还人类。规则：

1. `checks` 只放真跑命令的退出码结果（scripts/pdlc-checks.sh 的 stdout 原样），键名只能是 tests_pass / coverage_pass /

lint_clean / e2e_pass（tdd 段 red_verified），值只能是布尔或 null（无法判定）。不照抄 test-commands.yml 的 unit / lint， 不写 "4 passed, 1 failed" 这类摘要。没有检查可跑的阶段（文档类阶段、项目无 test-commands.yml）→ checks: {}， 绝不因为「本阶段成功」就填 true——schema 示例里 checks 是空的，正是这个意思。

1. `self_audit` 单列：只放自检未通过数，仅供参考，不作循环判停依据。
2. `ok` 的定义：没有命中 blocked_reason，且 tdd 段 red_verified 为 true、其它阶段没有任何检查为 false（null 不拦）→ true；否则 false。
3. 命名空间：advanced_to = 下一阶段的短名，不是命令名、也不是本阶段的 `current_stage`。三者关系：stage=本阶段短名、current_stage=本阶段完成后的当前短名、advanced_to=下一阶段短名、next_step=下一跳命令名。

⛔ 短名不是「命令名去掉 `pdlc-` 前缀」——pdlc-implement 的短名是 `impl`，不是 implement。别推导，查下表：

<!-- stage-map:start -->

<!-- stage-map:end -->

next_step 为 null（终态或无后续）时 advanced_to 也是 null。

📌 本表是唯一真源，且是被断言钉住的：每行的短名必须等于该 skill 自己 frontmatter 里声明的 stage:，且任何 skill 的非 null next_step 都必须在表里有行——两个方向 都由 tests/frontmatter-check.sh 检查，所以表不会和实现各自漂移。

>

写错短名的后果与键名写错同类：消费方按契约名匹配，认不出就当没这个阶段。

1. 推进一致：ok=true 时本阶段必须真的推进了 current_stage（与第 6 条 IRON LAW 呼应）；到达终态或无后续时 advanced_to=null。ok=false（含 blocked）时 current_stage 不变、advanced_to=null、blocked_reason 写明原因。
2. `run_mode`：镜像本次调用是否带 --autonomous（带了写 autonomous，没带写 interactive）。

<!-- @include-end templates/prompts/state-update.md --> <!-- @include templates/prompts/handoff.md（已内联于下方，无需另读） -->

段四：交接（Handoff）

命令完成后必须输出以下格式的最终消息：

✅ <阶段名> 完成：<主要产出物路径>
📊 自检：<通过数>/<总数> 通过（若有未通过，附要点）
📦 状态快照：docs/.pdlc-state/<feature-id>.json
👉 下一步：/pdlc-<next_step>
   （如果有分叉）或 /pdlc-<alt>（条件：<选择依据>）

规则：

• 主流程命令（写状态机的命令；下一跳见正文里「本命令的状态机取值」）必须显式输出"下一步"，不可省略
• 工具型命令（Layer 3）可以没有 next_step，此时输出 👉 下一步：（本次流程结束，无后续）
• 分叉场景必须说明选择条件，例如"若需补充测试用例 → /pdlc-tdd；若测试已齐 → /pdlc-review"

<!-- @include-end templates/prompts/handoff.md -->