rungate 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -0,0 +1,140 @@
1
+ /**
2
+ * The remedy line a conformity failure carries, and the routing to the rule
3
+ * file that explains the whole family (#813).
4
+ *
5
+ * ## Why this exists
6
+ *
7
+ * The checks in `.claude/rules/self-referential-tests.md`'s Tier 1 assert a
8
+ * property about the REPOSITORY, not about a unit of code. They go red on a
9
+ * pull request that never opened the file they are about: add a spec, and
10
+ * `HYGIENE-4` fails; add a script, and `HYGIENE-3` fails. The agent who needs
11
+ * that document is by definition staring at a test failure, and measured on
12
+ * `e0429b82` not one of those failures named it — two references in the whole
13
+ * executable tree, both prose inside a docblock, against 321 for
14
+ * `checks-must-be-able-to-fail`.
15
+ *
16
+ * So the document was unreachable from the only place it was ever needed.
17
+ *
18
+ * ## The two layers, and why they are not one
19
+ *
20
+ * `lib/conformity.ts` is published, and `lib/scaffold/steps.ts` generates the
21
+ * consumer test that calls it. The rule file has exactly one copy in this tree
22
+ * and no template copy, so it does NOT ship. Hardcoding its path into the
23
+ * published failure text would point every consumer at a file they do not
24
+ * have — a dangling route, which is the defect `test/rule-provenance.test.ts`
25
+ * exists to catch and cannot catch across the package boundary.
26
+ *
27
+ * Hence `fix` and `pointer` are separate:
28
+ *
29
+ * - The **fix** is a claim about the project's own tree and is true anywhere.
30
+ * "Add a row to `.claude/rules/specs-routing.md`" is the real remedy in a
31
+ * consumer exactly as it is here.
32
+ * - The **pointer** is DERIVED, not configured: it is emitted only when the
33
+ * rule file is present under `root`. No new config key, nothing for a
34
+ * consumer to set, absent where it would be wrong, and it begins working
35
+ * for a consumer on the day they adopt the file.
36
+ *
37
+ * A config key was the other option and is worse: it is a second decider about
38
+ * whether the document exists, and the two could disagree — the key set in a
39
+ * project that deleted the file routes an agent to nothing.
40
+ */
41
+
42
+ import { existsSync } from "fs";
43
+ import { join } from "path";
44
+
45
+ import { stripJsComments } from "./strip-js-comments";
46
+
47
+ /**
48
+ * The document, relative to a project root.
49
+ *
50
+ * Spelled once. A second copy is the thing
51
+ * `.claude/rules/checks-must-be-able-to-fail.md` calls two deciders that
52
+ * agree: the existence probe and the printed path would be free to drift, and
53
+ * the failure mode is silent — a pointer that prints a path nobody checked.
54
+ */
55
+ export const SELF_REFERENTIAL_RULES = ".claude/rules/self-referential-tests.md";
56
+
57
+ /**
58
+ * The routing sentence, or `""` when this project does not carry the document.
59
+ *
60
+ * Returns the empty string rather than throwing or omitting a field, because
61
+ * every caller is composing a message and an empty segment drops out of a
62
+ * `filter(Boolean).join()` without a branch at each site.
63
+ */
64
+ export function ruleDocPointer(root: string): string {
65
+ if (!existsSync(join(root, SELF_REFERENTIAL_RULES))) return "";
66
+ return (
67
+ `This check asserts a property of the REPOSITORY, so it can go red on a change ` +
68
+ `that never touched its subject. ${SELF_REFERENTIAL_RULES} lists the others ` +
69
+ `that behave this way and what each one wants.`
70
+ );
71
+ }
72
+
73
+ /**
74
+ * A conformity failure message: what is wrong, what to do, and where the rest
75
+ * of the family is documented.
76
+ *
77
+ * The `fix` is mandatory and takes no default. A default would let a new check
78
+ * be written with no remedy and still look like it had one, which is the
79
+ * failure this module was built to end — `test/check-remedy.test.ts` holds the
80
+ * population of Tier 1 checks for the same reason.
81
+ */
82
+ export function remedyMessage(opts: {
83
+ root: string;
84
+ check: string;
85
+ violations: string[];
86
+ fix: string;
87
+ }): string {
88
+ const { root, check, violations, fix } = opts;
89
+ const subject = violations.length === 0 ? "(none)" : violations.join(", ");
90
+ return [
91
+ `${check}: ${violations.length} violation(s) — ${subject}`,
92
+ `FIX: ${fix}`,
93
+ ruleDocPointer(root),
94
+ ]
95
+ .filter(Boolean)
96
+ .join("\n");
97
+ }
98
+
99
+ /**
100
+ * How far before a call site an `expect(` may open and still be counted as
101
+ * the assertion it belongs to.
102
+ *
103
+ * Generous on purpose. The cost of being too wide is a call site credited to
104
+ * a nearby assertion it does not serve; the cost of being too narrow is a
105
+ * correctly-wired check reported as missing, which trains the next agent to
106
+ * widen the number rather than read it.
107
+ */
108
+ const EXPECT_WINDOW = 200;
109
+
110
+ /** How far into a call site to look for its `check:` field. */
111
+ const FIELD_WINDOW = 600;
112
+
113
+ /**
114
+ * The `check:` value of every ASSERTED `remedyMessage(...)` call in a source.
115
+ *
116
+ * Pure, and over text rather than a path, because the two properties below
117
+ * are the whole point and neither can be witnessed against the live tree —
118
+ * the live tree has no violating file to find, so a scan that silently lost
119
+ * both would return the right answer today and nothing the day it mattered.
120
+ * `test/check-remedy.test.ts` plants a source for each.
121
+ *
122
+ * - **Comments are not code.** The scan looks for a symbol that this very
123
+ * docblock names. Counting prose would let a file satisfy the guard by
124
+ * describing the call it does not make — a checker that greps for a string
125
+ * cannot tell a use from a mention of one.
126
+ * - **A composed message is not an asserted one.** Building the string and
127
+ * never passing it to `expect` leaves the check failing with nothing while
128
+ * the guard reads green, which is the cheapest wrong way to go green here.
129
+ */
130
+ export function routedCheckIds(source: string): string[] {
131
+ const src = stripJsComments(source);
132
+ const found: string[] = [];
133
+ const CALL = "remedyMessage(";
134
+ for (let i = src.indexOf(CALL); i !== -1; i = src.indexOf(CALL, i + 1)) {
135
+ if (!src.slice(Math.max(0, i - EXPECT_WINDOW), i).includes("expect(")) continue;
136
+ const field = /check:\s*"([^"]+)"/.exec(src.slice(i, i + FIELD_WINDOW));
137
+ if (field) found.push(field[1]!);
138
+ }
139
+ return found;
140
+ }
@@ -62,7 +62,7 @@ export interface CheckoutModelResult {
62
62
  export const UNMODELLED: readonly string[] = [
63
63
  "the runner OS — CI is ubuntu-latest and this runs on the developer's machine, so anything platform-dependent (BSD vs GNU flags, path casing, file watchers) is still invisible here",
64
64
  "a fresh `bun install` — node_modules is linked from the working tree rather than installed, so a missing or mis-ranged dependency still passes locally",
65
- "the bun version — CI pins `bun-version: latest` at the moment the job runs; this uses whichever bun is on PATH",
65
+ "the bun version — CI installs what `.bun-version` declares (or `ci.bunVersion` when that file is absent; the file wins, and `declaredBunVersion` reports the disagreement when both exist) and this uses whichever bun is on PATH; since #622 the run REPORTS which one it is and whether it matches, but nothing here switches runtimes, so a mismatch is announced rather than removed",
66
66
  "the PR merge commit — `actions/checkout@v4` on a pull_request checks out a merge of the head into the base, while this checks out the head alone, so a conflict-free-but-broken merge is not modelled",
67
67
  "network and API availability — CI has neither the developer's `gh` credentials (stripped) nor their network conditions",
68
68
  "files git ignores — a `.env` or a stray build artefact present locally and absent in CI is carried over only if git can see it",
@@ -424,3 +424,20 @@ export function prepareCiCheckout(opts: PrepareOptions): PrepareOutcome {
424
424
 
425
425
  return { ok: true, dir: dest, model, refs: result.refs, carried };
426
426
  }
427
+
428
+ /**
429
+ * The job in a generated ci.yml that actually checks out and runs the suite
430
+ * (#735).
431
+ *
432
+ * `test` normally. When `ci.shards > 1` the suite moves to the `test-shard`
433
+ * matrix and `test` becomes the aggregate that reads the matrix result and
434
+ * runs no tests — so a reader that only knows `test` reports "no
435
+ * actions/checkout step" for a workflow that checks out four times.
436
+ *
437
+ * One exported binding, because the same question is asked by
438
+ * `scripts/contract-parity.ts`. Two readers that agree today are one decider
439
+ * too many (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
440
+ */
441
+ export function suiteJobName(workflowYaml: string): string {
442
+ return /^ {2}test-shard:\s*$/m.test(workflowYaml) ? "test-shard" : "test";
443
+ }
@@ -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
+ }