@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/dist/task/gate-resolution.js

@@ -0,0 +1,120 @@
+/** Attempts a class whose defect an implementation re-run can actually move. */
+const REATTEMPTABLE_BUDGET = 3;
+/**
+ * How many UNATTENDED implementation re-runs each FAIL class is worth.
+ *
+ * Zero is a statement, not a disabled feature: an absent tool is not installed by
+ * re-running the work that needed it, and a verification pass that could not run
+ * is not repaired by changing the code it failed to judge. Spending three turns
+ * on either is how a run burns an hour to arrive where round one already was.
+ */
+export const AUTOFIX_BUDGET = {
+    'repo-health': REATTEMPTABLE_BUDGET,
+    'static-checks': REATTEMPTABLE_BUDGET,
+    'model-verdict': REATTEMPTABLE_BUDGET,
+    unobserved: 0,
+    'harness-fault': 0
+};
+/**
+ * How many times the /task-auto loop will START one plan entry before abandoning it.
+ *
+ * Derived, not chosen: one run to reach the gate at all, plus the re-runs the most
+ * forgiving fail class is worth inside that run. An entry that comes back for a
+ * further attempt has already spent a full autofix budget without converging, and
+ * the plan's remaining entries are worth more than its next round. Raising a class
+ * budget raises this with it, which is the relationship that should hold.
+ */
+export const ENTRY_ATTEMPT_BUDGET = 1 + Math.max(...Object.values(AUTOFIX_BUDGET));
+/** The budget in force, honouring an UNOBSERVED flag on any class. */
+export function autofixBudget(i) {
+    return i.unobserved ? 0 : AUTOFIX_BUDGET[i.failClass];
+}
+export function contradictionReason(c) {
+    const criterion = c.criterion.trim();
+    return (`spec contradiction — \`${c.frozenPath}\` is frozen by this task's spec and `
+        + `${criterion.length > 0 ? criterion : 'the failing check'} cannot be satisfied `
+        + 'without editing it; no re-run under the same freeze converges');
+}
+/**
+ * The two ends of the ladder that are NOT an autofix: ask a human, or — when
+ * there is no human — accept and write the defect down under the origin that says
+ * a machine decided.
+ */
+function terminal(i, rule, reason) {
+    return i.unattended ?
+        { rule, action: 'accept', debtOrigin: 'yolo-accepted', reason }
+        : { rule, action: 'ask', debtOrigin: null, reason };
+}
+function noBudgetReason(i) {
+    return i.unobserved || i.failClass === 'unobserved' ?
+        'verify UNOBSERVED — the spec-required check could not run (tooling absent) and an '
+            + 'unattended re-run cannot provision it'
+        : 'the verification pass itself could not run — re-running the implementation cannot '
+            + 'fix a harness fault';
+}
+/**
+ * The ordered ladder. FIRST MATCH WINS, and this order is the only statement of
+ * the policy:
+ *
+ *  1. `spec-contradiction` — the fix the check demands is the edit the spec
+ *     forbids. First, because every row below would otherwise spend a budget,
+ *     a human's attention or both on a loop that cannot converge (0053 ran three
+ *     rounds past this exact fact).
+ *  2. `judge-accept` — before any budget arithmetic, because that arithmetic is
+ *     precisely what used to override a correct ACCEPT with a rescue attempt.
+ *  3. `no-autofix-budget` — a class worth zero attempts. Its own row, not folded
+ *     into the one below, because a budget that was never offered must not be
+ *     reported as one that was spent.
+ *  4. `budget-spent` — consecutive unattended attempts that all still FAIL. A
+ *     person breaks the loop, or (unattended) it terminates with a debt.
+ *  5. `autofix` — unconditional, so the table is total.
+ */
+export const RESOLUTION_RULES = [
+    {
+        id: 'spec-contradiction',
+        match: i => i.contradiction === null ?
+            null
+            : {
+                rule: 'spec-contradiction',
+                action: 'accept',
+                debtOrigin: 'spec-contradiction',
+                reason: contradictionReason(i.contradiction)
+            }
+    },
+    {
+        id: 'judge-accept',
+        match: i => i.recommend === 'accept' ?
+            terminal(i, 'judge-accept', `judge recommended ACCEPT after investigating the workspace (autofix budget `
+                + `${i.attempts}/${autofixBudget(i)})`)
+            : null
+    },
+    {
+        id: 'no-autofix-budget',
+        match: i => autofixBudget(i) === 0 ? terminal(i, 'no-autofix-budget', noBudgetReason(i)) : null
+    },
+    {
+        id: 'budget-spent',
+        match: i => i.attempts >= autofixBudget(i) ?
+            terminal(i, 'budget-spent', `autofix budget spent (${i.attempts}/${autofixBudget(i)})`)
+            : null
+    },
+    {
+        id: 'autofix',
+        match: i => ({
+            rule: 'autofix',
+            action: 'autofix',
+            debtOrigin: null,
+            reason: `autofix recommended, unattended ${i.attempts + 1}/${autofixBudget(i)}`
+        })
+    }
+];
+export function resolveDisposition(i) {
+    for (const rule of RESOLUTION_RULES) {
+        const d = rule.match(i);
+        if (d !== null)
+            return d;
+    }
+    // Unreachable while the last row is unconditional; a reordering that breaks
+    // that fails loudly here instead of returning undefined into the gate loop.
+    throw new Error('RESOLUTION_RULES must end in an unconditional row');
+}

package/dist/task/git-state-guard.js

@@ -46,8 +46,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { makeGit } from '../shared/git-runner.js';
 import { isRegenerableArtifact } from './regenerable-artifacts.js';
-/** Keep the gate machinery's own artifacts out of the snapshot and the restore. */
-const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
+import { worktreeTreeHash } from './tree-hash.js';
 /**
  * Untracked paths that are regenerable test/build OUTPUT, not graded source. A gate
  * child creating or rewriting one of these has not mutated the work under
@@ -115,28 +114,6 @@ function isAlwaysRegenerable(relPath, ctCacheDirs) {
         return true;
     return ctCacheDirs.some(d => p === d || p.startsWith(d + '/'));
 }
-/**
- * Snapshot the worktree content into a tree object via a THROWAWAY index file, so
- * neither the real index nor the stash is touched. Returns null when git cannot
- * build the tree (odd states — the guard then skips tree reconciliation).
- */
-async function captureWorktreeTree(git) {
-    const tmpIndex = path.join(os.tmpdir(), `pi-task-guard-index-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
-    const env = { GIT_INDEX_FILE: tmpIndex };
-    try {
-        const empty = await git(['read-tree', '--empty'], env);
-        if (empty.exitCode !== 0)
-            return null;
-        const add = await git(['add', '-A', '--', '.', EXCLUDE_TASKS_DIR], env);
-        if (add.exitCode !== 0)
-            return null;
-        const tree = await git(['write-tree'], env);
-        return tree.exitCode === 0 ? tree.stdout.trim() : null;
-    }
-    finally {
-        await fsp.rm(tmpIndex, { force: true }).catch(() => { });
-    }
-}
 /** Capture the repo state a gate child must leave untouched. */
 export async function captureGitState(cwd, signal, spawnFn) {
     const git = makeGit(cwd, signal, spawnFn);
@@ -161,7 +138,7 @@ export async function captureGitState(cwd, signal, spawnFn) {
         headSha: head.stdout.trim(),
         branchRef: branch.exitCode === 0 ? branch.stdout.trim() : null,
         stashSha: stash.exitCode === 0 ? stash.stdout.trim() : null,
-        treeSha: await captureWorktreeTree(git)
+        treeSha: await worktreeTreeHash(git)
     };
 }
 /** Paths tracked in the commit `headSha` points at — the "graded" codebase a gate
@@ -309,7 +286,7 @@ export async function reconcileGitState(cwd, before, signal, spawnFn) {
     }
     // 2. Worktree content.
     if (before.treeSha) {
-        const afterTree = await captureWorktreeTree(git);
+        const afterTree = await worktreeTreeHash(git);
         if (afterTree && afterTree !== before.treeSha) {
             const tracked = await trackedPathsAt(git, before.headSha);
             const ctCacheDirs = readCtCacheDirs(cwd);

package/dist/task/handoff.d.ts

@@ -0,0 +1,35 @@
+import type { FixContext } from './fix-context.js';
+import type { Disposition } from './gate-resolution.js';
+import type { VerifyFailClass } from './verify-work.js';
+/** The part of a {@link FixContext} worth keeping after the run that used it. */
+export interface HandoffFixSummary {
+    /** The rule of the decision table that sent the work back. */
+    rule: Disposition['rule'];
+    failClass?: VerifyFailClass;
+    /** Which re-run the fix context itself was built for, 1-based. */
+    fixAttempt: number;
+    /** Probe names that found something; the findings live in the gate trail. */
+    probes: string[];
+    frozenPath?: string;
+}
+export interface HandoffRecord {
+    /** Which delivery of this task's spec this is, 1-based. */
+    attempt: number;
+    specHash: string;
+    delivered: 'fresh' | 'reattempt';
+    fixContext?: HandoffFixSummary;
+    at?: string;
+}
+/** Short content hash of the spec as delivered. */
+export declare function specHash(spec: string): string;
+export declare function summariseFixContext(ctx: FixContext): HandoffFixSummary;
+export declare function formatHandoff(r: HandoffRecord): string;
+/**
+ * Every record in a `## handoff` body, oldest first. A block without the
+ * `attempt` field is one of the single-timestamp sections this grammar replaced:
+ * it is still a delivery, so it is returned as attempt 1 with an unknown hash
+ * rather than dropped, and the next append counts from it.
+ */
+export declare function parseHandoff(body: string | null): HandoffRecord[];
+/** The section body with `record` appended after everything already in `prev`. */
+export declare function appendHandoff(prev: string | null, record: HandoffRecord): string;

package/dist/task/handoff.js

@@ -0,0 +1,100 @@
+/**
+ * handoff — what was delivered to the implementer, per attempt.
+ *
+ * The `## handoff` section used to be one `handoff_at:` timestamp, overwritten on
+ * every re-entry, which answered neither of the questions asked of it after a run:
+ * how many times was this task's spec delivered, and was the spec that came back
+ * the same one that failed? A record per delivery answers both — the spec hash
+ * makes a re-delivery that silently changed the spec visible, and the fix summary
+ * says which gate decision paid for it.
+ *
+ * Key-value lines because this section is read by humans as often as by code, and
+ * a blank line between records is the only separator the grammar needs.
+ */
+import { createHash } from 'node:crypto';
+/** Short content hash of the spec as delivered. */
+export function specHash(spec) {
+    return createHash('sha256').update(spec).digest('hex').slice(0, 12);
+}
+export function summariseFixContext(ctx) {
+    const probes = Object.entries(ctx.probes)
+        .filter(([, findings]) => Array.isArray(findings) && findings.length > 0)
+        .map(([name]) => name);
+    return {
+        rule: ctx.disposition.rule,
+        ...(ctx.outcome.failClass ? { failClass: ctx.outcome.failClass } : {}),
+        fixAttempt: ctx.attempt,
+        probes,
+        ...(ctx.contradiction ? { frozenPath: ctx.contradiction.frozenPath } : {})
+    };
+}
+const FIELD_RE = /^([a-z_]+):\s*(.*)$/;
+export function formatHandoff(r) {
+    const lines = [
+        `handoff_at: ${r.at ?? new Date().toISOString()}`,
+        `attempt: ${r.attempt}`,
+        `spec_hash: ${r.specHash}`,
+        `delivered: ${r.delivered}`
+    ];
+    const f = r.fixContext;
+    if (f) {
+        lines.push(`fix_rule: ${f.rule}`);
+        if (f.failClass)
+            lines.push(`fix_class: ${f.failClass}`);
+        lines.push(`fix_attempt: ${f.fixAttempt}`);
+        if (f.probes.length > 0)
+            lines.push(`fix_probes: ${f.probes.join(', ')}`);
+        if (f.frozenPath)
+            lines.push(`fix_frozen_path: ${f.frozenPath}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Every record in a `## handoff` body, oldest first. A block without the
+ * `attempt` field is one of the single-timestamp sections this grammar replaced:
+ * it is still a delivery, so it is returned as attempt 1 with an unknown hash
+ * rather than dropped, and the next append counts from it.
+ */
+export function parseHandoff(body) {
+    const out = [];
+    for (const block of (body ?? '').split(/\n\s*\n/)) {
+        const fields = new Map();
+        for (const line of block.split('\n')) {
+            const m = FIELD_RE.exec(line.trim());
+            if (m)
+                fields.set(m[1], m[2].trim());
+        }
+        if (fields.size === 0)
+            continue;
+        const attempt = parseInt(fields.get('attempt') ?? '', 10);
+        const delivered = fields.get('delivered');
+        const rule = fields.get('fix_rule');
+        const probes = fields.get('fix_probes');
+        const failClass = fields.get('fix_class');
+        const frozenPath = fields.get('fix_frozen_path');
+        out.push({
+            attempt: Number.isNaN(attempt) ? out.length + 1 : attempt,
+            specHash: fields.get('spec_hash') ?? '',
+            delivered: delivered === 'reattempt' ? 'reattempt' : 'fresh',
+            ...(fields.has('handoff_at') ? { at: fields.get('handoff_at') } : {}),
+            ...(rule ?
+                {
+                    fixContext: {
+                        rule: rule,
+                        ...(failClass ? { failClass: failClass } : {}),
+                        fixAttempt: parseInt(fields.get('fix_attempt') ?? '1', 10) || 1,
+                        probes: probes ? probes.split(',').map(p => p.trim()) : [],
+                        ...(frozenPath ? { frozenPath } : {})
+                    }
+                }
+                : {})
+        });
+    }
+    return out;
+}
+/** The section body with `record` appended after everything already in `prev`. */
+export function appendHandoff(prev, record) {
+    const before = (prev ?? '').trim();
+    const line = formatHandoff(record);
+    return before.length === 0 ? line : `${before}\n\n${line}`;
+}

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

@@ -0,0 +1,87 @@
+import type { GitRunner } from '../shared/git-runner.js';
+import type { HealthCommandResult, HealthOutcome } from './repo-health-check.js';
+/**
+ * The permissive read of a health result: everything the differential needs and
+ * nothing else. The gate deps hand around structurally-typed health signals (and
+ * tests fake them), so the differential asks for the two fields it reads rather
+ * than for the full `HealthOutcome`.
+ */
+export interface HealthSignal {
+    ok: boolean;
+    /** Absent → the result predates per-command recording; the differential then
+     *  has only the overall verdict to compare. */
+    commands?: readonly HealthCommandResult[];
+}
+export interface HealthBaseline {
+    /** When the baseline was taken (ISO). */
+    at: string;
+    /** The tree it describes, so a reader can tell whether it still applies. */
+    treeHash: string | null;
+    outcome: HealthOutcome;
+}
+/**
+ * Whose fault the current health result is.
+ *   clean        — nothing is failing now.
+ *   regressed    — a check fails that the baseline did not have failing. THIS task.
+ *   pre-existing — every failing check failed the same way before the task ran.
+ */
+export type HealthDelta = 'clean' | 'regressed' | 'pre-existing';
+/**
+ * Classify the current health result against the baseline.
+ *
+ * A NULL baseline is `regressed`, deliberately. An unestablished baseline is not
+ * evidence that the breakage predates the task — it is the absence of evidence —
+ * and the two errors are not symmetrical: calling it pre-existing SHIPS a real
+ * regression as inherited debt, while calling it a regression routes the failure
+ * through the resolution table, where a judge, a bounded lint fix or a human can
+ * still say otherwise. The same reasoning retires the `healthBefore?.ok ?? true`
+ * default the enforce site used to carry.
+ */
+export declare function classifyHealthDelta(baseline: HealthSignal | null, after: HealthSignal): HealthDelta;
+/** The failing commands, as prompt/trail lines naming the exit code. */
+export declare function inheritedHealthFindings(after: HealthSignal): string[];
+export declare const HEALTH_BASELINE_SECTION = "health baseline";
+/**
+ * Render for `## health baseline`. JSON in a fence rather than a hand-rolled
+ * grammar: this round-trips through a committed file that a later run parses, and
+ * a second grammar is a second thing to drift.
+ *
+ * The captured `output` is dropped — up to 40 lines of a linter's report, in a
+ * file committed with every task, for a field the differential never reads. The
+ * live run's own trail already carries it.
+ */
+export declare function formatHealthBaseline(b: HealthBaseline): string;
+/** Parse a `## health baseline` section back. Null on anything unreadable — an
+ *  unparseable baseline is no baseline, never a fabricated clean one. */
+export declare function parseHealthBaseline(section: string | null): HealthBaseline | null;
+export interface CaptureDeps {
+    runHealth: () => Promise<HealthOutcome>;
+    treeHash: () => Promise<string | null>;
+    /** Undo whatever a `--fix`-style health command wrote. */
+    discardEdits: () => Promise<void>;
+    now?: () => Date;
+}
+/**
+ * Capture the baseline for the tree as it stands. The hash is taken FIRST: a
+ * health command that writes would otherwise be described by the hash of its own
+ * output rather than of the tree the task starts from.
+ */
+export declare function captureHealthBaseline(deps: CaptureDeps): Promise<HealthBaseline>;
+export interface LazyCaptureDeps {
+    git: GitRunner;
+    /** Run the health check in the given directory — the throwaway worktree. */
+    runHealthIn: (dir: string) => Promise<HealthOutcome>;
+    tmpDir?: () => string;
+    now?: () => Date;
+}
+/**
+ * Establish a baseline for a task file that has none, from a DETACHED WORKTREE at
+ * HEAD. HEAD is the last commit before the task's uncommitted work, so it is the
+ * state the task started from — and checking it out elsewhere means the real index,
+ * the real working tree and the stash are all untouched, which no `stash` or
+ * `checkout` of the live tree could promise.
+ *
+ * Null when git cannot produce the worktree; the caller then has no baseline, and
+ * `classifyHealthDelta` says what that means.
+ */
+export declare function lazyHealthBaseline(deps: LazyCaptureDeps): Promise<HealthBaseline | null>;

package/dist/task/health-baseline.js

@@ -0,0 +1,158 @@
+/**
+ * health-baseline — what the repo's own static checks said BEFORE the task ran,
+ * and the differential that decides whose fault a red check is.
+ *
+ * THE FAILURE THIS CLOSES. The verify gate ran `runRepoHealthCheck` and failed on
+ * its absolute exit code. So a task that inherited a repo whose lint was already
+ * red failed its gate for somebody else's defect (AUTO_0002: 0034 absorbed 0033's
+ * lint debt), and — worse — that FAIL short-circuited before the probes, so the
+ * deterministic findings about the task's OWN work were never computed at all.
+ *
+ * THE COMPARISON IS PER COMMAND, not per overall verdict. `ok` is one boolean over
+ * a list of checks that short-circuits on the first failure, so "red before, red
+ * after" is true of a repo whose lint was already broken AND of a task that broke
+ * typecheck on top of it. Only the (cmd, exitCode) pairs can tell those apart.
+ *
+ * WHERE THE BASELINE COMES FROM. `/task-auto` captures it at the pre-task
+ * checkpoint commit, where the tree is clean and therefore describes exactly the
+ * state the task starts from; `/task` captures at its own start. Health commands
+ * may WRITE (`--fix` is a common `lint` script), so the capture discards edits
+ * afterwards — a baseline that silently fixed the repo would make the task's gate
+ * judge a tree nobody authored. A task file that has no baseline (it predates this,
+ * or the capture failed) gets one lazily at verify time from a detached worktree at
+ * HEAD: no stash, and the real index is never touched.
+ */
+import * as fsp from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { commitTreeHash } from './tree-hash.js';
+function failures(signal) {
+    return (signal.commands ?? []).filter(c => c.outcome === 'fail');
+}
+/**
+ * Classify the current health result against the baseline.
+ *
+ * A NULL baseline is `regressed`, deliberately. An unestablished baseline is not
+ * evidence that the breakage predates the task — it is the absence of evidence —
+ * and the two errors are not symmetrical: calling it pre-existing SHIPS a real
+ * regression as inherited debt, while calling it a regression routes the failure
+ * through the resolution table, where a judge, a bounded lint fix or a human can
+ * still say otherwise. The same reasoning retires the `healthBefore?.ok ?? true`
+ * default the enforce site used to carry.
+ */
+export function classifyHealthDelta(baseline, after) {
+    if (after.ok)
+        return 'clean';
+    if (!baseline)
+        return 'regressed';
+    const before = failures(baseline);
+    const now = failures(after);
+    // A failing result that names no failing command carries no per-command detail
+    // (a legacy record, or an injected signal); the overall verdict is all there is.
+    const detailed = now.length > 0 && (baseline.ok || before.length > 0);
+    if (!detailed)
+        return baseline.ok ? 'regressed' : 'pre-existing';
+    const key = (c) => JSON.stringify([c.cmd, c.exitCode]);
+    const wasFailing = new Set(before.map(key));
+    return now.every(c => wasFailing.has(key(c))) ? 'pre-existing' : 'regressed';
+}
+/** The failing commands, as prompt/trail lines naming the exit code. */
+export function inheritedHealthFindings(after) {
+    return failures(after).map(c => `\`${c.cmd}\` exits ${c.exitCode} (and did before this task)`);
+}
+// ─── The task-file section ───────────────────────────────────────────────────
+export const HEALTH_BASELINE_SECTION = 'health baseline';
+/**
+ * Render for `## health baseline`. JSON in a fence rather than a hand-rolled
+ * grammar: this round-trips through a committed file that a later run parses, and
+ * a second grammar is a second thing to drift.
+ *
+ * The captured `output` is dropped — up to 40 lines of a linter's report, in a
+ * file committed with every task, for a field the differential never reads. The
+ * live run's own trail already carries it.
+ */
+export function formatHealthBaseline(b) {
+    const { output: _output, ...outcome } = b.outcome;
+    return ['```json', JSON.stringify({ ...b, outcome }, null, 2), '```'].join('\n');
+}
+/** Parse a `## health baseline` section back. Null on anything unreadable — an
+ *  unparseable baseline is no baseline, never a fabricated clean one. */
+export function parseHealthBaseline(section) {
+    if (!section)
+        return null;
+    const json = section.replace(/^```(?:json)?\s*/, '').replace(/```\s*$/, '');
+    try {
+        const parsed = JSON.parse(json);
+        const outcome = parsed.outcome;
+        if (!outcome || typeof outcome.ok !== 'boolean')
+            return null;
+        return {
+            at: typeof parsed.at === 'string' ? parsed.at : '',
+            treeHash: typeof parsed.treeHash === 'string' ? parsed.treeHash : null,
+            outcome: {
+                ok: outcome.ok,
+                reason: outcome.reason ?? '',
+                ecosystem: outcome.ecosystem ?? null,
+                commands: outcome.commands ?? [],
+                output: ''
+            }
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Capture the baseline for the tree as it stands. The hash is taken FIRST: a
+ * health command that writes would otherwise be described by the hash of its own
+ * output rather than of the tree the task starts from.
+ */
+export async function captureHealthBaseline(deps) {
+    const treeHash = await deps.treeHash();
+    try {
+        const outcome = await deps.runHealth();
+        return { at: (deps.now?.() ?? new Date()).toISOString(), treeHash, outcome };
+    }
+    finally {
+        await deps.discardEdits();
+    }
+}
+function lazyWorktreePath() {
+    return path.join(os.tmpdir(), `pi-task-health-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+}
+/**
+ * Establish a baseline for a task file that has none, from a DETACHED WORKTREE at
+ * HEAD. HEAD is the last commit before the task's uncommitted work, so it is the
+ * state the task started from — and checking it out elsewhere means the real index,
+ * the real working tree and the stash are all untouched, which no `stash` or
+ * `checkout` of the live tree could promise.
+ *
+ * Null when git cannot produce the worktree; the caller then has no baseline, and
+ * `classifyHealthDelta` says what that means.
+ */
+export async function lazyHealthBaseline(deps) {
+    const dir = (deps.tmpDir ?? lazyWorktreePath)();
+    const added = await deps.git(['worktree', 'add', '--detach', dir, 'HEAD']);
+    if (added.exitCode !== 0)
+        return null;
+    try {
+        const outcome = await deps.runHealthIn(dir);
+        return {
+            at: (deps.now?.() ?? new Date()).toISOString(),
+            treeHash: await commitTreeHash(deps.git, 'HEAD'),
+            outcome
+        };
+    }
+    finally {
+        // `--force` because the health run may have written into it (a `--fix`
+        // script, a build cache), which plain `worktree remove` refuses. If git
+        // still declines, drop the directory and prune the admin record by hand —
+        // a stale worktree entry makes every later `worktree add` in this repo
+        // noisier, and nothing else will clean it up.
+        const removed = await deps.git(['worktree', 'remove', '--force', dir]);
+        if (removed.exitCode !== 0) {
+            await fsp.rm(dir, { recursive: true, force: true }).catch(() => { });
+            await deps.git(['worktree', 'prune']);
+        }
+    }
+}

package/dist/task/ledger.d.ts

@@ -22,6 +22,16 @@ export interface LedgerSpec<T> {
      * writer produces, so it is an option, not a unification.
      */
     onNoop?: 'rewrite' | 'skip';
+    /**
+     * What `append` does when an incoming record's key is already stored:
+     *   'keep-first' (default) — the stored record wins, so provenance traces to
+     *     whoever established it first;
+     *   'replace' — the incoming record wins and moves to the end of the file, so
+     *     the freshest statement of a fact is the one that survives the cap.
+     * env-notes is the second kind: a re-measured environment fact SUPERSEDES the
+     * earlier one, and keeping the first is how a stale fact becomes permanent.
+     */
+    conflict?: 'keep-first' | 'replace';
 }
 export interface Ledger<T> {
     /** Absolute path of the ledger file for this cwd. */

package/dist/task/ledger.js

@@ -4,11 +4,11 @@
  * requirements, requirements-owned).
  *
  * The ritual is seven steps: read the file (ANY error → ''), parse it into records,
- * key the records, drop an incoming item whose key is already present, cap to the
- * newest MAX (oldest dropped), mkdir the tasks dir, write the whole file back
- * (`lines.join('\n') + '\n'`, plain `writeFile`, NOT atomic). Every fault is
- * swallowed — a ledger is a sharpener or an auditing aid, never a blocker of the
- * phase or gate that calls it.
+ * key the records, settle an incoming item whose key is already present (see
+ * `conflict`), cap to the newest MAX (oldest dropped), mkdir the tasks dir, write
+ * the whole file back (`lines.join('\n') + '\n'`, plain `writeFile`, NOT atomic).
+ * Every fault is swallowed — a ledger is a sharpener or an auditing aid, never a
+ * blocker of the phase or gate that calls it.
  *
  * What varies per site is the DATA SHAPE (file name, cap, key, line format, parser)
  * and exactly one RULE — what an append does when it adds nothing new (see
@@ -21,8 +21,9 @@
  *   • `read` is `parse(readRaw)`; every adapter's parser skips blank lines and lines
  *     it cannot read, so a corrupt line is dropped, never thrown on.
  *   • `append` with an empty batch is a no-op — it does not even create `.pi-tasks/`.
- *     Within a batch the first item with a key wins; a key already stored wins over
- *     the batch.
+ *     Under the default `conflict` the first item with a key wins within a batch,
+ *     and a key already stored wins over the batch; under `'replace'` the last
+ *     statement of a key wins and moves to the end.
  *   • `write` overwrites with exactly these records; an empty list writes an empty
  *     file (this is how a drained queue and a fully-resolved debt ledger look).
  *   • Neither `append` nor `write` ever throws.
@@ -33,6 +34,7 @@ import { tasksDir } from './task-io.js';
 export function makeLedger(spec) {
     const { file, max, key, serialize, parse } = spec;
     const onNoop = spec.onNoop ?? 'rewrite';
+    const conflict = spec.conflict ?? 'keep-first';
     const filePath = (cwd) => path.join(tasksDir(cwd), file);
     async function readRaw(cwd) {
         try {
@@ -57,14 +59,23 @@ export function makeLedger(spec) {
             const existing = await read(cwd);
             const seen = new Set(existing.map(key));
             const merged = [...existing];
+            let added = 0;
             for (const item of items) {
                 const k = key(item);
-                if (seen.has(k))
-                    continue;
-                seen.add(k);
+                if (seen.has(k)) {
+                    if (conflict === 'keep-first')
+                        continue;
+                    const at = merged.findIndex(m => key(m) === k);
+                    if (at !== -1)
+                        merged.splice(at, 1);
+                }
+                else {
+                    seen.add(k);
+                    added++;
+                }
                 merged.push(item);
             }
-            if (merged.length === existing.length && onNoop === 'skip')
+            if (added === 0 && onNoop === 'skip')
                 return;
             const kept = max === undefined ? merged : merged.slice(-max);
             await persist(cwd, kept);

package/dist/task/lint-fix.d.ts

@@ -1,8 +1,19 @@
+import type { SpecContradiction } from './gate-resolution.js';
 export interface LintFixResult {
     /** true → findings fixed, repo health passes, work preserved. */
     ok: boolean;
+    /**
+     * WHAT this pass proved, as data. `frozen-path` used to travel as a
+     * `frozen-path:` prefix on `reason`, which the gate loop recovered by
+     * re-typing the literal — a reword of either side silently disarmed the
+     * cross-task-contradiction routing.
+     */
+    class: 'converged' | 'frozen-path' | 'not-applied';
     /** why the fix was not applied (guard trip, no convergence, child error). */
     reason?: string;
+    /** Set exactly on `frozen-path`: the criterion and the frozen path whose edit
+     *  is the only way to meet it, for the gate's decision table. */
+    contradiction?: SpecContradiction;
 }
 export interface LintFixDeps {
     cwd: string;