@mjasnikovs/pi-task 0.38.29 → 0.38.30

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

@@ -46,13 +46,12 @@ export declare function formatPlanDecisions(entries: readonly PlanEntry[]): stri
 /**
  * The line that pins the DELIVERABLE, and it is not optional.
  *
- * The task prompt leads the handoff verbatim, and users reach /task-plan by
- * phrasing the request as planning — live (aiz-client TASK_PLAN_0001,
- * 2026-08-05): "Lets plan new tab and report @src/app/reports/". /task's refine
- * read the verb as the deliverable and produced a task titled "Plan the addition
- * of a new sub-tab…", whose ACCEPTANCE was "a planning document exists with
- * placeholder sections" and whose VERIFY asserted that no `.ts`/`.tsx` file had
- * changed. It passed. Nothing was built.
+ * The task prompt leads the handoff VERBATIM (see `buildHandoffPrompt`), and the
+ * way a user reaches /task-plan is by phrasing the request as planning — "let's
+ * plan X". Handed that verb, /task's refine can read PLANNING as the deliverable:
+ * the task becomes "plan X", its ACCEPTANCE becomes "a planning document exists",
+ * and its VERIFY asserts that no source file changed. Such a task passes its own
+ * gate with nothing built.
  *
  * Planning already happened — this prompt IS its output — so the handoff says so
  * rather than letting the request's own wording re-open it. It rides on every

package/dist/task/plan-io.js

@@ -76,13 +76,12 @@ export function formatPlanDecisions(entries) {
 /**
  * The line that pins the DELIVERABLE, and it is not optional.
  *
- * The task prompt leads the handoff verbatim, and users reach /task-plan by
- * phrasing the request as planning — live (aiz-client TASK_PLAN_0001,
- * 2026-08-05): "Lets plan new tab and report @src/app/reports/". /task's refine
- * read the verb as the deliverable and produced a task titled "Plan the addition
- * of a new sub-tab…", whose ACCEPTANCE was "a planning document exists with
- * placeholder sections" and whose VERIFY asserted that no `.ts`/`.tsx` file had
- * changed. It passed. Nothing was built.
+ * The task prompt leads the handoff VERBATIM (see `buildHandoffPrompt`), and the
+ * way a user reaches /task-plan is by phrasing the request as planning — "let's
+ * plan X". Handed that verb, /task's refine can read PLANNING as the deliverable:
+ * the task becomes "plan X", its ACCEPTANCE becomes "a planning document exists",
+ * and its VERIFY asserts that no source file changed. Such a task passes its own
+ * gate with nothing built.
  *
  * Planning already happened — this prompt IS its output — so the handoff says so
  * rather than letting the request's own wording re-open it. It rides on every

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

@@ -4,20 +4,22 @@
  * The command is a thin wiring layer. Everything it does is already in the
  * codebase and is reused as-is:
  *
- *   • the adaptive question loop, the duplicate backstop, the boxed picker and
- *     the A/B answer mapping        → plan-session.ts (which reuses parsers.ts,
- *                                     question-dedup.ts, inline-markdown.ts,
- *                                     question-box.ts, yolo.ts)
+ *   • the question loop, the duplicate backstop and the A/B answer mapping
+ *                              → plan-session.ts, via question-source.ts (which
+ *                                uses parsers.ts and question-dedup.ts),
+ *                                question-dialog.ts, inline-markdown.ts, yolo.ts
  *   • the child process, its loop/leak/stall guards and retries → child-runner.ts
- *   • local TUI + remote browser prompt fan-out                 → remote/bridge.ts
- *   • the status widget                                         → widget.ts
+ *   • local TUI + remote browser prompt fan-out, and the boxed
+ *     picker the TUI half renders                              → remote/bridge.ts
+ *   • the status widget                 → child-status.ts, which drives widget.ts
  *   • the plan file (.pi-tasks/TASK_PLAN_NNNN.md)               → task-io.ts
  *   • the handoff itself                                        → orchestrator.ts
  *
  * The handoff is deliberately the SAME call /task makes for a typed prompt —
  * gated when `verify work` / `enforce guidelines` is on, fire-and-forget
- * otherwise — so a planned task is not a second kind of task. The only thing
- * /task receives that a bare /task would not is the decisions block.
+ * otherwise — so a planned task is not a second kind of task. What /task
+ * receives beyond a bare /task is HANDOFF_DELIVERABLE_RULE, which rides on every
+ * handoff, and the decisions block when anything was settled.
  */
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { type PlanSessionDeps, type PlanOutcome } from './plan-session.js';

package/dist/task/plan-orchestrator.js

@@ -4,20 +4,22 @@
  * The command is a thin wiring layer. Everything it does is already in the
  * codebase and is reused as-is:
  *
- *   • the adaptive question loop, the duplicate backstop, the boxed picker and
- *     the A/B answer mapping        → plan-session.ts (which reuses parsers.ts,
- *                                     question-dedup.ts, inline-markdown.ts,
- *                                     question-box.ts, yolo.ts)
+ *   • the question loop, the duplicate backstop and the A/B answer mapping
+ *                              → plan-session.ts, via question-source.ts (which
+ *                                uses parsers.ts and question-dedup.ts),
+ *                                question-dialog.ts, inline-markdown.ts, yolo.ts
  *   • the child process, its loop/leak/stall guards and retries → child-runner.ts
- *   • local TUI + remote browser prompt fan-out                 → remote/bridge.ts
- *   • the status widget                                         → widget.ts
+ *   • local TUI + remote browser prompt fan-out, and the boxed
+ *     picker the TUI half renders                              → remote/bridge.ts
+ *   • the status widget                 → child-status.ts, which drives widget.ts
  *   • the plan file (.pi-tasks/TASK_PLAN_NNNN.md)               → task-io.ts
  *   • the handoff itself                                        → orchestrator.ts
  *
  * The handoff is deliberately the SAME call /task makes for a typed prompt —
  * gated when `verify work` / `enforce guidelines` is on, fire-and-forget
- * otherwise — so a planned task is not a second kind of task. The only thing
- * /task receives that a bare /task would not is the decisions block.
+ * otherwise — so a planned task is not a second kind of task. What /task
+ * receives beyond a bare /task is HANDOFF_DELIVERABLE_RULE, which rides on every
+ * handoff, and the decisions block when anything was settled.
  */
 import * as path from 'node:path';
 import { prependHint, USER_CANCELLED } from './child-runner.js';
@@ -93,8 +95,10 @@ export function buildPlanDeps(ctx, cwd, planId, task, signal) {
             });
         }
         finally {
-            // Outside a git repo `before` is null and there is nothing to compare
-            // against — the same degrade every other tree-reading guard here takes.
+            // `before` is null only when the snapshot itself failed, and there
+            // is then nothing to compare against. A non-repo cwd does NOT take
+            // that path: `git status` exits 128 and collectTreeChanges answers an
+            // empty summary, so the comparison runs and finds nothing.
             if (before) {
                 const after = await collectTreeChanges(cwd, signal).catch(() => null);
                 const touched = after ? newTreeChanges(before, after) : null;

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

@@ -9,11 +9,12 @@
  * {@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.
+ * What differs is the JOB. /task-auto's clarify asks for what most changes how a
+ * feature is SPLIT INTO TASKS — scope boundaries, which subsystems are in or out,
+ * ordering, the cross-cutting choices that fork the breakdown. /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 SCOPE RULES below rule it
+ * out explicitly.
  */
 /**
  * Ask the SINGLE most important remaining question about ONE task.

package/dist/task/plan-prompts.js

@@ -9,11 +9,12 @@
  * {@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.
+ * What differs is the JOB. /task-auto's clarify asks for what most changes how a
+ * feature is SPLIT INTO TASKS — scope boundaries, which subsystems are in or out,
+ * ordering, the cross-cutting choices that fork the breakdown. /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 SCOPE RULES below rule it
+ * out explicitly.
  */
 /**
  * Ask the SINGLE most important remaining question about ONE task.

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

@@ -11,9 +11,8 @@
  *
  *   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.
+ *   tools, so a write tool contributed by a whitelisted extension is excluded
+ *   too. 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
@@ -29,8 +28,8 @@ import type { TreeChangeSummary } from './write-guard.js';
  *
  * 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.
+ * and it should never happen by accident. The same value the grill-gen and
+ * auto-clarify children run under.
  */
 export declare const PLAN_TOOLS = "read";
 /**

package/dist/task/plan-readonly.js

@@ -11,9 +11,8 @@
  *
  *   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.
+ *   tools, so a write tool contributed by a whitelisted extension is excluded
+ *   too. 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
@@ -28,8 +27,8 @@
  *
  * 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.
+ * and it should never happen by accident. The same value the grill-gen and
+ * auto-clarify children run under.
  */
 export const PLAN_TOOLS = 'read';
 /**

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

@@ -1,31 +1,20 @@
 /**
- * What the PLAN-SHAPING loops record, and the decisions that record makes.
+ * What the PLAN-SHAPING loop records, and the decisions that record makes.
  *
- * `GateTally`'s and `AutofixLedger`'s twin, one phase earlier. CONTEXT.md records
- * that shape twice already: a long loop threading mutable locals by closure, with
- * pure helpers extracted for testability while the ORDERING and CARRY-FORWARD
- * decisions stayed in the caller. `coverPlan` was the third instance — five locals
- * (`planTitles`, `best`, `round`, `roundCap`, `bonusRoundUsed`) plus a
- * snapshot-before-overwrite pair (`priorCovered`, `priorMissing`) that existed
- * ONLY because the bonus-round decision was made downstream from the evidence it
- * needed, so the loop had to save a copy of `best` before replacing it.
+ * `GateTally`'s and `AutofixLedger`'s twin, one phase earlier: the ORDERING and
+ * CARRY-FORWARD decisions live in the record, not in the caller's locals.
  *
- * The last real bug here says the shape out loud, in the loop's own comment:
- * *"This used to be two assignments, and the second one kept the OLD plan's
- * accounting whenever the new plan's coverage-map child faulted
- * (`cand.accounting ?? accounting`) — binding requirements to titles they were
- * never mapped against."* `AutofixLedger`'s indictment, verbatim: the decision was
- * made downstream from the evidence.
+ * `consider` compares, replaces the plan WHOLE (`ScoredPlan` — titles and
+ * accounting together, because they are one value), and grants the bonus round IN
+ * THE SAME CALL that adopts — the way `AutofixLedger.judge(outcome, edited)`
+ * enters the demoted signature in the call that decides to demote. A caller
+ * cannot hold a pre-adoption snapshot that the replacement has already
+ * invalidated, because it never takes one.
  *
- * `consider` closes it by construction rather than by comment. It compares, it
- * replaces the plan WHOLE (titles and accounting together, because they are one
- * value), and it grants the bonus round IN THE SAME CALL that adopts — the way
- * `judge(outcome, edited)` enters the demoted signature in the call that demotes.
- * There is no window in which the snapshot and the replacement can disagree.
- *
- * NO I/O. No `logPlanDebug`, no notify, no child — for the same reason `GateTally`
- * performs none: a record that performs effects cannot be driven by a test that
- * only wants the verdict. The caller trails what the returned decision says.
+ * NO I/O. No `logPlanDebug`, no notify, no child — the same reason `GateTally`
+ * performs none (it imports two types and nothing else): a record that performs
+ * effects cannot be driven by a test that only wants the verdict. The caller
+ * trails what the returned decision says.
  */
 import { type AdoptionDecision, type ScoredPlan } from './coverage-loop.js';
 /** What `consider` did with a candidate, and why. */
@@ -42,17 +31,16 @@ export interface CoverageLedgerOptions {
     /**
      * Are there grounded requirements to judge against?
      *
-     * Without them `missing` is pure holistic-judge free text that can change every
-     * round, so there is no trustworthy "grew"/"new" signal — which is why the
-     * bonus round is requirements-path only.
+     * Without them `covered` is built by `groundedCoverage` over an EMPTY quote
+     * list, so it is empty every round and can never grow — the bonus round's own
+     * growth guard could not fire anyway. This flag says so up front instead of
+     * relying on that, and keeps the grant on the requirements path.
      */
     hasRequirements: boolean;
 }
 /**
  * The coverage loop's record: the best plan seen, the rounds spent, and the
  * one-shot bonus round.
- *
- * Methods are named for what they MEAN, not for the field they touch.
  */
 export declare class CoverageLedger {
     private _best;

package/dist/task/plan-rounds.js

@@ -1,38 +1,25 @@
 /**
- * What the PLAN-SHAPING loops record, and the decisions that record makes.
+ * What the PLAN-SHAPING loop records, and the decisions that record makes.
  *
- * `GateTally`'s and `AutofixLedger`'s twin, one phase earlier. CONTEXT.md records
- * that shape twice already: a long loop threading mutable locals by closure, with
- * pure helpers extracted for testability while the ORDERING and CARRY-FORWARD
- * decisions stayed in the caller. `coverPlan` was the third instance — five locals
- * (`planTitles`, `best`, `round`, `roundCap`, `bonusRoundUsed`) plus a
- * snapshot-before-overwrite pair (`priorCovered`, `priorMissing`) that existed
- * ONLY because the bonus-round decision was made downstream from the evidence it
- * needed, so the loop had to save a copy of `best` before replacing it.
+ * `GateTally`'s and `AutofixLedger`'s twin, one phase earlier: the ORDERING and
+ * CARRY-FORWARD decisions live in the record, not in the caller's locals.
  *
- * The last real bug here says the shape out loud, in the loop's own comment:
- * *"This used to be two assignments, and the second one kept the OLD plan's
- * accounting whenever the new plan's coverage-map child faulted
- * (`cand.accounting ?? accounting`) — binding requirements to titles they were
- * never mapped against."* `AutofixLedger`'s indictment, verbatim: the decision was
- * made downstream from the evidence.
+ * `consider` compares, replaces the plan WHOLE (`ScoredPlan` — titles and
+ * accounting together, because they are one value), and grants the bonus round IN
+ * THE SAME CALL that adopts — the way `AutofixLedger.judge(outcome, edited)`
+ * enters the demoted signature in the call that decides to demote. A caller
+ * cannot hold a pre-adoption snapshot that the replacement has already
+ * invalidated, because it never takes one.
  *
- * `consider` closes it by construction rather than by comment. It compares, it
- * replaces the plan WHOLE (titles and accounting together, because they are one
- * value), and it grants the bonus round IN THE SAME CALL that adopts — the way
- * `judge(outcome, edited)` enters the demoted signature in the call that demotes.
- * There is no window in which the snapshot and the replacement can disagree.
- *
- * NO I/O. No `logPlanDebug`, no notify, no child — for the same reason `GateTally`
- * performs none: a record that performs effects cannot be driven by a test that
- * only wants the verdict. The caller trails what the returned decision says.
+ * NO I/O. No `logPlanDebug`, no notify, no child — the same reason `GateTally`
+ * performs none (it imports two types and nothing else): a record that performs
+ * effects cannot be driven by a test that only wants the verdict. The caller
+ * trails what the returned decision says.
  */
 import { decideAdoption, normMissingArea } from './coverage-loop.js';
 /**
  * The coverage loop's record: the best plan seen, the rounds spent, and the
  * one-shot bonus round.
- *
- * Methods are named for what they MEAN, not for the field they touch.
  */
 export class CoverageLedger {
     _best;
@@ -82,8 +69,8 @@ export class CoverageLedger {
             return { adopted: false, decision, grantedBonusRound: false };
         const priorCovered = this._best.plan.covered.size;
         const priorMissing = new Set(this._best.plan.missing.map(normMissingArea));
-        // WHOLE, titles and accounting together. They are one value; splitting them
-        // is a bug this codebase has already had.
+        // WHOLE, titles and accounting together — one assignment, so the two can
+        // never come from different rounds.
         this._best = cand;
         const grant = !this._bonusUsed
             && this._round >= this._cap
@@ -97,9 +84,9 @@ export class CoverageLedger {
         return { adopted: true, decision, grantedBonusRound: grant };
     }
 }
-// DECOMPOSE's two retry budgets (`emptyAttempts`, `smallRetryUsed`) are NOT here.
-// They look like this shape and are not: that loop keys on `isSuspectPlan`, a
-// predicate over the SPEC LENGTH rather than a title-count floor, and its two
-// counters already sit inside a nine-line comment explaining why a single counter
-// was wrong. Wrapping them in a class that does not model `isSuspectPlan` would
-// move the code without concentrating the decision.
+// DECOMPOSE's two retry budgets (`emptyAttempts`, `smallRetryUsed` in
+// auto-orchestrator.ts) are NOT here. They look like this shape and are not: that
+// loop keys on `isSuspectPlan`, which combines a title-count ceiling with a
+// minimum SPEC LENGTH, and its two counters carry their own comment on why a
+// single counter was wrong. Wrapping them in a class that does not model
+// `isSuspectPlan` would move the code without concentrating the decision.

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

@@ -1,31 +1,29 @@
 /**
  * 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.
+ * Sequential and adaptive: ask ONE question at a time, feed the whole transcript
+ * back into the next generation call so later questions react to earlier answers,
+ * and stop when the model emits NONE. Generation, the question cap and the
+ * duplicate backstop live in question-source.ts; the answer cards and the A/B
+ * letter mapping in question-dialog.ts; markdown in inline-markdown.ts; the
+ * unattended policy in yolo.ts. /task's grill (phases.ts `phaseGrill`) and
+ * /task-auto's clarify (auto-orchestrator.ts `planAuto`) drive the same modules.
  *
- * 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:
+ * What this loop adds is the control surface. Grill and clarify let the user only
+ * answer the question in front of them. Here three moves are on every prompt, in
+ * this 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
+ *   ✎ answer in your own words    — the free-text card askQuestionBox appends to
+ *                                    every boxed picker. 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). Always the LAST card in the
  *                                    box — it ends the session, so it sits under
  *                                    every move that continues it, including the
  *                                    free-text card (see `manualPosition`).
  *
- * The loop is pure with respect to I/O: every side effect (child calls, dialogs,
+ * The loop performs no I/O of its own: every side effect (child calls, dialogs,
  * persistence) arrives through {@link PlanSessionDeps}, so the whole interaction
  * is unit-testable without a TUI or a model.
  */
@@ -37,8 +35,8 @@ export { resolveAnswer } from './question-dialog.js';
 export type { PendingQuestion } from './question-dialog.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.
+ * instead of answering. Same shape as `USER_CANCELLED` (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__";
@@ -52,99 +50,86 @@ export declare const PLAN_STATE_LABEL = "\u270E Add a decision of your own\u2026
 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.
+ * — it stops when the model emits NONE — so this only bounds a model that never
+ * does. Same value as /task-auto's MAX_CLARIFY_QUESTIONS.
  */
 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.
+ * either nothing the parser could read, or a question with no `SUGGESTED:` line.
+ * Same shape and same one-shot budget as GRILL_AUTO_FORMAT_HINT (prompts.ts).
+ *
+ * Both failures are silent without it. `makeQuestionSource` answers `exhausted`
+ * for a reply it cannot parse, which this loop renders as "no further questions";
+ * and a question with no SUGGESTED reaches `buildOptionCards` with nothing to
+ * build a card from.
  */
 export declare const PLAN_FORMAT_HINT: string;
 export { isNoneReply, pickQuestion } from './question-source.js';
 /**
  * Does the question offer the user a choice between two named alternatives?
- * Deliberately shallow — an "X or Y?" in the question's own clause.
+ * Deliberately shallow: an `or` anywhere before the first question mark.
  */
 export declare function looksLikeFork(question: string): boolean;
 /**
  * Does the recommended default DEFER the decision instead of making one?
  *
- * The prompt asks for a "concrete, decisive default", and nothing enforced it.
- * Live (aiz-client TASK_PLAN_0001, 2026-08-05): the model asked "what specific
- * report should this new tab display?" and recommended
- * "clarify with the user what the report is meant to show before proceeding".
- * The user pressed enter, so it was recorded `(accepted recommendation)` and rode
- * into /task's handoff as an AUTHORITATIVE decision — an order not to proceed,
- * addressed to a run where no user exists. /task duly built a task whose
- * ACCEPTANCE was "a planning document with placeholder sections" and whose VERIFY
- * asserted that no source file had changed.
- *
  * A deferral is not an answer, and the one place it can never be one is here: the
  * user IS present during planning, so "ask the user" is a null move — that IS the
- * question. Detection is anchored to the START of the default, which keeps it off
- * legitimate product behaviour ("prompt the user to confirm deletion" decides
- * something; "ask the user which report" decides nothing).
+ * question. An accepted recommendation is a `decision` entry, so it rides into
+ * /task's handoff inside the block `buildHandoffPrompt` (plan-io.ts) labels
+ * authoritative — addressed to a run where no user exists.
+ *
+ * Every pattern is anchored to the START of the default, which keeps it off
+ * legitimate product behaviour: "prompt the user to confirm deletion" decides
+ * something and does not match; "ask the user which report" decides nothing and
+ * does.
  */
 export declare function isDeferralSuggestion(suggested: string): boolean;
 /**
- * Corrective re-prompt for a default that deferred the decision. Same one-shot
- * budget and same quote-it-back shape as {@link planForkHint}, because the child
- * is stateless and cannot otherwise know what it just recommended.
+ * Corrective re-prompt for a default that deferred the decision. Quotes the
+ * question and the default back, because the child is a fresh process carrying
+ * only its prompt and cannot otherwise know what it just recommended.
  */
 export declare function planDecisiveHint(question: string, suggested: string): string;
 /**
  * Corrective re-prompt for a fork-shaped question that shipped only ONE option.
+ * With no ALT, `buildOptionCards` emits a single card, so the user has to type
+ * out the alternative the model itself just named.
  *
- * 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.
+ * The retry quotes the question back because the child is a fresh process
+ * carrying only its prompt, so it cannot otherwise know what it just wrote. It
+ * costs one extra child call on the questions where it fires.
  */
 export declare function planForkHint(question: string): string;
 /**
  * PLAN's quality rules, in order.
  *
- * Each is worth exactly one corrective re-prompt (the child is stateless, so each
- * hint quotes the question back), and each DEGRADES rather than discards when the
- * defect survives — a question with a weak default still beats no question.
+ * The corrective-re-prompt budget is per QUESTION and shared across the whole
+ * table (question-source.ts): at most one rule fires per draw, and a defect that
+ * survives its re-prompt DEGRADES through `repair` rather than discarding the
+ * question — a weak default still beats no question. Each hint quotes the
+ * question back, because the child is a fresh process carrying only its prompt.
  *
  * Only {@link CLARIFY_QUALITY_RULES} is shared with `/task-auto`, and only the
- * deferral rule is in it. The other two were MEASURED here (10/15 fork-shaped
- * questions shipped one option; the SUGGESTED requirement is in both prompts) but
- * each costs one extra child call every time it fires, and clarify is the most
- * A/B'd path in the codebase — moving them there is its own experiment, not a
- * side effect of sharing a state machine. Recorded rather than done.
+ * deferral rule is in it. The other two cost an extra child call every time they
+ * fire.
  */
 export declare const PLAN_QUALITY_RULES: ReadonlyArray<QuestionRule>;
 /**
  * The deferral rule alone — the one clarify shares.
  *
- * It exists because an accepted "clarify with the user before proceeding" rode
- * into `/task`'s handoff AS AN AUTHORITATIVE DECISION and produced a task whose
- * ACCEPTANCE was "a planning document with placeholder sections" and whose VERIFY
- * asserted that no source file had changed. Clarify's answers ride into the
- * decompose prompt and the AUTO file with exactly the same authority and had no
- * guard at all — the same bug, one command over, waiting.
+ * Clarify's answers ride into the decompose prompt and the AUTO file with the
+ * same authority /task-plan's decisions ride into the handoff, so an accepted
+ * "clarify with the user before proceeding" lands there as an instruction too.
  *
  * It is also the only one of the three that costs nothing on the happy path: a
  * decisive default never triggers it.
  */
 export declare const CLARIFY_QUALITY_RULES: ReadonlyArray<QuestionRule>;
-/** 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. */
+/** The ask spec the session hands to the UI: an {@link AskSpec} whose optional
+ *  picker fields are all required here. The same SessionUI.ask serves grill,
+ *  clarify and this loop. */
 export type PlanAskSpec = AskSpec & {
     options: {
         label: string;
@@ -158,7 +143,8 @@ export type PlanAskSpec = AskSpec & {
     }[];
 };
 export interface PlanSessionDeps {
-    /** Run the question-generation child. `hint` is the duplicate reprompt. */
+    /** Run the question-generation child. `hint` is whatever corrective
+     *  re-prompt question-source.ts chose, or null. */
     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>;
@@ -173,7 +159,7 @@ export interface PlanSessionDeps {
     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`). */
+    /** Status line while a child runs. */
     setStatus?(line: string | undefined): void;
     yolo?: boolean;
     logDebug?(msg: string): void;