agent-project-sdlc 0.1.18 → 0.1.19

package/README.md

@@ -82,11 +82,11 @@ The generic rule is that any workflow promoting a draft task into a formal `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.
+`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.
 
-SPRINTING Definition of Done includes runnable entry/exit 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` and `target_runtime_environment` in `plan.yaml`; `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 also include `Development Evidence` with `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`, or a justified `Not applicable`. 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.
+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 contract source, scenario results, executed gates, Module Key Test Path, actual evidence, missing/blockers and Testing Handoff Readiness; 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.
 
-`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, linked runnable-entry implementation docs and structured development evidence. 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. `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 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. 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. `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.
 
 `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

@@ -103,11 +103,11 @@ Agent 会读取 `<harnessRoot>/state/lifecycle.yaml` 和 `<harnessRoot>/state/pl
 
 在尚未进入开发前，`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。
+`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 / 本模块承诺的所有可运行入口和内部关键路径。
 
-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`；`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`，包含 `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`。provider smoke、fixture smoke、fake adapter 或 one-shot smoke 只能证明局部链路，不能单独证明 application readiness。REVIEWING 会把缺少入口/出口、初始化、配置契约、目标运行环境、证据等级或开发自测证据作为阻断项；TESTING 只调用 Review 已确认 `PASS` 的既有入口做输入输出验证，不能新增 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`，其中自测报告记录 contract source、scenario results、executed gates、Module Key Test Path、actual evidence、missing/blockers 和 Testing Handoff Readiness；`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。
 
-`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、implementation doc 和结构化 `Development Evidence`。页面类证据需要 dev server/page URL 与 browser check；API/CLI/worker/service/agent/runtime 类证据需要 startup/invocation command、endpoint/health/status 与 response/output/side effect。`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`。自测报告必须记录 `Module Key Test Path`，便于后续 Agent 复用从本地入口到全部自测用例完成的 debug 路径；该路径只要求覆盖本 task / 本模块承诺范围内的可运行入口和内部关键路径，不要求覆盖全系统所有模块。页面类证据需要 dev server/page URL 与 browser check；API/CLI/worker/service/agent/runtime 类证据需要 startup/invocation command、endpoint/health/status 与 response/output/side effect。`make validate-current` / `/advance` 是阶段出口 gate；进入 REVIEWING 前仍必须先完成 implementation commit 和 completion ledger，把 open task 从 `plan.yaml` 移除。
 
 `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。
 

package/assets/skills/pjsdlc_architect_design/SKILL.md

@@ -54,7 +54,7 @@ ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问
 - 如果 PRD、tech plan 或 draft task 明确出现 AI provider / AI copilot、外部系统边界、合规 / 权限 / 审计等横切主题，应各自有专门的 architecture slice；不要把多个横切架构问题都塞进一个总览文档。
 - 如果实现计划改变了已有模块边界，应更新相关 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`。`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`。
+- 这类开发 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 / 本模块承诺的所有可运行入口和内部关键路径。
 - 如果用户明确要求把既有完整技术方案文件切成多个 `.docs/03_tech_plan/` slices，先确认 replacement slices 覆盖原文件中仍有效的接口契约、数据模型、模块方案、任务组和 gate；切片完成并更新 `plan.draft.yaml` 引用、`.docs/INDEX.md`、刷新 `overview.md` 后，删除被替代的完整 tech plan file，避免同一事实由完整文件和 slices 双重保留。
 - 每次新增、拆分、合并或废弃 slice 后，都要更新 `.docs/INDEX.md`。
 
@@ -90,7 +90,7 @@ ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问
 - [ ] 已判断 architecture / tech plan / 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`。
+- [ ] task draft 字段完整且范围清晰；runtime/app/provider/live 类 task 已声明 `evidence_level`、`target_runtime_environment` 和 `self_test_contract`。
 - [ ] `.docs/INDEX.md` 已链接新增产物。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。
 - [ ] `make validate-design` 准备通过。

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、给出可能解释和推荐下一步，而不是扩大范围继续写。
 
-开发阶段的 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`，并按合同交付：`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`；确实不适用时也要显式写 `Not applicable` 和具体原因。provider smoke、fixture smoke、fake adapter 或 one-shot smoke 只能证明局部链路，不能单独证明 `Application readiness`。此时应保留或创建 `BLOCKED`/后续 dev task，或通过 RFC/ARCHITECTING 处理边界变更。
+开发阶段的 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 阶段产物，它只证明当前模块级可运行交付边界已经能被 Review/Testing 消费。报告还必须记录 `Module Key Test Path`：从本地启动或调用入口开始，执行并完成 `self_test_contract` 中全部自测用例的模块关键测试路径。该路径应覆盖本 task / 本模块承诺的所有可运行入口，以及自测用例实际经过的内部关键路径、关键边界、观察点和可观测完成证据，供后续 Agent 复用和 debug。
 
 页面类任务在开发阶段必须启动 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 结果。
 
@@ -39,7 +41,7 @@ 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、observable exit、basic self-test evidence、配置契约和 fixture/live 边界事实
+- implementation doc 中的 runnable entry/exit、observable exit、Development Self-Test Report、Module Key Test Path、配置契约和 fixture/live 边界事实
 - 更新后的 `<harnessRoot>/state/plan.yaml`
 - 如果本轮 promote draft，更新后的 `<harnessRoot>/state/plan.draft.yaml`
 - 更新后的 `.docs/INDEX.md`
@@ -68,7 +70,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`。
+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 / 本模块承诺的所有可运行入口和内部关键路径。
 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。
@@ -87,7 +89,7 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 6. 如果 gate 因代码或测试逻辑失败，在任务范围内修复。
 7. 如果 gate 因基础设施、凭证缺失、产品行为不清或高风险架构变化失败，进入 `BLOCKED`。
 8. gate 通过后调用 `pjsdlc_implementation_doc`。
-9. 只有 gate 通过、承诺的 runnable entry/exit 已实现或明确 `BLOCKED`，implementation doc 包含结构化 `Development Evidence`，且 implementation doc 校验通过后，才能把任务标记为 `done`。
+9. 只有 gate 通过、承诺的 runnable entry/exit 已实现或明确 `BLOCKED`，implementation doc 包含结构化 `Development Evidence` 和已执行的 `Development Self-Test Report`，且 implementation doc 校验通过后，才能把任务标记为 `done`。
 10. 任务完成并写入或更新相关 implementation doc、刷新 `overview.md`、记录 gate 后，先创建 task implementation commit；此时不要移除该 task。
 11. task implementation commit 必须发生在 task 移除前；后续默认不要读取其中的执行期字段，历史查询以模块级 implementation doc、RFC、PRD、tech plan 和代码为主。
 12. implementation commit 完成后，从当前 `plan.yaml` 移除该 task，并创建 task completion ledger commit。
@@ -106,6 +108,7 @@ 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"`，implementation doc 已填写 `Development Self-Test Report`，包含 contract source、scenario results、executed gates、Module Key Test Path、actual evidence、missing/blockers 和 Testing Handoff Readiness，且没有 `BLOCKED` 场景。
 - [ ] 如果 task 要求 `business_handoff_ready`，implementation doc 已写入 Testing Handoff Contract，包含入口、配置、初始化/health、输入样例、预期出口、清理方式和证据等级。
 - [ ] 如果当前 task 来自 `plan.draft.yaml.tasks[]`，源 draft 已在 promote 时从 draft 列表删除。
 - [ ] implementation doc 已生成或更新，并反映相关模块的真实代码。

package/assets/skills/pjsdlc_implementation_doc/SKILL.md

@@ -17,7 +17,9 @@ description: Use after development gates pass to update module-level implementat
 
 文档应帮助后来者快速理解：某个模块或核心数据流的当前实现是什么、关键对象/函数职责是什么、行为如何从输入流到输出、测试覆盖了什么、还有什么未覆盖。task id 只作为 provenance，不作为默认切片粒度。
 
-如果模块包含或承诺可运行系统边界，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`；确实没有应用入口时，`Not applicable` 必须写清原因。不能把未来才会实现的入口写成当前事实，不能把 provider smoke、fixture smoke、fake adapter 或 one-shot smoke 单独写成 application readiness。如果 task 要求 `business_handoff_ready`，还必须写 Testing Handoff Contract，包含入口、配置、初始化/health、输入样例、预期出口、清理/reset/幂等说明和证据等级。
+如果模块包含或承诺可运行系统边界，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 阶段定义的自测合同执行完成：记录 contract source、每个 scenario 的 `PASS` / `BLOCKED` 结果、实际执行入口、实际出口、证据位置或命令输出、executed gates、Module Key Test Path、missing/blockers 和 Testing Handoff Readiness。`Module Key Test Path` 必须说明从本地启动或调用入口开始，执行并完成 `self_test_contract` 中全部自测用例的模块关键测试路径。该路径应覆盖本 task / 本模块承诺的所有可运行入口，以及自测用例实际经过的内部关键路径、关键边界、观察点和可观测完成证据，供后续 Agent 复用和 debug。任何 scenario 为 `BLOCKED` 时，不得把开发 task 写成完成。
 
 ## 输入
 
@@ -49,8 +51,9 @@ description: Use after development gates pass to update module-level implementat
 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. 测试覆盖必须列出具体测试，或明确记录覆盖缺口。
-7. 文档粒度保持在模块、子系统或核心数据流级别；不要默认按 task 建文档，也不要写成跨全项目的巨型百科。
+6. `Development Self-Test Report` 必须执行 `self_test_contract` 中的全部 scenario 和 required gates，并记录从本地启动或调用入口开始，到完成所有自测用例的 `Module Key Test Path`；路径必须覆盖本 task / 本模块承诺的所有可运行入口、内部关键路径、关键边界、观察点和完成证据，不能只补一句 smoke 结果。
+7. 测试覆盖必须列出具体测试，或明确记录覆盖缺口。
+8. 文档粒度保持在模块、子系统或核心数据流级别；不要默认按 task 建文档，也不要写成跨全项目的巨型百科。
 
 ## 完成检查
 
@@ -60,6 +63,7 @@ description: Use after development gates pass to update module-level implementat
 - [ ] 核心数据流已说明。
 - [ ] 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` 已记录 contract source、scenario results、executed gates、Module Key Test Path、actual evidence、missing/blockers 和 Testing Handoff Readiness。
 - [ ] `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` 或等价交付边界，并核对真实代码和实现文档是否提供可调用入口、初始化方式、输出/副作用边界和验证方式；如果 task 声明了 `evidence_level.required` 和 `target_runtime_environment`，还必须核对实际证据等级、执行地点和目标运行环境是否匹配。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 要求 `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` 和 required gates 是否匹配。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`，并记录从本地启动或调用入口开始，到完成全部自测用例的 `Module Key Test Path`。该路径应覆盖本 task / 本模块承诺的所有可运行入口、内部关键路径、关键边界、观察点和可观测完成证据。如果 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 主题。
 
@@ -66,7 +66,7 @@ Review 阶段受 `plan.yaml` 管控：
 2. Findings 放在最前面，并按严重程度排序。
 3. 每条 finding 尽量引用文件、需求、任务或文档路径。
 4. 区分 blocking issues 和 follow-up improvements。
-5. 缺少已承诺的 runnable entry/exit、配置契约、fixture/live 边界或 `Development Evidence` 时，必须作为 P0/P1 blocking finding。
+5. 缺少已承诺的 runnable entry/exit、配置契约、fixture/live 边界、`Development Evidence` 或 `Development Self-Test Report` 时，必须作为 P0/P1 blocking finding。
 6. 如果未发现问题，明确说明，并列出剩余测试缺口或残余风险。
 7. Review 阶段一次只执行一个 `TASK-*` task。
 
@@ -79,6 +79,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 是否执行全部 scenario 和 required gates，并记录可复用的 Module Key Test Path。
 - [ ] 已核对证据等级和执行地点是否匹配 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、环境依赖或验收边界，必须同步审查 `.docs/07_test/**`。被新方案 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 和原因；如果只是文案澄清且不影响测试事实源，可写 `none`。
+如果 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 recalibration 本身也是 workflow task。开始处理变更前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "RFC_RECALIBRATION"`；当前轮只处理一个 RFC 文件、一个 impact analysis 单元或一个局部补丁单元。
 
@@ -45,7 +45,7 @@ RFC recalibration 本身也是 workflow task。开始处理变更前，先在 `<
 
 - `.docs/rfc/` 按一次需求变更切片，一份 RFC 只描述一个可独立评估、实现和回归的变更。
 - 如果用户一次提出多个互不依赖的变更，应拆成多份 RFC。
-- RFC 的 impact analysis 负责判断是否需要重切 PRD、tech plan、implementation doc、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、test strategy、test cases 或 test report，并覆盖 state、tools、package assets、tests、migration 和 generated overview。
 - 对受影响产物做局部补丁，不重写无关稳定 slice。
 - 每次 RFC 影响了文档边界，都要更新 `.docs/INDEX.md` 并记录受影响任务状态。
 
@@ -80,6 +80,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 影响。
 - [ ] 受影响任务已标记或新增。
 - [ ] 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`、live 模式不可调用、配置契约缺失、Review readiness checklist 不是全 `PASS`，或 `Evidence Level` / `Target Runtime Environment` 与 task 或技术方案承诺不一致，应记录 `BLOCKED`、生成 RFC 或后续 dev task 建议，并停止把测试阶段扩大成开发/集成搭建。开发尚未交付可测试 entry/exit、目标运行环境或 Testing Handoff Contract 时，不要在 `.docs/07_test/**` 提前生成正式测试用例或正式报告；验收思路应留在 PRD acceptance criteria、tech plan verification strategy 或非 `.docs/07_test/**` 的草稿说明里。`TEST_REPORT.md` 不能在描述缺少 entry/exit、缺少 Development Evidence、证据等级不匹配或未交付应用入口时给出 `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`、自测报告缺少从本地启动或调用入口到完成全部自测用例的 `Module Key Test Path`、或该路径没有覆盖本 task / 本模块承诺的入口、内部关键路径、关键边界、观察点和完成证据，live 模式不可调用、配置契约缺失、Review readiness checklist 不是全 `PASS`，或 `Evidence Level` / `Target Runtime Environment` / `self_test_contract` 与 task 或技术方案承诺不一致，应记录 `BLOCKED`、生成 RFC 或后续 dev task 建议，并停止把测试阶段扩大成开发/集成搭建。开发尚未交付可测试 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、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。
 2. 根据风险补充边界、负向、回归和集成测试。
 3. 如果有意延后覆盖，必须记录风险和 follow-up。
 4. 不得新增 product runtime、server/API/CLI/adapter、poller、cloud bootstrap、systemd unit、真实 provider adapter、package runtime script 或部署脚本；这些属于 SPRINTING/RFC。
@@ -87,6 +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 中 scenario results、executed gates、Module Key Test Path 和 actual evidence。
 - [ ] 已判断 test report / test matrix 的语义切片边界。
 - [ ] 未把测试计划、测试用例或待填内容写成 `TEST_REPORT.md`。
 - [ ] 已确认 `.docs/07_test/**` 只包含当前方案仍有效的测试事实。

package/assets/templates/IMPLEMENTATION_DOC_TEMPLATE.md

@@ -50,10 +50,24 @@ Input
 - Config Contract:
 - Testing Handoff Readiness:
 - Known Missing Runtime Boundaries:
-- Basic Self-test Evidence:
+- Basic Self-test Evidence: See `Development Self-Test Report`.
 - Not applicable:
 
-## 7. Testing Handoff Contract（测试交接合同）
+## 7. Development Self-Test Report（开发自测报告，已执行）
+
+- Contract Source:
+- Scenario Results:
+- Executed Gates:
+- Module Key Test Path: local start / invocation -> all self-test scenarios -> all task/module promised runnable entries -> actual internal key paths / boundaries / checkpoints -> observable completion evidence
+- Actual Evidence:
+- Missing / Blockers:
+- Testing Handoff Readiness:
+
+| Scenario ID | Result | Executed Entry | Actual Exit | Evidence |
+|---|---|---|---|---|
+| ST-001 | PASS / BLOCKED |  |  |  |
+
+## 8. Testing Handoff Contract（测试交接合同）
 
 - Entry:
 - Config:
@@ -63,7 +77,7 @@ Input
 - Cleanup / reset / idempotency:
 - Evidence Level:
 
-## 8. 关键实现逻辑
+## 9. 关键实现逻辑
 
 - 输入校验（Input validation）:
 - 核心分支（Core branches）:
@@ -71,22 +85,22 @@ Input
 - 边界兜底（Boundary fallback）:
 - 性能或并发注意事项（Performance or concurrency notes）:
 
-## 9. 与技术方案的偏移
+## 10. 与技术方案的偏移
 
 - 
 
-## 10. 测试覆盖（Test Coverage）
+## 11. 测试覆盖（Test Coverage）
 
 | 测试（Test） | 覆盖范围（Coverage） | 结果（Result） |
 |---|---|---|
 |  |  |  |
 
-## 11. 变更记录（Change Log）
+## 12. 变更记录（Change Log）
 
 | 日期（Date） | Task ID | Commit | 摘要（Summary） |
 |---|---|---|---|
 |  |  |  |  |
 
-## 12. 后续维护注意事项
+## 13. 后续维护注意事项
 
 - 

package/assets/templates/PLAN_TEMPLATE.yaml

@@ -63,6 +63,24 @@ tasks:
       kind: "local | ci | staging | cloud_vm | managed_service | browser | worker | not_applicable"
       required_for_done: true
       handoff_entrypoint: "URL / CLI / worker command / server action"
+    # Required for SPRINTING tasks with a runnable boundary. Created during
+    # ARCHITECTING/RFC and executed during SPRINTING.
+    self_test_contract:
+      status: "required | not_applicable"
+      source: ".docs/03_tech_plan/example.md"
+      capability_refs:
+        - "PRD-EXAMPLE-001"
+      runnable_entry: "command / URL / endpoint / worker command"
+      observable_exit: "response / page state / side effect / log / artifact"
+      module_key_test_path: "local start command / URL -> all self-test scenarios -> all task/module promised runnable entries -> internal key paths / boundaries / checkpoints -> observable completion evidence"
+      required_gates:
+        - "npm run smoke"
+      scenarios:
+        - id: "ST-001"
+          entry: "command / URL / endpoint / worker command"
+          expected_exit: "observable response / side effect / page state"
+          evidence: "command/browser/API/log/screenshot/etc"
+      not_applicable_reason: ""
     working_notes:
       - "执行现场备注只在 open task 保留。"
     result_docs:

package/assets/templates/RFC_TEMPLATE.md

@@ -38,6 +38,17 @@
 - Retained test docs:
 - Reason:
 
-## 8. Status
+## 8. Development Self-Test Impact（开发自测影响）
+
+- Entry/exit impact:
+- Runtime / target environment impact:
+- Required gates impact:
+- Tech plan self-test contract impact:
+- `plan.yaml` / `plan.draft.yaml` task contract impact:
+- Implementation doc self-test report impact:
+- Module key test path impact:
+- Review / Testing handoff impact:
+
+## 9. Status
 
 - Status: DRAFT

package/assets/templates/TECH_DESIGN_TEMPLATE.md

@@ -45,12 +45,29 @@ Input
 
 `Implementation Doc` 应指向模块、子系统或核心数据流级文档；多个 task 可以更新同一份文档，task id 和 commit 记录在该文档的 provenance / Change Log 中。
 
-## 7. 风险与缓解
+## 7. Development Self-Test Contract（开发自测合同，待执行）
+
+> service / agent / runtime / worker / frontend app / provider-live / API / CLI 等可运行边界的开发 task 必填，并同步写入 `plan.draft.yaml.tasks[].self_test_contract`。
+
+- Contract source:
+- Capability refs:
+- Runnable entry:
+- Observable exit:
+- Module key test path（local start -> all self-test scenarios -> all promised runnable entries -> internal key paths -> observable completion evidence）:
+- Required gates:
+
+| Scenario ID | Entry | Expected Exit | Evidence |
+|---|---|---|---|
+| ST-001 |  |  | command/browser/API/log/screenshot/etc |
+
+- Not applicable reason:
+
+## 8. 风险与缓解
 
 | 风险（Risk） | 等级（Level） | 缓解措施（Mitigation） |
 |---|---|---|
 |  | P1 |  |
 
-## 8. 需要关注的方案偏移
+## 9. 需要关注的方案偏移
 
 - 

package/dist/lib/validators.js

@@ -87,6 +87,10 @@ const RUNNABLE_ENTRY_EXIT_TERMS = [
     "not applicable"
 ];
 const DEVELOPMENT_EVIDENCE_TERMS = ["development evidence", "开发自测证据"];
+const DEVELOPMENT_SELF_TEST_CONTRACT_TERMS = ["development self-test contract", "开发自测合同"];
+const DEVELOPMENT_SELF_TEST_REPORT_TERMS = ["development self-test report", "开发自测报告"];
+const DEVELOPMENT_SELF_TEST_IMPACT_TERMS = ["development self-test impact", "开发自测影响"];
+const MODULE_KEY_TEST_PATH_TERMS = ["module key test path", "模块关键测试路径"];
 const TESTING_HANDOFF_TERMS = ["testing handoff contract", "测试交接合同"];
 const EVIDENCE_PLACEHOLDER_TERMS = [
     "pending",
@@ -217,6 +221,33 @@ const REVIEW_READINESS_FIELDS = [
     "Config Contract",
     "Testing Handoff Readiness"
 ];
+const SELF_TEST_CONTRACT_STATUSES = new Set(["required", "not_applicable"]);
+const RFC_SELF_TEST_TRIGGER_TERMS = [
+    "entry/exit",
+    "runnable entry",
+    "runnable exit",
+    "runnable entry/exit",
+    "runtime",
+    "environment",
+    "target_runtime_environment",
+    "target runtime",
+    "required_gates",
+    "gate",
+    "handoff",
+    "blocker",
+    "module key test path",
+    "test route",
+    "test path",
+    "debug path",
+    "测试路径",
+    "测试链路",
+    "自测链路",
+    "模块关键测试路径",
+    "入口",
+    "出口",
+    "运行环境",
+    "阻塞"
+];
 const validators = {
     "validate-harness": validateHarness,
     "validate-current": validateCurrent,
@@ -339,26 +370,26 @@ async function validateDesignDraft(projectRoot, root, techPlanFiles) {
     const availableTechPlans = new Set(techPlanFiles.map((file) => repoRelative(projectRoot, file)));
     const developmentTasks = [];
     const primaryRefs = [];
-    rawTasks.forEach((rawTask, index) => {
+    for (const [index, rawTask] of rawTasks.entries()) {
         if (!isRecord(rawTask)) {
             errors.push(`Task draft #${index + 1} must be a mapping`);
-            return;
+            continue;
         }
         validateDraftTaskShape(rawTask, index, errors);
         if (rawTask.status !== "pending") {
             errors.push(`Draft task ${String(rawTask.id ?? "")} should start as pending`);
         }
         if (!isDevelopmentDraft(rawTask))
-            return;
+            continue;
         developmentTasks.push(rawTask);
         if (!isRecord(rawTask.docs)) {
             errors.push(`Draft task ${String(rawTask.id ?? "")} docs must be a mapping`);
-            return;
+            continue;
         }
         const techRefs = asStringList(rawTask.docs.tech_plan);
         if (techRefs.length === 0) {
             errors.push(`Draft task ${String(rawTask.id ?? "")} must reference at least one tech plan slice in docs.tech_plan`);
-            return;
+            continue;
         }
         const normalizedRefs = techRefs.map(normalizeDocRef);
         for (const ref of normalizedRefs) {
@@ -369,8 +400,9 @@ async function validateDesignDraft(projectRoot, root, techPlanFiles) {
                 errors.push(`Draft task ${String(rawTask.id ?? "")} references missing or generated tech plan slice: ${ref}`);
             }
         }
+        errors.push(...(await validateSelfTestContractTechPlanBinding(projectRoot, rawTask, normalizedRefs)));
         primaryRefs.push(normalizedRefs[0]);
-    });
+    }
     if (developmentTasks.length === 0) {
         errors.push("plan.draft.yaml must contain at least one development task with implementation_doc");
     }
@@ -611,14 +643,36 @@ async function validateRfc(projectRoot) {
             errors.push(`Superseded test doc still linked from .docs/INDEX.md: ${superseded}`);
         }
     }
-    const statuses = [...text.matchAll(/status:\s*([a-z_]+)/g)].map((match) => match[1].toUpperCase());
+    const statuses = [...text.matchAll(/^\s*-?\s*Status:\s*([A-Z_]+)/gim)].map((match) => match[1].toUpperCase());
     if (statuses.length === 0)
         errors.push("RFC must include a Status line");
     const invalidStatuses = statuses.filter((status) => !["DRAFT", "APPLIED", "VERIFIED", "ARCHIVED"].includes(status));
     if (invalidStatuses.length > 0)
         errors.push(`Invalid RFC status: ${invalidStatuses.join(", ")}`);
+    errors.push(...(await validateRfcSelfTestImpact(projectRoot, docs)));
     return { info: [`validate-rfc checked ${docs.length} file(s)`], errors };
 }
+async function validateRfcSelfTestImpact(projectRoot, docs) {
+    const errors = [];
+    for (const doc of docs) {
+        const relative = repoRelative(projectRoot, doc);
+        const basename = path.basename(doc);
+        const number = rfcNumber(basename);
+        if (number !== undefined && number < 23)
+            continue;
+        const text = await readText(doc);
+        if (!containsAny(text, RFC_SELF_TEST_TRIGGER_TERMS))
+            continue;
+        if (!containsAny(text, DEVELOPMENT_SELF_TEST_IMPACT_TERMS)) {
+            errors.push(`${relative} must include Development Self-Test Impact when RFC changes entry/exit, runtime, gates, handoff, or blockers`);
+        }
+    }
+    return errors;
+}
+function rfcNumber(fileName) {
+    const match = fileName.match(/^RFC[_-](\d+)/i);
+    return match ? Number(match[1]) : undefined;
+}
 async function validatePlanState(projectRoot, allowOpen) {
     const errors = [];
     const root = await harnessRoot(projectRoot);
@@ -716,7 +770,7 @@ function validateRuntimeEvidenceContract(task) {
     if (String(task.phase ?? "") !== "SPRINTING")
         return errors;
     const context = taskText(task).toLowerCase();
-    const needsRuntimeContract = containsAny(context, [...APPLICATION_READINESS_TASK_TERMS, ...PAGE_TASK_TERMS]);
+    const needsRuntimeContract = needsRunnableTaskContract(task) && !isNotApplicableRuntimeTask(task);
     const evidenceLevel = task.evidence_level;
     const targetRuntime = task.target_runtime_environment;
     if (needsRuntimeContract && !isRecord(evidenceLevel)) {
@@ -769,6 +823,123 @@ function validateRuntimeEvidenceContract(task) {
             }
         }
     }
+    errors.push(...validateSelfTestContract(task, needsRuntimeContract));
+    return errors;
+}
+function needsRunnableTaskContract(task) {
+    const context = taskText(task).toLowerCase();
+    return containsAny(context, [...APPLICATION_READINESS_TASK_TERMS, ...PAGE_TASK_TERMS, ...CALLABLE_TASK_TERMS]);
+}
+function isNotApplicableRuntimeTask(task) {
+    const evidenceLevel = isRecord(task.evidence_level) ? task.evidence_level : undefined;
+    const targetRuntime = isRecord(task.target_runtime_environment) ? task.target_runtime_environment : undefined;
+    return String(evidenceLevel?.required ?? "") === "unit" && String(targetRuntime?.kind ?? "") === "not_applicable";
+}
+function validateSelfTestContract(task, requiredForRunnableBoundary) {
+    const errors = [];
+    const taskId = String(task.id ?? "Task");
+    const contract = task.self_test_contract;
+    if (requiredForRunnableBoundary && !isRecord(contract)) {
+        errors.push(`${taskId} runtime/app task must define self_test_contract`);
+        return errors;
+    }
+    if (contract === undefined)
+        return errors;
+    if (!isRecord(contract)) {
+        errors.push(`${taskId} self_test_contract must be a mapping`);
+        return errors;
+    }
+    const status = String(contract.status ?? "");
+    if (!SELF_TEST_CONTRACT_STATUSES.has(status)) {
+        errors.push(`${taskId} self_test_contract.status must be required or not_applicable`);
+    }
+    if (requiredForRunnableBoundary && status !== "required") {
+        errors.push(`${taskId} runnable boundary task self_test_contract.status must be required`);
+    }
+    if (status === "not_applicable") {
+        const reason = String(contract.not_applicable_reason ?? "").trim();
+        if (reason.length < 24 || isPlaceholderEvidence(reason)) {
+            errors.push(`${taskId} self_test_contract.not_applicable_reason must explain why self-test is not applicable`);
+        }
+        return errors;
+    }
+    if (status !== "required")
+        return errors;
+    for (const field of ["source", "runnable_entry", "observable_exit", "module_key_test_path"]) {
+        if (typeof contract[field] !== "string" || !String(contract[field]).trim() || isPlaceholderEvidence(String(contract[field]))) {
+            errors.push(`${taskId} self_test_contract.${field} must be concrete`);
+        }
+    }
+    if (!Array.isArray(contract.capability_refs) || contract.capability_refs.length === 0) {
+        errors.push(`${taskId} self_test_contract.capability_refs must be a non-empty list`);
+    }
+    const requiredGates = asStringList(contract.required_gates);
+    if (requiredGates.length === 0) {
+        errors.push(`${taskId} self_test_contract.required_gates must be a non-empty list`);
+    }
+    const taskGates = new Set(asStringList(task.required_gates));
+    for (const gate of requiredGates) {
+        if (!taskGates.has(gate)) {
+            errors.push(`${taskId} self_test_contract.required_gates must also appear in task required_gates: ${gate}`);
+        }
+    }
+    const scenarios = Array.isArray(contract.scenarios) ? contract.scenarios : [];
+    if (scenarios.length === 0) {
+        errors.push(`${taskId} self_test_contract.scenarios must be a non-empty list`);
+    }
+    const seen = new Set();
+    scenarios.forEach((scenario, index) => {
+        if (!isRecord(scenario)) {
+            errors.push(`${taskId} self_test_contract.scenarios[${index}] must be a mapping`);
+            return;
+        }
+        const scenarioId = String(scenario.id ?? "").trim();
+        if (!scenarioId) {
+            errors.push(`${taskId} self_test_contract.scenarios[${index}].id must be set`);
+        }
+        else if (seen.has(scenarioId)) {
+            errors.push(`${taskId} self_test_contract scenario id must be unique: ${scenarioId}`);
+        }
+        seen.add(scenarioId);
+        for (const field of ["entry", "expected_exit", "evidence"]) {
+            if (typeof scenario[field] !== "string" || !String(scenario[field]).trim() || isPlaceholderEvidence(String(scenario[field]))) {
+                errors.push(`${taskId} self_test_contract.scenarios[${scenarioId || index}].${field} must be concrete`);
+            }
+        }
+    });
+    return errors;
+}
+async function validateSelfTestContractTechPlanBinding(projectRoot, task, normalizedTechRefs) {
+    const errors = [];
+    const taskId = String(task.id ?? "Task");
+    const contract = isRecord(task.self_test_contract) ? task.self_test_contract : undefined;
+    if (!contract || String(contract.status ?? "") !== "required")
+        return errors;
+    const source = normalizeDocRef(String(contract.source ?? ""));
+    if (!source)
+        return errors;
+    if (!normalizedTechRefs.includes(source)) {
+        errors.push(`${taskId} self_test_contract.source must be listed in docs.tech_plan: ${source}`);
+        return errors;
+    }
+    const sourcePath = path.join(projectRoot, source);
+    if (!(await pathExists(sourcePath)))
+        return errors;
+    const text = await readText(sourcePath);
+    const section = markdownSection(text, DEVELOPMENT_SELF_TEST_CONTRACT_TERMS);
+    if (!section) {
+        errors.push(`${taskId} self_test_contract.source must contain a Development Self-Test Contract section: ${source}`);
+        return errors;
+    }
+    if (!containsAny(section, MODULE_KEY_TEST_PATH_TERMS)) {
+        errors.push(`${taskId} tech plan Development Self-Test Contract must include Module key test path: ${source}`);
+    }
+    for (const scenario of Array.isArray(contract.scenarios) ? contract.scenarios.filter(isRecord) : []) {
+        const scenarioId = String(scenario.id ?? "").trim();
+        if (scenarioId && !section.includes(scenarioId)) {
+            errors.push(`${taskId} tech plan Development Self-Test Contract must include scenario ${scenarioId}: ${source}`);
+        }
+    }
     return errors;
 }
 function validateParallelExecutionContract(plan, currentPhase, errors) {
@@ -1017,8 +1188,75 @@ function validateDevelopmentEvidenceText(text, task, implementationDoc) {
         }
     }
     errors.push(...validateEvidenceLevelAgainstContract(section, text, task, implementationDoc));
+    errors.push(...validateDevelopmentSelfTestReport(text, section, task, implementationDoc));
     return errors;
 }
+function validateDevelopmentSelfTestReport(fullText, developmentEvidenceSection, task, implementationDoc) {
+    const errors = [];
+    const taskId = String(task.id ?? "current task");
+    const contract = isRecord(task.self_test_contract) ? task.self_test_contract : undefined;
+    if (!contract || String(contract.status ?? "") !== "required")
+        return errors;
+    const report = markdownSection(fullText, DEVELOPMENT_SELF_TEST_REPORT_TERMS);
+    if (!report) {
+        return [`${taskId} implementation_doc must include Development Self-Test Report for self_test_contract: ${implementationDoc}`];
+    }
+    const basicSelfTest = evidenceFieldValue(developmentEvidenceSection, "Basic Self-test Evidence") ?? "";
+    if (!containsAny(basicSelfTest, ["Development Self-Test Report", "开发自测报告", "self-test report"])) {
+        errors.push(`${taskId} Basic Self-test Evidence must reference the Development Self-Test Report in ${implementationDoc}`);
+    }
+    for (const field of ["Contract Source", "Scenario Results", "Executed Gates", "Module Key Test Path", "Actual Evidence", "Missing / Blockers", "Testing Handoff Readiness"]) {
+        const value = evidenceFieldValue(report, field);
+        const allowsNone = field === "Missing / Blockers";
+        if (!value || (!allowsNone && isPlaceholderEvidence(value))) {
+            errors.push(`${taskId} Development Self-Test Report ${field} must contain executed evidence in ${implementationDoc}`);
+        }
+    }
+    const source = String(contract.source ?? "").trim();
+    if (source && !report.includes(source)) {
+        errors.push(`${taskId} Development Self-Test Report must reference contract source ${source} in ${implementationDoc}`);
+    }
+    for (const gate of asStringList(contract.required_gates)) {
+        if (!report.includes(gate)) {
+            errors.push(`${taskId} Development Self-Test Report must record required gate ${gate} in ${implementationDoc}`);
+        }
+    }
+    const moduleKeyTestPath = evidenceFieldValue(report, "Module Key Test Path") ?? "";
+    const runnableEntry = String(contract.runnable_entry ?? "").trim();
+    if (runnableEntry && !moduleKeyTestPath.includes(runnableEntry)) {
+        errors.push(`${taskId} Development Self-Test Report Module Key Test Path must include runnable entry ${runnableEntry} in ${implementationDoc}`);
+    }
+    const scenarios = Array.isArray(contract.scenarios) ? contract.scenarios.filter(isRecord) : [];
+    for (const scenario of scenarios) {
+        const scenarioId = String(scenario.id ?? "").trim();
+        if (!scenarioId)
+            continue;
+        if (!moduleKeyTestPath.includes(scenarioId)) {
+            errors.push(`${taskId} Development Self-Test Report Module Key Test Path must include scenario ${scenarioId} in ${implementationDoc}`);
+        }
+        const status = scenarioStatus(report, scenarioId);
+        if (!status) {
+            errors.push(`${taskId} Development Self-Test Report must record scenario ${scenarioId} as PASS or BLOCKED in ${implementationDoc}`);
+        }
+        else if (status === "BLOCKED") {
+            errors.push(`${taskId} Development Self-Test Report scenario ${scenarioId} is BLOCKED; keep task open or record a blocker`);
+        }
+    }
+    return errors;
+}
+function scenarioStatus(text, scenarioId) {
+    const escaped = scenarioId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const patterns = [
+        new RegExp("^.*" + escaped + ".*\\b(PASS|BLOCKED)\\b.*$", "im"),
+        new RegExp("\\|[^\\n|]*" + escaped + "[^\\n|]*\\|[^\\n|]*\\b(PASS|BLOCKED)\\b[^\\n|]*\\|", "i")
+    ];
+    for (const pattern of patterns) {
+        const match = text.match(pattern);
+        if (match)
+            return match[1].toUpperCase();
+    }
+    return undefined;
+}
 function hasConcreteDevelopmentEvidenceFields(section) {
     return ["Evidence Level", "Target Runtime Environment", "Runnable Entry", "Observable Exit", "Client / Server Initialization", "Config Contract"].some((field) => {
         const value = evidenceFieldValue(section, field);

package/package.json

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