agent-project-sdlc 0.1.22 → 0.1.24

package/assets/skills/pjsdlc_manager/SKILL.md

@@ -16,6 +16,8 @@ Skill、执行出口 gate，并记录 blocker。
 
 与用户对话时，先读取 lifecycle 和 plan，再说明当前阶段、active_skill、当前任务、阻塞项和下一步。不要基于猜测切换阶段；如果用户要求的动作与当前阶段冲突，说明冲突、可选路径和推荐处理方式。
 
+如果当前是 `TESTING` 且 `.docs/07_test/TEST_REPORT.md` 的 Final decision 为 `BLOCKED`，先读取其中的 `Bugfix Route` 再切换阶段。`bugfix_replan` 使用 `python3 tools/transition.py --to ARCHITECTING` 回到技术方案阶段，修正 tech plan、接口契约、任务拆分或 handoff graph 后再进入开发；`bugfix_implementation_gap` 使用 `python3 tools/transition.py --to SPRINTING` 回到开发阶段，只创建或选择小的实现偏差修复 task。若报告显示需求、验收标准或产品边界变化，仍进入 `RFC_RECALIBRATION`。不要把测试 bug 直接当作无分类重试。
+
 自然语言是默认控制方式，约定宏指令是更完整、更细节的提示词别名。用户说“状态如何”“继续”“下一步”“完善产品方案”“设计技术方案”“开始开发”“开始循环：写任务，执行任务”“跑测试”“准备 review”“需求变了”等，不应要求用户记忆 `/xxx`；你应先读取 lifecycle 和 plan，再把意图映射到对应 workflow action。执行 `/status`、`/next`、`/advance`、`/rfc`、`/prd`、`/design`、`/dev`、`/devloop` 等宏指令时，输出要短而明确：当前事实是什么、将调用哪个 gate 或 Skill、成功后会进入哪里、失败时如何保持状态安全。
 
 自然语言和宏指令必须进入同一组 workflow action；区别在于 `/xxx` 入口携带更稳定的细节约束，简单自然语言入口更低成本，但需要你根据当前阶段、plan 和文档上下文补足细节。
@@ -50,12 +52,13 @@ Parallel Execution 是默认评估、按需启用：每个阶段 task 开始时
 17. 用户输入 `/dev`，或自然语言要求“开始开发”“做当前任务”“做下一个任务”“继续开发下一个任务”时，如果 `current_phase` 是 `SPRINTING`，创建或选择一个最小 `TASK-*` development task 并执行一个 task 闭环；如果 task 来自 `plan.draft.yaml.tasks[]`，promote 时必须同次删除源 draft；否则说明当前阶段冲突和推荐路径。
 18. 用户输入 `/devloop`，或自然语言要求“开始循环：写任务，执行任务”“把开发循环跑完”“连续开发”时，如果 `current_phase` 是 `SPRINTING`，连续运行 `/dev` 循环，直到 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可做任务或遇到 blocker；否则说明当前阶段冲突和推荐路径。
 19. 用户自然语言要求跑测试或验证时，运行当前 task 或当前阶段的对应 gate。
-20. 每个阶段 task 开始时先判断当前阶段和当前 task 是否适合并行；如果适合，生成或使用 `parallel_execution.trigger: "workflow_default"` 合同；如果用户明确要求并行、多 agent 或多 worktree，使用 `trigger: "user_requested"`。
-21. 默认使用 `runtime_managed` + `runtime.provider: "codex_native_subagents"`；native subagent 不可用时使用 `user_orchestrated` 并输出每个 worker 的可复制 prompt；高风险写入或用户要求强隔离时可选择 `codex_exec_worktree` fallback。
-22. 用户自然语言要求 review 时，如果 `current_phase` 是 `REVIEWING`，创建或选择一个最小 `TASK-*` review task，并设置 `phase: "REVIEWING"`；reviewer 只读源码，不直接改源码。
-23. 用户自然语言要求刷新文档总览时，运行 `make docs-overview`。
-24. `/plan` 和 `/goal` 是客户端模式入口，不由 Harness 自动开启；如果用户手动组合 `/plan` 或 `/goal` 与自然语言或宏指令，应按对应 workflow action 继续执行。
-25. 如果动作会改变阶段、创建或删除 task、提交、push 或发布，先用一句话说明即将执行的动作和验证方式，再继续。
+20. 用户自然语言要求修复测试发现的 bug 时，如果当前是 `TESTING`，先读取 `TEST_REPORT.md#Bugfix Route`；`bugfix_replan` 回 `ARCHITECTING`，`bugfix_implementation_gap` 回 `SPRINTING`，需求或验收变化走 RFC。
+21. 每个阶段 task 开始时先判断当前阶段和当前 task 是否适合并行；如果适合，生成或使用 `parallel_execution.trigger: "workflow_default"` 合同；如果用户明确要求并行、多 agent 或多 worktree，使用 `trigger: "user_requested"`。
+22. 默认使用 `runtime_managed` + `runtime.provider: "codex_native_subagents"`；native subagent 不可用时使用 `user_orchestrated` 并输出每个 worker 的可复制 prompt；高风险写入或用户要求强隔离时可选择 `codex_exec_worktree` fallback。
+23. 用户自然语言要求 review 时，如果 `current_phase` 是 `REVIEWING`，创建或选择一个最小 `TASK-*` review task，并设置 `phase: "REVIEWING"`；reviewer 只读源码，不直接改源码。
+24. 用户自然语言要求刷新文档总览时，运行 `make docs-overview`。
+25. `/plan` 和 `/goal` 是客户端模式入口，不由 Harness 自动开启；如果用户手动组合 `/plan` 或 `/goal` 与自然语言或宏指令，应按对应 workflow action 继续执行。
+26. 如果动作会改变阶段、创建或删除 task、提交、push 或发布，先用一句话说明即将执行的动作和验证方式，再继续。
 
 ## Plan Protocol
 

package/assets/skills/pjsdlc_reviewer/SKILL.md

@@ -17,7 +17,7 @@ Review 时先建立证据链：PRD 说什么、技术方案承诺什么、implem
 
 不要把个人偏好包装成 blocker。区分 blocking issue、follow-up improvement 和 open question。如果没有发现问题，要明确说明，同时列出剩余测试缺口或残余风险。
 
-Review 必须把“当前模块没有可运行入口/出口”视为阻断项，而不是普通测试缺口。凡 PRD、技术方案或 implementation doc 承诺 API、CLI、server route、service、agent、runtime、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，Review 都要读取技术方案的 `Development Deliverable Contract`、`Development Self-Test Contract` 或等价交付边界，并核对真实代码和实现文档是否提供可调用入口、初始化方式、输出/副作用边界和验证方式；如果 task 声明了 `evidence_level.required`、`target_runtime_environment` 或 `self_test_contract`，还必须核对实际证据等级、执行地点、目标运行环境、自测 scenario 结果、`module_key_test_path` 和 required gates 是否匹配。high-risk runtime/live/remote-operator 工作要先看 `plan.yaml#resume_capsule` 和 `.docs/09_runbooks/**` runbook，确认 canonical path、do-not-retry、evidence index 和 exploration appendix 已把恢复主线与失败探索分开；Review 不应从失败探索中重新选择主路径。implementation doc 还必须包含结构化 `Development Evidence`，说明 `Evidence Level`、`Target Runtime Environment`、`Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract`、`Testing Handoff Readiness`、`Known Missing Runtime Boundaries` 和 `Basic Self-test Evidence`，或带原因的 `Not applicable`；如果 task 有 `self_test_contract.status: "required"`，还必须包含已执行的 `Development Self-Test Report`，并记录 `Report Status`、从本地启动或调用入口开始到完成全部自测用例的 `Module Key Test Path`。该报告不是 debug log、operator log、runbook 或历史流水；看到这些混入 scenario evidence 时应判为 blocker。`Report Status` 必须是 `PASS` 且所有 scenario 都是 `PASS` 才能进入 TESTING。该路径应覆盖本 task / 本模块承诺的所有可运行入口、内部关键路径、关键边界、观察点和可观测完成证据；high-risk task 还必须包含短的 `Current Operator Path` 和分层 `Gate Breakdown`。如果 task 要求 `deployed_runtime` 或 `business_handoff_ready`，但证据只是在开发机 `localhost`、provider live smoke、fixture smoke、fake adapter 或文档描述，应判 `BLOCKED`。缺失时 gate decision 应为 `BLOCKED`，并要求回到 SPRINTING/RFC，而不是允许进入 TESTING 后补 runtime。Review 报告必须写出 `Runnable Entry`、`Observable Exit`、`Initialization`、`Config Contract`、`Testing Handoff Readiness` 的 `PASS`/`BLOCKED` checklist；任一 `BLOCKED` 不得进入 TESTING。Review 不创建 `.docs/07_test/**` 正式测试产物；如果发现现有测试事实源仍链接已被 RFC supersede 的旧路线证据，应将其列为进入 TESTING 前的 blocker，并要求 RFC 清理或更新索引。
+Review 必须把“当前模块没有可运行入口/出口”视为阻断项，而不是普通测试缺口。凡 PRD、技术方案或 implementation doc 承诺 API、CLI、server route、service、agent、runtime、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，Review 都要读取技术方案的 `Development Deliverable Contract`、`Development Self-Test Contract` 或等价交付边界，并核对真实代码和实现文档是否提供可调用入口、初始化方式、输出/副作用边界和验证方式；如果 task 声明了 `evidence_level.required`、`target_runtime_environment` 或 `self_test_contract`，还必须核对实际证据等级、执行地点、目标运行环境、自测 scenario 结果、`module_key_test_path`、`module_key_test_graph`（若声明）和 required gates 是否匹配。high-risk runtime/live/remote-operator 工作要先看 `plan.yaml#resume_capsule` 和 `.docs/09_runbooks/**` runbook，确认 canonical path、do-not-retry、hard constraints、evidence index 和 exploration appendix 已把恢复主线与失败探索分开；Review 不应从失败探索中重新选择主路径。凡会改变下一步动作的判断，如果只埋在 evidence、notes、exploration appendix 或长 implementation doc 中，而没有 promoted 到 `resume_capsule.do_not_retry`、runbook 顶部 `Hard Constraints` 或短 `Current Operator Path`，应判为 blocker。implementation doc 还必须包含结构化 `Development Evidence`，说明 `Evidence Level`、`Target Runtime Environment`、`Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract`、`Testing Handoff Readiness`、`Known Missing Runtime Boundaries` 和 `Basic Self-test Evidence`，或带原因的 `Not applicable`；如果 task 有 `self_test_contract.status: "required"`，还必须包含已执行的 `Development Self-Test Report`，并记录 `Report Status`、`Module Application Entry`、从本地启动或调用入口开始到完成全部自测用例的 `Module Key Test Path`、`Observable Exit`、`Current Blocker`、`Testing Handoff Readiness` 和 `Evidence Index Refs`。如果 contract 设置 `graph_required: true` 或包含 `module_key_test_graph`，报告必须含实际 `Module Key Test Graph`，覆盖 promised entry/exit、scenario、checkpoint 和 evidence refs。该报告不是 debug log、operator log、runbook、evidence dump 或历史流水；看到这些混入 scenario evidence 或 graph node 时应判为 blocker。`Report Status` 必须是 `PASS` 且所有 scenario 都是 `PASS` 才能进入 TESTING。该路径应覆盖本 task / 本模块承诺的所有可运行入口、内部关键路径、关键边界、观察点和可观测完成证据；high-risk task 还必须包含短的 `Current Operator Path` 和分层 `Gate Breakdown`。如果 task 要求 `deployed_runtime` 或 `business_handoff_ready`，但证据只是在开发机 `localhost`、provider live smoke、fixture smoke、fake adapter 或文档描述，应判 `BLOCKED`。缺失时 gate decision 应为 `BLOCKED`，并要求回到 SPRINTING/RFC，而不是允许进入 TESTING 后补 runtime。Review 报告必须写出 `Runnable Entry`、`Observable Exit`、`Initialization`、`Config Contract`、`Testing Handoff Readiness` 的 `PASS`/`BLOCKED` checklist；任一 `BLOCKED` 不得进入 TESTING。Review 不创建 `.docs/07_test/**` 正式测试产物；如果发现现有测试事实源仍链接已被 RFC supersede 的旧路线证据，应将其列为进入 TESTING 前的 blocker，并要求 RFC 清理或更新索引。
 
 Review 产出本身也是 workflow task。开始 review 前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "REVIEWING"`；当前轮只产出一个 review batch、一个风险主题 slice 或一次 PR review 结论。不要在一个任务里覆盖多个互不相关的 review 主题。
 
@@ -81,7 +81,7 @@ Review 阶段受 `plan.yaml` 管控：
 - [ ] 已评估架构和可维护性风险。
 - [ ] 已评估 runnable entry/exit、配置契约和 fixture/live 边界是否足以进入 TESTING。
 - [ ] 已评估 implementation doc 是否包含 Evidence Level、Target Runtime Environment、Runnable Entry、Observable Exit、Client / Server Initialization、Config Contract、Testing Handoff Readiness、Known Missing Runtime Boundaries 和 Basic Self-test Evidence。
-- [ ] 已评估 `self_test_contract` 对应的 Development Self-Test Report 是否 `Report Status: PASS`、执行全部 scenario 和 required gates，并记录可复用的 Module Key Test Path。
+- [ ] 已评估 `self_test_contract` 对应的 Development Self-Test Report 是否 `Report Status: PASS`、执行全部 scenario 和 required gates，并记录可复用的 Module Key Test Path；若 contract 要求 DAG，已核对 Module Key Test Graph。
 - [ ] 已核对证据等级和执行地点是否匹配 task / 技术方案承诺的目标运行环境。
 - [ ] 已判断 review slice 的范围和风险主题边界。
 - [ ] 已列出测试缺口。

package/assets/skills/pjsdlc_rfc_recalibrate/SKILL.md

@@ -19,7 +19,7 @@ description: Use during RFC_RECALIBRATION to process requirement changes with im
 
 影响面分析必须先于补丁。至少检查 docs/state/skills/policies/templates/tools/package assets/tests/migrations/generated artifacts 是否受影响；如果某一类不受影响，也要显式说明不受影响或不需要修改。对于 Harness package 相关变更，还要检查 `sync`、`upgrade`、source mappings、package assets 和用户项目迁移行为。
 
-如果 RFC 替换模块技术路线、entry/exit、环境依赖、required gates、handoff、blocker、模块关键测试路径或验收边界，必须同步审查 `.docs/07_test/**` 和开发自测链路。模块关键测试路径变化包括本 task / 本模块承诺的可运行入口、内部关键路径、关键边界、观察点或完成证据变化。被新方案 supersede 的测试环境、测试进度、测试用例、测试报告和 partial evidence 要从当前测试事实源删除或迁出，并从 `.docs/INDEX.md` 和 generated overview 中移除链接；历史证据只保留在 RFC provenance、git history、CI/release 系统或明确 archive 语义中，不能继续放在当前 `.docs/07_test/**` 冒充现行测试依据。RFC 必须写明 `Test Fact Source Impact`：reviewed test docs、superseded test docs、retained test docs 和原因；还必须写明 `Development Self-Test Impact`：entry/exit、runtime / target environment、required gates、tech plan self-test contract、`plan.yaml` / `plan.draft.yaml` task contract、implementation doc self-test report、Module Key Test Path、Review / Testing handoff 的影响。如果只是文案澄清且不影响测试事实源或自测链路，可分别写 `none`。
+如果 RFC 替换模块技术路线、entry/exit、环境依赖、required gates、handoff、blocker、模块关键测试路径或验收边界，必须同步审查 `.docs/07_test/**` 和开发自测链路。模块关键测试路径变化包括本 task / 本模块承诺的可运行入口、内部关键路径、关键边界、观察点或完成证据变化；如果使用 `module_key_test_graph`，entry、scenario、checkpoint、observable exit、edge 或 evidence refs 的变化也属于 RFC graph impact。被新方案 supersede 的测试环境、测试进度、测试用例、测试报告和 partial evidence 要从当前测试事实源删除或迁出，并从 `.docs/INDEX.md` 和 generated overview 中移除链接；历史证据只保留在 RFC provenance、git history、CI/release 系统或明确 archive 语义中，不能继续放在当前 `.docs/07_test/**` 冒充现行测试依据。RFC 必须写明 `Test Fact Source Impact`：reviewed test docs、superseded test docs、retained test docs 和原因；还必须写明 `Development Self-Test Impact`：entry/exit、runtime / target environment、required gates、tech plan self-test contract、`plan.yaml` / `plan.draft.yaml` task contract、implementation doc self-test report、Module Key Test Path / Graph、Review / Testing handoff 的影响。如果只是文案澄清且不影响测试事实源或自测链路，可分别写 `none`。
 
 RFC recalibration 本身也是 workflow task。开始处理变更前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "RFC_RECALIBRATION"`；当前轮只处理一个 RFC 文件、一个 impact analysis 单元或一个局部补丁单元。
 
@@ -47,7 +47,7 @@ RFC 阶段默认先评估是否适合并行 impact analysis。适合时，主 Ag
 
 - `.docs/rfc/` 按一次需求变更切片，一份 RFC 只描述一个可独立评估、实现和回归的变更。
 - 如果用户一次提出多个互不依赖的变更，应拆成多份 RFC。
-- RFC 的 impact analysis 负责判断是否需要重切 PRD、tech plan、`self_test_contract`、implementation doc、Development Self-Test Report、Module Key Test Path、test strategy、test cases 或 test report，并覆盖 state、tools、package assets、tests、migration 和 generated overview。
+- RFC 的 impact analysis 负责判断是否需要重切 PRD、tech plan、`self_test_contract`、implementation doc、Development Self-Test Report、Module Key Test Path / Graph、test strategy、test cases 或 test report，并覆盖 state、tools、package assets、tests、migration 和 generated overview。
 - 对受影响产物做局部补丁，不重写无关稳定 slice。
 - 每次 RFC 影响了文档边界，都要更新 `.docs/INDEX.md` 并记录受影响任务状态。
 
@@ -82,7 +82,7 @@ RFC 阶段受 `plan.yaml` 管控：
 - [ ] 已判断 RFC 是否需要拆分，以及是否影响其它阶段 slice。
 - [ ] 已列出 docs/state/skills/policies/templates/tools/package assets/tests/migrations/generated artifacts 的影响面。
 - [ ] 已记录 `Test Fact Source Impact`，并清理被 supersede 的 `.docs/07_test/**` 当前事实链接。
-- [ ] 已记录 `Development Self-Test Impact`；如果 RFC 改变 entry/exit、runtime、gate、handoff、blocker 或模块关键测试路径，已同步 tech plan、task contract、required gates、implementation doc 和 Review/Testing handoff 影响。
+- [ ] 已记录 `Development Self-Test Impact`；如果 RFC 改变 entry/exit、runtime、gate、handoff、blocker、模块关键测试路径或 Module Key Test Graph，已同步 tech plan、task contract、required gates、implementation doc 和 Review/Testing handoff 影响。
 - [ ] 受影响任务已标记或新增。
 - [ ] Regression requirements 已明确。
 - [ ] `.docs/INDEX.md` 已链接 RFC 和受影响产物。

package/assets/skills/pjsdlc_tester/SKILL.md

@@ -17,7 +17,9 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 
 执行回归时，优先选择能证明阶段出口的 gate。测试无法运行、环境缺失或数据不可得时，不要宣布通过；如果已经进入 TESTING，应在 `TEST_REPORT.md` 中记录 `BLOCKED`、已完成检查和恢复条件。
 
-TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输出验证。可以补充测试、fixture、mock、assertion helper 和测试文档，但不能在 TESTING 中新增或长期维护 product runtime、server/API/CLI/adapter、direct poller、cloud bootstrap、systemd unit、真实 provider adapter、package runtime script 或部署脚本。如果发现真实入口/出口不存在、implementation doc 缺少 `Development Evidence` 或 `Development Self-Test Report`、自测报告缺少 `Report Status: PASS`、缺少从本地启动或调用入口到完成全部自测用例的 `Module Key Test Path`、或该路径没有覆盖本 task / 本模块承诺的入口、内部关键路径、关键边界、观察点和完成证据，live 模式不可调用、配置契约缺失、Review readiness checklist 不是全 `PASS`，或 `Evidence Level` / `Target Runtime Environment` / `self_test_contract` 与 task 或技术方案承诺不一致，应记录 `BLOCKED`、生成 RFC 或后续 dev task 建议，并停止把测试阶段扩大成开发/集成搭建。`Development Self-Test Report` 不是 debug log、operator log、runbook 或探索流水；测试只消费其模块入口、核心路径、出口和最小证据。high-risk runtime/live/remote-operator 验证要先读 `plan.yaml#resume_capsule`，再读 `.docs/09_runbooks/**` runbook 和 evidence index，最后才读 exploration appendix；测试只沿 canonical path 验证，不重新尝试 `do_not_retry` 中的失败路径。开发尚未交付可测试 entry/exit、目标运行环境、Development Self-Test Report 或 Testing Handoff Contract 时，不要在 `.docs/07_test/**` 提前生成正式测试用例或正式报告；验收思路应留在 PRD acceptance criteria、tech plan verification strategy 或非 `.docs/07_test/**` 的草稿说明里。`TEST_REPORT.md` 不能在描述缺少 entry/exit、缺少 Development Evidence、缺少 Development Self-Test Report、证据等级不匹配或未交付应用入口时给出 `PASS`。
+TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输出验证。可以补充测试、fixture、mock、assertion helper 和测试文档，但不能在 TESTING 中新增或长期维护 product runtime、server/API/CLI/adapter、direct poller、cloud bootstrap、systemd unit、真实 provider adapter、package runtime script 或部署脚本。如果发现真实入口/出口不存在、implementation doc 缺少 `Development Evidence` 或 `Development Self-Test Report`、自测报告缺少 `Report Status: PASS`、缺少从本地启动或调用入口到完成全部自测用例的 `Module Key Test Path`、缺少 `Evidence Index Refs`、或该路径没有覆盖本 task / 本模块承诺的入口、内部关键路径、关键边界、观察点和完成证据，live 模式不可调用、配置契约缺失、Review readiness checklist 不是全 `PASS`，或 `Evidence Level` / `Target Runtime Environment` / `self_test_contract` 与 task 或技术方案承诺不一致，应记录 `BLOCKED`、生成 RFC 或后续 dev task 建议，并停止把测试阶段扩大成开发/集成搭建。若 `self_test_contract` 设置 `graph_required: true` 或包含 `module_key_test_graph`，TESTING 必须按 `Module Key Test Graph` 选择入口、checkpoint、scenario 和 observable exit，不能重新发明 runtime 或把图扩成测试执行引擎。`Development Self-Test Report` 不是 debug log、operator log、runbook、evidence dump 或探索流水；测试只消费其模块入口、核心路径、出口和最小证据指针。high-risk runtime/live/remote-operator 验证要先读 `plan.yaml#resume_capsule`，再读 `.docs/09_runbooks/**` runbook 和 evidence index，最后才读 exploration appendix；测试只沿 canonical path 和 hard constraints 验证，不重新尝试 `do_not_retry` 中的失败路径。开发尚未交付可测试 entry/exit、目标运行环境、Development Self-Test Report 或 Testing Handoff Contract 时，不要在 `.docs/07_test/**` 提前生成正式测试用例或正式报告；验收思路应留在 PRD acceptance criteria、tech plan verification strategy 或非 `.docs/07_test/**` 的草稿说明里。`TEST_REPORT.md` 不能在描述缺少 entry/exit、缺少 Development Evidence、缺少 Development Self-Test Report、证据等级不匹配或未交付应用入口时给出 `PASS`。
+
+当 TESTING 发现 bug，`TEST_REPORT.md` 的 Final decision 必须为 `BLOCKED`，并写明 `Bugfix Route`。`bugfix_replan` 表示测试证明技术方案、接口契约、任务拆分、测试入口或 handoff graph 需要修改，Manager 可从 `TESTING` 轻量回退到 `ARCHITECTING`，先修正 tech plan / `plan.draft.yaml`，再回到 `SPRINTING`。`bugfix_implementation_gap` 表示既有技术方案仍正确，只是实现没有按方案交付，Manager 可从 `TESTING` 轻量回退到 `SPRINTING` 创建或选择小的 bugfix dev task；该路径是保留口子，不是预期常态。若测试暴露的是需求、验收标准或产品边界变化，仍然进入 `RFC_RECALIBRATION`。
 
 测试设计和回归证据产出本身也是 workflow task。开始测试前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "TESTING"`；当前轮只产出一个测试策略 slice、测试用例 slice、回归批次、风险验证片区或一组 scoped test changes。`plan.yaml` 仍是唯一执行计划事实源，`.docs/07_test/**` 只记录当前方案的 test strategy、test cases、executed regression evidence、coverage gaps 和 final decision，不表达“下一步如何开发”，也不保留已被 RFC supersede 的旧测试结果。
 
@@ -44,7 +46,7 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 - 更新后的 `<harnessRoot>/state/plan.yaml`
 - 回归证据记录
 - 覆盖缺口清单
-- `BLOCKED` 时的 RFC/dev follow-up 建议和恢复条件
+- `BLOCKED` 时的 `Bugfix Route`、RFC/dev follow-up 建议和恢复条件
 
 ## 语义切片
 
@@ -67,11 +69,11 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 
 ## 规则
 
-1. 测试用例必须追溯到 PRD acceptance criteria 或 Review findings，并绑定 SPRINTING/REVIEWING 已确认的 runnable entry/exit、Development Evidence、Development Self-Test Report、Evidence Level、Target Runtime Environment 和 Testing Handoff Contract。
+1. 测试用例必须追溯到 PRD acceptance criteria 或 Review findings，并绑定 SPRINTING/REVIEWING 已确认的 runnable entry/exit、Development Evidence、Development Self-Test Report、Evidence Level、Target Runtime Environment 和 Testing Handoff Contract；复杂路径还要消费 Module Key Test Graph，而不是在 TESTING 中重新设计 runtime path。
 2. 根据风险补充边界、负向、回归和集成测试。
 3. 如果有意延后覆盖，必须记录风险和 follow-up。
 4. 不得新增 product runtime、server/API/CLI/adapter、poller、cloud bootstrap、systemd unit、真实 provider adapter、package runtime script 或部署脚本；这些属于 SPRINTING/RFC。
-5. 测试发现入口/出口或 Development Evidence 缺失时，Final decision 必须为 `BLOCKED`，并指出回到 SPRINTING/RFC 的具体条件。
+5. 测试发现入口/出口或 Development Evidence 缺失时，Final decision 必须为 `BLOCKED`，并指出回到 `ARCHITECTING`、`SPRINTING` 或 `RFC_RECALIBRATION` 的具体条件。
 6. 新测试策略使用 `.docs/07_test/TEST_STRATEGY.md`，新测试用例使用 `.docs/07_test/TEST_CASES.md`，执行报告使用 `.docs/07_test/TEST_REPORT.md`；不要新建或继续依赖 `.docs/07_test/TEST_PLAN.md`。
 7. `TEST_REPORT.md` 不得包含 `pending`、`TBD`、`待填`、`TODO` 或占位结论；未执行或不可执行时 Final decision 必须为 `BLOCKED` 并给出恢复条件。
 8. RFC 改变技术路线、entry/exit 或验收边界后，必须确认 `.docs/07_test/**` 中旧路线测试证据已删除或不再从 `.docs/INDEX.md` 暴露。
@@ -87,12 +89,13 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 - [ ] Regression checklist 已完成。
 - [ ] 测试只调用既有 runnable entry/exit；未在 TESTING 中新增 product runtime、bootstrap、provider adapter、deploy 或 package runtime script。
 - [ ] 已核对 implementation doc 中的 Development Evidence、Evidence Level、Target Runtime Environment 和 Testing Handoff Contract，并只基于已交付入口设计测试。
-- [ ] 已核对 Development Self-Test Report 中 Report Status、scenario results、executed gates、Module Key Test Path 和 actual evidence。
+- [ ] 已核对 Development Self-Test Report 中 Report Status、Module Application Entry、scenario results、executed gates、Module Key Test Path、Observable Exit、Current Blocker、Testing Handoff Readiness 和 Evidence Index Refs；若存在 Module Key Test Graph，测试路径按图消费。
 - [ ] high-risk runtime/live 验证已优先使用 `resume_capsule` 与 runbook/evidence index，未重复执行 exploration appendix 中的失败路径。
 - [ ] 已判断 test report / test matrix 的语义切片边界。
 - [ ] 未把测试计划、测试用例或待填内容写成 `TEST_REPORT.md`。
 - [ ] 已确认 `.docs/07_test/**` 只包含当前方案仍有效的测试事实。
 - [ ] Coverage gaps 已明确。
+- [ ] 若 Final decision 为 `BLOCKED` 且原因是 bug，已写明 `Bugfix Route: bugfix_replan | bugfix_implementation_gap | RFC_RECALIBRATION`。
 - [ ] 如果启用了并行测试，worker evidence 已由主 Agent 汇总到测试产物。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。
 - [ ] Final decision 是 `PASS` 或 `BLOCKED`。

package/assets/templates/EVIDENCE_INDEX_TEMPLATE.md

@@ -1,6 +1,6 @@
 # [Runtime / Live Smoke] Evidence Index
 
-本文件只保存证据指针和缺口，不把证据正文塞回 implementation doc 主线。
+本文件只保存证据指针和缺口，不把证据正文塞回 implementation doc 主线或 `Development Self-Test Report`。
 
 | Scenario | Status | Evidence File / System | Gap / Next Action |
 |---|---|---|---|
@@ -11,6 +11,7 @@
 - Temporary evidence:
 - Stable artifact / CI / release record:
 - Evidence that must not be copied into main docs:
+- Development Self-Test Report reference format:
 
 ## Missing Evidence
 

package/assets/templates/EXPLORATION_APPENDIX_TEMPLATE.md

@@ -20,3 +20,5 @@
 | Decision | Promoted To |
 |---|---|
 |  | `plan.yaml#resume_capsule` / runbook / implementation doc |
+
+凡会改变下一步动作的判断，必须 promoted 到 `plan.yaml#resume_capsule.do_not_retry` 或 runbook 顶部 `Hard Constraints`；本 appendix 只能保留推导和历史背景。

package/assets/templates/IMPLEMENTATION_DOC_TEMPLATE.md

@@ -60,31 +60,37 @@ Input
 - Operator runbook: `.docs/09_runbooks/...`
 - Credential reference: Keychain item name 或 secret reference name only；不要记录明文密钥。
 - Command/UI channel:
+- Hard Constraints: 会改变下一步动作的判断必须提升到这里和 `plan.yaml#resume_capsule.do_not_retry`；不要只埋在 evidence、notes 或 appendix。
 - Do-not-retry summary: fallback / diagnostic 只写一句结论，详细内容进 exploration appendix 或 git history。
 
 ## 8. Development Self-Test Report（开发自测报告）
 
-本节只证明模块入口、核心路径、出口和最小证据，不是 debug log、operator log、runbook 或探索流水。
+本节是开发阶段可执行交接卡，只证明模块应用入口、核心路径、出口和最小证据指针。目标控制在几十行；high-risk runtime/live 场景包含 `Gate Breakdown` 时也不要超过 120 行。本节不是 debug log、operator log、runbook、evidence dump 或探索流水。
 
 - Report Status: PASS | BLOCKED | IN_PROGRESS | STALE
 - Contract Source:
+- Module Application Entry:
+- Module Key Test Path: local start / invocation -> all self-test scenarios -> all task/module promised runnable entries -> actual internal key paths / boundaries / checkpoints -> observable completion evidence
+- Module Key Test Graph: required only when `self_test_contract.graph_required: true` or `module_key_test_graph` exists; keep it as a compact DAG pointer list/table covering entry, checkpoints, scenario nodes, observable exit, and evidence refs.
 - Scenario Results:
 - Executed Gates:
-- Module Key Test Path: local start / invocation -> all self-test scenarios -> all task/module promised runnable entries -> actual internal key paths / boundaries / checkpoints -> observable completion evidence
-- Actual Evidence:
-- Missing / Blockers:
+- Observable Exit:
+- Current Blocker:
 - Testing Handoff Readiness:
+- Evidence Index Refs: `.docs/09_runbooks/..._evidence.md` 或外部 artifact / CI / command output path；不要复制证据正文。
 
 保留：
 - Runnable Entry / Module Key Test Path / Observable Exit
-- Scenario Results / Executed Gates / Actual Evidence
-- Missing / Blockers / Testing Handoff Readiness
+- Scenario Results / Executed Gates / Evidence Index Refs
+- Current Blocker / Testing Handoff Readiness
 
 不保留：
 - 每次工具探索的完整流水
 - debug log、operator log、历史操作日记或 runbook 正文
 - fallback / diagnostic 的长篇命令、截图过程或 UI 细节
 - 与当前恢复路径无关的旧失败通道；只在 appendix 或 git history 保留
+- `Actual Evidence` 正文字段；证据正文进入 Evidence Index 或外部 artifact，本节只留 refs
+- high-risk implementation doc 主线不得新增 `Evidence Dump`、`Operator Log`、`Failed Attempts`、`Screenshot Index` 等章节；这些只能进入 runbook / evidence index / exploration appendix
 
 ### Gate Breakdown（Gate 分层）
 
@@ -99,6 +105,21 @@ Input
 |---|---|---|---|---|
 |  |  |  |  |  |
 
+### Module Key Test Graph（复杂 / high-risk 路径需要）
+
+只记录实际 handoff path 的 DAG 骨架和 evidence pointer；不要放 command output、截图过程、operator log、debug log、runbook 正文、失败探索或历史流水。
+
+| Node ID | Kind | Label | Scenario Ref | Expected Exit | Evidence Ref |
+|---|---|---|---|---|---|
+| entry-local-start | entry |  |  |  |  |
+| scenario-st-001 | scenario |  | ST-001 |  | `.docs/09_runbooks/...#ST-001` |
+| exit-observable | observable_exit |  |  |  |  |
+
+| From | To |
+|---|---|
+| entry-local-start | scenario-st-001 |
+| scenario-st-001 | exit-observable |
+
 ## 9. Testing Handoff Contract（测试交接合同）
 
 - Entry:

package/assets/templates/PLAN_TEMPLATE.yaml

@@ -12,7 +12,7 @@ next_task_sequence: 2
 #   blocker: "current blocker, or none with context"
 #   last_passed_gate: "last concrete PASS gate or checkpoint"
 #   do_not_retry:
-#     - "known failed path or repeated trap to avoid"
+#     - "known failed path, repeated trap, or strategy-changing hard constraint; e.g. if PC WeChat shows QR after confirmed login, first classify rule_assumption_gap vs operator_induced_logout_or_session_reset before rescanning"
 #   recovery_refs:
 #     - ".docs/04_implementation/example.md"
 #     - ".docs/09_runbooks/example_live_smoke_runbook.md"
@@ -93,6 +93,36 @@ tasks:
       runnable_entry: "command / URL / endpoint / worker command"
       observable_exit: "response / page state / side effect / log / artifact"
       module_key_test_path: "local start command / URL -> all self-test scenarios -> all task/module promised runnable entries -> internal key paths / boundaries / checkpoints -> observable completion evidence"
+      # Set graph_required: true for complex/high-risk handoff paths:
+      # scenario >= 3, multiple branches/entries, runtime/live/provider/browser/worker,
+      # or paths that Review/Testing must consume explicitly. The graph is a
+      # lightweight DAG handoff skeleton, not an execution trace, runbook, log,
+      # evidence dump, or graph engine input.
+      graph_required: false
+      module_key_test_graph:
+        nodes:
+          - id: "entry-local-start"
+            kind: "entry"
+            label: "local start command / URL"
+          - id: "checkpoint-core-path"
+            kind: "checkpoint"
+            label: "core module boundary or checkpoint"
+          - id: "scenario-st-001"
+            kind: "scenario"
+            label: "ST-001 expected behavior"
+            scenario_ref: "ST-001"
+            expected_exit: "observable response / side effect / page state"
+            evidence_ref: ".docs/09_runbooks/example_evidence.md#ST-001"
+          - id: "exit-observable"
+            kind: "observable_exit"
+            label: "observable response / side effect / page state"
+        edges:
+          - from: "entry-local-start"
+            to: "checkpoint-core-path"
+          - from: "checkpoint-core-path"
+            to: "scenario-st-001"
+          - from: "scenario-st-001"
+            to: "exit-observable"
       required_gates:
         - "npm run smoke"
       scenarios:

package/assets/templates/RUNBOOK_TEMPLATE.md

@@ -10,7 +10,12 @@
 - Last known good checkpoint:
 - Primary blocker:
 
-## 2. Operator Path
+## 2. Hard Constraints
+
+- 会改变下一步动作的判断必须写在这里，并同步到 `plan.yaml#resume_capsule.do_not_retry` 或 implementation doc `Current Operator Path`。
+- Example: PC 微信已登录后再次出现 QR 时，先判定 `rule_assumption_gap` vs `operator_induced_logout_or_session_reset`，不得直接进入重新扫码流程。
+
+## 3. Operator Path
 
 ```txt
 canonical:
@@ -21,26 +26,26 @@ UI channel:
 do not prefer:
 ```
 
-## 3. Preconditions
+## 4. Preconditions
 
 - Required access:
 - Required local tools:
 - Required remote services:
 - Safety / cleanup notes:
 
-## 4. Resume Steps
+## 5. Resume Steps
 
 1. 
 2. 
 3. 
 
-## 5. Fallbacks And Diagnostics
+## 6. Fallbacks And Diagnostics
 
 - Preferred fallback:
 - Diagnostic-only paths:
 - Do not retry:
 
-## 6. Linked Evidence
+## 7. Linked Evidence
 
 - Evidence index:
 - Exploration appendix:

package/assets/templates/TEST_REPORT_TEMPLATE.md

@@ -43,4 +43,5 @@
 
 - Decision: `PASS` / `BLOCKED`
 - Evidence:
+- Bugfix Route when bug-related `BLOCKED`: `bugfix_replan` / `bugfix_implementation_gap` / `RFC_RECALIBRATION` / `not_applicable`
 - Recovery condition when `BLOCKED`: