coding-agent-harness 1.0.1 → 1.0.4

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 时，使用此技能。
@@ -24,6 +24,7 @@ description: >
 - **单元测试只是底线，不是保障。** 真正的保障需要多层证据（Evidence Depth）。
 - **先识别交付组织，再设计 harness。** 一人多 agent、多人团队、前后端分仓、program 多仓、敏捷/瀑布，对应的 SSoT 和冲突治理不同。
 - **Repo 护栏是地基。** CI/CD、PR policy、branch protection、required checks、worktree concurrency 必须项目级定制，不能停留在模板。
+- **外部资料先摄取，再投影。** 微服务或多仓项目的外部文档不能直接塞进执行文档；先建 source pack、digest、验证，再投影到 `03/04/06`。
 - **长程任务先设计合同，再开放执行。** 连续跑数小时的前提是 Goal、Scope、Review Loop、Evidence、Stop Condition 都清楚。
 - **审查必须落盘。** 对抗性 review 是独立交付物，不应只留在对话、progress 或 walkthrough 里；reviewer 必须用 Confidence Challenge 反复挑战方案，直到没有 open material finding。
 - **Worker handoff 必须 commit-backed。** 可写 subagent 不是 reviewer；它必须在独立 worktree / branch 内实现、验证并提交，再由 coordinator 集成。
@@ -41,11 +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，同步更新入口索引。
-7. 收口时写 walkthrough，必须包含 Lessons Reflection；如发现可复用教训，先写
-   `docs/01-GOVERNANCE/lessons/` 详情文档，再写 Lessons SSoT；最后在
+6. 如果引入 Harness Ledger、lesson detail docs 或新的 reference/template，同步更新入口索引。
+7. 收口时写 walkthrough，必须包含 Lessons Reflection；新任务先写并审查
+   `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，不是重新搭一遍。
@@ -57,6 +60,12 @@ coding-agent-harness"，不要重新 bootstrap 覆盖整个项目。先执行增
 `docs-release/guides/agent-installation.md`。如果本 Skill 与该指南出现差异，以
 本 Skill 的执行约束为准，并把差异记录为需要修复的文档漂移。
 
+CLI 示例默认使用目标项目可调用的 `harness` 命令。执行前先检查
+`command -v harness`；如果没有，不要静默全局安装，按安装指南询问用户是否
+允许 `npm install -g coding-agent-harness`。未获明确同意时，用
+`npx --yes coding-agent-harness <command>` 执行同一条命令。只有维护本源码
+checkout 时，才把 `harness` 替换为 `node scripts/harness.mjs`。
+
 ### Agent 安装合同
 
 这个 CLI 的主要操作者通常是目标项目里的 agent，而不是最终用户。Agent 不应要求用户
@@ -80,6 +89,12 @@ coding-agent-harness"，不要重新 bootstrap 覆盖整个项目。先执行增
 读 `references/project-onboarding-audit.md`，扫描项目技术栈、目录结构、现有文档、
 CI、团队/agent 协作方式和风险面，输出诊断报告。
 
+如果发现项目属于微服务、多仓、前后端分仓、平台子系统，或代码中出现外部服务、
+SDK、API gateway、message queue、webhook、contract、schema、mock，必须询问用户是否有
+外部资料。问题至少覆盖：是否有外部团队文档、接口文档、架构图、会议纪要、链接或导出包；
+这些资料能否复制进仓；哪些资料是可信来源。外部资料处理方法见
+`references/external-source-intake-standard.md`。
+
 ### Phase 2: Decide / 方案决策
 
 与用户确认三件事：
@@ -91,6 +106,8 @@ CI、团队/agent 协作方式和风险面，输出诊断报告。
    kanban-continuous。
 3. Capability Packs：core 必装；按需选择 module-parallel、subagent-worker、
    adversarial-review、long-running-task、dashboard、safe-adoption。
+4. External Source Intake：如果外部资料超过 5 份、跨多个主题或会持续增长，
+   决定是否创建 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`。
 
 Capability 选择规则必须按表执行，不得凭感觉多装：
 
@@ -124,13 +141,51 @@ Regression surface、Delivery SSoT、Module Registry、review routing 和
 worktree/subagent handoff 规则。已有项目事实只能 merge/append/residual，
 不能模板覆盖。
 
+如果用户提供了外部资料，Configure 阶段必须按
+`external-source-intake-standard.md` 执行：Inventory、Classify、Sanitize、Digest、
+Project、Verify、Residual。`external-source-packs/` 只保存资料索引、摘要和投影状态；
+稳定事实必须回写到 `03-ARCHITECTURE`、`04-DEVELOPMENT/external-context` 或
+`06-INTEGRATIONS`。
+
+### Phase 4b: Task Lifecycle / 任务生命周期
+
+初始化或迁移完成后，活跃任务必须通过 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 review-confirm <task-id> --message "<human confirmation>" /path/to/project
+harness task-complete <task-id> --message "<closeout>" /path/to/project
+harness lesson-promote <task-id> <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 索引。
+- 已存在任务不会被覆盖；旧项目迁移时先 `task-list --json`，再决定复用旧任务还是开新任务。
+- 状态推进只写 `progress.md`，不得重写历史 `task_plan.md`。
+- `simple` 任务可以直接 `in_progress -> done`；`standard` / `complex` 必须 `in_progress -> review -> done`，不能跳过 `task-review`。
+- `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 / 验证
 
 运行当前 repo 支持的检查命令，例如：
 
 ```bash
-node scripts/harness.mjs check --profile target-project /path/to/project
-node scripts/harness.mjs status --json /path/to/project
+harness check --profile target-project /path/to/project
+harness status --json /path/to/project
 ```
 
 如果是在开发或修改本 harness 自身，Phase 5 必须覆盖两条回归路径：
@@ -143,6 +198,15 @@ node scripts/harness.mjs status --json /path/to/project
 检查失败时不能声称 harness complete；必须修复或记录 owner/action/status 明确的
 residual。
 
+旧项目迁移时必须先运行：
+
+```bash
+harness migrate-plan --json /path/to/project
+```
+
+然后按 `docs-release/guides/migration-playbook.md` 分阶段处理。不要机械迁移所有历史
+task；先迁移活跃或重新打开的任务，再升级当前门禁相关 review 和 capability。
+
 ### Phase 6: Deliver / 交付
 
 输出 bootstrap summary，说明创建/定制了哪些文件、启用了哪些 capability、当前
@@ -158,144 +222,11 @@ Summary 至少包含：
 - residual owner / action / status
 - 是否提交；若只是 dogfood 测试，必须清理测试产物
 
-### Historical 12-Phase Bootstrap（旧版参考）
-
-以下 12-phase 流程是历史参考，用于理解旧版 harness 的组成，不再作为 v1.0
-`init` 的默认执行协议。
-
-### Phase 1: 项目诊断
-
-读 `references/project-onboarding-audit.md`，按其中的扫描清单分析用户项目现状，输出诊断报告。
-
-### Phase 2: 确认方案
-
-根据诊断结果，确定 harness 规模（参考 `references/project-onboarding-audit.md` 中的项目类型分支），与用户确认落地方案。
-
-### Phase 2b: 选择 Delivery Operating Model
-
-读 `references/delivery-operating-model-standard.md`。先判定项目的工程组织形态：
-
-- `solo-orchestrator`：一人主控，多 agent / worktree 并行
-- `team-feature-lead`：leader 拆 feature block，多人各带 agent 开发
-- `split-repo-contract`：前后端或 app/service 分仓，通过接口合同协作
-- `program-multi-repo`：主项目协调多个子仓库
-- `waterfall-stage-gate`：需求、设计、实现、验证、发布分阶段推进
-- `kanban-continuous`：连续流动式开发，用 WIP 和集成队列控节奏
-
-如果是多人、多仓或传统工程流程，必须创建或更新 `docs/09-PLANNING/Delivery-SSoT.md`。
-
-### Phase 2c: 模块识别与注册（可选）
-
-当项目满足以下条件时启用：
-
-- Operating Model 为 `solo-orchestrator` 或 `team-feature-lead`
-- 存在 2+ 个可独立演进的功能域
-- 开发者计划多会话 / 多 worktree 并行
-
-读 `references/module-parallel-standard.md`，执行：
-
-1. 识别项目中的独立模块（按功能域划分，不按技术层划分）
-2. 为每个模块声明 write scope，确认无交集
-3. 创建 `docs/09-PLANNING/Module-Registry.md`（使用 `templates/ssot/Module-Registry.md`）
-4. 为每个活跃模块创建 `docs/09-PLANNING/MODULES/<key>/module_plan.md`（使用 `templates/planning/module_plan.md`）
-5. 在 AGENTS.md 中添加模块冷启动指引段落
-6. 启用检查器的模块任务反向索引规则：模块 worker 必须把活跃任务写入 `module_plan.md`，并用 Coordinator Handoff 标记总表同步需求；只有 coordinator pass 或显式 shared lock owner 写 `Module-Registry.md` / Harness Ledger。
-
-如果项目从线性 Phase 模型迁移，还需执行迁移步骤（见 `references/module-parallel-standard.md` 的"从线性 Phase 迁移"段落）。
-
-### Phase 3: 搭建目录结构
-
-读 `references/docs-directory-standard.md`，在项目中创建 docs/ 目录结构。根据诊断结果裁剪不需要的目录。
+### 旧版 Bootstrap 参考
 
-### Phase 4: 生成 AGENTS.md + CLAUDE.md
-
-读 `references/agents-md-pattern.md`，根据项目技术栈和目录结构生成 AGENTS.md。使用 `templates/AGENTS.md.template` 作为起点。
-
-同时生成 `CLAUDE.md`：
-- 优先使用 `templates/CLAUDE.md.template`
-- `CLAUDE.md` 只作为 Claude Code 兼容入口，指向 AGENTS.md
-- 不要在 `CLAUDE.md` 中复制完整规范，避免 AGENTS.md 与 CLAUDE.md 漂移
-
-### Phase 5: 生成 Reference 标准文件
-
-读 `references/docs-directory-standard.md` 中的 reference 文件清单，根据项目需要生成对应的标准文件到 `docs/11-REFERENCE/`。使用 `templates/reference/` 下的模板。
-标准 harness 安装必须包含 `adversarial-review-standard.md` 和
-`review-routing-standard.md`，因为 planned task closeout 默认启用 reviewer routing。
-标准 harness 安装也必须包含 `repo-governance-standard.md` 和 `ci-cd-standard.md`，
-因为 CI/CD、PR policy、branch protection、required checks 和 worktree concurrency 是 base guardrails。
-标准 harness 安装还必须包含 `delivery-operating-model-standard.md`，
-因为 harness 必须先知道自己服务的是哪一种工程组织形态。
-
-### Phase 5b: 初始化 Repository Governance / CI-CD
-
-读 `references/repo-governance-standard.md` 和 `references/ci-cd-standard.md`。
-根据项目技术栈和远端平台定制：
-
-- repo platform profile
-- branch model
-- PR policy
-- required checks
-- branch protection plan
-- CI workflow 或 blocked-with-owner residual
-- worktree concurrency
-
-如果是 GitHub 项目，优先生成或更新 `.github/pull_request_template.md` 和
-`.github/workflows/ci.yml`。如果 agent 没有权限设置 branch protection，必须写 manual setup residual，
-不能把 `designed` 冒充成 `verified`。
-
-### Phase 6: 初始化 Planning Loop
-
-读 `references/planning-loop.md`，在 `docs/09-PLANNING/TASKS/` 下建立任务模板目录。使用 `templates/planning/` 下的任务模板。
-模板目录必须额外包含 `review.md`，用于 reviewer agent / subagent / 自审写入对抗性 review 报告。
-
-### Phase 7: 初始化 Long-Running Task Protocol
-
-读 `references/long-running-task-standard.md`，在 `docs/11-REFERENCE/` 中生成长程任务标准。使用 `templates/reference/long-running-task-standard.md`，并把 `templates/planning/long-running-task-contract.md` 放入任务模板目录。
-
-### Phase 8: 初始化 SSoT
-
-读 `references/ssot-governance.md`，创建 Feature SSoT 和 Regression SSoT。使用 `templates/ssot/` 下的模板。
-
-### Phase 8b: 初始化经验沉淀体系
-
-读 `references/lessons-governance.md`，创建 Lessons SSoT。使用 `templates/ssot/Lessons-SSoT.md` 作为模板。同时在 `docs/01-GOVERNANCE/` 下创建 `lessons/` 和 `_archive/` 目录（含 `.gitkeep`）。
-
-### Phase 8c: 初始化 Harness Ledger
-
-读 `references/harness-ledger.md`，在 `docs/` 根目录创建 `Harness-Ledger.md`。使用 `templates/ledger/Harness-Ledger.md` 作为模板。
-
-### Phase 9: 初始化 Regression 体系
-
-读 `references/regression-system.md` 和 `references/cadence-ledger.md`，根据项目的关键 surface 建立回归 gate 和 cadence 规则。使用 `templates/regression/` 下的模板。
-
-### Phase 10: 初始化 Walkthrough 流程
-
-读 `references/walkthrough-closeout.md`，建立 walkthrough 模板和 Closeout SSoT。
-使用 `templates/walkthrough/` 下的模板。
-
-### Phase 11: 初始化 Worktree 规范
-
-读 `references/worktree-parallel.md`，确认 worktree 命名、分支规范、subagent worker
-handoff 和 coordinator integration 规则，写入 AGENTS.md 或对应 reference 文件。
-
-### Phase 11b: 初始化模块并行启动 Prompt（如启用）
-
-如果项目启用模块并行开发，读 `references/module-parallel-standard.md`，并为每个 active module 创建：
-
-- `docs/09-PLANNING/Module-Registry.md`
-- `docs/09-PLANNING/MODULES/<key>/module_plan.md`
-- `docs/09-PLANNING/MODULES/Session-Prompt-Pack.md` 或 `docs/09-PLANNING/MODULES/<key>/session_prompt.md`
-
-使用 `templates/planning/module_session_prompt.md` 填充每个模块的启动 prompt。Prompt 必须包含 start gate、worktree/branch preflight、Subagent Worker Invariant、write scope、shared coordination、verification、review/Lessons/Closeout 收口。
-
-### Phase 12: 输出 Bootstrap Summary
-
-输出一份 harness bootstrap 总结，包括：
-- 创建了哪些文件
-- 每个文件的用途
-- 建议的首批任务
-- 下一步行动
-- `node scripts/check-harness.mjs <project-root>` 的结果；未通过不得声称 bootstrap complete
+旧 12 阶段 bootstrap 只作为兼容迁移参考，不再放在 Skill 主执行协议里。
+需要理解旧项目结构或把旧任务迁移到 v1.0 时，读取
+`references/legacy-12-phase-bootstrap.md`。
 
 ---
 
@@ -303,7 +234,7 @@ handoff 和 coordinator integration 规则，写入 AGENTS.md 或对应 referenc
 
 harness bootstrap 完成后，项目中至少应存在以下文件：
 
-- [ ] `AGENTS.md`，100-300 行，宪章 + 索引结构
+- [ ] `AGENTS.md`，默认 80-160 行，宪章 + 阅读矩阵，不承载安装教程
 - [ ] `CLAUDE.md`，Claude Code 兼容 shim，指向 `AGENTS.md`（不复制完整规范）
 - [ ] `docs/11-REFERENCE/` 下至少 3 个标准文件
 - [ ] `docs/09-PLANNING/TASKS/_task-template/` 包含 task plan / findings / progress / review 模板
@@ -319,10 +250,10 @@ 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`
+- [ ] `docs/11-REFERENCE/external-source-intake-standard.md`
 - [ ] `docs/11-REFERENCE/harness-ledger-standard.md`
 - [ ] `.github/pull_request_template.md` 或 platform-specific PR template / residual
 - [ ] CI workflow 或 `ci-cd-standard.md` 中的 blocked-with-owner residual
@@ -334,7 +265,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 已输出给用户
 
 ---
@@ -347,77 +277,81 @@ 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 时主动反思共性/反复问题；`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
 
 ---
 
 ## Reference 索引
 
+旧 12 阶段编号只保留在 `references/legacy-12-phase-bootstrap.md`。下面按 v1.0
+能力和任务场景路由，不再使用旧 Phase 编号。
+
 | 模块 | Reference | 何时读取 |
 |------|-----------|---------|
-| 项目诊断 | `references/project-onboarding-audit.md` | Phase 1 |
-| AGENTS.md + CLAUDE.md | `references/agents-md-pattern.md` | Phase 4 |
-| 目录结构 | `references/docs-directory-standard.md` | Phase 3, 5 |
-| Delivery Operating Model | `references/delivery-operating-model-standard.md` | Phase 2b, 5 |
-| Repository Governance | `references/repo-governance-standard.md` | Phase 5b |
-| CI/CD | `references/ci-cd-standard.md` | Phase 5b |
-| Planning Loop | `references/planning-loop.md` | Phase 6 |
-| Long-Running Task | `references/long-running-task-standard.md` | Phase 7 |
-| Adversarial Review | `references/adversarial-review-standard.md` | Phase 5, 6, 7 |
-| Review Routing | `references/review-routing-standard.md` | Phase 5, 6, 7 |
-| SSoT 治理 | `references/ssot-governance.md` | Phase 8 |
-| 经验沉淀 | `references/lessons-governance.md` | Phase 8b |
-| Harness Ledger | `references/harness-ledger.md` | Phase 8c |
-| Regression | `references/regression-system.md` | Phase 9 |
-| Cadence Ledger | `references/cadence-ledger.md` | Phase 9 |
-| Walkthrough | `references/walkthrough-closeout.md` | Phase 10 |
-| Worktree | `references/worktree-parallel.md` | Phase 11 |
+| 项目诊断 | `references/project-onboarding-audit.md` | Diagnose 阶段判断项目形态、风险和 harness 深度 |
+| AGENTS.md + CLAUDE.md | `references/agents-md-pattern.md` | Scaffold / Configure 入口路由文件时 |
+| 目录结构 | `references/docs-directory-standard.md` | Scaffold docs 结构或检查目录边界时 |
+| 外部资料摄取 | `references/external-source-intake-standard.md` | 项目依赖微服务、多仓、外部团队资料或用户提供资料包时 |
+| Delivery Operating Model | `references/delivery-operating-model-standard.md` | Decide 阶段选择 solo / team / split-repo / program / stage-gate / kanban |
+| Repository Governance | `references/repo-governance-standard.md` | 配置 PR、分支、worktree、提交和发布边界时 |
+| CI/CD | `references/ci-cd-standard.md` | 配置或验证 required checks、release gate、CI residual 时 |
+| Planning Loop | `references/planning-loop.md` | 创建、推进或迁移任务计划时 |
+| 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` | 维护 Delivery / Regression 等非任务生命周期事实时 |
+| 经验沉淀 | `references/lessons-governance.md` | walkthrough 收口后判断是否沉淀 lesson 时 |
+| 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 和交付说明时 |
+| Worktree | `references/worktree-parallel.md` | 并行开发、worker handoff 或隔离分支时 |
 
 ## Template 索引
 
 | 模板 | 路径 | 用途 |
 |------|------|------|
-| AGENTS.md | `templates/AGENTS.md.template` | Phase 4 |
-| CLAUDE.md | `templates/CLAUDE.md.template` | Phase 4，Claude Code 兼容 shim |
-| Feature SSoT | `templates/ssot/Feature-SSoT.md` | Phase 8 |
-| Regression SSoT | `templates/ssot/Regression-SSoT.md` | Phase 8 |
-| Lessons SSoT | `templates/ssot/Lessons-SSoT.md` | Phase 8b |
-| Delivery SSoT | `templates/ssot/Delivery-SSoT.md` | Phase 2b |
-| Harness Ledger | `templates/ledger/Harness-Ledger.md` | Phase 8c |
+| AGENTS.md | `templates/AGENTS.md.template` | 目标项目 agent 入口：宪章 + 阅读矩阵 |
+| CLAUDE.md | `templates/CLAUDE.md.template` | Claude Code 兼容 shim，指向 AGENTS.md |
+| Regression SSoT | `templates/ssot/Regression-SSoT.md` | 回归面、证据深度、gate 状态 |
+| Delivery SSoT | `templates/ssot/Delivery-SSoT.md` | 多人、多仓、阶段性交付计划 |
+| 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 收口后 |
-| Cadence Ledger | `templates/regression/Cadence-Ledger.md` | Phase 9 |
-| Task Plan | `templates/planning/task_plan.md` | Phase 6 |
-| Findings | `templates/planning/findings.md` | Phase 6 |
-| Progress | `templates/planning/progress.md` | Phase 6 |
-| Review Report | `templates/planning/review.md` | Phase 6 |
-| Long-Running Task Contract | `templates/planning/long-running-task-contract.md` | Phase 7 |
+| Cadence Ledger | `templates/regression/Cadence-Ledger.md` | 回归触发节奏和批次记录 |
+| Task Plan | `templates/planning/task_plan.md` | 当前任务计划 |
+| Findings | `templates/planning/findings.md` | 发现、风险和 residual |
+| Progress | `templates/planning/progress.md` | 生命周期状态和执行日志 |
+| Review Report | `templates/planning/review.md` | 审查发现、确认和残余风险 |
+| Long-Running Task Contract | `templates/planning/long-running-task-contract.md` | 长程任务授权、review loop 和停止条件 |
 | Module Session Prompt | `templates/planning/module_session_prompt.md` | 模块并行开发会话冷启动 |
-| Walkthrough | `templates/walkthrough/walkthrough-template.md` | Phase 10 |
-| Closeout SSoT | `templates/walkthrough/Closeout-SSoT.md` | Phase 10 |
-| Testing Standard | `templates/reference/testing-standard.md` | Phase 5 |
-| Execution Workflow | `templates/reference/execution-workflow-standard.md` | Phase 5 |
-| Delivery Operating Model Standard | `templates/reference/delivery-operating-model-standard.md` | Phase 2b |
-| Repository Governance Standard | `templates/reference/repo-governance-standard.md` | Phase 5b |
-| CI/CD Standard | `templates/reference/ci-cd-standard.md` | Phase 5b |
-| Long-Running Task Standard | `templates/reference/long-running-task-standard.md` | Phase 7 |
-| Adversarial Review Standard | `templates/reference/adversarial-review-standard.md` | Phase 5 |
-| Review Routing Standard | `templates/reference/review-routing-standard.md` | Phase 5 |
-| Docs Library | `templates/reference/docs-library-standard.md` | Phase 5 |
-| Harness Ledger Standard | `templates/reference/harness-ledger-standard.md` | Phase 5 |
-| Regression Governance | `templates/reference/regression-ssot-governance.md` | Phase 5 |
-| Walkthrough Standard | `templates/reference/walkthrough-standard.md` | Phase 5 |
-| Worktree Standard | `templates/reference/worktree-standard.md` | Phase 5 |
-| Engineering Standard | `templates/reference/engineering-standard.md` | Phase 5 |
+| Walkthrough | `templates/walkthrough/walkthrough-template.md` | 任务收口记录 |
+| Closeout SSoT | `templates/walkthrough/Closeout-SSoT.md` | closed task 索引和收口证据 |
+| Testing Standard | `templates/reference/testing-standard.md` | 测试、冒烟和回归规范 |
+| 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` | 对抗性审查协议 |
+| Review Routing Standard | `templates/reference/review-routing-standard.md` | reviewer / subagent / human review 路由 |
+| Docs Library | `templates/reference/docs-library-standard.md` | 文档结构、命名和归档 |
+| External Source Intake Standard | `templates/reference/external-source-intake-standard.md` | 外部资料摄取、摘要和投影 |
+| Harness Ledger Standard | `templates/reference/harness-ledger-standard.md` | Harness Ledger 写入规范 |
+| Regression Governance | `templates/reference/regression-ssot-governance.md` | Regression SSoT 治理 |
+| Walkthrough Standard | `templates/reference/walkthrough-standard.md` | walkthrough / closeout / lessons 收口规范 |
+| Worktree Standard | `templates/reference/worktree-standard.md` | worktree、分支和 worker handoff |
+| Engineering Standard | `templates/reference/engineering-standard.md` | 工程和架构约束 |

package/docs-release/README.md

@@ -1,7 +1,25 @@
 # Coding Agent Harness Docs Release
 
 This directory is the public-facing documentation library for Coding Agent Harness.
-It is separate from the repository's private self-hosted harness.
+It is separate from maintainer-only operating records for this source repository.
+
+简体中文说明：这个目录只放可公开发布的方法论、架构和使用指南。它不记录本仓库自己的私有任务计划、审查草稿、ledger 或本地运行状态。
+
+## Language Entry / 语言入口
+
+English is the canonical public language for GitHub and npm discovery. Simplified Chinese is fully supported for README, guides, prompts, and executable templates. Other languages currently provide short introductions and route users to the English docs.
+
+英文是 GitHub 和 npm 公开传播的主语言。简体中文保留完整支持，包括 README、指南、prompt 和可执行模板。其他语言目前提供简介入口，并引导用户阅读英文文档。
+
+| Language | Entry | Support |
+| --- | --- | --- |
+| English | [`../README.md`](../README.md), [`intl/en-US.md`](intl/en-US.md) | Full docs and templates |
+| 简体中文 | [`../README.zh-CN.md`](../README.zh-CN.md), [`intl/zh-CN.md`](intl/zh-CN.md) | Full docs and templates |
+| 日本語 | [`intl/ja-JP.md`](intl/ja-JP.md) | Intro only |
+| 한국어 | [`intl/ko-KR.md`](intl/ko-KR.md) | Intro only |
+| Français | [`intl/fr-FR.md`](intl/fr-FR.md) | Intro only |
+| Español | [`intl/es-ES.md`](intl/es-ES.md) | Intro only |
+| Deutsch | [`intl/de-DE.md`](intl/de-DE.md) | Intro only |
 
 ## Boundary
 
@@ -9,22 +27,75 @@ 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 / 如何阅读
+
+Not every document is written for the same reader.
+
+不是所有文档都给同一种读者看。先判断自己是要理解方法、执行迁移，还是给目标项目里的 Agent 建立合同。
+
+| Reader / 读者 | Start here / 从这里开始 | Purpose / 用途 |
+| --- | --- | --- |
+| 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 执行文档和私有运行状态。 |
+
+## Public Docs / 公开文档
+
+### International Intros / 多语言简介
+
+- `intl/README.md` — language support matrix and intro page index. 语言支持矩阵和简介页索引。
+- `intl/en-US.md`, `intl/zh-CN.md`, `intl/ja-JP.md`, `intl/ko-KR.md`, `intl/fr-FR.md`, `intl/es-ES.md`, `intl/de-DE.md` — short public introductions for global discovery. 面向国际传播的短简介入口。
+
+### Architecture / 架构
+
+- `architecture/overview.md` / `architecture/overview.zh-CN.md` — public architecture overview, including the CLI, dashboard, task lifecycle, migration rails, review gate, and release package surface. 公开架构总览，覆盖 CLI、Dashboard、任务生命周期、迁移轨道、审查门禁和发布包表面。
+
+### 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 / 接入与迁移
+
+- `guides/agent-installation.md` / `guides/agent-installation.en-US.md` — operational installation guide for target-project agents. 目标项目 Agent 的安装和运行指南。
+- `guides/migration-playbook.md` / `guides/migration-playbook.en-US.md` — smooth migration guide for existing legacy harness projects. 旧 Harness 项目的平滑迁移指南。
+- `guides/legacy-migration-agent-prompt.md` / `guides/legacy-migration-agent-prompt.zh-CN.md` — prompt contract for agents running baseline or full legacy migration. 给迁移 Agent 使用的执行合同。
+- `guides/full-legacy-migration-subagent-strategy.md` / `guides/full-legacy-migration-subagent-strategy.zh-CN.md` — full readable cutover strategy with subagent roles, adversarial review, and dashboard/CLI proof gates. 完整可读迁移的 subagent 分工、对抗审查和 Dashboard/CLI 证据门禁。
+
+## Repository Operating Models / 仓库运行模式
+
+Coding Agent Harness supports three common repository shapes:
+
+Coding Agent Harness 支持三种常见仓库形态：
+
+| Model / 模式 | Summary / 摘要 | Primary doc / 主文档 |
+| --- | --- | --- |
+| Single-repo Harness 单仓模式 | One code repository owns code, plans, regression, and closeout. 一个代码仓库同时承载代码、计划、回归和收口。 | `guides/repository-operating-models.md` |
+| Independent multi-repo Harness 多仓独立模式 | Each code repository owns its own local Harness; cross-repo context must be documented in architecture, development, and integration docs. 每个代码仓库有自己的局部 Harness，跨仓上下文必须写进 architecture、development、integration 文档。 | `guides/repository-operating-models.md` |
+| Parent-control repository Harness 主控仓库模式 | One parent repository owns the Harness control plane; child repositories own implementation facts. 一个父仓库管理 Harness 控制面，子仓库只承载代码执行事实。 | `guides/parent-control-repository-pattern.md` |
 
-## Current Public Docs
+The parent-control pattern is the recommended default when one product spans many repositories but still needs one release plan, one task source of truth, and one agent startup point.
 
-- `architecture/overview.md` — public architecture overview.
-- `guides/agent-installation.md` — operational installation guide for target-project agents.
+当一个产品跨多个仓库，但仍然需要一个 release 计划、一个任务事实源和一个 Agent 启动入口时，推荐优先采用主控仓库模式。
 
 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.
 
-## Rule
+## Release Rule
 
 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.