@mjasnikovs/pi-task 0.14.10 → 0.14.11

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.10",
+    "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",