@geraldmaron/construct 1.5.1 → 1.5.3

package/lib/mcp/tools/artifact-author.mjs

@@ -5,23 +5,48 @@
  * the drafted typed-artifact markdown,
  * which gets materialized to its canonical path and run through the release gate.
  * Returns the path and a structured verdict so the agent can fix and re-call.
- * allowScaffold stays off — a real draft is required, never an empty scaffold.
+ *
+ * Type resolution respects the manifest gate. A registered class (builtin,
+ * user/project overlay, or the sanctioned `adhoc`) proceeds; an unknown
+ * non-adhoc class returns a classification/registration result instead of
+ * silently becoming a PRD. `adhoc` needs an explicit title + instructions and
+ * is not a bypass for a known class — naming a registered type through adhoc
+ * is redirected. allowScaffold stays off for a real author pass (a real draft
+ * is required); `dry_run` flips it on to preview the resolved template or the
+ * adhoc scaffold through the same gate without a live model.
  */
 import { runConstructArtifactLoop } from '../../artifact-loop-core.mjs';
+import { resolveArtifactType } from '../../artifact-manifest.mjs';
+import { ADHOC_TYPE } from '../../artifact-manifest-overlay.mjs';
+import { loadProjectConfig } from '../../config/project-config.mjs';
+import { resolveContextBindings } from '../../orchestration/context-bindings.mjs';
+import { synthesize } from '../../knowledge/synthesis.mjs';
 
-export async function authorArtifact(args = {}, { ROOT_DIR } = {}) {
-  const draftMarkdown = args.draft_markdown || args.draft || '';
-  const cwd = args.cwd || process.cwd();
-  const result = await runConstructArtifactLoop({
-    draftMarkdown,
-    artifactType: args.artifact_type,
-    text: args.subject || args.text || '',
-    cwd,
-    rootDir: ROOT_DIR,
-    explicit: true,
-    allowScaffold: false,
-  });
+// context_targets binds an author pass to registered source projects (B3): the
+// ids are validated the same way orchestration runs validate theirs (unknown id
+// → hard error before any authoring), and the multi-project synthesis context is
+// assembled deterministically (dry-run map) and woven into the authoring input so
+// the artifact draws on — and cites — every named project.
+async function resolveContextBlock(args, cwd) {
+  const contextTargets = args.context_targets;
+  if (contextTargets == null || (Array.isArray(contextTargets) && contextTargets.length === 0)) {
+    return { ok: true, block: '', bindings: [] };
+  }
+  const { config } = loadProjectConfig(cwd);
+  let bindings;
+  try {
+    bindings = resolveContextBindings(contextTargets, { config, cwd });
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+  const ask = String(args.subject || args.text || args.instructions || args.title || 'synthesize across the bound projects').trim();
+  const projects = bindings.map((b) => b.id).join(',');
+  const synth = await synthesize({ projects, ask, cwd, dryRun: true });
+  const block = synth.ok ? `\n\n## Cross-project context (cite as project:path)\n\n${synth.context}` : '';
+  return { ok: true, block, bindings };
+}
 
+function toResult(result) {
   return {
     ok: Boolean(result.ok),
     artifact_type: result.artifactType,
@@ -34,3 +59,91 @@ export async function authorArtifact(args = {}, { ROOT_DIR } = {}) {
     summary: result.summary,
   };
 }
+
+async function authorAdhoc(args, { ROOT_DIR, cwd, dryRun, contextBlock = '' }) {
+  const title = String(args.title || '').trim();
+  const instructions = String(args.instructions || '').trim();
+  if (!title || !instructions) {
+    return {
+      ok: false,
+      artifact_type: ADHOC_TYPE,
+      status: 'invalid-request',
+      errors: ['adhoc requires an explicit title and instructions'],
+      guidance: 'Call author_artifact with {type:"adhoc", title, instructions}. For a registered class, pass its type instead.',
+    };
+  }
+
+  // Guard R3: adhoc is for genuinely unstructured one-offs. When the caller
+  // names a registered class (via `for_type` or an exact-match title), redirect
+  // to that class so adhoc never becomes a bypass for a gated type.
+  const namedType = String(args.for_type || '').trim().toLowerCase() || title.toLowerCase();
+  const named = resolveArtifactType(namedType, { rootDir: ROOT_DIR, cwd });
+  if (named.status === 'registered' && named.type !== ADHOC_TYPE) {
+    return {
+      ok: false,
+      artifact_type: ADHOC_TYPE,
+      status: 'redirect',
+      redirect_to: named.type,
+      warnings: [`'${named.type}' is a registered class; author it directly instead of via adhoc.`],
+      guidance: `Call author_artifact with {type:"${named.type}", ...} to use its template and release gate.`,
+    };
+  }
+
+  const draftMarkdown = args.draft_markdown || args.draft || '';
+  const result = await runConstructArtifactLoop({
+    draftMarkdown,
+    artifactType: ADHOC_TYPE,
+    titleOverride: title,
+    instructions,
+    text: `${args.subject || args.text || instructions}${contextBlock}`,
+    cwd,
+    rootDir: ROOT_DIR,
+    explicit: true,
+    allowScaffold: dryRun || !draftMarkdown,
+  });
+  return toResult(result);
+}
+
+export async function authorArtifact(args = {}, { ROOT_DIR } = {}) {
+  const cwd = args.cwd || process.cwd();
+  const dryRun = args.dry_run === true || args.scaffold === true;
+  const requestedType = String(args.artifact_type || '').trim().toLowerCase();
+
+  const ctx = await resolveContextBlock(args, cwd);
+  if (!ctx.ok) {
+    return { ok: false, artifact_type: requestedType || null, status: 'invalid-context-target', errors: [ctx.error] };
+  }
+
+  if (requestedType === ADHOC_TYPE || requestedType === 'ad-hoc' || requestedType === 'free-form' || requestedType === 'freeform') {
+    return authorAdhoc(args, { ROOT_DIR, cwd, dryRun, contextBlock: ctx.block });
+  }
+
+  // Gate intact (R4): an explicitly requested class that resolves to nothing
+  // registered gets the classification/registration answer, not a PRD.
+  if (requestedType) {
+    const resolved = resolveArtifactType(requestedType, { rootDir: ROOT_DIR, cwd });
+    if (resolved.status !== 'registered') {
+      return {
+        ok: false,
+        artifact_type: requestedType,
+        status: 'unrecognized',
+        classification_required: true,
+        errors: [`Document class '${requestedType}' is not registered.`],
+        guidance: `${resolved.guidance} Register it with \`construct templates register ${requestedType}\`, or author a one-off with {type:"adhoc", title, instructions}.`,
+      };
+    }
+  }
+
+  const draftMarkdown = args.draft_markdown || args.draft || '';
+  const result = await runConstructArtifactLoop({
+    draftMarkdown,
+    artifactType: args.artifact_type,
+    text: `${args.subject || args.text || ''}${ctx.block}`,
+    cwd,
+    rootDir: ROOT_DIR,
+    explicit: true,
+    allowScaffold: dryRun,
+  });
+
+  return toResult(result);
+}

package/lib/mcp/tools/orchestration-run.mjs

@@ -73,6 +73,7 @@ export function shapeRun(run) {
     suggestedWorkflowType: run.plan?.suggestedWorkflowType ?? null,
     researchExecutionPolicy: run.plan?.researchExecutionPolicy ?? null,
     specialists: run.plan?.specialists ?? [],
+    contextBindings: run.contextBindings ?? [],
     tasks: (run.tasks || []).map((t) => ({
       id: t.id, role: t.role, status: t.status, executor: t.executor,
       output: t.output ?? null, reasoning: t.reasoning ?? null, error: t.error ?? null,
@@ -85,6 +86,7 @@ export function shapeRun(run) {
       // never be confused with a construct-verified provider execution.
       ...(t.hostPrompt ? { system: t.hostPrompt.system, user: t.hostPrompt.user } : {}),
       ...(t.provenanceSource ? { provenanceSource: t.provenanceSource } : {}),
+      ...(t.evidenceGate ? { evidenceGate: t.evidenceGate } : {}),
     })),
   };
 }
@@ -118,6 +120,7 @@ function toRequest(args) {
     hostProvider: args.host_provider,
     fileCount: args.file_count,
     moduleCount: args.module_count,
+    contextTargets: args.context_targets,
   };
 }
 

package/lib/mcp/tools/skills.mjs

@@ -290,11 +290,28 @@ export async function orchestrationPolicy(args) {
     }
   }
 
+  // A plan is not a tool. Weak models otherwise infer a tool name from
+  // suggestedWorkflowType (e.g. research-synthesis → an invented
+  // `research_synthesis` tool) or freelance raw host tools, bypassing the
+  // governed specialist chain and its anti-fabrication persona. Hand back an
+  // explicit, machine-actionable next step so the caller executes the plan
+  // through orchestration_run instead of guessing. Omitted for the immediate
+  // track, which needs no orchestration. worker_backend is left unset so the
+  // project's configured backend (free/host/inline) is honored — never forced.
+  const nextAction = route.track !== 'immediate'
+    ? {
+      tool: 'orchestration_run',
+      arguments: { request: args?.request || '' },
+      instruction: 'Execute this plan by calling the orchestration_run tool with the request above. suggestedWorkflowType is a plan label, not a tool — do not call it, and do not freelance raw web/file tools in its place.',
+    }
+    : null;
+
   return {
     ...route,
     specialistCatalog: buildSpecialistCatalog(),
     approvalRequired,
     terminalStates: TERMINAL_STATES,
+    nextAction,
     draftTask,
     handoffPacket,
     ...(contextPackets ? { contextPackets } : {}),

package/lib/model-cheapest-provider.mjs

@@ -22,6 +22,7 @@ import path from 'node:path';
 import { getProviderModelCatalog, PROVIDER_FAMILY_TIERS } from './model-router.mjs';
 import { getPricingForModels, formatPricingLabel } from './model-pricing.mjs';
 import { configDir } from './config/xdg.mjs';
+import { isModelTier } from './model-tiers.mjs';
 
 const CHEAPEST_PREF_KEY = 'CHEAPEST_PROVIDER_ENABLED';
 const CHEAPEST_CHECKED_KEY = 'CHEAPEST_PROVIDER_CHECKED';
@@ -47,7 +48,7 @@ const ENV_PATH = path.join(configDir(), 'config.env');
  * }>}
  */
 export async function selectCheapestProvider(tier, opts = {}) {
-  if (!['reasoning', 'standard', 'fast'].includes(tier)) {
+  if (!isModelTier(tier)) {
     return { providerId: null, providerLabel: null, modelId: null, configuredProviders: [], rankedList: [] };
   }
 

package/lib/model-policy.mjs

@@ -0,0 +1,329 @@
+/**
+ * lib/model-policy.mjs — user-facing model policy: presets, the effective-policy
+ * view, and per-specialist resolution traces, layered on the existing resolution
+ * chain (lib/model-router.mjs + lib/embedded-contract/model-resolve.mjs).
+ *
+ * Design constraint (construct-760c.7): the single edit surface for model
+ * assignment is specialists/org/models.json. config.schema is deliberately not a
+ * second surface. Presets are COMPUTED here from the cost/free selectors
+ * (model-cheapest-provider / model-free-selector / model-pricing) and then
+ * PERSISTED to models.json, which already sits below env pins in the chain — so
+ * CX_MODEL_<TIER> pins keep overriding and nothing new enters the chain.
+ *
+ * Budget invariant: computeBudgetTiers never treats a missing price as $0. An
+ * unknown or unreachable price ranks a candidate LAST, and flagship ids are
+ * hard-excluded — so with only an OpenRouter credential no frontier model can be
+ * selected for any tier, even when live pricing is unreachable.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  defaultModelRegistryPath,
+  getProviderModelCatalog,
+  resolveModelTiers,
+  MODEL_TIER_BY_WORK_CATEGORY,
+} from './model-router.mjs';
+import { getPricingForModels } from './model-pricing.mjs';
+import { pollFreeModels, selectForTier, isFreeModel } from './model-free-selector.mjs';
+import { getSpecialist } from './registry/loader.mjs';
+import { MODEL_TIERS } from './model-tiers.mjs';
+
+export const POLICY_PRESETS = ['budget', 'free', 'frontier', 'local'];
+export const POLICY_TIERS = MODEL_TIERS;
+
+// Flagship, high-cost models a budget/free policy must never resolve to. The set
+// mirrors the reasoning/standard flagships declared in PROVIDER_FAMILY_TIERS so a
+// preset can hard-exclude them regardless of whether live pricing was reachable;
+// the regex catches the same families' newer point releases.
+
+const FRONTIER_MODEL_IDS = new Set([
+  'anthropic/claude-opus-4-6',
+  'anthropic/claude-sonnet-4-6',
+  'openrouter/anthropic/claude-opus-4-6',
+  'openrouter/anthropic/claude-sonnet-4-6',
+  'openai/gpt-5.4',
+  'openai/gpt-5.1',
+  'openrouter/openai/gpt-5.4',
+  'openrouter/openai/gpt-5.1',
+  'openrouter/google/gemini-2.5-pro',
+  'openrouter/meta-llama/llama-3.1-405b-instruct',
+  'github-copilot/gpt-5.5',
+  'github-copilot/gpt-5.4',
+]);
+
+const FRONTIER_PATTERN = /(claude-opus|claude-sonnet|gpt-5\.(4|5)|gemini-2\.5-pro|llama-3\.1-405b|405b-instruct)/i;
+
+export function isFrontierModel(modelId) {
+  if (!modelId || typeof modelId !== 'string') return false;
+  if (isFreeModel(modelId)) return false;
+  return FRONTIER_MODEL_IDS.has(modelId) || FRONTIER_PATTERN.test(modelId);
+}
+
+function uniq(values) {
+  return [...new Set(values.filter((v) => typeof v === 'string' && v.trim()))];
+}
+
+function configuredProviders(env) {
+  const catalog = getProviderModelCatalog({ env });
+  return catalog.providers.filter((p) => p.configured);
+}
+
+function tierDefinition(primary, fallback = []) {
+  return { primary, fallback: uniq(fallback.filter((id) => id !== primary)) };
+}
+
+// Candidate models for a tier from every configured provider: the tier pin plus
+// the shipped option list. Frontier ids are dropped so a budget/free preset can
+// never rank one, whatever the pricing outcome.
+
+function budgetCandidates(providers, tier) {
+  const ids = [];
+  const local = new Set();
+  for (const p of providers) {
+    const list = uniq([p.tiers?.[tier], ...(p.options?.[tier] ?? [])]);
+    for (const id of list) {
+      ids.push(id);
+      if (p.local === true) local.add(id);
+    }
+  }
+  return { ids: uniq(ids).filter((id) => !isFrontierModel(id)), local };
+}
+
+/**
+ * Compute the budget tier assignments: the cheapest eligible model per tier from
+ * configured providers. Unknown/unreachable prices rank LAST (never $0), so the
+ * budget invariant holds even when the pricing fetch fails.
+ */
+export async function computeBudgetTiers({ env = process.env, getPricing = getPricingForModels } = {}) {
+  const providers = configuredProviders(env);
+  const warnings = [];
+  const models = {};
+  let pricingDegraded = false;
+
+  for (const tier of POLICY_TIERS) {
+    const { ids, local } = budgetCandidates(providers, tier);
+    if (ids.length === 0) {
+      models[tier] = tierDefinition(null, []);
+      continue;
+    }
+
+    let pricing = {};
+    try {
+      pricing = await getPricing(ids);
+    } catch {
+      pricing = {};
+    }
+
+    const scored = ids.map((id) => {
+      if (local.has(id)) return { id, cost: 0, priced: true };
+      const entry = pricing[id];
+      if (entry && Number.isFinite(Number(entry.input)) && Number.isFinite(Number(entry.output))) {
+        return { id, cost: Number(entry.input) + Number(entry.output), priced: true };
+      }
+      return { id, cost: Number.POSITIVE_INFINITY, priced: false };
+    });
+
+    const priced = scored.filter((s) => s.priced);
+    if (priced.length === 0) {
+      // No candidate had a reachable price. Fall back to a deterministic static
+      // ordering — a :free slug first, else the first non-frontier candidate —
+      // and say so rather than silently ranking on missing data.
+      pricingDegraded = true;
+      const free = ids.find((id) => isFreeModel(id));
+      const primary = free ?? ids[0];
+      models[tier] = tierDefinition(primary, ids.filter((id) => id !== primary).slice(0, 2));
+      continue;
+    }
+
+    scored.sort((a, b) => a.cost - b.cost);
+    const primary = scored[0].id;
+    const fallback = scored.slice(1).filter((s) => Number.isFinite(s.cost)).map((s) => s.id).slice(0, 2);
+    models[tier] = tierDefinition(primary, fallback);
+  }
+
+  if (pricingDegraded) {
+    warnings.push('Live pricing was unreachable for at least one tier; used static ordering (a :free slug, else the first eligible candidate).');
+  }
+  return { models, warnings };
+}
+
+/**
+ * Compute the free tier assignments: :free OpenRouter slugs only. A tier with no
+ * available free model is left null and reported, never silently substituted.
+ */
+export async function computeFreeTiers({ env = process.env, apiKey = null, poll = pollFreeModels } = {}) {
+  const warnings = [];
+  const models = {};
+  const key = apiKey || env.OPENROUTER_API_KEY || env.OPEN_ROUTER_API_KEY || null;
+  const freeModels = key ? await poll(key) : [];
+
+  for (const tier of POLICY_TIERS) {
+    const id = selectForTier(freeModels, tier, []);
+    if (id && isFreeModel(id)) {
+      models[tier] = tierDefinition(id, []);
+    } else {
+      models[tier] = tierDefinition(null, []);
+      warnings.push(`No free model available for the ${tier} tier; left unset (run \`construct models free\` to inspect the live catalog).`);
+    }
+  }
+  return { models, warnings };
+}
+
+// Best-available (flagship) per tier from configured providers, ranked by a fixed
+// capability order. This is the deliberately-expensive preset, so frontier ids are
+// not excluded here.
+
+const FRONTIER_PROVIDER_ORDER = [
+  'anthropic',
+  'openai',
+  'openrouter-anthropic',
+  'openrouter-openai',
+  'github-copilot',
+  'openrouter-google',
+  'openrouter-deepseek',
+  'openrouter-llama',
+  'openrouter-qwen',
+  'openrouter',
+];
+
+export function computeFrontierTiers({ env = process.env } = {}) {
+  const providers = configuredProviders(env);
+  const ranked = [...providers].sort((a, b) => {
+    const ia = FRONTIER_PROVIDER_ORDER.indexOf(a.id);
+    const ib = FRONTIER_PROVIDER_ORDER.indexOf(b.id);
+    return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);
+  });
+  const models = {};
+  for (const tier of POLICY_TIERS) {
+    const provider = ranked.find((p) => p.tiers?.[tier]);
+    const primary = provider?.tiers?.[tier] ?? null;
+    const fallback = ranked.filter((p) => p !== provider).map((p) => p.tiers?.[tier]).filter(Boolean);
+    models[tier] = tierDefinition(primary, fallback.slice(0, 2));
+  }
+  return { models, warnings: [] };
+}
+
+export function computeLocalTiers({ env = process.env } = {}) {
+  const providers = configuredProviders(env).filter((p) => p.local === true);
+  const models = {};
+  for (const tier of POLICY_TIERS) {
+    const provider = providers.find((p) => p.tiers?.[tier]);
+    const primary = provider?.tiers?.[tier] ?? null;
+    const fallback = providers.filter((p) => p !== provider).map((p) => p.tiers?.[tier]).filter(Boolean);
+    models[tier] = tierDefinition(primary, fallback.slice(0, 2));
+  }
+  return { models, warnings: [] };
+}
+
+/**
+ * Compute a preset's per-tier assignments. Refuses (ok:false) with a clear
+ * message when no provider credential can back the preset, so a preset never
+ * silently writes an unbacked frontier default.
+ */
+export async function computePolicyPreset(preset, { env = process.env, apiKey = null, getPricing, poll } = {}) {
+  if (!POLICY_PRESETS.includes(preset)) {
+    return { ok: false, refusal: `Unknown preset '${preset}'. Choose one of: ${POLICY_PRESETS.join(', ')}.` };
+  }
+
+  const providers = configuredProviders(env);
+  const localProviders = providers.filter((p) => p.local === true);
+  const hasOpenRouter = Boolean(env.OPENROUTER_API_KEY || env.OPEN_ROUTER_API_KEY);
+
+  if (preset === 'free' && !hasOpenRouter) {
+    return { ok: false, refusal: 'The `free` preset needs an OpenRouter credential (OPENROUTER_API_KEY). Set one, then rerun.' };
+  }
+  if (preset === 'local' && localProviders.length === 0) {
+    return { ok: false, refusal: 'The `local` preset needs a local provider (Ollama or a local OpenAI-compatible server). Start one, then rerun.' };
+  }
+  if ((preset === 'budget' || preset === 'frontier') && providers.length === 0) {
+    return { ok: false, refusal: `The \`${preset}\` preset needs at least one configured provider credential. Set an API key (e.g. OPENROUTER_API_KEY / ANTHROPIC_API_KEY), then rerun.` };
+  }
+
+  let result;
+  if (preset === 'budget') result = await computeBudgetTiers({ env, ...(getPricing ? { getPricing } : {}) });
+  else if (preset === 'free') result = await computeFreeTiers({ env, apiKey, ...(poll ? { poll } : {}) });
+  else if (preset === 'frontier') result = computeFrontierTiers({ env });
+  else result = computeLocalTiers({ env });
+
+  const anyResolved = POLICY_TIERS.some((tier) => result.models[tier]?.primary);
+  if (!anyResolved) {
+    return { ok: false, refusal: `No model could be computed for the \`${preset}\` preset with the current credentials.`, warnings: result.warnings };
+  }
+
+  return { ok: true, preset, models: result.models, warnings: result.warnings ?? [] };
+}
+
+/**
+ * Persist computed tier assignments to the models.json registry — the single
+ * edit surface. Writes only `models`; env pins keep overriding at resolution.
+ */
+export function writeModelRegistry(registryPath, models, { preset = null } = {}) {
+  const payload = {
+    _comment: `Written by \`construct models policy set${preset ? ` ${preset}` : ''}\` (construct-760c.7). Tier defaults below fill only tiers no CX_MODEL_<TIER> env pin sets; env pins always win. Edit via \`construct models policy set <preset>\` or \`construct models set\`.`,
+    models: {},
+  };
+  for (const tier of POLICY_TIERS) {
+    const def = models[tier];
+    if (def?.primary) payload.models[tier] = { primary: def.primary, fallback: def.fallback ?? [] };
+  }
+  fs.mkdirSync(path.dirname(registryPath), { recursive: true });
+  fs.writeFileSync(registryPath, `${JSON.stringify(payload, null, 2)}\n`);
+  return payload;
+}
+
+/**
+ * Effective-policy view: per-tier resolved model and the winning source, plus the
+ * work-category → tier map. Reads through resolveModelTiers so an env pin is
+ * attributed as the winning source over a registry default.
+ */
+export function readPolicyView({ env = process.env, registryPath = null } = {}) {
+  const resolvedRegistryPath = registryPath ?? defaultModelRegistryPath(env);
+  const resolution = resolveModelTiers({ env, registryPath: resolvedRegistryPath });
+  const tiers = POLICY_TIERS.map((tier) => ({
+    tier,
+    model: resolution.models[tier],
+    source: resolution.sources[tier],
+    envPin: env[`CX_MODEL_${tier.toUpperCase()}`] || env[`CONSTRUCT_MODEL_${tier.toUpperCase()}`] || null,
+  }));
+  return {
+    registryPath: resolvedRegistryPath,
+    tiers,
+    workCategoryMap: { ...MODEL_TIER_BY_WORK_CATEGORY },
+    configured: resolution.configured,
+    complete: resolution.complete,
+  };
+}
+
+/**
+ * Per-specialist resolution trace: the specialist's declared modelTier/model, the
+ * tier it maps to, and the winning rule for that tier. Mirrors what
+ * `construct models resolve --json --tier <tier>` reports for the same tier.
+ */
+export function explainRole(roleId, { env = process.env, registryPath = null, rootDir = null } = {}) {
+  const specialist = getSpecialist(roleId, rootDir ? { rootDir } : {});
+  if (!specialist) {
+    return { ok: false, error: `Unknown specialist '${roleId}'.` };
+  }
+
+  const declaredModel = specialist.model || null;
+  const declaredTier = specialist.modelTier || null;
+  const tier = declaredTier || 'standard';
+
+  const resolvedRegistryPath = registryPath ?? defaultModelRegistryPath(env);
+  const resolution = resolveModelTiers({ env, registryPath: resolvedRegistryPath });
+
+  const resolvedModel = declaredModel || resolution.models[tier];
+  const source = declaredModel ? 'specialist model pin' : resolution.sources[tier];
+
+  return {
+    ok: true,
+    role: specialist.name ? `cx-${specialist.name}` : roleId,
+    declaredModel,
+    declaredTier,
+    tier,
+    resolvedModel,
+    source,
+    registryPath: resolvedRegistryPath,
+  };
+}

package/lib/model-router.mjs

@@ -26,6 +26,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "child_process";
 import { hasAnySecret } from "./providers/secret-resolver.mjs";
+import { MODEL_TIERS } from "./model-tiers.mjs";
 import { isOllamaModelInstalled, toOllamaNativeModelId } from "./ollama/installed-models.mjs";
 import { readRawFromOpenCodeProvider } from "./providers/credential-sources.mjs";
 import { findOpenCodeConfigPath } from "./opencode-config.mjs";
@@ -535,9 +536,9 @@ export function getPickerModelAllowlist({
     if (!providerFamilyEnabled(family.id, vis)) continue;
 
     const tiers = family.resolve({});
-    const pins = uniqueStrings(['reasoning', 'standard', 'fast'].map((tier) => tiers[tier]));
+    const pins = uniqueStrings(MODEL_TIERS.map((tier) => tiers[tier]));
     const shipped = uniqueStrings(
-      ['reasoning', 'standard', 'fast'].flatMap((tier) => family.options?.[tier] || []),
+      MODEL_TIERS.flatMap((tier) => family.options?.[tier] || []),
     );
 
     if (vis.mode === 'explicit') {
@@ -675,7 +676,7 @@ export function listAvailableModels({ env = process.env, cwd = process.cwd(), ac
   const models = [];
   const seen = new Set();
   for (const provider of providers) {
-    for (const tier of ['reasoning', 'standard', 'fast']) {
+    for (const tier of MODEL_TIERS) {
       for (const id of provider.options?.[tier] || []) {
         if (seen.has(id)) continue;
         seen.add(id);
@@ -1135,7 +1136,7 @@ function resolveTierAssignments(envValues = {}, registryModels = {}) {
   const defaults = getRegistryDefaults(registryModels);
   const tiers = {};
 
-  for (const tier of ["reasoning", "standard", "fast"]) {
+  for (const tier of MODEL_TIERS) {
     if (explicitSources[tier]) {
       tiers[tier] = { model: normalizedEnv[tier] ?? defaults[tier], source: explicitSources[tier] };
     } else if (normalizedEnv[tier]) {
@@ -1224,7 +1225,7 @@ export function applyFreeSameFamilyPreferenceToTierSet(tierSet, selectedModel) {
 
   const sameFamily = family.resolve({ reasoning: null, standard: null, fast: null });
   const next = { ...tierSet };
-  for (const tier of ["reasoning", "standard", "fast"]) {
+  for (const tier of MODEL_TIERS) {
     if (tierSet[tier] === selectedModel) continue;
     const candidate = sameFamily[tier];
     if (candidate && isFreeModel(candidate)) next[tier] = candidate;
@@ -1341,13 +1342,13 @@ export function resolveModelTiers(options = {}) {
   const tiers = resolveTierAssignments(normalizeEnvAssignments(env), registryModels);
   const models = {};
   const sources = {};
-  for (const tier of ['reasoning', 'standard', 'fast']) {
+  for (const tier of MODEL_TIERS) {
     models[tier] = tiers[tier].model;
     sources[tier] = tiers[tier].source;
   }
   const configured = Object.values(models).filter(Boolean).length;
   const errors = strict && configured < 3
-    ? [`Missing configuration for tiers: ${['reasoning', 'standard', 'fast'].filter((t) => !models[t]).join(', ')}`]
+    ? [`Missing configuration for tiers: ${MODEL_TIERS.filter((t) => !models[t]).join(', ')}`]
     : null;
 
   return {
@@ -1386,7 +1387,7 @@ export function validateModelTiers(options = {}) {
 export function formatModelStatus(options = {}) {
   const resolved = resolveModelTiers(options);
   let output = 'Model Configuration:\n\n';
-  for (const tier of ['reasoning', 'standard', 'fast']) {
+  for (const tier of MODEL_TIERS) {
     const model = resolved.models[tier];
     const source = resolved.sources[tier];
     const icon = source === 'not configured' ? '!' : 'ok';
@@ -1407,7 +1408,7 @@ export function readCurrentModels(envPath, registryModels = {}) {
   };
   const tiers = resolveTierAssignments(mergedAssignments, registryModels);
   const result = { sources: {} };
-  for (const tier of ["reasoning", "standard", "fast"]) {
+  for (const tier of MODEL_TIERS) {
     result[tier] = tiers[tier].model;
     result.sources[tier] = tiers[tier].source;
   }

package/lib/model-tiers.mjs

@@ -0,0 +1,27 @@
+/**
+ * lib/model-tiers.mjs — the canonical model-tier vocabulary.
+ *
+ * `reasoning`, `standard`, and `fast` are the three work tiers every
+ * model-resolution surface keys off: the router's family tables, the registry
+ * validator's accept-list, cost selection, policy presets, the CLI, and the
+ * MCP tool schemas. They lived as a `['reasoning', 'standard', 'fast']` literal
+ * re-typed in ~30 places, so adding or renaming a tier meant the accept-lists
+ * could silently diverge from what the router actually resolves (construct-v1wk).
+ *
+ * Single source of truth for that vocabulary — deliberately zero-dependency so
+ * the lowest-level consumers (the registry validator, setup) can import it
+ * without pulling the router's provider probes or model-policy's
+ * pricing/registry imports. A JSON-schema `enum` or any caller that needs a
+ * fresh mutable array spreads it: `[...MODEL_TIERS]`.
+ *
+ * The intentionally self-contained `lib/embedded-contract/` bundle keeps its
+ * own copy on purpose — it must not import `lib/` internals.
+ */
+
+export const MODEL_TIERS = Object.freeze(['reasoning', 'standard', 'fast']);
+
+export const MODEL_TIER_SET = Object.freeze(new Set(MODEL_TIERS));
+
+export function isModelTier(value) {
+  return MODEL_TIER_SET.has(value);
+}