bareloop 0.41.0 → 0.42.0

package/types/authoring.d.ts

@@ -64,6 +64,15 @@ export function classMenu(verdictType: string | null, catalogue?: Record<string,
  * @param {string} kind @param {Record<string, KindSpec>} [catalogue]
  */
 export function envCapableKind(kind: string, catalogue?: Record<string, KindSpec>): boolean;
+/**
+ * The catalogue a close of this language may use. A rubric job on local files (`RUBRIC_LANG`) sees only
+ * {@link RUBRIC_LANG_KINDS}; every code language sees the whole catalogue MINUS the rubric-only kinds, so a code job's
+ * composer, schema and validator can never reach for a stage that reads step files. One filter, both directions.
+ * @param {string|null|undefined} lang
+ * @param {Record<string, KindSpec>} [catalogue]
+ * @returns {Record<string, KindSpec>}
+ */
+export function catalogueForLang(lang: string | null | undefined, catalogue?: Record<string, KindSpec>): Record<string, KindSpec>;
 /**
  * The floor's decision for one declared `cmd`, as a reason or null.
  *
@@ -80,6 +89,8 @@ export function envCapableKind(kind: string, catalogue?: Record<string, KindSpec
  * @param {string} cmd @returns {string|null}
  */
 export function deniedCommandReason(cmd: string): string | null;
+/** @param {unknown} lang @returns {string} the genre a close of this language is authored under */
+export function genreForLang(lang: unknown): string;
 /**
  * The warning line for a job whose ACTUAL stages carry the js `any` pattern, else
  * ''. Derived from the stages' patterns (never goal prose), so a job without the
@@ -274,7 +285,8 @@ export function judgedOutsideFence(paths: unknown, writeScope: string[] | null |
  * @param {{catalogue?: Record<string, KindSpec>, listing?: string[]|null,
  *   guards?: {name: string, kind: string, params: Record<string, any>, fill: string[]}[]|null,
  *   envOwned?: string[]|null, envInjected?: Record<string, string>|null, deferListing?: boolean,
- *   verdictType?: string|null, writeScope?: string[]|null, jobLines?: {n: number}[]|null}} [opts]
+ *   verdictType?: string|null, writeScope?: string[]|null, jobLines?: {n: number}[]|null, inputLabels?: string[]|null}} [opts]
+ *   `inputLabels` — the labels of the person's inputs (Part 1a). Present, a rubric-step `cited` part must name one of them.
  *   `jobLines` — the person's numbered job lines (P7). Present, every stage must name the line it serves and every
  *     line needs a stage or a refusal ({@link checkJobLines}); absent (every spec that predates the job block), the
  *     rule is not run.
@@ -310,6 +322,7 @@ export function validateDeclaration(declaration: any, opts?: {
     jobLines?: {
         n: number;
     }[] | null;
+    inputLabels?: string[] | null;
 }): {
     ok: boolean;
     reds: Red[];
@@ -482,6 +495,21 @@ export const DENIED_COMMANDS: readonly string[];
  */
 export const TYPES_GENRE_TEMPLATE: "1. The STRICT form of the language's type checker is used only when a confirmed check \u2014 or,\n   absent a confirm turn, the goal and interview answers \u2014 asks for strict typing; otherwise the\n   checker runs at whatever strictness the repo's own scripts already use.\n2. Tools are invoked so their binaries actually resolve \u2014 through the project's own package\n   runner or language module runner, never a bare binary name.\n3. The WORK stages \u2014 typecheck (error count IN the target scope, baseline 0, lower-is-better),\n   typecheck-outside (error count OUTSIDE the target scope, baseline measured at seed, a\n   ceiling \u2014 required whenever a typecheck stage is scoped to a subset of the tree), tests-kept\n   (a floor on tests that actually EXECUTED, baseline at seed, higher-is-better; a skipped or\n   deselected test did not run and must not count), and suite-green (the suite exits clean AND\n   reports zero failing tests \u2014 two assertions) \u2014 are composed ONLY for the checks a confirmed\n   plan asked for (or, absent a confirm turn, the goal and interview answers). The GUARDS \u2014\n   changed-from-seed and no-suppressions \u2014 are composed always, first-red-wins:\n   changed-from-seed before every WORK stage, no-suppressions last.\n4. One population per stage \u2014 two structurally different counts never share a stage.\n5. The checker must judge the PATIENT's own tree: if imports could resolve to an installed or\n   editable copy elsewhere, the environment is set so they resolve inside the patient.\n6. A number the tool did not report is unknown, never zero.";
 export const GENRE_LANGUAGES: readonly string[];
+/**
+ * PART 1a: the "language" of a RUBRIC job on local text files. It is not a code language and carries no suppression
+ * battery, no environment and no instruments — it only lets such a close declare which genre-shaped guards apply to it
+ * (`classGuards`) without pretending the file is JavaScript. `GENRE_LANGUAGES` stays the code-language menu (it is what a
+ * repo job's language detection and the confirm turn offer); this is the one extra value a close may DECLARE.
+ */
+export const RUBRIC_LANG: "text";
+/** the genre label a close over local text files carries (`closeDecl.genre`); the code languages' is `TYPES_GENRE.name`. Never the other's. */
+export const TEXT_GENRE: "TEXT";
+/** every `closeDecl.lang` a close may declare: the code languages plus the rubric-files one */
+export const DECLARABLE_LANGUAGES: readonly string[];
+/** the kinds that exist only for a rubric job on local files — a code job's menu, schema and validator never offer them */
+export const RUBRIC_ONLY_KINDS: readonly string[];
+/** the whole kind menu of a rubric job on local files: the one machine guard that applies to a file tree, plus its own stage */
+export const RUBRIC_LANG_KINDS: readonly string[];
 /** The worker-facing line that rides with the js `any` guard (run mv13ery3). */
 export const ANY_SUPPRESSION_WARNING: string;
 /**

package/types/authorjob.d.ts

@@ -30,18 +30,19 @@ export function refusalEvents(refusal: Refusal): {
  *     makes between a locked verdict and an invalid one).
  *
  * @param {{answers: Record<string|number, any>, verdictType?: string|null,
- *   repoPath?: string|null, questions?: Record<string|number, string>|null}} o
- *   `verdictType` and `repoPath` are STRUCTURED input from the UI, never parsed
+ *   repoPath?: string|null, questions?: Record<string|number, string>|null, required?: (string|number)[]|null}} o
+ *   `required` — the answer keys that must be present; absent = the picked class's whole set. `verdictType` and `repoPath` are STRUCTURED input from the UI, never parsed
  *   out of the prose of an answer: a class is picked off a radio and a path is
  *   read off the machine, or neither exists.
  * @returns {{ok: boolean, answers: Record<string|number, string>,
  *   verdictType: string|null, repoPath: string|null, refusal: Refusal|null, reds: Red[]}}
  */
-export function runInterview({ answers, verdictType, repoPath, questions }: {
+export function runInterview({ answers, verdictType, repoPath, questions, required: requiredOverride }: {
     answers: Record<string | number, any>;
     verdictType?: string | null;
     repoPath?: string | null;
     questions?: Record<string | number, string> | null;
+    required?: (string | number)[] | null;
 }): {
     ok: boolean;
     answers: Record<string | number, string>;
@@ -86,7 +87,7 @@ export function refuseLockedKind(kind: string): Refusal;
  *   rates?: {in: number, out: number}|null, draftThinking?: 'on'|'off',
  *   onPhase?: (phase: string, data?: any) => void,
  *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number, thinkingStatus?: string}) => void,
- *   seedFn?: Function, scoutFn?: Function, listingFn?: Function,
+ *   seedFn?: Function, scoutFn?: Function, listingFn?: Function, lookFn?: Function|null,
  *   authorFn?: Function, authorOpts?: object, writeScope?: string[]|null,
  *   signerFix?: Function|any, proposeFn?: Function, compileOpts?: object,
  *   ask?: ((step: {kind: string, [k: string]: any}) => Promise<string|null>)|null,
@@ -98,7 +99,7 @@ export function refuseLockedKind(kind: string): Refusal;
  *   closeDecl: any, seedRef: string|null, authoring: any, judged: any, reds: Red[],
  *   stop: string|null, cost: any, interview: any, confirmed: any}>}
  */
-export function authorCloseForJob({ answers, repoPath, lang, verdictType, questions, jobLines, inputs, generate, provider, seedRef, scout, listing, ceilingUsd, rates, draftThinking, writeScope, judgeModel, onPhase, onCall, seedFn, scoutFn, listingFn, authorFn, authorOpts, signerFix, proposeFn, compileOpts, ask, confirmGenerate, isRepo, langResult, answerQuestions, }: {
+export function authorCloseForJob({ answers, repoPath, lang, verdictType, questions, jobLines, inputs, generate, provider, seedRef, scout, listing, ceilingUsd, rates, draftThinking, writeScope, judgeModel, onPhase, onCall, seedFn, scoutFn, listingFn, lookFn, authorFn, authorOpts, signerFix, proposeFn, compileOpts, ask, confirmGenerate, isRepo, langResult, answerQuestions, }: {
     answers: Record<string | number, any>;
     repoPath?: string | null;
     lang: string;
@@ -135,6 +136,7 @@ export function authorCloseForJob({ answers, repoPath, lang, verdictType, questi
     seedFn?: Function;
     scoutFn?: Function;
     listingFn?: Function;
+    lookFn?: Function | null;
     authorFn?: Function;
     authorOpts?: object;
     writeScope?: string[] | null;

package/types/authorreadout.d.ts

@@ -199,6 +199,29 @@ export function plainKinds(): string[];
 export function plainReasons(reds: PlainRed[], { cases }?: {
     cases?: any;
 }): PlainReason[];
+/**
+ * WHY one drafting try was refused, in the code's own words: the unique `detail` of each red it raised (the same sentences
+ * `draftStopText` quotes at a stop), else the plain `reason` the loop gave (a seed-read failure raises no red). Scrubbed,
+ * one line, bounded; never empty.
+ * @param {{reds?: PlainRed[]|null, reason?: string|null}} o
+ * @returns {string}
+ */
+export function tryRefusedText({ reds, reason }: {
+    reds?: PlainRed[] | null;
+    reason?: string | null;
+}): string;
+/**
+ * A refused declaration as the drafting log keeps it (live fix A3), so a failed draft can be read and replayed at $0: the declaration
+ * itself, every secret masked as everywhere else (the JSON text goes through `redactSecrets`, then parses back), and bounded.
+ * @param {unknown} declaration
+ * @returns {{declaration: unknown}|{declarationText: string, declarationCut: true}|{}} nothing when there is no declaration
+ */
+export function declarationRecord(declaration: unknown): {
+    declaration: unknown;
+} | {
+    declarationText: string;
+    declarationCut: true;
+} | {};
 /**
  * THE MESSAGE a person reads when the rubric proposal was refused. Both doors
  * (the panel's failed step and the CLI) print exactly this.
@@ -218,10 +241,11 @@ export function proposalStopText({ stop, reds, cases, spend, source }: {
 }): string;
 /**
  * @param {{stop: string, reds?: PlainRed[]|null, refusal?: {detail?: string}|null,
- *   spend?: {knownUsd?: number|null, spendComplete?: boolean|null}|null}} o
+ *   spend?: {knownUsd?: number|null, spendComplete?: boolean|null}|null, wholeJob?: boolean}} o `wholeJob` - a rubric job on the person's
+ *   own inputs (PART 1c, I1): a failed draft asks nothing piecemeal; the person reviews the whole job and submits it again
  * @returns {string}
  */
-export function draftStopText({ stop, reds, refusal, spend }: {
+export function draftStopText({ stop, reds, refusal, spend, wholeJob }: {
     stop: string;
     reds?: PlainRed[] | null;
     refusal?: {
@@ -231,6 +255,7 @@ export function draftStopText({ stop, reds, refusal, spend }: {
         knownUsd?: number | null;
         spendComplete?: boolean | null;
     } | null;
+    wholeJob?: boolean;
 }): string;
 /**
  * Plain sentences for the reds of a refused signing, one or more per red. Card and practice-case reds reuse the

package/types/authorscout.d.ts

@@ -147,6 +147,72 @@ export function runAuthorScout({ workdir, provider, rounds, minBytes, blobMax, m
     }[];
     budgetStop: "cap-halt" | "pricing-red" | null;
 }>;
+/**
+ * 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 function runInputLook({ texts, inputs, jobLines, provider, rounds, maxTokens, ceilingUsd, callTimeoutMs, onCall, createLoop, rates, callOptions, prove, }: {
+    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;
+}): 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;
+}>;
 /**
  * `git ls-tree -r --name-only <seed>` — the files as of the SEED COMMIT.
  * Deliberately NOT `ls-files`, which reads the index and the working tree: this
@@ -336,6 +402,10 @@ export const SCOUT_SYSTEM: string;
  * produce) — never by asking politely in prose (F19/F37).
  */
 export const SCOUT_RECOVERY_PROMPT: string;
+/** the look's hard round bound */
+export const LOOK_ROUNDS: 8;
+export const LOOK_SYSTEM: string;
+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.";
 /** per-path full-listing cap; over it, names give way to counted directories */
 export const LIST_CAP: 40;
 /** whole-block ceiling — the block is a prompt ingredient, like the survey */

package/types/declaredclose.d.ts

@@ -53,7 +53,8 @@ export function declaredStages(closeDecl: any): any[] | null;
  *
  * @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}}
@@ -68,6 +69,7 @@ export function validateCloseDecl(closeDecl: any, opts?: {
     jobLines?: {
         n: number;
     }[] | null;
+    inputLabels?: string[] | null;
 }): {
     ok: boolean;
     reds: Red[];
@@ -162,7 +164,7 @@ export function closeGrade(v: any): {
 /** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
 /** 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: readonly "TYPES"[];
+export const DECLARED_GENRES: readonly string[];
 /**
  * The exact field set of a `closeDecl` — anything else is a smuggle channel, the
  * same rule `STAGE_FIELDS` enforces on a command stage.

package/types/facts.d.ts

@@ -0,0 +1,71 @@
+/** 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: any): any | null;
+/**
+ * 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: any, w: string, red: (code: string, path: string, detail: string) => void): void;
+/**
+ * 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: any): Record<string, any>[];
+/**
+ * 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: any, results: unknown): {
+    claim: string;
+    quote: string;
+    values?: Record<string, string>;
+}[];
+/**
+ * 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: any, source: string): string;
+/**
+ * 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: any): string;
+/** the "N results" row of a fact part, or null @param {any} part @returns {string|null} */
+export function countSentence(part: any): string | null;
+/**
+ * Every plan-card row a fact part carries: its facts, then its count.
+ * @param {any} part @returns {string[]}
+ */
+export function factRows(part: any): string[];
+/**
+ * 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: string, part: any): string;
+/**
+ * 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(): Record<string, string[]>;
+/**
+ * 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(): string;
+/** the shapes a fact may have (bareguard's value kinds, plus `phrase` = a presence decide) */
+export const FACT_SHAPES: readonly string[];
+/** the comparison ops a rule may use (bareguard's) */
+export const FACT_OPS: readonly string[];
+/** bareguard signs at most this many decides on one `cited` check */
+export const MAX_FACTS: 10;
+/** every field a part of class `fact` may carry (the shared ones are checked by rubricStepShapeReds) */
+export const FACT_PART_FIELDS: readonly string[];

package/types/factwords.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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: string, words: string): number;
+/**
+ * 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: string, words: string): number;
+/**
+ * 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 }: {
+    part: any;
+    text: string;
+    line: number | string;
+    scan?: import("./labelscan.js").LabelScan;
+}): {
+    code: string;
+    detail: string;
+}[];
+/**
+ * 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: any, texts: Record<string, string> | null): {
+    code: string;
+    path: string;
+    detail: string;
+}[];
+/**
+ * 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: Record<string, string>): (source: string, phrase: string) => number;
+export function squash(t: string): string;

package/types/inputlook.d.ts

@@ -0,0 +1,238 @@
+/**
+ * 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: string): string[];
+/**
+ * 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: Record<string, string>): {
+    name: string;
+    description: string;
+    parameters: any;
+    execute: (a: any) => Promise<any>;
+}[];
+/** the strict answer form (a JSON schema - never free prose with JSON inside) */
+export function lookReportSchema(): {
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        facts: {
+            type: string;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    line: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    name: {
+                        type: string;
+                        minLength: number;
+                        description: string;
+                    };
+                    shape: {
+                        enum: string[];
+                    };
+                    source: {
+                        type: string;
+                        minLength: number;
+                        description: string;
+                    };
+                    label: {
+                        type: string;
+                        description: string;
+                    };
+                    value: {
+                        type: string;
+                        description: string;
+                    };
+                    example: {
+                        type: string;
+                        description: string;
+                    };
+                    rule: {
+                        type: string;
+                        additionalProperties: boolean;
+                        required: string[];
+                        properties: {
+                            op: {
+                                enum: string[];
+                            };
+                            value: {};
+                            lo: {};
+                            hi: {};
+                        };
+                        description: string;
+                    };
+                    aiProposal: {
+                        type: string;
+                        description: string;
+                    };
+                    forRule: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                };
+            };
+        };
+        prose: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    line: {
+                        type: string;
+                        minimum: number;
+                    };
+                    text: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        notFound: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    line: {
+                        type: string;
+                        minimum: number;
+                    };
+                    rule: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    words: {
+                        type: string;
+                        description: string;
+                    };
+                    why: {
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
+        };
+    };
+};
+/**
+ * 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 }: {
+    jobLines: {
+        n: number;
+        text: string;
+        rule?: string;
+        rules?: string[];
+    }[];
+    labels: string[];
+    lists: Record<string, string>;
+}): string;
+/**
+ * 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: unknown, { scans, jobLines, prove }: {
+    scans: Record<string, import("./labelscan.js").LabelScan>;
+    jobLines: {
+        n: number;
+    }[];
+    prove?: (source: string, phrase: string) => number;
+}): LookReport;
+/**
+ * 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: LookReport): string;
+/**
+ * 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: Record<string, string>): {
+    scans: Record<string, import("./labelscan.js").LabelScan>;
+    lists: Record<string, string>;
+};
+/**
+ * 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: string, max: number): string;
+/**
+ * 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: LookNotFound[], jobLines: {
+    n: number;
+    text?: string;
+    rule?: string;
+    rules?: string[];
+}[]): {
+    line: number;
+    question: string;
+}[];
+/** 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;
+export { LABEL_SHAPES };
+export type LookFact = {
+    line: number;
+    name: string;
+    shape: string;
+    source: string;
+    label?: string;
+    labelId?: string;
+    value?: string;
+    phrase?: string;
+    example: string;
+    rule?: any;
+    aiProposal?: boolean;
+    forRule?: number;
+};
+export type LookNotFound = {
+    line: number;
+    rule?: number;
+    words?: string;
+    why: string;
+};
+export type LookReport = {
+    facts: LookFact[];
+    prose: {
+        line: number;
+        text?: string;
+    }[];
+    notFound: LookNotFound[];
+};
+import { LABEL_SHAPES } from './labelscan.js';

package/types/jobblock.d.ts

@@ -52,11 +52,18 @@ export function renderInputs(inputs: JobInput[]): string;
  * 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: JobLine[], rubric: boolean): string | null;
+export function jobBlockFitsCheck(lines: JobLine[], rubric: boolean, { judged }?: {
+    judged?: boolean;
+}): string | null;
 /**
  * The signed `jobLines` field from parsed lines: the person's own words, `{n, text, rule, rules}` (examples stay inside the
  * rule text, where the person wrote them). `rules` is the same `~` lines as an array, BESIDE the joined `rule` (never