artshelf 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -91,6 +91,58 @@
   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.
+- Integrated reconcile findings into `review --agent`, `status --agent`, and
+  `doctor --agent` triage: missing-path warnings now route to reconcile dry-run
+  guidance before approval, reconciled plans escalate to ready-for-approval, and
+  the `ArtshelfReviewReport` schema adds the `reconcile` action type (NGX-438).
+- Moved `artshelf put` registry-warning output from stdout to stderr in human
+  mode; `--json` output is unchanged (NGX-429).
+
+## [0.13.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.12.0...artshelf-v0.13.0) (2026-06-15)
+
+
+### Features
+
+* **review:** integrate reconcile findings into agent review packets ([878785e](https://github.com/calvinnwq/artshelf/commit/878785e72c4e65bd8e09572525b05cc020d2f1e1))
+* **review:** integrate reconcile findings into agent triage; move put registry-warning to stderr (NGX-438, NGX-429) ([2573470](https://github.com/calvinnwq/artshelf/commit/25734701b439f617a33609ac98c3fae895199640))
+
+
+### Bug Fixes
+
+* **review:** include reconcile counts in all-ledger triage ([2eeb2fe](https://github.com/calvinnwq/artshelf/commit/2eeb2fea6eae58bfd652be959f2bb6e28d7cb90f))
+* **review:** keep reconcile approval schema and blocked triage consistent ([0c8925a](https://github.com/calvinnwq/artshelf/commit/0c8925a851023622796f2b8d847fcc89cab3c5f0))
+
+## [0.12.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.11.0...artshelf-v0.12.0) (2026-06-15)
+
+
+### 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

@@ -99,8 +99,9 @@ Defaults:
 `put` should refuse to record a path that does not exist unless a future flag
 explicitly supports planned artifacts. After appending the record, `put`
 registers the ledger in the ledger registry. Registry registration is
-best-effort: if it fails, the record remains appended and output includes a
-registry warning or `registryError`.
+best-effort: if it fails, the record remains appended and a registry warning is
+printed to stderr in human mode, or surfaced as a `registryError` field in
+`--json` output, so stdout stays machine-clean.
 
 ### `artshelf ledgers`
 
@@ -253,10 +254,13 @@ included with a `not-created` plan instead of writing a plan file.
 
 In `--all` mode, review emits an aggregate triage summary on top of the
 per-ledger detail. JSON includes a `summary` block with affected-ledger, due,
-manual-review, missing-path, executable, and skipped counts plus the preview
-plan ids; JSON also includes the next safe action. Human output adds a one-line
-triage count and states the same next safe action (repair broken ledgers, dry-run
-cleanup, inspect missing paths, or nothing to do). Review never writes a plan, so
+manual-review, missing-path, executable, skipped, and reconcile entry/blocked
+counts plus the preview plan ids; JSON also includes the next safe action. The
+per-ledger human detail appends a `reconcile` count when a ledger has reconcile
+drift. Human output adds a one-line triage count with the same reconcile counts
+and states the same next safe action (repair broken ledgers, dry-run cleanup,
+dry-run reconcile for missing-path or reconcile drift, or nothing to do). Review
+never writes a plan, so
 the next action always points at an explicit follow-up command.
 
 `review`, `status`, and `doctor` share three render modes. The default human
@@ -265,9 +269,13 @@ stays the full, backward-compatible public audit report; and `--agent` emits a c
 deterministic single-line JSON decision packet for agents, taking precedence over
 `--json` when both are passed. For `review`, the packet sorts records into
 ready-for-approval, needs-review-first, and blocked groups. Because review is
-read-only and never mints a cleanup plan, the only exact approval target it emits
-is `resolve missing`; cleanup-eligible records stay needs-review-first and point
-at `cleanup --dry-run`, which mints the reviewed plan id to approve.
+read-only and never mints a cleanup plan, the exact approval targets it emits are
+`resolve missing` and `reconcile`; the `reconcile` target appears only when a
+prior reviewed reconcile plan still matches the live drift. Cleanup-eligible
+records and reconcile drift without a reviewed plan stay needs-review-first and
+point at `cleanup --dry-run` or `reconcile --dry-run`, which mint the reviewed
+plan id to approve. Blocked or ambiguous reconcile findings surface in the
+blocked group with no approval target.
 
 ### `artshelf doctor`
 
@@ -526,6 +534,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 +737,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 +961,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 +980,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;
@@ -31,6 +31,6 @@ export function handlePut(parsed, ledgerPath, json) {
         return printJson({ ok: true, record, ledgerPath, registryPath, ...(ledger ? { ledger } : {}), ...(registryError ? { registryError } : {}) });
     process.stdout.write(`recorded ${record.id}\npath: ${record.path}\nretains until: ${record.retainUntil ?? "manual review"}\nledger: ${ledgerPath}\n`);
     if (registryError)
-        process.stdout.write(`registry warning: ${registryError}\n`);
+        process.stderr.write(`registry warning: ${registryError}\n`);
     return 0;
 }

package/dist/src/commands/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/review.js

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

package/dist/src/commands/shared.js

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

package/dist/src/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}`);
     }