coding-agent-harness 1.0.0 → 1.0.2

package/docs-release/guides/repository-operating-models.md

@@ -0,0 +1,196 @@
+# 仓库运行模式选择指南
+
+English mirror: `docs-release/guides/repository-operating-models.en-US.md`
+
+Coding Agent Harness 可以落在不同的仓库组织方式里。选择错了，后面最常见的问题不是“文档少”，而是 Harness 自己变成新的混乱源。
+
+这份指南解释三种常见模式：
+
+- 单仓模式：一个代码仓库，一套 Harness。
+- 多仓独立模式：多个代码仓库，每个仓库有自己的 Harness。
+- 主控仓库模式：一个父级控制仓库管理 Harness，多个子仓库只承载代码执行事实。
+
+## 快速选择
+
+| 模式 | 适合 | 不适合 | Harness 事实源 |
+| --- | --- | --- | --- |
+| 单仓模式 | 单产品、单代码仓库、团队边界清楚 | 已经拆成多个独立发布仓库 | 当前仓库 `AGENTS.md` + `docs/` |
+| 多仓独立模式 | 前端、后端、SDK 等仓库长期独立迭代，跨仓任务少 | 大量跨仓 feature 和统一 release 计划 | 每个仓库自己的 `AGENTS.md` + `docs/` |
+| 主控仓库模式 | 微服务、多子系统、多仓统一路线图、跨仓 release、Agent 需要从一个地方启动 | 小项目，或只有一个短期脚本仓库 | 父仓库 `AGENTS.md` + `docs/` |
+
+## 单仓模式
+
+单仓模式最简单。代码、计划、回归、walkthrough 都在同一个仓库里。
+
+```text
+product-repo/
+  AGENTS.md
+  docs/
+    03-ARCHITECTURE/
+    04-DEVELOPMENT/
+    05-TEST-QA/
+    09-PLANNING/
+    10-WALKTHROUGH/
+    11-REFERENCE/
+  src/
+  tests/
+```
+
+Agent 从仓库根目录启动，读 `AGENTS.md`，然后进入任务文件和代码。
+
+### 什么时候选
+
+- 应用、服务、脚本或库都在一个仓库里。
+- Feature 通常只改这个仓库。
+- 回归命令可以在一个 checkout 内完成。
+- 团队希望快速接入 Harness，不想先改组织结构。
+
+### 风险
+
+当项目后来拆出多个仓库时，单仓 Harness 容易失去全局视野。前端、后端、SDK 各自都有状态，但没有一个地方能说明跨仓任务到底完成到哪一步。
+
+## 多仓独立模式
+
+多仓独立模式让每个仓库都有自己的 Harness。
+
+```text
+frontend-repo/
+  AGENTS.md
+  docs/
+
+backend-repo/
+  AGENTS.md
+  docs/
+
+sdk-repo/
+  AGENTS.md
+  docs/
+```
+
+每个仓库的 Agent 入口只管本仓库。前端任务在前端仓库计划和收口，后端任务在后端仓库计划和收口。
+
+### 什么时候选
+
+- 仓库之间组织上确实独立。
+- 每个仓库有自己的 owner、release 节奏和 review 规则。
+- 跨仓任务少，或者跨仓任务由人手动协调。
+- 某个仓库的 Harness 不应该知道另一个仓库的内部状态。
+
+### 必须补的外围文档
+
+多仓独立模式不能只给每个仓库复制一套模板。否则跨仓上下文会断。
+
+每个仓库至少要在这些位置写清楚外部边界：
+
+- `docs/03-ARCHITECTURE/`：本仓库在整体系统中的位置。
+- `docs/04-DEVELOPMENT/`：依赖哪些 sibling repo、本地联调怎么启动。
+- `docs/06-INTEGRATIONS/`：API、事件、SDK、队列、数据库、鉴权等外部契约。
+- `docs/05-TEST-QA/Regression-SSoT.md`：哪些检查只覆盖本仓库，哪些需要跨仓联调。
+- `AGENTS.md`：遇到跨仓任务时，Agent 应该停下来、切仓库，还是交给人协调。
+
+### 风险
+
+多仓独立模式的风险是 Harness 分裂：
+
+- 前端 Feature SSoT 认为任务完成，后端 Regression SSoT 仍是红灯。
+- SDK 的 breaking change 没有投影到产品 shell。
+- Agent 从子仓库启动后，只看到局部事实，误以为全局任务已经结束。
+
+如果这种情况频繁发生，应升级到主控仓库模式。
+
+## 主控仓库模式
+
+主控仓库模式把 Harness 放在父仓库。子仓库只承载代码执行事实。
+
+```text
+product-control-repo/
+  AGENTS.md
+  docs/
+    03-ARCHITECTURE/
+    04-DEVELOPMENT/
+    05-TEST-QA/
+    06-INTEGRATIONS/
+    09-PLANNING/
+    10-WALKTHROUGH/
+    11-REFERENCE/
+  tools/
+  frontend/   -> child repository
+  backend/    -> child repository
+  sdk/        -> child repository
+  service-a/  -> child repository
+  service-b/  -> child repository
+```
+
+父仓库是 control plane。它管理：
+
+- 总体架构和 repo topology。
+- 跨仓 Feature SSoT。
+- 任务计划、review、walkthrough。
+- Regression SSoT 和跨仓 cadence。
+- Agent 启动入口和读文件矩阵。
+- 子仓库 commit、分支、submodule pointer 或 release version 的证据。
+
+子仓库是 execution plane。它们管理：
+
+- 代码实现。
+- 本仓库依赖和 lockfile。
+- 本仓库局部测试和 CI。
+- 本仓库局部 `AGENTS.md`。
+- 具体提交和 PR。
+
+### 什么时候选
+
+- 一个产品由多个仓库共同交付。
+- Feature 经常跨前端、后端、SDK、微服务。
+- 你希望 Agent 永远从同一个入口启动。
+- 你需要统一的任务状态、review 门禁和 release closeout。
+- 微服务数量很多，不能让每个仓库各自维护一套全局计划。
+
+### 核心好处
+
+主控仓库模式把“全局事实”固定在一个地方。即使有 100 个子仓库，Agent 也先读父仓库的任务合同，然后再进入具体子仓库执行。
+
+这能避免：
+
+- 多个 Feature SSoT 互相冲突。
+- 每个子仓库都声称自己已经完成，但 release 仍不能发。
+- Agent 从错误仓库启动，只看到局部上下文。
+- 跨仓 review 和 regression 证据散落在不同地方。
+
+完整方法见 `docs-release/guides/parent-control-repository-pattern.md`。
+
+## 从一种模式迁移到另一种
+
+### 单仓到多仓
+
+当一个单仓拆出前端、后端、SDK 时，不要直接复制 `docs/` 到每个仓库。
+
+先决定：
+
+- 哪些任务仍是全局任务？
+- 哪些任务变成子仓库局部任务？
+- 原来的 Regression SSoT 是保留在父层，还是拆成局部 gate？
+- Agent 未来从哪里启动？
+
+如果跨仓 feature 仍然很多，优先创建主控仓库。
+
+### 多仓独立到主控仓库
+
+迁移顺序：
+
+1. 创建父仓库 `AGENTS.md` 和 repo topology。
+2. 把全局 Feature SSoT、Regression SSoT、walkthrough index 收到父仓库。
+3. 子仓库保留局部 `AGENTS.md`，但把全局计划指向父仓库。
+4. 新跨仓任务只在父仓库创建 task。
+5. 子仓库提交只作为父任务的 evidence。
+
+不要一次性重写所有历史任务。先把当前 release 和活跃 feature 接到父仓库。
+
+## 推荐默认值
+
+- 新的小项目：单仓模式。
+- 已经有多个强独立团队：多仓独立模式。
+- 一个产品、多个代码仓库、一个 release 目标：主控仓库模式。
+- 微服务很多但需要统一 Agent 协作：主控仓库模式。
+
+真正的判断标准不是仓库数量，而是全局决策是否需要一个唯一事实源。

package/docs-release/intl/README.md

@@ -0,0 +1,15 @@
+# International Introductions
+
+Coding Agent Harness uses English as the canonical public language and maintains full executable templates in English and Simplified Chinese.
+
+These lightweight introductions help international readers understand the project quickly. For implementation details, use the English docs first.
+
+| Language | Intro | Support Level |
+| --- | --- | --- |
+| English | [`en-US.md`](en-US.md) | Full docs and templates |
+| Simplified Chinese | [`zh-CN.md`](zh-CN.md) | Full docs and templates |
+| Japanese | [`ja-JP.md`](ja-JP.md) | Intro only |
+| Korean | [`ko-KR.md`](ko-KR.md) | Intro only |
+| French | [`fr-FR.md`](fr-FR.md) | Intro only |
+| Spanish | [`es-ES.md`](es-ES.md) | Intro only |
+| German | [`de-DE.md`](de-DE.md) | Intro only |

package/docs-release/intl/de-DE.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness legt die Arbeit von Coding Agents im Repository ab, nicht nur im Chatverlauf. Plaene, Fortschritt, Reviews, Migrationsnotizen und Dashboard-Zustaende bleiben beim Code.
+
+Die vollstaendige UI und die ausfuehrbaren Templates werden derzeit in English und Simplified Chinese gepflegt.
+
+## So funktioniert es
+
+1. Installieren Sie den Skill oder starten Sie die CLI mit `npx`.
+2. Der Agent analysiert das Repository und schlaegt einen Initialisierungs- oder Migrationsplan vor.
+3. Das lokale Dashboard zeigt Aufgaben, Warnungen, Nachweise und Review-Status.
+4. Vor der Uebergabe laufen die harness checks.
+
+## Sprachunterstuetzung
+
+Ausfuehrbare Templates und vollstaendige Dokumentation werden derzeit in English und Simplified Chinese gepflegt. Diese Seite ist eine kurze Einfuehrung.
+
+Start here: [`../../README.md`](../../README.md).

package/docs-release/intl/en-US.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness keeps coding-agent work inside the repository instead of leaving it buried in chat history. Plans, progress, reviews, migration notes, and dashboard snapshots stay with the code.
+
+![Dashboard overview](../assets/dashboard-overview-en.png)
+
+## How It Works
+
+1. Install the Skill or run the CLI with `npx`.
+2. Let the agent diagnose the repository and propose an initialization or migration plan.
+3. Review tasks, warnings, evidence, and handoff state in the local Dashboard.
+4. Run harness checks before delivery.
+
+## Language Support
+
+English and Simplified Chinese have full README, guide, and executable template support. Other languages currently provide short introductions and route users to the English documentation.
+
+Start with the canonical README: [`../../README.md`](../../README.md).

package/docs-release/intl/es-ES.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness deja el trabajo de los agentes de programacion dentro del repositorio, no solo en el historial del chat. Planes, progreso, revisiones, notas de migracion y estados del Dashboard quedan junto al codigo.
+
+La interfaz completa y las plantillas ejecutables se mantienen actualmente en English y Simplified Chinese.
+
+## Como funciona
+
+1. Instala el Skill o ejecuta la CLI con `npx`.
+2. El agente diagnostica el repositorio y propone un plan de inicializacion o migracion.
+3. El Dashboard local muestra tareas, advertencias, evidencia y estado de revision.
+4. Ejecuta las verificaciones de harness antes de entregar.
+
+## Idiomas
+
+Las plantillas ejecutables y la documentacion completa se mantienen en English y Simplified Chinese. Esta pagina es una introduccion breve.
+
+Start here: [`../../README.md`](../../README.md).

package/docs-release/intl/fr-FR.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness garde le travail des agents de code dans le depot, pas seulement dans l'historique de discussion. Plans, progression, revues, notes de migration et etats du Dashboard restent avec le code.
+
+L'interface complete et les modeles executables sont actuellement maintenus en English et Simplified Chinese.
+
+## Fonctionnement
+
+1. Installez le Skill ou lancez le CLI avec `npx`.
+2. L'agent analyse le depot et propose un plan d'initialisation ou de migration.
+3. Le Dashboard local affiche les taches, alertes, preuves et etats de revue.
+4. Les verifications harness confirment l'etat avant livraison.
+
+## Langues
+
+Les modeles executables et la documentation complete sont maintenus en English et Simplified Chinese. Cette page est une introduction courte.
+
+Start here: [`../../README.md`](../../README.md).

package/docs-release/intl/ja-JP.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness は、コーディングエージェントの作業をチャット履歴ではなくリポジトリに残すための仕組みです。計画、進捗、レビュー、移行メモ、Dashboard の状態がコードと一緒に残ります。
+
+UI と実行可能なテンプレートは、現在 English と Simplified Chinese を中心に保守されています。
+
+## 使い方
+
+1. Skill をインストールするか、`npx` で CLI を実行します。
+2. エージェントがリポジトリを診断し、初期化または移行計画を提示します。
+3. ローカル Dashboard でタスク、警告、証拠、レビュー状態を確認します。
+4. 受け渡し前に harness check を実行します。
+
+## 言語サポート
+
+実行可能なテンプレートと詳細ドキュメントは、現在 English と Simplified Chinese を中心に保守されています。このページは概要紹介です。
+
+Start here: [`../../README.md`](../../README.md).

package/docs-release/intl/ko-KR.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness는 코딩 에이전트의 작업을 채팅 기록이 아니라 저장소 안에 남기기 위한 도구입니다. 계획, 진행 상황, 리뷰, 마이그레이션 메모, Dashboard 상태가 코드와 함께 남습니다.
+
+전체 UI와 실행 가능한 템플릿은 현재 English와 Simplified Chinese를 중심으로 유지됩니다.
+
+## 사용 방식
+
+1. Skill을 설치하거나 `npx`로 CLI를 실행합니다.
+2. 에이전트가 저장소를 진단하고 초기화 또는 마이그레이션 계획을 제안합니다.
+3. 로컬 Dashboard에서 작업, 경고, 증거, 리뷰 상태를 확인합니다.
+4. 전달 전에 harness check를 실행합니다.
+
+## 언어 지원
+
+실행 가능한 템플릿과 자세한 문서는 현재 English와 Simplified Chinese를 중심으로 유지됩니다. 이 페이지는 간단한 소개입니다.
+
+Start here: [`../../README.md`](../../README.md).

package/docs-release/intl/zh-CN.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness 把 Coding Agent 的计划、进度、审查、迁移记录和 Dashboard 快照留在仓库里，而不是散在聊天记录里。
+
+![Dashboard overview](../assets/dashboard-overview-en.png)
+
+## 怎么用
+
+1. 安装 Skill，或用 `npx` 运行 CLI。
+2. 让 Agent 先诊断仓库，再给出初始化或迁移计划。
+3. 在本地 Dashboard 里查看任务、风险、证据和审查状态。
+4. 交付前运行 harness 检查。
+
+## 语言支持
+
+英文和简体中文提供完整 README、指南和可执行模板。其他语言目前是简介和入口页，具体实施请优先阅读英文文档。
+
+中文 README：[`../../README.zh-CN.md`](../../README.zh-CN.md)。

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/brief.md

@@ -0,0 +1,13 @@
+# Demo task
+
+## Brief
+
+Minimal example task used by the dashboard smoke tests.
+
+## Task ID
+
+`demo-task`
+
+## Outcome
+
+Show a readable task summary in the static dashboard without requiring an editor.

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/lesson_candidates.md

@@ -0,0 +1,24 @@
+# Demo Task - Lesson Candidates
+
+## Candidate Status
+
+| Field | Value |
+| --- | --- |
+| Schema version | lesson-candidate-v1 |
+| Task-level status | no-candidate-accepted |
+| Review gate | candidate-file-present |
+| Review decision | accepted-no-candidate |
+| Promotion state | not-promoted |
+| Closeout token | checked-candidate:LC-20260101-000 |
+| Source task | demo-task |
+| Owner | coordinator |
+| Last updated | 2026-01-01 |
+
+## Candidates
+
+| ID | Row Status | Title | Why It Might Matter | Review Decision | Promotion Target |
+| --- | --- | --- | --- | --- | --- |
+
+## No-Candidate Reason
+
+The example task exists only to demonstrate dashboard parsing and does not produce a reusable governance lesson.

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/progress.md

@@ -8,4 +8,4 @@ in-progress
 
 | Date | Update | Evidence |
 | --- | --- | --- |
-| 2026-05-18 | Created example roadmap | report:TARGET:docs/09-PLANNING/TASKS/demo-task/visual_roadmap.md:example phase table |
+| 2026-05-18 | Created example visual map | report:TARGET:docs/09-PLANNING/TASKS/demo-task/visual_map.md:example phase table |

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/task_plan.md

@@ -1,8 +1,10 @@
 # Demo Task
 
+Task Contract: harness-task/v1
+
 ## Goal
 
-Show the v1.0 visual roadmap contract.
+Show the v1.0 visual map contract.
 
 ## Scope
 
@@ -11,4 +13,4 @@ Public example only.
 ## Execution & Visualization Files
 
 - `execution_strategy.md`
-- `visual_roadmap.md`
+- `visual_map.md`

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/{visual_roadmap.md → visual_map.md}

@@ -1,4 +1,12 @@
-# Visual Roadmap
+# Visual Map
+
+Visual Map Contract: v1.0
+
+## Map Index
+
+| ID | Type | Purpose | Required For Understanding | Source Evidence | Promotion Candidate |
+| --- | --- | --- | --- | --- | --- |
+| MAP-01 | phase | Show the demo task phase relationship | yes | `task_plan.md` | no |
 
 ```mermaid
 flowchart LR

package/package.json

@@ -1,8 +1,27 @@
 {
   "name": "coding-agent-harness",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Document governance kernel for long-running coding agents.",
   "type": "module",
+  "keywords": [
+    "agent",
+    "coding-agent",
+    "codex",
+    "claude-code",
+    "gemini-cli",
+    "harness",
+    "ai-engineering",
+    "workflow",
+    "governance"
+  ],
+  "homepage": "https://github.com/FairladyZ625/coding-agent-harness#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FairladyZ625/coding-agent-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/FairladyZ625/coding-agent-harness/issues"
+  },
   "bin": {
     "harness": "scripts/harness.mjs"
   },
@@ -17,6 +36,8 @@
   },
   "files": [
     "README.md",
+    "README.en-US.md",
+    "README.zh-CN.md",
     "CHANGELOG.md",
     "SKILL.md",
     "LICENSE",

package/references/agents-md-pattern.md

@@ -68,7 +68,7 @@ AGENTS.md 只包含两类内容：
 
 ```
 项目根目录/
-├── AGENTS.md        ← 231 行，canonical 宪章 + 索引
+├── AGENTS.md        ← concise canonical charter + routing index
 ├── CLAUDE.md        ← 轻量 shim，指向 AGENTS.md
 └── docs/
     ├── Harness-Ledger.md
@@ -91,7 +91,7 @@ AGENTS.md 只包含两类内容：
 
 ### 行数控制
 
-AGENTS.md 控制在 **100-300 行**。超过 300 行说明有内容应该下沉到 reference 文件。
+AGENTS.md 默认控制在 **80-160 行**。超过 160 行时，优先把操作细节下沉到 reference 文件；超过 300 行基本可以判断已经变成百科全书式入口。
 
 CLAUDE.md 控制在 **10-50 行**。它只做 Claude Code 兼容入口，不应复制 AGENTS.md 的完整规则，避免两份入口文件漂移。
 
@@ -112,7 +112,7 @@ CLAUDE.md 控制在 **10-50 行**。它只做 Claude Code 兼容入口，不应
 4. 填写项目信息区（项目名、技术栈、仓库结构）
 5. 根据项目模块编写 Task-Type Reading Matrix
 6. 写入硬规则（核心架构约束、绝对不能违反的原则）
-7. 控制 AGENTS.md 总行数在 100-300 行
+7. 控制 AGENTS.md 总行数在 80-160 行，避免把安装教程或操作手册塞进入口
 8. 用 `templates/CLAUDE.md.template` 生成 CLAUDE.md shim，指向 AGENTS.md
 9. 不要在 CLAUDE.md 中复制完整规范
 

package/references/docs-directory-standard.md

@@ -17,13 +17,13 @@ docs/
 │   └── _archive/              ← 已处理条目归档
 ├── 02-PRODUCT/                ← 产品设计、用户流程、功能规格
 │   └── _archive/              ← 本层历史文档归档（如该层会增长）
-├── 03-ARCHITECTURE/           ← 架构设计、技术方案、ADR
+├── 03-ARCHITECTURE/           ← 系统结构事实源：本仓架构、外部系统结构、服务地图、关键跨服务流、ADR
 │   └── _archive/              ← 本层历史文档归档（如该层会增长）
-├── 04-DEVELOPMENT/            ← 开发指南、环境配置、本地开发说明
+├── 04-DEVELOPMENT/            ← 开发上下文输入包：本地开发、外部服务摘要、外部资料包、mock/stub、跨仓调试
 │   └── _archive/              ← 本层历史文档归档（如该层会增长）
 ├── 05-TEST-QA/                ← 测试策略、Regression SSoT、Cadence Ledger
 │   └── _archive/              ← 废弃 regression gate / 旧 evidence pack 归档
-├── 06-INTEGRATIONS/           ← 第三方集成文档、API 对接说明
+├── 06-INTEGRATIONS/           ← 接口合同层：API、event、webhook、SDK、第三方接入细节
 │   └── _archive/              ← 本层历史文档归档（如该层会增长）
 ├── 07-OPERATIONS/             ← 部署、运维、监控、告警
 │   └── _archive/              ← 本层历史文档归档（如该层会增长）
@@ -72,6 +72,49 @@ docs/
 `docs/10-WALKTHROUGH/Closeout-SSoT.md` 是 closed task 的收口索引和硬门槛；
 每个 closed Harness Ledger row 必须在这里登记 walkthrough 或受控 skip reason。
 
+## 03 / 04 / 06 边界规则
+
+这三个目录共同承载项目和外部系统知识，但职责不能重叠：
+
+```text
+03 = 它在系统里是什么
+04 = 我开发当前仓时怎么面对它
+06 = 我和它具体怎么对接
+```
+
+| 目录 | 放什么 | 不放什么 | 必需机器字段 |
+| --- | --- | --- | --- |
+| `03-ARCHITECTURE/` | system map、service catalog、service responsibility、ownership、critical flows、ADR | endpoint payload、错误码、mock/stub、任务日志 | `Context Doc Type`, `Source Evidence`, `Last Verified`, `Confidence` |
+| `04-DEVELOPMENT/` | local setup、codebase map、external service development summary、external source packs、mocks/stubs、cross-repo debugging | 长期系统事实源、payload 合同、ADR、未经摘要的外部资料堆 | `Context Doc Type`, `Development Use`, `Do Not Assume`, `Mocks / Stubs`, `Source Evidence`, `Last Verified`, `Confidence` |
+| `06-INTEGRATIONS/` | endpoint、payload、错误码、auth、event schema、webhook、SDK、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` 可以写“Billing API: owner=payments, interface=/v1/invoices, link=06-INTEGRATIONS/billing-api-contract.md”。
+- `06-INTEGRATIONS/billing-api-contract.md` 才写 `/v1/invoices` 的 payload、错误码、鉴权和 contract test。
+- `04-DEVELOPMENT/external-context/billing.md` 写本仓开发时如何 mock Billing、如何排查 Billing 失败、哪些 Billing 假设不安全。
+- `04-DEVELOPMENT/external-source-packs/payments/` 只存外部团队资料的索引、摘要和投影状态；最终事实仍要回写到 `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 的原始资料不能进入执行事实层。
+
+Checker 规则：
+
+- 新增 `03/04/06` 文档必须声明 `Context Doc Type`。
+- 结构事实必须有 `Source Evidence`、`Last Verified` 和 `Confidence`。
+- `04-DEVELOPMENT/external-context/*.md` 必须包含 `Development Use`、`Do Not Assume`、`Mocks / Stubs`。
+- `06-INTEGRATIONS/*.md` 必须包含 `Contract Type`、`Auth`、`Payload`、`Errors`、`Contract Tests`。
+- 旧项目 safe-adoption 可先收到 warning；declared canonical 项目应修到 clean。
+
 ## 通用归档规则
 
 归档是目录级基础设施，不是单张表的特例。任何会持续增长的目录都应该有同级
@@ -113,6 +156,7 @@ docs/
 | adversarial-review-standard.md | 对抗性 review 报告、finding 分级、no-finding 结论、residual 路由 | 是 |
 | review-routing-standard.md | reviewer / subagent / external agent / human review 触发和路由规则 | 是 |
 | docs-library-standard.md | 文档治理规范、命名规则、归档规则 | 是 |
+| external-source-intake-standard.md | 外部资料摄取、过滤、摘要和投影规则 | 是 |
 | harness-ledger-standard.md | Harness Ledger 写入规范、closeout 检查 | 是 |
 | regression-ssot-governance.md | Regression SSoT 治理规范 | Standard+ |
 | walkthrough-standard.md | Walkthrough 写作规范 | 是 |

package/references/external-source-intake-standard.md

@@ -0,0 +1,75 @@
+# 外部资料摄取标准
+
+## 目的
+
+定义目标项目里的 Agent 如何接收、过滤、整理外部项目或微服务团队提供的大量资料。核心原则是：外部资料先进资料包，经过摘要和验证后，再投影到稳定执行文档。
+
+## 核心模型
+
+```text
+外部原始资料 -> source pack 索引 -> digest 摘要 -> 03/04/06 执行投影
+```
+
+`03-ARCHITECTURE`、`04-DEVELOPMENT`、`06-INTEGRATIONS` 不承载外部资料堆。它们只保存已经提炼、可验证、能指导当前仓库开发的事实。
+
+## Diagnose / Decide 必问条件
+
+只要目标项目满足任一条件，Agent 必须询问用户是否有外部资料：
+
+- 当前仓属于多仓系统、微服务系统、前后端分仓或平台子系统。
+- 代码中出现外部服务、SDK、API gateway、message queue、webhook、contract、schema 或 mock。
+- 用户提到其他仓库、上下游、接口文档、业务知识、系统整体设计。
+- Agent 无法只靠当前仓判断服务职责、接口契约或联调方式。
+
+推荐问题：
+
+1. 这个项目是否依赖外部服务或其他仓库？
+2. 你是否有外部团队提供的架构文档、接口文档、流程图、会议纪要、代码路径、链接或导出包？
+3. 这些资料能否复制进本仓？如果不能，是否只能保存本地路径或 URL？
+4. 哪些资料是可信来源，哪些只是历史参考？
+
+## 存储规则
+
+| 场景 | 存储方式 |
+| --- | --- |
+| 只有 1-4 个稳定外部文档 | 不必建独立 source pack；在对应 `03/04/06` 的 `Source Evidence` 中链接 |
+| 外部资料超过 5 份、跨多个主题、或会持续增长 | 创建 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/` |
+| 资料含敏感信息、密钥、客户数据或不能进仓 | 不复制原文；只记录外部路径、owner、访问条件和摘要 |
+| 资料可入仓 | 可放 `raw/`，但必须经过 digest 后才能投影到执行文档 |
+
+推荐结构：
+
+```text
+docs/04-DEVELOPMENT/external-source-packs/<source-key>/
+├── README.md
+├── digests/
+├── raw/
+└── raw-index.md
+```
+
+## 摄取流程
+
+1. Inventory：列出所有资料，记录来源、owner、时间、可信度和是否可入仓。
+2. Classify：按 architecture、development、integration、security、operations、product、unknown 分类。
+3. Sanitize：检查密钥、token、客户数据、隐私、内部账号和不可公开链接。
+4. Digest：提炼事实、疑问、不安全假设和证据。
+5. Project：把稳定事实投影到 `03/04/06`。
+6. Verify：尽可能用代码、接口测试、owner 确认或运行证据验证。
+7. Residual：不能确认的内容留在 source pack 或 `Do Not Assume`，不进入执行事实。
+
+## 投影规则
+
+| 资料内容 | 投影位置 |
+| --- | --- |
+| 服务职责、上下游、owner、数据归属、系统拓扑 | `03-ARCHITECTURE/service-catalog.md` 或 `services/<service-key>.md` |
+| 本仓开发时如何 mock、stub、启动、联调、排查 | `04-DEVELOPMENT/external-context/<service-key>.md` |
+| endpoint、payload、auth、error、event、webhook、SDK、contract test | `06-INTEGRATIONS/<contract>.md` |
+| 未确认、来源冲突、过期或背景参考 | 留在 source pack README / digest |
+
+## 禁止事项
+
+- 不把几十份外部文档直接复制到 `03-ARCHITECTURE`、`04-DEVELOPMENT` 或 `06-INTEGRATIONS` 根目录。
+- 不把 digest 当成已验证事实。
+- 不在执行文档里保留大段原文、聊天流水或历史会议记录。
+- 不把密钥、token、客户数据、个人隐私或不可公开资料提交进仓。
+- 不为每个微服务复制一套完整目录树。