artshelf 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -91,6 +91,38 @@
   entries must be well-formed, so mismatched or malformed plans are refused before
   moving files or writing a receipt — the plan-id-bound posture trash purge
   already enforces.
+- Added path provenance to new ledger records: each record now captures a
+  `provenance` block (root class, root-relative path, basename, path kind, and an
+  optional byte-size fingerprint) so a later reconcile can rebuild a moved
+  artifact's path after a root rename without a daemon, watcher, or shell hook.
+  Provenance is additive and backward compatible — records written before it
+  simply omit the field and still validate, read, list, find, and get as legacy
+  rows, while `validate` reports a malformed provenance block only when the field
+  is present.
+- Added the approval-gated `artshelf reconcile` command for ledger/registry
+  housekeeping that never creates, moves, or deletes files. `--dry-run`
+  classifies recorded-path drift into a reviewed plan (`remap`, `resolve-missing`,
+  `resolve-stale-trash`, or `blocked`), writing and registering an Artshelf-owned
+  plan only when actionable entries exist and reusing a matching plan id
+  otherwise, and `--all` previews every registered ledger as dry-run only.
+  `--execute` applies exactly one reviewed `--plan-id` against one explicit
+  `--ledger`, refuses missing, unknown, or mismatched plans and entries whose live
+  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.
+
+## [0.12.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.11.0...artshelf-v0.12.0) (2026-06-15)
+
+
+### Features
+
+* **ledger:** add path-provenance foundation for NGX-436 ([f0bf797](https://github.com/calvinnwq/artshelf/commit/f0bf797223e5032e326842cc1dd8fcb47130ed3e))
+* **ledger:** add provenance validation distinguishing legacy from malformed rows (NGX-436) ([ce5128a](https://github.com/calvinnwq/artshelf/commit/ce5128a85bcc6353f73c3b47bd9a433918236ee0))
+* **reconcile:** add path-provenance foundation and approval-gated reconcile command ([ad4bcec](https://github.com/calvinnwq/artshelf/commit/ad4bcec7839e004a0f7ca3cc9a8ecebb0caaac0f))
+* **reconcile:** add read-only classification engine for NGX-437 ([3245738](https://github.com/calvinnwq/artshelf/commit/3245738c8d7b3e3dfd95c49fae414596b35c22e1))
+* **reconcile:** add reconcile dry-run plan layer for NGX-437 ([ddc8881](https://github.com/calvinnwq/artshelf/commit/ddc8881713d26f1e43575b3097e49558c22cc2e7))
+* **reconcile:** add reconcile execute layer with audit trail and stale-state refusals (NGX-437) ([50a12d4](https://github.com/calvinnwq/artshelf/commit/50a12d49cdf0552b675bfaa75a0220c886bd64e5))
+* **reconcile:** wire reconcile CLI command with integration tests (NGX-437) ([0ea033b](https://github.com/calvinnwq/artshelf/commit/0ea033b73e96910de87a832e5ada835bc603ff12))
 
 ## [0.11.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.10.2...artshelf-v0.11.0) (2026-06-14)
 

package/README.md

@@ -141,6 +141,8 @@ artshelf doctor
 artshelf update [--json]
 artshelf cleanup --dry-run [--all]
 artshelf cleanup --execute --plan-id <id> [--ledger <path>] [--json]
+artshelf reconcile --dry-run [--all] [--ledger <path>] [--json]
+artshelf reconcile --execute --plan-id <id> --ledger <path> [--json]
 artshelf trash list [--all] [--ledger <path>] [--json]
 artshelf trash purge --older-than <ttl> --dry-run [--ledger <path>] [--json]
 artshelf trash purge --execute --plan-id <id> [--ledger <path>] [--json]

package/SPEC.md

@@ -526,6 +526,76 @@ Rules:
 - Keeps the record visible through `list` and `list --status resolved`.
 - Refuses records that are already `resolved`; the original reason is preserved.
 
+### `artshelf reconcile`
+
+Approval-gated ledger/registry housekeeping that turns recorded-path drift into a
+reviewed plan and then applies exactly one reviewed plan id. Reconcile is **not**
+cleanup: it never creates, moves, or deletes files. It only rewrites drifted ledger
+paths and resolves rows that can no longer be acted on, mirroring the cleanup
+dry-run/execute boundary.
+
+```bash
+artshelf reconcile --dry-run [--ledger <path>] [--json]
+artshelf reconcile --dry-run --all [--registry <path>] [--json]
+artshelf reconcile --execute --plan-id <id> --ledger <path> [--json]
+```
+
+Dry-run classifies each drifted record into one finding category:
+
+- `remap`: the recorded path is gone, but provenance reconstructs the artifact under
+  the current ledger/repo root (for example after a `shelf` -> `artshelf` or
+  `.shelf` -> `.artshelf` rename) and the basename plus optional file fingerprint
+  still match. The path can be safely rewritten to the reconstructed location.
+- `resolve-missing`: an `active` or `review-required` record's path is gone and no
+  safe remap target was found (external path, legacy row, or nothing matches). The
+  row can be resolved after review.
+- `resolve-stale-trash`: an already-`trashed` record's trash target is gone. The
+  ledger row is resolved ledger-only; the filesystem is never touched.
+- `blocked`: a candidate exists at the reconstructed location but its name or
+  fingerprint does not match, or evidence is otherwise ambiguous or unsafe. Blocked
+  findings are surfaced for review and never auto-applied.
+
+`registry-remap` is reserved in the finding taxonomy for a future registry pass that
+updates a registered ledger whose path moved; the current dry-run classifies drift
+within a single ledger's records and does not yet emit `registry-remap`.
+
+Dry-run rules:
+
+- Read-only except for reviewed plan artifact creation/reuse. It classifies drift
+  and, when actionable entries exist, persists the plan to
+  `<ledger-dir>/reconcile-plans/<id>.json` and registers an Artshelf-owned plan
+  record (`owner=artshelf`, `kind=run-artifact`, `ttl=14d`, `cleanup=trash`, labels
+  including `artshelf`, `reconcile-plan`, and the plan id).
+- A no-op dry-run (only blocked or no findings) reports `planId=not-created`,
+  `planPath=null`, and writes no plan file. A later dry-run whose actionable entries
+  match an existing plan reuses that plan id and refreshes its plan artifact.
+- `--all` is dry-run only and previews every registered ledger after the registry
+  validates. There is no global execute.
+
+Execute rules:
+
+- Requires `--plan-id` and one explicit `--ledger`. It binds to one reviewed plan id
+  and refuses a missing, unknown, or id/ledger-mismatched plan before any mutation.
+  There is no `reconcile --execute --all` and no fresh-plan-then-execute.
+- Before applying each entry it re-classifies the live ledger and refuses entries
+  whose live state has drifted since review (record gone, status changed, remap
+  target vanished, or path reappeared), skipping them instead of mutating stale rows.
+- A `remap` rewrites the record `path` and recomputes its provenance for the new
+  location while keeping the row's status; every resolve category archives the row
+  ledger-only as `resolved`.
+- Preserves audit provenance on every touched row (`previousPath`, the rewritten
+  `path` for a remap, `reconcilePlanId`, `reconcileReceiptPath`, `reconciledAt`, and
+  `reconcileReason`), and writes a reconcile receipt to
+  `<ledger-dir>/reconcile-receipts/<id>.json` registered as an Artshelf-owned
+  artifact (`ttl=30d`, `cleanup=review`, labels including `artshelf`,
+  `reconcile-receipt`, and the plan id).
+- Never creates or deletes filesystem artifacts. Reconcile is ledger/registry
+  bookkeeping only, and `doctor`, `status`, `review`, and `validate` never perform
+  silent reconcile edits.
+
+JSON output is deterministic (findings preserve ledger order) so agents can render a
+decision packet and approve a specific plan id.
+
 ## Ledger Storage
 
 V1 supports two scopes:
@@ -659,6 +729,69 @@ the purge provenance:
 }
 ```
 
+Records touched by `artshelf reconcile --execute` carry the reconcile audit trail so a
+remap or resolve stays traceable to the reviewed plan that produced it:
+
+```json
+{
+  "previousPath": "/old-absolute/path/build/out.txt",
+  "reconcilePlanId": "reconcile_20260601_062000_ab12",
+  "reconcileReceiptPath": "/absolute/path/.artshelf/reconcile-receipts/reconcile_20260601_062000_ab12.json",
+  "reconciledAt": "2026-06-01T06:20:00Z",
+  "reconcileReason": "recorded path is missing; reconstructed at the current root"
+}
+```
+
+`previousPath` preserves the path the row held before the action; for a `remap` the new
+location is the rewritten `path`, while resolve categories leave `path` and set
+`status=resolved`. These fields are additive and absent on records reconcile never
+touched.
+
+### Path provenance
+
+New records carry a `provenance` block alongside the absolute `path`. The absolute
+path is still the audit record of where the artifact lived; provenance adds the data
+a future reconcile needs to reason about an artifact that moved because its root was
+renamed (for example `shelf` -> `artshelf` or `.shelf` -> `.artshelf`). Capturing it
+at write time is what lets reconcile remap paths later **without** Artshelf running as
+a daemon, watcher, or shell hook.
+
+```json
+{
+  "provenance": {
+    "root": "repo",
+    "rootPath": "/absolute/path/to/repo",
+    "relativePath": "build/out.txt",
+    "basename": "out.txt",
+    "pathKind": "file",
+    "fingerprint": { "byteSize": 1024 }
+  }
+}
+```
+
+- `root` is `repo`, `ledger`, or `external`. Ledger-owned paths (`trash/`, `plans/`,
+  `receipts/`) classify as `ledger`; other paths inside the repo classify as `repo`;
+  anything else is `external`.
+- `rootPath` and `relativePath` are the matched root and the POSIX path beneath it.
+  The relative path is what survives a root rename, so a reconcile can rebuild the
+  current absolute path from the current root. `external` paths cannot be rebuilt, so
+  both fields are `null`.
+- `basename`, `pathKind`, and the optional file `fingerprint` (byte size only) are
+  cheap matching hints for disambiguating rename candidates.
+
+Provenance is additive and backward compatible. Records written before provenance
+existed simply omit the field; they are treated as **legacy records with missing
+provenance, not malformed data**, and continue to validate, read, list, find, and get
+normally. `artshelf validate` only inspects provenance when the field is present: a
+present-but-structurally-invalid block (bad `root`, missing reconstruct data on a
+`repo`/`ledger` root, reconstruct data on an `external` root, non-numeric fingerprint)
+is reported as an error, while an absent block is not.
+
+Provenance only records evidence. It never moves, deletes, or rewrites artifacts, and
+capturing it does not change any path. Acting on provenance to remap a ledger remains
+an explicit, approval-gated reconcile step — never an automatic side effect of `put`,
+`doctor`, `status`, `review`, or `validate`.
+
 ## Cleanup Safety Model
 
 Cleanup execution is intentionally boring and approval-only. Five boundaries
@@ -820,6 +953,17 @@ 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.
+- New records capture path provenance (root class, root-relative path, basename,
+  path kind, and an optional byte-size fingerprint); provenance is additive and
+  backward compatible, so legacy records without it still validate and read, and
+  `validate` reports a malformed provenance block only when the field is present.
+- CLI can reconcile drifted recorded paths through `artshelf reconcile` without
+  ever creating, moving, or deleting files: `--dry-run` classifies drift into a
+  reviewed plan (`remap`, `resolve-missing`, `resolve-stale-trash`, `blocked`) and
+  `--all` previews every registered ledger as dry-run only, while `--execute`
+  applies one reviewed plan id against one explicit ledger, refuses `--all`,
+  mismatched plans, and entries whose live state drifted since review, and writes
+  the reconcile audit trail and receipt.
 - Package includes the deterministic `ArtshelfReviewReport` schema, canonical
   example, and portable renderer script for agent-rendered review reports.
 - All core commands support `--json`.
@@ -828,7 +972,8 @@ human review.
 - Tests cover record/list/find/get/status-filter/due/validate/resolve/registry,
   `artshelf doctor`, the `artshelf status` dashboard, `--all` review, stale-registry,
   dry-run, global-dry-run, execute-plan, cleanup plan-id validation, concurrent
-  ledger writes, and trash list/purge behavior.
+  ledger writes, trash list/purge, path provenance validation, and reconcile
+  dry-run/execute behavior.
 
 ## Deferred
 

package/dist/src/commands/index.js

@@ -8,6 +8,7 @@ import { handleGet } from "./get.js";
 import { handleLedgers } from "./ledgers.js";
 import { handleList } from "./list.js";
 import { handlePut } from "./put.js";
+import { handleReconcile } from "./reconcile.js";
 import { handleResolve } from "./resolve.js";
 import { handleReview } from "./review.js";
 import { handleStatus } from "./status.js";
@@ -43,6 +44,9 @@ export async function runCommand(parsed) {
         case "cleanup":
             status = handleCleanup(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
             break;
+        case "reconcile":
+            status = handleReconcile(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
+            break;
         case "trash":
             status = handleTrash(parsed, normalizeLedgerPath(stringFlag(parsed, "ledger")), boolFlag(parsed, "json"));
             break;

package/dist/src/commands/put.js

@@ -16,7 +16,7 @@ export function handlePut(parsed, ledgerPath, json) {
         cleanup: stringFlag(parsed, "cleanup"),
         owner: stringFlag(parsed, "owner"),
         labels: arrayFlag(parsed, "label")
-    });
+    }, ledgerPath);
     const registryPath = normalizeRegistryPath(stringFlag(parsed, "registry"));
     appendPreparedRecord(ledgerPath, record);
     let ledger;

package/dist/src/commands/reconcile.js

@@ -0,0 +1,48 @@
+import { createReconcilePlan, executeReconcilePlan } from "../reconcile.js";
+import { normalizeRegistryPath } from "../registry.js";
+import { printJson } from "../renderers/json.js";
+import { boolFlag, requiredStringFlag, stringFlag } from "../shared/flags.js";
+import { printReconcilePlan, printReconcilePlans, printRegisteredLedgerValidation, validateRegisteredLedgersOrThrow } from "./shared.js";
+// `artshelf reconcile` (NGX-437): approval-gated ledger/registry housekeeping that
+// converts path drift into a reviewed plan, then applies one reviewed plan id. This
+// command layer enforces the safety envelope around the reconcile domain functions:
+// dry-run and execute are mutually exclusive, `--all` is dry-run only (no global
+// execute), and execute always binds to one explicit `--ledger` plus `--plan-id`.
+// Reconcile never touches the filesystem; it is ledger bookkeeping, not cleanup.
+export function handleReconcile(parsed, ledgerPath, json) {
+    const dryRun = boolFlag(parsed, "dry-run");
+    const execute = boolFlag(parsed, "execute");
+    if (dryRun && execute)
+        throw new Error("reconcile accepts either --dry-run or --execute, not both");
+    if (boolFlag(parsed, "all") && execute) {
+        throw new Error("reconcile --all is dry-run only; execute requires an explicit --ledger and reviewed --plan-id");
+    }
+    if (dryRun) {
+        if (boolFlag(parsed, "all")) {
+            const registryPath = normalizeRegistryPath(stringFlag(parsed, "registry"));
+            const { ok, results } = validateRegisteredLedgersOrThrow(registryPath);
+            if (!ok)
+                return printRegisteredLedgerValidation(registryPath, results, json);
+            const plans = results.map(({ ledger }) => ({ ledger, plan: createReconcilePlan(ledger.path) }));
+            if (json)
+                return printJson({ ok: true, registryPath, plans });
+            printReconcilePlans(plans);
+            process.stdout.write(`registry: ${registryPath}\n`);
+            return 0;
+        }
+        const plan = createReconcilePlan(ledgerPath);
+        if (json)
+            return printJson({ ok: true, plan });
+        printReconcilePlan(plan, ledgerPath);
+        return 0;
+    }
+    if (execute) {
+        const planId = requiredStringFlag(parsed, "plan-id");
+        const receipt = executeReconcilePlan(ledgerPath, planId);
+        if (json)
+            return printJson({ ok: true, receipt });
+        process.stdout.write(`receipt ${receipt.planId}: ${receipt.results.length} results\nreceipt: ${receipt.receiptPath}\nledger: ${ledgerPath}\n`);
+        return 0;
+    }
+    throw new Error("reconcile requires --dry-run or --execute");
+}

package/dist/src/commands/shared.js

@@ -103,6 +103,23 @@ export function printPlan(plan, ledgerPath) {
     process.stdout.write(`plan ${plan.planId}: ${plan.entries.length} entries, ${plan.skipped.length} skipped\n`);
     process.stdout.write(`plan: ${plan.planPath ?? "not created"}\nledger: ${ledgerPath}\n`);
 }
+export function printReconcilePlan(plan, ledgerPath) {
+    process.stdout.write(`plan ${plan.planId}: ${plan.entries.length} entries, ${plan.blocked.length} blocked\n`);
+    for (const entry of plan.entries) {
+        const target = entry.proposedPath ? `${entry.currentPath} -> ${entry.proposedPath}` : entry.currentPath;
+        process.stdout.write(`${entry.category} ${entry.id} ${entry.field} ${target} :: ${entry.reason}\n`);
+    }
+    for (const blocked of plan.blocked) {
+        process.stdout.write(`blocked ${blocked.id} ${blocked.field} ${blocked.currentPath} :: ${blocked.reason}\n`);
+    }
+    process.stdout.write(`plan: ${plan.planPath ?? "not created"}\nledger: ${ledgerPath}\n`);
+}
+export function printReconcilePlans(results) {
+    for (const result of results) {
+        process.stdout.write(`plan ${result.plan.planId} [${result.ledger.name}]: ${result.plan.entries.length} entries, ${result.plan.blocked.length} blocked\n`);
+        process.stdout.write(`plan: ${result.plan.planPath ?? "not created"}\nledger: ${result.ledger.path}\n`);
+    }
+}
 export function printTrashListEntries(results) {
     const total = results.reduce((count, result) => count + result.entries.length, 0);
     if (total === 0) {

package/dist/src/ledger.js

@@ -3,6 +3,7 @@ import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSy
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { withPathLock } from "./locks.js";
+import { computeProvenance, validateProvenance } from "./provenance.js";
 import { addTtl, assertIsoDate, ageOf, now, ttlToMs, toIso } from "./time.js";
 const KINDS = new Set([
     "scratch",
@@ -26,11 +27,11 @@ export function normalizeLedgerPath(path) {
     return resolve(path ?? defaultLedgerPath());
 }
 export function putRecord(ledgerPath, input) {
-    const record = prepareRecord(input);
+    const record = prepareRecord(input, ledgerPath);
     appendPreparedRecord(ledgerPath, record);
     return record;
 }
-export function prepareRecord(input) {
+export function prepareRecord(input, ledgerPath) {
     const artifactPath = resolve(input.path);
     if (!existsSync(artifactPath)) {
         throw new Error(`Path does not exist: ${input.path}`);
@@ -57,7 +58,8 @@ export function prepareRecord(input) {
         cleanup,
         owner: input.owner ?? "manual",
         labels: input.labels,
-        status: "active"
+        status: "active",
+        provenance: computeProvenance(artifactPath, { ledgerPath })
     };
     return record;
 }
@@ -239,6 +241,13 @@ export function validateLedger(ledgerPath) {
             if (!record.resolutionReason)
                 errors.push(`${label}: resolved record missing resolutionReason`);
         }
+        // Legacy rows simply omit provenance and are left alone; once a row carries
+        // provenance it must be well-formed so future reconcile can trust it.
+        if ("provenance" in record) {
+            for (const problem of validateProvenance(record.provenance)) {
+                errors.push(`${label}: ${problem}`);
+            }
+        }
     }
     return { ok: errors.length === 0, errors, warnings, entries: records.length };
 }
@@ -589,7 +598,10 @@ export function executeCleanupPlan(ledgerPath, planId) {
         return { planId, receiptPath, results };
     });
 }
-function registerArtshelfArtifact(ledgerPath, path, input) {
+// Exported so the reconcile plan layer (src/reconcile.ts) registers its dry-run plan
+// artifacts through the same upsert-by-path-and-labels path that cleanup plans use,
+// keeping plan files tracked and reused under a stable plan id.
+export function registerArtshelfArtifact(ledgerPath, path, input) {
     const prepared = prepareRecord({
         path,
         reason: input.reason,
@@ -598,7 +610,7 @@ function registerArtshelfArtifact(ledgerPath, path, input) {
         cleanup: input.cleanup,
         owner: "artshelf",
         labels: input.labels
-    });
+    }, ledgerPath);
     withLedgerLock(ledgerPath, () => {
         const records = readLedger(ledgerPath);
         const index = records.findIndex((record) => (isMatchingArtshelfArtifact(record, path, input.labels) &&
@@ -684,7 +696,10 @@ function appendRecord(ledgerPath, record) {
         atomicWriteFileSync(ledgerPath, `${previous}${previous && !previous.endsWith("\n") ? "\n" : ""}${JSON.stringify(record)}\n`);
     });
 }
-function writeLedger(ledgerPath, records) {
+// Exported so the reconcile execute layer (src/reconcile.ts) persists its mutated
+// records through the canonical JSONL writer + ledger lock instead of duplicating the
+// atomic-write format, keeping the reconcile -> ledger import direction one-way.
+export function writeLedger(ledgerPath, records) {
     withLedgerLock(ledgerPath, () => {
         mkdirSync(dirname(ledgerPath), { recursive: true });
         atomicWriteFileSync(ledgerPath, records.map((record) => JSON.stringify(record)).join("\n") + (records.length > 0 ? "\n" : ""));
@@ -867,7 +882,7 @@ function pathExistsForPurge(path) {
         return false;
     }
 }
-function assertSafeGeneratedId(value, label) {
+export function assertSafeGeneratedId(value, label) {
     if (!/^[A-Za-z0-9_-]+$/.test(value)) {
         throw new Error(`Invalid ${label}: ${value}`);
     }

package/dist/src/provenance.js

@@ -0,0 +1,142 @@
+import { existsSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+// Capture reconcile-safe provenance for an absolute artifact path. The matched root
+// plus the relative path against it is what survives a `shelf` -> `artshelf` or
+// `.shelf` -> `.artshelf` rename: a future reconcile can rebuild the current path
+// from the current root without Artshelf watching the filesystem. This reads the
+// filesystem to classify the node and fingerprint files; it never mutates anything.
+export function computeProvenance(targetPath, context) {
+    const absolute = resolve(targetPath);
+    const ledgerRoot = resolveLedgerRoot(context.ledgerPath);
+    const repoRoot = findRepoRoot(ledgerRoot);
+    const node = classifyNode(absolute);
+    // Ledger-owned paths are the most specific root, so they win over the repo root:
+    // trash/, plans/, and receipts/ all live under the ledger directory.
+    if (isWithin(ledgerRoot, absolute)) {
+        return reconstructable("ledger", ledgerRoot, absolute, node);
+    }
+    if (repoRoot && isWithin(repoRoot, absolute)) {
+        return reconstructable("repo", repoRoot, absolute, node);
+    }
+    return {
+        root: "external",
+        rootPath: null,
+        relativePath: null,
+        basename: basename(absolute),
+        pathKind: node.kind,
+        ...(node.fingerprint ? { fingerprint: node.fingerprint } : {})
+    };
+}
+const ROOT_KINDS = new Set(["repo", "ledger", "external"]);
+const NODE_KINDS = new Set(["file", "directory", "other"]);
+// Validate a provenance value carried on a record. Returns a list of problems
+// (empty means well-formed). This is the line between a legacy row (no provenance
+// field at all, which callers skip) and a malformed one: once provenance is present
+// it must conform to the PathProvenance contract, including the rule that only
+// `external` roots drop the reconstruct data (rootPath/relativePath).
+export function validateProvenance(provenance) {
+    if (typeof provenance !== "object" || provenance === null) {
+        return ["provenance must be an object"];
+    }
+    const value = provenance;
+    const problems = [];
+    if (typeof value.root !== "string" || !ROOT_KINDS.has(value.root)) {
+        problems.push(`provenance.root is invalid: ${String(value.root)}`);
+    }
+    if (typeof value.basename !== "string" || value.basename.length === 0) {
+        problems.push("provenance.basename must be a non-empty string");
+    }
+    if (typeof value.pathKind !== "string" || !NODE_KINDS.has(value.pathKind)) {
+        problems.push(`provenance.pathKind is invalid: ${String(value.pathKind)}`);
+    }
+    if (value.rootPath !== null && typeof value.rootPath !== "string") {
+        problems.push("provenance.rootPath must be a string or null");
+    }
+    if (value.relativePath !== null && typeof value.relativePath !== "string") {
+        problems.push("provenance.relativePath must be a string or null");
+    }
+    // Reconstruct-data consistency: external paths cannot be rebuilt, so they carry
+    // null rootPath/relativePath; repo/ledger paths must carry both to be remappable.
+    if (value.root === "external") {
+        if (value.rootPath !== null || value.relativePath !== null) {
+            problems.push("provenance with external root must have null rootPath and relativePath");
+        }
+    }
+    else if (value.root === "repo" || value.root === "ledger") {
+        if (typeof value.rootPath !== "string" || typeof value.relativePath !== "string") {
+            problems.push(`provenance with ${value.root} root requires rootPath and relativePath`);
+        }
+    }
+    if (value.fingerprint !== undefined) {
+        const fingerprint = value.fingerprint;
+        if (typeof fingerprint !== "object" || fingerprint === null || typeof fingerprint.byteSize !== "number") {
+            problems.push("provenance.fingerprint must have a numeric byteSize");
+        }
+    }
+    return problems;
+}
+// The current ledger root: the directory that owns trash/, plans/, and receipts/.
+// Provenance with a `ledger` root stores paths relative to this, so a reconcile can
+// re-root them under the current ledger directory after a `.shelf` -> `.artshelf` move.
+export function resolveLedgerRoot(ledgerPath) {
+    return resolve(dirname(ledgerPath));
+}
+// The current repo root for a ledger, using the same resolution as capture time:
+// the enclosing git checkout, or the parent of a dotted ledger directory. Returns
+// null when no repo root can be determined (e.g. a user-global ledger).
+export function resolveRepoRoot(ledgerPath) {
+    return findRepoRoot(resolveLedgerRoot(ledgerPath));
+}
+function reconstructable(root, rootPath, absolute, node) {
+    return {
+        root,
+        rootPath,
+        relativePath: toPosix(relative(rootPath, absolute)),
+        basename: basename(absolute),
+        pathKind: node.kind,
+        ...(node.fingerprint ? { fingerprint: node.fingerprint } : {})
+    };
+}
+function findRepoRoot(ledgerRoot) {
+    const gitRoot = findGitRoot(ledgerRoot);
+    if (gitRoot)
+        return gitRoot;
+    // No git checkout: a dotted ledger directory (.artshelf / .shelf) sits directly
+    // inside its repo/folder, so the parent is the best repo-root candidate.
+    if (basename(ledgerRoot).startsWith(".")) {
+        const parent = dirname(ledgerRoot);
+        return parent === ledgerRoot ? null : parent;
+    }
+    return null;
+}
+function findGitRoot(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(join(current, ".git")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function classifyNode(absolute) {
+    try {
+        const stats = statSync(absolute);
+        if (stats.isFile())
+            return { kind: "file", fingerprint: { byteSize: stats.size } };
+        if (stats.isDirectory())
+            return { kind: "directory" };
+        return { kind: "other" };
+    }
+    catch {
+        return { kind: "other" };
+    }
+}
+function isWithin(parent, child) {
+    const fromParent = relative(parent, child);
+    return fromParent === "" || (!fromParent.startsWith("..") && !isAbsolute(fromParent));
+}
+function toPosix(path) {
+    return sep === "/" ? path : path.split(sep).join("/");
+}

package/dist/src/reconcile.js

@@ -0,0 +1,332 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
+import { assertSafeGeneratedId, readLedger, registerArtshelfArtifact, writeLedger } from "./ledger.js";
+import { withPathLock } from "./locks.js";
+import { computeProvenance, resolveLedgerRoot, resolveRepoRoot } from "./provenance.js";
+import { now, toIso } from "./time.js";
+const RECONCILE_CATEGORIES = new Set([
+    "remap",
+    "resolve-missing",
+    "resolve-stale-trash",
+    "registry-remap",
+    "blocked"
+]);
+// Classify path drift in a ledger into reconcile findings (NGX-437). This is the
+// read-only engine the dry-run/execute workflow builds on: it never mutates the
+// ledger or the filesystem, it only reads records and probes whether recorded paths
+// still exist (and whether a renamed root can reconstruct them via provenance).
+// Findings are returned in ledger order so downstream JSON output is deterministic.
+export function classifyReconcileFindings(ledgerPath) {
+    const records = readLedger(ledgerPath);
+    const roots = {
+        ledgerRoot: resolveLedgerRoot(ledgerPath),
+        repoRoot: resolveRepoRoot(ledgerPath)
+    };
+    const findings = [];
+    for (const record of records) {
+        const finding = classifyRecord(record, roots);
+        if (finding)
+            findings.push(finding);
+    }
+    return findings;
+}
+// Build the reconcile plan without persisting anything (NGX-437 dry-run preview).
+// This is fully read-only: it classifies drift and returns the plan a `--dry-run`
+// would create, but never writes a plan file or touches the ledger. An empty plan
+// (no actionable entries) collapses to the not-created shape so callers can render
+// "nothing to reconcile" the same way cleanup does.
+export function previewReconcilePlan(ledgerPath) {
+    const plan = buildReconcilePlan(ledgerPath);
+    return plan.entries.length === 0 ? noCreatedReconcilePlan(plan) : plan;
+}
+// Create (or reuse) a reviewed reconcile plan (NGX-437 dry-run). This is the only
+// part of dry-run that writes: it persists the plan JSON and registers it as an
+// artshelf-owned artifact so the plan file is tracked and a later `--execute` can
+// bind to an exact reviewed plan id. When an earlier plan already covers the same
+// findings it is reused verbatim (stable plan id), and when nothing is actionable
+// no plan artifact is created at all, keeping dry-run side-effect-free in that case.
+export function createReconcilePlan(ledgerPath) {
+    const plan = buildReconcilePlan(ledgerPath);
+    if (plan.entries.length === 0)
+        return noCreatedReconcilePlan(plan);
+    const existing = matchingExistingReconcilePlan(ledgerPath, plan);
+    const reviewed = existing ? { ...plan, planId: existing.planId, planPath: existing.planPath } : plan;
+    if (!reviewed.planPath)
+        throw new Error("reconcile plan path was not created");
+    writeReconcilePlanFile(reviewed.planPath, reviewed);
+    registerArtshelfArtifact(ledgerPath, reviewed.planPath, {
+        reason: `Artshelf reconcile dry-run plan ${reviewed.planId}`,
+        ttl: "14d",
+        kind: "run-artifact",
+        cleanup: "trash",
+        labels: ["artshelf", "reconcile-plan", reviewed.planId]
+    });
+    return reviewed;
+}
+// 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
+//     plan file's declared id/ledger does not match the scoped request (no fresh plan,
+//     no `--all`; the command layer enforces those, this binds to one exact plan id).
+//   * Before applying any entry it re-classifies the live ledger and only acts when the
+//     current finding still matches the reviewed entry, so a plan executed against a
+//     drifted ledger refuses the stale entries instead of mutating the wrong rows.
+// Reconcile is ledger/registry housekeeping only: it rewrites paths and resolves rows
+// and writes a receipt; it never creates or deletes filesystem artifacts.
+export function executeReconcilePlan(ledgerPath, planId) {
+    if (!planId)
+        throw new Error("reconcile --execute requires --plan-id");
+    const planPath = reconcilePlanPath(ledgerPath, planId);
+    if (!existsSync(planPath))
+        throw new Error(`Reconcile plan not found: ${planId}`);
+    const plan = JSON.parse(readFileSync(planPath, "utf8"));
+    assertReconcilePlanExecutable(plan, planId, ledgerPath);
+    const receiptPath = reconcileReceiptPath(ledgerPath, planId);
+    return withPathLock(ledgerPath, () => {
+        const records = readLedger(ledgerPath);
+        const recordsById = new Map(records.map((record) => [record.id, record]));
+        const liveById = new Map(classifyReconcileFindings(ledgerPath).map((finding) => [finding.id, finding]));
+        const executedAt = toIso(now());
+        const audit = { reconcilePlanId: planId, reconcileReceiptPath: receiptPath, reconciledAt: executedAt };
+        const results = [];
+        for (const entry of plan.entries) {
+            const record = recordsById.get(entry.id);
+            const live = liveById.get(entry.id);
+            if (!record || !live || !sameReconcileTarget(live, entry)) {
+                results.push(skippedResult(entry));
+                continue;
+            }
+            const applied = applyReconcileEntry(record, entry, audit, ledgerPath);
+            recordsById.set(entry.id, applied);
+            results.push(appliedResult(entry, applied));
+        }
+        writeReconcileReceipt(receiptPath, { planId, ledgerPath, executedAt, results });
+        writeLedger(ledgerPath, records.map((record) => recordsById.get(record.id) ?? record));
+        registerArtshelfArtifact(ledgerPath, receiptPath, {
+            reason: `Artshelf reconcile receipt for plan ${planId}`,
+            ttl: "30d",
+            kind: "run-artifact",
+            cleanup: "review",
+            labels: ["artshelf", "reconcile-receipt", planId]
+        });
+        return { planId, receiptPath, executedAt, results };
+    }, "Artshelf ledger");
+}
+// Produce the mutated record for one applicable entry. A remap rewrites the path and
+// recomputes provenance against the new location (so the row is reconcile-healthy
+// afterwards) while keeping the row's status; every resolve category archives the row
+// ledger-only as `resolved`. previousPath always preserves the pre-action path.
+function applyReconcileEntry(record, entry, audit, ledgerPath) {
+    if (entry.category === "remap" && entry.proposedPath) {
+        return {
+            ...record,
+            path: entry.proposedPath,
+            provenance: computeProvenance(entry.proposedPath, { ledgerPath }),
+            previousPath: entry.currentPath,
+            ...audit,
+            reconcileReason: entry.reason
+        };
+    }
+    return {
+        ...record,
+        status: "resolved",
+        resolvedAt: audit.reconciledAt,
+        resolutionReason: entry.reason,
+        previousPath: entry.currentPath,
+        ...audit,
+        reconcileReason: entry.reason
+    };
+}
+function appliedResult(entry, applied) {
+    return {
+        id: entry.id,
+        category: entry.category,
+        field: entry.field,
+        status: applied.status === "resolved" ? "resolved" : "remapped",
+        previousPath: entry.currentPath,
+        newPath: entry.category === "remap" ? entry.proposedPath : null,
+        reason: entry.reason
+    };
+}
+function skippedResult(entry) {
+    return {
+        id: entry.id,
+        category: entry.category,
+        field: entry.field,
+        status: "skipped",
+        previousPath: entry.currentPath,
+        newPath: null,
+        reason: "live ledger state no longer matches the reviewed plan"
+    };
+}
+// Two findings describe the same drift only when every structural field agrees; this
+// is the execute-time safety check that refuses entries whose live state has moved on.
+function sameReconcileTarget(live, entry) {
+    return (live.category === entry.category &&
+        live.field === entry.field &&
+        live.status === entry.status &&
+        live.currentPath === entry.currentPath &&
+        live.proposedPath === entry.proposedPath);
+}
+// Bind a loaded reconcile plan to the request before any ledger mutation, mirroring
+// cleanup's assertCleanupPlanExecutable: the plan must declare the requested id, belong
+// to the executing ledger, and carry well-formed entries.
+function assertReconcilePlanExecutable(plan, planId, ledgerPath) {
+    if (plan.planId !== planId) {
+        throw new Error(`Reconcile plan id mismatch: plan file declares ${plan.planId}, requested ${planId}`);
+    }
+    if (plan.ledgerPath !== ledgerPath) {
+        throw new Error(`Reconcile plan ledger mismatch: plan was created for ${plan.ledgerPath}, executing ${ledgerPath}`);
+    }
+    if (!Array.isArray(plan.entries)) {
+        throw new Error(`Reconcile plan entries are malformed: ${planId}`);
+    }
+    for (const entry of plan.entries) {
+        if (!entry || typeof entry.id !== "string" || typeof entry.currentPath !== "string" || !RECONCILE_CATEGORIES.has(entry.category)) {
+            throw new Error(`Reconcile plan entries are malformed: ${planId}`);
+        }
+    }
+}
+function reconcileReceiptPath(ledgerPath, planId) {
+    assertSafeGeneratedId(planId, "reconcile plan id");
+    return join(dirname(ledgerPath), "reconcile-receipts", `${planId}.json`);
+}
+function writeReconcileReceipt(receiptPath, value) {
+    mkdirSync(dirname(receiptPath), { recursive: true });
+    writeFileSync(receiptPath, `${JSON.stringify(value, null, 2)}\n`);
+}
+function classifyRecord(record, roots) {
+    // A trashed row's original path is expected to be empty (it was moved to trash),
+    // so the only path that matters is the trash target.
+    if (record.status === "trashed")
+        return classifyTrashTarget(record);
+    // Live rows are the ones whose recorded artifact path should still exist. This
+    // mirrors validateLedger's "recorded path is missing" warning surface.
+    if (record.status === "active" || record.status === "review-required") {
+        return classifyActivePath(record, roots);
+    }
+    // resolved / cleanup-refused rows are terminal for reconcile purposes.
+    return null;
+}
+function classifyActivePath(record, roots) {
+    if (!record.path || existsSync(record.path))
+        return null;
+    const provenance = record.provenance;
+    const candidate = reconstructPath(provenance, roots);
+    if (provenance && candidate && existsSync(candidate)) {
+        if (isSafeMatch(provenance, candidate)) {
+            return finding(record, "remap", "path", record.path, candidate, `recorded path is missing; reconstructed at ${candidate}`);
+        }
+        return finding(record, "blocked", "path", record.path, null, `a candidate exists at ${candidate} but its name or fingerprint does not match the recorded artifact`);
+    }
+    return finding(record, "resolve-missing", "path", record.path, null, "recorded path is missing and no safe remap target was found");
+}
+function classifyTrashTarget(record) {
+    // Missing cleanup metadata on a trashed row is validateLedger's concern, not ours.
+    if (!record.targetPath || existsSync(record.targetPath))
+        return null;
+    return finding(record, "resolve-stale-trash", "targetPath", record.targetPath, null, "trashed target is missing; resolve the ledger row without touching the filesystem");
+}
+// Re-root a provenance-relative path under the current ledger/repo root. Only
+// reconstructable roots (repo/ledger) with a stored relative path can be rebuilt;
+// external paths and legacy rows without provenance return null.
+function reconstructPath(provenance, roots) {
+    if (!provenance || provenance.relativePath === null)
+        return null;
+    if (provenance.root === "repo") {
+        return roots.repoRoot ? join(roots.repoRoot, fromPosix(provenance.relativePath)) : null;
+    }
+    if (provenance.root === "ledger") {
+        return join(roots.ledgerRoot, fromPosix(provenance.relativePath));
+    }
+    return null;
+}
+// A reconstructed candidate is only trusted when its basename matches and, for
+// files with a captured fingerprint, its byte size matches too. Directories and
+// fingerprint-less rows fall back to name plus existence as the evidence.
+function isSafeMatch(provenance, candidate) {
+    if (basename(candidate) !== provenance.basename)
+        return false;
+    if (provenance.pathKind === "file" && provenance.fingerprint) {
+        try {
+            return statSync(candidate).size === provenance.fingerprint.byteSize;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+function finding(record, category, field, currentPath, proposedPath, reason) {
+    return { id: record.id, category, field, status: record.status, currentPath, proposedPath, reason };
+}
+function fromPosix(path) {
+    return sep === "/" ? path : path.split("/").join(sep);
+}
+// Split classified findings into a plan: actionable entries (everything a scoped
+// `--execute` may apply) versus blocked findings (surfaced for review only). The
+// plan id/path are computed up front so a dry-run can persist deterministically.
+function buildReconcilePlan(ledgerPath) {
+    const generatedAt = now();
+    const findings = classifyReconcileFindings(ledgerPath);
+    const entries = findings.filter((finding) => finding.category !== "blocked");
+    const blocked = findings.filter((finding) => finding.category === "blocked");
+    const planId = makeReconcilePlanId(generatedAt);
+    return {
+        planId,
+        generatedAt: toIso(generatedAt),
+        ledgerPath,
+        entries,
+        blocked,
+        planPath: reconcilePlanPath(ledgerPath, planId)
+    };
+}
+function noCreatedReconcilePlan(plan) {
+    return { ...plan, planId: "not-created", planPath: null };
+}
+// Reuse an earlier plan whose actionable entries match this one's, so repeated
+// dry-runs converge on a single stable plan id (mirrors cleanup plan reuse). Only
+// the structural entry fields are fingerprinted; volatile fields (generatedAt) and
+// the review-only blocked list do not affect reuse.
+function matchingExistingReconcilePlan(ledgerPath, plan) {
+    const plansDir = join(dirname(ledgerPath), "reconcile-plans");
+    if (!existsSync(plansDir))
+        return null;
+    const filenames = readdirSync(plansDir).filter((name) => name.endsWith(".json")).sort().reverse();
+    for (const filename of filenames) {
+        const planPath = join(plansDir, filename);
+        try {
+            const candidate = JSON.parse(readFileSync(planPath, "utf8"));
+            if (candidate.ledgerPath !== ledgerPath)
+                continue;
+            if (reconcilePlanFingerprint(candidate) !== reconcilePlanFingerprint(plan))
+                continue;
+            return { ...candidate, planPath };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function reconcilePlanFingerprint(plan) {
+    return JSON.stringify(plan.entries.map((entry) => ({
+        id: entry.id,
+        category: entry.category,
+        field: entry.field,
+        currentPath: entry.currentPath,
+        proposedPath: entry.proposedPath
+    })));
+}
+function writeReconcilePlanFile(planPath, plan) {
+    mkdirSync(dirname(planPath), { recursive: true });
+    writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`);
+}
+function makeReconcilePlanId(date) {
+    return `reconcile_${toIso(date).replace(/[-:]/g, "").replace("T", "_").replace("Z", "")}_${randomBytes(2).toString("hex")}`;
+}
+function reconcilePlanPath(ledgerPath, planId) {
+    assertSafeGeneratedId(planId, "reconcile plan id");
+    return join(dirname(ledgerPath), "reconcile-plans", `${planId}.json`);
+}

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

@@ -52,6 +52,7 @@ const COMMAND_GROUPS = [
         group: "Clean",
         commands: [
             { name: "cleanup", summary: "Plan and execute approved cleanups" },
+            { name: "reconcile", summary: "Reconcile drifted ledger paths via approval-gated plans" },
             { name: "trash", summary: "Inspect and purge Artshelf trash" },
             { name: "resolve", summary: "Mark a record manually resolved" }
         ]
@@ -107,6 +108,31 @@ Dry-run writes and registers a plan only when executable cleanup entries exist;
 Matching dry-runs reuse the existing plan id and refresh its Artshelf-owned plan artifact.
 Execute writes and registers an Artshelf-owned receipt artifact.
 Global --all mode is dry-run only.
+`;
+    }
+    if (command === "reconcile") {
+        return `Usage:
+  artshelf reconcile --dry-run [--ledger <path>] [--json]
+  artshelf reconcile --dry-run --all [--registry <path>] [--json]
+  artshelf reconcile --execute --plan-id <id> --ledger <path> [--json]
+
+Reconcile is approval-gated ledger/registry housekeeping, not cleanup: it never
+creates, moves, or deletes files. It rewrites drifted ledger paths and resolves
+rows that can no longer be acted on, always through one reviewed plan id.
+
+Dry-run classifies path drift into a reviewed plan:
+  remap                a safe moved/renamed path is rewritten to its current location
+  resolve-missing      an active path is gone with no safe target; resolve after review
+  resolve-stale-trash  a trashed target is gone; resolve the ledger row, files untouched
+  blocked              ambiguous or unsafe findings surfaced for review, never auto-applied
+
+Execute applies one reviewed plan id against one explicit --ledger and refuses
+missing, unknown, or mismatched plan ids and entries whose live ledger state has
+drifted since review. There is no reconcile --execute --all and no fresh-plan-then-execute.
+Dry-run writes and registers a plan only when actionable entries exist; no-op dry-runs report not-created.
+Matching dry-runs reuse the existing plan id and refresh its Artshelf-owned plan artifact.
+Execute writes and registers an Artshelf-owned reconcile receipt artifact.
+Global --all mode is dry-run only.
 `;
     }
     if (command === "trash")

package/docs/reference.html

@@ -203,6 +203,30 @@ artshelf trash purge --execute --plan-id <id> [--ledger <path>] [--j
             <p>Mark a handled, missing, or no-longer-needed record as manually resolved. Updates the ledger only; never moves or deletes files.</p>
           </section>
 
+          <section class="cmd">
+            <div class="cmd-head"><h2>artshelf reconcile</h2><span class="cmd-flag approval">approval-gated</span></div>
+            <pre><code><span class="c"># classify path drift into a reviewed plan</span>
+artshelf reconcile --dry-run [--all] [--ledger &lt;path&gt;] [--json]
+
+<span class="c"># apply exactly one reviewed plan id for one explicit ledger</span>
+artshelf reconcile --execute --plan-id &lt;id&gt; --ledger &lt;path&gt; [--json]</code></pre>
+            <p>
+              Approval-gated ledger housekeeping for drifted recorded paths, not cleanup: it never
+              creates, moves, or deletes files. <code>--dry-run</code> classifies each drifted record as
+              <code>remap</code> (a moved path safely rewritten from provenance), <code>resolve-missing</code>,
+              <code>resolve-stale-trash</code>, or <code>blocked</code>, and registers a reviewed plan when
+              actionable entries exist. <code>--execute</code> applies one reviewed plan id, refuses
+              missing/unknown/mismatched plans and entries whose live state drifted, and stamps the
+              reconcile audit trail (<code>previousPath</code>, <code>reconcilePlanId</code>,
+              <code>reconciledAt</code>) on every touched row.
+            </p>
+            <div class="callout" data-kind="boundary">
+              <span class="callout-label">Hard boundary</span>
+              <p>No file deletion, no auto-execute, and no global execute.
+              <code>reconcile --execute --all</code> does not exist, and a fresh plan cannot be executed in one command.</p>
+            </div>
+          </section>
+
           <section>
             <h2>Global flags</h2>
             <p>Only these apply to every command.</p>
@@ -252,7 +276,7 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
               <tr><th>option</th><th>meaning</th></tr>
               <tr><td>--ledger &lt;path&gt;</td><td>target an explicit JSONL ledger</td></tr>
               <tr><td>--registry &lt;path&gt;</td><td>target an explicit ledger registry</td></tr>
-              <tr><td>--all</td><td>read every registered ledger on commands that support discovery (<code>list</code>, <code>find</code>, <code>get</code>, <code>due</code>, <code>validate</code>, <code>review</code>, <code>status</code>, <code>cleanup --dry-run</code>, <code>trash list</code>)</td></tr>
+              <tr><td>--all</td><td>read every registered ledger on commands that support discovery (<code>list</code>, <code>find</code>, <code>get</code>, <code>due</code>, <code>validate</code>, <code>review</code>, <code>status</code>, <code>cleanup --dry-run</code>, <code>reconcile --dry-run</code>, <code>trash list</code>)</td></tr>
             </table>
           </section>
 
@@ -292,7 +316,7 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
               Inside a git repo, Artshelf defaults to <code>.artshelf/ledger.jsonl</code>. Outside a
               repo it defaults to <code>~/.artshelf/ledger.jsonl</code>. A user-level registry at
               <code>~/.artshelf/ledgers.json</code> is the discovery index for <code>--all</code>
-              review, status, cleanup dry-run, and trash-list; project records stay in their own
+              review, status, cleanup dry-run, reconcile dry-run, and trash-list; project records stay in their own
               repo-local ledgers. Automatic update checks cache their last npm result at
               <code>~/.artshelf/update-check.json</code> by default, with a long TTL
               for update-available results and a shorter TTL for no-update or failed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artshelf",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",