rungate 0.8.2 → 0.8.4

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 (74) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/BunTestPathGuard.hook.ts +106 -0
  9. package/hooks/DocHygiene.hook.ts +2 -1
  10. package/hooks/GateResultProtection.hook.ts +28 -7
  11. package/hooks/HookCurrency.hook.ts +48 -1
  12. package/hooks/TopLevelCdGuard.hook.ts +38 -6
  13. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  14. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  15. package/lib/ai-review-jury.ts +725 -0
  16. package/lib/ai-review-rounds.ts +791 -4
  17. package/lib/ai-review-unmeasured.ts +361 -0
  18. package/lib/bash-write-guard.ts +1235 -102
  19. package/lib/bun-test-paths.ts +253 -0
  20. package/lib/cli-commands.ts +252 -11
  21. package/lib/closing-reference-audit.ts +163 -0
  22. package/lib/conformity.ts +17 -1
  23. package/lib/create-sc.ts +45 -12
  24. package/lib/derived-spec.ts +206 -0
  25. package/lib/file-claims.ts +335 -0
  26. package/lib/finding-arbiter.ts +502 -28
  27. package/lib/finding-jury.ts +61 -5
  28. package/lib/finding-pr-routing.ts +333 -0
  29. package/lib/frontmatter.ts +16 -0
  30. package/lib/gate-check-audit.ts +646 -0
  31. package/lib/generators/agents-md.ts +29 -0
  32. package/lib/github.ts +112 -7
  33. package/lib/hook-tree-currency.ts +494 -0
  34. package/lib/issue-closure-audit.ts +161 -14
  35. package/lib/issue-create-override.ts +53 -3
  36. package/lib/issue-filing-gate.ts +1073 -76
  37. package/lib/local-review-rounds.ts +523 -0
  38. package/lib/organize.ts +21 -1
  39. package/lib/project-state-shape.ts +56 -5
  40. package/lib/release-preflight.ts +90 -1
  41. package/lib/repo-path.ts +94 -0
  42. package/lib/report-provenance.ts +218 -3
  43. package/lib/risk-tier.ts +302 -0
  44. package/lib/rounds-to-pass.ts +274 -0
  45. package/lib/rule-row-drift.ts +199 -0
  46. package/lib/sc-claim-forms.ts +33 -5
  47. package/lib/sc-guard.ts +11 -1
  48. package/lib/sc-id-cross-tree.ts +17 -2
  49. package/lib/sc-ids.ts +71 -6
  50. package/lib/sc-reservations.ts +158 -14
  51. package/lib/scaffold/ai-review-findings.ts +1369 -27
  52. package/lib/scaffold/ai-review-step.ts +4095 -119
  53. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  54. package/lib/scaffold/owned-files.ts +14 -0
  55. package/lib/scaffold/steps.ts +100 -9
  56. package/lib/scratch-roots.ts +93 -3
  57. package/lib/spec-updater.ts +22 -2
  58. package/lib/spec-write-ast.ts +728 -0
  59. package/lib/spec-write-sweep.ts +470 -0
  60. package/lib/test-suite-lock.ts +127 -13
  61. package/lib/ts-ast.ts +26 -0
  62. package/lib/validators/spec-validators.ts +36 -7
  63. package/lib/write-spec.ts +138 -0
  64. package/package.json +2 -1
  65. package/scripts/ai-review-findings.ts +41 -1
  66. package/scripts/arbitrate-finding.ts +330 -12
  67. package/scripts/audit-specs.ts +225 -24
  68. package/scripts/convert-spec.ts +7 -2
  69. package/scripts/create-sc.ts +14 -2
  70. package/scripts/create-spec.ts +5 -2
  71. package/scripts/detect-sc-drift.ts +10 -2
  72. package/scripts/record-ai-review-unmeasured.ts +370 -0
  73. package/scripts/split-spec.ts +17 -4
  74. package/scripts/sync-sc-status.ts +14 -2
package/bin/rungate.ts CHANGED
@@ -13,7 +13,7 @@
13
13
  import { existsSync } from "fs";
14
14
  import { dirname, join, resolve } from "path";
15
15
  import { fileURLToPath } from "url";
16
- import { CLI_COMMANDS, helpText } from "../lib/cli-commands";
16
+ import { CLI_COMMANDS, helpText, runCommandScript } from "../lib/cli-commands";
17
17
 
18
18
  const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
19
19
 
@@ -63,8 +63,13 @@ if (!existsSync(script)) {
63
63
  const needsRoot = command.projectRootFlag && !rest.includes("--project-root");
64
64
  const args = needsRoot ? [...rest, "--project-root", process.cwd()] : rest;
65
65
 
66
- // Each script reads process.argv at the top level and none guards on
67
- // import.meta.main, so the import IS the invocation. Rewrite argv first so
68
- // the script sees its own arguments and not the subcommand name.
69
- process.argv = [process.argv[0], script, ...args];
70
- await import(script);
66
+ // Run the script as an ENTRY MODULE, so `import.meta.main` is true inside it
67
+ // and it sees its own arguments rather than the subcommand name.
68
+ //
69
+ // This was `process.argv = [...]; await import(script)`, and the argv rewrite
70
+ // was the tell: it existed to make an imported module look like an entry
71
+ // module, which is most of the way to just running it as one. The half it
72
+ // could not fake is `import.meta.main`, which is false for any dynamic
73
+ // import — so the three command scripts that guard on it loaded, ran nothing
74
+ // and exited 0. `lib/cli-commands.ts` carries the measurement.
75
+ process.exit(runCommandScript(script, args).code);
@@ -11,13 +11,31 @@
11
11
  "commitSHA": { "type": "string" },
12
12
  "capturedAt": { "type": "string", "format": "date-time" },
13
13
  "beforeEvidence": {
14
+ "$comment": "#1540: UNMEASURED declares no type. The old shape filled an absent before-state with type \"none\", which is a value /goal legitimately writes for a run it did measure, so the two were indistinguishable. Artefacts written before #1540 carry no status and remain valid.",
14
15
  "type": "object",
15
16
  "properties": {
16
- "type": { "type": "string", "enum": ["text", "screenshot", "api", "none"] },
17
+ "status": { "type": "string", "enum": ["CAPTURED", "DECLARED_NONE", "UNMEASURED"] },
18
+ "type": { "type": "string", "enum": ["text", "screenshot", "api", "data", "none"] },
17
19
  "path": { "type": ["string", "null"] },
18
20
  "capturedAt": { "type": ["string", "null"] },
19
- "description": { "type": "string" }
20
- }
21
+ "description": { "type": "string" },
22
+ "reason": { "type": "string" }
23
+ },
24
+ "allOf": [
25
+ {
26
+ "$comment": "An unmeasured reading says why, and never claims a type.",
27
+ "if": { "properties": { "status": { "const": "UNMEASURED" } }, "required": ["status"] },
28
+ "then": { "required": ["reason"], "not": { "required": ["type"] } }
29
+ },
30
+ {
31
+ "$comment": "Any reading that is not UNMEASURED was taken, so it carries when.",
32
+ "if": {
33
+ "properties": { "status": { "enum": ["CAPTURED", "DECLARED_NONE"] } },
34
+ "required": ["status"]
35
+ },
36
+ "then": { "required": ["type", "capturedAt"] }
37
+ }
38
+ ]
21
39
  },
22
40
  "afterEvidence": {
23
41
  "type": "object",
package/gates/.gate-salt CHANGED
@@ -1 +1 @@
1
- 4bf447cd9f1aa5df2cbb1c260d54255a2d976fb28149b342a2b0360d7c4adbe4
1
+ 133dd39229ff86fc5f80fce43d9a3c806ad88e9d7d8e27b27688fc1ae27030eb
@@ -288,6 +288,144 @@ export function recordTestBaseline(
288
288
  }
289
289
  }
290
290
 
291
+ /**
292
+ * What /prove knows about the state of the world before the change (#1540).
293
+ *
294
+ * Three facts, not two. `beforeState.type` admits `"none"`, and
295
+ * `reference/prompts/goal-skill.md` tells /goal to write exactly that when it
296
+ * looked and there was nothing worth capturing — so "looked, found nothing"
297
+ * is a measurement. "Nobody looked" is not, and the two were spelled the same.
298
+ */
299
+ export type BeforeStateReading =
300
+ | { status: "captured"; type: string; path: string | null; capturedAt: string; description?: string }
301
+ | { status: "declared-none"; capturedAt: string; description?: string }
302
+ | { status: "unmeasured"; reason: string };
303
+
304
+ /** The `beforeState.type` values `gates/schema.ts` admits. */
305
+ const BEFORE_STATE_TYPES = ["text", "screenshot", "api", "data", "none"];
306
+
307
+ /**
308
+ * Read `beforeState` off a workflow state, saying which of the three it found.
309
+ *
310
+ * Measured on 2026-10-24: of the STANDARD and THOROUGH runs in the
311
+ * `~/.rungate` corpus, **none** carried a `beforeState` — the field has
312
+ * readers in three files and a producer in none, and every run since it was
313
+ * introduced has taken the absent branch. That is not the thing this function
314
+ * fixes; nothing here writes a before-state either. What it fixes is that the
315
+ * absent branch was indistinguishable from a measured one, so the gap could
316
+ * not be seen from outside and nothing reported it.
317
+ *
318
+ * A present-but-malformed field is UNMEASURED rather than captured. Reading
319
+ * an unknown shape as a measurement would put an undefined `type` into the
320
+ * evidence artefact and claim a comparison off it.
321
+ */
322
+ export function readBeforeState(state: Record<string, any>): BeforeStateReading {
323
+ const bs = state?.beforeState;
324
+ if (bs === undefined || bs === null) {
325
+ return {
326
+ status: "unmeasured",
327
+ reason:
328
+ "no beforeState on the workflow state — /goal captures it, and nothing " +
329
+ "in this tree writes one (#1540)",
330
+ };
331
+ }
332
+ if (typeof bs !== "object" || Array.isArray(bs) || typeof bs.capturedAt !== "string" ||
333
+ typeof bs.type !== "string" || !BEFORE_STATE_TYPES.includes(bs.type)) {
334
+ return {
335
+ status: "unmeasured",
336
+ reason:
337
+ `beforeState is present but not readable — expected {type, capturedAt} with type one of ` +
338
+ `${BEFORE_STATE_TYPES.join("|")}, got ${JSON.stringify(bs)} (#1540)`,
339
+ };
340
+ }
341
+ if (bs.type === "none") {
342
+ return { status: "declared-none", capturedAt: bs.capturedAt, description: bs.description };
343
+ }
344
+ return {
345
+ status: "captured",
346
+ type: bs.type,
347
+ path: typeof bs.path === "string" ? bs.path : null,
348
+ capturedAt: bs.capturedAt,
349
+ description: bs.description,
350
+ };
351
+ }
352
+
353
+ /** The reading as a status string, for anything that records or reports one. */
354
+ function beforeStateStatus(reading: BeforeStateReading): string {
355
+ return reading.status === "captured" ? "CAPTURED"
356
+ : reading.status === "declared-none" ? "DECLARED_NONE"
357
+ : "UNMEASURED";
358
+ }
359
+
360
+ /**
361
+ * Write a reading onto the durable workflow state, in place (#1540).
362
+ *
363
+ * Exported and pure for the same reason `recordTestBaseline` is: a reading
364
+ * that is honest buys nothing if the line recording it quietly drops the
365
+ * distinction. The two keys are mutually exclusive both ways — a stale reason
366
+ * beside a fresh status gives a consumer two answers and `??` picks one.
367
+ */
368
+ export function recordBeforeState(
369
+ state: Record<string, any>,
370
+ reading: BeforeStateReading,
371
+ ): void {
372
+ state.beforeStateStatus = beforeStateStatus(reading);
373
+ if (reading.status === "unmeasured") {
374
+ state.beforeStateUnmeasured = reading.reason;
375
+ } else {
376
+ delete state.beforeStateUnmeasured;
377
+ }
378
+ }
379
+
380
+ /**
381
+ * The `beforeEvidence` block of `prove-evidence.json` (#1540).
382
+ *
383
+ * The old shape was `wf.beforeState ?? { type: "none", path: null,
384
+ * capturedAt: <now>, description: "no before-state captured" }`. `"none"` is
385
+ * a value /goal legitimately writes, so a run nobody measured and a run
386
+ * measured as empty differed only by a timestamp. UNMEASURED carries no
387
+ * `type` at all — there is no honest value to put there.
388
+ */
389
+ export function beforeEvidenceFor(reading: BeforeStateReading): Record<string, any> {
390
+ if (reading.status === "unmeasured") {
391
+ return { status: "UNMEASURED", reason: reading.reason };
392
+ }
393
+ if (reading.status === "declared-none") {
394
+ return {
395
+ status: "DECLARED_NONE", type: "none", path: null,
396
+ capturedAt: reading.capturedAt,
397
+ description: reading.description ?? "/goal captured no before-state for this run",
398
+ };
399
+ }
400
+ return {
401
+ status: "CAPTURED", type: reading.type, path: reading.path,
402
+ capturedAt: reading.capturedAt, description: reading.description,
403
+ };
404
+ }
405
+
406
+ /**
407
+ * `prove-evidence.json`'s `comparisonSummary` (#1540).
408
+ *
409
+ * It used to read `"${passed}/${total} criteria passed"` unconditionally — a
410
+ * true sentence about the ACs, and no answer to the question the field name
411
+ * asks. The counts are kept because they are the only thing it carried; what
412
+ * is added is whether a comparison happened at all.
413
+ */
414
+ export function comparisonSummaryFor(
415
+ reading: BeforeStateReading,
416
+ passed: number,
417
+ total: number,
418
+ ): string {
419
+ const counts = `${passed}/${total} criteria passed`;
420
+ if (reading.status === "unmeasured") {
421
+ return `before/after comparison UNMEASURED — ${reading.reason}; ${counts}`;
422
+ }
423
+ if (reading.status === "declared-none") {
424
+ return `no before/after comparison: /goal declared beforeState.type "none" at ${reading.capturedAt}; ${counts}`;
425
+ }
426
+ return `compared against the ${reading.type} before-state captured at ${reading.capturedAt}; ${counts}`;
427
+ }
428
+
291
429
  /** What a gate run does about the tests that existed when it last looked. */
292
430
  export type CensusVerdict =
293
431
  | { kind: "unmeasured"; reason: string }
@@ -1349,10 +1487,21 @@ async function runProveReproducer(state: Record<string, any>, issue: number, iss
1349
1487
  }
1350
1488
  }
1351
1489
 
1490
+ // #1540: `state.beforeState || null` was the same silent default one field
1491
+ // over — a run nobody captured a before-state for, and a run whose /goal
1492
+ // declared there was nothing to capture, both arrived at the reproducer as
1493
+ // `null`. The reading travels beside the raw field so the prompt can say
1494
+ // which it got, and the raw field stays for a producer that may yet exist.
1495
+ const beforeReading = readBeforeState(state);
1496
+ if (beforeReading.status === "unmeasured") {
1497
+ console.warn(`WARN: prove gate — before/after comparison UNMEASURED: ${beforeReading.reason}`);
1498
+ }
1499
+
1352
1500
  const proveInput = {
1353
1501
  issueBody, issueTitle, issueNumber: issue,
1354
1502
  acs: state.acs || [], apiBase, uiBase,
1355
- beforeState: state.beforeState || null, projectRoot,
1503
+ beforeState: state.beforeState || null,
1504
+ beforeEvidence: beforeEvidenceFor(beforeReading), projectRoot,
1356
1505
  // #304: the liveness readings, including the ones that measured nothing.
1357
1506
  // UNMEASURED has to be durable or relaxing the refusal above is a silent
1358
1507
  // fail-open.
@@ -1363,6 +1512,9 @@ async function runProveReproducer(state: Record<string, any>, issue: number, iss
1363
1512
  // writing only there would make the record as ephemeral as the stdout line
1364
1513
  // it replaced.
1365
1514
  state.liveness = proveInput.liveness;
1515
+ // Same argument as liveness, for the same reason (#1540): UNMEASURED has to
1516
+ // be durable or the gap is visible only in a stdout line nobody reads back.
1517
+ recordBeforeState(state, beforeReading);
1366
1518
  writeFileSync(stateFile, JSON.stringify(state, null, 2));
1367
1519
  const proveInputPath = join(workDir, "prove-input.json");
1368
1520
  writeFileSync(proveInputPath, JSON.stringify(proveInput, null, 2));
@@ -1,6 +1,7 @@
1
1
  import { test, expect, describe } from "bun:test";
2
2
  import { readFileSync, existsSync, writeFileSync } from "fs";
3
3
  import { execSync } from "child_process";
4
+ import { beforeEvidenceFor, comparisonSummaryFor, readBeforeState } from "./gate-executor";
4
5
 
5
6
  const TEST_DIR = process.env.TEST_WORK_DIR || "";
6
7
  const PROJECT_ROOT = process.env.PROJECT_ROOT || process.cwd();
@@ -117,23 +118,28 @@ describe("prove: run evidence commands from workflow-state", () => {
117
118
  const verdict = criteriaResults.length === 0 ? "INCONCLUSIVE"
118
119
  : fails.length > 0 ? "UNPROVEN" : "PROVEN";
119
120
 
121
+ // #1540: the fallback here used to manufacture `type: "none"`, which is a
122
+ // value /goal legitimately writes — so a run nobody measured was recorded
123
+ // as a run measured as empty. The reading keeps the two apart.
124
+ const beforeReading = readBeforeState(wf);
125
+
120
126
  const evidence = {
121
127
  issueNumber: wf.issue,
122
128
  verdict,
123
129
  commitSHA: commitSha,
124
130
  capturedAt: new Date().toISOString(),
125
- beforeEvidence: wf.beforeState ?? {
126
- type: "none", path: null,
127
- capturedAt: new Date().toISOString(),
128
- description: "no before-state captured",
129
- },
131
+ beforeEvidence: beforeEvidenceFor(beforeReading),
130
132
  afterEvidence: {
131
133
  type: "text", path: null,
132
134
  capturedAt: new Date().toISOString(),
133
135
  environment: proveEnvironment,
134
136
  description: criteriaResults.map(r => `${r.scId}: ${r.verdict}`).join(", "),
135
137
  },
136
- comparisonSummary: `${criteriaResults.filter(r => r.verdict === "PASS").length}/${criteriaResults.length} criteria passed`,
138
+ comparisonSummary: comparisonSummaryFor(
139
+ beforeReading,
140
+ criteriaResults.filter(r => r.verdict === "PASS").length,
141
+ criteriaResults.length,
142
+ ),
137
143
  reproduced: true,
138
144
  gaps: fails.map(f => ({ ac: f.scId, status: "UNPROVEN", detail: f.evidence })),
139
145
  criteriaResults,
package/gates/schema.ts CHANGED
@@ -1048,6 +1048,25 @@ export const WorkflowStateSchema = z.object({
1048
1048
  description: z.string().optional(),
1049
1049
  }).optional(),
1050
1050
 
1051
+ /**
1052
+ * Which of the three readings the prove gate took of `beforeState` (#1540).
1053
+ *
1054
+ * `beforeState` has no producer in this tree and never had one, so the
1055
+ * absent case is the only one the corpus contains. It is recorded rather
1056
+ * than inferred because `beforeState.type` admits `"none"` — /goal is told
1057
+ * to write that when it looked and found nothing — and a reader cannot
1058
+ * otherwise tell "nobody looked" from "looked, nothing there".
1059
+ */
1060
+ beforeStateStatus: z.enum(["CAPTURED", "DECLARED_NONE", "UNMEASURED"]).optional(),
1061
+
1062
+ /**
1063
+ * Why no before-state was read (#1540). Present exactly when
1064
+ * `beforeStateStatus` is `UNMEASURED`, and deleted when it is not —
1065
+ * `recordBeforeState` keeps the two exclusive, for the same reason
1066
+ * `testBaselineUnmeasured` is exclusive with `testBaseline`.
1067
+ */
1068
+ beforeStateUnmeasured: z.string().optional(),
1069
+
1051
1070
  issueType: z.enum(["feature", "bug-fix", "bug", "refactor", "chore"]).optional(),
1052
1071
  rca: z.object({
1053
1072
  rootCause: z.string().optional(),
@@ -1184,17 +1203,61 @@ export const ShipEvidenceSchema = z.object({
1184
1203
  sizing: z.object({ predicted: z.string().optional(), actual: z.string().optional() }).optional(),
1185
1204
  });
1186
1205
 
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({
1206
+ /**
1207
+ * `prove-evidence.json`'s `beforeEvidence` block (#1540).
1208
+ *
1209
+ * Four arms, and the fourth is the reason this is a union rather than a
1210
+ * widening. The first three are what `beforeEvidenceFor` emits; the last is
1211
+ * every artefact written before #1540, which carries no `status` at all and
1212
+ * still sits on disk under `~/.rungate`. `gates/chain.test.ts` validates
1213
+ * whatever artefact it finds, so a schema that admitted only the new shape
1214
+ * would redden on a run nobody touched.
1215
+ *
1216
+ * UNMEASURED declares no `type`, which is the whole point: the old fallback
1217
+ * put `"none"` there, and `"none"` is a value /goal legitimately writes. The
1218
+ * other arms keep `type` and `capturedAt` REQUIRED, so admitting the absent
1219
+ * case costs nothing on the cases that were already honest.
1220
+ */
1221
+ const BeforeEvidenceSchema = z.union([
1222
+ // `.strict()` carries the claim. Zod strips unknown keys by default, so a
1223
+ // block spelling `{ status: "UNMEASURED", type: "none" }` would otherwise
1224
+ // be ACCEPTED with the type quietly discarded — the declaration would read
1225
+ // as enforced while admitting exactly the shape it exists to forbid.
1226
+ z.object({
1227
+ status: z.literal("UNMEASURED"),
1228
+ reason: z.string(),
1229
+ }).strict(),
1230
+ z.object({
1231
+ status: z.literal("DECLARED_NONE"),
1232
+ type: z.literal("none"),
1233
+ path: z.null(),
1234
+ capturedAt: z.string(),
1235
+ description: z.string(),
1236
+ }),
1237
+ z.object({
1238
+ status: z.literal("CAPTURED"),
1239
+ type: z.enum(["text", "screenshot", "api", "data"]),
1240
+ path: z.string().nullable(),
1241
+ capturedAt: z.string(),
1242
+ description: z.string().optional(),
1243
+ }),
1244
+ // Pre-#1540 artefacts. No `status`, and `"none"` here is ambiguous by
1245
+ // construction — that ambiguity is what the issue was about, and it cannot
1246
+ // be resolved retroactively for a file already written.
1247
+ z.object({
1193
1248
  type: z.enum(["text", "screenshot", "api", "data", "none"]),
1194
1249
  path: z.string().nullable(),
1195
1250
  capturedAt: z.string(),
1196
1251
  description: z.string(),
1197
1252
  }),
1253
+ ]);
1254
+
1255
+ export const ProveEvidenceSchema = z.object({
1256
+ issueNumber: z.number(),
1257
+ verdict: z.enum(["PROVEN", "UNPROVEN", "INCONCLUSIVE"]),
1258
+ commitSHA: z.string(),
1259
+ capturedAt: z.string(),
1260
+ beforeEvidence: BeforeEvidenceSchema,
1198
1261
  afterEvidence: z.object({
1199
1262
  type: z.enum(["text", "screenshot", "api", "data", "none"]),
1200
1263
  path: z.string().nullable(),
@@ -1690,11 +1690,18 @@ describe("ship checks", () => {
1690
1690
  const slug = sf("slug");
1691
1691
  if (!slug) return;
1692
1692
  const witnessDir = runArtifact("witnesses");
1693
- if (!existsSync(witnessDir)) {
1694
- // WARN — witnesses are new, not all workflows have them yet
1695
- console.warn("WARN: No witness directory found — witness chain not verified");
1696
- return;
1697
- }
1693
+ // #1384 — this warned and returned on exactly the condition it is named
1694
+ // for, so the check could not fail on an absent witness directory. The
1695
+ // deferral it carried ("witnesses are new, not all workflows have them
1696
+ // yet") had outlived its measurement: over ~/.rungate on 2026-10-24, all
1697
+ // 52 runs that reach this check — phase SHIP or DONE, with a slug — carry
1698
+ // a non-empty witnesses/ directory. Refusing costs no run.
1699
+ expect(
1700
+ existsSync(witnessDir),
1701
+ `witness-chain: no witness directory at ${witnessDir} — the gate system records ` +
1702
+ "one per run from SHIP onward, so an absent directory means the chain was never " +
1703
+ "written rather than that this run did not need it (#473, #1384)",
1704
+ ).toBe(true);
1698
1705
  const witnesses = readdirSync(witnessDir).filter(f => f.endsWith(".json"));
1699
1706
  expect(witnesses.length, "Witness directory exists but is empty").toBeGreaterThan(0);
1700
1707
  });
@@ -0,0 +1,106 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * BunTestPathGuard.hook.ts — PreToolUse on Bash
4
+ *
5
+ * SC-370 (HOOK-ARCHITECTURE-SPEC): hook SC traceability
6
+ * SC-371 (HOOK-ARCHITECTURE-SPEC): no hook exceeds 150 lines
7
+ * SC-2543 (HOOK-ARCHITECTURE-SPEC): the guard is registered in all four positions
8
+ *
9
+ * The decision lives in lib/bun-test-paths.ts and not here — hooks are thin
10
+ * triggers (HOOK-ARCHITECTURE-SPEC), the same shape as TopLevelCdGuard over
11
+ * lib/top-level-cd.ts and BashToolGuard over lib/bash-file-read.ts.
12
+ *
13
+ * Refuses a Bash command that hands `bun test` a path matching no file.
14
+ *
15
+ * Why a hook and not a sentence. `bun test <real> <absent>` exits 0 and
16
+ * prints a pass total, so a typo'd path in a verification command is
17
+ * byte-identical to a suite that ran and passed. On 2026-10-24 an agent
18
+ * shipping #1536 reported six suites green; one of the six did not exist and
19
+ * had never been opened. The agent self-reported it, which is the only
20
+ * reason it is written down — an instruction to check the file count would
21
+ * have had to be followed by the one person who already believed they had.
22
+ *
23
+ * Why the Bash tool and not a wrapper. 55 sites in this tree execute
24
+ * `bun test` with a path argument and 49 are inside `test/`; a wrapper
25
+ * covers none of them until each is rewritten, and covers a hand-composed
26
+ * command never. The failure this exists for was in a command an agent
27
+ * composed by hand, so the binding has to be the one chokepoint those pass
28
+ * through. The known gap is the reverse: a spawn from inside a running
29
+ * process never reaches a PreToolUse hook. Both halves are stated in
30
+ * lib/bun-test-paths.ts under WHAT THIS DOES NOT COVER.
31
+ *
32
+ * It is registered at PROJECT scope, like TopLevelCdGuard:
33
+ * `${CLAUDE_PROJECT_DIR}` resolves to the worktree a session is in, every
34
+ * worktree carries the committed `.claude/settings.json`, and a targeted
35
+ * test run is a harness concern. Machine-wide registration lives in
36
+ * `~/.claude/settings.json`, which no PR can carry.
37
+ *
38
+ * SCOPED to harnessed projects via lib/harness-project.ts, the same decider
39
+ * TopLevelCdGuard and BashToolGuard use.
40
+ *
41
+ * Issue: #1544
42
+ */
43
+
44
+ import { parseHookInput } from './lib/parseStdin';
45
+ import {
46
+ BUN_TEST_PATH_GUARD_DECISION,
47
+ bunTestPathGuardMode,
48
+ bunTestPathRefusal,
49
+ } from '../lib/bun-test-paths';
50
+ import { isHarnessProject } from '../lib/harness-project';
51
+
52
+ async function main() {
53
+ const payload = await parseHookInput();
54
+ if (!payload) process.exit(0);
55
+
56
+ if (payload.tool_name !== 'Bash') process.exit(0);
57
+
58
+ // Scope before parse: outside a harnessed project this repo's verification
59
+ // conventions do not apply and there is nothing for this to protect.
60
+ // NARROWED, not `|| process.cwd()`: the payload field is untyped, and a
61
+ // non-string reaching `resolve()` would throw inside the guard and be
62
+ // swallowed by the fail-open below — a guard that silently stops firing.
63
+ const declared = payload.cwd;
64
+ const cwd = typeof declared === 'string' && declared !== '' ? declared : process.cwd();
65
+ if (!isHarnessProject(cwd)) process.exit(0);
66
+
67
+ const { mode, unrecognised } = bunTestPathGuardMode();
68
+ if (mode === 'off') process.exit(0);
69
+
70
+ // Fails open on an unexpected error, and says so. A broken guard must never
71
+ // be able to block every `bun test` in the repository — but it must not be
72
+ // able to do that SILENTLY either, which is a different thing and is the
73
+ // defect TestSuiteGuard's #194 found in itself.
74
+ let refusal: ReturnType<typeof bunTestPathRefusal>;
75
+ try {
76
+ refusal = bunTestPathRefusal(payload.tool_input?.command, cwd);
77
+ } catch (e) {
78
+ console.log(JSON.stringify({
79
+ systemMessage:
80
+ `GUARD-FAILURE-VISIBLE: BunTestPathGuard could not evaluate this command and ` +
81
+ `allowed it. #1544 is NOT being enforced right now. ${(e as Error)?.message ?? e}`,
82
+ }));
83
+ process.exit(0);
84
+ }
85
+
86
+ if (refusal === null) process.exit(0);
87
+
88
+ const note = unrecognised
89
+ ? `\n(${'RUNGATE_BUN_TEST_PATH_GUARD'}=${JSON.stringify(unrecognised)} is not a mode I know; refusing, which is the default.)`
90
+ : '';
91
+
92
+ if (mode === 'block') {
93
+ console.log(JSON.stringify({
94
+ decision: BUN_TEST_PATH_GUARD_DECISION,
95
+ reason: refusal.message + note,
96
+ }));
97
+ process.exit(0);
98
+ }
99
+
100
+ // WARN: the command RUNS. stderr, so it reaches the transcript without
101
+ // becoming a tool result the model might read as a refusal.
102
+ console.error(`[bun-test-path] ${refusal.message}${note}`);
103
+ process.exit(0);
104
+ }
105
+
106
+ main();
@@ -47,13 +47,14 @@ if (!filePath.endsWith('.md')) process.exit(0);
47
47
  // consumer than the doc index. A mutation record is identified by its one `# `
48
48
  // heading, so a stamp there is not a missing field being filled in, it is a
49
49
  // convention being broken one file at a time.
50
+ // Every entry names a CLASS of markdown, never a place to work, which is why
51
+ // `.claude/worktrees/` left in #1432 — see DOC-HYGIENE-ARCHITECTURE-SPEC.md.
50
52
  const SKIP_PATTERNS = [
51
53
  '/archive/',
52
54
  '/MEMORY/WORK/',
53
55
  '/.pai-work/',
54
56
  '/config/',
55
57
  '/test-results/',
56
- '.claude/worktrees/',
57
58
  '.claude/agents/',
58
59
  '.claude/rules/mutations/',
59
60
  '/tmp/',
@@ -36,10 +36,21 @@
36
36
  * write the artifact at all**, and refuses every Write/Edit of it.
37
37
  * - THIS hook is authoritative for **what a permitted write may contain**.
38
38
  *
39
- * Neither subsumes the other. Because the blanket guard fires first in THIS
40
- * repository, this hook's ALLOW-path is not observable from an ordinary
41
- * session here — that is #1152, and the reason the contract test runs each
42
- * hook on its own rather than through a session.
39
+ * Since #1211 case-folded the blanket guard's matcher, this hook's refusals
40
+ * are a SUBSET of the blanket guard's: both now agree on which paths are the
41
+ * artifact, and the blanket guard refuses every Write/Edit of it. Until then
42
+ * the one input this hook refused and the blanket guard permitted was
43
+ * `WORKFLOW-STATE.JSON` — a hole in the SHIPPING guard, not a feature of this
44
+ * one, which is why closing it was right even though it made this hook
45
+ * behaviourally subsumed in a tree holding both.
46
+ *
47
+ * Subsumed is not dead, and the reason is deployment rather than behaviour:
48
+ * this hook does not travel to consumers (below), and in a session on this
49
+ * machine its registration resolves to a tree outside this repository (#713).
50
+ * Because the blanket guard fires first in THIS repository, this hook's
51
+ * ALLOW-path is not observable from an ordinary session here — that is #1152,
52
+ * and the reason the contract test runs each hook on its own rather than
53
+ * through a session.
43
54
  *
44
55
  * Note the reach is the opposite way round from what #1152's body assumes:
45
56
  * `WorkflowStateGuard` is `deployToConsumers: true` and this hook is
@@ -54,11 +65,11 @@
54
65
  * `specs/HOOK-ARCHITECTURE-SPEC.md` § "The workflow-state.json write contract"
55
66
  * in the same commit.
56
67
  *
57
- * Issues: #471, #1137, #1152
68
+ * Issues: #471, #1137, #1152, #1359
58
69
  */
59
70
 
60
71
  import { parseHookInput } from './lib/parseStdin';
61
- import { decideGateResultWrite } from '../lib/gate-result-protection';
72
+ import { decideGateResultWrite, isWorkflowState } from '../lib/gate-result-protection';
62
73
 
63
74
  async function main() {
64
75
  const input = await parseHookInput();
@@ -77,8 +88,18 @@ async function main() {
77
88
  // A guard that crashes must not thereby allow the thing it guards (#1137).
78
89
  // Scoped to a payload that already named workflow-state.json, so a bug
79
90
  // here refuses writes to one artifact rather than bricking the session.
91
+ //
92
+ // #1359: this used to be a second, hand-written `endsWith` and it was
93
+ // case-SENSITIVE, so #1184's fold reached the predicate and not the arm
94
+ // whose whole job is to not fail open. Measured rather than read: with
95
+ // `decideGateResultWrite` forced to throw, `workflow-state.json` was
96
+ // refused and `WORKFLOW-STATE.JSON` was ALLOWED, silently. On the default
97
+ // macOS filesystem those are the same inode.
98
+ //
99
+ // One binding for the question, not two. A second predicate deciding the
100
+ // same thing is exactly how this one drifted away from the first.
80
101
  const named = String((input.tool_input as { file_path?: unknown })?.file_path ?? '');
81
- if (!named.endsWith('workflow-state.json')) process.exit(0);
102
+ if (!isWorkflowState(named)) process.exit(0);
82
103
  decision = {
83
104
  blocked: true,
84
105
  reason: `Refused: gate-result protection could not evaluate this write (${String(e)}).`,
@@ -24,11 +24,27 @@
24
24
  *
25
25
  * Thin trigger: every decision is `scripts/check-installed-hook-currency.ts`.
26
26
  * This file chooses a root, prints, and exits 0.
27
+ *
28
+ * ## The second reading: Claude Code hooks, not git hooks (#1216)
29
+ *
30
+ * The same shape one layer out. `.git/hooks` is untracked, so nothing in the
31
+ * repository can see what is installed there — and a Claude Code hook
32
+ * registration names a DIRECTORY, so nothing can see which commit the bytes
33
+ * it executes are on either. Why a startup report rather than a suite case or
34
+ * a line per hook, why this hook survives the staleness it reports, and why
35
+ * it REPORTS and never repairs: `lib/hook-tree-currency.ts`. The runner below
36
+ * passes through whatever that module asks for, so the query-only constraint
37
+ * is asserted where the subcommands are chosen —
38
+ * `test/unit/hook-tree-currency.test.ts` HC-16.
27
39
  */
28
40
 
29
- import { existsSync } from 'fs';
41
+ import { spawnSync } from 'child_process';
42
+ import { existsSync, readFileSync, readdirSync } from 'fs';
43
+ import { homedir } from 'os';
30
44
  import { join } from 'path';
45
+ import { tryLoadRungateConfig } from '../lib/config-loader';
31
46
  import { repoRootFrom } from '../lib/paths';
47
+ import { currencyReportLines, readRegistrationCurrency, spawnGitRunner } from '../lib/hook-tree-currency';
32
48
  import {
33
49
  readHookCurrency,
34
50
  currencyClass,
@@ -96,4 +112,35 @@ try {
96
112
  report(`Hook currency UNMEASURED: ${e instanceof Error ? e.message : String(e)}`);
97
113
  }
98
114
 
115
+ // ── Second reading: how old are the hooks a session actually executes (#1216)
116
+ // Its own `try`: two readings of different files, so one throwing must not
117
+ // take the other's with it — a shared `catch` would be one refusal standing
118
+ // for two, and nobody could tell which was never taken. The `hooks/` gate is
119
+ // the `.git/hooks` gate above, for the same reason: a tree the scaffold never
120
+ // touched owns no hooks of ours to be stale.
121
+ try {
122
+ const hooksDir = join(PROJECT_ROOT, 'hooks');
123
+ if (existsSync(hooksDir)) {
124
+ const config = tryLoadRungateConfig(PROJECT_ROOT) as { hooks?: unknown[] } | null;
125
+ const reading = readRegistrationCurrency({
126
+ repoRoot: PROJECT_ROOT,
127
+ home: homedir(),
128
+ // Named at the call site, not defaulted inside the module — its header
129
+ // says why.
130
+ base: 'origin/main',
131
+ readFile: p => (existsSync(p) ? readFileSync(p, 'utf-8') : null),
132
+ ownedHooks: readdirSync(hooksDir)
133
+ .filter(n => n.endsWith('.hook.ts'))
134
+ .map(n => n.replace(/\.hook\.ts$/, '')),
135
+ registryCommands: (config?.hooks ?? []).map(h => String((h as { command?: string })?.command ?? h)),
136
+ // `spawnGitRunner`, never an inline spawn: these directories are the
137
+ // unsupervised ones, and git executes its own config. See the module.
138
+ git: spawnGitRunner(spawnSync),
139
+ });
140
+ for (const line of currencyReportLines(reading)) report(line);
141
+ }
142
+ } catch (e) {
143
+ report(`Hook tree currency UNMEASURED: ${e instanceof Error ? e.message : String(e)}`);
144
+ }
145
+
99
146
  process.exit(0);