artshelf 0.12.0 → 0.13.1

package/dist/src/renderers/review.js

@@ -7,7 +7,7 @@ const REVIEW_SAFETY = {
     noResolveRan: true,
     noDeleteRan: true
 };
-export function reviewNextAction(summary, scope, ledgerPath) {
+export function reviewNextAction(summary, scope, ledgerPath, registryPath) {
     const broken = summary.invalid + summary.stale;
     const review = statusCommand(scope, "review", ledgerPath);
     if (broken > 0) {
@@ -18,25 +18,30 @@ export function reviewNextAction(summary, scope, ledgerPath) {
         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";
+    if (summary.missingPath > 0 || summary.reconcileEntries > 0 || summary.reconcileBlocked > 0) {
+        const reconcile = scope === "all" ? `artshelf reconcile --dry-run --all${registryPath ? ` --registry ${registryPath}` : ""}` : `artshelf reconcile --dry-run --ledger ${ledgerPath}`;
+        return `run \`${reconcile} --json\` and then \`${review}\` to surface reconcile-ready approvals; nothing is auto-executable`;
     }
     return "nothing to do — no broken ledgers and no due, manual-review, missing-path, or executable cleanup entries";
 }
 export function printReviewAll(results, summary, nextAction, registryPath) {
-    const needsAttention = summary.invalid + summary.stale + summary.executable + summary.due + summary.manualReview + summary.missingPath > 0;
+    const needsAttention = summary.invalid + summary.stale + summary.executable + summary.due + summary.manualReview + summary.missingPath + summary.reconcileEntries + summary.reconcileBlocked > 0;
     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`);
+    process.stdout.write(`triage: due ${summary.due} · manual-review ${summary.manualReview} · missing ${summary.missingPath} · executable ${summary.executable} · skipped ${summary.skipped} · reconcile ${summary.reconcileEntries} · blocked ${summary.reconcileBlocked}\n`);
     process.stdout.write(`next: ${nextAction}\n`);
 }
 export function printReview(results) {
     for (const result of results) {
         const visibleDue = result.due.filter((entry) => entry.dueStatus !== "kept");
-        const needsAttention = !result.validate.ok || visibleDue.length > 0 || result.plan.entries.length > 0;
+        const reconcileEntries = result.reconcile?.plan.entries.length ?? 0;
+        const reconcileBlocked = result.reconcile?.plan.blocked.length ?? 0;
+        const reconcileDrift = reconcileEntries + reconcileBlocked;
+        const needsAttention = !result.validate.ok || visibleDue.length > 0 || result.plan.entries.length > 0 || reconcileDrift > 0;
+        const reconcileDetail = reconcileDrift > 0 ? `; reconcile: ${reconcileEntries} entries, ${reconcileBlocked} blocked` : "";
         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(`due/manual/missing: ${visibleDue.length}; plan ${result.plan.planId}: ${result.plan.entries.length} entries, ${result.plan.skipped.length} skipped${reconcileDetail}\n`);
         process.stdout.write(`ledger: ${result.ledger.path}\n`);
     }
 }
@@ -60,7 +65,15 @@ function buildReviewDecisions(results, scope) {
             });
             continue;
         }
-        const missingPath = due.filter((entry) => entry.dueStatus === "missing-path");
+        const handledReconcileIds = new Set([
+            ...(result.reconcile?.plan.entries.map((entry) => entry.id) ?? []),
+            ...(result.reconcile?.plan.blocked.map((entry) => entry.id) ?? [])
+        ]);
+        const reconcileActions = buildReconcileDecisions(result, scope);
+        readyForApproval.push(...reconcileActions.readyForApproval);
+        needsReviewFirst.push(...reconcileActions.needsReviewFirst);
+        blocked.push(...reconcileActions.blocked);
+        const missingPath = due.filter((entry) => entry.dueStatus === "missing-path" && !handledReconcileIds.has(entry.id));
         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")));
@@ -103,6 +116,57 @@ function buildReviewDecisions(results, scope) {
     }
     return { readyForApproval, needsReviewFirst, blocked };
 }
+function buildReconcileDecisions(result, _scope) {
+    if (!result.reconcile)
+        return { readyForApproval: [], needsReviewFirst: [], blocked: [] };
+    const readyForApproval = [];
+    const needsReviewFirst = [];
+    const blocked = [];
+    const hasReviewedPlan = Boolean(result.reconcile.reviewedPlan && result.reconcile.reviewedPlan.planId !== "not-created");
+    const reviewedPlanId = result.reconcile.reviewedPlan?.planId ?? null;
+    const byCategory = {
+        remap: [],
+        "resolve-missing": [],
+        "resolve-stale-trash": [],
+        "registry-remap": [],
+        blocked: []
+    };
+    for (const finding of result.reconcile.plan.entries.concat(result.reconcile.plan.blocked)) {
+        byCategory[finding.category].push(finding);
+    }
+    const reconcileActionCategories = ["remap", "resolve-missing", "resolve-stale-trash", "registry-remap"];
+    for (const category of reconcileActionCategories) {
+        const entries = byCategory[category];
+        if (entries.length === 0)
+            continue;
+        const ids = entries.map((entry) => entry.id).sort();
+        const label = `Review ${entries.length} reconcile ${category} finding(s) in ${result.ledger.name}`;
+        const reason = `recorded paths are ${category === "remap" ? "safe to remap" : "stale and require manual review before execution"}`;
+        const decision = {
+            label,
+            itemIds: ids,
+            actionType: "reconcile",
+            approvalTarget: hasReviewedPlan ? `approve artshelf reconcile ledger ${result.ledger.path} plan ${reviewedPlanId}` : null,
+            reason,
+            nextStep: hasReviewedPlan
+                ? `run \`artshelf reconcile --execute --plan-id ${reviewedPlanId} --ledger ${result.ledger.path}\``
+                : `run \`artshelf reconcile --dry-run --ledger ${result.ledger.path} --json\`, then approve with \`approve artshelf reconcile ledger ${result.ledger.path} plan <plan-id>\``
+        };
+        (hasReviewedPlan ? readyForApproval : needsReviewFirst).push(decision);
+    }
+    if (byCategory.blocked.length > 0) {
+        const entries = byCategory.blocked;
+        blocked.push({
+            label: `Review ${entries.length} blocked reconcile finding(s) in ${result.ledger.name}`,
+            itemIds: entries.map((entry) => entry.id).sort(),
+            actionType: "reconcile",
+            approvalTarget: null,
+            reason: "path drift is ambiguous or unsafe and needs manual investigation",
+            nextStep: `run \`artshelf reconcile --dry-run --ledger ${result.ledger.path} --json\`, then handle each item manually`
+        });
+    }
+    return { readyForApproval, needsReviewFirst, blocked };
+}
 function reviewCounts(summary) {
     return {
         due: summary.due,
@@ -131,7 +195,7 @@ export function buildReviewAgentPacketAll(results, summary, registry) {
         needsReviewFirst: groups.needsReviewFirst,
         blocked: groups.blocked,
         safety: REVIEW_SAFETY,
-        nextAction: reviewNextAction(summary, "all"),
+        nextAction: reviewNextAction(summary, "all", undefined, registry.path),
         verification: `artshelf review --all --agent --registry ${registry.path}`
     };
 }

package/dist/src/renderers/status.js

@@ -14,7 +14,7 @@ export function statusCommand(scope, command, ledgerPath) {
         return `artshelf ${command} --all`;
     return ledgerPath ? `artshelf ${command} --ledger ${ledgerPath}` : `artshelf ${command}`;
 }
-function statusNextAction(blockers, counts, scope, ledgerPath) {
+function statusNextAction(blockers, counts, scope, ledgerPath, registryPath) {
     if (blockers.length > 0) {
         const verify = statusCommand(scope, "status", ledgerPath);
         return `repair ${blockers.length} broken ledger(s) above, then re-run \`${verify}\``;
@@ -27,7 +27,8 @@ function statusNextAction(blockers, counts, scope, ledgerPath) {
         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";
+        const reconcile = scope === "all" ? `artshelf reconcile --dry-run --all${registryPath ? ` --registry ${registryPath}` : ""}` : `artshelf reconcile --dry-run --ledger ${ledgerPath}`;
+        return `run \`${reconcile} --json\` and then \`${review}\` to surface reconcile-ready approvals; nothing is auto-executable`;
     }
     return "nothing due — no broken ledgers and no due, manual-review, missing-path, or pending cleanup entries";
 }
@@ -58,7 +59,7 @@ export function buildStatusAgentPacketAll(report) {
         counts,
         attention: statusAttention(counts),
         blockers,
-        nextAction: statusNextAction(blockers, counts, "all"),
+        nextAction: statusNextAction(blockers, counts, "all", undefined, report.registryPath),
         verification: `artshelf status --all --agent --registry ${report.registryPath}`
     };
 }

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

@@ -188,7 +188,8 @@ Resolved records stay in the audit trail but no longer participate in due or cle
 
 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.
+safe action, including reconcile entry and blocked counts when path drift is
+detected.
 
 Render modes:
   (default)  Human summary of validation, triage counts, and the next safe action.

package/docs/agent-clean.html

@@ -38,8 +38,8 @@
           <h1>Execute only what was reviewed and approved.</h1>
           <p class="lede">
             Clean is meant to be boring. The human approves one plan, the agent runs
-            exactly that plan, writes a receipt, and checks that the next review
-            comes back quiet.
+            exactly that plan, leaves durable receipt evidence before moving files,
+            and checks that the next review comes back quiet.
           </p>
 
           <section>
@@ -90,10 +90,11 @@ artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt;</code></pre>
             <h2>Verify quiet</h2>
             <p>After cleanup execute or resolve, verify with <code>artshelf review --all --json</code>.</p>
             <p>
-              Execution writes a receipt and updates touched ledger records to
-              <code>trashed</code>, <code>review-required</code>, or
-              <code>cleanup-refused</code>. Generated plans and receipts are recorded as
-              <code>owner=artshelf</code> artifacts.
+              Execution writes a started receipt before the first move, completes it after
+              ledger updates, and updates touched ledger records to <code>trashed</code>,
+              <code>review-required</code>, or <code>cleanup-refused</code>. Rerunning the same
+              plan id resumes or idempotently replays durable receipt/trash evidence.
+              Generated plans and receipts are recorded as <code>owner=artshelf</code> artifacts.
             </p>
           </section>
         </article>

package/docs/agent-monitor.html

@@ -111,6 +111,13 @@ artshelf doctor --agent
 <span class="c"># lightweight counts, cron-friendly</span>
 artshelf status --all --json
 artshelf status --all --agent</code></pre>
+            <p>
+              If any ledger is stale or missing-path, run the safe sequence in order:
+              <code>review --all --json</code> for affected classifications,
+              <code>validate --all --json</code> for provenance signals, then
+              <code>reconcile --dry-run --all --json --registry &lt;registry-path&gt;</code>
+              before any approve/execute step.
+            </p>
             <p>
               Use <code>--agent</code> for concise monitor decisions and exact next
               actions. Use <code>--json</code> instead when the job needs full

package/docs/agent-review.html

@@ -44,10 +44,15 @@
           <section>
             <h2>Daily review workflow</h2>
             <ol>
-              <li>Read <code>ledgers list --json</code>, <code>review --all --agent</code>, and <code>trash list --all --json</code>.</li>
+              <li>Start with health and registry-level context: <code>status --all --agent</code>,
+                then read raw pressure points from <code>review --all --agent</code>
+                and <code>trash list --all --json</code>.</li>
+              <li>For stale or missing path warnings, run <code>validate --all --json</code>
+                and then <code>reconcile --dry-run --all --json --registry &lt;registry-path&gt;</code>
+                to produce reviewed-safe plans.</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>
+              <li>Execute the exact approval path only after review packet verification: exact ledger path and reviewed plan id or ids.</li>
             </ol>
             <p>
               Prefer the built-in <code>--agent</code> packet when an acting agent
@@ -104,7 +109,8 @@ Dry-run only. No execute, resolve, or delete ran.</code></pre>
             </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;
-approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;</code></pre>
+approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;
+approve artshelf reconcile ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;</code></pre>
             <div class="callout" data-kind="boundary">
               <span class="callout-label">Hard boundary</span>
               <p>

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

@@ -27,27 +27,41 @@
     "skipped": 2,
     "refused": 0,
     "manualReview": 1,
-    "missingPath": 1,
+    "missingPath": 2,
     "trashed": 0
   },
   "decisionSummary": {
-    "readyForApproval": 2,
-    "needsReviewFirst": 1,
-    "blocked": 0
+    "readyForApproval": 3,
+    "needsReviewFirst": 2,
+    "blocked": 1
   },
   "decisionGroups": {
     "readyForApproval": [
       {
         "label": "Clean up temp debug output",
-        "itemIds": ["shf_20260606_120000_ab12"],
+        "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": "Review 1 reconcile remap finding(s) in example-project",
+        "itemIds": [
+          "shf_20260606_121500_gh78"
+        ],
+        "actionType": "reconcile",
+        "approvalTarget": "approve artshelf reconcile ledger /path/to/example-project/.artshelf/ledger.jsonl plan plan_20260606_122000_repl",
+        "reason": "Parent folder drift looks safe to reconcile after inspection and review.",
+        "nextStep": "run `artshelf reconcile --execute --plan-id plan_20260606_122000_repl --ledger /path/to/example-project/.artshelf/ledger.jsonl` after approval."
+      },
       {
         "label": "Resolve missing report record",
-        "itemIds": ["shf_20260606_120500_cd34"],
+        "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.",
@@ -56,17 +70,40 @@
     ],
     "needsReviewFirst": [
       {
-        "label": "Inspect lifecycle smoke report",
-        "itemIds": ["shf_20260606_121000_ef56"],
-        "actionType": "inspect",
+        "label": "Review 1 reconcile resolve-stale-trash finding(s) in example-project",
+        "itemIds": [
+          "shf_20260606_121800_jk90"
+        ],
+        "actionType": "reconcile",
+        "approvalTarget": null,
+        "reason": "Trash references point to trashed artifacts whose originals moved or got deleted.",
+        "nextStep": "run `artshelf reconcile --dry-run --ledger /path/to/example-project/.artshelf/ledger.jsonl --json`, then approve with `approve artshelf reconcile ledger /path/to/example-project/.artshelf/ledger.jsonl plan <plan-id>`"
+      },
+      {
+        "label": "Review 1 reconcile registry-remap finding(s) in example-project",
+        "itemIds": [
+          "shf_20260606_121900_lm01"
+        ],
+        "actionType": "reconcile",
         "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."
+        "reason": "Ledger name or registry path drift needs explicit review before remapping records.",
+        "nextStep": "run `artshelf reconcile --dry-run --ledger /path/to/example-project/.artshelf/ledger.jsonl --json`, then approve with `approve artshelf reconcile ledger /path/to/example-project/.artshelf/ledger.jsonl plan <plan-id>`"
       }
     ],
-    "blocked": []
+    "blocked": [
+      {
+        "label": "Review 1 reconcile blocked finding(s) in example-project",
+        "itemIds": [
+          "shf_20260606_122200_qr11"
+        ],
+        "actionType": "reconcile",
+        "approvalTarget": null,
+        "reason": "Path drift is ambiguous or unsafe and needs manual investigation.",
+        "nextStep": "Run a manual artifact-by-artifact review and decide whether to keep, resolve, or move the ledger entry."
+      }
+    ]
   },
-  "recommendation": "Approve the reviewed cleanup plan for the disposable temp directory, then resolve the missing record after confirming it is no longer needed.",
+  "recommendation": "Run reconcile dry-run for stale/missing path entries, then follow the exact approvals returned in the review packet.",
   "items": [
     {
       "id": "shf_20260606_120000_ab12",
@@ -87,13 +124,31 @@
       "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",
+      "id": "shf_20260606_121800_jk90",
+      "path": "/tmp/stale-trash-record.json",
+      "classification": "resolve-candidate",
+      "proposedAction": "reconcile stale trashed entry after review",
+      "dueStatus": "trashed",
+      "reason": "trash path is stale after source artifact delete",
+      "note": "Run reconcile to confirm whether to rewrite the artifact path or resolve manually."
+    },
+    {
+      "id": "shf_20260606_121900_lm01",
+      "path": "/path/to/example-project/src/legacy/file.txt",
+      "classification": "registry-problem",
+      "proposedAction": "inspect registry-backed path drift",
+      "dueStatus": "missing-path",
+      "reason": "Artifact moved by repository migration from .shelf to .artshelf",
+      "note": "Review registry identity and run reconcile dry-run before executing any path updates."
+    },
+    {
+      "id": "shf_20260606_122200_qr11",
+      "path": "/tmp/blocked-dupe-path",
+      "classification": "registry-problem",
+      "proposedAction": "manual investigation required",
       "dueStatus": "manual-review",
-      "reason": "cleanup=review artifact retained for manual inspection",
-      "note": "No approval target is shown until the review decision is known."
+      "reason": "reconstructed paths conflicted with another active artifact",
+      "note": "Blocked finding intentionally requires human disambiguation."
     }
   ],
   "alternatives": [

package/docs/reference.html

@@ -130,10 +130,11 @@ 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. All three also accept
-              <code>--agent</code> for a deterministic, token-efficient decision packet (see Output mode).
+              summary, including reconcile entry and blocked counts, 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. All three also accept <code>--agent</code> for a
+              deterministic, token-efficient decision packet (see Output mode).
             </p>
           </section>
 
@@ -169,7 +170,9 @@ artshelf cleanup --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--json]
               <code>--dry-run</code> creates and registers a cleanup plan without moving files;
               no-op dry-runs report <code>not-created</code>, and matching dry-runs reuse the
               existing plan id. <code>--execute</code> is approval-only for one reviewed plan id:
-              it writes a receipt, registers the receipt artifact, and updates touched records in the ledger.
+              it writes a started receipt before the first move, completes and registers the receipt
+              artifact, updates touched records in the ledger, and can resume or idempotently replay
+              the same plan id from durable receipt/trash evidence.
             </p>
             <div class="callout" data-kind="boundary">
               <span class="callout-label">Hard boundary</span>