@mjasnikovs/pi-task 0.38.29 → 0.38.31

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

@@ -1,23 +1,27 @@
 /**
  * coverage-loop — the MONOTONIC replacement rule for /task-auto's decompose
- * coverage gate (mx5 run 12).
+ * coverage gate.
  *
- * The failure this closes: the coverage-retry loop regenerated the whole plan on
- * every INCOMPLETE verdict, and adopted the regeneration on nothing but a size
- * floor (`retry.length * 2 >= current.length`). A regeneration is a fresh
- * stochastic roll of the ENTIRE plan, so one that DROPPED a previously-covered
- * feature-area but kept the title count replaced the better plan anyway — and,
- * because the loop shipped whatever the LAST round produced, the dropped area was
- * gone with only a toast. Live: a complete full-stack plan (31 requirements
- * mapped, frontend pages present) was overwritten by a backend-only one and
- * shipped, driven by 3 NEGATIVE requirements no task could ever "own" that kept
- * the verdict INCOMPLETE forever.
+ * The failure this closes: a coverage retry regenerates the WHOLE plan, so it is a
+ * fresh stochastic roll rather than an edit. Adopt it on a size floor alone and a
+ * retry that DROPPED a previously-covered area but kept the title count replaces
+ * the better plan — and since the loop ships whatever the last round produced, the
+ * dropped area is gone with only a toast.
+ *
+ * The shape that makes this bite: a requirement no task can ever "own" — a
+ * prohibition, say — keeps the verdict INCOMPLETE forever, so the loop keeps
+ * rolling until a worse plan happens to come up last.
  *
  * The rule here makes replacement monotone: coverage can only hold or grow across
  * rounds. A retry is adopted ONLY when it drops no requirement the current plan
- * already owns (its owned-set is a superset). Because adoption is monotone, the
- * working plan at exhaustion is the best-covered one seen — so "ship the working
- * plan" is automatically "ship the best", never "ship the last".
+ * already owns — its owned-set must be a superset. Because adoption is monotone,
+ * the working plan at exhaustion is the best-covered one seen, so "ship the
+ * working plan" is automatically "ship the best" and never "ship the last".
+ *
+ * Each rule was run. A retry dropping one owned requirement is rejected naming
+ * it; a strict superset is adopted; a retry that grows while covering nothing new
+ * is rejected as "no coverage gain"; and with no requirement signal at all, a
+ * retry leaving MORE areas uncovered is rejected while one leaving fewer is taken.
  *
  * Spec-shape-agnostic: the only inputs are title counts and the set of
  * requirement INDICES a task owns (from the host-side coverage map). No feature
@@ -47,13 +51,13 @@ export interface CoveragePlan {
  * DETERMINISTIC owned-set for the monotonic guard — grounded in requirement↔title
  * token overlap, NOT the coverage-map model's `TASK n` verdict.
  *
- * Why this exists (live A/B, Qwen3.6-27B, mx5-shaped CLI spec): the model
+ * Why this exists: the model
  * over-credits ownership — it mapped a "--json output" requirement to a generic
  * "scaffold + argument parser" task, so a plan with NO --json task still reported
  * owning it. A guard that trusts those numbers is blind to the very drop it must
- * catch (treatment held only 1/5 trials). Grounding coverage in whether a task
+ * catch. Grounding coverage in whether a task
  * TITLE actually shares a distinctive token with the requirement makes the
- * drop-signal independent of the model's rubber-stamp (treatment → 5/5).
+ * drop-signal independent of the model's rubber-stamp.
  *
  * A requirement is "covered" when some title shares a DISTINCTIVE token with it —
  * distinctive meaning the token is not shared across more than half the ownable
@@ -103,7 +107,7 @@ export declare function decideAdoption(current: CoveragePlan, retry: CoveragePla
  * title list the coverage-map child was prompted with. Hold the two apart and the
  * index silently addresses the wrong plan.
  *
- * That is not hypothetical. The coverage loop used to keep `best` (the scored plan)
+ * That is not hypothetical: a loop that keeps `best` (the scored plan)
  * and a separate `let accounting`, updated on adoption as
  * `accounting = cand.accounting ?? accounting`. `cand.accounting` is null whenever
  * the coverage-map child throws or its output fails to parse — a fault that is

package/dist/task/coverage-loop.js

@@ -1,23 +1,27 @@
 /**
  * coverage-loop — the MONOTONIC replacement rule for /task-auto's decompose
- * coverage gate (mx5 run 12).
+ * coverage gate.
  *
- * The failure this closes: the coverage-retry loop regenerated the whole plan on
- * every INCOMPLETE verdict, and adopted the regeneration on nothing but a size
- * floor (`retry.length * 2 >= current.length`). A regeneration is a fresh
- * stochastic roll of the ENTIRE plan, so one that DROPPED a previously-covered
- * feature-area but kept the title count replaced the better plan anyway — and,
- * because the loop shipped whatever the LAST round produced, the dropped area was
- * gone with only a toast. Live: a complete full-stack plan (31 requirements
- * mapped, frontend pages present) was overwritten by a backend-only one and
- * shipped, driven by 3 NEGATIVE requirements no task could ever "own" that kept
- * the verdict INCOMPLETE forever.
+ * The failure this closes: a coverage retry regenerates the WHOLE plan, so it is a
+ * fresh stochastic roll rather than an edit. Adopt it on a size floor alone and a
+ * retry that DROPPED a previously-covered area but kept the title count replaces
+ * the better plan — and since the loop ships whatever the last round produced, the
+ * dropped area is gone with only a toast.
+ *
+ * The shape that makes this bite: a requirement no task can ever "own" — a
+ * prohibition, say — keeps the verdict INCOMPLETE forever, so the loop keeps
+ * rolling until a worse plan happens to come up last.
  *
  * The rule here makes replacement monotone: coverage can only hold or grow across
  * rounds. A retry is adopted ONLY when it drops no requirement the current plan
- * already owns (its owned-set is a superset). Because adoption is monotone, the
- * working plan at exhaustion is the best-covered one seen — so "ship the working
- * plan" is automatically "ship the best", never "ship the last".
+ * already owns — its owned-set must be a superset. Because adoption is monotone,
+ * the working plan at exhaustion is the best-covered one seen, so "ship the
+ * working plan" is automatically "ship the best" and never "ship the last".
+ *
+ * Each rule was run. A retry dropping one owned requirement is rejected naming
+ * it; a strict superset is adopted; a retry that grows while covering nothing new
+ * is rejected as "no coverage gain"; and with no requirement signal at all, a
+ * retry leaving MORE areas uncovered is rejected while one leaving fewer is taken.
  *
  * Spec-shape-agnostic: the only inputs are title counts and the set of
  * requirement INDICES a task owns (from the host-side coverage map). No feature
@@ -28,8 +32,12 @@
 // titles and requirement quotes, so overlap on them would falsely connect a
 // requirement to any plan. Stopped so grounding keys on the DISTINCTIVE nouns
 // (json, dead-letter, serialize, symlink…) that actually name a deliverable.
+//
+// Confirmed: titles built only from these words own NOTHING, while titles naming
+// `JSON output` and `dead-letter queue` own the matching requirements.
+//
 // English function words + generic task verbs + generic project nouns — all
-// domain-agnostic (no mx5/web vocabulary).
+// domain-agnostic.
 const COVERAGE_STOPWORDS = new Set([
     // function words
     'the',
@@ -151,13 +159,13 @@ function contentTokens(s) {
  * DETERMINISTIC owned-set for the monotonic guard — grounded in requirement↔title
  * token overlap, NOT the coverage-map model's `TASK n` verdict.
  *
- * Why this exists (live A/B, Qwen3.6-27B, mx5-shaped CLI spec): the model
+ * Why this exists: the model
  * over-credits ownership — it mapped a "--json output" requirement to a generic
  * "scaffold + argument parser" task, so a plan with NO --json task still reported
  * owning it. A guard that trusts those numbers is blind to the very drop it must
- * catch (treatment held only 1/5 trials). Grounding coverage in whether a task
+ * catch. Grounding coverage in whether a task
  * TITLE actually shares a distinctive token with the requirement makes the
- * drop-signal independent of the model's rubber-stamp (treatment → 5/5).
+ * drop-signal independent of the model's rubber-stamp.
  *
  * A requirement is "covered" when some title shares a DISTINCTIVE token with it —
  * distinctive meaning the token is not shared across more than half the ownable
@@ -244,31 +252,28 @@ export function decideAdoption(current, retry, hasRequirements) {
         }
         // 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".
+        // covers nothing new. Adopting it anyway lets a plan inflate round after
+        // round with the owned-set pinned, every step 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
+        // guard adopted unconditionally. A retry that is a strict superset is
+        // always adopted; an independently-sampled one often is not — 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".
+        // gained: a later round can add the requirement a tied round did not. "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
+        // strictly better one. It removes plans inflated by a retry that added
+        // titles without adding coverage, and leaves coverage itself alone — the
+        // win is removing pathological
         // inflation, not shrinking plans generally.
         if (retry.covered.size <= current.covered.size
             && retry.titles.length > current.titles.length) {

package/dist/task/critique-probes.d.ts

@@ -6,21 +6,20 @@
  * the deterministic half of critique: the triage child judges taste, these decide
  * facts.
  *
- * Why a table. Every probe used to be written out three times inside
- * `phaseCritique` — once as a four-line detect/format/log ritual, once as a term
- * in the seven-way conjunction that lets a CLEAN triage short-circuit, and once
- * as an element of the array merged into the rewrite. Adding a probe meant three
- * coordinated edits, and forgetting the SECOND one is silent and severe: a CLEAN
- * triage would then ship a spec carrying a defect the scanner had already found —
- * which is precisely the failure each probe exists to prevent. No test would
- * notice, because the wiring, unlike the scanners, was almost entirely untested
- * (1 of 6).
+ * Why a table. Longhand, a probe has to appear three times in `phaseCritique`:
+ * once as a detect/format/log ritual, once as a term in the conjunction that lets
+ * a CLEAN triage short-circuit, and once in the array merged into the rewrite.
+ * Adding one then means three coordinated edits, and forgetting the SECOND is
+ * silent and severe — a CLEAN triage ships a spec carrying a defect the scanner
+ * already found, which is precisely what each probe exists to prevent. Wiring like
+ * that is also the part tests rarely cover, because the scanners are the
+ * interesting half.
  *
- * With a table the override and the merge are DERIVED from the rows, so "every
- * probe blocks a CLEAN short-circuit" is structurally true rather than something
- * a reviewer must check. This is the same move `PROBE_ADAPTERS` (verify-work.ts)
- * and `CLOSURE_SCANS` (final-gate.ts) already made; critique is the one place
- * that never got it.
+ * As a table the override and the merge are DERIVED from the rows:
+ * `collectCritiqueDefects` returns `forced: blocks.length > 0`, so "every probe
+ * blocks a CLEAN short-circuit" is structurally true rather than something a
+ * reviewer must check. Same move as `PROBE_ADAPTERS` (verify-work.ts) and
+ * `CLOSURE_SCANS` (final-gate.ts).
  */
 /** Everything the probes read. Assembled once by the critique phase. */
 export interface CritiqueProbeContext {

package/dist/task/critique-probes.js

@@ -6,21 +6,20 @@
  * the deterministic half of critique: the triage child judges taste, these decide
  * facts.
  *
- * Why a table. Every probe used to be written out three times inside
- * `phaseCritique` — once as a four-line detect/format/log ritual, once as a term
- * in the seven-way conjunction that lets a CLEAN triage short-circuit, and once
- * as an element of the array merged into the rewrite. Adding a probe meant three
- * coordinated edits, and forgetting the SECOND one is silent and severe: a CLEAN
- * triage would then ship a spec carrying a defect the scanner had already found —
- * which is precisely the failure each probe exists to prevent. No test would
- * notice, because the wiring, unlike the scanners, was almost entirely untested
- * (1 of 6).
+ * Why a table. Longhand, a probe has to appear three times in `phaseCritique`:
+ * once as a detect/format/log ritual, once as a term in the conjunction that lets
+ * a CLEAN triage short-circuit, and once in the array merged into the rewrite.
+ * Adding one then means three coordinated edits, and forgetting the SECOND is
+ * silent and severe — a CLEAN triage ships a spec carrying a defect the scanner
+ * already found, which is precisely what each probe exists to prevent. Wiring like
+ * that is also the part tests rarely cover, because the scanners are the
+ * interesting half.
  *
- * With a table the override and the merge are DERIVED from the rows, so "every
- * probe blocks a CLEAN short-circuit" is structurally true rather than something
- * a reviewer must check. This is the same move `PROBE_ADAPTERS` (verify-work.ts)
- * and `CLOSURE_SCANS` (final-gate.ts) already made; critique is the one place
- * that never got it.
+ * As a table the override and the merge are DERIVED from the rows:
+ * `collectCritiqueDefects` returns `forced: blocks.length > 0`, so "every probe
+ * blocks a CLEAN short-circuit" is structurally true rather than something a
+ * reviewer must check. Same move as `PROBE_ADAPTERS` (verify-work.ts) and
+ * `CLOSURE_SCANS` (final-gate.ts).
  */
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -40,22 +39,28 @@ function probe(row) {
  */
 export const CRITIQUE_PROBES = [
     probe({
-        // run-8 F2: a required VERIFY check wrapped in a skip-announcing `||`
-        // fallback (`… || echo "skipping (tool absent)"`) lets the check pass
-        // while never running. FP-measured 0/20 on the historical specs.
+        // A required VERIFY check wrapped in a skip-announcing `||` fallback
+        // (`… || echo "skipping (tool absent)"`) lets the check pass while never
+        // running. Confirmed: that exact line makes the collector force a rewrite.
         id: 'skip-escape',
         detect: ctx => findSkipEscapes(ctx.spec),
         text: f => skipEscapeDefectText(f),
         log: f => `skip-escape flagged in VERIFY: ${f.length} line(s)`
     }),
     probe({
-        // run-8 F3, generation side. The registry alone is a WEAK catcher (live
-        // A/B: prompt+registry ~1/8) — the model's attention goes to the obvious
-        // VERIFY weakness and it rarely does the path-composition reasoning. The
-        // scanner NAMES the inferred mount mappings and juxtaposes the verbatim
-        // pinned facts, forcing focused reconciliation. FP-clean (1/18 files on
-        // the run-8 trees). Grounding = the registry ∪ any design doc the
-        // spec/refined @-reference. No registry ⇒ nothing to contradict.
+        // The generation-side complement of the verify-side boundary check: a spec
+        // that INFERS a wiring specific (a tidy mount table) the design never
+        // pinned.
+        //
+        // Handing the registry to the model alone is a weak catcher, because its
+        // attention goes to the obvious VERIFY weakness rather than to
+        // path-composition reasoning. So this scanner NAMES the inferred mount
+        // mappings and juxtaposes the verbatim pinned facts, forcing a focused
+        // reconciliation.
+        //
+        // Grounding is the registry plus any design doc the spec or refined text
+        // @-references. No registry means nothing to contradict, and the row
+        // returns no findings at all.
         id: 'synthesized-wiring',
         detect: ctx => ctx.registryRaw.trim().length > 0 ?
             findSynthesizedWiring(ctx.spec, ctx.registryRaw + '\n' + readReferencedDocs(ctx.cwd, ctx.refined, ctx.spec), ctx.registryRaw)
@@ -64,11 +69,11 @@ export const CRITIQUE_PROBES = [
         log: f => `synthesized wiring flagged in spec: ${f.map(w => w.line).join(' | ')}`
     }),
     probe({
-        // mx5 run 11, goal D: a VERIFY line asserting the ABSENCE of an artifact
+        // A VERIFY line asserting the ABSENCE of an artifact
         // the plan pins elsewhere — a path a prior task already shipped, a sibling
-        // title's deliverable, a contract-pinned boundary. Run 11: the scope fence
-        // leaked into TASK_0009's verify as "the admin page must NOT exist"
-        // (TASK_0008's deliverable); the guaranteed FAIL became an accepted debt
+        // title's deliverable, a contract-pinned boundary. A scope fence can
+        // leak into a sibling's verify as "the admin page must NOT exist"
+        //; the guaranteed FAIL became an accepted debt
         // that the final-gate autofix then "fixed" by deleting the sibling's work.
         // It must die here, at spec time. Delete-tasks keep their check by
         // declaring the delete.
@@ -83,14 +88,20 @@ export const CRITIQUE_PROBES = [
             + f.map(c => `${c.assertion.target} (${c.against})`).join(' | ')
     }),
     probe({
-        // mx5 run 12 root cause: a blanket frozen path ("Do NOT modify
-        // `tsconfig.json` … handled in steps 1–2") whose registration edit the
-        // spec's OWN body — or the task's RESEARCH the spec was composed from
-        // (live drafts sometimes drop the nuance while shipping the freeze and the
-        // creation) — says the deliverable requires. Shipped as-is, the created
-        // files turn the repo-wide static check permanently red and no task is
-        // allowed to fix it: every later task burns its AUTOFIX rounds on it. The
-        // rewrite must grant scoped ownership or drop the creation.
+        // An unsatisfiable pair: the spec FREEZES a path outright ("Do NOT modify
+        // `tsconfig.json` — handled in steps 1-2") while something also says the
+        // deliverable requires editing that same path. The freeze always comes from
+        // the spec; the requirement may come from the spec's own body OR from the
+        // RESEARCH it was composed from, since compose can drop the nuance while
+        // keeping both the freeze and the file creation.
+        //
+        // Shipped as-is, the created files turn the repo-wide static check
+        // permanently red and no task is allowed to fix it — every later task burns
+        // its AUTOFIX rounds on it. The rewrite must grant scoped ownership or drop
+        // the creation.
+        //
+        // Confirmed: a freeze alone yields nothing; a freeze plus a
+        // requires-edit statement in the same spec yields one conflict.
         id: 'frozen-conflict',
         detect: ctx => findFrozenPathConflicts(ctx.spec, ctx.research),
         text: f => frozenConflictProbeText(f),
@@ -98,7 +109,7 @@ export const CRITIQUE_PROBES = [
             + f.map(c => c.path).join(' | ')
     }),
     probe({
-        // mx5 run 13, Bug B: a VERIFY block that grep-asserts the SOURCE of a
+        // A VERIFY block that grep-asserts the SOURCE of a
         // runnable deliverable while every command in the block is static
         // inspection — the build script "verified" by three greps that was never
         // run, shipping broken for 14 tasks. VERIFY must EXECUTE the artifact and
@@ -107,7 +118,7 @@ export const CRITIQUE_PROBES = [
         detect: ctx => findGrepOnlyVerify(ctx.spec),
         text: f => grepOnlyVerifyDefectText(f),
         log: f => `grep-theater VERIFY flagged in spec: ${f.map(x => x.target).join(' | ')}`,
-        // Detector-backed closure: live A/B, 1/5 rewrites ignored the injected
+        // Detector-backed closure: a rewrite can ignore the injected
         // defect and re-shipped the grep-only block.
         unresolvedProblem: {
             name: 'verify_grep_theater',
@@ -115,7 +126,7 @@ export const CRITIQUE_PROBES = [
         }
     }),
     probe({
-        // mx5 run 13, PROMPT 4 item 4: a spec that DICTATES a check script which
+        // A spec that DICTATES a check script which
         // cannot fail — `"lint": "… || true"`, or a checker laundered through an
         // inverted grep. Whatever task implements that spec writes the disarmed
         // script into package.json, and from then on every gate that runs it

package/dist/task/debug-log.d.ts

@@ -1,10 +1,13 @@
 import { type DebugLogLevel } from '../config/config.js';
 /**
  * Escape hatch for reproducing a user's bug without walking them through
- * /task-config. Follows the existing `PI_TASK_*` instrumentation convention
- * (`PI_TASK_TYPEONLY_LOG`, `PI_REMOTE_PUSH_DEBUG`). An unrecognised value is
- * ignored rather than treated as `off` — a typo in an env var must not silently
- * throw the trail away.
+ * /task-config. Follows the `PI_TASK_*` instrumentation convention this codebase
+ * already uses in nine places, `PI_TASK_TYPEONLY_LOG` among them.
+ *
+ * An unrecognised value is IGNORED rather than treated as `off` — a typo in an env
+ * var must not silently throw the trail away. Run: `full` and `off` both take
+ * effect, surrounding whitespace is tolerated, and `verbose` falls through to the
+ * saved config instead of resolving to anything.
  */
 export declare const DEBUG_LOG_ENV = "PI_TASK_DEBUG_LOG";
 /** A trail line's kind — see the module note. Producers default to `'event'`. */
@@ -15,7 +18,9 @@ export type DebugLine = 'event' | 'stream';
  * line instead of at the next restart.
  */
 export declare function debugLogLevel(getEnv?: (k: string) => string | undefined): DebugLogLevel;
-/** Whether a line of this kind should be written at `level`. */
+/** Whether a line of this kind should be written at `level`. The whole matrix:
+ *  `off` writes nothing, `full` writes both kinds, `events` writes events and
+ *  drops stream. */
 export declare function shouldLogDebug(kind: DebugLine, level: DebugLogLevel): boolean;
 /**
  * A timestamped fire-and-forget appender for one trail file, level-gated.
@@ -30,5 +35,8 @@ export declare function makeDebugAppender(logPath: string, appendFile?: (p: stri
  * Wrap a raw append in the level gate. Returns `undefined` when the level is
  * `off`, so callers that hold an OPTIONAL `logDebug` leave it unset and every
  * `logDebug?.(…)` in the pipeline short-circuits before it formats a string.
+ *
+ * Run: undefined at `off`, a function otherwise, and at `events` it writes an
+ * event line while dropping a stream one.
  */
 export declare function gateDebugWriter(write: (msg: string) => void, getEnv?: (k: string) => string | undefined): ((msg: string, kind?: DebugLine) => void) | undefined;

package/dist/task/debug-log.js

@@ -1,38 +1,45 @@
 /**
  * One place that decides whether a `.pi-tasks/*-debug.log` line gets written.
  *
- * THE TRAIL IS WRITE-ONLY. Nothing in pi-task reads these files back: `task-io.ts`
- * globs `TASK_NNNN.md` and skips everything else, and auto-commit's `snapshotTrail`
- * copies the bytes across a `reset --hard` without ever parsing them. Every producer
- * is a `logDebug?.(…)` / `log(…)` side effect whose return value is discarded. So
- * this gate cannot change what a run DOES — only what it can explain afterwards.
+ * THE TRAIL IS WRITE-ONLY in production. Nothing under src/ reads these files
+ * back: `task-io.ts` globs `TASK_NNNN.md` and skips everything else, and
+ * auto-commit's `snapshotTrail` copies the bytes across a `reset --hard` without
+ * ever parsing them. Every producer is a `logDebug?.(…)` / `log(…)` side effect
+ * whose return value is discarded. So this gate cannot change what a run DOES —
+ * only what it can explain afterwards. (Tests do read the trail back, which is why
+ * `flushPlanDebug` exists.)
  *
  * TWO KINDS OF LINE, and the distinction is the whole point of having three levels
  * rather than a boolean:
  *
- *   'stream' — what the child model said, and what its tools returned. Reproducible
- *              by re-running, useful while you are actively debugging, and 85% of the
- *              bytes (measured: a 247 KB IAR1 `verify-debug.log` is 1315 lines, of
- *              which 521 are `↳` tool dumps and most of the rest is raw model text).
+ *   'stream' — what the child model said, and what its tools returned. It is the
+ *              bulk of the bytes by a wide margin, and it is REPRODUCIBLE: re-run
+ *              the child and you get it again. Useful while actively debugging,
+ *              worthless as a record.
  *
  *   'event'  — a decision or a guard action: which phase started, why a worker was
  *              retried or degraded, what the git-state guard restored, what a
- *              write-capable child changed on disk, why a gate returned FAIL. Ten-ish
- *              lines per task, and NOT reproducible — it is the only record that the
- *              guard fired at all. mx5 run 11's final-fix child deleted a source file
- *              and the `tree changes:` line is the reason anyone could tell.
+ *              write-capable child changed on disk, why a gate returned FAIL. A
+ *              handful of lines per task, and NOT reproducible — it is the only
+ *              record that the guard fired at all. If a final-fix child deletes a
+ *              source file, the `tree changes:` line is the only way anyone can
+ *              tell.
  *
- * Hence the default is `events`, not `off`: the quiet default users want costs the
- * chatter, not the audit trail.
+ * Hence the shipped default is `events`, not `off` (DEFAULT_DEBUG_LOGS in
+ * config.ts): the quiet default users want costs the chatter, not the audit trail.
+ * A machine-local `"debugLogs": "off"` still wins — this is a default, not a floor.
  */
 import * as fsp from 'node:fs/promises';
 import { getConfig, sanitizeDebugLogs } from '../config/config.js';
 /**
  * Escape hatch for reproducing a user's bug without walking them through
- * /task-config. Follows the existing `PI_TASK_*` instrumentation convention
- * (`PI_TASK_TYPEONLY_LOG`, `PI_REMOTE_PUSH_DEBUG`). An unrecognised value is
- * ignored rather than treated as `off` — a typo in an env var must not silently
- * throw the trail away.
+ * /task-config. Follows the `PI_TASK_*` instrumentation convention this codebase
+ * already uses in nine places, `PI_TASK_TYPEONLY_LOG` among them.
+ *
+ * An unrecognised value is IGNORED rather than treated as `off` — a typo in an env
+ * var must not silently throw the trail away. Run: `full` and `off` both take
+ * effect, surrounding whitespace is tolerated, and `verbose` falls through to the
+ * saved config instead of resolving to anything.
  */
 export const DEBUG_LOG_ENV = 'PI_TASK_DEBUG_LOG';
 /**
@@ -49,7 +56,9 @@ export function debugLogLevel(getEnv = k => process.env[k]) {
         return raw;
     return getConfig().debugLogs;
 }
-/** Whether a line of this kind should be written at `level`. */
+/** Whether a line of this kind should be written at `level`. The whole matrix:
+ *  `off` writes nothing, `full` writes both kinds, `events` writes events and
+ *  drops stream. */
 export function shouldLogDebug(kind, level) {
     if (level === 'off')
         return false;
@@ -76,6 +85,9 @@ export function makeDebugAppender(logPath, appendFile = (p, data) => fsp.appendF
  * Wrap a raw append in the level gate. Returns `undefined` when the level is
  * `off`, so callers that hold an OPTIONAL `logDebug` leave it unset and every
  * `logDebug?.(…)` in the pipeline short-circuits before it formats a string.
+ *
+ * Run: undefined at `off`, a function otherwise, and at `events` it writes an
+ * event line while dropping a stream one.
  */
 export function gateDebugWriter(write, getEnv) {
     if (debugLogLevel(getEnv) === 'off')

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

@@ -7,15 +7,17 @@ export interface SourcedTitle {
 /**
  * Split a decompose title into its base and its GROUNDED source citations.
  *
- * PLURAL, because the model emits plural. The prompt asks for one trailing
- * citation and a quarter of real titles carry more — 62 of 244 across the 20
- * recorded runs. The old pattern was `\[source:\s*"(.+)"\]$`: greedy `.+`
- * against an end anchor, so on `[source: "A"] [source: "B"]` it matched from the
- * FIRST clause to the LAST quote and produced the superstring `A"] [source: "B`,
- * which of course is not in the document. Two real citations became one
- * fabricated one, and both were discarded. Peeling from the end with
- * lastIndexOf is the fix; a lazy quantifier is NOT, because leftmost-first
- * matching plus the `$` anchor expands it across the later clauses just the same.
+ * PLURAL, because the model emits plural: the prompt asks for one trailing
+ * citation and a real share of titles carry more than one.
+ *
+ * A single anchored pattern cannot read them. Run on `[source: "A"] [source: "B"]`,
+ * `\[source:\s*"(.+)"\]$` captures the superstring `A"] [source: "B` — from the
+ * FIRST clause to the LAST quote — which is of course not in the document, so two
+ * real citations become one fabricated one and both are discarded. Making the
+ * quantifier LAZY changes nothing: `(.+?)` against the same input captures the
+ * identical superstring, because leftmost-first matching plus the `$` anchor
+ * expands it across the later clauses just the same. Peeling from the end with
+ * lastIndexOf is what actually works — confirmed, both citations come back.
  *
  * An absent clause yields no sources; a fabricated (ungrounded) one is dropped
  * — exactly like keepGroundedContracts rejects a paraphrased quote.