coding-agent-harness 1.0.8 → 1.1.0

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

@@ -1,7 +1,5 @@
 # {{TASK_TITLE}}
 
-## Brief
-
 ## Task ID
 
 `{{TASK_ID}}`
@@ -10,9 +8,25 @@
 
 {{DATE}}
 
-## 目标结果
+## 一句话结果
+
+用一句话说明这个任务完成后会产生什么具体结果。
+
+## 完成后能得到什么
+
+用 100-300 字说明这个任务完成后，用户、项目或下一轮 agent 能直接拿到什么结果。
+说明这个结果能用于什么决策、交付、验证或继续开发。聚焦可用结果，不要展开实现过程，
+除非实现方式本身就是交付物。
+
+## 交付物
 
-说明这个任务完成后，用户或项目能直接看到的结果。
+- 可见产物：
+- 修改位置：
+- 验证证据：
+
+## 第一眼应该看什么
+
+写明人或下一轮 agent 打开任务后，应该先读哪些文件、证据或生成产物。
 
 ## 边界
 
@@ -20,13 +34,18 @@
 - 范围外：不能顺手塞进来的工作。
 - 停止条件：遇到不确定性、风险或缺少权限时，必须回到 coordinator 或用户确认。
 
+## 完成判断
+
+列出 3-5 条能证明目标结果已经达成的具体条件。完整执行计划保留在 `task_plan.md`。
+
 ## 执行合同
 
 - Owner：coordinator
 - 生命周期状态：未开始
-- 必需文件：`INDEX.md`、`task_plan.md`、`execution_strategy.md`、`visual_map.md`、`progress.md`、`findings.md`、`review.md`
+- 必需文件：`INDEX.md`、`task_plan.md`、`execution_strategy.md`、`visual_map.md`、
+  `progress.md`、`findings.md`、`review.md`
 - 完成条件：验证证据必须记录到 `progress.md`
 
-## 第一步
+## 当前下一步
 
-开始实现前，把这里替换成第一个具体动作。
+写明开始实现前的第一个具体动作。

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

@@ -1,7 +1,5 @@
 # {{TASK_TITLE}} 模块
 
-## Brief
-
 ## 模块 Key
 
 `{{TASK_ID}}`
@@ -10,6 +8,26 @@
 
 {{DATE}}
 
+## 一句话结果
+
+用一句话说明这个模块持续维护什么结果。
+
+## 完成后能得到什么
+
+用 100-300 字说明这个模块健康运行时，用户、项目、coordinator 或 worker agents
+能得到什么。说明它能改善哪些决策、交付协调、验证或交接工作。聚焦模块带来的运行结果，
+不要展开内部流程。
+
+## 交付物
+
+- 可见产物：
+- 负责范围：
+- 验证证据：
+
+## 第一眼应该看什么
+
+写明人打开模块后应该先读哪个 module plan、任务列表、证据或生成产物。
+
 ## 模块职责
 
 说明这个模块负责什么，以及为什么需要独立管理。
@@ -20,6 +38,10 @@
 - 共享面：需要 coordinator 同步的文件。
 - 不负责：相邻模块或未声明的全局文件。
 
+## 完成判断
+
+列出能证明这个模块 brief 仍然反映当前模块合同的条件。执行细节保留在 `module_plan.md`。
+
 ## 当前工作
 
 列出当前模块任务，或指向 `module_plan.md`。

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

@@ -1,43 +1,49 @@
-# [模块名] Module Plan
+# {{TASK_TITLE}} 模块计划
 
-## 基本信息
+## 模块身份
 
-- Key：[module key]
-- PREFIX：[step ID prefix]
-- Branch：[长期分支名，例如 `codex/reader`]
-- 写入范围：[该模块可修改的目录或文件范围]
-- Shared surfaces：[与其他模块共享、需要协调的文件或能力面；无则写“无”]
+- 模块 Key：`{{TASK_ID}}`
+- 负责人：coordinator
+- 分支：
+- 写入范围：
+- 共享面：
+- 依赖模块：
 
-## 步骤序列
+## 边界
+
+- 可以编辑：
+- 禁止编辑：
+- 外部依赖：
+
+## 步骤
 
 | 步骤 ID | 名称 | 状态 | 任务计划 | 依赖 |
 | --- | --- | --- | --- | --- |
-| XXX-01 | [步骤名] | planned | — | — |
-| XXX-02 | [步骤名] | planned | — | XXX-01 |
+| MOD-01 | 定义模块运行合同 | planned | none | none |
 
-## 执行与可视化文件
+## 活跃任务
 
-模块级 `execution_strategy.md` 和 `visual_map.md` 应放在本模块目录，与 `module_plan.md` 同级，不嵌入本文件。
-
-| 合同文件 | 是否必需 | 用途 |
-| --- | --- | --- |
-| `execution_strategy.md` | yes | 模块执行模式、写入边界、subagent 使用、全局同步 owner、验证深度 |
-| `visual_map.md` | yes | 模块图表集合、阶段图、状态、完成度、证据状态、阻塞风险 |
-
-旧模块目录可以保留历史嵌入式段落作为 fallback；新模块目录必须使用独立文件。
+| 任务 | 状态 | 负责人 | 证据 | 备注 |
+| --- | --- | --- | --- | --- |
+| none | planned | coordinator | none | 有模块任务后替换此行。 |
 
-## 状态定义
+## 验证
 
-- `planned`：尚未开始
-- `in-progress`：正在开发
-- `done`：已完成并合并
-- `blocked`：被依赖或外部条件阻塞
-- `superseded`：已被其他步骤替代
+| 检查 | 命令或证据 | 必需 |
+| --- | --- | --- |
+| 模块任务合同 | `harness check --profile target-project .` | yes |
 
-## 当前状态
+## 交接
 
-[用 1-3 句话描述当前进度，供新会话快速接手。每次会话结束时更新。]
+- 分支：
+- Commit SHA：
+- 检查：
+- 变更文件：
+- 残余风险：
+- 需要 coordinator 同步：
 
-## 完成标准
+## 模板边界
 
-[写清模块整体完成条件。所有步骤 `done` 不等于模块完成，可能仍需集成测试、性能验证、文档收口或 coordinator 同步。]
+这份 planning 模板仅为兼容旧安装保留。新的模块根目录从 `templates/modules/**`
+生成，默认只拥有 `brief.md` 和 `module_plan.md`。`execution_strategy.md`、
+`visual_map.md`、`review.md`、`walkthrough.md` 等执行合同属于具体任务目录。

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

@@ -1,4 +1,8 @@
-# 模块会话提示词（Module Session Prompt）
+# 模块会话提示词包
+
+这份 planning 模板作为兼容旧安装的别名保留。新的安装使用全局
+`templates/modules/session_prompt_pack.md`；CLI 默认不会创建每个模块自己的
+`session_prompt.md`。
 
 用于为模块并行项目启动一个长程模块会话。交给新 agent 前，coordinator 必须先用真实项目事实替换占位符。
 
@@ -12,14 +16,14 @@
 - Coordinator 负责集成 worker commit 并运行最终门禁；不要在一个 checkout 中混合多个 worker 的未提交改动。
 
 目标：
-- 执行 coding-agent-harness/planning/modules/Module-Registry.md 与 coding-agent-harness/planning/modules/<module-key>/module_plan.md 中为 <module-key> 标记的当前步骤。
+- 执行 {{paths.harnessRoot}}/planning/modules/Module-Registry.md 与 {{paths.harnessRoot}}/planning/modules/<module-key>/module_plan.md 中为 <module-key> 标记的当前步骤。
 - 除非触发 stop condition，否则持续推进到该步骤已实现、已验证、已记录，并可进入审查。
 
 冷启动：
 1. 阅读 AGENTS.md。
-2. 阅读 coding-agent-harness/planning/modules/Module-Registry.md。
-3. 阅读 coding-agent-harness/planning/modules/Session-Prompt-Pack.md 或 coding-agent-harness/planning/modules/<module-key>/session_prompt.md。
-4. 阅读 coding-agent-harness/planning/modules/<module-key>/module_plan.md。
+2. 阅读 {{paths.harnessRoot}}/planning/modules/Module-Registry.md。
+3. 阅读 {{paths.harnessRoot}}/planning/modules/Session-Prompt-Pack.md。
+4. 阅读 {{paths.harnessRoot}}/planning/modules/<module-key>/module_plan.md。
 5. 按项目任务阅读矩阵读取本任务涉及文件对应的标准文档。
 
 启动门禁：
@@ -27,9 +31,9 @@
 - 确认当前 checkout/worktree path 是 <worktree-path>，当前分支是 <branch-name>。
 - 编辑前检查 dirty state，不要 revert 无关改动。
 - 如果另一个活跃会话拥有该模块或必需共享文件，停止并记录冲突。
-- 代码编辑前，基于项目 planning 模板创建或更新 coding-agent-harness/planning/modules/<module-key>/tasks/<current-step>-<short-name>/task_plan.md，写清范围、验收、验证、分支/worktree 和共享协调。
+- 代码编辑前，基于项目 planning 模板创建或更新 {{paths.harnessRoot}}/planning/modules/<module-key>/tasks/<current-step>-<short-name>/task_plan.md，写清范围、验收、验证、分支/worktree 和共享协调。
 - 代码编辑前，确认模块任务目录含有 `execution_strategy.md` 与 `visual_map.md`。如缺失，先补齐再实现。
-- 如果 coding-agent-harness/planning/modules/<module-key>/ 缺少模块级 `execution_strategy.md` 或 `visual_map.md`，在派发 worker 前补齐或更新。
+- 模块根目录默认只维护 `brief.md` 和 `module_plan.md`；不要把任务执行合同放到模块根目录。
 
 分支与工作树：
 - Worktree path: <worktree-path>.
@@ -41,7 +45,7 @@
 写入范围：
 - 允许：<module-write-scope>.
 - 未明确协调前禁止：<shared-or-forbidden-scope>.
-- 共享协调产物：coding-agent-harness/planning/modules/_shared/tasks/<id>/task_plan.md，或模块任务计划中的“共享协调”段，必须写明 owner、涉及文件、允许改动、reviewer 和 merge 顺序。
+- 共享协调产物：{{paths.harnessRoot}}/planning/modules/_shared/tasks/<id>/task_plan.md，或模块任务计划中的“共享协调”段，必须写明 owner、涉及文件、允许改动、reviewer 和 merge 顺序。
 - 如果实现需要触碰允许范围之外的文件，停止并记录所需协调，不要直接编辑。
 
 验证：
@@ -52,12 +56,12 @@
 
 收口：
 - 更新模块计划和模块任务进度。
-- 除非 coordinator 明确分配共享锁，worker session 不得更新 coding-agent-harness/planning/modules/Module-Registry.md、coding-agent-harness/governance/generated/Harness-Ledger.md、Closeout Index、Regression SSoT 或 Cadence Ledger。
+- 除非 coordinator 明确分配共享锁，worker session 不得更新 {{paths.harnessRoot}}/planning/modules/Module-Registry.md、{{paths.harnessRoot}}/governance/generated/Harness-Ledger.md、Closeout Index、Regression SSoT 或 Cadence Ledger。
 - 如果需要全局表更新，在 task_plan.md 或 progress.md 写 Coordinator 交接，并标记 `Global sync status: pending-coordinator-pass`。
-- 只有 coordinator pass 或明确的 shared-lock owner 可以更新 coding-agent-harness/planning/modules/Module-Registry.md。
+- 只有 coordinator pass 或明确的 shared-lock owner 可以更新 {{paths.harnessRoot}}/planning/modules/Module-Registry.md。
 - 汇报状态时区分 `task.state`、`lifecycleState`、`reviewStatus` 和 `closeoutStatus`；`done` 只表示实现步骤完成，不等于 `closed`。
 - 把当前任务 `visual_map.md` 阶段表作为生命周期地图。切片结束时检查当前 gate phase；只有 `Actor` 为 `agent` 的 `Exit Command` 才由 Agent 执行。
-- 更新 coding-agent-harness/planning/modules/<module-key>/module_plan.md。
+- 更新 {{paths.harnessRoot}}/planning/modules/<module-key>/module_plan.md。
 - 写 review.md，或记录 review skipped-with-reason。需要人工确认审查完成时，必须通过本地 dashboard workbench，或由 coordinator 执行 `harness review-confirm`；存在开放 P0/P1/P2 finding 时不得确认。
 - 步骤完成时写 walkthrough，并包含 Lessons 反思。
 - Coordinator pass 在任务关闭时更新 Closeout Index 和 Lessons 检查。

package/templates-zh-CN/planning/optional/slices/_slice-template/brief.md

@@ -1,14 +1,29 @@
 # 切片简报
 
-## 切片 ID
+## 一句话结果
 
-SL-001
+用一句话说明这个切片完成后会产生什么具体结果。
 
-## 所属阶段（Parent Phase）
+## 完成后能得到什么
+
+用 100-300 字说明这个切片完成后，父任务、coordinator 或下游 worker 能得到什么。
+说明它能解锁哪个决策、集成、验证或下一切片。实现细节保留在切片计划或证据文件里。
+
+## 交付物
+
+- 可见产物：
+- 修改位置：
+- 验证证据：
+
+## 第一眼应该看什么
+
+写明人应该先看哪些切片证据、改动文件或交接说明。
+
+## 身份
 
 | 父阶段 ID | 依赖 | 状态 | 负责人 / 交接 |
 | --- | --- | --- | --- |
-| PH-01 | none | planned | coordinator |
+| PH-01 | none | planned | [owner] |
 
 ## 目标
 
@@ -20,16 +35,18 @@ SL-001
 - 明确排除：[不属于本切片的内容]
 - 共享协调：[涉及共享文件时写 owner、锁和 merge 顺序；如无写“无”]
 
-## 输入（Inputs）
+## 完成判断
 
-- [引用 `references/INDEX.md`、`artifacts/INDEX.md`、任务计划或上游切片 ID]
+- [ ] 一句话结果已经实现。
+- [ ] 必需证据已经登记。
+- [ ] 共享更新或残余风险已经交给 coordinator。
 
 ## 必需证据
 
-- [ ] [该切片关闭前必须提供的命令、diff、截图、review 或报告]
+| 证据 | 命令 / 路径 | 必需 |
+| --- | --- | --- |
+| [check] | [command or path] | yes |
 
-## 关闭条件
+## 交接要求
 
-- [ ] 范围内工作完成。
-- [ ] 必需证据已登记到 `evidence.md`。
-- [ ] 如需审查，`review.md` 无 open blocking finding。
+切片 owner 必须报告变更文件、已运行检查、残余风险，以及需要 coordinator 处理的共享更新。

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

@@ -93,7 +93,7 @@ Scanner 会根据必需文件、章节、证据和这个严格提交块派生 `m
 | 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 或作为只读审计历史保留。 |
+| Soft-deleted / Superseded | yes / no | 任务有 tombstone、superseded-by 或 archive 状态；duplicate / abandoned 等语义写在 `Reason`。 | reopen 或作为只读审计历史保留。 |
 
 ## 后续路由（Follow-Up Routing）
 

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

@@ -7,7 +7,7 @@
 审查报告默认写入：
 
 ```text
-coding-agent-harness/planning/tasks/<YYYY-MM-DD-任务名>/review.md
+{{paths.harnessRoot}}/planning/tasks/<YYYY-MM-DD-任务名>/review.md
 ```
 
 审查路由由 `review-routing-standard.md` 决定；本文件只规定审查报告怎么写、什么结论可以收口。

package/templates-zh-CN/reference/delivery-operating-model-standard.md

@@ -21,8 +21,8 @@
 | 层级 | 负责人 | 主要产物 | 规则 |
 | --- | --- | --- | --- |
 | 路线图 | product / tech lead / owner | roadmap、release plan | 只放阶段目标，不替代任务计划。 |
-| 功能块 | coordinator / feature lead | `coding-agent-harness/planning/Delivery-SSoT.md` 或功能 SSoT | 标明 owner、依赖、集成顺序。 |
-| 任务 | task owner | `coding-agent-harness/planning/tasks/<task>/task_plan.md` | 每个任务有目标、范围、证据和 stop condition。 |
+| 功能块 | coordinator / feature lead | `{{paths.harnessRoot}}/planning/Delivery-SSoT.md` 或功能 SSoT | 标明 owner、依赖、集成顺序。 |
+| 任务 | task owner | `{{paths.harnessRoot}}/planning/tasks/<task>/task_plan.md` | 每个任务有目标、范围、证据和 stop condition。 |
 | 审查 | reviewer / subagent / human | `review.md` 或 PR review | 按审查路由执行，不只留在聊天里。 |
 | 集成 | coordinator / maintainer | PR、integration branch、release branch | 由集成 owner 决定 merge 顺序和最终 gates。 |
 
@@ -40,7 +40,7 @@
 
 ## 交付单一事实源要求
 
-以下任一条件成立时，必须维护 `coding-agent-harness/planning/Delivery-SSoT.md`：
+以下任一条件成立时，必须维护 `{{paths.harnessRoot}}/planning/Delivery-SSoT.md`：
 
 - 多人或多 agent 并行开发。
 - 多仓或前后端分离协作。

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

@@ -2,21 +2,21 @@
 
 ## 职责
 
-本标准定义 `coding-agent-harness/` 文档库的目录、命名、归档和引用规则。文档库服务于 agent 执行，不是资料堆；每个文件都应有明确职责、当前事实和可追溯证据。
+本标准定义 `{{paths.harnessRoot}}/` 文档库的目录、命名、归档和引用规则。文档库服务于 agent 执行，不是资料堆；每个文件都应有明确职责、当前事实和可追溯证据。
 
 ## 目录职责
 
 | 位置 | 职责 |
 | --- | --- |
-| `coding-agent-harness/governance/generated/Harness-Ledger.md` | 全局上下文维护总账，记录非平凡任务是否完成计划、审查、回归、Lessons 和收口回写。 |
-| `coding-agent-harness/governance/` | promoted lesson 详情、治理记录、归档。 |
-| `coding-agent-harness/context/architecture/` | ADR、架构设计、接口决策、关键技术方案。 |
-| `coding-agent-harness/context/development/` | 本地开发、代码地图、外部服务开发上下文、mock/stub、跨仓调试。 |
-| `coding-agent-harness/governance/regression/` | Regression SSoT、Cadence Ledger、测试策略和回归证据索引。 |
-| `coding-agent-harness/planning/` | Delivery SSoT、Module Registry、任务目录、模块计划。 |
-| `coding-agent-harness/planning/tasks/` | 每个任务一个目录，包含 task plan、progress、findings、review。 |
-| `coding-agent-harness/planning/tasks/<task>/` | 收口记录和 Closeout Index。 |
-| `coding-agent-harness/governance/standards/` | agent 按需加载的标准文件，控制行为而不是记录流水账。 |
+| `{{paths.harnessRoot}}/governance/generated/Harness-Ledger.md` | 全局上下文维护总账，记录非平凡任务是否完成计划、审查、回归、Lessons 和收口回写。 |
+| `{{paths.harnessRoot}}/governance/` | promoted lesson 详情、治理记录、归档。 |
+| `{{paths.harnessRoot}}/context/architecture/` | ADR、架构设计、接口决策、关键技术方案。 |
+| `{{paths.harnessRoot}}/context/development/` | 本地开发、代码地图、外部服务开发上下文、mock/stub、跨仓调试。 |
+| `{{paths.harnessRoot}}/governance/regression/` | Regression SSoT、Cadence Ledger、测试策略和回归证据索引。 |
+| `{{paths.harnessRoot}}/planning/` | Delivery SSoT、Module Registry、任务目录、模块计划。 |
+| `{{paths.harnessRoot}}/planning/tasks/` | 每个任务一个目录，包含 task plan、progress、findings、review。 |
+| `{{paths.harnessRoot}}/planning/tasks/<task>/` | 收口记录和 Closeout Index。 |
+| `{{paths.harnessRoot}}/governance/standards/` | agent 按需加载的标准文件，控制行为而不是记录流水账。 |
 | `docs/99-TMP/` | 临时材料，定期清理，不作为长期事实来源。 |
 
 ## 03 / 04 / 06 路由规则
@@ -29,16 +29,16 @@
 
 | 目录 | 负责 | 不负责 | 必需 schema 信号 |
 | --- | --- | --- | --- |
-| `coding-agent-harness/context/architecture/` | 系统结构、服务职责、owner、service catalog、critical flows、ADR | endpoint payload、mock 指南、任务日志 | `Context Doc Type`, `Source Evidence`, `Last Verified`, `Confidence` |
-| `coding-agent-harness/context/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` |
-| `coding-agent-harness/context/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` |
+| `{{paths.harnessRoot}}/context/architecture/` | 系统结构、服务职责、owner、service catalog、critical flows、ADR | endpoint payload、mock 指南、任务日志 | `Context Doc Type`, `Source Evidence`, `Last Verified`, `Confidence` |
+| `{{paths.harnessRoot}}/context/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` |
+| `{{paths.harnessRoot}}/context/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` |
 
 具体分工：
 
-- `coding-agent-harness/context/architecture/service-catalog.md` 只写服务摘要和链接。
-- `coding-agent-harness/context/integrations/<service>-api-contract.md` 才写 payload、auth、errors、contract tests。
-- `coding-agent-harness/context/development/external-context/<service>.md` 写 mock/stub、不安全假设和调试说明。
-- `coding-agent-harness/context/development/external-source-packs/` 只写外部资料索引、digest 和投影状态；最终事实必须回写到 `context/{architecture,development,integrations}`。
+- `{{paths.harnessRoot}}/context/architecture/service-catalog.md` 只写服务摘要和链接。
+- `{{paths.harnessRoot}}/context/integrations/<service>-api-contract.md` 才写 payload、auth、errors、contract tests。
+- `{{paths.harnessRoot}}/context/development/external-context/<service>.md` 写 mock/stub、不安全假设和调试说明。
+- `{{paths.harnessRoot}}/context/development/external-source-packs/` 只写外部资料索引、digest 和投影状态；最终事实必须回写到 `context/{architecture,development,integrations}`。
 
 ## 外部资料摄取规则
 
@@ -54,7 +54,7 @@ Inventory -> Classify -> Sanitize -> Digest -> Project -> Verify -> Residual
 
 ## 命名规则
 
-- 目录可使用编号前缀，例如 `coding-agent-harness/planning`、`coding-agent-harness/governance/standards`。
+- 目录可使用编号前缀，例如 `{{paths.harnessRoot}}/planning`、`{{paths.harnessRoot}}/governance/standards`。
 - 标准文件使用 kebab-case，例如 `testing-standard.md`。
 - 时序文档使用日期前缀，例如 `2026-05-19-runtime-cleanup-walkthrough.md`。
 - 模板目录或模板文件用 `_` 前缀，例如 `_task-template/`。
@@ -64,15 +64,15 @@ Inventory -> Classify -> Sanitize -> Digest -> Project -> Verify -> Residual
 
 | 类型 | 推荐位置 | 要求 |
 | --- | --- | --- |
-| 任务计划 | `coding-agent-harness/planning/tasks/<task>/task_plan.md` | 写目标、范围、证据、stop condition。 |
-| 进度记录 | `coding-agent-harness/planning/tasks/<task>/progress.md` | 记录阶段状态、阻塞、决策和验证。 |
-| 研究发现 | `coding-agent-harness/planning/tasks/<task>/findings.md` | 记录调查证据，不替代审查报告。 |
-| 审查报告 | `coding-agent-harness/planning/tasks/<task>/review.md` | 记录 Confidence Challenge、material findings、evidence、residual。 |
-| 收口记录 | `coding-agent-harness/planning/tasks/<task>/<date>-<name>.md` | 给下一轮 agent 的可追溯交接。 |
-| Closeout Index | `coding-agent-harness/governance/generated/Closeout-Index.md` | closed task 的 walkthrough 路径和跳过原因索引。 |
-| Regression SSoT | `coding-agent-harness/governance/regression/Regression-SSoT.md` | 管回归 surface、evidence depth、residual。 |
+| 任务计划 | `{{paths.harnessRoot}}/planning/tasks/<task>/task_plan.md` | 写目标、范围、证据、stop condition。 |
+| 进度记录 | `{{paths.harnessRoot}}/planning/tasks/<task>/progress.md` | 记录阶段状态、阻塞、决策和验证。 |
+| 研究发现 | `{{paths.harnessRoot}}/planning/tasks/<task>/findings.md` | 记录调查证据，不替代审查报告。 |
+| 审查报告 | `{{paths.harnessRoot}}/planning/tasks/<task>/review.md` | 记录 Confidence Challenge、material findings、evidence、residual。 |
+| 收口记录 | `{{paths.harnessRoot}}/planning/tasks/<task>/<date>-<name>.md` | 给下一轮 agent 的可追溯交接。 |
+| Closeout Index | `{{paths.harnessRoot}}/governance/generated/Closeout-Index.md` | closed task 的 walkthrough 路径和跳过原因索引。 |
+| Regression SSoT | `{{paths.harnessRoot}}/governance/regression/Regression-SSoT.md` | 管回归 surface、evidence depth、residual。 |
 | Harness Ledger | `Harness-Ledger.md` | 管上下文维护合规性，不复制业务事实。 |
-| Reference 标准 | `coding-agent-harness/governance/standards/*.md` | 管长期规则，避免写成任务日志。 |
+| Reference 标准 | `{{paths.harnessRoot}}/governance/standards/*.md` | 管长期规则，避免写成任务日志。 |
 
 ## 归档规则
 
@@ -81,7 +81,7 @@ Inventory -> Classify -> Sanitize -> Digest -> Project -> Verify -> Residual
 - 归档不删除原始 ID，不破坏 task plan、walkthrough、SSoT、Ledger 之间的引用。
 - 活跃文件必须留下归档指针，说明历史记录在哪里。
 - `review.md` 留在对应任务目录，不移动到 walkthrough 或根目录。
-- `coding-agent-harness/governance/generated/Harness-Ledger.md` 由 CLI 生成，不应手写。
+- `{{paths.harnessRoot}}/governance/generated/Harness-Ledger.md` 由 CLI 生成，不应手写。
 - `docs/99-TMP/` 下超过 7 天未更新的文件应清理或迁移到正式位置。
 
 ## 写作原则

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

@@ -10,7 +10,7 @@
 2. 读取功能 SSoT 或 Delivery SSoT，确认任务状态、owner 和依赖。
 3. 读取 `task_plan.md`，确认目标、范围、证据、stop condition 和允许修改的路径。
 4. 读取 `delivery-operating-model-standard.md`，判断本轮是 solo、team、split-repo、program、waterfall 还是 kanban 交付形态。
-5. 多人、多 agent、多仓、共享文件或阶段交付任务必须更新 `coding-agent-harness/planning/Delivery-SSoT.md`。
+5. 多人、多 agent、多仓、共享文件或阶段交付任务必须更新 `{{paths.harnessRoot}}/planning/Delivery-SSoT.md`。
 6. 判断是否属于长程任务；如属于，按 `long-running-task-standard.md` 补齐合同。
 7. 判断是否需要对抗性审查；如需要，按 `adversarial-review-standard.md` 创建或更新 `review.md`。
 8. planned task 默认需要 closeout review；先读取 `review-routing-standard.md`。
@@ -54,11 +54,21 @@
 
 Preset 包不能新增或替换根级 base scaffold 文档。Preset 只能追加固定基础文档的受控 section，或把隔离资源写入 `references/**` 和 `artifacts/**`。resource rows 只能登记在 `references/INDEX.md` 和 `artifacts/INDEX.md`；根 `INDEX.md` 最多显示系统渲染的 preset summary 字段。
 
+## 模块包边界
+
+已注册模块写在根 `harness.yaml` 的 `modules.items`。生成的
+`planning/modules/Module-Registry.md` 是阅读视图，不是可编辑事实源。
+
+使用 `harness module register` 或 `harness module scaffold`，不要手工复制模块文件。
+模块根目录默认只拥有 `brief.md` 和 `module_plan.md`。`execution_strategy.md`、
+`visual_map.md`、`review.md`、`walkthrough.md` 等执行合同属于具体任务目录，包括
+`planning/modules/<key>/tasks/<task-id>/`。
+
 ## 完成任务后
 
 1. 按 `testing-standard.md` 和 Regression SSoT 运行对应检查。
 2. 确认 repo governance、CI/CD required checks 已执行、更新或 residualized。
-3. 更新功能 SSoT；多人、多仓、多模块任务同时更新 Delivery SSoT 或 Module Registry。
+3. 更新功能 SSoT；多人、多仓、多模块任务同时更新 Delivery SSoT，模块注册变化通过 `harness.yaml` 的 `modules.items` 并重新生成 Module Registry 视图。
 4. 更新 Regression SSoT 和 Cadence Ledger（如适用）。
 5. 确认 `review.md` 没有 open P0/P1 finding；material P2 已修复或写为 `accepted-risk` 并路由。
 6. planned task 必须完成 closeout review，或写明 `skipped-with-reason`。

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

@@ -10,7 +10,7 @@
 外部原始资料 -> source pack 索引 -> digest 摘要 -> context/{architecture,development,integrations} 执行投影
 ```
 
-`context/architecture`、`context/development`、`context/integrations` 只保存已经提炼并可用于执行的事实。外部团队丢来的原文、长文档、截图、聊天记录、导出包和历史资料先进入 `coding-agent-harness/context/development/external-source-packs/`，不能直接污染执行文档。
+`context/architecture`、`context/development`、`context/integrations` 只保存已经提炼并可用于执行的事实。外部团队丢来的原文、长文档、截图、聊天记录、导出包和历史资料先进入 `{{paths.harnessRoot}}/context/development/external-source-packs/`，不能直接污染执行文档。
 
 ## 何时询问用户
 
@@ -33,14 +33,14 @@
 | 场景 | 存储方式 |
 | --- | --- |
 | 只有 1-4 个稳定外部文档 | 不必建独立 source pack；在对应 `context/{architecture,development,integrations}` 的 `Source Evidence` 中链接即可 |
-| 外部资料超过 5 份、跨多个主题、或会持续增长 | 创建 `coding-agent-harness/context/development/external-source-packs/<source-key>/` |
+| 外部资料超过 5 份、跨多个主题、或会持续增长 | 创建 `{{paths.harnessRoot}}/context/development/external-source-packs/<source-key>/` |
 | 资料含敏感信息、密钥、客户数据或不能进仓 | 不复制原文；在 source pack README 记录外部路径、owner、访问条件和摘要 |
 | 资料是可公开或可入仓的原始文档 | 可放 `raw/`，但仍要经过 digest 后才能投影到执行文档 |
 
 建议结构：
 
 ```text
-coding-agent-harness/context/development/external-source-packs/<source-key>/
+{{paths.harnessRoot}}/context/development/external-source-packs/<source-key>/
 ├── README.md              # 资料索引和投影状态
 ├── digests/               # 每份或每组资料的摘要
 ├── raw/                   # 可入仓原文；禁止放密钥、隐私或客户数据
@@ -49,10 +49,10 @@ coding-agent-harness/context/development/external-source-packs/<source-key>/
 
 不要为每个微服务复制一套完整 `context/{architecture,development,integrations}` 目录。source pack 是资料入口；稳定执行入口仍然是：
 
-- `coding-agent-harness/context/architecture/service-catalog.md`
-- `coding-agent-harness/context/architecture/services/<service-key>.md`
-- `coding-agent-harness/context/development/external-context/<service-key>.md`
-- `coding-agent-harness/context/integrations/<contract>.md`
+- `{{paths.harnessRoot}}/context/architecture/service-catalog.md`
+- `{{paths.harnessRoot}}/context/architecture/services/<service-key>.md`
+- `{{paths.harnessRoot}}/context/development/external-context/<service-key>.md`
+- `{{paths.harnessRoot}}/context/integrations/<contract>.md`
 
 ## 摄取流程
 
@@ -68,9 +68,9 @@ coding-agent-harness/context/development/external-source-packs/<source-key>/
 
 | 资料内容 | 投影位置 |
 | --- | --- |
-| 服务职责、上下游、owner、数据归属、系统拓扑 | `coding-agent-harness/context/architecture/service-catalog.md` 或 `services/<service-key>.md` |
-| 本仓开发时如何 mock、stub、启动、联调、排查 | `coding-agent-harness/context/development/external-context/<service-key>.md` |
-| endpoint、payload、auth、error、event、webhook、SDK、contract test | `coding-agent-harness/context/integrations/<contract>.md` |
+| 服务职责、上下游、owner、数据归属、系统拓扑 | `{{paths.harnessRoot}}/context/architecture/service-catalog.md` 或 `services/<service-key>.md` |
+| 本仓开发时如何 mock、stub、启动、联调、排查 | `{{paths.harnessRoot}}/context/development/external-context/<service-key>.md` |
+| endpoint、payload、auth、error、event、webhook、SDK、contract test | `{{paths.harnessRoot}}/context/integrations/<contract>.md` |
 | 仍未确认、来源冲突、过期或只作为背景参考 | 留在 source pack README / digest，不进入执行文档 |
 
 ## 禁止事项

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

@@ -2,10 +2,10 @@
 
 ## 职责
 
-Harness Ledger 是 `coding-agent-harness/` 骨架的全局上下文维护总账，固定位置为：
+Harness Ledger 是 `{{paths.harnessRoot}}/` 骨架的全局上下文维护总账，固定位置为：
 
 ```text
-coding-agent-harness/governance/generated/Harness-Ledger.md
+{{paths.harnessRoot}}/governance/generated/Harness-Ledger.md
 ```
 
 它记录每个非平凡任务是否完成了 task plan、progress、review、功能 SSoT、Delivery SSoT、Regression SSoT、lesson candidates/detail docs、walkthrough、Closeout Index、reference/template 和 CI/CD 治理回写。它不复制业务事实，只记录上下文维护是否合规。
@@ -88,7 +88,7 @@ coding-agent-harness/governance/generated/Harness-Ledger.md
 活跃表保留最近 50 条。更早的 `closed` 或 `superseded` 条目按季度归档：
 
 ```text
-coding-agent-harness/governance/archive/Harness-Ledger-archive-YYYY-QN.md
+{{paths.harnessRoot}}/governance/archive/Harness-Ledger-archive-YYYY-QN.md
 ```
 
 归档后，活跃表必须留下归档位置说明。

package/templates-zh-CN/reference/regression-ssot-governance.md

@@ -7,7 +7,7 @@ Regression SSoT 是项目回归控制塔，管理所有 regression surface 的 g
 默认位置：
 
 ```text
-coding-agent-harness/governance/regression/Regression-SSoT.md
+{{paths.harnessRoot}}/governance/regression/Regression-SSoT.md
 ```
 
 ## 维护时机
@@ -61,7 +61,7 @@ coding-agent-harness/governance/regression/Regression-SSoT.md
 
 ## 废弃回归门禁
 
-1. 将 gate 移入 `coding-agent-harness/governance/regression/_archive/Regression-SSoT-archive-YYYY-QN.md`。
+1. 将 gate 移入 `{{paths.harnessRoot}}/governance/regression/_archive/Regression-SSoT-archive-YYYY-QN.md`。
 2. 写明废弃原因、替代 gate 和最后状态。
 3. 同步更新 Cadence Ledger。
 4. 在 walkthrough 和 Harness Ledger 记录本次治理变化。

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

@@ -33,7 +33,7 @@
 | --- | --- |
 | 是否必须 PR | yes / no / local-only |
 | PR 标题格式 | 通常与 commit 规范一致 |
-| PR 描述要求 | 遵守 `coding-agent-harness/governance/standards/pull-request-standard.md`；写清改动、原因、版本影响、验证、residual、关联 task / SSoT / review |
+| PR 描述要求 | 遵守 `{{paths.harnessRoot}}/governance/standards/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 |

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

@@ -42,6 +42,9 @@ Worker 必须走 `worktree-standard.md`，并先在 `execution_strategy.md` 记
 - 同一任务、同一范围、同一 worktree/branch 内可复用该授权；范围变化时重新请求授权。
 - 如果 worker subagent 对任务有明显帮助但尚未授权，coordinator 必须用白话主动向用户申请一次授权；可以直接说 worker subagent，但不要等用户知道或提醒使用 subagent。
 - 如果独立切片已经明显但精确文件路径还不清楚，先确认文件路径，然后在 implementation 前立刻申请独立执行助手授权。
+
+Subagent 授权是任务级合同。不要寻找模块根目录的 `execution_strategy.md`；模块根目录只使用
+`brief.md` 和 `module_plan.md`，worker 授权属于具体任务目录。
 - 一旦 `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

@@ -7,13 +7,13 @@
 默认位置：
 
 ```text
-coding-agent-harness/planning/tasks/<task>/walkthrough.md
+{{paths.harnessRoot}}/planning/tasks/<task>/walkthrough.md
 ```
 
 Closeout Index 固定位置：
 
 ```text
-coding-agent-harness/governance/generated/Closeout-Index.md
+{{paths.harnessRoot}}/governance/generated/Closeout-Index.md
 ```
 
 ## 何时必须写

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

@@ -42,7 +42,7 @@ worktree 目录推荐：
 - `fix/`：缺陷修复。
 - `refactor/`：重构。
 - `test/`：测试相关。
-- `coding-agent-harness/`：文档相关。
+- `{{paths.harnessRoot}}/`：文档相关。
 - `codex/`：agent 任务分支。
 
 示例：