bareloop 0.10.0 → 0.12.0

package/src/kinds.js

@@ -64,8 +64,9 @@ import { realpathSync } from 'node:fs';
 import { readFile, stat, mkdtemp, rm, symlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, sep } from 'node:path';
-import { globToPrefix } from './validate.js';
+import { globToPrefix, isNonEmptyString } from './validate.js';
 import { CLOSE_ENV_DENY } from './ralph.js';
+import { runLocate, decide, validateCard, LOCATE_AXES, LOCATE_LABEL, JUDGE_MODEL } from './judged.js';
 
 /** the close's two judgment exits — a stage's verdict, in the shape the
  * hand-written closes already spoke (exit code is truth) */
@@ -132,23 +133,163 @@ export const STOP_FAULTS = Object.freeze({
 
 export const AGGREGATES = Object.freeze(['first', 'sum']);
 export const SIGNS = Object.freeze([1, -1]);
-/** every kind this executor implements. `judged-floor` / `human-confirms`
- * are catalogue entries and are deliberately absent here: declaring one is
- * counted demand (the request-red path), and reaching one at runtime is a
- * stop — never a red, and never a silent pass. */
-export const LIVE_KINDS = Object.freeze(['command-exit', 'count-not-worse', 'pattern-absent-in-diff', 'files-changed']);
+/** every kind this executor implements. It is asserted EQUAL to the catalogue's
+ * own live half by the suite, both directions: a kind the catalogue offers and
+ * this executor cannot run is a close that stops at runtime, and a kind this
+ * executor runs that the catalogue never names is a capability nothing can
+ * reach. `judged-floor` joined at softgreen module 2 — the runner and the
+ * catalogue unlock in ONE commit for exactly that reason. */
+export const LIVE_KINDS = Object.freeze(['command-exit', 'count-not-worse', 'pattern-absent-in-diff', 'files-changed', 'human-confirms', 'judged-floor']);
+/**
+ * The judged stage's ladder: ONE attempt plus ONE retry, and no more.
+ *
+ * The POC measured a malformed emission roughly 1 in 6, which is exactly the
+ * shape a single retry buys down and a longer ladder buys nothing more of — each
+ * further attempt is another paid call against the same unchanged artifact and
+ * the same unchanged prompt. It is a CEILING the arbiter owns, never a knob a
+ * declaration can widen: a stage that could re-ask a model forever is a stage
+ * that can spend a budget without ever rendering a verdict.
+ *
+ * A `pricing-red` is never retried at all (see `runJudgedFloor`): a retry of an
+ * unpriced call only buys more spend nobody can see (F6).
+ */
+export const JUDGE_ATTEMPTS = 2;
+/**
+ * The ceiling on how many artifacts ONE judged stage may buy a judgement of —
+ * the sibling of `MAX_TERMS` and `MAX_STAGES`, and here for the same reason: a
+ * runaway list is a bill, not a red. Enforced by the catalogue's validator
+ * before any token, so a declaration that names more is refused at the gate
+ * rather than discovered at the invoice.
+ */
+export const MAX_JUDGED_PATHS = 8;
+/** RULING 8 — the stages the seed-verdict read (D12) must NOT run. A judged
+ * number at seed is unstable and a person at seed is an interview, not a
+ * measurement; their bar comes from calibration (soft-green) or from the person
+ * themselves (hitl), never from the seed. The skip is RECORDED by name rather
+ * than taken in silence (F59: absent is not empty), so `seedRead` still returns
+ * one row per declared stage. */
+/** the one kind a MODEL renders. Named once for the same reason `HUMAN_KIND` is:
+ * the authoring pipeline, the card, the catalogue and the close each key a
+ * decision on it, and five literals is how they come to disagree. */
+export const JUDGED_FLOOR_KIND = 'judged-floor';
+export const SEED_EXEMPT_KINDS = Object.freeze([JUDGED_FLOOR_KIND, 'human-confirms']);
+/** the one kind a PERSON renders — named once, because the runner keys three
+ * decisions on it (is there a door to answer, which stage paused, whose ruling
+ * this is) and three literals is how they come to disagree */
+export const HUMAN_KIND = 'human-confirms';
+/** the three doors the signer is offered at a hitl pause (2026-08-12 §1, doors
+ * re-cut 2026-08-17). No fourth door, and no free-text-only variant: a red that
+ * is not one of these two is not a ruling the run can act on.
+ *
+ * `cancel` was the third door and is DELETED as a concept (hamr: *"what's the
+ * point of cancel anyways? pause can resume — that would be more honest"*). The
+ * case it served — a person who looks and does not want to carry on — is a pause
+ * nobody returns to, which the 60-day checkpoint TTL retires on its own. Nothing
+ * here forces a forever-decision at the one moment the person has least reason
+ * to make one. */
+export const HUMAN_DECISIONS = Object.freeze(['accept', 'rerun', 'pause']);
+
+// ── THE REVIEW DOOR's vocabulary (softgreen module 8, PRD v1.71 §3) ──────────
+//
+// The pause machinery re-homed: the same three doors, one level out — from a
+// stage INSIDE the close to the door at the END of a run. The vocabulary lives
+// here, beside the doors themselves, because `src/planrun.js` needs it to OPEN a
+// door and `src/reviewdoor.js` needs it to ANSWER one, and a constant imported
+// through the answering module would drag the registry (and `runJob` behind it)
+// into the run's own import graph.
+
+/** the door's record type on the spine. It is a DISPOSITION, never a verdict:
+ * hamr's law, verbatim — *"it's important not to change the loop self verdict"*.
+ * The close mints the verdict before this is written, and nothing downstream of
+ * this record may change what the ledger recorded. */
+export const REVIEW_DOOR = 'review-door';
+
+/** the terminals a door opens on: the verdict-bearing ones, and only those. A red,
+ * a casualty and a governance halt are not offered to a person as merchandise —
+ * they are already decision-ready in their own right, with their own levers. */
+export const DOOR_OPEN_OUTCOMES = Object.freeze(['green', 'already-green']);
+
+/** the classes whose door opens WITHOUT being asked for. Soft-green is here
+ * because the judge is young: its green is quarantined at mint (module 6) and a
+ * person's `accept` is the only thing that releases the credit, so a run that
+ * never offered the door would hold its own credit forever.
+ *
+ * `green` is deliberately ABSENT, and that is the one operator-facing default in
+ * this module: a green-class run behaves exactly as it always has unless the
+ * runner asks for the door (`reviewDoor: true`, `--review-door`). PRD v1.71 §3
+ * says *"the door at the end of EVERY run"* and also that a green door is
+ * NON-BLOCKING, and the two readings differ only in whether an unasked-for door
+ * appears on an existing job's spine. Flipping it is one line — adding `'green'`
+ * here — and it is hamr's to flip, not this module's to assume. A constant, never
+ * a threshold; widening it is arbiter territory. */
+export const REVIEW_DOOR_CLASSES = Object.freeze(['soft-green']);
+
+/**
+ * Does this run end at a review door? The operator's flag WINS in both
+ * directions and is never inferred: `true` opens it for any class, `false` shuts
+ * it for any class, and `null`/absent is the class default above.
+ * @param {any} job the signed spec (its `verdictType` is the class)
+ * @param {boolean|null} [reviewDoor] the operator's explicit choice, or null
+ * @returns {boolean}
+ */
+export function doorOpens(job, reviewDoor = null) {
+  if (reviewDoor === true) return true;
+  if (reviewDoor === false) return false;
+  return REVIEW_DOOR_CLASSES.includes(job?.verdictType ?? 'green');
+}
+
+/**
+ * The stages an `accept` re-runs: the MECHANICAL ones, and never a judged floor
+ * or a person (`SEED_EXEMPT_KINDS`, ruling 8's set, for the same reason it was
+ * drawn — a machine may re-prove a machine's reading, and may not re-prove a
+ * judgment). hamr's N4 ruling: an accept re-runs the mechanical stages, because a
+ * door lives 60 days and nothing freezes a tree.
+ * @param {any[]|null|undefined} stages
+ * @returns {any[]}
+ */
+export function mechanicalStages(stages) {
+  return (Array.isArray(stages) ? stages : []).filter((s) => !SEED_EXEMPT_KINDS.includes(s?.kind));
+}
 
 /**
  * @typedef {{code: string, path: string, detail: string}} Red
  * @typedef {{workdir: string, seedRef: string, gapKeep: string,
  *   timeoutMsDefault?: number, baselineMode?: 'auto'|'worktree',
- *   gapCap?: number, maxBuffer?: number, seedTrees?: SeedTrees}} Ctx
+ *   gapCap?: number, maxBuffer?: number, seedTrees?: SeedTrees,
+ *   humanRuling?: {decision: string, text?: string|null}|null,
+ *   judgeLoop?: (o: {system: string}) => any,
+ *   onJudgeCost?: (c: {stage: string|null, kind: string|null, path: string, attempt: number,
+ *     label: string, model: string, costUsd: number|null, unpricedRounds: number}) => void,
+ *   onStage?: (row: {stage: string|null, kind: string|null, verdict: string, durationMs: number}) => void}} Ctx
  *   The arbiter's half of a stage run. Every field here is operator/runner
  *   territory: a declaration parameterises kinds, never the contracts.
- * @typedef {{verdict: 'green'|'red'|'instrument-stop'|'not-reached',
+ *   `humanRuling` is the SIGNER's answer at a hitl pause, carried in from the
+ *   runner — never authored, never defaulted, and absent on every ordinary run.
+ *   `judgeLoop` is the PAID seam the judged stage runs its locate call through, and
+ *   it is operator territory for the same reason the worker's provider is: this
+ *   module owns no provider and never picks one, and the judge tier is PINNED
+ *   (`JUDGE_MODEL`) rather than chosen. Absent is not a fall-back to some other
+ *   model — the stage stops as a wiring gap, the same answer `runPlan` gives a
+ *   native job with no native factory.
+ *   `onJudgeCost` is the METER, and it is the only reason a judged stage can be
+ *   funded honestly: this executor cannot reach the run's ledger, so every locate
+ *   call's cost is reported OUT through it, once per call, on every route including
+ *   the red ones — a paid call that leaves no meter record is F12 in a judge's coat.
+ *   `onStage` is a REPORTING seam and nothing else: the seed read spawns a real
+ *   toolchain per stage (a suite is the slow one) and a whole read is one opaque
+ *   await, so the shell gets told as each stage lands. It decides nothing, it is
+ *   never consulted, and no verdict depends on it — the house pattern is
+ *   `runJob`'s `emit` (the library reports, the shell prints).
+ * @typedef {{verdict: 'green'|'red'|'instrument-stop'|'not-reached'|'pause'|'skipped',
  *   exitCode: number|null, value: number|null, baseline: number|null,
  *   baselineSource: string|null, gapLines: string[], judged: boolean,
  *   stage: string|null, kind: string|null, detail: Record<string, any>}} StageResult
+ *   Six outcomes, and only two of them are verdicts. `pause` is N4's fifth: the
+ *   close reached a stage a machine cannot render and is WAITING on a person —
+ *   neither green nor red, and never graded (the F17 forbidden-zone rule applied
+ *   to a non-verdict). `skipped` is the sixth and says a stage was deliberately
+ *   not run at THIS reading (ruling 8's seed exemption), which is a different
+ *   fact from `not-reached` (an earlier stage decided first).
  * @typedef {{ensure: (workdir: string, seedRef: string) => Promise<{stop: string, fault: string}|{stop: null, dir: string}>,
  *   cleanup: () => Promise<{ok: boolean, leaked: string[], detail: string|null}>}} SeedTrees
  */
@@ -1323,12 +1464,397 @@ async function runFilesChanged(stage, ctx) {
   });
 }
 
+/**
+ * THE SIGNER'S ANSWER, normalised at the seam that accepts it — the library half
+ * of the three-button gate (2026-08-12 §1).
+ *
+ * `null` is not a refusal: no ruling at all IS the pause path, which is how every
+ * ordinary run and every first leg of a hitl run arrives here. What is refused is
+ * an answer that is not one of the three doors, and — the case the POC's negative
+ * control measured — a `rerun` with no text. Ruling 3 makes the human's words the
+ * gap the worker converts from; an empty one launches a fix worker that re-runs
+ * as though nothing had been said, which is the failure this refusal exists for.
+ *
+ * It never throws and never repairs: a decision that cannot be read is handed
+ * back as a refusal with its reason, and the caller decides what to do about it.
+ * @param {any} ruling
+ * @returns {{ok: boolean, ruling: {decision: string, text: string|null}|null, why: string|null}}
+ */
+export function normalizeHumanRuling(ruling) {
+  if (ruling === null || ruling === undefined) return { ok: true, ruling: null, why: null };
+  if (typeof ruling !== 'object' || Array.isArray(ruling)) {
+    return { ok: false, ruling: null, why: `a decision is an object {decision, text?} — one of ${HUMAN_DECISIONS.join(' | ')}` };
+  }
+  const decision = String(/** @type {any} */ (ruling).decision);
+  if (!HUMAN_DECISIONS.includes(decision)) {
+    return {
+      ok: false,
+      ruling: null,
+      why: `"${decision}" is not one of the three doors (${HUMAN_DECISIONS.join(' | ')}). There is no fourth, and no `
+        + 'free-text-only variant: a red that is not one of these two is not a ruling the run can act on',
+    };
+  }
+  const text = /** @type {any} */ (ruling).text;
+  if (decision === 'rerun') {
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      return {
+        ok: false,
+        ruling: null,
+        why: 'a "rerun" decision needs TEXT: the human is the gap author (ruling 3), and their words are the whole of '
+          + 'what the fix worker is given. An empty gap re-runs the worker as though nothing had been said',
+      };
+    }
+    return { ok: true, ruling: { decision, text }, why: null };
+  }
+  return { ok: true, ruling: { decision, text: null }, why: null };
+}
+
+/**
+ * WHICH ANSWER IS THIS LEG ACTING ON — the fresh one, or the one the checkpoint
+ * held? F102's cure needs one seam that can say, because two callers ask the same
+ * question (`runJob` declares the fold on `job-start` before `runPlan` reads the
+ * ruling at all), and two spellings of "is this a fresh engagement" is how the
+ * record and the clock come to disagree about the same leg.
+ *
+ * THE AMBIGUITY IS REFUSED, NEVER MERGED. A checkpoint that holds a decision and a
+ * command line that carries another are two answers to one question. Merging them
+ * picks a winner nobody chose; overriding silently discards words a person typed
+ * (the F98/F28 class at a process boundary). So it comes back as a refusal that
+ * NAMES the held decision, and the operator resolves it — by answering the held
+ * one, or by starting a fresh run against the tree as it stands.
+ *
+ * `fresh` is F103's half: a `rerun` is a FRESH ENGAGEMENT (design record §3.4 —
+ * *"redo/rerun comes with new authoring for money+time and keeps accounting of
+ * this far and this session separate counters"*), and nothing else is. An `accept`
+ * commissions no work and a `pause` runs nothing, so neither opens one.
+ *
+ * A REVIEW DOOR's rerun (module 8) is the SAME fact arriving one level out, and it
+ * is folded in here rather than beside the clock, because "is this a fresh
+ * engagement" gets ONE spelling — a second one is how a record and a clock come to
+ * disagree about the same leg, which is the very thing this resolver exists to
+ * prevent. It is deliberately NOT read as a ruling: a `humanRuling` answers a
+ * close's human STAGE and is refused for a close that has none, so the door's words
+ * stay in their own parameter and only this reading is shared.
+ *
+ * PRECEDENCE, stated because both CAN be handed to one leg: a door rerun makes the
+ * engagement fresh whatever the ruling says, and the two are OR'd, never merged.
+ * Freshness is the FAIL-SAFE direction — a fresh clock costs a leg nothing, while
+ * inheriting a dead leg's wall is F103's measured, structurally-impossible
+ * engagement. The door's own validation (empty words are refused) stays where it
+ * is, at the seam that accepts it.
+ * @param {any} fresh the answer arriving on this invocation (`--decide`), or null
+ * @param {any} held the answer the CHECKPOINT carries (`readResume`'s
+ *   `restart.pendingDecision`), or null. `receivedAt` is when the PERSON said it —
+ *   carried through so the resumed leg records the receipt, not its own re-reading.
+ * @param {any} [doorRerun] MODULE 8 — the review door's rerun, when this leg IS the
+ *   fresh engagement a signer commissioned at a previous run's door. Presence is the
+ *   whole of what is read here; the words are the accepting seam's business.
+ * @returns {{ok: boolean, why: string|null, ruling: {decision: string, text: string|null}|null,
+ *   source: 'operator'|'checkpoint'|null, receivedAt: string|null, fresh: boolean}}
+ */
+export function resolveHumanRuling(fresh, held, doorRerun = null) {
+  const has = (/** @type {any} */ v) => v !== null && v !== undefined;
+  const atDoor = has(doorRerun);
+  const none = { ruling: null, source: /** @type {any} */ (null), receivedAt: null, fresh: atDoor };
+  if (has(fresh) && has(held)) {
+    const d = typeof held === 'object' && !Array.isArray(held) ? String(/** @type {any} */ (held).decision) : String(held);
+    return {
+      ok: false,
+      why: `this checkpoint already holds a "${d}" decision that no round was ever bought for, and a second answer `
+        + 'arrived with this invocation. Two answers to one question is ambiguity, not a merge: resume with no '
+        + 'decision to act on the held one, or start a fresh run against the tree as it stands.',
+      ...none,
+    };
+  }
+  const raw = has(fresh) ? fresh : held;
+  const norm = normalizeHumanRuling(raw ?? null);
+  if (!norm.ok) return { ok: false, why: norm.why, ...none };
+  if (norm.ruling === null) return { ok: true, why: null, ...none };
+  const at = has(held) ? /** @type {any} */ (held).receivedAt : null;
+  return {
+    ok: true,
+    why: null,
+    ruling: norm.ruling,
+    source: has(fresh) ? 'operator' : 'checkpoint',
+    receivedAt: typeof at === 'string' && at.length > 0 ? at : null,
+    // OR'd, never merged: either door the person came through commissions work
+    fresh: atDoor || norm.ruling.decision === 'rerun',
+  };
+}
+
+/**
+ * THE HUMAN STAGE (N4 slice 1) — the one kind that measures nothing.
+ *
+ * With no ruling in hand it does not RUN, it PAUSES: the fifth outcome, neither
+ * green nor red, so nothing downstream grades it. With the signer's ruling in
+ * hand it renders exactly what the person said — `accept` is a green a PERSON
+ * judged, and `rerun` is a red whose gap is the human's own words, verbatim,
+ * through the same bounded/announced channel every other stage's gap uses.
+ *
+ * It spawns nothing, reads nothing and touches no tree, which is why it can
+ * render both without a workdir that exists.
+ *
+ * `pause` is deliberately NOT a case here. It is not a judgment about the tree
+ * — it is the signer saying "not now" — and it is consumed above this stage, by
+ * the runner and by `runPlan` before the close is ever asked (a `pause` that
+ * reached this far has bypassed that seam, so it renders NO verdict rather than
+ * being guessed into one). With no ruling in hand this kind pauses anyway, which
+ * is the same place the person is left; what the door adds is the RECORD that
+ * they looked and chose to keep the checkpoint.
+ * @param {any} stage @param {Ctx} ctx @returns {Promise<StageResult>}
+ */
+async function runHumanConfirms(stage, ctx) {
+  const ask = stage?.params?.ask;
+  const norm = normalizeHumanRuling(ctx.humanRuling ?? null);
+  if (!norm.ok) {
+    return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" was handed a decision it cannot read — ${norm.why}`,
+      {}, STOP_FAULTS.CRASHED);
+  }
+  if (norm.ruling === null) {
+    // THE PAUSE. `judged: false` and `exitCode: null` together are the whole
+    // contract: nothing was measured and no process ran, so a zero here would be
+    // F6 in an exit code's coat.
+    return result(stage, {
+      verdict: 'pause',
+      exitCode: null,
+      judged: false,
+      detail: { ask: isNonEmptyString(ask) ? ask : null },
+    });
+  }
+  if (norm.ruling.decision === 'accept') {
+    return result(stage, { verdict: 'green', exitCode: EXIT_GREEN, judged: true, detail: { ask: ask ?? null, decision: 'accept' } });
+  }
+  if (norm.ruling.decision === 'rerun') {
+    const gap = new Gap(ctx.gapKeep, ctx.gapCap);
+    gap.push(`${stage.name}: the signer reviewed the result and asked for another pass. Their words:`);
+    gap.push(/** @type {string} */ (norm.ruling.text));
+    return result(stage, {
+      verdict: 'red',
+      exitCode: EXIT_RED,
+      judged: true,
+      gapLines: gap.render(),
+      detail: { ask: ask ?? null, decision: 'rerun' },
+    });
+  }
+  return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" was handed a "${norm.ruling.decision}" decision, which `
+    + 'is the signer ending the run and is never a verdict about the tree — the runner consumes it before the close',
+  {}, STOP_FAULTS.CRASHED);
+}
+
+/**
+ * THE JUDGED FLOOR (softgreen module 2) — the one kind that BUYS its measurement.
+ *
+ * It is `src/judged.js`'s two halves wired into the close, and the split is the
+ * whole safety argument: LOCATE is a pinned, toolless model asked for facts with
+ * addresses over the AUTHORITATIVE artifact, and DECIDE is a pure arbiter-owned
+ * function with no model in it. The judge never renders a verdict; this runner
+ * renders it, from an owned rulebook, over quotes the artifact must contain.
+ *
+ * FOUR ROUTES OUT, and which is which is the load-bearing part:
+ *
+ *   - GREEN / RED come from `decide()` alone. A red is CONTENT — facts in hand,
+ *     and a card item those facts do not satisfy (or cannot be sure about, since
+ *     unsure is red). That is evidence about the tree.
+ *   - AN INSTRUMENT STOP is everything else: a card this arbiter cannot read, an
+ *     artifact that will not open, no judge seam wired, and — after the ladder —
+ *     a judge whose emission never parsed or whose call never came back.
+ *     Contract (a) names "unreadable or unparseable required output" as a stop in
+ *     so many words, and the reason is the casualty rule: our judge producing
+ *     garbage says nothing whatsoever about the worker, and grading a tree red on
+ *     it would be manufactured evidence (F45).
+ *   - A `pricing-red` locate is that same stop with the retry REFUSED: an
+ *     unpriced call cannot be summed, and buying a second one only adds more
+ *     spend nobody can see (F6).
+ *
+ * The gap is ITEMIZED (ruling 7, F38/F39): named card items, per-file, with the
+ * function names and the instrument's own quotes — never one paragraph. It rides
+ * the same `Gap` bound as every other kind, so the trim is announced.
+ *
+ * EVERY path is judged, not just up to the first red, for the same reason
+ * `decide()` grades every item: calibration reads itemized reds, and a stage that
+ * short-circuits reports the first thing it found rather than what is true.
+ * `firstRed` still names the deciding item in DECLARED order, so the verdict's
+ * reason is stable against whatever order a model emitted anything in.
+ *
+ * NOT WIRED, AND NAMED RATHER THAN SILENTLY SKIPPED — `judgeToAnnotation` →
+ * `gate.annotate` (the slice-2 obligation list, item 4). Two independent reasons,
+ * either of which alone would defer it:
+ *   (1) THE ADAPTER TAKES A VERDICT. bare-agent's `judgeToAnnotation` maps a
+ *       `judge()` verdict (`{verdict, where:{field, stated, returned}}`) onto the
+ *       annotation shape, and this pipe deliberately never buys a verdict from a
+ *       model — LOCATE returns facts, and the verdict is `decide()`'s. Feeding it
+ *       a synthesised verdict would annotate the gate with a judgement no judge
+ *       made, which is the one thing the locate-not-verdict split exists to stop.
+ *   (2) THERE IS NO GATE HERE. A Gate is built per WORKER step (`mkWorker`,
+ *       src/planrun.js) and is gone by the time the close runs; the close is
+ *       deliberately outside every worker's fence. Annotating "the arbiter's own
+ *       gate" needs a run-scoped gate that does not exist today, and inventing
+ *       one to carry an annotation would be plumbing built for its own sake.
+ * The facts themselves are NOT lost meanwhile: every per-path reading (verdict,
+ * itemized reds, the ladder, the scrubbed raw) rides `detail.perPath`.
+ * @param {any} stage @param {Ctx} ctx @returns {Promise<StageResult>}
+ */
+async function runJudgedFloor(stage, ctx) {
+  const p = stage.params;
+  // 1. the CARD, through the one spelling (`validateCard`). A card this arbiter
+  //    cannot read is a broken close, never a red about the tree — and it is
+  //    checked before the seam and before the artifact, because it costs nothing.
+  const cv = validateCard(p?.card);
+  if (!cv.ok) {
+    return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" carries a rubric card this arbiter cannot read: ${cv.reds.join('; ')}`,
+      {}, STOP_FAULTS.CRASHED);
+  }
+  const paths = Array.isArray(p?.paths) ? p.paths.filter(isNonEmptyString) : [];
+  if (paths.length === 0) {
+    return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" names no artifact to judge — a judged stage with no `
+      + 'paths judges nothing, and nothing is not a pass', {}, STOP_FAULTS.CRASHED);
+  }
+  if (paths.length > MAX_JUDGED_PATHS) {
+    return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" names ${paths.length} artifacts, over the ceiling of `
+      + `${MAX_JUDGED_PATHS} — a judged stage buys one call per artifact, and a runaway list is a bill`, {}, STOP_FAULTS.CRASHED);
+  }
+  // 1b. THE TIER THE SIGNED SET WAS GRADED BY, against the tier this run would buy.
+  //     `JUDGE_MODEL` has always SAID a bump forces a full recalibration; this is the
+  //     detector, because a rule with no wired detector is prose (F45). The stamp comes
+  //     off the SIGNED calibration (`calibration.judgeModel`, carried across by
+  //     `declaredStages`), so a mismatch means exactly one thing: the pin moved under a
+  //     signature, and the floor standing behind this stage was certified by a model
+  //     nobody is about to call. That is a FAILED wiring gap and not a crash — the same
+  //     fault, and for the same reason, as the absent seam below: nothing is broken,
+  //     something was never re-done. It stops rather than degrading in either direction,
+  //     because grading on the new tier would mint a verdict against an uncalibrated
+  //     floor and grading on the old one is not on offer (the pin is a constant).
+  //     AN ABSENT STAMP IS NOT CHECKED HERE, deliberately and for the reason the SET's
+  //     own presence is not checked in `validateCloseDecl`: a spec that judges cannot
+  //     reach a run without a calibration (the signing gate, module 5) or without a
+  //     model on it (`validateCloseDecl`), so the runtime question is only ever WHICH
+  //     model — and a stage descriptor handed straight to `runStage` by an adopter or a
+  //     test is not a signed spec making a claim about a tier.
+  if (isNonEmptyString(stage.calibrationJudgeModel) && stage.calibrationJudgeModel !== JUDGE_MODEL) {
+    return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" would grade with ${JUDGE_MODEL}, and the calibration `
+      + `set signed with this close was graded by ${stage.calibrationJudgeModel} — the judge tier moved under the `
+      + 'signature. A floor is worth exactly the judge that certified it, so this stops rather than grading against a '
+      + 'floor nobody calibrated: re-sign the spec with the new tier and re-run the calibration gate (recalibrate)',
+    { signedJudgeModel: stage.calibrationJudgeModel, judgeModel: JUDGE_MODEL }, STOP_FAULTS.FAILED);
+  }
+  if (typeof ctx.judgeLoop !== 'function') {
+    return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" is a judged stage and this run wired no judge seam `
+      + `(ctx.judgeLoop) — an adopter wiring gap, never a silent fall-back: the judge is ${JUDGE_MODEL}, pinned, and a `
+      + 'stage that quietly graded on whatever model was lying around would be a floor nobody calibrated',
+    {}, STOP_FAULTS.FAILED);
+  }
+  const loopFactory = /** @type {(o: {system: string}) => any} */ (ctx.judgeLoop);
+
+  const gap = new Gap(ctx.gapKeep, ctx.gapCap);
+  /** @type {any[]} */
+  const perPath = [];
+  /** @type {{path: string, rule: string, text: string, reds: any[]}[]} */
+  const redItems = [];
+  /** the reds that name NO card item: `decide()`'s unsure routes (no usable facts,
+   * an empty function list). They are the fail-safe itself, so the verdict is read
+   * off the per-path verdicts and NEVER off `redItems` — a red with nothing itemized
+   * under it is exactly the shape that would otherwise fall through to green. */
+  /** @type {{path: string, reason: string}[]} */
+  const unsure = [];
+  let redFiles = 0;
+
+  for (const rel of paths) {
+    let artifactText;
+    try {
+      artifactText = await readFile(join(ctx.workdir, rel), 'utf8');
+    } catch (e) {
+      return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" could not read the artifact it judges (${rel}): `
+        + `${String(/** @type {any} */ (e)?.message ?? e)}`, { path: rel }, STOP_FAULTS.CRASHED);
+    }
+    if (artifactText.trim() === '') {
+      return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}"'s artifact ${rel} is empty — an empty artifact `
+        + 'yields no facts, and no facts is unknown, never a pass', { path: rel }, STOP_FAULTS.CRASHED);
+    }
+
+    /** @type {any} */
+    let last = null;
+    /** @type {any[]} */
+    const tries = [];
+    for (let attempt = 1; attempt <= JUDGE_ATTEMPTS; attempt += 1) {
+      last = await runLocate({
+        artifactText,
+        card: p.card,
+        loopFactory,
+        attempt,
+        onCost: (c) => {
+          if (typeof ctx.onJudgeCost !== 'function') return;
+          ctx.onJudgeCost({
+            stage: stage?.name ?? null, kind: stage?.kind ?? null, path: rel, attempt,
+            label: LOCATE_LABEL, model: JUDGE_MODEL, costUsd: c.costUsd, unpricedRounds: c.unpricedRounds,
+          });
+        },
+      });
+      tries.push({ attempt, ok: last.ok, axis: last.red?.axis ?? null, costUsd: last.costUsd, truncated: last.truncated, parseError: last.parseError });
+      if (last.ok) break;
+      // the ONE non-retryable axis, and it outranks the ladder: a retry of an
+      // unpriced call buys more spend nobody can see (F6).
+      if (last.red.axis === LOCATE_AXES.PRICING) break;
+    }
+    if (!last.ok) {
+      return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}"'s judge returned no usable facts for ${rel} after `
+        + `${tries.length} attempt(s) [${last.red.axis}]: ${last.red.detail}`,
+      { path: rel, axis: last.red.axis, attempts: tries }, STOP_FAULTS.CRASHED);
+    }
+
+    const d = decide(last.facts, p.card, { artifactText });
+    perPath.push({ path: rel, verdict: d.verdict, firstRed: d.firstRed, attempts: tries, raw: last.raw, items: d.items });
+    if (d.verdict === 'red') {
+      redFiles += 1;
+      for (const it of d.items) if (!it.ok) redItems.push({ path: rel, rule: it.rule, text: it.text, reds: it.reds });
+      if (!d.items.some((it) => !it.ok)) unsure.push({ path: rel, reason: String(d.reason ?? 'unsure, and unsure is red') });
+    }
+  }
+
+  const red = redFiles > 0;
+  if (red) {
+    // FIRST-RED-WINS in the CARD's own signed order, across every artifact: the
+    // card is the arbiter's order, and the file loop's order is the declaration's.
+    const order = p.card.items.map((/** @type {any} */ it) => it.rule);
+    const firstRed = order.find((/** @type {string} */ r) => redItems.some((x) => x.rule === r))
+      ?? (redItems[0]?.rule ?? 'unsure');
+    gap.push(`${stage.name}: the judged floor is not met — ${redItems.length} card item(s) red across ${redFiles} of `
+      + `${paths.length} artifact(s); first red: ${firstRed}`);
+    for (const u of unsure) gap.push(`  ${u.path}: ${u.reason}`);
+    for (const it of redItems) {
+      gap.push(`  [${it.rule}] ${it.text}`);
+      // the file, the function and the quote are all things the INSTRUMENT itself
+      // reported (contract (b) bars naming a culprit it did not) — and a red with
+      // no address is the semantic genre F38 measured as inert
+      for (const r of it.reds) {
+        gap.push(`    ${it.path}: ${r.fn} — ${r.why}`);
+        if (r.quote) gap.push(`      > ${String(r.quote).split('\n')[0].trim().slice(0, 200)}`);
+      }
+    }
+  }
+  return result(stage, {
+    verdict: red ? 'red' : 'green',
+    exitCode: red ? EXIT_RED : EXIT_GREEN,
+    gapLines: gap.render(),
+    detail: {
+      model: JUDGE_MODEL,
+      card: p.card.items.map((/** @type {any} */ it) => it.rule),
+      paths,
+      perPath,
+      redItems: redItems.length,
+      unsure,
+      redFiles,
+    },
+  });
+}
+
 /** @type {Record<string, (stage: any, ctx: Ctx) => Promise<StageResult>>} */
 const RUNNERS = {
   'command-exit': runCommandExit,
   'count-not-worse': runCountNotWorse,
   'pattern-absent-in-diff': runPatternAbsentInDiff,
   'files-changed': runFilesChanged,
+  'human-confirms': runHumanConfirms,
+  'judged-floor': runJudgedFloor,
 };
 
 /**
@@ -1387,10 +1913,41 @@ export async function seedRead(declaration, ctx) {
   const owned = !ctx.seedTrees;
   const seedTrees = ctx.seedTrees ?? makeSeedTrees();
   const inner = { ...ctx, seedTrees };
+  /** AFTER the stage completes, never before: a line saying a stage STARTED and
+   * a line saying what it RETURNED are two different facts, and only the second
+   * one can carry a verdict. The duration is measured around the call rather
+   * than reported by it, so a stage that stops still gets a real number.
+   * @param {StageResult} row @param {number} startedAt */
+  const told = (row, startedAt) => {
+    if (typeof ctx.onStage === 'function') {
+      ctx.onStage({ stage: row.stage, kind: row.kind, verdict: row.verdict, durationMs: Date.now() - startedAt });
+    }
+    return row;
+  };
   try {
     /** @type {StageResult[]} */
     const rows = [];
-    for (const stage of declaration?.stages ?? []) rows.push(await runStageIn(stage, inner));
+    for (const stage of declaration?.stages ?? []) {
+      // RULING 8 — judged and human stages are EXEMPT from the seed read, and
+      // the exemption is a ROW, not an absence (F59). A person asked at the seed
+      // is being interviewed, not measured, and there is nothing to baseline.
+      const startedAt = Date.now();
+      if (SEED_EXEMPT_KINDS.includes(stage?.kind)) {
+        rows.push(told(result(stage, {
+          verdict: 'skipped',
+          exitCode: null,
+          judged: false,
+          detail: {
+            skipped: true,
+            why: 'ruling 8 (2026-08-07): judged and human stages skip the seed-verdict read — a judged number at seed '
+              + 'is unstable and a person at seed is an interview, not a measurement. This stage has no seed baseline '
+              + 'and contributes none.',
+          },
+        }), startedAt));
+        continue;
+      }
+      rows.push(told(await runStageIn(stage, inner), startedAt));
+    }
     return rows;
   } finally {
     if (owned) await seedTrees.cleanup();
@@ -1412,7 +1969,7 @@ export async function seedRead(declaration, ctx) {
  * room would break a documented adopter contract for nothing; the new name says
  * exactly what differs. `src/declaredclose.js` is what bridges the two shapes.
  * @param {any} declaration @param {Ctx} ctx
- * @returns {Promise<{verdict: 'green'|'red'|'instrument-stop', exitCode: number, judged: boolean, firstRed: string|null, stages: StageResult[]}>}
+ * @returns {Promise<{verdict: 'green'|'red'|'instrument-stop'|'pause', exitCode: number|null, judged: boolean, firstRed: string|null, pausedAt: string|null, stages: StageResult[]}>}
  */
 export async function runDeclaredClose(declaration, ctx) {
   const owned = !ctx.seedTrees;
@@ -1431,12 +1988,20 @@ export async function runDeclaredClose(declaration, ctx) {
       stages.push(r);
       if (r.verdict !== 'green') ended = true;
     }
+    // A PAUSE stops the close exactly like a red does, and is DELIBERATELY not
+    // in this list: `deciding` names the stage that rendered a VERDICT, and a
+    // pause rendered none. Reading it as one would fall through to green — the
+    // close would mint a verdict nobody gave (the defect this line exists to
+    // make impossible).
     const deciding = stages.find((s) => s.verdict === 'red' || s.verdict === 'instrument-stop');
+    const paused = deciding ? null : stages.find((s) => s.verdict === 'pause') ?? null;
     return {
-      verdict: /** @type {'green'|'red'|'instrument-stop'} */ (deciding ? deciding.verdict : 'green'),
-      exitCode: deciding ? /** @type {number} */ (deciding.exitCode) : EXIT_GREEN,
-      judged: deciding ? deciding.judged : true,
+      verdict: /** @type {'green'|'red'|'instrument-stop'|'pause'} */ (deciding ? deciding.verdict : (paused ? 'pause' : 'green')),
+      exitCode: deciding ? /** @type {number} */ (deciding.exitCode) : (paused ? null : EXIT_GREEN),
+      judged: deciding ? deciding.judged : (paused ? false : true),
       firstRed: deciding ? deciding.stage : null,
+      /** the stage the close is WAITING on, when it is waiting on a person */
+      pausedAt: paused ? paused.stage : null,
       stages,
     };
   } finally {