@mjasnikovs/pi-task 0.23.0 → 0.24.0

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/dist/task/requirements.d.ts

@@ -31,7 +31,18 @@ export declare function keepGroundedRequirements(entries: RequirementEntry[], so
  * never the model-authored anchor text. Without `sourceDoc` (or for quotes that
  * cannot be located) the fill degrades to the old given-order behavior.
  */
-export declare function capRequirements(entries: RequirementEntry[], passages: string[], sourceDoc?: string): RequirementEntry[];
+export declare function capRequirements(entries: RequirementEntry[], passages: string[], sourceDoc?: string, 
+/** A/B seam: `false` reproduces the pre-budget rule, so an offline harness can
+ *  score the shipped rule against the one it replaced without transcribing
+ *  sectionFairFill and letting the copy drift. Production never passes it. */
+deprioritiseLowValue?: boolean): RequirementEntry[];
+/**
+ * Quotes that pass the grounding guard (verbatim substring of the doc) but state
+ * no obligation. There is no obligation test anywhere else in the pipeline —
+ * `keepGroundedRequirements` only checks the quote really appears in the source,
+ * so any sentence at all survives it and precision rests entirely on the model.
+ */
+export declare function isLowValueQuote(quote: string): boolean;
 /**
  * DETERMINISTIC RECALL FLOOR (same medicine as the launch-contract checklist):
  * paragraphs carrying an obligation marker (word-bounded "required"/"must").

package/dist/task/requirements.js

@@ -98,7 +98,11 @@ export function keepGroundedRequirements(entries, sourceDoc) {
  * never the model-authored anchor text. Without `sourceDoc` (or for quotes that
  * cannot be located) the fill degrades to the old given-order behavior.
  */
-export function capRequirements(entries, passages, sourceDoc) {
+export function capRequirements(entries, passages, sourceDoc, 
+/** A/B seam: `false` reproduces the pre-budget rule, so an offline harness can
+ *  score the shipped rule against the one it replaced without transcribing
+ *  sectionFairFill and letting the copy drift. Production never passes it. */
+deprioritiseLowValue = true) {
     if (entries.length <= MAX_REQUIREMENTS)
         return entries;
     const norms = passages.map(normalise);
@@ -109,7 +113,114 @@ export function capRequirements(entries, passages, sourceDoc) {
     const marked = entries.filter(covers);
     const rest = entries.filter(e => !covers(e));
     const budget = MAX_REQUIREMENTS - Math.min(marked.length, MAX_REQUIREMENTS);
-    return [...marked.slice(0, MAX_REQUIREMENTS), ...sectionFairFill(rest, budget, sourceDoc)];
+    // The low-value filter applies to the UNMARKED remainder only. Quoting an
+    // obligation-marked passage is the pipeline's existing, validated evidence
+    // that a quote states an obligation, and it outranks any lexical heuristic:
+    // "MUST log every request" is 22 characters and every length-based rule reads
+    // it as a fragment. Filtering ahead of the marked/rest split deleted it.
+    //
+    // INSURANCE, not a measured win on mx5: across both 30-run pools exactly one
+    // distinct quote per pool is low-value AND marked, and it is a genuinely
+    // truncated one. The layering matters for specs whose obligations are SHORT,
+    // which mx5's are not. Do not cite it as the reason tail coverage holds —
+    // tail coverage is identical with the filter applied before the split.
+    const pool = deprioritiseLowValue ? budgetedByObligation(rest, budget, sourceDoc) : rest;
+    return [...marked.slice(0, MAX_REQUIREMENTS), ...sectionFairFill(pool, budget, sourceDoc)];
+}
+/** Longest a dependency-pin row can be before it is presumed to carry an
+ *  obligation after the pin. Real pins in the measured corpus run 32..48 chars;
+ *  the pin-prefixed lines that DO obligate ("TypeScript `6.0.3` — one strict
+ *  `tsconfig.json`: `strict`, `noUncheckedIndexedAccess`, …") run 130..260. */
+const MAX_PIN_LENGTH = 80;
+/** Cut mid-expression: an unbalanced fence or bracket, or a trailing separator.
+ *  NOT `;` — a complete clause legitimately ends with one, and dropping on `;`
+ *  discarded a runnable `lint` = `prettier … && eslint … && tsc --noEmit` line. */
+function isTruncatedQuote(q) {
+    if ((q.match(/`/g) ?? []).length % 2 === 1)
+        return true;
+    for (const [open, close] of [
+        ['(', ')'],
+        ['[', ']'],
+        ['{', '}']
+    ]) {
+        const o = (q.match(new RegExp(`\\${open}`, 'g')) ?? []).length;
+        const c = (q.match(new RegExp(`\\${close}`, 'g')) ?? []).length;
+        if (o > c)
+            return true;
+    }
+    return /[,:([{]\s*$/.test(q.trim());
+}
+/** A bare version row — data, not an obligation. Length-gated, see MAX_PIN_LENGTH. */
+function isDependencyPin(q) {
+    const t = q.trim().replace(/^\*\*|\*\*$/g, '');
+    if (t.length > MAX_PIN_LENGTH)
+        return false;
+    return /^\**[`*]?[\w@/-]+[`*]?\**\s*[`']?\d+\.\d+/.test(t);
+}
+/** A DDL/schema row: `col type …`. */
+function isSchemaRow(q) {
+    return /^\s*[\w_]+\s+(?:uuid|text|int|integer|bigint|boolean|timestamptz|bytea|jsonb|numeric|smallint)\b/i.test(q);
+}
+/** Too short to state an obligation. MIN_QUOTE_LENGTH (6) admits "Contact
+ *  seller"; a clause needs a subject and a predicate. */
+function isQuoteFragment(q) {
+    const t = q.trim();
+    return t.length < 25 || t.split(/\s+/).length < 4;
+}
+/**
+ * Quotes that pass the grounding guard (verbatim substring of the doc) but state
+ * no obligation. There is no obligation test anywhere else in the pipeline —
+ * `keepGroundedRequirements` only checks the quote really appears in the source,
+ * so any sentence at all survives it and precision rests entirely on the model.
+ */
+export function isLowValueQuote(quote) {
+    return (isTruncatedQuote(quote)
+        || isDependencyPin(quote)
+        || isSchemaRow(quote)
+        || isQuoteFragment(quote));
+}
+/**
+ * Deprioritise obligation-free quotes, but only as far as the BUDGET requires.
+ *
+ * Measured (mx5, 20402-char spec, two independent 30-run extraction pools): the
+ * extractor's single-pass yield swings 20..160 for byte-identical input, and the
+ * padding crowds real obligations out of the 40 that ship — high-yield runs land
+ * FEWER critical obligations than low-yield ones. Critical obligations reaching
+ * the shipped list go 8.50 → 9.37 of 16 on the design pool (10 runs better, 0
+ * worse, p=0.0020) and 7.70 → 8.43 on the confirmation pool (12 / 0, p=0.0005).
+ *
+ * BUDGETED, not absolute. Below the cap no slot is contested, so dropping there
+ * destroys information and buys nothing; a run that filtered 55 quotes down to 20
+ * lost its only carrier of the Argon2id obligation — a DDL row that was correctly
+ * classified as one — while 20 slots sat empty. So the low-value entries come back
+ * in source-doc order until the list reaches the cap.
+ *
+ * Absolute filtering scored marginally higher on raw count (24 gains vs 22 across
+ * both pools) and was rejected anyway: its extra gains are one more obligation in
+ * an already-populated list, while its one loss is an obligation vanishing from a
+ * run outright. Those are not the same size of mistake.
+ *
+ * Doc order for the restore is the neutral choice: which entries return only
+ * matters when more were dropped than there are free slots, and ordering by
+ * anything fitted to an observed loss would be tuning the rule to one pool.
+ */
+function budgetedByObligation(entries, budget, sourceDoc) {
+    const keep = entries.filter(e => !isLowValueQuote(e.quote));
+    if (keep.length >= budget)
+        return keep;
+    const at = (e) => {
+        if (!sourceDoc)
+            return Number.MAX_SAFE_INTEGER;
+        const i = sourceDoc.indexOf(e.quote.trim());
+        return i < 0 ? Number.MAX_SAFE_INTEGER : i;
+    };
+    const restored = entries
+        .filter(e => isLowValueQuote(e.quote))
+        .map((e, given) => ({ e, at: at(e), given }))
+        .sort((x, y) => x.at - y.at || x.given - y.given)
+        .slice(0, budget - keep.length)
+        .map(x => x.e);
+    return [...keep, ...restored];
 }
 /** The doc split into heading-delimited sections, each pre-normalised for
  *  containment tests. Text before the first heading is its own section. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.23.0",
+    "version": "0.24.0",
     "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",