artshelf 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## 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
@@ -126,6 +132,16 @@
 - 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)
 
 

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` and `ledgers prune --dry-run`**, a
+  compact, token-efficient decision packet for agents, while the default render
+  stays human-scannable.
 
 ## Reference
 
@@ -130,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>
@@ -152,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>
@@ -176,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`.
 
@@ -662,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
 
@@ -929,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
 
@@ -949,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.
@@ -990,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;

package/dist/src/registry-prune.js

@@ -0,0 +1,259 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { assertSafeGeneratedId } from "./ledger.js";
+import { withPathLock } from "./locks.js";
+import { listRegisteredLedgers, normalizeRegistryPath, removeRegisteredLedgers } from "./registry.js";
+import { now, toIso } from "./time.js";
+// Classify the registry into prune findings (read-only). A registration is prunable
+// when its ledger file is missing — the same "missing/stale" signal `ledgers list`
+// reports via existence of the ledger path. Registrations whose resolved path appears
+// more than once are ambiguous: pruning one would silently drop a sibling, so they are
+// blocked for manual resolution instead of pruned. Present ledger files yield nothing.
+export function classifyRegistryPruneFindings(registryPath) {
+    const entries = listRegisteredLedgers(normalizeRegistryPath(registryPath));
+    const pathCounts = new Map();
+    for (const entry of entries) {
+        pathCounts.set(entry.path, (pathCounts.get(entry.path) ?? 0) + 1);
+    }
+    const findings = [];
+    for (const entry of entries) {
+        if ((pathCounts.get(entry.path) ?? 0) > 1) {
+            findings.push(finding(entry, "blocked", "ambiguous duplicate registry path; resolve manually before pruning"));
+            continue;
+        }
+        if (existsSync(entry.path))
+            continue;
+        findings.push(finding(entry, "prune", "registered ledger file is missing"));
+    }
+    return findings;
+}
+// Build the registry-prune plan without persisting anything (dry-run preview). Fully
+// read-only: it classifies the registry and returns the plan a `--dry-run` would
+// create, but never writes a plan file or mutates the registry. A plan with no
+// actionable entries collapses to the not-created shape so callers can render
+// "nothing to prune" the same way cleanup and reconcile do.
+export function previewRegistryPrunePlan(registryPath) {
+    const plan = buildRegistryPrunePlan(normalizeRegistryPath(registryPath));
+    return plan.entries.length === 0 ? noCreatedRegistryPrunePlan(plan) : plan;
+}
+// Create (or reuse) a reviewed registry-prune plan (dry-run). This is the only part of
+// dry-run that writes, and it only writes the plan file — never the registry. When an
+// earlier plan already covers the same prunable entries it is reused verbatim (stable
+// plan id), and when nothing is actionable no plan artifact is created at all, keeping
+// dry-run side-effect-free in that case. The plan file lives next to the registry under
+// `registry-prune-plans/` so a later `--execute` can discover it by exact plan id.
+export function createRegistryPrunePlan(registryPath) {
+    const normalized = normalizeRegistryPath(registryPath);
+    const plan = buildRegistryPrunePlan(normalized);
+    if (plan.entries.length === 0)
+        return noCreatedRegistryPrunePlan(plan);
+    const existing = matchingExistingRegistryPrunePlan(normalized, plan);
+    const reviewed = existing ? { ...plan, planId: existing.planId, planPath: existing.planPath } : plan;
+    if (!reviewed.planPath)
+        throw new Error("registry prune plan path was not created");
+    writeRegistryPrunePlanFile(reviewed.planPath, reviewed);
+    return reviewed;
+}
+// Apply a reviewed registry-prune plan (NGX-481 `ledgers prune --execute`). This is the
+// only mutating registry-prune entrypoint and it is deliberately conservative:
+//   * It refuses up front when the plan id is missing, the registry is absent, the plan
+//     file is absent, or the plan file's declared id/registry does not match the scoped
+//     request (no fresh plan, no `--all`; it binds to one exact reviewed plan id against
+//     one exact registry path).
+//   * Inside one registry lock it re-classifies the live registry and only removes a
+//     planned entry that still classifies as prunable; entries whose ledger file
+//     reappeared or whose path became an ambiguous duplicate are skipped, not removed.
+//   * It writes a rollback copy of the registry before mutating and a receipt after,
+//     then verifies the removed registrations are actually gone.
+export function executeRegistryPrunePlan(registryPath, planId) {
+    if (!planId)
+        throw new Error("ledgers prune --execute requires --plan-id");
+    const normalized = normalizeRegistryPath(registryPath);
+    if (!existsSync(normalized))
+        throw new Error(`Registry not found: ${normalized}`);
+    const planPath = registryPrunePlanPath(normalized, planId);
+    if (!existsSync(planPath))
+        throw new Error(`Registry prune plan not found: ${planId}`);
+    const plan = JSON.parse(readFileSync(planPath, "utf8"));
+    assertRegistryPrunePlanExecutable(plan, planId, normalized);
+    const receiptPath = registryPruneReceiptPath(normalized, planId);
+    const rollbackPath = registryPruneRollbackPath(normalized, planId);
+    return withPathLock(normalized, () => {
+        const existingReceipt = readExistingRegistryPruneReceipt(receiptPath, planId, normalized);
+        if (existingReceipt)
+            return existingReceipt;
+        const liveByKey = new Map(classifyRegistryPruneFindings(normalized).map((item) => [pruneKey(item.name, item.path), item]));
+        const removable = [];
+        const skipped = [];
+        for (const entry of plan.entries) {
+            if (liveByKey.get(pruneKey(entry.name, entry.path))?.status === "prune")
+                removable.push(entry);
+            else
+                skipped.push(removal(entry.name, entry.path, entry.scope));
+        }
+        let removedEntries = [];
+        const receiptRollbackPath = removable.length > 0 ? rollbackPath : null;
+        if (removable.length > 0) {
+            copyRegistrySnapshot(normalized, rollbackPath);
+            removedEntries = removeRegisteredLedgers(normalized, removable.map((entry) => ({ name: entry.name, path: entry.path })));
+        }
+        const removed = removedEntries.map((entry) => removal(entry.name, entry.path, entry.scope));
+        const verification = verifyRegistryPrune(normalized, removed);
+        const receipt = {
+            planId,
+            registryPath: normalized,
+            executedAt: toIso(now()),
+            rollbackPath: receiptRollbackPath,
+            removed,
+            skipped,
+            verification,
+            receiptPath
+        };
+        writeRegistryPruneReceiptFile(receiptPath, receipt);
+        return receipt;
+    }, "Artshelf ledger registry");
+}
+function finding(entry, status, reason) {
+    return { name: entry.name, path: entry.path, scope: entry.scope, status, reason };
+}
+function buildRegistryPrunePlan(registryPath) {
+    const generatedAt = now();
+    const findings = classifyRegistryPruneFindings(registryPath);
+    const entries = findings.filter((item) => item.status === "prune").map(planEntry);
+    const skipped = findings.filter((item) => item.status === "blocked").map(planEntry);
+    const planId = makeRegistryPrunePlanId(generatedAt);
+    return {
+        planId,
+        generatedAt: toIso(generatedAt),
+        registryPath,
+        entries,
+        skipped,
+        planPath: registryPrunePlanPath(registryPath, planId)
+    };
+}
+function planEntry(item) {
+    return { name: item.name, path: item.path, scope: item.scope, reason: item.reason };
+}
+function noCreatedRegistryPrunePlan(plan) {
+    return { ...plan, planId: "not-created", planPath: null };
+}
+// Reuse an unexecuted earlier plan whose prunable entries match this one's, so repeated
+// dry-runs converge on a single stable plan id (mirrors cleanup/reconcile plan reuse).
+// Only the structural entry fields are fingerprinted; volatile fields (generatedAt) and
+// the review-only skipped list do not affect reuse.
+function matchingExistingRegistryPrunePlan(registryPath, plan) {
+    const plansDir = join(dirname(registryPath), "registry-prune-plans");
+    if (!existsSync(plansDir))
+        return null;
+    const filenames = readdirSync(plansDir).filter((name) => name.endsWith(".json")).sort().reverse();
+    for (const filename of filenames) {
+        const planPath = join(plansDir, filename);
+        try {
+            const candidate = JSON.parse(readFileSync(planPath, "utf8"));
+            if (candidate.registryPath !== registryPath)
+                continue;
+            if (registryPrunePlanFingerprint(candidate) !== registryPrunePlanFingerprint(plan))
+                continue;
+            if (existsSync(registryPruneReceiptPath(registryPath, candidate.planId)))
+                continue;
+            return { ...candidate, planPath };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function registryPrunePlanFingerprint(plan) {
+    return JSON.stringify(plan.entries.map((entry) => ({ name: entry.name, path: entry.path, scope: entry.scope })));
+}
+function writeRegistryPrunePlanFile(planPath, plan) {
+    mkdirSync(dirname(planPath), { recursive: true });
+    writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`);
+}
+function makeRegistryPrunePlanId(date) {
+    return `registry-prune_${toIso(date).replace(/[-:]/g, "").replace("T", "_").replace("Z", "")}_${randomBytes(2).toString("hex")}`;
+}
+function registryPrunePlanPath(registryPath, planId) {
+    assertSafeGeneratedId(planId, "registry prune plan id");
+    return join(dirname(registryPath), "registry-prune-plans", `${planId}.json`);
+}
+// Bind a loaded registry-prune plan to the request before any registry mutation,
+// mirroring reconcile's assertReconcilePlanExecutable: the plan must declare the
+// requested id, belong to the executing registry, and carry well-formed entries.
+function assertRegistryPrunePlanExecutable(plan, planId, registryPath) {
+    if (plan.planId !== planId) {
+        throw new Error(`Registry prune plan id mismatch: plan file declares ${plan.planId}, requested ${planId}`);
+    }
+    if (plan.registryPath !== registryPath) {
+        throw new Error(`Registry prune plan registry mismatch: plan was created for ${plan.registryPath}, executing ${registryPath}`);
+    }
+    if (!Array.isArray(plan.entries)) {
+        throw new Error(`Registry prune plan entries are malformed: ${planId}`);
+    }
+    for (const entry of plan.entries) {
+        if (!entry || typeof entry.name !== "string" || typeof entry.path !== "string") {
+            throw new Error(`Registry prune plan entries are malformed: ${planId}`);
+        }
+    }
+}
+// Re-scan the registry after mutation and confirm every removed registration is gone.
+// `ok` stays true only when none of them resurface; `remainingPrunable` counts any
+// prunable registrations left registry-wide so the receipt reflects whether the
+// registry is fully clean or other plans still have work.
+function verifyRegistryPrune(registryPath, removed) {
+    const live = classifyRegistryPruneFindings(registryPath);
+    const stillPresent = removed.filter((entry) => live.some((item) => item.name === entry.name && item.path === entry.path));
+    const remainingPrunable = live.filter((item) => item.status === "prune").length;
+    return {
+        ok: stillPresent.length === 0,
+        remainingPrunable,
+        detail: stillPresent.length === 0
+            ? "removed registrations are gone; registry re-scan is clean of them"
+            : `still registered after prune: ${stillPresent.map((entry) => entry.name).join(", ")}`
+    };
+}
+// Snapshot the registry verbatim before mutation so the receipt's rollbackPath points
+// at a restorable copy. The registry is always UTF-8 JSON, so a read/write round-trip
+// reproduces it byte-for-byte and keeps file I/O consistent with the rest of the code.
+function copyRegistrySnapshot(registryPath, rollbackPath) {
+    mkdirSync(dirname(rollbackPath), { recursive: true });
+    writeFileSync(rollbackPath, readFileSync(registryPath, "utf8"));
+}
+function readExistingRegistryPruneReceipt(receiptPath, planId, registryPath) {
+    if (!existsSync(receiptPath))
+        return null;
+    let receipt;
+    try {
+        receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+    }
+    catch {
+        throw new Error(`Registry prune receipt already exists but is unreadable: ${receiptPath}`);
+    }
+    if (receipt.planId !== planId || receipt.registryPath !== registryPath || receipt.receiptPath !== receiptPath) {
+        throw new Error(`Registry prune receipt already exists for a different execution: ${receiptPath}`);
+    }
+    if (!Array.isArray(receipt.removed) || !Array.isArray(receipt.skipped) || !receipt.verification) {
+        throw new Error(`Registry prune receipt already exists but is malformed: ${receiptPath}`);
+    }
+    return receipt;
+}
+function removal(name, path, scope) {
+    return { name, path, scope };
+}
+function pruneKey(name, path) {
+    return JSON.stringify([name, path]);
+}
+function registryPruneReceiptPath(registryPath, planId) {
+    assertSafeGeneratedId(planId, "registry prune plan id");
+    return join(dirname(registryPath), "registry-prune-receipts", `${planId}.json`);
+}
+function registryPruneRollbackPath(registryPath, planId) {
+    assertSafeGeneratedId(planId, "registry prune plan id");
+    return join(dirname(registryPath), "registry-prune-rollbacks", `${planId}.json`);
+}
+function writeRegistryPruneReceiptFile(receiptPath, receipt) {
+    mkdirSync(dirname(receiptPath), { recursive: true });
+    writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+}

package/dist/src/registry.js

@@ -51,6 +51,33 @@ export function registerLedger(input) {
         return entry;
     });
 }
+// Remove registrations matching the given (name, path) targets, returning the entries
+// actually removed. The approval-gated registry prune execute composes this under its
+// own registry lock (re-entrant), so classification, rollback copy, mutation, and
+// verification all stay inside one critical section. Matching on both name and path
+// keeps removal precise when two registrations happen to share a path. The registry is
+// only rewritten when something is actually removed, so a no-op target list is inert.
+export function removeRegisteredLedgers(registryPath, targets) {
+    const normalized = normalizeRegistryPath(registryPath);
+    return withRegistryLock(normalized, () => {
+        const registry = readRegistry(normalized);
+        const wanted = new Set(targets.map((target) => removalKey(target.name, resolve(target.path))));
+        const removed = [];
+        const kept = [];
+        for (const entry of registry.ledgers) {
+            if (wanted.has(removalKey(entry.name, entry.path)))
+                removed.push(entry);
+            else
+                kept.push(entry);
+        }
+        if (removed.length > 0)
+            writeRegistry(normalized, { version: 1, ledgers: kept });
+        return removed;
+    });
+}
+function removalKey(name, path) {
+    return JSON.stringify([name, path]);
+}
 function writeRegistry(registryPath, registry) {
     mkdirSync(dirname(registryPath), { recursive: true });
     const tmpPath = `${registryPath}.${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}.tmp`;

package/dist/src/renderers/doctor.js

@@ -5,7 +5,17 @@ function doctorAttention(summary) {
 }
 function doctorNextAction(blockers, summary, registryPath) {
     if (blockers.length > 0) {
-        return `repair ${blockers.length} registry/ledger issue(s) above, then re-run \`artshelf doctor\``;
+        const fixes = [];
+        if (summary.stale > 0) {
+            fixes.push(`run \`artshelf ledgers prune --dry-run --registry ${registryPath}\` to review removing ${summary.stale} missing/stale registration(s)`);
+        }
+        if (summary.invalid > 0) {
+            fixes.push(`repair ${summary.invalid} invalid ledger file(s) above`);
+        }
+        if (fixes.length === 0) {
+            return `repair ${blockers.length} registry/ledger issue(s) above, then re-run \`artshelf doctor\``;
+        }
+        return `${fixes.join("; ")}, then re-run \`artshelf doctor\``;
     }
     if (summary.warnings > 0) {
         return `healthy, but ${summary.warnings} warning(s) noted — run \`artshelf reconcile --dry-run --all --registry ${registryPath}\` to prepare reconcile-ready approvals, then run \`artshelf review --all --registry ${registryPath}\`; nothing is auto-executed`;

package/dist/src/renderers/review.js

@@ -11,6 +11,14 @@ export function reviewNextAction(summary, scope, ledgerPath, registryPath) {
     const broken = summary.invalid + summary.stale;
     const review = statusCommand(scope, "review", ledgerPath);
     if (broken > 0) {
+        if (scope === "all" && summary.stale > 0 && registryPath) {
+            const fixes = [
+                `run \`artshelf ledgers prune --dry-run --registry ${registryPath}\` to review removing ${summary.stale} missing/stale registration(s)`
+            ];
+            if (summary.invalid > 0)
+                fixes.push(`repair ${summary.invalid} invalid ledger(s) above (re-register or fix the file)`);
+            return `${fixes.join("; ")}, then re-run \`${review}\``;
+        }
         const repair = scope === "all" ? "re-register or fix the file" : "fix the file";
         return `repair ${broken} broken ledger(s) above (${repair}), then re-run \`${review}\``;
     }
@@ -45,7 +53,7 @@ export function printReview(results) {
         process.stdout.write(`ledger: ${result.ledger.path}\n`);
     }
 }
-function buildReviewDecisions(results, scope) {
+function buildReviewDecisions(results, scope, registryPath) {
     const readyForApproval = [];
     const needsReviewFirst = [];
     const blocked = [];
@@ -54,6 +62,20 @@ function buildReviewDecisions(results, scope) {
         const { ledger, validate, due } = result;
         if (!validate.ok) {
             const status = result.ledgerExists ? "invalid" : "missing";
+            // A missing registered ledger is repaired through the approval-gated registry-prune
+            // flow rather than hand-editing the registry; an invalid-but-present file still needs
+            // a manual re-register/fix.
+            if (scope === "all" && status === "missing" && registryPath) {
+                blocked.push({
+                    label: `Prune ${ledger.name} registration (missing)`,
+                    itemIds: [],
+                    actionType: "fix-registry",
+                    approvalTarget: null,
+                    reason: validate.errors[0] ?? "the registered ledger file is missing",
+                    nextStep: `run \`artshelf ledgers prune --dry-run --registry ${registryPath} --json\` to review removing it, then approve \`approve artshelf ledgers prune registry ${registryPath} plan <plan-id>\``
+                });
+                continue;
+            }
             const repair = scope === "all" ? `re-register or fix ${ledger.path}` : `fix ${ledger.path}`;
             blocked.push({
                 label: `Repair ${ledger.name} ledger (${status})`,
@@ -177,7 +199,7 @@ function reviewCounts(summary) {
     };
 }
 export function buildReviewAgentPacketAll(results, summary, registry) {
-    const groups = buildReviewDecisions(results, "all");
+    const groups = buildReviewDecisions(results, "all", registry.path);
     return {
         schemaVersion: 1,
         command: "review",

package/dist/src/renderers/status.js

@@ -14,9 +14,17 @@ export function statusCommand(scope, command, ledgerPath) {
         return `artshelf ${command} --all`;
     return ledgerPath ? `artshelf ${command} --ledger ${ledgerPath}` : `artshelf ${command}`;
 }
-function statusNextAction(blockers, counts, scope, ledgerPath, registryPath) {
+function statusNextAction(blockers, counts, scope, ledgerPath, registryPath, stale = 0, invalid = 0) {
     if (blockers.length > 0) {
         const verify = statusCommand(scope, "status", ledgerPath);
+        if (scope === "all" && stale > 0 && registryPath) {
+            const fixes = [
+                `run \`artshelf ledgers prune --dry-run --registry ${registryPath}\` to review removing ${stale} missing/stale registration(s)`
+            ];
+            if (invalid > 0)
+                fixes.push(`repair ${invalid} invalid ledger(s) above`);
+            return `${fixes.join("; ")}, then re-run \`${verify}\``;
+        }
         return `repair ${blockers.length} broken ledger(s) above, then re-run \`${verify}\``;
     }
     const review = statusCommand(scope, "review", ledgerPath);
@@ -59,7 +67,7 @@ export function buildStatusAgentPacketAll(report) {
         counts,
         attention: statusAttention(counts),
         blockers,
-        nextAction: statusNextAction(blockers, counts, "all", undefined, report.registryPath),
+        nextAction: statusNextAction(blockers, counts, "all", undefined, report.registryPath, report.totals.stale, report.totals.invalid),
         verification: `artshelf status --all --agent --registry ${report.registryPath}`
     };
 }

package/dist/src/shared/help-text.js

@@ -6,6 +6,7 @@ Usage:
 Available Commands:
   list      List and validate registered ledgers
   add       Register an existing ledger file
+  prune     Review and remove registrations whose ledger files are missing
 
 Flags:
   -h, --help   help for ledgers
@@ -68,7 +69,7 @@ const COMMAND_GROUPS = [
 ];
 const NESTED_HELP = new Map([
     ["trash", new Set(["list", "purge"])],
-    ["ledgers", new Set(["list", "add"])]
+    ["ledgers", new Set(["list", "add", "prune"])]
 ]);
 export function resolveHelpKey(parsed) {
     if (parsed.command === "help") {
@@ -347,6 +348,34 @@ Options:
 
 Ledgers add registers an existing ledger file in the global registry so --all
 commands and the registry index can find it. The ledger file must already exist.
+`;
+    }
+    if (command === "ledgers prune") {
+        return `Usage:
+  artshelf ledgers prune --dry-run [--registry <path>] [--json|--agent]
+  artshelf ledgers prune --execute --plan-id <id> [--registry <path>] [--json]
+
+Options:
+  --dry-run                Review prunable registrations and write a reviewed plan
+  --execute                Apply a reviewed plan, removing the missing registrations
+  --plan-id <id>           Reviewed plan id to execute (required with --execute)
+  --registry <path>        Registry path to inspect or prune
+  --json                   Emit machine-readable output
+  --agent                  Emit a compact single-line decision packet (dry-run)
+
+Ledgers prune is the approval-gated way to remove registry entries whose ledger
+files are missing, so missing temp ledgers no longer need hand-edited registry
+JSON. Dry-run is read-only except for writing a reviewed plan when action is
+needed; it never mutates the registry. Registrations sharing a duplicate path are
+surfaced as blocked, never pruned. Dry-run prints the exact approval target:
+  approve artshelf ledgers prune registry <registry-path> plan <plan-id>
+
+Execute binds to one exact registry path and reviewed plan id. It re-checks the
+live registry and only removes entries still classified as prunable (entries
+whose ledger file reappeared or whose path became an ambiguous duplicate are
+skipped). It writes a rollback copy of the registry before mutating and a receipt
+after, both discoverable next to the registry under registry-prune-rollbacks/ and
+registry-prune-receipts/.
 `;
     }
     return renderTopLevelHelp(version);

package/docs/agent-monitor.html

@@ -54,7 +54,7 @@
               </li>
               <li>
                 <span class="stamp refused">Repair</span>
-                <span>Registry stale, ledger invalid, or path state unsafe. Fix discovery before anything else.</span>
+                <span>Registry stale, ledger invalid, or path state unsafe. Review missing registrations with registry prune; fix invalid files manually.</span>
               </li>
             </ul>
           </section>
@@ -72,6 +72,9 @@ artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;pro
 <span class="c"># list registered ledgers and their health</span>
 artshelf ledgers list --json
 
+<span class="c"># review missing/stale registrations without hand-editing JSON</span>
+artshelf ledgers prune --dry-run --registry &lt;registry-path&gt; --agent
+
 <span class="c"># review and due-check every registered ledger at once</span>
 artshelf review --all --agent
 artshelf due --all --json
@@ -112,11 +115,12 @@ artshelf doctor --agent
 artshelf status --all --json
 artshelf status --all --agent</code></pre>
             <p>
-              If any ledger is stale or missing-path, run the safe sequence in order:
-              <code>review --all --json</code> for affected classifications,
-              <code>validate --all --json</code> for provenance signals, then
-              <code>reconcile --dry-run --all --json --registry &lt;registry-path&gt;</code>
-              before any approve/execute step.
+              If registered ledgers are stale/missing, run <code>ledgers prune --dry-run --registry &lt;registry-path&gt;</code>
+              to review removing missing registrations, then approve the exact registry/prune plan before execute.
+              If valid ledgers report missing-path records, run <code>review --all --json</code> for
+              affected classifications, <code>validate --all --json</code> for provenance signals, then
+              <code>reconcile --dry-run --all --json --registry &lt;registry-path&gt;</code> before any
+              reconcile approve/execute step.
             </p>
             <p>
               Use <code>--agent</code> for concise monitor decisions and exact next
@@ -131,6 +135,9 @@ artshelf status --all --agent</code></pre>
 artshelf cleanup --dry-run --json
 artshelf cleanup --dry-run --all --json
 
+<span class="c"># preview stale registry registration pruning</span>
+artshelf ledgers prune --dry-run --registry &lt;registry-path&gt; --json
+
 <span class="c"># what is sitting in trash, and how old it is</span>
 artshelf trash list --ledger &lt;ledger-path&gt; --json
 artshelf trash list --all --json
@@ -139,7 +146,7 @@ artshelf trash list --all --json
 artshelf trash purge --older-than 7d --dry-run --ledger &lt;ledger-path&gt; --json</code></pre>
             <p>
               Dry-runs may write reusable plan files when entries exist. No-op dry-runs
-              report <code>not-created</code>. Matching cleanup dry-runs reuse the existing plan id.
+              report <code>not-created</code>. Matching cleanup and registry-prune dry-runs reuse the existing plan id.
             </p>
           </section>
 
@@ -148,10 +155,11 @@ artshelf trash purge --older-than 7d --dry-run --ledger &lt;ledger-path&gt; --js
             <p>Do not scan arbitrary filesystem locations unless the user opted into that discovery scope.</p>
             <div class="callout" data-kind="boundary">
               <span class="callout-label">Never scheduled</span>
-              <p>These two commands require exact human approval and must never run from a monitor job:</p>
+              <p>These commands require exact human approval and must never run from a monitor job:</p>
             </div>
             <pre><code><span class="c"># mutating commands: approval only, never from a schedule</span>
 artshelf cleanup --execute --plan-id &lt;id&gt;
+artshelf ledgers prune --execute --plan-id &lt;id&gt;
 artshelf trash purge --execute --plan-id &lt;id&gt;</code></pre>
           </section>
         </article>

package/docs/agent-review.html

@@ -47,7 +47,10 @@
               <li>Start with health and registry-level context: <code>status --all --agent</code>,
                 then read raw pressure points from <code>review --all --agent</code>
                 and <code>trash list --all --json</code>.</li>
-              <li>For stale or missing path warnings, run <code>validate --all --json</code>
+              <li>For stale registered ledgers, run <code>ledgers prune --dry-run --registry &lt;registry-path&gt;</code>
+                to review removing missing registrations; duplicate paths remain manual
+                <code>registry-problem</code> blockers.</li>
+              <li>For missing-path records inside valid ledgers, run <code>validate --all --json</code>
                 and then <code>reconcile --dry-run --all --json --registry &lt;registry-path&gt;</code>
                 to produce reviewed-safe plans.</li>
               <li>Run explicit-ledger purge dry-runs only when old trash needs review.</li>
@@ -110,12 +113,14 @@ Dry-run only. No execute, resolve, or delete ran.</code></pre>
             <pre><code>approve artshelf cleanup ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;
 approve artshelf trash purge ledger &lt;ledger-path&gt; plan &lt;purge-plan-id&gt;
 approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;
-approve artshelf reconcile ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;</code></pre>
+approve artshelf reconcile ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;
+approve artshelf ledgers prune registry &lt;registry-path&gt; plan &lt;plan-id&gt;</code></pre>
             <div class="callout" data-kind="boundary">
               <span class="callout-label">Hard boundary</span>
               <p>
                 Never execute from a read-only preview id. Never generate a fresh plan and
-                execute it in the same step. After any approved action, verify quiet with
+                execute it in the same step. After registry-prune approval, verify with
+                <code>artshelf ledgers list --json</code>; after any approved ledger action, verify quiet with
                 <code>artshelf review --all --json</code>.
               </p>
             </div>

package/docs/agent-usage.html

@@ -90,13 +90,13 @@
           <section>
             <h2>Render modes</h2>
             <p>
-              <code>review</code>, <code>status</code>, and <code>doctor</code> share three render modes
+              <code>review</code>, <code>status</code>, <code>doctor</code>, and <code>ledgers prune --dry-run</code> share agent-oriented render modes
               so the same data fits both people and agents. Reach for <code>--agent</code> when an agent
               decides and acts; reach for <code>--json</code> for full record, plan, or health detail.
             </p>
             <dl class="def-rows">
               <div><dt>default</dt><dd>human render: scannable grouped counts, attention states, and a short next action for a person at the terminal</dd></div>
-              <div><dt>--agent</dt><dd>a deterministic, token-efficient decision packet (single-line compact JSON) with health, counts, classifications, exact approval targets, blockers, and a verification command</dd></div>
+              <div><dt>--agent</dt><dd>a deterministic, token-efficient decision packet (single-line compact JSON) with health, counts, classifications, blockers, approval targets where applicable, and a verification command</dd></div>
               <div><dt>--json</dt><dd>the backward-compatible public audit contract: complete machine-readable JSON for debugging and integrations</dd></div>
             </dl>
           </section>
@@ -114,7 +114,7 @@
               </li>
               <li>
                 <span class="stamp refused">Blocked</span>
-                <span>Registry is stale, a path is suspicious, or the action would delete without a purge plan.</span>
+                <span>Registry is stale, a path is suspicious, or the action would delete without a purge plan. Missing registrations use a reviewed registry-prune plan, not hand-edited JSON.</span>
               </li>
             </ul>
           </section>

package/docs/agent-usage.md

@@ -47,19 +47,20 @@ The browsable docs split the workflow into focused child pages:
 - Scheduled checks read and report only; set `ARTSHELF_NO_UPDATE_CHECK=1` when
   they must avoid npm network checks and update-cache writes.
 - Review output is a decision packet, not raw counts.
-- Approval names the exact ledger, plan id, or record ids.
+- Stale registry entries route through `ledgers prune --dry-run`, not manual JSON edits.
+- Approval names the exact ledger or registry, plan id, or record ids.
 - Every approved action ends with a read-only verification.
 
 ## Render modes
 
-`review`, `status`, and `doctor` share three render modes so the same data fits
+`review`, `status`, `doctor`, and `ledgers prune --dry-run` share agent-oriented render modes so the same data fits
 both people and agents:
 
 - **default**: a human render — scannable grouped counts, attention states, and a
   short next action for a person at the terminal.
 - **`--agent`**: a deterministic, token-efficient decision packet (single-line
-  compact JSON) with health, counts, classifications, exact approval targets,
-  blockers, and a verification command. Use it when an agent acts on the result.
+  compact JSON) with health, counts, classifications, blockers, approval targets where applicable, and a
+  verification command. Use it when an agent acts on the result.
 - **`--json`**: the backward-compatible public audit contract — complete
   machine-readable JSON for debugging and integrations.
 

package/docs/install.html

@@ -197,6 +197,15 @@ artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <pro
 artshelf ledgers list --json
 ```
 
+If `ledgers list`, `doctor`, or `status --all --agent` reports stale/missing
+registrations, review a registry-prune plan instead of hand-editing the registry:
+
+```bash
+artshelf ledgers prune --dry-run --registry <registry-path> --json
+# after approval: approve artshelf ledgers prune registry <registry-path> plan <plan-id>
+artshelf ledgers prune --execute --plan-id <plan-id> --registry <registry-path> --json
+```
+
 ## 4. Scheduled review (ask the user first)
 
 Ask the user whether they want a scheduled review job before creating one.
@@ -209,8 +218,8 @@ artshelf review --all --json
 ```
 
 and reports what needs attention. Scheduled jobs are review and report only:
-never schedule `artshelf cleanup --execute` or `artshelf trash purge
---execute`.
+never schedule `artshelf cleanup --execute`, `artshelf ledgers prune --execute`,
+or `artshelf trash purge --execute`.
 
 ## 5. Verify and report
 

package/docs/reference.html

@@ -46,8 +46,9 @@
             Run <code>artshelf help</code> for the grouped command list. Use
             <code>artshelf &lt;command&gt; --help</code> or
             <code>artshelf help &lt;command&gt;</code> for focused help; nested commands
-            such as <code>artshelf trash purge --help</code> and
-            <code>artshelf ledgers add --help</code> show only that subcommand.
+            such as <code>artshelf trash purge --help</code>,
+            <code>artshelf ledgers add --help</code>, and
+            <code>artshelf ledgers prune --help</code> show only that subcommand.
           </p>
 
           <section class="cmd">
@@ -84,6 +85,29 @@ artshelf ledgers add --ledger &lt;path&gt; [--name &lt;project&gt;] [--scope rep
             </p>
           </section>
 
+          <section class="cmd">
+            <div class="cmd-head"><h2>artshelf ledgers prune</h2><span class="cmd-flag approval">approval-gated</span></div>
+            <pre><code><span class="c"># review stale/missing registrations before touching the registry</span>
+artshelf ledgers prune --dry-run [--registry &lt;path&gt;] [--json|--agent]
+
+<span class="c"># execute exactly one reviewed registry-prune plan</span>
+artshelf ledgers prune --execute --plan-id &lt;id&gt; [--registry &lt;path&gt;] [--json]</code></pre>
+            <p>
+              <code>prune --dry-run</code> is the registry-safe way to remove registrations whose
+              ledger files are missing. It writes a reviewed plan only when entries are
+              prunable, reuses matching unexecuted plans, prints
+              <code>approve artshelf ledgers prune registry &lt;registry-path&gt; plan &lt;plan-id&gt;</code>,
+              and never mutates the registry during review. Duplicate registry paths are
+              blocked for manual repair.
+            </p>
+            <p>
+              <code>prune --execute</code> binds to one registry path and reviewed plan id,
+              re-checks the live registry, skips stale plan entries whose files reappeared
+              or became ambiguous, writes a rollback copy, removes only still-prunable
+              registrations, and writes a receipt.
+            </p>
+          </section>
+
           <section class="cmd">
             <div class="cmd-head"><h2>artshelf list / find / get</h2><span class="cmd-flag readonly">read-only</span></div>
             <pre><code><span class="c"># browse ledger entries by status</span>
@@ -133,8 +157,10 @@ artshelf doctor [--agent] [--json]</code></pre>
               summary, including reconcile entry and blocked counts, plus the next safe action.
               <code>status</code> is the lightweight dashboard of counts; <code>--all --json</code> is
               cron-friendly. <code>doctor</code> reports CLI version, resolved paths, registry health,
-              and the cleanup safety posture. All three also accept <code>--agent</code> for a
-              deterministic, token-efficient decision packet (see Output mode).
+              and the cleanup safety posture. Missing registered ledger files now point to
+              <code>ledgers prune --dry-run</code>; invalid-but-present ledgers still need manual
+              repair. All three also accept <code>--agent</code> for a deterministic, token-efficient
+              decision packet (see Output mode).
             </p>
           </section>
 
@@ -250,9 +276,9 @@ artshelf reconcile --execute --plan-id &lt;id&gt; --ledger &lt;path&gt; [--json]
               output stays clean.
             </p>
             <p>
-              <code>review</code>, <code>status</code>, and <code>doctor</code> add <code>--agent</code>:
+              <code>review</code>, <code>status</code>, <code>doctor</code>, and <code>ledgers prune --dry-run</code> add <code>--agent</code>:
               a deterministic, token-efficient decision packet emitted as a single line of compact JSON.
-              It names health, counts, classifications, exact approval targets, blockers, and the command
+              It names the relevant health or prune counts, classifications, blockers, approval targets where applicable, and the command
               to re-run for verification, so an agent can act without parsing decorative output.
             </p>
             <p>
@@ -264,7 +290,7 @@ artshelf reconcile --execute --plan-id &lt;id&gt; --ledger &lt;path&gt; [--json]
             <table class="opts">
               <tr><th>option</th><th>meaning</th></tr>
               <tr><td>(default)</td><td>human render: grouped counts, ✓/⚠ attention glyphs, and a short next action</td></tr>
-              <tr><td>--agent</td><td>token-efficient decision packet for agents on <code>review</code>, <code>status</code>, <code>doctor</code></td></tr>
+              <tr><td>--agent</td><td>token-efficient decision packet for agents on <code>review</code>, <code>status</code>, <code>doctor</code>, and <code>ledgers prune --dry-run</code></td></tr>
               <tr><td>--json</td><td>full machine-readable audit JSON on commands that return data</td></tr>
             </table>
           </section>
@@ -279,7 +305,7 @@ artshelf reconcile --execute --plan-id &lt;id&gt; --ledger &lt;path&gt; [--json]
               <tr><th>option</th><th>meaning</th></tr>
               <tr><td>--ledger &lt;path&gt;</td><td>target an explicit JSONL ledger</td></tr>
               <tr><td>--registry &lt;path&gt;</td><td>target an explicit ledger registry</td></tr>
-              <tr><td>--all</td><td>read every registered ledger on commands that support discovery (<code>list</code>, <code>find</code>, <code>get</code>, <code>due</code>, <code>validate</code>, <code>review</code>, <code>status</code>, <code>cleanup --dry-run</code>, <code>reconcile --dry-run</code>, <code>trash list</code>)</td></tr>
+              <tr><td>--all</td><td>read every registered ledger on commands that support discovery (<code>list</code>, <code>find</code>, <code>get</code>, <code>due</code>, <code>validate</code>, <code>review</code>, <code>status</code>, <code>cleanup --dry-run</code>, <code>reconcile --dry-run</code>, <code>trash list</code>); registry pruning is scoped by <code>--registry</code>, not <code>--all</code></td></tr>
             </table>
           </section>
 
@@ -320,7 +346,10 @@ artshelf reconcile --execute --plan-id &lt;id&gt; --ledger &lt;path&gt; [--json]
               repo it defaults to <code>~/.artshelf/ledger.jsonl</code>. A user-level registry at
               <code>~/.artshelf/ledgers.json</code> is the discovery index for <code>--all</code>
               review, status, cleanup dry-run, reconcile dry-run, and trash-list; project records stay in their own
-              repo-local ledgers. Automatic update checks cache their last npm result at
+              repo-local ledgers. Registry-prune plans, rollback copies, and receipts live next to the
+              selected registry under <code>registry-prune-plans/</code>,
+              <code>registry-prune-rollbacks/</code>, and <code>registry-prune-receipts/</code>.
+              Automatic update checks cache their last npm result at
               <code>~/.artshelf/update-check.json</code> by default, with a long TTL
               for update-available results and a shorter TTL for no-update or failed
               results.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artshelf",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",

package/skills/artshelf/SKILL.md

@@ -96,8 +96,9 @@ artshelf trash list --all --json
 
 `artshelf ledgers list --json` reports per-ledger validation status. `--plain`
 skips validation. `--all` is for discovery and review, not mutation permission.
-Use `--agent` on `review`, `status`, and `doctor` for compact decisions; use
-`--json` for full audit/API payloads, custom rendering, or debugging.
+Use `--agent` on `review`, `status`, `doctor`, and `ledgers prune --dry-run`
+for compact decisions; use `--json` for full audit/API payloads, custom
+rendering, or debugging.
 
 Register existing project ledgers explicitly:
 
@@ -108,7 +109,7 @@ artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --s
 ### Scheduled Review
 
 Scheduled jobs are review/report only. Set `ARTSHELF_NO_UPDATE_CHECK=1` for no
-npm network/cache writes. Reports should name the ledger path and plan ids. They may run:
+npm network/cache writes. Reports should name the ledger path or registry path and plan ids. They may run:
 
 ```bash
 artshelf validate --json
@@ -119,6 +120,7 @@ artshelf cleanup --dry-run --all --json
 artshelf trash list --all --json
 artshelf doctor --json
 artshelf status --all --json
+artshelf ledgers prune --dry-run --registry <registry-path> --json
 ```
 
 For old-trash review, dry-run purge only for an explicit ledger:
@@ -128,10 +130,12 @@ artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json
 ```
 
 Do not scan arbitrary filesystem locations for ledgers unless the user opted
-into that discovery scope. Never schedule cleanup or purge execution:
+into that discovery scope. Scheduled jobs may review registry-prune plans but
+must not execute them. Never schedule cleanup, registry-prune, or purge execution:
 
 ```bash
 artshelf cleanup --execute --plan-id <id>
+artshelf ledgers prune --execute --plan-id <id>
 artshelf trash purge --execute --plan-id <id>
 ```
 
@@ -142,16 +146,17 @@ count dump.
 
 1. Run read-only review first: `artshelf status --all --agent` for machine health,
    then `artshelf review --all --agent`, and `artshelf trash list --all --json`.
-2. If stale/missing-path warnings exist, run `artshelf validate --all --json` then `artshelf reconcile --dry-run --all --json --registry <registry-path>` for renames, moves, deletes, stale topology after handoff/finalization, and `.shelf`/`.artshelf` migration fallout.
-3. If cleanup attention exists, run `artshelf cleanup --dry-run --all --json`.
-4. Classify candidates as `trash-safe`, `needs-human-review`,
+2. If stale registered ledgers exist, run `artshelf ledgers prune --dry-run --registry <registry-path> --json` to review removing missing registrations; duplicate paths remain manual registry-problem blockers.
+3. If missing-path warnings exist inside valid ledgers, run `artshelf validate --all --json` then `artshelf reconcile --dry-run --all --json --registry <registry-path>` for renames, moves, deletes, topology after handoff/finalization, and `.shelf`/`.artshelf` migration fallout.
+4. If cleanup attention exists, run `artshelf cleanup --dry-run --all --json`.
+5. Classify candidates as `trash-safe`, `needs-human-review`,
    `resolve-candidate`, or `registry-problem`.
-5. Use the built-in `--agent` packet when the CLI output is enough to decide,
+6. Use the built-in `--agent` packet when the CLI output is enough to decide,
    because it is deterministic and token-efficient. Use
    `ArtshelfReviewReport` from `schemas/artshelf-review-report.schema.json` and `examples/artshelf-review-report.json` when you need a host-specific card, attachment, or richer audit record.
-6. Render full packets with `scripts/render-review-report.mjs`; keep
+7. Render full packets with `scripts/render-review-report.mjs`; keep
    `decisionSummary` in audit, while `decisionGroups` drive counts. Emojis are encouraged only in host-specific wrappers, not the renderer.
-7. Always include the exact approval target in the message body as a fallback.
+8. Always include the exact approval target in the message body as a fallback.
    Do not paste the whole packet into chat unless the user asks for it.
 
 ### Review Plan Report Schema
@@ -201,23 +206,15 @@ approve artshelf cleanup ledger <ledger-path> plan <plan-id>
 approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id>
 approve artshelf resolve missing ledger <ledger-path> ids <id...>
 approve artshelf reconcile ledger <ledger-path> plan <plan-id>
+approve artshelf ledgers prune registry <registry-path> plan <plan-id>
 ```
 
 Never execute from a read-only preview id. Never generate a fresh plan and
-execute it in the same step. After cleanup or resolve approval, verify with `artshelf review --all --json`; after trash purge approval, also run `artshelf trash list --all --json`.
+execute it in the same step. After cleanup, resolve, or registry-prune approval, verify with `artshelf review --all --json` and `artshelf ledgers list --json`; after trash purge approval, also run `artshelf trash list --all --json`.
 
 ## Clean
 
-Read-only and dry-run commands are safe:
-
-```bash
-artshelf validate --json
-artshelf validate --all --json
-artshelf due --json
-artshelf due --all --json
-artshelf cleanup --dry-run --json
-artshelf cleanup --dry-run --all --json
-```
+Read-only and dry-run commands listed above are safe. Registry-prune execution requires approval naming the reviewed registry and plan id (`artshelf ledgers prune --execute --plan-id <id> --registry <registry-path> --json`); it removes only registrations whose ledger files are still missing, writes a rollback copy and receipt next to the registry, and skips entries that changed after review.
 
 Cleanup execution requires approval naming the reviewed ledger and plan id: