pattern-mcp 0.2.0 → 0.4.0

package/README.md

@@ -5,8 +5,9 @@
 [![npm downloads](https://img.shields.io/npm/dm/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 helps coding agents make better UI
-component decisions.
+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.
 
 [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)
 
@@ -31,7 +32,7 @@ whether to:
 
 Pattern is designed for agents to use **while they are building**.
 
-It exposes three tools:
+It exposes six tools:
 
 - `recommend_component` — evaluates a UI component need and returns a
   structured recommendation.
@@ -41,6 +42,18 @@ It exposes three tools:
 - `record_component_decision` — records what the agent actually did so
   future recommendations in the same project can take that decision into
   account.
+- `read_ledger` — lists past `recommend_component` judgments for a
+  `project_id`, including any that were served from the ledger cache (see
+  [Per-project judgment ledger](#per-project-judgment-ledger)); pass
+  `feature_id` instead of browsing by keyword to get a full cost rollup for
+  one feature (see [Tool: `report_build_cost`](#tool-report_build_cost)).
+- `report_build_cost` — self-reports the end-to-end build cost for one
+  feature, so cost incurred after Pattern's own verdict (the actual
+  scaffold/install/build) is still attributable back to it.
+- `report_outcome_proxy` — self-reports a value signal (rework, time to
+  merge, kept-vs-replaced) for one feature, deliberately independent of
+  Pattern's own verdict -- see [Outcome
+  proxies](#outcome-proxies).
 
 ## How it works
 
@@ -70,6 +83,9 @@ A result can also be:
 - `custom_build`
 - `no_candidates_found`
 - `skip_list`
+- `ledger_cache_hit` — served from a recent, matching prior judgment
+  instead of a fresh search+score (see
+  [Per-project judgment ledger](#per-project-judgment-ledger)).
 
 `no_candidates_found` is kept separate from a low-coverage result. Not
 finding a candidate is different from finding candidates that don't cover
@@ -78,7 +94,14 @@ the requirements.
 If `project_id` is supplied, Pattern also checks for past confirmed
 decisions on that project and factors them in as a consistency signal —
 never a rule that overrides a genuinely better match found in the current
-search.
+search. Separately, `project_id` also enables the judgment ledger: a
+high-confidence prior judgment matching this exact
+component_need/domain/framework/existing_stack, recorded recently enough,
+can be served directly (`ledger_cache_hit`) instead of running a fresh
+search+score. This is the one deliberate exception to "every recommendation
+searches and scores again" — see
+[Per-project judgment ledger](#per-project-judgment-ledger) for the exact
+rules and why it's safe.
 
 Every result includes `computed_at`, because coverage is a snapshot of the
 search at that point in time, not a permanent fact. Every result also
@@ -395,6 +418,16 @@ Leave `checklist` out to keep today's default behavior: `recommend_component`
 extracts its own checklist internally, exactly as before this option
 existed.
 
+#### `feature_id`
+
+`feature_id` is optional -- a stable identifier for the feature this
+component need belongs to (e.g. a ticket id or branch name). Its only use
+is joining this call's cost with a later
+[`report_build_cost`](#tool-report_build_cost) call for the same feature.
+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).
+
 **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
@@ -600,7 +633,8 @@ Anthropic API call.
   "domain": "Airbnb-style rental marketplace",
   "action": "custom_built",
   "source": "custom",
-  "timestamp": "2026-08-25T14:32:00.000Z"
+  "timestamp": "2026-08-25T14:32:00.000Z",
+  "time_saved_minutes": 25
 }
 ```
 
@@ -609,6 +643,15 @@ Anthropic API call.
 - `action` must be `"installed"` or `"custom_built"`.
 - `source` can be `"shadcn"`, `"21st.dev"`, `"reui"`, or `"custom"`.
 - `timestamp` is optional. If omitted, Pattern uses the current time.
+- `time_saved_minutes` is optional -- the calling agent's own estimate,
+  in minutes, of how much time this decision saved by having Pattern's
+  verdict instead of researching candidates and judging fit from scratch.
+  This is entirely self-reported. Pattern has no way to measure a
+  counterfactual ("how long would this have taken without Pattern?"), so
+  unlike `_meta` (Pattern's own real cost/latency for the call that
+  produced the verdict), this number is never computed or verified --
+  it's just recorded as-given. Omit it rather than guess a number to fill
+  the field.
 
 ### Output
 
@@ -620,6 +663,322 @@ Anthropic API call.
 }
 ```
 
+## Tool: `read_ledger`
+
+Lists past `recommend_component` judgments for a `project_id` -- every
+call that reached the API and produced a verdict, not just ones explicitly
+confirmed via `record_component_decision`. Useful for auditing what
+Pattern has already judged for a project, or for understanding why a call
+came back with `served_from_ledger: true`.
+
+### Input
+
+```json
+{
+  "project_id": "my-booking-app",
+  "component_need": "cancellation",
+  "limit": 10
+}
+```
+
+- `project_id` is required.
+- `component_need` is optional -- a simple keyword filter (substring
+  match, no embeddings) against stored entries' `component_need`. Omit to
+  list everything for the project.
+- `limit` is optional, defaults to 20. Most recent entries first.
+- `feature_id` is optional. When provided, `component_need` and `limit`
+  are ignored and the response is a full cost rollup for that one feature
+  instead of a keyword listing -- see [Feature cost
+  attribution](#feature-cost-attribution).
+
+### Output
+
+```json
+{
+  "project_id": "my-booking-app",
+  "entries": [
+    {
+      "id": "a1b2c3d4-...",
+      "timestamp": "2026-08-29T19:50:47.073Z",
+      "project_id": "my-booking-app",
+      "feature_id": "3f9a21c0",
+      "component_need": "cancellation policy display with refund tiers by date",
+      "domain": "Airbnb-style rental marketplace",
+      "framework": "React + Tailwind",
+      "checklist": ["...", "..."],
+      "checklist_source": "extracted",
+      "candidates_evaluated": [
+        { "source": "ReUI (reui.io)", "name": "Timeline", "url": "https://reui.io/components/timeline", "coverage_pct": 62.5 }
+      ],
+      "verdict": "use_existing",
+      "chosen_candidate": "Timeline",
+      "confidence": "low",
+      "reason": "scored",
+      "coverage": "5/8 (62.5%)",
+      "cost_usd": 0.087,
+      "cache_hit": false,
+      "project_conventions_snapshot": "9f3a1c7e2b0d4f5a"
+    }
+  ]
+}
+```
+
+Passing `feature_id` instead returns:
+
+```json
+{
+  "project_id": "my-booking-app",
+  "feature_id": "3f9a21c0",
+  "verdict_entries": [ "...same shape as above, filtered to this feature_id..." ],
+  "build_records": [
+    { "id": "...", "timestamp": "...", "project_id": "my-booking-app", "feature_id": "3f9a21c0", "tokens_used": 9000, "cost_usd": 1.25, "outcome": "shipped" }
+  ],
+  "total_cost_usd": 1.34,
+  "outcome_proxy": { "time_to_merge_hours": 3.5, "reworked": true, "days_to_rework": 12, "status_at_30d": "kept" },
+  "outcome_proxy_history": [ "...every raw report_outcome_proxy record for this feature_id, oldest first..." ]
+}
+```
+
+`outcome_proxy` is `null` (and `outcome_proxy_history` an empty array)
+when no `report_outcome_proxy` calls have been made for this feature yet
+-- see [Outcome proxies](#outcome-proxies).
+
+Each entry holds only distilled fields -- `candidates_evaluated` never
+contains raw HTML, full prop tables, or the per-requirement evidence text
+`recommend_component` itself returns. See
+[Data minimization](#data-minimization) below.
+
+## Tool: `report_build_cost`
+
+Self-reports the end-to-end build cost for one feature. Pattern only ever
+sees the cost of judging *what* to use (`recommend_component`'s own
+`_meta.estimated_cost_usd`); everything past that -- the actual scaffold,
+install, or custom build -- happens outside Pattern entirely and Pattern
+has no way to observe it. Call this once, after the calling agent's build
+for a feature is actually complete (shipped, abandoned, or replaced), not
+on every verdict.
+
+### Input
+
+```json
+{
+  "feature_id": "3f9a21c0",
+  "project_id": "my-booking-app",
+  "tokens_used": 9000,
+  "cost_usd": 1.25,
+  "outcome": "shipped"
+}
+```
+
+- `feature_id` is required -- either a value you explicitly passed to an
+  earlier `recommend_component` call for this feature, or (if you didn't)
+  the same value `recommend_component` derives on its own:
+  `sha256(project_id + "::" + component_need, lowercased/trimmed)`
+  truncated to 8 hex characters. When in doubt, call `read_ledger` with
+  just `project_id` and copy the `feature_id` off the relevant entry
+  rather than re-deriving it by hand.
+- `project_id` is optional but recommended -- without it, this record
+  still joins to a `recommend_component` entry by `feature_id` alone, but
+  `read_ledger`'s rollup can't scope it to one project.
+- `tokens_used` is optional.
+- `cost_usd` is required -- your own real number, not Pattern's.
+- `outcome` is required: `"shipped"`, `"abandoned"`, or
+  `"replaced_with_existing"`.
+
+### Output
+
+```json
+{
+  "status": "recorded",
+  "record": {
+    "id": "c5706b47-...",
+    "timestamp": "2026-09-02T01:25:29.653Z",
+    "project_id": "my-booking-app",
+    "feature_id": "3f9a21c0",
+    "tokens_used": 9000,
+    "cost_usd": 1.25,
+    "outcome": "shipped"
+  }
+}
+```
+
+This only appends a local record to `~/.pattern/build_ledger.jsonl`
+(override with `PATTERN_BUILD_LEDGER_PATH`) -- it never re-runs any
+judgment and never calls the Anthropic API.
+
+## Tool: `report_outcome_proxy`
+
+Self-reports a value signal for one feature, deliberately independent of
+Pattern's own verdict -- the whole point is a signal that could
+*contradict* the verdict, so nothing on this path ever reads
+`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.
+
+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
+merge, `reworked` on a later re-check, `status_at_30d` at the 30-day mark.
+`read_ledger`'s `feature_id` rollup merges every report into one
+latest-value-per-field view (a later report only overwrites the specific
+fields it includes, never the others).
+
+### Input
+
+```json
+{
+  "feature_id": "3f9a21c0",
+  "project_id": "my-booking-app",
+  "reworked": true,
+  "days_to_rework": 12
+}
+```
+
+- `feature_id` is required.
+- `project_id` is optional but recommended, same reasoning as
+  `report_build_cost`.
+- `reworked`, `days_to_rework`, `time_to_merge_hours`, `status_at_30d` are
+  all individually optional, but **at least one is required** -- an empty
+  report is rejected rather than silently recording nothing.
+
+### Output
+
+```json
+{
+  "status": "recorded",
+  "record": {
+    "id": "8a2f1e0c-...",
+    "timestamp": "2026-09-16T18:04:12.881Z",
+    "project_id": "my-booking-app",
+    "feature_id": "3f9a21c0",
+    "reworked": true,
+    "days_to_rework": 12
+  }
+}
+```
+
+This only appends a local record to `~/.pattern/outcome_proxies.jsonl`
+(override with `PATTERN_OUTCOME_PROXY_PATH`) -- it never calls the
+Anthropic API.
+
+## Feature cost attribution
+
+Every `recommend_component` call that writes to the ledger -- a fresh
+judgment *or* a $0 [ledger cache hit](#the-cache-hit-exception) -- now
+carries a `feature_id`, plus its own `cost_usd` and `cache_hit`. Pair that
+with `report_build_cost`'s build-time record and `read_ledger`'s
+`feature_id` rollup, and total spend on a feature (judgment + build,
+across however many calls) is queryable end to end, not just the cost of
+one verdict call.
+
+`feature_id` defaults to a deterministic derivation --
+`sha256(project_id + "::" + component_need)` truncated to 8 hex chars --
+so repeat calls for the same feature land under the same id automatically,
+with no coordination needed between `recommend_component` and
+`report_build_cost` calls. Pass your own `feature_id` explicitly (e.g. a
+ticket id or branch name) if you'd rather key on something stable on your
+own side.
+
+## Outcome proxies
+
+Cost data alone (`feature cost attribution` above) can't answer whether a
+cheaper build was actually *worth it* -- comparing it against Pattern's
+own verdict/`coverage_pct` would be circular, since that's the very thing
+being evaluated. `report_outcome_proxy` attaches a cheap, non-circular
+value signal per `feature_id` instead:
+
+- **`reworked` / `days_to_rework`** (primary proxy) -- was any file this
+  feature's build touched modified again after the original merge, and if
+  so, how soon? Computed from real git history, not Pattern's own data.
+- **`time_to_merge_hours`** (secondary proxy) -- how long the feature
+  took from first commit to merge.
+- **`status_at_30d`** (tertiary, longer-horizon proxy) -- at a ~30-day
+  horizon, does the component Pattern recommended still exist in the
+  codebase, unchanged in kind (`"kept"`), was it swapped for a different
+  approach (`"replaced"`), or removed entirely (`"removed"`)?
+
+`read_ledger`'s `feature_id` rollup returns both `outcome_proxy` (the
+merged latest-value-per-field view) and `outcome_proxy_history` (every
+raw report, in case the timeline itself matters) alongside the cost
+figures from [Feature cost attribution](#feature-cost-attribution) above
+-- so "what did this feature cost end to end, and did it hold up?" is
+answerable from one `read_ledger` call.
+
+## Per-project judgment ledger
+
+Distinct from [per-project decision memory](#per-project-decision-memory)
+below -- that file only gains an entry when `record_component_decision` is
+explicitly called. The ledger instead gains one entry automatically for
+**every** `recommend_component` call with a `project_id` that lands on
+reason `"scored"` or `"no_candidates_found"` -- whether that's a fresh
+call that reached the API, or a $0 [ledger cache
+hit](#the-cache-hit-exception) served without one (`cache_hit: true`,
+`cost_usd: 0`), so a feature's total cost still rolls up correctly even
+once most of its later calls are free. See [Feature cost
+attribution](#feature-cost-attribution).
+
+Pattern stores it locally in:
+
+```
+~/.pattern/ledger.jsonl
+```
+
+Change the location with `PATTERN_LEDGER_PATH`. One JSON object per line
+(append-only, JSONL).
+
+### The cache-hit exception
+
+Every other part of Pattern scores fresh every time (see
+[No caching, by design](#no-caching-by-design)). The ledger is the one
+deliberate exception: a later `recommend_component` call with a matching
+`project_id` **can** be served directly from a prior entry, skipping
+search+score entirely, when **all** of the following hold:
+
+- `component_need` matches exactly (case-insensitive).
+- `domain` and `framework` match exactly.
+- `existing_stack` hashes to the same value as the stored entry's
+  (both omitted counts as a match).
+- The stored entry's `confidence` is `"high"`.
+- The stored entry's `reason` is `"scored"` or `"no_candidates_found"`.
+- The stored entry is no older than `PATTERN_LEDGER_TTL_DAYS` (default
+  **30** days, configurable).
+
+When served this way, the response has `reason: "ledger_cache_hit"`,
+`served_from_ledger: true`, `ledger_entry_id`, and
+`original_verdict_timestamp` -- so nothing is ever silently passed off as
+freshly verified. `_meta.estimated_cost_usd` and `tokens_used` are
+genuinely `0`: no API call happened. `requirements_checked` is `null` on
+this path -- the ledger never stores per-requirement evidence text (see
+[Data minimization](#data-minimization)), so a cache hit can only replay
+the verdict/confidence/coverage/chosen-candidate, not the original
+per-requirement reasoning.
+
+Any mismatch on the criteria above -- a different `domain`, a changed
+`existing_stack`, an entry that's gone stale, or one that wasn't
+high-confidence -- falls through to a normal, fresh search+score call.
+
+### Turning the cache-hit exception off
+
+Set `PATTERN_NO_LEDGER_CACHE_HIT` (any truthy value) to restore
+"every `recommend_component` call always scores fresh" without removing
+any ledger code. This disables only the cache-hit short-circuit --
+entries are still written to `ledger.jsonl` and `read_ledger` still works
+either way, so the audit trail keeps growing even with the switch on.
+Unset the variable to re-enable cache hits again at any time.
+
+### Data minimization
+
+Nothing written to the ledger ever contains raw search/fetch content.
+Every candidate is reduced to exactly four fields before it's written --
+`source`, `name`, `url`, `coverage_pct` -- enforced at the type level
+(`assertDistilledCandidateShape` in `src/index.ts`), not just by
+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.
+
 ## Per-project decision memory
 
 Pattern stores confirmed decisions locally in:
@@ -644,12 +1003,16 @@ The file is organized by project:
       "domain": "Airbnb-style rental marketplace",
       "action": "custom_built",
       "source": "custom",
-      "timestamp": "2026-08-25T14:32:00.000Z"
+      "timestamp": "2026-08-25T14:32:00.000Z",
+      "time_saved_minutes": 25
     }
   ]
 }
 ```
 
+`time_saved_minutes` is omitted from an entry entirely when the calling
+agent didn't provide one -- it's never backfilled or estimated by Pattern.
+
 Each project keeps its 50 most recent decisions. Older entries are
 removed as new ones are added.
 
@@ -668,12 +1031,13 @@ sensitive information in them. See [SECURITY.md](./SECURITY.md).
 A failure to write the decision file is returned as an error from
 `record_component_decision`.
 
-**No caching, by design.** Project memory does not cache recommendations.
-A previous decision is only additional context for a new judgment. Every
-`recommend_component` call performs a fresh search and recalculates
-coverage. This means Pattern can use past decisions to improve
-consistency without letting stale decisions replace current evidence —
-see [Known limitations](#known-limitations) for more.
+**No caching, by design.** Project memory (this file, `memory.json`) does
+not cache recommendations. A previous decision is only additional context
+for a new judgment. This is unrelated to the
+[judgment ledger](#per-project-judgment-ledger)'s bounded cache-hit
+exception, which lives in a separate file (`ledger.jsonl`) and is always
+flagged (`served_from_ledger: true`) when it happens — see
+[Known limitations](#known-limitations) for more.
 
 ## Security and privacy
 
@@ -683,28 +1047,103 @@ recommendations.
 Local project memory and the local call log are stored on the machine
 running Pattern. They are not sent anywhere by Pattern itself.
 
+The one exception is opt-in telemetry, off by default -- see
+[Telemetry](#telemetry) below for exactly what it sends and how to turn
+it on or off.
+
 Review [SECURITY.md](./SECURITY.md) before putting sensitive information
 into fields such as `component_need`, `domain`, or project IDs.
 
+## Telemetry
+
+Off by default. Nothing is sent anywhere for telemetry purposes unless
+you explicitly set:
+
+```
+PATTERN_TELEMETRY=1
+```
+
+**The one-time notice.** The first time you run this version of Pattern
+-- whether it's a brand-new install or an upgrade from a version before
+telemetry existed -- it prints a short notice to stderr explaining all of
+this and how to opt in. It prints exactly once, ever (tracked by a marker
+file at `~/.pattern/telemetry_notice_shown`), then never again, regardless
+of whether you act on it. There's no interactive y/n prompt: Pattern's
+stdin is the MCP JSON-RPC channel the client uses to talk to it, so
+blocking on stdin for a keypress would fight the protocol handshake
+instead of showing a dialog -- a stderr notice is the safe equivalent for
+a stdio MCP server.
+
+**Why it exists.** Two things about real usage can't be answered from
+this repo alone: whether people actually come back and use Pattern on a
+second or third project on their own, and how often a BYO Anthropic key
+actually hits a rate limit or runs out of credit in real sessions, not
+just the one time that happened during manual testing (see
+[Known limitations](#known-limitations)). Telemetry answers both without
+requiring anyone to fill out a survey.
+
+**What gets sent, when enabled:**
+
+- An anonymous, randomly generated install ID -- a UUID created once and
+  stored at `~/.pattern/install_id` (overridable via
+  `PATTERN_INSTALL_ID_PATH`), never derived from your machine, username,
+  or any other identifying information. This is the only thing that ties
+  two events together as "the same install."
+- A one-way SHA-256 hash of `project_id`, truncated to 16 hex characters
+  -- never the raw `project_id` string. The hash lets Pattern count how
+  many *distinct* projects one install has used, without ever seeing what
+  those projects are named.
+- On every `recommend_component` call that reaches the API or the ledger
+  cache-hit shortcut: `verdict`, `confidence`, `reason`,
+  `ensemble_triggered`, `estimated_cost_usd`, and `served_from_ledger` --
+  the same distilled shape already written to the
+  [local call log](#local-call-log), not new information.
+- On a failed Anthropic API call specifically: the HTTP status code and a
+  coarse classification (`rate_limit`, `insufficient_credit`, or `other`)
+  -- never the request or response body.
+
+**What never gets sent, telemetry on or off:** `component_need`,
+`domain`, `framework`, `existing_stack`, `requirements_checked` evidence,
+the raw `project_id`, or your Anthropic API key.
+
+**Where it goes.** Events go to Pattern's PostHog project via its public,
+write-only project key (safe to ship in source -- it can send events, it
+cannot read data back). Set `PATTERN_POSTHOG_KEY` /
+`PATTERN_POSTHOG_HOST` to point at a different project, e.g. for
+self-hosting.
+
+**Turning it off** is the default -- just don't set `PATTERN_TELEMETRY`.
+If you'd previously enabled it, unset the variable (or set it to `0`) to
+go back to fully local.
+
 ## Cost
 
 Pattern uses the Anthropic API, so `recommend_component` has a cost.
 
 A typical single pass costs about $0.06–$0.10 with Sonnet 5 at current
 pricing. Skip-listed primitives cost $0 because they're handled locally
-and never reach the API.
+and never reach the API. A [ledger cache hit](#the-cache-hit-exception)
+also costs $0, for the same reason -- no API call happens.
 
 ### The `_meta` field
 
 Every `recommend_component` and `extract_requirements` response includes
-an internal `_meta` block reporting what that call actually spent:
+an internal `_meta` block reporting what that call actually spent. This
+is not shown to the user automatically -- the calling agent has to
+surface it, the same way it's separately instructed to show
+`install_command` before running it (see
+[above](#installation-commands-are-not-trusted)). Both tool descriptions
+say so explicitly: surface `_meta.estimated_cost_usd` after the call,
+since it's real spend against the user's own API key, not internal
+bookkeeping.
 
 ```json
 {
   "total_ms": 41516,
   "breakdown_ms": { "extract": 5006, "search": 3114, "score": 33396 },
   "tokens_used": { "input": 8400, "output": 620 },
-  "estimated_cost_usd": 0.14
+  "estimated_cost_usd": 0.14,
+  "scoring_fetch": { "attempted": true, "succeeded": true, "url": "https://ui.shadcn.com/docs/components/..." }
 }
 ```
 
@@ -719,6 +1158,14 @@ an internal `_meta` block reporting what that call actually spent:
   discounts.
 - `breakdown_ms` -- how `total_ms` splits across `recommend_component`'s
   three internal phases.
+- `scoring_fetch` -- whether step 4's single candidate-verification fetch
+  (see [Fetch-grounded scoring](#fetch-grounded-scoring-and-reference-verification)
+  below) actually happened for this response. `url` is `null` when
+  `attempted` is `false` (no real candidate to verify, e.g. `reason:
+  "no_candidates_found"` or `"skip_list"`). This is a diagnostic only --
+  Pattern never uses it to auto-correct `requirements_checked` after the
+  fact, since there's no safe fallback value for an unverified met/not-met
+  call the way there is for a reference URL.
 
 **How `breakdown_ms` is measured, and its one real caveat.** The bundled
 call runs extraction, search, and scoring inside a single model turn
@@ -746,6 +1193,10 @@ not the wall-clock time you waited. The three ensemble passes run with the
 2nd and 3rd concurrent, so perceived latency is closer to ~2x one pass,
 not the ~3x `total_ms` will show. Cost and token spend are genuinely
 additive across reruns, which is what `_meta` is reporting there.
+`scoring_fetch` is the one exception -- it isn't summed (a fetch either
+happened for the specific pass whose evidence became the returned
+`requirements_checked`, or it didn't), so it reports that winning pass's
+own value, not an aggregate across all three.
 
 Three things help keep the cost down without changing the decision process.
 
@@ -770,18 +1221,33 @@ shadcn/ui, 21st.dev, and ReUI are searched in the same turn rather than
 sequentially, which reduces how much conversation context needs to be
 sent repeatedly.
 
-### Reference verification
-
-Pattern allows up to 2 `web_fetch` calls, used only to verify reference
-URLs.
+### Fetch-grounded scoring and reference verification
+
+Pattern allows up to 3 `web_fetch` calls per pass: 1 reserved for scoring,
+2 reserved for reference verification (1 for Mobbin, 1 for Figma
+Community).
+
+Before finalizing coverage, Pattern fetches the best-fitting candidate's
+own real docs/source page once and re-checks the checklist against that
+page, not just the search-result snippet it started with. This exists
+because search-result descriptions can both overstate a component's real
+capabilities and miss real ones it actually has -- both were observed in
+testing on the same case (an invented feature claim and a missed real
+one). If the fetch fails, or there's no confirmed URL to fetch, Pattern
+falls back to search-only evidence and says so in the affected items.
+
+Each result's `_meta.scoring_fetch` reports whether this fetch actually
+happened for that response (`{ attempted, succeeded, url }`) -- it's a
+diagnostic, not something Pattern uses to auto-correct individual
+requirement judgments. Unlike a reference URL (which has a safe fallback:
+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.
 
-Pattern does not use `web_fetch` during requirement scoring. It's
-reserved for verifying reference links.
-
 ### Choosing a cheaper model
 
 You can change the model with:
@@ -1047,22 +1513,32 @@ pipeline is still fully bundled; nothing about this evaluation changed.
 
 ### No caching, by design
 
-Every recommendation searches and scores again.
+Every recommendation searches and scores again -- with one bounded
+exception (see below).
 
 This means a recommendation can change as component libraries change.
 For example, a later shadcn/ui release can introduce a component that
 changes a previous `custom_build` result.
 
-Do not persist a recommendation across sessions or builds at the
-calling-agent layer.
-
-If you add caching, keep it session-scoped.
+Do not build a second, unbounded cache of recommendations at the
+calling-agent layer on top of Pattern's own. If you add caching there,
+keep it session-scoped.
 
 [Project decision memory](#per-project-decision-memory) does not change
 this. It provides context from previous decisions, but every
 `recommend_component` call still performs a fresh search and scoring
 pass.
 
+The one deliberate exception is the
+[judgment ledger's cache-hit path](#the-cache-hit-exception): a later
+call matching an exact, recent, high-confidence prior judgment can be
+served without a fresh search+score. It's bounded (exact
+component_need/domain/framework/conventions match, a staleness TTL) and
+always self-identifies via `served_from_ledger: true` and
+`reason: "ledger_cache_hit"` -- so a calling agent that wants a guaranteed
+fresh check on every call should look for that flag and treat it the same
+as any other verdict it wants to double-check.
+
 ### The skip-list is still evolving
 
 The primitive skip-list is a starting point and has not yet been