coding-agent-harness 1.0.1 → 1.0.4

package/templates/reference/pull-request-standard.md

@@ -0,0 +1,80 @@
+# 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
+
+The PR body must include:
+
+1. Summary
+2. What Changed
+3. Version Impact
+4. Verification
+5. Review Evidence
+6. Residual Risk
+7. References
+
+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 the localized section follows after the English section.
+
+## 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]
+```

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

@@ -10,9 +10,11 @@ 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 no-commit reason, owner, and next step.
+6. Do not mix unrelated dirty changes into a task commit. CLI-owned Harness writes should use the local Harness commands so their locked, allowlisted auto-commit can protect shared governance files.
+7. Pull requests must follow `docs/11-REFERENCE/pull-request-standard.md` and describe intent, changed surfaces, version impact, checks run, checks not run, review status, references, and residual risk.
+8. Required checks and material review findings block merge unless an approved exception is recorded.
+9. Merge or release ownership must be explicit when several branches or workers contribute to the same outcome.
 
 ## Required Checklist
 
@@ -20,10 +22,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.
-- PR summary includes evidence and residuals.
+- Verified slices have commit SHAs, or deferred commit rationale records the no-commit reason, owner, and next step.
+- PR summary follows `pull-request-standard.md` and includes evidence, version impact, references, 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/review-routing-standard.md

@@ -13,6 +13,12 @@ Define when work needs review, which reviewer identity is appropriate, and how r
 5. Reviewers must list `Evidence Checked`; unverified claims are questions, not conclusions.
 6. The implementation owner is responsible for reconciling conflicting reviewer feedback.
 7. Closeout must include the final review disposition and `Final Confidence Basis`.
+8. At task start, read the current task `execution_strategy.md` Subagent Authorization and Subagent Delegation Decision sections, then report the state and delegation choice; users do not need to know or ask for subagents.
+9. Reviewer subagents are allowed by default for read-only review within the current task.
+10. If a worker subagent would materially help and is not authorized, proactively ask the user once in plain language for task/scope/worktree authorization; it is fine to say "worker subagent", but do not wait for the user to know or suggest subagents.
+11. If independent slices are obvious but exact file paths are not, identify the file paths first and then immediately ask for independent-execution-helper authorization before implementation.
+12. Worker subagents require one user authorization recorded in `execution_strategy.md`; reuse is limited to the same task, scope, and worktree/branch.
+13. A `Would a worker subagent materially help?` decision of `ask-user` is a blocking gate until `User Authorization Decision` records `authorized`, `denied`, or `not-needed`.
 
 ## Required Checklist
 

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`; candidates marked `needs-promotion` must link a task-local `lessons/LC-*.md` detail artifact before a follow-up task or promotion tries to preserve them.
 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,8 @@ 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>`.
+- Source lesson detail link for any queued or promoted candidate.
 - Links to updated SSoT, Regression SSoT, or Harness Ledger entries when applicable.
 
 ## Closeout Expectations

package/templates/verifier/verifier-output.md

@@ -16,7 +16,7 @@
 | Tests and regression | yes / no | commands, CI runs, logs, screenshots |
 | SSoT and ledger updates | yes / no | Feature, Delivery, Regression, Closeout, or Harness Ledger links |
 | Review disposition | yes / no | review path, finding IDs, or no-finding statement |
-| Lessons and references | yes / no | Lessons SSoT, detail doc, or checked-none reason |
+| Lessons and references | yes / no | lesson_candidates.md, detail doc, or checked-none reason |
 
 ## Explicit Exclusions
 

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,95 @@
 # [项目名称]
 
-> 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. 已验证的、有意义的工作切片要主动提交。除非用户明确暂停提交、检查失败、dirty 归属不清，或安全边界导致无法形成干净提交，否则不要把已完成工作只留在未提交文件里；不能提交时，必须在 progress、handoff 或 closeout 中写明 no-commit reason、owner 和下一步。不要把无关 dirty 改动混入本任务提交。
 
 ## 任务阅读矩阵
 
-按任务类型读取最少但足够的上下文。不要一次性加载整套文档。
+按任务类型读取最少但足够的上下文，不要一次性加载整套文档。
 
 | 任务类型 | 先读文件 |
 | --- | --- |
 | 架构、核心模块、跨模块改动 | `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/pull-request-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`、当前任务 `lesson_candidates.md`、`docs/01-GOVERNANCE/lessons/` |
+| 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. 根据用户目标主动判断是否需要分工；用户不需要知道或主动要求 subagent。
+4. 只读取任务阅读矩阵要求的 reference 文档。
+5. 保留已有项目事实；新增上下文使用 merge / append，不覆盖历史。
+6. 需要隔离或并行时，使用独立 worktree 或分支。
+7. 只在确认范围内实现。
+8. 运行相关检查，并把证据写入任务记录。
+9. 按需触发 review，关闭阻塞发现。
+10. 写入或更新 walkthrough 与 closeout 记录。
+11. 只更新本任务实际触达的 SSoT / ledger；任务生命周期总账优先由 Harness CLI 生成，不手写任务行。
+
+## 协作规则
+
+- 任务开始时，先读取当前任务 `execution_strategy.md` 的 Subagent Authorization 和 Subagent Delegation Decision，并说明是否应该使用 reviewer 或 worker subagent；即使用户只说目标，也要主动判断。
+- reviewer subagent 默认允许，只能做当前任务的只读审查。
+- 如果 worker subagent 对任务有明显帮助但尚未授权，用白话主动向用户申请一次 task/scope/worktree 授权；可以直接说 worker subagent，但不要等用户知道或主动提醒你用 subagent。
+- 如果独立切片已经明显但精确文件路径还不清楚，先确认文件路径，然后在 implementation 前立刻申请独立执行助手授权。
+- worker subagent 需要用户授权一次，并记录到 `execution_strategy.md`；之后只可在同一任务、同一范围、同一 worktree/branch 内复用。
+- 共享 ledger、registry 和 SSoT 默认由 coordinator 维护，除非明确登记锁。
+- worker 交接必须包含分支或 worktree、改动文件、检查、证据和残余风险。
+
+## 单一事实源
+
+- Harness Ledger：`docs/Harness-Ledger.md`（任务生命周期总账，由 CLI 生成）
+- 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`
+- Lesson Candidates：当前任务 `lesson_candidates.md`
+- Lesson Detail Docs：`docs/01-GOVERNANCE/lessons/`
+- Closeout SSoT：`docs/10-WALKTHROUGH/Closeout-SSoT.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 |
+| --- | --- | --- | --- | --- | --- |