@mjasnikovs/pi-task 0.40.50 → 0.42.0

package/dist/task/gate-deps.js

@@ -22,13 +22,18 @@
 import { existsSync, readFileSync } from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
-import { tasksDir, readTaskFile, appendGateRecord } from './task-io.js';
+import { readTaskFile, appendGateRecord, readSection, setTaskSection } from './task-io.js';
+import { makeGit } from '../shared/git-runner.js';
+import { worktreeTreeHash } from './tree-hash.js';
+import { captureHealthBaseline, formatHealthBaseline, lazyHealthBaseline, parseHealthBaseline, HEALTH_BASELINE_SECTION } from './health-baseline.js';
 import { gitCommitAll, gitDropLastCommit, git } from './auto-commit.js';
 import { runGuidelineEnforcement } from './enforce-guidelines.js';
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
 import { readEnvNotes, appendEnvNotes } from './env-notes.js';
+import { currentRunContext } from './run-context.js';
+import { runGateEvidence, evidenceVerifyFindings } from './gate-evidence.js';
 import { readContracts } from './contracts.js';
-import { recordDebt } from './accept-debt.js';
+import { closeHealthDebts, recordDebt } from './accept-debt.js';
 import { recordRepairCandidate } from './root-cause-repair.js';
 import { runRepoHealthCheck } from './repo-health-check.js';
 import { runFinalIntegrationGate, discoverGateCommandLabels, discoverGateCommandBodies } from './final-gate.js';
@@ -45,12 +50,17 @@ import { runBoundedLintFix } from './lint-fix.js';
 import { findForeignPaths, foreignPathVerifyFindings, repairForeignPaths } from './foreign-path.js';
 import { findScriptEscapesInManifest, scriptEscapeVerifyFindings } from './script-escape.js';
 import { assessRunnerGlobs, runnerGlobVerifyFindings } from './runner-globs.js';
+import { compileSuppressionPatterns, findSuppressionWidening, suppressionPatternsFor } from './suppression-probe.js';
+import { detectEcosystems } from '../workers/docs-ecosystems.js';
+import { qaKindsFromRecord } from './qa-transcript.js';
+import { extractSection } from './task-parsers.js';
 import { captureGitState, reconcileGitState } from './git-state-guard.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { getConfig } from '../config/config.js';
 import { groupChildArgs } from '../config/group-args.js';
 import { contextWindowForGroup } from './context-usage.js';
 import { makeDebugAppender } from './debug-log.js';
+import { runLogPath } from './state-dir.js';
 import { startAutoLoader } from './widget.js';
 import { ChildStatus } from './child-status.js';
 import { makeGateChild } from './gate-child.js';
@@ -494,6 +504,50 @@ export async function readSpecForVerification(cwd, taskId) {
         return null;
     }
 }
+/**
+ * The task's rendered Q&A, which is what a constraint's `[from: Q<n>]` tag
+ * resolves against (see qa-transcript's `qaKindsFromRecord`). Null when the task
+ * asked nothing, or the file cannot be read — both mean every tagged constraint
+ * reads as `derived`, and `constraint-policy.ts` says what that is worth.
+ */
+export async function readQaRecordForVerification(cwd, taskId) {
+    try {
+        const { body } = await readTaskFile(cwd, taskId);
+        return extractSection(body, 'grill Q&A');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The health baseline the verify gate's differential needs: the one stored on the
+ * task file, or — for a task file that has none — one established lazily from a
+ * DETACHED WORKTREE at HEAD and written back, so the next resolution round does
+ * not pay for it again.
+ *
+ * Everything here is best-effort. A baseline that cannot be established is null,
+ * and `classifyHealthDelta` already states what an absent baseline means; failing
+ * the gate because the differential could not run would be the harness blaming
+ * the work for its own gap.
+ */
+export async function healthBaselineFor(cwd, taskId, signal) {
+    try {
+        const stored = parseHealthBaseline(await readSection(cwd, taskId, HEALTH_BASELINE_SECTION));
+        if (stored)
+            return stored;
+        const fresh = await lazyHealthBaseline({
+            git: makeGit(cwd, signal),
+            runHealthIn: dir => runRepoHealthCheck(dir, { signal })
+        });
+        if (fresh) {
+            await setTaskSection(cwd, taskId, HEALTH_BASELINE_SECTION, formatHealthBaseline(fresh)).catch(() => { });
+        }
+        return fresh;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Bind the deterministic verify probes — THE one place the collectors above meet
  * the probe table in verify-work.ts. One entry per `BoundProbeKey`; the table row
@@ -507,8 +561,30 @@ export async function readSpecForVerification(cwd, taskId) {
  * verify debug appender for the one probe that repairs as well as reports.
  */
 export function buildVerifyProbes(params) {
-    const { cwd, signal, taskId, spec, log } = params;
+    const { cwd, signal, taskId, spec, qaRecord, log, onCommand, run } = params;
+    const kinds = qaRecord ? qaKindsFromRecord(qaRecord) : [];
     return {
+        // The project's own check and build commands, run ONCE per tree by the
+        // parent (gate-evidence.ts) and handed to the child as a result to read.
+        // Cached on the RUN's context, so every gate child of this session shares
+        // one answer and a lint-fix that moves the tree costs exactly one re-run.
+        // Outside a run bracket (a direct runSingleTask, a test) there is no run
+        // to share and each ask gets a fresh context, so the cache spans one call.
+        evidence: () => {
+            const rc = currentRunContext(cwd);
+            return rc
+                .gateEvidenceFor((commands, tree) => runGateEvidence({
+                cwd,
+                runId: rc.runId,
+                commands,
+                treeHash: tree,
+                timeoutMs: getConfig().requestTimeoutMs,
+                ...(signal === undefined ? {} : { signal }),
+                ...(onCommand === undefined ? {} : { onCommand }),
+                ...(run === undefined ? {} : { run })
+            }))
+                .then(evidenceVerifyFindings);
+        },
         // Deterministic self-verification probe: test files the task itself
         // authored/changed become prompt-level findings mandating the child
         // to drive the real artifact before trusting their green result.
@@ -518,7 +594,7 @@ export function buildVerifyProbes(params) {
         // under the no-waiver rule — the child otherwise rarely runs `git
         // diff` and cannot even see the violation.
         prohibition: () => {
-            const banned = spec ? extractProhibitions(spec) : [];
+            const banned = spec ? extractProhibitions(spec, n => kinds[n - 1] ?? null) : [];
             if (banned.length === 0)
                 return Promise.resolve([]);
             return collectChangedFiles(cwd, signal).then(files => findProhibitionViolations(banned, files));
@@ -555,9 +631,65 @@ export function buildVerifyProbes(params) {
         // production wiring — importing the leaf modules the shipped entry
         // composes and assembling their own copy — become rule-3f findings,
         // so the child drives the REAL assembly and not the copy.
-        testAssembly: () => collectChangedFiles(cwd, signal).then(changed => collectTestAssemblyFindings(cwd, changed, signal))
+        testAssembly: () => collectChangedFiles(cwd, signal).then(changed => collectTestAssemblyFindings(cwd, changed, signal)),
+        // Deterministic suppression-widening probe: checker suppressions this
+        // task NET added. Injected under rule 4i — the child cannot find these
+        // by running the checks, because the suppressions are why they pass.
+        suppressionWidening: () => collectSuppressionHits(cwd, signal)
     };
 }
+/**
+ * The task's net-new suppressions: the files its work touched (the same tree
+ * shape the write-guard reads), diffed against the checkpoint HEAD, counted per
+ * pattern.
+ *
+ * The pattern set follows the repo's detected ecosystems, so a Go project is not
+ * scanned for `@ts-expect-error` and a TypeScript one is not scanned for
+ * `//nolint`; `suppressionPatterns` in the config adds project-specific rows.
+ * Failures degrade to no findings — a sharpener, never a blocker.
+ */
+export async function collectSuppressionHits(cwd, signal) {
+    const changes = await collectTreeChanges(cwd, signal);
+    const files = [...changes.modified, ...changes.added];
+    if (files.length === 0)
+        return [];
+    const patterns = suppressionPatternsFor(detectEcosystems(cwd), compileSuppressionPatterns(getConfig().suppressionPatterns));
+    const diff = await git(cwd, ['diff', ...DIFF_PREFIX_ARGS, 'HEAD', '--', ...files], signal);
+    const lines = diff.exitCode === 0 ? parseDiffLines(diff.stdout) : [];
+    const untracked = await Promise.all(changes.added.map(async (rel) => {
+        try {
+            const text = await fsp.readFile(path.join(cwd, rel), 'utf8');
+            return text.split('\n').map(t => ({ path: rel, text: t, added: true }));
+        }
+        catch {
+            return [];
+        }
+    }));
+    return findSuppressionWidening([...lines, ...untracked.flat()], patterns);
+}
+/**
+ * A unified diff's content lines, tagged with their side and their file. The `+++`
+ * header names the file and the `---`/`+++` headers themselves are excluded, which
+ * is the one thing a naive `startsWith('+')` scan gets wrong — it counts every
+ * changed file's own header as an added line.
+ */
+export function parseDiffLines(diff) {
+    const out = [];
+    let file = '';
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('+++ ')) {
+            file = line.slice(4).replace(/^b\//, '').trim();
+            continue;
+        }
+        if (line.startsWith('--- ') || line.startsWith('@@'))
+            continue;
+        if (line.startsWith('+'))
+            out.push({ path: file, text: line.slice(1), added: true });
+        else if (line.startsWith('-'))
+            out.push({ path: file, text: line.slice(1), added: false });
+    }
+    return out;
+}
 /**
  * Build the gate deps for one command run. `runTask` is the orchestrator's
  * implementation re-runner, injected by the caller. The returned object also drives
@@ -581,13 +713,37 @@ export function buildGateDeps(params) {
     // mutationCheck dep to discard a verdict computed on a mutated tree.
     let lastGuardReconcile = null;
     // Restore tracked files to HEAD and drop files a pass created. The `.pi-tasks`
-    // trail and log writes made during the pass survive both: the checkout excludes
-    // that directory by pathspec and the clean excludes it with `-e`. Shared by the
+    // trail survives both: the checkout excludes that directory by pathspec and the
+    // clean excludes it with `-e`. Debug logs are outside the tree. Shared by the
     // enforce pre-commit gate (discardEdits) and the final-gate autofix guards.
     const discardTreeEdits = async (cwd2) => {
         await git(cwd2, ['checkout', '--', '.', EXCLUDE_TASKS_DIR], signal);
         await git(cwd2, ['clean', '-fd', '-e', '.pi-tasks'], signal);
     };
+    // The project's own statics, under a live loader naming the running command.
+    // Each run is as long as that command, and a gate step that long with no widget
+    // is indistinguishable from a hang. Shared by the enforce pre-commit gate (a
+    // baseline before the edit pass, a differential after it) and by the
+    // pre-task baseline capture.
+    const runHealthUnderLoader = (healthCtx, cwd2, label) => {
+        const startedAt = Date.now();
+        let running;
+        const stop = startAutoLoader(healthCtx, () => ({
+            title: label,
+            kind: 'enforce',
+            step: 'repo health',
+            stepNum: 1,
+            stepTotal: 1,
+            startedAt,
+            lastLine: running ? `repo health · ${running}` : 'repo health'
+        }));
+        return runRepoHealthCheck(cwd2, {
+            signal,
+            onCommand: c => {
+                running = c;
+            }
+        }).finally(stop);
+    };
     // Adapter onto the shared gate-child runner (gate-child.ts). What survives
     // here is WIRING — which context, which log file, which config knobs, and
     // the shared live status; the ritual and the per-kind policy are the
@@ -597,7 +753,7 @@ export function buildGateDeps(params) {
         cwd: cwd2,
         taskTitle,
         kind,
-        logPath: path.join(tasksDir(cwd2), logFile),
+        logPath: runLogPath(cwd2, logFile),
         ...(opts.loader === undefined ? {} : { loader: opts.loader }),
         commandTimeoutMs: getConfig().requestTimeoutMs,
         streamInactivityMs: getConfig().streamInactivityMs,
@@ -630,6 +786,7 @@ export function buildGateDeps(params) {
         // origin, and the final integration gate re-checks each one at run end.
         recordDebt,
         recordRepairCandidate: (cwd2, candidate) => recordRepairCandidate(cwd2, candidate),
+        closeHealthDebts,
         // file → introducing task, the provenance half of the discriminator.
         introducedBy: (cwd2, rel) => Promise.resolve(taskThatIntroduced(cwd2, rel)),
         // Tracked paths, used only to resolve a bare file name a FAIL text names
@@ -733,6 +890,10 @@ export function buildGateDeps(params) {
             // file. A task that never reached compose has no spec section —
             // runWorkVerification treats a null spec as a no-op pass.
             const spec = await readSpecForVerification(cwd2, taskId);
+            const qaRecord = await readQaRecordForVerification(cwd2, taskId);
+            // One id for the whole gate: read and append must agree on which run
+            // these facts belong to.
+            const { runId } = currentRunContext(cwd2);
             // DEAD AIR (the reason this loader exists). The gate's DETERMINISTIC
             // stage — repo health plus the nine PROBE_ADAPTERS rows — runs before
             // the verify child, and the child's own loader only starts once the
@@ -788,6 +949,10 @@ export function buildGateDeps(params) {
                         stageLine = `repo health · ${c}`;
                     }
                 }),
+                // What those checks said before the task started, so a red one
+                // is attributed rather than absolutely failed. Read only when
+                // the check above comes back red.
+                healthBaseline: () => healthBaselineFor(cwd2, taskId, signal),
                 // The deterministic probes, bound in one place (buildVerifyProbes
                 // above); the PROBE_ADAPTERS table in verify-work.ts runs them.
                 probes: buildVerifyProbes({
@@ -795,8 +960,15 @@ export function buildGateDeps(params) {
                     signal,
                     taskId,
                     spec,
-                    log: makeDebugAppender(path.join(tasksDir(cwd2), 'verify-debug.log'))
+                    qaRecord,
+                    log: makeDebugAppender(runLogPath(cwd2, 'verify-debug.log')),
+                    // The evidence row runs the project's own checks, so it is
+                    // the longest step of the stage the loader above exists for.
+                    onCommand: c => {
+                        stageLine = `project checks · ${c}`;
+                    }
                 }),
+                ...(qaRecord === null ? {} : { qaRecord }),
                 // Git-state guard result of the most recent child run: a verdict
                 // computed on a tree the child itself mutated is discarded — but ONLY
                 // when the mutation touched graded state (verdictTainted). A child
@@ -812,11 +984,13 @@ export function buildGateDeps(params) {
                 // the re-archaeology; its own ENV-NOTE lines are stored for the
                 // next one, stamped with this task's id as their origin so a
                 // later child sees a cited fact is second-hand and must
-                // re-validate before excusing a failure. Facts only — verdict
-                // rules unaffected.
+                // re-validate before excusing a failure, and with the RUN's id so
+                // the facts measured against this tree lead the block. Facts
+                // only — verdict rules unaffected.
                 envNotes: {
                     read: () => readEnvNotes(cwd2),
-                    append: notes => appendEnvNotes(cwd2, notes, taskId)
+                    append: notes => appendEnvNotes(cwd2, notes, taskId, runId),
+                    runId
                 },
                 // Per-run cross-slice contract registry under `.pi-tasks/`: the
                 // verbatim interface facts the design pins that multiple slices
@@ -854,31 +1028,17 @@ export function buildGateDeps(params) {
                 introducedBy: rel => Promise.resolve(taskThatIntroduced(cwd2, rel))
             });
         },
-        // Deterministic static check + tree helpers for the enforce pre-commit gate.
-        // task-gates.ts calls it up to twice per task in `edit` mode — a baseline
-        // before the edit pass, and a differential check after it when edits were
-        // made. Each run is as long as the project's own lint, so it gets the same
-        // treatment as the verify-side run: async, under a live loader naming the
-        // command.
-        repoHealth: (healthCtx, cwd2, label) => {
-            const startedAt = Date.now();
-            let running;
-            const stop = startAutoLoader(healthCtx, () => ({
-                title: label,
-                kind: 'enforce',
-                step: 'repo health',
-                stepNum: 1,
-                stepTotal: 1,
-                startedAt,
-                lastLine: running ? `repo health · ${running}` : 'repo health'
-            }));
-            return runRepoHealthCheck(cwd2, {
-                signal,
-                onCommand: c => {
-                    running = c;
-                }
-            }).finally(stop);
-        },
+        // task-gates.ts calls this up to twice per task in `edit` mode — a baseline
+        // before the enforce edit pass, and a differential check after it.
+        repoHealth: runHealthUnderLoader,
+        captureHealthBaseline: (healthCtx, cwd2, label) => captureHealthBaseline({
+            runHealth: () => runHealthUnderLoader(healthCtx, cwd2, label),
+            treeHash: () => worktreeTreeHash(makeGit(cwd2, signal)),
+            // A project's `lint` script commonly runs `--fix`, so the baseline
+            // can leave the tree edited. Undone here, or the task starts on a
+            // tree the baseline authored.
+            discardEdits: () => discardTreeEdits(cwd2)
+        }).catch(() => null),
         dirty: async (cwd2) => {
             const r = await git(cwd2, ['status', '--porcelain', '--', '.', EXCLUDE_TASKS_DIR], signal);
             return r.exitCode === 0 && r.stdout.trim().length > 0;
@@ -919,17 +1079,19 @@ export function buildGateDeps(params) {
             // proven to depend on it.
             ignoredSnapshot: () => collectIgnoredSnapshot(cwd2, signal),
             ...(ignoredKnown && ignoredKnown.length > 0 ? { ignoredKnown } : {}),
-            gateWithoutIgnored: paths => gatePassesWithoutIgnored(cwd2, paths, c => runFinalIntegrationGate(c, { signal }), makeDebugAppender(path.join(tasksDir(cwd2), 'final-gate-debug.log'))),
-            log: makeDebugAppender(path.join(tasksDir(cwd2), 'final-gate-debug.log'))
+            gateWithoutIgnored: paths => gatePassesWithoutIgnored(cwd2, paths, c => runFinalIntegrationGate(c, { signal }), makeDebugAppender(runLogPath(cwd2, 'final-gate-debug.log'))),
+            log: makeDebugAppender(runLogPath(cwd2, 'final-gate-debug.log'))
         }),
         recommend: async (recCtx, cwd2, taskTitle, taskId, failReason) => {
             // Read the same composed spec the verify gate judged against, so the
             // recommendation reasons over the real contract (degrade to the bare title).
             const spec = (await readSpecForVerification(cwd2, taskId)) ?? taskTitle;
+            const qaRecord = await readQaRecordForVerification(cwd2, taskId);
             return researchResolution({
                 cwd: cwd2,
                 signal,
                 spec,
+                ...(qaRecord === null ? {} : { qaRecord }),
                 failReason,
                 runChild: gateChild(recCtx, cwd2, taskTitle, 'recommend', 'verify-debug.log')
             });

package/dist/task/gate-evidence.d.ts

@@ -0,0 +1,51 @@
+import { type CommandRunner } from './command-run.js';
+import { type VerifiedCommand } from './run-context.js';
+/** One command the parent ran for the children, and where its full output went. */
+export interface EvidenceCommand {
+    cmd: string;
+    cwd: string;
+    /** Its real exit code, or {@link NOT_RUN} when `gap` says nothing was observed. */
+    exitCode: number;
+    /** Absolute path — outside the worktree — of the file holding the full output. */
+    outputPath: string;
+    /** The tree it was measured against; null when git could not say (see treeHash). */
+    treeHash: string | null;
+    /** The env-gap ladder's reason nothing was observed. Absent ⇒ the command ran. */
+    gap?: string;
+}
+/** What one gate session hands its children in place of a command to run. */
+export interface GateEvidence {
+    commands: EvidenceCommand[];
+}
+export interface EvidenceRunDeps {
+    cwd: string;
+    /** Whose state dir the output files land in. */
+    runId: string;
+    /** Already filtered to the classes that terminate (see RunContext). */
+    commands: readonly VerifiedCommand[];
+    treeHash: string | null;
+    /** Per-command ceiling. The same one a gate child's own bash tool gets: a
+     *  command pre-run here must not be bounded more tightly than the same command
+     *  run by the child, or the child would see a timeout the child cannot reproduce. */
+    timeoutMs: number;
+    signal?: AbortSignal;
+    /** Called with each command as it STARTS. These are the project's own whole-repo
+     *  checks and they run before the child exists, so without a live line naming
+     *  the running one the gate's longest stage is also its quietest. */
+    onCommand?: (cmd: string) => void;
+    /** The spawner. Injected so a session's command count is assertable. */
+    run?: CommandRunner;
+}
+/** Where a run's evidence output lives. */
+export declare function evidenceDir(cwd: string, runId: string): string;
+/**
+ * Run each command and write its output to the run's state dir.
+ *
+ * Sequential: these are the project's own whole-repo checks, and running a
+ * typecheck, a build and a test suite at once on the machine the user is working on
+ * would make each of them slower and their results less reproducible.
+ */
+export declare function runGateEvidence(deps: EvidenceRunDeps): Promise<GateEvidence>;
+/** One prompt line per command: what ran, how it ended, and the file the child
+ *  reads instead of running it again. */
+export declare function evidenceVerifyFindings(evidence: GateEvidence): string[];

package/dist/task/gate-evidence.js

@@ -0,0 +1,90 @@
+/**
+ * gate-evidence — the project's own check and build commands, run ONCE per tree by
+ * the parent, so a gate child reads a result instead of producing one.
+ *
+ * The failure this closes: the verify child is told to run the project's own
+ * commands; so is the lint-fix child after it; so is the verify child after that.
+ * One real run spent 2755 s inside gate children re-running the same suites 49
+ * times, and a single gate session ran one of them seven times over a tree that
+ * changed twice.
+ *
+ * What makes pre-supplying safe is the CLASS column the run context already holds:
+ * `check` and `build` terminate on their own, `serve` does not, and a dev server
+ * launched here would hang the gate before the child ever started. So `serve` is
+ * never run — the filter lives in `RunContext.gateEvidenceFor`, which owns the
+ * verdicts.
+ *
+ * Nothing observed is nothing claimed. A command that could not run on this machine
+ * is recorded SKIPPED with the env-gap ladder's own reason (command-run.ts), never
+ * as a failure: the ladder is the single statement of what an ending MEANS, and a
+ * second statement of it here would drift from the gate's.
+ *
+ * The output files live in the run's state dir, OUTSIDE the worktree. The children
+ * that read them run under the git-state guard, which restores the tree around
+ * them; evidence written into the tree would be reverted between being produced and
+ * being read.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { classifyCommandRun, leadingBin, spawnCommand } from './command-run.js';
+import { resolveRunner, runnerEnv } from './runner-resolve.js';
+import { NOT_RUN } from './run-context.js';
+import { stateDir } from './state-dir.js';
+/** Where a run's evidence output lives. */
+export function evidenceDir(cwd, runId) {
+    return path.join(stateDir(cwd, runId), 'evidence');
+}
+/** The output file, readable on its own once the session that produced it is gone. */
+function evidenceFile(cmd, ending, stdout, stderr) {
+    return [`$ ${cmd}`, ending, '', stdout, stderr].join('\n');
+}
+/**
+ * Run each command and write its output to the run's state dir.
+ *
+ * Sequential: these are the project's own whole-repo checks, and running a
+ * typecheck, a build and a test suite at once on the machine the user is working on
+ * would make each of them slower and their results less reproducible.
+ */
+export async function runGateEvidence(deps) {
+    if (deps.commands.length === 0)
+        return { commands: [] };
+    const dir = evidenceDir(deps.cwd, deps.runId);
+    await fsp.mkdir(dir, { recursive: true });
+    const run = deps.run ?? spawnCommand;
+    const commands = [];
+    for (const [i, v] of deps.commands.entries()) {
+        const outputPath = path.join(dir, `${i + 1}.out`);
+        deps.onCommand?.(v.cmd);
+        // A verified command is a SHELL line, not an argv (`bun run lint`, `make -j2
+        // build`), so it runs through `sh -c`; its leading word still resolves through
+        // runner-resolve, or a login-shell-stripped PATH makes every command a gap.
+        const bin = leadingBin(v.cmd);
+        const runner = bin === null ? null : resolveRunner(bin);
+        const r = await run({
+            cwd: v.cwd,
+            bin: 'sh',
+            args: ['-c', v.cmd],
+            timeoutMs: deps.timeoutMs,
+            env: runner ? runnerEnv(runner) : { ...process.env },
+            ...(deps.signal === undefined ? {} : { signal: deps.signal })
+        });
+        const verdict = classifyCommandRun(r);
+        const gap = verdict.outcome === 'gap' ? verdict.detail : undefined;
+        await fsp.writeFile(outputPath, evidenceFile(v.cmd, gap === undefined ? `exit ${r.status}` : `skipped — ${gap}`, r.stdout, r.stderr), 'utf8');
+        commands.push({
+            cmd: v.cmd,
+            cwd: v.cwd,
+            exitCode: gap === undefined ? (r.status ?? NOT_RUN) : NOT_RUN,
+            outputPath,
+            treeHash: deps.treeHash,
+            ...(gap === undefined ? {} : { gap })
+        });
+    }
+    return { commands };
+}
+/** One prompt line per command: what ran, how it ended, and the file the child
+ *  reads instead of running it again. */
+export function evidenceVerifyFindings(evidence) {
+    return evidence.commands.map(c => `\`${c.cmd}\` — ${c.gap === undefined ? `exit ${c.exitCode}` : `SKIPPED (${c.gap})`}`
+        + ` — full output: ${c.outputPath}`);
+}

package/dist/task/gate-resolution.d.ts

@@ -0,0 +1,119 @@
+/**
+ * gate-resolution — what to DO about a verify FAIL, as one ordered decision table.
+ *
+ * WHY A TABLE. The gate loop used to answer this with three overlapping booleans
+ * over five predicates, and then RE-DERIVE the same branches afterwards to name
+ * them in the trail. In AUTO_0002 that shape cost: a correct judge ACCEPT
+ * overridden by a "rescue" attempt (41 minutes, 16 suppressions shipped, no
+ * debt), a spec contradiction that looped three rounds with no exit, and five
+ * defects that left the gate with no ledger entry at all. One row per decision in
+ * precedence order is the whole policy, and the row that fired NAMES itself — so
+ * the durable trail can no longer disagree with the branch that produced it.
+ *
+ * THERE IS NO RESCUE ACTION. A judge ACCEPT comes from a pass that read the real
+ * workspace and ran the real commands; spending an implementation re-run "just in
+ * case" overrides that verdict with nothing.
+ *
+ * Same ordered-data shape as `FAILURE_RULES` (src/workers/worker-failure.ts):
+ * first match wins, and row order IS the precedence.
+ */
+import type { VerifyFailClass } from './verify-work.js';
+import type { ResolutionRecommendation } from './verify-resolution.js';
+import type { DebtOrigin } from './accept-debt.js';
+/**
+ * A criterion the task CANNOT meet without an edit its own spec forbids.
+ *
+ * Both gates that can prove one mint this shape: the bounded lint fix, whose
+ * static findings trace to a frozen path, and the resolution judge, through its
+ * `VERIFY-RESOLUTION: BLOCKED-BY-FROZEN` marker. It is the one input no re-run
+ * and no human ACCEPT-vs-AUTOFIX choice can move — the fix the check demands is
+ * the edit the spec denies — so it outranks every other row below.
+ */
+export interface SpecContradiction {
+    /** The acceptance criterion (or static check) that cannot be satisfied. May be
+     *  empty when the judge named only the path. */
+    criterion: string;
+    /** The spec-frozen path whose edit is the only way to satisfy it. */
+    frozenPath: string;
+}
+/** Everything the decision depends on. Nothing else may enter the table. */
+export interface ResolutionInput {
+    failClass: VerifyFailClass;
+    /** What the resolution judge recommended, or the default when it was not consulted. */
+    recommend: ResolutionRecommendation;
+    /** Rule 5c: a spec-required check could not RUN because its tooling is absent. */
+    unobserved: boolean;
+    contradiction: SpecContradiction | null;
+    /** Unattended AUTOFIX attempts already spent on this task. */
+    attempts: number;
+    /** Nobody can be asked (YOLO mode) — the picker is unreachable. */
+    unattended: boolean;
+}
+export type ResolutionRuleId = 'spec-contradiction' | 'judge-accept' | 'no-autofix-budget' | 'budget-spent' | 'autofix';
+/**
+ * What the gate loop does next. `debtOrigin` is non-null exactly on `accept`,
+ * which is the loop's terminal exit: a defect may not leave the gate without a
+ * ledger entry, and the type — not a runtime check — is what enforces it. `ask`
+ * and `autofix` carry null because the human's answer (or the next round) names
+ * the origin instead.
+ */
+export type Disposition = {
+    rule: ResolutionRuleId;
+    action: 'autofix';
+    debtOrigin: null;
+    reason: string;
+} | {
+    rule: ResolutionRuleId;
+    action: 'accept';
+    debtOrigin: DebtOrigin;
+    reason: string;
+} | {
+    rule: ResolutionRuleId;
+    action: 'ask';
+    debtOrigin: null;
+    reason: string;
+};
+/**
+ * How many UNATTENDED implementation re-runs each FAIL class is worth.
+ *
+ * Zero is a statement, not a disabled feature: an absent tool is not installed by
+ * re-running the work that needed it, and a verification pass that could not run
+ * is not repaired by changing the code it failed to judge. Spending three turns
+ * on either is how a run burns an hour to arrive where round one already was.
+ */
+export declare const AUTOFIX_BUDGET: Record<VerifyFailClass, number>;
+/**
+ * How many times the /task-auto loop will START one plan entry before abandoning it.
+ *
+ * Derived, not chosen: one run to reach the gate at all, plus the re-runs the most
+ * forgiving fail class is worth inside that run. An entry that comes back for a
+ * further attempt has already spent a full autofix budget without converging, and
+ * the plan's remaining entries are worth more than its next round. Raising a class
+ * budget raises this with it, which is the relationship that should hold.
+ */
+export declare const ENTRY_ATTEMPT_BUDGET: number;
+/** The budget in force, honouring an UNOBSERVED flag on any class. */
+export declare function autofixBudget(i: Pick<ResolutionInput, 'failClass' | 'unobserved'>): number;
+export declare function contradictionReason(c: SpecContradiction): string;
+/**
+ * The ordered ladder. FIRST MATCH WINS, and this order is the only statement of
+ * the policy:
+ *
+ *  1. `spec-contradiction` — the fix the check demands is the edit the spec
+ *     forbids. First, because every row below would otherwise spend a budget,
+ *     a human's attention or both on a loop that cannot converge (0053 ran three
+ *     rounds past this exact fact).
+ *  2. `judge-accept` — before any budget arithmetic, because that arithmetic is
+ *     precisely what used to override a correct ACCEPT with a rescue attempt.
+ *  3. `no-autofix-budget` — a class worth zero attempts. Its own row, not folded
+ *     into the one below, because a budget that was never offered must not be
+ *     reported as one that was spent.
+ *  4. `budget-spent` — consecutive unattended attempts that all still FAIL. A
+ *     person breaks the loop, or (unattended) it terminates with a debt.
+ *  5. `autofix` — unconditional, so the table is total.
+ */
+export declare const RESOLUTION_RULES: ReadonlyArray<{
+    id: ResolutionRuleId;
+    match: (i: ResolutionInput) => Disposition | null;
+}>;
+export declare function resolveDisposition(i: ResolutionInput): Disposition;