@mjasnikovs/pi-task 0.38.29 → 0.38.30

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

@@ -1,36 +1,48 @@
 /**
- * Clarify: asks ONE question at a time. Output MUST match parseClarifyList — a
- * single numbered question followed by a "SUGGESTED: <default>" line, an optional
- * "ALT: <alternative>" line for binary "A or B?" forks, or the literal token NONE
- * when no clarification remains. priorQA carries the questions already answered so
- * each next question adapts to them.
+ * Clarify: asks ONE question at a time. Output MUST match `parseClarifyList` —
+ * the shared parser in parsers.ts that question-source.ts actually calls on this
+ * reply — so the shape is a single numbered question, then a "SUGGESTED: <default>"
+ * line, then an optional "ALT: <alternative>" line for binary "A or B?" forks, or
+ * the literal token NONE when no clarification remains. `priorQA` is interpolated
+ * as ANSWERS SO FAR, so each next question adapts to what has been settled.
+ *
+ * Runs with the read tool (`--tools read`), which is what the "you may use the read
+ * tool" line above depends on.
  */
 export declare const AUTO_CLARIFY_PROMPT: (feature: string, priorQA: string) => string;
 /**
  * Decompose: output a markdown checkbox list of task titles (one line each).
- * `requirementsLedger` is buildRequirementsLedger's grounded quote list (goal E's
- * belt): the spec's obligations ride into decompose explicitly, so mirroring the
- * spec's own milestone/section structure cannot silently discharge them. '' ⇒
- * the prompt is unchanged.
  *
- * `noBatchTests` adds the anti-batch-test rule (batch-test-task.ts) — emitted ONLY
- * when the decisions mandate tests-in-the-same-change, so every other run sees the
- * prompt it always saw. It is the belt; the host-side rewrite is the lever.
+ * `requirementsLedger` is buildRequirementsLedger's grounded quote list: the spec's
+ * obligations ride into decompose explicitly, so mirroring the spec's own
+ * milestone/section structure cannot silently discharge them. An empty or
+ * whitespace-only ledger leaves the prompt byte-identical to the default — checked.
+ *
+ * `noBatchTests` adds the anti-batch-test rule (batch-test-task.ts), emitted ONLY
+ * when the decisions mandate tests-in-the-same-change; `false` also leaves the
+ * prompt byte-identical, so every other run sees the same text. It is the belt —
+ * `rewriteBatchTestPlan` is the host-side lever.
  *
- * Plan GRANULARITY is deliberately NOT a rule here — it rides in CLARIFICATIONS
- * (decompose-granularity.ts). Live A/B: as a RULES line replacing "prefer a
- * handful", it made plan size explode (81 and 85 titles for a spec whose healthy
- * plan is ~30, one 120k-context blowup); as a clarification, with the counterweight
- * below left intact, the same directive holds 20–39 across 16 reps.
+ * Plan GRANULARITY is deliberately NOT a rule here. The only count-shaped line in
+ * RULES is the FORMAT one ("One task per line"); the floor reaches the model as a
+ * CLARIFICATION instead, through the host-set plan-shape answer in the transcript
+ * (decompose-granularity.ts), with a split-retry hint if the drawn plan still comes
+ * in under it. Kept out of RULES so it lands as one input among several rather
+ * than as another imperative competing with the ones already there.
  */
 export declare const AUTO_DECOMPOSE_PROMPT: (feature: string, clarifications: string, requirementsLedger?: string, noBatchTests?: boolean) => string;
 /**
- * Coverage triage: judge whether a decomposed task list covers the whole
- * feature. Guards the plan — the highest-leverage artifact in /task-auto —
- * against a degenerate-but-nonempty decompose completion (live mx5: the model
- * emitted ONE task for an 18KB design doc with a natural EOS, and the only
- * existing gate was `titles.length === 0`, so the run "completed" after one
- * task). Pure judgment over text already in hand, so it runs with --no-tools.
- * Output MUST match parseCoverageVerdict.
+ * Coverage triage: judge whether a decomposed task list covers the whole feature.
+ * Guards the plan — the highest-leverage artifact in /task-auto — against a
+ * degenerate-but-nonempty decompose completion: one task emitted for a whole
+ * design document, with a natural end-of-stream, which a `titles.length === 0`
+ * gate waves through so the run "completes" after that single task.
+ *
+ * Pure judgment over text already in hand, so it runs with NO tools: the call site
+ * passes an empty tools string, which childArgs turns into `--no-tools`.
+ *
+ * Output MUST match `parseCoverageVerdict`, including the at-most-8 bound — the
+ * parser stops collecting MISSING lines at eight, so a longer list is truncated
+ * rather than rejected.
  */
 export declare const DECOMPOSE_COVERAGE_PROMPT: (feature: string, clarifications: string, list: string[]) => string;

package/dist/task/auto-prompts.js

@@ -1,15 +1,21 @@
 /**
- * Prompts for /task-auto's two feature-level child calls. These produce a task
- * LIST only; all research/spec depth is /task's job, run per-title later.
+ * The three feature-level prompts /task-auto sends before any task starts: one
+ * clarifying QUESTION at a time, one task LIST, and one coverage VERDICT over
+ * that list. None of them produces a spec — all research and spec depth is
+ * /task's job, run per title later.
  */
 import { DECOMPOSE_SOURCE_RULE } from './decompose-fidelity.js';
 import { DECOMPOSE_NO_BATCH_TESTS_RULE } from './batch-test-task.js';
 /**
- * Clarify: asks ONE question at a time. Output MUST match parseClarifyList — a
- * single numbered question followed by a "SUGGESTED: <default>" line, an optional
- * "ALT: <alternative>" line for binary "A or B?" forks, or the literal token NONE
- * when no clarification remains. priorQA carries the questions already answered so
- * each next question adapts to them.
+ * Clarify: asks ONE question at a time. Output MUST match `parseClarifyList` —
+ * the shared parser in parsers.ts that question-source.ts actually calls on this
+ * reply — so the shape is a single numbered question, then a "SUGGESTED: <default>"
+ * line, then an optional "ALT: <alternative>" line for binary "A or B?" forks, or
+ * the literal token NONE when no clarification remains. `priorQA` is interpolated
+ * as ANSWERS SO FAR, so each next question adapts to what has been settled.
+ *
+ * Runs with the read tool (`--tools read`), which is what the "you may use the read
+ * tool" line above depends on.
  */
 export const AUTO_CLARIFY_PROMPT = (feature, priorQA) => `You are planning how to split a feature into separate implementation tasks, one clarifying question at a time.
 
@@ -68,20 +74,23 @@ No question remains:
 NONE`;
 /**
  * Decompose: output a markdown checkbox list of task titles (one line each).
- * `requirementsLedger` is buildRequirementsLedger's grounded quote list (goal E's
- * belt): the spec's obligations ride into decompose explicitly, so mirroring the
- * spec's own milestone/section structure cannot silently discharge them. '' ⇒
- * the prompt is unchanged.
  *
- * `noBatchTests` adds the anti-batch-test rule (batch-test-task.ts) — emitted ONLY
- * when the decisions mandate tests-in-the-same-change, so every other run sees the
- * prompt it always saw. It is the belt; the host-side rewrite is the lever.
+ * `requirementsLedger` is buildRequirementsLedger's grounded quote list: the spec's
+ * obligations ride into decompose explicitly, so mirroring the spec's own
+ * milestone/section structure cannot silently discharge them. An empty or
+ * whitespace-only ledger leaves the prompt byte-identical to the default — checked.
+ *
+ * `noBatchTests` adds the anti-batch-test rule (batch-test-task.ts), emitted ONLY
+ * when the decisions mandate tests-in-the-same-change; `false` also leaves the
+ * prompt byte-identical, so every other run sees the same text. It is the belt —
+ * `rewriteBatchTestPlan` is the host-side lever.
  *
- * Plan GRANULARITY is deliberately NOT a rule here — it rides in CLARIFICATIONS
- * (decompose-granularity.ts). Live A/B: as a RULES line replacing "prefer a
- * handful", it made plan size explode (81 and 85 titles for a spec whose healthy
- * plan is ~30, one 120k-context blowup); as a clarification, with the counterweight
- * below left intact, the same directive holds 20–39 across 16 reps.
+ * Plan GRANULARITY is deliberately NOT a rule here. The only count-shaped line in
+ * RULES is the FORMAT one ("One task per line"); the floor reaches the model as a
+ * CLARIFICATION instead, through the host-set plan-shape answer in the transcript
+ * (decompose-granularity.ts), with a split-retry hint if the drawn plan still comes
+ * in under it. Kept out of RULES so it lands as one input among several rather
+ * than as another imperative competing with the ones already there.
  */
 export const AUTO_DECOMPOSE_PROMPT = (feature, clarifications, requirementsLedger = '', noBatchTests = false) => `Split this feature into an ordered list of implementation tasks. Each task
 will be handed, by its title, to a separate pipeline that does its own research
@@ -108,13 +117,18 @@ RULES:
 ${DECOMPOSE_SOURCE_RULE}${noBatchTests ? `\n${DECOMPOSE_NO_BATCH_TESTS_RULE}` : ''}
 - Output the checkbox list and NOTHING else (no preamble, no numbering).`;
 /**
- * Coverage triage: judge whether a decomposed task list covers the whole
- * feature. Guards the plan — the highest-leverage artifact in /task-auto —
- * against a degenerate-but-nonempty decompose completion (live mx5: the model
- * emitted ONE task for an 18KB design doc with a natural EOS, and the only
- * existing gate was `titles.length === 0`, so the run "completed" after one
- * task). Pure judgment over text already in hand, so it runs with --no-tools.
- * Output MUST match parseCoverageVerdict.
+ * Coverage triage: judge whether a decomposed task list covers the whole feature.
+ * Guards the plan — the highest-leverage artifact in /task-auto — against a
+ * degenerate-but-nonempty decompose completion: one task emitted for a whole
+ * design document, with a natural end-of-stream, which a `titles.length === 0`
+ * gate waves through so the run "completes" after that single task.
+ *
+ * Pure judgment over text already in hand, so it runs with NO tools: the call site
+ * passes an empty tools string, which childArgs turns into `--no-tools`.
+ *
+ * Output MUST match `parseCoverageVerdict`, including the at-most-8 bound — the
+ * parser stops collecting MISSING lines at eight, so a longer list is truncated
+ * rather than rejected.
  */
 export const DECOMPOSE_COVERAGE_PROMPT = (feature, clarifications, list) => `You are auditing a task decomposition for completeness. Below is a FEATURE
 REQUEST (with any referenced design spec inlined), the CLARIFICATIONS the user

package/dist/task/autofix-ledger.d.ts

@@ -2,28 +2,25 @@
  * autofix-ledger — what the run-end RESOLUTION LOOP records, and the decisions
  * that record makes.
  *
- * The same deepening `GateTally` already proved one altitude down. That replaced
- * twelve mutable locals threaded through ~400 lines of `runFinalIntegrationGate`
- * by closure; this replaces six threaded through ~235 lines of
- * `runFinalGateStage` — the attempt count, the accumulated gitignored writes, the
- * stranded sub-fixes, the previous failure signature, the demoted set, and the
- * rejected-edits flag.
+ * Six pieces of state that would otherwise be mutable locals threaded through
+ * `runFinalGateStage` by closure: the attempt count, the accumulated gitignored
+ * writes, the stranded sub-fixes, the previous failure signature, the demoted
+ * set, and the rejected-edits flag. The same shape `GateTally` uses one altitude
+ * down.
  *
  * The reason is not tidiness. `final-gate-progress.ts` holds five pure functions,
- * each called from exactly ONE site inside that loop — extracted for testability
- * while the decisions about ORDERING and CARRY-FORWARD stayed in the caller. That
- * is precisely the shape `isNonProgress`'s own comment indicts:
- *
- *   > The fix is NOT a better string pattern — the bug is that the decision was
- *   > made downstream from the evidence.
- *
- * mx5 run 21 shipped a product whose every page was blank as a `completed` run
- * through that gap. Here the evidence and the decision sit in one module, and the
- * loop body reads as picker → apply → record.
+ * and all five are consumed HERE and nowhere else — run-final-gate.ts names the
+ * module only in comments and does not import it. The judgement therefore sits
+ * beside the evidence it judges: `judge` reads `observedFailures` off the SAME
+ * outcome the failure came from, and enters the demoted signature and breaks the
+ * previous-signature chain in that one call. A caller cannot apply those steps
+ * out of order or skip one, and the loop body reads as picker → apply → record.
  *
  * What is NOT here: anything that talks to the user, writes a ledger file, or
- * commits. The loop keeps those, the same way `GateTally` keeps no I/O — a record
- * that performs effects cannot be driven by a test that only wants the verdict.
+ * commits — confirmed, the module's only import is final-gate-progress and it
+ * touches no filesystem, UI or git. The loop keeps those, the same way
+ * `GateTally` keeps no I/O: a record that performs effects cannot be driven by a
+ * test that only wants the verdict.
  */
 /** The gate-outcome fields this record reads. Structural, so a caller can hand it
  *  a `FinalGateOutcome` without this module importing the gate. */
@@ -51,11 +48,15 @@ export declare class AutofixLedger {
     private _attempts;
     /**
      * Gitignored paths the fix passes have written so far. ACCUMULATED across
-     * attempts: a `.env` written by a failed attempt is still on disk for the next
-     * one, and that attempt's own before/after diff cannot see it (mx5 run 19).
+     * attempts, and that asymmetry with `_stranded` below is deliberate: a `.env`
+     * written by a failed attempt is still on disk for the next one, and that
+     * attempt's own before/after diff cannot see it. Run: two calls carrying an
+     * overlapping path yield the union, deduplicated, in first-seen order.
      */
     private _ignoredWritten;
-    /** Sub-fixes a non-converging attempt left uncommitted. REPLACED each attempt. */
+    /** Sub-fixes a non-converging attempt left uncommitted. REPLACED each attempt,
+     *  unlike `_ignoredWritten` above — this is a snapshot of what is uncommitted
+     *  right now, not a history. Run: a second `setStranded` discards the first. */
     private _stranded;
     /** The previous attempt's normalized ranked-first failure. */
     private _prevFailSig;
@@ -64,7 +65,7 @@ export declare class AutofixLedger {
     /**
      * A write-guard rejected an attempt whose edits could NOT be discarded, so
      * REJECTED edits are sitting in the tree and the terminal paths must not commit
-     * what they find there (mx5 run 14 item 2b — the cheat guard is never weakened
+     * what they find there (the cheat guard is never weakened
      * to ease committing).
      */
     private _rejectedEditsInTree;
@@ -85,9 +86,10 @@ export declare class AutofixLedger {
     /**
      * May a terminal path commit what is in the working tree?
      *
-     * False once a guard has rejected an attempt without discarding its edits.
-     * This is the ONE question the flag exists to answer, and it is asked at three
-     * terminal sites — as a method rather than a bare boolean read at each.
+     * False once a guard has rejected an attempt without discarding its edits, and
+     * it never flips back — rejected edits stay rejected for the rest of the loop.
+     * Exposed as a method rather than a public boolean so the question is asked in
+     * one vocabulary wherever a terminal path needs it.
      */
     mayCommitTree(): boolean;
     /**

package/dist/task/autofix-ledger.js

@@ -2,28 +2,25 @@
  * autofix-ledger — what the run-end RESOLUTION LOOP records, and the decisions
  * that record makes.
  *
- * The same deepening `GateTally` already proved one altitude down. That replaced
- * twelve mutable locals threaded through ~400 lines of `runFinalIntegrationGate`
- * by closure; this replaces six threaded through ~235 lines of
- * `runFinalGateStage` — the attempt count, the accumulated gitignored writes, the
- * stranded sub-fixes, the previous failure signature, the demoted set, and the
- * rejected-edits flag.
+ * Six pieces of state that would otherwise be mutable locals threaded through
+ * `runFinalGateStage` by closure: the attempt count, the accumulated gitignored
+ * writes, the stranded sub-fixes, the previous failure signature, the demoted
+ * set, and the rejected-edits flag. The same shape `GateTally` uses one altitude
+ * down.
  *
  * The reason is not tidiness. `final-gate-progress.ts` holds five pure functions,
- * each called from exactly ONE site inside that loop — extracted for testability
- * while the decisions about ORDERING and CARRY-FORWARD stayed in the caller. That
- * is precisely the shape `isNonProgress`'s own comment indicts:
- *
- *   > The fix is NOT a better string pattern — the bug is that the decision was
- *   > made downstream from the evidence.
- *
- * mx5 run 21 shipped a product whose every page was blank as a `completed` run
- * through that gap. Here the evidence and the decision sit in one module, and the
- * loop body reads as picker → apply → record.
+ * and all five are consumed HERE and nowhere else — run-final-gate.ts names the
+ * module only in comments and does not import it. The judgement therefore sits
+ * beside the evidence it judges: `judge` reads `observedFailures` off the SAME
+ * outcome the failure came from, and enters the demoted signature and breaks the
+ * previous-signature chain in that one call. A caller cannot apply those steps
+ * out of order or skip one, and the loop body reads as picker → apply → record.
  *
  * What is NOT here: anything that talks to the user, writes a ledger file, or
- * commits. The loop keeps those, the same way `GateTally` keeps no I/O — a record
- * that performs effects cannot be driven by a test that only wants the verdict.
+ * commits — confirmed, the module's only import is final-gate-progress and it
+ * touches no filesystem, UI or git. The loop keeps those, the same way
+ * `GateTally` keeps no I/O: a record that performs effects cannot be driven by a
+ * test that only wants the verdict.
  */
 import { applyDemotions, isNonProgress, normalizeFailureDetail, rankedFirstFailure, unobservedDebtReason } from './final-gate-progress.js';
 export class AutofixLedger {
@@ -32,11 +29,15 @@ export class AutofixLedger {
     _attempts = 0;
     /**
      * Gitignored paths the fix passes have written so far. ACCUMULATED across
-     * attempts: a `.env` written by a failed attempt is still on disk for the next
-     * one, and that attempt's own before/after diff cannot see it (mx5 run 19).
+     * attempts, and that asymmetry with `_stranded` below is deliberate: a `.env`
+     * written by a failed attempt is still on disk for the next one, and that
+     * attempt's own before/after diff cannot see it. Run: two calls carrying an
+     * overlapping path yield the union, deduplicated, in first-seen order.
      */
     _ignoredWritten = [];
-    /** Sub-fixes a non-converging attempt left uncommitted. REPLACED each attempt. */
+    /** Sub-fixes a non-converging attempt left uncommitted. REPLACED each attempt,
+     *  unlike `_ignoredWritten` above — this is a snapshot of what is uncommitted
+     *  right now, not a history. Run: a second `setStranded` discards the first. */
     _stranded = [];
     /** The previous attempt's normalized ranked-first failure. */
     _prevFailSig = null;
@@ -45,7 +46,7 @@ export class AutofixLedger {
     /**
      * A write-guard rejected an attempt whose edits could NOT be discarded, so
      * REJECTED edits are sitting in the tree and the terminal paths must not commit
-     * what they find there (mx5 run 14 item 2b — the cheat guard is never weakened
+     * what they find there (the cheat guard is never weakened
      * to ease committing).
      */
     _rejectedEditsInTree = false;
@@ -89,9 +90,10 @@ export class AutofixLedger {
     /**
      * May a terminal path commit what is in the working tree?
      *
-     * False once a guard has rejected an attempt without discarding its edits.
-     * This is the ONE question the flag exists to answer, and it is asked at three
-     * terminal sites — as a method rather than a bare boolean read at each.
+     * False once a guard has rejected an attempt without discarding its edits, and
+     * it never flips back — rejected edits stay rejected for the rest of the loop.
+     * Exposed as a method rather than a public boolean so the question is asked in
+     * one vocabulary wherever a terminal path needs it.
      */
     mayCommitTree() {
         return !this._rejectedEditsInTree;
@@ -123,7 +125,8 @@ export class AutofixLedger {
             })) {
             this._demoted.add(normalizeFailureDetail(detail));
             // A demotion ends the chain: the next attempt has no previous signature
-            // to match, so one demotion cannot cascade into a second.
+            // to match, so one demotion cannot cascade into a second. Run on three
+            // identical outcomes — only the SECOND demotes, the third does not.
             this._prevFailSig = null;
             return { detail, demoted: true, debtReason: unobservedDebtReason(detail) };
         }

package/dist/task/batch-test-task.d.ts

@@ -1,11 +1,12 @@
 /**
  * Does the decisions/spec text mandate tests-in-the-same-change?
  *
- * Scans sentence by sentence and requires BOTH signals in the SAME sentence, so
- * a testing section that happens to sit near an unrelated "don't defer" line
- * cannot trigger the ban. `decisions` is checked first and alone is sufficient;
- * the spec is scanned too because run 14's cadence rule is stated in §10 of the
- * doc and only echoed into the decisions channel.
+ * Scans sentence by sentence and requires BOTH signals in the SAME sentence, so a
+ * testing section that happens to sit near an unrelated "don't defer" line cannot
+ * trigger the ban — confirmed, "Don't defer the docs. Every route has tests."
+ * returns false. `decisions` is checked first and alone is sufficient; the spec is
+ * scanned too, and a mandate found only there is enough, because a cadence rule is
+ * often stated in the doc body and only echoed into the decisions channel.
  */
 export declare function mandatesTestsInSameChange(decisions: string, spec?: string): boolean;
 /**
@@ -25,9 +26,11 @@ export declare function findBatchTestTitles(titles: string[], spec?: string): nu
  * The spec's own coverage source — the command whose report scopes the sweep.
  *
  * Only backticked spans are considered, so the result is a command the spec
- * actually writes down rather than a phrase inferred from prose; a span carrying
- * a coverage flag wins over a plain test run. Falls back to a generic phrase when
- * the spec names no command, which keeps the sweep title well-formed either way.
+ * actually writes down rather than a phrase inferred from prose: a plain-prose
+ * "bun test" is ignored and falls through to the generic phrase. A span carrying a
+ * coverage flag wins over a plain test run — a spec naming both `bun test` and
+ * `bun test --coverage` yields the latter. The fallback keeps the sweep title
+ * well-formed when the spec names no command at all.
  */
 export declare function coverageSourceFromSpec(spec: string): string;
 /**
@@ -56,15 +59,20 @@ export interface BatchTestRewrite {
  * Rewrite a decomposed plan so it carries no whole-project batch test task when
  * the decisions mandate tests-in-the-same-change.
  *
- * No mandate, or no batch title ⇒ the plan is returned untouched (identity), so
- * every non-cadence run behaves exactly as before.
+ * No mandate, or no batch title ⇒ the plan is returned untouched, with no actions,
+ * so every non-cadence run is unaffected. Both identity paths run as described.
  *
  * With a mandate, ALL batch titles are removed at once before coverage is
  * re-measured — otherwise two batch tasks would each mask the other's orphans and
  * both would look droppable. The orphaned set is then whatever grounded coverage
  * the removal costs; it is non-empty only when no other task's title claims that
- * requirement, and it becomes the sweep's scope. At most ONE sweep is emitted (in
- * the first batch title's position, so plan order is preserved).
+ * requirement, and it becomes the sweep's scope. At most ONE sweep is emitted, in
+ * the first batch title's position, so plan order is preserved.
+ *
+ * Run on the SAME batch title twice, changing only the requirement list: when
+ * another task grounds the requirement the title is DROPPED, and when the batch
+ * title is its only owner it is SCOPED into a sweep naming that quote and the
+ * spec's own coverage command. Any `[decisions: …]` tail rides onto the sweep.
  */
 export declare function rewriteBatchTestPlan(titles: string[], decisions: string, spec: string, requirementQuotes: string[], isCrossCutting: (quote: string) => boolean): BatchTestRewrite;
 /**