artshelf 0.10.2 → 0.12.0

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/registry.js

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
+import { withPathLock } from "./locks.js";
 import { now, toIso } from "./time.js";
 export function defaultRegistryPath() {
     return process.env.ARTSHELF_REGISTRY ?? process.env.SHELF_REGISTRY ?? join(homedir(), ".artshelf", "ledgers.json");
@@ -57,46 +58,7 @@ function writeRegistry(registryPath, registry) {
     renameSync(tmpPath, registryPath);
 }
 function withRegistryLock(registryPath, fn) {
-    mkdirSync(dirname(registryPath), { recursive: true });
-    const lockPath = `${registryPath}.lock`;
-    const deadline = Date.now() + 5000;
-    const staleAfterMs = 30_000;
-    while (true) {
-        try {
-            mkdirSync(lockPath);
-            break;
-        }
-        catch (error) {
-            if (error.code !== "EEXIST")
-                throw error;
-            if (isStaleLock(lockPath, staleAfterMs)) {
-                rmSync(lockPath, { recursive: true, force: true });
-                continue;
-            }
-            if (Date.now() > deadline)
-                throw new Error(`Timed out waiting for Artshelf ledger registry lock: ${registryPath}`);
-            sleep(25);
-        }
-    }
-    try {
-        return fn();
-    }
-    finally {
-        rmSync(lockPath, { recursive: true, force: true });
-    }
-}
-function sleep(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-function isStaleLock(lockPath, staleAfterMs) {
-    try {
-        return Date.now() - statSync(lockPath).mtimeMs > staleAfterMs;
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return false;
-        throw error;
-    }
+    return withPathLock(registryPath, fn, "Artshelf ledger registry");
 }
 function normalizeEntry(entry) {
     if (!entry.name || !entry.path || !entry.scope || !entry.createdAt || !entry.updatedAt) {

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.10.2",
+  "version": "0.12.0",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",