agent-project-sdlc 0.1.14 → 0.1.16

package/README.md

@@ -22,8 +22,8 @@ npx sdlc-harness init --adopt
 | Project initialization | `npx sdlc-harness init` | Creates `AGENTS.md`, `<harnessRoot>/state/**`, workflow skills, managed templates/policies, `.docs/**` and a Makefile include. |
 | Existing project adoption | `npx sdlc-harness init --adopt` | Adds Harness non-destructively to an existing repository. |
 | Configurable Harness root | `--harness-folder`, `package.json#sdlcHarness.harnessFolderName`, `sdlc-harness.config.json` | Supports Codex `.codex`, Claude `.claude`, Cursor `.cursor`, Cline `.cline`, Roo `.roo`, Gemini `.gemini` or a custom folder. |
-| Managed file sync | `npx sdlc-harness sync` | Materializes package canonical assets into the configured Harness root while preserving project state, docs and local overrides. |
-| Upgrade | `npx sdlc-harness upgrade` | Runs migrations and sync for already-adopted projects. |
+| Managed file sync | `npx sdlc-harness sync` | Materializes package canonical assets and safely updates package-managed guidance sections inside user-owned Markdown files while preserving project state, docs and local overrides. |
+| Upgrade | `npx sdlc-harness upgrade` | Runs migrations and sync for already-adopted projects, including legacy seed guidance migration. |
 | Diagnostics | `npx sdlc-harness doctor` | Reports Harness root, package version, schema version and key managed paths. |
 | Validators | `npx sdlc-harness validate-*`, `make validate-current`, `make validate-harness` | Checks product, design slicing, development, review, test, release, RFC, active plan shape, prompt language contract and generated overview freshness. |
 | Lifecycle workflow | `<harnessRoot>/state/lifecycle.yaml`, `<harnessRoot>/state/plan.yaml`, `.docs/**` | Tracks REQUIREMENT_GATHERING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING and RFC_RECALIBRATION facts. |
@@ -84,9 +84,9 @@ Before development starts, `ARCHITECTING` can return to `REQUIREMENT_GATHERING`
 
 `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.
+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. The current task implementation doc must also include `Development Evidence` with `Runnable Entry`, `Observable Exit`, `Basic Self-test Evidence`, or a justified `Not applicable`. REVIEWING treats missing entry/exit or development evidence as blocking, and TESTING only exercises existing entrypoints; 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 and linked runnable-entry implementation docs. `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, 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 tasks need a command, endpoint or invocation plus 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.
 
@@ -98,6 +98,8 @@ Do not create formal `.docs/07_test/**` test cases or reports before development
 
 `<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.
 
+`sync` and `upgrade` also maintain fixed package-managed sections inside user-owned Markdown files: `## Harness Guidance` in `<harnessRoot>/state/memory.md` and `## Harness Maintenance Rules` in `.docs/INDEX.md`. User memory entries, artifact maps and links stay outside those sections and are preserved. Legacy untitled seed guidance is migrated into the titled section to avoid duplicates. `.github/workflows/harness.yml` is updated only when it has `pjsdlc:sdlc-harness:github-workflow:*` markers or exactly matches the old generated workflow; customized workflows without markers are skipped and reported as `customized`.
+
 ## Common Commands
 
 ```sh

package/assets/docs/README.md

@@ -57,8 +57,8 @@ npx sdlc-harness init --adopt
 | 新项目初始化 | `npx sdlc-harness init` | 选择目标 Agent，生成 Harness 根目录、状态文件、workflow skills、模板、策略、`.docs/**` 和 Makefile include |
 | 已有项目接入 | `npx sdlc-harness init --adopt` | 非破坏性接入已有仓库，不覆盖业务代码和已有项目事实源 |
 | 可配置 Harness 根目录 | `--harness-folder`、`package.json#sdlcHarness.harnessFolderName`、`sdlc-harness.config.json` | 支持 `.codex`、`.claude`、`.cursor`、`.cline`、`.roo`、`.gemini` 或自定义目录 |
-| 同步 managed workflow 文件 | `npx sdlc-harness sync` | 从包内 canonical assets 物化 `AGENTS.md` managed block、workflow skills、templates、policies、Makefile 片段和 GitHub workflow |
-| 升级已接入项目 | `npx sdlc-harness upgrade` | 执行迁移并自动 `sync`，保留 state、docs、业务代码和本地 override |
+| 同步 managed workflow 文件 | `npx sdlc-harness sync` | 从包内 canonical assets 物化 `AGENTS.md` managed block、workflow skills、templates、policies、Makefile 片段、GitHub workflow，并安全更新 user-owned Markdown guidance sections |
+| 升级已接入项目 | `npx sdlc-harness upgrade` | 执行迁移并自动 `sync`，保留 state、docs、业务代码和本地 override，同时迁移旧 seed guidance |
 | 接入诊断 | `npx sdlc-harness doctor` | 检查 harness root、版本、schema、关键文件和 managed paths |
 | 阶段 gate | `npx sdlc-harness validate-*`、`make validate-current`、`make validate-harness` | 校验需求、设计切片、开发、Review、测试、发布、RFC、Harness 骨架、提示词语言契约和 overview freshness |
 | 生命周期工作流 | `lifecycle.yaml`、`plan.yaml`、`.docs/**` | 固定 REQUIREMENT_GATHERING、ARCHITECTING、SPRINTING、REVIEWING、TESTING、RELEASING、RFC_RECALIBRATION 等阶段事实链 |
@@ -105,9 +105,9 @@ Agent 会读取 `<harnessRoot>/state/lifecycle.yaml` 和 `<harnessRoot>/state/pl
 
 `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。
+SPRINTING 的 Definition of Done 包含可运行入口/出口：技术方案或 task 承诺的 API、CLI、server route、adapter、worker、provider、配置契约和 fixture/live 边界必须在开发阶段实现或明确 `BLOCKED`。当前 task 的 implementation doc 还必须写入 `Development Evidence`，包含 `Runnable Entry`、`Observable Exit`、`Basic Self-test Evidence`，或带原因的 `Not applicable`。REVIEWING 会把缺少入口/出口或开发自测证据作为阻断项；TESTING 只调用既有入口做输入输出验证，不能新增 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` 和 implementation doc。`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`、implementation doc 和结构化 `Development Evidence`。页面类证据需要 dev server/page URL 与 browser check；API/CLI/worker 类证据需要 command/endpoint/invocation 与 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。
 
@@ -119,6 +119,8 @@ SPRINTING 的 Definition of Done 包含可运行入口/出口：技术方案或
 
 `<harnessRoot>/state/memory.md` 只做跨阶段快捷提示和导航，回答“下次进来要先记住什么、去哪里找”。memory 可以链接到 ADR、PRD、tech plan 或 implementation doc；完整背景、备选方案、取舍和长期后果放在 `.docs/05_decisions/` ADR 或其它正式 `.docs/**` 事实源里。
 
+`sync` / `upgrade` 会维护用户耦合文件里的固定 package-managed sections：`<harnessRoot>/state/memory.md` 的 `## Harness Guidance` 和 `.docs/INDEX.md` 的 `## Harness Maintenance Rules`。用户自己的 memory 条目、文档产物地图和链接保留在这些标题区块之外；如果旧项目只有早期无标题 seed 文案，升级会把它迁移到固定标题区块，避免重复。`.github/workflows/harness.yml` 只在文件带 `pjsdlc:sdlc-harness:github-workflow:*` marker 或内容等于旧版 generated workflow 时自动更新；自定义且无 marker 的 workflow 会被跳过并报告 `customized`。
+
 ### Workflow skill 如何生效
 
 `<harnessRoot>/skills/<name>/SKILL.md` 是 Harness 的 workflow skill 事实源，也是稳定的 hard file index。它有两种使用方式：

package/assets/github/harness.yml

@@ -1,3 +1,4 @@
+# pjsdlc:sdlc-harness:github-workflow:begin
 name: Harness Gates
 
 on:
@@ -43,3 +44,4 @@ jobs:
         run: make "${HARNESS_GATE}"
         env:
           HARNESS_GATE: ${{ github.event.inputs.gate || 'validate-harness' }}
+# pjsdlc:sdlc-harness:github-workflow:end

package/assets/policies/gates.yaml

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

package/assets/policies/phase_contracts.yaml

@@ -45,7 +45,7 @@ phases:
       - "REQUIREMENT_GATHERING"
 
   SPRINTING:
-    goal: "按任务状态执行开发、消费已采用草案、开发验证和实现文档沉淀"
+    goal: "按任务状态执行开发、消费已采用草案、开发验证、Development Evidence 和实现文档沉淀"
     role: "developer"
     skill: "pjsdlc_dev_sprint"
     inputs:

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、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，当前实现必须提供对应入口、调用方式、输出/副作用边界和验证方式；如果真实入口/出口尚不可运行，不能把 task 当作完成，也不能把缺口留给 TESTING 补 runtime。Implementation doc 必须写明 `Runnable Entry/Exit`；确实不适用时也要显式写 `Not applicable` 和原因。此时应保留或创建 `BLOCKED`/后续 dev task，或通过 RFC/ARCHITECTING 处理边界变更。
+开发阶段的 Definition of Done 包含可运行的系统入口/出口。凡技术方案或 task 承诺 API、CLI、server route、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，当前实现必须提供对应入口、调用方式、输出/副作用边界和验证方式；如果真实入口/出口尚不可运行，不能把 task 当作完成，也不能把缺口留给 TESTING 补 runtime。Implementation doc 必须写明 `Runnable Entry/Exit`，并在 `Development Evidence` 中记录 `Runnable Entry`、`Observable Exit`、`Basic Self-test Evidence`；确实不适用时也要显式写 `Not applicable` 和具体原因。此时应保留或创建 `BLOCKED`/后续 dev task，或通过 RFC/ARCHITECTING 处理边界变更。
+
+页面类任务在开发阶段必须启动 dev server 或等价预览入口，并用浏览器、Playwright、截图或等价方式验证页面可加载、主入口可访问、核心按钮/表单/跳转可用、没有明显报错或空白页。API/CLI/worker/RPA 类任务必须记录实际调用命令、endpoint、worker command、dry-run/live preflight 或 server action，以及可观察的 response、队列 item、审计日志、文件产物、发送结果、错误码或 PASS/BLOCKED 结果。
 
 `/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。
 
@@ -37,7 +39,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、配置契约和 fixture/live 边界事实
+- implementation doc 中的 runnable entry/exit、observable exit、basic self-test evidence、配置契约和 fixture/live 边界事实
 - 更新后的 `<harnessRoot>/state/plan.yaml`
 - 如果本轮 promote draft，更新后的 `<harnessRoot>/state/plan.draft.yaml`
 - 更新后的 `.docs/INDEX.md`
@@ -85,7 +87,7 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 6. 如果 gate 因代码或测试逻辑失败，在任务范围内修复。
 7. 如果 gate 因基础设施、凭证缺失、产品行为不清或高风险架构变化失败，进入 `BLOCKED`。
 8. gate 通过后调用 `pjsdlc_implementation_doc`。
-9. 只有 gate 通过、承诺的 runnable entry/exit 已实现或明确 `BLOCKED`，且 implementation doc 校验通过后，才能把任务标记为 `done`。
+9. 只有 gate 通过、承诺的 runnable entry/exit 已实现或明确 `BLOCKED`，implementation doc 包含结构化 `Development Evidence`，且 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。
@@ -103,6 +105,7 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 - [ ] open task 在 `plan.yaml` 中包含完整执行合同。
 - [ ] 当前任务仍然是单一清晰的执行单元。
 - [ ] 技术方案或 task 承诺的 API/CLI/adapter/worker/provider、配置契约、输出/副作用和 fixture/live 边界已可运行并写入 implementation doc，或已明确 `BLOCKED`/后续 dev task。
+- [ ] implementation doc `Development Evidence` 已记录 `Runnable Entry`、`Observable Exit`、`Basic Self-test Evidence`，或写明带原因的 `Not applicable`。
 - [ ] 如果当前 task 来自 `plan.draft.yaml.tasks[]`，源 draft 已在 promote 时从 draft 列表删除。
 - [ ] implementation doc 已生成或更新，并反映相关模块的真实代码。
 - [ ] 如果启用了 `parallel_execution`，worker owned paths、forbidden paths、required gates 和主 Agent 集成结果已记录。

package/assets/skills/pjsdlc_implementation_doc/SKILL.md

@@ -17,7 +17,7 @@ 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 模式边界，以及哪些真实外部执行器尚未实现。不能把未来才会实现的入口写成当前事实。
+如果模块包含或承诺可运行系统边界，implementation doc 必须记录 runnable entry/exit：API/CLI/server route/adapter/worker/provider 的调用方式、配置契约、输入来源、输出或副作用、fixture/live 模式边界，以及哪些真实外部执行器尚未实现。还必须在 `Development Evidence` 中记录开发阶段实际验证过的 `Runnable Entry`、`Observable Exit` 和 `Basic Self-test Evidence`；确实没有应用入口时，`Not applicable` 必须写清原因。不能把未来才会实现的入口写成当前事实。
 
 ## 输入
 
@@ -48,8 +48,9 @@ description: Use after development gates pass to update module-level implementat
 2. 每个被记录的文件都应说明它在该模块或数据流中的作用和关键函数/对象。
 3. 与技术方案的偏移必须明确记录，即便该偏移是合理的。
 4. runnable entry/exit、配置契约和 fixture/live 边界必须记录当前事实；缺失项写入 `未覆盖（Not covered）` 或方案偏移。
-5. 测试覆盖必须列出具体测试，或明确记录覆盖缺口。
-6. 文档粒度保持在模块、子系统或核心数据流级别；不要默认按 task 建文档，也不要写成跨全项目的巨型百科。
+5. `Development Evidence` 必须包含实际可调用入口、可观察出口和开发自测证据；页面类任务记录 dev server/page URL 与 browser check，API/CLI/worker/RPA 类任务记录 invocation command/endpoint 与 response/output/side effect。
+6. 测试覆盖必须列出具体测试，或明确记录覆盖缺口。
+7. 文档粒度保持在模块、子系统或核心数据流级别；不要默认按 task 建文档，也不要写成跨全项目的巨型百科。
 
 ## 完成检查
 
@@ -58,6 +59,7 @@ description: Use after development gates pass to update module-level implementat
 - [ ] 真实代码结构表已填写。
 - [ ] 核心数据流已说明。
 - [ ] runnable entry/exit、配置契约和 fixture/live 边界已记录，或缺失项已明确标注。
+- [ ] `Development Evidence` 已记录 `Runnable Entry`、`Observable Exit`、`Basic Self-test Evidence`，或带原因的 `Not applicable`。
 - [ ] 已判断 implementation doc 的语义切片边界。
 - [ ] 方案偏移和测试覆盖已记录。
 - [ ] `.docs/INDEX.md` 已链接 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、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，Review 都要核对真实代码和实现文档是否提供可调用入口、输出/副作用边界和验证方式；缺失时 gate decision 应为 `BLOCKED`，并要求回到 SPRINTING/RFC，而不是允许进入 TESTING 后补 runtime。Review 不创建 `.docs/07_test/**` 正式测试产物；如果发现现有测试事实源仍链接已被 RFC supersede 的旧路线证据，应将其列为进入 TESTING 前的 blocker，并要求 RFC 清理或更新索引。
+Review 必须把“当前模块没有可运行入口/出口”视为阻断项，而不是普通测试缺口。凡 PRD、技术方案或 implementation doc 承诺 API、CLI、server route、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，Review 都要核对真实代码和实现文档是否提供可调用入口、输出/副作用边界和验证方式；implementation doc 还必须包含结构化 `Development Evidence`，说明 `Runnable Entry`、`Observable Exit` 和 `Basic Self-test Evidence`，或带原因的 `Not applicable`。缺失时 gate decision 应为 `BLOCKED`，并要求回到 SPRINTING/RFC，而不是允许进入 TESTING 后补 runtime。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 边界时，必须作为 P0/P1 blocking finding。
+5. 缺少已承诺的 runnable entry/exit、配置契约、fixture/live 边界或 `Development Evidence` 时，必须作为 P0/P1 blocking finding。
 6. 如果未发现问题，明确说明，并列出剩余测试缺口或残余风险。
 7. Review 阶段一次只执行一个 `TASK-*` task。
 
@@ -78,6 +78,7 @@ Review 阶段受 `plan.yaml` 管控：
 - [ ] 已评估需求一致性。
 - [ ] 已评估架构和可维护性风险。
 - [ ] 已评估 runnable entry/exit、配置契约和 fixture/live 边界是否足以进入 TESTING。
+- [ ] 已评估 implementation doc 是否包含 Runnable Entry、Observable Exit 和 Basic Self-test Evidence。
 - [ ] 已判断 review slice 的范围和风险主题边界。
 - [ ] 已列出测试缺口。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。

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 已经交付的入口做输入/输出验证。可以补充测试、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 建议，并停止把测试阶段扩大成开发/集成搭建。开发尚未交付可测试 entry/exit 时，不要在 `.docs/07_test/**` 提前生成正式测试用例或正式报告；验收思路应留在 PRD acceptance criteria、tech plan verification strategy 或非 `.docs/07_test/**` 的草稿说明里。
+TESTING 只能调用 SPRINTING 已经交付的入口做输入/输出验证。可以补充测试、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 模式不可调用、配置契约缺失或用户目标与已实现通道不一致，应记录 `BLOCKED`、生成 RFC 或后续 dev task 建议，并停止把测试阶段扩大成开发/集成搭建。开发尚未交付可测试 entry/exit 时，不要在 `.docs/07_test/**` 提前生成正式测试用例或正式报告；验收思路应留在 PRD acceptance criteria、tech plan verification strategy 或非 `.docs/07_test/**` 的草稿说明里。
 
 测试设计和回归证据产出本身也是 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,11 +67,11 @@ TESTING 只能调用 SPRINTING 已经交付的入口做输入/输出验证。可
 
 ## 规则
 
-1. 测试用例必须追溯到 PRD acceptance criteria 或 Review findings，并绑定 SPRINTING/REVIEWING 已确认的 runnable entry/exit。
+1. 测试用例必须追溯到 PRD acceptance criteria 或 Review findings，并绑定 SPRINTING/REVIEWING 已确认的 runnable entry/exit 和 Development Evidence。
 2. 根据风险补充边界、负向、回归和集成测试。
 3. 如果有意延后覆盖，必须记录风险和 follow-up。
 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 的具体条件。
+5. 测试发现入口/出口或 Development Evidence 缺失时，Final decision 必须为 `BLOCKED`，并指出回到 SPRINTING/RFC 的具体条件。
 6. 新测试策略使用 `.docs/07_test/TEST_STRATEGY.md`，新测试用例使用 `.docs/07_test/TEST_CASES.md`，执行报告使用 `.docs/07_test/TEST_REPORT.md`；不要新建或继续依赖 `.docs/07_test/TEST_PLAN.md`。
 7. `TEST_REPORT.md` 不得包含 `pending`、`TBD`、`待填`、`TODO` 或占位结论；未执行或不可执行时 Final decision 必须为 `BLOCKED` 并给出恢复条件。
 8. RFC 改变技术路线、entry/exit 或验收边界后，必须确认 `.docs/07_test/**` 中旧路线测试证据已删除或不再从 `.docs/INDEX.md` 暴露。
@@ -86,6 +86,7 @@ TESTING 只能调用 SPRINTING 已经交付的入口做输入/输出验证。可
 - [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] Regression checklist 已完成。
 - [ ] 测试只调用既有 runnable entry/exit；未在 TESTING 中新增 product runtime、bootstrap、provider adapter、deploy 或 package runtime script。
+- [ ] 已核对 implementation doc 中的 Development Evidence，并只基于已交付入口设计测试。
 - [ ] 已判断 test report / test matrix 的语义切片边界。
 - [ ] 未把测试计划、测试用例或待填内容写成 `TEST_REPORT.md`。
 - [ ] 已确认 `.docs/07_test/**` 只包含当前方案仍有效的测试事实。

package/assets/templates/IMPLEMENTATION_DOC_TEMPLATE.md

@@ -40,7 +40,14 @@ Input
 - Fixture/live boundary:
 - Missing runtime boundaries:
 
-## 6. 关键实现逻辑
+## 6. Development Evidence（开发自测证据）
+
+- Runnable Entry:
+- Observable Exit:
+- Basic Self-test Evidence:
+- Not applicable:
+
+## 7. 关键实现逻辑
 
 - 输入校验（Input validation）:
 - 核心分支（Core branches）:
@@ -48,22 +55,22 @@ Input
 - 边界兜底（Boundary fallback）:
 - 性能或并发注意事项（Performance or concurrency notes）:
 
-## 7. 与技术方案的偏移
+## 8. 与技术方案的偏移
 
 - 
 
-## 8. 测试覆盖（Test Coverage）
+## 9. 测试覆盖（Test Coverage）
 
 | 测试（Test） | 覆盖范围（Coverage） | 结果（Result） |
 |---|---|---|
 |  |  |  |
 
-## 9. 变更记录（Change Log）
+## 10. 变更记录（Change Log）
 
 | 日期（Date） | Task ID | Commit | 摘要（Summary） |
 |---|---|---|---|
 |  |  |  |  |
 
-## 10. 后续维护注意事项
+## 11. 后续维护注意事项
 
 - 

package/assets/templates/REVIEW_TEMPLATE.md

@@ -31,6 +31,7 @@
 - Exit / side effects:
 - Config contract:
 - Fixture/live boundary:
+- Development Evidence:
 - Blocking gaps before TESTING:
 
 ## 7. Gate Result（阶段结论）

package/assets/templates/TEST_CASES_TEMPLATE.md

@@ -5,6 +5,7 @@
 - PRD:
 - Technical design:
 - Runnable entry/exit under test:
+- Development Evidence under test:
 
 ## 2. Cases（用例）
 

package/assets/templates/TEST_REPORT_TEMPLATE.md

@@ -24,6 +24,7 @@
 
 - Existing entry points under test:
 - Expected exits / side effects:
+- Development Evidence used:
 - Config contract used:
 - Fixture/live boundary:
 - Missing entry/exit blocker:

package/dist/commands/sync.js

@@ -2,6 +2,9 @@ import { runSync } from "../lib/sync-engine.js";
 export async function sync() {
     const report = await runSync(process.cwd());
     console.log(`sync changed=${report.changed.length} skipped=${report.skipped.length} blocked=${report.blocked.length}`);
+    for (const skipped of report.skipped.filter((line) => line.includes("customized"))) {
+        console.log(`skipped: ${skipped}`);
+    }
     for (const blocked of report.blocked) {
         console.error(`blocked: ${blocked}`);
     }

package/dist/lib/init.js

@@ -3,6 +3,7 @@ import { writeConfigIfMissing } from "./config.js";
 import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
 import { ensureDir, pathExists, writeTextIfChanged } from "./fs.js";
 import { runSync } from "./sync-engine.js";
+import { syncDocsIndexMaintenanceSection, syncMemoryGuidanceSection } from "./user-owned-sections.js";
 const DOC_DIRS = [
     ".docs/00_raw",
     ".docs/01_product",
@@ -55,24 +56,24 @@ 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/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。\n"
-        ]
     ];
     for (const [relative, content] of files) {
         if (await writeTextIfChanged(path.join(projectRoot, relative), content)) {
             report.push(`created ${relative}`);
         }
     }
+    await syncMemoryGuidanceSection(projectRoot, root, {
+        changed: report,
+        skipped: []
+    });
 }
 async function createDocs(projectRoot, report) {
     for (const dir of DOC_DIRS) {
         await ensureDir(path.join(projectRoot, dir));
         await writeTextIfChanged(path.join(projectRoot, dir, ".gitkeep"), "");
     }
-    const index = ".docs/INDEX.md";
-    if (await writeTextIfChanged(path.join(projectRoot, index), "# Documentation Index\n\n本文件是 AI SDLC Harness 的文档路由表。\n")) {
-        report.push(`created ${index}`);
-    }
+    await syncDocsIndexMaintenanceSection(projectRoot, {
+        changed: report,
+        skipped: []
+    });
 }

package/dist/lib/managed-file.d.ts

@@ -10,6 +10,8 @@ export declare const MAKEFILE_BLOCK_START = "# pjsdlc:sdlc-harness:make:begin";
 export declare const MAKEFILE_BLOCK_END = "# pjsdlc:sdlc-harness:make:end";
 export declare const LEGACY_MAKEFILE_BLOCK_START = "# sdlc-harness:make:begin";
 export declare const LEGACY_MAKEFILE_BLOCK_END = "# sdlc-harness:make:end";
+export declare const GITHUB_WORKFLOW_BLOCK_START = "# pjsdlc:sdlc-harness:github-workflow:begin";
+export declare const GITHUB_WORKFLOW_BLOCK_END = "# pjsdlc:sdlc-harness:github-workflow:end";
 export declare const MANAGED_METADATA_START = "<!-- pjsdlc:sdlc-harness-managed";
 export declare const LEGACY_MANAGED_METADATA_START = "<!-- sdlc-harness-managed";
 export declare const MANAGED_METADATA_END = "-->";

package/dist/lib/managed-file.js

@@ -6,6 +6,8 @@ export const MAKEFILE_BLOCK_START = "# pjsdlc:sdlc-harness:make:begin";
 export const MAKEFILE_BLOCK_END = "# pjsdlc:sdlc-harness:make:end";
 export const LEGACY_MAKEFILE_BLOCK_START = "# sdlc-harness:make:begin";
 export const LEGACY_MAKEFILE_BLOCK_END = "# sdlc-harness:make:end";
+export const GITHUB_WORKFLOW_BLOCK_START = "# pjsdlc:sdlc-harness:github-workflow:begin";
+export const GITHUB_WORKFLOW_BLOCK_END = "# pjsdlc:sdlc-harness:github-workflow:end";
 export const MANAGED_METADATA_START = "<!-- pjsdlc:sdlc-harness-managed";
 export const LEGACY_MANAGED_METADATA_START = "<!-- sdlc-harness-managed";
 export const MANAGED_METADATA_END = "-->";

package/dist/lib/migrations.js

@@ -3,6 +3,7 @@ import { readdir, rename, rm } from "node:fs/promises";
 import { defaultConfig, readConfig } from "./config.js";
 import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
 import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
+import { syncDocsIndexMaintenanceSection, syncMemoryGuidanceSection } from "./user-owned-sections.js";
 import { parseYaml, stringifyYaml } from "./yaml.js";
 export const CURRENT_SCHEMA_VERSION = "1";
 export const migrations = [];
@@ -27,7 +28,7 @@ export async function runMigrations(projectRoot) {
     await migratePlan(projectRoot, root, report, "plan.draft.yaml", "tasks.draft.yaml", { activePlan: false });
     await removeLegacyGateResults(projectRoot, root, report);
     await removeLegacyCheckpoints(projectRoot, root, report);
-    await ensureMemory(projectRoot, root, report);
+    await ensureUserOwnedGuidanceSections(projectRoot, root, report);
     return report;
 }
 async function migrateConfig(projectRoot, root, report) {
@@ -161,6 +162,9 @@ function migrateManagedFiles(managedFiles, root) {
             migrated.unshift(makefileEntry);
         }
     }
+    if (!seen.has(".github/workflows/harness.yml")) {
+        push({ path: ".github/workflows/harness.yml", strategy: "create-if-missing" });
+    }
     return migrated;
 }
 async function migrateLifecycle(projectRoot, root, report) {
@@ -349,15 +353,7 @@ async function removeLegacyGateResults(projectRoot, root, report) {
     await rm(gateResultsPath, { force: true });
     report.changed.push(relativeGateResultsPath);
 }
-async function ensureMemory(projectRoot, root, report) {
-    const relativeMemoryPath = harnessPath(root, "state", "memory.md");
-    const memoryPath = path.join(projectRoot, relativeMemoryPath);
-    if (await pathExists(memoryPath)) {
-        report.skipped.push(relativeMemoryPath);
-        return;
-    }
-    const content = "# Project Memory\n\n记录跨阶段长期有效知识的简短摘要和链接。完整决策背景、备选方案、取舍和后果写入 `.docs/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。\n";
-    if (await writeTextIfChanged(memoryPath, content)) {
-        report.changed.push(relativeMemoryPath);
-    }
+async function ensureUserOwnedGuidanceSections(projectRoot, root, report) {
+    await syncMemoryGuidanceSection(projectRoot, root, report);
+    await syncDocsIndexMaintenanceSection(projectRoot, report);
 }

package/dist/lib/sync-engine.js

@@ -2,8 +2,9 @@ import path from "node:path";
 import { readConfig } from "./config.js";
 import { harnessRoot } from "./harness-root.js";
 import { copyTree, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
-import { AGENTS_BLOCK_MARKERS, MAKEFILE_BLOCK_END, MAKEFILE_BLOCK_MARKERS, MAKEFILE_BLOCK_START, MANAGED_BLOCK_END, MANAGED_BLOCK_START } from "./managed-file.js";
+import { AGENTS_BLOCK_MARKERS, GITHUB_WORKFLOW_BLOCK_END, GITHUB_WORKFLOW_BLOCK_START, MAKEFILE_BLOCK_END, MAKEFILE_BLOCK_MARKERS, MAKEFILE_BLOCK_START, MANAGED_BLOCK_END, MANAGED_BLOCK_START } from "./managed-file.js";
 import { packageAssetPath } from "./paths.js";
+import { syncProjectGuidanceSections } from "./user-owned-sections.js";
 import { parseYaml, stringifyYaml } from "./yaml.js";
 export function emptySyncReport() {
     return {
@@ -19,6 +20,7 @@ export async function runSync(projectRoot) {
     for (const managedFile of config.managed_files) {
         await syncManagedFile(projectRoot, root, managedFile, report);
     }
+    await syncProjectGuidanceSections(projectRoot, root, report);
     return report;
 }
 async function syncManagedFile(projectRoot, root, managedFile, report) {
@@ -48,11 +50,7 @@ async function syncManagedFile(projectRoot, root, managedFile, report) {
         return;
     }
     if (managedFile.path === ".github/workflows/harness.yml") {
-        if (await pathExists(destination)) {
-            report.skipped.push(managedFile.path);
-            return;
-        }
-        await syncFile(packageAssetPath("github", "harness.yml"), destination, report, "skip-if-missing");
+        await syncGithubWorkflow(packageAssetPath("github", "harness.yml"), destination, managedFile.path, report);
         return;
     }
     report.skipped.push(managedFile.path);
@@ -368,3 +366,61 @@ async function syncFile(source, destination, report, missingMode) {
         report.skipped.push(destination);
     }
 }
+async function syncGithubWorkflow(source, destination, relativePath, report) {
+    if (!(await pathExists(source))) {
+        report.skipped.push(relativePath);
+        return;
+    }
+    const sourceContent = await readText(source);
+    if (!(await pathExists(destination))) {
+        if (await writeTextIfChanged(destination, sourceContent)) {
+            report.changed.push(relativePath);
+        }
+        else {
+            report.skipped.push(relativePath);
+        }
+        return;
+    }
+    const existing = await readText(destination);
+    const markerState = workflowMarkerState(existing);
+    if (markerState === "invalid") {
+        report.blocked.push(`${relativePath}: incomplete managed workflow markers`);
+        return;
+    }
+    if (markerState === "managed" || normalizeWorkflow(existing) === normalizeWorkflow(stripWorkflowMarkers(sourceContent))) {
+        if (await writeTextIfChanged(destination, sourceContent)) {
+            report.changed.push(relativePath);
+        }
+        else {
+            report.skipped.push(relativePath);
+        }
+        return;
+    }
+    report.skipped.push(`${relativePath}: customized`);
+}
+function workflowMarkerState(content) {
+    const startIndex = content.indexOf(GITHUB_WORKFLOW_BLOCK_START);
+    const endIndex = content.indexOf(GITHUB_WORKFLOW_BLOCK_END);
+    const hasStart = startIndex >= 0;
+    const hasEnd = endIndex >= 0;
+    if (!hasStart && !hasEnd) {
+        return "missing";
+    }
+    if (hasStart !== hasEnd || endIndex < startIndex) {
+        return "invalid";
+    }
+    if (content.indexOf(GITHUB_WORKFLOW_BLOCK_START, startIndex + GITHUB_WORKFLOW_BLOCK_START.length) >= 0 ||
+        content.indexOf(GITHUB_WORKFLOW_BLOCK_END, endIndex + GITHUB_WORKFLOW_BLOCK_END.length) >= 0) {
+        return "invalid";
+    }
+    return "managed";
+}
+function stripWorkflowMarkers(content) {
+    return content
+        .split(/\r?\n/)
+        .filter((line) => line.trim() !== GITHUB_WORKFLOW_BLOCK_START && line.trim() !== GITHUB_WORKFLOW_BLOCK_END)
+        .join("\n");
+}
+function normalizeWorkflow(content) {
+    return content.replace(/\r\n/g, "\n").trim();
+}

package/dist/lib/upgrade.js

@@ -7,6 +7,9 @@ export async function runUpgrade(projectRoot) {
     lines.push(`migrations changed=${migrationReport.changed.length} skipped=${migrationReport.skipped.length}`);
     const syncReport = await runSync(projectRoot);
     lines.push(`sync changed=${syncReport.changed.length} skipped=${syncReport.skipped.length} blocked=${syncReport.blocked.length}`);
+    for (const skipped of syncReport.skipped.filter((line) => line.includes("customized"))) {
+        lines.push(`sync skipped: ${skipped}`);
+    }
     const doctor = await runDoctor(projectRoot);
     lines.push(`doctor warnings=${doctor.warnings.length} errors=${doctor.errors.length}`);
     if (syncReport.blocked.length > 0 || doctor.errors.length > 0) {

package/dist/lib/user-owned-sections.d.ts

@@ -0,0 +1,7 @@
+export interface UserOwnedSectionReport {
+    changed: string[];
+    skipped: string[];
+}
+export declare function syncProjectGuidanceSections(projectRoot: string, root: string, report: UserOwnedSectionReport): Promise<void>;
+export declare function syncMemoryGuidanceSection(projectRoot: string, root: string, report: UserOwnedSectionReport): Promise<void>;
+export declare function syncDocsIndexMaintenanceSection(projectRoot: string, report: UserOwnedSectionReport): Promise<void>;

package/dist/lib/user-owned-sections.js

@@ -0,0 +1,105 @@
+import path from "node:path";
+import { pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { harnessPath } from "./harness-root.js";
+const MEMORY_GUIDANCE_HEADING = "## Harness Guidance";
+const DOCS_INDEX_RULES_HEADING = "## Harness Maintenance Rules";
+const LEGACY_MEMORY_PARAGRAPHS = [
+    "短期执行计划写入 plan.yaml；长期稳定知识只在这里记录简短摘要和链接。完整决策背景、备选方案、取舍和后果写入 `.docs/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。",
+    "记录跨阶段长期有效知识的简短摘要和链接。完整决策背景、备选方案、取舍和后果写入 `.docs/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。",
+    "内容保持简短，详细说明链接到 `.docs/` 下的对应文档。完整决策背景、备选方案、取舍和后果应写入 `.docs/05_decisions/` ADR 或其它正式 `.docs/**` 事实源。"
+];
+const LEGACY_INDEX_MAINTENANCE_SECTION = [
+    "## 维护规则",
+    "",
+    "- 每个新增产物都要从本索引链接。",
+    "- 仍属于产品、架构、实现、测试或 RFC 事实源的过时产物标记为 superseded；短期执行计划和历史发布流水以 git、tag、registry、CI 或外部 release 系统追溯。",
+    "- task/release 的历史动作记录以 git commit、tag 或外部 release 系统为准，不再维护 `<harnessRoot>/archive/` 常规归档。",
+    "- implementation docs 必须对齐真实代码，而不只是原始技术方案。"
+].join("\n");
+export async function syncProjectGuidanceSections(projectRoot, root, report) {
+    await syncMemoryGuidanceSection(projectRoot, root, report);
+    await syncDocsIndexMaintenanceSection(projectRoot, report);
+}
+export async function syncMemoryGuidanceSection(projectRoot, root, report) {
+    const relativePath = harnessPath(root, "state", "memory.md");
+    const targetPath = path.join(projectRoot, relativePath);
+    const existing = (await pathExists(targetPath)) ? await readText(targetPath) : "# Project Memory\n";
+    const next = mergeMarkdownSection(removeLegacyMemoryGuidance(existing), MEMORY_GUIDANCE_HEADING, renderMemoryGuidanceSection(root));
+    await writeSectionIfChanged(targetPath, relativePath, next, report);
+}
+export async function syncDocsIndexMaintenanceSection(projectRoot, report) {
+    const relativePath = ".docs/INDEX.md";
+    const targetPath = path.join(projectRoot, relativePath);
+    const existing = (await pathExists(targetPath))
+        ? await readText(targetPath)
+        : "# Documentation Index\n\n本文件是 AI SDLC Harness 的文档路由表。\n";
+    const next = mergeMarkdownSection(removeLegacyIndexMaintenanceSection(existing), DOCS_INDEX_RULES_HEADING, renderDocsIndexMaintenanceSection());
+    await writeSectionIfChanged(targetPath, relativePath, next, report);
+}
+function renderMemoryGuidanceSection(root) {
+    const planPath = harnessPath(root, "state", "plan.yaml");
+    return [
+        MEMORY_GUIDANCE_HEADING,
+        "",
+        "- 内容保持简短，详细说明链接到 `.docs/` 下的对应文档。",
+        `- 短期执行计划写入 \`${planPath}\`；长期稳定知识只在这里记录简短摘要和链接。`,
+        "- 完整决策背景、备选方案、取舍和后果应写入 `.docs/05_decisions/` ADR 或其它正式 `.docs/**` 事实源。"
+    ].join("\n");
+}
+function renderDocsIndexMaintenanceSection() {
+    return [
+        DOCS_INDEX_RULES_HEADING,
+        "",
+        "- `overview.md` 是 generated artifact，用于浏览和阶段交接；不要手写或局部编辑。",
+        "- Markdown slices 和 `.docs/INDEX.md` 是事实源。",
+        "- 任意 `.docs/<stage>/**/*.md` 新增、修改、拆分、合并或废弃后，运行 `make docs-overview`。",
+        "- 提交或阶段交付前，运行 `make validate-doc-overviews` 或 `make validate-harness` 确认 overview 未过期。",
+        "- 每个新增产物都要从本索引链接；implementation docs 必须对齐真实代码。"
+    ].join("\n");
+}
+function removeLegacyMemoryGuidance(content) {
+    let next = content;
+    for (const paragraph of LEGACY_MEMORY_PARAGRAPHS) {
+        next = next.replace(paragraph, "");
+    }
+    return compactBlankLines(next);
+}
+function removeLegacyIndexMaintenanceSection(content) {
+    return compactBlankLines(content.replace(LEGACY_INDEX_MAINTENANCE_SECTION, ""));
+}
+function mergeMarkdownSection(existing, heading, section) {
+    const normalizedExisting = existing.replace(/\r\n/g, "\n").trimEnd();
+    const normalizedSection = section.trimEnd();
+    if (!normalizedExisting) {
+        return `${normalizedSection}\n`;
+    }
+    const lines = normalizedExisting.split("\n");
+    const startIndex = lines.findIndex((line) => line.trim() === heading);
+    if (startIndex < 0) {
+        return `${normalizedExisting}\n\n${normalizedSection}\n`;
+    }
+    const headingLevel = heading.match(/^#+/)?.[0].length ?? 2;
+    let endIndex = lines.length;
+    for (let index = startIndex + 1; index < lines.length; index += 1) {
+        const match = lines[index].match(/^(#{1,6})\s+/);
+        if (match && match[1].length <= headingLevel) {
+            endIndex = index;
+            break;
+        }
+    }
+    const before = lines.slice(0, startIndex).join("\n").trimEnd();
+    const after = lines.slice(endIndex).join("\n").trimStart();
+    const parts = [before, normalizedSection, after].filter((part) => part.trim());
+    return `${parts.join("\n\n")}\n`;
+}
+async function writeSectionIfChanged(targetPath, relativePath, content, report) {
+    if (await writeTextIfChanged(targetPath, content)) {
+        report.changed.push(relativePath);
+    }
+    else {
+        report.skipped.push(relativePath);
+    }
+}
+function compactBlankLines(content) {
+    return content.replace(/\r\n/g, "\n").replace(/\n{3,}/g, "\n\n");
+}

package/dist/lib/validators.js

@@ -83,6 +83,36 @@ const RUNNABLE_ENTRY_EXIT_TERMS = [
     "入口/出口",
     "not applicable"
 ];
+const DEVELOPMENT_EVIDENCE_TERMS = ["development evidence", "开发自测证据"];
+const EVIDENCE_PLACEHOLDER_TERMS = [
+    "pending",
+    "tbd",
+    "todo",
+    "placeholder",
+    "待填",
+    "待补",
+    "待确认"
+];
+const PAGE_TASK_TERMS = ["frontend", "front-end", "browser", "page", "页面", "前端", "按钮", "表单", "跳转"];
+const PAGE_ENTRY_TERMS = ["http://", "https://", "localhost", "127.0.0.1", "page url", "页面 url", "dev server"];
+const PAGE_BROWSER_CHECK_TERMS = ["browser check", "playwright", "screenshot", "click", "button", "form", "页面可加载", "浏览器"];
+const CALLABLE_TASK_TERMS = [
+    "api",
+    "endpoint",
+    "cli",
+    "command",
+    "worker",
+    "route",
+    "server action",
+    "adapter",
+    "provider",
+    "rpa",
+    "bot",
+    "机器人",
+    "队列"
+];
+const CALLABLE_ENTRY_TERMS = ["command", "endpoint", "api", "cli", "worker", "route", "curl", "npm ", "npx ", "node ", "python", "make "];
+const CALLABLE_RESULT_TERMS = ["pass", "response", "output", "result", "exit code", "queue", "log", "artifact", "created", "produced", "返回", "输出", "日志", "队列", "产物", "错误码"];
 const validators = {
     "validate-harness": validateHarness,
     "validate-current": validateCurrent,
@@ -333,9 +363,10 @@ async function validateDevInternal(projectRoot, options) {
     const pathErrors = options.phaseExit ? [] : await validateChangedPaths(projectRoot, plan.plan, true);
     const draftErrors = await validateDevDraftConsumed(projectRoot, root);
     const implementationDocErrors = await validateImplementationDocRunnableEntryExit(projectRoot);
+    const evidenceErrors = options.phaseExit ? [] : await validateCurrentTaskDevelopmentEvidence(projectRoot, plan.plan);
     return {
         info: [`validate-dev checked ${plan.taskCount} task(s)${options.phaseExit ? " for phase exit" : ""}`],
-        errors: [...phaseErrors, ...plan.errors, ...openTaskErrors, ...pathErrors, ...draftErrors, ...implementationDocErrors]
+        errors: [...phaseErrors, ...plan.errors, ...openTaskErrors, ...pathErrors, ...draftErrors, ...implementationDocErrors, ...evidenceErrors]
     };
 }
 function validateDevOpenTaskState(plan) {
@@ -737,6 +768,113 @@ async function validateImplementationDocRunnableEntryExit(projectRoot) {
     }
     return errors;
 }
+async function validateCurrentTaskDevelopmentEvidence(projectRoot, plan) {
+    const currentTask = currentOpenSprintTask(plan);
+    if (!currentTask)
+        return [];
+    const taskId = String(currentTask.id ?? "");
+    const implementationDoc = String(currentTask.implementation_doc ?? "").trim();
+    if (!implementationDoc)
+        return [];
+    const docPath = path.join(projectRoot, implementationDoc);
+    if (!(await pathExists(docPath))) {
+        return [`${taskId} implementation_doc is missing: ${implementationDoc}`];
+    }
+    const text = await readText(docPath);
+    return validateDevelopmentEvidenceText(text, currentTask, implementationDoc);
+}
+function currentOpenSprintTask(plan) {
+    const currentTaskId = String(plan.current_task_id ?? "");
+    if (!currentTaskId)
+        return undefined;
+    const tasks = Array.isArray(plan.tasks) ? plan.tasks.filter(isRecord) : [];
+    return tasks.find((task) => String(task.id ?? "") === currentTaskId && OPEN_TASK_STATUSES.has(String(task.status)) && task.phase === "SPRINTING");
+}
+function validateDevelopmentEvidenceText(text, task, implementationDoc) {
+    const errors = [];
+    const taskId = String(task.id ?? "current task");
+    const section = markdownSection(text, DEVELOPMENT_EVIDENCE_TERMS);
+    if (!section) {
+        return [`${taskId} implementation_doc must include Development Evidence with Runnable Entry, Observable Exit, and Basic Self-test Evidence: ${implementationDoc}`];
+    }
+    if (hasJustifiedNotApplicableEvidence(section))
+        return [];
+    for (const field of ["Runnable Entry", "Observable Exit", "Basic Self-test Evidence"]) {
+        const value = evidenceFieldValue(section, field);
+        if (!value || isPlaceholderEvidence(value)) {
+            errors.push(`${taskId} Development Evidence ${field} must contain concrete, executed evidence in ${implementationDoc}`);
+        }
+    }
+    const context = `${taskText(task)}\n${text}`.toLowerCase();
+    const loweredSection = section.toLowerCase();
+    if (containsAny(context, PAGE_TASK_TERMS)) {
+        if (!containsAny(loweredSection, PAGE_ENTRY_TERMS)) {
+            errors.push(`${taskId} page Development Evidence must include a dev server or page URL in ${implementationDoc}`);
+        }
+        if (!containsAny(loweredSection, PAGE_BROWSER_CHECK_TERMS)) {
+            errors.push(`${taskId} page Development Evidence must include a browser check, Playwright run, screenshot, or equivalent interaction evidence in ${implementationDoc}`);
+        }
+    }
+    if (containsAny(context, CALLABLE_TASK_TERMS)) {
+        if (!containsAny(loweredSection, CALLABLE_ENTRY_TERMS)) {
+            errors.push(`${taskId} callable Development Evidence must include an API/CLI/worker command, endpoint, route, or invocation in ${implementationDoc}`);
+        }
+        if (!containsAny(loweredSection, CALLABLE_RESULT_TERMS)) {
+            errors.push(`${taskId} callable Development Evidence must include an observable response, output, side effect, log, artifact, or PASS/BLOCKED result in ${implementationDoc}`);
+        }
+    }
+    return errors;
+}
+function markdownSection(text, headerTerms) {
+    const lines = text.split(/\r?\n/);
+    let start = -1;
+    let level = 0;
+    for (let index = 0; index < lines.length; index += 1) {
+        const match = lines[index].match(/^(#{1,6})\s+(.+)$/);
+        if (!match)
+            continue;
+        const title = match[2].toLowerCase();
+        if (headerTerms.some((term) => title.includes(term.toLowerCase()))) {
+            start = index;
+            level = match[1].length;
+            break;
+        }
+    }
+    if (start === -1)
+        return undefined;
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        const match = lines[index].match(/^(#{1,6})\s+/);
+        if (match && match[1].length <= level) {
+            end = index;
+            break;
+        }
+    }
+    return lines.slice(start, end).join("\n");
+}
+function hasJustifiedNotApplicableEvidence(section) {
+    for (const line of section.split(/\r?\n/)) {
+        const match = line.match(/^\s*[-*]\s*Not applicable\s*:[ \t]*(.+)$/i);
+        if (!match)
+            continue;
+        const value = match[1].trim();
+        if (value.length >= 24 && !isPlaceholderEvidence(value) && containsAny(value, ["because", "reason", "原因", "无应用入口", "no product runtime", "no runnable boundary"])) {
+            return true;
+        }
+    }
+    return false;
+}
+function evidenceFieldValue(section, field) {
+    const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`^\\s*[-*]\\s*${escaped}\\s*:[ \\t]*(.+)$`, "im");
+    return section.match(pattern)?.[1]?.trim();
+}
+function isPlaceholderEvidence(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized || ["-", "n/a", "na", "none", "null", "不适用", "无"].includes(normalized))
+        return true;
+    return EVIDENCE_PLACEHOLDER_TERMS.some((term) => normalized === term || normalized.includes(term.toLowerCase()));
+}
 async function markdownFiles(root) {
     const files = await listFiles(root);
     return files.filter((file) => {

package/package.json

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