@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/wiring-claims.js

@@ -1,31 +1,22 @@
 /**
- * Deterministic synthesized-wiring scanner for a composed spec (run-8 F3, gen side).
+ * Deterministic synthesized-wiring scanner for a composed spec, wired as the
+ * `synthesized-wiring` critique probe.
  *
- * F3 (the dominant run-8 shipped defect): refine/compose invent a "uniform" wiring
- * table — one module → one mount prefix, `/api/<x>` → `<x>Routes` for every module —
- * though the design pins ENDPOINTS, not mounts, and one module's pinned endpoints do
- * NOT all sit under a single prefix (photos: `POST /api/listings/:id/photos` AND
- * `GET/DELETE /api/photos/:id`). Mounting that module at `/api/photos` double-prefixes
- * the upload; consumers follow the pinned paths, assembly follows the invented table,
- * the seam ships broken. See [[contract-registry-f3]] (#4, the verify-side + registry
- * lever) — this is its GENERATION-side complement.
- *
- * A/B-measured on the live 27B (F3 critique trap): the CROSS-SLICE CONTRACTS registry
- * is NECESSARY but the prompt+registry alone is a WEAK catcher (A/B arms 0/8, +registry
- * only 1/8) — the model's attention goes to the obvious VERIFY weakness and it rarely
- * does the path-composition reasoning even with the facts in front of it. The reliable
- * lever is the SAME probe+rule pattern as [[skip-escape-scanner-f2]] / [[verify-
- * substitution-ab]]: a deterministic finding that NAMES the exact synthesized mappings
- * and juxtaposes the verbatim pinned facts, forcing focused reconciliation.
+ * The failure it catches: a spec states a "uniform" wiring table — one module to one
+ * mount prefix, `/api/<x>` → `<x>Routes` — while the design pins ENDPOINTS, not
+ * mounts. When a module's pinned endpoints do NOT all sit under a single prefix
+ * (`POST /api/listings/:id/photos` AND `GET /api/photos/:id`), mounting it at
+ * `/api/photos` double-prefixes the upload. Consumers follow the pinned paths,
+ * assembly follows the invented table, and the seam ships broken.
  *
  * This scanner does NOT decide which mapping is wrong — that needs routing-composition
- * knowledge (a forbidden stack assumption). It surfaces every mapping that (a) is not a
- * verbatim substring of the design/registry (so it is INFERRED, not cited) AND (b) touches
- * a pinned cross-slice boundary (an operand appears in the registry) — i.e. it reshapes a
- * shared contract. The 4 coincidentally-correct mappings are surfaced too, but framed as
- * "reconcile each; keep the conforming ones" — the LLM decides, informed. Pure text/
- * substring analysis; no stack, framework, or routing assumptions. Empty registry (single
- * `/task`, or no shared boundary) ⇒ no-op.
+ * knowledge, which would be a stack assumption. It surfaces every mapping that (a) is
+ * not a verbatim substring of the design or registry, so it is INFERRED rather than
+ * cited, AND (b) touches a pinned cross-slice boundary, meaning an operand appears in
+ * the registry. Conforming mappings are surfaced too, framed as "reconcile each; keep
+ * the conforming ones" — the model decides, informed. Pure text and substring analysis;
+ * no stack, framework, or routing assumptions. An empty registry (a single `/task`, or
+ * a design pinning no shared boundary) is a no-op.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -37,8 +28,9 @@ const ARROW = '(?:→|->|=>|⇒|↦)';
 const MAPPING_LINE_RE = new RegExp(`^[ \\t]*[-*]?[ \\t]*(.+?)[ \\t]*${ARROW}[ \\t]*(.+?)[ \\t]*$`);
 /** An operand shorter than this is too generic to anchor a boundary match. */
 const MIN_OPERAND_LENGTH = 4;
-/** Collapse whitespace + lowercase; drop markdown backticks so quoting formatting
- *  differences don't defeat the substring match. Mirrors contracts.ts's normalise. */
+/** Collapse whitespace + lowercase, and drop markdown backticks so a spec that
+ *  quotes `/api/photos` still matches a design that writes it bare. That backtick
+ *  strip is the one thing this does beyond contracts.ts's `normalise`. */
 function normalise(s) {
     return s.replace(/`/g, '').replace(/\s+/g, ' ').trim().toLowerCase();
 }
@@ -68,9 +60,9 @@ export function findSynthesizedWiring(spec, grounding, registry) {
         // Cited, not synthesized: the whole mapping appears verbatim in the source.
         if (groundHay.includes(key))
             continue;
-        // Only a mapping that touches a PINNED shared boundary is an F3 suspect — this
-        // is the crisp discriminator that keeps internal-flow prose ("input → output")
-        // out. An operand (long enough to be specific) must appear in the registry.
+        // Only a mapping that touches a PINNED shared boundary is a suspect. That is
+        // the discriminator keeping internal-flow prose ("input → output") out: an
+        // operand, long enough to be specific, must appear in the registry.
         const touchesBoundary = [from, to].some(op => {
             const n = normalise(op);
             return n.length >= MIN_OPERAND_LENGTH && regHay.includes(n);
@@ -111,22 +103,25 @@ export function wiringProbeText(findings, registry) {
     ].join('\n');
 }
 /**
- * Render findings as a critique-rewrite defect block (fed into the FOCUS list): the
- * rewrite must reconcile each mapping against the pinned facts and correct only the
- * one(s) that break. Mirrors skipEscapeDefectText's shape.
+ * The same text under the name the critique-rewrite defect path uses. One rendering
+ * serves both readers, so the probe the model sees and the defect the rewrite is
+ * handed can never drift apart.
  */
 export function wiringDefectText(findings, registry) {
     return wiringProbeText(findings, registry);
 }
 // An @-file mention in a spec ("@DESIGN/foo.md"), minus trailing prose punctuation.
-// Mirrors phantom-imports' mention rules so grounding sees the same source docs.
+// Byte-identical to auto-orchestrator.ts's pair, so grounding resolves the same
+// mentions the planner already resolved. `@` must follow start-of-string or
+// whitespace, so "mail@DESIGN.md" is not a mention.
 const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
 const MENTION_TRAILING_PUNCT = /[.,;:!?)\]}>"']+$/;
 /**
  * Concatenate the design/spec docs the given texts @-reference (best-effort, readable
  * files only) as extra grounding for findSynthesizedWiring — so a mapping the design
- * states verbatim is treated as CITED, not synthesized. Unreadable/absent mentions are
- * skipped; returns '' when nothing resolves.
+ * states verbatim is treated as CITED, not synthesized. Each path is read once across
+ * all texts; unreadable or absent mentions are skipped; returns '' when nothing
+ * resolves.
  */
 export function readReferencedDocs(cwd, ...texts) {
     const seen = new Set();

package/dist/task/write-guard.d.ts

@@ -9,37 +9,33 @@ export interface TreeChangeSummary {
 }
 /**
  * Parse `git status --porcelain` output into the change summary. A rename entry
- * contributes its source to `deleted` and its target to `added` (unstaged child
- * edits show the same reality as separate ` D old` + `?? new` lines, so both
- * shapes classify identically). Deterministic and pure so it is unit-tested
- * without a repo.
+ * contributes its source to `deleted` and its target to `added`. An unstaged child
+ * edit shows the same reality as separate ` D old` + `A  new` (or `?? new`) lines,
+ * and both shapes produce the identical summary — which is what lets the
+ * relocation allowance below read either one. Deterministic and pure, so it is
+ * unit-tested without a repo.
  */
 export declare function parseTreeChanges(porcelain: string): TreeChangeSummary;
 /**
  * Parse `git diff --name-status` output (tab-separated: `M\tpath`, `A\tpath`,
- * `D\tpath`, `R100\told\tnew`, `C75\told\tnew`) into the same change summary. Used
- * where the working tree is already clean and the last COMMIT's diff is the record
- * of the task's changes (the post-enforce re-verify fallback). A rename entry
- * contributes its source to `deleted` and its target to `added`, matching
- * parseTreeChanges so the relocation allowance below reads both shapes identically;
- * a copy's source still exists, so only its target counts (as added).
+ * `D\tpath`, `R100\told\tnew`, `C100\told\tnew`) into the same change summary.
+ * Used where the working tree is already clean and the last COMMIT's diff is the
+ * record of the task's changes. A rename entry contributes its source to `deleted`
+ * and its target to `added`, matching parseTreeChanges so the relocation allowance
+ * below reads both shapes identically; a copy's source still exists, so only its
+ * target counts (as added).
  */
 export declare function parseNameStatusChanges(nameStatus: string): TreeChangeSummary;
 /**
- * The deletions a fix pass may NOT make: every deleted tracked file whose name does
- * not reappear among the added files (a relocation keeps the file, under the same
- * name, somewhere in the tree). Anything returned here rejects the whole fix
- * attempt — run 11's `rm src/client/pages/admin.tsx` had no corresponding add and
- * destroyed a sibling task's verified deliverable.
+ * The deletions a fix pass may NOT make: every deleted tracked file whose BASENAME
+ * does not reappear among the added files. A relocation keeps the file, under the
+ * same name, somewhere in the tree; a RENAME does not, and is reported. Anything
+ * returned here makes final-gate-fix discard the whole attempt.
  *
- * REGENERABLE TEST-RUNNER OUTPUT IS EXEMPT (mx5 run 20). The guard is pure git: no
- * ecosystem, no exemption list, so three Playwright FAILURE screenshots that
- * TASK_0027's own `git add -A` had swept into a commit read as deliverables. Two
- * consecutive attempts were discarded whole over them — each taking a real
- * `src/client/api.test.tsx` repair with it, which attempt 3 then re-did and kept.
- * 6m14s of an 8m16s gate. And the pipeline committed those same three deletions at
- * the end anyway, in the stranded-fix commit (mx5 5d4147e), so the guard did not
- * even preserve what it rejected two attempts to protect.
+ * REGENERABLE TEST-RUNNER OUTPUT IS EXEMPT. Without an exemption the guard is pure
+ * git, so a failure screenshot a task's own `git add -A` swept into a commit reads
+ * as a deliverable and its removal discards a whole attempt — including the real
+ * repair that attempt also made.
  *
  * The exempt list is a strict SUBSET of the verdict-level artifact list and lives
  * in `regenerable-artifacts.ts`. `dist/`, `build/`, `.next/`, `.turbo/` and
@@ -52,23 +48,27 @@ export declare function findForbiddenDeletions(changes: TreeChangeSummary): stri
 export type IgnoredClass = 'build-output' | 'dep-dir' | 'task-dir' | 'vcs-meta' | 'actionable';
 /**
  * Classify one repo-relative ignored path. `outdirs` are build output directories
- * parsed from the project's own build commands. Only `actionable` may produce a
- * finding — everything else is reproducible from the repository by running the
+ * parsed from the project's own build commands (gate-deps' `parseBuildOutdirs`),
+ * matched by whole leading path SEGMENTS — outdir `artifacts` matches
+ * `artifacts/a.js` and not `artifactsx/a.js`. Only `actionable` may produce a
+ * finding; everything else is reproducible from the repository by running the
  * project's own tooling, which is exactly what makes it not a gate concern.
  */
 export declare function classifyIgnoredPath(rel: string, outdirs: string[]): IgnoredClass;
 /** The ignored paths a gate may rule on: everything not exempt by mechanism. */
 export declare function findActionableIgnoredWrites(paths: string[], outdirs: string[]): string[];
 /**
- * A fingerprint per ignored path (`mtimeMs:size`, or a marker for a directory),
- * taken before and after a write-capable child so a write is ATTRIBUTED to that
- * child rather than to the tree's pre-existing state. Ignored files are untracked,
- * so git cannot tell "changed" from "was always there" — only the snapshot can.
+ * A fingerprint per ignored path (`<mtimeMs>:<size>` for a file, `dir:<mtimeMs>`
+ * for a directory), taken before and after a write-capable child so a write is
+ * ATTRIBUTED to that child rather than to the tree's pre-existing state. Ignored
+ * files are untracked, so git cannot tell "changed" from "was always there" — only
+ * the snapshot can.
  */
 export type IgnoredSnapshot = Record<string, string>;
 /**
- * Paths whose fingerprint appeared or changed across the child's window. Pure, so
- * the attribution rule is unit-testable without a repo.
+ * Paths whose fingerprint appeared or changed across the child's window, sorted.
+ * A path that VANISHED is not reported — the channel exists to catch writes.
+ * Pure, so the attribution rule is unit-testable without a repo.
  */
 export declare function diffIgnoredSnapshots(before: IgnoredSnapshot, after: IgnoredSnapshot): string[];
 /**
@@ -80,19 +80,19 @@ export declare function ignoredWriteTrailLine(paths: string[]): string;
 /**
  * The durable debt reason for the same event. Path names only, same rule.
  *
- * The wording tracks what was actually PROVEN. `dependent === true` is the probe's
- * answer that the gate does not pass without these files; `undefined` is an
- * unanswered probe (the attempt never converged, or the probe could not run), which
- * is still worth carrying because the file is on disk and can green a LATER attempt.
- * A debt that overstates its evidence is the same defect this whole channel exists
- * to fix, one level up.
+ * The wording tracks what was actually PROVEN. Only `dependent === true` — the
+ * probe's answer that the gate does not pass without these files — earns the strong
+ * head. Anything else, `false` or an unanswered `undefined`, gets the weaker one:
+ * the write is still worth carrying because the file is on disk and can green a
+ * LATER attempt. A debt that overstates its evidence is the same defect this whole
+ * channel exists to fix, one level up.
  */
 export declare function ignoredWriteDebtReason(paths: string[], dependent?: boolean): string;
 /** The UNOBSERVED note that replaces such a PASS. Path names only, same rule. */
 export declare function ignoredWriteUnobservedNote(paths: string[]): string;
 /**
  * One-line summary for the gate debug log — the diff capture every write-capable
- * child gets so "what did this pass change" is answerable from artifacts (the
- * run-11 `rm` left no trace outside the bash stream).
+ * child gets, so "what did this pass change" is answerable from the artifacts
+ * rather than only from the child's bash stream.
  */
 export declare function formatTreeChanges(changes: TreeChangeSummary): string;

package/dist/task/write-guard.js

@@ -1,26 +1,24 @@
 /**
  * write-guard — deterministic tree-change accounting for WRITE-CAPABLE gate
- * children (mx5 run 11).
+ * children (`FINAL_FIX_TOOLS` and `LINT_FIX_TOOLS` are both `read,edit,bash`).
  *
- * The failure class: the final-gate autofix child (read,edit,bash) was added after
- * the run-8 guard generation and inherited NONE of the guards the other
- * write-capable passes carry — no diff capture, no frozen-path deny, no probe
- * scans, free `rm`. Run 11 it deleted `src/client/pages/admin.tsx` (TASK_0008's
- * verified deliverable) to satisfy a recorded debt claim, and the deletion was
- * invisible: nothing even logged what the pass changed.
+ * The failure class it exists for: a fix child with `bash` can `rm` a tracked
+ * file to satisfy a recorded claim, and nothing else in the gate would log what
+ * that pass changed.
  *
  * This module is the pure half of the guard stack: parse `git status --porcelain`
- * into a change summary (the diff-capture log line every write-capable child now
- * gets at the gate-deps seam), and classify tracked-file DELETIONS. A fix pass
- * exists to repair the assembled repository, not to shrink it: every tracked file
- * is a committed task's deliverable, so deleting one is rejected outright — with
- * one allowance, a RELOCATION (the same file name reappears as an added file
- * elsewhere, e.g. moving a test the runner was never meant to pick up out of its
- * glob — the legitimate fix shape from run 7). Pure text/path analysis; no git
- * execution, no stack assumptions.
+ * (or `git diff --name-status`) into a change summary — the diff-capture log line
+ * every write-capable child gets at the gate-deps seam — and classify tracked-file
+ * DELETIONS. A fix pass exists to repair the assembled repository, not to shrink
+ * it: every tracked file is a committed task's deliverable, so deleting one is
+ * rejected outright, with two allowances. A RELOCATION, where the same file NAME
+ * reappears among the added files (moving a test out of a runner's glob is a
+ * legitimate fix shape), and the regenerable test output `regenerable-artifacts.ts`
+ * exempts. Pure text and path analysis; no git execution, no stack assumptions.
  */
 import { isDeletionExemptArtifact } from './regenerable-artifacts.js';
-/** Porcelain v1 line: `XY <path>` or `XY <orig> -> <new>` (rename/copy). */
+/** Porcelain v1 line: `XY <path>`, or `XY <orig> -> <new>` for a staged rename or
+ *  copy. A path git had to quote arrives wrapped in `"` and is unwrapped here. */
 function splitEntry(raw) {
     if (raw.length < 4)
         return null;
@@ -41,10 +39,11 @@ function splitEntry(raw) {
 }
 /**
  * Parse `git status --porcelain` output into the change summary. A rename entry
- * contributes its source to `deleted` and its target to `added` (unstaged child
- * edits show the same reality as separate ` D old` + `?? new` lines, so both
- * shapes classify identically). Deterministic and pure so it is unit-tested
- * without a repo.
+ * contributes its source to `deleted` and its target to `added`. An unstaged child
+ * edit shows the same reality as separate ` D old` + `A  new` (or `?? new`) lines,
+ * and both shapes produce the identical summary — which is what lets the
+ * relocation allowance below read either one. Deterministic and pure, so it is
+ * unit-tested without a repo.
  */
 export function parseTreeChanges(porcelain) {
     const modified = new Set();
@@ -78,12 +77,12 @@ export function parseTreeChanges(porcelain) {
 }
 /**
  * Parse `git diff --name-status` output (tab-separated: `M\tpath`, `A\tpath`,
- * `D\tpath`, `R100\told\tnew`, `C75\told\tnew`) into the same change summary. Used
- * where the working tree is already clean and the last COMMIT's diff is the record
- * of the task's changes (the post-enforce re-verify fallback). A rename entry
- * contributes its source to `deleted` and its target to `added`, matching
- * parseTreeChanges so the relocation allowance below reads both shapes identically;
- * a copy's source still exists, so only its target counts (as added).
+ * `D\tpath`, `R100\told\tnew`, `C100\told\tnew`) into the same change summary.
+ * Used where the working tree is already clean and the last COMMIT's diff is the
+ * record of the task's changes. A rename entry contributes its source to `deleted`
+ * and its target to `added`, matching parseTreeChanges so the relocation allowance
+ * below reads both shapes identically; a copy's source still exists, so only its
+ * target counts (as added).
  */
 export function parseNameStatusChanges(nameStatus) {
     const modified = new Set();
@@ -121,20 +120,15 @@ const basename = (p) => {
     return i === -1 ? p : p.slice(i + 1);
 };
 /**
- * The deletions a fix pass may NOT make: every deleted tracked file whose name does
- * not reappear among the added files (a relocation keeps the file, under the same
- * name, somewhere in the tree). Anything returned here rejects the whole fix
- * attempt — run 11's `rm src/client/pages/admin.tsx` had no corresponding add and
- * destroyed a sibling task's verified deliverable.
+ * The deletions a fix pass may NOT make: every deleted tracked file whose BASENAME
+ * does not reappear among the added files. A relocation keeps the file, under the
+ * same name, somewhere in the tree; a RENAME does not, and is reported. Anything
+ * returned here makes final-gate-fix discard the whole attempt.
  *
- * REGENERABLE TEST-RUNNER OUTPUT IS EXEMPT (mx5 run 20). The guard is pure git: no
- * ecosystem, no exemption list, so three Playwright FAILURE screenshots that
- * TASK_0027's own `git add -A` had swept into a commit read as deliverables. Two
- * consecutive attempts were discarded whole over them — each taking a real
- * `src/client/api.test.tsx` repair with it, which attempt 3 then re-did and kept.
- * 6m14s of an 8m16s gate. And the pipeline committed those same three deletions at
- * the end anyway, in the stranded-fix commit (mx5 5d4147e), so the guard did not
- * even preserve what it rejected two attempts to protect.
+ * REGENERABLE TEST-RUNNER OUTPUT IS EXEMPT. Without an exemption the guard is pure
+ * git, so a failure screenshot a task's own `git add -A` swept into a commit reads
+ * as a deliverable and its removal discards a whole attempt — including the real
+ * repair that attempt also made.
  *
  * The exempt list is a strict SUBSET of the verdict-level artifact list and lives
  * in `regenerable-artifacts.ts`. `dist/`, `build/`, `.next/`, `.turbo/` and
@@ -176,8 +170,10 @@ const BUILD_DIR_NAMES = new Set([
 ]);
 /**
  * Classify one repo-relative ignored path. `outdirs` are build output directories
- * parsed from the project's own build commands. Only `actionable` may produce a
- * finding — everything else is reproducible from the repository by running the
+ * parsed from the project's own build commands (gate-deps' `parseBuildOutdirs`),
+ * matched by whole leading path SEGMENTS — outdir `artifacts` matches
+ * `artifacts/a.js` and not `artifactsx/a.js`. Only `actionable` may produce a
+ * finding; everything else is reproducible from the repository by running the
  * project's own tooling, which is exactly what makes it not a gate concern.
  */
 export function classifyIgnoredPath(rel, outdirs) {
@@ -210,8 +206,9 @@ export function findActionableIgnoredWrites(paths, outdirs) {
     return paths.filter(p => classifyIgnoredPath(p, outdirs) === 'actionable');
 }
 /**
- * Paths whose fingerprint appeared or changed across the child's window. Pure, so
- * the attribution rule is unit-testable without a repo.
+ * Paths whose fingerprint appeared or changed across the child's window, sorted.
+ * A path that VANISHED is not reported — the channel exists to catch writes.
+ * Pure, so the attribution rule is unit-testable without a repo.
  */
 export function diffIgnoredSnapshots(before, after) {
     const out = [];
@@ -233,12 +230,12 @@ export function ignoredWriteTrailLine(paths) {
 /**
  * The durable debt reason for the same event. Path names only, same rule.
  *
- * The wording tracks what was actually PROVEN. `dependent === true` is the probe's
- * answer that the gate does not pass without these files; `undefined` is an
- * unanswered probe (the attempt never converged, or the probe could not run), which
- * is still worth carrying because the file is on disk and can green a LATER attempt.
- * A debt that overstates its evidence is the same defect this whole channel exists
- * to fix, one level up.
+ * The wording tracks what was actually PROVEN. Only `dependent === true` — the
+ * probe's answer that the gate does not pass without these files — earns the strong
+ * head. Anything else, `false` or an unanswered `undefined`, gets the weaker one:
+ * the write is still worth carrying because the file is on disk and can green a
+ * LATER attempt. A debt that overstates its evidence is the same defect this whole
+ * channel exists to fix, one level up.
  */
 export function ignoredWriteDebtReason(paths, dependent) {
     const head = dependent === true ?
@@ -258,8 +255,8 @@ export function ignoredWriteUnobservedNote(paths) {
 }
 /**
  * One-line summary for the gate debug log — the diff capture every write-capable
- * child gets so "what did this pass change" is answerable from artifacts (the
- * run-11 `rm` left no trace outside the bash stream).
+ * child gets, so "what did this pass change" is answerable from the artifacts
+ * rather than only from the child's bash stream.
  */
 export function formatTreeChanges(changes) {
     if (changes.modified.length === 0

package/dist/task/yolo.d.ts

@@ -2,10 +2,11 @@ import type { AutoAnswer } from './parsers.js';
 import type { ResolutionChoice } from './verify-resolution.js';
 import type { FinalGateChoice } from './final-gate-fix.js';
 /**
- * Visible provenance marker on EVERY artifact an auto-pick writes (gate trails,
- * task-file Q&A, the debt ledger's reason text). A later audit reading only the
- * artifacts must never mistake an auto-pick for a human decision — that is the
- * same confusion the accept-debt origins were introduced to prevent.
+ * Visible provenance marker on the artifacts an auto-pick writes: gate trail lines
+ * and the task file's Q&A record (qa-transcript.ts `QA_PROVENANCE`). A later audit
+ * reading only the artifacts must never mistake an auto-pick for a human decision.
+ * The debt ledger does not use this stamp — it carries the `'yolo-accepted'` ORIGIN
+ * instead, which is stronger: a typed field rather than text.
  */
 export declare const YOLO_STAMP = "(YOLO)";
 /** Is unattended auto-pick on for this run? The ONLY config read in this module. */
@@ -25,16 +26,17 @@ export type YoloPick = {
     note: string;
 } | null;
 /**
- * The clarify/grill policy: take the RECOMMENDED option — which is positional,
- * index 0 of the card list (question-box.ts tints it green), i.e. `suggested`,
- * falling back to the B-side `alt` when a fork offers only that.
+ * The clarify/grill policy: take the RECOMMENDED option — `suggested`, falling
+ * back to the B-side `alt` when a fork offers only that. Recommended is positional
+ * for a human too: bridge.ts marks card index 0, and question-box.ts tints the
+ * marked card green.
  *
  * `unsafe` is the step-aside channel: a caller that KNOWS the recommendation must
- * not be auto-accepted passes why, and the question is skipped instead. Its one
- * producer today is the anti-synthesis demotion — an answer proven to name a
- * hallucinated API identifier. Auto-accepting that would re-promote exactly the
- * invention the demotion was built to stop (it reached requirements AND the VERIFY
- * block in mx5 run 13), so a machine may never take it; a human still can.
+ * not be auto-accepted passes why, and the question is skipped instead. The only
+ * thing that supplies it is `yoloPickAutoAnswer` below, on the anti-synthesis
+ * demotion — an answer proven to name an unverified API identifier. Auto-accepting
+ * that would re-promote exactly the invention the demotion exists to stop, so a
+ * machine may never take it; a human still can.
  */
 export declare function yoloPickAnswer(enabled: boolean, opts: {
     suggested?: string;
@@ -42,33 +44,35 @@ export declare function yoloPickAnswer(enabled: boolean, opts: {
     unsafe?: string;
 }): YoloPick;
 /**
- * The same policy expressed over an {@link AutoAnswer}, for the grill site. Only
- * the ANTI-SYNTHESIS unknown is unsafe: the other two producers (an integration
- * unknown research could not ground, a child that threw) carry an ordinary
- * best-effort recommendation, which is precisely what a human would be shown as
- * the green card. The variants are told apart by the union's `reason` tag — never
- * by pattern-matching the answer text.
+ * The same policy expressed over an {@link AutoAnswer}, for the grill site. Of the
+ * four `reason` tags an unknown can carry — `api-synthesis`, `integration`,
+ * `threw`, `model-unknown` — only ANTI-SYNTHESIS is unsafe. The other three carry
+ * an ordinary best-effort recommendation, which is precisely what a human would be
+ * shown as the green card. The variants are told apart by that tag, never by
+ * pattern-matching the answer text.
  */
 export declare function yoloPickAutoAnswer(enabled: boolean, auto: AutoAnswer): YoloPick;
 /**
  * The verify-FAIL picker policy: ACCEPT (and write a debt), never AUTOFIX.
  *
- * Not a preference — a bound. Every branch that REACHES this picker has already
- * spent its unattended budget: the loop auto-runs AUTOFIX while the research
- * recommends it, up to MAX_AUTO_AUTOFIX consecutive failures, and only then hands
- * over. Answering AUTOFIX here would restart that budget from a site whose whole
- * purpose is that the budget ran out. So YOLO takes the terminal option and
- * records the defect ('yolo-accepted' — an origin a human never produces).
+ * Not a preference — a bound. task-gates.ts consults this only after its own
+ * unattended paths are exhausted: `autoFixNow` has run AUTOFIX up to
+ * MAX_AUTO_AUTOFIX times while the research recommended it, and the YOLO rescue has
+ * spent its one attempt on an ACCEPT recommendation with an untouched budget.
+ * Answering AUTOFIX here would restart that budget from the very site that proves
+ * it ran out. So YOLO takes the terminal option and records the defect under the
+ * `'yolo-accepted'` debt origin, which a human decision never produces.
  */
 export declare function yoloVerifyResolution(enabled: boolean): ResolutionChoice | null;
 /**
- * The final-integration-gate policy: keep autofixing WHILE the picker still
- * offers that card (the loop withdraws it after MAX_FINAL_GATE_AUTOFIX attempts),
- * then leave the run FAILED.
+ * The final-integration-gate policy: keep autofixing WHILE the picker still offers
+ * that card — run-final-gate.ts withdraws it from `options` after
+ * MAX_FINAL_GATE_AUTOFIX attempts, and passes that as `canAutofix` — then leave the
+ * run FAILED.
  *
  * 'leave', not 'accept': an unattended run that cannot fix the whole-repo gate has
- * not produced a working project, and the honest terminal state is a failed run a
- * resume can re-enter — mx5 run 13 ended "FAIL accepted by user" on an app that
- * 404'd at `/`, and that acceptance is what made the failure look like a success.
+ * not produced a working project. The honest terminal state is a failed run a
+ * resume can re-enter. Accepting instead would make the failure read as a success
+ * in every artifact that survives the run.
  */
 export declare function yoloFinalGateChoice(enabled: boolean, canAutofix: boolean): FinalGateChoice | null;