pattern-mcp 0.9.1 → 0.11.0

package/README.md

@@ -15,6 +15,11 @@ 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)
 
+**Current release: v0.10.0** — adds an opt-in enforcement boundary (a
+`PreToolUse` hook plus a paired CI check) so a new component decision can
+be required, not just logged. See [Enforcement boundary: hook + CI
+gate](#enforcement-boundary-hook--ci-gate).
+
 <details>
 <summary><strong>Contents</strong> (click to expand)</summary>
 
@@ -22,6 +27,7 @@ design reference.
 - **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)
+- [Enforcement boundary: hook + CI gate](#enforcement-boundary-hook--ci-gate) (new in v0.10.0 — require the call, don't just log it)
 - [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)
@@ -31,7 +37,7 @@ design reference.
 ## Install
 
 ```bash
-npm install pattern-mcp
+npx pattern-mcp
 ```
 
 See [Quick Start](#quick-start) below to add your Anthropic API key and connect
@@ -224,11 +230,11 @@ threshold.
 ### 1. Install
 
 ```bash
-npm install pattern-mcp
+npx pattern-mcp
 ```
 
-This installs the `pattern-mcp` command via `npx` (or your project's
-local `node_modules/.bin`), used in the client configs below.
+`npx` runs the `pattern-mcp` command on demand without a separate install
+step, used in the client configs below.
 
 <details>
 <summary>Build from source instead</summary>
@@ -1477,14 +1483,21 @@ 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.
-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
+Both are now fully addressed, across five tools -- **old decisions can be
+checked, not just logged**: [`check_ledger_liveness`](#tool-check_ledger_liveness)
+verifies that the file where a decision was implemented still exists and
+still uses the recommended component, marking it an orphaned entry if it
+doesn't ([`sweep_ledger_liveness`](#tool-sweep_ledger_liveness) is the
+batch/scheduled version of the same check); **decisions can become
+shareable records**: [`export_ledger_provenance`](#tool-export_ledger_provenance)
+turns a decision into a self-contained Markdown record, 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.
+can attach it directly to the relevant PR or issue; and **older decisions
+aren't left behind**: [`backfill_ledger_snapshot_ref`](#tool-backfill_ledger_snapshot_ref)
+adds a `snapshot_ref` to decisions created before this feature existed, so
+the liveness check above works retroactively. 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
@@ -1576,6 +1589,91 @@ the source line, most recent record wins at read time" convention as
 layered onto `ledger.jsonl`'s own entries at read time -- the ledger line
 itself is never rewritten.
 
+## Enforcement boundary: hook + CI gate
+
+**Decisions can be enforced, not just tracked.** An opt-in `PreToolUse`
+hook can block a new component from being written until a matching
+ledger entry exists; a paired GitHub Action can also fail the PR if that
+decision record isn't committed alongside the code.
+
+**The gap this closes:** SKILL.md instructs the calling agent to call
+`recommend_component` before scaffolding a new, non-trivial UI component,
+but nothing before this feature *enforced* that -- an agent could simply
+skip the call, and nothing server-side would know. This is opt-in and
+Claude-Code-specific for the hook half; a consuming repo that never wires
+either piece up gets Pattern exactly as it worked before, and any other
+MCP host (Cursor, Codex, etc.) is entirely unaffected either way.
+
+**Set it up with one command:**
+
+```bash
+npx pattern-check-gate init
+```
+
+Confirms each step independently rather than one blanket "proceed?", and
+never auto-commits -- review with `git status`/`git diff` and commit
+yourself when ready:
+
+1. Confirms a project id (pre-filled from `package.json`'s `name`, or
+   your git remote/directory name -- accept it or type your own).
+2. Writes or merges `.claude/settings.json` -- if one already exists, it
+   parses it, leaves any unrelated hooks untouched, and only appends the
+   `PreToolUse` entry if it isn't already there (safe to rerun).
+3. Writes `.github/workflows/pattern-gate.yml`, if a GitHub remote is
+   detected and the file doesn't already exist with different content
+   (never silently overwritten).
+4. Asks, as its own explicit yes/no: **mark the check required in branch
+   protection?** Needs `gh` installed and authenticated with admin rights
+   on the repo; skips with clear next steps otherwise. Deliberately only
+   offered when no branch protection exists yet on the default branch --
+   GitHub's branch-protection API replaces the *entire* configuration on
+   write, not just the required-checks list, so this refuses to guess at
+   merging into whatever you already have rather than risk silently
+   dropping an unrelated setting (e.g. required PR reviews). If
+   protection already exists, add `pattern-gate` to it by hand instead.
+
+Run non-interactively with `--yes` (accepts every safe default; branch
+protection is never auto-confirmed even then -- it's the one step that
+reaches outside your local filesystem into real, shared GitHub config).
+
+**Or set it up by hand**, two pieces, neither installed automatically:
+
+- **`.claude/settings.json`** wired to run `npx --yes
+  pattern-check-gate-hook` on `PreToolUse` (see
+  `templates/claude-settings/settings.json` for the exact shape) -- a
+  Claude Code hook that runs on `Write`/`Edit` calls. For a genuinely new
+  `.tsx`/`.jsx` file that exports a non-trivial component, it looks up a
+  ledger entry (via `~/.pattern/ledger.jsonl`, same as everywhere else in
+  Pattern) whose `file_path` matches the file being written. A match
+  writes a receipt and allows the write; no match blocks it with a reason
+  fed back to the model as retryable guidance, not a hard failure.
+  **This is the one new exception where Pattern writes into your repo**
+  (`.pattern/receipts/<feature_id>.json`) -- everything else described in
+  this README is read-only. `project_id` no longer needs to be set by
+  hand either -- it's derived the same way `init` pre-fills it (see
+  `src/project-id.ts`); set `PATTERN_PROJECT_ID` only to override that.
+- **`templates/github-workflows/pattern-gate.yml`** -- a required PR
+  check that reads the same receipt files back out of the diff. It never
+  touches `~/.pattern/` (not reachable from a CI runner) and needs no
+  `GITHUB_TOKEN` -- it trusts the committed receipt as the artifact of
+  record, the same way it would trust a committed test fixture.
+
+The join between the two depends on `file_path` being passed to
+`recommend_component`/`record_component_decision` -- if it's omitted, the
+gate has nothing to match against and fails closed (blocks) rather than
+guessing. Pass `file_path` whenever you know it.
+
+An escape hatch exists for both a whole-hook kill switch
+(`PATTERN_NO_ENFORCEMENT_HOOK`, local only -- does not affect the CI
+check) and a per-file override (a `// pattern-mcp:override reason="..."`
+comment) -- the override still writes a receipt recording
+`manual_override: true` and the reason, so it stays visible rather than
+silent. See `src/component-gate.ts`, `src/gate-receipt.ts`,
+`src/check-gate.ts` (the `pattern-check-gate` CLI, this project's first
+entry point separate from the stdio MCP server), `src/check-gate-hook.ts`,
+and `src/init-enforcement.ts` for the implementation, and BACKLOG.md's
+"Enforcement boundary" entries for the fuller design writeup.
+
 ## Per-project decision memory
 
 Pattern stores confirmed decisions locally in:

package/dist/check-gate-hook.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// pattern-check-gate-hook -- the Claude-Code-specific PreToolUse adapter.
+// Wired up via .claude/settings.json (see templates/claude-settings/settings.json,
+// or generated automatically by `pattern-check-gate init`). Not installed
+// automatically by pattern-mcp itself -- opt-in, per BACKLOG.md's
+// "Enforcement boundary: hook + CI gate" entry.
+//
+// A real bin entry (not a template file to hand-copy) so it resolves the
+// same way whether pattern-mcp is a real devDependency in the consuming
+// repo's node_modules or only ever fetched ad hoc via npx -- both cases
+// invoke it as `npx --yes pattern-check-gate-hook`, npx's own caching
+// handles the rest. This also makes it testable the same way as
+// check-gate.ts itself (spawned as a real subprocess in
+// scripts/verify-check-gate.mjs), rather than living outside the build.
+//
+// Reads the PreToolUse stdin JSON, shells out to `pattern-check-gate
+// write`, and translates the result into the hook's blocking contract: a
+// JSON object on stdout with permissionDecision "deny" blocks the tool
+// call and feeds the reason back to Claude as retryable guidance (not a
+// hard turn failure); exiting 0 with no output allows it.
+//
+// --project-id is intentionally omitted unless PATTERN_PROJECT_ID is set
+// -- pattern-check-gate derives one itself (package.json name, then git
+// remote, then directory name) when it's not passed. See project-id.ts.
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+async function main() {
+    if (process.env.PATTERN_NO_ENFORCEMENT_HOOK) {
+        process.exit(0);
+    }
+    const input = JSON.parse(readFileSync(0, "utf8"));
+    const toolName = input.tool_name;
+    if (toolName !== "Write" && toolName !== "Edit") {
+        process.exit(0);
+    }
+    const filePath = input.tool_input?.file_path;
+    if (!filePath)
+        process.exit(0);
+    // isNewFile is determined here, at hook time, before the write happens
+    // -- the one piece of Claude-Code-specific state pattern-check-gate
+    // itself doesn't have access to. Edit calls always target an existing
+    // file, so isNewFile is always false for them -- the initial Write
+    // that creates the file is the highest-signal moment.
+    const isNewFile = !existsSync(filePath);
+    const content = toolName === "Write" ? (input.tool_input?.content ?? "") : "";
+    const root = input.cwd ?? process.cwd();
+    const args = ["write", "--file", filePath, "--project-root", root];
+    if (process.env.PATTERN_PROJECT_ID) {
+        args.push("--project-id", process.env.PATTERN_PROJECT_ID);
+    }
+    if (isNewFile)
+        args.push("--is-new");
+    const result = spawnSync("npx", ["--yes", "pattern-check-gate", ...args], {
+        input: content,
+        encoding: "utf8",
+        timeout: 30000,
+    });
+    let parsed;
+    try {
+        parsed = JSON.parse((result.stdout || "").trim());
+    }
+    catch {
+        // If pattern-check-gate itself crashed or produced no parseable
+        // output, fail open (allow) rather than blocking on a plumbing bug --
+        // stderr still carries the detail for debugging.
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        process.exit(0);
+    }
+    if (parsed.ok === false) {
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "deny",
+                permissionDecisionReason: parsed.reason ?? "pattern-check-gate blocked this file.",
+            },
+        }));
+    }
+    process.exit(0);
+}
+main();

package/dist/check-gate.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// pattern-check-gate -- the enforcement-boundary CLI (see
+// BACKLOG.md's "Enforcement boundary: hook + CI gate" entry).
+//
+// Three modes. write/verify share one classifier (component-gate.ts) so
+// the local hook and the CI check can never silently drift on what
+// counts as "gated":
+//
+//   write  -- run locally (by check-gate-hook.ts) where
+//             ~/.pattern/ledger.jsonl is reachable. Looks up a ledger
+//             entry whose file_path matches the file being written; on a
+//             match (or a manual override), writes a receipt into the
+//             CONSUMING repo at .pattern/receipts/<feature_id>.json and
+//             exits 0. No match, no override -> exits 1 and blocks.
+//             --project-id is optional -- see project-id.ts (Option A).
+//
+//   verify -- run in CI, where ~/.pattern/ is never reachable. Trusts the
+//             committed receipt as the artifact of record instead of
+//             re-deriving anything from the ledger -- fails if a gated
+//             file in the diff has no matching receipt.
+//
+//   init   -- Option C: a guided setup that writes/merges
+//             .claude/settings.json and the workflow file, and can
+//             optionally configure branch protection via `gh`. See
+//             init-enforcement.ts; this file only dispatches to it.
+//
+// No CLI-parsing or git-wrapper dependency, matching this project's
+// existing minimal-dependency posture (index.ts shells out to fixed git
+// subcommands rather than a library) -- argv is parsed by hand below.
+//
+// This is the project's first standalone CLI entry point separate from
+// the stdio MCP server (see package.json's new "pattern-check-gate" bin
+// entry) -- entirely opt-in. A consuming repo that never installs the
+// hook template or the workflow template never invokes this file, and
+// Pattern's core MCP tools are unaffected either way.
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve as resolvePath } from "node:path";
+import { isGatedComponentFile, parseManualOverride } from "./component-gate.js";
+import { deriveOverrideFeatureId, readAllGateReceipts, writeGateReceipt } from "./gate-receipt.js";
+import { deriveProjectId } from "./project-id.js";
+import { runInit } from "./init-enforcement.js";
+function normalize(p) {
+    return p.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+// Converts a possibly-absolute file argument into a path relative to
+// root, without ever reading/writing outside root.
+function toRepoRelative(root, fileArg) {
+    const abs = isAbsolute(fileArg) ? fileArg : resolvePath(root, fileArg);
+    const rel = relative(root, abs);
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return null;
+    return normalize(rel);
+}
+function parseArgs(argv) {
+    const mode = argv[0];
+    const flags = {};
+    const files = [];
+    for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--files") {
+            // --files (verify mode) consumes every following non-flag token
+            i++;
+            while (i < argv.length && !argv[i].startsWith("--")) {
+                files.push(argv[i]);
+                i++;
+            }
+            i--;
+        }
+        else if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+    }
+    return { mode, flags, files };
+}
+function readStdin() {
+    return new Promise((resolveP, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolveP(data));
+        process.stdin.on("error", reject);
+    });
+}
+function emit(result, ok) {
+    process.stdout.write(JSON.stringify(result) + "\n");
+    process.exit(ok ? 0 : 1);
+}
+async function runWrite(root, flags) {
+    const fileArg = flags.file;
+    if (typeof fileArg !== "string") {
+        emit({ ok: false, reason: "write mode requires --file <path>" }, false);
+    }
+    // Option A: --project-id is now optional -- derive it (package.json
+    // name, then git remote, then the directory name) rather than require
+    // every caller to know and pass it. An explicit --project-id always
+    // wins over the derivation.
+    const projectId = typeof flags["project-id"] === "string" ? flags["project-id"] : deriveProjectId(root);
+    const relPath = toRepoRelative(root, fileArg);
+    if (relPath === null) {
+        emit({ ok: false, reason: `--file resolves outside project root: ${fileArg}` }, false);
+    }
+    const content = await readStdin();
+    const isNew = flags["is-new"] === true;
+    if (!isGatedComponentFile(relPath, content, isNew)) {
+        emit({ ok: true, gated: false }, true);
+    }
+    const override = parseManualOverride(content);
+    const checkedAt = new Date().toISOString();
+    // Dynamic import, after nothing has set PATTERN_NO_AUTOSTART yet in
+    // this process -- set it now, before index.js's module body runs, same
+    // convention scripts/*.mjs already use to import from this file
+    // without starting the stdio MCP server as a side effect.
+    process.env.PATTERN_NO_AUTOSTART = "1";
+    const { readLedgerEntries, computeSnapshotRef } = await import("./index.js");
+    const snapshotRef = computeSnapshotRef(root);
+    if (override.overridden) {
+        const receipt = {
+            schema_version: 1,
+            feature_id: deriveOverrideFeatureId(projectId, relPath),
+            file_path: relPath,
+            ledger_entry_id: null,
+            verdict: null,
+            chosen_candidate: null,
+            snapshot_ref: snapshotRef,
+            checked_at: checkedAt,
+            manual_override: true,
+            override_reason: override.reason,
+        };
+        writeGateReceipt(root, receipt);
+        emit({ ok: true, gated: true, manual_override: true, feature_id: receipt.feature_id }, true);
+    }
+    const entries = readLedgerEntries(projectId);
+    const match = entries.find((e) => e.file_path && normalize(e.file_path) === relPath);
+    if (!match) {
+        emit({
+            ok: false,
+            gated: true,
+            reason: `No recommend_component/record_component_decision entry found with file_path="${relPath}" ` +
+                `for project_id="${projectId}". Call recommend_component with file_path set to this exact ` +
+                `path before creating it, or add \`// pattern-mcp:override reason="..."\` to the file.`,
+        }, false);
+    }
+    const receipt = {
+        schema_version: 1,
+        feature_id: match.feature_id,
+        file_path: relPath,
+        ledger_entry_id: match.id,
+        verdict: match.verdict,
+        chosen_candidate: match.chosen_candidate,
+        snapshot_ref: snapshotRef,
+        checked_at: checkedAt,
+        manual_override: false,
+        override_reason: null,
+    };
+    writeGateReceipt(root, receipt);
+    emit({ ok: true, gated: true, feature_id: receipt.feature_id }, true);
+}
+async function runVerify(root, files) {
+    const receipts = readAllGateReceipts(root);
+    const ungated = [];
+    let checked = 0;
+    for (const fileArg of files) {
+        const relPath = toRepoRelative(root, fileArg);
+        if (relPath === null)
+            continue;
+        const abs = resolvePath(root, relPath);
+        if (!existsSync(abs))
+            continue;
+        const content = readFileSync(abs, "utf8");
+        // verify mode's caller (the workflow) is expected to pass only files
+        // already filtered to "added in this diff" -- see
+        // templates/github-workflows/pattern-gate.yml.
+        if (!isGatedComponentFile(relPath, content, true))
+            continue;
+        checked++;
+        const hasReceipt = receipts.some((r) => normalize(r.file_path) === relPath);
+        if (!hasReceipt)
+            ungated.push(relPath);
+    }
+    if (ungated.length > 0) {
+        emit({
+            ok: false,
+            ungated_files: ungated,
+            reason: "One or more new UI components have no matching .pattern/receipts/*.json entry.",
+        }, false);
+    }
+    emit({ ok: true, checked }, true);
+}
+async function main() {
+    const { mode, flags, files } = parseArgs(process.argv.slice(2));
+    const root = typeof flags["project-root"] === "string" ? flags["project-root"] : process.cwd();
+    if (mode === "write") {
+        await runWrite(root, flags);
+    }
+    else if (mode === "verify") {
+        await runVerify(root, files);
+    }
+    else if (mode === "init") {
+        await runInit(root, { yes: flags.yes === true });
+    }
+    else {
+        process.stderr.write("Usage: pattern-check-gate write --file <path> [--is-new] [--project-id <id>] [--project-root <root>] (content on stdin)\n");
+        process.stderr.write("       pattern-check-gate verify --files <path...> [--project-root <root>]\n");
+        process.stderr.write("       pattern-check-gate init [--project-root <root>] [--yes]\n");
+        process.exit(2);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`pattern-check-gate crashed: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(2);
+});

package/dist/component-gate.js

@@ -0,0 +1,56 @@
+// Shared classifier for the enforcement-boundary feature (hook + CI gate).
+// Used identically by check-gate.ts's write mode (the local PreToolUse
+// hook) and verify mode (the CI check) -- lives in its own module,
+// deliberately with zero dependency on index.ts, so the two call sites can
+// never silently drift on what counts as "a non-trivial new UI component."
+// This is host-agnostic and opt-in: nothing here runs unless a consuming
+// repo explicitly wires up the hook template or the workflow template --
+// Pattern's core MCP tools (recommend_component, record_component_decision,
+// etc.) are unaffected either way, so Codex/Cursor/any other MCP host keeps
+// working exactly as before.
+const GATED_EXTENSIONS = new Set([".tsx", ".jsx"]);
+// Deliberately NOT a "non-trivial" threshold -- an earlier version used
+// 15 here specifically to auto-exempt "trivial" files, and a real,
+// 14-non-blank-line component (a labeled progress-bar widget) slipped
+// through ungated in end-to-end testing on 2026-09-11 as a direct result.
+// Any fixed line-count threshold used as an exemption has this problem by
+// construction: there's always a real component sitting just under
+// whatever number you pick, and tuning the number only moves the
+// boundary to a different real component, it doesn't close the class of
+// bug. This floor exists ONLY to exclude degenerate non-components (a
+// bare re-export line, an empty file) -- genuine trivial-but-real
+// components are meant to go through the manual override instead
+// (parseManualOverride below), which requires a reason and still leaves
+// a visible, logged receipt, rather than being silently auto-exempted.
+const MIN_NON_BLANK_LINES = 3;
+const COMPONENT_EXPORT_PATTERN = /^export\s+(default\s+)?(function|class)\s+[A-Z]|^export\s+(default\s+)?const\s+[A-Z]\w*\s*[:=]/m;
+// isNewFile is passed in, not derived here -- the local hook knows it via
+// existsSync before the write happens; CI verify mode knows it via the
+// workflow's own `git diff --diff-filter=A` filtering. Keeping that
+// detection out of this module keeps it a pure, easily-tested function.
+export function isGatedComponentFile(filePath, fileContent, isNewFile) {
+    if (!isNewFile)
+        return false;
+    const dot = filePath.lastIndexOf(".");
+    if (dot === -1)
+        return false;
+    if (!GATED_EXTENSIONS.has(filePath.slice(dot)))
+        return false;
+    if (!COMPONENT_EXPORT_PATTERN.test(fileContent))
+        return false;
+    const nonBlankLines = fileContent.split("\n").filter((l) => l.trim().length > 0).length;
+    return nonBlankLines >= MIN_NON_BLANK_LINES;
+}
+// Per-file escape hatch (Q3 from the enforcement-boundary design): a
+// magic comment with a required reason. The hook and CI both honor this
+// identically because both call this same function -- but it never
+// silently bypasses: check-gate.ts still writes a receipt recording
+// manual_override: true and the reason, so the exception stays visible in
+// the same committed artifact as a normal pass.
+const OVERRIDE_PATTERN = /\/\/\s*pattern-mcp:override\s+reason="([^"]+)"/;
+export function parseManualOverride(fileContent) {
+    const match = fileContent.match(OVERRIDE_PATTERN);
+    if (!match || !match[1].trim())
+        return { overridden: false, reason: null };
+    return { overridden: true, reason: match[1].trim() };
+}

package/dist/gate-receipt.js

@@ -0,0 +1,94 @@
+// Receipt schema + read/write for the enforcement-boundary feature.
+// Deliberately committed into the CONSUMING repo (e.g. `.pattern/receipts/`
+// at that repo's root) rather than `~/.pattern/` -- this is the one
+// artifact a CI runner can see without any access to the local, homedir-
+// scoped ledger (see SECURITY.md's "not sent anywhere by Pattern itself").
+// One JSON file per feature, git-diffable, not an append-only jsonl --
+// receipts are meant to be read directly out of a small PR diff, not
+// grown forever like the homedir ledger overlays.
+//
+// No dependency on index.ts by design: importing index.ts triggers its
+// module-level MCP-server autostart unless PATTERN_NO_AUTOSTART is set
+// before the import resolves, which a static import from this module
+// could not guarantee. check-gate.ts handles that ordering itself via a
+// dynamic import for the one piece of real reuse it needs
+// (readLedgerEntries/computeSnapshotRef) -- this module stays
+// self-contained.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+const RECEIPTS_DIR = ".pattern/receipts";
+const ALLOWED_GATE_RECEIPT_KEYS = new Set([
+    "schema_version",
+    "feature_id",
+    "file_path",
+    "ledger_entry_id",
+    "verdict",
+    "chosen_candidate",
+    "snapshot_ref",
+    "checked_at",
+    "manual_override",
+    "override_reason",
+]);
+// Same throw-on-unknown-key discipline as index.ts's
+// assertDistilledCandidateShape -- a receipt reaching this function with
+// an extra key is a bug, not something to silently strip, since this
+// shape is the one thing CI trusts without re-deriving it.
+export function assertGateReceiptShape(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("GateReceipt must be a plain object");
+    }
+    const record = value;
+    const extra = Object.keys(record).filter((k) => !ALLOWED_GATE_RECEIPT_KEYS.has(k));
+    if (extra.length > 0) {
+        throw new Error(`GateReceipt has disallowed key(s): ${extra.join(", ")}`);
+    }
+    if (record.schema_version !== 1) {
+        throw new Error("GateReceipt.schema_version must be 1");
+    }
+}
+// feature_id can be caller-supplied (recommend_component's optional
+// feature_id arg) -- never trust it as a bare filename. Sanitizing to a
+// safe character set makes path traversal structurally impossible here
+// without needing index.ts's resolveWithinRoot (see file header).
+function sanitizeFeatureIdForFilename(featureId) {
+    return featureId.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+// Only used on the manual-override path, which has no ledger entry to
+// derive a feature_id from. Deliberately a separate, local derivation
+// rather than index.ts's deriveFeatureId (not exported, and this only
+// ever needs to be stable for one project_id+file_path pair -- it's never
+// joined against real ledger data).
+export function deriveOverrideFeatureId(projectId, filePath) {
+    return createHash("sha256").update(`override::${projectId}::${filePath}`).digest("hex").slice(0, 8);
+}
+export function writeGateReceipt(root, receipt) {
+    assertGateReceiptShape(receipt);
+    const abs = join(root, RECEIPTS_DIR, `${sanitizeFeatureIdForFilename(receipt.feature_id)}.json`);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, JSON.stringify(receipt, null, 2) + "\n", "utf8");
+}
+// verify mode's only read path: it doesn't know a file's feature_id ahead
+// of time (that lives in the local ledger, invisible to CI), so it scans
+// every committed receipt and matches on file_path instead. A malformed
+// receipt is treated as absent, not fatal -- the caller reports the gated
+// file as unreceipted, same as if no file existed at all.
+export function readAllGateReceipts(root) {
+    const dirAbs = join(root, RECEIPTS_DIR);
+    if (!existsSync(dirAbs))
+        return [];
+    const receipts = [];
+    for (const name of readdirSync(dirAbs)) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(join(dirAbs, name), "utf8"));
+            assertGateReceiptShape(parsed);
+            receipts.push(parsed);
+        }
+        catch {
+            // skip malformed/unreadable receipt
+        }
+    }
+    return receipts;
+}

package/dist/index.js

@@ -189,6 +189,12 @@ const LEDGER_TTL_DAYS = Number(process.env.PATTERN_LEDGER_TTL_DAYS ?? 30);
 // failure-prone surface than "does this one file exist right now" or
 // "what commit is HEAD."
 //
+// resolveWithinRoot/computeSnapshotRef/readLedgerEntries are exported so
+// check-gate.ts (the enforcement-boundary CLI, see that file) can reuse
+// this exact scoping rather than growing a second, parallel fs/git-access
+// surface -- it imports these dynamically, after setting
+// PATTERN_NO_AUTOSTART, the same convention scripts/*.mjs already use.
+//
 // Defaults to process.cwd() -- for a locally-run stdio MCP server, that's
 // normally the consuming repo's root, since MCP hosts typically launch
 // the server with the project directory as its working directory. When
@@ -202,7 +208,7 @@ const PROJECT_ROOT = process.env.PATTERN_PROJECT_ROOT ?? process.cwd();
 // to "unknown" rather than silently stat-ing something outside the
 // project. Returns null (never throws) on anything that doesn't resolve
 // cleanly inside root.
-function resolveWithinRoot(root, relPath) {
+export function resolveWithinRoot(root, relPath) {
     if (!relPath || isAbsolute(relPath))
         return null;
     const resolved = resolve(root, relPath);
@@ -217,7 +223,7 @@ function resolveWithinRoot(root, relPath) {
 // rather than failing the judgment call that triggered this write (see
 // buildLedgerEntry). Read-only: `git rev-parse HEAD` never touches repo
 // state.
-function computeSnapshotRef(root) {
+export function computeSnapshotRef(root) {
     try {
         const sha = execFileSync("git", ["rev-parse", "HEAD"], {
             cwd: root,
@@ -2206,7 +2212,7 @@ function backfillLedgerSnapshotRefs(input) {
 // 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)
 // is skipped rather than failing the whole read.
-function readLedgerEntries(projectId) {
+export function readLedgerEntries(projectId) {
     let raw;
     try {
         raw = readFileSync(LEDGER_PATH, "utf8");

package/dist/init-enforcement.js

@@ -0,0 +1,316 @@
+// Option C from BACKLOG.md's "Enforcement boundary setup" entry: a
+// guided `pattern-check-gate init` that does the mechanical parts of
+// setting up the hook + CI gate (see check-gate-hook.ts,
+// templates/github-workflows/pattern-gate.yml) instead of requiring a
+// hand copy-edit-commit of each piece separately.
+//
+// Every step confirms independently and defaults to the safe choice --
+// this never auto-commits, and the branch-protection step in particular
+// never runs without an explicit, un-implied "yes" (see
+// maybeSetupBranchProtection), matching the same "always confirm, never
+// silently run" treatment Pattern already gives install_command and
+// post_ledger_provenance_to_github.
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+import { deriveProjectId } from "./project-id.js";
+const HOOK_MARKER = "pattern-check-gate-hook";
+// A queue-based prompt helper, not readline/promises' question() --
+// question() only starts listening for a line *after* it's called, but
+// with piped/non-TTY stdin (as in an automated test, or `init | cat`)
+// every line arrives in one synchronous burst, ahead of any await
+// cycle. Confirmed directly: two sequential `rl.question()` calls on a
+// piped `printf 'a\nb\n'` answer only the first and hang forever on the
+// second -- Node even logs "Detected unsettled top-level await" in that
+// repro. The fix is a small always-listening queue: a persistent 'line'
+// listener buffers answers that arrive before they're asked for, so
+// `askLine` either drains an already-buffered answer immediately or
+// waits for the next 'line' event, whichever comes first -- correct for
+// both a real interactive TTY (waiter path) and piped/scripted input
+// (queue path).
+let rl = null;
+const lineQueue = [];
+const waiters = [];
+function ensureRl() {
+    if (!rl) {
+        rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.on("line", (line) => {
+            const waiter = waiters.shift();
+            if (waiter)
+                waiter(line);
+            else
+                lineQueue.push(line);
+        });
+    }
+    return rl;
+}
+function askLine(promptStr) {
+    ensureRl();
+    process.stdout.write(promptStr);
+    const queued = lineQueue.shift();
+    if (queued !== undefined)
+        return Promise.resolve(queued);
+    return new Promise((resolve) => waiters.push(resolve));
+}
+function closeRl() {
+    rl?.close();
+    rl = null;
+}
+async function confirm(question, options, defaultYes) {
+    if (options.yes)
+        return defaultYes;
+    const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+    const answer = (await askLine(`${question} ${suffix} `)).trim().toLowerCase();
+    if (!answer)
+        return defaultYes;
+    return answer === "y" || answer === "yes";
+}
+async function promptText(question, defaultValue, options) {
+    if (options.yes)
+        return defaultValue;
+    const answer = (await askLine(`${question} [${defaultValue}]: `)).trim();
+    return answer || defaultValue;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+async function setupClaudeSettings(root, projectIdOverride, options) {
+    const settingsPath = join(root, ".claude", "settings.json");
+    let settings = {};
+    let existed = false;
+    if (existsSync(settingsPath)) {
+        existed = true;
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+        }
+        catch {
+            console.log("  .claude/settings.json exists but isn't valid JSON -- skipping, fix it manually first.");
+            return;
+        }
+    }
+    const preToolUse = settings.hooks?.PreToolUse ?? [];
+    const alreadyInstalled = preToolUse.some((entry) => (entry.hooks ?? []).some((h) => typeof h.command === "string" && h.command.includes(HOOK_MARKER)));
+    if (alreadyInstalled) {
+        console.log("  .claude/settings.json: hook already configured, skipping.");
+        return;
+    }
+    const command = projectIdOverride
+        ? `env PATTERN_PROJECT_ID=${shellQuote(projectIdOverride)} npx --yes pattern-check-gate-hook`
+        : "npx --yes pattern-check-gate-hook";
+    const newEntry = {
+        matcher: "Edit|Write",
+        hooks: [{ type: "command", command, timeout: 60 }],
+    };
+    console.log(`\n  ${existed ? "Merging into" : "Creating"} .claude/settings.json:`);
+    console.log(JSON.stringify(newEntry, null, 2)
+        .split("\n")
+        .map((l) => `    ${l}`)
+        .join("\n"));
+    const proceed = await confirm("  Write this?", options, true);
+    if (!proceed) {
+        console.log("  Skipped.");
+        return;
+    }
+    const merged = {
+        ...settings,
+        hooks: {
+            ...settings.hooks,
+            PreToolUse: [...preToolUse, newEntry],
+        },
+    };
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    console.log("  Written.");
+}
+function isGitHubRepo(root) {
+    try {
+        const url = execFileSync("git", ["remote", "get-url", "origin"], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+        }).trim();
+        const match = url.match(/github\.com[:/]([^/]+)\/([^/]+?)(\.git)?$/);
+        if (match)
+            return { owner: match[1], repo: match[2] };
+    }
+    catch {
+        // no remote, or not git
+    }
+    return null;
+}
+async function setupWorkflowFile(root, options) {
+    const gh = isGitHubRepo(root);
+    if (!gh) {
+        console.log("\n  No GitHub remote detected -- skipping the GitHub Action workflow file.");
+        return false;
+    }
+    const workflowPath = join(root, ".github", "workflows", "pattern-gate.yml");
+    const templatePath = fileURLToPath(new URL("../templates/github-workflows/pattern-gate.yml", import.meta.url));
+    const templateContent = readFileSync(templatePath, "utf8");
+    if (existsSync(workflowPath)) {
+        const existing = readFileSync(workflowPath, "utf8");
+        if (existing === templateContent) {
+            console.log("\n  .github/workflows/pattern-gate.yml: already up to date, skipping.");
+            return true;
+        }
+        console.log("\n  .github/workflows/pattern-gate.yml already exists with different content.");
+        const overwrite = await confirm("  Overwrite it?", options, false);
+        if (!overwrite) {
+            console.log("  Skipped -- left your existing file untouched.");
+            return false;
+        }
+    }
+    else {
+        console.log("\n  Creating .github/workflows/pattern-gate.yml.");
+        const proceed = await confirm("  Write this?", options, true);
+        if (!proceed) {
+            console.log("  Skipped.");
+            return false;
+        }
+    }
+    mkdirSync(dirname(workflowPath), { recursive: true });
+    writeFileSync(workflowPath, templateContent, "utf8");
+    console.log("  Written.");
+    return true;
+}
+function ghCliAvailable() {
+    try {
+        execFileSync("gh", ["--version"], { stdio: "ignore", timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ghAuthenticated() {
+    try {
+        execFileSync("gh", ["auth", "status"], { stdio: "ignore", timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getDefaultBranch(gh) {
+    try {
+        const out = execFileSync("gh", ["api", `repos/${gh.owner}/${gh.repo}`, "--jq", ".default_branch"], {
+            encoding: "utf8",
+            timeout: 10000,
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+function stderrOf(err) {
+    if (err && typeof err === "object" && "stderr" in err) {
+        const stderr = err.stderr;
+        if (stderr)
+            return String(stderr);
+    }
+    return "";
+}
+function getExistingProtection(gh, branch) {
+    try {
+        execFileSync("gh", ["api", `repos/${gh.owner}/${gh.repo}/branches/${branch}/protection`], {
+            encoding: "utf8",
+            timeout: 10000,
+        });
+        return "exists";
+    }
+    catch (err) {
+        return stderrOf(err).includes("404") ? "none" : "unknown";
+    }
+}
+// Only ever called when getExistingProtection returned "none". The
+// Update Branch Protection endpoint REPLACES the entire protection
+// object, and its GET/PUT schemas differ for several fields
+// (enforce_admins is {enabled} on GET but a bare boolean on PUT, for
+// example) -- verified against GitHub's own REST API docs before writing
+// this. Deliberately does not attempt to merge into pre-existing
+// protection; that case is handled by the caller bailing out to manual
+// instructions instead of risking a wrong reconstruction that silently
+// drops an unrelated setting (e.g. required PR reviews).
+function createMinimalProtection(gh, branch) {
+    const body = JSON.stringify({
+        required_status_checks: { strict: false, checks: [{ context: "pattern-gate", app_id: -1 }] },
+        enforce_admins: false,
+        required_pull_request_reviews: null,
+        restrictions: null,
+    });
+    try {
+        execFileSync("gh", ["api", "-X", "PUT", `repos/${gh.owner}/${gh.repo}/branches/${branch}/protection`, "--input", "-"], {
+            input: body,
+            encoding: "utf8",
+            timeout: 10000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function maybeSetupBranchProtection(root, options) {
+    const gh = isGitHubRepo(root);
+    if (!gh)
+        return;
+    console.log("");
+    // Never implied by --yes, and never defaults to yes -- see BACKLOG's
+    // "strictest confirmation of the four steps" note. This is the one
+    // step that reaches outside the local filesystem into real, shared
+    // GitHub config.
+    const wantsIt = await confirm("  Mark the pattern-gate check as required in branch protection?", options, false);
+    if (!wantsIt) {
+        console.log(`  Skipped. To do this later, add "pattern-gate" as a required status check in\n` +
+            `  https://github.com/${gh.owner}/${gh.repo}/settings/branches`);
+        return;
+    }
+    if (!ghCliAvailable()) {
+        console.log("  `gh` CLI not found -- install it (https://cli.github.com) and rerun, or configure manually.");
+        return;
+    }
+    if (!ghAuthenticated()) {
+        console.log("  `gh` CLI isn't authenticated -- run `gh auth login` and rerun, or configure manually.");
+        return;
+    }
+    const branch = getDefaultBranch(gh);
+    if (!branch) {
+        console.log("  Couldn't determine the default branch -- configure manually.");
+        return;
+    }
+    const existing = getExistingProtection(gh, branch);
+    if (existing !== "none") {
+        console.log(existing === "exists"
+            ? `  Branch protection already exists on "${branch}". To avoid overwriting your other protection\n` +
+                `  settings (this endpoint replaces the whole configuration, not just required checks), add\n` +
+                `  "pattern-gate" to your required status checks manually instead of through this command.`
+            : `  Couldn't determine "${branch}"'s current protection state -- configure manually rather than\n` +
+                `  risk overwriting settings this command can't see.`);
+        return;
+    }
+    const ok = createMinimalProtection(gh, branch);
+    console.log(ok
+        ? `  Required "pattern-gate" check added to "${branch}" branch protection.`
+        : "  Failed to update branch protection -- configure manually.");
+}
+export async function runInit(root, options) {
+    console.log("Setting up Pattern's enforcement boundary (hook + CI gate)...\n");
+    const derivedId = deriveProjectId(root);
+    const projectId = await promptText("Project id", derivedId, options);
+    const projectIdOverride = projectId !== derivedId ? projectId : null;
+    try {
+        await setupClaudeSettings(root, projectIdOverride, options);
+        await setupWorkflowFile(root, options);
+        await maybeSetupBranchProtection(root, options);
+    }
+    finally {
+        // Always close, even on error -- an open readline interface keeps
+        // the process alive waiting on stdin otherwise.
+        closeRl();
+    }
+    console.log("\nDone. Review the changes with `git status` / `git diff`, then commit when ready.");
+}

package/dist/project-id.js

@@ -0,0 +1,36 @@
+// Option A from BACKLOG.md's "Enforcement boundary setup" entry:
+// auto-derives a project id instead of requiring PATTERN_PROJECT_ID to be
+// hand-set. Shared by check-gate.ts's write mode (runtime fallback when
+// --project-id is omitted) and init-enforcement.ts (to pre-fill its
+// prompt) -- one derivation, not two, so the hook's actual behavior and
+// init's preview can never disagree.
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+export function deriveProjectId(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        if (typeof pkg.name === "string" && pkg.name.trim())
+            return pkg.name.trim();
+    }
+    catch {
+        // no package.json, or unparseable -- fall through to the git remote
+    }
+    try {
+        const url = execFileSync("git", ["remote", "get-url", "origin"], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+        }).trim();
+        // Matches the repo name out of either an https or ssh remote URL,
+        // with or without a trailing .git.
+        const match = url.match(/([^/:]+?)(\.git)?$/);
+        if (match && match[1])
+            return match[1];
+    }
+    catch {
+        // no git remote, or git not available -- fall through to the dir name
+    }
+    return basename(root);
+}

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "pattern-mcp",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "MCP server that turns your design guidance into a checkable process -- evaluates UI components from external libraries (shadcn/ui, 21st.dev, ReUI) or your own registered design system against a requirements checklist, then tells the agent whether to reuse an existing component or build one from a concrete design reference.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "pattern-mcp": "dist/index.js"
+    "pattern-mcp": "dist/index.js",
+    "pattern-check-gate": "dist/check-gate.js",
+    "pattern-check-gate-hook": "dist/check-gate-hook.js"
   },
   "author": "Don Richard",
   "license": "MIT",
@@ -28,7 +30,8 @@
   ],
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "templates"
   ],
   "scripts": {
     "build": "tsc",

package/templates/claude-settings/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx --yes pattern-check-gate-hook",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/github-workflows/pattern-gate.yml

@@ -0,0 +1,42 @@
+name: Pattern gate
+
+# Required-check template for the enforcement boundary (see BACKLOG.md's
+# "Enforcement boundary: hook + CI gate" entry). Copy this into your own
+# repo's .github/workflows/ and mark the "pattern-gate" job required in
+# branch protection. Opt-in -- pattern-mcp never installs this for you.
+#
+# Deliberately does NOT need a GITHUB_TOKEN or any secret: it only reads
+# the receipt files already committed in this PR's diff
+# (.pattern/receipts/*.json), which were written locally by the
+# PreToolUse hook (see ../hooks/check-gate-hook.mjs) when the gate
+# passed. It never touches ~/.pattern/ledger.jsonl, which isn't reachable
+# from a CI runner at all -- see gate-receipt.ts for why the receipt file
+# is the artifact of record here, not a posted PR comment.
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  pattern-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+      - name: Compute added files
+        id: diff
+        run: |
+          ADDED=$(git diff --name-only --diff-filter=A "origin/${{ github.base_ref }}...HEAD")
+          echo "files<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$ADDED" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+      - name: Run pattern-check-gate verify
+        if: steps.diff.outputs.files != ''
+        run: npx --yes pattern-check-gate verify --files ${{ steps.diff.outputs.files }} --project-root "$PWD"