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,159 @@
1
+ /**
2
+ * How much history a generated CI job keeps, and whether that is enough for
3
+ * the failure intake to report MEASURED (#987).
4
+ *
5
+ * ## The reading this exists to fix
6
+ *
7
+ * `lib/failure-intake.ts` mines `fix:` and `Revert` subjects out of `git log`.
8
+ * Its refusal is `SHALLOW_HISTORY`, taken from
9
+ * `git rev-parse --is-shallow-repository`, and `actions/checkout@v4` with no
10
+ * `fetch-depth` clones to depth 1. So the intake has reported UNMEASURED on
11
+ * every run of every generated workflow since it shipped — uniformly absent
12
+ * rather than occasionally missing, which is why nobody noticed.
13
+ *
14
+ * ## Why this is a module and not a `fetch-depth: 0` on one line
15
+ *
16
+ * Two things were measured on 2026-10-21 against real repositories, and each
17
+ * one falsifies a step of the obvious fix. Both are asserted as cases in
18
+ * `test/ci-history-depth.test.ts` rather than described here.
19
+ *
20
+ * **A bounded depth does not make the intake MEASURED on a repository longer
21
+ * than the depth.** `--is-shallow-repository` is a fact about `.git/shallow`,
22
+ * not about how many commits you fetched: a clone deepened to
23
+ * `MAX_COMMITS_SCANNED` and a clone at depth 1 both answer `true` as long as
24
+ * there is any history past the boundary. #987 proposes `fetch-depth: 500` as
25
+ * the bounded option that "matches what the code actually asks for"; measured
26
+ * on a 520-commit repository, a depth-500 clone holds all 500 commits the
27
+ * intake would read and still reports UNMEASURED. This repository's `main`
28
+ * carries 1090 commits and only grows, so that is its permanent state.
29
+ *
30
+ * The exception, stated because it is the direction this module is
31
+ * deliberately wrong in: when the depth exceeds the whole history, git has
32
+ * nothing left to truncate and removes `.git/shallow`, so the intake reports
33
+ * MEASURED. `ciHistoryReading` below refuses a bounded depth anyway — see its
34
+ * docblock.
35
+ *
36
+ * And it is not even cheaper. Three clones of this repository, each repeated
37
+ * three times: depth 1 took 1.23–1.64s for 6MB, depth 500 took 1.54–2.75s for
38
+ * 9MB, and full history took 1.43–1.64s for 13MB. A bounded deepen makes the
39
+ * server compute a cut of the graph; a full clone is served from a pack it
40
+ * already has. The cheap option is the one that does not work, and the
41
+ * bounded middle is the slowest of the three.
42
+ *
43
+ * **A bounded `git fetch` AFTER the checkout re-shallows a complete clone.**
44
+ * This is the one that makes `fetch-depth: 0` alone inert. The generated job
45
+ * already runs `git fetch --no-tags --depth=200 origin '+refs/heads/main:…'`
46
+ * one step after the checkout, for the conformity ratchet's comparison base.
47
+ * Measured on a complete 40-commit clone: `is-shallow-repository` goes
48
+ * `false` → `true` and `rev-list --count HEAD` drops 40 → 20. Setting
49
+ * `fetch-depth: 0` and leaving that step alone buys nothing at all.
50
+ *
51
+ * So the depth of the base-ref fetch is DERIVED from the checkout's depth
52
+ * here, rather than declared beside it. Two numbers that have to agree, with
53
+ * nothing comparing them, is the defect class this repository pays for most
54
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
55
+ *
56
+ * ## WHAT THIS DOES NOT COVER
57
+ *
58
+ * - **It does not make the intake's reading good, only present.** Whether the
59
+ * mined set is worth anything is #988, and nothing here touches the
60
+ * classifier.
61
+ * - **It says nothing about a job it cannot see.** The reading is taken from a
62
+ * parsed `CheckoutModel`; a job that acquires history some other way — a
63
+ * cache restore, a submodule, a hand-rolled `git clone` inside `run:` — is
64
+ * invisible to it and will read UNMEASURED while being fine. The direction
65
+ * is deliberate: a false UNMEASURED costs a conversation, a false MEASURED
66
+ * costs the whole point of #987.
67
+ * - **It does not check that the history is ENOUGH**, only that it is
68
+ * untruncated. A repository younger than `MAX_COMMITS_SCANNED` commits
69
+ * reports MEASURED over fewer commits than the intake asked for, which is
70
+ * correct — there is no more history to have — but it is not the same claim.
71
+ * - **It disagrees with the intake on one input, on purpose.** A bounded depth
72
+ * GREATER than the repository's whole history leaves nothing to truncate, so
73
+ * the real `mineFixCommits` reports MEASURED there while this reports
74
+ * UNMEASURED. The disagreement is asserted as a case rather than described.
75
+ * A generator cannot know how long a consumer's history is, still less how
76
+ * long it will be next year, so the only honest reading of a bounded depth
77
+ * at generation time is "this will truncate" — and the cost of being wrong
78
+ * is a young repository being told to keep history it already keeps.
79
+ */
80
+ import type { CheckoutModel } from "./ci-checkout";
81
+
82
+ /**
83
+ * The `fetch-depth:` the generated suite and gates jobs declare. `0` is
84
+ * `actions/checkout`'s spelling for full history, and per the module docblock
85
+ * it is the only value under which the intake can report MEASURED.
86
+ *
87
+ * One declaring position. The generator reads it, the base-ref fetch derives
88
+ * from it, and the tests compare the emitted YAML against it.
89
+ */
90
+ export const CI_SUITE_FETCH_DEPTH = 0;
91
+
92
+ /**
93
+ * How deep the post-checkout base-ref fetch may go, given the checkout's own
94
+ * depth.
95
+ *
96
+ * A function rather than a second constant, because the whole finding is that
97
+ * these two cannot be chosen independently: a bounded fetch re-shallows a
98
+ * complete checkout and silently undoes the `fetch-depth` above it. Passing
99
+ * the suite depth in makes that dependency something a mutation can reach.
100
+ *
101
+ * `null` means "no `--depth` flag at all". It is not a wasteful choice when
102
+ * the checkout is already full: the objects are local, so the fetch moves a
103
+ * ref and nothing else.
104
+ */
105
+ export function baseRefFetchDepth(suiteDepth: number): number | null {
106
+ return suiteDepth === 0 ? null : 200;
107
+ }
108
+
109
+ /** Why a job's history is not a history. Exported so callers compare against the producer's spelling. */
110
+ export const SHALLOW_CHECKOUT = "SHALLOW_CHECKOUT";
111
+ export const RESHALLOWED_BY_FETCH = "RESHALLOWED_BY_FETCH";
112
+
113
+ export interface HistoryReading {
114
+ /** The single discriminator; `reasons` is the other projection of one computation. */
115
+ reading: "MEASURED" | "UNMEASURED";
116
+ reasons: string[];
117
+ }
118
+
119
+ /**
120
+ * THE decider: can the failure intake report MEASURED in a job with this
121
+ * checkout?
122
+ *
123
+ * One binding, so there is one thing to mutate. It reads the `CheckoutModel`
124
+ * `lib/ci-checkout.ts` already parses out of a workflow, rather than
125
+ * re-parsing the YAML — a second reader of the same file would survive any
126
+ * mutation of the first and both would read as covered.
127
+ *
128
+ * This PREDICTS what `mineFixCommits` will say. It is not a second copy of
129
+ * that decision: the prediction is compared against the real intake run over
130
+ * real clones built to this exact model, so the two are held to each other
131
+ * instead of merely agreeing.
132
+ *
133
+ * It is a CONSERVATIVE prediction, and the one input on which it is knowingly
134
+ * wrong is named in WHAT THIS DOES NOT COVER above: a bounded depth longer
135
+ * than the repository's entire history is MEASURED in fact and UNMEASURED
136
+ * here. Refusing every bounded depth is the only reading available at
137
+ * generation time, when the history's length is unknown and unbounded.
138
+ */
139
+ export function ciHistoryReading(model: CheckoutModel): HistoryReading {
140
+ const reasons: string[] = [];
141
+
142
+ // `depth: null` is `fetch-depth: 0`. Any number — including one larger than
143
+ // MAX_COMMITS_SCANNED — leaves `.git/shallow` on disk, and the intake reads
144
+ // that file and not the commit count.
145
+ if (model.depth !== null) {
146
+ reasons.push(`${SHALLOW_CHECKOUT}: fetch-depth ${model.depth}`);
147
+ }
148
+
149
+ // Order matters to a reader and not to the verdict: a bounded fetch
150
+ // re-shallows whatever the checkout left, so it is a reason on its own even
151
+ // when the checkout above it was full.
152
+ for (const f of model.fetches) {
153
+ if (f.depth !== null) {
154
+ reasons.push(`${RESHALLOWED_BY_FETCH}: git fetch --depth=${f.depth} ${f.refspec}`);
155
+ }
156
+ }
157
+
158
+ return { reading: reasons.length > 0 ? "UNMEASURED" : "MEASURED", reasons };
159
+ }
@@ -0,0 +1,96 @@
1
+ /**
2
+ * The one extension point a consumer has INSIDE a rungate-managed CI job
3
+ * (#529).
4
+ *
5
+ * `resolveManagedWrite` preserves whole JOBS a consumer adds and refuses
6
+ * rather than dropping one, so the ownership boundary has always been
7
+ * job-level. That boundary cannot express "run this before the suite": jobs
8
+ * do not share a filesystem, so a consumer-owned job cannot seed the tree the
9
+ * test job tests. The only thing left is to edit the managed job, which works
10
+ * until the next re-scaffold.
11
+ *
12
+ * The repository that filed #529 carries the scar in its own `ci.yml` — a
13
+ * comment above an edited `- run:` line explaining that a re-scaffold will
14
+ * revert it. **A consumer documenting that their own edit will be reverted is
15
+ * the feature request.**
16
+ *
17
+ * ## What this is, in one sentence
18
+ *
19
+ * The generated job always runs `scripts/ci-setup.sh` when the tree has one.
20
+ * Rungate owns 100% of the YAML; the consumer owns a file rungate never reads,
21
+ * never writes and never mentions in an ownership table.
22
+ *
23
+ * ## Why the step is emitted unconditionally, not "when the file exists"
24
+ *
25
+ * The obvious shape is a generation-time `existsSync` — emit the step for
26
+ * trees that have the script, omit it for trees that do not. It produces a
27
+ * tidier file and it is the wrong decision, because **generation happens once
28
+ * and the tree keeps moving.** A consumer who adds `scripts/ci-setup.sh` the
29
+ * week after scaffolding gets a file with no extension point in it, their
30
+ * script never runs, and nothing anywhere says so: a green CI run over a tree
31
+ * that was never set up (`.claude/rules/config-access.md`, *Silent Default
32
+ * Substitution*). The existence question belongs at the moment the answer is
33
+ * used, which is run time.
34
+ *
35
+ * ## Why both arms print
36
+ *
37
+ * `0`, `{}`, `SKIP` and silence are indistinguishable from success. A step
38
+ * that quietly does nothing when the file is absent cannot be told from one
39
+ * that ran a script which happened to do nothing, and an operator debugging a
40
+ * tree that was not seeded has no line to search for. Both branches name the
41
+ * path and say which happened.
42
+ *
43
+ * ## Why `-f` and `bash`, not `-x`
44
+ *
45
+ * The executable bit is one byte of filesystem state that git preserves and
46
+ * most editors, `cp`, and every zip-based download do not. `[ -x ]` turns a
47
+ * missing mode bit into a silently skipped setup — #492's one-byte row, with
48
+ * the guard on the other side. `-f` plus an explicit interpreter has no mode
49
+ * bit in it. A consumer who needs another language execs it from the script.
50
+ *
51
+ * ## Why it is a NAMED step with a block scalar, and not `- run:`
52
+ *
53
+ * `testCommandsNamedByCiWorkflow` reads the suite job's **first** `- run:`
54
+ * line that is not known setup, and calls it the project's test command. A
55
+ * setup step written `- run: bash scripts/ci-setup.sh` would be read as the
56
+ * test command by every position check in the tree, and #621's agreement
57
+ * binding would report the project's test command three different ways. A
58
+ * `- name:` step with a `run: |` body is invisible to that regex, which is
59
+ * why every other multi-line step in the generated files is already written
60
+ * that way. `test/ci-setup-step.test.ts` holds that, rather than this comment.
61
+ *
62
+ * ## Failure is terminal, deliberately
63
+ *
64
+ * No `|| true`. A setup script that fails has left the tree in a state the
65
+ * suite was not written against, and a green suite over it is the least
66
+ * useful thing CI can produce.
67
+ */
68
+
69
+ /**
70
+ * The conventional path. One declaration: the generator, the prose and every
71
+ * test read this, so a rename cannot half-apply.
72
+ */
73
+ export const CI_SETUP_SCRIPT = "scripts/ci-setup.sh";
74
+
75
+ /**
76
+ * The step, indented for the `steps:` list of a generated job.
77
+ *
78
+ * Returns the leading newline too, so a call site concatenates it the way the
79
+ * typecheck and global-tools steps beside it are concatenated.
80
+ */
81
+ export function ciSetupStep(): string {
82
+ return `
83
+ - name: Consumer setup (${CI_SETUP_SCRIPT}, optional)
84
+ run: |
85
+ # rungate's one extension point inside this managed job (#529).
86
+ # The script is yours; this file is not. Re-scaffolding rewrites the
87
+ # YAML around this step and never touches ${CI_SETUP_SCRIPT}.
88
+ # Both branches print: a step that is silent when the file is absent
89
+ # cannot be told from one that ran and did nothing.
90
+ if [ -f ${CI_SETUP_SCRIPT} ]; then
91
+ echo "rungate: running ${CI_SETUP_SCRIPT} before the suite (#529)"
92
+ bash ${CI_SETUP_SCRIPT}
93
+ else
94
+ echo "rungate: no ${CI_SETUP_SCRIPT} in this tree, so no consumer setup ran (#529)"
95
+ fi`;
96
+ }
@@ -0,0 +1,85 @@
1
+ /**
2
+ * The one pin for `anthropics/claude-code-action` (#689).
3
+ *
4
+ * Two workflows pinned this action to two different commits and annotated
5
+ * both `# v1`:
6
+ *
7
+ * | File | Pin | Comment | What it actually was |
8
+ * |---|---|---|---|
9
+ * | `.github/workflows/ai-review.yml` (#631, unmerged) | `5eb090f3` | `# v1` | v1 |
10
+ * | `.github/workflows/claude-review.yml` | `f27be6b6` | `# v1` | v1 as of 2026-10-16 |
11
+ *
12
+ * The comment is the only thing a reader checks. It agreed with itself in both
13
+ * files while naming neither commit, which is `.claude/rules/
14
+ * checks-must-be-able-to-fail.md`'s "two deciders that agree" with a comment
15
+ * standing in for the second decider.
16
+ *
17
+ * ## Why this is a module and not a string in two YAML files
18
+ *
19
+ * It was two strings, and they diverged. This is `lib/bun-version.ts`'s answer
20
+ * (#622) applied to the step beside it: one binding, so a mutation of it can
21
+ * show that the agreement is load-bearing rather than coincidental.
22
+ *
23
+ * A workflow file cannot import, so the agreement is not achieved by
24
+ * substitution — it is CHECKED, by `actionPinParity` in
25
+ * `scripts/contract-parity.ts`, which reads every `.github/workflows/*.yml`
26
+ * and every literal in `lib/` and `scripts/` and compares each to this
27
+ * declaration. That check refuses when it finds no pin at all: zero strings
28
+ * are trivially all equal, and on this tree there is exactly one consumer, so
29
+ * "finding nothing in every file is perfect agreement" is one renamed step
30
+ * away rather than hypothetical.
31
+ *
32
+ * ## How the SHA was established, and the trap in establishing it
33
+ *
34
+ * ```
35
+ * $ gh api repos/anthropics/claude-code-action/git/ref/tags/v1
36
+ * → object.type "tag", object.sha 310805dc335398c705877f09079340090470ff77
37
+ * $ gh api repos/anthropics/claude-code-action/git/tags/310805dc…
38
+ * → object.type "commit", object.sha 5eb090f3c3afd701a0672cd32981197ca27688f6
39
+ * $ gh api repos/anthropics/claude-code-action/commits/v1
40
+ * → sha 5eb090f3c3afd701a0672cd32981197ca27688f6
41
+ * ```
42
+ *
43
+ * `v1` is an ANNOTATED tag, so `refs/tags/v1` points at a tag OBJECT and the
44
+ * commit is one dereference further down. Reading `.object.sha` off the ref
45
+ * and stopping there gives `310805dc`, which is not a commit and cannot be a
46
+ * `uses:` pin at all — #689's own resolution step made exactly that error and
47
+ * concluded from it that neither pinned SHA was v1. One of them was.
48
+ *
49
+ * ## What this does NOT do
50
+ *
51
+ * It does not keep itself fresh. `v1` is a MOVING tag upstream: every release
52
+ * repoints it, so `RESOLVED_ON` dates the reading rather than certifying it.
53
+ * Nothing here fails when the pin goes stale — a check for that needs the
54
+ * network, and whether a staleness refusal belongs in the suite is the
55
+ * decision #377 is open for. Bumping is a deliberate edit to this file, and
56
+ * `actionPinParity` makes every consumer follow it in the same commit.
57
+ */
58
+
59
+ /** The action, by the name a `uses:` line spells. */
60
+ export const CLAUDE_CODE_ACTION = "anthropics/claude-code-action";
61
+
62
+ /**
63
+ * The commit `refs/tags/v1` dereferences to, resolved on `RESOLVED_ON`.
64
+ * A full 40-character commit SHA, because that is the only form of a `uses:`
65
+ * reference the publisher cannot repoint.
66
+ */
67
+ export const CLAUDE_CODE_ACTION_SHA = "5eb090f3c3afd701a0672cd32981197ca27688f6";
68
+
69
+ /**
70
+ * The tag that SHA was v1 of, carried here so the trailing `# vN` comment in
71
+ * every workflow is DERIVED from the same declaration as the pin. A comment
72
+ * that can disagree with the pin it annotates is worse than no comment.
73
+ */
74
+ export const CLAUDE_CODE_ACTION_VERSION = "v1";
75
+
76
+ /** The day the tag was dereferenced. A moving tag's reading needs a date. */
77
+ export const CLAUDE_CODE_ACTION_RESOLVED_ON = "2026-10-19";
78
+
79
+ /**
80
+ * The exact text a workflow's `uses:` value must carry — pin and comment in
81
+ * one rendering, so there is one thing to mutate and no way to update half.
82
+ */
83
+ export function claudeCodeActionRef(): string {
84
+ return `${CLAUDE_CODE_ACTION}@${CLAUDE_CODE_ACTION_SHA} # ${CLAUDE_CODE_ACTION_VERSION}`;
85
+ }
@@ -0,0 +1,188 @@
1
+ /**
2
+ * Which tool names Claude Code actually knows, so a deny list denies things
3
+ * that exist (#885).
4
+ *
5
+ * The CLI validates every `--allowedTools` / `--disallowedTools` entry at
6
+ * startup and prints a warning for a name it does not recognise:
7
+ *
8
+ * Permission deny rule "SlashCommand" matches no known tool — check for typos.
9
+ * Permission deny rule "MultiEdit" matches no known tool — check for typos.
10
+ *
11
+ * Then it carries on. So **a rule that matches no known tool is
12
+ * indistinguishable from a rule that is holding** — eleven entries in a deny
13
+ * list read as eleven denials, and two of them are inert. Nothing asserted
14
+ * otherwise, which also means a tool renamed upstream silently turns its
15
+ * denial off and the only trace is a line in a log nobody greps.
16
+ *
17
+ * ## The record, and how it was taken
18
+ *
19
+ * Measured 2026-10-21 against `claude 2.1.306`, with this command — no network
20
+ * call is made, because the CLI validates the rules and then refuses the empty
21
+ * prompt:
22
+ *
23
+ * printf '' | claude -p --disallowedTools "<comma-separated names>"
24
+ *
25
+ * The candidate list probed was deliberately WIDER than anything this repo
26
+ * emits. A record built only from the names we use would be the question
27
+ * restated — `.claude/rules/checks-must-be-able-to-fail.md`'s #530 shape,
28
+ * where the artifact agrees because you put the value in it. 35 names went in;
29
+ * the 29 below came back known and 6 came back unknown.
30
+ *
31
+ * ## What this record is NOT
32
+ *
33
+ * It is not a claim about the CLI running in CI, which is a different version
34
+ * (`v2.1.303` at the time of writing). It is a claim about the vocabulary on
35
+ * the day and version named above, and `probePermissionRules` below is how a
36
+ * machine with a CLI re-takes it. A tree with no `claude` on PATH gets
37
+ * `UNMEASURED` from that probe and the static comparison from
38
+ * `unknownAgainstRecord`, which is `.claude/rules/checks-must-be-able-to-fail.md`'s
39
+ * split: enforce the half the repo owns, and make the other half say it did
40
+ * not run.
41
+ */
42
+
43
+ import { probeExternalTool, toolProbe, type ToolProbe } from "./tool-probe";
44
+
45
+ export const CLAUDE_TOOL_VOCABULARY_VERSION = "2.1.306";
46
+ export const CLAUDE_TOOL_VOCABULARY_MEASURED_ON = "2026-10-21";
47
+ export const CLAUDE_TOOL_VOCABULARY_COMMAND =
48
+ `printf '' | claude -p --disallowedTools "<comma-separated names>"`;
49
+
50
+ /** Names the CLI resolved to a tool. Re-take with the command above. */
51
+ export const VERIFIED_KNOWN_TOOLS: ReadonlySet<string> = new Set([
52
+ "Agent",
53
+ "AskUserQuestion",
54
+ "Bash",
55
+ "BashOutput",
56
+ "Edit",
57
+ "EnterPlanMode",
58
+ "ExitPlanMode",
59
+ "Glob",
60
+ "Grep",
61
+ "KillShell",
62
+ "ListAgents",
63
+ "ListMcpResources",
64
+ "Monitor",
65
+ "NotebookEdit",
66
+ "Read",
67
+ "ReadMcpResource",
68
+ "ReportFindings",
69
+ "ScheduleWakeup",
70
+ "SendMessage",
71
+ "Skill",
72
+ "Task",
73
+ "TaskList",
74
+ "TaskStop",
75
+ "TodoWrite",
76
+ "ToolSearch",
77
+ "WebFetch",
78
+ "WebSearch",
79
+ "Workflow",
80
+ "Write",
81
+ ]);
82
+
83
+ /**
84
+ * Names the CLI resolved to NOTHING, kept as data rather than deleted.
85
+ *
86
+ * This is the negative control the check needs, built from real readings
87
+ * instead of a synthetic typo: "every name is known" passes over an empty
88
+ * list, and a control made of names nobody writes proves only that the
89
+ * comparison runs. These are names this project or its history actually used.
90
+ *
91
+ * `NotebookRead` and `LS` are retired tools, probed as controls alongside the
92
+ * two the issue is about.
93
+ */
94
+ export const VERIFIED_UNKNOWN_TOOLS: ReadonlySet<string> = new Set([
95
+ "LS",
96
+ "MultiEdit",
97
+ "NotebookRead",
98
+ "SlashCommand",
99
+ ]);
100
+
101
+ /**
102
+ * The tool a permission rule names, with any path spec removed.
103
+ *
104
+ * `Edit(./**)` is a rule about the `Edit` tool, and the CLI resolves the tool
105
+ * name before it looks at the pattern. A check that compared the whole rule
106
+ * text to the vocabulary would report every path-scoped rule as unknown — a
107
+ * detector narrower than what it detects, arriving as a flood of false
108
+ * positives rather than as silence.
109
+ */
110
+ export function ruleToolName(rule: string): string {
111
+ const open = rule.indexOf("(");
112
+ return (open === -1 ? rule : rule.slice(0, open)).trim();
113
+ }
114
+
115
+ /**
116
+ * The names in `rules` that the record does not vouch for, in order.
117
+ *
118
+ * One binding, so there is one thing to mutate. A name is vouched for only by
119
+ * `VERIFIED_KNOWN_TOOLS`: membership of `VERIFIED_UNKNOWN_TOOLS` is NOT an
120
+ * exemption, it is the record saying the opposite. The caller that keeps an
121
+ * inert rule on purpose declares it where it keeps it, and says why.
122
+ */
123
+ export function unknownAgainstRecord(rules: readonly string[]): string[] {
124
+ return rules.map(ruleToolName).filter(name => !VERIFIED_KNOWN_TOOLS.has(name));
125
+ }
126
+
127
+ /** Every name the CLI complained about, in the order it complained. */
128
+ export function parseUnknownRuleWarnings(output: string): string[] {
129
+ const out: string[] = [];
130
+ for (const m of output.matchAll(/rule "([^"]+)" matches no known tool/g)) out.push(m[1]!);
131
+ return out;
132
+ }
133
+
134
+ export interface PermissionRuleProbe {
135
+ /** `MEASURED` only when a CLI ran and validated the rules. */
136
+ reading: "MEASURED" | "UNMEASURED";
137
+ /** Names this CLI did not recognise. Empty and meaningless when UNMEASURED. */
138
+ unknown: string[];
139
+ probe: ToolProbe;
140
+ }
141
+
142
+ /**
143
+ * Ask the installed CLI which of `rules` it does not know.
144
+ *
145
+ * Takes no network: the CLI validates the rules, then refuses the empty prompt
146
+ * and exits. A tree with no `claude` on PATH reads `UNMEASURED` — not an empty
147
+ * `unknown` list, which is what a passing probe looks like.
148
+ */
149
+ export function probePermissionRules(
150
+ rules: readonly string[],
151
+ opts?: { timeoutMs?: number; command?: string },
152
+ ): PermissionRuleProbe {
153
+ const command = opts?.command ?? "claude";
154
+ const present = probeExternalTool(command, ["--version"], opts);
155
+ if (!present.available) return { reading: "UNMEASURED", unknown: [], probe: present };
156
+
157
+ const joined = rules.join(",");
158
+ let output: string;
159
+ try {
160
+ const r = Bun.spawnSync([command, "-p", "--disallowedTools", joined], {
161
+ stdin: new Blob([""]),
162
+ stdout: "pipe",
163
+ stderr: "pipe",
164
+ timeout: opts?.timeoutMs ?? 30_000,
165
+ });
166
+ output = `${r.stdout?.toString() ?? ""}${r.stderr?.toString() ?? ""}`;
167
+ } catch (e) {
168
+ const message = e instanceof Error ? e.message : String(e);
169
+ return {
170
+ reading: "UNMEASURED",
171
+ unknown: [],
172
+ probe: toolProbe({
173
+ outcome: "errored",
174
+ tool: `${command} -p --disallowedTools`,
175
+ reason: `the rule validation run did not complete: ${message.split("\n")[0]}`,
176
+ }),
177
+ };
178
+ }
179
+ return {
180
+ reading: "MEASURED",
181
+ unknown: parseUnknownRuleWarnings(output),
182
+ probe: toolProbe({
183
+ outcome: "available",
184
+ tool: `${command} -p --disallowedTools`,
185
+ reason: `${command} validated ${rules.length} permission rule(s)`,
186
+ }),
187
+ };
188
+ }
@@ -105,6 +105,21 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
105
105
  summary: "Extract constraints from a project's docs into agent rules",
106
106
  usage: "rungate extract-constraints",
107
107
  },
108
+ // Registered so the GENERATED ai-review workflow has something to run. The
109
+ // reader has existed and been tested since #631 and nothing executed it:
110
+ // `lib/scaffold/ai-review-step.ts` emitted a warning saying so by name,
111
+ // because a scaffolded consumer has no copy of rungate's sources at a path
112
+ // the workflow could hardcode. This registry is the path (#675).
113
+ //
114
+ // No `projectRootFlag`: the argument is the findings payload, which lives
115
+ // outside the checkout by design (`RUNNER_TEMP`), and appending
116
+ // `--project-root <cwd>` would arrive as a second positional and be read as
117
+ // a second payload.
118
+ "ai-review-findings": {
119
+ script: "scripts/ai-review-findings.ts",
120
+ summary: "Adjudicate an AI review's findings payload — exits non-zero on a blocking finding",
121
+ usage: "rungate ai-review-findings <path-to-findings.json>",
122
+ },
108
123
  };
109
124
 
110
125
  /** The commands the AGENTS.md generator may publish to a consumer. */
@@ -0,0 +1,42 @@
1
+ /**
2
+ * What a commit SHA looks like, in ONE place (#602).
3
+ *
4
+ * `gates/schema.ts` has carried this pattern since #224 to keep a ref name
5
+ * out of `suiteMeasurement.measuredSha` — the field that says which tree a
6
+ * suite verdict is about. #602 adds a second field with the same job for
7
+ * the harness that did the grading, and a second copy of the pattern would
8
+ * be two deciders for one question: they would agree today, a mutation of
9
+ * either would leave the other refusing, and no behavioural test could
10
+ * tell them apart (`.claude/rules/checks-must-be-able-to-fail.md`, the
11
+ * fourth shape).
12
+ *
13
+ * It lives in `lib/` and not in `gates/` because the dependency runs that
14
+ * way: `gates/schema.ts` already imports from `lib/`, and `lib/` importing
15
+ * back would be a cycle.
16
+ *
17
+ * ## Why 7 and not 40
18
+ *
19
+ * `git rev-parse --short` is the form a human pastes and the form several
20
+ * scripts in this tree print. Demanding 40 would refuse readings that are
21
+ * correct, and a refusal that fires on correct input is the fastest way to
22
+ * build one everybody learns to work around. The thing being excluded is a
23
+ * REF NAME — `main`, `HEAD`, `origin/main`, `rungate/run-602` — because a
24
+ * ref is a pointer and the whole point of recording a SHA is that it still
25
+ * names the same tree tomorrow.
26
+ */
27
+
28
+ /** A commit SHA, short or full. Anchored at both ends: a ref name containing hex is not one. */
29
+ export const COMMIT_SHA = /^[0-9a-f]{7,40}$/i;
30
+
31
+ /**
32
+ * Is this string a commit SHA?
33
+ *
34
+ * Exported beside the pattern so a caller never has to spell `.test()`
35
+ * against a shared `RegExp`. `COMMIT_SHA` carries no `g` flag, so it is
36
+ * stateless and safe to share — a `g` flag would make `lastIndex` persist
37
+ * across callers and produce alternating answers for one input, which is a
38
+ * check that cannot fail every other time it is asked.
39
+ */
40
+ export function isCommitSha(value: unknown): value is string {
41
+ return typeof value === "string" && COMMIT_SHA.test(value);
42
+ }