Model registry refresh

Model Registry Refresh

Doctrine

catalog/model-registry.json is the single source of truth scripts/model-policy.mjs fails closed against. Every model name and reasoning-effort value it accepts must trace to official documentation with a citation — never to memory, never to a plausible-sounding guess at a slug. This skill is the repeatable workflow for keeping that registry accurate without letting research cost dominate the orchestrator's context.

When to run

• npm run model-policy:check fails with an error naming a model "not in the verified model registry" — the registry is missing a model the policy (or an operator) wants to use.
• A provider (OpenAI, Anthropic, Cursor) ships new models or retires old ones and the catalog needs to reflect current reality.
• Quarterly staleness check — last_refreshed in catalog/model-registry.json is more than ~3 months old.

Step 1 — delegate research to Haiku Explore agents

Fan out one Haiku Explore agent per harness (or per namespace, for codex) using the Context7 MCP tools (mcp__Context7__resolve-library-id then mcp__Context7__query-docs) plus official docs URLs already cited in the registry. Each research task must:

• Ask for exact slugs/IDs, not families — gpt-5.5 not "the gpt-5 line".
• Ask for reasoning-effort support per model, not per harness — some models in a family predate newer effort levels (see o1/o3/o4-mini lacking none/minimal/xhigh in the current registry).
• Ask for failure-mode evidence — what error shape a bad model name or unsupported effort actually produces (HTTP status, error code/type), so docs/model-policy-matrix.md's failure table stays accurate.
• Require a source citation per claim — a Context7 library ID + section, or an official docs URL. A finding without one is not actionable.
• Require an explicit UNVERIFIED flag on anything the agent could not confirm from a primary source (e.g. inferred from a changelog mention, or contradicted between two docs). Do not let an agent silently round an uncertain claim into a confident one.

Example prompt template (adapt per harness/namespace):

Research current [codex OpenAI models | codex Ollama routing | codex OpenRouter routing |
claude-code subagent model/effort fields | cursor subagent model field] using Context7
(resolve-library-id then query-docs) and official docs. Report, for each model/field:
exact slug or ID, supported reasoning-effort values (if any), and the error shape observed
or documented for an invalid value (HTTP status + error code/type). Cite the Context7 library
ID + section or the exact docs URL for every claim. If you cannot confirm a claim from a
primary source, prefix it UNVERIFIED and say why. Do not guess slugs from training data.

Run these Explore agents in parallel; each is scoped to one harness or namespace so the citations stay traceable to a narrow question.

Step 2 — orchestrator updates the registry

The orchestrator, not a delegate, edits catalog/model-registry.json:

• Add new models with last_verified (today's date) and a source where the schema allows it; update the relevant namespace's sources array if a new canonical URL was used.
• Bump the registry-level last_refreshed date.
• Never remove a model still referenced by catalog/model-policy.json without first migrating the policy rule(s) that reference it to a replacement model — check with npm run model-policy:report before deleting anything.
• Treat every UNVERIFIED-flagged finding from Step 1 as a blocker, not a data point to merge as-is — either verify it directly or leave the registry unchanged for that item.
• Validate the edit against schemas/model-registry.schema.json structurally (required fields, anchored match patterns, last_verified date format) before moving on.

Step 3 — sync the human-readable matrix

Delegate to a Sonnet writer subagent to update docs/model-policy-matrix.md so its tables match the registry exactly (namespace tables, verified-model tables, failure modes, enforcement boundaries). Give the delegate the exact diff you made to catalog/model-registry.json in Step 2 and instruct it to touch only docs/model-policy-matrix.md — no other file, no commits.

Step 4 — verify

Run in order, orchestrator-owned:

npm run model-policy:check          # registry schema + policy resolves against it
npm run validate                    # full gate suite
npm run asset-integrity:write       # LAST — after every other write has settled

The orchestrator reviews the full diff (registry, matrix doc, any touched harness projections) and is the only one who commits. A delegate's self-report that research or writing is "done" is not verification — read the diff and run the gates yourself before accepting.

Delegation defaults

• Haiku — research only (Step 1): Context7 lookups, docs reading, citation gathering. Never writes to catalog/model-registry.json or any tracked file.
• Sonnet — writing only (Step 3): syncing docs/model-policy-matrix.md prose/tables to a registry diff the orchestrator already made. Never edits catalog/model-registry.json itself.
• Orchestrator — owns catalog/model-registry.json edits, schema/gate verification, and the commit. This is the same split .claude/skills/agentic-delegation/SKILL.md codifies more generally: cheap parallel research to Haiku, bulk writing to Sonnet, judgment and commits stay with the orchestrator.