@mjasnikovs/pi-task 0.37.7 → 0.38.0

package/dist/shared/child-output.d.ts

@@ -3,8 +3,22 @@ export declare function parseChildOutput(stdout: string): {
     excerpt?: string;
 };
 export declare function normaliseWhitespace(s: string): string;
-/** Check whether an excerpt appears verbatim in the source content
- *  (whitespace-normalised). Returns false for empty excerpts. */
+/**
+ * THE excerpt predicate: does this excerpt appear verbatim in the source content
+ * (whitespace-normalised)? {@link verifyExcerpt} delegates to it, so there is exactly one
+ * definition of "verified" in the codebase.
+ *
+ * False for an excerpt that is empty OR whitespace-only. The emptiness test is applied to
+ * the NORMALISED excerpt, not the raw one: `"   "` is a non-empty string that normalises to
+ * `""`, and `content.includes('')` is true for every content — so the raw-string guard let a
+ * whitespace-only excerpt "verify" against anything, while `verifyExcerpt` (which tested the
+ * normalised length) called the same input unverified. A citation with no characters in it is
+ * not evidence, so both now answer false.
+ *
+ * Unreachable from the shipped extractors — `parseChildOutput` already maps a whitespace-only
+ * `<excerpt>` to `undefined` via `.trim() || undefined`, and every call site guards on that —
+ * so this is a latent-disagreement fix, not a behaviour change to any recorded verdict.
+ */
 export declare function isExcerptInContent(excerpt: string, content: string): boolean;
 /**
  * The same verdict as {@link isExcerptInContent}, PLUS a retained record of what was
@@ -13,7 +27,9 @@ export declare function isExcerptInContent(excerpt: string, content: string): bo
  * DIAGNOSABLE after the fact, so it can be attributed to fabrication (the excerpt is nowhere
  * near the content) versus a normaliser gap (it is a markdown-escape or entity variant of
  * text that IS present) WITHOUT re-fetching. It deliberately does NOT loosen the verifier:
- * `.verified` is identical to `isExcerptInContent`. F-3(f) — whether the normaliser needs
+ * `.verified` IS `isExcerptInContent` — delegated, not re-implemented, so the two cannot
+ * drift apart again (they had: a whitespace-only excerpt verified there and failed here).
+ * F-3(f) — whether the normaliser needs
  * markdown-escape handling — is left unproven on purpose; you decide that from the retained
  * evidence, not by weakening the one working hallucination detector first.
  */

package/dist/shared/child-output.js

@@ -20,18 +20,34 @@ export function parseChildOutput(stdout) {
 export function normaliseWhitespace(s) {
     return s.replace(/\s+/g, ' ').trim();
 }
-/** Check whether an excerpt appears verbatim in the source content
- *  (whitespace-normalised). Returns false for empty excerpts. */
+/**
+ * THE excerpt predicate: does this excerpt appear verbatim in the source content
+ * (whitespace-normalised)? {@link verifyExcerpt} delegates to it, so there is exactly one
+ * definition of "verified" in the codebase.
+ *
+ * False for an excerpt that is empty OR whitespace-only. The emptiness test is applied to
+ * the NORMALISED excerpt, not the raw one: `"   "` is a non-empty string that normalises to
+ * `""`, and `content.includes('')` is true for every content — so the raw-string guard let a
+ * whitespace-only excerpt "verify" against anything, while `verifyExcerpt` (which tested the
+ * normalised length) called the same input unverified. A citation with no characters in it is
+ * not evidence, so both now answer false.
+ *
+ * Unreachable from the shipped extractors — `parseChildOutput` already maps a whitespace-only
+ * `<excerpt>` to `undefined` via `.trim() || undefined`, and every call site guards on that —
+ * so this is a latent-disagreement fix, not a behaviour change to any recorded verdict.
+ */
 export function isExcerptInContent(excerpt, content) {
-    if (!excerpt)
+    const ne = normaliseWhitespace(excerpt);
+    if (ne.length === 0)
         return false;
-    return normaliseWhitespace(content).includes(normaliseWhitespace(excerpt));
+    return normaliseWhitespace(content).includes(ne);
 }
 export function verifyExcerpt(excerpt, content) {
     const nc = normaliseWhitespace(content);
     const ne = normaliseWhitespace(excerpt);
     return {
-        verified: ne.length > 0 && nc.includes(ne),
+        // Delegated on purpose: this struct adds EVIDENCE, never a second opinion.
+        verified: isExcerptInContent(excerpt, content),
         contentSha256: createHash('sha256').update(nc).digest('hex'),
         contentLength: nc.length,
         normalisedExcerpt: ne

package/dist/shared/git-runner.d.ts

@@ -0,0 +1,39 @@
+/**
+ * git-runner — the ONE way this codebase runs `git`.
+ *
+ * WHY IT EXISTS. The right shape already existed, privately, inside
+ * `task/git-state-guard.ts`: an abort-aware async runner carrying an injectable
+ * `spawnFn` seam, returning `{stdout, exitCode}` and never throwing. Nothing
+ * outside that file could reach it, so ~27 other sites hand-rolled their own —
+ * with FOUR incompatible failure contracts (throws / returns null / returns '' /
+ * returns a result object) and THREE different maxBuffer limits. A caller reading
+ * one of them learns nothing about the next, and a git failure means something
+ * different at every site. Lifting the seam here does not add a capability; it
+ * removes the ambiguity about which contract you are holding.
+ *
+ * THE CONTRACT, deliberately narrow:
+ *   - NEVER THROWS. A missing git, a non-repo cwd, a fatal subcommand — all of
+ *     them arrive as a non-zero `exitCode`. Callers branch on the number, they do
+ *     not wrap in try/catch. (`git rev-parse --verify HEAD` on an unborn HEAD is
+ *     an ordinary answer, not an exception, and every guard built on this one
+ *     treats "git could not tell me" as "no claim" rather than a crash.)
+ *   - Only `stdout` and `exitCode` are exposed. stderr is deliberately absent:
+ *     the callers that legitimately need it (auto-commit's identity-failure
+ *     sniffing) also need `aborted`, and widening this type for them would push
+ *     two fields nobody else reads onto every call site.
+ *   - `signal` is honoured by the underlying runChild, including its listener
+ *     detach discipline (GitHub issue #9) — a run-long orchestrator signal does
+ *     not accumulate one listener per git invocation.
+ *   - `env` entries are MERGED over `process.env` (the GIT_INDEX_FILE
+ *     throwaway-index pattern), not substituted for it.
+ *   - `spawnFn` is the test seam: pass a fake from `test-utils/fake-spawn.ts` and
+ *     the runner never touches a real repo.
+ */
+import { type SpawnFn } from './child-process.js';
+export interface GitRunner {
+    (args: string[], env?: Record<string, string>): Promise<{
+        stdout: string;
+        exitCode: number;
+    }>;
+}
+export declare function makeGit(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): GitRunner;

package/dist/shared/git-runner.js

@@ -0,0 +1,38 @@
+/**
+ * git-runner — the ONE way this codebase runs `git`.
+ *
+ * WHY IT EXISTS. The right shape already existed, privately, inside
+ * `task/git-state-guard.ts`: an abort-aware async runner carrying an injectable
+ * `spawnFn` seam, returning `{stdout, exitCode}` and never throwing. Nothing
+ * outside that file could reach it, so ~27 other sites hand-rolled their own —
+ * with FOUR incompatible failure contracts (throws / returns null / returns '' /
+ * returns a result object) and THREE different maxBuffer limits. A caller reading
+ * one of them learns nothing about the next, and a git failure means something
+ * different at every site. Lifting the seam here does not add a capability; it
+ * removes the ambiguity about which contract you are holding.
+ *
+ * THE CONTRACT, deliberately narrow:
+ *   - NEVER THROWS. A missing git, a non-repo cwd, a fatal subcommand — all of
+ *     them arrive as a non-zero `exitCode`. Callers branch on the number, they do
+ *     not wrap in try/catch. (`git rev-parse --verify HEAD` on an unborn HEAD is
+ *     an ordinary answer, not an exception, and every guard built on this one
+ *     treats "git could not tell me" as "no claim" rather than a crash.)
+ *   - Only `stdout` and `exitCode` are exposed. stderr is deliberately absent:
+ *     the callers that legitimately need it (auto-commit's identity-failure
+ *     sniffing) also need `aborted`, and widening this type for them would push
+ *     two fields nobody else reads onto every call site.
+ *   - `signal` is honoured by the underlying runChild, including its listener
+ *     detach discipline (GitHub issue #9) — a run-long orchestrator signal does
+ *     not accumulate one listener per git invocation.
+ *   - `env` entries are MERGED over `process.env` (the GIT_INDEX_FILE
+ *     throwaway-index pattern), not substituted for it.
+ *   - `spawnFn` is the test seam: pass a fake from `test-utils/fake-spawn.ts` and
+ *     the runner never touches a real repo.
+ */
+import { runChildDefault } from './child-process.js';
+export function makeGit(cwd, signal, spawnFn) {
+    return async (args, env) => {
+        const r = await runChildDefault({ command: 'git', args, ...(env ? { env: { ...process.env, ...env } } : {}) }, cwd, signal, { mode: 'text' }, spawnFn);
+        return { stdout: r.stdout, exitCode: r.exitCode };
+    };
+}

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

@@ -92,71 +92,36 @@ export declare function readAcceptDebtsRaw(cwd: string): Promise<string>;
 export declare function parseAcceptDebts(raw: string): AcceptDebt[];
 /** Read + parse in one step. */
 export declare function readAcceptDebts(cwd: string): Promise<AcceptDebt[]>;
-/** Record a user-ACCEPTED-despite-verify-FAIL debt. */
-export declare function recordAcceptDebt(cwd: string, taskId: string, reason: string): Promise<void>;
 /**
- * Record an ENFORCE-REVERT debt (mx5 run 10 item 3): an enforce re-verify FAILED and
- * the enforce edits were reverted, but the FAIL indicted the ORIGINAL work — so the
- * defect is still in the shipped tree. Durable so the final gate re-checks/surfaces it
- * rather than letting it die with the revert.
- */
-export declare function recordEnforceRevertDebt(cwd: string, taskId: string, reason: string): Promise<void>;
-/**
- * Record an ENFORCE-KEPT debt (mx5 run 18 / nexttask 4): an enforce re-verify FAILED
- * on a check whose named files are DISJOINT from the enforce commit's own diff, so
- * the edits were kept — discarding them could not have repaired a failure they cannot
- * reach. The defect is real and still in the shipped tree, so it is recorded with the
- * same durability as an enforce-revert; only the disposition of the edits differs.
- */
-export declare function recordEnforceKeptDebt(cwd: string, taskId: string, reason: string): Promise<void>;
-/**
- * Record a FROZEN-BLOCKED debt (mx5 run 12 / PROMPT 1 layer B): a repo-health FAIL
- * whose static findings can only be fixed by editing a path this task's spec froze —
- * a cross-task contradiction no unattended re-run may resolve. Recorded when the gate
- * loop routes to the picker (regardless of what the human then picks), so the final
- * gate re-checks it at run end. Static-class by reason prefix (`repo health: …`), so
- * it auto-closes iff the final gate's own static check passes.
+ * Record one durable defect against the run ledger, stamped with the DebtOrigin that
+ * says how it was reached (see DebtOrigin's doc for what each class asserts).
+ *
+ * This was eight exported wrappers that differed only in that one string literal, so
+ * a new class cost six edit sites. The origin is not cosmetic: the final gate
+ * re-checks and reports BY class, and an unattended auto-pick may never be recorded
+ * as the 'accepted' class — that one asserts a human weighed the failing artifact.
+ *
+ * Best-effort by construction (appendDebt swallows its own faults): the ledger is an
+ * auditing aid and must never break the gate sequence that calls it. `origin`
+ * defaults to 'accepted', which is the legacy 2-field on-disk shape.
  */
-export declare function recordFrozenBlockedDebt(cwd: string, taskId: string, reason: string): Promise<void>;
+export declare function recordDebt(cwd: string, taskId: string, reason: string, origin?: DebtOrigin): Promise<void>;
 /**
- * Record a CROSS-TASK DELETION debt (mx5 run 12 PROMPT 2): the task's work deleted a
- * file a DIFFERENT task's commit introduced, verify FAILed, and the user ACCEPTed —
- * so the deletion survives into the next commit. The reason is a fixed machine-
- * parseable shape (`deleted \`<path>\` …`) so the final gate's re-check can extract
- * the path and prove the debt resolved iff the file is back in the tree.
+ * The reason text a CROSS-TASK DELETION debt stores (mx5 run 12 PROMPT 2): the task's
+ * work deleted a file a DIFFERENT task's commit introduced, verify FAILed, and the
+ * user ACCEPTed — so the deletion survives into the next commit. The shape is fixed
+ * and machine-parseable so the final gate's re-check can extract the path and prove
+ * the debt resolved iff the file is back in the tree; it lives here, next to
+ * extractDeletedDebtPath, because the writer and the reader of that shape have to
+ * move together.
  */
-export declare function recordCrossTaskDeletionDebt(cwd: string, taskId: string, deletion: {
+export declare function crossTaskDeletionReason(deletion: {
     path: string;
     owner: string;
-}): Promise<void>;
-/**
- * Record a YOLO-ACCEPTED debt: unattended auto-pick took the verify-FAIL picker's
- * ACCEPT branch because there was nobody to ask (yolo.ts). Its own origin — and
- * therefore its own line in the final gate's surfaced report — so a later audit
- * reading only the artifacts can never read it as "a human decided this".
- */
-export declare function recordYoloAcceptDebt(cwd: string, taskId: string, reason: string): Promise<void>;
-/**
- * Record a FINAL-GATE UNOBSERVED debt (mx5 run 14): the final gate demoted one of its
- * OWN checks after two tree-changing fix attempts returned an identical ranked-first
- * failure — unfalsifiable in this environment, so the gate stopped paying for it and
- * converged on the remaining checks. Durable so the NEXT run's gate re-checks it: it
- * is model-/environment-judged, so the re-check surfaces it (never auto-closes it).
- * The taskId is the run's parent id — the demotion is a run-level decision.
- */
-export declare function recordFinalGateUnobservedDebt(cwd: string, taskId: string, reason: string): Promise<void>;
-/**
- * Record a ROOT-CAUSE debt (mx5 run 14 / PROMPT item 5): this task's verify FAILed
- * on a pre-existing defect in a file ANOTHER task created and this task never
- * touched. The current task is not at fault — its work (and, at the enforce site,
- * the enforce pass's edits) is KEPT — but the defect is real and still in the tree,
- * so it is recorded here and a scoped repair task is queued (root-cause-repair.ts).
- * Behavioral/model-judged, so the final gate surfaces it rather than auto-closing it.
- */
-export declare function recordRootCauseDebt(cwd: string, taskId: string, reason: string): Promise<void>;
+}): string;
 /**
  * The deleted path a cross-task-deletion debt names (the fixed shape
- * recordCrossTaskDeletionDebt writes). Null on any other reason text — an
+ * crossTaskDeletionReason builds). Null on any other reason text — an
  * unextractable path means the re-check cannot prove anything, so the debt
  * stays open (surface, never re-hide).
  */
@@ -248,5 +213,9 @@ export declare function annotateDebtConflicts(debts: AcceptDebt[], introducedBy:
  * instructions — and a conflicting claim carries its contradiction inline.
  */
 export declare function buildAcceptDebtNote(open: AcceptDebt[]): string;
-/** One-line provenance label for a debt, for the surfaced report. */
+/**
+ * One-line provenance label for a debt, for the surfaced report. Straight off
+ * DEBT_LABELS, so a new origin cannot ship without one; an absent or unregistered
+ * origin falls back to the 'accepted' class exactly as the branch chain did.
+ */
 export declare function describeDebt(d: AcceptDebt): string;

package/dist/task/accept-debt.js

@@ -40,6 +40,33 @@ const MAX_REASON_LENGTH = 300;
  * cleanly and any stray tab in a reason is flattened to a space before storage.
  */
 const FIELD_SEP = '\t';
+/**
+ * Origin → the one-line provenance label the surfaced report prints for it
+ * (describeDebt). This table IS the origin registry: `Record<DebtOrigin, string>`
+ * makes a new union member a compile error until it has a label, and both the
+ * describe side and the parse side read it, so adding an origin is one union member
+ * plus one line here — not the six edit sites the per-origin recorder functions used
+ * to cost. The label text is user-facing (it lands in the final gate's report and in
+ * the FAIL picker), so these strings are byte-frozen.
+ */
+const DEBT_LABELS = {
+    accepted: 'accepted despite verify-FAIL',
+    'enforce-revert': 'enforce re-verify FAILED then the edits were reverted (defect indicts the ORIGINAL work, still shipped)',
+    'enforce-kept': 'enforce re-verify FAILED on a check the enforce diff cannot reach — the guideline edits were KEPT (reverting them could not fix it) and the defect indicts the ORIGINAL work, still shipped',
+    'frozen-blocked': 'repo health blocked by a spec-frozen path (cross-task contradiction — no task may perform the fixing edit)',
+    'cross-task-deletion': "a sibling task's committed deliverable was DELETED by this task's work and the deletion was accepted (still missing from the tree)",
+    'yolo-accepted': 'auto-ACCEPTED by YOLO mode despite verify-FAIL (unattended — no human weighed this)',
+    'final-gate': 'final-gate check DEMOTED to UNOBSERVED (identical failure across two tree-changing fix attempts — unfalsifiable in that environment, never proven passing)',
+    'root-cause': "verify FAILed on a PRE-EXISTING defect in another task's file that this task never touched (this task's work was kept; a scoped repair task was queued for the root cause)"
+};
+/**
+ * A stored origin field is honoured only when it is a REGISTERED origin — anything
+ * else (a hand-edited line, a field from a newer build) falls back to the 'accepted'
+ * class rather than being trusted or dropped.
+ */
+function isKnownOrigin(origin) {
+    return origin !== undefined && Object.hasOwn(DEBT_LABELS, origin);
+}
 export function acceptDebtFile(cwd) {
     return path.join(tasksDir(cwd), ACCEPT_DEBT_FILE);
 }
@@ -78,15 +105,10 @@ export function parseAcceptDebts(raw) {
         out.push({
             taskId: parts[0].trim(),
             reason: parts[1].trim(),
-            ...((origin === 'enforce-revert'
-                || origin === 'enforce-kept'
-                || origin === 'frozen-blocked'
-                || origin === 'cross-task-deletion'
-                || origin === 'yolo-accepted'
-                || origin === 'final-gate'
-                || origin === 'root-cause') ?
-                { origin: origin }
-                : {}),
+            // 'accepted' is deliberately NOT carried: it is the legacy 2-field shape's
+            // implicit class, so an absent origin and a spelled-out 'accepted' must
+            // parse to the same record.
+            ...(isKnownOrigin(origin) && origin !== 'accepted' ? { origin } : {}),
             ...(verifyCommand !== undefined && verifyCommand.length > 0 ? { verifyCommand } : {})
         });
     }
@@ -147,112 +169,37 @@ async function appendDebt(cwd, entry) {
         // best-effort ledger
     }
 }
-/** Record a user-ACCEPTED-despite-verify-FAIL debt. */
-export async function recordAcceptDebt(cwd, taskId, reason) {
-    await appendDebt(cwd, { taskId: taskId.trim(), reason: normaliseReason(reason) });
-}
-/**
- * Record an ENFORCE-REVERT debt (mx5 run 10 item 3): an enforce re-verify FAILED and
- * the enforce edits were reverted, but the FAIL indicted the ORIGINAL work — so the
- * defect is still in the shipped tree. Durable so the final gate re-checks/surfaces it
- * rather than letting it die with the revert.
- */
-export async function recordEnforceRevertDebt(cwd, taskId, reason) {
-    await appendDebt(cwd, {
-        taskId: taskId.trim(),
-        reason: normaliseReason(reason),
-        origin: 'enforce-revert'
-    });
-}
 /**
- * Record an ENFORCE-KEPT debt (mx5 run 18 / nexttask 4): an enforce re-verify FAILED
- * on a check whose named files are DISJOINT from the enforce commit's own diff, so
- * the edits were kept — discarding them could not have repaired a failure they cannot
- * reach. The defect is real and still in the shipped tree, so it is recorded with the
- * same durability as an enforce-revert; only the disposition of the edits differs.
- */
-export async function recordEnforceKeptDebt(cwd, taskId, reason) {
-    await appendDebt(cwd, {
-        taskId: taskId.trim(),
-        reason: normaliseReason(reason),
-        origin: 'enforce-kept'
-    });
-}
-/**
- * Record a FROZEN-BLOCKED debt (mx5 run 12 / PROMPT 1 layer B): a repo-health FAIL
- * whose static findings can only be fixed by editing a path this task's spec froze —
- * a cross-task contradiction no unattended re-run may resolve. Recorded when the gate
- * loop routes to the picker (regardless of what the human then picks), so the final
- * gate re-checks it at run end. Static-class by reason prefix (`repo health: …`), so
- * it auto-closes iff the final gate's own static check passes.
- */
-export async function recordFrozenBlockedDebt(cwd, taskId, reason) {
-    await appendDebt(cwd, {
-        taskId: taskId.trim(),
-        reason: normaliseReason(reason),
-        origin: 'frozen-blocked'
-    });
-}
-/**
- * Record a CROSS-TASK DELETION debt (mx5 run 12 PROMPT 2): the task's work deleted a
- * file a DIFFERENT task's commit introduced, verify FAILed, and the user ACCEPTed —
- * so the deletion survives into the next commit. The reason is a fixed machine-
- * parseable shape (`deleted \`<path>\` …`) so the final gate's re-check can extract
- * the path and prove the debt resolved iff the file is back in the tree.
- */
-export async function recordCrossTaskDeletionDebt(cwd, taskId, deletion) {
-    await appendDebt(cwd, {
-        taskId: taskId.trim(),
-        reason: normaliseReason(`deleted \`${deletion.path}\` — ${deletion.owner}'s committed deliverable, removed by this task's work`),
-        origin: 'cross-task-deletion'
-    });
-}
-/**
- * Record a YOLO-ACCEPTED debt: unattended auto-pick took the verify-FAIL picker's
- * ACCEPT branch because there was nobody to ask (yolo.ts). Its own origin — and
- * therefore its own line in the final gate's surfaced report — so a later audit
- * reading only the artifacts can never read it as "a human decided this".
- */
-export async function recordYoloAcceptDebt(cwd, taskId, reason) {
-    await appendDebt(cwd, {
-        taskId: taskId.trim(),
-        reason: normaliseReason(reason),
-        origin: 'yolo-accepted'
-    });
-}
-/**
- * Record a FINAL-GATE UNOBSERVED debt (mx5 run 14): the final gate demoted one of its
- * OWN checks after two tree-changing fix attempts returned an identical ranked-first
- * failure — unfalsifiable in this environment, so the gate stopped paying for it and
- * converged on the remaining checks. Durable so the NEXT run's gate re-checks it: it
- * is model-/environment-judged, so the re-check surfaces it (never auto-closes it).
- * The taskId is the run's parent id — the demotion is a run-level decision.
+ * Record one durable defect against the run ledger, stamped with the DebtOrigin that
+ * says how it was reached (see DebtOrigin's doc for what each class asserts).
+ *
+ * This was eight exported wrappers that differed only in that one string literal, so
+ * a new class cost six edit sites. The origin is not cosmetic: the final gate
+ * re-checks and reports BY class, and an unattended auto-pick may never be recorded
+ * as the 'accepted' class — that one asserts a human weighed the failing artifact.
+ *
+ * Best-effort by construction (appendDebt swallows its own faults): the ledger is an
+ * auditing aid and must never break the gate sequence that calls it. `origin`
+ * defaults to 'accepted', which is the legacy 2-field on-disk shape.
  */
-export async function recordFinalGateUnobservedDebt(cwd, taskId, reason) {
-    await appendDebt(cwd, {
-        taskId: taskId.trim(),
-        reason: normaliseReason(reason),
-        origin: 'final-gate'
-    });
+export async function recordDebt(cwd, taskId, reason, origin = 'accepted') {
+    await appendDebt(cwd, { taskId: taskId.trim(), reason: normaliseReason(reason), origin });
 }
 /**
- * Record a ROOT-CAUSE debt (mx5 run 14 / PROMPT item 5): this task's verify FAILed
- * on a pre-existing defect in a file ANOTHER task created and this task never
- * touched. The current task is not at fault — its work (and, at the enforce site,
- * the enforce pass's edits) is KEPT — but the defect is real and still in the tree,
- * so it is recorded here and a scoped repair task is queued (root-cause-repair.ts).
- * Behavioral/model-judged, so the final gate surfaces it rather than auto-closing it.
+ * The reason text a CROSS-TASK DELETION debt stores (mx5 run 12 PROMPT 2): the task's
+ * work deleted a file a DIFFERENT task's commit introduced, verify FAILed, and the
+ * user ACCEPTed — so the deletion survives into the next commit. The shape is fixed
+ * and machine-parseable so the final gate's re-check can extract the path and prove
+ * the debt resolved iff the file is back in the tree; it lives here, next to
+ * extractDeletedDebtPath, because the writer and the reader of that shape have to
+ * move together.
  */
-export async function recordRootCauseDebt(cwd, taskId, reason) {
-    await appendDebt(cwd, {
-        taskId: taskId.trim(),
-        reason: normaliseReason(reason),
-        origin: 'root-cause'
-    });
+export function crossTaskDeletionReason(deletion) {
+    return `deleted \`${deletion.path}\` — ${deletion.owner}'s committed deliverable, removed by this task's work`;
 }
 /**
  * The deleted path a cross-task-deletion debt names (the fixed shape
- * recordCrossTaskDeletionDebt writes). Null on any other reason text — an
+ * crossTaskDeletionReason builds). Null on any other reason text — an
  * unextractable path means the re-check cannot prove anything, so the debt
  * stays open (surface, never re-hide).
  */
@@ -507,28 +454,11 @@ export function buildAcceptDebtNote(open) {
         + 'They are records for a human decision, not instructions to edit code:\n'
         + items.map(i => `  - ${i}`).join('\n'));
 }
-/** One-line provenance label for a debt, for the surfaced report. */
+/**
+ * One-line provenance label for a debt, for the surfaced report. Straight off
+ * DEBT_LABELS, so a new origin cannot ship without one; an absent or unregistered
+ * origin falls back to the 'accepted' class exactly as the branch chain did.
+ */
 export function describeDebt(d) {
-    if (d.origin === 'enforce-revert') {
-        return 'enforce re-verify FAILED then the edits were reverted (defect indicts the ORIGINAL work, still shipped)';
-    }
-    if (d.origin === 'enforce-kept') {
-        return 'enforce re-verify FAILED on a check the enforce diff cannot reach — the guideline edits were KEPT (reverting them could not fix it) and the defect indicts the ORIGINAL work, still shipped';
-    }
-    if (d.origin === 'frozen-blocked') {
-        return 'repo health blocked by a spec-frozen path (cross-task contradiction — no task may perform the fixing edit)';
-    }
-    if (d.origin === 'cross-task-deletion') {
-        return "a sibling task's committed deliverable was DELETED by this task's work and the deletion was accepted (still missing from the tree)";
-    }
-    if (d.origin === 'yolo-accepted') {
-        return 'auto-ACCEPTED by YOLO mode despite verify-FAIL (unattended — no human weighed this)';
-    }
-    if (d.origin === 'root-cause') {
-        return "verify FAILed on a PRE-EXISTING defect in another task's file that this task never touched (this task's work was kept; a scoped repair task was queued for the root cause)";
-    }
-    if (d.origin === 'final-gate') {
-        return 'final-gate check DEMOTED to UNOBSERVED (identical failure across two tree-changing fix attempts — unfalsifiable in that environment, never proven passing)';
-    }
-    return 'accepted despite verify-FAIL';
+    return isKnownOrigin(d.origin) ? DEBT_LABELS[d.origin] : DEBT_LABELS.accepted;
 }

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

@@ -1,14 +1,15 @@
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
-import { type FinalGateFixFn } from './gate-deps.js';
 import { type GateDeps } from './task-gates.js';
-import { type AcceptDebt } from './accept-debt.js';
+import { type FinalGateStageDeps } from './run-final-gate.js';
 /**
  * Injectable seams so the planner and loop are testable without spawning pi.
- * `runChild` is the planning-only seam used by planAuto; everything else (runTask,
- * commit, verify, enforce, recommend, revert) is the shared post-implementation
- * gate surface defined by {@link GateDeps} and built by {@link buildGateDeps}.
+ * `runChild` is the planning-only seam used by planAuto; everything else is one of
+ * two shared gate surfaces — the per-task one ({@link GateDeps}, driven by
+ * runGatesForTask) and the run-end one ({@link FinalGateStageDeps}, driven by
+ * runFinalGateStage) — both built by {@link buildGateDeps} / defaultDeps. Only the
+ * loop's own repo-integrity probes are declared here.
  */
-export interface AutoDeps extends GateDeps {
+export interface AutoDeps extends GateDeps, FinalGateStageDeps {
     runChild: (name: string, tools: string, prompt: string) => Promise<string>;
     /**
      * Paths with unmerged index entries (an in-progress merge conflict). The loop
@@ -24,57 +25,6 @@ export interface AutoDeps extends GateDeps {
      * Absent (tests) → the check is skipped.
      */
     stashRef?: (cwd: string) => Promise<string | null>;
-    /**
-     * Whole-repo FINAL integration gate, run once when every task is checked off
-     * and BEFORE the run is declared complete (see final-gate.ts): the project's
-     * own static checks plus its own test/build commands, unaided. Absent (tests /
-     * gate off) → the run completes as before.
-     */
-    finalGate?: (cwd: string, planText?: string) => Promise<{
-        ok: boolean;
-        reason: string;
-        failures?: string[];
-        debtNote?: string;
-        openDebts?: AcceptDebt[];
-        /** Set ⇒ the gate observed nothing dynamic: UNOBSERVED, not PASS. */
-        unobserved?: string;
-    }>;
-    /**
-     * Bounded model-driven fix pass for a final-gate FAIL (see final-gate-fix.ts),
-     * offered as the picker's third option. Runs the fix child, applies the
-     * command-shrink guard, and re-runs the gate; the result's `ok` means the gate
-     * now passes. Absent (tests / no fix wiring) → the picker keeps only
-     * Leave-failed / Accept, exactly the pre-autofix behavior.
-     */
-    finalGateFix?: FinalGateFixFn;
-    /**
-     * Paths currently uncommitted in the working tree (`git status` shape), used to
-     * detect SUB-FIXES a non-converging final-gate autofix left behind (mx5 run 13
-     * PROMPT 4 item 3). Every task is committed by the time the final gate runs, so
-     * anything dirty here is the fix pass's own work. Absent → the stranded-fix
-     * handling is skipped entirely (prior behavior).
-     */
-    pendingChanges?: (cwd: string) => Promise<string[]>;
-    /**
-     * Re-derive the still-open ACCEPT-debt ledger against the tree AS IT IS NOW
-     * (final-gate.ts `deriveOpenDebts`). Needed because the run's "N recorded
-     * verify-FAIL defect(s) are STILL unresolved" report used to be built from the
-     * FIRST gate result and the converged-autofix path then rebuilt the gate
-     * outcome as a bare `{ok, reason}` — so `openDebts` was not merely un-actioned,
-     * it was GONE from the value, and no code path could ever clear, re-check or
-     * act on it (mx5 run 18: four defects reported STILL OPEN at 14:58, one of them
-     * fixed by the autofix that converged at 15:03, and the report never moved).
-     *
-     * `staticOk` is the caller's PROOF about the current statics, never a guess:
-     * pass true only where the gate itself just passed them. Absent (tests) → the
-     * post-autofix re-check is skipped and the pre-autofix report stands, exactly
-     * the prior behavior.
-     */
-    recheckOpenDebts?: (cwd: string, staticOk: boolean) => Promise<{
-        openDebts: AcceptDebt[];
-        debtNote?: string;
-        trail?: string[];
-    }>;
 }
 /**
  * Expand any @file references in the feature text by appending each referenced