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
@@ -7,30 +7,66 @@
7
7
  * Extracted per SCAFFOLD-DECOMPOSITION-SPEC to keep scaffold-project.ts
8
8
  * as orchestrator-only (under 200 lines).
9
9
  */
10
- import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from "fs";
10
+ import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, statSync } from "fs";
11
+ import { readdirSorted } from "../readdir-sorted";
11
12
  import { join, basename, dirname } from "path";
12
13
  import { auditSpecs } from "../../scripts/audit-specs";
13
14
  import { generateAgentsMd as buildAgentsMdContent, generateScopedRules } from "../generators/agents-md";
14
15
  import { isHarnessItself } from "../harness-identity";
16
+ import { scanSpecs } from "../scanner";
17
+ import { projectStateDerivation, projectStateKeyFileNote } from "../project-state-derivation";
15
18
  import { generateAgentBriefs as buildAgentBriefsContent } from "../generators/agent-briefs";
16
19
  import { generateCodeMap as buildCodeMapContent } from "../generators/code-map";
17
20
  import { buildAgentMeta, DEFAULT_AGENT_META } from "../create-brief";
18
21
  import { buildDefaultRoles, buildDefaultHooks } from "./defaults";
19
22
  import {
20
- mergeManagedWorkflow,
23
+ mergeManagedWorkflowRecording,
21
24
  duplicateTopLevelKeys,
25
+ managedPreamble,
26
+ MANAGED_BANNER_PREFIX,
22
27
  movedTopLevelKeys,
28
+ WORKFLOW_OVERRIDE_COMMENT,
29
+ workflowOverrides,
30
+ type ComputedSubKeys,
31
+ type MergeProvenance,
23
32
  type MovedKey,
33
+ type RevokedSubKey,
24
34
  } from "./managed-workflow";
25
35
  import { PRE_PUSH_MANAGED_MARKER, prePushHookScript } from "./pre-push-hook";
36
+ import {
37
+ AI_REVIEW_JOB,
38
+ aiReviewScaffoldAction,
39
+ buildAuthDetectStep,
40
+ buildOutcomesHeader,
41
+ buildReviewRunStep,
42
+ vertexCiConfig,
43
+ } from "./ai-review-step";
44
+ import { CI_SUITE_FETCH_DEPTH, baseRefFetchDepth } from "../ci-history-depth";
45
+ import { CLAUDE_CODE_ACTION } from "../claude-code-action";
46
+ import { GOOGLE_AUTH_ACTION } from "../google-auth-action";
26
47
  import { loadComplianceConfig, tryLoadRungateConfig } from "../config-loader";
27
48
  import { organizeProjectReport } from "../organize";
28
49
  import type { ProjectScan, ProjectType, SpecEntry, TestFile, RefFile, DocRoute, Category } from "../generators/types";
29
- import { tier1Ere } from "../secret-patterns";
50
+ import {
51
+ TIER2_ALLOWED_VALUE_ERE,
52
+ TIER2_GREP_CASE_FLAG,
53
+ TIER3_ALLOWED_VALUE_ERE,
54
+ tier1Ere,
55
+ tier2Ere,
56
+ tier3Ere,
57
+ } from "../secret-patterns";
30
58
  import { healthPathIn } from "../liveness-contradiction";
59
+ import { localCalendarDay } from "../local-calendar-day";
31
60
  import { decideRuleWrite } from "../rule-provenance";
61
+ import { actionRef } from "../workflow-actions";
62
+ import { ciSetupStep } from "../ci-setup-step";
32
63
  import { DEFAULT_PROFILE, isRuleIncluded, type ScaffoldProfile } from "./profiles";
33
64
  import { referencedPaths } from "../agents-md-refs";
65
+ import { scanDocsDirectory } from "../doc-routing";
66
+ import { inferredTestCommand, testCommandDecision } from "../test-command";
67
+ import { declaredBunVersion, setupBunWith } from "../bun-version";
68
+ import { codeMapUnreferenced, unlistedSpecs } from "../spec-listing";
69
+ import { censusReport, stampWorkflow, workflowBody, workflowCensus } from "./workflow-census";
34
70
  import {
35
71
  readSuccessDoc,
36
72
  readSuccessTemplate,
@@ -40,11 +76,12 @@ import {
40
76
  } from "../success-doc";
41
77
  import { TS_SOURCE_DIRS, typeScriptSourceDirs, typecheckDecision } from "../typescript-project";
42
78
  import {
43
- OWNED_FILES,
44
79
  SCAFFOLD_REFUSE,
45
80
  decideOwnedWrite,
81
+ ownedFileFor,
46
82
  type WriteStrategy,
47
83
  } from "./owned-files";
84
+ import type { SectionSpec } from "../agents-md-sections";
48
85
 
49
86
  /**
50
87
  * Look for a declared health route in the places a server declares one.
@@ -115,18 +152,23 @@ export function safeWrite(filePath: string, content: string, label: string, acti
115
152
  * prose while being written by a helper that skips it.
116
153
  */
117
154
  export function ownedStrategy(label: string): WriteStrategy {
118
- for (const owned of OWNED_FILES) {
119
- if (owned.path === label) return owned.strategy;
120
- if (owned.path.includes("*")) {
121
- const [prefix, suffix] = owned.path.split("*");
122
- if (label.startsWith(prefix) && label.endsWith(suffix)) return owned.strategy;
123
- }
124
- }
125
155
  // An unlisted file is regenerated. The direction this is allowed to be
126
156
  // wrong in: a file nobody declared gets rewritten with the generator's
127
157
  // own output, which is recoverable. Defaulting to create-only would make
128
158
  // forgetting to declare a file look exactly like #208.
129
- return "regenerate";
159
+ return ownedFileFor(label)?.strategy ?? "regenerate";
160
+ }
161
+
162
+ /**
163
+ * Which section of this label carries forward, from the declaration (#655).
164
+ *
165
+ * `undefined` for every strategy that preserves nothing, and for a
166
+ * `section-preserving` row that forgot to declare one — which
167
+ * `test/scaffold-ownership.test.ts` refuses, because reading it here would
168
+ * make the omission resolve to AGENTS.md's heading and look deliberate.
169
+ */
170
+ export function ownedSections(label: string): SectionSpec | undefined {
171
+ return ownedFileFor(label)?.sections;
130
172
  }
131
173
 
132
174
  export function regenerateOwned(
@@ -177,7 +219,7 @@ export function regenerateOwned(
177
219
  return;
178
220
  }
179
221
  const existing = link ? readFileSync(filePath, "utf-8") : null;
180
- const decision = decideOwnedWrite(strategy, existing, content);
222
+ const decision = decideOwnedWrite(strategy, existing, content, ownedSections(label));
181
223
 
182
224
  if (decision.action === "preserve") {
183
225
  actions.push(
@@ -186,6 +228,15 @@ export function regenerateOwned(
186
228
  );
187
229
  return;
188
230
  }
231
+ if (decision.action === "refuse") {
232
+ // Not the same thing as `preserve`, and the advice is the opposite:
233
+ // `preserve` means the file on disk is yours and the generator stood
234
+ // down, so deleting it accepts the generator. This means the generator
235
+ // cannot produce an output that keeps a promise the spec makes, and
236
+ // deleting the file would destroy exactly the content at issue.
237
+ actions.push(`${SCAFFOLD_REFUSE}: ${label} not written — ${decision.reason}`);
238
+ return;
239
+ }
189
240
  if (decision.action === "unchanged") {
190
241
  actions.push(`UNCHANGED: ${label} (${decision.reason})`);
191
242
  return;
@@ -241,40 +292,6 @@ function loadHarnessConfig(root: string): any {
241
292
 
242
293
  // ── AGENTS.md generation and updates ───────────────────────────
243
294
 
244
- export function updateSpecsTable(agentsMdPath: string, actions: string[]): void {
245
- if (!existsSync(agentsMdPath)) return;
246
- const specsDir = join(dirname(agentsMdPath), "specs");
247
- if (!existsSync(specsDir)) return;
248
-
249
- const specFiles = readdirSync(specsDir).filter(f => f.endsWith(".md") && f !== "SPEC-TEMPLATE.md");
250
- if (specFiles.length === 0) return;
251
-
252
- const specRows: string[] = [];
253
- for (const f of specFiles) {
254
- const content = readFileSync(join(specsDir, f), "utf-8");
255
- const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
256
- let testable = "false";
257
- let governs = f.replace(/\.md$/, "");
258
- if (fmMatch) {
259
- const tMatch = fmMatch[1].match(/testable:\s*(true|false)/);
260
- if (tMatch) testable = tMatch[1];
261
- const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
262
- if (gMatch) governs = gMatch[1].trim();
263
- }
264
- specRows.push(`| ${f} | ${governs} | ${testable === "true" ? "yes" : "no"} |`);
265
- }
266
-
267
- const existing = readFileSync(agentsMdPath, "utf-8");
268
- const tablePattern = /(\|[^\n]*Spec[^\n]*\|\n\|[-| ]+\|\n)((?:\|[^\n]+\|\n)*)/;
269
- const match = existing.match(tablePattern);
270
- if (match) {
271
- const newTable = match[1] + specRows.join("\n") + "\n";
272
- const updated = existing.replace(tablePattern, newTable);
273
- writeFileSync(agentsMdPath, updated);
274
- actions.push("UPDATED: AGENTS.md specs table from frontmatter");
275
- }
276
- }
277
-
278
295
  export function injectEnvironmentSection(root: string, actions: string[]): void {
279
296
  const agentsMdPath = join(root, "AGENTS.md");
280
297
  if (!existsSync(agentsMdPath)) return;
@@ -390,7 +407,7 @@ export function generateAgentsMdContent(
390
407
  // Scan key files
391
408
  const keyFiles: Array<{ file: string; what: string; when: string }> = [
392
409
  { file: "AGENTS.md", what: "Project entry point", when: "Always first" },
393
- { file: "PROJECT-STATE.md", what: "Live status + handoff (generated from project-state.json — don't edit directly)", when: "Session start, always first after AGENTS.md" },
410
+ { file: "PROJECT-STATE.md", what: projectStateKeyFileNote(projectStateDerivation(projectPath)), when: "Session start, always first after AGENTS.md" },
394
411
  { file: "project-state.json", what: "Source of truth for project status", when: "When editing state" },
395
412
  ];
396
413
  const conditionalPatterns: Array<{ pattern: string; what: string; when: string }> = [
@@ -417,78 +434,36 @@ export function generateAgentsMdContent(
417
434
  }
418
435
  }
419
436
 
420
- // Scan specs
421
- const specsDir = join(projectPath, "specs");
422
- const specEntries: SpecEntry[] = [];
423
- if (existsSync(specsDir)) {
424
- const specFiles = readdirSync(specsDir).filter(f => f.endsWith(".md") && f !== "SPEC-TEMPLATE.md");
425
- for (const f of specFiles) {
426
- const content = readFileSync(join(specsDir, f), "utf-8");
427
- const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
428
- let governs = "";
429
- let testable = "TODO";
430
- if (fmMatch) {
431
- const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
432
- if (gMatch && gMatch[1].trim() !== "TODO" && gMatch[1].trim().length > 5) {
433
- governs = gMatch[1].trim().replace(/\|/g, "—").slice(0, 120);
434
- }
435
- const tMatch = fmMatch[1].match(/testable:\s*(.+)/);
436
- if (tMatch) testable = tMatch[1].trim();
437
- }
438
- specEntries.push({ file: f, governs, testable });
439
- }
440
-
441
- // Also scan specs subdirectories
442
- try {
443
- const specSubDirs = readdirSync(specsDir, { withFileTypes: true })
444
- .filter(d => d.isDirectory())
445
- .map(d => d.name);
446
- for (const sub of specSubDirs) {
447
- const subPath = join(specsDir, sub);
448
- const subFiles = readdirSync(subPath).filter(f => f.endsWith(".md") && f !== "INDEX.md");
449
- if (subFiles.length > 0) {
450
- const indexPath = join(subPath, "INDEX.md");
451
- let groupGoverns = `${sub} (${subFiles.length} specs)`;
452
- if (existsSync(indexPath)) {
453
- const indexContent = readFileSync(indexPath, "utf-8");
454
- const fmMatch = indexContent.match(/^---\n([\s\S]*?)\n---/);
455
- if (fmMatch) {
456
- const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
457
- if (gMatch && gMatch[1].trim().length > 5) {
458
- groupGoverns = gMatch[1].trim().replace(/\|/g, "—").slice(0, 120);
459
- }
460
- }
461
- }
462
- specEntries.push({ file: `${sub}/ (${subFiles.length} specs)`, governs: groupGoverns, testable: "yes" });
463
- }
464
- }
465
- } catch {}
466
- }
437
+ // Scan specs — delegated to `lib/scanner.ts`, which is the one derivation.
438
+ // This function used to carry its own copy, and the copy drifted three
439
+ // times (#827): it never set `criteriaNone`, so `STATES NO CRITERIA` was
440
+ // dropped from every row that earned it; it hardcoded `testable: "yes"` on
441
+ // group rows, a word `scanner.ts` notes "means false to the code and true
442
+ // to a reader"; and it filtered spec files by name instead of `isSpecFile`,
443
+ // which is how #382's two scans disagreed about `SPEC-TEMPLATE.md`. All
444
+ // three were fixed in `scanner.ts` alone, because nobody knew this existed.
445
+ const specEntries: SpecEntry[] = scanSpecs(projectPath);
467
446
 
468
447
  // Scan tests
469
448
  const testDir = existsSync(join(projectPath, "test")) ? "test" : existsSync(join(projectPath, "tests")) ? "tests" : null;
470
449
  const testEntries: TestFile[] = [];
471
450
  if (testDir) {
472
- for (const f of readdirSync(join(projectPath, testDir)).filter(f => f.endsWith(".test.ts"))) {
451
+ for (const f of readdirSorted(join(projectPath, testDir)).filter(f => f.endsWith(".test.ts"))) {
473
452
  const label = f.replace(".test.ts", "").replace(/-/g, " ");
474
453
  testEntries.push({ label, file: f });
475
454
  }
476
455
  }
477
456
 
478
- // Detect test command
479
- let testCmd = "bun test";
480
- if (existsSync(pkgPath)) {
481
- try {
482
- const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
483
- if (pkg.scripts?.test) testCmd = pkg.scripts.test;
484
- } catch {}
485
- }
457
+ // Detect test command — through the one binding (#488). This copy read
458
+ // package.json and nothing else, so AGENTS.md's Commands row ignored a
459
+ // `dev.testCmd` the agent briefs honoured and CI ignored both.
460
+ const testCmd = testCommandDecision(projectPath).command;
486
461
 
487
462
  // Scan reference files
488
463
  const refDir = join(projectPath, "reference");
489
464
  const refEntries: RefFile[] = [];
490
465
  if (existsSync(refDir)) {
491
- for (const f of readdirSync(refDir)) {
466
+ for (const f of readdirSorted(refDir)) {
492
467
  refEntries.push({ file: f, what: "Historical reference" });
493
468
  }
494
469
  }
@@ -541,42 +516,23 @@ export function generateAgentsMdContent(
541
516
  // Recursive — see the same fix in scanner.ts. This is a second copy of
542
517
  // scanDocRouting and it is the one the scaffold actually calls, so the
543
518
  // scanner fix alone changed no generated output at all (#91).
544
- const files = readdirSync(catPath, { recursive: true }).map(String).filter(f => f.endsWith(".md"));
519
+ const files = readdirSorted(catPath, { recursive: true }).filter(f => f.endsWith(".md"));
545
520
  docRouting.push({ need: `${cat.label} (${files.length} files)`, file: `${cat.dir}/` });
546
521
  } else {
547
522
  docRouting.push({ need: cat.label, file: `${cat.dir}/` });
548
523
  actions.push(`WARN: ${cat.dir}/ listed in routing but directory does not exist`);
549
524
  }
550
525
  }
551
- if (existsSync(docsDir)) {
552
- const allDocs = readdirSync(docsDir).filter(f => f.endsWith(".md"));
553
- for (const f of allDocs) {
554
- const docPath = join(docsDir, f);
555
- const content = readFileSync(docPath, "utf-8");
556
- const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
557
- let need = f.replace(/\.md$/, "").replace(/-/g, " ");
558
- if (fmMatch) {
559
- const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
560
- if (gMatch && gMatch[1].trim() !== "TODO") need = gMatch[1].trim();
561
- }
562
- docRouting.push({ need, file: `docs/${f}` });
563
- }
564
- const subDirs = readdirSync(docsDir, { withFileTypes: true })
565
- .filter(d => d.isDirectory() && !categories.some(c => c.dir === `docs/${d.name}`))
566
- .map(d => d.name);
567
- for (const sub of subDirs) {
568
- const subPath = join(docsDir, sub);
569
- const subFiles = readdirSync(subPath).filter(f => f.endsWith(".md"));
570
- if (subFiles.length > 0) {
571
- docRouting.push({ need: `${sub} (${subFiles.length} files)`, file: `docs/${sub}/` });
572
- }
573
- }
574
- }
575
- const filteredRouting = docRouting.filter(d => {
576
- const slug = d.file.replace(/\.md$/, "").replace(/.*\//, "").toLowerCase().replace(/-/g, " ");
577
- const needLower = d.need.toLowerCase();
578
- return !needLower.startsWith(slug) || d.need.includes("—") || d.need.includes("(");
579
- });
526
+ // Through the one binding (#617, #619). This was a complete second copy of
527
+ // `scanDocRouting`, with its own inline `governs:` regex — and it is the copy
528
+ // the scaffold actually calls, so a fix applied only to the scanner changes
529
+ // no generated output at all (#91).
530
+ docRouting.push(...scanDocsDirectory(docsDir, categories.map(c => c.dir)));
531
+
532
+ // The "filter to non-obvious mappings" is deleted here for the same reason
533
+ // as in lib/scanner.ts: it could only ever drop a top-level `docs/*.md`, and
534
+ // dropping those is #617. See lib/doc-routing.ts.
535
+ const filteredRouting = docRouting;
580
536
 
581
537
  const consumers = harness?.consumers || [];
582
538
 
@@ -661,8 +617,14 @@ export function generateAgentsMdContent(
661
617
  * Re-running the generator is safe and cheap: `generateAgentsMdContent` writes
662
618
  * only the rules, and returns AGENTS.md content for its caller to write. The
663
619
  * return value is discarded here on purpose — AGENTS.md has already been
664
- * through `updateSpecsTable` and `injectEnvironmentSection` by this point, and
665
- * rewriting it would undo both.
620
+ * through `injectEnvironmentSection` by this point, and rewriting it would
621
+ * undo that.
622
+ *
623
+ * It used to say `updateSpecsTable` as well. That function ran immediately
624
+ * after the generator had rewritten AGENTS.md, edited an EXISTING table
625
+ * matched on a header row containing `Spec`, and the generator emits no such
626
+ * table — so the match never succeeded, the `if` had no `else`, and its
627
+ * action string never once appeared in a report. It is deleted (#382).
666
628
  */
667
629
  export function refreshScopedRulesStep(
668
630
  root: string,
@@ -724,19 +686,23 @@ export function refreshAgentsMd(root: string, type: ProjectType, actions: string
724
686
  } catch (e: unknown) { console.warn('Staleness check failed for', ref, (e as Error).message); }
725
687
  }
726
688
 
727
- // Check specs table
728
- const specsDir = join(root, "specs");
729
- if (existsSync(specsDir)) {
730
- const actualSpecs = readdirSync(specsDir).filter(f => f.endsWith(".md"));
731
- const unlisted = actualSpecs.filter(f => !content.includes(f));
732
- if (unlisted.length > 0) {
733
- issues.push(`UNLISTED specs: ${unlisted.join(", ")} (in specs/ but not in AGENTS.md)`);
734
- }
689
+ // Check specs table.
690
+ //
691
+ // Across AGENTS.md AND `.claude/rules/`, because D-15 capped AGENTS.md at
692
+ // 100 lines and moved both tables there (#382). Asked of `lib/spec-listing.ts`
693
+ // rather than inline: this site had its own idea of what counts as a spec —
694
+ // every `.md` in `specs/`, including `SPEC-TEMPLATE.md` — and the routing
695
+ // generator had another, so the one entry that could never be listed
696
+ // anywhere was reported on every run.
697
+ const unlisted = unlistedSpecs(root);
698
+ if (unlisted.length > 0) {
699
+ issues.push(`UNLISTED specs: ${unlisted.join(", ")} (in specs/ but not in AGENTS.md or .claude/rules/)`);
735
700
  }
736
701
 
737
- // Check CODE-MAP.md reference
738
- if (existsSync(join(root, "CODE-MAP.md")) && !content.includes("CODE-MAP")) {
739
- issues.push("CODE-MAP.md exists but not referenced in AGENTS.md routing table");
702
+ // Check CODE-MAP.md reference — same surfaces, same reason. It is named in
703
+ // the first row of `.claude/rules/docs-routing.md`.
704
+ if (codeMapUnreferenced(root)) {
705
+ issues.push("CODE-MAP.md exists but not referenced in AGENTS.md or .claude/rules/");
740
706
  }
741
707
 
742
708
  if (issues.length > 0 || staleFiles.length > 0) {
@@ -782,7 +748,7 @@ export function generateConformityTest(root?: string): string {
782
748
  const from = root && isHarnessItself(root) ? "../lib/conformity" : "rungate/lib/conformity";
783
749
  return `import { resolve } from "path";
784
750
  import { afterAll } from "bun:test";
785
- import { runScaffoldConformity, runSpecDiscovery, runSpecDrift, runDocHygiene, runFallowCheck, runAgentFileValidation, runDirectoryValidation, runPackageValidation, runTsconfigValidation, runConfigAccessValidation, runPromptConfigAccessValidation, runSuccessDocValidation, writeFindingsReport } from "${from}";
751
+ import { runScaffoldConformity, runSpecDiscovery, runSpecDrift, runDocHygiene, runFallowCheck, runAgentFileValidation, runDirectoryValidation, runPackageValidation, runTsconfigValidation, runConfigAccessValidation, runPromptConfigAccessValidation, runSuccessDocValidation, runAiReviewValidation, runBranchProtectionValidation, runWorkflowDriftValidation, writeFindingsReport } from "${from}";
786
752
 
787
753
  const ROOT = resolve(import.meta.dir, "..");
788
754
 
@@ -798,6 +764,9 @@ runTsconfigValidation(ROOT);
798
764
  runConfigAccessValidation(ROOT);
799
765
  runPromptConfigAccessValidation(ROOT);
800
766
  runSuccessDocValidation(ROOT);
767
+ runAiReviewValidation(ROOT);
768
+ runBranchProtectionValidation(ROOT);
769
+ runWorkflowDriftValidation(ROOT);
801
770
 
802
771
  afterAll(() => writeFindingsReport(ROOT));
803
772
  `;
@@ -805,7 +774,26 @@ afterAll(() => writeFindingsReport(ROOT));
805
774
 
806
775
  // ── Agent briefs generation ────────────────────────────────────
807
776
 
808
- export function generateAgentBriefsStep(root: string, actions: string[]): void {
777
+ export function generateAgentBriefsStep(
778
+ root: string,
779
+ actions: string[],
780
+ opts: {
781
+ /**
782
+ * Where the brief templates live. Defaults to the harness's own
783
+ * `templates/agent-briefs/`, which is what every production caller
784
+ * wants and what makes the templates harness-wide (#655).
785
+ *
786
+ * The seam exists because the `section-preserving` refusal below can
787
+ * only fire when the GENERATED brief carries the project-owned heading
788
+ * itself, and no input `root` accepts can produce that — the identity
789
+ * extractor stops at the first `\n##` and the README fallback flattens
790
+ * newlines. Without a seam the refusal would be reachable in
791
+ * production and unreachable in a test, which is the shape
792
+ * `.claude/rules/checks-must-be-able-to-fail.md` is about.
793
+ */
794
+ templatesDir?: string;
795
+ } = {},
796
+ ): void {
809
797
  const agentsDir = join(root, ".claude", "agents");
810
798
  safeDir(agentsDir, ".claude/agents", actions);
811
799
 
@@ -847,7 +835,7 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
847
835
  marcus: [], quinn: [], rook: [], serena: [], aditi: [], discovery: []
848
836
  };
849
837
  if (existsSync(promptsDir)) {
850
- const promptFiles = readdirSync(promptsDir).filter(f => f.endsWith(".md"));
838
+ const promptFiles = readdirSorted(promptsDir).filter(f => f.endsWith(".md"));
851
839
  for (const f of promptFiles) {
852
840
  const content = readFileSync(join(promptsDir, f), "utf-8");
853
841
  const lower = f.toLowerCase();
@@ -878,7 +866,8 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
878
866
  const consumers = harness?.consumers || [];
879
867
 
880
868
  // Resolve templates directory relative to this module
881
- const harnessTemplatesDir = join(dirname(dirname(__dirname)), "templates", "agent-briefs");
869
+ const harnessTemplatesDir =
870
+ opts.templatesDir ?? join(dirname(dirname(__dirname)), "templates", "agent-briefs");
882
871
 
883
872
  // buildAgentMeta takes the whole harness config and reads .roles itself.
884
873
  // Passing harness?.roles made it look for roles.roles, so every consumer's
@@ -910,7 +899,7 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
910
899
  identity: projectIdentity,
911
900
  techStack: [],
912
901
  repoUrl: "",
913
- testCmd: harness?.dev?.testCmd || "bun test",
902
+ testCmd: testCommandDecision(root).command,
914
903
  keyFiles: [],
915
904
  specs: [],
916
905
  testFiles: [],
@@ -937,8 +926,40 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
937
926
 
938
927
  for (const [agentName, content] of Object.entries(briefs)) {
939
928
  const p = join(agentsDir, `${agentName}.md`);
940
- writeFileSync(p, content);
941
- actions.push(existsSync(p) ? `UPDATED: .claude/agents/${agentName}.md` : `CREATED: .claude/agents/${agentName}.md`);
929
+ const label = `.claude/agents/${agentName}.md`;
930
+ // #654. The probe is taken BEFORE the write it describes. Asked
931
+ // afterwards it is true on every path that reaches it — `writeFileSync`
932
+ // either succeeded, in which case the file is there, or threw, in which
933
+ // case this line never runs — so the `CREATED:` arm was unreachable and
934
+ // a consumer scaffolding for the first time was told its briefs were
935
+ // updated.
936
+ const existedBefore = existsSync(p);
937
+
938
+ // #655. The write used to be a bare `writeFileSync(p, content)` — no
939
+ // `decideOwnedWrite`, no strategy read, nothing. The row in
940
+ // `OWNED_FILES` said `regenerate` and a bare overwrite happens to
941
+ // behave like `regenerate`, so nothing ever disagreed and the
942
+ // declaration test could not see it: reading a strategy is not the same
943
+ // as honouring it. Flipping the row alone would have changed nothing
944
+ // here; this is the other half.
945
+ const existing = existedBefore ? readFileSync(p, "utf-8") : null;
946
+ const decision = decideOwnedWrite(
947
+ ownedStrategy(label),
948
+ existing,
949
+ content,
950
+ ownedSections(label),
951
+ );
952
+
953
+ if (decision.action === "refuse" || decision.action === "preserve") {
954
+ actions.push(`${SCAFFOLD_REFUSE}: ${label} not written — ${decision.reason}`);
955
+ continue;
956
+ }
957
+ if (decision.action === "unchanged") {
958
+ actions.push(`UNCHANGED: ${label} (${decision.reason})`);
959
+ continue;
960
+ }
961
+ writeFileSync(p, decision.content!);
962
+ actions.push(`${existedBefore ? "UPDATED" : "CREATED"}: ${label}`);
942
963
  }
943
964
  }
944
965
 
@@ -969,7 +990,7 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
969
990
  // Scan pages from dashboard/src/pages/*.tsx (file-based routing)
970
991
  const dashboardPagesDir = join(root, "dashboard", "src", "pages");
971
992
  if (existsSync(dashboardPagesDir)) {
972
- const pageFiles = readdirSync(dashboardPagesDir).filter(f => f.endsWith(".tsx") || f.endsWith(".jsx"));
993
+ const pageFiles = readdirSorted(dashboardPagesDir).filter(f => f.endsWith(".tsx") || f.endsWith(".jsx"));
973
994
  for (const f of pageFiles) {
974
995
  const componentName = f.replace(/\.(tsx|jsx)$/, "");
975
996
  // Convert CamelCase to kebab-case route path
@@ -980,13 +1001,12 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
980
1001
  }
981
1002
  }
982
1003
 
983
- // Scan test commands
1004
+ // `inferredTestCommand`, not the full decision (#488). This value is what
1005
+ // gets WRITTEN into `dev.testCmd`, so reading `dev.testCmd` to choose it
1006
+ // is circular — and this step runs against trees whose config is
1007
+ // malformed, which is what it exists to repair.
1008
+ const testCmd = inferredTestCommand(root).command;
984
1009
  const pkgPath = join(root, "package.json");
985
- let testCmd = "bun test";
986
- if (existsSync(pkgPath)) {
987
- const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
988
- if (pkg.scripts?.test) testCmd = pkg.scripts.test;
989
- }
990
1010
  // #87 — this defaulted to `bunx tsc --noEmit` for every project, including
991
1011
  // one with no tsconfig, and `gates/gate-executor.ts` RUNS what lands here.
992
1012
  // Without a tsconfig that command prints 147 lines of help and exits 1, so
@@ -1071,7 +1091,7 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
1071
1091
  const srcDir = join(root, "src");
1072
1092
  if (existsSync(srcDir)) {
1073
1093
  const consumerPatterns = ["-routes.ts", "-generator.ts", "-plan.ts", "-intel.ts"];
1074
- for (const f of readdirSync(srcDir).filter(f => f.endsWith(".ts"))) {
1094
+ for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts"))) {
1075
1095
  const content = readFileSync(join(srcDir, f), "utf-8");
1076
1096
  const isConsumer = consumerPatterns.some(p => f.includes(p)) ||
1077
1097
  content.includes("app.get(") || content.includes("app.post(") ||
@@ -1158,7 +1178,14 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
1158
1178
  envVars: envVars || [],
1159
1179
  ci: {
1160
1180
  runner: "ubuntu-latest",
1161
- bunVersion: "latest",
1181
+ // Detected, never defaulted (#346, #622). `"latest"` here wrote an
1182
+ // UNPINNED runtime into every greenfield project's CI and called it a
1183
+ // configuration: the job installs whatever shipped this morning, so
1184
+ // re-running a red build is also a Bun upgrade. The bun that ran the
1185
+ // scaffold is a measurement of what this project has been built with,
1186
+ // which is the honest thing to write down, and the operator can change
1187
+ // it in one place afterwards.
1188
+ bunVersion: Bun.version,
1162
1189
  branches: ["main"],
1163
1190
  },
1164
1191
  contextDocs: {},
@@ -1449,7 +1476,17 @@ function writeDirectoryStructure(
1449
1476
  * so no later scaffold ever corrected it. Running this step last is what makes
1450
1477
  * that skip safe — the content it preserves is now right from run 1.
1451
1478
  */
1452
- export function generateCodeMapStep(root: string, actions: string[]): void {
1479
+ export function generateCodeMapStep(
1480
+ root: string,
1481
+ actions: string[],
1482
+ // #654 — the one injection seam, so the branch where the generator exits 0
1483
+ // and writes nothing can be entered. There is no input to the real
1484
+ // generator that provokes it, and a branch no test can enter is the thing
1485
+ // `.claude/rules/checks-must-be-able-to-fail.md` is about. Optional and
1486
+ // defaulted to the real script, so every caller is unchanged and a test
1487
+ // that forgets it is testing the real thing.
1488
+ opts: { generatorPath?: string } = {},
1489
+ ): void {
1453
1490
  // No dry-run branch. It reported `GAP: CODE-MAP.md missing` and nothing
1454
1491
  // else — one of the four `existsSync` checks that stood in for twenty-five
1455
1492
  // write steps and made audit report 0 changes on a tree `--fix` rewrote in
@@ -1481,11 +1518,31 @@ export function generateCodeMapStep(root: string, actions: string[]): void {
1481
1518
  }
1482
1519
 
1483
1520
  // Run generate-code-map.ts if available
1484
- const scriptPath = join(dirname(dirname(__dirname)), "scripts", "generate-code-map.ts");
1521
+ const scriptPath =
1522
+ opts.generatorPath ?? join(dirname(dirname(__dirname)), "scripts", "generate-code-map.ts");
1485
1523
  if (existsSync(scriptPath)) {
1524
+ // #654, and the same shape as the brief loop above with one extra arm.
1525
+ // Asked after the generator ran, `existsSync` answered two questions at
1526
+ // once and got both wrong: a successful generation reported `UPDATED:`
1527
+ // whether or not the file was new, and a generator that exits 0 WITHOUT
1528
+ // writing reported `CREATED:` for a file that is not there. The second
1529
+ // is the one that matters — `lib/scaffold/rehearsal.ts:481` records the
1530
+ // same defect at a site that was fixed, and it survived here because
1531
+ // the note was attached to the site rather than to the shape.
1532
+ const existedBefore = existsSync(codeMapPath);
1486
1533
  const result = Bun.spawnSync(["bun", scriptPath, root], { timeout: 60_000 });
1487
1534
  if (result.exitCode === 0) {
1488
- actions.push(existsSync(codeMapPath) ? "UPDATED: CODE-MAP.md" : "CREATED: CODE-MAP.md");
1535
+ const existsNow = existsSync(codeMapPath);
1536
+ actions.push(
1537
+ !existsNow
1538
+ // Neither created nor updated: the generator reported success and
1539
+ // produced nothing, which is a measurement that did not happen
1540
+ // and must not read as one that did.
1541
+ ? "UNMEASURED: CODE-MAP.md — the generator exited 0 and wrote no file"
1542
+ : existedBefore
1543
+ ? "UPDATED: CODE-MAP.md"
1544
+ : "CREATED: CODE-MAP.md",
1545
+ );
1489
1546
  } else {
1490
1547
  actions.push("WARN: CODE-MAP.md generation failed via script — trying inline");
1491
1548
  generateCodeMapInline(root, codeMapPath, actions);
@@ -1499,13 +1556,13 @@ function generateCodeMapInline(root: string, outPath: string, actions: string[])
1499
1556
  const name = basename(root);
1500
1557
  const skip = new Set(["node_modules", ".git", "reference", "dist", "build", ".next", ".fallow"]);
1501
1558
  const dirs: Array<{ name: string; fileCount: number; types: string[] }> = [];
1502
- for (const entry of readdirSync(root)) {
1559
+ for (const entry of readdirSorted(root)) {
1503
1560
  if (entry.startsWith(".") && entry !== ".claude") continue;
1504
1561
  if (skip.has(entry)) continue;
1505
1562
  const full = join(root, entry);
1506
1563
  try {
1507
1564
  if (!statSync(full).isDirectory()) continue;
1508
- const files = readdirSync(full, { recursive: true }).map(String);
1565
+ const files = readdirSorted(full, { recursive: true });
1509
1566
  const exts = new Set(files.map(f => f.split(".").pop()).filter((e): e is string => Boolean(e)));
1510
1567
  dirs.push({ name: entry, fileCount: files.length, types: [...exts].slice(0, 5) });
1511
1568
  } catch {}
@@ -1525,7 +1582,7 @@ function generateCodeMapInline(root: string, outPath: string, actions: string[])
1525
1582
  const srcDir = join(root, "src");
1526
1583
  const modules: Array<{ file: string; exports: string[] }> = [];
1527
1584
  if (existsSync(srcDir)) {
1528
- for (const f of readdirSync(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
1585
+ for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
1529
1586
  const content = readFileSync(join(srcDir, f), "utf-8");
1530
1587
  const exports: string[] = [];
1531
1588
  const exportPattern = /export\s+(?:function|const|class|type|interface)\s+(\w+)/g;
@@ -1538,7 +1595,7 @@ function generateCodeMapInline(root: string, outPath: string, actions: string[])
1538
1595
  // Detect API routes
1539
1596
  const routes: Array<{ method: string; path: string; file: string }> = [];
1540
1597
  if (existsSync(srcDir)) {
1541
- for (const f of readdirSync(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
1598
+ for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
1542
1599
  const content = readFileSync(join(srcDir, f), "utf-8");
1543
1600
  const routePatterns = [
1544
1601
  /app\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/gi,
@@ -1599,7 +1656,7 @@ export function copySpecTemplateIfEmpty(specsDir: string, actions: string[]): vo
1599
1656
  if (!existsSync(specsDir)) return;
1600
1657
 
1601
1658
  // Skip if specs/ already has .md files (besides SPEC-TEMPLATE.md itself)
1602
- const existingSpecs = readdirSync(specsDir).filter(
1659
+ const existingSpecs = readdirSorted(specsDir).filter(
1603
1660
  f => f.endsWith(".md") && f !== "SPEC-TEMPLATE.md"
1604
1661
  );
1605
1662
  if (existingSpecs.length > 0) {
@@ -1779,7 +1836,20 @@ export function missingGitignorePatterns(existing: string): string[] {
1779
1836
  .map(l => l.trim())
1780
1837
  .filter(l => l !== "" && !l.startsWith("#")),
1781
1838
  );
1782
- return requiredGitignorePatterns().filter(p => !present.has(p));
1839
+ // #586: `X/` is satisfied by an existing `X`, and ONLY in that direction.
1840
+ // This repo's `.gitignore` opens with `node_modules` and the required
1841
+ // pattern is `node_modules/`, so exact matching reported it absent and
1842
+ // every scaffold run re-added a line that changes nothing.
1843
+ //
1844
+ // The direction is the whole safety argument, and it is the opposite of
1845
+ // the trap the docstring above names. A bare `node_modules` matches files
1846
+ // AND directories, so it is STRICTLY BROADER than `node_modules/` — the
1847
+ // requirement is already met. `service-account` present against a required
1848
+ // `service-account*` is the reverse: the required pattern is broader, the
1849
+ // requirement is NOT met, and that case must keep failing.
1850
+ const satisfied = (p: string): boolean =>
1851
+ present.has(p) || (p.endsWith("/") && present.has(p.slice(0, -1)));
1852
+ return requiredGitignorePatterns().filter(p => !satisfied(p));
1783
1853
  }
1784
1854
 
1785
1855
  export function createGitignore(root: string, actions: string[]): void {
@@ -1809,7 +1879,7 @@ export function generateProjectState(root: string, actions: string[]): void {
1809
1879
  return;
1810
1880
  }
1811
1881
 
1812
- const today = new Date().toISOString().split("T")[0];
1882
+ const today = localCalendarDay();
1813
1883
 
1814
1884
  interface SC { id: string; what: string; done: boolean; }
1815
1885
  const scs: SC[] = [];
@@ -1934,7 +2004,7 @@ export function seedSuccessDoc(root: string, actions: string[]): void {
1934
2004
  return;
1935
2005
  }
1936
2006
 
1937
- const today = new Date().toISOString().slice(0, 10);
2007
+ const today = localCalendarDay();
1938
2008
  const owner = process.env.USER || "TODO-OWNER";
1939
2009
  // The SHARED substitution. Writing the template raw here while
1940
2010
  // `create-success` substituted meant one seed with two possible byte
@@ -2031,6 +2101,26 @@ export interface ManagedWrite {
2031
2101
  * was being made.
2032
2102
  */
2033
2103
  movedKeys: MovedKey[];
2104
+ /**
2105
+ * Derived grants the merge withdrew because the generator stopped computing
2106
+ * them (#923).
2107
+ *
2108
+ * Not a refusal and not an overwrite — a third thing, and it needs its own
2109
+ * field because the other two would both misreport it. In `lostLines` it is
2110
+ * a refusal over two lines the harness wrote itself; in `overwrittenLines`
2111
+ * it is a report that says "in harness-owned jobs" about a top-level key.
2112
+ *
2113
+ * Reported rather than silent, because the removal is the whole point: a
2114
+ * consumer who removes `ci.vertex` keeps `id-token: write` — the right to
2115
+ * mint an OIDC token for a federation that no longer exists — and a
2116
+ * permission nobody consumes is a permission nobody audits. Taking it away
2117
+ * without saying so would make the scaffold do, silently, the one thing
2118
+ * `ci.workflowOverrides` was built to guarantee is always visible.
2119
+ *
2120
+ * The record travels from the merge rather than being recomputed here. See
2121
+ * `mergeManagedWorkflowRecording`.
2122
+ */
2123
+ revokedGrants: RevokedSubKey[];
2034
2124
  /** Non-null ⇒ the write must not happen. Names the dropped jobs and the line delta. */
2035
2125
  refusal: string | null;
2036
2126
  }
@@ -2128,10 +2218,11 @@ function measureWrite(existing: string | null, next: string): { verb: ManagedWri
2128
2218
  * test/scaffold-ci-preservation-mutation.test.ts performs, so that
2129
2219
  * "preservation works" is a claim with a demonstrated way of being false.
2130
2220
  */
2131
- export function resolveManagedWrite(existing: string | null, generated: string): ManagedWrite {
2221
+ export function resolveManagedWrite(existing: string | null, generated: string, overrides: readonly string[] = [], provenance: MergeProvenance = "UNPROVEN", computed: ComputedSubKeys = new Map()): ManagedWrite {
2132
2222
  const base: ManagedWrite = {
2133
2223
  content: generated, verb: "CREATED", lineDelta: lineCount(generated),
2134
- preservedJobs: [], droppedJobs: [], overwrittenLines: [], movedKeys: [], refusal: null,
2224
+ preservedJobs: [], droppedJobs: [], overwrittenLines: [], movedKeys: [], revokedGrants: [],
2225
+ refusal: null,
2135
2226
  };
2136
2227
  if (existing === null) return base;
2137
2228
 
@@ -2160,7 +2251,7 @@ export function resolveManagedWrite(existing: string | null, generated: string):
2160
2251
  // A refusal that is structurally incapable of firing on the thing being
2161
2252
  // destroyed is the defect class .claude/rules/checks-must-be-able-to-fail.md
2162
2253
  // exists for, and it was in the fix written to prevent a data-loss bug.
2163
- const content = mergeManagedWorkflow(existing, generated);
2254
+ const { content, revoked: revokedGrants } = mergeManagedWorkflowRecording(existing, generated, overrides, provenance, computed);
2164
2255
  const lineDelta = lineCount(content) - before;
2165
2256
 
2166
2257
  const preservedJobs = existingJobs.filter(j => !generatedJobs.includes(j));
@@ -2244,19 +2335,98 @@ export function resolveManagedWrite(existing: string | null, generated: string):
2244
2335
  const block = blocks.get(name);
2245
2336
  if (block !== undefined) for (const l of nonBlankLines(block)) harnessOwned.add(l);
2246
2337
  }
2247
- // The harness's own banner is the harness's to reword. Without this, the
2248
- // first run after the banner's text changed refused to update a file the
2249
- // harness had written itself, naming its own previous sentence as consumer
2250
- // content it declined to drop — a refusal is only useful if it is about
2251
- // somebody else's work.
2338
+ // The harness's own bookkeeping lines are the harness's to reword or
2339
+ // withdraw. Without this, the first run after the banner's text changed
2340
+ // refused to update a file the harness had written itself, naming its own
2341
+ // previous sentence as consumer content it declined to drop — a refusal is
2342
+ // only useful if it is about somebody else's work. The override notice is
2343
+ // here for the same reason and one more: it is DELETED, not reworded, the
2344
+ // run after a consumer removes the config entry, so without this the way
2345
+ // back from an override is a refusal (#839).
2252
2346
  for (const l of nonBlankLines(existing)) {
2253
- if (l.startsWith(MANAGED_BANNER_PREFIX)) harnessOwned.add(l);
2347
+ if (HARNESS_BOOKKEEPING_PREFIXES.some(p => l.startsWith(p))) harnessOwned.add(l);
2254
2348
  }
2255
2349
 
2350
+ // The harness's own preamble is the harness's to reword — the WHOLE of it
2351
+ // from the banner down, not just the banner line (#834). A bookkeeping
2352
+ // PREFIX catches the sentence it opens and nothing else, so the paragraphs
2353
+ // underneath read as consumer content: a consumer that added `ci.vertex`
2354
+ // had its re-scaffold refused over three lines of the harness's own "no
2355
+ // credential is configured" header, which is precisely the header the new
2356
+ // one replaces. The merge already declares that preamble its own, so this
2357
+ // reads the boundary from `managedPreamble` rather than restating it —
2358
+ // the two disagreeing is what made the refusal possible.
2359
+ //
2360
+ // This SUBSUMES the banner entry in `HARNESS_BOOKKEEPING_PREFIXES` for the
2361
+ // LEADING PREAMBLE, and only there. The banner of a generated workflow is
2362
+ // always in that preamble, so for the file the generator wrote the two
2363
+ // deciders cannot disagree — which is why giving the constant a second
2364
+ // spelling in this module turned 0 of 107 red when #916 landed, and why
2365
+ // saying so was cheaper than implying a guard that is not there
2366
+ // (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
2367
+ //
2368
+ // "Only there" is the part that was missing, and #926 is where it was
2369
+ // measured. `managedPreamble` reads the HEAD section and returns `[]` when
2370
+ // the banner is not in it, so a bookkeeping line anywhere else in the file
2371
+ // — beside the job key it introduces, which is exactly where the override
2372
+ // notice sits — reaches this loss set with nothing above covering it. The
2373
+ // entry is what keeps it out, and the write refuses without it. Both
2374
+ // entries now carry that witness in
2375
+ // `test/scaffold-permissions-merge.test.ts`, generated from the array.
2376
+ //
2377
+ // What the entry is not any more is the thing keeping the HEADER out of the
2378
+ // loss set. That job is `harnessPreamble`'s.
2379
+ const harnessPreamble = new Set(nonBlankLines(managedPreamble(existing).join("\n")));
2380
+
2381
+ // The grants the merge withdrew, as the lines it took out (#923).
2382
+ //
2383
+ // Taken FROM THE MERGE, not recomputed. A second reading here of which
2384
+ // sub-keys ought to have gone would be a decider that can disagree with the
2385
+ // one that actually removed them, and #834 is the bill for exactly that
2386
+ // arrangement: the merge computed the correct file, the write's own view of
2387
+ // what it was allowed to drop refused to put it on disk, and `id-token:
2388
+ // write` stayed off every consumer for it. Here the disagreement would run
2389
+ // the other way and be worse — a line the merge removed and this set did
2390
+ // not cover is a REFUSED re-scaffold, and a line this set covered and the
2391
+ // merge did not remove is a consumer's own content dropped in silence.
2392
+ // A MULTISET, and spending it is what makes it one. A `Set` of line TEXT
2393
+ // excuses every line in the file that happens to share that text, and
2394
+ // ` id-token: write` is a line a multi-job workflow plausibly carries more
2395
+ // than once — one legitimately withdrawn occurrence would then silently
2396
+ // excuse an unrelated one the consumer still wants. A set also cannot
2397
+ // count: two revoked and five present is indistinguishable from one and
2398
+ // one. Exactly as many occurrences are forgiven as the merge removed, and
2399
+ // the rest refuse like any other dropped line.
2400
+ const revocationBudget = new Map<string, number>();
2401
+ for (const r of revokedGrants) {
2402
+ for (const l of nonBlankLines(r.lines.join("\n"))) {
2403
+ revocationBudget.set(l, (revocationBudget.get(l) ?? 0) + 1);
2404
+ }
2405
+ }
2406
+ /** Spend one occurrence, or report that there is none left to spend. */
2407
+ const spendRevocation = (line: string): boolean => {
2408
+ const left = revocationBudget.get(line) ?? 0;
2409
+ if (left === 0) return false;
2410
+ revocationBudget.set(line, left - 1);
2411
+ return true;
2412
+ };
2413
+
2256
2414
  const kept = new Set(nonBlankLines(content));
2257
2415
  const gone = nonBlankLines(existing).filter(l => !kept.has(l));
2258
- const lostLines = gone.filter(l => !harnessOwned.has(l));
2259
- const overwrittenLines = gone.filter(l => harnessOwned.has(l) && !l.startsWith(MANAGED_BANNER_PREFIX));
2416
+ // Order matters: `spendRevocation` is reached only when the two cheaper
2417
+ // owners decline, so a line the harness already owns does not burn a
2418
+ // revocation another occurrence may need.
2419
+ const lostLines = gone.filter(
2420
+ l => !harnessOwned.has(l) && !harnessPreamble.has(l) && !spendRevocation(l),
2421
+ );
2422
+ // Rewording its own header is not overwriting somebody's edit, and this
2423
+ // report says "in harness-owned jobs" — which the preamble is not.
2424
+ const overwrittenLines = gone.filter(
2425
+ l =>
2426
+ harnessOwned.has(l) &&
2427
+ !harnessPreamble.has(l) &&
2428
+ !HARNESS_BOOKKEEPING_PREFIXES.some(p => l.startsWith(p)),
2429
+ );
2260
2430
  const droppedJobs = existingJobs.filter(j => !resultJobs.includes(j));
2261
2431
 
2262
2432
  if (lostLines.length > 0) {
@@ -2273,7 +2443,11 @@ export function resolveManagedWrite(existing: string | null, generated: string):
2273
2443
  };
2274
2444
  }
2275
2445
 
2276
- return { content, ...measureWrite(existing, content), preservedJobs, droppedJobs: [], overwrittenLines, movedKeys, refusal: null };
2446
+ // `revokedGrants` only reaches a caller on this path. Every return above is
2447
+ // a refusal and `unchanged` carries the empty list from `base`: nothing was
2448
+ // written, so nothing was withdrawn, and a report naming a grant that is
2449
+ // still in the file on disk is the reading disagreeing with reality again.
2450
+ return { content, ...measureWrite(existing, content), preservedJobs, droppedJobs: [], overwrittenLines, movedKeys, revokedGrants, refusal: null };
2277
2451
  }
2278
2452
 
2279
2453
  /** Non-blank lines, trimmed — the unit the loss set is counted in. */
@@ -2282,13 +2456,85 @@ function nonBlankLines(text: string): string[] {
2282
2456
  }
2283
2457
 
2284
2458
  /**
2285
- * Opening of the banner every generated workflow carries.
2459
+ * Lines in a managed file that are the harness talking to the consumer, not
2460
+ * the consumer's content.
2461
+ *
2462
+ * Both are prefixes rather than whole sentences: the rest of each names a
2463
+ * config path, and that tail is exactly the part that changes.
2464
+ *
2465
+ * EXPORTED so the list itself can be tested rather than its members (#926).
2466
+ * `test/scaffold-permissions-merge.test.ts` demands a WITNESS for every entry
2467
+ * — an input where matching the prefix is what decides the outcome — and
2468
+ * ratchets this array against the witnessed population, so an entry added
2469
+ * here with no case there is red. An entry nothing asserts reads as covered,
2470
+ * and adding the next one is how a dead decider gets in; this is what stops
2471
+ * the next one arriving dead the way the banner entry did.
2472
+ *
2473
+ * The witnesses plant lines built from the constants in `managed-workflow.ts`
2474
+ * rather than from this array, deliberately. A fixture read out of the list
2475
+ * under test matches whatever the list says and cannot see it drift.
2476
+ */
2477
+ export const HARNESS_BOOKKEEPING_PREFIXES = [MANAGED_BANNER_PREFIX, WORKFLOW_OVERRIDE_COMMENT];
2478
+
2479
+ /**
2480
+ * The sub-keys each generated workflow COMPUTES, by file and then by the
2481
+ * top-level key they sit under (#923).
2482
+ *
2483
+ * Same shape as `HARNESS_OWNED_JOBS` and for the same reason: a
2484
+ * conditionally emitted thing cannot be recognised from the generated side
2485
+ * once it stops being emitted. `mergeTopLevelSection`'s rule — a sub-key
2486
+ * only the consumer declares is the consumer's — is right for a LOCAL KNOB
2487
+ * and wrong for a DERIVED GRANT. `pull-requests: write` that a consumer
2488
+ * added for a job of their own is theirs. `id-token: write` that this
2489
+ * generator emitted because `ci.vertex` resolved is nobody's choice; the
2490
+ * config made it, and when the config goes the justification goes with it.
2491
+ * By the time the merge runs both are just lines in the consumer's file and
2492
+ * nothing records which side wrote them, so this records it instead.
2493
+ *
2494
+ * A sub-key named here is REMOVED from the consumer's section when that
2495
+ * file's generated side does not declare it. Add a conditionally emitted
2496
+ * sub-key in the same commit that makes it conditional.
2497
+ *
2498
+ * ## Keyed by FILE, which is the whole of the scoping
2499
+ *
2500
+ * The merge runs over every managed workflow. Keyed by section alone,
2501
+ * `permissions.id-token` becomes revocable in files whose generator never
2502
+ * emits it under any config — and all three of these emit a top-level
2503
+ * `permissions:`, so a consumer with a deploy job of their own would have
2504
+ * the grant withdrawn out of a workflow this feature was not reasoning
2505
+ * about. That is #923's own defect wearing the other hat: the issue is a
2506
+ * grant outliving its reason, and an unscoped revoker is a WITHDRAWAL
2507
+ * outliving its reason.
2508
+ *
2509
+ * Declared HERE rather than in `managed-workflow.ts` because the write loop
2510
+ * below is the only place that knows which file it is writing, and because
2511
+ * this module already spells that tuple as a literal for
2512
+ * `test/release-guard.test.ts`. A file absent from this map revokes nothing.
2513
+ *
2514
+ * ## Scoped to what the generator COMPUTES
2515
+ *
2516
+ * Not to everything it emits. `contents: read` is unconditional in all three
2517
+ * files, so both sides always declare it, #839's rule already settles it,
2518
+ * and an entry for it would be one no input can reach.
2519
+ * `test/scaffold-permissions-merge.test.ts` holds this map against the
2520
+ * generators themselves — it scaffolds every generated workflow with and
2521
+ * without the config that drives the grant and takes the per-file symmetric
2522
+ * difference of the emitted sub-keys — so the population is read off the
2523
+ * emitting module rather than off this list, and an entry for a file whose
2524
+ * generator never computes the sub-key is red.
2525
+ *
2526
+ * ## Not `ci.workflowOverrides`, which could not be the mechanism
2286
2527
  *
2287
- * Deliberately the stable prefix and not the whole sentence: the rest of it
2288
- * names the config path, and that is exactly the part that changed and caused
2289
- * the harness to refuse to update its own file.
2528
+ * That is an opt-OUT: a consumer names a key and the merge stops touching
2529
+ * it. Revocation needs the opposite default, because the consumer who has
2530
+ * stopped using Vertex is exactly the consumer who will not think to declare
2531
+ * anything about it. The override still wins where it is declared — naming
2532
+ * the top-level key short-circuits `mergeTopLevelSection` before this is
2533
+ * read — so the escape hatch covers the path with no new config surface.
2290
2534
  */
2291
- const MANAGED_BANNER_PREFIX = "# Managed by rungate";
2535
+ export const HARNESS_COMPUTED_SUBKEYS: ReadonlyMap<string, ComputedSubKeys> = new Map([
2536
+ ["ai-review.yml", new Map([["permissions", new Set(["id-token"])]])],
2537
+ ]);
2292
2538
 
2293
2539
  /**
2294
2540
  * Write a harness-managed file, preserving whatever the harness did not author.
@@ -2296,27 +2542,75 @@ const MANAGED_BANNER_PREFIX = "# Managed by rungate";
2296
2542
  * Throws on refusal. Callers decide whether a refusal aborts the run or is
2297
2543
  * recorded and reported; what they may not do is write anyway.
2298
2544
  */
2545
+ /**
2546
+ * How a managed file carries the record of who wrote it (#767).
2547
+ *
2548
+ * Optional, because most managed files have no marker. When present it is
2549
+ * applied LAST, to the bytes that land on disk, and stripped from both sides
2550
+ * of every comparison — a marker that describes anything other than the file
2551
+ * it is attached to is worse than no marker, because the census believes it.
2552
+ */
2553
+ export interface WriteProvenance {
2554
+ /** The document with its marker line removed. */
2555
+ body(text: string): string;
2556
+ /** The document with a marker describing its own body. */
2557
+ stamp(text: string): string;
2558
+ }
2559
+
2299
2560
  export function writeManagedFile(
2300
2561
  filePath: string,
2301
2562
  generated: string,
2302
2563
  label: string,
2303
2564
  actions: string[],
2304
- opts: { force?: boolean } = {},
2565
+ opts: { force?: boolean; workflowOverrides?: readonly string[]; computedSubKeys?: ComputedSubKeys } = {},
2566
+ provenance?: WriteProvenance,
2305
2567
  ): void {
2306
- const existing = existsSync(filePath) ? readFileSync(filePath, "utf-8") : null;
2307
- const resolved = resolveManagedWrite(existing, generated);
2568
+ const raw = existsSync(filePath) ? readFileSync(filePath, "utf-8") : null;
2569
+ // The marker is stripped from BOTH sides before anything compares them, and
2570
+ // re-applied to whatever is about to be written (#767).
2571
+ //
2572
+ // It has to be both sides and it has to be last. `resolveManagedWrite`
2573
+ // treats every line outside a job as the consumer's, so the OLD marker —
2574
+ // which differs from the new one exactly when the generator changed — read
2575
+ // as content about to be dropped and REFUSED the write. And stamping the
2576
+ // generated text before the merge produced a file whose marker described
2577
+ // bytes that were never written, so a workflow with one preserved job was
2578
+ // classified `generated-and-hand-edited` for ever, about bytes the harness
2579
+ // itself had just written.
2580
+ const existing = raw === null ? null : (provenance ? provenance.body(raw) : raw);
2581
+ const incoming = provenance ? provenance.body(generated) : generated;
2582
+ // What the marker proves about the bytes on disk, read HERE because here is
2583
+ // the only layer that still holds them (#957). Everything below this line
2584
+ // has had the marker stripped, which is the whole reason #941 could not
2585
+ // repair the residue it left: the merge was handed a file with no way of
2586
+ // telling its own old output from the consumer's.
2587
+ //
2588
+ // One expression, over the `WriteProvenance` the caller already supplies:
2589
+ // re-stamping the body reproduces the file exactly when the marker is
2590
+ // present AND describes that body. An absent marker and a stale one are both
2591
+ // UNPROVEN, which is the only distinction the merge acts on, and a managed
2592
+ // file with no provenance at all reads as UNPROVEN too — the fail-closed
2593
+ // direction and the pre-#957 behaviour unchanged.
2594
+ const proven: MergeProvenance =
2595
+ provenance !== undefined && raw !== null && provenance.stamp(provenance.body(raw)) === raw
2596
+ ? "VERIFIED"
2597
+ : "UNPROVEN";
2598
+ const resolved = resolveManagedWrite(existing, incoming, opts.workflowOverrides ?? [], proven, opts.computedSubKeys ?? new Map());
2599
+ /** The bytes that land on disk: the decision's content, then the marker. */
2600
+ const stamped = (content: string): string => (provenance ? provenance.stamp(content) : content);
2308
2601
 
2309
2602
  if (opts.force) {
2310
2603
  // The escape hatch, and it still reports a measured verb: --force changes
2311
2604
  // what is ALLOWED, not what gets claimed about it. The dropped jobs are
2312
2605
  // still named, because an operator who overrides the refusal should be
2313
2606
  // told in the report exactly what they overrode.
2314
- const { verb, lineDelta } = measureWrite(existing, generated);
2315
- if (verb === "SKIP") { actions.push(`SKIP: ${label} (unchanged)`); return; }
2607
+ const bytes = stamped(incoming);
2608
+ if (bytes === raw) { actions.push(`SKIP: ${label} (unchanged)`); return; }
2609
+ const { verb, lineDelta } = measureWrite(existing, incoming);
2316
2610
  const dropped = resolved.droppedJobs.length > 0 ? `, dropped ${resolved.droppedJobs.join(", ")}` : "";
2317
2611
  mkdirSync(dirname(filePath), { recursive: true });
2318
- writeFileSync(filePath, generated);
2319
- actions.push(`${verb}: ${label} (--force, ${signed(lineDelta)} lines${dropped})`);
2612
+ writeFileSync(filePath, bytes);
2613
+ actions.push(`${verb === "SKIP" ? "UPDATED" : verb}: ${label} (--force, ${signed(lineDelta)} lines${dropped})`);
2320
2614
  return;
2321
2615
  }
2322
2616
 
@@ -2339,16 +2633,296 @@ export function writeManagedFile(
2339
2633
  `${over.slice(0, 2).map(l => JSON.stringify(l)).join(", ")}` +
2340
2634
  `${over.length > 2 ? ` and ${over.length - 2} more` : ""}`;
2341
2635
 
2342
- if (resolved.verb === "SKIP") {
2636
+ const bytes = stamped(resolved.content);
2637
+
2638
+ // Compared as BYTES, not as a verb. `resolved.verb` is a statement about
2639
+ // the bodies, and a file whose body is unchanged can still need writing —
2640
+ // its marker may be absent or describe something else. Reporting SKIP on
2641
+ // that file is how the stamp stayed wrong across every later run.
2642
+ if (bytes === raw) {
2343
2643
  actions.push(`SKIP: ${label} (unchanged${kept})`);
2344
2644
  return;
2345
2645
  }
2346
2646
 
2347
2647
  mkdirSync(dirname(filePath), { recursive: true });
2348
- writeFileSync(filePath, resolved.content);
2349
- actions.push(`${resolved.verb}: ${label} (${signed(resolved.lineDelta)} lines${kept}${overwrote})`);
2648
+ writeFileSync(filePath, bytes);
2649
+ if (resolved.verb === "SKIP") {
2650
+ // Body identical, marker not. Said plainly rather than as `UPDATED (+0
2651
+ // lines)`, which is the line an operator reads as "my generator change
2652
+ // landed" (#767).
2653
+ actions.push(`UPDATED: ${label} (provenance marker refreshed, +0 lines${kept})`);
2654
+ } else {
2655
+ actions.push(`${resolved.verb}: ${label} (${signed(resolved.lineDelta)} lines${kept}${overwrote})`);
2656
+ }
2657
+ actions.push(...revocationActions(label, resolved.revokedGrants));
2658
+ }
2659
+
2660
+ /**
2661
+ * One line per grant the merge withdrew (#923).
2662
+ *
2663
+ * Its OWN line rather than a parenthetical on the write, and after the write
2664
+ * rather than folded into it. "REPLACED (-74 lines)" is already true of a
2665
+ * re-scaffold that withdraws nothing, so a consumer cannot read a withdrawal
2666
+ * out of it, and the thing being reported is not a line count: a standing
2667
+ * right to mint a credential has been taken away. That is the fact #631 says
2668
+ * nobody audits, and burying it inside a byte-delta is how it goes on not
2669
+ * being audited.
2670
+ *
2671
+ * The reason given is the one THIS layer actually knows — the generator
2672
+ * computes this sub-key and has stopped computing it — and not the config
2673
+ * entry that drove it. The merge cannot see `ci.vertex`; a sentence naming it
2674
+ * here would be a second, unverified reading of the generator's own decision,
2675
+ * and it would be wrong the first time a different sub-key joins the map.
2676
+ */
2677
+ function revocationActions(label: string, revoked: readonly RevokedSubKey[]): string[] {
2678
+ return revoked.map(
2679
+ r =>
2680
+ `REVOKED: ${label} no longer declares \`${r.section}: ${r.key}\` — the harness ` +
2681
+ `computes that sub-key and this project's \`ci\` config no longer produces it, so ` +
2682
+ `the grant has nothing left to justify it. Name \`${r.section}\` in ` +
2683
+ `\`ci.workflowOverrides\` to keep it, and re-scaffold.`,
2684
+ );
2685
+ }
2686
+
2687
+ /** One globally installed CI tool, and the exact version it is pinned to. */
2688
+ export interface GlobalToolPin {
2689
+ package: string;
2690
+ version: string;
2691
+ }
2692
+
2693
+ export interface GlobalToolDecision {
2694
+ /** YAML spliced into the test job ahead of the test step. Never empty. */
2695
+ step: string;
2696
+ /** What will be installed, in declaration order. */
2697
+ pins: GlobalToolPin[];
2698
+ /** Why this and not something else. */
2699
+ reason: string;
2700
+ /** Declarations refused, each naming itself, so the omission is visible. */
2701
+ rejected: string[];
2702
+ }
2703
+
2704
+ /** An npm package name, optionally scoped. Excludes every shell metacharacter. */
2705
+ const SAFE_GLOBAL_TOOL_PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
2706
+
2707
+ /**
2708
+ * An EXACT version. Deliberately not a semver test and deliberately not a
2709
+ * range: `^1.2.0`, `latest` and `next` all resolve to whatever shipped today,
2710
+ * which is the state #597 is about, and admitting one here would be a fix
2711
+ * that looks like the fix while reintroducing the defect.
2712
+ */
2713
+ const PINNED_GLOBAL_TOOL_VERSION = /^[0-9][A-Za-z0-9.+-]*$/;
2714
+
2715
+ /**
2716
+ * A value on its way into a generated YAML comment.
2717
+ *
2718
+ * Only REJECTED entries ever reach a comment, and they are rejected precisely
2719
+ * because they did not match the two charsets above — so this is the one
2720
+ * place in the generator that formats a string nothing has validated. A
2721
+ * newline in it ends the comment, and the next line is a step.
2722
+ *
2723
+ * That was live, not theoretical. Before this function existed, a config
2724
+ * declaring a package named `pwned\n - name: Injected step\n
2725
+ * run: echo INJECTED` produced a generated `ci.yml` containing exactly that
2726
+ * step, runnable. The version field did the same, and a config pairing one
2727
+ * VALID pin with one evil entry injected through the success path too,
2728
+ * because the refusals string is appended there as well.
2729
+ *
2730
+ * The accepted path does not need this — it is charset-validated and single
2731
+ * quoted, two defences chosen to agree. The rejection path is the one that
2732
+ * handles hostile input by definition, which is what made it the hole: the
2733
+ * branch whose whole job is to refuse an unsafe declaration was the branch
2734
+ * that emitted it verbatim.
2735
+ */
2736
+ function commentSafe(value: string): string {
2737
+ return value.replace(/[\r\n]+/g, " ").replace(/[^\x20-\x7e]/g, "?").slice(0, 120);
2738
+ }
2739
+
2740
+ /**
2741
+ * The global-install step for the generated CI test job (#597).
2742
+ *
2743
+ * `lib/compliance.ts` decides three Layer 1 verdicts by spawning `agnix` and
2744
+ * `npx @reporails/cli`. CI installed neither, so the registry's mood at that
2745
+ * moment was the verdict — an identical SHA re-ran red to green with no code
2746
+ * change. The versions live in ONE position, `ci.globalTools` in
2747
+ * `.claude/rungate/config.json`; this function carries none of them, for the
2748
+ * same reason `setupBunWith` carries no Bun version (#622) and the test step
2749
+ * carries no command (#488).
2750
+ *
2751
+ * It returns LINES rather than writing, which is what lets a test assert the
2752
+ * emission for a declaration no registry has ever served.
2753
+ *
2754
+ * `npm install -g` rather than `bun add -g`: the consumers are
2755
+ * `probeExternalTool("agnix", …)`, which wants a binary on PATH, and
2756
+ * `npx @reporails/cli`, which resolves through npm.
2757
+ *
2758
+ * The absent case emits a REASON, not silence —
2759
+ * `.claude/rules/config-access.md`: `0`, `{}`, `null` and nothing at all are
2760
+ * indistinguishable from success. Same shape as `typecheckStep` below.
2761
+ */
2762
+ /**
2763
+ * How many CI shards to split the test files across (#728).
2764
+ *
2765
+ * One exported binding, read off the same `ci` object as its siblings, so
2766
+ * there is one thing to mutate and the generator cannot grow a second
2767
+ * opinion about the shard count.
2768
+ *
2769
+ * **Absent means 1, and 1 means the single-job workflow byte for byte.** A
2770
+ * consumer who has never configured this gets exactly what they have today;
2771
+ * sharding is something a project opts into once its suite is slow enough to
2772
+ * be worth the runners.
2773
+ *
2774
+ * Refuses anything that is not a positive whole number, and refuses silently
2775
+ * upward rather than downward — a malformed value yields 1 (no sharding),
2776
+ * never 0 shards, because a matrix with an empty list runs NO tests and
2777
+ * reports success. `0`, `{}` and `null` are indistinguishable from a clean
2778
+ * result (`.claude/rules/config-access.md`); a suite that ran nothing and a
2779
+ * suite that passed must not produce the same verdict.
2780
+ *
2781
+ * Capped at 32: the shard count becomes a matrix leg, and an unbounded value
2782
+ * read from config is an unbounded number of runners billed to whoever
2783
+ * mistyped it.
2784
+ */
2785
+ export function shardCount(ci: unknown): number {
2786
+ const raw = (ci as { shards?: unknown } | null | undefined)?.shards;
2787
+ if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1) return 1;
2788
+ return Math.min(raw, 32);
2789
+ }
2790
+
2791
+ /**
2792
+ * Top-level workflow keys this consumer has taken back from the generator
2793
+ * (#839). Declared in `lib/scaffold/managed-workflow.ts`, beside the merge
2794
+ * that consumes it and the notice it makes the merge write.
2795
+ *
2796
+ * Re-exported from here, unmoved as far as every caller is concerned, because
2797
+ * `lib/conformity.ts` needs the same reading (#915) and importing this module
2798
+ * to get it would pull the whole scaffold generator graph — the scanner, the
2799
+ * spec auditor, every generator — into the conformity suite of every consumer
2800
+ * project. `managed-workflow.ts` imports `crypto` and nothing else.
2801
+ *
2802
+ * One binding, so there is one thing to mutate. A second reader in
2803
+ * `conformity.ts` would agree with this one on every input the suite has, and
2804
+ * two deciders that agree are behaviourally one
2805
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
2806
+ */
2807
+ export { workflowOverrides } from "./managed-workflow";
2808
+
2809
+ export function globalToolInstallStep(ci: unknown, indent = " "): GlobalToolDecision {
2810
+ const declared = (ci as { globalTools?: unknown } | null | undefined)?.globalTools;
2811
+ const entries =
2812
+ declared !== null && typeof declared === "object" && !Array.isArray(declared)
2813
+ ? Object.entries(declared as Record<string, unknown>)
2814
+ : [];
2815
+
2816
+ const pins: GlobalToolPin[] = [];
2817
+ const rejected: string[] = [];
2818
+ for (const [name, raw] of entries) {
2819
+ const version = typeof raw === "string" ? raw.trim() : "";
2820
+ if (!SAFE_GLOBAL_TOOL_PACKAGE.test(name)) {
2821
+ rejected.push(`${commentSafe(name)}@${commentSafe(version) || "(nothing)"} (not an npm package name)`);
2822
+ continue;
2823
+ }
2824
+ if (!PINNED_GLOBAL_TOOL_VERSION.test(version)) {
2825
+ rejected.push(`${commentSafe(name)}@${commentSafe(version) || "(nothing)"} (not an exact version)`);
2826
+ continue;
2827
+ }
2828
+ pins.push({ package: name, version });
2829
+ }
2830
+
2831
+ const refusals = rejected.length === 0 ? "" : ` Refused, and so NOT installed: ${rejected.join("; ")}.`;
2832
+
2833
+ if (pins.length === 0) {
2834
+ const reason =
2835
+ entries.length === 0 ? "the config declares no ci.globalTools" : "every ci.globalTools entry was refused";
2836
+ return { step: `\n${indent}# No global tools installed: ${reason}.${refusals}`, pins, reason, rejected };
2837
+ }
2838
+
2839
+ // Validated AND quoted, chosen to agree: the charset above admits nothing
2840
+ // the single quotes would have to defend against, which is what makes
2841
+ // neither defence a place for the other to be relaxed.
2842
+ const specs = pins.map(p => `'${p.package}@${p.version}'`).join(" ");
2843
+ return {
2844
+ // The versions appear on the `run:` line and nowhere else in the emitted
2845
+ // YAML, so a test asserting the pin is asserting the command rather than
2846
+ // a comment that happens to quote it.
2847
+ step:
2848
+ `\n${indent}# Pinned by ci.globalTools in .claude/rungate/config.json — one declaration (#597).` +
2849
+ (rejected.length === 0 ? "" : `\n${indent}#${refusals}`) +
2850
+ `\n${indent}- name: Install pinned global tools` +
2851
+ `\n${indent} run: npm install -g ${specs}`,
2852
+ pins,
2853
+ reason: `ci.globalTools pins ${pins.map(p => `${p.package}@${p.version}`).join(", ")}`,
2854
+ rejected,
2855
+ };
2350
2856
  }
2351
2857
 
2858
+ /**
2859
+ * The top-level concurrency block for the CI workflow.
2860
+ *
2861
+ * The GROUP does the work here, not the flag. A run can only be cancelled by
2862
+ * another run in the SAME group, so a key that is unique per main commit makes
2863
+ * the question moot — there is never a second occupant to do the cancelling.
2864
+ *
2865
+ * #937 tried the other arrangement: a ref-keyed group with
2866
+ * `cancel-in-progress: ${{ github.event_name == 'pull_request' }}`. It does not
2867
+ * work. Measured on this repository's own main after it shipped (#952): three
2868
+ * push runs cancelled inside eight minutes with that expression in the file,
2869
+ * one of them one second after the next run was created, and every cancelled
2870
+ * run had job count 0 — cancellation at queue time. The mechanism is
2871
+ * UNMEASURED; the leading hypothesis is that the result coerces to the
2872
+ * non-empty string "false", which is truthy. This form does not depend on
2873
+ * knowing which, and that is the point of choosing it.
2874
+ *
2875
+ * The three events:
2876
+ *
2877
+ * - A pull request's ref is `refs/pull/<n>/merge`, unique to that PR, so a
2878
+ * new push to PR #5 can only ever cancel PR #5. Superseding it is the
2879
+ * point: the older commit's result is about code nobody will merge.
2880
+ *
2881
+ * - A push to main shares ONE ref with every other push to main. Two merges
2882
+ * landing within a few minutes cancel the first, and the first is the only
2883
+ * run that ever builds that commit — a gap in main's history with no red
2884
+ * check anywhere to say so. Measured on one consumer: five cancelled runs,
2885
+ * all of them main pushes, and the `test` job runs on main push there, so
2886
+ * what was lost was a test result and not just a container build. The repo
2887
+ * and the run IDs are on #937 — the harness does not name its consumers
2888
+ * (#304), and `test/anti.test.ts` SC-A1 is the check that says so.
2889
+ *
2890
+ * - `merge_group` must not be cancelled either. A queue entry builds its own
2891
+ * `gh-readonly-queue/...` ref, so it is already alone in its group, and
2892
+ * cancelling one mid-flight dequeues the PR behind it.
2893
+ *
2894
+ * So: a push keys on `github.sha`, unique per commit and therefore never
2895
+ * shared. Everything else keys on `github.ref`, which is unique per pull
2896
+ * request and per queue entry but STABLE across pushes to the same PR — which
2897
+ * is what lets a PR supersede itself, the one case where cancelling is right.
2898
+ *
2899
+ * This is a SUB-KEY merge under `mergeManagedWorkflow`: a consumer that already
2900
+ * declares `cancel-in-progress` keeps its own value, and this reaches only the
2901
+ * consumers that have no concurrency block at all.
2902
+ */
2903
+ export const CI_CONCURRENCY = `# The GROUP does the work here, not the flag. A run is only ever cancelled by
2904
+ # another run in the SAME group, so keying a push on its own commit makes the
2905
+ # question moot: there is never a second occupant to do the cancelling.
2906
+ #
2907
+ # A push to \`main\` keys on \`github.sha\`, unique per commit. Every other main
2908
+ # run is in a different group and nothing can cancel it. That matters because
2909
+ # a main run is the ONLY run that will ever build that commit, so losing it
2910
+ # leaves a gap in main's history with no red check anywhere saying so.
2911
+ #
2912
+ # Everything else keys on \`github.ref\`: unique per pull request
2913
+ # (\`refs/pull/<n>/merge\`) and per merge-queue entry
2914
+ # (\`gh-readonly-queue/...\`), but STABLE across pushes to the same pull
2915
+ # request — which is what lets a pull request supersede itself, the one case
2916
+ # where cancelling is the right answer.
2917
+ #
2918
+ # Do NOT "simplify" this to a ref-keyed group with an event expression in
2919
+ # cancel-in-progress. That was tried and measured: three main-push runs
2920
+ # cancelled inside eight minutes with the expression in place.
2921
+ concurrency:
2922
+ group: ci-\${{ github.event_name == 'push' && github.sha || github.ref }}
2923
+ cancel-in-progress: true
2924
+ `;
2925
+
2352
2926
  export function createCiWorkflows(root: string, actions: string[], opts: { force?: boolean } = {}): void {
2353
2927
  const workflowsDir = join(root, ".github", "workflows");
2354
2928
  if (!existsSync(workflowsDir)) {
@@ -2356,7 +2930,17 @@ export function createCiWorkflows(root: string, actions: string[], opts: { force
2356
2930
  }
2357
2931
 
2358
2932
  const harness = loadHarnessConfig(root);
2359
- const bunVersion = harness?.ci?.bunVersion || "latest";
2933
+ // #622. This was `harness?.ci?.bunVersion || "latest"`, emitted at the two
2934
+ // sites below, while the two hand-owned workflow files this generator never
2935
+ // touches named versions of their own — four positions, three spellings,
2936
+ // and nothing comparing any of them. (Neither of those filenames is spelled
2937
+ // here: test/release-guard.test.ts asserts this module names no workflow it
2938
+ // does not write, and prose is indistinguishable from a write to it.) The
2939
+ // decision and the YAML it becomes are now `lib/bun-version.ts`'s, for the
2940
+ // same reason #87 took the typecheck step and #488 took the test step: two
2941
+ // sites that agree today are one decider too many, and only a mutation of a
2942
+ // SHARED binding can show the agreement is load-bearing.
2943
+ const bunStep = setupBunWith(declaredBunVersion(root), " ");
2360
2944
  const runner = harness?.ci?.runner || "ubuntu-latest";
2361
2945
  const branches = harness?.ci?.branches || ["main"];
2362
2946
  // Branch patterns are globs: a bare `*` is a YAML alias indicator and `*-dev`
@@ -2393,16 +2977,51 @@ export function createCiWorkflows(root: string, actions: string[], opts: { force
2393
2977
  // is the gap, not the absence of a validator.
2394
2978
  const baseBranch = String(branches[0] ?? "main");
2395
2979
  const SAFE_BRANCH = /^[A-Za-z0-9][A-Za-z0-9._\/-]*$/;
2980
+ // #987. This step used to be unconditionally `--depth=200`, and that flag is
2981
+ // what made `fetch-depth: 0` above it inert: a bounded `git fetch`
2982
+ // RE-SHALLOWS a repository that was already complete. Measured on a complete
2983
+ // 40-commit clone, `is-shallow-repository` goes false → true and
2984
+ // `rev-list --count HEAD` drops 40 → 20. The depth is therefore derived from
2985
+ // the checkout's own, in `lib/ci-history-depth.ts`, rather than written here
2986
+ // as a second number that has to agree with the first.
2987
+ //
2988
+ // Unbounded is not expensive in the full-history case: the objects are
2989
+ // already local, so the fetch updates a ref and transfers nothing.
2990
+ const baseDepth = baseRefFetchDepth(CI_SUITE_FETCH_DEPTH);
2991
+ const baseDepthFlag = baseDepth === null ? "" : `--depth=${baseDepth} `;
2992
+
2993
+ // #987. `actions/checkout` with nothing declared clones ONE commit, so every
2994
+ // generated job that reads git history has been reading one commit since the
2995
+ // first workflow this harness wrote. `lib/failure-intake.ts` refuses a
2996
+ // shallow clone by name, which means its reading was UNMEASURED on every run
2997
+ // on every runner — uniformly absent rather than occasionally missing, and
2998
+ // absence looked like quiet.
2999
+ //
3000
+ // Both generated jobs declare it, not just the suite job. `test/scaffold-
3001
+ // conformity.test.ts` calls `runDocHygiene`, HYGIENE-6 inside it is the
3002
+ // intake's only caller, and the gates job names that file directly while the
3003
+ // suite job reaches it through the test command.
3004
+ //
3005
+ // The cost, measured on this repository three times each: depth 1 is
3006
+ // 1.23–1.64s for 6MB, full history is 1.43–1.64s for 13MB. A bounded middle
3007
+ // was measured too and is the worst of the three — 1.54–2.75s for 9MB, and
3008
+ // still UNMEASURED, because a shallow clone is shallow whatever its depth.
3009
+ const checkoutStep = ` - uses: ${actionRef("actions/checkout")}
3010
+ with:
3011
+ # Full history. A bounded depth leaves .git/shallow behind, and
3012
+ # lib/failure-intake.ts refuses on that file rather than on a commit
3013
+ # count — so any bounded value here reports UNMEASURED (#987).
3014
+ # Declared once, in lib/ci-history-depth.ts.
3015
+ fetch-depth: ${CI_SUITE_FETCH_DEPTH}`;
2396
3016
  const baseRefStep =
2397
3017
  SAFE_BRANCH.test(baseBranch) && !baseBranch.includes("..")
2398
- ? // `--depth=200`, not `--depth=1`. The conformity ratchet only diffs the
2399
- // tip and was happy with one commit, but a tip with no history behind
2400
- // it makes any check that reads the recent log unmeasurable — and an
2401
- // empty log is indistinguishable from a clean one. Two hundred commits
2402
- // is a few hundred KB and spans months of this project's history.
3018
+ ? // The conformity ratchet only diffs the tip and was happy with one
3019
+ // commit, but a tip with no history behind it makes any check that
3020
+ // reads the recent log unmeasurable — and an empty log is
3021
+ // indistinguishable from a clean one.
2403
3022
  ` - name: Fetch the comparison base for the conformity ratchet
2404
3023
  run: |
2405
- git fetch --no-tags --depth=200 origin '+refs/heads/${baseBranch}:refs/remotes/origin/${baseBranch}' \\
3024
+ git fetch --no-tags ${baseDepthFlag}origin '+refs/heads/${baseBranch}:refs/remotes/origin/${baseBranch}' \\
2406
3025
  || echo "WARN: could not fetch ${baseBranch}; the conformity allowlist growth check will report UNMEASURED."`
2407
3026
  : // Not a fetchable ref: a glob pattern, a leading dash, or a traversal
2408
3027
  // segment. Emitted as a comment so the omission is visible in the
@@ -2422,15 +3041,149 @@ export function createCiWorkflows(root: string, actions: string[], opts: { force
2422
3041
  // `dev.typeCheck` read (#87). This site used to check for
2423
3042
  // `scripts/typecheck.ts` on disk, a branch `files:` makes unreachable for
2424
3043
  // every consumer, and never looked at a project's own `typecheck` script.
3044
+ // #488. This was `- run: bun test`, hardcoded, while `harness` was in
3045
+ // scope and three of its siblings read `harness?.ci?.*` four lines above.
3046
+ // Same binding AGENTS.md's Commands row and the agent briefs read, for the
3047
+ // same reason the typecheck step below it got one in #87: two sites that
3048
+ // agree today are one decider too many, and only a mutation of a shared
3049
+ // binding can show the agreement is load-bearing.
3050
+ const test = testCommandDecision(root);
3051
+
3052
+ // #597. The Layer 1 compliance checks shell out to agnix and
3053
+ // @reporails/cli; CI installed neither, so what the registry served at that
3054
+ // moment decided the verdict. Pinned from the one declaration, never a
3055
+ // literal here.
3056
+ const globalTools = globalToolInstallStep(harness?.ci);
3057
+
2425
3058
  const typecheck = typecheckDecision(root);
2426
3059
  const typecheckStep = typecheck.command
2427
3060
  ? `\n - run: ${typecheck.command}`
2428
3061
  : `\n # No type check: ${typecheck.reason}.`;
2429
3062
 
2430
- const ciYml = `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
3063
+ // #728. A suite is a wall every branch pays, and this one was 313s of a
3064
+ // 376s run — one `bun test` on one runner, 13,562 tests, while `strict`
3065
+ // branch protection makes every merge re-run it. Sharding splits the FILES
3066
+ // across runners, which is not the same lever as `--parallel`: that one was
3067
+ // tried, and #621 records it starving 122 I/O-bound tests past bun's
3068
+ // per-test timeout so every ship run reported SHIP_PASSED_SUITE_FAILED over
3069
+ // a tree with zero real failures. Separate runners give each shard a whole
3070
+ // machine, so the starvation mechanism is absent by construction.
3071
+ //
3072
+ // Opt-in, and absent config means one shard and the single-job shape byte
3073
+ // for byte — a consumer who has never heard of this gets what they have
3074
+ // today. `shard` is read from the same `harness?.ci` binding as every
3075
+ // sibling above rather than a second reader.
3076
+ const shards = shardCount(harness?.ci);
3077
+
3078
+ // #839. Which top-level keys this consumer has taken back, read from the
3079
+ // same binding as every sibling above rather than a second reader. Absent
3080
+ // config means none, and none means the generator's structural keys reach
3081
+ // every workflow it has ever written — which is the whole point of the
3082
+ // change this config exists to make reversible.
3083
+ const declined = workflowOverrides(harness?.ci);
3084
+
3085
+ // The required status check is the JOB NAME, and a matrix renames it:
3086
+ // `test` becomes `test (1)`, `test (2)`. A repo whose protection requires
3087
+ // `test` would then require a context nothing ever reports, and GitHub
3088
+ // treats an absent required check as pending forever — every PR wedged,
3089
+ // with no error anywhere saying why. So the matrix is `test-shard` and a
3090
+ // dependent job keeps the name `test`, which is the context protection
3091
+ // already names. Do not collapse these two jobs.
3092
+ const ciYml = shards > 1
3093
+ ? `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
3094
+ name: CI
3095
+
3096
+ on:
3097
+ # Re-run this workflow on demand, on any ref. Without the trigger the
3098
+ # Actions API refuses with \`HTTP 422: Workflow does not have
3099
+ # 'workflow_dispatch' trigger\` — measured on 2026-10-21 across the fleet,
3100
+ # where 5 of 6 re-run attempts came back 422. The cost is not the button: a
3101
+ # flake cannot be told from a real failure without pushing an empty commit,
3102
+ # and a fix landed on the default branch cannot be confirmed until unrelated
3103
+ # traffic happens to arrive (#940).
3104
+ workflow_dispatch:
3105
+ # merge_group carries NO branches: filter, deliberately. A merge queue builds
3106
+ # a temporary \`gh-readonly-queue/<base>/...\` ref, which no branch list here
3107
+ # would match — so filtering it is the same as not handling the event, and a
3108
+ # trigger that is present and inert is worse than an absent one because the
3109
+ # file then reads as handling it.
3110
+ #
3111
+ # Without this trigger a merge queue cannot work at all, and it fails in the
3112
+ # worst available way: the queue waits for a required check that will never
3113
+ # report, every entry sits pending with no error anywhere, and the repo looks
3114
+ # like it has simply stopped merging. UNMEASURED, not red.
3115
+ #
3116
+ # This is the SHARDED body, and it is the one that matters most: the required
3117
+ # context is the \`test\` aggregate below, which only exists here. The first
3118
+ # draft of #765 added the trigger to the unsharded body only — 91 tests passed
3119
+ # and the repo that needed it was untouched.
3120
+ merge_group:
3121
+ push:
3122
+ branches:
3123
+ ${branchList}
3124
+ pull_request:
3125
+ branches:
3126
+ ${branchList}
3127
+
3128
+ ${CI_CONCURRENCY}
3129
+ permissions:
3130
+ # Least privilege, and it matters most on the consumers. A workflow with
3131
+ # no permissions: block inherits the REPOSITORY default, which is a setting
3132
+ # the harness does not control and cannot read at generation time. Measured
3133
+ # 2026-10-20 across the consumers this harness serves: the default is
3134
+ # read-only on some and WRITE on others, so a generated job that declares
3135
+ # nothing holds a push-capable GITHUB_TOKEN wherever the default is write.
3136
+ # Neither job needs it: both check out, install and run tests.
3137
+ contents: read
3138
+
3139
+ jobs:
3140
+ test-shard:
3141
+ runs-on: ${runsOn}
3142
+ strategy:
3143
+ # One red shard must not cancel the others: the whole point is to see
3144
+ # every failure in one run rather than re-running to find the next.
3145
+ fail-fast: false
3146
+ matrix:
3147
+ shard: [${Array.from({ length: shards }, (_, i) => i + 1).join(", ")}]
3148
+ steps:
3149
+ ${checkoutStep}
3150
+ ${baseRefStep}
3151
+ - uses: ${actionRef("oven-sh/setup-bun")}
3152
+ with:
3153
+ ${bunStep}
3154
+ - run: bun install${globalTools.step}${ciSetupStep()}
3155
+ - run: ${test.command} --shard=\${{ matrix.shard }}/${shards}${typecheckStep}
3156
+
3157
+ # The aggregate. Named "test" because that is the context branch protection
3158
+ # requires; it exists to turn N shard results into the one verdict.
3159
+ test:
3160
+ runs-on: ${runsOn}
3161
+ needs: test-shard
3162
+ # always() so a failed or cancelled shard reaches this job instead of
3163
+ # skipping it. A skipped required check is not a failed one, and some
3164
+ # protection configurations read a skip as satisfied — which would make
3165
+ # this aggregate a gate that cannot refuse.
3166
+ if: always()
3167
+ steps:
3168
+ - name: Every shard passed
3169
+ run: |
3170
+ result='\${{ needs.test-shard.result }}'
3171
+ if [ "$result" != "success" ]; then
3172
+ echo "::error::test-shard concluded '$result' — the suite is not green."
3173
+ exit 1
3174
+ fi
3175
+ echo "All ${shards} shards passed."
3176
+ `
3177
+ : `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
2431
3178
  name: CI
2432
3179
 
2433
3180
  on:
3181
+ # See the sharded body above: a re-run of this workflow is a 422 without
3182
+ # this trigger, so a flake and a real failure are indistinguishable.
3183
+ workflow_dispatch:
3184
+ # See the sharded body above: no branches: filter, and its absence hangs a
3185
+ # merge queue silently rather than failing it.
3186
+ merge_group:
2434
3187
  push:
2435
3188
  branches:
2436
3189
  ${branchList}
@@ -2438,23 +3191,40 @@ ${branchList}
2438
3191
  branches:
2439
3192
  ${branchList}
2440
3193
 
3194
+ ${CI_CONCURRENCY}
3195
+ permissions:
3196
+ # Least privilege, and it matters most on the consumers. A workflow with
3197
+ # no permissions: block inherits the REPOSITORY default, which is a setting
3198
+ # the harness does not control and cannot read at generation time. Measured
3199
+ # 2026-10-20 across the consumers this harness serves: the default is
3200
+ # read-only on some and WRITE on others, so a generated job that declares
3201
+ # nothing holds a push-capable GITHUB_TOKEN wherever the default is write.
3202
+ # Neither job needs it: both check out, install and run tests.
3203
+ contents: read
3204
+
2441
3205
  jobs:
2442
3206
  test:
2443
3207
  runs-on: ${runsOn}
2444
3208
  steps:
2445
- - uses: actions/checkout@v4
3209
+ ${checkoutStep}
2446
3210
  ${baseRefStep}
2447
- - uses: oven-sh/setup-bun@v2
3211
+ - uses: ${actionRef("oven-sh/setup-bun")}
2448
3212
  with:
2449
- bun-version: "${bunVersion}"
2450
- - run: bun install
2451
- - run: bun test${typecheckStep}
3213
+ ${bunStep}
3214
+ - run: bun install${globalTools.step}${ciSetupStep()}
3215
+ - run: ${test.command}${typecheckStep}
2452
3216
  `;
2453
3217
 
2454
3218
  const gatesYml = `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
2455
3219
  name: Gates
2456
3220
 
2457
3221
  on:
3222
+ # See ci.yml above: without this the Actions API refuses a re-run with a
3223
+ # 422, and the gates are the checks most worth re-running on their own.
3224
+ workflow_dispatch:
3225
+ # See ci.yml above: a merge queue builds a ref no branch list matches, so
3226
+ # this trigger carries no filter and its absence hangs the queue silently.
3227
+ merge_group:
2458
3228
  push:
2459
3229
  branches:
2460
3230
  ${branchList}
@@ -2462,14 +3232,24 @@ ${branchList}
2462
3232
  branches:
2463
3233
  ${branchList}
2464
3234
 
3235
+ permissions:
3236
+ # Least privilege, and it matters most on the consumers. A workflow with
3237
+ # no permissions: block inherits the REPOSITORY default, which is a setting
3238
+ # the harness does not control and cannot read at generation time. Measured
3239
+ # 2026-10-20 across the consumers this harness serves: the default is
3240
+ # read-only on some and WRITE on others, so a generated job that declares
3241
+ # nothing holds a push-capable GITHUB_TOKEN wherever the default is write.
3242
+ # Neither job needs it: both check out, install and run tests.
3243
+ contents: read
3244
+
2465
3245
  jobs:
2466
3246
  gates:
2467
3247
  runs-on: ${runsOn}
2468
3248
  steps:
2469
- - uses: actions/checkout@v4
2470
- - uses: oven-sh/setup-bun@v2
3249
+ ${checkoutStep}
3250
+ - uses: ${actionRef("oven-sh/setup-bun")}
2471
3251
  with:
2472
- bun-version: "${bunVersion}"
3252
+ ${bunStep}
2473
3253
  - run: bun install
2474
3254
  - name: Conformity + spec drift
2475
3255
  run: bun test test/scaffold-conformity.test.ts
@@ -2486,6 +3266,9 @@ jobs:
2486
3266
  # CLAIM parity while CI carried 3 patterns and the hook carried 8 —
2487
3267
  # CI missed gho_, ghs_, github_pat_, sk-ant- and PEM private keys
2488
3268
  # entirely. Asserted now in test/unit/secret-patterns.test.ts.
3269
+ # Tier 1 also owns the signed JWT, because it is the one unquoted
3270
+ # credential whose shape is a dotted identifier path and so is
3271
+ # excused by the tier-2 exclusion below (#863).
2489
3272
  if git grep -I -lE '${tier1Ere()}' -- .; then
2490
3273
  echo "::error::Potential secrets detected in tracked files"
2491
3274
  exit 1
@@ -2497,8 +3280,14 @@ jobs:
2497
3280
  # NOTE: do NOT append "|| true" to the assignment below. It makes the
2498
3281
  # assignment itself succeed, so $? is always 0 and the error branch
2499
3282
  # becomes dead code — the scan would fail open on a git error.
3283
+ # -i on tier 2 only, never on the tier-1 scan above: tier 1 matches
3284
+ # anchored key FORMATS whose case is part of the format, and it has
3285
+ # no allowlist to absorb a false positive. The flag is interpolated
3286
+ # from lib/secret-patterns.ts rather than typed here, because four
3287
+ # hand-written flags are four things that can disagree about what
3288
+ # counts as a secret (#844).
2500
3289
  set +e
2501
- tier2=$(git grep -I -hoE '(password|passwd|api[_-]?key|secret)[[:space:]]*[:=][[:space:]]*[A-Za-z0-9/+=_.-]{12,}' -- .)
3290
+ tier2=$(git grep -I -hoE ${TIER2_GREP_CASE_FLAG} '${tier2Ere()}' -- .)
2502
3291
  rc=$?
2503
3292
  set -e
2504
3293
  # git grep: 0 = match, 1 = no match, >1 = real error.
@@ -2509,26 +3298,196 @@ jobs:
2509
3298
  # Exclusion applies to the extracted VALUE, not the whole line.
2510
3299
  # Matching anywhere on the line let a trailing "# placeholder"
2511
3300
  # launder a real secret past the check.
2512
- if printf '%s\\n' "$tier2" | grep -qvE '^$|[:=][[:space:]]*(process\\.env|os\\.environ|Deno\\.env|getenv|REDACTED|CHANGEME|placeholder)'; then
3301
+ # It reads case the same way the capture does, for a reason
3302
+ # recorded in lib/secret-patterns.ts: the population the capture
3303
+ # newly sees is mostly .env.example, where a non-value is spelled
3304
+ # CHANGEME and PLACEHOLDER (#844).
3305
+ # The last alternative excuses a DOTTED IDENTIFIER PATH, anchored at
3306
+ # both ends so the whole value must be one. The value charset has no
3307
+ # quote characters, so in source tier 2 only ever sees an unquoted
3308
+ # value, and an unquoted value is an expression: apiKey:
3309
+ # config.judge.apiKey is a property reference, not a credential
3310
+ # (#863). A JWT has the same shape and is a credential, which is why
3311
+ # the tier-1 scan above carries it.
3312
+ # The optional dash after the separator is the shell-default
3313
+ # separator, so the placeholder vocabulary can reach the value of a
3314
+ # NAME:-default form. That vocabulary is a closed list of documented
3315
+ # non-values, not a judgement that a value looks harmless: a 32-char
3316
+ # random default carries none of its words and is still reported.
3317
+ if printf '%s\\n' "$tier2" | grep -qvE ${TIER2_GREP_CASE_FLAG} '${TIER2_ALLOWED_VALUE_ERE}'; then
2513
3318
  echo "::error::Potential credential assignment in tracked files"
2514
3319
  exit 1
2515
3320
  fi
3321
+ # Tier 3 — a credential written as a shell default, caught by SHAPE
3322
+ # rather than by a name. Tier 2 can only see one whose variable name
3323
+ # carries credential vocabulary; a variable named for what it holds
3324
+ # is invisible to it, and every neighbouring line in such a block
3325
+ # genuinely is a default, so the one that is not sits in a list of
3326
+ # things that look alike (#848).
3327
+ #
3328
+ # Captured first for the same reason tier 2 is: piping git straight
3329
+ # into the filter turns an error into empty input, which reads as
3330
+ # clean. No "|| true" on the assignment — see the note above.
3331
+ #
3332
+ # No -i here, and that is not an oversight: tier 3 has no vocabulary
3333
+ # to spell in the wrong case. Its classes already cover both cases,
3334
+ # and the flag would only widen the value class.
3335
+ set +e
3336
+ tier3=$(git grep -I -hoE '${tier3Ere()}' -- .)
3337
+ rc=$?
3338
+ set -e
3339
+ if [ "$rc" -gt 1 ]; then
3340
+ echo "::error::git grep failed (exit $rc) — refusing to report a clean scan"
3341
+ exit 1
3342
+ fi
3343
+ # The exclusion is the discriminator, not the length floor: a value
3344
+ # with no digit or no letter is a path, a container name or a port,
3345
+ # and those are what this shape is full of.
3346
+ if printf '%s\\n' "$tier3" | grep -qvE '${TIER3_ALLOWED_VALUE_ERE}'; then
3347
+ echo "::error::Potential credential in a shell default in tracked files"
3348
+ exit 1
3349
+ fi
2516
3350
  echo "Secret scan clean"
2517
3351
  `;
2518
3352
 
3353
+ // #630. The ai-review job, and the one property that makes it a check
3354
+ // rather than a decoration: there is NO `if:` here, at job level or step
3355
+ // level. A job skipped by `if:` reports `skipped`, and a skipped required
3356
+ // check can be treated as satisfied — a green required check for a review
3357
+ // that never ran. `secrets` is unavailable in `if:` at any level anyway, so
3358
+ // the mode is resolved inside `run:`, where it can emit an annotation and
3359
+ // choose an exit code. The step text is `buildAuthDetectStep()`'s verbatim,
3360
+ // not a copy: one decider for the script, and a mutation of it has one
3361
+ // binding. See lib/scaffold/ai-review-step.ts.
3362
+ //
3363
+ // `pull_request` and `merge_group`, and NOT `push`. A review of a pull
3364
+ // request has nothing to say about a push to a branch, and a trigger that
3365
+ // fires where the job cannot do its work is a run whose outcome means
3366
+ // nothing.
3367
+ //
3368
+ // `merge_group` is the exception to that sentence, and #867 is why it had to
3369
+ // be. This job was `pull_request`-only on exactly the reasoning above: a
3370
+ // merge group has no pull request, so the review would be vacuous. True, and
3371
+ // the wrong conclusion — it is an argument about what the job can DO on the
3372
+ // event, and it was applied to whether the job REPORTS on it. A consumer
3373
+ // makes `ai-review` a required context precisely because it is the check
3374
+ // that reads the code; a required context that never reports does not fail
3375
+ // the queue, it HANGS it, with every entry pending and nothing red anywhere.
3376
+ //
3377
+ // So the trigger is here and the vacuousness is handled where it belongs, in
3378
+ // the report step, which exits 0 on this event and says in a notice that no
3379
+ // review ran and why. That is sound rather than a green check for nothing: a
3380
+ // pull request cannot enter a merge queue without first satisfying its
3381
+ // required checks, so `ai-review` has already run on that exact head commit.
3382
+ //
3383
+ // No `branches:` filter, for the reason ci.yml states at length: the queue
3384
+ // builds a `gh-readonly-queue/<base>/...` ref that no branch list matches,
3385
+ // so a filtered trigger is an absent one that reads as handled.
3386
+ // #631. Workload Identity Federation, read from the consumer's own config.
3387
+ // One reading, taken here and threaded into both the permission block and
3388
+ // the steps — a second `vertexCiConfig(...)` call beside either would be a
3389
+ // decider that always agrees with this one and could never be told apart
3390
+ // from it (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
3391
+ const vertex = vertexCiConfig(harness?.ci);
3392
+
3393
+ // `id-token: write` is what lets the runner mint the OIDC token GCP's STS
3394
+ // exchanges. Granted ONLY when there is a federation to use it, because a
3395
+ // permission nobody consumes is a permission nobody audits.
3396
+ const aiReviewPermissions =
3397
+ vertex.config === null
3398
+ ? `permissions:\n contents: read`
3399
+ : `permissions:\n contents: read\n # Mint the OIDC token Workload Identity Federation exchanges (#631).\n id-token: write`;
3400
+
3401
+ const aiReviewYml = `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
3402
+ #
3403
+ ${buildOutcomesHeader(vertex)}#
3404
+ # This job is deliberately unconditional. A job skipped by a condition reports
3405
+ # \`skipped\`, which a required status check can be configured to accept, and
3406
+ # that is a green check for a review that never ran. The credential check
3407
+ # happens inside \`run:\` instead, and reports UNMEASURED when there is none.
3408
+ #
3409
+ # The second step says the same thing for the other door: a credential that
3410
+ # resolved with no reviewer wired to use it (#631) has also not produced a
3411
+ # review, and a check that stays quiet about that is the same defect.
3412
+ #
3413
+ # AUTHENTICATION. There is no service-account key in this file and no input
3414
+ # that could carry one. Vertex authenticates with Workload Identity
3415
+ # Federation: GitHub mints a short-lived OIDC token for this run, GCP's STS
3416
+ # exchanges it for an access token that expires in an hour, and no long-lived
3417
+ # credential exists anywhere on the runner (#677 AC-15). What this job holds
3418
+ # as read from this consumer's config:
3419
+ # ${vertex.reason}
3420
+ name: AI Review
3421
+
3422
+ on:
3423
+ # See the block comment in lib/scaffold/steps.ts: no branches: filter, and
3424
+ # its absence hangs a merge queue silently rather than failing it (#867).
3425
+ merge_group:
3426
+ pull_request:
3427
+ branches:
3428
+ ${branchList}
3429
+
3430
+ ${aiReviewPermissions}
3431
+
3432
+ jobs:
3433
+ ${AI_REVIEW_JOB}:
3434
+ runs-on: ${runsOn}
3435
+ steps:
3436
+ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(vertex, {
3437
+ checkout: actionRef("actions/checkout"),
3438
+ auth: actionRef(GOOGLE_AUTH_ACTION),
3439
+ review: actionRef(CLAUDE_CODE_ACTION),
3440
+ })}`;
3441
+
2519
3442
  // Not `writeFileSync`. The harness owns the `test` and `gates` jobs; it does
2520
3443
  // not own the file, and a consumer's own jobs have to survive the update
2521
3444
  // that re-scaffolding IS. A refusal is recorded rather than thrown so that
2522
3445
  // one unpreservable workflow does not abandon the rest of the scaffold
2523
3446
  // half-done — scripts/scaffold-project.ts exits non-zero on it.
2524
- for (const [name, content] of [["ci.yml", ciYml], ["gates.yml", gatesYml]] as const) {
3447
+ // The filenames are spelled here, not read from a constant, because
3448
+ // test/release-guard.test.ts pins this tuple as a literal: a directory-wide
3449
+ // write would take the caller-owned workflows with it, and a name behind an
3450
+ // import is a name that assertion cannot see. (That test also asserts this
3451
+ // module names no workflow it does not write — prose is indistinguishable
3452
+ // from a write to it — so the caller-owned files are not spelled anywhere
3453
+ // here, this comment included.) `AI_REVIEW_WORKFLOW_FILE` is the spelling
3454
+ // lib/conformity.ts reads back, and the two are held together by
3455
+ // test/ai-review-workflow.test.ts AC-1, which looks for the constant's
3456
+ // filename in what this loop actually wrote.
3457
+ for (const [name, content] of [["ci.yml", ciYml], ["gates.yml", gatesYml], ["ai-review.yml", aiReviewYml]] as const) {
2525
3458
  const label = `.github/workflows/${name}`;
2526
3459
  try {
2527
- writeManagedFile(join(workflowsDir, name), content, label, actions, opts);
3460
+ // Keyed by FILE, and the lookup is here because this loop is the only
3461
+ // place that knows which file is being written (#923).
3462
+ const computedSubKeys = HARNESS_COMPUTED_SUBKEYS.get(name) ?? new Map();
3463
+ // Stamped, so the file says who wrote it. The owned-path list is a list
3464
+ // of files this generator writes, which is precisely why it could never
3465
+ // describe a file it does not write — ownership has to travel with the
3466
+ // bytes for an unowned workflow to be visible at all (#722). The marker
3467
+ // is a YAML comment, so nothing that parses the workflow can see it.
3468
+ writeManagedFile(join(workflowsDir, name), content, label, actions, { ...opts, workflowOverrides: declined, computedSubKeys }, {
3469
+ body: workflowBody,
3470
+ stamp: stampWorkflow,
3471
+ });
2528
3472
  } catch (e) {
2529
3473
  actions.push(`REFUSED: ${(e as Error).message}`);
2530
3474
  }
2531
3475
  }
3476
+
3477
+ // #632 AC-14. One line, every scaffold, unconditional. `writeManagedFile`
3478
+ // above already reported that the FILE was written; this reports the thing
3479
+ // writing it does not establish — that the gate it contains is inert until
3480
+ // a credential resolves, which the generator cannot see and must therefore
3481
+ // not guess at. A consumer who reads only the checks list sees a green
3482
+ // `ai-review` and has no reason to look further, and that is #630.
3483
+ actions.push(aiReviewScaffoldAction(vertex));
3484
+
3485
+ // Everything else in the directory, named. This generator writes three
3486
+ // files; a consumer's CI may run any number, and until #722 the ones it did
3487
+ // not write were not merely unmanaged but unreported — a clean run over 2 of
3488
+ // 7 workflow files, which reads exactly like a clean run over 7 of 7.
3489
+ // Reporting only: what a consumer does with a NOT-OWNED workflow is theirs.
3490
+ actions.push(...censusReport(workflowCensus(root)));
2532
3491
  }
2533
3492
 
2534
3493
  // ── Consumer hook deployment ─────────────────────────────────
@@ -2614,6 +3573,62 @@ export function deployHooksToConsumers(root: string, actions: string[]): void {
2614
3573
  }
2615
3574
  }
2616
3575
 
3576
+ /**
3577
+ * ## The generated pre-commit hook, as one binding (#610)
3578
+ *
3579
+ * ## What was wrong
3580
+ *
3581
+ * The hook decided WHICH updater to run by sniffing the working tree at
3582
+ * commit time:
3583
+ *
3584
+ * updater=""
3585
+ * if [ -f "scripts/update-project-state.ts" ]; then
3586
+ * updater="scripts/update-project-state.ts"
3587
+ * elif [ -f "node_modules/rungate/scripts/update-project-state.ts" ]; then
3588
+ * updater="node_modules/rungate/scripts/update-project-state.ts"
3589
+ * fi
3590
+ *
3591
+ * and the comment above it said the order was deliberate because "a checkout
3592
+ * that has its own scripts/ copy is the harness". That is an identity
3593
+ * inferred from a FILENAME. "This tree holds a file at this path" and "this
3594
+ * tree is the rungate harness" are different facts, and the hook treated the
3595
+ * first as proof of the second — so a consumer that keeps a script at that
3596
+ * path for its own reasons was silently reclassified as the harness and ran a
3597
+ * different program than the one rungate installed. Nothing in the commit
3598
+ * recorded which branch fired, so the two outcomes were indistinguishable
3599
+ * afterwards.
3600
+ *
3601
+ * A detector narrower than what it detects
3602
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, second shape), with the
3603
+ * *Silent Default Substitution* that `.claude/rules/config-access.md` refuses
3604
+ * sitting underneath it.
3605
+ *
3606
+ * ## What it does instead
3607
+ *
3608
+ * The decision is taken HERE, at generation time, and one concrete path is
3609
+ * baked into the emitted script. The hook names the program it runs; a tree
3610
+ * that acquires a same-named file afterwards cannot change what executes.
3611
+ *
3612
+ * Identity is read from the project's own declaration — `isHarnessItself`,
3613
+ * which reads `package.json`'s `name` and is the single existing binding for
3614
+ * this question in the tree (#380). It is deliberately NOT a second reading
3615
+ * of the same fact: two deciders that agree are behaviourally one, and no
3616
+ * mutation of either could tell them apart.
3617
+ *
3618
+ * ## Three readings, and UNMEASURED is one of them
3619
+ *
3620
+ * | the tree declares | the candidate | emitted |
3621
+ * |---|---|---|
3622
+ * | `name: "rungate"` | `scripts/update-project-state.ts` | that path, baked |
3623
+ * | anything else | `node_modules/rungate/scripts/…` | that path, baked |
3624
+ * | either, candidate absent | — | UNMEASURED, and no lookup at all |
3625
+ *
3626
+ * The third row is the one that must not be a guess. A hook carrying a
3627
+ * lookup "in case the file turns up later" succeeds at some unknown future
3628
+ * commit for a reason nobody chose, and `0`, `""`, `null` and a
3629
+ * plausible-looking path are all indistinguishable from success.
3630
+ */
3631
+
2617
3632
  /**
2618
3633
  * The line that marks a pre-commit hook as ours, so a fix can reach one that
2619
3634
  * already exists (#450).
@@ -2627,18 +3642,104 @@ export function deployHooksToConsumers(root: string, actions: string[]): void {
2627
3642
  */
2628
3643
  export const PRE_COMMIT_MANAGED_MARKER = "# Managed by rungate — secret scan + PROJECT-STATE update";
2629
3644
 
2630
- export function createGitHooks(root: string, actions: string[]): void {
2631
- const hooksDir = join(root, ".git", "hooks");
2632
- if (!existsSync(hooksDir)) return;
3645
+ /**
3646
+ * Present in EVERY form this generator emits, resolved or not.
3647
+ *
3648
+ * `scripts/check-installed-hook-currency.ts` probes for it to tell a hook
3649
+ * that predates #610 from one that carries it, and that probe has to work for
3650
+ * a consumer and for the harness alike — so it cannot be either baked path.
3651
+ */
3652
+ export const UPDATER_GENERATION_MARKER =
3653
+ "# Which updater runs was decided when this hook was generated (#610), not here.";
2633
3654
 
2634
- const { chmodSync } = require("fs");
3655
+ /** The harness's own copy, relative to the project root. */
3656
+ export const HARNESS_UPDATER = "scripts/update-project-state.ts";
2635
3657
 
2636
- const preCommit = join(hooksDir, "pre-commit");
2637
- const existingPreCommit = existsSync(preCommit) ? readFileSync(preCommit, "utf-8") : null;
2638
- if (existingPreCommit !== null && !existingPreCommit.includes(PRE_COMMIT_MANAGED_MARKER)) {
2639
- actions.push("SKIP: .git/hooks/pre-commit (hand-written, not overwriting)");
2640
- } else {
2641
- writeFileSync(preCommit, `#!/bin/sh
3658
+ /** The copy rungate installs into a consumer, relative to the project root. */
3659
+ export const VENDORED_UPDATER = "node_modules/rungate/scripts/update-project-state.ts";
3660
+
3661
+ export type UpdaterIdentity = "harness" | "consumer";
3662
+
3663
+ export interface UpdaterResolution {
3664
+ /** What the tree declared itself to be, read from package.json's name. */
3665
+ identity: UpdaterIdentity;
3666
+ /** The one path that identity selects — present or not. */
3667
+ candidate: string;
3668
+ /** The path baked into the hook, or null when the candidate is absent. */
3669
+ path: string | null;
3670
+ }
3671
+
3672
+ /**
3673
+ * The single decider. One binding to mutate, asked once by
3674
+ * `preCommitHookScript` and nowhere else.
3675
+ */
3676
+ export function resolveUpdater(root: string): UpdaterResolution {
3677
+ const identity: UpdaterIdentity = isHarnessItself(root) ? "harness" : "consumer";
3678
+ const candidate = identity === "harness" ? HARNESS_UPDATER : VENDORED_UPDATER;
3679
+ return {
3680
+ identity,
3681
+ candidate,
3682
+ path: existsSync(join(root, candidate)) ? candidate : null,
3683
+ };
3684
+ }
3685
+
3686
+ const IDENTITY_NOTE: Record<UpdaterIdentity, string> = {
3687
+ harness:
3688
+ "# package.json names this tree as the rungate harness, so the updater is its own\n" +
3689
+ " # scripts/ copy — never a vendored duplicate of itself, which would be stale.",
3690
+ consumer:
3691
+ "# package.json does not name this tree as the harness, so the updater is the copy\n" +
3692
+ " # rungate installed. A script this project keeps at scripts/ is its own program\n" +
3693
+ " # and is not run here, whatever it is called.",
3694
+ };
3695
+
3696
+ /**
3697
+ * The block that goes inside the primary-checkout arm.
3698
+ *
3699
+ * The resolved form contains the path EXACTLY ONCE — in the assignment — so
3700
+ * there is one literal to mutate and one literal for a test to count. The
3701
+ * echo below it reports `$updater` rather than repeating the path, which is
3702
+ * the same reason: a second copy would survive any mutation of the first.
3703
+ */
3704
+ function updaterBlock(r: UpdaterResolution): string {
3705
+ if (r.path === null) {
3706
+ return ` ${UPDATER_GENERATION_MARKER}
3707
+ ${IDENTITY_NOTE[r.identity]}
3708
+ #
3709
+ # Nothing was found there when this hook was generated, so this hook runs
3710
+ # no updater and performs no lookup. A lookup kept "in case it turns up"
3711
+ # would succeed at some later commit for a reason nobody chose.
3712
+ echo "project-state: UNMEASURED — when this hook was generated this tree read as a ${r.identity} checkout and no updater was present at ${r.candidate}. This hook runs none and stages nothing. Re-scaffold once it is installed." >&2`;
3713
+ }
3714
+ return ` ${UPDATER_GENERATION_MARKER}
3715
+ ${IDENTITY_NOTE[r.identity]}
3716
+ updater="${r.path}"
3717
+ # Say which program is about to run, before running it. Without this the
3718
+ # commit's output records nothing about which updater fired and the
3719
+ # answer is only recoverable by inspecting the tree afterwards (#610).
3720
+ echo "project-state: running $updater (resolved when this hook was generated)" >&2
3721
+ if bun "$updater" --skip-tests >&2; then
3722
+ # Staged only after the updater SUCCEEDED. Staging regardless is the
3723
+ # fail-open the readings above exist to replace: it puts yesterday's
3724
+ # PROJECT-STATE.md in today's commit, and the commit then looks exactly
3725
+ # like one that updated it.
3726
+ git add PROJECT-STATE.md project-state.json 2>/dev/null || true
3727
+ else
3728
+ echo "project-state: UNMEASURED — $updater exited non-zero, so PROJECT-STATE.md and project-state.json were NOT staged. Run it by hand to see why." >&2
3729
+ fi`;
3730
+ }
3731
+
3732
+ /**
3733
+ * What `createGitHooks` writes, for a given project root.
3734
+ *
3735
+ * A function of the root rather than a constant, because the updater is
3736
+ * resolved here. It writes nothing: `scripts/check-installed-hook-currency.ts`
3737
+ * has to obtain the text for a project it is only INSPECTING, and a generator
3738
+ * that could only answer by installing itself would make the check the thing
3739
+ * it is checking.
3740
+ */
3741
+ export function preCommitHookScript(root: string): string {
3742
+ return `#!/bin/sh
2642
3743
  ${PRE_COMMIT_MANAGED_MARKER}
2643
3744
  #
2644
3745
  # Scans the staged DIFF, not files on disk. This is deliberate and fixes four
@@ -2678,14 +3779,43 @@ fi
2678
3779
  # Exclusions are env lookups and explicit non-values. password =
2679
3780
  # process.env.DB_PASSWORD is a reference, not a secret, and flagging it would
2680
3781
  # only train people to reach for --no-verify.
3782
+ #
3783
+ # Both expressions are interpolated from lib/secret-patterns.ts, never
3784
+ # written here. A hardcoded copy is a second binding for one string, and
3785
+ # #489's narrowing then has to be applied in places nothing compares. The
3786
+ # allowlist's leading \`^$|\` alternative cannot fire on this pipeline —
3787
+ # grep -oE emits no empty lines — so using the one constant is the same
3788
+ # behaviour with one fewer decider.
3789
+ #
3790
+ # -i is on both tier-2 greps and on neither tier-1 one, interpolated from the
3791
+ # same constant the CI job uses. Without it the vocabulary could only see
3792
+ # lowercase, which is the spelling an environment variable or a shell default
3793
+ # is least often written in (#844).
2681
3794
  if printf '%s\\n' "$staged_diff" \\
2682
3795
  | grep '^+' \\
2683
- | grep -oE '(password|passwd|api[_-]?key|secret)[[:space:]]*[:=][[:space:]]*[A-Za-z0-9/+=_.-]{12,}' \\
2684
- | grep -qvE '[:=][[:space:]]*(process\\.env|os\\.environ|Deno\\.env|getenv|REDACTED|CHANGEME|placeholder)'; then
3796
+ | grep -oE ${TIER2_GREP_CASE_FLAG} '${tier2Ere()}' \\
3797
+ | grep -qvE ${TIER2_GREP_CASE_FLAG} '${TIER2_ALLOWED_VALUE_ERE}'; then
2685
3798
  echo "ERROR: Potential credential assignment in staged changes"
2686
3799
  exit 1
2687
3800
  fi
2688
3801
 
3802
+ # Tier 3 — a credential written as a shell default, caught by shape rather
3803
+ # than by the variable name. Tier 2 only sees one whose name carries
3804
+ # credential vocabulary (#848).
3805
+ #
3806
+ # Both expressions are interpolated from lib/secret-patterns.ts for the
3807
+ # reason tier 2's are: a hardcoded copy is a second binding for one string.
3808
+ #
3809
+ # No -i, deliberately. Tier 3 has no vocabulary to miss in the wrong case,
3810
+ # and the flag would only widen the value class.
3811
+ if printf '%s\\n' "$staged_diff" \\
3812
+ | grep '^+' \\
3813
+ | grep -oE '${tier3Ere()}' \\
3814
+ | grep -qvE '${TIER3_ALLOWED_VALUE_ERE}'; then
3815
+ echo "ERROR: Potential credential in a shell default in staged changes"
3816
+ exit 1
3817
+ fi
3818
+
2689
3819
  # Update PROJECT-STATE if it exists — but NEVER from a linked worktree (#450).
2690
3820
  #
2691
3821
  # project-state.json, PROJECT-STATE.md and SUCCESS.md are DA-owned: a single
@@ -2709,17 +3839,28 @@ fi
2709
3839
  # linked worktree. An unmeasured guard is indistinguishable from an absent
2710
3840
  # one, so it is absent. git hooks run from the toplevel, and both calls share
2711
3841
  # a cwd, so there was never a case that needed it.
3842
+ #
3843
+ # The primary arm had three fail-opens in two lines (#599), and the shape is
3844
+ # this file's recurring one: a check that passed because of what it never
3845
+ # looked at. The path was the CONSUMER layout, so in the harness's own
3846
+ # checkout — which has scripts/update-project-state.ts and no
3847
+ # node_modules/rungate at all — bun exited non-zero on a file that is not
3848
+ # there. 2>/dev/null threw the ENOENT away, || true threw the status away, and
3849
+ # the git add below then staged whatever happened to be on disk.
3850
+ #
3851
+ # Every message is on STDERR: stdout is what a caller captures as the
3852
+ # command's answer, and a decline, a reading and an updater's progress are all
3853
+ # diagnosis rather than output.
2712
3854
  if [ -f "project-state.json" ]; then
2713
3855
  gitdir=$(git rev-parse --git-dir)
2714
3856
  commondir=$(git rev-parse --git-common-dir)
2715
3857
  if [ -n "$gitdir" ] && [ "$gitdir" = "$commondir" ]; then
2716
- bun node_modules/rungate/scripts/update-project-state.ts --skip-tests 2>/dev/null || true
2717
- git add PROJECT-STATE.md project-state.json 2>/dev/null || true
3858
+ ${updaterBlock(resolveUpdater(root))}
2718
3859
  else
2719
3860
  # Announced, not silent. A developer who expected the state files to move
2720
3861
  # would otherwise be left guessing, and SKIP that says nothing is
2721
3862
  # indistinguishable from the update having happened.
2722
- echo "project-state: SKIPPED — linked worktree. project-state.json, PROJECT-STATE.md and SUCCESS.md are DA-owned (#296); update them from the primary checkout."
3863
+ echo "project-state: SKIPPED — linked worktree. project-state.json, PROJECT-STATE.md and SUCCESS.md are DA-owned (#296); update them from the primary checkout." >&2
2723
3864
  fi
2724
3865
  fi
2725
3866
 
@@ -2728,61 +3869,95 @@ fi
2728
3869
  # made the hook exit non-zero and reject a perfectly good commit. Everything
2729
3870
  # that should block has already exited 1 above.
2730
3871
  exit 0
2731
- `);
2732
- chmodSync(preCommit, 0o755);
2733
- actions.push(
2734
- existingPreCommit === null
2735
- ? "CREATED: .git/hooks/pre-commit (secret scan + PROJECT-STATE update)"
2736
- : "UPDATED: .git/hooks/pre-commit (secret scan + PROJECT-STATE update)",
2737
- );
2738
- }
3872
+ `;
3873
+ }
2739
3874
 
2740
- const prePush = join(hooksDir, "pre-push");
2741
- const MANAGED_MARKER = PRE_PUSH_MANAGED_MARKER;
3875
+ /**
3876
+ * One hook the scaffold installs (#891).
3877
+ *
3878
+ * `createGitHooks` used to name each hook in its own paragraph of imperative
3879
+ * code, and `scripts/check-installed-hook-currency.ts` joined the literal
3880
+ * `pre-commit` and compared that one file. Two positions deciding what the
3881
+ * set of hooks is, with nothing comparing them — so the installed `pre-push`
3882
+ * in this repository sat four months and one mutation battery behind its
3883
+ * generator while the currency check printed a verdict about the other hook
3884
+ * and exited 0.
3885
+ *
3886
+ * This is the declaration both of them read. A hook added here is installed
3887
+ * by the loop below AND reported by the checker, without either being
3888
+ * edited; that is the property `test/unit/hook-currency-population.test.ts`
3889
+ * AC-5 plants a case for, and it is what the cheap repair — adding the
3890
+ * string `"pre-push"` to the checker — does not buy.
3891
+ *
3892
+ * `script` takes the project root because the pre-commit hook's content
3893
+ * depends on it (#610): the updater it names is resolved at generation time
3894
+ * from what the project declares itself to be. A hook that does not care
3895
+ * ignores the argument.
3896
+ */
3897
+ export interface GeneratedHook {
3898
+ /** The file name under the hooks directory, and the name every report uses. */
3899
+ name: string;
3900
+ /** The script this project should have, generated and written nowhere. */
3901
+ script: (root: string) => string;
3902
+ /** The line that marks an installed copy as one of ours. */
3903
+ marker: string;
3904
+ /** What the scaffold's action log calls it. */
3905
+ describes: string;
3906
+ }
2742
3907
 
2743
- // `2>/dev/null` threw away the only output that said WHY conformity failed,
2744
- // leaving the developer a bare "fix before pushing" and no diagnosis. And the
2745
- // old guard was `if (!existsSync(prePush))`, so once a hook existed it was
2746
- // never updated again — every fix to this hook, including this one, would
2747
- // have reached nobody. Overwrite only our own managed hook; a hook a human
2748
- // wrote is left alone.
2749
- const existing = existsSync(prePush) ? readFileSync(prePush, "utf-8") : null;
2750
- if (existing !== null && !existing.includes(MANAGED_MARKER)) {
2751
- actions.push("SKIP: .git/hooks/pre-push (hand-written, not overwriting)");
2752
- return;
2753
- }
3908
+ export const GENERATED_HOOKS: ReadonlyArray<GeneratedHook> = [
3909
+ {
3910
+ name: "pre-commit",
3911
+ script: preCommitHookScript,
3912
+ marker: PRE_COMMIT_MANAGED_MARKER,
3913
+ describes: "secret scan + PROJECT-STATE update",
3914
+ },
3915
+ {
3916
+ // Checks the COMMITS BEING PUSHED, not the working tree (#85). The old
3917
+ // hook ran conformity in the working tree, which is not what is being
3918
+ // pushed: on 2026-10-05 that let a regression reach main, because
3919
+ // HYGIENE-3's reference index recursed into `.claude/worktrees/` and
3920
+ // every file looked referenced. A gate that inspects something other
3921
+ // than what it is gating is not a weaker gate; it is a different gate
3922
+ // wearing the name of the one you wanted.
3923
+ //
3924
+ // The script itself lives in `lib/scaffold/pre-push-hook.ts` (#397). As
3925
+ // a template literal here it was unrunnable, and the thing nothing runs
3926
+ // is the thing nothing checks.
3927
+ name: "pre-push",
3928
+ script: () => prePushHookScript(),
3929
+ marker: PRE_PUSH_MANAGED_MARKER,
3930
+ describes: "conformity check",
3931
+ },
3932
+ ];
2754
3933
 
2755
- // Checks the COMMITS BEING PUSHED, not the working tree (#85).
2756
- //
2757
- // The old hook ran the conformity suite in the working tree, which is not
2758
- // what is being pushed. On 2026-10-05 that let a regression reach main:
2759
- // HYGIENE-3's reference index recursed into .claude/worktrees/, 39 full repo
2760
- // copies that exist locally and not in a clean checkout, so every file
2761
- // looked referenced. It passed before push and Gates went red on main. A
2762
- // gate that inspects something other than what it is gating is not a weaker
2763
- // gate; it is a different gate wearing the name of the one you wanted.
2764
- //
2765
- // On node_modules, which #85 left open: symlinking the working tree's is
2766
- // fast, and it is honest exactly while the pushed commit's lockfile matches
2767
- // the one those modules were installed from. Installing unconditionally is
2768
- // correct and slow enough that people disable the hook, which is worse than
2769
- // either. So compare the lockfiles and only pay for an install when they
2770
- // actually differ — the common push changes no dependencies and keeps the
2771
- // fast path, and the push that does change them cannot quietly test against
2772
- // the wrong ones.
2773
- //
2774
- // The script itself lives in lib/scaffold/pre-push-hook.ts (#397). As a
2775
- // template literal here it was unrunnable, and the thing nothing runs is
2776
- // the thing nothing checks: the lockfile comparison read the CHECKOUT's
2777
- // `bun.lock`, so a consumer that gitignores its lockfile could never take
2778
- // the fast path and could never pass. Over there it is one binding with one
2779
- // exit-code constant, and test/pre-push-hook.test.ts drives it against
2780
- // planted repositories.
2781
- writeFileSync(prePush, prePushHookScript());
2782
- chmodSync(prePush, 0o755);
2783
- actions.push(existing === null
2784
- ? "CREATED: .git/hooks/pre-push (conformity check)"
2785
- : "UPDATED: .git/hooks/pre-push (conformity check)");
3934
+ export function createGitHooks(root: string, actions: string[]): void {
3935
+ const hooksDir = join(root, ".git", "hooks");
3936
+ if (!existsSync(hooksDir)) return;
3937
+
3938
+ const { chmodSync } = require("fs");
3939
+
3940
+ // A loop over the declaration, and not four paragraphs. The old shape also
3941
+ // carried a `return` in the pre-push SKIP arm, which was harmless only
3942
+ // because pre-push happened to be last — a third hook would have been
3943
+ // silently skipped for every project with a hand-written pre-push.
3944
+ for (const hook of GENERATED_HOOKS) {
3945
+ const at = join(hooksDir, hook.name);
3946
+ const existing = existsSync(at) ? readFileSync(at, "utf-8") : null;
3947
+ // Overwrite only our own managed hook; a hook a human wrote is left
3948
+ // alone. The old guard here was `if (!existsSync(prePush))`, so once a
3949
+ // hook existed it was never updated again and every fix to it — this one
3950
+ // included — would have reached nobody.
3951
+ if (existing !== null && !existing.includes(hook.marker)) {
3952
+ actions.push(`SKIP: .git/hooks/${hook.name} (hand-written, not overwriting)`);
3953
+ continue;
3954
+ }
3955
+ writeFileSync(at, hook.script(root));
3956
+ chmodSync(at, 0o755);
3957
+ actions.push(
3958
+ `${existing === null ? "CREATED" : "UPDATED"}: .git/hooks/${hook.name} (${hook.describes})`,
3959
+ );
3960
+ }
2786
3961
  }
2787
3962
 
2788
3963
  /**
@@ -3113,7 +4288,7 @@ export function runAuditSpecsFix(root: string, actions: string[]): void {
3113
4288
  actions.push("SKIP: audit-specs (no specs/ directory)");
3114
4289
  return;
3115
4290
  }
3116
- const specFiles = readdirSync(specsDir).filter(f => f.endsWith(".md"));
4291
+ const specFiles = readdirSorted(specsDir).filter(f => f.endsWith(".md"));
3117
4292
  if (specFiles.length === 0) {
3118
4293
  actions.push("SKIP: audit-specs (no spec files)");
3119
4294
  return;
@@ -3225,15 +4400,64 @@ export function writtenPath(line: string): string | null {
3225
4400
  return m?.[1] ?? null;
3226
4401
  }
3227
4402
 
3228
- export function reportScaffoldActions(actions: string[]): number {
4403
+ /**
4404
+ * What an action line carries when the run that produced it was a rehearsal.
4405
+ *
4406
+ * **A TRAILING marker, and that is a constraint rather than a preference.**
4407
+ * `writtenPath` above matches `^(?:CREATED|UPDATED|…): path` after a trim,
4408
+ * and two callers depend on it: `postScaffoldCommit` stages by it, and
4409
+ * `test/scaffold-audit-agreement.test.ts` compares the paths audit NAMES
4410
+ * against the paths `--fix` WROTE. A leading `REHEARSED ` prefix — the form
4411
+ * #642 suggests — makes `writtenPath` return null for every audit line, so
4412
+ * that comparison would go green with nothing in it on both sides. Agreement
4413
+ * by both sides reporting nothing is the vacuous shape #398 built it to
4414
+ * avoid.
4415
+ *
4416
+ * Square brackets rather than parentheses on purpose: most action lines
4417
+ * already end in a parenthetical (`(security template)`, `(rungate devDep)`),
4418
+ * and a marker that looks like one more of those is one a reader skims past.
4419
+ *
4420
+ * One exported binding, so there is one thing to mutate and one string for a
4421
+ * consumer to grep.
4422
+ */
4423
+ export const REHEARSAL_MARKER = " [REHEARSAL — not applied]";
4424
+
4425
+ /**
4426
+ * ## Every line, because a line is the unit a reader consumes (#642)
4427
+ *
4428
+ * The mode was announced exactly once, by `rehearsalNotice`, at the top of
4429
+ * the run — and then no line of the report carried it. Measured on two
4430
+ * planted repositories: **all 56 of an audit's report lines were
4431
+ * byte-identical to the lines `--fix` printed for the same work.** So
4432
+ * `grep ci.yml`, `| tail -25`, a scrolled terminal, and an agent reading the
4433
+ * last N lines of a tool result all received `REPLACED: … (+114 lines)` with
4434
+ * no way to tell it from a write that landed. The issue's author read one
4435
+ * four times and filed a missing-write bug off it. The report never lied;
4436
+ * its unit of qualification was wider than its unit of consumption.
4437
+ *
4438
+ * `mode` is REQUIRED rather than defaulted. A default of `false` is a silent
4439
+ * default substitution (`.claude/rules/config-access.md`): a future call site
4440
+ * that forgets to say which mode it is in would print unqualified lines and
4441
+ * look exactly like one that meant to.
4442
+ *
4443
+ * **Not sufficient: marking the `Total:` line, or the first line.** That is
4444
+ * the cheapest repair and it leaves every grep/tail/scrolled consumer in
4445
+ * precisely the position the issue is about. The `Total:` line is marked as
4446
+ * well, but after the per-line marking, not instead of it.
4447
+ */
4448
+ export function reportScaffoldActions(actions: string[], mode: { rehearsed: boolean }): number {
4449
+ const qualify = (line: string) => (mode.rehearsed ? `${line}${REHEARSAL_MARKER}` : line);
3229
4450
  console.log("\n=== Scaffold Report ===");
3230
- for (const action of actions) console.log(` ${action}`);
4451
+ for (const action of actions) console.log(` ${qualify(action)}`);
3231
4452
  const count = (verb: string) => actions.filter(a => a.startsWith(verb)).length;
3232
4453
  // AUTO-FIXED is reported separately from AUDITED on purpose (#42 SC-3).
3233
4454
  // What the scaffold CHANGED and what it merely NOTICED are different facts,
3234
4455
  // and a reader who cannot tell them apart has to diff the tree to find out
3235
4456
  // which of the reported gaps are still gaps.
3236
- console.log(`\nTotal: ${count("CREATED")} created, ${count("REPLACED")} replaced, ${count("AUTO-FIXED")} auto-fixed, ${count("SKIP")} skipped, ${count("REFUSED")} refused`);
4457
+ // The marker goes on the END of this line rather than into the `Total:`
4458
+ // token: `test/scaffold-auto-fix.test.ts` finds it with
4459
+ // `startsWith("\nTotal:")`, and a reader's eye finds it the same way.
4460
+ console.log(qualify(`\nTotal: ${count("CREATED")} created, ${count("REPLACED")} replaced, ${count("AUTO-FIXED")} auto-fixed, ${count("SKIP")} skipped, ${count("REFUSED")} refused`));
3237
4461
  return count("REFUSED");
3238
4462
  }
3239
4463