bareloop 0.10.0 → 0.12.0

package/src/declaredclose.js

@@ -68,11 +68,14 @@
 // once instead of once-per-invocation, but `runPlan` has a dozen return paths and
 // a leaked worktree outlives the process that made it.
 
-import { runStage, makeSeedTrees, STOP_FAULTS, EXIT_RED } from './kinds.js';
+import { runStage, makeSeedTrees, STOP_FAULTS, EXIT_RED, JUDGED_FLOOR_KIND } from './kinds.js';
 import {
   validateDeclaration, classGuards, genreOwnedEnvNames, ungroundedGenreEnv, GENRE_LANGUAGES, TYPES_GENRE,
-  VERDICT_CLASSES, LIVE_CLASSES,
+  VERDICT_CLASSES, LIVE_CLASSES, NEVER_OFFERED_KINDS,
 } from './authoring.js';
+// the calibration set's own gate lives beside the rulebook it is graded against
+// (src/judged.js) — one opinion about what a judged floor's signed artifacts are
+import { validateCalibrationSet } from './judged.js';
 import { stageGap } from './ralph.js';
 import { isObj, isNonEmptyString } from './validate.js';
 
@@ -99,7 +102,14 @@ export const DECLARED_GENRES = Object.freeze([TYPES_GENRE.name]);
  * constrained to the names the genre OWNS, so it can never become an environment
  * channel of its own.
  */
-export const CLOSE_DECL_FIELDS = Object.freeze(['genre', 'lang', 'stages', 'notes', 'genreEnv']);
+export const CLOSE_DECL_FIELDS = Object.freeze(['genre', 'lang', 'stages', 'notes', 'genreEnv', 'calibration']);
+
+/** what a stored calibration set carries, ENUMERATED: the frozen cases and the judge
+ * tier that graded them. Both are inside the spec, so `jobSpecHash` covers both — which
+ * is the whole mechanism behind "a judge-model bump forces a full recalibration"
+ * (src/judged.js, `JUDGE_MODEL`): the field moves, the hash moves, the signature dies,
+ * and the re-sign re-runs the gate. Anything else in there is a field nobody reads. */
+export const CALIBRATION_FIELDS = Object.freeze(['cases', 'judgeModel']);
 
 /**
  * The prefix M1 puts on EVERY gap line of a declared stage (its `ctx.gapKeep`).
@@ -112,12 +122,75 @@ export const DECLARED_GAP_PREFIX = 'close: ';
  * whole judged output rather than a hand-picked slice of it. */
 export const DECLARED_GAP_KEEP = `^${DECLARED_GAP_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`;
 
-/** The verdict class a DECLARED close may claim. Hard, and by CONSTRUCTION
- * rather than by assertion: every live kind is a mechanical command whose
- * measurement is the truth, and the two judgment kinds are locked out at the
- * catalogue (M2) and absent from the executor (M1). Named as data so the job
- * validator reads one hierarchy table rather than hard-coding a class. */
-export const DECLARED_CLOSE_CLASSES = Object.freeze(['hard']);
+/**
+ * The close verdict word for a run WAITING on a person (N4 §1.3/§1.4). A
+ * literal, exported, because three readers key on it — the runner's pause
+ * branch, the ledger's excluded set, and the trend reader's blind rule — and
+ * three hand-spelled copies of one terminal is how they come to disagree.
+ *
+ * It is not in `CLOSE_FAULTS` and must never be added: a fault says the close
+ * could not render a verdict, and this says the close is not FINISHED rendering
+ * one. The first escalates; the second is a checkpoint the operator returns to.
+ */
+export const HUMAN_PAUSE = 'human-pause';
+
+/**
+ * The RUN-level terminal names the hitl class mints one layer up from
+ * `HUMAN_PAUSE` (N4 §1.3–§1.5): the checkpoint, and the honest refusal of the
+ * operator's rerun input. Spelled once here, beside the close-verdict word they
+ * translate, for the same reason `HUMAN_PAUSE` is — the emitters (`planrun.js`),
+ * the ledger's excluded set, the resume reader (`reuse.js`), and the runner
+ * script all key on them, and hand-spelled copies of one terminal is how they
+ * come to disagree.
+ *
+ * There were three (2026-08-17): `hitl-cancel` was the signer's own terminal and
+ * is DELETED with the door it belonged to. A person who does not want to carry on
+ * now PAUSES — the same checkpoint, resumable, retired by the TTL if nobody comes
+ * back — so nothing in this tree mints that name any more. The ledger keeps the
+ * bare string in its excluded set so a spine written before this change still
+ * reads as governance rather than as a capability gap; that is a READER's
+ * backward compatibility, and deliberately not a constant a writer could reach.
+ */
+export const HITL_PAUSE = 'hitl-pause';
+export const HITL_DECISION_RED = 'hitl-decision-red';
+
+/**
+ * The terminals above that leave the run WAITING ON A PERSON — as a list, minted
+ * beside the names it holds so a reader keys on membership rather than on a
+ * spelling, and a rename here travels to every reader for free.
+ *
+ * It is deliberately NOT `reuse.js`'s `CHECKPOINT_OUTCOMES`, which is the wider
+ * RESUME list: every stop that left work on disk and an allowance unspent, money
+ * and time included. Those are governance stops the reuse loop is meant to try
+ * again under its remaining tries; this is the half no further attempt can
+ * change, because the allowance still unspent is a human answer. `CHECKPOINT_OUTCOMES`
+ * is composed FROM this list so the two can never disagree about which is which.
+ *
+ * `HITL_DECISION_RED` is not here: it is a verdict already rendered on the operator's
+ * own input, not a question still open.
+ */
+export const HUMAN_CHECKPOINTS = Object.freeze([HITL_PAUSE]);
+
+/** The verdict classes a DECLARED close may claim. Named as data so the job
+ * validator reads one hierarchy table rather than hard-coding a class.
+ *
+ * `hard` is by CONSTRUCTION: every mechanical kind is a command whose measurement
+ * is the truth. `hitl` joined it at N4 slice 1, and `soft` at softgreen module 3
+ * — each only because its kind is genuinely LIVE (`human-confirms`, then
+ * `judged-floor`): the widening and the kind go in one commit, or this table
+ * admits a class the executor cannot render.
+ *
+ * `hitl` STAYS despite the class's retirement (PRD v1.71: the human stage moved
+ * out of the close and became the review door at the end of every run). It is
+ * kept because `jobs/litectx-maintainer.json` is a SIGNED spec carrying a hitl
+ * declaration, and a signed spec is untouchable — dropping the spelling here
+ * would invalidate a signature the operator already gave, which is a re-sign
+ * nobody asked for. Retiring it is a separate, deliberate deletion.
+ *
+ * The direction that matters is unchanged. This says which class a declaration
+ * MAY claim; `closeCeiling` says which class its stages actually NEED. A pick
+ * below the ceiling is still the silent upgrade `class-ceiling` refuses. */
+export const DECLARED_CLOSE_CLASSES = Object.freeze(['hard', 'soft', 'hitl']);
 
 /** @param {any} job @returns {boolean} */
 export function isDeclaredClose(job) {
@@ -130,12 +203,38 @@ export function isDeclaredClose(job) {
  *
  * `offer` and `needs` pass through untouched when a declaration carries them
  * (v1's schema does not let one), so `checkMenu`'s derivation is unchanged.
+ *
+ * THE JUDGE TIER RIDES ALONG, and it rides as a STAMP for the same reason `offer`
+ * does. The tier that graded this close's calibration set is a CLOSE-level fact
+ * (`calibration.judgeModel`), and the stage that would buy a judge call is a STAGE;
+ * `runStage` is handed stages and never the declaration they came out of. Rather than
+ * plumb a second close-level channel down through every executor seam, the one place
+ * that already turns a declaration into stages carries it across — and it carries it
+ * from the SIGNED bytes, so a stage can never name a tier the signature does not.
+ * `runJudgedFloor` refuses a mismatch; the absence of a stamp is the SPEC gate's
+ * business (`validateCloseDecl` reds a set with no model), never a runtime fall-back.
  * @param {any} closeDecl
  * @returns {any[]|null} null when this is not a declaration
  */
 export function declaredStages(closeDecl) {
   if (!isObj(closeDecl) || !Array.isArray(closeDecl.stages)) return null;
-  return closeDecl.stages.map((s) => (isObj(s) ? { ...s, gapKeep: DECLARED_GAP_KEEP } : s));
+  const calibrationJudgeModel = isObj(closeDecl.calibration) && isNonEmptyString(closeDecl.calibration.judgeModel)
+    ? closeDecl.calibration.judgeModel
+    : null;
+  return closeDecl.stages.map((s) => (isObj(s)
+    // RULING 5, stamped by the ARBITER rather than trusted from the artefact:
+    // a judged or human stage is `offer: false` BY LAW, so `checkMenu` can never
+    // hand the agent `check-passes(<a person>)`. The validator refuses a
+    // declaration that says anything else (`human-stage-offered`), so this is
+    // never overwriting a signer-visible value — it is filling in a law the
+    // declaration schema deliberately gives the composer no way to state.
+    ? {
+      ...s,
+      gapKeep: DECLARED_GAP_KEEP,
+      ...(NEVER_OFFERED_KINDS.includes(s.kind) ? { offer: false } : {}),
+      ...(s.kind === JUDGED_FLOOR_KIND && calibrationJudgeModel !== null ? { calibrationJudgeModel } : {}),
+    }
+    : s));
 }
 
 // ── the spec-level gate ──────────────────────────────────────────────────────
@@ -310,6 +409,56 @@ export function validateCloseDecl(closeDecl, opts = {}) {
   });
   for (const r of v.reds) reds.push({ ...r, path: r.path ? `${at}.${r.path}` : at });
 
+  // ── THE FROZEN CALIBRATION SET (softgreen module 4, design §4.4). It rides
+  // the closeDecl rather than a stage's params because it calibrates the RULER,
+  // not one stage's parameters — and because it is read BEFORE any stage runs.
+  //
+  // WHAT IS CHECKED HERE is that a stored set is LEGAL: exactly the signed size,
+  // both polarities present, itemized reds naming lines THIS close's card
+  // actually carries. WHAT IS NOT is whether the pipe grades it correctly — that
+  // is module 5's gate, it costs paid calls, and a validator cannot buy them.
+  //
+  // A set with NO judged stage to calibrate is its own red: the card lives on
+  // the stage, so an orphan set is graded against nothing and would validate
+  // clean forever. The reverse (a judged stage with no set) is deliberately NOT
+  // redded here — making the set MANDATORY is the signing gate's call, and
+  // module 5 owns it.
+  if (closeDecl.calibration !== undefined) {
+    const judged = (Array.isArray(closeDecl.stages) ? closeDecl.stages : [])
+      .filter((/** @type {any} */ s) => isObj(s) && s.kind === JUDGED_FLOOR_KIND);
+    if (!isObj(closeDecl.calibration)) {
+      red('invalid-value', `${at}.calibration`, 'the frozen calibration set, as an object carrying `cases`');
+    } else if (judged.length !== 1) {
+      red('calibration-orphan', `${at}.calibration`, `this close carries a calibration set and ${judged.length} `
+        + 'judged-floor stage(s). The set calibrates ONE judged ruler against ONE card — with no judged stage it is '
+        + 'graded against nothing and would read clean forever, and with two there is no one card it belongs to',
+      { judgedStages: judged.length });
+    } else {
+      for (const key of Object.keys(closeDecl.calibration)) {
+        if (!CALIBRATION_FIELDS.includes(key)) red('invalid-value', `${at}.calibration.${key}`, `a calibration set carries ${CALIBRATION_FIELDS.map((f) => `\`${f}\``).join(' and ')} and nothing else`);
+      }
+      // WHICH TIER GRADED THIS SET, and it is REQUIRED rather than optional. A
+      // stored set is only worth the judge that graded it (§4.2's safety argument
+      // is BA-20's haiku-4.5 injection evidence and nothing else), so a set with
+      // no model beside it is a set nobody can attribute — and the `JUDGE_MODEL`
+      // docstring's promise that a bump forces recalibration has nothing to fire
+      // on. Required HERE and not at the stage, for the same reason the SET's own
+      // presence is the signing gate's call and not this validator's: this gate
+      // reads a stored artifact and says whether it is legal. The RUNTIME half —
+      // refusing to grade when the stored tier is not the tier this run would buy
+      // — is the judged stage's (`runJudgedFloor`), reached through the stamp
+      // `declaredStages` puts on the stage.
+      if (closeDecl.calibration.judgeModel === undefined) {
+        red('missing-required', `${at}.calibration.judgeModel`, 'the judge tier this set was GRADED by — a calibration '
+          + 'nobody can attribute to a model is a floor nobody can tell apart from a bumped one');
+      } else if (!isNonEmptyString(closeDecl.calibration.judgeModel)) {
+        red('invalid-value', `${at}.calibration.judgeModel`, 'the judge tier this set was graded by, as a non-empty string');
+      }
+      const cv = validateCalibrationSet(closeDecl.calibration.cases, { card: judged[0]?.params?.card ?? null });
+      for (const r of cv.reds) reds.push({ ...r, path: r.path ? `${at}.${r.path}` : `${at}.calibration` });
+    }
+  }
+
   const ok = reds.length === 0;
   return {
     ok,
@@ -361,7 +510,7 @@ export function guardNames(closeDecl, verdictType) {
  * @param {any} r an M1 `StageResult`
  * @param {(s: string) => string} redact
  * @returns {{verdict: string, notes?: string, gap?: string, detail?: string,
- *   exitCode?: number, judgedCount?: number}} `notes` is absent, never empty —
+ *   exitCode?: number, judgedCount?: number, ask?: string|null}} `notes` is absent, never empty —
  *   a field that is always there says nothing; a RED carries its diagnostics
  *   inside `gap` and so has none of its own.
  */
@@ -370,6 +519,13 @@ function translate(r, redact) {
   /** absent rather than empty: a field that is always there says nothing */
   const notes = gapText ? { notes: gapText } : {};
   if (r.verdict === 'green') return { verdict: 'satisfied', judgedCount: 1, ...notes };
+  // THE PAUSE (N4 §1.3) — its own verdict word, and deliberately NOT one of the
+  // three below. `satisfied` would mint a green nobody gave; `needs_revision`
+  // would hand the fix worker a gap the person has not written yet; a
+  // `CLOSE_FAULTS` word would file a working arbiter as a broken instrument.
+  // No `gap` and no `judgedCount`: nothing was judged, and every consumer guards
+  // with `if (gap)`.
+  if (r.verdict === 'pause') return { verdict: HUMAN_PAUSE, ask: r.detail?.ask ?? null, ...notes };
   if (r.verdict === 'red') {
     return {
       verdict: 'needs_revision',
@@ -408,11 +564,17 @@ function translate(r, redact) {
  * @param {any[]} stages declared stage descriptors, already validated
  * @param {(s: string) => string} [redact] the scrub, applied at THIS boundary
  * @param {{timeoutMs?: number, cwd?: string, seedRef?: string,
- *   seedTrees?: any, gapCap?: number, maxBuffer?: number, baselineMode?: 'auto'|'worktree'}} [opts]
+ *   seedTrees?: any, gapCap?: number, maxBuffer?: number, baselineMode?: 'auto'|'worktree',
+ *   humanRuling?: {decision: string, text?: string|null}|null,
+ *   judgeLoop?: ((o: {system: string}) => any)|null,
+ *   onJudgeCost?: ((c: any) => void)|null}} [opts]
  * @returns {Promise<any>}
  */
 export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
-  const { timeoutMs, cwd, seedRef, seedTrees: shared, gapCap, maxBuffer, baselineMode } = opts;
+  const {
+    timeoutMs, cwd, seedRef, seedTrees: shared, gapCap, maxBuffer, baselineMode, humanRuling = null,
+    judgeLoop = null, onJudgeCost = null,
+  } = opts;
   if (!isNonEmptyString(cwd) || !isNonEmptyString(seedRef)) {
     // Refuse rather than guess. A declared close measures against a SEED; a
     // missing one is the close unable to run, not a red about the worker.
@@ -436,6 +598,19 @@ export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
     ...(gapCap !== undefined ? { gapCap } : {}),
     ...(maxBuffer !== undefined ? { maxBuffer } : {}),
     ...(baselineMode !== undefined ? { baselineMode } : {}),
+    // the SIGNER's answer, when this close has a human stage and a leg is
+    // carrying one. Absent (null) is the ordinary path AND the pause path — the
+    // human stage reads the absence as "nobody has answered yet", which is the
+    // whole of what a pause means.
+    humanRuling,
+    // THE PAID SEAM and THE METER, both operator territory and both absent on
+    // every mechanical close. A judged stage with no seam STOPS as a wiring gap
+    // rather than falling back to some other model (M1 owns no provider and the
+    // judge tier is pinned), and every locate call it does buy is reported OUT
+    // through the meter so the run's ONE ledger can see it — a close has cost $0
+    // until this kind, and a budget must fund the attempt PLUS its close.
+    judgeLoop,
+    onJudgeCost,
     seedTrees,
   };
   try {

package/src/index.js

@@ -31,23 +31,36 @@ export { validateJob, jobSpecHash, checkApproval, checkMenu, CLOSE_TYPES, CLASS_
 export { validatePlan, stageClose, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS } from './plan.js';
 export { snapshotScope, evalExits } from './exits.js';
 export { runPlan } from './planrun.js';
-export { runJob } from './run.js';
+// `ACCOUNTED_ROUND_TYPES` rides with it: the round records the ONE ledger sums.
+// A runner reconstructing a killed run's spend (the resume fold) must add exactly
+// these and nothing else, and a second hand-kept list is how a paid call comes to
+// be free (`judge-round` — the close's own spend — joined at softgreen module 2).
+export { runJob, ACCOUNTED_ROUND_TYPES } from './run.js';
 // Layer 3 — the REUSE registry (bridge-v1) and D3's display half. The registry is a
 // directory of plain files at an OPERATOR-supplied path (never a default location), the
 // load gate is the code half of D2's split, and `renderListing`/`selectionPrompt` are
 // pure text: they send nothing, parse nothing and decide nothing. The selection CALL and
 // the pin/shortlist/force-cold flow are the adopter's, which is why the pieces they need
 // are exported rather than kept internal to the runner.
+//
+// Softgreen module 6 exports the QUARANTINE surface with them: a judged green is minted
+// HELD and earns nothing until the signer's `accept` at the review door releases it
+// (PRD v1.71 §3). `recordDoor` is the pure half (record the disposition, release
+// forward-only) and `reuseEligibility`/`newestEligibleVersion` are what every consumer
+// asks before starting from a stored plan.
 export {
   BRIDGE_SCHEMA, validateBridge, deriveStatus, listingRow, loadGate,
   mintBridge, appendGreen, appendRed,
   loadBridge, loadRegistry, saveBridge, makeRegistry, registryExists,
+  QUARANTINED_VERDICTS, QUARANTINED_CODE, quarantinesCredit, newestEligibleVersion, reuseEligibility, recordDoor,
 } from './bridges.js';
 export { renderListing, selectionPrompt } from './selection.js';
 // Layer 3 modules 4+5 — the D7 envelope and the reuse runner. `runReuse` composes
-// `runJob` under an operator-signed envelope (three explicit numbers, tighten-only) and
-// is the only thing in the library that WRITES the registry — minting is a graded
-// green's privilege (R1), never a caller's. `validateEnvelope`/`resolveTrySpec` are
+// `runJob` under an operator-signed envelope (three explicit numbers, tighten-only). It
+// is not the only registry WRITER any more (2B: `writeRunGreenRow`), but the rule it
+// enforced is unchanged and now lives in both — minting is a graded green's privilege
+// (R1), never a caller's: both writers go through `writeGreenRow`, and neither can mint
+// a row for anything but a green that this run actually earned. `validateEnvelope`/`resolveTrySpec` are
 // exported because an operator runner has to show the resolved per-try spec's HASH at
 // its approval gate: a tightened envelope is a new spec version, and the human signs it.
 // `resolveReuse`/`reuseSpecHash` are the pair that gate must actually PRINT: the try
@@ -60,7 +73,15 @@ export { renderListing, selectionPrompt } from './selection.js';
 // `resumeTreeGate` is the ruling that a resumed patient is continued dirty and never
 // reset. Both are read by a runner BEFORE the approval gate, so neither can live behind
 // `runReuse`'s own entry.
-export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate } from './reuse.js';
+// `applyDoorDecision` is the registry half of the REVIEW DOOR (softgreen module 6): the
+// door opens AFTER a run has ended, so a person's answer cannot ride the run's own return
+// path — the runner calls this with the runid it printed at the door.
+// `writeRunGreenRow` is that door's other half (2B), and it is exported for the same
+// reason: a runner that drives `runJob` directly rather than through `runReuse` still ends
+// at a review door, and a door with no row to act on can only describe a held learning
+// credit it has no way to release. STORAGE ONLY — nothing here selects, promotes or reuses
+// a bridge; those stay parked on `layer-3-reuse`.
+export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate, CHECKPOINT_OUTCOMES, PAUSE_TTL_MS, checkpointAgeGate, applyDoorDecision, writeRunGreenRow } from './reuse.js';
 export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES } from './ledger.js';
 // THE WORK BRANCH (PRD v1.57 §3). `workBranchName` is exported so an operator runner can
 // SHOW, before the approval gate, which branch the run will work on — the same reason the
@@ -89,7 +110,66 @@ export { workBranchName, prepareWorkBranch, WORK_BRANCH_PREFIX, WORK_BRANCH_RE }
 export {
   runDeclaredClose, runStage, seedRead, seedAtHead, seedListing, changedSet, makeSeedTrees,
   LIVE_KINDS, STOP_FAULTS, JUDGED_MARKER, EXIT_GREEN, EXIT_RED, EXIT_STOP,
+  // N4 slice 1 — the hitl surface an adopting runner needs: the three doors, the
+  // gate that reads a signer's answer (and refuses an empty one), and the seed
+  // exemption ruling 8 states.
+  HUMAN_DECISIONS, SEED_EXEMPT_KINDS, JUDGED_FLOOR_KIND, normalizeHumanRuling, resolveHumanRuling,
+  // SOFTGREEN module 2 — the judged stage's own arbiter-owned bounds. An adopter
+  // wiring `judgeProvider` needs both numbers to reason about what a judged close
+  // can cost: one paid call per artifact, at most one retry each.
+  JUDGE_ATTEMPTS, MAX_JUDGED_PATHS,
+  // SOFTGREEN module 8 — the REVIEW DOOR's vocabulary: the record type a run
+  // writes when it ends at the door, which terminals open one, which classes open
+  // one unasked, and the mechanical-only rule an `accept` re-proves against.
+  REVIEW_DOOR, DOOR_OPEN_OUTCOMES, REVIEW_DOOR_CLASSES, doorOpens, mechanicalStages,
 } from './kinds.js';
+// SOFTGREEN module 8 — the door's ANSWERING half. A run OPENS the door on its own
+// spine and ends; a person answers minutes or days later, from another process, so
+// the answer cannot ride the run's return path. `answerReviewDoor` is that seam:
+// it re-proves the tree for an `accept`, releases a held judged green through
+// module 6's registry half, and refuses an expired door under the same 60-day TTL a
+// hitl checkpoint keeps. It never returns, writes or implies a verdict.
+export { answerReviewDoor, doorRecordOf, doorAgeGate } from './reviewdoor.js';
+// SOFTGREEN module 1 — the judged floor's core. The pieces an adopter (and an
+// integrating UI) genuinely needs: the PIN (`JUDGE_MODEL` — what a wired judge
+// provider must be bound to, and a bump of which forces recalibration), the
+// rulebook a card SELECTS from, the card gate, and the two halves themselves so a
+// calibration harness can grade the whole pipe without running a close.
+// `defaultJudgeLoop` is the one spelling of how this repo drives a judge; the
+// runner reaches it through `runPlan`'s `judgeProvider`, and it is exported so a
+// caller building its own harness does not spell a second one.
+export {
+  JUDGE_MODEL, JUDGE_MAX_TOKENS, JUDGE_RULES, JUDGE_RULE_IDS, LOCATE_AXES, LOCATE_LABEL,
+  validateCard, validateFacts, locatePrompt, runLocate, decide, defaultJudgeLoop,
+  // SOFTGREEN module 4 — what a legal SIGNED calibration set is. The SIZE is
+  // hamr's own ruling and a size change is a spec-level threshold change;
+  // `expectedOf` is the ONE reduction of a `decide()` result to the shape a case
+  // stores, so a calibration harness compares one shape rather than two.
+  CALIBRATION_SIZE, CASE_VERDICTS, validateCalibrationSet, validateJudgedArtifacts, expectedOf,
+} from './judged.js';
+// SOFTGREEN module 4 — the COMPILE. Q6 becomes the rubric card and Q7 becomes the
+// frozen calibration set, both on the D5 shown-and-fixed path: the LLM proposes
+// through `proposeJudgedArtifacts`, an integrating UI shows the proposal, the
+// SIGNER's fix goes through `signJudgedArtifacts`, and `foldJudgedArtifacts`
+// enumerates both into the closeDecl — where the spec hash covers them, so a card
+// line or a case is a re-sign like every other spec edit.
+export {
+  proposeJudgedArtifacts, signJudgedArtifacts, foldJudgedArtifacts,
+  proposalSchema, proposalTool, cardCasesPrompt,
+  PROPOSAL_TOOL_NAME, PROPOSAL_LABEL, MAX_PROPOSAL_RETRIES, COMPILE_SYSTEM,
+} from './cardauthor.js';
+// SOFTGREEN module 5 — THE CALIBRATION GATE. `runCalibration` grades the whole
+// pipe (locate + decide) over the signed ten and the five arbiter-owned injection
+// artifacts; `prepareSigning` runs it and refuses on anything short of all of
+// them. Exported because an integrating UI has to be able to RUN and RENDER the
+// gate — the graded rows are what a signer reads before giving a signature — and
+// because the battery is evidence a reader may want to inspect rather than take
+// on trust. `INJECTION_LOCATE_BATTERY` and `INJECTION_CARD` are ARBITER-OWNED
+// constants: no signer authors them and nothing stores them in a spec.
+export {
+  runCalibration, compareExpectation, factsResist, artifactHash,
+  INJECTION_LOCATE_BATTERY, INJECTION_CARD, CALIBRATION_LABEL, CASUALTY_AXES,
+} from './calibrate.js';
 // M2 — what a declaration may SAY, and whether one said it legally. The
 // catalogue and the genre are DATA an integrating UI renders (the kind menu, the
 // guard batteries it must show the user under D5 and cannot let them remove).
@@ -102,7 +182,9 @@ export {
   DIRECTIONS, BASELINES, MAX_STAGES,
   // the verdict-class surface (PRD v1.57 §1–§2): the radio's own menu, the guard
   // battery keyed off it, and the ceiling that makes the pick a promise
-  VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES, CLASS_BATTERIES, classGuards, closeCeiling,
+  VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES, CLASS_BATTERIES, classGuards, classMenu, closeCeiling,
+  // ruling 5 as data: the kinds no agent may ever be offered as an in-run ruler
+  NEVER_OFFERED_KINDS,
 } from './authoring.js';
 // M3 — the looking half and the writing half. `authorClose` is the grounded
 // loop; `runAuthorScout`/`buildSeedListing` are exported because a caller that
@@ -119,7 +201,7 @@ export {
 export { scrubRaw, RAW_PERSIST_MAX, RAW_TRIM_MARKER } from './text.js';
 export {
   authorClose, authorPrompt, declarationSchema, makeLoopGenerate, MAX_REVISIONS,
-  QUESTION_SETS, GREEN_QUESTIONS, CLASS_STATEMENTS, questionsFor, requiredAnswersFor,
+  QUESTION_SETS, GREEN_QUESTIONS, SOFTGREEN_QUESTIONS, CLASS_STATEMENTS, questionsFor, requiredAnswersFor,
 } from './authorflow.js';
 // M4a — the runtime bridge. `validateCloseDecl` is the spec-level gate (the job
 // validator's own branch calls it); `runDeclaredStages` is the executor seam a
@@ -128,6 +210,7 @@ export {
 export {
   validateCloseDecl, runDeclaredStages, declaredStages, isDeclaredClose, guardNames, closeGrade,
   DECLARED_GENRES, DECLARED_GAP_PREFIX, DECLARED_GAP_KEEP, DECLARED_CLOSE_CLASSES, CLOSE_DECL_FIELDS,
+  HUMAN_PAUSE, HITL_PAUSE, HITL_DECISION_RED, HUMAN_CHECKPOINTS,
 } from './declaredclose.js';
 export { closeStagesOf } from './plan.js';
 // M4b — the interview, the refusal, the composition, and D9's three gates.

package/src/job.js

@@ -1,5 +1,5 @@
 // Job-spec validator — the OPERATOR-owned half of the config story (N1,
-// design record: docs/plans/2026-07-12-n1-job-close-schema-design.md).
+// design record: docs/02-features/2026-07-12-n1-job-close-schema-design.md).
 // A job spec is the arbiter's rulebook: the close chain, the budget, the
 // outer write fence, the escalation route. It is pure declarative data —
 // no freeform code is expressible anywhere in it — and it validates
@@ -98,12 +98,30 @@ export const MIN_WALL_MS = 120_000;
  * counts admission demand, and a generic invalid-value would bury it as a typo. */
 export const LOCKED_TOOLS = Object.freeze(['run']);
 /** Layer 2 (design record 2026-07-21, decision 5): the verdict-type radio of
- * the four-field plan shape. v1 ADMITS only `green`; soft-green/hitl are
- * declared-but-locked — declaring one is a `request-red` (the tool-menu
- * pattern: disclosure ≠ admission), so the ledger counts the demand and the
- * non-code rung later fills a declared slot instead of reshaping the schema. */
+ * the four-field plan shape. All three are ADMITTED as of softgreen module 3;
+ * the declared-but-locked mechanism below (`LOCKED_VERDICTS`) is what carried
+ * them here one rung at a time — declaring a locked one is a `request-red` (the
+ * tool-menu pattern: disclosure ≠ admission), so the ledger counted the demand
+ * instead of the schema being reshaped when the rung finally landed. */
 export const VERDICT_TYPES = Object.freeze(['green', 'soft-green', 'hitl']);
-export const LOCKED_VERDICTS = Object.freeze(['soft-green', 'hitl']);
+/** N4 slice 1 admitted `hitl`; softgreen module 3 admits `soft-green`, and the
+ * menu is now EMPTY — every class the radio names is built.
+ *
+ * `soft-green`'s lock was never a policy, it was a missing floor: a judged
+ * verdict with no ruler mints nothing honestly. Modules 1 and 2 built the ruler
+ * (a pinned judge that only LOCATES, an arbiter-owned `decide()`, a calibration
+ * gate) and wired it as the `judged-floor` kind, so the lock has nothing left to
+ * protect (design record 2026-08-17 §4, and the 2026-08-18 thresholds addendum).
+ *
+ * EMPTY here means "nothing is locked", which is a TRUE statement about a closed
+ * menu — not F59's absent-read-as-empty, where a `{}` stood in for a fact nobody
+ * gathered. The mechanism below stays exactly as it is: it is read at call time
+ * from this constant, so re-locking a class (or admitting a fourth) is one edit
+ * and the counted `request-red` path comes back with it. `LOCKED_CLASSES` in
+ * src/authoring.js is the twin and moved in the same commit; the suite pins the
+ * two identical. */
+/** @type {readonly string[]} */
+export const LOCKED_VERDICTS = Object.freeze([]);
 /** which close CLASS a declared verdictType demands — the close hierarchy one
  * level up: the same laundering guard as CLASS_BY_CLOSE, applied to the plan
  * shape's single close (green on a rubric would be a fake-hard verdict). */
@@ -515,8 +533,9 @@ function validateStagedClose(stages, red) {
  * stages instead (PRD v1.28/v1.32), and a spec that still declares it gets the
  * `checks-derived` red below rather than a bare unknown-field.
  *
- * v1 admits only verdictType `green`; soft-green/hitl are declared-but-locked
- * and red as `request-red` — admission demand the ledger counts, never a grant.
+ * Every verdictType the radio names is admitted (softgreen module 3); a class
+ * that were locked reds as `request-red` — admission demand the ledger counts,
+ * never a grant.
  * The close is validated one level up as well: a declared verdict demands a
  * close CLASS, so green-on-rubric reds as `close-hierarchy` rather than
  * laundering a soft judgement into a hard one.
@@ -536,7 +555,7 @@ function validatePlanShape(spec, red, reds) {
     // the type rides as a structured field — the ledger keys admission demand
     // on it, never on prose. `lib: 'bareloop'`: the refused catalogue is OURS
     // (VERDICT_TYPES), so this demand is never an upstream ask.
-    reds.push({ code: 'request-red', path: 'verdictType', verb: spec.verdictType, lib: 'bareloop', detail: `"${spec.verdictType}" is declared-but-locked — not at this rung (v1 admits green only); this red IS the admission evidence, never a grant` });
+    reds.push({ code: 'request-red', path: 'verdictType', verb: spec.verdictType, lib: 'bareloop', detail: `"${spec.verdictType}" is declared-but-locked — not at this rung (admitted: ${VERDICT_TYPES.filter((v) => !LOCKED_VERDICTS.includes(v)).join(', ')}); this red IS the admission evidence, never a grant` });
     demanded = CLASS_BY_VERDICT[spec.verdictType];
   } else if (!VERDICT_TYPES.includes(spec.verdictType)) {
     red('invalid-value', 'verdictType', `menu: ${VERDICT_TYPES.join('|')} — an unknown type is a typo, never a request`);