@mjasnikovs/pi-task 0.18.14 → 0.18.16

package/dist/task/final-gate.js

@@ -42,8 +42,10 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { runRepoHealthCheck, discoverHealthCommands } from './repo-health-check.js';
-import { readAcceptDebts, recheckAcceptDebts, writeAcceptDebts, buildAcceptDebtNote } from './accept-debt.js';
-import { readDeclaredScripts, missingDeclaredScripts } from './launch-contract.js';
+import { readAcceptDebts, recheckAcceptDebts, writeAcceptDebts, buildAcceptDebtNote, annotateDebtConflicts } from './accept-debt.js';
+import { readDeclaredScripts, missingDeclaredScripts, runnableDeclaredScripts } from './launch-contract.js';
+import { readEnvNotes, parseEnvNotes, isExcuseNote } from './env-notes.js';
+import { runRenderCheck } from './render-check.js';
 function packageScripts(cwd) {
     try {
         const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -79,7 +81,9 @@ export function discoverIntegrationCommands(cwd) {
         // order, then `build`. Env-gap SKIP still applies per command (a suite whose
         // browser/runtime is absent skips, it does not fail — see runGateCommand).
         const testNames = Object.keys(s).filter(n => n === 'test' || /^test[:_-]/.test(n));
-        testNames.sort((a, b) => (a === 'test' ? -1 : b === 'test' ? 1 : 0));
+        testNames.sort((a, b) => a === 'test' ? -1
+            : b === 'test' ? 1
+                : 0);
         for (const name of testNames)
             cmds.push(['bun', ['run', name]]);
         if (s.build)
@@ -218,32 +222,46 @@ export function detectsServedApp(cwd, planText) {
     }
     return planText !== undefined && SERVE_TEXT_RE.test(planText);
 }
-/** Pids currently owning a LISTENing TCP socket (best-effort; ss first, then lsof).
+/** Listening TCP sockets as {pid, port} pairs (best-effort; ss first, then lsof).
  *  Empty on any failure — the caller then cannot attribute a listener to our group
  *  and the served-app check degrades to survival (never a false FAIL). */
-function listeningSocketPids() {
-    const pids = new Set();
+function listeningSockets() {
+    const out = [];
     try {
         const t = spawnSync('ss', ['-tlnpH'], { encoding: 'utf8', timeout: 4000 });
         if (!t.error && t.stdout) {
-            for (const m of t.stdout.matchAll(/pid=(\d+)/g))
-                pids.add(Number(m[1]));
+            for (const line of t.stdout.split('\n')) {
+                const pm = /pid=(\d+)/.exec(line);
+                if (!pm)
+                    continue;
+                // Column 4 (0-based 3) is the local address; the port is its last
+                // `:`-suffixed number ("0.0.0.0:3000", "[::]:3000").
+                const local = line.trim().split(/\s+/)[3] ?? '';
+                const portm = /:(\d+)$/.exec(local);
+                if (!portm)
+                    continue;
+                out.push({ pid: Number(pm[1]), port: Number(portm[1]) });
+            }
         }
     }
     catch {
         // ss missing — try lsof
     }
-    if (pids.size === 0) {
+    if (out.length === 0) {
         try {
-            const t = spawnSync('lsof', ['-iTCP', '-sTCP:LISTEN', '-t', '-n', '-P'], {
+            const t = spawnSync('lsof', ['-iTCP', '-sTCP:LISTEN', '-n', '-P'], {
                 encoding: 'utf8',
                 timeout: 4000
             });
             if (!t.error && t.stdout) {
-                for (const line of t.stdout.split('\n')) {
-                    const n = Number(line.trim());
-                    if (Number.isInteger(n) && n > 0)
-                        pids.add(n);
+                for (const line of t.stdout.split('\n').slice(1)) {
+                    const cols = line.trim().split(/\s+/);
+                    const pid = Number(cols[1]);
+                    const name = cols.find(c => /:\d+$/.test(c)) ?? '';
+                    const portm = /:(\d+)$/.exec(name);
+                    if (Number.isInteger(pid) && pid > 0 && portm) {
+                        out.push({ pid, port: Number(portm[1]) });
+                    }
                 }
             }
         }
@@ -251,7 +269,7 @@ function listeningSocketPids() {
             // neither tool available
         }
     }
-    return [...pids];
+    return out;
 }
 /** Process-group id of `pid`, or null if it cannot be read. */
 function pgidOf(pid) {
@@ -270,12 +288,21 @@ function pgidOf(pid) {
 /** Default listener probe: any LISTENing socket owned by a pid in process group
  *  `pgid` (the detached boot child IS its own group leader, so pgid === child.pid). */
 function defaultGroupHasListener(pgid) {
-    for (const pid of listeningSocketPids()) {
+    for (const { pid } of listeningSockets()) {
         if (pgidOf(pid) === pgid)
             return true;
     }
     return false;
 }
+/** Default port lookup for the render check: the LOWEST port among the group's
+ *  listeners (a dev toolchain may open an HMR socket too; the app's own server
+ *  conventionally sits on the lower, configured port). Null when undeterminable. */
+function defaultGroupListeningPort(pgid) {
+    const ports = listeningSockets()
+        .filter(({ pid }) => pgidOf(pid) === pgid)
+        .map(({ port }) => port);
+    return ports.length > 0 ? Math.min(...ports) : null;
+}
 /** Default port-holder lookup: `lsof` first, then `ss`/`fuser`. Returns null on any
  *  failure (the diagnosis then omits the pid — never blocks). */
 function defaultFindPortHolder(port) {
@@ -389,21 +416,40 @@ export function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}) {
                 // group already gone
             }
         };
-        const passAndKill = () => {
-            settle({ outcome: 'pass' });
+        const passAndKill = (renderNote) => {
+            settle(renderNote ? { outcome: 'pass', renderNote } : { outcome: 'pass' });
+            killGroup('SIGTERM');
+            setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
+        };
+        const failAndKill = (detail) => {
+            settle({ outcome: 'fail', detail });
             killGroup('SIGTERM');
             setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
         };
         // Served apps only: poll for a listening socket owned by our process group.
-        // As soon as one appears the boot has demonstrably served → PASS early.
+        // As soon as one appears the boot has demonstrably served → run the render
+        // check against the LIVE listener (mx5 runs 8/11: a listener that serves a
+        // permanently blank page passed every curl-shaped check), then PASS/FAIL.
+        // The probe is spawnSync, so the interval cannot re-enter mid-check.
         const poll = expectServer ?
             setInterval(() => {
                 if (settled || !child.pid)
                     return;
-                if (groupHasListener(child.pid)) {
-                    listenerSeen = true;
-                    passAndKill();
+                if (!groupHasListener(child.pid))
+                    return;
+                listenerSeen = true;
+                const probe = opts.deps?.renderProbe;
+                if (!probe)
+                    return passAndKill();
+                const port = (opts.deps?.groupListeningPort ?? defaultGroupListeningPort)(child.pid);
+                if (port === null) {
+                    return passAndKill('render check UNOBSERVED: a listener was seen but its port could not be determined');
+                }
+                const rr = probe(`http://127.0.0.1:${port}/`);
+                if (rr.outcome === 'fail') {
+                    return failAndKill(`listens on :${port} but ${rr.detail}`);
                 }
+                passAndKill(rr.outcome === 'skip' ? `render check UNOBSERVED: ${rr.note}` : undefined);
             }, 500)
             : null;
         const timer = setTimeout(() => {
@@ -483,14 +529,23 @@ function outputTail(stdout, stderr, limit = 400) {
  * These exit non-zero (not 127), so they need output-shape recognition to skip.
  */
 const ENV_GAP_OUTPUT_RE = /Executable doesn't exist|playwright install|browserType\.\w+: Executable|(?:wasn't|weren't) installed|Host system is missing dependencies|No usable sandbox|Cypress verification|Cypress executable (?:not found|was not found)|browser(?:s)? (?:is|are)? ?not installed/i;
+/**
+ * A non-zero exit whose output shows the EXTERNAL INFRASTRUCTURE a launch script
+ * talks to is absent HERE — a database/daemon that is not running or not
+ * installed — rather than a fault in the script itself. Applied ONLY to
+ * launch-contract scripts (a migrate/seed against no DB is an environment gap on
+ * this box; the same wording in a `test` run is a real failure the suite must own).
+ */
+export const INFRA_GAP_OUTPUT_RE = /ECONNREFUSED|connection refused|ENOTFOUND|EAI_AGAIN|is the server running|could not connect|cannot connect to the docker daemon|connect: connection|no such host/i;
 /**
  * Run one gate command with the env-gap contract: tool missing, timeout, or
  * command-not-found inside the script chain (127) → environment gap, not a code
  * fault → skipped (same contract as repo-health). Also skips a non-zero exit whose
- * output shows a missing browser/runtime (ENV_GAP_OUTPUT_RE). Only a command that
- * actually ran and exited non-zero for a real reason fails.
+ * output shows a missing browser/runtime (ENV_GAP_OUTPUT_RE) — or, when the caller
+ * passes `extraGapRe` (launch scripts), missing external infrastructure. Only a
+ * command that actually ran and exited non-zero for a real reason fails.
  */
-function runGateCommand(cwd, [bin, args], timeoutMs) {
+function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe) {
     // env passed explicitly: bun's spawnSync resolves the binary against a
     // startup snapshot of the environment, not the live process.env.
     const r = spawnSync(bin, args, {
@@ -502,7 +557,10 @@ function runGateCommand(cwd, [bin, args], timeoutMs) {
     if (r.error || r.status === null || r.status === 127)
         return { outcome: 'skip' };
     if (r.status !== 0) {
-        if (ENV_GAP_OUTPUT_RE.test(`${r.stdout ?? ''}\n${r.stderr ?? ''}`))
+        const output = `${r.stdout ?? ''}\n${r.stderr ?? ''}`;
+        if (ENV_GAP_OUTPUT_RE.test(output))
+            return { outcome: 'skip' };
+        if (extraGapRe?.test(output))
             return { outcome: 'skip' };
         return { outcome: 'fail', status: r.status, tail: outputTail(r.stdout ?? '', r.stderr ?? '') };
     }
@@ -528,6 +586,27 @@ async function recoverOrphanPort(cwd, boot, first, bootGraceMs, deps, expectServ
     await new Promise(r => setTimeout(r, 1_500));
     return runBootCheck(cwd, boot, bootGraceMs, { expectServer, deps });
 }
+/**
+ * The task whose commit INTRODUCED `rel` (oldest `--diff-filter=A` commit whose
+ * subject carries the pi-task `(TASK_nnnn)` suffix — both the task snapshot and the
+ * ENFORCE commit shapes match). Null when the file predates the run, was never
+ * committed, git is unavailable, or the adding commit is not a task commit — every
+ * unknown degrades to "no conflict claim".
+ */
+export function taskThatIntroduced(cwd, rel) {
+    const r = spawnSync('git', ['log', '--diff-filter=A', '--format=%s', '--', rel], {
+        cwd,
+        encoding: 'utf8'
+    });
+    if (r.error || r.status !== 0 || !r.stdout)
+        return null;
+    const subjects = r.stdout.trim().split('\n').filter(Boolean);
+    // Newest-first output; the LAST line is the original introduction (a
+    // delete-and-re-add later in history must not reattribute the file).
+    const first = subjects[subjects.length - 1] ?? '';
+    const m = /\((TASK_\d+)\)\s*$/.exec(first);
+    return m ? m[1] : null;
+}
 /**
  * Run the final gate: static analysis first, then the lockfile consistency
  * checks, then the discovered integration commands, then one boot exercise of
@@ -544,15 +623,23 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     // run may not complete silently carrying an accepted defect. FP-safe by
     // construction (see accept-debt.ts). Best-effort: a ledger read/write failure
     // must never break the gate.
-    const { open: openDebts, resolved } = recheckAcceptDebts(await readAcceptDebts(cwd), {
+    const { open: openRaw, resolved } = recheckAcceptDebts(await readAcceptDebts(cwd), {
         staticOk: stat.ok
     });
     if (resolved.length > 0)
-        await writeAcceptDebts(cwd, openDebts);
+        await writeAcceptDebts(cwd, openRaw);
+    // Conflicting-claim annotation (mx5 run 11): an existence-as-failure debt whose
+    // named file is another task's committed deliverable is a plan defect — surface
+    // the contradiction with the debt so nobody (human or child) treats the claim as
+    // a deletion instruction. Pure git-history lookup; degrades to no annotation.
+    const openDebts = annotateDebtConflicts(openRaw, p => taskThatIntroduced(cwd, p));
     const debtNote = buildAcceptDebtNote(openDebts);
+    // The debt note rides in its OWN field: `reason` stays the mechanical failure
+    // because it seeds the autofix child's prompt (see FinalGateOutcome.reason —
+    // run 11's fix child executed a recorded claim as an instruction).
     const withDebts = (o) => ({
         ...o,
-        reason: `${o.reason}${debtNote}`,
+        ...(debtNote ? { debtNote } : {}),
         openDebts
     });
     if (!stat.ok)
@@ -596,12 +683,67 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
             ran.push(label);
         }
     }
+    // EXECUTE the launch contract (mx5 run 11): every declared script that is
+    // neither boot-class (the boot check below owns those) nor already covered by
+    // the integration commands above RUNS as a one-shot, in declared order —
+    // existence is not launchability (`migrate`/`seed` shipped as first-call
+    // TypeErrors while the gate checked only that they exist). The env-gap
+    // contract extends to missing external INFRASTRUCTURE (no DB/daemon on this
+    // box → skip, not fail); a skip whose script also carries a standing EXCUSE
+    // note (F7) is surfaced as an UNOBSERVED warning — the note may be covering a
+    // real defect the gate could not reach here (run 11's "pre-existing .rows
+    // bug" note excused the exact scripts that shipped broken).
+    const warnings = [];
+    if (declared.length > 0) {
+        const covered = cmds.flatMap(([bin, args]) => (bin === 'bun' || bin === 'npm') && args[0] === 'run' && args[1] ? [args[1]] : []);
+        const skippedLaunch = [];
+        for (const name of runnableDeclaredScripts(declared, covered)) {
+            const cmd = ['bun', ['run', name]];
+            const label = `${cmd[0]} ${cmd[1].join(' ')}`;
+            const r = runGateCommand(cwd, cmd, Math.min(timeoutMs, 180_000), INFRA_GAP_OUTPUT_RE);
+            if (r.outcome === 'skip') {
+                skippedLaunch.push(name);
+                continue;
+            }
+            if (r.outcome === 'fail') {
+                return withDebts({
+                    ok: false,
+                    reason: `launch script: \`${label}\` exited ${r.status}${r.tail ? ` — ${r.tail}` : ''}`
+                });
+            }
+            ran.push(label);
+        }
+        if (skippedLaunch.length > 0) {
+            const notes = parseEnvNotes(await readEnvNotes(cwd)).filter(n => isExcuseNote(n.fact));
+            for (const name of skippedLaunch) {
+                const re = new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i');
+                const excuse = notes.find(n => re.test(n.fact));
+                if (excuse) {
+                    warnings.push(`launch script \`${name}\` could not run here (environment gap) and a `
+                        + `standing excuse note covers it ("${excuse.fact.slice(0, 160)}") — `
+                        + `UNOBSERVED: verify it by hand before trusting the launch surface`);
+                }
+            }
+        }
+    }
     if (boot) {
         const label = `${boot[0]} ${boot[1].join(' ')}`;
         const expectServer = detectsServedApp(cwd, planText);
-        let b = await runBootCheck(cwd, boot, bootGraceMs, { expectServer, deps: bootDeps });
+        // Render check (mx5 runs 8/11): for a served app, load the live page in a
+        // headless browser and judge the RENDERED DOM — curl can't run JS, so a
+        // blank-mount app passed every prior "renders" check. Default to the real
+        // probe; tests inject their own. runRenderCheck env-gap-SKIPs when no
+        // browser exists, so a box without one never gets a false FAIL.
+        const bootDepsWithRender = {
+            ...bootDeps,
+            renderProbe: bootDeps.renderProbe ?? runRenderCheck
+        };
+        let b = await runBootCheck(cwd, boot, bootGraceMs, {
+            expectServer,
+            deps: bootDepsWithRender
+        });
         if (b.outcome === 'orphan-port') {
-            b = await recoverOrphanPort(cwd, boot, b, bootGraceMs, bootDeps, expectServer);
+            b = await recoverOrphanPort(cwd, boot, b, bootGraceMs, bootDepsWithRender, expectServer);
         }
         if (b.outcome === 'fail') {
             return withDebts({ ok: false, reason: `boot check: \`${label}\` ${b.detail}` });
@@ -618,13 +760,19 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
                 reason: `boot check: \`${label}\` could not bind: orphaned process / port already in use${who} (harness condition, not an app fault)`
             });
         }
-        if (b.outcome === 'pass')
+        if (b.outcome === 'pass') {
             ran.push(label);
+            // A listener that served, but whose page could not be OBSERVED to render
+            // (no browser, undeterminable port) → UNOBSERVED warning, not a silent pass.
+            if (b.renderNote)
+                warnings.push(b.renderNote);
+        }
     }
+    const warningNote = warnings.length > 0 ? ` — WARNING: ${warnings.join('; WARNING: ')}` : '';
     return withDebts({
         ok: true,
-        reason: ran.length > 0 ?
+        reason: (ran.length > 0 ?
             `statics + ${ran.map(c => `\`${c}\``).join(', ')} passed`
-            : 'statics passed (integration commands not runnable here)'
+            : 'statics passed (integration commands not runnable here)') + warningNote
     });
 }

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

@@ -3,6 +3,7 @@ import type { GateDeps } from './task-gates.js';
 import { type FinalFixResult } from './final-gate-fix.js';
 import { type AddedLine } from './probe-gaming.js';
 import { type ChangedFile } from './substitution-probe.js';
+import { type TreeChangeSummary } from './write-guard.js';
 /** A function that re-runs a task's implementation turn (AUTOFIX). Injected by the
  *  command so this module stays free of the orchestrators (avoids an import cycle). */
 export type RunTaskFn = GateDeps['runTask'];
@@ -33,6 +34,12 @@ export declare function collectChangedFiles(cwd: string, signal?: AbortSignal):
  * never a blocker. The `.pi-tasks/` bookkeeping is excluded from every git command.
  */
 export declare function collectAddedLines(cwd: string, signal?: AbortSignal): Promise<AddedLine[]>;
+/**
+ * The working tree's current changes as a summary (write-guard shape): what a
+ * write-capable gate child changed, given the tree was clean when it started.
+ * Failures degrade to an empty summary — the guard then has nothing to reject.
+ */
+export declare function collectTreeChanges(cwd: string, signal?: AbortSignal): Promise<TreeChangeSummary>;
 /**
  * Build the gate deps for one command run. `runTask` is the orchestrator's
  * implementation re-runner, injected by the caller. The returned object also drives

package/dist/task/gate-deps.js

@@ -30,6 +30,7 @@ import { extractProhibitions, findProhibitionViolations } from './prohibition-pr
 import { frozenPathsFromSpec, revertFrozenPaths } from './frozen-path-guard.js';
 import { findProbeGaming, parseAddedLines } from './probe-gaming.js';
 import { findSubstitutionSuspects, isTestFile } from './substitution-probe.js';
+import { parseTreeChanges, formatTreeChanges } from './write-guard.js';
 import { findTestRebuiltAssemblies, testAssemblyVerifyFindings } from './test-assembly.js';
 import { runBoundedLintFix } from './lint-fix.js';
 import { captureGitState, reconcileGitState } from './git-state-guard.js';
@@ -121,6 +122,15 @@ export async function collectAddedLines(cwd, signal) {
     }
     return lines;
 }
+/**
+ * The working tree's current changes as a summary (write-guard shape): what a
+ * write-capable gate child changed, given the tree was clean when it started.
+ * Failures degrade to an empty summary — the guard then has nothing to reject.
+ */
+export async function collectTreeChanges(cwd, signal) {
+    const r = await git(cwd, ['status', '--porcelain', '--', '.', EXCLUDE_TASKS_DIR], signal);
+    return r.exitCode === 0 ? parseTreeChanges(r.stdout) : { modified: [], deleted: [], added: [] };
+}
 /** Source extensions whose relative imports the test-assembly probe reasons over. */
 const SOURCE_EXT_RE = /\.(?:[cm]?[jt]sx?)$/;
 /** Bounds so the probe stays cheap on large repos (it reads file text). */
@@ -282,6 +292,13 @@ export function buildGateDeps(params) {
             log(failure ? `=== ${kind} end: FAIL — ${failure} ===` : `=== ${kind} end: ok ===`);
             if (failure)
                 throw new Error(failure);
+            // CAPABILITY-LEVEL diff capture (mx5 run 11): any WRITE-capable
+            // child — decided by its tools, not by which phase spawned it —
+            // gets its tree changes logged, so a future write-capable kind
+            // cannot run invisibly the way the final-fix child's `rm` did.
+            if (/\b(?:edit|bash|write)\b/.test(tools)) {
+                log(`=== ${kind} tree changes: ${formatTreeChanges(await collectTreeChanges(cwd2, sig))} ===`);
+            }
             return r.text;
         }
         finally {
@@ -502,7 +519,26 @@ export function buildGateDeps(params) {
             // shrink guard's discovery is the gate's own (see final-gate.ts).
             gate: c => runFinalIntegrationGate(c),
             discoverLabels: discoverGateCommandLabels,
-            discard: discardTreeEdits
+            discard: discardTreeEdits,
+            // WRITE-GUARD STACK (mx5 run 11: this child ran with free bash and
+            // none of the run-8 guards — it rm'd a sibling task's verified
+            // deliverable and hand-copied a contract to green the lint). Diff
+            // capture happens at the makeGateChild seam; deletion guard +
+            // probe scan reject-and-discard here. The frozen-path deny
+            // (FinalFixDeps.frozenPaths/revertFrozen) is deliberately NOT
+            // wired: per-task fences are task-SCOPED ("this task must not
+            // touch a sibling's territory"), and the measured union over the
+            // run-11 specs would have reverted the one legitimate fix that
+            // run needed (migrate.ts, frozen by its own producing task). Wire
+            // it only when a run-GLOBAL freeze source exists (a design-level
+            // preserve registry), never a per-task union.
+            treeChanges: () => collectTreeChanges(cwd2, signal),
+            probeScan: () => collectAddedLines(cwd2, signal).then(findProbeGaming),
+            log: msg => {
+                void fsp
+                    .appendFile(path.join(tasksDir(cwd2), 'final-gate-debug.log'), `${new Date().toISOString()} ${msg}\n`)
+                    .catch(() => { });
+            }
         }),
         recommend: async (recCtx, cwd2, taskTitle, taskId, failReason) => {
             // Read the same composed spec the verify gate judged against, so the

package/dist/task/launch-contract.d.ts

@@ -11,12 +11,42 @@ export declare function parseScriptLines(text: string): string[];
  * false-flag on it. Deduplicated, case-insensitive.
  */
 export declare function keepGroundedScripts(names: string[], sourceDoc: string): string[];
+/**
+ * DETERMINISTIC RECALL (mx5 run 11): enumerate every backticked, script-name-shaped
+ * token in a paragraph that mentions the word "script", as extraction CANDIDATES.
+ *
+ * The run-11 failure this closes: `test:ct` is backticked in the design's §2 tooling
+ * paragraph, so the grounding guard would have KEPT it — but the extraction child
+ * anchored on §9's one-line summary (`dev`,`build`,`migrate`,`seed`,`test`) and never
+ * emitted it. Grounding can only DROP a candidate, never add one, so recall was
+ * entirely the model's, over a 20KB doc. This makes recall mechanical: the host
+ * enumerates candidates and hands them to the child as an explicit checklist; the
+ * model's job flips from recall (weak) to per-candidate classification (strong).
+ *
+ * The paragraph gate (`\bscripts?\b`, word-bounded so "TypeScript"/"JavaScript"
+ * don't match) is a grounded-context filter, not a tuned knob: a design declares a
+ * script by calling it one. It keeps package-name paragraphs (`hono`, `react`) out
+ * of the checklist so a weak model isn't invited to keep junk the grounding guard
+ * would then bless (every package name is backticked somewhere). A design with no
+ * such paragraph yields no candidates and the prompt is unchanged.
+ */
+export declare function enumerateScriptCandidates(sourceDoc: string): string[];
 /** The stored declared-script list ('' when none recorded). */
 export declare function readLaunchContractRaw(cwd: string): Promise<string>;
 /** The declared script names recorded for this run (deduped, order preserved). */
 export declare function readDeclaredScripts(cwd: string): Promise<string[]>;
 /** Append grounded script names, deduped against what is stored, keeping newest MAX. */
 export declare function appendDeclaredScripts(cwd: string, names: string[]): Promise<void>;
+/**
+ * The declared scripts the final gate must EXECUTE as one-shot commands (mx5 run
+ * 11): everything the launch contract declares that is neither boot-class (the
+ * boot check exercises those) nor already covered by the gate's integration
+ * commands (`covered`, case-insensitive — the test/build-shaped scripts that ran).
+ * Run 11 shipped `migrate` and `seed` broken (`.rows` on a Bun sql array —
+ * TypeError on first call) while the gate checked only that the scripts EXIST;
+ * existence is not launchability.
+ */
+export declare function runnableDeclaredScripts(declared: string[], covered: string[]): string[];
 /**
  * Declared scripts the manifest does NOT expose (case-insensitive). Empty when every
  * declared script is present, or when nothing was declared (no check). This is the
@@ -27,5 +57,10 @@ export declare function missingDeclaredScripts(declared: string[], manifestScrip
  * The plan-time extraction prompt: the design in hand, emit the scripts it declares.
  * Runs with --no-tools (pure extraction). Every emitted name is re-grounded HOST-SIDE
  * (keepGroundedScripts), so a hallucinated script cannot reach the diff.
+ *
+ * `candidates` is enumerateScriptCandidates' mechanical checklist. It exists so the
+ * model cannot MISS a declared script buried far from the design's summary list (the
+ * run-11 `test:ct` hole); the model still classifies each candidate against the
+ * design, and the host grounding still applies. Empty ⇒ the prompt is unchanged.
  */
-export declare const LAUNCH_EXTRACT_PROMPT: (feature: string) => string;
+export declare const LAUNCH_EXTRACT_PROMPT: (feature: string, candidates?: string[]) => string;

package/dist/task/launch-contract.js

@@ -42,7 +42,10 @@ export function parseScriptLines(text) {
     const out = [];
     for (const m of text.matchAll(/^[ \t]*SCRIPT:[ \t]*(.+)$/gim)) {
         // Take the first whitespace/comma-delimited token, stripping backticks/quotes.
-        const raw = m[1].trim().split(/[\s,]+/)[0]?.replace(/[`'"]/g, '') ?? '';
+        const raw = m[1]
+            .trim()
+            .split(/[\s,]+/)[0]
+            ?.replace(/[`'"]/g, '') ?? '';
         if (SCRIPT_NAME_RE.test(raw))
             out.push(raw);
     }
@@ -69,6 +72,44 @@ export function keepGroundedScripts(names, sourceDoc) {
     }
     return kept;
 }
+/**
+ * DETERMINISTIC RECALL (mx5 run 11): enumerate every backticked, script-name-shaped
+ * token in a paragraph that mentions the word "script", as extraction CANDIDATES.
+ *
+ * The run-11 failure this closes: `test:ct` is backticked in the design's §2 tooling
+ * paragraph, so the grounding guard would have KEPT it — but the extraction child
+ * anchored on §9's one-line summary (`dev`,`build`,`migrate`,`seed`,`test`) and never
+ * emitted it. Grounding can only DROP a candidate, never add one, so recall was
+ * entirely the model's, over a 20KB doc. This makes recall mechanical: the host
+ * enumerates candidates and hands them to the child as an explicit checklist; the
+ * model's job flips from recall (weak) to per-candidate classification (strong).
+ *
+ * The paragraph gate (`\bscripts?\b`, word-bounded so "TypeScript"/"JavaScript"
+ * don't match) is a grounded-context filter, not a tuned knob: a design declares a
+ * script by calling it one. It keeps package-name paragraphs (`hono`, `react`) out
+ * of the checklist so a weak model isn't invited to keep junk the grounding guard
+ * would then bless (every package name is backticked somewhere). A design with no
+ * such paragraph yields no candidates and the prompt is unchanged.
+ */
+export function enumerateScriptCandidates(sourceDoc) {
+    const out = [];
+    const seen = new Set();
+    for (const para of sourceDoc.split(/\n[ \t]*\n/)) {
+        if (!/\bscripts?\b/i.test(para))
+            continue;
+        for (const m of para.matchAll(/`([^`\n]+)`/g)) {
+            const tok = m[1].trim();
+            if (!SCRIPT_NAME_RE.test(tok))
+                continue;
+            const key = tok.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(tok);
+        }
+    }
+    return out.slice(0, MAX_SCRIPTS);
+}
 /** The stored declared-script list ('' when none recorded). */
 export async function readLaunchContractRaw(cwd) {
     try {
@@ -117,6 +158,26 @@ export async function appendDeclaredScripts(cwd, names) {
         // best-effort artifact
     }
 }
+/**
+ * Boot-class script names: long-running serve/watch shapes the gate's BOOT check
+ * owns (it needs a listener, a grace window, and a group kill). These are never run
+ * as one-shot gate commands — a `dev` server run synchronously would only burn the
+ * timeout. Suffixed variants (`dev:client`, `start-prod`) are boot-class too.
+ */
+const BOOT_CLASS_RE = /^(?:dev|start|serve|preview|watch)(?:[:_-].*)?$/i;
+/**
+ * The declared scripts the final gate must EXECUTE as one-shot commands (mx5 run
+ * 11): everything the launch contract declares that is neither boot-class (the
+ * boot check exercises those) nor already covered by the gate's integration
+ * commands (`covered`, case-insensitive — the test/build-shaped scripts that ran).
+ * Run 11 shipped `migrate` and `seed` broken (`.rows` on a Bun sql array —
+ * TypeError on first call) while the gate checked only that the scripts EXIST;
+ * existence is not launchability.
+ */
+export function runnableDeclaredScripts(declared, covered) {
+    const have = new Set(covered.map(s => s.toLowerCase()));
+    return declared.filter(n => !BOOT_CLASS_RE.test(n) && !have.has(n.toLowerCase()));
+}
 /**
  * Declared scripts the manifest does NOT expose (case-insensitive). Empty when every
  * declared script is present, or when nothing was declared (no check). This is the
@@ -139,8 +200,13 @@ export function missingDeclaredScripts(declared, manifestScripts) {
  * The plan-time extraction prompt: the design in hand, emit the scripts it declares.
  * Runs with --no-tools (pure extraction). Every emitted name is re-grounded HOST-SIDE
  * (keepGroundedScripts), so a hallucinated script cannot reach the diff.
+ *
+ * `candidates` is enumerateScriptCandidates' mechanical checklist. It exists so the
+ * model cannot MISS a declared script buried far from the design's summary list (the
+ * run-11 `test:ct` hole); the model still classifies each candidate against the
+ * design, and the host grounding still applies. Empty ⇒ the prompt is unchanged.
  */
-export const LAUNCH_EXTRACT_PROMPT = (feature) => [
+export const LAUNCH_EXTRACT_PROMPT = (feature, candidates = []) => [
     'You are recording the PACKAGE/BUILD SCRIPTS the design below says the finished',
     'project MUST expose (the `scripts` a package.json / Makefile / task runner must',
     'declare — e.g. build, test, a migration runner, a seed step, a start/serve command).',
@@ -150,6 +216,18 @@ export const LAUNCH_EXTRACT_PROMPT = (feature) => [
     'DESIGN (the ONLY source — name only scripts the design itself declares):',
     feature.trim(),
     '',
+    ...(candidates.length > 0 ?
+        [
+            'CANDIDATE TOKENS — found mechanically in the design near the word "script".',
+            'This checklist exists ONLY so you do not MISS a declared script; many of these',
+            'tokens are NOT scripts (config option names, tool names). For EACH candidate,',
+            'decide from the design whether it is a script the finished project must expose,',
+            'and emit it only if so. A declared script MISSING from this checklist must still',
+            'be emitted — the checklist is a floor, not a ceiling.',
+            candidates.map(c => `  - ${c}`).join('\n'),
+            ''
+        ]
+        : []),
     'For each script the design declares by name, emit exactly:',
     '  SCRIPT: <name>',
     'one per line, the bare script name only (e.g. `SCRIPT: migrate`). RULES: (1) name',

package/dist/task/phases.d.ts

@@ -59,6 +59,18 @@ export declare function refineExistingFilesBlock(deps: PhaseDeps): Promise<strin
  * no-op. Best-effort: a read fault yields '' rather than blocking the phase.
  */
 export declare function phaseContractsBlock(deps: PhaseDeps): Promise<string>;
+/**
+ * The carried-context blocks a GENERATIVE phase (refine, compose) receives: the
+ * cross-slice contracts plus the carried cross-cutting requirements (mx5 run 11,
+ * goals A/C — `.pi-tasks/requirements.md`, written at plan time). The verbatim
+ * requirement quotes travel INTO every task's spec generation, so a mandated
+ * methodology ("a test lands in the same change as each new route") reaches the
+ * task's GOAL/CONSTRAINTS and its VERIFY — a pointer back to the spec doc
+ * recovered the dropped §10 in only 1 of ~6 applicable run-11 tasks; content
+ * travels, pointers don't. Both blocks are '' outside their runs, so a bare
+ * /task is byte-identical to before.
+ */
+export declare function phaseCarriedBlocks(deps: PhaseDeps): Promise<string>;
 export declare const phaseRefine: (deps: PhaseDeps, raw: string, planContext?: string) => Promise<string>;
 export declare function phaseVerifyTooling(deps: PhaseDeps, research: string): Promise<string>;
 export interface PhaseResearchDeps extends ExternalContextDeps {
@@ -105,7 +117,7 @@ export interface PhaseAutoAnswerDeps {
 export declare function phaseAutoAnswer(deps: PhaseDeps, refined: string, research: string, question: string, autoDeps?: PhaseAutoAnswerDeps): Promise<AutoAnswer>;
 export declare function phaseGrill(deps: PhaseDeps, ctx: ExtensionCommandContext, widgetState: WidgetState, refined: string, research: string): Promise<string>;
 export declare function phaseCompose(deps: PhaseDeps, refined: string, research: string, qa: string): Promise<string>;
-export declare function phaseCritique(deps: PhaseDeps, spec: string, refined: string, qa: string): Promise<string>;
+export declare function phaseCritique(deps: PhaseDeps, spec: string, refined: string, qa: string, planContext?: string): Promise<string>;
 export declare function critiqueWithFallback(d: PhaseDeps, p: PhaseContext): Promise<string>;
 export declare const PHASES: PhaseConfig[];
 export declare function postCommitPhase(phase: PhaseConfig, deps: PhaseDeps, pc: PhaseContext, out: string): Promise<void>;