coding-agent-harness 1.0.1 → 1.0.2

package/templates-zh-CN/development/external-source-packs/README.md

@@ -0,0 +1,24 @@
+# 外部资料包索引 / External Source Packs
+
+Context Doc Type: external-source-pack-registry
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Purpose
+
+这个目录只承载外部资料的摄取、索引和摘要。稳定事实必须投影到 `03-ARCHITECTURE`、`04-DEVELOPMENT/external-context` 或 `06-INTEGRATIONS` 后才算进入 Harness 执行上下文。
+
+先读 `docs/11-REFERENCE/external-source-intake-standard.md`，再新增资料包。
+
+## Source Packs
+
+| Source Key | External Project / Service | Raw Storage Mode | Source Count | Digest Status | Projected To 03/04/06 | Owner | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Placement Rule
+
+- 资料量小于 5 份时，优先在 `03/04/06` 的 `Source Evidence` 中引用，不必建资料包。
+- 资料很多、跨多个主题或会持续增长时，创建 `<source-key>/README.md` 和 `digests/`。
+- `raw/` 只能放允许入仓、无密钥、无隐私、无客户数据的原始材料。
+- 不能入仓的资料只记录外部路径、owner、访问条件和 digest。

package/templates-zh-CN/development/external-source-packs/digest-template.md

@@ -0,0 +1,28 @@
+# 外部资料摘要：<source-id> / External Source Digest: <source-id>
+
+Context Doc Type: external-source-digest
+Source Pack: <source-key>
+Original Location: <path-or-url-or-owner>
+Digest Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Source Summary
+
+[用 5-10 行说明原始资料是什么、覆盖范围、可信度和更新时间。]
+
+## Extracted Facts
+
+| Fact ID | Fact | Category | Project To | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| F-001 | [可验证事实] | architecture / development / integration / security / operations / product / unknown | `docs/...` 或 hold | <source-id> | unknown | low |
+
+## Questions / Unsafe Assumptions
+
+| ID | Question Or Assumption | Why It Matters | Owner | Status |
+| --- | --- | --- | --- | --- |
+
+## Projection Status
+
+| Target Doc | Action | Status | Evidence |
+| --- | --- | --- | --- |

package/templates-zh-CN/development/local-setup.md

@@ -0,0 +1,16 @@
+# 本地启动 / Local Setup
+
+Context Doc Type: local-setup
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Commands
+
+| Task | Command | Expected Result | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+
+## Environment
+
+| Variable | Required | Purpose | Source Evidence |
+| --- | --- | --- | --- |

package/templates-zh-CN/development/stubs-and-mocks.md

@@ -0,0 +1,11 @@
+# Stub 与 Mock / Stubs and Mocks
+
+Context Doc Type: stubs-and-mocks
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Available Stubs
+
+| External Service | Scenario | Stub Path | How To Run | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- |

package/templates-zh-CN/integrations/README.md

@@ -0,0 +1,42 @@
+# 接口契约 / Integrations
+
+Context Doc Type: integration-index
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Purpose
+
+这个文件夹只放具体接口契约：API、event、webhook、SDK、第三方集成、auth、payload、error 和 contract tests。
+
+Keep the English field names and section headings because CLI checks rely on them.
+
+## Boundary
+
+- 服务拓扑和职责归属放 `docs/03-ARCHITECTURE/`。
+- 开发 mock 和调试说明放 `docs/04-DEVELOPMENT/`。
+- endpoint、payload、error、auth、event、webhook、SDK 契约放这里。
+
+## Structure Contract
+
+| 文件 / 路径 | 必须维护的事实 | 写入规则 |
+| --- | --- | --- |
+| `<service-key>-api.md` | API endpoint、auth、payload、error、contract test | 从 `api-contract.md` 创建 |
+| `<event-name>-event.md` | event producer/consumer、schema、delivery、retry | 从 `event-contract.md` 创建 |
+| `<webhook-name>-webhook.md` | webhook source、target、signature、payload、retry | 从 `webhook-contract.md` 创建 |
+| `third-party/<vendor-key>.md` | 第三方平台、账号/权限边界、SDK 使用、限制 | 从 `third-party/vendor-template.md` 创建 |
+
+## Contract Rule
+
+每个接口契约必须是独立文件，并链接回对应服务：
+
+- 服务职责和上下游关系：`docs/03-ARCHITECTURE/service-catalog.md` 或 `services/<service-key>.md`
+- 本地 mock / stub / debug：`docs/04-DEVELOPMENT/external-context/<service-key>.md`
+- 具体 payload、auth、error、contract test：本文件夹
+
+不要在一个“接口说明”大文档里混写多个服务。多个微服务就维护多个契约文件；README 里的 Contract Index 负责让人和 Agent 快速定位。
+
+## Contract Index
+
+| Contract | Type | Producer | Consumer | Service Profile | Development Context | Contract Tests | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |

package/templates-zh-CN/integrations/api-contract.md

@@ -0,0 +1,42 @@
+# API 契约：<service-or-api> / API Contract: <service-or-api>
+
+Context Doc Type: api-contract
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+API
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-context/<service-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Auth
+
+[认证和授权要求。不要写入真实密钥。]
+
+## Endpoints
+
+| Method | Path | Purpose | Request Payload | Response Payload | Errors | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Payload
+
+[请求/响应 schema，或指向 schema 的路径。]
+
+## Errors
+
+[错误码、重试规则、用户可见行为。]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+本文件只写一个 API 契约。服务职责放 `03-ARCHITECTURE`，本地 mock/stub/debug 放 `04-DEVELOPMENT`。

package/templates-zh-CN/integrations/event-contract.md

@@ -0,0 +1,46 @@
+# 事件契约：<event-name> / Event Contract: <event-name>
+
+Context Doc Type: event-contract
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+Event
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-context/<service-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Topic / Channel
+
+[Queue、topic、stream 或 bus。]
+
+## Auth
+
+[生产者/消费者权限、签名或访问控制。没有也要写 N/A 和证据。]
+
+## Payload
+
+[事件 schema 或 schema 路径。]
+
+## Producers and Consumers
+
+| Role | Service | Responsibility | Source Evidence |
+| --- | --- | --- | --- |
+
+## Errors
+
+[Dead-letter、retry、兼容性策略。]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+本文件只写一个 event 契约。服务职责放 `03-ARCHITECTURE`，本地 mock/stub/debug 放 `04-DEVELOPMENT`。

package/templates-zh-CN/integrations/third-party/vendor-template.md

@@ -0,0 +1,42 @@
+# 第三方集成：<vendor> / Third-Party Integration: <vendor>
+
+Context Doc Type: third-party-integration
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+Third-party service
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<vendor-key>.md` | `docs/04-DEVELOPMENT/external-context/<vendor-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Auth
+
+[凭证与权限模型。不要写入真实密钥。]
+
+## API / SDK Surface
+
+| Surface | Purpose | Contract Link | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+
+## Payload
+
+[重要请求/响应体，或相关 schema 路径。]
+
+## Errors
+
+[供应商错误、额度限制、重试和降级策略。]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+本文件只写一个第三方集成。账号/权限/SDK/限制放这里；业务职责和系统拓扑放 `03-ARCHITECTURE`。

package/templates-zh-CN/integrations/webhook-contract.md

@@ -0,0 +1,41 @@
+# Webhook 契约：<webhook-name> / Webhook Contract: <webhook-name>
+
+Context Doc Type: webhook-contract
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+Webhook
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-context/<service-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Auth
+
+[签名、token、IP allowlist 或其他认证方式。不要写入真实密钥。]
+
+## Payload
+
+[Webhook body schema 或 schema 路径。]
+
+## Source Evidence
+
+[代码、供应商文档、负责人说明或发现命令。]
+
+## Errors
+
+[重试、超时、幂等行为。]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+本文件只写一个 webhook 契约。服务职责放 `03-ARCHITECTURE`，本地 mock/stub/debug 放 `04-DEVELOPMENT`。

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

@@ -0,0 +1,32 @@
+# {{TASK_TITLE}}
+
+## Brief
+
+## Task ID
+
+`{{TASK_ID}}`
+
+## 创建日期
+
+{{DATE}}
+
+## 目标结果
+
+说明这个任务完成后，用户或项目能直接看到的结果。
+
+## 边界
+
+- 范围内：本任务允许修改的文件、行为、文档或验证内容。
+- 范围外：不能顺手塞进来的工作。
+- 停止条件：遇到不确定性、风险或缺少权限时，必须回到 coordinator 或用户确认。
+
+## 执行合同
+
+- Owner：coordinator
+- 生命周期状态：未开始
+- 必需文件：`task_plan.md`、`execution_strategy.md`、`visual_map.md`、`progress.md`、`findings.md`、`review.md`
+- 完成条件：验证证据必须记录到 `progress.md`
+
+## 第一步
+
+开始实现前，把这里替换成第一个具体动作。

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

@@ -0,0 +1,58 @@
+# {{TASK_TITLE}} - 教训候选
+
+本文件是任务本地 lesson candidate queue。它不是 Lessons SSoT；只有人工审查确认值得沉淀后，才进入治理 promotion。
+
+## Candidate Status
+
+| Field | Value |
+| --- | --- |
+| Schema version | lesson-candidate-v1 |
+| Task-level status | pending-review |
+| Review gate | candidate-file-present |
+| Review decision | pending-human-review |
+| Promotion state | not-promoted |
+| Closeout token | pending |
+| Source task | {{TASK_ID}} |
+| Owner | coordinator |
+| Last updated | {{DATE}} |
+
+## Schema
+
+允许的任务级状态：
+
+- `missing`：候选文件不存在。
+- `pending-review`：候选文件存在，但人工判定还没完成。
+- `no-candidate-accepted`：人工接受本任务没有可复用候选的理由。
+- `needs-promotion`：至少一个候选已排队等待治理沉淀。
+- `promoted`：所有接受的候选都已写入 Lessons SSoT。
+- `rejected`：所有候选都已带理由拒绝或归档。
+
+允许的行级状态：
+
+- `ready-for-review`：agent 认为这个候选可能有复用价值。
+- `needs-promotion`：人工标记这个候选值得沉淀。
+- `promoted`：维护 CLI 已把候选写入 Lessons SSoT。
+- `rejected`：人工带理由拒绝这个候选。
+
+聚合规则：
+
+- 任意 `ready-for-review` 行会让任务级状态保持 `pending-review`。
+- 任意 `needs-promotion` 行会让任务级状态变成 `needs-promotion`，除非仍有 `ready-for-review` 行。
+- 全部行都是 `promoted` 时，任务级状态为 `promoted`。
+- 全部行都是 `rejected` 时，任务级状态为 `rejected`。
+- 没有候选的任务必须使用 `no-candidate-accepted`，并填写 `No-Candidate Reason`。
+
+## Candidates
+
+| ID | Row Status | Title | Why It Might Matter | Review Decision | Promotion Target |
+| --- | --- | --- | --- | --- | --- |
+
+## No-Candidate Reason
+
+尚未判定。只有人工审查接受本任务没有可复用候选时，才填写这里。
+
+## Promotion Notes
+
+- 如果人工审查认为候选值得沉淀，把对应行标记为 `needs-promotion`，并记录目标治理位置。
+- 如果人工审查拒绝候选，把对应行标记为 `rejected`，并在 review decision 中保留理由。
+- `needs-promotion` 不阻止任务 closeout，但必须继续出现在维护队列和收口记录里。

package/templates-zh-CN/planning/long-running-task-contract.md

@@ -113,6 +113,6 @@
 - [ ] `progress.md` / `findings.md` 更新
 - [ ] Harness Ledger 更新
 - [ ] 收口记录
-- [ ] Lessons 反思与检查（`checked-created` 或 `checked-none`）
+- [ ] Lessons 反思与检查：`lesson_candidates.md` 已进入 `no-candidate-accepted` / `needs-promotion` / `promoted` / `rejected`
 - [ ] PR / commit / 发布说明
 - [ ] 残余风险摘要

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

@@ -0,0 +1,25 @@
+# {{TASK_TITLE}} 模块
+
+## Brief
+
+## 模块 Key
+
+`{{TASK_ID}}`
+
+## 创建日期
+
+{{DATE}}
+
+## 模块职责
+
+说明这个模块负责什么，以及为什么需要独立管理。
+
+## 边界
+
+- 负责：本模块拥有的目录、服务或文档区域。
+- 共享面：需要 coordinator 同步的文件。
+- 不负责：相邻模块或未声明的全局文件。
+
+## 当前工作
+
+列出当前模块任务，或指向 `module_plan.md`。

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

@@ -17,12 +17,12 @@
 
 ## 执行与可视化文件
 
-模块级 `execution_strategy.md` 和 `visual_roadmap.md` 应放在本模块目录，与 `module_plan.md` 同级，不嵌入本文件。
+模块级 `execution_strategy.md` 和 `visual_map.md` 应放在本模块目录，与 `module_plan.md` 同级，不嵌入本文件。
 
 | 合同文件 | 是否必需 | 用途 |
 | --- | --- | --- |
 | `execution_strategy.md` | yes | 模块执行模式、写入边界、subagent 使用、全局同步 owner、验证深度 |
-| `visual_roadmap.md` | yes | 模块阶段图、状态、完成度、证据状态、阻塞风险 |
+| `visual_map.md` | yes | 模块图表集合、阶段图、状态、完成度、证据状态、阻塞风险 |
 
 旧模块目录可以保留历史嵌入式段落作为 fallback；新模块目录必须使用独立文件。
 

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

@@ -28,8 +28,8 @@
 - 编辑前检查 dirty state，不要 revert 无关改动。
 - 如果另一个活跃会话拥有该模块或必需共享文件，停止并记录冲突。
 - 代码编辑前，基于项目 planning 模板创建或更新 docs/09-PLANNING/MODULES/<module-key>/TASKS/<current-step>-<short-name>/task_plan.md，写清范围、验收、验证、分支/worktree 和共享协调。
-- 代码编辑前，确认模块任务目录含有 `execution_strategy.md` 与 `visual_roadmap.md`。如缺失，先补齐再实现。
-- 如果 docs/09-PLANNING/MODULES/<module-key>/ 缺少模块级 `execution_strategy.md` 或 `visual_roadmap.md`，在派发 worker 前补齐或更新。
+- 代码编辑前，确认模块任务目录含有 `execution_strategy.md` 与 `visual_map.md`。如缺失，先补齐再实现。
+- 如果 docs/09-PLANNING/MODULES/<module-key>/ 缺少模块级 `execution_strategy.md` 或 `visual_map.md`，在派发 worker 前补齐或更新。
 
 分支与工作树：
 - Worktree path: <worktree-path>.
@@ -55,8 +55,9 @@
 - 除非 coordinator 明确分配共享锁，worker session 不得更新 docs/09-PLANNING/Module-Registry.md、docs/Harness-Ledger.md、Closeout SSoT、Regression SSoT 或 Cadence Ledger。
 - 如果需要全局表更新，在 task_plan.md 或 progress.md 写 Coordinator 交接，并标记 `Global sync status: pending-coordinator-pass`。
 - 只有 coordinator pass 或明确的 shared-lock owner 可以更新 docs/09-PLANNING/Module-Registry.md。
+- 汇报状态时区分 `task.state`、`lifecycleState`、`reviewStatus` 和 `closeoutStatus`；`done` 只表示实现步骤完成，不等于 `closed`。
 - 更新 docs/09-PLANNING/MODULES/<module-key>/module_plan.md。
-- 写 review.md，或记录 review skipped-with-reason。
+- 写 review.md，或记录 review skipped-with-reason。需要人工确认审查完成时，必须通过本地 dashboard workbench，或由 coordinator 执行 `harness review-confirm`；存在开放 P0/P1/P2 finding 时不得确认。
 - 步骤完成时写 walkthrough，并包含 Lessons 反思。
 - Coordinator pass 在任务关闭时更新 Closeout SSoT 和 Lessons 检查。
 - Coordinator pass 在行为、测试、架构或流程改变时更新 Regression SSoT 和 Harness Ledger。

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

@@ -1,5 +1,7 @@
 # [任务名称]
 
+Task Contract: harness-task/v1
+
 ## 目标
 
 [用一句话说明本任务完成后应达到的状态。]
@@ -14,8 +16,11 @@
 
 | 预算 | 适用场景 | 必需结构 |
 | --- | --- | --- |
-| 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 | 常规功能、修复或文档改动 | 完整任务文件：计划、策略、图谱、进度、发现和按需审查 |
+| complex | 需要 L2/L3 证据、subagent/reviewer、外部参考、生成产物，或超过 5 个切片 | 完整任务文件，并只启用实际需要的可选索引 |
+
+选择预算：{{TASK_BUDGET}}
 
 可选子目录按触发条件创建，不作为默认脚手架：
 
@@ -40,12 +45,13 @@
 
 ## 执行与可视化文件
 
-`execution_strategy.md` 和 `visual_roadmap.md` 是本任务的同级合同文件，不嵌入 `task_plan.md`。这样 dashboard 和 checker 可以稳定读取。
+`execution_strategy.md` 和 `visual_map.md` 是本任务的同级合同文件，不嵌入 `task_plan.md`。这样 dashboard 和 checker 可以稳定读取。
 
 | 合同文件 | 是否必需 | 用途 |
 | --- | --- | --- |
 | `execution_strategy.md` | yes | 执行模式、subagent 使用、冲突控制、证据深度、交接规则 |
-| `visual_roadmap.md` | yes | Mermaid 路线图、阶段表、完成度、证据状态、阻塞风险 |
+| `visual_map.md` | yes | 图表集合：阶段图、可选架构/时序/数据流/状态图、完成度、证据状态、阻塞风险 |
+| `lesson_candidates.md` | standard/complex 必需 | 任务本地教训候选队列。人工审查确认前必须接受无候选、拒绝候选，或排队 promotion |
 | `review.md` | 按需 | 对抗性审查、release review、外部 reviewer 结论 |
 
 旧任务可以保留历史嵌入式段落作为 fallback；新任务必须使用独立文件。

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/docs-library-standard.md

@@ -11,6 +11,7 @@
 | `docs/Harness-Ledger.md` | 全局上下文维护总账，记录非平凡任务是否完成计划、审查、回归、Lessons 和收口回写。 |
 | `docs/01-GOVERNANCE/` | Lessons SSoT、经验详情、治理记录、归档。 |
 | `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,7 @@
 5. 可写 worker 必须在自己的 worktree 内实现、验证、提交，并 handoff branch、commit SHA、checks、residual。
 6. 遇到共享文件冲突，由 coordinator 或人工决定串行顺序。
 7. 遇到目标失效、权限阻塞、高风险决策或 stop condition 不适用，立即暂停并记录。
-8. 有意义地提交中间成果；commit message 应说明变更类型和范围。
+8. 主动提交已验证的、有意义的中间成果；commit message 应说明变更类型和范围。除非用户明确要求暂不提交，或检查失败 / diff 归属不清，否则不要把已完成切片长期留在未提交状态。
 
 ## 完成任务后
 
@@ -38,7 +38,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`，再由维护命令写 lesson 详情并更新 Lessons SSoT。没有可复用候选时记录 `no-candidate-accepted`；旧任务兼容可记录 `checked-none: <reason>`。
 9. 最后更新 Harness Ledger，因为它记录本轮上下文维护的最终状态。
 10. 完成 commit / PR / release note，并确认本任务工作区没有未解释的遗留改动。
 11. 如使用 worker，coordinator 集成 worker commit 后运行最终 gates，并记录 integration evidence。
@@ -71,6 +71,13 @@ PR 描述必须包含：
 - residual、owner 和不阻塞理由。
 - required checks、reviewer、merge method 是否满足 `repo-governance-standard.md`。
 
+## 主动提交规则
+
+- 每个已验证的、有意义的切片默认都要提交。
+- 提交前只 stage 本任务范围内文件，不能顺手带入无关 dirty 文件、私有文件或生成产物。
+- 如果用户明确说不要提交、检查失败、或 diff 归属还没厘清，必须把未提交原因写入 `progress.md` 或交接说明。
+- closeout 时必须列出相关 commit SHA；如果没有 commit，必须说明为什么这是安全的例外。
+
 ## 禁止事项
 
 - 非平凡任务跳过 task plan 直接实现。