pattern-mcp 0.10.0 → 0.12.0

package/README.md

@@ -15,6 +15,12 @@ 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.11.0** — adds `pattern-check-gate init`, a guided
+setup for the 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 +28,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)
@@ -1477,14 +1484,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
@@ -1578,6 +1592,11 @@ 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
@@ -1586,19 +1605,54 @@ 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.
 
-Two pieces, both templates under `templates/` -- pattern-mcp never
-installs either into your repo on its own:
-
-- **`templates/hooks/check-gate-hook.mjs`** + **`templates/claude-settings/settings.json`**
-  -- a Claude Code `PreToolUse` 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.
+**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
@@ -1615,11 +1669,11 @@ An escape hatch exists for both a whole-hook kill switch
 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`, and
-`src/check-gate.ts` (the new `pattern-check-gate` CLI, this project's
-first entry point separate from the stdio MCP server) for the
-implementation, and BACKLOG.md's "Enforcement boundary: hook + CI gate"
-entry for the fuller design writeup.
+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
 

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

@@ -2,21 +2,28 @@
 // pattern-check-gate -- the enforcement-boundary CLI (see
 // BACKLOG.md's "Enforcement boundary: hook + CI gate" entry).
 //
-// Two modes, one shared classifier (component-gate.ts) so the local hook
-// and the CI check can never silently drift on what counts as "gated":
+// 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 the PreToolUse hook template) where
+//   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.
@@ -30,6 +37,8 @@ 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(/^\.\//, "");
 }
@@ -86,10 +95,14 @@ function emit(result, ok) {
 }
 async function runWrite(root, flags) {
     const fileArg = flags.file;
-    const projectId = flags["project-id"];
-    if (typeof fileArg !== "string" || typeof projectId !== "string") {
-        emit({ ok: false, reason: "write mode requires --file <path> and --project-id <id>" }, false);
+    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);
@@ -190,9 +203,13 @@ async function main() {
     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("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);
     }
 }

package/dist/index.js

@@ -38,6 +38,7 @@ import { homedir } from "node:os";
 import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { captureApiError, captureRecommendation, getClient as getPostHogClient, installId, printTelemetryNoticeOnce, shutdownTelemetry, TELEMETRY_ENABLED, } from "./telemetry.js";
+import { offerEnforcementSetupOnce } from "./init-enforcement.js";
 export const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
 // Only required for org-scoped keys (not tied to one workspace); unset for
 // legacy workspace-scoped keys, which don't need it.
@@ -3864,6 +3865,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 async function main() {
     printTelemetryNoticeOnce();
+    // Piggybacks on this same first-run moment (Option B, see
+    // init-enforcement.ts) -- always prints a one-time, non-blocking mention;
+    // only prompts interactively when stdin is a real TTY, never when a real
+    // MCP client has piped stdio into this process for JSON-RPC. Always
+    // returns before the transport below claims stdin.
+    await offerEnforcementSetupOnce(PROJECT_ROOT);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Best-effort telemetry drain on clean shutdown -- no-op when telemetry

package/dist/init-enforcement.js

@@ -0,0 +1,385 @@
+// 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 { homedir } from "node:os";
+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.");
+}
+// Option B from BACKLOG.md's "Enforcement boundary setup" entry: piggyback
+// on the moment someone's already setting Pattern up, rather than leaving
+// enforcement as something only the README mentions. Called once from
+// index.ts's main(), right alongside printTelemetryNoticeOnce, before the
+// stdio transport connects.
+//
+// The literal original phrasing of this option ("extend the first-run
+// notice into a [y/N] prompt") turns out not to be safely buildable as
+// written: stdin is the live JSON-RPC channel a real MCP client uses to
+// talk to this process (see telemetry.ts's printTelemetryNoticeOnce for
+// the same constraint, stated first). Blocking it on a keypress here would
+// fight the protocol handshake, not show a dialog. So this does two
+// different things depending on how stdin is actually connected:
+//
+//  - Always (any context, including a real client subprocess): print a
+//    one-time, non-blocking mention that the enforcement boundary exists
+//    and how to set it up. Same "print once, gated by a marker file"
+//    pattern as the telemetry notice, deliberately a separate marker/
+//    message so the two stay independently legible in a terminal.
+//  - Only when process.stdin.isTTY is true -- which a real MCP client's
+//    spawned subprocess never has, since it always pipes stdio to speak
+//    JSON-RPC over it, but a human running `npx pattern-mcp` bare in
+//    their own terminal does -- also offer a real interactive prompt,
+//    reusing runInit itself rather than duplicating its logic.
+const ENFORCEMENT_NOTICE_PATH = process.env.PATTERN_ENFORCEMENT_NOTICE_PATH ?? join(homedir(), ".pattern", "enforcement_notice_shown");
+export async function offerEnforcementSetupOnce(root) {
+    if (process.env.PATTERN_NO_ENFORCEMENT_NOTICE)
+        return;
+    try {
+        readFileSync(ENFORCEMENT_NOTICE_PATH, "utf8");
+        return; // Already shown -- never repeat, same discipline as the telemetry notice.
+    }
+    catch {
+        // No marker yet -- fall through and show it.
+    }
+    console.error([
+        "",
+        "Pattern -- enforcement boundary available (this will not print again)",
+        "By default, Pattern is something the calling agent chooses to use.",
+        "An opt-in hook + CI check can require it instead: run `npx pattern-check-gate init`",
+        "in your repo to set it up.",
+        "Full details: https://github.com/donaldrichard19-LVD/pattern-mcp#enforcement-boundary-hook--ci-gate",
+        "",
+    ].join("\n"));
+    try {
+        mkdirSync(dirname(ENFORCEMENT_NOTICE_PATH), { recursive: true });
+        writeFileSync(ENFORCEMENT_NOTICE_PATH, new Date().toISOString(), "utf8");
+    }
+    catch {
+        // Couldn't persist the marker -- worst case this prints again next
+        // run. Never blocks startup over it, same as the telemetry notice.
+    }
+    if (!process.stdin.isTTY)
+        return;
+    try {
+        const setUpNow = await confirm("Set it up now?", { yes: false }, false);
+        if (setUpNow) {
+            await runInit(root, { yes: false }); // closes the shared readline itself, in its own finally block
+        }
+    }
+    finally {
+        // closeRl() is safe to call even if runInit already closed it (checks
+        // rl?.close() and no-ops on null) -- this just guarantees stdin is
+        // always released back before main() connects the stdio transport,
+        // whether the answer was no or runInit already cleaned up after itself.
+        closeRl();
+    }
+}

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,12 +1,13 @@
 {
   "name": "pattern-mcp",
-  "version": "0.10.0",
+  "version": "0.12.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-check-gate": "dist/check-gate.js"
+    "pattern-check-gate": "dist/check-gate.js",
+    "pattern-check-gate-hook": "dist/check-gate-hook.js"
   },
   "author": "Don Richard",
   "license": "MIT",

package/templates/claude-settings/settings.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "env PATTERN_PROJECT_ID=your-project-id node ./node_modules/pattern-mcp/templates/hooks/check-gate-hook.mjs",
+            "command": "npx --yes pattern-check-gate-hook",
             "timeout": 60
           }
         ]

package/templates/hooks/check-gate-hook.mjs

@@ -1,89 +0,0 @@
-#!/usr/bin/env node
-// Claude-Code-specific PreToolUse adapter for pattern-check-gate. Copy this
-// file into your repo (or reference it from node_modules/pattern-mcp) and
-// wire it up via .claude/settings.json -- see
-// ../claude-settings/settings.json for the exact hook config. Not
-// installed automatically by pattern-mcp; this is opt-in (see
-// BACKLOG.md's "Enforcement boundary: hook + CI gate" entry for why).
-//
-// 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.
-//
-// Requires a PATTERN_PROJECT_ID env var (or --project-id below) -- set it
-// in the hook's own "command" (e.g. via `env PATTERN_PROJECT_ID=my-app
-// node ...`) or export it in your shell profile for local dev.
-
-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
-  // -- this is the one piece of Claude-Code-specific state check-gate.ts
-  // itself doesn't have access to. Edit calls always target an existing
-  // file, so isNewFile is always false for them, which is why they're
-  // effectively never gated by this hook (see component-gate.ts's
-  // comment on isNewFile) -- 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 projectId = process.env.PATTERN_PROJECT_ID;
-  if (!projectId) {
-    // Fail open with a clear stderr note rather than blocking every write
-    // in a repo that hasn't configured this yet -- misconfiguration
-    // shouldn't look identical to "no ledger entry found."
-    process.stderr.write("check-gate-hook: PATTERN_PROJECT_ID not set, skipping gate\n");
-    process.exit(0);
-  }
-
-  const args = ["write", "--file", filePath, "--project-id", projectId, "--project-root", input.cwd ?? process.cwd()];
-  if (isNewFile) args.push("--is-new");
-
-  const result = spawnSync("npx", ["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();