coding-agent-harness 1.0.2 → 1.0.4

package/presets/standard-task/templates/task_plan.append.md

@@ -0,0 +1,7 @@
+## Standard Task Preset
+
+This task was created through the declarative `standard-task` preset.
+
+| Field | Value |
+| --- | --- |
+| Preset Title | {{title}} |

package/references/adversarial-review-standard.md

@@ -102,7 +102,7 @@ Reviewer 必须以找问题为目标，而不是证明实现正确。
 - Progress:
 - Findings:
 - Regression SSoT:
-- Lessons SSoT:
+- Lesson Candidates / Detail Docs:
 - Walkthrough:
 ```
 
@@ -150,7 +150,7 @@ Review loop 的固定执行形态：
 - `progress.md` 记录审查发生的时间和处理结果摘要
 - `findings.md` 记录审查中产生的技术决策或研究发现
 - `Regression-SSoT.md` 记录新增或调整的 regression surface
-- `Lessons-SSoT.md` 记录可复用的流程、架构或标准改进建议
+- `lesson_candidates.md` 和 `docs/01-GOVERNANCE/lessons/*.md` 记录可复用的流程、架构或标准改进建议
 - `walkthrough` 收口时引用 `review.md` 的 material finding 状态和 no-finding 结论
 - `Harness Ledger` 记录本轮是否完成 review report
 

package/references/agents-md-pattern.md

@@ -40,7 +40,7 @@ AGENTS.md 只包含两类内容：
   先读 docs/11-REFERENCE/harness-ledger-standard.md
 
 - Walkthrough / Closeout / Lessons 收口：
-  先读 docs/11-REFERENCE/walkthrough-standard.md，然后读 docs/01-GOVERNANCE/Lessons-SSoT.md 和 docs/10-WALKTHROUGH/Closeout-SSoT.md
+  先读 docs/11-REFERENCE/walkthrough-standard.md，然后读 docs/10-WALKTHROUGH/Closeout-SSoT.md、任务本地 lesson_candidates.md 和 docs/01-GOVERNANCE/lessons/
 
 - 开发执行 / 回写流程：
   先读 docs/11-REFERENCE/execution-workflow-standard.md
@@ -100,7 +100,7 @@ CLAUDE.md 控制在 **10-50 行**。它只做 Claude Code 兼容入口，不应
 - agent 做后端重构时，不会被前端规范干扰
 - agent 做测试时，不会被文档治理规则分心
 - 每种任务类型只加载它需要的上下文
-- agent 写 walkthrough 时会被入口显式路由回 Lessons SSoT，但 Lessons 全文不会塞进 AGENTS.md
+- agent 写 walkthrough 时会被入口显式路由回 lesson candidate / detail doc 流程，但 Lessons 全文不会塞进 AGENTS.md
 
 这跟 OpenAI 在 Harness Engineering 实践中得出的结论一致：给 agent 一张地图，不给一本千页手册。
 

package/references/delivery-operating-model-standard.md

@@ -39,7 +39,7 @@ Define who breaks roadmap work into feature blocks:
 | Level | Owner | Artifact | Rule |
 |-------|-------|----------|------|
 | Roadmap | [owner] | [SSoT / issue tracker] | [how priority is chosen] |
-| Feature block | [owner] | `Delivery-SSoT.md` / Feature SSoT | [how blocks are bounded] |
+| Feature block | [owner] | `Delivery-SSoT.md` / generated Harness Ledger | [how blocks are bounded] |
 | Task | [owner] | `docs/09-PLANNING/TASKS/<task>/task_plan.md` | [who can start work] |
 | Review | [owner] | `review.md` / PR review | [required reviewers] |
 | Integration | [owner] | PR / release branch / integration branch | [merge order] |
@@ -50,14 +50,14 @@ Define who breaks roadmap work into feature blocks:
 
 Use when one human directs multiple agents across worktrees.
 
-- One primary Feature SSoT is enough for linear phase work.
+- One generated Harness Ledger is enough for ordinary task lifecycle tracking.
 - Worktree concurrency is central.
 - Merge order is human-decided.
 - Cross-task conflicts are managed by task ownership and shared-file notices.
 
 **模块并行扩展**：当项目有 2+ 个可独立演进的功能域时，启用模块并行开发（见 `references/module-parallel-standard.md`）。此时：
 
-- Module Registry 替代 Feature SSoT 作为进度追踪的主要工具
+- Module Registry 管模块边界；Harness Ledger 生成全局任务生命周期索引
 - 每个模块一个长期 worktree（`codex/<module-key>`）
 - 模块间通过 write scope 声明避免冲突
 - 跨模块修改走独立的基础设施 task

package/references/docs-directory-standard.md

@@ -8,12 +8,11 @@
 
 ```
 docs/
-├── Harness-Ledger.md           ← 全局 harness 上下文回写总账
+├── Harness-Ledger.md           ← CLI 生成的任务生命周期总账
 ├── 00-RAW-PRDS/              ← 原始需求文档、PRD、用户故事
 │   └── _archive/              ← 本层历史文档归档（如该层会增长）
 ├── 01-GOVERNANCE/             ← 项目治理规则、决策记录、经验沉淀
-│   ├── Lessons-SSoT.md        ← 经验沉淀建议表
-│   ├── lessons/               ← 具体沉淀内容
+│   ├── lessons/               ← promoted lesson 详情文档
 │   └── _archive/              ← 已处理条目归档
 ├── 02-PRODUCT/                ← 产品设计、用户流程、功能规格
 │   └── _archive/              ← 本层历史文档归档（如该层会增长）
@@ -34,9 +33,8 @@ docs/
 │   │   └── _task-template/    ← 任务模板
 │   ├── MODULES/               ← 模块并行开发计划（启用时）
 │   │   └── _archive/          ← 已完成 / 暂停过久模块归档
-│   ├── _archive/              ← 历史任务、旧 Feature SSoT 明细、过期排期归档
+│   ├── _archive/              ← 历史任务、旧生命周期表明细、过期排期归档
 │   ├── Delivery-SSoT.md       ← 多人 / 多仓 / 传统流程下的交付排期和集成顺序
-│   └── [Feature-SSoT].md     ← 实施排期表
 ├── 10-WALKTHROUGH/            ← Walkthrough 收口记录与 Closeout SSoT
 │   └── _archive/              ← 历史 walkthrough 批量归档（迁移 / 年度收束时）
 ├── 11-REFERENCE/              ← 标准文件（agent 按需加载）
@@ -133,11 +131,11 @@ Checker 规则：
 
 | 对象 | 触发条件 | 归档位置 |
 |------|----------|----------|
-| Feature SSoT Active 表 | 模块并行切换、release 完成、或 completed rows 超过 20 条 | `09-PLANNING/_archive/` |
+| Legacy Feature / Private Feature 生命周期表 | 迁移到 ledger-only 版本 | `09-PLANNING/_archive/` |
 | Delivery SSoT | 集成 wave 结束或 completed/superseded blocks 超过 20 条 | `09-PLANNING/_archive/` |
 | Module Registry / module_plan | 模块 completed 或 paused 超过 60 天 | `09-PLANNING/MODULES/_archive/<key>/` |
 | Regression SSoT | gate 废弃或长期不再运行 | `05-TEST-QA/_archive/` |
-| Lessons SSoT | merged/rejected 条目超过 20 条 | `01-GOVERNANCE/_archive/` |
+| Lesson detail docs | merged/rejected/superseded 详情文档超过 20 条 | `01-GOVERNANCE/_archive/` |
 | Harness Ledger | closed/superseded 超过 50 条 | `01-GOVERNANCE/_archive/` |
 | Walkthrough | 年度/阶段迁移或目录过大 | `10-WALKTHROUGH/_archive/` |
 
@@ -151,6 +149,7 @@ Checker 规则：
 | execution-workflow-standard.md | 开发执行流程、commit 规范、PR 流程 | 是 |
 | delivery-operating-model-standard.md | 工程组织形态、feature block 拆分、跨仓/团队协作模型 | 是 |
 | repo-governance-standard.md | repo platform、branch protection、PR policy、required checks、worktree concurrency | 是 |
+| pull-request-standard.md | PR 描述结构、中英双语要求、版本影响、验证、审查证据、残余风险和引用 | 是 |
 | ci-cd-standard.md | CI/CD profile、workflow、required checks、release/CD residual | 是 |
 | long-running-task-standard.md | 长程任务合同、连续执行权限、review loop、停止条件 | 是 |
 | adversarial-review-standard.md | 对抗性 review 报告、finding 分级、no-finding 结论、residual 路由 | 是 |

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 <task-id>
+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>`。