rungate 0.8.2 → 0.8.3

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 (63) 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/DocHygiene.hook.ts +2 -1
  9. package/hooks/GateResultProtection.hook.ts +28 -7
  10. package/hooks/HookCurrency.hook.ts +48 -1
  11. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  12. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  13. package/lib/ai-review-jury.ts +725 -0
  14. package/lib/ai-review-rounds.ts +791 -4
  15. package/lib/ai-review-unmeasured.ts +361 -0
  16. package/lib/bash-write-guard.ts +1235 -102
  17. package/lib/cli-commands.ts +252 -11
  18. package/lib/closing-reference-audit.ts +163 -0
  19. package/lib/conformity.ts +12 -0
  20. package/lib/create-sc.ts +45 -12
  21. package/lib/derived-spec.ts +206 -0
  22. package/lib/file-claims.ts +335 -0
  23. package/lib/finding-arbiter.ts +502 -28
  24. package/lib/finding-jury.ts +48 -1
  25. package/lib/finding-pr-routing.ts +333 -0
  26. package/lib/frontmatter.ts +16 -0
  27. package/lib/gate-check-audit.ts +259 -0
  28. package/lib/generators/agents-md.ts +29 -0
  29. package/lib/github.ts +112 -7
  30. package/lib/hook-tree-currency.ts +494 -0
  31. package/lib/issue-closure-audit.ts +161 -14
  32. package/lib/issue-create-override.ts +53 -3
  33. package/lib/issue-filing-gate.ts +1073 -76
  34. package/lib/local-review-rounds.ts +523 -0
  35. package/lib/organize.ts +10 -0
  36. package/lib/project-state-shape.ts +56 -5
  37. package/lib/repo-path.ts +94 -0
  38. package/lib/report-provenance.ts +65 -3
  39. package/lib/risk-tier.ts +302 -0
  40. package/lib/rounds-to-pass.ts +274 -0
  41. package/lib/rule-row-drift.ts +199 -0
  42. package/lib/sc-claim-forms.ts +33 -5
  43. package/lib/sc-guard.ts +11 -1
  44. package/lib/sc-id-cross-tree.ts +17 -2
  45. package/lib/sc-ids.ts +71 -6
  46. package/lib/sc-reservations.ts +158 -14
  47. package/lib/scaffold/ai-review-findings.ts +1157 -18
  48. package/lib/scaffold/ai-review-step.ts +3798 -76
  49. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  50. package/lib/scaffold/owned-files.ts +14 -0
  51. package/lib/scaffold/steps.ts +83 -9
  52. package/lib/scratch-roots.ts +93 -3
  53. package/lib/spec-updater.ts +16 -0
  54. package/lib/validators/spec-validators.ts +28 -2
  55. package/package.json +2 -1
  56. package/scripts/ai-review-findings.ts +41 -1
  57. package/scripts/arbitrate-finding.ts +330 -12
  58. package/scripts/audit-specs.ts +225 -23
  59. package/scripts/create-sc.ts +11 -0
  60. package/scripts/detect-sc-drift.ts +10 -2
  61. package/scripts/record-ai-review-unmeasured.ts +370 -0
  62. package/scripts/split-spec.ts +12 -0
  63. package/scripts/sync-sc-status.ts +11 -0
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
+ 47f8d47ee78dd4b50c501a7cb42b8c220a9511b6d5ce62c6012fe6596440fbe0
@@ -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
  });
@@ -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);
@@ -102,21 +102,38 @@ async function main() {
102
102
  // inside one phase would leave the intake rate untouched.
103
103
  const gate = await filingGate(cmd, { projectRoot: process.cwd() });
104
104
  const unrecorded = gate.rows.filter(row => !recordAdjudication(row)).length;
105
+ // A refusal says the override "is recorded beside the refusal it waived".
106
+ // When the write failed that sentence is false, and a security control
107
+ // asserting a guarantee it is not providing is worse than one that says
108
+ // nothing — so the unrecorded notice rides ON the refusal rather than
109
+ // being skipped by the early exit, which is where it used to go.
110
+ const unrecordedNote =
111
+ unrecorded > 0
112
+ ? `[FindingArbiter] ${unrecorded} adjudication(s) could NOT be written to ${ledgerPath()}, ` +
113
+ "so they are not in the population that prices this gate and any claim below that " +
114
+ "a decision was recorded does not hold for them."
115
+ : null;
105
116
 
117
+ // `gate.note` rides on the refusal for the same reason `unrecordedNote`
118
+ // does, and it was missed when that one was fixed: a `decision: "block"`
119
+ // payload has ONE text field, so anything not folded into `reason` here is
120
+ // discarded by the early exit and never reaches the agent.
121
+ //
122
+ // The note that mattered is the corpus-drop one. A refusal computed against
123
+ // a tracker three issues short is exactly where the shortfall needs saying
124
+ // — the agent is being told its finding is already filed, by a comparison
125
+ // that did not read the whole tracker — and that was the one path on which
126
+ // it was silently dropped. `FG-60` is the case; it went red here first.
106
127
  if (gate.refusal !== null) {
107
- console.log(JSON.stringify({ decision: "block", reason: gate.refusal }));
128
+ const riders = [gate.note, unrecordedNote].filter((n): n is string => n !== null);
129
+ const reason = [gate.refusal, ...riders].join("\n\n");
130
+ console.log(JSON.stringify({ decision: "block", reason }));
108
131
  process.exit(0);
109
132
  }
110
133
  // systemMessage and not stderr: stderr from a hook that exits 0 is not
111
134
  // shown. An UNMEASURED nobody sees is a silent pass, which is the one thing
112
135
  // lib/issue-filing-gate.ts's header says this must not become.
113
- const notes = [
114
- gate.note,
115
- unrecorded > 0
116
- ? `[FindingArbiter] ${unrecorded} adjudication(s) could not be written to ${ledgerPath()}, ` +
117
- `so this filing is not in the population that prices the gate.`
118
- : null,
119
- ].filter((n): n is string => n !== null);
136
+ const notes = [gate.note, unrecordedNote].filter((n): n is string => n !== null);
120
137
  if (notes.length > 0) console.log(JSON.stringify({ systemMessage: notes.join("\n\n") }));
121
138
  process.exit(0);
122
139
  }
@@ -19,12 +19,22 @@
19
19
  * - `GateResultProtection` is authoritative for **what a permitted write may
20
20
  * contain** — forged, erased or changed gate results, and `phase` DONE.
21
21
  *
22
- * Neither subsumes the other. THIS hook is the one that ships
23
- * (`deployToConsumers: true`); the specific guard is OPT-IN and a scaffolded
24
- * consumer does not get it. So on a consumer tree this is the ONLY guard on
25
- * the artifact — which is why its matcher being case-SENSITIVE while the
26
- * specific guard's is case-folded (#1184) is a consumer-reachable gap and not
27
- * a tidiness question.
22
+ * THIS hook is the one that ships (`deployToConsumers: true`); the specific
23
+ * guard is OPT-IN and a scaffolded consumer does not get it. So on a consumer
24
+ * tree this is the ONLY guard on the artifact, and that is why its matcher
25
+ * being case-SENSITIVE while the specific guard's was case-folded (#1184) was
26
+ * a consumer-reachable gap and not a tidiness question. #1211 closed it: the
27
+ * matcher below case-folds, so the two predicates now agree on WHICH paths are
28
+ * the artifact and differ only in reach — `.includes()` here against
29
+ * `.endsWith()` there.
30
+ *
31
+ * The specific guard's refusals are therefore a SUBSET of this hook's. That is
32
+ * the safe direction and it is asserted, not assumed: this hook refusing every
33
+ * Write/Edit of the artifact means a consumer tree is covered for the question
34
+ * "may a tool call write this at all", which is the only question a consumer
35
+ * tree has a guard for. Subsumed is not dead — the two do not ship to the same
36
+ * trees, and the specific guard's refusal messages name the forgery while this
37
+ * one names the sanctioned writer.
28
38
  *
29
39
  * The contract is executed, not described:
30
40
  * `test/workflow-state-write-contract.test.ts` runs both hooks over one corpus
@@ -47,7 +57,14 @@ async function main() {
47
57
  // Write tool uses file_path; Edit tool uses file_path
48
58
  const path = (toolInput.file_path as string) || (toolInput.path as string) || '';
49
59
 
50
- if (!path.includes('workflow-state.json')) process.exit(0);
60
+ // Case-FOLDED (#1211). `WORKFLOW-STATE.JSON` and `workflow-state.json` are one
61
+ // file on a case-insensitive filesystem — measured in #1184, which closed this
62
+ // in GateResultProtection and never carried the fix here. This is the guard
63
+ // that ships, so the uppercase spelling was reaching a consumer's disk with no
64
+ // guard at all. The population the fold newly claims is enumerated and bounded
65
+ // in test/workflow-state-guard-case.test.ts; it is case-variants of this name
66
+ // and nothing else.
67
+ if (!path.toLowerCase().includes('workflow-state.json')) process.exit(0);
51
68
 
52
69
  // Block the write
53
70
  const reason = [