@mjasnikovs/pi-task 0.18.38 → 0.18.40

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

@@ -29,8 +29,16 @@
  *     `lsof` and the sandbox had neither) and no further attempt can move it. The
  *     run is allowed to converge on the REMAINING checks, carrying this one here
  *     so the next run's gate re-checks and re-surfaces it rather than losing it.
+ *   - 'root-cause' — the task's verify FAILed because of a PRE-EXISTING defect in a
+ *     file a DIFFERENT task created, which this task's own work never touched (mx5
+ *     run 14: TASK_0007's `test/teardown.ts` TRUNCATE bug FAILed TASK_0013 and
+ *     TASK_0019). The current task is not at fault, so its work — and, at the
+ *     enforce site, the enforce pass's edits — are KEPT rather than reverted; the
+ *     defect is recorded here and a scoped repair task is queued into the plan
+ *     (root-cause-repair.ts). Before this class existed the ledger recorded the same
+ *     root cause twice and nothing ever scheduled a fix, so it survived ~24h.
  */
-export type DebtOrigin = 'accepted' | 'enforce-revert' | 'frozen-blocked' | 'cross-task-deletion' | 'yolo-accepted' | 'final-gate';
+export type DebtOrigin = 'accepted' | 'enforce-revert' | 'frozen-blocked' | 'cross-task-deletion' | 'yolo-accepted' | 'final-gate' | 'root-cause';
 /** One recorded defect: the task, why its VERIFY failed, and how it was recorded. */
 export interface AcceptDebt {
     taskId: string;
@@ -105,6 +113,15 @@ export declare function recordYoloAcceptDebt(cwd: string, taskId: string, reason
  * 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>;
 /**
  * The deleted path a cross-task-deletion debt names (the fixed shape
  * recordCrossTaskDeletionDebt writes). Null on any other reason text — an

package/dist/task/accept-debt.js

@@ -78,7 +78,8 @@ export function parseAcceptDebts(raw) {
                 || origin === 'frozen-blocked'
                 || origin === 'cross-task-deletion'
                 || origin === 'yolo-accepted'
-                || origin === 'final-gate') ?
+                || origin === 'final-gate'
+                || origin === 'root-cause') ?
                 { origin: origin }
                 : {})
         });
@@ -203,6 +204,21 @@ export async function recordFinalGateUnobservedDebt(cwd, taskId, reason) {
         origin: 'final-gate'
     });
 }
+/**
+ * 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 async function recordRootCauseDebt(cwd, taskId, reason) {
+    await appendDebt(cwd, {
+        taskId: taskId.trim(),
+        reason: normaliseReason(reason),
+        origin: 'root-cause'
+    });
+}
 /**
  * The deleted path a cross-task-deletion debt names (the fixed shape
  * recordCrossTaskDeletionDebt writes). Null on any other reason text — an
@@ -357,6 +373,9 @@ export function describeDebt(d) {
     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)';
     }

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

@@ -42,5 +42,21 @@ export declare function checkOffTask(cwd: string, id: string, index: number, pro
  * of starting a brand-new task — matching how /task-resume behaves.
  */
 export declare function stampTaskInProgress(cwd: string, id: string, index: number, producedId: string, title: string): Promise<void>;
+/**
+ * Insert a NEW unchecked entry directly after the `afterIndex`th checkbox — the
+ * mid-run plan mutation the root-cause repair channel needs (mx5 run 14 item 5:
+ * a repair task must land BEFORE the next dependent task, not at the end of the
+ * plan, or the defect keeps failing everything in between).
+ *
+ * MONOTONIC by construction (the run-12 replacement lesson): this only ever
+ * SPLICES a line in. No existing entry is rewritten, reordered, or dropped, and
+ * an already-present title is a no-op — so a plan can grow mid-run but never
+ * shrink, and a retried insert cannot duplicate. Returns whether a line was added.
+ *
+ * Later entries shift down by one, which is safe because the /task-auto loop
+ * re-reads and re-parses the plan at the top of every iteration and locates its
+ * next step by "first unchecked" rather than by a cached index.
+ */
+export declare function insertTaskAfter(cwd: string, id: string, afterIndex: number, title: string): Promise<boolean>;
 /** Find the most-recently-updated resumable TASK_AUTO_* file, or null. */
 export declare function findResumableAuto(cwd: string): Promise<string | null>;

package/dist/task/auto-io.js

@@ -140,6 +140,60 @@ export async function checkOffTask(cwd, id, index, producedId, title) {
 export async function stampTaskInProgress(cwd, id, index, producedId, title) {
     await rewriteTaskLine(cwd, id, index, () => `- [ ] ${producedId}  ${title}`, 'stampTaskInProgress');
 }
+/** The bare title of a checkbox line (id stamp stripped), or null if not one. */
+function entryTitle(line) {
+    const m = CHECKBOX_RE.exec(line.trim());
+    if (!m)
+        return null;
+    const rest = m[2].trim();
+    const idm = PRODUCED_ID_RE.exec(rest);
+    return idm ? idm[2].trim() : rest;
+}
+/**
+ * Insert a NEW unchecked entry directly after the `afterIndex`th checkbox — the
+ * mid-run plan mutation the root-cause repair channel needs (mx5 run 14 item 5:
+ * a repair task must land BEFORE the next dependent task, not at the end of the
+ * plan, or the defect keeps failing everything in between).
+ *
+ * MONOTONIC by construction (the run-12 replacement lesson): this only ever
+ * SPLICES a line in. No existing entry is rewritten, reordered, or dropped, and
+ * an already-present title is a no-op — so a plan can grow mid-run but never
+ * shrink, and a retried insert cannot duplicate. Returns whether a line was added.
+ *
+ * Later entries shift down by one, which is safe because the /task-auto loop
+ * re-reads and re-parses the plan at the top of every iteration and locates its
+ * next step by "first unchecked" rather than by a cached index.
+ */
+export async function insertTaskAfter(cwd, id, afterIndex, title) {
+    const clean = title.trim();
+    if (clean.length === 0)
+        return false;
+    const { body } = await readTaskFile(cwd, id);
+    const section = extractSection(body, 'tasks') ?? '';
+    const lines = section.split('\n');
+    // Duplicate check scans the WHOLE list first: an existing entry with this exact
+    // title (checked or not) means the plan already carries this step, wherever it
+    // sits relative to afterIndex — never add a second one.
+    if (lines.some(l => entryTitle(l) === clean))
+        return false;
+    let seen = -1;
+    let insertAt = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (!CHECKBOX_RE.test(lines[i].trim()))
+            continue;
+        seen++;
+        insertAt = i + 1;
+        if (seen === afterIndex)
+            break;
+    }
+    // An out-of-range index appends after the LAST checkbox rather than throwing:
+    // a plan that grew underneath the caller must still receive the entry.
+    if (insertAt === -1)
+        return false;
+    lines.splice(insertAt, 0, `- [ ] ${clean}`);
+    await setTaskSection(cwd, id, 'tasks', lines.join('\n'));
+    return true;
+}
 /** Find the most-recently-updated resumable TASK_AUTO_* file, or null. */
 export async function findResumableAuto(cwd) {
     await ensureTasksDir(cwd);

package/dist/task/auto-orchestrator.js

@@ -14,7 +14,8 @@ import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js'
 import { AUTO_CLARIFY_PROMPT, AUTO_DECOMPOSE_PROMPT, DECOMPOSE_COVERAGE_PROMPT } from './auto-prompts.js';
 import { GRILL_AUTO_ANSWER_PROMPT, GRILL_AUTO_FORMAT_HINT } from './prompts.js';
 import { isDuplicateQuestion, MAX_DUP_STRIKES, DUP_REPROMPT_HINT } from './question-dedup.js';
-import { allocateAutoId, buildAutoBody, parseDecomposeList, parseCoverageVerdict, parseTaskList, checkOffTask, stampTaskInProgress, findResumableAuto } from './auto-io.js';
+import { allocateAutoId, buildAutoBody, parseDecomposeList, parseCoverageVerdict, parseTaskList, checkOffTask, stampTaskInProgress, insertTaskAfter, findResumableAuto } from './auto-io.js';
+import { drainRepairQueue, mergeRepairCandidates, planHasRepairFor, parseRepairTitleFile, buildRepairTitle, buildRepairScopeFence, extractFailingCommand } from './root-cause-repair.js';
 import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath, tasksDir } from './task-io.js';
 import { readTextFile } from '../shared/fs-text.js';
 import { findPhantomImports, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
@@ -320,6 +321,63 @@ export function buildScopeFence(titles, currentIndex) {
         + `components, or flows owned by a later step.\n\n`
         + `The full plan (these run separately — do NOT implement them here):\n${listing}`);
 }
+/**
+ * The scope fence for step `currentIndex`, plus the REPAIR fence when that step is
+ * a queued root-cause repair. A repair title ("repair test/teardown.ts: …") reads
+ * to refine like any other feature step, and refine's job is to expand a title into
+ * a full spec — which is exactly how "repair the teardown" becomes "overhaul the
+ * test infrastructure" (the /task-auto drift lesson). The extra fence pins the one
+ * editable file and pins VERIFY to the command the defect was failing.
+ */
+function buildStepFence(titles, currentIndex) {
+    const base = buildScopeFence(titles, currentIndex);
+    const repairFile = parseRepairTitleFile(titles[currentIndex] ?? '');
+    if (!repairFile)
+        return base;
+    return `${base}\n\n${buildRepairScopeFence(repairFile, extractFailingCommand(titles[currentIndex] ?? ''))}`;
+}
+/**
+ * Drain the gate's root-cause repair queue into the running plan: one scoped
+ * repair step per accused FILE, spliced in directly after the step that just
+ * finished.
+ *
+ * Three bounds, all mandatory (mx5 run 14 item 5 gray areas):
+ *   - DEDUP by file — run 14's two `test/teardown.ts` debts must yield ONE repair
+ *     step, not two. mergeRepairCandidates collapses the drained queue, and
+ *     planHasRepairFor rejects a file the plan already carries a repair for.
+ *   - CAP 1 per file per RUN — planHasRepairFor counts CHECKED-OFF entries too, so
+ *     a repair step that itself failed is never re-spawned; it lands in the
+ *     accept-debt ledger like any other task. That is what stops a repair loop.
+ *   - MONOTONIC — insertTaskAfter only splices; no existing entry is rewritten,
+ *     reordered or dropped (the run-12 replacement lesson).
+ *
+ * Best-effort throughout: a fault here must never fail the run that produced the
+ * finding — the debt is already durably recorded either way.
+ */
+async function schedulePendingRepairs(cwd, id, afterIndex, ctx, deps) {
+    try {
+        const pending = await drainRepairQueue(cwd);
+        if (pending.length === 0)
+            return;
+        const { body } = await readTaskFile(cwd, id);
+        const titles = parseTaskList(body).map(e => e.title);
+        let at = afterIndex;
+        for (const repair of mergeRepairCandidates(pending)) {
+            if (planHasRepairFor(titles, repair.file))
+                continue;
+            const title = buildRepairTitle(repair);
+            if (!(await insertTaskAfter(cwd, id, at, title)))
+                continue;
+            titles.splice(at + 1, 0, title);
+            at += 1;
+            await deps.record?.(cwd, id, `plan: inserted scoped repair step after step ${afterIndex + 1} — ${title}`);
+            ctx.ui.notify(`${id}: queued a scoped repair for ${repair.file} (${repair.owner}'s file — root cause of ${repair.blamed.join(', ')}).`, 'warning');
+        }
+    }
+    catch {
+        // the plan is best-effort here; the underlying debt is already recorded
+    }
+}
 /** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
 export async function planAuto(ctx, cwd, feature, deps) {
     // clarify — sequential & adaptive: ask one question at a time, feeding every
@@ -1341,7 +1399,7 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 // matters when refine runs fresh (a resumed task past refine ignores
                 // it), but always supplied so a resume that restarts at refine is
                 // fenced too.
-                planContext: buildScopeFence(entries.map(e => e.title), next.index),
+                planContext: buildStepFence(entries.map(e => e.title), next.index),
                 onStart: resumeId ? undefined : (innerId => stampTaskInProgress(cwd, id, next.index, innerId, next.title))
             });
             active = res.ctx ?? active;
@@ -1396,7 +1454,7 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 title: next.title,
                 tag: id,
                 // Fence an AUTOFIX re-run against re-expanding the whole spec.
-                planContext: buildScopeFence(entries.map(e => e.title), next.index),
+                planContext: buildStepFence(entries.map(e => e.title), next.index),
                 // res.ok === true means runner.run() completed, so res.taskId is the
                 // allocated TASK_NNNN id (never empty here). The parent task-list
                 // check-off runs after verify passes/accepts and before the commit,
@@ -1426,6 +1484,14 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 announceDone(active, `${id} stopped at "${next.title}"${why} — fix and run /task-auto-resume.`, 'error');
                 return;
             }
+            // ROOT-CAUSE REPAIR (mx5 run 14 item 5): the gate may have attributed a
+            // FAIL to a pre-existing defect in a file some OTHER task created. It can
+            // only QUEUE that finding — mutating the plan is this loop's job. Drain
+            // the queue and splice a scoped repair step in right after the step that
+            // just finished, so the defect is fixed BEFORE the next dependent task
+            // trips over it too (run 14 recorded the same `test/teardown.ts` cause
+            // twice, scheduled nothing, and the bug outlived ~24h of the run).
+            await schedulePendingRepairs(cwd, id, next.index, active, deps);
             // gate.kind === 'done' → fall through to the next task, after checking
             // no landmine stash was left behind by anything that ran in between.
             if (deps.stashRef && stashBefore !== undefined) {
@@ -1518,13 +1584,15 @@ async function handleTaskAutoResume(_args, ctx) {
     autoRunning = true;
     armTerminalCancel(ctx);
     try {
-        // Reuse the interrupted run's research-cache id when the cache proves it still
-        // describes the same dependency surface (F10). mx5 run 13 resumed three times and
-        // each resume's fresh id discarded a working 201-entry cache; anything inconclusive
-        // still falls back to a fresh id and a re-fetch. See resumeResearchRun.
+        // Reuse the interrupted run's research-cache id, dropping only the entries whose
+        // own package moved version (F10). mx5 run 13 resumed three times and each
+        // resume's fresh id discarded a working 201-entry cache; run 14 then showed a
+        // whole-file freshness gate can never hold on a greenfield run that installs
+        // packages as it goes, so invalidation is per entry. See resumeResearchRun.
         const research = await resumeResearchRun(cwd, getConfig().researchCache);
         if (research.reused) {
-            logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies)`);
+            logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies), `
+                + `dropped ${research.dropped} stale`);
         }
         const abort = new AbortController();
         // Resume only runs the loop (runTask); no planning children, so the loader

package/dist/task/gate-deps.js

@@ -22,7 +22,8 @@ import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
 import { readEnvNotes, appendEnvNotes } from './env-notes.js';
 import { readContracts } from './contracts.js';
-import { recordAcceptDebt, recordEnforceRevertDebt, recordFrozenBlockedDebt, recordCrossTaskDeletionDebt, recordYoloAcceptDebt } from './accept-debt.js';
+import { recordAcceptDebt, recordEnforceRevertDebt, recordFrozenBlockedDebt, recordCrossTaskDeletionDebt, recordYoloAcceptDebt, recordRootCauseDebt } from './accept-debt.js';
+import { recordRepairCandidate } from './root-cause-repair.js';
 import { runRepoHealthCheck } from './repo-health-check.js';
 import { runFinalIntegrationGate, discoverGateCommandLabels } from './final-gate.js';
 import { runFinalGateAutofix } from './final-gate-fix.js';
@@ -471,6 +472,40 @@ export function buildGateDeps(params) {
         // deliverable this task's diff deletes, ACCEPTed into a commit anyway —
         // the final gate re-checks it (resolved iff the file is back in the tree).
         recordCrossTaskDeletionDebt: (cwd2, taskId, deletion) => recordCrossTaskDeletionDebt(cwd2, taskId, deletion),
+        // ROOT-CAUSE channel (mx5 run 14 item 5): a FAIL another task's untouched
+        // file caused is recorded as its own debt class and queued as a scoped
+        // repair task, instead of being blamed on — and reverted out of — the task
+        // that merely tripped over it.
+        recordRootCauseDebt: (cwd2, taskId, reason) => recordRootCauseDebt(cwd2, taskId, reason),
+        recordRepairCandidate: (cwd2, candidate) => recordRepairCandidate(cwd2, candidate),
+        // file → introducing task, the provenance half of the discriminator.
+        introducedBy: (cwd2, rel) => Promise.resolve(taskThatIntroduced(cwd2, rel)),
+        // The authorship half: which files THIS task's work touched. `worktree` is
+        // the pre-commit verify site (uncommitted changes); `committed` is the
+        // post-commit enforce site, where the task snapshot and the ENFORCE commit
+        // are the last two commits. Any git fault returns null, which stands the
+        // channel down entirely rather than guessing.
+        touchedFiles: async (cwd2, scope) => {
+            try {
+                if (scope === 'worktree') {
+                    const r = await git(cwd2, ['status', '--porcelain'], signal);
+                    if (r.exitCode !== 0)
+                        return null;
+                    const c = parseTreeChanges(r.stdout);
+                    return [...c.modified, ...c.added, ...c.deleted];
+                }
+                const r = await git(cwd2, ['log', '-n', '2', '--name-only', '--format=', 'HEAD'], signal);
+                if (r.exitCode !== 0)
+                    return null;
+                return r.stdout
+                    .split('\n')
+                    .map(l => l.trim())
+                    .filter(l => l.length > 0);
+            }
+            catch {
+                return null;
+            }
+        },
         // Frozen-path write-deny (see frozen-path-guard.ts): the concrete paths this
         // task's spec forbids modifying, so the gate sequence can UNDO any edit the
         // enforce EDIT pass makes to them before those edits are committed. Reads the

package/dist/task/root-cause-repair.d.ts

@@ -0,0 +1,122 @@
+/** One file accused of causing another task's verify FAIL. */
+export interface RepairCandidate {
+    /** Repo-relative path of the accused file. */
+    file: string;
+    /** The task whose commit introduced `file` (provenance). */
+    owner: string;
+    /** One-line summary of the defect, lifted from the FAIL text. */
+    defect: string;
+    /** The task whose verify FAILed because of it. */
+    blamedTask: string;
+    /** The failing command from the debt — becomes the repair task's VERIFY. */
+    verifyCommand?: string;
+}
+/** True when the FAIL text blames the ENVIRONMENT rather than a file. */
+export declare function isEnvironmentAttributed(text: string): boolean;
+interface Accusation {
+    file: string;
+    /** Character distance between the blame cue and the path token. */
+    distance: number;
+    /** The clause the accusation was made in — the defect summary source. */
+    clause: string;
+}
+/**
+ * The single file a FAIL text accuses, or null. Scans every blame cue, pairs it
+ * with the NEAREST path token within {@link BLAME_WINDOW} characters (a cue and its
+ * subject sit adjacent in practice: "pre-existing teardown bug in
+ * `test/teardown.ts`"), and keeps the closest pair overall. One FAIL has one root
+ * cause, so this deliberately returns at most one accusation rather than every
+ * path the reason happens to name.
+ */
+export declare function findAccusedFile(text: string): Accusation | null;
+/**
+ * Collapse whitespace and clamp — a stored defect summary is one short line that
+ * has to read well inside a plan title. The gate's own verdict boilerplate ("work
+ * did not verify: ") and a leading repeat of the accused file are stripped: the
+ * title already names both the step kind and the file, so repeating them there
+ * spends the clamp budget on nothing.
+ */
+export declare function summariseDefect(clause: string, file?: string): string;
+/**
+ * A runnable command quoted in the FAIL text — the repair task's VERIFY, per the
+ * requirement that it re-run the exact command the debt failed on. Only the first
+ * backticked token that STARTS like a shell command (optionally env-prefixed)
+ * qualifies, so prose in backticks is never mistaken for a command.
+ */
+export declare function extractFailingCommand(text: string): string | undefined;
+export interface RootCauseInput {
+    /** The verify gate's FAIL reason. */
+    failReason: string;
+    /** The resolution research's rationale, when one ran ('' otherwise). */
+    rationale?: string;
+    /** The task whose verify FAILed. */
+    currentTaskId: string;
+    /**
+     * Paths the CURRENT task's own work touches. `null` means unknown (git
+     * unavailable) — the channel stands down rather than guessing, so an
+     * unreadable tree can only cost a repair task, never spawn a wrong one.
+     */
+    touched: string[] | null;
+    /** file → introducing task (task-provenance.ts). May throw; a throw reads
+     *  as unknown provenance. */
+    introducedBy: (rel: string) => string | null | Promise<string | null>;
+}
+/**
+ * The repair candidate a verify FAIL justifies, or null. All three conditions from
+ * the module header must hold; anything unknown or environment-shaped returns null.
+ */
+export declare function findRepairCandidate(input: RootCauseInput): Promise<RepairCandidate | null>;
+export declare function repairQueueFile(cwd: string): string;
+/** Parse the stored queue. Malformed lines are skipped, never thrown on. */
+export declare function parseRepairQueue(raw: string): RepairCandidate[];
+/** Append one candidate. Best-effort — the queue never blocks a gate. */
+export declare function recordRepairCandidate(cwd: string, c: RepairCandidate): Promise<void>;
+/**
+ * Read the queue and CLEAR it. Draining is what makes the "cap 1 repair task per
+ * file per run" bound hold without a second ledger: whatever is drained either
+ * becomes a plan entry (which is then itself the dedup key — see
+ * {@link planHasRepairFor}) or was already covered by one.
+ */
+export declare function drainRepairQueue(cwd: string): Promise<RepairCandidate[]>;
+/** One merged repair per file, carrying every task the defect FAILed. */
+export interface MergedRepair {
+    file: string;
+    owner: string;
+    defect: string;
+    blamed: string[];
+    verifyCommand?: string;
+}
+/**
+ * Collapse candidates by file — MANDATORY dedup: run 14's two teardown.ts debts
+ * (TASK_0013, TASK_0019) must yield exactly ONE repair task naming both. First
+ * record wins for defect/command (they describe the same fault); blamed tasks
+ * accumulate in first-seen order.
+ */
+export declare function mergeRepairCandidates(candidates: RepairCandidate[]): MergedRepair[];
+/** Machine-recognisable prefix, so a repair entry can be found in a plan again. */
+export declare const REPAIR_TITLE_PREFIX = "repair ";
+/**
+ * The plan title for a repair task, in the fixed shape
+ * `repair <file>: <defect> (root cause of TASK_A, TASK_B debts)`. The file sits
+ * immediately after the prefix so {@link parseRepairTitleFile} can recover it —
+ * that recovery is both the dedup key and how the loop knows to attach the
+ * repair scope fence.
+ */
+export declare function buildRepairTitle(r: MergedRepair): string;
+/** The file a repair title names, or null when the title is not a repair entry. */
+export declare function parseRepairTitleFile(title: string): string | null;
+/**
+ * Is a repair for `file` ALREADY in the plan? This is the cap-1-per-file-per-run
+ * bound: it counts checked-off entries too, so a repair task that ran and FAILed
+ * is never re-spawned — it lands in the accept-debt ledger like any other task.
+ */
+export declare function planHasRepairFor(titles: string[], file: string): boolean;
+/**
+ * The extra scope fence a repair entry carries into refine. Without it, refine
+ * re-expands "repair test/teardown.ts: parameterized table names in TRUNCATE"
+ * into "overhaul the test infrastructure" — the /task-auto drift lesson. The
+ * fence pins the single editable file and pins the VERIFY to the exact command
+ * the debt failed on.
+ */
+export declare function buildRepairScopeFence(file: string, verifyCommand?: string): string;
+export {};