pattern-mcp 0.4.0 → 0.6.0

package/README.md

@@ -32,7 +32,7 @@ whether to:
 
 Pattern is designed for agents to use **while they are building**.
 
-It exposes six tools:
+It exposes eight tools:
 
 - `recommend_component` — evaluates a UI component need and returns a
   structured recommendation.
@@ -54,6 +54,13 @@ It exposes six tools:
   merge, kept-vs-replaced) for one feature, deliberately independent of
   Pattern's own verdict -- see [Outcome
   proxies](#outcome-proxies).
+- `check_ledger_liveness` — checks whether a ledger entry's recorded
+  `file_path` still exists and still references its `chosen_candidate` --
+  see [Tool: `check_ledger_liveness`](#tool-check_ledger_liveness).
+- `export_ledger_provenance` — formats one ledger entry as a stable
+  markdown block (checklist, candidates, verdict, `snapshot_ref`) you can
+  paste into a PR or issue by hand -- see [Tool:
+  `export_ledger_provenance`](#tool-export_ledger_provenance).
 
 ## How it works
 
@@ -428,6 +435,17 @@ Omit it to have one derived deterministically from `project_id` +
 `component_need`; only meaningful together with `project_id`. See
 [Feature cost attribution](#feature-cost-attribution).
 
+#### `file_path`
+
+`file_path` is optional -- path (relative to `PROJECT_ROOT`) where this
+component decision is expected to be implemented, if already known.
+Usually not known yet at call time, since the decision typically precedes
+the file existing. When provided, it's stored on the resulting ledger
+entry and [`check_ledger_liveness`](#tool-check_ledger_liveness) can later
+confirm the file still exists and still references `chosen_candidate`. It
+cannot currently be attached to an entry after the fact -- see [Ledger
+integrity and decision provenance](#ledger-integrity-and-decision-provenance).
+
 **Is the checklist actually skipped, not just re-derived?** Checked, not
 assumed. `breakdown_ms.extract` for a `checklist`-provided call is smaller
 than the default path's, but not near-zero -- which raised the question of
@@ -717,12 +735,24 @@ came back with `served_from_ledger: true`.
       "coverage": "5/8 (62.5%)",
       "cost_usd": 0.087,
       "cache_hit": false,
-      "project_conventions_snapshot": "9f3a1c7e2b0d4f5a"
+      "project_conventions_snapshot": "9f3a1c7e2b0d4f5a",
+      "file_path": null,
+      "snapshot_ref": "a1b2c3d4e5f6...",
+      "last_verified_live": null,
+      "live_status": "unknown"
     }
   ]
 }
 ```
 
+`file_path`/`snapshot_ref`/`last_verified_live`/`live_status` are the
+ledger integrity + decision provenance fields -- see [Ledger integrity and
+decision provenance](#ledger-integrity-and-decision-provenance) and [Tool:
+`check_ledger_liveness`](#tool-check_ledger_liveness). Entries written
+before this feature shipped read back with `file_path`/`snapshot_ref`/
+`last_verified_live` as `null` and `live_status` as `"unknown"` rather
+than missing keys.
+
 Passing `feature_id` instead returns:
 
 ```json
@@ -814,10 +844,12 @@ Pattern's own verdict -- the whole point is a signal that could
 `coverage_pct`, `confidence`, or any other Pattern-produced field. Compute
 `reworked`/`days_to_rework` and `time_to_merge_hours` from your own repo's
 real git history (e.g. `git log --follow` against the files this
-feature's build touched) -- Pattern has no `process.cwd()`/repo-path
-concept and no filesystem access to your repo at all, so it can't compute
-these itself. Report `status_at_30d` only once a real ~30-day-post-merge
-horizon has actually passed.
+feature's build touched) rather than relying on Pattern -- rework rate and
+time-to-merge need real git *history*, a materially bigger surface than
+the one narrow, read-only exception described in [Ledger integrity and
+decision provenance](#ledger-integrity-and-decision-provenance) below.
+Report `status_at_30d` only once a real ~30-day-post-merge horizon has
+actually passed.
 
 Safe to call more than once for the same `feature_id` as more signal
 becomes available over time -- e.g. `time_to_merge_hours` right after
@@ -864,6 +896,122 @@ This only appends a local record to `~/.pattern/outcome_proxies.jsonl`
 (override with `PATTERN_OUTCOME_PROXY_PATH`) -- it never calls the
 Anthropic API.
 
+## Tool: `check_ledger_liveness`
+
+Checks whether ledger entries for a `project_id` are still **live** --
+does the `file_path` recorded on the entry (if any, see
+[`file_path`](#tool-recommend_component)) still exist, and does it still
+mention `chosen_candidate`. See [Ledger integrity and decision
+provenance](#ledger-integrity-and-decision-provenance) for the full design
+and its deliberate limits.
+
+This is the **one exception** to Pattern otherwise having no filesystem
+access to your repo (see [Outcome proxies](#outcome-proxies) above) --
+scoped narrowly to read-only `fs.existsSync`/file-read calls against
+`PROJECT_ROOT` (defaults to this server's own working directory; override
+with `PATTERN_PROJECT_ROOT`). It never writes to your repo and never runs
+an arbitrary shell command.
+
+### Input
+
+```json
+{
+  "project_id": "my-booking-app",
+  "ledger_entry_id": "a1b2c3d4-..."
+}
+```
+
+- `project_id` is required.
+- `ledger_entry_id` is optional -- check just that one entry instead of
+  every entry for `project_id` that has a `file_path` set.
+
+### Output
+
+```json
+{
+  "project_id": "my-booking-app",
+  "checked": 1,
+  "total_entries": 2,
+  "results": [
+    {
+      "ledger_entry_id": "a1b2c3d4-...",
+      "component_need": "cancellation policy display with refund tiers by date",
+      "file_path": "src/components/CancellationPolicy.tsx",
+      "live_status": "live",
+      "checked_at": "2026-09-02T20:11:03.442Z",
+      "note": null
+    },
+    {
+      "ledger_entry_id": "e5f6a7b8-...",
+      "component_need": "gallery",
+      "file_path": null,
+      "live_status": "unknown",
+      "checked_at": null,
+      "note": "no file_path recorded on this entry -- nothing to check"
+    }
+  ]
+}
+```
+
+`live_status` is one of `"live"`, `"orphaned"`, `"unknown"`, or
+(reserved, not yet produced -- see [Ledger integrity and decision
+provenance](#ledger-integrity-and-decision-provenance)) `"dangling"`.
+Entries with no `file_path` are listed but never checked or written to
+`ledger_liveness.jsonl` -- their status is permanently `"unknown"` since
+there's nothing to check. Results here are also layered onto
+`read_ledger`'s `live_status`/`last_verified_live` fields for the same
+entries afterward -- `check_ledger_liveness` is the only thing that
+advances those fields past their write-time defaults.
+
+## Tool: `export_ledger_provenance`
+
+Formats one ledger entry -- requirements checklist, candidates compared,
+verdict, confidence, `snapshot_ref` -- as a single markdown block: a
+stable, portable record of that decision you can paste into a PR
+description or issue by hand. See [Ledger integrity and decision
+provenance](#ledger-integrity-and-decision-provenance) for the full
+design and its deliberate limits.
+
+Pure and deterministic: the same entry always produces byte-identical
+markdown, since the function reads nothing but its input (no live system
+time, no disk state). This only formats and returns text -- it does not
+post anything to GitHub or anywhere else; that's a separate action, not
+yet built.
+
+### Input
+
+```json
+{
+  "project_id": "my-booking-app",
+  "ledger_entry_id": "a1b2c3d4-..."
+}
+```
+
+Both fields are required -- unlike `check_ledger_liveness`, there's no
+"every entry for this project" mode, since a provenance artifact is
+inherently about one specific decision.
+
+### Output
+
+```json
+{
+  "ledger_entry_id": "a1b2c3d4-...",
+  "markdown": "## Pattern decision: cancellation policy display with refund tiers by date\n\n- **Verdict:** use_existing (confidence: high)\n- **Reason:** scored\n- **Coverage:** 5/8 (62.5%)\n- **Domain:** Airbnb-style rental marketplace\n- **Framework:** React + Tailwind\n- **Snapshot:** `9f3a1c7e2b0d4f5a6b7c8d9e0f1a2b3c4d5e6f70`\n- **Judged at:** 2026-08-29T19:50:47.073Z\n\n### Requirements checked\n- ...\n\n### Candidates compared\n| Source | Name | Coverage | Chosen |\n| --- | --- | --- | --- |\n| ReUI (reui.io) | Timeline | 62.5 | ✓ |\n\n_Generated by Pattern (`export_ledger_provenance`) from ledger entry `a1b2c3d4-...`._"
+}
+```
+
+Errors (as `isError: true`, not a thrown exception) when `ledger_entry_id`
+doesn't match any entry for that `project_id` -- including when the id is
+real but belongs to a different project, since entries are always scoped
+per `project_id`.
+
+For a `custom_build` verdict, the candidates section explains that gap in
+prose instead of an empty table -- Pattern doesn't persist the
+custom-build reference (Mobbin/Figma) to the ledger (see
+[`distillCandidate`](#data-minimization)), so it can't reproduce it here.
+A `null` `snapshot_ref` (project root wasn't a git repository at judgment
+time) renders as prose too, not the literal word `null`.
+
 ## Feature cost attribution
 
 Every `recommend_component` call that writes to the ledger -- a fresh
@@ -979,6 +1127,102 @@ convention: a raw or extended object throws rather than silently
 persisting. Run `node scripts/verify-ledger-boundary.mjs` (after
 `npm run build`) to check this boundary directly.
 
+## Ledger integrity and decision provenance
+
+Two gaps in the ledger, surfaced from user feedback: it tracks that a
+decision was made, but not whether the thing it decided about is still
+live in your codebase, and it stores the checklist/verdict but not a
+version pin or an exportable artifact you can attach to a PR or issue.
+This section covers what's shipped so far -- **P0/P1 of both halves**, not
+the full spec. See `pattern-ledger-integrity-and-provenance-spec.md` for
+the complete phased plan; P2/P3 (a scheduled/batch sweep, dangling-cluster
+detection, the provenance-artifact exporter, and GitHub PR/issue posting)
+are not built yet.
+
+**This is the one deliberate exception** to Pattern otherwise having [no
+filesystem/git access to your repo](#per-project-judgment-ledger) at all
+(the principle `report_build_cost`/`report_outcome_proxy` are built
+around). It's narrow on purpose:
+
+- `git rev-parse HEAD` (read-only, never touches repo state) to capture
+  `snapshot_ref` on every ledger write.
+- `fs.existsSync` plus a plain-text read of one file, only for a
+  `file_path` you explicitly passed to `recommend_component`, only inside
+  `PROJECT_ROOT` (see below), to answer `check_ledger_liveness`.
+
+Nothing here runs an arbitrary git or shell command, and nothing writes to
+your repo.
+
+### `PROJECT_ROOT`
+
+Defaults to `process.cwd()` -- for a locally-run stdio MCP server, that's
+normally the consuming repo's root, since MCP hosts typically launch the
+server with the project directory as its working directory. Override with
+`PATTERN_PROJECT_ROOT` if that assumption doesn't hold for your setup.
+
+A `file_path` that's absolute or escapes `PROJECT_ROOT` via `../` resolves
+to `live_status: "unknown"` rather than being read -- belt-and-suspenders,
+since the calling agent already has real filesystem access to its own
+machine regardless.
+
+### Decision provenance: `snapshot_ref`
+
+Every ledger entry -- fresh judgment or [ledger cache
+hit](#the-cache-hit-exception) -- now carries `snapshot_ref`: the commit
+SHA of `PROJECT_ROOT` at the moment that line was written, or `null` when
+`PROJECT_ROOT` isn't a git repo (or `git` isn't installed, or the call
+times out) -- this never fails the underlying `recommend_component` call.
+Entries written before this shipped read back with `snapshot_ref: null`.
+
+A cache-hit entry's `snapshot_ref` reflects the codebase state *when that
+cache-hit line was written*, not the original judgment's -- to see the
+original judgment's snapshot, look up the entry named in its
+`ledger_entry_id`/`original_verdict_timestamp` fields instead.
+
+[`export_ledger_provenance`](#tool-export_ledger_provenance) packages one
+entry's full record -- checklist, candidates, verdict, `snapshot_ref` --
+into a markdown block you can paste into a PR or issue by hand.
+
+Not yet built (P2-P3 of Feature 2): the MCP action to post that artifact
+to a GitHub PR/issue automatically (blocked on an open question -- personal
+token vs. GitHub App -- see BACKLOG.md), and provenance backfill for
+entries that predate `snapshot_ref`.
+
+### Referential integrity: `file_path` / `live_status`
+
+`recommend_component` optionally accepts `file_path` (see [Tool:
+`recommend_component`](#tool-recommend_component)) -- usually not known at
+call time, since the decision typically precedes the file existing. When
+set, [`check_ledger_liveness`](#tool-check_ledger_liveness) can later
+check whether that file still exists and still mentions
+`chosen_candidate`:
+
+- **`live`** -- the file exists and mentions `chosen_candidate`.
+- **`orphaned`** -- `file_path` is set but the file no longer exists.
+- **`unknown`** -- no `file_path` was ever recorded, the path escapes
+  `PROJECT_ROOT`, or the file exists but `chosen_candidate` can't be
+  confirmed in it. Deliberately the default outcome for anything
+  ambiguous: a false `"orphaned"` is worse than a lingering `"unknown"`.
+- **`dangling`** -- reserved, not yet produced. Feature 1's second
+  staleness type (a cluster of entries that only reference each other,
+  with no live anchor anywhere) is graph-level analysis across the whole
+  ledger, not a single-entry check -- P3, not built here.
+
+Checks are on-demand only right now (call `check_ledger_liveness`
+yourself, or on whatever schedule you want) -- there's no automatic
+sweep. `live_status`/`last_verified_live` start `"unknown"`/`null` on
+every entry at write time and only ever advance via a
+`check_ledger_liveness` call; results are stored append-only in
+`~/.pattern/ledger_liveness.jsonl` (override with
+`PATTERN_LEDGER_LIVENESS_PATH`, same "append, never mutate the source
+line, most recent record wins at read time" convention as
+`outcome_proxies.jsonl`, see [Outcome proxies](#outcome-proxies)) and
+layered onto `ledger.jsonl`'s own entries at read time -- the ledger line
+itself is never rewritten.
+
+Not yet built (P2-P3 of Feature 1): a scheduled/batch sweep across an
+entire ledger, and dangling-cluster detection.
+
 ## Per-project decision memory
 
 Pattern stores confirmed decisions locally in:

package/dist/index.js

@@ -30,10 +30,11 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { captureApiError, captureRecommendation, printTelemetryNoticeOnce, shutdownTelemetry, } from "./telemetry.js";
 export const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
 // Configurable so Sonnet vs. Haiku can be A/B tested without a code change.
@@ -129,6 +130,64 @@ const MAX_DECISIONS_PER_PROJECT = 50;
 // call is about, only the caller-supplied project_id string.
 const LEDGER_PATH = process.env.PATTERN_LEDGER_PATH ?? join(homedir(), ".pattern", "ledger.jsonl");
 const LEDGER_TTL_DAYS = Number(process.env.PATTERN_LEDGER_TTL_DAYS ?? 30);
+// Ledger integrity + decision provenance
+// (pattern-ledger-integrity-and-provenance-spec.md). This deliberately
+// reverses the principle stated above report_outcome_proxy elsewhere in
+// this file ("Pattern has no process.cwd()/repo-path concept and no
+// filesystem access to a caller's repo at all") -- but narrowly: the only
+// two things this grants are (1) checking whether one caller-supplied
+// file_path still exists / still mentions a chosen_candidate
+// (checkFileLiveStatus) and (2) reading the current commit SHA via
+// `git rev-parse HEAD` (computeSnapshotRef). Both are read-only, both are
+// scoped to PROJECT_ROOT (see resolveWithinRoot's traversal guard), and
+// neither ever runs an arbitrary shell command. report_build_cost/
+// report_outcome_proxy remain self-reported by design -- rework rate and
+// time-to-merge need real git *history*, a materially bigger and more
+// failure-prone surface than "does this one file exist right now" or
+// "what commit is HEAD."
+//
+// Defaults to process.cwd() -- for a locally-run stdio MCP server, that's
+// normally the consuming repo's root, since MCP hosts typically launch
+// the server with the project directory as its working directory. When
+// that assumption doesn't hold (or for tests), override with
+// PATTERN_PROJECT_ROOT.
+const PROJECT_ROOT = process.env.PATTERN_PROJECT_ROOT ?? process.cwd();
+// Belt-and-suspenders guard against a file_path (ultimately caller-
+// supplied, see recommend_component's input schema) that's absolute or
+// escapes PROJECT_ROOT via "../" -- the calling agent already has real fs
+// access to its own machine regardless, but a stray path should degrade
+// to "unknown" rather than silently stat-ing something outside the
+// project. Returns null (never throws) on anything that doesn't resolve
+// cleanly inside root.
+function resolveWithinRoot(root, relPath) {
+    if (!relPath || isAbsolute(relPath))
+        return null;
+    const resolved = resolve(root, relPath);
+    const rel = relative(root, resolved);
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return null;
+    return resolved;
+}
+// Feature 2 / Decision Provenance, P0: best-effort commit SHA at
+// ledger-write time. Never throws -- not being in a git repo, git not
+// being installed, or the call simply timing out all degrade to null
+// rather than failing the judgment call that triggered this write (see
+// buildLedgerEntry). Read-only: `git rev-parse HEAD` never touches repo
+// state.
+function computeSnapshotRef(root) {
+    try {
+        const sha = execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+        }).trim();
+        return /^[0-9a-f]{7,40}$/i.test(sha) ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}
 // Kill switch for the cache-hit short-circuit specifically -- does NOT
 // disable the ledger itself. Entries still get written and read_ledger
 // still works either way; this only controls whether judgeComponent is
@@ -382,6 +441,8 @@ const EXTRACT_REQUIREMENTS_TOOL_NAME = "extract_requirements";
 const READ_LEDGER_TOOL_NAME = "read_ledger";
 const REPORT_BUILD_COST_TOOL_NAME = "report_build_cost";
 const REPORT_OUTCOME_PROXY_TOOL_NAME = "report_outcome_proxy";
+const CHECK_LEDGER_LIVENESS_TOOL_NAME = "check_ledger_liveness";
+const EXPORT_LEDGER_PROVENANCE_TOOL_NAME = "export_ledger_provenance";
 const INPUT_SCHEMA = {
     type: "object",
     properties: {
@@ -441,6 +502,16 @@ const INPUT_SCHEMA = {
                 "then land under the same id automatically, with no coordination " +
                 "needed between calls. Only meaningful together with project_id.",
         },
+        file_path: {
+            type: "string",
+            description: "Optional. Path (relative to the project root) where this component " +
+                "decision is expected to be implemented, if already known -- usually " +
+                "not known yet at this call, since the decision typically precedes " +
+                "the file existing. When provided, it's stored on the resulting " +
+                "ledger entry and check_ledger_liveness can later confirm the file " +
+                "still exists and still references chosen_candidate. Omit if unknown; " +
+                "it cannot currently be attached to an entry after the fact.",
+        },
     },
     required: ["component_need", "domain", "framework"],
 };
@@ -592,6 +663,35 @@ const REPORT_OUTCOME_PROXY_INPUT_SCHEMA = {
     },
     required: ["feature_id"],
 };
+const CHECK_LEDGER_LIVENESS_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "The project_id used in the recommend_component call(s) whose ledger entries you want live-checked.",
+        },
+        ledger_entry_id: {
+            type: "string",
+            description: "Optional. Check just this one entry (its id, from read_ledger) " +
+                "instead of every entry for project_id that has a file_path set.",
+        },
+    },
+    required: ["project_id"],
+};
+const EXPORT_LEDGER_PROVENANCE_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "The project_id used in the recommend_component call that produced this ledger entry.",
+        },
+        ledger_entry_id: {
+            type: "string",
+            description: "The specific entry to export, from read_ledger or check_ledger_liveness.",
+        },
+    },
+    required: ["project_id", "ledger_entry_id"],
+};
 // Shared between buildSystemPrompt's own step 2 and
 // buildExtractionSystemPrompt (the extract_requirements tool's standalone
 // prompt) -- the extraction *instructions* are one piece of text reused
@@ -1243,6 +1343,125 @@ function deriveFeatureId(componentNeed, projectId, provided) {
         .digest("hex")
         .slice(0, 8);
 }
+// Overlay store for live-check results, same "append-only, latest-value-
+// per-key wins at read time, never mutate the source-of-truth line"
+// convention as outcome_proxies.jsonl/latestOutcomeProxy above -- a check
+// is a new observation, not a correction of the original ledger entry, so
+// ledger.jsonl itself stays untouched by it.
+const LEDGER_LIVENESS_PATH = process.env.PATTERN_LEDGER_LIVENESS_PATH ?? join(homedir(), ".pattern", "ledger_liveness.jsonl");
+function appendLedgerLivenessRecord(record) {
+    mkdirSync(dirname(LEDGER_LIVENESS_PATH), { recursive: true });
+    appendFileSync(LEDGER_LIVENESS_PATH, JSON.stringify(record) + "\n", "utf8");
+}
+function readLedgerLivenessRecords(ledgerEntryId) {
+    let raw;
+    try {
+        raw = readFileSync(LEDGER_LIVENESS_PATH, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && parsed.ledger_entry_id === ledgerEntryId) {
+                records.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return records;
+}
+function latestLiveness(ledgerEntryId) {
+    const records = readLedgerLivenessRecords(ledgerEntryId).sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    return records[0] ?? null;
+}
+function withLatestLiveness(entry) {
+    const latest = latestLiveness(entry.id);
+    if (!latest)
+        return entry;
+    return { ...entry, live_status: latest.live_status, last_verified_live: latest.timestamp };
+}
+// Feature 1 / Referential Integrity, P1: the single-entry live-check.
+// Orphaned when file_path is set but the file no longer exists; live when
+// the file exists and (best-effort) still mentions chosen_candidate;
+// unknown when file_path was never supplied, escapes PROJECT_ROOT (see
+// resolveWithinRoot), or exists but the candidate name can't be confirmed
+// in its content -- conservative on purpose, per the spec's own risk
+// mitigation (a false "orphaned" is worse than a lingering "unknown").
+// "dangling" (an entry only cross-referenced by other ledger entries, no
+// live anchor anywhere) is graph-level analysis across the whole ledger,
+// not a single-entry check -- Feature 1 P3, not built here.
+function checkFileLiveStatus(entry) {
+    if (!entry.file_path)
+        return "unknown";
+    const abs = resolveWithinRoot(PROJECT_ROOT, entry.file_path);
+    if (!abs)
+        return "unknown";
+    if (!existsSync(abs))
+        return "orphaned";
+    if (!entry.chosen_candidate)
+        return "live";
+    try {
+        const content = readFileSync(abs, "utf8");
+        return content.toLowerCase().includes(entry.chosen_candidate.toLowerCase()) ? "live" : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function checkLedgerEntryLiveness(entry) {
+    const record = {
+        id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        ledger_entry_id: entry.id,
+        project_id: entry.project_id,
+        live_status: checkFileLiveStatus(entry),
+        checked_file_path: entry.file_path,
+    };
+    appendLedgerLivenessRecord(record);
+    return record;
+}
+// check_ledger_liveness tool: on-demand invocation of the live-check above
+// (the design's "on demand via an MCP call" case -- a scheduled/batch
+// sweep is Feature 1 P2, not built here). Entries with no file_path are
+// reported but never checked/recorded -- their status is permanently
+// "unknown" by construction, so re-checking them on every call would only
+// grow ledger_liveness.jsonl without ever learning anything new.
+function checkLedgerLiveness(input) {
+    const entries = readLedgerEntries(input.project_id).filter((e) => !input.ledger_entry_id || e.id === input.ledger_entry_id);
+    const results = entries.map((e) => {
+        if (!e.file_path) {
+            return {
+                ledger_entry_id: e.id,
+                component_need: e.component_need,
+                file_path: null,
+                live_status: "unknown",
+                checked_at: null,
+                note: "no file_path recorded on this entry -- nothing to check",
+            };
+        }
+        const record = checkLedgerEntryLiveness(e);
+        return {
+            ledger_entry_id: e.id,
+            component_need: e.component_need,
+            file_path: e.file_path,
+            live_status: record.live_status,
+            checked_at: record.timestamp,
+            note: null,
+        };
+    });
+    return {
+        checked: results.filter((r) => r.checked_at !== null).length,
+        total_entries: results.length,
+        results,
+    };
+}
 // Same "missing/malformed collapses to empty" philosophy as readMemory,
 // but line-oriented (JSONL) rather than whole-file JSON -- a single
 // corrupted line (e.g. a hand-edited file, or a write that got cut off)
@@ -1262,7 +1481,19 @@ function readLedgerEntries(projectId) {
         try {
             const parsed = JSON.parse(line);
             if (parsed && typeof parsed === "object" && parsed.project_id === projectId) {
-                entries.push(parsed);
+                // Backward-compatible defaults for entries written before the
+                // ledger integrity/provenance fields existed -- a missing key
+                // (not merely a null one) falls back to these rather than
+                // `undefined` leaking into the returned shape.
+                const rawEntry = parsed;
+                const normalized = {
+                    ...rawEntry,
+                    file_path: rawEntry.file_path ?? null,
+                    snapshot_ref: rawEntry.snapshot_ref ?? null,
+                    last_verified_live: rawEntry.last_verified_live ?? null,
+                    live_status: rawEntry.live_status ?? "unknown",
+                };
+                entries.push(withLatestLiveness(normalized));
             }
         }
         catch {
@@ -1325,6 +1556,54 @@ function findLedgerMatches(projectId, componentNeed, limit = 20) {
     entries.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
     return entries.slice(0, limit);
 }
+// Feature 2 / Decision Provenance, P1: renders one ledger entry as a
+// stable markdown block -- "stable" meaning a pure function of the entry
+// alone (never Date.now(), never anything read live off disk), so the
+// same entry always produces byte-identical markdown. That determinism is
+// what makes verify-provenance-artifact.mjs's snapshot test meaningful:
+// a diff in the generated markdown for a fixed fixture means the format
+// changed, not that time passed. Markdown, not JSON, per the spec --
+// PRs/issues render it natively (P2, not built here, attaches this to
+// one).
+export function formatProvenanceArtifact(entry) {
+    const lines = [];
+    lines.push(`## Pattern decision: ${entry.component_need}`);
+    lines.push("");
+    lines.push(`- **Verdict:** ${entry.verdict} (confidence: ${entry.confidence})`);
+    lines.push(`- **Reason:** ${entry.reason}`);
+    lines.push(`- **Coverage:** ${entry.coverage ?? "n/a"}`);
+    lines.push(`- **Domain:** ${entry.domain}`);
+    lines.push(`- **Framework:** ${entry.framework}`);
+    lines.push(`- **Snapshot:** ${entry.snapshot_ref ? "`" + entry.snapshot_ref + "`" : "not available (project root wasn't a git repository at judgment time)"}`);
+    lines.push(`- **Judged at:** ${entry.timestamp}${entry.cache_hit ? " (served from ledger cache hit)" : ""}`);
+    lines.push("");
+    lines.push("### Requirements checked");
+    if (entry.checklist.length === 0) {
+        lines.push("_No checklist recorded for this entry._");
+    }
+    else {
+        for (const item of entry.checklist)
+            lines.push(`- ${item}`);
+    }
+    lines.push("");
+    lines.push("### Candidates compared");
+    if (entry.candidates_evaluated.length === 0) {
+        lines.push(entry.verdict === "custom_build"
+            ? "_No existing candidate met the bar -- Pattern recommended a custom build. Pattern doesn't persist the custom-build reference (Mobbin/Figma) to the ledger, so it isn't reproducible here._"
+            : "_No candidates recorded for this entry._");
+    }
+    else {
+        lines.push("| Source | Name | Coverage | Chosen |");
+        lines.push("| --- | --- | --- | --- |");
+        for (const c of entry.candidates_evaluated) {
+            const chosen = c.name !== null && c.name === entry.chosen_candidate ? "✓" : "";
+            lines.push(`| ${c.source ?? "n/a"} | ${c.name ?? "n/a"} | ${c.coverage_pct ?? "n/a"} | ${chosen} |`);
+        }
+    }
+    lines.push("");
+    lines.push(`_Generated by Pattern (\`export_ledger_provenance\`) from ledger entry \`${entry.id}\`._`);
+    return lines.join("\n");
+}
 // report_build_cost (cost-attribution build plan, 1.3) -- self-reported
 // build cost, cheapest option first, since Pattern has no visibility into
 // what happens after judgeComponent returns a verdict (1.4's
@@ -1562,6 +1841,19 @@ function buildLedgerEntry(input, projectId, result, opts) {
         cost_usd: opts.costUsd,
         cache_hit: opts.cacheHit,
         project_conventions_snapshot: hashConventions(input.existing_stack),
+        // Feature 2 P0: captured fresh for every entry (cache hits included),
+        // not inherited from a matched ledger_cache_hit -- this reflects the
+        // codebase state at the moment *this line* was written, not the
+        // moment the original judgment ran (see PROJECT_ROOT above).
+        snapshot_ref: computeSnapshotRef(PROJECT_ROOT),
+        // Feature 1 P0: caller-supplied at write time (recommend_component's
+        // optional file_path), null when not yet known -- typically the case,
+        // since the decision is usually made before the file exists. Always
+        // starts "unknown"/unchecked; check_ledger_liveness fills these in
+        // later via the ledger_liveness.jsonl overlay (see withLatestLiveness).
+        file_path: input.file_path ?? null,
+        last_verified_live: null,
+        live_status: "unknown",
     };
 }
 async function judgeComponent(input) {
@@ -2230,6 +2522,36 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "This only appends a local record; it never calls the Anthropic API.",
             inputSchema: REPORT_OUTCOME_PROXY_INPUT_SCHEMA,
         },
+        {
+            name: CHECK_LEDGER_LIVENESS_TOOL_NAME,
+            description: "Checks whether recommend_component ledger entries for a project_id " +
+                "are still 'live' -- the file_path recorded on the entry (if any) " +
+                "still exists and still mentions chosen_candidate. Requires real, " +
+                "read-only filesystem access to PROJECT_ROOT (defaults to this " +
+                "server's working directory; override with PATTERN_PROJECT_ROOT) -- " +
+                "this is the one exception to Pattern otherwise having no " +
+                "filesystem access to a caller's repo (see report_build_cost/" +
+                "report_outcome_proxy above). Entries with no file_path are listed " +
+                "but not checked -- their status is permanently 'unknown' since " +
+                "there's nothing to check. Never writes to your repo, never runs " +
+                "an arbitrary git/shell command beyond `git rev-parse HEAD` " +
+                "elsewhere in this server. Results are also layered onto " +
+                "read_ledger's live_status/last_verified_live fields for the same " +
+                "entries afterward.",
+            inputSchema: CHECK_LEDGER_LIVENESS_INPUT_SCHEMA,
+        },
+        {
+            name: EXPORT_LEDGER_PROVENANCE_TOOL_NAME,
+            description: "Formats one ledger entry (requirements checklist, candidates " +
+                "compared, verdict, confidence, snapshot_ref) as a single markdown " +
+                "block -- a stable, portable record of that decision you can paste " +
+                "into a PR description or issue by hand. Pure and deterministic: " +
+                "the same entry always produces the same markdown, nothing here " +
+                "reads live system time or disk state. This only formats and " +
+                "returns text; it does not post anything to GitHub or anywhere " +
+                "else -- that's a separate, not-yet-built action.",
+            inputSchema: EXPORT_LEDGER_PROVENANCE_INPUT_SCHEMA,
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -2358,6 +2680,43 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    if (request.params.name === CHECK_LEDGER_LIVENESS_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const result = checkLedgerLiveness(args);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ project_id: args.project_id, ...result }) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
+    if (request.params.name === EXPORT_LEDGER_PROVENANCE_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const entry = readLedgerEntries(args.project_id).find((e) => e.id === args.ledger_entry_id);
+            if (!entry) {
+                throw new Error(`No ledger entry with id "${args.ledger_entry_id}" found for project_id "${args.project_id}". Use read_ledger to list entries and their ids.`);
+            }
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ledger_entry_id: entry.id, markdown: formatProvenanceArtifact(entry) }) },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
     throw new Error(`Unknown tool: ${request.params.name}`);
 });
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "MCP tool that judges whether a UI component need should be met with an existing shadcn/ui, 21st.dev, or ReUI component or requires a custom build, using field/requirement coverage scored against real component code.",
   "type": "module",
   "main": "dist/index.js",