@mjasnikovs/pi-task 0.30.0 → 0.31.0

package/dist/task/final-gate.js

@@ -1038,6 +1038,56 @@ function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe) {
     }
     return { outcome: 'pass' };
 }
+/** The command word of a shell line, past any leading `VAR=value` assignments. */
+function leadingBin(line) {
+    for (const tok of line.trim().split(/\s+/)) {
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tok))
+            continue;
+        return tok;
+    }
+    return null;
+}
+/**
+ * Re-run one VERIFY-block command line (nexttask 5) under the gate's existing
+ * env-gap contract, so a debt whose reason NAMES that command can be closed by the
+ * command itself rather than by a judgement about it.
+ *
+ * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: run 19's
+ * is `AGENT=1 bun test test/listings.test.ts`, and env prefixes, `&&` and redirects
+ * are all ordinary there. The leading command word is still resolved through
+ * runner-resolve so a login-shell-stripped PATH cannot make every re-run look like a
+ * gap (mx5 run 16's blindness, one level down).
+ *
+ * The asymmetry is the point: only exit 0 is conclusive. Every other ending — real
+ * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the
+ * debt exactly as open as it was.
+ */
+export function runVerifyCommandLine(cwd, line, timeoutMs, extraGapRe) {
+    const bin = leadingBin(line);
+    const runner = bin === null ? null : resolveRunner(bin);
+    const r = spawnSync('sh', ['-c', line], {
+        cwd,
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        env: runner ? runnerEnv(runner) : { ...process.env }
+    });
+    if (r.error)
+        return { outcome: 'gap', detail: `shell did not spawn (${r.error.message})` };
+    if (r.status === null)
+        return { outcome: 'gap', detail: 'killed (timeout or signal)' };
+    const output = `${r.stdout ?? ''}\n${r.stderr ?? ''}`;
+    if (r.status === 0)
+        return { outcome: 'pass' };
+    if (isCommandNotFound(r.status, output)) {
+        return { outcome: 'gap', detail: 'command not found (127)' };
+    }
+    if (ENV_GAP_OUTPUT_RE.test(output))
+        return { outcome: 'gap', detail: 'missing browser/runtime' };
+    if (INFRA_GAP_OUTPUT_RE.test(output) || extraGapRe?.test(output) === true) {
+        return { outcome: 'gap', detail: 'external infrastructure unreachable' };
+    }
+    return { outcome: 'fail', status: r.status, tail: outputTail(r.stdout ?? '', r.stderr ?? '') };
+}
 /**
  * The full-skip blindness guard (mx5 run 16, validated): dynamic commands were
  * DISCOVERED but every single one skipped as an environment gap, so the gate
@@ -1204,12 +1254,16 @@ export { taskThatIntroduced };
  * must pass `false` (unprovable ⇒ stays open), never a guess.
  */
 export async function deriveOpenDebts(cwd, staticOk) {
-    const { open: openRaw, resolved } = recheckAcceptDebts(await readAcceptDebts(cwd), {
+    const { open: openRaw, resolved, trail } = recheckAcceptDebts(await readAcceptDebts(cwd), {
         staticOk,
         // Cross-task-deletion debts auto-close iff the deleted file is back in the
         // tree — a deterministic existence check, corroborating the per-file
         // provenance the record already carries.
-        fileExists: rel => existsSync(path.join(cwd, rel))
+        fileExists: rel => existsSync(path.join(cwd, rel)),
+        // VERIFY-COMMAND class (nexttask 5): a debt that NAMES a command is settled
+        // by running that command, under the gate's own env-gap contract and behind
+        // the no-write guard below.
+        rerunVerify: cmd => rerunDebtVerifyCommand(cwd, cmd)
     });
     if (resolved.length > 0)
         await writeAcceptDebts(cwd, openRaw);
@@ -1219,7 +1273,65 @@ export async function deriveOpenDebts(cwd, staticOk) {
     // a deletion instruction. Pure git-history lookup; degrades to no annotation.
     const openDebts = annotateDebtConflicts(openRaw, p => taskThatIntroduced(cwd, p));
     const debtNote = buildAcceptDebtNote(openDebts);
-    return { openDebts, ...(debtNote ? { debtNote } : {}) };
+    return { openDebts, ...(debtNote ? { debtNote } : {}), ...(trail.length > 0 ? { trail } : {}) };
+}
+/** Per-command ceiling for a debt re-run (`inv-bounded`). */
+const DEBT_RERUN_TIMEOUT_MS = 300_000;
+/**
+ * Extra infrastructure-gap shapes recognised ONLY when re-running a debt's command,
+ * never in the gate's own verdicts. A driver that reports its connection simply
+ * closed (`ERR_POSTGRES_CONNECTION_CLOSED` — what bun's SQL client says when the
+ * database is not there at all, as on this box with the mx5 container stopped) is an
+ * absent dependency, and calling that "the defect is still present" would be a
+ * finding the environment invented. Kept out of INFRA_GAP_OUTPUT_RE on purpose: in a
+ * gate verdict the same wording can be a real fault the suite must own, and only the
+ * debt re-check needs the conservative reading — where it costs nothing, because gap
+ * and fail both leave the debt open.
+ */
+const DEBT_INFRA_GAP_RE = /ERR_POSTGRES_CONNECTION_CLOSED|ERR_MYSQL_CONNECTION|ECONNRESET/i;
+/**
+ * Re-run ONE debt's stored VERIFY command for the re-check, with the no-write guard
+ * (`inv-no-write`) wrapped around it.
+ *
+ * A VERIFY command is the project's own command and may legitimately write (a build
+ * emits `dist/`, a suite writes a snapshot). What it may NOT do is turn the tree into
+ * a passing tree and have that count as the debt being fixed — the run would then be
+ * certifying its own side effect. So tracked state is captured before and after, and
+ * a pass that came with a tracked change is downgraded to INCONCLUSIVE with the
+ * change named. Untracked output is left alone: it is what a build legitimately
+ * produces, and `git status --porcelain` in a repo with the usual ignores does not
+ * see it.
+ *
+ * A repository the guard cannot read (no git, git absent) is not a licence to skip
+ * the guard: the re-run is INCONCLUSIVE there, because "nothing changed" would be an
+ * assumption rather than an observation.
+ */
+export function rerunDebtVerifyCommand(cwd, command) {
+    const tracked = () => {
+        const r = spawnSync('git', ['status', '--porcelain', '--untracked-files=no'], {
+            cwd,
+            encoding: 'utf8',
+            timeout: 60_000
+        });
+        return r.error || r.status !== 0 ? null : (r.stdout ?? '');
+    };
+    const before = tracked();
+    const r = runVerifyCommandLine(cwd, command, DEBT_RERUN_TIMEOUT_MS, DEBT_INFRA_GAP_RE);
+    if (r.outcome === 'fail')
+        return { outcome: 'fail', detail: `exit ${r.status} — ${r.tail}` };
+    if (r.outcome === 'gap')
+        return { outcome: 'gap', detail: r.detail };
+    const after = tracked();
+    if (before === null || after === null) {
+        return { outcome: 'gap', detail: 'tracked-state guard could not read git status' };
+    }
+    if (before !== after) {
+        return {
+            outcome: 'gap',
+            detail: 'the re-run itself CHANGED tracked files — a command that edits the tree into a pass proves nothing'
+        };
+    }
+    return { outcome: 'pass' };
 }
 /**
  * Run the final gate: static analysis first, then the lockfile consistency

package/dist/task/plan-io.d.ts

@@ -0,0 +1,55 @@
+/** Next free TASK_PLAN_NNNN id. Mirrors allocateAutoId. */
+export declare function allocatePlanId(cwd: string): Promise<string>;
+/**
+ * How an answer to a model question was produced. Recorded verbatim in the plan
+ * file because "the user chose this" and "the recommendation was accepted by
+ * default" are different levels of evidence when you read the plan back later —
+ * the same distinction /task-auto draws with its "(accepted recommendation)" and
+ * "(YOLO)" stamps.
+ */
+export type AnswerSource = 'chosen' | 'accepted' | 'typed' | 'skipped' | 'yolo';
+export type PlanEntry = 
+/** The model asked; the user answered. */
+{
+    kind: 'decision';
+    question: string;
+    answer: string;
+    source: AnswerSource;
+}
+/** The user volunteered a decision without being asked. */
+ | {
+    kind: 'stated';
+    text: string;
+}
+/** The user asked; the model answered. Advisory — decides nothing on its own. */
+ | {
+    kind: 'note';
+    question: string;
+    answer: string;
+};
+/**
+ * The transcript as the MODEL sees it — fed back as `priorQA` on every next
+ * question, and prepended to the handoff prompt. Decisions are numbered so a
+ * later question can refer to one; notes and stated decisions are labelled by who
+ * said them, because a model answer the user merely READ must not be mistaken for
+ * a decision the user MADE.
+ */
+export declare function formatPlanTranscript(entries: readonly PlanEntry[]): string;
+/** Body of a fresh plan file, before any entry is recorded. */
+export declare function buildPlanBody(task: string): string;
+/**
+ * The `## decisions` section: the human-readable transcript. Same content as
+ * {@link formatPlanTranscript} — the model and the reader see the same record, so
+ * there is no hidden channel.
+ */
+export declare function formatPlanDecisions(entries: readonly PlanEntry[]): string;
+/**
+ * The prompt handed to /task when the user proceeds to execution.
+ *
+ * The task prompt leads, exactly as a bare `/task <prompt>` would, so refine sees
+ * a normal task description first; the decisions follow as an authoritative block.
+ * Anything the user did NOT settle is simply absent — /task's own grill phase asks
+ * about what is left, which is why this block never invents a decision to fill a
+ * gap.
+ */
+export declare function buildHandoffPrompt(task: string, entries: readonly PlanEntry[]): string;

package/dist/task/plan-io.js

@@ -0,0 +1,94 @@
+/**
+ * PLAN-file I/O & transcript formatting for /task-plan.
+ *
+ * A TASK_PLAN_NNNN.md is a normal task file — same front matter, same section
+ * machinery (task-io.ts) — whose body holds the task prompt and the planning
+ * transcript. This mirrors auto-io.ts, which does exactly the same thing for
+ * /task-auto's TASK_AUTO_NNNN.md; nothing about the file format is new here.
+ *
+ * The transcript is the whole point of the command: it is what rides into /task
+ * as the handoff prompt, and it is what a human reads afterwards to see which
+ * decisions were made and who made them.
+ */
+import * as fsp from 'node:fs/promises';
+import { tasksDir, ensureTasksDir } from './task-io.js';
+const PLAN_FILE_RE = /^(TASK_PLAN_\d{4,})\.md$/;
+/** Next free TASK_PLAN_NNNN id. Mirrors allocateAutoId. */
+export async function allocatePlanId(cwd) {
+    await ensureTasksDir(cwd);
+    const entries = await fsp.readdir(tasksDir(cwd));
+    let max = 0;
+    for (const e of entries) {
+        const m = PLAN_FILE_RE.exec(e);
+        if (m) {
+            const n = parseInt(m[1].slice('TASK_PLAN_'.length), 10);
+            if (n > max)
+                max = n;
+        }
+    }
+    return `TASK_PLAN_${String(max + 1).padStart(4, '0')}`;
+}
+const SOURCE_STAMP = {
+    chosen: '',
+    accepted: ' (accepted recommendation)',
+    typed: '',
+    skipped: '',
+    yolo: ' (YOLO)'
+};
+/**
+ * The transcript as the MODEL sees it — fed back as `priorQA` on every next
+ * question, and prepended to the handoff prompt. Decisions are numbered so a
+ * later question can refer to one; notes and stated decisions are labelled by who
+ * said them, because a model answer the user merely READ must not be mistaken for
+ * a decision the user MADE.
+ */
+export function formatPlanTranscript(entries) {
+    const lines = [];
+    let n = 0;
+    for (const e of entries) {
+        if (e.kind === 'decision') {
+            n++;
+            lines.push(`Q${n}: ${e.question}`);
+            lines.push(`A${n}: ${e.answer}${SOURCE_STAMP[e.source]}`);
+        }
+        else if (e.kind === 'stated') {
+            lines.push(`DECIDED BY USER: ${e.text}`);
+        }
+        else {
+            lines.push(`THE USER ASKED: ${e.question}`);
+            lines.push(`YOU ANSWERED: ${e.answer}`);
+        }
+    }
+    return lines.join('\n');
+}
+/** Body of a fresh plan file, before any entry is recorded. */
+export function buildPlanBody(task) {
+    return `\n## task prompt\n\n${task.trim() || '(none)'}\n\n## decisions\n\n(none yet)\n`;
+}
+/**
+ * The `## decisions` section: the human-readable transcript. Same content as
+ * {@link formatPlanTranscript} — the model and the reader see the same record, so
+ * there is no hidden channel.
+ */
+export function formatPlanDecisions(entries) {
+    return entries.length === 0 ? '(none yet)' : formatPlanTranscript(entries);
+}
+/**
+ * The prompt handed to /task when the user proceeds to execution.
+ *
+ * The task prompt leads, exactly as a bare `/task <prompt>` would, so refine sees
+ * a normal task description first; the decisions follow as an authoritative block.
+ * Anything the user did NOT settle is simply absent — /task's own grill phase asks
+ * about what is left, which is why this block never invents a decision to fill a
+ * gap.
+ */
+export function buildHandoffPrompt(task, entries) {
+    const decisions = entries.filter(e => e.kind !== 'note');
+    if (decisions.length === 0)
+        return task.trim();
+    return (`${task.trim()}\n\n`
+        + `PLANNING DECISIONS — these were settled with the user before this task was started. `
+        + `They are authoritative: implement them as written, and do not re-open or contradict `
+        + `them. They may not cover everything; decide anything they leave open as usual.\n\n`
+        + `${formatPlanTranscript(decisions)}`);
+}

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

@@ -0,0 +1,52 @@
+/**
+ * /task-plan — plan ONE task with the model, then hand it to /task.
+ *
+ * The command is a thin wiring layer. Everything it does is already in the
+ * codebase and is reused as-is:
+ *
+ *   • the adaptive question loop, the duplicate backstop, the boxed picker and
+ *     the A/B answer mapping        → plan-session.ts (which reuses parsers.ts,
+ *                                     question-dedup.ts, inline-markdown.ts,
+ *                                     question-box.ts, yolo.ts)
+ *   • the child process, its loop/leak/stall guards and retries → child-runner.ts
+ *   • local TUI + remote browser prompt fan-out                 → remote/bridge.ts
+ *   • the status widget                                         → widget.ts
+ *   • the plan file (.pi-tasks/TASK_PLAN_NNNN.md)               → task-io.ts
+ *   • the handoff itself                                        → orchestrator.ts
+ *
+ * The handoff is deliberately the SAME call /task makes for a typed prompt —
+ * gated when `verify work` / `enforce guidelines` is on, fire-and-forget
+ * otherwise — so a planned task is not a second kind of task. The only thing
+ * /task receives that a bare /task would not is the decisions block.
+ */
+import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import { type PlanSessionDeps, type PlanOutcome } from './plan-session.js';
+import { type PlanEntry } from './plan-io.js';
+/**
+ * Build the session deps around a live command ctx: children with a status
+ * loader, prompts fanned out to the terminal AND any remote viewer, and the plan
+ * file rewritten after every entry.
+ */
+export declare function buildPlanDeps(ctx: ExtensionCommandContext, cwd: string, planId: string, task: string, signal: AbortSignal): PlanSessionDeps;
+/**
+ * Write the transcript into the plan file. The decisions and the model's answers
+ * to the user's questions live in separate sections: only the decisions are
+ * authoritative for the implementation, and the file must not blur that.
+ */
+export declare function persistEntries(cwd: string, planId: string, entries: readonly PlanEntry[]): Promise<void>;
+/**
+ * Seams the command flow needs from the outside world. Defaulted to the real
+ * thing in {@link handleTaskPlan}; injected in tests so the whole flow — plan
+ * file, transcript, handoff prompt — can be exercised without a model or a
+ * session replacement.
+ */
+export interface PlanCommandDeps {
+    /** Build the session deps (children + dialogs) for this run. */
+    session(ctx: ExtensionCommandContext, cwd: string, planId: string, task: string, signal: AbortSignal): PlanSessionDeps;
+    /** Run the loop. */
+    run(deps: PlanSessionDeps): Promise<PlanOutcome>;
+    /** Hand the composed prompt to /task. Returns the produced task id, if any. */
+    handoff(ctx: ExtensionCommandContext, cwd: string, prompt: string): Promise<string | undefined>;
+}
+export declare function handleTaskPlan(args: string, ctx: ExtensionCommandContext, commandDeps?: PlanCommandDeps): Promise<void>;
+export declare function registerTaskPlan(pi: ExtensionAPI): void;

package/dist/task/plan-orchestrator.js

@@ -0,0 +1,234 @@
+/**
+ * /task-plan — plan ONE task with the model, then hand it to /task.
+ *
+ * The command is a thin wiring layer. Everything it does is already in the
+ * codebase and is reused as-is:
+ *
+ *   • the adaptive question loop, the duplicate backstop, the boxed picker and
+ *     the A/B answer mapping        → plan-session.ts (which reuses parsers.ts,
+ *                                     question-dedup.ts, inline-markdown.ts,
+ *                                     question-box.ts, yolo.ts)
+ *   • the child process, its loop/leak/stall guards and retries → child-runner.ts
+ *   • local TUI + remote browser prompt fan-out                 → remote/bridge.ts
+ *   • the status widget                                         → widget.ts
+ *   • the plan file (.pi-tasks/TASK_PLAN_NNNN.md)               → task-io.ts
+ *   • the handoff itself                                        → orchestrator.ts
+ *
+ * The handoff is deliberately the SAME call /task makes for a typed prompt —
+ * gated when `verify work` / `enforce guidelines` is on, fire-and-forget
+ * otherwise — so a planned task is not a second kind of task. The only thing
+ * /task receives that a bare /task would not is the decisions block.
+ */
+import * as path from 'node:path';
+import { runPhaseChild, prependHint, USER_CANCELLED } from './child-runner.js';
+import { PLAN_QUESTION_PROMPT, PLAN_ANSWER_PROMPT } from './plan-prompts.js';
+import { runPlanSession, ASK_TITLE } from './plan-session.js';
+import { allocatePlanId, buildPlanBody, buildHandoffPrompt, formatPlanDecisions } from './plan-io.js';
+import { writeTaskFile, setTaskSection, updateTaskFrontMatter, tasksDir } from './task-io.js';
+import { deriveTitle } from './parsers.js';
+import { renderInlineMarkdown } from './inline-markdown.js';
+import { expandFeatureMentions } from './auto-orchestrator.js';
+import { runSingleTask, runGatedTask } from './orchestrator.js';
+import { startAutoLoader } from './widget.js';
+import { SessionUI, publishViewer, publishNotify, publishLifecycleNotice, registerBridgeCommand } from '../remote/bridge.js';
+import { getConfig } from '../config/config.js';
+import { isYoloMode } from './yolo.js';
+import { gateDebugWriter } from './debug-log.js';
+import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
+import * as fsp from 'node:fs/promises';
+/** Loader labels for the two planning children. */
+const PLAN_STEPS = {
+    'plan-question': 'question',
+    'plan-answer': 'answering you'
+};
+/**
+ * Build the session deps around a live command ctx: children with a status
+ * loader, prompts fanned out to the terminal AND any remote viewer, and the plan
+ * file rewritten after every entry.
+ */
+export function buildPlanDeps(ctx, cwd, planId, task, signal) {
+    const ui = new SessionUI(ctx);
+    const theme = ctx.ui.theme;
+    let lastLine;
+    let status;
+    let contextUsage;
+    const parentContextWindow = getParentContextWindow(ctx);
+    const title = deriveTitle(task);
+    const logDebug = gateDebugWriter((msg) => {
+        const line = `${new Date().toISOString()} ${msg}\n`;
+        void fsp.appendFile(path.join(tasksDir(cwd), `${planId}-debug.log`), line).catch(() => { });
+    });
+    const phaseDeps = {
+        cwd,
+        taskId: planId,
+        signal,
+        onChildOutput: line => {
+            lastLine = line;
+        },
+        onContextUsage: snapshot => {
+            contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
+        },
+        ...(logDebug && { logDebug })
+    };
+    /** Run a planning child under the shared /task-auto-style loader. */
+    const child = async (name, prompt) => {
+        lastLine = undefined;
+        contextUsage = undefined;
+        const startedAt = Date.now();
+        const stopLoader = startAutoLoader(ctx, () => ({
+            command: '/task-plan',
+            title,
+            step: status ?? PLAN_STEPS[name] ?? name,
+            stepNum: 1,
+            stepTotal: 1,
+            startedAt,
+            lastLine,
+            contextUsage
+        }));
+        try {
+            return await runPhaseChild(phaseDeps, name, 'read', prompt);
+        }
+        finally {
+            stopLoader();
+        }
+    };
+    return {
+        generateQuestion: (priorQA, hint) => child('plan-question', prependHint(hint, PLAN_QUESTION_PROMPT(task, priorQA))),
+        answerUserQuestion: (priorQA, question) => child('plan-answer', PLAN_ANSWER_PROMPT(task, priorQA, question)),
+        ask: (spec) => ui.ask(spec),
+        promptText: (localTitle, question) => ui.ask({
+            localTitle,
+            question,
+            // No recommendation and no options: both surfaces fall back to
+            // their plain text input, which is exactly what "type your
+            // question" needs. Skip = changed my mind.
+            allowSkip: true
+        }),
+        showAnswer: async (question, answer) => {
+            const text = `You asked:\n${question}\n\n${answer}\n`;
+            publishViewer(ASK_TITLE, text);
+            await ctx.ui.editor(ASK_TITLE, text);
+        },
+        onEntries: async (entries) => {
+            await persistEntries(cwd, planId, entries);
+        },
+        renderMarkdown: (s) => renderInlineMarkdown(s, theme),
+        setStatus: line => {
+            status = line;
+        },
+        yolo: isYoloMode(),
+        ...(logDebug && { logDebug })
+    };
+}
+/**
+ * Write the transcript into the plan file. The decisions and the model's answers
+ * to the user's questions live in separate sections: only the decisions are
+ * authoritative for the implementation, and the file must not blur that.
+ */
+export async function persistEntries(cwd, planId, entries) {
+    const decisions = entries.filter(e => e.kind !== 'note');
+    const notes = entries.filter(e => e.kind === 'note');
+    await setTaskSection(cwd, planId, 'decisions', formatPlanDecisions(decisions));
+    if (notes.length > 0) {
+        await setTaskSection(cwd, planId, 'notes', notes
+            .map(n => (n.kind === 'note' ? `Q: ${n.question}\nA: ${n.answer}` : ''))
+            .join('\n\n'));
+    }
+}
+/**
+ * The default handoff: EXACTLY what `/task <prompt>` does with a typed prompt —
+ * gated when `verify work` / `enforce guidelines` is on, fire-and-forget
+ * otherwise. A planned task must not be a second kind of task.
+ */
+async function defaultHandoff(ctx, cwd, prompt) {
+    const cfg = getConfig();
+    if (cfg.verifyWork || cfg.enforceGuidelines) {
+        // runGatedTask owns the whole gated sequence and reports its own outcome;
+        // it does not surface the inner task id, so the plan file records the
+        // handoff without one.
+        await runGatedTask(ctx, cwd, prompt);
+        return undefined;
+    }
+    const { taskId, sessionCancelled } = await runSingleTask(ctx, cwd, prompt, { notifyFinish: true });
+    if (sessionCancelled) {
+        ctx.ui.notify('Could not start a fresh session for /task-plan.', 'warning');
+        return undefined;
+    }
+    return taskId || undefined;
+}
+const DEFAULT_COMMAND_DEPS = {
+    session: buildPlanDeps,
+    run: runPlanSession,
+    handoff: defaultHandoff
+};
+export async function handleTaskPlan(args, ctx, commandDeps = DEFAULT_COMMAND_DEPS) {
+    await ctx.waitForIdle();
+    const cwd = ctx.cwd;
+    const raw = args.trim();
+    if (raw.length === 0) {
+        ctx.ui.setEditorText('/task-plan ');
+        ctx.ui.notify('Describe the task after /task-plan (use @ for file completion).', 'info');
+        return;
+    }
+    // Inline any @file the user referenced, exactly as /task-auto's planner does:
+    // a one-line "Implement @spec.md" reads as trivial to a model that cannot see
+    // the file, and the first question comes out useless.
+    const task = await expandFeatureMentions(cwd, raw);
+    const planId = await allocatePlanId(cwd);
+    const now = new Date().toISOString();
+    const fm = {
+        id: planId,
+        state: 'in_progress',
+        // Plan files have no phase pipeline of their own — same as TASK_AUTO_*,
+        // which parks at 'done' so the phase progress bar never claims otherwise.
+        phase: 'done',
+        created_at: now,
+        updated_at: now,
+        title: deriveTitle(raw)
+    };
+    await writeTaskFile(cwd, fm, buildPlanBody(task));
+    const abort = new AbortController();
+    let outcome;
+    try {
+        outcome = await commandDeps.run(commandDeps.session(ctx, cwd, planId, task, abort.signal));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        await updateTaskFrontMatter(cwd, planId, {
+            state: msg === USER_CANCELLED ? 'cancelled' : 'failed',
+            reason: msg.slice(0, 200)
+        }).catch(() => { });
+        const line = `${planId} stopped — ${msg.slice(0, 160)}`;
+        ctx.ui.notify(line, 'error');
+        publishLifecycleNotice(line, 'error');
+        return;
+    }
+    if (outcome.kind === 'cancelled') {
+        // Nothing is handed to /task, but whatever WAS decided stays on disk —
+        // a cancelled plan is a record, not a rollback.
+        await updateTaskFrontMatter(cwd, planId, { state: 'cancelled' }).catch(() => { });
+        const line = outcome.entries.length === 0 ?
+            `${planId} cancelled — nothing planned.`
+            : `${planId} cancelled — ${outcome.entries.length} entr${outcome.entries.length === 1 ? 'y' : 'ies'} kept in .pi-tasks/${planId}.md`;
+        ctx.ui.notify(line, 'warning');
+        publishNotify(line, 'warning');
+        return;
+    }
+    const prompt = buildHandoffPrompt(task, outcome.entries);
+    const decisions = outcome.entries.filter(e => e.kind !== 'note').length;
+    await setTaskSection(cwd, planId, 'handoff', `handoff_at: ${new Date().toISOString()}\ndecisions: ${decisions}`).catch(() => { });
+    await updateTaskFrontMatter(cwd, planId, { state: 'completed' }).catch(() => { });
+    const taskId = await commandDeps.handoff(ctx, cwd, prompt);
+    if (taskId) {
+        // Stamped after the fact: this is the one link from the plan to the task
+        // it produced, and /task allocates the id only once its own run starts.
+        await setTaskSection(cwd, planId, 'handoff', `handoff_at: ${new Date().toISOString()}\ndecisions: ${decisions}\ntask: ${taskId}`).catch(() => { });
+    }
+}
+export function registerTaskPlan(pi) {
+    registerBridgeCommand(pi, 'task-plan', {
+        description: 'Plan one task with the model — it asks, you answer (or ask it something, or '
+            + 'proceed) — then hand the decisions to /task. Usage: /task-plan <prompt>',
+        handler: handleTaskPlan
+    });
+}

package/dist/task/plan-prompts.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Prompts for /task-plan's two planning children.
+ *
+ * /task-plan plans ONE task interactively before any spec work happens. Its
+ * question generator is deliberately the SAME SHAPE as /task-auto's clarify head
+ * (`AUTO_CLARIFY_PROMPT` in auto-prompts.ts): one numbered question, a required
+ * `SUGGESTED:` line, an optional `ALT:` line for a binary fork, the literal token
+ * NONE when nothing remains. That is not a coincidence — it means
+ * {@link parseClarifyList} parses this output UNCHANGED, and the boxed picker,
+ * the duplicate backstop and the YOLO picker all work here with no new code.
+ *
+ * What differs is the JOB. /task-auto's clarify asks what changes how a feature is
+ * SPLIT INTO TASKS; every question it asks is about plan shape, ordering, and which
+ * subsystems are in or out. /task-plan is planning a single unit of work that /task
+ * will implement in one run, so a "how do we split this" question is off-topic here
+ * and the prompt below rules it out explicitly.
+ */
+/**
+ * Ask the SINGLE most important remaining question about ONE task.
+ *
+ * `priorQA` carries every decision made so far — model questions the user
+ * answered, answers the user volunteered, and the Q&A from questions the user
+ * asked the model — so each next question adapts to them. Output MUST match
+ * parseClarifyList.
+ */
+export declare const PLAN_QUESTION_PROMPT: (task: string, priorQA: string) => string;
+/**
+ * Answer a question the USER asked the model during planning.
+ *
+ * This is the one channel /task-plan adds that no existing phase has: everywhere
+ * else in pi-task the model asks and the user answers. Here the user asks. The
+ * answer is advisory — it is recorded in the plan file as a note, and it does NOT
+ * by itself decide anything; the user still answers the model's own questions.
+ *
+ * The abstention rule matters more here than anywhere else in the pipeline: a
+ * planning answer that invents a file, a flag, or an API reads exactly like a
+ * grounded one, and the user is asking BECAUSE they do not know. Saying "I could
+ * not confirm this" is a correct answer; a confident guess is not.
+ */
+export declare const PLAN_ANSWER_PROMPT: (task: string, priorQA: string, question: string) => string;