rungate 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/conformity.ts CHANGED
@@ -17,6 +17,7 @@ import { tryLoadRungateConfig } from "./config-loader";
17
17
  import { stripJsComments } from "./strip-js-comments";
18
18
  import { parseScDeclarations } from "./sc-ids";
19
19
  import { isHarnessItself } from "./harness-identity";
20
+ import { tsconfigVerdict } from "./typescript-project";
20
21
 
21
22
  // ── Shared utilities ────────────────────────────────────────
22
23
 
@@ -539,17 +540,23 @@ function loadRegistry(
539
540
  return builtIn;
540
541
  }
541
542
 
542
- // Look for consumer custom matchers in .claude/rungate.json
543
- const configPath = join(projectRoot, ".claude", "rungate.json");
544
- if (!existsSync(configPath)) {
545
- _registryCache.set(cacheKey, builtIn);
546
- return builtIn;
547
- }
548
-
543
+ // Consumer custom matchers, via the loader (ADR-002 D1, #309). Reading the
544
+ // monolith directly saw nothing on a project that had migrated to the
545
+ // directory layout, so a consumer's custom matchers silently stopped
546
+ // existing the moment they ran the scaffold that migrates them.
547
+ // Named without constructing the path — the loader resolves either layout,
548
+ // so there is no single file to point at, and spelling one out here would
549
+ // be the very access CONFIG-1 forbids in the file that hosts CONFIG-1.
550
+ const configDesc = `the rungate config under ${projectRoot}`;
549
551
  let customMatchers: Array<{ name: string; regex: string }>;
550
552
  try {
551
- const config = JSON.parse(readFileSync(configPath, "utf-8"));
552
- customMatchers = config.customMatchers ?? [];
553
+ const config = tryLoadRungateConfig(projectRoot);
554
+ if (!config) {
555
+ _registryCache.set(cacheKey, builtIn);
556
+ return builtIn;
557
+ }
558
+ customMatchers = (config as { customMatchers?: Array<{ name: string; regex: string }> })
559
+ .customMatchers ?? [];
553
560
  } catch (err) {
554
561
  // Falling back to the built-ins is right — one consumer's broken config
555
562
  // must not take the engine's own matchers down with it. Doing it in
@@ -563,7 +570,7 @@ function loadRegistry(
563
570
  // logs is how a secret in a misplaced field reaches somewhere it was
564
571
  // never meant to go.
565
572
  console.warn(
566
- `WARN: ${configPath} could not be read as JSON (${err instanceof Error ? err.name : "error"}; ` +
573
+ `WARN: ${configDesc} could not be read as JSON (${err instanceof Error ? err.name : "error"}; ` +
567
574
  `message withheld — it can quote file contents). ` +
568
575
  `Falling back to the built-in matcher registry — any customMatchers in that file are NOT loaded, ` +
569
576
  `so SCs written against them will be reported as having no matcher.`,
@@ -582,7 +589,7 @@ function loadRegistry(
582
589
  for (const candidate of customMatchers) {
583
590
  if (!allowOverride && builtInNames.has(candidate.name)) {
584
591
  console.warn(
585
- `WARN: ${configPath} defines a custom matcher named "${candidate.name}", which is a built-in. ` +
592
+ `WARN: ${configDesc} defines a custom matcher named "${candidate.name}", which is a built-in. ` +
586
593
  `A project cannot replace a built-in matcher while being verified by it — the entry is IGNORED. ` +
587
594
  `Rename it to extend the vocabulary instead.`,
588
595
  );
@@ -595,7 +602,7 @@ function loadRegistry(
595
602
  new RegExp(candidate.regex, "i");
596
603
  } catch {
597
604
  console.warn(
598
- `WARN: ${configPath} custom matcher "${candidate.name}" has a regex that does not compile — the entry is IGNORED.`,
605
+ `WARN: ${configDesc} custom matcher "${candidate.name}" has a regex that does not compile — the entry is IGNORED.`,
599
606
  );
600
607
  continue;
601
608
  }
@@ -1389,10 +1396,15 @@ export function runScaffoldConformity(root: string, opts?: { extraSpecDirs?: str
1389
1396
  expect(missing).toEqual([]);
1390
1397
  });
1391
1398
 
1392
- test("rungate.json has required fields (if exists)", () => {
1393
- const p = join(root, ".claude", "rungate.json");
1394
- if (!existsSync(p)) return;
1395
- const config = JSON.parse(readFileSync(p, "utf-8"));
1399
+ test("rungate config has required fields (if configured)", () => {
1400
+ // Through the loader (ADR-002 D1, #309). Reading the monolith directly
1401
+ // meant a project on the directory layout skipped this check entirely —
1402
+ // `existsSync` was false, the test returned, and a config missing
1403
+ // `project` or `repo` passed by never being looked at. Exactly the
1404
+ // shape .claude/rules/checks-must-be-able-to-fail.md opens with, in the
1405
+ // check that validates config.
1406
+ const config = tryLoadRungateConfig(root);
1407
+ if (!config) return;
1396
1408
  expect(config.project).toBeDefined();
1397
1409
  expect(config.repo).toBeDefined();
1398
1410
  });
@@ -1994,16 +2006,22 @@ export function runDocHygiene(
1994
2006
 
1995
2007
  test("HYGIENE-11: Stale unreferenced files warn with archival suggestion", () => {
1996
2008
  const index = getRefIndex();
1997
- // Load stalenessThreshold from rungate.json, default 90 days
1998
- const configPath = join(root, ".claude", "rungate.json");
2009
+ // stalenessThreshold through the loader (ADR-002 D1, #309), default 90
2010
+ // days. The bare `catch {}` is kept deliberately narrow in meaning: a
2011
+ // config that cannot be read must not take HYGIENE-11 down, but it also
2012
+ // must not silently become 90 — which, with nothing logged, is what it
2013
+ // used to do.
1999
2014
  let threshold = 90;
2000
- if (existsSync(configPath)) {
2001
- try {
2002
- const config = JSON.parse(readFileSync(configPath, "utf-8"));
2003
- if (typeof config.stalenessThreshold === "number") {
2004
- threshold = config.stalenessThreshold;
2005
- }
2006
- } catch {}
2015
+ try {
2016
+ const config = tryLoadRungateConfig(root);
2017
+ if (typeof config?.stalenessThreshold === "number") {
2018
+ threshold = config.stalenessThreshold;
2019
+ }
2020
+ } catch (err) {
2021
+ console.warn(
2022
+ `WARN: HYGIENE-11 could not read the rungate config (${(err as Error).name}); ` +
2023
+ `using the ${threshold}-day default. A configured threshold is NOT in effect.`,
2024
+ );
2007
2025
  }
2008
2026
 
2009
2027
  // Scan docs directories for markdown files — skip reference/ entirely (AC-2)
@@ -2564,10 +2582,39 @@ export function runPackageValidation(root: string) {
2564
2582
  });
2565
2583
  }
2566
2584
 
2585
+ /**
2586
+ * #87 — TSC-1 demanded a tsconfig.json that the generator had deliberately
2587
+ * decided not to write.
2588
+ *
2589
+ * `createTsconfig` skips a project with no hand-written TypeScript, because a
2590
+ * tsconfig whose `include` matches nothing is tsc error TS18003 — a type check
2591
+ * that reads as broken rather than as "nothing to check". `createCiWorkflows`
2592
+ * and the AGENTS.md generator both agreed and emitted no step and no row. Then
2593
+ * this hard assert ran in that same consumer's generated conformity suite and
2594
+ * failed over the absent file. Both halves of the question were asserted at
2595
+ * once, which is the contradiction #87 was filed to settle.
2596
+ *
2597
+ * Settled in favour of "consumers may be non-TypeScript projects", so TSC-1
2598
+ * asks `tsconfigVerdict` — the one predicate `createTsconfig` uses — whether
2599
+ * it has anything to assert. The skip is RECORDED as a finding rather than
2600
+ * taken quietly: an unmeasured check and a satisfied check look identical from
2601
+ * the outside, and `.claude/rules/config-access.md` names the silent form as
2602
+ * the anti-pattern it is.
2603
+ */
2567
2604
  export function runTsconfigValidation(root: string) {
2568
2605
  describe("TSConfig validation", () => {
2569
- test("TSC-1: tsconfig.json exists", () => {
2570
- expect(existsSync(join(root, "tsconfig.json"))).toBe(true);
2606
+ test("TSC-1: tsconfig.json exists where TypeScript source does", () => {
2607
+ const verdict = tsconfigVerdict(root);
2608
+ if (!verdict.applicable) {
2609
+ addFinding({
2610
+ ruleId: "TSC-1",
2611
+ severity: "WARN",
2612
+ file: "tsconfig.json",
2613
+ message: `UNMEASURED: ${verdict.reason}`,
2614
+ });
2615
+ return;
2616
+ }
2617
+ expect(verdict.present, verdict.reason).toBe(true);
2571
2618
  });
2572
2619
 
2573
2620
  test("TSC-2: strict mode enabled", () => {
@@ -2627,6 +2674,296 @@ export function runModuleDepthCheck(root: string) {
2627
2674
  });
2628
2675
  }
2629
2676
 
2677
+ // ── Config access conformity (ADR-002 D4, #309) ────────────────
2678
+ //
2679
+ // ADR-001 decided the single-loader policy on 2026-10-05 and specified this
2680
+ // check as the enforcement. It was never built. Six days later the thing it
2681
+ // was written to stop had gone from ~24 sites to ~89 — the policy was
2682
+ // written down the whole time, which is the measurement that makes
2683
+ // "a rule nothing executes is not a rule" a number rather than a slogan.
2684
+ //
2685
+ // TWO checks, not one, because there are two bypass routes and ADR-001's
2686
+ // single check would have missed eleven of them: `workflows/*.js` reaches
2687
+ // config from inside agent PROMPT TEXT, which a TypeScript-source scan does
2688
+ // not look at.
2689
+ //
2690
+ // ## The self-reference trap
2691
+ //
2692
+ // This file is inside the scanned set and is about to contain the literals
2693
+ // it searches for. An allowlist naming the exempt files becomes evidence
2694
+ // those files are referenced — this repo has hit that three times. So the
2695
+ // pattern is ASSEMBLED from fragments that never appear adjacent in this
2696
+ // source, and the test asserts the check reports zero against its own file.
2697
+ // The three real violations this file used to carry are migrated to the
2698
+ // loader in the same change, so that zero is a fact and not an exemption.
2699
+ const CFG_DOT = ".";
2700
+ const CFG_DIR = "claude";
2701
+ const CFG_NAME = "rungate";
2702
+
2703
+ /**
2704
+ * A path being built to the config, in CODE.
2705
+ *
2706
+ * Comments are blanked by `stripJsComments` before this runs — offset
2707
+ * preserving, already proven on `ship.js` by its own suite — rather than by a
2708
+ * line rule of my own. Prose that DISCUSSES the config is not an access, and
2709
+ * counting it would bury the real sites in noise until the ratchet became a
2710
+ * number nobody reads.
2711
+ *
2712
+ * STATED LIMIT, carried over from ADR-001 and not an oversight: this is
2713
+ * string matching, so `join(root, CFG_DOT + CFG_DIR, dynamicName)` is not
2714
+ * caught. It catches every one of the present sites; a variable-constructed
2715
+ * path is not the realistic failure mode and an AST check is not worth the
2716
+ * dependency.
2717
+ */
2718
+ function configAccessPattern(): RegExp {
2719
+ return new RegExp(
2720
+ "\\" + CFG_DOT + CFG_DIR + "[\"'`/\\\\,\\s)]+\\s*[\"'`]?" + CFG_NAME,
2721
+ "g",
2722
+ );
2723
+ }
2724
+
2725
+ /** Directories CHECK-1 walks. Tests and `test/` are excluded by ADR-002 D4. */
2726
+ const CONFIG_SCAN_DIRS = ["lib", "gates", "scripts", "hooks", "generators"];
2727
+
2728
+ /** The one module allowed to read the config. ADR-002 D1. */
2729
+ const CONFIG_LOADER = "lib/config-loader.ts";
2730
+
2731
+ function walkSources(dir: string, rel: string, out: Array<{ path: string; text: string }>) {
2732
+ let entries;
2733
+ try {
2734
+ entries = readdirSync(dir, { withFileTypes: true });
2735
+ } catch {
2736
+ return;
2737
+ }
2738
+ for (const e of entries) {
2739
+ const abs = join(dir, e.name);
2740
+ const relPath = rel ? `${rel}/${e.name}` : e.name;
2741
+ if (e.isDirectory()) {
2742
+ if (e.name === "test" || e.name === "node_modules") continue;
2743
+ walkSources(abs, relPath, out);
2744
+ continue;
2745
+ }
2746
+ if (!/\.(ts|js)$/.test(e.name) || /\.test\.ts$/.test(e.name)) continue;
2747
+ out.push({ path: relPath, text: readFileSync(abs, "utf-8") });
2748
+ }
2749
+ }
2750
+
2751
+ /** What a scan saw: per-file counts, and how much it actually read. */
2752
+ export interface ConfigAccessScan {
2753
+ /** Repo-relative path -> site count. Allowlisted files are excluded. */
2754
+ counts: Record<string, number>;
2755
+ /** Files walked. ZERO means the scan found nothing to look at. */
2756
+ filesScanned: number;
2757
+ /** Bytes read. Zero with a non-zero file count means empty sources. */
2758
+ bytesScanned: number;
2759
+ }
2760
+
2761
+ /**
2762
+ * CHECK-1's reading: direct config access in TypeScript sources.
2763
+ *
2764
+ * A separate function from the refusal so there is ONE site for the mutation
2765
+ * harness to short-circuit (`.claude/rules/checks-must-be-able-to-fail.md`,
2766
+ * and ADR-002 D4's third mutation).
2767
+ */
2768
+ export function scanConfigAccess(root: string): ConfigAccessScan {
2769
+ const files: Array<{ path: string; text: string }> = [];
2770
+ for (const d of CONFIG_SCAN_DIRS) walkSources(join(root, d), d, files);
2771
+
2772
+ const counts: Record<string, number> = {};
2773
+ let bytesScanned = 0;
2774
+ for (const f of files) {
2775
+ bytesScanned += f.text.length;
2776
+ if (f.path === CONFIG_LOADER) continue;
2777
+ const n = (stripJsComments(f.text).match(configAccessPattern()) || []).length;
2778
+ if (n > 0) counts[f.path] = n;
2779
+ }
2780
+ return { counts, filesScanned: files.length, bytesScanned };
2781
+ }
2782
+
2783
+ /**
2784
+ * CHECK-2's reading: config access inside `workflows/*.js`, prompts included.
2785
+ *
2786
+ * Comments are stripped and literals are NOT, which is the whole point —
2787
+ * `ship.js` is mostly prompt text, and the eleven sites ADR-001's check could
2788
+ * not see all live inside template literals handed to agents.
2789
+ */
2790
+ export function scanPromptConfigAccess(root: string): ConfigAccessScan {
2791
+ const dir = join(root, "workflows");
2792
+ const counts: Record<string, number> = {};
2793
+ let filesScanned = 0;
2794
+ let bytesScanned = 0;
2795
+ let entries: string[];
2796
+ try {
2797
+ entries = readdirSync(dir).filter(f => f.endsWith(".js"));
2798
+ } catch {
2799
+ return { counts, filesScanned: 0, bytesScanned: 0 };
2800
+ }
2801
+ for (const f of entries) {
2802
+ const text = readFileSync(join(dir, f), "utf-8");
2803
+ filesScanned++;
2804
+ bytesScanned += text.length;
2805
+ const n = (stripJsComments(text).match(configAccessPattern()) || []).length;
2806
+ if (n > 0) counts[`workflows/${f}`] = n;
2807
+ }
2808
+ return { counts, filesScanned, bytesScanned };
2809
+ }
2810
+
2811
+ /**
2812
+ * The banked violations, read from `.claude/config-access-ratchet.json`.
2813
+ *
2814
+ * Data rather than a constant, because `lib/conformity.ts` travels into every
2815
+ * scaffolded project and rungate's own numbers have no business there. A
2816
+ * consumer with no ratchet file gets `{}` — zero tolerance, which is the
2817
+ * right default for a tree that has never had the defect.
2818
+ *
2819
+ * NOT `.claude/rungate*`, deliberately: this is harness metadata about a
2820
+ * migration, not project config, and routing it through the loader would make
2821
+ * the check depend on the thing it is enforcing access to.
2822
+ */
2823
+ export function readConfigAccessRatchet(
2824
+ root: string,
2825
+ scope: "sources" | "workflows" | "all" = "all",
2826
+ ): Record<string, number> {
2827
+ const p = join(root, ".claude", "config-access-ratchet.json");
2828
+ if (!existsSync(p)) return {};
2829
+ const raw = JSON.parse(readFileSync(p, "utf-8"));
2830
+ const out: Record<string, number> = {};
2831
+ for (const [k, v] of Object.entries(raw)) {
2832
+ if (typeof v !== "number") continue;
2833
+ // One file, two checks. Scoping matters because the both-ways ratchet
2834
+ // complains about a banked entry with no violations left, and CHECK-1
2835
+ // never scans `workflows/` — without this it would demand the removal of
2836
+ // every entry CHECK-2 owns, and vice versa.
2837
+ const isWorkflow = k.startsWith("workflows/");
2838
+ if (scope === "sources" && isWorkflow) continue;
2839
+ if (scope === "workflows" && !isWorkflow) continue;
2840
+ out[k] = v;
2841
+ }
2842
+ return out;
2843
+ }
2844
+
2845
+ /**
2846
+ * Turn a scan into refusals. Empty allows. BOTH DIRECTIONS.
2847
+ *
2848
+ * Over its number refuses, and so does UNDER — an entry that has stopped
2849
+ * being a violation is an entry nobody will ever remove, and the list rots
2850
+ * into one more artefact that certifies nothing. A file absent from the
2851
+ * ratchet is allowed nothing, which is ADR-002 D4's requirement that the
2852
+ * ratchet "refuses on any new file entering the violation set even while the
2853
+ * count is above zero": the migration window is exactly when the next reader
2854
+ * is most likely to be written.
2855
+ *
2856
+ * An EMPTY SCAN REFUSES. A conformity check that silently scans zero files
2857
+ * reports zero violations and is indistinguishable from compliance, which is
2858
+ * this repo's defining defect and would be the most embarrassing possible
2859
+ * place to reproduce it (ADR-002 D4, mutation 5).
2860
+ */
2861
+ export function configAccessViolations(
2862
+ scan: ConfigAccessScan,
2863
+ banked: Record<string, number>,
2864
+ label: string,
2865
+ requireNonEmpty = true,
2866
+ ): string[] {
2867
+ const out: string[] = [];
2868
+ if (requireNonEmpty && scan.filesScanned === 0) {
2869
+ return [
2870
+ `${label}: the scan read NO files. A check that scans nothing reports ` +
2871
+ `zero violations and cannot be told from compliance — refusing rather ` +
2872
+ `than reporting clean (ADR-002 D4).`,
2873
+ ];
2874
+ }
2875
+ if (requireNonEmpty && scan.filesScanned > 0 && scan.bytesScanned === 0) {
2876
+ return [`${label}: ${scan.filesScanned} files were walked and none had any content.`];
2877
+ }
2878
+
2879
+ for (const [file, n] of Object.entries(scan.counts).sort()) {
2880
+ const allowed = banked[file] ?? 0;
2881
+ if (n > allowed) {
2882
+ out.push(
2883
+ `${label}: ${file} has ${n} direct config access site(s), ${allowed} allowed. ` +
2884
+ `Only ${CONFIG_LOADER} may read the config (ADR-002 D1). Use ` +
2885
+ `loadRungateConfig / tryLoadRungateConfig / resolveConfig.`,
2886
+ );
2887
+ } else if (n < allowed) {
2888
+ out.push(
2889
+ `${label}: ${file} is banked at ${allowed} but only ${n} remain — lower the ` +
2890
+ `number in .claude/config-access-ratchet.json in the same commit that earned it.`,
2891
+ );
2892
+ }
2893
+ }
2894
+ for (const [file, allowed] of Object.entries(banked).sort()) {
2895
+ if (allowed > 0 && !(file in scan.counts)) {
2896
+ out.push(
2897
+ `${label}: ${file} is banked at ${allowed} but has no violations left — ` +
2898
+ `remove its entry from .claude/config-access-ratchet.json.`,
2899
+ );
2900
+ }
2901
+ }
2902
+ return out;
2903
+ }
2904
+
2905
+ /**
2906
+ * CHECK-1 — direct config access in TypeScript sources (ADR-002 D4).
2907
+ *
2908
+ * FAILS; does not warn. `DEPTH-1` and `ABSENCE-1` only `console.warn`, and
2909
+ * warnings are how 89 sites accumulated with the policy written down.
2910
+ */
2911
+ export function runConfigAccessValidation(root: string) {
2912
+ describe("Config access (ADR-002 D1)", () => {
2913
+ test("CONFIG-1: only the loader reads the rungate config", () => {
2914
+ const scan = scanConfigAccess(root);
2915
+ const violations = configAccessViolations(
2916
+ scan,
2917
+ readConfigAccessRatchet(root, "sources"),
2918
+ "CONFIG-1",
2919
+ );
2920
+ for (const v of violations) {
2921
+ addFinding({
2922
+ ruleId: "CONFIG-1",
2923
+ severity: "FAIL",
2924
+ file: v.split(": ")[1]?.split(" ")[0] || "",
2925
+ message: v,
2926
+ fixCommand: "Route the read through lib/config-loader.ts",
2927
+ });
2928
+ }
2929
+ expect(violations, violations.join("\n")).toEqual([]);
2930
+ });
2931
+ });
2932
+ }
2933
+
2934
+ /**
2935
+ * CHECK-2 — config access inside workflow prompt text (ADR-002 D4).
2936
+ *
2937
+ * The check ADR-001 did not have, and the reason its single check would have
2938
+ * been insufficient: `ship.js:1637` reaches the config from inside a prompt.
2939
+ * Allowlist is empty — no workflow has any business reading it directly.
2940
+ */
2941
+ export function runPromptConfigAccessValidation(root: string) {
2942
+ describe("Config access in workflows (ADR-002 D4)", () => {
2943
+ test("CONFIG-2: no workflow reaches the rungate config, prompts included", () => {
2944
+ const scan = scanPromptConfigAccess(root);
2945
+ // A project with no workflows/ directory is not in violation; the
2946
+ // empty-scan refusal above is for a scan that should have found files.
2947
+ const violations = configAccessViolations(
2948
+ scan,
2949
+ readConfigAccessRatchet(root, "workflows"),
2950
+ "CONFIG-2",
2951
+ scan.filesScanned > 0,
2952
+ );
2953
+ for (const v of violations) {
2954
+ addFinding({
2955
+ ruleId: "CONFIG-2",
2956
+ severity: "FAIL",
2957
+ file: v.split(": ")[1]?.split(" ")[0] || "",
2958
+ message: v,
2959
+ fixCommand: "Point the prompt at the resolved-config artefact instead",
2960
+ });
2961
+ }
2962
+ expect(violations, violations.join("\n")).toEqual([]);
2963
+ });
2964
+ });
2965
+ }
2966
+
2630
2967
  export function runAbsenceValidation(root: string) {
2631
2968
  describe("Absence validation", () => {
2632
2969
  test("ABSENCE-1: anti-criteria use absence verification", () => {
package/lib/create-sc.ts CHANGED
@@ -9,6 +9,7 @@ import { join, dirname } from "path";
9
9
  import { fileURLToPath } from "url";
10
10
 
11
11
  import type { ScRegistry } from "./sc-ids";
12
+ import { tryLoadRungateConfig } from "./config-loader";
12
13
 
13
14
  // ── Types ─────────────────────────────────────────────────────
14
15
 
@@ -41,9 +42,10 @@ function loadBuiltInRegistry(): RegistryEntry[] {
41
42
  /**
42
43
  * Load the matcher registry, optionally merging consumer-defined custom matchers.
43
44
  *
44
- * When projectRoot is provided, looks for .claude/rungate.json in that directory
45
- * and merges any `customMatchers` array entries with the built-in registry.
46
- * Consumer entries with the same `name` as a built-in entry override the built-in.
45
+ * When projectRoot is provided, resolves that project's config through
46
+ * `lib/config-loader.ts` and merges any `customMatchers` array entries with the
47
+ * built-in registry. Consumer entries with the same `name` as a built-in entry
48
+ * override the built-in.
47
49
  */
48
50
  export function loadRegistry(projectRoot?: string): RegistryEntry[] {
49
51
  const cacheKey = projectRoot ?? "__builtin__";
@@ -54,33 +56,26 @@ export function loadRegistry(projectRoot?: string): RegistryEntry[] {
54
56
  return builtIn;
55
57
  }
56
58
 
57
- // Look for consumer custom matchers in .claude/rungate.json
58
- const configPath = join(projectRoot, ".claude", "rungate.json");
59
- if (!existsSync(configPath)) {
59
+ // Through the loader, so a consumer on the directory layout can supply
60
+ // custom matchers at all — this read was monolith-only, which is #212/#90.
61
+ // The parse failure is NOT caught: the old `catch` returned the built-in
62
+ // registry, so a consumer whose config had a trailing comma silently got
63
+ // rungate's matchers and no indication their own had been dropped.
64
+ const config = tryLoadRungateConfig(projectRoot);
65
+ const customMatchers = (config?.customMatchers ?? []) as RegistryEntry[];
66
+ if (customMatchers.length === 0) {
60
67
  _registryCache.set(cacheKey, builtIn);
61
68
  return builtIn;
62
69
  }
63
70
 
64
- try {
65
- const config = JSON.parse(readFileSync(configPath, "utf-8"));
66
- const customMatchers: RegistryEntry[] = config.customMatchers ?? [];
67
- if (customMatchers.length === 0) {
68
- _registryCache.set(cacheKey, builtIn);
69
- return builtIn;
70
- }
71
+ // Merge: consumer entries override built-in entries with same name
72
+ const merged = builtIn.filter(
73
+ (entry) => !customMatchers.some((c) => c.name === entry.name)
74
+ );
75
+ merged.push(...customMatchers);
71
76
 
72
- // Merge: consumer entries override built-in entries with same name
73
- const merged = builtIn.filter(
74
- (entry) => !customMatchers.some((c) => c.name === entry.name)
75
- );
76
- merged.push(...customMatchers);
77
-
78
- _registryCache.set(cacheKey, merged);
79
- return merged;
80
- } catch {
81
- _registryCache.set(cacheKey, builtIn);
82
- return builtIn;
83
- }
77
+ _registryCache.set(cacheKey, merged);
78
+ return merged;
84
79
  }
85
80
 
86
81
  // ── Pattern param definitions ─────────────────────────────────