rungate 0.6.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 (113) 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 +81 -16
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-protection.ts +790 -0
  7. package/lib/brief-ac-alignment.ts +104 -0
  8. package/lib/brief-references.ts +205 -0
  9. package/lib/bun-version.ts +93 -14
  10. package/lib/check-remedy.ts +140 -0
  11. package/lib/ci-checkout.ts +17 -0
  12. package/lib/ci-history-depth.ts +159 -0
  13. package/lib/ci-setup-step.ts +96 -0
  14. package/lib/claude-code-action.ts +85 -0
  15. package/lib/claude-tool-vocabulary.ts +188 -0
  16. package/lib/cli-commands.ts +15 -0
  17. package/lib/commit-sha.ts +42 -0
  18. package/lib/commit-subject.ts +90 -0
  19. package/lib/compliance-report.ts +377 -45
  20. package/lib/compliance.ts +191 -17
  21. package/lib/config-loader.ts +39 -1
  22. package/lib/config-trackable.ts +391 -0
  23. package/lib/conformity.ts +1087 -100
  24. package/lib/containment.ts +238 -0
  25. package/lib/content-hash.ts +24 -0
  26. package/lib/create-sc.ts +249 -16
  27. package/lib/dev-liveness.ts +180 -0
  28. package/lib/discovery-branch-points.ts +432 -0
  29. package/lib/discovery-stability.ts +481 -0
  30. package/lib/distribution-currency.ts +186 -0
  31. package/lib/doc-routing.ts +157 -0
  32. package/lib/evidence-prevalidator.ts +224 -2
  33. package/lib/evidence-satisfiability.ts +534 -12
  34. package/lib/failure-intake.ts +317 -0
  35. package/lib/fallow-availability.ts +157 -0
  36. package/lib/fs-write-capabilities.ts +232 -0
  37. package/lib/gate-run-split.ts +147 -0
  38. package/lib/generators/agents-md.ts +140 -32
  39. package/lib/git-isolation.ts +140 -0
  40. package/lib/github.ts +15 -0
  41. package/lib/google-auth-action.ts +93 -0
  42. package/lib/harness-project.ts +48 -0
  43. package/lib/harness-provenance.ts +255 -0
  44. package/lib/hook-evidence.ts +235 -0
  45. package/lib/hook-scopes.ts +386 -0
  46. package/lib/hook-target-tree.ts +398 -0
  47. package/lib/hook-trees.ts +447 -0
  48. package/lib/js-top-level-code.ts +78 -10
  49. package/lib/junit-checks.ts +52 -0
  50. package/lib/launch-base.ts +253 -0
  51. package/lib/line-citation.ts +372 -0
  52. package/lib/orphan-reaper.ts +468 -0
  53. package/lib/parity-binding.ts +205 -0
  54. package/lib/per-test-timeouts.ts +219 -0
  55. package/lib/plan-coverage.ts +151 -0
  56. package/lib/prior-branch.ts +201 -8
  57. package/lib/process-table.ts +146 -0
  58. package/lib/project-state-derivation.ts +219 -0
  59. package/lib/project-state-root.ts +258 -0
  60. package/lib/published-artifact.ts +525 -0
  61. package/lib/readdir-sorted.ts +45 -0
  62. package/lib/review-execution-reading.ts +206 -0
  63. package/lib/review-tool-agreement.ts +433 -0
  64. package/lib/rule-promotion.ts +234 -0
  65. package/lib/rule-retirement.ts +525 -0
  66. package/lib/run-branch.ts +612 -0
  67. package/lib/rungate-schema.ts +19 -0
  68. package/lib/runner-home.ts +274 -0
  69. package/lib/sc-id-cross-tree.ts +19 -7
  70. package/lib/sc-ids.ts +121 -13
  71. package/lib/sc-reservations.ts +289 -0
  72. package/lib/scaffold/ai-review-findings.ts +403 -0
  73. package/lib/scaffold/ai-review-step.ts +4661 -64
  74. package/lib/scaffold/managed-workflow.ts +587 -192
  75. package/lib/scaffold/owned-files.ts +152 -45
  76. package/lib/scaffold/pre-push-hook.ts +49 -5
  77. package/lib/scaffold/steps.ts +1413 -244
  78. package/lib/scaffold/workflow-census.ts +217 -0
  79. package/lib/scaffold/workflow-drift.ts +217 -0
  80. package/lib/scaffold/write-steps.ts +4 -0
  81. package/lib/scan-budget.ts +247 -0
  82. package/lib/scanner.ts +43 -51
  83. package/lib/scratch-roots.ts +50 -5
  84. package/lib/screenshot-discovery.ts +121 -0
  85. package/lib/screenshot-upload.ts +41 -1
  86. package/lib/secret-patterns.ts +511 -8
  87. package/lib/ship-mode.ts +219 -0
  88. package/lib/source-slice.ts +294 -0
  89. package/lib/stale-cleanup.ts +37 -3
  90. package/lib/suite-flake.ts +278 -0
  91. package/lib/suite-measurement.ts +23 -4
  92. package/lib/suite-run-reading.ts +241 -1
  93. package/lib/suite-timeout-margin.ts +193 -0
  94. package/lib/test-case-bodies.ts +883 -0
  95. package/lib/test-case-deletion.ts +653 -0
  96. package/lib/test-census.ts +97 -29
  97. package/lib/test-command-positions.ts +274 -0
  98. package/lib/test-suite-lock.ts +159 -16
  99. package/lib/tool-probe.ts +31 -9
  100. package/lib/top-level-cd.ts +393 -0
  101. package/lib/tree-entries.ts +89 -0
  102. package/lib/ts-ast.ts +200 -0
  103. package/lib/walk-test-files.ts +97 -0
  104. package/lib/workflow-actions.ts +263 -0
  105. package/lib/worktree-collect.ts +177 -5
  106. package/lib/worktree-repo.ts +36 -1
  107. package/package.json +2 -1
  108. package/scripts/ai-review-findings.ts +45 -0
  109. package/scripts/create-sc.ts +21 -1
  110. package/scripts/extract-constraints.ts +107 -7
  111. package/scripts/generate-code-map.ts +23 -30
  112. package/scripts/scaffold-project.ts +8 -1
  113. package/scripts/sync-sc-status.ts +77 -16
@@ -0,0 +1,104 @@
1
+ /**
2
+ * Does the Marcus brief cover every AC the state declares? (ADR-009 C2, #700)
3
+ *
4
+ * This is the decision behind `brief-ac-alignment` in `gates/workflow.test.ts`,
5
+ * lifted out so there is ONE binding to mutate and so the two refusals can be
6
+ * driven directly instead of through a spawned gate.
7
+ *
8
+ * ## Why it moved (#700)
9
+ *
10
+ * The check failed on five consecutive pushes to `main` and nobody could say
11
+ * which of its two branches fired. Both refusals were written inline, and
12
+ * neither named the path it had resolved:
13
+ *
14
+ * expect("marcus-brief.md missing").toBe("brief file required when Marcus spawned (ADR-009 C2)")
15
+ * expect(missingIds, `brief-ac-alignment: brief missing AC ids: ${...}`).toEqual([])
16
+ *
17
+ * `brief missing AC ids: AC-2` tells a reader WHICH id is absent and not
18
+ * WHERE the check looked — and the path is the whole question here, because
19
+ * it is assembled at call time from `RUNGATE_WORK_DIR`, a `$HOME/.rungate`
20
+ * fallback and the state's slug. A reading that is wrong about its directory
21
+ * and a brief that is genuinely short are the same sentence today.
22
+ *
23
+ * So every refusal names the resolved path. One interpolated string, and it
24
+ * converts "the brief is wrong" into "the brief at <this path> is wrong",
25
+ * which is a claim somebody can check.
26
+ *
27
+ * ## The reading is total, and `NOT_APPLICABLE` is a state
28
+ *
29
+ * The inline version `return`ed in two places — no slug, and an absent brief
30
+ * with Marcus not spawned — which made "the check decided nothing was wrong"
31
+ * and "the check declined to look" the same observation from outside. They
32
+ * are different, so they are different readings. `0`, `{}` and silence are
33
+ * indistinguishable from success (`.claude/rules/config-access.md`).
34
+ */
35
+
36
+ export type BriefAlignmentReading =
37
+ | "ALIGNED"
38
+ | "BRIEF_ABSENT"
39
+ | "IDS_MISSING"
40
+ | "NOT_APPLICABLE";
41
+
42
+ export interface BriefAlignment {
43
+ reading: BriefAlignmentReading;
44
+ /** The path the check resolved, always — including when it found nothing there. */
45
+ briefPath: string;
46
+ /** AC ids the brief does not name. Empty under every reading but `IDS_MISSING`. */
47
+ missingIds: string[];
48
+ /** Why this is a refusal, naming the path. `null` when it is not one. */
49
+ refusal: string | null;
50
+ /** Why the check declined to look. `null` unless the reading is `NOT_APPLICABLE`. */
51
+ declined: string | null;
52
+ }
53
+
54
+ export interface BriefAlignmentInput {
55
+ /** The resolved path, composed by the caller so this function reads no env. */
56
+ briefPath: string;
57
+ briefExists: boolean;
58
+ /** The brief's text. Ignored when `briefExists` is false. */
59
+ briefText: string;
60
+ acIds: string[];
61
+ marcusSpawned: boolean;
62
+ }
63
+
64
+ export function briefAcAlignment(input: BriefAlignmentInput): BriefAlignment {
65
+ const { briefPath, briefExists, briefText, acIds, marcusSpawned } = input;
66
+ const base = { briefPath, missingIds: [] as string[], refusal: null, declined: null };
67
+
68
+ if (!briefExists) {
69
+ // An absent brief is only a refusal when something was supposed to write
70
+ // one. With Marcus never spawned there is no brief to be missing, and
71
+ // calling that a pass would be the same substitution one level down.
72
+ if (!marcusSpawned) {
73
+ return {
74
+ ...base,
75
+ reading: "NOT_APPLICABLE",
76
+ declined:
77
+ `brief-ac-alignment: no brief at ${briefPath}, and Marcus was not spawned — ` +
78
+ "nothing was expected to write one, so this is UNMEASURED rather than a pass",
79
+ };
80
+ }
81
+ return {
82
+ ...base,
83
+ reading: "BRIEF_ABSENT",
84
+ refusal:
85
+ `brief-ac-alignment: Marcus was spawned but no brief exists at ${briefPath} ` +
86
+ "(ADR-009 C2). The path is resolved from RUNGATE_WORK_DIR, or $HOME/.rungate " +
87
+ "when that is unset, plus the state's slug — so a wrong directory and a " +
88
+ "missing file look the same from here. Check the path before the file.",
89
+ };
90
+ }
91
+
92
+ const missingIds = acIds.filter(id => !briefText.includes(id));
93
+ if (missingIds.length === 0) return { ...base, reading: "ALIGNED" };
94
+
95
+ return {
96
+ ...base,
97
+ reading: "IDS_MISSING",
98
+ missingIds,
99
+ refusal:
100
+ `brief-ac-alignment: the brief at ${briefPath} does not name ` +
101
+ `${missingIds.join(", ")} (ADR-009 C2). It exists and was read, so this is ` +
102
+ "the brief's content and not the resolved path.",
103
+ };
104
+ }
@@ -0,0 +1,205 @@
1
+ /**
2
+ * Whether a `node_modules/...` path named in an agent brief could be checked
3
+ * at all (#884).
4
+ *
5
+ * AGENT-6 resolves every `node_modules/...` path the briefs reference. A ship
6
+ * worktree is created without an install, so in one the paths cannot be
7
+ * resolved — and the check reported them as BROKEN. Both of the files it named
8
+ * exist in the main checkout; the briefs were correct and the corpus was
9
+ * missing. `record-local-env` runs the suite in that worktree, so the FAIL was
10
+ * recorded as the project's test health and failed `tests-pass` on every run.
11
+ *
12
+ * A conformity check whose corpus is absent did not run. Three outcomes, not
13
+ * two:
14
+ *
15
+ * | the package is | the path is | status |
16
+ * |---|---|---|
17
+ * | installed | present | `resolved` |
18
+ * | installed | absent | `broken` — AGENT-6 fails, as before |
19
+ * | not installed | unknowable | `unresolvable` — UNMEASURED, by name |
20
+ *
21
+ * The third is NOT a pass. `0`, `{}`, `SKIP` and silence are indistinguishable
22
+ * from success, so an unresolvable reference is recorded as a WARN finding
23
+ * naming the package that is missing, per `.claude/rules/config-access.md`.
24
+ *
25
+ * ## One binding
26
+ *
27
+ * `briefReferenceReading` is the only thing that decides any of this, and
28
+ * `reading` / `absentCorpora` are projections of the lists it builds rather
29
+ * than second answers computed beside them — two deciders that agree are
30
+ * behaviourally one, and no behavioural test can tell them apart.
31
+ *
32
+ * It lives here rather than in `lib/conformity.ts` because conformity imports
33
+ * `bun:test` at module scope and so cannot be imported by a CLI. Same
34
+ * arrangement as `lib/fallow-availability.ts` (#581) and `lib/git-dates.ts`
35
+ * (#508).
36
+ */
37
+
38
+ import { existsSync, readFileSync, readdirSync } from "fs";
39
+ import { join } from "path";
40
+
41
+ /**
42
+ * The packages the project says it depends on, or `null` when it does not say.
43
+ *
44
+ * This is the evidence that stops the UNMEASURED reading swallowing a real
45
+ * finding. In a tree that HAS an install, a reference into a package the
46
+ * manifest never declared cannot be "not installed yet" — it is a wrong
47
+ * reference, and before #884 it was reported as one. `null` is a third answer
48
+ * and not an empty set: a project with no readable manifest has told us
49
+ * nothing, and nothing is not "depends on nothing".
50
+ */
51
+ export function declaredPackages(root: string): Set<string> | null {
52
+ let pkg: any;
53
+ try {
54
+ pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
55
+ } catch {
56
+ return null;
57
+ }
58
+ if (pkg === null || typeof pkg !== "object") return null;
59
+ return new Set([
60
+ ...Object.keys(pkg.dependencies ?? {}),
61
+ ...Object.keys(pkg.devDependencies ?? {}),
62
+ ...Object.keys(pkg.optionalDependencies ?? {}),
63
+ ...Object.keys(pkg.peerDependencies ?? {}),
64
+ ]);
65
+ }
66
+
67
+ /** The pattern AGENT-6 has always used to find references. Unchanged. */
68
+ export const BRIEF_REFERENCE_PATTERN = /node_modules\/[^\s`*)"']+/g;
69
+
70
+ /** Markdown punctuation a reference picks up from the prose around it. */
71
+ export function cleanBriefReference(raw: string): string {
72
+ return raw.replace(/[`*)"']+$/, "");
73
+ }
74
+
75
+ export type BriefReferenceStatus = "resolved" | "broken" | "unresolvable";
76
+
77
+ export interface BriefReference {
78
+ /** The brief's file name, e.g. `quinn.md`. */
79
+ brief: string;
80
+ /** The cleaned reference, repo-relative. */
81
+ ref: string;
82
+ /** The installed tree this reference lives inside, repo-relative. */
83
+ packageRoot: string;
84
+ status: BriefReferenceStatus;
85
+ }
86
+
87
+ export interface BriefReferenceReading {
88
+ /** `UNMEASURED` as soon as one reference could not be looked at. */
89
+ reading: "MEASURED" | "UNMEASURED";
90
+ references: BriefReference[];
91
+ broken: BriefReference[];
92
+ unresolvable: BriefReference[];
93
+ /** The corpora the scan could not see, deduped and sorted. */
94
+ absentCorpora: string[];
95
+ }
96
+
97
+ /**
98
+ * The installed tree a reference lives inside — the thing whose absence makes
99
+ * the reference unknowable rather than wrong.
100
+ *
101
+ * For a scoped package that is `node_modules/@scope/name` and not
102
+ * `node_modules/@scope`: a scope directory holding some other package of the
103
+ * same scope is present while the package itself is not, and a corpus computed
104
+ * one segment short reads that tree as an install.
105
+ */
106
+ export function corpusOf(ref: string): string {
107
+ const parts = ref.split("/");
108
+ if (parts.length >= 3 && parts[1]!.startsWith("@")) return parts.slice(0, 3).join("/");
109
+ if (parts.length >= 2) return parts.slice(0, 2).join("/");
110
+ return "node_modules";
111
+ }
112
+
113
+ /**
114
+ * Three outcomes, and the order of the three questions is the whole design.
115
+ *
116
+ * 1. **A traversal segment is broken, and is never probed.** `node_modules/../..`
117
+ * matches the reference pattern, and probing it turns a conformity check
118
+ * into a filesystem-existence oracle for paths outside the repository. A
119
+ * brief naming one is a wrong reference whatever is on disk, so the answer
120
+ * does not need the disk.
121
+ * 2. **No install at all means no reading, unconditionally.** This is #884's
122
+ * case: a ship worktree. Nothing about the project's manifest can make a
123
+ * reference checkable when there is nothing to check it against.
124
+ * 3. **With an install present, the manifest decides.** A declared dependency
125
+ * that is not there is a broken or partial install — unknowable. A package
126
+ * the project never declared is a wrong reference, and it was reported as
127
+ * one before #884. Asking the manifest here is what stops the new
128
+ * UNMEASURED reading swallowing that finding: without it, a typo in a
129
+ * package name goes silent in a fully installed tree.
130
+ *
131
+ * A project with no readable manifest has said nothing, so step 3 cannot run
132
+ * and the answer is `unresolvable`. That is UNMEASURED by name, not a pass.
133
+ */
134
+ export function classifyBriefReference(
135
+ root: string,
136
+ ref: string,
137
+ declared: Set<string> | null = declaredPackages(root),
138
+ ): BriefReferenceStatus {
139
+ if (ref.split("/").includes("..")) return "broken";
140
+ if (!existsSync(join(root, "node_modules"))) return "unresolvable";
141
+ const corpus = corpusOf(ref);
142
+ if (!existsSync(join(root, corpus))) {
143
+ return declared !== null && !declared.has(corpus.replace(/^node_modules\//, ""))
144
+ ? "broken"
145
+ : "unresolvable";
146
+ }
147
+ return existsSync(join(root, ref)) ? "resolved" : "broken";
148
+ }
149
+
150
+ export function briefReferenceReading(root: string, agentsDir: string): BriefReferenceReading {
151
+ const references: BriefReference[] = [];
152
+ // Read once per reading, not once per reference: the manifest cannot change
153
+ // mid-scan, and a second read is a second chance to disagree with the first.
154
+ const declared = declaredPackages(root);
155
+ if (existsSync(agentsDir)) {
156
+ for (const brief of readdirSync(agentsDir).filter(f => f.endsWith(".md"))) {
157
+ const content = readFileSync(join(agentsDir, brief), "utf-8");
158
+ for (const raw of content.match(BRIEF_REFERENCE_PATTERN) ?? []) {
159
+ const ref = cleanBriefReference(raw);
160
+ references.push({
161
+ brief,
162
+ ref,
163
+ packageRoot: corpusOf(ref),
164
+ status: classifyBriefReference(root, ref, declared),
165
+ });
166
+ }
167
+ }
168
+ }
169
+ const broken = references.filter(r => r.status === "broken");
170
+ const unresolvable = references.filter(r => r.status === "unresolvable");
171
+ return {
172
+ reading: unresolvable.length > 0 ? "UNMEASURED" : "MEASURED",
173
+ references,
174
+ broken,
175
+ unresolvable,
176
+ absentCorpora: [...new Set(unresolvable.map(r => r.packageRoot))].sort(),
177
+ };
178
+ }
179
+
180
+ /** What a single unresolvable reference records, as the finding says it. */
181
+ export function unresolvableBriefReferenceMessage(r: BriefReference): string {
182
+ return (
183
+ `UNMEASURED — the brief references "${r.ref}", but "${r.packageRoot}" is not ` +
184
+ `installed in this checkout, so the reference was never checked. ` +
185
+ `This is not a passing reference and it is not a broken one.`
186
+ );
187
+ }
188
+
189
+ /**
190
+ * The line the suite prints in place of a reading it could not take, or `null`
191
+ * when there was nothing it could not take.
192
+ *
193
+ * `null` rather than an empty string: a notice composed unconditionally names
194
+ * UNMEASURED on a clean tree too, and then the word stops meaning anything.
195
+ */
196
+ export function unmeasuredBriefReferenceNotice(r: BriefReferenceReading): string | null {
197
+ if (r.reading !== "UNMEASURED") return null;
198
+ const lines = r.unresolvable.map(u => ` ${u.brief} → ${u.ref}`);
199
+ return (
200
+ `UNMEASURED — ${r.unresolvable.length} brief reference(s) could not be checked ` +
201
+ `because ${r.absentCorpora.join(", ")} ${r.absentCorpora.length === 1 ? "is" : "are"} ` +
202
+ `not installed here. Run the install in this checkout and re-run; a worktree ` +
203
+ `created without dependencies cannot see the package corpus.\n${lines.join("\n")}`
204
+ );
205
+ }
@@ -231,6 +231,47 @@ export function bunVersionReading(decision: BunVersionDecision, running: string)
231
231
  };
232
232
  }
233
233
 
234
+ /**
235
+ * What a `setup-bun` step's `with:` block NAMES, one entry per step.
236
+ *
237
+ * The reading half of `setupBunWith` below, and here rather than in
238
+ * `scripts/contract-parity.ts` (#637, AC-9) for one reason: the generator and
239
+ * the reader of the thing it generates are a producer and a consumer that must
240
+ * agree, and keeping them in one module is what makes a round-trip case —
241
+ * emit a step, read it back, compare — an ordinary import rather than a second
242
+ * copy of this regex somewhere a script can reach.
243
+ *
244
+ * Deliberately text, not YAML: `#622c`'s position is the step the SCAFFOLD
245
+ * would emit, which is a string that has never been a file.
246
+ */
247
+ export function setupBunDeclarations(text: string): Array<{ key: "bun-version" | "bun-version-file"; value: string }> {
248
+ const out: Array<{ key: "bun-version" | "bun-version-file"; value: string }> = [];
249
+ for (const m of text.matchAll(/^\s*(bun-version|bun-version-file):\s*"?([^"\s#]+)"?\s*$/gm)) {
250
+ out.push({ key: m[1] as "bun-version" | "bun-version-file", value: m[2] });
251
+ }
252
+ return out;
253
+ }
254
+
255
+ /**
256
+ * The `# UNPINNED:` block, spelled in exactly one place (#932).
257
+ *
258
+ * Three rungs can now reach it — a moving tag in `.bun-version`, a moving tag
259
+ * in `ci.bunVersion`, and no declaration at all — and a second copy of the
260
+ * marker would survive a mutation of the first, leaving a case green over a
261
+ * rung that had gone quiet (`.claude/rules/checks-must-be-able-to-fail.md`).
262
+ */
263
+ function unpinnedComment(indent: string, why: string, remedy: string): string {
264
+ return (
265
+ `${indent}# UNPINNED: ${why}, so every run of this job installs whatever\n` +
266
+ `${indent}# shipped today and re-running a red job is also a Bun upgrade. ${remedy}\n`
267
+ );
268
+ }
269
+
270
+ /** How to stop being unpinned, from a rung that already declares something. */
271
+ function repinRemedy(source: Exclude<BunVersionSource, "undeclared">): string {
272
+ return `Name an exact version in ${bunVersionSourceLabel(source)} and re-scaffold.`;
273
+ }
274
+
234
275
  /**
235
276
  * The `with:` body of a generated `oven-sh/setup-bun` step.
236
277
  *
@@ -238,31 +279,69 @@ export function bunVersionReading(decision: BunVersionDecision, running: string)
238
279
  * for a fallback to grow. It returns LINES rather than writing anything,
239
280
  * which is what lets a test assert the emission for a declaration no machine
240
281
  * has — including one CI cannot resolve.
282
+ *
283
+ * ## Why the pin test is asked here and not only by the checker (#932)
284
+ *
285
+ * `isPinnedBunVersion` had exactly one consumer — `scripts/contract-parity.ts`
286
+ * — and the generator was not it. So a consumer declaring
287
+ * `ci.bunVersion: "latest"` had `bun-version: "latest"` written into a managed
288
+ * workflow under prose describing a successful declaration, and the only way
289
+ * to learn otherwise was to run the checker, which then called that same line
290
+ * a violation. One predicate, two positions, opposite behaviour.
291
+ *
292
+ * Worse, it inverted the rungs: a project declaring NOTHING got the loud block
293
+ * below, and a project declaring a moving tag got silence. Declaring `latest`
294
+ * was reported strictly better than declaring nothing, while installing the
295
+ * same runtime.
296
+ *
297
+ * The VALUE is still emitted verbatim at every rung. `MOVING_BUN_TAGS` says
298
+ * declaring one "is a legitimate thing for a consumer to choose", and
299
+ * substituting a pin here would change a consumer's runtime without being
300
+ * asked — which is AC-7's forbidden silent fallback wearing a fix. What
301
+ * changes is only that the file says what it is.
241
302
  */
242
303
  export function setupBunWith(decision: BunVersionDecision, indent: string): string {
304
+ const pinned = isPinnedBunVersion(decision.version);
305
+
243
306
  if (decision.source === "bun-version-file") {
244
- return (
245
- `${indent}# Pinned by ${BUN_VERSION_FILE} — the project's single declaration (#622).\n` +
246
- `${indent}# setup-bun reads that file, so there is no version spelled here to drift from it.\n` +
247
- `${indent}bun-version-file: "${BUN_VERSION_FILE}"`
248
- );
307
+ // The file still wins and CI still reads it: what is wrong about a
308
+ // `.bun-version` holding `canary` is the prose, not the mechanism, and
309
+ // spelling a literal here instead would put a second position naming the
310
+ // version back into the workflow — #622's defect, repaired into existence.
311
+ const comment = pinned
312
+ ? `${indent}# Pinned by ${BUN_VERSION_FILE} — the project's single declaration (#622).\n` +
313
+ `${indent}# setup-bun reads that file, so there is no version spelled here to drift from it.\n`
314
+ : unpinnedComment(
315
+ indent,
316
+ `${BUN_VERSION_FILE} declares the moving tag \`${decision.version}\``,
317
+ repinRemedy("bun-version-file"),
318
+ );
319
+ return comment + `${indent}bun-version-file: "${BUN_VERSION_FILE}"`;
249
320
  }
321
+
250
322
  if (decision.source === "config") {
251
- return (
252
- `${indent}# From ci.bunVersion in .claude/rungate/config.json — this project declares no\n` +
253
- `${indent}# ${BUN_VERSION_FILE}. Add one and re-scaffold to let CI read the declaration directly.\n` +
254
- `${indent}bun-version: "${decision.version}"`
255
- );
323
+ const comment = pinned
324
+ ? `${indent}# From ci.bunVersion in .claude/rungate/config.json — this project declares no\n` +
325
+ `${indent}# ${BUN_VERSION_FILE}. Add one and re-scaffold to let CI read the declaration directly.\n`
326
+ : unpinnedComment(
327
+ indent,
328
+ `ci.bunVersion in .claude/rungate/config.json declares the moving tag ` +
329
+ `\`${decision.version}\``,
330
+ repinRemedy("config"),
331
+ );
332
+ return comment + `${indent}bun-version: "${decision.version}"`;
256
333
  }
334
+
257
335
  // UNPINNED, said out loud. The value is unchanged from what this generator
258
336
  // has always emitted for a project that declares nothing — changing a
259
337
  // consumer's runtime without being asked is not this issue's business — but
260
338
  // the silence is. An unpinned CI is a state, and a state that is not
261
339
  // reportable is one nobody fixes.
262
340
  return (
263
- `${indent}# UNPINNED: ${decision.reason}, so every run of this job installs whatever\n` +
264
- `${indent}# shipped today and re-running a red job is also a Bun upgrade. Declare a version in\n` +
265
- `${indent}# ${BUN_VERSION_FILE} (or ci.bunVersion) and re-scaffold.\n` +
266
- `${indent}bun-version: "latest"`
341
+ unpinnedComment(
342
+ indent,
343
+ decision.reason,
344
+ `Declare a version in ${BUN_VERSION_FILE} (or ci.bunVersion) and re-scaffold.`,
345
+ ) + `${indent}bun-version: "latest"`
267
346
  );
268
347
  }
@@ -0,0 +1,140 @@
1
+ /**
2
+ * The remedy line a conformity failure carries, and the routing to the rule
3
+ * file that explains the whole family (#813).
4
+ *
5
+ * ## Why this exists
6
+ *
7
+ * The checks in `.claude/rules/self-referential-tests.md`'s Tier 1 assert a
8
+ * property about the REPOSITORY, not about a unit of code. They go red on a
9
+ * pull request that never opened the file they are about: add a spec, and
10
+ * `HYGIENE-4` fails; add a script, and `HYGIENE-3` fails. The agent who needs
11
+ * that document is by definition staring at a test failure, and measured on
12
+ * `e0429b82` not one of those failures named it — two references in the whole
13
+ * executable tree, both prose inside a docblock, against 321 for
14
+ * `checks-must-be-able-to-fail`.
15
+ *
16
+ * So the document was unreachable from the only place it was ever needed.
17
+ *
18
+ * ## The two layers, and why they are not one
19
+ *
20
+ * `lib/conformity.ts` is published, and `lib/scaffold/steps.ts` generates the
21
+ * consumer test that calls it. The rule file has exactly one copy in this tree
22
+ * and no template copy, so it does NOT ship. Hardcoding its path into the
23
+ * published failure text would point every consumer at a file they do not
24
+ * have — a dangling route, which is the defect `test/rule-provenance.test.ts`
25
+ * exists to catch and cannot catch across the package boundary.
26
+ *
27
+ * Hence `fix` and `pointer` are separate:
28
+ *
29
+ * - The **fix** is a claim about the project's own tree and is true anywhere.
30
+ * "Add a row to `.claude/rules/specs-routing.md`" is the real remedy in a
31
+ * consumer exactly as it is here.
32
+ * - The **pointer** is DERIVED, not configured: it is emitted only when the
33
+ * rule file is present under `root`. No new config key, nothing for a
34
+ * consumer to set, absent where it would be wrong, and it begins working
35
+ * for a consumer on the day they adopt the file.
36
+ *
37
+ * A config key was the other option and is worse: it is a second decider about
38
+ * whether the document exists, and the two could disagree — the key set in a
39
+ * project that deleted the file routes an agent to nothing.
40
+ */
41
+
42
+ import { existsSync } from "fs";
43
+ import { join } from "path";
44
+
45
+ import { stripJsComments } from "./strip-js-comments";
46
+
47
+ /**
48
+ * The document, relative to a project root.
49
+ *
50
+ * Spelled once. A second copy is the thing
51
+ * `.claude/rules/checks-must-be-able-to-fail.md` calls two deciders that
52
+ * agree: the existence probe and the printed path would be free to drift, and
53
+ * the failure mode is silent — a pointer that prints a path nobody checked.
54
+ */
55
+ export const SELF_REFERENTIAL_RULES = ".claude/rules/self-referential-tests.md";
56
+
57
+ /**
58
+ * The routing sentence, or `""` when this project does not carry the document.
59
+ *
60
+ * Returns the empty string rather than throwing or omitting a field, because
61
+ * every caller is composing a message and an empty segment drops out of a
62
+ * `filter(Boolean).join()` without a branch at each site.
63
+ */
64
+ export function ruleDocPointer(root: string): string {
65
+ if (!existsSync(join(root, SELF_REFERENTIAL_RULES))) return "";
66
+ return (
67
+ `This check asserts a property of the REPOSITORY, so it can go red on a change ` +
68
+ `that never touched its subject. ${SELF_REFERENTIAL_RULES} lists the others ` +
69
+ `that behave this way and what each one wants.`
70
+ );
71
+ }
72
+
73
+ /**
74
+ * A conformity failure message: what is wrong, what to do, and where the rest
75
+ * of the family is documented.
76
+ *
77
+ * The `fix` is mandatory and takes no default. A default would let a new check
78
+ * be written with no remedy and still look like it had one, which is the
79
+ * failure this module was built to end — `test/check-remedy.test.ts` holds the
80
+ * population of Tier 1 checks for the same reason.
81
+ */
82
+ export function remedyMessage(opts: {
83
+ root: string;
84
+ check: string;
85
+ violations: string[];
86
+ fix: string;
87
+ }): string {
88
+ const { root, check, violations, fix } = opts;
89
+ const subject = violations.length === 0 ? "(none)" : violations.join(", ");
90
+ return [
91
+ `${check}: ${violations.length} violation(s) — ${subject}`,
92
+ `FIX: ${fix}`,
93
+ ruleDocPointer(root),
94
+ ]
95
+ .filter(Boolean)
96
+ .join("\n");
97
+ }
98
+
99
+ /**
100
+ * How far before a call site an `expect(` may open and still be counted as
101
+ * the assertion it belongs to.
102
+ *
103
+ * Generous on purpose. The cost of being too wide is a call site credited to
104
+ * a nearby assertion it does not serve; the cost of being too narrow is a
105
+ * correctly-wired check reported as missing, which trains the next agent to
106
+ * widen the number rather than read it.
107
+ */
108
+ const EXPECT_WINDOW = 200;
109
+
110
+ /** How far into a call site to look for its `check:` field. */
111
+ const FIELD_WINDOW = 600;
112
+
113
+ /**
114
+ * The `check:` value of every ASSERTED `remedyMessage(...)` call in a source.
115
+ *
116
+ * Pure, and over text rather than a path, because the two properties below
117
+ * are the whole point and neither can be witnessed against the live tree —
118
+ * the live tree has no violating file to find, so a scan that silently lost
119
+ * both would return the right answer today and nothing the day it mattered.
120
+ * `test/check-remedy.test.ts` plants a source for each.
121
+ *
122
+ * - **Comments are not code.** The scan looks for a symbol that this very
123
+ * docblock names. Counting prose would let a file satisfy the guard by
124
+ * describing the call it does not make — a checker that greps for a string
125
+ * cannot tell a use from a mention of one.
126
+ * - **A composed message is not an asserted one.** Building the string and
127
+ * never passing it to `expect` leaves the check failing with nothing while
128
+ * the guard reads green, which is the cheapest wrong way to go green here.
129
+ */
130
+ export function routedCheckIds(source: string): string[] {
131
+ const src = stripJsComments(source);
132
+ const found: string[] = [];
133
+ const CALL = "remedyMessage(";
134
+ for (let i = src.indexOf(CALL); i !== -1; i = src.indexOf(CALL, i + 1)) {
135
+ if (!src.slice(Math.max(0, i - EXPECT_WINDOW), i).includes("expect(")) continue;
136
+ const field = /check:\s*"([^"]+)"/.exec(src.slice(i, i + FIELD_WINDOW));
137
+ if (field) found.push(field[1]!);
138
+ }
139
+ return found;
140
+ }
@@ -424,3 +424,20 @@ export function prepareCiCheckout(opts: PrepareOptions): PrepareOutcome {
424
424
 
425
425
  return { ok: true, dir: dest, model, refs: result.refs, carried };
426
426
  }
427
+
428
+ /**
429
+ * The job in a generated ci.yml that actually checks out and runs the suite
430
+ * (#735).
431
+ *
432
+ * `test` normally. When `ci.shards > 1` the suite moves to the `test-shard`
433
+ * matrix and `test` becomes the aggregate that reads the matrix result and
434
+ * runs no tests — so a reader that only knows `test` reports "no
435
+ * actions/checkout step" for a workflow that checks out four times.
436
+ *
437
+ * One exported binding, because the same question is asked by
438
+ * `scripts/contract-parity.ts`. Two readers that agree today are one decider
439
+ * too many (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
440
+ */
441
+ export function suiteJobName(workflowYaml: string): string {
442
+ return /^ {2}test-shard:\s*$/m.test(workflowYaml) ? "test-shard" : "test";
443
+ }