@mjasnikovs/pi-task 0.30.0 → 0.32.0

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

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

package/dist/task/plan-prompts.js

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

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

@@ -0,0 +1,47 @@
+/**
+ * The read-only contract for /task-plan.
+ *
+ * Planning happens BEFORE the work is agreed, so a plan session must leave the
+ * project exactly as it found it: no file created, edited, or deleted. Nothing is
+ * built yet, so any artifact a plan produced would be an artifact nobody approved
+ * — and it would sit in the tree looking like part of the change the user is
+ * still deciding whether to make.
+ *
+ * Two layers, because one of them is somebody else's flag:
+ *
+ *   PREVENTION — the planning children run with {@link PLAN_TOOLS}, an allowlist
+ *   of exactly one tool. pi applies `--tools` to built-in, extension AND custom
+ *   tools, so a write tool contributed by a whitelisted extension is excluded too
+ *   (proven live — scripts/live-task-plan-readonly.ts). This is what actually
+ *   makes the session read-only.
+ *
+ *   VERIFICATION — after every child, the working tree is compared against the
+ *   snapshot taken before it. `.pi-tasks/` is excluded (that is where the plan
+ *   file itself lives — see collectTreeChanges), so what remains is precisely
+ *   "did planning touch the project". If it ever fires, prevention has a hole:
+ *   it is reported loudly and recorded in the plan file rather than silently
+ *   tolerated. It never deletes anything — an unexplained file is a thing to show
+ *   the user, not a thing to quietly destroy.
+ */
+import type { TreeChangeSummary } from './write-guard.js';
+/**
+ * The tool allowlist every /task-plan child runs under. One tool: `read`.
+ *
+ * Deliberately a named constant with a test pinning it (plan-readonly.test.ts):
+ * widening this string is the single edit that would end the read-only guarantee,
+ * and it should never happen by accident. The same value grill and clarify use
+ * for their generation children — planning has never needed more.
+ */
+export declare const PLAN_TOOLS = "read";
+/**
+ * What appeared in `after` that was not already in `before`.
+ *
+ * A set difference, not an emptiness check: /task-plan runs against whatever the
+ * user already has in progress, and a tree that was dirty when planning started
+ * is normal — only what planning ADDED is a violation.
+ */
+export declare function newTreeChanges(before: TreeChangeSummary, after: TreeChangeSummary): TreeChangeSummary;
+/** True when the summary names nothing at all. */
+export declare function isEmptyChange(c: TreeChangeSummary): boolean;
+/** One line naming what a planning step touched, for the notify and the record. */
+export declare function formatReadOnlyViolation(step: string, c: TreeChangeSummary): string;

package/dist/task/plan-readonly.js

@@ -0,0 +1,67 @@
+/**
+ * The read-only contract for /task-plan.
+ *
+ * Planning happens BEFORE the work is agreed, so a plan session must leave the
+ * project exactly as it found it: no file created, edited, or deleted. Nothing is
+ * built yet, so any artifact a plan produced would be an artifact nobody approved
+ * — and it would sit in the tree looking like part of the change the user is
+ * still deciding whether to make.
+ *
+ * Two layers, because one of them is somebody else's flag:
+ *
+ *   PREVENTION — the planning children run with {@link PLAN_TOOLS}, an allowlist
+ *   of exactly one tool. pi applies `--tools` to built-in, extension AND custom
+ *   tools, so a write tool contributed by a whitelisted extension is excluded too
+ *   (proven live — scripts/live-task-plan-readonly.ts). This is what actually
+ *   makes the session read-only.
+ *
+ *   VERIFICATION — after every child, the working tree is compared against the
+ *   snapshot taken before it. `.pi-tasks/` is excluded (that is where the plan
+ *   file itself lives — see collectTreeChanges), so what remains is precisely
+ *   "did planning touch the project". If it ever fires, prevention has a hole:
+ *   it is reported loudly and recorded in the plan file rather than silently
+ *   tolerated. It never deletes anything — an unexplained file is a thing to show
+ *   the user, not a thing to quietly destroy.
+ */
+/**
+ * The tool allowlist every /task-plan child runs under. One tool: `read`.
+ *
+ * Deliberately a named constant with a test pinning it (plan-readonly.test.ts):
+ * widening this string is the single edit that would end the read-only guarantee,
+ * and it should never happen by accident. The same value grill and clarify use
+ * for their generation children — planning has never needed more.
+ */
+export const PLAN_TOOLS = 'read';
+/**
+ * What appeared in `after` that was not already in `before`.
+ *
+ * A set difference, not an emptiness check: /task-plan runs against whatever the
+ * user already has in progress, and a tree that was dirty when planning started
+ * is normal — only what planning ADDED is a violation.
+ */
+export function newTreeChanges(before, after) {
+    const diff = (a, b) => {
+        const seen = new Set(b);
+        return a.filter(p => !seen.has(p));
+    };
+    return {
+        modified: diff(after.modified, before.modified),
+        added: diff(after.added, before.added),
+        deleted: diff(after.deleted, before.deleted)
+    };
+}
+/** True when the summary names nothing at all. */
+export function isEmptyChange(c) {
+    return c.modified.length + c.added.length + c.deleted.length === 0;
+}
+/** One line naming what a planning step touched, for the notify and the record. */
+export function formatReadOnlyViolation(step, c) {
+    const parts = [];
+    if (c.added.length > 0)
+        parts.push(`created ${c.added.join(', ')}`);
+    if (c.modified.length > 0)
+        parts.push(`modified ${c.modified.join(', ')}`);
+    if (c.deleted.length > 0)
+        parts.push(`deleted ${c.deleted.join(', ')}`);
+    return `/task-plan is read-only, but the ${step} step ${parts.join('; ')}`;
+}

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

@@ -0,0 +1,184 @@
+/**
+ * The /task-plan interaction loop.
+ *
+ * Sequential & adaptive, exactly like /task's grill (phases.ts `phaseGrill`) and
+ * /task-auto's clarify (auto-orchestrator.ts `planAuto`): ask ONE question at a
+ * time, feed every answer back into the next generation call so later questions
+ * react to earlier ones, and stop when the model emits NONE. The duplicate
+ * backstop (`isDuplicateQuestion` + `DUP_REPROMPT_HINT` + `MAX_DUP_STRIKES`), the
+ * markdown handling, the A/B answer-letter mapping and the YOLO policy are the
+ * SAME modules those two loops use — none of that is new here.
+ *
+ * What IS new is the control surface. In grill and clarify the user's only move is
+ * to answer the question in front of them. Here three moves are available at every
+ * single prompt, in that order of appearance:
+ *
+ *   ❓ ask the model a question   — the user asks, the model answers (PLAN_ASK)
+ *   ✎ answer in your own words    — the free-text card askQuestionBox already
+ *                                    appends to every boxed picker; it is not new,
+ *                                    it is simply always present here, and it
+ *                                    doubles as "state a decision" when the model
+ *                                    has nothing to ask
+ *   ▶ proceed to execution        — stop planning, hand the decisions to /task
+ *                                    (PLAN_PROCEED)
+ *
+ * The loop is pure with respect to I/O: every side effect (child calls, dialogs,
+ * persistence) arrives through {@link PlanSessionDeps}, so the whole interaction
+ * is unit-testable without a TUI or a model.
+ */
+import type { AskSpec } from '../remote/bridge.js';
+import { type PlanEntry, type AnswerSource } from './plan-io.js';
+/**
+ * Sentinel values the picker resolves to when the user takes a control action
+ * instead of answering. Deliberately shaped like the existing `USER_CANCELLED`
+ * sentinel (child-runner.ts): a value no model answer and no human ever types.
+ */
+export declare const PLAN_ASK = "__plan_ask__";
+export declare const PLAN_PROCEED = "__plan_proceed__";
+export declare const PLAN_ASK_LABEL = "\u2753 Ask the model a question\u2026";
+export declare const PLAN_PROCEED_LABEL = "\u25B6 Proceed to execution (hand off to /task)";
+/** Free-text card label while a model question is on screen. */
+export declare const PLAN_ANSWER_LABEL = "\u270E Answer in your own words\u2026";
+/** …and when there is no question to answer, so the same card reads correctly. */
+export declare const PLAN_STATE_LABEL = "\u270E Add a decision of your own\u2026";
+/** Header shown once the model has nothing left to ask. */
+export declare const PLAN_NO_QUESTIONS = "No further questions \u2014 the decisions so far settle how this task is built.";
+/**
+ * Hard ceiling on model-generated questions for one plan. The loop is open-ended
+ * (it stops when the model emits NONE); this only bounds a model that never
+ * does. Matches /task-auto's MAX_CLARIFY_QUESTIONS, for the same reason.
+ */
+export declare const MAX_PLAN_QUESTIONS = 8;
+/**
+ * Corrective re-prompt for a question reply that did not follow the format —
+ * either nothing parseable at all, or a question with no `SUGGESTED:` line. Same
+ * shape and same one-shot budget as GRILL_AUTO_FORMAT_HINT (prompts.ts), which
+ * exists because the local model drops a required tag every so often and a
+ * silent fallback is worse than one extra call: an unparsed reply reads as "no
+ * questions left" and a missing SUGGESTED leaves the picker with nothing to
+ * recommend.
+ */
+export declare const PLAN_FORMAT_HINT: string;
+/** True when the reply is the deliberate "nothing left to ask" sentinel, as
+ *  opposed to output the parser simply could not read. */
+export declare function isNoneReply(raw: string): boolean;
+/**
+ * Which of the parsed entries is the actual question.
+ *
+ * parseClarifyList turns EVERY numbered line into an entry, and the local model
+ * sometimes writes a numbered analysis note or two before the question it was
+ * asked for (measured live: the first numbered line was a note like
+ * "1. gateDebugWriter in orchestrator.ts — wraps a raw append function"). Taking
+ * entry 0 blindly then shows the note as the question and loses the SUGGESTED
+ * line that was attached further down.
+ *
+ * The SUGGESTED line is the reliable marker of the real question — the prompt
+ * requires exactly one, and parseClarifyList attaches it to the entry it follows.
+ * So: prefer the first entry that has one; fall back to the first entry when none
+ * does, which is the case the format re-prompt then covers.
+ */
+export declare function pickQuestion<T extends {
+    suggested?: string;
+}>(parsed: T[]): T | undefined;
+/**
+ * Does the question offer the user a choice between two named alternatives?
+ * Deliberately shallow — an "X or Y?" in the question's own clause.
+ */
+export declare function looksLikeFork(question: string): boolean;
+/**
+ * Corrective re-prompt for a fork-shaped question that shipped only ONE option.
+ *
+ * Measured on the local model (scripts/live-task-plan-step0.ts, 15 reps): the
+ * SUGGESTED line is always there, but 10/15 questions named two alternatives and
+ * gave only one of them — so the picker showed a single card and the user had to
+ * type out the option the model itself had just proposed.
+ *
+ * The retry quotes the question back because the child is stateless (a fresh
+ * process per call, prompt only), so it cannot otherwise know what it just wrote.
+ * Validated before wiring (scripts/live-task-plan-fork-alt.ts): 6/6 fires
+ * recovered an ALT, and 6/6 re-asked the SAME question rather than changing the
+ * subject. It costs one extra child call on the questions where it fires.
+ */
+export declare function planForkHint(question: string): string;
+/** The ask spec the session hands to the UI: an {@link AskSpec} plus the picker
+ *  entries. Kept structurally identical to what phaseGrill/planAuto build so the
+ *  same SessionUI.ask serves all three. */
+export type PlanAskSpec = AskSpec & {
+    options: {
+        label: string;
+        value: string;
+    }[];
+    manualLabel: string;
+    actions: {
+        label: string;
+        value: string;
+    }[];
+};
+export interface PlanSessionDeps {
+    /** Run the question-generation child. `hint` is the duplicate reprompt. */
+    generateQuestion(priorQA: string, hint: string | null): Promise<string>;
+    /** Run the child that answers a question the USER asked. */
+    answerUserQuestion(priorQA: string, question: string): Promise<string>;
+    /** Show the picker; resolves to a value, a control sentinel, or undefined
+     *  when the user dismissed it. */
+    ask(spec: PlanAskSpec): Promise<string | undefined>;
+    /** Collect free text (the user's own question). undefined = cancelled. */
+    promptText(title: string, question: string): Promise<string | undefined>;
+    /** Display the model's answer to the user's question. */
+    showAnswer(question: string, answer: string): void | Promise<void>;
+    /** Called after every transcript change, for persistence. */
+    onEntries?(entries: readonly PlanEntry[]): void | Promise<void>;
+    /** Theme-aware markdown renderer for displayed text; identity when absent. */
+    renderMarkdown?(text: string): string;
+    /** Status line while a child runs (the widget's `lastLine`). */
+    setStatus?(line: string | undefined): void;
+    yolo?: boolean;
+    logDebug?(msg: string): void;
+}
+export type PlanOutcome = {
+    kind: 'proceed';
+    entries: PlanEntry[];
+} | {
+    kind: 'cancelled';
+    entries: PlanEntry[];
+};
+interface PendingQuestion {
+    /** Plain text — persisted, and fed back to the model. */
+    plain: string;
+    /** Markdown-rendered — displayed. */
+    shown: string;
+    suggested?: string;
+    shownSuggested?: string;
+    alt?: string;
+    shownAlt?: string;
+}
+/**
+ * Build the picker for a pending model question: the recommendation first (index
+ * 0 is the green RECOMMENDED card), the alternative second when the question is a
+ * binary fork, then the two control actions. The free-text card is appended by
+ * askQuestionBox itself — that is the "answer in your own words" affordance, and
+ * it is the same card grill and clarify already show.
+ */
+export declare function buildQuestionSpec(p: PendingQuestion): PlanAskSpec;
+/**
+ * Build the picker for the state with NO pending question — the model is out of
+ * questions, or the cap/duplicate backstop stopped it. The same three moves are
+ * still on offer; only "answer this question" is gone, because there is no
+ * question, so the free-text card becomes "add a decision of your own".
+ */
+export declare function buildIdleSpec(): PlanAskSpec;
+/**
+ * Map what the picker returned onto the answer that gets recorded. Mirrors the
+ * identical mapping in phaseGrill and planAuto: an empty submit accepts the
+ * recommendation, a bare "A"/"B" from a remote user or the free-text fallback maps
+ * back to the option's full text, and anything else is taken verbatim.
+ */
+export declare function resolveAnswer(p: PendingQuestion, raw: string): {
+    answer: string;
+    source: AnswerSource;
+};
+/** Copy for the dialog that collects the user's own question. */
+export declare const ASK_TITLE = "Ask the model";
+export declare const ASK_QUESTION = "What do you want to ask about this task? The answer is recorded as a note; it does not decide anything by itself.";
+export declare function runPlanSession(deps: PlanSessionDeps): Promise<PlanOutcome>;
+export {};