rungate 0.5.0 → 0.7.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 (142) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
package/lib/compliance.ts CHANGED
@@ -10,6 +10,7 @@
10
10
  */
11
11
  import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from "fs";
12
12
  import { join, relative } from "path";
13
+ import { probeExternalTool, type ToolProbe, type ToolProbeOutcome } from "./tool-probe";
13
14
 
14
15
  // ── Types ──────────────────────────────────────────────────
15
16
 
@@ -30,6 +31,47 @@ export interface FileScore {
30
31
  reporailsFindings: number;
31
32
  reporailsQuality: number | null;
32
33
  findings: InstructionFinding[];
34
+ /**
35
+ * Which tools READ this file — not which found something in it (#755).
36
+ *
37
+ * A file on the surface gets a `FileScore` whether or not any tool ever
38
+ * looked at it, so `findings.length` is the only per-file evidence the
39
+ * report used to carry, and it cannot tell three states apart: the tool
40
+ * ran and found nothing, the tool ran and returned nothing because it
41
+ * broke, and the file genuinely improved. All three are zero findings.
42
+ * This is the reading the count is not.
43
+ */
44
+ scoredBy: ComplianceTool[];
45
+ }
46
+
47
+ /** The external tools Layer 1 scores with, in the order they are reported. */
48
+ export const COMPLIANCE_TOOLS = ["agnix", "reporails"] as const;
49
+
50
+ export type ComplianceTool = (typeof COMPLIANCE_TOOLS)[number];
51
+
52
+ /** A tool that did not answer, as the report names it. */
53
+ export interface UnmeasuredTool {
54
+ /** The tool's name in this report — not the command line it was probed with. */
55
+ tool: ComplianceTool;
56
+ outcome: ToolProbeOutcome;
57
+ /** The probe's own one-liner, carried through unedited. */
58
+ reason: string;
59
+ }
60
+
61
+ /**
62
+ * Whether this report measured what it claims to have measured.
63
+ *
64
+ * A scan that one of its two tools sat out is not a scan with a slightly
65
+ * smaller finding count — it is a scan of an unknown fraction of the surface,
66
+ * and the number it would print is indistinguishable from the number a clean
67
+ * run prints. `UNMEASURED` is the only value that is not.
68
+ */
69
+ export interface ComplianceReading {
70
+ reading: "MEASURED" | "UNMEASURED";
71
+ /** Every tool that did not answer, in probe order. Empty exactly when MEASURED. */
72
+ unmeasured: UnmeasuredTool[];
73
+ /** Names every tool that did not answer and why. Null exactly when MEASURED. */
74
+ reason: string | null;
33
75
  }
34
76
 
35
77
  export interface ComplianceReport {
@@ -41,6 +83,13 @@ export interface ComplianceReport {
41
83
  totalFindings: number;
42
84
  highCount: number;
43
85
  toolsAvailable: { agnix: boolean; reporails: boolean };
86
+ /**
87
+ * The whole probe per tool — outcome and reason, not just the boolean.
88
+ * `toolsAvailable` above is a projection of these and stays for the callers
89
+ * that only ever wanted "can I run this".
90
+ */
91
+ toolProbes: Record<ComplianceTool, ToolProbe>;
92
+ reading: ComplianceReading;
44
93
  }
45
94
 
46
95
  // ── Tool Runners ───────────────────────────────────────────
@@ -191,14 +240,118 @@ export function collectComplianceSurface(root: string, surface?: string[]): stri
191
240
  }
192
241
 
193
242
  // ── Tool Availability ──────────────────────────────────────
243
+ //
244
+ // The probe lives in `lib/tool-probe.ts` and has THREE outcomes (#626 AC-10).
245
+ // What was here returned `false` for "agnix is not installed", "npx ran and
246
+ // failed" and "the registry timed out" alike, which is why #597's CI failures
247
+ // could be re-run red to green on an identical SHA with nothing to read that
248
+ // said why. `available` below is the same boolean these two call sites always
249
+ // wanted — the difference is that it is now a projection of a reading that
250
+ // still knows which of the three happened.
251
+
252
+ /** How each tool is asked whether it is there. */
253
+ const COMPLIANCE_TOOL_PROBE_ARGV: Record<ComplianceTool, string[]> = {
254
+ agnix: ["agnix", "--version"],
255
+ reporails: ["npx", "@reporails/cli", "version"],
256
+ };
194
257
 
195
- function checkToolAvailable(command: string, args: string[]): boolean {
196
- try {
197
- const result = Bun.spawnSync([command, ...args], { timeout: 5_000 });
198
- return result.exitCode === 0 || result.stdout.toString().length > 0;
199
- } catch {
200
- return false;
258
+ /**
259
+ * The single seam between this module and the outside world (#597).
260
+ *
261
+ * Every availability question Layer 1 asks is asked here, once per tool, and
262
+ * `probeExternalTool` is called from nowhere else in this file — two deciders
263
+ * that agree are behaviourally one, and a second probe would survive any
264
+ * mutation of this one.
265
+ *
266
+ * A caller may supply a reading per tool. That is how a test forces a tool
267
+ * absent or errored without mutating `PATH`, which is both unavailable to a
268
+ * test running in-process and a global mutation that leaks into whatever else
269
+ * the suite is doing. An injected tool overrides; an omitted one still spawns,
270
+ * so the seam cannot silently drop a tool it was not told about.
271
+ */
272
+ export function probeComplianceTools(
273
+ injected?: Partial<Record<ComplianceTool, ToolProbe>>,
274
+ ): Record<ComplianceTool, ToolProbe> {
275
+ const probes = {} as Record<ComplianceTool, ToolProbe>;
276
+ for (const tool of COMPLIANCE_TOOLS) {
277
+ const given = injected?.[tool];
278
+ if (given) {
279
+ probes[tool] = given;
280
+ continue;
281
+ }
282
+ const [command, ...args] = COMPLIANCE_TOOL_PROBE_ARGV[tool];
283
+ probes[tool] = probeExternalTool(command, args);
201
284
  }
285
+ return probes;
286
+ }
287
+
288
+ /**
289
+ * Turns the probes into the report's own verdict about itself.
290
+ *
291
+ * One binding, so there is one thing to mutate, and so no branch can decide
292
+ * separately that a report is clean enough to print a number.
293
+ */
294
+ export function complianceReading(
295
+ probes: Record<ComplianceTool, ToolProbe>,
296
+ ): ComplianceReading {
297
+ const unmeasured: UnmeasuredTool[] = [];
298
+ for (const tool of COMPLIANCE_TOOLS) {
299
+ const probe = probes[tool];
300
+ if (probe.available) continue;
301
+ unmeasured.push({ tool, outcome: probe.outcome, reason: probe.reason });
302
+ }
303
+
304
+ if (unmeasured.length === 0) {
305
+ return { reading: "MEASURED", unmeasured: [], reason: null };
306
+ }
307
+
308
+ // Name every one of them. A warning that does not say what was missing is a
309
+ // warning nobody can act on, and "a tool was unavailable" does not tell an
310
+ // operator whether to install something or to look at a stderr line.
311
+ const named = unmeasured.map(u => `${u.tool} (${u.outcome}): ${u.reason}`).join("; ");
312
+ return {
313
+ reading: "UNMEASURED",
314
+ unmeasured,
315
+ reason:
316
+ `UNMEASURED: ${unmeasured.length} of ${COMPLIANCE_TOOLS.length} compliance tools did not ` +
317
+ `answer — ${named}. The quality score is withheld rather than averaged over the tools ` +
318
+ `that did, because a surface nobody scored has not passed and a number would say it had.`,
319
+ };
320
+ }
321
+
322
+ /**
323
+ * The surface's quality score, or nothing when the reading says nothing was
324
+ * measured.
325
+ *
326
+ * Averaging whatever came back is the shape this exists to refuse: with one
327
+ * tool silent the mean is taken over the files the other tool happened to
328
+ * reach, and it prints as an ordinary number beside an ordinary PASS.
329
+ */
330
+ export function overallQualityOf(
331
+ fileScores: FileScore[],
332
+ reading: ComplianceReading,
333
+ ): number | null {
334
+ if (reading.reading === "UNMEASURED") return null;
335
+ const scored = fileScores.filter(f => f.reporailsQuality !== null);
336
+ if (scored.length === 0) return null;
337
+ return scored.reduce((sum, f) => sum + f.reporailsQuality!, 0) / scored.length;
338
+ }
339
+
340
+ /**
341
+ * The tools that read one file, from a per-tool reading of whether they did.
342
+ *
343
+ * One binding, so a case can mutate the thing that decides coverage rather
344
+ * than a boolean each caller re-derives. The two tools report their having
345
+ * read a file by different routes and neither is a finding count:
346
+ *
347
+ * - agnix is run ONCE over the whole surface, and `runAgnixBatch` returns
348
+ * `null` when it produced nothing parseable. A batch that parsed read every
349
+ * file in it, including the clean ones it says nothing about.
350
+ * - RepoRails is run per file and returns a quality score for each, so its
351
+ * receipt is per file: an entry exists or it does not.
352
+ */
353
+ export function scoredByOf(read: Record<ComplianceTool, boolean>): ComplianceTool[] {
354
+ return COMPLIANCE_TOOLS.filter(tool => read[tool]);
202
355
  }
203
356
 
204
357
  // ── Layer 1: Template Compliance ───────────────────────────
@@ -206,6 +359,11 @@ function checkToolAvailable(command: string, args: string[]): boolean {
206
359
  export interface TemplateComplianceOpts {
207
360
  surface?: string[];
208
361
  writeReport?: boolean;
362
+ /**
363
+ * Readings to use instead of spawning. Per tool — an omitted tool is still
364
+ * probed for real.
365
+ */
366
+ probes?: Partial<Record<ComplianceTool, ToolProbe>>;
209
367
  }
210
368
 
211
369
  export async function runTemplateCompliance(
@@ -214,17 +372,24 @@ export async function runTemplateCompliance(
214
372
  ): Promise<ComplianceReport> {
215
373
  const files = collectComplianceSurface(root, opts?.surface);
216
374
 
217
- const agnixAvailable = checkToolAvailable("agnix", ["--version"]);
218
- const reporailsAvailable = checkToolAvailable("npx", ["@reporails/cli", "version"]);
375
+ const toolProbes = probeComplianceTools(opts?.probes);
376
+ const reading = complianceReading(toolProbes);
377
+ const agnixAvailable = toolProbes.agnix.available;
378
+ const reporailsAvailable = toolProbes.reporails.available;
219
379
 
220
380
  // agnix: batch mode works fine for file attribution
221
381
  const agnixByFile = new Map<string, AgnixDiagnostic[]>();
222
382
  // RepoRails: per-file mode — batch drops findings for small files
223
383
  const rrByFile = new Map<string, { quality: number | null; findings: RepoRailsFinding[] }>();
224
384
 
225
- if (agnixAvailable) {
385
+ // Whether the batch answered at all. `agnixAvailable` says the probe found
386
+ // the binary; this says the run over this surface produced a reading.
387
+ let agnixRead = false;
388
+
389
+ if (agnixAvailable && files.length > 0) {
226
390
  const results = runAgnixBatch(files);
227
391
  if (results) {
392
+ agnixRead = true;
228
393
  for (const d of results) {
229
394
  const key = d.file;
230
395
  if (!agnixByFile.has(key)) agnixByFile.set(key, []);
@@ -289,6 +454,7 @@ export async function runTemplateCompliance(
289
454
  reporailsFindings: findings.filter(f => f.source === "reporails").length,
290
455
  reporailsQuality,
291
456
  findings,
457
+ scoredBy: scoredByOf({ agnix: agnixRead, reporails: rrData !== undefined }),
292
458
  });
293
459
  }
294
460
 
@@ -298,20 +464,17 @@ export async function runTemplateCompliance(
298
464
  0,
299
465
  );
300
466
 
301
- const qualityScores = fileScores.filter(f => f.reporailsQuality !== null);
302
- const overallQuality = qualityScores.length > 0
303
- ? qualityScores.reduce((sum, f) => sum + f.reporailsQuality!, 0) / qualityScores.length
304
- : null;
305
-
306
467
  const report: ComplianceReport = {
307
468
  timestamp: new Date().toISOString(),
308
469
  layer: "template",
309
470
  surface: files.map(f => relative(root, f)),
310
471
  files: fileScores,
311
- overallQuality,
472
+ overallQuality: overallQualityOf(fileScores, reading),
312
473
  totalFindings,
313
474
  highCount,
314
475
  toolsAvailable: { agnix: agnixAvailable, reporails: reporailsAvailable },
476
+ toolProbes,
477
+ reading,
315
478
  };
316
479
 
317
480
  if (opts?.writeReport !== false) {
@@ -323,12 +486,15 @@ export async function runTemplateCompliance(
323
486
  );
324
487
  }
325
488
 
326
- if (!agnixAvailable) {
327
- console.warn("WARN TOOL-NOT-INSTALLED-agnix: agnix not found — install globally or via npm");
328
- }
329
- if (!reporailsAvailable) {
330
- console.warn("WARN TOOL-NOT-INSTALLED-reporails: @reporails/cli not found — install via npm");
489
+ // SC-183 keeps its marker, but only for the state it describes: a tool that
490
+ // ran and failed is not one that is missing, and telling an operator to
491
+ // install something already installed is the advice the collapsed boolean
492
+ // used to give.
493
+ for (const u of reading.unmeasured) {
494
+ if (u.outcome !== "absent") continue;
495
+ console.warn(`WARN TOOL-NOT-INSTALLED-${u.tool}: ${u.reason} — install it, then re-run`);
331
496
  }
497
+ if (reading.reason) console.warn(`WARN COMPLIANCE-${reading.reason}`);
332
498
 
333
499
  return report;
334
500
  }
@@ -348,6 +514,16 @@ export async function runGeneratedCompliance(
348
514
  `FAIL: Scaffold degraded instruction quality from ${baselineReport.overallQuality.toFixed(1)} to ${report.overallQuality.toFixed(1)}`
349
515
  );
350
516
  }
517
+ } else if (baselineReport) {
518
+ // A comparison that could not be made is not a comparison that passed.
519
+ // Both sides are reported, because "which one had no number" is the first
520
+ // thing anyone reading this will want to know.
521
+ console.warn(
522
+ `WARN COMPLIANCE-UNMEASURED: the Layer 2 degradation check did not run — ` +
523
+ `baseline ${baselineReport.reading.reading}/${baselineReport.overallQuality ?? "no score"}, ` +
524
+ `generated ${report.reading.reading}/${report.overallQuality ?? "no score"}` +
525
+ (report.reading.reason ? ` — ${report.reading.reason}` : ""),
526
+ );
351
527
  }
352
528
 
353
529
  const outDir = join(root, ".rungate");
@@ -107,6 +107,45 @@ export type ResolvedConfig = z.infer<typeof ResolvedConfigSchema>;
107
107
  /** ship.js:1705's fallback, kept identical so normalisation changes no run. */
108
108
  export const DEFAULT_TEST_TIMEOUT = 120000;
109
109
 
110
+ /**
111
+ * The config's path relative to a project root, in the directory layout.
112
+ *
113
+ * Exported because a reader sometimes has to NAME the file without reading
114
+ * it — `scripts/contract-parity.ts` compares what each position in a tree
115
+ * DECLARES, so it labels and plants the config by path. Writing that literal
116
+ * anywhere else is a CONFIG-1 violation and rightly so, and the fix for a
117
+ * label is the same as the fix for a read: get it from here, so there is one
118
+ * module that knows where the config lives.
119
+ */
120
+ export const RUNGATE_CONFIG_RELATIVE_PATH = join(".claude", "rungate", "config.json");
121
+
122
+ /**
123
+ * Every path a project's rungate config can occupy, in POSIX form, newest
124
+ * layout first (#505).
125
+ *
126
+ * Slash-separated and not `join`ed, because the one consumer outside this
127
+ * module compares them against `.gitignore` patterns and `git check-ignore`
128
+ * output, both of which are POSIX whatever the platform. A `path.join` here
129
+ * would produce backslashes on Windows and silently stop matching.
130
+ *
131
+ * It exists because a question about the config's LOCATION is the same
132
+ * question `resolveConfig` answers, and ADR-002 D1 centralises that for a
133
+ * reason — a second list is a second answer to drift from, and this one is
134
+ * consulted by a step that EDITS the project's ignore rules. A stale entry
135
+ * there does not produce a wrong reading; it produces a config file the
136
+ * project cannot commit.
137
+ */
138
+ export const RUNGATE_CONFIG_IGNORE_PATHS = [
139
+ ".claude/rungate/config.json",
140
+ ".claude/rungate.json",
141
+ ] as const;
142
+
143
+ /** The directory both of the above sit in. */
144
+ export const RUNGATE_CONFIG_PARENT_DIR = ".claude";
145
+
146
+ /** The directory layout's own directory, POSIX form, for the same consumer. */
147
+ export const RUNGATE_CONFIG_DIR = ".claude/rungate";
148
+
110
149
  /**
111
150
  * The resolution (ADR-002 D2(a)). `absent` is TRUTHY and carries no `.test`,
112
151
  * so the four sites that wrote `config?.test?.command || fallback` cannot
@@ -124,7 +163,18 @@ export type ConfigResolution =
124
163
  }
125
164
  | { status: "absent" };
126
165
 
127
- const DIRECTORY_CONFIG_FILES = ["config.json", "roles.json", "hooks.json", "compliance.json"];
166
+ /**
167
+ * The files the directory layout is made of.
168
+ *
169
+ * Exported because the scaffold's `.gitignore` negation has to name each one
170
+ * (#505): the negation re-includes `.claude/rungate/` and then re-excludes
171
+ * its contents, so a config file this list does not carry is a config file
172
+ * the project cannot commit — and losing `roles.json` to a branch switch is
173
+ * the same defect as losing `config.json`. One list, in the module that
174
+ * knows where the config lives, or the two drift and the symptom is a file
175
+ * that silently stops being version-controlled.
176
+ */
177
+ export const DIRECTORY_CONFIG_FILES = ["config.json", "roles.json", "hooks.json", "compliance.json"];
128
178
 
129
179
  /**
130
180
  * ADR-002 D3. `dev.*` is the authored canonical shape; `test.command` keeps