@mjasnikovs/pi-task 0.21.10 → 0.22.0

package/dist/shared/child-process.js

@@ -335,6 +335,40 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
             else
                 stdout += chunk;
         });
+        // This accumulation is deliberately unbounded, unlike `discardStdout`
+        // above. The asymmetry was investigated on 2026-07-28 and the "stderr can
+        // overflow V8's max string length" hypothesis is REFUTED at ~5 orders of
+        // magnitude — do not re-open it without new volume evidence.
+        //
+        // Measured ceiling (binary search on `'a'.repeat`, not cited from memory):
+        // node v26.2.0 536,870,888 chars (512 MiB, 2^29-24), bun 1.3.14
+        // 2,147,483,647 (2 GiB). Both throw RangeError, not OOM — node's default
+        // heap is 4192 MiB, well clear of its own string ceiling. If it were ever
+        // reached the severity would be high: a throw in this handler escapes as
+        // an uncaughtException and the enclosing promise never settles (measured),
+        // so it would kill the host, not fail the child.
+        //
+        // Measured volume, real runs not synthetic: the largest single tool output
+        // in a full mx5 run is 5,043 bytes and that whole run's verify-debug.log is
+        // 112,216 bytes. The heaviest commands in the system are far under —
+        // pi-task's own 2,452-test suite emits 162 bytes of stderr, mx5's
+        // prettier+eslint+tsc lint 90, a cached `bun install` 0. Observed max is
+        // ~106,000x below the node ceiling; reaching it inside the 15-min command
+        // bound would need ~596 KB/s sustained on stderr for the full window.
+        //
+        // The structural reason is the population of children that reach here:
+        // `pi` model children (stderr near-empty), `git`, and one
+        // `npm install --loglevel=error`. Genuinely verbose work — test runners,
+        // builds, boot probes — does not use runChild; final-gate.ts spawns its own
+        // and already caps at 8000 chars. So `discardStdout`'s single caller
+        // (docs-core.ts) is not an oversight to mirror: it discards the verbose
+        // stream and KEEPS stderr precisely because stderr is that call's payload.
+        //
+        // A symmetric `discardStderr` would therefore have no caller, and a naive
+        // cap here would be actively unsafe: consumers disagree about which end
+        // carries the cause — phases.ts:474 takes the tail (-500), phases.ts:936
+        // takes the head (0, 300), and child-runner.ts:172 feeds the whole string
+        // into failure classification.
         proc.stderr?.on('data', (d) => {
             lastActivity = Date.now();
             streamWatch?.note();

package/dist/task/auto-orchestrator.js

@@ -42,6 +42,7 @@ import { isYoloMode, yoloPickAnswer, yoloFinalGateChoice, YOLO_STAMP } from './y
 import { configureResearchRun, resumeResearchRun } from '../workers/research-cache.js';
 import { CONTRACT_EXTRACT_PROMPT, parseContractLines, keepGroundedContracts, appendContracts } from './contracts.js';
 import { reconcileTitleSources } from './decompose-fidelity.js';
+import { granularityFloor, granularitySplitHint, isPlanShapeQuestion, isTooCoarse, planShapeIsHostsToAnswer, PLAN_SHAPE_ANSWER } from './decompose-granularity.js';
 import { mandatesTestsInSameChange, rewriteBatchTestPlan } from './batch-test-task.js';
 import { REQUIREMENT_EXTRACT_PROMPT, COVERAGE_MAP_PROMPT, parseRequirementLines, keepGroundedRequirements, capRequirements, writeOwnedRequirements, enumerateObligationPassages, uncoveredPassages, extractionRetryHint, parseCoverageMap, accountCoverage, isCrossCuttingRequirement, appendCarriedRequirements, buildRequirementsLedger } from './requirements.js';
 import { decideAdoption, groundedCoverage } from './coverage-loop.js';
@@ -424,6 +425,54 @@ export async function planAuto(ctx, cwd, feature, deps) {
         taskId: '',
         signal: new AbortController().signal
     }).catch(() => '');
+    // Requirement extraction (mx5 run 11, goal A): grounded requirement units,
+    // extracted from whatever structure the spec has, BEFORE decompose — they ride
+    // into the decompose prompt as a ledger (structure-mirroring can't discharge
+    // them) and drive the per-requirement coverage accounting below.
+    //
+    // Runs BEFORE clarify (it depends only on the inlined feature, never on the
+    // answers) so the plan-shape gate below has a real count to judge with: the
+    // host must not seize the granularity fork on a spec that has no breakdown to
+    // speak of. Best-effort:
+    // a fault leaves reqEntries empty and the whole channel degrades to the old
+    // behavior (one-liners / doc-less features naturally yield few or none).
+    let reqEntries = [];
+    try {
+        // Recall floor: the obligation-marked passages ride into the prompt as a
+        // checklist, and a marked passage that produced NO quote is hard evidence
+        // for one forced re-extraction (measured live: 1/5 extractions missed the
+        // entire marked testing section without this).
+        const passages = enumerateObligationPassages(featureForModel);
+        const extractOnce = async (hint) => keepGroundedRequirements(parseRequirementLines(await deps.runChild('requirement-extract', '', prependHint(hint, REQUIREMENT_EXTRACT_PROMPT(featureForModel, passages)))), featureForModel);
+        reqEntries = await extractOnce(null);
+        const uncovered = uncoveredPassages(passages, reqEntries);
+        if (uncovered.length > 0) {
+            logPlanDebug(cwd, `requirement extraction: ${uncovered.length} obligation-marked passage(s) `
+                + 'uncovered — forcing one re-extraction');
+            const retry = await extractOnce(extractionRetryHint(uncovered));
+            // Union of both grounded passes (keepGrounded dedupes).
+            reqEntries = keepGroundedRequirements([...reqEntries, ...retry], featureForModel);
+        }
+        // Bound with marked-passage priority — a plain first-N cap truncates the
+        // doc's tail sections (measured live: an eager model fills 40 top-down).
+        reqEntries = capRequirements(reqEntries, passages, featureForModel);
+        logPlanDebug(cwd, `requirement extraction: ${reqEntries.length} grounded requirement(s) kept`);
+    }
+    catch {
+        // best-effort channel
+    }
+    // Granularity floor (mx5 Jul 25 vs Jul 27): the plan's task COUNT was being set
+    // by an auto-resolved clarify line the user never saw — the same spec planned
+    // into 41 tasks one day and 11 the next, with identical code. Derive the floor
+    // from the requirements a task can own, so an unreviewable "one task per
+    // milestone" decision cannot collapse the plan; it also gates whether the
+    // plan-shape fork below is the host's to answer at all. 0 ownable ⇒ no channel.
+    const ownableRequirements = reqEntries.filter(e => !isCrossCuttingRequirement(e.quote)).length;
+    const coarseFloor = granularityFloor(ownableRequirements);
+    if (coarseFloor > 0) {
+        logPlanDebug(cwd, `granularity floor: ${ownableRequirements} ownable requirement(s) ⇒ at least `
+            + `${coarseFloor} task(s)`);
+    }
     const answers = [];
     // Plain text of every question already shown, for the duplicate backstop.
     const askedQuestions = [];
@@ -458,6 +507,19 @@ export async function planAuto(ctx, cwd, feature, deps) {
         const shownQ = renderInlineMarkdown(question, theme);
         const plainQ = stripInlineMarkdown(question);
         askedQuestions.push(plainQ);
+        // PLAN SHAPE is the host's call, not the triage's (mx5 41→11 tasks on the
+        // same spec, same base commit, same code — see decompose-granularity.ts).
+        // The triage answers this fork for itself in 8/8 live reps and stamps it
+        // "already settled by the spec" while the spec settles no such thing, so the
+        // single most load-bearing decision in a run was an invisible coin flip.
+        // Answer it deterministically instead: same channel, same transcript, but a
+        // fixed value the user can read in the AUTO file and override next run.
+        if (planShapeIsHostsToAnswer(ownableRequirements) && isPlanShapeQuestion(plainQ)) {
+            logPlanDebug(cwd, `plan-shape question answered host-side (not the triage): ${plainQ.replace(/\s+/g, ' ').slice(0, 120)}`);
+            answers.push(`Q${answers.length + 1}: ${plainQ}\n`
+                + `A${answers.length + 1}: ${PLAN_SHAPE_ANSWER} (host-set — plan granularity is not left to chance)`);
+            continue;
+        }
         // Answer-side triage (grill parity): if the inlined spec already settles
         // this question, auto-resolve it and never show it. The resolved value is
         // recorded so decompose sees the decision and the next gen call's priorQA
@@ -544,37 +606,6 @@ export async function planAuto(ctx, cwd, feature, deps) {
         ctx.ui.notify('No clarifying questions needed — planning tasks…', 'info');
     }
     const clarifications = answers.join('\n');
-    // Requirement extraction (mx5 run 11, goal A): grounded requirement units,
-    // extracted from whatever structure the spec has, BEFORE decompose — they ride
-    // into the decompose prompt as a ledger (structure-mirroring can't discharge
-    // them) and drive the per-requirement coverage accounting below. Best-effort:
-    // a fault leaves reqEntries empty and the whole channel degrades to the old
-    // behavior (one-liners / doc-less features naturally yield few or none).
-    let reqEntries = [];
-    try {
-        // Recall floor: the obligation-marked passages ride into the prompt as a
-        // checklist, and a marked passage that produced NO quote is hard evidence
-        // for one forced re-extraction (measured live: 1/5 extractions missed the
-        // entire marked testing section without this).
-        const passages = enumerateObligationPassages(featureForModel);
-        const extractOnce = async (hint) => keepGroundedRequirements(parseRequirementLines(await deps.runChild('requirement-extract', '', prependHint(hint, REQUIREMENT_EXTRACT_PROMPT(featureForModel, passages)))), featureForModel);
-        reqEntries = await extractOnce(null);
-        const uncovered = uncoveredPassages(passages, reqEntries);
-        if (uncovered.length > 0) {
-            logPlanDebug(cwd, `requirement extraction: ${uncovered.length} obligation-marked passage(s) `
-                + 'uncovered — forcing one re-extraction');
-            const retry = await extractOnce(extractionRetryHint(uncovered));
-            // Union of both grounded passes (keepGrounded dedupes).
-            reqEntries = keepGroundedRequirements([...reqEntries, ...retry], featureForModel);
-        }
-        // Bound with marked-passage priority — a plain first-N cap truncates the
-        // doc's tail sections (measured live: an eager model fills 40 top-down).
-        reqEntries = capRequirements(reqEntries, passages, featureForModel);
-        logPlanDebug(cwd, `requirement extraction: ${reqEntries.length} grounded requirement(s) kept`);
-    }
-    catch {
-        // best-effort channel
-    }
     // Artifact-production closure, plan side (mx5 run 13, PROMPT 2): runtime
     // files the spec REFERENCES (server snippets, prose "serve the built
     // index.html") that neither its file tree, its parsed build outputs, nor the
@@ -636,6 +667,20 @@ export async function planAuto(ctx, cwd, feature, deps) {
     const listRaw = await deps.runChild('auto-decompose', 'read', decomposePrompt);
     let planTitles = parsePlan(listRaw);
     logPlanDebug(cwd, `decompose produced ${planTitles.length} title(s)`);
+    // BRACES for the floor: the prompt clause alone is a preference the model can
+    // ignore, so a plan under the floor is sent back ONCE to be split (never
+    // regenerated — a fresh roll can drop a covered area, mx5 run 12). Longer plan
+    // wins; a still-coarse plan falls through to the coverage judge as before, so
+    // this can never block planning.
+    if (isTooCoarse(planTitles.length, coarseFloor)) {
+        logPlanDebug(cwd, `plan under the granularity floor (${planTitles.length} < ${coarseFloor}) — `
+            + 'reprompting once to split');
+        const splitRaw = await deps.runChild('auto-decompose', 'read', prependHint(granularitySplitHint(planTitles.length, ownableRequirements), decomposePrompt));
+        const splitTitles = parsePlan(splitRaw);
+        logPlanDebug(cwd, `granularity split-retry produced ${splitTitles.length} title(s)`);
+        if (splitTitles.length > planTitles.length)
+            planTitles = splitTitles;
+    }
     // Distrust floor (see isSuspectPlan): a ≤2-title plan for a multi-KB spec is
     // regenerated once BEFORE the judge runs — the judge cannot be trusted to
     // catch it (3/10 live false-pass) and a hinted retry heals it reliably

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

@@ -16,6 +16,12 @@ export declare const AUTO_CLARIFY_PROMPT: (feature: string, priorQA: string) =>
  * `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.
+ *
+ * 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.
  */
 export declare const AUTO_DECOMPOSE_PROMPT: (feature: string, clarifications: string, requirementsLedger?: string, noBatchTests?: boolean) => string;
 /**

package/dist/task/auto-prompts.js

@@ -76,6 +76,12 @@ NONE`;
  * `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.
+ *
+ * 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.
  */
 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

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

@@ -0,0 +1,98 @@
+/**
+ * decompose-granularity — the deterministic FLOOR on how finely /task-auto cuts
+ * a feature into tasks.
+ *
+ * The failure this closes (mx5, Jul 25 vs Jul 27): the SAME design doc, from the
+ * SAME base commit, with a byte-identical planning path, planned once into 41
+ * tasks and once into 11. The whole 4x difference is one line of clarify text.
+ * /task-auto's clarify head asks a plan-shape question first ("one task per
+ * milestone, or split smaller?" — 8/8 live reps), the answer-side triage
+ * auto-resolves it 8/8 and stamps it "already settled by the spec", so the user
+ * never sees the fork; and the answer decides the whole plan. Live A/B, run 18's
+ * transcript with ONLY that line swapped (n=8/arm): coarse mean 11.4 titles vs
+ * fine mean 28.6, 63.5/64 pairwise wins, p<0.001.
+ *
+ * The spec does NOT settle it. mx5's §12 is titled "Build order (milestones)" —
+ * an ORDER, 9 items, not a task breakdown. So the plan's granularity, the single
+ * highest-leverage decision in a run (each title is handed to its own pipeline
+ * that researches and specs it alone), was being decided by a coin flip nobody
+ * could see, review, or reproduce.
+ *
+ * Surfacing the question does not fix it: under YOLO/unattended `yoloPickAnswer`
+ * takes the recommendation, which is the same stochastic line. The fix has to be
+ * host-side and deterministic, so this module derives the floor from integers the
+ * run already has — the count of grounded requirements that a task can OWN.
+ *
+ *   floor = ceil(ownable requirements / MAX_REQUIREMENTS_PER_TASK)
+ *
+ * MAX_REQUIREMENTS_PER_TASK = 2 is anchored on the two real mx5 plans, not on
+ * taste: the 41-task plan carried 0.8 ownable requirements per task, the collapsed
+ * 11-task plan carried 2.8. A ceiling of 2 sits between them — it rejects the
+ * collapse without demanding the finest plan ever observed.
+ *
+ * Spec-shape-agnostic: the only inputs are two integers. A CLI, a library, a
+ * refactor, a docs job all flow through the same arithmetic, and a feature with
+ * no extracted requirements (a one-liner, a doc-less request) yields floor 0 —
+ * the whole channel degrades to exactly the previous behaviour.
+ */
+/**
+ * The most distinct grounded requirements one task may carry before the plan is
+ * judged too coarse. See the module docstring for the mx5 anchoring.
+ */
+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.
+ */
+export declare function granularityFloor(ownable: number): number;
+/** Is this plan too coarse for the requirements it has to carry? */
+export declare function isTooCoarse(titles: number, floor: number): boolean;
+/**
+ * Fewest ownable requirements a feature needs before the host takes the
+ * plan-shape fork away from the triage.
+ *
+ * Below this the fork is not load-bearing — the whole plan is one or two tasks
+ * either way — and seizing it does harm: live smoke over 24 prompts, the host
+ * directive turned "rename the `foo()` helper across the repo" (1 requirement)
+ * into a 6-task plan and "add a .editorconfig" (4) into 4. Every case at or above
+ * this cut planned inside its expected range. So: a feature with real breadth
+ * gets the deterministic answer, a chore keeps the old triage path untouched.
+ */
+export declare const MIN_REQUIREMENTS_FOR_PLAN_SHAPE = 5;
+/** Does this feature have enough distinct deliverables for granularity to matter? */
+export declare function planShapeIsHostsToAnswer(ownable: number): boolean;
+/**
+ * Does this clarify question decide how finely the feature is CUT into tasks?
+ *
+ * Deterministic and narrow on purpose. It must fire on the fork the triage keeps
+ * answering for itself ("follow the milestones as-is, or split more granularly?")
+ * and stay off ordinary scope questions — an over-eager classifier would replace
+ * a real user decision with the host's. Matched against the plain-text question.
+ */
+export declare function isPlanShapeQuestion(question: string): boolean;
+/**
+ * BELT — the host's own answer to that fork, recorded in the clarify transcript in
+ * place of the triage's.
+ *
+ * WHY A CLARIFICATION AND NOT A DECOMPOSE RULE. Both were measured live. As a
+ * RULES line replacing "prefer a handful of substantial tasks", the same directive
+ * removed the collapse but destroyed plan-size control: 66, then 81 and 85 titles
+ * for a spec whose healthy plan is ~30, plus one decompose child that blew the
+ * model's 120k context window and killed the planning phase (the baseline produced
+ * no such failure in 27 reps). Naming a target count made it worse, not better.
+ * In the CLARIFICATIONS block, with the "prefer a handful" counterweight left
+ * intact, the identical directive held 20–39 titles across 16 reps. The channel is
+ * part of the lever, not a detail.
+ *
+ * Deliberately count-free: the spec-derived floor stays host-side, where it is
+ * enforced silently and cannot be chased.
+ */
+export declare const PLAN_SHAPE_QUESTION = "How finely should this feature be split into tasks?";
+export declare const PLAN_SHAPE_ANSWER: string;
+/**
+ * BRACES — the reprompt when the returned plan lands under the floor. Also
+ * countless, for the reason above: it asks for a SPLIT of the plan in hand rather
+ * than a fresh roll (a regeneration is a new stochastic draw over the whole plan
+ * and can drop an area the current one covers — mx5 run 12).
+ */
+export declare function granularitySplitHint(titles: number, ownable: number): string;

package/dist/task/decompose-granularity.js

@@ -0,0 +1,124 @@
+/**
+ * decompose-granularity — the deterministic FLOOR on how finely /task-auto cuts
+ * a feature into tasks.
+ *
+ * The failure this closes (mx5, Jul 25 vs Jul 27): the SAME design doc, from the
+ * SAME base commit, with a byte-identical planning path, planned once into 41
+ * tasks and once into 11. The whole 4x difference is one line of clarify text.
+ * /task-auto's clarify head asks a plan-shape question first ("one task per
+ * milestone, or split smaller?" — 8/8 live reps), the answer-side triage
+ * auto-resolves it 8/8 and stamps it "already settled by the spec", so the user
+ * never sees the fork; and the answer decides the whole plan. Live A/B, run 18's
+ * transcript with ONLY that line swapped (n=8/arm): coarse mean 11.4 titles vs
+ * fine mean 28.6, 63.5/64 pairwise wins, p<0.001.
+ *
+ * The spec does NOT settle it. mx5's §12 is titled "Build order (milestones)" —
+ * an ORDER, 9 items, not a task breakdown. So the plan's granularity, the single
+ * highest-leverage decision in a run (each title is handed to its own pipeline
+ * that researches and specs it alone), was being decided by a coin flip nobody
+ * could see, review, or reproduce.
+ *
+ * Surfacing the question does not fix it: under YOLO/unattended `yoloPickAnswer`
+ * takes the recommendation, which is the same stochastic line. The fix has to be
+ * host-side and deterministic, so this module derives the floor from integers the
+ * run already has — the count of grounded requirements that a task can OWN.
+ *
+ *   floor = ceil(ownable requirements / MAX_REQUIREMENTS_PER_TASK)
+ *
+ * MAX_REQUIREMENTS_PER_TASK = 2 is anchored on the two real mx5 plans, not on
+ * taste: the 41-task plan carried 0.8 ownable requirements per task, the collapsed
+ * 11-task plan carried 2.8. A ceiling of 2 sits between them — it rejects the
+ * collapse without demanding the finest plan ever observed.
+ *
+ * Spec-shape-agnostic: the only inputs are two integers. A CLI, a library, a
+ * refactor, a docs job all flow through the same arithmetic, and a feature with
+ * no extracted requirements (a one-liner, a doc-less request) yields floor 0 —
+ * the whole channel degrades to exactly the previous behaviour.
+ */
+/**
+ * The most distinct grounded requirements one task may carry before the plan is
+ * judged too coarse. See the module docstring for the mx5 anchoring.
+ */
+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.
+ */
+export function granularityFloor(ownable) {
+    return ownable <= 0 ? 0 : Math.ceil(ownable / MAX_REQUIREMENTS_PER_TASK);
+}
+/** Is this plan too coarse for the requirements it has to carry? */
+export function isTooCoarse(titles, floor) {
+    return floor > 0 && titles < floor;
+}
+/**
+ * Fewest ownable requirements a feature needs before the host takes the
+ * plan-shape fork away from the triage.
+ *
+ * Below this the fork is not load-bearing — the whole plan is one or two tasks
+ * either way — and seizing it does harm: live smoke over 24 prompts, the host
+ * directive turned "rename the `foo()` helper across the repo" (1 requirement)
+ * into a 6-task plan and "add a .editorconfig" (4) into 4. Every case at or above
+ * this cut planned inside its expected range. So: a feature with real breadth
+ * gets the deterministic answer, a chore keeps the old triage path untouched.
+ */
+export const MIN_REQUIREMENTS_FOR_PLAN_SHAPE = 5;
+/** Does this feature have enough distinct deliverables for granularity to matter? */
+export function planShapeIsHostsToAnswer(ownable) {
+    return ownable >= MIN_REQUIREMENTS_FOR_PLAN_SHAPE;
+}
+/**
+ * Does this clarify question decide how finely the feature is CUT into tasks?
+ *
+ * Deterministic and narrow on purpose. It must fire on the fork the triage keeps
+ * answering for itself ("follow the milestones as-is, or split more granularly?")
+ * and stay off ordinary scope questions — an over-eager classifier would replace
+ * a real user decision with the host's. Matched against the plain-text question.
+ */
+export function isPlanShapeQuestion(question) {
+    const q = question.toLowerCase();
+    // The fork has to be about the BREAKDOWN itself…
+    const aboutBreakdown = /\b(task breakdown|break(ing)? (it|this|the \w+) down|decompos\w*|split\w*|subdivid\w*|granular\w*|fine[- ]grained|one task per|task per (milestone|section|step|phase|feature)|per[- ](milestone|route|component|page|module)\b|(own|separate|standalone|dedicated|self[- ]contained|single)\s+(\w+\s+)?tasks?\b)/.test(q);
+    if (!aboutBreakdown)
+        return false;
+    // …and offer a coarse/fine choice over the plan's own units.
+    return /\b(milestone|section|step|phase|task|tasks)\b/.test(q);
+}
+/**
+ * BELT — the host's own answer to that fork, recorded in the clarify transcript in
+ * place of the triage's.
+ *
+ * WHY A CLARIFICATION AND NOT A DECOMPOSE RULE. Both were measured live. As a
+ * RULES line replacing "prefer a handful of substantial tasks", the same directive
+ * removed the collapse but destroyed plan-size control: 66, then 81 and 85 titles
+ * for a spec whose healthy plan is ~30, plus one decompose child that blew the
+ * model's 120k context window and killed the planning phase (the baseline produced
+ * no such failure in 27 reps). Naming a target count made it worse, not better.
+ * In the CLARIFICATIONS block, with the "prefer a handful" counterweight left
+ * intact, the identical directive held 20–39 titles across 16 reps. The channel is
+ * part of the lever, not a detail.
+ *
+ * Deliberately count-free: the spec-derived floor stays host-side, where it is
+ * enforced silently and cannot be chased.
+ */
+export const PLAN_SHAPE_QUESTION = 'How finely should this feature be split into tasks?';
+export const PLAN_SHAPE_ANSWER = 'subdivide into smaller per-deliverable tasks — one task per route, page, screen,'
+    + ' module, schema, or pipeline stage — rather than one task per milestone or spec'
+    + ' section. A milestone or section that spans several deliverables becomes several'
+    + ' tasks. (host-set: the spec fixes the build ORDER, not the task breakdown, so'
+    + ' pi-task settles granularity deterministically instead of guessing per run)';
+/**
+ * BRACES — the reprompt when the returned plan lands under the floor. Also
+ * countless, for the reason above: it asks for a SPLIT of the plan in hand rather
+ * than a fresh roll (a regeneration is a new stochastic draw over the whole plan
+ * and can drop an area the current one covers — mx5 run 12).
+ */
+export function granularitySplitHint(titles, ownable) {
+    return (`[SYSTEM NOTE: your plan of ${titles} task(s) is too coarse for the`
+        + ` ${ownable} required contents this spec lists — several tasks each bundle work`
+        + ' that belongs in separate ones. Emit the SAME plan with those tasks SPLIT: keep'
+        + ' every task that is already one deliverable, and break each one that bundles'
+        + ' several routes, pages, modules, or pipeline stages into one task per piece.'
+        + ' Do not drop anything, do not merge, do not pad with trivia — split what is'
+        + ' already there.]');
+}

package/package.json

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