rungate 0.4.1 → 0.6.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 (87) 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/agents-md-sections.ts +144 -0
  11. package/lib/branch-diff.ts +139 -0
  12. package/lib/bun-version.ts +268 -0
  13. package/lib/ci-checkout.ts +1 -1
  14. package/lib/cli-commands.ts +7 -1
  15. package/lib/compliance.ts +13 -11
  16. package/lib/config-loader.ts +12 -0
  17. package/lib/conformity.ts +1147 -116
  18. package/lib/context-docs.ts +143 -28
  19. package/lib/create-brief.ts +2 -1
  20. package/lib/create-sc.ts +90 -4
  21. package/lib/doc-scan-targets.ts +9 -0
  22. package/lib/evidence-command-transport.ts +160 -0
  23. package/lib/evidence-prevalidator.ts +22 -0
  24. package/lib/fallow-availability.ts +129 -0
  25. package/lib/gate-refusal-currency.ts +112 -0
  26. package/lib/gate-timeouts.ts +82 -0
  27. package/lib/generators/agent-briefs.ts +4 -1
  28. package/lib/generators/agents-md.ts +71 -23
  29. package/lib/generators/code-map.ts +2 -1
  30. package/lib/generators/types.ts +8 -0
  31. package/lib/git-dates.ts +55 -0
  32. package/lib/github.ts +195 -0
  33. package/lib/js-top-level-code.ts +27 -2
  34. package/lib/junit-checks.ts +484 -0
  35. package/lib/local-calendar-day.ts +78 -0
  36. package/lib/package-closure.ts +278 -2
  37. package/lib/project-state-shape.ts +59 -0
  38. package/lib/promote-outputs.ts +6 -2
  39. package/lib/release-preflight.ts +196 -0
  40. package/lib/report-provenance.ts +156 -0
  41. package/lib/sc-claim-forms.ts +75 -0
  42. package/lib/sc-id-cross-tree.ts +311 -0
  43. package/lib/scaffold/ai-review-step.ts +180 -0
  44. package/lib/scaffold/defaults.ts +40 -0
  45. package/lib/scaffold/managed-workflow.ts +125 -27
  46. package/lib/scaffold/owned-files.ts +48 -2
  47. package/lib/scaffold/profiles.ts +94 -0
  48. package/lib/scaffold/rehearsal.ts +232 -73
  49. package/lib/scaffold/steps.ts +777 -152
  50. package/lib/scaffold/write-steps.ts +56 -13
  51. package/lib/scanner.ts +38 -12
  52. package/lib/source-anchor.ts +144 -0
  53. package/lib/spec-listing.ts +148 -0
  54. package/lib/spec-requirements.ts +209 -0
  55. package/lib/success-doc.ts +779 -0
  56. package/lib/suite-run-reading.ts +364 -0
  57. package/lib/test-census.ts +199 -0
  58. package/lib/test-command.ts +133 -0
  59. package/lib/test-suite-lock.ts +166 -10
  60. package/lib/tool-probe.ts +120 -0
  61. package/lib/tracked-vs-ignored.ts +234 -0
  62. package/lib/trajectory.ts +377 -0
  63. package/lib/validators/spec-validators.ts +35 -6
  64. package/lib/workflow-security.ts +101 -0
  65. package/lib/workflow-test-harness.ts +349 -0
  66. package/package.json +6 -1
  67. package/scripts/audit-specs.ts +247 -12
  68. package/scripts/audit-transcript.ts +2 -1
  69. package/scripts/convert-spec.ts +2 -1
  70. package/scripts/create-sc.ts +17 -7
  71. package/scripts/create-spec.ts +2 -1
  72. package/scripts/create-success.ts +163 -0
  73. package/scripts/extract-constraints.ts +90 -19
  74. package/scripts/generate-code-map.ts +53 -12
  75. package/scripts/scaffold-project.ts +31 -4
  76. package/scripts/split-spec.ts +2 -1
  77. package/scripts/sync-sc-status.ts +57 -5
  78. package/scripts/sync-spec-tests.ts +2 -1
  79. package/specs/SPEC-TEMPLATE.md +200 -0
  80. package/templates/SUCCESS-TEMPLATE.md +72 -0
  81. package/templates/agent-briefs/_shared.md +9 -0
  82. package/templates/agent-briefs/aditi.md +46 -0
  83. package/templates/agent-briefs/discovery.md +37 -0
  84. package/templates/agent-briefs/marcus.md +39 -0
  85. package/templates/agent-briefs/quinn.md +67 -0
  86. package/templates/agent-briefs/rook.md +40 -0
  87. package/templates/agent-briefs/serena.md +39 -0
package/lib/conformity.ts CHANGED
@@ -6,10 +6,19 @@
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";
12
+ import {
13
+ ambiguousSpecNames,
14
+ readSpecRequirements,
15
+ requirementViolations,
16
+ specIsReferenced,
17
+ testableViolations,
18
+ } from "./spec-requirements";
19
+ import { lastCommitDates } from "./git-dates";
11
20
  import { spawnSync } from "child_process";
12
- import { join, dirname } from "path";
21
+ import { join, dirname, sep } from "path";
13
22
  import { fileURLToPath } from "url";
14
23
  import { deriveDirectoryName } from "../scripts/split-spec";
15
24
  import { readFreshCache } from "./behavioral-cache";
@@ -17,7 +26,9 @@ import { tryLoadRungateConfig } from "./config-loader";
17
26
  import { stripJsComments } from "./strip-js-comments";
18
27
  import { parseScDeclarations } from "./sc-ids";
19
28
  import { isHarnessItself } from "./harness-identity";
20
- import { tsconfigVerdict } from "./typescript-project";
29
+ import { fallowAvailable } from "./fallow-availability";
30
+ import { tsconfigVerdict, TS_SOURCE_DIRS } from "./typescript-project";
31
+ import { readSuccessDoc, readSuccessTemplate, successViolations } from "./success-doc";
21
32
 
22
33
  // ── Shared utilities ────────────────────────────────────────
23
34
 
@@ -1524,7 +1535,11 @@ export function runSpecDrift(
1524
1535
  }
1525
1536
  }
1526
1537
 
1527
- const orphaned = testable.filter(s => !allContent.includes(s));
1538
+ // Not `allContent.includes(s)`. A bare basename credits a spec for a
1539
+ // test that names a DIFFERENT file — see `lib/spec-requirements.ts`,
1540
+ // where the collision and its one instance on this tree are measured.
1541
+ const ambiguous = ambiguousSpecNames(root, collectSpecFiles(specsDir));
1542
+ const orphaned = testable.filter(s => !specIsReferenced(allContent, s, ambiguous));
1528
1543
 
1529
1544
  // Was `expect(true).toBe(true)` after a console.warn, so the mechanical
1530
1545
  // enforcement of CLAUDE.md's "SCs without tests are wishes" could never
@@ -1610,6 +1625,23 @@ export function runSpecDrift(
1610
1625
  `exemption a deliberate recorded decision rather than a diff.`,
1611
1626
  ).toEqual([]);
1612
1627
  });
1628
+
1629
+ test("DRIFT-4: Every spec states criteria, or declares that it states none", () => {
1630
+ if (!existsSync(specsDir)) return checkSkipped("DRIFT-4", "no specs/ directory");
1631
+ const specs = collectSpecFiles(specsDir);
1632
+ if (specs.length === 0) return checkSkipped("DRIFT-4", "no spec files");
1633
+
1634
+ // Unlike DRIFT-2 this has no ratchet and does not need one. The
1635
+ // exemption is a line in the document's own frontmatter, so a consumer
1636
+ // on upgrade can clear a violation by declaring it where the reader it
1637
+ // affects will see it — no list to adopt, nothing inherited from
1638
+ // rungate's backlog, and nothing DRIFT-3 has to police.
1639
+ const violations = requirementViolations(specs.map(s => readSpecRequirements(specsDir, s)));
1640
+ expect(violations, violations.join("\n")).toEqual([]);
1641
+
1642
+ const badFlags = testableViolations(specsDir, specs);
1643
+ expect(badFlags, badFlags.join("\n")).toEqual([]);
1644
+ });
1613
1645
  });
1614
1646
  }
1615
1647
 
@@ -1620,67 +1652,11 @@ export function runSpecDrift(
1620
1652
  * `runDocHygiene(ROOT, findings)`.
1621
1653
  */
1622
1654
  /**
1623
- * Every path's most recent commit date, from ONE git subprocess (#323).
1624
- *
1625
- * Exported so the regression test can run it against the repository and
1626
- * compare it to the per-file calls it replaced — a single site to mutate, and
1627
- * the only way to prove the parser still agrees with git rather than merely
1628
- * being faster. A detector that got quicker by finding less would pass every
1629
- * timing test and none of the ones that matter.
1630
- *
1631
- * Walks newest-first, so the first time a path appears is its latest commit
1632
- * and later entries are ignored. Paths deleted or renamed earlier in history
1633
- * also appear; they are never looked up, which is cheaper than filtering them.
1634
- *
1635
- * `pathspecs` must be the SET OF PATHS THE CALLER WILL LOOK UP, not the
1636
- * directories they mostly live in. The first version of this took the six doc
1637
- * directories, which is where the staleness scan finds most of its files — but
1638
- * the scan also walks root-level markdown, and `git log -- specs docs` cannot
1639
- * report a commit for `AGENTS.md`. Six files silently dropped out of the
1640
- * lookup and `if (!dateStr) continue` read that as "newly added, so not
1641
- * stale". A detector narrower than what it detects, shipped inside the fix for
1642
- * a different instance of the same thing. Passing the lookup set makes the
1643
- * pathspec and the keys the same list by construction, so they cannot drift.
1644
- *
1645
- * Fails CLOSED. `spawnSync` does not throw when git exits non-zero, so a
1646
- * broken invocation would otherwise return an empty map and every file would
1647
- * read as newly added — total blindness that looks exactly like a clean run.
1655
+ * Re-exported from `lib/git-dates.ts` (#508). The body moved to a leaf so a
1656
+ * CLI outside the test runner can call it; this stays the name SC-842 and
1657
+ * every existing caller use.
1648
1658
  */
1649
- export function lastCommitDates(root: string, pathspecs: string[]): Map<string, string> {
1650
- const lastCommit = new Map<string, string>();
1651
- // Not a git repository: nothing is tracked, so no path has a commit date.
1652
- // That is a real answer, not a failure, and scaffolded projects hit it.
1653
- if (!existsSync(join(root, ".git"))) return lastCommit;
1654
- if (pathspecs.length === 0) return lastCommit;
1655
- {
1656
- const log = spawnSync(
1657
- "git",
1658
- ["-C", root, "log", "--format=%H %ci", "--name-only", "--", ...pathspecs],
1659
- { timeout: 60_000, maxBuffer: 64 * 1024 * 1024 },
1660
- );
1661
- if (log.error) {
1662
- throw new Error(`lastCommitDates: git log could not run in ${root}: ${log.error.message}`);
1663
- }
1664
- if (log.status !== 0) {
1665
- throw new Error(
1666
- `lastCommitDates: git log exited ${log.status} in ${root}: ` +
1667
- `${log.stderr?.toString().trim() || "(no stderr)"}`,
1668
- );
1669
- }
1670
- let currentDate = "";
1671
- for (const line of log.stdout.toString().split("\n")) {
1672
- const header = /^[0-9a-f]{7,40} (\d{4}-\d{2}-\d{2})/.exec(line);
1673
- if (header) {
1674
- currentDate = header[1];
1675
- continue;
1676
- }
1677
- const path = line.trim();
1678
- if (!path || !currentDate) continue;
1679
- if (!lastCommit.has(path)) lastCommit.set(path, currentDate);
1680
- }
1681
- }
1682
- return lastCommit;
1683
- }
1659
+ export { lastCommitDates };
1684
1660
 
1685
1661
  export function runDocHygiene(
1686
1662
  root: string,
@@ -2001,7 +1977,28 @@ export function runDocHygiene(
2001
1977
  );
2002
1978
  }
2003
1979
 
2004
- expect(true).toBe(true);
1980
+ // The leniency above is about the BACKLOG. It was never meant to be
1981
+ // leniency about whether the scan happened, and `expect(true).toBe(true)`
1982
+ // made it both: with no assertion on the reading, the only red this
1983
+ // check could produce was a timeout — which is exactly the red it
1984
+ // produced, four times, until #508 made the staleness scan one git
1985
+ // call instead of ninety-two.
1986
+ //
1987
+ // So the reading is asserted and the backlog still is not. `0
1988
+ // candidates` over 91 documents and `0 candidates` over 4 are the same
1989
+ // line of output, and nothing here could previously tell them apart.
1990
+ console.log(
1991
+ `HYGIENE-6 coverage: read ${result.coverage.read} of ${result.coverage.planned} planned documents ` +
1992
+ `from ${result.scan.roots.length} directories (${result.scan.source})`,
1993
+ );
1994
+ expect(
1995
+ result.coverage.planned,
1996
+ "the documentation scan planned no files, so this check measured nothing",
1997
+ ).toBeGreaterThan(0);
1998
+ expect(
1999
+ result.coverage.unread,
2000
+ "planned documents could not be read, so the candidate list above is partial",
2001
+ ).toEqual([]);
2005
2002
  });
2006
2003
 
2007
2004
  test("HYGIENE-11: Stale unreferenced files warn with archival suggestion", () => {
@@ -2462,21 +2459,13 @@ interface FallowResult {
2462
2459
  // fail as timeouts instead of skipping, which blocks the pre-push conformity
2463
2460
  // gate on a tool nobody installed.
2464
2461
  //
2465
- // Resolve it locally instead, with no network path. Memoised PER ROOT —
2466
- // runFallowCheck is exported and consumer projects call it with their own
2467
- // root, so a single process can ask about several. A root-independent cache
2468
- // would answer for the wrong directory.
2469
- const FALLOW_AVAILABLE = new Map<string, boolean>();
2470
-
2471
- function fallowAvailable(root: string): boolean {
2472
- const cached = FALLOW_AVAILABLE.get(root);
2473
- if (cached !== undefined) return cached;
2474
- const available =
2475
- existsSync(join(root, "node_modules", ".bin", "fallow")) ||
2476
- Bun.which("fallow") !== null;
2477
- FALLOW_AVAILABLE.set(root, available);
2478
- return available;
2479
- }
2462
+ // Resolve it locally instead, with no network path. The predicate moved to
2463
+ // `lib/fallow-availability.ts` in #581 and is re-exported here rather than
2464
+ // copied: this module imports `bun:test` at module scope, so a CLI cannot
2465
+ // import it, and `scripts/generate-code-map.ts` is a CLI that needed the
2466
+ // same answer. It had a second answer — a bare `npx fallow` — for four
2467
+ // months, which is the defect #581 is about.
2468
+ export { fallowAvailable };
2480
2469
 
2481
2470
  /** Shared skip notice — a skipped check must say so, not read as a pass. */
2482
2471
  function fallowSkipped(check: string): void {
@@ -2869,8 +2858,79 @@ export function classifyConfigSites(source: string): ConfigSite[] {
2869
2858
  return sites;
2870
2859
  }
2871
2860
 
2872
- /** Directories CHECK-1 walks. Tests and `test/` are excluded by ADR-002 D4. */
2873
- const CONFIG_SCAN_DIRS = ["lib", "gates", "scripts", "hooks", "generators"];
2861
+ /**
2862
+ * `workflows/` is CONFIG-2's, and it is the ONLY directory CONFIG-1 declines
2863
+ * from the set of places this project believes TypeScript lives (#492).
2864
+ *
2865
+ * `readConfigAccessRatchet` scopes the two ratchets separately precisely so
2866
+ * the checks do not demand the removal of each other's entries, so CONFIG-1
2867
+ * walking `workflows/` would make each one's green require the other's red.
2868
+ */
2869
+ export const CONFIG_1_DECLINES = new Set(["workflows"]);
2870
+
2871
+ /**
2872
+ * Directories CHECK-1 walks. Tests and `test/` are excluded by ADR-002 D4.
2873
+ *
2874
+ * DERIVED from `TS_SOURCE_DIRS` rather than written out again, because the
2875
+ * two lists silently diverged and that is #492. The hand-written version was
2876
+ * `["lib", "gates", "scripts", "hooks", "generators"]` while
2877
+ * `TS_SOURCE_DIRS` was `["src", "lib", "scripts", "gates", "hooks",
2878
+ * "workflows"]`. **`src/` was in the second and not the first**, so a
2879
+ * consumer on the single most common layout outside this repo got a CONFIG-1
2880
+ * that walked zero files over a project that might be full of direct config
2881
+ * reads. Measured on one real consumer: PASS, having scanned 36 of 426
2882
+ * TypeScript files, 390 of them in `src/` (#492).
2883
+ *
2884
+ * Deriving it means a directory added to one list cannot fail to reach the
2885
+ * other without someone writing it into `CONFIG_1_DECLINES` and saying why.
2886
+ * `test/config-access-conformity.test.ts` asserts that relationship, because
2887
+ * a derivation nothing checks is a convention.
2888
+ *
2889
+ * **This is not the whole of #492, and on its own it would be the wrong
2890
+ * fix.** A hardcoded list being wrong is the defect; `src/` was only the
2891
+ * instance. The coverage shortfall reported further down is what survives
2892
+ * the next directory nobody thought of, and its fixture deliberately uses a
2893
+ * name no list will ever contain.
2894
+ */
2895
+ export const CONFIG_SCAN_DIRS = [
2896
+ ...new Set([...TS_SOURCE_DIRS, "generators"]),
2897
+ ].filter(d => !CONFIG_1_DECLINES.has(d));
2898
+
2899
+ /**
2900
+ * Source CONFIG-1 does not walk and that is NOT a coverage shortfall,
2901
+ * because somebody else measures it or policy excludes it.
2902
+ *
2903
+ * Without this the shortfall warning is wrong on rungate's own tree, and on
2904
+ * every tree the scaffolder produces. Measured through the real validator
2905
+ * before it existed: **19 files named, 1 of them a true gap.**
2906
+ *
2907
+ * | Named | Count | Why it is not a shortfall |
2908
+ * |---|---|---|
2909
+ * | `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 |
2910
+ * | `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 |
2911
+ * | `bin/` | 1 | **a real gap, and the one the warning should keep naming** |
2912
+ *
2913
+ * A warning that is wrong on the repo that ships it is how a project learns
2914
+ * to ignore warnings, and then the true one — `bin/rungate.ts` here, the
2915
+ * shape of #476's `bin/cli.ts` — is invisible too. The test asserting that
2916
+ * silence said so in its own comment before this was measured.
2917
+ *
2918
+ * Found by sec-492. It is #492's own rubric entry recurring inside #492's
2919
+ * fix: every shortfall fixture in the battery used a directory that was
2920
+ * genuinely unmeasured, so the precondition "no declined-but-measured
2921
+ * directory exists" held across every case, and the branch where it does
2922
+ * not hold was outside the battery's reach entirely.
2923
+ */
2924
+ function measuredElsewhere(top: string): boolean {
2925
+ // TOP-LEVEL ONLY, deliberately. An earlier cut also excluded anything
2926
+ // under a `fixtures/` path at any depth, which was dead on this tree —
2927
+ // every fixture here is under `test/`, already covered by the clause
2928
+ // below — and opened a hole in a consumer's: `domain/fixtures/config.ts`
2929
+ // is real source in a directory nothing walks, and the broader rule
2930
+ // dropped it from the count silently. An exclusion that is not needed to
2931
+ // make the warning true is an exclusion that only subtracts coverage.
2932
+ return CONFIG_1_DECLINES.has(top) || top === "test" || top === "tests";
2933
+ }
2874
2934
 
2875
2935
  /** The one module allowed to read the config. ADR-002 D1. */
2876
2936
  const CONFIG_LOADER = "lib/config-loader.ts";
@@ -2886,11 +2946,36 @@ function walkSources(dir: string, rel: string, out: Array<{ path: string; text:
2886
2946
  const abs = join(dir, e.name);
2887
2947
  const relPath = rel ? `${rel}/${e.name}` : e.name;
2888
2948
  if (e.isDirectory()) {
2949
+ // NOT a test-directory skip, and not `isTestSourceFile` below. The first draft of
2950
+ // the #500 fix widened both here to match the evidence walk, and that
2951
+ // silently REDUCED enforcement: `lib/tests/sneaky.ts`, `lib/spec/y.ts`,
2952
+ // `lib/__mocks__/x.ts`, `lib/sneaky.test.js` and `lib/sneaky.spec.ts`
2953
+ // each carried a real direct config read, were counted as violations
2954
+ // before, and became silent green after — no WARN, no UNMEASURED, no
2955
+ // record, because a non-empty scan never engages the waiver.
2956
+ //
2957
+ // The invariant the waiver needs is ONE-DIRECTIONAL: the evidence walk
2958
+ // must not claim source the scan would never read. The scan reading
2959
+ // MORE than the walk is harmless — a file the scan reads makes
2960
+ // `filesScanned > 0`, and the waiver is never reached. So the walk is
2961
+ // the side that narrows, and this stays where ADR-002 D4 left it.
2889
2962
  if (e.name === "test" || e.name === "node_modules") continue;
2890
2963
  walkSources(abs, relPath, out);
2891
2964
  continue;
2892
2965
  }
2893
- if (!/\.(ts|js)$/.test(e.name) || /\.test\.ts$/.test(e.name)) continue;
2966
+ // `SOURCE_EXTENSIONS`, not `/\.(ts|js)$/`. The evidence walk counts
2967
+ // `.tsx .jsx .mjs .cjs .mts .cts` as source and this scan could not read
2968
+ // any of them, so the invariant stated above — the walk must not claim
2969
+ // source the scan would never read — was violated for six extensions
2970
+ // (#506).
2971
+ //
2972
+ // Measured: a project whose only code is `lib/app.tsx` holding a live
2973
+ // direct config read scans ZERO files, and CONFIG-1 refuses with *"This
2974
+ // project DOES contain source — lib/app.tsx — none of it in the
2975
+ // directories this check reads"*. `lib/` is the first directory this
2976
+ // check reads. The sentence is false, the refusal is unclearable, and
2977
+ // the read goes uncaught — three failures from one missing extension.
2978
+ if (!SOURCE_EXTENSIONS.test(e.name) || /\.test\.ts$/.test(e.name)) continue;
2894
2979
  out.push({ path: relPath, text: readFileSync(abs, "utf-8") });
2895
2980
  }
2896
2981
  }
@@ -2943,19 +3028,58 @@ export function scanConfigAccess(root: string): ConfigAccessScan {
2943
3028
  * through both scans and asserts they disagree, so the collapse cannot be made
2944
3029
  * quietly in the name of consistency.
2945
3030
  */
3031
+ /**
3032
+ * Every module in `workflows/`, in any language this project writes them in.
3033
+ *
3034
+ * It was `.js` only, non-recursively, because rungate's own workflows are
3035
+ * flat `.js` — they cannot import (#69). A consumer keeping TypeScript
3036
+ * workflows got CONFIG-2 reading zero files over a directory full of code,
3037
+ * which the empty-scan refusal then reported as `the scan read NO files`,
3038
+ * unsatisfiable without converting the workflows to `.js` (#501).
3039
+ *
3040
+ * `.d.ts` is excluded for the same reason the CONFIG-1 walk excludes it:
3041
+ * declarations contain no calls.
3042
+ */
3043
+ const WORKFLOW_MODULE = /\.(js|mjs|cjs|ts|mts|cts)$/;
3044
+
3045
+ function workflowModules(dir: string, rel: string, out: string[]): void {
3046
+ let entries;
3047
+ try {
3048
+ entries = readdirSync(dir, { withFileTypes: true });
3049
+ } catch {
3050
+ return;
3051
+ }
3052
+ for (const e of entries) {
3053
+ const childRel = rel ? `${rel}/${e.name}` : e.name;
3054
+ // RECURSIVE, and that is load-bearing rather than tidy. CONFIG-1
3055
+ // declines `workflows/` entirely on the grounds that CONFIG-2 owns it,
3056
+ // so a depth CONFIG-2 does not reach is a depth NEITHER check reads —
3057
+ // a blind spot the hand-off would create rather than one it inherits.
3058
+ if (e.isDirectory()) {
3059
+ if (e.name === "node_modules") continue;
3060
+ workflowModules(join(dir, e.name), childRel, out);
3061
+ continue;
3062
+ }
3063
+ if (!e.isFile()) continue;
3064
+ if (!WORKFLOW_MODULE.test(e.name) || e.name.endsWith(".d.ts")) continue;
3065
+ out.push(childRel);
3066
+ }
3067
+ }
3068
+
2946
3069
  export function scanPromptConfigAccess(root: string): ConfigAccessScan {
2947
3070
  const dir = join(root, "workflows");
2948
3071
  const counts: Record<string, number> = {};
2949
3072
  let filesScanned = 0;
2950
3073
  let bytesScanned = 0;
2951
- let entries: string[];
2952
- try {
2953
- entries = readdirSync(dir).filter(f => f.endsWith(".js"));
2954
- } catch {
2955
- return { counts, filesScanned: 0, bytesScanned: 0 };
2956
- }
2957
- for (const f of entries) {
2958
- const text = readFileSync(join(dir, f), "utf-8");
3074
+ const entries: string[] = [];
3075
+ workflowModules(dir, "", entries);
3076
+ for (const f of entries.sort()) {
3077
+ let text: string;
3078
+ try {
3079
+ text = readFileSync(join(dir, f), "utf-8");
3080
+ } catch {
3081
+ continue;
3082
+ }
2959
3083
  filesScanned++;
2960
3084
  bytesScanned += text.length;
2961
3085
  const n = (stripJsComments(text).match(configAccessPattern()) || []).length;
@@ -3014,50 +3138,904 @@ export function readConfigAccessRatchet(
3014
3138
  * this repo's defining defect and would be the most embarrassing possible
3015
3139
  * place to reproduce it (ADR-002 D4, mutation 5).
3016
3140
  */
3141
+ /**
3142
+ * A violation and the file it is about, produced together (#517).
3143
+ *
3144
+ * `file` is `""` when the violation is not about one file — the two
3145
+ * empty-scan refusals below are about the SCAN. That is the same value
3146
+ * `runConfigAccessValidation` already records for its UNMEASURED finding,
3147
+ * so there is one spelling of "no file here" rather than two.
3148
+ *
3149
+ * It used to be recovered from the message by
3150
+ * `v.split(": ")[1]?.split(" ")[0] || ""`, which reads a path out of
3151
+ * `CONFIG-1: lib/scanner.ts has 3 direct reads` correctly and reads the
3152
+ * word **`the`** out of `CONFIG-1: the scan read NO files…`. A findings
3153
+ * report renders that under a column headed `file`: it looks like a path,
3154
+ * it is a stopword, and nothing downstream could tell it from a real one.
3155
+ *
3156
+ * The defect is not the parser. It is that the violation string is the
3157
+ * HUMAN rendering and `file` is the MACHINE one, and the second was being
3158
+ * recovered from the first — by the producer, which had the fact all
3159
+ * along and threw it away by formatting it into prose. The `|| ""`
3160
+ * fallback then made "this is not about a file" and "my parse failed"
3161
+ * the same value. Producing both together removes the second case
3162
+ * entirely rather than handling it.
3163
+ */
3164
+ export interface ConfigAccessViolation {
3165
+ /**
3166
+ * The file in violation, or `""` when the violation is not about one.
3167
+ *
3168
+ * **`""` is not a one-meaning sentinel, and saying it was would be the
3169
+ * silent-default shape.** `scan.counts` keys can never be empty —
3170
+ * `walkSources` seeds every one from a scan directory and
3171
+ * `scanPromptConfigAccess` prefixes `workflows/`, so all of them contain
3172
+ * a `/`. `banked` keys CAN be: `readConfigAccessRatchet` validates only
3173
+ * that the VALUE is a number, so a ratchet carrying `{"": 2}` produces a
3174
+ * banked-but-absent violation whose `file` is `""` — a violation that IS
3175
+ * about a ratchet entry, indistinguishable here from one about the scan.
3176
+ *
3177
+ * Measured by sec-517, and not a regression: the parse this replaced
3178
+ * produced `""` there too. Recorded because the sentence it replaces
3179
+ * claimed a guarantee the code does not make.
3180
+ */
3181
+ file: string;
3182
+ message: string;
3183
+ }
3184
+
3185
+ /**
3186
+ * The string rendering, derived from the records rather than beside them.
3187
+ *
3188
+ * A pure projection, so it cannot disagree with `file`. Keeping it means
3189
+ * the fifteen existing call sites that assert on message text do not have
3190
+ * to be rewritten to prove a path field, and there is still only one
3191
+ * binding that DECIDES what a violation is.
3192
+ */
3017
3193
  export function configAccessViolations(
3018
3194
  scan: ConfigAccessScan,
3019
3195
  banked: Record<string, number>,
3020
3196
  label: string,
3021
3197
  requireNonEmpty = true,
3198
+ evidence?: SourceEvidence,
3022
3199
  ): string[] {
3023
- const out: string[] = [];
3200
+ return configAccessViolationRecords(scan, banked, label, requireNonEmpty, evidence)
3201
+ .map(v => v.message);
3202
+ }
3203
+
3204
+ /**
3205
+ * Turn a scan into refusals, as RECORDS. The one binding that decides what
3206
+ * a config-access violation is.
3207
+ *
3208
+ * Empty allows. The ratchet refuses in BOTH directions: over its number
3209
+ * fails, under its number fails, and a file absent from the ratchet is
3210
+ * allowed nothing — so a new reader fails the suite even while the total is
3211
+ * above zero, and clearing a file means deleting its entry in the same
3212
+ * commit.
3213
+ *
3214
+ * **This is the mutation target, not `configAccessViolations`.** That one
3215
+ * is now a pure projection used only by tests; short-circuiting it to
3216
+ * `return []` still scores red, but not one of those reds is a production
3217
+ * path, so the score would be unchanged and the meaning would not.
3218
+ */
3219
+ export function configAccessViolationRecords(
3220
+ scan: ConfigAccessScan,
3221
+ banked: Record<string, number>,
3222
+ label: string,
3223
+ requireNonEmpty = true,
3224
+ evidence?: SourceEvidence,
3225
+ ): ConfigAccessViolation[] {
3226
+ const out: ConfigAccessViolation[] = [];
3024
3227
  if (requireNonEmpty && scan.filesScanned === 0) {
3228
+ // Name the source that made this refusal happen. Without it the consumer
3229
+ // reads "the scan read NO files" on a project they believe has no code,
3230
+ // with nothing pointing at the file responsible — which is the difference
3231
+ // between a two-minute fix and an undiagnosable red. `SourceEvidence`
3232
+ // already collects up to three paths and its docstring has always
3233
+ // promised this; nothing read the field until now.
3234
+ const why = evidence?.found && evidence.examples.length > 0
3235
+ ? ` This project DOES contain source — ${evidence.examples.join(", ")}` +
3236
+ `${evidence.examples.length === 3 ? " (first 3)" : ""} — none of it in the ` +
3237
+ `directories this check reads, so the check is blind rather than satisfied.`
3238
+ : evidence && evidence.unreadable.length > 0
3239
+ ? ` The source walk could not read ${evidence.unreadable.join(", ")}, so ` +
3240
+ `"no code here" could not be established.`
3241
+ : "";
3242
+ // About the SCAN, not about a file. This is the violation whose
3243
+ // message begins "the scan read NO files" and whose derived path was
3244
+ // therefore the word `the`.
3025
3245
  return [
3026
- `${label}: the scan read NO files. A check that scans nothing reports ` +
3027
- `zero violations and cannot be told from compliance — refusing rather ` +
3028
- `than reporting clean (ADR-002 D4).`,
3246
+ {
3247
+ file: "",
3248
+ message:
3249
+ `${label}: the scan read NO files. A check that scans nothing reports ` +
3250
+ `zero violations and cannot be told from compliance — refusing rather ` +
3251
+ `than reporting clean (ADR-002 D4).${why}`,
3252
+ },
3029
3253
  ];
3030
3254
  }
3031
3255
  if (requireNonEmpty && scan.filesScanned > 0 && scan.bytesScanned === 0) {
3032
- return [`${label}: ${scan.filesScanned} files were walked and none had any content.`];
3256
+ // About the scan too — `${scan.filesScanned}` is a COUNT, and the old
3257
+ // parse reported it as a path.
3258
+ return [
3259
+ { file: "", message: `${label}: ${scan.filesScanned} files were walked and none had any content.` },
3260
+ ];
3033
3261
  }
3034
3262
 
3035
3263
  for (const [file, n] of Object.entries(scan.counts).sort()) {
3036
3264
  const allowed = banked[file] ?? 0;
3037
3265
  if (n > allowed) {
3038
- out.push(
3039
- `${label}: ${file} has ${n} direct config access site(s), ${allowed} allowed. ` +
3266
+ out.push({
3267
+ file,
3268
+ message:
3269
+ `${label}: ${file} has ${n} direct config access site(s), ${allowed} allowed. ` +
3040
3270
  `Only ${CONFIG_LOADER} may read the config (ADR-002 D1). Use ` +
3041
3271
  `loadRungateConfig / tryLoadRungateConfig / resolveConfig.`,
3042
- );
3272
+ });
3043
3273
  } else if (n < allowed) {
3044
- out.push(
3045
- `${label}: ${file} is banked at ${allowed} but only ${n} remain — lower the ` +
3274
+ out.push({
3275
+ file,
3276
+ message:
3277
+ `${label}: ${file} is banked at ${allowed} but only ${n} remain — lower the ` +
3046
3278
  `number in .claude/config-access-ratchet.json in the same commit that earned it.`,
3047
- );
3279
+ });
3048
3280
  }
3049
3281
  }
3050
3282
  for (const [file, allowed] of Object.entries(banked).sort()) {
3051
3283
  if (allowed > 0 && !(file in scan.counts)) {
3052
- out.push(
3053
- `${label}: ${file} is banked at ${allowed} but has no violations left — ` +
3284
+ out.push({
3285
+ file,
3286
+ message:
3287
+ `${label}: ${file} is banked at ${allowed} but has no violations left — ` +
3054
3288
  `remove its entry from .claude/config-access-ratchet.json.`,
3055
- );
3289
+ });
3056
3290
  }
3057
3291
  }
3058
3292
  return out;
3059
3293
  }
3060
3294
 
3295
+ /**
3296
+ * Why an empty scan is UNMEASURED rather than a refusal — or `null` when it is
3297
+ * a refusal after all (#476).
3298
+ *
3299
+ * `configAccessViolations`'s empty-scan refusal is correct and stays. What it
3300
+ * cannot do on its own is tell two situations apart, because both reach it as
3301
+ * `filesScanned === 0`:
3302
+ *
3303
+ * | Situation | Verdict |
3304
+ * |---|---|
3305
+ * | a code project whose file walk broke | **refuse** — this is what the refusal is for |
3306
+ * | a content project that has no sources of that kind | UNMEASURED, and say so |
3307
+ *
3308
+ * `--profile=minimal` (#449) exists so a project can take rungate's structure
3309
+ * without the ship harness, and the first consumer to use it — a Claude Code
3310
+ * plugin shipping a skill, a spec and two reference files, with deliberately
3311
+ * no executable surface — got a conformity suite with one permanently-red
3312
+ * check it could only satisfy by adding TypeScript it does not want.
3313
+ *
3314
+ * **Two questions, not one decider asked twice.** `scan.filesScanned` answers
3315
+ * "did I read anything"; `sourcesPresent` answers "was there anything to
3316
+ * read", over a different directory list and a different traversal
3317
+ * (`lib/typescript-project.ts`, #87's one decider for that fact). A project
3318
+ * with TypeScript the walk failed to reach still refuses, which is case 3.
3319
+ *
3320
+ * It returns a REASON, never a bare boolean: `0`, `{}`, `null` and `SKIP` are
3321
+ * all indistinguishable from success and `UNMEASURED` is not
3322
+ * (`.claude/rules/config-access.md`). A check that skips has to be able to say
3323
+ * what it skipped over.
3324
+ *
3325
+ * The waiver this replaces was `requireNonEmpty = scan.filesScanned > 0`,
3326
+ * which required a non-empty scan only when the scan was already non-empty —
3327
+ * a blanket disable wearing a conditional's clothes, so CONFIG-2's empty-scan
3328
+ * refusal had never been reachable.
3329
+ */
3330
+ /** Anything that can carry code. Deliberately WIDER than any scanner's filter. */
3331
+ export const SOURCE_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;
3332
+
3333
+ /** Directories that hold code nobody wrote, or output nobody edits. */
3334
+ const SOURCE_SKIP_DIRS = new Set([
3335
+ "node_modules", ".git", "dist", "build", "coverage", ".next", ".output", "vendor",
3336
+ ]);
3337
+
3338
+ /**
3339
+ * Test directories and test files — excluded from BOTH readings, by ADR-002 D4.
3340
+ *
3341
+ * One declaration, consulted by `walkSources` (which produces the scan) and
3342
+ * by `projectSourceEvidence` (which decides whether an empty scan is
3343
+ * believable). **They have to agree.** The evidence walk asks "should the
3344
+ * scan have found something?", so a file the scan would never read is not an
3345
+ * answer to that question.
3346
+ *
3347
+ * The first draft of this fix had them disagree, and the cost was precise:
3348
+ * the scaffold writes `tests/scaffold-conformity.test.ts`, which on a
3349
+ * `--profile=minimal` content project is the ONLY code-extension file in the
3350
+ * tree. The evidence walk saw it, reported source present, and CONFIG-1
3351
+ * refused with "the scan read NO files" — on every scaffolded content
3352
+ * project, unsatisfiably, since the only ways out were adding config-reading
3353
+ * source the project does not want or deleting the suite. **The file that
3354
+ * made the evidence true was the generated suite running the check.** That is
3355
+ * #476's original complaint — a permanently-red check — arriving through the
3356
+ * fix for the fix, measured end-to-end by running the real CLI rather than
3357
+ * reasoned about.
3358
+ */
3359
+ // There is deliberately no TEST_DIRECTORY exclusion. `isTestSourceFile`
3360
+ // below is the only test-related skip, and sec-500 established that the
3361
+ // directory form was never needed: the scaffold writes exactly one file
3362
+ // into a test directory (`test/scaffold-conformity.test.ts`, the whole of
3363
+ // sec-476's B1), and the filename predicate already matches it.
3364
+ //
3365
+ // The case the directory skip was defending — `tests/helpers/setup.ts`, a
3366
+ // non-test file in a test directory — described a project that cannot
3367
+ // exist in the state where it would matter. The waiver is only reached
3368
+ // when a project has NO production source, and a project with test
3369
+ // helpers has production source, so `filesScanned > 0` and the waiver is
3370
+ // never consulted. Meanwhile the skip cost a real hole: a non-test file
3371
+ // in `tests/` carrying a live `join(process.cwd(), ".claude", ...)` was
3372
+ // waived.
3373
+ export function isTestSourceFile(name: string): boolean {
3374
+ return /\.(test|spec)\.[cm]?[jt]sx?$/.test(name);
3375
+ }
3376
+
3377
+ /**
3378
+ * Tool configuration at the project root is not the project's source.
3379
+ *
3380
+ * `prettier.config.js`, `vite.config.ts`, `jest.config.js`. A policy call,
3381
+ * and it is the one place this walk is deliberately narrower than "any file
3382
+ * with a code extension", so the reasoning is written down rather than
3383
+ * implied:
3384
+ *
3385
+ * The question is "should the scan have read something?" — and the cost of
3386
+ * the two wrong answers is wildly asymmetric. Answering yes wrongly gives
3387
+ * every content project with a prettier config a permanently red, literally
3388
+ * unsatisfiable CONFIG-1, which is the defect #476 was filed about. Answering
3389
+ * no wrongly waives a project whose only direct rungate-config read is inside
3390
+ * a build tool's config file, which is not a thing that happens — these files
3391
+ * configure the tool that loads them and nothing else reads them.
3392
+ *
3393
+ * Root level only. A `src/app.config.ts` is ordinary source and is counted.
3394
+ */
3395
+ function isRootToolConfig(rel: string, name: string): boolean {
3396
+ return !rel.includes("/") && /\.config\.[cm]?[jt]s$/.test(name);
3397
+ }
3398
+
3399
+ /**
3400
+ * Whether this project contains code at all, and whether the answer is
3401
+ * trustworthy (#476 follow-up).
3402
+ *
3403
+ * `found` is deliberately BROADER than what any individual check scans —
3404
+ * every code extension, every directory, the whole tree. That direction is
3405
+ * the whole point. The question it answers is "is this a project with code
3406
+ * in it", and a narrower answer turns a blind check into a clean one.
3407
+ *
3408
+ * `unreadable` exists because "there is no code" and "I could not look" are
3409
+ * different facts that a swallowed `readdirSync` makes identical. Before the
3410
+ * waiver existed, swallowing was harmless: a failed walk left `filesScanned`
3411
+ * at zero and the refusal fired. With a waiver reading the same silence, two
3412
+ * fail-opens point the same way and a chmod turns a FAIL into a green run.
3413
+ */
3414
+ export interface SourceEvidence {
3415
+ /** The project contains at least one source file somewhere. */
3416
+ found: boolean;
3417
+ /** Up to three paths, so a refusal can name what went unscanned. */
3418
+ examples: string[];
3419
+ /** Directories the walk could not read. Non-empty means `found` is unreliable. */
3420
+ unreadable: string[];
3421
+ /**
3422
+ * Entries the walk DECLINED to look at, and why.
3423
+ *
3424
+ * The third state, and #500's own complaint turned on itself. With only
3425
+ * `found` and `unreadable`, a declined entry is indistinguishable from an
3426
+ * absent one, and the waiver went on to assert "no source files of any
3427
+ * kind were found anywhere in the tree" — a sentence the walk never
3428
+ * established and which is FALSE for every skip class below. "True
3429
+ * sentence, wrong inference" was this issue's headline; this was the
3430
+ * sentence becoming untrue.
3431
+ *
3432
+ * Recorded rather than fixed by widening, because most of the skips are
3433
+ * correct: a content project with a `.github/` release script really does
3434
+ * have no project source. What is not correct is saying nothing is there.
3435
+ */
3436
+ skipped: string[];
3437
+ /**
3438
+ * Every file the walk counted as project source, not just the first three
3439
+ * (#492).
3440
+ *
3441
+ * `examples` is capped at 3 because a refusal that names four hundred
3442
+ * files is not a message. A COUNT is a different thing and the check
3443
+ * needs both: "CONFIG-1 read 36 files" is uninterpretable on its own.
3444
+ *
3445
+ * It counts ONLY source outside `CONFIG_SCAN_DIRS`, and deliberately does
3446
+ * not try to be a denominator for `filesScanned`. The two walks do not
3447
+ * agree about what source is inside a scanned directory and are not
3448
+ * supposed to: `walkSources` reads `lib/x.test.ts`, `lib/types.d.ts` and
3449
+ * `lib/tests/sneaky.ts`, all of which this walk declines, because the
3450
+ * comment on `walkSources` explains that narrowing the SCAN to match the
3451
+ * walk silently reduced enforcement. So `sourceCount - filesScanned`
3452
+ * would be a subtraction across two definitions, and could go negative.
3453
+ * One number, one walk, no arithmetic between them.
3454
+ */
3455
+ unscannedSourceCount: number;
3456
+ /**
3457
+ * Top-level directories holding source that `CONFIG_SCAN_DIRS` does not
3458
+ * walk — `"."` for a source file at the root (#492).
3459
+ *
3460
+ * This is the half of #492 that survives the fix. Adding `src/` to the
3461
+ * scan list closes the instance; this closes the CLASS, because the defect
3462
+ * is that a hardcoded list can be wrong and nothing notices. A consumer
3463
+ * who keeps their code in `domain/`, `packages/`, `app/` or `internal/`
3464
+ * gets told which directory went unread instead of a PASS that means
3465
+ * "clean in the five places I happened to look".
3466
+ */
3467
+ unscannedDirs: string[];
3468
+ }
3469
+
3470
+ /**
3471
+ * Directories that can never hold the project's own source, so a decline is
3472
+ * not worth recording. `.git` and `node_modules` are the whole list, and
3473
+ * both were cluttering the waiver message with facts true of every repo.
3474
+ */
3475
+ const NEVER_PROJECT_SOURCE = new Set([".git", "node_modules"]);
3476
+
3477
+ /**
3478
+ * Whether a DECLINED entry is a directory — for the label, and only for the
3479
+ * label (#518).
3480
+ *
3481
+ * The three decline-by-name branches below matched a name and then wrote
3482
+ * `${rel}/` with a directory-shaped label without asking. Measured before
3483
+ * the fix: 8 of this repo's 369 declines and **5 of a consumer's 13** named
3484
+ * a directory that does not exist, including four `.DS_Store/`. `.git` is
3485
+ * the one worth naming — in a worktree it is a gitfile, so that branch was
3486
+ * wrong in every worktree this project develops in.
3487
+ *
3488
+ * It is a `statSync` and not `e.isDirectory()` because `Dirent.isDirectory()`
3489
+ * is false for a symlink, and a symlinked `node_modules` is the ordinary
3490
+ * pnpm / npm-workspace shape — the cheap predicate gets the commonest real
3491
+ * instance backwards.
3492
+ *
3493
+ * **A failed stat answers "not a directory" rather than reaching the
3494
+ * verdict, and that is deliberate.** These entries are declined BY NAME and
3495
+ * were declined before this function existed; nothing here may change
3496
+ * WHETHER they are declined. If a throw pushed `unreadable`, a
3497
+ * `.hidden -> /locked/dir` would refuse CONFIG-1 for a whole project over an
3498
+ * entry the walk discards as tooling either way — the over-refusal the
3499
+ * dangling-symlink note further down already rules out for the same reason.
3500
+ * A link that resolves to nothing is not somewhere a reader can go looking,
3501
+ * which is the only thing the trailing slash claims.
3502
+ *
3503
+ * ## The dirent is authoritative for everything that is not a symlink (#543)
3504
+ *
3505
+ * `if (!e.isSymbolicLink()) return false` is a COST guard, not a correctness
3506
+ * one — `statSync` on a regular file answers the same thing the dirent
3507
+ * already did, so removing it changes no label on any real tree and was
3508
+ * **0 red of 92**. What it changes is syscalls. Before #518 an entry named
3509
+ * `.git`, `node_modules`, `dist`, `build`, `coverage`, `.next`, `.output`,
3510
+ * `vendor` or any dot-name cost zero; this function made it cost one, and
3511
+ * those are exactly the names people symlink onto network paths — a shared
3512
+ * `node_modules`, a pnpm store, `dist` on a build mount. `statSync` on a
3513
+ * stale NFS or autofs target blocks uninterruptibly and there is no timeout
3514
+ * to give it.
3515
+ *
3516
+ * A cost is not observable from a test, so the guard is pinned by the one
3517
+ * thing that is: a dirent that DISAGREES with the filesystem. Hand this
3518
+ * function "not a directory, not a symlink" together with a path that is a
3519
+ * directory, and today it answers `false`; without the guard the stat runs
3520
+ * and it answers `true`. That is the syscall, made visible.
3521
+ *
3522
+ * **Two residuals, stated rather than silently carried:**
3523
+ *
3524
+ * - A declined SYMLINK still costs one `statSync`, and that is the stale-
3525
+ * mount exposure. It is kept deliberately: dropping it writes a symlinked
3526
+ * `node_modules` down as a file, which is the commonest real instance of
3527
+ * the thing #518 fixed. `readlinkSync` would resolve the name without
3528
+ * touching the target, but a monorepo's `node_modules -> ../../node_modules`
3529
+ * is outside the project and still a directory, so the cheap answer is
3530
+ * wrong for the case that motivates the stat.
3531
+ * - That stat crosses the project boundary without consulting
3532
+ * `insideProject`. The walk does not follow the link — all three branches
3533
+ * `continue` — so containment holds, verified over a 64-shape matrix; the
3534
+ * residual is that the waiver message asserts one bit about a path
3535
+ * outside the project, reachable only by someone who could already plant
3536
+ * a symlink inside it.
3537
+ */
3538
+ export function declinedIsDir(e: Dirent, abs: string): boolean {
3539
+ if (e.isDirectory()) return true;
3540
+ // Not a correctness branch — see the note above. A dirent that says
3541
+ // "regular file" is the answer; going to the filesystem to ask again is a
3542
+ // syscall on a path that may be a stale mount.
3543
+ if (!e.isSymbolicLink()) return false;
3544
+ try {
3545
+ return statSync(abs).isDirectory();
3546
+ } catch {
3547
+ return false;
3548
+ }
3549
+ }
3550
+
3551
+ /**
3552
+ * Scripts the config scan cannot read but a project can absolutely be built
3553
+ * from. A `lib/loader.py` or a `hooks/run.sh` doing a direct config read is
3554
+ * invisible to `SOURCE_EXTENSIONS` and therefore to CONFIG-1 — which is a
3555
+ * defensible limit for a TypeScript check, and an indefensible silence.
3556
+ */
3557
+ const SCRIPT_LIKE = /\.(py|rb|sh|bash|zsh|fish|pl|php|lua|r|go|rs|java|kt|swift|ex|exs)$/i;
3558
+
3559
+ export function projectSourceEvidence(root: string): SourceEvidence {
3560
+ const examples: string[] = [];
3561
+ // #492: the COUNT and the WHERE, alongside the capped sample.
3562
+ let unscannedSourceCount = 0;
3563
+ const unscannedDirs = new Set<string>();
3564
+ const unreadable: string[] = [];
3565
+ const skipped: string[] = [];
3566
+ // Symlinked source directories ARE followed — `packages/core` behind
3567
+ // `lib/impl` is an ordinary monorepo shape, and a predicate that cannot see
3568
+ // it waives a project full of code. `realpathSync` keys the visited set so
3569
+ // a cycle terminates instead of hanging.
3570
+ const seen = new Set<string>();
3571
+ const stack: Array<[string, string]> = [[root, ""]];
3572
+ // The walk may not leave the project. A symlink to `$HOME` or `/` would
3573
+ // otherwise make `found` true because of code that is not in this project,
3574
+ // and walk the whole of it to decide that.
3575
+ let rootReal: string;
3576
+ try {
3577
+ rootReal = realpathSync(root);
3578
+ } catch {
3579
+ return {
3580
+ found: false, examples: [], unreadable: ["."], skipped: [],
3581
+ unscannedSourceCount: 0, unscannedDirs: [],
3582
+ };
3583
+ }
3584
+ const insideProject = (p: string) => p === rootReal || p.startsWith(rootReal + sep);
3585
+
3586
+ while (stack.length > 0) {
3587
+ const [dir, rel] = stack.pop()!;
3588
+ let real: string;
3589
+ try {
3590
+ real = realpathSync(dir);
3591
+ } catch {
3592
+ unreadable.push(rel || ".");
3593
+ continue;
3594
+ }
3595
+ if (!insideProject(real)) {
3596
+ if (rel) skipped.push(`${rel}/ (directory resolving outside the project)`);
3597
+ continue;
3598
+ }
3599
+ if (seen.has(real)) continue;
3600
+ seen.add(real);
3601
+
3602
+ let entries;
3603
+ try {
3604
+ entries = readdirSync(dir, { withFileTypes: true });
3605
+ } catch {
3606
+ unreadable.push(rel || ".");
3607
+ continue;
3608
+ }
3609
+ for (const e of entries) {
3610
+ const childRelEarly = rel ? `${rel}/${e.name}` : e.name;
3611
+ // RECORDED, not dropped. An earlier cut skipped `.git` and
3612
+ // `node_modules` entirely on the grounds that they can never hold the
3613
+ // project's own source — true, and still the wrong move, because
3614
+ // "I declined 400 entries under node_modules/" is honest and short
3615
+ // while silence is neither (sec-485). They collapse to one counted
3616
+ // line in the message, which gets the brevity without the silence.
3617
+ // The trailing slash is a claim about the entry, so it is asked
3618
+ // rather than assumed (#518). `.git` in a worktree is a gitfile.
3619
+ const dirSlash = () => (declinedIsDir(e, join(dir, e.name)) ? "/" : "");
3620
+ if (NEVER_PROJECT_SOURCE.has(e.name)) {
3621
+ skipped.push(`${childRelEarly}${dirSlash()} (dependency or VCS metadata)`);
3622
+ continue;
3623
+ }
3624
+ // Recorded whether or not it holds anything, and that is deliberate.
3625
+ // An earlier cut ran a bounded recursive walk here and recorded the
3626
+ // decline only for directories that turned out to contain source,
3627
+ // on the grounds that an empty `dist/` is not a fact about this
3628
+ // project. sec-485 took it apart and was right: this field is a log
3629
+ // of DECISIONS, and the walk declined either way. Measured against
3630
+ // the implementation — one tree, one set of decisions, `dist/` empty
3631
+ // and then holding a build artifact — the predicate made the evidence
3632
+ // record differ between the two, so a reader auditing a waiver saw a
3633
+ // different list depending on whether CI had run. A tracked-but-empty
3634
+ // `dist/` on a clean checkout is the live shape of that, not a
3635
+ // contrived one.
3636
+ //
3637
+ // What it cost to keep: a recursive walk inside the directories this
3638
+ // function exists specifically not to walk, build-state-dependent
3639
+ // evidence, and a second predicate to keep correct forever. What it
3640
+ // bought, once the message collapses by class: one name inside a
3641
+ // capped sample and one off a count. `test/config-access-conformity
3642
+ // .test.ts`'s "function of the DECISIONS" case holds this line.
3643
+ if (SOURCE_SKIP_DIRS.has(e.name)) {
3644
+ skipped.push(`${childRelEarly}${dirSlash()} (build output or dependency)`);
3645
+ continue;
3646
+ }
3647
+ // Tooling lives in dot-directories — `.github/scripts/release.js`,
3648
+ // `.husky/`, `.claude/`. `containsTypeScript` skipped every entry
3649
+ // starting with "." and this walk replaced it, so dropping that was a
3650
+ // silent widening: a release script is not the project's source, and a
3651
+ // content project that has one is not a project CONFIG-1 can measure.
3652
+ if (e.name.startsWith(".")) {
3653
+ // The only one of the three that needed a second LABEL and not just
3654
+ // a conditional slash, because this label names the kind out loud.
3655
+ // A `.DS_Store` reported as `.DS_Store/ (dot-directory, tooling)`
3656
+ // sends an auditor looking for a directory that is not there, and
3657
+ // auditing the waiver is the entire reason this list exists.
3658
+ skipped.push(
3659
+ declinedIsDir(e, join(dir, e.name))
3660
+ ? `${childRelEarly}/ (dot-directory, tooling)`
3661
+ : `${childRelEarly} (dot-file, tooling)`,
3662
+ );
3663
+ continue;
3664
+ }
3665
+ const childRel = childRelEarly;
3666
+ const abs = join(dir, e.name);
3667
+ // `isDirectory()` is false for a symlink, so the stat is what makes a
3668
+ // symlinked directory visible at all.
3669
+ let isDir = e.isDirectory();
3670
+ if (!isDir && e.isSymbolicLink()) {
3671
+ try {
3672
+ isDir = statSync(abs).isDirectory();
3673
+ } catch (err) {
3674
+ // A DANGLING symlink is not unmeasured — it is empty. It resolves
3675
+ // to nothing, so it cannot be hiding source, and counting it would
3676
+ // mean one broken link anywhere in a content project refuses
3677
+ // CONFIG-1 for the rest of the project's life. `unreadable` exists
3678
+ // for the case where source might be behind something we could not
3679
+ // open; that is a permission error, not a link to a file that does
3680
+ // not exist.
3681
+ //
3682
+ // The distinction is the ERRNO, not `existsSync`. The first draft
3683
+ // asked `existsSync(abs)`, which returns false for BOTH — so
3684
+ // `vendored -> /locked/inner`, with `/locked` at mode 000 and a
3685
+ // real config read inside, gave found=false, unreadable=[] and a
3686
+ // clean UNMEASURED. The code was invisible AND the walk did not
3687
+ // record that it could not look, which is the exact failure the
3688
+ // `unreadable` guard exists to prevent, reintroduced inside the
3689
+ // guard itself.
3690
+ if ((err as NodeJS.ErrnoException).code !== "ENOENT") unreadable.push(childRel);
3691
+ continue;
3692
+ }
3693
+ }
3694
+ if (isDir) {
3695
+ stack.push([abs, childRel]);
3696
+ } else if (!SOURCE_EXTENSIONS.test(e.name) && SCRIPT_LIKE.test(e.name)) {
3697
+ // Code in a language this check cannot read. sec-500's point, and
3698
+ // the reason keying on "extension-less" would have been too narrow:
3699
+ // a project whose only config-reading code is `lib/loader.py` or
3700
+ // `bin/run.sh` got `skipped: []` and the fallback sentence "the walk
3701
+ // found no files of any kind that it counts as source" — which is
3702
+ // LITERALLY TRUE, and that is exactly what would have let it outlive
3703
+ // the fix. Anywhere in the tree, not just the scan dirs, because
3704
+ // `bin/` is not a scan dir and `bin/run.sh` was the example.
3705
+ skipped.push(`${childRel} (${e.name.slice(e.name.lastIndexOf("."))} — not a language this check reads)`);
3706
+ } else if (
3707
+ !SOURCE_EXTENSIONS.test(e.name)
3708
+ && !e.name.includes(".")
3709
+ && CONFIG_SCAN_DIRS.some(d => childRel === d || childRel.startsWith(`${d}/`))
3710
+ ) {
3711
+ // An extension-less executable INSIDE a directory this check scans.
3712
+ // sec-500's sharpest case, and not hypothetical: this repo ships two
3713
+ // of them (`scripts/git-hooks/pre-commit`, `scripts/git-hooks/pre-push`).
3714
+ // A node or shell script with no extension reading the config is
3715
+ // invisible to `SOURCE_EXTENSIONS`, so the project reads as having no
3716
+ // code while carrying a live direct read in a scanned directory.
3717
+ //
3718
+ // Recorded, not counted: deciding these are source would make every
3719
+ // git hook, `Makefile` and CI shim project source, which is a much
3720
+ // larger change than this issue. Naming it is what stops the next
3721
+ // reader having to rediscover it.
3722
+ skipped.push(`${childRel} (extension-less file in a scanned directory)`);
3723
+ } else if (SOURCE_EXTENSIONS.test(e.name) && e.name.endsWith(".d.ts")) {
3724
+ skipped.push(`${childRel} (type declarations)`);
3725
+ } else if (SOURCE_EXTENSIONS.test(e.name) && isTestSourceFile(e.name)) {
3726
+ skipped.push(`${childRel} (test file)`);
3727
+ } else if (SOURCE_EXTENSIONS.test(e.name) && isRootToolConfig(childRel, e.name)) {
3728
+ skipped.push(`${childRel} (root tool config)`);
3729
+ } else if (SOURCE_EXTENSIONS.test(e.name)) {
3730
+ // The three exclusions that used to be repeated here —
3731
+ // `!endsWith(".d.ts")`, `!isTestSourceFile`, `!isRootToolConfig` —
3732
+ // are GONE, and their absence is the point. The `else if` chain
3733
+ // above already consumes each of those files to record the decline,
3734
+ // so re-asking here could never change the outcome: mutating any of
3735
+ // the three was 0 red against a prediction of 3, and the three
3736
+ // branches above were holding all of it up.
3737
+ //
3738
+ // Three collapsed pairs, introduced by the commit that added the
3739
+ // recording and caught by the battery rather than by reading. The
3740
+ // rubric offers two fixes and this is the first one — delete a
3741
+ // decider, do not feed it — because the recording branch has to
3742
+ // exist anyway and a second copy of its question cannot ever
3743
+ // disagree with it.
3744
+ // A symlinked FILE is containment-checked too. The directory check
3745
+ // above cannot see this case, so `linked.ts -> /outside/x.ts` made
3746
+ // `found` true on the strength of code outside the project — which
3747
+ // contradicts the invariant the directory check exists to state.
3748
+ // Checked here rather than assumed, because "the walk cannot leave
3749
+ // the project" is either true of both kinds of entry or it is not a
3750
+ // property at all.
3751
+ if (e.isSymbolicLink()) {
3752
+ try {
3753
+ if (!insideProject(realpathSync(abs))) {
3754
+ // Recorded. "I chose not to look" was rendering identically to
3755
+ // "there was nothing there", which is the distinction
3756
+ // `unreadable` exists to preserve — and a pnpm/npm-workspace
3757
+ // monorepo with `lib/impl -> ../../packages/core` is an
3758
+ // ordinary shape, not an attack. The containment decision is
3759
+ // right; the silence was not.
3760
+ skipped.push(`${childRel} (symlink pointing outside the project)`);
3761
+ continue;
3762
+ }
3763
+ } catch {
3764
+ continue;
3765
+ }
3766
+ }
3767
+ // The top-level segment, because CONFIG_SCAN_DIRS is matched at
3768
+ // the top level. `.` is a source file sitting at the root, which
3769
+ // the scan does not walk either — `index.ts` is an ordinary shape
3770
+ // and leaving it out would be the same blind spot one level up.
3771
+ const top = childRel.includes("/") ? childRel.slice(0, childRel.indexOf("/")) : ".";
3772
+ // Source another CHECK measures is not evidence that this one is
3773
+ // blind (#501). `workflows/w.ts` set `found`, so a project whose
3774
+ // only code is a workflow was told CONFIG-1 "DOES contain source …
3775
+ // none of it in the directories this check reads" — true, and
3776
+ // unsatisfiable, because CONFIG-1 declines that directory precisely
3777
+ // so CONFIG-2 can own it. Two red checks, neither fixable without
3778
+ // rewriting the project in another language.
3779
+ //
3780
+ // `CONFIG_1_DECLINES` and NOT `measuredElsewhere`, and the gap
3781
+ // between the two is deliberate: `test/` is excluded by ADR-002 D4
3782
+ // with nobody measuring it, so a project whose only source is a test
3783
+ // directory must still refuse — that is #500's own case, and
3784
+ // collapsing the two predicates would waive it.
3785
+ //
3786
+ // Recorded rather than skipped silently, so the UNMEASURED sentence
3787
+ // names the hand-off instead of implying the tree is empty.
3788
+ if (CONFIG_1_DECLINES.has(top)) {
3789
+ skipped.push(`${childRel} (measured by CONFIG-2, which reads ${top}/)`);
3790
+ continue;
3791
+ }
3792
+ if (!CONFIG_SCAN_DIRS.includes(top) && !measuredElsewhere(top)) {
3793
+ unscannedDirs.add(top);
3794
+ unscannedSourceCount++;
3795
+ }
3796
+ if (examples.length < 3) examples.push(childRel);
3797
+ }
3798
+ }
3799
+ }
3800
+ // Ranked, then alphabetical. `readdir` order is neither, so WHICH entries
3801
+ // survived the message's truncation differed per machine and per tree —
3802
+ // sec-500's point that a consumer and CI could be shown different lists,
3803
+ // which makes the message unciteable in a bug report. Ranking also puts
3804
+ // the classes that can plausibly hold first-party code above the ones
3805
+ // that cannot, so the truncation cuts the least useful entries first
3806
+ // rather than arbitrary ones.
3807
+ const rank = (entry: string) =>
3808
+ /\((?:symlink|directory resolving)/.test(entry) ? 0 // escaped the project
3809
+ : /\(extension-less|not a language this check reads/.test(entry) ? 1 // code, unparseable
3810
+ // `(?:\/|\s)` and not `\/`, because this fix removes the trailing
3811
+ // slash from a declined FILE and the slash was load-bearing here —
3812
+ // sec-518's F3. A file named `build` or `vendor` silently dropped
3813
+ // from rank 2 to rank 5, which is a second behavioural change riding
3814
+ // inside the first. Measured on one tree carrying both as files:
3815
+ // before `["build/", "vendor/", ".alpha/", "dist/"]`, after
3816
+ // `[".alpha/", "build", "dist/", "vendor"]`. Rank 2 is the right
3817
+ // answer for both spellings — the class is "generated from source",
3818
+ // and a build manifest is as generated as a build directory.
3819
+ : /^(?:build|vendor)(?:\/|\s)/.test(entry) ? 2 // generated-from-source
3820
+ : /\(dot-directory/.test(entry) ? 3 // tooling, can hold scripts
3821
+ : /\(test (?:file|directory)/.test(entry) ? 4
3822
+ : 5; // dist, coverage, .d.ts, and dot-FILES (#518):
3823
+ // `.github/` can hide a release script, which is
3824
+ // why it ranks 3. `.gitignore` cannot hide
3825
+ // anything, so the new class falls to the
3826
+ // default on purpose and the truncation cuts it
3827
+ // before anything that could hold code.
3828
+ skipped.sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
3829
+ return {
3830
+ found: examples.length > 0,
3831
+ examples,
3832
+ unreadable,
3833
+ skipped,
3834
+ unscannedSourceCount,
3835
+ unscannedDirs: [...unscannedDirs].sort(),
3836
+ };
3837
+ }
3838
+
3839
+ /**
3840
+ * Why an empty scan is UNMEASURED rather than a refusal — or `null` when it is
3841
+ * a refusal after all (#476).
3842
+ *
3843
+ * THREE conditions, not two, and the second and third were both missing from
3844
+ * the first version of this. A security review found five project layouts
3845
+ * carrying a real direct config read that flipped from FAIL to green:
3846
+ * `lib/loader.mjs`, `lib/loader.cjs`, `src/app.js`, `bin/cli.ts` and a
3847
+ * root-level `index.ts`. The waiver asked `isTypeScriptProject`, which
3848
+ * matches `.tsx?` under `TS_SOURCE_DIRS`, while the scan reads `.ts` AND
3849
+ * `.js` under a different list — so wherever the scan's reach exceeded the
3850
+ * predicate's, a blind check reported clean. `lib/loader.mjs` is the
3851
+ * sharpest: the file sits in the FIRST directory CONFIG-1 walks, and the
3852
+ * waiver told the consumer the project had no TypeScript. True sentence,
3853
+ * wrong inference.
3854
+ *
3855
+ * The replacement cannot have that defect by construction: `found` is
3856
+ * answered over every code extension in the whole tree, so it can never be
3857
+ * narrower than a scanner's filter. Widening a scanner later cannot open a
3858
+ * hole in it.
3859
+ */
3860
+ /**
3861
+ * Collapse the decline list by class, with a count and a capped sample.
3862
+ *
3863
+ * The first cut printed the first eight entries and ", and N more". On
3864
+ * rungate itself the list is 320 entries of which 310 are test files, so
3865
+ * the cap showed ten test files and hid everything else — including the two
3866
+ * extension-less scripts in scanned directories, which are the entries most
3867
+ * likely to explain a waiver and the ones sec-500 filed the issue about.
3868
+ *
3869
+ * Collapsing rather than dropping is sec-485's correction to my first
3870
+ * remedy, and it is the better shape for the reason that applies to this
3871
+ * whole field: **every decline stays distinguishable from an absence**, and
3872
+ * the reader still gets a message they can read. Dropping entries to shorten
3873
+ * the list reintroduces exactly the silence `skipped` exists to remove.
3874
+ *
3875
+ * The class is the parenthetical each decline already carries, and ordering
3876
+ * follows the ranked array, so the classes that can plausibly hold
3877
+ * first-party code come first.
3878
+ */
3879
+ function summariseDeclines(skipped: string[], sample = 3): string {
3880
+ const order: string[] = [];
3881
+ const byClass = new Map<string, string[]>();
3882
+ for (const entry of skipped) {
3883
+ const m = /^(.*) \(([^()]*)\)$/.exec(entry);
3884
+ const kind = m ? m[2] : "other";
3885
+ const path = m ? m[1] : entry;
3886
+ if (!byClass.has(kind)) {
3887
+ byClass.set(kind, []);
3888
+ order.push(kind);
3889
+ }
3890
+ byClass.get(kind)!.push(path);
3891
+ }
3892
+ return order
3893
+ .map(kind => {
3894
+ const paths = byClass.get(kind)!;
3895
+ const shown = paths.slice(0, sample).join(", ");
3896
+ // `kind: N (samples)` rather than `N kinds (samples)`. Pluralising
3897
+ // the class prose correctly means handling "test file" -> "test
3898
+ // files" but "dot-directory, tooling" -> "dot-directories, tooling"
3899
+ // and "type declarations" -> unchanged, and a regex that gets that
3900
+ // wrong prints "40 tests file" — which it did. Putting the count
3901
+ // after the label sidesteps the whole problem and reads better in a
3902
+ // list.
3903
+ return `${kind}: ${paths.length}` + (paths.length > sample ? ` (${shown}, …)` : ` (${shown})`);
3904
+ })
3905
+ .join("; ");
3906
+ }
3907
+
3908
+ /**
3909
+ * What CONFIG-1 did not read, when it read something (#492).
3910
+ *
3911
+ * `null` when the scan covered every source file the walk found — the
3912
+ * normal case, which must stay silent or the message becomes one more line
3913
+ * nobody reads.
3914
+ *
3915
+ * ## Why this exists on top of adding `src/` to the scan list
3916
+ *
3917
+ * Adding `src/` fixes the INSTANCE. This fixes the class, and the class is
3918
+ * what #492 is actually about: a hardcoded list of directories can be
3919
+ * wrong, and until now nothing noticed. A consumer who keeps their code in
3920
+ * `domain/`, `packages/`, `app/` or `internal/` would have hit the
3921
+ * identical defect the week after `src/` was added, and the only signal
3922
+ * would have been a PASS.
3923
+ *
3924
+ * The regression fixture uses a directory named `domain` for exactly that
3925
+ * reason — a name no list will ever contain, so the case cannot be
3926
+ * satisfied by extending the list. That is the fifth failure shape (#519)
3927
+ * applied in advance: the wrong fix here is "add src and move on", and it
3928
+ * is the cheap one.
3929
+ *
3930
+ * ## Why it reports both numbers
3931
+ *
3932
+ * "CONFIG-1 read 36 files" is uninterpretable. 36 of 426 is the finding.
3933
+ * The directory names are what make it actionable — without them a consumer
3934
+ * knows the check is partial and has nowhere to go.
3935
+ */
3936
+ export function coverageShortfall(scan: ConfigAccessScan, evidence: SourceEvidence): string | null {
3937
+ // Both guards are `=== 0`, and both are load-bearing at exactly that
3938
+ // point. ONE unread file is a shortfall and ONE scanned file is a scan,
3939
+ // and `test/config-access-conformity.test.ts` pins both boundaries —
3940
+ // because a threshold is the cheapest way to make this quiet.
3941
+ //
3942
+ // `unread < 20` is not hypothetical: before `measuredElsewhere` existed
3943
+ // this warning named 19 files on rungate's own tree, so 20 is precisely
3944
+ // the number someone reaches for to silence it. And `bytesScanned < 10`
3945
+ // in place of the file guard re-opens the one-byte hole recorded in
3946
+ // `.claude/rules/checks-must-be-able-to-fail.md`, one guard over from
3947
+ // where that entry already closed it. Both measured at 0 red before the
3948
+ // boundary cases were added (sec-492).
3949
+ if (scan.filesScanned === 0) return null; // the empty-scan refusal owns this case
3950
+ const unread = evidence.unscannedSourceCount;
3951
+ if (unread === 0) return null;
3952
+ const where = evidence.unscannedDirs.map(d => (d === "." ? "the project root" : `${d}/`)).join(", ");
3953
+ return (
3954
+ `UNMEASURED: CONFIG-1 read ${scan.filesScanned} file(s), and ${unread} more source ` +
3955
+ `file(s) live in directories it does not walk — ${where} — so a direct config read ` +
3956
+ `there is invisible to it. A PASS here means "clean in ` +
3957
+ `${CONFIG_SCAN_DIRS.map(d => `${d}/`).join(", ")}", not "clean". ` +
3958
+ `Nothing is necessarily wrong with this project; the check is partial, and a partial ` +
3959
+ `check reporting a clean result is indistinguishable from a complete one (ADR-002 D4).`
3960
+ );
3961
+ }
3962
+
3963
+ export function unmeasuredScanReason(
3964
+ scan: ConfigAccessScan,
3965
+ evidence: SourceEvidence,
3966
+ label: string,
3967
+ sourceKind: string,
3968
+ ): string | null {
3969
+ // Something was read, so the check measured. Asked first: a non-empty scan
3970
+ // is never waived no matter what else is true.
3971
+ if (scan.filesScanned > 0) return null;
3972
+ // The walk could not complete. "No code here" and "I could not look" are
3973
+ // the same silence, and only one of them is a reason to waive.
3974
+ if (evidence.unreadable.length > 0) return null;
3975
+ // There IS code and this check read none of it. That is a blind check, the
3976
+ // first row of the table above, and it must refuse.
3977
+ if (evidence.found) return null;
3978
+ // What the walk ACTUALLY established, which is narrower than "nothing is
3979
+ // there". It looked outside the scan dirs, found no source it counts, and
3980
+ // declined to look at these. Naming the declines is the whole fix: the
3981
+ // previous sentence asserted "no source files of any kind were found
3982
+ // anywhere in the tree", which is false for every skip class and is this
3983
+ // issue's own headline complaint — a true-sounding sentence the walk never
3984
+ // established — reintroduced in the waiver that #500 added.
3985
+ const declined =
3986
+ evidence.skipped.length > 0
3987
+ ? ` It declined ${evidence.skipped.length} entr${evidence.skipped.length === 1 ? "y" : "ies"}: ` +
3988
+ summariseDeclines(evidence.skipped) +
3989
+ `. So this is "no source this check counts", not "no files here".`
3990
+ : ` The walk found no files of any kind that it counts as source.`;
3991
+ return (
3992
+ `UNMEASURED: ${label} read no files because this project has no ${sourceKind}.` +
3993
+ `${declined} ` +
3994
+ `Nothing was checked, which is NOT the same as nothing being wrong — if this ` +
3995
+ `project grows ${sourceKind}, this check starts measuring again on the next run.`
3996
+ );
3997
+ }
3998
+
3999
+ /**
4000
+ * SUCCESS-1 — the project states what it is for, falsifiably (#485).
4001
+ *
4002
+ * `CLAUDE.md` calls `SUCCESS.md` the measure and the scaffold never wrote
4003
+ * one, so `specs/HARNESS-STANDARD.md` carried SC-822..824 asserting
4004
+ * properties of a file that did not exist in any consumer.
4005
+ *
4006
+ * Absent is UNMEASURED and present-but-unfilled is a REFUSAL, and the
4007
+ * asymmetry is the point: a project that never opted in has not failed at
4008
+ * anything, while a project that ran the generator and stopped has a
4009
+ * document that every "does it exist" check waves through. The second is
4010
+ * the case this check is for.
4011
+ */
4012
+ export function runSuccessDocValidation(root: string) {
4013
+ describe("SUCCESS.md (#485)", () => {
4014
+ test("SUCCESS-1: the project states what it is for, and how each claim fails", () => {
4015
+ const verdict = successViolations(readSuccessDoc(root), readSuccessTemplate());
4016
+ if (verdict.unmeasured) {
4017
+ addFinding({
4018
+ ruleId: "SUCCESS-1",
4019
+ severity: "WARN",
4020
+ file: "SUCCESS.md",
4021
+ message: verdict.unmeasured,
4022
+ });
4023
+ return;
4024
+ }
4025
+ for (const v of verdict.violations) {
4026
+ addFinding({
4027
+ ruleId: "SUCCESS-1",
4028
+ severity: "FAIL",
4029
+ file: "SUCCESS.md",
4030
+ message: v,
4031
+ fixCommand: "Fill in SUCCESS.md — see bunx rungate create-success",
4032
+ });
4033
+ }
4034
+ expect(verdict.violations, verdict.violations.join("\n")).toEqual([]);
4035
+ });
4036
+ });
4037
+ }
4038
+
3061
4039
  /**
3062
4040
  * CHECK-1 — direct config access in TypeScript sources (ADR-002 D4).
3063
4041
  *
@@ -3068,21 +4046,57 @@ export function runConfigAccessValidation(root: string) {
3068
4046
  describe("Config access (ADR-002 D1)", () => {
3069
4047
  test("CONFIG-1: only the loader reads the rungate config", () => {
3070
4048
  const scan = scanConfigAccess(root);
3071
- const violations = configAccessViolations(
4049
+ const evidence = projectSourceEvidence(root);
4050
+ const unmeasured = unmeasuredScanReason(
4051
+ scan,
4052
+ evidence,
4053
+ "CONFIG-1",
4054
+ `TypeScript or JavaScript in ${CONFIG_SCAN_DIRS.map(d => `${d}/`).join(", ")}`,
4055
+ );
4056
+ if (unmeasured) {
4057
+ addFinding({
4058
+ ruleId: "CONFIG-1",
4059
+ severity: "WARN",
4060
+ file: "",
4061
+ message: unmeasured,
4062
+ });
4063
+ return;
4064
+ }
4065
+ // #492: the scan read SOME files, and that is where nothing was
4066
+ // looking. Every guard above — the waiver, the source walk, the
4067
+ // decline list — is reached only when `filesScanned === 0`, so ONE
4068
+ // clean file in a scanned directory makes the whole apparatus
4069
+ // unreachable. Measured on one consumer: PASS, having read 36 of 426
4070
+ // TypeScript files, because `scripts/` is non-empty and the 390 files
4071
+ // in `src/` were never walked.
4072
+ //
4073
+ // Recorded rather than failed. The consumer has done nothing wrong —
4074
+ // their layout is ordinary and it is this check that cannot see it —
4075
+ // and a FAIL they cannot act on is a FAIL they will switch off. But
4076
+ // `0`, `{}`, `null` and `SKIP` are indistinguishable from success and
4077
+ // so is a PASS over 8% of a tree, which is why it is not silence.
4078
+ const shortfall = coverageShortfall(scan, evidence);
4079
+ if (shortfall) {
4080
+ addFinding({ ruleId: "CONFIG-1", severity: "WARN", file: "", message: shortfall });
4081
+ }
4082
+ const violations = configAccessViolationRecords(
3072
4083
  scan,
3073
4084
  readConfigAccessRatchet(root, "sources"),
3074
4085
  "CONFIG-1",
4086
+ true,
4087
+ evidence,
3075
4088
  );
3076
4089
  for (const v of violations) {
3077
4090
  addFinding({
3078
4091
  ruleId: "CONFIG-1",
3079
4092
  severity: "FAIL",
3080
- file: v.split(": ")[1]?.split(" ")[0] || "",
3081
- message: v,
4093
+ file: v.file,
4094
+ message: v.message,
3082
4095
  fixCommand: "Route the read through lib/config-loader.ts",
3083
4096
  });
3084
4097
  }
3085
- expect(violations, violations.join("\n")).toEqual([]);
4098
+ const messages = violations.map(v => v.message);
4099
+ expect(messages, messages.join("\n")).toEqual([]);
3086
4100
  });
3087
4101
  });
3088
4102
  }
@@ -3098,24 +4112,41 @@ export function runPromptConfigAccessValidation(root: string) {
3098
4112
  describe("Config access in workflows (ADR-002 D4)", () => {
3099
4113
  test("CONFIG-2: no workflow reaches the rungate config, prompts included", () => {
3100
4114
  const scan = scanPromptConfigAccess(root);
3101
- // A project with no workflows/ directory is not in violation; the
3102
- // empty-scan refusal above is for a scan that should have found files.
3103
- const violations = configAccessViolations(
4115
+ // A project with no workflows/ directory is not in violation. A project
4116
+ // that HAS one and read nothing out of it still refuses — the previous
4117
+ // waiver here was `scan.filesScanned > 0`, which could never be false
4118
+ // at the point it was read (#476).
4119
+ const unmeasured = unmeasuredScanReason(
4120
+ scan,
4121
+ { found: existsSync(join(root, "workflows")), examples: [], unreadable: [], skipped: [], unscannedSourceCount: 0, unscannedDirs: [] },
4122
+ "CONFIG-2",
4123
+ "workflows/ directory",
4124
+ );
4125
+ if (unmeasured) {
4126
+ addFinding({
4127
+ ruleId: "CONFIG-2",
4128
+ severity: "WARN",
4129
+ file: "",
4130
+ message: unmeasured,
4131
+ });
4132
+ return;
4133
+ }
4134
+ const violations = configAccessViolationRecords(
3104
4135
  scan,
3105
4136
  readConfigAccessRatchet(root, "workflows"),
3106
4137
  "CONFIG-2",
3107
- scan.filesScanned > 0,
3108
4138
  );
3109
4139
  for (const v of violations) {
3110
4140
  addFinding({
3111
4141
  ruleId: "CONFIG-2",
3112
4142
  severity: "FAIL",
3113
- file: v.split(": ")[1]?.split(" ")[0] || "",
3114
- message: v,
4143
+ file: v.file,
4144
+ message: v.message,
3115
4145
  fixCommand: "Point the prompt at the resolved-config artefact instead",
3116
4146
  });
3117
4147
  }
3118
- expect(violations, violations.join("\n")).toEqual([]);
4148
+ const messages = violations.map(v => v.message);
4149
+ expect(messages, messages.join("\n")).toEqual([]);
3119
4150
  });
3120
4151
  });
3121
4152
  }