@mjasnikovs/pi-task 0.23.0 → 0.23.1

package/dist/task/auto-orchestrator.js

@@ -89,9 +89,26 @@ function coverageRepromptHint(missing) {
 // that insists twice still ships its small plan, with a warning.
 const SUSPECT_PLAN_MAX_TITLES = 2;
 const SUSPECT_PLAN_MIN_SPEC_CHARS = 4000;
+/**
+ * Extra retries granted when the plan is EMPTY rather than merely small. One
+ * hinted retry heals a small-but-nonempty plan reliably; an empty generation is a
+ * harder fault and was measured recurring back-to-back (2026-07-28 smoke: 13 empty
+ * draws across 24 reps of a 20KB spec, including two in a row in one rep).
+ */
+const EMPTY_PLAN_RETRIES = 2;
+/**
+ * An empty list is NEVER a valid decomposition of any feature request, at any spec
+ * size. It used to escape this guard entirely — the old predicate opened with
+ * `titles.length > 0`, so zero titles was not "suspect", the suspect-retry never
+ * fired, the coverage loop broke immediately on `titles.length === 0`, and the run
+ * aborted with "no tasks produced from the feature". A single degenerate
+ * generation killed the whole run with no retry, which is the opposite of how the
+ * same fault is treated one title higher.
+ */
 function isSuspectPlan(titles, featureForModel) {
-    return (titles.length > 0
-        && titles.length <= SUSPECT_PLAN_MAX_TITLES
+    if (titles.length === 0)
+        return true;
+    return (titles.length <= SUSPECT_PLAN_MAX_TITLES
         && featureForModel.length >= SUSPECT_PLAN_MIN_SPEC_CHARS);
 }
 /** Reprompt prefix for a suspect (degenerate-count) list; unlike
@@ -695,8 +712,32 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // catch it (3/10 live false-pass) and a hinted retry heals it reliably
     // (5/5 live). Longer list wins; a still-suspect plan falls through to the
     // judge loop as before, so this never blocks planning.
-    if (isSuspectPlan(planTitles, featureForModel)) {
+    // An EMPTY plan gets extra attempts (see EMPTY_PLAN_RETRIES): falling through
+    // with zero titles aborts the whole run, so one roll of the dice is not enough.
+    // A merely-small plan keeps its single retry — it still ships if the retry does
+    // not help, so spending more children on it buys nothing.
+    //
+    // The two budgets are tracked SEPARATELY on purpose. A single counter bounded by
+    // `plan.length === 0 ? EMPTY_PLAN_RETRIES : 0` re-reads the bound against the
+    // CURRENT plan, so an empty draw that healed to a still-suspect 1-title plan saw
+    // the bound collapse to 0 and skipped the small-plan retry that an identical
+    // 1-title FIRST draw would have received. Same end state, different treatment,
+    // purely because of how it got there.
+    let emptyAttempts = 0;
+    let smallRetryUsed = false;
+    while (isSuspectPlan(planTitles, featureForModel)) {
+        if (planTitles.length === 0) {
+            if (emptyAttempts > EMPTY_PLAN_RETRIES)
+                break;
+            emptyAttempts++;
+        }
+        else {
+            if (smallRetryUsed)
+                break;
+            smallRetryUsed = true;
+        }
         logPlanDebug(cwd, `decompose suspect (${planTitles.length} title(s) for a ${featureForModel.length}-char spec)`
+            + `${emptyAttempts > 1 ? ` — empty retry ${emptyAttempts}` : ''}`
             + ` — raw output: ${listRaw.trim().slice(0, 300)}`);
         const retryRaw = await deps.runChild('auto-decompose', 'read', prependHint(suspectPlanHint(planTitles.length), decomposePrompt));
         const retryTitles = parsePlan(retryRaw);

package/dist/task/coverage-loop.d.ts

@@ -85,6 +85,10 @@ export interface AdoptionDecision {
  *      current plan already owns (non-superset owned-set). This is the monotone
  *      guarantee; it holds regardless of how the un-ownable requirements were
  *      classified, so it backstops the cross-cutting classifier completely.
+ *   2b. WITH requirement signal: reject a retry that grows the plan while covering
+ *      NOTHING new — the tiebreak that makes "ship the best" also mean "ship the
+ *      smallest among equals". Without it the guard is inert against the superset
+ *      the reprompt asks for; see the long note at the branch.
  *   3. WITHOUT requirement signal: fall back to the count floor, and additionally
  *      refuse a retry that leaves MORE areas uncovered than the current plan — so
  *      the no-requirements path also ships the best, not the last.

package/dist/task/coverage-loop.js

@@ -215,6 +215,10 @@ export function droppedCoverage(current, retry) {
  *      current plan already owns (non-superset owned-set). This is the monotone
  *      guarantee; it holds regardless of how the un-ownable requirements were
  *      classified, so it backstops the cross-cutting classifier completely.
+ *   2b. WITH requirement signal: reject a retry that grows the plan while covering
+ *      NOTHING new — the tiebreak that makes "ship the best" also mean "ship the
+ *      smallest among equals". Without it the guard is inert against the superset
+ *      the reprompt asks for; see the long note at the branch.
  *   3. WITHOUT requirement signal: fall back to the count floor, and additionally
  *      refuse a retry that leaves MORE areas uncovered than the current plan — so
  *      the no-requirements path also ships the best, not the last.
@@ -238,6 +242,43 @@ export function decideAdoption(current, retry, hasRequirements) {
                 dropped
             };
         }
+        // Growth must PAY FOR ITSELF. Past this point the retry's owned-set is a
+        // superset, so an equal size means the sets are IDENTICAL — the retry
+        // covers nothing new. Adopting it anyway is how mx5 (2026-07-28) went
+        // 26 → 32 → 60 titles with the owned-set pinned at 27 in all three rounds,
+        // both retries logged as "preserves owned coverage".
+        //
+        // The old rule could not object, by construction: groundedCoverage is
+        // monotone in the title set (titleTokens is a union over titles; df/maxDF
+        // depend only on the quotes), and coverageRepromptHint asks the model for
+        // "every task your previous list already had ... PLUS" — a superset. So
+        // `dropped` is structurally empty whenever the model obeys the hint and the
+        // guard adopted unconditionally (measured: 2000/2000 superset retries
+        // adopted; 563/2000 independently-sampled ones rejected — the guard has
+        // power, just not against the shape the prompt requests).
+        //
+        // REJECT, never break. Rejection keeps the smaller plan and lets the loop
+        // reprompt again; breaking here forfeits a later round that would have
+        // gained (live: 19t/24c → 38t/24c → 40t/25c, where stopping at the tie
+        // loses the 25th requirement). "No gain this round" is not "no gain ever".
+        //
+        // Safety is structural, not statistical: this branch is reachable only when
+        // the retry covers NO MORE than the current plan, so it can never decline a
+        // strictly better one. Live A/B (Qwen3.6-27B, mx5 20KB spec, 24 reps,
+        // precondition 24/24): inflated plans 7/24 → 0/24, Fisher two-sided
+        // p=0.0094; coverage mean 24.58 → 24.79 (higher in 6 reps, lower in 1, and
+        // that one rep never fired this clause); plan size 41.8 → 38.8, which is
+        // NOT significant (sign 15/8, p=0.21) — the win is removing pathological
+        // inflation, not shrinking plans generally.
+        if (retry.covered.size <= current.covered.size
+            && retry.titles.length > current.titles.length) {
+            return {
+                adopt: false,
+                reason: `no coverage gain for +${retry.titles.length - current.titles.length} titles `
+                    + `(${current.covered.size} owned, unchanged)`,
+                dropped: []
+            };
+        }
         return { adopt: true, reason: 'preserves owned coverage', dropped: [] };
     }
     if (retry.missing.length > current.missing.length) {

package/dist/task/decompose-granularity.d.ts

@@ -43,6 +43,18 @@ export declare const MAX_REQUIREMENTS_PER_TASK = 2;
 /**
  * Fewest task titles a plan may have for `ownable` requirements. Zero when the
  * requirement channel produced nothing, which disables every check below.
+ *
+ * Also zero below MIN_REQUIREMENTS_FOR_PLAN_SHAPE, for the reason that constant
+ * already documents: under a handful of requirements the plan is one or two tasks
+ * either way, and the requirement COUNT at that scale is an artifact of extraction
+ * granularity rather than real breadth. Measured (2026-07-28 size smoke): the
+ * 78-char feature "Add a `--version` flag to the CLI that prints the package
+ * version and exits 0" extracted THREE ownable requirements — the flag, the
+ * print, the exit code — yielding a floor of 2 for what is unambiguously one
+ * task. Both arms correctly shipped 1 title, so the floor bought nothing and cost
+ * a split-retry child; had anything ever made it binding it would have forced a
+ * bad split. The same cut governs both because it is the same judgement: the
+ * requirement channel is not load-bearing for shape until a feature has real breadth.
  */
 export declare function granularityFloor(ownable: number): number;
 /** Is this plan too coarse for the requirements it has to carry? */

package/dist/task/decompose-granularity.js

@@ -43,9 +43,23 @@ export const MAX_REQUIREMENTS_PER_TASK = 2;
 /**
  * Fewest task titles a plan may have for `ownable` requirements. Zero when the
  * requirement channel produced nothing, which disables every check below.
+ *
+ * Also zero below MIN_REQUIREMENTS_FOR_PLAN_SHAPE, for the reason that constant
+ * already documents: under a handful of requirements the plan is one or two tasks
+ * either way, and the requirement COUNT at that scale is an artifact of extraction
+ * granularity rather than real breadth. Measured (2026-07-28 size smoke): the
+ * 78-char feature "Add a `--version` flag to the CLI that prints the package
+ * version and exits 0" extracted THREE ownable requirements — the flag, the
+ * print, the exit code — yielding a floor of 2 for what is unambiguously one
+ * task. Both arms correctly shipped 1 title, so the floor bought nothing and cost
+ * a split-retry child; had anything ever made it binding it would have forced a
+ * bad split. The same cut governs both because it is the same judgement: the
+ * requirement channel is not load-bearing for shape until a feature has real breadth.
  */
 export function granularityFloor(ownable) {
-    return ownable <= 0 ? 0 : Math.ceil(ownable / MAX_REQUIREMENTS_PER_TASK);
+    if (ownable < MIN_REQUIREMENTS_FOR_PLAN_SHAPE)
+        return 0;
+    return Math.ceil(ownable / MAX_REQUIREMENTS_PER_TASK);
 }
 /** Is this plan too coarse for the requirements it has to carry? */
 export function isTooCoarse(titles, floor) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.23.0",
+    "version": "0.23.1",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",