coding-agent-harness 1.0.2 → 1.0.5

package/references/harness-ledger.md

@@ -2,13 +2,11 @@
 
 ## 核心思路
 
-Harness Ledger 是 `docs/` 骨架的全局更新总账。它不保存业务事实，也不替代
-Delivery / Feature / Regression / Lessons 四张 SSoT；它只记录每个非平凡任务是否按 harness SOP
-维护了应该维护的上下文。Closeout SSoT 则记录每个 closed 任务是否有 walkthrough 或受控 skip reason。
+Harness Ledger 是任务生命周期的全局生成索引。它把任务目录、模块任务、review、lesson、closeout 和 residual 的可扫描状态汇总到一张表，方便 Agent 快速定位；人看当前状态优先使用 Dashboard。
 
 一句话定义：
 
-> SSoT 保存当前事实；Harness Ledger 记录每轮任务是否维护了这些事实。
+> 任务本地文件保存事实；Harness CLI 从这些事实生成 Harness Ledger。
 
 ## 文件位置
 
@@ -16,135 +14,94 @@ Delivery / Feature / Regression / Lessons 四张 SSoT；它只记录每个非平
 docs/Harness-Ledger.md
 ```
 
-放在 `docs/` 根目录，而不是 `docs/01-GOVERNANCE/`。原因是它横跨 planning、
-regression、walkthrough、reference、lessons 等多个目录，是全局审计索引。
+放在 `docs/` 根目录，因为它横跨 planning、review、walkthrough、lessons 和模块索引。
 
 ## 职责边界
 
 Harness Ledger 记录：
 
-- 本任务是否创建或更新 task plan
-- 是否创建或更新 review report（如任务需要对抗性审查）
-- 是否更新或验证 Repo Governance / CI-CD guardrails
-- 是否回写 Feature SSoT
-- 是否更新 Regression SSoT 或 Cadence Ledger
-- 是否创建 walkthrough
-- 是否执行 Lessons 检查，是否产生 Lessons SSoT 条目
-- 如果产生 Lessons SSoT 条目，是否已创建 `docs/01-GOVERNANCE/lessons/` 详情文档
-- 本轮触碰了哪些 harness 文档
-- 是否有 residual 或 skipped-with-reason
+- task / module scope
+- module key
+- task title
+- lifecycle state
+- queue markers
+- task plan 路径
+- review 状态或路径
+- Lessons Check 状态
+- closeout 状态
+- residual 摘要
+- 生成日期
 
 Harness Ledger 不记录：
 
 - 每次 `progress.md` 的过程性更新
 - 每条测试输出
 - 每个 git diff 细节
-- Feature / Regression / Lessons 的业务事实本身
+- Regression / Delivery / Cadence / Closeout 的详细治理事实
+- lesson 详情正文
 - 可以从 git history 直接恢复的逐行变更
 
-## 触发规则
+`Feature-SSoT.md` 和 `Private-Feature-SSoT.md` 是旧版任务生命周期投影。当前版本在 `harness governance rebuild --archive --apply` 中归档这些旧表，不再重新生成。
 
-必须更新 Harness Ledger：
+## 生成规则
 
-1. 完成一个非平凡 task / wave / feature
-2. Bootstrap harness 完成
-3. 同步或升级最新版 coding-agent-harness
-4. 新增或修改 AGENTS.md / CLAUDE.md / reference / template
-5. 创建或更新 required review report
-6. coordinator pass 同步模块任务的全局状态、review、closeout 或 regression 结果
-7. 修改 Repo Governance / CI-CD / required checks / branch protection 状态
-8. 修改 Feature SSoT、Regression SSoT、Lessons SSoT 任一文件
-9. 创建 walkthrough
-10. Lessons approved 后合入正式 reference
+触发任务生命周期变化时，优先使用 CLI：
 
-不需要更新 Harness Ledger：
-
-1. 小 typo
-2. 单次 `progress.md` 过程性更新
-3. 普通测试输出粘贴
-4. 只读分析
-5. routine regression batch 只更新 `Last Verified` 且无 residual /
-   evidence depth 变化
-
-## 状态词
-
-字段值必须使用固定词，避免自由文本失控：
-
-- `required`
-- `updated`
-- `created`
-- `checked-none`
-- `checked-candidate`
-- `queued-promotion`
-- `checked-created`
-- `n/a`
-- `skipped-with-reason`
-- `missing`
-
-## ID 规则
-
-格式：
-
-```text
-HL-YYYYMMDD-NNN
+```bash
+harness new-task --title "<title>"
+harness task-start <task-id>
+harness task-phase <task-id> <phase-id> --state done
+harness task-review <task-id>
+harness task-complete <task-id>
+harness governance rebuild --archive --apply
 ```
 
-示例：
+Agent 不应手写或机械更新 Ledger 的任务行。如果发现生成结果不对，应修复 scanner、generator 或任务本地事实，再重新生成。
 
-```text
-HL-20260511-001
-```
+## 与其他治理表的关系
+
+- Delivery SSoT 仍管理交付 block、跨仓顺序、owner 和依赖。
+- Regression SSoT 仍管理回归面、证据深度和 residual。
+- Cadence Ledger 仍管理周期性验证节奏。
+- Closeout SSoT 仍管理 walkthrough、closeout status 和受控 skip reason。
+- Module Registry 仍管理模块边界、owner、worktree 和写入范围。
 
-多 agent 并行时，每个 agent 只追加或更新自己负责的 row。冲突时保留双方 row，
-不要重排全表。
+这些表不是任务生命周期小表。本版本只移除 `Feature-SSoT.md` / `Private-Feature-SSoT.md` 这类生命周期投影，不删除尚无等价 scanner/generator 的治理表。
 
 ## 归档规则
 
-Active 表保留最近 50 条。更早的 `closed` 或 `superseded` 条目按季度归档：
+旧生命周期表切换时归档到：
 
 ```text
-docs/01-GOVERNANCE/_archive/Harness-Ledger-archive-YYYY-QN.md
+docs/09-PLANNING/_archive/<timestamp>/
 ```
 
-归档不改变 `HL-*` ID，也不删除 walkthrough、task plan 或四张 SSoT 中的引用。
+归档不改变历史证据，也不要求迁移 Agent 删除旧快照。确认 Dashboard、`task-list`、`task-index` 和新 Ledger 都能表达当前任务后，项目 owner 再决定是否清理归档。
 
 ## Closeout 顺序
 
 每个非平凡任务收口时按以下顺序：
 
-1. 更新 `progress.md`
-2. 跑必要验证和 regression gate
-3. 回写 Feature SSoT；模块并行 worker 只回写 module_plan 和 Coordinator Handoff，coordinator pass 再同步 Module Registry / Harness Ledger
-4. 完成 `review.md` 并处理 material findings（如适用）
-5. 回写 Repo Governance / CI-CD 状态（如适用）
-6. 回写 Regression SSoT / Cadence Ledger（如适用）
-7. 写 walkthrough
-8. 更新 Closeout SSoT
-9. 执行 Lessons 检查；新任务先更新 `lesson_candidates.md`，如人工确认沉淀，再由维护命令写详情文档并更新 Lessons SSoT
-10. 更新 Harness Ledger
-
-最后更新 Harness Ledger，是为了让它记录本轮所有上下文维护的最终状态。
-如果 Harness Ledger row 进入 `closed` / `closed-with-residual` / `closed-local-only`，
-必须同步在 `docs/10-WALKTHROUGH/Closeout-SSoT.md` 登记 walkthrough 或受控 skip reason。
-同时必须登记 Lessons Check：`checked-candidate: LC-...`、`queued-promotion: LC-...`、
-`checked-created: L-YYYY-MM-DD-NNN`，或旧任务兼容的 `checked-none: <reason>`。
+1. 更新 `progress.md` 或等价任务本地事实。
+2. 跑必要验证和 regression gate。
+3. 完成 `review.md` 并处理 material findings（如适用）。
+4. 回写 Repo Governance / CI-CD 状态（如适用）。
+5. 回写 Regression SSoT / Cadence Ledger / Delivery SSoT 等本轮实际触达的非生命周期治理表（如适用）。
+6. 写 walkthrough。
+7. 更新 Closeout SSoT。
+8. 执行 Lessons 检查；新任务先更新 `lesson_candidates.md`，如人工确认沉淀，再由维护命令写详情文档。
+9. 运行 Harness CLI 生成或刷新 Harness Ledger。
 
-## Harness Update 记录
-
-更新已有 harness 时，Ledger row 只记录本次 delta merge：
+最后刷新 Harness Ledger，是为了让它记录本轮任务本地事实和治理表维护结果的最终状态。
 
-- 读到了哪个最新版 Skill / reference / template
-- 新增或修补了哪些 harness 骨架文件
-- 哪些既有 SSoT / walkthrough / task history 被保留未覆盖
-- 是否产生 residual，例如某个标准暂不适合当前项目
+## Harness Update 记录
 
-不要把模板全文、旧文档全文或逐行 diff 复制进 Ledger。细节由 git history 和
-walkthrough 保存，Ledger 只回答"这次升级维护了哪些上下文入口"。
+更新已有 harness 时，Ledger row 只记录本次 task lifecycle delta。具体标准、模板、reference 的合并细节由 task plan、progress、walkthrough 和 git history 保存。
 
 ## 常见反模式
 
-- 把 Harness Ledger 写成逐行 diff 日志
-- 把 Feature / Regression / Lessons 的业务事实复制进 Ledger
+- 手写 Ledger 任务行而不是修复任务事实或生成器
+- 把 Regression / Delivery 的详细治理事实复制进 Ledger
 - 每次测试或每次 progress 变动都追加 row
 - 用自由文本状态导致无法快速扫描
-- 任务完成但 Ledger 标记 `missing` 没有 residual 说明
+- 旧 Feature 生命周期表归档后又重新创建

package/references/lessons-governance.md

@@ -2,92 +2,92 @@
 
 ## 核心思路
 
-Agent 在 Walkthrough 收口时自动识别可沉淀的经验，先将详细内容落到
-`docs/01-GOVERNANCE/lessons/` 目录，再写入 Lessons SSoT。人审批后决定是否合入正式 reference。
+Lessons 不再使用一张手工维护的全局表。原因很简单：lesson candidate 是任务收口时的审查材料，promotion 是后续治理动作；把两者都塞进共享表，会让多个 agent 争抢同一个文件，也会让表和任务本地事实漂移。
 
-**硬规则：Lessons SSoT 表行不能单独存在。** 每一条 pending lesson 必须有一篇
-`docs/01-GOVERNANCE/lessons/L-YYYY-MM-DD-NNN-<slug>.md` 详情文档，表里的
-`Detail Doc` 列必须指向这篇文档。如果只是填表而没有详情文档，这次 closeout
-不算完成。
+新的事实来源只有三层：
 
-这是 harness 的第三条 SSoT 轨道：
+| 层级 | 文件 | 职责 |
+| --- | --- | --- |
+| 任务本地队列 | `docs/09-PLANNING/**/lesson_candidates.md` | 记录候选、拒绝、无候选、排队 promotion 和人工判定 |
+| 任务本地详情 | `docs/09-PLANNING/**/lessons/LC-*.md` | 在源任务上下文还新鲜时写完整 lesson 正文，供后续沉淀任务读取 |
+| Promoted lesson 详情 | `docs/01-GOVERNANCE/lessons/L-YYYY-MM-DD-NNN-<slug>.md` | 记录已接受、可复用、需要后续治理合入的经验 |
 
-| SSoT | 管什么 | 位置 |
-|------|--------|------|
-| Feature SSoT | 实施排期 | `docs/09-PLANNING/` |
-| Regression SSoT | 回归控制 | `docs/05-TEST-QA/` |
-| **Lessons SSoT** | **经验沉淀** | **`docs/01-GOVERNANCE/`** |
-
-Lessons SSoT 管“规范是否应该演进”。本轮任务是否做过 Lessons 检查、是否创建了
-Lessons 条目，由 `docs/Harness-Ledger.md` 记录，避免把 SOP 合规状态塞进
-Lessons SSoT。
+`docs/Harness-Ledger.md` 和 `docs/10-WALKTHROUGH/Closeout-SSoT.md` 只记录 closeout 结果：
+`checked-candidate:<LC-ID>`、`queued-promotion:<LC-ID>`、`checked-created:<L-ID>` 或历史兼容的 `checked-none:<reason>`。
 
 ## 目录结构
 
-```
+```text
 docs/01-GOVERNANCE/
-├── Lessons-SSoT.md              ← 沉淀建议表（SSoT）
-├── lessons/                     ← 具体沉淀内容存放
-│   ├── L-2026-05-07-001-xxx.md  ← 单条沉淀建议的详细内容
+├── lessons/                     ← promoted lesson 详情文档
+│   ├── L-2026-05-07-001-xxx.md
 │   └── ...
-└── _archive/                    ← 已处理的历史条目归档
-    └── Lessons-SSoT-archive-YYYY-QN.md
+└── _archive/                    ← 已合入或废弃的历史详情归档
+
+docs/09-PLANNING/TASKS/<task-id>/
+├── lesson_candidates.md          ← 候选索引和人工路由状态
+└── lessons/
+    └── LC-YYYYMMDD-NNN.md        ← task-local detail artifact
 ```
 
 ## 触发时机
 
-在 Walkthrough 收口流程中，写完 Walkthrough 并更新 Feature/Regression SSoT 之后，Agent 执行经验沉淀检查：
+在 Walkthrough 收口流程中，写完 Walkthrough 并更新 Feature / Regression / Closeout / Ledger 之后，Agent 执行经验沉淀检查：
 
 1. 这次开发中有没有发现现有 reference 不够用或有误的地方？
-2. 有没有值得固化为规范的新模式/新做法？
+2. 有没有值得固化为规范的新模式或新做法？
 3. 有没有踩坑经验值得记录，避免下次重复？
 4. 有没有架构层面的洞察，值得更新架构文档？
 
-如果任何一条答案是"有"，先写入任务目录的 `lesson_candidates.md`，由人工 review 决定是否进入治理 promotion。
+如果任何一条答案是“有”，先写入任务目录的 `lesson_candidates.md`。当候选进入
+`needs-promotion` 时，Agent 必须同步写出任务本地 `lessons/LC-*.md` 详情文件，并在
+`Detail Artifact` 列链接它；后续沉淀任务读取这个详情文件，不从表格 brief 复写正文。
+
 人工决定后只允许以下任务级状态：
 
 - `no-candidate-accepted`：接受本轮没有可复用 lesson。
 - `needs-promotion`：至少一个候选已排队进入治理沉淀。
-- `promoted`：维护命令已经写入 Lessons SSoT 和详情文档。
+- `promoted`：维护命令已经创建 promoted lesson 详情文档，并回写源 candidate。
 - `rejected`：候选已带理由拒绝。
 
-`needs-promotion` 不阻塞任务 closeout，但必须在 Closeout SSoT / Harness Ledger 中记录
-`queued-promotion: LC-YYYYMMDD-NNN`，并由后续维护命令处理。`promoted` 或人工直接创建时记录
-`checked-created: L-YYYY-MM-DD-NNN`。如果没有候选，记录 `checked-candidate: LC-...` 或
-`checked-none: <reason>`，其中 `checked-none` 只用于旧任务兼容或没有 candidate 文件的历史收口。
+`needs-promotion` 不阻塞任务 closeout，但必须在 Closeout SSoT / Harness Ledger 中记录 `queued-promotion: LC-YYYYMMDD-NNN`，并由后续维护任务处理。模块级候选还必须填写 `Module Key`，避免沉淀任务丢失模块边界。`promoted` 或人工直接创建详情文档时记录 `checked-created: L-YYYY-MM-DD-NNN`。如果没有候选，记录 `checked-candidate: LC-...` 或 `checked-none: <reason>`；`checked-none` 只用于旧任务兼容或没有 candidate 文件的历史收口。
 
-promotion 执行“双写”：
+## Promotion 执行
 
-1. 选择 `templates/lessons/` 下的对应模板，先创建详情文档。
-2. 详情文档必须写清背景、现状问题、建议改动、影响范围和冲突声明。
-3. 再在 Lessons SSoT 追加表行，`Detail Doc` 指向这篇详情文档。
-4. 在 Closeout SSoT / Harness Ledger 中记录 `checked-created` 或 `queued-promotion`，并引用 lesson/candidate ID。
+promotion 只写 promoted 详情文档和源 candidate，不写共享 Lessons 表：
 
-如果四个问题的答案全是"没有"，也不能静默跳过。新任务必须在 `lesson_candidates.md` 中使用
-`no-candidate-accepted` 并填写 No-Candidate Reason；旧任务可在 Closeout SSoT 和 Harness Ledger 中记录
-`checked-none: <一句话原因>`。
+1. 读取源任务 `lesson_candidates.md` 中的 `Detail Artifact` 指向的任务本地详情文件。
+2. 选择 `templates/lessons/` 下的对应模板，或由 `lesson-promote --apply` 创建 promoted 详情文档。
+3. promoted 详情文档写清背景、现状问题、建议改动、影响范围和冲突声明。
+4. 回写源任务 `lesson_candidates.md`：对应候选标记为 `promoted`，并记录 `promoted:<L-ID>`。
+5. 在 Closeout SSoT / Harness Ledger 中记录 `checked-created:<L-ID>` 或 `queued-promotion:<LC-ID>`。
+
+`lesson-promote --apply` 是 CLI-owned 机械写入：目标仓库必须是干净 Git root，
+命令会加 governance lock，只允许提交新 lesson detail 和源任务 `lesson_candidates.md`。
+如果存在 unrelated dirty diff，命令必须拒绝，让 coordinator 先提交、归属或记录 no-commit reason。
+
+如果四个问题的答案全是“没有”，也不能静默跳过。新任务必须在 `lesson_candidates.md` 中使用 `no-candidate-accepted` 并填写 No-Candidate Reason；旧任务可在 Closeout SSoT 和 Harness Ledger 中记录 `checked-none: <一句话原因>`。
 
 ## Closeout 判定
 
 收口时只允许以下合格状态：
 
-- `checked-created: L-YYYY-MM-DD-NNN`：发现可沉淀经验，已创建详情文档并更新 Lessons SSoT。
+- `checked-created: L-YYYY-MM-DD-NNN`：发现可沉淀经验，已创建 promoted lesson 详情文档。
 - `queued-promotion: LC-YYYYMMDD-NNN`：人工确认候选值得沉淀，但交给维护命令后续提升。
 - `checked-candidate: LC-YYYYMMDD-NNN`：人工已审查 candidate 文件，结论为无候选或全部拒绝。
 - `checked-none: <reason>`：旧任务兼容状态，已完整检查且没有 candidate 文件。
 
 以下状态不合格：
 
-- 只写 Lessons SSoT 表行，没有详情文档。
-- 只写详情文档，没有 Lessons SSoT 表行。
-- 在 walkthrough 或 progress 中说“无 lessons”，但 Closeout SSoT / Harness Ledger 没有记录。
+- 只在 walkthrough 或 progress 中说“无 lessons”，但 Closeout SSoT / Harness Ledger 没有记录。
 - 新任务跳过 `lesson_candidates.md`，只用 `checked-none` 代替 candidate 判定。
 - 用 `n/a` 代替检查结果，除非任务是纯只读分析且没有 closed ledger row。
+- `checked-created:<L-ID>` 指向的 `docs/01-GOVERNANCE/lessons/*.md` 不存在。
 
 ## 沉淀类型
 
 | Type | 说明 |
-|------|------|
+| --- | --- |
 | `ref-change` | 修改现有 reference 文档 |
 | `new-doc` | 新增文档/规范 |
 | `arch-change` | 架构层面的改动建议 |
@@ -95,80 +95,75 @@ promotion 执行“双写”：
 
 ## 冲突处理规则
 
-### 规则 1：写之前必须读 SSoT
+### 规则 1：写之前必须查重
+
+Agent 在产出任何 promoted lesson 之前，必须查看：
+
+- 任务本地 `lesson_candidates.md`
+- 任务本地 `lessons/LC-*.md`
+- `docs/01-GOVERNANCE/lessons/*.md`
+- 目标 reference / template / checker
 
-Agent 在产出任何沉淀建议之前，**必须完整读一遍 Lessons SSoT**，了解：
-- 当前有哪些 pending 条目
-- 是否有人已经对同一个 target 提出了改动
-- 当前各条目的状态
+目的是确认是否已有同一 target、同一问题或冲突建议。
 
 ### 规则 2：副本始终基于正式版本
 
-无论 SSoT 上有多少个 pending 的改动指向同一个 target，新的副本**始终基于当前正式 reference 的最新版本**，不基于任何未合入的 pending 副本。
+无论已有多少个待处理 lesson 指向同一个 target，新的副本始终基于当前正式 reference 的最新版本，不基于任何未合入的 pending 副本。
 
-**原因**：人可能选择不采纳之前的 pending 改动。如果基于别人未合入的副本去改，一旦那个被 reject，改动就建立在错误基础上。
+原因：人可能选择不采纳之前的 pending 改动。如果基于别人未合入的副本去改，一旦那个被 reject，改动就建立在错误基础上。
 
 ### 规则 3：以解决冲突的方式编写
 
-如果发现有 pending 条目指向同一 target，Agent 必须：
-1. 读取那个 pending 条目的内容（了解对方想改什么）
-2. 在自己的副本中，以"解决冲突"的方式编写——即：假设对方的改动最终也会被采纳，自己的改动应该与之兼容
-3. 在"冲突声明"中明确说明：我看到了 L-XXX 的改动，我的副本已考虑兼容
-4. 但**不是在对方副本之上修改**，而是独立基于正式版本编写
+如果发现已有 lesson 指向同一 target，Agent 必须：
 
-### 规则 4：人做最终聚合
+1. 读取那个 lesson 的内容，了解对方想改什么。
+2. 在自己的详情文档中，以解决冲突的方式编写。
+3. 在“冲突声明”中明确说明看到了哪个 lesson，自己的建议如何兼容或取代它。
+4. 独立基于正式版本编写，不直接修改对方详情文档。
 
-当多个 pending 条目指向同一 target 时，人在审批时可以：
-- 逐个 approve，按顺序合入
-- 一次性看所有 pending 改动，做聚合后合入
-- reject 部分，approve 部分
-- 要求 Agent 基于审批结果重新生成一个合并版本
+### 规则 4：人做最终聚合
 
-### 规则 5：SSoT 表标记冲突
+当多个 lesson 指向同一 target 时，人在审批时可以：
 
-当新条目与已有 pending 条目指向同一 target 时，两个条目的 Conflict 列都要标记对方的 ID。人一眼就能看到"这两个要一起审"。
+- 逐个 approve，按顺序合入。
+- 一次性看所有 pending 改动，做聚合后合入。
+- reject 部分，approve 部分。
+- 要求 Agent 基于审批结果重新生成一个合并版本。
 
 ## 状态流转
 
-```
-🟡 pending → 🟢 approved → ✅ merged
-                         ↘ (人决定不合入) → ❌ rejected
-          → 🔀 superseded (被后续条目取代)
+```text
+lesson_candidates.md:
+pending-review -> needs-promotion -> promoted
+               -> rejected
+               -> no-candidate-accepted
+
+lesson detail docs:
+pending governance integration -> approved -> merged
+                                -> rejected
+                                -> superseded
 ```
 
 ## 归档机制
 
-### 触发条件
-- Active Lessons 表超过 **20 条**时，将所有 `✅ merged` 和 `❌ rejected` 的条目移入归档
-- 人也可以手动触发归档
-
-### 归档格式
-```
-docs/01-GOVERNANCE/_archive/Lessons-SSoT-archive-YYYY-QN.md
-```
-
-### 归档后
-- Active 表只保留 `🟡 pending` / `🟢 approved` / `🔀 superseded` 的条目
-- 归档文件保留完整历史，可追溯
+当 `docs/01-GOVERNANCE/lessons/` 中已合入或废弃的详情文档过多时，可以把 `merged`、`rejected`、`superseded` 的文档移入 `docs/01-GOVERNANCE/_archive/`。不要归档仍被 Closeout SSoT 或 Harness Ledger 当前行引用的文档，除非同步更新引用。
 
 ## 人的审批工作流
 
-1. 打开 `Lessons-SSoT.md`，看 Active 表里有没有 🟡 pending 的条目
-2. 看 Summary 列，大部分情况一句话就能判断
-3. 需要细看就点进 Detail Doc 路径，看完整副本和改动理由
-4. 有冲突的条目一起审（看 Conflict 列）
-5. 批准后改状态为 🟢 approved
-6. Agent 下次看到 approved 状态就执行合入，完成后改为 ✅ merged
+1. 打开 dashboard 的 Lessons 队列，或搜索任务本地 `lesson_candidates.md` 中的 `needs-promotion`。
+2. 查看候选行的 `Detail Artifact`，确认任务本地详情正文足够完整。
+3. 需要提升时创建后续 sedimentation task，或批准 `lesson-promote --apply`。
+4. 查看生成的 `docs/01-GOVERNANCE/lessons/*.md`。
+5. 有冲突的 lesson 一起审。
+6. 批准后由维护任务更新目标 reference / template / checker。
 
 ## 合入执行
 
-当 Agent 发现 Lessons SSoT 中有 `🟢 approved` 状态的条目时：
-- `ref-change`：用 lessons/ 中的副本替换正式 reference
-- `new-doc`：将 lessons/ 中的内容移动到建议路径
-- `arch-change`：按建议更新架构文档
-- `process-change`：按建议更新流程文档
+当 Agent 获得明确的人审批准后：
 
-合入完成后，状态改为 `✅ merged`。
+- `ref-change`：按 lesson 详情更新正式 reference。
+- `new-doc`：将 lesson 建议落到正式建议路径。
+- `arch-change`：按建议更新架构文档。
+- `process-change`：按建议更新流程文档或 CLI/checker。
 
-合入任务收口时，还必须在 `docs/Harness-Ledger.md` 的当前任务 row 中记录
-`Lessons=updated` 或 `Lessons=checked-created`。
+合入任务收口时，必须在 `docs/Harness-Ledger.md` 的当前任务 row 中记录 `checked-created:<L-ID>`、`queued-promotion:<LC-ID>` 或 `checked-candidate:<LC-ID>`。

package/references/module-parallel-standard.md

@@ -13,7 +13,7 @@
 - 各功能域的源文件几乎不重叠
 - 开发者计划多会话 / 多 worktree 并行推进
 
-不满足时继续使用 Feature SSoT + 线性 Phase 模型。
+不满足时继续使用普通任务队列 + CLI 生成 Harness Ledger，不强行拆模块。
 
 ## 核心概念
 
@@ -241,23 +241,22 @@ HARNESS_REQUIRE_GLOBAL_MODULE_SYNC=1 node scripts/check-harness.mjs <repo-path>
 - 建议频率：每周一次，或每次基础设施 task 完成后
 - 目的：避免 divergence 过大导致 merge 困难
 
-## 与 Feature SSoT 的分工
+## 与生成 Ledger 的分工
 
 启用模块并行后：
 
 - **Module Registry + module_plan.md** 追踪模块内步骤进度
-- **Feature SSoT** 只追踪：
-  - 不属于任何模块的独立功能
-  - 发布级汇总（哪个 release 包含了哪些模块步骤）
+- **Harness Ledger** 从任务本地事实生成全局生命周期索引
+- **Delivery SSoT** 只在需要跨模块、跨仓或多人交付编排时追踪 release / block 依赖
 
-**禁止**：同一个工作项同时出现在 module_plan 和 Feature SSoT 中。
+**禁止**：同一个工作项同时作为模块步骤和另一张手写任务生命周期表维护。
 
-切换时必须收缩 Feature SSoT：
+切换时必须归档 legacy 生命周期表：
 
-- Feature SSoT Active 表只保留非模块、未完成、仍需操作的 feature。
-- Phase 历史和 completed 明细移到 `docs/09-PLANNING/_archive/<feature-ssot-name>-phase-<range>.md`。
-- Feature SSoT 主文件保留 freeze notice、当前 active 指针、completed summary、archive index。
-- 不允许把历史大表留在 Feature SSoT 主文件底部作为"文件内归档"；这会让 Active SSoT 继续膨胀。
+- `Feature-SSoT.md` / `Private-Feature-SSoT.md` 移到 `docs/09-PLANNING/_archive/`。
+- Phase 历史和 completed 明细作为历史证据保留，不再作为 active 表继续维护。
+- 使用 `harness governance rebuild --archive --apply` 从 task / module 文件重建 Harness Ledger、module plan 和 visual map 索引。
+- 不允许把历史大表留在 active 生命周期入口底部作为"文件内归档"；这会让 Agent 继续读取旧状态。
 
 ## 归档与过期检测
 
@@ -277,16 +276,17 @@ HARNESS_REQUIRE_GLOBAL_MODULE_SYNC=1 node scripts/check-harness.mjs <repo-path>
 
 对已有线性 Phase 历史的项目：
 
-1. 冻结 Feature SSoT 当前状态，标注"后续工作按模块推进"
-2. 将 Feature SSoT 的历史 completed 明细移入 `docs/09-PLANNING/_archive/`，主文件只保留 active 指针、summary 和 archive index
+1. 冻结 legacy 生命周期表当前状态，标注"后续工作按模块推进"
+2. 将 `Feature-SSoT.md` / `Private-Feature-SSoT.md` 历史明细移入 `docs/09-PLANNING/_archive/`
 3. 将历史 `docs/09-PLANNING/TASKS/` 移入 `docs/09-PLANNING/_archive/`
 4. 将历史 walkthrough 移入 `docs/10-WALKTHROUGH/_archive/`
 5. 从最后一个 Phase 的未完成项中识别模块
 6. 创建 Module Registry 和各模块的 module_plan.md
 7. 创建 Module Session Prompt Pack 或每模块 `session_prompt.md`
 8. 定义切换日期，此后不再创建新 Phase
+9. 运行 `harness governance rebuild --archive --apply` 生成新的 Harness Ledger 和模块索引
 
 不做的事：
 - 不回溯重写历史 Ledger 条目
-- 不删除现有 Feature SSoT
+- 不直接删除 legacy 生命周期表证据；先归档，是否清理归档由 owner 决定
 - 不强制已完成的 Phase 工作重新归类

package/references/planning-loop.md

@@ -55,7 +55,7 @@ slices/<slice-id>/review.md
 8. **复杂任务必须记录 `execution_strategy.md`** — 是否使用 subagent、reviewer、worktree、handoff 都写入独立文件。
 9. **非平凡任务必须记录 `visual_map.md`** — 这是任务图表集合，不只是 roadmap；HTML dashboard 从独立文件的 phase table 计算完成度、阻塞和证据状态。
 10. **路径必须带来源前缀** — 使用 `PUBLIC:`, `PRIVATE:`, `TARGET:`, `EXTERNAL:`, `URL:`，避免脆弱相对路径。
-11. **已验证切片必须主动提交** — 每个有意义的工作切片通过对应检查后，agent 默认主动 commit；只有用户明确要求暂不提交、检查失败、或 dirty diff 归属未清时才延期，并把原因写入 progress / handoff。
+11. **已验证切片必须主动提交** — 每个有意义的工作切片通过对应检查后，agent 默认主动 commit；只有用户明确要求暂不提交、检查失败、或 dirty diff 归属未清时才延期，并把 no-commit reason、owner 和下一步写入 progress / handoff。
 
 ## task_plan.md 模板
 
@@ -76,10 +76,15 @@ slices/<slice-id>/review.md
 | --- | --- | --- | --- | --- |
 
 ## Execution & Visualization Files
-| Contract File | Required | Purpose |
-| --- | --- | --- |
-| `execution_strategy.md` | yes | Execution mode, subagent use, conflict control, evidence depth, handoff rules |
-| `visual_map.md` | yes | Mermaid maps, phase table, architecture/sequence/data-flow/state diagrams when useful, completion, evidence status, blocking risk |
+Do not manually copy task templates. Create task folders through `harness new-task`
+so the selected budget creates the correct files and `harness check` can enforce
+the same contract.
+
+| Budget | Required Files |
+| --- | --- |
+| simple | `brief.md`, `task_plan.md`, `visual_map.md`, `progress.md` |
+| standard | simple files plus `execution_strategy.md`, `findings.md`, `lesson_candidates.md`, `review.md` |
+| complex | standard files plus `references/INDEX.md`, `artifacts/INDEX.md` |
 
 ## 步骤
 1. [步骤1]
@@ -207,7 +212,7 @@ standard / complex:
 对 standard / complex 是硬门禁：当前状态不是 `review` 时必须拒绝。`simple`
 可以直接从 `in_progress` 完成。
 
-每次状态变更时，必须同时更新 progress.md 和 Feature SSoT。
+每次状态变更时，必须更新 task-local facts，例如 `progress.md`、`review.md` 或 `lesson_candidates.md`。任务生命周期总表由 lifecycle CLI 或 `harness governance rebuild` 生成，不手工维护 Feature lifecycle 表。
 
 任务完成时，必须在 `docs/Harness-Ledger.md` 中记录本轮 task plan、SSoT、
 walkthrough、Lessons 检查等上下文回写结果。
@@ -216,6 +221,7 @@ walkthrough、Lessons 检查等上下文回写结果。
 
 非平凡任务不是等用户提醒才提交。每个已验证、有意义、范围清晰的切片都应形成 commit。
 提交前只 stage 本任务范围内文件；无关 dirty 文件、私有文件和生成产物必须保留原样或按项目规则处理。
+不能提交时必须写清 no-commit reason、owner 和下一步；归属不清的 dirty diff 不能被混入本任务提交。
 
 任务相关 commit 应在 message footer 中引用任务 ID：