catherd-cli 1.1.1 → 1.2.0

package/src/domain/catalog.ts

@@ -3,10 +3,31 @@ import { type Rung, parseRung } from "./ids.ts";
 import { DIFFICULTIES, type Difficulty, KINDS, type Kind } from "./lane.ts";
 import type { Role } from "./roles.ts";
 
-/** Spec §5.2: the scored dimensions, each on one named benchmark. */
-export const DIMS = ["repo_code", "terminal", "honesty"] as const;
+/**
+ * Spec §5.2 and 1.2 §5.1: the scored dimensions, each in its anchor's unit. `agentic`, `steer` and `frontend`
+ * (1.2) carry no shipped bar yet.
+ */
+export const DIMS = ["repo_code", "terminal", "honesty", "agentic", "steer", "frontend"] as const;
 export type Dim = (typeof DIMS)[number];
 
+/**
+ * Spec 1.2 §4.3: how a value was obtained, best first. The 1.0 levels (`verified`, `secondary`,
+ * `inferred`) keep their names, so an older override file stays valid.
+ */
+export const CONFIDENCE = [
+  "verified",
+  "measured",
+  "calibrated",
+  "adjacent",
+  "secondary",
+  "inferred",
+] as const;
+export type Confidence = (typeof CONFIDENCE)[number];
+export const RANK = Object.fromEntries(CONFIDENCE.map((c, i) => [c, i])) as Record<Confidence, number>;
+/** Spec 1.2 §4.3: a value older than this many days counts one level lower. */
+export const STALE_DAYS = 90;
+const DAY_MS = 86_400_000;
+
 /**
  * Spec §7.1 `billing` keys: a rung's backend, except that opencode's Go models (`opencode-go/…`) are billed
  * apart from its Zen models (`opencode/…`).
@@ -52,6 +73,10 @@ const FamilySchema = z.looseObject({
   meteredOnPlan: z.boolean().default(false),
   on: z.partialRecord(z.enum(MODEL_KEYS), BackendModelSchema),
   notes: z.record(z.string(), z.string()).default({}),
+  /** the day the vendor released it (models.dev), a stand-in feature (spec 1.2 §6.3) */
+  releaseDate: z.iso.date().optional(),
+  /** a sync's speed facts (spec 1.2 §4.1), `<source>.<field>` → value; they never carry a bar */
+  speed: z.record(z.string(), z.number()).optional(),
 });
 export type Family = z.infer<typeof FamilySchema>;
 
@@ -72,7 +97,18 @@ export type ModelsFile = z.infer<typeof ModelsFileSchema>;
 /** A canonical rung: `<canonical model id>#<effort>`, the key scores and treat-likes use. */
 export const CanonicalRung = z.string().regex(/^[^:#\s]+#[^#\s]+$/, "a canonical rung is model#effort");
 
-const ScoreSchema = z.object({
+/** Spec 1.2 §4.2: `anchor = a·x + b`, fitted on `n` rungs both sources cover, with its R². */
+export const FitSchema = z.object({
+  source: z.string(),
+  field: z.string(),
+  a: z.number(),
+  b: z.number(),
+  r2: z.number(),
+  n: z.number().int(),
+});
+export type Fit = z.infer<typeof FitSchema>;
+
+export const ScoreSchema = z.object({
   rung: CanonicalRung,
   dim: z.enum(DIMS),
   value: z.number(),
@@ -80,8 +116,14 @@ const ScoreSchema = z.object({
   version: z.string(),
   url: z.url(),
   date: z.iso.date(),
-  confidence: z.enum(["verified", "secondary", "inferred"]),
+  confidence: z.enum(CONFIDENCE),
   note: z.string().optional(),
+  /** spec 1.2 §4.3: the source a synced value came from (absent: the shipped file or the user's override) */
+  source: z.string().optional(),
+  /** a calibrated value: the fit that mapped it onto the anchor */
+  fit: FitSchema.optional(),
+  /** the source named no effort, so the family's default effort was assumed (spec 1.2 §3.4) */
+  effortAssumed: z.boolean().optional(),
 });
 export type Score = z.infer<typeof ScoreSchema>;
 
@@ -89,7 +131,13 @@ const BarSchema = z.partialRecord(z.enum(DIMS), z.number());
 type Bars = Record<Kind, Record<Difficulty, Partial<Record<Dim, number>>>>;
 const BarsSchema = z.record(z.enum(KINDS), z.record(z.enum(DIFFICULTIES), BarSchema));
 
-/** `barsWhy` (the reasoning behind the bars) stays in the file as documentation; nothing reads it. */
+/** Spec 1.2 §5.2: per dimension and difficulty, where the default threshold came from. */
+const BarsWhySchema = z.partialRecord(z.enum(DIMS), z.partialRecord(z.enum(DIFFICULTIES), z.string()));
+
+/**
+ * `catalog/scores.json`: the hand-typed and keyless values (spec 1.2 §7), the shipped treat-likes, and the
+ * default bars with the `barsWhy` line of each threshold (spec 1.2 §5.2).
+ */
 export const ScoresFileSchema = z.looseObject({
   schema: z.literal(1),
   version: z.string(),
@@ -97,18 +145,35 @@ export const ScoresFileSchema = z.looseObject({
   scores: z.array(ScoreSchema),
   treatLike: z.record(CanonicalRung, z.object({ like: CanonicalRung, note: z.string() })),
   bars: BarsSchema,
+  barsWhy: BarsWhySchema.default({}),
 });
 export type ScoresFile = z.infer<typeof ScoresFileSchema>;
 
-/** `<config>/catalog.override.json` (spec §3.5): the user's treat-likes, scores and bars. */
+/** An override's bar: per dimension a threshold, or `null` to remove the default's (spec 1.2 §5.2). */
+const OverrideBarSchema = z.partialRecord(z.enum(DIMS), z.number().nullable());
+
+/**
+ * `<config>/catalog.override.json` (spec §3.5): the user's treat-likes, scores and bars. Its bars override
+ * the default bars per dimension (spec 1.2 §5.2): a number sets that threshold, `null` removes it, and a
+ * dimension it does not name keeps the default's.
+ */
 export const OverrideSchema = z.looseObject({
   schema: z.literal(1).default(1),
   treatLike: z.record(CanonicalRung, CanonicalRung).default({}),
   scores: z.array(ScoreSchema).default([]),
-  bars: z.partialRecord(z.enum(KINDS), z.partialRecord(z.enum(DIFFICULTIES), BarSchema)).default({}),
+  bars: z.partialRecord(z.enum(KINDS), z.partialRecord(z.enum(DIFFICULTIES), OverrideBarSchema)).default({}),
 });
 export type Override = z.infer<typeof OverrideSchema>;
 
+/** Spec 1.2 §6.1: the rung whose value a rung without one uses on a dimension, as `inferred`. */
+export interface InferredStandIn {
+  like: string;
+  /** spec 1.2 §6.3's distance between the two */
+  distance: number;
+  /** the features that distance rests on */
+  features: string[];
+}
+
 interface Listed {
   id: string;
   efforts: string[];
@@ -124,29 +189,119 @@ export interface Catalog {
   scores: Record<string, Partial<Record<Dim, Score>>>;
   treatLike: Record<string, { like: string; source: "shipped" | "user" }>;
   bars: Bars;
+  /** where each default threshold came from (spec 1.2 §5.2), by dimension and difficulty */
+  barsWhy: ScoresFile["barsWhy"];
   /** per backend id, the last `listModels()`; absent when never listed */
   listed: Record<string, { fetchedAt: string; models: Listed[] }>;
   /** `<canonical rung>|<kind or *>` → median seconds, only with ≥ 5 samples (spec §5.2) */
   secs: Record<string, number>;
+  /** canonical rung → the Artificial Analysis stand-in features a sync read for it (spec 1.2 §6.3) */
+  features: Record<string, Record<string, number>>;
+  /**
+   * canonical rung → per dimension it has no value for (of its own or through a treat-like), the stand-in
+   * whose value it uses as `inferred` (spec 1.2 §6.1); filled by the stand-in ranking (services/standins.ts)
+   */
+  inferred: Record<string, Partial<Record<Dim, InferredStandIn>>>;
+}
+
+/**
+ * Spec 1.2 §3.5: what a sync learned about a family. `price`, `capabilities` and the opencode backends'
+ * `efforts` and `context` come from models.dev; `speed` holds facts that never carry a bar (spec 1.2 §4.1),
+ * as `<source>.<field>` → value.
+ */
+export const FamilyFactsSchema = z.object({
+  price: z.object({ input: z.number(), cached: z.number(), output: z.number() }).optional(),
+  capabilities: z.object({ toolUse: z.boolean(), imageIn: z.boolean(), reasoning: z.boolean() }).optional(),
+  on: z
+    .partialRecord(
+      z.enum(MODEL_KEYS),
+      z.object({ efforts: z.array(z.string()).optional(), context: z.number().int().positive().optional() }),
+    )
+    .default({}),
+  releaseDate: z.string().optional(),
+  speed: z.record(z.string(), z.number()).default({}),
+});
+export type FamilyFacts = z.infer<typeof FamilyFactsSchema>;
+
+/**
+ * Spec 1.2 §3.5: the families with a sync's facts laid over them. The shipped file stays the floor: a fact
+ * the sync lacks keeps the shipped one, and a backend keeps every effort it ships with.
+ */
+export function applyFacts(families: Family[], facts: Record<string, FamilyFacts>): Family[] {
+  return families.map((f) => {
+    const x = facts[f.id];
+    if (!x) return f;
+    const on = { ...f.on };
+    for (const key of MODEL_KEYS) {
+      const cur = on[key];
+      const got = x.on[key];
+      if (!cur || !got) continue;
+      on[key] = {
+        ...cur,
+        efforts: [...cur.efforts, ...(got.efforts ?? []).filter((e) => !cur.efforts.includes(e))],
+        context: got.context ?? cur.context,
+      };
+    }
+    // a sync may add a capability, never remove one the shipped file gives (the floor)
+    const got = x.capabilities;
+    const capabilities = got
+      ? {
+          toolUse: f.capabilities.toolUse || got.toolUse,
+          imageIn: f.capabilities.imageIn || got.imageIn,
+          reasoning: f.capabilities.reasoning || got.reasoning,
+        }
+      : f.capabilities;
+    return {
+      ...f,
+      price: x.price ?? f.price,
+      capabilities,
+      on,
+      ...(x.releaseDate || f.releaseDate ? { releaseDate: x.releaseDate ?? f.releaseDate } : {}),
+      ...(Object.keys(x.speed).length ? { speed: x.speed } : {}),
+    };
+  });
 }
 
-const RANK: Record<Score["confidence"], number> = { verified: 0, secondary: 1, inferred: 2 };
+/** Spec 1.2 §4.3: the level a value counts at: its own, one lower once it is older than STALE_DAYS. */
+export function effectiveRank(s: Score, now: number): number {
+  const stale = now - Date.parse(s.date) > STALE_DAYS * DAY_MS;
+  return Math.min(RANK[s.confidence] + (stale ? 1 : 0), CONFIDENCE.length - 1);
+}
 
+/** Spec 1.2 §4.3: `a` beats `b` at a better level, or at the same level with a newer date. */
+export function outranks(a: Score, b: Score, now: number): boolean {
+  const ra = effectiveRank(a, now);
+  const rb = effectiveRank(b, now);
+  return ra < rb || (ra === rb && a.date > b.date);
+}
+
+/**
+ * The catalog routing reads: the shipped files, the synced values (spec 1.2 §3), each backend's listing and
+ * the user's override, which always wins. Between shipped and synced values the better level wins, then the
+ * newer date (spec 1.2 §4.3); `now` dates the 90-day drop.
+ */
 export function buildCatalog(o: {
   models: ModelsFile;
   scores: ScoresFile;
+  synced?: Score[];
+  facts?: Record<string, FamilyFacts>;
   override?: Override;
   listed?: Catalog["listed"];
   secs?: Catalog["secs"];
+  features?: Catalog["features"];
+  now?: number;
 }): Catalog {
+  const now = o.now ?? Date.now();
   const scores: Catalog["scores"] = {};
   const put = (s: Score, force: boolean) => {
     const cur = (scores[s.rung] ??= {});
     const had = cur[s.dim];
-    if (force || !had || RANK[s.confidence] < RANK[had.confidence]) cur[s.dim] = s;
+    if (force || !had || outranks(s, had, now)) cur[s.dim] = s;
   };
   for (const s of o.scores.scores) put(s, false);
-  for (const s of o.override?.scores ?? []) put(s, true);
+  for (const s of o.synced ?? []) put(s, false);
+  // the user's values say so whatever source they were copied with, for route's provenance (spec 1.2 §5.3)
+  for (const s of o.override?.scores ?? []) put({ ...s, source: "override" }, true);
   const treatLike: Catalog["treatLike"] = {};
   for (const [rung, t] of Object.entries(o.scores.treatLike))
     treatLike[rung] = { like: t.like, source: "shipped" };
@@ -154,18 +309,21 @@ export function buildCatalog(o: {
     treatLike[rung] = { like, source: "user" };
   const bars = structuredClone(o.scores.bars) as Bars;
   for (const kind of KINDS)
-    for (const d of DIFFICULTIES) {
-      const bar = o.override?.bars[kind]?.[d];
-      if (bar) bars[kind][d] = bar;
-    }
+    for (const d of DIFFICULTIES)
+      for (const [dim, min] of Object.entries(o.override?.bars[kind]?.[d] ?? {}) as [Dim, number | null][])
+        if (min === null) delete bars[kind][d][dim];
+        else bars[kind][d][dim] = min;
   return {
-    families: o.models.families,
+    families: o.facts ? applyFacts(o.models.families, o.facts) : o.models.families,
     backends: o.models.backends,
     scores,
     treatLike,
     bars,
+    barsWhy: o.scores.barsWhy,
     listed: o.listed ?? {},
     secs: o.secs ?? {},
+    features: o.features ?? {},
+    inferred: {},
   };
 }
 
@@ -211,18 +369,47 @@ export function rungInfo(c: Catalog, rung: string): RungInfo {
   };
 }
 
-/** The rung's scores: its own, else those of the rung it is treated like. null when unscored. */
+/**
+ * The rung's scores: per dimension its own value, else that of the rung it is treated like (a sync may score
+ * a rung on some dimensions only), else its inferred stand-in's (spec 1.2 §6.1). `via` names the treat-like
+ * when it lends any value and `borrowed` the dimensions it lends; `inferred` the dimensions an inferred
+ * stand-in fills and `standIns` whose values they are. null when it has no value at all.
+ */
 export function scoresOf(
   c: Catalog,
   canonical: string,
-): { values: Partial<Record<Dim, number>>; records: Partial<Record<Dim, Score>>; via: string | null } | null {
-  const own = c.scores[canonical];
-  const via = own ? null : (c.treatLike[canonical]?.like ?? null);
-  const records = own ?? (via ? c.scores[via] : undefined);
-  if (!records || Object.keys(records).length === 0) return null;
+): {
+  values: Partial<Record<Dim, number>>;
+  records: Partial<Record<Dim, Score>>;
+  via: string | null;
+  borrowed: Dim[];
+  inferred: Dim[];
+  standIns: Partial<Record<Dim, string>>;
+} | null {
+  const own = c.scores[canonical] ?? {};
+  const like = c.treatLike[canonical]?.like ?? null;
+  const lent = like ? (c.scores[like] ?? {}) : {};
+  const guessed = c.inferred[canonical] ?? {};
   const values: Partial<Record<Dim, number>> = {};
-  for (const d of DIMS) if (records[d]) values[d] = records[d].value;
-  return { values, records, via };
+  const records: Partial<Record<Dim, Score>> = {};
+  const borrowed: Dim[] = [];
+  const inferred: Dim[] = [];
+  const standIns: Partial<Record<Dim, string>> = {};
+  for (const d of DIMS) {
+    const stand = guessed[d];
+    const r = own[d] ?? lent[d] ?? (stand ? c.scores[stand.like]?.[d] : undefined);
+    if (!r) continue;
+    records[d] = r;
+    values[d] = r.value;
+    if (own[d]) continue;
+    if (lent[d]) borrowed.push(d);
+    else if (stand) {
+      inferred.push(d);
+      standIns[d] = stand.like;
+    }
+  }
+  if (Object.keys(records).length === 0) return null;
+  return { values, records, via: borrowed.length ? like : null, borrowed, inferred, standIns };
 }
 
 /** Spec §4 roles: what a rung must offer to be placed on a role. */

package/src/domain/failover.ts

@@ -2,6 +2,7 @@ import { billingKeyOf, type Catalog, DIMS, type Dim, rungInfo, scoresOf } from "
 import { type BillingMode, compareCost, type Cost, costOf, DEFAULT_BILLING } from "./cost.ts";
 import { type Rung, tryParseRung } from "./ids.ts";
 import { DIFFICULTIES, KINDS } from "./lane.ts";
+import { EFFORT_ORDER } from "./sources.ts";
 
 /**
  * Spec §7.1 and §4.5: a stand-in on the same quota would be out of quota too. The billing key names the
@@ -72,7 +73,9 @@ const costFor = (c: Catalog, billing: Partial<Record<string, BillingMode>>, rung
  * Spec 1.1 §11: the rungs of `pool` that can stand in for `rung`, best first. A stand-in is on another
  * quota, scored, paid from a plan or subscription under `billing` (a metered one spends money nobody chose
  * to), startable by `dispatch` (not a native `claude:` subagent), and no downgrade on the rung's bar dims.
- * Claude-billed stand-ins rank last, then the cheapest first.
+ * Claude-billed stand-ins rank last, then the effort nearest the rung's own (a model's efforts carry one
+ * another's values as `adjacent`, spec 1.2 §4.3, so the cheapest would otherwise be its lowest effort; plan 14
+ * Ruling 4), then the cheapest.
  */
 export function rankStandIns(
   c: Catalog,
@@ -88,14 +91,24 @@ export function rankStandIns(
     if (costFor(c, billing, x).tier === 1) return false;
     return downgradeDims(c, rung, x).length === 0;
   });
+  const gap = (x: string) => effortGap(from.effort, tryParseRung(x)?.effort ?? "");
   return fits.sort(
     (a, b) =>
       Number(claudeBilled(a)) - Number(claudeBilled(b)) ||
+      gap(a) - gap(b) ||
       compareCost(costFor(c, billing, a), costFor(c, billing, b)) ||
       a.localeCompare(b),
   );
 }
 
+/** How many effort steps apart two efforts are; an effort that is no effort word (`default`) is far from all. */
+function effortGap(a: string, b: string): number {
+  const i = (EFFORT_ORDER as readonly string[]).indexOf(a);
+  const j = (EFFORT_ORDER as readonly string[]).indexOf(b);
+  if (a === b) return 0;
+  return i < 0 || j < 0 ? EFFORT_ORDER.length : Math.abs(i - j);
+}
+
 /** How a family's `on` key or a model id's prefix maps to the backend that runs it. */
 const BACKEND_OF_KEY: Record<string, string> = { "opencode-go": "opencode" };
 

package/src/domain/profile-rules.ts

@@ -1,5 +1,6 @@
 import {
   type Catalog,
+  type Dim,
   capableFor,
   effortOffered,
   ROLE_NEEDS,
@@ -37,6 +38,71 @@ export interface Validation {
 
 const TREAT_LIKE_FIX = (rung: string) =>
   `map it with: catherd catalog treat-like ${rung} <a scored rung>; catalog_query lists them`;
+const SUGGEST_FIX = (rung: string) =>
+  `confirm or replace it: catherd catalog treat-like --suggest ${rung}, then catherd catalog treat-like ${rung} <a rung>`;
+
+/** Spec 1.2 §6.2: two findings are the same one when they name the same path with the same message. */
+const sameIssue = (a: Issue, b: Issue): boolean => a.path === b.path && a.message === b.message;
+
+/**
+ * Spec 1.2 §6.2: a save that leaves errors goes through when it removes at least one of the errors the
+ * profile had and adds none. `before` is the stored profile's validation, null when it does not exist yet.
+ */
+export function repairs(before: Validation | null, after: Validation): boolean {
+  if (after.errors.length === 0) return true;
+  if (!before) return false;
+  const added = after.errors.some((e) => !before.errors.some((b) => sameIssue(b, e)));
+  const removed = before.errors.some((b) => !after.errors.some((e) => sameIssue(b, e)));
+  return removed && !added;
+}
+
+/** Spec 1.2 §6.1 "stand-in to confirm": a rung whose values on some bar dimensions are an inferred stand-in's. */
+export interface StandInToConfirm {
+  canonical: string;
+  /** the profile's rungs that run it, and where the first one is */
+  rungs: string[];
+  path: string;
+  dims: { dim: Dim; like: string }[];
+}
+
+/**
+ * Spec 1.2 §6.1: the profile's rungs that lean on an inferred stand-in, one entry per canonical rung. Only
+ * where bars choose: rungs of a role with more than one usable rung, and failover stand-ins; a role with one
+ * rung runs it whatever the bars say (plan 14 Ruling 13).
+ */
+export function standInsToConfirm(p: Profile, c: Catalog, backends: readonly string[]): StandInToConfirm[] {
+  const seen = new Map<string, StandInToConfirm>();
+  const add = (rung: string, path: string) => {
+    const r = tryParseRung(rung);
+    if (!r || !backends.includes(r.backend)) return;
+    const info = rungInfo(c, rung);
+    const s = scoresOf(c, info.canonical);
+    if (!s || s.inferred.length === 0) return;
+    const had = seen.get(info.canonical);
+    if (had) {
+      if (!had.rungs.includes(rung)) had.rungs.push(rung);
+      return;
+    }
+    const dims = s.inferred.map((dim) => ({ dim, like: s.standIns[dim] as string }));
+    seen.set(info.canonical, { canonical: info.canonical, rungs: [rung], path, dims });
+  };
+  for (const role of ROLES) {
+    const rc = p.roles[role];
+    if (!rc.enabled || candidates(c, routingProfileOf(p, role), role).length < 2) continue;
+    for (const rung of rc.rungs) add(rung, `roles.${role}.rungs`);
+  }
+  for (const [from, to] of Object.entries(p.failover)) add(to, `failover.${from}`);
+  return [...seen.values()];
+}
+
+/** One "stand-in to confirm" warning's words. */
+export function standInMessage(x: StandInToConfirm): string {
+  const words = (xs: string[]) =>
+    xs.length < 3 ? xs.join(" or ") : `${xs.slice(0, -1).join(", ")} or ${xs.at(-1)}`;
+  const lent = x.dims.map((d) => `${d.like}'s ${d.dim}`).join(", ");
+  const also = x.rungs.length > 1 ? ` (${x.rungs.join(", ")})` : "";
+  return `stand-in to confirm: ${x.canonical}${also} has no ${words(x.dims.map((d) => d.dim))} value of its own; routing uses ${lent} (inferred)`;
+}
 
 export const routingProfileOf = (p: Profile, role: Role): RoutingProfile => ({
   objective: p.objective,
@@ -44,22 +110,35 @@ export const routingProfileOf = (p: Profile, role: Role): RoutingProfile => ({
   role: p.roles[role],
 });
 
-/** Whether a rung's scores are catherd's guess: borrowed through a treat-like, or only `inferred` ones. */
-export function inferredScores(c: Catalog, info: RungInfo): { inferred: boolean; via: string | null } {
+/**
+ * Whether a rung's scores are catherd's guess: borrowed through a treat-like, filled by an inferred stand-in
+ * (spec 1.2 §6.1), or only `inferred` ones. `note` says what a treat-like lends: "scores borrowed from X"
+ * when the rung has no value of its own, else the dimensions it borrows (a rung a sync scored on some).
+ */
+export function inferredScores(
+  c: Catalog,
+  info: RungInfo,
+): { inferred: boolean; via: string | null; note: string | null } {
   const s = scoresOf(c, info.canonical);
-  if (!s) return { inferred: false, via: null };
+  if (!s) return { inferred: false, via: null, note: null };
   const records = Object.values(s.records);
-  return { inferred: s.via !== null || records.every((r) => r.confidence === "inferred"), via: s.via };
+  const guessed =
+    s.via !== null || s.inferred.length > 0 || records.every((r) => r.confidence === "inferred");
+  const all = s.borrowed.length + s.inferred.length === records.length;
+  const note = s.via ? `${all ? "scores" : s.borrowed.join(", ")} borrowed from ${s.via}` : null;
+  return { inferred: guessed, via: s.via, note };
 }
 
 /**
- * Spec §7.1. Errors: the worker disabled; an enabled role with no usable rung; an unscored rung without a
- * treat-like; a failover stand-in unscored or on the same quota; a rung whose backend catherd cannot run
- * (`backends` lists those it can, `claude` included). Everything else worth knowing is a warning: an access
- * mode other than the role's default, an effort or model the last listing does not offer, a stand-in
- * that never runs, and (spec 1.1 §11) a stand-in that downgrades its rung, one that spends Claude quota
- * while another plan could stand in, and a ladder that goes down. With the stored `doc` `p` came from, a value this catherd does not know is also a
- * warning, one that says how the value is read.
+ * Spec §7.1. Errors: the worker disabled; an enabled role with no usable rung; a failover stand-in on the
+ * same quota; a rung whose backend catherd cannot run (`backends` lists those it can, `claude` included).
+ * Everything else worth knowing is a warning: an access mode other than the role's default, an effort or
+ * model the last listing does not offer, a stand-in that never runs, (spec 1.1 §11) a stand-in that
+ * downgrades its rung, one that spends Claude quota while another plan could stand in, and a ladder that goes
+ * down, and (spec 1.2 §6.1) an unscored rung or stand-in, never an error: a rung that leans on an inferred
+ * stand-in is a "stand-in to confirm", and one with no value and no stand-in is skipped by routing. With the
+ * stored `doc` `p` came from, a value this catherd does not know is also a warning, one that says how the
+ * value is read.
  */
 export function validateProfile(
   p: Profile,
@@ -133,7 +212,11 @@ export function validateProfile(
           message: `${r.backend}'s last listing does not offer ${r.model}; routing skips it`,
         });
       if (!scoresOf(c, info.canonical))
-        errors.push({ path: `${at}.rungs`, message: `${rung} is unscored`, fix: TREAT_LIKE_FIX(rung) });
+        warnings.push({
+          path: `${at}.rungs`,
+          message: `${rung} is unscored and no rung is near enough to stand in for it: routing skips it`,
+          fix: TREAT_LIKE_FIX(rung),
+        });
     }
     rc.rungs.forEach((rung, i) => {
       const prev = rc.rungs[i - 1];
@@ -170,14 +253,15 @@ export function validateProfile(
             path: `${at}.rungs`,
             message: `${x.rung} clears no routing bar, so a lane starts on it only as the role's default rung and never climbs onto it`,
           });
+    // spec 1.2 §5.2: the logic and hard bars sit at the 60th and 75th percentiles, which a cost-minded ladder
+    // may never reach, and those lanes start at the default rung and climb; only a kind whose every bar the
+    // ladder misses routes blind (plan 14 Ruling 12)
     if (role === "worker" && usable.length > 1) {
-      const missed = KINDS.flatMap((k) =>
-        DIFFICULTIES.filter((d) => !usable.some((x) => clearsBar(c, x, k, d))).map((d) => `${k}/${d}`),
-      );
-      if (missed.length)
+      const blind = KINDS.filter((k) => !DIFFICULTIES.some((d) => usable.some((x) => clearsBar(c, x, k, d))));
+      if (blind.length)
         warnings.push({
           path: `${at}.rungs`,
-          message: `no worker rung clears the bar for ${missed.join(", ")}; those lanes start at the default rung`,
+          message: `no worker rung clears any bar for ${blind.join(", ")}; those lanes always start at the default rung`,
         });
     }
   }
@@ -205,7 +289,11 @@ export function validateProfile(
       continue;
     }
     if (!scoresOf(c, rungInfo(c, to).canonical))
-      errors.push({ path: at, message: `stand-in ${to} is unscored`, fix: TREAT_LIKE_FIX(to) });
+      warnings.push({
+        path: at,
+        message: `stand-in ${to} is unscored and no rung is near enough to stand in for it`,
+        fix: TREAT_LIKE_FIX(to),
+      });
     if (quotaOf(a) === quotaOf(b))
       errors.push({
         path: at,
@@ -235,5 +323,7 @@ export function validateProfile(
     if (!ladders.has(from))
       warnings.push({ path: at, message: `${from} is on no enabled role's ladder, so this never runs` });
   }
+  for (const x of standInsToConfirm(p, c, backends))
+    warnings.push({ path: x.path, message: standInMessage(x), fix: SUGGEST_FIX(x.rungs[0] as string) });
   return { errors, warnings };
 }