coding-agent-harness 1.0.2 → 1.0.5

package/README.zh-CN.md

@@ -4,22 +4,11 @@
 
 [English](README.md) | 简体中文 | [日本語](docs-release/intl/ja-JP.md) | [한국어](docs-release/intl/ko-KR.md) | [Français](docs-release/intl/fr-FR.md) | [Español](docs-release/intl/es-ES.md) | [Deutsch](docs-release/intl/de-DE.md)
 
-AI 写代码不难。
+![Coding Agent Harness 架构图](docs-release/assets/harness-architecture.svg)
 
-难的是一个任务跑到第五个小时以后，谁还记得上一个 Agent 为什么这么改、哪些风险没处理、哪些证据是真的。
+> 开源、文档驱动、开箱即用的 Agent Harness。让 Codex、Claude Code、Gemini CLI 等 Coding Agent 在长程开发中保持上下文清晰、过程透明、结果可审查。
 
-Coding Agent Harness 做的事很朴素：把这些东西放回仓库里，再用一个 Dashboard 展示出来。
-
-![Coding Agent Harness Dashboard 总览](docs-release/assets/dashboard-overview-en.png)
-
-## 先看它怎么玩
-
-| 步骤 | 人看到什么 | Agent / CLI 做什么 |
-| --- | --- | --- |
-| 1. 安装入口 | 把 Harness 入口发给 Agent | `npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness` |
-| 2. 初始化或迁移 | Agent 先诊断仓库，再给计划 | `init` / `migrate-plan` |
-| 3. 打开 Dashboard | 看任务、风险、审查和证据 | `npx --yes coding-agent-harness dev .` |
-| 4. 交付前检查 | 用检查结果证明状态 | `check --profile target-project` |
+![Coding Agent Harness Dashboard](docs-release/assets/dashboard-overview.png)
 
 ## 一眼看懂
 
@@ -32,6 +21,8 @@ Coding Agent Harness 不是另一个聊天提示词集合。它把 Agent 长程
 - CLI 和 Dashboard 把状态、风险、迁移计划和审查证据暴露出来。
 - 下一个 Agent 不靠上一轮聊天记忆，而是从仓库事实继续。
 
+![Harness 执行流程](docs-release/assets/harness-workflow.svg)
+
 ## 这是什么
 
 Coding Agent Harness 是一套给 AI Coding Agent 使用的项目工程框架。
@@ -76,6 +67,22 @@ Harness 覆盖长程开发里的持续性问题：任务生命周期、Brief、E
 
 它让 Agent 每一步都有上下文、证据和收口标准。
 
+### 面向任务族的可复用 Preset
+
+Preset 是一个可版本化、声明式的任务方法包。它不是安装一个新 Agent，也不是替代
+Harness；它告诉 `harness new-task` 如何为某一类可重复工作创建任务：应该设置什么
+Task Kind、需要询问哪些输入、要把哪些共享 Reference 或 Artifact 复制进任务、Agent
+必须先读哪些文件，以及要生成哪些 audit / evidence 文件来证明任务创建正确。
+
+当一组任务共享同一套启动上下文时，就适合用 Preset。比如多个接口任务都依赖同一个
+上游微服务 contract、fixture packet、runbook 和验证清单，就不应该每次都把这些内容塞进
+prompt；应该把它们放进 Preset，然后用
+`harness new-task --preset <preset-id> ...` 创建每个任务。
+
+Harness 自带内置 Preset，`harness init` 会把它们 seed 到目标项目，团队也可以在
+`.coding-agent-harness/presets/` 下维护项目级 Preset。`preset-creator` Skill 用来制作
+这些 Preset 包；真正检查、安装、列出和应用 Preset 的是 Harness CLI。
+
 ### 旧项目也能迁移
 
 旧项目迁移不是直接套模板。标准流程是：先扫描项目，生成迁移计划，推荐迁移模式，向用户提问确认，再执行迁移，最后用 Dashboard 和检查结果证明迁移状态。
@@ -92,15 +99,22 @@ Coding Agent Harness 适合：
 
 ## 快速开始
 
-### 安装 Skill
+### 安装 Skills
 
-如果你的 Agent 支持 Skills，用 `npx` 安装本 Skill：
+如果你的 Agent 支持 Skills，可以用 `npx` 查看本仓库提供的 Skill。因为本仓库既有根
+Skill，也有嵌套 Skill；要看到或安装 `preset-creator`，需要加 `--full-depth`：
 
 ```bash
-npx skills add FairladyZ625/coding-agent-harness --list
+npx skills add FairladyZ625/coding-agent-harness --list --full-depth
 npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness
+npx skills add FairladyZ625/coding-agent-harness --skill preset-creator --full-depth
 ```
 
+两个 Skill 的用途不同：
+
+- `coding-agent-harness`：用于在目标项目中安装、迁移、运行和审查 Harness。
+- `preset-creator`：用于给一组重复任务制作可复用 Harness Preset。适合这些任务共享同一套方法、外部 Reference、Artifact、Evidence 要求，或需要在 Complex Task 骨架上叠加 Preset。这个 Skill 自带 Complex Task 骨架参考，所以 Agent 不需要预先理解 Harness 内部结构，也能做出正确的 Preset。
+
 安装到 Codex 全局 Skill 目录：
 
 ```bash
@@ -111,6 +125,17 @@ npx skills add FairladyZ625/coding-agent-harness \
   -y
 ```
 
+安装 Preset Creator Skill：
+
+```bash
+npx skills add FairladyZ625/coding-agent-harness \
+  --skill preset-creator \
+  --full-depth \
+  --agent codex \
+  --global \
+  -y
+```
+
 CLI 不会自动写进目标项目依赖。需要运行 Harness 命令时，用 `npx` 即可；第一次执行会从 npm 拉取包到本机 npm 缓存，不会写入目标项目：
 
 ```bash
@@ -126,6 +151,11 @@ npm install -g coding-agent-harness
 harness --help
 ```
 
+npm 安装会把内置 Preset seed 到 `~/.coding-agent-harness/presets/`。
+`harness init` 也会把这些 Preset seed 到目标项目的
+`.coding-agent-harness/presets/`，所以 Agent 可以用
+`harness preset list --json` 发现稳定的任务方法。
+
 Agent 不应静默执行全局安装。只有用户明确同意修改全局 npm 环境后，Agent 才能运行 `npm install -g coding-agent-harness`；否则继续使用 `npx --yes coding-agent-harness ...`。
 
 ### 人看的常用命令
@@ -164,9 +194,6 @@ npx --yes coding-agent-harness check --profile target-project .
 
 npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness
 
-注意：这一步会在目标仓写入 .agents/skills/coding-agent-harness/ 和 skills-lock.json。
-如果本轮只允许零写入扫描，请先跳过本步，直接使用 npx --yes coding-agent-harness ... 扫描；获准写入后再安装 Skill。
-
 先检查当前环境是否有 harness 命令。
 
 如果没有，不要静默全局安装。请先问我：
@@ -176,10 +203,10 @@ npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness
 
 只有我明确同意后，才运行：
 npm install -g coding-agent-harness
+harness preset list --json
 
 如果我不同意或没有回复，后续 CLI 都用：
 npx --yes coding-agent-harness <command>
-这是“全局 npm 安装确认”，和后面的“初始化计划确认”是两个不同确认点。
 
 在当前项目上搭建 Coding Agent Harness。
 默认使用中文模板；如果项目明确是英文团队或英文文档，请先询问我是否改用英文。
@@ -188,9 +215,9 @@ npx --yes coding-agent-harness <command>
 如果项目是微服务、多仓、前后端分仓，或依赖外部系统，请主动询问我是否有外部架构文档、接口文档、流程图、会议纪要、链接或导出包。
 外部资料很多时，请先建立 external-source-packs 索引和摘要，再把稳定结论投影到 03-ARCHITECTURE / 04-DEVELOPMENT / 06-INTEGRATIONS。
 确认后，按照 Diagnose → Decide → Scaffold → Configure → Verify → Deliver 六阶段执行。
-这里的确认是“初始化计划确认”；如果我已经在本消息里明确要求直接搭建，可视为已确认。
 执行初始化时使用：
 npx --yes coding-agent-harness init --locale zh-CN --capabilities core,dashboard .
+npx --yes coding-agent-harness preset list --json .
 
 初始化完成后，日常查看和人工确认使用动态网页：
 npx --yes coding-agent-harness dev .
@@ -209,9 +236,6 @@ npx --yes coding-agent-harness dashboard --out-dir tmp/harness-dashboard .
 
 npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness
 
-注意：这一步会在目标仓写入 .agents/skills/coding-agent-harness/ 和 skills-lock.json。
-如果本轮只允许零写入扫描，请先跳过本步，直接使用 npx --yes coding-agent-harness ... 扫描；获准写入后再安装 Skill。
-
 先检查当前环境是否有 harness 命令。
 
 如果没有，不要静默全局安装。请先问我：
@@ -221,12 +245,12 @@ npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness
 
 只有我明确同意后，才运行：
 npm install -g coding-agent-harness
+harness preset list --json
 
 如果我不同意或没有回复，后续 CLI 都用：
 npx --yes coding-agent-harness <command>
-这是“全局 npm 安装确认”，和后面的“迁移计划确认”是两个不同确认点。
 
-这个项目已有旧版 Harness。除上面 Skill 安装可能产生的 .agents/skills/coding-agent-harness/ 和 skills-lock.json 外，先不要改业务文件或 Harness 文件。
+这个项目已有旧版 Harness。先不要改文件。
 
 请先执行详尽扫描，并给我一个迁移计划：
 1. 检查当前 git 状态、Harness 状态、任务数量、brief 覆盖、visual_map 覆盖、warning/action/residual、strict 状态和 dashboard 可用性。
@@ -237,29 +261,43 @@ npx --yes coding-agent-harness <command>
    - full-semantic-rewrite：全量重写任务的 brief / execution_strategy / visual_map，让旧项目整体变成 v1.0 可读项目。
 4. 给出推荐模式、原因、预计改动范围、预计 token/时间成本、风险和是否需要 subagent。
 5. 向我提出需要确认的问题，等我确认后再开始写文件。
-这里的确认是“迁移计划确认”，不是全局 npm 安装确认。
 
 扫描阶段至少运行：
 npx --yes coding-agent-harness status --json .
 npx --yes coding-agent-harness migrate-plan --json --limit 1000 .
 
-确认执行迁移后，先生成并验证 baseline session，再创建 Complex Task preset：
-npx --yes coding-agent-harness migrate-run --locale zh-CN --session-dir /tmp/cah-migration-project --out-dir /tmp/cah-migration-project/dashboard .
-npx --yes coding-agent-harness migrate-verify /tmp/cah-migration-project/session.json
-npx --yes coding-agent-harness new-task --budget complex --preset legacy-migration --from-session /tmp/cah-migration-project/session.json
+最终迁移完成时，必须给出动态 workbench 入口或静态 dashboard HTML、session.json、normal/strict check、migrate-plan summary，以及 full-cutover 验证是否通过。需要人工确认审查时，必须通过本地网页 workbench 暴露确认操作；静态 dashboard 只作为只读证据快照。
+```
 
-这个 preset 只创建任务骨架和证据包，不会继续迁移、改写历史、stage 或 commit。后续迁移工作必须在这个 Complex Task 里推进。
+## 参与贡献
 
-最终迁移完成时，必须给出动态 workbench 入口或静态 dashboard HTML、session.json、normal/strict check、migrate-plan summary，以及 full-cutover 验证是否通过。需要人工确认审查时，必须通过本地网页 workbench 暴露确认操作；静态 dashboard 只作为只读证据快照。
+外部贡献者请先阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。它说明仓库结构、PR 要求、根包检查、Dashboard smoke test、npm package dry run 和 GUI 子模块验证。中文详细流程见 [`docs-release/guides/contributing.zh-CN.md`](docs-release/guides/contributing.zh-CN.md)。
+
+如果你想让自己的 Coding Agent 帮你改这个仓库，可以把下面这段发给它：
+
+```text
+我想给 FairladyZ625/coding-agent-harness 贡献一个聚焦改动。
+
+请从最新 main 分支开始，新建一个 feature branch。先阅读 README.md 和 CONTRIBUTING.md。改文件前，先检查相关代码/文档，并给我一个简短计划。
+
+改动要保持聚焦。只使用公开仓库文件；不要依赖维护者本地状态、隐藏工作流、凭据、生成的 Dashboard、临时文件或被 ignore 的本地专用文件。
+
+根据改动范围运行检查。仅文档改动至少运行 git diff --check。根包相关改动按需运行 npm install、npm test、npm run smoke:dashboard、npm run check、node scripts/harness.mjs check --profile target-project examples/minimal-project、npm run pack:dry-run 和 git diff --check。如果改到 harness-gui，还要运行 cd harness-gui && npm ci && npm run typecheck && npm test && npm run build。
+
+完成后，请总结改了什么，列出验证结果，说明任何未运行检查及原因，并按仓库 PR 模板准备 PR。
 ```
 
 ## 了解更多
 
+- 贡献者指南：[`CONTRIBUTING.md`](CONTRIBUTING.md)
+- 中文贡献者详细指南：[`docs-release/guides/contributing.zh-CN.md`](docs-release/guides/contributing.zh-CN.md)
 - Agent 安装指南：[`docs-release/guides/agent-installation.md`](docs-release/guides/agent-installation.md)
 - 新项目安装冒烟：[`examples/minimal-project/`](examples/minimal-project/)
 - 旧项目迁移指南：[`docs-release/guides/migration-playbook.md`](docs-release/guides/migration-playbook.md)
 - 完整旧项目迁移策略：[`docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md`](docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md)
 - 架构说明：[`docs-release/architecture/overview.md`](docs-release/architecture/overview.md)
+- 深度架构解析（中文）：[`docs-release/architecture/system-explainer/`](docs-release/architecture/system-explainer/) — 系统设计、模块依赖、任务生命周期、检查体系、数据流、Preset 与迁移引擎，含设计决策背景
+- Deep architecture explainer (en-US): [`docs-release/architecture/system-explainer/en-US/`](docs-release/architecture/system-explainer/en-US/)
 
 ## Star History
 
@@ -267,4 +305,8 @@ npx --yes coding-agent-harness new-task --budget complex --preset legacy-migrati
 
 ## License
 
-MIT
+AGPL-3.0-or-later，并附带 Generated Harness Materials 额外许可。
+
+详见 [`LICENSE`](LICENSE) 和 [`LICENSE-EXCEPTION.md`](LICENSE-EXCEPTION.md)。
+该额外许可确保 Harness 生成或安装到目标项目里的文件，不会仅仅因为由
+Coding Agent Harness 创建或更新，就自动变成 AGPL 覆盖范围。

package/SKILL.md

@@ -5,7 +5,7 @@ description: >
   做长程项目开发的团队，在用户的项目上构建一套完整的 harness 工程体系。
   包括：项目诊断、AGENTS.md + CLAUDE.md 入口文件生成、docs/ 目录搭建、Planning Loop、SSoT 治理、
   Delivery Operating Model、Repository Governance、CI/CD、Long-Running Task Protocol、Adversarial Review Report、Review Routing、Worktree 并行开发、
-  Regression SSoT 与 Evidence Depth 分级回归、Walkthrough / Closeout SSoT 收口、Cadence Ledger、经验沉淀回流（Lessons SSoT）、
+  Regression SSoT 与 Evidence Depth 分级回归、Walkthrough / Closeout SSoT 收口、Cadence Ledger、任务本地 lesson 候选与 promoted lesson 详情文档、
   Harness Ledger 全局上下文回写总账。
   当用户要求设置 coding agent 的开发流程、建立回归测试体系、设计 AGENTS.md / CLAUDE.md、
   规划长程 agent 任务的执行框架、子代理审查循环、对抗性 review 报告、搭建 harness、或者提到 harness engineering 时，使用此技能。
@@ -42,12 +42,13 @@ coding-agent-harness"，不要重新 bootstrap 覆盖整个项目。先执行增
 2. 扫描目标项目现有 `AGENTS.md`、`CLAUDE.md`、`docs/` 和 SSoT / Ledger 文件。
 3. 输出 delta plan：哪些 harness 骨架、reference、template、SSoT、Ledger 项缺失或过期。
 4. 只补齐新增标准和缺失结构；不得用模板覆盖已有业务事实、历史 walkthrough、
-   task progress、Feature SSoT、Regression SSoT 或 Lessons SSoT。
+   task progress、generated ledger、Regression SSoT 或 lesson detail docs。
 5. 对已有文档采用 merge / append / residual-with-reason；只有全新缺失文件才从模板创建。
-6. 如果引入 Lessons SSoT、Harness Ledger 或新的 reference/template，同步更新入口索引。
+6. 如果引入 Harness Ledger、lesson detail docs 或新的 reference/template，同步更新入口索引。
 7. 收口时写 walkthrough，必须包含 Lessons Reflection；新任务先写并审查
-   `lesson_candidates.md`。如人工标记值得沉淀，维护命令再写
-   `docs/01-GOVERNANCE/lessons/` 详情文档和 Lessons SSoT；最后在
+   `lesson_candidates.md`。如人工标记值得沉淀，默认先用 dry-run 或后续
+   lesson sedimentation 任务完成分类、冲突检查和建议 diff；只有人工明确批准后，
+   维护命令才写 `docs/01-GOVERNANCE/lessons/` 详情文档；最后在
    `docs/Harness-Ledger.md` 与 `docs/10-WALKTHROUGH/Closeout-SSoT.md` 记录本次 harness update 的 delta 和 Lessons Check。
 
 一句话：harness update 是 delta merge，不是重新搭一遍。
@@ -151,22 +152,32 @@ Project、Verify、Residual。`external-source-packs/` 只保存资料索引、
 初始化或迁移完成后，活跃任务必须通过 CLI 创建和推进，避免 agent 手工复制模板造成漂移：
 
 ```bash
-harness new-task <task-id> --title "<title>" --locale zh-CN|en-US /path/to/project
-harness task-start <task-id> --message "<what started>" /path/to/project
-harness task-log <task-id> --message "<what changed>" --evidence "command:TARGET:path:summary" /path/to/project
-harness task-block <task-id> --message "<blocker>" /path/to/project
-harness task-review <task-id> --message "<ready for review>" /path/to/project
-harness task-complete <task-id> --message "<closeout>" /path/to/project
+harness new-task --title "<title>" --locale zh-CN|en-US /path/to/project
+harness task-start <task-id-from-new-task-output> --message "<what started>" /path/to/project
+harness task-log <task-id-from-new-task-output> --message "<what changed>" --evidence "command:TARGET:path:summary" /path/to/project
+harness task-block <task-id-from-new-task-output> --message "<blocker>" /path/to/project
+harness task-review <task-id-from-new-task-output> --message "<ready for review>" /path/to/project
+harness review-confirm <task-id-from-new-task-output> --confirm <task-id-from-new-task-output> --message "<human confirmation>" /path/to/project
+harness task-complete <task-id-from-new-task-output> --message "<closeout>" /path/to/project
+harness lesson-promote <task-id-from-new-task-output> <candidate-id> --dry-run /path/to/project
 harness task-list --json /path/to/project
 ```
 
 - `new-task --budget simple` 创建轻量任务目录：`brief.md`、`task_plan.md`、`visual_map.md`、`progress.md`。
 - `new-task` 默认 `standard`，创建完整任务目录，包括 `brief.md`、计划、策略、路线图、进度、发现和审查文件。
 - `new-task --budget complex` 在完整任务文件之外创建 optional references/artifacts 索引。
+- `new-task --title "<title>"` 默认生成 `YYYY-MM-DD-<title-slug>-<8hex>` 任务 ID，降低多人和多 agent 同仓创建任务时的重名概率；只有 coordinator 需要固定兼容 ID 时才传显式 `<task-id>`。
 - 已存在任务不会被覆盖；旧项目迁移时先 `task-list --json`，再决定复用旧任务还是开新任务。
 - 状态推进只写 `progress.md`，不得重写历史 `task_plan.md`。
 - `simple` 任务可以直接 `in_progress -> done`；`standard` / `complex` 必须 `in_progress -> review -> done`，不能跳过 `task-review`。
-- `review-confirm` 只确认人工 review evidence / findings，不代表 closeout；closeout 仍走 walkthrough / Closeout SSoT。
+- `task-review` 只表示 Agent Review Submission：agent/coordinator 认为材料包已准备好并提交待审。它不是人工确认。
+- `review-confirm` 是唯一的 Human Review Confirmation 门禁。它只确认人工 review evidence / findings，不代表 closeout；closeout 仍走 walkthrough / Closeout SSoT。
+- Review queue 只收录已提交 review packet、材料齐全、无 blocker、等待人工确认的任务。
+- 缺文件、缺章节、缺证据、缺 lesson decision 或未执行 `task-review` 的任务进入 Missing Materials 队列，不进入 Review queue。
+- open blocking finding、状态矛盾、审计失败或需要 human waiver 的任务进入 Blocked 队列，不进入 Review queue。
+- 已 Human Review Confirmation 但 closeout / ledger / lesson routing 未完成的任务属于 Confirmed / Finalized 队列，不应显示成“仍在审查”。
+- lesson candidate 进入 Lessons 队列后，默认先 dry-run 或创建后续沉淀任务；不要在 Dashboard 或普通 closeout 中直接写共享 Lessons 表。
+- soft delete / supersede / archive 是只读可追溯生命周期，默认不 hard delete 任务目录；保留 tombstone、替代任务、原因和审计记录。
 - 证据必须进入 `task-log` 或 `progress.md`，并继续遵守 `type:PATH:summary` 格式。
 
 ### Phase 5: Verify / 验证
@@ -240,7 +251,6 @@ harness bootstrap 完成后，项目中至少应存在以下文件：
 - [ ] `docs/05-TEST-QA/Cadence-Ledger.md`
 - [ ] `docs/10-WALKTHROUGH/_walkthrough-template.md`
 - [ ] `docs/10-WALKTHROUGH/Closeout-SSoT.md`
-- [ ] `docs/01-GOVERNANCE/Lessons-SSoT.md`
 - [ ] `docs/01-GOVERNANCE/lessons/`（空目录 + .gitkeep）
 - [ ] `docs/01-GOVERNANCE/_archive/`（空目录 + .gitkeep）
 - [ ] `docs/Harness-Ledger.md`
@@ -256,7 +266,6 @@ harness bootstrap 完成后，项目中至少应存在以下文件：
 - [ ] 如启用模块并行：每个 active module 有 `docs/09-PLANNING/MODULES/<key>/module_plan.md`
 - [ ] 如启用模块并行：模块 task template / shared lock / dependency readiness 规则已落地
 - [ ] Harness checker 已通过，或 residual 写明 owner/action/status
-- [ ] Feature SSoT 文件（位置由项目决定）
 - [ ] Bootstrap Summary 已输出给用户
 
 ---
@@ -269,17 +278,17 @@ harness 搭建完成后，每个 feature 从想法到代码的标准流程：
 2. **Planning with Files** — 建任务目录，task plan / findings / progress / review 文件
 3. **Long-Running Contract（如适用）** — 明确连续执行权限、review loop、evidence、stop condition
 4. **Delivery Operating Model** — 确认本轮属于 solo / team / split-repo / program / stage-gate / kanban 哪种交付形态
-5. **SSoT 排期** — 回写到 Feature SSoT；模块并行时 worker 回写 module_plan + Coordinator Handoff，coordinator pass 回写 Module Registry / Harness Ledger；多人/多仓时回写 Delivery SSoT
+5. **任务生命周期事实** — 更新任务本地事实文件；任务生命周期总表由 CLI 生成。模块并行时 worker 回写 module_plan + Coordinator Handoff，coordinator pass 回写 Module Registry；多人/多仓时维护 Delivery SSoT
 6. **Repo Governance / CI-CD** — 确认 PR policy、required checks、branch protection、worktree concurrency
 7. **Worktree / Branch 并行开发** — 按 operating model 决定 worktree、feature branch、contract branch 或 release branch
 8. **Subagent Worker Handoff（如适用）** — coordinator 分配独立 worktree / branch / write scope；worker 提交自己的 commit 并 handoff commit SHA / checks / residuals
-9. **Adversarial Review Report（如适用）** — 在任务目录写 `review.md`，记录 material findings / no-finding / residual risk
-10. **Review Routing** — planned task 收口前自动触发 subagent / reviewer 审查，或记录 skip reason
+9. **Adversarial Review Report（如适用）** — 在任务目录写 `review.md`，记录 Agent Review Submission、material findings / no-finding / residual risk；这一步只表示提交待审，不等于人工批准
+10. **Review Routing** — planned task 收口前自动触发 subagent / reviewer 审查，或记录 skip reason；Review queue 只等待 Human Review Confirmation，缺材料和 blocker 分别进入 Missing Materials / Blocked 队列
 11. **Merge + 自动回归** — Cadence Ledger 触发对应回归面；coordinator 只集成 worker commit，不混合多个 worker 的未提交改动
 12. **Walkthrough 收口** — 写收口记录并引用 review report
 13. **Closeout SSoT 回写** — 每个 closed 任务必须记录 walkthrough 路径或受控 skip reason
-14. **Lessons Reflection** — 写 walkthrough 时主动反思共性/反复问题；新任务用 `lesson_candidates.md` 承载人工判定，`queued-promotion` 进入维护队列，`checked-created` 必须有详情文档和 SSoT 表行，旧任务兼容的 `checked-none` 必须写明原因
-15. **Harness Ledger 回写** — 记录本轮上下文维护是否完成
+14. **Lessons Reflection** — 写 walkthrough 时主动反思共性/反复问题；新任务用 `lesson_candidates.md` 承载人工判定，`queued-promotion` 进入 Lessons 队列；默认先 dry-run 或创建沉淀任务，不直接写共享 Lessons 表；`checked-created` 必须有 promoted lesson 详情文档，旧任务兼容的 `checked-none` 必须写明原因
+15. **Generated Ledger 刷新** — 由 lifecycle CLI 或 `harness governance rebuild` 生成任务生命周期总索引
 16. **Worktree 清理** — 删除已 merge 的 worktree
 
 ---
@@ -302,9 +311,9 @@ harness 搭建完成后，每个 feature 从想法到代码的标准流程：
 | Long-Running Task | `references/long-running-task-standard.md` | 任务需要连续执行、长上下文或 stop condition 时 |
 | Adversarial Review | `references/adversarial-review-standard.md` | 需要独立审查报告、信心挑战或 material finding 分级时 |
 | Review Routing | `references/review-routing-standard.md` | 决定 self-review、subagent、外部 reviewer 或人工审查时 |
-| SSoT 治理 | `references/ssot-governance.md` | 维护 Feature / Delivery / Regression / Lessons 等当前事实时 |
+| SSoT 治理 | `references/ssot-governance.md` | 维护 Delivery / Regression 等非任务生命周期事实时 |
 | 经验沉淀 | `references/lessons-governance.md` | walkthrough 收口后判断是否沉淀 lesson 时 |
-| Harness Ledger | `references/harness-ledger.md` | 记录本轮 harness 上下文维护、证据和 residual 时 |
+| Harness Ledger | `references/harness-ledger.md` | 理解 generated task lifecycle ledger 与非任务治理表边界时 |
 | Regression | `references/regression-system.md` | 设计或更新回归面、evidence depth 和 gate 时 |
 | Cadence Ledger | `references/cadence-ledger.md` | 根据改动类型触发回归批次时 |
 | Walkthrough | `references/walkthrough-closeout.md` | 收口、Closeout SSoT 和交付说明时 |
@@ -316,11 +325,9 @@ harness 搭建完成后，每个 feature 从想法到代码的标准流程：
 |------|------|------|
 | AGENTS.md | `templates/AGENTS.md.template` | 目标项目 agent 入口：宪章 + 阅读矩阵 |
 | CLAUDE.md | `templates/CLAUDE.md.template` | Claude Code 兼容 shim，指向 AGENTS.md |
-| Feature SSoT | `templates/ssot/Feature-SSoT.md` | 功能、wave、当前实施状态 |
 | Regression SSoT | `templates/ssot/Regression-SSoT.md` | 回归面、证据深度、gate 状态 |
-| Lessons SSoT | `templates/ssot/Lessons-SSoT.md` | 经验沉淀候选、审批和归档 |
 | Delivery SSoT | `templates/ssot/Delivery-SSoT.md` | 多人、多仓、阶段性交付计划 |
-| Harness Ledger | `templates/ledger/Harness-Ledger.md` | 全局 harness 上下文维护总账 |
+| Harness Ledger | `templates/ledger/Harness-Ledger.md` | CLI 生成的任务生命周期总索引 |
 | Lesson (ref-change) | `templates/lessons/lesson-ref-change.md` | Walkthrough 收口后 |
 | Lesson (new-doc) | `templates/lessons/lesson-new-doc.md` | Walkthrough 收口后 |
 | Lesson (arch/process) | `templates/lessons/lesson-arch-process-change.md` | Walkthrough 收口后 |
@@ -337,6 +344,7 @@ harness 搭建完成后，每个 feature 从想法到代码的标准流程：
 | Execution Workflow | `templates/reference/execution-workflow-standard.md` | 执行、提交、PR 和证据记录 |
 | Delivery Operating Model Standard | `templates/reference/delivery-operating-model-standard.md` | 交付组织模型选择 |
 | Repository Governance Standard | `templates/reference/repo-governance-standard.md` | repo、分支、PR、worktree 规则 |
+| Pull Request Standard | `templates/reference/pull-request-standard.md` | PR 描述、中英双语、版本影响、验证和引用 |
 | CI/CD Standard | `templates/reference/ci-cd-standard.md` | CI/CD、required checks、release residual |
 | Long-Running Task Standard | `templates/reference/long-running-task-standard.md` | 长程任务协议 |
 | Adversarial Review Standard | `templates/reference/adversarial-review-standard.md` | 对抗性审查协议 |

package/docs-release/README.md

@@ -1,7 +1,7 @@
 # Coding Agent Harness Docs Release
 
 This directory is the public-facing documentation library for Coding Agent Harness.
-It is separate from this source repository's private self-hosted harness.
+It is separate from maintainer-only operating records for this source repository.
 
 简体中文说明：这个目录只放可公开发布的方法论、架构和使用指南。它不记录本仓库自己的私有任务计划、审查草稿、ledger 或本地运行状态。
 
@@ -27,8 +27,8 @@ Public docs in this directory explain the product architecture, concepts, and re
 roadmap. They must not contain private task ledgers, local review drafts, internal
 handoffs, or user/project-specific operating state.
 
-Private operating state for this repository lives in `.harness-private/`, which is
-ignored by the open-source repository and versioned separately.
+Maintainer-only operating state for this repository is kept outside the public
+documentation tree and outside the public release package.
 
 ## How To Read This Library / 如何阅读
 
@@ -40,6 +40,8 @@ Not every document is written for the same reader.
 | --- | --- | --- |
 | Product / engineering leaders 产品和工程负责人 | `guides/repository-operating-models.md` / `guides/repository-operating-models.en-US.md` | Choose single-repo, independent multi-repo, or parent-control repository mode. 选择单仓、多仓独立或主控仓库模式。 |
 | Architects / tech leads 架构负责人 | `architecture/overview.md` / `architecture/overview.zh-CN.md` | Understand the product architecture and task lifecycle. 理解产品架构和任务生命周期。 |
+| Review owners / maintainers 审查负责人和维护者 | `guides/task-state-machine.md` / `guides/task-state-machine.en-US.md` | Understand task state, review status, closeout, and review queue semantics. 理解任务状态、审查状态、收口和审查队列语义。 |
+| External contributors 外部贡献者 | `../CONTRIBUTING.md`, `guides/contributing.md` / `guides/contributing.zh-CN.md` | Prepare a focused PR with the right local checks and CI expectations. 按正确的本地检查和 CI 预期提交聚焦 PR。 |
 | Teams adopting Harness 项目接入团队 | `guides/agent-installation.md` / `guides/agent-installation.en-US.md` | Install and operate the agent entrypoint in a target project. 在目标项目中安装和运行 Agent 入口。 |
 | Agents running a migration 执行迁移的 Agent | `guides/legacy-migration-agent-prompt.md` / `guides/legacy-migration-agent-prompt.zh-CN.md` | Follow an executable migration contract. 按可执行迁移合同工作。 |
 | Maintainers deciding what to publish 维护者 | `guides/document-audience-and-surfaces.md` / `guides/document-audience-and-surfaces.en-US.md` | Separate human docs, agent docs, and private operating state. 区分人读文档、Agent 执行文档和私有运行状态。 |
@@ -57,9 +59,11 @@ Not every document is written for the same reader.
 
 ### Methodology / 方法论
 
+- `guides/contributing.md` / `guides/contributing.zh-CN.md` — public contributor workflow, local checks, PR expectations, and GUI submodule validation. 公开贡献者流程、本地检查、PR 要求和 GUI 子模块验证。
 - `guides/document-audience-and-surfaces.md` / `guides/document-audience-and-surfaces.en-US.md` — explains which docs are for humans, which docs are for agents, and which state must stay out of public release docs. 说明哪些文档给人看，哪些给 Agent 执行，以及哪些状态不能进入公开发布文档。
 - `guides/repository-operating-models.md` / `guides/repository-operating-models.en-US.md` — compares single-repo, independent multi-repo, and parent-control repository operating models. 对比单仓、多仓独立、主控仓库三种运行模式。
 - `guides/parent-control-repository-pattern.md` / `guides/parent-control-repository-pattern.en-US.md` — describes the control-plane pattern for products with many child repositories, services, SDKs, or upstream references. 解释多子仓库、多服务、SDK、上游参考仓库场景下的控制面模式。
+- `guides/task-state-machine.md` / `guides/task-state-machine.en-US.md` — explains task state, derived lifecycle, review status, closeout, review queue buckets, and human confirmation flow. 解释任务状态、派生生命周期、审查状态、收口、审查队列分桶和人工确认流程。
 
 ### Adoption And Migration / 接入与迁移
 
@@ -86,7 +90,7 @@ The parent-control pattern is the recommended default when one product spans man
 
 Release roadmaps, staged plans, task execution strategy, final-check walkthroughs,
 and maintainer publishing notes are project operating state. Keep them in
-`.harness-private/`, not in this public documentation tree.
+maintainer-only operating records, not in this public documentation tree.
 
 ## Release Rule
 
@@ -94,4 +98,4 @@ If a document tells users how the harness works, it belongs here or under
 `references/`.
 
 If a document records how this repository is being operated, reviewed, migrated, or
-closed out, it belongs in `.harness-private/`.
+closed out, keep it outside the public documentation tree.

package/docs-release/architecture/overview.md

@@ -103,7 +103,7 @@ The target repository can be organized in three ways:
 | Parent-control repository | A parent repository owns the global Harness control plane. | Child repositories own implementation code and local checks. |
 
 For products split across frontend, backend, SDKs, services, and upstream references,
-the parent-control model keeps the agent startup point, Feature SSoT, regression
+the parent-control model keeps the agent startup point, generated task lifecycle Ledger, regression
 state, and closeout evidence in one place. See
 `docs-release/guides/repository-operating-models.en-US.md` and
 `docs-release/guides/parent-control-repository-pattern.en-US.md`.
@@ -173,19 +173,23 @@ stateDiagram-v2
   closed --> [*]
 ```
 
-The scanner keeps raw task state and derived lifecycle state separate:
+The scanner keeps raw task state, review status, closeout status, and derived
+lifecycle state separate:
 
-| Raw task state | Derived lifecycle meaning |
+| Raw task state / evidence | Derived lifecycle meaning |
 | --- | --- |
 | `not_started` / `planned` | `ready` |
 | `in_progress` | `active` |
 | `blocked` | `blocked` |
-| `review` with open blocking findings | `review-blocked` |
+| `reviewStatus = blocked-open-findings` | `review-blocked` |
 | `review` without blocking findings | `in_review` |
 | `done` without closeout | `closing` |
-| any state with closed closeout evidence | `closed` |
+| `closeoutStatus = closed` and missing human confirmation | `closed-review-pending` |
+| `closeoutStatus = closed` and `reviewStatus = confirmed` | `closed` |
 
 This prevents a task from looking finished just because one file says `done`.
+See `docs-release/guides/task-state-machine.en-US.md` for the full state and
+review queue matrix.
 
 ## Review And Closeout Gate
 
@@ -216,6 +220,14 @@ flowchart TB
 Standard and complex tasks must show progress, evidence, lesson resolution,
 review confirmation, and closeout linkage before they are treated as closed.
 
+The Review queue is only for submitted review packets that are ready for human
+confirmation. Tasks with missing packets, incomplete evidence, lesson-routing
+work, blocking findings, or historical closeout debt are routed to separate
+lifecycle queues: Missing Materials, Blocked, Lessons, Confirmed / Finalized,
+and Soft-deleted / Superseded. Agent-authored submissions can request review,
+but only committed Task Audit Metadata in `INDEX.md` marks the task as
+`confirmed`.
+
 ## Migration Rails
 
 ```mermaid

package/docs-release/architecture/overview.zh-CN.md

@@ -93,7 +93,7 @@ flowchart TB
 | 多仓独立模式 | 每个仓库都有自己的局部 `AGENTS.md` 和 `docs/`。 | 每个仓库独立执行。 |
 | 主控仓库模式 | 父仓库管理全局 Harness 控制面。 | 子仓库管理实现代码和局部检查。 |
 
-如果一个产品拆成前端、后端、SDK、微服务和上游参考仓库，主控仓库模式可以把 Agent 启动入口、Feature SSoT、回归状态和收口证据固定在一个地方。详见 `docs-release/guides/repository-operating-models.md` 和 `docs-release/guides/parent-control-repository-pattern.md`。
+如果一个产品拆成前端、后端、SDK、微服务和上游参考仓库，主控仓库模式可以把 Agent 启动入口、生成的任务生命周期 Ledger、回归状态和收口证据固定在一个地方。详见 `docs-release/guides/repository-operating-models.md` 和 `docs-release/guides/parent-control-repository-pattern.md`。
 
 ## CLI 命令面
 
@@ -158,19 +158,21 @@ stateDiagram-v2
   closed --> [*]
 ```
 
-扫描器会区分原始任务状态和派生生命周期状态：
+扫描器会区分原始任务状态、审查状态、收口状态和派生生命周期状态：
 
-| 原始任务状态 | 派生生命周期含义 |
+| 原始任务状态 / 证据 | 派生生命周期含义 |
 | --- | --- |
 | `not_started` / `planned` | `ready` |
 | `in_progress` | `active` |
 | `blocked` | `blocked` |
-| `review` 且存在阻塞 finding | `review-blocked` |
+| `reviewStatus = blocked-open-findings` | `review-blocked` |
 | `review` 且无阻塞 finding | `in_review` |
 | `done` 但缺少 closeout | `closing` |
-| 任意状态且已有 closed closeout 证据 | `closed` |
+| `closeoutStatus = closed` 且缺少人工确认 | `closed-review-pending` |
+| `closeoutStatus = closed` 且 `reviewStatus = confirmed` | `closed` |
 
 这样可以避免一个文件里写了 `done`，任务就被误认为真正完成。
+完整状态机和审查队列矩阵见 `docs-release/guides/task-state-machine.md`。
 
 ## Review 与 Closeout 门禁
 
@@ -200,6 +202,8 @@ flowchart TB
 
 standard 和 complex 任务必须具备进度、证据、lesson 决议、人工确认和收口链接，才会被视为真正关闭。
 
+Review 队列只展示已经提交审查材料包、并且可以等待人工确认的任务。缺少审查提交、证据不完整、仍有 Lesson 路由、存在阻塞发现，或历史收口债务的任务，会进入独立的生命周期队列：Missing Materials、Blocked、Lessons、Confirmed / Finalized、Soft-deleted / Superseded。Agent 写入的提交只能请求审查；只有 `INDEX.md` 中已提交的 Task Audit Metadata 才能把任务标记为 `confirmed`。
+
 ## 迁移轨道
 
 ```mermaid