artshelf 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -64,6 +64,30 @@
   and `artshelf ledgers help` aliases, advertised short `-h`/`-v` flags, and
   reclassified `--ledger`, `--registry`, and `--all` as command-specific scope
   flags instead of global options.
+- Added an `--agent` render mode to `artshelf review`, `status`, and `doctor`: a
+  compact, deterministic single-line JSON decision packet (health, counts,
+  attention categories or classified decision groups, blockers, the next safe
+  action, and a verification command) tuned for agents acting on results.
+  `--agent` takes precedence over `--json`, while `--json` stays the full,
+  backward-compatible audit report. The default human renders of these three
+  commands now lead each ledger and summary line with a `✓`/`⚠` attention glyph
+  (plain Unicode, no color) so redirected output stays clean.
+
+## [0.10.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.9.0...artshelf-v0.10.0) (2026-06-12)
+
+
+### Features
+
+* **cli:** add --agent decision-packet render mode for review, status, and doctor ([4d2dee0](https://github.com/calvinnwq/artshelf/commit/4d2dee099569803b887ae49438b0747d1330ec5d))
+* **cli:** add --agent render mode and implement status --agent ([36f8e78](https://github.com/calvinnwq/artshelf/commit/36f8e7839d535fcabddadfc616ba518a9b444114))
+* **cli:** add ✓/⚠ attention glyphs to human renders of status/doctor/review ([6f6cbe8](https://github.com/calvinnwq/artshelf/commit/6f6cbe85d54886cfd137791863e1b3554ca908f0))
+* **cli:** implement artshelf doctor --agent compact decision packet ([d9abd4e](https://github.com/calvinnwq/artshelf/commit/d9abd4e75a7f4b2898eeacc3b3404221f4456bd4))
+* **cli:** implement artshelf review --agent compact decision packet ([6f5476c](https://github.com/calvinnwq/artshelf/commit/6f5476ca987de3190f7a8760c6bb9c1efa8b9fce))
+
+
+### Bug Fixes
+
+* **cli:** preserve ledger scope in agent next actions ([a583683](https://github.com/calvinnwq/artshelf/commit/a583683064cdd16dd929766dc01f23fc31fa50e7))
 
 ## [0.9.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.8.0...artshelf-v0.9.0) (2026-06-11)
 

package/README.md

@@ -112,6 +112,8 @@ destructive deletion.
 - **Trash before delete** — `cleanup=delete` stays refused; physical deletion
   needs its own reviewed trash purge. No silent deletion, ever.
 - **`--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.
 
 ## Reference
 
@@ -143,7 +145,8 @@ 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`; `--ledger`, `--registry`, and
+subcommand. All core commands support `--json`; `review`, `status`, and `doctor`
+also take `--agent` for a compact decision packet; `--ledger`, `--registry`, and
 `--all` are scope flags only on commands that list them.
 </details>
 

package/SPEC.md

@@ -242,7 +242,9 @@ files or writing a plan.
 
 ```bash
 artshelf review --json
+artshelf review --agent
 artshelf review --all --json
+artshelf review --all --agent
 ```
 
 `review` is the compact report surface for scheduled checks. `--all` reads every
@@ -257,6 +259,16 @@ triage count and states the same next safe action (repair broken ledgers, dry-ru
 cleanup, inspect missing paths, 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 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 only exact approval target it emits
+is `resolve missing`; cleanup-eligible records stay needs-review-first and point
+at `cleanup --dry-run`, which mints the reviewed plan id to approve.
+
 ### `artshelf doctor`
 
 Reports whether Artshelf is healthy on the current machine without mutating
@@ -265,6 +277,7 @@ anything.
 ```bash
 artshelf doctor
 artshelf doctor --json
+artshelf doctor --agent
 artshelf doctor --ledger <path>
 artshelf doctor --registry <path>
 ```
@@ -284,7 +297,11 @@ 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.
+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
+`--json`.
 
 ### `artshelf status`
 
@@ -293,7 +310,9 @@ The lightweight daily "what is going on?" view across ledgers.
 ```bash
 artshelf status
 artshelf status --json
+artshelf status --agent
 artshelf status --all --json
+artshelf status --all --agent
 artshelf status --all --registry <path> --json
 ```
 
@@ -312,7 +331,9 @@ 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.
+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`.
 
 ### `artshelf update`
 
@@ -773,6 +794,8 @@ 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`.
 - 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, and trash list/purge behavior.

package/dist/src/cli.js

@@ -9,7 +9,7 @@ const VERSION = readPackageVersion();
 const PACKAGE_NAME = "artshelf";
 const NPM_REGISTRY_URL = process.env.ARTSHELF_NPM_REGISTRY_URL ?? `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
 const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
-const BOOLEAN_FLAGS = new Set(["all", "json", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
+const BOOLEAN_FLAGS = new Set(["all", "json", "agent", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
 const VALUE_FLAGS = new Set([
     "cleanup",
     "kind",
@@ -535,12 +535,17 @@ function handleTrashPurge(parsed, ledgerPath, json) {
     return 0;
 }
 function handleReview(parsed, ledgerPath, json) {
+    const agent = boolFlag(parsed, "agent");
     if (boolFlag(parsed, "all")) {
         const registryPath = normalizeRegistryPath(stringFlag(parsed, "registry"));
         const results = registeredLedgersOrThrow(registryPath).map((ledger) => reviewLedger(ledger));
         const ok = results.every((entry) => entry.validate.ok);
         const summary = summarizeReview(results);
-        const nextAction = reviewNextAction(summary);
+        if (agent) {
+            printCompactJson(buildReviewAgentPacketAll(results, summary, registryPath));
+            return ok ? 0 : 1;
+        }
+        const nextAction = reviewNextAction(summary, "all");
         if (json) {
             printJson({ ok, registryPath, summary, nextAction, ledgers: results });
             return ok ? 0 : 1;
@@ -549,6 +554,10 @@ function handleReview(parsed, ledgerPath, json) {
         return ok ? 0 : 1;
     }
     const result = reviewLedger({ name: "current", path: ledgerPath, scope: "other", createdAt: "", updatedAt: "" }, false);
+    if (agent) {
+        printCompactJson(buildReviewAgentPacketSingle(result, ledgerPath));
+        return result.validate.ok ? 0 : 1;
+    }
     if (json) {
         printJson({ ok: result.validate.ok, ledger: result });
         return result.validate.ok ? 0 : 1;
@@ -558,6 +567,10 @@ function handleReview(parsed, ledgerPath, json) {
 }
 function handleDoctor(parsed, ledgerPath, json) {
     const report = buildDoctorReport(ledgerPath, normalizeRegistryPath(stringFlag(parsed, "registry")));
+    if (boolFlag(parsed, "agent")) {
+        printCompactJson(buildDoctorAgentPacket(report));
+        return report.ok ? 0 : 1;
+    }
     if (json) {
         printJson(report);
         return report.ok ? 0 : 1;
@@ -624,16 +637,72 @@ function buildDoctorReport(ledgerPath, registryPath) {
         errors
     };
 }
+// Actionable categories only — ok ledgers are healthy states, never attention.
+// Order is fixed so the packet is byte-for-byte deterministic. Warnings surface
+// even when health is ok (they never fail the machine), mirroring status attention.
+const DOCTOR_ATTENTION_CATEGORIES = ["stale", "invalid", "warnings"];
+function doctorAttention(summary) {
+    return DOCTOR_ATTENTION_CATEGORIES.filter((key) => summary[key] > 0);
+}
+function doctorNextAction(blockers, summary) {
+    if (blockers.length > 0) {
+        return `repair ${blockers.length} registry/ledger issue(s) above, then re-run \`artshelf doctor\``;
+    }
+    if (summary.warnings > 0) {
+        return `healthy, but ${summary.warnings} warning(s) noted — run \`artshelf validate --all\` to inspect; nothing is auto-executed`;
+    }
+    return "artshelf is healthy on this machine — cleanup safety enforced; no action needed";
+}
+function buildDoctorAgentPacket(report) {
+    const blockers = [];
+    if (report.registryError)
+        blockers.push(`registry unreadable: ${report.registryError}`);
+    for (const ledger of report.ledgers) {
+        if (ledger.status !== "ok") {
+            blockers.push(`${ledger.name} ${ledger.status}${ledger.errors.length ? `: ${ledger.errors[0]}` : ""}`);
+        }
+    }
+    return {
+        schemaVersion: 1,
+        command: "doctor",
+        health: report.ok ? "ok" : "attention",
+        version: report.version,
+        node: report.node,
+        ledgerPath: report.ledgerPath,
+        registry: { path: report.registryPath, exists: report.registryExists, ok: report.registryOk, error: report.registryError },
+        ledgers: {
+            total: report.summary.ledgers,
+            ok: report.summary.ok,
+            stale: report.summary.stale,
+            invalid: report.summary.invalid,
+            warnings: report.summary.warnings
+        },
+        attention: doctorAttention(report.summary),
+        blockers,
+        cleanupSafety: report.cleanupSafety,
+        nextAction: doctorNextAction(blockers, report.summary),
+        verification: `artshelf doctor --agent --registry ${report.registryPath}`
+    };
+}
+// Human render (NGX-396): a scannable left-column glyph so attention state is
+// obvious at a glance — ✓ clear, ⚠ needs attention. Plain Unicode (no ANSI
+// color) keeps redirected/piped human output clean, and the `--agent`/`--json`
+// renders never carry glyphs (those stay machine contracts).
+const HUMAN_OK_GLYPH = "✓";
+const HUMAN_ATTENTION_GLYPH = "⚠";
+function attentionGlyph(needsAttention) {
+    return needsAttention ? HUMAN_ATTENTION_GLYPH : HUMAN_OK_GLYPH;
+}
 function printDoctor(report) {
     process.stdout.write(`artshelf ${report.version} (node ${report.node})\n`);
-    process.stdout.write(`health: ${report.ok ? "ok" : "needs attention"}\n`);
+    process.stdout.write(`${attentionGlyph(!report.ok)} health: ${report.ok ? "ok" : "needs attention"}\n`);
     process.stdout.write(`ledger: ${report.ledgerPath}${report.ledgerExists ? "" : " (absent)"}\n`);
     process.stdout.write(`registry: ${report.registryPath}${report.registryExists ? "" : " (absent)"}\n`);
     if (report.registryError)
         process.stdout.write(`registry error: ${report.registryError}\n`);
     process.stdout.write(`registered ledgers: ${report.summary.ledgers} (${report.summary.ok} ok, ${report.summary.stale} stale, ${report.summary.invalid} invalid)\n`);
     for (const ledger of report.ledgers) {
-        process.stdout.write(`  ${ledger.status} ${ledger.name} ${ledger.path}\n`);
+        process.stdout.write(`  ${attentionGlyph(ledger.status !== "ok")} ${ledger.status} ${ledger.name} ${ledger.path}\n`);
         for (const message of ledger.errors)
             process.stdout.write(`    error: ${message}\n`);
     }
@@ -644,8 +713,13 @@ function printDoctor(report) {
     }
 }
 function handleStatus(parsed, ledgerPath, json) {
+    const agent = boolFlag(parsed, "agent");
     if (boolFlag(parsed, "all")) {
         const report = buildStatusReport(normalizeRegistryPath(stringFlag(parsed, "registry")));
+        if (agent) {
+            printCompactJson(buildStatusAgentPacketAll(report));
+            return report.ok ? 0 : 1;
+        }
         if (json) {
             printJson(report);
             return report.ok ? 0 : 1;
@@ -654,6 +728,10 @@ function handleStatus(parsed, ledgerPath, json) {
         return report.ok ? 0 : 1;
     }
     const ledger = statusLedger({ name: "current", path: ledgerPath, scope: "other", createdAt: "", updatedAt: "" }, false);
+    if (agent) {
+        printCompactJson(buildStatusAgentPacketSingle(ledger, ledgerPath));
+        return ledger.ok ? 0 : 1;
+    }
     if (json) {
         printJson({ ok: ledger.ok, ledger });
         return ledger.ok ? 0 : 1;
@@ -737,23 +815,101 @@ function sumStatusCounts(ledgers, key) {
 function formatStatusCounts(counts) {
     return `active ${counts.active} · due ${counts.due} · manual-review ${counts.manualReview} · missing ${counts.missingPath} · kept ${counts.kept} · pending ${counts.pendingCleanup}`;
 }
+// Actionable categories only — active and kept are healthy states, never
+// attention. Order is fixed so the packet is byte-for-byte deterministic.
+const STATUS_ATTENTION_CATEGORIES = ["due", "manualReview", "missingPath", "pendingCleanup"];
+function statusAttention(counts) {
+    return STATUS_ATTENTION_CATEGORIES.filter((key) => counts[key] > 0);
+}
+function statusCommand(scope, command, ledgerPath) {
+    if (scope === "all")
+        return `artshelf ${command} --all`;
+    return ledgerPath ? `artshelf ${command} --ledger ${ledgerPath}` : `artshelf ${command}`;
+}
+function statusNextAction(blockers, counts, scope, ledgerPath) {
+    if (blockers.length > 0) {
+        const verify = statusCommand(scope, "status", ledgerPath);
+        return `repair ${blockers.length} broken ledger(s) above, then re-run \`${verify}\``;
+    }
+    const review = statusCommand(scope, "review", ledgerPath);
+    if (counts.pendingCleanup > 0 || counts.due > 0) {
+        return `run \`${review}\` to preview cleanup plans; nothing is auto-executed`;
+    }
+    if (counts.manualReview > 0) {
+        return `run \`${review}\` to inspect manual-review records; nothing is auto-executed`;
+    }
+    if (counts.missingPath > 0) {
+        return "inspect missing-path records and `artshelf resolve` the ones no longer needed; nothing is auto-executable";
+    }
+    return "nothing due — no broken ledgers and no due, manual-review, missing-path, or pending cleanup entries";
+}
+function buildStatusAgentPacketAll(report) {
+    const blockers = [];
+    if (report.registryError)
+        blockers.push(`registry unreadable: ${report.registryError}`);
+    for (const ledger of report.ledgers) {
+        if (ledger.status !== "ok") {
+            blockers.push(`${ledger.name} ${ledger.status}${ledger.errors.length ? `: ${ledger.errors[0]}` : ""}`);
+        }
+    }
+    const counts = {
+        active: report.totals.active,
+        due: report.totals.due,
+        manualReview: report.totals.manualReview,
+        missingPath: report.totals.missingPath,
+        kept: report.totals.kept,
+        pendingCleanup: report.totals.pendingCleanup
+    };
+    return {
+        schemaVersion: 1,
+        command: "status",
+        scope: "all",
+        health: report.ok ? "ok" : "attention",
+        registry: { path: report.registryPath, exists: report.registryExists, ok: report.registryOk, error: report.registryError },
+        ledgers: { total: report.totals.ledgers, ok: report.totals.ok, stale: report.totals.stale, invalid: report.totals.invalid },
+        counts,
+        attention: statusAttention(counts),
+        blockers,
+        nextAction: statusNextAction(blockers, counts, "all"),
+        verification: `artshelf status --all --agent --registry ${report.registryPath}`
+    };
+}
+function buildStatusAgentPacketSingle(ledger, ledgerPath) {
+    const blockers = ledger.ok
+        ? []
+        : [`${ledger.status}${ledger.errors.length ? `: ${ledger.errors[0]}` : ""}`];
+    return {
+        schemaVersion: 1,
+        command: "status",
+        scope: "single",
+        health: ledger.ok ? "ok" : "attention",
+        ledgerPath,
+        counts: ledger.counts,
+        attention: statusAttention(ledger.counts),
+        blockers,
+        nextAction: statusNextAction(blockers, ledger.counts, "single", ledgerPath),
+        verification: `artshelf status --agent --ledger ${ledgerPath}`
+    };
+}
 function printStatusAll(report) {
-    process.stdout.write(`artshelf status: ${report.ok ? "ok" : "needs attention"}\n`);
+    const anyActionable = report.ledgers.some((ledger) => statusAttention(ledger.counts).length > 0);
+    process.stdout.write(`${attentionGlyph(!report.ok || anyActionable)} artshelf status: ${report.ok ? "ok" : "needs attention"}\n`);
     process.stdout.write(`registry: ${report.registryPath}${report.registryExists ? "" : " (absent)"} — ${report.totals.ledgers} ledgers (${report.totals.ok} ok, ${report.totals.stale} stale, ${report.totals.invalid} invalid)\n`);
     if (report.registryError)
         process.stdout.write(`registry error: ${report.registryError}\n`);
     for (const ledger of report.ledgers) {
         if (ledger.status === "ok") {
-            process.stdout.write(`[${ledger.name}] ${formatStatusCounts(ledger.counts)}\n`);
+            process.stdout.write(`${attentionGlyph(statusAttention(ledger.counts).length > 0)} [${ledger.name}] ${formatStatusCounts(ledger.counts)}\n`);
         }
         else {
-            process.stdout.write(`[${ledger.name}] ${ledger.status}: ${ledger.errors.join("; ")}\n`);
+            process.stdout.write(`${HUMAN_ATTENTION_GLYPH} [${ledger.name}] ${ledger.status}: ${ledger.errors.join("; ")}\n`);
         }
     }
     process.stdout.write(`total: ${formatStatusCounts(report.totals)}\n`);
 }
 function printStatusSingle(ledger) {
-    process.stdout.write(`artshelf status: ${ledger.ok ? "ok" : ledger.status}\n`);
+    const needsAttention = !ledger.ok || statusAttention(ledger.counts).length > 0;
+    process.stdout.write(`${attentionGlyph(needsAttention)} artshelf status: ${ledger.ok ? "ok" : ledger.status}\n`);
     process.stdout.write(`ledger: ${ledger.path}\n`);
     if (ledger.ok) {
         process.stdout.write(`${formatStatusCounts(ledger.counts)}\n`);
@@ -1008,6 +1164,12 @@ function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
     return 0;
 }
+// Agent/compact surface: a single minified JSON line. The default `--json`
+// stays pretty-printed for audit/debug; agent packets optimize for tokens.
+function printCompactJson(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+    return 0;
+}
 function registeredLedgersOrThrow(registryPath) {
     const ledgers = listRegisteredLedgers(registryPath);
     if (ledgers.length === 0)
@@ -1157,13 +1319,16 @@ function summarizeReview(results) {
     }
     return summary;
 }
-function reviewNextAction(summary) {
+function reviewNextAction(summary, scope, ledgerPath) {
     const broken = summary.invalid + summary.stale;
+    const review = statusCommand(scope, "review", ledgerPath);
     if (broken > 0) {
-        return `repair ${broken} broken ledger(s) above (re-register or fix the file), then re-run \`artshelf review --all\``;
+        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}\``;
     }
     if (summary.executable > 0) {
-        return "run `artshelf cleanup --dry-run --all` to generate plans, then `artshelf cleanup --execute --plan-id <id> --ledger <path>` for each reviewed plan";
+        const dryRun = scope === "all" ? "artshelf cleanup --dry-run --all" : `artshelf cleanup --dry-run${ledgerPath ? ` --ledger ${ledgerPath}` : ""}`;
+        return `run \`${dryRun}\` to generate plans, then \`artshelf cleanup --execute --plan-id <id> --ledger <path>\` for each reviewed plan`;
     }
     if (summary.missingPath > 0) {
         return "inspect missing-path entries and `artshelf resolve` the ones no longer needed; nothing is auto-executable";
@@ -1172,7 +1337,7 @@ function reviewNextAction(summary) {
 }
 function printReviewAll(results, summary, nextAction, registryPath) {
     const needsAttention = summary.invalid + summary.stale + summary.executable + summary.due + summary.manualReview + summary.missingPath > 0;
-    process.stdout.write(`artshelf review --all: ${needsAttention ? "needs attention" : "all clear"}\n`);
+    process.stdout.write(`${attentionGlyph(needsAttention)} artshelf review --all: ${needsAttention ? "needs attention" : "all clear"}\n`);
     process.stdout.write(`registry: ${registryPath} — ${summary.ledgers} ledgers (${summary.ok} ok, ${summary.invalid} invalid, ${summary.stale} stale)\n`);
     printReview(results);
     process.stdout.write(`triage: due ${summary.due} · manual-review ${summary.manualReview} · missing ${summary.missingPath} · executable ${summary.executable} · skipped ${summary.skipped}\n`);
@@ -1181,11 +1346,149 @@ function printReviewAll(results, summary, nextAction, registryPath) {
 function printReview(results) {
     for (const result of results) {
         const visibleDue = result.due.filter((entry) => entry.dueStatus !== "kept");
-        process.stdout.write(`[${result.ledger.name}] ${result.validate.ok ? "ok" : "invalid"}: ${result.validate.entries} entries, ${result.validate.errors.length} errors, ${result.validate.warnings.length} warnings\n`);
+        const needsAttention = !result.validate.ok || visibleDue.length > 0 || result.plan.entries.length > 0;
+        process.stdout.write(`${attentionGlyph(needsAttention)} [${result.ledger.name}] ${result.validate.ok ? "ok" : "invalid"}: ${result.validate.entries} entries, ${result.validate.errors.length} errors, ${result.validate.warnings.length} warnings\n`);
         process.stdout.write(`due/manual/missing: ${visibleDue.length}; plan ${result.plan.planId}: ${result.plan.entries.length} entries, ${result.plan.skipped.length} skipped\n`);
         process.stdout.write(`ledger: ${result.ledger.path}\n`);
     }
 }
+// review is read-only, so every safety guarantee holds unconditionally.
+const REVIEW_SAFETY = {
+    dryRunOnly: true,
+    executeAllRefused: true,
+    noExecuteRan: true,
+    noResolveRan: true,
+    noDeleteRan: true
+};
+// Classify each registered ledger's records into decision groups. Order is
+// fixed (registry order, then a stable per-ledger sub-order) so the packet is
+// byte-for-byte deterministic.
+function buildReviewDecisions(results, scope) {
+    const readyForApproval = [];
+    const needsReviewFirst = [];
+    const blocked = [];
+    const review = scope === "all" ? "artshelf review --all" : "artshelf review";
+    for (const result of results) {
+        const { ledger, validate, due } = result;
+        if (!validate.ok) {
+            const status = existsSync(ledger.path) ? "invalid" : "missing";
+            const repair = scope === "all" ? `re-register or fix ${ledger.path}` : `fix ${ledger.path}`;
+            blocked.push({
+                label: `Repair ${ledger.name} ledger (${status})`,
+                itemIds: [],
+                actionType: "fix-registry",
+                approvalTarget: null,
+                reason: validate.errors[0] ?? `${scope === "all" ? "registered ledger" : "ledger"} is ${status}`,
+                nextStep: `${repair}, then re-run \`${review}\``
+            });
+            continue;
+        }
+        const missingPath = due.filter((entry) => entry.dueStatus === "missing-path");
+        const trashSafe = due.filter((entry) => entry.dueStatus === "due" && entry.cleanup === "trash");
+        const inspectItems = due.filter((entry) => entry.dueStatus === "manual-review" ||
+            (entry.dueStatus === "due" && (entry.cleanup === "review" || entry.cleanup === "delete")));
+        // Ready for approval: missing-path records resolve ledger-only with an exact,
+        // plan-less approval target. Resolution updates the ledger and never touches
+        // files, so it is the one action review can hand an agent directly.
+        if (missingPath.length > 0) {
+            const ids = missingPath.map((entry) => entry.id).sort();
+            readyForApproval.push({
+                label: `Resolve ${ids.length} missing-path record(s) in ${ledger.name}`,
+                itemIds: ids,
+                actionType: "resolve-missing",
+                approvalTarget: `approve artshelf resolve missing ledger ${ledger.path} ids ${ids.join(" ")}`,
+                reason: "the recorded path is already missing",
+                nextStep: "confirm the artifact is no longer needed, then approve the ledger-only resolve"
+            });
+        }
+        // Trash-safe records are cleanup-eligible, but review never mints a plan, so
+        // they carry no approval target: the next step is the dry-run that produces
+        // the reviewed plan id to approve.
+        if (trashSafe.length > 0) {
+            const ids = trashSafe.map((entry) => entry.id).sort();
+            needsReviewFirst.push({
+                label: `Plan cleanup for ${ids.length} trash-eligible artifact(s) in ${ledger.name}`,
+                itemIds: ids,
+                actionType: "cleanup",
+                approvalTarget: null,
+                reason: "disposable artifacts are due but no reviewed cleanup plan exists yet",
+                nextStep: `run \`artshelf cleanup --dry-run --ledger ${ledger.path} --json\`, then approve \`approve artshelf cleanup ledger ${ledger.path} plan <plan-id>\``
+            });
+        }
+        // manual-review and cleanup=review records need a human decision before any
+        // cleanup; cleanup=delete is refused outright. None carry an approval target.
+        if (inspectItems.length > 0) {
+            const ids = inspectItems.map((entry) => entry.id).sort();
+            const hasDelete = inspectItems.some((entry) => entry.cleanup === "delete");
+            needsReviewFirst.push({
+                label: `Inspect ${ids.length} record(s) in ${ledger.name} before cleanup`,
+                itemIds: ids,
+                actionType: "inspect",
+                approvalTarget: null,
+                reason: hasDelete
+                    ? "records need manual review; cleanup=delete is refused and never deletes files"
+                    : "records are held for manual review before any cleanup",
+                nextStep: "inspect each path, then keep, change retention, resolve, or set cleanup=trash and plan a cleanup"
+            });
+        }
+    }
+    return { readyForApproval, needsReviewFirst, blocked };
+}
+function reviewCounts(summary) {
+    return {
+        due: summary.due,
+        manualReview: summary.manualReview,
+        missingPath: summary.missingPath,
+        executable: summary.executable,
+        skipped: summary.skipped
+    };
+}
+function buildReviewAgentPacketAll(results, summary, registryPath) {
+    const groups = buildReviewDecisions(results, "all");
+    return {
+        schemaVersion: 1,
+        command: "review",
+        scope: "all",
+        health: summary.invalid + summary.stale > 0 ? "attention" : "ok",
+        registry: { path: registryPath, exists: existsSync(registryPath) },
+        ledgers: { total: summary.ledgers, ok: summary.ok, stale: summary.stale, invalid: summary.invalid },
+        counts: reviewCounts(summary),
+        decisionSummary: {
+            readyForApproval: groups.readyForApproval.length,
+            needsReviewFirst: groups.needsReviewFirst.length,
+            blocked: groups.blocked.length
+        },
+        readyForApproval: groups.readyForApproval,
+        needsReviewFirst: groups.needsReviewFirst,
+        blocked: groups.blocked,
+        safety: REVIEW_SAFETY,
+        nextAction: reviewNextAction(summary, "all"),
+        verification: `artshelf review --all --agent --registry ${registryPath}`
+    };
+}
+function buildReviewAgentPacketSingle(result, ledgerPath) {
+    const summary = summarizeReview([result]);
+    const groups = buildReviewDecisions([result], "single");
+    return {
+        schemaVersion: 1,
+        command: "review",
+        scope: "single",
+        health: summary.invalid + summary.stale > 0 ? "attention" : "ok",
+        ledgerPath,
+        counts: reviewCounts(summary),
+        decisionSummary: {
+            readyForApproval: groups.readyForApproval.length,
+            needsReviewFirst: groups.needsReviewFirst.length,
+            blocked: groups.blocked.length
+        },
+        readyForApproval: groups.readyForApproval,
+        needsReviewFirst: groups.needsReviewFirst,
+        blocked: groups.blocked,
+        safety: REVIEW_SAFETY,
+        nextAction: reviewNextAction(summary, "single", ledgerPath),
+        verification: `artshelf review --agent --ledger ${ledgerPath}`
+    };
+}
 const COMMAND_GROUPS = [
     {
         group: "Create",
@@ -1387,17 +1690,28 @@ Resolved records stay in the audit trail but no longer participate in due or cle
     }
     if (command === "review") {
         process.stdout.write(`Usage:
-  artshelf review [--ledger <path>] [--json]
-  artshelf review --all [--registry <path>] [--json]
+  artshelf review [--ledger <path>] [--json|--agent]
+  artshelf review --all [--registry <path>] [--json|--agent]
+
+Review runs validate, due, and cleanup plan preview without moving files or
+writing a plan. With --all, review adds aggregate triage counts and the next
+safe action.
 
-Review runs validate, due, and cleanup plan preview without moving files or writing a plan.
-With --all, review adds aggregate triage counts and the next safe action.
+Render modes:
+  (default)  Human summary of validation, triage counts, and the next safe action.
+  --json     Full read-only audit report (backward-compatible).
+  --agent    Compact single-line JSON decision packet for agents: health, triage
+             counts, and classified decision groups (ready for approval, needs
+             review first, blocked) with exact approval targets where they are
+             safe. Review is read-only, so cleanup approval targets are minted by
+             \`cleanup --dry-run\`, never leaked from a preview plan id.
+             Token-efficient; --agent takes precedence over --json.
 `);
         return;
     }
     if (command === "doctor") {
         process.stdout.write(`Usage:
-  artshelf doctor [--registry <path>] [--ledger <path>] [--json]
+  artshelf doctor [--registry <path>] [--ledger <path>] [--json|--agent]
 
 Doctor reports whether Artshelf is healthy on this machine: CLI version, selected
 or default ledger path, selected or global registry path, registered ledger health
@@ -1406,6 +1720,14 @@ selected or default ledger and still requires a reviewed plan id; --all execute
 and cleanup=delete are refused, while physical trash purge requires a separate
 reviewed purge plan.
 
+Render modes:
+  (default)  Human summary of machine health and cleanup safety.
+  --json     Full audit report (backward-compatible; suitable for cron/reporting).
+  --agent    Compact single-line JSON decision packet for agents: health, registry
+             and registered-ledger health, blockers, cleanup-safety posture, next
+             action, and a verify command. Token-efficient; --agent takes
+             precedence over --json.
+
 Run it after install, when --all commands behave unexpectedly, or on a schedule to
 catch stale registry entries. Doctor is read-only. A healthy machine exits 0; a
 broken registry or registered ledger exits non-zero with actionable errors.
@@ -1414,8 +1736,8 @@ broken registry or registered ledger exits non-zero with actionable errors.
     }
     if (command === "status") {
         process.stdout.write(`Usage:
-  artshelf status [--ledger <path>] [--json]
-  artshelf status --all [--registry <path>] [--json]
+  artshelf status [--ledger <path>] [--json|--agent]
+  artshelf status --all [--registry <path>] [--json|--agent]
 
 Status is the lightweight daily "what is going on?" view. Without --all, it
 reports counts for the selected or default ledger only. With --all, it adds
@@ -1423,10 +1745,16 @@ registry health, total ledgers, and aggregated counts across registered ledgers.
 Counts include active artifacts, kept, due, manual-review, missing-path, and
 pending cleanup entries.
 
-Human output is short enough to paste into a chat; \`artshelf status --all --json\`
-is suitable for cron and reporting. Status is read-only: it never creates plans
-or receipts and never mutates records. A healthy selected ledger exits 0; with
---all, a broken registry or any stale or invalid registered ledger exits non-zero.
+Render modes:
+  (default)  Human summary, short enough to paste into a chat.
+  --json     Full audit report (backward-compatible; suitable for cron/reporting).
+  --agent    Compact single-line JSON decision packet for agents: health, counts,
+             attention categories, blockers, next action, and a verify command.
+             Token-efficient; --agent takes precedence over --json.
+
+Status is read-only: it never creates plans or receipts and never mutates
+records. A healthy selected ledger exits 0; with --all, a broken registry or any
+stale or invalid registered ledger exits non-zero.
 `);
         return;
     }

package/docs/agent-monitor.html

@@ -73,7 +73,7 @@ artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <pro
 artshelf ledgers list --json
 
 <span class="c"># review and due-check every registered ledger at once</span>
-artshelf review --all --json
+artshelf review --all --agent
 artshelf due --all --json
 
 <span class="c"># find records this agent owns, across ledgers</span>
@@ -102,12 +102,20 @@ artshelf due --all --json
 
 <span class="c"># the full read-only pass: validate + due + plan preview</span>
 artshelf review --all --json
+artshelf review --all --agent
 
 <span class="c"># CLI version, paths, registry health, safety posture</span>
 artshelf doctor --json
+artshelf doctor --agent
 
 <span class="c"># lightweight counts, cron-friendly</span>
-artshelf status --all --json</code></pre>
+artshelf status --all --json
+artshelf status --all --agent</code></pre>
+            <p>
+              Use <code>--agent</code> for concise monitor decisions and exact next
+              actions. Use <code>--json</code> instead when the job needs full
+              audit/API detail for storage, debugging, or a custom report.
+            </p>
           </section>
 
           <section>

package/docs/agent-review.html

@@ -44,16 +44,22 @@
           <section>
             <h2>Daily review workflow</h2>
             <ol>
-              <li>Read <code>ledgers list</code>, <code>review --all</code>, and <code>trash list --all</code>.</li>
+              <li>Read <code>ledgers list --json</code>, <code>review --all --agent</code>, and <code>trash list --all --json</code>.</li>
               <li>Run explicit-ledger purge dry-runs only when old trash needs review.</li>
               <li>Classify each candidate: <code>trash-safe</code>, <code>needs-human-review</code>, <code>resolve-candidate</code>, or <code>registry-problem</code>.</li>
               <li>Ask only with exact ledger path, reviewed plan id, or ids.</li>
             </ol>
+            <p>
+              Prefer the built-in <code>--agent</code> packet when an acting agent
+              needs the compact decision surface. Use full <code>--json</code>
+              output when you need every ledger field for audit, debugging, or a
+              custom renderer.
+            </p>
           </section>
 
           <section>
             <h2>Review plan report schema</h2>
-            <p>Construct an <code>ArtshelfReviewReport</code> JSON packet first, then render a compact decision card.</p>
+            <p>For richer host cards, attachments, or audit packets, construct an <code>ArtshelfReviewReport</code> JSON packet first, then render a compact decision card.</p>
             <p>
               Use <a href="schemas/artshelf-review-report.schema.json">schemas/artshelf-review-report.schema.json</a>
               and <a href="examples/artshelf-review-report.json">examples/artshelf-review-report.json</a>.

package/docs/agent-usage.html

@@ -87,6 +87,20 @@
             </dl>
           </section>
 
+          <section>
+            <h2>Render modes</h2>
+            <p>
+              <code>review</code>, <code>status</code>, and <code>doctor</code> share three 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>--json</dt><dd>the full audit and API contract: complete machine-readable JSON for debugging and existing integrations, unchanged and backward compatible</dd></div>
+            </dl>
+          </section>
+
           <section>
             <h2>The mental model</h2>
             <ul class="boundary-list">

package/docs/agent-usage.md

@@ -50,6 +50,23 @@ The browsable docs split the workflow into focused child pages:
 - Approval names the exact ledger, 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
+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.
+- **`--json`**: the full audit and API contract — complete machine-readable JSON
+  for debugging and existing integrations, unchanged and backward compatible.
+
+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.
+
 ## Portable Skill
 
 The repo ships a portable skill at

package/docs/reference.html

@@ -120,19 +120,20 @@ artshelf validate [--all] [--json]</code></pre>
           <section class="cmd">
             <div class="cmd-head"><h2>artshelf review / status / doctor</h2><span class="cmd-flag readonly">read-only</span></div>
             <pre><code><span class="c"># validate + due + plan preview in one pass</span>
-artshelf review [--all] [--json]
+artshelf review [--all] [--agent] [--json]
 
 <span class="c"># lightweight dashboard of counts</span>
-artshelf status [--all] [--json]
+artshelf status [--all] [--agent] [--json]
 
 <span class="c"># CLI version, resolved paths, registry health</span>
-artshelf doctor [--json]</code></pre>
+artshelf doctor [--agent] [--json]</code></pre>
             <p>
               <code>review</code> runs validate, due, and a cleanup plan preview in one pass; no-op
               previews report <code>not-created</code>, and <code>--all</code> adds an aggregate triage
               summary 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.
+              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).
             </p>
           </section>
 
@@ -212,13 +213,29 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
           <section>
             <h2>Output mode</h2>
             <p>
-              <code>--json</code> is the agent contract: it switches commands that return data,
-              records, plans, receipts, or health output to machine-readable JSON on stdout.
-              Update notices and other diagnostics stay on stderr and never corrupt JSON output.
+              Every command has a default human render: compact, scannable terminal output with
+              grouped counts, a leading <code>✓</code>/<code>⚠</code> attention glyph on each ledger
+              and the summary line, and a short next action — meant for a person reading the screen,
+              not a wall of raw JSON. The glyphs are plain Unicode (no ANSI color), so redirected
+              output stays clean.
+            </p>
+            <p>
+              <code>review</code>, <code>status</code>, and <code>doctor</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
+              to re-run for verification, so an agent can act without parsing decorative output.
+            </p>
+            <p>
+              <code>--json</code> stays the audit and API contract: the full, pretty-printed report for
+              debugging, audit trails, and existing integrations. It is unchanged and backward compatible,
+              and <code>--agent</code> takes precedence when both are passed. Update notices and other
+              diagnostics stay on stderr and never corrupt JSON or packet output.
             </p>
             <table class="opts">
               <tr><th>option</th><th>meaning</th></tr>
-              <tr><td>--json</td><td>emit machine-readable JSON on commands that return data</td></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>--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.9.0",
+  "version": "0.10.0",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",

package/skills/artshelf/SKILL.md

@@ -59,8 +59,7 @@ npm link
 artshelf doctor
 ```
 
-Install, copy, or reference this portable skill only after the user chooses the
-integration path. Offer to schedule read-only review job delivery in the host runtime.
+Install, copy, or reference this portable skill only after the user chooses the integration path. Offer to schedule read-only review job delivery in the host runtime.
 
 ## Create
 
@@ -72,15 +71,11 @@ artshelf put <path> --reason "<why this exists>" --ttl 3d --kind run-artifact --
 artshelf get <id> --json
 ```
 
-Register backups, quarantine folders, debug output, generated reports, long-run
-evidence, and copied files kept for review. Skip source files, cheap regenerated
-build output, dependency caches, secrets, credential dumps, and artifacts already
-owned by another durable ledger.
+Register backups, quarantine folders, debug output, generated reports, long-run evidence, and copied files kept for review. Skip source files, cheap regenerated
+build output, dependency caches, secrets, credential dumps, and artifacts already owned by another durable ledger.
 
-Defaults: `kind=scratch` for temp dirs, `backup` for rollback copies,
-`run-artifact` for logs/reports/evidence, `quarantine` for isolated questionable
-files. Use `cleanup=review` when judgment is needed and `cleanup=trash` only when
-later disposal is clearly safe.
+Defaults: `kind=scratch` for temp dirs, `backup` for rollback copies, `run-artifact` for logs/reports/evidence, `quarantine` for isolated questionable
+files. Use `cleanup=review` when judgment is needed and `cleanup=trash` only when later disposal is clearly safe.
 
 When JSON registration succeeds, include this deterministic Artshelf footnote:
 
@@ -94,13 +89,15 @@ Use the ledger registry for whole-machine review:
 
 ```bash
 artshelf ledgers list --json
-artshelf status --all --json
-artshelf review --all --json
+artshelf status --all --agent
+artshelf review --all --agent
 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.
 
 Register existing project ledgers explicitly:
 
@@ -144,22 +141,23 @@ Daily Review Workflow: turn raw Artshelf output into a decision packet, not a
 count dump.
 
 1. Run read-only review first: `artshelf ledgers list --json`,
-   `artshelf review --all --json`, and `artshelf trash list --all --json`.
+   `artshelf review --all --agent`, and `artshelf trash list --all --json`.
 2. If cleanup attention exists, run `artshelf cleanup --dry-run --all --json`.
 3. Classify candidates as `trash-safe`, `needs-human-review`,
    `resolve-candidate`, or `registry-problem`.
-4. Use `ArtshelfReviewReport` from
-   `schemas/artshelf-review-report.schema.json`; use
-   `examples/artshelf-review-report.json` as the canonical packet.
-5. Render the compact decision card 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.
+4. 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.
+5. 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.
 6. 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
 
-Deterministic renderer:
+Deterministic compact decision card renderer:
 
 ```bash
 cd /path/to/skills/artshelf