@mjasnikovs/pi-task 0.14.9 → 0.14.11

package/dist/task/auto-orchestrator.js

@@ -17,6 +17,7 @@ import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath, tasks
 import { gitCommitAll } from './auto-commit.js';
 import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-guidelines.js';
 import { runWorker } from '../workers/pi-worker-core.js';
+import { findPhantomImports, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
 import { runPhaseChild, prependHint, formatLoopHint, USER_CANCELLED } from './child-runner.js';
 import { SessionUI, registerBridgeCommand } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
@@ -42,6 +43,19 @@ const MENTION_TRAILING_PUNCT = /[.,;:!?)\]}>"']+$/;
 function mentionPath(token) {
     return token.replace(MENTION_TRAILING_PUNCT, '');
 }
+/**
+ * Fire-and-forget debug line for the PLAN phase (clarify/decompose), which runs
+ * before any task file — hence any per-task `TASK_XXXX-debug.log` — exists. Writes
+ * to `.pi-tasks/plan-debug.log`; the `*-debug.log` suffix keeps it grep-compatible
+ * with the per-task logs. Never throws (mkdir + append are best-effort).
+ */
+function logPlanDebug(cwd, msg) {
+    const line = `${new Date().toISOString()} ${msg}\n`;
+    const dir = tasksDir(cwd);
+    fsp.mkdir(dir, { recursive: true })
+        .then(() => fsp.appendFile(path.join(dir, 'plan-debug.log'), line))
+        .catch(() => { });
+}
 /**
  * Expand any @file references in the feature text by appending each referenced
  * file's contents, so the planning children (clarify, decompose) always see the
@@ -180,7 +194,22 @@ export async function planAuto(ctx, cwd, feature, deps) {
     const ui = new SessionUI(ctx);
     // Inline any @file spec the user referenced so clarify/decompose reason over
     // the real content, not a one-line "Implement @file" that reads as trivial.
-    const featureForModel = await expandFeatureMentions(cwd, feature);
+    const rawFeatureForModel = await expandFeatureMentions(cwd, feature);
+    // Strike phantom runtime specifiers (`bun:sql`) out of the inlined spec BEFORE
+    // clarify/decompose ever see it. Layer A only rewrites the per-task `refined`
+    // text — which is DOWNSTREAM of here: clarify is the first phase and runs on
+    // this raw inline, so the doc's affirmative `bun:sql` is parroted straight into
+    // the very first clarifying question ("instantly bun:sql is back"). Apply the
+    // same deterministic, no-LLM strike at the single point that feeds both planning
+    // children. Silent + no-op when nothing is flagged or the runtime's types aren't
+    // installed.
+    const planPhantoms = findPhantomImports(rawFeatureForModel, cwd);
+    const featureForModel = planPhantoms.length === 0 ?
+        rawFeatureForModel
+        : rewritePhantomSpecifiers(rawFeatureForModel, planPhantoms);
+    if (planPhantoms.length > 0) {
+        logPlanDebug(cwd, `phantom specifiers rewritten in plan spec: ${planPhantoms.map(x => x.spec).join(', ')}`);
+    }
     const answers = [];
     // Plain text of every question already shown, for the duplicate backstop.
     const askedQuestions = [];

package/dist/task/orchestrator.d.ts

@@ -57,6 +57,16 @@ export declare class TaskRunner {
      *  finally block's call. */
     private _disposeWidget;
     private _deliverSpec;
+    /**
+     * The spec as the implementer should receive it (Layer B). Layer A strips phantom
+     * specifiers from the upstream pipeline text, but a residual affirmative can survive
+     * into the composed spec, or arrive when pi expands an `@design.md` the spec
+     * references — and the implementer is told that doc is authoritative. Prepend a
+     * VERIFIED API OVERRIDES banner that outranks the spec for any specifier the
+     * deterministic check proves does not exist. No-op (returns the spec unchanged) when
+     * nothing is flagged or the runtime's types aren't installed.
+     */
+    private _specForDelivery;
 }
 export interface RunSingleTaskOptions {
     /** Await the session going idle after the spec is delivered, so the caller

package/dist/task/orchestrator.js

@@ -26,6 +26,7 @@ import { startWidget } from './widget.js';
 import { publishViewer, publishNotify, registerBridgeCommand, getBridge } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { parseVerifyBlock } from './spec-validation.js';
+import { findDeliveryPhantoms, formatApiOverrideBanner } from '../workers/phantom-imports.js';
 import { titleForDisplay } from './parsers.js';
 import { formatTimings } from './timings.js';
 import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
@@ -261,20 +262,38 @@ export class TaskRunner {
         this._stopWidget = null;
     }
     async _deliverSpec(ctx) {
+        const spec = this._specForDelivery();
         if (this._sendSpec) {
-            await this._sendSpec(this._pc.spec);
+            await this._sendSpec(spec);
             return;
         }
         if (!piApi) {
             throw new Error('extension not initialised (no ExtensionAPI captured)');
         }
         if (ctx.isIdle()) {
-            piApi.sendUserMessage(this._pc.spec);
+            piApi.sendUserMessage(spec);
         }
         else {
-            piApi.sendUserMessage(this._pc.spec, { deliverAs: 'followUp' });
+            piApi.sendUserMessage(spec, { deliverAs: 'followUp' });
         }
     }
+    /**
+     * The spec as the implementer should receive it (Layer B). Layer A strips phantom
+     * specifiers from the upstream pipeline text, but a residual affirmative can survive
+     * into the composed spec, or arrive when pi expands an `@design.md` the spec
+     * references — and the implementer is told that doc is authoritative. Prepend a
+     * VERIFIED API OVERRIDES banner that outranks the spec for any specifier the
+     * deterministic check proves does not exist. No-op (returns the spec unchanged) when
+     * nothing is flagged or the runtime's types aren't installed.
+     */
+    _specForDelivery() {
+        const phantoms = findDeliveryPhantoms(this._pc.spec, this._cwd);
+        const banner = formatApiOverrideBanner(phantoms);
+        if (!banner)
+            return this._pc.spec;
+        this._deps.logDebug?.(`impl-handoff API override banner prepended for: ${phantoms.map(p => p.spec).join(', ')}`);
+        return `${banner}\n\n${this._pc.spec}`;
+    }
 }
 /** Dialog copy for the post-interrupt steering prompt. */
 const STEER_TITLE = 'Paused — steer the model';

package/dist/workers/phantom-imports.d.ts

@@ -36,6 +36,25 @@ export declare function loadRuntimeTypeText(runtime: string, cwd: string): strin
 export declare function findPhantomImports(text: string, cwd: string, loadText?: (runtime: string, cwd: string) => string | null): PhantomImport[];
 /** Render flagged phantoms as an authoritative research section, or '' if none. */
 export declare function formatApiCorrections(phantoms: PhantomImport[]): string;
+/**
+ * A top-of-handoff override banner (Layer B). The deterministic check has proven —
+ * against the installed type definitions — that the spec, or a design doc it
+ * references, names an API that does NOT exist. The implementer is told the spec/doc
+ * is authoritative, so a residual affirmative that survived into the composed spec, or
+ * one re-injected when pi expands an `@design.md` the spec references, can still push it
+ * to write `bun:sql` / a `declare module` shim. This banner sits ABOVE the spec and is
+ * declared to outrank it for these specifiers only. Empty when nothing is flagged.
+ */
+export declare function formatApiOverrideBanner(phantoms: PhantomImport[]): string;
+/**
+ * The phantoms the IMPLEMENTER would actually encounter: those named in the delivered
+ * spec text itself, PLUS those in any @-file the spec references (pi expands that
+ * mention at send time, re-injecting the doc's affirmative). Concatenates the spec with
+ * each readable referenced doc and runs the standard deterministic check over the whole.
+ * Unreadable mentions are skipped; silent when types are absent or nothing is flagged.
+ * Drives the impl-handoff override banner (Layer B).
+ */
+export declare function findDeliveryPhantoms(spec: string, cwd: string): PhantomImport[];
 /**
  * Subtractively rewrite every flagged phantom specifier in `text` to the canonical
  * import the installed types prove, so NO affirmative occurrence of the non-existent

package/dist/workers/phantom-imports.js

@@ -186,6 +186,56 @@ export function formatApiCorrections(phantoms) {
     const lines = phantoms.map(p => `  - ${p.suggestion}`);
     return `API CORRECTIONS\n${lines.join('\n')}`;
 }
+/**
+ * A top-of-handoff override banner (Layer B). The deterministic check has proven —
+ * against the installed type definitions — that the spec, or a design doc it
+ * references, names an API that does NOT exist. The implementer is told the spec/doc
+ * is authoritative, so a residual affirmative that survived into the composed spec, or
+ * one re-injected when pi expands an `@design.md` the spec references, can still push it
+ * to write `bun:sql` / a `declare module` shim. This banner sits ABOVE the spec and is
+ * declared to outrank it for these specifiers only. Empty when nothing is flagged.
+ */
+export function formatApiOverrideBanner(phantoms) {
+    if (phantoms.length === 0)
+        return '';
+    const lines = phantoms.map(p => `  - ${p.suggestion}`);
+    return ('VERIFIED API OVERRIDES — checked against the installed type definitions. These '
+        + 'SUPERSEDE the spec below and any design/spec document it references: the doc is '
+        + 'WRONG about these specifiers, so do NOT follow it here.\n'
+        + lines.join('\n')
+        + '\nUse the corrected import shown for each. Never write the phantom specifier, '
+        + 'and never add a `declare module` shim to make it resolve.');
+}
+// An @-file mention in a spec ("@DESIGN/foo.md", path until whitespace) minus the
+// trailing prose punctuation a sentence adds. Mirrors auto-orchestrator's mention
+// rules so we read the same docs pi re-expands when delivering the spec.
+const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
+const MENTION_TRAILING_PUNCT = /[.,;:!?)\]}>"']+$/;
+/**
+ * The phantoms the IMPLEMENTER would actually encounter: those named in the delivered
+ * spec text itself, PLUS those in any @-file the spec references (pi expands that
+ * mention at send time, re-injecting the doc's affirmative). Concatenates the spec with
+ * each readable referenced doc and runs the standard deterministic check over the whole.
+ * Unreadable mentions are skipped; silent when types are absent or nothing is flagged.
+ * Drives the impl-handoff override banner (Layer B).
+ */
+export function findDeliveryPhantoms(spec, cwd) {
+    let text = spec;
+    const seen = new Set();
+    for (const m of spec.matchAll(MENTION_RE)) {
+        const rel = m[1].replace(MENTION_TRAILING_PUNCT, '');
+        if (rel === '' || seen.has(rel))
+            continue;
+        seen.add(rel);
+        try {
+            text += '\n' + fs.readFileSync(path.resolve(cwd, rel), 'utf8');
+        }
+        catch {
+            // not a readable file — leave the @token, skip it
+        }
+    }
+    return findPhantomImports(text, cwd);
+}
 /**
  * Subtractively rewrite every flagged phantom specifier in `text` to the canonical
  * import the installed types prove, so NO affirmative occurrence of the non-existent

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.14.9",
+    "version": "0.14.11",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",