phronesis 1.0.0

package/src/skills-bump.js

@@ -0,0 +1,885 @@
+// `phronesis skills bump` (core-0031 / T7.4 + the T7.2 coverage floor) — the
+// deployment-unit gate. Bumping a skill's prompt_pin runs the candidate-execution
+// substrate (core-0028) k times under the proposed pin, aggregates to a STRICT-min
+// floor on BOTH axes (quality + coverage), refuses the comparison if the evaluation
+// identity drifted, blocks an either-axis regression vs the previous accepted pin,
+// increments the skill version, and writes the new pin ONLY on pass
+// (specs/eval-discipline.md §"Prompt + model is the deployment unit").
+//
+// This module is orchestration + decision. It executes NO skill itself (the substrate
+// does) and runs NO judge itself (the substrate's one judge does). The substrate is
+// injected (deps.runCandidates) so the fitness gate runs deterministic, no model/credits.
+//
+// Why a NEW aggregator and not harness/evals/compile/run_floor.py's aggregate(): that
+// routine is compile-specific (locked to judge.py's six CRITERIA) and SOFT-floored
+// (passes = mean >= floor and lo >= floor-1, a one-point slack). The spec's floor is the
+// literal "minimum score ... not the mean" (eval-discipline.md), criteria-agnostic. So
+// this builds a generic, strict-min aggregator: per criterion of the skill's OWN rubric,
+// the minimum across the k runs must clear the floor — a [5,5,5,5,3] 5/3 split FAILS at
+// floor 4 (min 3 < 4), where run_floor's soft floor would pass it.
+
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { open, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const DEFAULT_K = 5;
+// A hard cap on k: each run is k × goldens model+judge calls, so an un-bounded --k turns a
+// typo (`--k 1000`) into a runaway model/judge bill. 50 is far above any real reliability
+// sample; above it, refuse and tell the operator to lower it.
+export const MAX_K = 50;
+export const DEFAULT_QUALITY_FLOOR = 4;
+// Quality scores are integers 1-5 (judge.py). A floor outside [1,5] (e.g. 0 or negative)
+// would silently disable the quality axis — reject it.
+export const QUALITY_FLOOR_RANGE = [1, 5];
+// The coverage floor defaults to 1.0 (every warranted capture fires in the WORST run) —
+// fail-closed; a skill declares a looser floor explicitly. The reliability protocol is a
+// floor, not a mean, on this axis too.
+export const DEFAULT_COVERAGE_FLOOR = 1;
+// Coverage is a warranted-capture hit-rate ∈ [0,1]. A negative floor would disable the
+// axis; a floor > 1 would fail even a perfect run. 0 is allowed (disables coverage) but
+// warned at the call site.
+export const COVERAGE_FLOOR_RANGE = [0, 1];
+
+// ---------------------------------------------------------------------------
+// Pin + version
+// ---------------------------------------------------------------------------
+
+// A model id is letters/digits with `.`, `-`, `_` separators only — NO whitespace,
+// newlines, or YAML-significant characters. The pin is written verbatim into SKILL.md
+// YAML frontmatter (rewriteSkillFrontmatter), so an unvalidated id with a newline could
+// inject a frontmatter line (`prompt_pin: gpt-5\nweight: light@...`). Matches the real
+// ids: gpt-5, claude-opus-4-8, us.anthropic.claude-opus-4-8.
+export const MODEL_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+// prompt_pin = {model_id}@{date} (specs/skills.md). The candidate runs under model_id.
+export function parsePin(pin) {
+  if (typeof pin !== 'string' || pin.trim() === '') {
+    return { error: 'pin must be a non-empty {model_id}@{date} string' };
+  }
+  const at = pin.lastIndexOf('@');
+  if (at <= 0 || at === pin.length - 1) {
+    return { error: `pin must be {model_id}@{date} (got "${pin}")` };
+  }
+  const modelId = pin.slice(0, at).trim();
+  const date = pin.slice(at + 1).trim();
+  if (!MODEL_ID_RE.test(modelId)) {
+    return {
+      error:
+        `pin model id "${modelId}" is not allowlisted — only letters, digits, and . - _ ` +
+        '(no whitespace, newlines, or YAML-significant characters that could corrupt the frontmatter)',
+    };
+  }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+    return { error: `pin date must be YYYY-MM-DD (got "${date}")` };
+  }
+  // raw is RECONSTRUCTED from the validated parts — never the raw input — so trailing
+  // junk or interior whitespace in the input can never reach SKILL.md.
+  return { modelId, date, raw: `${modelId}@${date}` };
+}
+
+// B5: every pin change increments the version. Output-shape change → MAJOR (skills.md:43);
+// a model-only prompt_pin swap (no output-shape change) → MINOR. There is no
+// re-pin-without-version path.
+export function bumpVersion(version, component = 'minor') {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(version || '').trim());
+  if (!m) throw new Error(`skill version is not SemVer X.Y.Z: "${version}"`);
+  let [major, minor, patch] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  if (component === 'major') return `${major + 1}.0.0`;
+  if (component === 'minor') return `${major}.${minor + 1}.0`;
+  if (component === 'patch') return `${major}.${minor}.${patch + 1}`;
+  throw new Error(`unknown SemVer component: ${component}`);
+}
+
+// ---------------------------------------------------------------------------
+// Score extraction (tolerant of the judge's known format drift — rules.md: coerce
+// "5"/5.0 → 5; a floor that fails on the judge's formatting is a lying gate)
+// ---------------------------------------------------------------------------
+
+export function coerceScore(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value))) {
+    return Number(value);
+  }
+  if (value && typeof value === 'object') return coerceScore(value.score);
+  return NaN;
+}
+
+// per_run_scores is the judge's output. judge.py returns { scores: {<crit>: {score}} };
+// a function judge may return {<crit>: {score}} or {<crit>: 5} directly. Normalize both.
+export function extractCriterionScores(perRunScores) {
+  if (!perRunScores || typeof perRunScores !== 'object') {
+    throw new Error('a candidate run is missing per_run_scores — cannot gate the quality axis');
+  }
+  const scores = perRunScores.scores && typeof perRunScores.scores === 'object'
+    ? perRunScores.scores
+    : perRunScores;
+  const out = {};
+  for (const [crit, raw] of Object.entries(scores)) {
+    // judge.py siblings `meta` beside `scores`, so the unwrap above already drops it; this
+    // guards a flat function-judge that returns criteria and a `meta` key in one object.
+    if (crit === 'meta') continue;
+    const n = coerceScore(raw);
+    if (!Number.isFinite(n)) throw new Error(`criterion "${crit}" has a non-numeric score`);
+    out[crit] = n;
+  }
+  if (Object.keys(out).length === 0) {
+    throw new Error('a candidate run produced an empty rubric score set — cannot gate quality');
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Coverage axis (read off the substrate's action_trace coverage markers)
+// ---------------------------------------------------------------------------
+
+// Per run: warranted captures that fired = hits; warranted that did NOT fire = misses;
+// UNwarranted that fired = fabrications (a signal failure, eval-discipline.md anti-
+// fabrication rule); unwarranted not-fired = honest restraint. Hit-rate is over the
+// warranted set only; an honest-negative run (nothing warranted) scores a full 1.0.
+export function coverageFromTrace(actionTrace) {
+  const markers = (actionTrace || []).filter((e) => e && e.kind === 'coverage');
+  let warrantedTotal = 0;
+  let warrantedFired = 0;
+  let fabrications = 0;
+  for (const m of markers) {
+    const warranted = m.payload?.warranted === true;
+    const fired = m.result === 'fired';
+    if (warranted) {
+      warrantedTotal += 1;
+      if (fired) warrantedFired += 1;
+    } else if (fired) {
+      fabrications += 1;
+    }
+  }
+  const hitRate = warrantedTotal === 0 ? 1 : warrantedFired / warrantedTotal;
+  return { warrantedTotal, warrantedFired, fabrications, hitRate };
+}
+
+// ---------------------------------------------------------------------------
+// The generic, strict-min aggregator (B3) — over the FLATTENED k×goldens runs.
+// Quality: per criterion, min across all runs ≥ floor (every golden's worst run clears
+// it). Coverage: min per-run hit-rate across all runs ≥ floor; any fabrication anywhere
+// fails outright.
+// ---------------------------------------------------------------------------
+
+export function aggregateFloor(perRunResults, {
+  qualityFloor = DEFAULT_QUALITY_FLOOR,
+  coverageFloor = DEFAULT_COVERAGE_FLOOR,
+} = {}) {
+  const runs = Array.isArray(perRunResults) ? perRunResults : [];
+  if (runs.length === 0) {
+    return {
+      runs: 0,
+      empty: true,
+      quality: { criteria: {}, passes: false },
+      coverage: { hit_rate_min: 0, fabrications: 0, asserted: false, per_run: [], passes: false },
+    };
+  }
+
+  // Quality — collect per-criterion score vectors across every run.
+  const perCriterion = new Map();
+  for (const run of runs) {
+    const scores = extractCriterionScores(run.per_run_scores);
+    for (const [crit, score] of Object.entries(scores)) {
+      if (!perCriterion.has(crit)) perCriterion.set(crit, []);
+      perCriterion.get(crit).push(score);
+    }
+  }
+  // Every run must score every criterion — a missing criterion means inconsistent
+  // scoring (or a rubric mismatch), which must not silently pass.
+  const criteria = {};
+  let qualityPasses = true;
+  for (const [crit, vec] of perCriterion) {
+    if (vec.length !== runs.length) {
+      throw new Error(
+        `criterion "${crit}" scored in ${vec.length}/${runs.length} runs — inconsistent rubric scoring`,
+      );
+    }
+    const min = Math.min(...vec);
+    const passes = min >= qualityFloor;
+    if (!passes) qualityPasses = false;
+    criteria[crit] = { min, max: Math.max(...vec), scores: vec, passes };
+  }
+
+  // Coverage — per-run hit-rate + fabrication tally. `asserted` is false when NO run
+  // carried a warranted expectation: the coverage axis then passes vacuously (an honest
+  // negative is valid, eval-discipline.md), but the gate must surface that it asserted
+  // nothing rather than report a verified coverage pass (the change-0010 misfire class).
+  const perRunCoverage = runs.map((run) => coverageFromTrace(run.action_trace));
+  const hitRateMin = Math.min(...perRunCoverage.map((c) => c.hitRate));
+  const fabrications = perRunCoverage.reduce((sum, c) => sum + c.fabrications, 0);
+  const asserted = perRunCoverage.some((c) => c.warrantedTotal > 0);
+  const coveragePasses = fabrications === 0 && hitRateMin >= coverageFloor;
+
+  return {
+    runs: runs.length,
+    quality: { criteria, passes: qualityPasses },
+    coverage: {
+      hit_rate_min: hitRateMin,
+      fabrications,
+      asserted,
+      per_run: perRunCoverage.map((c) => ({
+        warranted_total: c.warrantedTotal,
+        warranted_fired: c.warrantedFired,
+        fabrications: c.fabrications,
+        hit_rate: c.hitRate,
+      })),
+      passes: coveragePasses,
+    },
+  };
+}
+
+// The per-criterion + coverage floor numbers a baseline record carries (B4a "the scores").
+export function floorScores(aggregate) {
+  const quality = {};
+  for (const [crit, c] of Object.entries(aggregate.quality.criteria)) quality[crit] = c.min;
+  return {
+    quality,
+    coverage: {
+      hit_rate_floor: aggregate.coverage.hit_rate_min,
+      fabrications: aggregate.coverage.fabrications,
+      asserted: aggregate.coverage.asserted,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Evaluation identity (B4b / B10) — a floor number is only comparable against the SAME
+// eval. Record name-free hashes/versions of everything the scores depend on; refuse the
+// comparison if any drifted.
+// ---------------------------------------------------------------------------
+
+function sha256(value) {
+  return createHash('sha256').update(String(value), 'utf8').digest('hex');
+}
+
+export function computeEvalIdentity({ corpus, rubric, registry, runnerProtocolVersion, judgePin }) {
+  return {
+    corpus: sha256(corpus ?? ''),
+    rubric: sha256(rubric ?? ''),
+    registry: sha256(registry ?? ''),
+    runner_protocol: String(runnerProtocolVersion ?? ''),
+    judge: sha256(judgePin ?? ''),
+  };
+}
+
+const IDENTITY_COMPONENTS = ['corpus', 'rubric', 'registry', 'runner_protocol', 'judge'];
+
+export function identityDrift(before, after) {
+  if (!before || !after) return [];
+  const drifted = [];
+  for (const k of IDENTITY_COMPONENTS) {
+    if ((before[k] ?? '') !== (after[k] ?? '')) drifted.push(k);
+  }
+  return drifted;
+}
+
+// ---------------------------------------------------------------------------
+// The decision (B3 / B4 / B8 / B10)
+// ---------------------------------------------------------------------------
+
+function absoluteFloorCheck(aggregate, qualityFloor, coverageFloor) {
+  const qualityFailures = Object.entries(aggregate.quality.criteria)
+    .filter(([, c]) => c.min < qualityFloor)
+    .map(([crit, c]) => ({ axis: 'quality', criterion: crit, floor: qualityFloor, got: c.min }));
+  const coverageFail = aggregate.coverage.hit_rate_min < coverageFloor
+    ? [{ axis: 'coverage', floor: coverageFloor, got: aggregate.coverage.hit_rate_min }]
+    : [];
+  const failures = [...qualityFailures, ...coverageFail];
+  return { passes: failures.length === 0, failures };
+}
+
+function regressionCheck(baselineScores, aggregate, coverageFloor) {
+  const regressed = [];
+  const baseQuality = baselineScores?.quality || {};
+  for (const [crit, c] of Object.entries(aggregate.quality.criteria)) {
+    const base = baseQuality[crit];
+    if (base === undefined) {
+      // A criterion absent from the baseline under matched identity is a rubric the
+      // baseline never measured — treat as a regression rather than a silent pass.
+      regressed.push({ axis: 'quality', criterion: crit, baseline: null, got: c.min });
+    } else if (c.min < base) {
+      regressed.push({ axis: 'quality', criterion: crit, baseline: base, got: c.min });
+    }
+  }
+  // The reverse direction: a criterion the baseline measured but the new run no longer
+  // scores (consistently, so aggregateFloor didn't throw) is an unverified disappearance —
+  // never silently let it pass as "no regression."
+  for (const crit of Object.keys(baseQuality)) {
+    if (!(crit in aggregate.quality.criteria)) {
+      regressed.push({ axis: 'quality', criterion: crit, baseline: baseQuality[crit], got: null });
+    }
+  }
+  // Coverage RELATIVE regression: a dip that stays at/above the absolute floor but below
+  // the accepted baseline's recorded floor. (A drop BELOW the absolute floor is already a
+  // hard block in decideBump, so this branch only ever catches above-floor dips.) Fails
+  // CLOSED, symmetric with the missing-quality-criterion branch: a baseline that recorded
+  // no `hit_rate_floor` (cross-version / hand-edited PINS.md) falls back to the absolute
+  // coverage floor rather than skipping the check.
+  const baseCoverage = baselineScores?.coverage?.hit_rate_floor ?? coverageFloor;
+  if (aggregate.coverage.hit_rate_min < baseCoverage) {
+    regressed.push({ axis: 'coverage', baseline: baseCoverage, got: aggregate.coverage.hit_rate_min });
+  }
+  return { regressed };
+}
+
+// mode: 'normal' | 'rebaseline'. (accept-regression is a caller policy over a 'regression'
+// verdict, not a separate decision mode — the gate's verdict is the same; only whether the
+// caller proceeds differs.)
+export function decideBump({
+  mode = 'normal',
+  baseline,
+  aggregate,
+  newIdentity,
+  qualityFloor = DEFAULT_QUALITY_FLOOR,
+  coverageFloor = DEFAULT_COVERAGE_FLOOR,
+}) {
+  if (aggregate.empty || aggregate.runs === 0) {
+    return { status: 'blocked-empty', detail: 'no candidate runs were produced — cannot gate' };
+  }
+
+  // Fabrication is a hard fail in EVERY mode and is NOT a "regression" overridable by
+  // --accept-regression: it is a signal-integrity failure (anti-Goodhart). Only fixing the
+  // skill clears it.
+  if (aggregate.coverage.fabrications > 0) {
+    return { status: 'blocked-fabrication', fabrications: aggregate.coverage.fabrications };
+  }
+
+  const absolute = absoluteFloorCheck(aggregate, qualityFloor, coverageFloor);
+
+  // First bump (no baseline) and --rebaseline both seed under the absolute floor on BOTH
+  // axes, no regression check (B4 / B10). The absolute floor is never bypassable — it is
+  // the one path with no regression check to catch a fabricating / under-capturing seed.
+  if (mode === 'rebaseline' || !baseline) {
+    if (!absolute.passes) return { status: 'blocked-absolute', absolute };
+    return { status: 'pass', seeded: true, absolute };
+  }
+
+  // Normal bump with a baseline: identity drift REFUSES the comparison first (B10) — a
+  // changed corpus/rubric/registry/runner/judge could make a real regression appear to
+  // pass. Neither pass nor regression; the operator must --rebaseline.
+  const drift = identityDrift(baseline.identity, newIdentity);
+  if (drift.length) return { status: 'refused-drift', drift };
+
+  // The absolute floor — quality's rubric pass bar (≥ qualityFloor on every criterion) AND
+  // the coverage floor (min per-run hit-rate ≥ coverageFloor) — is a HARD block in EVERY
+  // mode, never overridable. --accept-regression overrides only a RELATIVE dip that stays
+  // AT OR ABOVE both floors (e.g. 5 → 4), never a skill that fell BELOW a floor (5 → 2, or
+  // a coverage collapse below the declared floor). Both axes are treated symmetrically:
+  // without this, a coverage absolute failure slipped past the (formerly quality-only)
+  // guard into the overridable regression branch, so --accept-regression — or a baseline
+  // seeded at a lower hit_rate_floor — could ship coverage below the advertised floor.
+  if (!absolute.passes) {
+    return { status: 'blocked-absolute', absolute };
+  }
+
+  const reg = regressionCheck(baseline.scores, aggregate, coverageFloor);
+  if (reg.regressed.length) return { status: 'regression', regressed: reg.regressed };
+  return { status: 'pass' };
+}
+
+// ---------------------------------------------------------------------------
+// PINS.md — the committed, name-free baseline-per-pin record (B4 / B8 / B10). One
+// self-contained record per accepted bump; kind ∈ baseline | override | rebaseline; every
+// record carries scores + identity; the CURRENT baseline is the last record.
+// ---------------------------------------------------------------------------
+
+const PINS_HEADER = `# PINS — accepted prompt_pin baselines
+
+Name-free, git-tracked, one record per accepted bump (specs/eval-discipline.md
+§"Promotion semantics"). Each record carries the per-criterion quality floor + coverage
+hit-rate floor that the next bump compares against, and the evaluation identity those
+scores were produced under. \`kind\`: \`baseline\` (clean pass), \`override\`
+(\`--accept-regression\` over a real regression), \`rebaseline\` (\`--rebaseline\` reset
+after evaluation-identity drift). The current accepted baseline is the LAST record.
+`;
+
+export function renderPinsRecord(record) {
+  const heading = `## ${record.pin} — ${record.kind} (v${record.version})`;
+  return `${heading}\n\n\`\`\`json\n${JSON.stringify(record, null, 2)}\n\`\`\`\n`;
+}
+
+export function parsePins(text) {
+  if (typeof text !== 'string' || text.trim() === '') return { records: [] };
+  const records = [];
+  const re = /```json\s*\n([\s\S]*?)\n```/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    try {
+      records.push(JSON.parse(m[1]));
+    } catch {
+      throw new Error('PINS.md contains an unparseable record block');
+    }
+  }
+  return { records };
+}
+
+export function currentBaseline(records) {
+  if (!records || records.length === 0) return null;
+  return records[records.length - 1];
+}
+
+export function appendPinsRecord(existingText, record) {
+  const base = existingText && existingText.trim() !== '' ? existingText.replace(/\s*$/, '') : PINS_HEADER.replace(/\s*$/, '');
+  return `${base}\n\n${renderPinsRecord(record).replace(/\s*$/, '')}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// SKILL.md frontmatter rewrite (write pin + version on pass only)
+// ---------------------------------------------------------------------------
+
+export function rewriteSkillFrontmatter(source, { pin, version }) {
+  if (typeof source !== 'string' || !source.startsWith('---')) {
+    throw new Error('SKILL.md does not start with a --- frontmatter fence');
+  }
+  const end = source.indexOf('\n---', 3);
+  if (end === -1) throw new Error('SKILL.md frontmatter is not closed with ---');
+  const fmEnd = end + 1; // index of the closing --- line start
+  const front = source.slice(0, fmEnd);
+  const rest = source.slice(fmEnd);
+  let out = front;
+  if (version !== undefined) {
+    if (!/^version:.*$/m.test(out)) throw new Error('SKILL.md frontmatter has no version field');
+    out = out.replace(/^version:.*$/m, `version: ${version}`);
+  }
+  if (pin !== undefined) {
+    if (!/^prompt_pin:.*$/m.test(out)) throw new Error('SKILL.md frontmatter has no prompt_pin field');
+    out = out.replace(/^prompt_pin:.*$/m, `prompt_pin: ${pin}`);
+  }
+  return out + rest;
+}
+
+export function readFrontmatterField(source, field) {
+  const end = source.indexOf('\n---', 3);
+  const front = end === -1 ? source : source.slice(0, end);
+  const m = new RegExp(`^${field}:\\s*(.+)$`, 'm').exec(front);
+  return m ? m[1].trim() : null;
+}
+
+// ---------------------------------------------------------------------------
+// Repo resolution (B6) — explicit --repo, else cwd must be a repo ROOT (skills/ +
+// changes/ present). Refuse if neither resolves; no silent install fallback (bump is a
+// dev/release op on git-tracked source).
+// ---------------------------------------------------------------------------
+
+export function resolveRepoRoot({ repo, cwd = process.cwd() }) {
+  const root = repo || cwd;
+  const isRepo = existsSync(join(root, 'skills')) && existsSync(join(root, 'changes'));
+  if (!isRepo) {
+    return {
+      error:
+        `not a Phronesis repo root: ${root} (expected skills/ and changes/). ` +
+        'skills bump operates on git-tracked source — pass --repo <path> or run from the repo root. ' +
+        'There is no install fallback; the install picks up the pin on init/update.',
+    };
+  }
+  return { root };
+}
+
+// ---------------------------------------------------------------------------
+// Result-completeness + write-safety helpers
+// ---------------------------------------------------------------------------
+
+// The golden id the substrate stamps on each result (run_candidates: golden.id || name ||
+// golden-N). Recompute it identically so the gate can prove one result per golden.
+export function expectedGoldenIds(goldens) {
+  return (goldens || []).map((g, i) => g?.id || g?.name || `golden-${i + 1}`);
+}
+
+// Compare the substrate's returned golden ids to the corpus's as a MULTISET — catches a
+// missing golden, a duplicate (re-ran one, dropped another), an extraneous result, and a
+// result with no golden_id. Returns a human-readable mismatch description, or null if exact.
+export function goldenResultMismatch(expectedIds, results) {
+  if (!Array.isArray(results)) return 'returned a non-array result set';
+  const got = results.map((r) => (r && typeof r === 'object' ? r.golden_id : undefined));
+  if (got.some((id) => typeof id !== 'string' || id === '')) {
+    return 'returned a result with no golden_id';
+  }
+  const expected = [...expectedIds].sort();
+  const actual = [...got].sort();
+  if (expected.length !== actual.length || expected.some((id, i) => id !== actual[i])) {
+    return `returned golden ids [${actual.join(', ')}] ≠ corpus [${expected.join(', ')}]`;
+  }
+  return null;
+}
+
+// Atomic write: write a temp sibling then rename over the target (rename is atomic within a
+// dir), so a crash mid-write can never leave a torn PINS.md / SKILL.md. Under the skill lock
+// the temp name needn't be unique, but the pid suffix is cheap insurance.
+async function atomicWrite(path, content) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  await writeFile(tmp, content);
+  await rename(tmp, path);
+}
+
+// A per-skill advisory lock (git-style index.lock): O_EXCL create fails if a concurrent
+// bump for the same skill holds it, so two bumps can't interleave their PINS read-modify-
+// write and lose a record. Returns { path } on acquire, { error } on conflict. A crash
+// leaves a stale lock the operator clears by hand — the same contract as git.
+async function acquireSkillLock(skillDir) {
+  const lockPath = join(skillDir, '.bump.lock');
+  try {
+    const fh = await open(lockPath, 'wx');
+    await fh.write(`bump in progress · pid ${process.pid}\n`);
+    await fh.close();
+    return { path: lockPath };
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      return {
+        error:
+          `another \`skills bump\` for this skill is in progress (lock: ${lockPath}). ` +
+          'If you are certain no other bump is running, remove the lock file and retry.',
+      };
+    }
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The orchestrator (B1) — consume the substrate; orchestrate + decide only.
+// ---------------------------------------------------------------------------
+
+export async function bumpSkill(opts, deps) {
+  const {
+    skill,
+    toPin,
+    repoRoot,
+    k = DEFAULT_K,
+    rebaseline = false,
+    acceptRegression = false,
+    shapeChange = false,
+    qualityFloor = DEFAULT_QUALITY_FLOOR,
+    coverageFloor = DEFAULT_COVERAGE_FLOOR,
+    rationale = null,
+    acceptedBy = 'operator',
+    activeDomain,
+  } = opts;
+  const {
+    runCandidates,
+    parseSkillSource,
+    runnerProtocolVersion,
+    registrySection,
+    judgePin,
+    judgeModel,
+    loadCorpus,
+    judge,
+    now,
+  } = deps;
+
+  const mode = rebaseline ? 'rebaseline' : 'normal';
+  if (typeof skill !== 'string' || skill.trim() === '') throw new Error('bumpSkill requires a skill name');
+  // Sanitize the skill name before it reaches any path join (the substrate sanitizes its
+  // own workspace paths; the gate that writes git-tracked source must match that
+  // discipline). A kebab-case skill name matches the SKILL.md directory contract.
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(skill)) {
+    return { status: 'invalid', error: `invalid skill name "${skill}" (expected kebab-case [a-z0-9-], matching the skills/ directory)` };
+  }
+  const pin = parsePin(toPin);
+  if (pin.error) return { status: 'invalid', error: pin.error };
+  if (!Number.isInteger(k) || k < 1) return { status: 'invalid', error: '--k must be a positive integer' };
+  if (k > MAX_K) {
+    return {
+      status: 'invalid',
+      error: `--k ${k} exceeds the cap of ${MAX_K} — each run is k × goldens model+judge calls, so a large k is almost always a typo. Lower it (a reliability floor needs only a handful of runs).`,
+    };
+  }
+  if (!Number.isFinite(qualityFloor) || qualityFloor < QUALITY_FLOOR_RANGE[0] || qualityFloor > QUALITY_FLOOR_RANGE[1]) {
+    return {
+      status: 'invalid',
+      error: `--quality-floor must be within [${QUALITY_FLOOR_RANGE.join(', ')}] (judge scores are integers 1-5); got ${qualityFloor}. A floor outside the scale would disable the quality axis.`,
+    };
+  }
+  if (!Number.isFinite(coverageFloor) || coverageFloor < COVERAGE_FLOOR_RANGE[0] || coverageFloor > COVERAGE_FLOOR_RANGE[1]) {
+    return {
+      status: 'invalid',
+      error: `--coverage-floor must be within [${COVERAGE_FLOOR_RANGE.join(', ')}] (a warranted-capture hit-rate); got ${coverageFloor}. A negative floor would disable the coverage axis.`,
+    };
+  }
+  // The escape hatches MUST carry a rationale — the override / rebaseline record is the
+  // committed audit trail (B8/B10), and a null rationale destroys its only value. Fail
+  // fast, before the (expensive) substrate runs.
+  if ((rebaseline || acceptRegression) && (typeof rationale !== 'string' || rationale.trim() === '')) {
+    const flag = rebaseline ? '--rebaseline' : '--accept-regression';
+    return {
+      status: 'invalid',
+      error: `${flag} requires a non-empty --rationale — it is the audit trail for the escape hatch, and a missing rationale makes the recorded override/rebaseline unauditable.`,
+    };
+  }
+
+  const skillDir = join(repoRoot, 'skills', skill);
+  const skillPath = join(skillDir, 'SKILL.md');
+  if (!existsSync(skillPath)) {
+    return { status: 'invalid', error: `skill not found: ${skillPath}` };
+  }
+  const source = await readFile(skillPath, 'utf8');
+  const currentVersion = readFrontmatterField(source, 'version');
+  const currentPin = readFrontmatterField(source, 'prompt_pin');
+
+  const rubricPath = join(skillDir, 'evals', 'rubric.md');
+  if (!existsSync(rubricPath)) {
+    return { status: 'invalid', error: `skill has no L2 rubric: ${rubricPath} (cannot gate quality)` };
+  }
+  const rubric = await readFile(rubricPath, 'utf8');
+
+  // Corpus + signedness (B7). The gate ALWAYS runs; unsigned annotates, never bypasses.
+  const corpus = await loadCorpus({ skill, repoRoot });
+  const goldens = corpus?.goldens || [];
+  const corpusSigned = corpus?.signed === true;
+  const gateStatus = corpusSigned ? 'authoritative' : 'provisional';
+  if (goldens.length === 0) {
+    return {
+      status: 'blocked',
+      reason: 'empty-corpus',
+      corpus_signed: corpusSigned,
+      gate_status: gateStatus,
+      message:
+        `no goldens resolved for "${skill}" — cannot gate (corpus: ${corpus?.source || 'unresolved'}). ` +
+        'Goldens live in the install ($PHRONESIS_INSTALL/corpus/skill-goldens/<skill>), never the repo; ' +
+        'pass --goldens-dir or set $PHRONESIS_INSTALL.',
+    };
+  }
+
+  const newIdentity = computeEvalIdentity({
+    corpus: corpus.identity ?? corpus.corpus ?? '',
+    rubric,
+    registry: registrySection,
+    runnerProtocolVersion,
+    judgePin,
+  });
+
+  // Run the substrate k times under the proposed pin; flatten k × goldens per-run results.
+  const { skill: parsedSkill, promptBody } = parseSkillSource({ name: skill, source, declaredVersion: currentVersion });
+  const expectedIds = expectedGoldenIds(goldens);
+  const perRun = [];
+  for (let i = 0; i < k; i += 1) {
+    const results = await runCandidates({
+      goldens,
+      skill: parsedSkill,
+      promptBody,
+      modelId: pin.modelId,
+      judge,
+      // Pass the judge model AND the exact rubric bytes the identity was hashed from, so
+      // "the scores were produced under THIS judge + THIS rubric" is an enforced invariant,
+      // not a coincidence of two independent disk reads (the substrate would otherwise
+      // default judge.py to sonnet and re-read the rubric from its own repo root).
+      judgeOptions: { model: judgeModel, rubricText: rubric },
+      activeDomain,
+      now,
+    });
+    // Verify the substrate returned EXACTLY one result per golden — no missing, duplicate,
+    // or extraneous golden id. A partial substrate failure that silently dropped a hard
+    // golden would let the floor aggregate only the survivors (a false green); the gate
+    // floors on the worst case, so a dropped worst case is the most dangerous loss.
+    const mismatch = goldenResultMismatch(expectedIds, results);
+    if (mismatch) {
+      return {
+        skill,
+        pin: pin.raw,
+        from_pin: currentPin,
+        corpus_signed: corpusSigned,
+        gate_status: gateStatus,
+        status: 'blocked',
+        reason: 'incomplete-results',
+        message:
+          `substrate run ${i + 1}/${k} ${mismatch} — the gate requires exactly one result per ` +
+          `corpus golden (${expectedIds.length}). A dropped, duplicated, or malformed result would let the ` +
+          'floor aggregate only the survivors. Re-run the gate; if it persists the substrate needs attention.',
+      };
+    }
+    perRun.push(...results);
+  }
+
+  // A non-`completed` substrate run (max_turns_exceeded / error / a malformed result with
+  // no loop) is an infrastructure failure, not a candidate — its partial trace + any
+  // truncated scores must NEVER fold into a release decision. The reliability protocol
+  // floors on the worst run, and a crashed run is the worst: hard-block, name the count.
+  const incomplete = perRun.filter((r) => !r || !r.loop || r.loop.outcome !== 'completed');
+  if (incomplete.length) {
+    const outcomes = [...new Set(incomplete.map((r) => r?.loop?.outcome || 'malformed'))];
+    return {
+      skill,
+      pin: pin.raw,
+      from_pin: currentPin,
+      corpus_signed: corpusSigned,
+      gate_status: gateStatus,
+      status: 'blocked',
+      reason: 'incomplete-runs',
+      message:
+        `${incomplete.length}/${perRun.length} candidate run(s) did not complete (${outcomes.join(', ')}) — ` +
+        'an errored or truncated run cannot count toward a release decision. Re-run the gate; ' +
+        'if it persists the substrate or credentials need attention.',
+    };
+  }
+
+  const aggregate = aggregateFloor(perRun, { qualityFloor, coverageFloor });
+
+  // Serialize the PINS read → decide → write critical section under a per-skill lock so two
+  // concurrent bumps of the same skill cannot interleave their read-modify-write and lose a
+  // record. Release it on EVERY exit path (finally), refusal or pass alike.
+  const lock = await acquireSkillLock(skillDir);
+  if (lock.error) {
+    return {
+      skill,
+      pin: pin.raw,
+      from_pin: currentPin,
+      corpus_signed: corpusSigned,
+      gate_status: gateStatus,
+      status: 'blocked',
+      reason: 'locked',
+      message: lock.error,
+    };
+  }
+  try {
+    const pinsPath = join(skillDir, 'evals', 'PINS.md');
+    const pinsText = existsSync(pinsPath) ? await readFile(pinsPath, 'utf8') : '';
+    const { records } = parsePins(pinsText);
+    const baseline = currentBaseline(records);
+
+    const verdict = decideBump({ mode, baseline, aggregate, newIdentity, qualityFloor, coverageFloor });
+    const scores = floorScores(aggregate);
+    const component = shapeChange ? 'major' : 'minor';
+
+    const base = {
+      skill,
+      pin: pin.raw,
+      from_pin: currentPin,
+      current_version: currentVersion,
+      corpus_signed: corpusSigned,
+      gate_status: gateStatus,
+      coverage_asserted: aggregate.coverage.asserted,
+      aggregate,
+      verdict,
+    };
+
+    // --- Refusals / hard blocks (never bypassable, never write) ---------------
+    if (verdict.status === 'refused-drift') {
+      return {
+        ...base,
+        status: 'refused',
+        reason: 'evaluation-identity drift',
+        drift: verdict.drift,
+        message:
+          `evaluation identity drifted (${verdict.drift.join(', ')}) since the baseline pin — ` +
+          'the floor comparison is invalid (a changed corpus/rubric/registry/runner/judge could mask a real ' +
+          'regression). Re-run with --rebaseline to reset the comparison basis under the new identity.',
+      };
+    }
+    if (verdict.status === 'blocked-fabrication') {
+      return {
+        ...base,
+        status: 'blocked',
+        reason: 'fabrication',
+        message:
+          `the candidate fabricated ${verdict.fabrications} unwarranted capture(s) (coverage anti-fabrication ` +
+          'rule, eval-discipline.md) — a signal-integrity failure, not a regression. --accept-regression cannot ' +
+          'override it; fix the skill.',
+      };
+    }
+    if (verdict.status === 'blocked-absolute') {
+      const axes = [...new Set(verdict.absolute.failures.map((f) => f.axis))];
+      const seedContext = !baseline || mode === 'rebaseline';
+      const bar = [
+        axes.includes('quality') ? `quality ≥ ${qualityFloor} on every criterion` : null,
+        axes.includes('coverage') ? `coverage hit-rate ≥ ${coverageFloor}` : null,
+      ].filter(Boolean).join(' AND ');
+      return {
+        ...base,
+        status: 'blocked',
+        reason: seedContext ? (mode === 'rebaseline' ? 'rebaseline absolute floor' : 'first-bump absolute floor') : 'below absolute floor',
+        absolute: verdict.absolute,
+        message:
+          `the absolute floor was not met on the ${axes.join(' + ')} axis (${bar}). ` +
+          'The absolute floor is a hard block on BOTH axes — --accept-regression overrides a relative dip ' +
+          'that stays above the floor, never a skill that fell below it. Not bypassable.',
+      };
+    }
+    if (verdict.status === 'blocked-empty') {
+      return { ...base, status: 'blocked', reason: 'empty', message: verdict.detail };
+    }
+
+    // --- Regression: blocked unless --accept-regression -----------------------
+    if (verdict.status === 'regression' && !acceptRegression) {
+      return {
+        ...base,
+        status: 'blocked',
+        reason: 'regression',
+        regressed: verdict.regressed,
+        message:
+          'a regression on ' + [...new Set(verdict.regressed.map((r) => r.axis))].join(' + ') +
+          ' vs the accepted pin blocks the bump. Override with --accept-regression (logs a structured ' +
+          'override record to PINS.md) only if the regression is acceptable.',
+      };
+    }
+
+    // --- Pass / override / rebaseline: write pin + version + PINS record -------
+    const newVersion = bumpVersion(currentVersion, component);
+    const kind = mode === 'rebaseline' ? 'rebaseline' : verdict.status === 'regression' ? 'override' : 'baseline';
+
+    const record = {
+      pin: pin.raw,
+      version: newVersion,
+      kind,
+      accepted_by: acceptedBy,
+      accepted_at: (now || new Date()).toISOString(),
+      scores,
+      identity: newIdentity,
+    };
+    if (kind === 'override') {
+      record.from_pin = currentPin;
+      record.regressed_axis = verdict.regressed;
+      record.rationale = rationale;
+    }
+    if (kind === 'rebaseline') {
+      record.from_pin = currentPin;
+      record.identity_before = baseline ? baseline.identity : null;
+      record.rationale = rationale;
+    }
+
+    // Write the PINS baseline record BEFORE the SKILL.md pin mutation, each write ATOMIC
+    // (temp + rename — a crash can never leave a torn file). If the SKILL write still fails,
+    // the safe residue is an orphan baseline (recoverable — the next bump re-measures the
+    // same body and re-passes) rather than a pinned skill with no baseline (which the next
+    // bump would mistake for a first bump and re-seed without a regression check — a
+    // silent-regression hole).
+    const newSource = rewriteSkillFrontmatter(source, { pin: pin.raw, version: newVersion });
+    await atomicWrite(pinsPath, appendPinsRecord(pinsText, record));
+    try {
+      await atomicWrite(skillPath, newSource);
+    } catch (err) {
+      return {
+        ...base,
+        status: 'error',
+        reason: 'pin-write-failed',
+        record,
+        written: { pins: pinsPath },
+        message:
+          `the PINS.md baseline for ${pin.raw} was recorded, but writing the pin to ${skillPath} failed ` +
+          `(${err.message}). Re-run the bump to complete it — the skill body is unchanged, so it will re-pass.`,
+      };
+    }
+
+    const coverageNote = !aggregate.coverage.asserted
+      ? ' [coverage axis not exercised — no warranted captures in the corpus]'
+      : coverageFloor === 0
+        ? ' [coverage floor 0 — coverage regressions are disabled for this baseline]'
+        : '';
+    return {
+      ...base,
+      status: 'ok',
+      kind,
+      version: newVersion,
+      record,
+      written: { skill: skillPath, pins: pinsPath },
+      message:
+        kind === 'override'
+          ? `bumped ${skill} to ${pin.raw} (v${newVersion}) — REGRESSION ACCEPTED; override recorded in PINS.md${coverageNote}`
+          : kind === 'rebaseline'
+            ? `rebaselined ${skill} to ${pin.raw} (v${newVersion}) under the new evaluation identity${coverageNote}`
+            : `bumped ${skill} to ${pin.raw} (v${newVersion}); baseline recorded in PINS.md` +
+              (corpusSigned ? '' : ' [provisional — corpus unsigned]') + coverageNote,
+    };
+  } finally {
+    await rm(lock.path, { force: true });
+  }
+}