@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/qa-transcript.js

@@ -3,25 +3,18 @@
  * (`/task-auto`) — and the one place its numbering, its formatting and its
  * provenance policy live.
  *
- * `question-dialog.ts` unified the ANSWER side of these loops: the picker cards
- * and the reply mapping. It did not unify what the loop RECORDS, and that was
- * eight retyped push sites across two files, each choosing a suffix by hand
- * according to which branch of an `if/else` it stood in.
+ * `question-dialog.ts` owns the ANSWER side of these loops — the picker cards and
+ * the reply mapping. This owns what the loop RECORDS.
  *
- * The cost is written into the code. `phases.ts` states the invariant in a
- * comment — *"No provenance stamp here, unlike clarify's transcript: this string
- * is fed back VERBATIM into the next grill-gen prompt, so a `(accepted
- * recommendation)` suffix would become model input"* — and TWELVE LINES ABOVE it,
- * the YOLO branch pushes `${answer} ${YOLO_STAMP}` into that very array. The rule
- * was violated inside the loop body that declares it, because the rule lived in
- * prose and the decision lived at each push.
- *
- * Here it is a property of a value: an entry states its KIND, and the policy says
- * where that kind's provenance is allowed to appear.
+ * Provenance is a property of a value here, not a decision taken at each push
+ * site: an entry states its KIND, and the policy says where that kind's
+ * provenance is allowed to appear. The two renderings below differ ONLY in those
+ * suffixes, which is how a hand-stamped transcript drifts apart unnoticed.
  *
  * NOT unified here: `plan-session.ts`'s `PlanEntry` transcript. It is a different
- * shape — decisions vs advisory notes, persisted to its own task file, with no
- * `Qn:`/`An:` numbering — and folding it in would be a rename, not a deepening.
+ * shape — model decisions, advisory notes and user-stated decisions in one list,
+ * persisted to its own task file — and folding it in would be a rename, not a
+ * deepening.
  */
 import { YOLO_STAMP } from './yolo.js';
 /**
@@ -42,10 +35,11 @@ export const QA_PROVENANCE = {
  * GRILL: stamps `auto` and both YOLO kinds in the record, and shows the generator
  * nothing.
  *
- * `accepted` is deliberately NOT in the record set. Grill's record reaches
- * `COMPOSE_PROMPT` and `CRITIQUE_PROMPT`, where it is named GROUND TRUTH; clarify's
- * reaches a decompose prompt. Whether those two should agree is a prompt question
- * with its own A/B, so today's answer is preserved rather than harmonised here.
+ * `accepted` is deliberately NOT in the record set, and clarify's policy below
+ * disagrees. Grill's record is handed to `COMPOSE_PROMPT` and `CRITIQUE_PROMPT`
+ * (the latter names the Q&A GROUND TRUTH); clarify's is handed to
+ * `AUTO_DECOMPOSE_PROMPT`. Whether the two should agree is a question about those
+ * prompts, so each keeps its own answer here.
  */
 export const GRILL_QA_POLICY = {
     record: new Set(['auto', 'yolo', 'yolo-skip']),
@@ -75,7 +69,7 @@ export class QaTranscript {
     get entries() {
         return this._entries;
     }
-    /** Record one answered question. The number is assigned here, not by the caller. */
+    /** Record one answered question. Position IS the number; no caller supplies one. */
     add(kind, question, answer) {
         this._entries.push({ kind, question, answer });
     }

package/dist/task/question-box.d.ts

@@ -1,14 +1,15 @@
 /**
  * Boxed question dialog for the clarify / grill phases.
  *
- * The built-in `ctx.ui.select` renders every option as a bare line under one
- * outer frame — the question, the recommendation, and the choices all read as a
- * single blob. The remote (browser) prompt card instead gives each response its
- * own bounded panel, tints the recommended one green, and separates everything
- * with margins. This module mirrors that remote style in the terminal: a custom
- * `ctx.ui.custom` component that draws each answer in its own bounding box with a
- * green RECOMMENDED tag, an accent-highlighted cursor box, and clear vertical
- * spacing.
+ * The built-in `ctx.ui.select` takes `options: string[]` and builds one
+ * `SelectList` inside a single `frame` (pi-coding-agent's llama/ui.js), so the
+ * question, the recommendation and the choices read as one blob and no option can
+ * be styled apart from the rest. The remote prompt card instead puts the
+ * recommendation in its own panel with a green left border and a green label
+ * (`.rec-panel` / `.rec-label` in remote/ui-styles.ts). This module mirrors that in
+ * the terminal: a `ctx.ui.custom` component that draws each answer in its own
+ * bounding box with a green RECOMMENDED tag, an accent cursor bar, and vertical
+ * spacing between cards.
  *
  * `renderQuestionBox` is the pure layout — width in, lines out — so the visual
  * structure (borders, tag, cursor arrow, padding) is unit-testable without a
@@ -41,12 +42,14 @@ export declare const HINT_TEXT = "\u2191\u2193 navigate \u00B7 enter select \u00
 export declare const MANUAL_CARD_LABEL = "\u270E Type a different answer\u2026";
 /**
  * Lay the whole dialog out for `width` columns: a QUESTION label + wrapped
- * question, one bounding box per card (recommended tinted green, the cursor box
- * highlighted with an accent border and "▸" arrow), and a key-hint footer.
+ * question, one bounding box per card (the recommended one tinted green, the
+ * selected one given an accent border and a "▌" bar in the gutter), and a
+ * key-hint footer.
  */
 export declare function renderQuestionBox(width: number, question: string, cards: BoxCard[], selected: number, c: BoxColors, hintText?: string): string[];
 export declare function boxColors(theme: ThemeLike): BoxColors;
-/** Focusable picker component; navigation mirrors the built-in select dialog. */
+/** Focusable picker component. Navigation is pi-tui's own `tui.select.up`,
+ *  `.down`, `.confirm` and `.cancel` bindings, plus `j`/`k`. */
 export declare class QuestionBoxComponent implements Component {
     private readonly question;
     private readonly cards;
@@ -54,8 +57,9 @@ export declare class QuestionBoxComponent implements Component {
     private readonly onChoose;
     private readonly onCancel;
     private selected;
-    /** Card labels in display order (recommended first, manual last). Read-only
-     *  view for tests that drive the picker without parsing rendered output. */
+    /** Card labels in display order, free-text card included at whatever index
+     *  `manualPosition` put it. Read-only view for tests that drive the picker
+     *  without parsing rendered output. */
     get cardLabels(): string[];
     /** The question header text. Read-only view for tests. */
     get headerText(): string;

package/dist/task/question-box.js

@@ -1,14 +1,15 @@
 /**
  * Boxed question dialog for the clarify / grill phases.
  *
- * The built-in `ctx.ui.select` renders every option as a bare line under one
- * outer frame — the question, the recommendation, and the choices all read as a
- * single blob. The remote (browser) prompt card instead gives each response its
- * own bounded panel, tints the recommended one green, and separates everything
- * with margins. This module mirrors that remote style in the terminal: a custom
- * `ctx.ui.custom` component that draws each answer in its own bounding box with a
- * green RECOMMENDED tag, an accent-highlighted cursor box, and clear vertical
- * spacing.
+ * The built-in `ctx.ui.select` takes `options: string[]` and builds one
+ * `SelectList` inside a single `frame` (pi-coding-agent's llama/ui.js), so the
+ * question, the recommendation and the choices read as one blob and no option can
+ * be styled apart from the rest. The remote prompt card instead puts the
+ * recommendation in its own panel with a green left border and a green label
+ * (`.rec-panel` / `.rec-label` in remote/ui-styles.ts). This module mirrors that in
+ * the terminal: a `ctx.ui.custom` component that draws each answer in its own
+ * bounding box with a green RECOMMENDED tag, an accent cursor bar, and vertical
+ * spacing between cards.
  *
  * `renderQuestionBox` is the pure layout — width in, lines out — so the visual
  * structure (borders, tag, cursor arrow, padding) is unit-testable without a
@@ -53,15 +54,16 @@ function renderCard(card, selected, boxWidth, c) {
     const bodyLines = wrapTextWithAnsi(card.label, innerWidth);
     const body = (bodyLines.length > 0 ? bodyLines : ['']).map(line => borderFn('│ ') + padTo(line, innerWidth) + borderFn(' │'));
     const bottom = borderFn(`└${dash(boxWidth - 2)}┘`);
-    // A full-height accent bar in the gutter marks the selected card — far more
-    // visible than a single "▸" glyph on the top border alone.
+    // A full-height accent bar in the gutter marks the selected card; it occupies
+    // the two GUTTER columns every card reserves, so nothing shifts.
     const cursor = selected ? c.arrow('▌') + ' ' : '  ';
     return [cursor + top, ...body.map(b => cursor + b), cursor + bottom];
 }
 /**
  * Lay the whole dialog out for `width` columns: a QUESTION label + wrapped
- * question, one bounding box per card (recommended tinted green, the cursor box
- * highlighted with an accent border and "▸" arrow), and a key-hint footer.
+ * question, one bounding box per card (the recommended one tinted green, the
+ * selected one given an accent border and a "▌" bar in the gutter), and a
+ * key-hint footer.
  */
 export function renderQuestionBox(width, question, cards, selected, c, hintText = HINT_TEXT) {
     const W = Math.min(Math.max(width, 12), MAX_CONTENT_WIDTH);
@@ -93,7 +95,8 @@ export function boxColors(theme) {
     };
 }
 // ─── Component ─────────────────────────────────────────────────────────────────
-/** Focusable picker component; navigation mirrors the built-in select dialog. */
+/** Focusable picker component. Navigation is pi-tui's own `tui.select.up`,
+ *  `.down`, `.confirm` and `.cancel` bindings, plus `j`/`k`. */
 export class QuestionBoxComponent {
     question;
     cards;
@@ -101,8 +104,9 @@ export class QuestionBoxComponent {
     onChoose;
     onCancel;
     selected = 0;
-    /** Card labels in display order (recommended first, manual last). Read-only
-     *  view for tests that drive the picker without parsing rendered output. */
+    /** Card labels in display order, free-text card included at whatever index
+     *  `manualPosition` put it. Read-only view for tests that drive the picker
+     *  without parsing rendered output. */
     get cardLabels() {
         return this.cards.map(c => c.label);
     }

package/dist/task/question-dedup.d.ts

@@ -1,14 +1,13 @@
 /**
  * Detects when a freshly-generated clarifying question is a near-duplicate of one
  * already asked. The clarify/grill loops re-call the generator after every answer
- * and rely on a prompt instruction ("Never re-ask something already answered") to
- * stop repeats. A weaker local model ignores that and re-asks the same fork worded
- * differently (observed: a "Bun bundler vs Vite" question asked four ways across a
- * single run). This is a deterministic backstop so a model that won't self-police
- * can't barrage the user with the same decision.
+ * and rely on a prompt instruction — "Never re-ask something already answered",
+ * carried by both prompts.ts and auto-prompts.ts — to stop repeats. A model that
+ * ignores it re-asks the same fork worded differently, so this is a deterministic
+ * backstop against barraging the user with one decision.
  *
- * Pure logic, no I/O — trivially unit-testable, and validated against the actual
- * repeated questions from a real /task-auto run (see question-dedup.test.ts).
+ * Pure logic, no I/O: the module imports nothing. question-dedup.test.ts drives it
+ * against a recorded set of ten questions in which three restate one earlier fork.
  */
 /**
  * Lowercase, drop markdown emphasis/backticks, split on non-alphanumeric, then

package/dist/task/question-dedup.js

@@ -1,14 +1,13 @@
 /**
  * Detects when a freshly-generated clarifying question is a near-duplicate of one
  * already asked. The clarify/grill loops re-call the generator after every answer
- * and rely on a prompt instruction ("Never re-ask something already answered") to
- * stop repeats. A weaker local model ignores that and re-asks the same fork worded
- * differently (observed: a "Bun bundler vs Vite" question asked four ways across a
- * single run). This is a deterministic backstop so a model that won't self-police
- * can't barrage the user with the same decision.
+ * and rely on a prompt instruction — "Never re-ask something already answered",
+ * carried by both prompts.ts and auto-prompts.ts — to stop repeats. A model that
+ * ignores it re-asks the same fork worded differently, so this is a deterministic
+ * backstop against barraging the user with one decision.
  *
- * Pure logic, no I/O — trivially unit-testable, and validated against the actual
- * repeated questions from a real /task-auto run (see question-dedup.test.ts).
+ * Pure logic, no I/O: the module imports nothing. question-dedup.test.ts drives it
+ * against a recorded set of ten questions in which three restate one earlier fork.
  */
 // Function words plus the boilerplate the prompt makes every question share
 // ("should we use", "or should", "this determines whether the task", …). Stripping
@@ -142,11 +141,11 @@ export function jaccard(a, b) {
     const union = a.size + b.size - inter;
     return union === 0 ? 0 : inter / union;
 }
-// Validated against the real mx5 run (question-dedup.test.ts): the re-asked
-// SPA-build/serve forks scored 0.152 / 0.275 / 0.421 against an earlier question,
-// while every genuinely-distinct subsystem question topped out at 0.077. 0.12 sits
-// in that gap — above the distinct ceiling, below the lowest true duplicate — so
-// it catches the repeats without suppressing a real question.
+// The similarity at which a question counts as a re-ask. It is low because the
+// stopword list has already stripped the scaffolding every generated question
+// shares, leaving only the salient nouns: two questions about the same fork overlap
+// on those, two different subsystems share almost none. question-dedup.test.ts pins
+// both sides — the re-asks must be caught, the distinct questions must not be.
 export const DEFAULT_DUP_THRESHOLD = 0.12;
 /**
  * True when `next` is a near-duplicate of any question in `prior` (Jaccard of
@@ -161,8 +160,8 @@ export function isDuplicateQuestion(prior, next, threshold = DEFAULT_DUP_THRESHO
 }
 // After this many consecutive near-duplicate questions, the question loop stops:
 // a model that can't produce a novel question after being told to move on has
-// nothing genuinely new left to ask. Shared by /task-auto's clarify loop and
-// /task's grill loop.
+// nothing genuinely new left to ask. Read by grill (phases.ts) and by the shared
+// question source (question-source.ts) that clarify and /task-plan both drive.
 export const MAX_DUP_STRIKES = 2;
 // Reprompt injected when a duplicate is caught — tells the model the topic is
 // settled and to either move to a different open fork or finish.

package/dist/task/question-dialog.d.ts

@@ -7,26 +7,17 @@
  * display; decide whether the question is a binary fork; short-circuit under
  * YOLO; build `A: …` / `B: …` cards; call `ui.ask`; treat `undefined` as a
  * cancel; and map the reply back onto an answer — where an empty submit accepts
- * the recommendation, a bare "A"/"B" from a remote user (or the picker's
- * free-text fallback) maps back to the option's full text, and anything else is
- * taken verbatim.
+ * the recommendation, a bare "A"/"B" ON A FORK (from a remote user, or from the
+ * picker's free-text fallback) maps back to that option's full text, and anything
+ * else is taken verbatim.
  *
- * The mapping is the load-bearing part. Storing the literal letter "A" leaves the
- * next generation call a dangling reference it cannot decode, so getting it wrong
- * is not cosmetic.
+ * The mapping is the load-bearing part. The recorded answer is fed back into the
+ * next generation call, so storing the literal letter "A" would hand that call a
+ * dangling reference it cannot decode.
  *
- * It was written three times. The Plan session factored its copy into a pure
- * `resolveAnswer` returning a typed `AnswerSource`, and its own docstring said so
- * out loud — "Mirrors the identical mapping in phaseGrill and planAuto" — but the
- * two mirrors were never converted, and they had already drifted apart in three
- * ways (which of them stamps an accepted recommendation, which has a
- * single-option card branch, which handles a typed reply that equals an option).
- * None was a crash. The next edit to any of them is where the bug lands, which is
- * why they now share this.
- *
- * What stays at the call sites is POLICY, not mechanics: grill's auto-answer and
- * widget line, clarify's plan-shape and triage pre-emption, plan's control
- * actions. Those genuinely differ.
+ * What stays at the call sites is POLICY, not mechanics: grill's auto-answer
+ * (`phaseAutoAnswer`) and its widget line, clarify's plan-shape fork and
+ * answer-side triage, plan's control actions. Those genuinely differ.
  */
 import type { AnswerSource } from './plan-io.js';
 import type { YoloPick } from './yolo.js';
@@ -46,8 +37,10 @@ export declare function isTwoOption(p: PendingQuestion): boolean;
 /**
  * The answer cards: the recommendation first (index 0 is the green RECOMMENDED
  * card), the alternative second when the question is a fork. `undefined` — not an
- * empty array — when there is nothing to recommend, because that is what makes
- * `ui.ask` fall back to a bare text prompt instead of an empty picker.
+ * empty array — when there is nothing to recommend, so a conditional spread of the
+ * result leaves the `options` key off the ask spec entirely. Either way the local
+ * side falls back to a bare text prompt: bridge.ts boxes only when
+ * `options.length > 0`.
  */
 export declare function buildOptionCards(p: PendingQuestion): Array<{
     label: string;
@@ -57,14 +50,13 @@ export declare function buildOptionCards(p: PendingQuestion): Array<{
  * Map what the picker returned onto the answer that gets recorded, and say WHERE
  * the answer came from.
  *
- * The `source` is returned rather than baked into the string because the three
- * call sites disagree about provenance stamping, and that disagreement is real:
- * `/task-auto`'s clarify transcript marks an accepted recommendation
- * ("… (accepted recommendation)") while grill's does not, because grill's
- * transcript is fed back verbatim into the next grill-gen prompt and the stamp
- * would become model input. Keeping the stamp at the call site makes that a
- * one-line difference you can see instead of a divergence hidden inside two
- * six-branch ladders.
+ * The `source` is returned rather than baked into the string because each
+ * transcript owns its own provenance table — `QA_PROVENANCE` (qa-transcript.ts)
+ * for grill and clarify, `SOURCE_STAMP` (plan-io.ts) for the plan file — and they
+ * disagree. That disagreement is real: clarify marks an accepted recommendation
+ * "(accepted recommendation)" while grill marks nothing, because grill's
+ * transcript is fed back verbatim into the next grill-gen prompt, where the stamp
+ * would become model input rather than the answer.
  */
 export declare function resolveAnswer(p: PendingQuestion, raw: string): {
     answer: string;
@@ -119,9 +111,7 @@ export type SettledKind = 'yolo' | 'yolo-skip' | 'accepted' | 'typed';
  * Settle one question: YOLO short-circuit, cards, ask, record.
  *
  * Returns `'cancelled'` rather than throwing, because that is the one thing the
- * two callers genuinely disagree about — grill throws `USER_CANCELLED` into the
- * phase ladder, clarify announces and returns null from the plan. Everything
- * before it was written out twice at ~50 lines each and had already drifted on
- * `recommended2`, harmless today only because the bridge re-guards it.
+ * two callers genuinely disagree about: grill throws `USER_CANCELLED` into the
+ * phase ladder, clarify announces and returns null from the plan.
  */
 export declare function settleQuestion(input: SettleQuestionInput): Promise<'settled' | 'cancelled'>;

package/dist/task/question-dialog.js

@@ -7,26 +7,17 @@
  * display; decide whether the question is a binary fork; short-circuit under
  * YOLO; build `A: …` / `B: …` cards; call `ui.ask`; treat `undefined` as a
  * cancel; and map the reply back onto an answer — where an empty submit accepts
- * the recommendation, a bare "A"/"B" from a remote user (or the picker's
- * free-text fallback) maps back to the option's full text, and anything else is
- * taken verbatim.
+ * the recommendation, a bare "A"/"B" ON A FORK (from a remote user, or from the
+ * picker's free-text fallback) maps back to that option's full text, and anything
+ * else is taken verbatim.
  *
- * The mapping is the load-bearing part. Storing the literal letter "A" leaves the
- * next generation call a dangling reference it cannot decode, so getting it wrong
- * is not cosmetic.
+ * The mapping is the load-bearing part. The recorded answer is fed back into the
+ * next generation call, so storing the literal letter "A" would hand that call a
+ * dangling reference it cannot decode.
  *
- * It was written three times. The Plan session factored its copy into a pure
- * `resolveAnswer` returning a typed `AnswerSource`, and its own docstring said so
- * out loud — "Mirrors the identical mapping in phaseGrill and planAuto" — but the
- * two mirrors were never converted, and they had already drifted apart in three
- * ways (which of them stamps an accepted recommendation, which has a
- * single-option card branch, which handles a typed reply that equals an option).
- * None was a crash. The next edit to any of them is where the bug lands, which is
- * why they now share this.
- *
- * What stays at the call sites is POLICY, not mechanics: grill's auto-answer and
- * widget line, clarify's plan-shape and triage pre-emption, plan's control
- * actions. Those genuinely differ.
+ * What stays at the call sites is POLICY, not mechanics: grill's auto-answer
+ * (`phaseAutoAnswer`) and its widget line, clarify's plan-shape fork and
+ * answer-side triage, plan's control actions. Those genuinely differ.
  */
 import { stripInlineMarkdown } from './inline-markdown.js';
 /** True when the question is a binary fork rather than a single recommendation. */
@@ -36,8 +27,10 @@ export function isTwoOption(p) {
 /**
  * The answer cards: the recommendation first (index 0 is the green RECOMMENDED
  * card), the alternative second when the question is a fork. `undefined` — not an
- * empty array — when there is nothing to recommend, because that is what makes
- * `ui.ask` fall back to a bare text prompt instead of an empty picker.
+ * empty array — when there is nothing to recommend, so a conditional spread of the
+ * result leaves the `options` key off the ask spec entirely. Either way the local
+ * side falls back to a bare text prompt: bridge.ts boxes only when
+ * `options.length > 0`.
  */
 export function buildOptionCards(p) {
     if (isTwoOption(p)) {
@@ -55,14 +48,13 @@ export function buildOptionCards(p) {
  * Map what the picker returned onto the answer that gets recorded, and say WHERE
  * the answer came from.
  *
- * The `source` is returned rather than baked into the string because the three
- * call sites disagree about provenance stamping, and that disagreement is real:
- * `/task-auto`'s clarify transcript marks an accepted recommendation
- * ("… (accepted recommendation)") while grill's does not, because grill's
- * transcript is fed back verbatim into the next grill-gen prompt and the stamp
- * would become model input. Keeping the stamp at the call site makes that a
- * one-line difference you can see instead of a divergence hidden inside two
- * six-branch ladders.
+ * The `source` is returned rather than baked into the string because each
+ * transcript owns its own provenance table — `QA_PROVENANCE` (qa-transcript.ts)
+ * for grill and clarify, `SOURCE_STAMP` (plan-io.ts) for the plan file — and they
+ * disagree. That disagreement is real: clarify marks an accepted recommendation
+ * "(accepted recommendation)" while grill marks nothing, because grill's
+ * transcript is fed back verbatim into the next grill-gen prompt, where the stamp
+ * would become model input rather than the answer.
  */
 export function resolveAnswer(p, raw) {
     const typed = raw.trim();
@@ -92,10 +84,8 @@ export function resolveAnswer(p, raw) {
  * Settle one question: YOLO short-circuit, cards, ask, record.
  *
  * Returns `'cancelled'` rather than throwing, because that is the one thing the
- * two callers genuinely disagree about — grill throws `USER_CANCELLED` into the
- * phase ladder, clarify announces and returns null from the plan. Everything
- * before it was written out twice at ~50 lines each and had already drifted on
- * `recommended2`, harmless today only because the bridge re-guards it.
+ * two callers genuinely disagree about: grill throws `USER_CANCELLED` into the
+ * phase ladder, clarify announces and returns null from the plan.
  */
 export async function settleQuestion(input) {
     const { ui, transcript, plain, shown, render, yolo } = input;

package/dist/task/question-source.d.ts

@@ -1,36 +1,12 @@
 /**
- * Where the NEXT question comes from — the other half of `question-dialog.ts`.
+ * Where the NEXT question comes from — the other half of `question-dialog.ts`,
+ * which owns the ANSWER side.
  *
- * `question-dialog.ts` unified the ANSWER side of the adaptive dialogs (the picker
- * cards, the reply mapping) and its own docstring makes the argument for doing so:
- * *"It was written three times… the two mirrors were never converted, and they had
- * already drifted apart in three ways… The next edit to any of them is where the
- * bug lands."* The QUESTION side — generate → parse → pick the real question →
- * dedupe → spend one corrective re-prompt → yield or exhaust — was left behind,
- * and it had drifted between the two loops that use the SAME parser on the SAME
- * prompt format (`plan-prompts.ts` says `parseClarifyList` parses it "UNCHANGED";
- * `auto-prompts.ts` specifies the identical shape).
- *
- * The five drifts, all in clarify's favour of being wrong:
- *
- *  1. **Which entry is the question.** `parseClarifyList` pushes an entry for
- *     EVERY numbered line, and the local model writes numbered analysis notes
- *     before the question it was asked for (measured live). `pickQuestion` prefers
- *     the first entry carrying a `SUGGESTED:` line; clarify took `parsed[0]`
- *     blindly, showing the note as the question and losing the recommendation
- *     attached further down.
- *  2. **NONE vs unparseable.** The parser returns `[]` for both. Clarify's
- *     `if (parsed.length === 0) break` ended the whole clarify — and decomposed the
- *     feature with ZERO clarifications — on a formatting slip.
- *  3. **A re-typed sentinel.** `isNoneReply`'s regex was a byte-identical second
- *     copy of the parser's own.
- *  4. **Missing SUGGESTED** bought one corrective re-prompt in plan and none in
- *     clarify, so clarify showed a card-less question.
- *  5. **The deferral guard.** 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 VERIFY asserted 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.
+ * One state machine: generate → parse → pick the real question → dedupe → spend
+ * one corrective re-prompt → yield or exhaust. Two loops drive it, `/task-auto`'s
+ * clarify and `/task-plan`, and they use the SAME parser on the SAME prompt format
+ * — plan-prompts.ts says `parseClarifyList` parses its output UNCHANGED, and
+ * auto-prompts.ts specifies the identical shape.
  *
  * NOT unified here: grill's generation loop. It uses a different parser
  * (`parseGrillQuestions`, which yields bare strings) and has no `SUGGESTED` at
@@ -41,11 +17,9 @@
  */
 import { type ClarifyQuestion } from './parsers.js';
 /**
- * The cap on distinct questions ONE adaptive dialog may ask.
- *
- * Clarify and plan each declared their own `8`, linked only by a comment saying
- * "matches /task-auto's MAX_CLARIFY_QUESTIONS, for the same reason". They bound
- * the same thing for the same reason; this is that reason, once.
+ * Default cap on distinct questions ONE adaptive dialog may ask. Both live
+ * callers pass their own constant of the same value instead
+ * (MAX_CLARIFY_QUESTIONS, MAX_PLAN_QUESTIONS); this is what an unset `cap` gets.
  */
 export declare const MAX_DIALOG_QUESTIONS = 8;
 /** True when the reply is the deliberate "nothing left to ask" sentinel, as
@@ -54,13 +28,12 @@ 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
- * attached further down. The prompt requires exactly one SUGGESTED, and the parser
- * attaches it to the entry it follows.
+ * `parseClarifyList` turns EVERY numbered line into an entry, and a model that
+ * writes a numbered analysis note before the question it was asked for produces
+ * more than one. Taking entry 0 blindly then shows the note as the question and
+ * loses the SUGGESTED line attached further down. The prompt requires exactly one
+ * SUGGESTED, and the parser attaches it to the entry it follows, so preferring the
+ * entry that HAS one lands on the real question.
  */
 export declare function pickQuestion<T extends {
     suggested?: string;
@@ -88,7 +61,8 @@ export interface QuestionSourceDeps {
     generate: (hint: string | null) => Promise<string>;
     /** The corrective re-prompt for a reply the parser could not read. */
     formatHint: string;
-    /** Ordered quality rules; each may fire at most once per question. */
+    /** Ordered quality rules. At most ONE fires per question: they share a single
+     *  corrective re-prompt, spent by the first rule that detects a defect. */
     rules?: ReadonlyArray<QuestionRule>;
     cap?: number;
     log?: (msg: string) => void;