ADR 压缩与受控检索

ADR 压缩的目标是减少重复阅读，而不是删除决策历史。它与现有提交门禁相互独立。已接受 ADR 仍然有效，直到明确接受的后继决策替代它。 CURRENT 是经过评审的派生视图，不是新决策，也不证明代码已经符合决策。

日常流程

/adr compaction
/adr compaction --mode summary
/adr compaction --mode consolidate --sources ADR-0001,ADR-0002
/adr compaction --mode consolidate --domain runtime --archive

第一个命令只进行本地只读分析：不调用模型，不创建文件，不接受决策。即使指定模式，--dry-run 也保持这一性质。机械分析不能证明语义等价。

显式起草模式依次经过：

1. 范围与成本 Ask。 展示证据记录数、字符数及“字符数/4”的粗略 token 估算。只授权读取证据和起草。成本对话本身需要少量模型轮次；证据、输出、工具定义、上下文重放和评审另有开销。不推断供应商价格或支出上限。
2. 有界证据与候选。 代理分页读取完整证据、预留编号、保留独立有用的记录，并建立逐决策覆盖矩阵。选择源记录只限制可替代目标；完整 CURRENT 仍需要未受影响的当前记录作为证据。
3. 评审。 检查完整候选 ADR、保留或改变的约束、双向血缘、CURRENT、来源信息、确定性索引，以及可选移动和链接修复。本地评审文件与分页工具提供完整变更。
4. 原生 Ask。 选择接受并执行、仅保存提案草稿、要求修改或取消。摘要模式提供发布摘要／要求修改／取消。一次接受即可执行已展示的完整计划，不要求逐条 /adr decide 或再次确认。

发布／移动阻塞会移除执行选项，但仍可检查候选、保存提案草稿。仅保存草稿不发布索引或 CURRENT。

拒绝、关闭或过期的问题不构成同意。源文件、成员集合、配置、目标路径或计划改变后，必须重新评审。问题绑定会话、原生调用／请求、修订号及内容哈希，模型自己提供的确认标记无效。确认窗口为 30 分钟。

整合支持 N 对 M，而不只支持多合一。独立有用的记录可以保持原样。每个源决策单元必须有覆盖项；只替代部分单元的 OCP 容器保持有效，不能借容器退役隐式接受其中的提案。结构覆盖只是必要条件，语义保真和有意改变仍由人评审。

大型草稿：分批提交候选

代理可调用 adr_compaction 的 stage，提供稳定的 batch 键和包含 summary、replacements、coverage 三个数组的 candidate 子集，允许空数组。 每批解析后的载荷最多 12,000 个 Unicode 码点。同键重试会替换整批，不追加重复内容； 源覆盖行和后继编号不能跨批次重复。batches 可分页取回已存草稿；条目拆分时须继续读取并重组。

读完全部必要证据并保存所有批次后，调用不带 candidate 的 submit，由服务组装并执行与完整提交 相同的校验。之后才能评审并通过原生 Ask 授权执行。修改批次会使旧封印／Ask 失效，完全相同的重试不会。 显式提交完整 candidate 会替换已存批次。分批保存只写本地草稿状态，不写 ADR、CURRENT 或索引。

这避免要求模型在最后一次输出中生成整个大型计划，但不消除证据／上下文重放成本， 不保证跨批次语义综合质量，也不拆分单篇后继正文：单篇后继须装入一批，或采用完整提交。 若正文超过供应商输出上限，应在不丢失约束的前提下缩小范围，不能静默截断。

编号与配置

后继采用显式指定或项目配置的 ocp、madr、nygard 风格，并在整个项目范围分配身份，包括归档中的编号。--style 仅用于整合。顺序编号不复用。迭代编号必须提供已获批准的 --baseline 和 --iteration，工具不猜测下一版本命名空间。OCP 迭代容器不能与同命名空间的其他容器或逐决策文件静默冲突。

--domain 与 --sources 互斥。摘要模式拒绝归档、风格及编号参数。未知或冲突参数报错。自定义文件名仍须符合现有 ADR 引擎的数字前缀发现规则，否则拒绝候选，而不是写出无法发现的记录。

任务检索

/adr context
/adr context ADR-0002
/adr context ADR-0.40.0#01 --history
/adr context --domain runtime
/adr context --iteration 0.40.0
/adr check --compaction

代理使用原生 adr_context，选择 id、domain 或 iteration，可指定 intent: current|rationale|history 和分页 cursor。不要让代理模拟用户的确认命令。

• 新鲜 CURRENT 提供精简决策意图；过期、缺失或损坏时，回退为有界源证据或导航。读取时检查源成员及内容哈希，涵盖日常／手工新增、删除、状态或章节修改、迁移和移动，不自动付费刷新摘要。
• 包含适用的系统约束。查询被替代编号的当前意图时，优先返回无歧义的已接受后继。历史引用是查询入口，不是递归阅读全文的指令。
• 单次响应最多 8 项、12,000 个 Unicode 码点，包含 JSON 元数据。摘录最多 1,600 码点；一般关系最多展开 3 跳，每次请求最多跨 1 跳归档正文。
• 必要约束仍不完整时，不能忽略 coverage: incomplete 与 next。游标绑定查询与源快照，源变化后失效。重复证据会提示，但没有跨所有原生读取器的会话级 token 硬上限。
• 工作子代理和 Lite 可以检索证据。维护起草保持主 ADR 插件的作用域限制，工具型辅助会话被排除。

读取策略

/adr config readGuard off
/adr config readGuard warn
/adr config readGuard guard

默认为 off，独立于治理模式和 /adr guard。warn 去重提示；guard 在内容输出前拒绝受支持的直接归档读取、过期 CURRENT、超大 ADR 读取、覆盖 ADR 的全根正文搜索及可识别的批量／归档 Shell 命令。定向读取有效记录和文件名发现仍可使用。匹配已有路径时解析符号链接；维护写入拒绝符号链接路径和越界。

这是上下文效率辅助，不是安全沙箱。已经真实验证的原生取消路径是 read（在 OpenCode 1.18.15 上验证；v2 2.0.x 线暴露同名工具，针对 v2 的运行时复验待集成测试阶段完成）。适配器还识别 read_file、grep 及有限的明显 bash／shell 参数形状。任意脚本、混淆 Shell、Git 历史、MCP、未适配工具及原生读取累计预算，不保证全面拦截。被拦截后应改用定向 adr_context 历史检索，而不是绕路读取。

配置损坏时会提示，并在当前运行实例保留最近有效模式；新进程没有有效配置时从 off 开始并披露降级，不自行创建全面拒绝策略。压缩不会偷偷启用读取门禁。

文件、归档和恢复

<adr-root>/CURRENT.md
<adr-root>/CURRENT.sources.json
<adr-root>/INDEX.md
<adr-root>/archive/<original-filename>.md
<ocp-state>/adr-compaction/<plan-id>.review.md

正式源文件、CURRENT 文件对和索引应进入版本控制；计划、回执、锁和日志保存在被忽略的本地状态目录。<ocp-state> 默认 .ocp，遵守项目相对路径 OCP_PROJECT_DIR 契约。自定义／模块 ADR 根拥有各自 CURRENT 文件对和跨根导航；全局检索保留项目级覆盖。

/adr compaction archive --sources ADR-0001
/adr compaction archive restore cp-0123456789abcdef
/adr compaction status
/adr compaction status cp-0123456789abcdef
/adr compaction --confirm cp-0123456789abcdef

归档和恢复先准备原生 Ask 评审。仅完全退役且相关血缘有效的记录可归档。身份及决策正文保留，相对链接和译文指针可能发生明确展示的机械修复；不能保证修复外部链接。恢复撤销位置和链接变更，不撤销决策接受。已新鲜的摘要可在评审后的纯移动中机械重发，过期摘要不会被静默标记为新鲜。

接受／审计、视图／索引、归档和移动后视图使用独立事务日志。先写入已接受后继，再退役前驱。中断后只能从原始字节或计划内字节恢复；无关编辑、新 ADR 和配置变化会阻止恢复。status 展示状态、各日志完成情况和回执；待恢复事务（包括批准后、首份日志之前以及日志阶段之间的间隙）不会被检索误报为完整发布，并会阻止新计划创建或执行。

--confirm 是用户对已评审计划的备用／恢复入口，它可以接受列出的决策，而不只是保存文件。恢复保留原始操作者和选项，不能改变模式、源集合或归档范围。重启不恢复内存中的 Ask，需重新请求 Ask 或使用这一显式备用入口。

不要自动删除锁：检查 PID／拥有者，确认写入者已经停止后才能清理。解决编辑冲突时不要重置工作区。文件移动失败后，不要删除已接受后继来“回滚”；逆转决策应走正常后继治理。

验证与成本证据

参见验证和基准结果；安装／发布步骤与仍存在的平台限制见交付状态。可复现原生测试使用确定性的本地模型，不调用付费供应商，覆盖分批起草、四种批准结果、受支持读取取消、实际进程中断恢复及单独批准的逆向归档。另有 14 个写入边界的进程中断矩阵和隔离安装包／哈希检查。合成 token 测量区分首次起草与后续检索，并以现有“上下文导航＋定向源文件”作为对照，不是语义质量评分，也不承诺固定节省比例。