6.2 KiB
上下文治理契约
更新时间：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”写成一张卡。
四、执行生命周期
领取
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。
成功交接
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 证据。任务卡、索引或队列指针不一致时先修复生成证据，再继续实现。
五、提交前门禁
提交前至少运行：
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、模板和治理测试；长期规划只增加链接，不复制规则。 - 发现重复或过大的历史文档：标记为背景/归档并从默认入口移除，不在任务卡中粘贴摘要。