@mjasnikovs/pi-task 0.14.5 → 0.14.6

package/dist/task/auto-orchestrator.d.ts

@@ -13,6 +13,8 @@ export interface AutoDeps {
         resumeId?: string;
         /** Called with the inner task id once its file exists, before phases. */
         onStart?: (taskId: string) => void | Promise<void>;
+        /** Scope fence naming the sibling steps, forwarded into refine. */
+        planContext?: string;
     }) => Promise<RunSingleTaskResult>;
     /** Snapshot the working tree into one commit after a task passes. */
     commit: (cwd: string, message: string) => Promise<CommitResult>;
@@ -62,6 +64,21 @@ export declare function readableMentions(cwd: string, feature: string): Promise<
  * exactly as before.
  */
 export declare function attachSpecRefs(titles: string[], refs: string[]): string[];
+/**
+ * Build the refine scope fence for step `currentIndex` of an N-step /task-auto
+ * plan. Every per-step pipeline only ever sees its own title, so without this the
+ * refine phase — told "the task title is only a pointer into that spec; follow the
+ * spec" — re-expands the whole referenced design into one task (a real run
+ * implemented all 24 steps under step 1). The fence lists the sibling steps by
+ * number and forbids touching anything they own, so refine bounds this step's
+ * slice. Validated on the local model: with the fence, refine's CONSTRAINTS gained
+ * an explicit per-step deferral list and tool calls dropped 27→11.
+ *
+ * The plan listing strips the threaded "| decisions … | spec …" tail from each
+ * title (keeps the human-readable head) so the model reads clean step names. The
+ * authoritative spec ref still rides on THIS step's own title via attachSpecRefs.
+ */
+export declare function buildScopeFence(titles: string[], currentIndex: number): string;
 /** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
 export declare function planAuto(ctx: ExtensionCommandContext, cwd: string, feature: string, deps: AutoDeps): Promise<string | null>;
 export declare function requestAutoCancel(): void;

package/dist/task/auto-orchestrator.js

@@ -118,6 +118,40 @@ export function attachSpecRefs(titles, refs) {
         return out;
     });
 }
+/**
+ * Build the refine scope fence for step `currentIndex` of an N-step /task-auto
+ * plan. Every per-step pipeline only ever sees its own title, so without this the
+ * refine phase — told "the task title is only a pointer into that spec; follow the
+ * spec" — re-expands the whole referenced design into one task (a real run
+ * implemented all 24 steps under step 1). The fence lists the sibling steps by
+ * number and forbids touching anything they own, so refine bounds this step's
+ * slice. Validated on the local model: with the fence, refine's CONSTRAINTS gained
+ * an explicit per-step deferral list and tool calls dropped 27→11.
+ *
+ * The plan listing strips the threaded "| decisions … | spec …" tail from each
+ * title (keeps the human-readable head) so the model reads clean step names. The
+ * authoritative spec ref still rides on THIS step's own title via attachSpecRefs.
+ */
+export function buildScopeFence(titles, currentIndex) {
+    const n = titles.length;
+    const listing = titles
+        .map((t, i) => {
+        const head = t.split(' | ')[0].trim();
+        const tag = i === currentIndex ? ' (THIS STEP)' : '';
+        return `[${i + 1}]${tag} ${head}`;
+    })
+        .join('\n');
+    return (`PLAN CONTEXT — this task is STEP ${currentIndex + 1} of ${n} in an already-decomposed plan. `
+        + `Each step below is implemented by its OWN separate run; the others are NOT your job and `
+        + `are done in later runs. Implement ONLY the slice named in "Task" below.\n\n`
+        + `The design/spec document the task references describes the WHOLE system across all ${n} `
+        + `steps. Read it to get exact names, types, and signatures for YOUR step and to understand `
+        + `how your step fits — but DO NOT design, scaffold, schema, route, page, query, component, or `
+        + `test anything that belongs to another step listed below. Your GOAL / CONSTRAINTS / `
+        + `KNOWN-UNKNOWNS must cover only THIS step's slice. Do not pull in tables, endpoints, pages, `
+        + `components, or flows owned by a later step.\n\n`
+        + `The full plan (these run separately — do NOT implement them here):\n${listing}`);
+}
 /** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
 export async function planAuto(ctx, cwd, feature, deps) {
     // clarify — sequential & adaptive: ask one question at a time, feeding every
@@ -301,7 +335,8 @@ function defaultDeps(ctx, cwd, signal, title) {
         runTask: (c, cwd2, t, opts) => runSingleTask(c, cwd2, t, {
             waitForImplementation: true,
             resumeId: opts?.resumeId,
-            onStart: opts?.onStart
+            onStart: opts?.onStart,
+            planContext: opts?.planContext
         }),
         commit: (cwd2, message) => getConfig().autoCommit ?
             gitCommitAll(cwd2, message, signal)
@@ -472,6 +507,12 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             }
             const res = await deps.runTask(active, cwd, next.title, {
                 resumeId,
+                // Fence this step against re-expanding the whole referenced spec:
+                // name the sibling steps so refine bounds this step's slice. Only
+                // matters when refine runs fresh (a resumed task past refine ignores
+                // it), but always supplied so a resume that restarts at refine is
+                // fenced too.
+                planContext: buildScopeFence(entries.map(e => e.title), next.index),
                 onStart: resumeId ? undefined : (innerId => stampTaskInProgress(cwd, id, next.index, innerId, next.title))
             });
             active = res.ctx ?? active;

package/dist/task/orchestrator.d.ts

@@ -26,6 +26,7 @@ export declare class TaskRunner {
     private readonly _resumeId;
     private readonly _sendSpec;
     private readonly _onStart;
+    private readonly _planContext;
     private readonly _abort;
     private readonly _startedAt;
     private readonly _widgetState;
@@ -41,7 +42,7 @@ export declare class TaskRunner {
      */
     private readonly _timings;
     private _currentPhaseChildren;
-    constructor(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, resumeId?: string, sendSpec?: (spec: string) => Promise<void>, spawnFn?: SpawnFn, onStart?: (taskId: string) => void | Promise<void>);
+    constructor(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, resumeId?: string, sendSpec?: (spec: string) => Promise<void>, spawnFn?: SpawnFn, onStart?: (taskId: string) => void | Promise<void>, planContext?: string);
     get taskId(): string;
     get signal(): AbortSignal;
     /** Return the current widget state, or null if not started. */
@@ -84,6 +85,13 @@ export interface RunSingleTaskOptions {
      * internal per-task runs, which must stay silent. Default false.
      */
     notifyFinish?: boolean;
+    /**
+     * Scope fence naming the sibling steps of a /task-auto plan. Forwarded into
+     * the refine phase so a single decomposed step bounds its slice instead of
+     * re-expanding the whole referenced spec doc. Set only by /task-auto's loop;
+     * a bare /task leaves it undefined and the refine prompt is unchanged.
+     */
+    planContext?: string;
 }
 export interface RunSingleTaskResult {
     taskId: string;

package/dist/task/orchestrator.js

@@ -51,6 +51,7 @@ export class TaskRunner {
     _resumeId;
     _sendSpec;
     _onStart;
+    _planContext;
     _abort = new AbortController();
     _startedAt;
     _widgetState;
@@ -66,13 +67,14 @@ export class TaskRunner {
      */
     _timings = [];
     _currentPhaseChildren = null;
-    constructor(ctx, cwd, rawPrompt, resumeId, sendSpec, spawnFn, onStart) {
+    constructor(ctx, cwd, rawPrompt, resumeId, sendSpec, spawnFn, onStart, planContext) {
         this._ctx = ctx;
         this._cwd = cwd;
         this._rawPrompt = rawPrompt;
         this._resumeId = resumeId;
         this._sendSpec = sendSpec;
         this._onStart = onStart;
+        this._planContext = planContext;
         this._startedAt = Date.now();
         // We'll populate id/title/phase lazily in run().
         // Placeholder — real values set in run().
@@ -109,7 +111,8 @@ export class TaskRunner {
             refined: '',
             research: '',
             qa: '',
-            spec: ''
+            spec: '',
+            planContext: this._planContext
         };
     }
     get taskId() {
@@ -372,7 +375,7 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                     if (!interrupted)
                         implError = implementationError(newCtx);
                 }
-            }, opts.spawnFn, opts.onStart);
+            }, opts.spawnFn, opts.onStart, opts.planContext);
             await runner.run();
             taskId = runner.taskId;
         }

package/dist/task/phases.d.ts

@@ -23,6 +23,13 @@ export interface PhaseContext {
     research: string;
     qa: string;
     spec: string;
+    /**
+     * Scope fence for a task that is one step of a /task-auto plan: names the
+     * sibling steps so refine bounds this task's slice instead of re-expanding the
+     * whole spec doc. Undefined for a bare /task run (prompt unchanged). Threaded
+     * only into refine — its scoped output carries the boundary downstream.
+     */
+    planContext?: string;
 }
 export type OutputField = 'refined' | 'research' | 'qa' | 'spec';
 export interface PhaseConfig {
@@ -35,7 +42,7 @@ export interface PhaseConfig {
 export declare function extractToolingCommands(research: string): string[] | null;
 /** Replace the TOOLING section in a research string with a VERIFIED-TOOLING section. */
 export declare function replaceToolingWithVerified(research: string, verifiedCommands: string[]): string;
-export declare const phaseRefine: (deps: PhaseDeps, raw: string) => 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 {
     getFileInventory?: (cwd: string, signal?: AbortSignal) => Promise<string>;

package/dist/task/phases.js

@@ -61,7 +61,7 @@ export function replaceToolingWithVerified(research, verifiedCommands) {
     return replaced;
 }
 // ─── Phase functions ─────────────────────────────────────────────────────────
-export const phaseRefine = (deps, raw) => runPhaseWithLoopGuard(deps, 'refine', 'read', hint => prependHint(hint, appendNoThink(REFINE_PROMPT(raw))));
+export const phaseRefine = (deps, raw, planContext) => runPhaseWithLoopGuard(deps, 'refine', 'read', hint => prependHint(hint, appendNoThink(REFINE_PROMPT(raw, planContext))));
 export async function phaseVerifyTooling(deps, research) {
     const commands = extractToolingCommands(research);
     if (!commands || commands.length === 0) {
@@ -650,7 +650,7 @@ export const PHASES = [
         name: 'refine',
         section: 'refined prompt',
         field: 'refined',
-        run: (d, p) => phaseRefine(d, p.rawPrompt)
+        run: (d, p) => phaseRefine(d, p.rawPrompt, p.planContext)
     },
     {
         name: 'research',

package/dist/task/prompts.d.ts

@@ -35,7 +35,19 @@ export declare function appendNoThink(prompt: string): string;
  * right *content* (identifying nouns) rather than trusting the model on length.
  */
 export declare const COMPRESS_LABEL_PROMPT: (title: string, maxChars: number) => string;
-declare const REFINE_PROMPT: (raw: string) => string;
+/**
+ * Optional scope fence for a task that is ONE step of a /task-auto plan. Prepended
+ * verbatim ahead of the refine body so the model reads the step boundary as
+ * authoritative context before it expands the (whole-system) spec doc. Empty for a
+ * bare /task run, which keeps that prompt byte-for-byte unchanged. The caller
+ * (auto-orchestrator) builds the listing; this prompt only positions it.
+ *
+ * Without it, refine is told "the task title is only a pointer into that spec —
+ * follow the spec" with no signal that the other steps exist, so a one-step
+ * "Scaffold …" title re-expands the entire design into one task (validated: a real
+ * /task-auto run implemented all 24 steps under step 1).
+ */
+declare const REFINE_PROMPT: (raw: string, planContext?: string) => string;
 declare const RESEARCH_READ_ONLY_CONSTRAINT = "IMPORTANT: You are ONLY allowed to READ. Do NOT create, modify, or delete any files. Use the read, grep, find, and ls tools to inspect the repo.";
 declare const RESEARCH_FILES_PROMPT: (refined: string) => string;
 declare const RESEARCH_APIS_PROMPT: (refined: string) => string;

package/dist/task/prompts.js

@@ -49,7 +49,19 @@ Rules:
 
 TITLE:
 ${title}`;
-const REFINE_PROMPT = (raw) => `You receive a user's task description for an AI coding agent. Rewrite it to be unambiguous and actionable.
+/**
+ * Optional scope fence for a task that is ONE step of a /task-auto plan. Prepended
+ * verbatim ahead of the refine body so the model reads the step boundary as
+ * authoritative context before it expands the (whole-system) spec doc. Empty for a
+ * bare /task run, which keeps that prompt byte-for-byte unchanged. The caller
+ * (auto-orchestrator) builds the listing; this prompt only positions it.
+ *
+ * Without it, refine is told "the task title is only a pointer into that spec —
+ * follow the spec" with no signal that the other steps exist, so a one-step
+ * "Scaffold …" title re-expands the entire design into one task (validated: a real
+ * /task-auto run implemented all 24 steps under step 1).
+ */
+const REFINE_PROMPT = (raw, planContext) => `${planContext ? planContext + '\n\n---\n\n' : ''}You receive a user's task description for an AI coding agent. Rewrite it to be unambiguous and actionable.
 
 Output structure (four sections, exact headings, in this order):
 
@@ -116,6 +128,8 @@ NPM PACKAGES — use pi-worker-docs, NOT file reads: for any third-party npm pac
 
 PROJECT SOURCE — use pi-worker-docs with module ".", NOT file reads: for any function, class, type, or interface defined in THIS project's own .ts/.tsx source (e.g. "what does requireAuth check?", "what does CreateListingSchema look like?", "what does the listings query module export?"), call \`pi-worker-docs(".", query)\` instead of reading the file. The tool indexes all git-tracked source files and returns only the relevant chunks — far cheaper than reading whole files.
 
+RUNTIME BUILTINS — verify, do NOT echo: a task (or the spec doc it references) may name a runtime/builtin import like \`bun:sql\`, \`bun:sqlite\`, \`node:fs\`, or \`Bun.password\`. A runtime exposes only a small FIXED set of \`<runtime>:<submodule>\` modules, and a spec doc can confidently name one that does not exist. Before you list ANY \`<pkg>:<sub>\` specifier, confirm it with \`pi-worker-docs\` (e.g. \`pi-worker-docs("bun:sql", "sql tagged template and SQL class — the import")\` — the tool resolves the runtime's real types) and emit the CANONICAL import the types actually prove, NOT the string copied from the task. Concretely: Bun's SQL client is \`import { sql } from "bun"\` (or \`Bun.sql\` / \`new SQL()\`) — there is NO \`bun:sql\` module. Never pass an unverified colon-specifier through to the APIS list; a phantom import laundered here becomes fabricated \`declare module\` shims in the implementation.
+
 APIS owns symbols and commands BY NAME ONLY. Do NOT include any file path or path fragment — no \`package.json\`, no \`./src/foo.ts\`, no \`package.json#scripts.lint\`. If the symbol is a script defined in package.json, write the invocation (\`npm run lint\`), not its location. If the symbol is a config file, it does not belong in APIS at all — it belongs in FILES.
 
 RELEVANCE — read carefully: list ONLY the symbols the agent will call, implement, modify, or directly depend on for THIS task. Do NOT enumerate the project's entire public surface or dump every exported function in a touched file. A symbol unrelated to the task does not belong here just because it sits in the same module. Keep the smallest sufficient set: include every symbol the task actually exercises and nothing more. There is no fixed limit — list as many as the task truly needs and no padding beyond that.

package/dist/workers/docs-core.js

@@ -4,7 +4,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { openCache as defaultOpenCache } from './docs-cache.js';
 import { ensureIndexed as defaultEnsureIndexed } from './docs-index.js';
-import { resolvePackage as defaultResolvePackage, ResolveError, detectTypesRedirect, typesPackageName, hasTypeFiles, isDtsFile } from './docs-resolve.js';
+import { resolvePackage as defaultResolvePackage, ResolveError, detectTypesRedirect, typesPackageName, hasTypeFiles, isDtsFile, splitRuntimeNamespace } from './docs-resolve.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
 import { getPiInvocation } from '../shared/pi-invocation.js';
@@ -97,21 +97,27 @@ export async function docsRaw(input) {
     const openCache = input.openCache ?? defaultOpenCache;
     const spawn = input.spawn ?? defaultSpawn;
     const npmVersionLookup = input.npmVersionLookup ?? defaultNpmVersionLookup;
+    // A runtime builtin specifier (`bun:sql`, `node:fs`) is typed by the runtime's
+    // own types package, not a literal package of that colon-name — so resolve the
+    // runtime instead. This is what turns a `bun:sql` lookup into Bun's real SQL
+    // surface (`declare module "bun"` → `const sql: SQL`) rather than an
+    // `invalid_name` error, and it lets the docs tool disprove a phantom submodule.
+    const requested = splitRuntimeNamespace(input.pkg)?.runtime ?? input.pkg;
     // Fire the npm registry lookup in parallel with resolve/index/retrieve.
     // It returns null on any failure, so it never blocks the local pipeline.
-    const npmVersionPromise = npmVersionLookup(extractParentPackage(input.pkg), {
+    const npmVersionPromise = npmVersionLookup(extractParentPackage(requested), {
         signal: input.signal
     }).catch(() => null);
     // Step 1: resolve package
     let pkg;
     let autoInstalled = false;
     try {
-        pkg = resolvePackage(input.pkg, input.cwd);
+        pkg = resolvePackage(requested, input.cwd);
     }
     catch (firstErr) {
         if (firstErr instanceof ResolveError && firstErr.kind === 'not_installed') {
             // auto-install
-            const parentPkg = extractParentPackage(input.pkg);
+            const parentPkg = extractParentPackage(requested);
             const installResult = await runAutoInstall(spawn, parentPkg, undefined);
             if (!installResult.success) {
                 return {
@@ -124,7 +130,7 @@ export async function docsRaw(input) {
             }
             autoInstalled = true;
             try {
-                pkg = resolvePackage(input.pkg, installResult.installDir);
+                pkg = resolvePackage(requested, installResult.installDir);
             }
             catch (retryErr) {
                 if (retryErr instanceof ResolveError) {
@@ -166,7 +172,7 @@ export async function docsRaw(input) {
     // @types/<name> + triple-slash `<reference types>` chain to the package that
     // actually holds the declarations (e.g. bun -> @types/bun -> bun-types).
     // Best-effort: any failure leaves the original resolution untouched.
-    pkg = await resolveTypeSource(pkg, input.pkg, input.cwd, spawn, resolvePackage, input.signal);
+    pkg = await resolveTypeSource(pkg, requested, input.cwd, spawn, resolvePackage, input.signal);
     // Step 2: open cache
     let cache = null;
     let cacheError;

package/dist/workers/docs-resolve.d.ts

@@ -11,6 +11,18 @@ export declare class ResolveError extends Error {
     readonly kind: 'not_installed' | 'invalid_name';
     constructor(kind: 'not_installed' | 'invalid_name', message: string);
 }
+/**
+ * Split a runtime builtin specifier (`bun:sql`, `node:fs/promises`) into its
+ * runtime and submodule. Returns null for ordinary specifiers (including scoped
+ * names, which legitimately contain no colon). The resolver maps the runtime to
+ * its types package via the existing @types redirect chain (bun -> bun-types,
+ * node -> @types/node), so a `bun:sql` query lands on Bun's real SQL surface
+ * (`declare module "bun"` → `const sql: SQL`) instead of erroring `invalid_name`.
+ */
+export declare function splitRuntimeNamespace(spec: string): {
+    runtime: string;
+    sub: string;
+} | null;
 export declare function resolvePackage(moduleName: string, cwd: string): ResolvedPackage;
 /** Conventional DefinitelyTyped package for a runtime package that ships no
  *  types of its own. `bun` -> `@types/bun`, `@scope/x` -> `@types/scope__x`.

package/dist/workers/docs-resolve.js

@@ -20,6 +20,30 @@ function isValidModuleName(name) {
         return false;
     return MODULE_NAME_RE.test(name);
 }
+// Runtimes whose builtin `<runtime>:<sub>` imports are typed by the runtime's own
+// types package, not by a literal package named "<runtime>:<sub>". `node:fs` and
+// `bun:sqlite` are real imports, but their declarations live in @types/node and
+// bun-types — and a phantom like `bun:sql` (no such submodule) is only disprovable
+// by resolving the runtime and finding the symbol absent. Either way the docs
+// lookup target is the runtime, never the colon-name.
+const RUNTIME_NAMESPACES = new Set(['bun', 'node', 'deno']);
+/**
+ * Split a runtime builtin specifier (`bun:sql`, `node:fs/promises`) into its
+ * runtime and submodule. Returns null for ordinary specifiers (including scoped
+ * names, which legitimately contain no colon). The resolver maps the runtime to
+ * its types package via the existing @types redirect chain (bun -> bun-types,
+ * node -> @types/node), so a `bun:sql` query lands on Bun's real SQL surface
+ * (`declare module "bun"` → `const sql: SQL`) instead of erroring `invalid_name`.
+ */
+export function splitRuntimeNamespace(spec) {
+    const m = /^([a-z]+):([a-z0-9./_-]+)$/i.exec(spec);
+    if (!m)
+        return null;
+    const runtime = m[1].toLowerCase();
+    if (!RUNTIME_NAMESPACES.has(runtime))
+        return null;
+    return { runtime, sub: m[2] };
+}
 function parentPackageName(moduleName) {
     if (moduleName.startsWith('@')) {
         const parts = moduleName.split('/');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.14.5",
+    "version": "0.14.6",
     "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",