artshelf 0.14.0 → 0.16.0

package/docs/agent-usage.html

@@ -63,7 +63,7 @@
               <a class="ledger-row" href="agent-clean.html">
                 <span class="n">4.4</span>
                 <span class="stage">Clean</span>
-                <span class="what"><span class="cmdline">artshelf cleanup --execute --plan-id &lt;id&gt;</span>Run the one plan the human approved, resolve confirmed ids, and verify the next review is quiet.</span>
+                <span class="what"><span class="cmdline">artshelf cleanup --execute --plan-id &lt;id&gt;</span>Run cleanup or dispose plans the human approved, resolve confirmed ids, and verify the next review is quiet.</span>
               </a>
               <a class="ledger-row" href="agent-purge.html">
                 <span class="n">4.5</span>
@@ -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>, <code>dispose --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

@@ -19,8 +19,8 @@ Use Artshelf as a five-stage loop around agent work:
    paths, and trash state.
 3. **Review**: turn raw output into an `ArtshelfReviewReport` decision packet
    with exact approval targets.
-4. **Clean**: execute approved cleanup plans (which trash, never delete),
-   resolve confirmed ids, then verify quiet.
+4. **Clean**: execute approved cleanup and dispose plans, resolve confirmed ids,
+   then verify quiet.
 5. **Purge**: clear old trash only from a separate, separately reviewed purge
    plan; physical deletion never piggybacks on the cleanup plan.
 
@@ -36,8 +36,8 @@ The browsable docs split the workflow into focused child pages:
   and preview plans.
 - [Review](agent-review.html): decision packet schema, classifications, and
   exact approval wording.
-- [Clean](agent-clean.html): approval-only cleanup, resolve, receipts, and
-  verify-quiet checks.
+- [Clean](agent-clean.html): approval-only cleanup, dispose, resolve, receipts,
+  and verify-quiet checks.
 - [Purge](agent-purge.html): separately reviewed trash purge that physically
   deletes, with its own approval target and receipts.
 
@@ -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`, `dispose --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/index.html

@@ -107,6 +107,10 @@ artshelf review --json</code></pre>
                 <span class="stamp refused">Refused</span>
                 <span><code>cleanup --execute --all</code> does not exist. Execution names one ledger and one reviewed plan id.</span>
               </li>
+              <li>
+                <span class="stamp refused">Refused</span>
+                <span><code>dispose --all</code> does not exist. Disposition is one reviewed record and one plan id at a time.</span>
+              </li>
               <li>
                 <span class="stamp refused">Refused</span>
                 <span>Delete is refused in v1. <code>cleanup=trash</code> quarantines; physical deletion needs a separate reviewed purge plan.</span>

package/docs/install.html

@@ -109,7 +109,7 @@ npm link</code></pre>
               with the full agent setup steps: install the portable skill together
               with its bundled report renderer script, register existing ledgers, and
               ask you first before creating any scheduled review job. Scheduled jobs
-              stay read-only; cleanup and purge execution always come back to you.
+              stay read-only; cleanup, dispose, and purge execution always come back to you.
             </p>
             <p>Copy this one line into your coding agent:</p>
             <pre><code>Follow the instructions in https://github.com/calvinnwq/artshelf/blob/main/INSTALL.md to set up Artshelf in this workspace.</code></pre>
@@ -219,7 +219,7 @@ artshelf review --all --json
 
 and reports what needs attention. Scheduled jobs are review and report only:
 never schedule `artshelf cleanup --execute`, `artshelf ledgers prune --execute`,
-or `artshelf trash purge --execute`.
+`artshelf dispose --execute`, or `artshelf trash purge --execute`.
 
 ## 5. Verify and report
 

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>
 
@@ -207,6 +217,33 @@ artshelf cleanup --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--json]
             </div>
           </section>
 
+          <section class="cmd">
+            <div class="cmd-head"><h2>artshelf dispose</h2><span class="cmd-flag approval">approval-gated</span></div>
+            <pre><code><span class="c"># classify one reviewed record into a reviewed plan</span>
+artshelf dispose --id &lt;id&gt; --action trash-resolve|resolve-only|snooze|keep --dry-run [--reason &lt;text&gt;] [--ttl &lt;ttl&gt;|--retain-until &lt;date&gt;] [--ledger &lt;path&gt;] [--json|--agent]
+
+<span class="c"># execute exactly one reviewed plan (approval only)</span>
+artshelf dispose --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--json]</code></pre>
+            <p>
+              Approval-gated disposition for one reviewed record, usually the next step after
+              <code>get --inspect</code>. <code>--dry-run</code> classifies exactly one record id
+              and action, writes a reviewed plan under <code>dispose-plans/</code> when actionable
+              (and reuses a matching earlier plan id), and prints the exact approval target.
+              <code>--execute</code> binds to one reviewed plan id: it re-snapshots the live
+              subject, refuses status/subject drift or a target conflict, moves the subject to
+              plan-scoped trash for <code>trash-resolve</code>, resolves the row for
+              <code>resolve-only</code>, extends retention for <code>snooze</code>, stamps
+              reviewed-and-kept for <code>keep</code>, and writes a receipt registered as an
+              Artshelf-owned artifact. Reruns are idempotent.
+            </p>
+            <div class="callout" data-kind="boundary">
+              <span class="callout-label">Hard boundary</span>
+              <p>No daemon, no auto-execute, no global execute, no fresh-plan-then-execute, and no
+              physical deletion. <code>dispose --all</code> does not exist; one plan binds one
+              record id to one action.</p>
+            </div>
+          </section>
+
           <section class="cmd">
             <div class="cmd-head"><h2>artshelf trash</h2><span class="cmd-flag approval">approval-gated</span></div>
             <pre><code><span class="c"># show trashed records with provenance and age</span>
@@ -276,9 +313,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>, <code>dispose --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, dispose plan status, 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 +326,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>, <code>dispose --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.16.0",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",

package/skills/artshelf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: artshelf
-description: "Use before any final response, status update, handoff, or done report to check whether created/copied/exported/quarantined/backed-up/preserved non-source files or directories outlive the command; and when registering temporary artifacts, backups, run outputs, debug evidence, daily Artshelf reviews, cleanup plans, trash listings, or trash purge plans with Artshelf."
+description: "Use before any final response, status update, handoff, or done report to check whether created/copied/exported/quarantined/backed-up/preserved non-source files or directories outlive the command; and when registering temporary artifacts, backups, run outputs, debug evidence, daily Artshelf reviews, cleanup plans, dispose plans, trash listings, or trash purge plans with Artshelf."
 ---
 
 # Artshelf
@@ -22,8 +22,8 @@ review packets, and verify results.
   record a clear skip reason.
 - Include reason, TTL or manual-review, cleanup mode, owner, and labels.
 - Report the Artshelf id anywhere restart or cleanup context matters.
-- Use read-only commands freely; execute cleanup, trash purge, or resolve only
-  after exact human approval.
+- Use read-only and dry-run commands freely; execute cleanup, dispose, trash
+  purge, or resolve only after exact human approval.
 - Do not call work done while known eligible artifacts are neither registered
   nor explicitly skipped.
 
@@ -96,9 +96,10 @@ 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`,
+`dispose --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:
 
@@ -131,10 +132,11 @@ artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json
 
 Do not scan arbitrary filesystem locations for ledgers unless the user opted
 into that discovery scope. Scheduled jobs may review registry-prune plans but
-must not execute them. Never schedule cleanup, registry-prune, or purge execution:
+must not execute them. Never schedule cleanup, dispose, registry-prune, or purge execution:
 
 ```bash
 artshelf cleanup --execute --plan-id <id>
+artshelf dispose --execute --plan-id <id>
 artshelf ledgers prune --execute --plan-id <id>
 artshelf trash purge --execute --plan-id <id>
 ```
@@ -150,13 +152,17 @@ 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.
 7. Render full packets with `scripts/render-review-report.mjs`; keep
    `decisionSummary` in audit, while `decisionGroups` drive counts. Emojis are encouraged only in host-specific wrappers, not the renderer.
-8. Always include the exact approval target in the message body as a fallback.
+8. For one inspected decision that needs a disposition plan, run `artshelf dispose --id <id> --action <trash-resolve|resolve-only|snooze|keep> --dry-run --ledger <ledger-path> --json` and include its exact approval target.
+9. 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
@@ -168,41 +174,15 @@ cd /path/to/skills/artshelf
 node scripts/render-review-report.mjs examples/artshelf-review-report.json
 ```
 
-Expected card shape:
-
-```text
-Artshelf daily review
-Status: <ok|attention needed>; registry <ok|attention>
-
-Ready for approval: <n>
-Needs review first: <n>
-Blocked: <n>
-
-Recommended action
-<one short sentence>.
-
-Ready for approval
-1. <label>
-   Why: <reason>
-   Action: <next step>
-   <approval target>
-
-Needs review first
-1. <label>
-   Why: <reason>
-   Suggested next step: <next step>
-
-Blocked
-<none, or blocker and repair step>
-
-Safety
-Dry-run only. No execute, resolve, or delete ran.
-```
+The renderer owns the exact layout.
+It emits `Artshelf daily review`, `Ready for approval`, `Needs review first`, `Blocked`, `Recommended action`, `Why:`, `Action:`, `Suggested next step:`, and `Safety`.
+Its safety line stays: `Dry-run only. No execute, resolve, or delete ran.`
 
 Approval wording:
 
 ```text
 approve artshelf cleanup ledger <ledger-path> plan <plan-id>
+approve artshelf dispose ledger <ledger-path> plan <dispose-plan-id>
 approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id>
 approve artshelf resolve missing ledger <ledger-path> ids <id...>
 approve artshelf reconcile ledger <ledger-path> plan <plan-id>
@@ -210,7 +190,7 @@ approve artshelf ledgers prune registry <registry-path> plan <plan-id>
 ```
 
 Never execute from a read-only preview id. Never generate a fresh plan and
-execute it in the same step. After cleanup, resolve, or registry-prune approval, verify with `artshelf review --all --json` and `artshelf ledgers list --json`; after trash purge approval, also run `artshelf trash list --all --json`.
+execute it in the same step. After cleanup, dispose, resolve, or registry-prune approval, verify with `artshelf review --all --json` and `artshelf ledgers list --json`; after trash purge approval, also run `artshelf trash list --all --json`.
 
 ## Clean
 
@@ -226,6 +206,18 @@ If cleanup is interrupted, rerun the same plan id; durable receipt/trash
 evidence resumes or replays without a fresh plan. `cleanup=trash` quarantines
 files into Artshelf trash. Physical deletion belongs to the separate Purge stage.
 
+Dispose execution requires approval naming the reviewed ledger and plan id:
+
+```bash
+artshelf dispose --execute --plan-id <id> --ledger <ledger-path> --json
+```
+
+`dispose` applies one inspected record decision: `trash-resolve` moves the
+subject into plan-scoped Artshelf trash and resolves the row, `resolve-only`
+closes the row without moving files, `snooze` extends retention, and `keep`
+stamps the record reviewed-and-kept. It refuses `--all`, stale plans, target
+conflicts, fresh-plan-then-execute, and physical deletion.
+
 Resolve only after confirmation; it updates the ledger and does not move or
 delete files: