@mjasnikovs/pi-task 0.13.6 → 0.13.7

package/dist/task/parsers.js

@@ -7,31 +7,6 @@ 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;
-// ─── Verify block parser ─────────────────────────────────────────────────────
-export function parseVerifyBlock(spec) {
-    const lines = spec.split('\n');
-    let i = 0;
-    while (i < lines.length && !/^VERIFY:\s*$/.test(lines[i]))
-        i++;
-    if (i >= lines.length)
-        return null;
-    i++;
-    while (i < lines.length && lines[i].trim() === '')
-        i++;
-    if (i >= lines.length)
-        return null;
-    if (!/^```(sh|bash)?\s*$/.test(lines[i]))
-        return null;
-    i++;
-    const cmds = [];
-    while (i < lines.length && !/^```\s*$/.test(lines[i])) {
-        const line = lines[i].trim();
-        if (line.length > 0 && !line.startsWith('#'))
-            cmds.push({ raw: line });
-        i++;
-    }
-    return cmds;
-}
 // ─── Grill questions parser ──────────────────────────────────────────────────
 // The grill-gen prompt instructs the worker to emit the literal token `NONE`
 // when it has zero questions, so the runner's empty-output guard can still
@@ -97,6 +72,14 @@ export function parseClarifyList(raw) {
     return out;
 }
 // ─── Auto-answer parser ──────────────────────────────────────────────────────
+// Did the model use one of the required output tags (ANSWER/UNKNOWN/ALT,
+// tolerating the same ANSWER misspellings parseAutoAnswer accepts)? When no tag
+// is present the model ignored the format and wrote free-form prose, so the
+// caller reprompts instead of trusting parseAutoAnswer's lenient salvage.
+const AUTO_ANSWER_TAG_RE = /^\s*(AN[SW]{1,3}E?R|UNKNOWN|ALT)\s*:/im;
+export function autoAnswerHasTag(raw) {
+    return AUTO_ANSWER_TAG_RE.test(raw);
+}
 export function parseAutoAnswer(raw) {
     const lines = raw
         .split('\n')
@@ -140,8 +123,15 @@ export function parseAutoAnswer(raw) {
             raw
         };
     }
-    if (lines.length > 0)
-        return { kind: 'unknown', suggested: lines[0], raw };
+    // Last-resort salvage: the model emitted no tag at all. Take the first line
+    // that reads like an answer, NOT a preamble — a trailing colon marks a
+    // heading ("Here's the analysis:") that introduces prose rather than
+    // recommending anything. Surfacing such a line as the recommendation is the
+    // "wrong format" the user sees; better to offer no default and let them
+    // answer than to pre-fill a meaningless preamble.
+    const salvaged = lines.find(l => !l.endsWith(':'));
+    if (salvaged)
+        return { kind: 'unknown', suggested: salvaged, raw };
     return { kind: 'unknown', raw };
 }
 // ─── Verify tooling output parser ────────────────────────────────────────────
@@ -173,63 +163,6 @@ export function parseVerifyToolingOutput(output) {
     }
     return { verified, rejected };
 }
-// ─── Critique triage parser ──────────────────────────────────────────────────
-// The critique-triage prompt instructs the worker to emit the literal token
-// `CLEAN` on its own line when the compose draft has no substantive defects, so
-// we can skip the expensive full-rewrite pass. Anything else is treated as a
-// defect list that gets fed into the rewrite. Empty output is NOT clean — that
-// would be a silent crash, and treating it as clean would skip review entirely.
-export function isCritiqueClean(text) {
-    const firstLine = text
-        .split('\n')
-        .map(l => l.trim())
-        .find(l => l.length > 0);
-    if (!firstLine)
-        return false;
-    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)
-        return 'spec is empty';
-    const firstLine = trimmed.split('\n', 1)[0];
-    if (/^\s*```/.test(firstLine))
-        return 'spec starts with a markdown fence';
-    if (/^\s*cat\s*<<\s*['"]?[A-Za-z_][A-Za-z0-9_]*['"]?/.test(firstLine)) {
-        return 'spec is wrapped in a cat heredoc';
-    }
-    if (!/^GOAL\b/i.test(trimmed))
-        return 'spec does not start with GOAL';
-    for (const section of ['CONSTRAINTS', 'ACCEPTANCE', 'VERIFY']) {
-        if (!new RegExp(`^\\s*${section}\\b`, 'm').test(trimmed)) {
-            return `spec missing required section: ${section}`;
-        }
-    }
-    return null;
-}
 // ─── Title derivation ────────────────────────────────────────────────────────
 export function deriveTitle(refined) {
     const stripBold = (s) => s.replace(/^\*+|\*+$/g, '').trim();

package/dist/task/phases.d.ts

@@ -3,11 +3,12 @@
  * critique) plus the config table that drives the orchestrator loop.
  */
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
-import { docsRaw, docsFocused } from '../workers/docs-core.js';
-import { fetchRaw, fetchFocused } from '../workers/fetch-core.js';
+import { docsFocused } from '../workers/docs-core.js';
+import { fetchFocused } from '../workers/fetch-core.js';
 import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
+import { type ExternalContextDeps } from './external-context.js';
 import { MAX_GRILL_QUESTIONS } from './prompts.js';
-import { type PhaseName } from './task-file.js';
+import { type PhaseName } from './task-types.js';
 import { type WidgetState } from './widget.js';
 import { type AutoAnswer } from './parsers.js';
 import { type PhaseDeps } from './child-runner.js';
@@ -36,11 +37,8 @@ export declare function extractToolingCommands(research: string): string[] | nul
 export declare function replaceToolingWithVerified(research: string, verifiedCommands: string[]): string;
 export declare const phaseRefine: (deps: PhaseDeps, raw: string) => Promise<string>;
 export declare function phaseVerifyTooling(deps: PhaseDeps, research: string): Promise<string>;
-export interface PhaseResearchDeps {
-    docsRaw?: typeof docsRaw;
-    fetchRaw?: typeof fetchRaw;
+export interface PhaseResearchDeps extends ExternalContextDeps {
     getFileInventory?: (cwd: string, signal?: AbortSignal) => Promise<string>;
-    searchFn?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
 }
 export declare function phaseResearch(deps: PhaseDeps, refined: string, researchDeps?: PhaseResearchDeps): Promise<string>;
 export interface PhaseAutoAnswerDeps {

package/dist/task/phases.js

@@ -2,18 +2,20 @@
  * Phase pipeline — the five phase functions (refine, research, grill, compose,
  * critique) plus the config table that drives the orchestrator loop.
  */
-import { docsRaw, docsFocused } from '../workers/docs-core.js';
-import { fetchRaw, fetchFocused } from '../workers/fetch-core.js';
+import { docsFocused } from '../workers/docs-core.js';
+import { fetchFocused } from '../workers/fetch-core.js';
 import { formatNpmVersionSection } from '../workers/npm-version.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { search as defaultSearch } from '../workers/search-core.js';
 import { extractEnrichTargets } from './enrichment.js';
 import { getFileInventory } from './file-inventory.js';
 import { formatServiceBlock, formatFreshnessSkippedBlock } from './service-blocks.js';
-import { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, MAX_GRILL_QUESTIONS, appendNoThink } from './prompts.js';
-import { setTaskSection, updateTaskFrontMatter } from './task-file.js';
+import { gatherExternalContext } from './external-context.js';
+import { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, GRILL_AUTO_FORMAT_HINT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, MAX_GRILL_QUESTIONS, appendNoThink } from './prompts.js';
+import { setTaskSection, updateTaskFrontMatter } from './task-io.js';
 import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js';
-import { parseVerifyBlock, parseGrillQuestions, parseAutoAnswer, parseVerifyToolingOutput, validateSpecShape, stripSpecPreamble, deriveTitle, isCritiqueClean } from './parsers.js';
+import { parseGrillQuestions, parseAutoAnswer, autoAnswerHasTag, parseVerifyToolingOutput, deriveTitle } from './parsers.js';
+import { parseVerifyBlock, validateSpecShape, stripSpecPreamble, isCritiqueClean } from './spec-validation.js';
 import { runPhaseChild, runPhaseWithLoopGuard, runWithEmphasisRetry, prependHint, USER_CANCELLED } from './child-runner.js';
 import { SessionUI } from '../remote/bridge.js';
 // ─── Re-export constants from their home modules ────────────────────────────
@@ -76,75 +78,8 @@ export async function phaseVerifyTooling(deps, research) {
 }
 const DOCS_EXTENSION_PATH = new URL('../workers/docs-extension.js', import.meta.url).pathname;
 export async function phaseResearch(deps, refined, researchDeps = {}) {
-    const docsRawFn = researchDeps.docsRaw ?? docsRaw;
-    const fetchRawFn = researchDeps.fetchRaw ?? fetchRaw;
     const fileInventoryFn = researchDeps.getFileInventory ?? getFileInventory;
-    const searchFn = researchDeps.searchFn ?? defaultSearch;
-    const enrichTargets = extractEnrichTargets(refined);
-    const enrichSections = [];
-    if (enrichTargets.packages.length > 0
-        || enrichTargets.urls.length > 0
-        || enrichTargets.services.length > 0) {
-        const tEnrichStart = Date.now();
-        const [docsResults, fetchResults, serviceResults] = await Promise.all([
-            Promise.all(enrichTargets.packages.map(pkg => docsRawFn({
-                pkg,
-                query: refined.split('\n').find(l => l.trim()) ?? refined,
-                cwd: deps.cwd,
-                signal: deps.signal
-            }).catch(() => null))),
-            Promise.all(enrichTargets.urls.map(url => fetchRawFn({ url, signal: deps.signal }).catch(() => null))),
-            Promise.all(enrichTargets.services.map(s => searchFn({
-                query: `${s.name} ${s.query}`,
-                count: 3,
-                signal: deps.signal
-            }).catch(() => null)))
-        ]);
-        // npm version blocks come from docsRaw's bundled lookup and lead the
-        // section so the model anchors on live version data before reading
-        // the docs body.
-        for (let i = 0; i < enrichTargets.packages.length; i++) {
-            const v = docsResults[i]?.npmVersion;
-            if (v)
-                enrichSections.push(formatNpmVersionSection(v));
-        }
-        for (let i = 0; i < enrichTargets.packages.length; i++) {
-            const r = docsResults[i];
-            if (r?.kind === 'ok' && r.chunks.length > 0) {
-                const body = r.chunks
-                    .map(c => c.content)
-                    .join('\n\n')
-                    .slice(0, 4000);
-                enrichSections.push(`### docs: ${enrichTargets.packages[i]}\n${body}`);
-            }
-        }
-        for (let i = 0; i < enrichTargets.urls.length; i++) {
-            const r = fetchResults[i];
-            if (r) {
-                enrichSections.push(`### url: ${enrichTargets.urls[i]}\n${r.markdown.slice(0, 4000)}`);
-            }
-        }
-        const skipped = [];
-        for (let i = 0; i < enrichTargets.services.length; i++) {
-            const s = enrichTargets.services[i];
-            const r = serviceResults[i];
-            if (r === null)
-                continue;
-            if (r.kind === 'no_key') {
-                skipped.push(s.name);
-                continue;
-            }
-            if (r.kind === 'error')
-                continue;
-            // kind === 'ok'
-            enrichSections.push(formatServiceBlock(s.name, `${s.name} ${s.query}`, r.results));
-        }
-        if (skipped.length > 0) {
-            enrichSections.push(formatFreshnessSkippedBlock(skipped));
-        }
-        deps.recordSubStep?.('enrichment', Date.now() - tEnrichStart);
-    }
-    const externalContext = enrichSections.length > 0 ? `EXTERNAL CONTEXT\n${enrichSections.join('\n\n')}\n\n` : '';
+    const externalContext = await gatherExternalContext(refined, deps, researchDeps);
     // Pre-compute the project file inventory once and hand it to every worker.
     // Workers can then jump straight to targeted read/grep on known paths
     // instead of each spawning its own discovery loop (find/ls). A '' result
@@ -156,8 +91,9 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     let doneCount = 0;
     const updateProgress = () => {
         doneCount++;
-        if (deps.onChildOutput)
-            deps.onChildOutput(`research (${doneCount}/4 workers done)`);
+        if (deps.onChildOutput) {
+            deps.onChildOutput(`research (${doneCount}/${workerSpecs.length} workers done)`);
+        }
     };
     // Per-worker timing split into wait (spawn → first byte) and work (first
     // byte → exit). The workers run sequentially below, so each split is a clean
@@ -190,16 +126,19 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     // tooling) is preserved for assembly.
     const workerSpecs = [
         {
+            section: 'FILES',
             label: 'worker:files',
             prompt: appendNoThink(promptHeader + RESEARCH_FILES_PROMPT(refined))
         },
         {
+            section: 'APIS',
             label: 'worker:apis',
             prompt: appendNoThink(promptHeader + RESEARCH_APIS_PROMPT(refined)),
             tools: 'read,grep,find,ls,pi-worker-docs',
             extensions: [DOCS_EXTENSION_PATH]
         },
         {
+            section: 'CONTEXT',
             label: 'worker:context',
             prompt: appendNoThink(promptHeader + RESEARCH_CONTEXT_PROMPT(refined)),
             // Context owns architectural understanding, not path discovery —
@@ -209,6 +148,7 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             tools: 'read,grep'
         },
         {
+            section: 'TOOLING',
             label: 'worker:tooling',
             prompt: appendNoThink(promptHeader + RESEARCH_TOOLING_PROMPT(refined))
         }
@@ -234,13 +174,10 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
         updateProgress();
         workerResults.push(r);
     }
-    const [files, apis, context, tooling] = workerResults;
-    const sections = [
-        { name: 'FILES', result: files },
-        { name: 'APIS', result: apis },
-        { name: 'CONTEXT', result: context },
-        { name: 'TOOLING', result: tooling }
-    ];
+    // Validate + assemble by mapping spec.section over the results, so adding or
+    // reordering a worker is a single edit to workerSpecs (the result order
+    // mirrors workerSpecs order — the loop above pushes in sequence).
+    const sections = workerSpecs.map((spec, i) => ({ name: spec.section, result: workerResults[i] }));
     for (const { name, result } of sections) {
         if (result.exitCode !== 0) {
             throw new Error(`Research ${name} worker failed (exit ${result.exitCode}): ${result.stderr.slice(-500)}`);
@@ -253,7 +190,7 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
                 + `(${result.leakedToolCall.trim()}) — it never ran`);
         }
     }
-    return `FILES\n${files.text}\n\nAPIS\n${apis.text}\n\nCONTEXT\n${context.text}\n\nTOOLING\n${tooling.text}`;
+    return sections.map(({ name, result }) => `${name}\n${result.text}`).join('\n\n');
 }
 export async function phaseAutoAnswer(deps, refined, research, question, autoDeps = {}) {
     const docsFocusedFn = autoDeps.docsFocused ?? docsFocused;
@@ -336,7 +273,15 @@ export async function phaseAutoAnswer(deps, refined, research, question, autoDep
         const externalContext = contextSections.length > 0 ?
             `EXTERNAL CONTEXT\n${contextSections.join('\n\n')}\n\n`
             : '';
-        const text = await runPhaseChild(deps, 'grill-auto', 'read', externalContext + GRILL_AUTO_ANSWER_PROMPT(refined, research, question));
+        const basePrompt = externalContext + GRILL_AUTO_ANSWER_PROMPT(refined, research, question);
+        let text = await runPhaseChild(deps, 'grill-auto', 'read', basePrompt);
+        if (!autoAnswerHasTag(text)) {
+            // The model ignored the ANSWER/UNKNOWN/ALT format and wrote prose
+            // (typically an "analysis" preamble). Reprompt once, forcing the
+            // tagged form, before falling back to parseAutoAnswer's salvage —
+            // otherwise a preamble line leaks out as the recommended answer.
+            text = await runPhaseChild(deps, 'grill-auto', 'read', prependHint(GRILL_AUTO_FORMAT_HINT, basePrompt));
+        }
         return parseAutoAnswer(text);
     }
     catch (err) {

package/dist/task/prompts.d.ts

@@ -36,6 +36,7 @@ declare const RESEARCH_CONTEXT_PROMPT: (refined: string) => string;
 declare const RESEARCH_TOOLING_PROMPT: (refined: string) => string;
 declare const GRILL_GEN_PROMPT: (refined: string, research: string, priorQA: string) => string;
 declare const GRILL_AUTO_ANSWER_PROMPT: (refined: string, research: string, question: string) => string;
+export declare const GRILL_AUTO_FORMAT_HINT: string;
 declare function composeRetryEmphasis(problem: string): string;
 declare const COMPOSE_PROMPT: (refined: string, research: string, qa: string, retryProblem: string | null) => string;
 declare const CRITIQUE_TRIAGE_PROMPT: (spec: string, refined: string, qa: string) => string;

package/dist/task/prompts.js

@@ -215,6 +215,15 @@ Research:
 ${research}
 
 Question: ${question}`;
+// Reprompt prefix when grill-auto's first reply ignored the tagged output format
+// and wrote free-form prose (an "analysis" preamble). Forces the terse form so a
+// real recommendation reaches the user instead of a leaked preamble line.
+export const GRILL_AUTO_FORMAT_HINT = '[SYSTEM NOTE: Your previous reply did NOT follow the required format — it had no '
+    + 'ANSWER:, UNKNOWN:, or ALT: line and read as free-form prose. Do not explain or '
+    + 'analyse. Output ONLY the tagged lines and nothing else. For a binary "A or B?" '
+    + 'question emit two lines:\nUNKNOWN: <primary option>\nALT: <alternative>\n'
+    + 'For a safe default the user would accept without thinking, emit one ANSWER: line. '
+    + 'No preamble, no markdown.]';
 function composeRetryEmphasis(problem) {
     if (problem === 'spec does not start with GOAL'
         || problem === 'spec starts with a markdown fence'

package/dist/task/spec-validation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Spec gate — the guards that decide whether a composed spec is acceptable at
+ * handoff. Unlike the informational parsers in parsers.ts, these answer a
+ * yes/no (or "what's wrong") question the orchestrator and critique phase act
+ * on: is the VERIFY block runnable, is the shape well-formed, did critique come
+ * back CLEAN. Self-contained (no imports) so the gate doesn't drag in the phase
+ * pipeline.
+ */
+export interface VerifyCommand {
+    raw: string;
+}
+export declare function parseVerifyBlock(spec: string): VerifyCommand[] | null;
+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;

package/dist/task/spec-validation.js

@@ -0,0 +1,90 @@
+/**
+ * Spec gate — the guards that decide whether a composed spec is acceptable at
+ * handoff. Unlike the informational parsers in parsers.ts, these answer a
+ * yes/no (or "what's wrong") question the orchestrator and critique phase act
+ * on: is the VERIFY block runnable, is the shape well-formed, did critique come
+ * back CLEAN. Self-contained (no imports) so the gate doesn't drag in the phase
+ * pipeline.
+ */
+// ─── Verify block parser ─────────────────────────────────────────────────────
+export function parseVerifyBlock(spec) {
+    const lines = spec.split('\n');
+    let i = 0;
+    while (i < lines.length && !/^VERIFY:\s*$/.test(lines[i]))
+        i++;
+    if (i >= lines.length)
+        return null;
+    i++;
+    while (i < lines.length && lines[i].trim() === '')
+        i++;
+    if (i >= lines.length)
+        return null;
+    if (!/^```(sh|bash)?\s*$/.test(lines[i]))
+        return null;
+    i++;
+    const cmds = [];
+    while (i < lines.length && !/^```\s*$/.test(lines[i])) {
+        const line = lines[i].trim();
+        if (line.length > 0 && !line.startsWith('#'))
+            cmds.push({ raw: line });
+        i++;
+    }
+    return cmds;
+}
+// ─── Critique triage gate ────────────────────────────────────────────────────
+// The critique-triage prompt instructs the worker to emit the literal token
+// `CLEAN` on its own line when the compose draft has no substantive defects, so
+// we can skip the expensive full-rewrite pass. Anything else is treated as a
+// defect list that gets fed into the rewrite. Empty output is NOT clean — that
+// would be a silent crash, and treating it as clean would skip review entirely.
+export function isCritiqueClean(text) {
+    const firstLine = text
+        .split('\n')
+        .map(l => l.trim())
+        .find(l => l.length > 0);
+    if (!firstLine)
+        return false;
+    return /^CLEAN[.!]?$/i.test(firstLine);
+}
+// ─── Spec shape gate ─────────────────────────────────────────────────────────
+/**
+ * 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)
+        return 'spec is empty';
+    const firstLine = trimmed.split('\n', 1)[0];
+    if (/^\s*```/.test(firstLine))
+        return 'spec starts with a markdown fence';
+    if (/^\s*cat\s*<<\s*['"]?[A-Za-z_][A-Za-z0-9_]*['"]?/.test(firstLine)) {
+        return 'spec is wrapped in a cat heredoc';
+    }
+    if (!/^GOAL\b/i.test(trimmed))
+        return 'spec does not start with GOAL';
+    for (const section of ['CONSTRAINTS', 'ACCEPTANCE', 'VERIFY']) {
+        if (!new RegExp(`^\\s*${section}\\b`, 'm').test(trimmed)) {
+            return `spec missing required section: ${section}`;
+        }
+    }
+    return null;
+}

package/dist/task/widget.d.ts

@@ -5,7 +5,7 @@
  * context usage, and the latest child-process line.
  */
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
-import { type PhaseName, type TaskState } from './task-file.js';
+import { type PhaseName, type TaskState } from './task-types.js';
 export interface WidgetState {
     taskId: string;
     title: string;

package/dist/task/widget.js

@@ -4,7 +4,7 @@
  * Renders a live-updating status block showing task id, phase, elapsed time,
  * context usage, and the latest child-process line.
  */
-import { PHASE_INDEX, PHASE_ORDER } from './task-file.js';
+import { PHASE_INDEX, PHASE_ORDER } from './task-types.js';
 import { setTaskWidget } from '../remote/session-state.js';
 // ─── Constants ───────────────────────────────────────────────────────────────
 export const WIDGET_KEY = 'pi-tasks';