@mjasnikovs/pi-task 0.29.3 → 0.30.0

package/dist/task/auto-orchestrator.js

@@ -35,6 +35,7 @@ import { runGatesForTask } from './task-gates.js';
 import { gitUnmergedPaths, gitStashRef } from './auto-commit.js';
 import { runFinalIntegrationGate, deriveOpenDebts } from './final-gate.js';
 import { describeDebt, recordFinalGateUnobservedDebt } from './accept-debt.js';
+import { ignoredWriteTrailLine, ignoredWriteDebtReason } from './write-guard.js';
 import { applyDemotions, isNonProgress, normalizeFailureDetail, rankedFirstFailure, unobservedDebtReason } from './final-gate-progress.js';
 import { classifyFinalGateAnswer, MAX_FINAL_GATE_AUTOFIX, FINAL_LEAVE_LABEL, FINAL_LEAVE_VALUE, FINAL_ACCEPT_LABEL, FINAL_ACCEPT_VALUE, FINAL_AUTOFIX_LABEL, FINAL_AUTOFIX_VALUE, STRANDED_FIX_COMMIT, strandedFixNote } from './final-gate-fix.js';
 import { getConfig } from '../config/config.js';
@@ -1322,6 +1323,11 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     // after MAX_FINAL_GATE_AUTOFIX attempts that still FAIL the
                     // autofix card is withdrawn so the loop cannot run unbounded.
                     let fixAttempts = 0;
+                    // Gitignored paths the fix passes have written so far in this
+                    // resolution loop (mx5 run 19). Accumulated across attempts: a
+                    // `.env` written by a failed attempt is still on disk for the next
+                    // one, and that attempt's own before/after diff cannot see it.
+                    let ignoredWritten = [];
                     // Sub-fixes a non-converging autofix attempt left uncommitted.
                     // Refreshed after every attempt; drives the picker note and the
                     // terminal commit (mx5 run 13 PROMPT 4 item 3, run 14 item 2b).
@@ -1446,7 +1452,30 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                             const seed = choice.guidance ?
                                 `${fin.reason}\n\nUser guidance: ${choice.guidance}`
                                 : fin.reason;
-                            const fix = await deps.finalGateFix(active, cwd, seed);
+                            const fix = await deps.finalGateFix(active, cwd, seed, ignoredWritten);
+                            // IGNORED-PATH WRITES (mx5 run 19). The pass wrote file(s)
+                            // git ignores, so they are not in the commit and a fresh
+                            // clone does not have them. Trailed on EVERY outcome — a
+                            // rejected attempt's tracked edits are discarded while its
+                            // ignored writes survive on disk — and carried forward, so a
+                            // later attempt's PASS is judged against everything this loop
+                            // wrote, not just its own attempt. PATH NAMES ONLY: an ignored
+                            // file's contents (`.env` is the canonical case) never enter a
+                            // log, a debt or a child prompt.
+                            if (fix.ignoredWrites && fix.ignoredWrites.length > 0) {
+                                ignoredWritten = [
+                                    ...new Set([...ignoredWritten, ...fix.ignoredWrites])
+                                ].sort();
+                                await recGate(ignoredWriteTrailLine(fix.ignoredWrites));
+                                // Debt only where a verdict can rest on the file: the
+                                // probe proved the gate needs it, or the question stayed
+                                // open. A write the gate demonstrably does NOT need is
+                                // trailed and nothing more — a ledger full of scratch
+                                // files is a ledger nobody reads.
+                                if (fix.ignoredDependent !== false) {
+                                    await recordFinalGateUnobservedDebt(cwd, id, ignoredWriteDebtReason(fix.ignoredWrites, fix.ignoredDependent));
+                                }
+                            }
                             if (fix.ok) {
                                 await deps.commit(cwd, `FINAL GATE AUTOFIX (${id})`);
                                 // A converged re-run that observed nothing dynamic is

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

@@ -1,4 +1,4 @@
-import { type TreeChangeSummary } from './write-guard.js';
+import { type TreeChangeSummary, type IgnoredSnapshot } from './write-guard.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. */
 export declare const FINAL_FIX_TOOLS = "read,edit,bash";
@@ -108,6 +108,14 @@ export interface FinalFixResult {
      *  labels a converge-on-statics-alone the same way it labels a first-pass one —
      *  "converged" must never quietly mean "we stopped being able to check". */
     unobserved?: string;
+    /** Gitignored path(s) this fix pass wrote, exempt classes already removed (see
+     *  write-guard.ts). Present whether or not the gate converged — the caller
+     *  trails them either way; path names only, never contents. */
+    ignoredWrites?: string[];
+    /** …and the mechanical dependency probe found the converged gate does NOT pass
+     *  without them, so `unobserved` above carries the downgrade. Absent when the
+     *  probe could not answer (no probe wired, restore risk, too many paths). */
+    ignoredDependent?: boolean;
     /** A write-guard rejected this attempt (deletion / shrink / probe-gaming). */
     guardTripped?: boolean;
     /** …and its edits were discarded. When a guard tripped and this is false, the
@@ -158,6 +166,19 @@ export interface FinalFixDeps {
      *  run 11's autofix replaced the typed client with a hand-written contract
      *  copy to green the lint. Findings are verbatim offending lines. */
     probeScan?: () => Promise<string[]>;
+    /** Fingerprint of the ACTIONABLE ignored paths (build output and node_modules
+     *  already exempt). Called before and after the child; the difference is what
+     *  this pass wrote. Absent → the channel is off and behaviour is unchanged. */
+    ignoredSnapshot?: () => Promise<IgnoredSnapshot>;
+    /** Ignored paths EARLIER attempts in this resolution loop already wrote. An
+     *  attempt that fails still leaves its ignored writes on disk (discard reverts
+     *  tracked files only), so without this a `.env` written by attempt 1 would be
+     *  invisible to attempt 2's before/after diff — and attempt 2's converged PASS
+     *  would rest on it unrecorded. The caller accumulates. */
+    ignoredKnown?: string[];
+    /** The mechanical dependency test: does the gate still pass with these paths
+     *  moved aside? `null` ⇒ unanswerable, which never downgrades a verdict. */
+    gateWithoutIgnored?: (paths: string[]) => Promise<boolean | null>;
     /** Write a timestamped line to the gate debug log (guard events). */
     log?: (msg: string) => void;
 }

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/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/write-guard.d.ts

@@ -54,6 +54,48 @@ export declare function parseNameStatusChanges(nameStatus: string): TreeChangeSu
  * destroyed a sibling task's verified deliverable.
  */
 export declare function findForbiddenDeletions(changes: TreeChangeSummary): string[];
+/** Why an ignored path is (or is not) something the gate may rule on. */
+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
+ * 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.
+ */
+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.
+ */
+export declare function diffIgnoredSnapshots(before: IgnoredSnapshot, after: IgnoredSnapshot): string[];
+/**
+ * The gate-trail line. PATH NAMES ONLY: the contents of an ignored file are never
+ * read into a log, a debt reason or a child prompt (`.env` is the canonical case —
+ * this channel exists because of a file full of credentials).
+ */
+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.
+ */
+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

package/dist/task/write-guard.js

@@ -132,6 +132,114 @@ export function findForbiddenDeletions(changes) {
     const addedNames = new Set(changes.added.map(basename));
     return changes.deleted.filter(p => !addedNames.has(basename(p)));
 }
+/**
+ * Directory names that are build output or a dependency tree by convention. The
+ * parsed outdirs (see classifyIgnoredPath's `outdirs`) come from the project's
+ * own tooling and are the primary mechanism; this list is the fallback for
+ * projects whose build is not declared in a package.json (CMake, cargo, gradle).
+ */
+const BUILD_DIR_NAMES = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'target',
+    'out',
+    'coverage',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+    '.turbo',
+    '.cache',
+    '.parcel-cache',
+    '.vite',
+    '.gradle',
+    '__pycache__',
+    '.pytest_cache',
+    '.venv',
+    'venv'
+]);
+/**
+ * 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
+ * project's own tooling, which is exactly what makes it not a gate concern.
+ */
+export function classifyIgnoredPath(rel, outdirs) {
+    const segs = rel
+        .replace(/^\.\//, '')
+        .split('/')
+        .filter(s => s.length > 0);
+    if (segs.length === 0)
+        return 'actionable';
+    if (segs.includes('.pi-tasks'))
+        return 'task-dir';
+    if (segs.includes('.git'))
+        return 'vcs-meta';
+    if (segs.includes('node_modules'))
+        return 'dep-dir';
+    for (const o of outdirs) {
+        const oSegs = o
+            .replace(/^\.\//, '')
+            .split('/')
+            .filter(s => s.length > 0);
+        if (oSegs.length > 0 && oSegs.every((s, i) => segs[i] === s))
+            return 'build-output';
+    }
+    if (segs.some(s => BUILD_DIR_NAMES.has(s)))
+        return 'build-output';
+    return 'actionable';
+}
+/** The ignored paths a gate may rule on: everything not exempt by mechanism. */
+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.
+ */
+export function diffIgnoredSnapshots(before, after) {
+    const out = [];
+    for (const [p, fp] of Object.entries(after)) {
+        if (before[p] !== fp)
+            out.push(p);
+    }
+    return out.sort();
+}
+/**
+ * The gate-trail line. PATH NAMES ONLY: the contents of an ignored file are never
+ * read into a log, a debt reason or a child prompt (`.env` is the canonical case —
+ * this channel exists because of a file full of credentials).
+ */
+export function ignoredWriteTrailLine(paths) {
+    return (`final-gate: fix pass modified IGNORED path(s) — ${paths.join(', ')}; `
+        + 'these are NOT committed and NOT reproducible from the repository');
+}
+/**
+ * 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.
+ */
+export function ignoredWriteDebtReason(paths, dependent) {
+    const head = dependent === true ?
+        `final-gate PASS depended on gitignored file(s) the run wrote and cannot ship: ${paths.join(', ')}. `
+            + 'A fresh clone does NOT have them, so the checks that passed here cannot be reproduced. '
+        : `the final-gate fix pass wrote gitignored file(s) that are NOT in the commit: ${paths.join(', ')}. `
+            + 'Whether the gate needs them was not established, so a fresh clone may not reproduce this run. ';
+    return (head
+        + 'The durable fix is a TRACKED counterpart (e.g. .env.example) or a check that '
+        + 'does not need the file — never committing the ignored file itself.');
+}
+/** The UNOBSERVED note that replaces such a PASS. Path names only, same rule. */
+export function ignoredWriteUnobservedNote(paths) {
+    return (`UNOBSERVED — NOT a pass: the gate's checks passed only with gitignored file(s) `
+        + `this run wrote (${paths.join(', ')}), which are not in the commit; re-running `
+        + 'them without those files FAILS, so no reproducible evidence was produced.');
+}
 /**
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.29.3",
+    "version": "0.30.0",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",