rungate 0.4.0 → 0.5.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.
Files changed (65) hide show
  1. package/config/behavioral-sc-map.json +170 -0
  2. package/config/brief-policies.json +28 -0
  3. package/config/ceremony-profiles.json +207 -0
  4. package/config/check-registry.json +114 -0
  5. package/config/matcher-registry.json +142 -0
  6. package/config/prove-evidence.schema.json +65 -0
  7. package/config/spec-policies.json +36 -0
  8. package/config/universal-rules.yaml +15 -0
  9. package/config/workflow-schema.json +279 -0
  10. package/lib/ac-quality.ts +119 -0
  11. package/lib/cli-commands.ts +7 -1
  12. package/lib/config-loader.ts +129 -5
  13. package/lib/conformity.ts +1122 -31
  14. package/lib/context-docs.ts +182 -0
  15. package/lib/create-brief.ts +22 -17
  16. package/lib/create-sc.ts +35 -8
  17. package/lib/doc-scan-targets.ts +435 -0
  18. package/lib/gate-check-audit.ts +9 -9
  19. package/lib/github.ts +195 -0
  20. package/lib/js-top-level-code.ts +27 -2
  21. package/lib/organize.ts +129 -40
  22. package/lib/package-closure.ts +387 -0
  23. package/lib/project-aliases.ts +100 -0
  24. package/lib/release-preflight.ts +352 -48
  25. package/lib/rungate-schema.ts +23 -1
  26. package/lib/sc-cover.ts +92 -1
  27. package/lib/sc-ids.ts +151 -0
  28. package/lib/scaffold/defaults.ts +40 -0
  29. package/lib/scaffold/managed-workflow.ts +125 -27
  30. package/lib/scaffold/owned-files.ts +6 -0
  31. package/lib/scaffold/profiles.ts +94 -0
  32. package/lib/scaffold/rehearsal.ts +355 -0
  33. package/lib/scaffold/steps.ts +787 -105
  34. package/lib/scaffold/write-steps.ts +208 -0
  35. package/lib/scratch-cleanup.ts +198 -0
  36. package/lib/scratch-roots.ts +94 -0
  37. package/lib/source-anchor.ts +144 -0
  38. package/lib/success-doc.ts +779 -0
  39. package/lib/suite-run-reading.ts +194 -0
  40. package/lib/test-census.ts +199 -0
  41. package/lib/trajectory.ts +377 -0
  42. package/lib/validators/spec-validators.ts +52 -35
  43. package/lib/workflow-security.ts +152 -7
  44. package/lib/workflow-test-harness.ts +349 -0
  45. package/lib/worktree-cleanup.ts +123 -7
  46. package/lib/worktree-repo.ts +165 -0
  47. package/package.json +10 -1
  48. package/scripts/audit-specs.ts +134 -37
  49. package/scripts/audit-transcript.ts +259 -0
  50. package/scripts/create-sc.ts +15 -1
  51. package/scripts/create-success.ts +162 -0
  52. package/scripts/detect-sc-drift.ts +200 -0
  53. package/scripts/extract-constraints.ts +16 -36
  54. package/scripts/scaffold-project.ts +51 -137
  55. package/scripts/split-spec.ts +315 -0
  56. package/scripts/sync-sc-status.ts +751 -0
  57. package/specs/SPEC-TEMPLATE.md +200 -0
  58. package/templates/SUCCESS-TEMPLATE.md +72 -0
  59. package/templates/agent-briefs/_shared.md +9 -0
  60. package/templates/agent-briefs/aditi.md +46 -0
  61. package/templates/agent-briefs/discovery.md +37 -0
  62. package/templates/agent-briefs/marcus.md +39 -0
  63. package/templates/agent-briefs/quinn.md +67 -0
  64. package/templates/agent-briefs/rook.md +40 -0
  65. package/templates/agent-briefs/serena.md +39 -0
package/lib/conformity.ts CHANGED
@@ -6,10 +6,11 @@
6
6
  * runScaffoldConformity(import.meta.dir + "/..");
7
7
  */
8
8
  import { describe, test, expect } from "bun:test";
9
- import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
9
+ import { existsSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "fs";
10
+ import type { Dirent } from "fs";
10
11
  import { collectSpecFiles } from "./spec-files";
11
12
  import { spawnSync } from "child_process";
12
- import { join, dirname } from "path";
13
+ import { join, dirname, sep } from "path";
13
14
  import { fileURLToPath } from "url";
14
15
  import { deriveDirectoryName } from "../scripts/split-spec";
15
16
  import { readFreshCache } from "./behavioral-cache";
@@ -17,7 +18,8 @@ import { tryLoadRungateConfig } from "./config-loader";
17
18
  import { stripJsComments } from "./strip-js-comments";
18
19
  import { parseScDeclarations } from "./sc-ids";
19
20
  import { isHarnessItself } from "./harness-identity";
20
- import { tsconfigVerdict } from "./typescript-project";
21
+ import { tsconfigVerdict, TS_SOURCE_DIRS } from "./typescript-project";
22
+ import { readSuccessDoc, readSuccessTemplate, successViolations } from "./success-doc";
21
23
 
22
24
  // ── Shared utilities ────────────────────────────────────────
23
25
 
@@ -2722,8 +2724,226 @@ function configAccessPattern(): RegExp {
2722
2724
  );
2723
2725
  }
2724
2726
 
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
+ * Calls whose arguments are FILESYSTEM PATHS (#415).
2729
+ *
2730
+ * The positive list IS the definition, not a heuristic: a config path that
2731
+ * reaches the disk is either built by a path API or handed straight to an fs
2732
+ * one. Everything a `node:path` call touches is a path by construction.
2733
+ */
2734
+ const FS_PATH_CALLS = new Set([
2735
+ "existsSync", "readFileSync", "writeFileSync", "appendFileSync", "readdirSync",
2736
+ "mkdirSync", "rmSync", "rmdirSync", "unlinkSync", "statSync", "lstatSync",
2737
+ "copyFileSync", "cpSync", "renameSync", "realpathSync", "readlinkSync", "openSync",
2738
+ ]);
2739
+
2740
+ /**
2741
+ * `node:path` builders. Receiver-checked, unlike the fs names above, because
2742
+ * `Array.prototype.join` shares one of them and `["a", "b"].join(", ")` is
2743
+ * text. A bare `join` is the named import this repo uses; `path.join` is the
2744
+ * namespace form.
2745
+ */
2746
+ const PATH_BUILDERS = new Set(["join", "resolve", "relative", "normalize"]);
2747
+
2748
+ /**
2749
+ * Handing a shell a command that names the config is a read, and the literal
2750
+ * carrying it has spaces in it by construction — `cat <root>/…json` would
2751
+ * otherwise read as prose and go uncounted, which is the one fail-open the
2752
+ * prose rule could have opened on its own.
2753
+ */
2754
+ const SHELL_CALLS = new Set(["execSync", "exec", "execFileSync", "spawnSync", "spawn"]);
2755
+
2756
+ function isPathCall(callee: string | null): boolean {
2757
+ if (!callee) return false;
2758
+ const bare = callee.slice(callee.lastIndexOf(".") + 1);
2759
+ if (FS_PATH_CALLS.has(bare) || SHELL_CALLS.has(bare)) return true;
2760
+ return PATH_BUILDERS.has(bare) && (callee === bare || callee === `path.${bare}`);
2761
+ }
2762
+
2763
+ /**
2764
+ * Calls that take TEXT. Both are universal JS idioms rather than names out of
2765
+ * this repo — `x.push(…)` into a list of messages, and `console.*` — and both
2766
+ * are needed because a documentation entry can carry a path-SHAPED literal:
2767
+ * `keyFiles.push({ file: "…/" })` is a row in a generated table, not a read.
2768
+ */
2769
+ function isTextCall(callee: string | null): boolean {
2770
+ if (!callee) return false;
2771
+ return callee.endsWith(".push") || callee.startsWith("console.");
2772
+ }
2773
+
2774
+ /** The dotted name immediately left of an open paren, or `""` for a group. */
2775
+ function calleeBefore(text: string, parenIndex: number): string {
2776
+ let j = parenIndex - 1;
2777
+ while (j >= 0 && /\s/.test(text[j]!)) j--;
2778
+ const end = j + 1;
2779
+ while (j >= 0 && /[A-Za-z0-9_$.]/.test(text[j]!)) j--;
2780
+ return text.slice(j + 1, end);
2781
+ }
2782
+
2783
+ /** What a config-path match turned out to be. */
2784
+ export type ConfigSiteKind = "use" | "mention";
2785
+
2786
+ export interface ConfigSite {
2787
+ /** Offset in the comment-stripped source. */
2788
+ index: number;
2789
+ kind: ConfigSiteKind;
2790
+ /** Innermost enclosing call, or null at statement level. */
2791
+ callee: string | null;
2792
+ /** The literal run the match sits in, or null if it is not in one. */
2793
+ literal: string | null;
2794
+ }
2795
+
2796
+ /**
2797
+ * Is this path being BUILT, or merely NAMED? (#415)
2798
+ *
2799
+ * The one place that decides, so the mutation harness has one site to
2800
+ * collapse (`.claude/rules/checks-must-be-able-to-fail.md`). Collapsing it
2801
+ * either way moves a banked number and the both-ways ratchet refuses, which
2802
+ * is the property `test/config-access-mentions.test.ts` SC-1553 pins down.
2803
+ *
2804
+ * ## How the two views are read
2805
+ *
2806
+ * There is NO second lexer here. `stripJsComments` already scans code,
2807
+ * strings, templates (with `${}` to any depth) and regex literals, offset
2808
+ * preserving, and `blankLiterals` gives a view in which every literal's
2809
+ * CONTENTS are spaces and its delimiters are not. Over that view a naive
2810
+ * paren counter is exact — no quote, paren or brace inside a string or a
2811
+ * regex can reach it — and the literal a match sits in is simply the maximal
2812
+ * run of blanked offsets around it. A second scanner answering the same
2813
+ * question is a second scanner to drift.
2814
+ *
2815
+ * ## The decision, and which way each branch is allowed to be wrong
2816
+ *
2817
+ * 1. an fs, shell or `node:path` call
2818
+ * around it → USE, whatever the text says
2819
+ * 2. otherwise, prose around the path → MENTION
2820
+ * 3. otherwise, a path-shaped literal into a
2821
+ * message list or the console → MENTION
2822
+ * 4. otherwise → USE
2823
+ *
2824
+ * Rule 4 is the fail-closed default and it is the reason an unrecognised
2825
+ * helper, a bare `const p = "…"` or a path built by concatenation still
2826
+ * counts: a path-shaped literal is a path until something shows otherwise.
2827
+ *
2828
+ * STATED LIMIT, in the tradition of ADR-001's: a literal containing
2829
+ * whitespace, passed to a call this cannot recognise, reads as prose. Both
2830
+ * halves have to be true at once, which is why the remaining blind spot is a
2831
+ * sentence that is also a path.
2832
+ */
2833
+ export function classifyConfigSites(source: string): ConfigSite[] {
2834
+ const code = stripJsComments(source);
2835
+ const bare = stripJsComments(source, { blankLiterals: true });
2836
+
2837
+ const sites: ConfigSite[] = [];
2838
+ const pattern = configAccessPattern();
2839
+ let match: RegExpExecArray | null;
2840
+ while ((match = pattern.exec(code)) !== null) {
2841
+ const at = match.index;
2842
+
2843
+ let depthCallee: string | null = null;
2844
+ const stack: string[] = [];
2845
+ for (let i = 0; i < at; i++) {
2846
+ const c = bare[i];
2847
+ if (c === "(") stack.push(calleeBefore(bare, i));
2848
+ else if (c === ")") stack.pop();
2849
+ }
2850
+ depthCallee = stack.length > 0 ? stack[stack.length - 1]! : null;
2851
+
2852
+ let literal: string | null = null;
2853
+ if (bare[at] === " " && code[at] !== " ") {
2854
+ let lo = at;
2855
+ let hi = at;
2856
+ while (lo > 0 && bare[lo - 1] === " ") lo--;
2857
+ while (hi + 1 < bare.length && bare[hi + 1] === " ") hi++;
2858
+ literal = code.slice(lo, hi + 1);
2859
+ }
2860
+
2861
+ const kind: ConfigSiteKind = isPathCall(depthCallee)
2862
+ ? "use"
2863
+ : literal !== null && /\s/.test(literal)
2864
+ ? "mention"
2865
+ : isTextCall(depthCallee)
2866
+ ? "mention"
2867
+ : "use";
2868
+
2869
+ sites.push({ index: at, kind, callee: depthCallee, literal });
2870
+ }
2871
+ return sites;
2872
+ }
2873
+
2874
+ /**
2875
+ * `workflows/` is CONFIG-2's, and it is the ONLY directory CONFIG-1 declines
2876
+ * from the set of places this project believes TypeScript lives (#492).
2877
+ *
2878
+ * `readConfigAccessRatchet` scopes the two ratchets separately precisely so
2879
+ * the checks do not demand the removal of each other's entries, so CONFIG-1
2880
+ * walking `workflows/` would make each one's green require the other's red.
2881
+ */
2882
+ export const CONFIG_1_DECLINES = new Set(["workflows"]);
2883
+
2884
+ /**
2885
+ * Directories CHECK-1 walks. Tests and `test/` are excluded by ADR-002 D4.
2886
+ *
2887
+ * DERIVED from `TS_SOURCE_DIRS` rather than written out again, because the
2888
+ * two lists silently diverged and that is #492. The hand-written version was
2889
+ * `["lib", "gates", "scripts", "hooks", "generators"]` while
2890
+ * `TS_SOURCE_DIRS` was `["src", "lib", "scripts", "gates", "hooks",
2891
+ * "workflows"]`. **`src/` was in the second and not the first**, so a
2892
+ * consumer on the single most common layout outside this repo got a CONFIG-1
2893
+ * that walked zero files over a project that might be full of direct config
2894
+ * reads. Measured on one real consumer: PASS, having scanned 36 of 426
2895
+ * TypeScript files, 390 of them in `src/` (#492).
2896
+ *
2897
+ * Deriving it means a directory added to one list cannot fail to reach the
2898
+ * other without someone writing it into `CONFIG_1_DECLINES` and saying why.
2899
+ * `test/config-access-conformity.test.ts` asserts that relationship, because
2900
+ * a derivation nothing checks is a convention.
2901
+ *
2902
+ * **This is not the whole of #492, and on its own it would be the wrong
2903
+ * fix.** A hardcoded list being wrong is the defect; `src/` was only the
2904
+ * instance. The coverage shortfall reported further down is what survives
2905
+ * the next directory nobody thought of, and its fixture deliberately uses a
2906
+ * name no list will ever contain.
2907
+ */
2908
+ export const CONFIG_SCAN_DIRS = [
2909
+ ...new Set([...TS_SOURCE_DIRS, "generators"]),
2910
+ ].filter(d => !CONFIG_1_DECLINES.has(d));
2911
+
2912
+ /**
2913
+ * Source CONFIG-1 does not walk and that is NOT a coverage shortfall,
2914
+ * because somebody else measures it or policy excludes it.
2915
+ *
2916
+ * Without this the shortfall warning is wrong on rungate's own tree, and on
2917
+ * every tree the scaffolder produces. Measured through the real validator
2918
+ * before it existed: **19 files named, 1 of them a true gap.**
2919
+ *
2920
+ * | Named | Count | Why it is not a shortfall |
2921
+ * |---|---|---|
2922
+ * | `workflows/` | 6 | `CONFIG_1_DECLINES` holds it *because CONFIG-2 owns it*. `scanPromptConfigAccess` reads exactly those 6, and the ratchet banks 11 violations across three of them. The warning's sentence — "a direct config read there is invisible to it" — is not imprecise about these, it is false: they are enumerated and ratcheted |
2923
+ * | `test/` | 12 | excluded by ADR-002 D4, as `CONFIG_SCAN_DIRS`'s own docstring says. Nine of the twelve are planted fixture projects, which are not project source in any sense |
2924
+ * | `bin/` | 1 | **a real gap, and the one the warning should keep naming** |
2925
+ *
2926
+ * A warning that is wrong on the repo that ships it is how a project learns
2927
+ * to ignore warnings, and then the true one — `bin/rungate.ts` here, the
2928
+ * shape of #476's `bin/cli.ts` — is invisible too. The test asserting that
2929
+ * silence said so in its own comment before this was measured.
2930
+ *
2931
+ * Found by sec-492. It is #492's own rubric entry recurring inside #492's
2932
+ * fix: every shortfall fixture in the battery used a directory that was
2933
+ * genuinely unmeasured, so the precondition "no declined-but-measured
2934
+ * directory exists" held across every case, and the branch where it does
2935
+ * not hold was outside the battery's reach entirely.
2936
+ */
2937
+ function measuredElsewhere(top: string): boolean {
2938
+ // TOP-LEVEL ONLY, deliberately. An earlier cut also excluded anything
2939
+ // under a `fixtures/` path at any depth, which was dead on this tree —
2940
+ // every fixture here is under `test/`, already covered by the clause
2941
+ // below — and opened a hole in a consumer's: `domain/fixtures/config.ts`
2942
+ // is real source in a directory nothing walks, and the broader rule
2943
+ // dropped it from the count silently. An exclusion that is not needed to
2944
+ // make the warning true is an exclusion that only subtracts coverage.
2945
+ return CONFIG_1_DECLINES.has(top) || top === "test" || top === "tests";
2946
+ }
2727
2947
 
2728
2948
  /** The one module allowed to read the config. ADR-002 D1. */
2729
2949
  const CONFIG_LOADER = "lib/config-loader.ts";
@@ -2739,6 +2959,19 @@ function walkSources(dir: string, rel: string, out: Array<{ path: string; text:
2739
2959
  const abs = join(dir, e.name);
2740
2960
  const relPath = rel ? `${rel}/${e.name}` : e.name;
2741
2961
  if (e.isDirectory()) {
2962
+ // NOT a test-directory skip, and not `isTestSourceFile` below. The first draft of
2963
+ // the #500 fix widened both here to match the evidence walk, and that
2964
+ // silently REDUCED enforcement: `lib/tests/sneaky.ts`, `lib/spec/y.ts`,
2965
+ // `lib/__mocks__/x.ts`, `lib/sneaky.test.js` and `lib/sneaky.spec.ts`
2966
+ // each carried a real direct config read, were counted as violations
2967
+ // before, and became silent green after — no WARN, no UNMEASURED, no
2968
+ // record, because a non-empty scan never engages the waiver.
2969
+ //
2970
+ // The invariant the waiver needs is ONE-DIRECTIONAL: the evidence walk
2971
+ // must not claim source the scan would never read. The scan reading
2972
+ // MORE than the walk is harmless — a file the scan reads makes
2973
+ // `filesScanned > 0`, and the waiver is never reached. So the walk is
2974
+ // the side that narrows, and this stays where ADR-002 D4 left it.
2742
2975
  if (e.name === "test" || e.name === "node_modules") continue;
2743
2976
  walkSources(abs, relPath, out);
2744
2977
  continue;
@@ -2774,7 +3007,7 @@ export function scanConfigAccess(root: string): ConfigAccessScan {
2774
3007
  for (const f of files) {
2775
3008
  bytesScanned += f.text.length;
2776
3009
  if (f.path === CONFIG_LOADER) continue;
2777
- const n = (stripJsComments(f.text).match(configAccessPattern()) || []).length;
3010
+ const n = classifyConfigSites(f.text).filter(site => site.kind === "use").length;
2778
3011
  if (n > 0) counts[f.path] = n;
2779
3012
  }
2780
3013
  return { counts, filesScanned: files.length, bytesScanned };
@@ -2786,6 +3019,15 @@ export function scanConfigAccess(root: string): ConfigAccessScan {
2786
3019
  * Comments are stripped and literals are NOT, which is the whole point —
2787
3020
  * `ship.js` is mostly prompt text, and the eleven sites ADR-001's check could
2788
3021
  * not see all live inside template literals handed to agents.
3022
+ *
3023
+ * **It does NOT use `classifyConfigSites`, and must not** (#415). CHECK-1's
3024
+ * subject is a path being built in code, so a sentence naming the file is
3025
+ * noise. CHECK-2's subject is the sentence: "Read ${PROJECT_ROOT}/…" IS the
3026
+ * violation, and it is prose by construction. Pointing the classifier at this
3027
+ * scan would silently empty the check — every one of its sites would reclassify
3028
+ * as a mention. `test/config-access-mentions.test.ts` SC-1552 runs one sentence
3029
+ * through both scans and asserts they disagree, so the collapse cannot be made
3030
+ * quietly in the name of consistency.
2789
3031
  */
2790
3032
  export function scanPromptConfigAccess(root: string): ConfigAccessScan {
2791
3033
  const dir = join(root, "workflows");
@@ -2858,50 +3100,846 @@ export function readConfigAccessRatchet(
2858
3100
  * this repo's defining defect and would be the most embarrassing possible
2859
3101
  * place to reproduce it (ADR-002 D4, mutation 5).
2860
3102
  */
3103
+ /**
3104
+ * A violation and the file it is about, produced together (#517).
3105
+ *
3106
+ * `file` is `""` when the violation is not about one file — the two
3107
+ * empty-scan refusals below are about the SCAN. That is the same value
3108
+ * `runConfigAccessValidation` already records for its UNMEASURED finding,
3109
+ * so there is one spelling of "no file here" rather than two.
3110
+ *
3111
+ * It used to be recovered from the message by
3112
+ * `v.split(": ")[1]?.split(" ")[0] || ""`, which reads a path out of
3113
+ * `CONFIG-1: lib/scanner.ts has 3 direct reads` correctly and reads the
3114
+ * word **`the`** out of `CONFIG-1: the scan read NO files…`. A findings
3115
+ * report renders that under a column headed `file`: it looks like a path,
3116
+ * it is a stopword, and nothing downstream could tell it from a real one.
3117
+ *
3118
+ * The defect is not the parser. It is that the violation string is the
3119
+ * HUMAN rendering and `file` is the MACHINE one, and the second was being
3120
+ * recovered from the first — by the producer, which had the fact all
3121
+ * along and threw it away by formatting it into prose. The `|| ""`
3122
+ * fallback then made "this is not about a file" and "my parse failed"
3123
+ * the same value. Producing both together removes the second case
3124
+ * entirely rather than handling it.
3125
+ */
3126
+ export interface ConfigAccessViolation {
3127
+ /**
3128
+ * The file in violation, or `""` when the violation is not about one.
3129
+ *
3130
+ * **`""` is not a one-meaning sentinel, and saying it was would be the
3131
+ * silent-default shape.** `scan.counts` keys can never be empty —
3132
+ * `walkSources` seeds every one from a scan directory and
3133
+ * `scanPromptConfigAccess` prefixes `workflows/`, so all of them contain
3134
+ * a `/`. `banked` keys CAN be: `readConfigAccessRatchet` validates only
3135
+ * that the VALUE is a number, so a ratchet carrying `{"": 2}` produces a
3136
+ * banked-but-absent violation whose `file` is `""` — a violation that IS
3137
+ * about a ratchet entry, indistinguishable here from one about the scan.
3138
+ *
3139
+ * Measured by sec-517, and not a regression: the parse this replaced
3140
+ * produced `""` there too. Recorded because the sentence it replaces
3141
+ * claimed a guarantee the code does not make.
3142
+ */
3143
+ file: string;
3144
+ message: string;
3145
+ }
3146
+
3147
+ /**
3148
+ * The string rendering, derived from the records rather than beside them.
3149
+ *
3150
+ * A pure projection, so it cannot disagree with `file`. Keeping it means
3151
+ * the fifteen existing call sites that assert on message text do not have
3152
+ * to be rewritten to prove a path field, and there is still only one
3153
+ * binding that DECIDES what a violation is.
3154
+ */
2861
3155
  export function configAccessViolations(
2862
3156
  scan: ConfigAccessScan,
2863
3157
  banked: Record<string, number>,
2864
3158
  label: string,
2865
3159
  requireNonEmpty = true,
3160
+ evidence?: SourceEvidence,
2866
3161
  ): string[] {
2867
- const out: string[] = [];
3162
+ return configAccessViolationRecords(scan, banked, label, requireNonEmpty, evidence)
3163
+ .map(v => v.message);
3164
+ }
3165
+
3166
+ /**
3167
+ * Turn a scan into refusals, as RECORDS. The one binding that decides what
3168
+ * a config-access violation is.
3169
+ *
3170
+ * Empty allows. The ratchet refuses in BOTH directions: over its number
3171
+ * fails, under its number fails, and a file absent from the ratchet is
3172
+ * allowed nothing — so a new reader fails the suite even while the total is
3173
+ * above zero, and clearing a file means deleting its entry in the same
3174
+ * commit.
3175
+ *
3176
+ * **This is the mutation target, not `configAccessViolations`.** That one
3177
+ * is now a pure projection used only by tests; short-circuiting it to
3178
+ * `return []` still scores red, but not one of those reds is a production
3179
+ * path, so the score would be unchanged and the meaning would not.
3180
+ */
3181
+ export function configAccessViolationRecords(
3182
+ scan: ConfigAccessScan,
3183
+ banked: Record<string, number>,
3184
+ label: string,
3185
+ requireNonEmpty = true,
3186
+ evidence?: SourceEvidence,
3187
+ ): ConfigAccessViolation[] {
3188
+ const out: ConfigAccessViolation[] = [];
2868
3189
  if (requireNonEmpty && scan.filesScanned === 0) {
3190
+ // Name the source that made this refusal happen. Without it the consumer
3191
+ // reads "the scan read NO files" on a project they believe has no code,
3192
+ // with nothing pointing at the file responsible — which is the difference
3193
+ // between a two-minute fix and an undiagnosable red. `SourceEvidence`
3194
+ // already collects up to three paths and its docstring has always
3195
+ // promised this; nothing read the field until now.
3196
+ const why = evidence?.found && evidence.examples.length > 0
3197
+ ? ` This project DOES contain source — ${evidence.examples.join(", ")}` +
3198
+ `${evidence.examples.length === 3 ? " (first 3)" : ""} — none of it in the ` +
3199
+ `directories this check reads, so the check is blind rather than satisfied.`
3200
+ : evidence && evidence.unreadable.length > 0
3201
+ ? ` The source walk could not read ${evidence.unreadable.join(", ")}, so ` +
3202
+ `"no code here" could not be established.`
3203
+ : "";
3204
+ // About the SCAN, not about a file. This is the violation whose
3205
+ // message begins "the scan read NO files" and whose derived path was
3206
+ // therefore the word `the`.
2869
3207
  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).`,
3208
+ {
3209
+ file: "",
3210
+ message:
3211
+ `${label}: the scan read NO files. A check that scans nothing reports ` +
3212
+ `zero violations and cannot be told from compliance — refusing rather ` +
3213
+ `than reporting clean (ADR-002 D4).${why}`,
3214
+ },
2873
3215
  ];
2874
3216
  }
2875
3217
  if (requireNonEmpty && scan.filesScanned > 0 && scan.bytesScanned === 0) {
2876
- return [`${label}: ${scan.filesScanned} files were walked and none had any content.`];
3218
+ // About the scan too — `${scan.filesScanned}` is a COUNT, and the old
3219
+ // parse reported it as a path.
3220
+ return [
3221
+ { file: "", message: `${label}: ${scan.filesScanned} files were walked and none had any content.` },
3222
+ ];
2877
3223
  }
2878
3224
 
2879
3225
  for (const [file, n] of Object.entries(scan.counts).sort()) {
2880
3226
  const allowed = banked[file] ?? 0;
2881
3227
  if (n > allowed) {
2882
- out.push(
2883
- `${label}: ${file} has ${n} direct config access site(s), ${allowed} allowed. ` +
3228
+ out.push({
3229
+ file,
3230
+ message:
3231
+ `${label}: ${file} has ${n} direct config access site(s), ${allowed} allowed. ` +
2884
3232
  `Only ${CONFIG_LOADER} may read the config (ADR-002 D1). Use ` +
2885
3233
  `loadRungateConfig / tryLoadRungateConfig / resolveConfig.`,
2886
- );
3234
+ });
2887
3235
  } else if (n < allowed) {
2888
- out.push(
2889
- `${label}: ${file} is banked at ${allowed} but only ${n} remain — lower the ` +
3236
+ out.push({
3237
+ file,
3238
+ message:
3239
+ `${label}: ${file} is banked at ${allowed} but only ${n} remain — lower the ` +
2890
3240
  `number in .claude/config-access-ratchet.json in the same commit that earned it.`,
2891
- );
3241
+ });
2892
3242
  }
2893
3243
  }
2894
3244
  for (const [file, allowed] of Object.entries(banked).sort()) {
2895
3245
  if (allowed > 0 && !(file in scan.counts)) {
2896
- out.push(
2897
- `${label}: ${file} is banked at ${allowed} but has no violations left — ` +
3246
+ out.push({
3247
+ file,
3248
+ message:
3249
+ `${label}: ${file} is banked at ${allowed} but has no violations left — ` +
2898
3250
  `remove its entry from .claude/config-access-ratchet.json.`,
2899
- );
3251
+ });
2900
3252
  }
2901
3253
  }
2902
3254
  return out;
2903
3255
  }
2904
3256
 
3257
+ /**
3258
+ * Why an empty scan is UNMEASURED rather than a refusal — or `null` when it is
3259
+ * a refusal after all (#476).
3260
+ *
3261
+ * `configAccessViolations`'s empty-scan refusal is correct and stays. What it
3262
+ * cannot do on its own is tell two situations apart, because both reach it as
3263
+ * `filesScanned === 0`:
3264
+ *
3265
+ * | Situation | Verdict |
3266
+ * |---|---|
3267
+ * | a code project whose file walk broke | **refuse** — this is what the refusal is for |
3268
+ * | a content project that has no sources of that kind | UNMEASURED, and say so |
3269
+ *
3270
+ * `--profile=minimal` (#449) exists so a project can take rungate's structure
3271
+ * without the ship harness, and the first consumer to use it — a Claude Code
3272
+ * plugin shipping a skill, a spec and two reference files, with deliberately
3273
+ * no executable surface — got a conformity suite with one permanently-red
3274
+ * check it could only satisfy by adding TypeScript it does not want.
3275
+ *
3276
+ * **Two questions, not one decider asked twice.** `scan.filesScanned` answers
3277
+ * "did I read anything"; `sourcesPresent` answers "was there anything to
3278
+ * read", over a different directory list and a different traversal
3279
+ * (`lib/typescript-project.ts`, #87's one decider for that fact). A project
3280
+ * with TypeScript the walk failed to reach still refuses, which is case 3.
3281
+ *
3282
+ * It returns a REASON, never a bare boolean: `0`, `{}`, `null` and `SKIP` are
3283
+ * all indistinguishable from success and `UNMEASURED` is not
3284
+ * (`.claude/rules/config-access.md`). A check that skips has to be able to say
3285
+ * what it skipped over.
3286
+ *
3287
+ * The waiver this replaces was `requireNonEmpty = scan.filesScanned > 0`,
3288
+ * which required a non-empty scan only when the scan was already non-empty —
3289
+ * a blanket disable wearing a conditional's clothes, so CONFIG-2's empty-scan
3290
+ * refusal had never been reachable.
3291
+ */
3292
+ /** Anything that can carry code. Deliberately WIDER than any scanner's filter. */
3293
+ const SOURCE_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;
3294
+
3295
+ /** Directories that hold code nobody wrote, or output nobody edits. */
3296
+ const SOURCE_SKIP_DIRS = new Set([
3297
+ "node_modules", ".git", "dist", "build", "coverage", ".next", ".output", "vendor",
3298
+ ]);
3299
+
3300
+ /**
3301
+ * Test directories and test files — excluded from BOTH readings, by ADR-002 D4.
3302
+ *
3303
+ * One declaration, consulted by `walkSources` (which produces the scan) and
3304
+ * by `projectSourceEvidence` (which decides whether an empty scan is
3305
+ * believable). **They have to agree.** The evidence walk asks "should the
3306
+ * scan have found something?", so a file the scan would never read is not an
3307
+ * answer to that question.
3308
+ *
3309
+ * The first draft of this fix had them disagree, and the cost was precise:
3310
+ * the scaffold writes `tests/scaffold-conformity.test.ts`, which on a
3311
+ * `--profile=minimal` content project is the ONLY code-extension file in the
3312
+ * tree. The evidence walk saw it, reported source present, and CONFIG-1
3313
+ * refused with "the scan read NO files" — on every scaffolded content
3314
+ * project, unsatisfiably, since the only ways out were adding config-reading
3315
+ * source the project does not want or deleting the suite. **The file that
3316
+ * made the evidence true was the generated suite running the check.** That is
3317
+ * #476's original complaint — a permanently-red check — arriving through the
3318
+ * fix for the fix, measured end-to-end by running the real CLI rather than
3319
+ * reasoned about.
3320
+ */
3321
+ // There is deliberately no TEST_DIRECTORY exclusion. `isTestSourceFile`
3322
+ // below is the only test-related skip, and sec-500 established that the
3323
+ // directory form was never needed: the scaffold writes exactly one file
3324
+ // into a test directory (`test/scaffold-conformity.test.ts`, the whole of
3325
+ // sec-476's B1), and the filename predicate already matches it.
3326
+ //
3327
+ // The case the directory skip was defending — `tests/helpers/setup.ts`, a
3328
+ // non-test file in a test directory — described a project that cannot
3329
+ // exist in the state where it would matter. The waiver is only reached
3330
+ // when a project has NO production source, and a project with test
3331
+ // helpers has production source, so `filesScanned > 0` and the waiver is
3332
+ // never consulted. Meanwhile the skip cost a real hole: a non-test file
3333
+ // in `tests/` carrying a live `join(process.cwd(), ".claude", ...)` was
3334
+ // waived.
3335
+ export function isTestSourceFile(name: string): boolean {
3336
+ return /\.(test|spec)\.[cm]?[jt]sx?$/.test(name);
3337
+ }
3338
+
3339
+ /**
3340
+ * Tool configuration at the project root is not the project's source.
3341
+ *
3342
+ * `prettier.config.js`, `vite.config.ts`, `jest.config.js`. A policy call,
3343
+ * and it is the one place this walk is deliberately narrower than "any file
3344
+ * with a code extension", so the reasoning is written down rather than
3345
+ * implied:
3346
+ *
3347
+ * The question is "should the scan have read something?" — and the cost of
3348
+ * the two wrong answers is wildly asymmetric. Answering yes wrongly gives
3349
+ * every content project with a prettier config a permanently red, literally
3350
+ * unsatisfiable CONFIG-1, which is the defect #476 was filed about. Answering
3351
+ * no wrongly waives a project whose only direct rungate-config read is inside
3352
+ * a build tool's config file, which is not a thing that happens — these files
3353
+ * configure the tool that loads them and nothing else reads them.
3354
+ *
3355
+ * Root level only. A `src/app.config.ts` is ordinary source and is counted.
3356
+ */
3357
+ function isRootToolConfig(rel: string, name: string): boolean {
3358
+ return !rel.includes("/") && /\.config\.[cm]?[jt]s$/.test(name);
3359
+ }
3360
+
3361
+ /**
3362
+ * Whether this project contains code at all, and whether the answer is
3363
+ * trustworthy (#476 follow-up).
3364
+ *
3365
+ * `found` is deliberately BROADER than what any individual check scans —
3366
+ * every code extension, every directory, the whole tree. That direction is
3367
+ * the whole point. The question it answers is "is this a project with code
3368
+ * in it", and a narrower answer turns a blind check into a clean one.
3369
+ *
3370
+ * `unreadable` exists because "there is no code" and "I could not look" are
3371
+ * different facts that a swallowed `readdirSync` makes identical. Before the
3372
+ * waiver existed, swallowing was harmless: a failed walk left `filesScanned`
3373
+ * at zero and the refusal fired. With a waiver reading the same silence, two
3374
+ * fail-opens point the same way and a chmod turns a FAIL into a green run.
3375
+ */
3376
+ export interface SourceEvidence {
3377
+ /** The project contains at least one source file somewhere. */
3378
+ found: boolean;
3379
+ /** Up to three paths, so a refusal can name what went unscanned. */
3380
+ examples: string[];
3381
+ /** Directories the walk could not read. Non-empty means `found` is unreliable. */
3382
+ unreadable: string[];
3383
+ /**
3384
+ * Entries the walk DECLINED to look at, and why.
3385
+ *
3386
+ * The third state, and #500's own complaint turned on itself. With only
3387
+ * `found` and `unreadable`, a declined entry is indistinguishable from an
3388
+ * absent one, and the waiver went on to assert "no source files of any
3389
+ * kind were found anywhere in the tree" — a sentence the walk never
3390
+ * established and which is FALSE for every skip class below. "True
3391
+ * sentence, wrong inference" was this issue's headline; this was the
3392
+ * sentence becoming untrue.
3393
+ *
3394
+ * Recorded rather than fixed by widening, because most of the skips are
3395
+ * correct: a content project with a `.github/` release script really does
3396
+ * have no project source. What is not correct is saying nothing is there.
3397
+ */
3398
+ skipped: string[];
3399
+ /**
3400
+ * Every file the walk counted as project source, not just the first three
3401
+ * (#492).
3402
+ *
3403
+ * `examples` is capped at 3 because a refusal that names four hundred
3404
+ * files is not a message. A COUNT is a different thing and the check
3405
+ * needs both: "CONFIG-1 read 36 files" is uninterpretable on its own.
3406
+ *
3407
+ * It counts ONLY source outside `CONFIG_SCAN_DIRS`, and deliberately does
3408
+ * not try to be a denominator for `filesScanned`. The two walks do not
3409
+ * agree about what source is inside a scanned directory and are not
3410
+ * supposed to: `walkSources` reads `lib/x.test.ts`, `lib/types.d.ts` and
3411
+ * `lib/tests/sneaky.ts`, all of which this walk declines, because the
3412
+ * comment on `walkSources` explains that narrowing the SCAN to match the
3413
+ * walk silently reduced enforcement. So `sourceCount - filesScanned`
3414
+ * would be a subtraction across two definitions, and could go negative.
3415
+ * One number, one walk, no arithmetic between them.
3416
+ */
3417
+ unscannedSourceCount: number;
3418
+ /**
3419
+ * Top-level directories holding source that `CONFIG_SCAN_DIRS` does not
3420
+ * walk — `"."` for a source file at the root (#492).
3421
+ *
3422
+ * This is the half of #492 that survives the fix. Adding `src/` to the
3423
+ * scan list closes the instance; this closes the CLASS, because the defect
3424
+ * is that a hardcoded list can be wrong and nothing notices. A consumer
3425
+ * who keeps their code in `domain/`, `packages/`, `app/` or `internal/`
3426
+ * gets told which directory went unread instead of a PASS that means
3427
+ * "clean in the five places I happened to look".
3428
+ */
3429
+ unscannedDirs: string[];
3430
+ }
3431
+
3432
+ /**
3433
+ * Directories that can never hold the project's own source, so a decline is
3434
+ * not worth recording. `.git` and `node_modules` are the whole list, and
3435
+ * both were cluttering the waiver message with facts true of every repo.
3436
+ */
3437
+ const NEVER_PROJECT_SOURCE = new Set([".git", "node_modules"]);
3438
+
3439
+ /**
3440
+ * Whether a DECLINED entry is a directory — for the label, and only for the
3441
+ * label (#518).
3442
+ *
3443
+ * The three decline-by-name branches below matched a name and then wrote
3444
+ * `${rel}/` with a directory-shaped label without asking. Measured before
3445
+ * the fix: 8 of this repo's 369 declines and **5 of a consumer's 13** named
3446
+ * a directory that does not exist, including four `.DS_Store/`. `.git` is
3447
+ * the one worth naming — in a worktree it is a gitfile, so that branch was
3448
+ * wrong in every worktree this project develops in.
3449
+ *
3450
+ * It is a `statSync` and not `e.isDirectory()` because `Dirent.isDirectory()`
3451
+ * is false for a symlink, and a symlinked `node_modules` is the ordinary
3452
+ * pnpm / npm-workspace shape — the cheap predicate gets the commonest real
3453
+ * instance backwards.
3454
+ *
3455
+ * **A failed stat answers "not a directory" rather than reaching the
3456
+ * verdict, and that is deliberate.** These entries are declined BY NAME and
3457
+ * were declined before this function existed; nothing here may change
3458
+ * WHETHER they are declined. If a throw pushed `unreadable`, a
3459
+ * `.hidden -> /locked/dir` would refuse CONFIG-1 for a whole project over an
3460
+ * entry the walk discards as tooling either way — the over-refusal the
3461
+ * dangling-symlink note further down already rules out for the same reason.
3462
+ * A link that resolves to nothing is not somewhere a reader can go looking,
3463
+ * which is the only thing the trailing slash claims.
3464
+ */
3465
+ function declinedIsDir(e: Dirent, abs: string): boolean {
3466
+ if (e.isDirectory()) return true;
3467
+ if (!e.isSymbolicLink()) return false;
3468
+ try {
3469
+ return statSync(abs).isDirectory();
3470
+ } catch {
3471
+ return false;
3472
+ }
3473
+ }
3474
+
3475
+ /**
3476
+ * Scripts the config scan cannot read but a project can absolutely be built
3477
+ * from. A `lib/loader.py` or a `hooks/run.sh` doing a direct config read is
3478
+ * invisible to `SOURCE_EXTENSIONS` and therefore to CONFIG-1 — which is a
3479
+ * defensible limit for a TypeScript check, and an indefensible silence.
3480
+ */
3481
+ const SCRIPT_LIKE = /\.(py|rb|sh|bash|zsh|fish|pl|php|lua|r|go|rs|java|kt|swift|ex|exs)$/i;
3482
+
3483
+ export function projectSourceEvidence(root: string): SourceEvidence {
3484
+ const examples: string[] = [];
3485
+ // #492: the COUNT and the WHERE, alongside the capped sample.
3486
+ let unscannedSourceCount = 0;
3487
+ const unscannedDirs = new Set<string>();
3488
+ const unreadable: string[] = [];
3489
+ const skipped: string[] = [];
3490
+ // Symlinked source directories ARE followed — `packages/core` behind
3491
+ // `lib/impl` is an ordinary monorepo shape, and a predicate that cannot see
3492
+ // it waives a project full of code. `realpathSync` keys the visited set so
3493
+ // a cycle terminates instead of hanging.
3494
+ const seen = new Set<string>();
3495
+ const stack: Array<[string, string]> = [[root, ""]];
3496
+ // The walk may not leave the project. A symlink to `$HOME` or `/` would
3497
+ // otherwise make `found` true because of code that is not in this project,
3498
+ // and walk the whole of it to decide that.
3499
+ let rootReal: string;
3500
+ try {
3501
+ rootReal = realpathSync(root);
3502
+ } catch {
3503
+ return {
3504
+ found: false, examples: [], unreadable: ["."], skipped: [],
3505
+ unscannedSourceCount: 0, unscannedDirs: [],
3506
+ };
3507
+ }
3508
+ const insideProject = (p: string) => p === rootReal || p.startsWith(rootReal + sep);
3509
+
3510
+ while (stack.length > 0) {
3511
+ const [dir, rel] = stack.pop()!;
3512
+ let real: string;
3513
+ try {
3514
+ real = realpathSync(dir);
3515
+ } catch {
3516
+ unreadable.push(rel || ".");
3517
+ continue;
3518
+ }
3519
+ if (!insideProject(real)) {
3520
+ if (rel) skipped.push(`${rel}/ (directory resolving outside the project)`);
3521
+ continue;
3522
+ }
3523
+ if (seen.has(real)) continue;
3524
+ seen.add(real);
3525
+
3526
+ let entries;
3527
+ try {
3528
+ entries = readdirSync(dir, { withFileTypes: true });
3529
+ } catch {
3530
+ unreadable.push(rel || ".");
3531
+ continue;
3532
+ }
3533
+ for (const e of entries) {
3534
+ const childRelEarly = rel ? `${rel}/${e.name}` : e.name;
3535
+ // RECORDED, not dropped. An earlier cut skipped `.git` and
3536
+ // `node_modules` entirely on the grounds that they can never hold the
3537
+ // project's own source — true, and still the wrong move, because
3538
+ // "I declined 400 entries under node_modules/" is honest and short
3539
+ // while silence is neither (sec-485). They collapse to one counted
3540
+ // line in the message, which gets the brevity without the silence.
3541
+ // The trailing slash is a claim about the entry, so it is asked
3542
+ // rather than assumed (#518). `.git` in a worktree is a gitfile.
3543
+ const dirSlash = () => (declinedIsDir(e, join(dir, e.name)) ? "/" : "");
3544
+ if (NEVER_PROJECT_SOURCE.has(e.name)) {
3545
+ skipped.push(`${childRelEarly}${dirSlash()} (dependency or VCS metadata)`);
3546
+ continue;
3547
+ }
3548
+ // Recorded whether or not it holds anything, and that is deliberate.
3549
+ // An earlier cut ran a bounded recursive walk here and recorded the
3550
+ // decline only for directories that turned out to contain source,
3551
+ // on the grounds that an empty `dist/` is not a fact about this
3552
+ // project. sec-485 took it apart and was right: this field is a log
3553
+ // of DECISIONS, and the walk declined either way. Measured against
3554
+ // the implementation — one tree, one set of decisions, `dist/` empty
3555
+ // and then holding a build artifact — the predicate made the evidence
3556
+ // record differ between the two, so a reader auditing a waiver saw a
3557
+ // different list depending on whether CI had run. A tracked-but-empty
3558
+ // `dist/` on a clean checkout is the live shape of that, not a
3559
+ // contrived one.
3560
+ //
3561
+ // What it cost to keep: a recursive walk inside the directories this
3562
+ // function exists specifically not to walk, build-state-dependent
3563
+ // evidence, and a second predicate to keep correct forever. What it
3564
+ // bought, once the message collapses by class: one name inside a
3565
+ // capped sample and one off a count. `test/config-access-conformity
3566
+ // .test.ts`'s "function of the DECISIONS" case holds this line.
3567
+ if (SOURCE_SKIP_DIRS.has(e.name)) {
3568
+ skipped.push(`${childRelEarly}${dirSlash()} (build output or dependency)`);
3569
+ continue;
3570
+ }
3571
+ // Tooling lives in dot-directories — `.github/scripts/release.js`,
3572
+ // `.husky/`, `.claude/`. `containsTypeScript` skipped every entry
3573
+ // starting with "." and this walk replaced it, so dropping that was a
3574
+ // silent widening: a release script is not the project's source, and a
3575
+ // content project that has one is not a project CONFIG-1 can measure.
3576
+ if (e.name.startsWith(".")) {
3577
+ // The only one of the three that needed a second LABEL and not just
3578
+ // a conditional slash, because this label names the kind out loud.
3579
+ // A `.DS_Store` reported as `.DS_Store/ (dot-directory, tooling)`
3580
+ // sends an auditor looking for a directory that is not there, and
3581
+ // auditing the waiver is the entire reason this list exists.
3582
+ skipped.push(
3583
+ declinedIsDir(e, join(dir, e.name))
3584
+ ? `${childRelEarly}/ (dot-directory, tooling)`
3585
+ : `${childRelEarly} (dot-file, tooling)`,
3586
+ );
3587
+ continue;
3588
+ }
3589
+ const childRel = childRelEarly;
3590
+ const abs = join(dir, e.name);
3591
+ // `isDirectory()` is false for a symlink, so the stat is what makes a
3592
+ // symlinked directory visible at all.
3593
+ let isDir = e.isDirectory();
3594
+ if (!isDir && e.isSymbolicLink()) {
3595
+ try {
3596
+ isDir = statSync(abs).isDirectory();
3597
+ } catch (err) {
3598
+ // A DANGLING symlink is not unmeasured — it is empty. It resolves
3599
+ // to nothing, so it cannot be hiding source, and counting it would
3600
+ // mean one broken link anywhere in a content project refuses
3601
+ // CONFIG-1 for the rest of the project's life. `unreadable` exists
3602
+ // for the case where source might be behind something we could not
3603
+ // open; that is a permission error, not a link to a file that does
3604
+ // not exist.
3605
+ //
3606
+ // The distinction is the ERRNO, not `existsSync`. The first draft
3607
+ // asked `existsSync(abs)`, which returns false for BOTH — so
3608
+ // `vendored -> /locked/inner`, with `/locked` at mode 000 and a
3609
+ // real config read inside, gave found=false, unreadable=[] and a
3610
+ // clean UNMEASURED. The code was invisible AND the walk did not
3611
+ // record that it could not look, which is the exact failure the
3612
+ // `unreadable` guard exists to prevent, reintroduced inside the
3613
+ // guard itself.
3614
+ if ((err as NodeJS.ErrnoException).code !== "ENOENT") unreadable.push(childRel);
3615
+ continue;
3616
+ }
3617
+ }
3618
+ if (isDir) {
3619
+ stack.push([abs, childRel]);
3620
+ } else if (!SOURCE_EXTENSIONS.test(e.name) && SCRIPT_LIKE.test(e.name)) {
3621
+ // Code in a language this check cannot read. sec-500's point, and
3622
+ // the reason keying on "extension-less" would have been too narrow:
3623
+ // a project whose only config-reading code is `lib/loader.py` or
3624
+ // `bin/run.sh` got `skipped: []` and the fallback sentence "the walk
3625
+ // found no files of any kind that it counts as source" — which is
3626
+ // LITERALLY TRUE, and that is exactly what would have let it outlive
3627
+ // the fix. Anywhere in the tree, not just the scan dirs, because
3628
+ // `bin/` is not a scan dir and `bin/run.sh` was the example.
3629
+ skipped.push(`${childRel} (${e.name.slice(e.name.lastIndexOf("."))} — not a language this check reads)`);
3630
+ } else if (
3631
+ !SOURCE_EXTENSIONS.test(e.name)
3632
+ && !e.name.includes(".")
3633
+ && CONFIG_SCAN_DIRS.some(d => childRel === d || childRel.startsWith(`${d}/`))
3634
+ ) {
3635
+ // An extension-less executable INSIDE a directory this check scans.
3636
+ // sec-500's sharpest case, and not hypothetical: this repo ships two
3637
+ // of them (`scripts/git-hooks/pre-commit`, `scripts/git-hooks/pre-push`).
3638
+ // A node or shell script with no extension reading the config is
3639
+ // invisible to `SOURCE_EXTENSIONS`, so the project reads as having no
3640
+ // code while carrying a live direct read in a scanned directory.
3641
+ //
3642
+ // Recorded, not counted: deciding these are source would make every
3643
+ // git hook, `Makefile` and CI shim project source, which is a much
3644
+ // larger change than this issue. Naming it is what stops the next
3645
+ // reader having to rediscover it.
3646
+ skipped.push(`${childRel} (extension-less file in a scanned directory)`);
3647
+ } else if (SOURCE_EXTENSIONS.test(e.name) && e.name.endsWith(".d.ts")) {
3648
+ skipped.push(`${childRel} (type declarations)`);
3649
+ } else if (SOURCE_EXTENSIONS.test(e.name) && isTestSourceFile(e.name)) {
3650
+ skipped.push(`${childRel} (test file)`);
3651
+ } else if (SOURCE_EXTENSIONS.test(e.name) && isRootToolConfig(childRel, e.name)) {
3652
+ skipped.push(`${childRel} (root tool config)`);
3653
+ } else if (SOURCE_EXTENSIONS.test(e.name)) {
3654
+ // The three exclusions that used to be repeated here —
3655
+ // `!endsWith(".d.ts")`, `!isTestSourceFile`, `!isRootToolConfig` —
3656
+ // are GONE, and their absence is the point. The `else if` chain
3657
+ // above already consumes each of those files to record the decline,
3658
+ // so re-asking here could never change the outcome: mutating any of
3659
+ // the three was 0 red against a prediction of 3, and the three
3660
+ // branches above were holding all of it up.
3661
+ //
3662
+ // Three collapsed pairs, introduced by the commit that added the
3663
+ // recording and caught by the battery rather than by reading. The
3664
+ // rubric offers two fixes and this is the first one — delete a
3665
+ // decider, do not feed it — because the recording branch has to
3666
+ // exist anyway and a second copy of its question cannot ever
3667
+ // disagree with it.
3668
+ // A symlinked FILE is containment-checked too. The directory check
3669
+ // above cannot see this case, so `linked.ts -> /outside/x.ts` made
3670
+ // `found` true on the strength of code outside the project — which
3671
+ // contradicts the invariant the directory check exists to state.
3672
+ // Checked here rather than assumed, because "the walk cannot leave
3673
+ // the project" is either true of both kinds of entry or it is not a
3674
+ // property at all.
3675
+ if (e.isSymbolicLink()) {
3676
+ try {
3677
+ if (!insideProject(realpathSync(abs))) {
3678
+ // Recorded. "I chose not to look" was rendering identically to
3679
+ // "there was nothing there", which is the distinction
3680
+ // `unreadable` exists to preserve — and a pnpm/npm-workspace
3681
+ // monorepo with `lib/impl -> ../../packages/core` is an
3682
+ // ordinary shape, not an attack. The containment decision is
3683
+ // right; the silence was not.
3684
+ skipped.push(`${childRel} (symlink pointing outside the project)`);
3685
+ continue;
3686
+ }
3687
+ } catch {
3688
+ continue;
3689
+ }
3690
+ }
3691
+ // The top-level segment, because CONFIG_SCAN_DIRS is matched at
3692
+ // the top level. `.` is a source file sitting at the root, which
3693
+ // the scan does not walk either — `index.ts` is an ordinary shape
3694
+ // and leaving it out would be the same blind spot one level up.
3695
+ const top = childRel.includes("/") ? childRel.slice(0, childRel.indexOf("/")) : ".";
3696
+ if (!CONFIG_SCAN_DIRS.includes(top) && !measuredElsewhere(top)) {
3697
+ unscannedDirs.add(top);
3698
+ unscannedSourceCount++;
3699
+ }
3700
+ if (examples.length < 3) examples.push(childRel);
3701
+ }
3702
+ }
3703
+ }
3704
+ // Ranked, then alphabetical. `readdir` order is neither, so WHICH entries
3705
+ // survived the message's truncation differed per machine and per tree —
3706
+ // sec-500's point that a consumer and CI could be shown different lists,
3707
+ // which makes the message unciteable in a bug report. Ranking also puts
3708
+ // the classes that can plausibly hold first-party code above the ones
3709
+ // that cannot, so the truncation cuts the least useful entries first
3710
+ // rather than arbitrary ones.
3711
+ const rank = (entry: string) =>
3712
+ /\((?:symlink|directory resolving)/.test(entry) ? 0 // escaped the project
3713
+ : /\(extension-less|not a language this check reads/.test(entry) ? 1 // code, unparseable
3714
+ // `(?:\/|\s)` and not `\/`, because this fix removes the trailing
3715
+ // slash from a declined FILE and the slash was load-bearing here —
3716
+ // sec-518's F3. A file named `build` or `vendor` silently dropped
3717
+ // from rank 2 to rank 5, which is a second behavioural change riding
3718
+ // inside the first. Measured on one tree carrying both as files:
3719
+ // before `["build/", "vendor/", ".alpha/", "dist/"]`, after
3720
+ // `[".alpha/", "build", "dist/", "vendor"]`. Rank 2 is the right
3721
+ // answer for both spellings — the class is "generated from source",
3722
+ // and a build manifest is as generated as a build directory.
3723
+ : /^(?:build|vendor)(?:\/|\s)/.test(entry) ? 2 // generated-from-source
3724
+ : /\(dot-directory/.test(entry) ? 3 // tooling, can hold scripts
3725
+ : /\(test (?:file|directory)/.test(entry) ? 4
3726
+ : 5; // dist, coverage, .d.ts, and dot-FILES (#518):
3727
+ // `.github/` can hide a release script, which is
3728
+ // why it ranks 3. `.gitignore` cannot hide
3729
+ // anything, so the new class falls to the
3730
+ // default on purpose and the truncation cuts it
3731
+ // before anything that could hold code.
3732
+ skipped.sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
3733
+ return {
3734
+ found: examples.length > 0,
3735
+ examples,
3736
+ unreadable,
3737
+ skipped,
3738
+ unscannedSourceCount,
3739
+ unscannedDirs: [...unscannedDirs].sort(),
3740
+ };
3741
+ }
3742
+
3743
+ /**
3744
+ * Why an empty scan is UNMEASURED rather than a refusal — or `null` when it is
3745
+ * a refusal after all (#476).
3746
+ *
3747
+ * THREE conditions, not two, and the second and third were both missing from
3748
+ * the first version of this. A security review found five project layouts
3749
+ * carrying a real direct config read that flipped from FAIL to green:
3750
+ * `lib/loader.mjs`, `lib/loader.cjs`, `src/app.js`, `bin/cli.ts` and a
3751
+ * root-level `index.ts`. The waiver asked `isTypeScriptProject`, which
3752
+ * matches `.tsx?` under `TS_SOURCE_DIRS`, while the scan reads `.ts` AND
3753
+ * `.js` under a different list — so wherever the scan's reach exceeded the
3754
+ * predicate's, a blind check reported clean. `lib/loader.mjs` is the
3755
+ * sharpest: the file sits in the FIRST directory CONFIG-1 walks, and the
3756
+ * waiver told the consumer the project had no TypeScript. True sentence,
3757
+ * wrong inference.
3758
+ *
3759
+ * The replacement cannot have that defect by construction: `found` is
3760
+ * answered over every code extension in the whole tree, so it can never be
3761
+ * narrower than a scanner's filter. Widening a scanner later cannot open a
3762
+ * hole in it.
3763
+ */
3764
+ /**
3765
+ * Collapse the decline list by class, with a count and a capped sample.
3766
+ *
3767
+ * The first cut printed the first eight entries and ", and N more". On
3768
+ * rungate itself the list is 320 entries of which 310 are test files, so
3769
+ * the cap showed ten test files and hid everything else — including the two
3770
+ * extension-less scripts in scanned directories, which are the entries most
3771
+ * likely to explain a waiver and the ones sec-500 filed the issue about.
3772
+ *
3773
+ * Collapsing rather than dropping is sec-485's correction to my first
3774
+ * remedy, and it is the better shape for the reason that applies to this
3775
+ * whole field: **every decline stays distinguishable from an absence**, and
3776
+ * the reader still gets a message they can read. Dropping entries to shorten
3777
+ * the list reintroduces exactly the silence `skipped` exists to remove.
3778
+ *
3779
+ * The class is the parenthetical each decline already carries, and ordering
3780
+ * follows the ranked array, so the classes that can plausibly hold
3781
+ * first-party code come first.
3782
+ */
3783
+ function summariseDeclines(skipped: string[], sample = 3): string {
3784
+ const order: string[] = [];
3785
+ const byClass = new Map<string, string[]>();
3786
+ for (const entry of skipped) {
3787
+ const m = /^(.*) \(([^()]*)\)$/.exec(entry);
3788
+ const kind = m ? m[2] : "other";
3789
+ const path = m ? m[1] : entry;
3790
+ if (!byClass.has(kind)) {
3791
+ byClass.set(kind, []);
3792
+ order.push(kind);
3793
+ }
3794
+ byClass.get(kind)!.push(path);
3795
+ }
3796
+ return order
3797
+ .map(kind => {
3798
+ const paths = byClass.get(kind)!;
3799
+ const shown = paths.slice(0, sample).join(", ");
3800
+ // `kind: N (samples)` rather than `N kinds (samples)`. Pluralising
3801
+ // the class prose correctly means handling "test file" -> "test
3802
+ // files" but "dot-directory, tooling" -> "dot-directories, tooling"
3803
+ // and "type declarations" -> unchanged, and a regex that gets that
3804
+ // wrong prints "40 tests file" — which it did. Putting the count
3805
+ // after the label sidesteps the whole problem and reads better in a
3806
+ // list.
3807
+ return `${kind}: ${paths.length}` + (paths.length > sample ? ` (${shown}, …)` : ` (${shown})`);
3808
+ })
3809
+ .join("; ");
3810
+ }
3811
+
3812
+ /**
3813
+ * What CONFIG-1 did not read, when it read something (#492).
3814
+ *
3815
+ * `null` when the scan covered every source file the walk found — the
3816
+ * normal case, which must stay silent or the message becomes one more line
3817
+ * nobody reads.
3818
+ *
3819
+ * ## Why this exists on top of adding `src/` to the scan list
3820
+ *
3821
+ * Adding `src/` fixes the INSTANCE. This fixes the class, and the class is
3822
+ * what #492 is actually about: a hardcoded list of directories can be
3823
+ * wrong, and until now nothing noticed. A consumer who keeps their code in
3824
+ * `domain/`, `packages/`, `app/` or `internal/` would have hit the
3825
+ * identical defect the week after `src/` was added, and the only signal
3826
+ * would have been a PASS.
3827
+ *
3828
+ * The regression fixture uses a directory named `domain` for exactly that
3829
+ * reason — a name no list will ever contain, so the case cannot be
3830
+ * satisfied by extending the list. That is the fifth failure shape (#519)
3831
+ * applied in advance: the wrong fix here is "add src and move on", and it
3832
+ * is the cheap one.
3833
+ *
3834
+ * ## Why it reports both numbers
3835
+ *
3836
+ * "CONFIG-1 read 36 files" is uninterpretable. 36 of 426 is the finding.
3837
+ * The directory names are what make it actionable — without them a consumer
3838
+ * knows the check is partial and has nowhere to go.
3839
+ */
3840
+ export function coverageShortfall(scan: ConfigAccessScan, evidence: SourceEvidence): string | null {
3841
+ // Both guards are `=== 0`, and both are load-bearing at exactly that
3842
+ // point. ONE unread file is a shortfall and ONE scanned file is a scan,
3843
+ // and `test/config-access-conformity.test.ts` pins both boundaries —
3844
+ // because a threshold is the cheapest way to make this quiet.
3845
+ //
3846
+ // `unread < 20` is not hypothetical: before `measuredElsewhere` existed
3847
+ // this warning named 19 files on rungate's own tree, so 20 is precisely
3848
+ // the number someone reaches for to silence it. And `bytesScanned < 10`
3849
+ // in place of the file guard re-opens the one-byte hole recorded in
3850
+ // `.claude/rules/checks-must-be-able-to-fail.md`, one guard over from
3851
+ // where that entry already closed it. Both measured at 0 red before the
3852
+ // boundary cases were added (sec-492).
3853
+ if (scan.filesScanned === 0) return null; // the empty-scan refusal owns this case
3854
+ const unread = evidence.unscannedSourceCount;
3855
+ if (unread === 0) return null;
3856
+ const where = evidence.unscannedDirs.map(d => (d === "." ? "the project root" : `${d}/`)).join(", ");
3857
+ return (
3858
+ `UNMEASURED: CONFIG-1 read ${scan.filesScanned} file(s), and ${unread} more source ` +
3859
+ `file(s) live in directories it does not walk — ${where} — so a direct config read ` +
3860
+ `there is invisible to it. A PASS here means "clean in ` +
3861
+ `${CONFIG_SCAN_DIRS.map(d => `${d}/`).join(", ")}", not "clean". ` +
3862
+ `Nothing is necessarily wrong with this project; the check is partial, and a partial ` +
3863
+ `check reporting a clean result is indistinguishable from a complete one (ADR-002 D4).`
3864
+ );
3865
+ }
3866
+
3867
+ export function unmeasuredScanReason(
3868
+ scan: ConfigAccessScan,
3869
+ evidence: SourceEvidence,
3870
+ label: string,
3871
+ sourceKind: string,
3872
+ ): string | null {
3873
+ // Something was read, so the check measured. Asked first: a non-empty scan
3874
+ // is never waived no matter what else is true.
3875
+ if (scan.filesScanned > 0) return null;
3876
+ // The walk could not complete. "No code here" and "I could not look" are
3877
+ // the same silence, and only one of them is a reason to waive.
3878
+ if (evidence.unreadable.length > 0) return null;
3879
+ // There IS code and this check read none of it. That is a blind check, the
3880
+ // first row of the table above, and it must refuse.
3881
+ if (evidence.found) return null;
3882
+ // What the walk ACTUALLY established, which is narrower than "nothing is
3883
+ // there". It looked outside the scan dirs, found no source it counts, and
3884
+ // declined to look at these. Naming the declines is the whole fix: the
3885
+ // previous sentence asserted "no source files of any kind were found
3886
+ // anywhere in the tree", which is false for every skip class and is this
3887
+ // issue's own headline complaint — a true-sounding sentence the walk never
3888
+ // established — reintroduced in the waiver that #500 added.
3889
+ const declined =
3890
+ evidence.skipped.length > 0
3891
+ ? ` It declined ${evidence.skipped.length} entr${evidence.skipped.length === 1 ? "y" : "ies"}: ` +
3892
+ summariseDeclines(evidence.skipped) +
3893
+ `. So this is "no source this check counts", not "no files here".`
3894
+ : ` The walk found no files of any kind that it counts as source.`;
3895
+ return (
3896
+ `UNMEASURED: ${label} read no files because this project has no ${sourceKind}.` +
3897
+ `${declined} ` +
3898
+ `Nothing was checked, which is NOT the same as nothing being wrong — if this ` +
3899
+ `project grows ${sourceKind}, this check starts measuring again on the next run.`
3900
+ );
3901
+ }
3902
+
3903
+ /**
3904
+ * SUCCESS-1 — the project states what it is for, falsifiably (#485).
3905
+ *
3906
+ * `CLAUDE.md` calls `SUCCESS.md` the measure and the scaffold never wrote
3907
+ * one, so `specs/HARNESS-STANDARD.md` carried SC-822..824 asserting
3908
+ * properties of a file that did not exist in any consumer.
3909
+ *
3910
+ * Absent is UNMEASURED and present-but-unfilled is a REFUSAL, and the
3911
+ * asymmetry is the point: a project that never opted in has not failed at
3912
+ * anything, while a project that ran the generator and stopped has a
3913
+ * document that every "does it exist" check waves through. The second is
3914
+ * the case this check is for.
3915
+ */
3916
+ export function runSuccessDocValidation(root: string) {
3917
+ describe("SUCCESS.md (#485)", () => {
3918
+ test("SUCCESS-1: the project states what it is for, and how each claim fails", () => {
3919
+ const verdict = successViolations(readSuccessDoc(root), readSuccessTemplate());
3920
+ if (verdict.unmeasured) {
3921
+ addFinding({
3922
+ ruleId: "SUCCESS-1",
3923
+ severity: "WARN",
3924
+ file: "SUCCESS.md",
3925
+ message: verdict.unmeasured,
3926
+ });
3927
+ return;
3928
+ }
3929
+ for (const v of verdict.violations) {
3930
+ addFinding({
3931
+ ruleId: "SUCCESS-1",
3932
+ severity: "FAIL",
3933
+ file: "SUCCESS.md",
3934
+ message: v,
3935
+ fixCommand: "Fill in SUCCESS.md — see bunx rungate create-success",
3936
+ });
3937
+ }
3938
+ expect(verdict.violations, verdict.violations.join("\n")).toEqual([]);
3939
+ });
3940
+ });
3941
+ }
3942
+
2905
3943
  /**
2906
3944
  * CHECK-1 — direct config access in TypeScript sources (ADR-002 D4).
2907
3945
  *
@@ -2912,21 +3950,57 @@ export function runConfigAccessValidation(root: string) {
2912
3950
  describe("Config access (ADR-002 D1)", () => {
2913
3951
  test("CONFIG-1: only the loader reads the rungate config", () => {
2914
3952
  const scan = scanConfigAccess(root);
2915
- const violations = configAccessViolations(
3953
+ const evidence = projectSourceEvidence(root);
3954
+ const unmeasured = unmeasuredScanReason(
3955
+ scan,
3956
+ evidence,
3957
+ "CONFIG-1",
3958
+ `TypeScript or JavaScript in ${CONFIG_SCAN_DIRS.map(d => `${d}/`).join(", ")}`,
3959
+ );
3960
+ if (unmeasured) {
3961
+ addFinding({
3962
+ ruleId: "CONFIG-1",
3963
+ severity: "WARN",
3964
+ file: "",
3965
+ message: unmeasured,
3966
+ });
3967
+ return;
3968
+ }
3969
+ // #492: the scan read SOME files, and that is where nothing was
3970
+ // looking. Every guard above — the waiver, the source walk, the
3971
+ // decline list — is reached only when `filesScanned === 0`, so ONE
3972
+ // clean file in a scanned directory makes the whole apparatus
3973
+ // unreachable. Measured on one consumer: PASS, having read 36 of 426
3974
+ // TypeScript files, because `scripts/` is non-empty and the 390 files
3975
+ // in `src/` were never walked.
3976
+ //
3977
+ // Recorded rather than failed. The consumer has done nothing wrong —
3978
+ // their layout is ordinary and it is this check that cannot see it —
3979
+ // and a FAIL they cannot act on is a FAIL they will switch off. But
3980
+ // `0`, `{}`, `null` and `SKIP` are indistinguishable from success and
3981
+ // so is a PASS over 8% of a tree, which is why it is not silence.
3982
+ const shortfall = coverageShortfall(scan, evidence);
3983
+ if (shortfall) {
3984
+ addFinding({ ruleId: "CONFIG-1", severity: "WARN", file: "", message: shortfall });
3985
+ }
3986
+ const violations = configAccessViolationRecords(
2916
3987
  scan,
2917
3988
  readConfigAccessRatchet(root, "sources"),
2918
3989
  "CONFIG-1",
3990
+ true,
3991
+ evidence,
2919
3992
  );
2920
3993
  for (const v of violations) {
2921
3994
  addFinding({
2922
3995
  ruleId: "CONFIG-1",
2923
3996
  severity: "FAIL",
2924
- file: v.split(": ")[1]?.split(" ")[0] || "",
2925
- message: v,
3997
+ file: v.file,
3998
+ message: v.message,
2926
3999
  fixCommand: "Route the read through lib/config-loader.ts",
2927
4000
  });
2928
4001
  }
2929
- expect(violations, violations.join("\n")).toEqual([]);
4002
+ const messages = violations.map(v => v.message);
4003
+ expect(messages, messages.join("\n")).toEqual([]);
2930
4004
  });
2931
4005
  });
2932
4006
  }
@@ -2942,24 +4016,41 @@ export function runPromptConfigAccessValidation(root: string) {
2942
4016
  describe("Config access in workflows (ADR-002 D4)", () => {
2943
4017
  test("CONFIG-2: no workflow reaches the rungate config, prompts included", () => {
2944
4018
  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(
4019
+ // A project with no workflows/ directory is not in violation. A project
4020
+ // that HAS one and read nothing out of it still refuses — the previous
4021
+ // waiver here was `scan.filesScanned > 0`, which could never be false
4022
+ // at the point it was read (#476).
4023
+ const unmeasured = unmeasuredScanReason(
4024
+ scan,
4025
+ { found: existsSync(join(root, "workflows")), examples: [], unreadable: [], skipped: [], unscannedSourceCount: 0, unscannedDirs: [] },
4026
+ "CONFIG-2",
4027
+ "workflows/ directory",
4028
+ );
4029
+ if (unmeasured) {
4030
+ addFinding({
4031
+ ruleId: "CONFIG-2",
4032
+ severity: "WARN",
4033
+ file: "",
4034
+ message: unmeasured,
4035
+ });
4036
+ return;
4037
+ }
4038
+ const violations = configAccessViolationRecords(
2948
4039
  scan,
2949
4040
  readConfigAccessRatchet(root, "workflows"),
2950
4041
  "CONFIG-2",
2951
- scan.filesScanned > 0,
2952
4042
  );
2953
4043
  for (const v of violations) {
2954
4044
  addFinding({
2955
4045
  ruleId: "CONFIG-2",
2956
4046
  severity: "FAIL",
2957
- file: v.split(": ")[1]?.split(" ")[0] || "",
2958
- message: v,
4047
+ file: v.file,
4048
+ message: v.message,
2959
4049
  fixCommand: "Point the prompt at the resolved-config artefact instead",
2960
4050
  });
2961
4051
  }
2962
- expect(violations, violations.join("\n")).toEqual([]);
4052
+ const messages = violations.map(v => v.message);
4053
+ expect(messages, messages.join("\n")).toEqual([]);
2963
4054
  });
2964
4055
  });
2965
4056
  }