agent-project-sdlc 0.1.15 → 0.1.17

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. 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.
+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. The current task implementation doc must also include `Development Evidence` with `Runnable Entry`, `Observable Exit`, `Client / Server Initialization`, `Config Contract`, `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 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, 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.
+`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/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.
 
@@ -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`。当前 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。
+SPRINTING 的 Definition of Done 包含可运行入口/出口：技术方案或 task 承诺的 API、CLI、server route、service、agent、runtime、adapter、worker、provider、配置契约和 fixture/live 边界必须在开发阶段实现或明确 `BLOCKED`。当前 task 的 implementation doc 还必须写入 `Development Evidence`，包含 `Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract`、`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。
 
-`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` 移除。
+`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/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。
 
@@ -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/skills/pjsdlc_dev_sprint/SKILL.md

@@ -15,9 +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`，并在 `Development Evidence` 中记录 `Runnable Entry`、`Observable Exit`、`Basic Self-test Evidence`；确实不适用时也要显式写 `Not applicable` 和具体原因。此时应保留或创建 `BLOCKED`/后续 dev task，或通过 RFC/ARCHITECTING 处理边界变更。
+开发阶段的 Definition of Done 包含可运行的系统入口/出口。凡技术方案或 task 承诺 API、CLI、server route、service、agent、runtime、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，当前实现必须提供对应入口、调用方式、初始化方式、输出/副作用边界和验证方式；如果真实入口/出口尚不可运行，不能把 task 当作完成，也不能把缺口留给 TESTING 补 runtime。Implementation doc 必须写明 `Runnable Entry/Exit`，并在 `Development Evidence` 中记录 `Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract`、`Basic Self-test Evidence`；确实不适用时也要显式写 `Not applicable` 和具体原因。provider smoke、fixture smoke、fake adapter 或 one-shot smoke 只能证明局部链路，不能单独证明 `Application readiness`。此时应保留或创建 `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 server 或等价预览入口，并用浏览器、Playwright、截图或等价方式验证页面可加载、主入口可访问、核心按钮/表单/跳转可用、没有明显报错或空白页。API/CLI/worker/RPA/service/agent/runtime 类任务必须记录实际启动或调用命令、endpoint、worker command、dry-run/live preflight、health/status 或 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。
 
@@ -105,7 +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`。
+- [ ] implementation doc `Development Evidence` 已记录 `Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract`、`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 模式边界，以及哪些真实外部执行器尚未实现。还必须在 `Development Evidence` 中记录开发阶段实际验证过的 `Runnable Entry`、`Observable Exit` 和 `Basic Self-test Evidence`；确实没有应用入口时，`Not applicable` 必须写清原因。不能把未来才会实现的入口写成当前事实。
+如果模块包含或承诺可运行系统边界，implementation doc 必须记录 runnable entry/exit：API/CLI/server route/service/agent/runtime/adapter/worker/provider 的调用方式、初始化方式、配置契约、输入来源、输出或副作用、fixture/live 模式边界，以及哪些真实外部执行器尚未实现。还必须在 `Development Evidence` 中记录开发阶段实际验证过的 `Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract` 和 `Basic Self-test Evidence`；确实没有应用入口时，`Not applicable` 必须写清原因。不能把未来才会实现的入口写成当前事实，不能把 provider smoke、fixture smoke、fake adapter 或 one-shot smoke 单独写成 application readiness。
 
 ## 输入
 
@@ -48,7 +48,7 @@ description: Use after development gates pass to update module-level implementat
 2. 每个被记录的文件都应说明它在该模块或数据流中的作用和关键函数/对象。
 3. 与技术方案的偏移必须明确记录，即便该偏移是合理的。
 4. runnable entry/exit、配置契约和 fixture/live 边界必须记录当前事实；缺失项写入 `未覆盖（Not covered）` 或方案偏移。
-5. `Development Evidence` 必须包含实际可调用入口、可观察出口和开发自测证据；页面类任务记录 dev server/page URL 与 browser check，API/CLI/worker/RPA 类任务记录 invocation command/endpoint 与 response/output/side effect。
+5. `Development Evidence` 必须包含实际可调用入口、可观察出口、初始化方式、配置契约和开发自测证据；页面类任务记录 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 建文档，也不要写成跨全项目的巨型百科。
 
@@ -59,7 +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`。
+- [ ] `Development Evidence` 已记录 `Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract`、`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 都要核对真实代码和实现文档是否提供可调用入口、输出/副作用边界和验证方式；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 必须把“当前模块没有可运行入口/出口”视为阻断项，而不是普通测试缺口。凡 PRD、技术方案或 implementation doc 承诺 API、CLI、server route、service、agent、runtime、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，Review 都要读取技术方案的 `Development Deliverable Contract` 或等价交付边界，并核对真实代码和实现文档是否提供可调用入口、初始化方式、输出/副作用边界和验证方式；implementation doc 还必须包含结构化 `Development Evidence`，说明 `Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract` 和 `Basic Self-test Evidence`，或带原因的 `Not applicable`。缺失时 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 主题。
 
@@ -78,7 +78,7 @@ Review 阶段受 `plan.yaml` 管控：
 - [ ] 已评估需求一致性。
 - [ ] 已评估架构和可维护性风险。
 - [ ] 已评估 runnable entry/exit、配置契约和 fixture/live 边界是否足以进入 TESTING。
-- [ ] 已评估 implementation doc 是否包含 Runnable Entry、Observable Exit 和 Basic Self-test Evidence。
+- [ ] 已评估 implementation doc 是否包含 Runnable Entry、Observable Exit、Client / Server Initialization、Config Contract 和 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 或部署脚本。如果发现真实入口/出口不存在、implementation doc 缺少 `Development Evidence`、live 模式不可调用、配置契约缺失或用户目标与已实现通道不一致，应记录 `BLOCKED`、生成 RFC 或后续 dev task 建议，并停止把测试阶段扩大成开发/集成搭建。开发尚未交付可测试 entry/exit 时，不要在 `.docs/07_test/**` 提前生成正式测试用例或正式报告；验收思路应留在 PRD acceptance criteria、tech plan verification strategy 或非 `.docs/07_test/**` 的草稿说明里。
+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`，或用户目标与已实现通道不一致，应记录 `BLOCKED`、生成 RFC 或后续 dev task 建议，并停止把测试阶段扩大成开发/集成搭建。开发尚未交付可测试 entry/exit 时，不要在 `.docs/07_test/**` 提前生成正式测试用例或正式报告；验收思路应留在 PRD acceptance criteria、tech plan verification strategy 或非 `.docs/07_test/**` 的草稿说明里。`TEST_REPORT.md` 不能在描述缺少 entry/exit、缺少 Development Evidence 或未交付应用入口时给出 `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 的旧测试结果。
 

package/assets/templates/IMPLEMENTATION_DOC_TEMPLATE.md

@@ -44,6 +44,8 @@ Input
 
 - Runnable Entry:
 - Observable Exit:
+- Client / Server Initialization:
+- Config Contract:
 - Basic Self-test Evidence:
 - Not applicable:
 

package/assets/templates/REVIEW_TEMPLATE.md

@@ -34,7 +34,15 @@
 - Development Evidence:
 - Blocking gaps before TESTING:
 
-## 7. Gate Result（阶段结论）
+## 7. Application Readiness Checklist（应用就绪检查）
+
+- Runnable Entry: `PASS` / `BLOCKED`
+- Observable Exit: `PASS` / `BLOCKED`
+- Initialization: `PASS` / `BLOCKED`
+- Config Contract: `PASS` / `BLOCKED`
+- Testing Handoff Readiness: `PASS` / `BLOCKED`
+
+## 8. Gate Result（阶段结论）
 
 - Decision: `PASS` / `BLOCKED`
 - Required before testing:

package/assets/templates/TEST_REPORT_TEMPLATE.md

@@ -25,6 +25,7 @@
 - Existing entry points under test:
 - Expected exits / side effects:
 - Development Evidence used:
+- Application readiness decision source:
 - 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/config.js

@@ -1,15 +1,11 @@
 import path from "node:path";
-import { createRequire } from "node:module";
 import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
 import { pathExists, readText, writeTextIfChanged } from "./fs.js";
 import { parseYaml, stringifyYaml } from "./yaml.js";
-const require = createRequire(import.meta.url);
-const packageMetadata = require("../../package.json");
 export function defaultConfig(root) {
     return {
         core: {
             package: "agent-project-sdlc",
-            version: packageMetadata.version ?? "0.0.0",
             schema_version: "1"
         },
         managed_files: [
@@ -51,7 +47,6 @@ export function normalizeConfig(value, root = ".agent") {
     return {
         core: {
             package: value.core?.package ?? fallback.core.package,
-            version: value.core?.version ?? fallback.core.version,
             schema_version: value.core?.schema_version ?? fallback.core.schema_version
         },
         managed_files: value.managed_files ?? fallback.managed_files,

package/dist/lib/doctor.js

@@ -1,7 +1,10 @@
+import { createRequire } from "node:module";
 import path from "node:path";
 import { readConfig } from "./config.js";
 import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
 import { pathExists } from "./fs.js";
+const require = createRequire(import.meta.url);
+const packageMetadata = require("../../package.json");
 export async function runDoctor(projectRoot) {
     const report = { info: [], warnings: [], errors: [] };
     const root = await harnessRoot(projectRoot);
@@ -12,8 +15,9 @@ export async function runDoctor(projectRoot) {
         return report;
     }
     const config = await readConfig(projectRoot);
+    const packageVersion = packageMetadata.version ?? "0.0.0";
     report.info.push(`harness root: ${root}`);
-    report.info.push(`core package: ${config.core.package}@${config.core.version}`);
+    report.info.push(`core package: ${config.core.package}@${packageVersion}`);
     report.info.push(`schema version: ${config.core.schema_version}`);
     for (const required of [harnessPath(root, "state", "lifecycle.yaml"), harnessPath(root, "state", "plan.yaml"), ".docs/INDEX.md"]) {
         if (!(await pathExists(path.join(projectRoot, required)))) {

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) {
@@ -40,8 +41,8 @@ async function migrateConfig(projectRoot, root, report) {
     const config = await readConfig(projectRoot);
     const currentCore = defaultConfig(root).core;
     config.core.package = currentCore.package;
-    config.core.version = currentCore.version;
     config.core.schema_version = CURRENT_SCHEMA_VERSION;
+    delete config.core.version;
     config.managed_files = migrateManagedFiles(config.managed_files, root);
     config.local_overrides = config.local_overrides.map((item) => migrateLocalOverride(item, root));
     if (await writeTextIfChanged(configPath, stringifyYaml(config))) {
@@ -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/types.d.ts

@@ -1,7 +1,6 @@
 export interface HarnessConfig {
     core: {
         package: string;
-        version: string;
         schema_version: string;
     };
     managed_files: ManagedFile[];

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

@@ -113,6 +113,80 @@ const CALLABLE_TASK_TERMS = [
 ];
 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 APPLICATION_READINESS_TASK_TERMS = [
+    "service",
+    "agent",
+    "runtime",
+    "http",
+    "server",
+    "worker",
+    "provider",
+    "adapter",
+    "live mode",
+    "live",
+    "external integration",
+    "webhook",
+    "bot",
+    "机器人",
+    "常驻",
+    "云端",
+    "入口",
+    "出口"
+];
+const APPLICATION_START_TERMS = [
+    "start",
+    "startup",
+    "启动",
+    "listen",
+    "serve",
+    "server",
+    "http://",
+    "https://",
+    "localhost",
+    "endpoint",
+    "cli command",
+    "worker command",
+    "daemon",
+    "常驻",
+    "health",
+    "status"
+];
+const CONFIG_CONTRACT_TERMS = ["config", "configuration", "env", "environment", "api key", "secret", "契约", "配置", "环境变量"];
+const INSUFFICIENT_APPLICATION_SMOKE_TERMS = [
+    "provider smoke",
+    "provider live smoke",
+    "fixture smoke",
+    "fake adapter",
+    "fake send",
+    "one-shot smoke",
+    "one shot smoke",
+    "domain smoke",
+    "受控 smoke"
+];
+const MISSING_READINESS_TERMS = [
+    "missing entry",
+    "missing exit",
+    "missing runnable",
+    "missing development evidence",
+    "no runnable",
+    "no entry",
+    "no exit",
+    "入口缺失",
+    "出口缺失",
+    "缺少入口",
+    "缺少出口",
+    "缺少 development evidence",
+    "尚未交付",
+    "未交付",
+    "不存在"
+];
+const REVIEW_READINESS_FIELDS = [
+    "Runnable Entry",
+    "Observable Exit",
+    "Initialization",
+    "Config Contract",
+    "Testing Handoff Readiness"
+];
 const validators = {
     "validate-harness": validateHarness,
     "validate-current": validateCurrent,
@@ -415,7 +489,8 @@ async function validateDevDraftConsumed(projectRoot, root) {
 }
 async function validateReview(projectRoot) {
     const plan = await validatePlanState(projectRoot, false);
-    const text = (await readText(path.join(projectRoot, ".docs/06_review/REVIEW_REPORT.md"))).toLowerCase();
+    const rawText = await readText(path.join(projectRoot, ".docs/06_review/REVIEW_REPORT.md"));
+    const text = rawText.toLowerCase();
     const errors = [...plan.errors];
     if (!containsAny(text, ["finding", "发现", "风险"]))
         errors.push("Review report must include findings or risks");
@@ -424,6 +499,7 @@ async function validateReview(projectRoot) {
     if (!containsAny(text, ["entry/exit", "entrypoint", "入口", "出口", "runnable", "可运行"])) {
         errors.push("Review report must assess runnable entry/exit readiness before TESTING");
     }
+    errors.push(...validateReviewReadinessChecklist(rawText));
     if (!containsAny(text, ["pass", "blocked", "通过", "阻塞"]))
         errors.push("Review report must include PASS/BLOCKED decision");
     return { info: ["validate-review checked review report"], errors };
@@ -451,6 +527,7 @@ async function validateTest(projectRoot) {
     }
     if (!containsAny(text, ["pass", "blocked", "通过", "阻塞"]))
         errors.push("Test report must include PASS/BLOCKED decision");
+    errors.push(...validateTestReadinessDecision(text));
     if (lifecycle.current_phase === "TESTING") {
         errors.push(...testingBoundaryErrorsForChangedFiles(await changedFiles(projectRoot)));
     }
@@ -799,7 +876,7 @@ function validateDevelopmentEvidenceText(text, task, implementationDoc) {
     }
     if (hasJustifiedNotApplicableEvidence(section))
         return [];
-    for (const field of ["Runnable Entry", "Observable Exit", "Basic Self-test Evidence"]) {
+    for (const field of ["Runnable Entry", "Observable Exit", "Client / Server Initialization", "Config Contract", "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}`);
@@ -823,8 +900,58 @@ function validateDevelopmentEvidenceText(text, task, implementationDoc) {
             errors.push(`${taskId} callable Development Evidence must include an observable response, output, side effect, log, artifact, or PASS/BLOCKED result in ${implementationDoc}`);
         }
     }
+    if (containsAny(context, APPLICATION_READINESS_TASK_TERMS)) {
+        if (!containsAny(loweredSection, APPLICATION_START_TERMS)) {
+            errors.push(`${taskId} application readiness evidence must include a real startup, live entrypoint, health/status check, endpoint, CLI command, or worker command in ${implementationDoc}`);
+        }
+        if (!containsAny(loweredSection, CONFIG_CONTRACT_TERMS)) {
+            errors.push(`${taskId} application readiness evidence must include the configuration contract or required env/config inputs in ${implementationDoc}`);
+        }
+        if (containsAny(loweredSection, INSUFFICIENT_APPLICATION_SMOKE_TERMS) && !containsAny(loweredSection, ["application readiness", "runtime http smoke", "external integration smoke", "blocked", "阻塞"])) {
+            errors.push(`${taskId} provider, fixture, fake-adapter, or one-shot smoke is not enough for application readiness; record application readiness evidence or BLOCKED in ${implementationDoc}`);
+        }
+    }
     return errors;
 }
+function validateReviewReadinessChecklist(text) {
+    const errors = [];
+    for (const field of REVIEW_READINESS_FIELDS) {
+        const status = readinessStatus(text, field);
+        if (!status) {
+            errors.push(`Review report must include ${field}: PASS/BLOCKED`);
+        }
+        else if (status === "BLOCKED") {
+            errors.push(`Review readiness is BLOCKED: ${field}`);
+        }
+    }
+    return errors;
+}
+function readinessStatus(text, field) {
+    const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const patterns = [
+        new RegExp("^\\s*[-*]?\\s*" + escaped + "\\s*:\\s*`?(PASS|BLOCKED)`?\\b", "im"),
+        new RegExp("\\|\\s*" + escaped + "\\s*\\|\\s*`?(PASS|BLOCKED)`?\\s*\\|", "i")
+    ];
+    for (const pattern of patterns) {
+        const match = text.match(pattern);
+        if (match)
+            return match[1].toUpperCase();
+    }
+    return undefined;
+}
+function validateTestReadinessDecision(text) {
+    const decision = finalDecision(text);
+    if (decision !== "PASS")
+        return [];
+    if (containsAny(text, MISSING_READINESS_TERMS)) {
+        return ["Test report cannot PASS while runnable entry/exit or Development Evidence is missing; use BLOCKED with recovery conditions"];
+    }
+    return [];
+}
+function finalDecision(text) {
+    const match = text.match(/(?:decision|final decision|结论)\s*:?\s*`?(PASS|BLOCKED)`?/i);
+    return match ? match[1].toUpperCase() : undefined;
+}
 function markdownSection(text, headerTerms) {
     const lines = text.split(/\r?\n/);
     let start = -1;

package/package.json

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