@mjasnikovs/pi-task 0.29.3 → 0.31.0

package/dist/task/final-gate-fix.js

@@ -44,7 +44,7 @@
  * producing task). It activates only when a run-GLOBAL freeze source exists.
  */
 import { USER_CANCELLED } from './child-runner.js';
-import { findForbiddenDeletions } from './write-guard.js';
+import { findForbiddenDeletions, diffIgnoredSnapshots, ignoredWriteTrailLine, ignoredWriteUnobservedNote } from './write-guard.js';
 import { findNarrowedCommands, narrowingRejectionText } from './command-shrink.js';
 /** Same bounded-fix contract as lint-fix: edit in place, bash exists to RUN the
  *  failing command (and the project's own tooling), not to mutate git state. */
@@ -215,6 +215,10 @@ export function strandedFixNote(paths) {
 export async function runFinalGateAutofix(deps) {
     const before = deps.discoverLabels(deps.cwd);
     const bodiesBefore = deps.discoverBodies?.(deps.cwd) ?? {};
+    // Ignored paths as they stood BEFORE the child. Attribution needs both ends:
+    // ignored files are untracked, so git alone cannot tell a file this pass wrote
+    // from one that was already sitting in the worktree.
+    const ignoredBefore = deps.ignoredSnapshot ? await deps.ignoredSnapshot() : null;
     let text;
     try {
         text = await deps.runChild(FINAL_FIX_TOOLS, buildFinalFixPrompt(deps.failReason), deps.signal);
@@ -225,7 +229,22 @@ export async function runFinalGateAutofix(deps) {
             throw err;
         return { ok: false, reason: `fix child failed: ${msg}` };
     }
-    const rejected = (what) => ({
+    // What the child wrote to gitignored paths. Recorded on the trail IMMEDIATELY —
+    // before any guard can reject the attempt — because `discard` reverts tracked
+    // edits only: an ignored file the pass wrote survives a rejection, and the trail
+    // is the only place that fact can ever be read back.
+    const ignoredWrites = ignoredBefore === null || !deps.ignoredSnapshot ?
+        []
+        : [
+            ...new Set([
+                ...diffIgnoredSnapshots(ignoredBefore, await deps.ignoredSnapshot()),
+                ...(deps.ignoredKnown ?? [])
+            ])
+        ].sort();
+    if (ignoredWrites.length > 0)
+        deps.log?.(ignoredWriteTrailLine(ignoredWrites));
+    const withIgnored = (r) => ignoredWrites.length > 0 ? { ...r, ignoredWrites } : r;
+    const rejected = (what) => withIgnored({
         ok: false,
         reason: `${what} — edits ${deps.discard ? 'discarded' : 'REJECTED but left in the tree (no discard available)'}`,
         guardTripped: true,
@@ -311,16 +330,44 @@ export async function runFinalGateAutofix(deps) {
     const marker = parseFinalFixMarker(text);
     if (marker.blocked) {
         // Self-declared blocked: skip the (expensive) gate re-run; nothing converged.
-        return { ok: false, reason: `fix child blocked: ${marker.note}` };
+        return withIgnored({ ok: false, reason: `fix child blocked: ${marker.note}` });
     }
     const fin = await deps.gate(deps.cwd);
     if (!fin.ok) {
-        return {
+        return withIgnored({
             ok: false,
             reason: `did not converge: ${fin.reason}`,
             gateReason: fin.reason,
             gateFailures: fin.failures
-        };
+        });
+    }
+    // IGNORED-DEPENDENCY DOWNGRADE (mx5 run 19). The gate says PASS; the question
+    // this answers is whether that PASS belongs to the REPOSITORY or only to this
+    // worktree. Decided mechanically, never by judgement: move the ignored files
+    // the pass wrote aside, re-run the gate once, put them back. Still passing ⇒
+    // they were incidental and the PASS stands. Failing ⇒ the checks were passing
+    // on state no fresh clone has, which is the definition of UNOBSERVED (see
+    // final-gate.ts unobservedVerdict) — not a FAIL: the fix is real, it just did
+    // not ship. The probe runs only here, so a run with no ignored writes (the
+    // overwhelming majority — 1 of 68 recorded child logs) pays nothing.
+    let ignoredDependent;
+    if (ignoredWrites.length > 0 && deps.gateWithoutIgnored) {
+        const passesWithout = await deps.gateWithoutIgnored(ignoredWrites);
+        if (passesWithout !== null)
+            ignoredDependent = !passesWithout;
     }
-    return { ok: true, reason: fin.reason, ...(fin.unobserved ? { unobserved: fin.unobserved } : {}) };
+    const notes = [
+        ...(fin.unobserved ? [fin.unobserved] : []),
+        ...(ignoredDependent === true ? [ignoredWriteUnobservedNote(ignoredWrites)] : [])
+    ];
+    if (ignoredDependent === true) {
+        deps.log?.(`final-gate: converged PASS DOWNGRADED to UNOBSERVED — the gate does not pass with `
+            + `${ignoredWrites.join(', ')} moved aside, and those path(s) are gitignored`);
+    }
+    return withIgnored({
+        ok: true,
+        reason: fin.reason,
+        ...(notes.length > 0 ? { unobserved: notes.join(' ') } : {}),
+        ...(ignoredDependent !== undefined ? { ignoredDependent } : {})
+    });
 }

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

@@ -1,5 +1,5 @@
 import { type HealthCommand } from './repo-health-check.js';
-import { type AcceptDebt } from './accept-debt.js';
+import { type AcceptDebt, type VerifyRerunResult } from './accept-debt.js';
 import { type RenderOutcome } from './render-check.js';
 import { type DeepRenderOutcome } from './deep-render-check.js';
 import { taskThatIntroduced } from './task-provenance.js';
@@ -344,6 +344,40 @@ export declare function discoverGateCommandBodies(cwd: string): Record<string, s
  * this box; the same wording in a `test` run is a real failure the suite must own).
  */
 export declare const INFRA_GAP_OUTPUT_RE: RegExp;
+/**
+ * How a re-run of ONE recorded VERIFY command line ended.
+ *   pass — it ran and exited 0. The ONLY outcome that may close a debt.
+ *   fail — it ran and exited non-zero for a real reason. Debt stays open.
+ *   gap  — nothing was observed: the shell/runner never spawned, 127 inside the
+ *          chain, a timeout, a missing browser, or absent external infrastructure.
+ *          INCONCLUSIVE, so the debt stays open (surface, never re-hide).
+ */
+export type VerifyRerunOutcome = {
+    outcome: 'pass';
+} | {
+    outcome: 'fail';
+    status: number;
+    tail: string;
+} | {
+    outcome: 'gap';
+    detail: string;
+};
+/**
+ * Re-run one VERIFY-block command line (nexttask 5) under the gate's existing
+ * env-gap contract, so a debt whose reason NAMES that command can be closed by the
+ * command itself rather than by a judgement about it.
+ *
+ * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: run 19's
+ * is `AGENT=1 bun test test/listings.test.ts`, and env prefixes, `&&` and redirects
+ * are all ordinary there. The leading command word is still resolved through
+ * runner-resolve so a login-shell-stripped PATH cannot make every re-run look like a
+ * gap (mx5 run 16's blindness, one level down).
+ *
+ * The asymmetry is the point: only exit 0 is conclusive. Every other ending — real
+ * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the
+ * debt exactly as open as it was.
+ */
+export declare function runVerifyCommandLine(cwd: string, line: string, timeoutMs: number, extraGapRe?: RegExp): VerifyRerunOutcome;
 /**
  * The full-skip blindness guard (mx5 run 16, validated): dynamic commands were
  * DISCOVERED but every single one skipped as an environment gap, so the gate
@@ -484,7 +518,26 @@ export { taskThatIntroduced };
 export declare function deriveOpenDebts(cwd: string, staticOk: boolean): Promise<{
     openDebts: AcceptDebt[];
     debtNote?: string;
+    trail?: string[];
 }>;
+/**
+ * Re-run ONE debt's stored VERIFY command for the re-check, with the no-write guard
+ * (`inv-no-write`) wrapped around it.
+ *
+ * A VERIFY command is the project's own command and may legitimately write (a build
+ * emits `dist/`, a suite writes a snapshot). What it may NOT do is turn the tree into
+ * a passing tree and have that count as the debt being fixed — the run would then be
+ * certifying its own side effect. So tracked state is captured before and after, and
+ * a pass that came with a tracked change is downgraded to INCONCLUSIVE with the
+ * change named. Untracked output is left alone: it is what a build legitimately
+ * produces, and `git status --porcelain` in a repo with the usual ignores does not
+ * see it.
+ *
+ * A repository the guard cannot read (no git, git absent) is not a licence to skip
+ * the guard: the re-run is INCONCLUSIVE there, because "nothing changed" would be an
+ * assumption rather than an observation.
+ */
+export declare function rerunDebtVerifyCommand(cwd: string, command: string): VerifyRerunResult;
 /**
  * Run the final gate: static analysis first, then the lockfile consistency
  * checks, then the discovered integration commands, then one boot exercise of

package/dist/task/final-gate.js

@@ -1038,6 +1038,56 @@ function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe) {
     }
     return { outcome: 'pass' };
 }
+/** The command word of a shell line, past any leading `VAR=value` assignments. */
+function leadingBin(line) {
+    for (const tok of line.trim().split(/\s+/)) {
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tok))
+            continue;
+        return tok;
+    }
+    return null;
+}
+/**
+ * Re-run one VERIFY-block command line (nexttask 5) under the gate's existing
+ * env-gap contract, so a debt whose reason NAMES that command can be closed by the
+ * command itself rather than by a judgement about it.
+ *
+ * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: run 19's
+ * is `AGENT=1 bun test test/listings.test.ts`, and env prefixes, `&&` and redirects
+ * are all ordinary there. The leading command word is still resolved through
+ * runner-resolve so a login-shell-stripped PATH cannot make every re-run look like a
+ * gap (mx5 run 16's blindness, one level down).
+ *
+ * The asymmetry is the point: only exit 0 is conclusive. Every other ending — real
+ * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the
+ * debt exactly as open as it was.
+ */
+export function runVerifyCommandLine(cwd, line, timeoutMs, extraGapRe) {
+    const bin = leadingBin(line);
+    const runner = bin === null ? null : resolveRunner(bin);
+    const r = spawnSync('sh', ['-c', line], {
+        cwd,
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        env: runner ? runnerEnv(runner) : { ...process.env }
+    });
+    if (r.error)
+        return { outcome: 'gap', detail: `shell did not spawn (${r.error.message})` };
+    if (r.status === null)
+        return { outcome: 'gap', detail: 'killed (timeout or signal)' };
+    const output = `${r.stdout ?? ''}\n${r.stderr ?? ''}`;
+    if (r.status === 0)
+        return { outcome: 'pass' };
+    if (isCommandNotFound(r.status, output)) {
+        return { outcome: 'gap', detail: 'command not found (127)' };
+    }
+    if (ENV_GAP_OUTPUT_RE.test(output))
+        return { outcome: 'gap', detail: 'missing browser/runtime' };
+    if (INFRA_GAP_OUTPUT_RE.test(output) || extraGapRe?.test(output) === true) {
+        return { outcome: 'gap', detail: 'external infrastructure unreachable' };
+    }
+    return { outcome: 'fail', status: r.status, tail: outputTail(r.stdout ?? '', r.stderr ?? '') };
+}
 /**
  * The full-skip blindness guard (mx5 run 16, validated): dynamic commands were
  * DISCOVERED but every single one skipped as an environment gap, so the gate
@@ -1204,12 +1254,16 @@ export { taskThatIntroduced };
  * must pass `false` (unprovable ⇒ stays open), never a guess.
  */
 export async function deriveOpenDebts(cwd, staticOk) {
-    const { open: openRaw, resolved } = recheckAcceptDebts(await readAcceptDebts(cwd), {
+    const { open: openRaw, resolved, trail } = recheckAcceptDebts(await readAcceptDebts(cwd), {
         staticOk,
         // Cross-task-deletion debts auto-close iff the deleted file is back in the
         // tree — a deterministic existence check, corroborating the per-file
         // provenance the record already carries.
-        fileExists: rel => existsSync(path.join(cwd, rel))
+        fileExists: rel => existsSync(path.join(cwd, rel)),
+        // VERIFY-COMMAND class (nexttask 5): a debt that NAMES a command is settled
+        // by running that command, under the gate's own env-gap contract and behind
+        // the no-write guard below.
+        rerunVerify: cmd => rerunDebtVerifyCommand(cwd, cmd)
     });
     if (resolved.length > 0)
         await writeAcceptDebts(cwd, openRaw);
@@ -1219,7 +1273,65 @@ export async function deriveOpenDebts(cwd, staticOk) {
     // a deletion instruction. Pure git-history lookup; degrades to no annotation.
     const openDebts = annotateDebtConflicts(openRaw, p => taskThatIntroduced(cwd, p));
     const debtNote = buildAcceptDebtNote(openDebts);
-    return { openDebts, ...(debtNote ? { debtNote } : {}) };
+    return { openDebts, ...(debtNote ? { debtNote } : {}), ...(trail.length > 0 ? { trail } : {}) };
+}
+/** Per-command ceiling for a debt re-run (`inv-bounded`). */
+const DEBT_RERUN_TIMEOUT_MS = 300_000;
+/**
+ * Extra infrastructure-gap shapes recognised ONLY when re-running a debt's command,
+ * never in the gate's own verdicts. A driver that reports its connection simply
+ * closed (`ERR_POSTGRES_CONNECTION_CLOSED` — what bun's SQL client says when the
+ * database is not there at all, as on this box with the mx5 container stopped) is an
+ * absent dependency, and calling that "the defect is still present" would be a
+ * finding the environment invented. Kept out of INFRA_GAP_OUTPUT_RE on purpose: in a
+ * gate verdict the same wording can be a real fault the suite must own, and only the
+ * debt re-check needs the conservative reading — where it costs nothing, because gap
+ * and fail both leave the debt open.
+ */
+const DEBT_INFRA_GAP_RE = /ERR_POSTGRES_CONNECTION_CLOSED|ERR_MYSQL_CONNECTION|ECONNRESET/i;
+/**
+ * Re-run ONE debt's stored VERIFY command for the re-check, with the no-write guard
+ * (`inv-no-write`) wrapped around it.
+ *
+ * A VERIFY command is the project's own command and may legitimately write (a build
+ * emits `dist/`, a suite writes a snapshot). What it may NOT do is turn the tree into
+ * a passing tree and have that count as the debt being fixed — the run would then be
+ * certifying its own side effect. So tracked state is captured before and after, and
+ * a pass that came with a tracked change is downgraded to INCONCLUSIVE with the
+ * change named. Untracked output is left alone: it is what a build legitimately
+ * produces, and `git status --porcelain` in a repo with the usual ignores does not
+ * see it.
+ *
+ * A repository the guard cannot read (no git, git absent) is not a licence to skip
+ * the guard: the re-run is INCONCLUSIVE there, because "nothing changed" would be an
+ * assumption rather than an observation.
+ */
+export function rerunDebtVerifyCommand(cwd, command) {
+    const tracked = () => {
+        const r = spawnSync('git', ['status', '--porcelain', '--untracked-files=no'], {
+            cwd,
+            encoding: 'utf8',
+            timeout: 60_000
+        });
+        return r.error || r.status !== 0 ? null : (r.stdout ?? '');
+    };
+    const before = tracked();
+    const r = runVerifyCommandLine(cwd, command, DEBT_RERUN_TIMEOUT_MS, DEBT_INFRA_GAP_RE);
+    if (r.outcome === 'fail')
+        return { outcome: 'fail', detail: `exit ${r.status} — ${r.tail}` };
+    if (r.outcome === 'gap')
+        return { outcome: 'gap', detail: r.detail };
+    const after = tracked();
+    if (before === null || after === null) {
+        return { outcome: 'gap', detail: 'tracked-state guard could not read git status' };
+    }
+    if (before !== after) {
+        return {
+            outcome: 'gap',
+            detail: 'the re-run itself CHANGED tracked files — a command that edits the tree into a pass proves nothing'
+        };
+    }
+    return { outcome: 'pass' };
 }
 /**
  * Run the final gate: static analysis first, then the lockfile consistency

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

@@ -3,7 +3,7 @@ import type { GateDeps } from './task-gates.js';
 import { type FinalFixResult } from './final-gate-fix.js';
 import { type AddedLine } from './probe-gaming.js';
 import { type ChangedFile } from './substitution-probe.js';
-import { type TreeChangeSummary } from './write-guard.js';
+import { type TreeChangeSummary, type IgnoredSnapshot } from './write-guard.js';
 /** A function that re-runs a task's implementation turn (AUTOFIX). Injected by the
  *  command so this module stays free of the orchestrators (avoids an import cycle). */
 export type RunTaskFn = GateDeps['runTask'];
@@ -15,7 +15,11 @@ export type RunTaskFn = GateDeps['runTask'];
 export declare function truncateToolResult(text: string, limit?: number): string;
 /** One bounded final-gate fix attempt (see final-gate-fix.ts): fix child →
  *  shrink guard → gate re-run. Consumed by /task-auto's run-end gate branch. */
-export type FinalGateFixFn = (ctx: ExtensionCommandContext, cwd: string, failReason: string) => Promise<FinalFixResult>;
+export type FinalGateFixFn = (ctx: ExtensionCommandContext, cwd: string, failReason: string, 
+/** Ignored paths earlier attempts in this resolution loop already wrote (see
+ *  FinalFixDeps.ignoredKnown) — a failed attempt's ignored writes survive its
+ *  discard and can green a later attempt. */
+ignoredKnown?: string[]) => Promise<FinalFixResult>;
 /**
  * Collect the task's changed files as pure GIT SHAPE — path + added-line count,
  * no content, no language parsing — for the self-verification probe. Before the
@@ -40,6 +44,41 @@ export declare function collectAddedLines(cwd: string, signal?: AbortSignal): Pr
  * Failures degrade to an empty summary — the guard then has nothing to reject.
  */
 export declare function collectTreeChanges(cwd: string, signal?: AbortSignal): Promise<TreeChangeSummary>;
+/**
+ * Build output directories declared by the project's OWN build commands
+ * (`--outdir=X`, `--out-dir X`), so the ignored-write exemption follows the real
+ * tooling instead of a name list. Best-effort: an unreadable or non-JSON manifest
+ * contributes nothing and the name-list fallback in classifyIgnoredPath applies.
+ */
+export declare function parseBuildOutdirs(cwd: string): string[];
+/**
+ * IGNORED-PATH CHANNEL (mx5 run 19 — see write-guard.ts). A fingerprint of every
+ * ACTIONABLE ignored path (`git status --porcelain --ignored=matching`, minus
+ * build output / node_modules / .pi-tasks / .git), taken before and after a
+ * write-capable gate child so its writes to files git never reports are
+ * attributable to it.
+ *
+ * `--ignored=matching` collapses a wholly-ignored directory into ONE entry, which
+ * is what keeps this cheap: `node_modules/` is one exempt line, never 40,000
+ * stats. Every failure mode degrades to `{}` — no git, an older git that rejects
+ * `--ignored=matching`, an unreadable path — so the gate behaves exactly as it did
+ * before this channel existed.
+ */
+export declare function collectIgnoredSnapshot(cwd: string, signal?: AbortSignal): Promise<IgnoredSnapshot>;
+/**
+ * The dependency test, decided mechanically rather than by judgement: move the
+ * ignored paths aside, re-run the gate once, put them back. A gate that no longer
+ * passes without them was passing on state the repository does not contain.
+ *
+ * Returns null when the question could not be answered (nothing movable, a move or
+ * a restore fault, too many paths) — an unanswered probe never downgrades a
+ * verdict. Restoration runs in a finally and is best-effort per path: leaving a
+ * developer's `.env` renamed on disk would be a far worse failure than a missed
+ * downgrade.
+ */
+export declare function gatePassesWithoutIgnored(cwd: string, paths: string[], runGate: (cwd: string) => Promise<{
+    ok: boolean;
+}>, log?: (msg: string) => void): Promise<boolean | null>;
 /**
  * The task's changes for the cross-task deletion probe: the working tree's status
  * when the work is uncommitted (pre-commit verify), else the LAST COMMIT's

package/dist/task/gate-deps.js

@@ -13,7 +13,7 @@
  * path-revisit disabled because re-running the same check IS the job), each with a
  * status widget and a per-gate debug log under .pi-tasks/.
  */
-import { existsSync } from 'node:fs';
+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';
@@ -32,7 +32,7 @@ import { extractProhibitions, findProhibitionViolations } from './prohibition-pr
 import { frozenPathsFromSpec, revertFrozenPaths } from './frozen-path-guard.js';
 import { findProbeGaming, parseAddedLines } from './probe-gaming.js';
 import { findSubstitutionSuspects, isTestFile } from './substitution-probe.js';
-import { parseTreeChanges, parseNameStatusChanges, formatTreeChanges } from './write-guard.js';
+import { parseTreeChanges, parseNameStatusChanges, formatTreeChanges, findActionableIgnoredWrites } from './write-guard.js';
 import { taskThatIntroduced, findCrossTaskDeletions } from './task-provenance.js';
 import { findTestRebuiltAssemblies, testAssemblyVerifyFindings } from './test-assembly.js';
 import { runBoundedLintFix } from './lint-fix.js';
@@ -253,6 +253,133 @@ export async function collectTreeChanges(cwd, signal) {
     const r = await git(cwd, ['status', '--porcelain', '--', '.', EXCLUDE_TASKS_DIR], signal);
     return r.exitCode === 0 ? parseTreeChanges(r.stdout) : { modified: [], deleted: [], added: [] };
 }
+/**
+ * Build output directories declared by the project's OWN build commands
+ * (`--outdir=X`, `--out-dir X`), so the ignored-write exemption follows the real
+ * tooling instead of a name list. Best-effort: an unreadable or non-JSON manifest
+ * contributes nothing and the name-list fallback in classifyIgnoredPath applies.
+ */
+export function parseBuildOutdirs(cwd) {
+    let raw;
+    try {
+        raw = readFileSync(path.join(cwd, 'package.json'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    let scripts;
+    try {
+        scripts = JSON.parse(raw).scripts ?? {};
+    }
+    catch {
+        return [];
+    }
+    const out = new Set();
+    for (const body of Object.values(scripts)) {
+        if (typeof body !== 'string')
+            continue;
+        for (const m of body.matchAll(/--out-?dir[= ]([^\s'"]+)/g)) {
+            const p = (m[1] ?? '').replace(/^\.\//, '').replace(/\/+$/, '');
+            if (p.length > 0 && !p.startsWith('-'))
+                out.add(p);
+        }
+    }
+    return [...out];
+}
+/**
+ * IGNORED-PATH CHANNEL (mx5 run 19 — see write-guard.ts). A fingerprint of every
+ * ACTIONABLE ignored path (`git status --porcelain --ignored=matching`, minus
+ * build output / node_modules / .pi-tasks / .git), taken before and after a
+ * write-capable gate child so its writes to files git never reports are
+ * attributable to it.
+ *
+ * `--ignored=matching` collapses a wholly-ignored directory into ONE entry, which
+ * is what keeps this cheap: `node_modules/` is one exempt line, never 40,000
+ * stats. Every failure mode degrades to `{}` — no git, an older git that rejects
+ * `--ignored=matching`, an unreadable path — so the gate behaves exactly as it did
+ * before this channel existed.
+ */
+export async function collectIgnoredSnapshot(cwd, signal) {
+    const r = await git(cwd, ['status', '--porcelain', '--ignored=matching', '--', '.', EXCLUDE_TASKS_DIR], signal);
+    if (r.exitCode !== 0)
+        return {};
+    const outdirs = parseBuildOutdirs(cwd);
+    const paths = r.stdout
+        .split('\n')
+        .filter(l => l.startsWith('!! '))
+        .map(l => l.slice(3).trim())
+        .map(p => (p.startsWith('"') && p.endsWith('"') ? p.slice(1, -1) : p))
+        .filter(p => p.length > 0);
+    const snap = {};
+    for (const rel of findActionableIgnoredWrites(paths, outdirs)) {
+        try {
+            const st = await fsp.stat(path.join(cwd, rel));
+            // A directory's own mtime moves when entries are added or removed; that
+            // is the whole fingerprint available for one without walking it, and a
+            // walk is exactly the cost this channel refuses to pay.
+            snap[rel] = st.isDirectory() ? `dir:${st.mtimeMs}` : `${st.mtimeMs}:${st.size}`;
+        }
+        catch {
+            // Vanished between status and stat — nothing to fingerprint.
+        }
+    }
+    return snap;
+}
+/**
+ * The dependency test, decided mechanically rather than by judgement: move the
+ * ignored paths aside, re-run the gate once, put them back. A gate that no longer
+ * passes without them was passing on state the repository does not contain.
+ *
+ * Returns null when the question could not be answered (nothing movable, a move or
+ * a restore fault, too many paths) — an unanswered probe never downgrades a
+ * verdict. Restoration runs in a finally and is best-effort per path: leaving a
+ * developer's `.env` renamed on disk would be a far worse failure than a missed
+ * downgrade.
+ */
+export async function gatePassesWithoutIgnored(cwd, paths, runGate, log) {
+    if (paths.length === 0 || paths.length > MAX_IGNORED_PROBE_PATHS)
+        return null;
+    const moved = [];
+    try {
+        for (const rel of paths) {
+            // `--ignored=matching` reports a wholly-ignored DIRECTORY with a trailing
+            // slash (`logs/`). Left on, `${path.join(cwd, 'logs/')}.pi-gate-probe`
+            // names a path INSIDE the directory, so the rename is a move-into-itself
+            // and the probe silently answers null for every directory entry.
+            const from = path.join(cwd, rel.replace(/\/+$/, ''));
+            const to = `${from}.pi-gate-probe`;
+            try {
+                await fsp.rename(from, to);
+                moved.push({ from, to });
+            }
+            catch {
+                // Could not move one → the probe cannot answer the question at all.
+                return null;
+            }
+        }
+        if (moved.length === 0)
+            return null;
+        const again = await runGate(cwd);
+        return again.ok;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        for (const m of moved) {
+            try {
+                await fsp.rename(m.to, m.from);
+            }
+            catch {
+                log?.(`final-gate: WARNING — could not restore ${path.relative(cwd, m.from)} after `
+                    + `the ignored-dependency probe; it is on disk as ${path.basename(m.to)}`);
+            }
+        }
+    }
+}
+/** Bound on the ignored-dependency probe: past this the set is not a fix child's
+ *  handful of files and moving them is not a safe thing to do to a worktree. */
+const MAX_IGNORED_PROBE_PATHS = 20;
 /**
  * The task's changes for the cross-task deletion probe: the working tree's status
  * when the work is uncommitted (pre-commit verify), else the LAST COMMIT's
@@ -806,7 +933,7 @@ export function buildGateDeps(params) {
             return r.exitCode === 0 && r.stdout.trim().length > 0;
         },
         discardEdits: discardTreeEdits,
-        finalGateFix: (fixCtx, cwd2, failReason) => runFinalGateAutofix({
+        finalGateFix: (fixCtx, cwd2, failReason, ignoredKnown) => runFinalGateAutofix({
             cwd: cwd2,
             signal,
             failReason,
@@ -831,6 +958,17 @@ export function buildGateDeps(params) {
             // preserve registry), never a per-task union.
             treeChanges: () => collectTreeChanges(cwd2, signal),
             probeScan: () => collectAddedLines(cwd2, signal).then(findProbeGaming),
+            // IGNORED-PATH CHANNEL (mx5 run 19): the write guards above read
+            // `git status --porcelain`, which never reports ignored paths, so
+            // the pass that greened `bun run seed` by writing credentials into
+            // a gitignored `.env` was structurally invisible to all of them —
+            // and the gate certified a PASS no fresh clone can reproduce. This
+            // does not reject the write (a local `.env` is often the only way to
+            // make a check run); it records it, and downgrades a PASS proven to
+            // depend on it.
+            ignoredSnapshot: () => collectIgnoredSnapshot(cwd2, signal),
+            ...(ignoredKnown && ignoredKnown.length > 0 ? { ignoredKnown } : {}),
+            gateWithoutIgnored: paths => gatePassesWithoutIgnored(cwd2, paths, c => runFinalIntegrationGate(c), makeDebugAppender(path.join(tasksDir(cwd2), 'final-gate-debug.log'))),
             log: makeDebugAppender(path.join(tasksDir(cwd2), 'final-gate-debug.log'))
         }),
         recommend: async (recCtx, cwd2, taskTitle, taskId, failReason) => {

package/dist/task/plan-io.d.ts

@@ -0,0 +1,55 @@
+/** Next free TASK_PLAN_NNNN id. Mirrors allocateAutoId. */
+export declare function allocatePlanId(cwd: string): Promise<string>;
+/**
+ * How an answer to a model question was produced. Recorded verbatim in the plan
+ * file because "the user chose this" and "the recommendation was accepted by
+ * default" are different levels of evidence when you read the plan back later —
+ * the same distinction /task-auto draws with its "(accepted recommendation)" and
+ * "(YOLO)" stamps.
+ */
+export type AnswerSource = 'chosen' | 'accepted' | 'typed' | 'skipped' | 'yolo';
+export type PlanEntry = 
+/** The model asked; the user answered. */
+{
+    kind: 'decision';
+    question: string;
+    answer: string;
+    source: AnswerSource;
+}
+/** The user volunteered a decision without being asked. */
+ | {
+    kind: 'stated';
+    text: string;
+}
+/** The user asked; the model answered. Advisory — decides nothing on its own. */
+ | {
+    kind: 'note';
+    question: string;
+    answer: string;
+};
+/**
+ * The transcript as the MODEL sees it — fed back as `priorQA` on every next
+ * question, and prepended to the handoff prompt. Decisions are numbered so a
+ * later question can refer to one; notes and stated decisions are labelled by who
+ * said them, because a model answer the user merely READ must not be mistaken for
+ * a decision the user MADE.
+ */
+export declare function formatPlanTranscript(entries: readonly PlanEntry[]): string;
+/** Body of a fresh plan file, before any entry is recorded. */
+export declare function buildPlanBody(task: string): string;
+/**
+ * The `## decisions` section: the human-readable transcript. Same content as
+ * {@link formatPlanTranscript} — the model and the reader see the same record, so
+ * there is no hidden channel.
+ */
+export declare function formatPlanDecisions(entries: readonly PlanEntry[]): string;
+/**
+ * The prompt handed to /task when the user proceeds to execution.
+ *
+ * The task prompt leads, exactly as a bare `/task <prompt>` would, so refine sees
+ * a normal task description first; the decisions follow as an authoritative block.
+ * Anything the user did NOT settle is simply absent — /task's own grill phase asks
+ * about what is left, which is why this block never invents a decision to fill a
+ * gap.
+ */
+export declare function buildHandoffPrompt(task: string, entries: readonly PlanEntry[]): string;