artshelf 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+- Added approval-gated `artshelf ledgers prune` registry maintenance: dry-run
+  writes or reuses a reviewed plan for missing registered ledger files, `--agent`
+  emits the exact registry-prune approval target, execute binds to one registry
+  and plan id, writes a rollback copy and receipt, and `doctor`/`status`/`review`
+  agent guidance routes stale registrations to this flow instead of manual JSON
+  edits.
+- Hardened `cleanup --execute` with durable resumability: a `started` receipt is
+  written before the first filesystem move so an interrupted run is detectable,
+  terminal receipt evidence preserves an artifact's original
+  `executedAt`/`cleanedAt`, an artifact already moved into the plan's trash
+  directory without terminal receipt evidence is recorded as `trashed` at resume
+  time without moving it again, a missing original path with no trash target and no
+  receipt evidence stays a skipped missing path rather than a success, and a
+  completed receipt replays idempotently without duplicating the Artshelf-owned
+  receipt record (NGX-427).
 - Renamed the published package and CLI binary from `shelf` to `artshelf`,
   moved project URLs to `calvinnwq/artshelf`, and prepared public npm publishing.
 - Added a user-level ledger registry plus `--all` review commands so Artshelf can
@@ -117,6 +132,24 @@
 - Moved `artshelf put` registry-warning output from stdout to stderr in human
   mode; `--json` output is unchanged (NGX-429).
 
+## [0.14.0](https://github.com/calvinnwq/artshelf/compare/v0.13.1...v0.14.0) (2026-06-19)
+
+
+### Features
+
+* **commands:** add approval-gated registry pruning ([beaaca8](https://github.com/calvinnwq/artshelf/commit/beaaca84b6d0c62e66f4438ecf9323f482fcdba4))
+* **ledgers:** Implemented the approval-gated `artshelf ledgers prune --dry-run` registry-prune planning slice of NGX-481 — new domain module, command wiring with human/JSON/agent output carrying the exact approval target, help text, and 12 focused tests — with all verification gates passing. ([6d2de1f](https://github.com/calvinnwq/artshelf/commit/6d2de1fe2390785aa9e0ffa2b009e318e350e06e))
+* **ledgers:** Implemented the approval-gated `artshelf ledgers prune --execute --plan-id` slice of NGX-481 — plan-id-bound registry mutation with a pre-mutation rollback copy, post-mutation receipt with verification, and stale/duplicate/mismatch refusals — with 10 new tests and all five verification gates passing. ([11e03db](https://github.com/calvinnwq/artshelf/commit/11e03dbde7c5e4e933f241548bd8f88d316ae5a4))
+* **ledgers:** Wired doctor, status --all, and review --all to point users at the approval-gated `artshelf ledgers prune --dry-run` flow when the registry has stale (missing-file) registrations, completing the last NGX-481 scope bullet with 4 focused tests and all five verification gates passing. ([66cd791](https://github.com/calvinnwq/artshelf/commit/66cd791dae2a6f5b60ab506a4f4e2be8358369d6))
+
+## [0.13.1](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.13.0...artshelf-v0.13.1) (2026-06-15)
+
+
+### Bug Fixes
+
+* **cleanup:** make cleanup --execute resumable after interruption ([d0188f7](https://github.com/calvinnwq/artshelf/commit/d0188f73a62b1ff2d173e26c61c826a67bbc9542))
+* **cleanup:** make cleanup execution resumable ([7ec0ebe](https://github.com/calvinnwq/artshelf/commit/7ec0ebe113f589ccd00ed0fdd1a54034afc242ec))
+
 ## [0.13.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.12.0...artshelf-v0.13.0) (2026-06-15)
 
 

package/README.md

@@ -113,12 +113,14 @@ destructive deletion.
 - **No fresh-plan-then-execute shortcut** — review the plan, then run that plan.
 - **Trash before delete** — `cleanup=delete` stays refused; physical deletion
   needs its own reviewed trash purge. No silent deletion, ever.
-- **Durable, concurrency-safe writes** — ledger and registry mutations take a
-  cross-process lock and commit atomically, so overlapping commands never lose
-  records or leave a half-written ledger.
+- **Durable, resumable cleanup** — execution writes a started receipt before
+  moving files, can replay the same plan id after interruption, and ledger and
+  registry mutations take a cross-process lock so overlapping commands never
+  lose records or leave a half-written ledger.
 - **`--json` on every command**, so agents can act on structured output.
-- **`--agent` on `review`/`status`/`doctor`**, a compact, token-efficient
-  decision packet for agents, while the default render stays human-scannable.
+- **`--agent` on `review`/`status`/`doctor` and `ledgers prune --dry-run`**, a
+  compact, token-efficient decision packet for agents, while the default render
+  stays human-scannable.
 
 ## Reference
 
@@ -129,6 +131,8 @@ destructive deletion.
 artshelf put <path> --reason "debug parser output" --ttl 3d --kind scratch
 artshelf ledgers list [--plain] [--json]
 artshelf ledgers add --ledger <path> [--name <project>] [--scope repo|user|other] [--json]
+artshelf ledgers prune --dry-run [--registry <path>] [--json|--agent]
+artshelf ledgers prune --execute --plan-id <id> [--registry <path>] [--json]
 artshelf list [--all] [--status active]
 artshelf find --path <path> --owner <agent-or-runtime> --label <task-or-run-id>
 artshelf find --all --owner <agent-or-runtime>
@@ -151,8 +155,9 @@ artshelf resolve <id> --status resolved --reason "inspected and no longer needed
 
 Use `artshelf help` for a grouped command list, then `artshelf <command> --help`
 or `artshelf help <command>` for focused details. Nested commands such as
-`artshelf trash purge --help` and `artshelf ledgers add --help` show only that
-subcommand. All core commands support `--json`; `review`, `status`, and `doctor`
+`artshelf trash purge --help`, `artshelf ledgers add --help`, and
+`artshelf ledgers prune --help` show only that subcommand. All core commands
+support `--json`; `review`, `status`, `doctor`, and `ledgers prune --dry-run`
 also take `--agent` for a compact decision packet; `--ledger`, `--registry`, and
 `--all` are scope flags only on commands that list them.
 </details>
@@ -175,7 +180,11 @@ Artshelf keeps a small global registry of known ledgers at
 existing one with `artshelf ledgers add --ledger <path> --name <project> --json`.
 `artshelf ledgers list` validates each registered ledger by default (ok/missing/invalid
 status with counts, non-zero exit when broken), so it doubles as a stale-entry
-check; add `--plain` to skip validation.
+check; add `--plain` to skip validation. When registered ledger files are
+missing, use `artshelf ledgers prune --dry-run --registry <path>` to write a
+reviewed registry-prune plan, approve `approve artshelf ledgers prune registry
+<registry-path> plan <plan-id>`, then execute that exact plan id; duplicate paths
+are blocked for manual repair and are never pruned automatically.
 
 Use `--all` for one read-only discovery entry point across registered ledgers
 (`review`, `status`, `due`, `trash list`, `find`). `artshelf cleanup --dry-run --all`

package/SPEC.md

@@ -56,8 +56,8 @@ Rules:
 - Command groups are `Create`, `Inspect`, `Review`, `Clean`, and `System`.
 - `artshelf <command> --help` and `artshelf help <command>` show focused help
   for that command.
-- Nested help is supported for `trash list`, `trash purge`, `ledgers list`, and
-  `ledgers add`.
+- Nested help is supported for `trash list`, `trash purge`, `ledgers list`,
+  `ledgers add`, and `ledgers prune`.
 - `artshelf trash help` and `artshelf ledgers help` are aliases for the focused
   help of those commands, matching `artshelf help trash` and `artshelf help ledgers`.
 - Top-level help presents `-h, --help` and `-v, --version` as global options,
@@ -105,13 +105,16 @@ printed to stderr in human mode, or surfaced as a `registryError` field in
 
 ### `artshelf ledgers`
 
-Lists or registers known Artshelf ledgers.
+Lists, registers, or prunes known Artshelf ledger registrations.
 
 ```bash
 artshelf ledgers list
 artshelf ledgers list --json
 artshelf ledgers list --plain
 artshelf ledgers add --ledger <path> --name <project> --scope repo --json
+artshelf ledgers prune --dry-run --registry <path> --json
+artshelf ledgers prune --dry-run --registry <path> --agent
+artshelf ledgers prune --execute --plan-id <id> --registry <path> --json
 ```
 
 Rules:
@@ -125,6 +128,19 @@ Rules:
   them; it does not validate and exits zero whenever the registry itself is
   readable.
 - `add` requires an existing ledger path.
+- `prune --dry-run` classifies registry entries whose ledger files are missing,
+  writes a reviewed registry-prune plan only when prunable entries exist, and
+  never mutates the registry. Repeated matching dry-runs reuse the same
+  unexecuted plan id. Duplicate registry paths are ambiguous and are reported as
+  blocked for manual repair, never pruned automatically.
+- `prune --dry-run --agent` emits a compact single-line packet with the prunable
+  count, blocked count, plan id, and exact approval target:
+  `approve artshelf ledgers prune registry <registry-path> plan <plan-id>`.
+- `prune --execute --plan-id <id>` binds to one exact registry path and reviewed
+  plan id. It re-checks the live registry, removes only entries still classified
+  as prunable, skips stale plan entries whose file reappeared or became
+  ambiguous, writes a rollback copy before mutation, writes a receipt after, and
+  exits non-zero if verification fails.
 - `--name` defaults from the ledger path when omitted.
 - `--scope` is optional; when omitted, Artshelf infers `repo`, `user`, or
   `other` from the ledger path.
@@ -259,22 +275,27 @@ counts plus the preview plan ids; JSON also includes the next safe action. The
 per-ledger human detail appends a `reconcile` count when a ledger has reconcile
 drift. Human output adds a one-line triage count with the same reconcile counts
 and states the same next safe action (repair broken ledgers, dry-run cleanup,
-dry-run reconcile for missing-path or reconcile drift, or nothing to do). Review
-never writes a plan, so
-the next action always points at an explicit follow-up command.
-
-`review`, `status`, and `doctor` share three render modes. The default human
-render leads each ledger and summary line with a `✓`/`⚠` attention glyph; `--json`
-stays the full, backward-compatible public audit report; and `--agent` emits a compact,
+registry-prune dry-run for missing registered ledgers, dry-run reconcile for
+missing-path or reconcile drift, or nothing to do). Review never writes a plan,
+so the next action always points at an explicit follow-up command.
+
+`review`, `status`, `doctor`, and `ledgers prune --dry-run` expose
+agent-oriented render modes. For review/status/doctor, the default human render
+leads each ledger and summary line with a `✓`/`⚠` attention glyph. `--json` stays
+the full, backward-compatible public audit report; and `--agent` emits a compact,
 deterministic single-line JSON decision packet for agents, taking precedence over
 `--json` when both are passed. For `review`, the packet sorts records into
 ready-for-approval, needs-review-first, and blocked groups. Because review is
-read-only and never mints a cleanup plan, the exact approval targets it emits are
-`resolve missing` and `reconcile`; the `reconcile` target appears only when a
-prior reviewed reconcile plan still matches the live drift. Cleanup-eligible
-records and reconcile drift without a reviewed plan stay needs-review-first and
-point at `cleanup --dry-run` or `reconcile --dry-run`, which mint the reviewed
-plan id to approve. Blocked or ambiguous reconcile findings surface in the
+read-only and never mints a cleanup or registry-prune plan, the exact approval
+targets it emits are `resolve missing` and `reconcile`; the `reconcile` target
+appears only when a prior reviewed reconcile plan still matches the live drift.
+Cleanup-eligible records and reconcile drift without a reviewed plan stay
+needs-review-first and point at `cleanup --dry-run` or `reconcile --dry-run`,
+which mint the reviewed plan id to approve. Missing registered ledger files in
+`--all` mode surface as blocked registry fixes that point at `ledgers prune
+--dry-run --registry <path>`; the prune dry-run produces the registry-prune
+approval target. Invalid-but-present ledger files still point at manual
+re-register/fix work. Blocked or ambiguous reconcile findings surface in the
 blocked group with no approval target.
 
 ### `artshelf doctor`
@@ -302,10 +323,13 @@ Doctor reports:
   physical trash purge requires a separate reviewed purge plan.
 
 A healthy machine exits 0. A broken registry file or any stale or invalid
-registered ledger exits non-zero with actionable errors. Humans should run
-`artshelf doctor` after install or when `--all` commands behave unexpectedly; agents
-may run it on a schedule to catch stale registry entries before relying on
-cleanup planning. Doctor never creates plans, receipts, or records. Like `review`
+registered ledger exits non-zero with actionable errors. When stale/missing
+registrations exist, the agent next action points at `artshelf ledgers prune
+--dry-run --registry <path>` before re-running doctor; invalid ledger files still
+need manual repair. Humans should run `artshelf doctor` after install or when
+`--all` commands behave unexpectedly; agents may run it on a schedule to catch
+stale registry entries before relying on cleanup planning. Doctor never creates
+plans, receipts, or records. Like `review`
 and `status`, `doctor` accepts `--agent` for a compact single-line JSON decision
 packet (health, registry and registered-ledger health, blockers, cleanup-safety
 posture, next action, and a verify command); `--agent` takes precedence over
@@ -337,9 +361,12 @@ Status reports:
 output is short enough to paste into a chat. Status is strictly read-only: it
 never creates plans or receipts and never mutates records. A healthy machine
 exits 0. In `--all` mode, a broken registry or any stale or invalid registered
-ledger exits non-zero. Due entries are normal operational state and do not change
-the exit code. With single `--ledger`, a not-yet-created ledger reports empty
-counts. Like `review` and `doctor`, `status` accepts `--agent` for a compact
+ledger exits non-zero. When stale/missing registrations exist, `--all --agent`
+points at `artshelf ledgers prune --dry-run --registry <path>` before re-running
+status; invalid ledgers are still manual repair. Due entries are normal
+operational state and do not change the exit code. With single `--ledger`, a
+not-yet-created ledger reports empty counts. Like `review` and `doctor`,
+`status` accepts `--agent` for a compact
 single-line JSON decision packet (health, counts, attention categories, blockers,
 next action, and a verify command); `--agent` takes precedence over `--json`.
 
@@ -440,10 +467,19 @@ Rules:
   ledger, and its entries must be well-formed. A mismatched or malformed plan is
   refused without moving files or writing a receipt, mirroring the live-record
   re-checks `trash purge --execute` performs.
-- Writes a cleanup receipt and appends or refreshes an Artshelf-owned ledger record
-  for that receipt with `owner=artshelf`, `kind=run-artifact`, `ttl=30d`,
-  `cleanup=review`, and labels including `artshelf`, `cleanup-receipt`, and the
-  plan id.
+- Writes a `started` cleanup receipt to `<ledger-dir>/receipts/<plan-id>.json` before
+  the first filesystem move, then completes the receipt with `completedAt` and the
+  per-entry `trashed`, `review-required`, `refused`, or `skipped` results.
+- Appends or refreshes an Artshelf-owned ledger record for the completed receipt with
+  `owner=artshelf`, `kind=run-artifact`, `ttl=30d`, `cleanup=review`, and labels
+  including `artshelf`, `cleanup-receipt`, and the plan id.
+- Resumes an interrupted run on rerun of the same plan id: terminal receipt evidence
+  for an artifact keeps its original `executedAt`/`cleanedAt`, an artifact already
+  moved into the plan's trash directory without terminal receipt evidence is recorded
+  as `trashed` at resume time without moving it again, a missing original path with no
+  trash target and no receipt evidence stays a skipped missing path rather than a
+  success, and a completed receipt replays idempotently without duplicating the
+  Artshelf-owned receipt record.
 - Updates touched ledger records so handled artifacts stop appearing as active
   cleanup candidates.
 - Uses trash/review behavior by default.
@@ -653,8 +689,11 @@ V1 also supports a user-level registry of known ledgers:
 - `--all` reads registered ledgers as one review surface.
 - `trash list --all` reads trashed records across registered ledgers after
   registry validation.
-- `cleanup --execute --all` and `trash purge --all` are refused; execution stays
-  scoped to one explicit ledger and one reviewed plan id.
+- Registry-prune artifacts live next to the registry: `registry-prune-plans/`,
+  `registry-prune-rollbacks/`, and `registry-prune-receipts/`.
+- `cleanup --execute --all`, `reconcile --execute --all`, and `trash purge --all`
+  are refused; execution stays scoped to one explicit ledger or registry and one
+  reviewed plan id.
 
 ## Ledger Registry Schema
 
@@ -829,11 +868,15 @@ Operational rules that back those boundaries:
 - Dry-run first.
 - Execute only by plan id.
 - Trash/review before delete.
-- Execute updates ledger state after writing the cleanup receipt. A trashed,
-  review-required, or refused record no longer participates in future `due` or
-  cleanup dry-run output by default.
-- Missing paths update the report; they are not treated as a successful cleanup
-  unless the user explicitly repairs the ledger later.
+- Execute writes a `started` cleanup receipt before the first filesystem move,
+  updates ledger state after recording per-entry outcomes, and completes the
+  receipt with `completedAt`. A trashed, review-required, or refused record no
+  longer participates in future `due` or cleanup dry-run output by default.
+- Rerunning the same plan id resumes or replays durable receipt/trash evidence:
+  terminal receipt evidence keeps its original cleanup timestamp, existing
+  plan-trash targets are not moved again, completed receipts are idempotent,
+  and missing paths without receipt or trash evidence stay skipped rather than
+  successful.
 - Cleanup never scans arbitrary filesystem paths for deletion in v1.
 - Cleanup only acts on ledger entries.
 - Trash purge is scoped to one ledger, requires a reviewed purge plan id, and
@@ -916,9 +959,9 @@ installs. The report groups decisions into ready-for-approval,
 needs-review-first, and blocked sections, and must still include exact approval
 targets in the message body.
 
-Scheduled jobs must never run `artshelf cleanup --execute` or
-`artshelf trash purge --execute`; they may only dry-run and report plans for later
-human review.
+Scheduled jobs must never run `artshelf cleanup --execute`,
+`artshelf ledgers prune --execute`, or `artshelf trash purge --execute`; they may
+only dry-run and report plans for later human review.
 
 ## Dogfood Scenarios
 
@@ -936,6 +979,10 @@ human review.
   by default, or a `--plain` fast path that skips validation.
 - CLI can review registered ledgers through `--all` read-only entry points,
   emitting an aggregate triage summary and the next safe action.
+- CLI can prune missing/stale ledger registrations through an approval-gated
+  `artshelf ledgers prune` dry-run/execute workflow that writes a reviewed plan,
+  rollback copy, and receipt; duplicate registry paths are blocked for manual
+  repair.
 - CLI refuses records without a reason.
 - CLI requires TTL, retain-until, or manual-review.
 - CLI can list, filter by status, and show due entries.
@@ -957,7 +1004,9 @@ human review.
   creates.
 - Cleanup execute refuses to run without a plan id, and refuses an unsafe,
   mismatched, or malformed plan before moving files or writing a receipt.
-- Cleanup execute writes a receipt.
+- Cleanup execute writes a started receipt before moving files, resumes or
+  replays the same plan id from receipt/trash evidence, and completes the
+  receipt idempotently.
 - CLI can list trashed records (single ledger or `--all`) and purge them through
   an approval-first, ledger-scoped dry-run/execute boundary that writes a purge
   receipt; purge refuses `--all` and never deletes without a reviewed plan id.
@@ -975,13 +1024,14 @@ human review.
 - Package includes the deterministic `ArtshelfReviewReport` schema, canonical
   example, and portable renderer script for agent-rendered review reports.
 - All core commands support `--json`.
-- `review`, `status`, and `doctor` also support `--agent`, a compact single-line
-  JSON decision packet for agents that takes precedence over `--json`.
+- `review`, `status`, `doctor`, and `ledgers prune --dry-run` also support
+  `--agent`, a compact single-line JSON decision packet for agents that takes
+  precedence over `--json`.
 - Tests cover record/list/find/get/status-filter/due/validate/resolve/registry,
   `artshelf doctor`, the `artshelf status` dashboard, `--all` review, stale-registry,
   dry-run, global-dry-run, execute-plan, cleanup plan-id validation, concurrent
-  ledger writes, trash list/purge, path provenance validation, and reconcile
-  dry-run/execute behavior.
+  ledger writes, trash list/purge, path provenance validation, registry-prune,
+  and reconcile dry-run/execute behavior.
 
 ## Deferred
 

package/dist/src/commands/ledgers.js

@@ -1,7 +1,8 @@
 import { existsSync } from "node:fs";
 import { normalizeLedgerPath } from "../ledger.js";
 import { listRegisteredLedgers, normalizeRegistryPath, registerLedger } from "../registry.js";
-import { printJson } from "../renderers/json.js";
+import { createRegistryPrunePlan, executeRegistryPrunePlan } from "../registry-prune.js";
+import { printCompactJson, printJson } from "../renderers/json.js";
 import { boolFlag, requiredStringFlag, stringFlag } from "../shared/flags.js";
 import { LEDGERS_HELP } from "../shared/help-text.js";
 import { validateRegisteredLedger } from "./shared.js";
@@ -49,8 +50,94 @@ export function handleLedgers(parsed, json) {
         printLedgersList(report);
         return report.ok ? 0 : 1;
     }
+    if (action === "prune") {
+        return handleLedgersPrune(parsed, registryPath, json);
+    }
     throw new Error(`Unknown ledgers action: ${action}`);
 }
+// Approval-gated registry prune (NGX-481). Dry-run is read-only except for writing a
+// reviewed plan when missing registrations are detected; it never mutates the registry.
+// Execute binds to one exact registry path and reviewed plan id, copies a rollback
+// snapshot before mutating, and writes a receipt after.
+function handleLedgersPrune(parsed, registryPath, json) {
+    const dryRun = boolFlag(parsed, "dry-run");
+    const execute = boolFlag(parsed, "execute");
+    if (dryRun && execute)
+        throw new Error("ledgers prune accepts either --dry-run or --execute, not both");
+    if (execute)
+        return handleLedgersPruneExecute(parsed, registryPath, json);
+    if (!dryRun)
+        throw new Error("ledgers prune requires --dry-run or --execute");
+    const plan = createRegistryPrunePlan(registryPath);
+    const approve = plan.planId === "not-created" ? null : pruneApprovalTarget(registryPath, plan.planId);
+    if (boolFlag(parsed, "agent")) {
+        return printCompactJson({
+            ok: true,
+            command: "ledgers-prune",
+            registryPath,
+            prunable: plan.entries.length,
+            blocked: plan.skipped.length,
+            planId: plan.planId === "not-created" ? null : plan.planId,
+            approve
+        });
+    }
+    if (json)
+        return printJson({ ok: true, registryPath, plan, approve });
+    printRegistryPrunePlan(plan, registryPath, approve);
+    return 0;
+}
+// Execute one reviewed registry-prune plan. The plan id is required up front (refusing
+// `--execute` without it), then the domain layer re-checks the live registry, takes a
+// rollback copy, removes only entries still classified as prunable, and writes a
+// receipt. Exit is non-zero when post-mutation verification fails.
+function handleLedgersPruneExecute(parsed, registryPath, json) {
+    const planId = stringFlag(parsed, "plan-id");
+    if (!planId) {
+        throw new Error("ledgers prune --execute requires --plan-id <id>; run `artshelf ledgers prune --dry-run` first to review a plan");
+    }
+    const receipt = executeRegistryPrunePlan(registryPath, planId);
+    if (json) {
+        printJson({ ok: receipt.verification.ok, registryPath, receipt });
+        return receipt.verification.ok ? 0 : 1;
+    }
+    printRegistryPruneReceipt(receipt);
+    return receipt.verification.ok ? 0 : 1;
+}
+function pruneApprovalTarget(registryPath, planId) {
+    return `approve artshelf ledgers prune registry ${registryPath} plan ${planId}`;
+}
+function printRegistryPruneReceipt(receipt) {
+    process.stdout.write(`artshelf ledgers prune --execute: removed ${receipt.removed.length}, skipped ${receipt.skipped.length}\nregistry: ${receipt.registryPath}\n`);
+    for (const entry of receipt.removed) {
+        process.stdout.write(`[${entry.name}] removed ${entry.scope} — ${entry.path}\n`);
+    }
+    for (const entry of receipt.skipped) {
+        process.stdout.write(`[${entry.name}] skipped ${entry.scope}: live registry no longer matches the reviewed plan — ${entry.path}\n`);
+    }
+    if (receipt.rollbackPath)
+        process.stdout.write(`rollback: ${receipt.rollbackPath}\n`);
+    process.stdout.write(`receipt: ${receipt.receiptPath}\n`);
+    process.stdout.write(`verification: ${receipt.verification.ok ? "ok" : "failed"} — ${receipt.verification.detail}\n`);
+}
+function printRegistryPrunePlan(plan, registryPath, approve) {
+    if (plan.entries.length === 0) {
+        process.stdout.write(`artshelf ledgers prune: nothing to prune\nregistry: ${registryPath}\n`);
+        for (const entry of plan.skipped) {
+            process.stdout.write(`[${entry.name}] blocked ${entry.scope}: ${entry.reason} — ${entry.path}\n`);
+        }
+        return;
+    }
+    process.stdout.write(`artshelf ledgers prune: ${plan.entries.length} prunable, ${plan.skipped.length} blocked\nregistry: ${registryPath}\n`);
+    for (const entry of plan.entries) {
+        process.stdout.write(`[${entry.name}] prune ${entry.scope}: ${entry.reason} — ${entry.path}\n`);
+    }
+    for (const entry of plan.skipped) {
+        process.stdout.write(`[${entry.name}] blocked ${entry.scope}: ${entry.reason} — ${entry.path}\n`);
+    }
+    process.stdout.write(`plan: ${plan.planPath ?? "not created"}\n`);
+    if (approve)
+        process.stdout.write(`approve: ${approve}\n`);
+}
 function buildLedgersReport(registryPath) {
     let registryOk = true;
     let registryError = null;