coding-agent-harness 1.0.1 → 1.0.4

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,6 +1,6 @@
 {
   "name": "coding-agent-harness",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "Document governance kernel for long-running coding agents.",
   "type": "module",
   "keywords": [
@@ -31,15 +31,22 @@
     "status": "node scripts/harness.mjs status --json .",
     "dashboard": "node scripts/harness.mjs dashboard --out tmp/harness-dashboard.html examples/minimal-project",
     "dashboard:folder": "node scripts/harness.mjs dashboard --out-dir tmp/harness-dashboard examples/minimal-project",
-    "smoke:dashboard": "node scripts/smoke-dashboard.mjs",
-    "test": "node scripts/test-harness.mjs"
+    "pack:dry-run": "npm pack --dry-run --json",
+    "postinstall": "node scripts/postinstall.mjs",
+    "smoke:dashboard": "node tests/smoke-dashboard.mjs",
+    "test": "node tests/run-all.mjs"
   },
   "files": [
     "README.md",
+    "README.en-US.md",
+    "README.zh-CN.md",
+    "CONTRIBUTING.md",
     "CHANGELOG.md",
     "SKILL.md",
     "LICENSE",
     "references/",
+    "skills/",
+    "presets/",
     "templates/",
     "templates-zh-CN/",
     "scripts/",

package/presets/legacy-migration/checks/preset-check.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+console.log(JSON.stringify({ status: "pass", preset: "legacy-migration", scope: "manifest" }, null, 2));

package/presets/legacy-migration/preset.yaml

@@ -0,0 +1,134 @@
+id: legacy-migration
+version: 2
+compatibleBudgets: [complex]
+localeSupport: [en-US, zh-CN]
+purpose: migrate legacy Harness projects into v1 task readability and cutover gates
+task:
+  kind: project-migration
+  defaultTaskId: harness-v1-migration
+  defaultOutcome: Create a controlled Harness v1 migration task from the recorded migrate-run session without rewriting history automatically.
+  requiresFromSession: true
+  projectLevelOnly: true
+  migrationTargetLevel: migration-baseline
+inputs:
+  session:
+    type: json-file
+    flag: --from-session
+    required: true
+    validateOperation: migrate-run
+    rejectPlanOnly: true
+    requireTarget: true
+    targetFromSession: true
+templateValues:
+  preset:
+    value: legacy-migration
+  presetVersion:
+    value: 2
+  evidenceBundle:
+    from: computed.evidenceBundle
+  migrationTargetLevel:
+    from: computed.migrationTargetLevel
+  migrationAchievedLevel:
+    from: computed.migrationAchievedLevel
+  strictDeferred:
+    from: computed.strictDeferred
+  fullCutoverClaimAllowed:
+    from: computed.fullCutoverClaimAllowed
+  warnings:
+    from: computed.warnings
+  taskActions:
+    from: computed.taskActions
+  legacyResiduals:
+    from: computed.legacyResiduals
+entrypoints:
+  newTask:
+    type: template
+    writes: [docs/09-PLANNING/TASKS/**]
+    reads: [session.json]
+    audit: true
+    templates:
+      taskPlanAppend: templates/task_plan.append.md
+      executionStrategyAppend: templates/execution_strategy.append.md
+      visualMapAppend: templates/visual_map.append.md
+      findingsSeed: templates/findings.seed.md
+      reviewSeed: templates/review.seed.md
+  plan:
+    type: script
+    command: scripts/plan-work-queue.mjs
+    writes: [docs/09-PLANNING/TASKS/**]
+    reads: [docs/**, .git/**]
+    audit: true
+  scaffold:
+    type: script
+    command: scripts/scaffold-task-contracts.mjs
+    writes: [docs/09-PLANNING/TASKS/**]
+    reads: [docs/**]
+    audit: true
+  check:
+    type: check
+    command: checks/preset-check.mjs
+    writes: [docs/09-PLANNING/TASKS/**]
+    reads: [docs/**]
+    audit: true
+workbench:
+  panels: workbench/dashboard-panels.yaml
+  migrationQueueSchema: workbench/migration-queue.schema.json
+evidence:
+  bundleDir: evidence
+  files:
+    session:
+      path: session.json
+      type: input-json
+      value: inputs.session
+    migratePlan:
+      path: migrate-plan.json
+      type: json
+      value: inputs.session.plan
+    normalCheck:
+      path: normal-check.json
+      type: json
+      value: inputs.session.checks.normal
+    strictCheck:
+      path: strict-check.json
+      type: json
+      value: inputs.session.checks.strict
+    migrateVerify:
+      path: migrate-verify.json
+      type: migration-verify
+    migrationLedger:
+      path: migration-ledger.json
+      type: migration-ledger
+    presetManifest:
+      path: preset-manifest.json
+      type: preset-manifest
+    presetAudit:
+      path: preset-audit.json
+      type: preset-audit
+    writeScope:
+      path: write-scope.json
+      type: write-scope
+    dashboardHash:
+      path: dashboard.hash.txt
+      type: dashboard-hash
+    targetGitStatus:
+      path: target-git-status.txt
+      type: target-git-status
+    targetCommit:
+      path: target-commit.txt
+      type: target-commit
+    harnessVersion:
+      path: harness-version.txt
+      type: harness-version
+    generatedAt:
+      path: generated-at.txt
+      type: generated-at
+review:
+  required: true
+  materialFindingPolicy: block-open-p0-p2
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-manifest.json, preset-audit.json, write-scope.json]
+writeScopes:
+  taskArtifacts:
+    path: docs/09-PLANNING/TASKS/**
+    access: write

package/presets/legacy-migration/scripts/plan-work-queue.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+console.error("legacy-migration plan entrypoint is declared for audit and will be implemented in the v2 package slice.");
+process.exit(2);

package/presets/legacy-migration/scripts/scaffold-task-contracts.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+console.error("legacy-migration scaffold entrypoint is declared for audit and will be implemented in the v2 package slice.");
+process.exit(2);

package/presets/legacy-migration/templates/execution_strategy.append.md

@@ -0,0 +1,18 @@
+## Legacy Migration Preset Strategy
+
+This preset keeps migration inside the Complex Task contract.
+
+| Area | Rule |
+| --- | --- |
+| Write boundary | Do not rewrite historical task bodies unless the user explicitly confirms that phase. |
+| Evidence source | Use `{{evidenceBundle}}/` as the handoff bundle. Absolute session paths are origin data only. |
+| Target level | `{{migrationTargetLevel}}` |
+| Achieved level | `{{migrationAchievedLevel}}` |
+
+## Subagent Lane Table
+
+Declare lanes before dispatching workers.
+
+| Lane ID | Allowed globs | Forbidden globs | Shared file owner | Worktree / branch | Handoff path | Merge order | Verification command |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| coordinator | docs/09-PLANNING/TASKS/** | AGENTS.md, CLAUDE.md, docs/Harness-Ledger.md until closeout | coordinator | current | progress.md | 1 | harness check --profile target-project . |

package/presets/legacy-migration/templates/findings.seed.md

@@ -0,0 +1,17 @@
+## Legacy Migration Action Buckets
+
+| Bucket | Count | Owner | Status | Next Action |
+| --- | ---: | --- | --- | --- |
+| warnings | {{warnings}} | coordinator | open | Triage before increasing target level |
+| taskActions | {{taskActions}} | coordinator | open | Upgrade only current/reopened/current-evidence tasks |
+| legacyResiduals | {{legacyResiduals}} | coordinator | open | Assign real owner before full cutover |
+
+## Residual Policy
+
+Residuals require reason, owner, trigger, next action, and reviewer. Placeholder owner `migration-owner` is not a real owner.
+
+## Status Conflict Table
+
+| Item | Competing Evidence | Chosen Classification | Confidence | Human Needed |
+| --- | --- | --- | --- | --- |
+| pending | session / SSoT / progress / git | pending | medium | yes |

package/presets/legacy-migration/templates/review.seed.md

@@ -0,0 +1,12 @@
+## Legacy Migration Preset Gate
+
+`migration-full-cutover` can only be claimed when the final session proves all gates:
+
+- final session result is `complete`
+- strict check passes
+- `migrate-verify --full-cutover` passes
+- warnings/actions/residuals/strictDeferred are zero
+- dashboard evidence is readable
+- review has no open P0/P1/P2 blocker
+
+Current achieved level: `{{migrationAchievedLevel}}`.

package/presets/legacy-migration/templates/task_plan.append.md

@@ -0,0 +1,9 @@
+## Legacy Migration Preset
+
+This Complex Task uses the `{{preset}}` preset package. The preset only scaffolds the migration task and records evidence at creation time. It does not run migration, rewrite historical task bodies, stage files, or commit changes.
+
+- Preset version: `{{presetVersion}}`
+- Baseline session: `{{evidenceBundle}}/session.json`
+- Migration plan: `{{evidenceBundle}}/migrate-plan.json`
+- Strict deferred: {{strictDeferred}}
+- Full-cutover claim allowed now: {{fullCutoverClaimAllowed}}

package/presets/legacy-migration/templates/visual_map.append.md

@@ -0,0 +1,12 @@
+## Legacy Migration Preset Flow
+
+```mermaid
+flowchart TD
+  A["Recorded migrate-run session"] --> B["Create Complex Task preset"]
+  B --> C["Baseline usable"]
+  C --> D{"User confirms deeper cutover?"}
+  D -- no --> E["Keep residuals owned"]
+  D -- yes --> F["Current work cutover"]
+  F --> G["Historical consolidation"]
+  G --> H["Strict / full-cutover verify"]
+```

package/presets/legacy-migration/workbench/dashboard-panels.yaml

@@ -0,0 +1,2 @@
+id: legacy-migration
+panels: [migration-queue, task-evidence, human-confirmation]

package/presets/legacy-migration/workbench/migration-queue.schema.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": "legacy-migration-queue/v2",
+  "staticDashboardRole": "evidence-snapshot",
+  "workbenchRole": "human-confirmation-control-plane",
+  "requiredItemFields": [
+    "taskId",
+    "phase",
+    "mechanicalState",
+    "semanticState",
+    "evidenceSources",
+    "reviewState",
+    "confirmationState",
+    "owner",
+    "residual"
+  ],
+  "allowedPhases": [
+    "baseline",
+    "mechanical-scaffold",
+    "semantic-reconstruction",
+    "cutover-review"
+  ],
+  "semanticRule": "Semantic reconstruction requires evidenceSources and cannot be marked complete by scaffold-only automation."
+}

package/presets/lesson-sedimentation/preset.yaml

@@ -0,0 +1,23 @@
+id: lesson-sedimentation
+version: 1
+purpose: Create a follow-up task for reviewing and sedimenting an accepted lesson candidate into a promoted detail doc.
+compatibleBudgets: [standard, complex]
+localeSupport: [en-US, zh-CN]
+task:
+  kind: lesson-sedimentation
+  projectLevelOnly: true
+entrypoints:
+  newTask:
+    type: template
+    writes: [docs/09-PLANNING/TASKS/**]
+    reads: [docs/09-PLANNING/TASKS/**/lesson_candidates.md]
+    audit: true
+    templates:
+      prompt: templates/prompt.md
+writeScopes:
+  taskDocs:
+    path: docs/09-PLANNING/TASKS/**
+    access: write
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-audit.json]

package/presets/lesson-sedimentation/templates/prompt.md

@@ -0,0 +1,23 @@
+You are executing a lesson sedimentation follow-up task.
+
+Source task: {{sourceTaskId}}
+Source candidate: {{candidateId}} - {{candidateTitle}}
+Follow-up task: {{followUpTaskId}}
+
+Candidate scope: {{candidateScope}}
+Candidate module key: {{candidateModuleKey}}
+Detail artifact: {{detailArtifact}}
+Boundary reason: {{boundaryReason}}
+Why it might matter: {{whyItMightMatter}}
+Promotion target: {{promotionTarget}}
+Conflict check: {{conflictCheck}}
+Required standard update: {{requiredStandardUpdate}}
+
+Instructions:
+
+1. Read the source task, its review, findings, progress, lesson_candidates.md, and the task-local detail artifact.
+2. Classify whether the lesson is task-local, module-local, or global; if module-local, preserve the module key/path.
+3. Check for conflicts with existing lesson candidates, promoted lesson detail docs, public docs, and relevant standards.
+4. Propose the smallest diff needed to preserve the lesson.
+5. Do not write a shared Lessons table; accepted candidates become promoted lesson detail docs or target standard updates.
+6. Record evidence and residual risks in the follow-up task before asking for review.

package/presets/module/preset.yaml

@@ -0,0 +1,25 @@
+id: module
+version: 1
+purpose: Create module-scoped tasks with module context entry points and auditable preset metadata.
+compatibleBudgets: [simple, standard, complex]
+localeSupport: [en-US, zh-CN]
+task:
+  kind: module-task
+entrypoints:
+  newTask:
+    type: template
+    writes: [docs/09-PLANNING/**]
+    audit: true
+    templates:
+      taskPlanAppend: templates/task_plan.append.md
+      executionStrategyAppend: templates/execution_strategy.append.md
+templateValues:
+  moduleKey:
+    from: task.moduleKey
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-audit.json]
+writeScopes:
+  planningDocs:
+    path: docs/09-PLANNING/**
+    access: write

package/presets/module/templates/execution_strategy.append.md

@@ -0,0 +1,8 @@
+## Module Preset Strategy
+
+| Field | Value |
+| --- | --- |
+| Module Key | {{moduleKey}} |
+| Module Plan | docs/09-PLANNING/MODULES/{{moduleKey}}/module_plan.md |
+
+Keep shared module decisions in the module plan or module context files. Keep task-specific evidence in this task directory.

package/presets/module/templates/task_plan.append.md

@@ -0,0 +1,17 @@
+## Module Preset
+
+This module task was created through the `module` preset.
+
+| Field | Value |
+| --- | --- |
+| Module Key | {{moduleKey}} |
+
+## Module Context Entry Points
+
+Read these module-level entry points before changing shared module behavior. Continue into narrower context only when the task surface requires it.
+
+| Reference | Path | Why / When |
+| --- | --- | --- |
+| Module brief | docs/09-PLANNING/MODULES/{{moduleKey}}/brief.md | Start here for the module purpose and current scope. |
+| Module plan | docs/09-PLANNING/MODULES/{{moduleKey}}/module_plan.md | Use this for module steps, active task links, and handoff state. |
+| Module visual map | docs/09-PLANNING/MODULES/{{moduleKey}}/visual_map.md | Inspect when the change affects module sequencing or dependencies. |

package/presets/standard-task/preset.yaml

@@ -0,0 +1,31 @@
+id: standard-task
+version: 1
+purpose: Create a standard task using the generic declarative preset engine.
+compatibleBudgets: [standard, complex]
+localeSupport: [en-US, zh-CN]
+task:
+  kind: standard-task
+  defaultTaskId: standard-task
+entrypoints:
+  newTask:
+    type: template
+    writes: [docs/09-PLANNING/TASKS/**]
+    audit: true
+    templates:
+      taskPlanAppend: templates/task_plan.append.md
+templateValues:
+  title:
+    from: task.title
+evidence:
+  bundleDir: artifacts/preset
+  files:
+    presetAudit:
+      path: preset-audit.json
+      type: preset-audit
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-audit.json]
+writeScopes:
+  taskDocs:
+    path: docs/09-PLANNING/TASKS/**
+    access: write

package/presets/standard-task/templates/task_plan.append.md

@@ -0,0 +1,7 @@
+## Standard Task Preset
+
+This task was created through the declarative `standard-task` preset.
+
+| Field | Value |
+| --- | --- |
+| Preset Title | {{title}} |

package/references/adversarial-review-standard.md

@@ -102,7 +102,7 @@ Reviewer 必须以找问题为目标，而不是证明实现正确。
 - Progress:
 - Findings:
 - Regression SSoT:
-- Lessons SSoT:
+- Lesson Candidates / Detail Docs:
 - Walkthrough:
 ```
 
@@ -150,7 +150,7 @@ Review loop 的固定执行形态：
 - `progress.md` 记录审查发生的时间和处理结果摘要
 - `findings.md` 记录审查中产生的技术决策或研究发现
 - `Regression-SSoT.md` 记录新增或调整的 regression surface
-- `Lessons-SSoT.md` 记录可复用的流程、架构或标准改进建议
+- `lesson_candidates.md` 和 `docs/01-GOVERNANCE/lessons/*.md` 记录可复用的流程、架构或标准改进建议
 - `walkthrough` 收口时引用 `review.md` 的 material finding 状态和 no-finding 结论
 - `Harness Ledger` 记录本轮是否完成 review report
 

package/references/agents-md-pattern.md

@@ -40,7 +40,7 @@ AGENTS.md 只包含两类内容：
   先读 docs/11-REFERENCE/harness-ledger-standard.md
 
 - Walkthrough / Closeout / Lessons 收口：
-  先读 docs/11-REFERENCE/walkthrough-standard.md，然后读 docs/01-GOVERNANCE/Lessons-SSoT.md 和 docs/10-WALKTHROUGH/Closeout-SSoT.md
+  先读 docs/11-REFERENCE/walkthrough-standard.md，然后读 docs/10-WALKTHROUGH/Closeout-SSoT.md、任务本地 lesson_candidates.md 和 docs/01-GOVERNANCE/lessons/
 
 - 开发执行 / 回写流程：
   先读 docs/11-REFERENCE/execution-workflow-standard.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 的完整规则，避免两份入口文件漂移。
 
@@ -100,7 +100,7 @@ CLAUDE.md 控制在 **10-50 行**。它只做 Claude Code 兼容入口，不应
 - agent 做后端重构时，不会被前端规范干扰
 - agent 做测试时，不会被文档治理规则分心
 - 每种任务类型只加载它需要的上下文
-- agent 写 walkthrough 时会被入口显式路由回 Lessons SSoT，但 Lessons 全文不会塞进 AGENTS.md
+- agent 写 walkthrough 时会被入口显式路由回 lesson candidate / detail doc 流程，但 Lessons 全文不会塞进 AGENTS.md
 
 这跟 OpenAI 在 Harness Engineering 实践中得出的结论一致：给 agent 一张地图，不给一本千页手册。
 
@@ -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/delivery-operating-model-standard.md

@@ -39,7 +39,7 @@ Define who breaks roadmap work into feature blocks:
 | Level | Owner | Artifact | Rule |
 |-------|-------|----------|------|
 | Roadmap | [owner] | [SSoT / issue tracker] | [how priority is chosen] |
-| Feature block | [owner] | `Delivery-SSoT.md` / Feature SSoT | [how blocks are bounded] |
+| Feature block | [owner] | `Delivery-SSoT.md` / generated Harness Ledger | [how blocks are bounded] |
 | Task | [owner] | `docs/09-PLANNING/TASKS/<task>/task_plan.md` | [who can start work] |
 | Review | [owner] | `review.md` / PR review | [required reviewers] |
 | Integration | [owner] | PR / release branch / integration branch | [merge order] |
@@ -50,14 +50,14 @@ Define who breaks roadmap work into feature blocks:
 
 Use when one human directs multiple agents across worktrees.
 
-- One primary Feature SSoT is enough for linear phase work.
+- One generated Harness Ledger is enough for ordinary task lifecycle tracking.
 - Worktree concurrency is central.
 - Merge order is human-decided.
 - Cross-task conflicts are managed by task ownership and shared-file notices.
 
 **模块并行扩展**：当项目有 2+ 个可独立演进的功能域时，启用模块并行开发（见 `references/module-parallel-standard.md`）。此时：
 
-- Module Registry 替代 Feature SSoT 作为进度追踪的主要工具
+- Module Registry 管模块边界；Harness Ledger 生成全局任务生命周期索引
 - 每个模块一个长期 worktree（`codex/<module-key>`）
 - 模块间通过 write scope 声明避免冲突
 - 跨模块修改走独立的基础设施 task

package/references/docs-directory-standard.md

@@ -8,22 +8,21 @@
 
 ```
 docs/
-├── Harness-Ledger.md           ← 全局 harness 上下文回写总账
+├── Harness-Ledger.md           ← CLI 生成的任务生命周期总账
 ├── 00-RAW-PRDS/              ← 原始需求文档、PRD、用户故事
 │   └── _archive/              ← 本层历史文档归档（如该层会增长）
 ├── 01-GOVERNANCE/             ← 项目治理规则、决策记录、经验沉淀
-│   ├── Lessons-SSoT.md        ← 经验沉淀建议表
-│   ├── lessons/               ← 具体沉淀内容
+│   ├── lessons/               ← promoted lesson 详情文档
 │   └── _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/              ← 本层历史文档归档（如该层会增长）
@@ -34,9 +33,8 @@ docs/
 │   │   └── _task-template/    ← 任务模板
 │   ├── MODULES/               ← 模块并行开发计划（启用时）
 │   │   └── _archive/          ← 已完成 / 暂停过久模块归档
-│   ├── _archive/              ← 历史任务、旧 Feature SSoT 明细、过期排期归档
+│   ├── _archive/              ← 历史任务、旧生命周期表明细、过期排期归档
 │   ├── Delivery-SSoT.md       ← 多人 / 多仓 / 传统流程下的交付排期和集成顺序
-│   └── [Feature-SSoT].md     ← 实施排期表
 ├── 10-WALKTHROUGH/            ← Walkthrough 收口记录与 Closeout SSoT
 │   └── _archive/              ← 历史 walkthrough 批量归档（迁移 / 年度收束时）
 ├── 11-REFERENCE/              ← 标准文件（agent 按需加载）
@@ -72,6 +70,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。
+
 ## 通用归档规则
 
 归档是目录级基础设施，不是单张表的特例。任何会持续增长的目录都应该有同级
@@ -90,11 +131,11 @@ docs/
 
 | 对象 | 触发条件 | 归档位置 |
 |------|----------|----------|
-| Feature SSoT Active 表 | 模块并行切换、release 完成、或 completed rows 超过 20 条 | `09-PLANNING/_archive/` |
+| Legacy Feature / Private Feature 生命周期表 | 迁移到 ledger-only 版本 | `09-PLANNING/_archive/` |
 | Delivery SSoT | 集成 wave 结束或 completed/superseded blocks 超过 20 条 | `09-PLANNING/_archive/` |
 | Module Registry / module_plan | 模块 completed 或 paused 超过 60 天 | `09-PLANNING/MODULES/_archive/<key>/` |
 | Regression SSoT | gate 废弃或长期不再运行 | `05-TEST-QA/_archive/` |
-| Lessons SSoT | merged/rejected 条目超过 20 条 | `01-GOVERNANCE/_archive/` |
+| Lesson detail docs | merged/rejected/superseded 详情文档超过 20 条 | `01-GOVERNANCE/_archive/` |
 | Harness Ledger | closed/superseded 超过 50 条 | `01-GOVERNANCE/_archive/` |
 | Walkthrough | 年度/阶段迁移或目录过大 | `10-WALKTHROUGH/_archive/` |
 
@@ -108,11 +149,13 @@ docs/
 | execution-workflow-standard.md | 开发执行流程、commit 规范、PR 流程 | 是 |
 | delivery-operating-model-standard.md | 工程组织形态、feature block 拆分、跨仓/团队协作模型 | 是 |
 | repo-governance-standard.md | repo platform、branch protection、PR policy、required checks、worktree concurrency | 是 |
+| pull-request-standard.md | PR 描述结构、中英双语要求、版本影响、验证、审查证据、残余风险和引用 | 是 |
 | ci-cd-standard.md | CI/CD profile、workflow、required checks、release/CD residual | 是 |
 | long-running-task-standard.md | 长程任务合同、连续执行权限、review loop、停止条件 | 是 |
 | 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 写作规范 | 是 |