frontend-project-context 1.3.1 → 1.7.0

package/docs/23-ADAPTIVE-BOUNDED-TASK-CONTEXT-DESIGN.md

@@ -0,0 +1,432 @@
+# 23 — `1.6.0` 后自适应有界任务上下文反证设计
+
+> 权威说明：本文是 `frontend-project-context@1.6.0` 发布后“真源覆盖、大项目检索与真实需求 token 消耗”的冻结设计与可证伪验收合同。如与 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md) 冲突，以产品宪法为准。
+>
+> 状态：`1.7.0-docs-26-local-implementation-complete; 195/195; bounded-provider-revalidation-not-authorized; release-blocked`
+>
+> 版本：实现新增公开 CLI 与四份 schema，因此本地目标版本确定为 `1.7.0`；发布仍未授权。
+>
+> 基线：`frontend-project-context@1.6.0`，120/120 验收、公共 npm 发布与 registry 独立复验已完成。A-130 历史两次真实对照均为完整 8/8、自适应 7/8。docs/26 的协议与有界评测闭环已本地实现并通过 195/195；新的 Host/Provider 复验尚未授权，`1.7.0` 继续阻断发布。
+
+## 1. 结论先行
+
+本轮反证否定的不是“减少上下文”，而是以下简化方案：
+
+1. 用一个固定小数量或固定小字节数硬截断每次需求的上下文；
+2. 让派生索引代替 Project Contract 或原始来源回答事实；
+3. 宣称自动 discovery 能理解并找全任意项目的所有真源；
+4. 每个小需求都重复做全项目 discovery、全量 source digest 和完整 `check`；
+5. 仅用词法相似度删除上下文，并把未命中解释为“不需要”。
+
+本轮选定的设计是：
+
+> **Adaptive Bounded Task Context（自适应有界任务上下文）**：初始化或显式审计时允许做昂贵的覆盖复核和派生索引重建；真实需求时先返回完整的必选规则、高召回候选和证据闭包，只对相关来源做即时校验；证据不足、冲突、跨模块或预算不足时显式扩展或阻断，不猜测、不静默截断。
+
+“有界”是可观测和可阻断，不是为了最小而最小。优先级固定为：
+
+```text
+需求完成质量
+> 必要规则与证据的召回
+> 可追溯与失败封闭
+> token、读文件数和耗时收益
+```
+
+## 2. 问题边界
+
+### 2.1 本设计解决的问题
+
+用户已确认：初始化阶段的较高消耗可接受，主要问题是项目接入后，一个真实小需求仍可能发生：
+
+- 为了确认上下文健康，重复扫描和哈希无关来源；
+- 路径选择后输出所有适用项，任务文本不参与选择；
+- 摘要、候选、原文和健康检查在多次工具往返中重复产生；
+- 项目越大，全量校验成本越接近项目规模，而不是本次需求的证据规模；
+- 对“没有检索到”、“没有登记”和“已证明不存在”没有严格区分。
+
+### 2.2 本设计不解决的问题
+
+- 不为 Host Agent 实现通用业务代码语义搜索、调用图或 Agent Runtime；
+- 不保证自动理解任意文件中未经人确认的业务含义；
+- 不使用 Provider、embedding 服务、向量数据库、Git 变更检测、文件监听器或 daemon；
+- 不以降低模型推理档位、省略验收或减少必要证据换取数字上的 token 下降；
+- 不把一次真实项目观察直接提升为新内核需求。
+
+## 3. `1.6.0` 基线证据
+
+本设计不假设基线已经有“语义任务检索”。当前代码表明：
+
+1. `context` 先运行完整 `checkProject`，再根据 `--path` 编译上下文；
+2. `renderer.collectBundle` 只用目标路径调用 `effectiveItems`，`task` 只被渲染在输出中，不影响选择；
+3. 每个选中项默认输出 statement、scope、sources 和完整 canonical JSON value；
+4. `sync` 先复核来源，后续又调用 `checkProject`，同一来源可被重复读取或哈希；
+5. `file` 类型的目录来源递归读取并哈希除默认忽略外的所有文件，`path` 来源只校验存在类型；
+6. 自动 discovery 有固定的 config/dependency 列表，规则文件递归深度上限为 8，它是保守候选器，不是完整真源证明；
+7. `stage-context` 已有 canonical UTF-8 和 read-target 预算，且必需内容超预算时阻断，但普通 `context` 尚未共享这套语义。
+
+因此，“慢”和“消耗高”不能只归因于文件 I/O；至少要分开测量来源读取、上下文字节、工具往返和 Host 任务结果。
+
+## 4. 反证法与否证结果
+
+本节不问“方案看起来是否合理”，而是为每个主张寻找一个足以使它失败的反例。
+
+### H1：固定小预算不会伤害需求质量
+
+**反例**：一个看似只改单文件的登录字段，同时受项目级隐私 policy、目录级 API policy、文件级兼容规则和两个 validation-description 约束。如果硬限 8 项，第 9 项仍可能是必要条件。
+
+**结果**：否证。数量与字节只能是软目标和传输安全上限，不能是静默丢失的理由。
+
+### H2：派生索引可以代替原始真源
+
+**反例**：索引中保留了“使用 A”的旧摘要，Project Contract 已被人修订为“使用 B”；或索引摘要省略了例外条件。
+
+**结果**：否证。索引只能找候选，所有输出必须回到当前 Project Contract 与原始来源，并绑定 digest。
+
+### H3：一次自动全扫可以证明所有真源已找全
+
+**反例**：规则存在于内网页面、人工决策、未命名为规则的业务文档，或语句需要业务背景才能判断是否为规范。
+
+**结果**：否证。产品只能证明“已声明覆盖范围内的候选已经审查闭合”，不宣称理解全部项目语义。
+
+### H4：任务局部校验在任何情况下都等价于全局 `check`
+
+**反例**：被延后的项与当前项共用一个 source，或具有 project scope 的 policy 发生 drift；局部路径看似无关，实际上会改变当前任务结论。
+
+**结果**：否证。局部快速路径必须计算 scope、override、subject 和 source 共享的证据闭包；项目级规则永远不能因路径局部而被跳过。
+
+### H5：无变化信号、无全扫，仍可证明项目没有新真源或无关来源变更
+
+**反例**：在上次 clean 快照后，某人新增一个不在已登记集中的规则文件；运行时既不扫描目录，也不接收 Host 的 changed paths。
+
+**结果**：逻辑上不可能证明。必须三选一：接受 snapshot/signal-bound 保证、接收 Host 变化信号，或回退显式全局审计。产品不得把未校验包装为 `clean`。
+
+### H6：输出字节越少，真实需求就必然更快、更省 token
+
+**反例**：首轮输出很小，但 Host 需要连续调用五次工具才补齐证据；总模型输入、思考和往返时间反而更高。
+
+**结果**：否证。验收必须测量完整需求链路，不得只比较首包字节数。
+
+### H7：每次先运行全量 `check` 就能解决真源不彻底
+
+**反例**：全量 `check` 可以证明已登记来源的当前状态，却不能发现从未登记、也不在 discovery 候选中的业务规则。
+
+**结果**：否证。“登记覆盖”和“已登记来源新鲜度”是两个不同问题，必须分开报告。
+
+### H8：Adaptive Bundle 的传输包络天然小于完整 Context
+
+**反例**：真实项目的小型 Contract 只有少量必选项，但 initial bundle 为每个延后项携带 ID、digest、kind、scope、source 和 reason，同时还携带 source、健康与预算元数据。即使水合正文更少，完整 JSON 包络仍可能更大。
+
+**结果**：A-130 否证。完整 Context 初始提示为 12,351 UTF-8 字节，自适应提示为 14,466 字节，反增 17.1%。延后目录必须继续可审查，但不能再假设当前 schema 的完整机器包络本身就是字节优化。
+
+### H9：把机器审查 Bundle 整体传给模型不会干扰任务推理
+
+**反例**：A-130 的自适应臂将 deferred item 目录、digest、健康与预算元数据一起放入模型首轮输入。这些字段对 Host 审计有用，但不是业务任务证据；小 Contract 时它们比完整 Context 更大。
+
+**结果**：否证并修复。`context-query --json` 保留完整可审计 Bundle，`context-query --prompt` 只输出 digest-bound 的模型面向 Markdown。当完整适用 Context 字节数不大于机器 Review Bundle 时，投影确定性选择 `complete-fallback`；否则使用自适应证据闭包。Host 不再需要把审查包络传给模型。
+
+## 5. 三类保证，不再混用“真源完整”
+
+| 保证 | 回答的问题 | 可以证明 | 不可以证明 |
+| --- | --- | --- | --- |
+| Registration Coverage | 应该纳入治理的来源是否被审查 | 显式覆盖范围内的候选均已登记、排除或待决策 | 任意项目的全部隐式业务语义已被 AI 理解 |
+| Contract Coverage | 当前需求需要的长期规则是否有批准项 | 已批准 item、scope、override 和 provenance 的确定性闭包 | 未经人批准的候选自动成为规范 |
+| Freshness | 这些规则依赖的来源现在是否一致 | 已校验证据闭包与快照一致 | 未扫描、无变化信号的全项目仍然 clean |
+
+任何机器输出必须分别展示这三项，不能用一个 `complete: true` 混淆。
+
+## 6. 总体架构
+
+```text
+初始化 / 显式全局审计（可昂贵）
+→ 覆盖候选与人工决策闭合
+→ 批准的 Project Contract（唯一长期真源）
+→ 可重建 Routing Index + coverage/source snapshot（派生）
+
+真实需求快速路径
+Host task + target paths + topics + changed-path signals
+→ 校验 Contract/index 基线
+→ 必选项 + 高召回候选 + provenance/source 闭包
+→ 只校验相关来源
+→ 一次返回已水合内容、延后目录、扩展原因和健康级别
+→ 证据足够则进入需求；不足则扩展一层或阻断
+```
+
+实现必须共享一个选择内核，普通 task context 与 `stage-context` 不得形成两套相互矛盾的召回语义。
+
+## 7. 初始化与显式审计路径
+
+### 7.1 Coverage Profile 的归属
+
+覆盖根、明确排除和人工判定属于规范决策，必须以带 provenance 的普通 Project Contract item 表达，不新增第二份治理真源。
+
+产品可以定义一个机器可读的 coverage value 结构，但它只有在 item 被人明确批准后才生效。自动扫描生成的排除建议始终是 proposed candidate。
+
+### 7.2 Coverage Audit
+
+新的只读审计能力暂定为：
+
+```text
+project-context coverage-audit --project PATH [--changed-path PATH...] [--json]
+```
+
+它只在初始化、覆盖规则变更、发布、显式审计或无可信变化信号且要求严格新鲜度时执行。
+
+输出将候选分为：
+
+- `registered`：已有 active source 登记；
+- `excluded-approved`：有已批准、可追溯的排除决策；
+- `review-required`：位于已声明覆盖范围，但无登记或排除结论；
+- `outside-declared-coverage`：不在产品当前声明能证明的范围。
+
+只有 `review-required` 为空时，Registration Coverage 才能为 `closed-for-declared-scope`。它永远不输出 `all-project-truth-discovered`。
+
+### 7.3 Routing Index
+
+派生索引位于 `.project-context/derived/`，必须满足：
+
+- 只从当前 Contract、source registration、scope、subject、statement 和 locator 确定性重建；
+- 可以保留 token/term、path-prefix、item/source 反向边和内容 digest，不保留未批准真源副本；
+- 包含 contract/source-lock/schema/selector version 基线和 self-digest；
+- 丢失或过期时可从 Contract 内存重建，不得因索引缺失返回“无规则”；
+- 默认只读命令不写缓存；只有明确 `--write` 才能持久化重建结果；
+- 不是 store、Project Contract、approval 或健康证明，删除它不影响长期真源。
+
+## 8. 真实需求快速路径
+
+### 8.1 Host 输入
+
+Host Agent 根据用户原始需求准备一份短生命 `Context Query`，至少包含：
+
+- 原始 task text，不得只传 AI 摘要；
+- 已知 target paths，允许为空但会降低保证；
+- 由 Host 提取的 topics，作为候选信号而非真理；
+- 用户或 Host 明确要求的 item IDs；
+- Host 已知 changed paths；
+- 快照基线、freshness mode 和软/硬预算。
+
+Host 生成的 topic、path 和扩展请求不产生 approval，也不能扩大任务权限。
+
+### 8.2 选择顺序
+
+一次编译按以下顺序生成证据闭包：
+
+1. 验证 Contract、source lock 和 query snapshots；
+2. 对每个 target path 运行当前 scope/override/conflict 语义；
+3. 无条件纳入明确 item IDs；
+4. 无条件纳入所有适用的 `policy` 和 `validation-description`；
+5. 路径先通过既有 scope/override 语义约束候选；再纳入与原始 task text/topics 匹配的 fact/reference。`src`、`admin` 等通用路径段不能单独成为语义命中，否则会把同一 scope 的无关 fact/reference 全部水合；
+6. 纳入上述项的 override、subject-conflict 和 provenance/source 闭包；
+7. 对共享 source、project scope 和跨 target path 关系扩展一层；
+8. 校验闭包内的 active local sources；
+9. 返回已水合项、延后候选目录、选择原因、预算和健康声明。
+
+“所有适用 policy/validation 必选”是质量优先的故意取舍。如果这一集合本身巨大，应改善 Contract 的 scope 和内容粒度，不应在运行时偷偷丢掉规则。
+
+### 8.3 两类预算
+
+- `targetUtf8Bytes` / `targetReadTargets`：软目标。证据闭包可以超过，输出必须说明原因。
+- `maxUtf8Bytes` / `maxReadTargets`：传输安全上限。必需内容超过时返回 `blocked/context-budget-insufficient`，不截断、不返回假 `ready`。
+
+本设计不冻结“8 个候选 / 16 KiB”为产品真理。默认值只能由基准数据决定，且用户或 Host 可在硬上限内调高软目标。
+
+## 9. 自适应扩展
+
+### 9.1 必须扩展或阻断的触发器
+
+- 没有命中任何任务候选，但存在适用 Contract items；
+- task/topic 命中多个不兼容 subject；
+- target path 未知、不存在或越出已声明 coverage；
+- 需求跨顶层模块、shared package、公共组件或多个 scope；
+- 命中项、project-scope 项或共享 source 发生 drift；
+- 相关 coverage 中存在 `review-required`；
+- 验收、API、业务语义或影响边界不完整；
+- Host Agent 明确声明 evidence insufficient；
+- 必选闭包超过硬预算。
+
+### 9.2 扩展级别
+
+| 级别 | 用途 | 语义 |
+| --- | --- | --- |
+| `initial` | 普通局部需求 | 必选项 + 高召回候选 + 一层证据闭包 |
+| `expanded` | 证据不足或跨模块 | 在原 bundle digest 上增加指定 subject/source/scope 邻接项，不重复已水合正文 |
+| `complete` | 显式深度工作或基线对照 | 当前 target paths 的全部有效项，并运行严格健康校验 |
+
+`expanded` 必须绑定前一 bundle digest 和当前 snapshots。任何基线变化都使扩展请求失效，防止把新旧上下文拼在一起。
+
+## 10. 任务健康与全局健康
+
+新协议不重定义已有 `status.health=clean`。它在任务 bundle 中并列报告：
+
+- `globalHealth`：来自本次 strict check 或 Host 提供的快照，可为 `clean | attention | conflict | not-checked | snapshot-stale`；
+- `taskHealth`：对当前 item/source/coverage 证据闭包的结论，可为 `ready | needs-expansion | blocked`；
+- `freshnessGuarantee`：`strict-current | snapshot-and-signal-bound | unverifiable`。
+
+规则如下：
+
+1. `globalHealth=clean` 只能由本次完整健康检查得出；
+2. 快速路径可在 `globalHealth=not-checked` 时返回 `taskHealth=ready`，但必须明示 snapshot/signal-bound；
+3. 相关 source drift、project-scope drift、冲突、coverage 未决或基线过期时，`taskHealth` 必须为 `blocked` 或 `needs-expansion`；
+4. 不相关但已知的全局 finding 不得被删除，必须作为 warning 携带；
+5. 用户要求绝对当前新鲜度，但无 Host changed paths 或其他可信信号时，自动进入 `complete/strict`，不在快速路径中猜测。
+
+## 11. 公开协议草案
+
+### 11.1 CLI
+
+```text
+project-context coverage-audit --project PATH [--changed-path PATH...] [--json]
+project-context index-context --project PATH [--write] [--json]
+project-context context-query --project PATH --input FILE [--previous FILE] [--json]
+project-context context-query --project PATH --input FILE [--previous FILE] --prompt
+```
+
+- 三个命令均默认只读；
+- `index-context --write` 只写可重建派生索引，不修改 Contract、source lock 或 projection；
+- `context-query` 不读业务代码正文，只水合 Contract 内容并为 Host 返回精确 read targets；
+- `--json` 是 Host 审查面，`--prompt` 是单次工具调用的紧凑模型投影，两者互斥；
+- `--previous` 只接受通过 schema/self-digest/snapshot 校验的上一份 bundle；
+- 旧 `context` 保持兼容的按路径完整输出，并作为 correctness baseline；
+- `stage-context` 在同一实现阶段复用新 selector，但 schema 1 输入仍保留现有完整语义。
+
+### 11.2 `Context Query` schema 1
+
+固定字段：
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "context-query",
+  "projectId": "example",
+  "snapshots": {
+    "contract": "sha256:...",
+    "sourcesLock": "sha256:...",
+    "projectionsLock": "sha256:..."
+  },
+  "task": {
+    "text": "original user request",
+    "paths": ["src/feature/example.ts"],
+    "topics": ["authentication"],
+    "itemIds": [],
+    "changedPaths": []
+  },
+  "level": "initial",
+  "freshness": "snapshot-and-signal-bound",
+  "budget": {
+    "targetUtf8Bytes": 32768,
+    "targetReadTargets": 12,
+    "maxUtf8Bytes": 131072,
+    "maxReadTargets": 64
+  }
+}
+```
+
+示例数字只用于说明软/硬预算的区别，不是已冻结默认值。最终默认值必须由验收基准决定。
+
+### 11.3 `Adaptive Context Bundle` schema 1
+
+至少包含：
+
+- project/task/snapshot/index/self digests；
+- `globalHealth`、`taskHealth` 和 `freshnessGuarantee`；
+- 已水合的完整 item 内容；
+- deferred item 的 ID、kind、subject、scope、digest 和延后原因，不含 value/statement 正文；
+- item/source/override/conflict 证据闭包；
+- read targets 及选中原因；
+- coverage 三类保证和已知降级；
+- 软/硬预算使用量；
+- expansion triggers 和可请求的精确 item/source/subject IDs；
+- 固定 excluded bodies/boundaries，确保无 Provider、authority、shell 或 business-code body。
+- `delivery`：记录 `adaptive | complete-fallback`、精确 item IDs、Markdown content digest 与字节数，不在 JSON 中重复模型正文。
+
+## 12. 性能收益必须从哪里来
+
+允许的优化来源只有：
+
+1. 初始化/审计时建立可重建路由结构，任务时不重做全局 discovery；
+2. 同一请求内的 source read/digest 去重与 memoization，避免 `sync`/健康分类反复读同一来源；
+3. 任务路径只校验证据闭包，全局健康保留为独立声明；
+4. 相同项跨多路径只水合一次，不重复输出 value/statement/source index；
+5. 首包同时返回水合内容、延后目录和扩展入口，减少 Host 为了搞清“还缺什么”的串行工具往返；
+6. 扩展包只输出新增内容，通过 digest 与首包组合，不重发旧正文。
+
+不允许通过以下方式制造“收益”：丢掉适用 policy、只给摘要不给原文、降低验收要求、把 blocked 计为快速成功、或忽略为补证据产生的后续工具往返。
+
+## 13. 可证伪验收合同
+
+以下编号从已发布的 A-114 后延续。A-115 至 A-129 已成为本地自动验收；A-130 已在真实 Host/目标项目执行并因质量下降失败，详细证据见 [24-A130-REAL-HOST-TARGET-PROJECT-COMPARISON.md](./24-A130-REAL-HOST-TARGET-PROJECT-COMPARISON.md)。
+
+| ID | 反例/场景 | 必须成立的结果 |
+| --- | --- | --- |
+| A-115 | 单路径小需求同时有项目、目录和文件级 policy | 所有适用 policy/validation 均水合，与完整 `context` oracle 一致 |
+| A-116 | 关键规则位于第 9 项且软目标为 8 | 超软目标但不丢失；超硬上限则 blocked，不截断 |
+| A-117 | 任务文本与路径同时命中两个冲突 subject | 返回 needs-expansion/blocked 和完整冲突边，不自动择一 |
+| A-118 | 修改 Contract 后保留旧 Routing Index | 旧索引被拒绝；从当前 Contract 内存重建或明示降级，不返回旧事实 |
+| A-119 | 删除 Routing Index | 不返回“无规则”；只读内存重建可继续，且不产生写入 |
+| A-120 | 相关 source 或 project-scope policy source 发生 drift | 快速路径阻断，列出精确 source/item 和恢复入口 |
+| A-121 | 已知 finding 仅影响 sibling scope | 任务可为 ready，但 global warning 仍保留，不宣称 global clean |
+| A-122 | 上次快照后新增未登记规则文件，且无 changed-path 信号 | signal-bound 模式不声称绝对新鲜；strict 模式必须全局审计或阻断 |
+| A-123 | 一个 source 被已水合与延后项共享 | source 进入证据闭包并只校验一次 |
+| A-124 | 一个需求跨 feature 与 shared package | initial 包识别跨模块信号，expanded 包补全邻接 scope 且不重发旧正文 |
+| A-125 | 同一 paths，不同 task/topics | 选中的 fact/reference 可以不同；必选 policy/validation 必须相同 |
+| A-126 | coverage 中存在未登记且未排除候选 | Registration Coverage 只能为 review-required，不得输出 closed |
+| A-127 | 为同一小需求比较 1.6.0 与新路径 | 全链路必选 item 召回 100%，且新路径不得增加 Host 工具往返 |
+| A-128 | 全部敌意 fixture 和人工标注 task corpus | 最终 bundle 对 required Contract items 召回 100%，任一缺失直接否决发布 |
+| A-129 | 效率对照 | 在不触发扩展的局部 task corpus 上，相比 1.6.0 至少减少 40% 的 context UTF-8 字节且减少 50% 的 source body/digest reads；未达到则不宣称解决性能问题 |
+| A-130 | 端到端 Host 对照 | 模型只接收 `--prompt` 投影；完成同一需求的总输入字节、总工具调用、总耗时和结果质量同时记录；任务质量下降则即使 token 更少也失败 |
+| A-130R | 小 Contract 的审查包络大于完整 Context | `delivery.mode=complete-fallback`，`--prompt` 与完整 Context 字节等价，不携带 deferred/review 包络 |
+
+### 13.1 评测 oracle
+
+必须建立两类 oracle：
+
+1. **确定性 oracle**：用完整 `context` + 手工标注的 required item/source 集合，验证 selector 没有丢失必要 Contract 证据。
+2. **Host 结果 oracle**：在获得真实 Host/项目验收授权后，使用相同任务、验收和模型配置比较完整上下文与自适应上下文。
+
+本地实现证据没有推翻 H1 至 H7，A-115 至 A-129 已通过；其中 A-129 只证明隔离局部 task corpus 达到 `>=40%` context UTF-8 字节与 `>=50%` source body reads 的门槛。A-130R 已证明小 Contract 会通过紧凑 `--prompt` 退回与完整 Context 字节等价的输入，但随后的真实复验仍为完整 8/8、自适应 7/8；因此本地 fixture 成功不构成外部 Host 成功结论。
+
+## 14. 分段实现结果
+
+本地实现已按以下顺序完成前五段，没有先建设语义索引大工程：
+
+1. **基准与去重**：为现有 `context`/`sync` 记录 source reads、bytes、tool calls；同一命令内复用 digest/read 结果。
+2. **共享 selector 与结构化 bundle**：先实现必选项、证据闭包、延后目录和软/硬预算，不持久化索引。
+3. **任务健康**：实现 task/global/freshness 分离和 strict 回退，保持现有 `clean` 语义。
+4. **派生 Routing Index**：只在无索引内存路径已通过 correctness 后加入，证明它只优化耗时而不改变选择结果。
+5. **Coverage Audit**：将登记覆盖问题与新鲜度问题分开验收，不扩充框架白名单。
+6. **A-130 本地修复**：分离审查 JSON 与模型投影，增加小 Contract 完整上下文回退与 A-130R。
+7. **Host 重验**：已在单独授权后用相同模型/任务/oracle 执行；结果 8/8 对 7/8，门禁失败，通过前不得发布。
+
+实现中第一次敌意路由 fixture 发现：如果把通用 path segment 直接当词法命中，同 scope 的无关 fact/reference 会被错误水合。这一证据没有推翻“路径参与选择”，但修订了其语义：路径负责 scope narrowing，原始 task text/topics 负责内容路由，显式 item ID 继续无条件进入。修订后的 A-124/A-125/A-127/A-128 均通过。
+
+任一阶段发现 required-item 召回下降，必须回退到上一阶段；不得通过放宽评测标注继续推进。
+
+## 15. 兼容、迁移与边界
+
+- Project Contract 仍是唯一批准真源，现有 contract/source/projection store 不因索引必然升级；
+- 旧 `context` 输出语义保留，不在没有兼容入口时强制消费者迁移；
+- 派生索引不进入 approval、projection ownership 或 source lock；
+- 不新增 Provider、Agent loop、Git、network、dependency install、business-code write、scheduler、daemon 或 telemetry；
+- 不引入按框架增长的 discovery 白名单；
+- Host 的业务代码搜索与任务执行仍属于外部 Coding Agent，本产品只返回项目已治理来源的 read targets。
+
+## 16. 宪法分类
+
+本设计属于：
+
+- Scope Compiler / Context Renderer 对“按目录和任务生成必要上下文”的质量与效率完善；
+- Source Registration & Provenance 的覆盖证据完善；
+- AI Exchange Boundary 的短生命、无权限查询与 bundle 协议；
+- 可选 Host Adapter 的任务信号输入，不是 Agent Runtime。
+
+它不新增第八项内核，不改变产品宪法第 2 至第 6 节，因此基线下不需要宪法版本变更。
+
+## 17. 停止规则与当前授权
+
+用户于 `2026-09-11` 单独授权本设计的本地实现，并要求实现证据若与反证结论冲突则修订结论；又于 `2026-09-11` 至 `2026-09-12` 分两步授权 A-130 真实目标项目、真实 Host 与既定评测内容的 Provider 传输。两项授权均已消费。它们不授权：
+
+- 再次运行、扩大样本或更换模型继续做 Host 对照；
+- 修改业务代码、安装依赖，或把 Provider 访问扩大到本次两次只读运行之外；
+- Git commit/tag/push、npm 发布或下一版本号确定。
+
+用户于 `2026-09-12` 授权将 A-130 修复与 `docs/25` 协议正确性统一处理，随后单独授权并确认向当前 `custom` Provider 发送披露的私有评测材料，执行两次只读复验。本地修复与 Provider 复验权限均已消费，没有扩张为再次修复、新的 Provider 调用、真实项目写入、Git 或发布权限。当前唯一下一步是：
+
+> 复验已按 `--prompt`、同一任务/模型/oracle 执行并失败。下一轮协议与有界评测修订已按 [26-A130-QUALITY-CLOSURE-AND-ADAPTIVE-DELIVERY-REPAIR-DESIGN.md](./26-A130-QUALITY-CLOSURE-AND-ADAPTIVE-DELIVERY-REPAIR-DESIGN.md) 完成本地实现并通过 195/195；S 一对、L 三对、最多八次的新 Provider 重验、Git 和发布仍各自需独立授权。

package/docs/24-A130-REAL-HOST-TARGET-PROJECT-COMPARISON.md

@@ -0,0 +1,210 @@
+# 24 — A-130 真实 Host / 目标项目对照证据
+
+> 状态：`bounded-revalidation-passed; A-130-closed; 1.7.0-release-authorized`
+>
+> 日期：`2026-09-12`
+>
+> 权威边界：本文只记录 A-130 外部验收证据。它不批准目标项目治理内容，不授权业务代码修改、Git、发布或后续产品修复。
+
+## 1. 授权与目标
+
+用户先单独授权 A-130 真实 Host/目标项目对照，随后明确授权把约定的 `dtg-tmc-pc` 评测材料发送给当前配置的模型 Provider，范围限于两次只读 Host 对照。
+
+真实目标为 `dtg-tmc-pc`。原仓库没有写入 `.project-context/`；评测在过滤 `.git`、`node_modules`、构建产物、环境文件和密钥后的一次性副本中建立 evaluation-only Contract。Host 在该评测副本中只读检查两个生产文件：
+
+- `src/components/flight/non-whitelist-confirm.vue`
+- `src/views/flight/book/index.vue`
+
+评测前后原仓库 `git status --short` 均为空，三个抽查摘要保持不变：
+
+- `AGENTS.md`：`ffc2cb31e098aef8b396d19272ffa3322c09c57d99eb47822ef663e982f460be`
+- `non-whitelist-confirm.vue`：`9ea8d89bb1e7895d045c8e487dc9bc574112e04accb374721ddd8c76f23ebb48`
+- `flight/book/index.vue`：`89a6c99b1c69811f76b242748d10c789813fb5943edaa6c78b492a48c9f9f4ab`
+
+## 2. 固定方法
+
+两臂均使用：
+
+- Codex CLI `0.146.0`；
+- 模型 `gpt-5.6-sol`、reasoning effort `high`；
+- 全新 `--ephemeral` Host；
+- `read-only` sandbox；
+- 相同任务、相同八项 oracle、相同结构化输出 schema；
+- 禁止读取 `docs/reviews/**` 隐藏 oracle，禁止构建、测试、修改和 Git 写入。
+
+对照变量只有 Project Context 输入：
+
+- 完整臂：兼容 `1.6.0 context` 语义的完整 Context Bundle；
+- 自适应臂：`1.7.0 context-query` initial Adaptive Context Bundle。
+
+evaluation-only Contract 有 22 个已批准项。自适应臂水合 4 个项并延后 12 个适用 fact；所有适用 policy/validation-description 均保留。
+
+## 3. 结果
+
+| 指标 | 完整 Context | 自适应 Context | 变化 |
+| --- | ---: | ---: | ---: |
+| 初始提示 UTF-8 字节 | 12,351 | 14,466 | **+17.1%** |
+| Provider 报告 input tokens | 224,836 | 152,543 | **-32.2%** |
+| cached input tokens | 167,936 | 104,960 | -37.5% |
+| output tokens | 6,725 | 5,876 | -12.6% |
+| Host 只读命令调用 | 4 | 3 | -25.0% |
+| 观察墙钟时间 | 约 126 秒 | 约 174 秒 | **+37.8%** |
+| oracle 正确项 | **8/8** | **7/8** | **-12.5%** |
+| 最终质量判定 | pass | fail | **失败** |
+
+Codex CLI 只报告总 input tokens，不报告每轮 canonical input bytes；完整臂的流式事件还被操作层截断。因此“全链路总输入字节”没有得到与 tokens 同等级的完整计量，只能精确报告初始提示字节。这个仪表缺口本身也不满足 A-130 的完整测量要求，但不影响质量门已经失败的结论。
+
+## 4. 质量反例
+
+隐藏 oracle 明确记录：
+
+- 每个 `priceDetail` 只对应一种方向；
+- `priceList[0]` 是该明细的票价和方向来源；
+- 同一明细下所有 `segmentInfoList` 航段属于该方向。
+
+完整臂正确判定方向与逐航段编号通过。自适应臂却把 `priceList[0]` 解释为“丢弃后续去返程价格”，并引用父页面另一个展示区遍历全部 `priceList` 的代码作为反证，错误地把该检查判为 fail。
+
+这不是 required Contract item 漏召回：两臂都拿到了方向/航段 validation-description，自适应臂的 policy/validation 召回完整。单次同模型结果不能证明 selector 是唯一因果，但 A-130 的发布门只要求观察到任务质量下降即失败，不允许用 token 下降抵消。
+
+## 5. 结论
+
+A-130 判定为：`failed-quality-gate; release-blocked`。
+
+本次真实对照同时证明：
+
+1. H6 的否证成立：较少 input tokens 和工具调用不保证更快或质量不降；
+2. 新增反证成立：Adaptive Bundle 的完整 JSON 包络不保证比完整 Context 更小；在小型真实 Contract 中，`deferredItems`、digest、source 与健康元数据可使首包反而增大；
+3. A-129 的隔离 corpus 收益不能外推为真实 Host 收益；
+4. `1.7.0` 不具备发布资格。
+
+上述是 `2026-09-12` 原始外部证据，其数值和失败结论不因后续修复而改写。
+
+## 6. 后续本地补救与复验边界
+
+用户后续授权将 A-130 修复与 `docs/25` 协议正确性统一处理。本地实现已：
+
+- 把 Host 审查用的 `context-query --json` 与模型输入用的 `context-query --prompt` 分开；
+- 在完整适用 Context 不大于机器审查 Bundle 时确定性选择 `complete-fallback`；
+- 用 A-130R 本地回归证明小 Contract 下 `--prompt` 与完整 Context 字节等价，不把 deferred/review 包络发给模型。
+
+这消除了首次失败中已知的输入包络差异，但当时不等于新的真实 Host/Provider 对照已经通过。后续第 7 节记录了单独授权后的新对照；Git 与发布始终继续需独立授权。
+
+## 7. 修复后真实 Host/Provider 复验
+
+用户于 `2026-09-12` 单独授权复验，并在被告知当前 `custom` Provider 会接收两份私有生产源码、evaluation-only Project Context、任务与结构化 schema 后明确确认传输。权限仅限两次只读 A-130 复验，不授权发布。
+
+复验保持同一目标源码、任务、八项 oracle、输出 schema、`gpt-5.6-sol/high`、Codex CLI `0.146.0`、`--ephemeral` 和 `read-only` sandbox。为控制模型波动，完整 Context 基准臂与修复后 `--prompt` 臂均重新执行。
+
+| 指标 | 完整 Context 复验 | 修复后 `--prompt` | 变化 |
+| --- | ---: | ---: | ---: |
+| 初始提示 UTF-8 字节 | 12,351 | 5,283 | **-57.2%** |
+| Provider 报告 input tokens | 141,308 | 154,902 | **+9.6%** |
+| cached input tokens | 96,640 | 116,352 | +20.4% |
+| output tokens | 6,608 | 7,391 | +11.8% |
+| Host 只读命令调用 | 3 | 4 | +33.3% |
+| 观察墙钟时间 | 约 147 秒 | 约 150 秒 | +1.9% |
+| oracle 正确项 | **8/8** | **7/8** | **-12.5%** |
+| 最终质量判定 | pass | fail | **失败** |
+
+修复后 `delivery.mode` 为 `adaptive`，模型投影本体 4,017 字节，加上固定评测任务包装后首包 5,283 字节。它确实不再携带 deferred/review JSON 包络，但端到端 tokens、命令数、耗时与质量都没有优于同轮完整 Context。
+
+质量失败与首次相同：`--prompt` 臂再次把 `priceList[0]` 误解为丢弃同一 `priceDetail` 中的其他方向，而oracle 规定每个 `priceDetail` 只对应一个方向。因此“只分离 JSON 审查包络即可恢复质量”已被否证；单次对照仍不能把唯一因果归结为 selector、Contract 表达或模型随机性中的任一项。
+
+客观证据摘要：
+
+- 完整 prompt SHA-256：`4adad175be003aba872af8c45144b5c81c8c975ffcfe1b653c530a35e9a6a70d`；
+- 修复后完整自适应 prompt SHA-256：`aeab00befc39bbd38d692b84c4a7532a3e441e5213b11d2d9f2b3b8bf4e89382`；
+- 完整臂结果 SHA-256：`326044eb61ff4adcdc3cfe16551bce517af86df8aca27f59fb19c8fb0a2fe75d`；
+- 修复后臂结果 SHA-256：`a40a2a0ae48fe7e1ed50acfc1aace2f95b27ff4aaaff2d3363d9340cec738dc4`。
+
+复验前后目标仓库 `git status --short` 均为空，第 1 节三个文件摘要完全不变。A-130 当前判定为：
+
+> `revalidation-failed-quality-gate; further-remediation-required; release-blocked`
+
+本次 Provider 复验权限已消费。继续修复、再次 Provider 调用、Git 与发布均需新的明确授权。
+
+## 8. `2026-09-14` A-130-S/L 复验停止证据
+
+用户重新单独授权 A-130-S/L Host/Provider 复验，并在完整披露 `custom` Provider、`gpt-5.6-sol/high`、Codex CLI `0.146.0`、`--ephemeral`、只读 sandbox、两份冻结生产源码、evaluation-only Contract、任务与结构化 schema 后，确认冻结并开始执行。该权限不包含发布、Git 写入或真实 PC 项目改写。
+
+本地 preflight 结果：
+
+- A-130-S 的 full 与 candidate canonical prompt 均为 `7,653` UTF-8 字节，摘要同为 `sha256:9820e483e19f7e4ed11b5d3e70f0055a87ddaba5361cf5162ff5f09f8fe97442`，逐字节一致；
+- A-130-L 的 full 为 `18,226` 字节，candidate 为 `6,146` 字节，下降 `66.3%`；candidate 为真实 `adaptive`，批准的 validation、dependency fact、alias 与 required recall 均完整；
+- 两套隔离 Context 均为 `clean`；冻结源码 manifest 摘要为 `sha256:b535182b0e6883a7ee2b85e7fe537b60a081b7e4da9eb290530c7b2765e7538f`。
+
+按 `full→candidate` 顺序执行 A-130-S 第 1 对后，两臂使用相同的 `9,199` 字节 Host prompt，均为 `7/8`，且只在 `baggage` 检查失败：
+
+| 指标 | full | candidate |
+| --- | ---: | ---: |
+| Provider input tokens | 111,217 | 214,136 |
+| cached input tokens | 64,896 | 160,896 |
+| output tokens | 3,565 | 5,047 |
+| reasoning output tokens | 1,200 | 1,656 |
+| Host 只读命令数 | 3 | 7 |
+| 首个 Agent message | 16.507 秒 | 17.780 秒 |
+| 总墙钟时间 | 83 秒 | 122 秒 |
+| 结果摘要 | `sha256:f7f66c01c765c2c0f45944b5c0c6ad3b998982e6572a720768c6b866df8c4c13` | `sha256:85045f36baa323bbbe9a67b270f32f162a556e138c239aae0d9de1a1910f4654` |
+
+两臂一致指出：源码把 `freeCheckinLuggageDesc` 作为展示文本，把 `freeBaggage` 作为布尔式样式/可用性标志；本轮 fixture 却错误地把 `freeBaggage` 写成“手提行李值”。这是共同的 oracle 表述错误，不是 adaptive 相对 full 的质量下降，也不能据此判定真实 PC 源码缺陷。
+
+依据 `docs/26` 的 paired-full/adaptive 共同歧义停止规则，本轮立即停止剩余 10 次 Provider 调用，A-130-L 未进入 Provider。一次归档目录缺失造成的预启动失败在模型结果前被中止，不计有效样本。前后源码 manifest 完全一致，真实目标仓库 `git status --short` 前后均为空；无禁止路径访问、无目标写入、无 Git 变化。
+
+当前裁定：
+
+> `revalidation-inconclusive-fixture-oracle-error; correction-and-new-authorization-required; release-blocked`
+
+本次 Provider 权限已消费。下一步只能先由人确认正确语义：“`freeCheckinLuggageDesc` 是展示文本，`freeBaggage` 是布尔式样式/可用性标志”，重新冻结 A-130-S fixture；之后再次 Provider 调用仍需新的明确授权。
+
+## 9. baggage oracle 人工确认与重新冻结
+
+用户随后明确确认：
+
+- `freeCheckinLuggageDesc` 是展示文本；
+- `freeBaggage === false` 时视觉突出。
+
+隔离 A-130-S Contract 据此新增批准 fact `fact-baggage-display-semantics`，把 validation 的 baggage 检查修正为“展示文本 + `false` 条件通过 `is-no-free` 类视觉突出”，并把该 fact 与既有方向不变量一同纳入批准的 retrieval dependency。
+
+修正后本地 preflight：full 与 candidate canonical prompt 均为 `8,497` 字节，摘要同为 `sha256:3f740173548388a1c2fd2c857fd4c449eb4c7ff1371bc3ee13720adb9ed6cc53`；完整 Host prompt 均为 `10,092` 字节，摘要同为 `sha256:327d721fff0840d9060e703d7ca5ea478552d0fb03aa1d7f0cedb64c2299b8b6`。两臂逐字节一致、dependency coverage 完整、fixture `clean`。
+
+A-130-L 继续保持 full `18,226` 字节、adaptive `6,146` 字节，缩减 `66.3%`，required recall 为 `100%`。S/L 已重新冻结并通过当时的 Provider 前本地门，但上一轮 Provider 权限已经消费。
+
+## 10. A-130 有界收敛修订
+
+用户指出 A-130 不应退化为“发现一项就继续修复一项”。复核确认原设计仍有两个评测治理缺口：可追溯 oracle 不等于业务语义正确；逐字节一致的 S 两臂重复三对只是在重复测模型波动。随后授权本地统一修订，结果为：
+
+- oracle 表除来源可追溯外，必须由人以 canonical digest 显式签署；当前 S/L oracle digest 分别为 `sha256:be31262bd4f5395e6771c719b687f57e6ac5d7cd160d713802ea6f970e0d3be9` 与 `sha256:565418540523cef7453c0d59f69bdaf7acba5f944d5f6977ab56c0ee8e364675`；
+- S 只保留 1 对 Provider 冒烟，L 保留 3 个顺序平衡 pair，总上限由 12 次降为 8 次；
+- 两臂共同失败同一检查只属于 fixture/task inconclusive，不触发产品修复；
+- 只有 full 通过、adaptive 失败、可归因到 governed delivery evidence gap，且同一 gap 至少重现两次，才构成产品缺陷；
+- A-130 通过后永久关闭，未来业务样例进入新回归或后续版本。
+
+更新后的本地 preflight 已通过：S plan `sha256:8dd9113f0bc32e9cbf79a1c291afe1fcc440261a50942c62d1ec08b85fb847f9`，L plan `sha256:47d7070ce6da9624de0eb96f44be49ea64547acc6278cdefc3669abed2f079b2`。新的最多 8 次 Provider 调用仍需独立明确授权。
+
+## 11. 修正后有界 Host/Provider 终验
+
+用户于 `2026-09-14` 明确授权执行完整复验，并在通过后完成 `1.7.0` 发布。Host 按冻结顺序执行 S 一对和 L 三个顺序平衡 pair，共取得八个有效结构化结果：
+
+| case / pair | full | candidate | 结论 |
+| --- | ---: | ---: | --- |
+| S / 1 | 8/8 | 8/8 | 字节一致冒烟通过 |
+| L / 1 | 8/8 | 8/8 | 通过 |
+| L / 2 | 8/8 | 8/8 | 通过，顺序 candidate→full |
+| L / 3 | 8/8 | 8/8 | 通过 |
+
+L 的三次中位数证据：
+
+| 指标 | full 中位数 | adaptive 中位数 | 门槛结果 |
+| --- | ---: | ---: | --- |
+| canonical prompt 字节 | 18,226 | 6,146 | 下降 66.3%，通过 |
+| Provider input tokens | 201,770 | 145,861 | adaptive 不高于 full，通过 |
+| Host 只读命令数 | 4 | 3 | adaptive 不高于 full，通过 |
+| 墙钟秒数 | 66 | 69 | 不超过 full 的 1.1 倍，通过 |
+
+所有 candidate 均为真实 `adaptive` 交付，`requiredRecall=1`。八个结果均未报告禁止路径访问、目标写入或 Git 变化；冻结源 manifest 前后一致，真实 `dtg-tmc-pc` 的 `git status --short` 前后均为空。S candidate 曾有一次只产生 `thread.started/turn.started`、未产生模型结果和 usage 的基础设施卡顿，人工中止后重试成功；该无结果尝试不作为质量样本。
+
+仓库内置 `evaluateA130Runs` 对八个有效结果返回：
+
+> `status=passed; pairs=4; runs=8`
+
+因此 A-130 的质量、效率与安全门全部通过，历史失败已由修正后的有界终验证伪；A-130 按冻结规则永久关闭。以后发现的新业务样例进入独立回归或后续版本，不再重开 A-130。