vouchington-tooling 0.52.0 → 0.53.0

package/README.md

@@ -230,6 +230,33 @@ Host-lock environment:
 `git_worktree_canonical_path_hash <path>` helper resolves the physical path and prints a stable
 `d` plus the first 12 lowercase hexadecimal characters of its SHA-256 digest.
 
+## Reclaiming finished worktrees
+
+`vouchington worktree reclaim [--yes] [--json]` removes git worktrees whose work is done. It is a
+dry run unless `--yes` is passed. It prints one line per worktree (`reclaimed`, `would reclaim`, or
+`kept: <reason>`, control characters escaped), or `{ dryRun, worktrees }` with `--json`.
+
+It skips the main checkout, the caller's own worktree, and locked, bare, detached and missing
+worktrees. Any other worktree is kept, with a reason, unless all of these hold:
+
+- `git status` (untracked files and submodules included) is empty, and no index entry is
+  assume-unchanged or skip-worktree.
+- `gh pr list --head <branch>` has a merged or closed pull request from this repository (not a
+  fork) whose `headRefOid` equals HEAD, and no open pull request from this repository. That PR also
+  proves HEAD is published, so squash merges whose branch was deleted are reclaimed. A `gh` failure,
+  or a query returning 1000 results, keeps the worktree.
+
+With `--yes`, HEAD and cleanliness are checked again right before `git worktree remove <path>` runs.
+It is never forced, and a refusal from git is reported as kept. Ignored files (for example `.env`, `node_modules`, build output) are deleted with the worktree, exactly as `git worktree remove` does; keep anything you need outside ignored paths or commit it. An unexpected error on one worktree is reported as `kept: error: <message>` and the run carries on. There is no `prune`, no branch
+deletion, and git runs with `core.fsmonitor=false`.
+
+Known limitations: git cannot check and remove a worktree atomically, so a worktree that changes in the moment between the final check and `git worktree remove` can still be removed; the final check runs immediately before removal to keep that window small.
+
+This is NOT a security boundary. Run it as a trusted user or agent, and do not grant it as an
+unconditional allow rule. It has no teardown hook: per-worktree resources such as databases and
+containers are reclaimed afterwards by the consumer's own orphan cleanup, because the worktree is
+gone.
+
 ## Library
 
 ```ts

package/dist/cli/commands/worktree.d.mts

@@ -0,0 +1,2 @@
+/** `vouchington worktree reclaim [--yes] [--json]`: exits 2 on bad usage, 1 when git cannot list. */
+export declare function runWorktreeCommand(args: readonly string[], env?: NodeJS.ProcessEnv, cwd?: string): number;

package/dist/cli/commands/worktree.mjs

@@ -0,0 +1,21 @@
+import { formatReport, reclaimWorktrees } from "../../git-worktrees/reclaim.mjs";
+import { commandUsage } from "../usage.mjs";
+/** `vouchington worktree reclaim [--yes] [--json]`: exits 2 on bad usage, 1 when git cannot list. */
+export function runWorktreeCommand(args, env = process.env, cwd = process.cwd()) {
+    const [subcommand, ...flags] = args;
+    const unknown = flags.find((flag) => flag !== '--yes' && flag !== '--json');
+    if (subcommand !== 'reclaim' || unknown !== undefined) {
+        process.stderr.write(`vouchington: expected: reclaim [--yes] [--json]\n${commandUsage('worktree')}`);
+        return 2;
+    }
+    try {
+        const report = reclaimWorktrees(flags.includes('--yes'), { cwd, env });
+        const json = flags.includes('--json');
+        process.stdout.write(json ? `${JSON.stringify(report)}\n` : formatReport(report));
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`vouchington: ${error.message}\n`);
+        return 1;
+    }
+}

package/dist/cli/index.mjs

@@ -20,6 +20,7 @@ import { runLinkSkill } from "./commands/link-skill.mjs";
 import { runRetrospectiveFactsCommand } from "./commands/retrospective-facts.mjs";
 import { runAgentBlackboardCommand } from "./commands/agent-blackboard.mjs";
 import { runMcpCommand } from "./commands/mcp.mjs";
+import { runWorktreeCommand } from "./commands/worktree.mjs";
 import { runWithHostLock } from "./commands/with-host-lock.mjs";
 import { runFreshBase } from "./commands/fresh-base.mjs";
 import { runRequireUpToDate } from "./commands/require-up-to-date.mjs";
@@ -134,6 +135,8 @@ export function runCli(argv = process.argv) {
             return runAgentBlackboardCommand(parsed.args);
         case 'mcp':
             return runMcpCommand(parsed.args);
+        case 'worktree':
+            return runWorktreeCommand(parsed.args);
         case 'require-up-to-date':
             return runRequireUpToDate(parsed);
         case 'fresh-base':

package/dist/cli/parse-forwarded-commands.d.mts

@@ -37,6 +37,9 @@ type ForwardedCommand = {
 } | {
     kind: 'mcp';
     args: string[];
+} | {
+    kind: 'worktree';
+    args: string[];
 };
 export declare function parseForwardedCommand(command: string | undefined, args: string[]): ForwardedCommand | undefined;
 export {};

package/dist/cli/parse-forwarded-commands.mjs

@@ -25,5 +25,7 @@ export function parseForwardedCommand(command, args) {
         return { kind: 'agent-blackboard', args };
     if (command === 'mcp')
         return { kind: 'mcp', args };
+    if (command === 'worktree')
+        return { kind: 'worktree', args };
     return undefined;
 }

package/dist/cli/parse.d.mts

@@ -66,6 +66,9 @@ export type ParsedCli = {
 } | {
     kind: 'mcp';
     args: string[];
+} | {
+    kind: 'worktree';
+    args: string[];
 } | {
     kind: 'require-up-to-date';
     remote: string;

package/dist/cli/usage.d.mts

@@ -1,4 +1,4 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  fresh-base                    Classify the worktree against a remote base branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions (KEEP_MIN or --main-history)\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  gha-collaborator-trust        Classify authors as write-access collaborators or not\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N]  (SessionStart hook; payload on stdin)\nagent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, retrospective_check, retrospective_save,\n                         pr_validate, pr_create, pr_update,\n                         snapshot_export, snapshot_cleanup, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  fresh-base                    Classify the worktree against a remote base branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions (KEEP_MIN or --main-history)\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  gha-collaborator-trust        Classify authors as write-access collaborators or not\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\n  worktree                      Reclaim finished git worktrees (dry run unless --yes)\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N]  (SessionStart hook; payload on stdin)\nagent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, retrospective_check, retrospective_save,\n                         pr_validate, pr_create, pr_update,\n                         snapshot_export, snapshot_cleanup, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n\nworktree reclaim [--yes] [--json]\n  Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n  branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n  Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;
 export declare function commandNames(usage?: string): string[];
 export declare function commandUsage(command: string, usage?: string): string;

package/dist/cli/usage.mjs

@@ -47,6 +47,7 @@ Commands:
   retrospective-facts           Gather immutable facts for a retrospective
   agent-blackboard              Probe and journal an Agent Blackboard deployment
   mcp                           Serve the agent-blackboard journal tools over stdio (MCP)
+  worktree                      Reclaim finished git worktrees (dry run unless --yes)
 
 Options:
   -h, --help       Show this help
@@ -134,6 +135,11 @@ mcp
                          snapshot_export, snapshot_cleanup, and session_archive over stdio.
                          Needs the optional @modelcontextprotocol/sdk peer (and zod).
                          Launch it from inside the repository's git worktree.
+
+worktree reclaim [--yes] [--json]
+  Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the
+  branch is merged or closed at exactly HEAD, using git worktree remove (never forced).
+  Skips the main checkout, the current worktree, and locked, bare or detached worktrees.
 `;
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);

package/dist/git-worktrees/assess.d.mts

@@ -0,0 +1,14 @@
+import { type RunOptions } from './run.mts';
+export type Assessment = {
+    readonly head: string;
+} | {
+    readonly reason: string;
+};
+export declare function readRepository(main: RunOptions): string | undefined;
+/** Clean status and no hidden index entries. Returns the HEAD commit or a reason. */
+export declare function assessLocal(worktree: RunOptions): Assessment;
+/**
+ * Needs a merged or closed same-repository PR for this branch whose head is exactly HEAD. That
+ * also proves HEAD is published on GitHub, so deleted branches (squash merges) need no remote ref.
+ */
+export declare function assessPullRequest(branch: string, head: string, repository: string | undefined, main: RunOptions): string | undefined;

package/dist/git-worktrees/assess.mjs

@@ -0,0 +1,68 @@
+import { git, LOCAL_ENV, run, withoutVariables } from "./run.mjs";
+const FINISHED = new Set(['MERGED', 'CLOSED']);
+function parseJson(text) {
+    try {
+        return text === undefined ? undefined : JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Repo-local git variables, GH_REPO and GH_HOST must not redirect the lookup away from the main checkout. */
+function runGh(args, main) {
+    const env = withoutVariables(main.env, [...LOCAL_ENV, 'GH_REPO', 'GH_HOST']);
+    return run('gh', args, { cwd: main.cwd, env });
+}
+export function readRepository(main) {
+    const repo = parseJson(runGh(['repo', 'view', '--json', 'nameWithOwner'], main));
+    return repo?.nameWithOwner?.toLowerCase();
+}
+/** Clean status and no hidden index entries. Returns the HEAD commit or a reason. */
+export function assessLocal(worktree) {
+    const status = git(['status', '--porcelain', '--untracked-files=all', '--ignore-submodules=none'], worktree);
+    if (status === undefined)
+        return { reason: 'cannot read status' };
+    if (status !== '')
+        return { reason: 'uncommitted changes' };
+    const files = git(['ls-files', '-v', '-z'], worktree);
+    if (files === undefined)
+        return { reason: 'cannot read index' };
+    if (files.split('\0').some((entry) => /^[a-zS]/.test(entry))) {
+        return { reason: 'hidden index entries (assume-unchanged or skip-worktree)' };
+    }
+    const headOutput = git(['rev-parse', 'HEAD'], worktree);
+    if (headOutput === undefined)
+        return { reason: 'cannot read HEAD' };
+    const head = headOutput.trim();
+    return { head };
+}
+const PAGE = 1000;
+function listPulls(branch, state, main) {
+    const fields = 'state,headRefOid,isCrossRepository,headRepository,headRepositoryOwner';
+    const args = ['pr', 'list', '--head', branch, '--state', state, '--limit', String(PAGE)];
+    const listed = parseJson(runGh([...args, '--json', fields], main));
+    return Array.isArray(listed) && listed.length < PAGE ? listed : undefined;
+}
+/**
+ * Needs a merged or closed same-repository PR for this branch whose head is exactly HEAD. That
+ * also proves HEAD is published on GitHub, so deleted branches (squash merges) need no remote ref.
+ */
+export function assessPullRequest(branch, head, repository, main) {
+    if (repository === undefined)
+        return 'cannot read repository';
+    // Open PRs are queried on their own so a long history cannot hide one; a full page is unreadable.
+    const open = listPulls(branch, 'open', main);
+    const all = listPulls(branch, 'all', main);
+    if (open === undefined || all === undefined)
+        return 'cannot read PR state';
+    const own = [...open, ...all].filter((pr) => pr.isCrossRepository === false &&
+        `${pr.headRepositoryOwner?.login}/${pr.headRepository?.name}`.toLowerCase() === repository);
+    if (own.some((pr) => pr.state === 'OPEN'))
+        return 'open PR';
+    const finished = own.filter((pr) => FINISHED.has(pr.state));
+    if (finished.length === 0)
+        return 'no finished PR from this repository';
+    if (!finished.some((pr) => pr.headRefOid === head))
+        return 'PR head differs from HEAD';
+    return undefined;
+}

package/dist/git-worktrees/list.d.mts

@@ -0,0 +1,10 @@
+export interface WorktreeRecord {
+    readonly path: string;
+    readonly branch?: string;
+    readonly head?: string;
+    readonly locked: boolean;
+    readonly bare: boolean;
+    readonly detached: boolean;
+}
+/** Parses `git worktree list --porcelain -z` (NUL fields, an empty field ends each record). */
+export declare function parseWorktreeList(porcelain: string | undefined): WorktreeRecord[];

package/dist/git-worktrees/list.mjs

@@ -0,0 +1,34 @@
+const BRANCH_PREFIX = 'branch refs/heads/';
+function parseRecord(fields) {
+    const path = fields.find((field) => field.startsWith('worktree '))?.slice('worktree '.length);
+    if (path === undefined)
+        return undefined;
+    const branch = fields
+        .find((field) => field.startsWith(BRANCH_PREFIX))
+        ?.slice(BRANCH_PREFIX.length);
+    const head = fields.find((field) => field.startsWith('HEAD '))?.slice('HEAD '.length);
+    return {
+        path,
+        locked: fields.some((field) => field === 'locked' || field.startsWith('locked ')),
+        bare: fields.includes('bare'),
+        detached: fields.includes('detached'),
+        ...(branch === undefined ? {} : { branch }),
+        ...(head === undefined ? {} : { head }),
+    };
+}
+/** Parses `git worktree list --porcelain -z` (NUL fields, an empty field ends each record). */
+export function parseWorktreeList(porcelain) {
+    const records = [];
+    let fields = [];
+    for (const field of [...(porcelain ?? '').split('\0'), '']) {
+        if (field !== '') {
+            fields.push(field);
+            continue;
+        }
+        const record = parseRecord(fields);
+        if (record !== undefined)
+            records.push(record);
+        fields = [];
+    }
+    return records;
+}

package/dist/git-worktrees/reclaim.d.mts

@@ -0,0 +1,15 @@
+import { type RunOptions } from './run.mts';
+interface ReclaimEntry {
+    readonly path: string;
+    readonly branch: string;
+    readonly status: 'reclaimed' | 'would reclaim' | 'kept';
+    readonly reason?: string;
+}
+export interface ReclaimReport {
+    readonly dryRun: boolean;
+    readonly worktrees: ReclaimEntry[];
+}
+/** Lists finished worktrees and, with `yes`, removes them with a plain (never forced) `git worktree remove`. */
+export declare function reclaimWorktrees(yes: boolean, runtime: RunOptions): ReclaimReport;
+export declare function formatReport(report: ReclaimReport): string;
+export {};

package/dist/git-worktrees/reclaim.mjs

@@ -0,0 +1,80 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { sep } from 'node:path';
+import { assessLocal, assessPullRequest, readRepository } from "./assess.mjs";
+import { parseWorktreeList } from "./list.mjs";
+import { git } from "./run.mjs";
+/** Assesses (and with `yes` removes) one worktree; undefined means it is not a candidate. */
+function reclaimOne(record, context) {
+    const { path, branch, locked, bare, detached } = record;
+    if (locked || bare || detached || branch === undefined)
+        return undefined;
+    if (!existsSync(path) || realpathSync(path) === context.selfReal)
+        return undefined;
+    const keep = (reason) => ({ path, branch, status: 'kept', reason });
+    const nests = (paths) => paths.some((other) => other.startsWith(path + sep));
+    if (nests(context.registered)) {
+        return keep('contains another worktree');
+    }
+    const worktree = { cwd: path, env: context.runtime.env };
+    const local = assessLocal(worktree);
+    if ('reason' in local)
+        return keep(local.reason);
+    const reason = assessPullRequest(branch, local.head, context.repository, context.mainRun);
+    if (reason !== undefined)
+        return keep(reason);
+    if (!context.yes)
+        return { path, branch, status: 'would reclaim' };
+    const again = assessLocal(worktree);
+    const pullAgain = assessPullRequest(branch, local.head, context.repository, context.mainRun);
+    const listed = parseWorktreeList(git(['worktree', 'list', '--porcelain', '-z'], context.runtime));
+    const same = listed.some((entry) => entry.path === path && entry.branch === branch && entry.head === local.head);
+    if (nests(listed.map((entry) => entry.path)))
+        return keep('contains another worktree');
+    if ('reason' in again || again.head !== local.head || pullAgain !== undefined || !same)
+        return keep('changed since check');
+    if (git(['worktree', 'remove', path], { ...context.mainRun, timeout: 0 }) === undefined) {
+        return keep('git worktree remove refused');
+    }
+    return { path, branch, status: 'reclaimed' };
+}
+/** Lists finished worktrees and, with `yes`, removes them with a plain (never forced) `git worktree remove`. */
+export function reclaimWorktrees(yes, runtime) {
+    const listing = git(['worktree', 'list', '--porcelain', '-z'], runtime);
+    const self = git(['rev-parse', '--show-toplevel'], runtime)?.replace(/\n$/, '');
+    const [main, ...others] = parseWorktreeList(listing);
+    if (main === undefined || !self)
+        throw new Error('not inside a git worktree');
+    const mainRun = { cwd: main.path, env: runtime.env };
+    const context = {
+        yes,
+        runtime,
+        mainRun,
+        selfReal: realpathSync(self),
+        registered: [main, ...others].map((record) => record.path),
+        repository: readRepository(mainRun),
+    };
+    const worktrees = [];
+    for (const record of others) {
+        try {
+            const entry = reclaimOne(record, context);
+            if (entry !== undefined)
+                worktrees.push(entry);
+        }
+        catch (error) {
+            const reason = `error: ${error.message}`;
+            worktrees.push({ path: record.path, branch: record.branch, status: 'kept', reason });
+        }
+    }
+    return { dryRun: !yes, worktrees };
+}
+function escape(text) {
+    return text.replace(/\p{Cc}/gu, (char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`);
+}
+export function formatReport(report) {
+    return report.worktrees
+        .map((entry) => {
+        const status = entry.status === 'kept' ? `kept: ${entry.reason}` : entry.status;
+        return `${escape(entry.path)}: ${escape(status)}\n`;
+    })
+        .join('');
+}

package/dist/git-worktrees/reclaim.test-helpers.d.mts

@@ -0,0 +1,16 @@
+export interface Fixture {
+    readonly root: string;
+    readonly main: string;
+    readonly caller: string;
+    readonly env: NodeJS.ProcessEnv;
+    git(cwd: string, ...args: string[]): string;
+    /** Adds a worktree on a new branch with one commit; optionally pushes it to origin. */
+    addWorktree(name: string, options?: {
+        push?: boolean;
+        dir?: string;
+    }): string;
+    /** Writes the fake `gh pr list` answer; a PR with no head defaults to the branch tip. */
+    setPrs(branch: string, prs: object[]): void;
+    cleanup(): void;
+}
+export declare function createFixture(): Fixture;

package/dist/git-worktrees/reclaim.test-helpers.mjs

@@ -0,0 +1,113 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+// Answers `gh repo view` and `gh pr list --head <branch>` from files, like the real CLI.
+const FAKE_GH = `#!${process.execPath}
+const fs = require('node:fs')
+const args = process.argv.slice(2)
+const env = process.env
+if (env.FAKE_GH_FAIL) process.exit(1)
+if (env.FAKE_GH_NO_GIT_DIR && env.GIT_DIR) process.exit(1)
+if (args[0] === 'repo') {
+  console.log(JSON.stringify({ nameWithOwner: env.GH_REPO || 'Acme/Widgets' }))
+  process.exit(0)
+}
+if (env.FAKE_GH_GARBAGE) {
+  console.log('not json')
+  process.exit(0)
+}
+const state = args[args.indexOf('--state') + 1]
+// Simulates a change that lands between the first assessment and the re-check.
+if (state === 'all') {
+  const { execFileSync } = require('node:child_process')
+  const run = (cwd, ...a) => execFileSync('git', a, { cwd, stdio: 'ignore' })
+  if (env.FAKE_GH_NEST && !fs.existsSync(env.FAKE_GH_DIR + '/nested')) {
+    fs.writeFileSync(env.FAKE_GH_DIR + '/nested', '')
+    run(env.FAKE_GH_NEST, 'worktree', 'add', '-b', 'kid', 'sub/kid')
+  }
+  if (env.FAKE_GH_TOUCH) fs.writeFileSync(env.FAKE_GH_TOUCH, 'x')
+  if (env.FAKE_GH_SWITCH) run(env.FAKE_GH_SWITCH, 'checkout', '-b', 'switched')
+  if (env.FAKE_GH_ADVANCE) {
+    run(env.FAKE_GH_ADVANCE, 'commit', '--allow-empty', '-m', 'late')
+    run(env.FAKE_GH_ADVANCE, 'push', 'origin', 'HEAD')
+  }
+}
+const branch = args[args.indexOf('--head') + 1]
+const file = env.FAKE_GH_DIR + '/' + branch.replaceAll('/', '_') + '.json'
+let pulls = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : []
+if (state === 'open') pulls = pulls.filter((pr) => pr.state === 'OPEN')
+const pad = Number(env['FAKE_GH_PAD_' + state.toUpperCase()] || 0)
+for (let i = 0; i < pad; i += 1) pulls.push({ state: 'CLOSED' })
+console.log(JSON.stringify(pulls))
+// Reopen every PR after the first full answer, as if it changed before the re-check.
+if (state === 'all' && env.FAKE_GH_REOPEN && !fs.existsSync(file + '.reopened')) {
+  fs.writeFileSync(file, JSON.stringify(pulls.map((pr) => ({ ...pr, state: 'OPEN' }))))
+  fs.writeFileSync(file + '.reopened', '')
+}
+`;
+const realGit = execFileSync('which', ['git'], { encoding: 'utf8' }).trim();
+export function createFixture() {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), 'worktree-reclaim-')));
+    const bin = join(root, 'bin');
+    const ghDir = join(root, 'gh');
+    mkdirSync(bin);
+    mkdirSync(ghDir);
+    writeFileSync(join(bin, 'gh'), FAKE_GH);
+    chmodSync(join(bin, 'gh'), 0o755);
+    // A git wrapper that fails any invocation containing the words in FAKE_GIT_FAIL, to reach error paths.
+    writeFileSync(join(bin, 'git'), `#!/bin/sh\ncase " $* " in *" $FAKE_GIT_FAIL "*) [ -n "$FAKE_GIT_FAIL" ] && exit 1;; esac\nexec '${realGit}' "$@"\n`);
+    chmodSync(join(bin, 'git'), 0o755);
+    const env = {
+        ...process.env,
+        PATH: `${bin}:${process.env.PATH ?? ''}`,
+        FAKE_GH_DIR: ghDir,
+        GIT_CONFIG_GLOBAL: '/dev/null',
+        GIT_CONFIG_SYSTEM: '/dev/null',
+        GIT_AUTHOR_NAME: 'Test',
+        GIT_AUTHOR_EMAIL: 'test@example.com',
+        GIT_COMMITTER_NAME: 'Test',
+        GIT_COMMITTER_EMAIL: 'test@example.com',
+    };
+    const git = (cwd, ...args) => execFileSync('git', args, { cwd, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    const origin = join(root, 'origin.git');
+    const main = join(root, 'main');
+    git(root, 'init', '--bare', '-b', 'main', origin);
+    git(root, 'init', '-b', 'main', main);
+    writeFileSync(join(main, 'README.md'), 'base\n');
+    git(main, 'add', '.');
+    git(main, 'commit', '-m', 'base');
+    git(main, 'remote', 'add', 'origin', origin);
+    git(main, 'push', '-u', 'origin', 'main');
+    const caller = join(root, 'worktrees', 'caller');
+    git(main, 'worktree', 'add', '-b', 'caller', caller);
+    return {
+        root,
+        main,
+        caller,
+        env,
+        git,
+        addWorktree: (name, options = {}) => {
+            const path = join(root, 'worktrees', options.dir ?? name);
+            git(main, 'worktree', 'add', '-b', name, path);
+            writeFileSync(join(path, `${name}.txt`), `${name}\n`);
+            git(path, 'add', '.');
+            git(path, 'commit', '-m', name);
+            if (options.push)
+                git(path, 'push', '-u', 'origin', name);
+            return path;
+        },
+        setPrs: (branch, prs) => {
+            const tip = git(main, 'rev-parse', `refs/heads/${branch}`).trim();
+            const filled = prs.map((pr) => ({
+                headRefOid: tip,
+                isCrossRepository: false,
+                headRepository: { name: 'Widgets' },
+                headRepositoryOwner: { login: 'acme' },
+                ...pr,
+            }));
+            writeFileSync(join(ghDir, `${branch.replaceAll('/', '_')}.json`), JSON.stringify(filled));
+        },
+        cleanup: () => rmSync(root, { force: true, recursive: true }),
+    };
+}

package/dist/git-worktrees/run.d.mts

@@ -0,0 +1,13 @@
+export interface RunOptions {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    /** Milliseconds before a read-only call is killed; 0 for none (worktree removal). */
+    readonly timeout?: number;
+}
+/** Runs a command without a shell; returns stdout, or undefined when it fails to start or exits non-zero. */
+export declare function run(file: string, args: readonly string[], options: RunOptions): string | undefined;
+export declare const LOCAL_ENV: string[];
+/** A copy of `env` without the named variables. */
+export declare function withoutVariables(env: NodeJS.ProcessEnv, names: readonly string[]): NodeJS.ProcessEnv;
+/** git with fsmonitor disabled so a repository config can never execute a hook. */
+export declare function git(args: readonly string[], options: RunOptions): string | undefined;

package/dist/git-worktrees/run.mjs

@@ -0,0 +1,50 @@
+import { execFileSync } from 'node:child_process';
+/** Runs a command without a shell; returns stdout, or undefined when it fails to start or exits non-zero. */
+export function run(file, args, options) {
+    try {
+        return execFileSync(file, args, {
+            cwd: options.cwd,
+            env: options.env,
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: options.timeout ?? 120_000,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+// Repo-local overrides (see `git rev-parse --local-env-vars`): the cwd must pick the repository.
+export const LOCAL_ENV = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_COMMON_DIR',
+    'GIT_PREFIX',
+    'GIT_NAMESPACE',
+    'GIT_CONFIG',
+    'GIT_CONFIG_PARAMETERS',
+    'GIT_CONFIG_COUNT',
+    'GIT_GRAFT_FILE',
+    'GIT_IMPLICIT_WORK_TREE',
+    'GIT_INTERNAL_SUPER_PREFIX',
+    'GIT_SHALLOW_FILE',
+    'GIT_REPLACE_REF_BASE',
+    'GIT_NO_REPLACE_OBJECTS',
+    'GIT_QUARANTINE_PATH',
+];
+/** A copy of `env` without the named variables. */
+export function withoutVariables(env, names) {
+    const copy = { ...env };
+    for (const name of names)
+        delete copy[name];
+    return copy;
+}
+/** git with fsmonitor disabled so a repository config can never execute a hook. */
+export function git(args, options) {
+    const env = withoutVariables(options.env, LOCAL_ENV);
+    return run('git', ['-c', 'core.fsmonitor=false', ...args], { ...options, env });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "agent-workflow",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "agent-workflow/SKILL.md",
       "prerequisites": [
         "blackboard",
@@ -24,7 +24,7 @@
     {
       "name": "blackboard",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "blackboard/SKILL.md"
     },
     {
@@ -36,7 +36,7 @@
     {
       "name": "dependabot",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "dependabot/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
@@ -50,26 +50,26 @@
     {
       "name": "git-commit-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "git-commit-checklist/SKILL.md"
     },
     {
       "name": "github-actions-authoring",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "github-actions-authoring/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "github-actions-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "github-actions-checklist/SKILL.md"
     },
     {
       "name": "github-issue",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "github-issue/SKILL.md"
     },
     {
@@ -82,26 +82,26 @@
     {
       "name": "npm-publishing",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "npm-publishing/SKILL.md"
     },
     {
       "name": "organize-github-issues",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "organize-github-issues/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "package-json-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "package-json-checklist/SKILL.md"
     },
     {
       "name": "planning",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "planning/SKILL.md",
       "prerequisites": ["github-issue"]
     },
@@ -133,53 +133,53 @@
     {
       "name": "pr-description",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "pr-description/SKILL.md"
     },
     {
       "name": "retrospective",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "retrospective/SKILL.md"
     },
     {
       "name": "retrospective-distill",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "retrospective-distill/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "review-ci-logs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "review-ci-logs/SKILL.md",
       "prerequisites": ["github-actions-checklist", "pr-description"]
     },
     {
       "name": "review-github-issue-taxonomy",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "review-github-issue-taxonomy/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "revisit-followups",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "revisit-followups/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "stacked-prs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "stacked-prs/SKILL.md"
     },
     {
       "name": "static-analysis-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "static-analysis-checklist/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
@@ -206,7 +206,7 @@
     {
       "name": "triage-prs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "triage-prs/SKILL.md",
       "prerequisites": [
         "pr-description",

package/skills/stacked-prs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacked-prs
-description: Work native GitHub stacks bottom-up and merge the ready prefix in one command; a ready lower layer does not freeze later work.
+description: Work native GitHub stacks bottom-up and prefer merging the whole stack in one command; drain the ready lower layers first only when the upper layers will clearly take longer.
 ---
 
 # Stacked pull requests
@@ -44,7 +44,8 @@ a stack, and who may authorize a merge.
   a ready-delay, or green CI.
 - On each shepherd result, act on the lowest owned layer that is not ready before any higher
   layer. Put each fix on the lowest layer that owns it. A bottom layer that reaches ready early
-  frees the ready prefix above it to merge in one command.
+  waits for the rest of the stack unless the layers above will clearly take longer; keep readying
+  them.
 - Before a command that adds layers to a stack, such as `gh stack add` or `gh stack link`, add the
   forge's open-layer count, plus every locally tracked layer not yet submitted, to every layer the
   command would add. `gh stack add` creates only a local branch, so repeated adds before a submit
@@ -54,20 +55,25 @@ a stack, and who may authorize a merge.
 - A ready, mergeable, or queued lower layer blocks only an operation that would rewrite that
   layer. Keep readying every other owned layer.
 
-## Merge the ready prefix
+## Merge the whole stack
 
-- Do not merge one layer at a time, and do not wait for the whole stack. Layers accumulate rebase
-  surface, CI cost, and review context, and drift against the default branch.
-- The ready prefix is the bottom-most open layer plus every consecutive layer above it that is
-  also ready and inside the human's approval. As soon as the bottom layer is ready, merge the ready
-  prefix with one command whose target is the prefix's top layer. When every layer is ready and
-  approved, the target is the top of the stack.
+- Prefer merging the whole stack at once: when every layer is ready and inside the human's
+  approval, merge it with one command whose target is the top layer. Never merge one layer at a
+  time, and never merge only the lower layers when every layer is ready.
+- Ready every layer in parallel so the stack reaches ready together. A ready lower layer waits
+  while the layers above are close behind (a poll or a ready-delay away).
+- Drain bottom-up only when the layers above will clearly take longer: a requested change or
+  `FIX_CODE` still open, a pending human review, a blocker, or CI far longer than the wait so far.
+  Then merge the ready lower layers in one command whose target is the highest ready layer, state
+  why in the report, and merge the rest together when it is ready.
+- Re-read every layer's readiness immediately before merging. If the whole stack is ready and
+  approved, the target is the top layer; never retarget past the approval.
 - Nothing in the stack merges on its own. Run the merge checks in
-  [Drain and keep track](references/drain.md#merge-the-ready-prefix) before each merge.
-- After a merge, GitHub retargets the next unmerged layer onto the default branch. That layer is
-  the new bottom.
+  [Drain and keep track](references/drain.md#merge-the-whole-stack) before each merge.
+- After a bottom-up drain, GitHub retargets the next unmerged layer onto the default branch. That
+  layer is the new bottom.
 - On a stall, or when a layer closes without merging, stop if the bottom layers are otherwise
-  ready. Report every layer and ask before merging that ready prefix.
+  ready. Report every layer and ask before draining them.
 - A stall blocks only layers that depend on it. Ready the others. Pause the whole drain only when
   nothing further can be readied without the blocked layer.
 

package/skills/stacked-prs/references/drain.md

@@ -1,8 +1,8 @@
 # Drain and keep track
 
 Shepherding a layer to ready and merging are different acts. The first covers every pull request
-the worker owns in the stack at once. The second lands the ready prefix in one command, and it is
-never the agent's own decision.
+the worker owns in the stack at once. The second lands the whole stack in one command once every
+layer is ready, and it is never the agent's own decision.
 
 ## Establish scope
 
@@ -89,48 +89,55 @@ When the owned set settles, present the stack bottom to top: each layer's number
 and whether it is ready or blocked and why. Never leave a ready bottom layer under a blocked upper
 layer without saying so.
 
-## Merge the ready prefix
+## Merge the whole stack
 
-The ready prefix is the bottom-most open layer plus every consecutive layer above it that is also
-ready and inside the approval. Its top layer is the merge target. A shepherd that prints a merge
-of its highest ready layer may name a layer above the approved range. Target the highest approved
-layer of the prefix instead; that is still one command.
+Prefer one merge of the whole stack: when every open layer is ready and inside the approval, the
+target is the top layer, and one command lands it and every layer below it. A shepherd that prints
+a merge for a lower layer does not change that; when the whole stack is ready, target the top.
+
+Drain bottom-up only when the layers above will clearly take longer than the ready lower layers:
+an open requested change or `FIX_CODE`, a pending human review, a blocker, or CI far longer than
+the wait so far. A layer a poll or a ready-delay away is not a reason. Then the target is the
+highest layer of the ready, approved run from the bottom, still one command, and the report says
+why the upper layers were left.
 
 Merge only on explicit human approval. The approval names what it covers: one layer, a range, or
-the whole stack. Approving the whole stack also covers the next ready prefix after an earlier
-merge. It does not cover a layer added after the approval. Ask before merging any layer outside
-it.
+the whole stack. Approving the whole stack also covers a bottom-up drain under the rule above. It
+does not cover a layer added after the approval. Ask before merging any layer outside it.
 
-Immediately before each approved merge, run these checks in order:
+Immediately before the approved merge, run these checks in order:
 
 1. `gh api repos/{owner}/{repo}/stacks/<target>` must return 404. `gh stack merge` resolves a bare
    number as a stack number first, then a pull request number. A 200 response means `--yes` would
    merge every layer of that stack. Stop and ask.
 2. Re-read topology. Confirm every layer from the bottom-most open layer up to the target is open,
-   ready, and inside the approval, with nothing broken below.
-3. For every layer in the prefix, capture `pulls/<N>.head.sha` before the final poll and after it.
+   ready, and inside the approval, with nothing broken below. Re-read every layer above the
+   target too. If those layers are all ready now and the approval covers them, retarget to the
+   highest of them and restart these checks from step 1 for the new target. Never retarget past
+   the approval; report the ready layers above it and ask.
+3. For every layer being merged, capture `pulls/<N>.head.sha` before the final poll and after it.
    They must match. A mismatch means a push landed inside the evaluation window: discard the
    verdict and poll again.
 4. `gh stack merge <target> --yes` with the repository's merge strategy. It lands the target and
-   every open layer below it, which is the ready prefix.
+   every open layer below it.
 5. Do not `gh stack sync` here. Return to step 2 of [Establish scope](#establish-scope) and
    re-read topology remotely: rebasing right after a merge can replay already-landed commits from
-   a stale local base ref. Keep shepherding the layers above. When the new bottom is ready, merge
-   the next ready prefix the same way. Before any local edit, rebase, or push on a remaining
-   layer, rerun the fetch and ahead/behind check in
+   a stale local base ref. After a bottom-up drain, keep shepherding the layers above and merge
+   the rest the same way, preferring the whole remainder at once. Before any local edit, rebase, or push
+   on a remaining layer, rerun the fetch and ahead/behind check in
    [Import a stack](gh-stack.md#import-a-stack-before-acting-on-it): GitHub rebases the next
    layer remotely, so local upper branches are stale until fast-forwarded. The drain is complete when no unmerged owned layer remains.
 
 The window between the last head read and the merge cannot be closed, because `gh stack merge`
 has no head-SHA pin. Branch protection and rulesets are evaluated when the merge runs, and stacks
 cannot bypass merge requirements. If the merge is rejected, re-read topology instead of retrying
-blindly. Under a merge queue, a successful `gh stack merge` only enqueues: the prefix queues
+blindly. Under a merge queue, a successful `gh stack merge` only enqueues: the layers queue
 together, and a failing layer is ejected along with the layers above it. The next topology
 re-read handles that.
 
 When you stop or are blocked (an unresolved escalation, an interrupt or pause, repeated fixes with
 no progress, or an external blocker), report each layer's number and state. If the bottom layers
-are ready, ask whether to merge that ready prefix before continuing.
+are ready, ask whether to drain them before continuing.
 
 ## Keep track: derive the ledger
 

package/skills/triage-prs/SKILL.md

@@ -137,11 +137,11 @@ Classify the outcome:
 - **Repository auto-merge disabled:** dispatch the shepherd, report that a manual merge is
   required, and leave auto-merge unchanged.
 - **Native GitHub stack:** shepherd the owned layers per
-  [stacked-prs](../stacked-prs/SKILL.md#ownership-and-workers) and merge the ready prefix per
-  [Merge the ready prefix](../stacked-prs/SKILL.md#merge-the-ready-prefix), within explicit human
+  [stacked-prs](../stacked-prs/SKILL.md#ownership-and-workers) and merge the whole stack per
+  [Merge the whole stack](../stacked-prs/SKILL.md#merge-the-whole-stack), within explicit human
   approval and only as far as this run's decisions cover. Resolve the full stack against the Step 1
-  scope and Step 3 decisions first. End the ready prefix below the first layer that is out of scope
-  or not `MERGE`; never shepherd or merge a layer this run did not review. GitHub has no
+  scope and Step 3 decisions first. A bottom-up drain ends below the first layer that is out of
+  scope or not `MERGE`; never shepherd or merge a layer this run did not review. GitHub has no
   auto-merge for stacks, and an armed auto-merge does not authorize the drain on its own.
 
 Do not add a second pass that polls the dispatch workflow. It ends once the session is accepted or