@mjasnikovs/pi-task 0.25.0 → 0.27.0

package/dist/task/enforce-attribution.d.ts

@@ -0,0 +1,128 @@
+/**
+ * enforce-attribution — decide whether an enforce-pass re-verify FAIL can possibly
+ * be the ENFORCE COMMIT's fault (mx5 run 18, nexttask 4).
+ *
+ * The failure class, measured. Run 18's TASK_0024 enforce commit `ee65661` was, in
+ * full, one line:
+ *
+ *     -  setApiError((usersData).error ?? 'Failed to load users')
+ *     +  setApiError(usersData.error ?? 'Failed to load users')
+ *
+ * The differential re-verify then FAILed on `MyListings.spec.tsx:186`, a Playwright
+ * CT file `Admin.tsx` cannot reach (CT bundles per story; the import graph never
+ * touches it), and the differential reverted the enforce commit anyway. The defect
+ * was real and PRE-EXISTING — `getByText('SOLD')` matched two elements because
+ * MOCK_LISTINGS already carries a sold row — and the final gate fixed it five
+ * minutes later, in the same commit that RE-MADE the identical paren change. Cost:
+ * one correct change destroyed, one permanent false verify-FAIL debt written
+ * against work that was fine, and the change re-made anyway.
+ *
+ * The mechanism was not broken; it was asked the wrong question. The root-cause
+ * channel (root-cause-repair.ts) attributed against `scope: 'committed'` — the
+ * TASK's own commit, which touched `MyListings.tsx` — concluded "this task touched
+ * the file", and fell through to the conservative revert. But at THIS seam the
+ * differential is deciding whether to discard the ENFORCE COMMIT. The causal
+ * question is therefore *"could the enforce diff have caused this?"*, never *"could
+ * the task have?"*: reverting the enforce commit can only ever repair damage the
+ * enforce commit did.
+ *
+ * So the filter here is mechanical and one-sided:
+ *
+ *   - the files the FAIL text NAMES are extracted (paths AND bare basenames — run
+ *     18's reason named `MyListings.spec.tsx:186`, which carries no separator and
+ *     is invisible to root-cause-repair.ts's path-token regex, a second reason
+ *     that incident could not be attributed);
+ *   - each is compared against the enforce commit's own file set, by path suffix
+ *     and by RELATED STEM (`Admin.tsx` ~ `Admin.spec.tsx` ~ `Admin.stories.tsx`),
+ *     so a regression in a touched file's own test still counts as overlap;
+ *   - DISJOINT ⇒ keep the edits and route the defect. Anything else — an unknown
+ *     enforce diff, a FAIL text naming no file at all, any overlap — reverts,
+ *     which is exactly the pre-existing behaviour. Never keep on ignorance.
+ *
+ * Keeping the edits must not mean losing the finding: the caller still records the
+ * debt and still queues the repair. Losing the finding was mx5 run 5's mistake.
+ *
+ * MEASURED COVERAGE, and it is the honest weakness of this filter. Live, 40 trials
+ * against the run-18 tree with a real verify child
+ * (`scripts/live-enforce-attribution-ab.ts`):
+ *
+ *   reachable arm (the enforce edit itself breaks `Admin.tsx`, ground truth REVERT)
+ *     20/20 FAILs named a resolvable file, 20/20 decided correctly — tsc prints the
+ *     path, so the regression case is fully covered.
+ *   disjoint arm (a deterministic failure in `MyListings.spec.tsx`, ground truth KEEP)
+ *     only 9/20 FAILs named a file at all. The other 11 named the UNIT — "The
+ *     MyListings component test \"edit link navigates…\" fails … expects 4 Edit links"
+ *     — with no path and no `.tsx` anywhere. Those 11 fall through to the revert.
+ *
+ * So this fires on roughly half of live disjoint failures and on the recorded run-18
+ * verdict (which did name `MyListings.spec.tsx:186`), and it was NEVER wrong: 29 of
+ * 29 extractable decisions matched ground truth across both arms. The arm-level
+ * verdict is still FAIL against the pre-registered ≥80%-extractable bar, and the
+ * shipped rule is deliberately the conservative half of that trade: a miss costs
+ * exactly the behaviour that shipped before, while a false KEEP would ship a real
+ * regression. A stem-widened extractor (accept a bare identifier matching a tracked
+ * file's stem) reaches 40/40 with 0 errors in the same data and is NOT wired — see
+ * VALIDATION-DEBT.md, it resolves prose nouns to files and its FP mode was never
+ * exercised.
+ */
+/**
+ * The comparable stem of a file name: the base name with its extension and any
+ * companion suffix removed, lowercased. `src/client/pages/Admin.tsx`,
+ * `Admin.spec.tsx` and `Admin.stories.tsx` all reduce to `admin`, which is what
+ * makes "the enforce diff broke that file's own test" count as an overlap rather
+ * than a disjoint (and therefore keepable) failure.
+ */
+export declare function fileStem(p: string): string;
+/**
+ * Every file a FAIL text names, de-duplicated, in first-seen order. Both shapes
+ * count: `src/server/routes/photos.ts` (path) and `MyListings.spec.tsx:186` (bare
+ * name plus a line number). An empty result is the signal that NOTHING can be
+ * attributed — the caller must then revert, never keep.
+ */
+export declare function extractFailingFiles(text: string): string[];
+/**
+ * Resolve a named file to a tracked repo path when the repo file list makes it
+ * unambiguous. `MyListings.spec.tsx` → `src/client/pages/MyListings.spec.tsx`, so
+ * the KEEP path can ask provenance about it and queue a real repair task. An
+ * ambiguous name (two tracked files share it) resolves to null: guessing which one
+ * the failure meant would put a wrong file in a repair task's title.
+ */
+export declare function resolveNamedFile(named: string, repoFiles: string[] | null): string | null;
+export interface EnforceAttributionInput {
+    /** The differential re-verify's FAIL reason, verbatim. */
+    failReason: string;
+    /**
+     * Repo-relative paths the ENFORCE COMMIT changed. `null` means unknown (git
+     * unavailable) and forces the pre-existing revert — inconclusive is never
+     * evidence for keeping a possible regression.
+     */
+    enforceTouched: string[] | null;
+    /** Tracked repo paths, for resolving bare file names. Optional; absent only
+     *  costs resolution, never changes the keep/revert verdict. */
+    repoFiles?: string[] | null;
+}
+/** Why the differential decided as it did — verbatim into the gate trail. */
+export type EnforceAttributionWhy = 'enforce-diff-unknown' | 'no-file-named' | 'named-file-in-enforce-diff' | 'disjoint-from-enforce-diff';
+export interface EnforceAttribution {
+    /** `keep` only on positive mechanical evidence that enforce cannot be at fault. */
+    verdict: 'keep' | 'revert';
+    why: EnforceAttributionWhy;
+    /** Files the FAIL text named (resolved to repo paths where unambiguous). */
+    named: string[];
+    /** The enforce commit's own file set, as compared against (for the trail). */
+    enforceDiff: string[];
+    /** On `revert`: the named file that overlaps the enforce diff. */
+    overlap?: {
+        named: string;
+        enforce: string;
+    };
+    /** On `keep`: the file to blame the defect on (the first named file). */
+    file?: string;
+}
+/**
+ * Could the ENFORCE COMMIT have caused this FAIL? `keep` iff the failure names at
+ * least one file and NO named file is the enforce diff's, or a companion of one.
+ * Every unknown returns `revert`, i.e. exactly the behaviour that shipped before
+ * this filter existed.
+ */
+export declare function attributeEnforceFailure(input: EnforceAttributionInput): EnforceAttribution;

package/dist/task/enforce-attribution.js

@@ -0,0 +1,213 @@
+/**
+ * enforce-attribution — decide whether an enforce-pass re-verify FAIL can possibly
+ * be the ENFORCE COMMIT's fault (mx5 run 18, nexttask 4).
+ *
+ * The failure class, measured. Run 18's TASK_0024 enforce commit `ee65661` was, in
+ * full, one line:
+ *
+ *     -  setApiError((usersData).error ?? 'Failed to load users')
+ *     +  setApiError(usersData.error ?? 'Failed to load users')
+ *
+ * The differential re-verify then FAILed on `MyListings.spec.tsx:186`, a Playwright
+ * CT file `Admin.tsx` cannot reach (CT bundles per story; the import graph never
+ * touches it), and the differential reverted the enforce commit anyway. The defect
+ * was real and PRE-EXISTING — `getByText('SOLD')` matched two elements because
+ * MOCK_LISTINGS already carries a sold row — and the final gate fixed it five
+ * minutes later, in the same commit that RE-MADE the identical paren change. Cost:
+ * one correct change destroyed, one permanent false verify-FAIL debt written
+ * against work that was fine, and the change re-made anyway.
+ *
+ * The mechanism was not broken; it was asked the wrong question. The root-cause
+ * channel (root-cause-repair.ts) attributed against `scope: 'committed'` — the
+ * TASK's own commit, which touched `MyListings.tsx` — concluded "this task touched
+ * the file", and fell through to the conservative revert. But at THIS seam the
+ * differential is deciding whether to discard the ENFORCE COMMIT. The causal
+ * question is therefore *"could the enforce diff have caused this?"*, never *"could
+ * the task have?"*: reverting the enforce commit can only ever repair damage the
+ * enforce commit did.
+ *
+ * So the filter here is mechanical and one-sided:
+ *
+ *   - the files the FAIL text NAMES are extracted (paths AND bare basenames — run
+ *     18's reason named `MyListings.spec.tsx:186`, which carries no separator and
+ *     is invisible to root-cause-repair.ts's path-token regex, a second reason
+ *     that incident could not be attributed);
+ *   - each is compared against the enforce commit's own file set, by path suffix
+ *     and by RELATED STEM (`Admin.tsx` ~ `Admin.spec.tsx` ~ `Admin.stories.tsx`),
+ *     so a regression in a touched file's own test still counts as overlap;
+ *   - DISJOINT ⇒ keep the edits and route the defect. Anything else — an unknown
+ *     enforce diff, a FAIL text naming no file at all, any overlap — reverts,
+ *     which is exactly the pre-existing behaviour. Never keep on ignorance.
+ *
+ * Keeping the edits must not mean losing the finding: the caller still records the
+ * debt and still queues the repair. Losing the finding was mx5 run 5's mistake.
+ *
+ * MEASURED COVERAGE, and it is the honest weakness of this filter. Live, 40 trials
+ * against the run-18 tree with a real verify child
+ * (`scripts/live-enforce-attribution-ab.ts`):
+ *
+ *   reachable arm (the enforce edit itself breaks `Admin.tsx`, ground truth REVERT)
+ *     20/20 FAILs named a resolvable file, 20/20 decided correctly — tsc prints the
+ *     path, so the regression case is fully covered.
+ *   disjoint arm (a deterministic failure in `MyListings.spec.tsx`, ground truth KEEP)
+ *     only 9/20 FAILs named a file at all. The other 11 named the UNIT — "The
+ *     MyListings component test \"edit link navigates…\" fails … expects 4 Edit links"
+ *     — with no path and no `.tsx` anywhere. Those 11 fall through to the revert.
+ *
+ * So this fires on roughly half of live disjoint failures and on the recorded run-18
+ * verdict (which did name `MyListings.spec.tsx:186`), and it was NEVER wrong: 29 of
+ * 29 extractable decisions matched ground truth across both arms. The arm-level
+ * verdict is still FAIL against the pre-registered ≥80%-extractable bar, and the
+ * shipped rule is deliberately the conservative half of that trade: a miss costs
+ * exactly the behaviour that shipped before, while a false KEEP would ship a real
+ * regression. A stem-widened extractor (accept a bare identifier matching a tracked
+ * file's stem) reaches 40/40 with 0 errors in the same data and is NOT wired — see
+ * VALIDATION-DEBT.md, it resolves prose nouns to files and its FP mode was never
+ * exercised.
+ */
+/** A path-like token: at least one separator, ending in a file name. */
+const PATH_TOKEN_RE = /(?:[\w.@~-]+\/)+[\w.@-]+\.\w+/g;
+/**
+ * A bare file name with a code-ish extension. Deliberately extension-gated: an
+ * ungated `\w+\.\w+` matches prose ("e.g.", "v1.2"), object access (`usersData.error`
+ * — which run 18's own enforce diff contains) and assertion chains
+ * (`toBeVisible()`), and every one of those would be a phantom "named file".
+ */
+const BARE_FILE_RE = /\b[\w@-]+(?:\.[\w@-]+)*\.(?:tsx?|jsx?|mtsx?|ctsx?|mjs|cjs|vue|svelte|astro|py|go|rs|rb|java|kt|kts|cs|php|swift|scala|c|h|cc|cpp|hpp|css|scss|sass|less|html?|json|jsonc|ya?ml|toml|sql|sh|bash|zsh|md|mdx|prisma|graphql|gql|proto|lock)\b/g;
+/** Line/column suffixes and decoration a reason wraps a file name in. */
+const TRAILING_POSITION_RE = /:(\d+)(?::(\d+))?$/;
+/** Suffixes that make a file a sibling of another (test/story/type companions). */
+const COMPANION_SUFFIXES = ['.spec', '.test', '.stories', '.story', '.d', '.min'];
+/** A pathological reason cannot make this scan unbounded. */
+const MAX_NAMED = 24;
+/** Strip `./`, leading slashes and surrounding whitespace. */
+function normalisePath(p) {
+    return p.replace(/^\.\//, '').replace(/^\/+/, '').trim();
+}
+/** The last path segment of a repo-relative path. */
+function basename(p) {
+    const i = p.lastIndexOf('/');
+    return i < 0 ? p : p.slice(i + 1);
+}
+/**
+ * The comparable stem of a file name: the base name with its extension and any
+ * companion suffix removed, lowercased. `src/client/pages/Admin.tsx`,
+ * `Admin.spec.tsx` and `Admin.stories.tsx` all reduce to `admin`, which is what
+ * makes "the enforce diff broke that file's own test" count as an overlap rather
+ * than a disjoint (and therefore keepable) failure.
+ */
+export function fileStem(p) {
+    let name = basename(normalisePath(p));
+    const dot = name.lastIndexOf('.');
+    if (dot > 0)
+        name = name.slice(0, dot);
+    for (const suffix of COMPANION_SUFFIXES) {
+        if (name.toLowerCase().endsWith(suffix)) {
+            name = name.slice(0, name.length - suffix.length);
+            break;
+        }
+    }
+    return name.toLowerCase();
+}
+/**
+ * Every file a FAIL text names, de-duplicated, in first-seen order. Both shapes
+ * count: `src/server/routes/photos.ts` (path) and `MyListings.spec.tsx:186` (bare
+ * name plus a line number). An empty result is the signal that NOTHING can be
+ * attributed — the caller must then revert, never keep.
+ */
+export function extractFailingFiles(text) {
+    if (text.trim().length === 0)
+        return [];
+    const out = [];
+    const seen = new Set();
+    const add = (raw) => {
+        const cleaned = normalisePath(raw.replace(TRAILING_POSITION_RE, ''));
+        if (cleaned.length === 0)
+            return;
+        const key = cleaned.toLowerCase();
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        if (out.length < MAX_NAMED)
+            out.push(cleaned);
+    };
+    // Paths first so `src/a/B.ts` is recorded as the path, not as the bare `B.ts`
+    // its own tail also matches.
+    const covered = [];
+    for (const m of text.matchAll(PATH_TOKEN_RE)) {
+        covered.push([m.index, m.index + m[0].length]);
+        add(withPosition(text, m.index + m[0].length, m[0]));
+    }
+    for (const m of text.matchAll(BARE_FILE_RE)) {
+        const start = m.index;
+        if (covered.some(([s, e]) => start >= s && start < e))
+            continue;
+        add(withPosition(text, start + m[0].length, m[0]));
+    }
+    return out;
+}
+/** Re-attach a `:line[:col]` suffix that follows a match, so it can be stripped
+ *  uniformly (and so `a.ts:1` and `a.ts` collapse to one named file). */
+function withPosition(text, end, token) {
+    const m = /^:\d+(?::\d+)?/.exec(text.slice(end));
+    return m ? token + m[0] : token;
+}
+/** Two repo-relative paths that denote the same file (suffix-compared). */
+function samePath(a, b) {
+    const x = normalisePath(a).toLowerCase();
+    const y = normalisePath(b).toLowerCase();
+    return x === y || x.endsWith(`/${y}`) || y.endsWith(`/${x}`);
+}
+/**
+ * Resolve a named file to a tracked repo path when the repo file list makes it
+ * unambiguous. `MyListings.spec.tsx` → `src/client/pages/MyListings.spec.tsx`, so
+ * the KEEP path can ask provenance about it and queue a real repair task. An
+ * ambiguous name (two tracked files share it) resolves to null: guessing which one
+ * the failure meant would put a wrong file in a repair task's title.
+ */
+export function resolveNamedFile(named, repoFiles) {
+    if (!repoFiles || repoFiles.length === 0)
+        return null;
+    const matches = repoFiles.filter(f => samePath(f, named));
+    if (matches.length === 1)
+        return normalisePath(matches[0]);
+    // Exact-path hit wins over the suffix fan-out (a repo may track both
+    // `a/x.ts` and `b/a/x.ts`).
+    const exact = repoFiles.filter(f => normalisePath(f).toLowerCase() === normalisePath(named).toLowerCase());
+    return exact.length === 1 ? normalisePath(exact[0]) : null;
+}
+/**
+ * Could the ENFORCE COMMIT have caused this FAIL? `keep` iff the failure names at
+ * least one file and NO named file is the enforce diff's, or a companion of one.
+ * Every unknown returns `revert`, i.e. exactly the behaviour that shipped before
+ * this filter existed.
+ */
+export function attributeEnforceFailure(input) {
+    const enforce = (input.enforceTouched ?? []).map(normalisePath).filter(f => f.length > 0);
+    if (input.enforceTouched === null || enforce.length === 0) {
+        return { verdict: 'revert', why: 'enforce-diff-unknown', named: [], enforceDiff: enforce };
+    }
+    const raw = extractFailingFiles(input.failReason);
+    const named = raw.map(n => resolveNamedFile(n, input.repoFiles ?? null) ?? n);
+    if (named.length === 0)
+        return { verdict: 'revert', why: 'no-file-named', named, enforceDiff: enforce };
+    for (const n of named) {
+        const hit = enforce.find(e => samePath(e, n) || fileStem(e) === fileStem(n));
+        if (hit) {
+            return {
+                verdict: 'revert',
+                why: 'named-file-in-enforce-diff',
+                named,
+                enforceDiff: enforce,
+                overlap: { named: n, enforce: hit }
+            };
+        }
+    }
+    return {
+        verdict: 'keep',
+        why: 'disjoint-from-enforce-diff',
+        named,
+        enforceDiff: enforce,
+        file: named[0]
+    };
+}

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

@@ -305,7 +305,9 @@ export declare function preferredDeclaredPort(cwd: string): Promise<number | nul
  * needs no socket probe, so run 14's original true positive (a `--hot` runtime
  * pinning a crashed app) stays reportable wherever the tooling exists.
  *
- * Env-gap contract as everywhere: spawn error (ENOENT) or exit 127 → skip.
+ * Env-gap contract as everywhere: spawn error (ENOENT) or a command-not-found
+ * inside the chain (exit 127, or the runner's own wording where the platform
+ * reports it that way — see isCommandNotFound) → skip.
  */
 export declare function runBootCheck(cwd: string, [bin, args]: HealthCommand, graceMs?: number, opts?: {
     expectServer?: boolean;

package/dist/task/final-gate.js

@@ -55,7 +55,7 @@ import { readDeclaredScripts, missingDeclaredScripts, runnableDeclaredScripts }
 import { readEnvNotes, parseEnvNotes, isExcuseNote } from './env-notes.js';
 import { runRenderCheck } from './render-check.js';
 import { collectProjectEnv, pinnedLocalPort, runDeepRenderCheck } from './deep-render-check.js';
-import { resolveRunner, runnerEnv } from './runner-resolve.js';
+import { resolveRunner, runnerEnv, isCommandNotFound } from './runner-resolve.js';
 import { taskThatIntroduced } from './task-provenance.js';
 import { findDanglingArtifacts, danglingGateFailureText } from './artifact-closure.js';
 import { findMissingServeEntry, serveEntryGateFailureText } from './serve-entry.js';
@@ -693,7 +693,9 @@ function holderIsOurs(command, boot) {
  * needs no socket probe, so run 14's original true positive (a `--hot` runtime
  * pinning a crashed app) stays reportable wherever the tooling exists.
  *
- * Env-gap contract as everywhere: spawn error (ENOENT) or exit 127 → skip.
+ * Env-gap contract as everywhere: spawn error (ENOENT) or a command-not-found
+ * inside the chain (exit 127, or the runner's own wording where the platform
+ * reports it that way — see isCommandNotFound) → skip.
  */
 export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}) {
     const expectServer = (opts.expectServer ?? false) && process.platform !== 'win32';
@@ -881,7 +883,11 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
                 }
                 return settle({ outcome: 'pass' });
             }
-            if (status === 127 || (status === null && signal === null)) {
+            // Command-not-found inside the boot chain — 127 on a posix shell, or
+            // the runner's own wording where it isn't (Windows bun exits 1). Either
+            // way the boot never RAN, so it is an environment gap, not an app fault.
+            if (isCommandNotFound(status, `${out}\n${err}`)
+                || (status === null && signal === null)) {
                 return settle({ outcome: 'skip' });
             }
             const what = status !== null ? `exited ${status}` : `was killed by ${signal}`;
@@ -967,10 +973,12 @@ function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe) {
     });
     if (r.error)
         return { outcome: 'skip', spawnFailed: true };
-    if (r.status === null || r.status === 127)
+    if (r.status === null)
         return { outcome: 'skip', spawnFailed: false };
     if (r.status !== 0) {
         const output = `${r.stdout ?? ''}\n${r.stderr ?? ''}`;
+        if (isCommandNotFound(r.status, output))
+            return { outcome: 'skip', spawnFailed: false };
         if (ENV_GAP_OUTPUT_RE.test(output))
             return { outcome: 'skip', spawnFailed: false };
         if (extraGapRe?.test(output))

package/dist/task/gate-deps.js

@@ -22,7 +22,7 @@ import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
 import { readEnvNotes, appendEnvNotes } from './env-notes.js';
 import { readContracts } from './contracts.js';
-import { recordAcceptDebt, recordEnforceRevertDebt, recordFrozenBlockedDebt, recordCrossTaskDeletionDebt, recordYoloAcceptDebt, recordRootCauseDebt } from './accept-debt.js';
+import { recordAcceptDebt, recordEnforceKeptDebt, recordEnforceRevertDebt, recordFrozenBlockedDebt, recordCrossTaskDeletionDebt, recordYoloAcceptDebt, recordRootCauseDebt } from './accept-debt.js';
 import { recordRepairCandidate } from './root-cause-repair.js';
 import { runRepoHealthCheck } from './repo-health-check.js';
 import { runFinalIntegrationGate, discoverGateCommandLabels } from './final-gate.js';
@@ -469,6 +469,10 @@ export function buildGateDeps(params) {
         recordAcceptDebt: (cwd2, taskId, reason) => recordAcceptDebt(cwd2, taskId, reason),
         recordYoloAcceptDebt: (cwd2, taskId, reason) => recordYoloAcceptDebt(cwd2, taskId, reason),
         recordEnforceRevertDebt: (cwd2, taskId, reason) => recordEnforceRevertDebt(cwd2, taskId, reason),
+        // Same ledger, the KEPT disposition (mx5 run 18 / nexttask 4): the enforce
+        // re-verify FAILed on a check the enforce diff cannot reach, so the edits
+        // stayed and only the defect was recorded.
+        recordEnforceKeptDebt: (cwd2, taskId, reason) => recordEnforceKeptDebt(cwd2, taskId, reason),
         // Durable cross-task-contradiction ledger (PROMPT 1 layer B): a repo-health
         // FAIL whose only fix is an edit to a path this task's spec froze — recorded
         // when the gate loop routes it to the picker, re-checked by the final gate.
@@ -485,6 +489,23 @@ export function buildGateDeps(params) {
         recordRepairCandidate: (cwd2, candidate) => recordRepairCandidate(cwd2, candidate),
         // file → introducing task, the provenance half of the discriminator.
         introducedBy: (cwd2, rel) => Promise.resolve(taskThatIntroduced(cwd2, rel)),
+        // Tracked paths, used only to resolve a bare file name a FAIL text names
+        // (`MyListings.spec.tsx:186`) to its repo path. A git fault returns null,
+        // which costs resolution and nothing else.
+        repoFiles: async (cwd2) => {
+            try {
+                const r = await git(cwd2, ['ls-files'], signal);
+                if (r.exitCode !== 0)
+                    return null;
+                return r.stdout
+                    .split('\n')
+                    .map(l => l.trim())
+                    .filter(l => l.length > 0);
+            }
+            catch {
+                return null;
+            }
+        },
         // The authorship half: which files THIS task's work touched. `worktree` is
         // the pre-commit verify site (uncommitted changes); `committed` is the
         // post-commit enforce site, where the task snapshot and the ENFORCE commit
@@ -499,7 +520,18 @@ export function buildGateDeps(params) {
                     const c = parseTreeChanges(r.stdout);
                     return [...c.modified, ...c.added, ...c.deleted];
                 }
-                const r = await git(cwd2, ['log', '-n', '2', '--name-only', '--format=', 'HEAD'], signal);
+                // `enforce-commit` is HEAD ALONE — at the enforce differential HEAD is
+                // the ENFORCE commit, and that commit's own diff is the only file set
+                // that can answer "could reverting this repair the failure?" (mx5 run
+                // 18 / nexttask 4).
+                const r = await git(cwd2, [
+                    'log',
+                    '-n',
+                    scope === 'enforce-commit' ? '1' : '2',
+                    '--name-only',
+                    '--format=',
+                    'HEAD'
+                ], signal);
                 if (r.exitCode !== 0)
                     return null;
                 return r.stdout

package/dist/task/repo-health-check.js

@@ -32,7 +32,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
-import { resolveRunner, runnerEnv } from './runner-resolve.js';
+import { resolveRunner, runnerEnv, isCommandNotFound } from './runner-resolve.js';
 /** How much of a failing command's output to keep — bounded so a wedged tool that
  *  spews megabytes cannot bloat the trail. stderr leads (a crash trace lives there). */
 const HEALTH_OUTPUT_MAX_LINES = 40;
@@ -142,10 +142,12 @@ export function runRepoHealthCheck(cwd, timeoutMs = 600_000) {
         // Tool missing (ENOENT) or killed by timeout → cannot conclude; skip it.
         if (r.error || r.status === null)
             continue;
-        // Exit 127 = "command not found" INSIDE the script chain (e.g. `bun run lint`
-        // before node_modules exists — seen live failing TASK_0001's first verify).
-        // Same environment gap as ENOENT, just surfaced through the runner's shell.
-        if (r.status === 127)
+        // "Command not found" INSIDE the script chain (e.g. `bun run lint` before
+        // node_modules exists — seen live failing TASK_0001's first verify). Same
+        // environment gap as ENOENT, just surfaced through the runner's shell —
+        // as exit 127 where a posix shell ran it, else by the runner's own wording
+        // (Windows bun reports the miss itself and exits 1).
+        if (isCommandNotFound(r.status, `${r.stdout ?? ''}\n${r.stderr ?? ''}`))
             continue;
         if (r.status !== 0) {
             return {

package/dist/task/runner-resolve.d.ts

@@ -20,6 +20,31 @@ export declare function resolveRunner(bin: string, opts?: {
     probe?: (bin: string) => boolean;
     env?: NodeJS.ProcessEnv;
 }): ResolvedRunner;
+/**
+ * Output shapes a RUNNER emits when the command inside a script chain does not
+ * exist, on platforms where that is not reported as exit 127.
+ *
+ * 127 is a POSIX-SHELL convention: on Linux/macOS bun hands the script to
+ * /bin/sh, the shell prints `…: command not found` and exits 127, and the whole
+ * env-gap contract keys off that number. On Windows there is no such shell —
+ * bun runs the script in its own built-in shell, which reports the miss itself
+ * (`bun: command not found: X`) and exits **1**, indistinguishable by status
+ * alone from a real code fault. cmd.exe (9009) and PowerShell have their own
+ * wording. Recognising the shape restores one env-gap contract on all three.
+ *
+ * Deliberately narrow: only wordings a RUNNER/SHELL produces, never the bare
+ * phrase. A suite that prints "command not found" inside a failing assertion is
+ * a real FAIL and must stay one — the posix shape already travels as 127.
+ */
+export declare const COMMAND_NOT_FOUND_OUTPUT_RE: RegExp;
+/**
+ * Did this command fail because the thing it tried to run does not exist here,
+ * rather than because the code is wrong? Exit 127 (POSIX shell) or 9009
+ * (cmd.exe) say so outright; anything else needs the runner's own wording (see
+ * COMMAND_NOT_FOUND_OUTPUT_RE) — a Windows `bun run dev` on a missing binary
+ * exits 1. Callers treat a true here as an environment gap → skip, never FAIL.
+ */
+export declare function isCommandNotFound(status: number | null, output?: string): boolean;
 /**
  * The env a spawn site should pass so the resolved runner's script chain can
  * re-invoke it: base env with the runner's directory prepended to PATH. With no

package/dist/task/runner-resolve.js

@@ -83,6 +83,37 @@ export function resolveRunner(bin, opts = {}) {
     cache.set(bin, resolved);
     return resolved;
 }
+/**
+ * Output shapes a RUNNER emits when the command inside a script chain does not
+ * exist, on platforms where that is not reported as exit 127.
+ *
+ * 127 is a POSIX-SHELL convention: on Linux/macOS bun hands the script to
+ * /bin/sh, the shell prints `…: command not found` and exits 127, and the whole
+ * env-gap contract keys off that number. On Windows there is no such shell —
+ * bun runs the script in its own built-in shell, which reports the miss itself
+ * (`bun: command not found: X`) and exits **1**, indistinguishable by status
+ * alone from a real code fault. cmd.exe (9009) and PowerShell have their own
+ * wording. Recognising the shape restores one env-gap contract on all three.
+ *
+ * Deliberately narrow: only wordings a RUNNER/SHELL produces, never the bare
+ * phrase. A suite that prints "command not found" inside a failing assertion is
+ * a real FAIL and must stay one — the posix shape already travels as 127.
+ */
+export const COMMAND_NOT_FOUND_OUTPUT_RE = /\b(?:bun|npm|pnpm|yarn|node|deno): command not found:|is not recognized as an internal or external command|is not recognized as the name of a cmdlet/i;
+/**
+ * Did this command fail because the thing it tried to run does not exist here,
+ * rather than because the code is wrong? Exit 127 (POSIX shell) or 9009
+ * (cmd.exe) say so outright; anything else needs the runner's own wording (see
+ * COMMAND_NOT_FOUND_OUTPUT_RE) — a Windows `bun run dev` on a missing binary
+ * exits 1. Callers treat a true here as an environment gap → skip, never FAIL.
+ */
+export function isCommandNotFound(status, output = '') {
+    if (status === 127 || status === 9009)
+        return true;
+    if (status === null || status === 0)
+        return false;
+    return COMMAND_NOT_FOUND_OUTPUT_RE.test(output);
+}
 /**
  * The env a spawn site should pass so the resolved runner's script chain can
  * re-invoke it: base env with the runner's directory prepended to PATH. With no

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

@@ -170,6 +170,13 @@ export interface GateDeps {
      * so the final gate must re-check and surface it. Best-effort; absent in tests.
      */
     recordRootCauseDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
+    /**
+     * Record a durable ENFORCE-KEPT debt (mx5 run 18 / nexttask 4): the enforce
+     * re-verify FAILED but the failing check names only files the ENFORCE COMMIT
+     * does not touch, so the edits were KEPT. The defect is still real and still in
+     * the shipped tree — keeping the work must not lose the finding.
+     */
+    recordEnforceKeptDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
     /**
      * Queue a scoped repair task for a root-caused defect. The gate DETECTS the
      * cause; only the /task-auto loop may mutate the plan, so the two are decoupled
@@ -184,12 +191,22 @@ export interface GateDeps {
      * this task's own fault, and only a file it never touched can be somebody
      * else's pre-existing bug. `worktree` = uncommitted changes (the pre-commit
      * verify site); `committed` = the files the task snapshot + the ENFORCE commit
-     * changed (the post-commit enforce site). `null` means UNKNOWN (git
-     * unavailable) and stands the whole channel down — inconclusive is never
-     * evidence, so an unreadable tree can only cost a repair task, never spawn a
-     * wrong one or wrongly keep a regression.
+     * changed (the post-commit enforce site); `enforce-commit` = the ENFORCE COMMIT
+     * ALONE, which is the only correct authorship question at the enforce
+     * differential (mx5 run 18 / nexttask 4 — that differential decides whether to
+     * discard the enforce commit, so what the TASK touched is irrelevant to it).
+     * `null` means UNKNOWN (git unavailable) and stands the whole channel down —
+     * inconclusive is never evidence, so an unreadable tree can only cost a repair
+     * task, never spawn a wrong one or wrongly keep a regression.
+     */
+    touchedFiles?: (cwd: string, scope: 'worktree' | 'committed' | 'enforce-commit') => Promise<string[] | null>;
+    /**
+     * Every path git tracks in the repo — used ONLY to resolve a bare file name a
+     * FAIL text names (`MyListings.spec.tsx:186`) to its repo path, so the defect
+     * can be attributed and a repair queued for it. Absent/null costs resolution,
+     * never changes a keep/revert verdict.
      */
-    touchedFiles?: (cwd: string, scope: 'worktree' | 'committed') => Promise<string[] | null>;
+    repoFiles?: (cwd: string) => Promise<string[] | null>;
     /** The task whose commit INTRODUCED a file (task-provenance.ts). Null for a
      *  file predating the run or any git error → unknown provenance. */
     introducedBy?: (cwd: string, rel: string) => Promise<string | null>;