frontend-project-context 1.2.0 → 1.3.0

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,7 +48,7 @@
 
 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)
 
@@ -60,22 +60,26 @@
 
 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 已通过，发布仍未授权。
+    记录 `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 项回归已通过，发布未授权。
 
 ## 历史证据
 
-14. [06-HISTORICAL-PROTOTYPE.md](./06-HISTORICAL-PROTOTYPE.md)
-15. [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 证据
 
-16. [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)
 
    记录首次真实项目只读接入、通用修补和同项目回归。报告中的历史“下一步”不再产生新需求。
 
-17. [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)
 
    记录第二个真实项目只读接入和跨项目对比：核心链路与首轮通用修补再次通过。产品宪法已经停止继续寻找项目和扩充技术发现白名单。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontend-project-context",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Govern, compile, and verify project-local context for AI coding tools.",
   "private": false,
   "publishConfig": {
@@ -26,7 +26,7 @@
   },
   "scripts": {
     "check": "node --check bin/project-context.mjs && npm test",
-    "test": "node --test test/project-context/acceptance.test.mjs test/project-context/assist.test.mjs test/project-context/cli.test.mjs test/project-context/dashboard.test.mjs test/project-context/exchange.test.mjs test/project-context/maintenance.test.mjs test/project-context/source-lifecycle.test.mjs test/release/acceptance.test.mjs",
+    "test": "node --test test/project-context/acceptance.test.mjs test/project-context/assist.test.mjs test/project-context/cli.test.mjs test/project-context/dashboard.test.mjs test/project-context/exchange.test.mjs test/project-context/maintenance.test.mjs test/project-context/source-lifecycle.test.mjs test/project-context/task-context.test.mjs test/release/acceptance.test.mjs",
     "prepack": "npm run check"
   },
   "engines": {

package/schemas/capabilities.schema.json

@@ -11,6 +11,7 @@
     "schemas",
     "commands",
     "actionKinds",
+    "contextBudget",
     "initialization",
     "initialized",
     "project",
@@ -37,11 +38,15 @@
         "capabilities",
         "contract",
         "dashboardViewModel",
+        "integrationReviewBundle",
         "projectionLock",
         "projectionRenderer",
         "proposal",
         "reviewBundle",
-        "sourceLock"
+        "sourceLock",
+        "stageContextBundle",
+        "stageReceipt",
+        "taskContextPlan"
       ],
       "properties": {
         "actionPlan": { "const": 1 },
@@ -49,11 +54,15 @@
         "capabilities": { "const": 1 },
         "contract": { "type": "integer" },
         "dashboardViewModel": { "type": "integer" },
+        "integrationReviewBundle": { "const": 1 },
         "projectionLock": { "type": "integer" },
         "projectionRenderer": { "type": "integer" },
         "proposal": { "type": "integer" },
         "reviewBundle": { "const": 1 },
-        "sourceLock": { "type": "integer" }
+        "sourceLock": { "type": "integer" },
+        "stageContextBundle": { "const": 1 },
+        "stageReceipt": { "const": 1 },
+        "taskContextPlan": { "const": 1 }
       }
     },
     "commands": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } },
@@ -75,6 +84,16 @@
         ]
       }
     },
+    "contextBudget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["unit", "modelTokens", "callerMustProvideLimit"],
+      "properties": {
+        "unit": { "const": "canonical-utf8-bytes" },
+        "modelTokens": { "const": false },
+        "callerMustProvideLimit": { "const": true }
+      }
+    },
     "initialization": { "enum": ["uninitialized", "partial", "initialized"] },
     "initialized": { "type": "boolean" },
     "project": {
@@ -102,6 +121,8 @@
         "dependencyInstallation",
         "automaticApproval",
         "businessCodeWrites",
+        "taskExecution",
+        "stagePathBodyReads",
         "applyPlan",
         "scheduler",
         "daemon"
@@ -114,6 +135,8 @@
         "dependencyInstallation": { "const": false },
         "automaticApproval": { "const": false },
         "businessCodeWrites": { "const": false },
+        "taskExecution": { "const": false },
+        "stagePathBodyReads": { "const": false },
         "applyPlan": { "const": false },
         "scheduler": { "const": false },
         "daemon": { "const": false }

package/schemas/integration-review-bundle.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frontend-project-context:schema:integration-review-bundle:1",
+  "title": "Frontend Project Context Integration Review Bundle",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "project", "task", "workspace", "planDigest", "planSnapshots", "currentSnapshots", "mainChangedPaths", "branchChangedPaths", "receipts", "contractOverlapItemIds", "decisionCandidates", "readTargets", "findings", "excluded", "status", "bundleDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "integration-review-bundle" },
+    "project": { "$ref": "#/$defs/identity" },
+    "task": { "$ref": "#/$defs/task" },
+    "workspace": { "$ref": "#/$defs/workspace" },
+    "planDigest": { "$ref": "#/$defs/digest" },
+    "planSnapshots": { "$ref": "#/$defs/snapshots" },
+    "currentSnapshots": { "$ref": "#/$defs/snapshots" },
+    "mainChangedPaths": { "$ref": "#/$defs/paths" },
+    "branchChangedPaths": { "$ref": "#/$defs/paths" },
+    "receipts": { "type": "array", "items": { "$ref": "#/$defs/receiptSummary" } },
+    "contractOverlapItemIds": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/id" } },
+    "decisionCandidates": { "type": "array", "items": { "$ref": "#/$defs/decisionCandidate" } },
+    "readTargets": { "type": "array", "items": { "$ref": "#/$defs/readTarget" } },
+    "findings": { "type": "array", "items": { "type": "object" } },
+    "excluded": { "type": "array", "uniqueItems": true, "items": { "type": "string" } },
+    "status": { "enum": ["reviewable", "blocked"] },
+    "bundleDigest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:[.-][a-z0-9]+)*$" },
+    "text": { "type": "string", "minLength": 1 },
+    "paths": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "snapshots": { "type": "object", "additionalProperties": false, "required": ["contract", "sourcesLock", "projectionsLock"], "properties": { "contract": { "$ref": "#/$defs/digest" }, "sourcesLock": { "$ref": "#/$defs/digest" }, "projectionsLock": { "$ref": "#/$defs/digest" } } },
+    "identity": { "type": "object", "additionalProperties": false, "required": ["id", "name"], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "$ref": "#/$defs/text" } } },
+    "task": { "type": "object", "additionalProperties": false, "required": ["id", "title", "goal"], "properties": { "id": { "$ref": "#/$defs/id" }, "title": { "$ref": "#/$defs/text" }, "goal": { "$ref": "#/$defs/text" } } },
+    "workspace": { "type": "object", "additionalProperties": false, "required": ["branchLabel", "baseRevision"], "properties": { "branchLabel": { "$ref": "#/$defs/text" }, "baseRevision": { "$ref": "#/$defs/text" } } },
+    "acceptanceResult": { "type": "object", "additionalProperties": false, "required": ["id", "status", "evidence"], "properties": { "id": { "$ref": "#/$defs/id" }, "status": { "enum": ["observed", "not-observed"] }, "evidence": { "$ref": "#/$defs/paths" } } },
+    "verificationResult": { "type": "object", "additionalProperties": false, "required": ["id", "status", "summary", "evidence"], "properties": { "id": { "$ref": "#/$defs/id" }, "status": { "enum": ["passed", "failed", "observed", "skipped"] }, "summary": { "$ref": "#/$defs/text" }, "evidence": { "$ref": "#/$defs/paths" } } },
+    "receiptSummary": { "type": "object", "additionalProperties": false, "required": ["stageId", "status", "inputBundleDigest", "changedPaths", "acceptanceResults", "verificationResults", "decisions", "openIssues"], "properties": { "stageId": { "$ref": "#/$defs/id" }, "status": { "enum": ["completed", "blocked"] }, "inputBundleDigest": { "$ref": "#/$defs/digest" }, "changedPaths": { "$ref": "#/$defs/paths" }, "acceptanceResults": { "type": "array", "items": { "$ref": "#/$defs/acceptanceResult" } }, "verificationResults": { "type": "array", "items": { "$ref": "#/$defs/verificationResult" } }, "decisions": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/text" } }, "openIssues": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/text" } } } },
+    "decisionCandidate": { "type": "object", "additionalProperties": false, "required": ["stageId", "decision"], "properties": { "stageId": { "$ref": "#/$defs/id" }, "decision": { "$ref": "#/$defs/text" } } },
+    "readTarget": { "type": "object", "additionalProperties": false, "required": ["path", "reason"], "properties": { "path": { "type": "string", "minLength": 1 }, "reason": { "enum": ["integration-conflict", "contract-source"] }, "sourceId": { "$ref": "#/$defs/id" } } }
+  }
+}

package/schemas/stage-context-bundle.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frontend-project-context:schema:stage-context-bundle:1",
+  "title": "Frontend Project Context Stage Context Bundle",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "project", "task", "stage", "workspace", "planDigest", "snapshots", "dependencyReceipts", "changedPaths", "contractItems", "readTargets", "findings", "excluded", "budget", "status", "bundleDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "stage-context-bundle" },
+    "project": { "$ref": "#/$defs/identity" },
+    "task": { "$ref": "#/$defs/task" },
+    "stage": { "$ref": "#/$defs/stage" },
+    "workspace": { "$ref": "#/$defs/workspace" },
+    "planDigest": { "$ref": "#/$defs/digest" },
+    "snapshots": { "$ref": "#/$defs/snapshots" },
+    "dependencyReceipts": { "type": "array", "items": { "$ref": "#/$defs/receiptSummary" } },
+    "changedPaths": { "$ref": "#/$defs/paths" },
+    "contractItems": { "type": "array", "items": { "$ref": "#/$defs/contractItem" } },
+    "readTargets": { "type": "array", "items": { "$ref": "#/$defs/readTarget" } },
+    "findings": { "type": "array", "items": { "type": "object" } },
+    "excluded": { "type": "array", "uniqueItems": true, "items": { "type": "string" } },
+    "budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["unit", "maxUtf8Bytes", "maxReadTargets", "usedUtf8Bytes", "readTargetCount"],
+      "properties": {
+        "unit": { "const": "canonical-utf8-bytes" },
+        "maxUtf8Bytes": { "type": "integer", "minimum": 1 },
+        "maxReadTargets": { "type": "integer", "minimum": 1 },
+        "usedUtf8Bytes": { "type": "integer", "minimum": 0 },
+        "readTargetCount": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "status": { "enum": ["ready", "blocked"] },
+    "bundleDigest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "identity": { "type": "object", "additionalProperties": false, "required": ["id", "name"], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "$ref": "#/$defs/text" } } },
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:[.-][a-z0-9]+)*$" },
+    "text": { "type": "string", "minLength": 1 },
+    "paths": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "snapshots": { "type": "object", "additionalProperties": false, "required": ["contract", "sourcesLock", "projectionsLock"], "properties": { "contract": { "$ref": "#/$defs/digest" }, "sourcesLock": { "$ref": "#/$defs/digest" }, "projectionsLock": { "$ref": "#/$defs/digest" } } },
+    "task": { "type": "object", "additionalProperties": false, "required": ["id", "title", "goal"], "properties": { "id": { "$ref": "#/$defs/id" }, "title": { "$ref": "#/$defs/text" }, "goal": { "$ref": "#/$defs/text" } } },
+    "acceptance": { "type": "object", "additionalProperties": false, "required": ["id", "text"], "properties": { "id": { "$ref": "#/$defs/id" }, "text": { "$ref": "#/$defs/text" } } },
+    "stage": { "type": "object", "additionalProperties": false, "required": ["id", "title", "objective", "acceptance", "paths"], "properties": { "id": { "$ref": "#/$defs/id" }, "title": { "$ref": "#/$defs/text" }, "objective": { "$ref": "#/$defs/text" }, "acceptance": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/acceptance" } }, "paths": { "$ref": "#/$defs/paths" } } },
+    "workspace": { "type": "object", "additionalProperties": false, "required": ["branchLabel", "baseRevision"], "properties": { "branchLabel": { "$ref": "#/$defs/text" }, "baseRevision": { "$ref": "#/$defs/text" } } },
+    "acceptanceResult": { "type": "object", "additionalProperties": false, "required": ["id", "status", "evidence"], "properties": { "id": { "$ref": "#/$defs/id" }, "status": { "enum": ["observed", "not-observed"] }, "evidence": { "$ref": "#/$defs/paths" } } },
+    "verificationResult": { "type": "object", "additionalProperties": false, "required": ["id", "status", "summary", "evidence"], "properties": { "id": { "$ref": "#/$defs/id" }, "status": { "enum": ["passed", "failed", "observed", "skipped"] }, "summary": { "$ref": "#/$defs/text" }, "evidence": { "$ref": "#/$defs/paths" } } },
+    "receiptSummary": { "type": "object", "additionalProperties": false, "required": ["stageId", "status", "inputBundleDigest", "changedPaths", "acceptanceResults", "verificationResults", "decisions", "openIssues"], "properties": { "stageId": { "$ref": "#/$defs/id" }, "status": { "enum": ["completed", "blocked"] }, "inputBundleDigest": { "$ref": "#/$defs/digest" }, "changedPaths": { "$ref": "#/$defs/paths" }, "acceptanceResults": { "type": "array", "items": { "$ref": "#/$defs/acceptanceResult" } }, "verificationResults": { "type": "array", "items": { "$ref": "#/$defs/verificationResult" } }, "decisions": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/text" } }, "openIssues": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/text" } } } },
+    "scope": { "type": "object", "additionalProperties": false, "required": ["kind"], "properties": { "kind": { "enum": ["project", "path-prefix", "file"] }, "path": { "type": "string", "minLength": 1 } } },
+    "contractItem": { "type": "object", "additionalProperties": false, "required": ["id", "kind", "subject", "value", "statement", "scope", "sourceIds"], "properties": { "id": { "$ref": "#/$defs/id" }, "kind": { "enum": ["fact", "policy", "reference", "validation-description"] }, "subject": { "$ref": "#/$defs/id" }, "value": {}, "statement": { "$ref": "#/$defs/text" }, "scope": { "$ref": "#/$defs/scope" }, "sourceIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/id" } } } },
+    "readTarget": { "type": "object", "additionalProperties": false, "required": ["path", "reason"], "properties": { "path": { "type": "string", "minLength": 1 }, "reason": { "enum": ["stage-scope", "host-changed-path-signal", "contract-source"] }, "sourceId": { "$ref": "#/$defs/id" } } }
+  }
+}