@genee/omp-opsx-addon 0.7.0 → 0.9.0

package/lib/agent-defs.ts

@@ -2,10 +2,14 @@ export const ADDON_VERSION = '0.1.0';
 
 const MARKER = '<!-- @genee/omp-opsx-addon -->';
 
+/** 硬栅栏 marker：CODER_MD 栅栏小节标题与派发浓缩句都必须含它，供正/负断言与防漂移定位（change: opsx-scope-fence）。 */
+export const SCOPE_FENCE_TAG = '【无关状态栅栏】';
+
 const CODE_REVIEWER_MD = (model?: string) => `---
 name: code-reviewer
 description: OpenSpec 代码审查 agent，审查代码实现并执行全局验证
-tools: read, bash, glob, grep${model ? `\nmodel: "${model}"` : ''}
+tools: read, bash, glob, grep
+autoloadSkills: opsx-orchestration-protocol${model ? `\nmodel: "${model}"` : ''}
 ---
 
 你是一位资深代码审查员。你根据 OpenSpec 提案和设计文档审查代码实现，并在审阅的同时执行最后一次全局验证。
@@ -14,12 +18,13 @@ tools: read, bash, glob, grep${model ? `\nmodel: "${model}"` : ''}
 1. 从 prompt 或上下文确定要审查的变更
 2. 读取 proposal、design 和 tasks 文件
 3. 运行 \`git diff HEAD~1\` 或 \`git diff --stat\` 查看改动
-## scratchpad.md 共享缓存
-- 审查前 MUST 先读 \`openspec/changes/<name>/scratchpad.md\`（若存在），只读不改写（工具集无 write/edit）。
-- 以「调研与设计」+「实现探索」两区累计的涉及文件 \`path:line\` 集合为代码审查与增量验证范围：Tier 1（typecheck/lint）与 Tier 3（E2E，如适用）聚焦涉及文件改动面；Tier 2 冒烟套件仍全量执行项目现有测试套件。
+
+## 技能
+- 共享编排协议（scratchpad 四区共享缓存与角色读写矩阵、supersede 权威语义、结论上报去向、报告契约）由技能 \`opsx-orchestration-protocol\` 承载；若它未自动加载，用 Skill tool 读取 \`skill://opsx-orchestration-protocol\` 并遵循其流程。
+
+## 审查范围（scratchpad 涉及文件）
+- 以「调研与设计」+「实现探索」两区累计的涉及文件 \`path:line\` 集合为代码审查与增量验证范围：Tier 1（typecheck/lint）与 Tier 3（E2E，仅终审轮）聚焦涉及文件改动面；Tier 2 按改动分级选范围（见「全局验证」节）。
 - 无 scratchpad.md 时回退：从 proposal/design/tasks 确定审查范围。
-- 识别 \`- [R<n> coder] supersede:\` 条目：以紧随其后的新结论为权威，旧 \`path:line\` 不再作为验证范围；只读不改写。
-- 发现 scratchpad.md 结论与代码现状不符时，作为 P0/P1 审查发现发回，不直接改写。
 
 ## 审查维度
 1. **规范遵循**：是否精确实现了 proposal/design/tasks 定义的内容？有无缺失或偏离？
@@ -29,9 +34,12 @@ tools: read, bash, glob, grep${model ? `\nmodel: "${model}"` : ''}
 
 ## 全局验证（交付前最后一道质量门）
 coder 已在其改动面完成自验证；你的验证是 maker-checker 的兜底确认，与代码审查同轮执行：
-- **Tier 1 – 环境完整性（必需）**：依赖安装、typecheck、lint
-- **Tier 2 – 冒烟测试（必需）**：运行项目现有测试套件（\`bun test\`/\`npm test\` 等）
-- **Tier 3 – E2E（可选）**：变更涉及用户可见行为时运行 E2E
+先定级，再按级别选范围：
+- **微改级**（纯配置 / 展示文案 / 诊断输出 / 单文件可逆，且未命中下方全流程级任一项）：Tier 1 只跑改动面 typecheck/lint（无需依赖安装）；Tier 2 只跑与改动面相关的测试文件，不跑全量套件。
+- **全流程级**（跨文件语义 / 选择行为 / 排序 / 分区 / modelRoles 写入契约）：Tier 1 含依赖安装与完整 typecheck/lint；Tier 2 跑全量测试套件。
+- **Tier 1 – 环境完整性**：依赖安装（仅全流程级）、typecheck、lint
+- **Tier 2 – 冒烟测试**：微改级 → 相关测试文件；全流程级 → 项目现有测试套件（\`bun test\`/\`npm test\` 等）
+- **Tier 3 – E2E（仅终审轮，一次）**：开发过程中的中间轮一律不跑。只有本轮代码审查与 Tier 1 / Tier 2 均无 P0/P1（即本轮通过、无需发回修复）的**终审轮**，才在最后跑一次 E2E；本轮已发回修复（含 P0/P1）时记 N/A，留给后续轮次。变更不涉及用户可见行为时 N/A；因 E2E 自身失败而发回修复的，下一轮终审复核 E2E。
 
 ## 输出格式
 \`\`\`markdown
@@ -55,23 +63,20 @@ coder 已在其改动面完成自验证；你的验证是 maker-checker 的兜
 ### 全局验证
 - [x] / - [ ] Tier 1 环境完整性: <通过/失败项>
 - [x] / - [ ] Tier 2 冒烟测试: <通过/失败项>
-- [x] / - [ ] Tier 3 E2E（如适用）: <通过/失败或 N/A>
+- [x] / - [ ] Tier 3 E2E（仅终审轮；中间轮记 N/A）: <通过/失败或 N/A>
 - 验证失败项（按严重度）：<P0/P1 已并入关键问题；P2+ 告警，不阻塞通过>
 \`\`\`
 
 ## 结论与上报
-你是审查员，**只审查、不改代码**。如实报告，由主 agent 决定是否委派 coder 修复。
-- **APPROVE** → 报告通过
-- **REQUEST_CHANGES + P0/P1** → 返回问题列表，由主 agent 委派 coder 修复
-- **REQUEST_CHANGES + 仅 P2+** → 视为通过，建议可选
-- **BLOCKED** → 说明原因，由用户决策
+- 结论语义与上报去向见技能 \`opsx-orchestration-protocol\` 的「评审闭环与轮次上限」节（审查员只报告、不改代码）。
 - 全局验证失败项按严重度并入结论：P0/P1 → 关键问题（必须修复）；P2 级验证告警 → 改进建议，不阻塞通过
 ${MARKER}
 `;
 const PROPOSAL_REVIEWER_MD = (model?: string) => `---
 name: proposal-reviewer
 description: OpenSpec 提案审查 agent，审查提案质量
-tools: read, bash, glob, grep${model ? `\nmodel: "${model}"` : ''}
+tools: read, bash, glob, grep
+autoloadSkills: opsx-orchestration-protocol${model ? `\nmodel: "${model}"` : ''}
 ---
 
 你是一位资深需求审查员。你审查 OpenSpec 提案的完整性和质量。
@@ -79,11 +84,9 @@ tools: read, bash, glob, grep${model ? `\nmodel: "${model}"` : ''}
 ## 启动
 1. 从 prompt 或上下文确定要审查的提案名称
 2. 读取 proposal.md、design.md（如果存在）
-## scratchpad.md 共享缓存
-- 审查前 MUST 先读 \`openspec/changes/<name>/scratchpad.md\`（若存在），复用其中调研结论与涉及文件，避免重复 read/grep。
-- 只读，不改写 scratchpad.md；你的工具集不含 write/edit，物理上无法写入。
-- 识别 \`- [R<n> coder] supersede:\` 条目：以紧随其后的新结论为权威，旧结论不再作为调研依据；只读不改写。
-- 发现的 P0/P1 与关注点写入审查报告，由主 agent 中转回流，不直接写 scratchpad.md。
+
+## 技能
+- 共享编排协议（scratchpad 四区共享缓存与角色读写矩阵、审查前先读 scratchpad.md 并复用其调研结论、supersede 权威语义、结论上报去向、报告契约）由技能 \`opsx-orchestration-protocol\` 承载；若它未自动加载，用 Skill tool 读取 \`skill://opsx-orchestration-protocol\` 并遵循其流程。
 
 ## 审查维度
 1. **完整性**：Why/What/Capabilities/Impact 是否齐全？有无缺失章节？
@@ -113,56 +116,38 @@ tools: read, bash, glob, grep${model ? `\nmodel: "${model}"` : ''}
 \`\`\`
 
 ## 结论与上报
-- **APPROVE** → 提案通过
-- **REQUEST_CHANGES + P0/P1** → 返回问题列表，由主 agent 委派 planner 修复
-- **REQUEST_CHANGES + 仅 P2+** → 视为通过，建议可选
-- **BLOCKED** → 说明原因，由用户决策
+- 结论语义与上报去向见技能 \`opsx-orchestration-protocol\` 的「评审闭环与轮次上限」节（审查员只报告、不改代码）。
 ${MARKER}
 `;
 
 const CODER_MD = (model?: string) => `---
 name: coder
 description: OpenSpec 变更实现 agent，同步 tasks.md 进度
-tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: "${model}"` : ''}
-skill: openspec-apply-change
+tools: read, write, edit, bash, glob, grep, todo
+autoloadSkills: opsx-orchestration-protocol, openspec-apply-change${model ? `\nmodel: "${model}"` : ''}
 ---
 
 你是一个快速、专注的代码实现 agent。你从 prompt 和对话上下文推断要做什么。
 
-## 启动：确定任务
-0. 加载技能：用 Skill tool 读取 skill://openspec-apply-change 并遵循其流程
-1. 若 prompt 提到变更名称或能推断：读取 \`openspec/changes/<name>/tasks.md\`、\`proposal.md\`、\`design.md\` 并实现未完成任务
-2. 若无名称：运行 \`openspec list --json\`；单个用其，多个或无则停止并询问
-3. 通用编码请求：从 prompt 理解需求直接实现
-
-## 实现规则
-- 写代码前先读现有代码；匹配项目风格和模式
-- 完成任务后在 tasks.md 标记：\`- [ ]\` → \`- [x]\`
-- 每轮结束时根据实际进度更新 tasks.md，确保提案状态与代码一致
-- 代码全部完成后将所有未完成项标记为 \`- [x]\`，在 ACTION 报告中说明变更已全部实现
-- 不修改 \`proposal.md\`、\`design.md\` 或 \`.openspec.yaml\`
+## 技能
+- 本角色的共享编排协议（scratchpad 四区共享缓存与角色读写矩阵、supersede 与两档处置、无关状态硬栅栏、评审闭环与轮次上限、报告契约）由技能 \`opsx-orchestration-protocol\` 承载；若它未自动加载，用 Skill tool 读取 \`skill://opsx-orchestration-protocol\` 并遵循其流程。
+- 本角色的 OpenSpec 实现流程由技能 \`openspec-apply-change\` 承载；若它未自动加载，用 Skill tool 读取 \`skill://openspec-apply-change\` 并遵循其流程。
+
+## 工作边界
+- 不修改 \`proposal.md\`、\`design.md\` 或 \`.openspec.yaml\`。
 - 直接用 read/write/edit/bash 等内置工具实现；不要尝试调用 task 二次委派。
-## scratchpad.md 共享缓存
-- 开工前 MUST 读 \`openspec/changes/<name>/scratchpad.md\`（若存在），复用已记录结论，禁止重复探索。
-- 交付前 MUST 将本轮新探索结论 append 到「实现探索」区（关键符号/数据流、新增涉及文件 \`path:line\`、验证/构建命令、已排除假设），标注 \`- [R<n> coder] <结论>\`。
-- 收到主 agent 中转的 code-reviewer P0/P1 关注点时，开工时先将关注点 append 进「代码审查范围」区，再开始修复。
-- 后续轮次只做增量：仅探索未记录的文件/符号/假设，不重复 read/grep 已记录内容；append-only，不得改写他人结论。
-
-## scratchpad.md 与代码不一致时的两档处置
-执行中发现代码现实与 scratchpad.md 记录不一致时，按两档客观判据处置；判据仅为「偏差是否影响任何 task 的前提或产出定义」，禁止主观估量「问题大小」：
-- **档一：事实快照过期**——偏差不影响任何 task 的前提或产出定义（纯探索性信息：路径 / 行号 / 符号 / 命令漂移）。处置：继续执行当前任务，不终止；在「实现探索」区 append supersede 修正。
-- **档二：契约动摇**——偏差导致 tasks / proposal / design / specs 的有效性存疑（前提不成立、产出定义变、代码现状与设计决策冲突）。处置：立即停止实现，输出 STATUS: blocked（无 SESSION）并说明冲突点，交由主 agent 裁决（改提案 / 确认「现状即新设计」/ 开新 change）。
-- supersede 标注格式：\`- [R<n> coder] supersede: <旧结论摘要>\`，随后一行以 \`- [R<n> coder]\` 标注新结论；两条均落「实现探索」分区，旧结论保留（append-only），不删除。
-- 交付摘要 SUMMARY 义务：本轮发生过 supersede 时，输出格式中的 SUMMARY 行 MUST 提及本次 supersede 清单。
+- 通用编码请求（无 change 目录）：不创建也不维护 scratchpad.md 与 tasks.md，不得为满足流程而搭建空骨架。
+
+## 与本次任务无关的异常状态（硬栅栏）${SCOPE_FENCE_TAG}
+判据与处置见技能 \`opsx-orchestration-protocol\` 的栅栏节；该节仅适用于 coder（实现类）。
 
 ## 验证（交付门槛）
-- 交付前必须跑过 **scoped 到本次改动面** 的 lint、typecheck 与针对性单测（proposal 约定的测试必须通过）；任一未通过不得交付，先修到通过再标记 ACTION: REVIEW_REQUIRED。
+- 交付前必须跑过 **scoped 到本次改动面** 的 lint、typecheck 与针对性单测（若来自提案，proposal 约定的测试必须通过）；任一未通过不得交付，先修到通过再标记 ACTION: REVIEW_REQUIRED。
+- E2E 不属于自验证门槛，开发过程中不跑；整个变更只在终审轮由 code-reviewer 跑一次。
 - 项目级全量校验（全仓库 lint/typecheck/\`bun test\`）不属于自验证门槛：若失败可归因于并发 sibling 的半成品改动（与本改动无关），把失败连同「已排查与本改动无关」的证据作为上下文上报（交付摘要中注明），不要被其阻塞；最终由 code-reviewer 的全局验证兜底确认。
 
 ## 协作流程（由你编排）
-1. **完成实现后**：向主 agent 报告，由主 agent 决定是否委派审查
-2. **收到审查反馈（P0/P1）**：反馈统一由 code-reviewer 回传（含全局验证失败）；用 read/edit/bash 修复后重新标记 ACTION: REVIEW_REQUIRED
-3. **轮次上限**：最多 3 轮（含首次实现与修复）；仍无法解决则 STATUS: blocked
+三条义务（报告 → 修复 → 轮次上限）见技能 \`opsx-orchestration-protocol\` 的「评审闭环与轮次上限」节。
 
 ## 输出格式
 向主 agent 报告时以以下格式结尾：
@@ -184,62 +169,50 @@ ${MARKER}
 const PLANNER_MD = (model?: string) => `---
 name: planner
 description: OpenSpec 提案规划 agent
-tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: "${model}"` : ''}\nskill: openspec-propose
+tools: read, write, edit, bash, glob, grep, todo
+autoloadSkills: opsx-orchestration-protocol, openspec-propose${model ? `\nmodel: "${model}"` : ''}
 ---
 
 你是一个 OpenSpec 提案规划 agent。负责创建和更新 OpenSpec 变更提案文档。
 
-## 启动：确定任务
-1. 加载技能：用 Skill tool 读取 skill://openspec-propose 并遵循其流程
-2. 若 prompt 提到变更名称或能推断：读取 \`openspec/changes/<name>/\` 下已有文件，根据需求创建或更新 proposal/design/tasks
-3. 若无名称：从 prompt 理解需求，确定名称并创建新变更目录
-4. 若提到使用 skill（如 openspec-propose）：用 Skill tool 加载并执行
+## 技能
+- 本角色的共享编排协议（scratchpad 四区共享缓存与角色读写矩阵、supersede 与两档处置、评审闭环与轮次上限、报告契约）由技能 \`opsx-orchestration-protocol\` 承载；若它未自动加载，用 Skill tool 读取 \`skill://opsx-orchestration-protocol\` 并遵循其流程。
+- 本角色的 OpenSpec 提案流程由技能 \`openspec-propose\` 承载；若它未自动加载，用 Skill tool 读取 \`skill://openspec-propose\` 并遵循其流程。
 
-## 工作范围
-- **只负责提案文档**：proposal.md、design.md、tasks.md、specs/（openspec/changes/ 目录下）
+## 工作边界
 - 直接用内置工具；不要尝试调用 task 二次委派。
-## scratchpad.md 共享缓存
-变更目录下维护 \`openspec/changes/<name>/scratchpad.md\` 作四角色共享探索缓存（与 proposal.md/design.md/tasks.md 同级），固定四阶段分区：
-- \`## 调研与设计\`：调研结论、涉及文件（\`path:line\`）、已排除方案
-- \`## 提案审查关注点\`：proposal-reviewer 审查报告中的 P0/P1 与关注点（经主 agent 中转回流）
-- \`## 实现探索\`：coder 每轮 append 的关键符号/数据流、新增涉及文件、验证/构建命令、已排除假设
-- \`## 代码审查范围\`：code-reviewer 审查报告中的 P0/P1 与验证范围结论（经主 agent 中转回流）
-规则：
-- **出提案时 MUST 创建** \`openspec/changes/<name>/scratchpad.md\` 并写入四阶段骨架，预填「调研与设计」初始骨架：调研结论、涉及文件、已排除方案。
-- 后续轮次修改提案时，先读回 scratchpad.md：将 proposal-reviewer 关注点 append 进「提案审查关注点」区，新调研结论增量 append 进「调研与设计」区。
-- 条目以 \`- [R<n> planner] <结论>\` 标注轮次与角色；append-only，不得改写或删除他人结论。
-- 读回 scratchpad.md 时，以最新 supersede 条目为权威（识别 \`- [R<n> coder] supersede:\` 标记，其后的新结论优先于旧结论）。
+- scratchpad.md 的创建与预填规则见协议技能；单文件可逆微改动（快车道）不创建。
 
 ## 提案拆分
-- 接大需求先评估契约边界:能拆则拆成多个小变更,先输出拆分建议(契约边界+提案清单)待主 agent 确认后再开写。
+- 接大需求先评估契约边界:能拆则拆成多个小变更,先输出拆分建议(契约边界+提案清单)待主 agent 确认后再开写。对冲:同批串行落地、共享编辑区的强耦合改动合并为一个提案不拆;拆分收益仅在分批落地时成立。
 - 纲领/roadmap change 只做层级管理(阶段/依赖/验收口径),不含实现细节。
 
 ## Budget 估算
 
-在 proposal.md 末尾输出 \`## Budget Estimate\` 章节。Budget 必须覆盖**完整编排流程**的全部 agent 消耗（planner → proposal-reviewer → coder → code-reviewer + 可能的修复轮次），不只是提案撰写。
+在 proposal.md 末尾输出 \`## Budget Estimate\` 章节。估算本次提案**实际会走的**编排消耗；走快车道的微改动只估算提案成本并注明免审。
 
 ### 快速公式
-\`总额 = (涉及文件数 × 80K + 固定编排开销 120K) × 轮次系数\`
+\`总额 = (涉及文件数 × 80K + 编排开销) × 轮次系数\`（编排开销见下）
 
 - **涉及文件数**：需修改或新建的源文件数量（不含 proposal/design/tasks 等提案文档本身）
-- **固定编排开销**：120K tokens（planner 30K + proposal-reviewer 20K + code-reviewer(审查+全局验证) 30K + 主 agent 委派及缓冲 40K）
+- **编排开销**：全流程 120K tokens（planner 30K + proposal-reviewer 20K + code-reviewer(审查+全局验证) 30K + 主 agent 委派及缓冲 40K）；快车道为 0（无额外审查轮，实现由主 agent 或单次 coder 完成）
 - **轮次系数**：预期 1 轮 = 1.0，2 轮 = 1.3，3 轮 = 1.5
 
 ### 输出格式
 \`\`\`
 ## Budget Estimate
 - 涉及文件数: &lt;F&gt;
-- 预计审查轮次: &lt;R&gt;
+- 预计审查轮次: &lt;R&gt;（快车道免审 → 0）
 - 预计实现 token: &lt;F × 80K × R&gt;K
-- 预计审查 token: &lt;R × 25K&gt;K
-- 编排固定开销: 120K
+- 预计审查 token: &lt;R × 25K&gt;K（快车道免审 → 0）
+- 编排开销: 120K（全流程）/ 0（快车道）
 - 建议 /goal budget: &lt;总额&gt;K tokens
 \`\`\`
 
 ### 参考示例
 - 3 个文件、1 轮 → (240 + 120) × 1.0 = 360 → \`建议 /goal budget: 360K tokens\`
 - 8 个文件、2 轮 → (640 + 120) × 1.3 = 988 → \`建议 /goal budget: 990K tokens\`
-- 单文件修复、1 轮 → (80 + 120) × 1.0 = 200 → \`建议 /goal budget: 200K tokens\`
+- 单文件微改动（快车道）→ 不计编排开销：(80 + 0) × 1.0 = 80 → \`建议 /goal budget: 80K tokens\`
 
 ## 输出
 完成后列出所有创建或修改的文件及变更名称。

package/lib/complexity-router.ts

@@ -0,0 +1,336 @@
+/**
+ * Difficulty router (programme smart-model-selection W4 / change:
+ * difficulty-routed-selection) — classify a user prompt into a task band and
+ * derive write-set tier target offsets.
+ *
+ * Pipeline position (design D1): hard-constraint filtering (existing pool
+ * layer, untouched) → difficulty banding (THIS module) → in-band selection
+ * (the W1-W3 frozen order runs unchanged under the offset targets) → stall
+ * escalation + continuity guard → quality band knob.
+ *
+ * `classifyTask` is a PURE function: deterministic, no clock, no RNG, no
+ * session state, linear in prompt length (the hot path must stay far cheaper
+ * than generation — no LLM call, LiteLLM hybrid scorer explicitly out of
+ * scope per proposal Non-Goals).
+ *
+ * Signal families and caps are a portable subset of LiteLLM's
+ * complexity_router weights (config.py:429-446); band boundaries 0.15 / 0.35
+ * / 0.60 are LiteLLM 同款. Density-scaled families saturate at their cap, so
+ * a family's contribution is its weight × intensity, capped at the weight.
+ *
+ * Failure semantics are SAFE-SIDE (the LiteLLM failure mode "no evidence →
+ * 0.0 → cheapest band by default" is deliberately inverted):
+ * `classifyTaskSafe` maps an exception or a confidence below
+ * `CONFIDENCE_FLOOR` to `complex` (the strong band). Ambiguity never
+ * silently downgrades — cost ambiguity is the opt-in adopter's informed
+ * choice (design D2).
+ *
+ * plan-mode awareness: the host's plan-mode state is NOT visible to plugins
+ * (extension events and ctx carry no planMode field — verified at proposal
+ * time), so plan/intent detection is prompt-text-based; the plan marker
+ * vocabulary lives in `REASONING_MARKERS`.
+ *
+ * Confidence formula (supersedes the D2 sketch「命中信号族数归一 × 边界距
+ * 离」): evidence saturation × margin-modulated factor, i.e.
+ *   confidence = min(1, Σ|contributions| / EVIDENCE_CAP)
+ *              × (MARGIN_FLOOR + (1 − MARGIN_FLOOR) × min(1, dist/0.15))
+ * with EVIDENCE_CAP = 0.25, MARGIN_FLOOR = 0.6. The sketch's literal form
+ * (hitCount/7 × margin) mathematically caps at 0.29 for clean short
+ * housekeeping prompts and cannot reach the spec floor of 0.35, while any
+ * "applicable families" normalization scores empty ambiguous prompts as
+ * confident. The implemented form keeps both factors — evidence dominates,
+ * boundary margin modulates — and satisfies every spec scenario: rich
+ * reasoning prompts and clean housekeeping commands classify with
+ * confidence ≥ floor; evidence-free ambiguous phrases stay below it (and
+ * thus take the safe-side strong band).
+ */
+
+import { type TierName, TIER_NAMES, TIER_RANK } from './model-tiers.js';
+import { OMP_ROLE_TO_TIER, OMP_WRITE_SET_ROLES } from './model-roles.js';
+import type { SelectionContext } from '../index.js';
+
+/** Task difficulty bands, ordered from cheapest to strongest. */
+export const TASK_BANDS = ['simple', 'standard', 'complex', 'reasoning'] as const;
+export type TaskBand = (typeof TASK_BANDS)[number];
+
+/** Numeric rank of a band (higher = stronger); the guard's upgrade comparison. */
+export function bandRank(band: TaskBand): number {
+    return TASK_BANDS.indexOf(band);
+}
+
+/** Score → band thresholds (LiteLLM 同款): <0.15 simple, <0.35 standard, <0.60 complex, else reasoning. */
+export const BAND_BOUNDARIES = [0.15, 0.35, 0.6] as const;
+
+/** Confidence floor: below this (or on a classifier exception) the safe side applies. */
+export const CONFIDENCE_FLOOR = 0.35;
+
+/** Write-set tier target offset per band (design D3), clamped to [tiny, top]. */
+export const BAND_TIER_OFFSET: Record<TaskBand, number> = {
+    simple: -1,
+    standard: 0,
+    complex: 1,
+    reasoning: 2,
+};
+
+/** Quality band knob values (design D6). */
+export const QUALITY_PREFERENCES = ['balanced', 'cost', 'quality'] as const;
+export type QualityPreference = (typeof QUALITY_PREFERENCES)[number];
+
+/** `difficulty_routing` config (design D7). */
+export interface RoutingConfig {
+    enabled: boolean;
+}
+
+/** Classification result: the band plus evidence confidence in [0,1]. */
+export interface Classification {
+    band: TaskBand;
+    confidence: number;
+}
+
+/** Optional classification context. Reserved for hybrid scoring — the
+ *  near-window tool signatures are carried for future use and logged by the
+ *  caller, never scored (design D2: keep the pure function state-free). */
+export interface ClassifyContext {
+    toolSignatures?: readonly string[];
+}
+
+// ── signal vocabularies ─────────────────────────────────────────────────
+
+const CJK = /[\u4e00-\u9fff\u3040-\u30ff\uac00-\ud7af]/;
+
+/** Plan / design / reasoning markers. ≥2 distinct → full family weight. */
+const REASONING_MARKERS: RegExp[] = [
+    /\bthink/i, /\bplan/i, /\bdesign/i, /\barchitect/i, /\brefactor/i,
+    /\banalyz/i, /\banalys/i, /\bwhy\b/i, /\boptimiz/i, /\btrade[- ]?off/i,
+    /\bstrategy/i, /\binvestigat/i, /\broot cause/i, /\bevaluat/i, /\bapproach\b/i,
+    /方案/, /设计/, /规划/, /推理/, /分析/, /为什么/, /逐步/, /重构/, /架构/,
+    /权衡/, /思路/, /策略/, /评估/, /优化/, /调研/, /根因/, /梳理/,
+];
+
+/** Code-presence probes: fences, inline code, shell command lines, file paths. */
+const CODE_FENCE = /```/;
+const CODE_INLINE = /`[^`\n]+`/;
+const CODE_COMMAND = /(^|\n)\s*(\$|npm|bun|pnpm|yarn|cargo|make|sudo|python3?|pip)\s/;
+const CODE_PATH = /\b[\w@-]+(?:\/[\w@.-]+)+|\b[\w-]+\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|sql|json|ya?ml|toml|sh)\b/g;
+
+/** Housekeeping verbs (negative signal). Gated on short prompts without fences. */
+const SIMPLE_VERBS: RegExp[] = [
+    /\bformat\b/i, /\blint\b/i, /\brename\b/i, /\bfix typo/i, /\bclean ?up\b/i,
+    /\btidy\b/i, /\bprettify\b/i, /\blist\b/i, /\bshow\b/i, /\bprint\b/i,
+    /\bopen\b/i, /\bcount\b/i, /\bwhere is\b/i,
+    /格式化/, /重命名/, /改名/, /清理/, /整理/, /列出/, /查看/, /打印/, /删除/, /打开/, /找到/, /搜索/, /数一下/,
+];
+/** Above this token count a housekeeping verb no longer reads as a simple task. */
+const SIMPLE_MAX_TOKENS = 30;
+
+/** Technical terms; density (distinct hits) scales the family weight. */
+const TECH_TERMS: RegExp[] = [
+    /\bapi\b/i, /\bfunction/i, /\bclass\b/i, /\btype\b/i, /\binterface\b/i,
+    /\bbug\b/i, /\berror\b/i, /\bexception\b/i, /\btest\b/i, /\bdeploy/i,
+    /\bdatabase\b/i, /\bsql\b/i, /\bregex/i, /\bcache\b/i, /\bthread/i,
+    /\basync\b/i, /\bschema\b/i, /\bendpoint\b/i, /\bcompil/i, /\bbuild\b/i,
+    /\blint\b/i, /\bconfig\b/i, /\bdependenc/i, /\bmerge\b/i, /\bbranch\b/i,
+    /\bcommit\b/i, /\bserver\b/i, /\bclient\b/i, /\bdocker\b/i, /\bgit\b/i,
+    /函数/, /接口/, /类型/, /变量/, /数据库/, /编译/, /部署/, /缓存/, /线程/,
+    /异步/, /依赖/, /服务端/, /客户端/, /配置/, /测试/, /组件/, /模块/,
+    /算法/, /数据结构/, /性能/, /内存/,
+];
+
+/** Multi-step patterns (numbered lists, sequencing words). */
+const MULTI_STEP: RegExp[] = [
+    /\bfirst\b/i, /\bthen\b/i, /\bafter that\b/i, /\bfinally\b/i,
+    /\bstep [-#]?\d/i, /(^|\n)\s*\d+[.、)]\s/,
+    /首先/, /其次/, /然后/, /接着/, /最后/, /第一步/, /第二步/, /先.{0,12}再/,
+];
+
+/** Interrogative cues (multiple question marks or question words). */
+const QUESTION_WORDS: RegExp[] = [
+    /\bwhy\b/i, /\bhow\b/i, /\bcompare\b/i, /\bexplain\b/i,
+    /为什么/, /怎么/, /如何/, /区别/, /原理/, /原因/,
+];
+
+/** Family weight caps (design D2). */
+const WEIGHT_REASONING = 0.25;
+const WEIGHT_CODE = 0.3;
+const WEIGHT_TECH = 0.25;
+const WEIGHT_SIMPLE = -0.05;
+const WEIGHT_MULTI_STEP = 0.03;
+const WEIGHT_QUESTION = 0.02;
+const WEIGHT_TOKEN = 0.1;
+
+/** Token-count log term: 0.10 × min(1, log2(1 + tokens) / 4). */
+const TOKEN_LOG_DIVISOR = 4;
+
+/** Confidence tuning (module header formula). */
+const EVIDENCE_CAP = 0.25;
+const MARGIN_SCALE = 0.15;
+const MARGIN_FLOOR = 0.6;
+
+/** Count tokens: CJK chars individually plus non-CJK whitespace words. */
+function countTokens(prompt: string): number {
+    const cjk = prompt.match(/[\u4e00-\u9fff\u3040-\u30ff\uac00-\ud7af]/g)?.length ?? 0;
+    const words = prompt.replace(/[\u4e00-\u9fff\u3040-\u30ff\uac00-\ud7af]/g, ' ').split(/\s+/).filter(Boolean).length;
+    return cjk + words;
+}
+
+function countMatches(patterns: RegExp[], text: string): number {
+    let n = 0;
+    for (const p of patterns) {
+        p.lastIndex = 0;
+        if (p.test(text)) n++;
+    }
+    return n;
+}
+
+/**
+ * Classify a prompt into a task band (pure function — design D2).
+ *
+ * Score s = Σ family contributions, clamped to [0, 1]; band by
+ * BAND_BOUNDARIES. Confidence per the module header formula: evidence
+ * saturation (Σ|contributions| / EVIDENCE_CAP, capped at 1) × a
+ * margin-modulated factor (0.6 + 0.4 × normalized distance to the nearest
+ * band boundary). `context` is accepted for the hybrid extension point and
+ * never scored.
+ */
+export function classifyTask(prompt: string, _context?: ClassifyContext): Classification {
+    const text = prompt ?? '';
+    const tokens = countTokens(text);
+    const fence = CODE_FENCE.test(text);
+    const inline = CODE_INLINE.test(text);
+
+    // Housekeeping verb hit — gated on short, fence-free prompts.
+    const simpleHit = tokens <= SIMPLE_MAX_TOKENS && !fence && countMatches(SIMPLE_VERBS, text) > 0;
+
+    // Code presence. A housekeeping command's file arguments (rename X to Y)
+    // are payload, not code — path probes are suppressed for gated simple
+    // prompts so "rename utils.ts" does not read as a coding task.
+    let codeSignals = 0;
+    if (fence) codeSignals += 1;
+    if (inline) codeSignals += 1;
+    if (CODE_COMMAND.test(text)) codeSignals += 1;
+    const pathMatch = simpleHit && !inline ? null : CODE_PATH;
+    if (pathMatch) {
+        CODE_PATH.lastIndex = 0;
+        codeSignals += Math.min(2, (text.match(CODE_PATH) ?? []).length);
+    }
+
+    const reasoningDistinct = countMatches(REASONING_MARKERS, text);
+    const techDistinct = countMatches(TECH_TERMS, text);
+    const multiStep = countMatches(MULTI_STEP, text) > 0;
+    const questionMarks = (text.match(/\?/g) ?? []).length >= 2;
+    const questionWord = countMatches(QUESTION_WORDS, text) > 0;
+    const question = questionMarks || questionWord;
+
+    const cReasoning = WEIGHT_REASONING * Math.min(1, reasoningDistinct / 2);
+    const cCode = WEIGHT_CODE * Math.min(1, codeSignals / 2);
+    const cTech = WEIGHT_TECH * Math.min(1, techDistinct / 3);
+    const cSimple = simpleHit ? WEIGHT_SIMPLE : 0;
+    const cMulti = multiStep ? WEIGHT_MULTI_STEP : 0;
+    const cQuestion = question ? WEIGHT_QUESTION : 0;
+    const cToken = WEIGHT_TOKEN * Math.min(1, Math.log2(1 + tokens) / TOKEN_LOG_DIVISOR);
+
+    const score = Math.max(0, Math.min(1, cReasoning + cCode + cTech + cSimple + cMulti + cQuestion + cToken));
+
+    let band: TaskBand = 'reasoning';
+    for (let i = 0; i < BAND_BOUNDARIES.length; i++) {
+        if (score < BAND_BOUNDARIES[i]) {
+            band = TASK_BANDS[i];
+            break;
+        }
+    }
+
+    // Confidence: evidence saturation × margin-modulated factor (module header).
+    const fired = Math.abs(cReasoning) + Math.abs(cCode) + Math.abs(cTech)
+        + Math.abs(cSimple) + Math.abs(cMulti) + Math.abs(cQuestion) + Math.abs(cToken);
+    const evidence = Math.min(1, fired / EVIDENCE_CAP);
+    let dist = 1 - score; // reasoning band: no upper boundary in BAND_BOUNDARIES
+    for (const b of BAND_BOUNDARIES) {
+        const d = Math.abs(score - b);
+        if (d < dist) dist = d;
+    }
+    const margin = Math.min(1, dist / MARGIN_SCALE);
+    const confidence = evidence * (MARGIN_FLOOR + (1 - MARGIN_FLOOR) * margin);
+
+    return { band, confidence };
+}
+
+/**
+ * Safe-side wrapper (design D2): an exception inside the classifier or a
+ * confidence below CONFIDENCE_FLOOR yields `complex` (the strong band) —
+ * never a silent downgrade to the cheapest band. The `classify` parameter is
+ * a test-only injection seam (defaults to the pure classifier).
+ */
+export function classifyTaskSafe(
+    prompt: string,
+    context?: ClassifyContext,
+    classify: (p: string, c?: ClassifyContext) => Classification = classifyTask,
+): Classification {
+    try {
+        const result = classify(prompt, context);
+        if (result.confidence < CONFIDENCE_FLOOR) {
+            return { band: 'complex', confidence: result.confidence };
+        }
+        return result;
+    } catch {
+        return { band: 'complex', confidence: 0 };
+    }
+}
+
+/**
+ * Apply the band offset to write-set tier targets (design D3). ONLY
+ * `OMP_WRITE_SET_ROLES` ({smol, default, slow, vision}) are redirected —
+ * non-write-set roles are never touched (the pick-model-ux minimal-write-set
+ * red line). Base target = the map's explicit entry, else the built-in role
+ * default (model_role_tiers overrides keep working); the `skip` sentinel is
+ * preserved verbatim (a user opt-out is never rewritten). `stallActive`
+ * bumps `default` one extra tier (design D4), then the result clamps to
+ * [tiny, top]. Returns a NEW map; the input is not mutated.
+ */
+export function applyBandOffset(
+    roleTiers: Record<string, TierName | 'skip'>,
+    band: TaskBand,
+    opts?: { stallActive?: boolean },
+): Record<string, TierName | 'skip'> {
+    const out = { ...roleTiers };
+    for (const role of OMP_WRITE_SET_ROLES) {
+        const base = out[role] ?? OMP_ROLE_TO_TIER[role];
+        if (base === 'skip' || base === undefined) continue;
+        let rank = TIER_RANK[base] + BAND_TIER_OFFSET[band];
+        if (opts?.stallActive && role === 'default') rank += 1;
+        const clamped = Math.max(0, Math.min(TIER_NAMES.length - 1, rank));
+        out[role] = TIER_NAMES[clamped];
+    }
+    return out;
+}
+
+// ── routing runtime (assembly-layer payload, design D8.5) ───────────────
+
+/** Continuity-guard inputs carried on the runtime (see continuity-guard.ts). */
+export interface GuardRuntimeInput {
+    /** `continuity_guard.weight` — minimum confidence for an upgrade switch. */
+    weight: number;
+    /** Prior selection (the plugin closure's cached SelectionContext). */
+    incumbent: SelectionContext | null;
+    /** Band recorded on the prior selection; null = unknown (neutral standard). */
+    priorBand: TaskBand | null;
+}
+
+/**
+ * Per-recompute routing payload threaded into computeSelectionSync
+ * (design D8.5). `undefined` = every switch off + balanced — the zero-drift
+ * contract is that the selection path never sees a routing object at all.
+ */
+export interface RoutingRuntime {
+    /** Task band driving write-set tier offsets. */
+    band: TaskBand;
+    /** Classification confidence (annotation + guard upgrade threshold). */
+    confidence: number;
+    /** Stall escalation in effect (default alias +1, design D4). */
+    stallActive: boolean;
+    /** /pick-model explicit path: guard bypassed, no fresh classification, no band annotation. */
+    explicit: boolean;
+    /** Quality band knob (undefined/balanced = existing comparator branches, byte-identical). */
+    qualityPreference?: QualityPreference;
+    /** Continuity guard inputs (undefined = guard off / explicit). */
+    guard?: GuardRuntimeInput;
+}