@mjasnikovs/pi-task 0.29.3 → 0.31.0

package/README.md

@@ -46,6 +46,12 @@ One change — `/task` runs it through the full pipeline and hands the finished
 /task add rate limiting to the /api/upload endpoint
 ```
 
+One change, but you want a say in HOW — `/task-plan` talks it through with you first, one question at a time, then hands the decisions to `/task`:
+
+```
+/task-plan add rate limiting to the /api/upload endpoint
+```
+
 A whole plan — `/task-auto` splits it into an ordered task list and runs each one through `/task`:
 
 ```
@@ -59,6 +65,7 @@ A whole plan — `/task-auto` splits it into an ordered task list and runs each
 | Command | What it does |
 | --- | --- |
 | `/task <prompt>` | Start a new task and run it through the full pipeline. |
+| `/task-plan <prompt>` | Plan one task with the model — it asks, you answer, ask it something back, or proceed — then run it through `/task`. |
 | `/task-list` | Open the task list in an editor dialog. |
 | `/task-resume [id]` | Resume the most recent (or named) unfinished task. |
 | `/task-cancel` | Cancel the running task (soft-terminal — still resumable). |
@@ -86,6 +93,28 @@ A whole plan — `/task-auto` splits it into an ordered task list and runs each
 
 The finished spec is delivered to your main `pi` conversation via `sendUserMessage`, so you keep working in the same chat — no context handoff, no copy-paste.
 
+## Planning one task — `/task-plan`
+
+`/task` decides most things for you: refine sharpens the ask, research gathers context, and grill only surfaces the questions its research could not settle. That is the right trade when you want the change done. When you want a say in **how** it gets done, `/task-plan` puts the conversation first.
+
+```
+/task-plan add rate limiting to the /api/upload endpoint
+```
+
+It works like the clarify step you already know — **one question at a time, each one shaped by your last answer** — with a recommendation you can take with one keystroke. The difference is that three moves are on screen at *every* prompt, so the conversation is yours to steer:
+
+| Move | What it does |
+| --- | --- |
+| **Answer** | Take the recommendation (or the `B` option), or type your own answer. Empty submit = accept the recommendation. |
+| **❓ Ask the model a question** | You ask, it answers — grounded in the repo, with the read tool. The answer is recorded as a **note**, and the same question you were being asked comes straight back. Notes do not decide anything; they are context, and they ride into the next question. |
+| **▶ Proceed to execution** | Stop planning and hand what you have to `/task`. Available from the very first prompt — you are never forced through a question you do not care about. |
+
+When the model runs out of questions it says so and offers the same three moves rather than proceeding behind your back. Answering something new re-opens it: a decision you volunteer can make a fresh question worth asking.
+
+Everything lands in `.pi-tasks/TASK_PLAN_NNNN.md` — the task prompt, the `## decisions` transcript, and a separate `## notes` section for what you asked. Only the decisions are handed to `/task`, as an authoritative block ahead of your original prompt; the notes stay behind, because an answer you read is not a decision you made. From there it is an ordinary `/task` run — same pipeline, same gates.
+
+It works from the browser too (see [Remote](#remote--drive-a-task-from-your-phone)): the prompt card grows an **Ask the model** and a **Proceed to execution** button alongside the usual Accept / Manual answer.
+
 ## Orchestrating multiple tasks — `/task-auto`
 
 A real feature is usually several tasks, not one. `/task-auto` is a thin planner on top of the single-task pipeline:

package/dist/index.js

@@ -1,6 +1,7 @@
 import { registerConfig } from './config/register.js';
 import { registerTask } from './task/orchestrator.js';
 import { registerTaskAuto } from './task/auto-orchestrator.js';
+import { registerTaskPlan } from './task/plan-orchestrator.js';
 import { registerWorkers } from './workers/index.js';
 import { registerRemote } from './remote/register.js';
 import { registerThinkingCompression } from './thinking/compress.js';
@@ -10,6 +11,7 @@ export default function (pi) {
     registerConfig(pi);
     registerTask(pi);
     registerTaskAuto(pi);
+    registerTaskPlan(pi);
     registerWorkers(pi);
     registerRemote(pi);
     registerThinkingCompression(pi);

package/dist/remote/bridge.d.ts

@@ -52,6 +52,24 @@ export interface AskSpec {
         label: string;
         value: string;
     }[];
+    /**
+     * Label for the local picker's trailing free-text card (see
+     * {@link AskQuestionBoxSpec.manualLabel}). Ignored without `options`.
+     */
+    manualLabel?: string;
+    /**
+     * Extra buttons the BROWSER card shows alongside the recommendation, each
+     * answering with its own `value`. Unlike `options` — which are answers, and
+     * which the remote already covers with the recommended/recommended2 buttons —
+     * these are ACTIONS that mean something other than "here is my answer", so
+     * the remote cannot express them by any existing field. /task-plan's "ask the
+     * model" and "proceed to execution" are the only producers; every other call
+     * site omits this and the card is byte-for-byte what it was.
+     */
+    actions?: {
+        label: string;
+        value: string;
+    }[];
 }
 /** Wraps a live command ctx and fans interactions out to local TUI + browsers. */
 export declare class SessionUI {

package/dist/remote/bridge.js

@@ -54,6 +54,7 @@ export class SessionUI {
             question: spec.question,
             recommended: spec.recommended,
             ...(spec.recommended2 !== undefined && { recommended2: spec.recommended2 }),
+            ...(spec.actions !== undefined && spec.actions.length > 0 && { actions: spec.actions }),
             allowSkip: spec.allowSkip
         };
         setPrompt(prompt);
@@ -99,6 +100,7 @@ export class SessionUI {
                     value: o.value,
                     recommended: i === 0
                 })),
+                ...(spec.manualLabel !== undefined && { manualLabel: spec.manualLabel }),
                 signal
             });
         }

package/dist/remote/protocol.d.ts

@@ -4,6 +4,15 @@ export interface PromptMessage {
     question: string;
     recommended?: string;
     recommended2?: string;
+    /**
+     * Buttons that answer with their own `value` instead of with an answer to the
+     * question — /task-plan's "ask the model" and "proceed to execution". Absent
+     * on every other prompt, so an older card renders exactly as before.
+     */
+    actions?: {
+        label: string;
+        value: string;
+    }[];
     allowSkip: boolean;
 }
 export interface PromptResolvedMessage {

package/dist/remote/ui-script.js

@@ -109,6 +109,7 @@ export function clientScript(wsUrl) {
     let activePromptId = null;
     let activeRecommended = '';
     let activeRecommended2 = '';
+    let activeActions = [];
     let cancelArmTimer = null;
     const toolCallMap = {};
     let currentBubble = null;
@@ -144,6 +145,7 @@ export function clientScript(wsUrl) {
 
     const COMMANDS = [
       { name: '/task',             desc: 'Start a new task' },
+      { name: '/task-plan',        desc: 'Plan one task with the model, then run it' },
       { name: '/task-list',        desc: 'List tasks in this project' },
       { name: '/task-resume',      desc: 'Resume a task' },
       { name: '/task-cancel',      desc: 'Cancel the currently running task' },
@@ -782,6 +784,7 @@ export function clientScript(wsUrl) {
       promptInput.style.display = 'none';
       promptRec.style.display = 'none';
       activeRecommended2 = '';
+      activeActions = [];
       if (cancelArmTimer) { clearTimeout(cancelArmTimer); cancelArmTimer = null; }
       refreshComposer();
     }
@@ -815,10 +818,26 @@ export function clientScript(wsUrl) {
       return btn;
     }
 
+    // Action buttons (/task-plan's "ask the model" / "proceed to execution").
+    // They answer with their own sentinel value rather than with an answer to the
+    // question, so they sit between the answer buttons and Cancel. Empty — and
+    // therefore invisible — for every prompt that carries no actions.
+    function makeActionBtns() {
+      const out = [];
+      for (let i = 0; i < activeActions.length; i++) {
+        (function (a) {
+          out.push(makeBtn(a.label, 'secondary', function () { answer(a.value); }));
+        })(activeActions[i]);
+      }
+      return out;
+    }
+
     function renderButtons(buttons, stacked) {
       promptButtons.className = stacked ? 'row stacked' : 'row';
       promptButtons.innerHTML = '';
       for (let i = 0; i < buttons.length; i++) promptButtons.appendChild(buttons[i]);
+      const actions = makeActionBtns();
+      for (let i = 0; i < actions.length; i++) promptButtons.appendChild(actions[i]);
       promptButtons.appendChild(makeCancelBtn());
     }
 
@@ -861,6 +880,7 @@ export function clientScript(wsUrl) {
       promptQ.textContent = msg.question;
       activeRecommended = msg.recommended || '';
       activeRecommended2 = msg.recommended2 || '';
+      activeActions = msg.actions || [];
       if (msg.recommended) {
         // Mode A: recommendation(s) present. Render markdown in the panel so a
         // recommendation with code/emphasis reads the same as an assistant bubble.

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

@@ -64,6 +64,19 @@ export interface AcceptDebt {
      * child `rm`'d TASK_0008's verified admin page to satisfy exactly such a claim.
      */
     conflict?: string;
+    /**
+     * The ONE command this debt's own reason NAMES, quoted verbatim in backticks and
+     * present byte-identically in the owning task's VERIFY block (nexttask 5, mx5 run
+     * 19 TASK_0009). Set at record time by classifyVerifyCommand; absent whenever the
+     * reason names no such command — which is most of them (measured: 2 of 19
+     * PROJECT-pool debts, `scripts/debt-verify-class-baserate.ts`).
+     *
+     * It exists so the run-end re-check can settle the debt the way the debt was
+     * created: by RUNNING the command and reading its exit status. Never
+     * synthesised, never paraphrased, never reconstructed from prose — the stored
+     * string is the VERIFY-block line itself (`inv-command-provenance`).
+     */
+    verifyCommand?: string;
 }
 export declare function acceptDebtFile(cwd: string): string;
 /** The raw stored ledger ('' when none recorded yet). Parse with parseAcceptDebts. */
@@ -159,20 +172,56 @@ export declare function writeAcceptDebts(cwd: string, debts: AcceptDebt[]): Prom
  * behavioral and cannot be proven resolved without re-running the model.
  */
 export declare function isStaticClassDebt(reason: string): boolean;
+/**
+ * Read the owning task's spec and return the VERIFY command its FAIL reason names,
+ * or null. Best-effort by design: a missing task file, an unparseable or UNCLOSED
+ * VERIFY fence, or a reason that quotes nothing all yield null, and null simply
+ * means the debt keeps today's behaviour (surfaced, never auto-closed).
+ *
+ * The STRICT parse matters here. mx5 run 19's `TASK_0001.md` opens ```sh and never
+ * closes it, so the lenient parser hands back the phase-timings table and every
+ * appended gate-trail line as "VERIFY commands" — including sentences that quote
+ * `bun run lint`. Matching a reason against that would mint a stored, re-runnable
+ * command with fabricated provenance, which is the one thing this class may not do.
+ */
+export declare function classifyVerifyCommand(cwd: string, taskId: string, reason: string): Promise<string | null>;
+export declare function verifyCommandFromReason(reason: string, verifyCommands: readonly string[]): string | null;
+/**
+ * How a re-run of a debt's stored VERIFY command ended, as the re-check sees it.
+ * `pass` is the ONLY conclusive outcome: everything else — a real failure, a missing
+ * tool, unreachable infrastructure, a timeout, a tree the run mutated — leaves the
+ * debt exactly as open as it was.
+ */
+export interface VerifyRerunResult {
+    outcome: 'pass' | 'fail' | 'gap';
+    detail?: string;
+}
 /**
  * Re-check the ledger against the current run state. A static-class debt is RESOLVED
  * iff the final gate's own static check now passes (`staticOk`); a cross-task-deletion
  * debt is RESOLVED iff the file it names is back in the tree (`fileExists` — a later
  * task or a human restored it, so the deletion no longer holds); every other debt
- * stays OPEN (unprovable ⇒ surface, never re-hide). FP-safe: the only auto-closes are
- * ones a deterministic check can stand behind.
+ * stays OPEN (unprovable ⇒ surface, never re-hide) — unless it carries a stored
+ * `verifyCommand` and `rerunVerify` re-runs that command to a ZERO exit, which is the
+ * third class (nexttask 5): the debt named a command, the command was run, and it
+ * passed. FP-safe: the only auto-closes are ones a deterministic check can stand
+ * behind, and here the check is the task spec's own command.
  */
 export declare function recheckAcceptDebts(debts: AcceptDebt[], opts: {
     staticOk: boolean;
     fileExists?: (rel: string) => boolean;
+    /**
+     * Re-run a debt's stored VERIFY command (nexttask 5). Absent ⇒ the class is
+     * inert and every debt behaves exactly as it did before it existed. Only
+     * `pass` may close a debt; `fail` and `gap` both leave it open, and the
+     * caller is expected to have made `pass` mean "ran, exited 0, and changed
+     * nothing tracked" (`inv-no-write`).
+     */
+    rerunVerify?: (command: string, debt: AcceptDebt) => VerifyRerunResult;
 }): {
     open: AcceptDebt[];
     resolved: AcceptDebt[];
+    trail: string[];
 };
 /**
  * Extract the paths whose EXISTENCE the reason asserts as the failure — a path

package/dist/task/accept-debt.js

@@ -27,7 +27,8 @@
  */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
-import { tasksDir } from './task-io.js';
+import { parseVerifyBlockStrict } from './spec-validation.js';
+import { taskFilePath, tasksDir } from './task-io.js';
 const ACCEPT_DEBT_FILE = 'accept-debt.md';
 /** Cap kept records so a run that accepts many FAILs cannot grow the report unboundedly. */
 const MAX_DEBTS = 60;
@@ -71,6 +72,9 @@ export function parseAcceptDebts(raw) {
             continue;
         }
         const origin = parts[2]?.trim();
+        // 4th field: the verbatim VERIFY command the reason names (nexttask 5).
+        // Absent in every legacy record, and absent in most new ones.
+        const verifyCommand = parts[3]?.trim();
         out.push({
             taskId: parts[0].trim(),
             reason: parts[1].trim(),
@@ -82,7 +86,8 @@ export function parseAcceptDebts(raw) {
                 || origin === 'final-gate'
                 || origin === 'root-cause') ?
                 { origin: origin }
-                : {})
+                : {}),
+            ...(verifyCommand !== undefined && verifyCommand.length > 0 ? { verifyCommand } : {})
         });
     }
     return out;
@@ -101,6 +106,11 @@ function normaliseReason(reason) {
 function serialize(d) {
     // Legacy 2-field shape for 'accepted' (backward compatible); a 3rd origin field
     // only for the non-accepted classes, so old readers/files round-trip unchanged.
+    // The 4th verify-command field forces the origin field to be written (positional
+    // format) — 'accepted' spelled out there parses back to the same absent origin.
+    if (d.verifyCommand !== undefined && d.verifyCommand.length > 0) {
+        return [d.taskId, d.reason, d.origin ?? 'accepted', d.verifyCommand].join(FIELD_SEP);
+    }
     return d.origin && d.origin !== 'accepted' ?
         `${d.taskId}${FIELD_SEP}${d.reason}${FIELD_SEP}${d.origin}`
         : `${d.taskId}${FIELD_SEP}${d.reason}`;
@@ -119,6 +129,12 @@ async function appendDebt(cwd, entry) {
     if (entry.reason.length === 0)
         return;
     try {
+        // Classify AT RECORD TIME, against the spec as it stands when the defect is
+        // recorded (nexttask 5). Doing it later would read a spec a subsequent task
+        // may have rewritten — the provenance claim has to be made where it is true.
+        const verifyCommand = entry.verifyCommand ?? (await classifyVerifyCommand(cwd, entry.taskId, entry.reason));
+        if (verifyCommand !== null && verifyCommand !== undefined)
+            entry = { ...entry, verifyCommand };
         const existing = parseAcceptDebts(await readAcceptDebtsRaw(cwd));
         const seen = new Set(existing.map(debtKey));
         if (seen.has(debtKey(entry)))
@@ -269,17 +285,101 @@ export async function writeAcceptDebts(cwd, debts) {
 export function isStaticClassDebt(reason) {
     return /^\s*repo health:/i.test(reason);
 }
+/**
+ * The VERIFY-COMMAND class (nexttask 5): the ONE command a recorded reason itself
+ * NAMES, quoted verbatim in backticks, and present byte-identically in the owning
+ * task's VERIFY block.
+ *
+ * mx5 run 19 recorded `work did not verify: The VERIFY block command \`AGENT=1 bun
+ * test test/listings.test.ts\` fails unaided …`; eleven minutes later the final-gate
+ * autofix fixed exactly that, the gate's own re-run printed `121 pass 0 fail`, and
+ * the run still ended reporting the debt STILL OPEN — because no reachable code path
+ * could ever have closed it (see recheckAcceptDebts: two classes, neither reachable
+ * for a `work did not verify:` reason).
+ *
+ * Deliberately NOT fuzzy: a backticked span is accepted only when it equals a parsed
+ * VERIFY line exactly (after trimming). No paraphrase, no reconstruction, no prefix
+ * match — the returned string is the VERIFY-block entry itself, so anything stored
+ * or re-run carries the task spec's own provenance (`inv-command-provenance`). A
+ * reason that quotes a path, a symbol or a truncated command matches nothing and the
+ * debt stays unclassified, i.e. exactly as un-closable as it is today.
+ */
+/**
+ * A stored command must survive the ledger's own storage format and stay something
+ * a shell can be handed verbatim. A tab would break the positional record, a newline
+ * would split it into two, and an over-long line is a heredoc/prose artefact rather
+ * than a command. Any of those ⇒ not stored ⇒ the debt is simply unclassified, i.e.
+ * exactly as un-closable as it is today.
+ */
+function isStorableCommand(cmd) {
+    return cmd.length > 0 && cmd.length <= MAX_REASON_LENGTH && !/[\t\n\r]/.test(cmd);
+}
+/**
+ * Read the owning task's spec and return the VERIFY command its FAIL reason names,
+ * or null. Best-effort by design: a missing task file, an unparseable or UNCLOSED
+ * VERIFY fence, or a reason that quotes nothing all yield null, and null simply
+ * means the debt keeps today's behaviour (surfaced, never auto-closed).
+ *
+ * The STRICT parse matters here. mx5 run 19's `TASK_0001.md` opens ```sh and never
+ * closes it, so the lenient parser hands back the phase-timings table and every
+ * appended gate-trail line as "VERIFY commands" — including sentences that quote
+ * `bun run lint`. Matching a reason against that would mint a stored, re-runnable
+ * command with fabricated provenance, which is the one thing this class may not do.
+ */
+export async function classifyVerifyCommand(cwd, taskId, reason) {
+    if (taskId.trim().length === 0)
+        return null;
+    try {
+        const spec = await fsp.readFile(taskFilePath(cwd, taskId.trim()), 'utf8');
+        const cmds = parseVerifyBlockStrict(spec);
+        if (cmds === null || cmds.length === 0)
+            return null;
+        const hit = verifyCommandFromReason(reason, cmds.map(c => c.raw));
+        return hit !== null && isStorableCommand(hit) ? hit : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function verifyCommandFromReason(reason, verifyCommands) {
+    const byText = new Map();
+    for (const c of verifyCommands) {
+        const t = c.trim();
+        if (t.length > 0 && !byText.has(t))
+            byText.set(t, t);
+    }
+    if (byText.size === 0)
+        return null;
+    for (const m of reason.matchAll(/`([^`]+)`/g)) {
+        const hit = byText.get(m[1].trim());
+        if (hit !== undefined)
+            return hit;
+    }
+    return null;
+}
+/**
+ * Re-runs allowed per re-check. `inv-bounded`: a run that accepted many command-shaped
+ * FAILs must not turn its own report into an unbounded second test suite. Three covers
+ * every recorded run in the corpus (max classified per run: 1) with room to spare, and
+ * anything past it stays open with the budget stated in the trail — never closed.
+ */
+const MAX_VERIFY_RERUNS = 3;
 /**
  * Re-check the ledger against the current run state. A static-class debt is RESOLVED
  * iff the final gate's own static check now passes (`staticOk`); a cross-task-deletion
  * debt is RESOLVED iff the file it names is back in the tree (`fileExists` — a later
  * task or a human restored it, so the deletion no longer holds); every other debt
- * stays OPEN (unprovable ⇒ surface, never re-hide). FP-safe: the only auto-closes are
- * ones a deterministic check can stand behind.
+ * stays OPEN (unprovable ⇒ surface, never re-hide) — unless it carries a stored
+ * `verifyCommand` and `rerunVerify` re-runs that command to a ZERO exit, which is the
+ * third class (nexttask 5): the debt named a command, the command was run, and it
+ * passed. FP-safe: the only auto-closes are ones a deterministic check can stand
+ * behind, and here the check is the task spec's own command.
  */
 export function recheckAcceptDebts(debts, opts) {
     const open = [];
     const resolved = [];
+    const trail = [];
+    let rerunsLeft = MAX_VERIFY_RERUNS;
     for (const d of debts) {
         if (d.origin === 'cross-task-deletion') {
             const p = extractDeletedDebtPath(d.reason);
@@ -296,12 +396,45 @@ export function recheckAcceptDebts(debts, opts) {
                 open.push(d);
             continue;
         }
-        if (opts.staticOk && isStaticClassDebt(d.reason))
+        if (opts.staticOk && isStaticClassDebt(d.reason)) {
             resolved.push(d);
-        else
+            continue;
+        }
+        // VERIFY-COMMAND class, LAST so the two older classes decide exactly what they
+        // decided before (`inv-existing-classes-kept`) and nothing is re-run that was
+        // already settled without running anything.
+        const cmd = d.verifyCommand;
+        if (opts.rerunVerify === undefined || cmd === undefined || !isStorableCommand(cmd)) {
+            open.push(d);
+            continue;
+        }
+        if (rerunsLeft <= 0) {
+            trail.push(`${d.taskId}: NOT re-checked — the per-run re-run budget `
+                + `(${MAX_VERIFY_RERUNS}) is spent; the debt stays open`);
             open.push(d);
+            continue;
+        }
+        rerunsLeft -= 1;
+        let r;
+        try {
+            r = opts.rerunVerify(cmd, d);
+        }
+        catch {
+            // A harness fault observes nothing, so it proves nothing.
+            r = { outcome: 'gap', detail: 're-run harness fault' };
+        }
+        if (r.outcome === 'pass') {
+            resolved.push(d);
+            trail.push(`${d.taskId}: RESOLVED — re-ran \`${cmd}\` and it exited 0`);
+            continue;
+        }
+        trail.push(`${d.taskId}: still open — re-ran \`${cmd}\`: `
+            + (r.outcome === 'fail' ?
+                `it FAILED${r.detail ? ` (${r.detail})` : ''}`
+                : `INCONCLUSIVE${r.detail ? ` (${r.detail})` : ''}, nothing was observed`));
+        open.push(d);
     }
-    return { open, resolved };
+    return { open, resolved, trail };
 }
 // ─── Conflicting-claim classification (mx5 run 11) ──────────────────────────
 //

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

@@ -73,6 +73,7 @@ export interface AutoDeps extends GateDeps {
     recheckOpenDebts?: (cwd: string, staticOk: boolean) => Promise<{
         openDebts: AcceptDebt[];
         debtNote?: string;
+        trail?: string[];
     }>;
 }
 /**

package/dist/task/auto-orchestrator.js

@@ -35,6 +35,7 @@ import { runGatesForTask } from './task-gates.js';
 import { gitUnmergedPaths, gitStashRef } from './auto-commit.js';
 import { runFinalIntegrationGate, deriveOpenDebts } from './final-gate.js';
 import { describeDebt, recordFinalGateUnobservedDebt } from './accept-debt.js';
+import { ignoredWriteTrailLine, ignoredWriteDebtReason } from './write-guard.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';
 import { getConfig } from '../config/config.js';
@@ -1289,6 +1290,15 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                             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
@@ -1308,7 +1318,7 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                             return;
                         }
                         for (const d of closed) {
-                            await recGate(`defect RESOLVED by the final-gate autofix — ${d.taskId || '(unknown task)'}: `
+                            await recGate(`defect RESOLVED — ${d.taskId || '(unknown task)'}: `
                                 + `${d.reason.slice(0, 240)}`);
                         }
                         await surfaceOpenDebts(added);
@@ -1322,6 +1332,11 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     // 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).
@@ -1446,7 +1461,30 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                             const seed = choice.guidance ?
                                 `${fin.reason}\n\nUser guidance: ${choice.guidance}`
                                 : fin.reason;
-                            const fix = await deps.finalGateFix(active, cwd, seed);
+                            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 recordFinalGateUnobservedDebt(cwd, id, 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

package/dist/task/final-gate-fix.d.ts

@@ -1,4 +1,4 @@
-import { type TreeChangeSummary } from './write-guard.js';
+import { type TreeChangeSummary, type IgnoredSnapshot } from './write-guard.js';
 /** Same bounded-fix contract as lint-fix: edit in place, bash exists to RUN the
  *  failing command (and the project's own tooling), not to mutate git state. */
 export declare const FINAL_FIX_TOOLS = "read,edit,bash";
@@ -108,6 +108,14 @@ export interface FinalFixResult {
      *  labels a converge-on-statics-alone the same way it labels a first-pass one —
      *  "converged" must never quietly mean "we stopped being able to check". */
     unobserved?: string;
+    /** Gitignored path(s) this fix pass wrote, exempt classes already removed (see
+     *  write-guard.ts). Present whether or not the gate converged — the caller
+     *  trails them either way; path names only, never contents. */
+    ignoredWrites?: string[];
+    /** …and the mechanical dependency probe found the converged gate does NOT pass
+     *  without them, so `unobserved` above carries the downgrade. Absent when the
+     *  probe could not answer (no probe wired, restore risk, too many paths). */
+    ignoredDependent?: boolean;
     /** A write-guard rejected this attempt (deletion / shrink / probe-gaming). */
     guardTripped?: boolean;
     /** …and its edits were discarded. When a guard tripped and this is false, the
@@ -158,6 +166,19 @@ export interface FinalFixDeps {
      *  run 11's autofix replaced the typed client with a hand-written contract
      *  copy to green the lint. Findings are verbatim offending lines. */
     probeScan?: () => Promise<string[]>;
+    /** Fingerprint of the ACTIONABLE ignored paths (build output and node_modules
+     *  already exempt). Called before and after the child; the difference is what
+     *  this pass wrote. Absent → the channel is off and behaviour is unchanged. */
+    ignoredSnapshot?: () => Promise<IgnoredSnapshot>;
+    /** Ignored paths EARLIER attempts in this resolution loop already wrote. An
+     *  attempt that fails still leaves its ignored writes on disk (discard reverts
+     *  tracked files only), so without this a `.env` written by attempt 1 would be
+     *  invisible to attempt 2's before/after diff — and attempt 2's converged PASS
+     *  would rest on it unrecorded. The caller accumulates. */
+    ignoredKnown?: string[];
+    /** The mechanical dependency test: does the gate still pass with these paths
+     *  moved aside? `null` ⇒ unanswerable, which never downgrades a verdict. */
+    gateWithoutIgnored?: (paths: string[]) => Promise<boolean | null>;
     /** Write a timestamped line to the gate debug log (guard events). */
     log?: (msg: string) => void;
 }