@mjasnikovs/pi-task 0.37.7 → 0.38.0

package/dist/task/run-final-gate.js

@@ -0,0 +1,492 @@
+import { describeDebt, recordDebt } from './accept-debt.js';
+import { cancelCheckpoint } from './cancel-points.js';
+import { SessionUI } from '../remote/bridge.js';
+import { isYoloMode, yoloFinalGateChoice, YOLO_STAMP } from './yolo.js';
+import { ignoredWriteTrailLine, ignoredWriteDebtReason } from './write-guard.js';
+import { readOwnedRequirements } from './requirements.js';
+import { unclaimedPendingRequirements } from './owned-freeze-reassign.js';
+import { applyDemotions, isNonProgress, normalizeFailureDetail, rankedFirstFailure, unobservedDebtReason } from './final-gate-progress.js';
+import { classifyFinalGateAnswer, MAX_FINAL_GATE_AUTOFIX, FINAL_LEAVE_LABEL, FINAL_LEAVE_VALUE, FINAL_ACCEPT_LABEL, FINAL_ACCEPT_VALUE, FINAL_AUTOFIX_LABEL, FINAL_AUTOFIX_VALUE, STRANDED_FIX_COMMIT, strandedFixNote } from './final-gate-fix.js';
+/**
+ * Show the run-end picker and return the raw answer. Card ORDER is fixed —
+ * Leave-failed, then Autofix while the bound still allows it, then Accept — and
+ * Leave-failed is the recommendation on every branch: a run that could not green the
+ * whole-repo gate has not produced a working project. Same SessionUI.ask the
+ * clarify/grill/verify dialogs use, so a remote device answers it too.
+ */
+async function askFinalGateResolution(ctx, question, canAutofix) {
+    return new SessionUI(ctx).ask({
+        localTitle: 'Final integration gate failed — how should pi proceed?',
+        displayQuestion: question,
+        question,
+        recommended: FINAL_LEAVE_LABEL,
+        recommended2: canAutofix ? FINAL_AUTOFIX_LABEL : FINAL_ACCEPT_LABEL,
+        allowSkip: false,
+        options: [
+            { label: FINAL_LEAVE_LABEL, value: FINAL_LEAVE_VALUE },
+            ...(canAutofix ? [{ label: FINAL_AUTOFIX_LABEL, value: FINAL_AUTOFIX_VALUE }] : []),
+            { label: FINAL_ACCEPT_LABEL, value: FINAL_ACCEPT_VALUE }
+        ]
+    });
+}
+/** The run-completion announcement: a run that completed on statics alone must not
+ *  read like one whose product was actually exercised. */
+function completedResult(id, taskCount, unobservedNote) {
+    return {
+        kind: 'completed',
+        message: `${id} complete — all ${taskCount} tasks done.`
+            + (unobservedNote ?
+                ' WARNING: the final integration gate was UNOBSERVED — it ran no '
+                    + 'dynamic check at all, so "complete" here means the statics '
+                    + 'passed and nothing more. Carried as debt for the next run.'
+                : ''),
+        level: unobservedNote ? 'warning' : 'info'
+    };
+}
+/**
+ * Run the whole-repo gate and resolve its verdict with the user.
+ *
+ * Lifted verbatim out of /task-auto's run loop, which it never shared state with:
+ * the stage reads no per-task variable and writes none. Never throws for a gate
+ * outcome — only a user cancel inside a gate child propagates (the caller's
+ * USER_CANCELLED path handles it).
+ */
+export async function runFinalGateStage(active, deps, p) {
+    const { cwd, runId: id, planText, taskCount } = p;
+    // SAFE CHECKPOINT (pre-final-gate): every task is checked off and committed and
+    // the whole-repo gate has not started. A resume re-enters this same stage and
+    // runs the gate then, so the run is left exactly where it was — not silently
+    // declared complete.
+    if (cancelCheckpoint('pre-final-gate')) {
+        return {
+            kind: 'cancelled',
+            message: `${id} cancelled before the final integration gate — resume with /task-auto-resume.`
+        };
+    }
+    if (!deps.finalGate)
+        return completedResult(id, taskCount, null);
+    /**
+     * The ONE place this stage reaches the durable debt ledger. Four distinct findings
+     * feed it — an UNOBSERVED gate, an ignored-path write the gate depends on, a
+     * converged autofix that observed nothing, and a check DEMOTED as unfalsifiable —
+     * and they stay four calls because they are four different facts about the run.
+     * What they no longer each restate is WHERE the debt goes: the run's own id, under
+     * origin 'final-gate', which is what the next run's gate re-checks.
+     */
+    const carryDebt = (reason) => recordDebt(cwd, id, reason, 'final-gate');
+    // Set when the gate finished having observed NOTHING dynamic. Declared out here so
+    // the run-completion announcement can say so.
+    let unobservedNote = null;
+    active.ui.notify(`${id}: running final integration gate…`, 'info');
+    // Run-level gate trail on the parent task file — same durable auditability
+    // contract as the per-task `## gates` records.
+    const recGate = async (line) => {
+        try {
+            await deps.record?.(cwd, id, line);
+        }
+        catch {
+            // recording must never break the gate
+        }
+    };
+    // Trail EVERY aggregated failure entry (mx5 run 13): the gate runs all sections
+    // and ranks the list; a single sliced reason line would re-hide everything past
+    // the first entry.
+    const trailGateFail = async (f) => {
+        const list = f.failures ?? [f.reason];
+        if (list.length <= 1) {
+            await recGate(`final-gate: FAIL — ${f.reason.slice(0, 300)}`);
+            return;
+        }
+        await recGate(`final-gate: FAIL — ${list.length} failures (ranked, most load-bearing first)`);
+        for (const [i, entry] of list.entries()) {
+            await recGate(`final-gate FAIL ${i + 1}/${list.length}: ${entry.slice(0, 300)}`);
+        }
+    };
+    let fin = await deps.finalGate(cwd, planText);
+    // Record the outcome symmetrically (mx5 run 10 item 7): only FAIL was ever
+    // trailed, so a PASSing gate was indistinguishable from a gate that never ran. The
+    // PASS reason names the commands that were run. THREE verdicts, not two
+    // (final-gate.ts unobservedVerdict): a gate that observed nothing dynamic is
+    // UNOBSERVED, never PASS — IAR1 shipped `PASS — no integration command found`
+    // twice while carrying open verify-FAIL debt. It does not block (justified there),
+    // but it is labelled here, warned about, and recorded as durable debt so the next
+    // run's gate re-surfaces it.
+    if (fin.ok && fin.unobserved) {
+        unobservedNote = fin.unobserved;
+        await recGate(`final-gate: UNOBSERVED — ${fin.reason.slice(0, 300)}`);
+        await carryDebt(fin.unobserved);
+        active.ui.notify(`${id}: the final integration gate observed NOTHING dynamic — `
+            + 'the run completed on static checks alone. Nothing verified '
+            + 'that the assembled product builds, boots or works.', 'warning');
+    }
+    else if (fin.ok) {
+        await recGate(`final-gate: PASS — ${fin.reason.slice(0, 300)}`);
+    }
+    else {
+        await trailGateFail(fin);
+    }
+    // ACCEPT-debt re-check surfacing (mx5 run 4 B3 / run 8 TASK_0012): tasks the user
+    // accepted despite a verify-FAIL that the gate could not prove resolved against the
+    // current tree. Surface them at the gate moment — on PASS or FAIL — so a run never
+    // completes silently carrying an accepted defect. Informational: the per-task
+    // ACCEPT was already a human decision, so this reports, it does not re-fail.
+    const debtKey = (d) => `${d.taskId}\t${d.reason}`;
+    const surfaceOpenDebts = async (debts) => {
+        if (debts.length === 0)
+            return;
+        for (const d of debts) {
+            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}: ${debts.length} recorded verify-FAIL defect(s) are STILL unresolved at run end — see the gate trail.`, 'warning');
+    };
+    // What was REPORTED, so a post-autofix re-derivation can be compared against it
+    // rather than blindly re-printed.
+    let reportedDebts = fin.openDebts ?? [];
+    await surfaceOpenDebts(reportedDebts);
+    // An owned obligation a task DETACHED (its own spec froze the only file that could
+    // satisfy it, nexttask 2) and no later task claimed. Detach never deletes the
+    // quote, so the run ends holding it — say so, or the resolution would be a quieter
+    // version of the deletion it exists to prevent.
+    const unclaimed = unclaimedPendingRequirements(await readOwnedRequirements(cwd).catch(() => []));
+    for (const o of unclaimed) {
+        await recGate(`owned requirement UNCLAIMED — "${o.quote.slice(0, 200)}"`
+            + ` [frozen in "${o.title.slice(0, 60)}"; no task claimed`
+            + ` ${(o.pending ?? []).join(', ')}]`);
+    }
+    if (unclaimed.length > 0) {
+        active.ui.notify(`${id}: ${unclaimed.length} authoritative design requirement(s) ended the run`
+            + ' owned by NO task — the task they were mapped to could not touch the'
+            + ' file, and nothing else claimed it. See the gate trail.', 'warning');
+    }
+    /**
+     * nexttask 6 (mx5 run 18). The lines above are emitted from the FIRST gate result;
+     * the converged-autofix paths below used to rebuild `fin` as `{ok, reason}`, so
+     * `openDebts` did not survive the fix pass — the run's last word on its own defects
+     * was a snapshot of a tree that no longer existed, and no code path could clear,
+     * re-check or act on it. Re-derive here, against the tree the run actually ends
+     * with, and correct the record.
+     *
+     * FP-safe by inheritance: `deriveOpenDebts` auto-closes only what a deterministic
+     * check can stand behind (a static-class debt when the statics provably pass, a
+     * cross-task-deletion whose file is back). Anything model-judged or behavioral
+     * STAYS OPEN — `inv-no-false-clear`. `staticOk` is therefore only ever passed true
+     * where the gate itself just passed the statics.
+     */
+    const reconcileDebts = async (staticOk) => {
+        if (!deps.recheckOpenDebts)
+            return;
+        let fresh;
+        try {
+            fresh = await deps.recheckOpenDebts(cwd, staticOk);
+        }
+        catch {
+            // A ledger read fault is inconclusive: say nothing rather than imply the
+            // defects cleared.
+            return;
+        }
+        fin = {
+            ...fin,
+            openDebts: fresh.openDebts,
+            ...(fresh.debtNote ? { debtNote: fresh.debtNote } : {})
+        };
+        // Per-debt evidence from the VERIFY-COMMAND re-check (nexttask 5): which
+        // command was re-run and what it did. A close that cannot be read back from
+        // the trail is a close nobody can audit, and an INCONCLUSIVE re-run is worth
+        // saying out loud — it is the difference between "still broken" and "nothing
+        // could observe it".
+        for (const line of fresh.trail ?? []) {
+            await recGate(`defect re-check: ${line}`);
+        }
+        // Identity is (task, origin, reason), but a RESOLUTION claim needs more than a
+        // key miss: a ledger entry whose TEXT changed is the same defect re-recorded,
+        // never a fix. So a debt counts as closed only when nothing for that (task,
+        // origin) survives.
+        const slot = (d) => `${d.taskId}\t${d.origin ?? ''}`;
+        const before = new Set(reportedDebts.map(debtKey));
+        const after = new Set(fresh.openDebts.map(debtKey));
+        const beforeSlots = new Set(reportedDebts.map(slot));
+        const afterSlots = new Set(fresh.openDebts.map(slot));
+        const closed = reportedDebts.filter(d => !after.has(debtKey(d)) && !afterSlots.has(slot(d)));
+        const added = fresh.openDebts.filter(d => !before.has(debtKey(d)) && !beforeSlots.has(slot(d)));
+        if (closed.length === 0 && added.length === 0) {
+            if (reportedDebts.length > 0) {
+                await recGate(`defect re-check after autofix: all ${reportedDebts.length} defect(s) `
+                    + 'above re-derived against the FINAL tree and still open');
+            }
+            return;
+        }
+        for (const d of closed) {
+            await recGate(`defect RESOLVED — ${d.taskId || '(unknown task)'}: ` + `${d.reason.slice(0, 240)}`);
+        }
+        await surfaceOpenDebts(added);
+        reportedDebts = fresh.openDebts;
+        await recGate(`defect re-check after autofix: ${closed.length} resolved, `
+            + `${fresh.openDebts.length} still open (re-derived against the FINAL tree)`);
+    };
+    // Resolution loop: Leave-failed (recommended) / Autofix (bounded, model-driven fix
+    // pass + gate re-run — run 7's gap: the picker had NO automated fix path) /
+    // Accept. The user always decides; after MAX_FINAL_GATE_AUTOFIX attempts that
+    // still FAIL the autofix card is withdrawn so the loop cannot run unbounded.
+    let fixAttempts = 0;
+    // Gitignored paths the fix passes have written so far in this resolution loop (mx5
+    // run 19). Accumulated across attempts: a `.env` written by a failed attempt is
+    // still on disk for the next one, and that attempt's own before/after diff cannot
+    // see it.
+    let ignoredWritten = [];
+    // Sub-fixes a non-converging autofix attempt left uncommitted. Refreshed after
+    // every attempt; drives the picker note and the terminal commit (mx5 run 13 PROMPT
+    // 4 item 3, run 14 item 2b).
+    let stranded = [];
+    const refreshStranded = async () => {
+        if (!deps.pendingChanges)
+            return;
+        try {
+            stranded = await deps.pendingChanges(cwd);
+        }
+        catch {
+            // Inconclusive: say nothing rather than claim a clean tree.
+            stranded = [];
+        }
+    };
+    // NON-PROGRESS / UNFALSIFIABLE-CHECK state (mx5 run 14 item 2a). `prevFailSig` is
+    // the previous attempt's normalized ranked-first failure; `demoted` holds the
+    // signatures already carried as debt, so a re-run that still reports them does not
+    // re-fail the gate.
+    let prevFailSig = null;
+    const demoted = new Set();
+    // Set when a write-guard rejected an attempt whose edits could NOT be discarded:
+    // REJECTED edits are then sitting in the tree and must never be committed by the
+    // terminal paths below.
+    let rejectedEditsInTree = false;
+    // Commit whatever guard-clean repairs the fix passes left, on ANY terminal
+    // non-converged outcome. Run 14 ended on LEAVE with 13 real repairs dirty in the
+    // tree after an unattended run — the next checkout would have destroyed them
+    // silently.
+    const commitStranded = async (outcome) => {
+        if (stranded.length === 0)
+            return;
+        if (rejectedEditsInTree) {
+            await recGate(`final-gate: NOT committing ${stranded.length} working-tree change(s) — a `
+                + `write-guard rejected an attempt and its edits could not be discarded, `
+                + `so the tree holds REJECTED edits: ${stranded.slice(0, 8).join(', ')}`);
+            return;
+        }
+        // REPORT WHAT ACTUALLY HAPPENED (mx5 run 20). This bound the CommitResult to
+        // `sha` and interpolated it, so the trail read "committed 5 stranded fix-pass
+        // change(s) as [object Object]". Worse than cosmetic: `commit` returns
+        // {committed, reason?, note?} and NEVER a sha, the `committed` field was never
+        // read, and gitCommitAll returns {committed:false} WITHOUT throwing on an
+        // unmerged index — so on that path the catch below never fires and the trail
+        // claimed a commit over changes that were still sitting in the working tree.
+        const notCommitted = async (why) => {
+            await recGate(`final-gate: could NOT commit ${stranded.length} stranded fix-pass `
+                + `change(s) (${why}) — they remain UNCOMMITTED in the working `
+                + `tree: ${stranded.slice(0, 8).join(', ')}`);
+        };
+        try {
+            const res = await deps.commit(cwd, STRANDED_FIX_COMMIT(id, outcome));
+            if (res.committed) {
+                await recGate(`final-gate: committed ${stranded.length} stranded fix-pass change(s)`
+                    + `${res.note ? ` (${res.note})` : ''} — ${stranded.slice(0, 8).join(', ')}`);
+            }
+            else {
+                await notCommitted(res.reason ?? 'unknown');
+            }
+        }
+        catch (err) {
+            // Never break the terminal path over this — but say so, so the changes are
+            // not silently lost.
+            await notCommitted(err instanceof Error ? err.message : String(err));
+        }
+    };
+    while (!fin.ok) {
+        const canAutofix = deps.finalGateFix !== undefined && fixAttempts < MAX_FINAL_GATE_AUTOFIX;
+        // 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 ?
+                `\n\nAutofix attempts so far: ${fixAttempts}/${MAX_FINAL_GATE_AUTOFIX}.`
+                : '')
+            // Never let a partial repair be invisible at the moment the human decides
+            // (run 13: a bunfig fix that made `bun run test` pass 116/116 was stranded
+            // by an ACCEPT).
+            + strandedFixNote(stranded);
+        // YOLO: keep autofixing WHILE the card is still offered — the loop withdraws it
+        // after MAX_FINAL_GATE_AUTOFIX, so the cap that bounds a non-converging fix pass
+        // still bounds this — then LEAVE the run failed. Never 'accept': an unattended
+        // run that could not green the whole-repo gate has not produced a working
+        // project, and mx5 run 13 shows what an accepted FAIL looks like afterwards (a
+        // shipped app that 404s at `/`).
+        const yoloFinal = yoloFinalGateChoice(isYoloMode(), canAutofix);
+        if (yoloFinal !== null) {
+            await recGate(`final-gate: auto-chose ${yoloFinal.action.toUpperCase()} ${YOLO_STAMP}`);
+        }
+        const answer = yoloFinal !== null ?
+            yoloFinal.action === 'autofix' ?
+                FINAL_AUTOFIX_VALUE
+                : FINAL_LEAVE_VALUE
+            : await askFinalGateResolution(active, question, canAutofix);
+        const choice = classifyFinalGateAnswer(answer);
+        if (choice.action === 'accept') {
+            await recGate('final-gate: FAIL accepted by user');
+            // STRANDED SUB-FIXES: the run completes here, so anything the fix pass
+            // repaired but never committed would be lost to the next `git checkout`
+            // while HEAD keeps the defect it fixed. Commit it as its own, named
+            // commit — the ACCEPT is a decision about the FAILING gate, never an
+            // instruction to throw away work (mx5 run 13 item 3).
+            await commitStranded('accepted');
+            active.ui.notify(`${id}: final integration gate FAIL accepted by user — completing.`
+                + (stranded.length > 0 ?
+                    ` ${stranded.length} uncommitted fix-pass change(s) committed separately.`
+                    : ''), 'warning');
+            break;
+        }
+        if (choice.action === 'autofix' && canAutofix) {
+            fixAttempts += 1;
+            await recGate(`final-gate: user chose AUTOFIX (attempt ${fixAttempts}/${MAX_FINAL_GATE_AUTOFIX})`);
+            active.ui.notify(`${id}: final-gate autofix (${fixAttempts}/${MAX_FINAL_GATE_AUTOFIX}) — bounded fix pass, then the gate re-runs…`, 'info');
+            const seed = choice.guidance ? `${fin.reason}\n\nUser guidance: ${choice.guidance}` : fin.reason;
+            const fix = await deps.finalGateFix(active, cwd, seed, ignoredWritten);
+            // IGNORED-PATH WRITES (mx5 run 19). The pass wrote file(s) git ignores, so
+            // they are not in the commit and a fresh clone does not have them. Trailed
+            // on EVERY outcome — a rejected attempt's tracked edits are discarded while
+            // its ignored writes survive on disk — and carried forward, so a later
+            // attempt's PASS is judged against everything this loop wrote, not just its
+            // own attempt. PATH NAMES ONLY: an ignored file's contents (`.env` is the
+            // canonical case) never enter a log, a debt or a child prompt.
+            if (fix.ignoredWrites && fix.ignoredWrites.length > 0) {
+                ignoredWritten = [...new Set([...ignoredWritten, ...fix.ignoredWrites])].sort();
+                await recGate(ignoredWriteTrailLine(fix.ignoredWrites));
+                // Debt only where a verdict can rest on the file: the probe proved the
+                // gate needs it, or the question stayed open. A write the gate
+                // demonstrably does NOT need is trailed and nothing more — a ledger
+                // full of scratch files is a ledger nobody reads.
+                if (fix.ignoredDependent !== false) {
+                    await carryDebt(ignoredWriteDebtReason(fix.ignoredWrites, fix.ignoredDependent));
+                }
+            }
+            if (fix.ok) {
+                await deps.commit(cwd, `FINAL GATE AUTOFIX (${id})`);
+                // A converged re-run that observed nothing dynamic is UNOBSERVED on
+                // this door too — never announce it as a PASS just because it arrived
+                // via autofix.
+                if (fix.unobserved) {
+                    unobservedNote = fix.unobserved;
+                    await carryDebt(fix.unobserved);
+                }
+                await recGate(`final-gate: autofix ${fix.unobserved ? 'ended UNOBSERVED' : 'converged'} — ${fix.reason.slice(0, 200)}`);
+                active.ui.notify(`${id}: final integration gate ${fix.unobserved ? 'is UNOBSERVED' : 'PASSES'} after autofix — ${fix.reason.slice(0, 140)}`, fix.unobserved ? 'warning' : 'info');
+                fin = { ok: true, reason: fix.reason };
+                // The gate itself just passed, statics included, so `staticOk` here is
+                // proof rather than assumption.
+                await reconcileDebts(true);
+                break;
+            }
+            await recGate(`final-gate: autofix attempt ${fixAttempts} failed — ${fix.reason.slice(0, 200)}`);
+            // A guard that rejected an attempt WITHOUT discarding leaves rejected edits
+            // behind: the terminal paths must not commit the tree after that (the cheat
+            // guard stays intact).
+            if (fix.guardTripped === true && fix.editsDiscarded !== true) {
+                rejectedEditsInTree = true;
+            }
+            // The attempt's edits survive a non-convergence (only a guard trip
+            // discards). Find out what they are NOW, so the next picker shows them and
+            // a terminal outcome commits them.
+            await refreshStranded();
+            if (stranded.length > 0) {
+                await recGate(`final-gate: autofix attempt ${fixAttempts} left ${stranded.length} `
+                    + `uncommitted change(s) — ${stranded.slice(0, 8).join(', ')}`);
+            }
+            active.ui.notify(`${id}: final-gate autofix did not converge — ${fix.reason.slice(0, 140)}`, 'warning');
+            // NON-PROGRESS CLASSIFIER (mx5 run 14 item 2a). An attempt that changed the
+            // tree, re-ran the gate, and got back the SAME ranked-first failure as the
+            // previous such attempt is evidence about the CHECK, not the fix: run 14
+            // burned all three attempts on a boot probe that could not observe a
+            // listener in that sandbox at all. Demote that one check to
+            // UNOBSERVED-with-debt and let the REMAINING checks decide.
+            const detail = rankedFirstFailure({
+                reason: fix.gateReason,
+                failures: fix.gateFailures
+            });
+            const edited = fix.gateReason !== undefined && stranded.length > 0;
+            if (detail !== null
+                && isNonProgress({ previousSignature: prevFailSig, currentDetail: detail, edited })) {
+                demoted.add(normalizeFailureDetail(detail));
+                prevFailSig = null;
+                await carryDebt(unobservedDebtReason(detail));
+                await recGate(`final-gate: check DEMOTED to UNOBSERVED after ${fixAttempts} tree-changing `
+                    + `attempts returned an identical failure — carried as debt (origin final-gate) `
+                    + `and re-checked by the next run's gate: ${detail.slice(0, 240)}`);
+                active.ui.notify(`${id}: final-gate check is unfalsifiable in this environment — carried as debt; `
+                    + 'the remaining checks decide convergence.', 'warning');
+            }
+            else {
+                prevFailSig = detail !== null ? normalizeFailureDetail(detail) : null;
+            }
+            // Convergence on the REMAINING checks: a demoted signature no longer counts
+            // against the gate. Nothing left ⇒ the run converges carrying the demotion
+            // as debt, and the fix passes' repairs are committed rather than stranded.
+            if (demoted.size > 0 && fix.gateReason !== undefined) {
+                const remaining = applyDemotions(fix.gateFailures ?? [fix.gateReason], demoted);
+                if (remaining.length === 0) {
+                    await deps.commit(cwd, `FINAL GATE AUTOFIX (${id})`);
+                    const converged = `converged on all remaining checks; ${demoted.size} check(s) `
+                        + 'carried as UNOBSERVED debt (unfalsifiable in this environment)';
+                    await recGate(`final-gate: ${converged}`);
+                    active.ui.notify(`${id}: final integration gate converged — ${converged}.`, 'warning');
+                    fin = { ok: true, reason: converged };
+                    // Converged on the REMAINING checks only: one or more were DEMOTED
+                    // as unfalsifiable here, and the statics may be among them. No
+                    // proof ⇒ pass false, so nothing static-class can auto-close on
+                    // this door (inv-no-false-clear).
+                    await reconcileDebts(false);
+                    break;
+                }
+            }
+            // Work from the FRESH gate failure when the fix pass got as far as
+            // re-running the gate; otherwise keep the last. The full ranked list rides
+            // along (and is re-trailed when fresh) so the next picker and the next fix
+            // seed still carry every entry, not just the first. The debt note is
+            // carried so the next picker still shows the open claims (the seed never
+            // includes it). Demoted checks are stripped from what rides forward, so the
+            // next picker and the next fix seed target only what is still falsifiable —
+            // never re-aiming the child at the check the classifier just proved it
+            // cannot move.
+            const freshFailures = fix.gateReason !== undefined ? fix.gateFailures : fin.failures;
+            const carried = freshFailures !== undefined ? applyDemotions(freshFailures, demoted) : undefined;
+            fin = {
+                ok: false,
+                reason: demoted.size > 0 && carried !== undefined && carried.length > 0 ?
+                    carried[0]
+                    : (fix.gateReason ?? fin.reason),
+                failures: carried,
+                debtNote: fin.debtNote
+            };
+            if (fix.gateReason !== undefined && (fix.gateFailures?.length ?? 0) > 1) {
+                await trailGateFail(fin);
+            }
+            continue;
+        }
+        // Leave failed — the dismissal default, unchanged from the two-option picker
+        // (an unavailable autofix demotes here too).
+        await recGate(yoloFinal !== null ?
+            `final-gate: left failed — autofix budget spent, nobody to ask ${YOLO_STAMP}`
+            : 'final-gate: left failed (user)');
+        // Leaving the run failed is TERMINAL for an unattended run, so the fix passes'
+        // guard-clean repairs are committed here too — run 14 left 13 of them dirty for
+        // a `git checkout` to destroy (mx5 run 13 item 3, run 14 item 2b). The user
+        // still owns the outcome; they own it with the work in HEAD, named in the trail.
+        await commitStranded('left-failed');
+        return {
+            kind: 'failed',
+            message: `${id} finished all tasks but FAILED the final integration gate — ${fin.reason.slice(0, 200)} — fix and /task-auto-resume (the gate re-runs).`
+                + (stranded.length > 0 ?
+                    ` NOTE: ${stranded.length} fix-pass change(s) were committed separately (${stranded.slice(0, 4).join(', ')}).`
+                    : '')
+        };
+    }
+    return completedResult(id, taskCount, unobservedNote);
+}

package/dist/task/task-gates.d.ts

@@ -35,6 +35,7 @@ import type { VerifyOutcome } from './verify-work.js';
 import type { EnforceOutcome } from './enforce-guidelines.js';
 import { type ResolutionOutcome, type ResolutionChoice } from './verify-resolution.js';
 import { type RepairCandidate } from './root-cause-repair.js';
+import { type DebtOrigin } from './accept-debt.js';
 /**
  * The deps the gate sequence drives. A superset of these is built once per command
  * by buildGateDeps; AutoDeps extends this with the planning-only `runChild`. Every
@@ -125,68 +126,30 @@ export interface GateDeps {
      */
     record?: (cwd: string, taskId: string, line: string) => Promise<void>;
     /**
-     * Record a durable ACCEPT-despite-verify-FAIL debt (task id + FAIL reason) to the
-     * run-level ledger (`.pi-tasks/accept-debt.md`, see accept-debt.ts). Called only on
-     * the picker's ACCEPT branch — the human blessed a failing artifact as-is, so the
-     * defect is real and recorded; the final integration gate re-checks it at run end
-     * and surfaces it if still open. Best-effort; absent in tests → no ledger written.
+     * Record ONE durable defect to the run-level ledger (`.pi-tasks/accept-debt.md`,
+     * see accept-debt.ts), stamped with the DebtOrigin that says how it was reached.
+     * The final integration gate re-checks every recorded debt at run end and surfaces
+     * the ones still open, so a defect the gate found is never lost by whatever the
+     * loop then did with the WORK — accepted by a human ('accepted'), auto-picked
+     * unattended by yolo mode ('yolo-accepted'), reverted with the enforce commit
+     * ('enforce-revert'), kept because the enforce diff could not have caused it
+     * ('enforce-kept'), blocked by a spec-frozen path ('frozen-blocked'), a sibling's
+     * deliverable deleted and accepted ('cross-task-deletion'), or another task's
+     * pre-existing bug this one merely tripped over ('root-cause').
+     *
+     * The ORIGIN is load-bearing, not a label: the final gate reports by class, and
+     * an unattended auto-pick may never be recorded as the 'accepted' class, which
+     * asserts a human weighed the failing artifact. Best-effort; absent in tests →
+     * no ledger written.
      */
-    recordAcceptDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
-    /**
-     * Record a durable YOLO-ACCEPTED debt: the same ACCEPT branch, but reached by an
-     * unattended auto-pick (yolo mode) rather than a human. Separate dep — and
-     * separate ledger origin — because collapsing the two would let an auto-pick
-     * read as "a human blessed this" in the final gate's run-end report. Best-effort;
-     * absent in tests → no ledger written.
-     */
-    recordYoloAcceptDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
-    /**
-     * Record a durable ENFORCE-REVERT debt (mx5 run 10 item 3): the enforce re-verify
-     * FAILED and the enforce edits were reverted, but the FAIL indicts the ORIGINAL
-     * work (run 10 TASK_0004: "Missing server entry point … the Hono server cannot be
-     * started"). Without this the diagnosis dies with the revert; recorded, the final
-     * gate re-checks and surfaces it like an accept-debt. Best-effort; absent in tests.
-     */
-    recordEnforceRevertDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
-    /**
-     * Record a durable FROZEN-BLOCKED debt (mx5 run 12 / PROMPT 1 layer B): a
-     * repo-health FAIL whose only fix is an edit to a path THIS task's spec froze —
-     * a cross-task contradiction. Recorded when the loop routes such a FAIL to the
-     * picker (whatever the human then picks, the defect is real and no task may fix
-     * it), so the final gate re-checks it at run end. Best-effort; absent in tests.
-     */
-    recordFrozenBlockedDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
-    /**
-     * Record a durable CROSS-TASK DELETION debt (mx5 run 12 PROMPT 2): the task's
-     * work deleted a file a DIFFERENT task's commit introduced, verify FAILed with
-     * the deterministic finding attached, and the user ACCEPTed anyway — the
-     * deletion ships in the next commit, so the final gate must re-check it
-     * (resolved iff the file is back in the tree). Best-effort; absent in tests.
-     */
-    recordCrossTaskDeletionDebt?: (cwd: string, taskId: string, deletion: {
-        path: string;
-        owner: string;
-    }) => Promise<void>;
-    /**
-     * Record a durable ROOT-CAUSE debt (mx5 run 14 item 5): this task's verify
-     * FAILed on a pre-existing defect in a file ANOTHER task created and this task
-     * never touched. Its work is kept (it is not at fault) but the defect is real,
-     * so the final gate must re-check and surface it. Best-effort; absent in tests.
-     */
-    recordRootCauseDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
-    /**
-     * Record a durable ENFORCE-KEPT debt (mx5 run 18 / nexttask 4): the enforce
-     * re-verify FAILED but the failing check names only files the ENFORCE COMMIT
-     * does not touch, so the edits were KEPT. The defect is still real and still in
-     * the shipped tree — keeping the work must not lose the finding.
-     */
-    recordEnforceKeptDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
+    recordDebt?: (cwd: string, taskId: string, reason: string, origin: DebtOrigin) => Promise<void>;
     /**
      * Queue a scoped repair task for a root-caused defect. The gate DETECTS the
      * cause; only the /task-auto loop may mutate the plan, so the two are decoupled
      * through the durable `.pi-tasks/repair-queue.md` ledger this writes (see
-     * root-cause-repair.ts). Absent (bare `/task`, tests) → detection still records
-     * the debt, nothing is scheduled.
+     * root-cause-repair.ts). Absent (tests) → detection still records the debt,
+     * nothing is scheduled. buildGateDeps always supplies it, so a bare `/task`
+     * queues repairs exactly like /task-auto — only the plan mutation is the loop's.
      */
     recordRepairCandidate?: (cwd: string, candidate: RepairCandidate) => Promise<void>;
     /**