agent-project-sdlc 0.1.11 → 0.1.13

package/README.md

@@ -76,10 +76,22 @@ The CLI does not promise to automatically launch Codex agents. Workers do not ne
 
 Every stage's agent work is plan-controlled. Conversational PRD or design creation, existing document slicing, fact-source-based synthesis, development, review, testing, release preparation and RFC recalibration should create or resume one small `TASK-*` task in `plan.yaml` with a valid `phase`, write the current task's `result_docs` or `implementation_doc`, update indexes/overviews, run `validate-plan`, and remove the task after completion. Phase exit validators reject remaining open tasks.
 
+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.
+
 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 changes after `SPRINTING` still use RFC recalibration.
 
 `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.
 
+SPRINTING Definition of Done includes runnable entry/exit boundaries. API, CLI, server route, adapter, worker, provider, config-contract and fixture/live boundaries promised by a technical plan or task must be implemented or marked `BLOCKED` during development. REVIEWING treats missing entry/exit as blocking, and TESTING only exercises existing entrypoints; it must not add product runtime, bootstrap, provider adapter, deploy code or package runtime scripts.
+
+`validate-test` keeps its command name as the TESTING phase gate. The canonical TESTING deliverable is `.docs/07_test/TEST_REPORT.md`, which records test matrix, regression evidence, runnable entry/exit coverage, coverage gaps and final decision. Legacy `.docs/07_test/TEST_PLAN.md` remains accepted for existing projects, but new test evidence should use `TEST_REPORT.md`.
+
+## ADR And Memory Boundaries
+
+`.docs/05_decisions/` stores ADRs, or Architecture Decision Records. ADRs answer why a key architecture choice was made instead of another option. Architecture and tech plan slices may include local design rationale; create an ADR when a decision has real alternatives, affects multiple modules or stages, is likely to be challenged later, or would be expensive to reverse.
+
+`<harnessRoot>/state/memory.md` is only a short cross-stage reminder and navigation surface. It answers what an agent should remember next time and where to find the source. Memory may link to ADRs, PRDs, tech plans or implementation docs; full context, alternatives, tradeoffs and long-term consequences belong in `.docs/05_decisions/` ADRs or other formal `.docs/**` fact sources.
+
 ## Common Commands
 
 ```sh

package/assets/agents/AGENTS_CORE.md

@@ -34,10 +34,12 @@
 - `current_phase` 只保存在 `lifecycle.yaml`；不要在 `plan.yaml`、`plan.draft.yaml` 或 `parallel_execution` 中重复保存当前阶段。
 - 新建任务统一使用 `TASK-*` id，并通过 `phase` 标明属于 `REQUIREMENT_GATHERING`、`ARCHITECTING`、`SPRINTING`、`REVIEWING`、`TESTING`、`RELEASING` 或 `RFC_RECALIBRATION`；历史 `PRD-*`、`DES-*`、`DEV-*` 只作为兼容旧记录和旧提交的 provenance。
 - `next_task_sequence` 记录下一个可分配的 `TASK-*` 序号，避免删除历史 task 后发生 id 冲突。
-- 文档、Review、测试、发布和 RFC 类 task 使用 `result_docs` 指向本 task 产出的 PRD、architecture、tech plan、ADR、review report、test plan、release note、RFC 或 `plan.draft.yaml`；开发 task 使用 `implementation_doc` 指向模块级实现事实。
+- 文档、Review、测试、发布和 RFC 类 task 使用 `result_docs` 指向本 task 产出的 PRD、architecture、tech plan、ADR、review report、test report、release note、RFC 或 `plan.draft.yaml`；开发 task 使用 `implementation_doc` 指向模块级实现事实。
 - task 完成并写入或更新相关事实源后，从 `plan.yaml` 的 `tasks` 列表移除该 task；不要长期保留 done/cancelled task 摘要。
 - `plan.draft.yaml` 是架构阶段生成的计划草案，不自动覆盖 `plan.yaml`。
 - `plan.draft.yaml` 不保存 `current_phase` 或 `current_task_id`，只保存待采用的 task 草案和必要的 `next_task_sequence`。
+- 通用规则：任何阶段或工作流如果把 draft task promote 成 `plan.yaml` 中的正式 `TASK-*`，必须同次从源 draft queue 删除该 draft；draft queue 永远表示尚未采用的草案，不承担完成历史。
+- 当前内置 draft queue 只有 `plan.draft.yaml.tasks[]`，默认用于 `ARCHITECTING` 产出开发草案、`SPRINTING` 消费开发草案。
 - 不维护 checkpoint 文件；任务现场只存在于 open task 的 plan 条目里。
 - 历史动作记录以 git commit 为准，产物结果以模块、子系统或核心数据流级 implementation doc 为准。
 - `SPRINTING` 阶段每完成一个 task，先在 task 仍位于 `plan.yaml` 时创建 task implementation commit；随后再从 `plan.yaml` 移除该 task 并创建 task completion ledger commit。两段提交 push 成功前不进入下一个 task。
@@ -181,12 +183,12 @@ Parallel Execution 是可选协作协议，不是默认模式，也不是 CLI
 - `/rfc <file>`：挂起当前流程并进入 RFC recalibration。
 - `/prd`：在 `REQUIREMENT_GATHERING` 创建或选择一个最小 `TASK-*` task，澄清需求或切片文档，并只更新当前 task 对应的 PRD、验收标准、open questions、`.docs/INDEX.md` 和 overview；如果当前是 `ARCHITECTING` 且尚未进入开发，可先回到 `REQUIREMENT_GATHERING`。
 - `/design`：在 `ARCHITECTING` 创建或选择一个最小 `TASK-*` task，基于 PRD 生成或切分当前 task 对应的 architecture、tech plan 和 `plan.draft.yaml`。
-- `/dev`：在 `SPRINTING` 创建或选择下一个最小 `TASK-*` development task，执行一个 task，跑 gate，更新模块级 implementation doc，按两段 commit/push 闭环后停止。
-- `/devloop`：在 `SPRINTING` 连续运行 `/dev` 循环，直到没有明确可创建/执行的任务，或遇到需求、架构、allowed_paths、gate、commit/push blocker。
+- `/dev`：在 `SPRINTING` 创建或选择下一个最小 `TASK-*` development task；如果从 `plan.draft.yaml.tasks[]` promote draft，必须同次消费并删除该 draft；随后执行一个 task，跑 gate，更新模块级 implementation doc，按两段 commit/push 闭环后停止。
+- `/devloop`：在 `SPRINTING` 连续运行 `/dev` 循环，直到 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可执行任务，或遇到需求、架构、allowed_paths、gate、commit/push blocker。
 - `/syncdocs`：同步 `.docs/INDEX.md` 与当前文档事实源。
 - `/overview`：运行 `make docs-overview`，刷新 `.docs/<stage>/overview.md` 派生视图。
 - `/review`：运行只读 Review 工作流。
-- `/test`：运行测试计划和验证工作流。
+- `/test`：运行测试报告和验证工作流。
 
 ## 阶段流转
 

package/assets/docs/README.md

@@ -97,10 +97,24 @@ npx sdlc-harness init --adopt
 
 Agent 会读取 `<harnessRoot>/state/lifecycle.yaml` 和 `<harnessRoot>/state/plan.yaml`，再按当前阶段选择对应 workflow skill、产物和 gate。任何阶段的 Agent 主任务都不是一次性长生成：产品方案、技术方案、文档切片、基于上一阶段事实源生成、Review、测试、发布和 RFC 处理，都应先落成一个最小 `TASK-*` open task，并设置对应 `phase`；当前轮只执行一个 task，写入 `result_docs` 或 `implementation_doc`、更新索引和 overview，运行 `make validate-plan`，任务完成后再从 `plan.yaml` 移除。
 
+通用规则是：任何阶段或工作流如果把 draft task promote 成 `plan.yaml` 中的正式 `TASK-*`，必须在同一次状态更新里从源 draft queue 删除该 draft；正式 task 的恢复现场只保存在 `plan.yaml`，完成历史由 implementation docs、git/PR/CI 记录承担。当前 Harness 内置的 draft queue 只有 `plan.draft.yaml.tasks[]`，它表示尚未采用的开发草案；`/devloop` 只有在 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可执行任务时，才把开发队列视为耗尽。
+
+技术方案阶段需要产出 `plan.draft.yaml`，是为了解决跨阶段交接和当前执行队列纯净性的冲突。`ARCHITECTING` 必须在进入开发前证明方案可以拆成具体、可验证的开发单元，包括修改范围、gate、implementation doc 和执行顺序；但这些未来开发 task 如果直接进入 `plan.yaml`，会和当前架构阶段 task 混在一起，让阶段 gate 无法区分“架构任务未完成”和“下一阶段任务已预拆”。因此开发任务先作为 draft 暂存，进入 `SPRINTING` 后再逐个 promote 成正式 `TASK-*`。其它阶段默认根据上一阶段已经稳定的事实源即时创建当前阶段 task，只有当某个阶段也需要提前为后续阶段生成具体执行任务时，才应引入同类 draft queue。
+
 在尚未进入开发前，`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。
 
 `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。
 
+SPRINTING 的 Definition of Done 包含可运行入口/出口：技术方案或 task 承诺的 API、CLI、server route、adapter、worker、provider、配置契约和 fixture/live 边界必须在开发阶段实现或明确 `BLOCKED`。REVIEWING 会把缺少入口/出口作为阻断项；TESTING 只调用既有入口做输入输出验证，不能新增 product runtime、bootstrap、provider adapter、deploy 或 package runtime script。
+
+`validate-test` 仍然是 TESTING 阶段 gate 名称。TESTING 的 canonical 产物是 `.docs/07_test/TEST_REPORT.md`，记录 test matrix、regression evidence、runnable entry/exit coverage、coverage gaps 和 final decision；历史 `.docs/07_test/TEST_PLAN.md` 只作为 existing project 的 legacy alias 兼容，新测试证据应使用 `TEST_REPORT.md`。
+
+### ADR 与 Memory 的边界
+
+`.docs/05_decisions/` 保存 ADR（Architecture Decision Record）。ADR 是软件工程中常见的架构决策记录实践，用来回答“为什么当时选择这个方案，而不是别的方案”。architecture / tech plan 可以写当前方案里的局部设计理由；如果一个决定有备选方案、影响多个模块或阶段、未来容易被质疑，或修改成本高，就应写成 ADR，记录背景、备选方案、理由、后果和替代关系。
+
+`<harnessRoot>/state/memory.md` 只做跨阶段快捷提示和导航，回答“下次进来要先记住什么、去哪里找”。memory 可以链接到 ADR、PRD、tech plan 或 implementation doc；完整背景、备选方案、取舍和长期后果放在 `.docs/05_decisions/` ADR 或其它正式 `.docs/**` 事实源里。
+
 ### Workflow skill 如何生效
 
 `<harnessRoot>/skills/<name>/SKILL.md` 是 Harness 的 workflow skill 事实源，也是稳定的 hard file index。它有两种使用方式：
@@ -156,7 +170,7 @@ Harness CLI v1 不承诺自动启动 Codex agent，也不要求 worker 之间通
 | `/prd` | 完善产品方案 | 在需求阶段创建或选择一个最小 `TASK-*` task；如果当前仍在架构阶段且未进入开发，可先回到 `REQUIREMENT_GATHERING` 修改 PRD |
 | `/design` | 设计技术方案 | 在架构阶段创建或选择一个最小 `TASK-*` task，生成或切分当前 architecture / tech plan / `plan.draft.yaml` 产物 |
 | `/dev` | 做下一个任务 | 创建或选择下一个最小 `TASK-*` development task，完成一个 task 闭环后停止 |
-| `/devloop` | 开始循环：写任务，执行任务 | 连续运行 `/dev`，直到没有明确任务或遇到 blocker |
+| `/devloop` | 开始循环：写任务，执行任务 | 连续运行 `/dev`，直到 `plan.yaml` 和 `plan.draft.yaml` 都没有明确任务或遇到 blocker |
 | `/test` | 跑一下当前验证 | 运行当前 task 或阶段对应 gate |
 | `/review` | 准备 review | 进入只读 Review workflow |
 
@@ -212,12 +226,14 @@ make docs-overview
 |---|---|
 | `<harnessRoot>/state/lifecycle.yaml` | 当前生命周期阶段和 active skill |
 | `<harnessRoot>/state/plan.yaml` | 当前和未来 task 的短期执行计划 |
+| `<harnessRoot>/state/memory.md` | 跨阶段稳定知识的摘要和正式事实源链接 |
 | `.docs/01_product/` | PRD、用户场景、验收标准 |
 | `.docs/02_architecture/` | 架构边界和高层设计 |
 | `.docs/03_tech_plan/` | 技术方案、接口契约、任务拆分 |
 | `.docs/04_implementation/` | 模块、子系统和核心数据流的真实实现事实 |
+| `.docs/05_decisions/` | ADR，长期关键决策及其背景、备选方案、理由和后果 |
 | `.docs/06_review/` | Review 报告 |
-| `.docs/07_test/` | 测试计划和回归记录 |
+| `.docs/07_test/` | 测试报告、测试矩阵、回归证据和覆盖缺口 |
 | `.docs/08_release/` | 发布记录和回滚方案 |
 | `.docs/rfc/` | 需求变更和影响分析 |
 

package/assets/make/sdlc-harness.mk

@@ -12,9 +12,9 @@ help:
 	@echo "  make validate-plan       校验 plan.yaml task 合同，允许当前 open task"
 	@echo "  make validate-pm         校验产品需求产物"
 	@echo "  make validate-design     校验架构设计、技术方案和任务草案"
-	@echo "  make validate-dev        校验 sprint 任务状态、路径、代码 gate 和实现文档"
+	@echo "  make validate-dev        校验 sprint 任务状态、draft 消费、路径、代码 gate 和实现文档"
 	@echo "  make validate-review     校验 Review report"
-	@echo "  make validate-test       校验 regression/test plan"
+	@echo "  make validate-test       校验 regression/test report"
 	@echo "  make validate-release    校验 release note、smoke result 和 rollback plan"
 	@echo "  make validate-rfc        校验 RFC 产物并运行完整回归入口"
 
@@ -49,6 +49,7 @@ validate-design:
 
 validate-dev:
 	$(PYTHON) tools/validate_plan.py
+	$(PYTHON) tools/validate_dev_state.py
 	$(PYTHON) tools/validate_allowed_paths.py
 	$(MAKE) lint
 	$(MAKE) test-current-domain

package/assets/policies/allowed_paths.yaml

@@ -27,6 +27,7 @@ phases:
       - ".docs/04_implementation/**"
       - ".docs/INDEX.md"
       - "<harnessRoot>/state/plan.yaml"
+      - "<harnessRoot>/state/plan.draft.yaml"
 
   REVIEWING:
     read_only_source: true

package/assets/policies/gates.yaml

@@ -31,7 +31,7 @@ gates:
 
   validate-dev:
     command: "make validate-dev"
-    purpose: "验证任务状态、allowed_paths、代码检查、测试和实现文档"
+    purpose: "验证任务状态、已消费 draft、allowed_paths、代码检查、测试和实现文档"
     required_for:
       - "SPRINTING"
 

package/assets/policies/phase_contracts.yaml

@@ -45,11 +45,12 @@ phases:
       - "REQUIREMENT_GATHERING"
 
   SPRINTING:
-    goal: "按任务状态执行开发、测试和实现文档沉淀"
+    goal: "按任务状态执行开发、消费已采用草案、测试和实现文档沉淀"
     role: "developer"
     skill: "pjsdlc_dev_sprint"
     inputs:
       - "<harnessRoot>/state/plan.yaml"
+      - "<harnessRoot>/state/plan.draft.yaml"
       - "current open task plan contract"
       - ".docs/01_product/"
       - ".docs/03_tech_plan/"
@@ -57,6 +58,7 @@ phases:
       - "src/"
       - "tests/"
       - ".docs/04_implementation/"
+      - "<harnessRoot>/state/plan.draft.yaml"
     gates:
       - "make validate-dev"
     next: "REVIEWING"
@@ -79,7 +81,7 @@ phases:
     next: "TESTING"
 
   TESTING:
-    goal: "形成测试矩阵并完成回归验证"
+    goal: "形成测试报告、测试矩阵、回归证据和覆盖缺口结论"
     role: "tester"
     skill: "pjsdlc_tester"
     inputs:

package/assets/skills/pjsdlc_architect_design/SKILL.md

@@ -17,6 +17,8 @@ description: Use during ARCHITECTING to create architecture docs, technical plan
 
 架构产物应区分稳定边界和实现计划：architecture slice 记录领域边界、子系统、关键风险和长期约束；tech plan slice 记录接口契约、数据模型、模块方案、任务拆分和 gate。不要把重大架构变化藏在 task 描述里。
 
+ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问题。architecture / tech plan 可以记录当前方案的局部设计理由；如果一个决定有明确备选方案、影响多个模块或阶段、未来容易被质疑、修改成本高，或需要保留 supersede 关系，就写入 `.docs/05_decisions/`。`<harnessRoot>/state/memory.md` 只保留这类决策的简短提示和链接，不承载完整背景、备选方案、取舍和后果。
+
 架构和技术方案产出本身也是 workflow task，而不是一次性长文档生成。无论来源是对话式设计、既有完整技术方案切片，还是根据 PRD/architecture 事实源生成新方案，都要先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "ARCHITECTING"`，只完成当前 `current_task_id` 对应的一片 architecture / tech plan / ADR / `plan.draft.yaml` 产物。不要在一个任务里连续创建大量设计文件；如果需要多个 slices，先拆出 pending tasks，当前轮只执行一个 task。
 
 如果在 `ARCHITECTING` 中发现 PRD 缺失、验收标准不清或产品边界需要调整，且项目尚未进入 `SPRINTING`，不要用架构文档替代产品事实。先收尾或移除当前 open design task，再请 Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 回到 PM/PRD 工作流修改 `.docs/01_product/**`。进入 `SPRINTING` 后的需求变化走 RFC workflow。
@@ -45,6 +47,7 @@ description: Use during ARCHITECTING to create architecture docs, technical plan
 - `.docs/02_architecture/` 按领域边界、子系统、跨模块架构问题或关键技术风险切片。
 - `.docs/03_tech_plan/` 按可实现范围、接口契约、数据模型、模块方案或任务组切片。
 - `.docs/05_decisions/` 按单个架构决策切片，即一份 ADR 只记录一个 durable decision。
+- 写 ADR 的判断标准：存在备选方案、影响多个产物或阶段、未来容易被质疑、修改成本高、或需要说明 `Supersedes / Superseded by` 时，写 ADR；只影响当前模块内部实现细节、且理由已能在 architecture / tech plan 中局部说明时，不单独写 ADR。
 - 如果一个技术方案跨越多个独立模块，应拆成多个 tech plan slice，并在 `plan.draft.yaml` 中分别引用。
 - `plan.draft.yaml` 中每个开发 draft task 必须在 `docs.tech_plan` 引用已有 `.docs/03_tech_plan/` slice；多个开发 draft task 默认应引用不同的 primary tech plan slice，不能用一个总纲 tech plan 覆盖全部模块任务。
 - `overview.md` 是 generated artifact，不算 architecture / tech plan deliverable，也不能作为 `docs.tech_plan` 引用。

package/assets/skills/pjsdlc_dev_sprint/SKILL.md

@@ -15,7 +15,9 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 开始编码前，先确认当前 open task 是否完整，修改范围是否覆盖必要文件，验收标准是否能被测试或 gate 验证。如果发现任务边界、产品行为或技术方案不清晰，要停下来说明 blocker、给出可能解释和推荐下一步，而不是扩大范围继续写。
 
-`/dev` 和 `/devloop` 是开发阶段的两个入口。`/dev` 创建或选择下一个最小 `TASK-*` development task，设置 `phase: "SPRINTING"`，并只完成一个 task 闭环后停止。`/devloop` 连续运行 `/dev`，直到技术方案中没有明确可创建/执行的任务，或遇到需求、架构、allowed_paths、gate、commit/push blocker。
+开发阶段的 Definition of Done 包含可运行的系统入口/出口。凡技术方案或 task 承诺 API、CLI、server route、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，当前实现必须提供对应入口、调用方式、输出/副作用边界和验证方式；如果真实入口/出口尚不可运行，不能把 task 当作完成，也不能把缺口留给 TESTING 补 runtime。Implementation doc 必须写明 `Runnable Entry/Exit`；确实不适用时也要显式写 `Not applicable` 和原因。此时应保留或创建 `BLOCKED`/后续 dev task，或通过 RFC/ARCHITECTING 处理边界变更。
+
+`/dev` 和 `/devloop` 是开发阶段的两个入口。`/dev` 创建或选择下一个最小 `TASK-*` development task，设置 `phase: "SPRINTING"`，并只完成一个 task 闭环后停止。通用规则是从任何 draft queue promote 正式 `TASK-*` 时都必须同次消费源 draft；当前开发阶段的内置 draft queue 是 `plan.draft.yaml.tasks[]`，因此如果这个 task 来自 `plan.draft.yaml.tasks[]`，promote 时必须同次删除源 draft，避免已采用草案继续显示为 `pending`。`/devloop` 连续运行 `/dev`，直到 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可创建/执行的任务，或遇到需求、架构、allowed_paths、gate、commit/push blocker。
 
 实现时遵循小步闭环：先检查 `git status`，确认工作区没有未归属到当前 task 的脏变更；再定位相关代码和测试，做必要修改，运行 gate，修复失败，写入或更新相关 implementation doc 并刷新文档派生视图。此时先不要从 `plan.yaml` 移除当前 task，要在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit；随后再移除 task，创建 task completion ledger commit，并 push 两个 commit。不要顺手重构、重排格式或处理无关问题；如果发现无关风险，只记录或报告。
 
@@ -25,6 +27,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 - `<harnessRoot>/state/lifecycle.yaml`
 - `<harnessRoot>/state/plan.yaml`
+- `<harnessRoot>/state/plan.draft.yaml`
 - 当前任务关联的 PRD 和技术方案
 - 当前源码和测试文件
 
@@ -34,7 +37,9 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 - 当前 task `allowed_paths` 范围内的测试改动
 - `.docs/04_implementation/` 下相关模块、子系统或核心数据流的 implementation doc
 - 当前 task `working_notes` 或 implementation doc `Verification` 中的 gate evidence
+- implementation doc 中的 runnable entry/exit、配置契约和 fixture/live 边界事实
 - 更新后的 `<harnessRoot>/state/plan.yaml`
+- 如果本轮 promote draft，更新后的 `<harnessRoot>/state/plan.draft.yaml`
 - 更新后的 `.docs/INDEX.md`
 - 当前 task 移除前创建的 task implementation commit
 - 从 `plan.yaml` 移除当前 task 后的 task completion ledger commit
@@ -51,8 +56,8 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 - 本 Skill 不直接重切 PRD 或 tech plan；如果发现上游语义边界错误，进入 `BLOCKED`、创建 RFC，或请求回到 `ARCHITECTING`。
 - gate 通过后调用 `pjsdlc_implementation_doc`，由该 Skill 按真实实现更新或新增 `.docs/04_implementation/` 模块级 slice。
 - 如果一个任务实际变成多个独立实现边界，应停止扩大范围，拆分后续任务或回到任务规划。
-- `/dev` 是单任务执行入口：没有 open task 时，先根据 PRD、architecture、tech plan 和 `plan.draft.yaml` 创建一个最小 `TASK-*` open task；已有 open task 时，直接执行该 task；完成后停止。
-- `/devloop` 是连续执行入口：每完成一个 task 并 push 两段提交后，重新读取 lifecycle、plan、PRD、architecture 和 tech plan，再决定是否创建/执行下一个最小 task；没有明确任务或出现 blocker 时停止并报告。
+- `/dev` 是单任务执行入口：没有 open task 时，先根据 PRD、architecture、tech plan 和 `plan.draft.yaml` 创建一个最小 `TASK-*` open task；如果从 `plan.draft.yaml.tasks[]` 采用 draft，必须同次从 draft 列表删除源项；已有 open task 时，直接执行该 task；完成后停止。
+- `/devloop` 是连续执行入口：每完成一个 task 并 push 两段提交后，重新读取 lifecycle、`plan.yaml`、`plan.draft.yaml`、PRD、architecture 和 tech plan，再决定是否创建/执行下一个最小 task；没有 open task 且没有未采用 draft，或出现 blocker 时停止并报告。
 - Parallel Execution 是当前 task 的可选协作方式，不替代 task completion protocol；`SPRINTING` 并行从 lifecycle 的 `current_phase` 和 plan 的 `current_task_id` 推断上下文，不在 `parallel_execution` 内重复保存。
 
 ## Plan Protocol
@@ -61,10 +66,11 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 1. `current_task_id` 指向正在执行的 open task。
 2. open task 直接声明 `phase: "SPRINTING"`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `implementation_doc`。
-3. 任务执行中只保留恢复所需的简短 `working_notes`。
-4. gate、implementation doc、`.docs/INDEX.md` 和 `overview.md` 完成后，在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit。
-5. implementation commit 完成后，再把该 task 从 `plan.yaml` 的 `tasks` 列表移除，并保留/递增 `next_task_sequence`。
-6. 将移除当前 task 后的 `plan.yaml` 提交为 task completion ledger commit，并 `git push` 两个 commit 到当前 upstream branch。
+3. 如果 open task 是由 `plan.draft.yaml.tasks[]` promote 而来，创建正式 `TASK-*` 和删除源 draft 必须发生在同一次状态更新中；正式 task 的恢复现场只保存在 `plan.yaml`。
+4. 任务执行中只保留恢复所需的简短 `working_notes`。
+5. gate、implementation doc、`.docs/INDEX.md` 和 `overview.md` 完成后，在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit。
+6. implementation commit 完成后，再把该 task 从 `plan.yaml` 的 `tasks` 列表移除，并保留/递增 `next_task_sequence`。
+7. 将移除当前 task 后的 `plan.yaml` 提交为 task completion ledger commit，并 `git push` 两个 commit 到当前 upstream branch。
 
 done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认上下文。修 bug、补功能和继续开发时，优先读取当前代码、测试、PRD、技术方案和模块级 implementation doc；历史 task 查询主要看“做了什么、为什么做、影响哪个模块、验证了什么”，task id 和 commit 作为 implementation doc 的 provenance。`allowed_paths`、`required_gates`、临时 `working_notes` 是执行期约束，不作为历史查询 API。只有用户明确要求 forensic/audit/regression 追溯时，才临时使用 git、PR 或 CI 记录。
 
@@ -72,18 +78,18 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 
 1. 一次只执行一个任务。
 2. 开始修改前检查 `git status`；如果存在不属于当前 task 的未提交变更，先完成对应 task 的 commit/push，或报告 blocker，不要混入当前 task。
-3. 只编辑当前 task 的 `allowed_paths` 允许的文件，以及 `SPRINTING` 阶段允许的 Harness 记账文件。
+3. 只编辑当前 task 的 `allowed_paths` 允许的文件，以及 `SPRINTING` 阶段允许的 Harness 记账文件；如果本轮 promote draft，允许同步编辑 `<harnessRoot>/state/plan.draft.yaml` 来消费源 draft。
 4. 必须运行当前 task 的 `required_gates`。
 5. 如果 gate 因代码或测试逻辑失败，在任务范围内修复。
 6. 如果 gate 因基础设施、凭证缺失、产品行为不清或高风险架构变化失败，进入 `BLOCKED`。
 7. gate 通过后调用 `pjsdlc_implementation_doc`。
-8. 只有 gate 通过且 implementation doc 校验通过后，才能把任务标记为 `done`。
+8. 只有 gate 通过、承诺的 runnable entry/exit 已实现或明确 `BLOCKED`，且 implementation doc 校验通过后，才能把任务标记为 `done`。
 9. 任务完成并写入或更新相关 implementation doc、刷新 `overview.md`、记录 gate 后，先创建 task implementation commit；此时不要移除该 task。
 10. task implementation commit 必须发生在 task 移除前；后续默认不要读取其中的执行期字段，历史查询以模块级 implementation doc、RFC、PRD、tech plan 和代码为主。
 11. implementation commit 完成后，从当前 `plan.yaml` 移除该 task，并创建 task completion ledger commit。
 12. 默认不追溯已完成 task 的执行流水；只有显式 forensic/audit/regression 任务才临时查询 git、PR 或 CI 记录。
 13. 两个 commit 后必须 `git push` 到当前 upstream branch；如果没有 remote/upstream、权限或凭证导致无法 push，停止推进并报告 blocker。
-14. `/devloop` 每轮都必须重新读取当前状态，不得在一次上下文中假设 plan、代码或远端状态未变化。
+14. `/devloop` 每轮都必须重新读取当前状态，不得在一次上下文中假设 plan、draft、代码或远端状态未变化。
 15. 只有用户明确要求并行、多 agent 或多 worktree 时，才允许创建 `parallel_execution`；否则不得默认并行。
 16. `runtime_managed` 只在当前 runtime 支持 subagent 时使用；没有该能力时，输出 `user_orchestrated` worker prompt，由用户手动打开对话或 worktree 后粘贴。
 17. worker 不更新主事实源；主 Agent 才能更新 `plan.yaml`、`.docs/INDEX.md`、overview、implementation doc 和最终 gate 证据。
@@ -94,6 +100,8 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 - [ ] 当前 task `required_gates` 已通过，或 blocker 已记录。
 - [ ] open task 在 `plan.yaml` 中包含完整执行合同。
 - [ ] 当前任务仍然是单一清晰的执行单元。
+- [ ] 技术方案或 task 承诺的 API/CLI/adapter/worker/provider、配置契约、输出/副作用和 fixture/live 边界已可运行并写入 implementation doc，或已明确 `BLOCKED`/后续 dev task。
+- [ ] 如果当前 task 来自 `plan.draft.yaml.tasks[]`，源 draft 已在 promote 时从 draft 列表删除。
 - [ ] implementation doc 已生成或更新，并反映相关模块的真实代码。
 - [ ] 如果启用了 `parallel_execution`，worker owned paths、forbidden paths、required gates 和主 Agent 集成结果已记录。
 - [ ] gate 结果已写入 implementation doc `Verification`，必要时当前 task `working_notes` 也记录了恢复现场所需的 gate evidence。

package/assets/skills/pjsdlc_implementation_doc/SKILL.md

@@ -17,6 +17,8 @@ description: Use after development gates pass to update module-level implementat
 
 文档应帮助后来者快速理解：某个模块或核心数据流的当前实现是什么、关键对象/函数职责是什么、行为如何从输入流到输出、测试覆盖了什么、还有什么未覆盖。task id 只作为 provenance，不作为默认切片粒度。
 
+如果模块包含或承诺可运行系统边界，implementation doc 必须记录 runnable entry/exit：API/CLI/server route/adapter/worker/provider 的调用方式、配置契约、输入来源、输出或副作用、fixture/live 模式边界，以及哪些真实外部执行器尚未实现。不能把未来才会实现的入口写成当前事实。
+
 ## 输入
 
 - `<harnessRoot>/state/plan.yaml` 中当前 task 的 `implementation_doc` 路径和 task ID
@@ -45,8 +47,9 @@ description: Use after development gates pass to update module-level implementat
 1. implementation doc 描述当前代码事实，而不是期望中的未来设计。
 2. 每个被记录的文件都应说明它在该模块或数据流中的作用和关键函数/对象。
 3. 与技术方案的偏移必须明确记录，即便该偏移是合理的。
-4. 测试覆盖必须列出具体测试，或明确记录覆盖缺口。
-5. 文档粒度保持在模块、子系统或核心数据流级别；不要默认按 task 建文档，也不要写成跨全项目的巨型百科。
+4. runnable entry/exit、配置契约和 fixture/live 边界必须记录当前事实；缺失项写入 `未覆盖（Not covered）` 或方案偏移。
+5. 测试覆盖必须列出具体测试，或明确记录覆盖缺口。
+6. 文档粒度保持在模块、子系统或核心数据流级别；不要默认按 task 建文档，也不要写成跨全项目的巨型百科。
 
 ## 完成检查
 
@@ -54,6 +57,7 @@ description: Use after development gates pass to update module-level implementat
 - [ ] Task ID、commit 和关联产物路径已作为 provenance 记录。
 - [ ] 真实代码结构表已填写。
 - [ ] 核心数据流已说明。
+- [ ] runnable entry/exit、配置契约和 fixture/live 边界已记录，或缺失项已明确标注。
 - [ ] 已判断 implementation doc 的语义切片边界。
 - [ ] 方案偏移和测试覆盖已记录。
 - [ ] `.docs/INDEX.md` 已链接 implementation doc。

package/assets/skills/pjsdlc_manager/SKILL.md

@@ -47,8 +47,8 @@ Parallel Execution 是显式 opt-in：只有用户明确提出“并行”“多
 14. 用户自然语言表达需求或设计变化时，先判断阶段：如果当前是 `ARCHITECTING` 且尚未进入开发，可以说明将回到 `REQUIREMENT_GATHERING` 并用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切回 PM/PRD 工作流；如果当前是 `SPRINTING` 或之后，进入 RFC workflow。
 15. 用户输入 `/prd`，或自然语言要求“完善产品方案”“写 PRD”“文档切片”“我提供信息，你帮我完善产品方案”时，如果 `current_phase` 是 `REQUIREMENT_GATHERING`，调用产品方案工作流；如果 `current_phase` 是 `ARCHITECTING`，先确认没有 open design task 需要收尾，说明将开发前回退到 `REQUIREMENT_GATHERING`，再用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切换到 PM/PRD 工作流；该工作流必须先创建或选择一个最小 `TASK-*` open task，并设置 `phase: "REQUIREMENT_GATHERING"`，再执行一个 PRD 生成或切片 task；否则说明当前阶段冲突和推荐路径。
 16. 用户输入 `/design`，或自然语言要求“设计技术方案”“做架构方案”“根据 PRD 做技术方案”“切技术方案”时，如果 `current_phase` 是 `ARCHITECTING`，调用架构和技术方案工作流；该工作流必须先创建或选择一个最小 `TASK-*` open task，并设置 `phase: "ARCHITECTING"`，再执行一个 architecture / tech plan / `plan.draft.yaml` 生成或切片 task；否则说明当前阶段冲突和推荐路径。
-17. 用户输入 `/dev`，或自然语言要求“开始开发”“做当前任务”“做下一个任务”“继续开发下一个任务”时，如果 `current_phase` 是 `SPRINTING`，创建或选择一个最小 `TASK-*` development task 并执行一个 task 闭环；否则说明当前阶段冲突和推荐路径。
-18. 用户输入 `/devloop`，或自然语言要求“开始循环：写任务，执行任务”“把开发循环跑完”“连续开发”时，如果 `current_phase` 是 `SPRINTING`，连续运行 `/dev` 循环，直到没有明确可做任务或遇到 blocker；否则说明当前阶段冲突和推荐路径。
+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. 用户明确要求并行、多 agent 或多 worktree 时，先判断当前阶段是否是 `REQUIREMENT_GATHERING`、`SPRINTING` 或 `TESTING`；如果是，生成或使用 `parallel_execution.trigger: "user_requested"` 合同；否则说明当前阶段不支持并行合同。
 21. `runtime_managed` 模式只在当前 Agent runtime 真实具备 subagent 能力时使用；否则使用 `user_orchestrated` 并输出每个 worker 的可复制 prompt。
@@ -59,7 +59,7 @@ Parallel Execution 是显式 opt-in：只有用户明确提出“并行”“多
 
 ## Plan Protocol
 
-每个 open task 都必须在 `plan.yaml` 中包含 `id`、`phase`、`docs`、`allowed_paths`、`required_gates` 和 `acceptance_criteria`；新 task 统一使用 `TASK-*` id，历史 `DEV-*`、`PRD-*`、`DES-*` task 只作为兼容输入保留。文档和流程产物 task 使用 `result_docs` 指向本 task 产出的 PRD、architecture、tech plan、ADR、review、test、release、RFC 或 `plan.draft.yaml`，开发 task 使用 `implementation_doc` 指向模块级实现事实。done/cancelled task 不长期留在当前 `plan.yaml`。完成后的产物事实以对应 `.docs/**` slice、`plan.draft.yaml` 或模块级 implementation doc 为准，动作历史以 git/PR/CI/release 系统作为 cold archive，`next_task_sequence` 负责继续分配后续 task id。
+每个 open task 都必须在 `plan.yaml` 中包含 `id`、`phase`、`docs`、`allowed_paths`、`required_gates` 和 `acceptance_criteria`；新 task 统一使用 `TASK-*` id，历史 `DEV-*`、`PRD-*`、`DES-*` task 只作为兼容输入保留。文档和流程产物 task 使用 `result_docs` 指向本 task 产出的 PRD、architecture、tech plan、ADR、review、test、release、RFC 或 `plan.draft.yaml`，开发 task 使用 `implementation_doc` 指向模块级实现事实。任何阶段如果从 draft queue promote 正式 `TASK-*`，必须同次消费并删除源 draft；当前内置 draft queue 是 `plan.draft.yaml.tasks[]`，用于保存尚未采用的开发草案。done/cancelled task 不长期留在当前 `plan.yaml`。完成后的产物事实以对应 `.docs/**` slice 或模块级 implementation doc 为准，动作历史以 git/PR/CI/release 系统作为 cold archive，`next_task_sequence` 负责继续分配后续 task id。
 
 `/prd`、`/design`、`/dev`、`/review`、`/test`、`/release` 和 `/rfc` 都是单 task 推进：默认只完成一个 `TASK-*`。`validate-plan` 用于检查当前 open task 合同是否完整；阶段出口 gate `validate-pm`、`validate-design`、`validate-dev`、`validate-review`、`validate-test`、`validate-release` 和 `validate-rfc` 都要求没有 open task 残留。
 

package/assets/skills/pjsdlc_reviewer/SKILL.md

@@ -17,6 +17,8 @@ Review 时先建立证据链：PRD 说什么、技术方案承诺什么、implem
 
 不要把个人偏好包装成 blocker。区分 blocking issue、follow-up improvement 和 open question。如果没有发现问题，要明确说明，同时列出剩余测试缺口或残余风险。
 
+Review 必须把“当前模块没有可运行入口/出口”视为阻断项，而不是普通测试缺口。凡 PRD、技术方案或 implementation doc 承诺 API、CLI、server route、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，Review 都要核对真实代码和实现文档是否提供可调用入口、输出/副作用边界和验证方式；缺失时 gate decision 应为 `BLOCKED`，并要求回到 SPRINTING/RFC，而不是允许进入 TESTING 后补 runtime。
+
 Review 产出本身也是 workflow task。开始 review 前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "REVIEWING"`；当前轮只产出一个 review batch、一个风险主题 slice 或一次 PR review 结论。不要在一个任务里覆盖多个互不相关的 review 主题。
 
 ## 输入
@@ -35,6 +37,7 @@ Review 产出本身也是 workflow task。开始 review 前，先在 `<harnessRo
 - 更新后的 `<harnessRoot>/state/plan.yaml`
 - 风险清单
 - 重构建议
+- runnable entry/exit readiness 结论
 - 是否允许进入 `TESTING` 的结论
 
 ## 语义切片
@@ -62,8 +65,9 @@ Review 阶段受 `plan.yaml` 管控：
 2. Findings 放在最前面，并按严重程度排序。
 3. 每条 finding 尽量引用文件、需求、任务或文档路径。
 4. 区分 blocking issues 和 follow-up improvements。
-5. 如果未发现问题，明确说明，并列出剩余测试缺口或残余风险。
-6. Review 阶段一次只执行一个 `TASK-*` task。
+5. 缺少已承诺的 runnable entry/exit、配置契约或 fixture/live 边界时，必须作为 P0/P1 blocking finding。
+6. 如果未发现问题，明确说明，并列出剩余测试缺口或残余风险。
+7. Review 阶段一次只执行一个 `TASK-*` task。
 
 ## 完成检查
 
@@ -72,6 +76,7 @@ Review 阶段受 `plan.yaml` 管控：
 - [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] 已评估需求一致性。
 - [ ] 已评估架构和可维护性风险。
+- [ ] 已评估 runnable entry/exit、配置契约和 fixture/live 边界是否足以进入 TESTING。
 - [ ] 已判断 review slice 的范围和风险主题边界。
 - [ ] 已列出测试缺口。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。

package/assets/skills/pjsdlc_rfc_recalibrate/SKILL.md

@@ -42,7 +42,7 @@ RFC recalibration 本身也是 workflow task。开始处理变更前，先在 `<
 
 - `.docs/rfc/` 按一次需求变更切片，一份 RFC 只描述一个可独立评估、实现和回归的变更。
 - 如果用户一次提出多个互不依赖的变更，应拆成多份 RFC。
-- RFC 的 impact analysis 负责判断是否需要重切 PRD、tech plan、implementation doc 或 test plan，并覆盖 state、tools、package assets、tests、migration 和 generated overview。
+- RFC 的 impact analysis 负责判断是否需要重切 PRD、tech plan、implementation doc 或 test report，并覆盖 state、tools、package assets、tests、migration 和 generated overview。
 - 对受影响产物做局部补丁，不重写无关稳定 slice。
 - 每次 RFC 影响了文档边界，都要更新 `.docs/INDEX.md` 并记录受影响任务状态。
 

package/assets/skills/pjsdlc_tester/SKILL.md

@@ -11,13 +11,15 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 
 ## 角色提示词
 
-你是测试负责人，目标是把需求、风险和实现变化转成可执行、可追踪、可复用的测试计划。你不只是列测试项，而是要判断哪些路径最容易出错、哪些验收标准必须被自动化或手动验证覆盖。
+你是测试负责人，目标是把需求、风险和实现变化转成可执行、可追踪、可复用的测试报告：测试矩阵、回归证据、覆盖缺口和最终结论。你不只是列测试项，而是要判断哪些路径最容易出错、哪些验收标准必须被自动化或手动验证覆盖。
 
 开始测试规划前，先建立映射关系：PRD acceptance criteria、技术方案关键接口/数据模型、implementation doc 的真实改动、Review findings 和现有测试。对每个测试项说明它覆盖的需求或风险；对暂不覆盖的内容说明原因、残余风险和 follow-up。
 
 执行回归时，优先选择能证明阶段出口的 gate。测试无法运行、环境缺失或数据不可得时，不要宣布通过，应记录 blocker、已完成检查和恢复条件。
 
-测试计划和回归证据产出本身也是 workflow task。开始测试前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "TESTING"`；当前轮只产出一个测试矩阵 slice、一个回归批次、一个风险验证片区或一组 scoped test changes。
+TESTING 只能调用 SPRINTING 已经交付的入口做输入/输出验证。可以补充测试、fixture、mock、assertion helper 和测试文档，但不能在 TESTING 中新增或长期维护 product runtime、server/API/CLI/adapter、direct poller、cloud bootstrap、systemd unit、真实 provider adapter、package runtime script 或部署脚本。如果发现真实入口/出口不存在、live 模式不可调用、配置契约缺失或用户目标与已实现通道不一致，应记录 `BLOCKED`、生成 RFC 或后续 dev task 建议，并停止把测试阶段扩大成开发/集成搭建。
+
+测试报告和回归证据产出本身也是 workflow task。开始测试前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "TESTING"`；当前轮只产出一个测试矩阵 slice、一个回归批次、一个风险验证片区或一组 scoped test changes。`plan.yaml` 仍是唯一执行计划事实源，`.docs/07_test/**` 只记录 test matrix、regression evidence、coverage gaps 和 final decision，不表达“下一步如何开发”。
 
 如果用户明确要求并行、多 agent 或多 worktree，测试阶段可以启用 `parallel_execution`，让 worker 分别执行互不依赖的回归片区、smoke、兼容性或风险验证。worker 只提交证据和必要的 scoped test changes；最终 `.docs/07_test/**`、coverage gaps、PASS/BLOCKED 决策和阶段 gate 由主 Agent 汇总。没有用户显式要求时，测试 workflow 保持串行。
 
@@ -29,22 +31,23 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 - `.docs/04_implementation/`
 - `.docs/06_review/REVIEW_REPORT.md`
 - 现有测试
-- `<harnessRoot>/pjsdlc_managed/templates/TEST_PLAN_TEMPLATE.md`
+- `<harnessRoot>/pjsdlc_managed/templates/TEST_REPORT_TEMPLATE.md`
 
 ## 输出
 
-- `.docs/07_test/TEST_PLAN.md`
+- `.docs/07_test/TEST_REPORT.md`
 - 必要时在 `tests/` 下补充测试
 - 更新后的 `<harnessRoot>/state/plan.yaml`
-- 回归测试记录
+- 回归证据记录
 - 覆盖缺口清单
+- `BLOCKED` 时的 RFC/dev follow-up 建议和恢复条件
 
 ## 语义切片
 
-- `.docs/07_test/` 默认按测试计划、测试矩阵、回归批次或领域测试范围切片。
+- `.docs/07_test/` 默认按测试报告、测试矩阵、回归批次或领域测试范围切片。
 - Test matrix 的语义原子是 PRD acceptance criteria、Review findings 和关键风险路径。
-- 如果多个领域的测试范围互不依赖，应拆成多个 test plan slices，并在主 `TEST_PLAN.md` 汇总。
-- 如果新增测试只是覆盖同一验收标准，应更新原 test slice，不要创建重复测试计划。
+- 如果多个领域的测试范围互不依赖，应拆成多个 test evidence slices，并在主 `TEST_REPORT.md` 汇总。
+- 如果新增测试只是覆盖同一验收标准，应更新原 test slice，不要创建重复测试报告。
 - 每次新增、拆分或合并 test slice 后，都要更新 `.docs/INDEX.md`。
 
 ## Plan Protocol
@@ -63,9 +66,12 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 1. 测试用例必须追溯到 PRD acceptance criteria 或 Review findings。
 2. 根据风险补充边界、负向、回归和集成测试。
 3. 如果有意延后覆盖，必须记录风险和 follow-up。
-4. 并行测试必须使用 `parallel_execution.trigger: "user_requested"`；`runtime_managed` 只在当前 runtime 支持 subagent 时使用，否则输出 `user_orchestrated` worker prompt。
-5. 宣布阶段完成前运行 `make test-all`。
-6. 测试阶段一次只执行一个 `TASK-*` task。
+4. 不得新增 product runtime、server/API/CLI/adapter、poller、cloud bootstrap、systemd unit、真实 provider adapter、package runtime script 或部署脚本；这些属于 SPRINTING/RFC。
+5. 测试发现入口/出口缺失时，Final decision 必须为 `BLOCKED`，并指出回到 SPRINTING/RFC 的具体条件。
+6. 新测试文档使用 `.docs/07_test/TEST_REPORT.md`；历史 `.docs/07_test/TEST_PLAN.md` 只作为 legacy alias / index 兼容，不作为新事实源命名。
+7. 并行测试必须使用 `parallel_execution.trigger: "user_requested"`；`runtime_managed` 只在当前 runtime 支持 subagent 时使用，否则输出 `user_orchestrated` worker prompt。
+8. 宣布阶段完成前运行 `make test-all`。
+9. 测试阶段一次只执行一个 `TASK-*` task。
 
 ## 完成检查
 
@@ -73,7 +79,8 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 - [ ] 当前测试工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "TESTING"`。
 - [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] Regression checklist 已完成。
-- [ ] 已判断 test plan / test matrix 的语义切片边界。
+- [ ] 测试只调用既有 runnable entry/exit；未在 TESTING 中新增 product runtime、bootstrap、provider adapter、deploy 或 package runtime script。
+- [ ] 已判断 test report / test matrix 的语义切片边界。
 - [ ] Coverage gaps 已明确。
 - [ ] 如果启用了并行测试，worker evidence 已由主 Agent 汇总到测试产物。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。

package/assets/templates/ADR_TEMPLATE.md

@@ -2,18 +2,44 @@
 
 ## Status（状态）
 
-Proposed
+Proposed / Accepted / Superseded
 
 ## Context（背景）
 
-- 
+- 这个决策要解决什么问题？
+- 哪些需求、架构边界、技术方案或约束让这个决策必须长期保留？
+
+## Options（备选方案）
+
+- Option A:
+  - 优点:
+  - 代价/风险:
+- Option B:
+  - 优点:
+  - 代价/风险:
 
 ## Decision（决策）
 
 - 
 
+## Rationale（理由）
+
+- 为什么选择这个方案，而不是其它备选方案？
+- 这个选择依赖哪些前提？哪些变化会触发重新评估？
+
 ## Consequences（影响）
 
 - 正向影响（Positive）:
 - 负向影响（Negative）:
 - 后续动作（Follow-up）:
+
+## Supersedes / Superseded By（替代关系）
+
+- Supersedes:
+- Superseded by:
+
+## Links（链接）
+
+- Related PRD:
+- Related architecture / tech plan:
+- Related implementation:

package/assets/templates/IMPLEMENTATION_DOC_TEMPLATE.md

@@ -32,7 +32,15 @@ Input
 -> Output
 ```
 
-## 5. 关键实现逻辑
+## 5. Runnable Entry/Exit（可运行入口/出口）
+
+- Entry points:
+- Exit / side effects:
+- Config contract:
+- Fixture/live boundary:
+- Missing runtime boundaries:
+
+## 6. 关键实现逻辑
 
 - 输入校验（Input validation）:
 - 核心分支（Core branches）:
@@ -40,22 +48,22 @@ Input
 - 边界兜底（Boundary fallback）:
 - 性能或并发注意事项（Performance or concurrency notes）:
 
-## 6. 与技术方案的偏移
+## 7. 与技术方案的偏移
 
 - 
 
-## 7. 测试覆盖（Test Coverage）
+## 8. 测试覆盖（Test Coverage）
 
 | 测试（Test） | 覆盖范围（Coverage） | 结果（Result） |
 |---|---|---|
 |  |  |  |
 
-## 8. 变更记录（Change Log）
+## 9. 变更记录（Change Log）
 
 | 日期（Date） | Task ID | Commit | 摘要（Summary） |
 |---|---|---|---|
 |  |  |  |  |
 
-## 9. 后续维护注意事项
+## 10. 后续维护注意事项
 
 - 

package/assets/templates/REVIEW_TEMPLATE.md

@@ -25,7 +25,15 @@
 
 - 
 
-## 6. Gate Result（阶段结论）
+## 6. Runnable Entry/Exit Readiness（可运行入口/出口）
+
+- Entry points:
+- Exit / side effects:
+- Config contract:
+- Fixture/live boundary:
+- Blocking gaps before TESTING:
+
+## 7. Gate Result（阶段结论）
 
 - Decision: `PASS` / `BLOCKED`
 - Required before testing:

package/assets/templates/{TEST_PLAN_TEMPLATE.md → TEST_REPORT_TEMPLATE.md}

@@ -1,4 +1,4 @@
-# Test Plan（测试计划）
+# Test Report（测试报告）
 
 ## 1. Scope（范围）
 
@@ -13,17 +13,25 @@
 |---|---|---|---|---|
 |  |  | unit/integration/e2e/regression |  | pending |
 
-## 3. Regression Checklist（回归检查清单）
+## 3. Regression Evidence（回归证据）
 
-- [ ] 
+- 
 
-## 4. Coverage Gaps（覆盖缺口）
+## 4. Runnable Entry/Exit Coverage（可运行入口/出口覆盖）
+
+- Existing entry points under test:
+- Expected exits / side effects:
+- Config contract used:
+- Fixture/live boundary:
+- Missing entry/exit blocker:
+
+## 5. Coverage Gaps（覆盖缺口）
 
 | 缺口（Gap） | 风险（Risk） | 后续动作（Follow-up） |
 |---|---|---|
 |  |  |  |
 
-## 5. Final Result（最终结论）
+## 6. Final Decision（最终结论）
 
 - Decision: `PASS` / `BLOCKED`
 - Evidence:

package/dist/lib/init.js

@@ -55,7 +55,10 @@ async function createProjectState(projectRoot, root, report) {
         ],
         [harnessPath(root, "state", "plan.yaml"), `current_task_id: ""\nnext_task_sequence: 1\ntasks: []\n`],
         [harnessPath(root, "state", "plan.draft.yaml"), `next_task_sequence: 1\ntasks: []\n`],
-        [harnessPath(root, "state", "memory.md"), "# Project Memory\n\n短期执行计划写入 plan.yaml；长期稳定知识简短记录在这里，并链接到 `.docs/` 正式出处。\n"]
+        [
+            harnessPath(root, "state", "memory.md"),
+            "# Project Memory\n\n短期执行计划写入 plan.yaml；长期稳定知识只在这里记录简短摘要和链接。完整决策背景、备选方案、取舍和后果写入 `.docs/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。\n"
+        ]
     ];
     for (const [relative, content] of files) {
         if (await writeTextIfChanged(path.join(projectRoot, relative), content)) {

package/dist/lib/migrations.js

@@ -356,7 +356,7 @@ async function ensureMemory(projectRoot, root, report) {
         report.skipped.push(relativeMemoryPath);
         return;
     }
-    const content = "# Project Memory\n\n记录跨阶段长期有效的稳定知识，并链接到 `.docs/` 正式出处。\n";
+    const content = "# Project Memory\n\n记录跨阶段长期有效知识的简短摘要和链接。完整决策背景、备选方案、取舍和后果写入 `.docs/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。\n";
     if (await writeTextIfChanged(memoryPath, content)) {
         report.changed.push(relativeMemoryPath);
     }

package/dist/lib/sync-engine.js

@@ -300,7 +300,7 @@ function renderSkillWithOverride(baseContent, override) {
         "",
         `${guidance} Keep package-managed Skill files unchanged; edit the override source instead.`,
         "",
-        "After sync, review the merged Skill for semantic conflicts between the package base and local override, especially phase boundaries, `allowed_paths`, `required_gates`, commit/release rules and completion checks.",
+        "After sync, review the merged Skill for semantic conflicts between the package base and local override, especially phase boundaries, `allowed_paths`, `required_gates`, commit/release rules and completion checks. Package-managed phase boundaries stay authoritative; overrides may narrow local behavior but must not expand TESTING, REVIEWING or other roles into implementation/runtime ownership.",
         ""
     ].join("\n");
     return `${renderedBase.trimEnd()}${header}\n${override.content.trim()}\n`;

package/dist/lib/validators.js

@@ -27,6 +27,58 @@ const DESIGN_CATEGORIES = [
         architectureTerms: ["compliance", "permission", "authorization", "audit", "合规", "权限", "审计", "授权", "客户确认", "回执归档"]
     }
 ];
+const TESTING_DISALLOWED_ALLOWED_PATHS = [
+    "package.json",
+    "**/package.json",
+    "package-lock.json",
+    "**/package-lock.json",
+    "npm-shrinkwrap.json",
+    "**/npm-shrinkwrap.json",
+    "pnpm-lock.yaml",
+    "**/pnpm-lock.yaml",
+    "yarn.lock",
+    "**/yarn.lock",
+    "bun.lock",
+    "**/bun.lock",
+    "bun.lockb",
+    "**/bun.lockb",
+    "src/**",
+    "app/**",
+    "lib/**",
+    "server/**",
+    "bin/**",
+    "cli/**",
+    "runtime/**",
+    "scripts/**",
+    "tools/**",
+    "deploy/**",
+    "deployment/**",
+    "infra/**",
+    "ops/**",
+    "systemd/**",
+    ".github/workflows/**",
+    "dockerfile",
+    "dockerfile.*",
+    "docker-compose*.yml",
+    "docker-compose*.yaml",
+    "*.service",
+    "tests/runtime/**",
+    "tests/**/runtime/**"
+];
+const TESTING_DISALLOWED_CHANGED_PATHS = [...TESTING_DISALLOWED_ALLOWED_PATHS, "scripts/**", "tools/**"];
+const TESTING_RUNTIME_FILE_TERMS = ["bootstrap", "cloud", "daemon", "poller", "provider", "runtime", "service", "systemd"];
+const TESTING_ALLOWED_TEST_FILE_TERMS = ["assertion", "fixture", "mock", "smoke"];
+const TEST_REPORT_PATH = ".docs/07_test/TEST_REPORT.md";
+const LEGACY_TEST_PLAN_PATH = ".docs/07_test/TEST_PLAN.md";
+const RUNNABLE_ENTRY_EXIT_TERMS = [
+    "runnable entry/exit",
+    "entry/exit",
+    "entry points",
+    "entry point",
+    "可运行入口/出口",
+    "入口/出口",
+    "not applicable"
+];
 const validators = {
     "validate-harness": validateHarness,
     "validate-current": validateCurrent,
@@ -262,8 +314,27 @@ async function validateCrossCuttingArchitecture(projectRoot, productFiles, techP
     return errors;
 }
 async function validateDev(projectRoot) {
+    const root = await harnessRoot(projectRoot);
     const plan = await validatePlanState(projectRoot, false);
-    return { info: [`validate-dev checked ${plan.taskCount} task(s)`], errors: plan.errors };
+    const draftErrors = await validateDevDraftConsumed(projectRoot, root);
+    const implementationDocErrors = await validateImplementationDocRunnableEntryExit(projectRoot);
+    return { info: [`validate-dev checked ${plan.taskCount} task(s)`], errors: [...plan.errors, ...draftErrors, ...implementationDocErrors] };
+}
+async function validateDevDraftConsumed(projectRoot, root) {
+    const errors = [];
+    const draft = await readYamlObject(path.join(projectRoot, root, "state", "plan.draft.yaml"));
+    if ("current_phase" in draft) {
+        errors.push("plan.draft.yaml must not define current_phase; lifecycle.yaml is the single source for current_phase");
+    }
+    if ("current_task_id" in draft) {
+        errors.push("plan.draft.yaml must not define current_task_id because drafts are not active task state");
+    }
+    const tasks = Array.isArray(draft.tasks) ? draft.tasks : [];
+    if (tasks.length > 0) {
+        const ids = tasks.map((task) => (isRecord(task) ? String(task.id ?? "<missing id>") : "<missing id>")).join(", ");
+        errors.push(`Unconsumed draft tasks remain in plan.draft.yaml: ${ids}. Promote the next draft into plan.yaml or remove already-consumed drafts before validate-dev.`);
+    }
+    return errors;
 }
 async function validateReview(projectRoot) {
     const plan = await validatePlanState(projectRoot, false);
@@ -273,23 +344,37 @@ async function validateReview(projectRoot) {
         errors.push("Review report must include findings or risks");
     if (!containsAny(text, ["test gap", "测试缺口", "coverage"]))
         errors.push("Review report must include test gaps or coverage notes");
+    if (!containsAny(text, ["entry/exit", "entrypoint", "入口", "出口", "runnable", "可运行"])) {
+        errors.push("Review report must assess runnable entry/exit readiness before TESTING");
+    }
     if (!containsAny(text, ["pass", "blocked", "通过", "阻塞"]))
         errors.push("Review report must include PASS/BLOCKED decision");
     return { info: ["validate-review checked review report"], errors };
 }
 async function validateTest(projectRoot) {
+    const root = await harnessRoot(projectRoot);
+    const lifecycle = await readYamlObject(path.join(projectRoot, root, "state", "lifecycle.yaml"));
     const plan = await validatePlanState(projectRoot, false);
-    const text = (await readText(path.join(projectRoot, ".docs/07_test/TEST_PLAN.md"))).toLowerCase();
     const errors = [...plan.errors];
+    const report = await readTestReport(projectRoot);
+    const text = report ? report.text.toLowerCase() : "";
+    if (!report)
+        errors.push(`Missing test report: expected ${TEST_REPORT_PATH} or legacy ${LEGACY_TEST_PLAN_PATH}`);
     if (!containsAny(text, ["matrix", "矩阵"]))
-        errors.push("Test plan must include a test matrix");
+        errors.push("Test report must include a test matrix");
     if (!containsAny(text, ["regression", "回归"]))
-        errors.push("Test plan must include regression coverage");
+        errors.push("Test report must include regression evidence");
     if (!containsAny(text, ["coverage gap", "覆盖缺口", "gap"]))
-        errors.push("Test plan must include coverage gaps");
+        errors.push("Test report must include coverage gaps");
+    if (!containsAny(text, ["entry/exit", "entrypoint", "入口", "出口", "runnable", "可运行"])) {
+        errors.push("Test report must state existing runnable entry/exit coverage or blocker status");
+    }
     if (!containsAny(text, ["pass", "blocked", "通过", "阻塞"]))
-        errors.push("Test plan must include PASS/BLOCKED decision");
-    return { info: ["validate-test checked test plan"], errors };
+        errors.push("Test report must include PASS/BLOCKED decision");
+    if (lifecycle.current_phase === "TESTING") {
+        errors.push(...testingBoundaryErrorsForChangedFiles(await changedFiles(projectRoot)));
+    }
+    return { info: [`validate-test checked ${report?.source ?? "missing test report"}`], errors };
 }
 async function validateRelease(projectRoot) {
     const plan = await validatePlanState(projectRoot, false);
@@ -399,6 +484,7 @@ async function validatePlanState(projectRoot, allowOpen) {
             if (!Array.isArray(task.acceptance_criteria) || task.acceptance_criteria.length === 0) {
                 errors.push(`Open task ${task.id} must define acceptance_criteria`);
             }
+            errors.push(...testingBoundaryErrorsForAllowedPaths(task));
         }
         else {
             errors.push(`Completed task ${task.id} must not remain in plan.yaml`);
@@ -546,6 +632,28 @@ async function readYamlObject(filePath) {
         return {};
     return (parseYaml(await readText(filePath)) ?? {});
 }
+async function readTestReport(projectRoot) {
+    const canonical = path.join(projectRoot, TEST_REPORT_PATH);
+    if (await pathExists(canonical)) {
+        return { text: await readText(canonical), source: TEST_REPORT_PATH };
+    }
+    const legacy = path.join(projectRoot, LEGACY_TEST_PLAN_PATH);
+    if (await pathExists(legacy)) {
+        return { text: await readText(legacy), source: LEGACY_TEST_PLAN_PATH };
+    }
+    return undefined;
+}
+async function validateImplementationDocRunnableEntryExit(projectRoot) {
+    const docs = await markdownFiles(path.join(projectRoot, ".docs/04_implementation"));
+    const errors = [];
+    for (const doc of docs) {
+        const text = await readText(doc);
+        if (!containsAny(text, RUNNABLE_ENTRY_EXIT_TERMS)) {
+            errors.push(`Implementation doc must include Runnable Entry/Exit facts or explicit Not applicable: ${repoRelative(projectRoot, doc)}`);
+        }
+    }
+    return errors;
+}
 async function markdownFiles(root) {
     const files = await listFiles(root);
     return files.filter((file) => {
@@ -561,6 +669,47 @@ function containsAny(text, needles) {
     const lowered = text.toLowerCase();
     return needles.some((needle) => lowered.includes(needle.toLowerCase()));
 }
+function testingBoundaryErrorsForAllowedPaths(task) {
+    if (task.phase !== "TESTING")
+        return [];
+    const allowed = Array.isArray(task.allowed_paths) ? task.allowed_paths.map((item) => String(item)) : [];
+    const blocked = allowed.filter((item) => isTestingBoundaryAllowedPath(item));
+    if (blocked.length === 0)
+        return [];
+    return [
+        `TESTING task allowed_paths must not include product runtime, package/deploy config, or long-running runtime paths: ${blocked.join(", ")}`
+    ];
+}
+function testingBoundaryErrorsForChangedFiles(files) {
+    const blocked = files.filter((file) => isTestingRuntimeBoundaryChange(file));
+    if (blocked.length === 0)
+        return [];
+    return [
+        `TESTING changes must use existing product entrypoints only; move runtime, bootstrap, provider, deploy, or package script changes to SPRINTING/RFC: ${blocked.join(", ")}`
+    ];
+}
+function isTestingBoundaryAllowedPath(file) {
+    const lowered = file.replace(/\\/g, "/").toLowerCase();
+    if (["package.json", "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"].includes(lowered)) {
+        return true;
+    }
+    return matchesAny(lowered, TESTING_DISALLOWED_ALLOWED_PATHS);
+}
+function isTestingRuntimeBoundaryChange(file) {
+    const normalized = file.replace(/\\/g, "/");
+    const lowered = normalized.toLowerCase();
+    if (isTestingBoundaryAllowedPath(lowered) || matchesAny(lowered, TESTING_DISALLOWED_CHANGED_PATHS)) {
+        return true;
+    }
+    if (lowered.startsWith("tests/")) {
+        const name = path.basename(lowered);
+        if (TESTING_ALLOWED_TEST_FILE_TERMS.some((term) => name.includes(term))) {
+            return false;
+        }
+        return TESTING_RUNTIME_FILE_TERMS.some((term) => name.includes(term));
+    }
+    return false;
+}
 function isDevelopmentDraft(task) {
     const taskId = String(task.id ?? "");
     return Boolean(task.implementation_doc) || task.phase === "SPRINTING" || taskId.startsWith("DEV-");
@@ -591,7 +740,7 @@ function taskText(task) {
 }
 export async function changedFiles(projectRoot) {
     try {
-        const { stdout } = await execFileAsync("git", ["status", "--porcelain"], { cwd: projectRoot });
+        const { stdout } = await execFileAsync("git", ["status", "--porcelain", "--untracked-files=all"], { cwd: projectRoot });
         return stdout
             .split("\n")
             .map((line) => line.slice(3).trim())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-project-sdlc",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "CLI and canonical assets for the AI SDLC Harness workflow.",
   "type": "module",
   "bin": {