coding-agent-harness 1.0.1 → 1.0.4

package/references/external-source-intake-standard.md

@@ -0,0 +1,75 @@
+# 外部资料摄取标准
+
+## 目的
+
+定义目标项目里的 Agent 如何接收、过滤、整理外部项目或微服务团队提供的大量资料。核心原则是：外部资料先进资料包，经过摘要和验证后，再投影到稳定执行文档。
+
+## 核心模型
+
+```text
+外部原始资料 -> source pack 索引 -> digest 摘要 -> 03/04/06 执行投影
+```
+
+`03-ARCHITECTURE`、`04-DEVELOPMENT`、`06-INTEGRATIONS` 不承载外部资料堆。它们只保存已经提炼、可验证、能指导当前仓库开发的事实。
+
+## Diagnose / Decide 必问条件
+
+只要目标项目满足任一条件，Agent 必须询问用户是否有外部资料：
+
+- 当前仓属于多仓系统、微服务系统、前后端分仓或平台子系统。
+- 代码中出现外部服务、SDK、API gateway、message queue、webhook、contract、schema 或 mock。
+- 用户提到其他仓库、上下游、接口文档、业务知识、系统整体设计。
+- Agent 无法只靠当前仓判断服务职责、接口契约或联调方式。
+
+推荐问题：
+
+1. 这个项目是否依赖外部服务或其他仓库？
+2. 你是否有外部团队提供的架构文档、接口文档、流程图、会议纪要、代码路径、链接或导出包？
+3. 这些资料能否复制进本仓？如果不能，是否只能保存本地路径或 URL？
+4. 哪些资料是可信来源，哪些只是历史参考？
+
+## 存储规则
+
+| 场景 | 存储方式 |
+| --- | --- |
+| 只有 1-4 个稳定外部文档 | 不必建独立 source pack；在对应 `03/04/06` 的 `Source Evidence` 中链接 |
+| 外部资料超过 5 份、跨多个主题、或会持续增长 | 创建 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/` |
+| 资料含敏感信息、密钥、客户数据或不能进仓 | 不复制原文；只记录外部路径、owner、访问条件和摘要 |
+| 资料可入仓 | 可放 `raw/`，但必须经过 digest 后才能投影到执行文档 |
+
+推荐结构：
+
+```text
+docs/04-DEVELOPMENT/external-source-packs/<source-key>/
+├── README.md
+├── digests/
+├── raw/
+└── raw-index.md
+```
+
+## 摄取流程
+
+1. Inventory：列出所有资料，记录来源、owner、时间、可信度和是否可入仓。
+2. Classify：按 architecture、development、integration、security、operations、product、unknown 分类。
+3. Sanitize：检查密钥、token、客户数据、隐私、内部账号和不可公开链接。
+4. Digest：提炼事实、疑问、不安全假设和证据。
+5. Project：把稳定事实投影到 `03/04/06`。
+6. Verify：尽可能用代码、接口测试、owner 确认或运行证据验证。
+7. Residual：不能确认的内容留在 source pack 或 `Do Not Assume`，不进入执行事实。
+
+## 投影规则
+
+| 资料内容 | 投影位置 |
+| --- | --- |
+| 服务职责、上下游、owner、数据归属、系统拓扑 | `03-ARCHITECTURE/service-catalog.md` 或 `services/<service-key>.md` |
+| 本仓开发时如何 mock、stub、启动、联调、排查 | `04-DEVELOPMENT/external-context/<service-key>.md` |
+| endpoint、payload、auth、error、event、webhook、SDK、contract test | `06-INTEGRATIONS/<contract>.md` |
+| 未确认、来源冲突、过期或背景参考 | 留在 source pack README / digest |
+
+## 禁止事项
+
+- 不把几十份外部文档直接复制到 `03-ARCHITECTURE`、`04-DEVELOPMENT` 或 `06-INTEGRATIONS` 根目录。
+- 不把 digest 当成已验证事实。
+- 不在执行文档里保留大段原文、聊天流水或历史会议记录。
+- 不把密钥、token、客户数据、个人隐私或不可公开资料提交进仓。
+- 不为每个微服务复制一套完整目录树。

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,133 +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-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 检查；如有沉淀，先写详情文档，再更新 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-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/legacy-12-phase-bootstrap.md

@@ -0,0 +1,41 @@
+# Historical 12-Phase Bootstrap
+
+This document preserves the legacy bootstrap sequence used before the v1.0 capability-based installer. It is reference material for migration only. Agents should not use this as the default install protocol for new projects.
+
+## When To Read
+
+- You are migrating a project that was created with the older 12-phase harness flow.
+- You need to map older documents into v1.0 capabilities and task contracts.
+- You need to understand why a legacy project has broad reference files, embedded roadmap sections, or single-line phase planning.
+
+## Legacy Sequence
+
+1. Project diagnosis: read `references/project-onboarding-audit.md` and produce a project diagnosis.
+2. Solution confirmation: decide harness scale from the diagnosis.
+3. Delivery operating model: classify solo, team, split-repo, program, stage-gate, or kanban delivery.
+4. Optional module registration: identify independent modules, write scopes, module registry rows, and module plans.
+5. Directory structure: create or adapt `docs/` according to the docs directory standard.
+6. AGENTS.md and CLAUDE.md: generate the root agent entrypoint and Claude Code shim.
+7. Reference standards: generate project-specific reference files under `docs/11-REFERENCE/`.
+8. Repository governance and CI/CD: define PR policy, required checks, branch protection, CI, and worktree concurrency.
+9. Planning loop: create task templates and task directories.
+10. Long-running task protocol: add long-running task standard and contract template.
+11. SSoT, lessons, harness ledger, regression, cadence, walkthrough, and closeout files.
+12. Bootstrap summary: report created files, purpose, first tasks, next actions, and checker status.
+
+## v1.0 Mapping
+
+| Legacy Area | v1.0 Destination |
+| --- | --- |
+| AGENTS.md / CLAUDE.md | Preserve existing files; merge only missing routing and residuals. |
+| Task directory with only `task_plan.md` | Add `brief.md`, `execution_strategy.md`, `visual_map.md`, `progress.md`, `findings.md`, and `review.md` only for active tasks. |
+| Embedded roadmap in `task_plan.md` | Move active roadmap rows into standalone `visual_map.md`; leave historical tasks untouched unless they are reopened. |
+| Single-line progress status | Normalize active tasks through `harness task-start`, `task-block`, `task-log`, and `task-complete`. |
+| Broad reference bundle | Declare only capabilities that are actually adopted in `.harness-capabilities.json`. |
+| Long-running task artifacts | Add or declare `long-running-task` only when active work needs continuous autonomous execution. |
+| Informal module lists | Adopt `module-parallel` only after modules have owners, write scopes, dependency rules, and registry maintenance. |
+| Historical review notes | Do not rewrite all old review files. Upgrade active release-blocking reviews to the v1 review schema first. |
+
+## Migration Rule
+
+Do not mechanically rewrite the whole project. Use `harness add-capability safe-adoption` to add the v1.0 compatibility layer, then use `harness migrate-plan --json` to produce a staged action list. Migrate active or reopened work first; leave closed historical tasks as legacy evidence unless strict gates require them.

package/references/lessons-governance.md

@@ -2,75 +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`。当候选进入
+`needs-promotion` 时，Agent 必须同步写出任务本地 `lessons/LC-*.md` 详情文件，并在
+`Detail Artifact` 列链接它；后续沉淀任务读取这个详情文件，不从表格 brief 复写正文。
+
+人工决定后只允许以下任务级状态：
+
+- `no-candidate-accepted`：接受本轮没有可复用 lesson。
+- `needs-promotion`：至少一个候选已排队进入治理沉淀。
+- `promoted`：维护命令已经创建 promoted lesson 详情文档，并回写源 candidate。
+- `rejected`：候选已带理由拒绝。
 
-1. 选择 `templates/lessons/` 下的对应模板，先创建详情文档。
-2. 详情文档必须写清背景、现状问题、建议改动、影响范围和冲突声明。
-3. 再在 Lessons SSoT 追加表行，`Detail Doc` 指向这篇详情文档。
-4. 在 Closeout SSoT / Harness Ledger 中记录 `checked-created`，并引用 lesson ID。
+`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 文件的历史收口。
 
-如果四个问题的答案全是"没有"，也不能静默跳过。必须在 Closeout SSoT 和
-Harness Ledger 中记录 `checked-none: <一句话原因>`。
+## Promotion 执行
+
+promotion 只写 promoted 详情文档和源 candidate，不写共享 Lessons 表：
+
+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-none: <reason>`：已完整检查，确认本轮没有可复用的规范/流程/架构改进。
+- `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` | 架构层面的改动建议 |
@@ -78,80 +95,75 @@ Harness Ledger 中记录 `checked-none: <一句话原因>`。
 
 ## 冲突处理规则
 
-### 规则 1：写之前必须读 SSoT
+### 规则 1：写之前必须查重
+
+Agent 在产出任何 promoted lesson 之前，必须查看：
 
-Agent 在产出任何沉淀建议之前，**必须完整读一遍 Lessons SSoT**，了解：
-- 当前有哪些 pending 条目
-- 是否有人已经对同一个 target 提出了改动
-- 当前各条目的状态
+- 任务本地 `lesson_candidates.md`
+- 任务本地 `lessons/LC-*.md`
+- `docs/01-GOVERNANCE/lessons/*.md`
+- 目标 reference / template / checker
+
+目的是确认是否已有同一 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 工作重新归类