@mjasnikovs/pi-task 0.26.0 → 0.27.0

package/dist/task/accept-debt.d.ts

@@ -6,6 +6,12 @@
  *     server entry point … the Hono server cannot be started"), so the terminal defect
  *     was FOUND and then erased by the very mechanism that found it. Persisted here so
  *     the final gate re-checks and surfaces it instead of letting it die with the revert.
+ *   - 'enforce-kept'   — the same enforce re-verify FAIL, but the failing check named
+ *     only files the ENFORCE COMMIT does not touch, so reverting that commit could not
+ *     possibly repair it (mx5 run 18 TASK_0024: a one-line paren removal in `Admin.tsx`
+ *     was reverted over a `MyListings.spec.tsx` CT failure it cannot reach, and the
+ *     final gate re-made the identical change 5 minutes later). The edits are KEPT and
+ *     the defect is recorded here — keeping the work must never mean losing the finding.
  *   - 'frozen-blocked' — a repo-health verify-FAIL whose only fix is an edit to a path
  *     THIS task's spec froze (mx5 run 12: `bun run lint` permanently red because the
  *     created files need a tsconfig registration every spec forbids). Cross-task
@@ -43,7 +49,7 @@
  *     (root-cause-repair.ts). Before this class existed the ledger recorded the same
  *     root cause twice and nothing ever scheduled a fix, so it survived ~24h.
  */
-export type DebtOrigin = 'accepted' | 'enforce-revert' | 'frozen-blocked' | 'cross-task-deletion' | 'yolo-accepted' | 'final-gate' | 'root-cause';
+export type DebtOrigin = 'accepted' | 'enforce-revert' | 'enforce-kept' | 'frozen-blocked' | 'cross-task-deletion' | 'yolo-accepted' | 'final-gate' | 'root-cause';
 /** One recorded defect: the task, why its VERIFY failed, and how it was recorded. */
 export interface AcceptDebt {
     taskId: string;
@@ -82,6 +88,14 @@ export declare function recordAcceptDebt(cwd: string, taskId: string, reason: st
  * rather than letting it die with the revert.
  */
 export declare function recordEnforceRevertDebt(cwd: string, taskId: string, reason: string): Promise<void>;
+/**
+ * Record an ENFORCE-KEPT debt (mx5 run 18 / nexttask 4): an enforce re-verify FAILED
+ * on a check whose named files are DISJOINT from the enforce commit's own diff, so
+ * the edits were kept — discarding them could not have repaired a failure they cannot
+ * reach. The defect is real and still in the shipped tree, so it is recorded with the
+ * same durability as an enforce-revert; only the disposition of the edits differs.
+ */
+export declare function recordEnforceKeptDebt(cwd: string, taskId: string, reason: string): Promise<void>;
 /**
  * Record a FROZEN-BLOCKED debt (mx5 run 12 / PROMPT 1 layer B): a repo-health FAIL
  * whose static findings can only be fixed by editing a path this task's spec froze —

package/dist/task/accept-debt.js

@@ -75,6 +75,7 @@ export function parseAcceptDebts(raw) {
             taskId: parts[0].trim(),
             reason: parts[1].trim(),
             ...((origin === 'enforce-revert'
+                || origin === 'enforce-kept'
                 || origin === 'frozen-blocked'
                 || origin === 'cross-task-deletion'
                 || origin === 'yolo-accepted'
@@ -147,6 +148,20 @@ export async function recordEnforceRevertDebt(cwd, taskId, reason) {
         origin: 'enforce-revert'
     });
 }
+/**
+ * Record an ENFORCE-KEPT debt (mx5 run 18 / nexttask 4): an enforce re-verify FAILED
+ * on a check whose named files are DISJOINT from the enforce commit's own diff, so
+ * the edits were kept — discarding them could not have repaired a failure they cannot
+ * reach. The defect is real and still in the shipped tree, so it is recorded with the
+ * same durability as an enforce-revert; only the disposition of the edits differs.
+ */
+export async function recordEnforceKeptDebt(cwd, taskId, reason) {
+    await appendDebt(cwd, {
+        taskId: taskId.trim(),
+        reason: normaliseReason(reason),
+        origin: 'enforce-kept'
+    });
+}
 /**
  * Record a FROZEN-BLOCKED debt (mx5 run 12 / PROMPT 1 layer B): a repo-health FAIL
  * whose static findings can only be fixed by editing a path this task's spec froze —
@@ -364,6 +379,9 @@ export function describeDebt(d) {
     if (d.origin === 'enforce-revert') {
         return 'enforce re-verify FAILED then the edits were reverted (defect indicts the ORIGINAL work, still shipped)';
     }
+    if (d.origin === 'enforce-kept') {
+        return 'enforce re-verify FAILED on a check the enforce diff cannot reach — the guideline edits were KEPT (reverting them could not fix it) and the defect indicts the ORIGINAL work, still shipped';
+    }
     if (d.origin === 'frozen-blocked') {
         return 'repo health blocked by a spec-frozen path (cross-task contradiction — no task may perform the fixing edit)';
     }

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>;

package/dist/task/task-gates.js

@@ -1,7 +1,8 @@
 import { resolutionOptions, classifyResolutionAnswer } from './verify-resolution.js';
 import { SessionUI } from '../remote/bridge.js';
 import { isYoloMode, yoloVerifyResolution, YOLO_STAMP } from './yolo.js';
-import { findRepairCandidate } from './root-cause-repair.js';
+import { extractFailingCommand, findRepairCandidate, summariseDefect } from './root-cause-repair.js';
+import { attributeEnforceFailure } from './enforce-attribution.js';
 /**
  * How many times a verify FAIL may be auto-fixed UNATTENDED (the research
  * recommended AUTOFIX, so pi re-runs the impl turn without prompting) before the
@@ -455,8 +456,8 @@ export async function runGatesForTask(ctxIn, deps, p) {
                 const afterReason = after.reason ?? 'enforce re-verify failed';
                 // PRE-EXISTING-CAUSE KEEP PATH (mx5 run 14 item 5b). Both of run
                 // 14's enforce-reverts were this shape: the re-verify FAILed on
-                // TASK_0007's `test/teardown.ts` TRUNCATE bug — a file neither the
-                // task's work nor the enforce pass touched — and the differential
+                // TASK_0007's `test/teardown.ts` TRUNCATE bug — a file the enforce
+                // pass never touched — and the differential
                 // reverted enforce's edits anyway, destroying good work over a fault
                 // it did not cause AND leaving the actual cause unscheduled. When the
                 // FAIL is attributed to another task's untouched file, KEEP the edits
@@ -464,16 +465,82 @@ export async function runGatesForTask(ctxIn, deps, p) {
                 // unknown (git unavailable, no provenance, this task touched the file,
                 // an environment-blamed FAIL) falls through to the revert below —
                 // the conservative pre-existing behavior.
-                const rootCause = after.ok ? null : await routeRootCause(afterReason, '', 'committed');
+                //
+                // The scope is `enforce-commit`, NOT the task's own commit (mx5 run
+                // 18 / nexttask 4). This differential decides whether to discard the
+                // ENFORCE COMMIT, so the causal question is "could the enforce diff
+                // have caused this?" — asking what the TASK touched answers a
+                // question nobody at this seam is asking, and in run 18 it answered
+                // it in a way that destroyed a correct one-line change.
+                const rootCause = after.ok ? null : await routeRootCause(afterReason, '', 'enforce-commit');
+                // ATTRIBUTION PRE-FILTER (mx5 run 18 / nexttask 4). The root-cause
+                // channel above needs a blame CUE, a path-separator token and known
+                // provenance; run 18's FAIL text carried none of the three (it named
+                // a bare `MyListings.spec.tsx:186`), so it fell straight through to
+                // the revert. This filter asks only the mechanical question: does the
+                // failing check name any file the ENFORCE COMMIT touched? Disjoint =>
+                // the revert cannot repair the failure, so keep the edits and route
+                // the defect. Unknown diff, or a FAIL naming no file at all, still
+                // reverts — never keep on ignorance.
+                const attribution = !after.ok && !rootCause ?
+                    attributeEnforceFailure({
+                        failReason: afterReason,
+                        enforceTouched: (await deps.touchedFiles?.(p.cwd, 'enforce-commit')) ?? null,
+                        repoFiles: (await deps.repoFiles?.(p.cwd)) ?? null
+                    })
+                    : null;
                 if (!after.ok && rootCause) {
                     await rec(`enforce: re-verify FAILED (${afterReason.slice(0, 200)}) but the failure is attributed to a PRE-EXISTING defect in \`${rootCause.file}\` `
-                        + `(${rootCause.owner}'s file, untouched by this task and by the enforce pass) — edits KEPT, not reverted; repair task queued`);
+                        + `(${rootCause.owner}'s file, untouched by the ENFORCE COMMIT whose fate this differential decides) — edits KEPT, not reverted; repair task queued`);
                     active.ui.notify(`${p.tag}: guideline fixes on "${p.title}" re-verified red on a pre-existing defect in ${rootCause.file} (${rootCause.owner}'s file) — keeping the fixes, queued a repair task.`, 'warning');
                 }
+                else if (!after.ok && attribution?.verdict === 'keep') {
+                    // KEEP, mechanically justified: every file the failing check named
+                    // is outside the enforce diff (and outside its companions — a
+                    // touched file's own spec/story counts as inside). Discarding the
+                    // enforce commit could not repair this, and in run 18 doing so
+                    // cost a correct change that the final gate then re-made.
+                    await rec(`enforce: re-verify FAILED (${afterReason.slice(0, 200)}) but the failing check names only \`${attribution.named.join(', ')}\`, `
+                        + `which the ENFORCE COMMIT does not touch (its diff: ${attribution.enforceDiff.join(', ') || '—'}) — `
+                        + 'reverting it could not repair this, so the edits are KEPT and the defect is recorded as durable debt');
+                    // Keeping the edits must NOT lose the finding — that was mx5 run
+                    // 5's mistake. Same durability as the revert path; only the
+                    // disposition of the edits differs.
+                    await deps.recordEnforceKeptDebt?.(p.cwd, p.taskId, afterReason);
+                    // …and, when the named file is somebody else's committed work,
+                    // queue the scoped repair so something actually FIXES it.
+                    if (attribution.file && deps.introducedBy && deps.recordRepairCandidate) {
+                        try {
+                            const owner = await deps.introducedBy(p.cwd, attribution.file);
+                            const verifyCommand = extractFailingCommand(afterReason);
+                            if (owner && owner !== p.taskId) {
+                                await deps.recordRepairCandidate(p.cwd, {
+                                    file: attribution.file,
+                                    owner,
+                                    defect: summariseDefect(afterReason, attribution.file),
+                                    blamedTask: p.taskId,
+                                    ...(verifyCommand ? { verifyCommand } : {})
+                                });
+                                await rec(`root-cause: \`${attribution.file}\` is ${owner}'s file — scoped repair task queued`);
+                            }
+                        }
+                        catch {
+                            // queueing a repair must never break the gate sequence
+                        }
+                    }
+                    active.ui.notify(`${p.tag}: guideline fixes on "${p.title}" re-verified red on ${attribution.file ?? 'a file'} — outside the enforce diff, so keeping the fixes and recording the defect.`, 'warning');
+                }
                 else if (!after.ok) {
                     if (deps.revert)
                         await deps.revert(p.cwd);
-                    await rec(`enforce: fixes committed but re-verify FAILED (${(after.reason ?? 'now fails').slice(0, 200)}) — ${deps.revert ? 'REVERTED' : 'left in place (no revert available)'}`);
+                    await rec(`enforce: fixes committed but re-verify FAILED (${(after.reason ?? 'now fails').slice(0, 200)}) — ${deps.revert ? 'REVERTED' : 'left in place (no revert available)'}`
+                        // Why the attribution filter did NOT save the edits, so a
+                        // revert is explainable from the trail alone.
+                        + (attribution ?
+                            ` [attribution: ${attribution.why}${attribution.overlap ?
+                                ` — the check names \`${attribution.overlap.named}\`, the enforce diff touches \`${attribution.overlap.enforce}\``
+                                : ''}]`
+                            : ''));
                     // Persist the FAIL as a durable defect (mx5 run 10 item 3). The
                     // revert restores the tree the ORIGINAL verify already blessed, so
                     // this re-verify caught a defect that verify's earlier PASS missed —

package/package.json

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