artshelf 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -110,6 +110,26 @@
   state drifted since review, stamps the reconcile audit trail (`previousPath`,
   `reconcilePlanId`, `reconcileReceiptPath`, `reconciledAt`, `reconcileReason`) on
   every touched row, and writes an Artshelf-owned reconcile receipt.
+- Integrated reconcile findings into `review --agent`, `status --agent`, and
+  `doctor --agent` triage: missing-path warnings now route to reconcile dry-run
+  guidance before approval, reconciled plans escalate to ready-for-approval, and
+  the `ArtshelfReviewReport` schema adds the `reconcile` action type (NGX-438).
+- Moved `artshelf put` registry-warning output from stdout to stderr in human
+  mode; `--json` output is unchanged (NGX-429).
+
+## [0.13.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.12.0...artshelf-v0.13.0) (2026-06-15)
+
+
+### Features
+
+* **review:** integrate reconcile findings into agent review packets ([878785e](https://github.com/calvinnwq/artshelf/commit/878785e72c4e65bd8e09572525b05cc020d2f1e1))
+* **review:** integrate reconcile findings into agent triage; move put registry-warning to stderr (NGX-438, NGX-429) ([2573470](https://github.com/calvinnwq/artshelf/commit/25734701b439f617a33609ac98c3fae895199640))
+
+
+### Bug Fixes
+
+* **review:** include reconcile counts in all-ledger triage ([2eeb2fe](https://github.com/calvinnwq/artshelf/commit/2eeb2fea6eae58bfd652be959f2bb6e28d7cb90f))
+* **review:** keep reconcile approval schema and blocked triage consistent ([0c8925a](https://github.com/calvinnwq/artshelf/commit/0c8925a851023622796f2b8d847fcc89cab3c5f0))
 
 ## [0.12.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.11.0...artshelf-v0.12.0) (2026-06-15)
 

package/SPEC.md

@@ -99,8 +99,9 @@ Defaults:
 `put` should refuse to record a path that does not exist unless a future flag
 explicitly supports planned artifacts. After appending the record, `put`
 registers the ledger in the ledger registry. Registry registration is
-best-effort: if it fails, the record remains appended and output includes a
-registry warning or `registryError`.
+best-effort: if it fails, the record remains appended and a registry warning is
+printed to stderr in human mode, or surfaced as a `registryError` field in
+`--json` output, so stdout stays machine-clean.
 
 ### `artshelf ledgers`
 
@@ -253,10 +254,13 @@ included with a `not-created` plan instead of writing a plan file.
 
 In `--all` mode, review emits an aggregate triage summary on top of the
 per-ledger detail. JSON includes a `summary` block with affected-ledger, due,
-manual-review, missing-path, executable, and skipped counts plus the preview
-plan ids; JSON also includes the next safe action. Human output adds a one-line
-triage count and states the same next safe action (repair broken ledgers, dry-run
-cleanup, inspect missing paths, or nothing to do). Review never writes a plan, so
+manual-review, missing-path, executable, skipped, and reconcile entry/blocked
+counts plus the preview plan ids; JSON also includes the next safe action. The
+per-ledger human detail appends a `reconcile` count when a ledger has reconcile
+drift. Human output adds a one-line triage count with the same reconcile counts
+and states the same next safe action (repair broken ledgers, dry-run cleanup,
+dry-run reconcile for missing-path or reconcile drift, 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
@@ -265,9 +269,13 @@ stays the full, backward-compatible public audit report; and `--agent` emits a c
 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.
+read-only and never mints a cleanup plan, the exact approval targets it emits are
+`resolve missing` and `reconcile`; the `reconcile` target appears only when a
+prior reviewed reconcile plan still matches the live drift. Cleanup-eligible
+records and reconcile drift without a reviewed plan stay needs-review-first and
+point at `cleanup --dry-run` or `reconcile --dry-run`, which mint the reviewed
+plan id to approve. Blocked or ambiguous reconcile findings surface in the
+blocked group with no approval target.
 
 ### `artshelf doctor`
 

package/dist/src/commands/put.js

@@ -31,6 +31,6 @@ export function handlePut(parsed, ledgerPath, json) {
         return printJson({ ok: true, record, ledgerPath, registryPath, ...(ledger ? { ledger } : {}), ...(registryError ? { registryError } : {}) });
     process.stdout.write(`recorded ${record.id}\npath: ${record.path}\nretains until: ${record.retainUntil ?? "manual review"}\nledger: ${ledgerPath}\n`);
     if (registryError)
-        process.stdout.write(`registry warning: ${registryError}\n`);
+        process.stderr.write(`registry warning: ${registryError}\n`);
     return 0;
 }

package/dist/src/commands/review.js

@@ -15,7 +15,7 @@ export function handleReview(parsed, ledgerPath, json) {
             printCompactJson(buildReviewAgentPacketAll(results, summary, { path: registryPath, exists: existsSync(registryPath) }));
             return ok ? 0 : 1;
         }
-        const nextAction = reviewNextAction(summary, "all");
+        const nextAction = reviewNextAction(summary, "all", undefined, registryPath);
         if (json) {
             printJson({ ok, registryPath, summary, nextAction, ledgers: results.map(reviewJsonResult) });
             return ok ? 0 : 1;

package/dist/src/commands/shared.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { dueEntries, previewCleanupPlan, readLedger, validateLedger } from "../ledger.js";
 import { listRegisteredLedgers } from "../registry.js";
+import { matchingReconcilePlan, previewReconcilePlan } from "../reconcile.js";
 import { printJson } from "../renderers/json.js";
 export function registeredLedgersOrThrow(registryPath) {
     const ledgers = listRegisteredLedgers(registryPath);
@@ -43,15 +44,19 @@ export function reviewLedger(ledger, registered = true) {
             ledgerExists,
             validate,
             due: [],
-            plan: emptyReviewPlan(ledger.path)
+            plan: emptyReviewPlan(ledger.path),
+            reconcile: null
         };
     }
+    const reconcilePlan = previewReconcilePlan(ledger.path);
+    const reviewedReconcilePlan = reconcilePlan.entries.length > 0 || reconcilePlan.blocked.length > 0 ? matchingReconcilePlan(ledger.path, reconcilePlan) : null;
     return {
         ledger,
         ledgerExists,
         validate,
         due: dueEntries(readLedger(ledger.path)),
-        plan: previewCleanupPlan(ledger.path)
+        plan: previewCleanupPlan(ledger.path),
+        reconcile: { plan: reconcilePlan, reviewedPlan: reviewedReconcilePlan }
     };
 }
 export function reviewJsonResult(result) {
@@ -147,6 +152,8 @@ export function summarizeReview(results) {
         missingPath: 0,
         executable: 0,
         skipped: 0,
+        reconcileEntries: 0,
+        reconcileBlocked: 0,
         previewPlanIds: []
     };
     for (const result of results) {
@@ -162,14 +169,18 @@ export function summarizeReview(results) {
         const due = result.due.filter((entry) => entry.dueStatus === "due").length;
         const manualReview = result.due.filter((entry) => entry.dueStatus === "manual-review").length;
         const missingPath = result.due.filter((entry) => entry.dueStatus === "missing-path").length;
+        const reconcileEntries = result.reconcile?.plan.entries.length ?? 0;
+        const reconcileBlocked = result.reconcile?.plan.blocked.length ?? 0;
         summary.due += due;
         summary.manualReview += manualReview;
         summary.missingPath += missingPath;
         summary.executable += result.plan.entries.length;
         summary.skipped += result.plan.skipped.length;
+        summary.reconcileEntries += reconcileEntries;
+        summary.reconcileBlocked += reconcileBlocked;
         if (result.plan.planId !== "not-created")
             summary.previewPlanIds.push(result.plan.planId);
-        if (!result.validate.ok || due + manualReview + missingPath > 0 || result.plan.entries.length > 0) {
+        if (!result.validate.ok || due + manualReview + missingPath + reconcileEntries + reconcileBlocked > 0 || result.plan.entries.length > 0) {
             summary.affected += 1;
         }
     }

package/dist/src/reconcile.js

@@ -64,6 +64,9 @@ export function createReconcilePlan(ledgerPath) {
     });
     return reviewed;
 }
+export function matchingReconcilePlan(ledgerPath, plan) {
+    return matchingExistingReconcilePlan(ledgerPath, plan);
+}
 // Apply a reviewed reconcile plan (NGX-437 `reconcile --execute`). This is the only
 // mutating reconcile entrypoint and it is deliberately conservative:
 //   * It refuses up front when the plan id is missing, the plan file is absent, or the

package/dist/src/renderers/doctor.js

@@ -3,12 +3,12 @@ const DOCTOR_ATTENTION_CATEGORIES = ["stale", "invalid", "warnings"];
 function doctorAttention(summary) {
     return DOCTOR_ATTENTION_CATEGORIES.filter((key) => summary[key] > 0);
 }
-function doctorNextAction(blockers, summary) {
+function doctorNextAction(blockers, summary, registryPath) {
     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 `healthy, but ${summary.warnings} warning(s) noted — run \`artshelf reconcile --dry-run --all --registry ${registryPath}\` to prepare reconcile-ready approvals, then run \`artshelf review --all --registry ${registryPath}\`; nothing is auto-executed`;
     }
     return "artshelf is healthy on this machine — cleanup safety enforced; no action needed";
 }
@@ -39,7 +39,7 @@ export function buildDoctorAgentPacket(report) {
         attention: doctorAttention(report.summary),
         blockers,
         cleanupSafety: report.cleanupSafety,
-        nextAction: doctorNextAction(blockers, report.summary),
+        nextAction: doctorNextAction(blockers, report.summary, report.registryPath),
         verification: `artshelf doctor --agent --registry ${report.registryPath}`
     };
 }

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-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>