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.
- 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/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- 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/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +12 -0
- 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 +48 -1
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +259 -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 +10 -0
- package/lib/project-state-shape.ts +56 -5
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +65 -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 +1157 -18
- package/lib/scaffold/ai-review-step.ts +3798 -76
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +83 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +16 -0
- package/lib/validators/spec-validators.ts +28 -2
- 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 -23
- package/scripts/create-sc.ts +11 -0
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +12 -0
- 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
|
-
//
|
|
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
|
+
47f8d47ee78dd4b50c501a7cb42b8c220a9511b6d5ce62c6012fe6596440fbe0
|
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
|
});
|
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);
|
|
@@ -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
|
-
|
|
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
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
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
|
-
|
|
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 = [
|