@mjasnikovs/pi-task 0.38.16 → 0.38.17

package/dist/task/phases.js

@@ -40,7 +40,8 @@ import { detachUnsatisfiableRequirements, claimPendingRequirements, unclaimedPen
 import { trackedSourceOracle } from './owned-freeze-conflict.js';
 import { runPhaseChild, runWithEmphasisRetry, prependHint, USER_CANCELLED } from './child-runner.js';
 import { SessionUI } from '../remote/bridge.js';
-import { isYoloMode, yoloPickAutoAnswer, YOLO_STAMP } from './yolo.js';
+import { isYoloMode, yoloPickAutoAnswer } from './yolo.js';
+import { QaTranscript, GRILL_QA_POLICY } from './qa-transcript.js';
 // ─── Re-export constants from their home modules ────────────────────────────
 export { MAX_GRILL_QUESTIONS };
 // ─── Tooling helpers ─────────────────────────────────────────────────────────
@@ -1211,8 +1212,11 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
     // nothing ambiguous remains. Kept in sync with /task-auto's clarify dialog.
     const theme = ctx.ui.theme;
     const ui = new SessionUI(ctx);
-    const out = []; // human-facing Q&A transcript (with auto-worker debug lines)
-    const qa = []; // compact Q&A fed back into the next question
+    // ONE record, two renderings (task/qa-transcript.ts): `forRecord()` is what
+    // compose and critique are handed, `forGenerator()` is what the next grill-gen
+    // call sees. The provenance rule below used to be a comment 12 lines under a
+    // push that broke it.
+    const transcript = new QaTranscript(GRILL_QA_POLICY);
     const askedQuestions = []; // plain text of each question, for the dup backstop
     // Deterministic backstop against a model that ignores "never re-ask": a
     // near-duplicate question is reprompted (not auto-answered or shown), and after
@@ -1226,7 +1230,7 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
     for (let n = 0; n < MAX_GRILL_QUESTIONS; n++) {
         const tGenStart = Date.now();
         const genHint = dupHint;
-        const raw = await runPhaseChild(deps, 'grill-gen', 'read', prependHint(genHint, GRILL_GEN_PROMPT(refined, research, qa.join('\n'))), { verb: 'restart' });
+        const raw = await runPhaseChild(deps, 'grill-gen', 'read', prependHint(genHint, GRILL_GEN_PROMPT(refined, research, transcript.forGenerator())), { verb: 'restart' });
         deps.recordSubStep?.('gen', Date.now() - tGenStart);
         const questions = parseGrillQuestions(raw);
         if (questions.length === 0)
@@ -1252,11 +1256,8 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
         // for the editable default and the persisted file.
         const shownQ = renderInlineMarkdown(q, theme);
         const plainQ = stripInlineMarkdown(q);
-        out.push(`Q${n + 1}: ${plainQ}`);
-        let answer;
         if (auto.kind === 'answered') {
-            answer = stripInlineMarkdown(auto.text);
-            out.push(`A${n + 1}: ${answer} (auto)`);
+            transcript.add('auto', plainQ, stripInlineMarkdown(auto.text));
         }
         else {
             const plainSuggested = auto.suggested === undefined ? undefined : stripInlineMarkdown(auto.suggested);
@@ -1268,12 +1269,15 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
             // guard direction, promoting a hallucination is not.
             const yolo = yoloPickAutoAnswer(isYoloMode(), auto);
             if (yolo !== null) {
-                answer =
-                    yolo.kind === 'answer' ?
-                        stripInlineMarkdown(yolo.answer)
-                        : `(skipped — ${yolo.note})`;
-                out.push(`A${n + 1}: ${answer} ${YOLO_STAMP}`);
-                qa.push(`Q${n + 1}: ${plainQ}\nA${n + 1}: ${answer} ${YOLO_STAMP}`);
+                // The YOLO stamp is a RECORD fact. It used to be pushed into the
+                // generator feedback too, against the rule stated a dozen lines
+                // below — the policy now decides, so the two cannot disagree.
+                if (yolo.kind === 'answer') {
+                    transcript.add('yolo', plainQ, stripInlineMarkdown(yolo.answer));
+                }
+                else {
+                    transcript.add('yolo-skip', plainQ, `(skipped — ${yolo.note})`);
+                }
                 continue;
             }
             // The picker cards and the reply mapping are shared with /task-auto's
@@ -1304,17 +1308,17 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
             });
             if (a === undefined)
                 throw new Error(USER_CANCELLED);
-            // 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.
-            answer = resolveAnswer(pending, a).answer;
-            out.push(`A${n + 1}: ${answer}`);
+            // Grill's generator sees NO provenance — its feedback is fed verbatim
+            // into the next grill-gen prompt, where a suffix would describe how the
+            // answer was obtained rather than what it was. That is
+            // `GRILL_QA_POLICY.generatorSeesProvenance: false`, stated once.
+            const resolved = resolveAnswer(pending, a);
+            transcript.add(resolved.source === 'accepted' ? 'accepted' : 'typed', plainQ, resolved.answer);
         }
-        qa.push(`Q${n + 1}: ${plainQ}\nA${n + 1}: ${answer}`);
     }
-    if (out.length === 0)
+    if (transcript.length === 0)
         return '(no questions produced)';
-    return out.join('\n');
+    return transcript.forRecord();
 }
 /**
  * A refutation is a DELETION. Where the run's own research explicitly says a
@@ -1340,11 +1344,32 @@ export async function dropRefutedConstraints(deps, refined, research) {
     const refuted = applyRefutations(refined, research);
     if (refuted.trail.length === 0)
         return refined;
-    for (const line of refuted.trail) {
-        deps.logDebug?.(`compose: ${line}`);
+    await recordPhaseTrail(deps, 'compose', refuted.trail);
+    return refuted.refined;
+}
+/**
+ * COMPOSE's carry: the refutation drop, as a `PhaseConfig.carry`.
+ *
+ * Same transform as `dropRefutedConstraints` over the same pure core, minus the
+ * recording — the caller decides whether this application is the live one or a
+ * resume replay. `dropRefutedConstraints` stays exported and unchanged for the
+ * harnesses under `scripts/` that drive the drop directly.
+ */
+export function composeCarry(_deps, pc) {
+    // Not `async`, and that is the shape rather than an oversight: this carry
+    // performs no I/O at all, which is what lets the resume path replay it.
+    const refuted = applyRefutations(pc.refined, pc.research);
+    if (refuted.trail.length === 0)
+        return Promise.resolve([]);
+    pc.refined = refuted.refined;
+    return Promise.resolve(refuted.trail);
+}
+/** Write a carry's trail to the debug log and the task file's `## gates` section. */
+export async function recordPhaseTrail(deps, phaseName, trail) {
+    for (const line of trail) {
+        deps.logDebug?.(`${phaseName}: ${line}`);
         await appendGateRecord(deps.cwd, deps.taskId, line).catch(() => { });
     }
-    return refuted.refined;
 }
 export async function phaseCompose(deps, refined, research, qa) {
     // CLAIM before the belt is built: an obligation an earlier task had to
@@ -1558,14 +1583,14 @@ export function grillPhase(d, p) {
     return phaseGrill(d, p.ctx, p.widgetState, p.refined, p.research);
 }
 /**
- * COMPOSE — drop constraints research REFUTED before composing, then compose.
+ * COMPOSE — compose the spec from the refined task, the research and the Q&A.
  *
- * The drop mutates `p.refined` in place on purpose: the refuted constraint must be
- * gone from every later reader of the refined spec, not just from this call's
- * argument. Critique re-reads it.
+ * The refutation drop that must happen first is compose's declared `carry`
+ * (`composeCarry`), not a line at the top of this function. It settles `p.refined`,
+ * which is not compose's own `field`, so the orchestrator has to replay it on the
+ * resume path too — and a `run` body cannot be replayed.
  */
 export async function composePhase(d, p) {
-    p.refined = await dropRefutedConstraints(d, p.refined, p.research);
     return await phaseCompose(d, p.refined, p.research, p.qa);
 }
 /**
@@ -1604,12 +1629,40 @@ export async function critiquePhase(d, p) {
  * they run in is now asserted by driving the row rather than retyped in a test.
  */
 export const PHASES = [
-    { name: 'refine', section: 'refined prompt', field: 'refined', run: refinePhase },
+    {
+        name: 'refine',
+        section: 'refined prompt',
+        field: 'refined',
+        run: refinePhase,
+        postCommit: refinePostCommit
+    },
     { name: 'research', section: 'research', field: 'research', run: researchPhase },
     { name: 'grill', section: 'grill Q&A', field: 'qa', run: grillPhase },
-    { name: 'compose', section: 'spec', field: 'spec', run: composePhase },
+    { name: 'compose', section: 'spec', field: 'spec', carry: composeCarry, run: composePhase },
     { name: 'critique', section: 'spec', field: 'spec', run: critiquePhase }
 ];
+/**
+ * Run one phase row the way the orchestrator does: carry, then run.
+ *
+ * The row is the interface, so this is the surface a row-driving test crosses —
+ * calling `row.run` alone tests past it and would not have caught a carry that the
+ * resume path drops. The orchestrator adds only persistence, timings and the
+ * checkpoint around this.
+ */
+export async function runPhaseRow(row, deps, pc) {
+    if (row.carry)
+        await recordPhaseTrail(deps, row.name, await row.carry(deps, pc));
+    return await row.run(deps, pc);
+}
+/**
+ * Re-apply one phase row's carry on the RESUME path, where `run` is skipped.
+ *
+ * The trail is discarded: the live run that produced this phase's output already
+ * recorded it on `## gates`, and a replay must not append a second copy.
+ */
+export async function replayPhaseCarry(row, deps, pc) {
+    await row.carry?.(deps, pc);
+}
 // INTEGRATION-DEPTH APPEND (2026-07-27): the lever proposed for this exact site —
 // deterministically append a known-runnable integration command to the VERIFY block
 // whenever a task's ACCEPTANCE claims runtime behaviour — is REFUTED at STEP 0 and was
@@ -1654,9 +1707,16 @@ export const PHASES = [
 //
 // Durable assets kept: both rigs above and their unit tests. Do NOT wire an append here
 // without a command source that satisfies all four properties at once.
+/** Dispatch a row's declared post-commit effect. Rows with none do nothing. */
 export async function postCommitPhase(phase, deps, pc, out) {
-    if (phase.name !== 'refine')
-        return;
+    await phase.postCommit?.(deps, pc, out);
+}
+/**
+ * REFINE's post-commit: derive the task title from the refined prompt, then a short
+ * display label. Runs after the section write, so a fault here cannot lose the
+ * output it reads.
+ */
+export async function refinePostCommit(deps, pc, out) {
     const title = deriveTitle(out);
     pc.widgetState.title = title;
     // Compress the (often paragraph-long) title into a short display label. This

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

@@ -0,0 +1,86 @@
+/**
+ * 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 { type AdoptionDecision, type ScoredPlan } from './coverage-loop.js';
+/** What `consider` did with a candidate, and why. */
+export interface ConsiderOutcome {
+    adopted: boolean;
+    /** The adoption verdict's own reasoning, for the caller's trail. */
+    decision: AdoptionDecision;
+    /** True when this adoption is what bought the one bonus round. */
+    grantedBonusRound: boolean;
+}
+export interface CoverageLedgerOptions {
+    /** The round cap before any bonus. */
+    cap: number;
+    /**
+     * Are there grounded requirements to judge against?
+     *
+     * Without them `missing` is pure holistic-judge free text that can change every
+     * round, so there is no trustworthy "grew"/"new" signal — which is why the
+     * bonus round is requirements-path only.
+     */
+    hasRequirements: boolean;
+}
+/**
+ * The coverage loop's record: the best plan seen, the rounds spent, and the
+ * one-shot bonus round.
+ *
+ * Methods are named for what they MEAN, not for the field they touch.
+ */
+export declare class CoverageLedger {
+    private _best;
+    private readonly _opts;
+    private _round;
+    private _cap;
+    private _bonusUsed;
+    constructor(_best: ScoredPlan, _opts: CoverageLedgerOptions);
+    /** The best-covered plan seen so far — the one that reprompts, and the one that ships. */
+    best(): ScoredPlan;
+    /** Rounds spent so far. */
+    round(): number;
+    /** May another reprompt round run? */
+    mayRetry(): boolean;
+    /** Spend a round. Call once per reprompt, before the child runs. */
+    startRound(): number;
+    /** What is still uncovered in the shipping plan, or null when nothing is. */
+    unresolved(): string[] | 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: ScoredPlan): ConsiderOutcome;
+}

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. */