bareloop 0.41.0 → 0.42.0

package/src/authorrun.js

@@ -120,11 +120,13 @@ import { defaultJudgeLoop, resolveJobJudge } from './judged.js';
 import { validateJob, jobSpecHash, resolveWorkerModel } from './job.js';
 import { scanSecrets, redactSecrets } from './validate.js';
 import { detectLanguage } from './detectlang.js';
+import { RUBRIC_LANG } from './authoring.js';
+import { rubricGoal } from './rubricstep.js';
 import { moveFile } from './movefile.js';
 import { closeJudges, GATE_AUDIT_FILE } from './kinds.js';
 import { resolveProvider, buildRunnerProviders, apiKeyProblem } from './providers.js';
 import { commandFor } from './invoke.js';
-import { readSourceManifest, missingDependencies, nonRepoSourceMessage } from './source.js';
+import { readSourceManifest, missingDependencies, nonRepoSourceMessage, isRubricFilesManifest } from './source.js';
 import { tallyCalls } from './text.js';
 import {
   declarationLines, rubricLines, calibrationLines, parseCeiling, ceilingLine, crashRecord, phaseLine,
@@ -327,6 +329,9 @@ export async function main(argv, deps = {}) {
   // folder has no genre to detect) and the branch further down that decides
   // which of the two paths this run actually takes.
   const IS_REPO_SOURCE = manifestRead.manifest.kind === 'repo';
+  // PART 1a: a soft-green job whose source froze the person's own local FILES (`proveRubricInputs` left `inputs` in the
+  // manifest) is NOT the plain-folder stop below: it is authored against the hidden tree with the text genre, no scout.
+  const RUBRIC_FILES = !IS_REPO_SOURCE && VERDICT === 'soft-green' && isRubricFilesManifest(manifestRead.manifest);
 
   // ── LANGUAGE, DETECTED — never asked (PRD item 33 M3, ruling 3) ──────────────
   // $0, no provider, run BEFORE the API key is even read — this script must
@@ -361,7 +366,7 @@ export async function main(argv, deps = {}) {
   // the language pick (the old repo-only "worse than before" ask is retired
   // entirely as of 2026-09-28 — see src/authorflow.js's own retirement note).
   let langResult = /** @type {ReturnType<typeof detectLanguage>|null} */ (null);
-  let LANG = 'none-detected';
+  let LANG = RUBRIC_FILES ? RUBRIC_LANG : 'none-detected';
   if (IS_REPO_SOURCE) {
     langResult = detectLanguage(SOURCE);
     // AMBIGUOUS NO LONGER DIES (PRD item 33 M3 piece 4, step S4): the confirm
@@ -834,7 +839,7 @@ export async function main(argv, deps = {}) {
   // build can close. The stop fires HERE, immediately, at $0, no scout, no
   // confirm turn, no model call — a plain folder's spine is exactly
   // `author-start` → `author-end{outcome:'not-authored', stop:'non-code-source'}`.
-  if (!IS_REPO_SOURCE) {
+  if (!IS_REPO_SOURCE && !RUBRIC_FILES) {
     const message = nonRepoSourceMessage(manifestRead.manifest.kind);
     out(`\n${message}`);
     const red = {
@@ -896,7 +901,7 @@ export async function main(argv, deps = {}) {
       // so every path that reaches this call is a repo job. `langResult`
       // travels through unchanged — its `ambiguous` shape is what the confirm
       // turn's own $0 half (D7) asks about, before the scout.
-      ask, confirmGenerate, isRepo: true, langResult,
+      ask, confirmGenerate, isRepo: !RUBRIC_FILES, langResult,
     });
     const authoredFile = writeOut('authored.json', authored);
     emit('authored', { ok: authored.ok, stop: authored.stop, seedRef: authored.seedRef, cost: authored.cost, reds: authored.reds });
@@ -1008,7 +1013,11 @@ export async function main(argv, deps = {}) {
       // predates the confirm turn's own `ask` wiring (`authored.confirmed` is
       // `null` for every caller that runs no confirm turn) — the draft's own
       // goal (if any) then stands untouched.
-      if (authored.confirmed?.goal) {
+      if (RUBRIC_FILES && Array.isArray(draft.jobLines) && draft.jobLines.length > 0) {
+        // PART 1a: the worker's goal for a rubric job on files is written by code from the person's own numbered lines and the
+        // frozen input files the manifest recorded (src/rubricstep.js); the confirmed goal sentence rides as the plan line
+        draft.goal = redactSecrets(rubricGoal({ jobLines: draft.jobLines, files: manifestRead.manifest?.inputs ?? [], confirmedGoal: authored.confirmed?.goal ?? null, closeDecl: authored.closeDecl }));
+      } else if (authored.confirmed?.goal) {
         draft.goal = redactSecrets(String(authored.confirmed.goal));
       }
       // ── 2. the operator's half + the authored half → one spec ──────────────────

package/src/authorscout.js

@@ -56,6 +56,7 @@ import { TOOL_BY_VERB, CTX_TOOLS, createCtxTools, toolAction, strategyFor } from
 import { redactSecrets, SECRET_PATTERNS } from './validate.js';
 import { extractArtifact, priceOf, scrubRaw, stampRaw, tallyCalls, capStop, callCasualty } from './text.js';
 import { PROVIDER_TIMEOUT_MS } from './clock.js';
+import { lookReadTools, lookReportSchema, lookPrompt, verifyLookReport, labelListsOf, LOOK_REPORT_TOOL } from './inputlook.js';
 
 const require = createRequire(import.meta.url);
 const { Loop, wireGate } = require('bare-agent');
@@ -656,6 +657,113 @@ export async function runAuthorScout({
   }
 }
 
+// ── THE LOOK AT A RUBRIC JOB'S INPUTS (PART 1c, docs/product/ITEM33-BUILD.md "3. The look") ─────────────────────────────────────
+//
+// The same pattern as the repo survey above, aimed at the person's own input text instead of a repository: a FIXED read-only grant
+// (search the input, read a slice around a hit - closures over in-memory text, so there is nothing to fence), a hard round bound, a
+// reserved final round whose ONLY tool is the answer form (no more looking), the spend metered per call into the same `calls` the
+// drafting book absorbs, and the answer through a strict tool call (never free prose with JSON inside). The result is shaped like a
+// survey (`state`, `facts`, `calls`, `raws`, `budgetStop`) so the drafting pipeline absorbs it exactly as it absorbs the repo scout.
+
+/** the look's hard round bound */
+export const LOOK_ROUNDS = AUTHOR_SCOUT_ROUNDS;
+
+export const LOOK_SYSTEM = 'You are a careful analyst setting up a checkable job. You are given the person\'s job and the text of their inputs. '
+  + 'You can only search and read that text - you cannot write, run anything or change anything. You have a hard, small number of turns. '
+  + 'Your single deliverable is a report of which facts the job asks for can be CHECKED in the input, with the label that sits right before each value (picked from the list you are shown), and what you could not find. '
+  + 'You do not judge whether a result is good and you do not decide what is done with the job.';
+
+export const LOOK_RECOVERY_PROMPT = 'You are out of looking turns. Report NOW, from what you have already read: call the report tool once with everything you can check and everything you could not find.';
+
+/**
+ * Run the look. `createLoop` is the same seam the repo scout has; nothing else here needs a live process.
+ * @param {{texts: Record<string, string>, inputs: {n: number, label: string}[], jobLines: {n: number, text: string, rule?: string, rules?: string[]}[],
+ *   provider?: any, rounds?: number, maxTokens?: number, ceilingUsd?: number|null, callTimeoutMs?: number,
+ *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number, thinkingStatus?: string}) => void,
+ *   createLoop?: (o: {system: string, policy: any, onLlmResult: any, provider: any, rates?: {in: number, out: number}}) => any,
+ *   rates?: {in: number, out: number}|null, callOptions?: Record<string, any>,
+ *   prove?: (source: string, phrase: string) => number}} o
+ * @returns {Promise<{state: 'PRESENT'|'ABSENT', facts: any, reason: string|null, cause: string|null, meta: any, raw: string,
+ *   raws: ReturnType<typeof scrubRaw>[], calls: {label: string, costUsd: number|null, unpricedRounds: number}[],
+ *   budgetStop: 'cap-halt'|'pricing-red'|null}>}
+ */
+export async function runInputLook({
+  texts, inputs, jobLines, provider = null, rounds = LOOK_ROUNDS, maxTokens = AUTHOR_SCOUT_MAX_TOKENS, ceilingUsd = null,
+  callTimeoutMs = AUTHOR_CALL_TIMEOUT_MS, onCall = () => {}, createLoop = defaultLoop, rates = null, callOptions = {}, prove,
+}) {
+  const callTimeout = Number.isFinite(Number(callTimeoutMs)) && Number(callTimeoutMs) > 0
+    ? Math.min(Math.trunc(Number(callTimeoutMs)), AUTHOR_CALL_TIMEOUT_MS) : AUTHOR_CALL_TIMEOUT_MS;
+  const priced = rates ? { rates } : {};
+  /** @type {{label: string, costUsd: number|null, unpricedRounds: number}[]} */
+  const calls = [];
+  /** @type {ReturnType<typeof scrubRaw>[]} */
+  const raws = [];
+  const record = (/** @type {string} */ label, /** @type {any} */ r) => {
+    const call = { label, ...priceOf(r) };
+    calls.push(call);
+    onCall({ ...call, ...(r?.thinkingStatus === undefined ? {} : { thinkingStatus: r.thinkingStatus }) });
+    raws.push(scrubRaw({ label, attempt: 1, text: r?.text }));
+  };
+  const settled = async (/** @type {Promise<any>} */ p) => {
+    try { return await p; } catch (e) {
+      const reason = callCasualty(e);
+      if (reason === null) throw e;
+      return { error: reason };
+    }
+  };
+  const { scans, lists } = labelListsOf(texts);
+  /** @type {{calls: any[]}} */
+  const box = { calls: [] };
+  /** @type {any} */
+  let loop = null;
+  const reportTool = {
+    name: LOOK_REPORT_TOOL,
+    description: 'Deliver the report. Call this exactly once, with the whole report as its arguments.',
+    parameters: lookReportSchema(),
+    execute: async (/** @type {any} */ args) => { box.calls.push(args); if (loop) loop.stop(); return 'received'; },
+  };
+  const tools = [...lookReadTools(texts), reportTool];
+  const absent = (/** @type {string} */ reason, /** @type {string} */ cause, /** @type {'cap-halt'|'pricing-red'|null} */ budgetStop = null) => ({
+    state: /** @type {'ABSENT'} */ ('ABSENT'), facts: null, reason, cause, meta: { rounds: seen, bounded }, raw: '', raws, calls, budgetStop,
+  });
+  let seen = 0;
+  let bounded = false;
+  const halt0 = capStop({ ceilingUsd, ...tallyCalls(calls) });
+  if (halt0) return absent(`the look was never asked for: the $${ceilingUsd} ceiling was already spent`, SURVEY_CAUSES.NOT_FUNDED, halt0);
+
+  const metered = async (/** @type {any} */ arg) => {
+    if ((arg?.kind ?? 'turn') === 'turn') {
+      seen += 1;
+      if (seen >= rounds) { bounded = true; loop.stop(); }
+    }
+  };
+  loop = createLoop({ system: LOOK_SYSTEM, policy: undefined, onLlmResult: metered, provider, ...priced });
+  const r = await settled(loop.run([{ role: 'user', content: lookPrompt({ jobLines, labels: Object.keys(texts), lists }) }], tools,
+    { cacheMessages: true, maxTokens, timeoutMs: callTimeout, ...callOptions }));
+  record('input-look', r);
+  /** @type {any} */
+  let last = r;
+  if (box.calls.length === 0 && !r?.error) {
+    // THE RESERVED FINAL ROUND: no more looking - the only tool is the answer form
+    const halt = capStop({ ceilingUsd, ...tallyCalls(calls) });
+    if (halt) return absent(`the look stopped on the cost ceiling before it reported: ${halt}`, SURVEY_CAUSES.NOT_FUNDED, halt);
+    const recovery = createLoop({ system: LOOK_SYSTEM, policy: undefined, onLlmResult: undefined, provider, ...priced });
+    const rMsgs = Array.isArray(r?.msgs) && r.msgs.length ? (r.msgs[0]?.role === 'system' ? r.msgs.slice(1) : r.msgs) : [];
+    const only = { ...reportTool, execute: async (/** @type {any} */ args) => { box.calls.push(args); recovery.stop(); return 'received'; } };
+    last = await settled(recovery.run([...rMsgs, { role: 'user', content: LOOK_RECOVERY_PROMPT }], [only],
+      { cacheMessages: true, maxTokens, timeoutMs: callTimeout, ...callOptions }));
+    record('input-look-recovery', last);
+  }
+  if (box.calls.length === 0) {
+    return absent(last?.error ? `the look call failed: ${redactSecrets(String(last.error))}` : 'the look ended without a report', last?.error ? SURVEY_CAUSES.CALL_FAILED : SURVEY_CAUSES.EMPTY);
+  }
+  const report = verifyLookReport(box.calls[0], { scans, jobLines, ...(prove ? { prove } : {}) });
+  return {
+    state: 'PRESENT', reason: null, cause: null, meta: { rounds: seen, bounded }, raw: '', raws, calls, budgetStop: null,
+    facts: { rubricFiles: true, inputs: inputs.map((i) => ({ n: i.n, label: i.label })), look: report },
+  };
+}
+
 // ── L1: THE MECHANICAL SEED LISTING ──────────────────────────────────────────
 
 /** per-path full-listing cap; over it, names give way to counted directories */

package/src/declaredclose.js

@@ -70,7 +70,7 @@
 
 import { runStage, makeSeedTrees, STOP_FAULTS, EXIT_RED, JUDGED_FLOOR_KIND, judgedStages } from './kinds.js';
 import {
-  validateDeclaration, classGuards, genreOwnedEnvNames, ungroundedGenreEnv, GENRE_LANGUAGES, TYPES_GENRE,
+  validateDeclaration, classGuards, genreOwnedEnvNames, ungroundedGenreEnv, DECLARABLE_LANGUAGES, TYPES_GENRE, catalogueForLang, KIND_CATALOGUE, TEXT_GENRE, genreForLang,
   VERDICT_CLASSES, LIVE_CLASSES, NEVER_OFFERED_KINDS,
 } from './authoring.js';
 // the calibration set's own gate lives beside the rulebook it is graded against
@@ -83,7 +83,7 @@ import { isObj, isNonEmptyString } from './validate.js';
 
 /** The genres a `closeDecl` may name. v1 admits exactly one (D13) — a genre
  * classifier is designed the day there is a second genre to classify. */
-export const DECLARED_GENRES = Object.freeze([TYPES_GENRE.name]);
+export const DECLARED_GENRES = Object.freeze([TYPES_GENRE.name, TEXT_GENRE]);
 /**
  * The exact field set of a `closeDecl` — anything else is a smuggle channel, the
  * same rule `STAGE_FIELDS` enforces on a command stage.
@@ -272,13 +272,14 @@ export function declaredStages(closeDecl) {
  *
  * @param {any} closeDecl
  * @param {{at?: string, listing?: string[]|null, deferListing?: boolean,
- *   catalogue?: Record<string, any>, verdictType?: string|null, writeScope?: string[]|null, jobLines?: {n: number}[]|null}} [opts]
+ *   catalogue?: Record<string, any>, verdictType?: string|null, writeScope?: string[]|null, jobLines?: {n: number}[]|null,
+ *   inputLabels?: string[]|null}} [opts]
  * @returns {{ok: boolean, reds: Red[], closeDecl: any, grounded: boolean,
  *   scoped: {scoped: boolean, via: string|null},
  *   ceiling: {class: string, kind: string, stage: string|null, locked: boolean}|null}}
  */
 export function validateCloseDecl(closeDecl, opts = {}) {
-  const { at = 'closeDecl', listing = null, catalogue, verdictType = null, writeScope = null, jobLines = null } = opts;
+  const { at = 'closeDecl', listing = null, catalogue, verdictType = null, writeScope = null, jobLines = null, inputLabels = null } = opts;
   const deferListing = opts.deferListing === true;
   /** @type {Red[]} */
   const reds = [];
@@ -320,13 +321,15 @@ export function validateCloseDecl(closeDecl, opts = {}) {
         + `land here); fields: ${CLOSE_DECL_FIELDS.join(', ')}`);
     }
   }
-  if (!DECLARED_GENRES.includes(closeDecl.genre)) {
-    red('invalid-value', `${at}.genre`, `menu: ${DECLARED_GENRES.join('|')} — v1 admits exactly one genre (D13), and a `
-      + 'genre with no guard battery must refuse rather than author a close without the guards it cannot supply');
+  // PART 1a: a genre is bound to its language — code languages are TYPES, the rubric-files language is TEXT, and neither may
+  // wear the other's label (`lang` is checked just below; an unknown lang reds there)
+  if (!DECLARED_GENRES.includes(closeDecl.genre) || closeDecl.genre !== genreForLang(closeDecl.lang)) {
+    red('invalid-value', `${at}.genre`, `menu: ${DECLARED_GENRES.join('|')} — a close's genre follows its language (${genreForLang(closeDecl.lang)} for "${String(closeDecl.lang)}"), `
+      + 'and a genre with no guard battery must refuse rather than author a close without the guards it cannot supply');
   }
-  const langOk = GENRE_LANGUAGES.includes(closeDecl.lang);
+  const langOk = DECLARABLE_LANGUAGES.includes(closeDecl.lang);
   if (!langOk) {
-    red('invalid-value', `${at}.lang`, `menu: ${GENRE_LANGUAGES.join('|')} — the language selects the genre's guard `
+    red('invalid-value', `${at}.lang`, `menu: ${DECLARABLE_LANGUAGES.join('|')} — the language selects the genre's guard `
       + 'battery and its environment, both of which are ours and neither of which has a default');
   }
   // `notes` is NOT checked here. It is M2's rule now (`validateDeclaration`),
@@ -391,7 +394,9 @@ export function validateCloseDecl(closeDecl, opts = {}) {
   }
 
   const v = validateDeclaration(closeDecl, {
-    ...(catalogue ? { catalogue } : {}),
+    // PART 1a: the kinds a close may use depend on its language — a rubric-files ("text") close sees its own two kinds, every
+    // code close never sees a rubric-only one. A caller-supplied catalogue is narrowed the same way.
+    catalogue: catalogueForLang(closeDecl.lang, catalogue ?? KIND_CATALOGUE),
     // BOTH are forwarded, always. Forwarding only one would hide the case M2
     // reds as `listing-conflict` — a caller that defers the tree-grounded half
     // AND hands over a tree does not know which gate it is running, and silently
@@ -403,6 +408,7 @@ export function validateCloseDecl(closeDecl, opts = {}) {
     verdictType: picked,
     writeScope,
     jobLines,
+    inputLabels,
     envOwned: owned,
     // POST-injection: an owned name is accepted only when its value is EXACTLY
     // the recorded one. `{}` (nothing recorded) keeps the pre-injection rule, so
@@ -486,7 +492,7 @@ export function validateCloseDecl(closeDecl, opts = {}) {
  * @param {any} closeDecl @param {string} verdictType @returns {string[]}
  */
 export function guardNames(closeDecl, verdictType) {
-  if (!isObj(closeDecl) || !GENRE_LANGUAGES.includes(closeDecl.lang)) return [];
+  if (!isObj(closeDecl) || !DECLARABLE_LANGUAGES.includes(closeDecl.lang)) return [];
   if (!LIVE_CLASSES.includes(String(verdictType))) return [];
   return classGuards({ verdictType: String(verdictType), lang: closeDecl.lang }).map((g) => g.name);
 }
@@ -592,6 +598,7 @@ export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
   }
   const owned = !shared;
   const seedTrees = shared ?? makeSeedTrees();
+  const textClose = stages.some((st) => st?.kind === 'rubric-step');
   /** @type {any} */
   const ctx = {
     workdir: cwd,
@@ -633,10 +640,14 @@ export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
     /** @type {any[]} */
     const ran = [];
     /** @type {any} */
-    let last = { verdict: 'satisfied', judgedCount: 1 };
+    /** @type {any} */
+    let last = textClose ? { verdict: 'satisfied' } : { verdict: 'satisfied', judgedCount: 1 };
     for (const st of stages) {
       const r = await runStage(st, ctx);
       const t = translate(r, redact);
+      // PART 1a: `judgedCount` marks a judgment rendered by the close's judging kinds. A rubric-files (TEXT) close renders only
+      // mechanical verdicts and runs no judge, so none of its records may claim one
+      if (textClose) delete t.judgedCount;
       ran.push({
         name: st?.name ?? null,
         verdict: t.verdict,

package/src/facts.js

@@ -0,0 +1,317 @@
+// PART 1b (docs/product/ITEM33-BUILD.md, "Addendum 2026-10-13 — Part 1b: required facts"): the FACT step.
+//
+// A job line the person phrased as "find / list / look up" leaves behind a step file that holds ONLY filled facts:
+//
+//     { "results": [ { "quote": "<words copied from the input>", "values": { "<fact name>": "<value as the quote writes it>" } } ] }
+//
+// What each result must hold is the signed list of REQUIRED FACTS on the line's `fact` part (name, shape, rule, source
+// input). The check is bareguard's `cited` + `decides`, built here by code from the signed part: the quote is really in the
+// frozen input, every value really is in the quote (compared exactly by shape), every value meets its rule. No model is in
+// the check. The claim TEXT that bareguard's number scan reads is written by code from the values, never by the worker.
+
+import { rubricVocabulary } from 'bareguard';
+
+/** the shapes a fact may have (bareguard's value kinds, plus `phrase` = a presence decide) */
+export const FACT_SHAPES = Object.freeze(['money', 'number', 'date', 'time', 'phrase', 'text']);
+/** the comparison ops a rule may use (bareguard's) */
+export const FACT_OPS = Object.freeze(['lt', 'lte', 'gt', 'gte', 'between']);
+/** bareguard signs at most this many decides on one `cited` check */
+export const MAX_FACTS = 10;
+/** every field a fact may carry */
+const FACT_FIELDS = Object.freeze(['name', 'shape', 'unit', 'currency', 'phrase', 'anchor', 'until', 'rule', 'aiProposal']);
+/** every field a part of class `fact` may carry (the shared ones are checked by rubricStepShapeReds) */
+export const FACT_PART_FIELDS = Object.freeze(['source', 'facts', 'count']);
+/** a fact's name appears in the claim text bareguard scans for numbers, so it carries letters only (no digit can red the claim) */
+const NAME_RE = /^[A-Za-z][A-Za-z _-]{0,63}$/;
+
+/** @param {unknown} v @returns {v is Record<string, any>} */
+const isRec = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/** @param {unknown} v @returns {v is string} */
+const nonEmpty = (v) => typeof v === 'string' && v.trim() !== '';
+
+/** the `fact` part of a step's parameters, or null (a step has at most one) @param {any} params @returns {any|null} */
+export function factPartOf(params) {
+  const parts = Array.isArray(params?.parts) ? params.parts : [];
+  return parts.find((/** @type {any} */ p) => isRec(p) && p.class === 'fact') ?? null;
+}
+
+/** @param {any} v @returns {boolean} a rule bound has the type its shape needs: a number for number/money, a string for date/time */
+const boundOk = (/** @type {string} */ shape, /** @type {unknown} */ v) => (shape === 'number' || shape === 'money' ? typeof v === 'number' && Number.isFinite(v) : typeof v === 'string' && v !== '');
+
+/**
+ * The SHAPE of a `fact` part (what it may carry), pushed as reds in the same form `rubricStepShapeReds` uses. Whether the
+ * bareguard rubric it builds is signable is asked of bareguard itself (`checkRubricParts` builds it once at drafting).
+ * @param {any} part @param {string} w the path prefix @param {(code: string, path: string, detail: string) => void} red
+ */
+export function factShapeReds(part, w, red) {
+  for (const k of Object.keys(part)) {
+    if (!['text', 'class', 'covers', 'rules', 'source', 'facts', 'count'].includes(k)) {
+      red('invalid-value', `${w}.${k}`, `"${k}" is not a field of a fact part — fields: text, class, covers, rules, ${FACT_PART_FIELDS.join(', ')}`);
+    }
+  }
+  if (!(nonEmpty(part.source) && part.source.length <= 128)) red('invalid-value', `${w}.source`, 'the label of the input the quotes come from');
+  if (!Array.isArray(part.facts) || part.facts.length === 0 || part.facts.length > MAX_FACTS) {
+    red('invalid-value', `${w}.facts`, `a list of 1 to ${MAX_FACTS} facts {name, shape, ...}`);
+  } else {
+    /** @type {Set<string>} */
+    const seen = new Set();
+    part.facts.forEach((/** @type {any} */ f, /** @type {number} */ j) => {
+      const fw = `${w}.facts[${j}]`;
+      if (!isRec(f)) { red('invalid-value', fw, '{name, shape, ...}'); return; }
+      for (const k of Object.keys(f)) {
+        if (FACT_FIELDS.includes(k)) continue;
+        // L4 (smv710w8c3wdh, 3 of 3 tries): "covers" / "rules" are fields of the PART, written once, never of a fact inside it
+        red('invalid-value', `${fw}.${k}`, k === 'covers' || k === 'rules'
+          ? `"${k}" is a field of the PART, not of a fact - write the numbers once on the fact part ("${k}": [..]) and take it off every fact. Fact fields: ${FACT_FIELDS.join(', ')}`
+          : `"${k}" is not a field of a fact — fields: ${FACT_FIELDS.join(', ')}`);
+      }
+      if (!(typeof f.name === 'string' && NAME_RE.test(f.name))) red('invalid-value', `${fw}.name`, 'the fact\'s name: letters, spaces, "_" or "-" only (no digits), at most 64 characters');
+      else if (seen.has(f.name)) red('invalid-value', `${fw}.name`, `the name "${f.name}" is used twice on this line`);
+      else seen.add(f.name);
+      if (!FACT_SHAPES.includes(f.shape)) { red('invalid-value', `${fw}.shape`, `one of ${FACT_SHAPES.join(' | ')}`); return; }
+      if (Object.hasOwn(f, 'aiProposal') && typeof f.aiProposal !== 'boolean') red('invalid-value', `${fw}.aiProposal`, 'true when the AI turned the person\'s words into this number');
+      const has = (/** @type {string} */ k) => Object.hasOwn(f, k);
+      if (f.shape === 'money') {
+        if (has('unit') === has('currency')) red('invalid-value', `${fw}.unit`, 'money names exactly one of unit (words the input writes after the amount, e.g. "US dollars") or currency ("$", "€" or "£")');
+      } else if (has('unit') || has('currency')) red('invalid-value', `${fw}.${has('unit') ? 'unit' : 'currency'}`, 'only money has a unit or a currency');
+      if (has('unit') && !nonEmpty(f.unit)) red('invalid-value', `${fw}.unit`, 'a non-empty string copied from the input');
+      if (has('currency') && !['$', '€', '£'].includes(f.currency)) red('invalid-value', `${fw}.currency`, 'one of $ | € | £');
+      if (f.shape === 'phrase') {
+        if (!nonEmpty(f.phrase)) red('invalid-value', `${fw}.phrase`, 'the fixed words the quote must contain, copied from the input');
+        for (const k of ['anchor', 'until', 'rule']) if (has(k)) red('invalid-value', `${fw}.${k}`, 'a phrase is fixed words the quote must contain; it has no anchor, until or rule');
+      } else if (has('phrase')) red('invalid-value', `${fw}.phrase`, 'only a phrase fact carries phrase');
+      if (has('anchor') && !nonEmpty(f.anchor)) red('invalid-value', `${fw}.anchor`, 'a label copied VERBATIM from the input');
+      if (has('until') && !nonEmpty(f.until)) red('invalid-value', `${fw}.until`, 'a label copied VERBATIM from the input');
+      if (has('until') && !has('anchor') && f.shape !== 'phrase') red('invalid-value', `${fw}.until`, 'until needs an anchor');
+      if (has('until') && f.shape !== 'text' && f.shape !== 'phrase') red('invalid-value', `${fw}.until`, 'until closes a text fact only');
+      if (has('rule') && f.shape !== 'phrase') {
+        const r = f.rule;
+        if (f.shape === 'text') red('invalid-value', `${fw}.rule`, 'a text fact is bind only: it has no rule');
+        else if (!isRec(r) || !FACT_OPS.includes(r.op)) red('invalid-value', `${fw}.rule`, `{op: ${FACT_OPS.join(' | ')}, value} or {op: "between", lo, hi}`);
+        else if (r.op === 'between' ? !(boundOk(f.shape, r.lo) && boundOk(f.shape, r.hi) && !Object.hasOwn(r, 'value')) : !(boundOk(f.shape, r.value) && !Object.hasOwn(r, 'lo') && !Object.hasOwn(r, 'hi'))) {
+          red('invalid-value', `${fw}.rule`, r.op === 'between' ? 'between needs lo and hi (numbers for number/money, strings for date/time) and no value' : 'a comparison needs value (a number for number/money, a string for date/time)');
+        }
+      }
+    });
+  }
+  if (Object.hasOwn(part, 'count')) {
+    const c = part.count;
+    const ok = isRec(c) && Object.keys(c).every((k) => k === 'min' || k === 'max') && (Object.hasOwn(c, 'min') || Object.hasOwn(c, 'max'))
+      && ['min', 'max'].every((k) => !Object.hasOwn(c, k) || (Number.isInteger(c[k]) && c[k] >= 1))
+      && (!Object.hasOwn(c, 'min') || !Object.hasOwn(c, 'max') || c.min <= c.max);
+    if (!ok) red('invalid-value', `${w}.count`, '{min?, max?} — how many results the person asked for (integers, 1 or more, min no more than max)');
+  }
+}
+
+/**
+ * bareguard's `decides` list for a fact part: one decide per fact, in the fact order (so `d<j>` is the fact's own index).
+ * @param {any} part @returns {Record<string, any>[]}
+ */
+export function factDecides(part) {
+  return part.facts.map((/** @type {any} */ f) => {
+    if (f.shape === 'phrase') return { phrases: [f.phrase] };
+    /** @type {Record<string, any>} */
+    const d = { valueKind: f.shape };
+    if (f.shape === 'money') { if (f.unit !== undefined) d.unit = f.unit; else d.currency = f.currency; }
+    if (f.anchor !== undefined) d.anchor = f.anchor;
+    if (f.until !== undefined) d.until = f.until;
+    if (f.rule) {
+      d.op = f.rule.op;
+      if (f.rule.op === 'between') { d.lo = f.rule.lo; d.hi = f.rule.hi; } else d.value = f.rule.value;
+    }
+    return d;
+  });
+}
+
+/**
+ * The claims bareguard reads for a fact step, built from the step file's `results`. The claim TEXT is written here, by code,
+ * from the values the worker gave (the worker writes no claim text): `name: value; name: value`. A phrase fact contributes its
+ * own signed words. A result that is not an object, or has no string quote, still becomes a claim — an empty one — so
+ * bareguard reds it by name rather than the result vanishing.
+ * @param {any} part @param {unknown} results @returns {{claim: string, quote: string, values?: Record<string, string>}[]}
+ */
+export function factClaims(part, results) {
+  const list = Array.isArray(results) ? results : [];
+  return list.map((/** @type {any} */ r) => {
+    const given = isRec(r) && isRec(r.values) ? r.values : null;
+    /** @type {Record<string, string>} */
+    const values = {};
+    /** @type {string[]} */
+    const said = [];
+    part.facts.forEach((/** @type {any} */ f, /** @type {number} */ j) => {
+      if (f.shape === 'phrase') { said.push(`${f.name}: ${f.phrase}`); return; }
+      const v = given && Object.hasOwn(given, f.name) ? given[f.name] : undefined;
+      // a JSON number is the value as written ("389"): converted, never repaired; anything else is left for bareguard to red
+      const s = typeof v === 'number' && Number.isFinite(v) ? String(v) : v;
+      if (typeof s === 'string') { values[`d${j}`] = s; said.push(`${f.name}: ${s}`); } else if (s !== undefined) { /** @type {any} */ (values)[`d${j}`] = s; }
+    });
+    return { claim: said.join('; '), quote: isRec(r) && typeof r.quote === 'string' ? r.quote : '', values };
+  });
+}
+
+/** @param {unknown} n @param {string} shape @param {any} f @returns {string} one bound, as the person would say it */
+function sayBound(n, shape, f) {
+  if (shape === 'money') return f.unit !== undefined ? `${n} ${f.unit}` : `${f.currency}${n}`;
+  return String(n);
+}
+
+/** @param {any} f a fact with a rule @returns {string} the rule in words, e.g. "at most 450 US dollars" */
+function ruleWords(f) {
+  const r = f.rule;
+  return r.op === 'between' ? `between ${sayBound(r.lo, f.shape, f)} and ${sayBound(r.hi, f.shape, f)}`
+    : `${{ lt: 'under', lte: 'at most', gt: 'over', gte: 'at least' }[/** @type {'lt'|'lte'|'gt'|'gte'} */ (r.op)]} ${sayBound(r.value, f.shape, f)}`;
+}
+
+/**
+ * One fact as a plain row, written by code from the signed fields:
+ * `fact · price — money, at most 450 US dollars, after "Price", quoted from "Flights"`.
+ * @param {any} f @param {string} source
+ * @returns {string}
+ */
+export function factSentence(f, source) {
+  /** @type {string[]} */
+  const bits = [];
+  if (f.shape === 'phrase') bits.push('phrase', `must say "${f.phrase}"`);
+  else {
+    bits.push(f.shape === 'money' ? `money in ${f.unit !== undefined ? f.unit : f.currency}` : f.shape);
+    if (f.rule) bits.push(ruleWords(f));
+    else if (f.anchor === undefined) bits.push('as the quote writes it');
+    if (f.anchor !== undefined) bits.push(f.until !== undefined ? `the words after "${f.anchor}" up to "${f.until}"` : `after "${f.anchor}"`);
+  }
+  bits.push(`quoted from "${source}"`);
+  return `fact · ${f.name} — ${bits.join(', ')}${f.aiProposal ? ' — AI\'s proposal — check it' : ''}`;
+}
+
+/**
+ * One fact as the WORKER is told it (item 7): what to write for it and where in the quote it sits, in plain words, from the signed
+ * fields. A phrase fact has no value to write — the quote has to say it.
+ * @param {any} f @returns {string}
+ */
+export function factBrief(f) {
+  if (f.shape === 'phrase') return `${f.name} — no value to write; the quote you copy must say "${f.phrase}"`;
+  /** @type {string[]} */
+  const bits = [f.shape === 'money' ? `an amount in ${f.unit !== undefined ? f.unit : f.currency}` : `a ${f.shape}`];
+  if (f.shape === 'text') bits[0] = 'words';
+  if (f.anchor !== undefined) bits.push(f.until !== undefined ? `the words right after "${f.anchor}" up to "${f.until}"` : `right after "${f.anchor}"`);
+  if (f.rule) bits.push(`must be ${ruleWords(f)}`);
+  return `${f.name} — ${bits.join(', ')}`;
+}
+
+/** the "N results" row of a fact part, or null @param {any} part @returns {string|null} */
+export function countSentence(part) {
+  const c = isRec(part.count) ? part.count : null;
+  if (!c) return null;
+  const n = (/** @type {number} */ v) => `${v} result${v === 1 ? '' : 's'}`;
+  if (c.min !== undefined && c.max !== undefined) return c.min === c.max ? `fact · results — exactly ${n(c.min)}, each quoted from "${part.source}"` : `fact · results — ${c.min} to ${c.max} results, each quoted from "${part.source}"`;
+  return c.min !== undefined ? `fact · results — at least ${n(c.min)}, each quoted from "${part.source}"` : `fact · results — at most ${n(c.max)}, each quoted from "${part.source}"`;
+}
+
+/**
+ * Every plan-card row a fact part carries: its facts, then its count.
+ * @param {any} part @returns {string[]}
+ */
+export function factRows(part) {
+  const rows = (Array.isArray(part.facts) ? part.facts : []).map((/** @type {any} */ f) => factSentence(f, part.source));
+  const c = countSentence(part);
+  return [...rows, ...(c ? [c] : [])];
+}
+
+/**
+ * One bareguard `cited` item (`#<result>:d<j>:<reason>[:<detail>]`, or `#<result>:<reason>`) as a sentence the worker can act
+ * on. The names and numbers are bareguard's measurements and the person's signed facts, never inferred here.
+ * @param {string} item @param {any} part @returns {string}
+ */
+export function plainFactItem(item, part) {
+  const m = /^#(\d+):(?:d(\d+):)?([a-z-]+)(?::([\s\S]*))?$/.exec(item);
+  if (!m) return item;
+  const at = `result ${Number(m[1]) + 1}`;
+  const f = m[2] !== undefined && Array.isArray(part.facts) ? part.facts[Number(m[2])] : null;
+  const who = f ? `${at}, fact "${f.name}"` : at;
+  const detail = m[4] ?? '';
+  const say = (/** @type {string} */ s) => `${who}: ${s}`;
+  switch (m[3]) {
+    case 'quote-not-found': return `${at}: the quote is not found word for word in "${part.source}"`;
+    case 'empty-quote': return `${at}: the quote is empty — copy the words from "${part.source}" that hold the facts`;
+    case 'quote-too-long': return `${at}: the quote is too long — copy only that one result's own words, not more`;
+    case 'numbers': return `${at}: the number ${detail} is not in the quote the way the value writes it — write each value as the quote writes it (for example "9:27 AM", not "09:27")`;
+    case 'value-over': case 'value-under': return say(`the value in the quote is ${m[3] === 'value-over' ? 'above' : 'below'} what the rule allows${f && f.rule ? ` (${ruleWords(f)})` : ''}`);
+    case 'value-none': return say(`the quote holds no ${f ? f.shape : 'value'}${f && f.anchor !== undefined ? ` after "${f.anchor}"` : ''}`);
+    case 'value-many': return say(`the quote holds more than one ${f ? f.shape : 'value'} — quote only the words that hold this one`);
+    case 'value-malformed': return say(`a ${f ? f.shape : 'value'} in the quote is not written in a form the check can read`);
+    case 'anchor-missing': return say(`the label "${f ? f.anchor : ''}" is not in the quote`);
+    case 'anchor-ambiguous': return say(`the label "${f ? f.anchor : ''}" is in the quote more than once`);
+    case 'until-missing': return say(`"${f ? f.until : ''}" does not follow the label "${f ? f.anchor : ''}" in the quote`);
+    case 'phrase-missing': return say(`the quote does not say "${detail}"`);
+    case 'claim-value-missing': return say('no value was given in "values"');
+    case 'claim-value-malformed': return say('the value is not written as a value of this kind');
+    case 'claim-value-absent': return say('the value is not in the quote as a whole word');
+    case 'claim-value-unknown': return say('this value is not one of the signed facts');
+    case 'claim-value-mismatch': return say(`the value is not what the quote holds (${detail.replace('!=', ' is not ')})`);
+    default: return `${who}: ${m[3]}${detail ? ` ${detail}` : ''}`;
+  }
+}
+
+// ── which shape takes which fields (live fix B2) ─────────────────────────────────────────────────────────────────────────────
+//
+// The drafter put `until` on a money fact and `anchor`/`until`/`rule` on a phrase (smv6k6l8dxkzs). What a shape takes is bareguard's
+// to say, so the table the drafter is shown is READ OFF `rubricVocabulary` (the `cited` rule's decide shapes and their stated
+// conditions), never hand-typed. If bareguard's wording of a condition changes so that it cannot be read, this throws at load time
+// and the test that pins it fails: a stale guide is never shown quietly.
+
+/**
+ * The fields each fact shape takes, in the fact part's own names (`rule` = bareguard's op/value/lo/hi; `unit`/`currency`; `phrase`
+ * = the presence decide's phrases), read off bareguard's rubric vocabulary.
+ * @returns {Record<string, string[]>} shape -> the fields it takes besides name and shape
+ */
+export function factShapeFields() {
+  const decides = /** @type {any} */ (rubricVocabulary).rules?.cited?.fields?.decides?.shapes;
+  const value = decides?.value;
+  const presence = decides?.presence;
+  const kinds = /** @type {string[]} */ (value?.fields?.valueKind?.enum);
+  /** @type {string[]} */
+  const conditions = value?.conditions ?? [];
+  const find = (/** @type {RegExp} */ re) => {
+    for (const c of conditions) { const m = re.exec(c); if (m) return m; }
+    throw new Error(`bareguard's rubric vocabulary no longer states the condition ${re} — update src/facts.js factShapeFields`);
+  };
+  if (!Array.isArray(kinds) || !presence?.fields?.phrases) throw new Error('bareguard\'s rubric vocabulary has no cited decide shapes — update src/facts.js factShapeFields');
+  const bindOnlyKind = find(/^valueKind (\w+) is bind-only: it refuses op, value, lo, hi, currency and unit/)[1];
+  const untilKind = find(/^until is allowed only on a (\w+) decide that also signs an anchor/)[1];
+  const moneyKind = find(/^(\w+) needs (?:exactly|at least) one of currency or unit/)[1];
+  /** @type {Record<string, string[]>} */
+  const out = {};
+  for (const k of kinds) {
+    /** @type {string[]} */
+    const f = [];
+    if (k !== bindOnlyKind) f.push('rule');
+    if (value.fields.anchor) f.push('anchor');
+    if (k === untilKind) f.push('until');
+    if (k === moneyKind) f.push('unit or currency');
+    out[k] = f;
+  }
+  out.phrase = ['phrase'];
+  return out;
+}
+
+/**
+ * The lines the drafter is shown about which shape takes which fields, generated from {@link factShapeFields} (shapes with the same
+ * fields are listed together). One owner: the composer brief and the confirm note both print this.
+ * @returns {string}
+ */
+export function factShapeGuide() {
+  const by = factShapeFields();
+  /** @type {Map<string, string[]>} */
+  const groups = new Map();
+  for (const shape of FACT_SHAPES) {
+    const key = (by[shape] ?? []).join(' | ');
+    groups.set(key, [...(groups.get(key) ?? []), shape]);
+  }
+  const all = [...new Set(Object.values(by).flat())];
+  const lines = [];
+  for (const [key, shapes] of groups) {
+    const takes = key === '' ? [] : key.split(' | ');
+    const never = all.filter((f) => !takes.includes(f));
+    lines.push(`${shapes.join(' / ')}: takes ${takes.length ? takes.join(', ') : 'no extra field'}${never.length ? `; never ${never.join(', ')}` : ''}`);
+  }
+  return lines.map((l) => ` - ${l}`).join('\n');
+}