artshelf 0.10.2 → 0.12.0

package/CHANGELOG.md

@@ -79,6 +79,63 @@
   cache, `ARTSHELF_NO_UPDATE_CHECK_TTL_MS` overrides the no-update/failed TTL
   (falling back to `ARTSHELF_UPDATE_CHECK_TTL_MS` for compatibility), and a
   non-numeric TTL value falls back to the default instead of disabling expiry.
+- Made concurrent ledger and registry writes safe: ledger mutations now take the
+  same cross-process advisory lock as the registry (extracted into a shared
+  `withPathLock` helper in `src/locks.ts`), and ledger appends and rewrites commit
+  through a unique temp file and an atomic rename, so overlapping `put`,
+  `resolve`, and cleanup runs no longer drop records or leave a partially written
+  ledger.
+- Hardened `cleanup --execute` to reject unsafe plan ids and bind the loaded plan
+  to the request before any filesystem mutation: the plan's `planId` must match
+  the requested id, its `ledgerPath` must match the executing ledger, and its
+  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)
+
+
+### Features
+
+* **ledger:** add cross-process advisory file lock and unique temp paths for atomic writes (NGX-428) ([0f553e4](https://github.com/calvinnwq/artshelf/commit/0f553e485737cf96390d451f4ae92f52e1abbf2a))
+
+
+### Bug Fixes
+
+* **cleanup:** reject unsafe plan-ids and mismatched plans before filesystem mutation (NGX-426) ([79debb7](https://github.com/calvinnwq/artshelf/commit/79debb7c3610984a969adea7f93b27ca08150647))
+* **ledger:** make ledger writes atomic and concurrency-safe and reject unsafe cleanup plans ([ac98c4e](https://github.com/calvinnwq/artshelf/commit/ac98c4eaf917b695e166f2ca7c40b6759d6e5f53))
 
 ## [0.10.2](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.10.1...artshelf-v0.10.2) (2026-06-13)
 

package/README.md

@@ -113,6 +113,9 @@ destructive deletion.
 - **No fresh-plan-then-execute shortcut** — review the plan, then run that plan.
 - **Trash before delete** — `cleanup=delete` stays refused; physical deletion
   needs its own reviewed trash purge. No silent deletion, ever.
+- **Durable, concurrency-safe writes** — ledger and registry mutations take a
+  cross-process lock and commit atomically, so overlapping commands never lose
+  records or leave a half-written ledger.
 - **`--json` on every command**, so agents can act on structured output.
 - **`--agent` on `review`/`status`/`doctor`**, a compact, token-efficient
   decision packet for agents, while the default render stays human-scannable.
@@ -138,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

@@ -423,8 +423,15 @@ artshelf cleanup --execute --plan-id <id> [--ledger <path>] --json
 
 Rules:
 
-- Requires `--plan-id`.
+- Requires `--plan-id`, and refuses an unsafe plan id (anything outside
+  `[A-Za-z0-9_-]`, such as a value containing path separators or `..`) before
+  touching the filesystem.
 - Refuses to generate a fresh live cleanup set during execute.
+- Binds the loaded plan to the request before any mutation: the plan file's
+  `planId` must match the requested id, its `ledgerPath` must match the executing
+  ledger, and its entries must be well-formed. A mismatched or malformed plan is
+  refused without moving files or writing a receipt, mirroring the live-record
+  re-checks `trash purge --execute` performs.
 - Writes a cleanup receipt and appends or refreshes an Artshelf-owned ledger record
   for that receipt with `owner=artshelf`, `kind=run-artifact`, `ttl=30d`,
   `cleanup=review`, and labels including `artshelf`, `cleanup-receipt`, and the
@@ -519,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:
@@ -532,6 +609,16 @@ Default behavior:
 - Otherwise write user-global.
 - Allow `--ledger <path>` for explicit tests and unusual workflows.
 
+Write durability:
+
+- Every mutation of a ledger or the registry runs under a cross-process advisory
+  lock keyed on the target file, so overlapping `artshelf` processes serialize
+  their writes instead of racing. The lock is re-entrant within a process and
+  reclaims a stale lock left by a crashed holder.
+- Ledger writes — both single-record appends and full rewrites — land through a
+  unique temp file and an atomic rename, so an interrupted write cannot truncate
+  the ledger or lose already-recorded entries.
+
 V1 also supports a user-level registry of known ledgers:
 
 - registry: `~/.artshelf/ledgers.json`
@@ -642,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
@@ -784,6 +934,8 @@ human review.
 - CLI can find existing records by path/owner/label/status and get records by id.
 - CLI can mark records manually resolved with a required reason.
 - CLI validates ledger shape.
+- Concurrent ledger and registry writes are serialized with a cross-process lock
+  and committed atomically, so overlapping commands do not lose records.
 - CLI reports machine and registry health through `artshelf doctor`, exiting
   non-zero when the registry or a registered ledger is broken.
 - CLI reports a read-only daily dashboard through `artshelf status`, with
@@ -795,11 +947,23 @@ human review.
   entries; no-op dry-runs do not write plan files.
 - Cleanup dry-run and execute register the plan/receipt artifacts that Artshelf
   creates.
-- Cleanup execute refuses to run without a plan id.
+- Cleanup execute refuses to run without a plan id, and refuses an unsafe,
+  mismatched, or malformed plan before moving files or writing a receipt.
 - Cleanup execute writes a receipt.
 - 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`.
@@ -807,7 +971,9 @@ human review.
   JSON decision packet for agents that takes precedence over `--json`.
 - 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, and trash list/purge behavior.
+  dry-run, global-dry-run, execute-plan, cleanup plan-id validation, concurrent
+  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) {