@mjasnikovs/pi-task 0.38.28 → 0.38.30

package/dist/task/context-attribution.js

@@ -1,25 +1,25 @@
 /**
- * Deterministic detector for the F-1 laundering shape: a CONTEXT bullet that asserts
+ * Deterministic detector for the laundering shape: a CONTEXT bullet that asserts
  * external API USAGE SEMANTICS under an attribution cue that no EXTERNAL CONTEXT block
  * can actually support.
  *
- * THE SHAPE, from mx5 run 15 (TASK_0027.md, verbatim):
+ * THE SHAPE:
  *
  *   - The `hono` dependency is pinned at `^4.12.31` in package.json, and the external
  *     context confirms `hc<AppType>` pattern with base URL `/api` for same-origin
  *     relative paths works correctly (per Hono RPC docs LIVE data).
  *
- * worker:context has tools `read,grep` only (phases.ts:623) — it cannot consult any
- * documentation — so the base-URL claim was necessarily from model memory. It shipped
- * into TASK_0027's CONSTRAINTS and ACCEPTANCE, the implementation obeyed it exactly
- * (`hc<AppType>('/api')` plus `api.api.auth.login.$post()`), and every request went to
- * `/api/api/...` ⇒ 404 ⇒ the product's entire API surface was dead.
+ * The `worker:context` row in phases.ts gives that worker `tools: 'read,grep'` and
+ * nothing else — no fetch, no docs channel — so a base-URL claim like that one is
+ * necessarily from model memory. It then ships into a task's CONSTRAINTS and
+ * ACCEPTANCE, the implementation obeys it exactly, and every request goes to the
+ * wrong path.
  *
  * WHY THE OBVIOUS TEST DOES NOT WORK. "Flag a bullet whose package has no EXTERNAL
  * CONTEXT block" misses this case: EXTERNAL CONTEXT *did* carry a `### npm: hono` block.
  * That block contains version numbers and nothing else, so it cannot support a claim
  * about what a base URL MEANS — yet it lends the sentence an air of having been checked.
- * That is the whole mechanism (F-1e): one citable fact, the pinned version, fused in a
+ * That is the whole mechanism: one citable fact, the pinned version, fused in a
  * single sentence with an uncitable one under a shared attribution. The true half
  * launders the false half.
  *
@@ -30,27 +30,35 @@
  *   ### url:      fetched page content            -> CAN source a semantics claim
  *   ### service:  3 search-result SNIPPETS        -> cannot source a semantics claim
  *
- * The `service` exclusion is not a judgement call — it is the LIVE-DATA RULE's own scope.
- * That rule makes a service block authoritative for "current API surface, deprecation
- * status, and replacement systems", i.e. versions/status/names. A service block is a
- * title + URL + one-line description per result (service-blocks.ts:10); it cannot carry
- * what a parameter MEANS. This matters concretely: TASK_0027's enrichment produced
- * exactly one service block, `### service: Hono RPC client` (extractEnrichTargets on the
- * verbatim refined task yields services=[Hono RPC client], urls=[], packages=[any,api,hc]).
- * Were `service` treated as source-capable for semantics, the subject string "Hono RPC
- * client" would match the package `hono` and the fatal bullet would pass unflagged — the
- * detector would be unable to catch the very defect it exists for.
+ * The `service` exclusion is not a judgement call — it is the LIVE-DATA RULE's own
+ * scope. That rule (prompts.ts) makes a service block authoritative for "current
+ * API surface, deprecation status, and replacement systems", i.e. versions, status
+ * and names. And a service block is only ever a title, a URL and a one-line
+ * description per result — see `formatServiceBlock` — so it cannot carry what a
+ * parameter MEANS.
+ *
+ * This matters concretely, and was checked: with a single
+ * `### service: Hono RPC client` block as the only external context, the fatal
+ * bullet IS flagged. Were `service` treated as source-capable, that subject would
+ * match the package `hono` and the bullet would pass — leaving the detector unable
+ * to catch the one defect it exists for.
  *
  * A bullet is FLAGGED iff all three hold:
- *   1. it carries an attribution cue ("per ... LIVE data", "the external context
- *      confirms", "docs confirm", "per the official docs", ...);
- *   2. it asserts API usage semantics — how something is called, what a parameter means,
- *      what a default is, what behaviour results — as opposed to a version or a status;
+ *   1. it carries an attribution cue ("per... LIVE data", "the external context
+ *      confirms", "docs confirm", "per the official docs",...);
+ *   2. it asserts API usage semantics — how something is called, what a parameter
+ *      means, what a default is, what behaviour results — as opposed to a version
+ *      or a status;
  *   3. no `### url:` or `### docs:` block exists for any package the bullet names.
  *
- * Pure and side-effect free; unit-tested in context-attribution.test.ts against the real
- * run-15 bullets, including the three legitimate attributed bullets (TASK_0007, _0012,
- * _0031) that must NOT be flagged.
+ * All six branches were run against the laundering bullet above. It is FLAGGED with
+ * an npm-only block, with a service-only block, and with no external context at
+ * all; it is NOT flagged once a `### docs:` or `### url:` block for that package
+ * exists. And the same context leaves alone a version claim made under an
+ * attribution cue, a semantics claim made with NO cue, and a plain "is pinned at"
+ * statement of fact.
+ *
+ * Pure and side-effect free; also unit-tested in context-attribution.test.ts.
  */
 /** Block kinds whose body is retrieved prose/declarations, so they can carry semantics. */
 const SOURCE_CAPABLE_KINDS = new Set(['docs', 'url']);
@@ -118,7 +126,7 @@ function firstMatch(text, patterns) {
 /**
  * Split a CONTEXT section into bullets WITH their line ranges. Continuation lines are
  * folded into the bullet above so a hard-wrapped claim is judged as one sentence — which
- * is exactly how the fatal run-15 bullet was written.
+ * is exactly how the fatal bullet was written.
  */
 export function splitBulletSpans(context) {
     const spans = [];

package/dist/task/context-silence.d.ts

@@ -1,27 +1,26 @@
 /**
- * Deterministic classifier for a SILENT worker:context — a rep whose CONTEXT section
- * carries zero parseable bullets. The open question this answers (STEP 0 of the
- * worker:context ZERO-BULLETS thread) is whether a silent rep is a genuine LOSS (the
- * architectural context was there to surface and the worker dropped all of it) or a
- * LEGITIMATE empty answer (the task truly had nothing worth a bullet). Only the former
- * is a defect worth a lever.
- *
- * WHAT THE RECORDED EVIDENCE SHOWED (48 reps, three runs, 2026-07-21/22). Every silent
- * rep — 5/48 — fell into one of two failure shapes, NONE legitimately empty:
- *
- *   LOOP_DEGRADE (3/5): the worker thrashed the SAME grep 5× until the loop-killer fired
- *     (exit 143), leaving only the degrade banner in place of a section. Verbatim:
- *       "(degraded: research CONTEXT worker stuck in a loop — called grep(...) ×5 ...)"
- *
- *   GENERATION_GARBAGE (2/5): the worker exited 0 in ~3.6s and emitted a hallucinated
- *     non-bullet fragment instead of context. Verbatim: "Users deleted" and
- *       "[SYSTEM NOTE This message received a positive feedback reward/+20 ...]"
- *
- * The fixture (mx5 pre-TASK_0027 tree) is IDENTICAL across all reps and non-silent reps
- * reliably emit 11–21 architectural bullets from it, so the input-empty rival is refuted:
- * the content was always there; a silent rep dropped it. Both shapes are therefore genuine
- * loss. This classifier keys on those shapes so the same verdict is reproducible and so a
- * PHASE-1 gate can reuse it to decide when a retry is warranted.
+ * Deterministic classifier for a SILENT worker:context — a run whose CONTEXT
+ * section carries zero parseable bullets. The question it answers is whether that
+ * silence is a genuine LOSS (architectural context was there to surface and the
+ * worker dropped all of it) or a LEGITIMATE empty answer (there was nothing worth
+ * a bullet). Only the first is worth re-running for.
+ *
+ * TWO SILENT SHAPES ARE LOSSES, and both are recognisable from the output alone:
+ *
+ *   LOOP_DEGRADE: the worker thrashed the same call until the loop-killer fired,
+ *     leaving the degrade banner in place of a section. research-worker.ts writes
+ *     that banner as "stuck in a loop — called <tool>(<args>) ×<n> in the last <m>
+ *     calls…", which is the substring this keys on.
+ *
+ *   GENERATION_GARBAGE: the worker exited 0 and emitted a non-bullet fragment
+ *     instead of context — a stray sentence, or a hallucinated system note.
+ *
+ * The third silent shape, an honest "nothing to surface" declaration, is NOT a
+ * loss and must not trigger a retry. Separating the three is the whole job.
+ *
+ * This is wired: research-worker gates its silent-retry on
+ * `verdict.silent && verdict.genuineLoss`, and keeps the retry only if
+ * `countBullets` says it produced any.
  */
 /** Why a CONTEXT section came out with no bullets — or that it did not (productive). */
 export type SilenceCause = 'productive' | 'loop-degrade' | 'generation-garbage' | 'legitimately-empty';
@@ -37,15 +36,26 @@ export interface SilenceVerdict {
 /** Bullet lines in an emitted CONTEXT section: leading `-` or `*` markers. */
 export declare function countBullets(contextText: string): number;
 /**
- * Classify one worker:context output. `workerLog` is optional and only consulted for the
- * loop banner, which the degrade machinery writes to the debug log even on the reps where
- * it never reached the persisted section (e.g. a mid-loop SIGTERM before any write).
+ * Classify one worker:context output.
+ *
+ * `workerLog` is optional and only consulted for the loop banner, which the degrade
+ * machinery writes to the debug log even when it never reached the persisted
+ * section — a mid-loop SIGTERM before any write. Confirmed by running it: a
+ * garbage-looking section plus a log carrying the banner classifies as
+ * `loop-degrade`, not `generation-garbage`. The production call site passes no
+ * log, so that path is currently reachable only by a caller that supplies one.
  */
 export declare function classifyContextSilence(contextText: string, workerLog?: string): SilenceVerdict;
 /**
- * Wilson score interval for a binomial proportion — the CI STEP 0 reports on the silent
- * and genuine-loss rates. Normal-approximation (Wald) intervals are badly wrong at the
- * small counts and near-boundary rates this measurement lives at; Wilson is not.
+ * Wilson score interval for a binomial proportion.
+ *
+ * A normal-approximation (Wald) interval is useless exactly where this kind of
+ * measurement lives — at small counts and rates near 0 or 1. At 0 successes of 12,
+ * Wald collapses to the zero-width [0, 0], claiming certainty from no evidence,
+ * while Wilson gives roughly [0, 0.24]. Checked both ways, including 12 of 12,
+ * which Wilson bounds below 1 rather than pinning at it.
+ *
+ * No production caller: this is a reporting helper, exercised by its own tests.
  */
 export declare function wilsonInterval(successes: number, n: number, z?: number): {
     lo: number;

package/dist/task/context-silence.js

@@ -1,27 +1,26 @@
 /**
- * Deterministic classifier for a SILENT worker:context — a rep whose CONTEXT section
- * carries zero parseable bullets. The open question this answers (STEP 0 of the
- * worker:context ZERO-BULLETS thread) is whether a silent rep is a genuine LOSS (the
- * architectural context was there to surface and the worker dropped all of it) or a
- * LEGITIMATE empty answer (the task truly had nothing worth a bullet). Only the former
- * is a defect worth a lever.
+ * Deterministic classifier for a SILENT worker:context — a run whose CONTEXT
+ * section carries zero parseable bullets. The question it answers is whether that
+ * silence is a genuine LOSS (architectural context was there to surface and the
+ * worker dropped all of it) or a LEGITIMATE empty answer (there was nothing worth
+ * a bullet). Only the first is worth re-running for.
  *
- * WHAT THE RECORDED EVIDENCE SHOWED (48 reps, three runs, 2026-07-21/22). Every silent
- * rep — 5/48 — fell into one of two failure shapes, NONE legitimately empty:
+ * TWO SILENT SHAPES ARE LOSSES, and both are recognisable from the output alone:
  *
- *   LOOP_DEGRADE (3/5): the worker thrashed the SAME grep 5× until the loop-killer fired
- *     (exit 143), leaving only the degrade banner in place of a section. Verbatim:
- *       "(degraded: research CONTEXT worker stuck in a loop — called grep(...) ×5 ...)"
+ *   LOOP_DEGRADE: the worker thrashed the same call until the loop-killer fired,
+ *     leaving the degrade banner in place of a section. research-worker.ts writes
+ *     that banner as "stuck in a loop — called <tool>(<args>) ×<n> in the last <m>
+ *     calls…", which is the substring this keys on.
  *
- *   GENERATION_GARBAGE (2/5): the worker exited 0 in ~3.6s and emitted a hallucinated
- *     non-bullet fragment instead of context. Verbatim: "Users deleted" and
- *       "[SYSTEM NOTE This message received a positive feedback reward/+20 ...]"
+ *   GENERATION_GARBAGE: the worker exited 0 and emitted a non-bullet fragment
+ *     instead of context — a stray sentence, or a hallucinated system note.
  *
- * The fixture (mx5 pre-TASK_0027 tree) is IDENTICAL across all reps and non-silent reps
- * reliably emit 11–21 architectural bullets from it, so the input-empty rival is refuted:
- * the content was always there; a silent rep dropped it. Both shapes are therefore genuine
- * loss. This classifier keys on those shapes so the same verdict is reproducible and so a
- * PHASE-1 gate can reuse it to decide when a retry is warranted.
+ * The third silent shape, an honest "nothing to surface" declaration, is NOT a
+ * loss and must not trigger a retry. Separating the three is the whole job.
+ *
+ * This is wired: research-worker gates its silent-retry on
+ * `verdict.silent && verdict.genuineLoss`, and keeps the retry only if
+ * `countBullets` says it produced any.
  */
 /** Bullet lines in an emitted CONTEXT section: leading `-` or `*` markers. */
 export function countBullets(contextText) {
@@ -31,9 +30,14 @@ const LOOP_BANNER = /stuck in a loop/i;
 /** Honest "nothing to surface" — the ONLY non-loss silent shape. */
 const EMPTY_DECLARATION = /^\s*(none|n\/a|no relevant (context|architectural)|nothing\b)/i;
 /**
- * Classify one worker:context output. `workerLog` is optional and only consulted for the
- * loop banner, which the degrade machinery writes to the debug log even on the reps where
- * it never reached the persisted section (e.g. a mid-loop SIGTERM before any write).
+ * Classify one worker:context output.
+ *
+ * `workerLog` is optional and only consulted for the loop banner, which the degrade
+ * machinery writes to the debug log even when it never reached the persisted
+ * section — a mid-loop SIGTERM before any write. Confirmed by running it: a
+ * garbage-looking section plus a log carrying the banner classifies as
+ * `loop-degrade`, not `generation-garbage`. The production call site passes no
+ * log, so that path is currently reachable only by a caller that supplies one.
  */
 export function classifyContextSilence(contextText, workerLog = '') {
     const bulletCount = countBullets(contextText);
@@ -76,9 +80,15 @@ export function classifyContextSilence(contextText, workerLog = '') {
     };
 }
 /**
- * Wilson score interval for a binomial proportion — the CI STEP 0 reports on the silent
- * and genuine-loss rates. Normal-approximation (Wald) intervals are badly wrong at the
- * small counts and near-boundary rates this measurement lives at; Wilson is not.
+ * Wilson score interval for a binomial proportion.
+ *
+ * A normal-approximation (Wald) interval is useless exactly where this kind of
+ * measurement lives — at small counts and rates near 0 or 1. At 0 successes of 12,
+ * Wald collapses to the zero-width [0, 0], claiming certainty from no evidence,
+ * while Wilson gives roughly [0, 0.24]. Checked both ways, including 12 of 12,
+ * which Wilson bounds below 1 rather than pinning at it.
+ *
+ * No production caller: this is a reporting helper, exercised by its own tests.
  */
 export function wilsonInterval(successes, n, z = 1.959963984540054 // 95%
 ) {

package/dist/task/context-usage.d.ts

@@ -4,14 +4,32 @@
  * the planning and gate children; the single-task widget (TaskRunner) calls it
  * directly, because its state is the whole-run `WidgetState`, not one child's.
  */
-import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import type { ContextSnapshot } from '../shared/child-process.js';
-/** The parent session's context window, or 0 when the model doesn't expose it. */
-export declare function getParentContextWindow(ctx: ExtensionCommandContext): number;
 /**
- * Fold a raw context snapshot into a display snapshot: prefer the child's
- * own contextWindow, else the last known one, else the parent session's; then
- * derive percent against it — falling back to the child's reported percent when
- * no window is known at all.
+ * The parent session's context window, or 0 when the model doesn't expose it.
+ *
+ * The parameter is the STRUCTURAL MINIMUM this reads, deliberately, rather than
+ * one of pi's context interfaces. Naming `ExtensionCommandContext` here would
+ * exclude the plain context a TOOL is handed — and that is a real caller:
+ * `workers/pi-worker.ts` reads the window through this to arm the churn rule.
+ * Both pi contexts carry a `model` whose `contextWindow` is a number, so both
+ * satisfy the shape.
+ *
+ * Returns 0 for a context with no model, and for a model with no window.
+ */
+export declare function getParentContextWindow(ctx: {
+    model?: {
+        contextWindow?: number;
+    };
+}): number;
+/**
+ * Fold a raw context snapshot into a display snapshot: prefer the child's own
+ * contextWindow, else the last known one, else the parent session's; then derive
+ * percent against it, falling back to the child's own reported percent when no
+ * window is known at all.
+ *
+ * Run through all four: a child reporting 4000 uses it; a child reporting 0 with a
+ * previous 8000 uses that; with neither, the parent's; and with nothing anywhere
+ * the reported percent survives untouched. The derived percent clamps at 100.
  */
 export declare function resolveContextUsage(snapshot: ContextSnapshot, prev: ContextSnapshot | undefined, parentContextWindow: number): ContextSnapshot;

package/dist/task/context-usage.js

@@ -4,15 +4,30 @@
  * the planning and gate children; the single-task widget (TaskRunner) calls it
  * directly, because its state is the whole-run `WidgetState`, not one child's.
  */
-/** The parent session's context window, or 0 when the model doesn't expose it. */
+/**
+ * The parent session's context window, or 0 when the model doesn't expose it.
+ *
+ * The parameter is the STRUCTURAL MINIMUM this reads, deliberately, rather than
+ * one of pi's context interfaces. Naming `ExtensionCommandContext` here would
+ * exclude the plain context a TOOL is handed — and that is a real caller:
+ * `workers/pi-worker.ts` reads the window through this to arm the churn rule.
+ * Both pi contexts carry a `model` whose `contextWindow` is a number, so both
+ * satisfy the shape.
+ *
+ * Returns 0 for a context with no model, and for a model with no window.
+ */
 export function getParentContextWindow(ctx) {
-    return (ctx.model?.contextWindow ?? 0);
+    return ctx.model?.contextWindow ?? 0;
 }
 /**
- * Fold a raw context snapshot into a display snapshot: prefer the child's
- * own contextWindow, else the last known one, else the parent session's; then
- * derive percent against it — falling back to the child's reported percent when
- * no window is known at all.
+ * Fold a raw context snapshot into a display snapshot: prefer the child's own
+ * contextWindow, else the last known one, else the parent session's; then derive
+ * percent against it, falling back to the child's own reported percent when no
+ * window is known at all.
+ *
+ * Run through all four: a child reporting 4000 uses it; a child reporting 0 with a
+ * previous 8000 uses that; with neither, the parent's; and with nothing anywhere
+ * the reported percent survives untouched. The derived percent clamps at 100.
  */
 export function resolveContextUsage(snapshot, prev, parentContextWindow) {
     const cw = snapshot.contextWindow > 0 ?

package/dist/task/contracts.d.ts

@@ -10,9 +10,11 @@ export declare function readContracts(cwd: string): Promise<string>;
 /**
  * Normalise for substring matching: collapse all whitespace runs to one space and
  * lowercase. Quoting across a line wrap or with reflowed spacing still matches the
- * source; casing differences do not defeat the anti-synthesis guard. Exported as
- * the ONE grounding normaliser every "verbatim quote from the source doc" guard
- * shares (contracts, decompose source anchors), so the rule can't drift.
+ * source, and casing differences do not defeat the anti-synthesis guard.
+ *
+ * Exported as the ONE grounding normaliser every "verbatim quote from the source
+ * doc" guard shares, so the rule cannot drift: decompose-fidelity and requirements
+ * both import it from here alongside this module's own use.
  */
 export declare function normalise(s: string): string;
 /**
@@ -21,7 +23,9 @@ export declare function normalise(s: string): string;
  *   CONTRACT: "<verbatim quote>" [anchor: <where>]
  * The quote (between the first pair of double quotes) is the pinned fact; the
  * optional `[anchor: …]` trailer records provenance. A line without a quoted span
- * is skipped — an unquoted "contract" is a summary, which this registry rejects.
+ * is skipped — an unquoted "contract" is a summary, which this registry rejects —
+ * and so is a quote shorter than MIN_QUOTE_LENGTH or longer than
+ * MAX_CONTRACT_LENGTH. All three skips were run.
  */
 export declare function parseContractLines(text: string): ContractEntry[];
 /**

package/dist/task/contracts.js

@@ -2,13 +2,13 @@
  * contracts — a per-run registry of CROSS-SLICE INTERFACE FACTS, recorded once at
  * decompose time and read (never written) by every downstream slice.
  *
- * The failure this serves (mx5 run 8, F3 — the dominant shipped-defect class): the
- * SOURCE design pins an interface contract (a SPLIT route table: `POST
- * /api/listings/:id/photos` but `GET/DELETE /api/photos/:id`). One slice's refine
- * FABRICATED a uniform mount table ("/api/photos → photosRoutes") with no anchor in
- * the doc; the consumer slices followed the spec, the assembly slice followed the
- * fabrication, and the seam between them shipped broken while each slice was locally
- * "right". Class: refine synthesizes plausible interface specifics instead of citing.
+ * The failure this serves: a source design pins an interface contract that is not
+ * uniform — say a split route table, `POST /api/listings/:id/photos` alongside
+ * `GET/DELETE /api/photos/:id`. One slice's refine then FABRICATES the tidy version
+ * it expected ("/api/photos → photosRoutes") with no anchor in the doc. Consumer
+ * slices follow the spec, the assembly slice follows the fabrication, and the seam
+ * between them ships broken while every slice is locally "right". The class is
+ * refine synthesizing plausible interface specifics instead of citing them.
  *
  * Mechanism (mirrors env-notes.ts): interface facts that MORE THAN ONE task will
  * touch — endpoint paths, exported signatures, file layouts, env var names, whatever
@@ -17,12 +17,16 @@
  * file (no artifact corruption). It lives under `.pi-tasks/`, surviving discardEdits
  * and the git-state guard.
  *
- * HARD DESIGN RULE (this is exactly how F3 happened): a registry entry is a VERBATIM
- * QUOTE from the source doc plus a source anchor — NEVER a model-synthesized summary.
- * The anti-synthesis guard is deterministic: a candidate quote is kept only if it is
- * an actual substring of the source document (normalised for whitespace). A quote the
- * model paraphrased or invented is not in the doc, so it is dropped — a fabricated
- * contract can never enter the registry.
+ * HARD DESIGN RULE: a registry entry is a VERBATIM QUOTE from the source doc plus a
+ * source anchor — NEVER a model-synthesized summary. The anti-synthesis guard is
+ * deterministic: a candidate quote is kept only if it is an actual substring of the
+ * source document, normalised for whitespace and case. A quote the model
+ * paraphrased or invented is not in the doc, so it is dropped.
+ *
+ * Run on the shape above: fed both real route lines AND the fabricated
+ * "/api/photos → photosRoutes", the guard keeps the two that are in the doc and
+ * drops the invention. Reflowed whitespace and different casing still match, so
+ * quoting across a line wrap does not defeat it.
  *
  * Stack-agnostic: an "interface fact" is any pinned boundary string; the guard is
  * pure substring matching over the source text, with no assumption about its shape.
@@ -59,9 +63,11 @@ export async function readContracts(cwd) {
 /**
  * Normalise for substring matching: collapse all whitespace runs to one space and
  * lowercase. Quoting across a line wrap or with reflowed spacing still matches the
- * source; casing differences do not defeat the anti-synthesis guard. Exported as
- * the ONE grounding normaliser every "verbatim quote from the source doc" guard
- * shares (contracts, decompose source anchors), so the rule can't drift.
+ * source, and casing differences do not defeat the anti-synthesis guard.
+ *
+ * Exported as the ONE grounding normaliser every "verbatim quote from the source
+ * doc" guard shares, so the rule cannot drift: decompose-fidelity and requirements
+ * both import it from here alongside this module's own use.
  */
 export function normalise(s) {
     return s.replace(/\s+/g, ' ').trim().toLowerCase();
@@ -72,7 +78,9 @@ export function normalise(s) {
  *   CONTRACT: "<verbatim quote>" [anchor: <where>]
  * The quote (between the first pair of double quotes) is the pinned fact; the
  * optional `[anchor: …]` trailer records provenance. A line without a quoted span
- * is skipped — an unquoted "contract" is a summary, which this registry rejects.
+ * is skipped — an unquoted "contract" is a summary, which this registry rejects —
+ * and so is a quote shorter than MIN_QUOTE_LENGTH or longer than
+ * MAX_CONTRACT_LENGTH. All three skips were run.
  */
 export function parseContractLines(text) {
     const entries = [];

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