@mjasnikovs/pi-task 0.18.14 → 0.18.16

package/README.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/@mjasnikovs/pi-task?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mjasnikovs/pi-task)
 [![license](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
-[![tests](https://img.shields.io/badge/tests-1405%20passing-3fb950)](#development)
+[![tests](https://img.shields.io/badge/tests-1617%20passing-3fb950)](#development)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
 
 </div>
@@ -175,7 +175,7 @@ Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. Add `.pi-tasks/` to your
 
 ```sh
 bun install
-bun test src/      # 1405 tests across 94 files
+bun test src/      # 1617 tests across 106 files
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```

package/dist/task/accept-debt.d.ts

@@ -14,6 +14,14 @@ export interface AcceptDebt {
     reason: string;
     /** Absent in legacy 2-field records → treated as 'accepted'. */
     origin?: DebtOrigin;
+    /**
+     * Set (never serialized) when the recorded reason CONFLICTS with the run itself:
+     * it asserts a file's existence is the failure, but that file is another task's
+     * committed deliverable (see annotateDebtConflicts). A conflicting debt is a
+     * PLAN defect to surface, never an instruction to act on — mx5 run 11's autofix
+     * child `rm`'d TASK_0008's verified admin page to satisfy exactly such a claim.
+     */
+    conflict?: string;
 }
 export declare function acceptDebtFile(cwd: string): string;
 /** The raw stored ledger ('' when none recorded yet). Parse with parseAcceptDebts. */
@@ -61,10 +69,29 @@ export declare function recheckAcceptDebts(debts: AcceptDebt[], opts: {
     open: AcceptDebt[];
     resolved: AcceptDebt[];
 };
+/**
+ * Extract the paths whose EXISTENCE the reason asserts as the failure — a path
+ * token immediately followed by "exists" / "still exists", or by "must/should not
+ * exist". Only this narrow shape qualifies: a reason that merely MENTIONS a path
+ * (a prohibition violation, a broken import) is an ordinary defect claim, not an
+ * existence assertion, and must never be flagged (run 11's T1/T7 debts name paths
+ * this way and are genuine).
+ */
+export declare function extractExistenceClaims(reason: string): string[];
+/**
+ * Annotate each debt whose existence-as-failure claim names a file INTRODUCED by a
+ * different task's commit (per `introducedBy`, typically git history) with a
+ * human-readable conflict statement. Everything degrades to no annotation: no
+ * existence claim, an unknown introducer, or the debt's own task introducing the
+ * file (then the claim is at least self-consistent) all pass through unchanged.
+ */
+export declare function annotateDebtConflicts(debts: AcceptDebt[], introducedBy: (path: string) => string | null): AcceptDebt[];
 /**
  * A one-line-per-debt suffix appended to the final gate's report reason so the still
  * -open accepted defects surface in the gate outcome the user sees (and in the fail
- * picker). Empty when nothing is open.
+ * picker). Empty when nothing is open. The header states the records' status
+ * explicitly: they are claims for the HUMAN, re-stated by the gate, never
+ * instructions — and a conflicting claim carries its contradiction inline.
  */
 export declare function buildAcceptDebtNote(open: AcceptDebt[]): string;
 /** One-line provenance label for a debt, for the surfaced report. */

package/dist/task/accept-debt.js

@@ -182,17 +182,75 @@ export function recheckAcceptDebts(debts, opts) {
     }
     return { open, resolved };
 }
+// ─── Conflicting-claim classification (mx5 run 11) ──────────────────────────
+//
+// A recorded debt is a CLAIM about the tree, not an instruction to change it. The
+// one class a deterministic check can prove SELF-CONTRADICTORY is an
+// existence-as-failure claim ("<path> exists" fails the verify) whose named path is
+// a DIFFERENT task's committed deliverable: the plan shipped the file on purpose
+// and a sibling's verify indicts it — a plan defect (sibling scope-fence leaked
+// into a verify assertion), not a fixable fault. Run 11's TASK_0009 debt read
+// "src/client/pages/admin.tsx exists (introduced by prior TASK_0008…)" and the
+// final-gate autofix child, seeded with it, ran `rm` on the verified page.
+/** A path-like token: at least one directory separator, ending in a file name. */
+const PATH_TOKEN_RE = /(?:[\w.@-]+\/)+[\w.@-]+\.\w+/g;
+/**
+ * Extract the paths whose EXISTENCE the reason asserts as the failure — a path
+ * token immediately followed by "exists" / "still exists", or by "must/should not
+ * exist". Only this narrow shape qualifies: a reason that merely MENTIONS a path
+ * (a prohibition violation, a broken import) is an ordinary defect claim, not an
+ * existence assertion, and must never be flagged (run 11's T1/T7 debts name paths
+ * this way and are genuine).
+ */
+export function extractExistenceClaims(reason) {
+    const out = [];
+    for (const m of reason.matchAll(PATH_TOKEN_RE)) {
+        const after = reason.slice(m.index + m[0].length);
+        if (/^\s+(?:still\s+)?exists\b/.test(after)
+            || /^\s+(?:must|should)\s+not\s+exist\b/.test(after)) {
+            out.push(m[0]);
+        }
+    }
+    return [...new Set(out)];
+}
+/**
+ * Annotate each debt whose existence-as-failure claim names a file INTRODUCED by a
+ * different task's commit (per `introducedBy`, typically git history) with a
+ * human-readable conflict statement. Everything degrades to no annotation: no
+ * existence claim, an unknown introducer, or the debt's own task introducing the
+ * file (then the claim is at least self-consistent) all pass through unchanged.
+ */
+export function annotateDebtConflicts(debts, introducedBy) {
+    return debts.map(d => {
+        for (const p of extractExistenceClaims(d.reason)) {
+            const producer = introducedBy(p);
+            if (producer && producer !== d.taskId) {
+                return {
+                    ...d,
+                    conflict: `\`${p}\` is ${producer}'s committed deliverable — this assertion `
+                        + `contradicts a sibling task's shipped work (a plan defect, not a fix `
+                        + `instruction); do NOT delete or rewrite that deliverable to satisfy it`
+                };
+            }
+        }
+        return d;
+    });
+}
 /**
  * A one-line-per-debt suffix appended to the final gate's report reason so the still
  * -open accepted defects surface in the gate outcome the user sees (and in the fail
- * picker). Empty when nothing is open.
+ * picker). Empty when nothing is open. The header states the records' status
+ * explicitly: they are claims for the HUMAN, re-stated by the gate, never
+ * instructions — and a conflicting claim carries its contradiction inline.
  */
 export function buildAcceptDebtNote(open) {
     if (open.length === 0)
         return '';
-    const items = open.map(d => `${d.taskId || '(unknown task)'} — ${describeDebt(d)}: ${d.reason}`);
+    const items = open.map(d => `${d.taskId || '(unknown task)'} — ${describeDebt(d)}: ${d.reason}`
+        + (d.conflict ? `\n    ⚠ CONFLICTING CLAIM — ${d.conflict}` : ''));
     return (`\n\nUNRESOLVED VERIFY-FAIL DEBT still open (${open.length}) — `
-        + 'these defects were recorded during the run and are NOT re-verified by this gate:\n'
+        + 'these defects were recorded during the run and are NOT re-verified by this gate. '
+        + 'They are records for a human decision, not instructions to edit code:\n'
         + items.map(i => `  - ${i}`).join('\n'));
 }
 /** One-line provenance label for a debt, for the surfaced report. */

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

@@ -20,8 +20,10 @@ export interface CoverageVerdict {
 export declare function parseCoverageVerdict(raw: string): CoverageVerdict | null;
 /** Parse the "## tasks" checkbox list. */
 export declare function parseTaskList(body: string): TaskEntry[];
-/** Build the initial AUTO-file body. */
-export declare function buildAutoBody(feature: string, clarifications: string, titles: string[]): string;
+/** Build the initial AUTO-file body. `coverage` is the requirement-level
+ *  accounting summary (goal A(c) — a durable, user-visible record of what was
+ *  carried cross-cutting and what stayed unowned); '' omits the section. */
+export declare function buildAutoBody(feature: string, clarifications: string, titles: string[], coverage?: string): string;
 /** Check off the Nth checkbox line, stamping the produced TASK_NNNN id. */
 export declare function checkOffTask(cwd: string, id: string, index: number, producedId: string, title: string): Promise<void>;
 /**

package/dist/task/auto-io.js

@@ -91,12 +91,15 @@ export function parseTaskList(body) {
     }
     return entries;
 }
-/** Build the initial AUTO-file body. */
-export function buildAutoBody(feature, clarifications, titles) {
+/** Build the initial AUTO-file body. `coverage` is the requirement-level
+ *  accounting summary (goal A(c) — a durable, user-visible record of what was
+ *  carried cross-cutting and what stayed unowned); '' omits the section. */
+export function buildAutoBody(feature, clarifications, titles, coverage = '') {
     const tasks = titles.map(t => `- [ ] ${t}`).join('\n');
     return (`\n## feature prompt\n\n${feature.trim() || '(none)'}\n\n`
         + `## clarifications\n\n${clarifications.trim() || '(none)'}\n\n`
-        + `## tasks\n\n${tasks}\n`);
+        + `## tasks\n\n${tasks}\n`
+        + (coverage.trim().length > 0 ? `\n## coverage\n\n${coverage.trim()}\n` : ''));
 }
 /** Rewrite the Nth checkbox line of the "## tasks" section in place. */
 async function rewriteTaskLine(cwd, id, index, render, label) {

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

@@ -33,6 +33,7 @@ export interface AutoDeps extends GateDeps {
     finalGate?: (cwd: string, planText?: string) => Promise<{
         ok: boolean;
         reason: string;
+        debtNote?: string;
         openDebts?: AcceptDebt[];
     }>;
     /**

package/dist/task/auto-orchestrator.js

@@ -32,7 +32,9 @@ import { classifyFinalGateAnswer, MAX_FINAL_GATE_AUTOFIX, FINAL_LEAVE_LABEL, FIN
 import { getConfig } from '../config/config.js';
 import { configureResearchRun } from '../workers/research-cache.js';
 import { CONTRACT_EXTRACT_PROMPT, parseContractLines, keepGroundedContracts, appendContracts } from './contracts.js';
-import { LAUNCH_EXTRACT_PROMPT, parseScriptLines, keepGroundedScripts, appendDeclaredScripts } from './launch-contract.js';
+import { reconcileTitleSources } from './decompose-fidelity.js';
+import { REQUIREMENT_EXTRACT_PROMPT, COVERAGE_MAP_PROMPT, parseRequirementLines, keepGroundedRequirements, capRequirements, enumerateObligationPassages, uncoveredPassages, extractionRetryHint, parseCoverageMap, accountCoverage, appendCarriedRequirements, buildRequirementsLedger } from './requirements.js';
+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.
@@ -436,10 +438,57 @@ export async function planAuto(ctx, cwd, feature, deps) {
         ctx.ui.notify('No clarifying questions needed — planning tasks…', 'info');
     }
     const clarifications = answers.join('\n');
+    // Requirement extraction (mx5 run 11, goal A): grounded requirement units,
+    // extracted from whatever structure the spec has, BEFORE decompose — they ride
+    // into the decompose prompt as a ledger (structure-mirroring can't discharge
+    // them) and drive the per-requirement coverage accounting below. Best-effort:
+    // a fault leaves reqEntries empty and the whole channel degrades to the old
+    // behavior (one-liners / doc-less features naturally yield few or none).
+    let reqEntries = [];
+    try {
+        // Recall floor: the obligation-marked passages ride into the prompt as a
+        // checklist, and a marked passage that produced NO quote is hard evidence
+        // for one forced re-extraction (measured live: 1/5 extractions missed the
+        // entire marked testing section without this).
+        const passages = enumerateObligationPassages(featureForModel);
+        const extractOnce = async (hint) => keepGroundedRequirements(parseRequirementLines(await deps.runChild('requirement-extract', '', prependHint(hint, REQUIREMENT_EXTRACT_PROMPT(featureForModel, passages)))), featureForModel);
+        reqEntries = await extractOnce(null);
+        const uncovered = uncoveredPassages(passages, reqEntries);
+        if (uncovered.length > 0) {
+            logPlanDebug(cwd, `requirement extraction: ${uncovered.length} obligation-marked passage(s) `
+                + 'uncovered — forcing one re-extraction');
+            const retry = await extractOnce(extractionRetryHint(uncovered));
+            // Union of both grounded passes (keepGrounded dedupes).
+            reqEntries = keepGroundedRequirements([...reqEntries, ...retry], featureForModel);
+        }
+        // Bound with marked-passage priority — a plain first-N cap truncates the
+        // doc's tail sections (measured live: an eager model fills 40 top-down).
+        reqEntries = capRequirements(reqEntries, passages);
+        logPlanDebug(cwd, `requirement extraction: ${reqEntries.length} grounded requirement(s) kept`);
+    }
+    catch {
+        // best-effort channel
+    }
     // decompose
-    const decomposePrompt = AUTO_DECOMPOSE_PROMPT(featureForModel, clarifications);
+    const decomposePrompt = AUTO_DECOMPOSE_PROMPT(featureForModel, clarifications, buildRequirementsLedger(reqEntries));
+    // Parse + FIDELITY RECONCILIATION (mx5 run 11, goal B): 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,
+    // suspect-retry, coverage-retry — so no path ships an unreconciled list.
+    const parsePlan = (raw) => {
+        const plan = reconcileTitleSources(parseDecomposeList(raw), featureForModel);
+        if (plan.sourced > 0 || plan.restored.length > 0) {
+            logPlanDebug(cwd, `decompose fidelity: ${plan.sourced}/${plan.titles.length} titles cited a grounded source; `
+                + `${plan.restored.length} restoration(s)`
+                + plan.restored
+                    .map(r => ` [task ${r.index + 1}: ${r.fragments.join(', ')}]`)
+                    .join(''));
+        }
+        return plan.titles;
+    };
     const listRaw = await deps.runChild('auto-decompose', 'read', decomposePrompt);
-    let planTitles = parseDecomposeList(listRaw);
+    let planTitles = parsePlan(listRaw);
     logPlanDebug(cwd, `decompose produced ${planTitles.length} title(s)`);
     // 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
@@ -450,7 +499,7 @@ export async function planAuto(ctx, cwd, feature, deps) {
         logPlanDebug(cwd, `decompose suspect (${planTitles.length} title(s) for a ${featureForModel.length}-char spec)`
             + ` — raw output: ${listRaw.trim().slice(0, 300)}`);
         const retryRaw = await deps.runChild('auto-decompose', 'read', prependHint(suspectPlanHint(planTitles.length), decomposePrompt));
-        const retryTitles = parseDecomposeList(retryRaw);
+        const retryTitles = parsePlan(retryRaw);
         logPlanDebug(cwd, `decompose suspect-retry produced ${retryTitles.length} title(s)`);
         if (retryTitles.length > planTitles.length)
             planTitles = retryTitles;
@@ -472,20 +521,48 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // re-judged the same unchanged list, and the known-incomplete plan shipped
     // with no warning.
     let unresolvedMissing = null;
+    // The last per-requirement accounting (goal A): completeness is computed
+    // HOST-SIDE from it — a holistic "COMPLETE" alone can no longer pass a plan
+    // while grounded requirements sit unowned (run 11: milestone-parity satisfied
+    // the judge while §10 Testing had zero tasks). Null when no requirements were
+    // extracted or every mapping call faulted (⇒ old judge-only behavior).
+    let accounting = null;
     for (let round = 0; round < MAX_COVERAGE_ROUNDS && planTitles.length > 0; round++) {
+        // Signal 1 — the holistic judge (kept as the belt; catches feature areas
+        // the requirement extraction itself missed). A fault yields no signal.
         let verdict;
         try {
             verdict = parseCoverageVerdict(await deps.runChild('decompose-coverage', '', DECOMPOSE_COVERAGE_PROMPT(featureForModel, clarifications, planTitles)));
         }
         catch {
-            // Judge fault: unknown coverage, not known-missing — stay silent.
-            unresolvedMissing = null;
-            break;
+            verdict = null;
         }
-        if (verdict === null || verdict.kind === 'complete') {
+        const verdictMissing = verdict?.kind === 'incomplete' ? verdict.missing : [];
+        // Signal 2 — the per-requirement map (the lever): every grounded
+        // requirement gets a falsifiable verdict (TASK n / CROSS-CUTTING / NONE);
+        // the host, not the model, decides what is uncovered. A fault keeps the
+        // previous round's accounting.
+        if (reqEntries.length > 0) {
+            try {
+                const mapRaw = await deps.runChild('coverage-map', '', COVERAGE_MAP_PROMPT(reqEntries, planTitles));
+                accounting = accountCoverage(reqEntries, parseCoverageMap(mapRaw, reqEntries.length, planTitles.length));
+                logPlanDebug(cwd, `coverage-map round ${round + 1}: ${accounting.mapped.length} task-mapped, `
+                    + `${accounting.crossCutting.length} cross-cutting, `
+                    + `${accounting.unmapped.length} unmapped`);
+            }
+            catch {
+                // mapping fault — keep whatever accounting an earlier round produced
+            }
+        }
+        const unmappedQuotes = (accounting?.unmapped ?? []).map(e => `"${e.quote}"`);
+        const missing = [...verdictMissing, ...unmappedQuotes];
+        if (missing.length === 0) {
             unresolvedMissing = null;
             logPlanDebug(cwd, `decompose-coverage round ${round + 1}: `
-                + (verdict === null ? 'no verdict — accepting list' : 'COMPLETE'));
+                + (verdict === null ? 'no judge verdict' : 'judge COMPLETE')
+                + (reqEntries.length > 0 ?
+                    ' and every grounded requirement is task-mapped or cross-cutting'
+                    : ' — accepting list'));
             // A COMPLETE on a still-suspect plan is the judge's known live
             // false-pass mode (bare verdict, indistinguishable from a real one).
             // The plan still ships — the floor never rejects on count — but
@@ -496,11 +573,11 @@ export async function planAuto(ctx, cwd, feature, deps) {
             }
             break;
         }
-        unresolvedMissing = verdict.missing;
+        unresolvedMissing = missing;
         logPlanDebug(cwd, `decompose-coverage round ${round + 1}: INCOMPLETE — missing: `
-            + verdict.missing.join('; ').slice(0, 300));
-        const retryRaw = await deps.runChild('auto-decompose', 'read', prependHint(coverageRepromptHint(verdict.missing), decomposePrompt));
-        const retryTitles = parseDecomposeList(retryRaw);
+            + missing.join('; ').slice(0, 300));
+        const retryRaw = await deps.runChild('auto-decompose', 'read', prependHint(coverageRepromptHint(missing), decomposePrompt));
+        const retryTitles = parsePlan(retryRaw);
         logPlanDebug(cwd, `decompose retry produced ${retryTitles.length} title(s)`);
         if (retryTitles.length > 0 && retryTitles.length * 2 >= planTitles.length) {
             planTitles = retryTitles;
@@ -517,6 +594,22 @@ export async function planAuto(ctx, cwd, feature, deps) {
             + unresolvedMissing.join('; ').slice(0, 300));
         ctx.ui.notify(`/task-auto: plan may be missing coverage — ${unresolvedMissing.join('; ').slice(0, 200)} — review the plan before running.`, 'warning');
     }
+    // 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
+    // too — marked — and recorded user-visibly in the plan file, never dropped.
+    if (accounting !== null) {
+        await appendCarriedRequirements(cwd, accounting.crossCutting, accounting.unmapped);
+        if (accounting.crossCutting.length > 0 || accounting.unmapped.length > 0) {
+            ctx.ui.notify(`/task-auto: carrying ${accounting.crossCutting.length} cross-cutting`
+                + (accounting.unmapped.length > 0 ?
+                    ` and ${accounting.unmapped.length} unowned`
+                    : '')
+                + ' requirement(s) into every task — see .pi-tasks/requirements.md.', 'info');
+        }
+    }
     // Cross-slice contract registry (mx5 run 8, F3): 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
@@ -540,9 +633,14 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // 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. Best-effort.
+    // manifest diff can never false-flag a hallucinated script. Recall is mechanical
+    // (mx5 run 11): 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.
+    // Best-effort.
     try {
-        const scriptRaw = await deps.runChild('launch-extract', '', LAUNCH_EXTRACT_PROMPT(featureForModel));
+        const scriptRaw = await deps.runChild('launch-extract', '', LAUNCH_EXTRACT_PROMPT(featureForModel, enumerateScriptCandidates(featureForModel)));
         const grounded = keepGroundedScripts(parseScriptLines(scriptRaw), featureForModel);
         logPlanDebug(cwd, `launch-contract extraction: ${grounded.length} grounded script(s) kept`
             + ` from ${parseScriptLines(scriptRaw).length} emitted`);
@@ -571,7 +669,16 @@ export async function planAuto(ctx, cwd, feature, deps) {
         updated_at: now,
         title: deriveTitle(feature)
     };
-    await writeTaskFile(cwd, fm, buildAutoBody(feature, clarifications, titles));
+    // Durable, user-visible coverage record (goal A(c)): what was carried and what
+    // stayed unowned lives in the plan file itself, not only in a transient toast.
+    const coverageNote = accounting === null ? '' : ([
+        `${reqEntries.length} grounded requirement(s): ${accounting.mapped.length} task-mapped, `
+            + `${accounting.crossCutting.length} cross-cutting (carried into every task via `
+            + `.pi-tasks/requirements.md), ${accounting.unmapped.length} unowned`,
+        ...accounting.crossCutting.map(e => `- carried: "${e.quote}"`),
+        ...accounting.unmapped.map(e => `- UNOWNED (no task covers this): "${e.quote}"`)
+    ].join('\n'));
+    await writeTaskFile(cwd, fm, buildAutoBody(feature, clarifications, titles, coverageNote));
     return id;
 }
 /** The two feature-level planning children, shown as steps in the loader. */
@@ -714,7 +821,7 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     // already a human decision, so this reports, it does not re-fail.
                     if (fin.openDebts && fin.openDebts.length > 0) {
                         for (const d of fin.openDebts) {
-                            await recGate(`defect STILL OPEN — ${d.taskId || '(unknown task)'}: ${describeDebt(d)}: ${d.reason.slice(0, 240)}`);
+                            await recGate(`defect STILL OPEN — ${d.taskId || '(unknown task)'}: ${describeDebt(d)}: ${d.reason.slice(0, 240)}${d.conflict ? ` [CONFLICTING CLAIM — ${d.conflict}]` : ''}`);
                         }
                         active.ui.notify(`${id}: ${fin.openDebts.length} recorded verify-FAIL defect(s) are STILL unresolved at run end — see the gate trail.`, 'warning');
                     }
@@ -726,7 +833,10 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     let fixAttempts = 0;
                     while (!fin.ok) {
                         const canAutofix = deps.finalGateFix !== undefined && fixAttempts < MAX_FINAL_GATE_AUTOFIX;
-                        const question = `Final integration gate FAILED for ${id}.\n\n${fin.reason}\n\n`
+                        // The picker question shows the debts (the HUMAN weighs them);
+                        // the autofix seed below deliberately does not — mx5 run 11's
+                        // fix child executed a debt claim as an `rm` instruction.
+                        const question = `Final integration gate FAILED for ${id}.\n\n${fin.reason}${fin.debtNote ?? ''}\n\n`
                             + 'All tasks are checked off — this is the whole-repo check '
                             + '(the project’s own test/build/static commands, run unaided).'
                             + (fixAttempts > 0 ?
@@ -772,7 +882,13 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                             active.ui.notify(`${id}: final-gate autofix did not converge — ${fix.reason.slice(0, 140)}`, 'warning');
                             // Work from the FRESH gate failure when the fix pass got
                             // as far as re-running the gate; otherwise keep the last.
-                            fin = { ok: false, reason: fix.gateReason ?? fin.reason };
+                            // The debt note is carried so the next picker still shows
+                            // the open claims (the seed never includes it).
+                            fin = {
+                                ok: false,
+                                reason: fix.gateReason ?? fin.reason,
+                                debtNote: fin.debtNote
+                            };
                             continue;
                         }
                         // Leave failed — the dismissal default, unchanged from the

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

@@ -1,7 +1,3 @@
-/**
- * Prompts for /task-auto's two feature-level child calls. These produce a task
- * LIST only; all research/spec depth is /task's job, run per-title later.
- */
 /**
  * Clarify: asks ONE question at a time. Output MUST match parseClarifyList — a
  * single numbered question followed by a "SUGGESTED: <default>" line, an optional
@@ -12,8 +8,12 @@
 export declare const AUTO_CLARIFY_PROMPT: (feature: string, priorQA: string) => string;
 /**
  * Decompose: output a markdown checkbox list of task titles (one line each).
+ * `requirementsLedger` is buildRequirementsLedger's grounded quote list (goal E's
+ * belt): the spec's obligations ride into decompose explicitly, so mirroring the
+ * spec's own milestone/section structure cannot silently discharge them. '' ⇒
+ * the prompt is unchanged.
  */
-export declare const AUTO_DECOMPOSE_PROMPT: (feature: string, clarifications: string) => string;
+export declare const AUTO_DECOMPOSE_PROMPT: (feature: string, clarifications: string, requirementsLedger?: string) => string;
 /**
  * Coverage triage: judge whether a decomposed task list covers the whole
  * feature. Guards the plan — the highest-leverage artifact in /task-auto —

package/dist/task/auto-prompts.js

@@ -2,6 +2,7 @@
  * Prompts for /task-auto's two feature-level child calls. These produce a task
  * LIST only; all research/spec depth is /task's job, run per-title later.
  */
+import { DECOMPOSE_SOURCE_RULE } from './decompose-fidelity.js';
 /**
  * Clarify: asks ONE question at a time. Output MUST match parseClarifyList — a
  * single numbered question followed by a "SUGGESTED: <default>" line, an optional
@@ -34,6 +35,7 @@ fork the breakdown). Account for the answers so far:
   real-time vs polling transport, search, deployment).
 - Skip anything /task will naturally resolve per-task during its own research.
 - Stay grounded in the referenced spec. If a design/spec doc is included above, do NOT propose a new subsystem, dependency, or requirement it does not call for, and do NOT re-ask a choice the spec already settles. Ask only about genuine forks the spec leaves open.
+- If the question or your SUGGESTED default locks the task breakdown to ONE part or structure of the spec (e.g. "follow the milestone list", "one task per section"), the SUGGESTED line must ALSO name the spec's other REQUIRED content that structure does not represent (a testing/security/quality section, cross-cutting rules) and state how each is carried — folded into every applicable task, or as its own task. Never present a structure-lock as settling the whole spec.
 
 YOU MUST propose a default answer for the question — every question you emit
 carries exactly one SUGGESTED line. Never omit it, never leave it blank, never
@@ -65,8 +67,12 @@ No question remains:
 NONE`;
 /**
  * Decompose: output a markdown checkbox list of task titles (one line each).
+ * `requirementsLedger` is buildRequirementsLedger's grounded quote list (goal E's
+ * belt): the spec's obligations ride into decompose explicitly, so mirroring the
+ * spec's own milestone/section structure cannot silently discharge them. '' ⇒
+ * the prompt is unchanged.
  */
-export const AUTO_DECOMPOSE_PROMPT = (feature, clarifications) => `Split this feature into an ordered list of implementation tasks. Each task
+export const AUTO_DECOMPOSE_PROMPT = (feature, clarifications, requirementsLedger = '') => `Split this feature into an ordered list of implementation tasks. Each task
 will be handed, by its title, to a separate pipeline that does its own research
 and writes its own spec — so here you produce TITLES ONLY, not specs.
 
@@ -75,7 +81,7 @@ ${feature.trim()}
 
 CLARIFICATIONS:
 ${clarifications.trim() || '(none)'}
-
+${requirementsLedger.trim().length > 0 ? `\n${requirementsLedger.trim()}\n` : ''}
 RULES:
 - One task per line, as a markdown checkbox: "- [ ] <title>".
 - Each title is a short imperative phrase; optionally add " — <one key detail>".
@@ -88,6 +94,7 @@ RULES:
   none. These are explicit user choices that may contradict the referenced spec
   doc; phrase them as imperative directives (e.g. "use Bun's built-in bundler, do
   not add vite"). Do NOT invent decisions — only restate ones from CLARIFICATIONS.
+${DECOMPOSE_SOURCE_RULE}
 - Output the checkbox list and NOTHING else (no preamble, no numbering).`;
 /**
  * Coverage triage: judge whether a decomposed task list covers the whole

package/dist/task/contracts.d.ts

@@ -7,6 +7,14 @@ export interface ContractEntry {
 export declare function contractsFile(cwd: string): string;
 /** The stored registry text ('' when none recorded yet). */
 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.
+ */
+export declare function normalise(s: string): string;
 /**
  * Parse `CONTRACT:` lines out of a child's answer text into entries. The line shape
  * the extraction prompt asks for is:

package/dist/task/contracts.js

@@ -52,9 +52,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.
+ * 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.
  */
-function normalise(s) {
+export function normalise(s) {
     return s.replace(/\s+/g, ' ').trim().toLowerCase();
 }
 /**

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

@@ -0,0 +1,47 @@
+export interface SourcedTitle {
+    /** The title with any source clause stripped. */
+    base: string;
+    /** The cited spec line, when present and grounded in the source doc. */
+    source?: string;
+}
+/** Split a decompose title into its base and its GROUNDED source citation.
+ *  An absent clause yields no source; a fabricated (ungrounded) one is stripped
+ *  and dropped — exactly like keepGroundedContracts rejects a paraphrased quote. */
+export declare function extractTitleSource(title: string, sourceDoc: string): SourcedTitle;
+/**
+ * The `+`-joined trailing constraint fragments of `sourceLine` whose words are
+ * absent from `title`. "2. **Auth** — sessions, login/logout/me, guards + tests."
+ * yields the fragment "tests"; a title that never mentions tests gets it back.
+ * Fragments before the first `+` are the task's body — a title paraphrases those
+ * freely and they are never judged here. A `+`-part is further split on commas
+ * ("+ Tailwind v4 tokens, nav, router" is three constraints), so a title missing
+ * one of them gets ONLY that one restored, not the whole phrase (measured live:
+ * whole-phrase restoration re-attached text the title already carried).
+ */
+export declare function findDroppedPlusFragments(sourceLine: string, title: string): string[];
+export interface TitleRestoration {
+    /** Index into the reconciled titles array. */
+    index: number;
+    /** The verbatim fragments re-attached to the title. */
+    fragments: string[];
+    /** The grounded source line they came from. */
+    source: string;
+}
+export interface ReconciledPlan {
+    titles: string[];
+    restored: TitleRestoration[];
+    /** How many titles carried a GROUNDED source citation (adoption signal). */
+    sourced: number;
+}
+/**
+ * Reconcile decompose output against the source doc: ground each citation, strip
+ * the clause (its job ends here), and re-attach any dropped `+`-fragments to the
+ * title verbatim so downstream refine/compose — which see ONLY the title — get
+ * the constraint back. Titles without a citation pass through unchanged, so a
+ * model that never cites degrades to exactly the old behavior.
+ */
+export declare function reconcileTitleSources(titles: string[], sourceDoc: string): ReconciledPlan;
+/** The decompose-prompt rule that makes titles citable (the belt half; the host
+ *  grounding + restoration above is the lever). Kept here so prompt and parser
+ *  can't drift apart. */
+export declare const DECOMPOSE_SOURCE_RULE: string;