artshelf 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -51,6 +51,21 @@
   available below the lead.
 - Tightened the portable agent skill description so the completion-gate trigger
   is visible before final responses, status updates, handoffs, and done reports.
+- Added packaged `ArtshelfReviewReport` schema and canonical example files for
+  deterministic agent review reports, plus deterministic footnote guidance for
+  `artshelf put --json` registrations.
+
+## [0.6.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.5.0...artshelf-v0.6.0) (2026-06-07)
+
+
+### Features
+
+* **artshelf:** add public review report assets ([6bc89ae](https://github.com/calvinnwq/artshelf/commit/6bc89ae78150bbb161a387f844f32c7ac23f30da))
+
+
+### Bug Fixes
+
+* **docs:** constrain review approval targets ([eccc16d](https://github.com/calvinnwq/artshelf/commit/eccc16d019f1245a9ab052db51137654a2c3363b))
 
 ## [0.5.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.4.1...artshelf-v0.5.0) (2026-06-05)
 

package/README.md

@@ -243,15 +243,18 @@ quickstart, agent usage, and CLI reference. The source repo also keeps the
 
 The package includes an agent-facing skill at `skills/artshelf/SKILL.md`. Agents
 that support local skills can copy or reference this file to learn when to call
-`artshelf put`, how to report Artshelf ids in handoffs and issue comments, why
-`artshelf find` / `artshelf get` are the read-only idempotency lookup surface, why
-`cleanup --execute` requires explicit approval for a reviewed plan id, how to
-review trashed records with `artshelf trash list` before a separately approved trash
-purge, and when `artshelf resolve <id> --status resolved --reason <text>` may mark
-confirmed handled, missing, or no-longer-needed records without moving or
-deleting files.
-
-The same skill ships in the npm package. From a source checkout, use
+`artshelf put`, how to report deterministic Artshelf footnotes after JSON
+registration, why `artshelf find` / `artshelf get` are the read-only idempotency
+lookup surface, why `cleanup --execute` requires explicit approval for a
+reviewed plan id, how to render dry-run cleanup and trash purge plans as
+review-report decision packets, how to review trashed records with
+`artshelf trash list` before a separately approved trash purge, and when
+`artshelf resolve <id> --status resolved --reason <text>` may mark confirmed
+handled, missing, or no-longer-needed records without moving or deleting files.
+
+The same skill ships in the npm package alongside
+`schemas/artshelf-review-report.schema.json` and the canonical
+`examples/artshelf-review-report.json` packet. From a source checkout, use
 `skills/artshelf/SKILL.md` directly. Agents should ask where the user wants
 Artshelf cloned before installing or linking it.
 

package/SPEC.md

@@ -597,11 +597,26 @@ Agents may run `artshelf find` and `artshelf get` before `put` to avoid duplicat
 registrations. `find`/`get` are read-only ledger queries; they must not be used
 as permission to clean up or resolve a record.
 
+When `artshelf put --json` succeeds, agents should include a deterministic
+Artshelf footnote in the same handoff, status, final response, or run summary
+that mentions the artifact:
+
+```text
+Artshelf footnote: registered <artifact-path> as <artshelf-id>; reason: <short reason>; due: <YYYY-MM-DD|manual-review>; cleanup=<cleanup-mode>.
+```
+
 Agents may run `artshelf resolve <id> --status resolved --reason <text>` only
 after explicit confirmation that the record has been handled, is missing, or is
 no longer needed. The reason must be specific; resolve does not move or delete
 files.
 
+For batches of missing-path records, agents should ask for exact approval before
+resolving:
+
+```text
+approve artshelf resolve missing ledger <ledger-path> ids <id...>
+```
+
 Scheduled jobs may run:
 
 ```bash
@@ -626,6 +641,15 @@ registered-ledger discovery and should include trashed record counts and target
 ages. Purge dry-runs stay scoped to one explicit ledger and should report any
 plan id, matching entries, and skipped entries.
 
+When a scheduled review or dry-run produces cleanup or trash purge plans,
+deterministic integrations should build an `ArtshelfReviewReport` packet first,
+then render a compact decision report from it. The packet schema is
+`schemas/artshelf-review-report.schema.json`, the canonical example is
+`examples/artshelf-review-report.json`, and packaged docs/skills carry matching
+copies for browsable docs and portable agent installs. The report groups
+decisions into ready-for-approval, needs-review-first, and blocked sections, and
+must still include exact approval targets in the message body.
+
 Scheduled jobs must never run `artshelf cleanup --execute` or
 `artshelf trash purge --execute`; they may only dry-run and report plans for later
 human review.
@@ -666,6 +690,8 @@ human review.
 - CLI can list trashed records (single ledger or `--all`) and purge them through
   an approval-first, ledger-scoped dry-run/execute boundary that writes a purge
   receipt; purge refuses `--all` and never deletes without a reviewed plan id.
+- Package includes the deterministic `ArtshelfReviewReport` schema and canonical
+  example for agent-rendered review reports.
 - All core commands support `--json`.
 - Tests cover record/list/find/get/status-filter/due/validate/resolve/registry,
   `artshelf doctor`, the `artshelf status` dashboard, `--all` review, stale-registry,

package/docs/agent-usage.html

@@ -193,8 +193,79 @@ artshelf trash list --all --json</code></pre>
               <pre><code>artshelf trash list --ledger &lt;ledger-path&gt;
 artshelf trash purge --older-than 7d --dry-run --ledger &lt;ledger-path&gt; --json
 artshelf trash purge --execute --plan-id &lt;purge-plan-id&gt; --ledger &lt;ledger-path&gt; --json</code></pre>
+              <h3>Review Plan Report Schema</h3>
+              <p>
+                When a dry-run creates or reuses a cleanup or trash purge plan, surface the
+                plan in a compact human-readable report. The report should let the user
+                approve, ask for changes, or request alternatives without opening the plan
+                file.
+              </p>
+              <p>
+                For deterministic agent integrations, construct an
+                <code>ArtshelfReviewReport</code> JSON object first, then render it to text.
+                Use <a href="schemas/artshelf-review-report.schema.json">schemas/artshelf-review-report.schema.json</a>
+                for the packet shape and
+                <a href="examples/artshelf-review-report.json">examples/artshelf-review-report.json</a>
+                as the canonical example. The schema locks report structure; the CLI output
+                and approval rules still define cleanup safety.
+              </p>
+              <p>
+                Render the JSON packet as a compact decision card using
+                <code>decisionSummary</code> and <code>decisionGroups</code>. Lead with
+                counts, then show exactly what is ready for approval and what needs review
+                first. Emojis are encouraged when the host renders them well because they
+                make review groups scannable; omit them only for plain-text or
+                accessibility-constrained surfaces.
+              </p>
+              <pre><code>Artshelf daily review
+Status: &lt;ok|attention needed&gt;; registry &lt;ok|attention&gt;
+
+✅ Ready for approval: &lt;n&gt;
+👀 Needs review first: &lt;n&gt;
+⚠️ Blocked: &lt;n&gt;
+
+Recommendation
+&lt;one short sentence with the next safest action&gt;.
+
+Ready for approval
+1. &lt;short item label&gt;
+   Why: &lt;short reason&gt;
+   Action: &lt;what approval will do&gt;
+   approve artshelf cleanup ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;
+
+2. &lt;short item label&gt;
+   Why: &lt;short reason&gt;
+   Action: &lt;ledger-only update, no file changes&gt;
+   approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;
+
+Needs review first
+1. &lt;short item label&gt;
+   Why: &lt;short reason&gt;
+   Suggested next step: inspect path, then choose keep, change retention, resolve, or clean up later
+   Path: &lt;path&gt;
+
+Blocked
+&lt;none, or the registry/refused/missing-path blocker and next repair step&gt;
+
+Safety
+Dry-run only. No execute, resolve, or delete ran.</code></pre>
+              <p>
+                Keep the full <code>ArtshelfReviewReport</code> JSON as the audit packet
+                and include it as an attachment, linked file, or expandable detail when the
+                host supports that. Do not paste the whole packet into chat unless the user
+                asks for it. For long plans, show only the first 3 to 5 decisions under
+                each visible group, then state the hidden count by group and classification.
+                Do not hide refused, registry-problem, or missing-path items.
+              </p>
+              <p>
+                If the host supports buttons, menus, or other interactive controls, they
+                should emit exact text commands such as the approval targets below. Always
+                include the exact approval target in the message body as a fallback for
+                clients where those controls do not render.
+              </p>
               <pre><code>approve artshelf cleanup ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;
-approve artshelf trash purge ledger &lt;ledger-path&gt; plan &lt;purge-plan-id&gt;</code></pre>
+approve artshelf trash purge ledger &lt;ledger-path&gt; plan &lt;purge-plan-id&gt;
+approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;</code></pre>
               <div class="note">
                 Never execute from a read-only preview id. Never generate a fresh plan and execute
                 it in the same step. <code>trash</code> moves artifacts into Artshelf trash; physical
@@ -216,6 +287,12 @@ approve artshelf trash purge ledger &lt;ledger-path&gt; plan &lt;purge-plan-id&g
                 skipped instead of registered, include the brief skip reason from the
                 completion checklist.
               </p>
+              <p>
+                When <code>artshelf put --json</code> succeeds, include a deterministic Artshelf
+                footnote in the same handoff, status, final response, or run summary that
+                mentions the artifact.
+              </p>
+              <pre><code>Artshelf footnote: registered &lt;artifact-path&gt; as &lt;artshelf-id&gt;; reason: &lt;short reason&gt;; due: &lt;YYYY-MM-DD|manual-review&gt;; cleanup=&lt;cleanup-mode&gt;.</code></pre>
             </section>
 
             <section>
@@ -250,8 +327,14 @@ artshelf trash purge --execute --plan-id &lt;purge-plan-id&gt; --ledger &lt;ledg
               <pre><code>artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt;</code></pre>
               <p>
                 Use a specific reason. <code>resolve</code> only updates the ledger; it does not
-                move or delete files. Resolved records stop reappearing in future due and
-                dry-run cleanup output while remaining visible through
+                move or delete files. For batches of missing-path records, ask for approval that
+                names the exact ledger and ids.
+              </p>
+              <pre><code>approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;</code></pre>
+              <p>
+                After resolution, verify with <code>artshelf review --all --json</code> and report
+                whether the review is quiet or what remains. Resolved records stop reappearing
+                in future due and dry-run cleanup output while remaining visible through
                 <code>artshelf list --status resolved</code>.
               </p>
             </section>

package/docs/agent-usage.md

@@ -92,6 +92,13 @@ Useful defaults for agents:
   repo, PR, issue, workflow id, or run id.
 
 Use `--json` when another tool needs to capture the Artshelf entry id.
+When `artshelf put --json` succeeds, include a deterministic Artshelf footnote in
+the same handoff, status, final response, or run summary that mentions the
+artifact:
+
+```text
+Artshelf footnote: registered <artifact-path> as <artshelf-id>; reason: <short reason>; due: <YYYY-MM-DD|manual-review>; cleanup=<cleanup-mode>.
+```
 
 ## Idempotent Lookup
 
@@ -194,11 +201,79 @@ artshelf trash purge --execute --plan-id <purge-plan-id> --ledger <ledger-path>
    `artshelf review --all --json`, plus `artshelf trash list --ledger <ledger-path> --json`
    and purge receipt evidence after purge, or explain what remains.
 
+### Review Plan Report Schema
+
+When a dry-run creates or reuses a cleanup or trash purge plan, surface the plan
+in a compact human-readable report. The report should let the user approve, ask
+for changes, or request alternatives without opening the plan file.
+
+For deterministic agent integrations, construct an `ArtshelfReviewReport` JSON
+object first, then render it to text. Use
+[`schemas/artshelf-review-report.schema.json`](schemas/artshelf-review-report.schema.json)
+for the packet shape and
+[`examples/artshelf-review-report.json`](examples/artshelf-review-report.json)
+as the canonical example. The schema locks report structure; the CLI output and
+approval rules still define cleanup safety.
+
+Render the JSON packet as a compact decision card using `decisionSummary` and
+`decisionGroups`. Lead with counts, then show exactly what is ready for approval
+and what needs review first. Emojis are encouraged when the host renders them
+well because they make the groups scannable; omit them only for plain-text or
+accessibility-constrained surfaces.
+
+```text
+Artshelf daily review
+Status: <ok|attention needed>; registry <ok|attention>
+
+✅ Ready for approval: <n>
+👀 Needs review first: <n>
+⚠️ Blocked: <n>
+
+Recommendation
+<one short sentence with the next safest action>.
+
+Ready for approval
+1. <short item label>
+   Why: <short reason>
+   Action: <what approval will do>
+   approve artshelf cleanup ledger <ledger-path> plan <plan-id>
+
+2. <short item label>
+   Why: <short reason>
+   Action: <ledger-only update, no file changes>
+   approve artshelf resolve missing ledger <ledger-path> ids <id...>
+
+Needs review first
+1. <short item label>
+   Why: <short reason>
+   Suggested next step: inspect path, then choose keep, change retention, resolve, or clean up later
+   Path: <path>
+
+Blocked
+<none, or the registry/refused/missing-path blocker and next repair step>
+
+Safety
+Dry-run only. No execute, resolve, or delete ran.
+```
+
+Keep the full `ArtshelfReviewReport` JSON as the audit packet and include it as
+an attachment, linked file, or expandable detail when the host supports that.
+Do not paste the whole packet into chat unless the user asks for it. For long
+plans, show only the first 3 to 5 decisions under each visible group, then state
+the hidden count by group and classification. Do not hide refused,
+registry-problem, or missing-path items.
+
+If the host supports buttons, menus, or other interactive controls, they should
+emit exact text commands such as the approval targets below. Always include the
+exact approval target in the message body as a fallback for clients where those
+controls do not render.
+
 Approval wording should be exact:
 
 ```text
 approve artshelf cleanup ledger <ledger-path> plan <plan-id>
 approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id>
+approve artshelf resolve missing ledger <ledger-path> ids <id...>
 ```
 
 Never execute from a read-only preview id. Never generate a fresh plan and
@@ -309,8 +384,17 @@ artshelf resolve <id> --status resolved --reason <text>
 ```
 
 Use a specific reason. `resolve` only updates the ledger; it does not move or
-delete files. Resolved records stop reappearing in future due and dry-run
-cleanup output while remaining visible in `artshelf list --status resolved`.
+delete files. For batches of missing-path records, ask for approval that names
+the exact ledger and ids:
+
+```text
+approve artshelf resolve missing ledger <ledger-path> ids <id...>
+```
+
+After resolution, verify with `artshelf review --all --json` and report whether
+the review is quiet or what remains. Resolved records stop reappearing in future
+due and dry-run cleanup output while remaining visible in
+`artshelf list --status resolved`.
 
 ## Scheduled Review
 

package/docs/examples/artshelf-review-report.json

@@ -0,0 +1,116 @@
+{
+  "schemaVersion": 1,
+  "scope": {
+    "registryPath": "~/.artshelf/ledgers.json",
+    "ledgerCount": 3,
+    "health": "attention",
+    "registryHealth": "ok",
+    "affectedLedgers": [
+      {
+        "name": "example-project",
+        "ledgerPath": "/path/to/example-project/.artshelf/ledger.jsonl",
+        "validationStatus": "ok"
+      }
+    ]
+  },
+  "plans": [
+    {
+      "type": "cleanup",
+      "ledgerPath": "/path/to/example-project/.artshelf/ledger.jsonl",
+      "planId": "plan_20260606_120000_ab12",
+      "planPath": "/path/to/example-project/.artshelf/plans/plan_20260606_120000_ab12.json",
+      "approvalTarget": "approve artshelf cleanup ledger /path/to/example-project/.artshelf/ledger.jsonl plan plan_20260606_120000_ab12"
+    }
+  ],
+  "summary": {
+    "executable": 1,
+    "skipped": 2,
+    "refused": 0,
+    "manualReview": 1,
+    "missingPath": 1,
+    "trashed": 0
+  },
+  "decisionSummary": {
+    "readyForApproval": 2,
+    "needsReviewFirst": 1,
+    "blocked": 0
+  },
+  "decisionGroups": {
+    "readyForApproval": [
+      {
+        "label": "Clean up temp debug output",
+        "itemIds": ["shf_20260606_120000_ab12"],
+        "actionType": "cleanup",
+        "approvalTarget": "approve artshelf cleanup ledger /path/to/example-project/.artshelf/ledger.jsonl plan plan_20260606_120000_ab12",
+        "reason": "Disposable temp artifact has a reviewed cleanup plan.",
+        "nextStep": "Approve the exact cleanup plan to move the artifact into Artshelf trash."
+      },
+      {
+        "label": "Resolve missing report record",
+        "itemIds": ["shf_20260606_120500_cd34"],
+        "actionType": "resolve-missing",
+        "approvalTarget": "approve artshelf resolve missing ledger /path/to/example-project/.artshelf/ledger.jsonl ids shf_20260606_120500_cd34",
+        "reason": "The report path is already missing.",
+        "nextStep": "Approve the ledger-only resolve command after confirming the report is no longer needed."
+      }
+    ],
+    "needsReviewFirst": [
+      {
+        "label": "Inspect lifecycle smoke report",
+        "itemIds": ["shf_20260606_121000_ef56"],
+        "actionType": "inspect",
+        "approvalTarget": null,
+        "reason": "cleanup=review means the artifact should be inspected before closing.",
+        "nextStep": "Inspect the path, then choose keep, change retention, resolve, or clean up later."
+      }
+    ],
+    "blocked": []
+  },
+  "recommendation": "Approve the reviewed cleanup plan for the disposable temp directory, then resolve the missing record after confirming it is no longer needed.",
+  "items": [
+    {
+      "id": "shf_20260606_120000_ab12",
+      "path": "/tmp/example-debug-output",
+      "classification": "trash-safe",
+      "proposedAction": "execute reviewed cleanup plan",
+      "dueStatus": "due",
+      "reason": "temporary debug output retained for 3 days",
+      "note": "The path exists, cleanup=trash, and the dry-run plan moves it into Artshelf trash."
+    },
+    {
+      "id": "shf_20260606_120500_cd34",
+      "path": "/tmp/missing-report.json",
+      "classification": "resolve-candidate",
+      "proposedAction": "resolve ledger-only after confirmation",
+      "dueStatus": "missing-path",
+      "reason": "report path is already missing",
+      "note": "Resolution updates only the ledger and does not move or delete files."
+    },
+    {
+      "id": "shf_20260606_121000_ef56",
+      "path": "/tmp/lifecycle-smoke-report.json",
+      "classification": "needs-human-review",
+      "proposedAction": "inspect before choosing cleanup or retention",
+      "dueStatus": "manual-review",
+      "reason": "cleanup=review artifact retained for manual inspection",
+      "note": "No approval target is shown until the review decision is known."
+    }
+  ],
+  "alternatives": [
+    "keep the artifact and change retention",
+    "inspect the path before approving cleanup",
+    "regenerate the plan after edits",
+    "resolve missing records ledger-only"
+  ],
+  "safety": {
+    "dryRunOnly": true,
+    "executeAllRefused": true,
+    "noExecuteRan": true,
+    "noResolveRan": true,
+    "noDeleteRan": true
+  },
+  "verification": {
+    "command": "artshelf review --all --json",
+    "successCondition": "no due, manual-review, missing-path, executable, or refused entries remain unless explicitly reported"
+  }
+}