@mjasnikovs/pi-task 0.17.13 → 0.17.14

package/dist/task/auto-commit.d.ts

@@ -12,6 +12,12 @@ export interface CommitResult {
     /** Short, human-readable reason when committed === false. */
     reason?: string;
 }
+export declare function git(cwd: string, args: string[], signal: AbortSignal | undefined, spawnFn?: SpawnFn): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    aborted: boolean;
+}>;
 /**
  * Stage everything (`git add -A`) and commit it with `message`. Honors
  * .gitignore via git itself. Never throws — failures surface as

package/dist/task/auto-commit.js

@@ -11,7 +11,7 @@ function firstLine(s) {
     const line = s.split('\n').find(l => l.trim().length > 0);
     return (line ?? s).trim();
 }
-async function git(cwd, args, signal, spawnFn) {
+export async function git(cwd, args, signal, spawnFn) {
     const r = await runChildDefault({ command: 'git', args }, cwd, signal, { mode: 'text' }, spawnFn);
     return { stdout: r.stdout, stderr: r.stderr, exitCode: r.exitCode, aborted: r.aborted };
 }

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

@@ -1,7 +1,17 @@
 import type { GateDeps } from './task-gates.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'];
+/**
+ * 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
+ * task commit the work is the tree-vs-HEAD diff (+ untracked files, counted from
+ * disk); on the post-enforce re-verify the tree is clean, so fall back to the last
+ * commit. Failures degrade to an empty list — the probe is a sharpener, never a
+ * blocker.
+ */
+export declare function collectChangedFiles(cwd: string, signal?: AbortSignal): Promise<ChangedFile[]>;
 /**
  * Build the gate deps for one command run. `runTask` is the orchestrator's
  * implementation re-runner, injected by the caller. The returned object also drives

package/dist/task/gate-deps.js

@@ -16,16 +16,60 @@
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { tasksDir, readTaskFile, appendGateRecord } from './task-io.js';
-import { gitCommitAll, gitDropLastCommit } from './auto-commit.js';
+import { gitCommitAll, gitDropLastCommit, git } from './auto-commit.js';
 import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-guidelines.js';
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
 import { runRepoHealthCheck } from './repo-health-check.js';
 import { researchResolution } from './verify-resolution.js';
+import { findSubstitutionSuspects } from './substitution-probe.js';
+import { runBoundedLintFix } from './lint-fix.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { formatLoopHint } from './child-runner.js';
 import { getConfig } from '../config/config.js';
 import { startAutoLoader } from './widget.js';
 import { resolveContextUsage } from './context-usage.js';
+/** Keep the gate machinery's own artifacts out of every git pathspec below. */
+const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
+const splitLines = (s) => s
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => l.length > 0);
+/** Parse `git diff --numstat` output into {path, addedLines} (binary files → 0). */
+const parseNumstat = (stdout) => splitLines(stdout).flatMap(line => {
+    const [added, , ...rest] = line.split('\t');
+    const p = rest.join('\t');
+    if (!p)
+        return [];
+    const n = Number.parseInt(added, 10);
+    return [{ path: p, addedLines: Number.isNaN(n) ? 0 : n }];
+});
+/**
+ * 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
+ * task commit the work is the tree-vs-HEAD diff (+ untracked files, counted from
+ * disk); on the post-enforce re-verify the tree is clean, so fall back to the last
+ * commit. Failures degrade to an empty list — the probe is a sharpener, never a
+ * blocker.
+ */
+export async function collectChangedFiles(cwd, signal) {
+    const tracked = await git(cwd, ['diff', '--numstat', 'HEAD', '--', '.', EXCLUDE_TASKS_DIR], signal);
+    const files = tracked.exitCode === 0 ? parseNumstat(tracked.stdout) : [];
+    const untracked = await git(cwd, ['ls-files', '--others', '--exclude-standard', '--', '.', EXCLUDE_TASKS_DIR], signal);
+    for (const name of splitLines(untracked.exitCode === 0 ? untracked.stdout : '')) {
+        try {
+            const content = await fsp.readFile(path.join(cwd, name), 'utf8');
+            files.push({ path: name, addedLines: content.split('\n').length });
+        }
+        catch {
+            // unreadable/binary — nothing to report
+        }
+    }
+    if (files.length === 0) {
+        const last = await git(cwd, ['diff', '--numstat', 'HEAD~1..HEAD', '--', '.', EXCLUDE_TASKS_DIR], signal);
+        return last.exitCode === 0 ? parseNumstat(last.stdout) : [];
+    }
+    return files;
+}
 /**
  * Build the gate deps for one command run. `runTask` is the orchestrator's
  * implementation re-runner, injected by the caller. The returned object also drives
@@ -203,9 +247,36 @@ export function buildGateDeps(params) {
                 // Deterministic whole-repo static-analysis gate — runs the project's
                 // own lint/typecheck and fails on a real non-zero exit, independent of
                 // the model-authored VERIFY block (which may not lint at all).
-                repoHealth: () => Promise.resolve(runRepoHealthCheck(cwd2))
+                repoHealth: () => Promise.resolve(runRepoHealthCheck(cwd2)),
+                // Deterministic self-verification probe: test files the task itself
+                // authored/changed become prompt-level findings mandating the child
+                // to drive the real artifact before trusting their green result.
+                probe: () => collectChangedFiles(cwd2, signal).then(findSubstitutionSuspects)
             });
         },
+        lintFix: (fixCtx, cwd2, taskTitle, failReason) => runBoundedLintFix({
+            cwd: cwd2,
+            signal,
+            failReason,
+            runChild: makeGateChild(fixCtx, cwd2, taskTitle, 'lint-fix', 'verify-debug.log'),
+            repoHealth: () => Promise.resolve(runRepoHealthCheck(cwd2)),
+            git: async (args) => {
+                const r = await git(cwd2, args, signal);
+                return { exitCode: r.exitCode, stdout: r.stdout };
+            }
+        }),
+        // Deterministic static check + tree helpers for the enforce pre-commit gate.
+        repoHealth: cwd2 => Promise.resolve(runRepoHealthCheck(cwd2)),
+        dirty: async (cwd2) => {
+            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);
+        },
         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).

package/dist/task/lint-fix.d.ts

@@ -0,0 +1,73 @@
+/**
+ * lint-fix — the bounded, graduated resolution for a repo-health verify FAIL.
+ *
+ * The failure this closes (mx5 run 3, TASK_0017): AUTOFIX's only hammer is a FULL
+ * implementation re-run. For a repo-health FAIL of 10 trivial lint findings the live
+ * run burned two 36–56-minute impl turns, each REGENERATING a fresh 900-line rewrite
+ * that failed lint differently — the loop cannot converge because the tool is bigger
+ * than the defect. Validated live on the real TASK_0017 tree: a bounded fix child
+ * (read,edit,bash) reached lint-clean in 64s and 106s, 2/2.
+ *
+ * The same validation caught the design's failure mode: BOTH runs cheated, running
+ * `git checkout -- src/test/request.ts` — REVERTING the task's uncommitted work to
+ * make the findings vanish. So this pass ships with a deterministic REVERT-GUARD,
+ * outcome-based (command filtering can't catch every path to the same effect):
+ *
+ *   - Before the child runs: snapshot the full working state (`git add -A` +
+ *     `git write-tree`, then unstage) and record which files differ from HEAD.
+ *   - After: any pre-existing work file now byte-identical to HEAD means the child
+ *     discarded work instead of fixing it → restore the snapshot, report not-applied.
+ *   - Converge check: the injected repoHealth must pass; otherwise not-applied.
+ *
+ * A file whose ENTIRE pre-fix diff was the lint finding (fixing it legitimately
+ * restores HEAD) trips the guard conservatively — the fix is discarded and the
+ * ordinary AUTOFIX picker takes over. Safe direction: the guard may only cost time,
+ * never work.
+ *
+ * Not-applied is never terminal: the caller falls through to the existing
+ * recommend → AUTOFIX/ACCEPT/dismiss picker, so this pass can only make the loop
+ * faster, never change what it can decide.
+ */
+export interface LintFixResult {
+    /** true → findings fixed, repo health passes, work preserved. */
+    ok: boolean;
+    /** why the fix was not applied (guard trip, no convergence, child error). */
+    reason?: string;
+}
+export interface LintFixDeps {
+    cwd: string;
+    signal?: AbortSignal;
+    /** The verify FAIL reason (names the failing command, e.g. "repo health: `bun run lint` exited 1"). */
+    failReason: string;
+    /** Run the fix child; same closure shape the other gate children use. */
+    runChild: (tools: string, prompt: string, signal?: AbortSignal) => Promise<string>;
+    /** The deterministic whole-repo static check to converge against. */
+    repoHealth: () => Promise<{
+        ok: boolean;
+        reason: string;
+    }>;
+    /** Run git in cwd; injected so the guard logic is unit-testable. */
+    git: (args: string[]) => Promise<{
+        exitCode: number;
+        stdout: string;
+    }>;
+}
+/** The fix child edits and runs the checker; bash exists to RUN the check, not git. */
+export declare const LINT_FIX_TOOLS = "read,edit,bash";
+/**
+ * Build the fix child's prompt. The constraints encode both live findings: smallest
+ * edits only (the impl re-run's rewrite habit is the defect this pass replaces), and
+ * an explicit ban on discarding work (both validation runs reached green via
+ * `git checkout` of the work file until the guard existed).
+ */
+export declare function buildLintFixPrompt(failReason: string): string;
+/**
+ * Pure guard core: which pre-existing work files did the fix pass revert to HEAD?
+ * `preDirty` = files differing from HEAD before the fix; `stillDirty` = after.
+ */
+export declare function revertGuardViolations(preDirty: string[], stillDirty: Set<string>): string[];
+/**
+ * Run the bounded fix: snapshot → child → revert-guard → converge check. Never
+ * throws for an outcome; only a child-level user cancel propagates from runChild.
+ */
+export declare function runBoundedLintFix(deps: LintFixDeps): Promise<LintFixResult>;

package/dist/task/lint-fix.js

@@ -0,0 +1,146 @@
+/**
+ * lint-fix — the bounded, graduated resolution for a repo-health verify FAIL.
+ *
+ * The failure this closes (mx5 run 3, TASK_0017): AUTOFIX's only hammer is a FULL
+ * implementation re-run. For a repo-health FAIL of 10 trivial lint findings the live
+ * run burned two 36–56-minute impl turns, each REGENERATING a fresh 900-line rewrite
+ * that failed lint differently — the loop cannot converge because the tool is bigger
+ * than the defect. Validated live on the real TASK_0017 tree: a bounded fix child
+ * (read,edit,bash) reached lint-clean in 64s and 106s, 2/2.
+ *
+ * The same validation caught the design's failure mode: BOTH runs cheated, running
+ * `git checkout -- src/test/request.ts` — REVERTING the task's uncommitted work to
+ * make the findings vanish. So this pass ships with a deterministic REVERT-GUARD,
+ * outcome-based (command filtering can't catch every path to the same effect):
+ *
+ *   - Before the child runs: snapshot the full working state (`git add -A` +
+ *     `git write-tree`, then unstage) and record which files differ from HEAD.
+ *   - After: any pre-existing work file now byte-identical to HEAD means the child
+ *     discarded work instead of fixing it → restore the snapshot, report not-applied.
+ *   - Converge check: the injected repoHealth must pass; otherwise not-applied.
+ *
+ * A file whose ENTIRE pre-fix diff was the lint finding (fixing it legitimately
+ * restores HEAD) trips the guard conservatively — the fix is discarded and the
+ * ordinary AUTOFIX picker takes over. Safe direction: the guard may only cost time,
+ * never work.
+ *
+ * Not-applied is never terminal: the caller falls through to the existing
+ * recommend → AUTOFIX/ACCEPT/dismiss picker, so this pass can only make the loop
+ * faster, never change what it can decide.
+ */
+/** The fix child edits and runs the checker; bash exists to RUN the check, not git. */
+export const LINT_FIX_TOOLS = 'read,edit,bash';
+/**
+ * Build the fix child's prompt. The constraints encode both live findings: smallest
+ * edits only (the impl re-run's rewrite habit is the defect this pass replaces), and
+ * an explicit ban on discarding work (both validation runs reached green via
+ * `git checkout` of the work file until the guard existed).
+ */
+export function buildLintFixPrompt(failReason) {
+    return [
+        'You are a bounded static-analysis fix pass. A verification gate just failed',
+        `with: ${failReason}`,
+        '',
+        'The working tree contains UNCOMMITTED task work. Your ONLY job is to make the',
+        "project's own static check pass again while preserving that work untouched.",
+        '',
+        '1. Run the failing check first to see the exact findings (the command is named',
+        "   above; it is one of the project's own package.json scripts / make targets).",
+        '',
+        '2. Fix EXACTLY those findings with the smallest possible edits.',
+        '   - Do NOT rewrite, restructure, or "improve" anything else.',
+        '   - Do NOT touch files that have no findings.',
+        '   - An unused variable/import introduced by the current work: delete just',
+        '     those lines (or prefix an intentionally-unused parameter with _).',
+        '',
+        '3. HARD CONSTRAINT — never discard work: you must NOT run git checkout,',
+        '   git restore, git stash, git reset, git clean, or any git command that',
+        '   mutates state; you must NOT delete or revert whole files or functions.',
+        '   Reverting the work would make the findings vanish — that is destroying the',
+        '   task, not fixing it, and it is detected and rejected.',
+        '',
+        '4. Re-run the check after editing and confirm it exits 0.',
+        '',
+        'End with exactly one line:',
+        '  LINT-FIX: DONE',
+        '  LINT-FIX: BLOCKED <why>'
+    ].join('\n');
+}
+/**
+ * Pure guard core: which pre-existing work files did the fix pass revert to HEAD?
+ * `preDirty` = files differing from HEAD before the fix; `stillDirty` = after.
+ */
+export function revertGuardViolations(preDirty, stillDirty) {
+    return preDirty.filter(f => !stillDirty.has(f));
+}
+const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
+async function dirtyFiles(deps) {
+    const r = await deps.git(['diff', '--name-only', 'HEAD', '--', '.', EXCLUDE_TASKS_DIR]);
+    if (r.exitCode !== 0)
+        return [];
+    return r.stdout
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.length > 0);
+}
+/**
+ * Run the bounded fix: snapshot → child → revert-guard → converge check. Never
+ * throws for an outcome; only a child-level user cancel propagates from runChild.
+ */
+export async function runBoundedLintFix(deps) {
+    // Snapshot the full working state as a tree object (includes untracked files),
+    // then unstage so the child sees the tree exactly as it was.
+    const preDirty = await dirtyFiles(deps);
+    const preUntracked = (await deps.git(['ls-files', '--others', '--exclude-standard', '--', '.', EXCLUDE_TASKS_DIR])).stdout
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.length > 0);
+    let snapshot = null;
+    const add = await deps.git(['add', '-A']);
+    if (add.exitCode === 0) {
+        const wt = await deps.git(['write-tree']);
+        if (wt.exitCode === 0)
+            snapshot = wt.stdout.trim();
+        await deps.git(['reset']);
+    }
+    try {
+        await deps.runChild(LINT_FIX_TOOLS, buildLintFixPrompt(deps.failReason), deps.signal);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // A cancel must propagate so the caller's USER_CANCELLED path runs.
+        if (msg === '__user_cancelled__')
+            throw err;
+        return { ok: false, reason: `fix child failed: ${msg}` };
+    }
+    // REVERT-GUARD: every pre-existing work file must still differ from HEAD, and
+    // every pre-existing untracked file must still exist. Trip → restore snapshot.
+    const stillDirty = new Set(await dirtyFiles(deps));
+    const violations = revertGuardViolations(preDirty, stillDirty);
+    for (const f of preUntracked) {
+        const probe = await deps.git(['ls-files', '--others', '--exclude-standard', '--', f]);
+        const gone = probe.stdout.trim().length === 0
+            // ...unless the child legitimately made it tracked-dirty (it edited it).
+            && !stillDirty.has(f);
+        if (gone)
+            violations.push(f);
+    }
+    if (violations.length > 0) {
+        if (snapshot) {
+            // Restore the pre-fix state: tree paths back, then unstage. .pi-tasks is
+            // excluded so gate logs appended during the fix survive.
+            await deps.git(['checkout', snapshot, '--', '.', EXCLUDE_TASKS_DIR]);
+            await deps.git(['reset']);
+        }
+        return {
+            ok: false,
+            reason: `revert-guard: fix pass discarded work (${violations.slice(0, 3).join(', ')}`
+                + `${violations.length > 3 ? ', …' : ''}) — fix ${snapshot ? 'rolled back' : 'REJECTED but no snapshot to restore'}`
+        };
+    }
+    const health = await deps.repoHealth();
+    if (!health.ok) {
+        return { ok: false, reason: `did not converge: ${health.reason}` };
+    }
+    return { ok: true };
+}

package/dist/task/substitution-probe.d.ts

@@ -0,0 +1,51 @@
+/**
+ * substitution-probe — deterministic detection of SELF-VERIFIED work, feeding the
+ * verify gate's prompt.
+ *
+ * The failure class (mx5 run 3, TASK_0016/0017): the implementation hit a real bug
+ * in the shipped app ("Context is not finalized" from a mis-signatured middleware),
+ * blamed the framework, and shipped "integration tests" that re-implement the API
+ * inline — an own server intercepting protected routes, and a 943-line hand-rolled
+ * duplicate in a test-support file that imports the real app and never calls it.
+ * The suite runs 26/26 green while every protected route of the real server 500s.
+ * The verify child judged "do the tests pass", saw green, and PASSed.
+ *
+ * A/B on the live local model (5 runs/arm, the real mx5 tree as fixture) proved the
+ * fix must be a DETERMINISTIC, CONCRETE finding in the prompt, not prompt language
+ * alone: the bare substitution rule caught 2/5 (right verdicts, 40% attention); the
+ * rule PLUS a probe finding naming the suspect file caught 5/5, each verdict naming
+ * the exact inline handlers and confirming the real app crashes.
+ *
+ * WHAT THE PROBE ASSERTS is deliberately the class INVARIANT, not any framework
+ * shape: when a task's own diff includes the very tests whose green result would
+ * bless it, the work is grading itself — so the verify child must independently
+ * confirm those tests exercise the real shipped artifact before trusting them.
+ * That is computable from pure git diff shape (which changed files live in test
+ * paths, and how many lines the task added there): no language parsing, no server-
+ * constructor lists, no import syntax — a Python, Go, or Rust project produces the
+ * same finding the same way. (An earlier draft pattern-matched JS server
+ * constructors; that only re-encoded the one incident. A behavioral canary — rerun
+ * the suite with shipped sources removed, still-green ⇒ copy — was also rejected:
+ * the real mx5 copy still imported the shipped db module, so poisoning sources
+ * breaks the copy's tests too and the conviction never fires.)
+ *
+ * Findings are advisory: they mandate the spot-check, they never auto-FAIL. Honest
+ * self-authored tests survive the spot-check (control fixtures PASS with the
+ * mandate present); only tests that bypass the artifact get named in a FAIL.
+ */
+/** One changed file as the git-shape collector reports it. */
+export interface ChangedFile {
+    /** Path relative to the repo root (used verbatim in the finding text). */
+    path: string;
+    /** Lines the task's diff ADDED to this file (0 for pure deletions). */
+    addedLines: number;
+}
+/** Is this a file whose job is testing — by suffix or by living in a test dir? */
+export declare function isTestFile(p: string): boolean;
+/**
+ * Analyse the task's changed files and return self-verification findings — one
+ * human-readable line per test file the task itself authored or changed, ready to
+ * inject into the verify prompt. Empty array → the task ships no tests of its own,
+ * the prompt gets no probe block.
+ */
+export declare function findSubstitutionSuspects(files: ChangedFile[]): string[];

package/dist/task/substitution-probe.js

@@ -0,0 +1,63 @@
+/**
+ * substitution-probe — deterministic detection of SELF-VERIFIED work, feeding the
+ * verify gate's prompt.
+ *
+ * The failure class (mx5 run 3, TASK_0016/0017): the implementation hit a real bug
+ * in the shipped app ("Context is not finalized" from a mis-signatured middleware),
+ * blamed the framework, and shipped "integration tests" that re-implement the API
+ * inline — an own server intercepting protected routes, and a 943-line hand-rolled
+ * duplicate in a test-support file that imports the real app and never calls it.
+ * The suite runs 26/26 green while every protected route of the real server 500s.
+ * The verify child judged "do the tests pass", saw green, and PASSed.
+ *
+ * A/B on the live local model (5 runs/arm, the real mx5 tree as fixture) proved the
+ * fix must be a DETERMINISTIC, CONCRETE finding in the prompt, not prompt language
+ * alone: the bare substitution rule caught 2/5 (right verdicts, 40% attention); the
+ * rule PLUS a probe finding naming the suspect file caught 5/5, each verdict naming
+ * the exact inline handlers and confirming the real app crashes.
+ *
+ * WHAT THE PROBE ASSERTS is deliberately the class INVARIANT, not any framework
+ * shape: when a task's own diff includes the very tests whose green result would
+ * bless it, the work is grading itself — so the verify child must independently
+ * confirm those tests exercise the real shipped artifact before trusting them.
+ * That is computable from pure git diff shape (which changed files live in test
+ * paths, and how many lines the task added there): no language parsing, no server-
+ * constructor lists, no import syntax — a Python, Go, or Rust project produces the
+ * same finding the same way. (An earlier draft pattern-matched JS server
+ * constructors; that only re-encoded the one incident. A behavioral canary — rerun
+ * the suite with shipped sources removed, still-green ⇒ copy — was also rejected:
+ * the real mx5 copy still imported the shipped db module, so poisoning sources
+ * breaks the copy's tests too and the conviction never fires.)
+ *
+ * Findings are advisory: they mandate the spot-check, they never auto-FAIL. Honest
+ * self-authored tests survive the spot-check (control fixtures PASS with the
+ * mandate present); only tests that bypass the artifact get named in a FAIL.
+ */
+/** Is this a file whose job is testing — by suffix or by living in a test dir? */
+export function isTestFile(p) {
+    if (/\.(test|spec)\.[cm]?[jt]sx?$/.test(p))
+        return true;
+    if (/(^|[._-])(test|spec)s?\.[a-z]+$/.test(p))
+        return true; // test_x.py, x_test.go, x.spec.rb
+    if (/(^|\/)test_[^/]+$/.test(p))
+        return true;
+    return /(^|\/)(test|tests|__tests__|spec|specs)\//.test(p);
+}
+/**
+ * Analyse the task's changed files and return self-verification findings — one
+ * human-readable line per test file the task itself authored or changed, ready to
+ * inject into the verify prompt. Empty array → the task ships no tests of its own,
+ * the prompt gets no probe block.
+ */
+export function findSubstitutionSuspects(files) {
+    const findings = [];
+    for (const f of files) {
+        if (!isTestFile(f.path))
+            continue;
+        if (f.addedLines <= 0)
+            continue;
+        findings.push(`${f.path} (+${f.addedLines} lines) — a test file this task authored or changed itself; `
+            + 'its green result blesses the very work that wrote it');
+    }
+    return findings;
+}

package/dist/task/task-gates.d.ts

@@ -77,6 +77,35 @@ export interface GateDeps {
      * skips the revert and warns.
      */
     revert?: (cwd: string) => Promise<void>;
+    /**
+     * BOUNDED fix for a repo-health verify FAIL: a small read,edit,bash child fixes
+     * exactly the static findings (revert-guarded — see lint-fix.ts), instead of the
+     * full implementation re-run AUTOFIX reaches for. Validated live: 64s/106s to
+     * lint-clean where the impl re-run burned 36–56 min and did not converge. Runs
+     * at most once per gate sequence; not-applied falls through to the picker.
+     * Absent → the loop goes straight to recommend/picker as before.
+     */
+    lintFix?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string, failReason: string) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Deterministic whole-repo static check (repo-health), used as the PRE-COMMIT
+     * gate on an edit-mode enforce pass: live data shows enforce edits broke the
+     * repo's own lint in 11 of 16 tasks, each costing a commit + model re-verify +
+     * revert cycle. Checking before committing skips that cycle. Absent → the old
+     * commit-then-differential path runs unchanged.
+     */
+    repoHealth?: (cwd: string) => Promise<{
+        ok: boolean;
+        reason: string;
+    }>;
+    /** Does the working tree hold changes (excluding .pi-tasks)? Lets the pre-commit
+     *  health check run only when the enforce pass actually edited something. */
+    dirty?: (cwd: string) => Promise<boolean>;
+    /** Restore the working tree to HEAD (excluding .pi-tasks) — discards enforce
+     *  edits that failed the pre-commit health check, before they are committed. */
+    discardEdits?: (cwd: string) => Promise<void>;
     /**
      * Append one line to the task's durable gate trail (`## gates` in the task
      * file). Every gate outcome — each verify verdict, the user's FAIL resolution,

package/dist/task/task-gates.js

@@ -63,8 +63,24 @@ export async function runGatesForTask(ctxIn, deps, p) {
         // A FAIL no longer dead-stops: offer the boxed AUTOFIX / ACCEPT / dismiss
         // picker. The USER always decides; AUTOFIX loops straight back to the gate
         // as many times as they keep choosing it (no attempt cap).
+        let lintFixAttempted = false;
         while (!verified.ok) {
             const failReason = verified.reason ?? 'did not verify';
+            // GRADUATED resolution: a repo-health FAIL (pure static findings) gets ONE
+            // bounded fix attempt before the picker — smallest tool first. Applied →
+            // re-verify and re-enter the loop on the fresh verdict; not applied (guard
+            // trip, no convergence) → fall through to the ordinary picker unchanged.
+            if (!lintFixAttempted && deps.lintFix && failReason.startsWith('repo health:')) {
+                lintFixAttempted = true;
+                active.ui.notify(`${p.tag}: static findings on "${p.title}" — attempting bounded lint fix…`, 'info');
+                const fix = await deps.lintFix(active, p.cwd, p.title, failReason);
+                await rec(`lint-fix: ${fix.ok ? 'applied — re-verifying' : `not applied (${fix.reason ?? 'failed'})`}`);
+                if (fix.ok) {
+                    verified = await deps.verify(active, p.cwd, p.title, p.taskId);
+                    await rec(verdictLine(verified));
+                    continue;
+                }
+            }
             const recOutcome = deps.recommend ?
                 await deps.recommend(active, p.cwd, p.title, p.taskId, failReason)
                 : { recommend: 'autofix', rationale: failReason };
@@ -129,11 +145,36 @@ export async function runGatesForTask(ctxIn, deps, p) {
             `${p.tag}: enforcing AGENTS.md/CLAUDE.md on "${p.title}"…`
             : `${p.tag}: reviewing "${p.title}" against AGENTS.md/CLAUDE.md (no verify signal — report only)…`, 'info');
         const verdict = await deps.enforce(active, p.cwd, p.title, mode);
-        await rec(`enforce(${mode}): ${verdict.ok ? `clean${verdict.reason ? ` (${verdict.reason})` : ''}` : (verdict.reason ?? 'not clean')}`);
+        // The child's verdict and its edits are independent facts: the pass has been
+        // observed declaring "clean" while having edited files (which then get
+        // committed as fixes) — record both so the trail cannot contradict itself.
+        const editsMade = mode === 'edit' && deps.dirty ? await deps.dirty(p.cwd) : undefined;
+        await rec(`enforce(${mode}): ${verdict.ok ? `clean${verdict.reason ? ` (${verdict.reason})` : ''}` : (verdict.reason ?? 'not clean')}${editsMade ? ' — edits in tree' : ''}`);
         if (!verdict.ok) {
             active.ui.notify(`${p.tag}: guideline ${mode === 'edit' ? 'enforcement' : 'review'} on "${p.title}" — ${verdict.reason ?? 'not clean'} — continuing.`, 'warning');
         }
-        if (mode === 'edit') {
+        // PRE-COMMIT health gate on enforce edits: live data shows the edit pass broke
+        // the repo's own lint in 11/16 tasks, each burning a commit + model re-verify +
+        // revert cycle. A deterministic static check BEFORE committing skips the cycle
+        // and discards the bad edits outright. Only runs when the tree is actually
+        // dirty (or dirtiness is unknowable); the differential guard below still
+        // catches behavioral regressions the static check cannot see.
+        let enforceEditsBlocked = false;
+        if (mode === 'edit' && deps.repoHealth && editsMade !== false) {
+            const h = await deps.repoHealth(p.cwd);
+            if (!h.ok) {
+                enforceEditsBlocked = true;
+                if (deps.discardEdits) {
+                    await deps.discardEdits(p.cwd);
+                    await rec(`enforce: edits discarded pre-commit (repo health: ${h.reason})`);
+                }
+                else {
+                    await rec(`enforce: edits FAILED repo health pre-commit (${h.reason}) — no discard available, left uncommitted`);
+                }
+                active.ui.notify(`${p.tag}: guideline edits on "${p.title}" failed repo health (${h.reason.slice(0, 120)}) — discarded before commit.`, 'warning');
+            }
+        }
+        if (mode === 'edit' && !enforceEditsBlocked) {
             // Commit whatever the pass fixed as its own snapshot. A no-op when it made
             // no edits (nothing to commit) — then there is nothing to re-verify/revert.
             const enforceCommit = await deps.commit(p.cwd, `ENFORCE GUIDELINES: ${p.title} (${p.taskId})`);

package/dist/task/verify-work.d.ts

@@ -34,8 +34,15 @@ export declare function extractSpecForVerification(taskBody: string): string | n
  * Build the verification child's prompt. Kept pure so the wording is unit-tested
  * without spawning pi. The contract: run the spec's own verification in the real
  * workspace, judge against ACCEPTANCE, and end on exactly one verdict line.
+ *
+ * `probeFindings` are the deterministic self-verification probe results (see
+ * substitution-probe.ts): the TEST-THE-COPY class is caught 5/5 only when the
+ * prompt carries both the rule (3b) AND a concrete finding naming the suspect
+ * file — the rule alone got 2/5 attention on the live model. The findings are
+ * pure git shape (test files the task itself changed), so the mandate is
+ * language- and framework-agnostic.
  */
-export declare function buildVerifyPrompt(spec: string): string;
+export declare function buildVerifyPrompt(spec: string, probeFindings?: string[]): string;
 /**
  * Parse the child's verdict. Scans for the LAST `WORK-VERIFIED: PASS|FAIL` marker
  * (the model discusses before concluding, and bash output may echo the word
@@ -69,6 +76,12 @@ export interface VerificationDeps {
         ok: boolean;
         reason: string;
     }>;
+    /**
+     * DETERMINISTIC substitution probe (see substitution-probe.ts): scans the task's
+     * changed test files for test-the-copy shapes and returns finding lines to inject
+     * into the child's prompt. A/B-proven load-bearing: the prompt rule alone caught
+     * the class 2/5, rule + probe finding 5/5. ABSENT or empty → no probe block. */
+    probe?: () => Promise<string[]>;
 }
 /**
  * Run the verification pass for one task. A missing spec is a pass. Otherwise run

package/dist/task/verify-work.js

@@ -115,8 +115,28 @@ export function extractSpecForVerification(taskBody) {
  * Build the verification child's prompt. Kept pure so the wording is unit-tested
  * without spawning pi. The contract: run the spec's own verification in the real
  * workspace, judge against ACCEPTANCE, and end on exactly one verdict line.
+ *
+ * `probeFindings` are the deterministic self-verification probe results (see
+ * substitution-probe.ts): the TEST-THE-COPY class is caught 5/5 only when the
+ * prompt carries both the rule (3b) AND a concrete finding naming the suspect
+ * file — the rule alone got 2/5 attention on the live model. The findings are
+ * pure git shape (test files the task itself changed), so the mandate is
+ * language- and framework-agnostic.
  */
-export function buildVerifyPrompt(spec) {
+export function buildVerifyPrompt(spec, probeFindings) {
+    const probeBlock = probeFindings && probeFindings.length > 0 ?
+        [
+            'SELF-VERIFICATION NOTICE (deterministic, computed by the orchestrator from the diff):',
+            'this task wrote or changed the very tests whose green result would bless it:',
+            ...probeFindings.map(f => `- ${f}`),
+            'A green run of self-authored tests is NOT sufficient verification. Before any PASS',
+            'you MUST confirm these tests exercise the REAL shipped artifact: drive 1-2 tested',
+            'behaviors directly against the real app / module / entry point and judge what IT',
+            'returns. Tests that intercept, re-implement, or stub the artifact prove only the',
+            'copy (rule 3b below).',
+            ''
+        ]
+        : [];
     return [
         'You are a strict verification pass running right after an AI coding agent',
         'finished a task and committed it. The agent is known to mark work "done"',
@@ -130,6 +150,7 @@ export function buildVerifyPrompt(spec) {
         'THE TASK SPEC (its ACCEPTANCE criteria and VERIFY block are the contract):',
         spec.trim(),
         '',
+        ...probeBlock,
         'How to verify — verify the REAL, shipped deliverable exactly as an unaided fresh',
         'checkout (or CI run) would experience it:',
         '',
@@ -159,6 +180,14 @@ export function buildVerifyPrompt(spec) {
         '   never executed is NOT a PASS — a static match cannot prove an artifact works, only',
         '   running it can.',
         '',
+        '3b. SUBSTITUTION: a test suite (or any check) shipped by the work counts as verification',
+        "   ONLY if it exercises the real shipped code paths. If the work's own tests re-implement",
+        '   logic inline, intercept or stub the artifact behind their own server or handlers, or',
+        '   import the real module and then never call it, a green suite proves only the copy —',
+        '   NOT the deliverable. Spot-check this: pick 1-2 tested behaviors and drive the REAL',
+        '   shipped artifact directly (the real app / module / entry point). If the real artifact',
+        '   fails where the tests pass, report FAIL and name the bypass.',
+        '',
         '4. Treat the ACCEPTANCE criteria as the bar. If a command fails, or its real output',
         '   contradicts an ACCEPTANCE criterion, the work has NOT verified.',
         '',
@@ -178,11 +207,24 @@ export function buildVerifyPrompt(spec) {
         '   not load, a wrong default, a command that cannot run unaided) is a defect, not an',
         '   environment gap.',
         '',
+        '5b. EXTERNAL SERVICE STATE IS PART OF "AS SHIPPED": you may probe and read an external',
+        '   service, but you must NOT create, alter, or repair its schema or data to make the',
+        '   artifact work — no ALTER TABLE, CREATE TABLE, manual INSERT/UPDATE fixes, or ad-hoc',
+        "   DDL. You may apply only the project's OWN migration/schema files, exactly as shipped.",
+        "   If the shipped code needs schema or data that the project's own files do not create,",
+        '   that is a FAIL naming the gap. Any schema surgery you performed to reach green IS the',
+        '   defect.',
+        '',
         '6. If the spec legitimately has no runnable verification (a pure docs / config change',
         '   with nothing to build or run), validating it cleanly is a PASS.',
         '',
         '7. Do NOT edit anything to make a check pass. Report what you actually saw.',
         '',
+        'VERDICT DISCIPLINE: the verdict must follow mechanically from your findings. If ANY',
+        'acceptance criterion is unmet — a required function absent, required data not persisted,',
+        'a required behavior missing — the verdict is FAIL, even if typecheck and lint are green',
+        'and even if the gap seems minor. Never downgrade an unmet criterion to a warning note.',
+        '',
         'When you are done, output EXACTLY ONE of these as the final line:',
         "  WORK-VERIFIED: PASS              (the project's own command, run unaided, met the spec)",
         '  WORK-VERIFIED: FAIL <text>      (the shipped command failed or did not meet the spec; say what failed)',
@@ -228,9 +270,20 @@ export async function runWorkVerification(deps) {
     if (!deps.spec || deps.spec.trim().length === 0) {
         return { ok: true, reason: 'no spec to verify' };
     }
+    // Substitution probe findings feed the prompt; a probe failure must never block
+    // verification (it is an optional sharpener, the gate still runs without it).
+    let findings = [];
+    if (deps.probe) {
+        try {
+            findings = await deps.probe();
+        }
+        catch {
+            findings = [];
+        }
+    }
     let text;
     try {
-        text = await deps.runChild(VERIFY_TOOLS, buildVerifyPrompt(deps.spec), deps.signal);
+        text = await deps.runChild(VERIFY_TOOLS, buildVerifyPrompt(deps.spec, findings), deps.signal);
     }
     catch (err) {
         if (err instanceof Error && err.message === USER_CANCELLED)

package/dist/task/widget.d.ts

@@ -53,8 +53,9 @@ export interface AutoLoaderState {
      *  numbered clarify/decompose steps); 'enforce' is the per-task guideline
      *  pass and 'verify' is the per-task work-verification pass, neither of which
      *  has step numbering. 'recommend' is the read-only research that picks the
-     *  recommended action after a verify FAIL. */
-    kind?: 'planning' | 'enforce' | 'verify' | 'recommend';
+     *  recommended action after a verify FAIL. 'lint-fix' is the bounded fix pass
+     *  for a repo-health verify FAIL. */
+    kind?: 'planning' | 'enforce' | 'verify' | 'recommend' | 'lint-fix';
 }
 export declare function buildAutoLoaderLines(s: AutoLoaderState, theme?: WidgetTheme): string[];
 /**

package/dist/task/widget.js

@@ -124,7 +124,8 @@ export function buildAutoLoaderLines(s, theme) {
     let detail = s.kind === 'enforce' ? `enforcing guidelines · ${elapsed}`
         : s.kind === 'verify' ? `verifying work · ${elapsed}`
             : s.kind === 'recommend' ? `assessing the failure · ${elapsed}`
-                : `planning ${s.stepNum}/${s.stepTotal} ${s.step} · ${elapsed}`;
+                : s.kind === 'lint-fix' ? `fixing static findings · ${elapsed}`
+                    : `planning ${s.stepNum}/${s.stepTotal} ${s.step} · ${elapsed}`;
     if (s.contextUsage) {
         const ctxDetail = formatContextDetail(s.contextUsage, theme);
         if (ctxDetail)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.17.13",
+    "version": "0.17.14",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",