@open-agent-toolkit/cli 0.2.19 → 0.2.20

package/assets/config/dispatch-matrix-recommendation.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026-07-11.1",
+  "version": "2026-07-25.1",
   "providers": {
     "codex": {
       "economy": {
@@ -102,23 +102,33 @@
       "economy": {
         "candidates": [
           "composer-2.5",
-          "claude-sonnet-5-high",
           "gpt-5.6-luna-high",
           "gpt-5.6-luna-xhigh"
         ]
       },
       "balanced": {
-        "candidates": ["cursor-grok-4.5-high", "gpt-5.6-terra-high"]
+        "candidates": [
+          "cursor-grok-4.5-high",
+          "gpt-5.6-terra-high",
+          "claude-opus-5-thinking-low"
+        ]
       },
       "high": {
-        "candidates": ["gpt-5.6-sol-medium", "gpt-5.6-sol-high"]
+        "candidates": [
+          "gpt-5.6-sol-medium",
+          "gpt-5.6-sol-high",
+          "claude-opus-5-thinking-medium",
+          "claude-opus-5-thinking-high"
+        ]
       },
       "frontier": {
         "candidates": [
           "claude-fable-5-thinking-high",
           "claude-fable-5-thinking-xhigh",
           "gpt-5.6-sol-xhigh",
-          "gpt-5.6-sol-max"
+          "gpt-5.6-sol-max",
+          "claude-opus-5-thinking-xhigh",
+          "claude-opus-5-thinking-max"
         ]
       }
     }

package/assets/docs/cli-utilities/configuration.md

@@ -361,13 +361,18 @@ even when the reusable ladder is user-owned.
 }
 ```
 
+The example above is illustrative rather than a copy of the bundled ladder; its
+tiers are trimmed for readability.
+
 The bundled recommendation covers 13 Codex model/effort combinations: Luna and
 Terra at `low`, `medium`, `high`, and `xhigh`, plus Sol at those efforts and
-`max`. Claude covers `haiku`, `sonnet`, `opus`, and `fable`. Cursor covers 12
-verified multi-family flat IDs across Composer, Claude, GPT, and Grok. An
-explicit mapping connects each flat ladder ID to a separate bracket-form
-frontmatter model; configuration and skills never derive or normalize either
-form.
+`max`. Claude covers `haiku`, `sonnet`, `opus`, and `fable`. Cursor covers 16
+candidates across four tiers, drawn from a materialization catalogue of 18
+verified multi-family flat IDs spanning Composer, Claude (Sonnet, Opus, and
+Fable), GPT, and Grok; the two figures differ because some approved mappings
+stay materializable without being recommended. An explicit mapping connects
+each flat ladder ID to a separate bracket-form frontmatter model; configuration
+and skills never derive or normalize either form.
 
 The corresponding pinned Codex variant catalogue includes
 `gpt-5.6-luna-high`, `gpt-5.6-terra-xhigh`, `gpt-5.6-sol-high`, and

package/assets/docs/contributing/index.md

@@ -17,3 +17,4 @@ Use this section when you are changing OAT itself rather than consuming it as a
 - [Commit Conventions](commit-conventions.md) - Traceable commit patterns for project and docs work.
 - [Hooks and Safety](hooks-and-safety.md) - Safety and mutation contracts for provider-sync behavior.
 - [Smoke Testing](smoke-testing.md) - Runbook for the live workflow smoke runner: prerequisites, scenarios, evidence reports, and recovery.
+- [Verifying Cursor Pins](verifying-cursor-pins.md) - Runbook for probe-verifying a Cursor model pin before shipping it.

package/assets/docs/contributing/verifying-cursor-pins.md

@@ -0,0 +1,282 @@
+---
+title: Verifying Cursor Pins
+description: 'Runbook for probe-verifying a Cursor model pin before shipping it: evidence channel, hook capture, subjects and controls, interpretation, and cleanup.'
+---
+
+# Verifying Cursor Pins
+
+A Cursor model pin maps an OAT ladder model ID to the frontmatter selector that
+materialized role files carry, for example `claude-opus-5-thinking-medium` to
+`claude-opus-5[effort=medium]`. Adding one to
+`packages/cli/src/providers/cursor/codec/catalog.ts` requires evidence that
+Cursor actually resolves that selector to the intended model.
+
+This runbook produces that evidence. Run it before adding any mapping.
+
+## Why a probe is required
+
+`DR-260718-explicit-cursor-pin-mapping` requires mapping-specific,
+native-launch evidence before a mapping may be marked `approved`. Two things
+that look like evidence are not:
+
+- **Structural validation.** That a mapping is well-formed says nothing about
+  what Cursor does with it.
+- **Agent self-report.** A subagent asked to name its own model is not a
+  reliable witness, and the probe agents in this runbook deliberately do not
+  ask.
+
+The catalog alone is also insufficient wherever a family carries both a
+thinking and a non-thinking flat ID at the same rung. Opus 5 carries both at
+low, medium, and high, so the bracket selector is genuinely ambiguous there and
+only a probe can resolve it. At rungs where only one variant exists, the
+catalog settles the question without a probe — but you still need the probe to
+prove the effort parameter was honored at all.
+
+## Evidence channel
+
+Cursor's agent lifecycle hooks report resolution from Cursor itself. Two
+independent events agree:
+
+- `subagentStart.subagent_model` — the model the subagent will use, and the
+  authoritative field per Cursor's hooks reference.
+- `preToolUse.model` — observed from inside the subagent's own tool call.
+
+Two channels that do **not** work:
+
+- **The `cursor-agent` CLI and remote runtime.** Agent lifecycle hooks do not
+  fire there. A Task subagent launched from that runtime produces zero hook
+  events, and every row records as not-reported. Run probes from the Cursor
+  desktop app's Agent Chat.
+- **The subagent card label.** It is built from the requested bracket
+  parameters and drops the thinking qualifier, so it cannot distinguish the
+  thinking and non-thinking variants — precisely the distinction a probe exists
+  to settle.
+
+As of Cursor 3.12.30, `model_params` (which would carry an explicit `thinking`
+flag) is empty and `model_id` is absent. Thinking is therefore established by
+the resolved slug itself, which is sound because the non-thinking IDs are
+distinct.
+
+## Prerequisites
+
+- Cursor desktop app, with the repository open as a workspace.
+- The live catalog for the families you intend to pin:
+
+```bash
+cursor-agent models
+```
+
+Read the full output rather than truncating it. You need to see whether a
+thinking and a non-thinking ID both exist at each rung, and which rung carries
+the family's unqualified display label.
+
+## Setting up capture
+
+Both files are temporary. Delete them when the probe is done.
+
+Create `.cursor/hooks/g01-capture.sh`:
+
+```bash
+#!/bin/bash
+# TEMPORARY pin-probe capture hook. Delete after probing.
+set -u
+
+OUT_DIR="/tmp/g01-probe"
+OUT="$OUT_DIR/hooks.jsonl"
+mkdir -p "$OUT_DIR" 2>/dev/null || :
+
+input=$(cat)
+ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
+
+printf '{"captured_at":"%s","payload":%s}\n' "$ts" "$input" >>"$OUT" 2>/dev/null || :
+
+event=$(printf '%s' "$input" |
+  sed -n 's/.*"hook_event_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')
+
+# Observe only. Never block, never fail closed.
+case "$event" in
+  subagentStop) printf '{}\n' ;;
+  *) printf '{"permission":"allow"}\n' ;;
+esac
+
+exit 0
+```
+
+Make it executable, then register it in `.cursor/hooks.json` for
+`subagentStart`, `subagentStop`, and `preToolUse`:
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "subagentStart": [
+      { "command": ".cursor/hooks/g01-capture.sh", "timeout": 10 }
+    ],
+    "subagentStop": [
+      { "command": ".cursor/hooks/g01-capture.sh", "timeout": 10 }
+    ],
+    "preToolUse": [{ "command": ".cursor/hooks/g01-capture.sh", "timeout": 10 }]
+  }
+}
+```
+
+The hook must observe only. A capture hook that can block or fail closed can
+change the behavior it is supposed to measure.
+
+Restart Cursor or reload the window so the hooks register.
+
+## Writing probe agents
+
+One throwaway agent per selector, under `.cursor/agents/`. Keep them trivial:
+the probe is the hook payload, not anything the agent produces.
+
+````markdown
+---
+# TEMPORARY pin probe - not oat-managed. Delete after probing.
+# Class: subject - expect claude-opus-5-thinking-medium
+name: zz-pin-probe-opus5-medium
+description: Temporary pin probe (subject) for claude-opus-5[effort=medium]. Delete after use.
+model: claude-opus-5[effort=medium]
+---
+
+## Role
+
+You are a throwaway pin probe. Run exactly one command and then stop:
+
+```bash
+echo PIN-PROBE zz-pin-probe-opus5-medium
+```
+
+Then reply with the single word `done`. Do not read files or use any
+other tool.
+
+Cursor's hook payload is the evidence for this probe. Your own claim about
+your identity is not evidence and is deliberately not requested.
+````
+
+The `echo` exists to force a tool call, which is what produces the
+corroborating `preToolUse` event.
+
+### Subjects and controls
+
+Probe every rung you intend to pin. Then add controls, which are what make the
+subject results interpretable:
+
+| Class            | Example selector               | Proves                                                           |
+| ---------------- | ------------------------------ | ---------------------------------------------------------------- |
+| Subject          | `claude-opus-5[effort=medium]` | The mapping resolves as intended                                 |
+| Positive control | `claude-sonnet-5[effort=high]` | Reproduces an already-verified mapping                           |
+| Negative control | `claude-opus-9[effort=high]`   | Unknown family — the channel reports resolution, not the request |
+| Negative control | `claude-opus-5[effort=ultra]`  | Unknown effort — exposes rung-level fallback                     |
+
+The negative controls carry most of the interpretive weight. Without them you
+cannot distinguish a hook that reports what Cursor actually resolved from one
+that merely echoes what you asked for. A bogus family that comes back as the
+bogus family would invalidate the entire run.
+
+## Running
+
+Launch each probe agent from the Cursor desktop app's Agent Chat, as a subagent
+with no model override, so Cursor resolves from the agent's frontmatter. Let
+each finish before starting the next.
+
+Then read the resolutions:
+
+```bash
+python3 - <<'PY'
+import json
+for line in open('/tmp/g01-probe/hooks.jsonl'):
+    p = json.loads(line).get('payload', {})
+    if p.get('hook_event_name') == 'subagentStart':
+        print(p.get('subagent_name'), '->', p.get('subagent_model'))
+PY
+```
+
+## Interpreting results
+
+### Unresolvable components fall back silently
+
+Cursor does not reject a malformed pin. It substitutes a default for whichever
+component it cannot resolve, with no error or warning:
+
+- An unknown **family** falls back to the account default model. Probing
+  `claude-opus-9[effort=high]` resolved to `cursor-grok-4.5-high-fast`.
+- An unknown **effort** falls back to that family's default rung. Probing
+  `claude-opus-5[effort=ultra]` resolved to `claude-opus-5-thinking-high`.
+
+This makes a typo in a selector more dangerous than a plain downgrade: the pin
+silently tracks whatever Cursor currently designates as the default, so a
+vendor-side change alters capability with no change in this repository.
+
+### The default rung is family-specific
+
+Exactly one rung per family carries an unqualified display label in the live
+catalog, and that marks the default. It is not always `high`:
+
+| Family   | Default rung | Unqualified label | Contrast                 |
+| -------- | ------------ | ----------------- | ------------------------ |
+| Opus 5   | high         | `Opus 5 1M`       | `Opus 5 1M Medium`       |
+| Opus 4.8 | high         | `Opus 4.8 1M`     | `Opus 4.8 1M Extra High` |
+| Opus 4.7 | **xhigh**    | `Opus 4.7 1M`     | `Opus 4.7 1M High`       |
+
+Opus 4.7 is the disconfirming case for a naive "high is always the default"
+reading.
+
+### A default-rung result proves nothing on its own
+
+If the rung you requested happens to be the family default, the observation is
+equally consistent with the effort parameter being honored and with it being
+ignored. That row cannot stand alone.
+
+Always probe at least one non-default rung in the same family. A set of
+non-default rungs that each resolve as requested is what demonstrates the
+parameter is genuinely honored; a default-rung row is then sound by inference
+across the set rather than from its own evidence.
+
+## Recording the result
+
+Add the mapping with a probe record, which ties it to the evidence that
+approved it:
+
+```ts
+approvedMapping(
+  'claude-opus-5-thinking-medium',
+  'claude-opus-5[effort=medium]',
+  'claude-effort',
+  { probeName: 'zz-pin-probe-opus5-medium', verifiedAt: '2026-07-25', evidencePath: '...' },
+),
+```
+
+The record asserts that `submittedSelector` equals the mapping's
+`frontmatterModel` and `resolvedModel` equals its `ladderModelId`. A mapping
+edited later without re-probing therefore fails its own consistency test rather
+than inheriting an approval that never covered the new selector.
+
+Retain the raw payloads alongside the summary. They are the primary evidence;
+the summary is an interpretation of them.
+
+## Cleanup
+
+Delete every temporary artifact:
+
+- `.cursor/hooks.json` and `.cursor/hooks/g01-capture.sh`
+- all `zz-pin-probe-*` agent files
+- the capture file under `/tmp`
+
+Before committing retained payloads, redact machine and identity fields.
+Cursor hook payloads carry `user_email`, `workspace_roots`, and an absolute
+`transcript_path`. None carries probe evidence — resolution is read from
+`subagent_model` — so removing them costs nothing and keeps private data out of
+the repository.
+
+Confirm the workspace is clean:
+
+```bash
+oat sync --scope project
+```
+
+## Related
+
+- [Smoke Testing](smoke-testing.md) - Runbook for the live workflow smoke runner.
+- [Dispatch Policy](../workflows/projects/dispatch-ceiling.md) - How pins reach the recommendation and role files.
+- [Provider Sync](../provider-sync/providers.md) - Provider-specific sync behavior.

package/assets/docs/workflows/projects/dispatch-ceiling.md

@@ -64,6 +64,23 @@ existing cells. Planning shows the complete recommendation before asking which
 scope should own it. If the resulting ladder is still missing or incomplete,
 planning remains blocked rather than replacing the user's explicit values.
 
+### Upgrading to a newer recommendation version
+
+Preservation applies to whole cells, which has a consequence worth stating
+plainly: when a new recommendation version adds candidates to a tier you have
+already populated, re-running adoption will not give them to you. The existing
+cell is kept intact rather than merged candidate by candidate. Removals are not
+propagated either.
+
+To pick up a new version, compare your
+`workflow.dispatchCeiling.recommendationVersion` against the bundled version,
+then either edit the affected cells by hand or clear them and re-adopt.
+
+Version `2026-07-25.1` is a live example: it adds Opus 5 rungs to the Cursor
+`balanced`, `high`, and `frontier` tiers and drops `claude-sonnet-5-high` from
+`economy`. An adopter still on the prior version keeps their existing Cursor
+tiers untouched until they take one of those actions.
+
 Before offering adoption, planning runs `oat config list --json` once and treats
 its output as the effective boundary across shared, repo-local, user, and
 bundled-default precedence. A complete effective ladder skips adoption even
@@ -194,10 +211,14 @@ candidate in each tier:
   `max`.
 - **Claude:** `haiku`, `sonnet`, `opus`, and `fable` across the ordered named
   tiers.
-- **Cursor:** 12 verified multi-family flat IDs across Composer, Claude, GPT,
-  and Grok. The explicit materialization catalogue maps each flat ladder ID to
-  a separate bracket-form frontmatter model; OAT does not derive or normalize
-  either value.
+- **Cursor:** verified multi-family flat IDs across Composer, Claude (Sonnet,
+  Opus, and Fable), GPT, and Grok. Two counts apply and they differ: the
+  bundled recommendation carries 16 Cursor candidates across the four tiers,
+  while the materialization catalogue carries 18 flat IDs. The extra entries
+  are approved mappings deliberately kept out of the recommendation but still
+  materializable. The catalogue maps each flat ladder ID to a separate
+  bracket-form frontmatter model; OAT does not derive or normalize either
+  value.
 
 The final candidate in a named tier defines that tier's reviewer ceiling. Lower
 reviewer selection requires a separate reviewed contract; a normal reviewer
@@ -305,6 +326,11 @@ separate evidence layers:
 - The materialized definition uses the mapping's explicit bracket-form
   frontmatter model.
 - Mapping-specific native-launch evidence authorizes the shipped mapping data.
+  An approved mapping may carry a probe record whose `submittedSelector` must
+  equal the mapping's `frontmatterModel` and whose `resolvedModel` must equal
+  its `ladderModelId`, so editing a mapping without re-probing fails its own
+  test rather than inheriting an approval it was never granted. See
+  [Verifying Cursor Pins](../../contributing/verifying-cursor-pins.md).
 - `oat doctor` checks current flat-ID catalogue availability, which can detect
   drift but cannot prove a definition pin.
 - The launcher records the selected variant and mapped model with `configured`
@@ -316,6 +342,26 @@ prevent a requested definition pin. Native variant acceptance is therefore not
 runtime-model verification, and skills must not promote self-report or
 catalogue presence into observed identity.
 
+#### Unresolvable selectors also fall back silently
+
+Entitlement is not the only trigger. Cursor does not reject a malformed pin
+either; it substitutes a default for whichever selector component it cannot
+resolve, with no error or warning:
+
+- An unknown family falls back to the account default model. Probing
+  `claude-opus-9[effort=high]` resolved to `cursor-grok-4.5-high-fast`.
+- An unknown effort falls back to that family's default rung. Probing
+  `claude-opus-5[effort=ultra]` resolved to `claude-opus-5-thinking-high`.
+
+The default rung is family-specific and is not always `high` — Opus 4.7
+defaults to `xhigh`. A typo in a pinned selector therefore ships a
+working-but-wrong model that silently tracks a vendor-controlled default, so
+capability can change with no corresponding change in the repository.
+
+OAT does not currently validate effort rungs at sync time; that is tracked as
+`BL-260726-validate-cursor-pin-effort`. Until it lands, the probe runbook is
+the only guard.
+
 ## Phase and Optional-Worker Layers
 
 The phase implementer directly implements the phase tasks from one Phase Scope

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.19",
-  "docs-config": "0.2.19",
-  "docs-theme": "0.2.19",
-  "docs-transforms": "0.2.19"
+  "cli": "0.2.20",
+  "docs-config": "0.2.20",
+  "docs-theme": "0.2.20",
+  "docs-transforms": "0.2.20"
 }

package/assets/skills/subagent-orchestration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subagent-orchestration
-version: 1.0.0
+version: 1.0.1
 description: Use when delegating work to subagents or choosing a model for a task — routing by task class, selecting provider-specific models and effort, and verifying subagent claims. Covers OpenAI/Codex, Anthropic/Claude, and Cursor.
 compatibility: Self-contained; no OAT installation required.
 user-invocable: true

package/assets/skills/subagent-orchestration/references/evidence-and-refresh.md

@@ -1,10 +1,10 @@
 # Evidence and Refresh Policy
 
 ```yaml
-guidance_version: 2026-07-21
-last_verified: 2026-07-21
-review_after: 2026-09-04
-stale_after: 2026-10-19
+guidance_version: 2026-07-25
+last_verified: 2026-07-25
+review_after: 2026-09-08
+stale_after: 2026-10-23
 ```
 
 This file governs dated provider examples. It does not override a live catalog,
@@ -17,8 +17,11 @@ authorization boundary.
 - `review-required`: older than 45 days, a newer family is observed, or a material control, price, tool, context, alias, or harness change is detected.
 - `stale`: older than 90 days, named models are unavailable or deprecated, or the launching surface can no longer express the recorded controls.
 
-Provider mappings in this package become review-required on 2026-09-04 and
-stale on 2026-10-19 unless re-verified earlier.
+Provider mappings in this package become review-required on 2026-09-08 and
+stale on 2026-10-23 unless re-verified earlier, or on the earlier date a
+reference states in its own header. `provider-cursor.md` carries an earlier
+2026-09-04 review date because its catalog was not re-verified in the
+2026-07-25 refresh.
 
 ## Immediate Review Triggers
 
@@ -61,24 +64,61 @@ When evidence is incomplete, retain the incumbent or route one class up.
 
 Do not use aggregate leaderboard rank as a universal model order.
 
+## Comparable-Rung Analysis
+
+For cross-provider analysis, show same-labelled effort rungs first when they
+exist, then show empirically interesting practical substitutions as a separate
+view. Label the model, effort, service tier, harness, benchmark version, and
+retrieval date for every row.
+
+Same-labelled rungs are comparable observations, not equivalent controls.
+CursorBench, provider-native coding-agent harnesses, and common-agent harnesses
+produce different Opus-to-Sol relationships. Preserve that disagreement; never
+publish a provider-independent effort conversion.
+
 ## Current Evidence Summary
 
 - OpenAI positions GPT-5.6 Sol as frontier, Terra as balanced, and Luna as
   high-volume. Official guidance starts at medium generally, but independent
   coding-agent data shows meaningful Luna/Terra quality cliffs below high for
   repository work. The dated mechanical Codex floor is therefore Luna high.
-- Anthropic positions Sonnet 5 as the speed/intelligence workhorse, Opus 4.8 as
-  a complex coding and enterprise model, and Fable 5 as the most capable widely
-  released model. Their effort defaults and recommendations differ by model.
+- Post-release Opus 5 evidence supports medium for normal substantive Claude
+  work and high for hard reasoning. Use xhigh for a reasoning-depth bottleneck
+  or evaluated long-horizon gain; max is selective and requires an effort
+  sweep. Consequence adds independent review rather than automatically raising
+  effort.
+- Sonnet 5 is a conditional route when measured latency, throughput, access,
+  rate limits, or end-to-end workload economics win. Fable 5 is an
+  eligibility-gated specialist; its missing-domain-concept or long-horizon
+  reviewer instantiation remains provisional, and zero-data-retention
+  requirements exclude the current route.
 - CursorBench supports Composer 2.5 as an economical bounded coding worker.
   Cursor explicitly documents Composer fast as the same intelligence at a
   higher latency tier price.
+- Mechanical reconnaissance remains harness-specific: Luna high in Codex,
+  Haiku 4.5 in Claude, and Composer 2.5 in Cursor. Direct API mini or nano
+  routes are limited to strict extraction, classification, or similarly
+  mechanically verified work.
 - OpenAI's long-context evidence disqualifies Luna for some very large-context
-  work even when Luna's nominal context window accepts the input.
-- Anthropic documents benign false positives from Fable's stronger cyber
-  classifier. This is operational evidence to consider when routing
-  cyber-sensitive work, not a capability weakness or a reason to invert the
-  general Opus-first policy.
+  work even when Luna's nominal context window accepts the input. Sol's current
+  direct-API requests above 272K input tokens carry a 2× input and 1.5× output
+  price step.
+- Sol's measured advantage is trajectory efficiency, not universal list-price
+  leadership. Opus output token pricing can be lower while Sol costs less per
+  completed task through fewer tokens, steps, turns, or recoveries.
+- Two independent benchmarks show top-end Opus effort is non-monotonic:
+  Artificial Analysis Coding Agent Index (xhigh 67, max 66) and Frontier-Bench
+  (xhigh 44.4%, max 43.3%), both retrieved 2026-07-25. Frontier-Bench is
+  vendor-operated and its figure rests on a single self-reported row with no
+  independently verified counterpart, so weight it below the Coding Agent Index
+  rather than treating the two as equal evidence. CursorBench 3.2 is monotonic
+  over the same range, 69.3% to 70.0%; its contribution is economic, since
+  marginal cost per score point is roughly 3.75x worse above high than below
+  it. Together these support treating max as a route requiring justification,
+  not a strictly better rung.
+- Cyber-sensitive and valid dual-use work should start on Opus 5 with
+  documented fallback handling where safeguards block the workflow. Opus 4.8
+  remains a compatibility fallback, not the universal primary.
 - Cursor disclosed that Cursor repository data entered Grok 4.5's training
   mixture. Its CursorBench ranking is evidence of competitiveness, not proof
   of superiority over nearby frontier models. Practical use supports Grok 4.5
@@ -86,8 +126,99 @@ Do not use aggregate leaderboard rank as a universal model order.
   implementation, and hard-reasoning economy routes, with cross-family review
   retained for consequential conclusions.
 
+## Speed and Wall-Clock Contract
+
+Speed evidence must satisfy the multi-measure contract defined in
+`model-selection-principles.md`, which is the single authority for which
+measures are required and which are recorded when available. Do not restate a
+divergent list here.
+
+Every load-bearing quantitative claim requires claim-level provenance:
+
+- a direct result locator, retrieval date, and stable source identity;
+- exact model selector, effort, reasoning mode, service tier, harness, and
+  benchmark version;
+- metric definition, aggregation basis, exclusions, and extraction method;
+- absolute input values before any derived ratio or delta;
+- the formula and units for each derived value;
+- cache, fallback, refusal, retry, and completion treatment;
+- unresolved source gaps stated explicitly rather than inferred away.
+
+The Coding Agent Index time measure is average active agent wall time per task.
+It excludes environment startup and verifier or judge time, and must not be
+relabeled as total user-observed elapsed time. AA-Briefcase time remains
+definition-unverified and must not be compared directly with it. Mutable
+leaderboards require row-level locators; a homepage or aggregate rank is not a
+sufficient source.
+
+This file records reconciled conclusions and the values that drive a rule, not
+the full ledger behind them. Every figure quoted here must name a publicly
+resolvable source: the benchmark, its version, and the retrieval date, so a
+reader outside the authoring environment can check it. Do not cite a private
+research artifact as a locator — an internal packet may hold the working
+arithmetic, but it cannot serve as provenance for published guidance.
+
+## Research Independence and Acceptance
+
+A policy refresh requires:
+
+1. a neutral research brief and isolated independent author lanes;
+2. a source ledger with claim-level provenance for each lane;
+3. reciprocal or independent review that did not author the claim under review;
+4. fact reconciliation before routing synthesis;
+5. a cross-model synthesis that preserves contradictions and uncertainty;
+6. explicit human acceptance of the update scope;
+7. canonical-first application;
+8. downstream parity verification by read-back.
+
+The author and reviewer may use the same evidence, but reviewer output must be
+independently produced. Agreement is not proof. Record disagreements and their
+resolution; do not collapse them into an unsupported consensus.
+
+## Live-Catalog and Downstream Gates
+
+Before adding or changing a selector, verify the live launching surface,
+resolved identity, effort or thinking control, service tier, and absence of
+silent fallback. Direct-provider evidence can nominate a harness candidate but
+cannot prove its alias.
+
+A selector ships only after a live probe verifies those controls for that
+specific mapping. Verification does not generalize: neither across rungs of one
+family nor across families, because a harness may substitute a default for any
+component it cannot resolve. Probe a non-default rung as well, or a result that
+merely matches the family default cannot distinguish an honored parameter from
+an ignored one.
+
+The six Cursor `claude-opus-5` and `claude-opus-4-8` mappings shipped on
+2026-07-25 met this gate; their resolved identities are listed in
+`provider-cursor.md`.
+
+After canonical changes:
+
+1. inventory exact mirrors, wrappers, generated views, and application-specific
+   consumers before synchronization;
+2. use each consumer's supported sync or bundle mechanism;
+3. read back every consumer, including each machine where user-scope copies
+   exist;
+4. require byte-for-byte equality for mirrors and documented semantic parity
+   for intentional wrappers;
+5. search live prompts, rules, code, and configuration for copied historical
+   selectors or effort defaults;
+6. record intentional exceptions and fail the gate while unexplained
+   divergence remains.
+
 ## Reverification Record
 
+One record describes one provider reference. When a single refresh cycle
+updates several provider references, emit one record per provider inside a
+`records:` list and lift the cycle-level fields — `verified_at`, `sources`,
+`claim_provenance`, `independent_author`, `independent_reviewer`,
+`incumbent_changes`, `reason`, `downstream_consumers`, `downstream_parity`, and
+`unresolved_items` — to the parent so they are stated once rather than
+duplicated per provider. Each record then carries only `provider`,
+`harness_context`, `catalog_source`, `models_considered`, `controls_verified`,
+and `eligibility_verified`.
+
 When updating a provider reference, record:
 
 ```yaml
@@ -97,7 +228,14 @@ harness_context: exact launching surface
 catalog_source: tool schema | CLI list | API catalog | UI snapshot
 models_considered: exact selectors
 controls_verified: effort, service tier, reasoning mode, context, tools
-sources: official docs and relevant benchmarks
+eligibility_verified: retention, access, pricing thresholds, safeguards
+sources: direct locators for official docs and relevant benchmark rows
+claim_provenance: selector, effort, harness, metric, locator, retrieval date
+independent_author: identity and model family
+independent_reviewer: identity and model family
 incumbent_changes: additions, replacements, removals, or none
 reason: scheduled review or trigger
+downstream_consumers: mirrors, wrappers, generated views, applications
+downstream_parity: hashes or documented semantic comparison
+unresolved_items: gaps, provisional routes, and deferred probes
 ```