@webpieces/rules-config 0.4.497 → 0.4.499

package/src/worktree-reaper.js

@@ -0,0 +1,305 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorktreeReaper = exports.WorktreeReapResult = exports.ReapedWorktree = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const path = tslib_1.__importStar(require("path"));
+const inversify_1 = require("inversify");
+const branch_archiver_1 = require("./branch-archiver");
+const branch_mutation_log_1 = require("./branch-mutation-log");
+const merged_branches_1 = require("./merged-branches");
+const worktrees_1 = require("./worktrees");
+/**
+ * The EXECUTOR for the dead-WORKTREE verdicts that merged-branches.ts has been computing all along.
+ *
+ * WHY this exists: `DeletableWorktree` was designed for reaping — it carries `path` (what
+ * `git worktree remove` takes) AND `branch` (what `git branch -D` takes afterwards) precisely because
+ * a reap is always those two steps in that order. The reaping was then never wired up. The verdicts
+ * had exactly one consumer, branch-creation-guard, which used them only to BLOCK: at the worktree cap
+ * it printed the reap commands and refused to create the next worktree. Nothing ever ran them.
+ *
+ * That composes into a deadlock, not merely a missing feature. A merged worktree HOLDS its branch, so
+ * the branch lands in `keep` with "checked out in worktree '<path>' — remove that worktree before
+ * deleting the branch". Nothing removes the worktree. Both accumulate forever, and the guard's only
+ * remaining advice is to loosen its own cap — which is the failure the cap exists to prevent. Observed
+ * twice in one day: a `wp-cleanup` run that spared three worktree-held branches with that exact line,
+ * and another that spared seven.
+ *
+ * THE ORDER IS FIXED AND LOAD-BEARING: archive the branch as a tag → `git worktree remove <path>` →
+ * `git branch -D <branch>`.
+ *  - Archive FIRST, and if it fails nothing is deleted. Same rule BranchArchiver already enforces for
+ *    branches: a branch we could not tag is a branch whose only copy would be the reflog.
+ *  - Remove the worktree BEFORE the branch, because git flatly refuses to delete a branch that is
+ *    still checked out somewhere.
+ *
+ * AND NEVER `--force`. Git refuses to remove a worktree with uncommitted changes or untracked files,
+ * and that refusal is the entire safety property here: a worktree removal deletes real FILES, not just
+ * a ref, and an untracked file is by definition something no archive tag captured. A failed removal is
+ * reported and moved past, exactly as a failed branch delete already is.
+ */
+// Data-only (per CLAUDE.md, classes for data). One worktree and what happened to it.
+class ReapedWorktree {
+    path;
+    // The branch the worktree held, '' when it was detached.
+    branch;
+    // The branch's tip BEFORE anything was destroyed. '' when it could not be resolved (or detached).
+    sha;
+    reason;
+    pr;
+    ok;
+    // git's own stderr when ok=false. Kept verbatim — a refused removal is a thing a human must read.
+    error;
+    // The `archive/<date>/<branch>` tag written before the removal, or '' (policy 'delete', or detached).
+    archiveTag = '';
+    /**
+     * Did the BRANCH delete also succeed? A worktree removal that succeeds while the branch delete
+     * fails is a real, reportable half-state — the directory is gone, the branch is still there — and
+     * collapsing it into `ok` would hide it. `ok` means the DIRECTORY is gone; this means the pair is.
+     */
+    branchDeleted = false;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(treePath, branch, sha, reason, pr, ok, error) {
+        this.path = treePath;
+        this.branch = branch;
+        this.sha = sha;
+        this.reason = reason;
+        this.pr = pr;
+        this.ok = ok;
+        this.error = error;
+    }
+}
+exports.ReapedWorktree = ReapedWorktree;
+/**
+ * The outcome of one worktree reap. `spared` carries the worktrees we refused to touch, each with its
+ * reason, for the same reason ReapResult does: a cleanup silent about what it did NOT remove reads as
+ * "there was nothing else", when those are exactly the ones only a human can rule on.
+ */
+class WorktreeReapResult {
+    reaped;
+    failed;
+    spared;
+    constructor(reaped, failed, spared) {
+        this.reaped = reaped;
+        this.failed = failed;
+        this.spared = spared;
+    }
+}
+exports.WorktreeReapResult = WorktreeReapResult;
+// The two never-removable sets, kept apart so each refusal can name its own reason (data-only class
+// per CLAUDE.md — `primary` is the clone that owns .git, `current` is the tree wp-cleanup runs in).
+class ProtectedPaths {
+    primary;
+    current;
+    constructor(primary, current) {
+        this.primary = primary;
+        this.current = current;
+    }
+}
+let WorktreeReaper = class WorktreeReaper {
+    worktrees;
+    mutationLog;
+    archiver;
+    // Defaulted like BranchReaper's collaborators, so the non-DI call sites can just
+    // `new WorktreeReaper()` while inversify still injects the singletons from a container.
+    constructor(worktrees = new worktrees_1.WorktreeService(), mutationLog = new branch_mutation_log_1.BranchMutationLog(), archiver = new branch_archiver_1.BranchArchiver()) {
+        this.worktrees = worktrees;
+        this.mutationLog = mutationLog;
+        this.archiver = archiver;
+    }
+    /**
+     * Reap every worktree in `targets`, skipping any the safety rails refuse.
+     *
+     * `cwd` is passed in rather than read from `process.cwd()` here so the "never remove the tree I am
+     * standing in" rule is testable and so a caller running from a subdirectory still gets the right
+     * answer — the containing WORKTREE is what matters, not the exact directory.
+     *
+     * `targets` is caller-chosen on purpose. wp-cleanup passes the provably-dead ones unattended, and
+     * passes human-approved probably-dead ones on a second call. The safety rails below apply to both:
+     * no answer at a prompt can authorise removing your own cwd or the primary clone.
+     */
+    // eslint-disable-next-line @typescript-eslint/max-params
+    reapWorktrees(repoRoot, cwd, verb, targets, retention = branch_archiver_1.BRANCH_RETENTION_ARCHIVE_TAG) {
+        // 'keep' means "delete nothing, ever" — the reap degrades to a pure report, exactly as it does
+        // for branches, so a repo that opted out of destructive cleanup still SEES what would have gone.
+        if (retention === branch_archiver_1.BRANCH_RETENTION_KEEP)
+            return new WorktreeReapResult([], [], targets);
+        const protectedPaths = this.protectedPaths(repoRoot, cwd);
+        const reaped = [];
+        const failed = [];
+        const spared = [];
+        for (const target of targets) {
+            const refusal = this.refuseReason(target, protectedPaths);
+            if (refusal !== '') {
+                spared.push(new merged_branches_1.DeletableWorktree(target.path, target.branch, refusal, target.pr, false, target.classification));
+                continue;
+            }
+            const outcome = this.removeOne(repoRoot, verb, target, retention);
+            if (outcome.ok)
+                reaped.push(outcome);
+            else
+                failed.push(outcome);
+        }
+        return new WorktreeReapResult(reaped, failed, spared);
+    }
+    /**
+     * The two directories that must never be removed, resolved to absolute paths so a relative
+     * `../foo` in a verdict can still be compared against them.
+     *
+     *  - THE PRIMARY CLONE. It owns `.git`; `git worktree remove` cannot take it, and a caller who
+     *    somehow got it into a target list has a bug we must not execute.
+     *  - THE TREE WE ARE STANDING IN. Removing your own cwd mid-command deletes the files underneath
+     *    the running process — including, when the tooling is invoked by an agent, the checkout the
+     *    agent's next tool call will try to read. merged-branches.ts already declines to mark it
+     *    deletable; this is the second, independent line, because the caller supplies the list.
+     */
+    protectedPaths(repoRoot, cwd) {
+        const primary = new Set();
+        for (const tree of this.worktrees.listWorktrees(repoRoot)) {
+            if (tree.isMain)
+                primary.add(path.resolve(tree.path));
+        }
+        const here = new Set();
+        const current = this.currentTree(repoRoot, cwd);
+        if (current !== null)
+            here.add(path.resolve(current.path));
+        // Fail SAFE when git could not name the current worktree: protect the raw paths anyway. An
+        // over-protected path costs one worktree that survives to the next cleanup; an under-protected
+        // one costs the directory the command is running in.
+        here.add(path.resolve(repoRoot));
+        here.add(path.resolve(cwd));
+        return new ProtectedPaths(primary, here);
+    }
+    // The worktree record CONTAINING cwd — not merely the one whose path equals it, so `wp-cleanup`
+    // run from `packages/whatever` inside a worktree still protects that worktree.
+    currentTree(repoRoot, cwd) {
+        const here = path.resolve(cwd);
+        let best = null;
+        for (const tree of this.worktrees.listWorktrees(repoRoot)) {
+            const root = path.resolve(tree.path);
+            if (here !== root && !here.startsWith(root + path.sep))
+                continue;
+            // Longest match wins: worktrees can nest, and the innermost one is the one we are in.
+            if (best === null || root.length > path.resolve(best.path).length)
+                best = tree;
+        }
+        return best;
+    }
+    // '' when the target may be reaped; otherwise the human-readable reason it was spared instead. The
+    // two rails report SEPARATELY: "you are standing in it" and "that is the primary clone" are
+    // different mistakes, and a message covering both tells the reader neither.
+    refuseReason(target, protectedPaths) {
+        if (target.path === '')
+            return 'no path recorded for this worktree — nothing safe to remove';
+        const resolved = path.resolve(target.path);
+        if (protectedPaths.primary.has(resolved)) {
+            return 'refused — that is the primary clone, which owns .git and is not removable';
+        }
+        if (protectedPaths.current.has(resolved)) {
+            return 'refused — this command is running in that worktree; removing your own cwd is a self-destruct';
+        }
+        return '';
+    }
+    /**
+     * One worktree: ARCHIVE the branch, REMOVE the directory, then DELETE the branch — and stop at the
+     * first step that fails.
+     *
+     * The prunable case is genuinely different and is why the classification token rides along on the
+     * verdict: the directory is ALREADY gone, so `git worktree remove` fails on it and the reap is
+     * `git worktree prune`. There is also nothing to archive from a directory that no longer exists —
+     * the branch itself is still archived, since it may well still hold the only copy of some work.
+     */
+    removeOne(repoRoot, verb, target, retention) {
+        // Tip first: after the branch is gone there is nothing left to resolve, and the audit line's
+        // whole job is to record what was destroyed while it still exists.
+        const sha = target.branch !== '' ? this.revParse(repoRoot, target.branch) : '';
+        const archive = this.archiveBranch(repoRoot, target, retention, sha);
+        if (!archive.ok)
+            return this.archiveFailed(repoRoot, verb, target, sha, archive);
+        const removed = target.classification === merged_branches_1.CLASSIFICATION_PRUNABLE
+            ? this.capture(repoRoot, ['worktree', 'prune'])
+            : this.capture(repoRoot, ['worktree', 'remove', target.path]);
+        if (!removed.ok)
+            return this.removalFailed(repoRoot, verb, target, sha, archive, removed.err);
+        // Only NOW may the branch go: git refuses while a worktree still holds it.
+        const branchDeleted = target.branch === ''
+            || this.capture(repoRoot, ['branch', '-D', target.branch]).ok;
+        const result = new ReapedWorktree(target.path, target.branch, sha, target.reason, target.pr, true, '');
+        result.archiveTag = archive.tag;
+        result.branchDeleted = branchDeleted;
+        this.log(repoRoot, verb, target, sha, archive.tag, branchDeleted
+            ? `removed worktree and deleted branch (${target.reason})`
+            : `removed worktree; branch '${target.branch}' survived (git refused the delete)`);
+        return result;
+    }
+    // Archiving is skipped for a detached worktree (no branch to tag) and under retention 'delete'.
+    // Both report ok=true with an empty tag: there is nothing to archive, which is not a failure.
+    archiveBranch(repoRoot, target, retention, sha) {
+        if (target.branch === '' || retention !== branch_archiver_1.BRANCH_RETENTION_ARCHIVE_TAG) {
+            return new branch_archiver_1.ArchiveResult('', sha, true, '');
+        }
+        return this.archiver.archive(repoRoot, target.branch);
+    }
+    // Archive refused ⇒ NOTHING is removed. The directory survives to the next cleanup, which is the
+    // fail-safe direction: the alternative is deleting files whose branch has no permanent ref.
+    // eslint-disable-next-line @typescript-eslint/max-params
+    archiveFailed(repoRoot, verb, target, sha, archive) {
+        const error = `not removed — could not archive its branch first: ${archive.error}`;
+        this.log(repoRoot, verb, target, sha, '', `SKIPPED (${error})`);
+        return new ReapedWorktree(target.path, target.branch, sha, target.reason, target.pr, false, error);
+    }
+    /**
+     * git refused to remove the directory — nearly always because it holds uncommitted changes or
+     * untracked files. Reported with git's own words and moved past. We do NOT retry with `--force`:
+     * an untracked file is work no archive tag captured, and `--force` is how a cleanup command turns
+     * into a data-loss command. The branch is left alone too, since it is still checked out here.
+     */
+    // eslint-disable-next-line @typescript-eslint/max-params
+    removalFailed(repoRoot, verb, target, sha, archive, err) {
+        const error = `git refused to remove it: ${err} (not forced — untracked or modified files are `
+            + 'work nothing has archived; remove them or the worktree by hand)';
+        this.log(repoRoot, verb, target, sha, archive.tag, `FAILED (${err})`);
+        const result = new ReapedWorktree(target.path, target.branch, sha, target.reason, target.pr, false, error);
+        result.archiveTag = archive.tag;
+        return result;
+    }
+    // eslint-disable-next-line @typescript-eslint/max-params
+    log(repoRoot, verb, target, sha, archiveTag, outcome) {
+        const event = new branch_mutation_log_1.BranchMutationEvent(verb, 'REAP_WORKTREE');
+        event.fromBranch = target.branch;
+        event.sha = sha;
+        event.archiveTag = archiveTag;
+        event.worktreePath = target.path;
+        event.outcome = outcome;
+        this.mutationLog.logBranchMutation(repoRoot, event);
+    }
+    /** The literal command that puts BOTH the directory and the branch back. */
+    restoreCommand(target) {
+        const ref = target.archiveTag !== '' ? target.archiveTag : target.sha;
+        if (ref === '')
+            return `git worktree add ${target.path} <ref>`;
+        if (target.branch === '')
+            return `git worktree add ${target.path} ${ref}`;
+        return `git worktree add -b ${target.branch} ${target.path} ${ref}`;
+    }
+    revParse(repoRoot, ref) {
+        const result = this.capture(repoRoot, ['rev-parse', ref]);
+        return result.ok ? result.out : '';
+    }
+    // Run a git command capturing trimmed stdout/stderr; ok=false on spawn failure or non-zero exit.
+    capture(repoRoot, args) {
+        const result = (0, child_process_1.spawnSync)('git', args, { cwd: repoRoot, encoding: 'utf8' });
+        const err = typeof result.stderr === 'string' ? result.stderr.trim() : '';
+        if (result.status !== 0 || typeof result.stdout !== 'string') {
+            return { ok: false, out: '', err: err !== '' ? err : 'git command failed' };
+        }
+        return { ok: true, out: result.stdout.trim(), err };
+    }
+};
+exports.WorktreeReaper = WorktreeReaper;
+exports.WorktreeReaper = WorktreeReaper = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [worktrees_1.WorktreeService,
+        branch_mutation_log_1.BranchMutationLog,
+        branch_archiver_1.BranchArchiver])
+], WorktreeReaper);
+//# sourceMappingURL=worktree-reaper.js.map

package/src/worktree-reaper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-reaper.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/worktree-reaper.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport {\n    ArchiveResult,\n    BranchArchiver,\n    BRANCH_RETENTION_ARCHIVE_TAG,\n    BRANCH_RETENTION_KEEP,\n} from './branch-archiver';\nimport { BranchMutationEvent, BranchMutationLog, MutationVerb } from './branch-mutation-log';\nimport { CLASSIFICATION_PRUNABLE, DeletableWorktree } from './merged-branches';\nimport { Worktree, WorktreeService } from './worktrees';\n\n/**\n * The EXECUTOR for the dead-WORKTREE verdicts that merged-branches.ts has been computing all along.\n *\n * WHY this exists: `DeletableWorktree` was designed for reaping — it carries `path` (what\n * `git worktree remove` takes) AND `branch` (what `git branch -D` takes afterwards) precisely because\n * a reap is always those two steps in that order. The reaping was then never wired up. The verdicts\n * had exactly one consumer, branch-creation-guard, which used them only to BLOCK: at the worktree cap\n * it printed the reap commands and refused to create the next worktree. Nothing ever ran them.\n *\n * That composes into a deadlock, not merely a missing feature. A merged worktree HOLDS its branch, so\n * the branch lands in `keep` with \"checked out in worktree '<path>' — remove that worktree before\n * deleting the branch\". Nothing removes the worktree. Both accumulate forever, and the guard's only\n * remaining advice is to loosen its own cap — which is the failure the cap exists to prevent. Observed\n * twice in one day: a `wp-cleanup` run that spared three worktree-held branches with that exact line,\n * and another that spared seven.\n *\n * THE ORDER IS FIXED AND LOAD-BEARING: archive the branch as a tag → `git worktree remove <path>` →\n * `git branch -D <branch>`.\n *  - Archive FIRST, and if it fails nothing is deleted. Same rule BranchArchiver already enforces for\n *    branches: a branch we could not tag is a branch whose only copy would be the reflog.\n *  - Remove the worktree BEFORE the branch, because git flatly refuses to delete a branch that is\n *    still checked out somewhere.\n *\n * AND NEVER `--force`. Git refuses to remove a worktree with uncommitted changes or untracked files,\n * and that refusal is the entire safety property here: a worktree removal deletes real FILES, not just\n * a ref, and an untracked file is by definition something no archive tag captured. A failed removal is\n * reported and moved past, exactly as a failed branch delete already is.\n */\n\n// Data-only (per CLAUDE.md, classes for data). One worktree and what happened to it.\nexport class ReapedWorktree {\n    path: string;\n    // The branch the worktree held, '' when it was detached.\n    branch: string;\n    // The branch's tip BEFORE anything was destroyed. '' when it could not be resolved (or detached).\n    sha: string;\n    reason: string;\n    pr: number;\n    ok: boolean;\n    // git's own stderr when ok=false. Kept verbatim — a refused removal is a thing a human must read.\n    error: string;\n    // The `archive/<date>/<branch>` tag written before the removal, or '' (policy 'delete', or detached).\n    archiveTag: string = '';\n    /**\n     * Did the BRANCH delete also succeed? A worktree removal that succeeds while the branch delete\n     * fails is a real, reportable half-state — the directory is gone, the branch is still there — and\n     * collapsing it into `ok` would hide it. `ok` means the DIRECTORY is gone; this means the pair is.\n     */\n    branchDeleted: boolean = false;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(treePath: string, branch: string, sha: string, reason: string, pr: number, ok: boolean, error: string) {\n        this.path = treePath;\n        this.branch = branch;\n        this.sha = sha;\n        this.reason = reason;\n        this.pr = pr;\n        this.ok = ok;\n        this.error = error;\n    }\n}\n\n/**\n * The outcome of one worktree reap. `spared` carries the worktrees we refused to touch, each with its\n * reason, for the same reason ReapResult does: a cleanup silent about what it did NOT remove reads as\n * \"there was nothing else\", when those are exactly the ones only a human can rule on.\n */\nexport class WorktreeReapResult {\n    reaped: ReapedWorktree[];\n    failed: ReapedWorktree[];\n    spared: DeletableWorktree[];\n\n    constructor(reaped: ReapedWorktree[], failed: ReapedWorktree[], spared: DeletableWorktree[]) {\n        this.reaped = reaped;\n        this.failed = failed;\n        this.spared = spared;\n    }\n}\n\n// The two never-removable sets, kept apart so each refusal can name its own reason (data-only class\n// per CLAUDE.md — `primary` is the clone that owns .git, `current` is the tree wp-cleanup runs in).\nclass ProtectedPaths {\n    primary: Set<string>;\n    current: Set<string>;\n\n    constructor(primary: Set<string>, current: Set<string>) {\n        this.primary = primary;\n        this.current = current;\n    }\n}\n\n// Result of a captured git invocation. `err` carries stderr so a refused removal can be reported.\ninterface CmdCapture {\n    ok: boolean;\n    out: string;\n    err: string;\n}\n\n@injectable(bindingScopeValues.Singleton)\nexport class WorktreeReaper {\n    // Defaulted like BranchReaper's collaborators, so the non-DI call sites can just\n    // `new WorktreeReaper()` while inversify still injects the singletons from a container.\n    constructor(\n        private readonly worktrees: WorktreeService = new WorktreeService(),\n        private readonly mutationLog: BranchMutationLog = new BranchMutationLog(),\n        private readonly archiver: BranchArchiver = new BranchArchiver(),\n    ) {}\n\n    /**\n     * Reap every worktree in `targets`, skipping any the safety rails refuse.\n     *\n     * `cwd` is passed in rather than read from `process.cwd()` here so the \"never remove the tree I am\n     * standing in\" rule is testable and so a caller running from a subdirectory still gets the right\n     * answer — the containing WORKTREE is what matters, not the exact directory.\n     *\n     * `targets` is caller-chosen on purpose. wp-cleanup passes the provably-dead ones unattended, and\n     * passes human-approved probably-dead ones on a second call. The safety rails below apply to both:\n     * no answer at a prompt can authorise removing your own cwd or the primary clone.\n     */\n    // eslint-disable-next-line @typescript-eslint/max-params\n    reapWorktrees(\n        repoRoot: string,\n        cwd: string,\n        verb: MutationVerb,\n        targets: DeletableWorktree[],\n        retention: string = BRANCH_RETENTION_ARCHIVE_TAG,\n    ): WorktreeReapResult {\n        // 'keep' means \"delete nothing, ever\" — the reap degrades to a pure report, exactly as it does\n        // for branches, so a repo that opted out of destructive cleanup still SEES what would have gone.\n        if (retention === BRANCH_RETENTION_KEEP) return new WorktreeReapResult([], [], targets);\n\n        const protectedPaths = this.protectedPaths(repoRoot, cwd);\n        const reaped: ReapedWorktree[] = [];\n        const failed: ReapedWorktree[] = [];\n        const spared: DeletableWorktree[] = [];\n\n        for (const target of targets) {\n            const refusal = this.refuseReason(target, protectedPaths);\n            if (refusal !== '') {\n                spared.push(new DeletableWorktree(\n                    target.path, target.branch, refusal, target.pr, false, target.classification));\n                continue;\n            }\n            const outcome = this.removeOne(repoRoot, verb, target, retention);\n            if (outcome.ok) reaped.push(outcome);\n            else failed.push(outcome);\n        }\n\n        return new WorktreeReapResult(reaped, failed, spared);\n    }\n\n    /**\n     * The two directories that must never be removed, resolved to absolute paths so a relative\n     * `../foo` in a verdict can still be compared against them.\n     *\n     *  - THE PRIMARY CLONE. It owns `.git`; `git worktree remove` cannot take it, and a caller who\n     *    somehow got it into a target list has a bug we must not execute.\n     *  - THE TREE WE ARE STANDING IN. Removing your own cwd mid-command deletes the files underneath\n     *    the running process — including, when the tooling is invoked by an agent, the checkout the\n     *    agent's next tool call will try to read. merged-branches.ts already declines to mark it\n     *    deletable; this is the second, independent line, because the caller supplies the list.\n     */\n    private protectedPaths(repoRoot: string, cwd: string): ProtectedPaths {\n        const primary = new Set<string>();\n        for (const tree of this.worktrees.listWorktrees(repoRoot)) {\n            if (tree.isMain) primary.add(path.resolve(tree.path));\n        }\n\n        const here = new Set<string>();\n        const current = this.currentTree(repoRoot, cwd);\n        if (current !== null) here.add(path.resolve(current.path));\n        // Fail SAFE when git could not name the current worktree: protect the raw paths anyway. An\n        // over-protected path costs one worktree that survives to the next cleanup; an under-protected\n        // one costs the directory the command is running in.\n        here.add(path.resolve(repoRoot));\n        here.add(path.resolve(cwd));\n        return new ProtectedPaths(primary, here);\n    }\n\n    // The worktree record CONTAINING cwd — not merely the one whose path equals it, so `wp-cleanup`\n    // run from `packages/whatever` inside a worktree still protects that worktree.\n    private currentTree(repoRoot: string, cwd: string): Worktree | null {\n        const here = path.resolve(cwd);\n        let best: Worktree | null = null;\n        for (const tree of this.worktrees.listWorktrees(repoRoot)) {\n            const root = path.resolve(tree.path);\n            if (here !== root && !here.startsWith(root + path.sep)) continue;\n            // Longest match wins: worktrees can nest, and the innermost one is the one we are in.\n            if (best === null || root.length > path.resolve(best.path).length) best = tree;\n        }\n        return best;\n    }\n\n    // '' when the target may be reaped; otherwise the human-readable reason it was spared instead. The\n    // two rails report SEPARATELY: \"you are standing in it\" and \"that is the primary clone\" are\n    // different mistakes, and a message covering both tells the reader neither.\n    private refuseReason(target: DeletableWorktree, protectedPaths: ProtectedPaths): string {\n        if (target.path === '') return 'no path recorded for this worktree — nothing safe to remove';\n        const resolved = path.resolve(target.path);\n        if (protectedPaths.primary.has(resolved)) {\n            return 'refused — that is the primary clone, which owns .git and is not removable';\n        }\n        if (protectedPaths.current.has(resolved)) {\n            return 'refused — this command is running in that worktree; removing your own cwd is a self-destruct';\n        }\n        return '';\n    }\n\n    /**\n     * One worktree: ARCHIVE the branch, REMOVE the directory, then DELETE the branch — and stop at the\n     * first step that fails.\n     *\n     * The prunable case is genuinely different and is why the classification token rides along on the\n     * verdict: the directory is ALREADY gone, so `git worktree remove` fails on it and the reap is\n     * `git worktree prune`. There is also nothing to archive from a directory that no longer exists —\n     * the branch itself is still archived, since it may well still hold the only copy of some work.\n     */\n    private removeOne(\n        repoRoot: string,\n        verb: MutationVerb,\n        target: DeletableWorktree,\n        retention: string,\n    ): ReapedWorktree {\n        // Tip first: after the branch is gone there is nothing left to resolve, and the audit line's\n        // whole job is to record what was destroyed while it still exists.\n        const sha = target.branch !== '' ? this.revParse(repoRoot, target.branch) : '';\n\n        const archive = this.archiveBranch(repoRoot, target, retention, sha);\n        if (!archive.ok) return this.archiveFailed(repoRoot, verb, target, sha, archive);\n\n        const removed = target.classification === CLASSIFICATION_PRUNABLE\n            ? this.capture(repoRoot, ['worktree', 'prune'])\n            : this.capture(repoRoot, ['worktree', 'remove', target.path]);\n        if (!removed.ok) return this.removalFailed(repoRoot, verb, target, sha, archive, removed.err);\n\n        // Only NOW may the branch go: git refuses while a worktree still holds it.\n        const branchDeleted = target.branch === ''\n            || this.capture(repoRoot, ['branch', '-D', target.branch]).ok;\n\n        const result = new ReapedWorktree(\n            target.path, target.branch, sha, target.reason, target.pr, true, '');\n        result.archiveTag = archive.tag;\n        result.branchDeleted = branchDeleted;\n\n        this.log(repoRoot, verb, target, sha, archive.tag, branchDeleted\n            ? `removed worktree and deleted branch (${target.reason})`\n            : `removed worktree; branch '${target.branch}' survived (git refused the delete)`);\n        return result;\n    }\n\n    // Archiving is skipped for a detached worktree (no branch to tag) and under retention 'delete'.\n    // Both report ok=true with an empty tag: there is nothing to archive, which is not a failure.\n    private archiveBranch(\n        repoRoot: string, target: DeletableWorktree, retention: string, sha: string,\n    ): ArchiveResult {\n        if (target.branch === '' || retention !== BRANCH_RETENTION_ARCHIVE_TAG) {\n            return new ArchiveResult('', sha, true, '');\n        }\n        return this.archiver.archive(repoRoot, target.branch);\n    }\n\n    // Archive refused ⇒ NOTHING is removed. The directory survives to the next cleanup, which is the\n    // fail-safe direction: the alternative is deleting files whose branch has no permanent ref.\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private archiveFailed(\n        repoRoot: string, verb: MutationVerb, target: DeletableWorktree, sha: string, archive: ArchiveResult,\n    ): ReapedWorktree {\n        const error = `not removed — could not archive its branch first: ${archive.error}`;\n        this.log(repoRoot, verb, target, sha, '', `SKIPPED (${error})`);\n        return new ReapedWorktree(target.path, target.branch, sha, target.reason, target.pr, false, error);\n    }\n\n    /**\n     * git refused to remove the directory — nearly always because it holds uncommitted changes or\n     * untracked files. Reported with git's own words and moved past. We do NOT retry with `--force`:\n     * an untracked file is work no archive tag captured, and `--force` is how a cleanup command turns\n     * into a data-loss command. The branch is left alone too, since it is still checked out here.\n     */\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private removalFailed(\n        repoRoot: string, verb: MutationVerb, target: DeletableWorktree, sha: string,\n        archive: ArchiveResult, err: string,\n    ): ReapedWorktree {\n        const error = `git refused to remove it: ${err} (not forced — untracked or modified files are `\n            + 'work nothing has archived; remove them or the worktree by hand)';\n        this.log(repoRoot, verb, target, sha, archive.tag, `FAILED (${err})`);\n        const result = new ReapedWorktree(\n            target.path, target.branch, sha, target.reason, target.pr, false, error);\n        result.archiveTag = archive.tag;\n        return result;\n    }\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private log(\n        repoRoot: string, verb: MutationVerb, target: DeletableWorktree,\n        sha: string, archiveTag: string, outcome: string,\n    ): void {\n        const event = new BranchMutationEvent(verb, 'REAP_WORKTREE');\n        event.fromBranch = target.branch;\n        event.sha = sha;\n        event.archiveTag = archiveTag;\n        event.worktreePath = target.path;\n        event.outcome = outcome;\n        this.mutationLog.logBranchMutation(repoRoot, event);\n    }\n\n    /** The literal command that puts BOTH the directory and the branch back. */\n    restoreCommand(target: ReapedWorktree): string {\n        const ref = target.archiveTag !== '' ? target.archiveTag : target.sha;\n        if (ref === '') return `git worktree add ${target.path} <ref>`;\n        if (target.branch === '') return `git worktree add ${target.path} ${ref}`;\n        return `git worktree add -b ${target.branch} ${target.path} ${ref}`;\n    }\n\n    private revParse(repoRoot: string, ref: string): string {\n        const result = this.capture(repoRoot, ['rev-parse', ref]);\n        return result.ok ? result.out : '';\n    }\n\n    // Run a git command capturing trimmed stdout/stderr; ok=false on spawn failure or non-zero exit.\n    private capture(repoRoot: string, args: string[]): CmdCapture {\n        const result = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8' });\n        const err = typeof result.stderr === 'string' ? result.stderr.trim() : '';\n        if (result.status !== 0 || typeof result.stdout !== 'string') {\n            return { ok: false, out: '', err: err !== '' ? err : 'git command failed' };\n        }\n        return { ok: true, out: result.stdout.trim(), err };\n    }\n}\n"]}

package/templates/webpieces.git-workflow.md

@@ -105,13 +105,19 @@ flow are not interchangeable.
 2. **`pnpm wp-finish-update`** — finalize a squash-update after you've resolved its conflicts (validates +
    commits + swaps the branch). Only needed on the conflict path; a clean `wp-start-update` finalizes
    itself. It does NOT build or post a PR.
-3. **`pnpm wp-start-upsert-pr`** — the PR flow: update from main (same 3-point engine), then tells you to
-   run `wp-checklist` + write `review.json`. It runs NO build gate and does NOT push — start only syncs
-   from main; the single (authoritative) build gate and the one push both live in finish. Never creates
-   the PR itself. On a merge conflict here, finish with `pnpm wp-finish-upsert-pr` (not `wp-finish-update`).
-4. **`pnpm wp-finish-upsert-pr`** — validates any in-progress merge, requires your `review.json` (its
-   `title` becomes the PR title), runs the **authoritative** build gate, pushes, and creates/updates the PR.
-5. **`pnpm wp-cleanup`** — delete the local branches that are provably dead (merged PR, squash-merge
+3. **`pnpm wp-start-upsert-pr`** — the PR flow, STAGE ①: update from main (same 3-point engine), then
+   tells you to run `wp-review-upsert-pr`. It runs NO build gate and does NOT push, and never creates the
+   PR itself. On a merge conflict here, resolve it and continue with `pnpm wp-review-upsert-pr` (not
+   `wp-finish-update`, and no longer `wp-finish-upsert-pr`).
+4. **`pnpm wp-review-upsert-pr`** — STAGE ②, and the one that verifies before anyone reviews. It validates
+   and commits any in-progress 3-point merge, asserts a clean tree, runs the **build gate**, extracts this
+   branch's diff to `.webpieces/pr-review/<branch>/diff/`, writes a per-reviewer instructions file, and
+   prints exactly what to spawn plus the `review.json` schema. It CAN fail — and when it does, no reviewer
+   has been spawned yet, so a broken branch costs no review effort.
+5. **`pnpm wp-finish-upsert-pr`** — STAGE ③: requires stage ②'s receipt, your `review.json` (its `title`
+   becomes the PR title) and every reviewer's verdict, then pushes and creates/updates the PR. It re-runs
+   the build gate ONLY if HEAD moved since stage ②, so the three stages still cost one build.
+6. **`pnpm wp-cleanup`** — delete the local branches that are provably dead (merged PR, squash-merge
    backup of a merged branch, or no commits of their own). Run it after `gh pr merge`, or any time the
    branch cap blocks you. It takes no arguments and needs no judgement call from you: it recomputes the
    verdicts itself, deletes one branch per command, spares anything a human should rule on, and logs

package/templates/webpieces.review-checklists.md

@@ -22,23 +22,34 @@ array of `{ subagent, doc?, patterns? }`, and that is the **only** accepted shap
 ## The one command you run
 
 ```bash
-pnpm wp-checklist
+pnpm wp-review-upsert-pr
 ```
 
-It validates the checklist config against **your** diff and prints which reviewer subagents you owe, and
-exactly what to tell each — its doc, what put it in scope, the `git diff` command with the real base sha,
-and the `review-<id>.json` it must write. That block is **self-sufficient**: hand a reviewer those lines
-verbatim. It is safe to run any number of times and never blocks.
+It validates and commits any in-progress 3-point merge, runs the build gate, then **extracts this branch's
+diff to disk** and writes one instructions file per reviewer under
+`.webpieces/pr-review/<branch>/instructions/`. It prints a copy-paste spawn block per reviewer whose prompt
+is a POINTER to that file and nothing else.
+
+That indirection is the design. Everything volatile — the diff, the matched files, the verdict schema, the
+resolved context paths — is REGENERATED every run, so it cannot go stale. The registered
+`.claude/agents/<subagent>.md` stays a thin stub that says "read the instructions file your caller names".
+When the verdict format last changed, hand-written agent files kept documenting the removed `success`
+field and a real PR had to carry a correction in its spawn prompt to work around it; nothing restated by
+hand can drift out of date if nothing is restated by hand.
+
+Unlike the report-only command it replaces, this one **can fail** — on an unresolved merge or a red build.
+It fails before any reviewer is spawned, which is the point.
 
 Checklists already reviewed on this branch are **not** re-listed — verdict files persist, so a second
-wp-start/wp-finish cycle re-instructs nothing.
+start/review/finish cycle re-instructs nothing.
 
 `wp-finish-upsert-pr` recomputes the same set and **refuses to open the PR** while any reviewer still owes
 a passing verdict, naming only the ones still missing.
 
 Note that **not every checklist is pattern-matched**: one with no `patterns` runs on EVERY PR, and the
-whole diff is in its scope. `wp-checklist` says `ALWAYS RUNS` for those rather than calling the whole diff
-a "match".
+whole diff is in its scope. `wp-review-upsert-pr` says `ALWAYS RUNS` for those rather than calling the
+whole diff a "match" — and says so loudly, because a patternless checklist fires on docs-only PRs too, and
+that is usually a missing `patterns` rather than an intent.
 
 Where patterns DO apply, matching is deliberately **coarse** — the reviewer subagent makes the fine,
 content-level judgment by reading the actual diff.