rungate 0.5.0 → 0.7.0

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 (142) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -0,0 +1,93 @@
1
+ /**
2
+ * The one pin for `google-github-actions/auth` (#689, applied to #631).
3
+ *
4
+ * `lib/claude-code-action.ts` is the sibling of this file and the model for
5
+ * it. The defect is the same one, found a second time in a second action, in
6
+ * a fleet rather than in one repository:
7
+ *
8
+ * | Position | Pin | Comment | What it actually was |
9
+ * |---|---|---|---|
10
+ * | `.github/workflows/claude-review.yml` | `c200f369` | `# v2` | v2 |
11
+ * | agentgrit's generated `.github/workflows/ai-review.yml` | `7c6bc770` | `# v3` | v3 |
12
+ *
13
+ * Two positions, two values, nothing comparing them — which is #689 exactly.
14
+ * Note what is DIFFERENT from #689 and worth saying rather than glossing:
15
+ * **both pins were accurate.** Neither comment lied. They name two different
16
+ * major versions of one action, chosen independently by two sessions that
17
+ * could not see each other, and a reader of either file has no way to learn
18
+ * that the other exists. A check that only catches a wrong comment would
19
+ * report this tree clean.
20
+ *
21
+ * ## Why v2 and not v3
22
+ *
23
+ * v3 is the latest release (`gh api .../releases/latest` → `v3`, read
24
+ * 2026-10-20). It is not the measured one.
25
+ *
26
+ * `c200f369` is the pin on `.github/workflows/claude-review.yml`, which is the
27
+ * only configuration in this fleet that has ever authenticated to Vertex at
28
+ * all: verified 2026-10-19 against the project named by this repository's own
29
+ * `ci.vertex` block, `claude-sonnet-5` returning HTTP 200 from `rawPredict` at
30
+ * location `global`, with no service-account key. The project is not named
31
+ * here on purpose — `SC-A1` refuses a consumer's name in the harness and a
32
+ * sentence quoting one is indistinguishable, to a scanner, from a value. The
33
+ * other repository's v3 pin has never run — it holds no `GCP_SA_KEY` and its
34
+ * generated job resolves mode `none` on every run — so adopting it would be
35
+ * adopting the untested half of a disagreement because it has the larger
36
+ * number on it.
37
+ *
38
+ * Both majors accept `workload_identity_provider` and neither accepts a
39
+ * directory for the credentials file, so the choice buys no behaviour either
40
+ * way. It is a choice between a reading and a version string, and this repo's
41
+ * rule is to keep the reading. Bumping to v3 is a deliberate edit to this
42
+ * file plus a re-measurement, and `actionPinParity` makes every consumer
43
+ * position follow it in the same commit.
44
+ *
45
+ * ## How the SHA was established, and the trap in establishing it
46
+ *
47
+ * ```
48
+ * $ gh api repos/google-github-actions/auth/commits/v2 --jq .sha
49
+ * → c200f3691d83b41bf9bbd8638997a462592937ed
50
+ * $ gh api repos/google-github-actions/auth/commits/v3 --jq .sha
51
+ * → 7c6bc770dae815cd3e89ee6cdf493a5fab2cc093
52
+ * ```
53
+ *
54
+ * `commits/vN` dereferences the tag for you. Do NOT read `.object.sha` off
55
+ * `git/ref/tags/vN` and stop: these are ANNOTATED tags, so that path returns a
56
+ * TAG object and the commit is one dereference further down. #689's own
57
+ * resolution step made exactly that error and concluded from it that neither
58
+ * pinned SHA was the tag it claimed. Both of these are.
59
+ *
60
+ * ## What this does NOT do
61
+ *
62
+ * It does not keep itself fresh. `v2` is a MOVING tag upstream, so
63
+ * `RESOLVED_ON` dates the reading rather than certifying it. Nothing here
64
+ * fails when the pin goes stale — see `lib/claude-code-action.ts` and #377.
65
+ */
66
+
67
+ /** The action, by the name a `uses:` line spells. */
68
+ export const GOOGLE_AUTH_ACTION = "google-github-actions/auth";
69
+
70
+ /**
71
+ * The commit `refs/tags/v2` dereferences to, resolved on `RESOLVED_ON`.
72
+ * A full 40-character commit SHA, because that is the only form of a `uses:`
73
+ * reference the publisher cannot repoint.
74
+ */
75
+ export const GOOGLE_AUTH_ACTION_SHA = "c200f3691d83b41bf9bbd8638997a462592937ed";
76
+
77
+ /**
78
+ * The tag that SHA was v2 of, carried here so the trailing `# vN` comment in
79
+ * every position is DERIVED from the same declaration as the pin. A comment
80
+ * that can disagree with the pin it annotates is worse than no comment.
81
+ */
82
+ export const GOOGLE_AUTH_ACTION_VERSION = "v2";
83
+
84
+ /** The day the tag was dereferenced. A moving tag's reading needs a date. */
85
+ export const GOOGLE_AUTH_ACTION_RESOLVED_ON = "2026-10-20";
86
+
87
+ /**
88
+ * The exact text a position's `uses:` value must carry — pin and comment in
89
+ * one rendering, so there is one thing to mutate and no way to update half.
90
+ */
91
+ export function googleAuthActionRef(): string {
92
+ return `${GOOGLE_AUTH_ACTION}@${GOOGLE_AUTH_ACTION_SHA} # ${GOOGLE_AUTH_ACTION_VERSION}`;
93
+ }
@@ -0,0 +1,48 @@
1
+ /**
2
+ * "Is this directory inside a rungate-harnessed project?" — one decider.
3
+ *
4
+ * Lifted out of `hooks/BashToolGuard.hook.ts`, where it was a private
5
+ * function, because #992 needs the same question answered by a second hook.
6
+ * A second inline copy would be two deciders for one question, which is this
7
+ * repository's most frequently repeated defect and is named as the thing to
8
+ * avoid in #992's own comments.
9
+ *
10
+ * ## Why hooks need this at all
11
+ *
12
+ * A hook registered at USER level fires for every Claude Code session on the
13
+ * machine, including projects that have nothing to do with rungate. Scoping
14
+ * cannot live in the registration: project-level hooks do not reach worktree
15
+ * subagents, so user-level registration is required and the scope check has
16
+ * to be in the hook.
17
+ *
18
+ * ## Both markers, deliberately
19
+ *
20
+ * Config is migrating from the monolithic `.claude/rungate.json` to the
21
+ * directory form `.claude/rungate/` (`CONFIG-DIRECTORY-STRUCTURE-SPEC.md`),
22
+ * and `lib/config-loader.ts` reads the directory and falls back to the file.
23
+ * Checking only one marker would silently go quiet for every project on the
24
+ * other layout — a hook that stops firing and a project that is not
25
+ * harnessed look identical from outside.
26
+ *
27
+ * This deliberately does NOT call `loadRungateConfig`: that throws on a
28
+ * malformed config, and a hook on every Bash call must not turn a bad config
29
+ * into a crash. The question here is "is there a harness here", not "is it
30
+ * valid".
31
+ *
32
+ * Issue: #992. Extracted from #COMP-7's `BashToolGuard`.
33
+ */
34
+
35
+ import { existsSync } from "fs";
36
+ import { dirname, join } from "path";
37
+
38
+ /** True when `startDir` sits at or below a rungate-harnessed project. */
39
+ export function isHarnessProject(startDir: string): boolean {
40
+ let dir = startDir;
41
+ while (true) {
42
+ const claude = join(dir, ".claude");
43
+ if (existsSync(join(claude, "rungate.json")) || existsSync(join(claude, "rungate"))) return true;
44
+ const parent = dirname(dir);
45
+ if (parent === dir) return false;
46
+ dir = parent;
47
+ }
48
+ }
@@ -0,0 +1,255 @@
1
+ /**
2
+ * Which harness graded this run? (#602)
3
+ *
4
+ * ## The silence, not the version
5
+ *
6
+ * `workflows/ship.js` resolves its gate machinery out of `harnessRoot` —
7
+ * a checkout on somebody's disk — and nothing has ever said which version
8
+ * that was. On 2026-10-18 the primary was 82 files and 10,527 insertions
9
+ * behind `origin/main`, including 44 lines of `gates/schema.ts` and 22 of
10
+ * `lib/evidence-prevalidator.ts`. Three runs that session were graded by a
11
+ * validator missing changes those very runs merged.
12
+ *
13
+ * **A stale harness and a current one emit byte-identical artefacts.**
14
+ * That is the whole defect: not that the checkout drifts — checkouts drift
15
+ * — but that a run reporting PASS cannot be distinguished from a run that
16
+ * reported PASS because the refusal had not been written yet.
17
+ *
18
+ * The direction is the bad one. A stale harness is strictly MORE
19
+ * permissive, because every refusal added since the checkout last moved is
20
+ * simply absent.
21
+ *
22
+ * ## What this does not do
23
+ *
24
+ * It does not pull, and it must not. Swapping `gates/` and `lib/` under a
25
+ * run already in flight produces a half-old, half-new grade that nothing
26
+ * can reproduce. It does not fetch either: a fetch is a network side
27
+ * effect in the middle of a grade, and an offline run would then report a
28
+ * staleness it had invented. It reads what is already on disk and says so.
29
+ *
30
+ * ## Three readings, and `UNMEASURED` is one of them
31
+ *
32
+ * `0`, `{}`, `null` and silence are indistinguishable from success;
33
+ * UNMEASURED is not (`.claude/rules/config-access.md`). A harness whose
34
+ * SHA cannot be read has not been proven current — it has not been
35
+ * *asked*, and those are different states.
36
+ */
37
+ import { spawnSync } from "child_process";
38
+
39
+ import { isCommitSha } from "./commit-sha";
40
+
41
+ /**
42
+ * The directories a run's grade actually depends on.
43
+ *
44
+ * Not the whole tree. A dirty `README.md` does not change a verdict, and a
45
+ * check that refused on one would be a refusal everybody learns to click
46
+ * past — which is worse than no check, because it trains people past the
47
+ * cases that matter. These four are what a run's verdict comes out of:
48
+ * `gates/` is the gate machinery, `lib/` is everything the gates import,
49
+ * `workflows/` is the run script itself, and `scripts/` is where that
50
+ * script's every measurement actually happens — `ship.js` has no
51
+ * filesystem and no subprocess (#69), so it reaches a verdict by having an
52
+ * agent run `scripts/record-suite-measurement.ts`,
53
+ * `scripts/grade-deterministic.ts`, `scripts/rook-review-scope.ts` and
54
+ * `scripts/verify-no-deleted-cases.ts`, among sixteen.
55
+ *
56
+ * `scripts/` was missing from the first draft of this list, which is the
57
+ * defect this module is about with the scope one directory too narrow: a
58
+ * harness whose deletion check had been edited in place would have
59
+ * reported MEASURED and clean. `test/unit/harness-provenance.test.ts`
60
+ * holds the list against what `ship.js` actually invokes, so a new grading
61
+ * directory cannot fall outside the reading unnoticed.
62
+ */
63
+ export const GRADING_PATHS = ["gates", "lib", "scripts", "workflows"] as const;
64
+
65
+ export type HarnessProvenance =
66
+ | {
67
+ reading: "MEASURED";
68
+ /** HEAD of the harness checkout, as a SHA — never a ref name. */
69
+ sha: string;
70
+ /** The branch HEAD is on, or `null` when detached. Informational. */
71
+ branch: string | null;
72
+ /**
73
+ * Paths under `GRADING_PATHS` with uncommitted changes. Empty means
74
+ * clean, and it means it because the probe succeeded — an unreadable
75
+ * status makes the whole reading UNMEASURED rather than this empty.
76
+ */
77
+ dirty: string[];
78
+ /**
79
+ * Commits HEAD is behind its configured upstream, or `null` when
80
+ * there is no upstream to compare against.
81
+ *
82
+ * `null` is NOT zero. A checkout with no upstream is one nobody can
83
+ * say anything about, and reporting 0 for it would be the silent
84
+ * default this module exists to refuse.
85
+ */
86
+ behind: number | null;
87
+ /** Why `behind` is null, when it is. `null` when it is a number. */
88
+ behindReason: string | null;
89
+ }
90
+ | { reading: "UNMEASURED"; reason: string };
91
+
92
+ /**
93
+ * `raw` is the untrimmed stdout and `out` is the trimmed one.
94
+ *
95
+ * Both, because porcelain status is COLUMN-SIGNIFICANT: a modified file
96
+ * arrives as `" M gates/schema.ts"`, and trimming eats the leading space
97
+ * so any fixed-width slice then cuts one character into the path. That
98
+ * produced `"ates/schema.ts"` here, caught by this module's own test.
99
+ * Every other probe in this file wants the trimmed form.
100
+ */
101
+ function git(root: string, args: string[]): { out: string; raw: string; ok: boolean; err: string } {
102
+ const r = spawnSync("git", ["-C", root, ...args], { timeout: 15_000, encoding: "utf-8" });
103
+ if (r.error) return { out: "", raw: "", ok: false, err: r.error.message };
104
+ const raw = String(r.stdout ?? "");
105
+ return {
106
+ out: raw.trim(),
107
+ raw,
108
+ ok: r.status === 0,
109
+ err: String(r.stderr ?? "").trim().split("\n")[0] ?? "",
110
+ };
111
+ }
112
+
113
+ /**
114
+ * The paths in a `git status --porcelain -z` reading.
115
+ *
116
+ * `-z` for the reason `lib/test-case-deletion.ts` gives at greater
117
+ * length: without it, any path with a non-ASCII byte, a quote, a tab or a
118
+ * newline comes back C-quoted — `"caf\303\251.ts"`, quotes included — and
119
+ * the name in the report is then not the name on disk.
120
+ *
121
+ * A rename record is `XY <new>\0<old>`, so the field after one is an
122
+ * ORIGIN path and not a status record. Treating it as one would report a
123
+ * path with its first three characters eaten, which is the same defect
124
+ * this function exists to avoid, arriving from the other side.
125
+ */
126
+ export function porcelainPaths(raw: string): string[] {
127
+ const fields = raw.split("\0").filter(f => f !== "");
128
+ const paths: string[] = [];
129
+ for (let i = 0; i < fields.length; i++) {
130
+ const f = fields[i];
131
+ if (f.length < 4) continue;
132
+ paths.push(f.slice(3));
133
+ // R and C carry their source path in the next field. Skip it.
134
+ if (f[0] === "R" || f[0] === "C" || f[1] === "R" || f[1] === "C") i++;
135
+ }
136
+ return paths.sort();
137
+ }
138
+
139
+ /**
140
+ * The provenance of one harness checkout.
141
+ *
142
+ * ONE discriminator, `reading`. Every field is a projection of the probes
143
+ * taken here and nowhere else, so no two of them can disagree, and a
144
+ * caller wanting a boolean derives it with `harnessProvenanceWarning`
145
+ * rather than re-asking git.
146
+ */
147
+ export function harnessProvenance(harnessRoot: string): HarnessProvenance {
148
+ const root = String(harnessRoot ?? "");
149
+ if (!root.trim()) {
150
+ return { reading: "UNMEASURED", reason: "no harnessRoot was given, so there is no checkout to read" };
151
+ }
152
+
153
+ const head = git(root, ["rev-parse", "HEAD"]);
154
+ if (!head.ok || !isCommitSha(head.out)) {
155
+ return {
156
+ reading: "UNMEASURED",
157
+ reason:
158
+ `the harness checkout at ${JSON.stringify(root)} has no readable HEAD ` +
159
+ `(${head.err || `git printed ${JSON.stringify(head.out)}`}), so nothing says which harness graded this run`,
160
+ };
161
+ }
162
+
163
+ // `--porcelain` with explicit pathspecs, so the reading is scoped to what
164
+ // a grade depends on and the format is the stable one. Untracked files
165
+ // count: an untracked `lib/x.ts` is loadable code the remote does not
166
+ // have, which is the same divergence as a modified one.
167
+ //
168
+ // `-uall` is load-bearing and not a flourish. The default collapses
169
+ // untracked files into their containing directory — a brand-new
170
+ // `workflows/ship.js` is reported as `workflows/`, and a wholly
171
+ // untracked `gates/` is reported as `gates/` whether it holds one file
172
+ // or a hundred. The reading would then name a directory in a message
173
+ // whose job is to tell an operator which file to look at, and a
174
+ // one-file divergence and a hundred-file one would be the same string.
175
+ // Caught by this module's own test, which expected a filename.
176
+ const status = git(root, ["status", "--porcelain", "-z", "-uall", "--", ...GRADING_PATHS]);
177
+ if (!status.ok) {
178
+ // Refused rather than reported clean. An unreadable status and a clean
179
+ // one both produce an empty list, and only one of them is a reading.
180
+ return {
181
+ reading: "UNMEASURED",
182
+ reason:
183
+ `the harness checkout at ${JSON.stringify(root)} is at ${head.out}, but its status could not be ` +
184
+ `read (${status.err || "git exited non-zero"}), so whether the grading code on disk matches ` +
185
+ "that commit is unknown — and unknown is not clean",
186
+ };
187
+ }
188
+ const dirty = porcelainPaths(status.raw);
189
+
190
+ const branchRead = git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
191
+ const branch = branchRead.ok && branchRead.out !== "HEAD" ? branchRead.out : null;
192
+
193
+ // No fetch. This compares against the upstream ref as it already stands
194
+ // on disk, which is a reading of "behind what I last saw", not "behind
195
+ // the server". Saying which is the difference between a number and a
196
+ // claim, so `behindReason` carries it when the number is unavailable.
197
+ const upstream = git(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
198
+ let behind: number | null = null;
199
+ let behindReason: string | null = null;
200
+ if (!upstream.ok || upstream.out === "") {
201
+ behindReason = `HEAD has no configured upstream (${upstream.err || "git named none"})`;
202
+ } else {
203
+ const count = git(root, ["rev-list", "--count", `HEAD..${upstream.out}`]);
204
+ const n = Number(count.out);
205
+ if (!count.ok || !Number.isInteger(n) || n < 0) {
206
+ behindReason =
207
+ `the distance from HEAD to ${upstream.out} could not be counted ` +
208
+ `(${count.err || `git printed ${JSON.stringify(count.out)}`})`;
209
+ } else {
210
+ behind = n;
211
+ }
212
+ }
213
+
214
+ return { reading: "MEASURED", sha: head.out, branch, dirty, behind, behindReason };
215
+ }
216
+
217
+ /**
218
+ * The sentence a run summary should carry, or `null` when there is nothing
219
+ * to say.
220
+ *
221
+ * Derived from `harnessProvenance` and never from a second probe. Three
222
+ * things make it non-null, and they are reported together rather than as
223
+ * the first one found: a run can be both dirty and behind, and a message
224
+ * naming one of them sends an operator to fix half the problem.
225
+ *
226
+ * It is a WARNING and not a refusal. #602 asks for *"refuse — or at
227
+ * minimum emit a loud UNMEASURED"*, and this takes the second: the
228
+ * decision to stop a run on a dirty harness is an operator's, and a
229
+ * refusal that fires on the ordinary state of a development checkout is
230
+ * one that gets switched off. What must not happen is silence.
231
+ */
232
+ export function harnessProvenanceWarning(p: HarnessProvenance): string | null {
233
+ if (p.reading === "UNMEASURED") {
234
+ return `HARNESS_UNMEASURED: ${p.reason}. A run whose grader cannot be identified has not been graded in any reproducible sense (#602)`;
235
+ }
236
+ const parts: string[] = [];
237
+ if (p.dirty.length > 0) {
238
+ parts.push(
239
+ `it has ${p.dirty.length} uncommitted change(s) under ${GRADING_PATHS.join("/, ")}/ ` +
240
+ `(${p.dirty.slice(0, 8).join(", ")}${p.dirty.length > 8 ? ", …" : ""}), so the code that graded ` +
241
+ `this run is not the code at ${p.sha}`,
242
+ );
243
+ }
244
+ if (p.behind !== null && p.behind > 0) {
245
+ parts.push(
246
+ `it is ${p.behind} commit(s) behind its upstream, so every refusal added since is absent from this ` +
247
+ "grade — a stale harness is strictly more permissive than a current one",
248
+ );
249
+ }
250
+ if (p.behind === null) {
251
+ parts.push(`whether it is behind its upstream is unknown: ${p.behindReason}`);
252
+ }
253
+ if (parts.length === 0) return null;
254
+ return `HARNESS_DIVERGENCE (${p.sha}${p.branch ? ` on ${p.branch}` : " detached"}): ${parts.join("; ")} (#602)`;
255
+ }
@@ -0,0 +1,235 @@
1
+ /**
2
+ * Evidence that a hook fired, and what it decided (#910).
3
+ *
4
+ * ## Why this exists
5
+ *
6
+ * #910's registration claim was wrong and was corrected by parsing the
7
+ * settings. Its execution claim could not be corrected, because there was
8
+ * nothing to correct it against: neither `TestSuiteRelease.hook.ts` nor
9
+ * `ProjectStateSync.hook.ts` wrote anything anywhere, so no search could ask
10
+ * whether either had ever run.
11
+ *
12
+ * That is `.claude/rules/checks-must-be-able-to-fail.md`'s #646 shape with the
13
+ * store removed entirely. The rule there is *"before believing an empty search
14
+ * over a store you did not write, name a string that must be PRESENT if the
15
+ * store has anything in it at all"*. For these two hooks there was no such
16
+ * string, and so no reading of their execution was available to anyone —
17
+ * including whoever picks up the issue next.
18
+ *
19
+ * ## The distinction a record has to preserve
20
+ *
21
+ * A hook that fired and deliberately declined, and a hook that never fired,
22
+ * are the same observation when nothing is written. They have different fixes,
23
+ * so they must look different:
24
+ *
25
+ * | outcome | means |
26
+ * |---|---|
27
+ * | no record at all | the call was out of the hook's population, or the hook did not run |
28
+ * | `declined-*` | it ran, reached the decision, and chose not to act |
29
+ * | the acting outcome | it ran and did the thing |
30
+ *
31
+ * **Only in-population calls are recorded.** Both hooks are attached to tool
32
+ * events that fire on every Bash call and every Write and Edit in every
33
+ * session, so recording every invocation would produce a file nobody can read
34
+ * — and the question is about full-suite commands and `project-state.json`
35
+ * writes, not about every tool call. The hook headers say which population
36
+ * each one records.
37
+ *
38
+ * ## Never throw
39
+ *
40
+ * A `PostToolUse` hook that throws fails the tool call it is attached to. So
41
+ * `appendEvidence` returns `false` rather than raising — and returns it rather
42
+ * than swallowing it, because a write that did not happen is not a write that
43
+ * happened, and a caller that wants to know can ask.
44
+ */
45
+
46
+ import { createHash } from "crypto";
47
+ import { appendFileSync, chmodSync, mkdirSync } from "fs";
48
+ import { homedir } from "os";
49
+ import { dirname, join } from "path";
50
+
51
+ export const HOOK_EVIDENCE_FILE = "hook-firings.jsonl";
52
+
53
+ /**
54
+ * The evidence file holds no raw command and no raw error text.
55
+ *
56
+ * A Bash tool call routinely carries leading environment assignments —
57
+ * `SOME_TOKEN=... bun test` — and an exception message routinely quotes the
58
+ * path or argv that produced it. Writing either verbatim turns an append-only
59
+ * log into a credential store that nothing rotates, in a file whose whole
60
+ * purpose is to be read later by somebody who was not there.
61
+ *
62
+ * So a record carries a non-reversible DISCRIMINATOR plus a classification
63
+ * drawn from a fixed vocabulary. That keeps every question the evidence
64
+ * exists to answer — did it fire, what did it decide, was it the same command
65
+ * as last time — and answers none of the questions a secret would.
66
+ *
67
+ * Raised by the security review of PR #970, findings 1 and 2.
68
+ */
69
+ export function digest(value: string): string {
70
+ // 16 hex characters: enough to correlate two runs of the same command,
71
+ // far too little to invert, and short enough that nobody is tempted to
72
+ // paste it anywhere as though it were the original.
73
+ return createHash("sha256").update(value).digest("hex").slice(0, 16);
74
+ }
75
+
76
+ /**
77
+ * The runner words a command contains, drawn from a FIXED vocabulary.
78
+ *
79
+ * Allowlisted rather than extracted, which is the property that matters: the
80
+ * output is a subset of this list, so no input can push an unexpected
81
+ * substring of the command into the record. A classification cannot leak;
82
+ * a pass-through can.
83
+ */
84
+ const SUITE_VOCABULARY = [
85
+ "bun",
86
+ "npm",
87
+ "pnpm",
88
+ "yarn",
89
+ "npx",
90
+ "test",
91
+ "vitest",
92
+ "jest",
93
+ "--parallel",
94
+ "--no-isolate",
95
+ "--coverage",
96
+ ] as const;
97
+
98
+ export function suiteTokens(command: string): string[] {
99
+ const seen = new Set(command.split(/\s+/).map(t => t.replace(/^['"]+|['"]+$/g, "")));
100
+ return SUITE_VOCABULARY.filter(word => seen.has(word));
101
+ }
102
+
103
+ /**
104
+ * A command reduced to what the evidence actually needs.
105
+ *
106
+ * One binding, so every hook records the same shape and there is one place to
107
+ * mutate when asking whether redaction is load-bearing.
108
+ */
109
+ export function commandDigestFacts(command: string): {
110
+ commandDigest: string;
111
+ suiteTokens: string[];
112
+ } {
113
+ return { commandDigest: digest(command), suiteTokens: suiteTokens(command) };
114
+ }
115
+
116
+ /** An error reduced to a class name and a digest — never its message. */
117
+ export function errorFacts(e: unknown): { errorClass: string; errorDigest: string } {
118
+ const raw = e instanceof Error ? `${e.name}: ${e.message}` : String(e);
119
+ const name = e instanceof Error ? e.name : typeof e;
120
+ return {
121
+ // Constructor names are identifiers. Anything else is refused rather
122
+ // than passed through, because `e.name` is writable.
123
+ errorClass: /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : "UNCLASSIFIED",
124
+ errorDigest: digest(raw),
125
+ };
126
+ }
127
+
128
+ export interface HookFiring {
129
+ /** ISO-8601, so a record can be compared against a run. */
130
+ at: string;
131
+ hook: string;
132
+ /** What the hook decided. `declined-*` for a deliberate no-op. */
133
+ outcome: string;
134
+ detail?: Record<string, unknown>;
135
+ }
136
+
137
+ /**
138
+ * Where the evidence lives, from an environment and a home directory.
139
+ *
140
+ * Both are parameters rather than reads of `process.env` and `homedir()`, so
141
+ * a case can drive this without touching the machine's real work directory.
142
+ * `RUNGATE_WORK_DIR` is the same override every other hook in this tree
143
+ * honours (`hooks/StaleTTLCleanup.hook.ts`, `hooks/lib/paths.ts`).
144
+ */
145
+ export function hookEvidencePath(
146
+ env: Record<string, string | undefined> = process.env,
147
+ home: string = homedir(),
148
+ ): string {
149
+ return join(env.RUNGATE_WORK_DIR || join(home, ".rungate"), HOOK_EVIDENCE_FILE);
150
+ }
151
+
152
+ /**
153
+ * One record, rendered.
154
+ *
155
+ * Pure, and the single place the on-disk shape is decided, so a case can
156
+ * assert the shape without a filesystem and the writer cannot disagree with
157
+ * the reader about it.
158
+ */
159
+ export function firingLine(
160
+ hook: string,
161
+ outcome: string,
162
+ detail: Record<string, unknown>,
163
+ at: Date,
164
+ ): string {
165
+ const record: HookFiring = { at: at.toISOString(), hook, outcome };
166
+ if (Object.keys(detail).length > 0) record.detail = detail;
167
+ // JSONL: the trailing newline terminates THIS record. Without it a crash
168
+ // mid-append leaves two records concatenated into one unparseable line, and
169
+ // the reader below would refuse the whole file over it.
170
+ return `${JSON.stringify(record)}\n`;
171
+ }
172
+
173
+ /**
174
+ * Read records back.
175
+ *
176
+ * A line that does not parse is DROPPED rather than throwing, and this is the
177
+ * one place in this tree where that is the right call: the file is appended to
178
+ * concurrently by hooks in unrelated sessions, so a torn final line is an
179
+ * expected state of a log and not a corrupt config. The distinction
180
+ * `.claude/rules/config-access.md` protects is about a document whose absence
181
+ * and whose corruption mean different things; here both mean "no record", and
182
+ * a reader that threw would make the evidence unreadable exactly when it is
183
+ * most wanted.
184
+ */
185
+ export function parseFirings(text: string): HookFiring[] {
186
+ const out: HookFiring[] = [];
187
+ for (const line of text.split("\n")) {
188
+ if (!line.trim()) continue;
189
+ try {
190
+ out.push(JSON.parse(line) as HookFiring);
191
+ } catch {
192
+ continue;
193
+ }
194
+ }
195
+ return out;
196
+ }
197
+
198
+ /**
199
+ * Append one rendered line, creating the directory.
200
+ *
201
+ * Returns `false` on any failure and NEVER throws — see the module docblock.
202
+ */
203
+ export function appendEvidence(path: string, line: string): boolean {
204
+ try {
205
+ // 0o700 / 0o600. The file records which suites ran, when, and from which
206
+ // worktree, for every session on the machine — a shape worth keeping to
207
+ // the owning user even with the redaction above. `mode` applies only on
208
+ // creation, so an existing file is corrected explicitly; a chmod failure
209
+ // must not lose the record, which is why it is caught separately.
210
+ mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
211
+ appendFileSync(path, line, { mode: 0o600 });
212
+ try {
213
+ chmodSync(path, 0o600);
214
+ } catch {
215
+ /* the record is written; its mode is a hardening, not the evidence */
216
+ }
217
+ return true;
218
+ } catch {
219
+ return false;
220
+ }
221
+ }
222
+
223
+ /**
224
+ * The one call a hook makes.
225
+ *
226
+ * One binding, so there is one thing to mutate and one site to grep for when
227
+ * asking which hooks are observable at all.
228
+ */
229
+ export function recordHookFiring(
230
+ hook: string,
231
+ outcome: string,
232
+ detail: Record<string, unknown> = {},
233
+ ): boolean {
234
+ return appendEvidence(hookEvidencePath(), firingLine(hook, outcome, detail, new Date()));
235
+ }