rungate 0.6.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 +81 -16
- package/lib/behavioral-cache.ts +150 -2
- 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 +93 -14
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +17 -0
- 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 +191 -17
- package/lib/config-loader.ts +39 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1087 -100
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/create-sc.ts +249 -16
- 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/evidence-prevalidator.ts +224 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/generators/agents-md.ts +140 -32
- 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 +52 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -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/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -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-id-cross-tree.ts +19 -7
- 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 +4661 -64
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +152 -45
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/steps.ts +1413 -244
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +4 -0
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +43 -51
- 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/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 +241 -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-suite-lock.ts +159 -16
- package/lib/tool-probe.ts +31 -9
- package/lib/top-level-cd.ts +393 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- 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/create-sc.ts +21 -1
- package/scripts/extract-constraints.ts +107 -7
- package/scripts/generate-code-map.ts +23 -30
- package/scripts/scaffold-project.ts +8 -1
- package/scripts/sync-sc-status.ts +77 -16
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The git-config isolation set, declared ONCE as data (#1001).
|
|
3
|
+
*
|
|
4
|
+
* ## Why this file exists rather than a second copy of a string
|
|
5
|
+
*
|
|
6
|
+
* `git` executes code out of its own configuration. `core.fsmonitor` is a
|
|
7
|
+
* command git runs, `core.hooksPath` points at hooks git fires, and
|
|
8
|
+
* `core.excludesFile` can make a file invisible to the reading that is
|
|
9
|
+
* supposed to see it. So **running `git` in a directory someone else chose
|
|
10
|
+
* means running whatever that directory's `.git/config` says**, and
|
|
11
|
+
* converting a shell string to an argv does nothing about it.
|
|
12
|
+
*
|
|
13
|
+
* That was measured once, under #960/#965, in a scratch repository with one
|
|
14
|
+
* planted untracked file (git 2.50.1):
|
|
15
|
+
*
|
|
16
|
+
* | poisoned key | written where | unisolated | isolated |
|
|
17
|
+
* |---|---|---|---|
|
|
18
|
+
* | `core.excludesFile` → a file listing the plant | `~/.gitconfig` | **plant INVISIBLE** | `?? planted.txt` |
|
|
19
|
+
* | `core.excludesFile` → a file listing the plant | the checkout's `.git/config` | **plant INVISIBLE** | `?? planted.txt` |
|
|
20
|
+
* | `core.fsmonitor` → a script touching a marker | `~/.gitconfig` | **marker written — git ran it** | not run |
|
|
21
|
+
* | `core.hooksPath` → a dir with `post-index-change` | `~/.gitconfig` | **hook fired** | not fired |
|
|
22
|
+
*
|
|
23
|
+
* **The lesson was learned once and propagated nowhere.** It lived as a
|
|
24
|
+
* single shell-prefix string inside `lib/scaffold/ai-review-step.ts`, so
|
|
25
|
+
* `hooks/CommitEnforcement.hook.ts` — which runs `git -C <a path out of an
|
|
26
|
+
* agent's reply text>` — could not reuse it even in principle: its call sites
|
|
27
|
+
* are `execFileSync('git', […])` and a shell prefix is not an argv.
|
|
28
|
+
*
|
|
29
|
+
* One declaration, two projections. `gitIsolatedShellPrefix()` reproduces the
|
|
30
|
+
* existing string exactly, so `AI_REVIEW_GIT_ISOLATED` is now derived rather
|
|
31
|
+
* than spelled; `gitIsolatedArgs`/`gitIsolatedEnv` serve the `execFileSync`
|
|
32
|
+
* callers. A second declaration of either is refused by
|
|
33
|
+
* `test/git-isolation.test.ts`.
|
|
34
|
+
*
|
|
35
|
+
* ## Why env vars AND `-c`, which is not belt-and-braces
|
|
36
|
+
*
|
|
37
|
+
* `GIT_CONFIG_GLOBAL`/`GIT_CONFIG_SYSTEM`/`GIT_CONFIG_NOSYSTEM` neutralise
|
|
38
|
+
* whole FILES, so they cover keys nobody thought to enumerate — but they do
|
|
39
|
+
* not touch the checkout's own `.git/config`, which is inside the tree being
|
|
40
|
+
* read. The `-c` flags are the only thing covering row two of the table, and
|
|
41
|
+
* command scope outranks local scope. **Neither covers the other.**
|
|
42
|
+
*
|
|
43
|
+
* ## `safe.directory='*'` is load-bearing, not a loosening
|
|
44
|
+
*
|
|
45
|
+
* `actions/checkout` writes `safe.directory` for the workspace into the
|
|
46
|
+
* GLOBAL config on every job. Neutralise the global file and that exception
|
|
47
|
+
* goes with it, so wherever the working tree is owned by a different uid than
|
|
48
|
+
* the process — containers, rootless self-hosted pools — `git` exits 128 with
|
|
49
|
+
* *"detected dubious ownership"*. `safe.directory` is honoured only from
|
|
50
|
+
* protected scopes (system, global, command), so `-c` restores it from the
|
|
51
|
+
* one source the subject cannot write, and the checkout's `.git/config` still
|
|
52
|
+
* cannot set it. Without it, isolation would be stricter than what it
|
|
53
|
+
* replaces in a way that fails closed on **green** repositories.
|
|
54
|
+
*
|
|
55
|
+
* ## WHAT THIS DOES NOT COVER
|
|
56
|
+
*
|
|
57
|
+
* - **Config a caller passes deliberately.** These are defaults a caller
|
|
58
|
+
* prepends; anything added after them wins.
|
|
59
|
+
* - **`git` subcommands that reach the network.** `fetch` with these env vars
|
|
60
|
+
* also discards a proxy, a CA bundle, or an `insteadOf` rewrite a
|
|
61
|
+
* self-hosted runner legitimately keeps in `~/.gitconfig`. That is a
|
|
62
|
+
* different trade-off and is why `buildRestoreScript` was left out of #960.
|
|
63
|
+
* - **The repository's CONTENT.** Isolating config is not reviewing a tree.
|
|
64
|
+
*
|
|
65
|
+
* Issue: #1001. Refs #960, #965.
|
|
66
|
+
*/
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Env vars neutralising whole config FILES.
|
|
70
|
+
*
|
|
71
|
+
* `GIT_CONFIG_NOSYSTEM=1` is not redundant with `GIT_CONFIG_SYSTEM=/dev/null`
|
|
72
|
+
* on every git version, so both are set.
|
|
73
|
+
*/
|
|
74
|
+
export const GIT_ISOLATION_ENV: Readonly<Record<string, string>> = Object.freeze({
|
|
75
|
+
GIT_CONFIG_GLOBAL: "/dev/null",
|
|
76
|
+
GIT_CONFIG_SYSTEM: "/dev/null",
|
|
77
|
+
GIT_CONFIG_NOSYSTEM: "1",
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Keys overridden at COMMAND scope, which outranks the checkout's own
|
|
82
|
+
* `.git/config` — the one scope the env vars above cannot reach.
|
|
83
|
+
*
|
|
84
|
+
* `core.fsmonitor` is set to the empty string rather than removed: an empty
|
|
85
|
+
* value is how git spells "no fsmonitor", and there is no `-c` form that
|
|
86
|
+
* unsets a key.
|
|
87
|
+
*/
|
|
88
|
+
export const GIT_ISOLATION_CONFIG: ReadonlyArray<readonly [string, string]> = Object.freeze([
|
|
89
|
+
["core.fsmonitor", ""],
|
|
90
|
+
["core.excludesFile", "/dev/null"],
|
|
91
|
+
["core.hooksPath", "/dev/null"],
|
|
92
|
+
["safe.directory", "*"],
|
|
93
|
+
] as const);
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* The shell-prefix projection: `VAR=… VAR=… git -c k=v …`, ready to be
|
|
97
|
+
* interpolated in front of a subcommand in a generated script.
|
|
98
|
+
*
|
|
99
|
+
* `safe.directory`'s value is single-quoted because `*` would otherwise be
|
|
100
|
+
* glob-expanded by the shell. That quoting is a property of THIS projection
|
|
101
|
+
* and must not leak into the argv one, where the value is passed literally —
|
|
102
|
+
* a `'*'` reaching git through `execFileSync` would be three characters that
|
|
103
|
+
* match no directory, i.e. isolation that silently does not apply.
|
|
104
|
+
*/
|
|
105
|
+
export function gitIsolatedShellPrefix(): string {
|
|
106
|
+
const env = Object.entries(GIT_ISOLATION_ENV).map(([k, v]) => `${k}=${v}`).join(" ");
|
|
107
|
+
const flags = GIT_ISOLATION_CONFIG.map(([k, v]) => `-c ${k}=${shellQuoteIfGlob(v)}`).join(" ");
|
|
108
|
+
return `${env} git ${flags}`;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** Single-quote a value a shell would otherwise expand. */
|
|
112
|
+
function shellQuoteIfGlob(v: string): string {
|
|
113
|
+
return /[*?[\]]/.test(v) ? `'${v}'` : v;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* The argv projection: the `-c` flags, followed by whatever the caller
|
|
118
|
+
* passes.
|
|
119
|
+
*
|
|
120
|
+
* Pre-command options only, so a caller's own `-C <dir>` may follow in any
|
|
121
|
+
* order. Pair with `gitIsolatedEnv`; the flags alone leave `~/.gitconfig`
|
|
122
|
+
* live, and the env alone leaves the checkout's `.git/config` live.
|
|
123
|
+
*/
|
|
124
|
+
export function gitIsolatedArgs(args: readonly string[] = []): string[] {
|
|
125
|
+
const flags: string[] = [];
|
|
126
|
+
for (const [k, v] of GIT_ISOLATION_CONFIG) flags.push("-c", `${k}=${v}`);
|
|
127
|
+
return [...flags, ...args];
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* `base` with the isolation vars applied on top.
|
|
132
|
+
*
|
|
133
|
+
* Takes the base environment as a parameter rather than reading
|
|
134
|
+
* `process.env`, so a case can drive it without touching the machine's.
|
|
135
|
+
*/
|
|
136
|
+
export function gitIsolatedEnv(
|
|
137
|
+
base: NodeJS.ProcessEnv = process.env,
|
|
138
|
+
): NodeJS.ProcessEnv {
|
|
139
|
+
return { ...base, ...GIT_ISOLATION_ENV };
|
|
140
|
+
}
|
package/lib/github.ts
CHANGED
|
@@ -37,6 +37,21 @@ export interface GitHubClient {
|
|
|
37
37
|
update: (params: { owner: string; repo: string; pull_number: number; [key: string]: any }) => Promise<{ data: any }>;
|
|
38
38
|
list: (params: { owner: string; repo: string; [key: string]: any }) => Promise<{ data: any[] }>;
|
|
39
39
|
};
|
|
40
|
+
repos: {
|
|
41
|
+
/** Repository metadata. `owner.type` and `default_branch` are what PROTECT-1 reads (#909). */
|
|
42
|
+
get: (params: { owner: string; repo: string }) => Promise<{ data: any }>;
|
|
43
|
+
/**
|
|
44
|
+
* One branch. Carries `protected`, and needs only read access (#909).
|
|
45
|
+
*
|
|
46
|
+
* Asked BEFORE `getBranchProtection`, which needs admin: a 404 from the
|
|
47
|
+
* protection endpoint means "unprotected" or "you are not an admin"
|
|
48
|
+
* with no way to tell which, and conflating those would let a token
|
|
49
|
+
* without admin report every repo clean.
|
|
50
|
+
*/
|
|
51
|
+
getBranch: (params: { owner: string; repo: string; branch: string }) => Promise<{ data: any }>;
|
|
52
|
+
/** Branch protection. Requires admin on the repo; 403 for everyone else. */
|
|
53
|
+
getBranchProtection: (params: { owner: string; repo: string; branch: string }) => Promise<{ data: any }>;
|
|
54
|
+
};
|
|
40
55
|
checks: {
|
|
41
56
|
/**
|
|
42
57
|
* Check runs for one ref (#46).
|
|
@@ -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
|
+
}
|