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.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- 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
|
+
}
|