@mjasnikovs/pi-task 0.29.3 → 0.31.0

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;

package/dist/task/plan-prompts.js

@@ -0,0 +1,138 @@
+/**
+ * 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 const PLAN_QUESTION_PROMPT = (task, priorQA) => `You are helping a user plan ONE implementation task before it is built, one clarifying question at a time.
+
+TASK:
+${task.trim()}
+
+DECISIONS SO FAR:
+${priorQA.trim() || '(none yet)'}
+
+READ FIRST. Use the read tool on the repo and any referenced docs before you
+decide what to ask — open the files this task would touch. A question you could
+have asked without opening anything is almost always the wrong one: the good
+question is the fork you can only see once you know what is already there, and
+the SUGGESTED default has to name real, existing things to be worth accepting.
+Reading is expected and costs you nothing; only your REPLY is short.
+
+Output the SINGLE most important question that REMAINS — the one whose answer
+would most change HOW THIS ONE TASK IS BUILT: what is in and out of its scope,
+which approach or data shape it commits to, which existing code it changes versus
+leaves alone, how it behaves at the edges the request does not pin down. Account
+for the decisions so far:
+- Never re-ask something already decided above.
+- If a decision introduced a new fork or contradicts an assumption in the request
+  (for example, the user picked an approach the request did not anticipate), ask
+  about the most important consequence of that choice next.
+- Drop questions the decisions have made irrelevant.
+
+SCOPE RULES — read carefully:
+- This is ONE task, implemented in ONE run. Do NOT ask how the work should be
+  split, sequenced, phased, or broken into separate tasks, milestones, or PRs —
+  that decision is not on the table here.
+- Questions must clarify the EXISTING request. Do NOT propose new deliverables,
+  enhancements, migrations, or "while we're here" cleanups.
+- Skip anything the implementer will naturally resolve by reading the code
+  (where a file lives, what a function is currently called, which test runner the
+  repo uses).
+- Ask about decisions that are costly to reverse once the code is written.
+
+YOU MUST propose a default answer for the question — every question you emit
+carries exactly one SUGGESTED line. Never omit it, never leave it blank, never
+refuse. Infer the most sensible, concrete, decisive default from the request, the
+repo, and any stated constraints; it is shown to the user as a recommendation they
+accept or override. When the question is a genuine binary "A or B?" fork, also give
+the single best alternative as an ALT line; otherwise emit only the one SUGGESTED.
+
+OUTPUT FORMAT (exact) — read as much as you like, but your written REPLY is 2 or
+3 lines and nothing else:
+- Do NOT report what you read. No preamble, no analysis, no findings, no numbered
+  notes about files. The FIRST line of your reply is the question itself.
+  (Measured failure: a reply that opened with a numbered observation about a file
+  was read as the question.) What you learned belongs INSIDE the question and its
+  SUGGESTED line, as concrete names — not in a summary of your investigation.
+- One question as a single numbered line: "1. ...".
+- On the NEXT line (never inline), a line that begins with "SUGGESTED: <your recommended default>". This line is REQUIRED for every question.
+- If your question names two alternatives — ANY question of the form "should it be X or Y?" — you MUST add a third line beginning with "ALT: <the option your SUGGESTED did not take>". Only a question with no second alternative (a genuinely open "what should X be?") omits the ALT line. Do not offer a choice in the question and then leave the user only one card.
+- Put the core question in **bold**, followed by a short one-line rationale in plain prose. Backticks around code/identifiers are fine. Avoid other markdown (headings, bullet lists, links).
+- Only when nothing decision-changing is left to ask — the request and the decisions above already pin down how this task is built — output exactly the single token NONE on its own line (and no SUGGESTED line).
+
+EXAMPLES (format only — your wording will differ):
+
+Open-ended question:
+1. **Which existing callers must keep working unchanged?** This decides whether the change can alter the exported signature or must add a new one alongside it.
+SUGGESTED: keep every current caller working — add the new option with a default that preserves today's behaviour
+
+Binary "A or B?" fork:
+1. **Should the retry live in the client wrapper or in each call site?** This decides whether one shared code path owns the backoff or every caller repeats it.
+SUGGESTED: put it in the client wrapper so every call site inherits the same backoff
+ALT: retry at each call site, so a caller can opt out
+
+No question remains:
+NONE`;
+/**
+ * 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 const PLAN_ANSWER_PROMPT = (task, priorQA, question) => `You are helping a user plan ONE implementation task. The user has asked YOU a question about it. Answer it.
+
+TASK:
+${task.trim()}
+
+DECISIONS SO FAR:
+${priorQA.trim() || '(none yet)'}
+
+THE USER'S QUESTION:
+${question.trim()}
+
+Use the read tool to check the repo before you answer. Ground the answer in what
+is actually there.
+
+RULES — read carefully:
+- Answer the question that was asked. Do not answer a different, easier one.
+- Name only files, symbols, commands, and options you have VERIFIED exist — by
+  reading them, or because they appear in the task above. Never name a path or an
+  API from memory.
+- If you cannot confirm the answer from the repo, say so plainly and say what you
+  would need to check. "I could not confirm X" is a correct answer here; a
+  confident guess is not.
+- If the question asks for a recommendation, give ONE, and say in a sentence what
+  it costs.
+- Do not start implementing, do not write code blocks longer than a few lines, and
+  do not restate the task back to the user.
+
+OUTPUT:
+- Plain prose, at most 8 short lines. No preamble, no headings, no bullet lists
+  longer than 4 items, no code fences.`;