artshelf 0.4.1 → 0.6.0

package/schemas/artshelf-review-report.schema.json

@@ -0,0 +1,315 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://calvinnwq.github.io/artshelf/schemas/artshelf-review-report.schema.json",
+  "title": "ArtshelfReviewReport",
+  "description": "Machine-readable decision packet for rendering an Artshelf review report.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "scope",
+    "decisionSummary",
+    "decisionGroups",
+    "summary",
+    "recommendation",
+    "items",
+    "alternatives",
+    "safety",
+    "verification"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["registryPath", "ledgerCount", "health", "registryHealth"],
+      "properties": {
+        "registryPath": { "type": "string" },
+        "ledgerCount": { "type": "integer", "minimum": 0 },
+        "health": { "type": "string", "enum": ["ok", "attention"] },
+        "registryHealth": { "type": "string", "enum": ["ok", "attention"] },
+        "affectedLedgers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["ledgerPath"],
+            "properties": {
+              "name": { "type": "string" },
+              "ledgerPath": { "type": "string" },
+              "validationStatus": {
+                "type": "string",
+                "enum": ["ok", "missing", "invalid"]
+              }
+            }
+          }
+        }
+      }
+    },
+    "plans": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/plan" },
+      "default": []
+    },
+    "decisionSummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["readyForApproval", "needsReviewFirst", "blocked"],
+      "properties": {
+        "readyForApproval": { "type": "integer", "minimum": 0 },
+        "needsReviewFirst": { "type": "integer", "minimum": 0 },
+        "blocked": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "decisionGroups": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["readyForApproval", "needsReviewFirst", "blocked"],
+      "properties": {
+        "readyForApproval": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/approvalDecision" }
+        },
+        "needsReviewFirst": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/nonApprovalDecision" }
+        },
+        "blocked": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/nonApprovalDecision" }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "executable",
+        "skipped",
+        "refused",
+        "manualReview",
+        "missingPath",
+        "trashed"
+      ],
+      "properties": {
+        "executable": { "type": "integer", "minimum": 0 },
+        "skipped": { "type": "integer", "minimum": 0 },
+        "refused": { "type": "integer", "minimum": 0 },
+        "manualReview": { "type": "integer", "minimum": 0 },
+        "missingPath": { "type": "integer", "minimum": 0 },
+        "trashed": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "recommendation": { "type": "string", "minLength": 1 },
+    "items": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/item" }
+    },
+    "alternatives": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "safety": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "dryRunOnly",
+        "executeAllRefused",
+        "noExecuteRan",
+        "noResolveRan",
+        "noDeleteRan"
+      ],
+      "properties": {
+        "dryRunOnly": { "type": "boolean" },
+        "executeAllRefused": { "type": "boolean" },
+        "noExecuteRan": { "type": "boolean" },
+        "noResolveRan": { "type": "boolean" },
+        "noDeleteRan": { "type": "boolean" }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "successCondition"],
+      "properties": {
+        "command": { "type": "string", "minLength": 1 },
+        "successCondition": { "type": "string", "minLength": 1 }
+      }
+    }
+  },
+  "$defs": {
+    "plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "ledgerPath", "planId", "approvalTarget"],
+      "properties": {
+        "type": { "type": "string", "enum": ["cleanup", "trash-purge"] },
+        "ledgerPath": { "type": "string" },
+        "planId": { "type": "string" },
+        "planPath": { "type": ["string", "null"] },
+        "approvalTarget": { "type": "string" }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "type": { "const": "cleanup" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "approvalTarget": {
+                "pattern": "^approve artshelf cleanup ledger .+ plan .+$"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "trash-purge" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "approvalTarget": {
+                "pattern": "^approve artshelf trash purge ledger .+ plan .+$"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "item": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "classification",
+        "proposedAction",
+        "dueStatus",
+        "reason",
+        "note"
+      ],
+      "properties": {
+        "id": { "type": "string" },
+        "path": { "type": "string" },
+        "classification": {
+          "type": "string",
+          "enum": [
+            "trash-safe",
+            "needs-human-review",
+            "resolve-candidate",
+            "registry-problem"
+          ]
+        },
+        "proposedAction": { "type": "string", "minLength": 1 },
+        "dueStatus": {
+          "type": "string",
+          "enum": ["kept", "due", "manual-review", "missing-path", "trashed"]
+        },
+        "reason": { "type": "string", "minLength": 1 },
+        "note": { "type": "string", "minLength": 1 }
+      },
+      "anyOf": [
+        { "required": ["id"] },
+        { "required": ["path"] }
+      ]
+    },
+    "decision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "actionType", "reason", "nextStep"],
+      "properties": {
+        "label": { "type": "string", "minLength": 1 },
+        "itemIds": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "default": []
+        },
+        "actionType": {
+          "type": "string",
+          "enum": [
+            "cleanup",
+            "trash-purge",
+            "resolve-missing",
+            "inspect",
+            "fix-registry",
+            "keep-or-snooze",
+            "change-retention"
+          ]
+        },
+        "approvalTarget": { "type": ["string", "null"] },
+        "reason": { "type": "string", "minLength": 1 },
+        "nextStep": { "type": "string", "minLength": 1 }
+      }
+    },
+    "approvalDecision": {
+      "allOf": [
+        { "$ref": "#/$defs/decision" },
+        {
+          "required": ["approvalTarget"],
+          "properties": {
+            "actionType": {
+              "enum": ["cleanup", "trash-purge", "resolve-missing"]
+            },
+            "approvalTarget": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "if": {
+            "properties": { "actionType": { "const": "cleanup" } },
+            "required": ["actionType"]
+          },
+          "then": {
+            "properties": {
+              "approvalTarget": {
+                "pattern": "^approve artshelf cleanup ledger .+ plan .+$"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "actionType": { "const": "trash-purge" } },
+            "required": ["actionType"]
+          },
+          "then": {
+            "properties": {
+              "approvalTarget": {
+                "pattern": "^approve artshelf trash purge ledger .+ plan .+$"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "actionType": { "const": "resolve-missing" } },
+            "required": ["actionType"]
+          },
+          "then": {
+            "properties": {
+              "approvalTarget": {
+                "pattern": "^approve artshelf resolve missing ledger .+ ids .+$"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "nonApprovalDecision": {
+      "allOf": [
+        { "$ref": "#/$defs/decision" },
+        {
+          "properties": {
+            "actionType": {
+              "enum": ["inspect", "fix-registry", "keep-or-snooze", "change-retention"]
+            },
+            "approvalTarget": { "type": "null" }
+          }
+        }
+      ]
+    }
+  }
+}

package/skills/artshelf/SKILL.md

@@ -25,6 +25,10 @@ fresh. Do not infer intent later from filesystem age or path names.
   labels.
 - Capture the Artshelf id in handoffs, PRs, issue comments, memory, or run
   summaries when the artifact matters for restart or review.
+- When `artshelf put --json` succeeds, report a deterministic Artshelf footnote
+  in the same handoff, status, final response, or run summary that mentions the
+  artifact. Include the path, Artshelf id, short reason, due date or
+  `manual-review`, and cleanup mode.
 - Cleanup execution is approval-only. Read-only review is fine; mutation needs
   a reviewed plan id and explicit human approval.
 
@@ -121,7 +125,7 @@ next safe action.
 them explicitly:
 
 ```bash
-artshelf ledgers add --ledger <repo>/.shelf/ledger.jsonl --name <project> --scope repo --json
+artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --scope repo --json
 ```
 
 `--all` is for discovery and review. Do not use it as permission to mutate
@@ -165,11 +169,78 @@ 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` for the packet shape and
+`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>
+
+Recommended action
+<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
@@ -219,6 +290,13 @@ Artshelf artifact: shf_20260601_182800_ab12, /tmp/parser-output, retain until
 2026-06-04, cleanup=review.
 ```
 
+When a machine-readable registration succeeds, use the same deterministic
+footnote shape:
+
+```text
+Artshelf footnote: registered <artifact-path> as <artshelf-id>; reason: <short reason>; due: <YYYY-MM-DD|manual-review>; cleanup=<cleanup-mode>.
+```
+
 ## Completion Check
 
 Before finalizing a task, review your own file actions:
@@ -283,8 +361,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/skills/artshelf/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"
+  }
+}