@cyning/harness 2.9.0 → 2.11.0

package/docs/spec/SPEC-lifecycle-engine-min_v1.md

@@ -0,0 +1,246 @@
+# SPEC：lifecycle 转移引擎最小骨架（Post-G4 Epic T2）（v1）
+
+> **状态**：`signed`（维护者签收 2026-07-25 · 对话「签收」）  
+> **track**：`feature`  
+> **关联图谱**：无（纯 Harness 工具链 / 过程轨）  
+> **上游**：工作区 Epic [`EPIC_post_g4_menu_serial_t1t2t3_v1_zh.md`](../../../docs/harness/guides/EPIC_post_g4_menu_serial_t1t2t3_v1_zh.md) · RETRO [`RETRO_post_g4_n1n4_debt_v1_zh.md`](../../../docs/harness/guides/RETRO_post_g4_n1n4_debt_v1_zh.md) §4 点菜 **#2** · PLAN 方向二  
+> **前置**：N1 `@cyning/harness@2.7.0`（`lifecycle.yaml` + `lifecycle show` 只读）· 当前产品仓 **2.9.0** · Epic **T1 CLOSE ✅**  
+> **下游**：00 已起草 task（HG-TASK-DRAFT pending）→ 10-task（可选）→ 20-task-audit → HG-AUDIT-R1 → 30（Epic：T1 已 CLOSE，闸链仍须人签）  
+> **目标版本**：Epic 统一发版建议 **`@cyning/harness@2.10.0`**（与 T3 同波复检后 publish；本 SPEC 可写目标版本，不代发）
+
+---
+
+## Harness 元信息
+
+| 字段 | 值 |
+|------|-----|
+| **spec_slug** | `lifecycle-engine-min` |
+| **invoke_slug** | `cyning-harness-lifecycle-engine-min` |
+| **test_strategy** | `required` |
+| **test_strategy_note** | 引擎：结构合法/非法 · 守卫 adapter 通过/block/unevaluated · CLI dry-run exit 码；既有 `lifecycle show` / verify / close 回归 |
+| **entry_invoke_10_spec** | `Projects/docs/harness/invokes/by-task/cyning-harness-lifecycle-engine-min/invoke_20260725_10_spec_lifecycle_engine_min.md` |
+| **entry_invoke_00_draft** | `Projects/docs/harness/invokes/by-task/cyning-harness-lifecycle-engine-min/invoke_20260725_00_draft_lifecycle_engine_min.md` |
+| **Open Folder（实现）** | `cyning-harness/`（产品仓改码） |
+| **epic_serial** | T2（T1 dogfood 卫生 → **本棒** → T3 discipline-coverage） |
+
+---
+
+## 1. 背景与目标
+
+N1（v2.7）已落地 **`harness/lifecycle.yaml`** 与 **`lifecycle show [--json]`**：状态 / 转移 / 守卫的**登记真值**可校验、可展示。yaml 文件头与 schema 均明示「只读登记 · 不由引擎执行」。
+
+方向二下一台阶（RETRO #2 / Epic T2）：在登记之上增加 **转移引擎最小骨架**——能对指定转移做 **dry-run 资格判定**（结构 + 部分守卫求值报告），让「补闸 / 开工前检查」从临场拼 CLI 变为**消费 lifecycle 真值**。
+
+**一句话目标**：YAML 仍是登记；**引擎是消费方**。禁止把 N1「已有 yaml」说成「已是引擎」。
+
+**消费者（本波）**：维护者 / Agent 在 30 前或联调时跑 `lifecycle dry-run`，得到可机读的转移资格报告（非 spawn Agent、非 G7 执行证据）。
+
+---
+
+## 2. 范围
+
+### D1 · 引擎库（最小 API）
+
+- 新增（或扩展）`lib/lifecycle*.js` 导出至少：
+  - `dryRunTransition({ transitionId, fromState, taskPath?, harnessRoot?, flags? })`
+  - 返回稳定结构（人读与 `--json` 同源字段），至少含：
+    - `transition_id` · `from` · `to` · `hat?`
+    - `structure_ok`（transition 存在且 `fromState ∈ from[]`）
+    - `guards[]`：`{ id, severity, status: pass|fail|warn|unevaluated, detail?, allow_flag? }`
+    - `blocked`（任一 `severity=block` 且 `status=fail` → true）
+    - `unevaluated_count`
+    - `engine: "lifecycle-dry-run"` · `lifecycle_doc_version`（yaml `version`）
+- **默认不写盘**；本波 **无** `--apply` / 无改 task `status` / 无写 invoke。
+
+### D2 · CLI · `lifecycle dry-run`
+
+- `npx @cyning/harness lifecycle dry-run --transition <id> --from <state> [--task PATH] [--json] [--allow-no-review] [--allow-lint-fail] …`
+- 复用既有 allow 旗名（与 verify/close 对齐）；未知旗 → 明确错误
+- **exit**：
+  - `0`：结构合法且无 block 级 `fail`（允许存在 `unevaluated` / warn；stdout 须标明 unevaluated）
+  - `2`：结构非法或存在 block 级 `fail`
+  - `1`：用法 / yaml 损坏等（与 `lifecycle show` 一致风格）
+- `lifecycle show` **行为不变**；help 文案区分：show=登记只读 · dry-run=引擎资格判定
+
+### D3 · 守卫 adapter（薄 · 可扩展表）
+
+- 维护 `GUARD_ADAPTERS`（或等价）：`guard.id → evaluator`
+- **本波必须接线**（当 `--task` 给出且 transition=`to_30` 时）：
+  - `HG-AUDIT-R1`（复用 gate-check / 既有 human_gate 读取）
+  - `reviews_retention`（复用 `findReview` / verify 同语义）
+- **本波允许 `unevaluated`**（须在报告中显式列出，禁止静默当 pass）：
+  - `HG-TASK-DRAFT` · `audit_D5` · `task_lint` · `close_*` · `spec_reviews_retention` 等未接线守卫
+  - 无 `--task` 时：除结构外，全部守卫 → `unevaluated`（仍可 exit 0，但人读/JSON 醒目提示「未求值」）
+- **禁止**本波实现「spawn 子进程跑完整 verify 再盲映射」作为唯一路径；优先 **库内复用** 既有函数。允许 30 实现时微调接线细节，但验收须可测。
+
+### D4 · 文档与登记语义护栏
+
+- `harness/lifecycle.yaml` 文件头注释修订：明确「登记真值 · **由 `lifecycle dry-run` 引擎消费** · yaml 本身不是引擎」
+- `schema/lifecycle.v1.schema.json` description 同步（仍不强制改字段；本波 **不**为引擎扩 schema 必填项，除非 30 发现缺字段阻塞）
+- USER_GUIDE / ONBOARDING / README 短节：dry-run 用法 · 与 show 对比 · **非** G7 / **非** runner
+- CHANGELOG：**2.10.0**（或 Epic 复检时实际版本号）条目
+
+### D5 · 测试
+
+- 单元：结构 pass/fail；`to_30` + fixture task 下 HG-AUDIT-R1 / reviews adapter 三态；unevaluated 计数
+- CLI：dry-run `--json` 字段稳定；show 回归；非法 transition id → exit ≠0
+- 既有 `test/lifecycle.test.js` · verify · close 不回归
+
+### D6 · 版本与 Epic 对齐
+
+- 目标版本挂 Epic 统一发版 **`2.10.0`**
+- 本棒 CLOSE 后 **不**单独强制 publish；等 T3 CLOSE → 00 发版前复检 → 维护者 publish
+- 若 T3 无产品 diff 且仅本棒有码：仍建议同 tag **2.10.0**（Epic 约定），由维护者裁定
+
+---
+
+## 3. 非范围
+
+- **完整 runner**（`harness run` · Agent spawn · 帽链自动推进）
+- **同波硬塞 G7**（40「真跑过」执行证据）—— 附录观察项；宜跟本引擎之后另开
+- 声称 / 文档暗示 **N1 YAML「已是引擎」**
+- **`--apply` / 写回 task status / 事件溯源 / 持久化转移日志**
+- 把全部 yaml 守卫一次性接线完毕（本波允许 unevaluated 清单）
+- N2-C lint→block · G6 · HGM · discipline-coverage（T3）· dogfood 缺审补文（T1）
+- 改变既有 `verify` / `task close` 的闸语义（引擎是**旁路报告**，不替换 verify 作为 30 硬闸；除非未来另 SPEC 规定「dry-run 替代」——本波不做）
+
+---
+
+## 4. 验收标准
+
+- [ ] `lifecycle dry-run --transition to_30 --from draft --task <fixture>`：结构 ok；至少 `HG-AUDIT-R1` 与 `reviews_retention` 出现非 `unevaluated` 的 `pass|fail`（按夹具）
+- [ ] 非法 `transition` id 或 `from` 不在 `from[]` → `structure_ok=false` · exit 2（或 1，须在实现/自检写死并测）
+- [ ] 无 `--task`：可 exit 0（结构合法时）但 JSON/`unevaluated_count` > 0 且人读标明未求值
+- [ ] block 守卫 adapter 返回 fail → `blocked=true` · exit 2
+- [ ] `lifecycle show` 仍只读登记 · 行为与 v2.7+ 兼容
+- [ ] 文档明确：**yaml ≠ 引擎**；dry-run ≠ runner / ≠ G7
+- [ ] `npm test` 全绿
+- [ ] CHANGELOG 含 2.10.0（或 Epic 实发版本）条目；Epic / RETRO #2 可回链本 SPEC
+
+---
+
+## 5. failure_paths
+
+| 触发条件 | 系统行为 | 可重试 |
+|----------|----------|--------|
+| lifecycle.yaml 缺失/损坏 | dry-run 失败 · 信息可定位（同 show） | 修 yaml / 升级包 |
+| 未知 `--transition` | exit ≠0 · 列出已知 id 或提示 `lifecycle show` | 改参数 |
+| `--from` ∉ transition.from | `structure_ok=false` · blocked | 改 from 或选对 transition |
+| `--task` 路径不可读 | exit ≠0 · 可定位 | 修路径 |
+| 守卫 adapter 内部依赖失败（如 gate 文件缺失） | 该守卫 `fail` 或显式 `detail`；不伪装 pass | 补闸表 / 修 task |
+| 用户误以为 unevaluated=已通过 | 文档 + JSON `unevaluated_count` + 人读 WARN 行 | — |
+| 用户误以为 dry-run 可替代 verify 进 30 | 文档醒目：旁路报告；30 仍以既有 verify/gate 为准 | — |
+| 业务仓未升级到含 dry-run 的版本 | 无子命令 | upgrade |
+
+---
+
+## 6. 依赖与引用
+
+- 产品仓：`harness/lifecycle.yaml` · `lib/lifecycle.js` · `lib/cli.js` `cmdLifecycle` · `schema/lifecycle.v1.schema.json` · `test/lifecycle.test.js`
+- 守卫复用候选：`lib/verify.js` · gate-check / human_gate · `findReview`（与 v2.5+/v2.9 语义对齐）
+- 上游 SPEC：[`SPEC-lifecycle-and-verify-lint_v1.md`](./SPEC-lifecycle-and-verify-lint_v1.md)（N1 非范围「状态机引擎」→ 本 SPEC 承接）
+- Epic 串行：T1 CLOSE 后才允许本 task **HG-AUDIT-R1 → 30**；SPEC 签收与 00 起草 task **可在 T1 完成前并行**（不挡文档轨）
+
+---
+
+## 7. 思考轮（10-spec 回填 · R0–R5）
+
+### R0 · 读入与约束
+
+读入：Epic T2 · RETRO #2（方向二转移引擎最小骨架）· N1 SPEC（yaml+show · **明确不做引擎**）· 现状 `lifecycle.yaml` / `lib/lifecycle.js`（load+validate+format · 无转移 API）· CLI 仅 `lifecycle show` · 产品仓 **2.9.0** · 统一发版建议 **2.10.0**。
+
+硬约束：
+
+1. 不做完整 runner；不同波硬塞 G7  
+2. 不声称 N1 YAML 已是引擎  
+3. early_stop=no（无充分理由裁轮）  
+4. Open Folder 实现 = `cyning-harness/`；本 10-spec 只写 SPEC/invoke  
+
+### R1 · 范围 / 非范围 / 场景
+
+**场景**：
+
+1. Agent/人：`lifecycle dry-run --transition to_30 --from draft --task path` → 得资格报告，再决定是否跑 verify / 开 30  
+2. 无 task：只验证「该转移在 yaml 里从该状态是否合法」+ 守卫清单 unevaluated  
+3. 维护者对照 show vs dry-run：登记 vs 求值  
+
+**范围边界**：引擎 = dry-run 资格判定 + 薄 adapter；**非**状态写回、**非**帽执行、**非** G7。  
+**非范围**：见 §3。与 T1/T3 切分清晰。
+
+### R2 · 方案对比
+
+| 方案 | 内容 | 利 | 弊 | 裁定 |
+|------|------|----|----|------|
+| **A** | 仅结构 dry-run（from∈from[] · id 存在），守卫一律打印不求值 | 极小 diff | 相对 show 增量弱；难称「引擎」 | **弃** |
+| **B** | 结构 + 薄 adapter（本波接线 to_30 核心 block 子集）+ 其余 `unevaluated`；**无 apply** | 真消费 yaml；边界清；可测；不撞 G7/runner | 守卫覆盖不全须文档说清 | **推荐 · 本波** |
+| **C** | B + `--apply` 写 task status | 「可执行转移」字面更满 | 易与 close/verify 双写；半成品状态机；超最小骨架 | **弃（residual）** |
+| **D** | 完整 runner / `harness run` / G7 同波 | 方向二终局感 | Epic 明禁；无消费者契约 | **禁** |
+
+**CLI 命名**：`lifecycle dry-run`（相对 `transition --dry-run`）—— 默认语义即 dry-run，降低误触 apply。  
+**与 verify 关系**：旁路报告，**不**在本波把 dry-run 设为 `may_start_30` 唯一真值。  
+**版本**：挂 **2.10.0**（Epic 统一），不拆 2.10 docs / 2.11 engine。
+
+### R3 · 边界 / 失败语义 / 安全
+
+- **挂点**：dry-run 在「读 yaml + 可选读 task」时刻求值；不修改仓库文件。  
+- **误报**：unevaluated 不得计为 pass；block fail 必须挡 exit。  
+- **泄压**：复用 `--allow-no-review` / `--allow-lint-fail` 等**已存在**旗（仅当对应 adapter 接线后生效；未接线则旗可忽略或 WARN「无效果」——实现时选一并测）。  
+- **安全**：无网络；无任意 shell（`command_or_check` 字段本波仍是**描述串**，不当 shell 执行）。  
+- **兼容**：旧仓无 dry-run 子命令；show 不变。  
+- **串行**：SPEC/task 文档可先行；**30 改码**受 Epic「T1 CLOSE」约束。
+
+### R4 · 验收 / 可测性 / test_strategy
+
+`test_strategy: required`。夹具覆盖：结构失败、adapter pass/fail、无 task 的 unevaluated、JSON 字段、show 回归。验收清单 §4 均可自动化或 CLI 断言。图谱无需 bootstrap。
+
+### R5 · SPEC 签收就绪 · 是否可交 00 出 task
+
+SPEC 自足：D1–D6、非范围、failure_paths、R2 裁定（方案 B）已写死。  
+**可交人签** → 签后 **00 起草 task**（slug `cyning-harness-lifecycle-engine-min`）。  
+建议：可选轻量 **20-spec-audit R1**；维护者亦可用对话「签收」直接 HG-SPEC-SIGNOFF。  
+**提醒 00**：task 元信息注明 Epic T2 · `target_version: 2.10.0` · Open Folder=`cyning-harness/` · `human_gate` 进 30 前核对 T1 CLOSE。
+
+### 思考轮控制
+
+| 字段 | 值 |
+|------|-----|
+| `actual_last_round` | `R5` |
+| `early_stop` | `no` |
+| `early_stop_reason` | — |
+| `residual_risks` | ① adapter 覆盖不全 → 用户误读 unevaluated；② 未来 `--apply` / G7 边界需另 SPEC；③ dry-run 与 verify 双轨可能短期认知负担；④ Epic 发版节奏依赖 T3，本棒 CLOSE≠立即 npm publish |
+| `round_extension_note` | — |
+
+---
+
+## 8. 下一棒可复制 Prompt（人签后 · 00 task）
+
+```text
+你是 Harness 00 编排 Agent，当前相位：起草 task（不写产品代码）。
+
+输入：
+- SPEC 已签收：cyning-harness/docs/spec/SPEC-lifecycle-engine-min_v1.md（状态须为 signed / HG-SPEC-SIGNOFF）
+- Epic：docs/harness/guides/EPIC_post_g4_menu_serial_t1t2t3_v1_zh.md · 串行 T2
+- slug：cyning-harness-lifecycle-engine-min
+- Open Folder（实现）：cyning-harness/
+- target_version：2.10.0（Epic 统一发版；不代 publish）
+- 约束：方案 B（dry-run + 薄 adapter · 无 apply · 无 G7/runner）；T1 CLOSE 前不得签 HG-AUDIT-R1 进 30
+
+【交付 · 须落盘】
+1) task：docs/harness/tasks/active/task_cyning_harness_lifecycle_engine_min_v1.md
+   - 投影 SPEC §2–§5；test_strategy=required；human_gate 表完整
+   - §4 预留 10-task 思考轮槽
+2) invoke：docs/harness/invokes/by-task/cyning-harness-lifecycle-engine-min/invoke_*_00_draft_*.md（可选快照）
+3) 勿改产品仓 lib/；勿 commit（除非维护者要求）
+
+【下一棒】
+10-task：回填 task §5 R0–R5 → 20-task-audit → 人签 HG-AUDIT-R1（且 T1 CLOSE）→ 30
+```
+
+---
+
+## 修订记录
+
+| 日期 | 摘要 |
+|------|------|
+| 2026-07-25 | 10-spec R0–R5 · Epic T2 / RETRO #2 · draft 落盘 · early_stop=no |
+| 2026-07-25 | 维护者签收（对话「签收」）→ `signed` · 00 起草 task · N3 纸链审查文 |

package/docs/spec/SPEC-lifecycle-guard-expand_v1.md

@@ -0,0 +1,100 @@
+# SPEC：lifecycle dry-run 守卫扩面（Post-2.10 Epic A）（v1）
+
+> **状态**：`signed`（维护者签收 2026-07-25 · 对话「签收 A+E」）  
+> **track**：`feature`  
+> **上游**：Epic [`EPIC_post_210_menu_serial_a_e_j_v1_zh.md`](../../../docs/harness/guides/EPIC_post_210_menu_serial_a_e_j_v1_zh.md) · RETRO [`RETRO_post_210_next_menu_v1_zh.md`](../../../docs/harness/guides/RETRO_post_210_next_menu_v1_zh.md) 候选 **A**  
+> **前置**：`@cyning/harness@2.10.0`（dry-run 骨架）· Epic **J CLOSE ✅**  
+> **下游**：人签 → 00 draft task → 20-task-audit → HG-AUDIT-R1 → 30  
+> **目标版本**：Epic 统一 **`2.11.0`**（与 E 同窗）
+
+---
+
+## Harness 元信息
+
+| 字段 | 值 |
+|------|-----|
+| **spec_slug** | `lifecycle-guard-expand` |
+| **invoke_slug** | `cyning-harness-lifecycle-guard-expand` |
+| **test_strategy** | `required` |
+| **test_strategy_note** | to_30 新 adapter 的 pass/fail/warn/unevaluated；既有 HG-AUDIT-R1 / reviews 回归；CLI dry-run exit；无 apply |
+| **Open Folder（实现）** | `cyning-harness/` |
+| **epic_serial** | A（J → **本棒** → E） |
+
+---
+
+## 1. 背景与目标
+
+T2（v2.10）已落地 `lifecycle dry-run`，但 `to_30` 仅接线 **`HG-AUDIT-R1`** 与 **`reviews_retention`**；`HG-TASK-DRAFT` · `audit_D5` · `task_lint` 及 `to_00` / `close_*` 仍为 **`unevaluated`**，报告易被误读。
+
+**一句话目标**：在**仍无 `--apply` / 仍非 runner / 仍非 G7** 的前提下，把 **`to_30` 剩余守卫**（及可选 `to_00`）接到薄 adapter，降低 unevaluated 面。
+
+---
+
+## 2. 范围
+
+### D1 · 必须接线（`--task` + `to_30`）
+
+| guard id | 语义（对齐既有） | 说明 |
+| --- | --- | --- |
+| `HG-TASK-DRAFT` | human_gate 表 `approved` | 同 HG-AUDIT-R1 解析路径 |
+| `audit_D5` | test_strategy vs 测试文件存在 | 复用 audit/verify 既有判定，禁止盲 spawn 全量 verify |
+| `task_lint` | `lintTaskFile`；severity=**warn** | fail→报告 `warn` 或 `fail` 按 yaml severity；`--allow-lint-fail` 抑制为非 block（本波 lint 仍非 block） |
+
+既有 `HG-AUDIT-R1` / `reviews_retention` **行为不得回归**。
+
+### D2 · 可选同波（若成本低）
+
+- `to_00` · `spec_reviews_retention`（复用 `findSpecReview` / verify `--spec` 语义）  
+- 若 30 评估成本高 → 记 residual，**不**阻塞 CLOSE
+
+### D3 · 仍允许 unevaluated
+
+- 全部 `close_*` 守卫（本波不扩 close 转移，除非顺手且单测充分）  
+- 无 `--task` 时：除结构外全部 unevaluated（语义同 T2）
+
+### D4 · 文档 / 测试 / 版本
+
+- CHANGELOG **2.11.0** 条目；USER_GUIDE / ONBOARDING 一句：扩面守卫列表  
+- 单测覆盖新 adapter 三态 + unevaluated 计数下降（相对 T2 fixture）  
+- **无** schema 必填扩张（除非缺字段阻塞）
+
+---
+
+## 3. 非范围
+
+- `--apply` / 写回 task status / 事件溯源（候选 B）  
+- G7 / `harness run` / 完整 runner  
+- N2-C · lint severity 升 **block**（候选 D；J 已测 FAIL≈93%）  
+- 改变 `verify` / `close` 硬闸语义（dry-run 仍旁路）  
+- E · `discipline show`（下一棒）
+
+---
+
+## 4. 验收清单
+
+- [ ] `to_30` + fixture：`HG-TASK-DRAFT` · `audit_D5` · `task_lint` 均出现非 `unevaluated` 的 `pass|fail|warn`
+- [ ] 既有两 adapter 回归绿
+- [ ] `--allow-lint-fail` 对 `task_lint` 行为可测
+- [ ] 无 `--task`：unevaluated 语义不变
+- [ ] `npm test` 全绿 · 文档列出已接线守卫
+- [ ] **无** `--apply` 旗
+
+---
+
+## 5. 思考轮控制表（摘要）
+
+| 字段 | 值 |
+| --- | --- |
+| `actual_last_round` | R2 |
+| `early_stop` | yes |
+| `early_stop_reason` | 扩面集合由 yaml to_30 未接线项冻结；与 T2 SPEC 方案 B 同构，争议面小 |
+| `residual_risks` | ① D5 与 verify 路径细微漂移；② close_* 仍 unevaluated 须文档标明；③ 与 E 同窗发版叙述勿漏 |
+
+---
+
+## 8. 下一棒 Prompt（人签后）
+
+```text
+【00】draft task · slug cyning-harness-lifecycle-guard-expand · Open Folder cyning-harness/
+约束：本 SPEC D1 必须接线；无 apply；无 N2-C；E 不得同 PR 抢做
+```

package/docs/spec/SPEC-post-g4-debt-retro_v1.md

@@ -0,0 +1,237 @@
+# SPEC：Post-G4 / N1–N4 欠账复盘与下一 Epic 点菜（v1）
+
+> **状态**：`signed`（维护者签收 2026-07-25 · 对话「签收」）  
+> **track**：`docs`（评估轨 · 非改码 Epic）  
+> **关联图谱**：无（文档复盘；不改 `_tech_graph`）  
+> **上游**：[`PLAN_post_g4_next_mechanization_v1_zh.md`](../../../docs/harness/guides/PLAN_post_g4_next_mechanization_v1_zh.md)（**closed**）· rethink [`2026-07-mechanization-rate/`](../rethink/2026-07-mechanization-rate/)（01–04）  
+> **前置**：G1–G4 ✅ · N1–N4 `@cyning/harness@2.7.0–2.9.0` published · CLOSE ✅  
+> **下游**：00 已起草 task（HG-TASK-DRAFT pending）→ 20-task-audit → HG-AUDIT-R1 → 30 写复盘文；**不**直接发版
+
+---
+
+## Harness 元信息
+
+| 字段 | 值 |
+|------|-----|
+| **spec_slug** | `post-g4-debt-retro` |
+| **test_strategy** | `not_applicable` |
+| **test_strategy_note** | 交付物为复盘文档 + 欠账表 + ≤3 条下一 Epic 点菜建议；不改引擎/CLI/包版本；无可失败自动化测试对象 |
+| **entry_invoke_10_spec** | `Projects/docs/harness/invokes/by-task/cyning-harness-post-g4-debt-retro/invoke_20260725_10_spec_post_g4_debt_retro.md` |
+| **entry_invoke_00_draft** | `Projects/docs/harness/invokes/by-task/cyning-harness-post-g4-debt-retro/invoke_20260725_00_draft_post_g4_debt_retro.md` |
+
+---
+
+## 1. 背景与目标
+
+2026-07-24～25 完成文档层主链机械化收口：
+
+| 波次 | 版本 | 要点 |
+|------|------|------|
+| G1+G3 | 2.3.0 | `task lint` 结构 / 绝对路径 |
+| G2 | 2.5.0 | reviews 留档（`--task` / close） |
+| G4 | 2.6.0 | 思考轮结构（条件触发） |
+| N1+N2 | 2.7.0 | `lifecycle.yaml` + `verify --task` lint **WARN** |
+| N3 | 2.8.0 | `verify --spec` |
+| N4 | 2.9.0 | 裸 `verify` 全量 reviews + 双路径 active |
+
+[`PLAN_post_g4_next_mechanization_v1_zh.md`](../../../docs/harness/guides/PLAN_post_g4_next_mechanization_v1_zh.md) 已 **closed**。维护者指令：**针对最近欠账与更新做复盘**；须 **多轮思考防遗漏**（禁止 early_stop）。
+
+**问题（PLAN 关闭后真空）**：候选下一棒（方向二引擎 / 方向三 git·契约 / dogfood 修齐 / N2-C block）散落在 PLAN §1–§3、rethink 03–04、各 SPEC residual、dogfood 口头结论中，**无单一复盘真值** → 点菜易漏项或重复立项。
+
+**目标**：产出一份可签收的复盘交付包，使维护者能在「不改码、不发版」前提下完成点菜决策；并显式点名全部已知欠账与双仓发布态。
+
+---
+
+## 2. 范围（R2 裁定后）
+
+### D1 · 复盘文落盘
+
+- 主文路径（二选一 · 实现 task 时定稿，本 SPEC 推荐见 R2）：  
+  - **推荐 A**：`docs/harness/guides/RETRO_post_g4_n1n4_debt_v1_zh.md`（工作区编排可见 · 与 PLAN 同层）  
+  - **备选 B**：`cyning-harness/docs/rethink/2026-07-post-g4-debt-retro/`（产品仓 rethink 续篇）  
+- 正文须含：时间线摘要、机械化率叙事更新（Starter 文档闸主链已覆盖 vs 仍 prompt-only）、PLAN closed 后真空说明。
+
+### D2 · 欠账清单表（强制四栏分类）
+
+| 分类 | 必须点名的项（最低集 · 复盘可增「新发现」行） |
+|------|-----------------------------------------------|
+| **已关账** | G1–G4；N1–N4 `@2.7–2.9`；PLAN closed |
+| **未修齐** | dogfood 缺审查文 **3**：`a5_cli_verify` · `hat_chain_pointer_sync` · `task_validate_human_gate_ci_gate`（闸可 30；N4 不强制修齐） |
+| **暂缓** | N2-C（lint→block）；G7 执行证据；G6 git 行为；HGM G2 查询；全量模式不跑 lint/D5（N2/N4 刻意非范围）；20 帽内容质量 / 40「真跑过」prompt-only |
+| **新发现 / 运维态** | 产品仓 tag/`main`/npm 时序核对；编排仓 Projects **ahead origin**（复盘时点名实测；本波不强制 push） |
+
+### D3 · 下一 Epic 点菜建议（≤3 条）
+
+- 每条：一句话目标 · 归属方向（一/二/三/运维）· 理由 · **不做清单**（防膨胀）  
+- 候选池（复盘文从中点菜，不必全开）：方向二状态机引擎骨架；G7；N2-C；dogfood 3 文修齐；方向三契约/G6；`discipline-coverage.yaml` 资产化；Projects push 卫生
+
+### D4 · 双仓与发布态核对（只读报告）
+
+- 复盘文内一小节：`@cyning/harness` 当前 version / tag `v2.9.0` / npm 是否对齐；Projects `origin/main` ahead 计数（复盘执行时重测）  
+- **不**代推、不改 npm 脚本
+
+### D5 · task 路径预告（仅指针）
+
+- 建议 task_slug：`cyning-harness-post-g4-debt-retro`  
+- 建议 active 路径：`docs/harness/tasks/active/task_cyning_harness_post_g4_debt_retro_v1.md`（**正文由 00 起草**；本 SPEC 不写 §5）
+
+---
+
+## 3. 非范围
+
+- 本波 **不**实现引擎 / 不改 `packages` 或产品仓 CLI 行为  
+- **不**强制修齐 3 个缺审查文 task（可列入点菜建议）  
+- **不**发版（无 2.9.x / 2.10.0）  
+- **不**把 lint 升 block（N2-C）、**不**做 G6/G7 实现、**不**开 HGM G2  
+- **不**代签 `HG-SPEC-SIGNOFF` / 任何人闸  
+- **不**更新 rethink 01–04 数字为「再审计」（可在复盘文注明「矩阵数字仍为 2026-07-24 快照，未重盘」）
+
+---
+
+## 4. 验收标准
+
+- [ ] 复盘主文已落盘于 D1 裁定路径，简体中文，可独立阅读  
+- [ ] 欠账表含四栏：已关账 / 未修齐 / 暂缓 / 新发现；最低集（§2 D2）无遗漏行  
+- [ ] 明确写出 PLAN closed 后「点菜真空」与闭环方式（本复盘 + 点菜 ≤3）  
+- [ ] 下一 Epic 建议 **≤3** 条，每条含理由 + 不做清单  
+- [ ] dogfood 3 task basename 与双仓发布态（npm/tag/ahead）有专节或表行  
+- [ ] 机械化率叙事：主链已机械 vs 20 内容质量 / 40 真跑过仍 prompt-only  
+- [ ] `test_strategy: not_applicable` 理由在 task 元信息回填（与本 SPEC 一致）  
+- [ ] 无产品代码 diff；无新版本号声称
+
+---
+
+## 5. failure_paths
+
+| 触发条件 | 系统行为 / 文档行为 | 可重试 |
+|----------|---------------------|--------|
+| 复盘文漏写某已知欠账 | 20-spec-audit / 维护者退回 · 补表行 | 是 |
+| 点菜建议 >3 条 | 拒签收 · 合并或降为「观察项」附录 | 是 |
+| 把实现/发版写进本波范围 | 00/30 拒开工 · 拆独立 SPEC | — |
+| 双仓状态与复盘时实测不符 | 复盘文标注「时点快照」· 不阻断签收 | 重测更新表 |
+| 误将 3 缺审 task 当作本波必做 | 对照 §3 非范围 · 仅建议栏 | — |
+
+---
+
+## 6. 依赖与引用
+
+- PLAN（closed）：`docs/harness/guides/PLAN_post_g4_next_mechanization_v1_zh.md`  
+- rethink：`cyning-harness/docs/rethink/2026-07-mechanization-rate/{01..04,README}.md`  
+- 最近 SPEC：`SPEC-verify-full-reviews-gate_v1.md`（N4 · dogfood 15/4/3）  
+- N2 residual：lint block（选项 C）须 FAIL 率下降  
+- dogfood active：  
+  - `docs/harness/tasks/active/task_cyning_harness_a5_cli_verify_v101_v1.md`  
+  - `docs/harness/tasks/active/task_harness_cyning_harness_hat_chain_pointer_sync_v1.md`  
+  - `docs/harness/tasks/active/task_harness_task_validate_human_gate_ci_gate_v1.md`  
+- 产品仓 `@2.9.0` · 编排仓 Harness 落盘惯例
+
+---
+
+## 7. 思考轮（10-spec 回填 · R0–R5 · 形态 A · 禁止 early_stop）
+
+### R0 · 读入与约束
+
+**读入**：维护者「新建任务 · 欠账与更新复盘 · 多轮防遗漏」；PLAN closed（N1–N4 published）；rethink 01（四方向排序）· 03（G7/G6 仍 P2/P3）· 04（lifecycle 文档先行已兑现；discipline YAML 仍建议）；N4 SPEC dogfood 3 缺审；用户明示欠账清单 1–8。
+
+**约束**：
+
+1. 只 SPEC + invoke；不实现、不发版、不代签。  
+2. `early_stop=no` · 跑满 R5（防遗漏优先于省轮）。  
+3. track=`docs` · `test_strategy=not_applicable`。  
+4. 交付可观测：落盘路径 + 表 + ≤3 点菜，而非「聊过就算」。
+
+**时点快照（10-spec 起草日 2026-07-25）**：产品仓 `main` 与 `origin/main` 对齐 · tag `v2.9.0` 存在 · npm `@cyning/harness@2.9.0`；编排仓 Projects **ahead origin 29**（含未追踪 interview/sim 文档等）——复盘执行须重测，防漂移。
+
+### R1 · 范围 / 非范围 / 场景
+
+**角色与场景**：
+
+| 场景 | 谁 | 要什么 |
+|------|-----|--------|
+| S1 点菜 | 维护者 | 一张欠账全景 + ≤3 可开 Epic，避免 PLAN 关闭后口头漂移 |
+| S2 考古 | 未来 10-spec / 面试叙事 | 「为何暂缓 G6/G7/N2-C」有单一出处 |
+| S3 dogfood 卫生 | 编排 Agent | 知道 3 缺审是已知债非 N4 回归失败 |
+| S4 发布卫生 | 维护者 | 双仓 tag/npm/ahead 是否再欠一刀 push |
+
+**范围边界**：复盘 + 建议；**不**消化债本身。非范围见 §3——尤其「不修 3 文 / 不发版 / 不做引擎」防止复盘 task 膨胀成隐藏 30。
+
+**遗漏扫描清单（R1 强制过一遍）**：
+
+1. 发布流程：npm ↔ tag ↔ CHANGELOG ↔ 本地 vs origin  
+2. 双仓：产品仓已同步 vs Projects ahead  
+3. dogfood：3 缺审 + N4「不强制修齐」语义  
+4. 机械化率：主链 ✅ vs 20 质量 / 40 真跑过 / 全量 lint·D5  
+5. PLAN 真空：closed 后下一动作入口 = 本复盘  
+6. 方向二/三接口：lifecycle 文档先行已有 → 引擎仍空  
+7. HGM G2：无消费者暂缓（方向四）  
+8. N2-C：warn→block 前置条件（FAIL 率）
+
+### R2 · 方案对比
+
+| 决策点 | 选项 | 裁定 | 理由 |
+|--------|------|------|------|
+| 复盘主文落点 | A 工作区 `guides/` · B 产品仓 `rethink/` · C 两者镜像 | **推荐 A 为主**；B 可作「索引一小段」链回 A（task 阶段二选一，勿双真值） | PLAN/点菜消费者在 Projects；rethink 01–04 已声明「非 SPEC」；镜像易漂移 |
+| 形态 | 仅聊天纪要 / 正式 SPEC+复盘文 / 直接开引擎 Epic | **SPEC（本文件）→ 签收 → 00 task → 复盘文** | 维护者要「新建任务」；防遗漏须可审计；引擎 Epic 须点菜后再独立 SPEC |
+| 点菜条数 | 开放列表 / 硬顶 3 / 只排序不建议 | **硬顶 ≤3** + 附录「观察项」可选 | 防同时开多 Epic；与 PLAN「点菜」语气一致 |
+| 3 缺审处理 | 本波必修 / 仅列表 / 忽略 | **仅列表 + 可进点菜候选** | N4 已裁定不强制；复盘职责是可见化 |
+| 是否重跑机械化率盘点 | 全量重盘 02/03 / 叙事增量 | **叙事增量**（主链已覆盖陈述） | 全量重盘另 Epic；本波防遗漏靠清单非重审计 |
+| test_strategy | recommended / N/A | **`not_applicable`** | 无改码；验收=文档勾选 |
+
+**弃选**：C 双落盘镜像（维护成本）；直接跳过 SPEC 开 30（违反帽链 · 且无范围闸）。
+
+### R3 · 边界 / 失败语义 / 安全
+
+- **边界**：复盘文不得声称「机械化率 XX%」新数字，除非附重盘方法；沿用 03 快照 +「主链已机械」定性即可。  
+- **失败**：漏项 → 书面审退回；把实现塞进范围 → 拒开工。  
+- **安全**：只读 git/npm 状态；不写密钥；不 push。  
+- **依赖**：签收本 SPEC 前，00 **不得**把复盘做成改 CLI 的 task。  
+- **误伤**：点菜若选「dogfood 修齐」勿与 N4 回归混淆——那是存量卫生，非 verify bug。
+
+### R4 · 验收 / 可测性 / test_strategy
+
+- 可测性 = **文档可勾选**（§4），非 pytest。  
+- `test_strategy: not_applicable` + note（元信息已填）。  
+- 建议 40 自检（task 阶段）：对 §2 D2 最低集做 diff 核对；`git status -sb` / `npm view` 结果贴进复盘「时点」节。  
+- 不要求新建自动化测试文件。
+
+### R5 · SPEC 签收就绪 · 是否可交 00 出 task
+
+**自足性**：背景、范围/非范围、欠账最低集、落盘推荐、点菜硬顶、failure_paths、双仓注意均已写入。
+
+**可交 00**：是。建议单 task：`cyning-harness-post-g4-debt-retro`（lightweight 文档 task · `test_strategy=not_applicable`）。图谱无需 bootstrap。
+
+**签收后链路**：人签本 SPEC（或轻量 20-spec-audit）→ 00 起草 task → 10-task（可 early_stop 若仅投影本 §2）→ 20-task-audit → HG-AUDIT-R1 → 30 写复盘文。
+
+**下一棒 Prompt 要点**：00 勿扩 scope 至 N2-C/G7 实现；点菜结论写进复盘文末「维护者待勾选」表即可。
+
+### 思考轮控制
+
+| 字段 | 值 |
+|------|-----|
+| `actual_last_round` | `R5` |
+| `early_stop` | `no` |
+| `early_stop_reason` | — |
+| `residual_risks` | ① 复盘执行时双仓 ahead/npm 可能已变——须时点重测；② 点菜 ≤3 仍可能争议排序（方向二 vs dogfood 卫生）——留给维护者勾选非 Agent 代决；③ rethink 03 数字未重盘，对外叙事若引用百分比须标注快照日；④ Projects 未追踪文档与 ahead 29 混杂，复盘勿误判「全是 Harness 债」；⑤ 若维护者坚持复盘落产品仓 rethink，须避免与 guides 双真值 |
+| `round_extension_note` | 维护者要求多轮防遗漏 · **禁止 early_stop** · 已跑满 R0–R5；未扩 R6 |
+
+---
+
+## 8. 建议点菜池（供复盘文精炼至 ≤3 · 非本波范围）
+
+| ID | 候选 | 方向 | 一句话理由 | 典型不做 |
+|----|------|------|------------|----------|
+| P1 | 方向二：lifecycle **转移引擎**最小骨架 | 二 | YAML 已先行；挂点决策下一台阶 | 不做完整 runner / G7 同波硬塞 |
+| P2 | dogfood：补齐 3 缺审查文 | 运维/卫生 | 裸 verify 工作区可绿；成本低 | 不改 verify 语义 |
+| P3 | N2-C：`verify --task` lint **block** | 一 | WARN 债转真闸；须先证明 FAIL 率下降 | 不做全量 lint |
+| P4 | G7 执行证据（`harness run`） | 二 | 40「真跑过」最大黑洞 | 不做 grep 伪证据 |
+| P5 | 方向三：`--json` 契约收敛 / G6 调研 | 三 | Agent 消费者放大前置 | 不上 MCP |
+| P6 | `discipline-coverage.yaml` 资产化 | 一 | 04 已建议；改进路线可版本化 | 不做重盘全量人工周 |
+
+---
+
+## 修订记录
+
+| 日期 | 摘要 |
+|------|------|
+| 2026-07-25 | 10-spec R0–R5（形态 A · early_stop=no）· 维护者指令「欠账复盘 · 多轮防遗漏」 |
+| 2026-07-25 | 维护者签收（对话「签收」）→ `signed` · 00 起草 task |

package/docs/spec/SPEC-verify-full-reviews-gate_v1.md

@@ -5,7 +5,7 @@
 > **关联图谱**：无（纯 Harness 工具链）  
 > **上游**：[`PLAN_post_g4_next_mechanization_v1_zh.md`](../../../docs/harness/guides/PLAN_post_g4_next_mechanization_v1_zh.md) · N4 · G2 residual  
 > **前置**：G2 `@cyning/harness@2.5.0`（`--task` 已查 reviews）· N3 `@2.8.0`  
-> **下游**：30/40 已完成（分支 `task/cyning-harness-verify-full-reviews-gate` · package **2.9.0** · 待 publish）
+> **下游**：CLOSE ✅ · `@cyning/harness@2.9.0` published · 合入 `main` · tag `v2.9.0`
 
 ---