@mjasnikovs/pi-task 0.2.1 → 0.2.3

package/dist/task/auto-orchestrator.js

@@ -0,0 +1,318 @@
+/**
+ * /task-auto — plans a feature into a resumable list of task titles, then runs
+ * each title through the existing single-task pipeline one at a time.
+ *
+ * This module currently holds the planning half (AutoDeps + planAuto). The run
+ * loop, command handlers, and defaultDeps are added by the next task.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { runSingleTask } from './orchestrator.js';
+import { parseClarifyList, deriveTitle } from './parsers.js';
+import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js';
+import { AUTO_CLARIFY_PROMPT, AUTO_DECOMPOSE_PROMPT } from './auto-prompts.js';
+import { allocateAutoId, buildAutoBody, parseDecomposeList, parseTaskList, checkOffTask, findResumableAuto } from './auto-io.js';
+import { writeTaskFile, readTaskFile, updateTaskFrontMatter } from './task-io.js';
+import { gitCommitAll } from './auto-commit.js';
+import { runPhaseChild, USER_CANCELLED } from './child-runner.js';
+import { startAutoLoader } from './widget.js';
+// Matches pi's @-file completion token (a path after @, until whitespace).
+const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
+/**
+ * Expand any @file references in the feature text by appending each referenced
+ * file's contents, so the planning children (clarify, decompose) always see the
+ * real spec inline instead of relying on the model to open the file itself.
+ * Without this, clarify on a one-line "Implement @spec.md" tends to bail with
+ * NONE because, to the model, the request looks small and unambiguous.
+ * Unreadable mentions (typos, non-file @tokens) are left untouched; the feature
+ * is returned verbatim when nothing readable is referenced.
+ */
+export async function expandFeatureMentions(cwd, feature) {
+    const seen = new Set();
+    const blocks = [];
+    for (const m of feature.matchAll(MENTION_RE)) {
+        const rel = m[1];
+        if (seen.has(rel))
+            continue;
+        seen.add(rel);
+        try {
+            const body = await fsp.readFile(path.resolve(cwd, rel), 'utf8');
+            if (body.trim().length > 0) {
+                blocks.push(`--- contents of ${rel} ---\n${body.trim()}`);
+            }
+        }
+        catch {
+            // not a readable file — leave the @token in place, skip expansion
+        }
+    }
+    return blocks.length === 0 ? feature : `${feature.trim()}\n\n${blocks.join('\n\n')}`;
+}
+/** 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
+    // answer back into the next call so later questions react to earlier ones
+    // (e.g. a framework choice reshapes what gets asked). Each question is shown
+    // with the model's recommended default pre-filled (Enter to accept, type to
+    // override); we never auto-answer. The model emits NONE when nothing remains.
+    const theme = ctx.ui.theme;
+    // Inline any @file spec the user referenced so clarify/decompose reason over
+    // the real content, not a one-line "Implement @file" that reads as trivial.
+    const featureForModel = await expandFeatureMentions(cwd, feature);
+    const answers = [];
+    // Open-ended: keep asking until the model emits NONE or the user dismisses.
+    for (;;) {
+        const qRaw = await deps.runChild('auto-clarify', 'read', AUTO_CLARIFY_PROMPT(featureForModel, answers.join('\n')));
+        const parsed = parseClarifyList(qRaw);
+        if (parsed.length === 0)
+            break; // NONE / nothing left to ask
+        const { question, suggested } = parsed[0];
+        // Render markdown (bold/code) for the displayed prompt; keep plain text
+        // for the editable default and the persisted file.
+        const shownQ = renderInlineMarkdown(question, theme);
+        const plainQ = stripInlineMarkdown(question);
+        const plainSuggested = suggested === undefined ? undefined : stripInlineMarkdown(suggested);
+        const title = suggested ?
+            `${shownQ}\n${theme.fg('muted', 'Recommended:')}\n\n${renderInlineMarkdown(suggested, theme)}\n\n${theme.fg('muted', 'press Enter to accept')}`
+            : `${shownQ}\n${theme.fg('muted', '(no recommendation — please answer)')}`;
+        const a = await ctx.ui.input(title, plainSuggested);
+        if (a === undefined) {
+            ctx.ui.notify('/task-auto cancelled.', 'warning');
+            return null;
+        }
+        const typed = a.trim();
+        let answer;
+        if (typed.length === 0 && plainSuggested) {
+            answer = `${plainSuggested} (accepted recommendation)`;
+        }
+        else if (typed.length === 0) {
+            answer = '(skipped)';
+        }
+        else {
+            answer = typed;
+        }
+        answers.push(`Q${answers.length + 1}: ${plainQ}\nA${answers.length + 1}: ${answer}`);
+    }
+    if (answers.length === 0) {
+        ctx.ui.notify('No clarifying questions needed — planning tasks…', 'info');
+    }
+    const clarifications = answers.join('\n');
+    // decompose
+    const listRaw = await deps.runChild('auto-decompose', 'read', AUTO_DECOMPOSE_PROMPT(featureForModel, clarifications));
+    const titles = parseDecomposeList(listRaw);
+    if (titles.length === 0) {
+        ctx.ui.notify('/task-auto: no tasks produced from the feature.', 'warning');
+        return null;
+    }
+    // persist
+    const id = await allocateAutoId(cwd);
+    const now = new Date().toISOString();
+    const fm = {
+        id,
+        state: 'in_progress',
+        phase: 'done',
+        created_at: now,
+        updated_at: now,
+        title: deriveTitle(feature)
+    };
+    await writeTaskFile(cwd, fm, buildAutoBody(feature, clarifications, titles));
+    return id;
+}
+/** The two feature-level planning children, shown as steps in the loader. */
+const AUTO_PLAN_STEPS = {
+    'auto-clarify': { step: 'clarify', stepNum: 1 },
+    'auto-decompose': { step: 'decompose', stepNum: 2 }
+};
+const AUTO_PLAN_STEP_TOTAL = 2;
+function defaultDeps(ctx, cwd, signal, title) {
+    // Captured by the loader's getState so the widget mirrors the child's latest
+    // output line and context usage, exactly like the single-task phase widget.
+    let lastLine;
+    let contextUsage;
+    const parentContextWindow = ctx.model?.contextWindow ?? 0;
+    const phaseDeps = {
+        cwd,
+        taskId: '',
+        signal,
+        onChildOutput: (line) => {
+            lastLine = line;
+        },
+        onContextUsage: snapshot => {
+            const cw = snapshot.contextWindow > 0 ?
+                snapshot.contextWindow
+                : contextUsage?.contextWindow || parentContextWindow;
+            const percent = cw > 0 ? Math.min(100, (snapshot.tokens / cw) * 100) : snapshot.percent;
+            contextUsage = { tokens: snapshot.tokens, contextWindow: cw, percent };
+        }
+    };
+    return {
+        runChild: async (name, tools, prompt) => {
+            // Planning children are slow LLM calls with no UI of their own; show
+            // the same status block as /task so this never goes silent until the
+            // drill dialog.
+            lastLine = undefined;
+            contextUsage = undefined;
+            const startedAt = Date.now();
+            const { step, stepNum } = AUTO_PLAN_STEPS[name] ?? { step: name, stepNum: 1 };
+            const stopLoader = startAutoLoader(ctx, () => ({
+                title,
+                step,
+                stepNum,
+                stepTotal: AUTO_PLAN_STEP_TOTAL,
+                startedAt,
+                lastLine,
+                contextUsage
+            }));
+            try {
+                return await runPhaseChild(phaseDeps, name, tools, prompt);
+            }
+            finally {
+                stopLoader();
+            }
+        },
+        runTask: (c, cwd2, t) => runSingleTask(c, cwd2, t, { waitForImplementation: true }),
+        commit: (cwd2, message) => gitCommitAll(cwd2, message, signal)
+    };
+}
+// ─── Loop ────────────────────────────────────────────────────────────────────
+let cancelRequested = false;
+let autoRunning = false;
+export function requestAutoCancel() {
+    cancelRequested = true;
+}
+export async function runAutoLoop(ctx, cwd, id, deps) {
+    cancelRequested = false;
+    // Each task runs in its own fresh session (deps.runTask → ctx.newSession),
+    // which tears down the current session and leaves the ctx we passed in stale.
+    // Adopt the replacement ctx the runner hands back and use it for all further
+    // UI and the next task — reusing the captured ctx throws "stale ctx".
+    let active = ctx;
+    try {
+        for (;;) {
+            if (cancelRequested) {
+                active.ui.notify(`${id} cancelled — resume with /task-auto-resume.`, 'warning');
+                return;
+            }
+            const { body } = await readTaskFile(cwd, id);
+            const entries = parseTaskList(body);
+            const next = entries.find(e => !e.done);
+            if (!next) {
+                await updateTaskFrontMatter(cwd, id, { state: 'completed' });
+                active.ui.notify(`${id} complete — all ${entries.length} tasks done.`, 'info');
+                return;
+            }
+            active.ui.notify(`${id}: task ${next.index + 1}/${entries.length} — ${next.title}`, 'info');
+            const res = await deps.runTask(active, cwd, next.title);
+            active = res.ctx ?? active;
+            if (res.sessionCancelled) {
+                active.ui.notify(`${id} paused — could not start a session. Run /task-auto-resume to retry.`, 'warning');
+                return;
+            }
+            if (!res.ok) {
+                await updateTaskFrontMatter(cwd, id, { state: 'failed' });
+                active.ui.notify(`${id} stopped at "${next.title}" — 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.
+            const message = `task: ${next.title} (${res.taskId})`;
+            const commit = await deps.commit(cwd, message);
+            if (commit.committed) {
+                active.ui.notify(`${id}: committed "${next.title}".`, 'info');
+            }
+            else {
+                active.ui.notify(`${id}: not committed (${commit.reason ?? 'unknown'}) — continuing.`, 'warning');
+            }
+        }
+    }
+    finally {
+        cancelRequested = false;
+    }
+}
+// ─── Command handlers ────────────────────────────────────────────────────────
+async function handleTaskAuto(args, ctx) {
+    await ctx.waitForIdle();
+    const cwd = ctx.cwd;
+    const raw = args.trim();
+    if (raw.length === 0) {
+        ctx.ui.setEditorText('/task-auto ');
+        ctx.ui.notify('Describe the feature after /task-auto (use @ for file completion).', 'info');
+        return;
+    }
+    autoRunning = true;
+    const abort = new AbortController();
+    const deps = defaultDeps(ctx, cwd, abort.signal, deriveTitle(raw));
+    let id;
+    try {
+        id = await planAuto(ctx, cwd, raw, deps);
+    }
+    catch (err) {
+        autoRunning = false;
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg === USER_CANCELLED) {
+            ctx.ui.notify('/task-auto cancelled.', 'warning');
+            return;
+        }
+        ctx.ui.notify(`/task-auto planning failed: ${msg}`, 'error');
+        return;
+    }
+    if (!id) {
+        autoRunning = false;
+        return;
+    }
+    // Check for a cancel that was requested during the planning phase before the
+    // loop resets the flag.
+    if (cancelRequested) {
+        cancelRequested = false;
+        autoRunning = false;
+        ctx.ui.notify('/task-auto cancelled.', 'warning');
+        return;
+    }
+    await runAutoLoop(ctx, cwd, id, deps);
+    autoRunning = false;
+}
+async function handleTaskAutoResume(_args, ctx) {
+    await ctx.waitForIdle();
+    const cwd = ctx.cwd;
+    const id = await findResumableAuto(cwd);
+    if (!id) {
+        ctx.ui.notify('No resumable /task-auto run.', 'info');
+        return;
+    }
+    ctx.ui.notify(`Resuming ${id}…`, 'info');
+    await updateTaskFrontMatter(cwd, id, { state: 'in_progress' });
+    autoRunning = true;
+    const abort = new AbortController();
+    // Resume only runs the loop (runTask); no planning children, so the loader
+    // title is unused here — pass the id for clarity if that ever changes.
+    await runAutoLoop(ctx, cwd, id, defaultDeps(ctx, cwd, abort.signal, id));
+    autoRunning = false;
+}
+// eslint-disable-next-line @typescript-eslint/require-await
+async function handleTaskAutoCancel(_args, ctx) {
+    if (!autoRunning) {
+        ctx.ui.notify('No /task-auto loop is running.', 'info');
+        return;
+    }
+    requestAutoCancel();
+    ctx.ui.notify('Stopping /task-auto after the current task…', 'warning');
+}
+// ─── Registration ────────────────────────────────────────────────────────────
+export function registerTaskAuto(pi) {
+    pi.registerCommand('task-auto', {
+        description: 'Plan a feature into tasks and run them. Usage: /task-auto <feature>',
+        handler: handleTaskAuto
+    });
+    pi.registerCommand('task-auto-resume', {
+        description: 'Resume the active /task-auto run.',
+        handler: handleTaskAutoResume
+    });
+    pi.registerCommand('task-auto-cancel', {
+        description: 'Stop the running /task-auto loop after the current task.',
+        handler: handleTaskAutoCancel
+    });
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Prompts for /task-auto's two feature-level child calls. These produce a task
+ * LIST only; all research/spec depth is /task's job, run per-title later.
+ */
+/**
+ * Clarify: asks ONE question at a time. Output MUST match parseClarifyList — a
+ * single numbered question followed by a "SUGGESTED: <default>" line, or the
+ * literal token NONE when no clarification remains. priorQA carries the
+ * questions already answered so each next question adapts to them.
+ */
+export declare const AUTO_CLARIFY_PROMPT: (feature: string, priorQA: string) => string;
+/**
+ * Decompose: output a markdown checkbox list of task titles (one line each).
+ */
+export declare const AUTO_DECOMPOSE_PROMPT: (feature: string, clarifications: string) => string;

package/dist/task/auto-prompts.js

@@ -0,0 +1,66 @@
+/**
+ * Prompts for /task-auto's two feature-level child calls. These produce a task
+ * LIST only; all research/spec depth is /task's job, run per-title later.
+ */
+/**
+ * Clarify: asks ONE question at a time. Output MUST match parseClarifyList — a
+ * single numbered question followed by a "SUGGESTED: <default>" line, or the
+ * literal token NONE when no clarification remains. priorQA carries the
+ * questions already answered so each next question adapts to them.
+ */
+export const AUTO_CLARIFY_PROMPT = (feature, priorQA) => `You are planning how to split a feature into separate implementation tasks, one clarifying question at a time.
+
+FEATURE REQUEST:
+${feature.trim()}
+
+ANSWERS SO FAR:
+${priorQA.trim() || '(none yet)'}
+
+You may use the read tool to inspect the repo and any referenced docs so your
+question and recommendation are grounded in what already exists.
+
+Output the SINGLE most important clarifying question that REMAINS — the one whose
+answer would most change HOW this feature is split into tasks (scope boundaries,
+which subsystems are in/out, ordering, the cross-cutting technical choices that
+fork the breakdown). Account for the answers so far:
+- Never re-ask something already answered above.
+- If an answer introduced a new fork or contradicts an assumption (for example,
+  the user chose a framework or tool the request did not anticipate), ask about
+  the most important consequence of that choice next — how it is built, what
+  extra dependencies it pulls in, how it changes the other subsystems.
+- When the feature spans multiple subsystems, work through its forks one at a
+  time (file/blob storage, client/rendering strategy, auth and session model,
+  real-time vs polling transport, search, deployment).
+- Skip anything /task will naturally resolve per-task during its own research.
+
+Also propose the single most sensible default answer for this question, inferred
+from the repo, the referenced docs, and any stated philosophy or constraints —
+concrete and decisive, shown to the user as a recommendation they can accept or
+override.
+
+OUTPUT FORMAT (exact):
+- One clarifying question as a single numbered line: "1. ...".
+- On the NEXT line (never inline), a line that begins with "SUGGESTED: <your recommended default>".
+- 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 the spec already pins down every choice that would change the task breakdown — nothing decision-changing is left to ask — output exactly:
+NONE`;
+/**
+ * Decompose: output a markdown checkbox list of task titles (one line each).
+ */
+export const AUTO_DECOMPOSE_PROMPT = (feature, clarifications) => `Split this feature into an ordered list of implementation tasks. Each task
+will be handed, by its title, to a separate pipeline that does its own research
+and writes its own spec — so here you produce TITLES ONLY, not specs.
+
+FEATURE REQUEST:
+${feature.trim()}
+
+CLARIFICATIONS:
+${clarifications.trim() || '(none)'}
+
+RULES:
+- One task per line, as a markdown checkbox: "- [ ] <title>".
+- Each title is a short imperative phrase; optionally add " — <one key detail>".
+- Order tasks so earlier ones unblock later ones (foundations first).
+- Each task should be independently implementable as a single /task run.
+- Prefer a handful of substantial tasks over many trivial ones.
+- Output the checkbox list and NOTHING else (no preamble, no numbering).`;

package/dist/task/inline-markdown.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Inline-markdown helpers for the clarify/grill question dialogs.
+ *
+ * The model often wraps the core question in **bold** (and code in backticks)
+ * because it makes the question easier to read at a glance. ctx.ui.input titles
+ * accept ANSI styling, so we RENDER those spans to terminal bold/code for the
+ * displayed prompt, and STRIP them to plain text for the editable input default
+ * and the persisted task file (which must stay ANSI-free).
+ */
+/** Minimal theme surface we need; ExtensionCommandContext['ui'].theme satisfies it. */
+export interface InlineMarkdownTheme {
+    bold(text: string): string;
+    fg(color: 'mdCode', text: string): string;
+}
+/** Render **bold** and `code` spans to themed terminal styling for display. */
+export declare function renderInlineMarkdown(text: string, theme: InlineMarkdownTheme): string;
+/** Strip **bold** and `code` markers to plain text (for defaults and storage). */
+export declare function stripInlineMarkdown(text: string): string;

package/dist/task/inline-markdown.js

@@ -0,0 +1,28 @@
+/**
+ * Inline-markdown helpers for the clarify/grill question dialogs.
+ *
+ * The model often wraps the core question in **bold** (and code in backticks)
+ * because it makes the question easier to read at a glance. ctx.ui.input titles
+ * accept ANSI styling, so we RENDER those spans to terminal bold/code for the
+ * displayed prompt, and STRIP them to plain text for the editable input default
+ * and the persisted task file (which must stay ANSI-free).
+ */
+const BOLD_SPAN = /\*\*(.+?)\*\*/g;
+const CODE_SPAN = /`([^`]+)`/g;
+/** Render **bold** and `code` spans to themed terminal styling for display. */
+export function renderInlineMarkdown(text, theme) {
+    return text
+        .replace(BOLD_SPAN, (_, b) => theme.bold(b))
+        .replace(CODE_SPAN, (_, c) => theme.fg('mdCode', c))
+        .replace(/\*\*/g, '') // drop stray/unbalanced bold markers
+        .replace(/`/g, ''); // drop stray backticks
+}
+/** Strip **bold** and `code` markers to plain text (for defaults and storage). */
+export function stripInlineMarkdown(text) {
+    return text
+        .replace(BOLD_SPAN, '$1')
+        .replace(CODE_SPAN, '$1')
+        .replace(/\*\*/g, '')
+        .replace(/`/g, '')
+        .trim();
+}

package/dist/task/orchestrator.d.ts

@@ -51,4 +51,32 @@ export declare class TaskRunner {
     run(): Promise<void>;
     private _deliverSpec;
 }
+export interface RunSingleTaskOptions {
+    /** Await the session going idle after the spec is delivered, so the caller
+     *  blocks until the agent has implemented it. Default false. */
+    waitForImplementation?: boolean;
+    /** Test seam: spawn function forwarded to TaskRunner. */
+    spawnFn?: SpawnFn;
+}
+export interface RunSingleTaskResult {
+    taskId: string;
+    ok: boolean;
+    sessionCancelled: boolean;
+    /**
+     * The session context the caller must use for any work after this call. A
+     * successful run replaces the session via ctx.newSession(), which leaves the
+     * caller's original ctx stale — this is the fresh replacement ctx and callers
+     * MUST adopt it (using the original throws "stale ctx"). On cancellation no
+     * replacement happened, so this is the original, still-live ctx. Optional
+     * only so test fakes that don't model session replacement can omit it.
+     */
+    ctx?: ExtensionCommandContext;
+}
+/**
+ * Run one prompt through the full single-task pipeline in a fresh session and
+ * deliver its spec. With waitForImplementation, block until the agent finishes
+ * implementing the delivered spec. Success is read off the produced task file's
+ * front-matter state (TaskRunner.run never throws).
+ */
+export declare function runSingleTask(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, opts?: RunSingleTaskOptions): Promise<RunSingleTaskResult>;
 export declare function registerTask(pi: ExtensionAPI): void;

package/dist/task/orchestrator.js

@@ -256,6 +256,46 @@ export class TaskRunner {
         }
     }
 }
+/**
+ * Run one prompt through the full single-task pipeline in a fresh session and
+ * deliver its spec. With waitForImplementation, block until the agent finishes
+ * implementing the delivered spec. Success is read off the produced task file's
+ * front-matter state (TaskRunner.run never throws).
+ */
+export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
+    let taskId = '';
+    // The newSession replacement ctx, captured so the caller can keep driving the
+    // UI after the original ctx is torn down. Defaults to the original for the
+    // cancellation path (where no replacement occurs).
+    let freshCtx = ctx;
+    const result = await ctx.newSession({
+        withSession: async (newCtx) => {
+            freshCtx = newCtx;
+            const runner = new TaskRunner(newCtx, cwd, rawPrompt, undefined, async (spec) => {
+                await newCtx.sendUserMessage(spec);
+                if (opts.waitForImplementation)
+                    await newCtx.waitForIdle();
+            }, opts.spawnFn);
+            await runner.run();
+            taskId = runner.taskId;
+        }
+    });
+    if (result.cancelled) {
+        // No replacement happened — the original ctx is still live.
+        return { taskId, ok: false, sessionCancelled: true, ctx };
+    }
+    let ok = false;
+    if (taskId) {
+        try {
+            const { frontMatter } = await readTaskFile(cwd, taskId);
+            ok = frontMatter.state === 'completed';
+        }
+        catch {
+            ok = false;
+        }
+    }
+    return { taskId, ok, sessionCancelled: false, ctx: freshCtx };
+}
 // ─── Command handlers ────────────────────────────────────────────────────────
 async function handleTask(args, ctx) {
     await ctx.waitForIdle();
@@ -266,15 +306,8 @@ async function handleTask(args, ctx) {
         ctx.ui.notify('Type your prompt after /task (use @ for file completion).', 'info');
         return;
     }
-    const result = await ctx.newSession({
-        withSession: async (newCtx) => {
-            const runner = new TaskRunner(newCtx, cwd, raw, undefined, async (spec) => {
-                await newCtx.sendUserMessage(spec);
-            });
-            await runner.run();
-        }
-    });
-    if (result.cancelled) {
+    const { sessionCancelled } = await runSingleTask(ctx, cwd, raw);
+    if (sessionCancelled) {
         ctx.ui.notify('Could not start a fresh session for /task.', 'warning');
     }
 }

package/dist/task/parsers.d.ts

@@ -15,10 +15,17 @@ export type AutoAnswer = {
     suggested?: string;
     raw: string;
 };
+/** One /task-auto clarify question with its model-recommended default answer. */
+export interface ClarifyQuestion {
+    question: string;
+    suggested?: string;
+}
 export declare const GRILL_LINE_RE: RegExp;
+export declare const SUGGESTED_LINE_RE: RegExp;
 export declare const TITLE_MAX_CHARS = 120;
 export declare function parseVerifyBlock(spec: string): VerifyCommand[] | null;
 export declare function parseGrillQuestions(raw: string): string[];
+export declare function parseClarifyList(raw: string): ClarifyQuestion[];
 export declare function parseAutoAnswer(raw: string): AutoAnswer;
 export declare function parseVerifyToolingOutput(output: string): {
     verified: string[];
@@ -28,5 +35,14 @@ export declare function parseVerifyToolingOutput(output: string): {
     }>;
 };
 export declare function isCritiqueClean(text: string): boolean;
+/**
+ * Drop any preamble the model emitted before the spec's GOAL header. The
+ * thinking model sometimes narrates ("Now I have all the context. Here's the
+ * rewritten spec:") before GOAL — the prompts forbid it, but the critique
+ * validator only checks for a VERIFY block, so it leaked into the delivered
+ * spec. We slice from the first line that begins a GOAL section so the spec
+ * starts at GOAL. No GOAL line → returned unchanged (validation then flags it).
+ */
+export declare function stripSpecPreamble(spec: string): string;
 export declare function validateSpecShape(spec: string): string | null;
 export declare function deriveTitle(refined: string): string;

package/dist/task/parsers.js

@@ -6,6 +6,7 @@
 import { MAX_GRILL_QUESTIONS } from './phases.js';
 // ─── Constants ───────────────────────────────────────────────────────────────
 export const GRILL_LINE_RE = /^\s*\d+[.)]\s+(.+)$/;
+export const SUGGESTED_LINE_RE = /^\s*SUGGESTED:\s*(.*)$/i;
 export const TITLE_MAX_CHARS = 120;
 // ─── Verify block parser ─────────────────────────────────────────────────────
 export function parseVerifyBlock(spec) {
@@ -49,6 +50,53 @@ export function parseGrillQuestions(raw) {
     }
     return out;
 }
+// ─── Clarify (/task-auto) parser ─────────────────────────────────────────────
+// Matches a "SUGGESTED:" marker anywhere in a string (not just line-start), so
+// we can recover a recommendation the model wrote inline on the question line
+// (e.g. "1. ...so this must be resolved. SUGGESTED: use polling.") rather than
+// on its own line.
+const INLINE_SUGGESTED_RE = /\bSUGGESTED:\s*/i;
+/** Split a question line's text into the question and any inline SUGGESTED default. */
+function splitInlineSuggested(text) {
+    const m = INLINE_SUGGESTED_RE.exec(text);
+    if (!m)
+        return { question: text.trim() };
+    const question = text.slice(0, m.index).trim();
+    const suggested = text.slice(m.index + m[0].length).trim();
+    return suggested.length > 0 ? { question, suggested } : { question };
+}
+// Parses the /task-auto clarify output: a numbered question list where each
+// question carries a "SUGGESTED: <default>" recommendation — either on its own
+// line below the question, or inline at the end of the question line. The first
+// SUGGESTED for a question wins; later ones are ignored. The literal token NONE
+// (its own line) means "no clarification needed" → [].
+//
+// Question/suggested text is returned VERBATIM (markdown intact). Inline
+// markdown is rendered for display / stripped for storage at the call site via
+// the helpers in inline-markdown.ts.
+export function parseClarifyList(raw) {
+    if (/^\s*NONE\s*$/m.test(raw))
+        return [];
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const q = GRILL_LINE_RE.exec(line);
+        if (q) {
+            if (out.length >= MAX_GRILL_QUESTIONS)
+                break;
+            out.push(splitInlineSuggested(q[1].trim()));
+            continue;
+        }
+        const s = SUGGESTED_LINE_RE.exec(line);
+        if (s && out.length > 0) {
+            const suggested = s[1].trim();
+            const last = out[out.length - 1];
+            if (suggested.length > 0 && last.suggested === undefined) {
+                last.suggested = suggested;
+            }
+        }
+    }
+    return out;
+}
 // ─── Auto-answer parser ──────────────────────────────────────────────────────
 export function parseAutoAnswer(raw) {
     const lines = raw
@@ -120,6 +168,28 @@ export function isCritiqueClean(text) {
     return /^CLEAN[.!]?$/i.test(firstLine);
 }
 // ─── Spec shape validator ────────────────────────────────────────────────────
+/**
+ * Drop any preamble the model emitted before the spec's GOAL header. The
+ * thinking model sometimes narrates ("Now I have all the context. Here's the
+ * rewritten spec:") before GOAL — the prompts forbid it, but the critique
+ * validator only checks for a VERIFY block, so it leaked into the delivered
+ * spec. We slice from the first line that begins a GOAL section so the spec
+ * starts at GOAL. No GOAL line → returned unchanged (validation then flags it).
+ */
+export function stripSpecPreamble(spec) {
+    const lines = spec.split('\n');
+    const idx = lines.findIndex(l => /^GOAL\b/i.test(l));
+    if (idx <= 0)
+        return spec;
+    // Only strip plain narration. If the lead-in is a markdown fence or a
+    // cat-heredoc wrapper, leave it untouched — that's a malformation
+    // validateSpecShape must reject (and compose must retry on), not something
+    // to silently unwrap into a passing spec.
+    const preamble = lines.slice(0, idx);
+    if (preamble.some(l => /^\s*```/.test(l) || /^\s*cat\s*<</.test(l)))
+        return spec;
+    return lines.slice(idx).join('\n');
+}
 export function validateSpecShape(spec) {
     const trimmed = spec.trim();
     if (trimmed.length === 0)