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.
- package/bin/rungate.ts +11 -6
- package/config/prove-evidence.schema.json +21 -3
- package/gates/.gate-salt +1 -1
- package/gates/gate-executor.ts +153 -1
- package/gates/prove.test.ts +12 -6
- package/gates/schema.ts +69 -6
- package/gates/workflow.test.ts +12 -5
- package/hooks/BunTestPathGuard.hook.ts +106 -0
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/TopLevelCdGuard.hook.ts +38 -6
- package/hooks/VerifyPhaseLock.hook.ts +25 -8
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +791 -4
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-write-guard.ts +1235 -102
- package/lib/bun-test-paths.ts +253 -0
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +17 -1
- package/lib/create-sc.ts +45 -12
- package/lib/derived-spec.ts +206 -0
- package/lib/file-claims.ts +335 -0
- package/lib/finding-arbiter.ts +502 -28
- package/lib/finding-jury.ts +61 -5
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +646 -0
- package/lib/generators/agents-md.ts +29 -0
- package/lib/github.ts +112 -7
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +53 -3
- package/lib/issue-filing-gate.ts +1073 -76
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +21 -1
- package/lib/project-state-shape.ts +56 -5
- package/lib/release-preflight.ts +90 -1
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +218 -3
- package/lib/risk-tier.ts +302 -0
- package/lib/rounds-to-pass.ts +274 -0
- package/lib/rule-row-drift.ts +199 -0
- package/lib/sc-claim-forms.ts +33 -5
- package/lib/sc-guard.ts +11 -1
- package/lib/sc-id-cross-tree.ts +17 -2
- package/lib/sc-ids.ts +71 -6
- package/lib/sc-reservations.ts +158 -14
- package/lib/scaffold/ai-review-findings.ts +1369 -27
- package/lib/scaffold/ai-review-step.ts +4095 -119
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +100 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +22 -2
- package/lib/spec-write-ast.ts +728 -0
- package/lib/spec-write-sweep.ts +470 -0
- package/lib/test-suite-lock.ts +127 -13
- package/lib/ts-ast.ts +26 -0
- package/lib/validators/spec-validators.ts +36 -7
- package/lib/write-spec.ts +138 -0
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +330 -12
- package/scripts/audit-specs.ts +225 -24
- package/scripts/convert-spec.ts +7 -2
- package/scripts/create-sc.ts +14 -2
- package/scripts/create-spec.ts +5 -2
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +17 -4
- 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
|
-
//
|
|
67
|
-
//
|
|
68
|
-
//
|
|
69
|
-
process.argv = [
|
|
70
|
-
|
|
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
|
-
"
|
|
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
|
-
|
|
1
|
+
133dd39229ff86fc5f80fce43d9a3c806ad88e9d7d8e27b27688fc1ae27030eb
|
package/gates/gate-executor.ts
CHANGED
|
@@ -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,
|
|
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));
|
package/gates/prove.test.ts
CHANGED
|
@@ -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:
|
|
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:
|
|
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
|
-
|
|
1188
|
-
|
|
1189
|
-
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
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(),
|
package/gates/workflow.test.ts
CHANGED
|
@@ -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
|
-
|
|
1694
|
-
|
|
1695
|
-
|
|
1696
|
-
|
|
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();
|
package/hooks/DocHygiene.hook.ts
CHANGED
|
@@ -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
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
* hook
|
|
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
|
|
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 {
|
|
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);
|