Govern task context and advance execution pointer

docs/CONTEXT_GOVERNANCE.md

@@ -0,0 +1,121 @@
+# 上下文治理契约
+
+更新时间：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`、模板和治理测试；长期规划只增加链接，不复制规则。
+- 发现重复或过大的历史文档：标记为背景/归档并从默认入口移除，不在任务卡中粘贴摘要。