bareloop 0.11.0 → 0.13.0

package/src/authorflow.js

@@ -75,11 +75,12 @@
 import { createRequire } from 'node:module';
 import { realpathSync } from 'node:fs';
 import { join, relative, isAbsolute } from 'node:path';
-import { seedRead as runSeedReadStages, makeSeedTrees, AGGREGATES, SIGNS, MAX_TERMS } from './kinds.js';
+import { seedRead as runSeedReadStages, makeSeedTrees, AGGREGATES, SIGNS, MAX_TERMS, MAX_JUDGED_PATHS } from './kinds.js';
+import { JUDGE_RULE_IDS } from './judged.js';
 import {
   KIND_CATALOGUE, MAX_STAGES, DIRECTIONS, BASELINES,
   GENRE_LANGUAGES, TYPES_GENRE_TEMPLATE, classGuards, genreEnv, genreOwnedEnvNames, genreInstruments,
-  validateDeclaration, envCapableKind, VERDICT_CLASSES, LIVE_CLASSES,
+  validateDeclaration, envCapableKind, classMenu, VERDICT_CLASSES, LIVE_CLASSES,
 } from './authoring.js';
 import { buildSeedListing, cleanEntry, SURVEY_CAUSES } from './authorscout.js';
 import { extractArtifact, priceOf, scrubRaw, tallyCalls, capStop } from './text.js';
@@ -223,11 +224,47 @@ export const HITL_QUESTIONS = Object.freeze({
 });
 
 /**
- * The three sets. `questions: null` on a locked class is ABSENT, never `{}`:
- * an empty set would read as "this class needs no questions", which is a
- * different and false statement (F59's distinction, at the interview layer).
- * Nothing ever reads them — a locked class refuses at ADMISSION, before its
- * questions run — and the two readers below throw rather than hand back nothing.
+ * THE SOFTGREEN SET (module 3, design record §4.6) — the green questions BYTE
+ * FOR BYTE, plus TWO.
+ *
+ * Same discipline as the hitl set, and for the same reason: a softgreen close is
+ * *mechanical stages first, the judged stage after* (§4.5), so a softgreen job
+ * needs every mechanical fact a green one does. No renumbering of the green set,
+ * no genre question, nothing reworded.
+ *
+ * The two additions are the only things the green set cannot supply, and neither
+ * is a flourish — they are the judged floor's two REQUIRED inputs:
+ *   - Q6 becomes the RUBRIC CARD (§4.3): the person's own pass/fail lines,
+ *     compiled into enumerated items, signed, and enumerated in the spec hash.
+ *     The documented ceiling rides with it — the judge catches violations of
+ *     STATED card items only, and the fix for a miss is a new card line and a
+ *     re-sign, never a smarter judge.
+ *   - Q7 becomes the frozen CALIBRATION SET (§4.4): the whole pipe must grade it
+ *     correctly before the close is signable.
+ * Both are asked in the person's own terms — an example they would pass and one
+ * they would fail, not a rubric they are asked to write — because compiling a lay
+ * answer into extractable items is the LLM's job (D5, proposed-and-signed) and
+ * asking the person to do it is the SWE tax this product refuses.
+ *
+ * What the two answers COMPILE INTO is module 4. This module carries them
+ * exactly as the hitl set carries its own last answer: they ride in `answers`,
+ * they reach the composer verbatim through the prompt's interview block, and
+ * nothing here derives anything from them.
+ */
+export const SOFTGREEN_QUESTIONS = Object.freeze({
+  ...GREEN_QUESTIONS,
+  6: 'When you judge the result yourself, what separates a pass from a fail? Name the few things you actually look for.',
+  7: 'Give one example you\'d pass and one you\'d fail, and say why.',
+});
+
+/**
+ * The three sets, all LIVE as of softgreen module 3. The locked shape stays
+ * spelled out in the readers below rather than deleted with the last locked
+ * class: `questions: null` is ABSENT, never `{}` — an empty set would read as
+ * "this class needs no questions", a different and false statement (F59's
+ * distinction, at the interview layer) — and a locked class refuses at ADMISSION,
+ * before its questions run, so the two readers throw rather than hand back
+ * nothing. A fourth class arrives locked, and the machinery is here for it.
  * @type {Record<string, {locked: boolean, questions: Record<string|number, string>|null, required: readonly number[]|null}>}
  */
 export const QUESTION_SETS = Object.freeze({
@@ -236,7 +273,11 @@ export const QUESTION_SETS = Object.freeze({
     questions: GREEN_QUESTIONS,
     required: Object.freeze(Object.keys(GREEN_QUESTIONS).map(Number).sort((a, b) => a - b)),
   }),
-  'soft-green': Object.freeze({ locked: true, questions: null, required: null }),
+  'soft-green': Object.freeze({
+    locked: false,
+    questions: SOFTGREEN_QUESTIONS,
+    required: Object.freeze(Object.keys(SOFTGREEN_QUESTIONS).map(Number).sort((a, b) => a - b)),
+  }),
   hitl: Object.freeze({
     locked: false,
     questions: HITL_QUESTIONS,
@@ -259,7 +300,18 @@ export const CLASS_STATEMENTS = Object.freeze({
     + 'to decide it — no judgement, no score, and no person in the loop. Every stage you compose is a mechanical '
     + 'measurement of this repository. If part of what they asked for cannot be measured that way, leave it out and '
     + 'say so in your notes rather than approximating it with a stage that means something else.',
-  'soft-green': null,
+  // softgreen module 3. Stated as an ORDER for the same reason hitl's is: the
+  // close is first-red-wins, so the cheap mechanical stages shield the one stage
+  // that spends money, and the judge is never the first filter. The last sentence
+  // is the documented ceiling (§4.3) said to the composer in its own terms — the
+  // judge only ever checks lines the card names, so an unstated expectation is
+  // not a stricter judge, it is a line nobody wrote.
+  'soft-green': 'The person declared this job SOFT-GREEN: part of what "done" means here needs JUDGEMENT — reading '
+    + 'the result and deciding whether it is any good — and no command can render it. Compose the mechanical part '
+    + 'first: everything about this repository a command can decide is still a mechanical stage, exactly as it would '
+    + 'be for a green job. Then put ONE judged-floor stage AFTER them, carrying the few things the person said they '
+    + 'actually look for and the real files the work lands in. A judged stage decides only the lines its card names, '
+    + 'so name each thing they look for as its own line, and leave nothing to be inferred.',
   // N4 slice 1. The mechanical-first composition law is stated as an ORDER
   // because first-red-wins makes the order the mechanism: the cheap stages shield
   // the expensive one, and the person is never the first filter.
@@ -408,6 +460,39 @@ export const PARAM_SCHEMAS = Object.freeze({
   extensions: { type: 'array', minItems: 1, items: { type: 'string' } },
   allowPrefixes: { type: 'array', minItems: 1, items: { type: 'string' } },
   requireNonEmpty: { const: true },
+  // SOFTGREEN's two. `rule` is an ENUM off the judge's own rulebook — where only a
+  // closed set can satisfy a field, the illegal value is made inexpressible rather
+  // than rejected after the fact (`check-passes(name)`, again) — and `text` is the
+  // only free string, carrying the signer's words so a red can be explained in them.
+  card: {
+    type: 'object',
+    description: 'the rubric, as enumerated items: one line per thing the person actually looks for, in the order '
+      + 'they look for them. The rule is SELECTED from the arbiter\'s own rulebook; the text is theirs.',
+    properties: {
+      items: {
+        type: 'array',
+        minItems: 1,
+        items: {
+          type: 'object',
+          properties: {
+            rule: { enum: [...JUDGE_RULE_IDS], description: 'which owned rule this line asserts' },
+            text: { type: 'string', minLength: 1, description: 'what this line means, in the person\'s own words' },
+          },
+          required: ['rule', 'text'],
+          additionalProperties: false,
+        },
+      },
+    },
+    required: ['items'],
+    additionalProperties: false,
+  },
+  paths: {
+    type: 'array',
+    minItems: 1,
+    maxItems: MAX_JUDGED_PATHS,
+    items: { type: 'string' },
+    description: 'the AUTHORITATIVE artifacts to judge, repository-relative, read off the listing. One paid call each.',
+  },
   ask: {
     type: 'string',
     minLength: 1,
@@ -451,19 +536,27 @@ export function schemaCoverage(catalogue = KIND_CATALOGUE) {
  * and they arrive as validation reds through the revise loop — a schema that
  * tried to restate them would be a second validator.
  *
+ * `verdictType` narrows the branches to the kinds the picked class may express
+ * (softgreen module 3, `classMenu`): a green job cannot SPELL `judged-floor`,
+ * rather than spelling it and being told afterwards. COVERAGE is still computed
+ * over the WHOLE catalogue — the class filter must never make a parameter look
+ * orphaned and turn a menu narrowing into a catalogue-drift alarm.
+ *
  * THROWS on a catalogue it cannot cover: a malformed catalogue is a bareloop bug,
  * and failing loudly beats emitting a schema that quietly cannot say something
  * the validator will then demand.
  * @param {Record<string, any>} [catalogue]
+ * @param {{verdictType?: string|null}} [o]
  */
-export function declarationSchema(catalogue = KIND_CATALOGUE) {
+export function declarationSchema(catalogue = KIND_CATALOGUE, { verdictType = null } = {}) {
   const cov = schemaCoverage(catalogue);
   if (!cov.ok) {
     throw new Error('[authorflow] the declaration schema does not cover the catalogue — '
       + `missing: ${cov.missing.join(', ') || 'none'}; orphaned: ${cov.orphan.join(', ') || 'none'}`);
   }
+  const menu = classMenu(verdictType, catalogue);
   const branches = Object.entries(catalogue)
-    .filter(([, spec]) => !spec.locked)
+    .filter(([kind, spec]) => !spec.locked && menu.includes(kind))
     .map(([kind, spec]) => {
       /** @type {Record<string, any>} */
       const properties = {};
@@ -511,13 +604,13 @@ export function declarationSchema(catalogue = KIND_CATALOGUE) {
  * The output channel. It records and acknowledges; it takes no action, which is
  * why handing it to a toolless authoring call does not reopen D3.
  * @param {{calls: any[]}} box
- * @param {{catalogue?: Record<string, any>}} [o]
+ * @param {{catalogue?: Record<string, any>, verdictType?: string|null}} [o]
  */
-export function declarationTool(box, { catalogue = KIND_CATALOGUE } = {}) {
+export function declarationTool(box, { catalogue = KIND_CATALOGUE, verdictType = null } = {}) {
   return {
     name: DECLARATION_TOOL_NAME,
     description: 'Deliver the finished close. Call this exactly once, with the whole declaration as its arguments.',
-    parameters: declarationSchema(catalogue),
+    parameters: declarationSchema(catalogue, { verdictType }),
     execute: async (/** @type {any} */ args) => { box.calls.push(args); return DECLARATION_ACK; },
   };
 }
@@ -528,10 +621,19 @@ export function declarationTool(box, { catalogue = KIND_CATALOGUE } = {}) {
  * The catalogue, as the authoring call sees it — rendered FROM the catalogue, so
  * the prompt and the validator judge one set of facts. `shape` and `asserts` are
  * M2's own strings.
+ *
+ * `verdictType` narrows it to the picked class's menu, exactly as it narrows the
+ * schema — the prompt and the tool must offer ONE set of kinds, or the composer
+ * reads about a kind it cannot call. A kind above the ceiling is omitted rather
+ * than rendered as unavailable: a LOCKED row says "this does not run in v1",
+ * which is a fact about the build; "not for your class" is a fact about a choice
+ * the person already made, and printing it invites the composer to argue with it.
  * @param {Record<string, any>} [catalogue]
+ * @param {{verdictType?: string|null}} [o]
  */
-export function catalogueBlock(catalogue = KIND_CATALOGUE) {
-  const rows = Object.entries(catalogue).map(([name, spec]) => (spec.locked
+export function catalogueBlock(catalogue = KIND_CATALOGUE, { verdictType = null } = {}) {
+  const menu = classMenu(verdictType, catalogue);
+  const rows = Object.entries(catalogue).filter(([name]) => menu.includes(name)).map(([name, spec]) => (spec.locked
     ? `- ${name}  — LOCKED. Not available in v1; it will not run.`
     : `- ${name}\n    ${spec.shape}\n    required: ${spec.required.join(', ')}`
       + `${spec.optional.length ? `   optional: ${spec.optional.join(', ')}` : ''}\n    asserts: ${spec.asserts}`));
@@ -719,7 +821,9 @@ measure anything.`;
     `THE INTERVIEW — the person's own words\n\n${interview}`,
     `THE FACTS OBJECT — from a read-only survey of the repository\n\n${JSON.stringify(facts, null, 2)}`
       + (listingBlock ? `\n\n${listingBlock}` : ''),
-    catalogueBlock(catalogue),
+    // CLASS-SCOPED (softgreen module 3): the composer for a green job is never
+    // shown a kind whose pick would red as `class-ceiling` after the call.
+    catalogueBlock(catalogue, { verdictType }),
     lawsBlock(),
     `THE GENRE TEMPLATE — fixed by the job's genre (${lang}), not yours to decide\n\n`
       + 'This job\'s genre carries a fixed close SHAPE. The following policy is law for your declaration. It names\n'
@@ -1058,13 +1162,23 @@ function canonical(x) {
 
 /**
  * ONE structured ask, with the malformed-emission retry bounded on its OWN axis.
- * A reply that carries no declaration is an ARTIFACT-RED — name the axis, retry
+ * A reply that carries no artifact is an ARTIFACT-RED — name the axis, retry
  * under a cap, write nothing — and it never consumes a revision, because a
  * transport fault is not a defect in a close.
+ *
+ * THE CHANNEL IS A PARAMETER, and that is softgreen module 4's only change here:
+ * the rubric card and the calibration set are a SECOND schema-forced emission
+ * with the same failure modes, and a second ladder is a second place for the cap,
+ * the reject block and the re-ask to drift. The declaration channel below is the
+ * one this loop has always used, spelled out rather than inlined — nothing about
+ * the authoring path's behaviour moves.
  * @param {{messages: any[], generate: Function, mode: 'tool'|'text', retries: number,
- *   label: string, book: ReturnType<typeof makeCostBook>, catalogue: Record<string, any>}} o
+ *   label: string, book: ReturnType<typeof makeCostBook>,
+ *   channel: {name: string, instruction: string, textPath?: string, tool: (box: {calls: any[]}) => any}}} o
+ * @returns {Promise<{artifact: any, attempts: number, convo: any[], raw: string,
+ *   providerError: string|null, red: Red|null, budget: 'cap-halt'|'pricing-red'|null}>}
  */
-async function askDeclaration({ messages, generate, mode, retries, label, book, catalogue }) {
+export async function askStructured({ messages, generate, mode, retries, label, book, channel }) {
   /** @type {any[]} */
   const convo = [...messages];
   let attempts = 0;
@@ -1080,49 +1194,78 @@ async function askDeclaration({ messages, generate, mode, retries, label, book,
     // unbounded. `attempts` is returned as-is so the caller can tell a cap that
     // tripped before this ask began (0) from one that cut a retry ladder short.
     const halt = book.capStop();
-    if (halt) return { declaration: null, attempts, convo, raw: '', providerError: null, red: null, budget: halt };
+    if (halt) return { artifact: null, attempts, convo, raw: '', providerError: null, red: null, budget: halt };
 
     /** @type {{calls: any[]}} */
     const box = { calls: [] };
-    const tools = mode === 'tool' ? [declarationTool(box, { catalogue })] : [];
+    // the tool's schema is CLASS-SCOPED, like the prompt's catalogue block: the
+    // two must offer one set of kinds, or the composer reads about a kind it
+    // cannot call — or worse, calls one the ceiling will refuse after we paid.
+    const tools = mode === 'tool' ? [channel.tool(box)] : [];
     const r = await generate(convo, tools, {});
     attempts += 1;
     book.add(attempt === 0 ? label : `${label}#${attempt + 1}`, r, attempts);
     const raw = redactSecrets(String(r?.text ?? ''));
 
     if (r?.error) {
-      return { declaration: null, attempts, convo, raw, providerError: String(r.error), red: null, budget: null };
+      return { artifact: null, attempts, convo, raw, providerError: String(r.error), red: null, budget: null };
     }
 
     if (mode === 'tool') {
-      if (box.calls.length === 1) return { declaration: box.calls[0], attempts, convo, raw, providerError: null, red: null, budget: null };
+      if (box.calls.length === 1) return { artifact: box.calls[0], attempts, convo, raw, providerError: null, red: null, budget: null };
       red = {
         code: 'artifact-red',
-        path: DECLARATION_TOOL_NAME,
+        path: channel.name,
         detail: box.calls.length === 0
-          ? `the reply delivered no ${DECLARATION_TOOL_NAME} call — structure is enforced, prose is never parsed`
-          : `the reply delivered ${box.calls.length} ${DECLARATION_TOOL_NAME} calls; exactly one declaration is expected`,
+          ? `the reply delivered no ${channel.name} call — structure is enforced, prose is never parsed`
+          : `the reply delivered ${box.calls.length} ${channel.name} calls; exactly one is expected`,
         axis: box.calls.length === 0 ? 'no-declaration-tool-call' : 'multiple-declaration-tool-calls',
       };
     } else {
       // THE FALLBACK PATH — providers without tool mode only. The ONE shipped
       // parser, never a second one.
+      const at = channel.textPath ?? channel.name;
       const { code, red: extractRed } = extractArtifact(raw);
       if (code) {
-        try { return { declaration: JSON.parse(code), attempts, convo, raw, providerError: null, red: null, budget: null }; }
-        catch (e) { red = { code: 'artifact-red', path: 'declaration', detail: `the declaration did not parse as JSON: ${String(/** @type {any} */ (e)?.message ?? e)}`, axis: 'unparseable-json' }; }
+        try { return { artifact: JSON.parse(code), attempts, convo, raw, providerError: null, red: null, budget: null }; }
+        catch (e) { red = { code: 'artifact-red', path: at, detail: `the ${at} did not parse as JSON: ${String(/** @type {any} */ (e)?.message ?? e)}`, axis: 'unparseable-json' }; }
       } else {
-        red = { code: 'artifact-red', path: 'declaration', detail: `no artifact in the reply: ${extractRed}`, axis: 'no-artifact' };
+        red = { code: 'artifact-red', path: at, detail: `no artifact in the reply: ${extractRed}`, axis: 'no-artifact' };
       }
     }
 
     if (attempt < retries) {
       const block = renderRejectBlock({ kind: 'artifact', reds: [/** @type {Red} */ (red).detail] });
       convo.push({ role: 'assistant', content: raw.trim() || '(the reply carried no text)' });
-      convo.push({ role: 'user', content: `${block}\n\n${mode === 'tool' ? STRUCTURE_INSTRUCTION_TOOL : STRUCTURE_INSTRUCTION_TEXT}` });
+      convo.push({ role: 'user', content: `${block}\n\n${mode === 'tool' ? channel.instruction : STRUCTURE_INSTRUCTION_TEXT}` });
     }
   }
-  return { declaration: null, attempts, convo, raw: '', providerError: null, red, budget: null };
+  return { artifact: null, attempts, convo, raw: '', providerError: null, red, budget: null };
+}
+
+/** THE DECLARATION CHANNEL — the one this loop has always used. Its schema is
+ * CLASS-SCOPED, like the prompt's catalogue block: the two must offer one set of
+ * kinds, or the composer reads about a kind it cannot call.
+ * @param {{catalogue: Record<string, any>, verdictType: string}} o */
+const declarationChannel = ({ catalogue, verdictType }) => ({
+  name: DECLARATION_TOOL_NAME,
+  instruction: STRUCTURE_INSTRUCTION_TOOL,
+  textPath: 'declaration',
+  tool: (/** @type {{calls: any[]}} */ box) => declarationTool(box, { catalogue, verdictType }),
+});
+
+/** The declaration ask, over the shared ladder. `declaration` is `artifact`
+ * under this channel's own name — the flow below reads a declaration, not an
+ * anonymous artifact, and one word for two things is how a reader loses which.
+ * @param {{messages: any[], generate: Function, mode: 'tool'|'text', retries: number,
+ *   label: string, book: ReturnType<typeof makeCostBook>, catalogue: Record<string, any>,
+ *   verdictType: string}} o
+ */
+async function askDeclaration({ messages, generate, mode, retries, label, book, catalogue, verdictType }) {
+  const r = await askStructured({
+    messages, generate, mode, retries, label, book, channel: declarationChannel({ catalogue, verdictType }),
+  });
+  return { ...r, declaration: r.artifact };
 }
 
 /**
@@ -1391,7 +1534,7 @@ export async function authorClose({
       // a readout quoting a number the loop does not obey is a second
       // instrument, and this file's own history is what that costs.
       onPhase('author-call', { call: label, i, of: revisionCap });
-      const ask = await askDeclaration({ messages, generate, mode: structuredMode, retries: retryCap, label, book, catalogue });
+      const ask = await askDeclaration({ messages, generate, mode: structuredMode, retries: retryCap, label, book, catalogue, verdictType });
       messages = ask.convo;
 
       // The cap tripped BEFORE this ask made any call at all, so there is no

package/src/authoring.js

@@ -72,7 +72,8 @@
 // flagged a `runClose` naming collision between the kind executor and
 // src/ralph.js; the public surface is settled once at M4, not piecemeal.
 
-import { normalizeParser } from './kinds.js';
+import { normalizeParser, MAX_JUDGED_PATHS, JUDGED_FLOOR_KIND } from './kinds.js';
+import { JUDGE_RULE_IDS, validateCard } from './judged.js';
 import { isObj, isNonEmptyString, hasNestedQuantifier, globToPrefix } from './validate.js';
 
 /** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
@@ -95,9 +96,15 @@ import { isObj, isNonEmptyString, hasNestedQuantifier, globToPrefix } from './va
 /** the whole menu, in ascending order of what it takes to render the verdict */
 export const VERDICT_CLASSES = Object.freeze(['green', 'soft-green', 'hitl']);
 /** declared-but-locked: selecting one is COUNTED demand, never an admission.
- * `hitl` LEFT this list at N4 slice 1 (see `src/job.js`'s twin) — the class is
- * built, and its battery is below. `soft-green` waits for the judged floor. */
-export const LOCKED_CLASSES = Object.freeze(['soft-green']);
+ * `hitl` LEFT this list at N4 slice 1 and `soft-green` at softgreen module 3
+ * (see `src/job.js`'s twin, `LOCKED_VERDICTS`, which moved in the same commit) —
+ * the judged floor its lock was waiting on is built, wired and calibrated.
+ *
+ * EMPTY is a true statement about a closed menu, not F59's absent-as-empty: the
+ * mechanism is read at call time from this constant, so re-locking a class is
+ * one edit and every counted refusal comes back with it. */
+/** @type {readonly string[]} */
+export const LOCKED_CLASSES = Object.freeze([]);
 /** the classes v1 actually builds */
 export const LIVE_CLASSES = Object.freeze(VERDICT_CLASSES.filter((c) => !LOCKED_CLASSES.includes(c)));
 
@@ -117,10 +124,11 @@ const CLASS_RANK = Object.freeze({ green: 0, 'soft-green': 1, hitl: 2 });
  * `CLASS_BY_VERDICT` exist to stop, defeated from ABOVE by never letting the
  * illegal pair be formed.
  *
- * INERT IN v1 BY CONSTRUCTION, which is why it is cheap now: every LIVE kind is
- * mechanical, so no declaration a v1 catalogue can express reaches above green.
- * It is written before the second class exists so the first soft-green kind is
- * not the thing that discovers the question.
+ * NO LONGER INERT: `human-confirms` (N4 slice 1) and `judged-floor` (softgreen
+ * module 2) are both live and both above green, so a green declaration naming
+ * one is a real red rather than a hypothetical. `classMenu` below is the other
+ * half of the same rule, applied one step earlier — the composer is never handed
+ * a kind this would refuse.
  *
  * A kind the catalogue does not know contributes NOTHING — it already carries an
  * `unknown-kind` red, and guessing a class for it would be deriving the promise
@@ -154,6 +162,49 @@ export function closeCeiling(declaration, catalogue = KIND_CATALOGUE) {
   return top;
 }
 
+/**
+ * THE MENU A JOB OF THIS CLASS MAY EXPRESS — the ceiling rule, moved one step
+ * EARLIER, to the moment the composer is handed its vocabulary.
+ *
+ * `closeCeiling` refuses an above-ceiling kind AFTER a paid call has composed a
+ * declaration around it. That is a late red for an illegal pick the composer was
+ * shown in its own catalogue and its own tool schema — and the standing rule is
+ * the opposite: wherever only a closed set can satisfy a field, hand over the
+ * enumerated set, so the illegal value is INEXPRESSIBLE rather than rejected
+ * after the fact (the `check-passes(name)` model). A green job is therefore never
+ * shown `judged-floor` or `human-confirms` at all.
+ *
+ * ONLY THE MENU NARROWS. The VALIDATOR keeps the whole catalogue, deliberately:
+ * a model that names a kind it was never offered must be told which RULE it
+ * broke (`class-ceiling`), not that the kind does not exist (`unknown-kind`) —
+ * one is the truth and the other invites it to invent a spelling.
+ *
+ * `null` means UNFILTERED and exists for callers inspecting the catalogue itself
+ * (the schema/coverage suite). Every composing call site passes the user's own
+ * picked class; `authorPrompt` already throws without one.
+ * @param {string|null} verdictType
+ * @param {Record<string, KindSpec>} [catalogue]
+ * @returns {string[]} kind names at or below the picked class, in catalogue order
+ */
+export function classMenu(verdictType, catalogue = KIND_CATALOGUE) {
+  const names = Object.keys(catalogue);
+  if (verdictType === null || verdictType === undefined) return names;
+  const picked = String(verdictType);
+  if (!Object.hasOwn(CLASS_RANK, picked)) {
+    throw new Error(`[authoring] no verdict class "${picked}" — the menu a composer may be handed is keyed by the `
+      + `class the user picked, one of ${VERDICT_CLASSES.join(', ')}, and guessing one would compose under a promise `
+      + 'nobody made');
+  }
+  return names.filter((k) => {
+    const spec = catalogue[k];
+    if (!spec || !Object.hasOwn(CLASS_RANK, spec.verdictClass)) {
+      throw new Error(`[authoring] catalogue kind "${k}" declares no verdict class — every kind states the class of `
+        + `verdict it can honestly render (one of ${VERDICT_CLASSES.join(', ')})`);
+    }
+    return CLASS_RANK[spec.verdictClass] <= CLASS_RANK[picked];
+  });
+}
+
 // ── 1. THE KIND CATALOGUE ────────────────────────────────────────────────────
 
 /**
@@ -229,15 +280,33 @@ export const KIND_CATALOGUE = Object.freeze({
     shape: 'allowPrefixes: string[], requireNonEmpty: true',
     asserts: 'the set of files this run changed must be non-empty and must lie wholly inside allowPrefixes.',
   }),
-  // LOCKED: named so declaring one is COUNTED DEMAND rather than an unknown-kind
-  // typo (D13 forward-compat point 2). Disclosure is not admission — these do
-  // not run in v1, and `close[]` on disk stays predicate-only and shape-enforced
-  // (src/job.js:442), so the inexpressibility that is already free stays free.
+  // LIVE at softgreen module 2, and the only kind that BUYS its measurement: a
+  // pinned toolless judge extracts facts WITH QUOTES from each named artifact and
+  // an arbiter-owned rulebook renders the verdict over them (src/judged.js). The
+  // judge never says whether anything passed — a model asked "did this pass?" is
+  // a model that can be argued with, and bareguard's A/B measured that
+  // `judgeLocate` is not injectable where `judgeVerdict` is.
+  //
+  // `card` is the signer's own rubric, compiled to ENUMERATED items: `rule`
+  // SELECTS from the rulebook we implement, so a rule we do not own is
+  // inexpressible rather than rejected late, and `text` is the signer's words —
+  // what a red is explained WITH, never what a red is decided BY. `paths` names
+  // the AUTHORITATIVE artifacts, selected from the seed listing like every other
+  // path, never the worker's summary of what it did.
+  //
+  // No `timeoutMs` and no `env`: this kind spawns nothing. Its own bounds are the
+  // arbiter's (the retry ladder and the artifact ceiling live in src/kinds.js),
+  // because a declaration that could widen them is a declaration that can spend.
   'judged-floor': Object.freeze({
     verdictClass: 'soft-green',
-    required: Object.freeze([]), optional: Object.freeze([]), pathParams: Object.freeze([]), locked: true,
-    shape: 'LOCKED — not available in v1',
-    asserts: 'a judged score must clear a floor. Declaring it is recorded as demand; it will not run.',
+    required: Object.freeze(['card', 'paths']),
+    optional: Object.freeze([]),
+    pathParams: Object.freeze(['paths']),
+    shape: `card: {items: [{rule: ${JUDGE_RULE_IDS.join('|')}, text: string}]}, paths: string[] (at most ${MAX_JUDGED_PATHS})`,
+    asserts: 'a pinned judge extracts facts and VERBATIM quotes from each named artifact, and an arbiter-owned rulebook '
+      + 'renders pass/fail per card item over those facts — first red wins, and anything it cannot be sure of is a red. '
+      + 'Name one card line per thing you actually look for, in the order you look for them, and name the real files the '
+      + 'work lands in. It is never offered to the agent as an in-run check.',
   }),
   // LIVE at N4 slice 1, and the ONLY kind that does not measure anything: it
   // does not RUN, it PAUSES the run and hands the tree to a person (ruling 1).
@@ -651,7 +720,15 @@ const MECHANICAL_GUARDS = Object.freeze([
 
 export const CLASS_BATTERIES = Object.freeze({
   green: Object.freeze({ locked: false, guards: MECHANICAL_GUARDS }),
-  'soft-green': Object.freeze({ locked: true, guards: null }),
+  // RULING 4 (hamr, 2026-08-18, selected): **softgreen INHERITS green's
+  // battery** — the same precedent hitl was built on. A softgreen job is a green
+  // job's agent-authored plan under the same arbiter with one judged stage at the
+  // end; the mandatory guards are about what the WORKER may not do, and nothing
+  // about a judged final stage relaxes any of them. It is the SAME OBJECT rather
+  // than a second spelling of the same prose: a fix to green's battery must flow
+  // here with no second edit, and `classGuards` deep-copies on the way out so
+  // sharing cannot become weakening.
+  'soft-green': Object.freeze({ locked: false, guards: MECHANICAL_GUARDS }),
   // OPEN-1, RULED (hamr, in-turn, 2026-08-13): **hitl inherits the green
   // mechanical guards and adds nothing a human stage cannot see.** D5 makes the
   // battery mandatory, shown-and-fixed and un-removable, and PRD v1.57 §2 keys it
@@ -948,7 +1025,29 @@ function scopeOfJob(declaration, idx, guards) {
  * stage — applied to the one population that decides whether the law fires at
  * all.
  */
-const AT_MOST_ONCE_KINDS = Object.freeze(['files-changed', 'human-confirms']);
+const AT_MOST_ONCE_KINDS = Object.freeze(['files-changed', 'human-confirms', 'judged-floor']);
+
+/** why each at-most-once kind is at most once, in the author's own terms. A map
+ * rather than a chain of conditionals: a kind added to the list above with no
+ * reason here is a red nobody can act on, and this fails loudly instead.
+ * @type {Record<string, (label: string, owner: string) => string>} */
+const AT_MOST_ONCE_REASON = Object.freeze({
+  'files-changed': (label, owner) => `stage "${label}" is a second files-changed stage — "${owner}" already declares `
+    + 'which files this job may change. Stages are ANDed, so two of them mean the intersection of two prefix sets, '
+    + 'which is itself a prefix set and already says the same thing in one stage; what a second one does add is a '
+    + 'second answer to what this job\'s scope IS',
+  'human-confirms': (label, owner) => `stage "${label}" is a second human-confirms stage — "${owner}" already asks the `
+    + 'person. One signer, one judge (ruling 4), asked ONCE at the end: a second door is a second verdict, and the run '
+    + 'has no way to say which of them was the one it stopped for',
+  // softgreen module 3. The judged floor is the close's ONE judged ruler: two of
+  // them are two bars for one verdict class, each buying its own paid calls, and
+  // first-red-wins means the second only ever runs when the first was satisfied —
+  // so its only reachable effect is to spend money re-judging a tree that already
+  // cleared the bar the signer signed. One card, one calibration set, one ruler.
+  'judged-floor': (label, owner) => `stage "${label}" is a second judged-floor stage — "${owner}" is already this `
+    + 'close\'s judged ruler. One card and one calibration set decide one bar: a second judged stage is a second bar '
+    + 'for the same verdict, and it buys its own paid calls to re-judge a tree the first one already passed',
+});
 
 /** the kinds NO ONE runs as an in-run ruler — ruling 5's law, as data. A
  * declaration that offers one is a red rather than a normalization: the signer
@@ -1156,14 +1255,12 @@ export function validateDeclaration(declaration, opts = {}) {
     if (AT_MOST_ONCE_KINDS.includes(s.kind)) {
       const owner = kindOwners.get(s.kind);
       if (owner !== undefined) {
-        red('duplicate-kind', `${at}.kind`, s.kind === 'human-confirms'
-          ? `stage "${label}" is a second ${s.kind} stage — "${owner}" already asks the person. One signer, one judge `
-            + '(ruling 4), asked ONCE at the end: a second door is a second verdict, and the run has no way to say '
-            + 'which of them was the one it stopped for'
-          : `stage "${label}" is a second ${s.kind} stage — "${owner}" already declares `
-            + 'which files this job may change. Stages are ANDed, so two of them mean the intersection of two prefix sets, '
-            + 'which is itself a prefix set and already says the same thing in one stage; what a second one does add is a '
-            + 'second answer to what this job\'s scope IS', { kind: s.kind, stage: label, twin: owner });
+        const why = AT_MOST_ONCE_REASON[s.kind];
+        if (!why) {
+          throw new Error(`[authoring] "${s.kind}" is declared at-most-once with no stated reason — a red the author `
+            + 'cannot act on is worse than no rule');
+        }
+        red('duplicate-kind', `${at}.kind`, why(label, owner), { kind: s.kind, stage: label, twin: owner });
       } else kindOwners.set(s.kind, label);
     }
 
@@ -1192,6 +1289,30 @@ export function validateDeclaration(declaration, opts = {}) {
         + 'evidence package and the mechanical stages behind them would be silently deleted (the composition law: '
         + 'mechanical first, human last)', { kind: s.kind, stage: label, at: i, last: stages.length - 1 });
     }
+    // ── THE SAME LAW's judged half (design record 2026-08-17 §4.5: *mechanical
+    // stages FIRST, the judged stage AFTER, first-red-wins*). The human rule is
+    // stated as "last" because a person is the top of the hierarchy; the judged
+    // rule is stated as "after the mechanical ones", because a human stage may
+    // legally follow it — mechanical → judge → person is the full composition.
+    //
+    // What it costs to admit is the same both ways round: first-red-wins means a
+    // judged stage in front of a mechanical one BUYS PAID CALLS to grade a tree
+    // the free stages would have refused for nothing — and if the judge passes it
+    // the mechanical red still lands, so the money bought no verdict either.
+    // A SECOND judged stage is NOT this red (it is `duplicate-kind`, emitted
+    // above): one problem, one red, in one vocabulary.
+    if (s.kind === JUDGED_FLOOR_KIND) {
+      const behind = stages.slice(i + 1).filter((/** @type {any} */ x) => isObj(x) && isNonEmptyString(x.kind)
+        && catalogue[x.kind] && CLASS_RANK[catalogue[x.kind].verdictClass] < CLASS_RANK['soft-green']);
+      if (behind.length) {
+        red('judged-stage-order', `${at}.kind`, `stage "${label}" is judged and runs BEFORE the mechanical `
+          + `stage${behind.length > 1 ? 's' : ''} ${behind.map((/** @type {any} */ x) => `"${x.name}"`).join(', ')}. `
+          + 'The close is first-red-wins and a judged stage buys a paid call per artifact: put every stage a command '
+          + 'can decide in front of it, so the free rulers shield the expensive one (the composition law: mechanical '
+          + 'first, judge after)',
+        { kind: s.kind, stage: label, at: i, behind: behind.map((/** @type {any} */ x) => x.name) });
+      }
+    }
 
     const p = s.params;
     if (!isObj(p)) { red('missing-field', `${at}.params`, `an object carrying: ${spec.required.join(', ')}`); return; }
@@ -1405,6 +1526,30 @@ function checkKind({ kind, params: p, at, red, scoped, label, populations, envOw
           + 'result — a human stage with nothing to ask is the bare "approve?" ruling 2 forbids');
       }
       break;
+    case 'judged-floor': {
+      // ONE spelling of what a card is, the JUDGE's own (`validateCard`, src/judged.js) —
+      // the same rule `normalizeParser` follows: the validator and the grader must agree
+      // about what a card MEANS, or the one that grades is the one nobody validated.
+      const cv = validateCard(p.card);
+      for (const detail of cv.reds) red('invalid-value', `${at}.params.card`, detail);
+      // the artifact list. The listing rule (`checkPaths`) judges whether each element
+      // EXISTS; this judges the shape and the bill — one paid call per artifact, so an
+      // unbounded list is a bill rather than a red (the MAX_TERMS sibling).
+      if (!strArray(p.paths)) {
+        red('invalid-value', `${at}.params.paths`, 'a non-empty array of repository-relative files to judge — the '
+          + 'AUTHORITATIVE artifacts, read off the seed listing, never the worker\'s summary of what it did');
+      } else if (new Set(p.paths.map(String)).size !== p.paths.length) {
+        // one artifact is one population, and a list naming it twice buys two paid
+        // calls over identical bytes — deduplicating it silently would leave the
+        // signer reading one list while the runner spent on another
+        red('invalid-value', `${at}.params.paths`, 'the same artifact is named twice — one artifact is one population, '
+          + 'and a duplicate buys a second paid call over identical bytes');
+      } else if (p.paths.length > MAX_JUDGED_PATHS) {
+        red('bounds', `${at}.params.paths`, `${p.paths.length} artifacts exceeds the ceiling of ${MAX_JUDGED_PATHS} — a `
+          + 'judged stage buys one call per artifact, and the ceiling is the arbiter\'s, not the declaration\'s');
+      }
+      break;
+    }
     default:
       red('unknown-kind', `${at}.kind`, `"${kind}" is in the catalogue but has no checker`, { kind });
   }