coding-agent-harness 1.0.1 → 1.0.2

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

@@ -0,0 +1,82 @@
+# External Source Intake Standard
+
+## Purpose
+
+This standard defines how agents receive, filter, organize, and project large external documentation sets from other projects, microservice teams, or platform owners. The goal is executable context, not a document dump.
+
+## Core Model
+
+```text
+external source material -> source pack index -> digest -> 03/04/06 execution projection
+```
+
+`03-ARCHITECTURE`, `04-DEVELOPMENT`, and `06-INTEGRATIONS` only hold facts that have been distilled enough to guide work. Raw external files, long documents, screenshots, exported chats, diagrams, and historical packets first go through `docs/04-DEVELOPMENT/external-source-packs/`.
+
+## When To Ask The User
+
+During Diagnose / Decide, the agent must ask whether external source material exists when any of these signals appear:
+
+- The repository is part of a multi-repo, microservice, split frontend/backend, or platform system.
+- The code references external services, SDKs, API gateways, message queues, webhooks, contracts, schemas, or mocks.
+- The user mentions other repositories, upstream/downstream services, interface docs, business knowledge, or system-level design.
+- The agent cannot determine service responsibility, integration contracts, or local debugging behavior from the current repository alone.
+
+Recommended questions:
+
+1. Does this project depend on external services or other repositories?
+2. Do you have architecture docs, API docs, diagrams, meeting notes, source links, code paths, or exported packets from those teams?
+3. Can those materials be copied into this repository? If not, should the Harness store only local paths or URLs?
+4. Which sources are authoritative, and which are historical references only?
+
+## Storage Rules
+
+| Case | Storage |
+| --- | --- |
+| Only 1-4 stable external documents | No separate source pack is required; link them from `Source Evidence` in the relevant `03/04/06` docs |
+| More than 5 documents, multiple topics, or continuing growth | Create `docs/04-DEVELOPMENT/external-source-packs/<source-key>/` |
+| Material contains secrets, customer data, private links, or cannot be committed | Do not copy raw files; record external location, owner, access condition, and digest only |
+| Material is safe to commit | Raw files may go under `raw/`, but only digested facts may be projected into execution docs |
+
+Recommended structure:
+
+```text
+docs/04-DEVELOPMENT/external-source-packs/<source-key>/
+├── README.md              # source index and projection status
+├── digests/               # digest for each source or source group
+├── raw/                   # commit-safe raw material only
+└── raw-index.md           # path/URL/owner index when raw material cannot be committed
+```
+
+Do not replicate a full `03/04/06` tree for every microservice. The source pack is the intake layer. The stable execution entries remain:
+
+- `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`
+
+## Intake Flow
+
+1. **Inventory**: list sources, owners, dates, trust level, and commit eligibility.
+2. **Classify**: tag each source as architecture, development, integration, security, operations, product, or unknown.
+3. **Sanitize**: check for secrets, tokens, customer data, personal information, internal accounts, and private links; keep non-committable material as references only.
+4. **Digest**: extract facts, questions, unsafe assumptions, and evidence with the digest template.
+5. **Project**: move stable facts into `03/04/06`, then mark the source as projected in the source pack README.
+6. **Verify**: use code evidence, contract tests, owner confirmation, or runtime checks where feasible; update `Last Verified` and `Confidence`.
+7. **Residual**: keep unverified or conflicting facts in the source pack or in `Do Not Assume`; do not treat them as execution facts.
+
+## Projection Rules
+
+| Source Content | Projection Target |
+| --- | --- |
+| Service responsibility, upstream/downstream relationship, owner, data ownership, topology | `03-ARCHITECTURE/service-catalog.md` or `services/<service-key>.md` |
+| Local mocks, stubs, startup, debugging, cross-repo development behavior | `04-DEVELOPMENT/external-context/<service-key>.md` |
+| Endpoint, payload, auth, error, event, webhook, SDK, contract test | `06-INTEGRATIONS/<contract>.md` |
+| Unconfirmed, conflicting, stale, or background-only material | Keep in source pack README / digest; do not project into execution docs |
+
+## Prohibited
+
+- Do not copy large external document sets directly into `03-ARCHITECTURE`, `04-DEVELOPMENT`, or `06-INTEGRATIONS`.
+- Do not treat an external-source digest as verified fact without `Source Evidence`, `Last Verified`, and `Confidence`.
+- Do not keep long raw excerpts, chat logs, or meeting transcripts inside execution docs.
+- Do not commit secrets, production tokens, customer data, personal information, or non-public raw material.
+- Do not create one full directory tree per microservice for completeness; create source packs only for large external source sets.

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

@@ -13,6 +13,7 @@ Define when and how the Harness Ledger records durable changes to the agent oper
 5. Do not store secrets, personal data, large logs, or raw generated output in the ledger.
 6. If a lesson changes a reference standard, record both the lesson and the reference update.
 7. If no ledger update is needed, closeout should say why.
+8. New task closeout should route lesson review through `lesson_candidates.md`; record `checked-candidate:<LC-ID>`, `queued-promotion:<LC-ID>`, or `checked-created:<L-ID>` as the final lesson outcome.
 
 ## Required Artifacts
 

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

@@ -10,9 +10,10 @@ Define repository-level rules for branches, commits, pull requests, ownership, g
 2. Use task-scoped branches and worktrees for non-trivial changes, especially when multiple workers are active.
 3. Keep commits focused on the requested scope and avoid mixing unrelated cleanup with feature work.
 4. Generated files, caches, build output, local runtime state, and secrets must be ignored or stored in the approved location.
-5. Pull requests must describe intent, changed surfaces, checks run, checks not run, review status, and residual risk.
-6. Required checks and material review findings block merge unless an approved exception is recorded.
-7. Merge or release ownership must be explicit when several branches or workers contribute to the same outcome.
+5. Commit verified, meaningful slices proactively. Deferred commits require an explicit reason and owner.
+6. Pull requests must describe intent, changed surfaces, checks run, checks not run, review status, and residual risk.
+7. Required checks and material review findings block merge unless an approved exception is recorded.
+8. Merge or release ownership must be explicit when several branches or workers contribute to the same outcome.
 
 ## Required Checklist
 
@@ -20,10 +21,11 @@ Define repository-level rules for branches, commits, pull requests, ownership, g
 - Allowed and forbidden paths are respected.
 - Dirty worktree state was checked before edits.
 - Generated and private files are not accidentally staged.
+- Verified slices have commit SHAs, or deferred commit rationale is recorded.
 - PR summary includes evidence and residuals.
 - Review findings are resolved or explicitly accepted.
 - Merge strategy and rollback or revert path are understood.
 
 ## Closeout Expectations
 
-Repository closeout must list changed paths, confirm scope boundaries were honored, report git status relevant to the task, summarize checks, and identify unrelated dirty files left untouched.
+Repository closeout must list changed paths, confirm scope boundaries were honored, report git status relevant to the task, cite relevant commit SHAs or deferred-commit rationale, summarize checks, and identify unrelated dirty files left untouched.

package/templates/reference/walkthrough-standard.md

@@ -10,7 +10,7 @@ Define the closeout walkthrough that converts implementation work into durable p
 2. A walkthrough must explain what changed, why it changed, how it was verified, what review found, and what residual risk remains.
 3. Do not paste large raw logs. Link to evidence files, commands, PRs, screenshots, or CI runs.
 4. Material findings and their resolution must be visible.
-5. Lessons that change future behavior must be routed to the appropriate SSoT, reference standard, or Harness Ledger.
+5. Lessons that change future behavior must first be routed through `lesson_candidates.md`; accepted candidates are then routed to the appropriate SSoT, reference standard, or Harness Ledger.
 6. Walkthroughs must be written from the final integrated state, not from a single worker's partial view.
 7. If work is incomplete, the walkthrough must identify the next safe action and stop reason.
 
@@ -21,6 +21,7 @@ Define the closeout walkthrough that converts implementation work into durable p
 - Review summary with material findings and disposition.
 - Residual risk section.
 - Lesson or follow-up section.
+- Lesson candidate decision: `checked-candidate:<LC-ID>`, `queued-promotion:<LC-ID>`, `checked-created:<L-ID>`, or legacy `checked-none:<reason>`.
 - Links to updated SSoT, Regression SSoT, or Harness Ledger entries when applicable.
 
 ## Closeout Expectations

package/templates/walkthrough/walkthrough-template.md

@@ -49,8 +49,8 @@ One sentence describing what changed and why it matters.
 | --- | --- |
 | Did this reveal a reusable reference, workflow, or checker gap? | yes / no, reason |
 | Could a future agent repeat the same mistake? | yes / no, reason |
-| Was a lesson created or updated? | L-YYYY-MM-DD-001 or checked-none: reason |
-| Lessons detail doc | path or none |
+| Was a lesson candidate reviewed? | checked-candidate:LC-... / queued-promotion:LC-... / checked-created:L-YYYY-MM-DD-001 / legacy checked-none: reason |
+| Lessons detail doc | lesson_candidates.md, governance detail doc, or none |
 
 ## Closeout Links
 

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

@@ -1,92 +1,91 @@
 # [项目名称]
 
-> Agent 进入本仓库时先读这个文件。它负责说明项目边界、工作顺序和文档入口，不承载所有细节。
+这个文件是 Agent 进入本仓库时的工作入口。它只负责说明硬规则和阅读路由；
+详细规范放在 `docs/11-REFERENCE/`，不要把操作手册全部塞进这里。
 
 ## 项目概况
 
 - **项目名**：[项目名称]
 - **技术栈**：[语言 / 框架 / 运行时]
 - **仓库形态**：[单仓 / monorepo / 多仓协作]
-- **主要模块**：[列出主要子项目、包或服务]
-- **默认分支**：[例如 `main`]
+- **主要模块**：[模块列表]
+- **默认分支**：[main / master / 其他]
 
 ## 不可违反的规则
 
-1. [架构约束，例如：外部依赖必须通过 adapter 层隔离]
-2. [安全约束，例如：不得提交密钥、令牌、用户隐私数据]
-3. [流程约束，例如：非平凡任务必须先建立任务目录和计划文件]
-4. [发布约束，例如：未通过指定回归门禁不得合并或发布]
+1. 遵守 `docs/11-REFERENCE/engineering-standard.md` 中的架构边界。
+2. 不提交密钥、令牌、私有接口、用户隐私数据或生产凭据。
+3. 非平凡任务先在 `docs/09-PLANNING/TASKS/` 下建立任务目录。
+4. 声称完成前必须记录证据。
+5. 保护无关工作区改动，不回滚任务范围外文件。
+6. 已验证的、有意义的工作切片要主动提交，除非用户明确说不要提交。
 
 ## 任务阅读矩阵
 
-按任务类型读取最少但足够的上下文。不要一次性加载整套文档。
+按任务类型读取最少但足够的上下文，不要一次性加载整套文档。
 
 | 任务类型 | 先读文件 |
 | --- | --- |
 | 架构、核心模块、跨模块改动 | `docs/11-REFERENCE/engineering-standard.md` |
-| 测试、冒烟、回归 | `docs/11-REFERENCE/testing-standard.md` |
-| 开发执行、提交、PR | `docs/11-REFERENCE/execution-workflow-standard.md` |
-| 多人协作、多仓交付、前后端分工 | `docs/11-REFERENCE/delivery-operating-model-standard.md`，再读 `docs/09-PLANNING/Delivery-SSoT.md` |
-| 仓库治理、PR 规则、分支保护 | `docs/11-REFERENCE/repo-governance-standard.md` |
-| CI/CD、必跑检查、发布门禁 | `docs/11-REFERENCE/ci-cd-standard.md` |
-| 长程任务、连续执行、子代理审查 | `docs/11-REFERENCE/long-running-task-standard.md` |
-| 对抗性审查、reviewer 报告 | `docs/11-REFERENCE/adversarial-review-standard.md` |
-| reviewer、subagent、外部审查路由 | `docs/11-REFERENCE/review-routing-standard.md` |
-| 文档治理、planning、任务目录 | `docs/11-REFERENCE/docs-library-standard.md` |
-| Harness Ledger 回写 | `docs/11-REFERENCE/harness-ledger-standard.md` |
+| 系统地图、服务职责、外部系统关系 | `docs/03-ARCHITECTURE/README.md`、`docs/03-ARCHITECTURE/service-catalog.md` |
+| 本地开发、mock、stub、跨仓调试 | `docs/04-DEVELOPMENT/README.md`、`docs/04-DEVELOPMENT/codebase-map.md` |
+| API、event、webhook、SDK、第三方契约 | `docs/06-INTEGRATIONS/README.md` 和相关契约文件 |
+| 测试、冒烟、回归 | `docs/11-REFERENCE/testing-standard.md`、`docs/05-TEST-QA/Regression-SSoT.md` |
+| 开发执行、提交、PR、发布 | `docs/11-REFERENCE/execution-workflow-standard.md`、`docs/11-REFERENCE/repo-governance-standard.md`、`docs/11-REFERENCE/ci-cd-standard.md` |
+| 创建或推进任务 | `docs/09-PLANNING/TASKS/` 下的当前任务目录；如果本项目已配置 Harness CLI，优先用 CLI |
+| Brief、Execution Strategy、Visual Map | 当前任务的 `brief.md`、`execution_strategy.md`、`visual_map.md` |
+| 长程任务 | `docs/11-REFERENCE/long-running-task-standard.md` |
+| reviewer、subagent、对抗性审查 | `docs/11-REFERENCE/review-routing-standard.md`、`docs/11-REFERENCE/adversarial-review-standard.md` |
+| 多人协作、多仓交付、阶段性交付 | `docs/11-REFERENCE/delivery-operating-model-standard.md`、`docs/09-PLANNING/Delivery-SSoT.md` |
+| 模块并行 | `docs/09-PLANNING/Module-Registry.md` 和相关 module plan |
+| 文档治理或 Harness 更新 | `docs/11-REFERENCE/docs-library-standard.md`、`.harness-capabilities.json` |
+| 外部资料摄取 | `docs/11-REFERENCE/external-source-intake-standard.md` |
 | Regression SSoT 维护 | `docs/11-REFERENCE/regression-ssot-governance.md` |
-| 收口记录、Closeout、Lessons | `docs/11-REFERENCE/walkthrough-standard.md`，再读 `docs/01-GOVERNANCE/Lessons-SSoT.md` 与 `docs/10-WALKTHROUGH/Closeout-SSoT.md` |
-| Worktree、并行开发、worker 隔离 | `docs/11-REFERENCE/worktree-standard.md` |
-| [前端任务] | `docs/11-REFERENCE/frontend-standard.md` |
-| [API 任务] | `docs/11-REFERENCE/api-standard.md` |
+| 收口、walkthrough、Lessons | `docs/11-REFERENCE/walkthrough-standard.md`、`docs/10-WALKTHROUGH/Closeout-SSoT.md`、`docs/01-GOVERNANCE/Lessons-SSoT.md` |
+| Worktree、并行开发隔离 | `docs/11-REFERENCE/worktree-standard.md` |
 
 ## 标准执行流程
 
-1. 判断任务是否非平凡；非平凡任务先在 `docs/09-PLANNING/TASKS/` 建任务目录。
-2. 填写 `task_plan.md`，并补齐同级 `execution_strategy.md` 与 `visual_roadmap.md`。
-3. 确认本任务的 delivery operating model；涉及多人、多仓或共享交付时更新 Delivery SSoT。
-4. 如果任务可能长时间连续执行，先填写 `long-running-task-contract.md`。
-5. 如需 reviewer、subagent、release review，在任务目录维护 `review.md`。
-6. 涉及合并、PR、CI 或发布时，先读仓库治理和 CI/CD 标准。
-7. 根据任务类型回写功能 SSoT、Delivery SSoT 或 Regression SSoT。
-8. 按 worktree 标准创建独立 worktree、feature branch、contract branch 或 release branch。
-9. 实现后运行约定检查和回归门禁，并把证据写入 `progress.md` 或 artifacts index。
-10. 收口前按 `review-routing-standard.md` 触发所需审查，处理所有阻塞发现。
-11. 写 walkthrough，并引用任务计划、证据、审查结论和残余风险。
-12. 执行 Lessons 检查：有可复用经验则写入 `docs/01-GOVERNANCE/lessons/` 并更新 Lessons SSoT；无经验也要记录 `checked-none: <原因>`。
-13. 更新 `docs/10-WALKTHROUGH/Closeout-SSoT.md` 与 `docs/Harness-Ledger.md`。
-14. 清理已完成并合并的 worktree。
-
-## 子代理 / Worker 规则
-
-主 agent 作为 coordinator 调用 subagent、外部 agent 或 reviewer 时，必须先判断对方角色。
-
-- `reviewer`：默认只读，只能写审查报告、findings 或 `review.md`，不得直接改业务代码。
-- `worker`：凡是会改代码、测试、产品文档或 harness 文档的 subagent，都必须在独立 worktree 和分支内工作。
-
-Worker 的最低交付合同：
-
-1. coordinator 先分配 worktree 路径、分支名、任务目录和允许写入范围。
-2. worker 只在自己的 worktree 内编辑，不写 coordinator 当前 checkout。
-3. worker 完成后运行约定检查，并提交自己的改动。
-4. worker handoff 必须包含 worktree path、branch、commit SHA、checks、residual risks。
-5. coordinator 只集成 worker 的 commit，不把多个 worker 的未提交改动混在同一个 checkout。
-6. coordinator 合并后运行最终回归，并更新 walkthrough、Harness Ledger 和 Lessons。
-
-如果环境或用户明确要求不使用独立 worktree，必须在 `progress.md`、walkthrough 或 Harness Ledger 记录偏离原因、风险和补偿验证。
-
-## SSoT 与总账
-
-- **功能 SSoT**：`docs/09-PLANNING/[功能-SSoT].md`
-- **Delivery SSoT**：`docs/09-PLANNING/Delivery-SSoT.md`
-- **Regression SSoT**：`docs/05-TEST-QA/Regression-SSoT.md`
-- **Lessons SSoT**：`docs/01-GOVERNANCE/Lessons-SSoT.md`
-- **Cadence Ledger**：`docs/05-TEST-QA/Cadence-Ledger.md`
-- **Harness Ledger**：`docs/Harness-Ledger.md`
-- **Closeout SSoT**：`docs/10-WALKTHROUGH/Closeout-SSoT.md`
-- **仓库治理标准**：`docs/11-REFERENCE/repo-governance-standard.md`
-- **CI/CD 标准**：`docs/11-REFERENCE/ci-cd-standard.md`
-
-## 协作补充
-
-[按项目实际填写：模块 owner、共享文件锁、merge 顺序、发布审批人、环境限制等。]
+1. 先确认请求、范围和受影响文件。
+2. 非平凡任务先创建或更新任务计划，再改代码。
+3. 只读取任务阅读矩阵要求的 reference 文档。
+4. 保留已有项目事实；新增上下文使用 merge / append，不覆盖历史。
+5. 需要隔离或并行时，使用独立 worktree 或分支。
+6. 只在确认范围内实现。
+7. 运行相关检查，并把证据写入任务记录。
+8. 按需触发 review，关闭阻塞发现。
+9. 写入或更新 walkthrough 与 closeout 记录。
+10. 只更新本任务实际触达的 SSoT / ledger。
+
+## 协作规则
+
+- reviewer 默认只读，除非明确分配写入范围。
+- worker 只能编辑分配给自己的分支、worktree 和文件范围。
+- 共享 ledger、registry 和 SSoT 默认由 coordinator 维护，除非明确登记锁。
+- worker 交接必须包含分支或 worktree、改动文件、检查、证据和残余风险。
+
+## 单一事实源
+
+- Feature SSoT：`docs/09-PLANNING/Feature-SSoT.md`
+- Delivery SSoT：`docs/09-PLANNING/Delivery-SSoT.md`
+- Module Registry：`docs/09-PLANNING/Module-Registry.md`
+- Regression SSoT：`docs/05-TEST-QA/Regression-SSoT.md`
+- Cadence Ledger：`docs/05-TEST-QA/Cadence-Ledger.md`
+- Lessons SSoT：`docs/01-GOVERNANCE/Lessons-SSoT.md`
+- Closeout SSoT：`docs/10-WALKTHROUGH/Closeout-SSoT.md`
+- Harness Ledger：`docs/Harness-Ledger.md`
+
+## 本地命令
+
+| 用途 | 命令 |
+| --- | --- |
+| 安装 | `[install command]` |
+| 测试 | `[test command]` |
+| Lint | `[lint command]` |
+| 构建 | `[build command]` |
+| 冒烟 | `[smoke command]` |
+
+## 完成标准
+
+只有当请求的改动已经实现、证据已经记录、必要审查已经处理、相关 SSoT 或
+ledger 已经更新时，任务才算完成。

package/templates-zh-CN/architecture/Architecture-SSoT.md

@@ -0,0 +1,21 @@
+# 架构事实源 / Architecture SSoT
+
+Context Doc Type: architecture-ssot
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## System Summary
+
+[用中文描述当前仓库，以及它参与的更大系统。保留关键服务名、仓库名和接口名原文。]
+
+## Current Architecture Facts
+
+| ID | Fact | Source Evidence | Last Verified | Confidence | Read Before |
+| --- | --- | --- | --- | --- | --- |
+| ARCH-001 | [事实，尽量一行说清] | [代码/文档/负责人说明/命令输出] | unknown | low | [path] |
+
+## Promotion Log
+
+| Source Task | Promoted Fact | Destination | Decision | Date |
+| --- | --- | --- | --- | --- |

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

@@ -0,0 +1,51 @@
+# 架构 / Architecture
+
+Context Doc Type: architecture-index
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Purpose
+
+这个文件夹是系统结构事实源。它说明当前仓库负责什么、属于哪个更大的系统、以及 Agent 改代码前必须理解哪些服务、流程和架构决策。
+
+Keep the English field names and file names because CLI checks rely on them.
+
+## Read Order
+
+1. `Architecture-SSoT.md`
+2. `local-repo-context.md`
+3. `system-map.md`
+4. `service-catalog.md`
+5. `critical-flows.md`
+6. `services/<service-key>.md`
+7. `decisions/ADR-*.md`
+
+## Boundary
+
+- 系统结构、服务责任、归属关系、关键流程放这里。
+- Payload、endpoint 参数、event schema、SDK 细节放 `docs/06-INTEGRATIONS/`。
+- 本地启动、mock、stub、跨仓调试经验放 `docs/04-DEVELOPMENT/`。
+
+## Structure Contract
+
+| 文件 / 路径 | 必须维护的事实 | 写入规则 |
+| --- | --- | --- |
+| `Architecture-SSoT.md` | 当前架构状态、关键决策、已知风险 | 只写跨任务仍成立的系统事实 |
+| `local-repo-context.md` | 当前仓库在整体系统中的职责和边界 | 说明本仓负责什么、不负责什么 |
+| `system-map.md` | 服务/模块拓扑、上下游关系、部署边界 | 用图或表表达全局关系，不写 payload |
+| `service-catalog.md` | 服务总表；每个服务/微服务一行 | 新增服务先加这里，再决定是否建 profile |
+| `services/<service-key>.md` | 单个服务的职责、数据、接口摘要、阅读入口 | 一个服务一个文件，不要多个服务混写 |
+| `critical-flows.md` | 跨服务关键流程 | 写业务/系统流，不写接口字段明细 |
+
+## Microservice Rule
+
+如果系统有多个微服务，`service-catalog.md` 是总索引。每个已知服务至少有一行；只要该服务会影响本仓开发、调试、接口或任务判断，就为它创建 `services/<service-key>.md`。
+
+每个 `services/<service-key>.md` 只回答三个问题：
+
+1. 这个服务负责什么、拥有什么数据。
+2. 它和本仓有什么关系。
+3. Agent 修改本仓前还需要读哪些 `04-DEVELOPMENT` 和 `06-INTEGRATIONS` 文档。
+
+不要在 `03-ARCHITECTURE` 里堆接口字段、mock 指令或临时调试记录。那些内容分别放到 `06-INTEGRATIONS` 和 `04-DEVELOPMENT`。

package/templates-zh-CN/architecture/critical-flows.md

@@ -0,0 +1,24 @@
+# 关键流程 / Critical Flows
+
+Context Doc Type: critical-flows
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Flow Index
+
+| Flow ID | Name | Trigger | Services | Business Impact | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Flow Template
+
+下面只是示例。按真实业务选择 sequenceDiagram、flowchart 或 stateDiagram，不需要为每个任务强行画图。
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant CurrentRepo
+  participant ExternalService
+  User->>CurrentRepo: request
+  CurrentRepo->>ExternalService: call
+```

package/templates-zh-CN/architecture/local-repo-context.md

@@ -0,0 +1,20 @@
+# 本仓上下文 / Local Repo Context
+
+Context Doc Type: local-repo-context
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Responsibility
+
+[说明这个仓库的职责边界。不要把外部系统的实现细节写成当前仓库事实。]
+
+## Main Components
+
+| Component | Path | Responsibility | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+
+## External Dependencies
+
+| Dependency | Why It Matters | Architecture Link | Integration Link | Development Link |
+| --- | --- | --- | --- | --- |

package/templates-zh-CN/architecture/service-catalog.md

@@ -0,0 +1,17 @@
+# 服务目录 / Service Catalog
+
+Context Doc Type: service-catalog
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Services
+
+| Service Key | Service / Component | Owner | Repo / Path | Responsibility | Interfaces | Data Owned | Dependencies | Service Profile | Development Context | Source Pack | Contract Index | Source Evidence | Last Verified | Stale After | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Boundary Rule
+
+这个目录只放服务责任、接口摘要和跳转链接。Payload、auth、error code、event schema 放 `docs/06-INTEGRATIONS/`。
+
+一个服务或微服务只占一行。只要该服务影响本仓开发或判断，就补 `services/<service-key>.md`、`docs/04-DEVELOPMENT/external-context/<service-key>.md` 和相关 `docs/06-INTEGRATIONS/<contract>.md` 链接。

package/templates-zh-CN/architecture/services/service-template.md

@@ -0,0 +1,31 @@
+# 服务：<service-key> / Service: <service-key>
+
+Context Doc Type: service-profile
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Index Links
+
+| Catalog Row | Development Context | Source Pack | Integration Contracts | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/service-catalog.md` | `docs/04-DEVELOPMENT/external-context/<service-key>.md` | `docs/04-DEVELOPMENT/external-source-packs/<source-key>/README.md` 或 N/A | `docs/06-INTEGRATIONS/<contract>.md` | unknown | low |
+
+## Responsibility
+
+[说明该服务拥有的职责、数据和边界。外部服务只写可验证事实。]
+
+## Interfaces Summary
+
+| Interface | Direction | Contract Link | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+
+## Agent Read Before
+
+- [架构链接 / architecture link]
+- [开发上下文链接 / development context link]
+- [接口契约链接 / integration contract link]
+
+## Placement Rule
+
+本文件只描述一个服务。不要把多个服务的职责、接口细节、mock 指令或临时调试记录合并到这里。

package/templates-zh-CN/architecture/system-map.md

@@ -0,0 +1,22 @@
+# 系统图谱 / System Map
+
+Context Doc Type: system-map
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Scope
+
+[描述当前仓库所在的系统边界。图谱只表达结构关系，不承载 payload 或本地 mock 细节。]
+
+## Mermaid Map
+
+```mermaid
+flowchart LR
+  current["Current Repository"] --> external["External Service"]
+```
+
+## Map Evidence
+
+| Node | Meaning | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |

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

@@ -0,0 +1,54 @@
+# 开发上下文 / Development Context
+
+Context Doc Type: development-index
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Purpose
+
+这个文件夹是 Agent 的开发输入包。它说明如何在本仓工作、外部服务不可见时如何开发、哪些内容只能 mock 或 stub、以及哪些假设不能直接成立。
+
+Keep the English field names and section headings because CLI checks rely on them.
+
+## Boundary
+
+- 本地启动、代码地图、外部服务开发摘要、mock、stub、跨仓调试放这里。
+- 长期系统结构放 `docs/03-ARCHITECTURE/`。
+- API、event、webhook 等具体契约放 `docs/06-INTEGRATIONS/`。
+
+## Structure Contract
+
+| 文件 / 路径 | 必须维护的事实 | 写入规则 |
+| --- | --- | --- |
+| `local-setup.md` | 本仓启动、依赖、环境变量、常见失败 | 只写开发启动事实，不写生产架构 |
+| `codebase-map.md` | 本仓代码入口、目录职责、阅读顺序 | Agent 改代码前先看这里 |
+| `external-context/<service-key>.md` | 外部服务对本仓开发的影响、mock/stub、调试入口 | 一个外部服务一个文件 |
+| `external-source-packs/` | 外部团队提供的大量资料、索引、摘要、投影状态 | 资料摄取层，不是最终事实层 |
+| `stubs-and-mocks.md` | 本仓可用 mock/stub 策略 | 写可执行路径或命令 |
+| `cross-repo-debugging.md` | 跨仓问题定位顺序和证据 | 写调试流程，不写服务职责总览 |
+
+## External Service Rule
+
+如果本仓依赖多个微服务，不要把所有外部知识写进一个大文档。只要某个外部服务会影响本仓开发或测试，就创建：
+
+- `docs/03-ARCHITECTURE/services/<service-key>.md`：该服务是什么、负责什么。
+- `docs/04-DEVELOPMENT/external-context/<service-key>.md`：本仓开发时如何 mock、stub、调试它。
+- `docs/06-INTEGRATIONS/<contract>.md`：具体 API/event/webhook 契约。
+
+`04-DEVELOPMENT` 只放“开发时怎么处理这个外部服务”。不要在这里维护完整系统拓扑，也不要把 payload schema 塞进来。
+
+## External Source Pack Rule
+
+如果外部团队给了多份文档、截图、导出包、会议纪要或链接，不要直接塞进 `03/04/06`。先读 `docs/11-REFERENCE/external-source-intake-standard.md`，再决定是否创建 `external-source-packs/<source-key>/`。
+
+`external-source-packs/` 只负责资料索引、摘要和投影状态。稳定结论必须回写到：
+
+- `docs/03-ARCHITECTURE/services/<service-key>.md`
+- `docs/04-DEVELOPMENT/external-context/<service-key>.md`
+- `docs/06-INTEGRATIONS/<contract>.md`
+
+## External Context Index
+
+| Service Key | Why It Matters To This Repo | Local Stub / Mock | Debug Entry | Architecture Link | Contract Link | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |

package/templates-zh-CN/development/codebase-map.md

@@ -0,0 +1,11 @@
+# 代码地图 / Codebase Map
+
+Context Doc Type: codebase-map
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Entry Points
+
+| Area | Path | Responsibility | Read When | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- |

package/templates-zh-CN/development/cross-repo-debugging.md

@@ -0,0 +1,18 @@
+# 跨仓调试 / Cross-Repo Debugging
+
+Context Doc Type: cross-repo-debugging
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Debug Flow
+
+1. 先定位失败的 interface 或 flow。
+2. 读 `docs/03-ARCHITECTURE/service-catalog.md`，确认归属和上下游服务。
+3. 读对应的 `docs/06-INTEGRATIONS/` 契约。
+4. 读 `docs/04-DEVELOPMENT/external-context/<service-key>.md`，使用其中的 mock、stub 和本地调试说明。
+
+## Known Failure Modes
+
+| Symptom | Likely Service | First Check | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |

package/templates-zh-CN/development/external-context/service-template.md

@@ -0,0 +1,33 @@
+# 外部服务开发上下文：<service-key> / External Development Context: <service-key>
+
+Context Doc Type: external-development-context
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Index Links
+
+| Service Profile | Source Pack | Integration Contracts | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-source-packs/<source-key>/README.md` 或 N/A | `docs/06-INTEGRATIONS/<contract>.md` | unknown | low |
+
+## Development Use
+
+[说明 Agent 修改本仓时需要知道的外部服务事实。只写可验证事实、mock 方式和调试入口。]
+
+## Do Not Assume
+
+- [未查看外部仓库或未问负责人前不能成立的假设。]
+
+## Mocks / Stubs
+
+| Scenario | Stub / Mock | Command or Path | Source Evidence |
+| --- | --- | --- | --- |
+
+## Cross-Repo Debug Notes
+
+[当问题涉及这个外部服务时，按什么顺序定位、用哪些命令或日志确认。]
+
+## Placement Rule
+
+本文件只写本仓开发、测试、调试这个外部服务时需要的上下文。服务职责放 `03-ARCHITECTURE`，接口字段和 schema 放 `06-INTEGRATIONS`。