@mjasnikovs/pi-task 0.38.15 → 0.38.17

package/dist/task/plan-rounds.js

@@ -0,0 +1,105 @@
+/**
+ * What the PLAN-SHAPING loops record, 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.
+ *
+ * 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` 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.
+ */
+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;
+    _opts;
+    _round = 0;
+    _cap;
+    _bonusUsed = false;
+    constructor(_best, _opts) {
+        this._best = _best;
+        this._opts = _opts;
+        this._cap = _opts.cap;
+    }
+    /** The best-covered plan seen so far — the one that reprompts, and the one that ships. */
+    best() {
+        return this._best;
+    }
+    /** Rounds spent so far. */
+    round() {
+        return this._round;
+    }
+    /** May another reprompt round run? */
+    mayRetry() {
+        return this._round < this._cap;
+    }
+    /** Spend a round. Call once per reprompt, before the child runs. */
+    startRound() {
+        return ++this._round;
+    }
+    /** What is still uncovered in the shipping plan, or null when nothing is. */
+    unresolved() {
+        return this._best.plan.missing.length > 0 ? this._best.plan.missing : null;
+    }
+    /**
+     * Judge one candidate against the best plan and, if it wins, adopt it.
+     *
+     * The bonus-round grant is decided HERE, against the pre-adoption plan this
+     * method still holds — not by a caller reading a snapshot it took beforehand.
+     * Two guards keep it off generic judge churn: the grounded covered-set must
+     * strictly GROW (a flaky judge relabelling the same-shaped plan's gap does not
+     * qualify), and the candidate must expose a NEW area (a gap already present is
+     * one we have reprompted against or will). Bounded to one, so a judge that
+     * flags forever still cannot loop the plan phase.
+     */
+    consider(cand) {
+        const decision = decideAdoption(this._best.plan, cand.plan, this._opts.hasRequirements);
+        if (!decision.adopt)
+            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.
+        this._best = cand;
+        const grant = !this._bonusUsed
+            && this._round >= this._cap
+            && this._opts.hasRequirements
+            && cand.plan.covered.size > priorCovered
+            && cand.plan.missing.some((m) => !priorMissing.has(normMissingArea(m)));
+        if (grant) {
+            this._bonusUsed = true;
+            this._cap++;
+        }
+        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.

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

@@ -30,6 +30,7 @@
  * is unit-testable without a TUI or a model.
  */
 import type { AskSpec } from '../remote/bridge.js';
+import { type QuestionRule } from './question-source.js';
 import { type PlanEntry } from './plan-io.js';
 import { type PendingQuestion } from './question-dialog.js';
 export { resolveAnswer } from './question-dialog.js';
@@ -65,27 +66,7 @@ export declare const MAX_PLAN_QUESTIONS = 8;
  * recommend.
  */
 export declare const PLAN_FORMAT_HINT: string;
-/** True when the reply is the deliberate "nothing left to ask" sentinel, as
- *  opposed to output the parser simply could not read. */
-export declare function isNoneReply(raw: string): boolean;
-/**
- * Which of the parsed entries is the actual question.
- *
- * parseClarifyList turns EVERY numbered line into an entry, and the local model
- * sometimes writes a numbered analysis note or two before the question it was
- * asked for (measured live: the first numbered line was a note like
- * "1. gateDebugWriter in orchestrator.ts — wraps a raw append function"). Taking
- * entry 0 blindly then shows the note as the question and loses the SUGGESTED
- * line that was attached further down.
- *
- * The SUGGESTED line is the reliable marker of the real question — the prompt
- * requires exactly one, and parseClarifyList attaches it to the entry it follows.
- * So: prefer the first entry that has one; fall back to the first entry when none
- * does, which is the case the format re-prompt then covers.
- */
-export declare function pickQuestion<T extends {
-    suggested?: string;
-}>(parsed: T[]): T | undefined;
+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.
@@ -132,6 +113,35 @@ export declare function planDecisiveHint(question: string, suggested: string): s
  * subject. 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.
+ *
+ * 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 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.
+ *
+ * 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. */

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');
+    }
+}