agent-project-sdlc 0.1.22 → 0.1.23

package/README.md

@@ -83,15 +83,21 @@ Release docs are current-state facts, not a version ledger. New release work sho
 
 The generic rule is that any workflow promoting a draft task into a formal `TASK-*` in `plan.yaml` must remove the source draft from its draft queue in the same state update. The formal task is then recovered only from `plan.yaml`; completed history lives in implementation docs, git, PR and CI records. The built-in Harness draft queue is currently `plan.draft.yaml.tasks[]`, which means unadopted development drafts only. `/devloop` treats the development queue as exhausted only when both `plan.yaml.tasks[]` and `plan.draft.yaml.tasks[]` have no executable task.
 
+Phase routing is expressed as a lightweight explicit directed graph in `<harnessRoot>/pjsdlc_managed/policies/phase_contracts.yaml`: `phases` stores stable phase contracts, while `transitions` stores legal edges and small runtime effects such as setting or clearing `suspended_phase`. This makes normal advance, pre-development return, RFC interrupt/resume and BLOCKED resume rules consumable by both the transition helper and validators. It is intentionally not a heavy graph engine: no history graph, traversal framework, node/edge classes or visualizer are introduced; the goal is to reduce missed rules and drift.
+
+Migration cost is low for projects that use managed assets: run `npx sdlc-harness upgrade` to sync the new `phase_contracts.yaml` and `tools/transition.py`, or run `npx sdlc-harness sync` if only managed files need refreshing. `lifecycle.yaml` and `plan.yaml` do not need manual migration; old `allowed_next_phases` values are regenerated from the graph on the next transition. Projects with custom phase policies should convert node-local `next` / `returns` to top-level `transitions`. If the new `validate-harness` reports missing `transitions`, run `upgrade` or `sync` before validating again.
+
 Before development starts, `ARCHITECTING` can return to `REQUIREMENT_GATHERING` for PRD edits. The manager uses `python3 tools/transition.py --to REQUIREMENT_GATHERING`, the PM workflow updates the PRD through one `TASK-*`, then `validate-pm` and `python3 tools/transition.py --to ARCHITECTING` return the project to design. Requirement or design changes after `SPRINTING` use RFC recalibration; `SPRINTING`, `REVIEWING`, `TESTING` and `RELEASING` can enter the controlled interrupt with `python3 tools/transition.py --to RFC_RECALIBRATION`, then return to `SPRINTING` after `validate-rfc`.
 
-`validate-design` treats semantic slicing as a hard gate. Generated `overview.md` files do not count as deliverables, development draft tasks in `plan.draft.yaml` must reference existing tech plan slices through `docs.tech_plan`, multiple development draft tasks need distinct primary tech plan slices, and explicit AI provider/copilot, external-system, or compliance/permission/audit themes require dedicated architecture slices. Draft tasks with runnable boundaries must also include `self_test_contract`, backed by a `Development Self-Test Contract` section in the tech plan; the contract must include `module_key_test_path` from local start or invocation to all self-test scenarios completion, covering every runnable entry promised by the current task/module and its internal key paths.
+`validate-design` treats semantic slicing as a hard gate. Generated `overview.md` files do not count as deliverables, development draft tasks in `plan.draft.yaml` must reference existing tech plan slices through `docs.tech_plan`, multiple development draft tasks need distinct primary tech plan slices, and explicit AI provider/copilot, external-system, or compliance/permission/audit themes require dedicated architecture slices. Draft tasks with runnable boundaries must also include `self_test_contract`, backed by a `Development Self-Test Contract` section in the tech plan; the contract must include `module_key_test_path` from local start or invocation to all self-test scenarios completion, covering every runnable entry promised by the current task/module and its internal key paths. Complex or high-risk paths may set `graph_required: true` and provide `module_key_test_graph` to express entries, checkpoints, scenarios, exits and evidence refs as a lightweight DAG.
+
+SPRINTING Definition of Done includes module-level runnable delivery boundaries. API, CLI, server route, service, agent, runtime, adapter, worker, provider, config-contract and fixture/live boundaries promised by a technical plan or task must be implemented or marked `BLOCKED` during development. Runtime/app/provider/live tasks must declare `evidence_level.required`, `target_runtime_environment` and `self_test_contract` in `plan.yaml`; every gate in `self_test_contract.required_gates` must also appear in task `required_gates`, and `self_test_contract.module_key_test_path` must describe the path from local start or invocation to all self-test scenarios completion, covering every runnable entry promised by the current task/module and its internal key paths. Complex task `module_key_test_graph` is the canonical handoff path detail: it is a DAG instead of a tree because scenarios can share setup and converge on the same observable exit; it is not a heavy test execution graph and must not store traces, debug logs, operator logs, runbook bodies or evidence bodies. `deployed_runtime` cannot be closed by `unit`, `local_runtime`, `external_provider_live`, provider smoke, fake adapters or localhost smoke alone, and `business_handoff_ready` requires a Testing Handoff Contract. The current task implementation doc must include `Development Evidence` and a completed `Development Self-Test Report` with `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`, contract source, Module Application Entry, scenario results, executed gates, Module Key Test Path, Module Key Test Graph when required, Observable Exit, Current Blocker, Testing Handoff Readiness and Evidence Index Refs; only `Report Status: PASS` with every scenario `PASS` can close a development task. The report proves module entry, core path, exit and minimal evidence pointers; it is not a debug log, operator log, runbook, evidence dump or exploration history. Fallback/diagnostic detail belongs in `.docs/09_runbooks/**` evidence indexes, appendices or git history. The report must not use an `Actual Evidence` body field, should stay under 80 lines for ordinary tasks and under 120 lines for high-risk runtime tasks. Module Key Test Path records actual entries, internal key paths, boundaries, checkpoints and observable completion evidence. Provider smoke, fixture smoke, fake adapters and one-shot smoke prove only local links; they do not by themselves prove application readiness. REVIEWING treats missing entry/exit, initialization, config contract, target runtime, evidence level or development evidence as blocking, and TESTING only exercises entrypoints that Review has confirmed as `PASS`; complex paths are consumed through Module Key Test Graph, and TESTING must not add product runtime, bootstrap, provider adapter, deploy code or package runtime scripts.
 
-SPRINTING Definition of Done includes module-level runnable delivery boundaries. API, CLI, server route, service, agent, runtime, adapter, worker, provider, config-contract and fixture/live boundaries promised by a technical plan or task must be implemented or marked `BLOCKED` during development. Runtime/app/provider/live tasks must declare `evidence_level.required`, `target_runtime_environment` and `self_test_contract` in `plan.yaml`; every gate in `self_test_contract.required_gates` must also appear in task `required_gates`, and `self_test_contract.module_key_test_path` must describe the path from local start or invocation to all self-test scenarios completion, covering every runnable entry promised by the current task/module and its internal key paths. `deployed_runtime` cannot be closed by `unit`, `local_runtime`, `external_provider_live`, provider smoke, fake adapters or localhost smoke alone, and `business_handoff_ready` requires a Testing Handoff Contract. The current task implementation doc must include `Development Evidence` and a completed `Development Self-Test Report` with `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`, contract source, scenario results, executed gates, Module Key Test Path, actual evidence, missing/blockers and Testing Handoff Readiness; only `Report Status: PASS` with every scenario `PASS` can close a development task. The report proves module entry, core path, exit and minimal evidence; it is not a debug log, operator log, runbook or exploration history. Fallback/diagnostic detail belongs in `.docs/09_runbooks/**` appendices or git history. Module Key Test Path records actual entries, internal key paths, boundaries, checkpoints and observable completion evidence. Provider smoke, fixture smoke, fake adapters and one-shot smoke prove only local links; they do not by themselves prove application readiness. REVIEWING treats missing entry/exit, initialization, config contract, target runtime, evidence level or development evidence as blocking, and TESTING only exercises entrypoints that Review has confirmed as `PASS`; it must not add product runtime, bootstrap, provider adapter, deploy code or package runtime scripts.
+High-risk runtime/live/remote-operator tasks are resume-first. When the current SPRINTING task requires `external_provider_live`, `deployed_runtime` or `business_handoff_ready`, or its target runtime is `cloud_vm`, `managed_service`, `browser` or `worker`, `plan.yaml` must include top-level `resume_capsule` with the current state, canonical path, next step, blocker, last passed gate, do-not-retry list and recovery refs. Any judgment that changes the next action must be promoted to `resume_capsule.do_not_retry`, the runbook top-level `Hard Constraints`, or the short `Current Operator Path`; it cannot live only in evidence, notes, an appendix, or a long implementation doc. The validator scans `working_notes`, implementation docs and runbooks for session / QR / canonical path / do-not-retry judgments and fails when they are not promoted. Open task `working_notes` stays short, with a 5-8 item target and an 8 item validator limit. Long-term implementation facts stay in the implementation doc; operator paths, credential references and remote entrypoints live in `.docs/09_runbooks/**`; the implementation doc only keeps a short `Current Operator Path` with canonical operator path, runbook link, credential reference name, command/UI channel, hard constraints and do-not-retry summary. Evidence bodies live in an evidence index or external system and must not move into implementation-doc mainline sections such as `Evidence Dump`, `Operator Log`, `Failed Attempts`, or `Screenshot Index`; failed exploration stays in an exploration appendix. The Development Self-Test Report for these tasks must include a Gate Breakdown that separates local gate, cloud/service gate, executor/operator readiness and live smoke or handoff evidence.
 
-High-risk runtime/live/remote-operator tasks are resume-first. When the current SPRINTING task requires `external_provider_live`, `deployed_runtime` or `business_handoff_ready`, or its target runtime is `cloud_vm`, `managed_service`, `browser` or `worker`, `plan.yaml` must include top-level `resume_capsule` with the current state, canonical path, next step, blocker, last passed gate, do-not-retry list and recovery refs. Open task `working_notes` stays short, with a 5-8 item target and an 8 item validator limit. Long-term implementation facts stay in the implementation doc; operator paths, credential references and remote entrypoints live in `.docs/09_runbooks/**`; the implementation doc only keeps a short `Current Operator Path` with canonical operator path, runbook link, credential reference name, command/UI channel and do-not-retry summary. Evidence bodies live in an evidence index or external system; failed exploration stays in an exploration appendix. The Development Self-Test Report for these tasks must include a Gate Breakdown that separates local gate, cloud/service gate, executor/operator readiness and live smoke or handoff evidence.
+`make validate-dev` and `npx sdlc-harness validate-dev` are in-development SPRINTING gates. They allow the current `current_task_id` open task to remain in `plan.yaml` while checking that it is a valid `phase: "SPRINTING"` task with `docs`, `allowed_paths`, `required_gates`, `acceptance_criteria`, `implementation_doc`, scoped dirty files, an empty `plan.draft.yaml` queue, runtime evidence task contract, `self_test_contract`, linked runnable-entry implementation docs, structured development evidence and a completed Development Self-Test Report. The report must include legal `Report Status` and Module Key Test Path so later agents can reuse the debug path from local entry to all self-test scenarios completion; that path is scoped to entries and internal key paths promised by the current task/module, not the whole system. When `graph_required: true` or `module_key_test_graph` exists, validators check that the graph is a single-entry DAG, node and edge refs are valid, every scenario is reachable from the entry and can reach an observable exit, and `evidence_ref` is only a short pointer. `validate-dev` only passes completion-oriented dev evidence when `Report Status: PASS` and every scenario is `PASS`; `BLOCKED`, `IN_PROGRESS` and `STALE` reports may exist as recovery facts but cannot close the current development task. Page tasks need a dev server or page URL plus browser/Playwright/screenshot/equivalent interaction evidence; API/CLI/worker/service/agent/runtime tasks need a startup or invocation command, endpoint/health/status, and observable response/output/side effect. `validate-dev` checks content consistency and completeness between the report and current `self_test_contract`; it does not prove commands really executed in the current run. Agents must execute the current task `required_gates` before filling the report, and writing `PASS` without running those gates is an Agent execution violation. `make validate-current` and `/advance` are phase-exit gates; before moving to REVIEWING, the implementation commit and completion ledger must be done and no open task may remain.
 
-`make validate-dev` and `npx sdlc-harness validate-dev` are in-development SPRINTING gates. They allow the current `current_task_id` open task to remain in `plan.yaml` while checking that it is a valid `phase: "SPRINTING"` task with `docs`, `allowed_paths`, `required_gates`, `acceptance_criteria`, `implementation_doc`, scoped dirty files, an empty `plan.draft.yaml` queue, runtime evidence task contract, `self_test_contract`, linked runnable-entry implementation docs, structured development evidence and a completed Development Self-Test Report. The report must include legal `Report Status` and Module Key Test Path so later agents can reuse the debug path from local entry to all self-test scenarios completion; that path is scoped to entries and internal key paths promised by the current task/module, not the whole system. `validate-dev` only passes completion-oriented dev evidence when `Report Status: PASS` and every scenario is `PASS`; `BLOCKED`, `IN_PROGRESS` and `STALE` reports may exist as recovery facts but cannot close the current development task. Page tasks need a dev server or page URL plus browser/Playwright/screenshot/equivalent interaction evidence; API/CLI/worker/service/agent/runtime tasks need a startup or invocation command, endpoint/health/status, and observable response/output/side effect. `validate-dev` checks content consistency and completeness between the report and current `self_test_contract`; it does not prove commands really executed in the current run. Agents must execute the current task `required_gates` before filling the report, and writing `PASS` without running those gates is an Agent execution violation. `make validate-current` and `/advance` are phase-exit gates; before moving to REVIEWING, the implementation commit and completion ledger must be done and no open task may remain.
+Migration cost for the lightweight DAG test path graph is zero to low. Existing projects, tasks and implementation docs that only use `module_key_test_path` remain valid; missing graphs are not retroactively rejected. Managed consumers can run `npx sdlc-harness upgrade`, or `npx sdlc-harness sync` when only managed files need refreshing. New high-risk or multi-scenario tasks will be prompted to generate `graph_required: true` and a graph skeleton. Existing high-risk tasks can be manually improved by splitting their current Module Key Test Path into a DAG. No automatic text-to-graph migration is provided because branches, checkpoints and observable exits require human or Agent judgment, and automatic conversion can invent false structure.
 
 `validate-test` keeps its command name as the TESTING phase gate. `.docs/07_test/TEST_STRATEGY.md` describes scope, environment, priority and execution strategy; `.docs/07_test/TEST_CASES.md` describes cases bound to real runnable entry/exit; `.docs/07_test/TEST_REPORT.md` only records executed TESTING evidence, test matrix, regression evidence, runnable entry/exit coverage, coverage gaps and final decision. `validate-test` only accepts `TEST_REPORT.md`; it no longer treats `TEST_PLAN.md` as a report fallback.
 

package/assets/docs/README.md

@@ -102,15 +102,21 @@ Agent 会读取 `<harnessRoot>/state/lifecycle.yaml` 和 `<harnessRoot>/state/pl
 
 技术方案阶段需要产出 `plan.draft.yaml`，是为了解决跨阶段交接和当前执行队列纯净性的冲突。`ARCHITECTING` 必须在进入开发前证明方案可以拆成具体、可验证的开发单元，包括修改范围、gate、implementation doc 和执行顺序；但这些未来开发 task 如果直接进入 `plan.yaml`，会和当前架构阶段 task 混在一起，让阶段 gate 无法区分“架构任务未完成”和“下一阶段任务已预拆”。因此开发任务先作为 draft 暂存，进入 `SPRINTING` 后再逐个 promote 成正式 `TASK-*`。其它阶段默认根据上一阶段已经稳定的事实源即时创建当前阶段 task，只有当某个阶段也需要提前为后续阶段生成具体执行任务时，才应引入同类 draft queue。
 
+阶段关系由 `<harnessRoot>/pjsdlc_managed/policies/phase_contracts.yaml` 中的轻量显式有向图表达：`phases` 保存稳定阶段 contract，`transitions` 保存合法流转边和少量效果，例如设置或清理 `suspended_phase`。这样做是为了让正常推进、开发前返回、RFC interrupt/resume 和 BLOCKED resume 都被 transition helper 与 validator 读取，避免规则埋在长文档或工具硬编码里。它不是重型图引擎，不保存历史、不做复杂遍历、不引入 node/edge class 或可视化；目标只是降低遗漏和漂移。
+
+迁移成本较低：对使用 managed assets 的项目，运行 `npx sdlc-harness upgrade` 即可同步新的 `phase_contracts.yaml` 和 `tools/transition.py`；也可以运行 `npx sdlc-harness sync` 只刷新 managed 文件。`lifecycle.yaml` 和 `plan.yaml` 不需要手动迁移，旧的 `allowed_next_phases` 会在下一次 `transition.py` 执行后按图重新生成。只有维护了自定义 phase policy 的项目需要把阶段内的 `next` / `returns` 转成 top-level `transitions`；如果升级前直接运行新版 `validate-harness` 看到缺少 `transitions`，先执行 `upgrade` / `sync`。
+
 在尚未进入开发前，`ARCHITECTING` 可以回到 `REQUIREMENT_GATHERING` 修改 PRD：Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切回 PM/PRD 工作流，完成 PRD task 和 `validate-pm` 后，再用 `python3 tools/transition.py --to ARCHITECTING` 回到设计阶段。进入 `SPRINTING` 后的需求或设计变化走 RFC workflow；`SPRINTING`、`REVIEWING`、`TESTING` 和 `RELEASING` 都可以通过 `python3 tools/transition.py --to RFC_RECALIBRATION` 进入受控 RFC 中断，RFC 完成后回到 `SPRINTING` 重新完成开发自测和 handoff。
 
-`validate-design` 会把架构阶段的语义切片作为硬 gate：`overview.md` 不计入 deliverables，`plan.draft.yaml` 中每个开发 draft task 必须通过 `docs.tech_plan` 指向存在的 tech plan slice；多个开发 draft task 默认需要不同 primary tech plan slice。PRD、tech plan 或 draft task 明确出现 AI provider / copilot、外部系统边界、合规 / 权限 / 审计等横切主题时，也需要对应的专门 architecture slice。可运行边界类 draft task 还必须带 `self_test_contract`，并在 tech plan 中有 `Development Self-Test Contract`；合同必须记录 `module_key_test_path`，说明从本地启动或调用入口开始，到完成全部自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径。
+`validate-design` 会把架构阶段的语义切片作为硬 gate：`overview.md` 不计入 deliverables，`plan.draft.yaml` 中每个开发 draft task 必须通过 `docs.tech_plan` 指向存在的 tech plan slice；多个开发 draft task 默认需要不同 primary tech plan slice。PRD、tech plan 或 draft task 明确出现 AI provider / copilot、外部系统边界、合规 / 权限 / 审计等横切主题时，也需要对应的专门 architecture slice。可运行边界类 draft task 还必须带 `self_test_contract`，并在 tech plan 中有 `Development Self-Test Contract`；合同必须记录 `module_key_test_path`，说明从本地启动或调用入口开始，到完成全部自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径。复杂或 high-risk 路径可设置 `graph_required: true` 并提供 `module_key_test_graph`，把入口、checkpoint、scenario、出口和 evidence refs 表达成轻量 DAG。
+
+SPRINTING 的 Definition of Done 包含模块级可运行交付边界：技术方案或 task 承诺的 API、CLI、server route、service、agent、runtime、adapter、worker、provider、配置契约和 fixture/live 边界必须在开发阶段实现或明确 `BLOCKED`。runtime/app/provider/live 类 task 必须在 `plan.yaml` 声明 `evidence_level.required`、`target_runtime_environment` 和 `self_test_contract`；`self_test_contract.required_gates` 必须同步出现在 task `required_gates`，`self_test_contract.module_key_test_path` 必须描述从本地启动或调用入口开始，到完成全部自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径。复杂 task 的 `module_key_test_graph` 是 handoff path 的 canonical detail：它是 DAG 而不是树，因为多个 scenario 可能共享 setup、分支后汇合到同一 observable exit；它不是重型测试执行图，不保存 trace、debug log、operator log、runbook 正文或证据正文。`deployed_runtime` 不能用 `unit`、`local_runtime`、`external_provider_live`、provider smoke、fake adapter 或 localhost smoke 单独关闭，`business_handoff_ready` 还必须有 Testing Handoff Contract。当前 task 的 implementation doc 还必须写入 `Development Evidence` 和 `Development Self-Test Report`，其中自测报告记录 `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`、contract source、Module Application Entry、scenario results、executed gates、Module Key Test Path、必要时的 Module Key Test Graph、Observable Exit、Current Blocker、Testing Handoff Readiness 和 Evidence Index Refs；只有 `Report Status: PASS` 且所有 scenario 为 `PASS` 才能关闭 development task。`Development Self-Test Report` 只证明模块入口、核心路径、出口和最小证据指针，不承担 debug log、operator log、runbook、evidence dump 或探索流水职责；fallback / diagnostic 最多一句总结，详细内容进入 `.docs/09_runbooks/**` evidence index / appendix 或 git history；主报告不得使用 `Actual Evidence` 正文字段，普通报告目标不超过 80 行，high-risk 报告目标不超过 120 行。`Module Key Test Path` 必须记录实际入口、内部关键路径、关键边界、观察点和可观测完成证据。provider smoke、fixture smoke、fake adapter 或 one-shot smoke 只能证明局部链路，不能单独证明 application readiness。REVIEWING 会把缺少入口/出口、初始化、配置契约、目标运行环境、证据等级或开发自测证据作为阻断项；TESTING 只调用 Review 已确认 `PASS` 的既有入口做输入输出验证，复杂路径按 Module Key Test Graph 消费，不能新增 product runtime、bootstrap、provider adapter、deploy 或 package runtime script。
 
-SPRINTING 的 Definition of Done 包含模块级可运行交付边界：技术方案或 task 承诺的 API、CLI、server route、service、agent、runtime、adapter、worker、provider、配置契约和 fixture/live 边界必须在开发阶段实现或明确 `BLOCKED`。runtime/app/provider/live 类 task 必须在 `plan.yaml` 声明 `evidence_level.required`、`target_runtime_environment` 和 `self_test_contract`；`self_test_contract.required_gates` 必须同步出现在 task `required_gates`，`self_test_contract.module_key_test_path` 必须描述从本地启动或调用入口开始，到完成全部自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径。`deployed_runtime` 不能用 `unit`、`local_runtime`、`external_provider_live`、provider smoke、fake adapter 或 localhost smoke 单独关闭，`business_handoff_ready` 还必须有 Testing Handoff Contract。当前 task 的 implementation doc 还必须写入 `Development Evidence` 和 `Development Self-Test Report`，其中自测报告记录 `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`、contract source、scenario results、executed gates、Module Key Test Path、actual evidence、missing/blockers 和 Testing Handoff Readiness；只有 `Report Status: PASS` 且所有 scenario 为 `PASS` 才能关闭 development task。`Development Self-Test Report` 只证明模块入口、核心路径、出口和最小证据，不承担 debug log、operator log、runbook 或探索流水职责；fallback / diagnostic 最多一句总结，详细内容进入 `.docs/09_runbooks/**` appendix 或 git history。`Module Key Test Path` 必须记录实际入口、内部关键路径、关键边界、观察点和可观测完成证据。provider smoke、fixture smoke、fake adapter 或 one-shot smoke 只能证明局部链路，不能单独证明 application readiness。REVIEWING 会把缺少入口/出口、初始化、配置契约、目标运行环境、证据等级或开发自测证据作为阻断项；TESTING 只调用 Review 已确认 `PASS` 的既有入口做输入输出验证，不能新增 product runtime、bootstrap、provider adapter、deploy 或 package runtime script。
+复杂 runtime/live/remote-operator 任务采用 resume-first 分层：当当前 SPRINTING task 要求 `external_provider_live`、`deployed_runtime`、`business_handoff_ready`，或目标环境是 `cloud_vm`、`managed_service`、`browser`、`worker` 时，`plan.yaml` 顶层必须维护 `resume_capsule`，只保留当前状态、canonical path、下一步、blocker、last passed gate、do-not-retry 和 recovery refs；凡会改变下一步动作的判断，必须 promoted 到 `resume_capsule.do_not_retry`、runbook 顶部 `Hard Constraints` 或短 `Current Operator Path`，不能只埋在 evidence、notes、appendix 或长 implementation doc 中。validator 会扫描 `working_notes`、implementation doc 和 runbook 中的 session / QR / canonical path / do-not-retry 类关键判断，未 promoted 时 fail。open task 的 `working_notes` 只保留恢复短备注，目标 5-8 条且 validator 上限 8 条。长期实现事实写 implementation doc；操作路径、凭证引用、远端入口写 `.docs/09_runbooks/**` runbook；implementation doc 只放短的 `Current Operator Path`，记录 canonical operator path、runbook link、credential reference name、command/UI channel、hard constraints 和 do-not-retry summary；证据正文只进入 evidence index 或外部证据系统，不得转移成 implementation doc 主线的 `Evidence Dump`、`Operator Log`、`Failed Attempts` 或 `Screenshot Index` 等章节；失败探索隔离到 exploration appendix。高风险 task 的 `Development Self-Test Report` 还必须有 `Gate Breakdown`，把 local gate、cloud/service gate、executor/operator readiness 和 live smoke / handoff 分开记录，不能只用一个 `validate-dev PASS` 覆盖全部进度。
 
-复杂 runtime/live/remote-operator 任务采用 resume-first 分层：当当前 SPRINTING task 要求 `external_provider_live`、`deployed_runtime`、`business_handoff_ready`，或目标环境是 `cloud_vm`、`managed_service`、`browser`、`worker` 时，`plan.yaml` 顶层必须维护 `resume_capsule`，只保留当前状态、canonical path、下一步、blocker、last passed gate、do-not-retry 和 recovery refs；open task 的 `working_notes` 只保留恢复短备注，目标 5-8 条且 validator 上限 8 条。长期实现事实写 implementation doc；操作路径、凭证引用、远端入口写 `.docs/09_runbooks/**` runbook；implementation doc 只放短的 `Current Operator Path`，记录 canonical operator path、runbook link、credential reference name、command/UI channel 和 do-not-retry summary；证据正文只进入 evidence index 或外部证据系统；失败探索隔离到 exploration appendix。高风险 task 的 `Development Self-Test Report` 还必须有 `Gate Breakdown`，把 local gate、cloud/service gate、executor/operator readiness 和 live smoke / handoff 分开记录，不能只用一个 `validate-dev PASS` 覆盖全部进度。
+`make validate-dev` / `npx sdlc-harness validate-dev` 是 SPRINTING 开发中 gate：当前 `current_task_id` 指向的 open task 可以继续留在 `plan.yaml`，validator 会检查它是否是合法 `phase: "SPRINTING"` task、是否具备 `docs`、`allowed_paths`、`required_gates`、`acceptance_criteria`、`implementation_doc`，并校验 dirty files、`plan.draft.yaml`、runtime evidence task contract、`self_test_contract`、implementation doc、结构化 `Development Evidence` 和 `Development Self-Test Report`。自测报告必须记录合法 `Report Status` 和 `Module Key Test Path`，便于后续 Agent 复用从本地入口到全部自测用例完成的 debug 路径；该路径只要求覆盖本 task / 本模块承诺范围内的可运行入口和内部关键路径，不要求覆盖全系统所有模块。若 `graph_required: true` 或存在 `module_key_test_graph`，validator 会校验它是单入口 DAG、节点和边引用有效、每个 scenario 可从 entry 到达并能走到 observable exit，且 `evidence_ref` 只是短指针。`validate-dev` 只接受 `Report Status: PASS` 且所有 scenario 为 `PASS` 的完成态；`BLOCKED`、`IN_PROGRESS`、`STALE` 可以记录恢复事实，但不能关闭当前 development task。页面类证据需要 dev server/page URL 与 browser check；API/CLI/worker/service/agent/runtime 类证据需要 startup/invocation command、endpoint/health/status 与 response/output/side effect。`validate-dev` 只校验自测报告内容与当前 `self_test_contract` 的一致性和完整性，不证明命令在本轮真实执行；Agent 必须先实际运行 current task `required_gates` 后再填写 `Development Self-Test Report`，未执行 required gates 却写 `PASS` 属于 Agent execution violation。`make validate-current` / `/advance` 是阶段出口 gate；进入 REVIEWING 前仍必须先完成 implementation commit 和 completion ledger，把 open task 从 `plan.yaml` 移除。
 
-`make validate-dev` / `npx sdlc-harness validate-dev` 是 SPRINTING 开发中 gate：当前 `current_task_id` 指向的 open task 可以继续留在 `plan.yaml`，validator 会检查它是否是合法 `phase: "SPRINTING"` task、是否具备 `docs`、`allowed_paths`、`required_gates`、`acceptance_criteria`、`implementation_doc`，并校验 dirty files、`plan.draft.yaml`、runtime evidence task contract、`self_test_contract`、implementation doc、结构化 `Development Evidence` 和 `Development Self-Test Report`。自测报告必须记录合法 `Report Status` 和 `Module Key Test Path`，便于后续 Agent 复用从本地入口到全部自测用例完成的 debug 路径；该路径只要求覆盖本 task / 本模块承诺范围内的可运行入口和内部关键路径，不要求覆盖全系统所有模块。`validate-dev` 只接受 `Report Status: PASS` 且所有 scenario 为 `PASS` 的完成态；`BLOCKED`、`IN_PROGRESS`、`STALE` 可以记录恢复事实，但不能关闭当前 development task。页面类证据需要 dev server/page URL 与 browser check；API/CLI/worker/service/agent/runtime 类证据需要 startup/invocation command、endpoint/health/status 与 response/output/side effect。`validate-dev` 只校验自测报告内容与当前 `self_test_contract` 的一致性和完整性，不证明命令在本轮真实执行；Agent 必须先实际运行 current task `required_gates` 后再填写 `Development Self-Test Report`，未执行 required gates 却写 `PASS` 属于 Agent execution violation。`make validate-current` / `/advance` 是阶段出口 gate；进入 REVIEWING 前仍必须先完成 implementation commit 和 completion ledger，把 open task 从 `plan.yaml` 移除。
+轻量 DAG 测试路径图的迁移成本为零到低：旧项目、旧 task 和旧 implementation doc 只写 `module_key_test_path` 仍然有效；缺少 graph 不会被 retroactive fail。升级 managed consumers 时运行 `npx sdlc-harness upgrade`，只刷新 managed files 时运行 `npx sdlc-harness sync`。新 high-risk / multi-scenario task 会由更新后的 prompts 倾向生成 `graph_required: true` 和 `module_key_test_graph` skeleton。旧 high-risk task 如需提升交接质量，可手动把现有 `Module Key Test Path` 拆成 DAG；不提供自动 text-to-graph migration，因为分支、checkpoint 和 observable exit 需要人工或 Agent 判断，自动转换容易制造虚假结构。
 
 `validate-test` 仍然是 TESTING 阶段 gate 名称。`.docs/07_test/TEST_STRATEGY.md` 描述测试范围、环境、优先级和执行策略；`.docs/07_test/TEST_CASES.md` 描述绑定真实 runnable entry/exit 的测试用例；`.docs/07_test/TEST_REPORT.md` 只记录 TESTING 阶段实际执行后的 test matrix、regression evidence、runnable entry/exit coverage、coverage gaps 和 final decision。`validate-test` 只接受 `TEST_REPORT.md`，不会把 `TEST_PLAN.md` 当作 report fallback。
 
@@ -128,7 +134,7 @@ SPRINTING 的 Definition of Done 包含模块级可运行交付边界：技术
 
 `<harnessRoot>/skills/<name>/SKILL.md` 是 Harness 的 workflow skill 事实源，也是稳定的 hard file index。它有两种使用方式：
 
-- Harness soft index：`AGENTS.md` 要求 Agent 先读 lifecycle/plan，再按 `active_skill` 和 `phase_contracts.yaml` 读取对应 skill。
+- Harness soft index：`AGENTS.md` 要求 Agent 先读 lifecycle/plan，再按 `active_skill` 和 `phase_contracts.yaml` 的 phase graph 读取对应 skill 与合法下一步。
 - Native skill adapter：如果某个 Agent 支持 native skill registry，可以把这些 workflow skills 同步或安装到该 Agent 的原生 skill root，让“产品方案”“技术方案”“开发循环”等自然语言在首轮就有机会命中。
 
 只在 `AGENTS.md` 里声明 `<harnessRoot>/skills` 不等于 native skill 注册；它保证的是 Harness soft index。Native skill 是否首轮水合，取决于具体 Agent 客户端是否扫描这个目录，或是否使用了额外 adapter。

package/assets/policies/phase_contracts.yaml

@@ -8,7 +8,6 @@ phases:
     outputs:
       - "<harnessRoot>/state/lifecycle.yaml"
     gates: []
-    next: "REQUIREMENT_GATHERING"
 
   REQUIREMENT_GATHERING:
     goal: "收集需求并形成产品方案"
@@ -23,7 +22,6 @@ phases:
       - ".docs/INDEX.md"
     gates:
       - "make validate-pm"
-    next: "ARCHITECTING"
 
   ARCHITECTING:
     goal: "根据产品方案生成架构设计、技术方案和任务草案"
@@ -40,9 +38,6 @@ phases:
       - "<harnessRoot>/state/plan.draft.yaml"
     gates:
       - "make validate-design"
-    next: "SPRINTING"
-    returns:
-      - "REQUIREMENT_GATHERING"
 
   SPRINTING:
     goal: "按任务状态执行开发、消费已采用草案、开发验证、Development Evidence 和实现文档沉淀"
@@ -62,7 +57,6 @@ phases:
       - "<harnessRoot>/state/plan.draft.yaml"
     gates:
       - "make validate-dev"
-    next: "REVIEWING"
 
   REVIEWING:
     goal: "只读审查实现质量、需求一致性和架构风险"
@@ -79,7 +73,6 @@ phases:
       - ".docs/06_review/REVIEW_REPORT.md"
     gates:
       - "make validate-review"
-    next: "TESTING"
 
   TESTING:
     goal: "基于已交付 entry/exit 形成测试策略、测试用例、执行报告、回归证据和覆盖缺口结论"
@@ -100,7 +93,6 @@ phases:
       - "tests/"
     gates:
       - "make validate-test"
-    next: "RELEASING"
 
   RELEASING:
     goal: "当前发布状态、发布检查和回滚方案"
@@ -115,7 +107,6 @@ phases:
       - ".docs/08_release/CURRENT_RELEASE.md"
     gates:
       - "make validate-release"
-    next: "COMPLETED"
 
   COMPLETED:
     goal: "当前里程碑已完成"
@@ -126,7 +117,6 @@ phases:
     outputs:
       - "<harnessRoot>/state/lifecycle.yaml"
     gates: []
-    next: "IDLE"
 
   RFC_RECALIBRATION:
     goal: "处理需求变更、影响分析、测试事实源清理、局部补丁和任务回退"
@@ -145,7 +135,6 @@ phases:
       - ".docs/INDEX.md"
     gates:
       - "make validate-rfc"
-    next: "SPRINTING"
 
   BLOCKED:
     goal: "等待人工补充信息、授权或基础设施处理"
@@ -156,4 +145,131 @@ phases:
     outputs:
       - "<harnessRoot>/state/lifecycle.yaml"
     gates: []
-    next: "REQUIREMENT_GATHERING"
+
+transitions:
+  - from: "IDLE"
+    to: "REQUIREMENT_GATHERING"
+    trigger: "advance"
+    kind: "normal"
+  - from: "REQUIREMENT_GATHERING"
+    to: "ARCHITECTING"
+    trigger: "advance"
+    kind: "normal"
+  - from: "ARCHITECTING"
+    to: "SPRINTING"
+    trigger: "advance"
+    kind: "normal"
+  - from: "SPRINTING"
+    to: "REVIEWING"
+    trigger: "advance"
+    kind: "normal"
+  - from: "REVIEWING"
+    to: "TESTING"
+    trigger: "advance"
+    kind: "normal"
+  - from: "TESTING"
+    to: "RELEASING"
+    trigger: "advance"
+    kind: "normal"
+  - from: "RELEASING"
+    to: "COMPLETED"
+    trigger: "advance"
+    kind: "normal"
+  - from: "COMPLETED"
+    to: "IDLE"
+    trigger: "advance"
+    kind: "normal"
+  - from: "ARCHITECTING"
+    to: "REQUIREMENT_GATHERING"
+    trigger: "return_to_prd"
+    kind: "return"
+  - from: "SPRINTING"
+    to: "RFC_RECALIBRATION"
+    trigger: "requirement_change"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "REVIEWING"
+    to: "RFC_RECALIBRATION"
+    trigger: "requirement_change"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "TESTING"
+    to: "RFC_RECALIBRATION"
+    trigger: "requirement_change"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "RELEASING"
+    to: "RFC_RECALIBRATION"
+    trigger: "requirement_change"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "RFC_RECALIBRATION"
+    to: "SPRINTING"
+    trigger: "rfc_complete"
+    kind: "resume"
+    effects:
+      clear_suspended_phase: true
+  - from: "IDLE"
+    to: "BLOCKED"
+    trigger: "blocked"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "REQUIREMENT_GATHERING"
+    to: "BLOCKED"
+    trigger: "blocked"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "ARCHITECTING"
+    to: "BLOCKED"
+    trigger: "blocked"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "SPRINTING"
+    to: "BLOCKED"
+    trigger: "blocked"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "REVIEWING"
+    to: "BLOCKED"
+    trigger: "blocked"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "TESTING"
+    to: "BLOCKED"
+    trigger: "blocked"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "RELEASING"
+    to: "BLOCKED"
+    trigger: "blocked"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "COMPLETED"
+    to: "BLOCKED"
+    trigger: "blocked"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "RFC_RECALIBRATION"
+    to: "BLOCKED"
+    trigger: "blocked"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
+  - from: "BLOCKED"
+    to: "<suspended_phase>"
+    trigger: "resume"
+    kind: "resume"
+    effects:
+      clear_suspended_phase: true

package/assets/skills/pjsdlc_architect_design/SKILL.md

@@ -57,7 +57,8 @@ ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问
 - 如果实现计划改变了已有模块边界，应更新相关 architecture slice，而不是只在 task 描述里补一句。
 - 只要技术方案或 draft task 出现 service、agent、runtime、worker、frontend app、provider/live integration 或外部可运行边界，task breakdown 必须包含最后一公里 runtime 初始化和 testing handoff 交付：目标运行环境、启动/部署或预览方式、health/readiness、smoke 输入输出、日志/错误证据、测试可调用入口和出口。
 - 这类开发 draft task 必须写入 `evidence_level.required`、`target_runtime_environment` 和 `self_test_contract`。`evidence_level.required` 只能使用 `unit`、`local_runtime`、`external_provider_live`、`deployed_runtime`、`business_handoff_ready`；`target_runtime_environment.kind` 只能使用 `local`、`ci`、`staging`、`cloud_vm`、`managed_service`、`browser`、`worker`、`not_applicable`。`self_test_contract` 的 `source` 必须引用当前 tech plan slice，`required_gates` 必须同步到 task `required_gates`，`scenarios[]` 至少覆盖一个可运行入口和可观测出口，`module_key_test_path` 必须描述从本地启动或调用入口开始，到完成所有自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径。
-- 如果 draft task 属于 high-risk runtime/live/remote-operator 工作（`external_provider_live`、`deployed_runtime`、`business_handoff_ready`，或目标环境为 `cloud_vm`、`managed_service`、`browser`、`worker`），还必须预留恢复分层：`docs.runbook` 指向 `.docs/09_runbooks/**` 下的 runbook / evidence index / exploration appendix，`allowed_paths` 覆盖这些文件，acceptance criteria 要求 promote 后维护 `plan.yaml#resume_capsule`。runbook 写 canonical operator path，evidence index 只写证据指针，exploration appendix 隔离失败尝试；不要把这些内容塞进 implementation doc 主线。
+- 复杂或高风险自测路径要同时生成轻量 DAG skeleton：当 scenario >= 3、多分支、多入口、runtime/live/provider/browser/worker，或 Review/Testing 需要明确消费 checkpoint / exit / evidence refs 时，在 `self_test_contract` 设置 `graph_required: true` 并填写 `module_key_test_graph`。图只保存 handoff path 的 `entry`、`checkpoint`、`branch`、`scenario`、`observable_exit` 节点和边，以及短 `evidence_ref` 指针；不要把命令输出、截图过程、operator log、debug log、runbook 正文、失败探索或历史流水塞进图。普通单入口 / 少量 scenario task 保留短 `module_key_test_path` 即可。
+- 如果 draft task 属于 high-risk runtime/live/remote-operator 工作（`external_provider_live`、`deployed_runtime`、`business_handoff_ready`，或目标环境为 `cloud_vm`、`managed_service`、`browser`、`worker`），还必须预留恢复分层：`docs.runbook` 指向 `.docs/09_runbooks/**` 下的 runbook / evidence index / exploration appendix，`allowed_paths` 覆盖这些文件，acceptance criteria 要求 promote 后维护 `plan.yaml#resume_capsule`，并把会改变下一步动作的判断 promoted 到 `resume_capsule.do_not_retry` 或 runbook 顶部 `Hard Constraints`。runbook 写 canonical operator path 和 hard constraints，evidence index 只写证据指针，exploration appendix 隔离失败尝试；不要把这些内容塞进 implementation doc 主线。
 - 如果用户明确要求把既有完整技术方案文件切成多个 `.docs/03_tech_plan/` slices，先确认 replacement slices 覆盖原文件中仍有效的接口契约、数据模型、模块方案、任务组和 gate；切片完成并更新 `plan.draft.yaml` 引用、`.docs/INDEX.md`、刷新 `overview.md` 后，删除被替代的完整 tech plan file，避免同一事实由完整文件和 slices 双重保留。
 - 每次新增、拆分、合并或废弃 slice 后，都要更新 `.docs/INDEX.md`。
 
@@ -94,6 +95,7 @@ ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问
 - [ ] `plan.draft.yaml` 中每个开发 draft task 已通过 `docs.tech_plan` 绑定到对应 tech plan slice。
 - [ ] 如果用户要求把完整技术方案切成 tech plan slices，已删除被替代的完整 tech plan file，并同步 `plan.draft.yaml` 引用。
 - [ ] task draft 字段完整且范围清晰；runtime/app/provider/live 类 task 已声明 `evidence_level`、`target_runtime_environment` 和 `self_test_contract`。
+- [ ] 复杂或 high-risk 自测路径已判断是否需要 `graph_required: true`；需要时已在 tech plan 和 draft task 中生成 `module_key_test_graph` skeleton。
 - [ ] `.docs/INDEX.md` 已链接新增产物。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。
 - [ ] `make validate-design` 准备通过。

package/assets/skills/pjsdlc_dev_sprint/SKILL.md

@@ -17,11 +17,11 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 开发阶段的 Definition of Done 包含可运行的系统入口/出口。凡技术方案或 task 承诺 API、CLI、server route、service、agent、runtime、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，当前实现必须提供对应入口、调用方式、初始化方式、输出/副作用边界和验证方式；如果真实入口/出口尚不可运行，不能把 task 当作完成，也不能把缺口留给 TESTING 补 runtime。runtime/app/provider/live 类 task 必须在 `plan.yaml` 声明 `evidence_level.required`、`target_runtime_environment` 和 `self_test_contract`，并按合同交付：`deployed_runtime` 不能用 `unit`、`local_runtime`、`external_provider_live`、provider smoke、fake adapter 或 localhost smoke 单独关闭；`business_handoff_ready` 必须提供 Testing Handoff Contract。Implementation doc 必须写明 `Runnable Entry/Exit`，并在 `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`；其中 `Basic Self-test Evidence` 应指向已执行的 `Development Self-Test Report`。确实不适用时也要显式写 `Not applicable` 和具体原因。provider smoke、fixture smoke、fake adapter 或 one-shot smoke 只能证明局部链路，不能单独证明 `Application readiness`。此时应保留或创建 `BLOCKED`/后续 dev task，或通过 RFC/ARCHITECTING 处理边界变更。
 
-`self_test_contract` 是开发阶段自测合同，由 ARCHITECTING 或 RFC_RECALIBRATION 先定义，SPRINTING 负责执行并在 implementation doc 填写 `Development Self-Test Report`。开发者不得在开发结束后用现有实现反推自测合同；如果合同缺失、入口不匹配、required gates 未同步或场景无法执行，要先回到 ARCHITECTING/RFC 或把 task 保持为 `BLOCKED`。自测报告不是 TESTING 阶段产物，也不是 debug log、operator log、runbook 或历史流水；它只证明当前模块级可运行交付边界已经能被 Review/Testing 消费。报告必须写 `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`，只有 `PASS` 且所有 scenario 都是 `PASS` 才能关闭当前 development task；`BLOCKED`、`IN_PROGRESS`、`STALE` 可以作为恢复事实存在，但不能作为交接通过。报告还必须记录 `Module Key Test Path`：从本地启动或调用入口开始，执行并完成 `self_test_contract` 中全部自测用例的模块关键测试路径。该路径应覆盖本 task / 本模块承诺的所有可运行入口，以及自测用例实际经过的内部关键路径、关键边界、观察点和可观测完成证据，供后续 Agent 复用和 debug。
+`self_test_contract` 是开发阶段自测合同，由 ARCHITECTING 或 RFC_RECALIBRATION 先定义，SPRINTING 负责执行并在 implementation doc 填写 `Development Self-Test Report`。开发者不得在开发结束后用现有实现反推自测合同；如果合同缺失、入口不匹配、required gates 未同步或场景无法执行，要先回到 ARCHITECTING/RFC 或把 task 保持为 `BLOCKED`。自测报告不是 TESTING 阶段产物，也不是 debug log、operator log、runbook 或历史流水；它只证明当前模块级可运行交付边界已经能被 Review/Testing 消费。报告必须写 `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`，只有 `PASS` 且所有 scenario 都是 `PASS` 才能关闭当前 development task；`BLOCKED`、`IN_PROGRESS`、`STALE` 可以作为恢复事实存在，但不能作为交接通过。报告还必须记录 `Module Key Test Path`：从本地启动或调用入口开始，执行并完成 `self_test_contract` 中全部自测用例的模块关键测试路径。该路径应覆盖本 task / 本模块承诺的所有可运行入口，以及自测用例实际经过的内部关键路径、关键边界、观察点和可观测完成证据，供后续 Agent 复用和 debug。如果合同包含 `graph_required: true` 或 `module_key_test_graph`，开发者还必须沿该 DAG 执行并在报告中写入实际 `Module Key Test Graph`：节点只记录 entry、checkpoint、branch、scenario、observable_exit 和 evidence pointer，边只记录路径流向；不要把图扩成 runtime 搭建、执行 trace、debug log 或证据正文。
 
-开发阶段交付包含两类产物：实现产物（代码、配置、脚本、测试等）和开发自测产物。`Development Self-Test Report` 是开发阶段产物，不是计划、模板或历史记录。若当前 task 或关联技术方案声明 `self_test_contract.status: "required"`，必须先逐条执行 `self_test_contract.scenarios[]` 和 `self_test_contract.required_gates`，再填写或更新 `Development Self-Test Report`。没有本轮执行过的 runnable entry、内部关键路径、observable exit / artifact / screenshot / response / log 等证据时，不得写 `PASS`，不得完成 task。fallback / diagnostic 在主报告最多一句总结，详细命令、截图过程、UI 操作细节和失败路径进入 `.docs/09_runbooks/**` exploration appendix 或 git history。
+开发阶段交付包含两类产物：实现产物（代码、配置、脚本、测试等）和开发自测产物。`Development Self-Test Report` 是开发阶段产物，不是计划、模板或历史记录。若当前 task 或关联技术方案声明 `self_test_contract.status: "required"`，必须先逐条执行 `self_test_contract.scenarios[]` 和 `self_test_contract.required_gates`，再填写或更新 `Development Self-Test Report`。没有本轮执行过的 runnable entry、内部关键路径、observable exit / artifact / screenshot / response / log 等证据时，不得写 `PASS`，不得完成 task。自测报告只保留交接卡字段：`Report Status`、`Contract Source`、`Module Application Entry`、`Module Key Test Path`、`Scenario Results`、`Executed Gates`、`Observable Exit`、`Current Blocker`、`Testing Handoff Readiness` 和 `Evidence Index Refs`；证据正文、长命令输出、截图过程和 UI 操作细节进入 evidence index、外部 artifact 或 `.docs/09_runbooks/**` exploration appendix。主报告目标几十行，fallback / diagnostic 最多一句总结，不写 `Actual Evidence` 正文字段。
 
-高风险 runtime/live/remote-operator task 必须维护恢复优先级。若 `evidence_level.required` 是 `external_provider_live`、`deployed_runtime`、`business_handoff_ready`，或 `target_runtime_environment.kind` 是 `cloud_vm`、`managed_service`、`browser`、`worker`，`plan.yaml` 顶层必须有 `resume_capsule`，并在路径选择结论变化时立即更新：`state`、`canonical_path`、`next_step`、`blocker`、`last_passed_gate`、`do_not_retry` 和 `recovery_refs`。`working_notes` 只保留短恢复备注，目标 5-8 条且不得超过 8 条；canonical operator path 写入 `.docs/09_runbooks/**` runbook，并在 implementation doc 写一个短的 `Current Operator Path` 链接 runbook、credential reference name、command/UI channel 和 do-not-retry summary。证据正文只在 evidence 文件或外部系统，失败探索写入 exploration appendix。不要把 A/B/C 路径探索流水混进 implementation doc 主线或 scenario evidence。
+高风险 runtime/live/remote-operator task 必须维护恢复优先级。若 `evidence_level.required` 是 `external_provider_live`、`deployed_runtime`、`business_handoff_ready`，或 `target_runtime_environment.kind` 是 `cloud_vm`、`managed_service`、`browser`、`worker`，`plan.yaml` 顶层必须有 `resume_capsule`，并在路径选择结论变化时立即更新：`state`、`canonical_path`、`next_step`、`blocker`、`last_passed_gate`、`do_not_retry` 和 `recovery_refs`。凡会改变下一步动作的判断，必须 promoted 到 `resume_capsule.do_not_retry`、runbook 顶部 `Hard Constraints` 或 implementation doc 的短 `Current Operator Path`，不能只埋在 evidence、notes、exploration appendix 或长 implementation doc 中。例如 PC 微信已确认登录后再次出现 QR 时，先判定 `rule_assumption_gap` vs `operator_induced_logout_or_session_reset`，不得直接进入重新扫码流程。validator 会扫描 `working_notes`、implementation doc 和 runbook 中的 session / QR / canonical path / do-not-retry 类关键判断；只在 notes/evidence 中出现而未 promoted 会 fail。`working_notes` 只保留短恢复备注，目标 5-8 条且不得超过 8 条；canonical operator path 写入 `.docs/09_runbooks/**` runbook，并在 implementation doc 写一个短的 `Current Operator Path` 链接 runbook、credential reference name、command/UI channel、hard constraints 和 do-not-retry summary。证据正文只在 evidence index 或外部系统，失败探索写入 exploration appendix。不要把 A/B/C 路径探索流水混进 implementation doc 主线或 scenario evidence。
 
 页面类任务在开发阶段必须启动 dev server 或等价预览入口，并用浏览器、Playwright、截图或等价方式验证页面可加载、主入口可访问、核心按钮/表单/跳转可用、没有明显报错或空白页。API/CLI/worker/RPA/service/agent/runtime 类任务必须记录实际启动或调用命令、endpoint、worker command、dry-run/live preflight、health/status 或 server action，以及可观察的 response、队列 item、审计日志、文件产物、发送结果、错误码或 PASS/BLOCKED 结果。
 
@@ -75,7 +75,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 每个 open task 都必须在 `plan.yaml` 中包含完整执行合同：
 
 1. `current_task_id` 指向正在执行的 open task。
-2. open task 直接声明 `phase: "SPRINTING"`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `implementation_doc`；runtime/app/provider/live 类 task 还必须声明 `evidence_level`、`target_runtime_environment` 和 `self_test_contract`。`self_test_contract.required_gates` 必须同步出现在 task `required_gates`，`self_test_contract.module_key_test_path` 必须描述从本地启动或调用入口开始，到完成所有自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径。
+2. open task 直接声明 `phase: "SPRINTING"`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `implementation_doc`；runtime/app/provider/live 类 task 还必须声明 `evidence_level`、`target_runtime_environment` 和 `self_test_contract`。`self_test_contract.required_gates` 必须同步出现在 task `required_gates`，`self_test_contract.module_key_test_path` 必须描述从本地启动或调用入口开始，到完成所有自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径；若 `graph_required: true`，`module_key_test_graph` 是复杂路径的 canonical detail，不能用长文字路径替代。
 3. 如果 open task 是由 `plan.draft.yaml.tasks[]` promote 而来，创建正式 `TASK-*` 和删除源 draft 必须发生在同一次状态更新中；正式 task 的恢复现场只保存在 `plan.yaml`。
 4. 任务执行中只保留恢复所需的简短 `working_notes`，目标 5-8 条且不得超过 8 条；high-risk runtime/live task 用 `resume_capsule` 保存恢复卡片，并链接 runbook / evidence index / exploration appendix。
 5. gate、implementation doc、`.docs/INDEX.md` 和 `overview.md` 完成后，在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit。
@@ -113,7 +113,8 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 - [ ] 当前任务仍然是单一清晰的执行单元。
 - [ ] 技术方案或 task 承诺的 API/CLI/adapter/worker/provider、配置契约、输出/副作用和 fixture/live 边界已可运行并写入 implementation doc，或已明确 `BLOCKED`/后续 dev task。
 - [ ] 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"`，已逐条执行当前 `self_test_contract.scenarios[]` 和 `self_test_contract.required_gates`，并在 implementation doc `Development Self-Test Report` 写入 `Report Status`、本轮 contract source、scenario results、executed gates、runnable entry、内部关键路径、observable exit/evidence、Module Key Test Path、missing/blockers 和 Testing Handoff Readiness，且 `Report Status: PASS`、所有 scenario 都是 `PASS`。
+- [ ] 如果当前 task 有 `self_test_contract.status: "required"`，已逐条执行当前 `self_test_contract.scenarios[]` 和 `self_test_contract.required_gates`，并在 implementation doc `Development Self-Test Report` 写入 `Report Status`、本轮 contract source、Module Application Entry、scenario results、executed gates、Module Key Test Path、Observable Exit、Current Blocker、Testing Handoff Readiness 和 Evidence Index Refs，且 `Report Status: PASS`、所有 scenario 都是 `PASS`。
+- [ ] 如果 `self_test_contract.graph_required: true` 或存在 `module_key_test_graph`，已在 `Development Self-Test Report` 写入实际 `Module Key Test Graph`，且 graph 覆盖入口、scenario、observable exit 和 evidence refs。
 - [ ] 如果当前 task 是 high-risk runtime/live/remote-operator 工作，`resume_capsule` 已更新为 5-8 条恢复事实，`recovery_refs` 链接 implementation doc 和 `.docs/09_runbooks/**` runbook/evidence，implementation doc 已填写短的 `Current Operator Path` 和分层 `Gate Breakdown`。
 - [ ] 如果 task 要求 `business_handoff_ready`，implementation doc 已写入 Testing Handoff Contract，包含入口、配置、初始化/health、输入样例、预期出口、清理方式和证据等级。
 - [ ] 如果当前 task 来自 `plan.draft.yaml.tasks[]`，源 draft 已在 promote 时从 draft 列表删除。

package/assets/skills/pjsdlc_implementation_doc/SKILL.md

@@ -21,7 +21,7 @@ implementation doc 只写长期实现事实，不写完整操作日记。对于
 
 如果模块包含或承诺可运行系统边界，implementation doc 必须记录 runnable entry/exit：API/CLI/server route/service/agent/runtime/adapter/worker/provider 的调用方式、初始化方式、配置契约、输入来源、输出或副作用、fixture/live 模式边界，以及哪些真实外部执行器尚未实现。还必须在 `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`；`Basic Self-test Evidence` 应指向已执行的 `Development Self-Test Report`。确实没有应用入口时，`Not applicable` 必须写清原因。不能把未来才会实现的入口写成当前事实，不能把 provider smoke、fixture smoke、fake adapter 或 one-shot smoke 单独写成 application readiness。如果 task 要求 `business_handoff_ready`，还必须写 Testing Handoff Contract，包含入口、配置、初始化/health、输入样例、预期出口、清理/reset/幂等说明和证据等级。
 
-如果当前 task 有 `self_test_contract.status: "required"`，implementation doc 必须填写 `Development Self-Test Report`，把设计/RFC 阶段定义的自测合同执行完成：记录 `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`、contract source、每个 scenario 的结果、实际执行入口、实际出口、证据位置或命令输出、executed gates、Module Key Test Path、missing/blockers 和 Testing Handoff Readiness。`Development Self-Test Report` 不是 debug log、operator log、runbook 或历史流水；fallback / diagnostic 在主报告最多一句总结，详细命令、截图过程、UI 操作细节和失败路径进入 exploration appendix 或 git history。High-risk runtime/live task 还必须写 `Current Operator Path` 和 `Gate Breakdown`，把 canonical operator path、runbook link、credential reference name、command/UI channel、do-not-retry summary 以及 local gate、cloud/service gate、executor/operator readiness、live smoke / handoff 分层记录，不能只写一个大 `validate-dev PASS`。`Development Self-Test Report` 只能记录当前 task 本轮实际执行后的结果；不得用历史报告、模板字段、代码阅读或无关通用 gate 替代本轮 self-test scenario 执行。`Module Key Test Path` 必须说明从本地启动或调用入口开始，执行并完成 `self_test_contract` 中全部自测用例的模块关键测试路径。该路径应覆盖本 task / 本模块承诺的所有可运行入口，以及自测用例实际经过的内部关键路径、关键边界、观察点和可观测完成证据，供后续 Agent 复用和 debug。任何 scenario 非 `PASS`，或 `Report Status` 为 `BLOCKED`、`IN_PROGRESS`、`STALE` 时，不得把开发 task 写成完成。
+如果当前 task 有 `self_test_contract.status: "required"`，implementation doc 必须填写 `Development Self-Test Report`，把设计/RFC 阶段定义的自测合同执行完成：记录 `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`、contract source、`Module Application Entry`、每个 scenario 的结果、executed gates、`Module Key Test Path`、`Observable Exit`、`Current Blocker`、`Testing Handoff Readiness` 和 `Evidence Index Refs`。`Development Self-Test Report` 是几十行交接卡，不是 debug log、operator log、runbook、evidence dump 或历史流水；不要写 `Actual Evidence` 正文字段。fallback / diagnostic 在主报告最多一句总结，详细命令、截图过程、UI 操作细节和失败路径进入 evidence index、exploration appendix 或 git history。High-risk runtime/live task 还必须写 `Current Operator Path` 和 `Gate Breakdown`，把 canonical operator path、runbook link、credential reference name、command/UI channel、hard constraints、do-not-retry summary 以及 local gate、cloud/service gate、executor/operator readiness、live smoke / handoff 分层记录，不能只写一个大 `validate-dev PASS`。凡会改变下一步动作的判断，必须 promoted 到 `plan.yaml#resume_capsule.do_not_retry` 或 runbook 顶部 `Hard Constraints`，不能只留在 evidence 或 appendix。`Development Self-Test Report` 只能记录当前 task 本轮实际执行后的结果；不得用历史报告、模板字段、代码阅读或无关通用 gate 替代本轮 self-test scenario 执行。`Module Key Test Path` 必须说明从本地启动或调用入口开始，执行并完成 `self_test_contract` 中全部自测用例的模块关键测试路径。该路径应覆盖本 task / 本模块承诺的所有可运行入口，以及自测用例实际经过的内部关键路径、关键边界、观察点和可观测完成证据，供后续 Agent 复用和 debug。如果 task contract 设置 `graph_required: true` 或包含 `module_key_test_graph`，还必须记录实际 `Module Key Test Graph`，用轻量 DAG 展示 entry、checkpoint、branch、scenario、observable_exit 与 evidence refs；图只放路径骨架和证据指针，不放执行 trace、命令输出、截图过程、operator log、debug log、runbook 正文或失败探索。任何 scenario 非 `PASS`，或 `Report Status` 为 `BLOCKED`、`IN_PROGRESS`、`STALE` 时，不得把开发 task 写成完成。
 
 ## 输入
 
@@ -53,7 +53,7 @@ implementation doc 只写长期实现事实，不写完整操作日记。对于
 3. 与技术方案的偏移必须明确记录，即便该偏移是合理的。
 4. runnable entry/exit、配置契约和 fixture/live 边界必须记录当前事实；缺失项写入 `未覆盖（Not covered）` 或方案偏移。
 5. `Development Evidence` 必须包含 task 合同要求的证据等级、目标运行环境、实际可调用入口、可观察出口、初始化方式、配置契约、测试交接状态、缺失 runtime 边界和开发自测证据；页面类任务记录 dev server/page URL 与 browser check，API/CLI/worker/RPA/service/agent/runtime 类任务记录 startup/invocation command、endpoint/health/status 与 response/output/side effect。
-6. `Development Self-Test Report` 必须记录 `Report Status`、当前 task 本轮执行 `self_test_contract` 中全部 scenario 和 required gates 后的结果，并记录从本地启动或调用入口开始，到完成所有自测用例的 `Module Key Test Path`；路径必须覆盖本 task / 本模块承诺的所有可运行入口、内部关键路径、关键边界、观察点和完成证据，不能只补一句 smoke 结果，也不能复用历史 PASS、模板字段、代码阅读或无关通用 gate 作为本轮证据。
+6. `Development Self-Test Report` 必须记录 `Report Status`、当前 task 本轮执行 `self_test_contract` 中全部 scenario 和 required gates 后的结果，并记录从本地启动或调用入口开始，到完成所有自测用例的 `Module Key Test Path`；路径必须覆盖本 task / 本模块承诺的所有可运行入口、内部关键路径、关键边界、观察点和完成证据，不能只补一句 smoke 结果，也不能复用历史 PASS、模板字段、代码阅读或无关通用 gate 作为本轮证据。若 contract 包含 `module_key_test_graph` 或 `graph_required: true`，报告还必须记录实际 `Module Key Test Graph`。
 7. 测试覆盖必须列出具体测试，或明确记录覆盖缺口。
 8. 文档粒度保持在模块、子系统或核心数据流级别；不要默认按 task 建文档，也不要写成跨全项目的巨型百科。
 
@@ -65,8 +65,9 @@ implementation doc 只写长期实现事实，不写完整操作日记。对于
 - [ ] 核心数据流已说明。
 - [ ] runnable entry/exit、配置契约和 fixture/live 边界已记录，或缺失项已明确标注。
 - [ ] `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`、contract source、scenario results、executed gates、Module Key Test Path、actual evidence、missing/blockers 和 Testing Handoff Readiness。
-- [ ] 如果当前 task 是 high-risk runtime/live/remote-operator 工作，implementation doc 主线只保留实现事实、`Current Operator Path` 和恢复链接，`Gate Breakdown` 已分层记录，本轮失败探索已隔离到 exploration appendix。
+- [ ] 如果当前 task 有 `self_test_contract.status: "required"`，`Development Self-Test Report` 已记录 `Report Status`、contract source、Module Application Entry、scenario results、executed gates、Module Key Test Path、Observable Exit、Current Blocker、Testing Handoff Readiness 和 Evidence Index Refs。
+- [ ] 如果 contract 包含 `module_key_test_graph` 或 `graph_required: true`，`Development Self-Test Report` 已记录实际 `Module Key Test Graph`，且图内只有路径骨架和 evidence pointer。
+- [ ] 如果当前 task 是 high-risk runtime/live/remote-operator 工作，implementation doc 主线只保留实现事实、短 `Current Operator Path`、hard constraints 和恢复链接，`Gate Breakdown` 已分层记录，本轮失败探索已隔离到 exploration appendix。
 - [ ] `business_handoff_ready` task 已记录 Testing Handoff Contract。
 - [ ] 已判断 implementation doc 的语义切片边界。
 - [ ] 方案偏移和测试覆盖已记录。

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,7 @@ 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`。
 
 测试设计和回归证据产出本身也是 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 的旧测试结果。
 
@@ -67,7 +67,7 @@ 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。
@@ -87,7 +87,7 @@ 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`。