coding-agent-harness 1.0.0

package/references/planning-loop.md

@@ -0,0 +1,192 @@
+# Planning Loop
+
+## 核心思路
+
+每个非平凡任务必须有独立的任务目录和稳定的任务文件。这是 agent 在长时间执行过程中不偏离目标的锚点。
+
+## 任务目录结构
+
+```
+docs/09-PLANNING/TASKS/<YYYY-MM-DD-任务名>/
+├── task_plan.md    ← 计划：目标、范围、步骤、验收标准
+├── execution_strategy.md ← 执行策略：模式、subagent、冲突控制、验证深度、handoff
+├── visual_roadmap.md ← 可视化路线：Mermaid、phase table、完成度、证据状态
+├── findings.md     ← 发现：执行过程中的研究发现和技术决策
+├── progress.md     ← 进度：每个阶段的状态更新和验证结果
+├── review.md       ← 对抗性审查报告（需要 reviewer / subagent / release review 时必填）
+└── long-running-task-contract.md ← 长程任务合同（仅长程任务需要）
+```
+
+复杂任务可以启用 optional structure，但不能默认创建空目录：
+
+```
+references/INDEX.md        ← 任务本地参考、外部链接、reviewer packet
+artifacts/INDEX.md         ← 命令输出、截图、fixture、review transcript
+slices/<slice-id>/brief.md ← 多切片任务的单切片输入和范围
+slices/<slice-id>/evidence.md
+slices/<slice-id>/review.md
+```
+
+启用条件：
+
+- reviewer/subagent 输入包需要复用：启用 `references/INDEX.md`
+- 命令输出、截图、fixture、review transcript 会污染主文件：启用 `artifacts/INDEX.md`
+- 超过 5 个 slice、多 worker、release gate、L2+ evidence：启用 `slices/`
+
+## 执行规则
+
+1. **每个阶段前读 task_plan.md** — agent 重新对齐目标
+2. **每个阶段后更新 progress.md** — 记录做了什么、验证了什么
+3. **研究发现写入 findings.md** — 不丢失中间产物
+4. **禁止在项目根目录放过程文件** — task_plan.md、findings.md、progress.md 只能在任务目录内
+5. **对抗性审查必须写 review.md** — 如果任务使用 reviewer / subagent / release review，按 `adversarial-review-standard.md` 写报告
+6. **长程任务必须补合同** — 如果任务需要连续执行、多轮审查或子代理 review，先补 `long-running-task-contract.md`
+7. **任务收口必须回写 Harness Ledger** — 只在任务完成或上下文回写状态变化时记录，不记录每次 `progress.md` 更新
+8. **复杂任务必须记录 `execution_strategy.md`** — 是否使用 subagent、reviewer、worktree、handoff 都写入独立文件。
+9. **非平凡任务必须记录 `visual_roadmap.md`** — HTML dashboard 从独立文件的 Mermaid 和 phase table 计算完成度、阻塞和证据状态。
+10. **路径必须带来源前缀** — 使用 `PUBLIC:`, `PRIVATE:`, `TARGET:`, `EXTERNAL:`, `URL:`，避免脆弱相对路径。
+
+## task_plan.md 模板
+
+```markdown
+# [任务名称]
+
+## 目标
+[一句话说清楚这个任务要达成什么]
+
+## 范围
+[做什么、不做什么]
+
+## Task IA Budget
+[simple / complex；如果 complex，列出启用哪些 optional structure 和原因]
+
+## Context Packet
+| ID | Type | Path | Why It Matters | Used By |
+| --- | --- | --- | --- | --- |
+
+## Execution & Visualization Files
+| Contract File | Required | Purpose |
+| --- | --- | --- |
+| `execution_strategy.md` | yes | Execution mode, subagent use, conflict control, evidence depth, handoff rules |
+| `visual_roadmap.md` | yes | Mermaid route, phase table, completion, evidence status, blocking risk |
+
+## 步骤
+1. [步骤1]
+2. [步骤2]
+...
+
+## 验收标准
+- [ ] [标准1]
+- [ ] [标准2]
+
+## Worktree
+- 路径：[worktree 路径]
+- 分支：[分支名]
+- Worker owner：[coordinator / subagent id / 不适用]
+- Worker handoff commit required：[yes / no / 不适用]
+- Coordinator integration branch：[分支名 / 不适用]
+- 若未开 worktree，原因：[说明]
+
+## 长程任务判定
+- 是否属于长程任务：[是 / 否]
+- 若是，合同文件：`long-running-task-contract.md`
+- Stop Condition 摘要：[什么时候可以停]
+
+## Review 判定
+- 是否需要对抗性 review：[是 / 否]
+- 若是，报告文件：`review.md`
+- Reviewer：[self / subagent / external / human]
+```
+
+## 模块并行开发时的任务目录
+
+当项目启用模块并行开发（见 `references/module-parallel-standard.md`）时：
+
+- 任务目录位于模块内：`docs/09-PLANNING/MODULES/<key>/TASKS/<PREFIX>-NN-<name>/`
+- 跨模块基础设施任务位于：`docs/09-PLANNING/MODULES/_shared/TASKS/YYYY-MM-DD-<name>/`
+- task_plan.md 应填写"模块关联"段（Module、Step、Module Plan link）
+- 会话结束时除了更新 progress.md，还需更新 module_plan.md。
+- 模块 worker 不直接写 Module Registry / Harness Ledger / Closeout SSoT。需要总表同步时，在 task_plan.md 或 progress.md 的 `Coordinator Handoff` 段标记 `pending-coordinator-pass`，由 coordinator 串行同步。
+- coordinator pass 完成后，才更新 Module Registry、Harness Ledger、必要的 Closeout / Regression 表，并把 handoff 标记为 `synced`。
+
+## 为什么这套东西有效
+
+- agent 的上下文窗口有限，task_plan 是它在长任务中唯一稳定的锚点
+- progress.md 让下一轮 agent（或同一个 agent 的下一个 session）能快速接上
+- findings.md 避免重复研究同一个问题
+- 强制目录结构让所有任务可追溯、可检索
+
+## 与 Anthropic Long-running Agents 方案的对照
+
+Anthropic 的方案用 Feature List JSON + progress file + git commit 做跨 session 交接。
+task_plan + findings + progress 是同一思路的更细粒度表达；`review.md` 负责保存
+对抗性审查结论，避免 review 只留在对话里。
+
+## findings.md 模板
+
+```markdown
+# [任务名称] - Findings
+
+## 研究发现
+
+### [发现主题 1]
+- 背景：[为什么要研究这个]
+- 发现：[具体发现了什么]
+- 影响：[对任务计划有什么影响]
+
+### [发现主题 2]
+...
+
+## 技术决策
+
+| 决策 | 选择 | 原因 | 替代方案 |
+|------|------|------|----------|
+| [决策1] | [选了什么] | [为什么] | [没选什么] |
+```
+
+## progress.md 模板
+
+```markdown
+# [任务名称] - Progress
+
+## 状态：[未开始 / 进行中 / 已完成 / 已阻塞]
+
+## 进度记录
+
+Evidence values use `type:path:summary`.
+
+### [YYYY-MM-DD HH:MM] - [阶段名称]
+- 做了什么：[具体操作]
+- 验证结果：[跑了什么测试，结果如何]
+- 下一步：[接下来做什么]
+- Evidence：[type:path:summary]
+
+### [YYYY-MM-DD HH:MM] - [阶段名称]
+...
+
+## Residual
+- [遗留问题1]
+- [遗留问题2]
+```
+
+## 任务目录命名规范
+
+格式：`YYYY-MM-DD-任务名称`
+
+示例：
+- `2026-03-15-user-auth-refactor`
+- `2026-03-18-ui-timeline-component`
+- `2026-04-01-regression-gate-webhook-live`
+
+## 状态流转
+
+```
+未开始 → 进行中 → 已完成
+              ↓
+          已阻塞 → 进行中
+```
+
+每次状态变更时，必须同时更新 progress.md 和 Feature SSoT。
+
+任务完成时，必须在 `docs/Harness-Ledger.md` 中记录本轮 task plan、SSoT、
+walkthrough、Lessons 检查等上下文回写结果。

package/references/project-onboarding-audit.md

@@ -0,0 +1,167 @@
+# 项目诊断（Onboarding Audit）
+
+## 目的
+
+在搭建 harness 之前，先了解项目现状，确定适合的 harness 规模和结构。
+
+## 扫描清单
+
+进入项目后，按以下清单逐项检查：
+
+### 1. 仓库结构
+- 单仓还是多仓？
+- 是否是 monorepo（多包）？
+- 有哪些子项目 / packages / apps？
+- 有没有前后端分离？
+
+### 2. 技术栈
+- 主要语言和框架？
+- 包管理器？（npm / pnpm / yarn / pip / cargo 等）
+- 构建工具？
+- 运行时环境？
+
+### 3. 现有文档
+- 有没有 AGENTS.md / CLAUDE.md / COPILOT.md？
+- 有没有 docs/ 目录？结构如何？
+- 有没有 README 以外的开发文档？
+- 有没有架构设计文档？
+
+### 4. 现有测试
+- 有没有测试框架？（jest / vitest / pytest / go test 等）
+- 有没有 CI/CD？
+- CI workflow 是否实际存在？路径是什么？
+- PR required checks 是哪些？是否和 workflow job 对齐？
+- 主分支有没有 branch protection？能否用平台 API 验证？
+- 测试覆盖率大概什么水平？
+- 有没有端到端测试或集成测试？
+- 有没有冒烟测试？
+
+### 5. 现有任务管理
+- 有没有任务追踪系统？（GitHub Issues / Linear / Jira 等）
+- 有没有排期文档或 SSoT？
+- 有没有 planning 目录或任务模板？
+- 有没有 Harness Ledger 或类似上下文回写总账？
+
+### 6. 协作模式
+- 几个人在开发？
+- 是否使用 Coding Agent？用哪些？
+- 是否有多 agent 并行的需求？
+- 是否使用 git worktree？
+- 允许同时存在几个 active worktree？
+- merge 顺序由谁决定？
+
+### 6a. Delivery Operating Model
+- 当前是单人主控、多 agent 并行，还是多人团队各自带 agent？
+- 是否有 team lead / tech lead 负责拆 feature block？
+- 是否是前后端分仓、app/service 分仓或 program 多仓？
+- 前端 agent 是否只能看到 API 文档 / mock / schema？后端 agent 是否只能看到消费合同？
+- 当前使用敏捷 sprint、kanban 连续流、瀑布 stage-gate，还是个人连续执行？
+- 是否需要 `docs/09-PLANNING/Delivery-SSoT.md` 记录 feature block owner、依赖、集成顺序和 acceptance gates？
+
+### 6b. Repo Governance
+- repo platform 是 GitHub / GitLab / local-only / 其他？
+- 是否有 PR template？
+- 是否有 CODEOWNERS？
+- 是否允许 direct push 到主分支？
+- branch protection 状态是 designed / implemented / verified / blocked-with-owner？
+- agent 是否有权限读取或设置 repo protection？
+
+### 7. 关键 Surface
+- 项目有哪些用户入口？（Web UI、API、CLI、Bot、插件等）
+- 有哪些外部集成点？（第三方 API、数据库、消息队列等）
+- 哪些 surface 最容易被改动破坏？
+
+## 诊断报告模板
+
+扫描完成后，输出以下格式的诊断报告：
+
+```markdown
+# Harness Onboarding Audit
+
+## 项目概况
+- 项目名：[名称]
+- 仓库类型：[单仓 / monorepo / 多仓]
+- 技术栈：[语言 / 框架 / 运行时]
+- 团队规模：[人数 + agent 数]
+
+## 现状评估
+
+| 维度 | 现状 | 评级 |
+|------|------|------|
+| AGENTS.md | [有/无/需改造] | 🟢/🟡/🔴 |
+| docs/ 目录 | [有/无/需改造] | 🟢/🟡/🔴 |
+| Reference 标准 | [有/无/需改造] | 🟢/🟡/🔴 |
+| Planning Loop | [有/无/需改造] | 🟢/🟡/🔴 |
+| Delivery Operating Model | [solo/team/split-repo/program/waterfall/kanban/需确认] | 🟢/🟡/🔴 |
+| Delivery SSoT | [有/无/不需要/需改造] | 🟢/🟡/🔴 |
+| Feature SSoT | [有/无/需改造] | 🟢/🟡/🔴 |
+| Regression 体系 | [有/无/需改造] | 🟢/🟡/🔴 |
+| CI/CD | [有/无/需改造] | 🟢/🟡/🔴 |
+| Repo Governance | [有/无/需改造] | 🟢/🟡/🔴 |
+| Branch Protection | [designed/implemented/verified/blocked] | 🟢/🟡/🔴 |
+| Required Checks | [有/无/需改造] | 🟢/🟡/🔴 |
+| Harness Ledger | [有/无/需改造] | 🟢/🟡/🔴 |
+| Walkthrough 流程 | [有/无/需改造] | 🟢/🟡/🔴 |
+| Worktree 规范 | [有/无/需改造] | 🟢/🟡/🔴 |
+
+## 关键 Surface 清单
+1. [Surface 1]：[描述]
+2. [Surface 2]：[描述]
+...
+
+## 推荐 Harness 规模
+[Lite / Standard / Full]（见下方项目类型分支）
+
+## 落地方案
+[具体说明需要创建哪些文件、改造哪些现有文件]
+
+## 风险点
+- [风险1]
+- [风险2]
+```
+
+## 项目类型分支
+
+根据项目规模和复杂度，harness 分三个规模：
+
+### Lite（小型项目）
+适用于：单仓、单人开发、代码量 < 1 万行、surface 少于 3 个
+
+最小配置：
+- AGENTS.md
+- docs/11-REFERENCE/ 下 2-3 个标准文件
+- Delivery Operating Model 标准，明确是否为 `solo-orchestrator`
+- Planning task plan / findings / progress / review 模板
+- repo governance / CI-CD 标准和 residual
+- 简化版 Regression SSoT（可以只有 tests + local_smoke 两层）
+- Harness Ledger（只记录 task closeout 行）
+- Walkthrough 模板
+
+可省略：
+- Cadence Ledger（手动触发即可）
+- Feature SSoT（用 AGENTS.md 里的简单列表替代）
+- Worktree 规范（单人不需要并行）
+
+### Standard（中型项目）
+适用于：单仓或 monorepo、1-3 人 + agent、代码量 1-10 万行、surface 3-10 个
+
+完整配置：
+- 全部 Phase 1-12
+- Delivery Operating Model；若多人协作则创建 Delivery SSoT
+- Evidence Depth 至少覆盖到 L3（live 环境验证）
+- Cadence Ledger
+- Harness Ledger
+- Worktree 规范
+- repo governance / CI-CD workflow 或 blocked-with-owner residual
+
+### Full（大型项目）
+适用于：多仓或大型 monorepo、多人 + 多 agent 并行、代码量 > 10 万行、surface > 10 个
+
+完整配置 + 额外要求：
+- Program / split-repo operating model 和 Delivery SSoT
+- 每个子仓库或重要子包有自己的 reference 文件
+- Evidence Depth 要求覆盖到 L4 或 L5
+- Shared Regression Batch 定期执行
+- Harness Ledger 季度归档
+- 多 agent 并行分工协议
+- 跨仓库 surface 映射

package/references/regression-system.md

@@ -0,0 +1,89 @@
+# Regression 体系
+
+## 核心思路
+
+单元测试只是底线。长程项目需要多层证据来保证正确性。
+
+## Evidence Depth 五级制
+
+每条回归面都标注它的证据到了哪一层：
+
+| 层级 | 名称 | 含义 | 可信度 |
+|------|------|------|--------|
+| L1 | tests | 只有单元测试 | 最低 |
+| L2 | local_smoke | 本地冒烟测试通过 | 低 |
+| L3 | live_e2e | 真实环境端到端验证 | 中 |
+| L4 | browser_human_proxy | 浏览器模拟真人操作 | 高 |
+| L5 | hard_gate | 结构化判定 + 非零退出 | 最高 |
+
+越高层的证据越可信。L1 只能说明代码能编译和通过基本逻辑检查，L5 能自动告诉你"过了"还是"没过"。
+
+## Regression SSoT 结构
+
+```markdown
+# Regression SSoT
+
+## Active Fixed Gates
+
+| ID | Status | Surface | Primary Entrypoint | Evidence Depth |
+|----|--------|---------|-------------------|----------------|
+| RG-001 | 🟢 | API Contract Smoke | `npm run smoke:api` | hard_gate |
+| RG-002 | 🟢 | External Integration E2E | `npm run smoke:integration:live` | live_e2e |
+| ...
+
+## Residual Items
+
+| ID | Surface | Issue | Priority |
+|----|---------|-------|----------|
+| R-001 | Frontend | Timeline 组件偶发渲染延迟 | P2 |
+| ...
+
+## Shared Regression Ledger
+
+| Batch | Date | Scope | Result | Next Checkpoint |
+|-------|------|-------|--------|-----------------|
+| SRB-010 | 2026-04-12 | Full | 9/9 🟢 | SRB-011 after wave-14 |
+| ...
+
+## Archive Index
+
+| Archive | Range | Notes |
+|---------|-------|-------|
+| `docs/05-TEST-QA/_archive/Regression-SSoT-archive-YYYY-QN.md` | RG-XXX-RG-YYY | retired gates |
+```
+
+## Cadence Ledger
+
+定义什么情况下自动触发哪些回归面：
+
+```markdown
+## Cadence Rules
+
+- 改了 API contract → 跑 RG-001 + RG-004
+- 改了 external integration adapter → 跑 RG-002 + RG-003
+- 改了 core domain logic → 跑 RG-008 + RG-009 + RG-010
+- 改了 frontend user flow → 跑 RG-005（如有）
+- 任何 merge 到 master → 跑 Full Shared Batch
+```
+
+不用人记住该跑什么，系统自己知道。
+
+## 与 Harness Ledger 的关系
+
+Regression SSoT 和 Cadence Ledger 管“回归事实”：有哪些 gate、证据深度是多少、
+最近 batch 结果如何。
+
+Harness Ledger 只在当前任务收口时记录 `Regression=updated`、`Regression=n/a` 等
+任务级回写状态。不要把 batch 明细复制进 Harness Ledger。
+
+## 建立回归体系的步骤
+
+1. 列出项目的所有关键 surface（用户入口、API 端点、集成点）
+2. 为每个 surface 建一条 regression gate，写好命令行入口
+3. 标注每条 gate 的当前 Evidence Depth
+4. 定义 Cadence Rules
+5. 跑第一轮 Shared Batch，记录结果
+6. 持续迭代：每次新增 surface 或 evidence depth 提升时更新 SSoT
+
+废弃 gate 或过期 shared batch 明细不要长期堆在 Active 表底部；移动到
+`docs/05-TEST-QA/_archive/`，并在 Regression SSoT 中保留 Archive Index。

package/references/repo-governance-standard.md

@@ -0,0 +1,131 @@
+# Repository Governance Standard
+
+## 核心思路
+
+Harness 不是只生成文档骨架。每个项目必须有项目级 repository governance contract，
+明确分支、PR、merge、review、required checks、worktree 并发和权限残项。
+
+如果某些设置因为权限不足无法自动配置，agent 不能把它们当作完成；必须记录为
+`blocked-with-owner` 或 `manual-setup-residual`。
+
+## 存放位置
+
+标准文件：
+
+```text
+docs/11-REFERENCE/repo-governance-standard.md
+```
+
+如果项目需要更详细的 CI/CD 说明，另见：
+
+```text
+docs/11-REFERENCE/ci-cd-standard.md
+```
+
+## 必填字段
+
+每个项目必须定制以下内容：
+
+### Repo Platform Profile
+
+- Platform: [GitHub / GitLab / local-only / other]
+- Remote: [owner/repo or URL]
+- Default branch: [main / master / other]
+- Repo type: [single app / monorepo / multi-repo / library / service]
+- Admin access available to agent: [yes / no / unknown]
+
+### Branch Model
+
+- Protected branch(es)
+- Feature branch naming
+- Release branch naming, if any
+- Hotfix branch naming, if any
+- Direct push policy
+
+### PR Policy
+
+- PR required before merge: [yes / no]
+- PR title format
+- PR body requirements
+- Required reviewers
+- Required review type: [self / subagent / external / human]
+- Merge method: [squash / merge commit / rebase]
+- Who decides merge order
+
+### Required Checks
+
+List every check required before merge:
+
+| Check | Command / Workflow | Required? | Evidence |
+|-------|--------------------|-----------|----------|
+| lint | [command] | yes/no | [where result is recorded] |
+| typecheck | [command] | yes/no | [where result is recorded] |
+| build | [command] | yes/no | [where result is recorded] |
+| test | [command] | yes/no | [where result is recorded] |
+| smoke | [command] | yes/no | [where result is recorded] |
+
+### Branch Protection Plan
+
+Branch protection status must use one of:
+
+- `designed`
+- `implemented`
+- `verified`
+- `blocked-with-owner`
+
+Required fields:
+
+- Required status checks
+- Required PR review count
+- Dismiss stale reviews: [yes / no]
+- Require branches up to date: [yes / no]
+- Block force push: [yes / no]
+- Block deletion: [yes / no]
+- Bypass actors, if any
+- Verification command or manual setup residual
+
+### Worktree Concurrency
+
+- Max active worktrees
+- Naming pattern
+- Branch pattern
+- Ownership rule
+- Subagent worker rule: each code-changing worker uses its own worktree / branch and hands off a commit SHA
+- Merge ordering rule
+- Cleanup rule
+
+## Evidence Status Model
+
+Every governance item must be marked as:
+
+| Status | Meaning |
+|--------|---------|
+| `designed` | Plan exists, not implemented |
+| `implemented` | File / workflow / config exists |
+| `verified` | Live or local verification passed |
+| `blocked-with-owner` | Cannot finish without named owner/action |
+
+Agent must not describe `designed` as complete.
+
+## GitHub Default Adapter
+
+For GitHub repositories, the default implementation should include:
+
+- `.github/pull_request_template.md`
+- `.github/workflows/ci.yml` or an explicit reason why CI is impossible
+- branch protection plan for `main`
+- required checks matching actual workflow job names
+- review routing rule aligned with `review-routing-standard.md`
+
+If the agent has GitHub admin permissions, it should verify branch protection with `gh api`.
+If not, it must write manual setup residual with owner and exact settings.
+
+## Completion Rule
+
+Bootstrap is not complete unless repository governance is at least:
+
+- PR policy: `implemented`
+- Required checks: `implemented`
+- Branch protection: `designed` with residual, or `verified`
+- Worktree concurrency: `implemented`
+- Harness checker: passing or blocked-with-owner with explicit residual

package/references/review-routing-standard.md

@@ -0,0 +1,103 @@
+# Review Routing Standard
+
+## 核心思路
+
+`adversarial-review-standard.md` 定义 review report 怎么写；本标准定义 review 怎么触发、谁来审、外部 reviewer 如何纳入项目规则。
+
+每个 planned task / wave / feature 结束前，必须自动进入 closeout review。默认最低要求是：
+
+1. 主 agent 完成 self-review。
+2. 主 agent 调用 reviewer / subagent 做外部视角审查。
+3. reviewer 按 `adversarial-review-standard.md` 写入或补全 `review.md`。
+4. 主 agent 修复或路由 material findings。
+5. 再次运行 Confidence Challenge，直到没有 open material finding。
+
+## 触发规则
+
+必须触发 closeout review：
+
+- planned task / wave / feature 收口
+- 长程任务每轮进入 stop condition 判断前
+- 涉及架构、数据、安全、权限、部署、迁移、跨模块契约
+- release / PR / merge 前
+- 用户明确要求 review / 外部审查 / 人工审查
+
+轻量单文件修复可以只做 self-review，但必须在 `progress.md` 写明跳过 subagent / external reviewer 的理由。
+
+## Reviewer 层级
+
+| 层级 | Reviewer | 适用场景 | 要求 |
+|------|----------|----------|------|
+| L0 | Self-review | 微小变更 | 写入 `progress.md` 或 `review.md` |
+| L1 | Subagent reviewer | 默认非平凡任务 | 必须写 `review.md` |
+| L2 | External agent reviewer | 用户或项目要求，如 Claude Code / Gemini / Codex 另一实例 | 必须写 `review.md`，并记录 reviewer identity |
+| L3 | Human reviewer | 高风险产品、架构、安全、数据、发布判断 | Agent 必须在内部审查结束后明确询问是否需要人工审查 |
+
+默认策略：planned task 至少 L1。若当前环境无法调用 subagent，必须记录
+`skipped-with-reason`，并升级 self-review 的 Confidence Challenge 严格度。
+
+## Subagent Worker Routing
+
+本标准默认把 subagent 当 reviewer：只读审查、写 `review.md`、报告 material findings。
+
+如果 subagent 被要求直接改代码、测试、产品文档或 harness 文档，它就不是 reviewer，
+而是 worker。Worker 必须按 `worktree-parallel.md` / 项目级 `worktree-standard.md`
+执行：
+
+- coordinator 先分配独立 worktree / branch、任务目录和 write scope
+- worker 只在自己的 worktree 内实现、验证并提交
+- handoff 必须包含 worktree path、branch、commit SHA、checks、residual risks
+- coordinator 负责 merge / conflict resolution / final gates
+
+禁止把多个 worker 的未提交改动混在 coordinator 当前 checkout，再由 coordinator 一次性提交。
+
+## 外部审查人工触发
+
+如果用户要求外部审查或人工审查，Agent 不应把这当成一次聊天请求。它应转化为项目规则：
+
+1. 在当前任务的 `review.md` 记录触发来源和审查范围。
+2. 如果是一次性审查，按本轮任务执行。
+3. 如果用户希望长期遵循，创建或更新项目级 `docs/11-REFERENCE/review-routing-standard.md`。
+4. 在 `AGENTS.md` 的 Task-Type Reading Matrix 中加入 reviewer routing 入口。
+5. 在 Harness Ledger 记录该规则变更。
+
+## 项目级 reviewer policy
+
+项目可以指定默认外部 reviewer，例如：
+
+- Claude Code 负责架构和实现策略外部审查
+- Gemini 负责 web / dependency / ecosystem research 交叉检查
+- Codex subagent 负责代码 diff、测试缺口和回归风险
+- Human reviewer 负责产品方向、安全和发布 gate
+
+项目级 policy 必须写清：
+
+- 默认 reviewer
+- 触发条件
+- reviewer 是否只读
+- reviewer 输出写入位置
+- 主 agent 如何处理分歧
+- 哪些 finding 必须暂停并询问用户
+
+## 两方校准
+
+当引入新的外部 reviewer 时，应先执行一次 calibration：
+
+1. 主 agent 写出任务目标、scope、证据和当前策略。
+2. 外部 reviewer 用 Confidence Challenge 挑战策略。
+3. 双方对 finding severity、accepted residual、stop condition 口径达成一致。
+4. 将共识写入项目级 `review-routing-standard.md`。
+
+校准不是长期讨论。它的目标是形成后续可执行规则。
+
+## Closeout Checklist
+
+任务收口前必须确认：
+
+- [ ] `review.md` 存在，或有明确 `skipped-with-reason`
+- [ ] L1 subagent review 已执行，或环境限制已记录
+- [ ] Confidence Challenge 已回答并记录 final confidence basis
+- [ ] open P0/P1 findings 为 0
+- [ ] material P2 已修复或 accepted residual 并路由
+- [ ] 如使用 worker subagent，已记录 worker branch、commit SHA、checks 和 integration evidence
+- [ ] walkthrough / Harness Ledger 引用了 review report 或 skip reason