bareloop 0.45.0 → 0.46.0

package/src/learnstore.js

@@ -0,0 +1,154 @@
+// The thin reader/writer around src/learn.js (cross-run learnings, ITEM33-BUILD.md rev 2). All file IO lives here and
+// the pure rules live in learn.js; nothing in either file can reach a model.
+//
+// ONE ledger per user: `<keys home>/learn/ledger.json` (~/.config/bareloop/learn/ledger.json in production; tests inject a
+// scratch home and never create the real directory). It lives outside every person's repo, is written atomically
+// (temp file + rename) and mode 600, and every string in it passes the one secret inventory before it is written.
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync, chmodSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { keysHome } from './keysfile.js';
+import { readConfig } from './config.js';
+import { emptyLedger, redactDeep, countLedger, holdPending, releasePending, recordHealth, buildCards, placeOf, renderHints } from './learn.js';
+import { stageQuestionsByName } from './stagewords.js';
+
+/**
+ * `<home>/learn/ledger.json`.
+ * @param {string} [home] test seam; production never passes it
+ * @returns {string}
+ */
+export function ledgerPath(home) {
+  return join(keysHome(home), 'learn', 'ledger.json');
+}
+
+/**
+ * Read the ledger. A missing file is an empty ledger; an unreadable or wrong-shaped one is reported as `problem` (and the
+ * writer then refuses to replace it: an append-only record is never silently reset).
+ * @param {string} [home]
+ * @returns {{ledger: import('./learn.js').Ledger, exists: boolean, problem: string|null}}
+ */
+export function readLedger(home) {
+  const file = ledgerPath(home);
+  if (!existsSync(file)) return { ledger: emptyLedger(), exists: false, problem: null };
+  try {
+    const d = JSON.parse(readFileSync(file, 'utf8'));
+    if (!d || typeof d !== 'object' || d.version !== 1 || !Array.isArray(d.rows) || !Array.isArray(d.pending)) {
+      return { ledger: emptyLedger(), exists: true, problem: `${file} is not a version-1 learnings ledger — fix or remove it` };
+    }
+    return { ledger: { ...emptyLedger(), ...d }, exists: true, problem: null };
+  } catch (/** @type {any} */ e) {
+    return { ledger: emptyLedger(), exists: true, problem: `${file} is not readable JSON (${e?.code ?? 'parse error'}) — fix or remove it` };
+  }
+}
+
+/**
+ * Write the ledger atomically (temp + rename, mode 600), every string masked through the one secret inventory.
+ * @param {import('./learn.js').Ledger} ledger @param {string} [home]
+ * @returns {string} the file written
+ */
+export function writeLedger(ledger, home) {
+  const file = ledgerPath(home);
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(redactDeep(ledger), null, 1)}\n`, { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, file);
+  return file;
+}
+
+/**
+ * Fold ONE finished run into the ledger on disk: a deterministic job's cards COUNT now; a rubric job's cards are HELD
+ * until a human Accept (they are written to `pending`, never counted, never readable). The run's health line is recorded
+ * either way. Never throws on a bad ledger file: it reports `problem` and writes nothing.
+ * @param {{home?: string, runid: string, build: import('./learn.js').CardBuild, workflow: string, place: string|null, specHash: string|null, trust: 'deterministic'|'rubric', at: string, now?: Date}} o
+ * @returns {{wrote: boolean, counted: number, held: number, problem: string|null}}
+ */
+export function foldRunIntoLedger({ home, runid, build, workflow, place, specHash, trust, at, now = new Date() }) {
+  const cur = readLedger(home);
+  if (cur.problem) return { wrote: false, counted: 0, held: 0, problem: cur.problem };
+  let L = cur.ledger;
+  let counted = 0;
+  let held = 0;
+  if (trust === 'rubric') {
+    L = holdPending(L, { runid, cards: build.cards, workflow, place, specHash, at }, now);
+    held = build.cards.length;
+  } else {
+    const before = L.rows.reduce((n, r) => n + r.runIds.filter((x) => x === runid).length, 0);
+    L = countLedger(L, { runid, cards: build.cards, workflow, place, specHash, trust, now });
+    counted = L.rows.reduce((n, r) => n + r.runIds.filter((x) => x === runid).length, 0) - before;
+  }
+  L = recordHealth(L, runid, build, at, now);
+  writeLedger(L, home);
+  return { wrote: true, counted, held, problem: null };
+}
+
+/**
+ * The human Accept at the review door: release the run's held rubric cards so they count (only forward, only here).
+ * @param {{home?: string, runid: string, now?: Date}} o
+ * @returns {{released: number, problem: string|null}}
+ */
+export function releaseRun({ home, runid, now = new Date() }) {
+  const cur = readLedger(home);
+  if (cur.problem) return { released: 0, problem: cur.problem };
+  const r = releasePending(cur.ledger, runid, now);
+  if (r.ledger !== cur.ledger) writeLedger(r.ledger, home);
+  return { released: r.released, problem: null };
+}
+
+/**
+ * The ONE setting: `learningHints` in config.json. Ships OFF (absent = off). OFF still writes the tally ($0) and the planner
+ * is simply handed nothing, so an ON/OFF contrast has data at once. An unreadable config reads as OFF.
+ * @param {string} [home]
+ * @returns {boolean}
+ */
+export function learningHintsOn(home) {
+  const c = readConfig({ home });
+  return c.problem === null && c.config.learningHints === true;
+}
+
+/** @param {string} p @returns {any[]} the parsed rows of a JSONL file; missing or torn lines are skipped */
+function readJsonl(p) {
+  if (!existsSync(p)) return [];
+  /** @type {any[]} */
+  const rows = [];
+  for (const l of readFileSync(p, 'utf8').split('\n')) {
+    if (!l) continue;
+    try { rows.push(JSON.parse(l)); } catch { /* a torn line is skipped, never a crash */ }
+  }
+  return rows;
+}
+
+/** a path resolved to its real location when it exists, else as written @param {string} p */
+const realOr = (p) => { try { return realpathSync(p); } catch { return p; } };
+
+/**
+ * THE RUN-END TALLY ($0, code only, no model): turn the finished run's whole record into cards and fold them into the
+ * ledger (a rubric job's are held until Accept). Called once from the one engine's run-end block (src/userrun.js
+ * `execute`, shared by the panel, the CLI and the bundle runner), inside its own try/catch: it is a record, never a verdict,
+ * and can never change a run's outcome, exit code or spend. It runs whether the hints setting is on or off.
+ * @param {{home?: string, runid: string, events: any[], auditFiles?: string[], spec: any, specHash: string|null, workdir: string|null, trust: 'deterministic'|'rubric', now?: Date}} o
+ * @returns {{wrote: boolean, counted: number, held: number, problem: string|null, noise: string|null, cards: number}}
+ */
+export function learnAtRunEnd({ home, runid, events, auditFiles = [], spec, specHash, workdir, trust, now = new Date() }) {
+  const audit = auditFiles.flatMap(readJsonl);
+  const build = buildCards({ runid, events, audit, workdir, spec, questions: stageQuestionsByName(spec) });
+  const at = events.findLast((e) => e?.type === 'job-end')?.ts ?? now.toISOString();
+  const r = foldRunIntoLedger({
+    home, runid, build, workflow: String(spec.job), place: placeOf(spec, realOr), specHash, trust, at, now,
+  });
+  return { ...r, noise: build.noise, cards: build.cards.length };
+}
+
+/**
+ * The block the planner is handed for this job, made ONCE at run start from the ledger as it stood — empty when the
+ * setting is off, when there is no ledger, or when nothing is readable. The one `renderHints` render, never a second.
+ * @param {{home?: string, spec: any, specHash: string|null, now?: Date}} o
+ * @returns {{text: string, ids: string[]}|null}
+ */
+export function hintsForRun({ home, spec, specHash, now = new Date() }) {
+  if (!learningHintsOn(home)) return null;
+  const cur = readLedger(home);
+  if (cur.problem) return null;
+  const r = renderHints(cur.ledger, { workflow: String(spec.job), place: placeOf(spec, realOr), specHash, now });
+  return r.text ? r : null;
+}

package/src/modellist.js

@@ -55,7 +55,7 @@ export function idsOf(shape, body) {
  * @returns {Promise<ListResult>}
  */
 export async function listModels({ shape, baseUrl, key, fetchImpl = fetch, timeoutMs = LIST_TIMEOUT_MS }) {
-  const base = typeof baseUrl === 'string' ? baseUrl.trim().replace(/\/+$/, '') : '';
+  const base = typeof baseUrl === 'string' ? baseUrl.trim().replace(/(?<!\/)\/+$/, '') : '';
   if (base === '') return { ok: false, why: 'Type a Base URL.', status: 'no-base-url' };
   const url = `${base}/models`;
   const started = Date.now();

package/src/pagedry.js

@@ -7,14 +7,13 @@
 
 import { createHash } from 'node:crypto';
 import { gradeStep } from './rubricstep.js';
-import { linesOf } from './pagerules.js';
+import { linesOf, numberAtEnd } from './pagerules.js';
 
 /** @typedef {import('./pagerules.js').KeptFact} KeptFact @typedef {import('./pagerules.js').Dropped} Dropped */
 
 /** a number as the page writes it, thousands commas allowed */
 const NUM = '\\d[\\d,]*(?:\\.\\d+)?';
 const AFTER_LABEL = new RegExp(`^\\s*(?:[$€£]\\s*)?(${NUM})`);
-const BEFORE_UNIT = new RegExp(`(${NUM})\\s*$`);
 /** the label every dry-read claim is made under (the checker only needs one name; the fact's own is not read) */
 const CLAIM = 'price';
 const SOURCE = 'page';
@@ -39,7 +38,7 @@ export function moneyResultLines(text, k) {
       }
     } else {
       for (const u of k.unit ?? []) {
-        for (let at = ln.indexOf(u); at !== -1 && amount === undefined; at = ln.indexOf(u, at + u.length)) amount = BEFORE_UNIT.exec(ln.slice(0, at))?.[1];
+        for (let at = ln.indexOf(u); at !== -1 && amount === undefined; at = ln.indexOf(u, at + u.length)) amount = numberAtEnd(ln.slice(0, at));
         if (amount !== undefined) break;
       }
     }

package/src/pagefetch.js

@@ -10,6 +10,7 @@
 // fetch is a plain-words stop, never a silent empty input. Nothing here touches a model.
 
 import { SECRET_PATTERNS } from './validate.js';
+import { TAG } from './labelscan.js';
 
 /** the session options (incognito: no auth ever enters; blockPrivateNetwork: SSRF guard); ONE frozen object so a test can pin them */
 export const CONNECT_OPTIONS = Object.freeze({ incognito: true, blockPrivateNetwork: true });
@@ -59,7 +60,7 @@ export function pageContentChars(text) {
       skipIndent = -1;
     }
     if (m && CHROME_ROLES.has(m[2])) { skipIndent = indent; continue; }
-    n += raw.replace(/\[[A-Za-z]+=[^\]\s]*\]/g, ' ').replace(/^\s*-\s*/, '').replace(/\s+/g, ' ').trim().length;
+    n += raw.replace(TAG, ' ').replace(/^\s*-\s*/, '').replace(/\s+/g, ' ').trim().length;
   }
   return n;
 }

package/src/pagerules.js

@@ -14,7 +14,7 @@ import { normLabel } from './labelscan.js';
  * @typedef {{facts: MapFact[]}} PageMap
  * @typedef {{line: number, name: string, shape: string, from: string, words: string[], unit?: string[], currency?: string[], forRule?: number, reading?: Reading}} KeptFact
  *   `words` = what the page proves: the labels of a money/number/time fact, or the alternative phrases of a phrase fact (a place is a phrase)
- * @typedef {{line: number, rule?: number, fact: string, word?: string, reason: string, other?: string}} Dropped  `other` = what the drop is compared to: the first label (R1), the primary form (R1L), the fact it would have repeated (S1)
+ * @typedef {{line: number, rule?: number, fact: string, word?: string, reason: string, other?: string}} Dropped  `other` = what the drop is compared to: the first label (R1), the primary form (R1L), the fact it would have repeated (S1), the phrase it looked for (phrase-no-result)
  */
 
 /** @param {unknown} v @returns {v is Record<string, any>} */
@@ -99,7 +99,30 @@ const sameSet = (a, b) => a.size === b.size && [...a].every((x) => b.has(x));
 
 /** a number as the page writes it: digits, thousands commas, optional decimals (a currency sign next to it is not part of it) */
 const NUM = '\\d[\\d,]*(?:\\.\\d+)?';
-const BEFORE = new RegExp(`(${NUM})\\s*$`);
+/**
+ * The number written at the very end of `s` (only whitespace after it): the leftmost match of NUM followed by `\s*$`. Shared with src/pagedry.js (one copy). Scans back from the end, so a
+ * long run of digits and commas costs O(n) where a backtracking regex is quadratic.
+ * @param {string} s @returns {string|undefined}
+ */
+export function numberAtEnd(s) {
+  let e = s.length;
+  while (e > 0 && /\s/.test(s[e - 1])) e--;
+  /** the first digit of the digit/comma run ending at `end`, or -1 if the run holds none; a start never follows a digit, so it is the run's first digit */
+  const firstDigit = (/** @type {number} */ end) => {
+    let l = end;
+    while (l > 0 && /[\d,]/.test(s[l - 1])) l--;
+    while (l < end && s[l] === ',') l++;
+    return l < end ? l : -1;
+  };
+  let d = e;
+  while (d > 0 && /\d/.test(s[d - 1])) d--;
+  if (d < e && s[d - 1] === '.') {
+    const p = firstDigit(d - 1);
+    if (p !== -1) return s.slice(p, e);
+  }
+  const p = firstDigit(e);
+  return p === -1 ? undefined : s.slice(p, e);
+}
 const AFTER = new RegExp(`^\\s*(?:[$€£]\\s*)?(${NUM})`);
 const AFTER_CUR = new RegExp(`^\\s*(${NUM})`);
 const stripCommas = (/** @type {string} */ s) => s.replace(/,/g, '');
@@ -121,13 +144,13 @@ function beforeAfter(lines, label) {
   let B = 0;
   let A = 0;
   for (const [l, i] of occs(lines, label)) {
-    if (BEFORE.test(l.slice(0, i))) B += 1;
+    if (numberAtEnd(l.slice(0, i)) !== undefined) B += 1;
     if (AFTER.test(l.slice(i + label.length))) A += 1;
   }
   return { B, A };
 }
 /** R1L: the numbers a UNIT form reads - the one right before each occurrence @param {string[]} lines @param {string} u @returns {Set<string>} */
-const unitSet = (lines, u) => new Set(occs(lines, u).map(([l, i]) => BEFORE.exec(l.slice(0, i))?.[1]).filter((v) => typeof v === 'string').map((v) => stripCommas(/** @type {string} */ (v))));
+const unitSet = (lines, u) => new Set(occs(lines, u).map(([l, i]) => numberAtEnd(l.slice(0, i))).filter((v) => typeof v === 'string').map((v) => stripCommas(/** @type {string} */ (v))));
 /** R1L: the numbers a CURRENCY form reads - the one right after each occurrence @param {string[]} lines @param {string} c @returns {Set<string>} */
 const curSet = (lines, c) => new Set(occs(lines, c).map(([l, i]) => AFTER_CUR.exec(l.slice(i + c.length))?.[1]).filter((v) => typeof v === 'string').map((v) => stripCommas(/** @type {string} */ (v))));
 

package/src/panel/authorroutes.js

@@ -422,7 +422,7 @@ export function createAuthorRoutes(opts) {
     }
     if (sub === 'sign') {
       const claimedHash = String(body?.specHash ?? '');
-      const r = signRun(session, claimedHash, { env: envNow(), spawnFn, bareloopBin, sessionsRoot: opts.sessionsRoot, home: opts.home, ...(opts.schedules ? { schedules: opts.schedules } : {}) });
+      const r = signRun(session, claimedHash, { env: envNow(), spawnFn, bareloopBin, sessionsRoot: opts.sessionsRoot, home: opts.home });
       send(r.ok ? 200 : 400, r);
       return true;
     }

package/src/panel/index.html

@@ -926,6 +926,10 @@
                 <button class="chip" aria-pressed="false" data-view="flat" data-testid="audit-view-flat">Flat</button>
               </div>
             </div>
+            <div id="audit-learnings" class="audit-part" data-testid="audit-learnings" hidden>
+              <button type="button" id="audit-learnings-summary" class="btn audit-part-toggle" aria-expanded="false" data-testid="audit-learnings-summary">What the planner was told from earlier runs</button>
+              <div id="audit-learnings-list" class="audit-part-body" data-testid="audit-learnings-list" hidden></div>
+            </div>
             <div id="audit-groups" data-testid="audit-groups"></div>
             <div id="audit-flat-wrap" hidden>
               <div id="audit-empty" class="hint" data-testid="audit-empty" style="font-size:13px;padding:24px 0;">select a run first</div>
@@ -2828,6 +2832,98 @@
     // fetch, wired separately in selectRun below).
     lastLegDividers = Array.isArray(detail.legDividers) ? detail.legDividers : [];
     renderAuditGroups(detail);
+    renderAuditLearnings(detail);
+  }
+
+  // Cross-run learnings, READ-ONLY: what the planner was handed, one group per injection (the draft, the first replan). ONE fold for the
+  // whole section (the <details> in the Audit tab); opened, every hint shows at once as a title line + labelled rows, no inner toggles.
+  // The fields come from the server (learn.js parseHintBlock, the one reader of the block) - this page never splits the prose.
+  // No edit, no Reject, no button. Absent (the setting was off, or nothing was readable) = the section stays hidden.
+  // one row of a hint's table: the same label cell + value cell the schedule section body uses
+  function learnRow(tbody, testid, label, lines){
+    var tr = document.createElement("tr");
+    tr.setAttribute("data-testid", testid);
+    var lab = document.createElement("td");
+    lab.className = "hint";
+    lab.style.cssText = "white-space:nowrap";
+    lab.textContent = label;
+    var val = document.createElement("td");
+    val.style.cssText = "overflow-wrap:anywhere;white-space:pre-wrap";
+    val.textContent = lines.join("\n");
+    tr.appendChild(lab);
+    tr.appendChild(val);
+    tbody.appendChild(tr);
+  }
+  function learnHintLabel(h){
+    var bits = [h.n, h.level, "seen " + h.count + (h.count === 1 ? " time" : " times")];
+    if(h.check) bits.push(h.check);
+    if(h.kinds && h.kinds.length) bits.push(h.kinds.join(", "));
+    bits.push(h.fixed ? "fixed" : "never fixed");
+    return bits.join(" \u00B7 ");
+  }
+  function renderAuditLearnings(detail){
+    var box = document.getElementById("audit-learnings");
+    var list = document.getElementById("audit-learnings-list");
+    var sum = document.getElementById("audit-learnings-summary");
+    if(!box || !list) return;
+    var items = detail && Array.isArray(detail.learnings) ? detail.learnings : [];
+    list.innerHTML = "";
+    var head = "What the planner was told from earlier runs";
+    items.forEach(function(it, gi){
+      var hints = Array.isArray(it.hints) ? it.hints : [];
+      var when = it.phase === "replan" ? "first replan" : "draft";
+      if(items.length > 1){
+        var g = document.createElement("div");
+        g.className = "hint";
+        g.style.cssText = "margin-top:10px;font-weight:600;";
+        g.setAttribute("data-testid", "audit-learnings-group-" + it.phase);
+        g.textContent = it.phase === "replan" ? "At the first replan" : "At the draft";
+        list.appendChild(g);
+      }
+      var note = document.createElement("div");
+      note.className = "hint";
+      note.style.cssText = "margin:6px 0;overflow-wrap:anywhere;";
+      note.textContent = (gi === 0 ? "Read-only. " : "") + "Given to the planner at the " + when + " (" + Number(it.chars).toLocaleString("en-US") + " characters)." + (gi === 0 ? " No worker sees it." : "");
+      list.appendChild(note);
+      hints.forEach(function(h){
+        var hint = document.createElement("div");
+        hint.className = "audit-table-scroll";
+        hint.setAttribute("data-testid", "audit-learnings-hint-" + it.phase + "-" + h.n);
+        var table = document.createElement("table");
+        table.className = "rounds-table";
+        var tbody = document.createElement("tbody");
+        var trT = document.createElement("tr");
+        var title = document.createElement("td");
+        title.setAttribute("colspan", "2");
+        title.style.cssText = "font-weight:600;overflow-wrap:anywhere";
+        title.setAttribute("data-testid", "audit-learnings-hint-" + it.phase + "-" + h.n + "-title");
+        title.textContent = learnHintLabel(h);
+        trT.appendChild(title);
+        tbody.appendChild(trT);
+        var t = "audit-learnings-hint-" + it.phase + "-" + h.n + "-";
+        if(h.said) learnRow(tbody, t + "said", "It said:", [h.said]);
+        if(h.touched) learnRow(tbody, t + "touched", "Fix touched:", [h.touched]);
+        if(h.changed && h.changed.length) learnRow(tbody, t + "changed", "What changed:", h.changed.concat(h.moreChanged ? ["(+" + h.moreChanged + " more)"] : []));
+        table.appendChild(tbody);
+        hint.appendChild(table);
+        list.appendChild(hint);
+      });
+    });
+    if(sum){
+      var first = items.length ? (Array.isArray(items[0].hints) ? items[0].hints.length : 0) : 0;
+      var label = items.length ? head + " \u00B7 " + first + (first === 1 ? " hint" : " hints") : head;
+      // no arrow (hamr 2026-10-23): the state chip leads; aria-expanded carries open/closed. The same `[✓] word` state markup the schedule/step headers wear (stateDotHTML), then the plain-words title
+      var paint = function(){ sum.innerHTML = stateDotHTML(glyphClass("\u2713"), "learnings", "audit-learnings-state") + " " + escapeXml(label); };
+      paint();
+      // ONE fold, same as the other Audit sections: the header button toggles the body (wired once)
+      sum.onclick = function(){
+        var open = sum.getAttribute("aria-expanded") === "true";
+        sum.setAttribute("aria-expanded", open ? "false" : "true");
+        list.hidden = open;
+        paint();
+      };
+    }
+    box.hidden = items.length === 0;
   }
 
   // ONE spelling of a step's state: its dot + the bold state word — read by the Run tab's step cards AND the Audit tab's grouped rows

package/src/panel/server.js

@@ -47,6 +47,7 @@ import { chainSpend } from '../ledger.js';
 import { runBehaviour } from '../behaviour.js';
 import { SPEND_RECORD_TYPES, floorsFromRecords } from '../ledger.js';
 import { jobSpecHash, workflowKey } from '../job.js';
+import { parseHintBlock } from '../learn.js';
 import { confirmProtections } from '../authorflow.js';
 import { createScheduleDoor } from './schedules.js';
 import { createStarter } from './schedulestart.js';
@@ -74,6 +75,7 @@ import { judgedFilesOf, lineRules, stepFileRel, proseNotCheckedItems } from '../
 import { factPartOf, factSentence, ruleWords, moneyAs } from '../facts.js';
 import { createSettingsRoutes } from './settingsroutes.js';
 import { planFromSpec } from './jobplan.js';
+import { stageQuestionsByName } from '../stagewords.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -1849,6 +1851,9 @@ function getRunDetailBody(runid, opts) {
     // carries no contamination risk); `null` when the spine carries no
     // `memory-cache` record at all (never armed on this run).
     behaviour: scopedBehaviour(row, rawSpineRecords),
+    // Cross-run learnings, READ-ONLY (ITEM33 rev 2, RULING 8): the exact block the planner was handed, as the spine recorded it at
+    // injection (the draft, and the first replan); `hints` = the same text split into fields by learn.js's parseHintBlock (the one reader). Empty when the setting was off or nothing was readable.
+    learnings: rawSpineRecords.filter((e) => e?.type === 'learnings' && typeof e.text === 'string').map((e) => ({ phase: String(e.phase), text: e.text, chars: e.text.length, ids: Array.isArray(e.ids) ? e.ids : [], hints: parseHintBlock(e.text) })),
     // PRD v1.106 Part 5 F: the two Run summary rows, worded here (the page prints them)
     callsLine: callsLineOf(rawSpineRecords, scopedBehaviour(row, rawSpineRecords)),
     checksLine: checksLineOf(rawSpineRecords, enrichedParts),
@@ -2593,116 +2598,6 @@ function resolveSpecForRow(row) {
   return null;
 }
 
-/**
- * THE PLAIN-QUESTION OWNER (plain-checks build, 2026-09-28, hamr's ruling:
- * the "checks N/M" headline is WITHDRAWN — "confusing, reads like 6 failed
- * when 5 never ran"). ONE pure function mapping a declared stage's own
- * signed `kind`+`params` (plus the close's own `genre`, also a signed field)
- * to a short plain-English question a person can read without knowing the
- * catalogue — never a second spelling on the client, and never anything the
- * model authored (the catalogue's kinds/params are the whole vocabulary this
- * reads).
- *
- * Every branch is traced straight off `src/kinds.js`'s runner semantics and
- * the TYPES genre template (`src/authoring.js` `TYPES_GENRE_TEMPLATE`,
- * `classGuards`'s `MECHANICAL_GUARDS`) — never guessed:
- *   - `files-changed` is always the `changed-from-seed` guard: "did it
- *     change any file?"
- *   - `pattern-absent-in-diff` is always the `no-suppressions` guard: "no
- *     casts or silencers added?"
- *   - `rubric-step` (Part 1a) is one job line's output file: "line N — does its output pass the line's checks?"
- *   - `command-exit` is the genre's `suite-green` stage (the only shipped use
- *     of this kind): "does the test suite pass?"
- *   - `count-not-worse` splits three ways on its own declared
- *     `direction`/`baseline` (never the runtime number — see
- *     {@link stageKindMetaFromSpec}'s own doc for why the baseline KIND must
- *     travel separately from the measured figure):
- *       - `higher-is-better` + `baseline: 'seed'` is the genre's `tests-kept`
- *         floor: "did all the old tests still exist?"
- *       - `lower-is-better` + `baseline: 0` is the genre's in-scope
- *         `typecheck` stage — UNLESS its own `cmd`+`args` is the SAME
- *         command a `command-exit` stage in the same close already runs
- *         (`suiteCmdKeys`, below): the TYPES template's `suite-green` is "the
- *         suite exits clean AND reports zero failing tests — TWO assertions"
- *         over ONE population (the same `npm test`/`pytest` invocation), so a
- *         `count-not-worse` stage sharing that exact command is the failing-
- *         test-count half of that pair, never a typecheck stage: "no failing
- *         tests?" — derived from the same cmd+args correlation (the stage
- *         counts the suite's own failing tests), never from the stage's own
- *         name string. The live check that found this (run mul5fofw's own
- *         `suite-zero-failing-tests`, cmd `npm test`, same as its sibling
- *         `suite-green` command-exit stage) would otherwise have read "test/
- *         has 0 type errors?", which is false: its parser counts FAILING
- *         TESTS (`^# fail (\d+)$`), not type-checker output. hamr's ruling:
- *         name this half honestly rather than reusing "type errors" for a
- *         population it was never about, or falling back to the stage's raw
- *         name. When the command differs from every sibling `command-exit`
- *         stage, the declared `scope.includePrefixes` naming exactly ONE path
- *         is quoted verbatim (a signed param, never invented): "<path> has 0
- *         type errors?" — otherwise the generic "type errors is 0?", never a
- *         guessed filename.
- *       - `lower-is-better` + `baseline: 'seed'` with a non-empty
- *         `scope.excludePrefixes` is the genre's `typecheck-outside` ceiling:
- *         "other files didn't get more type errors?"
- * The "type errors" wording is genre-owned (`GENRE_WHAT`), because TYPES is
- * the only genre this catalogue admits today (doc-genre kinds are not yet
- * built) — an unrecognised genre, or a `count-not-worse` shape none of the
- * three above matches, returns `null` rather than invent a fourth shape.
- *
- * `null` means "no honest plain question" — the caller (buildAttemptsList,
- * partLine1Text's `attemptChecksLine`) falls back to the stage's OWN name,
- * exactly as it already does for a stage with no resolvable kind at all.
- * @param {{kind: string|null, params: any, genre: string|null, suiteCmdKeys: Set<string>}} o
- * @returns {string|null}
- */
-const GENRE_WHAT = Object.freeze({ TYPES: 'type errors' });
-
-/** `cmd`+`args`, as a comparable key — the one signal (besides `kind`
- * itself) that two stages measure the SAME command's output, used to tell a
- * genuine typecheck stage apart from the TYPES genre's other `lower-is-
- * better`/`baseline: 0` stage (the failing-test-count half of `suite-green`'s
- * "two assertions"), which shares that stage's own shape but not its
- * population. `null` for a stage whose `cmd` isn't a non-empty string —
- * never matches anything, so it never falsely suppresses a real typecheck
- * question.
- * @param {any} params @returns {string|null} */
-function cmdKey(params) {
-  if (!params || typeof params.cmd !== 'string' || params.cmd.length === 0) return null;
-  const args = Array.isArray(params.args) ? params.args : [];
-  return JSON.stringify([params.cmd, args]);
-}
-
-function stageQuestionText({
-  kind, params, genre, suiteCmdKeys,
-}) {
-  if (kind === 'files-changed') return 'did it change any file?';
-  if (kind === 'pattern-absent-in-diff') return 'no casts or silencers added?';
-  if (kind === 'command-exit') return 'does the test suite pass?';
-  // Part 1a: one rubric-step stage = one job line's output file
-  if (kind === 'rubric-step') return params && Number.isInteger(params.step) ? `line ${params.step} — does its output pass the line's checks?` : null;
-  if (kind !== 'count-not-worse' || !params || typeof params !== 'object') return null;
-  const what = Object.hasOwn(GENRE_WHAT, String(genre)) ? GENRE_WHAT[String(genre)] : null;
-  if (params.direction === 'higher-is-better' && params.baseline === 'seed') {
-    return 'did all the old tests still exist?';
-  }
-  if (!what) return null;
-  const scope = params.scope && typeof params.scope === 'object' ? params.scope : null;
-  if (params.direction === 'lower-is-better' && params.baseline === 0) {
-    const key = cmdKey(params);
-    if (key !== null && suiteCmdKeys instanceof Set && suiteCmdKeys.has(key)) return 'no failing tests?';
-    const include = scope && Array.isArray(scope.includePrefixes) ? scope.includePrefixes : null;
-    if (include && include.length === 1 && typeof include[0] === 'string' && include[0].length > 0) {
-      return `${include[0]} has 0 ${what}?`;
-    }
-    return `${what} is 0?`;
-  }
-  if (params.direction === 'lower-is-better' && params.baseline === 'seed') {
-    const exclude = scope && Array.isArray(scope.excludePrefixes) ? scope.excludePrefixes : null;
-    if (exclude && exclude.length > 0) return `other files didn't get more ${what}?`;
-    return null;
-  }
-  return null;
-}
 
 /**
  * Per-stage `{kind, direction, baselineKind, question}`, keyed by stage NAME,
@@ -2724,18 +2619,7 @@ function stageQuestionText({
  */
 function stageKindMetaFromSpec(spec) {
   if (!spec || typeof spec !== 'object' || !spec.closeDecl || !Array.isArray(spec.closeDecl.stages)) return null;
-  const genre = typeof spec.closeDecl.genre === 'string' ? spec.closeDecl.genre : null;
-  // every command-exit stage's own cmd+args, gathered FIRST (a separate pass)
-  // so stageQuestionText can tell the failing-test-count half of suite-green's
-  // "two assertions" apart from a genuine typecheck stage — see its own doc.
-  /** @type {Set<string>} */
-  const suiteCmdKeys = new Set();
-  for (const s of spec.closeDecl.stages) {
-    if (s && s.kind === 'command-exit') {
-      const key = cmdKey(s.params);
-      if (key !== null) suiteCmdKeys.add(key);
-    }
-  }
+  const questions = stageQuestionsByName(spec);
   /** @type {Map<string, {kind: string|null, direction: string|null, baselineKind: 'seed'|0|null, question: string|null, fromLine: number[]}>} */
   const map = new Map();
   for (const s of spec.closeDecl.stages) {
@@ -2744,9 +2628,7 @@ function stageKindMetaFromSpec(spec) {
     const params = s.params && typeof s.params === 'object' ? s.params : null;
     const direction = params && typeof params.direction === 'string' ? params.direction : null;
     const baselineKind = params && (params.baseline === 'seed' || params.baseline === 0) ? params.baseline : null;
-    const question = stageQuestionText({
-      kind, params, genre, suiteCmdKeys,
-    });
+    const question = questions.get(s.name) ?? null;
     map.set(s.name, {
       kind, direction, baselineKind, question, fromLine: Array.isArray(s.fromLine) ? s.fromLine.filter(Number.isInteger) : [],
     });