@mjasnikovs/pi-task 0.38.29 → 0.38.31

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

@@ -6,9 +6,6 @@ import { isYoloMode, yoloFinalGateChoice, YOLO_STAMP } from './yolo.js';
 import { ignoredWriteTrailLine, ignoredWriteDebtReason } from './write-guard.js';
 import { readOwnedRequirements } from './requirements.js';
 import { unclaimedPendingRequirements } from './owned-freeze-reassign.js';
-// `final-gate-progress.ts`'s five pure functions are `AutofixLedger`'s internals
-// now — each was called from exactly ONE site inside this loop, extracted for
-// testability while the ordering and carry-forward decisions stayed out here.
 import { classifyFinalGateAnswer, MAX_FINAL_GATE_AUTOFIX, FINAL_LEAVE_LABEL, FINAL_LEAVE_VALUE, FINAL_ACCEPT_LABEL, FINAL_ACCEPT_VALUE, FINAL_AUTOFIX_LABEL, FINAL_AUTOFIX_VALUE, STRANDED_FIX_COMMIT, strandedFixNote } from './final-gate-fix.js';
 /**
  * Show the run-end picker and return the raw answer. Card ORDER is fixed —
@@ -49,10 +46,9 @@ function completedResult(id, taskCount, unobservedNote) {
 /**
  * Run the whole-repo gate and resolve its verdict with the user.
  *
- * Lifted verbatim out of /task-auto's run loop, which it never shared state with:
- * the stage reads no per-task variable and writes none. Never throws for a gate
- * outcome — only a user cancel inside a gate child propagates (the caller's
- * USER_CANCELLED path handles it).
+ * Shares no state with /task-auto's run loop: the stage reads no per-task variable
+ * and writes none. Never throws for a gate outcome — only a user cancel inside a
+ * gate child propagates (the caller's USER_CANCELLED path handles it).
  */
 export async function runFinalGateStage(active, deps, p) {
     const { cwd, runId: id, planText, taskCount } = p;
@@ -91,9 +87,8 @@ export async function runFinalGateStage(active, deps, p) {
             // recording must never break the gate
         }
     };
-    // Trail EVERY aggregated failure entry (mx5 run 13): the gate runs all sections
-    // and ranks the list; a single sliced reason line would re-hide everything past
-    // the first entry.
+    // Trail EVERY aggregated failure entry: the gate runs all sections and ranks the
+    // list, so a single sliced reason line would hide everything past the first.
     const trailGateFail = async (f) => {
         const list = f.failures ?? [f.reason];
         if (list.length <= 1) {
@@ -106,14 +101,12 @@ export async function runFinalGateStage(active, deps, p) {
         }
     };
     let fin = await deps.finalGate(cwd, planText);
-    // Record the outcome symmetrically (mx5 run 10 item 7): only FAIL was ever
-    // trailed, so a PASSing gate was indistinguishable from a gate that never ran. The
-    // PASS reason names the commands that were run. THREE verdicts, not two
-    // (final-gate.ts unobservedVerdict): a gate that observed nothing dynamic is
-    // UNOBSERVED, never PASS — IAR1 shipped `PASS — no integration command found`
-    // twice while carrying open verify-FAIL debt. It does not block (justified there),
-    // but it is labelled here, warned about, and recorded as durable debt so the next
-    // run's gate re-surfaces it.
+    // Record the outcome SYMMETRICALLY — trailing only FAIL would leave a passing
+    // gate indistinguishable from a gate that never ran, and the PASS reason names
+    // the commands that were run. THREE verdicts, not two (gate-tally.ts
+    // `unobservedVerdict`): a gate that observed nothing dynamic is UNOBSERVED, never
+    // PASS. It does not block, but it is labelled here, warned about, and recorded as
+    // durable debt so the next run's gate re-surfaces it.
     if (fin.ok && fin.unobserved) {
         unobservedNote = fin.unobserved;
         await recGate(`final-gate: UNOBSERVED — ${fin.reason.slice(0, 300)}`);
@@ -128,9 +121,8 @@ export async function runFinalGateStage(active, deps, p) {
     else {
         await trailGateFail(fin);
     }
-    // ACCEPT-debt re-check surfacing (mx5 run 4 B3 / run 8 TASK_0012): tasks the user
-    // accepted despite a verify-FAIL that the gate could not prove resolved against the
-    // current tree. Surface them at the gate moment — on PASS or FAIL — so a run never
+    // ACCEPT-debt surfacing: tasks the user accepted despite a verify-FAIL that the
+    // gate could not prove resolved against the current tree. Surface them at the gate moment — on PASS or FAIL — so a run never
     // completes silently carrying an accepted defect. Informational: the per-task
     // ACCEPT was already a human decision, so this reports, it does not re-fail.
     const debtKey = (d) => `${d.taskId}\t${d.reason}`;
@@ -146,10 +138,10 @@ export async function runFinalGateStage(active, deps, p) {
     // rather than blindly re-printed.
     let reportedDebts = fin.openDebts ?? [];
     await surfaceOpenDebts(reportedDebts);
-    // An owned obligation a task DETACHED (its own spec froze the only file that could
-    // satisfy it, nexttask 2) and no later task claimed. Detach never deletes the
-    // quote, so the run ends holding it — say so, or the resolution would be a quieter
-    // version of the deletion it exists to prevent.
+    // An owned obligation a task DETACHED — its own spec froze the only file that
+    // could satisfy it — and no later task claimed. Detach never deletes the quote, so
+    // the run ends holding it. Say so, or the detach becomes a quieter version of the
+    // deletion it exists to prevent.
     const unclaimed = unclaimedPendingRequirements(await (deps.ownedRequirements ?? readOwnedRequirements)(cwd).catch(() => []));
     for (const o of unclaimed) {
         await recGate(`owned requirement UNCLAIMED — "${o.quote.slice(0, 200)}"`
@@ -162,12 +154,11 @@ export async function runFinalGateStage(active, deps, p) {
             + ' file, and nothing else claimed it. See the gate trail.', 'warning');
     }
     /**
-     * nexttask 6 (mx5 run 18). The lines above are emitted from the FIRST gate result;
-     * the converged-autofix paths below used to rebuild `fin` as `{ok, reason}`, so
-     * `openDebts` did not survive the fix pass — the run's last word on its own defects
-     * was a snapshot of a tree that no longer existed, and no code path could clear,
-     * re-check or act on it. Re-derive here, against the tree the run actually ends
-     * with, and correct the record.
+     * Re-derive the debt report against the tree the run actually ends with.
+     *
+     * The lines above are emitted from the FIRST gate result, so without this the
+     * run's last word on its own defects describes a tree the autofix has since
+     * changed.
      *
      * FP-safe by inheritance: `deriveOpenDebts` auto-closes only what a deterministic
      * check can stand behind (a static-class debt when the statics provably pass, a
@@ -192,7 +183,7 @@ export async function runFinalGateStage(active, deps, p) {
             openDebts: fresh.openDebts,
             ...(fresh.debtNote ? { debtNote: fresh.debtNote } : {})
         };
-        // Per-debt evidence from the VERIFY-COMMAND re-check (nexttask 5): which
+        // Per-debt evidence from the VERIFY-COMMAND re-check: which
         // command was re-run and what it did. A close that cannot be read back from
         // the trail is a close nobody can audit, and an INCONCLUSIVE re-run is worth
         // saying out loud — it is the difference between "still broken" and "nothing
@@ -226,16 +217,15 @@ export async function runFinalGateStage(active, deps, p) {
         await recGate(`defect re-check after autofix: ${closed.length} resolved, `
             + `${fresh.openDebts.length} still open (re-derived against the FINAL tree)`);
     };
-    // Resolution loop: Leave-failed (recommended) / Autofix (bounded, model-driven fix
-    // pass + gate re-run — run 7's gap: the picker had NO automated fix path) /
-    // Accept. The user always decides; after MAX_FINAL_GATE_AUTOFIX attempts that
-    // still FAIL the autofix card is withdrawn so the loop cannot run unbounded.
-    // What this loop RECORDS, and the decisions that record makes: the attempt
-    // count and its bound, the accumulated gitignored writes, the stranded
+    // Resolution loop: Leave-failed (recommended) / Autofix (bounded, model-driven
+    // fix pass + gate re-run) / Accept. The user always decides; after
+    // MAX_FINAL_GATE_AUTOFIX attempts that still FAIL the autofix card is withdrawn,
+    // so the loop cannot run unbounded.
+    //
+    // Everything the loop remembers lives in the ledger, not in closure locals: the
+    // attempt count and its bound, the accumulated gitignored writes, the stranded
     // sub-fixes, the previous failure signature, the demoted set and the
-    // rejected-edits flag. Six closure-threaded locals before, and the
-    // non-progress rule applied downstream from the evidence it judges — the shape
-    // `final-gate-progress.ts`'s own comment names as the run-21 defect.
+    // rejected-edits flag. That keeps the non-progress rule where its evidence is.
     // `GateTally`'s twin, one altitude up (autofix-ledger.ts).
     const ledger = new AutofixLedger(MAX_FINAL_GATE_AUTOFIX);
     const refreshStranded = async () => {
@@ -250,9 +240,8 @@ export async function runFinalGateStage(active, deps, p) {
         }
     };
     // Commit whatever guard-clean repairs the fix passes left, on ANY terminal
-    // non-converged outcome. Run 14 ended on LEAVE with 13 real repairs dirty in the
-    // tree after an unattended run — the next checkout would have destroyed them
-    // silently.
+    // non-converged outcome. A run that ends on LEAVE can hold real repairs dirty in
+    // the tree, and the next checkout would destroy them silently.
     const commitStranded = async (outcome) => {
         const stranded = ledger.stranded();
         if (stranded.length === 0)
@@ -263,13 +252,11 @@ export async function runFinalGateStage(active, deps, p) {
                 + `so the tree holds REJECTED edits: ${stranded.slice(0, 8).join(', ')}`);
             return;
         }
-        // REPORT WHAT ACTUALLY HAPPENED (mx5 run 20). This bound the CommitResult to
-        // `sha` and interpolated it, so the trail read "committed 5 stranded fix-pass
-        // change(s) as [object Object]". Worse than cosmetic: `commit` returns
-        // {committed, reason?, note?} and NEVER a sha, the `committed` field was never
-        // read, and gitCommitAll returns {committed:false} WITHOUT throwing on an
-        // unmerged index — so on that path the catch below never fires and the trail
-        // claimed a commit over changes that were still sitting in the working tree.
+        // REPORT WHAT ACTUALLY HAPPENED, which means reading `committed`. A
+        // CommitResult is {committed, reason?, note?} and carries NO sha, and
+        // gitCommitAll answers {committed:false} WITHOUT throwing — so a trail line
+        // written from the catch alone would claim a commit over changes still sitting
+        // in the working tree.
         const notCommitted = async (why) => {
             await recGate(`final-gate: could NOT commit ${stranded.length} stranded fix-pass `
                 + `change(s) (${why}) — they remain UNCOMMITTED in the working `
@@ -293,25 +280,23 @@ export async function runFinalGateStage(active, deps, p) {
     };
     while (!fin.ok) {
         const canAutofix = deps.finalGateFix !== undefined && ledger.canAutofix();
-        // The picker question shows the debts (the HUMAN weighs them); the autofix seed
-        // below deliberately does not — mx5 run 11's fix child executed a debt claim as
-        // an `rm` instruction.
+        // The picker question shows the debts, because the HUMAN weighs them. The
+        // autofix seed below deliberately does not: a debt claim is prose about a
+        // defect, and a write-enabled child reads prose as an instruction.
         const question = `Final integration gate FAILED for ${id}.\n\n${fin.reason}${fin.debtNote ?? ''}\n\n`
             + 'All tasks are checked off — this is the whole-repo check '
             + '(the project’s own test/build/static commands, run unaided).'
             + (ledger.attempts() > 0 ?
                 `\n\nAutofix attempts so far: ${ledger.attempts()}/${MAX_FINAL_GATE_AUTOFIX}.`
                 : '')
-            // Never let a partial repair be invisible at the moment the human decides
-            // (run 13: a bunfig fix that made `bun run test` pass 116/116 was stranded
-            // by an ACCEPT).
+            // Never let a partial repair be invisible at the moment the human
+            // decides — an ACCEPT here would otherwise strand a real fix.
             + strandedFixNote([...ledger.stranded()]);
         // YOLO: keep autofixing WHILE the card is still offered — the loop withdraws it
         // after MAX_FINAL_GATE_AUTOFIX, so the cap that bounds a non-converging fix pass
         // still bounds this — then LEAVE the run failed. Never 'accept': an unattended
         // run that could not green the whole-repo gate has not produced a working
-        // project, and mx5 run 13 shows what an accepted FAIL looks like afterwards (a
-        // shipped app that 404s at `/`).
+        // project, and nobody is there to judge the FAIL it would be accepting.
         const yoloFinal = yoloFinalGateChoice(isYoloMode(), canAutofix);
         if (yoloFinal !== null) {
             await recGate(`final-gate: auto-chose ${yoloFinal.action.toUpperCase()} ${YOLO_STAMP}`);
@@ -328,7 +313,7 @@ export async function runFinalGateStage(active, deps, p) {
             // repaired but never committed would be lost to the next `git checkout`
             // while HEAD keeps the defect it fixed. Commit it as its own, named
             // commit — the ACCEPT is a decision about the FAILING gate, never an
-            // instruction to throw away work (mx5 run 13 item 3).
+            // instruction to throw away work.
             await commitStranded('accepted');
             active.ui.notify(`${id}: final integration gate FAIL accepted by user — completing.`
                 + (ledger.stranded().length > 0 ?
@@ -342,7 +327,7 @@ export async function runFinalGateStage(active, deps, p) {
             active.ui.notify(`${id}: final-gate autofix (${attempt}/${MAX_FINAL_GATE_AUTOFIX}) — bounded fix pass, then the gate re-runs…`, 'info');
             const seed = choice.guidance ? `${fin.reason}\n\nUser guidance: ${choice.guidance}` : fin.reason;
             const fix = await deps.finalGateFix(active, cwd, seed, [...ledger.ignoredWrites()]);
-            // IGNORED-PATH WRITES (mx5 run 19). The pass wrote file(s) git ignores, so
+            // IGNORED-PATH WRITES. The pass wrote file(s) git ignores, so
             // they are not in the commit and a fresh clone does not have them. Trailed
             // on EVERY outcome — a rejected attempt's tracked edits are discarded while
             // its ignored writes survive on disk — and carried forward, so a later
@@ -371,10 +356,9 @@ export async function runFinalGateStage(active, deps, p) {
                 }
                 await recGate(`final-gate: autofix ${fix.unobserved ? 'ended UNOBSERVED' : 'converged'} — ${fix.reason.slice(0, 200)}`);
                 active.ui.notify(`${id}: final integration gate ${fix.unobserved ? 'is UNOBSERVED' : 'PASSES'} after autofix — ${fix.reason.slice(0, 140)}`, fix.unobserved ? 'warning' : 'info');
-                // The gate's own outcome, whole, with this door's reason on it. It
-                // used to be a two-key literal, so `openDebts` and `observedFailures`
-                // were dropped and `reconcileDebts` was the only thing putting one of
-                // them back — the recorded mx5 run-18 defect.
+                // The gate's own outcome, WHOLE, with this door's reason on it.
+                // Rebuilding it as a two-key literal would drop `openDebts` and
+                // `observedFailures` from the value entirely.
                 fin = { ...(fix.gate ?? fin), ok: true, reason: fix.reason };
                 // The gate itself just passed, statics included, so `staticOk` here is
                 // proof rather than assumption.
@@ -397,12 +381,12 @@ export async function runFinalGateStage(active, deps, p) {
                     + `uncommitted change(s) — ${ledger.stranded().slice(0, 8).join(', ')}`);
             }
             active.ui.notify(`${id}: final-gate autofix did not converge — ${fix.reason.slice(0, 140)}`, 'warning');
-            // NON-PROGRESS CLASSIFIER (mx5 run 14 item 2a). An attempt that changed the
-            // tree, re-ran the gate, and got back the SAME ranked-first failure as the
-            // previous such attempt is evidence about the CHECK, not the fix: run 14
-            // burned all three attempts on a boot probe that could not observe a
-            // listener in that sandbox at all. Demote that one check to
-            // UNOBSERVED-with-debt and let the REMAINING checks decide.
+            // NON-PROGRESS CLASSIFIER. An attempt that changed the tree, re-ran the
+            // gate, and got back the SAME ranked-first failure as the previous such
+            // attempt is evidence about the CHECK, not about the fix — a check that
+            // cannot observe anything in this environment answers identically however
+            // the tree moves. Demote that one check to UNOBSERVED-with-debt and let
+            // the REMAINING checks decide.
             //
             // The judgement, the observed check and the signature carry-forward are
             // the ledger's — made where the evidence is, not downstream from it.
@@ -446,12 +430,10 @@ export async function runFinalGateStage(active, deps, p) {
             // next picker and the next fix seed target only what is still falsifiable —
             // never re-aiming the child at the check the classifier just proved it
             // cannot move.
-            // Outcome to outcome. The base is the FRESH gate outcome when the fix
-            // pass got as far as re-running it, otherwise the one we already hold —
-            // and either way it arrives whole, so nothing (`openDebts`,
-            // `observedFailures`) is dropped by the assignment. This used to be a
-            // literal with four keys, and the field it omitted is the recorded mx5
-            // run-18 defect.
+            // Outcome to outcome, WHOLE. The base is the FRESH gate outcome when the
+            // fix pass got as far as re-running it, otherwise the one we already hold;
+            // either way it is spread rather than rebuilt, so no field (`openDebts`,
+            // `observedFailures`) is dropped by the assignment.
             const base = fix.gate ?? fin;
             const carried = base.failures === undefined ? undefined : ledger.remaining(base);
             fin = {
@@ -477,9 +459,9 @@ export async function runFinalGateStage(active, deps, p) {
             `final-gate: left failed — autofix budget spent, nobody to ask ${YOLO_STAMP}`
             : 'final-gate: left failed (user)');
         // Leaving the run failed is TERMINAL for an unattended run, so the fix passes'
-        // guard-clean repairs are committed here too — run 14 left 13 of them dirty for
-        // a `git checkout` to destroy (mx5 run 13 item 3, run 14 item 2b). The user
-        // still owns the outcome; they own it with the work in HEAD, named in the trail.
+        // guard-clean repairs are committed here too, rather than left dirty for a
+        // `git checkout` to destroy. The user still owns the outcome; they own it with
+        // the work in HEAD, named in the trail.
         await commitStranded('left-failed');
         return {
             kind: 'failed',

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

@@ -2,18 +2,16 @@
  * runner-globs — deterministic detection of TWO TEST RUNNERS FIGHTING OVER THE SAME
  * FILES, checked as soon as a project declares both rather than discovered at run end.
  *
- * The failure this closes — SECOND occurrence, runs 7 AND 13: a project declares both
- * `bun test` and `playwright test`. Bun's runner scans the whole project for
- * `*.test.*` / `*.spec.*`; Playwright's component/e2e specs ARE `*.spec.tsx`. So
- * `bun test` imports Playwright spec files, which import `@playwright/test` outside a
- * Playwright runner, and the whole suite dies on a module it was never meant to load.
+ * The failure this closes: a project declares both `bun test` and
+ * `playwright test`. `bun test` with no arguments scans the whole project tree for
+ * `*.test.*` / `*.spec.*`, and Playwright's component/e2e specs ARE `*.spec.tsx`.
+ * So `bun test` imports Playwright spec files, which import `@playwright/test`
+ * outside a Playwright runner, and the whole suite dies on a module it was never
+ * meant to load.
  *
- * Run 7 found it in the final gate. Run 13 found it in the final gate AGAIN — and the
- * fix (a `pathIgnorePatterns` line in bunfig.toml) was still sitting UNCOMMITTED in
- * the working tree when the run ended, so HEAD shipped with `bun run test` broken. A
- * defect that recurs across runs and survives its own fix is not a discovery problem;
- * it is a missing invariant. This module states the invariant so it can be checked the
- * moment both runners are declared:
+ * Finding that at the final gate is too late: the fix is a one-line config change
+ * that can still be sitting uncommitted when the run ends. So the invariant is
+ * checked the moment both runners are declared:
  *
  *     if two runners are declared, their file sets must be provably DISJOINT
  *
@@ -51,8 +49,9 @@ export interface RunnerGlobInputs {
  */
 export declare function parsePathIgnorePatterns(bunfig: string | null): string[] | null;
 /**
- * Playwright's `testMatch`, when the config states one. Null → the default, which
- * matches `*.spec.*` and `*.test.*` — precisely Bun's claimed set.
+ * Playwright's `testMatch`, when the config states one. Null when the config
+ * states none (or there is no config), in which case the NAMING form cannot be
+ * proven and `assessRunnerGlobs` falls through to the exclusion check.
  */
 export declare function parseTestMatch(playwrightConfig: string | null): string[] | null;
 /** Playwright's `testDir`, when stated (used to explain the collision concretely). */

package/dist/task/runner-globs.js

@@ -2,18 +2,16 @@
  * runner-globs — deterministic detection of TWO TEST RUNNERS FIGHTING OVER THE SAME
  * FILES, checked as soon as a project declares both rather than discovered at run end.
  *
- * The failure this closes — SECOND occurrence, runs 7 AND 13: a project declares both
- * `bun test` and `playwright test`. Bun's runner scans the whole project for
- * `*.test.*` / `*.spec.*`; Playwright's component/e2e specs ARE `*.spec.tsx`. So
- * `bun test` imports Playwright spec files, which import `@playwright/test` outside a
- * Playwright runner, and the whole suite dies on a module it was never meant to load.
+ * The failure this closes: a project declares both `bun test` and
+ * `playwright test`. `bun test` with no arguments scans the whole project tree for
+ * `*.test.*` / `*.spec.*`, and Playwright's component/e2e specs ARE `*.spec.tsx`.
+ * So `bun test` imports Playwright spec files, which import `@playwright/test`
+ * outside a Playwright runner, and the whole suite dies on a module it was never
+ * meant to load.
  *
- * Run 7 found it in the final gate. Run 13 found it in the final gate AGAIN — and the
- * fix (a `pathIgnorePatterns` line in bunfig.toml) was still sitting UNCOMMITTED in
- * the working tree when the run ended, so HEAD shipped with `bun run test` broken. A
- * defect that recurs across runs and survives its own fix is not a discovery problem;
- * it is a missing invariant. This module states the invariant so it can be checked the
- * moment both runners are declared:
+ * Finding that at the final gate is too late: the fix is a one-line config change
+ * that can still be sitting uncommitted when the run ends. So the invariant is
+ * checked the moment both runners are declared:
  *
  *     if two runners are declared, their file sets must be provably DISJOINT
  *
@@ -53,8 +51,9 @@ export function parsePathIgnorePatterns(bunfig) {
     return [...m[1].matchAll(/["']([^"']+)["']/g)].map(x => x[1]);
 }
 /**
- * Playwright's `testMatch`, when the config states one. Null → the default, which
- * matches `*.spec.*` and `*.test.*` — precisely Bun's claimed set.
+ * Playwright's `testMatch`, when the config states one. Null when the config
+ * states none (or there is no config), in which case the NAMING form cannot be
+ * proven and `assessRunnerGlobs` falls through to the exclusion check.
  */
 export function parseTestMatch(playwrightConfig) {
     if (playwrightConfig === null)

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

@@ -24,13 +24,12 @@ export declare function resolveRunner(bin: string, opts?: {
  * 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.
+ * 127 is a POSIX-SHELL convention: bun hands the script to a shell, the shell
+ * prints `…: command not found` and exits 127, and the whole env-gap contract
+ * keys off that number. Where no such shell runs the script, the runner reports
+ * the miss itself (`bun: command not found: X`) and the status alone cannot be
+ * told from a real code fault. cmd.exe (9009) and PowerShell have their own
+ * wording. Recognising the shape restores the env-gap contract there.
  *
  * Deliberately narrow: only wordings a RUNNER/SHELL produces, never the bare
  * phrase. A suite that prints "command not found" inside a failing assertion is
@@ -41,8 +40,9 @@ 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.
+ * COMMAND_NOT_FOUND_OUTPUT_RE), because a runner that resolves the command
+ * itself can report the miss and still exit 1. Callers treat a true here as an
+ * environment gap → skip, never FAIL.
  */
 export declare function isCommandNotFound(status: number | null, output?: string): boolean;
 /**

package/dist/task/runner-resolve.js

@@ -2,26 +2,25 @@
  * runner-resolve — make the deterministic gates able to SPAWN the project's own
  * runner when the host PATH lost it.
  *
- * The failure this closes (mx5 run 16, validated): pi was launched inside the
- * sandbox through a LOGIN shell, whose /etc/profile reset PATH and dropped
- * ~/.bun/bin — so `bun` was unspawnable in every gate spawn. Under the env-gap
- * contract (ENOENT / exit 127 → skip, deliberately, so a missing tool is never a
- * code fault) EVERY dynamic check silently skipped: bun test, the boot of
- * `bun run dev`, and therefore the render check built for exactly the blank-page
- * class the run shipped. The gate converged on static checks alone and stamped
- * the run green while the binary sat at ~/.bun/bin/bun the whole time.
+ * The failure this closes: a host whose PATH lost the runner — pi launched
+ * through a login shell whose profile rebuilt PATH without `~/.bun/bin`, say.
+ * `bun` is then unspawnable in every gate spawn, and under the env-gap contract
+ * (ENOENT / exit 127 → skip, deliberately, so a missing tool is never a code
+ * fault) EVERY dynamic check silently skips: the test command, the boot of
+ * `bun run dev`, and therefore the render check too. The gate converges on static
+ * checks alone and stamps the run green while the binary sits in a directory
+ * nothing looked in.
  *
  * Resolution is discovery, never installation: try the bare name first (PATH
  * serves it → nothing changes), then probe well-known install locations. Each
  * probe is a real `<candidate> --version` spawn — an existing but broken binary
  * must not count as resolved.
  *
- * The PATH PREFIX matters as much as the binary: a resolved `bun run test` still
- * re-invokes `bun` (and the repo's own bins) INSIDE the script chain, and those
- * inner calls exit 127 without the runner's directory on PATH — the same silent
- * blindness one level down (run 16's final-fix child hit exactly this and had to
- * hand-export PATH). Spawn sites must therefore use runnerEnv(), not just the
- * resolved binary.
+ * {@link runnerEnv} prepends the resolved directory to PATH for the spawned
+ * script chain. Spawn sites should use it rather than the resolved binary alone:
+ * a `bun run test` re-invokes commands INSIDE the script, and a runner that does
+ * not put itself within reach of those inner calls would fail them for the same
+ * reason the outer spawn failed.
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
@@ -87,13 +86,12 @@ export function resolveRunner(bin, opts = {}) {
  * 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.
+ * 127 is a POSIX-SHELL convention: bun hands the script to a shell, the shell
+ * prints `…: command not found` and exits 127, and the whole env-gap contract
+ * keys off that number. Where no such shell runs the script, the runner reports
+ * the miss itself (`bun: command not found: X`) and the status alone cannot be
+ * told from a real code fault. cmd.exe (9009) and PowerShell have their own
+ * wording. Recognising the shape restores the env-gap contract there.
  *
  * Deliberately narrow: only wordings a RUNNER/SHELL produces, never the bare
  * phrase. A suite that prints "command not found" inside a failing assertion is
@@ -104,8 +102,9 @@ export const COMMAND_NOT_FOUND_OUTPUT_RE = /\b(?:bun|npm|pnpm|yarn|node|deno): c
  * 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.
+ * COMMAND_NOT_FOUND_OUTPUT_RE), because a runner that resolves the command
+ * itself can report the miss and still exit 1. Callers treat a true here as an
+ * environment gap → skip, never FAIL.
  */
 export function isCommandNotFound(status, output = '') {
     if (status === 127 || status === 9009)

package/dist/task/script-escape.d.ts

@@ -1,25 +1,24 @@
 /**
  * script-escape — deterministic detection of CHECK SCRIPTS THAT CANNOT FAIL.
  *
- * The failure this closes (mx5 run 13, PROMPT 4 item 4): the shipped package.json
- * declared, verbatim,
+ * The failure this closes: a package.json declaring
  *     "lint": "prettier … && eslint --fix … && (tsc --noEmit 2>&1 | grep -qv 'TS18003' || true)"
  * The typecheck is neutered twice over — its output is piped into an INVERTED grep
  * (so the status becomes "some line did not match", never tsc's verdict), and the
  * whole group is closed with `|| true` (so the script exits 0 unconditionally). Every
  * consumer of that script — the repo-health verify gate, the final integration gate,
- * a human reading a green CI line — is reading a constant, not a measurement.
+ * a human reading a green CI line — is reading a constant, not a measurement. It
+ * looks fine for exactly as long as the checker happens to be clean.
  *
- * It was harmless in run 13 only by luck: tsc happened to be clean (validated). The
- * class is not harmless — this is the same defect as run-8's F2 skip-escape, moved
- * one level out. findSkipEscapes (skip-escape.ts) scans a spec's own VERIFY block;
- * nothing scanned the SCRIPT DEFINITIONS those VERIFY blocks then invoke by name, so
- * `bun run lint` could be authored into a no-op and every gate would salute it.
+ * This is a skip-escape moved one level out. `findSkipEscapes` (skip-escape.ts)
+ * scans a spec's own VERIFY block; nothing else scans the SCRIPT DEFINITIONS those
+ * VERIFY blocks then invoke by name, so `bun run lint` can be authored into a no-op
+ * and every gate salutes it.
  *
  * TWO SHAPES, both crisp, both scoped to CHECK-CLASS script names:
  *
  *   A. ALWAYS-ZERO TAIL — the script's last command cannot fail (`… || true`,
- *      `… || :`, `… || exit 0`, `…; exit 0`, a trailing `|| echo` fallback). A
+ *      `… ||:`, `… || exit 0`, `…; exit 0`, a trailing `|| echo` fallback). A
  *      shell script's status is its last command's status, so this is a proof, not
  *      a heuristic: the script exits 0 no matter what the checker found.
  *
@@ -27,9 +26,8 @@
  *      "Some line of the output does NOT match X" is never a checker's verdict; it
  *      is true of virtually any non-empty output, including a wall of errors.
  *
- * Deliberately NOT flagged, because each is legitimate and FP-measured against the
- * real corpus (pi-task, aiz-server, aiz-client, gofer, mx5):
- *   - `|| exit 1` — a HARDENING, the opposite of an escape (aiz-server).
+ * Deliberately NOT flagged, because each is legitimate:
+ *   - `|| exit 1` — a HARDENING, the opposite of an escape.
  *   - any `||`/pipe in a NON-check script (`clean`, `dev`, `start`, `copy-fonts`) —
  *     a teardown `rm -rf dist || true` is correct and common.
  *   - pipes into formatters/reporters (`| tap-spec`, `| tee`) — those propagate

package/dist/task/script-escape.js

@@ -1,25 +1,24 @@
 /**
  * script-escape — deterministic detection of CHECK SCRIPTS THAT CANNOT FAIL.
  *
- * The failure this closes (mx5 run 13, PROMPT 4 item 4): the shipped package.json
- * declared, verbatim,
+ * The failure this closes: a package.json declaring
  *     "lint": "prettier … && eslint --fix … && (tsc --noEmit 2>&1 | grep -qv 'TS18003' || true)"
  * The typecheck is neutered twice over — its output is piped into an INVERTED grep
  * (so the status becomes "some line did not match", never tsc's verdict), and the
  * whole group is closed with `|| true` (so the script exits 0 unconditionally). Every
  * consumer of that script — the repo-health verify gate, the final integration gate,
- * a human reading a green CI line — is reading a constant, not a measurement.
+ * a human reading a green CI line — is reading a constant, not a measurement. It
+ * looks fine for exactly as long as the checker happens to be clean.
  *
- * It was harmless in run 13 only by luck: tsc happened to be clean (validated). The
- * class is not harmless — this is the same defect as run-8's F2 skip-escape, moved
- * one level out. findSkipEscapes (skip-escape.ts) scans a spec's own VERIFY block;
- * nothing scanned the SCRIPT DEFINITIONS those VERIFY blocks then invoke by name, so
- * `bun run lint` could be authored into a no-op and every gate would salute it.
+ * This is a skip-escape moved one level out. `findSkipEscapes` (skip-escape.ts)
+ * scans a spec's own VERIFY block; nothing else scans the SCRIPT DEFINITIONS those
+ * VERIFY blocks then invoke by name, so `bun run lint` can be authored into a no-op
+ * and every gate salutes it.
  *
  * TWO SHAPES, both crisp, both scoped to CHECK-CLASS script names:
  *
  *   A. ALWAYS-ZERO TAIL — the script's last command cannot fail (`… || true`,
- *      `… || :`, `… || exit 0`, `…; exit 0`, a trailing `|| echo` fallback). A
+ *      `… ||:`, `… || exit 0`, `…; exit 0`, a trailing `|| echo` fallback). A
  *      shell script's status is its last command's status, so this is a proof, not
  *      a heuristic: the script exits 0 no matter what the checker found.
  *
@@ -27,9 +26,8 @@
  *      "Some line of the output does NOT match X" is never a checker's verdict; it
  *      is true of virtually any non-empty output, including a wall of errors.
  *
- * Deliberately NOT flagged, because each is legitimate and FP-measured against the
- * real corpus (pi-task, aiz-server, aiz-client, gofer, mx5):
- *   - `|| exit 1` — a HARDENING, the opposite of an escape (aiz-server).
+ * Deliberately NOT flagged, because each is legitimate:
+ *   - `|| exit 1` — a HARDENING, the opposite of an escape.
  *   - any `||`/pipe in a NON-check script (`clean`, `dev`, `start`, `copy-fonts`) —
  *     a teardown `rm -rf dist || true` is correct and common.
  *   - pipes into formatters/reporters (`| tap-spec`, `| tee`) — those propagate
@@ -57,7 +55,8 @@ const ALWAYS_ZERO_TAILS = [
 const INVERTED_GREP_RE = /\|\s*grep\s+(?:-\w*v\w*|-\w+\s+-\w*v\w*)/;
 /**
  * Strip trailing subshell/group closers and separators so the tail patterns see the
- * real last command. mx5's script ends `… || true)` — without this the `)` hides it.
+ * real last command: a script ending `… && (tsc --noEmit || true)` hides its tail
+ * behind the `)`.
  */
 function tailOf(body) {
     let s = body.trim();
@@ -177,7 +176,7 @@ export function scriptEscapeVerifyFindings(findings) {
 export function scriptEscapeDefectText(findings) {
     return [
         'NEUTERED CHECK SCRIPT — this spec defines a check script that CANNOT FAIL, so every',
-        'gate that runs it reads a constant instead of a measurement (mx5 run 13 shipped',
+        'gate that runs it reads a constant instead of a measurement (a run shipped',
         '`"lint": "… && (tsc --noEmit 2>&1 | grep -qv \'TS18003\' || true)"` — the typecheck',
         'was fully disarmed, and it went unnoticed only because tsc happened to be clean).',
         "Rewrite each so it PROPAGATES the checker's exit status: drop the `|| true` /",

package/dist/task/serve-entry.d.ts

@@ -20,7 +20,7 @@ export declare function findBindEvidence(src: string, appNames?: Set<string>): s
 /** Why this file makes the project a SERVING one, or null. */
 export declare function findServeExpectation(src: string): string | null;
 /** A design/spec clause that names a served path — the plan-side half of the same
- *  expectation (mx5's `DESIGN/PROJECT.md:285`: "serves `/api` + static `dist/`"). */
+ *  expectation, e.g. a design that says "serves `/api` + static `dist/`". */
 export declare function planExpectsServing(planText: string | undefined): string | null;
 /** The platform that would bind on this project's behalf, or null. */
 export declare function opaqueLauncher(cwd: string): string | null;