artshelf 0.14.0 → 0.15.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,15 @@
 - Moved `artshelf put` registry-warning output from stdout to stderr in human
   mode; `--json` output is unchanged (NGX-429).
 
+## [0.15.0](https://github.com/calvinnwq/artshelf/compare/v0.14.0...v0.15.0) (2026-06-20)
+
+
+### Features
+
+* **inspect:** add read-only Artshelf review cards ([08478a8](https://github.com/calvinnwq/artshelf/commit/08478a871f624b048173a986511cc57cf2a2e609))
+* **inspect:** add read-only inspect decision model ([334ea7d](https://github.com/calvinnwq/artshelf/commit/334ea7de99326ed0b0c3129228beaa0d33f378b9))
+* **inspect:** wire get inspect output modes ([4a7270d](https://github.com/calvinnwq/artshelf/commit/4a7270df29f1895efe9032b2cfb7a2c1d47e971f))
+
 ## [0.14.0](https://github.com/calvinnwq/artshelf/compare/v0.13.1...v0.14.0) (2026-06-19)
 
 

package/README.md

@@ -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`, 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]
@@ -157,9 +159,9 @@ 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`, 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>

package/SPEC.md

@@ -199,10 +199,56 @@ Read-only lookup of a single ledger record by Artshelf id.
 artshelf get <id>
 artshelf get <id> --json
 artshelf get <id> --all --json
+artshelf get <id> --inspect
+artshelf get <id> --inspect --json
+artshelf get <id> --inspect --agent
+artshelf get <id> --inspect --all --registry <path> --agent
 ```
 
 `get` is for audit and handoff follow-up. Missing ids are an error. `--all`
-searches registered ledgers until the id is found.
+searches registered ledgers until the id is found. With `--inspect --all`, the
+registry is only used for lookup; the decision card reports the concrete ledger
+that owns the matching record.
+
+`--inspect` turns a record into a review decision card. It never moves files or
+mutates the ledger; it only reports existence, node kind, size, age, retention/due and
+manual-review state, cleanup mode, reason, and a recommendation bucket with the
+exact next-safe action. It never reads or previews arbitrary file contents:
+
+- `keep` — held for manual review, already resolved, already trashed, or due
+  with `cleanup=review`; it needs your judgment but nothing auto-runs.
+- `snooze` — retention has not expired yet; re-inspect after it is due.
+- `trash-safe` — due with `cleanup=trash`; safe to plan a reviewed cleanup.
+- `resolve-only` — the recorded path is gone; resolve the record (ledger-only)
+  rather than cleaning a file.
+- `blocked` — needs a human decision first: `cleanup=delete` (refused at
+  execute), a review-required flag, or a prior cleanup refusal.
+
+File-content previews are intentionally outside Artshelf core; an acting agent or
+host runtime may inspect file contents separately when appropriate.
+`--inspect --json` returns `{ inspect: <report> }`; `--inspect --agent` returns a compact single-line
+decision packet with a read-only safety block, the next-safe action, and a
+reproducer command, and takes precedence over `--json`. Both shapes are
+deterministic so portable agent skills can act without re-deriving anything.
+
+Example pattern — the dogfooding case that motivated this surface was an old
+rollback `backup` registered with `cleanup=review` (the kind of stale record
+`ledgers prune` and `review --all` surface). Inspect it before deciding, using
+the record id and ledger path rather than hardcoding either:
+
+```bash
+artshelf get <id> --inspect --ledger <ledger-path>
+```
+
+```text
+✓ <id> [backup] — keep
+path: <backup-path>
+status: active · cleanup: review · owner: agent · labels: registry-prune
+existence: present (directory, 49 B) · age: 14d · retention: manual-review · due: manual-review
+reason: rollback backup before registry prune
+next: Held for manual review — keep it, change its retention, or resolve it explicitly; no cleanup is scheduled.
+ledger: <ledger-path>
+```
 
 ### `artshelf due`
 
@@ -279,12 +325,13 @@ 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`, and `get --inspect`
+expose agent-oriented render modes. For review/status/doctor, the default human render
 leads each ledger and summary line with a `✓`/`⚠` attention glyph. `--json` stays
 the full, backward-compatible public audit report; and `--agent` emits a compact,
 deterministic single-line JSON decision packet for agents, taking precedence over
-`--json` when both are passed. For `review`, the packet sorts records into
+`--json` when both are passed. For `get --inspect`, `--agent` returns the
+per-record decision packet and requires `--inspect`. For `review`, the packet sorts records into
 ready-for-approval, needs-review-first, and blocked groups. Because review is
 read-only and never mints a cleanup or registry-prune plan, the exact approval
 targets it emits are `resolve missing` and `reconcile`; the `reconcile` target
@@ -1024,9 +1071,9 @@ 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`, 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

package/dist/src/cli.js

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

package/dist/src/commands/get.js

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

package/dist/src/inspect.js

@@ -0,0 +1,204 @@
+import * as fs from "node:fs";
+import { existsSync, lstatSync } from "node:fs";
+import { join } from "node:path";
+import { shellArg } from "./shared/shell-quote.js";
+import { ageOf, now as currentTime } from "./time.js";
+const DIRECTORY_SIZE_MAX_ENTRIES = 10_000;
+const openDirectorySync = fs.opendirSync;
+export function buildInspectReport(record, options) {
+    const at = options.now ?? currentTime();
+    const subjectPath = subjectPathOf(record);
+    const node = describeNode(subjectPath, record.status === "active");
+    const dueState = classifyDueState(record, at, node.existence);
+    const { recommendation, nextAction } = recommend(record, node.existence, dueState, options.ledgerPath);
+    return {
+        schemaVersion: 1,
+        id: record.id,
+        path: record.path,
+        subjectPath,
+        kind: record.kind,
+        owner: record.owner,
+        labels: record.labels,
+        status: record.status,
+        cleanup: record.cleanup,
+        reason: record.reason,
+        existence: node.existence,
+        nodeKind: node.nodeKind,
+        byteSize: node.byteSize,
+        byteSizeTruncated: node.byteSizeTruncated,
+        age: ageOf(at, record.createdAt),
+        retention: record.retention,
+        retainUntil: record.retainUntil ?? null,
+        dueState,
+        recommendation,
+        nextAction
+    };
+}
+function subjectPathOf(record) {
+    if (record.status === "trashed" && record.targetPath)
+        return record.targetPath;
+    return record.path;
+}
+function describeNode(subjectPath, followSymlinkExistence = false) {
+    if (followSymlinkExistence && !existsSync(subjectPath)) {
+        return { existence: "missing", nodeKind: null, byteSize: null, byteSizeTruncated: false };
+    }
+    let stat;
+    try {
+        stat = lstatSync(subjectPath);
+    }
+    catch {
+        return { existence: "missing", nodeKind: null, byteSize: null, byteSizeTruncated: false };
+    }
+    if (stat.isSymbolicLink())
+        return { existence: "present", nodeKind: "other", byteSize: null, byteSizeTruncated: false };
+    if (stat.isFile())
+        return { existence: "present", nodeKind: "file", byteSize: stat.size, byteSizeTruncated: false };
+    if (stat.isDirectory()) {
+        const size = directorySize(subjectPath);
+        return { existence: "present", nodeKind: "directory", byteSize: size.bytes, byteSizeTruncated: size.truncated };
+    }
+    return { existence: "present", nodeKind: "other", byteSize: null, byteSizeTruncated: false };
+}
+// Bounded recursive size: sums regular-file bytes, never follows symlinks, and stops at
+// a fixed entry budget so a pathological tree cannot stall a read-only inspect.
+function directorySize(root) {
+    let total = 0;
+    let visited = 0;
+    let incomplete = false;
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        let entries;
+        try {
+            entries = openDirectorySync(dir);
+        }
+        catch {
+            incomplete = true;
+            continue;
+        }
+        try {
+            while (true) {
+                let entry;
+                try {
+                    entry = entries.readSync();
+                }
+                catch {
+                    incomplete = true;
+                    break;
+                }
+                if (entry === null)
+                    break;
+                if (visited >= DIRECTORY_SIZE_MAX_ENTRIES)
+                    return { bytes: total, truncated: true };
+                visited += 1;
+                const child = join(dir, entry.name);
+                let stat;
+                try {
+                    stat = lstatSync(child);
+                }
+                catch {
+                    incomplete = true;
+                    continue;
+                }
+                if (stat.isSymbolicLink())
+                    continue;
+                if (stat.isDirectory()) {
+                    stack.push(child);
+                    continue;
+                }
+                if (stat.isFile())
+                    total += stat.size;
+            }
+        }
+        finally {
+            try {
+                entries.closeSync();
+            }
+            catch {
+                incomplete = true;
+            }
+        }
+    }
+    return { bytes: total, truncated: incomplete };
+}
+// Mirrors ledger due classification, but reuses the existence already observed so a
+// trashed/terminal record never re-stats. Only active records carry a due state.
+function classifyDueState(record, at, existence) {
+    if (record.status !== "active")
+        return null;
+    if (existence === "missing")
+        return "missing-path";
+    if (record.retention.mode === "manual-review")
+        return "manual-review";
+    if (!record.retainUntil)
+        return "due";
+    return new Date(record.retainUntil).getTime() <= at.getTime() ? "due" : "kept";
+}
+function recommend(record, existence, dueState, ledgerPath) {
+    const idArg = shellArg(record.id);
+    const ledgerArg = shellArg(ledgerPath);
+    if (record.status === "resolved") {
+        return { recommendation: "keep", nextAction: "Already resolved — no action needed." };
+    }
+    if (record.status === "trashed") {
+        if (existence === "missing") {
+            return {
+                recommendation: "resolve-only",
+                nextAction: `Trashed target is missing — confirm the artifact is gone, then run \`artshelf resolve ${idArg} --ledger ${ledgerArg} --status resolved --reason '<why>'\` (ledger-only).`
+            };
+        }
+        return {
+            recommendation: "keep",
+            nextAction: "Already trashed — permanent removal is the separate approval-gated `artshelf trash purge` flow."
+        };
+    }
+    if (record.status === "review-required") {
+        return {
+            recommendation: "blocked",
+            nextAction: "A cleanup run flagged this for manual review — inspect the artifact, then resolve or re-plan deliberately."
+        };
+    }
+    if (record.status === "cleanup-refused") {
+        return {
+            recommendation: "blocked",
+            nextAction: "A prior cleanup refused this record — handle it manually; Artshelf will not retry automatically."
+        };
+    }
+    if (existence === "missing" || dueState === "missing-path") {
+        return {
+            recommendation: "resolve-only",
+            nextAction: `Path is missing — confirm the artifact is gone, then run \`artshelf resolve ${idArg} --ledger ${ledgerArg} --status resolved --reason '<why>'\` (ledger-only).`
+        };
+    }
+    if (dueState === "kept") {
+        return {
+            recommendation: "snooze",
+            nextAction: `Retention holds until ${record.retainUntil ?? "the configured date"} — re-inspect after it expires; nothing is due now.`
+        };
+    }
+    if (dueState === "manual-review") {
+        return {
+            recommendation: "keep",
+            nextAction: "Held for manual review — keep it, change its retention, or resolve it explicitly; no cleanup is scheduled."
+        };
+    }
+    if (record.cleanup === "trash") {
+        return {
+            recommendation: "trash-safe",
+            nextAction: `Due and disposable — run \`artshelf cleanup --dry-run --ledger ${ledgerArg}\`, then approve the reviewed plan id.`
+        };
+    }
+    if (record.cleanup === "delete") {
+        return {
+            recommendation: "blocked",
+            nextAction: "Due with cleanup=delete, which Artshelf refuses — switch it to cleanup=trash and plan a cleanup, or resolve it manually."
+        };
+    }
+    return {
+        recommendation: "keep",
+        nextAction: "Due and held for review — keep it, change its retention, resolve it, or switch cleanup to trash and plan a cleanup."
+    };
+}

package/dist/src/renderers/inspect.js

@@ -0,0 +1,108 @@
+import { shellArg } from "../shared/shell-quote.js";
+import { attentionGlyph } from "./attention.js";
+// Buckets whose next-safe action is something other than "leave it alone" get the
+// attention glyph so a scanned card reads as a decision, not just a status line.
+const ATTENTION_RECOMMENDATIONS = new Set([
+    "trash-safe",
+    "resolve-only",
+    "blocked"
+]);
+export function buildInspectAgentPacket(report, ledgerPath) {
+    return {
+        schemaVersion: 1,
+        command: "get",
+        mode: "inspect",
+        ledgerPath,
+        inspect: report,
+        safety: {
+            readOnly: true,
+            noFileMoves: true,
+            noLedgerMutation: true
+        },
+        nextAction: report.nextAction,
+        verification: `artshelf get ${shellArg(report.id)} --inspect --agent --ledger ${shellArg(ledgerPath)}`
+    };
+}
+export function printInspect(report, ledgerPath) {
+    const glyph = attentionGlyph(ATTENTION_RECOMMENDATIONS.has(report.recommendation));
+    const labels = report.labels.length > 0 ? report.labels.map(sanitizeHumanLine).join(", ") : "none";
+    const lines = [];
+    lines.push(`${glyph} ${sanitizeHumanLine(report.id)} [${sanitizeHumanLine(report.kind)}] — ${sanitizeHumanLine(report.recommendation)}`);
+    lines.push(`path: ${sanitizeHumanLine(report.path)}`);
+    // Trashed records point `path` at the now-empty original; existence and size
+    // describe the trash target, so name it explicitly when the two differ.
+    if (report.subjectPath !== report.path)
+        lines.push(`trash target: ${sanitizeHumanLine(report.subjectPath)}`);
+    lines.push(`status: ${sanitizeHumanLine(report.status)} · cleanup: ${sanitizeHumanLine(report.cleanup)} · owner: ${sanitizeHumanLine(report.owner)} · labels: ${labels}`);
+    lines.push(`existence: ${sanitizeHumanLine(formatExistence(report))} · age: ${sanitizeHumanLine(report.age)} · retention: ${sanitizeHumanLine(formatRetention(report.retention))} · due: ${sanitizeHumanLine(report.dueState ?? "n/a")}`);
+    lines.push(`reason: ${sanitizeHumanLine(report.reason)}`);
+    lines.push(`next: ${sanitizeHumanLine(report.nextAction)}`);
+    lines.push(`ledger: ${sanitizeHumanLine(ledgerPath)}`);
+    process.stdout.write(`${lines.join("\n")}\n`);
+}
+function formatExistence(report) {
+    if (report.existence === "missing")
+        return "missing";
+    if (report.nodeKind === "file" || report.nodeKind === "directory") {
+        const size = report.byteSize === null ? "size unavailable" : formatBytes(report.byteSize);
+        if (report.nodeKind === "directory" && report.byteSizeTruncated) {
+            return `present (directory, at least ${size}; scan capped)`;
+        }
+        return `present (${report.nodeKind}, ${size})`;
+    }
+    return "present (other)";
+}
+function formatRetention(retention) {
+    if (retention.mode === "ttl")
+        return `ttl ${retention.ttl}`;
+    if (retention.mode === "retain-until")
+        return `retain-until ${retention.retainUntil}`;
+    return "manual-review";
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function sanitizeHumanLine(value) {
+    let out = "";
+    for (const char of value) {
+        const code = char.codePointAt(0);
+        if (code === undefined)
+            continue;
+        if (char === "\\") {
+            out += "\\\\";
+        }
+        else if (char === "\n") {
+            out += "\\n";
+        }
+        else if (char === "\r") {
+            out += "\\r";
+        }
+        else if (char === "\t") {
+            out += "\\t";
+        }
+        else if (code < 32 || (code >= 0x7f && code <= 0x9f) || isUnicodeFormatControl(code)) {
+            out += `\\u${code.toString(16).padStart(4, "0")}`;
+        }
+        else {
+            out += char;
+        }
+    }
+    return out;
+}
+function isUnicodeFormatControl(code) {
+    if (code === 0x00ad || code === 0x061c)
+        return true;
+    if (code >= 0x200b && code <= 0x200f)
+        return true;
+    if (code >= 0x202a && code <= 0x202e)
+        return true;
+    if (code >= 0x2060 && code <= 0x206f)
+        return true;
+    if (code >= 0xfe00 && code <= 0xfe0f)
+        return true;
+    return code >= 0xfff9 && code <= 0xfffb;
+}

package/dist/src/shared/flags.js

@@ -1,4 +1,5 @@
 export const BOOLEAN_FLAGS = new Set(["all", "json", "agent", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
+const COMMAND_BOOLEAN_FLAGS = new Map([["get", new Set(["inspect"])]]);
 export const VALUE_FLAGS = new Set([
     "cleanup",
     "kind",
@@ -16,6 +17,9 @@ export const VALUE_FLAGS = new Set([
     "status",
     "ttl"
 ]);
+export function isBooleanFlag(name, command) {
+    return BOOLEAN_FLAGS.has(name) || (command !== undefined && (COMMAND_BOOLEAN_FLAGS.get(command)?.has(name) ?? false));
+}
 export function requiredStringFlag(parsed, name) {
     const value = stringFlag(parsed, name);
     if (!value)

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

@@ -170,8 +170,24 @@ Find is read-only. Use it before put when an integration needs idempotent artifa
         return `Usage:
   artshelf get <id> [--ledger <path>] [--json]
   artshelf get <id> --all [--registry <path>] [--json]
+  artshelf get <id> --inspect [--ledger <path>] [--json|--agent]
+  artshelf get <id> --inspect --all [--registry <path>] [--json|--agent]
 
 Get is read-only and returns one ledger record by Artshelf id.
+
+--inspect adds a read-only review decision card for one record: existence,
+size, age, retention/due state, a recommendation bucket (keep, snooze,
+trash-safe, resolve-only, blocked), and the exact next-safe action. It never
+moves files or touches the ledger. It does not read or preview arbitrary
+file contents; agents can inspect contents separately when appropriate.
+With --all, the registry is only used to find the id; the card reports the
+concrete ledger that owns the record.
+
+Render modes:
+  (default)  Human record line, or a decision card with --inspect.
+  --json     Full read-only report (record, or { inspect } with --inspect).
+  --agent    Compact single-line JSON decision packet (requires --inspect);
+             takes precedence over --json.
 `;
     }
     if (command === "resolve") {

package/dist/src/shared/shell-quote.js

@@ -0,0 +1,6 @@
+const SHELL_SAFE = /^[A-Za-z0-9_./:@%+=,-]+$/;
+export function shellArg(value) {
+    if (value.length > 0 && SHELL_SAFE.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/docs/agent-review.html

@@ -65,6 +65,41 @@
             </p>
           </section>
 
+          <section>
+            <h2>Inspect a single record</h2>
+            <p>
+              When a review flags one record — most often a stale
+              <code>cleanup=review</code> backup that <code>ledgers prune</code> and
+              <code>review --all</code> surface — drill into it with
+              <code>get &lt;id&gt; --inspect</code> instead of running <code>get</code>,
+              <code>ls</code>, and <code>du</code> by hand. It is read-only: it never
+              moves files or mutates the ledger.
+            </p>
+            <pre><code><span class="c"># review one record as a decision card</span>
+artshelf get &lt;id&gt; --inspect --ledger &lt;ledger-path&gt;
+
+<span class="c"># compact, deterministic packet for an acting agent</span>
+artshelf get &lt;id&gt; --inspect --agent --ledger &lt;ledger-path&gt;</code></pre>
+            <p>
+              Each card reports existence, size, age, retention/due state, cleanup
+              mode, and reason, then ends with a recommendation bucket and the exact
+              next-safe action. It does not read or preview arbitrary file contents:
+              <code>keep</code>, <code>snooze</code>, <code>trash-safe</code>,
+              <code>resolve-only</code>, or <code>blocked</code>. These map onto the
+              daily-review classifications — a missing-path record reads as
+              <code>resolve-only</code> and points at <code>artshelf resolve</code>,
+              while a due disposable record reads as <code>trash-safe</code> and points
+              at a reviewed cleanup plan.
+            </p>
+            <pre><code>✓ &lt;id&gt; [backup] — keep
+path: &lt;backup-path&gt;
+status: active · cleanup: review · owner: agent · labels: registry-prune
+existence: present (directory, 49 B) · age: 14d · retention: manual-review · due: manual-review
+reason: rollback backup before registry prune
+next: Held for manual review — keep it, change its retention, or resolve it explicitly; no cleanup is scheduled.
+ledger: &lt;ledger-path&gt;</code></pre>
+          </section>
+
           <section>
             <h2>Review plan report schema</h2>
             <p>For richer host cards, attachments, or audit packets, construct an <code>ArtshelfReviewReport</code> JSON packet first, then render a compact decision card.</p>

package/docs/agent-usage.html

@@ -90,13 +90,15 @@
           <section>
             <h2>Render modes</h2>
             <p>
-              <code>review</code>, <code>status</code>, <code>doctor</code>, and <code>ledgers prune --dry-run</code> share agent-oriented render modes
+              <code>review</code>, <code>status</code>, <code>doctor</code>, <code>ledgers prune --dry-run</code>, and per-record
+              <code>get --inspect</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.
+              On <code>get</code>, <code>--agent</code> requires <code>--inspect</code>.
             </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, blockers, approval targets where applicable, 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, record recommendations, 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>

package/docs/agent-usage.md

@@ -53,20 +53,23 @@ The browsable docs split the workflow into focused child pages:
 
 ## Render modes
 
-`review`, `status`, `doctor`, and `ledgers prune --dry-run` share agent-oriented render modes so the same data fits
-both people and agents:
+`review`, `status`, `doctor`, `ledgers prune --dry-run`, and per-record
+`get --inspect` 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, blockers, approval targets where applicable, and a
-  verification command. Use it when an agent acts on the result.
+  compact JSON) with health, counts, classifications, blockers, record
+  recommendations, 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.
 
 Reach for `--agent` when an agent needs to decide and act cheaply; reach for
 `--json` when you want the full record, plan, or health detail for audit or
-debugging. `--agent` takes precedence if both flags are passed.
+debugging. `--agent` takes precedence if both flags are passed; on `get`, it
+requires `--inspect`.
 
 ## Portable Skill
 

package/docs/reference.html

@@ -117,12 +117,22 @@ artshelf list [--all] [--status active|review-required|trashed|cleanup-refused|r
 artshelf find --path <path> [--owner <o>] [--label <l>] [--json]
 
 <span class="c"># fetch one record by id</span>
-artshelf get &lt;id&gt; [--all] [--json]</code></pre>
+artshelf get &lt;id&gt; [--all] [--json]
+
+<span class="c"># review one record as a decision card (read-only, no mutation)</span>
+artshelf get &lt;id&gt; --inspect [--ledger &lt;path&gt;] [--json|--agent]
+artshelf get &lt;id&gt; --inspect --all [--registry &lt;path&gt;] [--json|--agent]</code></pre>
             <p>
               <code>list</code> shows ledger entries and current status. <code>find</code> looks up
               existing records by path, owner, labels, and status. Use it before <code>put</code>
               for idempotent registration; it requires at least one selector and never mutates records.
-              <code>get</code> is the audit lookup for one record by Artshelf id.
+              <code>get</code> is the audit lookup for one record by Artshelf id;
+              <code>--inspect</code> renders it as a review decision card — existence, size, age,
+              retention/due state, and a recommendation bucket (<code>keep</code>, <code>snooze</code>, <code>trash-safe</code>,
+              <code>resolve-only</code>, or <code>blocked</code>) with the exact next-safe action,
+              without moving files, touching the ledger, or previewing arbitrary file contents.
+              Combine <code>--inspect --all</code> to find the id through the registry while the card
+              reports the concrete ledger that owns the record.
             </p>
           </section>
 
@@ -276,9 +286,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>, <code>doctor</code>, and <code>ledgers prune --dry-run</code> add <code>--agent</code>:
+              <code>review</code>, <code>status</code>, <code>doctor</code>, <code>ledgers prune --dry-run</code>, and <code>get --inspect</code> add <code>--agent</code>:
               a deterministic, token-efficient decision packet emitted as a single line of compact JSON.
-              It names the relevant health or prune counts, classifications, blockers, approval targets where applicable, and the command
+              It names the relevant health, prune counts, or record recommendation, 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>
@@ -289,8 +299,8 @@ artshelf reconcile --execute --plan-id &lt;id&gt; --ledger &lt;path&gt; [--json]
             </p>
             <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>, and <code>ledgers prune --dry-run</code></td></tr>
+              <tr><td>(default)</td><td>human render: grouped counts or a record card, ✓/⚠ 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>, <code>ledgers prune --dry-run</code>, and <code>get --inspect</code></td></tr>
               <tr><td>--json</td><td>full machine-readable audit JSON on commands that return data</td></tr>
             </table>
           </section>

package/package.json

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

package/skills/artshelf/SKILL.md

@@ -96,9 +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`, `doctor`, and `ledgers prune --dry-run`
-for compact decisions; use `--json` for full audit/API payloads, custom
-rendering, or debugging.
+Use `--agent` on `review`, `status`, `doctor`, `ledgers prune --dry-run`, and
+`get --inspect` for compact decisions; use `--json` for full audit/API payloads,
+custom rendering, or debugging. On `get`, `--agent` requires `--inspect`.
 
 Register existing project ledgers explicitly:
 
@@ -150,7 +150,10 @@ count dump.
 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`.
+   `resolve-candidate`, or `registry-problem`. For one flagged record (e.g. a
+   stale `cleanup=review` backup), read-only `artshelf get <id> --inspect --agent`
+   returns a per-record decision (`keep`, `snooze`, `trash-safe`, `resolve-only`,
+   `blocked`) and the exact next-safe action without mutating anything.
 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.