rungate 0.8.0 → 0.8.2

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 (73) hide show
  1. package/gates/.gate-salt +1 -0
  2. package/gates/SCHEMA-GUIDE.md +485 -0
  3. package/gates/ac-quality.test.ts +106 -0
  4. package/gates/adversarial.test.ts +283 -0
  5. package/gates/brief-assembler.test.ts +487 -0
  6. package/gates/brief-assembler.ts +448 -0
  7. package/gates/bunfig.toml +2 -0
  8. package/gates/chain.test.ts +91 -0
  9. package/gates/e2e-smoke.test.ts +234 -0
  10. package/gates/error-classifier.test.ts +250 -0
  11. package/gates/error-classifier.ts +99 -0
  12. package/gates/gate-executor.ts +3071 -0
  13. package/gates/orchestrator.test.ts +968 -0
  14. package/gates/orchestrator.ts +827 -0
  15. package/gates/preload.ts +89 -0
  16. package/gates/prompts/ac-adversary.md +20 -0
  17. package/gates/prompts/evidence-validator.md +22 -0
  18. package/gates/prompts/prove-reproducer.md +53 -0
  19. package/gates/prompts.sha256 +3 -0
  20. package/gates/prove.test.ts +164 -0
  21. package/gates/rook-state.test.ts +108 -0
  22. package/gates/run-attribution.ts +290 -0
  23. package/gates/run-gate.ts +163 -0
  24. package/gates/schema-parity.test.ts +378 -0
  25. package/gates/schema.ts +1209 -0
  26. package/gates/self-heal.test.ts +511 -0
  27. package/gates/self-heal.ts +125 -0
  28. package/gates/ship-orchestrator.test.ts +399 -0
  29. package/gates/ship-orchestrator.ts +384 -0
  30. package/gates/spec-compliance-probe.ts +159 -0
  31. package/gates/test-fixtures/broken-no-environments.json +110 -0
  32. package/gates/test-fixtures/consumer-directory-layout.json +90 -0
  33. package/gates/test-fixtures/valid-standard.json +91 -0
  34. package/gates/test-utils.ts +43 -0
  35. package/gates/typecheck-gate.ts +111 -0
  36. package/gates/witness.ts +349 -0
  37. package/gates/workflow.test.ts +2018 -0
  38. package/hooks/BashWriteGuard.hook.ts +19 -0
  39. package/hooks/GateResultProtection.hook.ts +27 -1
  40. package/hooks/VerifyPhaseLock.hook.ts +51 -11
  41. package/hooks/WorkflowStateGuard.hook.ts +24 -0
  42. package/lib/ai-review-rounds.ts +462 -0
  43. package/lib/bash-file-read.ts +17 -3
  44. package/lib/bash-write-guard.ts +1285 -50
  45. package/lib/distribution-standing.ts +75 -4
  46. package/lib/failure-intake.ts +12 -4
  47. package/lib/file-extensions.ts +81 -0
  48. package/lib/finding-arbiter.ts +1015 -0
  49. package/lib/finding-jury.ts +537 -0
  50. package/lib/gate-enforcement.ts +171 -43
  51. package/lib/gate-result-protection.ts +12 -2
  52. package/lib/generators/code-map.ts +55 -4
  53. package/lib/generators/types.ts +27 -1
  54. package/lib/github.ts +55 -0
  55. package/lib/interpreters.ts +64 -0
  56. package/lib/issue-create-override.ts +69 -8
  57. package/lib/issue-filing-gate.ts +605 -0
  58. package/lib/js-top-level-code.ts +20 -2
  59. package/lib/junit-checks.ts +239 -1
  60. package/lib/package-closure.ts +114 -0
  61. package/lib/publish-window.ts +287 -0
  62. package/lib/scaffold/ai-review-findings.ts +142 -3
  63. package/lib/scaffold/ai-review-step.ts +1012 -18
  64. package/lib/scaffold/managed-workflow.ts +163 -4
  65. package/lib/scaffold/steps.ts +498 -22
  66. package/lib/scanner.ts +13 -4
  67. package/lib/ticked-sc-symbols.ts +361 -0
  68. package/lib/transcript-checker.ts +6 -0
  69. package/lib/workflow-actions.ts +18 -0
  70. package/package.json +3 -1
  71. package/scripts/arbitrate-finding.ts +224 -0
  72. package/scripts/generate-code-map.ts +18 -10
  73. package/scripts/sync-sc-status.ts +82 -8
@@ -0,0 +1,1209 @@
1
+ import { z } from "zod";
2
+
3
+ // The one binding that answers "which ACs already cleared their own bar on
4
+ // the pre-change tree" (#669). The schema compares the persisted list against
5
+ // it; the gate's refusal names ids out of it. A second copy here would be a
6
+ // second source of truth for one fact, and the two would disagree silently.
7
+ import { COMMIT_SHA } from "../lib/commit-sha";
8
+ import { alreadySatisfiedIds } from "../lib/evidence-prevalidator";
9
+
10
+ // ── Gate contract interfaces (SC-373) ─────────────────────────────────────
11
+
12
+ export interface SchemaValidateInput {
13
+ state: Record<string, unknown>;
14
+ }
15
+
16
+ export interface SchemaValidateResult {
17
+ valid: boolean;
18
+ issues: Array<{ path: string; message: string }>;
19
+ }
20
+
21
+ const BEHAVIORAL_PATTERN = /\b(DA should|remember to|make sure to|don't forget)\b/i;
22
+
23
+ const GARBAGE_PATTERNS = [
24
+ /^file exists?$/i,
25
+ /^it works?$/i,
26
+ /^code is (?:correct|good|done|working)$/i,
27
+ /^(?:the )?(?:feature|function|code|system) (?:works?|exists?|is (?:done|complete))$/i,
28
+ /^no errors?$/i,
29
+ /^tests? pass(?:es)?$/i,
30
+ /^changes? (?:are )?(?:made|applied|done)$/i,
31
+ ];
32
+
33
+ export const THRESHOLD_OPS = ["==", ">=", "<=", ">", "<", "!=", "contains", "exists"] as const;
34
+ export const EVIDENCE_METHOD_TYPES = ["GREP_CHECK", "FILE_EXISTS", "CURL_CHECK", "BUN_TEST", "SCREENSHOT", "PLAYWRIGHT", "COMMAND", "MANUAL", "grep", "command", "api", "screenshot", "manual"] as const;
35
+
36
+ export const ThresholdSchema = z.object({
37
+ op: z.enum(THRESHOLD_OPS),
38
+ value: z.union([z.string(), z.number()]),
39
+ unit: z.string().optional(),
40
+ });
41
+
42
+ /** One recorded change to an evidence command (#614). */
43
+ export const EvidenceRewriteSchema = z.object({
44
+ /** The site that made the change, named so a reader can go and read it. */
45
+ by: z.string(),
46
+ from: z.string(),
47
+ to: z.string(),
48
+ });
49
+
50
+ export const EvidenceMethodSchema = z.object({
51
+ type: z.enum(EVIDENCE_METHOD_TYPES),
52
+ command: z.string().optional(),
53
+ /**
54
+ * The command as the discovery agent wrote it, present once anything has
55
+ * rewritten it (#614).
56
+ *
57
+ * Three sites legitimately rewrite an evidence command — discovery's path
58
+ * normaliser, its evidence-type-ratio upgrade, and the git-ref
59
+ * qualification at the execution boundary (#118) — and each used to
60
+ * overwrite `command` in place. A reader of a broken command then had no
61
+ * way to tell a repair from a corruption, which is the question run
62
+ * `wf_c92dd0a7-fe6` cost a post-mortem to answer.
63
+ *
64
+ * Declared rather than left to `passthrough()`: an undeclared key
65
+ * round-trips through the writer and reads back exactly like a declared
66
+ * one, so the state file cannot witness that this field has a producer
67
+ * (#530).
68
+ */
69
+ authoredCommand: z.string().optional(),
70
+ /** Every change made to `command`, oldest first. */
71
+ rewrites: z.array(EvidenceRewriteSchema).optional(),
72
+ }).superRefine((em, ctx) => {
73
+ // A rewrite list with no authored form beside it is the same fail-open the
74
+ // pre-validator's `autoFixed`/`originalCommand` pairing closes: there is
75
+ // nothing to compare the current command to, so a repaired command is
76
+ // indistinguishable from one that was always written that way.
77
+ if (em.rewrites && em.rewrites.length > 0 && em.authoredCommand === undefined) {
78
+ ctx.addIssue({
79
+ code: z.ZodIssueCode.custom,
80
+ message:
81
+ "evidenceMethod records rewrites without authoredCommand — a rewrite that reports only " +
82
+ "its replacement cannot be reviewed",
83
+ path: ["authoredCommand"],
84
+ });
85
+ }
86
+ });
87
+
88
+ export const EvidenceSchema = z.object({
89
+ type: z.enum(["file-citation", "grep-output", "api-response", "screenshot", "test-output", "command-output", "manual-attestation"]),
90
+ content: z.string().optional(),
91
+ value: z.number().nullable().optional(),
92
+ url: z.string().nullable().optional(),
93
+ }).nullable().optional();
94
+
95
+ export const ContextFileSchema = z.object({
96
+ path: z.string(),
97
+ lines: z.string().optional(),
98
+ reason: z.string().optional(),
99
+ });
100
+
101
+ export const ACSchema = z.object({
102
+ id: z.string(),
103
+ type: z.enum(["CODE", "OUTCOME"]).optional(),
104
+ statement: z.string(),
105
+ specElement: z.string().optional(),
106
+ threshold: ThresholdSchema.optional(),
107
+ evidenceMethod: EvidenceMethodSchema.optional(),
108
+ contextFiles: z.array(ContextFileSchema).optional(),
109
+ evidence: EvidenceSchema,
110
+ verdict: z.enum(["PENDING", "PASS", "FAIL", "SKIP"]).optional(),
111
+ }).superRefine((ac, ctx) => {
112
+ if (!ac.threshold) {
113
+ ctx.addIssue({ code: z.ZodIssueCode.custom, message: `${ac.id}: missing threshold`, path: ["threshold"] });
114
+ }
115
+ // #339. `acs-have-type` is named by all three ceremony profiles and the
116
+ // field was `.optional()`, so an AC with no type passed the check named
117
+ // after requiring one. Refined rather than made non-optional, to match how
118
+ // `threshold` above states the same kind of rule.
119
+ //
120
+ // Safe to require: 0 of the 456 ACs across the 82 completed runs in
121
+ // ~/.rungate lack a type. This makes a check that could not fail start
122
+ // being true, not start failing.
123
+ if (!ac.type) {
124
+ ctx.addIssue({ code: z.ZodIssueCode.custom, message: `${ac.id}: missing type (CODE or OUTCOME)`, path: ["type"] });
125
+ }
126
+ if (BEHAVIORAL_PATTERN.test(ac.statement)) {
127
+ ctx.addIssue({ code: z.ZodIssueCode.custom, message: `${ac.id}: behavioral language "${ac.statement.match(BEHAVIORAL_PATTERN)?.[0]}"`, path: ["statement"] });
128
+ }
129
+ // Heuristic: minimum statement length (5 words)
130
+ const words = ac.statement.split(/\s+/).filter(Boolean);
131
+ if (words.length < 5) {
132
+ ctx.addIssue({
133
+ code: z.ZodIssueCode.custom,
134
+ message: `${ac.id}: statement too short (${words.length} words, min 5)`,
135
+ path: ["statement"],
136
+ });
137
+ }
138
+ // Heuristic: garbage/tautological statement detection
139
+ for (const pattern of GARBAGE_PATTERNS) {
140
+ if (pattern.test(ac.statement.trim())) {
141
+ ctx.addIssue({
142
+ code: z.ZodIssueCode.custom,
143
+ message: `${ac.id}: tautological/garbage statement "${ac.statement}"`,
144
+ path: ["statement"],
145
+ });
146
+ break;
147
+ }
148
+ }
149
+ // Heuristic: weak threshold detection
150
+ if (ac.threshold) {
151
+ const numVal = Number(ac.threshold.value);
152
+ if (ac.threshold.op === ">=" && !isNaN(numVal) && numVal <= 1) {
153
+ ctx.addIssue({
154
+ code: z.ZodIssueCode.custom,
155
+ message: `${ac.id}: threshold too weak (${ac.threshold.op} ${ac.threshold.value}) — effectively always passes`,
156
+ path: ["threshold"],
157
+ });
158
+ }
159
+ }
160
+ });
161
+
162
+ export const SourceSpecSchema = z.object({
163
+ path: z.string(),
164
+ citedInDiscovery: z.boolean(),
165
+ specElements: z.array(z.string()).optional(),
166
+ });
167
+
168
+ const AgentShape = {
169
+ spawned: z.boolean().optional(),
170
+ verdict: z.enum(["PASS", "FAIL", "SKIP"]).nullable().optional(),
171
+ branch: z.string().optional(),
172
+ iterations: z.number().optional(),
173
+ comparedToSpec: z.boolean().optional(),
174
+ screenshots: z.array(z.string()).optional(),
175
+ findings: z.string().nullable().optional(),
176
+ // One entry per blocking problem the agent found. Declared explicitly because
177
+ // Zod strips undeclared keys: without this line a rook FAIL round-trips through
178
+ // the schema as a verdict with no reasons attached. A FAIL verdict must carry a
179
+ // non-empty list (see gates/SCHEMA-GUIDE.md).
180
+ failures: z.array(z.string()).optional(),
181
+ testedSha: z.string().optional(),
182
+ testedPaths: z.array(z.string()).optional(),
183
+ port: z.number().optional(),
184
+ };
185
+
186
+ export const AgentSchema = z.object(AgentShape).optional();
187
+
188
+ // ── The security review's re-review cap (#171) ────────────────────────────
189
+ //
190
+ // A remediation committed after the security review leaves the run holding a
191
+ // verdict for code it no longer ships (#169). The answer is to re-review the
192
+ // new tip, and that loop — remediate, re-review, remediate — is capped.
193
+ //
194
+ // Spending the cap is its OWN outcome. The run ends with code nobody reviewed,
195
+ // which is the exact thing the #129 gate exists to stop, so it may not
196
+ // serialise to anything a reader can mistake for either of the other two: not
197
+ // "rook looked and found nothing" (a PASS), and not "rook found something" (a
198
+ // FAIL carrying findings). It gets its own verdict member and its own named
199
+ // refusal, and the superRefine below makes the three mutually exclusive at
200
+ // write time rather than by convention.
201
+ export const SECURITY_REREVIEW_EXHAUSTED = "SECURITY_REREVIEW_EXHAUSTED";
202
+
203
+ /** Rook's verdict vocabulary. EXHAUSTED is rook's alone — see above. */
204
+ export const ROOK_VERDICTS = ["PASS", "FAIL", "SKIP", "EXHAUSTED"] as const;
205
+
206
+ export const RookAgentSchema = z.object({
207
+ ...AgentShape,
208
+ verdict: z.enum(ROOK_VERDICTS).nullable().optional(),
209
+ /** The named refusal. Present only on an EXHAUSTED record. */
210
+ refusal: z.literal(SECURITY_REREVIEW_EXHAUSTED).optional(),
211
+ /** How many remediate/re-review rounds were spent before the cap ran out. */
212
+ rounds: z.number().int().positive().optional(),
213
+ }).superRefine((r, ctx) => {
214
+ if (r.verdict === "EXHAUSTED") {
215
+ if (r.refusal !== SECURITY_REREVIEW_EXHAUSTED) {
216
+ ctx.addIssue({
217
+ code: z.ZodIssueCode.custom,
218
+ message:
219
+ `agents.rook: an EXHAUSTED verdict must name its refusal — ` +
220
+ `expected refusal "${SECURITY_REREVIEW_EXHAUSTED}"`,
221
+ path: ["refusal"],
222
+ });
223
+ }
224
+ if (r.rounds === undefined) {
225
+ ctx.addIssue({
226
+ code: z.ZodIssueCode.custom,
227
+ message:
228
+ "agents.rook: an EXHAUSTED verdict must say how many rounds were spent — " +
229
+ "a cap nobody can see the size of is not a bound",
230
+ path: ["rounds"],
231
+ });
232
+ }
233
+ if (Array.isArray(r.failures) && r.failures.length > 0) {
234
+ ctx.addIssue({
235
+ code: z.ZodIssueCode.custom,
236
+ message:
237
+ "agents.rook: an EXHAUSTED verdict must not carry failures — findings are how " +
238
+ "'the review found something' is written down, and running out of attempts is not that",
239
+ path: ["failures"],
240
+ });
241
+ }
242
+ } else if (r.refusal !== undefined) {
243
+ // Without this, the exhausted outcome could be parked under a PASS while
244
+ // still recording the refusal honestly — the fail-open that every reader
245
+ // checking `verdict === "PASS"` would walk straight past.
246
+ ctx.addIssue({
247
+ code: z.ZodIssueCode.custom,
248
+ message:
249
+ `agents.rook: refusal "${SECURITY_REREVIEW_EXHAUSTED}" was recorded against ` +
250
+ `verdict ${JSON.stringify(r.verdict ?? null)} — only an EXHAUSTED verdict may carry it`,
251
+ path: ["verdict"],
252
+ });
253
+ }
254
+ }).optional();
255
+
256
+ export const EnvironmentLocalSchema = z.object({
257
+ api: z.enum(["PASS", "FAIL", "SKIP"]).nullable().optional(),
258
+ apiSkipReason: z.string().optional(),
259
+ ui: z.enum(["PASS", "FAIL", "SKIP"]).nullable().optional(),
260
+ uiSkipReason: z.string().optional(),
261
+ tests: z.enum(["PASS", "FAIL", "SKIP"]).nullable().optional(),
262
+ quinn: z.object({
263
+ port: z.number().optional(),
264
+ }).optional(),
265
+ }).optional();
266
+
267
+ export const EnvironmentProdSchema = z.object({
268
+ rebuild: z.enum(["PASS", "FAIL", "SKIP"]).nullable().optional(),
269
+ rebuildSkipReason: z.string().nullable().optional(),
270
+ smoke: z.enum(["PASS", "FAIL", "SKIP"]).nullable().optional(),
271
+ smokeSkipReason: z.string().nullable().optional(),
272
+ quinn: z.enum(["PASS", "FAIL", "SKIP"]).nullable().optional(),
273
+ quinnSkipReason: z.string().nullable().optional(),
274
+ quinnSpot: z.enum(["PASS", "FAIL", "SKIP"]).nullable().optional(),
275
+ quinnSpotSkipReason: z.string().optional(),
276
+ }).optional();
277
+
278
+ export const GateResultSchema = z.object({
279
+ result: z.enum(["PASS", "FAIL"]).nullable().optional(),
280
+ attempt: z.number().optional(),
281
+ failures: z.array(z.any()).optional(),
282
+ /**
283
+ * Every check the gate reported a verdict for, PASS and FAIL alike (#532).
284
+ *
285
+ * Optional rather than defaulted, and `lib/gate-refusal-currency.ts`
286
+ * treats its absence as "this gate says nothing about what it ran" rather
287
+ * than as "it ran nothing" — a record written by a harness older than this
288
+ * field must not be read as a gate that retired every earlier refusal.
289
+ */
290
+ checksRun: z.array(z.string()).optional(),
291
+ ts: z.string().optional(),
292
+ commitSha: z.string().optional(),
293
+ }).optional();
294
+
295
+ export const PhaseTimingEntry = z.object({
296
+ enteredTs: z.string(),
297
+ exitedTs: z.string().optional(),
298
+ iteration: z.number().optional(),
299
+ source: z.enum(["gate-runner", "DA"]),
300
+ });
301
+
302
+ export const ChangelogEntry = z.object({
303
+ ts: z.string(),
304
+ event: z.string(),
305
+ detail: z.string().optional(),
306
+ phase: z.string().optional(),
307
+ actor: z.enum(["da", "marcus", "quinn", "rook", "gate-runner", "ship-workflow"]).optional(),
308
+ });
309
+
310
+ // ── Suite measurement (#224) ──────────────────────────────────────────────
311
+ //
312
+ // A suite result that does not say which commit it ran against is a number
313
+ // whose provenance was discarded: run wf_7ac5f614-d21 published
314
+ // `regressions: 0` over a branch with a failing test, and nothing could tell,
315
+ // because there was nothing to compare the count to. So `measuredSha` is
316
+ // required, and it must be a SHA rather than a ref — "HEAD" means "whatever
317
+ // the checkout happened to be", which is the same absence of provenance in
318
+ // different words.
319
+ //
320
+ // The verdict enum has no UNMEASURED member on purpose. UNMEASURED is what
321
+ // lib/suite-measurement.ts returns for the ABSENCE of a record; writing it
322
+ // would be a measurement asserting there was no measurement, and would give a
323
+ // caller a way to park an unmeasured run in the field that is supposed to
324
+ // prove the suite ran.
325
+ // ONE binding, in lib/commit-sha.ts. `harness.sha` below asks the same
326
+ // question of a different field, and a second copy would be two deciders
327
+ // that agree (#602).
328
+ const MEASURED_SHA = COMMIT_SHA;
329
+
330
+ const SuiteMeasurementShape = {
331
+ // #673 — three words, and `PARTIAL` is not a third result. It says the
332
+ // reading was taken over something smaller than the suite, which
333
+ // `readSuiteMeasurement` resolves to UNMEASURED by name, so no gate can
334
+ // act on it. `UNMEASURED` itself is still not writable: recording it would
335
+ // be a measurement saying there was no measurement.
336
+ verdict: z.enum(["PASS", "FAIL", "PARTIAL"]),
337
+ measuredSha: z.string().regex(MEASURED_SHA, "measuredSha must be a commit SHA (7-40 hex), not a ref name"),
338
+ failures: z.number().int().nonnegative(),
339
+ measuredAt: z.string().optional(),
340
+ // #490 — what the run covered, beside what it found. A verdict with no
341
+ // coverage beside it cannot tell `0 fail` over 324 files from `0 fail` over
342
+ // one empty one, and both print the same summary.
343
+ //
344
+ // `.nullable()`, and the recorder writes null rather than omitting the key
345
+ // when a runner does not report a count: absent means "a harness older than
346
+ // this field", null means "this runner was asked and did not say", and 0
347
+ // means "it said none". Collapsing those is the defect one level down.
348
+ tests: z.number().int().nonnegative().nullable().optional(),
349
+ files: z.number().int().positive().nullable().optional(),
350
+ // #673 — `tests` is the COLLECTED total and `ran` is `pass + fail`. On run
351
+ // `wf_62d68d55-81c` those were 13915 and 13084, the changelog carried one
352
+ // and this record carried the other, and nothing said which was which. The
353
+ // difference is exactly `skip + todo`, so the three are recorded beside the
354
+ // total and a reader never has to subtract to find out what a number means.
355
+ //
356
+ // `ran` is always a number on a measured run — it is `pass + fail`, and a
357
+ // run with neither is refused upstream. `skip` and `todo` are `.nullable()`
358
+ // for the reason `tests` and `files` are: a runner that reports no skip
359
+ // count and a runner that skipped none are opposite facts, and `0` is the
360
+ // value that would let a reader add them together. Absent on all three
361
+ // means "recorded by a harness older than #673".
362
+ ran: z.number().int().nonnegative().optional(),
363
+ skip: z.number().int().nonnegative().nullable().optional(),
364
+ todo: z.number().int().nonnegative().nullable().optional(),
365
+ // #323 — the names beside the count. `failures` is a number, and the
366
+ // refusal two fields up says "a FAIL must name at least one" while naming
367
+ // nothing. A schema is a FILTER (#646): a recorder that writes these and a
368
+ // schema that does not declare them is a record that silently loses them.
369
+ //
370
+ // The list may be SHORTER than `failures` and that is not a contradiction:
371
+ // a module-scope error counts toward the total and prints no test name,
372
+ // because the test that would carry it never ran. `describeSuiteFailures`
373
+ // in lib/suite-run-reading.ts is the one place that says so in words.
374
+ failingTests: z.array(z.string()).optional(),
375
+ errors: z.number().int().nonnegative().nullable().optional(),
376
+ // #323 SC-4 — how much work the run did, beside what it found.
377
+ //
378
+ // The 2026-10-11 series this issue is about left exactly one usable lead:
379
+ // the run that failed executed 384 more assertions than either clean run,
380
+ // against an almost identical test count. Nobody could say so at the time,
381
+ // because the number lived in a terminal scrollback. Recorded, it is a
382
+ // number a reader can compare across two PRs.
383
+ //
384
+ // `.nullable()`, for the reason `tests` gives above: absent means a
385
+ // harness older than this field, null means the runner was asked and did
386
+ // not say, and a number means it said. No gate reads it — a run executing
387
+ // more assertions than the one before it is not a failure.
388
+ expectCalls: z.number().int().nonnegative().nullable().optional(),
389
+ };
390
+
391
+ /**
392
+ * The field names the measurement carries, exported so gates/schema-parity.test.ts
393
+ * can check gates/SCHEMA-GUIDE.md against the schema in both directions — a
394
+ * field added here and left undocumented turns that test red.
395
+ */
396
+ export const SUITE_MEASUREMENT_FIELDS = Object.keys(SuiteMeasurementShape);
397
+
398
+ export const SuiteMeasurementSchema = z.object(SuiteMeasurementShape).superRefine((m, ctx) => {
399
+ // A verdict its own count contradicts is not a result in either direction,
400
+ // and the write path is where that is cheapest to stop.
401
+ if (m.verdict === "PASS" && m.failures > 0) {
402
+ ctx.addIssue({
403
+ code: z.ZodIssueCode.custom,
404
+ message: `suiteMeasurement: PASS with ${m.failures} failing test(s) — a PASS must carry zero failures`,
405
+ path: ["failures"],
406
+ });
407
+ }
408
+ if (m.verdict === "FAIL" && m.failures === 0) {
409
+ ctx.addIssue({
410
+ code: z.ZodIssueCode.custom,
411
+ message: "suiteMeasurement: FAIL with no failing tests — a FAIL must name at least one",
412
+ path: ["failures"],
413
+ });
414
+ }
415
+ // #490. `files: z.number().positive()` refuses a run over no files, and on
416
+ // its own that would be the PROXY enforced in place of the property: one
417
+ // empty file satisfies it and measures nothing. A recorded `tests: 0` is
418
+ // the property, and it is the shape this field exists to make visible.
419
+ if (m.tests === 0) {
420
+ ctx.addIssue({
421
+ code: z.ZodIssueCode.custom,
422
+ message:
423
+ 'suiteMeasurement: a record carrying "tests": 0 is not a measurement — a runner that ' +
424
+ "discovered nothing to run exits exactly like a clean suite (#490)",
425
+ // Worded so it cannot be mistaken for `lib/suite-run-reading.ts`'s
426
+ // refusal, which says "executed 0 tests". The two are a legitimate
427
+ // pair — this one also catches a state the recorder did not produce —
428
+ // but a test asserting on the reading's sentence must not be able to
429
+ // pass on this one's. Measured: with identical wording, disabling the
430
+ // reading's refusal left two rows green that exist to witness it.
431
+ path: ["tests"],
432
+ });
433
+ }
434
+ });
435
+
436
+ // ── Evidence pre-validation (#235) ────────────────────────────────────────
437
+ //
438
+ // The scope gate dry-runs every AC's evidence command before Marcus runs. That
439
+ // result used to exist only as stdout from a promise nobody awaited: the gate
440
+ // wrote workflow-state.json, started the gate tests, and the verdict arrived
441
+ // afterwards into a log. A reading no later check can read is not a check.
442
+ //
443
+ // Unlike suiteMeasurement, UNMEASURED IS writable here, and the difference is
444
+ // deliberate. There, a recorded UNMEASURED would be a way to park an unmeasured
445
+ // run in the field that proves the suite ran. Here the failure mode runs the
446
+ // other way: a pre-validation that threw and a pre-validation that found
447
+ // nothing wrong both used to leave the field empty, and a reader cannot tell
448
+ // an absent field from a clean one. So a throw is recorded, with its reason,
449
+ // and absence keeps its own meaning — nobody got as far as measuring.
450
+ export const PREVALIDATION_VERDICTS = ["PASS", "FAIL", "UNMEASURED"] as const;
451
+ export const PREVALIDATION_AC_STATUSES = ["ok", "broken", "empty", "skipped"] as const;
452
+
453
+ export const BASELINE_VERDICTS = ["MEASURED", "UNMEASURED"] as const;
454
+
455
+ /**
456
+ * Which harness checkout graded this run (#602).
457
+ *
458
+ * `UNMEASURED` IS writable here, for `evidencePrevalidation`'s reason and
459
+ * not `suiteMeasurement`'s: there, a recorded UNMEASURED would be a way to
460
+ * park an unmeasured run in the field that proves the suite ran. Here the
461
+ * failure mode runs the other way — a harness whose SHA could not be read
462
+ * and a harness nobody asked about both leave the field absent, and a
463
+ * reader cannot tell them apart. So a failed reading is recorded with its
464
+ * reason, and absence keeps its own meaning: a run from before this field
465
+ * existed, or one that never got as far as asking.
466
+ *
467
+ * `sha` reuses `MEASURED_SHA`, which is `COMMIT_SHA` from lib/commit-sha.ts
468
+ * — ONE binding, because `measuredSha` above asks the same question of a
469
+ * different field and two copies would be two deciders that agree.
470
+ *
471
+ * The contradictions below are refused for the same reason the baseline's
472
+ * are: a verdict that disagrees with the fields beside it lets a reader
473
+ * pick whichever half suits them.
474
+ */
475
+ export const HarnessSchema = z.object({
476
+ reading: z.enum(["MEASURED", "UNMEASURED"]),
477
+ sha: z.string().regex(MEASURED_SHA, "harness.sha must be a commit SHA (7-40 hex), not a ref name").nullable(),
478
+ branch: z.string().nullable(),
479
+ dirty: z.array(z.string()),
480
+ // null is NOT zero: a checkout with no upstream is one nobody can say
481
+ // anything about, and 0 would be the silent default (#602).
482
+ behind: z.number().int().nonnegative().nullable(),
483
+ behindReason: z.string().nullable(),
484
+ reason: z.string().nullable(),
485
+ }).superRefine((h, ctx) => {
486
+ if (h.reading === "UNMEASURED") {
487
+ if (!h.reason) {
488
+ ctx.addIssue({
489
+ code: z.ZodIssueCode.custom,
490
+ message: "harness: UNMEASURED with no reason — an absence nobody can explain is not actionable",
491
+ });
492
+ }
493
+ if (h.sha !== null) {
494
+ ctx.addIssue({
495
+ code: z.ZodIssueCode.custom,
496
+ message: `harness: UNMEASURED while naming a SHA (${h.sha}) — a reading that could not be taken has no SHA to report`,
497
+ });
498
+ }
499
+ return;
500
+ }
501
+ if (h.sha === null) {
502
+ ctx.addIssue({
503
+ code: z.ZodIssueCode.custom,
504
+ message: "harness: MEASURED with no SHA — the SHA is the measurement",
505
+ });
506
+ }
507
+ if (h.reason !== null) {
508
+ ctx.addIssue({
509
+ code: z.ZodIssueCode.custom,
510
+ message: `harness: MEASURED while carrying a failure reason (${h.reason}) — one of the two is wrong`,
511
+ });
512
+ }
513
+ // `behind` and `behindReason` are the same pair one level down: exactly
514
+ // one of them says what happened.
515
+ if ((h.behind === null) === (h.behindReason === null)) {
516
+ ctx.addIssue({
517
+ code: z.ZodIssueCode.custom,
518
+ message:
519
+ h.behind === null
520
+ ? "harness: behind is null with no behindReason — a number nobody could read must say why"
521
+ : `harness: behind is ${h.behind} AND behindReason is set — a count and an excuse for not counting`,
522
+ });
523
+ }
524
+ });
525
+
526
+ /**
527
+ * The threshold as the AC wrote it, copied into the baseline (#669).
528
+ *
529
+ * Loose on purpose — it is a RECORD of what was there, not a second place
530
+ * that decides what a valid threshold is. `ThresholdSchema` above is that
531
+ * place, and a baseline refusing a threshold the AC schema accepted would be
532
+ * two deciders for one question.
533
+ */
534
+ export const BaselineThresholdSchema = z.object({
535
+ op: z.string().optional(),
536
+ value: z.union([z.string(), z.number()]).optional(),
537
+ unit: z.string().optional(),
538
+ });
539
+
540
+ /**
541
+ * What an AC's evidence command printed on the pre-change tree, beside the
542
+ * bar it will be judged against (#669).
543
+ *
544
+ * The contradictions below are refused for the same reason the reading's own
545
+ * `UNMEASURED with no reason` is: an absence nobody can explain is not
546
+ * actionable, and a verdict that disagrees with the fields beside it lets a
547
+ * reader pick whichever half suits them.
548
+ */
549
+ export const BaselineSchema = z.object({
550
+ verdict: z.enum(BASELINE_VERDICTS),
551
+ output: z.string(),
552
+ reason: z.string().nullable(),
553
+ threshold: BaselineThresholdSchema.nullable(),
554
+ satisfiesThreshold: z.boolean().nullable(),
555
+ }).superRefine((b, ctx) => {
556
+ if (b.verdict === "UNMEASURED") {
557
+ if (!b.reason) {
558
+ ctx.addIssue({
559
+ code: z.ZodIssueCode.custom,
560
+ message:
561
+ "baseline: UNMEASURED with no reason — an absence nobody can explain is not actionable",
562
+ path: ["reason"],
563
+ });
564
+ }
565
+ if (b.satisfiesThreshold !== null) {
566
+ ctx.addIssue({
567
+ code: z.ZodIssueCode.custom,
568
+ message:
569
+ `baseline: UNMEASURED carrying satisfiesThreshold=${b.satisfiesThreshold} — an output ` +
570
+ "nobody could read was reduced to a threshold comparison, which is how " +
571
+ "`bun test v1.3.14 (d1632b29)` once counted as evidence",
572
+ path: ["satisfiesThreshold"],
573
+ });
574
+ }
575
+ return;
576
+ }
577
+ if (b.reason !== null) {
578
+ ctx.addIssue({
579
+ code: z.ZodIssueCode.custom,
580
+ message: "baseline: reason is only for UNMEASURED — a measured output explains itself",
581
+ path: ["reason"],
582
+ });
583
+ }
584
+ if (b.output.trim().length === 0) {
585
+ ctx.addIssue({
586
+ code: z.ZodIssueCode.custom,
587
+ message:
588
+ "baseline: MEASURED with no output — a command that printed nothing measured nothing",
589
+ path: ["output"],
590
+ });
591
+ }
592
+ if (b.satisfiesThreshold !== null && b.threshold === null) {
593
+ ctx.addIssue({
594
+ code: z.ZodIssueCode.custom,
595
+ message:
596
+ "baseline: satisfiesThreshold recorded against no threshold — there was no bar to clear",
597
+ path: ["satisfiesThreshold"],
598
+ });
599
+ }
600
+ });
601
+
602
+ export const PrevalidatedACSchema = z.object({
603
+ id: z.string(),
604
+ status: z.enum(PREVALIDATION_AC_STATUSES),
605
+ // The pre-change reading (#669). Optional: a reading written before the
606
+ // field existed still validates, the same amnesty `broken` and `takenAt`
607
+ // have.
608
+ baseline: BaselineSchema.optional(),
609
+ autoFixed: z.boolean().optional(),
610
+ originalCommand: z.string().optional(),
611
+ fixedCommand: z.string().optional(),
612
+ needsRewrite: z.boolean().optional(),
613
+ diagnostic: z.string().optional(),
614
+ }).superRefine((ac, ctx) => {
615
+ // An auto-fix that reports only its replacement cannot be reviewed: there is
616
+ // nothing to compare it to, and a repaired command is indistinguishable from
617
+ // one that was always written that way.
618
+ if (ac.autoFixed) {
619
+ for (const field of ["originalCommand", "fixedCommand"] as const) {
620
+ if (!ac[field]) {
621
+ ctx.addIssue({
622
+ code: z.ZodIssueCode.custom,
623
+ message: `${ac.id}: autoFixed without ${field} — an auto-fix must carry both the original and the fixed command`,
624
+ path: [field],
625
+ });
626
+ }
627
+ }
628
+ }
629
+ });
630
+
631
+ /**
632
+ * Which gate took the reading. Optional: a reading written before #264 has no
633
+ * answer.
634
+ *
635
+ * In phase order, which is what `shouldRetakePrevalidation` and
636
+ * `prevalidationViolations` both read. `ship` joined the list in #280, where
637
+ * the ship gate was found consuming whatever block the verify gate left
638
+ * behind — on run `wf_ea3e428f-64f` a reading an hour old that disagreed with
639
+ * the tree by four ACs.
640
+ */
641
+ export const PREVALIDATION_SOURCES = ["scope", "verify", "ship"] as const;
642
+
643
+ export type PrevalidationSource = (typeof PREVALIDATION_SOURCES)[number];
644
+
645
+ const EvidencePrevalidationShape = {
646
+ verdict: z.enum(PREVALIDATION_VERDICTS),
647
+ checkedAt: z.string(),
648
+ acs: z.array(PrevalidatedACSchema),
649
+ // The ids a FAIL refuses for (#274).
650
+ //
651
+ // `prevalidationViolations` in gates/workflow.test.ts — the single site that
652
+ // turns this reading into a refusal — names the ACs to fix out of this key,
653
+ // and no writer produced it until #274. So every genuine FAIL refused with
654
+ // "no broken AC ids were recorded", which is true of the key and false of
655
+ // the reading: the per-AC results were under `acs` all along. Fail-closed,
656
+ // so nothing shipped that should not have, but a refusal that cannot name
657
+ // what to fix costs the heal loop a round and teaches it nothing.
658
+ //
659
+ // Optional, so a reading written before this field existed still validates —
660
+ // the same compatibility `takenAt` has. It is NOT optional on a FAIL: the
661
+ // superRefine below requires it there, because that is the only verdict
662
+ // whose whole job is to name something.
663
+ broken: z.array(z.string()).optional(),
664
+ // The ids whose pre-change output already satisfied their own threshold
665
+ // (#669).
666
+ //
667
+ // Derived from the baselines under `acs`, never supplied, and cross-checked
668
+ // below in both directions: a list that disagrees with its own results is
669
+ // refused, and a reading that omits the key while its results carry a
670
+ // satisfied baseline is refused too. Optional only so a reading written
671
+ // before the field existed still validates — those carry no baselines, so
672
+ // the derived list is empty and the absence agrees with it.
673
+ alreadySatisfied: z.array(z.string()).optional(),
674
+ reason: z.string().nullable(),
675
+ // Which gate measured this (#264).
676
+ //
677
+ // "A reading exists" cannot separate two cases that want opposite treatment
678
+ // on the next verify attempt: the scope gate measured this run's STARTING
679
+ // conditions, which re-measuring after Marcus has run would answer a
680
+ // different question; or a previous verify attempt measured it, in which
681
+ // case freezing that reading means no heal round can ever clear a refusal.
682
+ // #261 could not tell them apart and froze both, so run wf_c71f950f-c88
683
+ // spent four verify attempts judged against one reading taken in the wrong
684
+ // directory, with all six of its ACs passing.
685
+ //
686
+ // Optional, so a reading written before this field existed still validates
687
+ // and still behaves exactly as it did — absent is treated as "not verify",
688
+ // which preserves it.
689
+ takenAt: z.enum(PREVALIDATION_SOURCES).optional(),
690
+ };
691
+
692
+ /**
693
+ * The field names the reading carries, exported so the parity test in
694
+ * test/unit/evidence-prevalidation-gate.test.ts can check gates/SCHEMA-GUIDE.md
695
+ * against the schema in both directions.
696
+ */
697
+ export const EVIDENCE_PREVALIDATION_FIELDS = Object.keys(EvidencePrevalidationShape);
698
+
699
+ export const EvidencePrevalidationSchema = z.object(EvidencePrevalidationShape).superRefine((r, ctx) => {
700
+ const broken = r.acs.filter((ac) => ac.status === "broken");
701
+
702
+ // `broken` is DERIVED, so it is checked against what it claims to summarise
703
+ // rather than taken on its word (#274). A list a writer could set
704
+ // independently of `acs` is a second source of truth for the same fact, and
705
+ // the reader — the gate's refusal — would name whichever one was wrong.
706
+ const named = r.broken;
707
+ if (named !== undefined) {
708
+ const measured = broken.map((ac) => ac.id);
709
+ const differs =
710
+ named.length !== measured.length || named.some((id, i) => id !== measured[i]);
711
+ if (differs) {
712
+ ctx.addIssue({
713
+ code: z.ZodIssueCode.custom,
714
+ message:
715
+ `evidencePrevalidation: broken names [${named.join(", ")}] but the results classify ` +
716
+ `[${measured.join(", ")}] broken — a derived list that disagrees with its own results ` +
717
+ `is a second source of truth, and the refusal would name the wrong AC`,
718
+ path: ["broken"],
719
+ });
720
+ }
721
+ } else if (r.verdict === "FAIL") {
722
+ ctx.addIssue({
723
+ code: z.ZodIssueCode.custom,
724
+ message:
725
+ "evidencePrevalidation: FAIL with no `broken` list — the gate's refusal names the ACs to " +
726
+ "fix out of this field, and a FAIL that names none costs a heal round and teaches it nothing",
727
+ path: ["broken"],
728
+ });
729
+ }
730
+
731
+ // #669 — the vacuous-AC list, held to its own results the same way.
732
+ const satisfied = alreadySatisfiedIds(r.acs);
733
+ if (r.alreadySatisfied !== undefined) {
734
+ const named = r.alreadySatisfied;
735
+ const differs =
736
+ named.length !== satisfied.length || named.some((id, i) => id !== satisfied[i]);
737
+ if (differs) {
738
+ ctx.addIssue({
739
+ code: z.ZodIssueCode.custom,
740
+ message:
741
+ `evidencePrevalidation: alreadySatisfied names [${named.join(", ")}] but the baselines ` +
742
+ `classify [${satisfied.join(", ")}] as already satisfied — the gate's refusal would ` +
743
+ "name the wrong AC",
744
+ path: ["alreadySatisfied"],
745
+ });
746
+ }
747
+ } else if (satisfied.length > 0) {
748
+ ctx.addIssue({
749
+ code: z.ZodIssueCode.custom,
750
+ message:
751
+ `evidencePrevalidation: ${satisfied.length} AC baseline(s) already satisfy their own ` +
752
+ "threshold and the reading names none — a vacuous AC that nothing records is one " +
753
+ "nothing can refuse",
754
+ path: ["alreadySatisfied"],
755
+ });
756
+ }
757
+
758
+ if (r.verdict === "FAIL" && broken.length === 0) {
759
+ ctx.addIssue({
760
+ code: z.ZodIssueCode.custom,
761
+ message: "evidencePrevalidation: FAIL with no broken evidence command — a FAIL must name at least one",
762
+ path: ["acs"],
763
+ });
764
+ }
765
+ if (r.verdict === "PASS" && broken.length > 0) {
766
+ ctx.addIssue({
767
+ code: z.ZodIssueCode.custom,
768
+ message: `evidencePrevalidation: PASS with ${broken.length} broken evidence command(s) — a PASS must carry none`,
769
+ path: ["acs"],
770
+ });
771
+ }
772
+ if (r.verdict === "UNMEASURED") {
773
+ if (!r.reason) {
774
+ ctx.addIssue({
775
+ code: z.ZodIssueCode.custom,
776
+ message: "evidencePrevalidation: UNMEASURED with no reason — an absence nobody can explain is not actionable",
777
+ path: ["reason"],
778
+ });
779
+ }
780
+ if (r.acs.length > 0) {
781
+ ctx.addIssue({
782
+ code: z.ZodIssueCode.custom,
783
+ message: `evidencePrevalidation: UNMEASURED with ${r.acs.length} AC result(s) — results mean it was measured`,
784
+ path: ["acs"],
785
+ });
786
+ }
787
+ } else if (r.reason !== null) {
788
+ ctx.addIssue({
789
+ code: z.ZodIssueCode.custom,
790
+ message: "evidencePrevalidation: reason is only for UNMEASURED — a measured verdict explains itself through its ACs",
791
+ path: ["reason"],
792
+ });
793
+ }
794
+ });
795
+
796
+ export const WorkflowStateSchema = z.object({
797
+ schemaVersion: z.literal(2),
798
+ issue: z.number(),
799
+ repo: z.string().optional(),
800
+ issueRepo: z.string().optional(),
801
+ projectRoot: z.string().optional(),
802
+
803
+ /**
804
+ * The tree a gate check must MEASURE, as opposed to `projectRoot`, which is
805
+ * where configuration is READ from (#314).
806
+ *
807
+ * On a worktree-isolated run these differ: `projectRoot` is the main
808
+ * checkout, already merged and green by construction, while the change under
809
+ * test lives in `.claude/worktrees/<run>-N`. Eight checks executed commands
810
+ * against `projectRoot` and therefore measured the wrong tree — `tsc-pass`
811
+ * typechecked `main`, `code-committed` ran `git status` on a checkout the
812
+ * work was never in, and `code-pushed` asked whether `main` was ahead of its
813
+ * upstream. All three passed unconditionally.
814
+ *
815
+ * ship.js writes this whenever it establishes the commit directory. Absent is
816
+ * a refusal rather than a fallback to `projectRoot`: falling back is exactly
817
+ * the behaviour being removed, and it is indistinguishable from a correct
818
+ * measurement.
819
+ */
820
+ treeUnderTest: z.string().optional(),
821
+
822
+ /**
823
+ * Every worktree this run built in, so a gate can read each one's `origin`
824
+ * off the disk (#414, follow-up to #218).
825
+ *
826
+ * `treeUnderTest` names ONE tree. A decomposed run has one worktree per
827
+ * sub-issue, and the #218 incident was a second agent landing in a
828
+ * different checkout while the first was correct — so checking only the
829
+ * tree under test reads the right answer off the wrong worktree.
830
+ *
831
+ * `reportedRepo` is what the AGENT said `git remote get-url origin`
832
+ * printed. It is recorded, not trusted: the gate compares the disk, and
833
+ * keeping the reply beside it is what lets the refusal distinguish "the
834
+ * worktree is in the wrong place" from "the reply was right and the
835
+ * checkout disagrees". The second is the case the ship workflow
836
+ * structurally cannot see, because the reply is the only remote it has.
837
+ *
838
+ * Absent is not a pass — `worktreeRepoViolations` refuses an empty list,
839
+ * because every run reaching this gate has at least a tree under test.
840
+ */
841
+ worktrees: z.array(z.object({
842
+ path: z.string(),
843
+ reportedRepo: z.string().optional(),
844
+ })).optional(),
845
+
846
+ slug: z.string(),
847
+ phase: z.enum(["GOAL", "DISCOVERY", "SCOPE", "BUILD", "VERIFY", "SHIP", "DONE", "CIRCUIT_BREAK"]),
848
+ issueGoal: z.string().min(1, "issueGoal cannot be empty"),
849
+
850
+ sourceSpecs: z.array(SourceSpecSchema).optional(),
851
+
852
+ sizing: z.object({
853
+ predicted: z.enum(["XS", "S", "M", "L"]).optional(),
854
+ ceremonyTier: z.enum(["LIGHT", "STANDARD", "THOROUGH"]).optional(),
855
+ actualFiles: z.number().optional(),
856
+ actualMinutes: z.number().optional(),
857
+ }).optional(),
858
+
859
+ acs: z.array(ACSchema),
860
+
861
+ /**
862
+ * Dev- and prod-server liveness as the prove gate measured it, or did not
863
+ * (#304).
864
+ *
865
+ * `UNMEASURED` is a first-class status, not an absence. The prove gate used
866
+ * to `process.exit(1)` when a server did not answer at a route hardcoded
867
+ * into the harness; the route is read from `dev.healthPath` now, and a
868
+ * consumer that has not set one cannot be probed. Reporting DOWN for that
869
+ * consumer is a false FAIL on a healthy server, so the gate does not refuse
870
+ * — which means the gap has to be written down somewhere durable, or
871
+ * relaxing the refusal is a silent fail-open.
872
+ *
873
+ * Nothing refuses on this yet; #346 defines the refusal that should.
874
+ */
875
+ liveness: z.array(z.object({
876
+ tier: z.string(),
877
+ status: z.enum(["UP", "DOWN", "UNMEASURED"]),
878
+ detail: z.string(),
879
+ })).optional(),
880
+
881
+ governingSpec: z.object({
882
+ path: z.string(),
883
+ detectedFrom: z.string().optional(),
884
+ }).optional(),
885
+
886
+ agents: z.object({
887
+ marcus: AgentSchema,
888
+ quinn: AgentSchema,
889
+ rook: RookAgentSchema,
890
+ }).optional(),
891
+
892
+ environments: z.object({
893
+ local: EnvironmentLocalSchema,
894
+ prod: EnvironmentProdSchema,
895
+ }).optional(),
896
+
897
+ gates: z.object({
898
+ scope: GateResultSchema,
899
+ verify: GateResultSchema,
900
+ ship: GateResultSchema,
901
+ }).optional(),
902
+
903
+ iterationCount: z.number().optional(),
904
+ startTs: z.string().optional(),
905
+ updatedTs: z.string().optional(),
906
+
907
+ phaseTimings: z.record(z.string(), z.array(PhaseTimingEntry)).optional(),
908
+
909
+ gateContract: z.object({
910
+ /**
911
+ * How many tests each file declared at the last gate run (#307 SC-A19).
912
+ *
913
+ * Carried across gate runs so a heal round that deletes a test is
914
+ * visible to the re-run that follows it. Not banked when a regression
915
+ * is found — see `nextCensus`.
916
+ */
917
+ testCensus: z.record(z.string(), z.number()).optional(),
918
+ /**
919
+ * The gate's HMAC over `testCensus` and the run's slug (#494).
920
+ *
921
+ * Declared because a `z.object` is a FILTER, not a description: a field
922
+ * the schema does not name is stripped from every parsed state, so an
923
+ * undeclared signature would reach the next gate run looking exactly
924
+ * like one an agent had deleted.
925
+ *
926
+ * `.optional()` on purpose, and it is not a hole. Making it required
927
+ * would refuse the state file rather than report the erasure, which
928
+ * turns a detectable tamper into a crashed run — and the heal agent
929
+ * writes this file through `writeWorkflowState`, so the refusal would
930
+ * land on the wrong party. The detection is in `readPersistedCensus`
931
+ * and `censusVerdict`, where an absent signature beside an existing
932
+ * witness reads UNMEASURED.
933
+ */
934
+ testCensusSignature: z.string().optional(),
935
+ /**
936
+ * Which reader took `testCensus` — `TEST_CENSUS_READER` (#883).
937
+ *
938
+ * Declared for the same reason the signature is: a `z.object` is a
939
+ * FILTER, so an undeclared stamp would be stripped on every parse and
940
+ * every round would look like a reader change.
941
+ *
942
+ * Absent means the pre-#883 reader, which is the whole point: a banked
943
+ * census with no stamp was taken by an instrument that counted prose
944
+ * and missed `test.each`, so its numbers are not comparable with this
945
+ * one's. `censusVerdict` reads that as UNMEASURED rather than as a
946
+ * regression, and the round banks the new reading so the NEXT one
947
+ * compares like with like.
948
+ */
949
+ testCensusReader: z.string().optional(),
950
+ environments: z.any().optional(),
951
+ verdicts: z.any().optional(),
952
+ evidence: z.any().optional(),
953
+ baselines: z.object({
954
+ testBaseline: z.number().optional(),
955
+ /**
956
+ * Why no number is recorded (#307). Present exactly when `testBaseline`
957
+ * is absent, and never beside it: a reason sitting next to a `0` would
958
+ * let `?? 0` keep reading the run as a measured clean tree, which is
959
+ * the defect the reason exists to report.
960
+ */
961
+ testBaselineUnmeasured: z.string().optional(),
962
+ tscBaseline: z.number().optional(),
963
+ }).optional(),
964
+ }).optional(),
965
+
966
+ changelog: z.array(ChangelogEntry).optional(),
967
+
968
+ verifyBlockers: z.array(z.object({
969
+ id: z.string(),
970
+ description: z.string(),
971
+ fixCommit: z.string().optional(),
972
+ quinnReverified: z.boolean().default(false),
973
+ })).optional(),
974
+
975
+ /**
976
+ * What this run decided to measure, and what it decided not to (#251).
977
+ *
978
+ * A finished run showing six ACs is ambiguous: six because the issue had
979
+ * six criteria, or six because one was dropped? Run wf_e105dd33-220 was the
980
+ * second, and nothing anywhere recorded it. `deferrals` is the answer, and
981
+ * `uncovered` must be empty on any run that got past discovery — a
982
+ * non-empty one is a run that shipped against criteria it never measured.
983
+ */
984
+ acCoverage: z.object({
985
+ criteriaCount: z.number(),
986
+ acCount: z.number(),
987
+ covered: z.array(z.string()),
988
+ deferrals: z.array(z.object({
989
+ specElement: z.string(),
990
+ reason: z.string(),
991
+ subIssue: z.number().optional(),
992
+ })),
993
+ uncovered: z.array(z.string()),
994
+ }).nullable().optional(),
995
+
996
+ /**
997
+ * Which run wrote this file (#288).
998
+ *
999
+ * `WORK_DIR` is keyed by slug, so every run of one issue writes into one
1000
+ * directory. Without this a reader cannot tell a live run's state file from
1001
+ * the previous night's — and on 2026-10-13 a healthy #254 run was cancelled
1002
+ * on exactly that misreading. `gates/run-attribution.ts` compares it against
1003
+ * the directory's `run.json` marker; a disagreement reads as MIXED.
1004
+ */
1005
+ runId: z.string().optional(),
1006
+
1007
+ /**
1008
+ * The prior branch this run adopted work from, as detection reported it
1009
+ * (#288). Null means detection ran and found none; absent means nobody
1010
+ * looked.
1011
+ *
1012
+ * ship.js has passed this to `initWorkflow` since the field existed and
1013
+ * nothing persisted it — the call is assembled into a `bun -e` template
1014
+ * string, so TypeScript never saw the excess property and the drop was
1015
+ * silent. It is why #185 and #223 each had to reconstruct prior-branch
1016
+ * detection from scratch to investigate it.
1017
+ */
1018
+ priorWork: z.object({
1019
+ branch: z.string().optional(),
1020
+ refName: z.string().optional(),
1021
+ commitCount: z.number().nullable().optional(),
1022
+ acStatus: z.array(z.object({
1023
+ id: z.string(),
1024
+ status: z.string(),
1025
+ evidence: z.string().optional(),
1026
+ })).optional(),
1027
+ }).passthrough().nullable().optional(),
1028
+
1029
+ /**
1030
+ * Where each AC's verdict came from: earned by this run, or adopted from a
1031
+ * prior branch (#288).
1032
+ *
1033
+ * A run that inherited six passing ACs and a run that implemented six
1034
+ * passing ACs produce the same artefact without it. Every AC in the prior
1035
+ * work's list is labelled, because an absent entry is what an AC nobody
1036
+ * classified looks like.
1037
+ */
1038
+ acProvenance: z.record(z.object({
1039
+ source: z.enum(["adopted", "this-run"]),
1040
+ branch: z.string().optional(),
1041
+ })).optional(),
1042
+
1043
+ bootstrappedFrom: z.string().optional(),
1044
+ beforeState: z.object({
1045
+ type: z.enum(["text", "screenshot", "api", "data", "none"]),
1046
+ path: z.string().nullable(),
1047
+ capturedAt: z.string(),
1048
+ description: z.string().optional(),
1049
+ }).optional(),
1050
+
1051
+ issueType: z.enum(["feature", "bug-fix", "bug", "refactor", "chore"]).optional(),
1052
+ rca: z.object({
1053
+ rootCause: z.string().optional(),
1054
+ prediction: z.string().optional(),
1055
+ predictionVerified: z.boolean().optional(),
1056
+ }).optional(),
1057
+
1058
+ blastRadius: z.object({
1059
+ filesRead: z.number(),
1060
+ filesChanged: z.number(),
1061
+ }).optional(),
1062
+
1063
+ foundIssues: z.array(z.object({
1064
+ description: z.string(),
1065
+ disposition: z.enum(["fixed", "filed", "scoped-out"]).optional(),
1066
+ issueNumber: z.number().optional(),
1067
+ })).optional(),
1068
+
1069
+ filesChangedOutsideBrief: z.array(z.string()).optional(),
1070
+
1071
+ conformityFindings: z.any().optional(),
1072
+
1073
+ preExistingFailures: z.array(z.string()).optional(),
1074
+
1075
+ /**
1076
+ * The commit the run built and measured. Written by
1077
+ * `scripts/record-build-commit.ts`.
1078
+ *
1079
+ * Read at the ship gate (`gates/workflow.test.ts`) to decide whether the run
1080
+ * has a commit at all, and undeclared until #317 — a field that gates
1081
+ * shipping was not in the contract describing the state it is shipped from.
1082
+ */
1083
+ buildCommit: z.string().optional(),
1084
+
1085
+ /** The merge commit, written by `gates/orchestrator.ts` after the merge. */
1086
+ mergeCommitSha: z.string().optional(),
1087
+
1088
+ /**
1089
+ * Instruction-compliance grades for the run's agents, written by
1090
+ * `scripts/persist-compliance.ts`. `z.any()` rather than a shape: the
1091
+ * grader owns the structure and this schema only needs to stop claiming the
1092
+ * field does not exist.
1093
+ */
1094
+ compliance: z.any().optional(),
1095
+
1096
+ // Absent means UNMEASURED (#224). Write it with
1097
+ // scripts/record-suite-measurement.ts, never by hand.
1098
+ suiteMeasurement: SuiteMeasurementSchema.optional(),
1099
+
1100
+ // The scope gate's evidence dry-run (#235). Absent means UNMEASURED — the
1101
+ // gate never got as far as measuring. Written by the scope gate, not by hand.
1102
+ evidencePrevalidation: EvidencePrevalidationSchema.optional(),
1103
+
1104
+ // Which harness graded this run (#602). Absent means UNMEASURED, and that
1105
+ // is the state every run before this field was in: a stale harness and a
1106
+ // current one emit byte-identical artefacts, so the run's own output
1107
+ // could never say which validator produced its verdicts. Written by
1108
+ // scripts/record-harness-provenance.ts, never by hand.
1109
+ harness: HarnessSchema.optional(),
1110
+ });
1111
+
1112
+ export type WorkflowState = z.infer<typeof WorkflowStateSchema>;
1113
+
1114
+ // ── AFK batch plan schema (#468) ────────────────────────────
1115
+
1116
+ const REJECTED_SKIP_REASONS = [
1117
+ "needs investigation",
1118
+ "needs browser testing",
1119
+ "can't do from here",
1120
+ ];
1121
+
1122
+ export const AfkBatchPlanSchema = z.object({
1123
+ approvedAt: z.string(),
1124
+ planned: z.array(z.number()),
1125
+ shipped: z.array(z.number()),
1126
+ skipped: z.array(z.object({
1127
+ issue: z.number(),
1128
+ reason: z.string(),
1129
+ delegationAction: z.string().optional(),
1130
+ })),
1131
+ inProgress: z.number().nullable(),
1132
+ });
1133
+
1134
+ export type AfkBatchPlan = z.infer<typeof AfkBatchPlanSchema>;
1135
+
1136
+ export { REJECTED_SKIP_REASONS };
1137
+
1138
+ // ── Adversary report schema (ADR-009 B1) ──────────────────────
1139
+
1140
+ export const AdversaryReportSchema = z.object({
1141
+ gameable: z.number(),
1142
+ approved: z.boolean(),
1143
+ exploits: z.array(z.object({
1144
+ acId: z.string(),
1145
+ exploit: z.string(),
1146
+ recommendation: z.string(),
1147
+ })),
1148
+ });
1149
+
1150
+ // ── Chain artifact schemas ──────────────────────────────────
1151
+
1152
+ export const GoalRecordSchema = z.object({
1153
+ contractVersion: z.string(),
1154
+ id: z.string(),
1155
+ goalStatement: z.string().min(1),
1156
+ governingSpec: z.object({
1157
+ path: z.string(),
1158
+ detectedFrom: z.string().optional(),
1159
+ }).optional(),
1160
+ successCriteria: z.array(z.object({
1161
+ id: z.string(),
1162
+ assertion: z.string(),
1163
+ evidenceType: z.string(),
1164
+ threshold: z.object({ op: z.string(), value: z.string(), unit: z.string().optional() }),
1165
+ })),
1166
+ scopeBoundary: z.object({ in: z.array(z.string()), out: z.array(z.string()) }).optional(),
1167
+ artifactRef: z.object({ type: z.string(), locator: z.string() }).optional(),
1168
+ });
1169
+
1170
+ export const ShipEvidenceSchema = z.object({
1171
+ contractVersion: z.string(),
1172
+ issueNumber: z.number(),
1173
+ gateOut: z.object({
1174
+ status: z.enum(["PASS", "FAIL"]),
1175
+ evidence: z.array(z.object({
1176
+ criterion: z.string(),
1177
+ result: z.enum(["PASS", "FAIL", "SKIP"]),
1178
+ detail: z.any().optional(),
1179
+ })),
1180
+ }),
1181
+ mergeCommitSha: z.string().optional(),
1182
+ capturedAt: z.string(),
1183
+ iterationCount: z.number().optional(),
1184
+ sizing: z.object({ predicted: z.string().optional(), actual: z.string().optional() }).optional(),
1185
+ });
1186
+
1187
+ export const ProveEvidenceSchema = z.object({
1188
+ issueNumber: z.number(),
1189
+ verdict: z.enum(["PROVEN", "UNPROVEN", "INCONCLUSIVE"]),
1190
+ commitSHA: z.string(),
1191
+ capturedAt: z.string(),
1192
+ beforeEvidence: z.object({
1193
+ type: z.enum(["text", "screenshot", "api", "data", "none"]),
1194
+ path: z.string().nullable(),
1195
+ capturedAt: z.string(),
1196
+ description: z.string(),
1197
+ }),
1198
+ afterEvidence: z.object({
1199
+ type: z.enum(["text", "screenshot", "api", "data", "none"]),
1200
+ path: z.string().nullable(),
1201
+ capturedAt: z.string(),
1202
+ environment: z.enum(["local", "prod"]),
1203
+ description: z.string(),
1204
+ }),
1205
+ comparisonSummary: z.string(),
1206
+ quinnVerdict: z.enum(["PASS", "FAIL", "SKIP"]).optional(),
1207
+ reproduced: z.boolean(),
1208
+ gaps: z.array(z.object({ ac: z.string(), status: z.string(), detail: z.string() })).optional(),
1209
+ });