artshelf 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 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
@@ -132,6 +136,25 @@
 - Moved `artshelf put` registry-warning output from stdout to stderr in human
   mode; `--json` output is unchanged (NGX-429).
 
+## [0.16.0](https://github.com/calvinnwq/artshelf/compare/v0.15.0...v0.16.0) (2026-06-24)
+
+
+### Features
+
+* **dispose:** add approval-gated artifact disposition ([ee2406e](https://github.com/calvinnwq/artshelf/commit/ee2406e1850f6f2775d5d581bb529fac295b5159))
+* **dispose:** add disposition dry-run domain layer ([c7bdbb3](https://github.com/calvinnwq/artshelf/commit/c7bdbb3d8a40ffc3c9c14c7da6eb6acfedb42859))
+* **dispose:** add disposition execute domain layer ([b9fda32](https://github.com/calvinnwq/artshelf/commit/b9fda3254576d99e5c222a6d1a04c25b1a08d8b0))
+* **dispose:** wire disposition CLI command ([7fe7921](https://github.com/calvinnwq/artshelf/commit/7fe792123b2d4a05bef37d360ced573b82dcd322))
+
+## [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)
 
 

package/README.md

@@ -83,7 +83,7 @@ Follow the instructions in https://github.com/calvinnwq/artshelf/blob/main/INSTA
 It will install the CLI, copy the portable skill (with its bundled review-report
 renderer), register any existing project ledgers, and — only with your approval —
 schedule a **read-only** daily review. Scheduled jobs review and report only;
-cleanup and purge execution always come back to you. See [INSTALL.md](INSTALL.md)
+cleanup, dispose, and purge execution always come back to you. See [INSTALL.md](INSTALL.md)
 for the full steps.
 
 ## How it works
@@ -109,7 +109,7 @@ destructive deletion.
 - **Ledger-first**, not filesystem-scan-first — every artifact is a recorded decision.
 - **Dry-run before mutation**, and execute only from a reviewed plan id.
 - **No daemon, no auto-execute, no global execute** — `--all` is read-only or
-  dry-run reporting; cleanup and purge refuse it.
+  dry-run reporting; cleanup, dispose, and purge refuse it.
 - **No fresh-plan-then-execute shortcut** — review the plan, then run that plan.
 - **Trash before delete** — `cleanup=delete` stays refused; physical deletion
   needs its own reviewed trash purge. No silent deletion, ever.
@@ -118,9 +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` and `ledgers prune --dry-run`**, a
-  compact, token-efficient decision packet for agents, while the default render
-  stays human-scannable.
+- **`--agent` on `review`/`status`/`doctor`, `ledgers prune --dry-run`,
+  `dispose --dry-run`, and `get --inspect`**, a compact, token-efficient decision packet for agents,
+  while the default render stays human-scannable.
 
 ## Reference
 
@@ -137,6 +137,8 @@ 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]
@@ -145,6 +147,8 @@ artshelf doctor
 artshelf update [--json]
 artshelf cleanup --dry-run [--all]
 artshelf cleanup --execute --plan-id <id> [--ledger <path>] [--json]
+artshelf dispose --id <id> --action trash-resolve|resolve-only|snooze|keep --dry-run [--reason <text>] [--ttl <ttl>|--retain-until <date>] [--ledger <path>] [--json|--agent]
+artshelf dispose --execute --plan-id <id> [--ledger <path>] [--json]
 artshelf reconcile --dry-run [--all] [--ledger <path>] [--json]
 artshelf reconcile --execute --plan-id <id> --ledger <path> [--json]
 artshelf trash list [--all] [--ledger <path>] [--json]
@@ -157,9 +161,10 @@ 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`, `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.
+support `--json`; `review`, `status`, `doctor`, `ledgers prune --dry-run`,
+`dispose --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>
@@ -200,8 +205,9 @@ The package includes an agent-facing skill at `skills/artshelf`. Agents that
 support local skills can copy or reference this directory to learn when to call
 `artshelf put`, how to report deterministic footnotes after JSON registration,
 why `artshelf find` / `artshelf get` are the read-only idempotency lookup surface,
-why `cleanup --execute` requires an approved reviewed plan id, how to render
-dry-run cleanup and trash purge plans as review-report decision packets, and when
+why `cleanup --execute` and `dispose --execute` require approved reviewed plan ids, how to render
+dry-run cleanup and trash purge plans as review-report decision packets, how to use
+`dispose --agent` for per-record approval packets, and when
 `artshelf resolve <id> --status resolved --reason <text>` may mark a record handled
 without moving or deleting files.
 

package/SPEC.md

@@ -199,10 +199,57 @@ 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 dispose
+  `trash-resolve` decision.
+- `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 — run `artshelf dispose --id <id> --action keep --dry-run --reason '<why>' --ledger <ledger-path>` to keep it quiet through a reviewed decision, or choose resolve-only/snooze deliberately.
+ledger: <ledger-path>
+```
 
 ### `artshelf due`
 
@@ -279,12 +326,14 @@ 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
+`review`, `status`, `doctor`, `ledgers prune --dry-run`, `dispose --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 `dispose --dry-run`, `--agent` returns the per-request plan or blocked packet.
+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 or registry-prune plan, the exact approval
 targets it emits are `resolve missing` and `reconcile`; the `reconcile` target
@@ -640,6 +689,54 @@ Execute rules:
 JSON output is deterministic (findings preserve ledger order) so agents can render a
 decision packet and approve a specific plan id.
 
+### `artshelf dispose`
+
+Approval-gated disposition for one reviewed record. `dispose` is the command
+surface that follows `get --inspect`: inspect stays read-only, then dispose
+creates or executes the exact reviewed plan for the chosen decision.
+
+```bash
+artshelf dispose --id <id> --action trash-resolve --dry-run [--reason <text>] [--ledger <path>] [--json|--agent]
+artshelf dispose --id <id> --action resolve-only --dry-run --reason <text> [--ledger <path>] [--json|--agent]
+artshelf dispose --id <id> --action snooze --dry-run (--ttl <ttl>|--retain-until <date>) [--reason <text>] [--ledger <path>] [--json|--agent]
+artshelf dispose --id <id> --action keep --dry-run [--reason <text>] [--ledger <path>] [--json|--agent]
+artshelf dispose --execute --plan-id <id> --ledger <path> [--json]
+```
+
+Actions:
+
+- `trash-resolve`: move the recorded path into plan-scoped Artshelf trash,
+  mark the row `trashed`, and leave physical deletion to a separate trash purge.
+- `resolve-only`: resolve the ledger row only; requires `--reason`.
+- `snooze`: extend retention; requires `--ttl` or `--retain-until`.
+- `keep`: stamp that the record was reviewed and kept.
+
+Dry-run rules:
+
+- Classifies exactly one record id and action. There is no `--all` path.
+- Writes a reviewed plan only when the request is actionable, under
+  `<ledger-dir>/dispose-plans/<id>.json`.
+- Registers the plan as an Artshelf-owned artifact (`owner=artshelf`,
+  `kind=run-artifact`, `ttl=14d`, `cleanup=trash`, labels including
+  `artshelf`, `dispose-plan`, and the plan id).
+- Prints the exact approval target:
+  `approve artshelf dispose ledger <ledger-path> plan <plan-id>`.
+- A blocked request reports `planId=not-created`, writes no plan, and exits
+  non-zero while still returning a JSON/agent packet when requested.
+
+Execute rules:
+
+- Requires one explicit reviewed `--plan-id` and the target `--ledger`.
+- Refuses missing, unknown, id-mismatched, ledger-mismatched, malformed, stale,
+  drifted, or target-conflicting plans before mutating.
+- Re-snapshots the subject before execution; stale entries are skipped rather
+  than applied.
+- Writes a dispose receipt to `<ledger-dir>/dispose-receipts/<id>.json` and
+  registers it as an Artshelf-owned artifact (`ttl=30d`, `cleanup=review`,
+  labels including `artshelf`, `dispose-receipt`, and the plan id).
+- There is no fresh-plan-then-execute, no global execute, no daemon, and no
+  physical deletion.
+
 ## Ledger Storage
 
 V1 supports two scopes:
@@ -691,9 +788,9 @@ V1 also supports a user-level registry of known ledgers:
   registry validation.
 - 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.
+- `cleanup --execute --all`, `dispose --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
 
@@ -776,6 +873,23 @@ the purge provenance:
 }
 ```
 
+Records touched by `artshelf dispose --execute` carry the dispose audit trail so
+reviewed disposition stays traceable to the plan and receipt that produced it:
+
+```json
+{
+  "disposePlanId": "dispose_20260601_063000_ab12",
+  "disposeReceiptPath": "/absolute/path/.artshelf/dispose-receipts/dispose_20260601_063000_ab12.json",
+  "disposedAt": "2026-06-01T06:30:00Z",
+  "disposeAction": "trash-resolve",
+  "disposeReason": "reviewed and no longer needed"
+}
+```
+
+`trash-resolve` also sets `previousPath` and `targetPath`; `resolve-only` sets
+the resolve fields without moving the subject; `snooze` updates retention; and
+`keep` leaves retention intact while making due classification quiet.
+
 Records touched by `artshelf reconcile --execute` carry the reconcile audit trail so a
 remap or resolve stays traceable to the reviewed plan that produced it:
 
@@ -848,15 +962,16 @@ hold, and every future feature (`status`, `doctor`, `review`, scheduled jobs,
 - **No daemon.** Artshelf never runs in the background or watches the clock. It
   only does work while you are running an `artshelf` command.
 - **No auto-execute.** No command cleans up as a side effect. The only commands
-  that move, trash, or delete files are `artshelf cleanup --execute` and
-  `artshelf trash purge --execute`, each run by a human against a separately
-  reviewed plan id.
-- **No global execute.** `cleanup --execute --all` and `trash purge --all`
-  are refused; `--all` is read-only or dry-run reporting only. Execution is
-  always scoped to a single reviewed plan id.
-- **No fresh-plan-then-execute.** `cleanup --execute` refuses to compute a new
-  live set. It acts only on a plan id that an earlier `cleanup --dry-run`
-  produced and a human reviewed; it will not plan and execute in one step.
+  that move, trash, or delete files are `artshelf cleanup --execute`,
+  `artshelf dispose --execute`, and `artshelf trash purge --execute`, each run
+  by a human against a separately reviewed plan id.
+- **No global execute.** `cleanup --execute --all`, `dispose --all`, and
+  `trash purge --all` are refused; `--all` is read-only or dry-run reporting
+  only where supported. Execution is always scoped to a single reviewed plan id.
+- **No fresh-plan-then-execute.** `cleanup --execute` and `dispose --execute`
+  refuse to compute a new live set. They act only on plan ids that earlier
+  dry-runs produced and a human reviewed; they will not plan and execute in one
+  step.
 - **No silent deletion.** Cleanup trashes or flags for review and writes a
   receipt to the ledger. The `cleanup=delete` action stays refused in v1; the
   one sanctioned physical deletion is `artshelf trash purge --execute`, which only
@@ -893,9 +1008,9 @@ Agents should call `artshelf put` immediately after creating:
 - one-off generated reports
 - copied files kept for rollback
 
-Agents should not run `artshelf cleanup --execute` or
-`artshelf trash purge --execute` without explicit approval naming the ledger path
-and reviewed plan id.
+Agents should not run `artshelf cleanup --execute`,
+`artshelf dispose --execute`, or `artshelf trash purge --execute` without
+explicit approval naming the ledger path and reviewed plan id.
 
 Agents may run `artshelf find` and `artshelf get` before `put` to avoid duplicate
 registrations. `find`/`get` are read-only ledger queries; they must not be used
@@ -957,11 +1072,14 @@ then render a compact decision report from it. The packet schema is
 docs/skills carry matching copies for browsable docs and portable agent
 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.
+targets in the message body. `dispose --dry-run --agent` already emits its own
+compact per-record approval packet, so it does not require wrapping in this
+review-report schema.
 
 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.
+`artshelf ledgers prune --execute`, `artshelf dispose --execute`, or
+`artshelf trash purge --execute`; they may only dry-run and report plans
+for later human review.
 
 ## Dogfood Scenarios
 
@@ -969,7 +1087,9 @@ only dry-run and report plans for later human review.
 2. Record a config backup with manual review retention.
 3. Generate a dry-run cleanup plan after TTL expiry using fixture data.
 4. Execute a cleanup plan in a temporary test fixture and verify receipt output.
-5. List trashed records, dry-run an old-trash purge, then execute the reviewed
+5. Dispose one reviewed record through dry-run and exact execute approval, then
+   verify the receipt, audit fields, and quiet review state.
+6. List trashed records, dry-run an old-trash purge, then execute the reviewed
    purge plan in a fixture and verify receipt output plus resolved ledger state.
 
 ## V1 Acceptance Criteria
@@ -1007,6 +1127,11 @@ only dry-run and report plans for later human review.
 - Cleanup execute writes a started receipt before moving files, resumes or
   replays the same plan id from receipt/trash evidence, and completes the
   receipt idempotently.
+- CLI can dispose one reviewed record through `artshelf dispose`: `--dry-run`
+  creates or reuses an exact reviewed plan for trash-resolve, resolve-only,
+  snooze, or keep; `--execute` applies one plan id against one ledger, refuses
+  `--all`, stale state, and target conflicts, writes a receipt, and never
+  physically deletes.
 - CLI can list trashed records (single ledger or `--all`) and purge them through
   an approval-first, ledger-scoped dry-run/execute boundary that writes a purge
   receipt; purge refuses `--all` and never deletes without a reviewed plan id.
@@ -1024,14 +1149,14 @@ only dry-run and report plans for later 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`, `doctor`, and `ledgers prune --dry-run` also support
-  `--agent`, a compact single-line JSON decision packet for agents that takes
-  precedence over `--json`.
+- `review`, `status`, `doctor`, `ledgers prune --dry-run`, `dispose --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, registry-prune,
-  and reconcile dry-run/execute behavior.
+  reconcile dry-run/execute, and dispose 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/dispose.js

@@ -0,0 +1,88 @@
+import { createDisposePlan, executeDisposePlan } from "../dispose.js";
+import { printCompactJson, printJson } from "../renderers/json.js";
+import { boolFlag, requiredStringFlag, stringFlag } from "../shared/flags.js";
+export function handleDispose(parsed, ledgerPath, json) {
+    const dryRun = boolFlag(parsed, "dry-run");
+    const execute = boolFlag(parsed, "execute");
+    if (dryRun && execute)
+        throw new Error("dispose accepts either --dry-run or --execute, not both");
+    if (boolFlag(parsed, "all"))
+        throw new Error("dispose is scoped to one --ledger and one reviewed plan; --all is not supported");
+    if (execute) {
+        const planId = requiredStringFlag(parsed, "plan-id");
+        const execution = executeDisposePlan(ledgerPath, planId);
+        if (json) {
+            printJson({ ok: execution.result.status !== "skipped", ledgerPath, execution });
+            return execution.result.status === "skipped" ? 1 : 0;
+        }
+        printDisposeExecution(execution, ledgerPath);
+        return execution.result.status === "skipped" ? 1 : 0;
+    }
+    if (!dryRun)
+        throw new Error("dispose requires --dry-run or --execute");
+    const id = requiredStringFlag(parsed, "id");
+    const action = requiredStringFlag(parsed, "action");
+    const plan = createDisposePlan(ledgerPath, {
+        id,
+        action,
+        reason: stringFlag(parsed, "reason"),
+        ttl: stringFlag(parsed, "ttl"),
+        retainUntil: stringFlag(parsed, "retain-until")
+    });
+    const approve = disposeApprovalTarget(ledgerPath, plan.planId);
+    if (boolFlag(parsed, "agent")) {
+        printCompactJson({
+            ok: plan.entry !== null,
+            command: "dispose",
+            ledgerPath,
+            id,
+            action,
+            status: plan.entry ? "ready-for-approval" : "blocked",
+            planId: plan.entry ? plan.planId : null,
+            approve,
+            blocked: plan.blocked
+        });
+        return plan.entry ? 0 : 1;
+    }
+    if (json) {
+        printJson({ ok: plan.entry !== null, ledgerPath, plan, approve });
+        return plan.entry ? 0 : 1;
+    }
+    printDisposePlan(plan, ledgerPath, approve);
+    return plan.entry ? 0 : 1;
+}
+function disposeApprovalTarget(ledgerPath, planId) {
+    if (planId === "not-created")
+        return null;
+    return `approve artshelf dispose ledger ${ledgerPath} plan ${planId}`;
+}
+function printDisposePlan(plan, ledgerPath, approve) {
+    if (!plan.entry) {
+        process.stdout.write(`dispose plan not-created: blocked ${plan.request.id} ${plan.request.action}\n`);
+        if (plan.blocked)
+            process.stdout.write(`blocked: ${plan.blocked.reason} — ${plan.blocked.detail}\n`);
+        process.stdout.write(`ledger: ${ledgerPath}\n`);
+        return;
+    }
+    process.stdout.write(`dispose plan ${plan.planId}: ${plan.entry.action} ${plan.entry.id}\n`);
+    process.stdout.write(`reason: ${plan.entry.reason}\n`);
+    if (plan.entry.targetPath)
+        process.stdout.write(`target: ${plan.entry.targetPath}\n`);
+    if (plan.entry.retainUntil)
+        process.stdout.write(`retain-until: ${plan.entry.retainUntil}\n`);
+    process.stdout.write(`plan: ${plan.planPath ?? "not created"}\n`);
+    process.stdout.write(`ledger: ${ledgerPath}\n`);
+    if (approve)
+        process.stdout.write(`approve: ${approve}\n`);
+}
+function printDisposeExecution(execution, ledgerPath) {
+    process.stdout.write(`dispose receipt ${execution.planId}: ${execution.result.status} ${execution.result.action} ${execution.result.id}\n`);
+    if (execution.result.reason)
+        process.stdout.write(`reason: ${execution.result.reason}\n`);
+    if (execution.result.targetPath)
+        process.stdout.write(`target: ${execution.result.targetPath}\n`);
+    if (execution.result.retainUntil)
+        process.stdout.write(`retain-until: ${execution.result.retainUntil}\n`);
+    process.stdout.write(`receipt: ${execution.receiptPath}\n`);
+    process.stdout.write(`ledger: ${ledgerPath}\n`);
+}

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/index.js

@@ -1,6 +1,7 @@
 import { normalizeLedgerPath } from "../ledger.js";
 import { boolFlag, stringFlag } from "../shared/flags.js";
 import { handleCleanup } from "./cleanup.js";
+import { handleDispose } from "./dispose.js";
 import { handleDoctor } from "./doctor.js";
 import { handleDue } from "./due.js";
 import { handleFind } from "./find.js";
@@ -44,6 +45,9 @@ export async function runCommand(parsed) {
         case "cleanup":
             status = handleCleanup(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
             break;
+        case "dispose":
+            status = handleDispose(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+            break;
         case "reconcile":
             status = handleReconcile(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
             break;