rungate 0.8.0 → 0.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/gates/.gate-salt +1 -0
  2. package/gates/SCHEMA-GUIDE.md +485 -0
  3. package/gates/ac-quality.test.ts +106 -0
  4. package/gates/adversarial.test.ts +283 -0
  5. package/gates/brief-assembler.test.ts +487 -0
  6. package/gates/brief-assembler.ts +448 -0
  7. package/gates/bunfig.toml +2 -0
  8. package/gates/chain.test.ts +91 -0
  9. package/gates/e2e-smoke.test.ts +234 -0
  10. package/gates/error-classifier.test.ts +250 -0
  11. package/gates/error-classifier.ts +99 -0
  12. package/gates/gate-executor.ts +3071 -0
  13. package/gates/orchestrator.test.ts +968 -0
  14. package/gates/orchestrator.ts +827 -0
  15. package/gates/preload.ts +89 -0
  16. package/gates/prompts/ac-adversary.md +20 -0
  17. package/gates/prompts/evidence-validator.md +22 -0
  18. package/gates/prompts/prove-reproducer.md +53 -0
  19. package/gates/prompts.sha256 +3 -0
  20. package/gates/prove.test.ts +164 -0
  21. package/gates/rook-state.test.ts +108 -0
  22. package/gates/run-attribution.ts +290 -0
  23. package/gates/run-gate.ts +163 -0
  24. package/gates/schema-parity.test.ts +378 -0
  25. package/gates/schema.ts +1209 -0
  26. package/gates/self-heal.test.ts +511 -0
  27. package/gates/self-heal.ts +125 -0
  28. package/gates/ship-orchestrator.test.ts +399 -0
  29. package/gates/ship-orchestrator.ts +384 -0
  30. package/gates/spec-compliance-probe.ts +159 -0
  31. package/gates/test-fixtures/broken-no-environments.json +110 -0
  32. package/gates/test-fixtures/consumer-directory-layout.json +90 -0
  33. package/gates/test-fixtures/valid-standard.json +91 -0
  34. package/gates/test-utils.ts +43 -0
  35. package/gates/typecheck-gate.ts +111 -0
  36. package/gates/witness.ts +349 -0
  37. package/gates/workflow.test.ts +2018 -0
  38. package/hooks/BashWriteGuard.hook.ts +19 -0
  39. package/hooks/GateResultProtection.hook.ts +27 -1
  40. package/hooks/VerifyPhaseLock.hook.ts +51 -11
  41. package/hooks/WorkflowStateGuard.hook.ts +24 -0
  42. package/lib/ai-review-rounds.ts +462 -0
  43. package/lib/bash-file-read.ts +17 -3
  44. package/lib/bash-write-guard.ts +1285 -50
  45. package/lib/distribution-standing.ts +75 -4
  46. package/lib/failure-intake.ts +12 -4
  47. package/lib/file-extensions.ts +81 -0
  48. package/lib/finding-arbiter.ts +1015 -0
  49. package/lib/finding-jury.ts +537 -0
  50. package/lib/gate-enforcement.ts +171 -43
  51. package/lib/gate-result-protection.ts +12 -2
  52. package/lib/generators/code-map.ts +55 -4
  53. package/lib/generators/types.ts +27 -1
  54. package/lib/github.ts +55 -0
  55. package/lib/interpreters.ts +64 -0
  56. package/lib/issue-create-override.ts +69 -8
  57. package/lib/issue-filing-gate.ts +605 -0
  58. package/lib/js-top-level-code.ts +20 -2
  59. package/lib/junit-checks.ts +239 -1
  60. package/lib/package-closure.ts +114 -0
  61. package/lib/publish-window.ts +287 -0
  62. package/lib/scaffold/ai-review-findings.ts +142 -3
  63. package/lib/scaffold/ai-review-step.ts +1012 -18
  64. package/lib/scaffold/managed-workflow.ts +163 -4
  65. package/lib/scaffold/steps.ts +498 -22
  66. package/lib/scanner.ts +13 -4
  67. package/lib/ticked-sc-symbols.ts +361 -0
  68. package/lib/transcript-checker.ts +6 -0
  69. package/lib/workflow-actions.ts +18 -0
  70. package/package.json +3 -1
  71. package/scripts/arbitrate-finding.ts +224 -0
  72. package/scripts/generate-code-map.ts +18 -10
  73. package/scripts/sync-sc-status.ts +82 -8
@@ -0,0 +1,90 @@
1
+ {
2
+ "_comment": "Covers #44. A consumer-shaped workflow state, NOT this harness's shape. Every field that differs from valid-standard.json differs because it broke a gate on the first real consumer run, and the difference is the point: a gate change that works on the harness shape and fails on this one must turn a row red. Executed by test/consumer-fixture-gates.test.ts \u2014 if nothing reads this file it is decoration, which is what both fixtures in this directory were until #44.",
3
+ "schemaVersion": 2,
4
+ "issue": 1452,
5
+ "repo": "example-org/example-dashboard",
6
+ "issueRepo": "example-org/example-dashboard",
7
+ "projectRoot": "/tmp/rungate-consumer-fixture",
8
+ "slug": "consumer-directory-layout",
9
+ "phase": "VERIFY",
10
+ "issueGoal": "A consumer-shaped run on the directory config layout, with outcome criteria and healed acceptance criteria",
11
+ "sizing": {
12
+ "predicted": "M",
13
+ "ceremonyTier": "STANDARD"
14
+ },
15
+ "acs": [
16
+ {
17
+ "id": "AC-1",
18
+ "type": "CODE",
19
+ "statement": "The changed module exports the new reader",
20
+ "threshold": {
21
+ "op": "contains",
22
+ "value": "export function readThing"
23
+ },
24
+ "evidenceMethod": {
25
+ "type": "grep",
26
+ "command": "true"
27
+ },
28
+ "verdict": "PENDING"
29
+ },
30
+ {
31
+ "id": "AC-2",
32
+ "type": "OUTCOME",
33
+ "statement": "A report generated from an empty input names the absence rather than printing zero",
34
+ "threshold": {
35
+ "op": "contains",
36
+ "value": "UNMEASURED"
37
+ },
38
+ "evidenceMethod": {
39
+ "type": "COMMAND",
40
+ "command": "true"
41
+ },
42
+ "verdict": "PENDING"
43
+ },
44
+ {
45
+ "id": "AC-3",
46
+ "type": "OUTCOME",
47
+ "statement": "The healed criterion was rewritten after scope stamped its hash",
48
+ "threshold": {
49
+ "op": ">=",
50
+ "value": 2,
51
+ "unit": "rows"
52
+ },
53
+ "evidenceMethod": {
54
+ "type": "COMMAND",
55
+ "command": "true"
56
+ },
57
+ "verdict": "PENDING",
58
+ "_healed": "statement and threshold were rewritten by a heal agent after the scope gate stamped acHash \u2014 see test/consumer-fixture-gates.test.ts"
59
+ }
60
+ ],
61
+ "gates": {
62
+ "scope": {
63
+ "result": "PASS",
64
+ "attempt": 1,
65
+ "failures": [],
66
+ "acHash": "0000000000000000000000000000000000000000000000000000000000000000"
67
+ }
68
+ },
69
+ "environments": {
70
+ "prod": {
71
+ "rebuild": "SKIP",
72
+ "smoke": "SKIP",
73
+ "quinn": "SKIP"
74
+ }
75
+ },
76
+ "agents": {
77
+ "marcus": {
78
+ "spawned": true,
79
+ "verdict": "PASS",
80
+ "branch": "1452-fix",
81
+ "commitSha": "deadbee"
82
+ },
83
+ "quinn": {
84
+ "spawned": false
85
+ }
86
+ },
87
+ "buildCommit": "deadbee",
88
+ "changelog": [],
89
+ "bootstrappedFrom": "ship-workflow"
90
+ }
@@ -0,0 +1,91 @@
1
+ {
2
+ "schemaVersion": 2,
3
+ "issue": 9999,
4
+ "repo": "example-org/example-app",
5
+ "issueRepo": "example-org/example-app",
6
+ "projectRoot": "/tmp/rungate-fixture-project",
7
+ "slug": "test-canary",
8
+ "phase": "DONE",
9
+ "issueGoal": "Test canary issue for harness validation",
10
+ "sizing": {
11
+ "predicted": "XS",
12
+ "ceremonyTier": "LIGHT"
13
+ },
14
+ "acs": [
15
+ {
16
+ "id": "AC-1",
17
+ "type": "CODE",
18
+ "statement": "Test file contains canary comment marker",
19
+ "threshold": {
20
+ "op": "contains",
21
+ "value": "CANARY_MARKER"
22
+ },
23
+ "evidenceMethod": {
24
+ "type": "grep",
25
+ "command": "grep -c CANARY_MARKER test/unit/canary.test.ts"
26
+ },
27
+ "evidence": {
28
+ "type": "command-output",
29
+ "content": "1"
30
+ },
31
+ "verdict": "PASS"
32
+ },
33
+ {
34
+ "id": "AC-2",
35
+ "type": "CODE",
36
+ "statement": "Unit tests pass including canary test",
37
+ "threshold": {
38
+ "op": ">=",
39
+ "value": 2,
40
+ "unit": "passing tests"
41
+ },
42
+ "evidenceMethod": {
43
+ "type": "BUN_TEST",
44
+ "command": "bun test test/unit/canary.test.ts"
45
+ },
46
+ "evidence": {
47
+ "type": "command-output",
48
+ "content": "1 pass, 0 fail"
49
+ },
50
+ "verdict": "PASS"
51
+ }
52
+ ],
53
+ "gates": {
54
+ "scope": {
55
+ "result": "PASS",
56
+ "attempt": 1,
57
+ "failures": []
58
+ },
59
+ "verify": {
60
+ "result": "PASS",
61
+ "attempt": 1,
62
+ "failures": []
63
+ }
64
+ },
65
+ "environments": {
66
+ "local": {
67
+ "api": "PASS",
68
+ "ui": "PASS",
69
+ "tests": "PASS"
70
+ },
71
+ "prod": {
72
+ "rebuild": "SKIP",
73
+ "smoke": "SKIP",
74
+ "quinn": "SKIP"
75
+ }
76
+ },
77
+ "agents": {
78
+ "marcus": {
79
+ "spawned": true,
80
+ "verdict": "PASS",
81
+ "branch": "9999-fix",
82
+ "commitSha": "abc1234"
83
+ },
84
+ "quinn": {
85
+ "spawned": false
86
+ }
87
+ },
88
+ "buildCommit": "abc1234",
89
+ "changelog": [],
90
+ "bootstrappedFrom": "ship-workflow"
91
+ }
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Shared test utilities for gate test files.
3
+ *
4
+ * Provides safe accessors for workflow-state.json with graceful
5
+ * error handling when no active workflow is present (standalone runs).
6
+ */
7
+ import { readFileSync, existsSync } from "fs";
8
+
9
+ /**
10
+ * Whether the test suite is running in standalone mode (no active workflow).
11
+ * When true, tests that depend on workflow-state.json should skip.
12
+ */
13
+ export const STANDALONE = !process.env.TEST_WORK_DIR;
14
+
15
+ /**
16
+ * Safely read and parse a JSON file. Returns null on ENOENT or parse error.
17
+ */
18
+ export function safeReadJson(path: string): any | null {
19
+ if (!existsSync(path)) return null;
20
+ try {
21
+ return JSON.parse(readFileSync(path, "utf-8"));
22
+ } catch {
23
+ return null;
24
+ }
25
+ }
26
+
27
+ /**
28
+ * Create a safe workflow-state accessor for a given file path.
29
+ * Returns undefined for any path if the file doesn't exist.
30
+ */
31
+ export function createSf(statePath: string): (path: string) => any {
32
+ return (path: string): any => {
33
+ const raw = safeReadJson(statePath);
34
+ if (!raw) return undefined;
35
+ const parts = path.replace(/^\./, "").split(".").filter(Boolean);
36
+ let val: any = raw;
37
+ for (const p of parts) {
38
+ if (val == null) return undefined;
39
+ val = val[p];
40
+ }
41
+ return val;
42
+ };
43
+ }
@@ -0,0 +1,111 @@
1
+ /**
2
+ * The comparison half of the `tsc-pass` gate check (#176).
3
+ *
4
+ * The check in gates/workflow.test.ts was two early returns and an empty tail:
5
+ * no `expect`, no tsc invocation, no baseline comparison, under a name that
6
+ * promises all three. Its second return read `environments.local.tests` and
7
+ * bailed with the comment `// trust Marcus` — a gate asking the agent it is
8
+ * gating whether it needs to run.
9
+ *
10
+ * The rules below are scripts/typecheck.ts's, with one deliberate difference:
11
+ * that script is a ratchet and fails on FEWER errors than the baseline so
12
+ * progress gets banked, while this is a gate on one issue's work and only owes
13
+ * an answer to "did this run add errors". Unbanked progress warns here.
14
+ *
15
+ * Kept out of the test file so it can be unit-tested without spawning tsc, and
16
+ * so the branches below are reachable from a test that plants each one.
17
+ */
18
+
19
+ /** `path/to/file.ts(12,34): error TS1234: message` */
20
+ export const TSC_ERROR_LINE = /^\S.*\(\d+,\d+\): error TS\d+:/;
21
+
22
+ export function countTscErrors(output: string): number {
23
+ return output.split("\n").filter((l) => TSC_ERROR_LINE.test(l)).length;
24
+ }
25
+
26
+ export interface TscRun {
27
+ /** tsc's exit status, or null when it was killed or never started. */
28
+ status: number | null;
29
+ /** stdout and stderr concatenated — tsc writes diagnostics to stdout. */
30
+ output: string;
31
+ }
32
+
33
+ /**
34
+ * Everything wrong with this typecheck run. Empty means the gate passes.
35
+ *
36
+ * `baselineRaw` is the literal contents of the project's
37
+ * `.claude/typecheck-baseline.json`, or null when the file is absent. Absent
38
+ * means a declared tolerance of zero: a project that has not written the file
39
+ * down has not claimed any errors are acceptable. Unreadable is NOT zero —
40
+ * `{"error": 0}` is a one-character edit away from `{"errors": 0}` and reading
41
+ * it as "no baseline" would disable the gate while still printing a result.
42
+ */
43
+ export function typecheckFailures(run: TscRun, baselineRaw: string | null): string[] {
44
+ const failures: string[] = [];
45
+
46
+ const baseline = readBaseline(baselineRaw);
47
+ if (typeof baseline === "string") return [baseline];
48
+
49
+ // tsc with no usable config prints its help text and exits 1. Counting zero
50
+ // parseable diagnostics out of that reads as a clean typecheck — the exact
51
+ // defect #65/#76 found in the documented `bunx tsc --noEmit`.
52
+ if (/tsc: The TypeScript Compiler/.test(run.output)) {
53
+ return ["tsc printed its usage text instead of checking anything: " + run.output.slice(0, 300)];
54
+ }
55
+
56
+ const actual = countTscErrors(run.output);
57
+
58
+ if (run.status === null) {
59
+ return ["tsc did not run to completion (no exit status) — refusing to report a clean typecheck"];
60
+ }
61
+
62
+ // Config-level problems (TS18003 "no inputs were found", TS5083 "cannot read
63
+ // file") carry no file(line,col) prefix, so the count is zero and the run
64
+ // looks clean. Trust the exit status over the parse.
65
+ if (run.status !== 0 && actual === 0) {
66
+ failures.push(
67
+ `tsc exited ${run.status} but produced no parseable diagnostics — treating as failure, ` +
68
+ `not as a clean run:\n${run.output.slice(0, 500)}`,
69
+ );
70
+ return failures;
71
+ }
72
+
73
+ if (actual > baseline) {
74
+ failures.push(
75
+ `${actual} TypeScript errors, baseline is ${baseline} — ${actual - baseline} new error(s):\n` +
76
+ run.output
77
+ .split("\n")
78
+ .filter((l) => TSC_ERROR_LINE.test(l))
79
+ .slice(0, 20)
80
+ .join("\n"),
81
+ );
82
+ } else if (actual < baseline) {
83
+ // Not a gate failure: the gate's question is whether THIS run added
84
+ // errors. Banking the progress is scripts/typecheck.ts's job.
85
+ console.warn(
86
+ `WARN: tsc-pass: ${actual} errors against a baseline of ${baseline} — ` +
87
+ `bank it with \`bun scripts/typecheck.ts --update-baseline\` so it cannot drift back up.`,
88
+ );
89
+ }
90
+
91
+ return failures;
92
+ }
93
+
94
+ /** The baseline count, or a failure message when the file cannot be trusted. */
95
+ function readBaseline(raw: string | null): number | string {
96
+ if (raw === null) return 0;
97
+ let parsed: unknown;
98
+ try {
99
+ parsed = JSON.parse(raw);
100
+ } catch (e) {
101
+ return `.claude/typecheck-baseline.json is not valid JSON: ${(e as Error).message}`;
102
+ }
103
+ const n = (parsed as { errors?: unknown } | null)?.errors;
104
+ if (typeof n !== "number" || !Number.isInteger(n) || n < 0) {
105
+ return (
106
+ `.claude/typecheck-baseline.json has no integer "errors" field (got ${JSON.stringify(n)}). ` +
107
+ `Refusing to report a result against a baseline I cannot read.`
108
+ );
109
+ }
110
+ return n;
111
+ }
@@ -0,0 +1,349 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * witness.ts — Tamper-evident witness signing and verification
4
+ *
5
+ * Issue: #471
6
+ * ADR: ADR-008 (harness v3)
7
+ *
8
+ * Provides HMAC-signed witness files for gate results.
9
+ * Used by run-gate.ts (write) and pre-push (verify).
10
+ *
11
+ * Witness chain: scope -> verify -> ship
12
+ * Each witness stores gate result + commit SHA + HMAC signature.
13
+ */
14
+
15
+ import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs";
16
+ import { join } from "path";
17
+ import { createHmac } from "crypto";
18
+ import { execSync } from "child_process";
19
+
20
+ import { gateSaltPath } from "../lib/paths";
21
+
22
+ const GATE_SALT_PATH = gateSaltPath();
23
+
24
+ const REQUIRED_GATES = ["scope", "ship"] as const;
25
+
26
+ // ── Gate contract interfaces (SC-373) ─────────────────────────────────────
27
+
28
+ export interface WriteWitnessInput {
29
+ slug: string;
30
+ gate: string;
31
+ result: "PASS" | "FAIL";
32
+ testOutput: string;
33
+ issue?: number;
34
+ projectRoot?: string;
35
+ }
36
+
37
+ export interface VerifyWitnessResult {
38
+ valid: boolean;
39
+ record: WitnessRecord | null;
40
+ error?: string;
41
+ }
42
+
43
+ export interface WitnessRecord {
44
+ gate: string;
45
+ result: "PASS" | "FAIL";
46
+ slug: string;
47
+ issue: number;
48
+ commitSha: string;
49
+ timestamp: string;
50
+ testOutputHash: string;
51
+ hmac: string;
52
+ }
53
+
54
+ // ── Internal helpers ────────────────────────────────────────────────
55
+
56
+ function getSalt(saltPath: string = GATE_SALT_PATH): string {
57
+ if (!existsSync(saltPath)) {
58
+ throw new Error(`Gate salt not found at ${saltPath}`);
59
+ }
60
+ return readFileSync(saltPath, "utf-8").trim();
61
+ }
62
+
63
+ function gitSha(cwd?: string): string {
64
+ try {
65
+ return execSync("git rev-parse HEAD", { encoding: "utf-8", timeout: 5000, cwd }).trim();
66
+ } catch {
67
+ return "unknown";
68
+ }
69
+ }
70
+
71
+ function hashTestOutput(testOutput: string): string {
72
+ return createHmac("sha256", "test-output")
73
+ .update(testOutput)
74
+ .digest("hex")
75
+ .slice(0, 16);
76
+ }
77
+
78
+ function computeHmac(record: Omit<WitnessRecord, "hmac">): string {
79
+ const salt = getSalt();
80
+ const input = [
81
+ record.gate,
82
+ record.result,
83
+ record.slug,
84
+ record.issue,
85
+ record.commitSha,
86
+ record.timestamp,
87
+ record.testOutputHash,
88
+ ].join(":");
89
+ return createHmac("sha256", salt).update(input).digest("hex").slice(0, 16);
90
+ }
91
+
92
+ /**
93
+ * The exact bytes a census signature is taken over (#494).
94
+ *
95
+ * Named and exported so there is ONE definition of what is signed. A signer
96
+ * and a verifier that each built their own string would agree on every
97
+ * census anyone had tried and disagree on the first one nobody had.
98
+ *
99
+ * Three properties, each because of something an erasing agent could
100
+ * otherwise do:
101
+ *
102
+ * - **Sorted keys**, so the signature is over the READING and not over the
103
+ * order `censusOf` happened to walk the tree in. A signature that moved
104
+ * when the walk order moved would read as tampering on every platform
105
+ * whose `readdir` order differs.
106
+ * - **The slug**, so a census and signature lifted out of another run's
107
+ * state file on the same machine do not verify here. The salt is shared
108
+ * across runs; without the slug, every run's signature is every other
109
+ * run's signature.
110
+ * - **The file count**, so two different censuses cannot produce the same
111
+ * signing input through a path containing the separator.
112
+ */
113
+ export function censusSigningInput(
114
+ slug: string,
115
+ census: Record<string, number>,
116
+ reader?: string,
117
+ ): string {
118
+ const entries = Object.keys(census)
119
+ .sort()
120
+ .map(file => `${file}=${census[file]}`);
121
+ // `reader=` sits BEFORE `files=`, and that position is the domain
122
+ // separation (#883). Every entry line comes AFTER `files=N`, so no v1
123
+ // input can be spelled the same as a v2 input — not even a census whose
124
+ // one file is literally named `reader`.
125
+ const head = reader === undefined ? [`slug=${slug}`] : [`slug=${slug}`, `reader=${reader}`];
126
+ return [...head, `files=${entries.length}`, ...entries].join("\n");
127
+ }
128
+
129
+ /**
130
+ * Sign a banked test census (#494).
131
+ *
132
+ * #307's census lived in the run's `workflow-state.json` — a file the heal
133
+ * agent is handed a write recipe for, by name: `workflows/ship.js` tells it
134
+ * `Edit workflow-state.json ONLY via writeWorkflowState():` and then hands
135
+ * over a working one-liner, at both heal sites.
136
+ * An agent that deleted a test and the census together saw `first-reading`
137
+ * on the next round, which increments neither `fails` nor `warns`.
138
+ *
139
+ * Tamper-EVIDENT, not tamper-proof, and that is the intended goal: the salt
140
+ * is readable by anything running as this user, so a determined agent can
141
+ * re-sign. What it can no longer do is make the erasure look like an
142
+ * ordinary first round.
143
+ *
144
+ * Throws when the salt is absent, like every other reader here. A silently
145
+ * unsigned census is the same hole one layer down —
146
+ * `persistTestCensus` records that it could not sign instead of pretending
147
+ * it did, and the next round reads the unsigned census as UNMEASURED.
148
+ *
149
+ * **This is the v1 payload and nothing writes it any more.** It is reachable
150
+ * so that a genuinely pre-#883 state file — a census with no reader stamp —
151
+ * can still be verified and reported as a migration rather than a tamper.
152
+ * Everything the gate banks is signed by `signStampedCensus` below.
153
+ */
154
+ export function signCensus(
155
+ slug: string,
156
+ census: Record<string, number>,
157
+ saltPath: string = GATE_SALT_PATH,
158
+ ): string {
159
+ return createHmac("sha256", getSalt(saltPath))
160
+ .update(censusSigningInput(slug, census))
161
+ .digest("hex")
162
+ .slice(0, 16);
163
+ }
164
+
165
+ /**
166
+ * Sign a banked census together with the reader that took it (#883).
167
+ *
168
+ * #883 added `gateContract.testCensusReader` so a census taken by another
169
+ * instrument reads UNMEASURED instead of as a cliff of deleted tests. Signing
170
+ * the census and not the stamp made that arm a way PAST the #494 refusal it
171
+ * sits beside, and the first draft of this change shipped with a docblock on
172
+ * `TEST_CENSUS_READER` asserting the opposite — *"it is NOT a security
173
+ * control… that agent can already delete the census outright"*. That is the
174
+ * argument that let it through, and it is wrong in both halves:
175
+ *
176
+ * - Flipping one unsigned byte is cheaper than deleting the census, and
177
+ * quieter. The census still verifies, so the round reports a WARN whose
178
+ * text explains a legitimate migration, with no refusal anywhere.
179
+ * - It is not merely a missed refusal for one round. `nextCensus` BANKS the
180
+ * current reading on a reader change, by design, so the lowered count
181
+ * becomes the baseline and the next round is clean. The erasure is
182
+ * laundered into the record.
183
+ *
184
+ * So a PRESENT stamp is covered by the signature. An ABSENT one is accepted
185
+ * only against the v1 payload, which is the one shape no agent can mint by
186
+ * writing a stamp — and writing one onto a real pre-#883 file now reads as
187
+ * the rewrite it is.
188
+ *
189
+ * Still tamper-EVIDENT and not tamper-proof: the salt is readable by anything
190
+ * running as this user. The boundary is unchanged, and it is the salt.
191
+ */
192
+ export function signStampedCensus(
193
+ slug: string,
194
+ census: Record<string, number>,
195
+ reader: string,
196
+ saltPath: string = GATE_SALT_PATH,
197
+ ): string {
198
+ return createHmac("sha256", getSalt(saltPath))
199
+ .update(censusSigningInput(slug, census, reader))
200
+ .digest("hex")
201
+ .slice(0, 16);
202
+ }
203
+
204
+ // ── Public API ──────────────────────────────────────────────────────
205
+
206
+ /**
207
+ * Write a signed witness file after gate execution.
208
+ * Returns the path to the witness file.
209
+ */
210
+ export function writeWitness(
211
+ slug: string,
212
+ gate: string,
213
+ result: "PASS" | "FAIL",
214
+ testOutput: string,
215
+ issue: number = 0,
216
+ projectRoot?: string,
217
+ ): string {
218
+ const base = process.env.RUNGATE_WORK_DIR || join(process.env.HOME || "", ".rungate");
219
+ const wDir = join(base, slug);
220
+ const witnessDir = join(wDir, "witnesses");
221
+ mkdirSync(witnessDir, { recursive: true });
222
+
223
+ const ts = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
224
+ const commitSha = gitSha(projectRoot);
225
+ const testOutputHash = hashTestOutput(testOutput);
226
+
227
+ const record: Omit<WitnessRecord, "hmac"> = {
228
+ gate,
229
+ result,
230
+ slug,
231
+ issue,
232
+ commitSha,
233
+ timestamp: ts,
234
+ testOutputHash,
235
+ };
236
+
237
+ const hmac = computeHmac(record);
238
+ const witness: WitnessRecord = { ...record, hmac };
239
+
240
+ const filename = `${gate}-${ts.replace(/[:.]/g, "-")}.json`;
241
+ const witnessPath = join(witnessDir, filename);
242
+ writeFileSync(witnessPath, JSON.stringify(witness, null, 2) + "\n");
243
+
244
+ return witnessPath;
245
+ }
246
+
247
+ /**
248
+ * Verify a single witness file's HMAC signature.
249
+ * Returns { valid, record, error? }
250
+ */
251
+ export function verifyWitness(
252
+ witnessPath: string,
253
+ ): { valid: boolean; record: WitnessRecord | null; error?: string } {
254
+ if (!existsSync(witnessPath)) {
255
+ return { valid: false, record: null, error: "Witness file not found" };
256
+ }
257
+
258
+ let record: WitnessRecord;
259
+ try {
260
+ record = JSON.parse(readFileSync(witnessPath, "utf-8"));
261
+ } catch {
262
+ return { valid: false, record: null, error: "Invalid JSON in witness file" };
263
+ }
264
+
265
+ // Check required fields
266
+ const required = ["gate", "result", "slug", "issue", "commitSha", "timestamp", "testOutputHash", "hmac"];
267
+ for (const field of required) {
268
+ if (!(field in record)) {
269
+ return { valid: false, record, error: `Missing field: ${field}` };
270
+ }
271
+ }
272
+
273
+ // Verify HMAC
274
+ const { hmac: storedHmac, ...fields } = record;
275
+ let expectedHmac: string;
276
+ try {
277
+ expectedHmac = computeHmac(fields);
278
+ } catch (e: any) {
279
+ return { valid: false, record, error: `HMAC computation failed: ${e.message}` };
280
+ }
281
+
282
+ if (storedHmac !== expectedHmac) {
283
+ return { valid: false, record, error: `HMAC mismatch: stored=${storedHmac}, expected=${expectedHmac}` };
284
+ }
285
+
286
+ return { valid: true, record };
287
+ }
288
+
289
+ /**
290
+ * Verify the complete witness chain for a workflow.
291
+ * Checks: required gates present, HMACs valid, latest SHA matches HEAD.
292
+ *
293
+ * Returns { valid, errors[], witnesses[] }
294
+ */
295
+ export function verifyWitnessChain(
296
+ slug: string,
297
+ headSha?: string,
298
+ ): { valid: boolean; errors: string[]; witnesses: WitnessRecord[] } {
299
+ const base = process.env.RUNGATE_WORK_DIR || join(process.env.HOME || "", ".rungate");
300
+ const wDir = join(base, slug);
301
+ const witnessDir = join(wDir, "witnesses");
302
+ const errors: string[] = [];
303
+ const witnesses: WitnessRecord[] = [];
304
+
305
+ if (!existsSync(witnessDir)) {
306
+ return { valid: false, errors: ["No witnesses directory found"], witnesses };
307
+ }
308
+
309
+ // Read all witness files
310
+ const files = readdirSync(witnessDir).filter(f => f.endsWith(".json")).sort();
311
+ if (files.length === 0) {
312
+ return { valid: false, errors: ["No witness files found"], witnesses };
313
+ }
314
+
315
+ // Verify each witness
316
+ for (const file of files) {
317
+ const result = verifyWitness(join(witnessDir, file));
318
+ if (!result.valid) {
319
+ errors.push(`${file}: ${result.error}`);
320
+ }
321
+ if (result.record) {
322
+ witnesses.push(result.record);
323
+ }
324
+ }
325
+
326
+ // Check required gates have PASS witnesses
327
+ const passedGates = new Set(
328
+ witnesses
329
+ .filter(w => w.result === "PASS")
330
+ .map(w => w.gate),
331
+ );
332
+
333
+ for (const gate of REQUIRED_GATES) {
334
+ if (!passedGates.has(gate)) {
335
+ errors.push(`Missing PASS witness for required gate: ${gate}`);
336
+ }
337
+ }
338
+
339
+ // Check latest witness commitSha matches HEAD
340
+ const currentHead = headSha || gitSha();
341
+ const latestWitness = witnesses[witnesses.length - 1];
342
+ if (latestWitness && latestWitness.commitSha !== currentHead) {
343
+ errors.push(
344
+ `Stale witness: latest commitSha=${latestWitness.commitSha} but HEAD=${currentHead}`,
345
+ );
346
+ }
347
+
348
+ return { valid: errors.length === 0, errors, witnesses };
349
+ }