rungate 0.4.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/config/behavioral-sc-map.json +170 -0
  2. package/config/brief-policies.json +28 -0
  3. package/config/ceremony-profiles.json +207 -0
  4. package/config/check-registry.json +114 -0
  5. package/config/matcher-registry.json +142 -0
  6. package/config/prove-evidence.schema.json +65 -0
  7. package/config/spec-policies.json +36 -0
  8. package/config/universal-rules.yaml +15 -0
  9. package/config/workflow-schema.json +279 -0
  10. package/lib/agents-md-sections.ts +144 -0
  11. package/lib/branch-diff.ts +139 -0
  12. package/lib/bun-version.ts +268 -0
  13. package/lib/ci-checkout.ts +1 -1
  14. package/lib/cli-commands.ts +7 -1
  15. package/lib/compliance.ts +13 -11
  16. package/lib/config-loader.ts +12 -0
  17. package/lib/conformity.ts +1147 -116
  18. package/lib/context-docs.ts +143 -28
  19. package/lib/create-brief.ts +2 -1
  20. package/lib/create-sc.ts +90 -4
  21. package/lib/doc-scan-targets.ts +9 -0
  22. package/lib/evidence-command-transport.ts +160 -0
  23. package/lib/evidence-prevalidator.ts +22 -0
  24. package/lib/fallow-availability.ts +129 -0
  25. package/lib/gate-refusal-currency.ts +112 -0
  26. package/lib/gate-timeouts.ts +82 -0
  27. package/lib/generators/agent-briefs.ts +4 -1
  28. package/lib/generators/agents-md.ts +71 -23
  29. package/lib/generators/code-map.ts +2 -1
  30. package/lib/generators/types.ts +8 -0
  31. package/lib/git-dates.ts +55 -0
  32. package/lib/github.ts +195 -0
  33. package/lib/js-top-level-code.ts +27 -2
  34. package/lib/junit-checks.ts +484 -0
  35. package/lib/local-calendar-day.ts +78 -0
  36. package/lib/package-closure.ts +278 -2
  37. package/lib/project-state-shape.ts +59 -0
  38. package/lib/promote-outputs.ts +6 -2
  39. package/lib/release-preflight.ts +196 -0
  40. package/lib/report-provenance.ts +156 -0
  41. package/lib/sc-claim-forms.ts +75 -0
  42. package/lib/sc-id-cross-tree.ts +311 -0
  43. package/lib/scaffold/ai-review-step.ts +180 -0
  44. package/lib/scaffold/defaults.ts +40 -0
  45. package/lib/scaffold/managed-workflow.ts +125 -27
  46. package/lib/scaffold/owned-files.ts +48 -2
  47. package/lib/scaffold/profiles.ts +94 -0
  48. package/lib/scaffold/rehearsal.ts +232 -73
  49. package/lib/scaffold/steps.ts +777 -152
  50. package/lib/scaffold/write-steps.ts +56 -13
  51. package/lib/scanner.ts +38 -12
  52. package/lib/source-anchor.ts +144 -0
  53. package/lib/spec-listing.ts +148 -0
  54. package/lib/spec-requirements.ts +209 -0
  55. package/lib/success-doc.ts +779 -0
  56. package/lib/suite-run-reading.ts +364 -0
  57. package/lib/test-census.ts +199 -0
  58. package/lib/test-command.ts +133 -0
  59. package/lib/test-suite-lock.ts +166 -10
  60. package/lib/tool-probe.ts +120 -0
  61. package/lib/tracked-vs-ignored.ts +234 -0
  62. package/lib/trajectory.ts +377 -0
  63. package/lib/validators/spec-validators.ts +35 -6
  64. package/lib/workflow-security.ts +101 -0
  65. package/lib/workflow-test-harness.ts +349 -0
  66. package/package.json +6 -1
  67. package/scripts/audit-specs.ts +247 -12
  68. package/scripts/audit-transcript.ts +2 -1
  69. package/scripts/convert-spec.ts +2 -1
  70. package/scripts/create-sc.ts +17 -7
  71. package/scripts/create-spec.ts +2 -1
  72. package/scripts/create-success.ts +163 -0
  73. package/scripts/extract-constraints.ts +90 -19
  74. package/scripts/generate-code-map.ts +53 -12
  75. package/scripts/scaffold-project.ts +31 -4
  76. package/scripts/split-spec.ts +2 -1
  77. package/scripts/sync-sc-status.ts +57 -5
  78. package/scripts/sync-spec-tests.ts +2 -1
  79. package/specs/SPEC-TEMPLATE.md +200 -0
  80. package/templates/SUCCESS-TEMPLATE.md +72 -0
  81. package/templates/agent-briefs/_shared.md +9 -0
  82. package/templates/agent-briefs/aditi.md +46 -0
  83. package/templates/agent-briefs/discovery.md +37 -0
  84. package/templates/agent-briefs/marcus.md +39 -0
  85. package/templates/agent-briefs/quinn.md +67 -0
  86. package/templates/agent-briefs/rook.md +40 -0
  87. package/templates/agent-briefs/serena.md +39 -0
@@ -0,0 +1,139 @@
1
+ /**
2
+ * What THIS branch changed since the scope gate ran (#531).
3
+ *
4
+ * Three gate checks — `prove-evidence-type`, `contextual-skip-validation`
5
+ * and the ship-round repeat — decide what a run must prove from a list of
6
+ * changed files. All three built that list with
7
+ *
8
+ * git diff --name-only ${scopeSha}..HEAD
9
+ *
10
+ * Two dots compares two commits DIRECTLY. When `scopeSha` is not an ancestor
11
+ * of `HEAD`, the output also carries everything on the other side of the
12
+ * fork, and the gate attributes all of it to this branch.
13
+ *
14
+ * Measured on run `wf_e230fddc-a71`, whose `gates.scope.commitSha` was
15
+ * `247afba4`:
16
+ *
17
+ * ```
18
+ * git merge-base --is-ancestor 247afba4 HEAD -> false
19
+ * git diff --name-only 247afba4..HEAD | wc -l -> 78
20
+ * git diff --name-only 247afba4...HEAD | wc -l -> 3
21
+ * ```
22
+ *
23
+ * The branch touched three files. The gate saw seventy-eight and refused
24
+ * twice over files that do not exist on it — a `Dockerfile` it has never
25
+ * contained, and seven `.tsx` files it has never contained.
26
+ *
27
+ * Three dots diffs HEAD against the MERGE BASE, which is the question every
28
+ * one of these checks is actually asking: what did this branch do.
29
+ *
30
+ * ## Why the sha was wrong to begin with, and why three dots is not enough
31
+ *
32
+ * `247afba4` was the tip of the branch the MAIN CHECKOUT happened to be
33
+ * sitting on, while the run was shipping a worktree. `writeGateResult`
34
+ * recorded `gitSha(state.projectRoot)`. The state names `treeUnderTest`
35
+ * correctly, so the right value was available and the writer read HEAD from
36
+ * somewhere else — which is `.claude/rules/checks-must-be-able-to-fail.md`'s
37
+ * "a consumer reads a name, a producer writes a different name" in the
38
+ * smallest possible form. Both halves are fixed: the recorder reads the tree
39
+ * under test, and the readers compare branch-relative. Three dots alone
40
+ * still mis-attributes when the recorded sha came from the wrong tree, and
41
+ * the right sha alone still mis-attributes across a fork.
42
+ *
43
+ * ## An unusable diff is UNMEASURED, and says so
44
+ *
45
+ * The three call sites read `if (!diff.ok || !diff.output) return`, which
46
+ * collapses "git could not answer" into "nothing changed" — and the first of
47
+ * those is the state a check should be loudest about, because every file
48
+ * gate below it then passes for want of input. The reading keeps them apart:
49
+ * `files: null` is "could not measure", `files: []` is "measured, nothing
50
+ * changed" (`.claude/rules/config-access.md`, Silent Default Substitution).
51
+ *
52
+ * **The call sites still RETURN on `null`, and that is deliberate rather
53
+ * than an oversight.** An unreachable scope sha is an ORDINARY outcome, not
54
+ * an anomaly: a rebase during the run — which this project does on nearly
55
+ * every PR — leaves `gates.scope.commitSha` pointing at a commit no longer
56
+ * in the branch's history, and `A...HEAD` then fails. Refusing on it would
57
+ * red every rebased run, so the reading is printed as `WARN: … UNMEASURED`
58
+ * and the check declines to decide. The difference from before is that the
59
+ * decline is now visible in the gate log instead of being spelled
60
+ * `// no changed files`.
61
+ */
62
+
63
+ /** What one reading of the branch diff says. */
64
+ export interface BranchDiffReading {
65
+ /**
66
+ * The files this branch changed, or `null` when git could not answer.
67
+ * `[]` means it answered and the answer was none, which is a measurement.
68
+ */
69
+ files: string[] | null;
70
+ /** Why `files` is null. */
71
+ reason?: string;
72
+ }
73
+
74
+ /**
75
+ * An argv-form git runner, injected so the reading can be driven without git.
76
+ *
77
+ * Argv and not a command string: `scopeSha` comes out of
78
+ * `workflow-state.json`, which the run's own agents write, and the old call
79
+ * sites interpolated it straight into a shell. The sha is validated below as
80
+ * well — both, because the validation is the thing a later edit is most
81
+ * likely to widen.
82
+ */
83
+ export type DiffRunner = (args: string[]) => { ok: boolean; output: string };
84
+
85
+ /** A git object name and nothing else. */
86
+ const SHA = /^[0-9a-f]{7,64}$/;
87
+
88
+ /**
89
+ * The argv. One place, so the dot count has one binding to mutate.
90
+ *
91
+ * `-z` for the same reason `scripts/verify-merge-content.ts` uses it:
92
+ * `git diff --name-only` C-QUOTES any path holding a non-ASCII byte, a
93
+ * quote, a tab or a newline — `"caf\303\251.tsx"`, quotes included. Every
94
+ * consumer of this list is a regex on the filename, and
95
+ * `/\.(tsx|jsx|css)$/i` does not match a string ending in `"`. So a UI file
96
+ * with an accent in its name walks past `local-ui-validated` and
97
+ * `quinn-on-ui-change` without matching anything, which is #531's own defect
98
+ * — a changed-file list that is wrong about what changed — arriving through
99
+ * the encoding instead of through the dot count. `-z` emits raw bytes,
100
+ * NUL-separated, and nothing is ever re-parsed.
101
+ */
102
+ export function branchDiffArgs(scopeSha: string): string[] {
103
+ // THREE dots. See the docstring: two dots is the whole of #531.
104
+ return ["diff", "--name-only", "-z", `${scopeSha}...HEAD`];
105
+ }
106
+
107
+ /**
108
+ * The files this branch changed since `scopeSha`, branch-relative.
109
+ *
110
+ * `checkName` is carried so the UNMEASURED line names the check that could
111
+ * not measure rather than the helper that noticed.
112
+ */
113
+ export function readBranchDiff(
114
+ scopeSha: unknown,
115
+ run: DiffRunner,
116
+ checkName: string,
117
+ ): BranchDiffReading {
118
+ if (typeof scopeSha !== "string" || !SHA.test(scopeSha)) {
119
+ return {
120
+ files: null,
121
+ reason:
122
+ `${checkName}: gates.scope.commitSha is ${JSON.stringify(scopeSha)}, which is not a git ` +
123
+ `object name, so the changed-file list could not be built (#531).`,
124
+ };
125
+ }
126
+ const r = run(branchDiffArgs(scopeSha));
127
+ if (!r.ok) {
128
+ return {
129
+ files: null,
130
+ reason:
131
+ `${checkName}: \`git ${branchDiffArgs(scopeSha).join(" ")}\` failed, so the changed-file ` +
132
+ `list is UNMEASURED. This is not "nothing changed" — every file-matched gate below reads ` +
133
+ `this list, and an empty one waves all of them through (#531).`,
134
+ };
135
+ }
136
+ // NUL, not newline, and no `trim` on the paths themselves — a filename may
137
+ // legally contain a newline, and trimming one would rewrite it.
138
+ return { files: r.output.split("\0").filter(Boolean) };
139
+ }
@@ -0,0 +1,268 @@
1
+ /**
2
+ * The one Bun version for a project (#622).
3
+ *
4
+ * Nothing in this repository pinned the runtime. `.github/workflows/ci.yml`
5
+ * and `gates.yml` carried `bun-version: "latest"`, `release.yml` carried the
6
+ * literal `"1.3.14"`, the development machine ran 1.3.14 and CI's `latest`
7
+ * resolved to **1.4.3** — a full minor apart, with nothing comparing any of
8
+ * the four.
9
+ *
10
+ * `latest` is the opposite of a pin: the runtime executing a given commit can
11
+ * change between two runs of that same commit, with nothing in the diff to
12
+ * explain a new failure. Re-running a red job was also a Bun upgrade, and a
13
+ * green local run could not say which runtime produced it.
14
+ *
15
+ * ## Why this is a module and not a string in two template literals
16
+ *
17
+ * It was two, and they were fed by `harness?.ci?.bunVersion || "latest"` in
18
+ * `lib/scaffold/steps.ts` while two other workflow files — neither of them
19
+ * generated — named versions of their own. Four positions, three spellings,
20
+ * no decider. This is #87's fix for the type check and #488's for the test
21
+ * command, applied to the step directly beside them: one binding, so a
22
+ * mutation of it can show that the agreement is load-bearing rather than
23
+ * coincidental.
24
+ *
25
+ * ## The rungs, and what each one is not
26
+ *
27
+ * 1. **`.bun-version` at the project root.** The ecosystem's file:
28
+ * `oven-sh/setup-bun` reads it through `bun-version-file`, and so do
29
+ * `mise` and `asdf`. It wins because it is the file CI itself obeys —
30
+ * a resolver that preferred something else would be naming a version CI
31
+ * does not install.
32
+ * 2. **`ci.bunVersion` in the rungate config.** The field the harness has
33
+ * documented since SC-86, and the only declaration a consumer who has not
34
+ * adopted `.bun-version` has. Emitted as a literal, because there is no
35
+ * file for CI to point at.
36
+ * 3. **Nothing.** `null`, and the state is named `undeclared` rather than
37
+ * quietly becoming `latest`. `.claude/rules/config-access.md`: a built-in
38
+ * default substituted for an absent declaration must be loud, because `0`,
39
+ * `{}`, `null` and silence are all indistinguishable from success.
40
+ *
41
+ * ## What this does NOT cover
42
+ *
43
+ * - **Which bun is on the developer's PATH.** Two installations from two
44
+ * package managers sit on the issue's machine; this reports the mismatch,
45
+ * it cannot fix it. That is what `bunVersionReading` is for.
46
+ * - **Whether the declared version exists.** A pin CI cannot resolve fails
47
+ * the job, loudly, naming the value — which is the point. A
48
+ * well-formedness guard with `|| "latest"` behind it is the cheapest repair
49
+ * for that failure and is exactly the silent fallback AC-7 forbids, so
50
+ * `isPinnedBunVersion` refuses moving tags and nothing else.
51
+ * - **`package.json` `engines.bun` and `.tool-versions`.** Neither exists in
52
+ * this tree, and a rung nobody declares is a rung nothing can test. Add one
53
+ * here, with a case, if a consumer turns up on it — not before.
54
+ * - **`workflows/*.js`.** They cannot import (#69) and none of them installs
55
+ * bun; if one ever does, it reads the resolved config the way every other
56
+ * workflow prompt does.
57
+ */
58
+ import { existsSync, readFileSync } from "fs";
59
+ import { join } from "path";
60
+ import { tryLoadRungateConfig } from "./config-loader";
61
+
62
+ /** The declaration file, at the project root. The name `setup-bun` knows. */
63
+ export const BUN_VERSION_FILE = ".bun-version";
64
+
65
+ /**
66
+ * Tags that resolve to whatever shipped today. Declaring one is a declaration
67
+ * that the project is NOT pinned, which is a legitimate thing for a consumer
68
+ * to choose and is not a thing this repository may choose by accident.
69
+ */
70
+ export const MOVING_BUN_TAGS = ["latest", "canary"] as const;
71
+
72
+ export type BunVersionSource = "bun-version-file" | "config" | "undeclared";
73
+
74
+ export interface BunVersionDecision {
75
+ /** The declared version. Null only when nothing declares one. */
76
+ version: string | null;
77
+ source: BunVersionSource;
78
+ /** Why this version and not another. */
79
+ reason: string;
80
+ /**
81
+ * Both declarations present and disagreeing. Empty when they agree, or when
82
+ * only one of them exists. Reported rather than resolved in silence: two
83
+ * positions naming two versions is #621's defect, and the loser here is the
84
+ * one a human is most likely to have edited.
85
+ */
86
+ conflict: string;
87
+ }
88
+
89
+ /** Where a decision came from, spelled the way a log reader can act on. */
90
+ export function bunVersionSourceLabel(source: BunVersionSource): string {
91
+ if (source === "bun-version-file") return BUN_VERSION_FILE;
92
+ if (source === "config") return "ci.bunVersion in .claude/rungate/config.json";
93
+ return "no declaration";
94
+ }
95
+
96
+ /**
97
+ * Is this a pin — a value that names the same runtime tomorrow?
98
+ *
99
+ * Deliberately NOT a semver test. `1.0.x`, a commit sha and a download URL are
100
+ * all things `setup-bun` resolves, and narrowing this to `\d+\.\d+\.\d+` is
101
+ * the over-narrow detector that would reject a legitimate declaration and send
102
+ * someone looking for a fallback.
103
+ */
104
+ export function isPinnedBunVersion(version: string | null | undefined): boolean {
105
+ if (typeof version !== "string") return false;
106
+ const v = version.trim();
107
+ if (v === "") return false;
108
+ return !(MOVING_BUN_TAGS as readonly string[]).includes(v);
109
+ }
110
+
111
+ function fileDeclaration(root: string): string | null {
112
+ const path = join(root, BUN_VERSION_FILE);
113
+ if (!existsSync(path)) return null;
114
+ // A file that exists and says nothing is not a declaration. It is also not
115
+ // a reason to throw: `setup-bun` would fail on it anyway, and the rung below
116
+ // is a better answer than a dead scaffold.
117
+ const raw = readFileSync(path, "utf-8").trim();
118
+ return raw === "" ? null : raw;
119
+ }
120
+
121
+ function configDeclaration(root: string): string | null {
122
+ // Through the loader, never a constructed path to `.claude/rungate*`
123
+ // (`.claude/rules/config-access.md`), so both config layouts are honoured.
124
+ // It THROWS on a malformed config, deliberately: a corrupt config is never a
125
+ // missing config, and `catch {}` here is the conversion that rule forbids.
126
+ const config = tryLoadRungateConfig(root) as { ci?: { bunVersion?: unknown } } | null;
127
+ const declared = config?.ci?.bunVersion;
128
+ if (typeof declared !== "string" || declared.trim() === "") return null;
129
+ return declared.trim();
130
+ }
131
+
132
+ /** One position that declares a version, and what it says. */
133
+ export interface BunVersionDeclaration {
134
+ source: Exclude<BunVersionSource, "undeclared">;
135
+ version: string;
136
+ }
137
+
138
+ /**
139
+ * Every position in a project that declares a Bun version, in rung order.
140
+ *
141
+ * Separate from `declaredBunVersion` because the two questions are different:
142
+ * the decision is "what will CI install", and this is "who said so". A caller
143
+ * comparing positions — `scripts/contract-parity.ts` — needs the second, and
144
+ * reconstructing it from the decision's `conflict` string was the alternative:
145
+ * a consumer parsing a producer's prose, which is this repository's most
146
+ * expensive recurring mistake (#626).
147
+ */
148
+ export function bunVersionDeclarations(root: string): BunVersionDeclaration[] {
149
+ const out: BunVersionDeclaration[] = [];
150
+ const fromFile = fileDeclaration(root);
151
+ if (fromFile !== null) out.push({ source: "bun-version-file", version: fromFile });
152
+ const fromConfig = configDeclaration(root);
153
+ if (fromConfig !== null) out.push({ source: "config", version: fromConfig });
154
+ return out;
155
+ }
156
+
157
+ export function declaredBunVersion(root: string): BunVersionDecision {
158
+ const declarations = bunVersionDeclarations(root);
159
+ const fromFile = declarations.find(d => d.source === "bun-version-file")?.version ?? null;
160
+ const fromConfig = declarations.find(d => d.source === "config")?.version ?? null;
161
+ const conflict =
162
+ fromFile !== null && fromConfig !== null && fromFile !== fromConfig
163
+ ? `${BUN_VERSION_FILE} declares ${fromFile} and ci.bunVersion declares ${fromConfig}; ` +
164
+ `CI installs what ${BUN_VERSION_FILE} says, so the config field is the stale one`
165
+ : "";
166
+
167
+ if (fromFile !== null) {
168
+ return {
169
+ version: fromFile,
170
+ source: "bun-version-file",
171
+ reason: `the project declares ${BUN_VERSION_FILE}, which is the file setup-bun itself reads`,
172
+ conflict,
173
+ };
174
+ }
175
+ if (fromConfig !== null) {
176
+ return {
177
+ version: fromConfig,
178
+ source: "config",
179
+ reason: `the project declares ci.bunVersion and no ${BUN_VERSION_FILE}`,
180
+ conflict,
181
+ };
182
+ }
183
+ return {
184
+ version: null,
185
+ source: "undeclared",
186
+ reason: `the project declares neither ${BUN_VERSION_FILE} nor ci.bunVersion`,
187
+ conflict,
188
+ };
189
+ }
190
+
191
+ export type BunVersionState = "match" | "mismatch" | "undeclared";
192
+
193
+ export interface BunVersionReading {
194
+ state: BunVersionState;
195
+ /** One line, for a log somebody pastes into an issue. */
196
+ line: string;
197
+ }
198
+
199
+ /**
200
+ * What a run should say about the runtime it is running on.
201
+ *
202
+ * `running` is a parameter rather than `Bun.version` read inside, and that is
203
+ * the whole of AC-4: a comparison that reads the machine can only be driven
204
+ * with the machine's own answer, so the mismatch branch is unreachable from a
205
+ * test on any machine that is already correct — which is every machine where
206
+ * the case would be written.
207
+ */
208
+ export function bunVersionReading(decision: BunVersionDecision, running: string): BunVersionReading {
209
+ const suffix = decision.conflict ? ` WARNING: ${decision.conflict}.` : "";
210
+
211
+ if (decision.version === null) {
212
+ return {
213
+ state: "undeclared",
214
+ line:
215
+ `bun ${running} is running, and the declared version is UNMEASURED — ` +
216
+ `${decision.reason}, so this run says nothing about what CI will install.${suffix}`,
217
+ };
218
+ }
219
+ if (decision.version !== running) {
220
+ return {
221
+ state: "mismatch",
222
+ line:
223
+ `WARNING: bun ${running} is running but ${bunVersionSourceLabel(decision.source)} declares ` +
224
+ `${decision.version} — this run does NOT model CI, and a result pasted from it ` +
225
+ `describes ${running}.${suffix}`,
226
+ };
227
+ }
228
+ return {
229
+ state: "match",
230
+ line: `bun ${running} (declared in ${bunVersionSourceLabel(decision.source)}).${suffix}`,
231
+ };
232
+ }
233
+
234
+ /**
235
+ * The `with:` body of a generated `oven-sh/setup-bun` step.
236
+ *
237
+ * One function, so the generator has nothing to decide and no second place
238
+ * for a fallback to grow. It returns LINES rather than writing anything,
239
+ * which is what lets a test assert the emission for a declaration no machine
240
+ * has — including one CI cannot resolve.
241
+ */
242
+ export function setupBunWith(decision: BunVersionDecision, indent: string): string {
243
+ 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
+ );
249
+ }
250
+ 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
+ );
256
+ }
257
+ // UNPINNED, said out loud. The value is unchanged from what this generator
258
+ // has always emitted for a project that declares nothing — changing a
259
+ // consumer's runtime without being asked is not this issue's business — but
260
+ // the silence is. An unpinned CI is a state, and a state that is not
261
+ // reportable is one nobody fixes.
262
+ 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"`
267
+ );
268
+ }
@@ -62,7 +62,7 @@ export interface CheckoutModelResult {
62
62
  export const UNMODELLED: readonly string[] = [
63
63
  "the runner OS — CI is ubuntu-latest and this runs on the developer's machine, so anything platform-dependent (BSD vs GNU flags, path casing, file watchers) is still invisible here",
64
64
  "a fresh `bun install` — node_modules is linked from the working tree rather than installed, so a missing or mis-ranged dependency still passes locally",
65
- "the bun version — CI pins `bun-version: latest` at the moment the job runs; this uses whichever bun is on PATH",
65
+ "the bun version — CI installs what `.bun-version` declares (or `ci.bunVersion` when that file is absent; the file wins, and `declaredBunVersion` reports the disagreement when both exist) and this uses whichever bun is on PATH; since #622 the run REPORTS which one it is and whether it matches, but nothing here switches runtimes, so a mismatch is announced rather than removed",
66
66
  "the PR merge commit — `actions/checkout@v4` on a pull_request checks out a merge of the head into the base, while this checks out the head alone, so a conflict-free-but-broken merge is not modelled",
67
67
  "network and API availability — CI has neither the developer's `gh` credentials (stripped) nor their network conditions",
68
68
  "files git ignores — a `.env` or a stray build artefact present locally and absent in CI is carried over only if git can see it",
@@ -60,7 +60,7 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
60
60
  scaffold: {
61
61
  script: "scripts/scaffold-project.ts",
62
62
  summary: "Generate or refresh a project's agent files, rules and conformity suite",
63
- usage: "rungate scaffold <path> [--type code|workflow] [--fix] [--force] [--commit]",
63
+ usage: "rungate scaffold <path> [--type code|workflow] [--fix] [--force] [--commit] [--no-auto-fix] [--prune-consumers]",
64
64
  },
65
65
  "create-spec": {
66
66
  script: "scripts/create-spec.ts",
@@ -68,6 +68,12 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
68
68
  usage: 'rungate create-spec "Title" ["what it governs"] [--sc "statement"]',
69
69
  projectRootFlag: true,
70
70
  },
71
+ "create-success": {
72
+ script: "scripts/create-success.ts",
73
+ summary: "Seed SUCCESS.md — what this project is for, and the claims that prove it",
74
+ usage: "rungate create-success [--owner <name>] [--force]",
75
+ projectRootFlag: true,
76
+ },
71
77
  "create-sc": {
72
78
  script: "scripts/create-sc.ts",
73
79
  summary: "Generate a matchable success-criterion line from a registered pattern",
package/lib/compliance.ts CHANGED
@@ -10,6 +10,7 @@
10
10
  */
11
11
  import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from "fs";
12
12
  import { join, relative } from "path";
13
+ import { probeExternalTool } from "./tool-probe";
13
14
 
14
15
  // ── Types ──────────────────────────────────────────────────
15
16
 
@@ -191,15 +192,14 @@ export function collectComplianceSurface(root: string, surface?: string[]): stri
191
192
  }
192
193
 
193
194
  // ── Tool Availability ──────────────────────────────────────
194
-
195
- function checkToolAvailable(command: string, args: string[]): boolean {
196
- try {
197
- const result = Bun.spawnSync([command, ...args], { timeout: 5_000 });
198
- return result.exitCode === 0 || result.stdout.toString().length > 0;
199
- } catch {
200
- return false;
201
- }
202
- }
195
+ //
196
+ // The probe lives in `lib/tool-probe.ts` and has THREE outcomes (#626 AC-10).
197
+ // What was here returned `false` for "agnix is not installed", "npx ran and
198
+ // failed" and "the registry timed out" alike, which is why #597's CI failures
199
+ // could be re-run red to green on an identical SHA with nothing to read that
200
+ // said why. `available` below is the same boolean these two call sites always
201
+ // wanted — the difference is that it is now a projection of a reading that
202
+ // still knows which of the three happened.
203
203
 
204
204
  // ── Layer 1: Template Compliance ───────────────────────────
205
205
 
@@ -214,8 +214,10 @@ export async function runTemplateCompliance(
214
214
  ): Promise<ComplianceReport> {
215
215
  const files = collectComplianceSurface(root, opts?.surface);
216
216
 
217
- const agnixAvailable = checkToolAvailable("agnix", ["--version"]);
218
- const reporailsAvailable = checkToolAvailable("npx", ["@reporails/cli", "version"]);
217
+ const agnixProbe = probeExternalTool("agnix", ["--version"]);
218
+ const reporailsProbe = probeExternalTool("npx", ["@reporails/cli", "version"]);
219
+ const agnixAvailable = agnixProbe.available;
220
+ const reporailsAvailable = reporailsProbe.available;
219
221
 
220
222
  // agnix: batch mode works fine for file attribution
221
223
  const agnixByFile = new Map<string, AgnixDiagnostic[]>();
@@ -107,6 +107,18 @@ export type ResolvedConfig = z.infer<typeof ResolvedConfigSchema>;
107
107
  /** ship.js:1705's fallback, kept identical so normalisation changes no run. */
108
108
  export const DEFAULT_TEST_TIMEOUT = 120000;
109
109
 
110
+ /**
111
+ * The config's path relative to a project root, in the directory layout.
112
+ *
113
+ * Exported because a reader sometimes has to NAME the file without reading
114
+ * it — `scripts/contract-parity.ts` compares what each position in a tree
115
+ * DECLARES, so it labels and plants the config by path. Writing that literal
116
+ * anywhere else is a CONFIG-1 violation and rightly so, and the fix for a
117
+ * label is the same as the fix for a read: get it from here, so there is one
118
+ * module that knows where the config lives.
119
+ */
120
+ export const RUNGATE_CONFIG_RELATIVE_PATH = join(".claude", "rungate", "config.json");
121
+
110
122
  /**
111
123
  * The resolution (ADR-002 D2(a)). `absent` is TRUTHY and carries no `.test`,
112
124
  * so the four sites that wrote `config?.test?.command || fallback` cannot