bareloop 0.25.1 → 0.26.0

package/types/authorflow.d.ts

@@ -1,3 +1,5 @@
+/** @param {boolean} isRepo @returns {typeof DESTINATION_FIELD_REPO} */
+export function destinationFieldFor(isRepo: boolean): typeof DESTINATION_FIELD_REPO;
 /** The frozen question set for a picked class. Throws on a locked or unknown
  * one: reaching here with either means admission did not refuse, which is a
  * bareloop bug, and failing loudly beats interviewing for a class we cannot run.
@@ -6,6 +8,32 @@ export function questionsFor(verdictType: string): any;
 /** The question numbers whose answer must be present for that class's interview
  * to be finished. @param {string} verdictType @returns {number[]} */
 export function requiredAnswersFor(verdictType: string): number[];
+/** The signed table's label for each of that class's question keys (PRD item
+ * 33's "The intake form (RULED)" ruling) — a key with no table row (hitl's own
+ * fourth) is simply absent, never a fabricated label. Throws on the same locked
+ * or unknown class {@link questionsFor} does, for the same reason.
+ * @param {string} verdictType @returns {Record<string|number, string>} */
+export function labelsFor(verdictType: string): Record<string | number, string>;
+/**
+ * THE REAL PROTECTIONS a person is shown, and what {@link runConfirmTurn}
+ * records as `accepted.protections` — fixes finding #1 from live run
+ * mu0voeo4 (2026-09-14): the confirm turn used to show whatever prose the
+ * MODEL invented for `protections`, and that run's model invented a
+ * "behavior-preservation guard" this build cannot check — no kind in the
+ * catalogue can verify runtime behaviour, and the author call's own note
+ * elsewhere says outright that behaviour-preservation is not composed here.
+ * This reads the SAME guards `classGuards` will actually compose into the
+ * close — one source, never a second hand-typed list — rendered through the
+ * frozen line in {@link GUARD_DESCRIPTIONS}, plus the write fence (a real,
+ * signed fence — {@link writeScopeBlock}'s own subject) when one is set.
+ * @param {{verdictType: string, lang: string, writeScope?: string[]|null}} o
+ * @returns {string[]}
+ */
+export function confirmProtections({ verdictType, lang, writeScope }: {
+    verdictType: string;
+    lang: string;
+    writeScope?: string[] | null;
+}): string[];
 /**
  * The mechanical seam between the catalogue and the schema, read BOTH ways: a
  * catalogue parameter with no schema would be silently undeclarable, and a schema
@@ -196,6 +224,44 @@ export function catalogueBlock(catalogue?: Record<string, any>, { verdictType }?
 export function instrumentsBlock(lang: string): string;
 /** The three laws. Stated to the author; enforced, where checkable, by M2. */
 export function lawsBlock(): string;
+/**
+ * WHAT MAY CHANGE, AND WHAT IS ONLY READ — replaces the old Q2 (PRD item 33 M3
+ * piece 3). Q2 used to ask the person, in prose, which files change and which
+ * are read-only; that decision is now Destination, PROVEN against the
+ * repository rather than typed (`docs/product/ITEM33-BUILD.md` "M3", ruling 2),
+ * and for a repo source Destination's answer IS the signed `writeScope` fence.
+ * This states that fact to the composer instead of letting it vanish along
+ * with Q2 — the same "nothing the composer received before may silently
+ * disappear" rule `applyGenreEnv` already keeps for a dropped env var.
+ *
+ * THROWS on an empty `writeScope`: Destination is a MANDATORY fence
+ * (`run-interview.mjs` refuses an empty answer at capture), so a caller
+ * reaching this with nothing to state is a bareloop wiring bug, not a job with
+ * no fence — a composer told it may change everything guards nothing.
+ * @param {string[]} writeScope
+ */
+export function writeScopeBlock(writeScope: string[]): string;
+/**
+ * THE CONFIRMED-PLAN BLOCK (PRD item 33 M3 piece 4) — present only when the
+ * person already ran a confirm turn (`runConfirmTurn`'s `accepted`). States
+ * the composition law as an ORDER over the ACCEPTED checks, exactly the
+ * pattern {@link writeScopeBlock} already is for the fence: "compose these
+ * checks and no other" rather than a code matcher over the goal prose
+ * (ruling 6). Protections are restated as unchanged, never as checks to add.
+ * Open questions the person's own fix rounds left unresolved (D3) are named
+ * so the composer states them in notes rather than silently deciding them.
+ * `notChecked` (fix #1, run mu0voeo4) is anything the person asked for that
+ * no listed check can verify — shown so the composer names the gap in its
+ * own notes rather than the plan quietly reading as if everything asked for
+ * is covered.
+ * @param {{checks: string[], protections: string[], openQuestions?: string[], notChecked?: string[]}} confirmed
+ */
+export function confirmedBlock(confirmed: {
+    checks: string[];
+    protections: string[];
+    openQuestions?: string[];
+    notChecked?: string[];
+}): string;
 /**
  * The whole authoring prompt, as one string.
  *
@@ -208,12 +274,19 @@ export function lawsBlock(): string;
  * the one thing that tells the composer what DONE is allowed to mean here; a
  * defaulted class would be the prompt answering a question the user was asked.
  *
+ * `writeScope` carries what the old Q2 used to (PRD item 33 M3 piece 3): Q2 is
+ * gone from the numbered interview, so what may change and what is read-only
+ * reaches the composer through {@link writeScopeBlock} instead, fed from
+ * Destination's own proven fence — never silently dropped.
+ *
  * @param {{answers: Record<string|number, string>, questions?: Record<string|number, string>,
  *   facts: any, listingBlock: string, lang: string, verdictType: string,
  *   guards: {name: string, kind: string, params: Record<string, any>, fill: string[]}[],
- *   ownedEnvNames?: string[], mode?: 'tool'|'text', catalogue?: Record<string, any>}} o
+ *   ownedEnvNames?: string[], mode?: 'tool'|'text', catalogue?: Record<string, any>,
+ *   writeScope?: string[]|null,
+ *   confirmed?: {checks: string[], protections: string[], openQuestions?: string[], notChecked?: string[]}|null}} o
  */
-export function authorPrompt({ answers, questions, facts, listingBlock, lang, verdictType, guards, ownedEnvNames, mode, catalogue }: {
+export function authorPrompt({ answers, questions, facts, listingBlock, lang, verdictType, guards, ownedEnvNames, mode, catalogue, writeScope, confirmed, }: {
     answers: Record<string | number, string>;
     questions?: Record<string | number, string>;
     facts: any;
@@ -229,6 +302,13 @@ export function authorPrompt({ answers, questions, facts, listingBlock, lang, ve
     ownedEnvNames?: string[];
     mode?: "tool" | "text";
     catalogue?: Record<string, any>;
+    writeScope?: string[] | null;
+    confirmed?: {
+        checks: string[];
+        protections: string[];
+        openQuestions?: string[];
+        notChecked?: string[];
+    } | null;
 }): string;
 /**
  * The seed read, as the model sees it: mechanical labels, no editorial. Per-stage
@@ -495,6 +575,109 @@ export function askStructured({ messages, generate, mode, retries, label, book,
     red: Red | null;
     budget: "cap-halt" | "pricing-red" | null;
 }>;
+/** The output channel. It records and acknowledges; it takes no action.
+ * @param {{calls: any[]}} box */
+export function confirmTool(box: {
+    calls: any[];
+}): {
+    name: string;
+    description: string;
+    parameters: Record<string, any>;
+    execute: (args: any) => Promise<string>;
+};
+/**
+ * The confirm turn's per-round prompt (model-facing, registered). Shows the
+ * person's own answers with their labels (the signed table's Field/Holds
+ * pairing, same as {@link authorPrompt}'s interview block), the survey or
+ * listing already paid for, the write fence, the detected language, "worse
+ * than before" when the person gave one (repo only), and — on a fix round —
+ * what the person asked to change.
+ * @param {{answers: Record<string|number, string>, questions: Record<string|number, string>,
+ *   labels?: Record<string|number, string>, facts?: any, listing?: string|null,
+ *   writeScope?: string[]|null, isRepo: boolean, lang: string, worseThanBefore?: string,
+ *   fixText?: string|null}} o
+ */
+export function confirmPrompt({ answers, questions, labels, facts, listing, writeScope, isRepo, lang, worseThanBefore, fixText }: {
+    answers: Record<string | number, string>;
+    questions: Record<string | number, string>;
+    labels?: Record<string | number, string>;
+    facts?: any;
+    listing?: string | null;
+    writeScope?: string[] | null;
+    isRepo: boolean;
+    lang: string;
+    worseThanBefore?: string;
+    fixText?: string | null;
+}): string;
+/**
+ * THE CONFIRM TURN: the $0 half (worse-than-before for a repo, a language
+ * pick when `lang` carries `detectLanguage`'s own `ambiguous` shape), then up
+ * to 2 PAID rounds (ruling 5) of draft → show → the person's menu pick
+ * (ruling 5 addendum). `ask` is the ONE interactive seam — an async function
+ * from a "what's being asked" descriptor to the person's answer, or `null`
+ * meaning input ended (the same signal `scripts/run-interview.mjs`'s own
+ * `nextLine()` already uses) — never a process exit here, because this is a
+ * library function, not a script. A `null` at ANY ask stops the whole turn as
+ * `confirm-abandoned`, spending nothing beyond whatever rounds already ran.
+ *
+ * D3's shape is enforced by the loop bound alone (`round <= 2`), never a
+ * counter checked after the fact: a "fix" on round 2 returns immediately —
+ * there is no 3rd call to make.
+ *
+ * @param {{verdictType: string, answers: Record<string|number, string>,
+ *   questions: Record<string|number, string>, labels?: Record<string|number, string>,
+ *   facts?: any, listing?: string|null, writeScope?: string[]|null, isRepo: boolean,
+ *   lang: string|{kind: 'ambiguous', candidates: string[], dir: string},
+ *   generate: Function, book: ReturnType<typeof makeCostBook>,
+ *   ask: (step: {kind: string, [k: string]: any}) => Promise<string|null>,
+ *   onPhase?: (phase: string, data?: any) => void, mode?: 'tool'|'text',
+ *   worseThanBefore?: string}} o
+ * @returns {Promise<{ok: boolean,
+ *   stop: null|'cap-halt'|'pricing-red'|'provider-red'|'artifact-red'|'confirm-abandoned'|'confirm-restart',
+ *   rounds: number,
+ *   accepted: {goal: string, checks: string[], protections: string[], lang: string,
+ *     worseThanBefore: string, openQuestions: string[], notChecked: string[]}|null,
+ *   reds: Red[], cost: any}>}
+ */
+export function runConfirmTurn({ verdictType, answers, questions, labels, facts, listing, writeScope, isRepo, lang, generate, book, ask, onPhase, mode, worseThanBefore: presetWorseThanBefore, }: {
+    verdictType: string;
+    answers: Record<string | number, string>;
+    questions: Record<string | number, string>;
+    labels?: Record<string | number, string>;
+    facts?: any;
+    listing?: string | null;
+    writeScope?: string[] | null;
+    isRepo: boolean;
+    lang: string | {
+        kind: "ambiguous";
+        candidates: string[];
+        dir: string;
+    };
+    generate: Function;
+    book: ReturnType<typeof makeCostBook>;
+    ask: (step: {
+        kind: string;
+        [k: string]: any;
+    }) => Promise<string | null>;
+    onPhase?: (phase: string, data?: any) => void;
+    mode?: "tool" | "text";
+    worseThanBefore?: string;
+}): Promise<{
+    ok: boolean;
+    stop: null | "cap-halt" | "pricing-red" | "provider-red" | "artifact-red" | "confirm-abandoned" | "confirm-restart";
+    rounds: number;
+    accepted: {
+        goal: string;
+        checks: string[];
+        protections: string[];
+        lang: string;
+        worseThanBefore: string;
+        openQuestions: string[];
+        notChecked: string[];
+    } | null;
+    reds: Red[];
+    cost: any;
+}>;
 /**
  * THE AUTHORING FLOW.
  *
@@ -531,9 +714,12 @@ export function askStructured({ messages, generate, mode, retries, label, book,
  *   onPhase?: (phase: string, data?: any) => void,
  *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   maxRevisions?: number, structureRetries?: number,
- *   structuredMode?: 'tool'|'text', catalogue?: Record<string, any>}} o
+ *   structuredMode?: 'tool'|'text', catalogue?: Record<string, any>, writeScope?: string[]|null,
+ *   priorCalls?: {label: string, costUsd: number|null, unpricedRounds: number}[]|null,
+ *   priorRaws?: any[]|null,
+ *   confirmed?: {checks: string[], protections: string[], openQuestions?: string[], notChecked?: string[]}|null}} o
  */
-export function authorClose({ workdir, seedRef, lang, verdictType, answers, questions, scout, listing, generate, seedReadFn, closeCtx, ceilingUsd, onPhase, onCall, maxRevisions, structureRetries, structuredMode, catalogue, }: {
+export function authorClose({ workdir, seedRef, lang, verdictType, answers, questions, writeScope, scout, listing, priorCalls, priorRaws, confirmed, generate, seedReadFn, closeCtx, ceilingUsd, onPhase, onCall, maxRevisions, structureRetries, structuredMode, catalogue, }: {
     workdir: string;
     seedRef: string;
     lang: string;
@@ -569,6 +755,19 @@ export function authorClose({ workdir, seedRef, lang, verdictType, answers, ques
     structureRetries?: number;
     structuredMode?: "tool" | "text";
     catalogue?: Record<string, any>;
+    writeScope?: string[] | null;
+    priorCalls?: {
+        label: string;
+        costUsd: number | null;
+        unpricedRounds: number;
+    }[] | null;
+    priorRaws?: any[] | null;
+    confirmed?: {
+        checks: string[];
+        protections: string[];
+        openQuestions?: string[];
+        notChecked?: string[];
+    } | null;
 }): Promise<any>;
 /** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
 /** the output channel's name. It takes no action; it carries the answer. */
@@ -604,114 +803,157 @@ export const REVISE_INSTRUCTION: string;
 export const STRUCTURE_INSTRUCTION_TOOL: string;
 export const STRUCTURE_INSTRUCTION_TEXT: string;
 /**
- * THE INTERVIEW, KEYED BY VERDICT CLASS (hamr's ruling, PRD v1.57 §2).
- *
- * One question set per GENRE has no terminating shape — genres are a fat long
- * tail that cannot be enumerated, and TYPES was the first specimen rather than
- * the pattern. One set per verdict CLASS has exactly three. Genre understanding
- * does not disappear: it moves into the COMPOSITION over the kind catalogue
- * (`CLASS_STATEMENTS` below, rendered into the authoring prompt), which is the
- * layer already built to hold it — the authoring call composes owned kinds and
- * cannot emit anything else (D2/D3), so a genre it has never seen is a
- * composition problem, not a catalogue problem.
- *
- * The GREEN set descends from questions 1–6 of the frozen TYPES set (prereg §5).
- * TWO slots have been deleted since, both because the interview was ASKING FOR
- * SOMETHING IT ALREADY HAD or already knew:
- *
- *   - D13's genre CONFIRM ("this looks like a type-fixing job, correct?") —
- *     superseded in full: the interview never asks about a genre again, and the
- *     refusal it carried MOVED to the composer, on the same counted
- *     `request-red` path (see `authorCloseForJob`);
- *   - "Is there a code repo I can look at? Where?" — DROPPED on hamr's ruling
- *     after he drove the terminal interview himself (2026-08-15, verbatim: *"drop
- *     Q6"*). The repository is a MANDATORY, STRUCTURED input already —
- *     `runInterview`'s own `repoPath`, which the runner takes from `--patient` and
- *     refuses to start without. Asking a person to re-type in prose a path the
- *     machine is holding in a variable is the SWE tax this product refuses, and
- *     it invites a second, drifting answer for the same fact (hamr's own answer
- *     on the live run was *"Yes — the patient itself."*). Nothing downstream lost
- *     anything: the scout reads `repoPath`, never the answer.
- *
- * Question 2 was WIDENED in the same ruling: it now asks for the read-or-draw-from
- * files as well as the ones that change. The two halves belong in one answer
- * because they are one decision for the person answering — what the work touches,
- * and what it touches only to look at.
- *
- * The five that remain are genre-neutral, which is why every generalisation so far
- * has deleted a slot rather than reworded one. They are NUMBERED CONTIGUOUSLY from
- * 1: the number a person sees is the key their answer is filed under, and a gap
- * would be a hole in a form nobody can explain.
+ * THE UNIFIED INTAKE FORM (PRD item 33 M3 piece 3, `docs/product/ITEM33-BUILD.md`
+ * "M3", and the 2026-09-10 signed ruling "The intake form (RULED)" in
+ * `docs/product/PRD.md` item 33). Motivated by run `mtv8jihy` (F159): the OLD
+ * five-question green set produced a rubric compiled onto doc-comment rules —
+ * the wrong bar for what the person actually asked — because Q2 asked in prose
+ * for a decision the machine can prove instead, and Q3/Q5 asked the same "what
+ * must not go wrong" question twice from two directions.
+ *
+ * THE SAME SIX FIELDS FOR GREEN AND SOFT-GREEN, in the order a person sees them:
+ *
+ *   Source            replaces the read half of the old Q2 — MECHANICAL, proven
+ *                      against the machine ($0), never typed as free prose.
+ *   Destination        replaces the change half of the old Q2 (and, for a repo
+ *                      source, IS the signed `writeScope` fence) — MECHANICAL,
+ *                      same reason.
+ *   Goal               the old Q1, unchanged: "What do you want done?"
+ *   What success looks like   the old Q4, unchanged: a machine-countable check.
+ *   Guardrails         the old Q3 ("must not change") and Q5 ("worse than
+ *                      before") JOINED into one field — they were always one
+ *                      decision answered twice, and Q5 already only mattered for
+ *                      a repo source (the M3 confirm turn, not built in this
+ *                      piece, is where the repo-only half of it gets asked again
+ *                      if needed).
+ *   Judge examples     soft-green only — the old Q7 verbatim ("one you'd pass and
+ *                      one you'd fail, and say why"). The old Q6 ("what separates
+ *                      a pass from a fail") is retired as its own question: the
+ *                      "why" lines of a real pass/fail pair are what the rubric
+ *                      card compiles from (`cardauthor.js`), and asking the
+ *                      differentiator twice — once in the abstract, once against
+ *                      a real example — is the same double-ask Q3/Q5 already were.
+ *
+ * SOURCE and DESTINATION ARE MECHANICAL FIELDS, not entries in the numbered
+ * question record below: `runInterview`'s `answers` dict is what a close's
+ * composer prompt quotes verbatim (Q<n>/A<n>), and quoting a machine-proven fact
+ * back at the model as if a person had typed it would be the model reading a
+ * fabricated conversation. Their WORDING still lives here (`SOURCE_FIELD`,
+ * `DESTINATION_FIELD_REPO`, `DESTINATION_FIELD_PLAIN`, immediately below) so
+ * `scripts/run-interview.mjs` prints library text and nothing of its own, exactly
+ * as ruling 1 requires for the free-text questions.
+ *
+ * The free-text trio (soon quartet, soft-green only) IS numbered contiguously
+ * from 1 — the number a person sees is the key their answer is filed under, and
+ * that is what `questionsFor`/`requiredAnswersFor`/`QUESTION_SETS` still expose,
+ * unchanged in shape, to every existing caller.
  */
-export const GREEN_QUESTIONS: Readonly<{
-    1: "What do you want done?";
-    2: "Which files or folders should change? And which files should the work read or draw from (they stay untouched)?";
-    3: "Is there anything that must not change?";
-    4: "How do you check today whether it's working?";
-    5: "What would make you say this came back worse than before?";
+export const SOURCE_FIELD: Readonly<{
+    id: "source";
+    kind: "mechanical";
+    label: "Source";
+    prompt: "A local folder, subfolder or file, or one URL the machine can reach (no login, no setup).";
+}>;
+/** Destination's wording when Source resolved to a git repo: the answer IS the
+ * signed `writeScope` fence (ITEM33-BUILD.md M3 ruling 2). */
+export const DESTINATION_FIELD_REPO: Readonly<{
+    id: "destination";
+    kind: "mechanical";
+    label: "Destination";
+    prompt: string;
+}>;
+/** Destination's wording for every other kind of Source (a plain folder, a
+ * file, a URL): a directory the run may write into, never a filename
+ * (2026-09-12 Destination correction, PRD item 33). */
+export const DESTINATION_FIELD_PLAIN: Readonly<{
+    id: "destination";
+    kind: "mechanical";
+    label: "Destination";
+    prompt: string;
 }>;
 /**
- * THE HITL SET (N4 slice 1) — the green questions BYTE FOR BYTE, plus one.
+ * THE FREE-TEXT TRIO EVERY CLASS SHARES: Goal, What success looks like,
+ * Guardrails — numbered contiguously from 1. This is what `answers[1..3]` are
+ * filed under for every class; soft-green appends a fourth
+ * (`SOFTGREEN_QUESTIONS`) and hitl appends a different fourth
+ * (`HITL_QUESTIONS`), each its own next number rather than a fixed one, so a
+ * future trim of this trio renumbers instead of leaving a gap.
  *
- * The five are unchanged deliberately rather than economically: the
- * mechanical-first composition law (2026-08-07) says every hitl close is
- * *deterministic stages first, judge minimal, human last*, so a hitl job needs
- * exactly the same mechanical facts a green one does — what changes, what must
- * not, how it is checked today, what "worse" looks like. Rewording them would
- * fork one interview into two that drift.
- *
- * The last one is the only thing the green set cannot supply, and it is not a
- * flourish: `human-confirms` requires an `ask` — the question the signer answers
- * at the end of the run — and nothing else in the interview names it. Without it
- * the composer would have to invent what a person is deciding, which is the one
- * thing a human stage must never have done for it. It is the SPREAD's next number
- * rather than a fixed one, so a green-side deletion renumbers it instead of
- * leaving a gap (it was 7 while the green set held six, and is 6 now it holds five).
+ * THE TEXT IS THE SIGNED TABLE'S "Holds" COLUMN, VERBATIM (PRD item 33's
+ * 2026-09-10 "The intake form (RULED)" ruling, `docs/product/PRD.md`) — not the
+ * old worded questions ("What do you want done?", "How do you check today
+ * whether it's working?", "...worse than before?"). Motivated by run `mtv8jihy`
+ * (F159, `docs/logs/FINDINGS.md`): a rulebook this prompt commit did not touch
+ * still had to compile against a card built from a person's actual bar, and the
+ * old wording never matched what got signed — this reshape (commit 1ac4d05)
+ * trimmed the SET to three slots but left their PROSE unreconciled with the
+ * table it was meant to realize. `FIELD_LABELS` (below) carries the matching
+ * label for each key, so a caller wanting BOTH shows them together — see
+ * `authorPrompt`'s interview block and `scripts/run-interview.mjs`.
  */
-export const HITL_QUESTIONS: Readonly<{
-    6: "When you look at the finished result yourself, what are you deciding?";
-    1: "What do you want done?";
-    2: "Which files or folders should change? And which files should the work read or draw from (they stay untouched)?";
-    3: "Is there anything that must not change?";
-    4: "How do you check today whether it's working?";
-    5: "What would make you say this came back worse than before?";
+export const GREEN_QUESTIONS: Readonly<{
+    1: "what you want to achieve";
+    2: "checks a machine can count";
+    3: "what must not happen or change";
+}>;
+/**
+ * The signed table's own label for each of {@link GREEN_QUESTIONS}' keys — "the
+ * Field column", where {@link GREEN_QUESTIONS} is "the Holds column". Kept as a
+ * SEPARATE map rather than folding the label into the question string itself:
+ * every existing caller of `questionsFor`/`requiredAnswersFor`/`QUESTION_SETS`
+ * (`src/authorjob.js`, `src/cardauthor.js`, `scripts/run-interview.mjs`) treats
+ * a question as a plain string handed verbatim into a prompt or a `Q<n>. `
+ * line, and folding a label in would change that shape for every one of them.
+ * A caller that wants the label calls {@link labelsFor} exactly the way it
+ * calls `questionsFor` — additive, nothing existing breaks.
+ */
+export const FIELD_LABELS: Readonly<{
+    1: "Goal";
+    2: "What success looks like";
+    3: "Guardrails";
+}>;
+/** The soft-green quartet's own key for Judge Examples — exported so
+ * `cardauthor.js` reads the SAME number this module files the answer under,
+ * rather than a second, hand-typed "6"/"7". */
+export const SOFTGREEN_JUDGE_EXAMPLES_KEY: number;
+/** The Judge Examples question — the signed table's own Holds text, verbatim
+ * ("one pass, one fail, and why"), not the old worded Q7 ("Give one example
+ * you'd pass and one you'd fail, and say why."). Exported so `cardauthor.js`'s
+ * prompt and this module's own `SOFTGREEN_QUESTIONS` render the identical
+ * string; its label ("Judge examples") lives in `SOFTGREEN_FIELD_LABELS`. */
+export const JUDGE_EXAMPLES_QUESTION: "one pass, one fail, and why";
+/** {@link FIELD_LABELS} plus Judge Examples' own label, for the soft-green set. */
+export const SOFTGREEN_FIELD_LABELS: Readonly<{
+    1: "Goal";
+    2: "What success looks like";
+    3: "Guardrails";
 }>;
 /**
- * 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.
+ * THE SOFTGREEN SET — the green trio plus Judge Examples. A judged close needs
+ * exactly this one more thing the green set cannot supply: a real pass/fail
+ * pair in the person's own words, which module 4 (`cardauthor.js`) compiles
+ * into the signed rubric card and the frozen calibration set. It rides in
+ * `answers` and reaches the composer verbatim through the prompt's interview
+ * block, exactly as every other free-text answer does — this module derives
+ * nothing from it.
  */
 export const SOFTGREEN_QUESTIONS: Readonly<{
-    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.";
-    1: "What do you want done?";
-    2: "Which files or folders should change? And which files should the work read or draw from (they stay untouched)?";
-    3: "Is there anything that must not change?";
-    4: "How do you check today whether it's working?";
-    5: "What would make you say this came back worse than before?";
+    1: "what you want to achieve";
+    2: "checks a machine can count";
+    3: "what must not happen or change";
+}>;
+/**
+ * THE HITL SET (N4 slice 1, kept in code only — never offered in the form or
+ * anywhere customer-facing, PRD item 33 M3 ruling 8) — the green trio plus one.
+ * `human-confirms` requires an `ask`, the question the signer answers at the
+ * end of the run, and nothing else in the interview names it; without it the
+ * composer would have to invent what a person is deciding. It is the green
+ * set's next number, not a fixed one, so a green-side trim renumbers it too.
+ */
+export const HITL_QUESTIONS: Readonly<{
+    1: "what you want to achieve";
+    2: "checks a machine can count";
+    3: "what must not happen or change";
 }>;
 /**
  * The three sets, all LIVE as of softgreen module 3. The locked shape stays
@@ -721,11 +963,17 @@ export const SOFTGREEN_QUESTIONS: Readonly<{
  * 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}>}
+ * `labels` travels ALONGSIDE `questions`, one label per key that the signed
+ * table names one for (PRD item 33 M3 piece 3's wording fix) — hitl's own
+ * fourth question has no table row (it is never customer-facing, ruling 8) and
+ * so carries none; a reader finding no label for a key falls back to showing
+ * none, never a fabricated one.
+ * @type {Record<string, {locked: boolean, questions: Record<string|number, string>|null, labels: Record<string|number, string>, required: readonly number[]|null}>}
  */
 export const QUESTION_SETS: Record<string, {
     locked: boolean;
     questions: Record<string | number, string> | null;
+    labels: Record<string | number, string>;
     required: readonly number[] | null;
 }>;
 /**
@@ -739,6 +987,69 @@ export const QUESTION_SETS: Record<string, {
  * @type {Record<string, string|null>}
  */
 export const CLASS_STATEMENTS: Record<string, string | null>;
+/**
+ * Asked ONLY for a repo source (ruling 2 addendum's D7) — a plain folder or a
+ * URL has no "before" a repo's own history gives it to compare against. This
+ * is the OLD Q5 wording, verbatim ("What would make you say this came back
+ * worse than before?"), which M3 piece 3's reshape folded into Guardrails —
+ * it survives here as its OWN field because the confirm turn (ruling 5's
+ * 2026-09-13 addendum) includes it as a constraint only when the person
+ * actually gave one, and folding it silently into the Guardrails free-text
+ * slot would lose that "present or absent" distinction. An empty answer is
+ * "nothing beyond what Guardrails already said" and is not required — see
+ * the frozen-wording test below: this phrase appears NOWHERE in
+ * {@link questionsFor}'s own sets, so a caller cannot double-ask it by
+ * reading the wrong table.
+ */
+export const WORSE_THAN_BEFORE_FIELD: Readonly<{
+    id: "worseThanBefore";
+    kind: "mechanical";
+    label: "Worse than before";
+    prompt: "What would make you say this came back worse than before?";
+}>;
+/**
+ * Asked ONLY when `src/detectlang.js`'s `detectLanguage` reports its
+ * `ambiguous` outcome — two supported languages' manifests at the same
+ * (nearest) directory level (M3 ruling 3, point 3). The candidate list is
+ * NOT embedded here: it travels with the caller's own `ambiguous` result
+ * (`langResult.candidates`), so this module never hand-types a second copy
+ * of the supported-language set. An unsupported pick still goes through the
+ * existing `language-unsupported` refusal — this field only offers a choice
+ * among the candidates `detectLanguage` actually found.
+ */
+export const LANGUAGE_PICK_FIELD: Readonly<{
+    id: "language";
+    kind: "mechanical";
+    label: "Language";
+    prompt: "This repo has more than one supported language's manifest at the same level. Which one is this job about?";
+}>;
+/**
+ * THE CONFIRM TURN'S MENU — a structured CHOICE the person picks from after
+ * each round, never free text matched against a pattern (ruling 6's "no
+ * hand-authored check matcher" reasoning applies here too: the person's own
+ * reply is read as one of these four keys, never parsed for intent).
+ *   confirm     — sign the plan and the drafted goal sentence as shown.
+ *   fix         — free text describing what to change; feeds round r+1, up
+ *                 to the 2-round cap (ruling 5); after round 2 a "fix" is
+ *                 passed to the composer verbatim and shown at signing as an
+ *                 open question rather than spending a 3rd call (D3).
+ *   type-goal   — the person's own sentence REPLACES the drafted goal,
+ *                 verbatim (redacted); everything else in the plan stands.
+ *   start-over  — abandon this confirm turn; the person reruns the
+ *                 interview from the beginning (`confirm-restart`).
+ * @type {Record<'confirm'|'fix'|'type-goal'|'start-over', string>}
+ */
+export const CONFIRM_MENU: Record<"confirm" | "fix" | "type-goal" | "start-over", string>;
+/**
+ * PLAIN-ENGLISH lines for the guards `classGuards` can compose, keyed by
+ * guard NAME — frozen beside {@link CONFIRM_MENU} because both are constants
+ * the confirm turn shows a person verbatim. One entry per guard that exists
+ * in `MECHANICAL_GUARDS` (`src/authoring.js`); {@link confirmProtections}
+ * throws if a guard `classGuards` hands back has no line here, so a battery
+ * that grows a guard fails loudly instead of showing a blank description.
+ * @type {Record<string, string>}
+ */
+export const GUARD_DESCRIPTIONS: Record<string, string>;
 export const AUTHOR_SYSTEM: string;
 /**
  * ONE schema per PARAMETER NAME, composed into kinds by the catalogue's own
@@ -967,6 +1278,24 @@ export const PARAM_SCHEMAS: Readonly<{
         description: string;
     };
 }>;
+export const CONFIRM_TOOL_NAME: "confirm_plan";
+/** Acknowledgement text the confirm tool's `execute` returns — mirrors
+ * {@link DECLARATION_ACK}'s role: an output channel that records and
+ * acknowledges, takes no action, and ends the call the moment it fires
+ * (`makeLoopGenerate` stops the loop on any tool execute). */
+export const CONFIRM_ACK: "plan received";
+/** the confirm channel's own STRUCTURE_INSTRUCTION_TOOL analogue, shown after
+ * a malformed reply so the retry names the ONE required shape rather than
+ * repeating the whole system prompt */
+export const CONFIRM_STRUCTURE_INSTRUCTION: string;
+/**
+ * The confirm turn's system prompt (model-facing, registered — a commit
+ * touching this needs Failure/Addresses/Corrects labels, `src/promptregisters.js`).
+ * States ruling 6 ("a genre never adds a check the goal did not ask for") as
+ * an ORDER to the model itself, the same register {@link AUTHOR_SYSTEM} and
+ * {@link CLASS_STATEMENTS} already use, rather than a code matcher over prose.
+ */
+export const CONFIRM_SYSTEM: string;
 export type Red = {
     code: string;
     path: string;