@mjasnikovs/pi-task 0.38.29 → 0.38.30

package/dist/task/auto-orchestrator.js

@@ -2,8 +2,10 @@
  * /task-auto — plans a feature into a resumable list of task titles, then runs
  * each title through the existing single-task pipeline one at a time.
  *
- * This module currently holds the planning half (AutoDeps + planAuto). The run
- * loop, command handlers, and defaultDeps are added by the next task.
+ * The whole command lives here: the planning half (orient → elicit → decompose →
+ * cover → planAuto), the run loop (runAutoLoop), the production dependency table
+ * (defaultDeps), and the three command handlers registerTaskAuto wires up —
+ * /task-auto, /task-auto-resume and /task-auto-cancel.
  */
 import { existsSync } from 'node:fs';
 import * as fsp from 'node:fs/promises';
@@ -53,7 +55,7 @@ import { findSpecDanglingArtifacts, titlesCoverArtifact, danglingMissingText, da
 import { LAUNCH_EXTRACT_PROMPT, enumerateScriptCandidates, parseScriptLines, keepGroundedScripts, appendDeclaredScripts } from './launch-contract.js';
 // Hard ceiling on clarify questions per feature. The loop is open-ended (it stops
 // when the model emits NONE), but a model that never says NONE would otherwise
-// barrage the user — the real mx5 run asked 10, several of them redundant.
+// barrage the user with redundant questions.
 const MAX_CLARIFY_QUESTIONS = 8;
 // Bounded coverage-triage rounds after decompose: judge → reprompt-with-missing
 // → judge again, at most. Two rounds so one flaky retry doesn't end the gate,
@@ -80,30 +82,32 @@ function coverageRepromptHint(missing) {
         + 'the areas above. Output every task, one "- [ ] " line each, nothing else.]');
 }
 // Deterministic distrust floor for the coverage gate. The gate's judge is the
-// same stochastic model as the decompose call it guards, and live (mx5 2026-07-08,
-// A/B N=10) it rubber-stamps a 1-task plan for an 18KB spec 3/10 times — always
-// as the bare "COVERAGE: COMPLETE" line, which is byte-identical to a legitimate
-// verdict, so the rubber-stamp is NOT detectable from the judge's output. The
+// same stochastic model as the decompose call it guards, and it will sometimes
+// rubber-stamp a one-task plan for a whole design document — as the bare
+// "COVERAGE: COMPLETE" line, byte-identical to a legitimate verdict, so the
+// rubber-stamp is NOT detectable from the judge's output. The
 // distrust signal must come from the input: a plan this small for a spec this
-// large is near-certainly the known degenerate-decompose flake (healthy runs on
-// the same inputs produce 10–30 titles). The floor only ever forces a REGENERATION
-// — it never rejects a plan on count alone (the v0.13.34 objection), so a model
-// that insists twice still ships its small plan, with a warning.
+// large is near-certainly a degenerate generation rather than a real plan. The
+// floor only ever forces a REGENERATION — it never rejects a plan on count alone,
+// so a model that insists twice still ships its small plan, with a warning. Nine
+// tests pin the behaviour, including that a still-suspect plan ships and that a
+// shorter retry keeps the original list.
 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).
+ * hinted retry heals a small-but-nonempty plan; an empty generation is a harder
+ * fault that can recur back-to-back, and falling through with zero titles aborts
+ * the whole run rather than merely shipping a thin plan — so it is worth more
+ * than one roll of the dice.
  */
 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
+ * size. A predicate opening with `titles.length > 0` lets zero titles escape
+ * entirely: not "suspect", so the suspect-retry never fires, the coverage loop
+ * breaks immediately on `titles.length === 0`, and the run aborts 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.
  */
@@ -129,41 +133,43 @@ const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
 // [^\s]+ above would otherwise swallow into the path. Left unstripped, the
 // resulting "design.md," resolves to no file, expansion is silently skipped, and
 // the planner reasons over a one-line "Implement @design.md" with NO spec inline
-// → it fabricates generic questions/tasks the spec never called for (validated:
-// a stray comma turned a 32KB design into a contentless prompt). None of these
-// chars are legitimate trailing characters of a referenced doc path.
+// → it fabricates generic questions and tasks the spec never called for.
+//
+// Measured against a real file: the greedy token from "Implement @design.md,
+// reuse the parser" is `design.md,`, which does not exist; stripped, `design.md`
+// does. None of these chars are legitimate trailing characters of a doc path.
 const MENTION_TRAILING_PUNCT = /[.,;:!?)\]}>"']+$/;
 /** The cleaned path token of an @-mention: greedy match minus trailing prose punctuation. */
 function mentionPath(token) {
     return token.replace(MENTION_TRAILING_PUNCT, '');
 }
-/**
- * Fire-and-forget debug line for the PLAN phase (clarify/decompose), which runs
- * before any task file — hence any per-task `TASK_XXXX-debug.log` — exists. Writes
- * to `.pi-tasks/plan-debug.log`; the `*-debug.log` suffix keeps it grep-compatible
- * with the per-task logs. Never throws (mkdir + append are best-effort).
- *
- * Every call site here records a plan DECISION (how many titles a round produced,
- * whether a retry was adopted, which clarify answer was auto-resolved), so all of
- * them are `'event'` — this file carries no model chatter and survives at the
- * default level. It is also the only channel the plan phase has: it runs before
- * any task file, hence any `TASK_NNNN-debug.log`, exists.
- */
 /**
  * Every plan-debug write not yet on disk, chained.
  *
  * Fire-and-forget is right for production — a plan must never wait on its own
- * trail — but it leaves nothing to synchronise on, and the twelve tests that
- * read `plan-debug.log` back were racing the append that writes it. They failed
- * intermittently on ENOENT, ~4ms in, at a rate that moved with how many other
- * files the suite was running beside them. Chaining also serialises concurrent
- * appends, which is what keeps a line whole.
+ * trail — but it leaves nothing to synchronise on, so a test that reads
+ * `plan-debug.log` back races the append that writes it and fails on ENOENT.
+ * Chaining gives {@link flushPlanDebug} something to await, and it also
+ * serialises concurrent appends, which is what keeps a line whole.
  */
 let planDebugChain = Promise.resolve();
 /** Wait for every plan-debug line written so far to reach disk. Tests only. */
 export function flushPlanDebug() {
     return planDebugChain;
 }
+/**
+ * Fire-and-forget debug line for the PLAN phase (clarify/decompose). It is the
+ * only trail that phase has: planning runs before any task file exists, so there
+ * is no per-task `TASK_NNNN-debug.log` to write into yet. This goes to
+ * `.pi-tasks/plan-debug.log`, whose `*-debug.log` suffix matches the pattern
+ * debug-log.ts documents, so one grep still finds every log. Never throws — the
+ * mkdir and the append are both best-effort.
+ *
+ * Every call site records a plan DECISION (how many titles a round produced,
+ * whether a retry was adopted, which clarify answer was auto-resolved), so all of
+ * them are `'event'` and survive at the default level. No model chatter reaches
+ * this file.
+ */
 function logPlanDebug(cwd, msg) {
     if (!shouldLogDebug('event', debugLogLevel()))
         return;
@@ -205,8 +211,8 @@ async function triageClarifyQuestion(deps, cwd, featureForModel, existingFilesBl
         // manifest/config content) so a "scaffold/create/from scratch" question is
         // auto-resolved as an in-place UPDATE that PRESERVES what is on disk —
         // instead of "greenfield, from scratch", which the spec-only triage emitted
-        // 13/15 of the time and would mint a destructive decompose decision that can
-        // outrank refine's preserve directive (A/B live: 2/15 → 14/15 preserve).
+        // most of the time, minting a destructive decompose decision that can
+        // outrank refine's preserve directive.
         // Empty (greenfield repo / orientation off) → byte-identical to before.
         const source = existingFilesBlock.length > 0 ?
             `${existingFilesBlock}\n\n${featureForModel}`
@@ -293,19 +299,20 @@ export async function readableMentions(cwd, feature) {
 const DECISIONS_RE = /\s*\[decisions:\s*(.+?)\]\s*$/i;
 /**
  * Thread the feature's spec references AND any per-task decisions into every
- * decomposed task title. A title is ALL a per-task pipeline ever sees, so both
- * the design doc the feature pointed at and the user's clarification choices have
- * to ride along or they're invisible downstream — this is how an "Implement
- * @design.md" run built a generic `posts` table the spec never mentioned, and how
- * a "do not use vite" clarification got silently overridden by the doc's own
- * vite.config.ts.
+ * decomposed task title. A title is ALL a per-task pipeline ever sees, so both the
+ * design doc the feature pointed at and the user's clarification choices have to
+ * ride along or they are invisible downstream — a task that cannot see the doc
+ * invents its own schema, and one that cannot see "do not use vite" is overridden
+ * by whatever the doc's own config says.
+ *
+ * Precedence is the crux: a clarification is a CORRECTION to a possibly stale spec
+ * doc, so the decisions clause is marked as overriding the doc while the doc stays
+ * authoritative for everything the decisions do not touch. The emitted order puts
+ * decisions first, then the spec ref. Decompose scopes each decision to the tasks
+ * it governs, so most titles carry none.
  *
- * Precedence is the crux: a clarification is a CORRECTION to a (possibly stale)
- * spec doc, so the decisions clause is marked as overriding the doc, while the doc
- * stays authoritative for everything the decisions don't touch. Decompose scopes
- * each decision to the task(s) it governs, so most titles carry none. No readable
- * refs and no decisions → title unchanged, so a doc-less /task-auto behaves
- * exactly as before.
+ * Run: with no refs and no decisions the title comes back unchanged, and
+ * re-threading an already-threaded list is a no-op.
  */
 export function attachSpecRefs(titles, refs) {
     const list = refs.map(r => '@' + r).join(' ');
@@ -329,15 +336,15 @@ export function attachSpecRefs(titles, refs) {
  * Build the refine scope fence for step `currentIndex` of an N-step /task-auto
  * plan. Every per-step pipeline only ever sees its own title, so without this the
  * refine phase — told "the task title is only a pointer into that spec; follow the
- * spec" — re-expands the whole referenced design into one task (a real run
- * implemented all 24 steps under step 1). The fence lists the sibling steps by
- * number and forbids touching anything they own, so refine bounds this step's
- * slice. Validated on the local model: with the fence, refine's CONSTRAINTS gained
- * an explicit per-step deferral list and tool calls dropped 27→11.
+ * spec" — re-expands the whole referenced design into a single task, implementing
+ * the entire plan under step one. The fence lists the sibling steps by number and
+ * forbids touching anything they own, so refine bounds this step's slice.
  *
  * The plan listing strips the threaded "| decisions … | spec …" tail from each
- * title (keeps the human-readable head) so the model reads clean step names. The
- * authoritative spec ref still rides on THIS step's own title via attachSpecRefs.
+ * title and keeps the human-readable head, so the model reads clean step names,
+ * and it marks the current one "(THIS STEP)" — both confirmed by building a fence
+ * over threaded titles. The authoritative spec ref still rides on THIS step's own
+ * title via attachSpecRefs.
  */
 export function buildScopeFence(titles, currentIndex) {
     const n = titles.length;
@@ -364,8 +371,11 @@ export function buildScopeFence(titles, currentIndex) {
  * a queued root-cause repair. A repair title ("repair test/teardown.ts: …") reads
  * to refine like any other feature step, and refine's job is to expand a title into
  * a full spec — which is exactly how "repair the teardown" becomes "overhaul the
- * test infrastructure" (the /task-auto drift lesson). The extra fence pins the one
- * editable file and pins VERIFY to the command the defect was failing.
+ * test infrastructure". The extra fence pins the one editable file, and pins VERIFY
+ * to the failing command WHEN the title carries one: `extractFailingCommand` reads
+ * a backticked runner command out of the defect text, so a defect quoting
+ * `bun run test` yields it while a plain-prose defect yields undefined and only the
+ * file pin applies.
  */
 function buildStepFence(titles, currentIndex) {
     const base = buildScopeFence(titles, currentIndex);
@@ -379,15 +389,17 @@ function buildStepFence(titles, currentIndex) {
  * repair step per accused FILE, spliced in directly after the step that just
  * finished.
  *
- * Three bounds, all mandatory (mx5 run 14 item 5 gray areas):
- *   - DEDUP by file — run 14's two `test/teardown.ts` debts must yield ONE repair
+ * Three bounds, all mandatory:
+ *   - DEDUP by file — two debts naming the same file must yield ONE repair
  *     step, not two. mergeRepairCandidates collapses the drained queue, and
  *     planHasRepairFor rejects a file the plan already carries a repair for.
  *   - CAP 1 per file per RUN — planHasRepairFor counts CHECKED-OFF entries too, so
  *     a repair step that itself failed is never re-spawned; it lands in the
  *     accept-debt ledger like any other task. That is what stops a repair loop.
+ *     Both bounds run as described: three candidates over two files merge to two,
+ *     and a plan carrying an already-`[x]` repair for a file still answers true.
  *   - MONOTONIC — insertTaskAfter only splices; no existing entry is rewritten,
- *     reordered or dropped (the run-12 replacement lesson).
+ *     reordered or dropped.
  *
  * Best-effort throughout: a fault here must never fail the run that produced the
  * finding — the debt is already durably recorded either way.
@@ -431,7 +443,7 @@ export async function orientFeature(cwd, feature, deps) {
     // clarify/decompose ever see it. Layer A only rewrites the per-task `refined`
     // text — which is DOWNSTREAM of here: clarify is the first phase and runs on
     // this raw inline, so the doc's affirmative `bun:sql` is parroted straight into
-    // the very first clarifying question ("instantly bun:sql is back"). Apply the
+    // the very first clarifying question. Apply the
     // same deterministic, no-LLM strike at the single point that feeds both planning
     // children. Silent + no-op when nothing is flagged or the runtime's types aren't
     // installed.
@@ -451,7 +463,7 @@ export async function orientFeature(cwd, feature, deps) {
         taskId: '',
         signal: new AbortController().signal
     }).catch(() => '');
-    // Requirement extraction (mx5 run 11, goal A): grounded requirement units,
+    // Requirement extraction: 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.
@@ -462,8 +474,8 @@ export async function orientFeature(cwd, feature, deps) {
     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).
+        // for one forced re-extraction: without it an extraction can miss an
+        // entire marked section.
         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);
@@ -475,20 +487,23 @@ export async function orientFeature(cwd, feature, deps) {
             // 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).
+        // Bound with marked-passage priority. A plain first-N cap truncates the
+        // doc's tail sections, because an eager extraction fills the budget from the
+        // top down and never reaches them.
         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
+    // Granularity floor: without it the plan's task COUNT is set by an
+    // auto-resolved clarify line the user never sees, so the same spec and the same
+    // code can plan coarse one run and fine the next. Derive the floor from the
+    // requirements a task can own instead, 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.
+    // plan-shape fork below is the host's to answer at all. Measured:
+    // granularityFloor is 0 for three or fewer ownable requirements — no channel —
+    // and roughly half the count above that.
     const ownableRequirements = reqEntries.filter(e => !isCrossCuttingRequirement(e.quote)).length;
     const coarseFloor = granularityFloor(ownableRequirements);
     if (coarseFloor > 0) {
@@ -509,8 +524,9 @@ export async function orientFeature(cwd, feature, deps) {
  * settles is auto-resolved and never shown — only genuine open forks reach the user.
  * The model emits NONE when nothing remains.
  *
- * The ONLY stage that talks to the user, and so the only one that can be dismissed:
- * `null` means the user cancelled and the cancellation has already been announced.
+ * The ONLY stage that ASKS the user anything, and so the only one that can be
+ * dismissed — the others only notify, which cannot be. `null` means the user
+ * cancelled and the cancellation has already been announced.
  * Every other outcome is a transcript, possibly empty.
  */
 export async function elicitClarifications(ctx, cwd, deps, oriented) {
@@ -527,17 +543,18 @@ export async function elicitClarifications(ctx, cwd, deps, oriented) {
     // strikes out (can't produce anything novel) we stop instead of barraging the
     // user with the same decision worded N ways. Also caps the absolute count.
     // The generate → parse → pick → dedupe → re-prompt state machine is
-    // task/question-source.ts, shared with the plan session. Clarify used to write
-    // its own, and it had drifted from the sibling in five ways — every one of
-    // which the shared source closes for free: `parsed[0]` became `pickQuestion`
-    // (an analysis note is no longer shown as the question, and the SUGGESTED
-    // attached further down is no longer lost), and an unparseable reply now buys
-    // one format re-prompt instead of ending the whole clarify — and decomposing
-    // the feature with ZERO clarifications — on a formatting slip.
+    // task/question-source.ts, shared with the plan session. A second copy here
+    // would drift from the sibling, and the shared source buys two things: it
+    // PICKS a question rather than taking the first parsed line, so an analysis
+    // note is never shown as the question and its SUGGESTED is not lost; and an
+    // unparseable reply costs one format re-prompt instead of ending clarify
+    // outright and decomposing the feature with ZERO clarifications.
     //
-    // Of plan's three quality rules only the DEFERRAL guard crosses. The other two
-    // cost an extra child call every time they fire, and clarify is the most A/B'd
-    // path here; moving them is its own experiment. See CLARIFY_QUALITY_RULES.
+    // Of plan's three quality rules only the DEFERRAL guard crosses. Checked:
+    // PLAN_QUALITY_RULES holds three ('no SUGGESTED', 'SUGGESTED deferred the
+    // decision', 'fork-shaped question with no ALT') and CLARIFY_QUALITY_RULES
+    // holds exactly the middle one. The other two cost an extra child call every
+    // time they fire, so moving them is its own change to make and measure.
     const source = makeQuestionSource({
         generate: hint => deps.runChild('auto-clarify', 'read', prependHint(hint, AUTO_CLARIFY_PROMPT(featureForModel, transcript.forGenerator()))),
         formatHint: PLAN_FORMAT_HINT,
@@ -554,9 +571,10 @@ export async function elicitClarifications(ctx, cwd, deps, oriented) {
         // for the editable default and the persisted file.
         const shownQ = renderInlineMarkdown(question, theme);
         const plainQ = drawn.plain;
-        // 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
+        // PLAN SHAPE is the host's call, not the triage's — the same spec off the
+        // same base commit can plan far coarser or finer depending on this one
+        // answer (see decompose-granularity.ts).
+        // The triage answers this fork for itself every time 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
@@ -610,9 +628,9 @@ export async function elicitClarifications(ctx, cwd, deps, oriented) {
  */
 export async function decomposePlan(cwd, deps, oriented, clarifications) {
     const { featureForModel, reqEntries, ownableRequirements, coarseFloor } = oriented;
-    // Tests-in-the-same-change cadence (mx5 run 14, PROMPT item 6): when the
-    // decisions mandate it, a whole-project batch test task contradicts them —
-    // run 14 shipped one anyway (TASK_0037, 4.7h, yolo-accepted FAIL) because
+    // Tests-in-the-same-change cadence: when the
+    // decisions mandate it, a whole-project batch test task contradicts them, and
+    // one still ships because
     // decompose mirrors the spec's milestone shape. The decisions channel
     // OVERRIDES the spec doc, so this resolves toward the decision without asking.
     const noBatchTests = mandatesTestsInSameChange(clarifications, featureForModel);
@@ -622,7 +640,7 @@ export async function decomposePlan(cwd, deps, oriented, clarifications) {
     }
     // decompose
     const decomposePrompt = AUTO_DECOMPOSE_PROMPT(featureForModel, clarifications, buildRequirementsLedger(reqEntries), noBatchTests);
-    // Parse + FIDELITY RECONCILIATION (mx5 run 11, goal B): ground each title's
+    // Parse + FIDELITY RECONCILIATION: ground each title's
     // [source: "…"] citation against the doc, strip the clause, and re-attach any
     // `+`-joined constraint fragment the paraphrased title dropped (the silently
     // stripped "+ tests" class). Applied to EVERY decompose output — initial,
@@ -639,7 +657,7 @@ export async function decomposePlan(cwd, deps, oriented, clarifications) {
         // Batch-test ban (item 6): drop or scope a whole-project "write all the
         // tests" task. Identity unless the cadence decision is present, and the
         // sweep replacement re-grounds every requirement the drop would cost — so
-        // planned coverage cannot fall (run 12's lesson).
+        // planned coverage cannot fall.
         const debatched = rewriteBatchTestPlan(plan.titles, clarifications, featureForModel, reqEntries.map(e => e.quote), isCrossCuttingRequirement);
         for (const a of debatched.actions) {
             logPlanDebug(cwd, `batch test task ${a.kind} (tests-in-same-change decision): "${a.title}"`
@@ -654,7 +672,7 @@ export async function decomposePlan(cwd, deps, oriented, clarifications) {
     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
+    // regenerated — a fresh roll can drop a covered area). 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)) {
@@ -668,8 +686,8 @@ export async function decomposePlan(cwd, deps, oriented, clarifications) {
     }
     // 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
-    // (5/5 live). Longer list wins; a still-suspect plan falls through to the
+    // catch it, and a hinted retry heals it reliably.
+    // Longer list wins; a still-suspect plan falls through to the
     // judge loop as before, so this never blocks planning.
     // 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.
@@ -717,17 +735,16 @@ export async function coverPlan(ctx, cwd, deps, oriented, clarifications, decomp
     const { featureForModel, reqEntries } = oriented;
     const { decomposePrompt, parsePlan } = decomposed;
     let planTitles = decomposed.planTitles;
-    // Coverage gate: a stochastic degenerate completion (live mx5: ONE task +
-    // natural EOS for an 18KB design doc) is nonempty, so the length guard below
+    // Coverage gate: a degenerate completion — ONE task and a natural EOS for a
+    // whole design document — is nonempty, so the length guard below
     // never fires and the whole run "completes" after one task. Judge the list
     // against the feature with a no-tools child; on INCOMPLETE, re-run decompose
     // with the missing areas as a hint. Best-effort so a triage fault never blocks
     // planning (mirrors triageClarifyQuestion).
     //
-    // Two hard-won invariants (mx5 run 12: a complete full-stack plan — 31
-    // requirements mapped, frontend pages present — was overwritten by a
-    // backend-only regeneration and shipped with only a toast, driven by 3 NEGATIVE
-    // requirements no task could own that kept the verdict INCOMPLETE forever):
+    // Two invariants. Without them a complete full-stack plan is overwritten by a
+    // narrower regeneration, driven by a handful of NEGATIVE requirements that no
+    // task can own and that therefore keep the verdict INCOMPLETE forever:
     //   • MONOTONIC replacement (coverage-loop.ts): a retry that DROPS a requirement
     //     the current plan already owns is REJECTED, never adopted. Coverage can
     //     only hold or grow across rounds — a worse regeneration can no longer
@@ -759,8 +776,8 @@ export async function coverPlan(ctx, cwd, deps, oriented, clarifications, decomp
         // numbers. Live (Qwen3.6-27B) the model over-credits ownership, mapping a
         // "--json output" requirement to a generic "scaffold + argument parser"
         // task, so a plan with no --json task still "owned" it and the drop guard
-        // went blind (treatment 1/5). Grounding the drop-signal in the titles the
-        // model can't fake takes it back to 5/5. The model map still drives Fix A's
+        // went blind. Grounding the drop-signal in the titles the model cannot
+        // fake restores it. The model map still drives Fix A's
         // cross-cutting/unmapped accounting below (that only affects reprompt
         // aggressiveness, which the monotonic guard now backstops).
         const covered = groundedCoverage(reqEntries.map(e => e.quote), titles, isCrossCuttingRequirement);
@@ -796,9 +813,9 @@ export async function coverPlan(ctx, cwd, deps, oriented, clarifications, decomp
     // `best` is both the plan the next round reprompts FROM and the plan that
     // ships — kept identical because adoption is monotone (see coverage-loop.ts).
     //
-    // It is also the ONLY handle on the accounting. There used to be a second,
-    // `let accounting`, carried alongside — see the ScoredPlan doc comment for the
-    // requirement-to-wrong-task bug that cost us.
+    // It is also the ONLY handle on the accounting. A second one carried
+    // alongside is how a requirement gets attached to the wrong task — see the
+    // ScoredPlan doc comment.
     // The record, and the decisions it makes: task/plan-rounds.ts. This was five
     // locals threaded by closure through a ~90-line loop, plus a
     // snapshot-before-overwrite pair that existed only because the bonus-round
@@ -859,8 +876,8 @@ export async function coverPlan(ctx, cwd, deps, oriented, clarifications, decomp
     const round = rounds.round();
     planTitles = best.plan.titles;
     // Exhausted still INCOMPLETE: the best plan ships (the gate is best-effort), but
-    // silently shipping a KNOWN-gapped plan is how mx5 run 5 lost its whole test
-    // suite — tell the user what is still uncovered.
+    // silently shipping a KNOWN-gapped plan is how a run loses a whole area of
+    // work — tell the user what is still uncovered.
     const unresolvedMissing = rounds.unresolved();
     if (unresolvedMissing !== null) {
         logPlanDebug(cwd, `decompose-coverage exhausted ${round} round(s) still INCOMPLETE — missing: `
@@ -883,14 +900,14 @@ export async function planAuto(ctx, cwd, feature, deps) {
     const clarifications = await elicitClarifications(ctx, cwd, deps, oriented);
     if (clarifications === null)
         return null; // dismissed; already announced
-    // Artifact-production closure, plan side (mx5 run 13, PROMPT 2): runtime
+    // Artifact-production closure, plan side: runtime
     // files the spec REFERENCES (server snippets, prose "serve the built
     // index.html") that neither its file tree, its parsed build outputs, nor the
     // existing scaffold produce. Sentence-grounded coverage credited the SERVING
     // side and reported "0 unowned" while nothing ever CREATED the file — so
     // these ride the coverage loop's `missing` list as unowned areas until some
     // task title claims the artifact (grounded in titles, which the coverage-map
-    // model cannot fake — the run-12 lesson). Deterministic and best-effort.
+    // model cannot fake — the lesson). Deterministic and best-effort.
     let specDangling = [];
     try {
         specDangling = findSpecDanglingArtifacts(featureForModel, rel => existsSync(path.join(cwd, rel)));
@@ -910,16 +927,16 @@ export async function planAuto(ctx, cwd, feature, deps) {
     const planTitles = covered.planTitles;
     // Carry what no single task owns (goal A(b)/(c)): cross-cutting requirements
     // become `.pi-tasks/requirements.md`, injected VERBATIM into every task's
-    // refine/compose (run 11: §10's test-first cadence had no carrier — the "spec
-    // is authoritative" pointer recovered it in 1 of ~6 tasks; content travels,
-    // pointers don't). Requirements still unmapped after the rounds are carried
+    // refine/compose. A rule stated only in the spec body has no carrier, and a
+    // "spec is authoritative" pointer recovers it in a minority of tasks: content
+    // travels, pointers do not. Requirements still unmapped after the rounds are carried
     // too — marked — and recorded user-visibly in the plan file, never dropped.
     //
     // #1: the holistic-judge missing areas are carried as a THIRD channel. They are
     // areas requirement-extraction never captured as a tracked entry (so the
     // grounded accounting is structurally blind to them), seen only by the judge —
-    // exactly the class that, having no carrier, was warned-about then dropped (mx5
-    // 2026-07-16, §10 test-infra). Carried independent of `accounting` so a mapping
+    // exactly the class that, having no carrier, is warned about and then
+    // dropped. Carried independent of `accounting` so a mapping
     // fault (accounting === null) can't strand them either.
     const carriedCrossCutting = best.accounting?.crossCutting ?? [];
     const carriedUnmapped = best.accounting?.unmapped ?? [];
@@ -959,7 +976,7 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // empty-plan path the plan is discarded one line later, so running them first
     // burned two model calls and left contracts.md / launch-contract.md carrying
     // facts for a run that never produced a task.
-    // Cross-slice contract registry (mx5 run 8, F3): now that the plan is settled,
+    // Cross-slice contract registry: now that the plan is settled,
     // extract the interface facts MORE THAN ONE slice must agree on — endpoint paths,
     // exported signatures, file layouts, env var names the DESIGN pins — into a
     // run-level artifact each downstream refine/compose/verify reads. The extraction
@@ -979,12 +996,12 @@ export async function planAuto(ctx, cwd, feature, deps) {
         ground: emitted => keepGroundedContracts(emitted, featureForModel),
         append: appendContracts
     });
-    // Launch contract (mx5 run 10 item 4): extract the package/build SCRIPTS the design
+    // Launch contract: extract the package/build SCRIPTS the design
     // declares the project must expose (`migrate`/`seed` fell through decompose and
     // shipped missing, unchecked). Each emitted name is re-grounded against the design
     // (keepGroundedScripts — kept only if the design backticks it), so the final gate's
     // manifest diff can never false-flag a hallucinated script. Recall is mechanical
-    // (mx5 run 11): enumerateScriptCandidates hands the child every backticked
+    //: enumerateScriptCandidates hands the child every backticked
     // script-shaped token near the word "script" as a checklist, so a script declared
     // far from the design's summary list (`test:ct` in §2 vs §9's five) can't be
     // missed by a weak model's recall — the child classifies, it no longer recalls.
@@ -1001,10 +1018,10 @@ export async function planAuto(ctx, cwd, feature, deps) {
         append: appendDeclaredScripts
     });
     // Persist the TASK-MAPPED requirements keyed by the (spec-ref-attached) title
-    // each task will carry (mx5 run 16: only cross-cutting entries travelled;
-    // the 33 mapped ones shaped the title list and vanished — TASK_0008 narrowed
-    // §9's "serves `/api` + static `dist/`" out of its spec with nothing to stop
-    // it). Inert until the owned-requirements injection is wired into the phase
+    // each task will carry. With only cross-cutting entries travelling, the
+    // mapped ones shape the title list and then vanish, and a task can narrow a
+    // requirement out of its own spec with nothing to stop it.
+    // Inert until the owned-requirements injection is wired into the phase
     // prompts; recorded regardless so the plan's mapping is auditable per run.
     if (best.accounting && best.accounting.mapped.length > 0) {
         await writeOwnedRequirements(cwd, best.accounting.mapped
@@ -1042,7 +1059,7 @@ export async function planAuto(ctx, cwd, feature, deps) {
  *
  * The grounding step is the reason this shape exists rather than a plain child
  * call. A child asked for interface facts will paraphrase and occasionally invent
- * them (mx5 run 8, F3), and an invented fact in a run-level registry is read as
+ * them, and an invented fact in a run-level registry is read as
  * authoritative by every downstream refine/compose/verify. So nothing the child
  * says is trusted: `ground` re-checks each emitted line against the design text
  * host-side, and only substrings survive.
@@ -1086,9 +1103,9 @@ function defaultDeps(ctx, cwd, signal, title) {
         cwd,
         taskId: '',
         signal,
-        // IN-RUN thrash guard for the planning children (mx5-n 2026-08-14: a
-        // decompose child re-read DESIGN/marketplace.html until it filled a
-        // 120k window, and ran 16m23s without returning). Every planning child
+        // IN-RUN thrash guard for the planning children: without it a decompose
+        // child can re-read its design document until it fills the whole context
+        // window, and never return. Every planning child
         // gets its source doc INLINED in its prompt, so a second read of a file
         // it has already opened can only be thrash — which makes the read-once
         // block safe here in a way it is not for a phase that must explore.
@@ -1128,14 +1145,14 @@ function defaultDeps(ctx, cwd, signal, title) {
             runFinalIntegrationGate(cwd2, { planText, signal })
             : Promise.resolve({ ok: true, reason: 'disabled' }),
         // Uncommitted paths, for the stranded-sub-fix handling around the final-gate
-        // picker (mx5 run 13 PROMPT 4 item 3). Every task is committed by the time
+        // picker. Every task is committed by the time
         // the gate runs, so whatever is dirty here belongs to the fix pass.
         pendingChanges: async (cwd2) => {
             const changes = await collectTreeChanges(cwd2, signal);
             return [...changes.modified, ...changes.added, ...changes.deleted].sort();
         },
         // Re-derive the debt ledger against the FINAL tree after a converged
-        // autofix (nexttask 6). Only ever reached from inside the gate's own
+        // autofix. Only ever reached from inside the gate's own
         // resolution loop, so it needs no `verify work` switch of its own.
         // Same section, same cancel: this re-runs every ACCEPT-debt VERIFY command
         // against the final tree, each under its own 300s cap.
@@ -1150,11 +1167,11 @@ export function requestAutoCancel() {
 /**
  * Report a stash pushed during one task and left behind.
  *
- * An orphan stash later pops as an unresolvable conflict (mx5 run 6), so the
- * capture before the task and this check after it are ONE fact. They were a local
- * and a check ~120 lines and three returns apart, which is how the check came to
- * run only on the success path. Best-effort: never throws, so it cannot mask the
- * outcome of the attempt it closes.
+ * An orphan stash later pops as an unresolvable conflict, so the capture before
+ * the task and this check after it are ONE fact — which is why the call sits in a
+ * `finally` rather than on the fall-through, where it would only run when the task
+ * succeeded. Best-effort: never throws, so it cannot mask the outcome of the
+ * attempt it closes.
  */
 async function reportStashDrift(active, deps, cwd, id, title, before) {
     if (!deps.stashRef || before === undefined)
@@ -1198,8 +1215,8 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             const next = entries.find(e => !e.done);
             if (!next) {
                 // FINAL INTEGRATION GATE: every task passed its own per-slice gates,
-                // but per-slice green has shipped a dead app twice (mx5 runs 3 & 5:
-                // statics clean, every protected route 500ing). The run-level stage
+                // but per-slice green can still ship a dead app — every slice's own
+                // checks clean while the assembled whole does not serve. The run-level stage
                 // runs the project's OWN whole-repo commands once, unaided, before the
                 // run is declared complete, and resolves a FAIL with the user. It
                 // touches none of this loop's per-task state — see run-final-gate.ts —
@@ -1210,7 +1227,7 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     runId: id,
                     // The parent plan (the task list) is what lets the gate tell a
                     // served app from a CLI — the boot check requires a listener only
-                    // for the former (mx5 run 10: a CSS watcher satisfied "still alive").
+                    // for the former.
                     planText: body,
                     taskCount: entries.length
                 });
@@ -1228,8 +1245,7 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 return;
             }
             // REFUSE to start on a conflicted tree: an unmerged index dooms every
-            // commit ahead and a `git add -A` would silently mis-resolve it. mx5
-            // run 6 burned a full impl turn + three verify passes exactly here.
+            // commit ahead and a `git add -A` would silently mis-resolve it.
             const unmerged = deps.unmergedPaths ? await deps.unmergedPaths(cwd) : [];
             if (unmerged.length > 0) {
                 await updateTaskFrontMatter(cwd, id, { state: 'failed' });
@@ -1280,8 +1296,8 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             try {
                 // SAFE CHECKPOINT (pre-task): the tree is committed and no inner task
                 // is stamped yet, so stopping here just leaves this entry unchecked —
-                // a resume restarts it from scratch. Cheapest possible stop, and the
-                // last one before we commit to a ~30-minute task.
+                // a resume restarts it from scratch. The cheapest possible stop, and
+                // the last one before a whole task is under way.
                 if (cancelCheckpoint('pre-task')) {
                     announceDone(active, `${id} cancelled before "${next.title}" — resume with /task-auto-resume.`, 'warning');
                     return;
@@ -1297,18 +1313,18 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     onStart: resumeId ? undefined : (innerId => stampTaskInProgress(cwd, id, next.index, innerId, next.title))
                 });
                 active = res.ctx ?? active;
-                // One dispatch over the named ending. The five-branch ladder this
-                // replaces had to ask `isCancelRequested()` — a module global
-                // `/task-cancel` never sets — to tell a user stop from a fault, so a
-                // cancel during a task was announced in red as "stopped … fix and
-                // resume" and the inner file's `cancelled` was overwritten with
-                // `failed`. The runner names the ending now; resumability is
-                // RUN_END_POLICY's; only the wording is this command's.
+                // One dispatch over the named ending. The runner NAMES how the run
+                // ended, so nothing here has to infer a user stop from a fault by
+                // consulting a module global — the way that inference went wrong was
+                // announcing a cancel in red as "stopped … fix and resume" and
+                // overwriting the inner file's `cancelled` with `failed`.
+                // Resumability is RUN_END_POLICY's call (shared with /task's loop);
+                // only the wording is this command's.
                 if (!runSucceeded(res.end)) {
                     const policy = RUN_END_POLICY[res.end.kind];
                     // Demote the INNER task file: it reads `completed` from
                     // spec-handoff, and leaving it that way is how a failed run's task
-                    // file claimed success in the run 6 audit.
+                    // file claims success after the run failed.
                     if (policy.resumable)
                         await markResumable(cwd, res.taskId);
                     // The PLAN fails only on a fault. A declined-steer interrupt leaves
@@ -1373,20 +1389,20 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     }), outcome.level);
                     return;
                 }
-                // ROOT-CAUSE REPAIR (mx5 run 14 item 5): the gate may have attributed a
+                // ROOT-CAUSE REPAIR: the gate may have attributed a
                 // FAIL to a pre-existing defect in a file some OTHER task created. It can
                 // only QUEUE that finding — mutating the plan is this loop's job. Drain
                 // the queue and splice a scoped repair step in right after the step that
                 // just finished, so the defect is fixed BEFORE the next dependent task
-                // trips over it too (run 14 recorded the same `test/teardown.ts` cause
-                // twice, scheduled nothing, and the bug outlived ~24h of the run).
+                // trips over it too. Recording the same cause twice and scheduling
+                // nothing lets one defect outlive most of a run.
                 await schedulePendingRepairs(cwd, id, next.index, active, deps);
             }
             finally {
                 // EVERY exit from this attempt passes here — the two mid-attempt
-                // returns and a throw included. The check used to sit at the very
-                // end of the fall-through, ~120 lines and three returns below the
-                // capture, so it ran only when the task SUCCEEDED and the gate said
+                // returns and a throw included. Sitting at the end of the
+                // fall-through instead, below the capture and three returns, it
+                // would run only when the task SUCCEEDED and the gate said
                 // `done`. On a failed or interrupted task the user is told to run
                 // /task-auto-resume, straight onto the landmine the guard exists to
                 // name. The pairing is structural now, not positional.
@@ -1428,7 +1444,7 @@ async function handleTaskAuto(args, ctx) {
     // and the ordinary command path cannot reach us.
     try {
         await withRun(ctx, { onCancel: terminalCancel }, async () => {
-            // Stamp a fresh per-run research-cache id (F10) BEFORE planning so enrichment and
+            // Stamp a fresh per-run research-cache id BEFORE planning so enrichment and
             // every task's research phase share one run's cache; disabled ⇒ clears any token a
             // prior run left, so nothing is cached.
             configureResearchRun(getConfig().researchCache);
@@ -1493,10 +1509,10 @@ async function handleTaskAutoResume(args, ctx) {
     try {
         await withRun(ctx, { onCancel: terminalCancel }, async () => {
             // Reuse the interrupted run's research-cache id, dropping only the entries whose
-            // own package moved version (F10). mx5 run 13 resumed three times and each
-            // resume's fresh id discarded a working 201-entry cache; run 14 then showed a
-            // whole-file freshness gate can never hold on a greenfield run that installs
-            // packages as it goes, so invalidation is per entry. See resumeResearchRun.
+            // own package moved version. A fresh id per resume discards the whole
+            // working cache, and a whole-file freshness gate can never hold on a
+            // greenfield run that installs packages as it goes — so invalidation is
+            // per entry. See resumeResearchRun.
             const research = await resumeResearchRun(cwd, getConfig().researchCache);
             if (research.reused) {
                 logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies), `