@mjasnikovs/pi-task 0.14.4 → 0.14.6

package/README.md

@@ -148,7 +148,7 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | **compress reasoning** | After each message, compresses the model's `<think>` blocks down to the decisions/constraints/facts that matter later — keeping long local-model runs from drowning their own context in self-talk. |
 | **auto-commit** | Snapshots the working tree into one git commit per `/task-auto` sub-task (see above). |
 | **orientation** | Pre-reads the project's core files (manifest, config, domain types, schema, entrypoints, API surface) once and hands the contents to the read-heavy research workers, so they skip re-discovering the same files cold. Bounded by a hard byte budget; applied only where it helps (FILES/APIS workers). |
-| **enforce guidelines** _(off by default)_ | Before each `/task-auto` commit, re-checks the sub-task's work against the project's `AGENTS.md` / `CLAUDE.md` (in the working directory). Local models drift and skip those rules, so a fresh pass of the same local model — with edit tools — reads the diff, fixes any violations in place, and returns a verdict. A violation it can't clear (or a pass that can't run) **blocks the commit and stops the run** so non-compliant work is never snapshotted; fix and `/task-auto-resume`. Adds one extra local-model pass per task, so it's opt-in. |
+| **enforce guidelines** _(off by default)_ | After each `/task-auto` task is committed, re-checks that commit's work against the project's `AGENTS.md` / `CLAUDE.md` (in the working directory). Local models drift and skip those rules, so a fresh pass of the same local model — with edit tools — reads the **last commit's** diff, fixes any violations in place, and returns a verdict. Its fixes are committed **separately** as an `ENFORCE GUIDELINES` commit on top of the task commit, so guideline corrections are an independent, auditable diff. A violation it can't clear (or a pass that can't run) only **warns** — the task commit already landed, so the run continues. Skipped when nothing was committed for the task. Adds one extra local-model pass per task, so it's opt-in. |
 
 ## Configuration
 

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;
@@ -498,31 +539,14 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 announceDone(active, `${id} stopped at "${next.title}"${why} — fix and run /task-auto-resume.`, 'error');
                 return;
             }
-            // Before checking the task off or committing, hold the work to the
-            // project's AGENTS.md / CLAUDE.md rules. Local models drift and skip
-            // those guidelines, so the enforcement pass re-reads the diff with the
-            // same local model (edit tools enabled) and fixes violations in place.
-            // A non-clean verdict — or a pass that could not run — blocks the
-            // commit and fails the task: non-compliant work is never snapshotted,
-            // and the run pauses for /task-auto-resume. (No-op when the feature is
-            // off, when there are no guideline files, or in tests with no enforce
-            // dep.) Fixes it makes are folded into this task's snapshot below.
-            if (deps.enforce) {
-                active.ui.notify(`${id}: enforcing AGENTS.md/CLAUDE.md on "${next.title}"…`, 'info');
-                const verdict = await deps.enforce(active, cwd, next.title);
-                if (!verdict.ok) {
-                    await updateTaskFrontMatter(cwd, id, { state: 'failed' });
-                    announceDone(active, `${id} stopped at "${next.title}" — ${verdict.reason ?? 'guideline check failed'} — fix and run /task-auto-resume.`, 'error');
-                    return;
-                }
-            }
             // res.ok === true means runner.run() completed, so res.taskId is the
             // allocated TASK_NNNN id (never empty here). checkOffTask tolerates an
             // empty id by writing a plain checked line, but that path is unreachable.
             await checkOffTask(cwd, id, next.index, res.taskId, next.title);
             // Commit the task's work (and the just-written check-off) as one
-            // snapshot. Best-effort: a failed/empty commit only warns — the task
-            // already passed, so the run continues.
+            // snapshot FIRST — before guideline enforcement — so a passing task is
+            // durably recorded no matter what enforcement later finds. Best-effort:
+            // a failed/empty commit only warns; the task already passed.
             const message = `task: ${next.title} (${res.taskId})`;
             const commit = await deps.commit(cwd, message);
             if (commit.committed) {
@@ -531,6 +555,31 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             else {
                 active.ui.notify(`${id}: not committed (${commit.reason ?? 'unknown'}) — continuing.`, 'warning');
             }
+            // With the task committed, hold its work to the project's AGENTS.md /
+            // CLAUDE.md rules. Local models drift and skip those guidelines, so the
+            // enforcement pass re-reads THE LAST COMMIT's diff with the same local
+            // model (edit tools enabled) and fixes violations in place; those fixes
+            // are then committed SEPARATELY under an "ENFORCE GUIDELINES" commit so
+            // they form an independent, auditable diff on top of the task commit.
+            // A non-clean verdict only warns — the task commit already landed, so
+            // the run continues. Skipped when nothing was committed this round
+            // (autoCommit off or an empty commit): there is no "last commit" of this
+            // task's work to verify. (Also a no-op when the feature is off, when
+            // there are no guideline files, or in tests with no enforce dep.)
+            if (deps.enforce && commit.committed) {
+                active.ui.notify(`${id}: enforcing AGENTS.md/CLAUDE.md on "${next.title}"…`, 'info');
+                const verdict = await deps.enforce(active, cwd, next.title);
+                if (!verdict.ok) {
+                    active.ui.notify(`${id}: guideline enforcement on "${next.title}" — ${verdict.reason ?? 'not clean'} — continuing.`, 'warning');
+                }
+                // Commit whatever the pass fixed as its own snapshot. A no-op when
+                // the pass made no edits (gitCommitAll reports nothing to commit),
+                // so a clean task adds no empty commit — only announce a real one.
+                const enforceCommit = await deps.commit(cwd, `ENFORCE GUIDELINES: ${next.title} (${res.taskId})`);
+                if (enforceCommit.committed) {
+                    active.ui.notify(`${id}: committed guideline fixes for "${next.title}".`, 'info');
+                }
+            }
         }
     }
     catch (err) {

package/dist/task/enforce-guidelines.d.ts

@@ -11,7 +11,7 @@ export declare const GUIDELINE_FILENAMES: readonly ["AGENTS.md", "CLAUDE.md"];
  *    in one real run (see enforce-debug.log analysis). This is the load-bearing
  *    removal: dropping `write` is what stops the runaway file creation.
  *  - No `grep`/`find`/`ls` → the pass cannot enumerate or roam the tree; it is
- *    handed the explicit, closed list of changed files (see captureDiff) and is
+ *    handed the explicit, closed list of changed files (see captureCommitDiff) and is
  *    told to edit only those.
  *  - `read` IS allowed: the model genuinely needs it — to re-read a file after
  *    editing to confirm the fix landed, and to read a neighbouring file for the
@@ -88,28 +88,30 @@ export interface EnforceChildResult {
  */
 export declare function classifyEnforceChildFailure(r: EnforceChildResult): string | null;
 /**
- * Capture the work to verify as text: the tracked diff against HEAD followed by
- * the COMPLETE list of changed files — tracked-modified ∪ new (untracked) — that
+ * Capture the LAST COMMIT's work to verify as text: the unified diff of HEAD
+ * against its parent followed by the list of files that commit changed — the set
  * the child should read and is allowed to edit.
  *
+ * This runs AFTER the task's auto-commit, so the change set is whatever HEAD
+ * introduced (`HEAD~1..HEAD`). New files created by the task appear in that diff
+ * as additions, so — unlike the pre-commit working-tree capture this replaced —
+ * there is no separate untracked/new-files section to chase. On a root commit
+ * (no `HEAD~1`) the diff is taken against the empty tree so the first commit is
+ * still fully verifiable.
+ *
  * The child has a `read` tool, so file contents are NOT inlined here: it reads
  * each listed file itself (and re-reads after editing to confirm). The list is the
  * scoping signal — it tells the model the closed set of files to touch so it edits
- * only the change set rather than roaming. Validated against the local model:
- * inlining full bodies bought nothing (it read the files by name regardless).
- *
- * Non-destructive — it does not touch the index, so the later `git add -A` in
- * gitCommitAll still stages everything (including fixes the enforcement child
- * makes).
+ * only the change set rather than roaming.
  *
  * The `.pi-tasks/` directory is excluded from every git command. Those task files
- * are committable (tracked) by design, so they show up in `git diff HEAD` and
- * `git ls-files --others` — git does not honor the fd/ripgrep `.ignore` that keeps
- * them out of the worker's find/grep discovery. Without this pathspec the enforce
- * child is handed its own TASK_*.md / TASK_AUTO_*.md bookkeeping as "changes to
- * verify" and edits them, corrupting the front matter mid-run.
+ * are committable (tracked) by design, so they ride into the commit's diff — git
+ * does not honor the fd/ripgrep `.ignore` that keeps them out of the worker's
+ * find/grep discovery. Without this pathspec the enforce child is handed its own
+ * TASK_*.md / TASK_AUTO_*.md bookkeeping as "changes to verify" and edits them,
+ * corrupting the front matter mid-run.
  */
-export declare function captureDiff(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<string>;
+export declare function captureCommitDiff(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<string>;
 export interface EnforcementDeps {
     cwd: string;
     signal?: AbortSignal;

package/dist/task/enforce-guidelines.js

@@ -2,19 +2,21 @@
  * Guideline enforcement for /task-auto.
  *
  * Local models drift: they skip the rules written in AGENTS.md / CLAUDE.md even
- * when those files sit right next to the code. After a /task-auto sub-task's
- * implementation turn settles — but BEFORE its per-task commit — this runs a
+ * when those files sit right next to the code. A /task-auto sub-task's work is
+ * auto-committed AS SOON AS the implementation turn passes; THEN this runs a
  * fresh child pi (the same local model that did the work) that is handed the
- * project's guideline files, the task's diff, and the list of changed files. With
- * read + edit tools (and nothing else) it reads those files, fixes any violations
- * in place, and reports a CLEAN / VIOLATION verdict. It cannot create files or run
+ * project's guideline files and the diff of THAT LAST COMMIT. With read + edit
+ * tools (and nothing else) it reads the committed files, fixes any violations in
+ * place, and reports a CLEAN / VIOLATION verdict. It cannot create files or run
  * anything: no `write` (so it can't scaffold junk) and no `grep`/`find`/`ls` (so it
  * can't roam the tree) — see ENFORCE_TOOLS.
  *
- * A VIOLATION (or an enforcement pass that cannot confirm CLEAN) blocks the
- * commit and fails the task, so non-compliant work is never snapshotted — the
- * run pauses for /task-auto-resume. This is deliberately strict: the whole
- * point is that "the model probably followed the rules" is not good enough.
+ * The fixes it makes are committed SEPARATELY by the orchestrator under an
+ * "ENFORCE GUIDELINES" commit, so guideline corrections are an independent,
+ * auditable diff that sits on top of the task commit. A VIOLATION it could not
+ * fix (or a pass that cannot confirm CLEAN) is surfaced as a warning — the task
+ * commit already landed, so the run continues rather than pausing. The outcome's
+ * `ok` flag therefore drives a warn-or-not decision, not a hard gate.
  *
  * Gated by the `enforceGuidelines` config flag. With the flag off, or with no
  * guideline files in the working directory, enforcement is a pass (ok: true).
@@ -36,7 +38,7 @@ export const GUIDELINE_FILENAMES = ['AGENTS.md', 'CLAUDE.md'];
  *    in one real run (see enforce-debug.log analysis). This is the load-bearing
  *    removal: dropping `write` is what stops the runaway file creation.
  *  - No `grep`/`find`/`ls` → the pass cannot enumerate or roam the tree; it is
- *    handed the explicit, closed list of changed files (see captureDiff) and is
+ *    handed the explicit, closed list of changed files (see captureCommitDiff) and is
  *    told to edit only those.
  *  - `read` IS allowed: the model genuinely needs it — to re-read a file after
  *    editing to confirm the fix landed, and to read a neighbouring file for the
@@ -78,20 +80,21 @@ export async function discoverGuidelines(cwd, readFile = p => fsp.readFile(p, 'u
  */
 export function buildEnforcePrompt(rulesText, diff) {
     return [
-        'You are a strict guideline-enforcement pass running after an AI coding agent',
-        'finished a task but before its work is committed. The agent is known to skip',
-        'project rules, so do not trust that it followed them — verify against the changes.',
+        'You are a strict guideline-enforcement pass running right after an AI coding',
+        'agent finished a task and committed it. The agent is known to skip project',
+        'rules, so do not trust that it followed them — verify against the changes.',
         '',
         'You have a `read` tool and an `edit` tool — nothing else. You CANNOT run',
         'commands, run lint/tsc/tests, or create files. Read the changed files listed',
         'below to inspect them; you may also read a neighbouring file when you need the',
         'correct import or type. But EDIT ONLY the changed files listed below — do not',
-        'create new files and do not modify anything outside that set.',
+        'create new files and do not modify anything outside that set. Your fixes will',
+        'be committed separately, so make them count.',
         '',
         'PROJECT GUIDELINES (from this repository):',
         rulesText,
         '',
-        'CHANGES JUST MADE (verify these specifically against the rules):',
+        'CHANGES IN THE LAST COMMIT (verify these specifically against the rules):',
         diff.trim().length > 0 ? diff : '(no textual diff captured — nothing to verify)',
         '',
         'Your job:',
@@ -156,66 +159,60 @@ export function classifyEnforceChildFailure(r) {
     return null;
 }
 /**
- * Capture the work to verify as text: the tracked diff against HEAD followed by
- * the COMPLETE list of changed files — tracked-modified ∪ new (untracked) — that
+ * The git "empty tree" object — the canonical base for diffing a ROOT commit
+ * (one with no parent). Diffing `HEAD` against it renders the whole first commit
+ * as additions, so a root commit still produces a verifiable diff.
+ */
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/**
+ * Capture the LAST COMMIT's work to verify as text: the unified diff of HEAD
+ * against its parent followed by the list of files that commit changed — the set
  * the child should read and is allowed to edit.
  *
+ * This runs AFTER the task's auto-commit, so the change set is whatever HEAD
+ * introduced (`HEAD~1..HEAD`). New files created by the task appear in that diff
+ * as additions, so — unlike the pre-commit working-tree capture this replaced —
+ * there is no separate untracked/new-files section to chase. On a root commit
+ * (no `HEAD~1`) the diff is taken against the empty tree so the first commit is
+ * still fully verifiable.
+ *
  * The child has a `read` tool, so file contents are NOT inlined here: it reads
  * each listed file itself (and re-reads after editing to confirm). The list is the
  * scoping signal — it tells the model the closed set of files to touch so it edits
- * only the change set rather than roaming. Validated against the local model:
- * inlining full bodies bought nothing (it read the files by name regardless).
- *
- * Non-destructive — it does not touch the index, so the later `git add -A` in
- * gitCommitAll still stages everything (including fixes the enforcement child
- * makes).
+ * only the change set rather than roaming.
  *
  * The `.pi-tasks/` directory is excluded from every git command. Those task files
- * are committable (tracked) by design, so they show up in `git diff HEAD` and
- * `git ls-files --others` — git does not honor the fd/ripgrep `.ignore` that keeps
- * them out of the worker's find/grep discovery. Without this pathspec the enforce
- * child is handed its own TASK_*.md / TASK_AUTO_*.md bookkeeping as "changes to
- * verify" and edits them, corrupting the front matter mid-run.
+ * are committable (tracked) by design, so they ride into the commit's diff — git
+ * does not honor the fd/ripgrep `.ignore` that keeps them out of the worker's
+ * find/grep discovery. Without this pathspec the enforce child is handed its own
+ * TASK_*.md / TASK_AUTO_*.md bookkeeping as "changes to verify" and edits them,
+ * corrupting the front matter mid-run.
  */
-export async function captureDiff(cwd, signal, spawnFn) {
+export async function captureCommitDiff(cwd, signal, spawnFn) {
     // `:(exclude)<dir>` is a git pathspec that drops everything under the tasks
     // directory from the result, leaving only real source changes to verify.
     const excludeTasks = `:(exclude)${TASKS_DIR_NAME}`;
     const run = (args) => runChildDefault({ command: 'git', args }, cwd, signal, { mode: 'text' }, spawnFn);
-    const tracked = await run(['diff', 'HEAD', '--', '.', excludeTasks]);
-    const trackedNames = await run(['diff', 'HEAD', '--name-only', '--', '.', excludeTasks]);
-    const untracked = await run([
-        'ls-files',
-        '--others',
-        '--exclude-standard',
-        '--',
-        '.',
-        excludeTasks
-    ]);
+    // Diff the last commit against its parent. On a root commit there is no
+    // HEAD~1 (rev-parse exits non-zero), so fall back to the empty tree.
+    const parent = await run(['rev-parse', '--verify', '--quiet', 'HEAD~1']);
+    const base = parent.exitCode === 0 ? 'HEAD~1' : EMPTY_TREE;
+    const diff = await run(['diff', base, 'HEAD', '--', '.', excludeTasks]);
+    const names = await run(['diff', base, 'HEAD', '--name-only', '--', '.', excludeTasks]);
     const parts = [];
-    if (tracked.exitCode === 0 && tracked.stdout.trim().length > 0)
-        parts.push(`UNIFIED DIFF (modified files):\n${tracked.stdout.trim()}`);
-    const lines = (out) => out.exitCode === 0 ?
-        out.stdout
+    if (diff.exitCode === 0 && diff.stdout.trim().length > 0)
+        parts.push(`UNIFIED DIFF (last commit):\n${diff.stdout.trim()}`);
+    const changed = names.exitCode === 0 ?
+        names.stdout
             .split('\n')
             .map(s => s.trim())
             .filter(Boolean)
+            .sort()
         : [];
-    const modified = lines(trackedNames).sort();
-    // Untracked-NEW files do NOT appear in the diff above, so they are listed in
-    // their own emphatic section: in a flat list the model overlooks them and then
-    // emits a false CLEAN while a new file still violates the rules (observed on the
-    // local model). A diff-only file (already in `modified`) is not repeated here.
-    const newFiles = lines(untracked)
-        .filter(n => !modified.includes(n))
-        .sort();
-    if (modified.length > 0)
-        parts.push('MODIFIED FILES — read each in full and check it against the rules:\n'
-            + modified.map(n => `- ${n}`).join('\n'));
-    if (newFiles.length > 0)
-        parts.push('NEW FILES — created by this task and NOT shown in the diff above. You MUST'
-            + ' read and check each one against EVERY rule too:\n'
-            + newFiles.map(n => `- ${n}`).join('\n'));
+    if (changed.length > 0)
+        parts.push('FILES CHANGED IN THE LAST COMMIT — read each in full and check it against'
+            + ' EVERY rule:\n'
+            + changed.map(n => `- ${n}`).join('\n'));
     return parts.join('\n\n');
 }
 /**
@@ -226,7 +223,7 @@ export async function captureDiff(cwd, signal, spawnFn) {
  */
 export async function runGuidelineEnforcement(deps) {
     const discover = deps.discover ?? (cwd => discoverGuidelines(cwd));
-    const getDiff = deps.getDiff ?? ((cwd, signal) => captureDiff(cwd, signal));
+    const getDiff = deps.getDiff ?? ((cwd, signal) => captureCommitDiff(cwd, signal));
     const doc = await discover(deps.cwd);
     if (!doc)
         return { ok: true, reason: 'no guideline files' };

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