artshelf 0.13.1 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- Added read-only `artshelf get <id> --inspect` decision cards with human,
+  `--json`, and `--agent` render modes, including registry-wide `--all` lookup,
+  metadata-only existence/size reporting, recommendation buckets, and exact
+  next-safe actions without reading file contents or mutating ledgers.
+- 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
@@ -126,6 +136,25 @@
 - Moved `artshelf put` registry-warning output from stdout to stderr in human
   mode; `--json` output is unchanged (NGX-429).
 
+## [0.15.0](https://github.com/calvinnwq/artshelf/compare/v0.14.0...v0.15.0) (2026-06-20)
+
+
+### Features
+
+* **inspect:** add read-only Artshelf review cards ([08478a8](https://github.com/calvinnwq/artshelf/commit/08478a871f624b048173a986511cc57cf2a2e609))
+* **inspect:** add read-only inspect decision model ([334ea7d](https://github.com/calvinnwq/artshelf/commit/334ea7de99326ed0b0c3129228beaa0d33f378b9))
+* **inspect:** wire get inspect output modes ([4a7270d](https://github.com/calvinnwq/artshelf/commit/4a7270df29f1895efe9032b2cfb7a2c1d47e971f))
+
+## [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)
 
 

package/README.md

@@ -118,8 +118,9 @@ destructive deletion.
   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`, `ledgers prune --dry-run`, and
+  `get --inspect`**, a compact, token-efficient decision packet for agents,
+  while the default render stays human-scannable.
 
 ## Reference
 
@@ -130,10 +131,14 @@ 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>
 artshelf get <id> [--all]
+artshelf get <id> --inspect [--ledger <path>] [--json|--agent]
+artshelf get <id> --inspect --all [--registry <path>] [--json|--agent]
 artshelf due [--all]
 artshelf validate [--all]
 artshelf review [--all]
@@ -152,10 +157,11 @@ 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`
-also take `--agent` for a compact decision packet; `--ledger`, `--registry`, and
-`--all` are scope flags only on commands that list them.
+`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`, `ledgers prune --dry-run`, and
+`get --inspect` also take `--agent` for a compact decision packet; `--ledger`,
+`--registry`, and `--all` are scope flags only on commands that list them.
 </details>
 
 <details>
@@ -176,7 +182,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.
@@ -183,10 +199,56 @@ Read-only lookup of a single ledger record by Artshelf id.
 artshelf get <id>
 artshelf get <id> --json
 artshelf get <id> --all --json
+artshelf get <id> --inspect
+artshelf get <id> --inspect --json
+artshelf get <id> --inspect --agent
+artshelf get <id> --inspect --all --registry <path> --agent
 ```
 
 `get` is for audit and handoff follow-up. Missing ids are an error. `--all`
-searches registered ledgers until the id is found.
+searches registered ledgers until the id is found. With `--inspect --all`, the
+registry is only used for lookup; the decision card reports the concrete ledger
+that owns the matching record.
+
+`--inspect` turns a record into a review decision card. It never moves files or
+mutates the ledger; it only reports existence, node kind, size, age, retention/due and
+manual-review state, cleanup mode, reason, and a recommendation bucket with the
+exact next-safe action. It never reads or previews arbitrary file contents:
+
+- `keep` — held for manual review, already resolved, already trashed, or due
+  with `cleanup=review`; it needs your judgment but nothing auto-runs.
+- `snooze` — retention has not expired yet; re-inspect after it is due.
+- `trash-safe` — due with `cleanup=trash`; safe to plan a reviewed cleanup.
+- `resolve-only` — the recorded path is gone; resolve the record (ledger-only)
+  rather than cleaning a file.
+- `blocked` — needs a human decision first: `cleanup=delete` (refused at
+  execute), a review-required flag, or a prior cleanup refusal.
+
+File-content previews are intentionally outside Artshelf core; an acting agent or
+host runtime may inspect file contents separately when appropriate.
+`--inspect --json` returns `{ inspect: <report> }`; `--inspect --agent` returns a compact single-line
+decision packet with a read-only safety block, the next-safe action, and a
+reproducer command, and takes precedence over `--json`. Both shapes are
+deterministic so portable agent skills can act without re-deriving anything.
+
+Example pattern — the dogfooding case that motivated this surface was an old
+rollback `backup` registered with `cleanup=review` (the kind of stale record
+`ledgers prune` and `review --all` surface). Inspect it before deciding, using
+the record id and ledger path rather than hardcoding either:
+
+```bash
+artshelf get <id> --inspect --ledger <ledger-path>
+```
+
+```text
+✓ <id> [backup] — keep
+path: <backup-path>
+status: active · cleanup: review · owner: agent · labels: registry-prune
+existence: present (directory, 49 B) · age: 14d · retention: manual-review · due: manual-review
+reason: rollback backup before registry prune
+next: Held for manual review — keep it, change its retention, or resolve it explicitly; no cleanup is scheduled.
+ledger: <ledger-path>
+```
 
 ### `artshelf due`
 
@@ -259,22 +321,28 @@ 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`, `ledgers prune --dry-run`, and `get --inspect`
+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
+`--json` when both are passed. For `get --inspect`, `--agent` returns the
+per-record decision packet and requires `--inspect`. 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 +370,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 +408,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`.
 
@@ -662,8 +736,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
 
@@ -929,9 +1006,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
 
@@ -949,6 +1026,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.
@@ -990,13 +1071,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`, `ledgers prune --dry-run`, and `get --inspect`
+  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/cli.js

@@ -2,7 +2,7 @@
 import { maybeNotifyAvailableUpdate, runCommand } from "./commands/index.js";
 import { VERSION } from "./config/package.js";
 import { formatCliError } from "./shared/errors.js";
-import { BOOLEAN_FLAGS, boolFlag, VALUE_FLAGS } from "./shared/flags.js";
+import { boolFlag, isBooleanFlag, VALUE_FLAGS } from "./shared/flags.js";
 import { renderHelp, resolveHelpKey } from "./shared/help-text.js";
 async function main(argv) {
     try {
@@ -53,7 +53,7 @@ function parseArgs(argv) {
         }
         if (token.startsWith("--")) {
             const name = token.slice(2);
-            if (BOOLEAN_FLAGS.has(name)) {
+            if (isBooleanFlag(name, command)) {
                 flags.set(name, true);
                 continue;
             }

package/dist/src/commands/get.js

@@ -1,20 +1,28 @@
+import { buildInspectReport } from "../inspect.js";
 import { getRecord, readLedger } from "../ledger.js";
 import { normalizeRegistryPath } from "../registry.js";
-import { printJson } from "../renderers/json.js";
+import { buildInspectAgentPacket, printInspect } from "../renderers/inspect.js";
+import { printCompactJson, printJson } from "../renderers/json.js";
 import { boolFlag, stringFlag } from "../shared/flags.js";
 import { printRegisteredLedgerValidation, validateRegisteredLedgersOrThrow } from "./shared.js";
 export function handleGet(parsed, ledgerPath, json) {
     const id = parsed.positionals[0];
     if (!id)
         throw new Error("get requires <id>");
+    const inspect = boolFlag(parsed, "inspect");
+    const agent = boolFlag(parsed, "agent");
+    if (agent && !inspect)
+        throw new Error("--agent requires --inspect for get");
     if (boolFlag(parsed, "all")) {
         const registryPath = normalizeRegistryPath(stringFlag(parsed, "registry"));
         const validation = validateRegisteredLedgersOrThrow(registryPath);
         if (!validation.ok)
-            return printRegisteredLedgerValidation(registryPath, validation.results, json);
+            return printRegisteredLedgerValidation(registryPath, validation.results, json || agent);
         for (const { ledger } of validation.results) {
             const record = readLedger(ledger.path).find((entry) => entry.id === id);
             if (record) {
+                if (inspect)
+                    return renderInspect(record, ledger.path, json, agent);
                 if (json)
                     return printJson({ ok: true, registryPath, ledger, record });
                 process.stdout.write(`${record.id} ${record.kind} ${record.status} ${record.cleanup} ${record.path}\nreason: ${record.reason}\nledger: ${ledger.path}\nregistry: ${registryPath}\n`);
@@ -24,8 +32,22 @@ export function handleGet(parsed, ledgerPath, json) {
         throw new Error(`Artshelf record not found: ${id}`);
     }
     const record = getRecord(readLedger(ledgerPath), id);
+    if (inspect)
+        return renderInspect(record, ledgerPath, json, agent);
     if (json)
         return printJson({ ok: true, ledgerPath, record });
     process.stdout.write(`${record.id} ${record.kind} ${record.status} ${record.cleanup} ${record.path}\nreason: ${record.reason}\nledger: ${ledgerPath}\n`);
     return 0;
 }
+// Read-only inspect surface (NGX-482): builds a deterministic decision report and
+// renders it as a human card, full JSON, or a compact agent packet. --agent wins
+// over --json, matching `review`. Never mutates the ledger or the filesystem.
+function renderInspect(record, ledgerPath, json, agent) {
+    const report = buildInspectReport(record, { ledgerPath });
+    if (agent)
+        return printCompactJson(buildInspectAgentPacket(report, ledgerPath));
+    if (json)
+        return printJson({ ok: true, ledgerPath, inspect: report });
+    printInspect(report, ledgerPath);
+    return 0;
+}

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;