rungate 0.4.0 → 0.5.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 (65) 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/ac-quality.ts +119 -0
  11. package/lib/cli-commands.ts +7 -1
  12. package/lib/config-loader.ts +129 -5
  13. package/lib/conformity.ts +1122 -31
  14. package/lib/context-docs.ts +182 -0
  15. package/lib/create-brief.ts +22 -17
  16. package/lib/create-sc.ts +35 -8
  17. package/lib/doc-scan-targets.ts +435 -0
  18. package/lib/gate-check-audit.ts +9 -9
  19. package/lib/github.ts +195 -0
  20. package/lib/js-top-level-code.ts +27 -2
  21. package/lib/organize.ts +129 -40
  22. package/lib/package-closure.ts +387 -0
  23. package/lib/project-aliases.ts +100 -0
  24. package/lib/release-preflight.ts +352 -48
  25. package/lib/rungate-schema.ts +23 -1
  26. package/lib/sc-cover.ts +92 -1
  27. package/lib/sc-ids.ts +151 -0
  28. package/lib/scaffold/defaults.ts +40 -0
  29. package/lib/scaffold/managed-workflow.ts +125 -27
  30. package/lib/scaffold/owned-files.ts +6 -0
  31. package/lib/scaffold/profiles.ts +94 -0
  32. package/lib/scaffold/rehearsal.ts +355 -0
  33. package/lib/scaffold/steps.ts +787 -105
  34. package/lib/scaffold/write-steps.ts +208 -0
  35. package/lib/scratch-cleanup.ts +198 -0
  36. package/lib/scratch-roots.ts +94 -0
  37. package/lib/source-anchor.ts +144 -0
  38. package/lib/success-doc.ts +779 -0
  39. package/lib/suite-run-reading.ts +194 -0
  40. package/lib/test-census.ts +199 -0
  41. package/lib/trajectory.ts +377 -0
  42. package/lib/validators/spec-validators.ts +52 -35
  43. package/lib/workflow-security.ts +152 -7
  44. package/lib/workflow-test-harness.ts +349 -0
  45. package/lib/worktree-cleanup.ts +123 -7
  46. package/lib/worktree-repo.ts +165 -0
  47. package/package.json +10 -1
  48. package/scripts/audit-specs.ts +134 -37
  49. package/scripts/audit-transcript.ts +259 -0
  50. package/scripts/create-sc.ts +15 -1
  51. package/scripts/create-success.ts +162 -0
  52. package/scripts/detect-sc-drift.ts +200 -0
  53. package/scripts/extract-constraints.ts +16 -36
  54. package/scripts/scaffold-project.ts +51 -137
  55. package/scripts/split-spec.ts +315 -0
  56. package/scripts/sync-sc-status.ts +751 -0
  57. package/specs/SPEC-TEMPLATE.md +200 -0
  58. package/templates/SUCCESS-TEMPLATE.md +72 -0
  59. package/templates/agent-briefs/_shared.md +9 -0
  60. package/templates/agent-briefs/aditi.md +46 -0
  61. package/templates/agent-briefs/discovery.md +37 -0
  62. package/templates/agent-briefs/marcus.md +39 -0
  63. package/templates/agent-briefs/quinn.md +67 -0
  64. package/templates/agent-briefs/rook.md +40 -0
  65. package/templates/agent-briefs/serena.md +39 -0
@@ -0,0 +1,435 @@
1
+ /**
2
+ * Where a project's documentation actually lives (#440).
3
+ *
4
+ * `collectScanTargets` was four flat `readdirSync` loops — `*.md`, `docs/*.md`
5
+ * (skipping `archive`), `docs/adr/*.md`, `specs/*.md` — with no recursion.
6
+ * Measured on a consumer project: 84 files scanned, **28 missed**, and every
7
+ * one of the 28 sat in a directory that project's own
8
+ * `.claude/rules/docs-routing.md` names as a documentation location.
9
+ *
10
+ * | Missed | files |
11
+ * |---|---|
12
+ * | `docs/specs/` | 17 |
13
+ * | `reference/` | 5 |
14
+ * | `docs/designs/` | 3 |
15
+ * | `docs/agents/` | 3 |
16
+ *
17
+ * `docs/specs/` is the headline: specs are the densest source of hard
18
+ * constraints in a repo, and the extractor scanned `specs/` (2 files) while
19
+ * skipping `docs/specs/` (17). Same word, different directory, silently
20
+ * dropped.
21
+ *
22
+ * The fix that makes it self-correcting is to stop hardcoding. Every
23
+ * scaffolded project already has a routing table enumerating where its
24
+ * documentation lives — scaffold WRITES that file — so deriving the scan from
25
+ * it makes the extractor track each project's actual layout instead of a list
26
+ * someone has to remember to update.
27
+ */
28
+
29
+ import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "fs";
30
+ import { isAbsolute, join, relative, resolve } from "path";
31
+
32
+ /**
33
+ * Directory names never descended into, wherever they appear.
34
+ *
35
+ * ONE exported list, so there is one thing to mutate and one place to add to.
36
+ * `worktrees` covers `.claude/worktrees`, which is the case the issue names:
37
+ * a worktree is a second copy of the whole repo, so descending into one
38
+ * doubles every constraint and attributes half of them to a path that will
39
+ * not exist tomorrow.
40
+ */
41
+ export const SCAN_EXCLUDE_DIRS: readonly string[] = [
42
+ "archive", "node_modules", ".git", "worktrees", "dist", "build", "coverage",
43
+ ];
44
+
45
+ /**
46
+ * How deep recursion goes beneath a named root.
47
+ *
48
+ * Bounded because the roots come from a file in the repo, and an unbounded
49
+ * walk driven by repo content is a denial of service with extra steps. Six is
50
+ * well past anything observed: the deepest documentation path measured was
51
+ * `specs/bootstrap-data-flow/<file>.md`, at two.
52
+ */
53
+ export const MAX_SCAN_DEPTH = 6;
54
+
55
+ /**
56
+ * Scanned when a project has no routing table.
57
+ *
58
+ * Exactly the four the hardcoded version used, so a project without a routing
59
+ * table sees no change in behaviour — the fallback is the old code, named and
60
+ * reported rather than assumed.
61
+ */
62
+ /**
63
+ * How many directories may be walked.
64
+ *
65
+ * Depth was bounded from the start; breadth was not, and the roots come from
66
+ * a file in the repo — so a table naming thousands of directories is still a
67
+ * walk driven by repo content with no ceiling. Twenty is well past anything
68
+ * observed: this repo declares six.
69
+ */
70
+ export const MAX_SCAN_ROOTS = 20;
71
+
72
+ /**
73
+ * How many files the scan may collect.
74
+ *
75
+ * A cap on roots is not a cap on work — twenty roots times six levels of
76
+ * unbounded fanout is still unbounded — so the bound belongs on the thing
77
+ * that actually grows. This repo's own scan collects 92.
78
+ */
79
+ export const MAX_SCAN_FILES = 2000;
80
+
81
+ export const DEFAULT_SCAN_DIRS: readonly string[] = ["docs", "docs/adr", "specs"];
82
+
83
+ export const ROUTING_RELATIVE_PATH = join(".claude", "rules", "docs-routing.md");
84
+
85
+ export interface DocScanPlan {
86
+ /** Which list the roots came from. Never inferred by the caller. */
87
+ source: "routing" | "default";
88
+ /** Why, in a sentence — so a report can say it rather than imply it. */
89
+ reason: string;
90
+ /** Directories, relative to the project, that exist and were walked. */
91
+ roots: string[];
92
+ /**
93
+ * Directories the routing table names that are NOT on disk.
94
+ *
95
+ * UNMEASURED, not skipped. A routing table that has drifted from the tree
96
+ * is a finding about the project, and `0`, `[]` and "fine" are
97
+ * indistinguishable if it is dropped — which is the whole subject of
98
+ * `.claude/rules/config-access.md`'s *Silent Default Substitution*.
99
+ */
100
+ unmeasured: string[];
101
+ /** Absolute paths, root-level flat plus each root walked. */
102
+ files: string[];
103
+ /**
104
+ * Paths refused because they resolve outside the project (BUG-440-A).
105
+ *
106
+ * Reported rather than dropped, for the same reason `unmeasured` is: a
107
+ * symlinked documentation root that silently contributes nothing is
108
+ * indistinguishable from one that was read and happened to be empty.
109
+ */
110
+ refused: string[];
111
+ /**
112
+ * How many directories the walk entered.
113
+ *
114
+ * On the plan so that the file cap stopping the WALK is checkable rather
115
+ * than asserted in prose — a cap that only stops pushing bounds the output
116
+ * while the traversal keeps costing.
117
+ */
118
+ walked: number;
119
+ }
120
+
121
+ /**
122
+ * The resolved path, if it is really inside the project. Otherwise null.
123
+ *
124
+ * Lexical checks — `startsWith("/")`, `includes("..")` — cannot see a
125
+ * symlink, and recursion is what made that matter: the flat scan this
126
+ * replaces could not descend into `docs/elsewhere -> /somewhere`, so the
127
+ * exposure arrived with the walk. `extract-constraints` turns every `.md`
128
+ * sentence it reaches into a candidate constraint written to AGENTS.md, so
129
+ * one symlink in a cloned repo would copy markdown from anywhere the process
130
+ * can read into this project's rules.
131
+ *
132
+ * Containment, not a symlink ban: a link within the repo is ordinary, and
133
+ * refusing it would be a narrower detector than the thing being detected.
134
+ */
135
+ /**
136
+ * Whether a resolved path lies in or under an excluded directory.
137
+ *
138
+ * Keyed on the RESOLVED path, not the entry name. Measured before this was
139
+ * fixed: `docs/vendor -> node_modules` produced
140
+ * `node_modules/pkg/README.md`, because the exclusion saw the label
141
+ * `vendor`. ONE decider for "is this excluded", so there is one binding to
142
+ * mutate and no second copy that could hold a case up after the first is
143
+ * broken.
144
+ */
145
+ function excludedByPath(rootReal: string, real: string): boolean {
146
+ const rel = relative(rootReal, real);
147
+ if (rel === "") return false;
148
+ // Case-insensitive, always — not "when the filesystem is". On macOS and
149
+ // Windows `NODE_MODULES` and `node_modules` are one directory, and keying
150
+ // on the exact bytes let the whole list be bypassed by changing a letter.
151
+ // Measured before this: `docs/vendor -> NODE_MODULES` was scanned.
152
+ const lowered = SCAN_EXCLUDE_DIRS.map(d => d.toLowerCase());
153
+ return rel.split("/").some(seg => lowered.includes(seg.toLowerCase()));
154
+ }
155
+
156
+ function containedReal(rootReal: string, path: string): string | null {
157
+ let real: string;
158
+ try {
159
+ real = realpathSync(path);
160
+ } catch {
161
+ return null;
162
+ }
163
+ const rel = relative(rootReal, real);
164
+ if (rel !== "" && (rel.startsWith("..") || isAbsolute(rel))) return null;
165
+ return real;
166
+ }
167
+
168
+ /**
169
+ * Everything from the "Where to Create Things" heading onwards.
170
+ *
171
+ * The routing file has TWO tables and they mean different things. The first
172
+ * answers "where do I read about X"; the second answers "where do I put a new
173
+ * X", and it includes `src/` and `test/`. Reading both conflates
174
+ * documentation with source — measured on this repo, it pulled 36 files out
175
+ * of `test/fixtures/`, which is a synthetic project whose "constraints" would
176
+ * then be extracted and attributed to the real one.
177
+ *
178
+ * The cut is by SECTION rather than by column position. A parser tied to a
179
+ * column layout would silently read half when one table changed shape; a
180
+ * heading is what actually separates the two meanings.
181
+ */
182
+ const CREATE_SECTION = /^##\s+Where to Create Things\s*$/m;
183
+
184
+ /**
185
+ * The directories a routing table names as places documentation is READ from.
186
+ *
187
+ * Tokens ending in `/` are directories; `CODE-MAP.md` and friends are single
188
+ * files already caught by the flat root scan.
189
+ */
190
+ export function routedDirectories(routingText: string): string[] {
191
+ const cut = CREATE_SECTION.exec(routingText);
192
+ const readSection = cut ? routingText.slice(0, cut.index) : routingText;
193
+ const out: string[] = [];
194
+ for (const m of readSection.matchAll(/`([^`]+)`/g)) {
195
+ const token = m[1]!.trim();
196
+ if (!token.endsWith("/")) continue;
197
+ const dir = token.replace(/\/+$/, "");
198
+ if (dir === "" || dir.startsWith("/") || dir.includes("..")) continue;
199
+ // "(6 specs)" and similar annotations live outside the backticks, but a
200
+ // token with whitespace in it is prose, not a path.
201
+ if (/\s/.test(dir)) continue;
202
+ if (!out.includes(dir)) out.push(dir);
203
+ }
204
+ return out;
205
+ }
206
+
207
+ interface WalkState {
208
+ projectPath: string;
209
+ rootReal: string;
210
+ /**
211
+ * Resolved paths already handled.
212
+ *
213
+ * Keyed on the RESOLVED path, which is what makes it do two jobs: it stops
214
+ * a symlink loop, and it stops one file reachable under two names from
215
+ * being collected twice. A file counted twice reads as two independent
216
+ * sources agreeing, which is the evidence a reader weighs most heavily.
217
+ */
218
+ seen: Set<string>;
219
+ files: string[];
220
+ refused: string[];
221
+ truncatedFiles: number;
222
+ walked: number;
223
+ }
224
+
225
+ /**
226
+ * The project-anchored canonical spelling of a contained path.
227
+ *
228
+ * `real` is correct but anchored on the resolved root, and on macOS that is
229
+ * `/private/var/...` where the caller said `/var/...`. Callers do
230
+ * `relative(projectPath, file)`, so the path has to keep the caller's
231
+ * spelling of the root while taking the resolved spelling of everything
232
+ * below it.
233
+ *
234
+ * Reporting the canonical name also makes the list deterministic: a file
235
+ * reachable both directly and through an internal symlink was otherwise
236
+ * recorded under whichever name `readdirSync` happened to return first.
237
+ */
238
+ function anchored(projectPath: string, rootReal: string, real: string): string {
239
+ const rel = relative(rootReal, real);
240
+ return rel === "" ? projectPath : join(projectPath, rel);
241
+ }
242
+
243
+ function walkMarkdown(dir: string, depth: number, st: WalkState): void {
244
+ if (depth > MAX_SCAN_DEPTH) return;
245
+ // The cap stops the WALK. Stopping only the push bounds `files` while the
246
+ // traversal and `st.seen` keep growing, which caps the output and not the
247
+ // work.
248
+ if (st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; return; }
249
+ st.walked++;
250
+ let entries: string[];
251
+ try {
252
+ entries = readdirSync(dir);
253
+ } catch {
254
+ return;
255
+ }
256
+ for (const entry of entries) {
257
+ const path = join(dir, entry);
258
+ const isMarkdown = entry.endsWith(".md");
259
+ let isDir: boolean;
260
+ try {
261
+ isDir = statSync(path).isDirectory();
262
+ } catch {
263
+ continue;
264
+ }
265
+ if (!isDir && !isMarkdown) continue;
266
+
267
+ const real = containedReal(st.rootReal, path);
268
+ if (real === null) {
269
+ st.refused.push(path);
270
+ continue;
271
+ }
272
+ if (excludedByPath(st.rootReal, real)) {
273
+ st.refused.push(real);
274
+ continue;
275
+ }
276
+ if (st.seen.has(real)) continue;
277
+ st.seen.add(real);
278
+ if (!isDir && st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; continue; }
279
+
280
+
281
+ // The RESOLVED path is what gets walked and recorded, not the path that
282
+ // was validated a moment ago. Validating one value and using another is
283
+ // a window, however narrow, and using `real` closes it for free.
284
+ if (isDir) walkMarkdown(real, depth + 1, st);
285
+ else st.files.push(anchored(st.projectPath, st.rootReal, real));
286
+ }
287
+ }
288
+
289
+ /**
290
+ * Plan the scan for one project.
291
+ *
292
+ * Root-level `.md` files are read FLAT, exactly as before — recursing from
293
+ * the project root would reach `test/`, `lib/` and every fixture in the tree.
294
+ * Only the named documentation directories are walked.
295
+ */
296
+ export function planDocScan(projectPath: string): DocScanPlan {
297
+ const routingPath = join(projectPath, ROUTING_RELATIVE_PATH);
298
+ const hasRouting = existsSync(routingPath);
299
+
300
+ let declared: string[];
301
+ let source: DocScanPlan["source"];
302
+ let reason: string;
303
+
304
+ if (hasRouting) {
305
+ const routed = routedDirectories(readFileSync(routingPath, "utf-8"));
306
+ // UNION with the defaults, never replacement. This repo's own routing
307
+ // table names `docs/adr/` and `docs/research/` but not `docs/` — so a
308
+ // routing-only scan would have LOST the top-level `docs/*.md` the old
309
+ // code read. A fix for a scan that missed 28 files must not miss
310
+ // different ones.
311
+ declared = [...new Set([...routed, ...DEFAULT_SCAN_DIRS])];
312
+ // `source` answers "did the routing table contribute anything", which is
313
+ // not the same question as "does the file exist". A table naming nothing
314
+ // leaves the defaults doing all the work, and saying "routing" there
315
+ // would report a derivation that did not happen.
316
+ source = routed.length > 0 ? "routing" : "default";
317
+ reason = routed.length > 0
318
+ ? `${routed.length} directories named in ${ROUTING_RELATIVE_PATH}, unioned with the default set`
319
+ : `${ROUTING_RELATIVE_PATH} exists but names no directories — the default set only`;
320
+ } else {
321
+ declared = [...DEFAULT_SCAN_DIRS];
322
+ source = "default";
323
+ reason = `no ${ROUTING_RELATIVE_PATH} — scanning the documented default set`;
324
+ }
325
+
326
+ let rootReal: string;
327
+ try {
328
+ rootReal = realpathSync(resolve(projectPath));
329
+ } catch {
330
+ // Loud, not empty. A project root that cannot be resolved has nothing to
331
+ // scan, and returning zero files would be indistinguishable from a
332
+ // project whose documentation is genuinely empty — Silent Default
333
+ // Substitution, in `.claude/rules/config-access.md`'s terms.
334
+ throw new Error(`cannot scan documentation: ${projectPath} does not resolve to a directory`);
335
+ }
336
+
337
+ const st: WalkState = {
338
+ projectPath,
339
+ rootReal,
340
+ seen: new Set<string>(),
341
+ files: [],
342
+ refused: [],
343
+ truncatedFiles: 0,
344
+ walked: 0,
345
+ };
346
+
347
+ const roots: string[] = [];
348
+ const unmeasured: string[] = [];
349
+ let truncated = 0;
350
+ for (const dir of declared) {
351
+ // The exclusion list has to cover the roots as well as the entries.
352
+ // Applying it only inside the walk left a routing table naming
353
+ // `node_modules/` or `worktrees/` walked outright — the exact case the
354
+ // list exists to stop, reached by the one path the list did not cover.
355
+ const abs = join(projectPath, dir);
356
+ const declaredReal = containedReal(st.rootReal, abs);
357
+ if (declaredReal !== null && excludedByPath(st.rootReal, declaredReal)) {
358
+ st.refused.push(abs);
359
+ continue;
360
+ }
361
+ if (roots.length >= MAX_SCAN_ROOTS) { truncated++; continue; }
362
+ let present: boolean;
363
+ try {
364
+ present = statSync(abs).isDirectory();
365
+ } catch {
366
+ present = false;
367
+ }
368
+ if (present && declaredReal === null) {
369
+ // A routed root that leaves the project is neither walked nor silently
370
+ // treated as missing — "the project does not have this" and "the
371
+ // project points this somewhere I will not follow" are different facts.
372
+ st.refused.push(abs);
373
+ continue;
374
+ }
375
+ // Only a ROUTING entry can be unmeasured. A default directory a project
376
+ // simply does not have is not drift; the routing table is a claim the
377
+ // project made about itself, and a claim that does not hold is a finding.
378
+ if (present) roots.push(dir);
379
+ else if (source === "routing" && !DEFAULT_SCAN_DIRS.includes(dir)) unmeasured.push(dir);
380
+ }
381
+
382
+ if (truncated > 0) {
383
+ // Loud, not silent: a scan that quietly stopped at twenty directories
384
+ // reads as a scan that covered everything.
385
+ reason += ` — bounded at ${MAX_SCAN_ROOTS} roots, ${truncated} not walked`;
386
+ }
387
+
388
+ try {
389
+ for (const f of readdirSync(projectPath)) {
390
+ if (!f.endsWith(".md")) continue;
391
+ const path = join(projectPath, f);
392
+ const real = containedReal(st.rootReal, path);
393
+ if (real === null) { st.refused.push(path); continue; }
394
+ if (st.seen.has(real)) continue;
395
+ st.seen.add(real);
396
+ if (st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; continue; }
397
+ st.files.push(anchored(projectPath, st.rootReal, real));
398
+ }
399
+ } catch {
400
+ // An unreadable project root is the caller's problem, not a silent empty
401
+ // scan — it will show as zero files against a reason that says otherwise.
402
+ }
403
+ for (const dir of roots) walkMarkdown(join(projectPath, dir), 1, st);
404
+
405
+ if (st.truncatedFiles > 0) {
406
+ // Loud, not silent: a scan that quietly stopped reading files reads as
407
+ // a scan that covered everything it was pointed at.
408
+ reason += ` — bounded at ${MAX_SCAN_FILES} files, ${st.truncatedFiles} not read`;
409
+ }
410
+
411
+ st.files.sort();
412
+ st.refused.sort();
413
+ return {
414
+ source, reason, roots, unmeasured,
415
+ files: st.files, refused: st.refused, walked: st.walked,
416
+ };
417
+ }
418
+
419
+ /** Relative paths, for a report that a human reads. */
420
+ export function planSummary(projectPath: string, plan: DocScanPlan): string {
421
+ const parts = [
422
+ `scan: ${plan.files.length} files from ${plan.roots.length} directories (${plan.source} — ${plan.reason})`,
423
+ ];
424
+ if (plan.refused.length > 0) {
425
+ parts.push(
426
+ `REFUSED: ${plan.refused.map(r => relative(projectPath, r) || r).join(", ")} — resolves outside the project`,
427
+ );
428
+ }
429
+ if (plan.unmeasured.length > 0) {
430
+ parts.push(
431
+ `UNMEASURED: ${plan.unmeasured.join(", ")} — named in ${ROUTING_RELATIVE_PATH} but not present in ${relative(projectPath, projectPath) || "the project"}`,
432
+ );
433
+ }
434
+ return parts.join("\n");
435
+ }
@@ -46,16 +46,16 @@ export const WARN_TIER_CHECKS: Readonly<Record<string, string>> = Object.freeze(
46
46
  "spec-decision-compliance: AC language aligns with spec decisions":
47
47
  "#409 Decision #9 placed this in the WARN tier explicitly: it matches AC prose against " +
48
48
  "regex anti-patterns, and a regex over prose is not a basis for refusing a run.",
49
- "outcome-evidence-behavioral: OUTCOME AC evidence is not just a number":
50
- "#183 — reported, not fixed. This one is NOT a documented decision like the two above; " +
51
- "it is `tsc-pass`'s shape with a console.warn where the assertion should be, and the " +
52
- "sibling check `outcome-acs-no-skip` two tests above it does assert. Tightening it is a " +
53
- "behaviour change to a live gate and belongs to its own issue.",
54
49
  "ac-issue-alignment: ACs cover goal keywords":
55
- "#183 — reported, not fixed. Found by this audit, not by #176. ADR-009 C4 asks that ACs " +
56
- "cover the goal's keywords; the body computes a coverage ratio and warns under 50%. A " +
57
- "stopword-filtered substring match is not a basis for refusing a run, but nothing said " +
58
- "so until this entry, which is the whole point of the list.",
50
+ "#423 Decision — measured, then kept as a warning. ADR-009 C4 asks that ACs cover the " +
51
+ "goal's keywords and the body warns under 50% coverage. Measured over the 153 " +
52
+ "workflow-state.json files under ~/.rungate carrying a goal: 71% fall under that " +
53
+ "threshold, median coverage 38%. Restricted to states whose ACs carry real statements " +
54
+ "the figure is 66% of 131, median 41%; for substantial ones, 73% of 101. The number does " +
55
+ "not move, and a check that would refuse two runs in three is an outage rather than a " +
56
+ "gate. Same basis #409 Decision #9 rejected for spec-decision-compliance: a match over " +
57
+ "prose is not grounds for refusing a run. The reading is lib/ac-quality.ts's " +
58
+ "goalKeywordCoverage so the threshold is drivable from both sides by a test.",
59
59
  });
60
60
 
61
61
  /**
package/lib/github.ts CHANGED
@@ -37,6 +37,16 @@ export interface GitHubClient {
37
37
  update: (params: { owner: string; repo: string; pull_number: number; [key: string]: any }) => Promise<{ data: any }>;
38
38
  list: (params: { owner: string; repo: string; [key: string]: any }) => Promise<{ data: any[] }>;
39
39
  };
40
+ checks: {
41
+ /**
42
+ * Check runs for one ref (#46).
43
+ *
44
+ * `ref` is passed a commit SHA and never a branch name. The endpoint
45
+ * accepts both, and the branch form is the whole defect this gate would
46
+ * otherwise introduce — see `readCi`.
47
+ */
48
+ listForRef: (params: { owner: string; repo: string; ref: string; per_page?: number }) => Promise<{ data: { total_count: number; check_runs: any[] } }>;
49
+ };
40
50
  };
41
51
  /**
42
52
  * The GraphQL endpoint, for the handful of operations REST does not expose.
@@ -537,3 +547,188 @@ export async function listPRs(client: GitHubClient, repoSlug: string, opts?: Lis
537
547
  });
538
548
  return response.data;
539
549
  }
550
+
551
+ // ── CI verification (#46) ────────────────────────────────────
552
+
553
+ /**
554
+ * One check run, reduced to the four fields a verdict depends on.
555
+ *
556
+ * `headSha` is carried even though the query is already keyed on a SHA. It is
557
+ * the field `readCi` re-checks, and re-checking it is the point: see below.
558
+ */
559
+ export interface CheckRunSummary {
560
+ name: string;
561
+ /** `queued` | `in_progress` | `completed`, per the checks API. */
562
+ status: string;
563
+ /** `null` until the run completes. Never treat null as success. */
564
+ conclusion: string | null;
565
+ headSha: string;
566
+ url?: string;
567
+ }
568
+
569
+ export interface CiReading {
570
+ verdict: "PASS" | "FAIL" | "UNMEASURED";
571
+ /** The commit the verdict is ABOUT. A reading without this is not a reading. */
572
+ sha: string;
573
+ /** A sentence naming why, in every branch including PASS. */
574
+ reason: string;
575
+ checks: CheckRunSummary[];
576
+ failed: string[];
577
+ pending: string[];
578
+ /** Checks that completed without concluding either way — skipped, neutral. */
579
+ inconclusive: string[];
580
+ }
581
+
582
+ /**
583
+ * Conclusions that mean the check ran and said no.
584
+ *
585
+ * `cancelled` is in here deliberately. A cancelled run measured nothing, so
586
+ * the tempting reading is UNMEASURED — but on this repo's CI a cancellation is
587
+ * almost always `concurrency: cancel-in-progress` superseding the run, and
588
+ * calling that "unmeasured" lets a superseded commit's gate pass on a reading
589
+ * about a commit nobody is shipping. FAIL is the direction that costs a re-run
590
+ * rather than a bad merge.
591
+ */
592
+ const CI_FAILURE_CONCLUSIONS = new Set([
593
+ "failure",
594
+ "timed_out",
595
+ "cancelled",
596
+ "action_required",
597
+ "startup_failure",
598
+ "stale",
599
+ ]);
600
+
601
+ /**
602
+ * Conclusions that completed without answering the question.
603
+ *
604
+ * `skipped` is the one that matters. A skipped check is the single most
605
+ * convincing-looking way for this gate to certify nothing: the run exists, it
606
+ * completed, it did not fail, and a verdict computed as "no failures" calls it
607
+ * PASS. It measured nothing, so the reading is UNMEASURED.
608
+ */
609
+ const CI_INCONCLUSIVE_CONCLUSIONS = new Set(["skipped", "neutral"]);
610
+
611
+ /**
612
+ * The verdict for one commit, from the checks recorded against it.
613
+ *
614
+ * Pure, and separate from the fetching, because every interesting decision
615
+ * here is a classification rather than a network call — and the classification
616
+ * is the part that has to be wrong-proof.
617
+ *
618
+ * **There is no branch that arrives at PASS by not finding a failure.** PASS
619
+ * requires at least one check, every check belonging to this exact commit,
620
+ * every check `completed`, and every conclusion `success`. Absence, pending,
621
+ * skipped and null all land elsewhere. That is the whole design: the natural
622
+ * implementation of "did CI pass" is `!checks.some(failed)`, which returns
623
+ * true for a commit CI has never heard of.
624
+ *
625
+ * **A check whose `headSha` differs is discarded, not counted.** The checks
626
+ * API accepts a branch name as `ref` and will happily answer about whatever
627
+ * commit that branch pointed at when CI last ran — so a gate keyed on the
628
+ * branch certifies the previous push. Filtering here means that even a caller
629
+ * who passes a branch name gets UNMEASURED rather than a stale PASS.
630
+ */
631
+ export function readCi(sha: string, checks: CheckRunSummary[]): CiReading {
632
+ const base = { sha, checks, failed: [] as string[], pending: [] as string[], inconclusive: [] as string[] };
633
+
634
+ if (!sha || !/^[0-9a-f]{7,40}$/i.test(sha)) {
635
+ return { ...base, verdict: "UNMEASURED", reason: `"${sha}" is not a commit SHA, so there is nothing to ask CI about — a ref that is not a SHA would be answered about whatever commit it last pointed at` };
636
+ }
637
+
638
+ const mine = checks.filter(c => c.headSha === sha);
639
+ const foreign = checks.filter(c => c.headSha !== sha);
640
+ if (mine.length === 0) {
641
+ return {
642
+ ...base,
643
+ verdict: "UNMEASURED",
644
+ reason: foreign.length > 0
645
+ ? `every check found belongs to a different commit (${[...new Set(foreign.map(c => c.headSha))].join(", ")}), not ${sha} — this is the stale reading, not a pass`
646
+ : `no check has been recorded for ${sha} — CI has not reported on this commit, which is not the same as reporting success`,
647
+ };
648
+ }
649
+
650
+ const failed = mine.filter(c => c.conclusion !== null && CI_FAILURE_CONCLUSIONS.has(c.conclusion)).map(c => c.name);
651
+ const pending = mine.filter(c => c.status !== "completed").map(c => c.name);
652
+ const inconclusive = mine
653
+ .filter(c => c.status === "completed" && (c.conclusion === null || CI_INCONCLUSIVE_CONCLUSIONS.has(c.conclusion)))
654
+ .map(c => c.name);
655
+ const full = { ...base, checks: mine, failed, pending, inconclusive };
656
+
657
+ // A failure first, even with others still running. More waiting cannot
658
+ // un-fail a check, and reporting UNMEASURED here would turn a known red into
659
+ // "we did not find out".
660
+ if (failed.length > 0) {
661
+ return { ...full, verdict: "FAIL", reason: `CI failed on ${sha}: ${failed.join(", ")}` };
662
+ }
663
+ if (pending.length > 0) {
664
+ return { ...full, verdict: "UNMEASURED", reason: `CI has not finished on ${sha} — still running: ${pending.join(", ")}` };
665
+ }
666
+ if (inconclusive.length > 0) {
667
+ return { ...full, verdict: "UNMEASURED", reason: `CI completed on ${sha} without measuring: ${inconclusive.join(", ")} neither passed nor failed` };
668
+ }
669
+ return { ...full, verdict: "PASS", reason: `all ${mine.length} check${mine.length === 1 ? "" : "s"} passed on ${sha}: ${mine.map(c => c.name).join(", ")}` };
670
+ }
671
+
672
+ /** The check runs GitHub has recorded against one commit. */
673
+ export async function listCheckRuns(client: GitHubClient, repoSlug: string, sha: string): Promise<CheckRunSummary[]> {
674
+ const { owner, repo } = parseOwnerRepo(repoSlug);
675
+ const response = await client.rest.checks.listForRef({ owner, repo, ref: sha, per_page: 100 });
676
+ return (response.data?.check_runs ?? []).map((c: any) => ({
677
+ name: String(c.name ?? "<unnamed>"),
678
+ status: String(c.status ?? "unknown"),
679
+ conclusion: c.conclusion === undefined ? null : c.conclusion,
680
+ headSha: String(c.head_sha ?? ""),
681
+ url: typeof c.html_url === "string" ? c.html_url : undefined,
682
+ }));
683
+ }
684
+
685
+ export interface WaitForCiOptions {
686
+ timeoutMs: number;
687
+ intervalMs: number;
688
+ /** Injected so a test can run the loop without waiting for it. */
689
+ sleep?: (ms: number) => Promise<void>;
690
+ now?: () => number;
691
+ }
692
+
693
+ /**
694
+ * Poll until CI has an answer for this commit, or until the wait runs out.
695
+ *
696
+ * Polling, and not a webhook, because a local harness has no inbound endpoint
697
+ * for a webhook to arrive at — the choice is not whether to poll but who does
698
+ * and whether the wait is bounded. `gh run watch` polls too, and blocks
699
+ * without a bound.
700
+ *
701
+ * **A timeout returns the last reading, which is UNMEASURED.** It never
702
+ * upgrades to PASS, and it never degrades to FAIL either: running out of
703
+ * patience is not evidence about the code. The returned reason names what was
704
+ * still pending, so the operator can see what it was waiting for.
705
+ */
706
+ export async function waitForCi(
707
+ client: GitHubClient,
708
+ repoSlug: string,
709
+ sha: string,
710
+ opts: WaitForCiOptions,
711
+ ): Promise<CiReading> {
712
+ const sleep = opts.sleep ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)));
713
+ const now = opts.now ?? (() => Date.now());
714
+ const deadline = now() + Math.max(0, opts.timeoutMs);
715
+ let reading = readCi(sha, await listCheckRuns(client, repoSlug, sha));
716
+
717
+ // Only a pending or absent reading is worth waiting on. A FAIL will not
718
+ // improve, a PASS will not get better, and an inconclusive check has already
719
+ // finished — polling those is time spent to reach the same answer.
720
+ const worthWaiting = (r: CiReading) => r.verdict === "UNMEASURED" && (r.pending.length > 0 || r.checks.length === 0);
721
+
722
+ while (worthWaiting(reading) && now() < deadline) {
723
+ await sleep(Math.min(opts.intervalMs, Math.max(0, deadline - now())));
724
+ reading = readCi(sha, await listCheckRuns(client, repoSlug, sha));
725
+ }
726
+ if (worthWaiting(reading)) {
727
+ const waited = Math.round(opts.timeoutMs / 1000);
728
+ return {
729
+ ...reading,
730
+ reason: `${reading.reason} — gave up after ${waited}s, which is a statement about the wait and not about the code`,
731
+ };
732
+ }
733
+ return reading;
734
+ }