@mjasnikovs/pi-task 0.2.0

package/dist/task/prompts.js

@@ -0,0 +1,346 @@
+/**
+ * Prompt templates for every phase of the pi-task pipeline.
+ *
+ * Each template is a pure function: inputs → prompt string.  No I/O, no side
+ * effects, trivially testable.
+ */
+export const MAX_GRILL_QUESTIONS = 10;
+const REFINE_PROMPT = (raw) => `You receive a user's task description for an AI coding agent. Rewrite it to be unambiguous and actionable.
+
+Output structure (four sections, exact headings, in this order):
+
+GOAL
+  One paragraph. What done looks like, in the user's domain language.
+
+CONSTRAINTS
+  Bullet list. What must not change, what semantics to preserve, what the agent should avoid touching.
+
+KNOWN-UNKNOWNS
+  Bullet list. Questions worth asking the user before implementing, inferred from gaps or ambiguities in the raw prompt.
+
+EXTERNAL-DEPENDENCIES
+  Bullet list. Third-party APIs, SDKs, services, protocols, or cloud products the task touches. One bullet per dependency. Format each bullet as:
+    - <name>  <one-line search-friendly phrase optimized for current-state web search>
+  Two or more spaces separate name from phrase.
+  Do NOT list npm packages here — they flow through the existing backtick-package path. If the task mentions a service only by its npm SDK name (e.g. \`@twurple/api\`), still list the underlying service (Twitch) here.
+  If the task is purely local with no third-party services, leave this section header in place with zero bullets.
+
+Rules:
+- Fix spelling and grammar; output in English regardless of input language.
+- Preserve every concrete identifier verbatim (paths, function names, ports, env vars, file:line refs).
+- Do not invent requirements not implied by the input.
+- Do not output any preamble, commentary, or markdown headings beyond the four sections above.
+
+Task: ${raw}`;
+// ─── Research fan-out prompts ─────────────────────────────────────────────────
+const RESEARCH_READ_ONLY_CONSTRAINT = `IMPORTANT: You are ONLY allowed to READ. Do NOT create, modify, or delete any files. Use the read, grep, find, and ls tools to inspect the repo.`;
+// Shared guard for every research worker. Open-ended tasks ("analyze the code",
+// "how would you improve X", "write a report") tempt a worker into producing the
+// deliverable itself — e.g. writing the whole code-review report in the CONTEXT
+// section, which then runs for many minutes, gets truncated, and poisons every
+// downstream phase. Research only gathers INPUTS for a later spec; it must never
+// be the deliverable. This also pins the output format (no preamble, no fences,
+// no repeated header) that large/open-ended tasks otherwise drift away from.
+const RESEARCH_INPUTS_NOT_DELIVERABLE = `CRITICAL — you are gathering INPUTS for a later spec, NOT performing the task. Even if the task asks you to analyze, review, audit, report, plan, design, or write code, you must NOT produce that deliverable here. Do not write the report/analysis/plan/code. Your entire job is to emit the one structured section described below, which feeds a separate phase that writes the spec. Surveying the repo so that section is accurate is right; producing the task's output is wrong and wastes the run.
+
+OUTPUT DISCIPLINE — strict: emit ONLY the raw section lines described below. No preamble (never "I've read the codebase…", never "Here is the … section"), no closing remarks, no Markdown headings, no code fences (no \`\`\`), and do NOT repeat the section name as a header. The first character of your output is the first entry of the list.`;
+const RESEARCH_FILES_PROMPT = (refined) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools to locate every path on disk the agent will read, edit, or reference for the following task. This includes source code AND configuration, schemas, fixtures — any file the agent needs to know exists.
+
+FILES owns paths. APIS owns symbols. Do not omit a path because it "feels like config" — if the agent will touch or read it, list it here.
+
+When a task operates across a whole directory tree (e.g. lint, typecheck, build, format, test-all), list the root directory entry (\`src/  one-line purpose\`) instead of enumerating every file under it. Enumerate individual files only when they need to be singled out — modified specifically, called out by name in the task, or distinct from their siblings in some material way.
+
+RELEVANCE — read carefully: list ONLY paths this specific task touches — the files the agent will read, edit, or must be aware of to complete THIS task. Do NOT inventory the whole repo or list files just because they exist. A file the agent will never open does not belong here. Aim for the smallest sufficient set: include every path the task genuinely reaches and nothing more. There is no fixed limit — a broad task may need many entries, a narrow one only a few. Right-size to the task, not to a number, and collapse directories to their root entry where the task spans a whole tree.
+
+${RESEARCH_INPUTS_NOT_DELIVERABLE}
+
+${RESEARCH_READ_ONLY_CONSTRAINT}
+
+Output ONLY the content of a FILES section — one entry per line, format:
+  <path>[:<line>]  <one-line purpose>
+
+No section header. No other sections. No preamble.
+
+Task:
+${refined}`;
+const RESEARCH_APIS_PROMPT = (refined) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools to identify the commands, functions, types, and interfaces the agent will use for the following task.
+
+APIS owns symbols and commands BY NAME ONLY. Do NOT include any file path or path fragment — no \`package.json\`, no \`./src/foo.ts\`, no \`package.json#scripts.lint\`. If the symbol is a script defined in package.json, write the invocation (\`npm run lint\`), not its location. If the symbol is a config file, it does not belong in APIS at all — it belongs in FILES.
+
+RELEVANCE — read carefully: list ONLY the symbols the agent will call, implement, modify, or directly depend on for THIS task. Do NOT enumerate the project's entire public surface or dump every exported function in a touched file. A symbol unrelated to the task does not belong here just because it sits in the same module. Keep the smallest sufficient set: include every symbol the task actually exercises and nothing more. There is no fixed limit — list as many as the task truly needs and no padding beyond that.
+
+${RESEARCH_INPUTS_NOT_DELIVERABLE}
+
+${RESEARCH_READ_ONLY_CONSTRAINT}
+
+Output ONLY the content of an APIS section — one entry per line, format:
+  <name>  <one-line signature or use>
+
+No section header. No other sections. No preamble.
+
+Task:
+${refined}`;
+const RESEARCH_CONTEXT_PROMPT = (refined) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools to gather background knowledge and architectural context the agent will need for the following task.
+
+RELEVANCE — read carefully: keep it tight. Each bullet must be an architectural fact that changes HOW the agent implements THIS task — a constraint, a non-obvious data flow, a gotcha, a hidden coupling. No general project tour, no restating the task, no facts the agent would not act on. If a bullet would not change a single implementation decision, drop it. There is no fixed bullet count — include every fact that bears on the task and no filler; fewer sharp bullets beat many shallow ones. If the task is itself an analysis or review, these bullets capture facts that analysis will rely on — they are NOT the analysis; do not write findings or recommendations here.
+
+${RESEARCH_INPUTS_NOT_DELIVERABLE}
+
+${RESEARCH_READ_ONLY_CONSTRAINT}
+
+LIVE-DATA RULE:
+- If EXTERNAL CONTEXT contains an "### npm: <pkg>" block, those version numbers are LIVE registry data. Cite them verbatim if you mention versions at all.
+- If EXTERNAL CONTEXT contains a "### service: <name>" block, those search results are LIVE web data and are authoritative over training data for that service's current API surface, deprecation status, and replacement systems. Do not contradict them from memory. If you must cite a version, status, or API name for that service, take it from the block.
+- If EXTERNAL CONTEXT contains a "### freshness-check skipped" block, you have no current data for the listed services. Do NOT claim their current state from memory; say "current state not verified" and recommend the user verify before implementation.
+- Do NOT write bullets like "X is the latest stable" or "version Y is current" from memory — your training data goes stale. Either quote from EXTERNAL CONTEXT or omit the claim entirely.
+
+Output ONLY the content of a CONTEXT section — bullet list, one bullet per line, format:
+  - <bullet>
+
+No section header. No other sections. No preamble.
+
+Task:
+${refined}`;
+const RESEARCH_TOOLING_PROMPT = (refined) => `You are doing targeted research for an AI coding agent. Inspect the repo to identify the verification tools (lint, typecheck, test, build, e2e, container, dev-server) the project actually has.
+
+${RESEARCH_INPUTS_NOT_DELIVERABLE}
+
+${RESEARCH_READ_ONLY_CONSTRAINT}
+
+Look at package.json scripts, Makefile, pyproject.toml, go.mod, Dockerfile, docker-compose.y*ml, playwright.config.*, .eslintrc*, tsconfig.json, etc. Use exact commands, not guesses. If a tool isn't present in the repo, omit it — don't invent.
+
+Output ONLY the content of a TOOLING section — one entry per line, format:
+  <category>  <exact command to invoke>
+
+Categories: lint, typecheck, test, build, e2e/browser, container, dev-server
+
+No section header. No other sections. No preamble. May be empty if no verification tools are found.
+
+Task:
+${refined}`;
+const GRILL_GEN_PROMPT = (refined, research) => `You are preparing clarifying questions for the user, based on a refined task description and the research that follows.
+
+Start from the KNOWN-UNKNOWNS bullets in the task. Add any new ambiguity surfaced by the research. Drop any unknowns the research already resolved.
+
+SCOPE RULES — read carefully:
+- Questions must clarify the EXISTING scope. Do NOT propose new deliverables, enhancements, modernizations, or "while I'm here" cleanups.
+- Forbidden patterns: "should I also…", "should we modernize…", "do you want me to update X while I'm at it…", "should I integrate Y…", "would you like guidance on Z…".
+- Allowed patterns: "by 'X' do you mean A or B?", "should failure mode Y be treated as Z?", "which of <files matching the task> applies here?".
+- If the refined task + research leave no genuine ambiguity, output zero questions. Zero questions is a valid and preferred outcome. Do not pad.
+
+Output format — read carefully:
+- If you have questions: emit them as a plain numbered list, one per line, at most ${MAX_GRILL_QUESTIONS}, no preamble.
+- If you have zero questions: emit the single literal token NONE on its own line. Do NOT emit empty output — an empty response is treated as a crash, not as "no questions". The NONE sentinel is the only way to signal an intentional empty list.
+
+Refined task:
+${refined}
+
+Research:
+${research}`;
+const GRILL_AUTO_ANSWER_PROMPT = (refined, research, question) => `You are pre-answering a clarifying question for an AI coding task. You have the refined task and the research notes. You can also use the read tool to open any file mentioned in the research (e.g. package.json) if it helps you answer.
+
+Your job is to produce a recommended default answer. If the default is one the user would almost certainly accept, you tag it ANSWER and we skip the user entirely. Otherwise you tag it UNKNOWN and we show the suggestion in the input box for the user to confirm or override.
+
+YOU MUST PROPOSE A DEFAULT, no matter what. NEVER refuse. NEVER leave the answer empty.
+
+LIVE-DATA RULE — read carefully:
+- If EXTERNAL CONTEXT contains an "### npm: <pkg>" block, those version numbers are LIVE registry data and are MORE RECENT than anything you remember from training. Use them as the source of truth.
+- For any question about "latest", "current", "newest", or "which version" of an npm package, you MUST cite the version from the "### npm: <pkg>" block in EXTERNAL CONTEXT if one is present. Do NOT contradict it with a remembered version.
+- If EXTERNAL CONTEXT contains a "### service: <name>" block, those search results are LIVE web data and are authoritative over training data for that service's current API surface, deprecation status, and replacement systems. For any question about that service's API, status, or replacement, cite from the block; do not contradict it from memory.
+- If EXTERNAL CONTEXT contains a "### freshness-check skipped" block, you have no current data for the listed services. If the question is about one of them, tag UNKNOWN and say the current state needs user verification — do NOT answer from memory.
+- If no "### npm: <pkg>" block is present and the question is about latest/current versions, tag UNKNOWN — do not invent a version from training data, since that data goes stale within months.
+
+Use the REVERSIBILITY TEST to choose the tag:
+
+  ANSWER: accepting your default is cheap to undo — output style, reporting
+          format, treat-as-error policy, summary vs full output, scope when
+          obviously implied, recommended convention for a typical project.
+          If the user would only "fix" your default by editing prose in the
+          task file, it's ANSWER.
+
+  UNKNOWN: accepting your default would do work that is costly to reverse —
+           file mutations, destructive operations, irreversible writes, tool
+           or dependency choices, format/structure decisions that change
+           downstream artifacts, anything that touches state outside the
+           task file. This INCLUDES choosing the implementation approach,
+           algorithm, or strategy — *how* the task is solved, not just
+           whether (e.g. "extract the value with a post-processing regex" vs
+           "rewrite the system prompt", "add a fallback step" vs "swap the
+           model", "parse manually" vs "use a library"). Approach decisions
+           shape the entire spec and are expensive to unwind once the agent
+           builds on them, so the user must vet the strategy: tag UNKNOWN and
+           surface your recommended approach as the default.
+
+Output format — ONE LINE only, no preamble, no markdown:
+  ANSWER: <one-line answer>
+  UNKNOWN: <one-line default>
+
+Examples:
+  ANSWER: report a summary with counts and representative examples           ← reporting style is cheap to undo
+  ANSWER: treat all warnings and errors as genuine issues, do not ignore     ← policy is cheap to undo
+  ANSWER: run the read-only check variant (prettier --check, eslint, tsc)    ← read-only side, safer default; flip later if wanted
+  UNKNOWN: use npm                                                           ← package manager choice is costly to reverse mid-task
+  UNKNOWN: write output to ./report.md                                       ← creates a file; user may want a different path or no file
+  UNKNOWN: extract the value with a post-processing regex step               ← picks the implementation approach; user must vet the strategy
+
+Examples of FORBIDDEN outputs:
+  UNKNOWN:
+  UNKNOWN: it depends
+  (empty)
+  I think the user should decide.
+
+Refined task:
+${refined}
+
+Research:
+${research}
+
+Question: ${question}`;
+function composeRetryEmphasis(problem) {
+    if (problem === 'spec does not start with GOAL'
+        || problem === 'spec starts with a markdown fence'
+        || problem === 'spec is wrapped in a cat heredoc') {
+        return '\nPREVIOUS ATTEMPT VIOLATED THESE RULES. The very first characters of your output MUST be the letters G-O-A-L. Not a backtick, not `cat`, not a heredoc — the literal word GOAL.\n';
+    }
+    if (problem.startsWith('spec missing required section:')) {
+        const section = problem.replace('spec missing required section: ', '');
+        return `\nPREVIOUS ATTEMPT was missing the ${section} section. All four sections are required and must be non-empty: GOAL, CONSTRAINTS, ACCEPTANCE, VERIFY.\n`;
+    }
+    return `\nPREVIOUS ATTEMPT was invalid (${problem}). Ensure all four sections are present and the output starts with the literal word GOAL.\n`;
+}
+const COMPOSE_PROMPT = (refined, research, qa, retryProblem) => `You are composing the final implementation spec for an AI coding agent. Combine the refined task, the research, and the user's Q&A answers into one spec.
+
+CRITICAL FORMAT RULES (read first):
+- Output the spec as plain markdown text. Do NOT wrap your entire output in a code block, shell fence, or heredoc. Do NOT prefix with \`\`\`sh / \`\`\`bash. Do NOT use \`cat << EOF > file\` patterns. Your response begins literally with "GOAL" on the first line.
+- The ONLY fenced code block in your output is the one immediately following \`VERIFY:\` — and that fence must be \`\`\`sh, not \`\`\`bash, not anything else.
+- No preamble, no commentary, no trailing summary.
+${retryProblem ? composeRetryEmphasis(retryProblem) : ''}
+Output exactly four top-level sections in this order. Every section must be present and non-empty.
+
+GOAL
+  <one paragraph>
+
+CONSTRAINTS
+  - <bullet>
+  - …
+
+ACCEPTANCE
+  - <human-readable success criterion>
+  - …
+
+VERIFY:
+\`\`\`sh
+<runnable shell command 1>
+<runnable shell command 2>
+\`\`\`
+
+VERIFY must contain real, runnable commands the receiving agent can execute via \`bash -c\`. No placeholders. No "TODO". No "your test here".
+
+VERIFY must exercise the surface area the task actually touches. Draw VERIFY commands only from VERIFIED-TOOLING (the pre-validated subset of the research TOOLING section) — do not invent tools the repo does not have. Apply these rules:
+- HTML / CSS / client-side JS / UI changes → MUST include a browser-driving check. If the repo has playwright, use it (e.g. \`npx playwright test\`). If not, at minimum start the dev server and curl the affected route to confirm it serves 200 and the expected markup. A bare "open the page" instruction is not acceptable — it must be a shell command.
+- Dockerfile / docker-compose changes → MUST include a real build (\`docker build …\` or \`docker compose build\`) and, where feasible, a smoke run that proves the container starts (e.g. \`docker run --rm <img> <cmd>\` or \`docker compose up -d && docker compose ps\`).
+- TypeScript / JavaScript source changes → MUST include the project's typecheck, lint, and test commands when those scripts exist in TOOLING. Include build only if the change could affect the build output.
+- Python / Go / Rust / other source changes → MUST include the language's standard verification from TOOLING (e.g. \`pytest\`, \`go test ./...\`, \`cargo test\`) plus lint/typecheck if configured.
+- Config / infra-only changes with no executable verification → state that explicitly with a single command that re-reads or validates the config (e.g. \`docker compose config\`, \`nginx -t\`, \`yamllint file.yml\`). Never leave VERIFY with only \`true\` or \`echo ok\`.
+
+If TOOLING is empty for a category the change clearly touches, still include the best-effort standard command for that ecosystem (e.g. \`npx tsc --noEmit\` for a TS repo with no script) and note that the receiving agent may need to install it.
+
+Refined task:
+${refined}
+
+Research:
+${research}
+
+User Q&A:
+${qa}`;
+// Fast triage pass run before the (expensive) full rewrite. It produces either
+// the single token CLEAN — meaning the compose draft needs no rewrite — or a
+// short defect list. When CLEAN, the orchestrator returns the draft unchanged
+// and skips the rewrite entirely; otherwise the defects are fed into
+// CRITIQUE_PROMPT as a focus list so the rewrite targets real problems instead
+// of re-deriving them from scratch.
+const CRITIQUE_TRIAGE_PROMPT = (spec, refined, qa) => `You are triaging an implementation spec for an AI coding agent. Decide whether it needs a rewrite. Do NOT rewrite it — only judge it.
+
+The refined task and the user's Q&A below are GROUND TRUTH. Judge the spec against them. Look for SUBSTANTIVE defects only:
+- ambiguity that would let the agent build the wrong thing
+- acceptance criteria that are vague, unmeasurable, or missing
+- a VERIFY block that is missing, unrunnable, full of placeholders, or does not exercise the surface the task touches
+- scope drift: requirements, files, or deliverables not implied by the refined task or Q&A
+- a dropped or weakened CONSTRAINT from the refined task
+
+Do NOT flag cosmetic wording, style, or anything you would change only to "polish" prose. The bar is: would this defect change what the agent builds or whether the work can be verified?
+
+Output format — read carefully:
+- If the spec has NO substantive defects, output the single literal token CLEAN on its own line. Nothing else.
+- Otherwise output a short plain list, one defect per line, naming the section and the problem (e.g. "ACCEPTANCE: criterion 3 is unmeasurable — 'works well' has no check"). No rewrite, no preamble, no fixed spec.
+
+Refined task (ground truth):
+${refined}
+
+User Q&A (ground truth):
+${qa}
+
+Spec to triage:
+${spec}`;
+const CRITIQUE_PROMPT = (spec, refined, qa, addVerifyEmphasis, triageDefects = null) => `You are reviewing the implementation spec below for ambiguity, weak acceptance criteria, and missing or unrunnable VERIFY commands.
+
+CRITICAL FORMAT RULES (read first):
+- Output the rewritten spec as plain markdown. Do NOT wrap your entire output in a code block, shell fence, or heredoc. Do NOT prefix with \`\`\`sh / \`\`\`bash. Do NOT use \`cat << EOF > file\` patterns. Your response begins literally with "GOAL" on the first line.
+- The ONLY fenced code block in your output is the one immediately following \`VERIFY:\` — and that fence must be \`\`\`sh.
+- No separate critique section, no preamble, no trailing summary — just the rewritten spec.
+
+SCOPE RULES (equally critical — do not break these):
+- The refined task and the user's Q&A below are GROUND TRUTH. The rewritten spec must stay faithful to them.
+- Do NOT introduce new requirements, deliverables, files, scripts, hooks, configs, or acceptance criteria that are not explicitly implied by the refined task or the Q&A.
+- Do NOT broaden scope. If the refined task says "run X and report", do not turn it into "build a toolchain around X with hooks, docs, and reports".
+- CONSTRAINTS from the refined task MUST be preserved in spirit. Do not silently drop or weaken them.
+- If the spec below is malformed, empty, or wrapped in a heredoc, reconstruct it from the refined task and Q&A — not from your own invention.
+- Your job is to tighten language, sharpen acceptance criteria, and ensure VERIFY is runnable. Not to redesign the task.
+
+Rewrite the spec in the same four-section format (GOAL, CONSTRAINTS, ACCEPTANCE, VERIFY). Fix any issues you find within the scope rules above.
+
+VERIFY QUALITY CHECK (apply during the rewrite):
+- VERIFY must exercise the surface the task touches, using tools the repo actually has (see research notes).
+- Frontend / HTML / CSS / UI tasks → must include a browser-driving step (playwright if available; otherwise a dev-server + curl smoke test). Reject bare "open browser and check" instructions.
+- Dockerfile / compose tasks → must include a real \`docker build\` (or \`docker compose build\`) and, where feasible, a container smoke run.
+- Source-code tasks → must include the project's typecheck, lint, and tests when those exist. Do not drop them to "simplify".
+- If the existing VERIFY is missing or too thin for the change being described, expand it using commands consistent with the research notes. Do not invent tooling that isn't present.
+- Never accept \`true\`, \`echo ok\`, or other no-op commands as VERIFY content.
+
+${addVerifyEmphasis ? 'REQUIRED: The output MUST include a VERIFY: section followed by a ```sh fenced block of runnable shell commands. The previous attempt was missing this.' : ''}
+${triageDefects ?
+    `FOCUS — a triage pass already found these specific defects. Fix every one of them in your rewrite (without breaking the scope rules above):\n${triageDefects}\n`
+    : ''}
+Refined task (ground truth):
+${refined}
+
+User Q&A (ground truth):
+${qa}
+
+Spec to rewrite:
+${spec}`;
+const VERIFY_TOOLING_PROMPT = (tooling) => `You receive a TOOLING list of candidate verification commands for an AI coding task.
+
+YOU MAY ONLY READ. Do NOT execute any of the listed commands, not even with --help or --dry-run. Use ls/cat/grep/find/which/command -v (the BUILTIN command -v, NOT executing the candidate binary) to inspect static evidence:
+  - package.json scripts
+  - Makefile targets
+  - the presence of config files (tsconfig.json, playwright.config.*, .eslintrc*, etc.)
+  - binaries inside node_modules/.bin/
+  - system binaries in PATH (via command -v)
+
+Output exactly two sections:
+
+VERIFIED
+  <command>  <one-line evidence: where it was found>
+  ...
+
+REJECTED
+  <command>  <one-line reason it can't be confirmed>
+  ...
+
+Do not add other sections, preamble, or commentary.
+
+TOOLING (one command per line):
+${tooling}`;
+// ─── Exports ─────────────────────────────────────────────────────────────────
+export { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, RESEARCH_READ_ONLY_CONSTRAINT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, composeRetryEmphasis };

package/dist/task/service-blocks.d.ts

@@ -0,0 +1,3 @@
+import type { BraveResult } from '../workers/brave-search.js';
+export declare function formatServiceBlock(name: string, fullQuery: string, results: BraveResult[]): string;
+export declare function formatFreshnessSkippedBlock(names: string[]): string;

package/dist/task/service-blocks.js

@@ -0,0 +1,10 @@
+export function formatServiceBlock(name, fullQuery, results) {
+    const header = `### service: ${name}\nQuery: ${fullQuery}`;
+    if (results.length === 0)
+        return header;
+    const bullets = results.map(r => `- **${r.title}** — ${r.url}\n  ${r.description}`).join('\n');
+    return `${header}\n${bullets}`;
+}
+export function formatFreshnessSkippedBlock(names) {
+    return `### freshness-check skipped\nCould not verify external services (BRAVE_SEARCH_API_KEY not set):\n${names.map(n => `- ${n}`).join('\n')}`;
+}

package/dist/task/task-file.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Task file — barrel re-export for backward compatibility.
+ *
+ * All existing import sites continue to work unchanged.
+ *
+ * @deprecated Import from the specific modules:
+ *   - Types & constants: task-types.ts
+ *   - Parsing & formatting: task-parsers.ts
+ *   - File I/O: task-io.ts
+ */
+export type { TaskState, PhaseName, TaskFrontMatter } from './task-types.js';
+export { PHASE_ORDER, PHASE_INDEX, TASKS_DIR_NAME, RESUMABLE_STATES } from './task-types.js';
+export { emitFrontMatter, parseFrontMatter, sectionRegex, extractSection, normaliseTaskId } from './task-parsers.js';
+export { tasksDir, taskFilePath, ensureTasksDir, allocateTaskId, readTaskFile, writeTaskFile, updateTaskFrontMatter, readSection, setTaskSection } from './task-io.js';

package/dist/task/task-file.js

@@ -0,0 +1,15 @@
+/**
+ * Task file — barrel re-export for backward compatibility.
+ *
+ * All existing import sites continue to work unchanged.
+ *
+ * @deprecated Import from the specific modules:
+ *   - Types & constants: task-types.ts
+ *   - Parsing & formatting: task-parsers.ts
+ *   - File I/O: task-io.ts
+ */
+export { PHASE_ORDER, PHASE_INDEX, TASKS_DIR_NAME, RESUMABLE_STATES } from './task-types.js';
+// Parsing & formatting
+export { emitFrontMatter, parseFrontMatter, sectionRegex, extractSection, normaliseTaskId } from './task-parsers.js';
+// File I/O
+export { tasksDir, taskFilePath, ensureTasksDir, allocateTaskId, readTaskFile, writeTaskFile, updateTaskFrontMatter, readSection, setTaskSection } from './task-io.js';

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

@@ -0,0 +1,19 @@
+/**
+ * Task file I/O.
+ *
+ * File read/write operations for the .pi-tasks directory. Depends on
+ * task-types.ts (types, constants) and task-parsers.ts (parsing/formatting).
+ */
+import { type TaskFrontMatter } from './task-types.js';
+export declare function tasksDir(cwd: string): string;
+export declare function taskFilePath(cwd: string, id: string): string;
+export declare function ensureTasksDir(cwd: string): Promise<void>;
+export declare function allocateTaskId(cwd: string): Promise<string>;
+export declare function readTaskFile(cwd: string, id: string): Promise<{
+    frontMatter: TaskFrontMatter;
+    body: string;
+}>;
+export declare function writeTaskFile(cwd: string, fm: TaskFrontMatter, body: string): Promise<void>;
+export declare function updateTaskFrontMatter(cwd: string, id: string, patch: Partial<TaskFrontMatter>): Promise<void>;
+export declare function readSection(cwd: string, id: string, heading: string): Promise<string | null>;
+export declare function setTaskSection(cwd: string, id: string, heading: string, content: string): Promise<void>;

package/dist/task/task-io.js

@@ -0,0 +1,78 @@
+/**
+ * Task file I/O.
+ *
+ * File read/write operations for the .pi-tasks directory. Depends on
+ * task-types.ts (types, constants) and task-parsers.ts (parsing/formatting).
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { TASKS_DIR_NAME } from './task-types.js';
+import { emitFrontMatter, parseFrontMatter, sectionRegex } from './task-parsers.js';
+// ─── Directory & path helpers ────────────────────────────────────────────────
+export function tasksDir(cwd) {
+    return path.join(cwd, TASKS_DIR_NAME);
+}
+export function taskFilePath(cwd, id) {
+    return path.join(tasksDir(cwd), `${id}.md`);
+}
+export async function ensureTasksDir(cwd) {
+    await fsp.mkdir(tasksDir(cwd), { recursive: true });
+}
+export async function allocateTaskId(cwd) {
+    await ensureTasksDir(cwd);
+    const entries = await fsp.readdir(tasksDir(cwd));
+    let max = 0;
+    for (const e of entries) {
+        const m = /^TASK_(\d{4,})\.md$/.exec(e);
+        if (m) {
+            const n = parseInt(m[1], 10);
+            if (n > max)
+                max = n;
+        }
+    }
+    return `TASK_${String(max + 1).padStart(4, '0')}`;
+}
+// ─── File read/write ─────────────────────────────────────────────────────────
+export async function readTaskFile(cwd, id) {
+    const raw = await fsp.readFile(taskFilePath(cwd, id), 'utf8');
+    const fm = parseFrontMatter(raw);
+    if (!fm)
+        throw new Error(`malformed front matter in ${id}.md`);
+    const body = raw.replace(/^---\n[\s\S]*?\n---\n?/, '');
+    return { frontMatter: fm, body };
+}
+export async function writeTaskFile(cwd, fm, body) {
+    await ensureTasksDir(cwd);
+    const content = `${emitFrontMatter(fm)}\n${body}`;
+    await fsp.writeFile(taskFilePath(cwd, fm.id), content, 'utf8');
+}
+export async function updateTaskFrontMatter(cwd, id, patch) {
+    const { frontMatter, body } = await readTaskFile(cwd, id);
+    const next = {
+        ...frontMatter,
+        ...patch,
+        updated_at: new Date().toISOString()
+    };
+    await writeTaskFile(cwd, next, body);
+}
+// ─── Section read/write (append if absent, rewrite if present) ───────────────
+export async function readSection(cwd, id, heading) {
+    const { body } = await readTaskFile(cwd, id);
+    const m = sectionRegex(heading).exec(body);
+    return m ? m[2].trim() : null;
+}
+export async function setTaskSection(cwd, id, heading, content) {
+    const { frontMatter, body } = await readTaskFile(cwd, id);
+    const re = sectionRegex(heading);
+    let next;
+    if (re.test(body)) {
+        next = body.replace(re, `$1\n${content.trim()}\n\n`);
+    }
+    else {
+        const sep = body.endsWith('\n\n') ? ''
+            : body.endsWith('\n') ? '\n'
+                : '\n\n';
+        next = `${body}${sep}## ${heading}\n\n${content.trim()}\n`;
+    }
+    await writeTaskFile(cwd, { ...frontMatter, updated_at: new Date().toISOString() }, next);
+}

package/dist/task/task-parsers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Task file parsing and formatting.
+ *
+ * Pure functions for parsing YAML front matter, extracting sections, and
+ * normalising task IDs. No I/O.
+ */
+import { type TaskFrontMatter } from './task-types.js';
+export declare function emitFrontMatter(fm: TaskFrontMatter): string;
+export declare function parseFrontMatter(content: string): TaskFrontMatter | null;
+export declare function sectionRegex(heading: string): RegExp;
+export declare function extractSection(body: string, heading: string): string | null;
+export declare function normaliseTaskId(input: string): string;

package/dist/task/task-parsers.js

@@ -0,0 +1,75 @@
+/**
+ * Task file parsing and formatting.
+ *
+ * Pure functions for parsing YAML front matter, extracting sections, and
+ * normalising task IDs. No I/O.
+ */
+import { PHASE_INDEX } from './task-types.js';
+const FRONT_MATTER_KEYS = [
+    'id',
+    'state',
+    'phase',
+    'created_at',
+    'updated_at',
+    'title',
+    'reason'
+];
+// ─── Front matter ────────────────────────────────────────────────────────────
+export function emitFrontMatter(fm) {
+    const lines = ['---'];
+    for (const k of FRONT_MATTER_KEYS) {
+        const v = fm[k];
+        if (v === undefined || v === '') {
+            if (k === 'reason')
+                continue;
+        }
+        lines.push(`${k}: ${typeof v === 'string' ? v : String(v)}`);
+    }
+    lines.push('---');
+    return lines.join('\n');
+}
+export function parseFrontMatter(content) {
+    const m = /^---\n([\s\S]*?)\n---\n?/.exec(content);
+    if (!m)
+        return null;
+    const obj = {};
+    for (const line of m[1].split('\n')) {
+        const kv = /^([a-z_]+):\s*(.*)$/.exec(line);
+        if (kv)
+            obj[kv[1]] = kv[2];
+    }
+    if (!obj.id || !obj.state || !obj.phase || !obj.created_at)
+        return null;
+    if (PHASE_INDEX[obj.phase] === undefined) {
+        return null;
+    }
+    return {
+        id: obj.id,
+        state: obj.state,
+        phase: obj.phase,
+        created_at: obj.created_at,
+        updated_at: obj.updated_at ?? obj.created_at,
+        title: obj.title ?? '',
+        reason: obj.reason || undefined
+    };
+}
+// ─── Section helpers ─────────────────────────────────────────────────────────
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function sectionRegex(heading) {
+    return new RegExp(`(^## ${escapeRegex(heading)}\\s*\\n)([\\s\\S]*?)(?=^## |$(?![\\s\\S]))`, 'm');
+}
+export function extractSection(body, heading) {
+    const m = sectionRegex(heading).exec(body);
+    return m ? m[2].trim() : null;
+}
+// ─── Task ID helpers ─────────────────────────────────────────────────────────
+export function normaliseTaskId(input) {
+    const trimmed = input.trim();
+    if (/^TASK_\d{4,}$/.test(trimmed))
+        return trimmed;
+    if (/^\d+$/.test(trimmed))
+        return `TASK_${trimmed.padStart(4, '0')}`;
+    return trimmed;
+}

package/dist/task/task-types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Task file types and constants.
+ *
+ * Declares the core types used across the pi-task pipeline: task states,
+ * phase names, front matter, and ordering constants.
+ */
+export type TaskState = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+export type PhaseName = 'refine' | 'research' | 'grill' | 'compose' | 'critique' | 'done';
+export interface TaskFrontMatter {
+    id: string;
+    state: TaskState;
+    phase: PhaseName;
+    created_at: string;
+    updated_at: string;
+    title: string;
+    reason?: string;
+}
+export declare const PHASE_ORDER: PhaseName[];
+export declare const PHASE_INDEX: Record<PhaseName, number>;
+export declare const TASKS_DIR_NAME = ".pi-tasks";
+export declare const RESUMABLE_STATES: TaskState[];

package/dist/task/task-types.js

@@ -0,0 +1,18 @@
+/**
+ * Task file types and constants.
+ *
+ * Declares the core types used across the pi-task pipeline: task states,
+ * phase names, front matter, and ordering constants.
+ */
+// ─── Constants ───────────────────────────────────────────────────────────────
+export const PHASE_ORDER = ['refine', 'research', 'grill', 'compose', 'critique'];
+export const PHASE_INDEX = {
+    refine: 0,
+    research: 1,
+    grill: 2,
+    compose: 3,
+    critique: 4,
+    done: 5
+};
+export const TASKS_DIR_NAME = '.pi-tasks';
+export const RESUMABLE_STATES = ['in_progress', 'pending', 'cancelled', 'failed'];

package/dist/task/timings.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Phase timing data — captures how long each pipeline phase took so we can
+ * spot regressions and target future speed improvements.
+ *
+ * Top-level entries are the five phases (refine, research, grill, compose,
+ * critique). Each phase may attach optional sub-step children (e.g. research
+ * → workers + verify-tooling, grill → gen + auto-answers + user input).
+ *
+ * `formatTimings` produces the human-readable block we write to the
+ * `## phase timings` section of the TASK_NNNN.md file.
+ */
+export interface TimingEntry {
+    label: string;
+    ms: number;
+    children: TimingEntry[];
+}
+export declare function formatMs(ms: number): string;
+export declare function formatTimings(entries: ReadonlyArray<TimingEntry>): string;