pattern-mcp 0.5.0 → 0.7.0

package/README.md

@@ -32,7 +32,7 @@ whether to:
 
 Pattern is designed for agents to use **while they are building**.
 
-It exposes seven tools:
+It exposes eleven tools:
 
 - `recommend_component` — evaluates a UI component need and returns a
   structured recommendation.
@@ -57,6 +57,23 @@ It exposes seven tools:
 - `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).
+- `post_ledger_provenance_to_github` — posts that same artifact as a real
+  comment on a GitHub PR/issue, idempotently -- see [Tool:
+  `post_ledger_provenance_to_github`](#tool-post_ledger_provenance_to_github).
+  The one tool here with a real, visible side effect outside your own
+  machine; confirm with the user before calling it.
+- `sweep_ledger_liveness` — batch version of `check_ledger_liveness`
+  across a whole project (or every project in the ledger), plus
+  dangling-cluster detection -- see [Tool:
+  `sweep_ledger_liveness`](#tool-sweep_ledger_liveness). Meant to be
+  invoked by your own cron/CI, not something Pattern schedules itself.
+- `backfill_ledger_snapshot_ref` — best-effort `snapshot_ref`
+  reconstruction for entries written before that field existed -- see
+  [Tool: `backfill_ledger_snapshot_ref`](#tool-backfill_ledger_snapshot_ref).
 
 ## How it works
 
@@ -735,14 +752,16 @@ came back with `served_from_ledger: true`.
       "file_path": null,
       "snapshot_ref": "a1b2c3d4e5f6...",
       "last_verified_live": null,
-      "live_status": "unknown"
+      "live_status": "unknown",
+      "reconstructed_snapshot_ref": null
     }
   ]
 }
 ```
 
-`file_path`/`snapshot_ref`/`last_verified_live`/`live_status` are the
-ledger integrity + decision provenance fields -- see [Ledger integrity and
+`file_path`/`snapshot_ref`/`last_verified_live`/`live_status`/
+`reconstructed_snapshot_ref` 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`/
@@ -950,8 +969,11 @@ an arbitrary shell command.
 ```
 
 `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"`.
+`"dangling"` (only ever produced by
+[`sweep_ledger_liveness`](#tool-sweep_ledger_liveness)'s cluster
+detection, never by a single-entry `check_ledger_liveness` call -- see
+[Ledger integrity and decision
+provenance](#ledger-integrity-and-decision-provenance)).
 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
@@ -959,6 +981,249 @@ there's nothing to check. Results here are also layered onto
 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`.
+
+## Tool: `post_ledger_provenance_to_github`
+
+Posts one ledger entry's provenance artifact (the same content
+`export_ledger_provenance` produces) as a real comment on a GitHub PR or
+issue. **This is the one tool in this server with a real, visible side
+effect on a third-party service** -- every other tool here only ever
+touches local files. Confirm with the user before calling it, the same
+way you're expected to confirm before running a suggested
+`install_command` (see [Installation commands are not
+trusted](#installation-commands-are-not-trusted) and SECURITY.md).
+
+GitHub treats a PR and an issue identically for comments (both use the
+same `/issues/{number}/comments` endpoint), so there's one input shape
+for both -- no separate "is this a PR" flag.
+
+### Auth: `GITHUB_TOKEN`, not a GitHub App
+
+This resolves the open question left in [Ledger integrity and decision
+provenance](#ledger-integrity-and-decision-provenance)'s earlier writeup
+in favor of a **personal access token**, read from the `GITHUB_TOKEN`
+environment variable -- the same convention every GitHub Action and the
+`gh` CLI itself already use. Needs `repo` scope. A GitHub App was the
+alternative on the table, but it needs a hosted installation flow and a
+webhook receiver, which contradicts this project's entire distribution
+model (a local npm package, no hosted infrastructure -- see [Ledger
+integrity and decision provenance](#ledger-integrity-and-decision-provenance)
+and the Pattern Primer's build-order principle). Pattern manages no
+GitHub credential of its own, the same way it manages no git credential
+for `snapshot_ref` -- it just reads what's already in your environment.
+
+### Input
+
+```json
+{
+  "project_id": "my-booking-app",
+  "ledger_entry_id": "a1b2c3d4-...",
+  "repo": "my-org/my-booking-app",
+  "issue_number": 42
+}
+```
+
+All four fields are required.
+
+### Output
+
+```json
+{
+  "posted": true,
+  "comment_url": "https://github.com/my-org/my-booking-app/pull/42#issuecomment-...",
+  "comment_id": 123456789
+}
+```
+
+### Idempotent by construction
+
+Every posted comment is prefixed with a hidden HTML marker keyed to the
+ledger entry's id (`<!-- pattern-ledger-provenance:<id> -->`). A call
+first checks the thread's existing comments (most recent 100 -- full
+pagination isn't handled yet) for that marker; if found, it returns
+`{ "posted": false, "reason": "already_posted", "comment_url": "..." }`
+pointing at the existing comment instead of creating a duplicate. A
+repeat call is always safe to make.
+
+Errors (`isError: true`) clearly on: no `GITHUB_TOKEN` set, a malformed
+`repo` (not `owner/repo`), an unknown `ledger_entry_id`, or a GitHub API
+error (bad credentials, repo/issue not found, rate limit) -- the error
+message includes the real HTTP status and GitHub's own error text.
+
+## Tool: `sweep_ledger_liveness`
+
+Batch version of [`check_ledger_liveness`](#tool-check_ledger_liveness):
+updates `live_status` for every `file_path`-bearing entry across an
+entire project, or -- when `project_id` is omitted -- every `project_id`
+present in the ledger. This is the "on a schedule (project open or cron)"
+half of the referential-integrity design that `check_ledger_liveness`'s
+on-demand, single-project call doesn't cover.
+
+**Pattern has no daemon or scheduler of its own.** Each server invocation
+is transient, tied to its MCP host's lifecycle -- there is nowhere inside
+this server for a cron job to live. This tool is meant to be invoked by
+whatever external scheduler you already have (a cron job, a CI step
+running nightly), not something Pattern triggers automatically or ever
+will on its own.
+
+### Input
+
+```json
+{
+  "project_id": "my-booking-app"
+}
+```
+
+`project_id` is optional -- omit it to sweep every `project_id` present
+in the ledger in one call.
+
+### Output
+
+```json
+{
+  "projects_swept": 2,
+  "total_entries_checked": 14,
+  "dangling_clusters": [
+    { "project_id": "my-booking-app", "feature_id": "3f9a21c0", "entry_ids": ["...", "..."] }
+  ],
+  "per_project": [
+    { "project_id": "my-booking-app", "checked": 9, "total_entries": 12, "dangling_clusters": 1 },
+    { "project_id": "other-project", "checked": 5, "total_entries": 5, "dangling_clusters": 0 }
+  ]
+}
+```
+
+### Dangling clusters, and how "cluster" maps onto what the ledger actually stores
+
+The ledger has no explicit entry-to-entry reference field -- each line is
+an independent judgment record. `feature_id` (see [Feature cost
+attribution](#feature-cost-attribution)) is the one real grouping
+construct that already exists, so a "cluster" here means every entry
+sharing one `feature_id`, and "no live anchor" means none of them
+resolved to `live_status: "live"`. A single-entry group is just an
+ordinary orphaned/unknown entry, not a cluster phenomenon, so groups of
+one are never flagged.
+
+Every entry in a qualifying cluster gets `live_status: "dangling"` --
+overriding whatever `"orphaned"`/`"unknown"` value it had -- visible on
+its next `read_ledger`/`check_ledger_liveness` read via the same
+`ledger_liveness.jsonl` overlay `check_ledger_liveness` already writes to
+(see [Referential integrity](#referential-integrity-file_path--live_status)).
+Tested against the exact repro shape reported by a user: 13 entries, 12
+sharing a `feature_id` with no live anchor among them, 1 separate and
+live -- all 12 flag `dangling`, the 13th doesn't. Also tested at 200 and
+1,000 synthetic entries without reintroducing search+score-class latency
+(both complete in well under a second -- this is `fs.existsSync` calls
+and in-memory grouping, not API calls).
+
+## Tool: `backfill_ledger_snapshot_ref`
+
+Best-effort reconstruction of `snapshot_ref` for ledger entries written
+before that field existed (or written outside a git repository): finds
+the commit that was `HEAD` at or just before each entry's own timestamp
+(`git log --before=<timestamp> -1 --format=%H`). Entries that already
+have a real `snapshot_ref` are reported but never touched -- backfill
+only ever fills a gap, never second-guesses a captured value.
+
+### Input
+
+```json
+{
+  "project_id": "my-booking-app",
+  "ledger_entry_id": "a1b2c3d4-..."
+}
+```
+
+`ledger_entry_id` is optional -- omit it to backfill every entry in the
+project missing `snapshot_ref`.
+
+### Output
+
+```json
+{
+  "project_id": "my-booking-app",
+  "attempted": 3,
+  "reconstructed": 2,
+  "results": [
+    { "ledger_entry_id": "a1b2c3d4-...", "already_had_snapshot_ref": false, "reconstructed_snapshot_ref": "9f3a1c7e2b0d4f5a6b7c8d9e0f1a2b3c4d5e6f70" },
+    { "ledger_entry_id": "e5f6a7b8-...", "already_had_snapshot_ref": false, "reconstructed_snapshot_ref": null }
+  ]
+}
+```
+
+### A reconstructed value is always labeled, never presented as real
+
+Necessarily an approximation, not a guarantee: a rebase, force-push, or
+history rewrite since that timestamp can make "the commit `HEAD` pointed
+to then" no longer resolve to what the codebase actually looked like at
+judgment time. Every attempt is persisted (including failures -- a
+project whose git history doesn't reach back that far, or that isn't a
+git repository at all) to `~/.pattern/snapshot_backfill.jsonl` (override
+with `PATTERN_SNAPSHOT_BACKFILL_PATH`), and surfaces on later reads as
+`reconstructed_snapshot_ref` -- a field kept fully separate from
+`snapshot_ref` itself, never overwriting or being confused with it.
+[`export_ledger_provenance`](#tool-export_ledger_provenance) and
+[`post_ledger_provenance_to_github`](#tool-post_ledger_provenance_to_github)
+both render a reconstructed value with an explicit "(reconstructed via
+backfill -- best-effort approximation, not the original captured
+snapshot)" label, never silently as if it were equivalent to a value
+captured live.
+
+Tested against a real throwaway git repo with known commit history (an
+entry timestamped between two real commits reconstructs to exactly the
+first one), a 200-entry synthetic ledger outside any git repo (every
+attempt fails fast and reports `null` rather than throwing), and a
+read-only run against this project's own real `coop-commerce` ledger
+entries, per the spec's own test plan.
+
 ## Feature cost attribution
 
 Every `recommend_component` call that writes to the ledger -- a fresh
@@ -1126,8 +1391,15 @@ 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.
 
-Not yet built (P1-P3 of Feature 2): a markdown export of one entry's full
-record for attaching to a PR/issue, and the GitHub posting action itself.
+[`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.
+[`post_ledger_provenance_to_github`](#tool-post_ledger_provenance_to_github)
+posts that same artifact automatically, idempotently, using a personal
+`GITHUB_TOKEN` rather than a GitHub App (see that tool's docs for why).
+[`backfill_ledger_snapshot_ref`](#tool-backfill_ledger_snapshot_ref)
+reconstructs a best-effort `snapshot_ref` for entries that predate the
+field, always clearly labeled as reconstructed wherever it's rendered.
 
 ### Referential integrity: `file_path` / `live_status`
 
@@ -1144,26 +1416,26 @@ check whether that file still exists and still mentions
   `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
+- **`dangling`** -- only ever produced by
+  [`sweep_ledger_liveness`](#tool-sweep_ledger_liveness), never by
+  `check_ledger_liveness` on its own: a cluster of 2+ entries sharing a
+  `feature_id` where none of them resolved to `"live"`. Graph-level
+  analysis across a project's whole entry set, not a single-entry check
+  -- see that tool's docs for why `feature_id` is the grouping used.
+
+`check_ledger_liveness` remains on-demand and single-project;
+[`sweep_ledger_liveness`](#tool-sweep_ledger_liveness) is the
+scheduled/batch counterpart -- meant to be invoked by your own cron/CI,
+since Pattern has no scheduler of its own. `live_status`/`last_verified_live`
+start `"unknown"`/`null` on every entry at write time and only ever
+advance via a `check_ledger_liveness`/`sweep_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:
@@ -1392,6 +1664,38 @@ Pattern caches its system instructions using `cache_control: ephemeral`.
 The instructions are the same across calls, so repeated requests don't
 pay the full input cost for that block.
 
+### Measured cache and fetch behavior
+
+`_meta.tokens_used.input_breakdown` splits input tokens into `fresh`,
+`cache_write`, and `cache_read` (see [The `_meta`
+field](#the-_meta-field)) -- added specifically to check assumptions
+about caching against real numbers rather than guessing. Two real
+findings so far:
+
+- **A single, non-repeat call is not "all fresh."** The working
+  assumption had been that only exact-repeat calls (the [ledger cache
+  hit](#the-cache-hit-exception)) benefit from caching at all. A live
+  test disproved that: a fresh, non-repeat toast-component call came back
+  with roughly half its input tokens served from `cache_read`. A
+  follow-up 4-case sample (2026-09-02, spanning a clean `use_existing`
+  call, a `custom_build` call, and two historically boundary/inconsistent
+  cases) confirmed this wasn't a fluke -- `cache_read` share stayed in a
+  46-63% band across all four, regardless of call shape.
+- **`fresh` (fully-priced, never-cached) tokens are driven by whether the
+  call reaches step 6's Mobbin/Figma reference search, not by general
+  complexity or the boundary-risk ensemble firing.** In that same
+  4-case sample, the two `use_existing` calls had negligible `fresh`
+  tokens (0.2%); both `custom_build` calls (which searched Mobbin/Figma)
+  had 24-27.5% `fresh` -- even though, in both of those cases, the actual
+  Mobbin *fetch* failed (`url_not_accessible`, 0 bytes returned). That
+  rules out fetched-page content size as the driver for this cost --
+  it's the extra Mobbin/Figma-restricted *search* calls themselves. This
+  is why [`PATTERN_FETCH_MAX_CONTENT_TOKENS`](#fetch-grounded-scoring-and-reference-verification)
+  was trimmed (a fetch-content cap can't fix a search-call cost) rather
+  than split per-step as originally considered, and why reducing
+  Mobbin/Figma search overhead is tracked as its own, differently-scoped
+  future item rather than folded into that change.
+
 ### Search limits
 
 Pattern limits candidate discovery to 3 web searches -- one per source.
@@ -1429,9 +1733,12 @@ the category page), there's no safe fallback for an unverified met/not-met
 call, so nothing is silently corrected -- `scoring_fetch` just tells you
 whether the grounding actually ran.
 
-A fetch can read up to 15,000 content tokens. `web_fetch` has no separate
-per-call fee; the cost comes from the content added to the model's
-context.
+A fetch can read up to `PATTERN_FETCH_MAX_CONTENT_TOKENS` content tokens
+(default 12,000 -- trimmed from 15,000 after a real instrumentation
+sample showed the largest actual fetched page was ~10.7k tokens, see
+[Measured cache and fetch behavior](#measured-cache-and-fetch-behavior)
+above). `web_fetch` has no separate per-call fee; the cost comes from the
+content added to the model's context.
 
 ### Choosing a cheaper model
 

package/dist/index.js

@@ -59,6 +59,29 @@ const SEARCH_BUDGET = SEARCH_BUDGET_RAW.trim().toLowerCase() === "unlimited"
         }
         return parsed;
     })();
+// Cost/latency reduction plan, step 2 (BACKLOG.md): trimmed from 15,000
+// after a real 4-case instrumentation sample (2026-09-02) showed the
+// largest actual fetched page was ~10.7k tokens (a shadcn doc page),
+// comfortably under this new cap with headroom. Deliberately NOT split
+// into separate step-4 (candidate-doc) vs. step-6 (Mobbin/Figma) caps as
+// originally scoped: both steps share one web_fetch tool instance, so a
+// real split would mean defining two separately-named web_fetch tools and
+// trusting the model to pick the right one per step -- a real behavior
+// risk for a saving the same sample disproved anyway. Both custom_build
+// cases in that sample had elevated "fresh" (fully-priced, uncached)
+// token counts even though their Mobbin fetch *failed*
+// (url_not_accessible, 0 bytes returned) -- the cost driver there is the
+// extra Mobbin/Figma-restricted search calls, not fetched content size,
+// so this cap can't address it. That's tracked as a separate, differently
+// -scoped backlog item, not folded into this one.
+const FETCH_MAX_CONTENT_TOKENS_RAW = process.env.PATTERN_FETCH_MAX_CONTENT_TOKENS ?? "12000";
+const FETCH_MAX_CONTENT_TOKENS = (() => {
+    const parsed = Number.parseInt(FETCH_MAX_CONTENT_TOKENS_RAW, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`PATTERN_FETCH_MAX_CONTENT_TOKENS must be a positive integer, got: ${FETCH_MAX_CONTENT_TOKENS_RAW}`);
+    }
+    return parsed;
+})();
 // Static skip-list: single-purpose primitives with no meaningful internal
 // structure to score coverage against. Decided in the product brief as a
 // starting point -- revisit once real usage data exists (see README).
@@ -188,6 +211,31 @@ function computeSnapshotRef(root) {
         return null;
     }
 }
+// Feature 2 / Decision Provenance, P3: best-effort reconstruction of
+// snapshot_ref for an entry written before that field existed (or written
+// outside a git repo -- though a project that's never used git has
+// nothing to reconstruct from either way). Finds the commit that was HEAD
+// at or just before the entry's own timestamp. Necessarily an
+// approximation, not a guarantee: a rebase, force-push, or history
+// rewrite since that time can make "the commit HEAD pointed to then" no
+// longer resolve to what the codebase actually looked like at judgment
+// time -- exactly the risk the spec's own mitigation table already names.
+// Read-only, same timeout/error-swallowing discipline as
+// computeSnapshotRef above.
+function reconstructSnapshotRef(root, atISOTimestamp) {
+    try {
+        const sha = execFileSync("git", ["log", `--before=${atISOTimestamp}`, "-1", "--format=%H"], {
+            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
@@ -442,6 +490,10 @@ 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 POST_LEDGER_PROVENANCE_TOOL_NAME = "post_ledger_provenance_to_github";
+const SWEEP_LEDGER_LIVENESS_TOOL_NAME = "sweep_ledger_liveness";
+const BACKFILL_LEDGER_SNAPSHOT_REF_TOOL_NAME = "backfill_ledger_snapshot_ref";
 const INPUT_SCHEMA = {
     type: "object",
     properties: {
@@ -677,6 +729,68 @@ const CHECK_LEDGER_LIVENESS_INPUT_SCHEMA = {
     },
     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"],
+};
+const POST_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 post, from read_ledger or check_ledger_liveness.",
+        },
+        repo: {
+            type: "string",
+            description: 'GitHub repo in "owner/repo" form, e.g. "my-org/my-booking-app".',
+        },
+        issue_number: {
+            type: "number",
+            description: "The PR or issue number to comment on -- GitHub treats both identically for comments, so no separate type flag is needed.",
+        },
+    },
+    required: ["project_id", "ledger_entry_id", "repo", "issue_number"],
+};
+const SWEEP_LEDGER_LIVENESS_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "Optional. Scope the sweep to one project_id. Omit to sweep every " +
+                "project_id present in the ledger -- the whole-ledger, scheduler-driven " +
+                "mode this tool exists for.",
+        },
+    },
+    required: [],
+};
+const BACKFILL_LEDGER_SNAPSHOT_REF_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "The project_id whose ledger entries to backfill.",
+        },
+        ledger_entry_id: {
+            type: "string",
+            description: "Optional. Backfill just this one entry instead of every entry for project_id missing snapshot_ref.",
+        },
+    },
+    required: ["project_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
@@ -956,8 +1070,10 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${p
                 max_uses: 3,
                 // Category/browse pages can be large, and all we need from them
                 // is a permalink, not the full page -- caps token cost of a
-                // fetch that turns out not to have a deep link after all.
-                max_content_tokens: 15000,
+                // fetch that turns out not to have a deep link after all. See
+                // FETCH_MAX_CONTENT_TOKENS above for why this is 12,000, not the
+                // original 15,000, and why it isn't split per-step.
+                max_content_tokens: FETCH_MAX_CONTENT_TOKENS,
             },
         ],
     });
@@ -1362,9 +1478,21 @@ function readLedgerLivenessRecords(ledgerEntryId) {
     }
     return records;
 }
+// Deliberately not a sort-then-take-first: readLedgerLivenessRecords
+// returns records in file/append order (oldest first), and a descending
+// sort by timestamp is NOT tie-safe -- JS's stable sort preserves the
+// original relative order among equal timestamps, so on a tie (two
+// records appended within the same millisecond, which sweepLedgerLiveness
+// does routinely -- a per-entry check followed immediately by a
+// dangling-cluster append for the same entry) it would silently return
+// the OLDER of the two. reduce with >= walks forward through true append
+// order and lets each later-appended tied record win, which is what
+// "latest" actually means here.
 function latestLiveness(ledgerEntryId) {
-    const records = readLedgerLivenessRecords(ledgerEntryId).sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
-    return records[0] ?? null;
+    const records = readLedgerLivenessRecords(ledgerEntryId);
+    if (records.length === 0)
+        return null;
+    return records.reduce((latest, r) => (new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime() ? r : latest));
 }
 function withLatestLiveness(entry) {
     const latest = latestLiveness(entry.id);
@@ -1372,6 +1500,59 @@ function withLatestLiveness(entry) {
         return entry;
     return { ...entry, live_status: latest.live_status, last_verified_live: latest.timestamp };
 }
+// Feature 2 P3's overlay -- same append-only/latest-wins convention as
+// ledger_liveness.jsonl above, kept as a fully separate file/function pair
+// rather than folded into the liveness overlay: these two overlays answer
+// unrelated questions (is the file still there vs. what commit was this
+// judged against) and happen to share only their storage shape, not their
+// meaning.
+const SNAPSHOT_BACKFILL_PATH = process.env.PATTERN_SNAPSHOT_BACKFILL_PATH ?? join(homedir(), ".pattern", "snapshot_backfill.jsonl");
+function appendSnapshotBackfillRecord(record) {
+    mkdirSync(dirname(SNAPSHOT_BACKFILL_PATH), { recursive: true });
+    appendFileSync(SNAPSHOT_BACKFILL_PATH, JSON.stringify(record) + "\n", "utf8");
+}
+function readSnapshotBackfillRecords(ledgerEntryId) {
+    let raw;
+    try {
+        raw = readFileSync(SNAPSHOT_BACKFILL_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;
+}
+// Same tie-safety reasoning as latestLiveness above.
+function latestSnapshotBackfill(ledgerEntryId) {
+    const records = readSnapshotBackfillRecords(ledgerEntryId);
+    if (records.length === 0)
+        return null;
+    return records.reduce((latest, r) => (new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime() ? r : latest));
+}
+// Only overlays onto entries that actually need it -- an entry with a
+// real snapshot_ref never consults the backfill overlay at all, so a
+// stray/stale backfill record can never shadow a genuine captured value.
+function withReconstructedSnapshotRef(entry) {
+    if (entry.snapshot_ref)
+        return entry;
+    const latest = latestSnapshotBackfill(entry.id);
+    if (!latest)
+        return entry;
+    return { ...entry, reconstructed_snapshot_ref: latest.reconstructed_snapshot_ref };
+}
 // 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;
@@ -1379,9 +1560,10 @@ function withLatestLiveness(entry) {
 // 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.
+// "dangling" (a cluster of entries with no live anchor anywhere among
+// them) is graph-level analysis across a whole project's entries, not a
+// single-entry check -- see detectDanglingClusters, part of
+// sweep_ledger_liveness (Feature 1 P2/P3), not this function.
 function checkFileLiveStatus(entry) {
     if (!entry.file_path)
         return "unknown";
@@ -1413,11 +1595,12 @@ function checkLedgerEntryLiveness(entry) {
     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.
+// (the design's "on demand via an MCP call" case -- see
+// sweepLedgerLiveness below for the scheduled/batch case, Feature 1 P2).
+// 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) => {
@@ -1447,6 +1630,37 @@ function checkLedgerLiveness(input) {
         results,
     };
 }
+// backfill_ledger_snapshot_ref tool (Feature 2 P3): attempts
+// reconstructSnapshotRef for every entry in a project that's missing a
+// real snapshot_ref, and persists each attempt to snapshot_backfill.jsonl
+// regardless of outcome -- a documented "we tried, here's what we found"
+// audit trail, not just a cache, since a failed reconstruction is itself
+// meaningful information (this project's git history doesn't reach back
+// that far, or PROJECT_ROOT isn't a git repo at all). Entries that
+// already have a real snapshot_ref are reported but never touched --
+// backfill only ever fills a gap, never second-guesses a captured value.
+function backfillLedgerSnapshotRefs(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.snapshot_ref) {
+            return { ledger_entry_id: e.id, already_had_snapshot_ref: true, reconstructed_snapshot_ref: null };
+        }
+        const reconstructed = reconstructSnapshotRef(PROJECT_ROOT, e.timestamp);
+        appendSnapshotBackfillRecord({
+            id: randomUUID(),
+            timestamp: new Date().toISOString(),
+            ledger_entry_id: e.id,
+            project_id: e.project_id,
+            reconstructed_snapshot_ref: reconstructed,
+        });
+        return { ledger_entry_id: e.id, already_had_snapshot_ref: false, reconstructed_snapshot_ref: reconstructed };
+    });
+    return {
+        attempted: results.filter((r) => !r.already_had_snapshot_ref).length,
+        reconstructed: results.filter((r) => r.reconstructed_snapshot_ref !== null).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)
@@ -1477,8 +1691,9 @@ function readLedgerEntries(projectId) {
                     snapshot_ref: rawEntry.snapshot_ref ?? null,
                     last_verified_live: rawEntry.last_verified_live ?? null,
                     live_status: rawEntry.live_status ?? "unknown",
+                    reconstructed_snapshot_ref: rawEntry.reconstructed_snapshot_ref ?? null,
                 };
-                entries.push(withLatestLiveness(normalized));
+                entries.push(withReconstructedSnapshotRef(withLatestLiveness(normalized)));
             }
         }
         catch {
@@ -1487,6 +1702,109 @@ function readLedgerEntries(projectId) {
     }
     return entries;
 }
+// sweep_ledger_liveness (Feature 1 P2) needs every project_id present in
+// the ledger when none is specified -- readLedgerEntries always filters
+// to one project_id, so this is the one place that reads every line
+// unfiltered. Same "missing/malformed collapses to empty" tolerance as
+// readLedgerEntries itself.
+function listAllProjectIds() {
+    let raw;
+    try {
+        raw = readFileSync(LEDGER_PATH, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const ids = new Set();
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && typeof parsed.project_id === "string") {
+                ids.add(parsed.project_id);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return [...ids];
+}
+// Feature 1 P3: the graph-level half of referential integrity that
+// checkFileLiveStatus's single-entry check can't do. Pattern's ledger has
+// no explicit entry-to-entry reference field (each line is an independent
+// judgment record) -- feature_id is the one real grouping construct that
+// already exists (deriveFeatureId), so a "cluster" here means every entry
+// sharing one feature_id, and "cross-linked with no live anchor" means
+// none of them resolved to live_status "live". A cluster of exactly one
+// entry is just an ordinary orphaned/unknown entry, not a cluster
+// phenomenon, so single-entry groups are never flagged.
+//
+// Must run after checkLedgerLiveness has updated live_status for the
+// same project -- otherwise this would be judging stale per-entry
+// statuses. sweepLedgerLiveness below enforces that ordering; this
+// function does not re-check individual entries itself.
+function detectDanglingClusters(projectId) {
+    const entries = readLedgerEntries(projectId);
+    const byFeature = new Map();
+    for (const e of entries) {
+        const group = byFeature.get(e.feature_id) ?? [];
+        group.push(e);
+        byFeature.set(e.feature_id, group);
+    }
+    const clusters = [];
+    for (const [featureId, group] of byFeature) {
+        if (group.length < 2)
+            continue;
+        if (group.some((e) => e.live_status === "live"))
+            continue;
+        clusters.push({ feature_id: featureId, entry_ids: group.map((e) => e.id) });
+        for (const e of group) {
+            appendLedgerLivenessRecord({
+                id: randomUUID(),
+                timestamp: new Date().toISOString(),
+                ledger_entry_id: e.id,
+                project_id: projectId,
+                live_status: "dangling",
+                checked_file_path: e.file_path,
+            });
+        }
+    }
+    return clusters;
+}
+// The MCP tool: batch-updates live_status across an entire ledger,
+// optionally scoped to one project_id, but sweeping every project_id
+// present when omitted -- the "on a schedule (project open or cron)" half
+// of the design that check_ledger_liveness's on-demand, single-project
+// call (P1) doesn't cover. Pattern has no daemon or background process of
+// its own to schedule this from (each server invocation is transient,
+// tied to its MCP host's lifecycle) -- this tool is meant to be invoked
+// by whatever external scheduler you already have (a cron job, a CI
+// step), not something Pattern triggers on its own.
+function sweepLedgerLiveness(input) {
+    const projectIds = input.project_id ? [input.project_id] : listAllProjectIds();
+    const perProject = [];
+    const allDangling = [];
+    for (const projectId of projectIds) {
+        const liveness = checkLedgerLiveness({ project_id: projectId });
+        const clusters = detectDanglingClusters(projectId);
+        for (const c of clusters)
+            allDangling.push({ project_id: projectId, ...c });
+        perProject.push({
+            project_id: projectId,
+            checked: liveness.checked,
+            total_entries: liveness.total_entries,
+            dangling_clusters: clusters.length,
+        });
+    }
+    return {
+        projects_swept: projectIds.length,
+        total_entries_checked: perProject.reduce((sum, p) => sum + p.checked, 0),
+        dangling_clusters: allDangling,
+        per_project: perProject,
+    };
+}
 // The only entry point that writes ledger.jsonl. Validates every
 // candidate against the DistilledCandidate boundary before it ever touches
 // disk -- a raw object reaching here throws rather than silently
@@ -1541,6 +1859,151 @@ 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);
 }
+// entry.reconstructed_snapshot_ref only ever gets consulted when
+// snapshot_ref itself is null (see withReconstructedSnapshotRef) -- this
+// still checks both explicitly, rather than assuming that invariant holds,
+// so the two can never be silently conflated even if that changes later.
+// A reconstructed value is always labeled as such: it's an approximation
+// (the commit HEAD probably pointed to at that timestamp), not the
+// original captured snapshot, and presenting it unlabeled would overstate
+// its reliability.
+function formatSnapshotLine(entry) {
+    if (entry.snapshot_ref)
+        return "`" + entry.snapshot_ref + "`";
+    if (entry.reconstructed_snapshot_ref) {
+        return ("`" +
+            entry.reconstructed_snapshot_ref +
+            "` (reconstructed via backfill -- best-effort approximation, not the original captured snapshot)");
+    }
+    return "not available (project root wasn't a git repository at judgment time)";
+}
+// 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 (see export_ledger_provenance and
+// post_ledger_provenance_to_github, which attach 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:** ${formatSnapshotLine(entry)}`);
+    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");
+}
+// Feature 2 / Decision Provenance, P2: posts an export_ledger_provenance
+// artifact as a real comment on a GitHub PR or issue. GitHub's REST API
+// treats a PR and an issue identically for comments (both are backed by
+// the same /issues/{number}/comments endpoint), so one input shape covers
+// both -- no separate "is this a PR" flag needed.
+//
+// This is the one tool in this server with a real, visible side effect on
+// a third-party service outside the caller's own machine -- every other
+// tool here only ever touches local files. The calling agent should
+// confirm with the user before invoking it, the same way it's expected to
+// confirm before running a suggested install_command (see SECURITY.md).
+//
+// Auth resolves the spec's own open question (personal token vs. GitHub
+// App) in favor of a personal token: reads GITHUB_TOKEN from the
+// environment, the same convention every GitHub Action and the `gh` CLI
+// itself use. A GitHub App needs a hosted installation flow and a webhook
+// receiver, which contradicts this project's "local npm package, no
+// hosted infrastructure" distribution model (see the README's Ledger
+// integrity section and the Pattern Primer's build-order principle) --
+// Pattern manages no GitHub credential of its own, the same way it
+// manages no git credential for computeSnapshotRef above.
+//
+// Idempotent by construction, not just by convention: every posted
+// comment is prefixed with a hidden HTML marker keyed to the ledger
+// entry's id, and a post first checks existing comments for that marker
+// -- a repeat call for the same entry returns posted: false instead of
+// creating a duplicate. Only checks the most recent 100 comments (one
+// page) -- a thread with more prior comments than that is an edge case
+// this pass doesn't handle; full pagination is a later concern, not built
+// here.
+const GITHUB_API_BASE = process.env.PATTERN_GITHUB_API_BASE ?? "https://api.github.com";
+function provenanceMarker(ledgerEntryId) {
+    return `<!-- pattern-ledger-provenance:${ledgerEntryId} -->`;
+}
+async function postProvenanceToGitHub(input) {
+    const token = process.env.GITHUB_TOKEN;
+    if (!token) {
+        throw new Error("GITHUB_TOKEN is not set. This tool posts a real comment to GitHub and needs a personal access token " +
+            "with repo scope (the same one `gh auth login` or a GitHub Action would use) -- set the GITHUB_TOKEN " +
+            "environment variable and retry.");
+    }
+    if (!/^[^/\s]+\/[^/\s]+$/.test(input.repo)) {
+        throw new Error(`repo must be in "owner/repo" form, got: "${input.repo}"`);
+    }
+    const entry = readLedgerEntries(input.project_id).find((e) => e.id === input.ledger_entry_id);
+    if (!entry) {
+        throw new Error(`No ledger entry with id "${input.ledger_entry_id}" found for project_id "${input.project_id}". Use read_ledger to list entries and their ids.`);
+    }
+    const marker = provenanceMarker(entry.id);
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github+json",
+        "Content-Type": "application/json",
+        "User-Agent": "pattern-mcp",
+    };
+    const commentsUrl = `${GITHUB_API_BASE}/repos/${input.repo}/issues/${input.issue_number}/comments`;
+    const listResponse = await fetch(`${commentsUrl}?per_page=100`, { headers });
+    if (!listResponse.ok) {
+        const errText = await listResponse.text();
+        throw new Error(`GitHub API error ${listResponse.status} listing comments on ${input.repo}#${input.issue_number}: ${errText}`);
+    }
+    const existingComments = (await listResponse.json());
+    const existing = existingComments.find((c) => c.body.includes(marker));
+    if (existing) {
+        return { posted: false, reason: "already_posted", comment_url: existing.html_url, comment_id: existing.id };
+    }
+    const body = `${marker}\n\n${formatProvenanceArtifact(entry)}`;
+    const postResponse = await fetch(commentsUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ body }),
+    });
+    if (!postResponse.ok) {
+        const errText = await postResponse.text();
+        throw new Error(`GitHub API error ${postResponse.status} posting comment to ${input.repo}#${input.issue_number}: ${errText}`);
+    }
+    const created = (await postResponse.json());
+    return { posted: true, comment_url: created.html_url, comment_id: created.id };
+}
 // 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
@@ -1791,6 +2254,7 @@ function buildLedgerEntry(input, projectId, result, opts) {
         file_path: input.file_path ?? null,
         last_verified_live: null,
         live_status: "unknown",
+        reconstructed_snapshot_ref: null,
     };
 }
 async function judgeComponent(input) {
@@ -2477,6 +2941,65 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "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 -- see post_ledger_provenance_to_github for that.",
+            inputSchema: EXPORT_LEDGER_PROVENANCE_INPUT_SCHEMA,
+        },
+        {
+            name: POST_LEDGER_PROVENANCE_TOOL_NAME,
+            description: "Posts one ledger entry's provenance artifact (same content " +
+                "export_ledger_provenance produces) as a real comment on a GitHub " +
+                "PR or issue. This is the one tool in this server with a real, " +
+                "visible side effect on a third-party service, not just your own " +
+                "machine -- confirm with the user before calling this, the same " +
+                "way you'd confirm before running a suggested install_command " +
+                "(see SECURITY.md). Requires GITHUB_TOKEN (a personal access " +
+                "token with repo scope) in the environment -- Pattern manages no " +
+                "GitHub credential of its own. Idempotent: a repeat call for the " +
+                "same ledger_entry_id/repo/issue_number detects the previously " +
+                "posted comment (via a hidden marker) and returns posted: false " +
+                "instead of creating a duplicate.",
+            inputSchema: POST_LEDGER_PROVENANCE_INPUT_SCHEMA,
+        },
+        {
+            name: SWEEP_LEDGER_LIVENESS_TOOL_NAME,
+            description: "Batch version of check_ledger_liveness: updates live_status for " +
+                "every file_path-bearing entry across an entire project (or, when " +
+                "project_id is omitted, every project_id present in the ledger), " +
+                "then flags dangling clusters -- groups of 2+ entries sharing a " +
+                "feature_id where none of them resolved to live_status 'live'. " +
+                "Pattern has no daemon or scheduler of its own (each server " +
+                "invocation is transient, tied to its MCP host's lifecycle) -- " +
+                "this tool is meant to be invoked by whatever external scheduler " +
+                "you already have (a cron job, a CI step), not something Pattern " +
+                "triggers automatically. Tested at 200 and 1,000 synthetic " +
+                "entries without reintroducing search+score latency -- this is " +
+                "fs stat calls, not API calls.",
+            inputSchema: SWEEP_LEDGER_LIVENESS_INPUT_SCHEMA,
+        },
+        {
+            name: BACKFILL_LEDGER_SNAPSHOT_REF_TOOL_NAME,
+            description: "Best-effort reconstruction of snapshot_ref for ledger entries " +
+                "written before that field existed (or written outside a git " +
+                "repo): finds the commit that was HEAD at or just before each " +
+                "entry's own timestamp. Always clearly distinguished from a real " +
+                "captured snapshot_ref wherever it's rendered (export_ledger_provenance, " +
+                "post_ledger_provenance_to_github) -- a rebase/force-push/history " +
+                "rewrite since that time can make this approximation wrong, so " +
+                "it's never presented as equivalent to a value actually captured " +
+                "live. Entries that already have a real snapshot_ref are reported " +
+                "but never touched. Persists every attempt (including failures) " +
+                "for later lookup; never modifies ledger.jsonl itself.",
+            inputSchema: BACKFILL_LEDGER_SNAPSHOT_REF_INPUT_SCHEMA,
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -2621,6 +3144,75 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    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,
+            };
+        }
+    }
+    if (request.params.name === POST_LEDGER_PROVENANCE_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const result = await postProvenanceToGitHub(args);
+            return {
+                content: [{ type: "text", text: JSON.stringify(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 === SWEEP_LEDGER_LIVENESS_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const result = sweepLedgerLiveness(args);
+            return {
+                content: [{ type: "text", text: JSON.stringify(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 === BACKFILL_LEDGER_SNAPSHOT_REF_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const result = backfillLedgerSnapshotRefs(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,
+            };
+        }
+    }
     throw new Error(`Unknown tool: ${request.params.name}`);
 });
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-mcp",
-  "version": "0.5.0",
+  "version": "0.7.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",