frontend-project-context 1.0.1 → 1.3.0

package/docs/17-AI-EXCHANGE-BOUNDARY-DESIGN.md

@@ -0,0 +1,270 @@
+# 17 — `1.2.0` AI Exchange Boundary 设计
+
+> 权威说明：本文定义项目与现有 AI 编程工具之间的模型无关双向交换边界；如与 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md) 冲突，以产品宪法为准。
+>
+> 状态：`published-public-npm-verified; A-56-through-A-63-and-full-69-test-suite-passed`
+>
+> 设计基线：`frontend-project-context@1.1.0` 本地完整性修正、Assist Bundle schema 1、A-01 至 A-55、B0-01/B0-02、CLI 与发布工件共 61 项通过。
+
+## 1. 决定
+
+Frontend Project Context 的主要职责是成为项目与 AI 编程工具之间的桥梁。现有内核已稳定完成“项目 → AI”的治理、编译和投影，`1.1.0` 也已能以 Assist Bundle 向外部 Agent 输出 setup/sync 工作单元。但“AI → 项目”仍依赖宿主自行拼装多个 CLI 参数，没有统一、可验证、可分组审查的机器合同。
+
+因此产品内核增加第七项：**AI Exchange Boundary**。
+
+它只扩展桥接协议，不扩展为 Provider wrapper、Agent Runtime 或任务执行系统。
+
+## 2. 双向桥梁合同
+
+```text
+项目来源
+→ 人工治理的 Project Contract
+→ Context / Assist Bundle
+→ 现有 AI 编程工具
+→ Action Plan
+→ 确定性 Preflight / Review Bundle
+→ 人明确批准具体 action、ID 和路径
+→ 复用现有细粒度安全写命令
+→ 新的 Project Contract / projection
+```
+
+桥梁的责任边界是：
+
+1. 把项目知识编译成 AI 可消费的最小、可追溯上下文；
+2. 把 AI 的建议收敛为实例化、可预检、可人工审查的 action；
+3. 用 schema、snapshot、digest、scope、impact 和 ownership 限制 action；
+4. 在人批准后仍复用已验收的细粒度命令，不新建一个隐式权限更大的批处理写入器。
+
+## 3. 内核与适配器的分界
+
+### 3.1 归入内核
+
+- Assist Bundle 的机器可读 schema、版本和完整工作单元；
+- 模型无关 Action Plan schema；
+- 纯预检的 Review Bundle；
+- 公开 capability 与 protocol version 描述；
+- 对现有 register/propose/accept/revise/deprecate/approve/publish 原语的结构化映射；
+- 人工批准前的完整差异、baseline、impact、blocker 和路径集。
+
+### 3.2 仍属适配器
+
+- Codex Skill、Claude instruction、MCP Server、IDE 插件或 AGENTS 触发说明；
+- 把用户自然语言转换成 `setup`、`sync`、`context` 或 Action Plan 的宿主逻辑；
+- 外部 CI 从 Git 或平台事件获取 changed path 的逻辑。
+
+适配器可以根据不同 AI 工具替换；内核 schema、安全性和人工权限不随模型改变。
+
+## 4. 新增公共入口
+
+### 4.1 `capabilities`
+
+```text
+project-context capabilities --project PATH [--json]
+```
+
+永远只读，对未初始化和已初始化项目都可用。JSON 固定返回：
+
+- package version 与 exchange protocol version；
+- Contract/proposal/lock/renderer/dashboard/Assist/Action Plan/Review Bundle schema version；
+- 当前可用命令与 action kind；
+- initialized 状态和已初始化项目的 ID/name；
+- 永久边界：无 Provider、无 Agent Runtime、无 Git、无自动批准、无业务代码写入。
+
+输出必须从实现常量派生，不另存 capability 配置文件。
+
+### 4.2 `preflight`
+
+```text
+project-context preflight --project PATH --plan FILE [--json]
+```
+
+`preflight` 只读 Action Plan，不接受 `--write`、`--by`、`--approve`、`--ids` 或任何授权参数。它必须：
+
+1. 验证 Action Plan schema 与 project ID；
+2. 验证三个 project snapshot baseline；
+3. 对每个 action 复用现有纯 preview/helper；
+4. 计算 exact item/source/path/projection impact；
+5. 把相同人工决策类型稳定分组；
+6. 输出 Review Bundle 和结构化 invocation，不输出可直接 shell 执行的拼接字符串；
+7. 任一 action 不可审查时整份 plan 标记 blocked，但不隐藏其他 action 的预检结果。
+
+`1.2.0` 不新增 `apply-plan`。人工批准后，宿主根据 Review Bundle 中已展示的结构化 invocation 调用现有细粒度命令；任一 baseline 失效立即停止并重新 `sync`/`preflight`。
+
+## 5. Action Plan schema 1
+
+Action Plan 是由外部 AI 或其他调用方产生的短生命周期输入，不是 store，不是 Contract，不自带权限。
+
+```json
+{
+  "schemaVersion": 1,
+  "projectId": "project-id",
+  "baselines": {
+    "contract": "sha256:...",
+    "sourcesLock": "sha256:...",
+    "projectionsLock": "sha256:..."
+  },
+  "actions": [
+    {
+      "id": "action-revise-ui-copy",
+      "kind": "revise-item",
+      "input": {}
+    }
+  ]
+}
+```
+
+固定规则：
+
+- action ID 在当前 plan 中唯一且稳定；
+- `actions` 非空，按 ID 规范排序后计算 plan digest；
+- 拒绝未知字段、未知 action kind、重复 ID 和非项目内路径；
+- action 不得包含 `write`、`by`、`approval`、Provider 配置、shell command 或 AI 推理正文；
+- action 只表达建议，不表达人已批准。
+
+### 5.1 action kind
+
+| kind | 复用现有原语 | 必须携带的主要 baseline |
+| --- | --- | --- |
+| `register-source` | `register` preview | contract/source locator |
+| `propose-item` | `propose` preview | contract + proposal output path |
+| `accept-source-change` | `review-source` + `accept-source-change` preview | contract、source object、locked/current digest、affected IDs |
+| `revise-item` | `revise` preview | contract + current item digest |
+| `deprecate-item` | `deprecate` preview | contract + current item digest |
+| `deprecate-source` | `deprecate-source` preview | contract、source object digest、affected IDs |
+| `request-item-approval` | `approve` preview | proposal/pending item ID + contract/proposal baseline |
+| `publish-projection` | `publish` preview | contract + projection lock/ownership baseline |
+
+`input` 使用对应原语已公开的类型化参数，不复制第二套 scope、source、item 或 projection 解析器。
+
+## 6. Review Bundle schema 1
+
+```json
+{
+  "schemaVersion": 1,
+  "projectId": "project-id",
+  "planDigest": "sha256:...",
+  "baselines": {},
+  "status": "reviewable | blocked",
+  "summary": {
+    "actions": 0,
+    "reviewable": 0,
+    "blocked": 0,
+    "groups": 0
+  },
+  "actions": [],
+  "groups": [],
+  "findings": [],
+  "invocations": []
+}
+```
+
+每个 action 结果必须包含：
+
+- action ID/kind 和 `reviewable | blocked` 状态；
+- exact current/proposed 差异；
+- source/item/path/projection ID 影响集；
+- action 特定 baseline 与 blocker；
+- `humanApprovalRequired: true`；
+- 若可审查，一份 `{ command, args }` 结构化 invocation，不包含 `--write`、`--by` 或任何人类身份伪造。
+
+`groups` 至少分为 source change、new/revised knowledge、deprecation、approval request、projection 和 blocker。每组只可引用已完整展示的 action ID，不得用“全部后续变化”之类开放授权。
+
+## 7. 机器可读 schema 发布
+
+`1.2.0` 应在 npm 包中公开：
+
+```text
+schemas/capabilities.schema.json
+schemas/assist-bundle.schema.json
+schemas/action-plan.schema.json
+schemas/review-bundle.schema.json
+```
+
+schema 文件是交换形式的机器合同，不是项目真源。运行时验证与 schema 必须由同一组常量和验证规则产生或交叉验收，不允许文档与代码漂移。
+
+Contract、proposal、source lock、projection lock、renderer 和 Dashboard schema 不因此变更。
+
+## 8. 权限、并发与失败恢复
+
+- `capabilities`、`setup`、`sync`、`context`、`preflight` 可被 Agent/CI 自动调用，但不产生持久权限；
+- Action Plan 即使由人提供，也只是待审查建议；
+- Review Bundle 不是 approval receipt，不能被原命令解释为已授权；
+- 人必须根据已展示内容明确批准具体 action/ID/path，宿主才可补入已授权的 `--write`、`--by` 和 rationale；
+- 每个写命令继续使用自身 baseline 和原子写；
+- 任一写入后 project snapshot 变化，未执行的旧 invocation 全部失效，必须重新 `sync`/`preflight`；
+- 不引入全局 rollback、自动重放或跨命令事务。
+
+## 9. 错误类别
+
+| code | 退出码 | 含义 |
+| --- | --- | --- |
+| `action-plan-schema-invalid` | 2 | plan 字段、kind 或类型非法 |
+| `action-plan-project-mismatch` | 2 | plan project ID 与当前项目不同 |
+| `action-plan-baseline-changed` | 1 | plan snapshot 已过期，需重新 sync/preflight |
+| `action-plan-conflict` | 1 | action 内部重复、依赖循环或互相冲突 |
+| `action-preflight-blocked` | 1 | 对应现有原语预检失败 |
+
+能用现有稳定错误精确表达的情况必须直接复用，不创建同义错误。
+
+## 10. 兼容与版本
+
+- package 目标版本为 `1.2.0`，因为新增公共 CLI、机器 schema 和内核桥接协议；
+- `1.1.0` Assist Bundle 保持 schema 1，`1.2.0` 只补充机器 schema 文件与交叉验证；
+- 旧项目不需要 store migration；
+- 所有旧命令、参数和退出码保持兼容；
+- 旧 Host Agent 可继续直接调用原命令，不强制生成 Action Plan；
+- npm 包将 `schemas/` 加入白名单，不加入项目动态状态。
+
+## 11. 唯一实现范围
+
+| 文件 | 允许变更 |
+| --- | --- |
+| `src/project-context/exchange-schema.mjs` | Action Plan 与 Review Bundle 类型验证、稳定规范化 |
+| `src/project-context/exchange.mjs` | capabilities、preflight 聚合、分组和 structured invocation |
+| `src/project-context/assist.mjs` | 仅为机器 schema 交叉验收暴露必要常量；不改变 `1.1.0` 语义 |
+| `src/project-context/cli.mjs` | 新增 `capabilities`/`preflight` 及严格 allowlist |
+| `schemas/*.schema.json` | 四份公开交换 schema |
+| `test/project-context/exchange.test.mjs` | A-56 至 A-63 |
+| `README.md`、`docs/04`、`docs/05`、`docs/08`、`UPGRADING.md`、`CHANGELOG.md` | 实现后同步真实行为 |
+| `package.json` | 实现后升至 `1.2.0` 并发布 `schemas/` |
+
+不新建数据库、索引、缓存、Provider client、Agent loop、shell executor、Git 读取、scheduler、daemon、watcher、业务代码修改器或自动批准器。
+
+## 12. 冻结验收 A-56 至 A-63
+
+- **A-56 capability 可发现性**：未初始化/已初始化项目输出确定性 capability，版本、schema、action kind 和永久边界与代码一致，零写入。
+- **A-57 Action Plan schema**：合法 plan 稳定规范化；未知字段/kind、重复 ID、越界路径、权限字段和 shell 字符串失败封闭。
+- **A-58 原语复用**：八类 action 全部复用现有 schema/helper/preview，不存在第二套 scope、impact、source 或 projection 语义。
+- **A-59 Review Bundle 完整性**：精确 current/proposed、baseline、item/source/path/projection 影响、blocker、分组和 structured invocation 稳定且无遗漏。
+- **A-60 人工权限**：capabilities/preflight/plan/review 均不写 store/projection/业务文件，不产生 approval，invocation 不包含 write/by。
+- **A-61 baseline 与恢复**：三个 snapshot 或 action-specific digest 变化必须阻断旧 plan；重新 sync/preflight 可收敛，不重放旧计划。
+- **A-62 机器 schema 一致性**：四份发布 schema 验证实际 fixture 输入/输出，package whitelist 包含它们且不包含动态项目状态。
+- **A-63 兼容与永久边界**：A-01 至 A-55、B0/CLI/发布工件全部继续通过；零 Provider、Agent Runtime、Git、network、child process、dependency install、scheduler、daemon、自动批准或业务代码修改。
+
+实现 Gate：八项新验收全部通过，全量 `npm run check` 预期为 69/69；README/help/schema 足以让一个不同模型的宿主在不依赖内部代码的情况下生成 Action Plan 并理解 Review Bundle。这是协议可用性验收，不伪称已内置或运行任何真实 Host Agent。
+
+## 13. 明确不做
+
+- 不调用 OpenAI、Anthropic、Gemini 或其他 Provider；
+- 不实现 Agent Runtime、prompt runner、tool loop 或自然语言路由器；
+- 不新增 `apply-plan` 或批量隐式授权；
+- 不把 AI 建议、Review Bundle 或对话保存为第二真源；
+- 不读取 Git diff，不管理 hook、commit、branch、PR 或 CI 平台；
+- 不根据新框架、文件名或单项目差异扩大 discovery；
+- 不运行项目验证命令、不修改业务代码；
+- 不用本设计授权真实项目访问、网络、打包、Git 写入或 npm 发布。
+
+## 14. 实现结果与停止条件
+
+`1.2.0` 已按本文冻结范围完成本地实现：
+
+- `capabilities` 在未初始化、partial 和已初始化项目中确定性返回实现常量派生的能力、schema 与永久边界；
+- `exchange-schema.mjs` 严格验证并稳定规范化 Action Plan schema 1，拒绝未知/权限/执行字段、重复 action、未知 kind 和项目外路径；
+- `exchange.mjs` 对八类 action 复用既有原语进行纯预检，输出 Review Bundle schema 1、精确 impact、blocker、稳定 group 和结构化 invocation；
+- approval/deprecation 只在内部借用既有 preview 语义进行验证，对外 proposed intent 明确要求人类身份与执行时间，不暴露内部 sentinel、不形成 approval；
+- `schemas/` 发布 capabilities、Assist Bundle、Action Plan 与 Review Bundle 四份机器合同，npm 白名单继续排除动态项目状态和自托管 store；
+- A-56 至 A-63 和全部旧验收共 69/69 通过，store schema、renderer、Dashboard 与旧 CLI 无迁移和无回归。
+
+用户于 2026-09-09 单独授权进入 `1.2.0` 发布流程。冻结候选 prepack 69/69 通过，官方 registry public 发布成功，`latest` 指向 `1.2.0`；registry tarball 与候选逐字节一致，直接安装后的 help、capabilities、init 与 clean check 冒烟通过。`v1.2.0` 精确指向冻结候选提交 `c991187c4dfd094d9cff5a4e15516fb25d74d803`。
+
+本阶段至此停止，发布授权已经消耗。Provider、Agent Runtime、`apply-plan`、自动批准/修复、业务代码执行、Git 管理、网络能力、依赖安装、scheduler、daemon、真实项目访问和后续发布仍未授权；构建、测试或本次发布成功不会扩大这些永久边界。

package/docs/18-BRANCH-AWARE-STAGED-CONTEXT-DESIGN.md

@@ -0,0 +1,348 @@
+# 18 — `1.3.0` Branch-aware Staged Context & Handoff 设计
+
+> 权威说明：本文定义 AI Exchange Boundary 之上的可选附带能力，用于帮助现有 Coding Agent 以更小、更准确、可分阶段恢复的上下文完成目标功能；如与 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md) 冲突，以产品宪法为准。
+>
+> 状态：`implemented-locally; A-64-through-A-73-passed; release-not-authorized`
+>
+> 基线：`frontend-project-context@1.2.0` 已公开发布并独立验证；Project Contract 身份、七项内核、人工权限和永久边界保持不变。
+
+## 1. 用户问题
+
+团队采用“一个需求一个分支”的开发方式。一个需求通常不能一步完成，需要经历理解、实现、局部验证、修正和合并审查等多个阶段。当前 Coding Agent 容易在长对话中反复读取完整项目说明、历史讨论、代码和验证日志，导致：
+
+- 上下文超过宿主窗口后被压缩；
+- 无关叙述稀释当前目标、项目约束和验收条件；
+- 换窗口、换模型或换同事后重复解释任务现场；
+- AI 只看见代码差异，却不知道修改原因、已确认决定和未完成项；
+- 分支合入主分支前，代码冲突、Contract 基线变化和语义重叠没有统一的上下文审查入口；
+- 每个任务的临时描述如果长期累积，会反向污染 Project Contract 和后续会话。
+
+该问题的目标不是“保存更多上下文”，而是让现有 Coding Agent 在每个阶段只获得完成当前功能所需的最小、准确、可追溯上下文。
+
+## 2. 产品定位与分类
+
+本能力分类为 **可选适配器协议**，不是第八项内核，也不改变 Project Contract 的唯一真源地位。
+
+```text
+人工批准的 Project Contract
++ 宿主提供的 Task Context Plan
++ 宿主提供的 changed paths / revision labels
++ 前序 Stage Receipts
+→ 当前 Stage Context Bundle
+→ 现有 Coding Agent 执行开发任务
+→ 宿主提交新的 Stage Receipt
+→ Integration Review Bundle
+→ 人工决定是否合并或把长期事实提案到 Project Contract
+```
+
+Frontend Project Context 只验证机器合同、核对 baseline、复用 Scope Compiler 选择合同项、生成最小派生 Bundle 和报告冲突。任务拆分、代码修改、命令执行、测试结论、Git 操作和最终功能判断仍由外部 Coding Agent、现有工具和人负责。
+
+## 3. 成功定义
+
+本能力成功时：
+
+1. 一个需求可以由一个模型无关 Task Context Plan 表达为多个有依赖的 Stage；
+2. 每次只编译当前 Stage，前序过程只以结构化 receipt 进入上下文；
+3. Project Contract、任务目标、当前路径、验收条件和必要证据不会在压缩或换窗口后丢失；
+4. 输出有调用方显式提供的确定性字节预算，不存在隐式无限全文模式；
+5. 分支路径只是宿主提供的候选范围信号，不被自动提升为来源或长期规则；
+6. 合并前可以只读比较任务基线、主分支变化、分支变化和阶段完成证据；
+7. 合并后任务工件不会自动进入 Contract，只有人工明确选择的长期事实继续复用既有 `propose`/`approve`；
+8. 同一输入产生同一 Bundle，过期 baseline、缺失依赖和冲突均失败封闭。
+
+## 4. 非目标与永久边界
+
+本阶段不实现：
+
+- Provider、Agent Runtime、planner、任务执行器或自动循环；
+- 自动把自然语言需求拆成 Stage；
+- 修改、生成、验证或修复业务代码；
+- 执行测试、构建、lint、shell 或项目脚本；
+- 读取 Git diff、branch、commit、merge-base、PR 或远端平台；
+- checkout、rebase、merge、commit、push 或 Git hook；
+- scheduler、daemon、watcher、任务队列或多人锁；
+- 自动接受 source、批准 Contract、解决冲突或晋升长期事实；
+- 新的持久 store、聊天记录、AI 推理库、向量库或第二真源；
+- 精确模拟不同模型的 tokenizer。
+
+宿主可以只读调用 Git 或平台 API，再把规范化后的相对路径和不透明 revision label 显式传入；该行为属于宿主适配器，不属于产品内核。
+
+## 5. 机器合同
+
+`1.3.0` 公开四份 schema version 1：
+
+1. `task-context-plan.schema.json`
+2. `stage-receipt.schema.json`
+3. `stage-context-bundle.schema.json`
+4. `integration-review-bundle.schema.json`
+
+它们都是短生命周期交换合同，不是 store、Project Contract、approval、Git 事实或持久执行权限。`capabilities` 必须公开版本、命令、预算单位和永久边界。
+
+## 6. Task Context Plan schema 1
+
+Task Context Plan 由外部 Coding Agent、人或其他宿主生成，Frontend Project Context 只负责严格验证和稳定规范化。
+
+最小结构：
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "task-context-plan",
+  "projectId": "example-project",
+  "task": {
+    "id": "task-multi-segment-dialog",
+    "title": "非协议价弹窗支持多航段",
+    "goal": "在保持单航段行为不变的前提下展示多个航段",
+    "acceptance": [
+      { "id": "acceptance-single-segment", "text": "单航段行为保持不变" },
+      { "id": "acceptance-multi-segment", "text": "多航段按顺序完整展示" }
+    ]
+  },
+  "workspace": {
+    "branchLabel": "feature/multi-segment-dialog",
+    "baseRevision": "opaque-host-provided-value"
+  },
+  "snapshots": {
+    "contract": "sha256:...",
+    "sourcesLock": "sha256:...",
+    "projectionsLock": "sha256:..."
+  },
+  "budget": {
+    "maxUtf8Bytes": 12000,
+    "maxReadTargets": 12
+  },
+  "stages": [
+    {
+      "id": "stage-understand",
+      "title": "理解与定位",
+      "objective": "确认数据结构、渲染入口和回归范围",
+      "dependsOn": [],
+      "paths": ["src/components"],
+      "acceptanceIds": ["acceptance-single-segment"]
+    },
+    {
+      "id": "stage-render",
+      "title": "实现多航段渲染",
+      "objective": "完成最小渲染闭环",
+      "dependsOn": ["stage-understand"],
+      "paths": ["src/components/protocol-price-dialog.vue"],
+      "acceptanceIds": ["acceptance-single-segment", "acceptance-multi-segment"]
+    }
+  ]
+}
+```
+
+冻结规则：
+
+- 顶层和所有嵌套对象拒绝未知字段；
+- task、acceptance、stage ID 稳定且唯一；
+- `dependsOn` 必须引用存在的 stage，不允许循环；
+- 每个 stage 必须有单一 objective、至少一个项目内相对 path 和 acceptance ID；
+- path 拒绝绝对路径、`..`、项目外 realpath 和重复规范化结果；
+- 同一 plan 内没有依赖关系但 path 相同或祖先/后代重叠的 stages 报告并发范围冲突；
+- workspace 字段是不透明宿主标签，不证明 Git 状态；
+- snapshots 必须来自当前项目公开摘要；
+- budget 必须显式提供，`maxUtf8Bytes` 和 `maxReadTargets` 均为正整数；
+- 拒绝 `write`、`approve`、`by`、token、secret、shell、command、provider、autoRun 或其他权限/执行字段。
+
+## 7. Stage Receipt schema 1
+
+Stage Receipt 是宿主对外部执行结果的结构化陈述，不是产品自己运行测试后产生的证明，也不授予下一步权限。
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "stage-receipt",
+  "projectId": "example-project",
+  "taskId": "task-multi-segment-dialog",
+  "stageId": "stage-understand",
+  "planDigest": "sha256:...",
+  "inputBundleDigest": "sha256:...",
+  "status": "completed",
+  "changedPaths": [],
+  "acceptanceResults": [
+    {
+      "id": "acceptance-single-segment",
+      "status": "observed",
+      "evidence": ["src/components/protocol-price-dialog.vue"]
+    }
+  ],
+  "verificationResults": [],
+  "decisions": ["保留单航段渲染分支"],
+  "openIssues": [],
+  "nextStageId": "stage-render"
+}
+```
+
+冻结规则：
+
+- status 只允许 `completed` 或 `blocked`；
+- receipt 必须绑定 project、task、stage、plan digest 和输入 Bundle digest；
+- changed/evidence path 使用与 plan 相同的项目内路径规则；
+- acceptance result 只能引用 plan 中当前 stage 的 acceptance ID；
+- verification result 只记录宿主提供的 ID、状态、摘要和证据引用，不含可执行 shell；
+- completed 必须覆盖当前 stage 的全部 acceptance ID，blocked 必须有至少一个 open issue；
+- receipt 不代表人类接受功能、不代表 Contract approval，也不能自动触发下一 Stage；
+- 产品不写、覆盖、归档或删除 receipt。
+
+## 8. `stage-context` 命令
+
+```text
+project-context stage-context --project PATH --plan FILE --stage STAGE_ID
+  [--receipt FILE...] [--changed-path RELATIVE_PATH...] [--json]
+```
+
+命令永远只读，并按以下顺序执行：
+
+1. 读取并验证当前 Project Contract 与三个 store snapshot；
+2. 验证并稳定规范化 Task Context Plan；
+3. 验证 plan project ID、三个 snapshot 和所有 receipt baseline；
+4. 解析目标 stage，检查依赖 receipt 是否完整；
+5. 验证显式 changed path，只把它作为候选范围信号；
+6. 使用 stage paths、changed paths 与现有 Scope Compiler 选择已批准 Contract items；
+7. 汇总 task goal、当前 objective、acceptance、依赖 receipt 摘要、冲突和精确 read targets；
+8. 按预算优先级生成 Stage Context Bundle；
+9. 输出稳定 digest、预算使用和 `ready | blocked` 状态。
+
+产品不得读取 path 对应源码正文或 Git diff。AI 按 `readTargets` 渐进读取真正需要的代码片段。
+
+## 9. Stage Context Bundle schema 1
+
+Bundle 必须包含：
+
+- project/task/stage identity；
+- plan digest 和三个 project snapshots；
+- task goal、当前 stage objective、acceptance；
+- 完整的依赖 stage receipt 摘要；
+- 当前 stage paths 和调用方 changed paths；
+- 适用的 approved Contract item ID、kind、scope、value/statement 和 source ID；
+- readTargets、findings、明确排除项；
+- budget limit、used bytes、read target count；
+- `ready | blocked` 状态和稳定 bundle digest。
+
+预算优先级固定为：
+
+1. identity、goal、objective、acceptance、snapshot 和 blocker；
+2. 适用的人工批准 Contract items；
+3. 前序 receipt 的完成状态、决定、未解决问题和证据引用；
+4. readTargets 和 changed paths；
+5. 可省略的辅助说明。
+
+必需内容不得截断、改写或摘要。若前四类必要内容无法放入 `maxUtf8Bytes` 或 readTargets 超过限制，Bundle 必须 blocked，并报告 `context-budget-insufficient` 或 `read-target-budget-insufficient`；调用方只能进一步收窄 stage/path 或显式提高预算。不得静默丢失 Contract item、acceptance 或 blocker。
+
+核心只计算规范 UTF-8 字节，不声称等于任一模型 token。宿主适配器可以在此基础上实施模型特定 token 上限，但不能改变 Bundle 语义。
+
+## 10. 分阶段恢复规则
+
+- 没有依赖的 stage 可被显式选择；产品不自动选择“下一步”；
+- 有依赖的 stage 只有在全部依赖 receipt 为 completed、baseline 匹配且 acceptance 覆盖完整时才 ready；
+- blocked receipt 保留阻塞事实，但不能解锁后续 stage；
+- plan digest、Contract snapshot 或依赖 Bundle digest 变化时，旧 receipt 立即 stale；
+- 换窗口、换模型或换同事只需重新提供 plan、当前 stage、有效 receipts 和 changed paths，不携带聊天历史；
+- 前序 stage 的源码正文、完整 diff、完整验证日志和对话不得进入 Bundle；
+- replan 由宿主产生一份新 plan，旧 receipt 只作为外部历史证据，不自动迁移。
+
+## 11. `integration-review` 命令
+
+```text
+project-context integration-review --project PATH --plan FILE
+  [--receipt FILE...]
+  [--main-changed-path RELATIVE_PATH...]
+  [--branch-changed-path RELATIVE_PATH...]
+  [--json]
+```
+
+所有 revision 和 changed path 都由宿主显式提供；产品不调用 Git。命令永远只读，并输出 Integration Review Bundle：
+
+- 当前 Project Contract 与 plan snapshot 是否一致；
+- 全部 stage 是否具有有效 completed receipt；
+- main/branch exact path 和祖先/后代范围重叠；
+- 两组路径经 Scope Compiler 映射后的 Contract item 重叠；
+- source drift、pending item、Contract conflict 和 projection finding；
+- receipt 声明的 out-of-stage changed path；
+- 需要渐进读取的冲突路径和来源；
+- 可以由人考虑晋升为长期事实的 decision candidates；
+- `reviewable | blocked` 状态。
+
+## 12. 合并冲突分类
+
+| 类别 | 判定 | 结果 |
+| --- | --- | --- |
+| `path-overlap` | main/branch path 相同或祖先/后代重叠 | 报告精确路径，要求外部审查 |
+| `contract-overlap` | 两组路径命中同一 approved Contract item | 报告语义风险，不自动判定代码冲突 |
+| `contract-baseline-stale` | 当前 Contract digest 与 plan 不同 | blocked，重编 plan/context |
+| `source-drift` | 当前 checker 报告 changed/missing/unreadable | blocked，先走既有来源维护 |
+| `stage-incomplete` | 缺少 completed receipt 或 acceptance | blocked |
+| `stage-scope-escaped` | receipt changed path 不在 stage path 范围 | blocked，人工判断 replan |
+| `projection-stale` | 受管 projection 过期 | 报告，合并后由人决定显式 republish |
+| `decision-candidate` | receipt 中可能成为长期规则的决定 | 仅列候选，不自动 propose/approve |
+
+Git 自身的文本冲突、测试失败和最终业务语义正确性仍由 Git、项目工具、Coding Agent 和人判断。本产品只报告上下文层的可验证事实和不确定性。
+
+## 13. 合并后的生命周期
+
+Integration Review Bundle 不执行 merge。人或外部工具完成合并后：
+
+1. 重新运行既有 `sync` 与 `check`；
+2. 如 source 变化，继续使用 `review-source → accept-source-change → revise/deprecate → approve`；
+3. 如受管 projection stale，由人对精确输出路径执行既有 publish；
+4. receipt decision 只有在确属长期项目事实时，才通过既有 `propose → approve` 进入 Contract；
+5. plan、receipt、Stage/Integration Bundle 默认停止参与后续上下文；
+6. 产品不保存、提交、删除或归档这些工件，宿主决定放在临时目录、任务系统或分支文件中。
+
+合并关闭后不得把完整任务历史、聊天、diff、测试日志或所有 receipts 写入 Project Contract。长期合同只保留经过人工批准、对未来任务仍有效的项目事实和规则。
+
+## 14. 与 1.2.0 的复用和兼容
+
+直接复用：
+
+- Project Contract、source/projection lock 与三个 snapshot；
+- Scope Compiler 的 project/path-prefix/file 语义和 sibling 隔离；
+- `sync --changed-path` 的显式调用方路径信号；
+- checker、source drift、pending、conflict 与 projection findings；
+- Assist Bundle 的 readTargets/workUnits、无 source body 和稳定排序原则；
+- Action Plan/Review Bundle 的严格 schema、baseline、authority-free 和失败封闭原则。
+
+明确不复用：
+
+- 1.2.0 Action Plan 只描述治理 action，不扩展为业务 Task Plan；
+- Review Bundle 不承担 Stage 或 Git merge 语义；
+- 不修改 Contract、proposal、source lock、projection lock、renderer、Dashboard View Model、Assist Bundle、Action Plan 或 Review Bundle schema。
+
+`1.2.0 → 1.3.0` 不需要 store migration。未采用本适配器的项目行为完全不变。
+
+## 15. 实现文件图
+
+| 文件 | 责任 |
+| --- | --- |
+| `src/project-context/task-context-schema.mjs` | 严格验证/规范化 Task Context Plan 与 Stage Receipt |
+| `src/project-context/task-context.mjs` | Stage Bundle、预算、依赖、路径映射和 integration review 纯逻辑 |
+| `src/project-context/capabilities.mjs` | 公开新命令、schema 和预算单位 |
+| `src/project-context/cli.mjs` | 新增 `stage-context` 与 `integration-review` 只读入口 |
+| `schemas/task-context-plan.schema.json` | Task Context Plan schema 1 |
+| `schemas/stage-receipt.schema.json` | Stage Receipt schema 1 |
+| `schemas/stage-context-bundle.schema.json` | Stage Context Bundle schema 1 |
+| `schemas/integration-review-bundle.schema.json` | Integration Review Bundle schema 1 |
+| `test/project-context/task-context.test.mjs` | A-64 至 A-73 |
+| `test/release/acceptance.test.mjs` | npm 白名单、schema 和永久边界回归 |
+
+不得新增 child process、Git client、Provider client、tokenizer dependency、任务 store、scheduler、daemon 或业务代码执行模块。
+
+## 16. 冻结验收 A-64 至 A-73
+
+- **A-64 capability 与公开 schema**：capabilities 稳定公开两个命令、四份 schema、UTF-8 byte 预算和永久边界；发布白名单包含 schema。
+- **A-65 Task Context Plan**：合法 plan 稳定规范化；未知/权限/执行字段、重复 ID、循环依赖、非法路径、缺失预算和无依赖重叠 stage 失败封闭。
+- **A-66 Stage 选择与依赖**：只编译显式 stage；依赖缺失/blocked/stale 时 blocked，完整 completed receipts 才 ready，不自动前进。
+- **A-67 Scope 与 changed paths**：复用现有 compiler 精确选择 Contract items，保持 sibling 隔离；changed paths 只作信号，不读 Git、不成为来源。
+- **A-68 确定性预算**：相同输入字节等价；默认无 source/code/diff/chat body；必要内容超限显式 blocked，不静默截断。
+- **A-69 Stage Receipt**：严格绑定 plan/bundle/stage/acceptance；completed/blocked 语义完整；不含 shell、权限或伪造 approval。
+- **A-70 跨窗口恢复**：只用 plan、当前 stage、有效 receipts 和 paths 可重建同一 Bundle，不依赖聊天历史或新 store。
+- **A-71 Integration Review**：精确报告 main/branch path overlap、Contract item overlap、stage scope escape、incomplete receipt 和 decision candidate。
+- **A-72 baseline 与恢复**：Contract/source/projection snapshot、plan 或 receipt baseline 失效立即 blocked；刷新显式输入后可确定性恢复。
+- **A-73 生命周期、兼容与边界**：合并审查不执行 Git/测试/业务代码，不自动晋升决定或保存任务；A-01 至 A-63 和全部旧 CLI/发布验收继续通过，总计预期 79 项。
+
+## 17. 实现结果、停止条件与下一步
+
+用户于 2026-09-10 以 `authorize-1.3.0-branch-aware-staged-context-implementation` 明确授权冻结范围的本地实现。产品代码、四份机器 schema、两个只读 CLI 入口、capabilities、使用文档与 A-64 至 A-73 已完成，连同全部旧回归为 79/79 通过。
+
+实现授权已消耗，本阶段在状态同步后停止。未执行真实业务项目访问、Provider、依赖安装、产品内 Git 读取/写入、任务执行、团队试用、npm pack、registry、commit、push 或发布。79 项测试通过不等于发布授权；唯一下一步是等待用户另行授权 `1.3.0` 发布候选工件与公共 npm 发布。

package/docs/README.md

@@ -48,26 +48,38 @@
 
 10. [14-FORMAL-RELEASE-READINESS.md](./14-FORMAL-RELEASE-READINESS.md)
 
-    记录 `1.0.0` 正式发布与 `1.0.1` README/metadata patch：包边界、项目接入、CI、迁移、A-39、registry 完整性和不伪造公共仓库链接的决定。
+    记录 `1.0.0` 正式发布、`1.0.1` README/metadata patch 与 `1.2.0` AI Exchange Boundary 发布：包边界、项目接入、CI、迁移、验收、registry 完整性和不伪造公共仓库链接的决定。
 
 11. [15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md](./15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md)
 
     记录首次公开发布前来源生命周期修补的冻结设计与本地实现：处理来源删除、搬迁和永久退役，不自动接受、批准或修复；A-40 至 A-45 已通过。
 
+12. [16-GUIDED-ONBOARDING-AND-AI-RECONCILIATION-DESIGN.md](./16-GUIDED-ONBOARDING-AND-AI-RECONCILIATION-DESIGN.md)
+
+    记录 `1.1.0` AI Exchange Boundary 聚合基础的冻结合同与本地实现：以 setup/sync 聚合既有原语，外部 AI 依据模型无关工作单元准备首次接入和增量维护，人集中评判；Assist Bundle 默认不携带来源正文，A-46 至 A-55 已通过。
+
+13. [17-AI-EXCHANGE-BOUNDARY-DESIGN.md](./17-AI-EXCHANGE-BOUNDARY-DESIGN.md)
+
+    记录 `1.2.0` 双向 AI 交换内核的冻结设计、实现与公共发布结果：机器可发现 capability、Action Plan、只读 preflight/Review Bundle、结构化 invocation 和人工精确授权边界；A-56 至 A-63、完整 69 项验收及 registry 工件独立验证均已通过。
+
+14. [18-BRANCH-AWARE-STAGED-CONTEXT-DESIGN.md](./18-BRANCH-AWARE-STAGED-CONTEXT-DESIGN.md)
+
+    记录 `1.3.0` 可选附带协议的冻结设计与本地实现：由宿主提供任务、分支路径信号和阶段 receipt，产品只读编译当前 Stage 的预算 Context Bundle，并在合并前报告 baseline、path、Contract item 和生命周期冲突；A-64 至 A-73 及完整 79 项回归已通过，发布未授权。
+
 ## 历史证据
 
-12. [06-HISTORICAL-PROTOTYPE.md](./06-HISTORICAL-PROTOTYPE.md)
-13. [07-REAL-TASK-EVIDENCE.md](./07-REAL-TASK-EVIDENCE.md)
+15. [06-HISTORICAL-PROTOTYPE.md](./06-HISTORICAL-PROTOTYPE.md)
+16. [07-REAL-TASK-EVIDENCE.md](./07-REAL-TASK-EVIDENCE.md)
 
 历史文档只解释为什么不再建设任务执行 Harness。它们不是程序需求、工作流或授权来源。
 
 ## Beta 证据
 
-14. [09-B0-DTG-TMC-MOBILE.md](./09-B0-DTG-TMC-MOBILE.md)
+17. [09-B0-DTG-TMC-MOBILE.md](./09-B0-DTG-TMC-MOBILE.md)
 
    记录首次真实项目只读接入、通用修补和同项目回归。报告中的历史“下一步”不再产生新需求。
 
-15. [10-B0-DTG-TMC-PC.md](./10-B0-DTG-TMC-PC.md)
+18. [10-B0-DTG-TMC-PC.md](./10-B0-DTG-TMC-PC.md)
 
    记录第二个真实项目只读接入和跨项目对比：核心链路与首轮通用修补再次通过。产品宪法已经停止继续寻找项目和扩充技术发现白名单。