@mjasnikovs/pi-task 0.37.7 → 0.38.0

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

@@ -538,6 +538,86 @@ export declare function deriveOpenDebts(cwd: string, staticOk: boolean): Promise
  * assumption rather than an observation.
  */
 export declare function rerunDebtVerifyCommand(cwd: string, command: string): VerifyRerunResult;
+/**
+ * Where in the gate a closure scan runs. The two stages are NOT interchangeable
+ * and neither is a scheduling preference:
+ *
+ *   - `pre-discovery` runs before the zero-discovery early return, so a project
+ *     with no runnable command at all still FAILS the scan instead of returning
+ *     UNOBSERVED. A static check needs no runner; that is the whole point of
+ *     deciding it in exactly the environment where every dynamic probe went blind.
+ *   - `post-boot` runs after the dynamic sections, which is where these scans'
+ *     failures have always landed relative to command/launch/boot failures.
+ *     Execution order is the aggregate's tiebreak within a rank, so moving a row
+ *     between stages MOVES it in the user-visible failure list.
+ */
+type ClosureScanStage = 'pre-discovery' | 'post-boot';
+/** Everything a closure scan may look at. Static and synchronous by construction:
+ *  a check that had to spawn something would belong in the dynamic sections
+ *  above, not here — these run on trees where nothing is runnable. */
+interface ClosureScanInput {
+    cwd: string;
+    planText?: string;
+}
+/**
+ * One run-level closure scan: "the shipped tree references/requires something it
+ * does not contain". Each row owns its scan, its formatting, its rank and its
+ * position; the driver owns the fault isolation.
+ */
+interface ClosureScan {
+    /** Stable identity — how the driver and its tests address a row. */
+    id: string;
+    stage: ClosureScanStage;
+    /**
+     * Rank in the aggregated failure list. All three rows are 0 because all three
+     * say some form of "the app cannot be started / cannot serve what it
+     * references / cannot be configured at all", which is the same load-bearing
+     * class as boot/render. It is a per-row FIELD rather than a shared constant
+     * so that a future scan whose finding is NOT of that class can say so in the
+     * table instead of by getting a hand-typed argument right at a call site.
+     */
+    rank: number;
+    /**
+     * Scan and format in one pass, yielding one ready-to-emit failure text per
+     * finding.
+     *
+     * A GENERATOR rather than a function returning an array, for two reasons.
+     * First, the driver's try/catch wraps the ITERATION, so a scan that produces
+     * two findings and then faults still emits those two — precisely what the
+     * three hand-written `for (… ) fail(…)` loops inside try blocks did. Second,
+     * the three scans do not share a result shape (one nullable finding; a list;
+     * a list plus the template set its formatter also needs), and folding scan
+     * and format together lets each row keep its own arity instead of forcing a
+     * lowest-common-denominator result type on all of them.
+     */
+    run: (input: ClosureScanInput) => Iterable<string>;
+}
+/**
+ * The run-level closure scans, in emission order within their stage.
+ *
+ * ONLY checks of this shape belong here. Four other checks in this gate are
+ * deliberately NOT rows: repo-health returns {ok, reason} and formats inline;
+ * the launch-contract diff branches on manifest kind and can emit a NOTE instead
+ * of a failure; the launch config-gap produces neither a failure nor a note but
+ * UN-COUNTS a dynamic observation; and the boot check is an async, stateful,
+ * port-binding exercise. Squeezing any of those in would mean a row type with
+ * more escape hatches than content.
+ */
+declare const CLOSURE_SCANS: ClosureScan[];
+/**
+ * Run every closure scan belonging to `stage`, in table order, feeding each
+ * finding to `fail` at the row's own rank.
+ *
+ * FAULT ISOLATION IS PER ROW, not per stage: each row gets its own try/catch, so
+ * a scanner that throws contributes nothing and every LATER row still runs. One
+ * shared try would silently turn a fault in the first scan into blanket silence
+ * from the rest — the gate would keep working and keep missing defects it can
+ * decide. `scans` is injectable so that property can be tested with a row built
+ * to throw, without mocking the real scanners.
+ */
+declare function runClosureScans(stage: ClosureScanStage, input: ClosureScanInput, fail: (text: string, rank: number) => void, scans?: readonly ClosureScan[]): void;
+export { CLOSURE_SCANS, runClosureScans };
+export type { ClosureScan, ClosureScanInput, ClosureScanStage };
 /**
  * Run the final gate: static analysis first, then the lockfile consistency
  * checks, then the discovered integration commands, then one boot exercise of

package/dist/task/final-gate.js

@@ -1339,6 +1339,98 @@ export function rerunDebtVerifyCommand(cwd, command) {
     }
     return { outcome: 'pass' };
 }
+/**
+ * The run-level closure scans, in emission order within their stage.
+ *
+ * ONLY checks of this shape belong here. Four other checks in this gate are
+ * deliberately NOT rows: repo-health returns {ok, reason} and formats inline;
+ * the launch-contract diff branches on manifest kind and can emit a NOTE instead
+ * of a failure; the launch config-gap produces neither a failure nor a note but
+ * UN-COUNTS a dynamic observation; and the boot check is an async, stateful,
+ * port-binding exercise. Squeezing any of those in would mean a row type with
+ * more escape hatches than content.
+ */
+const CLOSURE_SCANS = [
+    {
+        // Serve-entry closure (mx5 run 18, nexttask 2B): the tree builds a server
+        // app, expects to serve (SPA fallback / static read / a design clause), and
+        // NOTHING anywhere starts a listener — `src/server/index.ts` ended at
+        // `export {app}`, so the product could not be started at all while every
+        // dynamic probe went blind on a docker-less box. Static, deterministic,
+        // milliseconds, and — unlike the boot check — decidable in exactly the
+        // environment where the boot skipped. Hence `pre-discovery`: a project with
+        // no runnable command at all must still fail this, not report UNOBSERVED.
+        id: 'serve-entry',
+        stage: 'pre-discovery',
+        rank: 0,
+        *run({ cwd, planText }) {
+            const found = findMissingServeEntry(cwd, planText);
+            if (found)
+                yield serveEntryGateFailureText(found);
+        }
+    },
+    {
+        // Artifact-production closure (mx5 run 13, PROMPT 2): a runtime file
+        // reference with NO producer anywhere ships silently — the server read
+        // `Bun.file('dist/index.html')` while the build emitted only app.css +
+        // main.js, so every non-API GET 404'd behind 32/32 green checkoffs.
+        // Deterministic scan of the shipped tree (literal refs only, positive
+        // producer evidence required — see artifact-closure.ts); each dangle names
+        // referencer + missing path.
+        id: 'dangling-artifact',
+        stage: 'post-boot',
+        rank: 0,
+        *run({ cwd }) {
+            for (const d of findDanglingArtifacts(cwd))
+                yield danglingGateFailureText(d);
+        }
+    },
+    {
+        // Env-template closure (mx5 run 19, nexttask 10): a shipped source file
+        // requires an env var the shipped template never mentions. `seed.ts` read
+        // `process.env.ADMIN_PHONE`/`ADMIN_PASSWORD`, `.env.example` declared
+        // neither, `bun run seed` exited 1, and the autofix "fixed" it by writing
+        // the GITIGNORED `.env` — so the committed tree still cannot seed and
+        // nothing at run end said why. Same shape and rank as the dangling-artifact
+        // scan above: naming the ARTIFACT that is wrong, statically, instead of only
+        // the command that failed. The formatter needs the template set as well as
+        // the finding, which is why scan and format are folded into one row.
+        // Inert on any tree with no tracked template (ENOENT = pass).
+        id: 'env-template',
+        stage: 'post-boot',
+        rank: 0,
+        *run({ cwd }) {
+            const env = findMissingEnvDeclarations(cwd);
+            for (const m of env.missing)
+                yield envGateFailureText(m, env.templates);
+        }
+    }
+];
+/**
+ * Run every closure scan belonging to `stage`, in table order, feeding each
+ * finding to `fail` at the row's own rank.
+ *
+ * FAULT ISOLATION IS PER ROW, not per stage: each row gets its own try/catch, so
+ * a scanner that throws contributes nothing and every LATER row still runs. One
+ * shared try would silently turn a fault in the first scan into blanket silence
+ * from the rest — the gate would keep working and keep missing defects it can
+ * decide. `scans` is injectable so that property can be tested with a row built
+ * to throw, without mocking the real scanners.
+ */
+function runClosureScans(stage, input, fail, scans = CLOSURE_SCANS) {
+    for (const scan of scans) {
+        if (scan.stage !== stage)
+            continue;
+        try {
+            for (const text of scan.run(input))
+                fail(text, scan.rank);
+        }
+        catch {
+            // best-effort scan — a scanner fault must never break the gate
+        }
+    }
+}
+export { CLOSURE_SCANS, runClosureScans };
 /**
  * Run the final gate: static analysis first, then the lockfile consistency
  * checks, then the discovered integration commands, then one boot exercise of
@@ -1403,23 +1495,9 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
             }
         }
     }
-    // Serve-entry closure (mx5 run 18, nexttask 2B): the tree builds a server app,
-    // expects to serve (SPA fallback / static read / a design clause), and NOTHING
-    // anywhere starts a listener — `src/server/index.ts` ended at `export {app}`, so
-    // the product could not be started at all while every dynamic probe went blind on
-    // a docker-less box. Static, deterministic, milliseconds, and — unlike the boot
-    // check — decidable in exactly the environment where the boot skipped. Rank 0:
-    // "the app cannot be started" is the same load-bearing class as boot/render.
-    // Placed BEFORE the zero-discovery early return on purpose: a project with no
-    // runnable command at all must still fail this, not report UNOBSERVED.
-    try {
-        const noServeEntry = findMissingServeEntry(cwd, planText);
-        if (noServeEntry)
-            fail(serveEntryGateFailureText(noServeEntry), 0);
-    }
-    catch {
-        // best-effort scan — a scanner fault must never break the gate
-    }
+    // Run-level closure scans that must be decided BEFORE the zero-discovery early
+    // return below — a static check needs no runner (CLOSURE_SCANS: 'pre-discovery').
+    runClosureScans('pre-discovery', { cwd, planText }, fail);
     const lockCmds = discoverLockfileChecks(cwd);
     const { cmds } = discoverIntegrationCommands(cwd);
     const boot = discoverBootCommand(cwd);
@@ -1486,7 +1564,8 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     const warnings = [];
     /** UNOBSERVED notes for launch scripts reclassified as CONFIG GAPS (run 20).
      *  They ride in `unobserved`, not `warnings`, so the caller's existing
-     *  recordFinalGateUnobservedDebt writes the debt — never a PASS. */
+     *  `recordDebt(cwd, id, fin.unobserved, 'final-gate')` writes the debt —
+     *  never a PASS. */
     const configGapNotes = [];
     if (declared.length > 0) {
         const covered = cmds.flatMap(([bin, args]) => (bin === 'bun' || bin === 'npm') && args[0] === 'run' && args[1] ? [args[1]] : []);
@@ -1672,37 +1751,11 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     });
     if (gap)
         fail(gap, 0);
-    // Artifact-production closure (mx5 run 13, PROMPT 2): a runtime file
-    // reference with NO producer anywhere ships silently — the server read
-    // `Bun.file('dist/index.html')` while the build emitted only app.css +
-    // main.js, so every non-API GET 404'd behind 32/32 green checkoffs.
-    // Deterministic scan of the shipped tree (literal refs only, positive
-    // producer evidence required — see artifact-closure.ts); each dangle is a
-    // ranked failure naming referencer + missing path. Rank 0: "the app cannot
-    // serve what it references" is the same load-bearing class as boot/render.
-    try {
-        for (const d of findDanglingArtifacts(cwd))
-            fail(danglingGateFailureText(d), 0);
-    }
-    catch {
-        // best-effort scan — a scanner fault must never break the gate
-    }
-    // Env-template closure (mx5 run 19, nexttask 10): a shipped source file
-    // requires an env var the shipped template never mentions. `seed.ts` read
-    // `process.env.ADMIN_PHONE`/`ADMIN_PASSWORD`, `.env.example` declared neither,
-    // `bun run seed` exited 1, and the autofix "fixed" it by writing the GITIGNORED
-    // `.env` — so the committed tree still cannot seed and nothing at run end said
-    // why. Same shape and rank as the dangling-artifact scan one layer up: naming
-    // the ARTIFACT that is wrong, statically, instead of only the command that
-    // failed. Inert on any tree with no tracked template (ENOENT = pass).
-    try {
-        const env = findMissingEnvDeclarations(cwd);
-        for (const m of env.missing)
-            fail(envGateFailureText(m, env.templates), 0);
-    }
-    catch {
-        // best-effort scan — a scanner fault must never break the gate
-    }
+    // The remaining run-level closure scans — "the shipped tree references or
+    // requires something it does not contain" — after every dynamic section, so
+    // their failures keep their historical place in the aggregate (CLOSURE_SCANS:
+    // 'post-boot').
+    runClosureScans('post-boot', { cwd, planText }, fail);
     if (failures.length > 0) {
         // Stable sort: boot/render (rank 0) leads, everything else keeps execution
         // order. One failure keeps the exact single-failure wording; several become

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, recordEnforceKeptDebt, recordEnforceRevertDebt, recordFrozenBlockedDebt, recordCrossTaskDeletionDebt, recordYoloAcceptDebt, recordRootCauseDebt } from './accept-debt.js';
+import { recordDebt } from './accept-debt.js';
 import { recordRepairCandidate } from './root-cause-repair.js';
 import { runRepoHealthCheck, runRepoHealthCheckAsync } from './repo-health-check.js';
 import { runFinalIntegrationGate, discoverGateCommandLabels, discoverGateCommandBodies } from './final-gate.js';
@@ -610,28 +610,11 @@ export function buildGateDeps(params) {
         // Durable per-task gate trail: every verdict/decision lands in the task
         // file's `## gates` section so gate behavior is auditable from artifacts.
         record: (cwd2, taskId, line) => appendGateRecord(cwd2, taskId, line),
-        // Durable ACCEPT-despite-verify-FAIL ledger under .pi-tasks/ (survives
-        // discardEdits): the final integration gate re-checks each debt at run end.
-        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.
-        recordFrozenBlockedDebt: (cwd2, taskId, reason) => recordFrozenBlockedDebt(cwd2, taskId, reason),
-        // Durable cross-task-deletion ledger (PROMPT 2): a sibling's committed
-        // deliverable this task's diff deletes, ACCEPTed into a commit anyway —
-        // the final gate re-checks it (resolved iff the file is back in the tree).
-        recordCrossTaskDeletionDebt: (cwd2, taskId, deletion) => recordCrossTaskDeletionDebt(cwd2, taskId, deletion),
-        // ROOT-CAUSE channel (mx5 run 14 item 5): a FAIL another task's untouched
-        // file caused is recorded as its own debt class and queued as a scoped
-        // repair task, instead of being blamed on — and reverted out of — the task
-        // that merely tripped over it.
-        recordRootCauseDebt: (cwd2, taskId, reason) => recordRootCauseDebt(cwd2, taskId, reason),
+        // Durable defect ledger under .pi-tasks/ (survives discardEdits): every
+        // recorded class — accepted, yolo-accepted, enforce-revert, enforce-kept,
+        // frozen-blocked, cross-task-deletion, root-cause — lands here with its
+        // origin, and the final integration gate re-checks each one at run end.
+        recordDebt,
         recordRepairCandidate: (cwd2, candidate) => recordRepairCandidate(cwd2, candidate),
         // file → introducing task, the provenance half of the discriminator.
         introducedBy: (cwd2, rel) => Promise.resolve(taskThatIntroduced(cwd2, rel)),

package/dist/task/git-state-guard.d.ts

@@ -1,4 +1,4 @@
-import { type SpawnFn } from '../shared/child-process.js';
+import type { SpawnFn } from '../shared/child-process.js';
 export interface GitStateSnapshot {
     /** false → not a usable git worktree; the guard is disabled for this run. */
     ok: boolean;

package/dist/task/git-state-guard.js

@@ -42,7 +42,7 @@ import { readFileSync } from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { runChildDefault } from '../shared/child-process.js';
+import { makeGit } from '../shared/git-runner.js';
 import { isRegenerableArtifact } from './regenerable-artifacts.js';
 /** Keep the gate machinery's own artifacts out of the snapshot and the restore. */
 const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
@@ -109,12 +109,6 @@ function isAlwaysRegenerable(relPath, ctCacheDirs) {
         return true;
     return ctCacheDirs.some(d => p === d || p.startsWith(d + '/'));
 }
-function makeGit(cwd, signal, spawnFn) {
-    return async (args, env) => {
-        const r = await runChildDefault({ command: 'git', args, ...(env ? { env: { ...process.env, ...env } } : {}) }, cwd, signal, { mode: 'text' }, spawnFn);
-        return { stdout: r.stdout, exitCode: r.exitCode };
-    };
-}
 /**
  * Snapshot the worktree content into a tree object via a THROWAWAY index file, so
  * neither the real index nor the stash is touched. Returns null when git cannot

package/dist/task/phases.js

@@ -5,11 +5,8 @@
 import { fileURLToPath } from 'node:url';
 import { docsFocused } from '../workers/docs-core.js';
 import { fetchFocused } from '../workers/fetch-core.js';
-import { formatNpmVersionSection } from '../workers/npm-version.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { findPhantomImports, formatApiCorrections, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
-import { search as defaultSearch } from '../workers/search-core.js';
-import { extractEnrichTargets } from './enrichment.js';
 import { fanoutTimeoutPolicy, workerCarryForward, workerProgressCeilingMs, projectDocsBudget, projectDocsBudgetNotice } from './research-fanout-budget.js';
 import { isIntegrationUnknown } from './unknown-routing.js';
 import { extractUserDirectives, preserveDirectivesBlock, enforceDirectives } from './user-directives.js';
@@ -20,8 +17,7 @@ import { buildOrientation, orientationTier } from './orientation.js';
 import { getConfig } from '../config/config.js';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { formatServiceBlock, formatFreshnessSkippedBlock } from './service-blocks.js';
-import { gatherExternalContext } from './external-context.js';
+import { buildExternalContext, gatherExternalContext } from './external-context.js';
 import { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, GRILL_AUTO_FORMAT_HINT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, MAX_GRILL_QUESTIONS, appendNoThink } from './prompts.js';
 import { appendGateRecord, readSection, removeTaskSection, setTaskSection, updateTaskFrontMatter } from './task-io.js';
 import { applyRefutations } from './refuted-constraint.js';
@@ -1054,83 +1050,44 @@ export async function phaseAutoAnswer(deps, refined, research, question, autoDep
     const docsFocusedFn = autoDeps.docsFocused ?? docsFocused;
     const fetchFocusedFn = autoDeps.fetchFocused ?? fetchFocused;
     try {
-        const enrichTargets = extractEnrichTargets(question);
-        const allTargets = [
-            ...enrichTargets.packages.slice(0, 2).map(pkg => ({ kind: 'pkg', pkg })),
-            ...enrichTargets.urls
-                .slice(0, 2 - Math.min(enrichTargets.packages.length, 2))
-                .map(url => ({ kind: 'url', url }))
-        ];
-        const cappedTargets = allTargets.slice(0, 2);
-        const npmSections = [];
-        const docSections = [];
-        const searchFn = autoDeps.searchFn ?? defaultSearch;
-        const cappedServices = enrichTargets.services.slice(0, 2);
-        // Fan out doc/url focused workers and service searches in parallel —
-        // otherwise the user waits for max(docs, fetch) + search instead of
-        // max(docs, fetch, search) on every grill auto-answer with at least
-        // one service plus a package or url. Mirrors phaseResearch's pattern.
-        const [, serviceResults] = await Promise.all([
-            Promise.all(cappedTargets.map(async (t, idx) => {
-                if (t.kind === 'pkg') {
-                    const r = await docsFocusedFn({
-                        pkg: t.pkg,
-                        query: question,
-                        cwd: deps.cwd,
-                        signal: deps.signal
-                    }).catch(() => null);
-                    if (r?.npmVersion) {
-                        npmSections[idx] = formatNpmVersionSection(r.npmVersion);
-                    }
-                    if (r?.answer) {
-                        docSections[idx] = `### docs: ${t.pkg}\n${r.answer}`;
-                    }
-                }
-                else {
-                    const r = await fetchFocusedFn({
-                        url: t.url,
-                        query: question,
-                        cwd: deps.cwd,
-                        signal: deps.signal
-                    }).catch(() => null);
-                    if (r?.answer) {
-                        docSections[idx] = `### url: ${t.url}\n${r.answer}`;
-                    }
-                }
-            })),
-            Promise.all(cappedServices.map(s => searchFn({
-                query: `${s.name} ${s.query}`,
-                count: 3,
-                signal: deps.signal
-            }).catch(() => null)))
-        ]);
-        const serviceSections = [];
-        const skipped = [];
-        for (let i = 0; i < cappedServices.length; i++) {
-            const s = cappedServices[i];
-            const r = serviceResults[i];
-            if (r === null)
-                continue;
-            if (r.kind === 'no_key') {
-                skipped.push(s.name);
-                continue;
-            }
-            if (r.kind === 'error')
-                continue;
-            serviceSections.push(formatServiceBlock(s.name, `${s.name} ${s.query}`, r.results));
-        }
-        if (skipped.length > 0) {
-            serviceSections.push(formatFreshnessSkippedBlock(skipped));
-        }
-        // npm blocks lead so the model anchors on live version data first.
-        const contextSections = [
-            ...npmSections.filter(Boolean),
-            ...docSections.filter(Boolean),
-            ...serviceSections
-        ];
-        const externalContext = contextSections.length > 0 ?
-            `EXTERNAL CONTEXT\n${contextSections.join('\n\n')}\n\n`
-            : '';
+        // Same assembly as the research phase (see external-context.ts); what
+        // differs is POLICY and the worker variant, and both are arguments now.
+        // The caps exist because this runs per grill question in front of a
+        // waiting user; there is deliberately no version-lookup fan-out, no body
+        // truncation (the focused child already answers in a paragraph) and no
+        // timing sub-step here.
+        //
+        // `groundingBodies` counts the doc/url bodies that made it into the block:
+        // the surviving-unknown routing below asks "did any doc/fetch worker
+        // produce a grounding section?", which is exactly this and nothing about
+        // npm-version or service blocks.
+        let groundingBodies = 0;
+        const countBody = (body) => {
+            if (body !== undefined)
+                groundingBodies += 1;
+            return body;
+        };
+        const externalContext = await buildExternalContext(question, deps, {
+            docs: async (pkg) => {
+                const r = await docsFocusedFn({
+                    pkg,
+                    query: question,
+                    cwd: deps.cwd,
+                    signal: deps.signal
+                });
+                return { npmVersion: r.npmVersion, body: countBody(r.answer || undefined) };
+            },
+            url: async (url) => {
+                const r = await fetchFocusedFn({
+                    url,
+                    query: question,
+                    cwd: deps.cwd,
+                    signal: deps.signal
+                });
+                return { body: countBody(r.answer || undefined) };
+            },
+            search: autoDeps.searchFn
+        }, { targetCap: 2, serviceCap: 2 });
         const basePrompt = externalContext + GRILL_AUTO_ANSWER_PROMPT(refined, research, question);
         let text = await runPhaseChild(deps, 'grill-auto', 'read', basePrompt);
         if (!autoAnswerHasTag(text)) {
@@ -1192,7 +1149,7 @@ export async function phaseAutoAnswer(deps, refined, research, question, autoDep
         // refuse the guess and surface it to the user — carrying the model's
         // best-effort answer as the pre-filled recommendation so the user accepts
         // it with one keystroke or overrides it. Benign unknowns are untouched.
-        const docResolved = docSections.filter(Boolean).length > 0;
+        const docResolved = groundingBodies > 0;
         if (parsed.kind === 'answered' && !docResolved && isIntegrationUnknown(question)) {
             deps.logDebug?.(`grill-auto: integration unknown unresolved by fetch — surfacing to user `
                 + `instead of auto-answering: ${question.replace(/\s+/g, ' ').slice(0, 120)}`);

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

@@ -0,0 +1,127 @@
+/**
+ * run-final-gate — the RUN-LEVEL final integration gate, the twin of task-gates.ts.
+ *
+ * task-gates.ts gates ONE task against its own spec. This gates the WHOLE REPO once,
+ * when every task in a /task-auto run is checked off and BEFORE the run is declared
+ * complete: every task passed its own per-slice gates, but per-slice green has shipped
+ * a dead app twice (mx5 runs 3 & 5 — statics clean, every protected route 500ing). So
+ * the project's OWN whole-repo commands run once here, unaided.
+ *
+ * The stage owns four things the per-task gate has no equivalent of:
+ *
+ *   1. THREE verdicts, not two — PASS / FAIL / UNOBSERVED. A gate that observed
+ *      nothing dynamic is never announced as a pass (final-gate.ts unobservedVerdict).
+ *   2. The run-end ACCEPT-debt report — every defect a task was allowed to ship with,
+ *      surfaced at the last moment anyone will look, and RE-DERIVED against the final
+ *      tree after a converged autofix so the last word is about the tree that shipped.
+ *   3. The resolution loop — Leave-failed (recommended) / Autofix (a bounded,
+ *      model-driven fix pass + gate re-run) / Accept, with the autofix card withdrawn
+ *      after MAX_FINAL_GATE_AUTOFIX so a non-converging fix pass cannot loop forever.
+ *   4. The stranded sub-fixes a non-converging fix pass leaves in the working tree —
+ *      committed on EVERY terminal outcome, because both of them end the run and the
+ *      next `git checkout` would destroy real repairs (mx5 run 14: 13 of them).
+ *
+ * Every terminal outcome is RETURNED, never announced here — same contract as
+ * {@link runGatesForTask}'s GateResult: the caller owns the parent task file's state
+ * and its own resume wording. Nothing in this module touches per-task loop state, so
+ * a resume simply re-enters it and re-runs the gate.
+ */
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import type { CommitResult } from './auto-commit.js';
+import type { FinalGateOutcome } from './final-gate.js';
+import type { FinalGateFixFn } from './gate-deps.js';
+import { type AcceptDebt } from './accept-debt.js';
+/**
+ * The seams this stage drives. A strict subset of what /task-auto builds, and
+ * deliberately narrow: every optional dep absent degrades to a documented earlier
+ * behaviour, so a test supplies only the ones its scenario is about.
+ */
+export interface FinalGateStageDeps {
+    /**
+     * Whole-repo FINAL integration gate: the project's own static checks plus its own
+     * test/build commands, unaided (see final-gate.ts). Absent (tests / gate off) →
+     * the run completes without one, as it did before the gate existed.
+     */
+    finalGate?: (cwd: string, planText?: string) => Promise<FinalGateOutcome>;
+    /**
+     * Bounded model-driven fix pass for a FAIL (see final-gate-fix.ts), offered as the
+     * picker's third option. Runs the fix child, applies the command-shrink guard, and
+     * re-runs the gate; the result's `ok` means the gate now passes. Absent (tests / no
+     * fix wiring) → the picker keeps only Leave-failed / Accept, exactly the
+     * pre-autofix behavior.
+     */
+    finalGateFix?: FinalGateFixFn;
+    /**
+     * Paths currently uncommitted in the working tree (`git status` shape), used to
+     * detect SUB-FIXES a non-converging fix pass left behind (mx5 run 13 PROMPT 4 item
+     * 3). Every task is committed by the time this stage runs, so anything dirty here
+     * is the fix pass's own work. Absent → the stranded-fix handling is skipped
+     * entirely (prior behavior).
+     */
+    pendingChanges?: (cwd: string) => Promise<string[]>;
+    /**
+     * Re-derive the still-open ACCEPT-debt ledger against the tree AS IT IS NOW
+     * (final-gate.ts `deriveOpenDebts`). Needed because the run's "N recorded
+     * verify-FAIL defect(s) are STILL unresolved" report used to be built from the
+     * FIRST gate result and the converged-autofix path then rebuilt the gate outcome
+     * as a bare `{ok, reason}` — so `openDebts` was not merely un-actioned, it was GONE
+     * from the value, and no code path could ever clear, re-check or act on it (mx5 run
+     * 18: four defects reported STILL OPEN at 14:58, one of them fixed by the autofix
+     * that converged at 15:03, and the report never moved).
+     *
+     * `staticOk` is the caller's PROOF about the current statics, never a guess: it is
+     * passed true only where the gate itself just passed them. Absent (tests) → the
+     * post-autofix re-check is skipped and the pre-autofix report stands, exactly the
+     * prior behavior.
+     */
+    recheckOpenDebts?: (cwd: string, staticOk: boolean) => Promise<{
+        openDebts: AcceptDebt[];
+        debtNote?: string;
+        trail?: string[];
+    }>;
+    /** Snapshot the working tree into one commit — used for a converged autofix and
+     *  for the stranded sub-fixes either terminal outcome would otherwise abandon. */
+    commit: (cwd: string, message: string) => Promise<CommitResult>;
+    /** Append one line to the RUN's durable gate trail (`## gates` on the parent task
+     *  file) — the same auditability contract the per-task records carry. Best-effort:
+     *  absent in tests → skipped; a failure never breaks the gate. */
+    record?: (cwd: string, taskId: string, line: string) => Promise<void>;
+}
+/** Inputs that vary per caller. */
+export interface FinalGateStageParams {
+    cwd: string;
+    /** The parent /task-auto id: trail target, notify prefix, commit-message tag. */
+    runId: string;
+    /** The parent plan (the task list), handed to the gate so it can tell a served app
+     *  from a CLI — the boot check requires a listener only for the former (mx5 run 10:
+     *  a CSS watcher satisfied "still alive"). */
+    planText: string;
+    /** How many tasks the run completed — for the completion announcement only. */
+    taskCount: number;
+}
+/**
+ * How the run ended. The caller announces each one with its own resume wording and
+ * owns the parent task file's state — `cancelled` changes no state (a resume
+ * re-enters this stage and runs the gate then), `failed` marks the run failed,
+ * `completed` marks it complete.
+ */
+export type FinalGateStageResult = {
+    kind: 'cancelled';
+    message: string;
+} | {
+    kind: 'failed';
+    message: string;
+} | {
+    kind: 'completed';
+    message: string;
+    level: 'info' | 'warning';
+};
+/**
+ * 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).
+ */
+export declare function runFinalGateStage(active: ExtensionCommandContext, deps: FinalGateStageDeps, p: FinalGateStageParams): Promise<FinalGateStageResult>;