@mjasnikovs/pi-task 0.17.27 → 0.18.1

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

@@ -0,0 +1,182 @@
+/**
+ * final-gate-fix — the bounded, model-driven fix pass offered when the FINAL
+ * integration gate fails.
+ *
+ * The failure this closes (mx5 run 7, validated): the final gate's first live
+ * firing was a TRUE POSITIVE — the project's own `test` command genuinely failed
+ * whole-repo while every per-slice check was green — but the resolution picker
+ * offered only "Leave failed" / "Accept". There was NO automated path to fix a
+ * defect the run itself shipped; the user had to leave the run failed, fix by
+ * hand, and resume.
+ *
+ * This mirrors the per-task graduated-resolution shape (lint-fix.ts): a bounded
+ * write-enabled child (read, edit, bash) is seeded with the gate's exact failure
+ * (command + exit code + output tail), fixes the defect in place, and the gate
+ * itself is re-run as the only arbiter — the child's self-report is never
+ * trusted. The user always chooses this path from the picker ("Leave failed"
+ * stays the recommended default), and attempts are capped so a non-converging
+ * loop hands control back to a person.
+ *
+ * CHEAT GUARD (deterministic): the cheapest way for a fix child to "converge" is
+ * to remove the failing command itself — delete the `test` script, drop the
+ * Makefile target — so the gate discovers nothing and vacuously passes. Both
+ * live lint-fix validation runs cheated exactly this way (via git checkout)
+ * until a guard existed. So the discovered gate commands are snapshotted before
+ * the child runs; any previously-discovered command that is no longer
+ * discoverable afterwards rejects the attempt and discards its edits. A fix may
+ * change what a command DOES, never make it disappear.
+ */
+import { USER_CANCELLED } from './child-runner.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 const FINAL_FIX_TOOLS = 'read,edit,bash';
+/**
+ * How many fix passes the user may launch from the picker before the option is
+ * withdrawn (mirrors the per-task MAX_AUTO_AUTOFIX budget). Each attempt is a
+ * full model child plus a full gate re-run — after this many that still FAIL,
+ * only Leave-failed / Accept remain so a person breaks the loop.
+ */
+export const MAX_FINAL_GATE_AUTOFIX = 3;
+/** Picker labels/values. Classification accepts the value token, the label, or
+ *  free text (→ autofix guidance), same contract as the per-task resolution. */
+export const FINAL_LEAVE_VALUE = 'fail';
+export const FINAL_ACCEPT_VALUE = 'accept';
+export const FINAL_AUTOFIX_VALUE = 'autofix';
+export const FINAL_LEAVE_LABEL = 'Leave failed — I will fix and /task-auto-resume';
+export const FINAL_ACCEPT_LABEL = 'Accept — complete the run anyway';
+export const FINAL_AUTOFIX_LABEL = 'Autofix — run a bounded fix pass and re-run the gate';
+/**
+ * Map a final-gate picker answer to an action. Dismissal (undefined/empty) and
+ * an explicit leave stay "leave" — exactly what the two-option picker did.
+ * Free text becomes autofix guidance, mirroring classifyResolutionAnswer; the
+ * caller demotes autofix back to "leave" when the option was not offered.
+ */
+export function classifyFinalGateAnswer(answer) {
+    if (answer === undefined)
+        return { action: 'leave' };
+    const t = answer.trim();
+    if (t.length === 0)
+        return { action: 'leave' };
+    if (t === FINAL_LEAVE_VALUE || /^leave\b/i.test(t))
+        return { action: 'leave' };
+    if (t === FINAL_ACCEPT_VALUE || /^accept\b/i.test(t))
+        return { action: 'accept' };
+    if (t === FINAL_AUTOFIX_VALUE || /^autofix\b/i.test(t))
+        return { action: 'autofix' };
+    return { action: 'autofix', guidance: t };
+}
+/**
+ * The gate's fail reason always carries the failing command in backticks
+ * (`` `bun run test` exited 1 — … `` / ``static checks: `make lint` exited 2``).
+ * Extract it for reporting; the shrink guard itself compares the FULL
+ * discovered-command sets, so a reason this cannot parse still guards.
+ */
+export function extractFailingCommand(reason) {
+    const m = /`([^`]+)`\s+exited\b/.exec(reason);
+    return m ? m[1] : null;
+}
+/**
+ * Build the fix child's prompt. Generic by construction: the only project facts
+ * in it are the gate's own failure text — the command comes from the project's
+ * discovered manifest, never from a hardcoded ecosystem.
+ */
+export function buildFinalFixPrompt(failReason) {
+    return [
+        'You are a bounded fix pass for a FAILED whole-repo integration gate.',
+        'Every task in this run is complete and committed; then the project’s own',
+        'integration command was run against the assembled repository and failed:',
+        '',
+        failReason.trim(),
+        '',
+        'Your ONLY job is to make that command pass by fixing the DEFECT it reveals.',
+        '',
+        '1. Re-run the exact failing command first and read its full output.',
+        '2. Diagnose the root cause, then fix it with the smallest correct change.',
+        '   The project’s own manifests, configs and conventions define what',
+        '   correct means — follow them, do not invent new structure.',
+        '',
+        '3. HARD CONSTRAINTS:',
+        '   - Do NOT delete, skip, disable, or weaken tests or checks to make the',
+        '     command pass. Relocating or scoping a file the runner was never meant',
+        '     to pick up (per the project’s own config) is a legitimate fix;',
+        '     deleting it or marking it skipped is not.',
+        '   - Do NOT remove or rename the project’s own commands (its test/build/',
+        '     lint scripts or targets). Making the gate unable to find the command',
+        '     is detected and the whole fix is rejected.',
+        '   - Do NOT run git commands that mutate state (checkout, restore, reset,',
+        '     revert, stash, clean). The work in this repository is finished and',
+        '     committed — reverting it is destroying the run, not fixing it.',
+        '',
+        '4. Re-run the failing command after your fix and confirm it exits 0. The',
+        '   gate is re-run mechanically after you finish — your claim is not the',
+        '   verdict, the real exit code is.',
+        '',
+        'End with exactly one line:',
+        '  FINAL-GATE-FIX: DONE',
+        '  FINAL-GATE-FIX: BLOCKED <why you could not fix it>'
+    ].join('\n');
+}
+/**
+ * Parse the child's final marker. Last match wins (the model reasons before
+ * concluding and bash output can echo the words). No marker → treated as DONE:
+ * the gate re-run is the arbiter either way, so a missing marker only skips the
+ * early-out on a self-declared BLOCKED.
+ */
+export function parseFinalFixMarker(text) {
+    const re = /FINAL-GATE-FIX:\s*(DONE|BLOCKED)\b[ \t]*(.*)/gi;
+    let last = null;
+    for (let m = re.exec(text); m !== null; m = re.exec(text))
+        last = m;
+    if (!last)
+        return { blocked: false };
+    if (last[1].toUpperCase() === 'BLOCKED') {
+        return { blocked: true, note: last[2].trim() || 'no reason given' };
+    }
+    return { blocked: false, note: last[2].trim() || undefined };
+}
+/**
+ * Run one bounded final-gate fix attempt: snapshot discovery → child → shrink
+ * guard → gate re-run. Never throws for an outcome; only a user cancel inside
+ * runChild propagates (the caller's USER_CANCELLED path handles it).
+ */
+export async function runFinalGateAutofix(deps) {
+    const before = deps.discoverLabels(deps.cwd);
+    let text;
+    try {
+        text = await deps.runChild(FINAL_FIX_TOOLS, buildFinalFixPrompt(deps.failReason), deps.signal);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg === USER_CANCELLED)
+            throw err;
+        return { ok: false, reason: `fix child failed: ${msg}` };
+    }
+    // SHRINK GUARD: every gate command discoverable before the fix must still be
+    // discoverable after it. A vanished command means the child "fixed" the gate
+    // by removing the check — reject and (when possible) discard the edits.
+    const after = new Set(deps.discoverLabels(deps.cwd));
+    const vanished = before.filter(label => !after.has(label));
+    if (vanished.length > 0) {
+        if (deps.discard)
+            await deps.discard(deps.cwd);
+        return {
+            ok: false,
+            reason: `fix pass removed the gate's own command(s) (${vanished.join(', ')}) — `
+                + `edits ${deps.discard ? 'discarded' : 'REJECTED but left in the tree (no discard available)'}`
+        };
+    }
+    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}` };
+    }
+    const fin = await deps.gate(deps.cwd);
+    if (!fin.ok) {
+        return {
+            ok: false,
+            reason: `did not converge: ${fin.reason}`,
+            gateReason: fin.reason
+        };
+    }
+    return { ok: true, reason: fin.reason };
+}

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

@@ -15,9 +15,45 @@ export declare function discoverIntegrationCommands(cwd: string): {
     ecosystem: string | null;
     cmds: HealthCommand[];
 };
+/** Every lockfile consistency check that applies to this tree (possibly none). */
+export declare function discoverLockfileChecks(cwd: string): HealthCommand[];
 /**
- * Run the final gate: static analysis first, then the discovered integration
- * commands, whole-repo, verbatim, unaided. Deterministic and synchronous under
- * the hood (callers wrap in Promise.resolve). First real failure wins.
+ * The project's OWN launch command, if it declares one (package.json `start`,
+ * else `dev`; Makefile `run`). null means the project has nothing to boot —
+ * the boot check degrades to nothing-to-run.
  */
-export declare function runFinalIntegrationGate(cwd: string, timeoutMs?: number): FinalGateOutcome;
+export declare function discoverBootCommand(cwd: string): HealthCommand | null;
+type BootOutcome = {
+    outcome: 'skip' | 'pass';
+} | {
+    outcome: 'fail';
+    detail: string;
+};
+/**
+ * Exercise the start command ONCE, with no port/URL/framework knowledge — the
+ * command's own fate within the grace window decides:
+ *
+ *   - non-zero exit (or signal death) before the window closes → FAIL, output tail;
+ *   - exit 0 before the window closes → PASS (a CLI-style "run" that finished);
+ *   - still alive when the window closes → PASS, then the whole process group is
+ *     killed (detached spawn = own group; SIGTERM, escalating to SIGKILL).
+ *
+ * Env-gap contract as everywhere: spawn error (ENOENT) or exit 127 → skip.
+ */
+export declare function runBootCheck(cwd: string, [bin, args]: HealthCommand, graceMs?: number): Promise<BootOutcome>;
+/**
+ * Labels (`bin args…`) of every command the gate CAN currently discover — the
+ * static half (repo-health) plus the integration half. Pure discovery, nothing
+ * runs. Used by the final-gate autofix shrink guard: a fix pass that makes a
+ * previously-discoverable command undiscoverable (deleted the script/target) is
+ * gaming the gate, not fixing the defect.
+ */
+export declare function discoverGateCommandLabels(cwd: string): string[];
+/**
+ * Run the final gate: static analysis first, then the lockfile consistency
+ * checks, then the discovered integration commands, then one boot exercise of
+ * the start command — whole-repo, verbatim, unaided. Deterministic (no model).
+ * First real failure wins.
+ */
+export declare function runFinalIntegrationGate(cwd: string, timeoutMs?: number, bootGraceMs?: number): Promise<FinalGateOutcome>;
+export {};

package/dist/task/final-gate.js

@@ -15,7 +15,18 @@
  * and lets their REAL exit codes decide:
  *
  *   - static analysis first (runRepoHealthCheck — cheap, precise), then
- *   - the project's own `test` and `build` commands, run verbatim and unaided.
+ *   - lockfile↔manifest consistency (mx5 run 7, validated: the lockfile carried a
+ *     dependency no committed manifest declared, so the tree tested green here
+ *     but a FRESH CHECKOUT could not even install — each ecosystem's own offline
+ *     "is the lock in sync" command decides), then
+ *   - the project's own `test` and `build` commands, run verbatim and unaided, then
+ *   - one boot exercise of the project's own start command (mx5 run 7, validated:
+ *     every static and test gate green, yet `bun run start` died in ~1s on a
+ *     self-inflicted EADDRINUSE — nothing had ever LAUNCHED the finished project).
+ *     No ports, URLs, or framework knowledge: fast non-zero exit → FAIL, quick
+ *     exit 0 → PASS (CLI-style), still alive after the grace window → PASS and
+ *     the whole process group is killed (scripts spawn children; a leaked child
+ *     server would mask every later boot check with a port collision).
  *
  * Environment-gap safety, same contract as repo-health-check: a command that
  * CANNOT run (ENOENT, exit 127 = command-not-found inside the script chain, or a
@@ -27,10 +38,10 @@
  * per-task gates kept excusing — and the caller puts a human on the decision
  * (accept / leave failed), so a genuine external gap can still be overridden.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
-import { runRepoHealthCheck } from './repo-health-check.js';
+import { runRepoHealthCheck, discoverHealthCommands } from './repo-health-check.js';
 function packageScripts(cwd) {
     try {
         const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -96,6 +107,141 @@ export function discoverIntegrationCommands(cwd) {
     }
     return { ecosystem: null, cmds: [] };
 }
+/**
+ * Per-ecosystem lockfile↔manifest consistency checks. A check applies only when
+ * BOTH the manifest and its lockfile exist (no lockfile → nothing to verify),
+ * and every command is the ecosystem's own non-mutating "is the lock in sync
+ * with the manifest" form — validated to exit 0 fast on an in-sync tree and
+ * non-zero on a genuine desync, without touching the tree or (when in sync)
+ * the network.
+ */
+const LOCKFILE_CHECKS = [
+    {
+        manifest: 'package.json',
+        lockfiles: ['bun.lock', 'bun.lockb'],
+        cmd: ['bun', ['install', '--frozen-lockfile', '--dry-run']]
+    },
+    {
+        manifest: 'package.json',
+        lockfiles: ['package-lock.json'],
+        cmd: ['npm', ['ci', '--dry-run']]
+    },
+    {
+        manifest: 'Cargo.toml',
+        lockfiles: ['Cargo.lock'],
+        cmd: ['cargo', ['metadata', '--locked', '--format-version', '1']]
+    },
+    { manifest: 'go.mod', lockfiles: ['go.sum'], cmd: ['go', ['mod', 'verify']] },
+    { manifest: 'pyproject.toml', lockfiles: ['uv.lock'], cmd: ['uv', ['lock', '--check']] },
+    { manifest: 'pyproject.toml', lockfiles: ['poetry.lock'], cmd: ['poetry', ['check', '--lock']] }
+];
+/** Every lockfile consistency check that applies to this tree (possibly none). */
+export function discoverLockfileChecks(cwd) {
+    const cmds = [];
+    for (const { manifest, lockfiles, cmd } of LOCKFILE_CHECKS) {
+        if (!existsSync(path.join(cwd, manifest)))
+            continue;
+        if (!lockfiles.some(f => existsSync(path.join(cwd, f))))
+            continue;
+        cmds.push(cmd);
+    }
+    return cmds;
+}
+/**
+ * The project's OWN launch command, if it declares one (package.json `start`,
+ * else `dev`; Makefile `run`). null means the project has nothing to boot —
+ * the boot check degrades to nothing-to-run.
+ */
+export function discoverBootCommand(cwd) {
+    if (existsSync(path.join(cwd, 'package.json'))) {
+        const s = packageScripts(cwd);
+        for (const name of ['start', 'dev']) {
+            if (s[name])
+                return ['bun', ['run', name]];
+        }
+        return null;
+    }
+    if (existsSync(path.join(cwd, 'Makefile')) && makeHasTarget(cwd, 'run')) {
+        return ['make', ['run']];
+    }
+    return null;
+}
+/**
+ * Exercise the start command ONCE, with no port/URL/framework knowledge — the
+ * command's own fate within the grace window decides:
+ *
+ *   - non-zero exit (or signal death) before the window closes → FAIL, output tail;
+ *   - exit 0 before the window closes → PASS (a CLI-style "run" that finished);
+ *   - still alive when the window closes → PASS, then the whole process group is
+ *     killed (detached spawn = own group; SIGTERM, escalating to SIGKILL).
+ *
+ * Env-gap contract as everywhere: spawn error (ENOENT) or exit 127 → skip.
+ */
+export function runBootCheck(cwd, [bin, args], graceMs = 10_000) {
+    return new Promise(resolve => {
+        const child = spawn(bin, args, {
+            cwd,
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env }
+        });
+        let out = '';
+        let err = '';
+        const cap = (s) => (s.length > 8000 ? s.slice(-8000) : s);
+        child.stdout?.on('data', (d) => (out = cap(out + String(d))));
+        child.stderr?.on('data', (d) => (err = cap(err + String(d))));
+        let settled = false;
+        const settle = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(r);
+        };
+        const killGroup = (sig) => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, sig);
+            }
+            catch {
+                // group already gone
+            }
+        };
+        const timer = setTimeout(() => {
+            settle({ outcome: 'pass' });
+            killGroup('SIGTERM');
+            setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
+        }, graceMs);
+        child.on('error', () => settle({ outcome: 'skip' }));
+        child.on('exit', (status, signal) => {
+            if (status === 0)
+                return settle({ outcome: 'pass' });
+            if (status === 127 || (status === null && signal === null)) {
+                return settle({ outcome: 'skip' });
+            }
+            const what = status !== null ? `exited ${status}` : `was killed by ${signal}`;
+            const tail = outputTail(out, err);
+            settle({ outcome: 'fail', detail: `${what}${tail ? ` — ${tail}` : ''}` });
+        });
+    });
+}
+/**
+ * Labels (`bin args…`) of every command the gate CAN currently discover — the
+ * static half (repo-health) plus the integration half. Pure discovery, nothing
+ * runs. Used by the final-gate autofix shrink guard: a fix pass that makes a
+ * previously-discoverable command undiscoverable (deleted the script/target) is
+ * gaming the gate, not fixing the defect.
+ */
+export function discoverGateCommandLabels(cwd) {
+    const boot = discoverBootCommand(cwd);
+    const labels = [
+        ...discoverHealthCommands(cwd).cmds,
+        ...discoverLockfileChecks(cwd),
+        ...discoverIntegrationCommands(cwd).cmds,
+        ...(boot ? [boot] : [])
+    ].map(([bin, args]) => `${bin} ${args.join(' ')}`);
+    return [...new Set(labels)];
+}
 /** Last ~`limit` chars of the command's combined output, one line, for the reason. */
 function outputTail(stdout, stderr, limit = 400) {
     const combined = `${stdout}\n${stderr}`.trim();
@@ -105,34 +251,70 @@ function outputTail(stdout, stderr, limit = 400) {
     return combined.length > limit ? `…${tail}` : tail;
 }
 /**
- * Run the final gate: static analysis first, then the discovered integration
- * commands, whole-repo, verbatim, unaided. Deterministic and synchronous under
- * the hood (callers wrap in Promise.resolve). First real failure wins.
+ * Run one gate command with the env-gap contract: tool missing, timeout, or
+ * command-not-found inside the script chain (127) → environment gap, not a code
+ * fault → skipped (same contract as repo-health). Only a command that actually
+ * ran and exited non-zero fails.
+ */
+function runGateCommand(cwd, [bin, args], timeoutMs) {
+    // env passed explicitly: bun's spawnSync resolves the binary against a
+    // startup snapshot of the environment, not the live process.env.
+    const r = spawnSync(bin, args, {
+        cwd,
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        env: { ...process.env }
+    });
+    if (r.error || r.status === null || r.status === 127)
+        return { outcome: 'skip' };
+    if (r.status !== 0) {
+        return { outcome: 'fail', status: r.status, tail: outputTail(r.stdout ?? '', r.stderr ?? '') };
+    }
+    return { outcome: 'pass' };
+}
+/**
+ * Run the final gate: static analysis first, then the lockfile consistency
+ * checks, then the discovered integration commands, then one boot exercise of
+ * the start command — whole-repo, verbatim, unaided. Deterministic (no model).
+ * First real failure wins.
  */
-export function runFinalIntegrationGate(cwd, timeoutMs = 900_000) {
+export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGraceMs = 10_000) {
     const stat = runRepoHealthCheck(cwd);
     if (!stat.ok)
         return { ok: false, reason: `static checks: ${stat.reason}` };
-    const { ecosystem, cmds } = discoverIntegrationCommands(cwd);
-    if (!ecosystem || cmds.length === 0) {
+    const lockCmds = discoverLockfileChecks(cwd);
+    const { cmds } = discoverIntegrationCommands(cwd);
+    const boot = discoverBootCommand(cwd);
+    if (lockCmds.length === 0 && cmds.length === 0 && !boot) {
         return { ok: true, reason: 'no integration command found (statics passed)' };
     }
     const ran = [];
-    for (const [bin, args] of cmds) {
-        const label = `${bin} ${args.join(' ')}`;
-        const r = spawnSync(bin, args, { cwd, encoding: 'utf8', timeout: timeoutMs });
-        // Tool missing, timeout, or command-not-found inside the script chain →
-        // environment gap, not a code fault; skip (same contract as repo-health).
-        if (r.error || r.status === null || r.status === 127)
-            continue;
-        if (r.status !== 0) {
-            const tail = outputTail(r.stdout ?? '', r.stderr ?? '');
-            return {
-                ok: false,
-                reason: `\`${label}\` exited ${r.status}${tail ? ` — ${tail}` : ''}`
-            };
+    for (const { prefix, list } of [
+        { prefix: 'lockfile check: ', list: lockCmds },
+        { prefix: '', list: cmds }
+    ]) {
+        for (const cmd of list) {
+            const label = `${cmd[0]} ${cmd[1].join(' ')}`;
+            const r = runGateCommand(cwd, cmd, timeoutMs);
+            if (r.outcome === 'skip')
+                continue;
+            if (r.outcome === 'fail') {
+                return {
+                    ok: false,
+                    reason: `${prefix}\`${label}\` exited ${r.status}${r.tail ? ` — ${r.tail}` : ''}`
+                };
+            }
+            ran.push(label);
+        }
+    }
+    if (boot) {
+        const label = `${boot[0]} ${boot[1].join(' ')}`;
+        const b = await runBootCheck(cwd, boot, bootGraceMs);
+        if (b.outcome === 'fail') {
+            return { ok: false, reason: `boot check: \`${label}\` ${b.detail}` };
         }
-        ran.push(label);
+        if (b.outcome === 'pass')
+            ran.push(label);
     }
     return {
         ok: true,

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

@@ -1,8 +1,13 @@
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import type { GateDeps } from './task-gates.js';
+import { type FinalFixResult } from './final-gate-fix.js';
 import { type ChangedFile } from './substitution-probe.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'];
+/** 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>;
 /**
  * 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
@@ -23,4 +28,6 @@ export declare function buildGateDeps(params: {
     signal: AbortSignal;
     parentContextWindow: number;
     runTask: RunTaskFn;
-}): GateDeps;
+}): GateDeps & {
+    finalGateFix: FinalGateFixFn;
+};

package/dist/task/gate-deps.js

@@ -19,8 +19,12 @@ import { tasksDir, readTaskFile, appendGateRecord } from './task-io.js';
 import { gitCommitAll, gitDropLastCommit, git } from './auto-commit.js';
 import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-guidelines.js';
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
+import { readEnvNotes, appendEnvNotes } from './env-notes.js';
 import { runRepoHealthCheck } from './repo-health-check.js';
+import { runFinalIntegrationGate, discoverGateCommandLabels } from './final-gate.js';
+import { runFinalGateAutofix } from './final-gate-fix.js';
 import { researchResolution } from './verify-resolution.js';
+import { extractProhibitions, findProhibitionViolations } from './prohibition-probe.js';
 import { findSubstitutionSuspects } from './substitution-probe.js';
 import { runBoundedLintFix } from './lint-fix.js';
 import { captureGitState, reconcileGitState } from './git-state-guard.js';
@@ -88,6 +92,13 @@ export function buildGateDeps(params) {
     // child run (see git-state-guard.ts). runWorkVerification reads this through its
     // 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/log writes made during the pass survive both. Shared by the enforce
+    // pre-commit gate (discardEdits) and the final-gate autofix shrink guard.
+    const discardTreeEdits = async (cwd2) => {
+        await git(cwd2, ['checkout', '--', '.', EXCLUDE_TASKS_DIR], signal);
+        await git(cwd2, ['clean', '-fd', '-e', '.pi-tasks'], signal);
+    };
     // Shared runner for the per-task GATE children (verify + post-FAIL recommend).
     // Both are read-only passes of the same local model that must run to completion:
     // unguarded (no wall-clock timeout, exact-match loop guard only, path-revisit
@@ -280,12 +291,30 @@ export function buildGateDeps(params) {
                 // authored/changed become prompt-level findings mandating the child
                 // to drive the real artifact before trusting their green result.
                 probe: () => collectChangedFiles(cwd2, signal).then(findSubstitutionSuspects),
+                // Deterministic prohibition probe: paths the spec forbids modifying
+                // that the task's diff modified anyway become prompt-level findings
+                // under the no-waiver rule — the child otherwise rarely runs `git
+                // diff` and cannot even see the violation.
+                prohibitionProbe: () => {
+                    const banned = spec ? extractProhibitions(spec) : [];
+                    if (banned.length === 0)
+                        return Promise.resolve([]);
+                    return collectChangedFiles(cwd2, signal).then(files => findProhibitionViolations(banned, files));
+                },
                 // Git-state guard result of the most recent child run: a verdict
                 // computed on a tree the child itself mutated is discarded (the
                 // guard already restored the state — see git-state-guard.ts).
                 mutationCheck: () => lastGuardReconcile?.mutated ?
                     { mutated: true, detail: lastGuardReconcile.actions.join('; ') }
-                    : { mutated: false, detail: '' }
+                    : { mutated: false, detail: '' },
+                // Per-run environment-facts cache under .pi-tasks/ (survives
+                // discardEdits): earlier children's discoveries save this child
+                // the re-archaeology; its own ENV-NOTE lines are stored for the
+                // next one. Facts only — verdict rules unaffected.
+                envNotes: {
+                    read: () => readEnvNotes(cwd2),
+                    append: notes => appendEnvNotes(cwd2, notes)
+                }
             });
         },
         lintFix: (fixCtx, cwd2, taskTitle, failReason) => runBoundedLintFix({
@@ -305,12 +334,18 @@ export function buildGateDeps(params) {
             const r = await git(cwd2, ['status', '--porcelain', '--', '.', EXCLUDE_TASKS_DIR], signal);
             return r.exitCode === 0 && r.stdout.trim().length > 0;
         },
-        discardEdits: async (cwd2) => {
-            // Restore tracked files to HEAD and drop files the pass created; the
-            // .pi-tasks trail/log writes made during the pass survive both.
-            await git(cwd2, ['checkout', '--', '.', EXCLUDE_TASKS_DIR], signal);
-            await git(cwd2, ['clean', '-fd', '-e', '.pi-tasks'], signal);
-        },
+        discardEdits: discardTreeEdits,
+        finalGateFix: (fixCtx, cwd2, failReason) => runFinalGateAutofix({
+            cwd: cwd2,
+            signal,
+            failReason,
+            runChild: makeGateChild(fixCtx, cwd2, 'final integration gate', 'final-fix', 'final-gate-debug.log'),
+            // The gate re-run is the only arbiter of convergence, and the
+            // shrink guard's discovery is the gate's own (see final-gate.ts).
+            gate: c => runFinalIntegrationGate(c),
+            discoverLabels: discoverGateCommandLabels,
+            discard: discardTreeEdits
+        }),
         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).