pattern-mcp 0.7.0 → 0.8.0

package/README.md

@@ -2,15 +2,32 @@
 
 [![Publish](https://github.com/donaldrichard19-LVD/pattern-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/donaldrichard19-LVD/pattern-mcp/actions/workflows/publish.yml)
 [![npm version](https://img.shields.io/npm/v/pattern-mcp.svg)](https://www.npmjs.com/package/pattern-mcp)
-[![npm downloads](https://img.shields.io/npm/dm/pattern-mcp.svg)](https://www.npmjs.com/package/pattern-mcp)
+[![npm downloads](https://img.shields.io/npm/dt/pattern-mcp.svg)](https://www.npmjs.com/package/pattern-mcp)
 [![MIT license](https://img.shields.io/badge/license-MIT-111111.svg)](./LICENSE)
 
-Pattern is an MCP server that checks a UI component need against real,
-current evidence before your agent commits to it, so a wrong decision
-gets caught before it's built, not after.
+Pattern solves a simple problem: agents don't always follow your design
+guidance. Instead of relying on the agent to interpret and follow
+instructions, Pattern turns that guidance into a checkable process. It
+evaluates UI components from external libraries or your own design
+system against a requirements checklist, then tells the agent whether to
+use an existing component or build one from scratch using a concrete
+design reference.
 
 [Website](https://usepattern.sh) · [npm](https://www.npmjs.com/package/pattern-mcp) · [Report an issue](https://github.com/donaldrichard19-LVD/pattern-mcp/issues/new/choose)
 
+<details>
+<summary><strong>Contents</strong> (click to expand)</summary>
+
+- [Install](#install) · [What Pattern Does](#what-pattern-does) · [How it works](#how-it-works) · [Quick Start](#quick-start) · [Try it](#try-it) · [Validation examples](#validation-examples)
+- **Make the judgment call:** [`recommend_component`](#tool-recommend_component) · [`extract_requirements`](#tool-extract_requirements)
+- **Track cost and outcome:** [`record_component_decision`](#tool-record_component_decision) · [`read_ledger`](#tool-read_ledger) · [`report_build_cost`](#tool-report_build_cost) · [`report_outcome_proxy`](#tool-report_outcome_proxy) · [Feature cost attribution](#feature-cost-attribution) · [Outcome proxies](#outcome-proxies) · [Per-project judgment ledger](#per-project-judgment-ledger)
+- **Verify and export old decisions:** [`check_ledger_liveness`](#tool-check_ledger_liveness) · [`sweep_ledger_liveness`](#tool-sweep_ledger_liveness) · [`export_ledger_provenance`](#tool-export_ledger_provenance) · [`backfill_ledger_snapshot_ref`](#tool-backfill_ledger_snapshot_ref) · [`post_ledger_provenance_to_github`](#tool-post_ledger_provenance_to_github) · [Ledger integrity and decision provenance](#ledger-integrity-and-decision-provenance) (design overview — start here for how the five fit together)
+- [Per-project decision memory](#per-project-decision-memory) · [Security and privacy](#security-and-privacy) · [Telemetry](#telemetry)
+- **Cost:** [The `_meta` field](#the-_meta-field) · [Prompt caching](#prompt-caching) · [Measured cache and fetch behavior](#measured-cache-and-fetch-behavior) · [Search limits](#search-limits) · [Ensemble cost](#ensemble-cost-boundary-risk-cases-only) · [Session call cap](#session-call-cap)
+- [Local call log](#local-call-log) · [Known limitations](#known-limitations)
+
+</details>
+
 ## Install
 
 ```bash
@@ -32,13 +49,18 @@ whether to:
 
 Pattern is designed for agents to use **while they are building**.
 
-It exposes eleven tools:
+It exposes eleven tools, in three groups:
+
+**Make the judgment call.**
 
 - `recommend_component` — evaluates a UI component need and returns a
   structured recommendation.
 - `extract_requirements` — runs just the requirement-extraction step on
   its own, so you can inspect or hand-edit the checklist before
   `recommend_component` spends its search+score budget on it.
+
+**Track what it cost and what actually happened.**
+
 - `record_component_decision` — records what the agent actually did so
   future recommendations in the same project can take that decision into
   account.
@@ -54,26 +76,27 @@ It exposes eleven tools:
   merge, kept-vs-replaced) for one feature, deliberately independent of
   Pattern's own verdict -- see [Outcome
   proxies](#outcome-proxies).
+
+**Verify old decisions still hold up, and export a record of them.** See
+[Ledger integrity and decision
+provenance](#ledger-integrity-and-decision-provenance) for how these five
+fit together.
+
 - `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.
+  `file_path` still exists and still references its `chosen_candidate`.
 - `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.
+  dangling-cluster detection. Meant to be invoked by your own cron/CI, not
+  something Pattern schedules itself.
+- `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.
 - `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).
+  reconstruction for entries written before that field existed.
+- `post_ledger_provenance_to_github` — posts an `export_ledger_provenance`
+  artifact as a real comment on a GitHub PR/issue, idempotently. The one
+  tool here with a real, visible side effect outside your own machine;
+  confirm with the user before calling it.
 
 ## How it works
 
@@ -577,6 +600,114 @@ The calling agent should:
 
 See [SECURITY.md](./SECURITY.md) for more details.
 
+## Tool: `register_design_system`
+
+Points `recommend_component` at *this project's own* design system instead
+of shadcn/ui, 21st.dev, and ReUI -- for a solo dev with their own component
+library or design spec who wants Pattern's coverage scoring against
+candidates they'll actually use, not external libraries they won't. This is
+the Solo Dev architecture from `pattern-solo-design-system-architecture.md`:
+local, per-project, one-or-the-other -- registering a design system for a
+`project_id` **replaces** external-library scoring for that project
+entirely, it does not add to it. There's no shared/remote ledger, no
+multi-user attribution, and no team auth in this scope -- those are
+deliberately deferred to a team phase, only if this use case proves out.
+
+### Input
+
+Exactly one of `manifest_path` or `directory_path` is required, both
+relative to the project root (`PATTERN_PROJECT_ROOT`, defaults to this
+server's working directory) -- never an absolute path.
+
+```json
+{
+  "project_id": "my-booking-app",
+  "directory_path": "src/components"
+}
+```
+
+- **`manifest_path`** -- a components manifest. Two recognized shapes:
+  - A hand-authored JSON array of `{name, props, description,
+    usage_example}` objects, optionally wrapped in `{"components": [...]}`.
+  - A Storybook-exported `stories.json`/`index.json` file (an object with a
+    top-level `entries` or `stories` map). Component names only in this
+    case -- Storybook's basic export doesn't carry prop data, so candidates
+    from this path start with an empty `props` list.
+- **`directory_path`** -- a directory of real component source files,
+  scanned recursively for `.jsx`/`.tsx`/`.js`/`.ts` files (excluding
+  `node_modules`/`dist`/`build`/`.git` and `.test.`/`.spec.`/`.stories.`
+  files). Each exported, uppercase-named function or const component found
+  becomes a candidate, with props read in priority order from a
+  `<Name>Props` interface/type, a `.propTypes` block, or (last resort) the
+  component's own destructured parameters. This is a heuristic scan, not a
+  full parser -- a sparse or partial props list for some components is
+  expected, not a bug, especially on plain JS with no prop typing at all.
+
+### Output
+
+```json
+{
+  "status": "registered",
+  "registration": {
+    "project_id": "my-booking-app",
+    "source_kind": "directory_scan",
+    "source_path": "src/components",
+    "registered_at": "2026-09-03T18:04:11.201Z",
+    "candidate_count": 29,
+    "candidates": [
+      { "name": "ReferralBanner", "props": ["code", "bonusAmount"], "description": null, "usage_example": null, "file_path": "rewards/ReferralBanner.jsx" }
+    ]
+  }
+}
+```
+
+Registering overwrites (does not merge with) any prior registration for the
+same `project_id`. Once registered, `recommend_component` scores ONLY
+against these candidates for calls with this `project_id` -- no separate
+flag needed, it's automatic based on `project_id` alone, and step 3's live
+web search is skipped entirely (`web_search` is still available, but
+reserved for a `custom_build` verdict's Mobbin/Figma Community reference
+grounding, same as the external-library path). A `use_existing` verdict
+scored this way always carries `"source": "design_system"` on the
+resulting ledger entry, set server-side regardless of what the model wrote,
+so `read_ledger` and `export_ledger_provenance` can match on it reliably.
+
+This only writes local config to `~/.pattern/design_systems.json` (override
+with `PATTERN_DESIGN_SYSTEMS_PATH`) -- it never calls the Anthropic API.
+Registration is a point-in-time snapshot, not a live link: re-run this
+whenever the design system's own components change meaningfully.
+
+### A safety net for a missed match
+
+The model can occasionally say `custom_build`/`no_candidates_found`
+against a registered design system even when a real match is sitting
+right there in its own prompt -- a reading-comprehension miss over its own
+known-complete candidate list, not evidence the list was actually empty.
+When this happens, `recommend_component`'s response may carry a
+`design_system_recall_check` field: a deterministic, zero-cost, local
+keyword-overlap check (component name, props, description/usage_example
+vs. `component_need`/`domain`) run automatically whenever reason is
+`no_candidates_found` in this mode.
+
+```json
+{
+  "verdict": "custom_build",
+  "reason": "no_candidates_found",
+  "design_system_recall_check": {
+    "possible_missed_candidates": [
+      { "name": "ReferralBanner", "shared_keywords": ["referral", "bonus"] }
+    ],
+    "note": "These registered design-system candidates share keywords with this component_need but were not selected as a match -- the verdict may have missed a real one. This is a weak, keyword-only signal, not proof of an actual match: double-check these candidates yourself (or re-run this call) before trusting custom_build here."
+  }
+}
+```
+
+This never overrides the verdict -- a shared keyword is weak evidence, not
+proof of a real match -- it only surfaces the risk so you (or the calling
+agent) know to double-check before accepting a `custom_build` verdict at
+face value. Absent entirely when there's no overlap, or outside
+design-system mode.
+
 ## Tool: `extract_requirements`
 
 Runs only the requirement-extraction step `recommend_component` normally
@@ -981,123 +1112,6 @@ 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):
@@ -1164,6 +1178,56 @@ live -- all 12 flag `dangling`, the 13th doesn't. Also tested at 200 and
 (both complete in well under a second -- this is `fs.existsSync` calls
 and in-memory grouping, not API calls).
 
+## 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 anywhere; see
+[`post_ledger_provenance_to_github`](#tool-post_ledger_provenance_to_github)
+below for that.
+
+### 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: `backfill_ledger_snapshot_ref`
 
 Best-effort reconstruction of `snapshot_ref` for ledger entries written
@@ -1224,6 +1288,74 @@ 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.
 
+## 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.
+
 ## Feature cost attribution
 
 Every `recommend_component` call that writes to the ledger -- a fresh
@@ -1345,25 +1477,33 @@ 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.
+Both are now fully addressed, across five tools:
+[`check_ledger_liveness`](#tool-check_ledger_liveness) and
+[`sweep_ledger_liveness`](#tool-sweep_ledger_liveness) close the first gap;
+[`export_ledger_provenance`](#tool-export_ledger_provenance),
+[`backfill_ledger_snapshot_ref`](#tool-backfill_ledger_snapshot_ref), and
+[`post_ledger_provenance_to_github`](#tool-post_ledger_provenance_to_github)
+close the second. See `pattern-ledger-integrity-and-provenance-spec.md`
+for the original phased plan this was built against.
+
+**This required 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). Still narrow, still all read-only, and still nothing here ever
+writes to your repo or runs an arbitrary git/shell command:
+
+- `git rev-parse HEAD`, on every ledger write, to capture `snapshot_ref`.
+- `git log --before=<timestamp> -1 --format=%H`, only inside
+  `backfill_ledger_snapshot_ref`, to reconstruct a best-effort
+  `snapshot_ref` for an entry that predates it.
 - `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` (see below) -- what
+  [`check_ledger_liveness`](#tool-check_ledger_liveness)/[`sweep_ledger_liveness`](#tool-sweep_ledger_liveness)
+  check. `post_ledger_provenance_to_github` additionally makes a real,
+  visible network call to the GitHub API -- see that tool's own docs,
+  it's a materially different kind of exception (a third-party service,
+  not your local machine) from the four above.
 
 ### `PROJECT_ROOT`
 
@@ -1975,6 +2115,25 @@ search or code problem.
 
 The boundary-risk ensemble exists to detect and surface this uncertainty.
 
+### A missed match in your own design system isn't automatically re-checked
+
+In [design-system mode](#tool-register_design_system), the model can say
+`custom_build`/`no_candidates_found` even when a real, relevant candidate
+is sitting right in its own prompt -- a reading-comprehension miss over a
+fully-known candidate list, not a live-search gap. The boundary-risk
+ensemble above doesn't catch this: it only re-checks a `"scored"` result
+near the 40%/80% threshold, never a `"no_candidates_found"` verdict.
+
+The [keyword-overlap safety net](#a-safety-net-for-a-missed-match) flags
+this risk (`design_system_recall_check` on the response) but does not fix
+it -- it's a detection layer, not a re-check. The actual fix (re-running
+the model on a suspicious `no_candidates_found` verdict, the same way a
+close `"scored"` call already gets re-checked) is scoped but not built.
+`custom_build` ledger entries in this mode also record zero candidates
+(`candidates_evaluated: []`), same as the external-library path, so a
+genuine miss and a correct "nothing here" still look identical in
+`read_ledger` afterward unless the recall check happened to catch it.
+
 ### A staged pipeline was evaluated and not adopted
 
 To address the variance above, an alternative architecture was built and