@mjasnikovs/pi-task 0.41.0 → 0.42.1

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

@@ -89,6 +89,12 @@ export interface AcceptDebt {
      * string is the VERIFY-block line itself (`inv-command-provenance`).
      */
     verifyCommand?: string;
+    /**
+     * The task whose verified work CLOSED this debt (a health repair whose check
+     * went green — see closeHealthDebts). A closed debt stays in the ledger as the
+     * record of what fixed it, and no re-check reads it again.
+     */
+    resolvedBy?: string;
 }
 export declare function acceptDebtFile(cwd: string): string;
 /** The raw stored ledger ('' when none recorded yet). Parse with parseAcceptDebts. */
@@ -146,6 +152,16 @@ export declare function crossTaskDeletionReason(deletion: {
 export declare function extractDeletedDebtPath(reason: string): string | null;
 /** Overwrite the ledger with exactly these records (used to prune resolved debts). */
 export declare function writeAcceptDebts(cwd: string, debts: AcceptDebt[]): Promise<void>;
+/** The debts nothing has closed yet — the only ones a re-check may read. */
+export declare function readOpenAcceptDebts(cwd: string): Promise<AcceptDebt[]>;
+/**
+ * Close every open static-class debt that names `command`, stamping the task
+ * whose verified work made that check pass again. Returns the debts closed.
+ * A reason that quotes the command is the whole match: the health-check reason
+ * (`repo health: \`bun run lint\` exited 1`) and its inherited form both do,
+ * and nothing else in the ledger quotes a health command. Best-effort.
+ */
+export declare function closeHealthDebts(cwd: string, command: string, resolvedBy: string): Promise<AcceptDebt[]>;
 /**
  * STATIC-CLASS debt: one whose accepted FAIL was the deterministic whole-repo static
  * health check (`repo health: …`, the prefix runWorkVerification's repoHealth branch

package/dist/task/accept-debt.js

@@ -113,6 +113,7 @@ export function parseAcceptDebts(raw) {
         // 4th field: the verbatim VERIFY command the reason names.
         // Absent in every legacy record, and absent in most new ones.
         const verifyCommand = parts[3]?.trim();
+        const resolvedBy = parts[4]?.trim();
         out.push({
             taskId: parts[0].trim(),
             reason: parts[1].trim(),
@@ -120,7 +121,8 @@ export function parseAcceptDebts(raw) {
             // 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 } : {})
+            ...(verifyCommand !== undefined && verifyCommand.length > 0 ? { verifyCommand } : {}),
+            ...(resolvedBy !== undefined && resolvedBy.length > 0 ? { resolvedBy } : {})
         });
     }
     return out;
@@ -141,6 +143,16 @@ function serialize(d) {
     // 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.
+    // The 5th field likewise forces an (empty) 4th.
+    if (d.resolvedBy !== undefined && d.resolvedBy.length > 0) {
+        return [
+            d.taskId,
+            d.reason,
+            d.origin ?? 'accepted',
+            d.verifyCommand ?? '',
+            d.resolvedBy
+        ].join(FIELD_SEP);
+    }
     if (d.verifyCommand !== undefined && d.verifyCommand.length > 0) {
         return [d.taskId, d.reason, d.origin ?? 'accepted', d.verifyCommand].join(FIELD_SEP);
     }
@@ -234,6 +246,33 @@ export function extractDeletedDebtPath(reason) {
 export async function writeAcceptDebts(cwd, debts) {
     await ledger.write(cwd, debts);
 }
+/** The debts nothing has closed yet — the only ones a re-check may read. */
+export async function readOpenAcceptDebts(cwd) {
+    return (await readAcceptDebts(cwd)).filter(d => d.resolvedBy === undefined);
+}
+/**
+ * Close every open static-class debt that names `command`, stamping the task
+ * whose verified work made that check pass again. Returns the debts closed.
+ * A reason that quotes the command is the whole match: the health-check reason
+ * (`repo health: \`bun run lint\` exited 1`) and its inherited form both do,
+ * and nothing else in the ledger quotes a health command. Best-effort.
+ */
+export async function closeHealthDebts(cwd, command, resolvedBy) {
+    try {
+        const all = await readAcceptDebts(cwd);
+        const quoted = `\`${command}\``;
+        const closing = all.filter(d => d.resolvedBy === undefined
+            && isStaticClassDebt(d.reason)
+            && d.reason.includes(quoted));
+        if (closing.length === 0)
+            return [];
+        await ledger.write(cwd, all.map(d => (closing.includes(d) ? { ...d, resolvedBy } : d)));
+        return closing;
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * STATIC-CLASS debt: one whose accepted FAIL was the deterministic whole-repo static
  * health check (`repo health: …`, the prefix runWorkVerification's repoHealth branch
@@ -512,7 +551,10 @@ export function describeDebt(d) {
 export async function deriveOpenDebts(cwd, staticOk, 
 /** The spawner for the VERIFY-COMMAND re-runs. Defaults to the real one. */
 run = spawnCommand, signal) {
-    const { open: openRaw, resolved, trail } = await recheckAcceptDebts(await readAcceptDebts(cwd), {
+    const all = await readAcceptDebts(cwd);
+    // Closed debts are kept as the record of what fixed them, and never re-checked.
+    const closed = all.filter(d => d.resolvedBy !== undefined);
+    const { open: openRaw, resolved, trail } = await recheckAcceptDebts(all.filter(d => d.resolvedBy === undefined), {
         staticOk,
         // Cross-task-deletion debts auto-close iff the deleted file is back in the
         // tree — a deterministic existence check, corroborating the per-file
@@ -524,7 +566,7 @@ run = spawnCommand, signal) {
         rerunVerify: cmd => rerunDebtVerifyCommand(cwd, cmd, run, signal)
     });
     if (resolved.length > 0)
-        await writeAcceptDebts(cwd, openRaw);
+        await writeAcceptDebts(cwd, [...closed, ...openRaw]);
     // Conflicting-claim annotation: an existence-as-failure debt whose
     // named file is another task's committed deliverable is a plan defect — surface
     // the contradiction with the debt so nobody (human or child) treats the claim as

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

@@ -127,6 +127,13 @@ export declare function recordTaskEnd(cwd: string, id: string, index: number, la
  * cached index.
  */
 export declare function insertTaskAfter(cwd: string, id: string, afterIndex: number, title: string): Promise<boolean>;
+/**
+ * Insert a NEW unchecked entry directly BEFORE the `index`th checkbox — the
+ * position a health repair needs: the task about to run must wait until the red
+ * it would build on is fixed. Same monotonic, duplicate-refusing splice as
+ * {@link insertTaskAfter}.
+ */
+export declare function insertTaskBefore(cwd: string, id: string, index: number, title: string): Promise<boolean>;
 /**
  * Find the most-recently-updated resumable TASK_AUTO_* file, with the state and
  * last-write time the resume banner reports (see resume-gap.ts). Null when there

package/dist/task/auto-io.js

@@ -294,6 +294,9 @@ export async function insertTaskAfter(cwd, id, afterIndex, title) {
         if (!entry)
             continue;
         entries.push(entry);
+        // A negative afterIndex means "before the first entry".
+        if (entries.length === 1 && afterIndex < 0)
+            insertAt = i;
         if (entries.length - 1 <= afterIndex)
             insertAt = i + 1;
     }
@@ -310,6 +313,15 @@ export async function insertTaskAfter(cwd, id, afterIndex, title) {
     await setTaskSection(cwd, id, 'tasks', lines.join('\n'));
     return true;
 }
+/**
+ * Insert a NEW unchecked entry directly BEFORE the `index`th checkbox — the
+ * position a health repair needs: the task about to run must wait until the red
+ * it would build on is fixed. Same monotonic, duplicate-refusing splice as
+ * {@link insertTaskAfter}.
+ */
+export function insertTaskBefore(cwd, id, index, title) {
+    return insertTaskAfter(cwd, id, index - 1, title);
+}
 /**
  * Find the most-recently-updated resumable TASK_AUTO_* file, with the state and
  * last-write time the resume banner reports (see resume-gap.ts). Null when there

package/dist/task/auto-orchestrator.js

@@ -16,12 +16,12 @@ import { parseAutoAnswer, autoAnswerHasTag, deriveTitle } from './parsers.js';
 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 { allocateAutoId, buildAutoBody, parseDecomposeList, parseCoverageVerdict, UNNAMED_COVERAGE_GAP, parseTaskList, planKeyAt, checkOffTask, stampTaskInProgress, beginTaskAttempt, recordTaskEnd, insertTaskAfter, findResumableAutoDetailed } from './auto-io.js';
+import { allocateAutoId, buildAutoBody, parseDecomposeList, parseCoverageVerdict, UNNAMED_COVERAGE_GAP, parseTaskList, planKeyAt, checkOffTask, stampTaskInProgress, beginTaskAttempt, recordTaskEnd, insertTaskAfter, insertTaskBefore, findResumableAutoDetailed } from './auto-io.js';
 import { decideResume, UNATTENDED_STATES } from './resume-gap.js';
 import { ENTRY_ATTEMPT_BUDGET } from './gate-resolution.js';
 import { recordDebt } from './accept-debt.js';
 import { drainRepairQueue, mergeRepairCandidates, planHasRepairFor, parseRepairTitleFile, buildRepairTitle, buildRepairScopeFence, extractFailingCommand } from './root-cause-repair.js';
-import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath } from './task-io.js';
+import { writeTaskFile, readTaskFile, readSection, updateTaskFrontMatter, taskFilePath } from './task-io.js';
 // Re-exported as well as used: the @-mention helpers moved to their own module so
 // the research phase can select a cited spec doc without importing this one, and
 // the planning call sites still name them here.
@@ -37,6 +37,8 @@ import { getParentContextWindow } from './context-usage.js';
 import { ChildStatus, runPlanningChild, statusCallbacks } from './child-status.js';
 import { buildGateDeps, collectTreeChanges } from './gate-deps.js';
 import { runGatesForTask } from './task-gates.js';
+import { buildHealthRepairFence, buildHealthRepairTitle, healthRedSubject, parseHealthRepairTitle, planCoversHealthRed } from './health-repair.js';
+import { HEALTH_BASELINE_SECTION, parseHealthBaseline } from './health-baseline.js';
 import { runFinalGateStage } from './run-final-gate.js';
 import { gitUnmergedPaths, gitStashRef } from './auto-commit.js';
 import { runFinalIntegrationGate, deriveOpenDebts } from './final-gate.js';
@@ -324,6 +326,9 @@ export function buildScopeFence(entries, currentIndex) {
 export function buildStepFence(entries, currentIndex) {
     const base = buildScopeFence(entries, currentIndex);
     const title = entries[currentIndex]?.title ?? '';
+    const healthRepair = parseHealthRepairTitle(title);
+    if (healthRepair)
+        return `${base}\n\n${buildHealthRepairFence(healthRepair)}`;
     const repairFile = parseRepairTitleFile(title);
     if (!repairFile)
         return base;
@@ -373,6 +378,53 @@ async function schedulePendingRepairs(cwd, id, afterIndex, ctx, deps) {
         // the plan is best-effort here; the underlying debt is already recorded
     }
 }
+/**
+ * A red health check at the pre-task checkpoint becomes a repair entry spliced
+ * BEFORE the task about to run (health-repair.ts). Returns whether the plan
+ * changed — the caller then re-reads it and runs the repair first. No splice when
+ * the plan already covers this red (a repair that ran and failed included): the
+ * task then proceeds and inherits it, as the baseline differential intends.
+ */
+async function spliceHealthRepair(cwd, id, next, entries, health, ctx, deps) {
+    try {
+        const red = healthRedSubject(health, cwd, (await deps.repoFiles?.(cwd)) ?? null);
+        if (!red)
+            return false;
+        if (planCoversHealthRed(entries.map(e => e.title), red))
+            return false;
+        const owners = [];
+        for (const f of red.files) {
+            const owner = await deps.introducedBy?.(cwd, f);
+            if (owner && !owners.includes(owner))
+                owners.push(owner);
+        }
+        const title = buildHealthRepairTitle({ ...red, owners });
+        if (!(await insertTaskBefore(cwd, id, next.index, title)))
+            return false;
+        await deps.record?.(cwd, id, `plan: \`${red.command}\` is red at the checkpoint before step ${next.index + 1} — inserted repair step first: ${title}`);
+        notifyRun(ctx, `${id}: \`${red.command}\` is red before "${next.title}" — queued a repair for `
+            + `${red.files.length > 0 ? red.files.join(', ') : 'it'} to run first.`, 'warning');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The health baseline a task starts from: the one its (resumed) task file already
+ * holds, else a fresh capture at the checkpoint. Null when neither is available.
+ */
+async function baselineAtCheckpoint(ctx, cwd, resumeId, label, deps) {
+    if (resumeId) {
+        const stored = await readSection(cwd, resumeId, HEALTH_BASELINE_SECTION).catch(() => null);
+        const parsed = parseHealthBaseline(stored);
+        if (parsed)
+            return parsed;
+    }
+    if (!deps.captureHealthBaseline)
+        return null;
+    return deps.captureHealthBaseline(ctx, cwd, label);
+}
 /**
  * ORIENT — read the feature, strike what must never reach a planning child, and
  * derive the requirement ledger. Depends on nothing but the feature and the tree,
@@ -1312,14 +1364,20 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             // the tree clean: what the project's own statics say now is what this task
             // INHERITED, and the verify gate attributes a red check against it instead
             // of failing the task for a sibling's defect (health-baseline.ts). The
-            // inner task file does not exist yet, so the capture is handed to the
+            // inner task file does not exist yet, so the result is handed to the
             // runner, which writes the section once its id is allocated.
-            const capture = deps.captureHealthBaseline;
-            const healthBaseline = capture ?
-                {
-                    healthBaseline: (taskCtx) => capture(taskCtx, cwd, next.title)
-                }
-                : {};
+            //
+            // A RED baseline is also the one moment every way red enters the tree
+            // is visible before anything builds on it — an accepted regression, a
+            // leftover the checkpoint just committed, a repo red at run start — so
+            // it is where the repair is scheduled (health-repair.ts).
+            const baseline = await baselineAtCheckpoint(active, cwd, resumeId, next.title, deps);
+            if (baseline
+                && !baseline.outcome.ok
+                && (await spliceHealthRepair(cwd, id, next, entries, baseline.outcome, active, deps))) {
+                continue;
+            }
+            const healthBaseline = baseline ? { healthBaseline: () => Promise.resolve(baseline) } : {};
             // Stash ref before the task: compared after the gates so a stash pushed
             // during the task (impl model or any child) and left behind is called
             // out instead of silently waiting to detonate in a later task.

package/dist/task/gate-deps.js

@@ -33,7 +33,7 @@ import { readEnvNotes, appendEnvNotes } from './env-notes.js';
 import { currentRunContext } from './run-context.js';
 import { runGateEvidence, evidenceVerifyFindings } from './gate-evidence.js';
 import { readContracts } from './contracts.js';
-import { recordDebt } from './accept-debt.js';
+import { closeHealthDebts, recordDebt } from './accept-debt.js';
 import { recordRepairCandidate } from './root-cause-repair.js';
 import { runRepoHealthCheck } from './repo-health-check.js';
 import { runFinalIntegrationGate, discoverGateCommandLabels, discoverGateCommandBodies } from './final-gate.js';
@@ -786,6 +786,7 @@ export function buildGateDeps(params) {
         // origin, and the final integration gate re-checks each one at run end.
         recordDebt,
         recordRepairCandidate: (cwd2, candidate) => recordRepairCandidate(cwd2, candidate),
+        closeHealthDebts,
         // file → introducing task, the provenance half of the discriminator.
         introducedBy: (cwd2, rel) => Promise.resolve(taskThatIntroduced(cwd2, rel)),
         // Tracked paths, used only to resolve a bare file name a FAIL text names

package/dist/task/health-repair.d.ts

@@ -0,0 +1,68 @@
+/**
+ * health-repair — a red static check at a pre-task checkpoint becomes a repair
+ * entry in the running plan, BEFORE the next planned task builds on it.
+ *
+ * The failure this closes: red enters the tree by three doors — a task whose
+ * regression was accepted, a leftover from an abandoned run swept in by the
+ * checkpoint commit, a repo that was red when the run began — and none of them is
+ * a gate. The health baseline (health-baseline.ts) stops the NEXT task being
+ * blamed, but blaming nobody is not fixing it: every later task inherits the red,
+ * and only the run-end gate re-checks it. All three doors pass the checkpoint,
+ * which already measures health for the baseline, so that one measurement is
+ * where the repair is scheduled.
+ *
+ * The subject of a repair is what the health output NAMES: the tracked files the
+ * failing command reported, or the command itself when it named none. The plan is
+ * the dedup ledger — a title covering the same command, or any of the same files,
+ * means no second entry, checked-off ones included, which is what stops a repair
+ * that failed from being re-spawned.
+ */
+import type { HealthSignal } from './health-baseline.js';
+/** The failing check, and what its output named. */
+export interface HealthRed {
+    command: string;
+    exitCode: number | null;
+    /** Repo-relative tracked paths the output named, in first-seen order. */
+    files: string[];
+}
+export interface HealthRedOwners {
+    /** Task ids whose commits introduced the named files; empty when nothing in
+     *  the run owns them (a leftover, or a red the run started on). */
+    owners: string[];
+}
+/**
+ * What a red health result is about. Null when the result records no failing
+ * command (a legacy baseline, or a signal with no per-command detail) — there is
+ * nothing a repair could be pinned to.
+ */
+export declare function healthRedSubject(health: HealthSignal & {
+    output?: string;
+}, cwd: string, tracked: readonly string[] | null): HealthRed | null;
+/**
+ * The plan title, in one of two fixed shapes the parser below recovers:
+ *   `repair src/a.ts, src/b.ts: \`bun run lint\` exits 1 (introduced by TASK_0033)`
+ *   `repair \`bun run lint\`: exits 1 (no task in this run owns it)`
+ * The subject sits right after the prefix so it is both the dedup key and what
+ * the scope fence pins.
+ */
+export declare function buildHealthRepairTitle(red: HealthRed & HealthRedOwners): string;
+export interface HealthRepairSubject {
+    command: string;
+    files: string[];
+}
+/** The command and files a health-repair title names, or null for any other title. */
+export declare function parseHealthRepairTitle(title: string): HealthRepairSubject | null;
+/**
+ * Does the plan already carry a repair for this red? Same command, or any of the
+ * same files — including a file-scoped root-cause repair (root-cause-repair.ts),
+ * which pins the same file. Checked-off entries count: a repair that ran and
+ * failed lands in the debt ledger, never in the plan a second time.
+ */
+export declare function planCoversHealthRed(titles: readonly string[], red: HealthRed): boolean;
+/**
+ * The extra scope fence a health-repair entry carries into refine. Without it
+ * "repair src/a.ts" refines into "overhaul the client", and a fix child left free
+ * to choose greens a linter fastest by suppressing it — which is how the red in
+ * the run this closes was painted over the first time.
+ */
+export declare function buildHealthRepairFence(subject: HealthRepairSubject): string;

package/dist/task/health-repair.js

@@ -0,0 +1,124 @@
+import { parseRepairTitleFile } from './root-cause-repair.js';
+/** A path-like token: at least one directory separator, ending in a file name. */
+const PATH_TOKEN_RE = /(?:[\w.@-]+[\\/])+[\w.@-]+\.\w+/g;
+function normalisePath(p) {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '').trim();
+}
+/**
+ * Resolve a token the output printed to the ONE tracked file it names. Linters
+ * print absolute paths, compilers print repo-relative ones, and a stack trace
+ * prints `node_modules/...` — the tracked list is what tells a deliverable from
+ * noise. An ambiguous suffix (two tracked `src/x.ts`) resolves to nothing rather
+ * than to a guess.
+ */
+function resolveTracked(token, cwd, tracked) {
+    let t = normalisePath(token);
+    const root = normalisePath(cwd);
+    if (root.length > 0 && t.startsWith(`${root}/`))
+        t = t.slice(root.length + 1);
+    if (tracked.includes(t))
+        return t;
+    const bySuffix = tracked.filter(r => t.endsWith(`/${r}`));
+    return bySuffix.length === 1 ? bySuffix[0] : null;
+}
+/**
+ * What a red health result is about. Null when the result records no failing
+ * command (a legacy baseline, or a signal with no per-command detail) — there is
+ * nothing a repair could be pinned to.
+ */
+export function healthRedSubject(health, cwd, tracked) {
+    const failing = (health.commands ?? []).find(c => c.outcome === 'fail');
+    if (!failing)
+        return null;
+    const files = [];
+    if (tracked) {
+        for (const m of (health.output ?? '').matchAll(PATH_TOKEN_RE)) {
+            const rel = resolveTracked(m[0], cwd, tracked);
+            if (rel !== null && !files.includes(rel))
+                files.push(rel);
+        }
+    }
+    return { command: failing.cmd, exitCode: failing.exitCode, files };
+}
+// ─── Plan entry ──────────────────────────────────────────────────────────────
+/**
+ * The plan title, in one of two fixed shapes the parser below recovers:
+ *   `repair src/a.ts, src/b.ts: \`bun run lint\` exits 1 (introduced by TASK_0033)`
+ *   `repair \`bun run lint\`: exits 1 (no task in this run owns it)`
+ * The subject sits right after the prefix so it is both the dedup key and what
+ * the scope fence pins.
+ */
+export function buildHealthRepairTitle(red) {
+    const exits = `exits ${red.exitCode ?? '?'}`;
+    const owner = red.owners.length > 0 ?
+        `introduced by ${red.owners.join(', ')}`
+        : 'no task in this run owns it';
+    return red.files.length > 0 ?
+        `repair ${red.files.join(', ')}: \`${red.command}\` ${exits} (${owner})`
+        : `repair \`${red.command}\`: ${exits} (${owner})`;
+}
+const PATH = String.raw `(?:[\w.@-]+\/)*[\w.@-]+\.\w+`;
+const HEALTH_REPAIR_TITLE_RE = new RegExp(`^repair\\s+(?:\`([^\`]+)\`\\s*:\\s*exits|(${PATH}(?:,\\s*${PATH})*)\\s*:\\s*\`([^\`]+)\`\\s+exits)\\s`);
+/** The command and files a health-repair title names, or null for any other title. */
+export function parseHealthRepairTitle(title) {
+    const m = HEALTH_REPAIR_TITLE_RE.exec(title.trim());
+    if (!m)
+        return null;
+    if (m[1] !== undefined)
+        return { command: m[1].trim(), files: [] };
+    return { command: m[3].trim(), files: m[2].split(',').map(f => f.trim()) };
+}
+/**
+ * Does the plan already carry a repair for this red? Same command, or any of the
+ * same files — including a file-scoped root-cause repair (root-cause-repair.ts),
+ * which pins the same file. Checked-off entries count: a repair that ran and
+ * failed lands in the debt ledger, never in the plan a second time.
+ */
+export function planCoversHealthRed(titles, red) {
+    const files = new Set(red.files.map(f => normalisePath(f).toLowerCase()));
+    return titles.some(t => {
+        const rootCause = parseRepairTitleFile(t);
+        if (rootCause !== null && files.has(normalisePath(rootCause).toLowerCase()))
+            return true;
+        const h = parseHealthRepairTitle(t);
+        if (h === null)
+            return false;
+        if (h.command === red.command)
+            return true;
+        return h.files.some(f => files.has(normalisePath(f).toLowerCase()));
+    });
+}
+/**
+ * The extra scope fence a health-repair entry carries into refine. Without it
+ * "repair src/a.ts" refines into "overhaul the client", and a fix child left free
+ * to choose greens a linter fastest by suppressing it — which is how the red in
+ * the run this closes was painted over the first time.
+ */
+export function buildHealthRepairFence(subject) {
+    const scope = subject.files.length > 0 ?
+        [
+            `  - ${subject.files.map(f => `\`${f}\``).join(', ')} ${subject.files.length > 1 ? 'are' : 'is'} the ONLY`,
+            '    file(s) you may modify. Do not refactor, restructure, or "improve" anything else,',
+            '    and do not create new files.'
+        ]
+        : [
+            '  - Modify only the files the command reports. Do not refactor, restructure, or',
+            '    "improve" anything else, and do not create new files.'
+        ];
+    return [
+        `REPAIR TASK — this step exists ONLY to make \`${subject.command}\` pass again. It`,
+        'was created because that check was red before this step, and every later step',
+        'would otherwise build on the red; it is not a feature step and must not grow into one.',
+        '',
+        'HARD CONSTRAINTS for this step (they override any broader reading of the title):',
+        ...scope,
+        '  - Fix the reported findings and nothing more. Do NOT redesign the build, the',
+        '    lint configuration, the schema, or any shared infrastructure — a wider change',
+        "    here would silently overwrite sibling tasks' shipped work.",
+        '  - Do NOT suppress, disable, ignore or weaken the check to make it pass: no',
+        '    disable comments, no ignore entries, no relaxed rules, no deleted or skipped',
+        '    tests. A finding is fixed in the code it reports.',
+        `  - The VERIFY block MUST be exactly: \`${subject.command}\` — the check that was`,
+        '    red. It passing is the whole acceptance criterion.'
+    ].join('\n');
+}

package/dist/task/implementation-guards.d.ts

@@ -16,6 +16,10 @@ export declare function implementationGuardArmed(): boolean;
  * one altered byte is a new key and a clean slate on both counters.
  */
 export declare function blockedCallReason(toolName: string, count: number): string;
+/** Every file under the task dir is host-written. MEASURED: an mx5 implementer
+ *  wrote its report over TASK_AUTO_0001.md, and the run died on its front matter. */
+export declare function targetsTaskDir(toolName: string, input: unknown): boolean;
+export declare function taskDirWriteReason(): string;
 /** The reason on the final block, which also ends the turn. */
 export declare function terminalCallReason(): string;
 export declare function consumeGuardTermination(): boolean;

package/dist/task/implementation-guards.js

@@ -1,4 +1,5 @@
 import { LoopDetector, loopKey, LOOP_THRESHOLD, LOOP_WINDOW, MAX_LOOP_RESTARTS } from './loop-detector.js';
+import { TASKS_DIR_NAME } from './task-types.js';
 /**
  * Runaway guard for the IMPLEMENTATION TURN — the one model surface with none.
  *
@@ -81,6 +82,18 @@ export function blockedCallReason(toolName, count) {
     return (`Blocked: this is the ${count}th identical ${toolName} call in this turn. `
         + `Use what you already have, or do something different, then continue the task.`);
 }
+/** Every file under the task dir is host-written. MEASURED: an mx5 implementer
+ *  wrote its report over TASK_AUTO_0001.md, and the run died on its front matter. */
+export function targetsTaskDir(toolName, input) {
+    if (!MUTATING_TOOLS.has(toolName))
+        return false;
+    const target = input?.path;
+    return typeof target === 'string' && target.split(/[\\/]/).includes(TASKS_DIR_NAME);
+}
+export function taskDirWriteReason() {
+    return (`Blocked: ${TASKS_DIR_NAME}/ belongs to pi-task and is written only by the host. `
+        + `Put your report in your reply, not in a file, then continue the task.`);
+}
 /** The reason on the final block, which also ends the turn. */
 export function terminalCallReason() {
     return (`Blocked: this turn repeated one call past every warning, so it is being stopped `
@@ -120,6 +133,9 @@ export function registerImplementationGuards(pi) {
             if (state.terminating) {
                 return { block: true, terminate: true, reason: terminalCallReason() };
             }
+            if (targetsTaskDir(event.toolName, event.input)) {
+                return { block: true, reason: taskDirWriteReason() };
+            }
             const call = { name: event.toolName, args: event.input };
             const mutating = MUTATING_TOOLS.has(event.toolName);
             const hit = mutating ? state.edits.record(call) : state.loop.record(call);

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

@@ -176,6 +176,16 @@ export interface GateDeps {
      * queues repairs exactly like /task-auto — only the plan mutation is the loop's.
      */
     recordRepairCandidate?: (cwd: string, candidate: RepairCandidate) => Promise<void>;
+    /**
+     * Close the open static debts naming a health command, stamped with the task
+     * whose verified work made that check pass — a health repair entry
+     * (health-repair.ts) going green. Returns the debts closed. Absent (tests) →
+     * nothing closes.
+     */
+    closeHealthDebts?: (cwd: string, command: string, resolvedBy: string) => Promise<{
+        taskId: string;
+        reason: string;
+    }[]>;
     /**
      * Paths the CURRENT task's own work touches — the AUTHORSHIP discriminator for
      * the root-cause channel: a FAIL blamed on a file this task edited may well be
@@ -282,7 +292,9 @@ export type GateResult = {
  * clarify/grill dialog: the same SessionUI.ask races the local boxed picker against
  * a remote answer, with the two actions also surfaced as remote buttons.
  */
-export declare function askVerifyResolution(ctx: ExtensionCommandContext, title: string, failReason: string, rec: ResolutionOutcome): Promise<ResolutionChoice>;
+export declare function askVerifyResolution(ctx: ExtensionCommandContext, title: string, failReason: string, rec: ResolutionOutcome, 
+/** The repair ACCEPT would queue (a regressed health check), if any. */
+acceptQueues?: string): Promise<ResolutionChoice>;
 /**
  * Run the verify + enforce gates against a task's just-finished implementation.
  *

package/dist/task/task-gates.js

@@ -6,6 +6,7 @@ import { SessionUI, notifyBoth, notifyRun } from '../remote/bridge.js';
 import { isYoloMode, YOLO_STAMP } from './yolo.js';
 import { extractFailingCommand, findRepairCandidate, summariseDefect } from './root-cause-repair.js';
 import { attributeEnforceFailure } from './enforce-attribution.js';
+import { healthRedSubject, parseHealthRepairTitle } from './health-repair.js';
 // The debt ledger is reached through the injected `recordDebt` dep (so it stays
 // absent-in-tests); only the origin TYPE and the cross-task-deletion reason SHAPE
 // come from accept-debt.ts directly — the latter because its writer and its
@@ -23,10 +24,13 @@ import { updateTaskFrontMatter } from './task-io.js';
  * clarify/grill dialog: the same SessionUI.ask races the local boxed picker against
  * a remote answer, with the two actions also surfaced as remote buttons.
  */
-export async function askVerifyResolution(ctx, title, failReason, rec) {
-    const options = resolutionOptions(rec.recommend);
+export async function askVerifyResolution(ctx, title, failReason, rec, 
+/** The repair ACCEPT would queue (a regressed health check), if any. */
+acceptQueues) {
+    const options = resolutionOptions(rec.recommend, acceptQueues);
     const question = `Verification FAILED for "${title}".\n\n${failReason}\n\n`
-        + `Recommended: ${rec.recommend.toUpperCase()} — ${rec.rationale}`;
+        + `Recommended: ${rec.recommend.toUpperCase()} — ${rec.rationale}`
+        + (acceptQueues ? `\n\nACCEPT queues ${acceptQueues} before the next task.` : '');
     const answer = await new SessionUI(ctx).ask({
         localTitle: 'Verification failed — how should pi proceed?',
         displayQuestion: question,
@@ -38,6 +42,12 @@ export async function askVerifyResolution(ctx, title, failReason, rec) {
     });
     return classifyResolutionAnswer(answer);
 }
+/** The repair a red health check earns, as the picker and the trail name it. */
+function describeHealthRepair(red) {
+    return red.files.length > 0 ?
+        `a repair for ${red.files.join(', ')} (\`${red.command}\`)`
+        : `a repair for \`${red.command}\``;
+}
 /**
  * The VERIFY resolution loop: run the task's verification against the finished
  * work, and carry out what gate-resolution.ts's decision table says to do with a
@@ -72,6 +82,14 @@ export async function resolveVerifyGate(ctxIn, deps, p, rec, routeRootCause) {
             // recording must never break the gate sequence
         }
     };
+    const healthRedOf = async (health) => {
+        try {
+            return healthRedSubject(health, p.cwd, (await deps.repoFiles?.(p.cwd)) ?? null);
+        }
+        catch {
+            return null;
+        }
+    };
     // GATE: actually RUN the task's verification against the just-finished work
     // BEFORE it is checked off or committed. Whether this produced a GENUINE clean
     // pass (a real signal ran and the work met it) also decides how the enforce pass
@@ -142,6 +160,12 @@ export async function resolveVerifyGate(ctxIn, deps, p, rec, routeRootCause) {
                 await rec(`resolution: recommended ${recOutcome.recommend.toUpperCase()}`);
             contradiction ??= recOutcome.contradiction ?? null;
             const unattended = isYoloMode();
+            // A regressed health check is THIS task's red. Accepting it ships the
+            // red, and the next checkpoint splices a repair before anything builds
+            // on it (health-repair.ts) — named here so a human choosing ACCEPT
+            // sees what the choice queues, and the trail says the same.
+            const regression = verified.health ? await healthRedOf(verified.health) : null;
+            const acceptQueues = regression ? describeHealthRepair(regression) : undefined;
             const disposition = resolveDisposition({
                 failClass,
                 recommend: recOutcome.recommend,
@@ -170,7 +194,7 @@ export async function resolveVerifyGate(ctxIn, deps, p, rec, routeRootCause) {
                 if (disposition.rule !== 'judge-accept') {
                     await rec(`resolution: asking the human — ${disposition.reason}`);
                 }
-                choice = await askVerifyResolution(active, p.title, failReason, recOutcome);
+                choice = await askVerifyResolution(active, p.title, failReason, recOutcome, acceptQueues);
             }
             if (choice.action === 'cancel') {
                 await rec('resolution: user dismissed the verify-FAIL picker — paused');
@@ -193,6 +217,9 @@ export async function resolveVerifyGate(ctxIn, deps, p, rec, routeRootCause) {
                 await settleDebt(origin, disposition.rule === 'spec-contradiction' ?
                     `${failReason} — ${disposition.reason}`
                     : failReason);
+                if (acceptQueues) {
+                    await rec(`accept: repo health regressed by this task — ${acceptQueues} is spliced before the next task`);
+                }
                 // ROOT CAUSE: an accepted FAIL that some OTHER task's file caused is
                 // not fixed by accepting it — every later task keeps tripping over
                 // the same bug. Queue the scoped repair so the plan closes it.
@@ -283,6 +310,21 @@ export async function resolveVerifyGate(ctxIn, deps, p, rec, routeRootCause) {
             await rec(`accept-debt: inherited repo health — ${verified.inheritedHealth}`);
             await settleDebt('inherited-health', verified.inheritedHealth);
         }
+        // A health repair that verified CLEAN — the check it exists for ran green,
+        // nothing inherited — closes the debts that check opened, under its own id.
+        const repair = parseHealthRepairTitle(p.title);
+        if (repair && verified.ok && !verified.reason && !verified.inheritedHealth) {
+            try {
+                const closed = await deps.closeHealthDebts?.(p.cwd, repair.command, p.taskId);
+                if (closed && closed.length > 0) {
+                    await rec(`accept-debt: closed ${closed.length} debt(s) on \`${repair.command}\` — `
+                        + `${closed.map(d => d.taskId).join(', ')} — repaired by ${p.taskId}`);
+                }
+            }
+            catch {
+                // closing debts must never break the gate sequence
+            }
+        }
         // Loop exited because the work verified OR the user accepted the artifact. A
         // genuine clean pass is ok===true with NO reason; a no-op pass or an
         // accept-override (verified.ok still false at break) is NOT a guardable signal.

package/dist/task/verify-resolution.d.ts

@@ -64,7 +64,10 @@ export interface ResolutionChoice {
  * `recommended: i === 0`). Values are the bare tokens; remote buttons carry the
  * labels — {@link classifyResolutionAnswer} accepts both.
  */
-export declare function resolutionOptions(recommend: ResolutionRecommendation): {
+export declare function resolutionOptions(recommend: ResolutionRecommendation, 
+/** What ACCEPT queues besides keeping the artifact — the repair a red health
+ *  check earns — so the picker shows the whole consequence of the choice. */
+acceptQueues?: string): {
     label: string;
     value: string;
     recommended: boolean;

package/dist/task/verify-resolution.js

@@ -193,8 +193,14 @@ export const AUTOFIX_LABEL = 'Autofix — re-run the task to fix it, then verify
  * `recommended: i === 0`). Values are the bare tokens; remote buttons carry the
  * labels — {@link classifyResolutionAnswer} accepts both.
  */
-export function resolutionOptions(recommend) {
-    const accept = { label: ACCEPT_LABEL, value: ACCEPT_VALUE };
+export function resolutionOptions(recommend, 
+/** What ACCEPT queues besides keeping the artifact — the repair a red health
+ *  check earns — so the picker shows the whole consequence of the choice. */
+acceptQueues) {
+    const accept = {
+        label: acceptQueues ? `${ACCEPT_LABEL}; queues ${acceptQueues}` : ACCEPT_LABEL,
+        value: ACCEPT_VALUE
+    };
     const autofix = { label: AUTOFIX_LABEL, value: AUTOFIX_VALUE };
     return recommend === 'accept' ?
         [

package/dist/task/verify-work.d.ts

@@ -35,6 +35,7 @@ export interface VerifyPass {
     unobserved?: undefined;
     crossTaskDeletions?: undefined;
     inheritedHealth?: string;
+    health?: undefined;
     probes?: ProbeFindings;
 }
 /**
@@ -63,6 +64,11 @@ export interface VerifyFail {
      *  then ships in the next commit and the final gate must re-check it. */
     crossTaskDeletions?: CrossTaskDeletion[];
     inheritedHealth?: string;
+    /** The health result behind a `repo-health` FAIL: which command, and what its
+     *  output named. What an ACCEPT of this FAIL hands to the repair channel. */
+    health?: HealthSignal & {
+        output?: string;
+    };
     /** What the deterministic probes found for THIS verdict, carried out so an
      *  AUTOFIX re-run is told what the gate already knows (see fix-context.ts)
      *  instead of re-deriving it from the one-line reason. */
@@ -254,6 +260,7 @@ export interface VerificationDeps {
     repoHealth?: () => Promise<{
         ok: boolean;
         reason: string;
+        output?: string;
     } & HealthSignal>;
     /**
      * What those same checks said BEFORE this task ran (see health-baseline.ts).

package/dist/task/verify-work.js

@@ -908,7 +908,12 @@ export async function runWorkVerification(deps) {
         if (!h.ok) {
             const baseline = deps.healthBaseline ? await deps.healthBaseline() : null;
             if (classifyHealthDelta(baseline?.outcome ?? null, h) === 'regressed') {
-                return { ok: false, failClass: 'repo-health', reason: `repo health: ${h.reason}` };
+                return {
+                    ok: false,
+                    failClass: 'repo-health',
+                    reason: `repo health: ${h.reason}`,
+                    health: h
+                };
             }
             pre.repoHealth = inheritedHealthFindings(h);
             inheritedHealth = `repo health: ${h.reason} — already failing before this task`;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.41.0",
+    "version": "0.42.1",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",