catherd-cli 1.1.1 → 1.2.1

package/catalog/sources.json

@@ -0,0 +1,87 @@
+{
+  "schema": 1,
+  "version": "2026-09-28",
+  "sources": [
+    {
+      "id": "models-dev",
+      "name": "models.dev",
+      "url": "https://models.dev/api.json",
+      "license": "MIT",
+      "attribution": "Model facts from models.dev (MIT License), https://models.dev",
+      "keyed": false
+    },
+    {
+      "id": "openrouter-models",
+      "name": "OpenRouter models",
+      "url": "https://openrouter.ai/api/v1/models",
+      "license": "public API",
+      "attribution": "Model listings from the OpenRouter API, https://openrouter.ai",
+      "keyed": false
+    },
+    {
+      "id": "openrouter-endpoints",
+      "name": "OpenRouter endpoints",
+      "url": "https://openrouter.ai/api/v1/models",
+      "license": "public API",
+      "attribution": "Endpoint latency and throughput from the OpenRouter API, https://openrouter.ai",
+      "keyed": false
+    },
+    {
+      "id": "litellm",
+      "name": "LiteLLM",
+      "url": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
+      "license": "MIT",
+      "attribution": "Prices from LiteLLM's model_prices_and_context_window.json (MIT License), https://github.com/BerriAI/litellm",
+      "keyed": false
+    },
+    {
+      "id": "arena",
+      "name": "Arena (LMArena)",
+      "url": "https://huggingface.co/datasets/lmarena-ai/leaderboard-dataset",
+      "license": "CC-BY-4.0",
+      "attribution": "Leaderboard data by LMArena, CC BY 4.0, https://huggingface.co/datasets/lmarena-ai/leaderboard-dataset",
+      "keyed": false
+    },
+    {
+      "id": "vectara",
+      "name": "Vectara hallucination leaderboard",
+      "url": "https://github.com/vectara/hallucination-leaderboard",
+      "license": "Apache-2.0",
+      "attribution": "Hallucination Leaderboard by Vectara (Apache License 2.0), https://github.com/vectara/hallucination-leaderboard",
+      "keyed": false
+    },
+    {
+      "id": "epoch",
+      "name": "Epoch AI benchmarks",
+      "url": "https://epoch.ai/data/benchmark_data.zip",
+      "license": "CC-BY-4.0; external tables keep their own license",
+      "attribution": "Epoch AI, 'Capabilities & benchmarking'. Published online at epoch.ai. Retrieved from 'https://epoch.ai/benchmarks' (CC BY 4.0)",
+      "keyed": false
+    },
+    {
+      "id": "artificial-analysis",
+      "name": "Artificial Analysis",
+      "url": "https://artificialanalysis.ai/api/v2/data/llms/models",
+      "license": "free key, internal use, attribution; read with the user's own key and never shipped",
+      "attribution": "Data from Artificial Analysis, https://artificialanalysis.ai",
+      "keyed": true
+    }
+  ],
+  "aliases": {
+    "claude-4-5-haiku": "claude-haiku-4-5",
+    "claude-haiku-4-5-20251001": "claude-haiku-4-5"
+  },
+  "defaultEffort": {
+    "gpt-6-astra": "medium",
+    "gpt-6-sol": "medium",
+    "gpt-6-luna": "medium",
+    "gpt-5.6-sol": "medium",
+    "gpt-5.6-terra": "medium",
+    "gpt-5.6-luna": "medium",
+    "claude-fable-5-1": "high",
+    "claude-opus-5-5": "high",
+    "claude-sonnet-5-5": "high",
+    "claude-sonnet-5": "high",
+    "claude-haiku-4-5": "default"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catherd-cli",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Herds coding agents: autopilot builds from your own Claude Code session.",
   "keywords": [
     "autopilot",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "catherd",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Herds coding agents: Claude plans and verifies, Codex, opencode or headless Claude Code workers write the code, and Jev picks the model and effort for each piece.",
   "author": {
     "name": "47vigen",

package/plugin/bin/catherd-mcp

@@ -1,7 +1,7 @@
 #!/bin/sh
 # catherd's MCP launcher (spec 1.1 §12): the plugin's .mcp.json runs it. The release stamps VERSION
 # (scripts/stamp-plugin-version.mjs), so the plugin always starts the server it was released with.
-VERSION="1.1.1"
+VERSION="1.2.1"
 
 # a global catherd at this version (catherd init installs one): start it, no resolve at all
 if command -v catherd >/dev/null 2>&1 && [ "$(catherd --version 2>/dev/null)" = "$VERSION" ]; then

package/plugin/skills/catherd/SKILL.md

@@ -23,7 +23,7 @@ Your job:
 
 The catherd server keeps `state.md` true: it rewrites it on every dispatch, climb and landing.
 
-**Your first call is `status()`.** Its `version` must be the one this plugin pins, `catherd-cli@1.1.1`. If it differs, stop and tell the user to restart Claude Code so the plugin and its server match.
+**Your first call is `status()`.** Its `version` must be the one this plugin pins, `catherd-cli@1.2.1`. If it differs, stop and tell the user to restart Claude Code so the plugin and its server match.
 
 **You never edit product files.** Every line of code, tests or docs comes from a role, including a one-line fix.
 
@@ -274,7 +274,7 @@ The brief is the `brief` text you pass to `dispatch` (catherd writes it to the d
 4. For a worker:
    - "Read `<R>/lanes/Mx.Ly.md`": decisions, signatures, data shapes;
    - its fast check (targeted tests, lint and type check), to run until it passes;
-   - "Run the full suite only if this brief says so", and "Wrap any full build or full test suite in `bunx catherd-cli@1.1.1 lock -- <command>`": other lanes share the machine.
+   - "Run the full suite only if this brief says so", and "Wrap any full build or full test suite in `bunx catherd-cli@1.2.1 lock -- <command>`": other lanes share the machine.
 5. For a reviewer: the A-lines and the changed files, with new files read in full. It reports every finding as `BLOCKER|BUG|NIT file:line — problem — fix`, covering:
    - unmet A-lines and edge cases;
    - code or abstractions nobody needs;

package/src/adapters/claude-code/models.ts

@@ -9,6 +9,7 @@ export const CLAUDE_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 export const CLAUDE_MODELS: DiscoveredModel[] = [
   { id: "claude-fable-5-1", efforts: CLAUDE_EFFORTS, context: 1_000_000, imageIn: true },
   { id: "claude-opus-5-5", efforts: CLAUDE_EFFORTS, context: 1_000_000, imageIn: true },
+  { id: "claude-sonnet-5-5", efforts: CLAUDE_EFFORTS, context: 1_000_000, imageIn: true },
   { id: "claude-sonnet-5", efforts: CLAUDE_EFFORTS, context: 1_000_000, imageIn: true },
   { id: "claude-haiku-4-5-20251001", efforts: [], context: 200_000, imageIn: true },
 ];
@@ -20,7 +21,7 @@ export const CLAUDE_ALIASES: Record<string, string> = {
   opus: "claude-opus-5-5",
   opusplan: "claude-opus-5-5",
   default: "claude-opus-5-5",
-  sonnet: "claude-sonnet-5",
+  sonnet: "claude-sonnet-5-5",
   haiku: "claude-haiku-4-5-20251001",
   "claude-haiku-4-5": "claude-haiku-4-5-20251001",
 };

package/src/domain/bars.ts

@@ -0,0 +1,119 @@
+import { type Dim, DIMS, type Score } from "./catalog.ts";
+import { DIFFICULTIES, type Difficulty, KINDS, type Kind } from "./lane.ts";
+
+/**
+ * Spec 1.2 §5.1: the dimensions each kind's default bars span, for Track A (`copy`, `build`) and Track B
+ * (`logic`, `hard`). `steer` has no default bar: it is shown, and a user may set one.
+ */
+export const DEFAULT_BAR_DIMS: Record<Kind, { A: Dim[]; B: Dim[] }> = {
+  repo_code: { A: ["repo_code"], B: ["repo_code", "honesty", "agentic"] },
+  terminal: { A: ["terminal"], B: ["terminal", "honesty", "agentic"] },
+  ui: { A: ["frontend", "repo_code"], B: ["frontend", "repo_code", "honesty", "agentic"] },
+  prose: { A: ["repo_code"], B: ["repo_code", "honesty"] },
+  research: { A: ["repo_code"], B: ["repo_code", "honesty"] },
+};
+
+/** The dimensions a difficulty's default bar spans for a kind. */
+export const barDimsOf = (kind: Kind, d: Difficulty): Dim[] =>
+  d === "copy" || d === "build" ? DEFAULT_BAR_DIMS[kind].A : DEFAULT_BAR_DIMS[kind].B;
+
+/** Every dimension some default bar uses: the values an enabled rung needs (spec 1.2 §6.1). */
+export const BAR_DIMS: Dim[] = DIMS.filter((d) =>
+  KINDS.some((k) => DIFFICULTIES.some((x) => barDimsOf(k, x).includes(d))),
+);
+
+/** Spec 1.2 §5.2: the percentile of the scored rungs each difficulty's threshold sits at. */
+export const BAR_PERCENTILE: Record<Difficulty, number> = { copy: 25, build: 50, logic: 60, hard: 75 };
+
+const PERCENTILE_WORD: Record<Difficulty, string> = {
+  copy: "the 25th percentile",
+  build: "the median",
+  logic: "the 60th percentile",
+  hard: "the 75th percentile",
+};
+
+/** The `p`th percentile of `xs`, interpolated linearly between the closest ranks; NaN for none. */
+export function percentile(xs: readonly number[], p: number): number {
+  if (xs.length === 0) return Number.NaN;
+  const s = [...xs].sort((a, b) => a - b);
+  const pos = ((s.length - 1) * p) / 100;
+  const lo = Math.floor(pos);
+  const hi = Math.ceil(pos);
+  return (s[lo] as number) + ((s[hi] as number) - (s[lo] as number)) * (pos - lo);
+}
+
+/**
+ * Spec 1.2 §5.2 "measured or better": a value published for this exact rung in the anchor's unit. That is a
+ * `verified` or `measured` value, and a hand-typed `secondary` one (no `source`: the 1.0 word for a value
+ * published by someone other than the vendor, which is 1.2's `measured`). Plan 14 Ruling 1.
+ */
+export const measuredOrBetter = (s: Score): boolean =>
+  s.confidence === "verified" ||
+  s.confidence === "measured" ||
+  (s.confidence === "secondary" && s.source === undefined);
+
+/** Each dimension's values that bars are derived from: one per canonical rung, measured or better. */
+export function barPool(scores: readonly Score[]): Record<Dim, number[]> {
+  const out = Object.fromEntries(DIMS.map((d) => [d, [] as number[]])) as Record<Dim, number[]>;
+  const seen = new Set<string>();
+  for (const s of scores) {
+    const key = `${s.rung} ${s.dim}`;
+    if (!measuredOrBetter(s) || seen.has(key)) continue;
+    seen.add(key);
+    out[s.dim].push(s.value);
+  }
+  return out;
+}
+
+/** A bar value, kept to four significant digits (DeepSWE 60.95, an Arena rating 1668, agentic 0.08622). */
+const tidy = (v: number): number => Number(v.toPrecision(4));
+
+export type Bars = Record<Kind, Record<Difficulty, Partial<Record<Dim, number>>>>;
+/** `scores.json` `barsWhy`: per dimension and difficulty, where its threshold came from. */
+export type BarsWhy = Partial<Record<Dim, Partial<Record<Difficulty, string>>>>;
+
+/**
+ * Spec 1.2 §5.1–§5.2: the default bars. Each dimension's threshold at a difficulty is that difficulty's
+ * percentile of the pool (`barPool`), the same in every kind whose bar spans the dimension. A dimension with
+ * no pooled value gets no threshold (and a `barsWhy` line saying so). `benchmark` names each dimension's unit
+ * and `date` the day the data was read.
+ */
+export function deriveBars(
+  pool: Record<Dim, number[]>,
+  benchmark: (d: Dim) => string,
+  date: string,
+): { bars: Bars; barsWhy: BarsWhy } {
+  const value: Partial<Record<Dim, Partial<Record<Difficulty, number>>>> = {};
+  const barsWhy: BarsWhy = {};
+  for (const dim of BAR_DIMS)
+    for (const d of DIFFICULTIES) {
+      if (!KINDS.some((k) => barDimsOf(k, d).includes(dim))) continue;
+      const xs = pool[dim];
+      const why = (barsWhy[dim] ??= {});
+      if (xs.length === 0) {
+        why[d] = `no rung is measured or better on ${benchmark(dim)} (${date}): no threshold`;
+        continue;
+      }
+      const v = tidy(percentile(xs, BAR_PERCENTILE[d]));
+      (value[dim] ??= {})[d] = v;
+      why[d] =
+        `${PERCENTILE_WORD[d]} of ${xs.length} rungs measured or better on ${benchmark(dim)} (${date}): ${v}`;
+    }
+  const bars = Object.fromEntries(
+    KINDS.map((k) => [
+      k,
+      Object.fromEntries(
+        DIFFICULTIES.map((d) => [
+          d,
+          Object.fromEntries(
+            barDimsOf(k, d).flatMap((dim) => {
+              const v = value[dim]?.[d];
+              return v === undefined ? [] : [[dim, v]];
+            }),
+          ),
+        ]),
+      ),
+    ]),
+  ) as Bars;
+  return { bars, barsWhy };
+}

package/src/domain/calibration.ts

@@ -0,0 +1,125 @@
+import type { Dim } from "./catalog.ts";
+import type { SourceId } from "./sources.ts";
+
+/** Spec 1.2 §4.2: a source needs this many rungs shared with the anchor for a dimension. */
+export const MIN_SHARED = 5;
+/** Spec 1.2 §4.2: a fit below this R² is not used. */
+export const MIN_R2 = 0.5;
+
+/** One number a source parser returns: `field` of `source`, and the benchmark it names. */
+export interface FieldRef {
+  source: SourceId;
+  field: string;
+  benchmark: string;
+}
+
+/**
+ * Spec 1.2 §4.1: each dimension's anchor, the unit its bars are in, and the sources calibrated onto it.
+ * `shipped` is the hand-typed value `catalog/scores.json` carries, published for that rung (every anchor is
+ * keyless, spec 1.2 §4.1).
+ */
+export const DIM_SOURCES: Record<Dim, { anchor: FieldRef | "shipped"; others: FieldRef[] }> = {
+  repo_code: {
+    anchor: "shipped",
+    others: [
+      {
+        source: "artificial-analysis",
+        field: "livecodebench",
+        benchmark: "LiveCodeBench (Artificial Analysis)",
+      },
+      { source: "artificial-analysis", field: "scicode", benchmark: "SciCode (Artificial Analysis)" },
+      {
+        source: "artificial-analysis",
+        field: "artificial_analysis_coding_index",
+        benchmark: "Artificial Analysis Coding Index",
+      },
+      { source: "epoch", field: "frontiercode", benchmark: "FrontierCode (Epoch AI)" },
+    ],
+  },
+  // plan 14 Ruling C-2: the vendors' Terminal-Bench 4.0 values, not Epoch's Terminal-Bench 2.0, which shares
+  // no rung with them; Epoch is fitted onto them once it covers five of their rungs
+  terminal: {
+    anchor: "shipped",
+    others: [
+      { source: "epoch", field: "terminalbench", benchmark: "Terminal-Bench (Epoch AI)" },
+      {
+        source: "artificial-analysis",
+        field: "terminalbench_v2_1",
+        benchmark: "Terminal-Bench 2.1 (Artificial Analysis)",
+      },
+    ],
+  },
+  honesty: {
+    anchor: "shipped",
+    others: [
+      { source: "vectara", field: "factual_consistency", benchmark: "Vectara factual consistency rate" },
+      { source: "arena", field: "agent_tool_hallucination", benchmark: "Arena agent tool hallucination" },
+    ],
+  },
+  agentic: {
+    anchor: { source: "arena", field: "agent", benchmark: "Arena agent, net improvement" },
+    others: [
+      { source: "arena", field: "agent_task_outcome_explicit", benchmark: "Arena agent task outcome" },
+      { source: "arena", field: "agent_bash_recovery_steps", benchmark: "Arena agent bash recovery" },
+      { source: "artificial-analysis", field: "tau2", benchmark: "tau2-bench (Artificial Analysis)" },
+    ],
+  },
+  steer: {
+    anchor: { source: "arena", field: "agent_steerability", benchmark: "Arena agent steerability" },
+    others: [],
+  },
+  frontend: {
+    anchor: { source: "arena", field: "webdev", benchmark: "Arena WebDev rating" },
+    others: [{ source: "epoch", field: "webdev", benchmark: "WebDev Arena (Epoch AI)" }],
+  },
+};
+
+export interface LineFit {
+  a: number;
+  b: number;
+  r2: number;
+  n: number;
+}
+
+/** Least squares `anchor = a·x + b` over `[x, anchor]` pairs; null with fewer than 2 pairs or no spread in x. */
+export function fitLine(pairs: readonly (readonly [number, number])[]): LineFit | null {
+  const n = pairs.length;
+  if (n < 2) return null;
+  const mx = pairs.reduce((s, [x]) => s + x, 0) / n;
+  const my = pairs.reduce((s, [, y]) => s + y, 0) / n;
+  let sxx = 0;
+  let sxy = 0;
+  let syy = 0;
+  for (const [x, y] of pairs) {
+    sxx += (x - mx) ** 2;
+    sxy += (x - mx) * (y - my);
+    syy += (y - my) ** 2;
+  }
+  if (sxx === 0) return null;
+  const a = sxy / sxx;
+  const b = my - a * mx;
+  const res = pairs.reduce((s, [x, y]) => s + (y - (a * x + b)) ** 2, 0);
+  return { a, b, r2: syy === 0 ? 0 : 1 - res / syy, n };
+}
+
+/**
+ * Spec 1.2 §4.2: the fit of `other` onto `anchor` over the keys both hold, and whether it may be used: at
+ * least MIN_SHARED shared rungs and an R² of at least MIN_R2. `why` says why not.
+ */
+export function calibrate(
+  anchor: ReadonlyMap<string, number>,
+  other: ReadonlyMap<string, number>,
+): { fit: LineFit | null; n: number; used: boolean; why?: string } {
+  const pairs: [number, number][] = [];
+  for (const [k, x] of other) {
+    const y = anchor.get(k);
+    if (y !== undefined) pairs.push([x, y]);
+  }
+  const n = pairs.length;
+  if (n < MIN_SHARED)
+    return { fit: null, n, used: false, why: `${n} shared rungs; a fit needs ${MIN_SHARED}` };
+  const fit = fitLine(pairs);
+  if (!fit) return { fit: null, n, used: false, why: "the source gives every shared rung the same value" };
+  if (fit.r2 < MIN_R2) return { fit, n, used: false, why: `R² ${fit.r2.toFixed(2)} is below ${MIN_R2}` };
+  return { fit, n, used: true };
+}