coding-agent-harness 1.0.1 → 1.0.4

package/templates-zh-CN/planning/review.md

@@ -13,6 +13,35 @@
 - 范围外：[明确不审查的内容；如无写“无”]
 - 来源材料：[task plan、diff、commit、PR、测试输出、运行证据]
 
+## Agent Review Submission（Agent 提交审查）
+
+本节由 agent 或 coordinator 在审查材料包准备好时填写。它只表示“提交待审”，不表示人工批准。
+
+| Field | Value |
+| --- | --- |
+| Submission ID | [由 task-review 生成] |
+| Submitted At | [timestamp] |
+| Submitted By | [agent 或 coordinator 身份] |
+| Task Key | {{TASK_ID}} |
+| Materials Checklist Hash | [由 task-review 生成；只作信息记录，不作为手工门禁] |
+| Evidence Summary | [测试、diff、运行和审查材料证据] |
+| Open Findings Count | [数字] |
+| Scanner Version | [生成时的 scanner 版本] |
+
+### Material Checklist（材料清单）
+
+| Material | Required? | Status | Evidence |
+| --- | --- | --- | --- |
+| Brief | yes / no | present / missing / incomplete | [路径或原因] |
+| Task plan | yes / no | present / missing / incomplete | [路径或原因] |
+| Progress and evidence | yes / no | present / missing / incomplete | [路径或原因] |
+| Visual map | yes / no | present / missing / incomplete | [路径或原因] |
+| Lesson candidate decision | yes / no | present / missing / incomplete | [路径或原因] |
+| Walkthrough or closeout link | yes / no | present / missing / incomplete | [路径或原因] |
+
+Scanner 会根据必需文件、章节、证据和这个严格提交块派生 `materialsReady`。如果材料未齐，任务应进入缺材料队列，而不是人工审查确认队列。
+如果存在开放的 P0/P1/P2 阻塞发现，任务应进入阻塞队列，而不是人工审查确认队列。
+
 ## 信心挑战（Confidence Challenge）
 
 直接回答：你是否对当前计划、实现和策略有 100% 信心？
@@ -49,19 +78,48 @@
 
 [如果没有重要发现，明确写：本轮已检查上述证据，未发现阻塞目标的重要发现。]
 
+## Human Review Confirmation（人工审查确认）
+
+本节只能由人工 reviewer，或代表明确人工确认的命令 / workbench 动作填写。Agent 提交审查、自查、subagent 审查都不能满足这个门禁。
+
+| Field | Value |
+| --- | --- |
+| Confirmation ID | [由 review-confirm 生成] |
+| Confirmed At | [timestamp] |
+| Reviewer | [人工 reviewer 姓名] |
+| Reviewer Email | [邮箱，如可用] |
+| Task Key | {{TASK_ID}} |
+| Confirm Text | [必须匹配任务 ID 或命令要求的确认短语] |
+| Evidence Checked | [review packet / tests / diff 摘要] |
+| Commit SHA | [由 review-confirm 生成的确认提交 SHA] |
+| Audit Status | committed / blocked |
+
+任务仍属于缺材料、阻塞或 Lessons 路由时，不要填写本节。`review-confirm` 与 Dashboard Workbench 必须在 Git dirty、提交身份缺失、hook 失败，或写入超出当前任务 `review.md` / `progress.md` 白名单时拒绝确认。
+
 ## 残余风险
 
 | Risk | Owner | Accepted? | Follow-up |
 | --- | --- | --- | --- |
 | [风险] | [负责人] | yes / no | [后续路径或“无”] |
 
+## Lifecycle Queue Routing（生命周期队列路由）
+
+| Queue | Applies? | Reason | Exit condition |
+| --- | --- | --- | --- |
+| Review | yes / no | 已提交审查材料包，且可等待人工确认。 | 人工确认或退回。 |
+| Missing Materials | yes / no | 必需文件、章节、证据或 review submission 缺失 / 不完整。 | Agent 补齐材料并重新提交审查。 |
+| Blocked | yes / no | 存在 open blocking finding、非法状态转换、审计失败或需要人工 waiver。 | blocker 被修复、关闭或明确豁免。 |
+| Lessons | yes / no | Lesson candidate 需要拒绝、留在任务内、dry-run promotion 或创建沉淀任务。 | 人工决定候选路由；除非明确批准，promotion 仍是单独维护任务。 |
+| Confirmed / Finalized | yes / no | 已有人工确认；可能仍待结项或治理收口。 | Closeout、ledger 和 lesson routing 都完成。 |
+| Soft-deleted / Superseded | yes / no | 任务有 tombstone、superseded-by、archive、duplicate 或 abandoned 状态。 | reopen 或作为只读审计历史保留。 |
+
 ## 后续路由（Follow-Up Routing）
 
 - 任务计划：[是否需要更新，路径或“无”]
 - Progress：[对应 `progress.md` 条目]
 - 发现记录：[是否需要写入 `findings.md`]
 - Regression SSoT：[新增 / 调整 / 无]
-- Lessons SSoT：[checked-created: L-YYYY-MM-DD-NNN / checked-none: 一句话原因]
+- Lessons：[checked-created: L-YYYY-MM-DD-NNN / checked-candidate: LC-YYYYMMDD-NNN / queued-promotion: LC-YYYYMMDD-NNN / checked-none: 一句话原因]
 - 收口记录：[收口时引用路径]
 
 ## 最终信心依据（Final Confidence Basis）

package/templates-zh-CN/planning/task_plan.md

@@ -1,5 +1,7 @@
 # [任务名称]
 
+Task Contract: harness-task/v1
+
 ## 目标
 
 [用一句话说明本任务完成后应达到的状态。]
@@ -14,11 +16,15 @@
 
 | 预算 | 适用场景 | 必需结构 |
 | --- | --- | --- |
-| simple | 单 owner、无 subagent、证据深度为 L0/L1 | 使用标准任务文件即可 |
-| complex | 需要 L2/L3 证据、subagent/reviewer、外部参考、生成产物，或超过 5 个切片 | 只启用实际需要的可选索引 |
+| simple | 单 owner、无 subagent、证据深度为 L0/L1、不需要正式 review gate | `brief.md`、`task_plan.md`、`visual_map.md`、`progress.md` |
+| standard | 常规功能、修复或文档改动 | `brief.md`、`task_plan.md`、`execution_strategy.md`、`visual_map.md`、`findings.md`、`lesson_candidates.md`、`progress.md`、`review.md` |
+| complex | 需要 L2/L3 证据、subagent/reviewer、外部参考、生成产物，或超过 5 个切片 | standard 文件，并额外创建 `references/INDEX.md` 与 `artifacts/INDEX.md` |
+
+选择预算：{{TASK_BUDGET}}
 
 可选子目录按触发条件创建，不作为默认脚手架：
 
+- `lessons/LC-*.md`：进入 `needs-promotion` 的 lesson candidate 的任务本地详情文件。
 - `references/INDEX.md`：任务本地资料、外部链接、reviewer 输入包、跨仓上下文。
 - `artifacts/INDEX.md`：命令输出、截图、fixture、生成报告、审查记录等证据。
 - `slices/<slice-id>/`：多切片任务。每个切片使用 `brief.md`、`evidence.md`、`review.md`。
@@ -40,13 +46,34 @@
 
 ## 执行与可视化文件
 
-`execution_strategy.md` 和 `visual_roadmap.md` 是本任务的同级合同文件，不嵌入 `task_plan.md`。这样 dashboard 和 checker 可以稳定读取。
-
-| 合同文件 | 是否必需 | 用途 |
-| --- | --- | --- |
-| `execution_strategy.md` | yes | 执行模式、subagent 使用、冲突控制、证据深度、交接规则 |
-| `visual_roadmap.md` | yes | Mermaid 路线图、阶段表、完成度、证据状态、阻塞风险 |
-| `review.md` | 按需 | 对抗性审查、release review、外部 reviewer 结论 |
+不要手工复制本模板来创建任务目录。必须使用 `harness new-task`，让所选预算自动
+创建正确文件集，并让 `harness check` 能按同一契约校验。
+
+`execution_strategy.md` 和 `visual_map.md` 是本任务的同级合同文件，不嵌入 `task_plan.md`。这样 dashboard 和 checker 可以稳定读取。
+
+| 预算 | 必需文件 |
+| --- | --- |
+| simple | `brief.md`、`task_plan.md`、`visual_map.md`、`progress.md` |
+| standard | simple 文件，加 `execution_strategy.md`、`findings.md`、`lesson_candidates.md`、`review.md` |
+| complex | standard 文件，加 `references/INDEX.md`、`artifacts/INDEX.md` |
+| long-running 附加项 | 选择 `--long-running` 时额外创建 `long-running-task-contract.md` |
+
+文件职责：
+
+| 合同文件 | 用途 |
+| --- | --- |
+| `brief.md` | 面向人和下一轮 agent 的任务摘要与上下文包 |
+| `task_plan.md` | 目标、范围、预算、验收与执行决策 |
+| `execution_strategy.md` | 执行模式、subagent 使用、冲突控制、证据深度、交接规则 |
+| `visual_map.md` | 图表集合：阶段图、可选架构/时序/数据流/状态图、完成度、证据状态、阻塞风险 |
+| `progress.md` | 执行日志、决策和交接 |
+| `findings.md` | 发现、研究记录和未解决风险 |
+| `lesson_candidates.md` | 任务本地教训候选队列。人工审查确认前必须接受无候选、拒绝候选，或排队 promotion |
+| `lessons/LC-*.md` | 可选的任务本地 lesson 详情文件，趁源任务上下文还新鲜写出，并由 `Detail Artifact` 链接 |
+| `review.md` | Agent Review Submission、对抗性审查、release review、外部 reviewer 结论 |
+| `references/INDEX.md` | complex 任务的资料包和参考索引 |
+| `artifacts/INDEX.md` | complex 任务的生成证据和产物索引 |
+| `long-running-task-contract.md` | 连续执行权限、循环规则和停止条件 |
 
 旧任务可以保留历史嵌入式段落作为 fallback；新任务必须使用独立文件。
 
@@ -95,10 +122,9 @@
 
 ## 关联
 
-- 功能 SSoT 条目：[引用]
 - 相关 Regression Gate：[引用]
 - 审查报告：[路径 / 不适用]
-- Harness Ledger 条目：[完成时填写 / HL-...]
+- Generated Ledger：由 lifecycle CLI / `harness governance rebuild` 重建
 - 前置任务：[引用；如无写“无”]
 
 ## 模块关联（启用模块并行时填写）

package/templates-zh-CN/planning/{visual_roadmap.md → visual_map.md}

@@ -1,6 +1,14 @@
-# 可视化路线图
+# Visual Map / 可视化图谱
 
-本文件供 HTML dashboard 和人工审查同时使用。Mermaid 图展示阶段关系；阶段表提供可解析的状态、完成度和证据状态。
+Visual Map Contract: v1.0
+
+本文件是任务图表集合，不只是阶段路线图。只有对人或 agent 理解任务有实际帮助的图才放进来。
+
+## 图表索引（Map Index）
+
+| ID | Type | Purpose | Required For Understanding | Source Evidence | Promotion Candidate |
+| --- | --- | --- | --- | --- | --- |
+| MAP-01 | phase | 展示执行阶段和依赖关系 | yes | `task_plan.md` | no |
 
 ## 阶段关系图（Phase Graph）
 
@@ -22,3 +30,14 @@ flowchart LR
 允许的 `Evidence Status`：`missing`, `partial`, `present`, `waived`。
 
 `Completion` 使用 `0..100` 的整数；`done` 应为 `100`，`planned` 应为 `0`，`skipped` 不计入 dashboard 总完成度。dashboard 以阶段表计算进度，不从正文推断。
+
+## 支持性图表（Supporting Maps）
+
+按需添加，不要求每类都存在：
+
+- architecture：模块、组件、服务结构。
+- sequence：前端、后端、服务、数据库、agent 时序。
+- data-flow：数据流转和所有权。
+- state：状态机或生命周期。
+- topology：repo、服务、worker、worktree 拓扑。
+- decision：方案分叉和决策树。

package/templates-zh-CN/reference/adversarial-review-standard.md

@@ -64,7 +64,7 @@ docs/09-PLANNING/TASKS/<YYYY-MM-DD-任务名>/review.md
 - `not-reproducible`
 - `out-of-scope`
 
-`accepted-risk` 必须写明为什么不阻塞本轮目标，并路由到 task、SSoT、Regression SSoT、Lessons SSoT 或后续 PR。
+`accepted-risk` 必须写明为什么不阻塞本轮目标，并路由到 task、SSoT、Regression SSoT、lesson candidates/detail docs 或后续 PR。
 
 ## 无发现结论
 

package/templates-zh-CN/reference/docs-library-standard.md

@@ -9,8 +9,9 @@
 | 位置 | 职责 |
 | --- | --- |
 | `docs/Harness-Ledger.md` | 全局上下文维护总账，记录非平凡任务是否完成计划、审查、回归、Lessons 和收口回写。 |
-| `docs/01-GOVERNANCE/` | Lessons SSoT、经验详情、治理记录、归档。 |
+| `docs/01-GOVERNANCE/` | promoted lesson 详情、治理记录、归档。 |
 | `docs/03-ARCHITECTURE/` | ADR、架构设计、接口决策、关键技术方案。 |
+| `docs/04-DEVELOPMENT/` | 本地开发、代码地图、外部服务开发上下文、mock/stub、跨仓调试。 |
 | `docs/05-TEST-QA/` | Regression SSoT、Cadence Ledger、测试策略和回归证据索引。 |
 | `docs/09-PLANNING/` | Delivery SSoT、Module Registry、任务目录、模块计划。 |
 | `docs/09-PLANNING/TASKS/` | 每个任务一个目录，包含 task plan、progress、findings、review。 |
@@ -18,6 +19,39 @@
 | `docs/11-REFERENCE/` | agent 按需加载的标准文件，控制行为而不是记录流水账。 |
 | `docs/99-TMP/` | 临时材料，定期清理，不作为长期事实来源。 |
 
+## 03 / 04 / 06 路由规则
+
+```text
+03 = 它在系统里是什么
+04 = 我开发当前仓时怎么面对它
+06 = 我和它具体怎么对接
+```
+
+| 目录 | 负责 | 不负责 | 必需 schema 信号 |
+| --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/` | 系统结构、服务职责、owner、service catalog、critical flows、ADR | endpoint payload、mock 指南、任务日志 | `Context Doc Type`, `Source Evidence`, `Last Verified`, `Confidence` |
+| `docs/04-DEVELOPMENT/` | local setup、codebase map、external development context、external source packs、mock/stub、cross-repo debugging | 长期架构事实、API payload 合同、未经摘要的外部资料堆 | `Context Doc Type`, `Development Use`, `Do Not Assume`, `Mocks / Stubs`, `Source Evidence`, `Last Verified`, `Confidence` |
+| `docs/06-INTEGRATIONS/` | API/event/webhook/SDK/third-party contract、auth、payload、errors、contract tests | 全局拓扑、service ownership catalog、调试笔记 | `Context Doc Type`, `Contract Type`, `Auth`, `Payload`, `Errors`, `Contract Tests`, `Source Evidence`, `Last Verified`, `Confidence` |
+
+具体分工：
+
+- `03-ARCHITECTURE/service-catalog.md` 只写服务摘要和链接。
+- `06-INTEGRATIONS/<service>-api-contract.md` 才写 payload、auth、errors、contract tests。
+- `04-DEVELOPMENT/external-context/<service>.md` 写 mock/stub、不安全假设和调试说明。
+- `04-DEVELOPMENT/external-source-packs/` 只写外部资料索引、digest 和投影状态；最终事实必须回写到 `03/04/06`。
+
+## 外部资料摄取规则
+
+如果目标项目属于微服务、多仓、前后端分仓或依赖外部团队文档，Agent 在 Diagnose / Decide 阶段必须询问用户是否有外部资料。资料少时直接作为 `Source Evidence` 链接；资料多时按 `external-source-intake-standard.md` 创建 source pack。
+
+外部资料处理顺序固定为：
+
+```text
+Inventory -> Classify -> Sanitize -> Digest -> Project -> Verify -> Residual
+```
+
+未经 digest 和 projection 的原始资料不能直接作为执行事实。
+
 ## 命名规则
 
 - 目录可使用编号前缀，例如 `09-PLANNING`、`11-REFERENCE`。
@@ -57,3 +91,4 @@
 3. 证据用路径、命令、日志、截图、PR、CI run 引用，不依赖聊天记录。
 4. 表格用于状态和路由；段落用于解释判断和边界。
 5. 更新 reference 或 template 时，必须在 Harness Ledger 记录本次上下文维护。
+6. `03/04/06` 文档必须使用 schema 信号，发现内容错位时迁移到正确目录。

package/templates-zh-CN/reference/execution-workflow-standard.md

@@ -27,7 +27,8 @@
 5. 可写 worker 必须在自己的 worktree 内实现、验证、提交，并 handoff branch、commit SHA、checks、residual。
 6. 遇到共享文件冲突，由 coordinator 或人工决定串行顺序。
 7. 遇到目标失效、权限阻塞、高风险决策或 stop condition 不适用，立即暂停并记录。
-8. 有意义地提交中间成果；commit message 应说明变更类型和范围。
+8. 主动提交已验证的、有意义的中间成果；commit message 应说明变更类型和范围。除非用户明确要求暂不提交、检查失败、dirty 归属不清，或安全边界阻止干净提交，否则不要把已完成切片长期留在未提交状态；延期提交必须写明 no-commit reason、owner 和下一步。
+9. 机械化 Harness 写入优先使用 CLI lifecycle 命令。CLI-owned 写入会加锁、限制 allowlist 并自动提交，也会拒绝 dirty Git 状态；agent-owned 手工编辑仍需要明确任务提交或延期提交理由。
 
 ## 完成任务后
 
@@ -38,7 +39,7 @@
 5. 确认 `review.md` 没有 open P0/P1 finding；material P2 已修复或写为 `accepted-risk` 并路由。
 6. planned task 必须完成 closeout review，或写明 `skipped-with-reason`。
 7. 写 walkthrough，引用 task plan、review、证据、residual、Regression SSoT 和 commit。
-8. 执行 Lessons 检查：有可复用经验则写 lesson 详情并更新 Lessons SSoT；没有也记录 `checked-none: <reason>`。
+8. 执行 Lessons 检查：新任务默认先写 `lesson_candidates.md` 并交给人工审查；人工标记后可记录 `queued-promotion`，再由维护命令写 promoted lesson 详情文档。没有可复用候选时记录 `no-candidate-accepted`；旧任务兼容可记录 `checked-none: <reason>`。
 9. 最后更新 Harness Ledger，因为它记录本轮上下文维护的最终状态。
 10. 完成 commit / PR / release note，并确认本任务工作区没有未解释的遗留改动。
 11. 如使用 worker，coordinator 集成 worker commit 后运行最终 gates，并记录 integration evidence。
@@ -71,6 +72,13 @@ PR 描述必须包含：
 - residual、owner 和不阻塞理由。
 - required checks、reviewer、merge method 是否满足 `repo-governance-standard.md`。
 
+## 主动提交规则
+
+- 每个已验证的、有意义的切片默认都要提交。
+- 提交前只 stage 本任务范围内文件，不能顺手带入无关 dirty 文件、私有文件或生成产物。
+- 如果用户明确说不要提交、检查失败、或 dirty 归属还没厘清，必须把 no-commit reason、owner 和下一步写入 `progress.md` 或交接说明。
+- closeout 时必须列出相关 commit SHA；如果没有 commit，必须说明为什么这是安全的例外。
+
 ## 禁止事项
 
 - 非平凡任务跳过 task plan 直接实现。

package/templates-zh-CN/reference/external-source-intake-standard.md

@@ -0,0 +1,82 @@
+# 外部资料摄取标准
+
+## 职责
+
+本标准定义 Agent 如何接收、过滤、整理外部项目或微服务团队提供的大量文档。目标是把外部资料变成可执行上下文，而不是把资料堆进 `03/04/06`。
+
+## 核心模型
+
+```text
+外部原始资料 -> source pack 索引 -> digest 摘要 -> 03/04/06 执行投影
+```
+
+`03-ARCHITECTURE`、`04-DEVELOPMENT`、`06-INTEGRATIONS` 只保存已经提炼并可用于执行的事实。外部团队丢来的原文、长文档、截图、聊天记录、导出包和历史资料先进入 `docs/04-DEVELOPMENT/external-source-packs/`，不能直接污染执行文档。
+
+## 何时询问用户
+
+在 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>/` |
+| 资料含敏感信息、密钥、客户数据或不能进仓 | 不复制原文；在 source pack README 记录外部路径、owner、访问条件和摘要 |
+| 资料是可公开或可入仓的原始文档 | 可放 `raw/`，但仍要经过 digest 后才能投影到执行文档 |
+
+建议结构：
+
+```text
+docs/04-DEVELOPMENT/external-source-packs/<source-key>/
+├── README.md              # 资料索引和投影状态
+├── digests/               # 每份或每组资料的摘要
+├── raw/                   # 可入仓原文；禁止放密钥、隐私或客户数据
+└── raw-index.md           # 原文不能入仓时，用路径/URL/owner 索引替代 raw/
+```
+
+不要为每个微服务复制一套完整 `03/04/06` 目录。source pack 是资料入口；稳定执行入口仍然是：
+
+- `docs/03-ARCHITECTURE/service-catalog.md`
+- `docs/03-ARCHITECTURE/services/<service-key>.md`
+- `docs/04-DEVELOPMENT/external-context/<service-key>.md`
+- `docs/06-INTEGRATIONS/<contract>.md`
+
+## 摄取流程
+
+1. **Inventory**：列出所有外部资料，记录来源、owner、时间、可信度、是否可入仓。
+2. **Classify**：按 architecture、development、integration、security、operations、product、unknown 分类。
+3. **Sanitize**：检查密钥、token、客户数据、隐私、内部账号、不可公开链接；不能入仓的只存引用。
+4. **Digest**：用 digest 模板提炼事实、疑问、不安全假设和证据。
+5. **Project**：把稳定事实投影到 `03/04/06`，并在 source pack README 标记 projected。
+6. **Verify**：能用代码、接口测试、owner 确认或运行证据验证的，更新 `Last Verified` 和 `Confidence`。
+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` 根目录。
+- 不要把外部资料摘要当成已验证事实；必须记录 `Source Evidence`、`Last Verified` 和 `Confidence`。
+- 不要在执行文档里保留大段原文、聊天流水或历史会议记录。
+- 不要把密钥、真实 token、客户数据、个人隐私或不可公开资料提交进仓。
+- 不要为了“完整”而给每个微服务复制一套目录树；只给资料量大的外部来源建 source pack。

package/templates-zh-CN/reference/harness-ledger-standard.md

@@ -8,7 +8,7 @@ Harness Ledger 是 `docs/` 骨架的全局上下文维护总账，固定位置
 docs/Harness-Ledger.md
 ```
 
-它记录每个非平凡任务是否完成了 task plan、progress、review、功能 SSoT、Delivery SSoT、Regression SSoT、Lessons SSoT、walkthrough、Closeout SSoT、reference/template 和 CI/CD 治理回写。它不复制业务事实，只记录上下文维护是否合规。
+它记录每个非平凡任务是否完成了 task plan、progress、review、功能 SSoT、Delivery SSoT、Regression SSoT、lesson candidates/detail docs、walkthrough、Closeout SSoT、reference/template 和 CI/CD 治理回写。它不复制业务事实，只记录上下文维护是否合规。
 
 ## 必须更新的场景
 
@@ -17,7 +17,7 @@ docs/Harness-Ledger.md
 - 新增或修改 AGENTS.md、CLAUDE.md、reference、template、checker 或 dashboard。
 - coordinator pass 汇总模块任务、worker handoff、review、closeout 或 regression 结果。
 - 创建或更新 required review。
-- 修改功能 SSoT、Delivery SSoT、Regression SSoT、Lessons SSoT、Closeout SSoT 任一文件。
+- 修改功能 SSoT、Delivery SSoT、Regression SSoT、lesson detail docs、Closeout SSoT 任一文件。
 - 创建 walkthrough 或接受受控跳过。
 - Lessons approved 后合入正式 reference。
 
@@ -37,7 +37,8 @@ docs/Harness-Ledger.md
 4. 状态值使用固定词，避免自由文本失控。
 5. 任务收口时最后更新 Harness Ledger。
 6. `closed` 行必须有 Lessons 检查结果。
-7. `checked-created` 必须引用 lesson ID 和详情文档。
+7. 新任务默认引用 `lesson_candidates.md`，并使用 `checked-candidate`、`queued-promotion` 或 `checked-created` 记录人工判定。
+8. `checked-created` 必须引用 lesson ID 和详情文档。
 8. 如果 closeout、review 或 regression 被跳过，必须写 `skipped-with-reason`。
 
 ## 固定状态词
@@ -46,6 +47,8 @@ docs/Harness-Ledger.md
 - `updated`
 - `created`
 - `checked-none`
+- `checked-candidate`
+- `queued-promotion`
 - `checked-created`
 - `n/a`
 - `skipped-with-reason`
@@ -66,7 +69,7 @@ docs/Harness-Ledger.md
 - [ ] Regression SSoT / Cadence Ledger 已更新，或标记 `n/a`。
 - [ ] walkthrough 已创建，或 Closeout SSoT 写明受控跳过原因。
 - [ ] walkthrough 包含 Lessons 反思。
-- [ ] Lessons 检查结果为 `checked-none: <reason>` 或 `checked-created: L-YYYY-MM-DD-NNN`。
+- [ ] Lessons 检查结果为 `checked-candidate: LC-...`、`queued-promotion: LC-...`、`checked-created: L-YYYY-MM-DD-NNN`，或旧任务兼容的 `checked-none: <reason>`。
 - [ ] Harness Ledger 行已收口，或 residual 已写明 owner 和后续路径。
 
 ## 框架更新检查清单

package/templates-zh-CN/reference/pull-request-standard.md

@@ -0,0 +1,106 @@
+# PR 提交标准
+
+## 职责
+
+每个非平凡 PR 都必须让 maintainer 在不阅读完整 agent 对话的情况下完成审查。PR body 是审查交接包：说明改了什么、为什么改、如何验证、影响哪个版本、还剩什么风险。
+
+## 必需结构
+
+如果仓库面向中英文用户，或本次任务讨论是中文，PR 必须中英双语。公开 GitHub 读者优先读英文，所以英文在前，简体中文在后。
+
+PR body 必须包含：
+
+1. Summary / 摘要
+2. What Changed / 改动内容
+3. Version Impact / 版本影响
+4. Verification / 验证
+5. Review Evidence / 审查证据
+6. Residual Risk / 残余风险
+7. References / 关联材料
+
+## 内容规则
+
+- 必须明确目标版本。如果 `package.json` 从 `1.0.2` 变为 `1.0.3`，就在版本影响里写清楚。
+- 改动内容按用户可见面或模块总结，不要只堆文件路径。
+- 验证必须列真实命令、浏览器检查、CI run 或证据产物。没有跑的检查必须说明原因。
+- 审查证据必须说明自查、subagent 审查、人工审查或代码质量审查状态。release-blocking finding 必须在 merge 前关闭或路由。
+- 残余风险必须区分已接受风险、延期 follow-up、无关本地或私有债务。
+- 关联材料必须链接相关 task doc、SSoT 行、review 文件、commit、issue 或 PR。
+
+## 模板
+
+```markdown
+## Summary
+
+[One or two sentences explaining the intent and outcome.]
+
+## What Changed
+
+- [User-facing or module-level change.]
+- [Governance, CLI, dashboard, docs, or template change.]
+
+## Version Impact
+
+- Package version: `[old]` -> `[new]`
+- Release notes: [CHANGELOG entry or reason no release note is needed]
+
+## Verification
+
+- `[command]`: pass
+- `[browser/runtime/CI evidence]`: pass
+- Not run: [reason]
+
+## Review Evidence
+
+- Self-review: [summary]
+- Additional review: [reviewer/subagent/human result]
+- Blocking findings: [none / closed / routed]
+
+## Residual Risk
+
+- [none / accepted / deferred / unrelated debt]
+
+## References
+
+- Task: [path or issue]
+- Review: [path or PR review]
+- Evidence: [path, commit, screenshot, workflow, or dashboard]
+
+---
+
+## 摘要
+
+[用一两句话说明目标和结果。]
+
+## 改动内容
+
+- [面向用户或模块级改动。]
+- [治理、CLI、Dashboard、文档或模板改动。]
+
+## 版本影响
+
+- 包版本：`[旧版本]` -> `[新版本]`
+- 发布说明：[CHANGELOG 条目或无需发布说明的原因]
+
+## 验证
+
+- `[命令]`：通过
+- `[浏览器 / 运行时 / CI 证据]`：通过
+- 未运行：[原因]
+
+## 审查证据
+
+- 自查：[摘要]
+- 额外审查：[reviewer / subagent / human 结果]
+- 阻塞发现：[无 / 已关闭 / 已路由]
+
+## 残余风险
+
+- [无 / 已接受 / 已延期 / 无关债务]
+
+## 关联材料
+
+- 任务：[路径或 issue]
+- 审查：[路径或 PR review]
+- 证据：[路径、commit、截图、workflow 或 dashboard]
+```

package/templates-zh-CN/reference/repo-governance-standard.md

@@ -33,7 +33,7 @@
 | --- | --- |
 | 是否必须 PR | yes / no / local-only |
 | PR 标题格式 | 通常与 commit 规范一致 |
-| PR 描述要求 | 改动、原因、验证、residual、关联 task / SSoT / review |
+| PR 描述要求 | 遵守 `docs/11-REFERENCE/pull-request-standard.md`；写清改动、原因、版本影响、验证、residual、关联 task / SSoT / review |
 | 必需审查者 | reviewer、外部 agent、人类 owner 或代码 owner |
 | 必需审查类型 | self-review、subagent review、human review、security review |
 | merge method | merge commit、squash、rebase、fast-forward |
@@ -73,6 +73,7 @@
 | branch 命名 | 分支模式 |
 | owner 规则 | 谁创建、谁清理、谁集成 |
 | subagent worker 规则 | 每个可写 worker 使用独立 worktree / branch，并 handoff commit SHA |
+| 主动提交规则 | 已验证的、有意义的切片默认主动提交；暂不提交必须写明 no-commit reason、owner 和下一步 |
 | merge 顺序 | coordinator 或 release owner 决定 |
 | 清理规则 | merge 后删除，保留需写原因 |
 
@@ -81,4 +82,6 @@
 - 非平凡任务的 PR 或 walkthrough 必须说明 required checks 的执行结果。
 - branch protection 未 verified 时，不能声称仓库已受保护；只能写 `designed`、`implemented` 或 `blocked-with-owner`。
 - worker 结果只能通过 commit / branch 集成，不能混入 coordinator 未提交改动。
+- coordinator 自己执行时也要主动提交已验证切片；未提交状态必须有 no-commit reason、owner 和下一步。
+- 不得把无关 dirty 改动混入任务提交；CLI-owned Harness 写入应优先用本地 Harness 命令，让加锁、allowlist 和自动提交保护共享治理文件。
 - repo governance 变化必须同步 CI/CD 标准、worktree 标准和 Harness Ledger。

package/templates-zh-CN/reference/review-routing-standard.md

@@ -28,14 +28,21 @@
 
 ## 可写执行者与只读审查者的区别
 
+任务开始时，先读取当前任务 `execution_strategy.md` 的 Subagent Authorization 和 Subagent Delegation Decision，并向用户说明当前授权状态和分工判断。用户不需要知道或主动要求 subagent；coordinator 必须从用户目标主动评估。
+
 审查路由默认把 subagent 当只读 reviewer。只要 subagent 被要求直接改代码、测试、产品文档或 harness 文档，它就不再是 reviewer，而是 worker。
+Reviewer subagent 在单个任务内默认允许，可重复用于只读审查。
 
-Worker 必须走 `worktree-standard.md`：
+Worker 必须走 `worktree-standard.md`，并先在 `execution_strategy.md` 记录一次用户授权：
 
 - coordinator 先分配独立 worktree / branch、任务目录和 write scope。
 - worker 在自己的 worktree 内实现、验证并提交。
 - worker handoff 写明 branch、commit SHA、checks、residual。
 - coordinator 负责 merge、冲突处理、最终 gates 和 integration evidence。
+- 同一任务、同一范围、同一 worktree/branch 内可复用该授权；范围变化时重新请求授权。
+- 如果 worker subagent 对任务有明显帮助但尚未授权，coordinator 必须用白话主动向用户申请一次授权；可以直接说 worker subagent，但不要等用户知道或提醒使用 subagent。
+- 如果独立切片已经明显但精确文件路径还不清楚，先确认文件路径，然后在 implementation 前立刻申请独立执行助手授权。
+- 一旦 `Would a worker subagent materially help?` 的决策是 `ask-user`，必须暂停 implementation，直到 `User Authorization Decision` 记录 `authorized`、`denied` 或 `not-needed`。
 
 禁止把多个 worker 的未提交改动混在 coordinator 当前 checkout，再由 coordinator 一次性提交。
 

package/templates-zh-CN/reference/walkthrough-standard.md

@@ -55,7 +55,7 @@ docs/10-WALKTHROUGH/Closeout-SSoT.md
 Closeout SSoT 中：
 
 - walkthrough 列写实际路径，或写受控跳过原因。
-- Lessons 检查列写 `checked-created: L-YYYY-MM-DD-NNN` 或 `checked-none: <reason>`。
+- Lessons 检查列写 `checked-candidate: LC-...`、`queued-promotion: LC-...`、`checked-created: L-YYYY-MM-DD-NNN`，或旧任务兼容的 `checked-none: <reason>`。
 - 允许的跳过原因只有：`docs-only`、`no-runtime`、`superseded`、`historical-backfill`、`owner-deferred`。
 
 ## 经验沉淀反思规则
@@ -68,14 +68,15 @@ Closeout SSoT 中：
 
 任一答案为“有”时：
 
-- 先在 `docs/01-GOVERNANCE/lessons/` 写 lesson 详情文档。
-- 再在 Lessons SSoT 追加一行。
-- Lessons SSoT 的详情文档列必须指向该详情文档。
+- 先在任务目录 `lesson_candidates.md` 写候选。
+- 候选进入 `needs-promotion` 时，同步写任务本地 `lessons/LC-*.md` 详情文件，并在 `Detail Artifact` 链接。
+- 人工审查后，如需沉淀，再由维护命令写 promoted lesson 详情文档。
+- `checked-created:<L-ID>` 必须能追溯到该详情文档。
 
 三个答案都为“没有”时，Closeout SSoT 和 Harness Ledger 仍要记录：
 
 ```text
-checked-none: <reason>
+lesson_candidates.md: no-candidate-accepted
 ```
 
 ## 收口要求

package/templates-zh-CN/walkthrough/Closeout-SSoT.md

@@ -38,5 +38,5 @@
 2. 实现类任务应写 walkthrough；跳过原因只用于受限场景，不用于省略收口。
 3. `证据` 必须列出实际检查、冒烟、review、运行时验证或发布证据。
 4. `残余路由` 必须写 `none`，或指向负责人、任务、Regression SSoT、Harness Ledger、issue 或接受风险记录。
-5. `Lessons 检查` 只能写 `checked-created: L-YYYY-MM-DD-NNN` 或 `checked-none: [原因]`。
-6. `checked-created` 必须同时存在 Lessons SSoT 行和 lesson 详情文档。
+5. `Lessons 检查` 只能写 `checked-candidate: LC-...`、`queued-promotion: LC-...`、`checked-created: L-YYYY-MM-DD-NNN`，或旧任务兼容的 `checked-none: [原因]`。
+6. `checked-created` 必须存在 promoted lesson 详情文档；`queued-promotion` 必须能追溯到任务目录 `lesson_candidates.md`。

package/templates-zh-CN/walkthrough/walkthrough-template.md

@@ -46,8 +46,8 @@
 | 本轮是否暴露 reference、workflow、模板或 checker 的缺口？ | [有 / 无，写一句理由] |
 | 是否出现跨模块、跨阶段、跨 agent 的重复问题？ | [有 / 无，写一句理由] |
 | 下次 agent 是否可能在同类任务中重复踩坑？ | [有 / 无，写一句理由] |
-| Lessons 结果 | `checked-created: L-YYYY-MM-DD-NNN` / `checked-none: [一句话原因]` |
-| Lessons 详情文档 | `docs/01-GOVERNANCE/lessons/[file].md` / `none` |
+| Lessons 结果 | `checked-candidate: LC-...` / `queued-promotion: LC-...` / `checked-created: L-YYYY-MM-DD-NNN` / 旧任务 `checked-none: [一句话原因]` |
+| Lessons 详情文档 | `lesson_candidates.md` / `docs/01-GOVERNANCE/lessons/[file].md` / `none` |
 
 ## 关联索引