# 上下文治理契约

更新时间：2026-08-19（America/New_York）

本契约解决两个问题：执行者不需要读完整路线图就能继续工作；任何任务卡、交接状态或机器索引
变大、漂移或重复指针时，自动门禁会在领取前失败。它是执行规则，不是项目进度表。

## 一、事实分层

每个问题只由一个层级回答，层级之间不互相复制内容：

| 层级 | 唯一职责 | 默认是否读取 |
| --- | --- | --- |
| `EXECUTION_QUEUE.md` | 当前 task、parent manifest、专项命令、全局硬规则 | 是 |
| `tasks/<task>.md` | 一个行为或一个证据变化的输入、边界、验收和回滚 | 是 |
| `tests/golden/<parent>/manifest.json` | parent 状态、artifact hash、运行时、`nextTask` | 是 |
| `docs/status/<parent>.md` | 上一项最小证据摘要和已知风险 | 是 |
| 协议/生产/测试文件 | 任务卡点名的实现事实 | 按需 |
| 长期计划、全量 ledger、历史 status | 背景、审计、归档 | 禁止默认读取 |

冲突优先级固定为：真实命令输出 > manifest/evidence > 任务卡 > 队列文字 > 长期规划和历史日志。
Markdown checkbox 不能覆盖失败命令或 hash 漂移。

## 二、硬预算

预算按 UTF-8 bytes 检查，token 用 `ceil(bytes / 4)` 作保守估算。超过任一单项或总预算都不能领取。

| 输入 | 上限 | 约束 |
| --- | ---: | --- |
| 队列 | 4 KiB | 只保留一个当前指针，不保留历史任务表 |
| 任务卡 | 8 KiB | 最多 12 个输入路径、8 条命令；不复制日志 |
| parent manifest | 24 KiB | 只记录必要 artifact，最多 32 项 |
| parent status | 6 KiB | 只保留命令、退出码、关键结果、风险和回滚 |
| 四份输入合计 | 3,500 tokens | 由 `contextSizeReport` 和治理门同时检查 |
| catalog 单行 | 2 KiB | 机器随机读取；执行者不得通读 catalog |

生成阶段的证据读取清单另外受 `maxFiles=12`、`evidenceBytes=8 KiB` 和基础文档扣除后的剩余上下文空间约束。
每个未选路径必须有 `inputSelection.excluded[].reason`，因此校验器不会成为首次发现超大上下文的地方。

全量 `next-task-plan.json`、parity map 和 gap audit 是生成器输入，不是执行上下文。索引保存源
hash 和 catalog offset；源 hash、catalog hash 或 offset 损坏时必须重新生成，不能回退读取大计划。

## 三、原子任务粒度

默认“一项任务 = 一个可观察行为或一项独立证据”。以下任一情况出现就拆任务：

- 同时改变 schema、生产消费、浏览器接线和发布证据；
- 需要两个互不依赖的 fixture 或两个不同 owner family；
- 正例、取消/重复/超限负例无法在同一 focused command 中清楚断言；
- 任务卡需要列出超过 12 个输入或超过 8 条命令；
- 任何一项失败会让另一项仍可安全交付。

复杂能力按适用门拆分，门之间通过 parent manifest 串联：

| 门 | 只交付一件事 | 失败状态 |
| --- | --- | --- |
| C 契约 | schema、稳定 ID、预算、错误边界和 revision 规则 | `in_progress` |
| P 生产 | Main/Worker/App/viewport 的真实消费路径 | `in_progress` |
| N 负例 | 非法、重复、取消、迟到、超限不改变已提交状态 | `in_progress` |
| B 浏览器 | Chromium 真实用户路径和可见结果 | `blocked` 或 `in_progress` |
| R 资源 | dispose、重启、save/reopen、OPFS/GPU/内存归零 | `in_progress` |
| E 证据 | focused command、报告、hash manifest、status、回滚 | 通过后才允许下一个 task |

M16 及后续 gap 固定为一 gap 一个 task：最小 fixture、desktop/WASM 对比、save/reopen、负例和
manifest 证据必须属于该 gap；不要把“完成整个 family”写成一张卡。

## 四、执行生命周期

### 领取

```bash
npm --prefix web run test:context-governance
node tools/web/print-task-context.mjs
node tools/web/check-task-context.mjs
```

只读取打印结果列出的四份文件和任务卡点名的最小实现入口。当前 task 必须等于 parent
manifest 的 `nextTask`；不能从旧 Markdown 编号、完整 plan 或 status 列表推导任务。

### 实施

先确认最小 fixture 和生产入口，再写 focused test/checker。每条验收命令都必须真实运行并记录
退出码；协议或测试文件存在不等于生产能力完成。浏览器、CI、验收和发布证据永久仅限 Chromium。

### 成功交接

```bash
node tools/web/check-task-context.mjs --task <task-id> --write
node tools/web/check-context-governance.mjs
```

只提交本任务的实现/测试、fixture、报告、manifest、status 和 `task-context.json`。manifest 必须
绑定所有产物的 SHA-256，并且 `nextTask` 是唯一的下一指针；长日志留在构件目录，不复制进 status。

### 失败、阻断和恢复

命令失败、环境缺失、取消、超限、重复、迟到结果或 hash 漂移时保持 `in_progress` 或 `blocked`，
不得写成功报告、修改 Main revision 或推进 `nextTask`。修复后从同一 parent 重新运行；不要覆盖
parent 证据。任务卡、索引或队列指针不一致时先修复生成证据，再继续实现。

## 五、提交前门禁

提交前至少运行：

```bash
npm --prefix web run test:context-governance
node tools/web/check-task-index.mjs
node tools/web/check-task-context.mjs
git diff --check
```

`check-context-governance` 会检查四份文档预算、任务卡必备章节和失败边界、禁止的长文档引用、
manifest 路径/构件数量、catalog 行边界以及唯一活动 task。门禁失败即停止，不通过手工删除输出
或修改 `nextTask` 绕过。

## 六、维护规则

- 新增任务：先更新机器源并运行 `generate-task-index.mjs`，再用 `generate-task-card.mjs --task` 生成短卡；禁止手写 catalog offset。
- 完成任务：先写 manifest/status，再用 `check-task-context --write` 生成交接上下文；队列只跟随新 manifest。
- 规则变化：只修改本契约、`CONTEXT_BUDGET.md`、模板和治理测试；长期规划只增加链接，不复制规则。
- 发现重复或过大的历史文档：标记为背景/归档并从默认入口移除，不在任务卡中粘贴摘要。