bareloop 0.41.0 → 0.42.0

package/src/factwords.js

@@ -0,0 +1,129 @@
+// THE FOUND-ONCE CHECK (PART 1c, docs/product/ITEM33-BUILD.md "3. The look", PRD item 33 RF20): code proves, at $0, that every word a fact
+// check depends on is really in the person's source - ONCE is enough - and that every label (anchor) is one PICKED from the list code
+// made from that source (src/labelscan.js), never typed. A word that is not found is a red naming the word and the input. Nothing is
+// graded here and no model is involved: the AI proposes the words, code proves they are there.
+//
+// Compared WHITE-SPACE BLIND: any run of white space (U+202F and U+00A0 included - Google writes U+202F before AM/PM, 259 times in one
+// page) is one space on both sides.
+
+import { labelOnList, normLabel, scanLabels } from './labelscan.js';
+
+const WS = /[\s   ]+/g;
+const escapeRe = (/** @type {string} */ s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** @param {string} t @returns {string} the source with every run of white space made one space */
+export const squash = (t) => String(t ?? '').replace(WS, ' ');
+/** @param {string} t @returns {string} lower case, markdown marks dropped, white space squashed - how a phrase or unit is compared */
+const loose = (t) => squash(t).replace(/[*_`]/g, '').trim().toLowerCase();
+
+/**
+ * How many times exact words occur in a source, white space blind. Zero for empty words.
+ * @param {string} source the raw source text @param {string} words
+ * @returns {number}
+ */
+export function countExact(source, words) {
+  const w = squash(words).trim();
+  if (w === '') return 0;
+  const hay = squash(source);
+  let n = 0;
+  for (let i = hay.indexOf(w); i !== -1; i = hay.indexOf(w, i + w.length)) n += 1;
+  return n;
+}
+
+/**
+ * How many times a phrase or unit occurs as WHOLE words, case and spacing aside ("SFO" is not found inside "sfocus").
+ * @param {string} source @param {string} words @returns {number}
+ */
+export function countPhrase(source, words) {
+  const w = loose(words);
+  if (w === '') return 0;
+  const re = new RegExp(`(^|[^\\p{L}\\p{N}])${escapeRe(w)}(?=$|[^\\p{L}\\p{N}])`, 'gu');
+  let n = 0;
+  for (const _m of loose(source).matchAll(re)) n += 1;
+  return n;
+}
+
+/** @param {string} shape @returns {'money'|'number'|'date'|'time'|'text'} the label list a fact's anchor is picked from */
+const listOf = (shape) => /** @type {any} */ (['money', 'number', 'date', 'time'].includes(shape) ? shape : 'text');
+
+/**
+ * The reds for ONE fact part against its frozen source text.
+ * @param {{part: any, text: string, line: number|string, scan?: import('./labelscan.js').LabelScan}} o
+ * @returns {{code: string, detail: string}[]}
+ */
+export function checkFactWords({ part, text, line, scan = scanLabels(text) }) {
+  /** @type {{code: string, detail: string}[]} */
+  const reds = [];
+  const src = part.source;
+  const red = (/** @type {string} */ code, /** @type {string} */ msg) => reds.push({ code, detail: `line ${line}: ${msg} Nothing was signed.` });
+  for (const f of Array.isArray(part.facts) ? part.facts : []) {
+    const who = `fact "${f.name}"`;
+    if (f.anchor !== undefined && f.shape !== 'phrase') {
+      const list = listOf(f.shape);
+      const row = labelOnList(scan, list, f.anchor);
+      if (!row) {
+        const some = scan[list].slice(0, 12).map((r) => JSON.stringify(r.label)).join(', ');
+        red('rubric-fact-label-off-list', `${who}: the label ${JSON.stringify(normLabel(String(f.anchor)))} is not one of the labels the input "${src}" holds before a ${f.shape === 'text' ? 'text value' : f.shape}. A label is picked from that list, never typed${some ? `: ${some}` : ' (the list is empty - leave the label out)'}.`);
+      } else if (countExact(text, row.label) < 1) {
+        red('rubric-fact-word-missing', `${who}: the label ${JSON.stringify(row.label)} is not in the input "${src}".`);
+      } else if (Number.isInteger(part.count?.min) && row.count < part.count.min) {
+        // M1: a label that starts each result must repeat as often as results were asked for; one that sits once on the page
+        // (a sort tab, a switch) is in no result, so no one-result quote can hold it
+        const n = part.count.min;
+        red('rubric-fact-label-rare', `${who}: the label ${JSON.stringify(row.label)} is in the input "${src}" only ${row.count} time${row.count === 1 ? '' : 's'}, but this line asks for ${n} results, so a label that sits in each result must be there at least ${n} times. Pick a label from the list that is counted ${n} or more times.`);
+      }
+    }
+    if (f.until !== undefined && countExact(text, f.until) < 1) red('rubric-fact-word-missing', `${who}: ${JSON.stringify(f.until)} is not in the input "${src}". Copy the closing words from the input, or leave them out.`);
+    if (f.shape === 'phrase' && typeof f.phrase === 'string') {
+      const seen = countPhrase(text, f.phrase);
+      if (seen < 1) red('rubric-fact-word-missing', `${who}: ${JSON.stringify(f.phrase)} is not in the input "${src}". Copy the words the input really uses, or remove the check.`);
+      else if (Number.isInteger(part.count?.min) && seen < part.count.min) {
+        // M4: the words each result's quote must say must repeat as often as results were asked for; page-header words (counted
+        // once or twice) are in no result, so no one-result quote can say them
+        const n = part.count.min;
+        red('rubric-fact-phrase-rare', `${who}: the words ${JSON.stringify(f.phrase)} are in the input "${src}" only ${seen} time${seen === 1 ? '' : 's'}, but this line asks for ${n} results - each result's own quote must say them. Pick words every result says, or drop this check.`);
+      }
+    }
+    if (typeof f.unit === 'string' && countPhrase(text, f.unit) < 1) red('rubric-fact-word-missing', `${who}: the unit ${JSON.stringify(f.unit)} is not in the input "${src}". Copy the words the input really uses.`);
+  }
+  return reds;
+}
+
+/**
+ * The reds for every fact part of a declaration. A fact part whose input text is not at hand is a red: a check whose words were never
+ * proved against the source is never signed.
+ * @param {any} declaration @param {Record<string, string>|null} texts label -> frozen text
+ * @returns {{code: string, path: string, detail: string}[]}
+ */
+export function checkDeclarationWords(declaration, texts) {
+  /** @type {{code: string, path: string, detail: string}[]} */
+  const reds = [];
+  if (!declaration || !Array.isArray(declaration.stages)) return reds;
+  /** @type {Map<string, import('./labelscan.js').LabelScan>} */
+  const scans = new Map();
+  declaration.stages.forEach((/** @type {any} */ st, /** @type {number} */ i) => {
+    const parts = st?.kind === 'rubric-step' && Array.isArray(st.params?.parts) ? st.params.parts : [];
+    parts.forEach((/** @type {any} */ p, /** @type {number} */ k) => {
+      if (p?.class !== 'fact') return;
+      const at = `stages[${i}].params.parts[${k}]`;
+      const text = texts ? texts[p.source] : undefined;
+      /** @param {string} code @param {string} detail */
+      const red = (code, detail) => reds.push({ code, path: at, detail });
+      if (typeof text !== 'string') {
+        red('rubric-fact-unread', `line ${st.params.step}: the input "${p.source}" could not be read here to prove the words against it. Nothing was signed.`);
+        return;
+      }
+      if (!scans.has(p.source)) scans.set(p.source, scanLabels(text));
+      for (const r of checkFactWords({ part: p, text, line: st.params.step, scan: scans.get(p.source) })) reds.push({ code: r.code, path: at, detail: r.detail });
+    });
+  });
+  return reds;
+}
+
+/**
+ * The look's own proof hook: how often a phrase the look built is in an input.
+ * @param {Record<string, string>} texts @returns {(source: string, phrase: string) => number}
+ */
+export function proverOf(texts) {
+  return (source, phrase) => (typeof texts[source] === 'string' ? countPhrase(texts[source], phrase) : 0);
+}

package/src/inputlook.js

@@ -0,0 +1,301 @@
+// THE LOOK (PART 1c, docs/product/ITEM33-BUILD.md "3. The look", PRD item 33 RF19/RF20): before the drafter writes a single check, the AI
+// LOOKS at the person's input - read only, bounded, with tools that can do nothing but search and read the input's own text - and
+// reports, per job line, the facts it can check (name, shape, a label PICKED from the code-made list, one example value it saw) and
+// what it could not find. This module holds the pure parts: the two read-only tools, the strict answer form, the prompt, and the
+// code that turns the AI's report into a verified one. The paid loop around them is `runInputLook` in src/authorscout.js.
+//
+// LABELS ARE PICKED, NEVER TYPED: the AI names a label by its id on the list (src/labelscan.js) or by its exact words; a label that is
+// not on the list is NOT carried into the report - it is moved to "could not check", named. Code never decides two words mean the
+// same: the AI proposes, the list and the source prove.
+
+import { scanLabels, labelOnList, renderLabelList, normLabel, LABEL_SHAPES } from './labelscan.js';
+import { FACT_SHAPES, FACT_OPS } from './facts.js';
+import { lineRules } from './rubricstep.js';
+
+/** the name of the answer tool - the one place the AI's report enters */
+export const LOOK_REPORT_TOOL = 'report_look';
+/** how many hits one search returns at most, and how long a snippet or a read line is */
+export const LOOK_MAX_HITS = 40;
+const SNIPPET = 220;
+const READ_LINE = 320;
+const READ_LINES = 40;
+const TAG = /\[[A-Za-z]+=[^\]\s]*\]/g;
+const WS = /[\s   ]+/g;
+
+/**
+ * The input as the AI sees it: lines with any run of white space (U+202F included) made one space and the page reader's bracketed tags
+ * (`[ref=549]`) removed - an id that is only the page reader's, never part of a label.
+ * @param {string} text @returns {string[]}
+ */
+export function lookLines(text) {
+  return String(text ?? '').split('\n').map((l) => l.replace(TAG, ' ').replace(WS, ' ').trim());
+}
+
+/**
+ * The two read-only tools: search the input text, read a slice around a hit. They are closures over in-memory text and touch nothing
+ * else - read-only BY CONSTRUCTION, not by a fence. Several inputs: the `input` argument names which (its label).
+ * @param {Record<string, string>} texts label -> frozen text
+ * @returns {{name: string, description: string, parameters: any, execute: (a: any) => Promise<any>}[]}
+ */
+export function lookReadTools(texts) {
+  const labels = Object.keys(texts);
+  /** @type {Record<string, string[]>} */
+  const lines = Object.fromEntries(labels.map((l) => [l, lookLines(texts[l])]));
+  const which = (/** @type {any} */ a) => (typeof a?.input === 'string' && lines[a.input] ? a.input : (labels.length === 1 ? labels[0] : null));
+  const inputProp = { type: 'string', description: `the input's label - one of: ${labels.join(', ')}` };
+  return [
+    {
+      name: 'search_input',
+      description: 'Case-insensitive search of one input for a word or phrase. Returns the line numbers and the start of each line that holds it. Search the person\'s own words AND other words that mean the same (nonstop / direct, San Francisco / SFO).',
+      parameters: { type: 'object', properties: { input: inputProp, text: { type: 'string', minLength: 1 }, max: { type: 'integer', minimum: 1, maximum: LOOK_MAX_HITS } }, required: ['text'] },
+      execute: async (a) => {
+        const name = which(a);
+        if (name === null) return { error: `name the input: ${labels.join(', ')}` };
+        const q = String(a?.text ?? '').toLowerCase().replace(WS, ' ').trim();
+        if (q === '') return { error: 'give the words to search for' };
+        const max = Math.min(Number.isInteger(a?.max) ? a.max : 20, LOOK_MAX_HITS);
+        /** @type {{line: number, text: string}[]} */
+        const hits = [];
+        let total = 0;
+        lines[name].forEach((l, i) => { if (l.toLowerCase().includes(q)) { total += 1; if (hits.length < max) hits.push({ line: i + 1, text: l.slice(0, SNIPPET) }); } });
+        return { input: name, total, hits };
+      },
+    },
+    {
+      name: 'read_input',
+      description: 'Read some lines of one input, starting at a line number (from a search).',
+      parameters: { type: 'object', properties: { input: inputProp, line: { type: 'integer', minimum: 1 }, count: { type: 'integer', minimum: 1, maximum: READ_LINES } }, required: ['line'] },
+      execute: async (a) => {
+        const name = which(a);
+        if (name === null) return { error: `name the input: ${labels.join(', ')}` };
+        const from = Math.max(1, Number.isInteger(a?.line) ? a.line : 1);
+        const n = Math.min(Number.isInteger(a?.count) ? a.count : 12, READ_LINES);
+        return { input: name, lines: lines[name].slice(from - 1, from - 1 + n).map((l, i) => ({ line: from + i, text: l.slice(0, READ_LINE) })) };
+      },
+    },
+  ];
+}
+
+/** the strict answer form (a JSON schema - never free prose with JSON inside) */
+export function lookReportSchema() {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    required: ['facts', 'prose', 'notFound'],
+    properties: {
+      facts: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['line', 'name', 'shape', 'source', 'example'],
+          properties: {
+            line: { type: 'integer', minimum: 1, description: 'the job line this fact belongs to' },
+            name: { type: 'string', minLength: 1, description: 'a short name, letters only' },
+            shape: { enum: [...FACT_SHAPES] },
+            source: { type: 'string', minLength: 1, description: 'the label of the input it is read from' },
+            label: { type: 'string', description: 'the words right before the value: the id (like t1) or the exact words of a label on the LIST for this input and shape - never a word you typed that is not on the list' },
+            value: { type: 'string', description: 'a phrase fact only: the fixed words, copied from the input exactly as it writes them (a place, a name, a word)' },
+            example: { type: 'string', description: 'ONE value you really saw in the input for this fact' },
+            rule: {
+              type: 'object',
+              additionalProperties: false,
+              required: ['op'],
+              properties: { op: { enum: [...FACT_OPS] }, value: {}, lo: {}, hi: {} },
+              description: 'only where the person asked for a limit (or you made one out of their words and set aiProposal)',
+            },
+            aiProposal: { type: 'boolean', description: 'true when YOU made this number out of the person\'s words (for example a night window for "not a red-eye")' },
+            forRule: { type: 'integer', minimum: 1, description: 'the number of the ~ rule under that line this fact carries out (1 = the first), when it carries one - a rule you turned into a number or range yourself ("not a red-eye") is carried by a fact with aiProposal, never reported as not found' },
+          },
+        },
+      },
+      prose: {
+        type: 'array',
+        description: 'job lines (and their ~ limits) that ask for written text - a summary, a report. They are not looked up.',
+        items: { type: 'object', additionalProperties: false, required: ['line'], properties: { line: { type: 'integer', minimum: 1 }, text: { type: 'string' } } },
+      },
+      notFound: {
+        type: 'array',
+        description: 'what you could not find in the input, and, when it is one ~ rule, which one',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['line', 'why'],
+          properties: { line: { type: 'integer', minimum: 1 }, rule: { type: 'integer', minimum: 1, description: 'the number of the ~ rule under that line (1 = the first), when the thing not found is one rule' }, words: { type: 'string', description: 'the person\'s own words that you could not find' }, why: { type: 'string', minLength: 1 } },
+        },
+      },
+    },
+  };
+}
+
+/**
+ * What the AI is told: the numbered job, the inputs and their label lists, and what to do.
+ * @param {{jobLines: {n: number, text: string, rule?: string, rules?: string[]}[], labels: string[], lists: Record<string, string>}} o
+ * @returns {string}
+ */
+export function lookPrompt({ jobLines, labels, lists }) {
+  const job = jobLines.map((l) => `${l.n}. ${l.text}${(l.rules ?? (l.rule ? l.rule.split('; ') : [])).map((r, i) => `\n   ~ ${i + 1}. ${r}`).join('')}`).join('\n');
+  return `The person's job (line numbers start at 1; "~" lines are the person's rules for the line above, numbered under it):\n${job}\n\n`
+    + `The inputs you can look at: ${labels.map((l) => JSON.stringify(l)).join(', ')}. You can only use search_input and read_input, then you MUST finish by calling ${LOOK_REPORT_TOOL} once.\n\n`
+    + `${labels.map((l) => lists[l]).join('\n\n')}\n\n`
+    + `Shapes a value can have: ${FACT_SHAPES.join(', ')} (phrase = fixed words the quote must contain; text = the words after a label).\n`
+    + 'For each job line, find the facts the person asked for and report ONLY what you can check in the input:\n'
+    + ' - Search the input with the person\'s words AND other words that mean the same, read the spots you find, and use what you know (for example what a red-eye is: propose a night time window and set aiProposal true).\n'
+    + ' - A ~ rule whose meaning you can turn into a number or a range from what you know (a red-eye is a night departure; a weekend; business hours) is NOT something to ask the person about and NOT "notFound": report it as a fact on the time, date or amount the input does hold, with a between (or other) rule, aiProposal true and forRule set to that rule\'s number. Use notFound with a rule number only for intent you cannot know (for example "one per week" when the input has no weekly grouping).\n'
+    + ' - Every place, date or name written in the job line itself is a fact too. Bind it to the label that sits right before it in the input - a direction like "from X to Y" is the label before the origin (for example Leaves) and the label before the destination (for example arrives at): report each as a phrase fact whose label is that label and whose value is the place EXACTLY as the input writes it.\n'
+    + ' - A label is PICKED from the LIST above (its id or its exact words) - never typed. A label that is not on the list is refused. Never use the person\'s own words as a label unless the list holds them, never a one-time id like [ref=...], and never one result\'s own value.\n'
+    + ' - Lines that ask for written prose (a summary, a short text) and the ~ limits on them (word count, paragraphs) are NOT looked up: put them in "prose" with their line number.\n'
+    + ' - Whatever you cannot find in the input goes to "notFound" with the person\'s own words; when it is one ~ rule, give that rule\'s number.\n'
+    + `Report only through ${LOOK_REPORT_TOOL}.`;
+}
+
+/** @typedef {{line: number, name: string, shape: string, source: string, label?: string, labelId?: string, value?: string, phrase?: string, example: string, rule?: any, aiProposal?: boolean, forRule?: number}} LookFact */
+/** @typedef {{line: number, rule?: number, words?: string, why: string}} LookNotFound */
+/** @typedef {{facts: LookFact[], prose: {line: number, text?: string}[], notFound: LookNotFound[]}} LookReport */
+
+/** @param {unknown} v @returns {v is Record<string, any>} */
+const isRec = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * Turn the AI's raw report into a VERIFIED one, by code, at $0. A fact is carried only when: its shape is a real shape, its source is
+ * a real input, and its label is ON THE LIST for that input and shape (an id is resolved to its exact words). Anything else is moved
+ * to `notFound` with a plain reason naming the word - never dropped silently. `prove` is the "found in the source" test of the
+ * phrase a phrase fact builds (label + value), supplied by the caller.
+ * @param {unknown} raw
+ * @param {{scans: Record<string, import('./labelscan.js').LabelScan>, jobLines: {n: number}[], prove?: (source: string, phrase: string) => number}} o
+ * @returns {LookReport}
+ */
+export function verifyLookReport(raw, { scans, jobLines, prove }) {
+  const rep = isRec(raw) ? raw : {};
+  const lineNos = new Set(jobLines.map((l) => l.n));
+  /** @type {LookFact[]} */
+  const facts = [];
+  /** @type {LookNotFound[]} */
+  const notFound = [];
+  const dropped = (/** @type {any} */ f, /** @type {string} */ why) => notFound.push({
+    line: Number.isInteger(f?.line) && lineNos.has(f.line) ? f.line : (jobLines[0]?.n ?? 1),
+    words: typeof f?.name === 'string' ? f.name : undefined,
+    why,
+  });
+  for (const f of Array.isArray(rep.facts) ? rep.facts : []) {
+    if (!isRec(f) || !Number.isInteger(f.line) || !lineNos.has(f.line)) { dropped(f, 'the look named a job line that does not exist'); continue; }
+    const name = typeof f.name === 'string' ? f.name.replace(/[^A-Za-z _-]/g, '').trim() : '';
+    if (name === '') { dropped(f, 'the look gave a fact no usable name'); continue; }
+    if (!FACT_SHAPES.includes(f.shape)) { dropped({ ...f, name }, `the look gave "${name}" a shape (${String(f.shape)}) that does not exist`); continue; }
+    const scan = typeof f.source === 'string' ? scans[f.source] : undefined;
+    if (!scan) { dropped({ ...f, name }, `the look read "${name}" from an input (${String(f.source)}) that is not one of yours`); continue; }
+    /** @type {LookFact} */
+    const out = { line: f.line, name, shape: f.shape, source: f.source, example: typeof f.example === 'string' ? f.example : '' };
+    if (typeof f.label === 'string' && f.label.trim() !== '') {
+      const row = labelOnList(scan, f.shape === 'phrase' ? 'text' : f.shape, f.label);
+      if (!row) { dropped({ ...f, name }, `the label "${normLabel(f.label)}" for "${name}" is not one of the labels found in "${f.source}", so it was not used`); continue; }
+      out.label = row.label;
+      out.labelId = row.id;
+    }
+    if (f.shape === 'phrase') {
+      const value = typeof f.value === 'string' ? normLabel(f.value) : '';
+      if (value === '') { dropped({ ...f, name }, `the look gave the phrase fact "${name}" no words`); continue; }
+      out.value = value;
+      out.phrase = out.label ? `${out.label} ${value}` : value;
+      if (prove && prove(f.source, out.phrase) < 1) { dropped({ ...f, name }, `"${out.phrase}" is not in the input "${f.source}"`); continue; }
+    }
+    if (isRec(f.rule)) out.rule = f.rule;
+    if (f.aiProposal === true) out.aiProposal = true;
+    if (Number.isInteger(f.forRule) && f.forRule >= 1) out.forRule = f.forRule;
+    facts.push(out);
+  }
+  for (const n of Array.isArray(rep.notFound) ? rep.notFound : []) {
+    if (!isRec(n) || !Number.isInteger(n.line) || !lineNos.has(n.line) || typeof n.why !== 'string') continue;
+    // a rule that a verified fact carries is checked, so it is not also "not found" (L3: a ~ rule is one or the other)
+    if (Number.isInteger(n.rule) && facts.some((x) => x.line === n.line && x.forRule === n.rule)) continue;
+    notFound.push({ line: n.line, ...(Number.isInteger(n.rule) ? { rule: n.rule } : {}), ...(typeof n.words === 'string' && n.words ? { words: n.words } : {}), why: n.why });
+  }
+  const prose = (Array.isArray(rep.prose) ? rep.prose : []).filter((p) => isRec(p) && Number.isInteger(p.line) && lineNos.has(p.line))
+    .map((p) => ({ line: p.line, ...(typeof p.text === 'string' ? { text: p.text.slice(0, 400) } : {}) }));
+  return { facts, prose, notFound };
+}
+
+/**
+ * The look's report as the DRAFTER reads it: one block, per job line, of what can be checked (with the exact words to copy) and what
+ * could not be found. Written by code from the verified report.
+ * @param {LookReport} report @returns {string}
+ */
+export function renderLookReport(report) {
+  const byLine = new Map();
+  const add = (/** @type {number} */ n, /** @type {string} */ s) => byLine.set(n, [...(byLine.get(n) ?? []), s]);
+  for (const f of report.facts) {
+    const bits = [`${f.name} - ${f.shape}`, `from "${f.source}"`];
+    if (f.phrase !== undefined) bits.push(`the quote must say ${JSON.stringify(f.phrase)}`);
+    else if (f.label !== undefined) bits.push(`label ${JSON.stringify(f.label)} (id ${f.labelId})`);
+    else bits.push('no label (the value as the quote writes it)');
+    if (f.example) bits.push(`seen: ${JSON.stringify(f.example)}`);
+    if (f.rule) bits.push(`rule ${JSON.stringify(f.rule)}`);
+    if (f.aiProposal) bits.push("AI's proposal");
+    if (f.forRule !== undefined) bits.push(`carries ~ rule ${f.forRule}`);
+    add(f.line, `CAN CHECK: ${bits.join(', ')}`);
+  }
+  for (const p of report.prose) add(p.line, 'WRITTEN TEXT (not looked up; keep its word/section counts)');
+  for (const n of report.notFound) add(n.line, `NOT FOUND${n.rule ? ` (rule ${n.rule})` : ''}: ${n.words ? `${JSON.stringify(n.words)} - ` : ''}${n.why}`);
+  const lines = [...byLine.keys()].sort((a, b) => a - b).map((n) => `line ${n}:\n${byLine.get(n).map((/** @type {string} */ s) => `  ${s}`).join('\n')}`);
+  return `WHAT THE LOOK AT THE INPUTS FOUND - write the facts from this; copy the label and phrase words exactly\n\n${lines.join('\n') || '(the look reported nothing)'}`;
+}
+
+/**
+ * The label scans and the rendered lists for the inputs the look will read.
+ * @param {Record<string, string>} texts
+ * @returns {{scans: Record<string, import('./labelscan.js').LabelScan>, lists: Record<string, string>}}
+ */
+export function labelListsOf(texts) {
+  /** @type {Record<string, import('./labelscan.js').LabelScan>} */
+  const scans = {};
+  /** @type {Record<string, string>} */
+  const lists = {};
+  for (const [label, text] of Object.entries(texts)) { scans[label] = scanLabels(text); lists[label] = renderLabelList(label, scans[label]); }
+  return { scans, lists };
+}
+
+export { LABEL_SHAPES };
+
+/**
+ * L3: a reason the AI gave, cut only at a sentence end (never mid-sentence): whole sentences while they fit in `max` characters,
+ * and nothing at all if the first one alone does not fit. A trailing full stop is dropped (the caller closes the clause).
+ * @param {string} text @param {number} max @returns {string}
+ */
+export function wholeSentences(text, max) {
+  const sentences = text.replace(/\s+/g, ' ').trim().split(/(?<=[.!?])\s+/).filter(Boolean);
+  let out = '';
+  for (const s of sentences) {
+    const next = out === '' ? s : `${out} ${s}`;
+    if (next.length > max) break;
+    out = next;
+  }
+  return out.replace(/[.!?]+$/, '');
+}
+
+/**
+ * I1 (hamr, 2026-10-13, "Ruled by hamr" 2): when the look shows the person's intent on one `~` rule was NOT captured - its words or
+ * meaning are not in the source - the person is asked about THAT rule at once, named by its line and rule. Only a look entry that names
+ * a rule number counts; anything else the look could not find is not asked piecemeal (it is Not checked, or the whole job is reviewed).
+ * The wording is the code's own, never the model's. The keep-or-drop and the cap are `normalizeQuestions` (src/authorflow.js).
+ * @param {LookNotFound[]} notFound @param {{n: number, text?: string, rule?: string, rules?: string[]}[]} jobLines
+ * @returns {{line: number, question: string}[]} every candidate question (the caller applies the machine's caps)
+ */
+export function ruleQuestions(notFound, jobLines) {
+  /** @type {{line: number, question: string}[]} */
+  const out = [];
+  /** @type {Set<string>} */
+  const seen = new Set();
+  for (const n of Array.isArray(notFound) ? notFound : []) {
+    if (!Number.isInteger(n.rule)) continue;
+    const line = jobLines.find((l) => l.n === n.line);
+    const rule = line ? lineRules(line)[/** @type {number} */ (n.rule) - 1] : undefined;
+    if (!line || rule === undefined) continue;
+    const key = `${n.line}:${n.rule}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const words = n.words ? `${JSON.stringify(n.words)} (from your words)` : 'what this rule asks for';
+    const why = wholeSentences(String(n.why), 200);
+    out.push({ line: n.line, question: `Line ${n.line}, rule ${n.rule} - "${rule}": I could not find ${words} in your input${why ? ` (${why})` : ''}. What do you mean by it? Your answer is added as a new ~ rule on line ${n.line}.` });
+  }
+  return out;
+}

package/src/job.js

@@ -16,6 +16,7 @@
 import { createHash } from 'node:crypto';
 import { globToPrefix, scopeContained, isObj, isNonEmptyString, sweepSecretLiterals, hasNestedQuantifier, closeScriptCandidateToken } from './validate.js';
 import { validateCloseDecl, DECLARED_CLOSE_CLASSES } from './declaredclose.js';
+import { inputLabelsOf } from './rubricstep.js';
 import { CLOSE_TIMEOUT_FLOOR_MS } from './closetimeout.js';
 
 // The menus below ARE the close-authoring hierarchy (PRD §7) and ship frozen:
@@ -795,7 +796,7 @@ function validatePlanShape(spec, red, reds) {
     // class the user picked (PRD v1.57 §2), so the gate cannot check D5 without
     // it. An unknown or locked class is refused there, on its own axis, beside
     // the counted `request-red` above.
-    const cd = validateCloseDecl(spec.closeDecl, { at: 'closeDecl', deferListing: true, verdictType: spec.verdictType, writeScope: spec.writeScope, jobLines: Array.isArray(spec.jobLines) ? spec.jobLines : null });
+    const cd = validateCloseDecl(spec.closeDecl, { at: 'closeDecl', deferListing: true, verdictType: spec.verdictType, writeScope: spec.writeScope, jobLines: Array.isArray(spec.jobLines) ? spec.jobLines : null, inputLabels: inputLabelsOf(spec.inputs) });
     for (const r of cd.reds) reds.push(r);
     if (demanded !== undefined && !CLASS_BY_CLOSE.declared.includes(demanded)) {
       // the same laundering guard as the close-type hierarchy, one level up: a

package/src/jobblock.js

@@ -113,16 +113,21 @@ export function renderInputs(inputs) {
  * The two cross-checks between a parsed job block and the Check type: a RUBRIC job needs at least one `PASS:` and one
  * `FAIL:` example (the calibration compile reads them); a DETERMINISTIC job has no judge, so an example line would be
  * silently dropped — a red instead.
+ * PART 1a (hamr's ruling P1=B, docs/product/ITEM33-BUILD.md "Addendum 2026-10-12"): the examples are required of a rubric
+ * job ONLY when it holds a judged part. A rubric job on the person's own local files holds none in this build (its
+ * parts are counted or checked against a quote), so the caller says `judged: false` and a block without examples fits.
+ * Examples written anyway are never a red there — they simply have no judge to read them yet.
  * @param {JobLine[]} lines
  * @param {boolean} rubric
+ * @param {{judged?: boolean}} [o] `judged` (default true): does this job hold a judged part, so that it needs examples?
  * @returns {string|null} the plain red, or null when the block fits the Check type
  */
-export function jobBlockFitsCheck(lines, rubric) {
+export function jobBlockFitsCheck(lines, rubric, { judged = true } = {}) {
   const all = lines.flatMap((l) => l.examples.map((e) => ({ n: l.n, ...e })));
   if (!rubric) {
     return all.length ? `The job, line ${all[0].n}: PASS:/FAIL: examples are for a Rubric check — a Deterministic job has no judge to read them` : null;
   }
-  if (!all.some((e) => e.verdict === 'PASS') || !all.some((e) => e.verdict === 'FAIL')) {
+  if (judged && (!all.some((e) => e.verdict === 'PASS') || !all.some((e) => e.verdict === 'FAIL'))) {
     return 'The job: a Rubric check needs at least one "~ PASS:" line and one "~ FAIL:" line under a job line';
   }
   return null;

package/src/kinds.js

@@ -61,13 +61,14 @@
 
 import { spawn } from 'node:child_process';
 import { realpathSync } from 'node:fs';
-import { readFile, stat, mkdtemp, rm, symlink } from 'node:fs/promises';
+import { readFile, stat, lstat, mkdtemp, rm, symlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, sep } from 'node:path';
+import { join, sep, dirname } from 'node:path';
 import { globToPrefix, isNonEmptyString } from './validate.js';
 import { CLOSE_ENV_DENY } from './ralph.js';
 import { runLocate, decide, validateCard, LOCATE_AXES, LOCATE_LABEL } from './judged.js';
 import { rateSourceFields } from './text.js';
+import { gradeStep, stepFileRel, STEP_MAX_BYTES, citedLabels, sha256Of } from './rubricstep.js';
 
 /** the close's two judgment exits — a stage's verdict, in the shape the
  * hand-written closes already spoke (exit code is truth) */
@@ -140,7 +141,7 @@ export const SIGNS = Object.freeze([1, -1]);
  * executor runs that the catalogue never names is a capability nothing can
  * reach. `judged-floor` joined at softgreen module 2 — the runner and the
  * catalogue unlock in ONE commit for exactly that reason. */
-export const LIVE_KINDS = Object.freeze(['command-exit', 'count-not-worse', 'pattern-absent-in-diff', 'files-changed', 'human-confirms', 'judged-floor']);
+export const LIVE_KINDS = Object.freeze(['command-exit', 'count-not-worse', 'pattern-absent-in-diff', 'files-changed', 'human-confirms', 'judged-floor', 'rubric-step']);
 /**
  * The judged stage's ladder: ONE attempt plus ONE retry, and no more.
  *
@@ -1526,6 +1527,85 @@ async function runFilesChanged(stage, ctx) {
   });
 }
 
+/**
+ * PART 1a — the `rubric-step` kind: grade ONE job line's step file (output/steps/N.json) with bareguard's rubric primitive.
+ * It spawns nothing and buys nothing. The inputs a step cites are read from the frozen tree (`input/...`) and held to the
+ * sha256 the SOURCE DOOR recorded in `<into>/source.json` (`inputs: [{label, rel, sha256}]`), so an input that changed after
+ * the freeze is a stopped instrument, never a green. The rubric is built here, at every run, from the stage's own parameters
+ * (the inputs belong to the run, not to the signed job). A step file that is missing, cut off, or not a JSON object is a RED
+ * (the worker has not finished the line); an instrument that cannot read what it must is a STOP (97), never a red.
+ * @param {any} stage @param {Ctx} ctx @returns {Promise<StageResult>}
+ */
+async function runRubricStep(stage, ctx) {
+  const p = stage.params;
+  const step = p.step;
+  const stop = (/** @type {string} */ why, /** @type {string} */ fault = STOP_FAULTS.FAILED) => stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}": ${why}`, { step }, fault);
+  // the source door's record of what was frozen: beside the tree, one level up (`<into>/source.json`, `<into>/tree`)
+  /** @type {any} */
+  let manifest;
+  try { manifest = JSON.parse(await readFile(join(dirname(ctx.workdir), 'source.json'), 'utf8')); } catch (e) {
+    return stop(`the source record (source.json beside the job's tree) could not be read: ${/** @type {Error} */ (e).message}`);
+  }
+  const recorded = Array.isArray(manifest?.inputs) ? manifest.inputs : [];
+  /** @type {Record<string, string>} */
+  const inputShas = {};
+  /** @type {Record<string, string>} */
+  const inputs = {};
+  for (const label of citedLabels(p)) {
+    const row = recorded.find((/** @type {any} */ r) => r && r.label === label);
+    if (!row || typeof row.rel !== 'string' || typeof row.sha256 !== 'string') return stop(`the step cites "${label}", but the source record has no input with that label`);
+    let buf;
+    try { buf = await readFile(join(ctx.workdir, row.rel)); } catch (e) { return stop(`input "${label}" (${row.rel}) could not be read: ${/** @type {Error} */ (e).message}`); }
+    if (sha256Of(buf) !== row.sha256) return stop(`input "${label}" (${row.rel}) no longer matches the bytes frozen at the source door`);
+    inputShas[label] = row.sha256;
+    inputs[label] = buf.toString('utf8');
+  }
+  // the step file: a regular file, read once, bounded
+  const abs = join(ctx.workdir, stepFileRel(step));
+  /** @type {string|null} */
+  let bytes = null;
+  let notRegular = false;
+  try {
+    const ls = await lstat(abs);
+    if (!ls.isFile()) notRegular = true;
+    else if (ls.size > STEP_MAX_BYTES) return stop(`${stepFileRel(step)} is over the ${STEP_MAX_BYTES} byte limit the rubric reads`);
+    else bytes = (await readFile(abs)).toString('utf8');
+  } catch (e) {
+    if (/** @type {any} */ (e)?.code !== 'ENOENT') return stop(`${stepFileRel(step)} could not be read: ${/** @type {Error} */ (e).message}`);
+  }
+  // PART 1b: a prose step's numbers are tied to the quotes the earlier fact lines' step files hold (those stages ran, and were
+  // green, before this one: the close is first-red-wins in stage order, which the validator pins). Unreadable = a stopped instrument.
+  /** @type {Record<number, string[]>} */
+  const factQuotes = {};
+  /** @type {number[]} */
+  const factMissing = [];
+  const tie = Array.isArray(p.parts) ? p.parts.find((/** @type {any} */ x) => x && x.class === 'countable' && x.check === 'numbersFromFacts') : null;
+  for (const n of tie ? tie.from : []) {
+    try {
+      const parsedFacts = JSON.parse(await readFile(join(ctx.workdir, stepFileRel(n)), 'utf8'));
+      const results = Array.isArray(parsedFacts?.results) ? parsedFacts.results : [];
+      factQuotes[n] = results.map((/** @type {any} */ r) => (r && typeof r.quote === 'string' ? r.quote : ''));
+    } catch (e) {
+      // M2: an earlier line's file that is not there (the seed read, before any worker wrote) is a normal red, never an instrument fault
+      if (/** @type {any} */ (e)?.code === 'ENOENT') { factMissing.push(n); continue; }
+      return stop(`the checked facts of line ${n} (${stepFileRel(n)}) could not be read for the number tie: ${/** @type {Error} */ (e).message}`);
+    }
+  }
+  const graded = await gradeStep({ params: p, bytes: notRegular ? null : bytes, outputBytes: notRegular ? null : bytes, inputs, factQuotes, factMissing }, inputShas);
+  if (graded.verdict === 'stopped') return stop(`the rubric stopped: ${graded.fault}`, STOP_FAULTS.CRASHED);
+  const gap = new Gap(ctx.gapKeep, ctx.gapCap);
+  if (notRegular) gap.push(`${stage.name}: line ${step}: ${stepFileRel(step)} is not a regular file`);
+  for (const l of graded.gapLines) gap.push(`${stage.name}: ${l}`);
+  const red = graded.verdict === 'red' || notRegular;
+  return result(stage, {
+    verdict: red ? 'red' : 'green',
+    exitCode: red ? EXIT_RED : EXIT_GREEN,
+    gapLines: gap.render(),
+    // the trend number (`trendValueOf`, src/declaredclose.js, reads `detail.redCount` for a stage with no measurement)
+    detail: { ...graded.detail, ...(notRegular ? { redCount: 1 } : {}) },
+  });
+}
+
 /**
  * THE SIGNER'S ANSWER, normalised at the seam that accepts it — the library half
  * of the three-button gate (2026-08-12 §1).
@@ -1954,6 +2034,7 @@ const RUNNERS = {
   'files-changed': runFilesChanged,
   'human-confirms': runHumanConfirms,
   'judged-floor': runJudgedFloor,
+  'rubric-step': runRubricStep,
 };
 
 /**