coding-agent-harness 1.0.2 → 1.0.5

package/references/pull-request-standard.md

@@ -0,0 +1,118 @@
+# Pull Request Standard
+
+## Purpose
+
+Every non-trivial PR must be reviewable without reading the full agent
+conversation. The PR body is a handoff packet for maintainers: what changed,
+why it changed, how it was verified, which version is affected, and what risks
+remain.
+
+## Required Shape
+
+Use a bilingual PR body when the repository has Chinese and English users or
+the task discussion is Chinese. English comes first for public GitHub readers,
+then Simplified Chinese.
+
+The PR body must include:
+
+1. Summary / 摘要
+2. What Changed / 改动内容
+3. Version Impact / 版本影响
+4. Verification / 验证
+5. Review Evidence / 审查证据
+6. Residual Risk / 残余风险
+7. References / 关联材料
+
+## Content Rules
+
+- State the target version explicitly. If `package.json` changes from `1.0.3`
+  to `1.0.4`, say so in Version Impact.
+- List changed surfaces by user-visible area or module, not by dumping every
+  file path.
+- Verification must name the real commands, browser checks, CI runs, or
+  evidence artifacts. If a check was not run, say why.
+- Review Evidence must mention self-review, subagent review, human review, or
+  code-quality review status. Release-blocking findings must be closed or
+  routed before merge.
+- Residual Risk must distinguish accepted risk, deferred follow-up, and
+  unrelated local/private debt.
+- References must link relevant task docs, SSoT rows, review files, commits,
+  issues, or PRs.
+
+## Template
+
+```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/references/repo-governance-standard.md

@@ -46,7 +46,9 @@ docs/11-REFERENCE/ci-cd-standard.md
 
 - PR required before merge: [yes / no]
 - PR title format
-- PR body requirements
+- PR body requirements. Use `docs/11-REFERENCE/pull-request-standard.md` for
+  the required bilingual structure, version impact, verification, review
+  evidence, residual risk, and references.
 - Required reviewers
 - Required review type: [self / subagent / external / human]
 - Merge method: [squash / merge commit / rebase]
@@ -91,7 +93,7 @@ Required fields:
 - Branch pattern
 - Ownership rule
 - Subagent worker rule: each code-changing worker uses its own worktree / branch and hands off a commit SHA
-- Checkpoint commit rule: verified, meaningful slices are committed proactively; deferred commits require an explicit reason
+- Checkpoint commit rule: verified, meaningful slices are committed proactively; deferred commits require an explicit no-commit reason, owner, and next step
 - Merge ordering rule
 - Cleanup rule
 
@@ -131,3 +133,10 @@ Bootstrap is not complete unless repository governance is at least:
 - Worktree concurrency: `implemented`
 - Harness checker: passing or blocked-with-owner with explicit residual
 - Checkpoint commit rule: `implemented`
+- Dirty-state visibility: `implemented` means status/dashboard/checker expose dirty paths that can block CLI-owned auto-commit; unresolved dirty state must have an owner or no-commit reason
+
+## Related Standards
+
+- `docs/11-REFERENCE/pull-request-standard.md` — PR body structure, bilingual
+  requirements, version impact, verification, review evidence, residual risk,
+  and references.

package/references/review-routing-standard.md

@@ -38,16 +38,22 @@
 
 ## Subagent Worker Routing
 
+任务开始时，先读取当前任务 `execution_strategy.md` 的 Subagent Authorization 和 Subagent Delegation Decision，并向用户说明当前授权状态和分工判断。用户不需要知道或主动要求 subagent；coordinator 必须从用户目标主动评估。
+
 本标准默认把 subagent 当 reviewer：只读审查、写 `review.md`、报告 material findings。
+Reviewer subagent 在单个任务内默认允许，可重复用于只读审查。
 
 如果 subagent 被要求直接改代码、测试、产品文档或 harness 文档，它就不是 reviewer，
 而是 worker。Worker 必须按 `worktree-parallel.md` / 项目级 `worktree-standard.md`
-执行：
+执行，并先在 `execution_strategy.md` 记录一次用户授权：
 
 - coordinator 先分配独立 worktree / branch、任务目录和 write scope
 - worker 只在自己的 worktree 内实现、验证并提交
 - handoff 必须包含 worktree path、branch、commit SHA、checks、residual risks
 - coordinator 负责 merge / conflict resolution / final gates
+- 同一任务、同一范围、同一 worktree/branch 内可复用该授权；范围变化时重新请求授权
+- 如果 worker subagent 对任务有明显帮助但尚未授权，coordinator 必须用白话主动向用户申请一次授权；可以直接说 worker subagent，但不要等用户知道或提醒使用 subagent
+- 如果独立切片已经明显但精确文件路径还不清楚，先确认文件路径，然后在 implementation 前立刻申请独立执行助手授权
 
 禁止把多个 worker 的未提交改动混在 coordinator 当前 checkout，再由 coordinator 一次性提交。
 

package/references/ssot-governance.md

@@ -2,11 +2,9 @@
 
 ## 核心思路
 
-SSoT（Single Source of Truth，单一事实源）是长程项目的命脉。没有 SSoT，agent 和人都会在多个版本的"真相"之间迷失。
+SSoT（Single Source of Truth，单一事实源）保存当前事实。任务生命周期状态现在由任务本地文件承载，并由 Harness CLI 生成 `docs/Harness-Ledger.md`，避免 Agent 或人手写多张重复进度表。
 
-## 四张 SSoT + 一张 Ledger
-
-长程项目需要四张 SSoT 保存当前事实，再用一张全局 Harness Ledger 记录每轮任务是否按 SOP 维护这些事实。
+## 当前治理表
 
 ### Delivery SSoT（交付排期表）
 
@@ -16,15 +14,6 @@ SSoT（Single Source of Truth，单一事实源）是长程项目的命脉。没
 - 职责：谁负责哪个 feature block、agent 能看哪些上下文、依赖和 merge 顺序是什么
 - 规则：多人、多仓、split-repo、program、waterfall 或 kanban 团队流程必须维护
 
-### Feature SSoT（实施排期表）
-
-管理 feature / wave / implementation 的进度和 residual。
-
-- 文件：`docs/09-PLANNING/Feature-SSoT.md`（按你的项目命名）
-- 职责：哪些 feature 在做、做到哪了、还剩什么
-- 规则：开始任何非平凡任务前先读，完成后必须回写
-- 归档：Active 表只保留未完成或仍需操作的 feature；completed / superseded 历史行超过 20 条、release 收束、或启用模块并行切换时，必须移入 `docs/09-PLANNING/_archive/` 的 Feature SSoT 归档文件
-
 ### Regression SSoT（回归控制塔）
 
 管理所有 regression surface 的状态、证据深度和残项。
@@ -33,79 +22,98 @@ SSoT（Single Source of Truth，单一事实源）是长程项目的命脉。没
 - 职责：哪些回归面存在、每条的标准入口、当前证据深度、residual
 - 规则：新增固定 gate 或 evidence depth 变化时必须更新
 
-### Lessons SSoT（经验沉淀）
+### Cadence Ledger（周期验证表）
+
+管理需要周期性复查的回归、release、migration 或环境检查。
+
+- 文件：`docs/05-TEST-QA/Cadence-Ledger.md`
+- 职责：哪些检查需要按节奏重跑、最近一次证据是什么、下一次应该何时触发
+- 规则：新增或改变周期性 gate 时必须更新
+
+### Module Registry（模块登记表）
+
+管理模块边界、owner、worktree 和写入范围。
+
+- 文件：`docs/09-PLANNING/Module-Registry.md`
+- 职责：模块 key、路径范围、负责人、状态、worktree、模块计划和依赖
+- 规则：启用模块并行时必须维护；模块内步骤进度由 module plan / module visual map 的生成索引表达
+
+### Closeout SSoT（收口表）
+
+管理任务是否有 walkthrough、Lessons Check 和受控 skip reason。
+
+- 文件：`docs/10-WALKTHROUGH/Closeout-SSoT.md`
+- 职责：任务收口状态、walkthrough 路径、lesson 结果和 residual
+- 规则：非平凡任务完成或关闭时必须维护
+
+### Lessons Governance（经验沉淀）
 
 管理 Agent 在开发过程中发现的经验、改进建议和规范演进。
 
-- 文件：`docs/01-GOVERNANCE/Lessons-SSoT.md`
-- 职责：哪些经验值得沉淀、当前审批状态、冲突关系
-- 规则：Walkthrough 收口后检查是否有沉淀建议；写之前必须完整读 SSoT
+- 文件：任务本地 `lesson_candidates.md` 与 `docs/01-GOVERNANCE/lessons/*.md`
+- 职责：哪些经验值得沉淀、人工如何判定、哪些 lesson 已提升为详情文档
+- 规则：Walkthrough 收口后检查是否有沉淀建议；promotion 前必须查重 candidate 和 detail doc
 - 详细治理规范：`references/lessons-governance.md`
 
-### Harness Ledger（全局上下文回写总账）
+### Harness Ledger（生成的任务生命周期总账）
 
-管理每个非平凡任务对 harness 文档骨架的回写情况。
+管理任务生命周期的可扫描汇总。
 
 - 文件：`docs/Harness-Ledger.md`
-- 职责：本轮任务是否回写 task plan、Feature SSoT、Regression SSoT、walkthrough、Lessons SSoT 和 reference/template
-- 规则：任务收口时最后更新；只记录任务级 compliance，不记录逐行 diff
+- 职责：从任务本地事实生成 scope、module、task、state、queues、plan、review、lesson、closeout、residual
+- 规则：由 Harness CLI 生成；不要手写任务生命周期行
 - 详细规范：`references/harness-ledger.md`
 
-### 分工规则
+## Legacy 生命周期表
 
-- Feature SSoT 不替代 Regression SSoT
-- Delivery SSoT 不替代 Feature SSoT；它管交付组织和集成顺序，不管功能细节
-- Regression SSoT 也不替代 Feature SSoT
-- Lessons SSoT 不替代前两者，它管的是规范本身的演进
-- Harness Ledger 不替代任何 SSoT，它只记录本轮任务是否维护了对应事实
-- 四张 SSoT 和 Harness Ledger 必须各司其职，不能彼此吞并
+`Feature-SSoT.md` 和 `Private-Feature-SSoT.md` 是旧版任务生命周期投影。当前版本不再创建或重建这些表；迁移旧项目时先归档，再用 `harness governance rebuild --archive --apply` 生成新的 Harness Ledger。
 
-### Module Registry 与 Feature SSoT 的分工
+## 分工规则
 
-当项目启用模块并行开发（见 `references/module-parallel-standard.md`）时：
-
-- **Module Registry + module_plan.md** 追踪模块内步骤进度（替代 Feature SSoT 对模块工作的追踪）
-- **Feature SSoT** 只追踪：
-  - 不属于任何模块的独立功能
-  - 发布级汇总（哪个 release 包含了哪些模块步骤）
+- Delivery SSoT 不替代 Regression SSoT；它管交付组织和集成顺序。
+- Regression SSoT 不替代 Closeout SSoT；它管验证面和证据深度。
+- Closeout SSoT 不替代 task-local `lesson_candidates.md`；它只记录收口状态。
+- Module Registry 不替代 module plan；它登记模块边界和 owner。
+- Harness Ledger 不替代上述治理表；它只生成任务生命周期索引。
+- 任务生命周期状态不要同时维护在旧 Feature 表和新 Ledger 中。
 
-**禁止**：同一个工作项同时出现在 module_plan 和 Feature SSoT 中。这会造成真相分裂。
+## 模块并行分工
 
-模块并行切换后，Feature SSoT 的 Active 表必须变小：
-
-- Active 表只保留不属于任何模块、且仍未完成的独立功能。
-- Phase 历史、completed feature 明细、旧 task 路径明细移入 `docs/09-PLANNING/_archive/`。
-- Feature SSoT 主文件只保留冻结边界、当前 active 指针、completed summary 和 archive index。
-- 不允许把几百行历史明细继续堆在 Feature SSoT 底部作为“文件内归档”。
+当项目启用模块并行开发（见 `references/module-parallel-standard.md`）时：
 
-未启用模块并行的项目继续使用 Feature SSoT 追踪所有功能进度。
+- Module Registry 管模块边界、owner、worktree 和写入范围。
+- module plan / module visual map 管模块内步骤和拓扑索引。
+- Harness Ledger 生成模块任务在全局任务生命周期中的位置。
+- Delivery SSoT 只在需要跨模块、跨仓或多人交付编排时维护。
 
-## SSoT 归档规则
+## 归档规则
 
-每张 SSoT 都必须区分 Active 与 Archive。Active 保存当前事实；Archive 保存可追溯历史。
+每张治理表都必须区分 Active 与 Archive。Active 保存当前事实；Archive 保存可追溯历史。
 
-| SSoT | Active 保留 | 归档触发 | 归档位置 |
+| 表 | Active 保留 | 归档触发 | 归档位置 |
 |------|-------------|----------|----------|
-| Feature SSoT | 未完成 / 仍需操作的 feature | completed/superseded 超过 20 条、release 收束、模块并行切换 | `docs/09-PLANNING/_archive/` |
+| Legacy Feature / Private Feature 生命周期表 | 不再作为 active 表保留 | 迁移到 ledger-only 版本 | `docs/09-PLANNING/_archive/` |
 | Delivery SSoT | 当前交付 block、集成顺序和阻塞项 | wave 结束或 completed/superseded blocks 超过 20 条 | `docs/09-PLANNING/_archive/` |
 | Module Registry | 活跃 / 暂停不久的模块 | 模块 completed 或 paused 超过 60 天 | `docs/09-PLANNING/MODULES/_archive/<key>/` |
 | Regression SSoT | active gates | gate 废弃或长期不再运行 | `docs/05-TEST-QA/_archive/` |
-| Lessons SSoT | pending / approved / superseded 条目 | merged/rejected 超过 20 条 | `docs/01-GOVERNANCE/_archive/` |
-| Harness Ledger | 最近 50 条 active/closed 任务记录 | closed/superseded 超过 50 条 | `docs/01-GOVERNANCE/_archive/` |
+| Cadence Ledger | active cadence checks | cadence 废弃或合并到其他 gate | `docs/05-TEST-QA/_archive/` |
+| Closeout SSoT | 当前 closeout 索引 | closed/superseded 超过保留窗口 | `docs/10-WALKTHROUGH/_archive/` |
+| Lesson detail docs | pending / approved / superseded 详情文档 | merged/rejected 超过 20 条 | `docs/01-GOVERNANCE/_archive/` |
+| Harness Ledger | 当前生成索引 | 重新生成前 archive 旧快照 | `docs/01-GOVERNANCE/_archive/` 或迁移会话 archive |
 
 归档不改变 ID，不删除证据文件；Active 文件必须留下 archive index 或指向归档文件。
 
-## SSoT 与 Planning 的双向绑定
+## SSoT 与 Planning 的绑定
 
-- 每个 task plan 必须指向 SSoT 中的对应条目
-- SSoT 中的每个条目必须指向对应的 task plan
-- 完成任务后，SSoT 和 task plan 都必须更新
-- 非平凡任务完成后，Harness Ledger 必须记录本轮上下文回写结果
+- 每个非平凡任务必须有任务本地 plan / progress / review / lesson / closeout 事实。
+- Harness Ledger 从这些事实生成，不要求人手写任务生命周期表。
+- 非任务生命周期治理表只在本轮实际触达对应事实时更新。
+- 如果生成索引不对，修复 scanner、generator 或任务本地事实。
 
 ## 常见反模式
 
-- 只更新 task plan 不回写 SSoT → SSoT 过时，下一轮 agent 拿到错误信息
-- 只更新 SSoT 不更新 task plan → 任务目录变成死文档
-- 建多个平行的进度总览 → 真相分裂，没人知道哪个是对的
-- 把业务事实复制进 Harness Ledger → 四张 SSoT 被架空
-- 把 Harness Ledger 写成逐行 diff 流水账 → 表会快速失控，没人再读
+- 同时维护旧 Feature 生命周期表和生成 Ledger
+- 只更新 task plan，不刷新生成索引
+- 手写生成表来绕过 scanner 问题
+- 把 Regression / Delivery / Closeout 的详细治理事实复制进 Harness Ledger
+- 建多个平行的进度总览，导致 Agent 不知道哪张表可信