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.
Files changed (113) 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 +81 -16
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-protection.ts +790 -0
  7. package/lib/brief-ac-alignment.ts +104 -0
  8. package/lib/brief-references.ts +205 -0
  9. package/lib/bun-version.ts +93 -14
  10. package/lib/check-remedy.ts +140 -0
  11. package/lib/ci-checkout.ts +17 -0
  12. package/lib/ci-history-depth.ts +159 -0
  13. package/lib/ci-setup-step.ts +96 -0
  14. package/lib/claude-code-action.ts +85 -0
  15. package/lib/claude-tool-vocabulary.ts +188 -0
  16. package/lib/cli-commands.ts +15 -0
  17. package/lib/commit-sha.ts +42 -0
  18. package/lib/commit-subject.ts +90 -0
  19. package/lib/compliance-report.ts +377 -45
  20. package/lib/compliance.ts +191 -17
  21. package/lib/config-loader.ts +39 -1
  22. package/lib/config-trackable.ts +391 -0
  23. package/lib/conformity.ts +1087 -100
  24. package/lib/containment.ts +238 -0
  25. package/lib/content-hash.ts +24 -0
  26. package/lib/create-sc.ts +249 -16
  27. package/lib/dev-liveness.ts +180 -0
  28. package/lib/discovery-branch-points.ts +432 -0
  29. package/lib/discovery-stability.ts +481 -0
  30. package/lib/distribution-currency.ts +186 -0
  31. package/lib/doc-routing.ts +157 -0
  32. package/lib/evidence-prevalidator.ts +224 -2
  33. package/lib/evidence-satisfiability.ts +534 -12
  34. package/lib/failure-intake.ts +317 -0
  35. package/lib/fallow-availability.ts +157 -0
  36. package/lib/fs-write-capabilities.ts +232 -0
  37. package/lib/gate-run-split.ts +147 -0
  38. package/lib/generators/agents-md.ts +140 -32
  39. package/lib/git-isolation.ts +140 -0
  40. package/lib/github.ts +15 -0
  41. package/lib/google-auth-action.ts +93 -0
  42. package/lib/harness-project.ts +48 -0
  43. package/lib/harness-provenance.ts +255 -0
  44. package/lib/hook-evidence.ts +235 -0
  45. package/lib/hook-scopes.ts +386 -0
  46. package/lib/hook-target-tree.ts +398 -0
  47. package/lib/hook-trees.ts +447 -0
  48. package/lib/js-top-level-code.ts +78 -10
  49. package/lib/junit-checks.ts +52 -0
  50. package/lib/launch-base.ts +253 -0
  51. package/lib/line-citation.ts +372 -0
  52. package/lib/orphan-reaper.ts +468 -0
  53. package/lib/parity-binding.ts +205 -0
  54. package/lib/per-test-timeouts.ts +219 -0
  55. package/lib/plan-coverage.ts +151 -0
  56. package/lib/prior-branch.ts +201 -8
  57. package/lib/process-table.ts +146 -0
  58. package/lib/project-state-derivation.ts +219 -0
  59. package/lib/project-state-root.ts +258 -0
  60. package/lib/published-artifact.ts +525 -0
  61. package/lib/readdir-sorted.ts +45 -0
  62. package/lib/review-execution-reading.ts +206 -0
  63. package/lib/review-tool-agreement.ts +433 -0
  64. package/lib/rule-promotion.ts +234 -0
  65. package/lib/rule-retirement.ts +525 -0
  66. package/lib/run-branch.ts +612 -0
  67. package/lib/rungate-schema.ts +19 -0
  68. package/lib/runner-home.ts +274 -0
  69. package/lib/sc-id-cross-tree.ts +19 -7
  70. package/lib/sc-ids.ts +121 -13
  71. package/lib/sc-reservations.ts +289 -0
  72. package/lib/scaffold/ai-review-findings.ts +403 -0
  73. package/lib/scaffold/ai-review-step.ts +4661 -64
  74. package/lib/scaffold/managed-workflow.ts +587 -192
  75. package/lib/scaffold/owned-files.ts +152 -45
  76. package/lib/scaffold/pre-push-hook.ts +49 -5
  77. package/lib/scaffold/steps.ts +1413 -244
  78. package/lib/scaffold/workflow-census.ts +217 -0
  79. package/lib/scaffold/workflow-drift.ts +217 -0
  80. package/lib/scaffold/write-steps.ts +4 -0
  81. package/lib/scan-budget.ts +247 -0
  82. package/lib/scanner.ts +43 -51
  83. package/lib/scratch-roots.ts +50 -5
  84. package/lib/screenshot-discovery.ts +121 -0
  85. package/lib/screenshot-upload.ts +41 -1
  86. package/lib/secret-patterns.ts +511 -8
  87. package/lib/ship-mode.ts +219 -0
  88. package/lib/source-slice.ts +294 -0
  89. package/lib/stale-cleanup.ts +37 -3
  90. package/lib/suite-flake.ts +278 -0
  91. package/lib/suite-measurement.ts +23 -4
  92. package/lib/suite-run-reading.ts +241 -1
  93. package/lib/suite-timeout-margin.ts +193 -0
  94. package/lib/test-case-bodies.ts +883 -0
  95. package/lib/test-case-deletion.ts +653 -0
  96. package/lib/test-census.ts +97 -29
  97. package/lib/test-command-positions.ts +274 -0
  98. package/lib/test-suite-lock.ts +159 -16
  99. package/lib/tool-probe.ts +31 -9
  100. package/lib/top-level-cd.ts +393 -0
  101. package/lib/tree-entries.ts +89 -0
  102. package/lib/ts-ast.ts +200 -0
  103. package/lib/walk-test-files.ts +97 -0
  104. package/lib/workflow-actions.ts +263 -0
  105. package/lib/worktree-collect.ts +177 -5
  106. package/lib/worktree-repo.ts +36 -1
  107. package/package.json +2 -1
  108. package/scripts/ai-review-findings.ts +45 -0
  109. package/scripts/create-sc.ts +21 -1
  110. package/scripts/extract-constraints.ts +107 -7
  111. package/scripts/generate-code-map.ts +23 -30
  112. package/scripts/scaffold-project.ts +8 -1
  113. 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
+ }