@mjasnikovs/pi-task 0.30.0 → 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

@@ -1290,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
@@ -1309,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);

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

@@ -1,5 +1,5 @@
 import { type HealthCommand } from './repo-health-check.js';
-import { type AcceptDebt } from './accept-debt.js';
+import { type AcceptDebt, type VerifyRerunResult } from './accept-debt.js';
 import { type RenderOutcome } from './render-check.js';
 import { type DeepRenderOutcome } from './deep-render-check.js';
 import { taskThatIntroduced } from './task-provenance.js';
@@ -344,6 +344,40 @@ export declare function discoverGateCommandBodies(cwd: string): Record<string, s
  * this box; the same wording in a `test` run is a real failure the suite must own).
  */
 export declare const INFRA_GAP_OUTPUT_RE: RegExp;
+/**
+ * How a re-run of ONE recorded VERIFY command line ended.
+ *   pass — it ran and exited 0. The ONLY outcome that may close a debt.
+ *   fail — it ran and exited non-zero for a real reason. Debt stays open.
+ *   gap  — nothing was observed: the shell/runner never spawned, 127 inside the
+ *          chain, a timeout, a missing browser, or absent external infrastructure.
+ *          INCONCLUSIVE, so the debt stays open (surface, never re-hide).
+ */
+export type VerifyRerunOutcome = {
+    outcome: 'pass';
+} | {
+    outcome: 'fail';
+    status: number;
+    tail: string;
+} | {
+    outcome: 'gap';
+    detail: string;
+};
+/**
+ * Re-run one VERIFY-block command line (nexttask 5) under the gate's existing
+ * env-gap contract, so a debt whose reason NAMES that command can be closed by the
+ * command itself rather than by a judgement about it.
+ *
+ * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: run 19's
+ * is `AGENT=1 bun test test/listings.test.ts`, and env prefixes, `&&` and redirects
+ * are all ordinary there. The leading command word is still resolved through
+ * runner-resolve so a login-shell-stripped PATH cannot make every re-run look like a
+ * gap (mx5 run 16's blindness, one level down).
+ *
+ * The asymmetry is the point: only exit 0 is conclusive. Every other ending — real
+ * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the
+ * debt exactly as open as it was.
+ */
+export declare function runVerifyCommandLine(cwd: string, line: string, timeoutMs: number, extraGapRe?: RegExp): VerifyRerunOutcome;
 /**
  * The full-skip blindness guard (mx5 run 16, validated): dynamic commands were
  * DISCOVERED but every single one skipped as an environment gap, so the gate
@@ -484,7 +518,26 @@ export { taskThatIntroduced };
 export declare function deriveOpenDebts(cwd: string, staticOk: boolean): Promise<{
     openDebts: AcceptDebt[];
     debtNote?: string;
+    trail?: string[];
 }>;
+/**
+ * Re-run ONE debt's stored VERIFY command for the re-check, with the no-write guard
+ * (`inv-no-write`) wrapped around it.
+ *
+ * A VERIFY command is the project's own command and may legitimately write (a build
+ * emits `dist/`, a suite writes a snapshot). What it may NOT do is turn the tree into
+ * a passing tree and have that count as the debt being fixed — the run would then be
+ * certifying its own side effect. So tracked state is captured before and after, and
+ * a pass that came with a tracked change is downgraded to INCONCLUSIVE with the
+ * change named. Untracked output is left alone: it is what a build legitimately
+ * produces, and `git status --porcelain` in a repo with the usual ignores does not
+ * see it.
+ *
+ * A repository the guard cannot read (no git, git absent) is not a licence to skip
+ * the guard: the re-run is INCONCLUSIVE there, because "nothing changed" would be an
+ * assumption rather than an observation.
+ */
+export declare function rerunDebtVerifyCommand(cwd: string, command: string): VerifyRerunResult;
 /**
  * Run the final gate: static analysis first, then the lockfile consistency
  * checks, then the discovered integration commands, then one boot exercise of