@mjasnikovs/pi-task 0.18.38 → 0.18.40

package/dist/task/root-cause-repair.js

@@ -0,0 +1,378 @@
+/**
+ * root-cause-repair — turn a verify-FAIL that was CAUSED by another task's file
+ * into a scoped repair task in the running plan (mx5 run 14, PROMPT item 5).
+ *
+ * The failure class this closes, observed end-to-end in run 14: TASK_0007 shipped
+ * `test/teardown.ts` with parameterized table names in its TRUNCATE statements.
+ * That bug then FAILED two later, unrelated tasks —
+ *
+ *   TASK_0013  "test/teardown.ts has a pre-existing bug (parameterized table names
+ *               in TRUNCATE statements) … despite all 10 actual tests passing"
+ *   TASK_0019  "… due to a pre-existing teardown bug in `test/teardown.ts`
+ *               (created by TASK_0007) … this task did not modify the teardown"
+ *
+ * — and BOTH ended in an enforce-revert, so the enforce pass's edits were destroyed
+ * over a defect the current task did not create. The ledger recorded the root cause
+ * twice and NOTHING ever scheduled a fix: the bug survived ~24h, until the final
+ * gate's fix child happened to patch it, and it also generated the "2 pre-existing
+ * failures / state pollution" excuse notes repeated across TASK_0033…0038.
+ *
+ * The channel here is deliberately narrow, because a false positive costs a whole
+ * task slot and mutates a running plan. Three independent conditions must ALL hold:
+ *
+ *   1. TEXT — the FAIL reason (or the resolution research's rationale) carries an
+ *      explicit blame cue ("pre-existing", "created by TASK_nnnn", "bug in", "this
+ *      task did not modify") and a path token near it. Merely MENTIONING a path is
+ *      not blame: run 14's TASK_0010 FAIL lists `src/server/db.ts` inside the
+ *      spec's own "Preserve all existing files on disk" quote, and must not spawn
+ *      a repair task for it.
+ *   2. PROVENANCE — the blamed file was introduced by a DIFFERENT task's commit
+ *      (task-provenance.ts). Unknown provenance is never evidence.
+ *   3. AUTHORSHIP — the current task's own work does not touch the blamed file. If
+ *      this task edited it, the defect may well be its own and the ordinary
+ *      autofix/revert path is right.
+ *
+ * Environment-attributed failures are vetoed outright (run 14's TASK_0006: "no
+ * PostgreSQL database server is available in this environment"). No file edit can
+ * repair a missing daemon, so a repair task would be a guaranteed non-converging
+ * yolo-FAIL.
+ *
+ * Everything downstream is deduplicated by FILE: N debts naming one root file yield
+ * exactly ONE repair task per run (run 14 would otherwise have spawned two for
+ * `test/teardown.ts`). The repair task itself is just an ordinary plan entry — if it
+ * fails, it lands in the ledger like any other task and is never re-spawned, which
+ * is what keeps this from looping.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { tasksDir } from './task-io.js';
+/** A path-like token: at least one directory separator, ending in a file name. */
+const PATH_TOKEN_RE = /(?:[\w.@-]+\/)+[\w.@-]+\.\w+/g;
+/**
+ * Phrases that ATTRIBUTE a failure to something that predates the current task.
+ * Each is a blame cue: the path token nearest a cue is the accused file. Kept
+ * deliberately specific — a bare "existing" matches the spec boilerplate
+ * "Preserve all existing files on disk" that run 14's TASK_0010 FAIL quotes.
+ */
+const BLAME_CUE_RE = /pre-?\s?existing|existing (?:bug|defect|failure|issue|fault)|(?:created|introduced|added|written) (?:by|in) TASK_\d+|(?:bug|defect|fault|error) in\b|already (?:broken|failing|red)|(?:this task )?did not (?:modify|touch|create|change)|not (?:modified|touched|created|introduced) by this task|unrelated to this task/gi;
+/**
+ * Failures the environment causes, not a file. No edit to any file repairs a
+ * missing database server, so these must never open the repair channel — run 14's
+ * TASK_0006 ("no PostgreSQL database server is available in this environment (no
+ * binary, no Docker, no listener on port 5432)") is the canonical shape.
+ */
+const ENVIRONMENT_BLAME_RE = /no (?:postgres|postgresql|mysql|database|redis|docker|network|internet|display)\b|not (?:installed|available|running|present) (?:in|on|for) (?:this |the )?(?:env|environment|sandbox|container|machine|image|system)|(?:environment|env|sandbox|container) (?:gap|limitation|lacks|has no|does not (?:have|provide))|no (?:binary|listener|daemon|server) (?:on|for|available)|missing (?:binary|executable|system (?:tool|package)|runtime)|is not installed|command not found/i;
+/** How far from a blame cue a path token may sit and still be the accused file. */
+const BLAME_WINDOW = 160;
+/** A recorded defect summary is one clamped line, not prose. */
+const MAX_DEFECT_LENGTH = 160;
+/** Ledger ceiling — a pathological run cannot grow the queue unboundedly. */
+const MAX_QUEUED = 40;
+const REPAIR_QUEUE_FILE = 'repair-queue.md';
+const FIELD_SEP = '\t';
+/** True when the FAIL text blames the ENVIRONMENT rather than a file. */
+export function isEnvironmentAttributed(text) {
+    return ENVIRONMENT_BLAME_RE.test(text);
+}
+/**
+ * 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 function findAccusedFile(text) {
+    if (text.trim().length === 0)
+        return null;
+    const paths = [...text.matchAll(PATH_TOKEN_RE)].map(m => ({
+        value: m[0],
+        start: m.index,
+        end: m.index + m[0].length
+    }));
+    if (paths.length === 0)
+        return null;
+    let best = null;
+    // matchAll on a /g regex is safe here (fresh iterator, no shared lastIndex).
+    for (const cue of text.matchAll(BLAME_CUE_RE)) {
+        const cueStart = cue.index;
+        const cueEnd = cueStart + cue[0].length;
+        for (const p of paths) {
+            const distance = p.start >= cueEnd ? p.start - cueEnd
+                : p.end <= cueStart ? cueStart - p.end
+                    : 0;
+            if (distance > BLAME_WINDOW)
+                continue;
+            if (best === null || distance < best.distance) {
+                best = { file: p.value, distance, clause: clauseAround(text, cueStart) };
+            }
+        }
+    }
+    return best;
+}
+/**
+ * The sentence/clause a character offset sits in. Splitting on sentence and dash
+ * boundaries keeps the defect summary to the accusation itself instead of the
+ * whole multi-clause FAIL reason.
+ */
+function clauseAround(text, offset) {
+    const before = text.slice(0, offset);
+    const startMatch = /[.;]\s|\s—\s/g;
+    let start = 0;
+    for (const m of before.matchAll(startMatch))
+        start = m.index + m[0].length;
+    const after = text.slice(offset);
+    const endMatch = /[.;]\s|\s—\s/.exec(after);
+    const end = endMatch ? offset + endMatch.index : text.length;
+    return text.slice(start, end).trim();
+}
+/**
+ * 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 function summariseDefect(clause, file) {
+    let out = clause.replace(/\s+/g, ' ').trim();
+    out = out.replace(/^work (?:did not verify|unobserved|is unverified)\s*:\s*/i, '');
+    if (file) {
+        const escaped = file.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        out = out.replace(new RegExp(`^\`?${escaped}\`?\\s+(?:has|had|contains)\\s+an?\\s+`, 'i'), '');
+    }
+    out = out.replace(/^[,\-—:\s]+/, '').trim();
+    // Drop trailing consequence clauses — "X is broken, which means the VERIFY
+    // command fails" restates the FAIL; the repair task only needs the X.
+    out = out.replace(/,\s*(?:which|so|meaning|causing the VERIFY)\b.*$/i, '');
+    if (out.length <= MAX_DEFECT_LENGTH)
+        return out;
+    const cut = out.slice(0, MAX_DEFECT_LENGTH);
+    const lastSpace = cut.lastIndexOf(' ');
+    return `${(lastSpace > MAX_DEFECT_LENGTH / 2 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}
+/**
+ * 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 function extractFailingCommand(text) {
+    const RUNNER = /^(?:[A-Z][A-Z0-9_]*=\S+\s+)*(?:bun|npm|pnpm|yarn|npx|node|deno|make|cargo|go|python3?|pytest|dotnet|mvn|gradle)\b\s+\S/;
+    for (const m of text.matchAll(/`([^`\n]+)`/g)) {
+        const cmd = m[1].trim();
+        if (RUNNER.test(cmd))
+            return cmd;
+    }
+    return undefined;
+}
+/**
+ * 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 async function findRepairCandidate(input) {
+    const current = input.currentTaskId.trim();
+    if (current.length === 0)
+        return null;
+    if (input.touched === null)
+        return null;
+    const text = [input.failReason, input.rationale ?? '']
+        .filter(t => t.trim().length > 0)
+        .join(' ');
+    if (text.trim().length === 0)
+        return null;
+    if (isEnvironmentAttributed(text))
+        return null;
+    const accused = findAccusedFile(text);
+    if (!accused)
+        return null;
+    // AUTHORSHIP: a file this task's own work touches is not somebody else's bug.
+    // Suffix-compare so an absolute or `./`-prefixed status path still matches.
+    const touchedSet = input.touched.map(t => normalisePath(t));
+    const file = normalisePath(accused.file);
+    if (touchedSet.some(t => t === file || t.endsWith(`/${file}`) || file.endsWith(`/${t}`))) {
+        return null;
+    }
+    let owner;
+    try {
+        owner = await input.introducedBy(accused.file);
+    }
+    catch {
+        owner = null;
+    }
+    if (!owner || owner === current)
+        return null;
+    return {
+        file: accused.file,
+        owner,
+        defect: summariseDefect(accused.clause, accused.file),
+        blamedTask: current,
+        ...(extractFailingCommand(text) ? { verifyCommand: extractFailingCommand(text) } : {})
+    };
+}
+function normalisePath(p) {
+    return p.replace(/^\.\//, '').replace(/^\/+/, '').trim();
+}
+// ─── Durable queue ───────────────────────────────────────────────────────────
+//
+// The gate sequence (task-gates.ts) DETECTS candidates; the /task-auto loop is
+// what may mutate the plan. They are decoupled through a small ledger under
+// `.pi-tasks/` — the same durability contract as accept-debt.ts: it survives
+// discardEdits and the git-state guard, and a resume picks up what a crash left.
+export function repairQueueFile(cwd) {
+    return path.join(tasksDir(cwd), REPAIR_QUEUE_FILE);
+}
+function serialize(c) {
+    return [c.file, c.owner, c.blamedTask, c.verifyCommand ?? '', c.defect]
+        .map(f => f.replace(/[\t\n]+/g, ' ').trim())
+        .join(FIELD_SEP);
+}
+/** Parse the stored queue. Malformed lines are skipped, never thrown on. */
+export function parseRepairQueue(raw) {
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const t = line.trim();
+        if (t.length === 0)
+            continue;
+        const parts = t.split(FIELD_SEP);
+        if (parts.length < 5)
+            continue;
+        const [file, owner, blamedTask, verifyCommand, defect] = parts;
+        if (!file.trim() || !owner.trim())
+            continue;
+        out.push({
+            file: file.trim(),
+            owner: owner.trim(),
+            blamedTask: blamedTask.trim(),
+            defect: defect.trim(),
+            ...(verifyCommand.trim() ? { verifyCommand: verifyCommand.trim() } : {})
+        });
+    }
+    return out;
+}
+/** Append one candidate. Best-effort — the queue never blocks a gate. */
+export async function recordRepairCandidate(cwd, c) {
+    try {
+        const existing = parseRepairQueue(await readQueueRaw(cwd));
+        const key = (x) => `${x.file.toLowerCase()} ${x.blamedTask.toLowerCase()}`;
+        if (existing.some(e => key(e) === key(c)))
+            return;
+        const kept = [...existing, c].slice(-MAX_QUEUED);
+        await fsp.mkdir(tasksDir(cwd), { recursive: true });
+        await fsp.writeFile(repairQueueFile(cwd), kept.map(serialize).join('\n') + '\n', 'utf8');
+    }
+    catch {
+        // best-effort ledger
+    }
+}
+async function readQueueRaw(cwd) {
+    try {
+        return (await fsp.readFile(repairQueueFile(cwd), 'utf8')).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * 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 async function drainRepairQueue(cwd) {
+    const parsed = parseRepairQueue(await readQueueRaw(cwd));
+    if (parsed.length === 0)
+        return [];
+    try {
+        await fsp.writeFile(repairQueueFile(cwd), '', 'utf8');
+    }
+    catch {
+        // best-effort; a failed clear at worst re-offers candidates that
+        // planHasRepairFor then rejects.
+    }
+    return parsed;
+}
+/**
+ * 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 function mergeRepairCandidates(candidates) {
+    const byFile = new Map();
+    for (const c of candidates) {
+        const key = normalisePath(c.file).toLowerCase();
+        const prev = byFile.get(key);
+        if (!prev) {
+            byFile.set(key, {
+                file: c.file,
+                owner: c.owner,
+                defect: c.defect,
+                blamed: c.blamedTask ? [c.blamedTask] : [],
+                ...(c.verifyCommand ? { verifyCommand: c.verifyCommand } : {})
+            });
+            continue;
+        }
+        if (c.blamedTask && !prev.blamed.includes(c.blamedTask))
+            prev.blamed.push(c.blamedTask);
+        if (!prev.verifyCommand && c.verifyCommand)
+            prev.verifyCommand = c.verifyCommand;
+    }
+    return [...byFile.values()];
+}
+// ─── Plan entry ──────────────────────────────────────────────────────────────
+/** Machine-recognisable prefix, so a repair entry can be found in a plan again. */
+export 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 function buildRepairTitle(r) {
+    const blame = r.blamed.length > 0 ? ` (root cause of ${r.blamed.join(', ')} debts)` : '';
+    return `${REPAIR_TITLE_PREFIX}${r.file}: ${r.defect}${blame}`;
+}
+/** The file a repair title names, or null when the title is not a repair entry. */
+export function parseRepairTitleFile(title) {
+    const m = /^repair\s+((?:[\w.@-]+\/)*[\w.@-]+\.\w+)\s*:/.exec(title.trim());
+    return m ? m[1] : 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 function planHasRepairFor(titles, file) {
+    const want = normalisePath(file).toLowerCase();
+    return titles.some(t => {
+        const f = parseRepairTitleFile(t);
+        return f !== null && normalisePath(f).toLowerCase() === want;
+    });
+}
+/**
+ * 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 function buildRepairScopeFence(file, verifyCommand) {
+    return [
+        `REPAIR TASK — this step exists ONLY to fix one specific pre-existing defect in`,
+        `\`${file}\`. It was created because that file made OTHER tasks' verification fail;`,
+        `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):',
+        `  - \`${file}\` is the ONLY file you may modify. Do not refactor, restructure, or`,
+        '    "improve" anything else, and do not create new files.',
+        '  - Fix the named defect and nothing more. Do NOT redesign the test harness, the',
+        '    build, the schema, or any shared infrastructure — a wider change here would',
+        "    silently overwrite sibling tasks' shipped work.",
+        '  - Do not delete or weaken any existing test to make the command pass.',
+        verifyCommand ?
+            `  - The VERIFY block MUST be exactly: \`${verifyCommand}\` — the command this`
+                + '    defect was failing. It passing is the whole acceptance criterion.'
+            : '  - The VERIFY block MUST re-run the command the defect was failing, unaided.'
+    ].join('\n');
+}

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

@@ -34,6 +34,7 @@ import type { CommitResult } from './auto-commit.js';
 import type { VerifyOutcome } from './verify-work.js';
 import type { EnforceOutcome } from './enforce-guidelines.js';
 import { type ResolutionOutcome, type ResolutionChoice } from './verify-resolution.js';
+import { type RepairCandidate } from './root-cause-repair.js';
 /**
  * The deps the gate sequence drives. A superset of these is built once per command
  * by buildGateDeps; AutoDeps extends this with the planning-only `runChild`. Every
@@ -162,6 +163,36 @@ export interface GateDeps {
         path: string;
         owner: string;
     }) => Promise<void>;
+    /**
+     * Record a durable ROOT-CAUSE debt (mx5 run 14 item 5): this task's verify
+     * FAILed on a pre-existing defect in a file ANOTHER task created and this task
+     * never touched. Its work is kept (it is not at fault) but the defect is real,
+     * so the final gate must re-check and surface it. Best-effort; absent in tests.
+     */
+    recordRootCauseDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
+    /**
+     * Queue a scoped repair task for a root-caused defect. The gate DETECTS the
+     * cause; only the /task-auto loop may mutate the plan, so the two are decoupled
+     * through the durable `.pi-tasks/repair-queue.md` ledger this writes (see
+     * root-cause-repair.ts). Absent (bare `/task`, tests) → detection still records
+     * the debt, nothing is scheduled.
+     */
+    recordRepairCandidate?: (cwd: string, candidate: RepairCandidate) => Promise<void>;
+    /**
+     * 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
+     * this task's own fault, and only a file it never touched can be somebody
+     * else's pre-existing bug. `worktree` = uncommitted changes (the pre-commit
+     * verify site); `committed` = the files the task snapshot + the ENFORCE commit
+     * changed (the post-commit enforce site). `null` means UNKNOWN (git
+     * unavailable) and stands the whole channel down — inconclusive is never
+     * evidence, so an unreadable tree can only cost a repair task, never spawn a
+     * wrong one or wrongly keep a regression.
+     */
+    touchedFiles?: (cwd: string, scope: 'worktree' | 'committed') => Promise<string[] | null>;
+    /** The task whose commit INTRODUCED a file (task-provenance.ts). Null for a
+     *  file predating the run or any git error → unknown provenance. */
+    introducedBy?: (cwd: string, rel: string) => Promise<string | null>;
     /**
      * The concrete paths this task's spec forbids modifying (its `Do NOT modify`
      * CONSTRAINTS — see frozen-path-guard.ts / prohibition-probe.ts). Used to

package/dist/task/task-gates.js

@@ -1,6 +1,7 @@
 import { resolutionOptions, classifyResolutionAnswer } from './verify-resolution.js';
 import { SessionUI } from '../remote/bridge.js';
 import { isYoloMode, yoloVerifyResolution, YOLO_STAMP } from './yolo.js';
+import { findRepairCandidate } from './root-cause-repair.js';
 /**
  * How many times a verify FAIL may be auto-fixed UNATTENDED (the research
  * recommended AUTOFIX, so pi re-runs the impl turn without prompting) before the
@@ -67,6 +68,39 @@ export async function runGatesForTask(ctxIn, deps, p) {
             // recording must never break the gate sequence
         }
     };
+    /**
+     * ROOT-CAUSE CHANNEL (mx5 run 14 item 5). Ask whether a FAIL was caused by a
+     * pre-existing defect in a file some OTHER task created and this task never
+     * touched. On a hit: record the durable debt (so the final gate surfaces it)
+     * and queue a scoped repair task (so something finally FIXES it — run 14
+     * recorded the same `test/teardown.ts` cause twice and scheduled nothing, and
+     * the bug survived ~24h). Returns the candidate so the caller can also decide
+     * NOT to punish the current task for it. Never throws: any fault degrades to
+     * null, i.e. exactly the pre-existing behavior.
+     */
+    const routeRootCause = async (failReason, rationale, scope) => {
+        if (!deps.touchedFiles || !deps.introducedBy)
+            return null;
+        try {
+            const candidate = await findRepairCandidate({
+                failReason,
+                rationale,
+                currentTaskId: p.taskId,
+                touched: await deps.touchedFiles(p.cwd, scope),
+                introducedBy: rel => deps.introducedBy(p.cwd, rel)
+            });
+            if (!candidate)
+                return null;
+            await deps.recordRootCauseDebt?.(p.cwd, p.taskId, `${failReason} — ROOT CAUSE: \`${candidate.file}\` (introduced by ${candidate.owner}, not touched by this task)`);
+            await deps.recordRepairCandidate?.(p.cwd, candidate);
+            await rec(`root-cause: FAIL attributed to \`${candidate.file}\` — a pre-existing defect in ${candidate.owner}'s file that this task never touched; `
+                + 'recorded as durable debt and a scoped repair task queued');
+            return candidate;
+        }
+        catch {
+            return null;
+        }
+    };
     const verdictLine = (v) => v.ok ?
         v.reason ?
             `verify: PASS (${v.reason})`
@@ -230,6 +264,11 @@ export async function runGatesForTask(ctxIn, deps, p) {
                         // recording must never break the gate sequence
                     }
                 }
+                // ROOT CAUSE: an accepted FAIL that some OTHER task's file caused is
+                // not fixed by accepting it — run 14 accepted this shape repeatedly
+                // and the causing bug outlived the whole run. Queue the scoped repair
+                // so the plan actually closes it.
+                await routeRootCause(failReason, recOutcome.rationale, 'worktree');
                 // Cross-task deletions the verify probe detected ship in the next
                 // commit with this ACCEPT — record each as its own durable debt so
                 // the final gate re-checks them (mx5 run 12 PROMPT 2). Best-effort.
@@ -413,7 +452,25 @@ export async function runGatesForTask(ctxIn, deps, p) {
                 const after = deps.verify ?
                     await deps.verify(active, p.cwd, p.title, p.taskId)
                     : { ok: true };
-                if (!after.ok) {
+                const afterReason = after.reason ?? 'enforce re-verify failed';
+                // PRE-EXISTING-CAUSE KEEP PATH (mx5 run 14 item 5b). Both of run
+                // 14's enforce-reverts were this shape: the re-verify FAILed on
+                // TASK_0007's `test/teardown.ts` TRUNCATE bug — a file neither the
+                // task's work nor the enforce pass touched — and the differential
+                // reverted enforce's edits anyway, destroying good work over a fault
+                // it did not cause AND leaving the actual cause unscheduled. When the
+                // FAIL is attributed to another task's untouched file, KEEP the edits
+                // and route the real defect to a repair task instead. Everything
+                // unknown (git unavailable, no provenance, this task touched the file,
+                // an environment-blamed FAIL) falls through to the revert below —
+                // the conservative pre-existing behavior.
+                const rootCause = after.ok ? null : await routeRootCause(afterReason, '', 'committed');
+                if (!after.ok && rootCause) {
+                    await rec(`enforce: re-verify FAILED (${afterReason.slice(0, 200)}) but the failure is attributed to a PRE-EXISTING defect in \`${rootCause.file}\` `
+                        + `(${rootCause.owner}'s file, untouched by this task and by the enforce pass) — edits KEPT, not reverted; repair task queued`);
+                    active.ui.notify(`${p.tag}: guideline fixes on "${p.title}" re-verified red on a pre-existing defect in ${rootCause.file} (${rootCause.owner}'s file) — keeping the fixes, queued a repair task.`, 'warning');
+                }
+                else if (!after.ok) {
                     if (deps.revert)
                         await deps.revert(p.cwd);
                     await rec(`enforce: fixes committed but re-verify FAILED (${(after.reason ?? 'now fails').slice(0, 200)}) — ${deps.revert ? 'REVERTED' : 'left in place (no revert available)'}`);

package/dist/workers/pi-worker-docs.d.ts

@@ -5,6 +5,13 @@ import { resolvePackage as defaultResolvePackage } from './docs-resolve.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
 import { type SpawnFn } from '../shared/child-process.js';
+/**
+ * The package NAME a module specifier belongs to — `hono/client` → `hono`,
+ * `@scope/name/sub` → `@scope/name`. The cache stores this (not the raw specifier) as an
+ * entry's package provenance, so a subpath lookup is matched against package.json's key
+ * and invalidated with its package rather than living forever unmatched.
+ */
+export declare function packageRootOf(module: string): string;
 export interface PiWorkerDocsInternals {
     resolvePackage?: typeof defaultResolvePackage;
     ensureIndexed?: typeof defaultEnsureIndexed;

package/dist/workers/pi-worker-docs.js

@@ -21,6 +21,16 @@ const Params = Type.Object({
         description: 'What to extract from the docs. The child pi reads ranked chunks and returns ONLY content answering this.'
     })
 });
+/**
+ * The package NAME a module specifier belongs to — `hono/client` → `hono`,
+ * `@scope/name/sub` → `@scope/name`. The cache stores this (not the raw specifier) as an
+ * entry's package provenance, so a subpath lookup is matched against package.json's key
+ * and invalidated with its package rather than living forever unmatched.
+ */
+export function packageRootOf(module) {
+    const parts = module.trim().split('/');
+    return parts[0].startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
 function pinDetails(pin) {
     return pin ? { versionSource: pin.source, declaredRange: pin.range } : {};
 }
@@ -249,6 +259,12 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         cacheKey: params => params.module === '.' ?
             null
             : `${normalizeQuery(params.module)}::${normalizeQuery(params.query)}`,
+        // Package provenance for per-entry resume invalidation: a docs digest describes
+        // one package at one declared version, so a resume drops it only when THAT
+        // package moves — an unrelated install no longer discards it. Package names are
+        // matched against package.json verbatim (npm names are case-sensitive), unlike
+        // the cache key, which normalises for phrasing collisions.
+        cachePkg: params => (params.module === '.' ? undefined : packageRootOf(params.module)),
         // Only a completed lookup (child exited 0) is a real answer; not-installed,
         // no-chunks, resolve/cache errors, and aborts omit childExitCode:0 and fall
         // through to a live retry next time.

package/dist/workers/research-cache.d.ts

@@ -23,31 +23,32 @@ export declare function configureResearchRun(enabled: boolean): string | undefin
  */
 export declare function normalizeQuery(s: string): string;
 /**
- * A stable fingerprint of the project's declared dependency surface — the only input a
- * cached docs digest actually depends on (a digest summarises a package's INSTALLED
- * types/README at a pinned version). Built from package.json's dependency blocks with
- * keys sorted, so formatting churn or an unrelated field edit does not invalidate it,
- * while any add/remove/version-bump does.
+ * The project's declared dependency surface as a name→range map, flattened across every
+ * dependency block (a package listed in two blocks resolves to the first range seen, in
+ * block order — a real manifest does not disagree with itself, and a disagreement can
+ * only make the comparison stricter, i.e. re-fetch).
  *
- * Returns undefined when the manifest is missing or unparseable — the caller then has
- * NO positive evidence of freshness and must not reuse. Deliberately NOT the lockfile's
- * hash or mtime: a lockfile is rewritten by installs that do not change any resolved
- * version, which would defeat reuse for no correctness gain.
+ * Returns undefined when the manifest is missing or unparseable: the caller then cannot
+ * prove any package's version and must treat every package-scoped entry as unprovable.
+ * Deliberately NOT the lockfile: it is rewritten by installs that change no resolved
+ * version, which would drop digests for no correctness gain.
  */
-export declare function depsFingerprint(cwd: string): Promise<string | undefined>;
+export declare function depsMap(cwd: string): Promise<Record<string, string> | undefined>;
 /**
- * Resume hook: reuse the interrupted run's cache id when — and only when — the file
- * proves it describes the same dependency surface. Returns the id now stamped into the
- * environment (reused or fresh), or undefined when caching is off.
+ * Resume hook: keep the interrupted run's cache id and PRUNE the entries the manifest
+ * has invalidated, rather than discarding the whole cache because anything moved. Returns
+ * the id now stamped into the environment (reused or fresh), how many entries survived,
+ * and how many were dropped; undefined id when caching is off.
  *
- * Every uncertain path falls through to a fresh id, which merely re-fetches:
- * caching disabled, no/corrupt cache file, a file with no fingerprint (written before
- * this shipped), an unreadable manifest, or a fingerprint that no longer matches.
+ * Falls through to a fresh id only where there is nothing to reuse or nothing to reason
+ * with: caching disabled, no/corrupt cache file, or a file predating per-entry package
+ * provenance (`pkgv`) whose docs entries cannot be told apart from its search entries.
  */
 export declare function resumeResearchRun(cwd: string, enabled: boolean): Promise<{
     runId: string | undefined;
     reused: boolean;
     entries: number;
+    dropped: number;
 }>;
 /**
  * Look up a cached result for `key` in the current run. Returns undefined on a miss,
@@ -61,6 +62,13 @@ export declare function lookupResearch(cwd: string, runId: string, key: string):
  * Store a successful result under `key` for the current run. A file written for a
  * different run id is discarded and started fresh (first write of a new run drops the
  * prior run's contents — self-healing per-run isolation without an explicit clear).
+ *
+ * `pkg` is the npm package the answer is ABOUT, supplied by package-scoped tools (docs).
+ * Its declared version is resolved HERE, at store time, so a package installed mid-run
+ * is stamped with the version its own digest was taken against — not with whatever the
+ * manifest happened to say at the run's first write. That is what makes a later resume
+ * able to prune this one entry instead of the whole file.
+ *
  * Best-effort: any failure is swallowed, leaving the caller's live result untouched.
  */
-export declare function storeResearch(cwd: string, runId: string, key: string, text: string, details: unknown): Promise<void>;
+export declare function storeResearch(cwd: string, runId: string, key: string, text: string, details: unknown, pkg?: string): Promise<void>;