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
@@ -188,6 +188,186 @@ export function probeTarget(
188
188
  return { kind: "probe", url, safeUrl: safeForRecord(url) };
189
189
  }
190
190
 
191
+ /**
192
+ * Where to reach the test container, or why not (#312 SC-A15, harness half).
193
+ *
194
+ * `probeTarget` was written so "unconfigured is UNMEASURED, never DOWN" is
195
+ * decided once (SC-733). It covers `dev` and `prod`. The container is the
196
+ * third tier and never went through it: `workflows/ship.js` built its own URL
197
+ * at two sites, from `(container.hosts || [])[0]` and `container.port || 3000`.
198
+ *
199
+ * Nothing reached either site until now. `ProjectHarnessSchema` did not
200
+ * declare `container`, so the validator deleted the key and both sites took
201
+ * their no-container arm on every run that has ever happened. #307 SC-A1
202
+ * declared it, and SC-A15 is a consumer putting a value there — at which
203
+ * point the first consumer with a `rebuildCommand` and no `hosts` gets:
204
+ *
205
+ * curl -s -o /dev/null -w "%{http_code}" http://undefined:3000/
206
+ *
207
+ * interpolated into an agent prompt, no 200 back, and
208
+ * `prod.smoke = SKIP, smokeSkipReason = test container not running` written
209
+ * into the artefact. That reason is a positive claim about a container
210
+ * nothing contacted, and it is indistinguishable in the record from a probe
211
+ * that ran and found the container down. Every field of `ContainerSchema` is
212
+ * optional, so that config validates.
213
+ *
214
+ * So there are three outcomes and not two, and the difference between the two
215
+ * new ones is which verdict the run has earned:
216
+ *
217
+ * - `unconfigured` — no container. Nothing to measure; the run may SKIP.
218
+ * - `unmeasured` — a container is declared and the config does not say where
219
+ * to reach it. The run measured nothing and must not say otherwise; its
220
+ * caller records FAIL, because SKIP here reads exactly like success.
221
+ * - `probe` — a URL built from values that were all present and well-formed.
222
+ *
223
+ * No default host and no default port. `|| 3000` is the same instinct as the
224
+ * `?? "/health"` this module already refuses: a guessed port is answered by
225
+ * whatever else holds it, and the run reports on a container it never found.
226
+ */
227
+ export type ContainerProbe =
228
+ | { kind: "unconfigured"; detail: string }
229
+ | { kind: "unmeasured"; detail: string }
230
+ | {
231
+ kind: "probe";
232
+ host: string;
233
+ port: number;
234
+ healthPath: string;
235
+ url: string;
236
+ safeUrl: string;
237
+ };
238
+
239
+ /**
240
+ * Hostname or IP literal, and nothing else.
241
+ *
242
+ * The host is interpolated into a `curl` command inside an agent prompt and
243
+ * is never shell-quoted there. This charset has no shell metacharacter, no
244
+ * `@` (so no userinfo can ride in) and no `:` (so no second port), which is
245
+ * also why `redactSecrets` has nothing to find in the authority half of the
246
+ * URL this builds. A host that does not match is not sanitised — it is
247
+ * refused, and the run says it was not probed.
248
+ */
249
+ export const CONTAINER_HOST = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
250
+
251
+ /**
252
+ * A character in `healthPath` that means something to a shell (#1031).
253
+ *
254
+ * Same set as `SHELL_METACHARACTERS` in `lib/workflow-security.ts`, and
255
+ * deliberately so: that is the set this project already decided reaches a
256
+ * shell unsafely, and a second, kinder set here would be a second answer to
257
+ * the same question.
258
+ *
259
+ * ## Why `healthPath` needs this when the config file is trusted
260
+ *
261
+ * `.claude/rungate/config.json` IS trusted. It is the operator's own file,
262
+ * `scripts/resolve-config.ts` is the only thing that reads it, and
263
+ * `container.rebuildCommand` is arbitrary command execution by design — a
264
+ * consumer who puts a destructive command behind that key has configured
265
+ * their own run to do that. Gating a trusted file against its own author is
266
+ * theatre, and #1031 names it as the cheapest wrong fix on offer.
267
+ *
268
+ * But the value that reaches the shell is not that file. `workflows/ship.js`
269
+ * cannot read files — the Workflow sandbox has no module loading (#69) — so
270
+ * the block it hands this function is `setupResult.config.container`: the
271
+ * **setup agent's restatement** of a file ship.js never sees, filtered on
272
+ * the way back by a JSON schema that constrains types and no values, and
273
+ * produced in a prompt that also carries issue-authored text. ship.js
274
+ * already names that channel for its neighbouring fields — *the reply agrees
275
+ * with whatever was put in it*, the #530 shape — and routes `harnessSha`
276
+ * through `rookReviewSha` rather than interpolating it, for this reason.
277
+ *
278
+ * So the trusted object and the interpolated object are different objects,
279
+ * and `healthPath` is the one free-form component of the URL this builds.
280
+ * `host` is already charset-filtered above and `port` is already a number;
281
+ * without this rule `/h;id` is an absolute path that is not `//`, so it
282
+ * becomes a `probe` and `;id` runs.
283
+ *
284
+ * REFUSED as `unmeasured`, never sanitised: a quietly repaired path probes a
285
+ * URL nobody configured and records the answer as the container's.
286
+ *
287
+ * ## Why this is narrower than `SHELL_METACHARACTERS`
288
+ *
289
+ * That set refuses `?`, `#`, `*`, `[`, `~` and `!`, and a health path is
290
+ * allowed all of them: `/h?token=…` is a shape this module already supports
291
+ * on purpose — `safeForRecord` exists to redact exactly that query string,
292
+ * and `SC-2485` asserts it. Refusing `?` here would delete a documented
293
+ * consumer shape to block a glob that the quoting added by #1031 at both
294
+ * `curl` sites already makes inert.
295
+ *
296
+ * What stays refused is the set no URL path needs and that ends a quoted
297
+ * shell word or starts a substitution: `;` `&` `|` `$` `` ` `` `"` `'` `\`
298
+ * `<` `>` `{` `}`, whitespace, and control characters. Every payload #1031
299
+ * named — `/h;id`, `/$(id)`, a backtick, `/h'` — is in it.
300
+ */
301
+ // eslint-disable-next-line no-control-regex
302
+ const CONTAINER_HEALTH_PATH_UNSAFE = /[;&|$`"'\\<>{}\s\u0000-\u001f]/;
303
+
304
+ export function containerProbeTarget(
305
+ container:
306
+ | { port?: unknown; healthPath?: unknown; hosts?: unknown; rebuildCommand?: unknown }
307
+ | null
308
+ | undefined,
309
+ ): ContainerProbe {
310
+ if (!container || typeof container !== "object") {
311
+ return {
312
+ kind: "unconfigured",
313
+ detail: "no container is configured for this project",
314
+ };
315
+ }
316
+ const hosts = Array.isArray(container.hosts) ? container.hosts : [];
317
+ const host = hosts.find(
318
+ (h: unknown) => typeof h === "string" && CONTAINER_HOST.test(h),
319
+ ) as string | undefined;
320
+ if (!host) {
321
+ return {
322
+ kind: "unmeasured",
323
+ detail:
324
+ "a container is configured and container.hosts names no host to reach it at, " +
325
+ "so nothing was probed. No host is guessed. This is UNMEASURED, not DOWN",
326
+ };
327
+ }
328
+ const port = container.port;
329
+ if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) {
330
+ return {
331
+ kind: "unmeasured",
332
+ detail:
333
+ `a container is configured at ${host} and container.port is not a port number, ` +
334
+ "so nothing was probed. No default port is invented: a guessed port is answered " +
335
+ "by whatever else holds it. This is UNMEASURED, not DOWN",
336
+ };
337
+ }
338
+ const raw = container.healthPath;
339
+ const healthPath = raw === undefined || raw === null || raw === "" ? "/" : raw;
340
+ // The value is never quoted back. It is the one free-form component here,
341
+ // it reaches a durable artefact, and naming the key is what a reader needs.
342
+ if (
343
+ typeof healthPath !== "string" ||
344
+ !healthPath.startsWith("/") ||
345
+ healthPath.startsWith("//")
346
+ ) {
347
+ return {
348
+ kind: "unmeasured",
349
+ detail:
350
+ `a container is configured at ${host} port ${port} and container.healthPath is not ` +
351
+ "an absolute path, so nothing was probed. This is UNMEASURED, not DOWN",
352
+ };
353
+ }
354
+ // #1031 — see CONTAINER_HEALTH_PATH_UNSAFE. The refused value is NOT echoed
355
+ // into the detail: this string is interpolated into a `bun -e` program in an
356
+ // agent prompt and written to a durable artefact, which is the last place
357
+ // the thing we just refused should turn up.
358
+ if (healthPath.length > 200 || CONTAINER_HEALTH_PATH_UNSAFE.test(healthPath)) {
359
+ return {
360
+ kind: "unmeasured",
361
+ detail:
362
+ `a container is configured at ${host} port ${port} and container.healthPath carries ` +
363
+ "whitespace, a shell metacharacter or over 200 characters, so nothing was probed. " +
364
+ "It reaches a curl command an agent runs. This is UNMEASURED, not DOWN",
365
+ };
366
+ }
367
+ const url = `http://${host}:${port}${healthPath}`;
368
+ return { kind: "probe", host, port, healthPath, url, safeUrl: safeForRecord(url) };
369
+ }
370
+
191
371
  export function livenessPlan(
192
372
  acs: unknown,
193
373
  dev: { apiBase?: string; healthPath?: string; start?: string } | undefined,
@@ -0,0 +1,432 @@
1
+ /**
2
+ * The other half of #523: is the list of "fields that must be stable" still true?
3
+ *
4
+ * `lib/discovery-stability.ts` compares k recorded runs over
5
+ * `STABLE_DISCOVERY_FIELDS`. That list was not written by taste — it was
6
+ * derived from one criterion, stated on #523 before any code:
7
+ *
8
+ * **A discovery field is required to be stable exactly when something
9
+ * downstream BRANCHES on it.**
10
+ *
11
+ * The same comment named the consequence and did not build it:
12
+ *
13
+ * *"The list is derivable, so it can be a test rather than a document.
14
+ * Something walking the branch points in `workflows/ship.js` and comparing
15
+ * them to the declared stable set would catch a new branch on a field
16
+ * nobody declared stable — which is the failure mode a hand-maintained
17
+ * list has."*
18
+ *
19
+ * This module is that walk. Without it the comparator has a hole that is
20
+ * invisible from inside itself: add `if (discovery.riskTier === 'HIGH')` to
21
+ * the workflow tomorrow and every test in `test/discovery-stability.test.ts`
22
+ * stays green, because every one of them reads the declared list, the schema,
23
+ * or synthetic states — never the workflow. The measurement would go on
24
+ * reporting "8 fields observed, 0 varied" while the field that actually
25
+ * decides the run was not among them. A list that can only be checked against
26
+ * itself is a document.
27
+ *
28
+ * ## The two readings, and what varies between them
29
+ *
30
+ * Reading A is the DECLARATION: `STABLE_DISCOVERY_FIELDS` plus `NOT_ASSERTED`,
31
+ * hand-written in `lib/discovery-stability.ts`.
32
+ *
33
+ * Reading B is the CODE: the conditions in `workflows/ship.js`, parsed, and
34
+ * the discovery properties read inside them.
35
+ *
36
+ * They have different producers and different inputs, which is the whole
37
+ * point — a determinism check that builds the same thing twice with the same
38
+ * code is 0 red against the mutation it exists to catch. Editing either side
39
+ * alone changes the result here: a new branch grows B, deleting an entry
40
+ * shrinks A, and `auditBranchCoverage` reports the disagreement either way.
41
+ *
42
+ * What this asserts is therefore (c): **a refusal when the two readings
43
+ * disagree.** Not a shape, not an order. No model is called and nothing here
44
+ * can red on a model-day.
45
+ *
46
+ * ## Why an empty reading is refused rather than counted as agreement
47
+ *
48
+ * A census that finds nothing agrees with every possible list. If the
49
+ * extractor breaks — the workflow stops parsing, the discovery object is
50
+ * renamed, acorn changes a node name — the honest result is UNMEASURED, not
51
+ * "no undeclared fields". Both the empty-source and the zero-branch-point
52
+ * cases leave through `refuse()`, which is guarded by the single exported
53
+ * `BRANCH_CENSUS_REFUSE` constant so a test can zero it and show each negative
54
+ * case passing only because the refusal fired
55
+ * (`.claude/rules/checks-must-be-able-to-fail.md`).
56
+ */
57
+
58
+ import { parse } from "acorn";
59
+
60
+ import { NOT_ASSERTED, STABLE_DISCOVERY_FIELDS, type StableField } from "./discovery-stability";
61
+
62
+ /**
63
+ * The one switch every refusal goes through. Declared on a single line and
64
+ * assigned exactly once, so a mutant copy with `= 0` neutralises ALL refusals
65
+ * and no branch can quietly bypass the mutation by raising directly.
66
+ */
67
+ export const BRANCH_CENSUS_REFUSE = 1;
68
+
69
+ /** Raised by every refusal in this module. */
70
+ export class BranchCensusRefusal extends Error {
71
+ constructor(reason: string) {
72
+ super(`branch census REFUSED: ${reason}`);
73
+ this.name = "BranchCensusRefusal";
74
+ }
75
+ }
76
+
77
+ function refuse(reason: string): never | void {
78
+ if (BRANCH_CENSUS_REFUSE) throw new BranchCensusRefusal(reason);
79
+ }
80
+
81
+ /**
82
+ * The identifiers the workflow holds DISCOVERY's model output in.
83
+ *
84
+ * `discovery` is the object `workflows/ship.js` parses the discovery agent's
85
+ * JSON into; `disc` is the short alias the same file uses in a few helpers.
86
+ * A rename that misses this list drops the census to zero branch points,
87
+ * which is refused rather than reported as agreement.
88
+ */
89
+ export const DISCOVERY_ROOTS = ["discovery", "disc"] as const;
90
+
91
+ /**
92
+ * Where a read of a discovery field decides what the run does.
93
+ *
94
+ * Keyed by acorn node type, valued by the property holding the deciding
95
+ * expression. A read anywhere else in the program — interpolated into a
96
+ * prompt, logged, copied into the state file — is not a branch and is not
97
+ * the subject of #523's criterion.
98
+ */
99
+ export const CONDITION_POSITIONS: Record<string, readonly string[]> = {
100
+ IfStatement: ["test"],
101
+ ConditionalExpression: ["test"],
102
+ SwitchStatement: ["discriminant"],
103
+ SwitchCase: ["test"],
104
+ WhileStatement: ["test"],
105
+ DoWhileStatement: ["test"],
106
+ ForStatement: ["test"],
107
+ /**
108
+ * `a && b` / `a || c` / `a ?? b`: the LEFT operand decides whether the right
109
+ * one is evaluated, so it is a branch wherever it appears. The right operand
110
+ * is not — it is the consequent.
111
+ */
112
+ LogicalExpression: ["left"],
113
+ };
114
+
115
+ export interface BranchPoint {
116
+ /** The discovery property the condition reads, e.g. `ceremonyTier`. */
117
+ field: string;
118
+ /** The root identifier it was read off — one of `DISCOVERY_ROOTS`. */
119
+ root: string;
120
+ /** The acorn construct that makes it a branch, e.g. `IfStatement.test`. */
121
+ construct: string;
122
+ /** 1-based line in the source, so a finding can be opened. */
123
+ line: number;
124
+ /** The condition text, collapsed and clipped. Evidence, not decoration. */
125
+ snippet: string;
126
+ }
127
+
128
+ type AstNode = { type: string; start: number; end: number; [k: string]: unknown };
129
+
130
+ function isNode(value: unknown): value is AstNode {
131
+ return (
132
+ typeof value === "object" &&
133
+ value !== null &&
134
+ typeof (value as AstNode).type === "string" &&
135
+ typeof (value as AstNode).start === "number" &&
136
+ typeof (value as AstNode).end === "number"
137
+ );
138
+ }
139
+
140
+ /**
141
+ * acorn options, matching `lib/reachability.ts`: `workflows/ship.js` is a
142
+ * module body the Workflow runtime wraps in an async function before running,
143
+ * so it legitimately contains top-level `return` and `await`. Both options
144
+ * only widen what PARSES.
145
+ */
146
+ const PARSE_OPTIONS = {
147
+ ecmaVersion: "latest",
148
+ sourceType: "module",
149
+ allowReturnOutsideFunction: true,
150
+ allowAwaitOutsideFunction: true,
151
+ allowHashBang: true,
152
+ } as const;
153
+
154
+ function children(node: AstNode): AstNode[] {
155
+ const out: AstNode[] = [];
156
+ for (const value of Object.values(node)) {
157
+ if (Array.isArray(value)) {
158
+ for (const child of value) if (isNode(child)) out.push(child);
159
+ } else if (isNode(value)) {
160
+ out.push(value);
161
+ }
162
+ }
163
+ return out;
164
+ }
165
+
166
+ function walk(node: AstNode, visit: (n: AstNode) => void): void {
167
+ visit(node);
168
+ for (const child of children(node)) walk(child, visit);
169
+ }
170
+
171
+ /**
172
+ * The discovery property a member expression reads, or null.
173
+ *
174
+ * Only the FIRST property off the root is returned: `discovery.sizing` and
175
+ * `discovery.sizing.predicted` both census as `sizing`, because the criterion
176
+ * is about which model-authored field decides the run, and the declaration
177
+ * side maps its own finer state paths onto these names through `readAs`.
178
+ * Computed access (`discovery[k]`) yields no name and is reported separately.
179
+ */
180
+ function rootedRead(node: AstNode): { root: string; field: string } | null {
181
+ if (node.type !== "MemberExpression") return null;
182
+ const object = node.object as AstNode | undefined;
183
+ const property = node.property as AstNode | undefined;
184
+ if (!isNode(object) || !isNode(property)) return null;
185
+ if (object.type !== "Identifier") return null;
186
+ const root = String((object as unknown as { name: string }).name);
187
+ if (!(DISCOVERY_ROOTS as readonly string[]).includes(root)) return null;
188
+ if (node.computed === true) return null;
189
+ if (property.type !== "Identifier") return null;
190
+ return { root, field: String((property as unknown as { name: string }).name) };
191
+ }
192
+
193
+ function lineOf(source: string, offset: number): number {
194
+ let line = 1;
195
+ for (let i = 0; i < offset && i < source.length; i++) if (source[i] === "\n") line++;
196
+ return line;
197
+ }
198
+
199
+ function clip(text: string, max = 110): string {
200
+ const flat = text.replace(/\s+/g, " ").trim();
201
+ return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
202
+ }
203
+
204
+ /**
205
+ * Every discovery property read inside a condition, one entry per read.
206
+ *
207
+ * REFUSES when the source does not parse, and when the walk finds no branch
208
+ * point at all — see the module header for why an empty census is not
209
+ * agreement.
210
+ */
211
+ export function extractDiscoveryBranchPoints(source: string): BranchPoint[] {
212
+ let program: AstNode;
213
+ try {
214
+ program = parse(source, PARSE_OPTIONS) as unknown as AstNode;
215
+ } catch (err) {
216
+ refuse(`the source does not parse as JavaScript: ${(err as Error).message}`);
217
+ return [];
218
+ }
219
+
220
+ const found: BranchPoint[] = [];
221
+ walk(program, node => {
222
+ const positions = CONDITION_POSITIONS[node.type];
223
+ if (!positions) return;
224
+ for (const position of positions) {
225
+ const condition = node[position];
226
+ if (!isNode(condition)) continue;
227
+ walk(condition, inner => {
228
+ const read = rootedRead(inner);
229
+ if (!read) return;
230
+ found.push({
231
+ field: read.field,
232
+ root: read.root,
233
+ construct: `${node.type}.${position}`,
234
+ line: lineOf(source, inner.start),
235
+ snippet: clip(source.slice(condition.start, condition.end)),
236
+ });
237
+ });
238
+ }
239
+ });
240
+
241
+ if (found.length === 0) {
242
+ refuse(
243
+ `no condition in this source reads any of [${DISCOVERY_ROOTS.join(", ")}]. ` +
244
+ `A census that finds nothing agrees with every possible list, so this is UNMEASURED, ` +
245
+ `not "no undeclared fields".`,
246
+ );
247
+ }
248
+
249
+ return found;
250
+ }
251
+
252
+ /* ────────────────────────── the declaration side ────────────────────────── */
253
+
254
+ /**
255
+ * A declaration entry that names which workflow-source property it covers.
256
+ *
257
+ * `STABLE_DISCOVERY_FIELDS` speaks in STATE paths (`sizing.ceremonyTier`) and
258
+ * the workflow speaks in DISCOVERY-object properties (`discovery.ceremonyTier`)
259
+ * — `workflows/ship.js` flattens one into the other when it writes the state
260
+ * file. `readAs` is that mapping, declared rather than guessed: a path with no
261
+ * `readAs` covers nothing, so adding an entry does not silently excuse a
262
+ * branch.
263
+ */
264
+ export interface SourceMapped {
265
+ path: string;
266
+ readAs?: readonly string[];
267
+ }
268
+
269
+ /** The discovery properties a declaration list claims to cover. */
270
+ export function coveredFields(entries: readonly SourceMapped[]): Set<string> {
271
+ const out = new Set<string>();
272
+ for (const entry of entries) for (const name of entry.readAs ?? []) out.add(name);
273
+ return out;
274
+ }
275
+
276
+ /**
277
+ * Branched on, and NOT MEASURABLE — the third register, and the one this
278
+ * census produced.
279
+ *
280
+ * `filesToModify` and `scopeOut` both meet #523's criterion outright: the run
281
+ * takes a different path on each of them. Neither is in
282
+ * `WorkflowStateSchema`. They exist inside a run and are gone when it ends, so
283
+ * no comparison over recorded run states can read them in either direction —
284
+ * a declared path for one would resolve to `undefined` in every run, which is
285
+ * perfectly stable and completely uninformative.
286
+ *
287
+ * They are therefore recorded as **UNMEASURED, not as excluded**. The
288
+ * distinction is the point: `NOT_ASSERTED` means "we looked and decided not
289
+ * to", this means "we could not look". A reading nobody could take is not a
290
+ * reading that passed.
291
+ *
292
+ * The excuse is itself checked. `test/discovery-branch-coverage.test.ts`
293
+ * asserts every entry here is genuinely ABSENT from the real
294
+ * `WorkflowStateSchema` — so the day somebody persists `filesToModify`, this
295
+ * entry becomes false and reddens, forcing the field into
296
+ * `STABLE_DISCOVERY_FIELDS` where it now belongs. An excuse that cannot go
297
+ * stale is a comment.
298
+ */
299
+ export const BRANCHED_BUT_UNPERSISTED: { field: string; reason: string }[] = [
300
+ {
301
+ field: "filesToModify",
302
+ reason:
303
+ "`workflows/ship.js:3841` branches the M-size decomposition on `(discovery.filesToModify || []).length >= 3`, and `:2964` feeds its contents to `scopeContradiction`, which REFUSES the run. Both are decisions, so the criterion is met — but `WorkflowStateSchema` has no `filesToModify`, so a k-run series cannot observe it. Measuring this needs the field persisted first.",
304
+ },
305
+ {
306
+ field: "scopeOut",
307
+ reason:
308
+ "`workflows/ship.js:2961` passes it to `deniedFiles`, whose result decides an early return and then a refusal; `:3837` recomputes the denied list that bounds the sub-issues. Same position as `filesToModify` — a real branch on model-authored content, absent from `WorkflowStateSchema`, therefore unobservable rather than stable.",
309
+ },
310
+ ];
311
+
312
+ export interface CoverageFinding {
313
+ field: string;
314
+ points: BranchPoint[];
315
+ }
316
+
317
+ export interface CoverageReport {
318
+ /** Every branch point the walk found, in source order. */
319
+ points: BranchPoint[];
320
+ /** Distinct discovery properties branched on. */
321
+ branchedFields: string[];
322
+ /**
323
+ * Branched on, and classified by neither list. THE FINDING: the run takes a
324
+ * different path on this field and nobody has said whether it is allowed to
325
+ * vary.
326
+ */
327
+ undeclared: CoverageFinding[];
328
+ /**
329
+ * Declared stable with a `branchedOnBy` justification, but no condition in
330
+ * the workflow reads it any more. The justification has gone stale — the
331
+ * other direction of the same rot.
332
+ */
333
+ staleJustification: string[];
334
+ /** Branched on and deliberately excluded, with the reason already on record. */
335
+ excluded: string[];
336
+ /**
337
+ * Branched on, meets the criterion, and the state file does not carry it —
338
+ * so no series can measure it. UNMEASURED, never counted as stable.
339
+ */
340
+ unmeasurable: string[];
341
+ }
342
+
343
+ /**
344
+ * Compare the two readings and report every disagreement, in both directions.
345
+ *
346
+ * REFUSES when the declaration covers nothing: a `readAs`-less list excuses
347
+ * no branch and would report every field in the workflow as a finding, which
348
+ * reads as a catastrophic result rather than as a broken instrument.
349
+ */
350
+ export function auditBranchCoverage(
351
+ points: BranchPoint[],
352
+ stable: readonly SourceMapped[] = STABLE_DISCOVERY_FIELDS as readonly StableField[] as readonly SourceMapped[],
353
+ notAsserted: readonly SourceMapped[] = NOT_ASSERTED as readonly SourceMapped[],
354
+ unpersisted: readonly { field: string }[] = BRANCHED_BUT_UNPERSISTED,
355
+ ): CoverageReport {
356
+ const stableFields = coveredFields(stable);
357
+ const excludedFields = coveredFields(notAsserted);
358
+ const unpersistedFields = new Set(unpersisted.map(u => u.field));
359
+ if (stableFields.size === 0 && excludedFields.size === 0) {
360
+ refuse(
361
+ "neither declaration list maps to a single workflow property, so every branch would " +
362
+ "report as undeclared. That is a broken mapping, not a finding.",
363
+ );
364
+ }
365
+
366
+ const byField = new Map<string, BranchPoint[]>();
367
+ for (const point of points) {
368
+ const list = byField.get(point.field);
369
+ if (list) list.push(point);
370
+ else byField.set(point.field, [point]);
371
+ }
372
+
373
+ const branchedFields = [...byField.keys()].sort();
374
+ const undeclared: CoverageFinding[] = [];
375
+ const excluded: string[] = [];
376
+ const unmeasurable: string[] = [];
377
+ for (const field of branchedFields) {
378
+ if (stableFields.has(field)) continue;
379
+ if (excludedFields.has(field)) {
380
+ excluded.push(field);
381
+ continue;
382
+ }
383
+ if (unpersistedFields.has(field)) {
384
+ unmeasurable.push(field);
385
+ continue;
386
+ }
387
+ undeclared.push({ field, points: byField.get(field) ?? [] });
388
+ }
389
+
390
+ const staleJustification = [...stableFields].filter(f => !byField.has(f)).sort();
391
+
392
+ return { points, branchedFields, undeclared, staleJustification, excluded, unmeasurable };
393
+ }
394
+
395
+ /** The finding, as text. Never a verdict a gate silently consumes. */
396
+ export function formatCoverageReport(report: CoverageReport): string {
397
+ const lines = [
398
+ `Discovery branch-point census (#523)`,
399
+ ``,
400
+ `${report.points.length} branch read(s) over ${report.branchedFields.length} field(s): ${report.branchedFields.join(", ")}`,
401
+ ``,
402
+ ];
403
+ if (report.undeclared.length === 0) {
404
+ lines.push(`No undeclared branched field. Every field a condition reads is classified.`);
405
+ } else {
406
+ lines.push(`UNDECLARED — branched on, classified by neither list:`);
407
+ for (const finding of report.undeclared) {
408
+ lines.push(` ${finding.field}`);
409
+ for (const point of finding.points) {
410
+ lines.push(` line ${point.line} [${point.construct}] ${point.snippet}`);
411
+ }
412
+ }
413
+ }
414
+ if (report.staleJustification.length > 0) {
415
+ lines.push(
416
+ ``,
417
+ `STALE — declared stable, but no condition reads them any more: ${report.staleJustification.join(", ")}`,
418
+ );
419
+ }
420
+ if (report.unmeasurable.length > 0) {
421
+ lines.push(
422
+ ``,
423
+ `UNMEASURED — branched on, but the state file does not carry them, so no series ` +
424
+ `can read them: ${report.unmeasurable.join(", ")}. This is not a clean result for ` +
425
+ `those fields; it is the absence of one.`,
426
+ );
427
+ }
428
+ if (report.excluded.length > 0) {
429
+ lines.push(``, `Branched and deliberately not asserted: ${report.excluded.join(", ")}`);
430
+ }
431
+ return lines.join("\n");
432
+ }