@mjasnikovs/pi-task 0.38.16 → 0.38.17

package/dist/task/plan-session.js

@@ -29,9 +29,8 @@
  * persistence) arrives through {@link PlanSessionDeps}, so the whole interaction
  * is unit-testable without a TUI or a model.
  */
-import { parseClarifyList } from './parsers.js';
+import { makeQuestionSource } from './question-source.js';
 import { stripInlineMarkdown } from './inline-markdown.js';
-import { isDuplicateQuestion, DUP_REPROMPT_HINT, MAX_DUP_STRIKES } from './question-dedup.js';
 import { yoloPickAnswer } from './yolo.js';
 import { formatPlanTranscript } from './plan-io.js';
 import { buildOptionCards, resolveAnswer } from './question-dialog.js';
@@ -73,29 +72,13 @@ export const PLAN_FORMAT_HINT = '[SYSTEM NOTE: Your previous reply did NOT follo
     + 'REQUIRED and must never be blank. Add an "ALT: " line only for a binary A-or-B fork. '
     + 'If nothing is left to ask, output the single token NONE and nothing else. No preamble, '
     + 'no analysis, no other text.]';
-/** True when the reply is the deliberate "nothing left to ask" sentinel, as
- *  opposed to output the parser simply could not read. */
-export function isNoneReply(raw) {
-    return /^\s*NONE\s*$/m.test(raw);
-}
-/**
- * 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 function pickQuestion(parsed) {
-    return parsed.find(q => q.suggested !== undefined && q.suggested.length > 0) ?? parsed[0];
-}
+// Re-exported, NOT re-implemented. After the state machine moved to
+// question-source.ts these were byte-identical copies: production read THAT
+// module's, while plan-session.test.ts and four `scripts/live-*.ts` A/B harnesses
+// read these — so a fix to `pickQuestion`'s heuristic would land in one copy while
+// the harnesses kept measuring the other, and the measurement would silently stop
+// describing shipped behaviour. That is the drift class this pass removes.
+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.
@@ -171,6 +154,75 @@ export function planForkHint(question) {
         + 'time emit BOTH lines:\nSUGGESTED: <the option you recommend>\nALT: <the other option>\n'
         + 'Nothing else.]');
 }
+/**
+ * A default that DEFERS decides nothing, and an accepted deferral reaches the
+ * consumer dressed as an authoritative decision.
+ *
+ * Declared as its own constant because it is the one rule BOTH dialogs use, and
+ * `CLARIFY_QUALITY_RULES` referencing it by `id` string would be the retyped
+ * literal with no compile link that this pass exists to remove — a rename would
+ * silently yield `[undefined]` and throw on the first clarify question of every
+ * run.
+ */
+const DEFERRAL_RULE = {
+    id: 'SUGGESTED deferred the decision',
+    detect: (q, plain) => q.suggested !== undefined && isDeferralSuggestion(q.suggested) ?
+        planDecisiveHint(plain, q.suggested)
+        : null,
+    // When only the recommendation defers, the ALT is still a real commitment:
+    // promote it so the question keeps a usable default. With no ALT the option is
+    // DROPPED rather than shown, so an empty submit records an unanswered question
+    // instead of a decision the user never made.
+    repair: q => {
+        const { alt: _alt, suggested: _suggested, ...rest } = q;
+        return q.alt !== undefined ? { ...rest, suggested: q.alt } : { ...rest };
+    }
+};
+/**
+ * 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.
+ *
+ * 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.
+ */
+export const PLAN_QUALITY_RULES = [
+    {
+        // A question with no SUGGESTED leaves the picker with nothing to
+        // recommend, which is the one thing the prompt says must never happen.
+        id: 'no SUGGESTED',
+        detect: q => (q.suggested === undefined ? PLAN_FORMAT_HINT : null)
+    },
+    DEFERRAL_RULE,
+    {
+        // A fork-shaped question that ships one option leaves the user typing out
+        // the alternative the model itself just named (10/15 measured live).
+        id: 'fork-shaped question with no ALT',
+        detect: (q, plain) => q.alt === undefined && q.suggested !== undefined && looksLikeFork(plain) ?
+            planForkHint(plain)
+            : null
+    }
+];
+/**
+ * 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.
+ *
+ * It is also the only one of the three that costs nothing on the happy path: a
+ * decisive default never triggers it.
+ */
+export const CLARIFY_QUALITY_RULES = [DEFERRAL_RULE];
 // ─── Pending question ────────────────────────────────────────────────────────
 /**
  * Build the picker for a pending model question: the recommendation first (index
@@ -237,12 +289,7 @@ export const ASK_TITLE = 'Ask the model';
 export 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 async function runPlanSession(deps) {
     const entries = [];
-    const asked = [];
     const render = (s) => deps.renderMarkdown?.(s) ?? s;
-    let dupStrikes = 0;
-    let dupHint = null;
-    /** Set for exactly one corrective re-prompt after a malformed reply. */
-    let formatHint = null;
     /** The model has nothing (more) to ask: NONE, the cap, or the dup backstop. */
     let exhausted = false;
     let pending = null;
@@ -250,103 +297,33 @@ export async function runPlanSession(deps) {
         entries.push(entry);
         await deps.onEntries?.(entries);
     };
+    const questions = makeQuestionSource({
+        generate: hint => deps.generateQuestion(formatPlanTranscript(entries), hint),
+        formatHint: PLAN_FORMAT_HINT,
+        rules: PLAN_QUALITY_RULES,
+        cap: MAX_PLAN_QUESTIONS,
+        log: msg => deps.logDebug?.(`plan: ${msg}`)
+    });
     for (;;) {
         if (pending === null && !exhausted) {
-            if (asked.length >= MAX_PLAN_QUESTIONS) {
-                deps.logDebug?.(`plan: question cap (${MAX_PLAN_QUESTIONS}) reached`);
-                exhausted = true;
-                continue;
-            }
-            deps.setStatus?.(`thinking of question ${asked.length + 1}…`);
-            const raw = await deps.generateQuestion(formatPlanTranscript(entries), formatHint ?? dupHint);
+            deps.setStatus?.(`thinking of question ${questions.asked().length + 1}…`);
+            const drawn = await questions.next();
             deps.setStatus?.(undefined);
-            const parsed = parseClarifyList(raw);
-            // parseClarifyList returns [] both for a deliberate NONE and for
-            // output it could not parse at all — treating the second as "no
-            // questions left" would end the planning session on a formatting
-            // slip. Tell them apart, and give a malformed reply exactly one
-            // corrective re-prompt (the same one-shot recovery the grill
-            // auto-answer does with GRILL_AUTO_FORMAT_HINT).
-            if (parsed.length === 0) {
-                if (!isNoneReply(raw) && formatHint === null) {
-                    deps.logDebug?.('plan: unparseable question reply — one format re-prompt');
-                    formatHint = PLAN_FORMAT_HINT;
-                    continue;
-                }
-                deps.logDebug?.('plan: model has no further questions (NONE)');
-                formatHint = null;
+            if (drawn.kind === 'exhausted') {
                 exhausted = true;
                 continue;
             }
-            const picked = pickQuestion(parsed);
-            const { question, suggested, alt } = picked;
-            const plain = stripInlineMarkdown(question);
-            // The duplicate backstop runs BEFORE either quality re-prompt: a
-            // question that is about to be discarded as a re-ask must not first
-            // buy itself an extra child call to be polished.
-            if (isDuplicateQuestion(asked, plain)) {
-                dupStrikes++;
-                deps.logDebug?.(`plan: duplicate question, strike ${dupStrikes}/${MAX_DUP_STRIKES}`);
-                formatHint = null;
-                if (dupStrikes >= MAX_DUP_STRIKES) {
-                    exhausted = true;
-                    continue;
-                }
-                dupHint = DUP_REPROMPT_HINT;
-                continue;
-            }
-            // A question with no SUGGESTED line leaves the picker with nothing to
-            // recommend, which is the one thing the prompt says must never happen.
-            // One-shot recovery; if it still comes back bare we show the question
-            // anyway — a question with no default beats no question.
-            if (suggested === undefined && formatHint === null) {
-                deps.logDebug?.('plan: question had no SUGGESTED — one format re-prompt');
-                formatHint = PLAN_FORMAT_HINT;
-                continue;
-            }
-            // A default that defers decides nothing, and an accepted deferral
-            // reaches /task dressed as an authoritative decision. One re-prompt to
-            // make it decisive; if it comes back deferring anyway the option is
-            // DROPPED rather than shown, so an empty submit records "(skipped)" —
-            // an unanswered question — instead of a decision the user never made.
-            const defers = suggested !== undefined && isDeferralSuggestion(suggested);
-            if (defers && formatHint === null) {
-                deps.logDebug?.('plan: SUGGESTED deferred the decision — one re-prompt');
-                formatHint = planDecisiveHint(plain, suggested);
-                continue;
-            }
-            // When only the recommendation defers, the ALT is still a real
-            // commitment: promote it so the question keeps a usable default.
-            const usableSuggested = defers ? alt : suggested;
-            const usableAlt = defers ? undefined : alt;
-            if (defers) {
-                deps.logDebug?.(usableSuggested === undefined ?
-                    'plan: SUGGESTED still deferred — question shown with no recommendation'
-                    : 'plan: SUGGESTED still deferred — promoted the ALT to the recommendation');
-            }
-            // A question that offers a choice but ships one option leaves the
-            // user typing out the alternative the model just named. Same one-shot
-            // budget, quoting the question back so the (stateless) child re-asks
-            // this one instead of a new one.
-            if (usableAlt === undefined && formatHint === null && !defers && looksLikeFork(plain)) {
-                deps.logDebug?.('plan: fork-shaped question with no ALT — one re-prompt');
-                formatHint = planForkHint(plain);
-                continue;
-            }
-            formatHint = null;
-            dupStrikes = 0;
-            dupHint = null;
-            asked.push(plain);
+            const { question, suggested, alt } = drawn.q;
             pending = {
-                plain,
+                plain: drawn.plain,
                 shown: render(question),
-                ...(usableSuggested !== undefined && {
-                    suggested: stripInlineMarkdown(usableSuggested),
-                    shownSuggested: render(usableSuggested)
+                ...(suggested !== undefined && {
+                    suggested: stripInlineMarkdown(suggested),
+                    shownSuggested: render(suggested)
                 }),
-                ...(usableAlt !== undefined && {
-                    alt: stripInlineMarkdown(usableAlt),
-                    shownAlt: render(usableAlt)
+                ...(alt !== undefined && {
+                    alt: stripInlineMarkdown(alt),
+                    shownAlt: render(alt)
                 })
             };
         }
@@ -394,7 +371,7 @@ export async function runPlanSession(deps) {
             // had run out of questions may now have one. Re-open the generator.
             if (exhausted) {
                 exhausted = false;
-                dupStrikes = 0;
+                questions.reopen();
             }
             continue; // the pending question, if any, is still unanswered
         }
@@ -408,7 +385,7 @@ export async function runPlanSession(deps) {
             await commit({ kind: 'stated', text });
             if (exhausted) {
                 exhausted = false;
-                dupStrikes = 0;
+                questions.reopen();
             }
             continue;
         }

package/dist/task/qa-transcript.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The Q&A TRANSCRIPT of one adaptive dialog — grill (`/task`) or clarify
+ * (`/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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+/** How one answer was arrived at. */
+export type QaKind = 
+/** grill: the research-backed auto-answer resolved it without asking. */
+'auto'
+/** clarify: answer-side triage found the spec already settles it. */
+ | 'auto-resolved'
+/** clarify: the host answers this fork deterministically (plan shape). */
+ | 'host-set'
+/** unattended: took the recommended option. */
+ | 'yolo'
+/** unattended: nothing safe to take, so the fork is left open. */
+ | 'yolo-skip'
+/** the human took the recommendation — green card, or an empty submit. */
+ | 'accepted'
+/** the human wrote their own answer. */
+ | 'typed';
+/**
+ * The provenance suffix each kind carries. A new kind is a compile error until it
+ * declares one; `typed` declares the empty string, which is a statement, not a
+ * gap — a human's own words are the baseline everything else is marked against.
+ */
+export declare const QA_PROVENANCE: Record<QaKind, string>;
+export interface QaPolicy {
+    /** Kinds whose provenance appears in the RECORD — persisted, and handed on. */
+    record: ReadonlySet<QaKind>;
+    /**
+     * Does the text fed back to the QUESTION GENERATOR carry provenance?
+     *
+     * The two dialogs genuinely disagree, and both say so in their own comments.
+     * Grill's is fed VERBATIM into the next grill-gen prompt, so a suffix there
+     * becomes model input describing how the answer was obtained rather than what
+     * it was. Clarify deliberately shows its generator the provenance, so a
+     * question the triage already settled reads as settled and is not re-asked.
+     * An option, not a unification — it is observable either way.
+     */
+    generatorSeesProvenance: boolean;
+}
+/**
+ * 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.
+ */
+export declare const GRILL_QA_POLICY: QaPolicy;
+/** CLARIFY: stamps every non-typed kind, in the record and to the generator alike. */
+export declare const CLARIFY_QA_POLICY: QaPolicy;
+export interface QaEntry {
+    kind: QaKind;
+    question: string;
+    answer: string;
+}
+/**
+ * One dialog's transcript. Owns the numbering and both renderings; performs no
+ * I/O and knows nothing about children, pickers or sessions — which is what makes
+ * it drivable by a test that only wants to know what a model would have been
+ * shown.
+ */
+export declare class QaTranscript {
+    private readonly _policy;
+    private readonly _entries;
+    constructor(_policy: QaPolicy);
+    /** How many questions have been answered. Also the next question's number − 1. */
+    get length(): number;
+    get entries(): ReadonlyArray<QaEntry>;
+    /** Record one answered question. The number is assigned here, not by the caller. */
+    add(kind: QaKind, question: string, answer: string): void;
+    /** The persisted / handed-on transcript, with provenance per the policy. */
+    forRecord(): string;
+    /** The text fed back into the next question-generation prompt. */
+    forGenerator(): string;
+    private _render;
+}

package/dist/task/qa-transcript.js

@@ -0,0 +1,99 @@
+/**
+ * The Q&A TRANSCRIPT of one adaptive dialog — grill (`/task`) or clarify
+ * (`/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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { YOLO_STAMP } from './yolo.js';
+/**
+ * The provenance suffix each kind carries. A new kind is a compile error until it
+ * declares one; `typed` declares the empty string, which is a statement, not a
+ * gap — a human's own words are the baseline everything else is marked against.
+ */
+export const QA_PROVENANCE = {
+    auto: '(auto)',
+    'auto-resolved': '(auto-resolved — already settled by the spec)',
+    'host-set': '(host-set — plan granularity is not left to chance)',
+    yolo: YOLO_STAMP,
+    'yolo-skip': YOLO_STAMP,
+    accepted: '(accepted recommendation)',
+    typed: ''
+};
+/**
+ * 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.
+ */
+export const GRILL_QA_POLICY = {
+    record: new Set(['auto', 'yolo', 'yolo-skip']),
+    generatorSeesProvenance: false
+};
+/** CLARIFY: stamps every non-typed kind, in the record and to the generator alike. */
+export const CLARIFY_QA_POLICY = {
+    record: new Set(['auto-resolved', 'host-set', 'yolo', 'yolo-skip', 'accepted']),
+    generatorSeesProvenance: true
+};
+/**
+ * One dialog's transcript. Owns the numbering and both renderings; performs no
+ * I/O and knows nothing about children, pickers or sessions — which is what makes
+ * it drivable by a test that only wants to know what a model would have been
+ * shown.
+ */
+export class QaTranscript {
+    _policy;
+    _entries = [];
+    constructor(_policy) {
+        this._policy = _policy;
+    }
+    /** How many questions have been answered. Also the next question's number − 1. */
+    get length() {
+        return this._entries.length;
+    }
+    get entries() {
+        return this._entries;
+    }
+    /** Record one answered question. The number is assigned here, not by the caller. */
+    add(kind, question, answer) {
+        this._entries.push({ kind, question, answer });
+    }
+    /** The persisted / handed-on transcript, with provenance per the policy. */
+    forRecord() {
+        return this._render(e => this._policy.record.has(e.kind));
+    }
+    /** The text fed back into the next question-generation prompt. */
+    forGenerator() {
+        return this._render(e => this._policy.generatorSeesProvenance && this._policy.record.has(e.kind));
+    }
+    _render(stamped) {
+        return this._entries
+            .map((e, i) => {
+            const suffix = stamped(e) ? QA_PROVENANCE[e.kind] : '';
+            const answer = suffix ? `${e.answer} ${suffix}` : e.answer;
+            return `Q${i + 1}: ${e.question}\nA${i + 1}: ${answer}`;
+        })
+            .join('\n');
+    }
+}

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

@@ -0,0 +1,117 @@
+/**
+ * Where the NEXT question comes from — the other half of `question-dialog.ts`.
+ *
+ * `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.
+ *
+ * NOT unified here: grill's generation loop. It uses a different parser
+ * (`parseGrillQuestions`, which yields bare strings) and has no `SUGGESTED` at
+ * generation time at all — grill's recommendation comes from `phaseAutoAnswer`
+ * one step later, so every quality rule below is inapplicable to it. Folding it in
+ * would mean a generic over the parsed shape with one consumer opting out of the
+ * entire rule table: a wider interface for less behaviour.
+ */
+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.
+ */
+export declare const MAX_DIALOG_QUESTIONS = 8;
+/** 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
+ * attached further down. The prompt requires exactly one SUGGESTED, and the parser
+ * attaches it to the entry it follows.
+ */
+export declare function pickQuestion<T extends {
+    suggested?: string;
+}>(parsed: T[]): T | undefined;
+/**
+ * One QUALITY rule: a defect in an otherwise-usable question that is worth exactly
+ * one corrective re-prompt.
+ *
+ * `detect` returns the hint to re-prompt with, or null to pass. `repair` is what
+ * to do when the SAME defect survives the re-prompt — a question with a bad
+ * default still beats no question, so a rule degrades rather than discards.
+ */
+export interface QuestionRule {
+    id: string;
+    detect: (q: ClarifyQuestion, plain: string) => string | null;
+    /** Applied only when the defect survived its one re-prompt. */
+    repair?: (q: ClarifyQuestion) => ClarifyQuestion;
+}
+export interface QuestionSourceDeps {
+    /**
+     * Ask the model for the next question. `hint` is the corrective re-prompt to
+     * prepend, or null. The caller closes over its own transcript and prompt — the
+     * source never builds one.
+     */
+    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. */
+    rules?: ReadonlyArray<QuestionRule>;
+    cap?: number;
+    log?: (msg: string) => void;
+}
+export type NextQuestion = {
+    kind: 'question';
+    q: ClarifyQuestion;
+    plain: string;
+    index: number;
+} | {
+    kind: 'exhausted';
+    why: 'none' | 'cap' | 'dups' | 'unparseable';
+};
+/**
+ * A deep module over a state machine that was five mutable locals per site.
+ *
+ * The interface is one method. Behind it: the cap, the duplicate backstop and its
+ * strike budget, the NONE-vs-unparseable distinction, `pickQuestion`, the one-shot
+ * budget shared by every quality rule, and the hint precedence between a format
+ * re-prompt and a duplicate re-prompt.
+ */
+export declare function makeQuestionSource(deps: QuestionSourceDeps): {
+    next: () => Promise<NextQuestion>;
+    asked: () => ReadonlyArray<string>;
+    reopen: () => void;
+};