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,253 @@
1
+ /**
2
+ * Is the session's cwd a safe place to cut agent worktrees from? (#644)
3
+ *
4
+ * ## The thing this does NOT do, stated first
5
+ *
6
+ * It does not derive the worktree base. `workflows/ship.js:1235` has pinned
7
+ * `opts.cwd = PROJECT_ROOT` for every worktree-isolated spawn since
8
+ * `804b9a43` on 2026-09-23, and there is no spawn path that bypasses it —
9
+ * all six roles resolve to `isolation: 'worktree'` and no call site sets it
10
+ * explicitly. **Rungate already passes the explicit argument.**
11
+ *
12
+ * It does not hold. `isolation: 'worktree'` is resolved by the agent
13
+ * runtime against the SESSION'S cwd, and `opts.cwd` is applied to the
14
+ * spawned agent afterwards. Run `wf_5e3ed885-98c` on 2026-10-14 put a
15
+ * remediation Marcus in a worktree of one consumer's repository while
16
+ * working an issue in another — three weeks after the pin landed. The
17
+ * repositories are named on #218; they are deliberately not named here,
18
+ * because the harness must not name its consumers (#304, SC-A1).
19
+ *
20
+ * So the one thing rungate controls is whether the run STARTS. This refuses
21
+ * at launch, before any agent is spawned, when the session's cwd would
22
+ * produce a worktree the run does not want.
23
+ *
24
+ * ## Two failures, one input
25
+ *
26
+ * Both of #644's failures are the same fact wearing different clothes, and
27
+ * the silent one is worse:
28
+ *
29
+ * 1. cwd is not a git repository at all. The runtime says *"not in a git
30
+ * repository and no WorktreeCreate hooks are configured… to use
31
+ * worktree isolation with other VCS systems"*, which is about the
32
+ * session's cwd while naming neither it nor the session. A reader
33
+ * configures hooks they do not need and still has the bug.
34
+ * 2. cwd IS a git repository, in another project or on another branch.
35
+ * Nothing fails. The run cuts its worktrees from somebody else's work
36
+ * and succeeds onto the wrong base, found later by the PR behaving
37
+ * oddly.
38
+ *
39
+ * A check that covers only the first is the cheapest wrong fix for this
40
+ * issue, named in #644's own body: it fixes the symptom that announces
41
+ * itself and leaves the one that does not.
42
+ *
43
+ * ## Why a refusal and not a repair
44
+ *
45
+ * `process.chdir()` would be the repair, and it is not available to a
46
+ * workflow script, nor would it be right: the session's cwd is shared with
47
+ * the operator and with whatever they do next. A run that quietly moved it
48
+ * would be a side effect outside its own worktrees, which is #640's
49
+ * complaint about the shared primary, arriving from the other direction.
50
+ *
51
+ * ## Three readings, not two
52
+ *
53
+ * `SAME_REPO` is not the same as `SAME_CHECKOUT`. The shared primary sits on
54
+ * `rungate/run-<issue>` for the life of a run (#640) — the same repository
55
+ * as `projectRoot`, a different working tree, on a branch belonging to
56
+ * another issue. Collapsing that into "same repo, fine" is the precondition
57
+ * blindness in `.claude/rules/checks-must-be-able-to-fail.md`: every natural
58
+ * fixture runs from the right directory, so the branch where cwd and
59
+ * `projectRoot` are the same repo and disagree anyway is outside the
60
+ * battery's reach entirely.
61
+ */
62
+ import { spawnSync } from "child_process";
63
+
64
+ import { readWorktreeRemote, redactRemote, repoSlug } from "./worktree-repo";
65
+
66
+ /**
67
+ * A path or branch name, quoted and redacted.
68
+ *
69
+ * `worktreeDiskIdentity` in the sibling module redacts everything it
70
+ * interpolates, and a control that does not is a parity gap a reader has
71
+ * to notice. Paths and branch names are not usually credential-bearing —
72
+ * but they come from the environment, a worktree can live under a
73
+ * directory named after one, and `redactRemote` leaves an ordinary path
74
+ * untouched, so the check costs nothing and the omission costs a leak
75
+ * nobody is looking for.
76
+ */
77
+ const safe = (v: unknown) => JSON.stringify(redactRemote(String(v)));
78
+
79
+ /** Every refusal and every pass travels through one of these. */
80
+ export type LaunchBaseReading =
81
+ /** cwd and projectRoot are the same working tree. The only clean answer. */
82
+ | { reading: "SAME_CHECKOUT"; cwd: string; projectRoot: string }
83
+ /** cwd is a git repository, and not one git can resolve a toplevel for. */
84
+ | { reading: "CWD_NOT_A_REPO"; cwd: string; projectRoot: string; refusal: string }
85
+ /** cwd is a repository in a DIFFERENT project. Failure 2, loud version. */
86
+ | { reading: "DIFFERENT_REPO"; cwd: string; projectRoot: string; refusal: string }
87
+ /** Same repository, different working tree or branch. Failure 2, quiet version. */
88
+ | { reading: "DIFFERENT_CHECKOUT"; cwd: string; projectRoot: string; refusal: string }
89
+ /**
90
+ * Something could not be read. NOT a pass: a reading that could not be
91
+ * taken is indistinguishable from a clean one, and only one of them is
92
+ * reportable (`.claude/rules/config-access.md`).
93
+ */
94
+ | { reading: "UNMEASURED"; cwd: string; projectRoot: string; refusal: string };
95
+
96
+ /** `git -C <dir> rev-parse --show-toplevel`, or `null`. */
97
+ function toplevel(dir: string): string | null {
98
+ if (typeof dir !== "string" || !dir.trim()) return null;
99
+ const got = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
100
+ timeout: 10_000,
101
+ encoding: "utf-8",
102
+ });
103
+ if (got.error || got.status !== 0) return null;
104
+ const out = String(got.stdout || "").trim();
105
+ return out === "" ? null : out;
106
+ }
107
+
108
+ /** `git -C <dir> rev-parse --abbrev-ref HEAD`, or `null`. */
109
+ function branchOf(dir: string): string | null {
110
+ const got = spawnSync("git", ["-C", dir, "rev-parse", "--abbrev-ref", "HEAD"], {
111
+ timeout: 10_000,
112
+ encoding: "utf-8",
113
+ });
114
+ if (got.error || got.status !== 0) return null;
115
+ const out = String(got.stdout || "").trim();
116
+ return out === "" ? null : out;
117
+ }
118
+
119
+ /**
120
+ * The reading for one launch.
121
+ *
122
+ * ONE discriminator, `reading`. Every other field is a projection of the
123
+ * same two probes taken here and nowhere else, so no two of them can
124
+ * disagree — and a caller that only wants a boolean derives it with
125
+ * `launchBaseRefusal` rather than re-asking git.
126
+ *
127
+ * The comparison is by RESOLVED TOPLEVEL first and by remote slug second,
128
+ * in that order and for a reason. Two worktrees of one repository have
129
+ * different toplevels and the same remote; two clones of one repository
130
+ * have different toplevels and the same remote as well. Only the toplevel
131
+ * separates "the tree the run was handed" from "another tree of the same
132
+ * project", and that distinction is the whole of failure 2's quiet half.
133
+ */
134
+ export function launchBaseReading(cwd: string, projectRoot: string): LaunchBaseReading {
135
+ // RAW for probing, REDACTED for reporting, and the two are never mixed
136
+ // up: `git -C` must receive the real path, and a redacted one would send
137
+ // the probe to a directory that does not exist — which resolves to
138
+ // CWD_NOT_A_REPO and reads exactly like the finding this module exists
139
+ // to report. Everything returned is built from `here`; everything handed
140
+ // to git comes from `raw`.
141
+ const raw = { cwd: String(cwd ?? ""), projectRoot: String(projectRoot ?? "") };
142
+ // Redacted ON THE READING, not at each call site. `check-launch-base.ts`
143
+ // serialises the whole object, and a caller that had to remember to
144
+ // redact is a control one caller will forget.
145
+ const here = { cwd: redactRemote(raw.cwd), projectRoot: redactRemote(raw.projectRoot) };
146
+
147
+ if (!raw.projectRoot.trim()) {
148
+ return {
149
+ ...here,
150
+ reading: "UNMEASURED",
151
+ refusal:
152
+ "no projectRoot was given, so there is nothing for the launching session's working directory to be " +
153
+ "compared against — a run that cannot state which tree it is for cannot check that it is in it",
154
+ };
155
+ }
156
+
157
+ const rootTop = toplevel(raw.projectRoot);
158
+ if (rootTop === null) {
159
+ return {
160
+ ...here,
161
+ reading: "UNMEASURED",
162
+ refusal:
163
+ `projectRoot ${safe(here.projectRoot)} is not a git repository git can resolve. ` +
164
+ "This is the run's own argument and not the launching session's working directory, so it is reported " +
165
+ "as unmeasured rather than as the cwd problem this check exists for",
166
+ };
167
+ }
168
+
169
+ const cwdTop = toplevel(raw.cwd);
170
+ if (cwdTop === null) {
171
+ // Failure 1, said about the right input. The runtime's own message for
172
+ // this state names neither the directory nor the fact that it is the
173
+ // SESSION's, and recommends VCS hook configuration that is irrelevant.
174
+ return {
175
+ ...here,
176
+ reading: "CWD_NOT_A_REPO",
177
+ refusal:
178
+ `the launching session's working directory ${safe(here.cwd)} is not a git repository. ` +
179
+ `projectRoot ${safe(here.projectRoot)} is one, and is correct — but agent worktrees ` +
180
+ "are cut by the runtime from the SESSION's directory, not from projectRoot, so this run " +
181
+ "would die at the first isolated spawn. This is not a VCS-configuration problem and " +
182
+ "WorktreeCreate hooks will not fix it: cd into projectRoot and relaunch",
183
+ };
184
+ }
185
+
186
+ if (cwdTop === rootTop) return { ...here, reading: "SAME_CHECKOUT" };
187
+
188
+ // Different trees. Which KIND of different decides what the operator does
189
+ // next, so the two are never collapsed.
190
+ const cwdRemote = readWorktreeRemote(cwdTop);
191
+ const rootRemote = readWorktreeRemote(rootTop);
192
+ const cwdSlug = repoSlug(cwdRemote.url);
193
+ const rootSlug = repoSlug(rootRemote.url);
194
+
195
+ if (cwdSlug === null || rootSlug === null) {
196
+ // A tree with no resolvable origin is not a tree we can clear. Refusing
197
+ // rather than passing: the guard must not go inert for exactly the
198
+ // misconfigured checkout most likely to need it (#218's reasoning).
199
+ return {
200
+ ...here,
201
+ reading: "UNMEASURED",
202
+ refusal:
203
+ `the launching session's working directory ${safe(cwdTop)} and projectRoot ` +
204
+ `${safe(rootTop)} are different trees, and at least one of them has no origin ` +
205
+ `remote this can resolve (cwd: ${cwdSlug ?? redactRemote(String(cwdRemote.error ?? cwdRemote.url))}, ` +
206
+ `projectRoot: ${rootSlug ?? redactRemote(String(rootRemote.error ?? rootRemote.url))}). ` +
207
+ "Whether they are the same project is therefore unknown, and unknown is not clean",
208
+ };
209
+ }
210
+
211
+ if (cwdSlug !== rootSlug) {
212
+ return {
213
+ ...here,
214
+ reading: "DIFFERENT_REPO",
215
+ refusal:
216
+ `the launching session's working directory ${safe(cwdTop)} is a checkout of ${cwdSlug}, but ` +
217
+ `this run targets ${rootSlug} at ${safe(rootTop)}. Agent worktrees are cut by the ` +
218
+ "runtime from the SESSION's directory, so this run would do its work in the wrong repository " +
219
+ "and succeed — which is how run wf_5e3ed885-98c put a remediation agent in a checkout of " +
220
+ "one consumer's repository while working an issue in another (#218). cd into projectRoot and relaunch",
221
+ };
222
+ }
223
+
224
+ // Same project, different working tree. The quiet one: nothing fails, and
225
+ // the run lands on whatever branch that tree happens to be parked on.
226
+ const cwdBranch = branchOf(cwdTop);
227
+ const rootBranch = branchOf(rootTop);
228
+ return {
229
+ ...here,
230
+ reading: "DIFFERENT_CHECKOUT",
231
+ refusal:
232
+ `the launching session's working directory ${safe(cwdTop)} and projectRoot ` +
233
+ `${safe(rootTop)} are two different working trees of the same repository ` +
234
+ `(${rootSlug}) — cwd is on ${cwdBranch ?? "an unreadable branch"} and projectRoot is on ` +
235
+ `${rootBranch ?? "an unreadable branch"}. Agent worktrees are cut by the runtime from the ` +
236
+ "SESSION's directory, so this run would cut from a tree it was not handed, and nothing would " +
237
+ "fail. A shared primary parked on another issue's run branch is exactly this state (#640). " +
238
+ "cd into projectRoot and relaunch",
239
+ };
240
+ }
241
+
242
+ /**
243
+ * The refusal string for a launch, or `null` when there is nothing to say.
244
+ *
245
+ * Derived from `launchBaseReading` and never from a second probe, so the
246
+ * boolean and the reading cannot disagree. `SAME_CHECKOUT` is the only
247
+ * reading that clears: UNMEASURED refuses with the rest, because a check
248
+ * that could not be run is not a check that passed.
249
+ */
250
+ export function launchBaseRefusal(cwd: string, projectRoot: string): string | null {
251
+ const reading = launchBaseReading(cwd, projectRoot);
252
+ return reading.reading === "SAME_CHECKOUT" ? null : reading.refusal;
253
+ }
@@ -0,0 +1,372 @@
1
+ /**
2
+ * Read a `path.ts:<N>` citation, and refuse to call it correct (#541).
3
+ *
4
+ * `lib/source-anchor.ts` (#514) is the form this repository is moving TO: a
5
+ * citation that carries the text it is about, so the resolver reports the
6
+ * position instead of the document asserting it. This module is about the
7
+ * 231 citations still written the old way, and the measurement that says
8
+ * why they need a guard rather than a cleanup:
9
+ *
10
+ * Of `specs/GATE-CONTRACTS-SPEC.md`'s seven line citations, the three under
11
+ * a test were correct and **three of the four unguarded ones were already
12
+ * wrong** — `gate-executor.ts:1725` pointed at a `parseFloat`,
13
+ * `evidence-prevalidator.ts:208` at a comment, `scaffold-rungate-config.ts:66`
14
+ * at an unrelated `existsSync`. Each pointed at a plausible-looking line in
15
+ * the right file, and nobody had noticed because nothing could.
16
+ *
17
+ * Two readings follow from that, and both are refusals of a comfortable
18
+ * default:
19
+ *
20
+ * **There is no VALID.** `LineReading` has two arms. A citation that
21
+ * resolves is `UNMEASURED`, not correct: the file exists and the line
22
+ * exists, and whether it is the line the sentence describes is not something
23
+ * this code can decide. A 75% staleness rate in the unguarded half of one
24
+ * document is the argument against reporting "ok" — `0`, `null`, `SKIP` and
25
+ * a green tick are all indistinguishable from a correct answer, and a
26
+ * refusal naming the reading is not.
27
+ *
28
+ * **A citation that cannot be resolved has a named cause.** A file that
29
+ * moved, a bare basename, a basename matching two files, a line past the
30
+ * end — four different repairs, so four different readings. "This citation
31
+ * is broken" is not actionable; `steps.ts:43` is ambiguous between two files
32
+ * and `src/api/auth.ts:23` names nothing at all, and the fix for one is not
33
+ * the fix for the other.
34
+ *
35
+ * The enforcement splits the same way, which is the only honest split
36
+ * available: the anchor form is DECIDABLE, so `citationFailures` is a hard
37
+ * gate over every document in the tree; the line form is not, so the
38
+ * population is held by a both-ways ratchet that records what it banked.
39
+ */
40
+ import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "fs";
41
+ import { join, resolve, sep } from "path";
42
+
43
+ import { anchorCitations, citationFailures } from "./source-anchor";
44
+
45
+ /**
46
+ * `path.ts:<N>`, optionally opening a code span.
47
+ *
48
+ * Deliberately NOT matching the historical prose form. "line 4462 of ship.js
49
+ * as it then stood" is a paragraph whose whole point is that the line no
50
+ * longer exists, and refusing it would be refusing the document for being
51
+ * about history. The two forms are distinguished by the colon and nothing
52
+ * else, which is why that boundary is asserted rather than described.
53
+ */
54
+ export const LINE_CITATION = /`?\b([A-Za-z0-9_./-]+\.(?:ts|js|json)):(\d+)\b/g;
55
+
56
+ export interface LineCitation {
57
+ path: string;
58
+ line: number;
59
+ raw: string;
60
+ }
61
+
62
+ export type BrokenCause =
63
+ | "NO_SUCH_FILE"
64
+ | "UNQUALIFIED_PATH"
65
+ | "AMBIGUOUS_PATH"
66
+ | "PAST_END_OF_FILE"
67
+ | "OUTSIDE_REPOSITORY";
68
+
69
+ /**
70
+ * Two arms. Adding a third that means "fine" would undo the whole module.
71
+ */
72
+ export type LineReading =
73
+ | { reading: "BROKEN"; cause: BrokenCause; cite: LineCitation; detail: string }
74
+ | { reading: "UNMEASURED"; cite: LineCitation; detail: string };
75
+
76
+ /** Raised when a document that should carry citations yields none (#621). */
77
+ export class NoLineCitationsError extends Error {
78
+ constructor(message: string) {
79
+ super(message);
80
+ this.name = "NoLineCitationsError";
81
+ }
82
+ }
83
+
84
+ /** Every line citation in a document, in order. */
85
+ export function lineCitations(doc: string): LineCitation[] {
86
+ const out: LineCitation[] = [];
87
+ // Anchor citations contain a path and a quoted fragment, and a fragment
88
+ // can end in `.ts:12`. Removing them first stops the new form being
89
+ // counted as an instance of the old one.
90
+ const text = doc.replace(/`[A-Za-z0-9_./-]+@"[^"`]*"`/g, " ");
91
+ for (const m of text.matchAll(LINE_CITATION)) {
92
+ out.push({ path: m[1], line: Number.parseInt(m[2], 10), raw: m[0] });
93
+ }
94
+ return out;
95
+ }
96
+
97
+ const SKIP_DIRS = new Set([
98
+ ".git",
99
+ "node_modules",
100
+ "worktrees",
101
+ "dist",
102
+ "build",
103
+ "coverage",
104
+ ".next",
105
+ ".bun",
106
+ ]);
107
+
108
+ function walk(root: string, rel: string, out: string[], want: (p: string) => boolean): void {
109
+ let entries;
110
+ try {
111
+ entries = readdirSync(join(root, rel), { withFileTypes: true });
112
+ } catch {
113
+ // A directory that cannot be read is not an empty directory. Nothing in
114
+ // this walk can repair that, but it must not be reported as "nothing
115
+ // here" either, so the caller's control — a floor on the count — is what
116
+ // catches it rather than a silent zero.
117
+ return;
118
+ }
119
+ for (const e of entries) {
120
+ if (e.name.startsWith(".") && e.name !== ".claude" && e.name !== ".github") continue;
121
+ const next = rel ? `${rel}/${e.name}` : e.name;
122
+ // `isDirectory()` is false for a symlink, which is what keeps the walk
123
+ // out of the `node_modules` link a worktree carries.
124
+ if (e.isDirectory()) {
125
+ if (SKIP_DIRS.has(e.name)) continue;
126
+ walk(root, next, out, want);
127
+ } else if (e.isFile() && want(next)) {
128
+ out.push(next);
129
+ }
130
+ }
131
+ }
132
+
133
+ /** Every repository-relative file path, for deciding whether a basename is unique. */
134
+ export function repoFileIndex(root: string): string[] {
135
+ const out: string[] = [];
136
+ walk(root, "", out, () => true);
137
+ return out.sort();
138
+ }
139
+
140
+ /** Every markdown document in the tree. */
141
+ export function markdownDocuments(root: string): string[] {
142
+ const out: string[] = [];
143
+ walk(root, "", out, p => p.endsWith(".md"));
144
+ return out.sort();
145
+ }
146
+
147
+ /**
148
+ * What a line citation can be said about, which is never that it is right.
149
+ */
150
+ export function readLineCitation(root: string, index: string[], cite: LineCitation): LineReading {
151
+ const { path } = cite;
152
+ const broken = (cause: BrokenCause, detail: string): LineReading =>
153
+ ({ reading: "BROKEN", cause, cite, detail });
154
+
155
+ // `join` concatenates a leading slash rather than absorbing it, so an
156
+ // absolute citation reads `<root>/etc/passwd` and the containment check
157
+ // below has nothing to say about it. Refused on its own, because a
158
+ // citation written absolute means something other than what its author
159
+ // thinks it means.
160
+ if (path.startsWith("/")) {
161
+ return broken("OUTSIDE_REPOSITORY", `${path} is absolute — citations are repository-relative`);
162
+ }
163
+ const full = join(root, path);
164
+ if (!resolve(full).startsWith(resolve(root) + sep)) {
165
+ return broken("OUTSIDE_REPOSITORY", `${path} resolves outside the repository`);
166
+ }
167
+
168
+ if (existsSync(full) && statSync(full).isFile()) {
169
+ // The symlink question the lexical check cannot answer: a link inside
170
+ // the tree whose target is outside it passes containment and then reads
171
+ // a file that is not in the repository at all.
172
+ if (!realpathSync(full).startsWith(realpathSync(resolve(root)) + sep)) {
173
+ return broken("OUTSIDE_REPOSITORY", `${path} is a symlink whose target is outside the repository`);
174
+ }
175
+ const lines = readFileSync(full, "utf-8").split("\n").length;
176
+ if (cite.line > lines) {
177
+ return broken("PAST_END_OF_FILE", `${path} has ${lines} lines, so line ${cite.line} is not in it`);
178
+ }
179
+ return {
180
+ reading: "UNMEASURED",
181
+ cite,
182
+ detail:
183
+ `${path}:${cite.line} names a line that exists; whether it is the line this sentence ` +
184
+ `describes cannot be decided mechanically`,
185
+ };
186
+ }
187
+
188
+ // Not a path in this repository. It may still be a basename somebody wrote
189
+ // instead of one, which is a different defect with a different repair.
190
+ const suffix = `/${path}`;
191
+ const candidates = index.filter(f => f === path || f.endsWith(suffix));
192
+ if (candidates.length === 0) {
193
+ return broken("NO_SUCH_FILE", `${path} names no file in the repository`);
194
+ }
195
+ if (candidates.length > 1) {
196
+ return broken(
197
+ "AMBIGUOUS_PATH",
198
+ `${path} matches ${candidates.length} files (${candidates.join(", ")}), so it names no site`,
199
+ );
200
+ }
201
+ return broken(
202
+ "UNQUALIFIED_PATH",
203
+ `${path} is not a repository path; it probably means ${candidates[0]}, and writing that down ` +
204
+ `is the repair`,
205
+ );
206
+ }
207
+
208
+ export interface DocumentCensus {
209
+ broken: number;
210
+ unmeasured: number;
211
+ anchors: number;
212
+ readings: LineReading[];
213
+ anchorFailures: string[];
214
+ }
215
+
216
+ /**
217
+ * Count one document's citations by reading.
218
+ *
219
+ * `expectCitations` is the ratchet's statement that this document carries
220
+ * some. When it does and none are found, this THROWS — because a checker
221
+ * that finds zero citations in every document is in perfect agreement, and
222
+ * zero strings are trivially all fine. Returning an empty census would fold
223
+ * a dead pattern into a clean result, which is the exact shape #621
224
+ * describes: the refusal has to escape.
225
+ */
226
+ export function documentCensus(
227
+ root: string,
228
+ index: string[],
229
+ docPath: string,
230
+ expectCitations: boolean,
231
+ ): DocumentCensus {
232
+ const full = join(root, docPath);
233
+ if (!existsSync(full)) {
234
+ throw new NoLineCitationsError(
235
+ `${docPath} is banked in the citation ratchet and is not in the tree. If the document was ` +
236
+ `removed or renamed, delete or move its entry in the same commit.`,
237
+ );
238
+ }
239
+ const text = readFileSync(full, "utf-8");
240
+ const cites = lineCitations(text);
241
+ if (expectCitations && cites.length === 0) {
242
+ throw new NoLineCitationsError(
243
+ `${docPath} is banked in the citation ratchet as carrying line citations and the census ` +
244
+ `found none. Either every one of them was converted — in which case delete the entry's ` +
245
+ `broken and unmeasured counts in the same commit — or LINE_CITATION has stopped matching, ` +
246
+ `in which case this guard was about to pass over the whole tree.`,
247
+ );
248
+ }
249
+ const readings = cites.map(c => readLineCitation(root, index, c));
250
+ return {
251
+ broken: readings.filter(r => r.reading === "BROKEN").length,
252
+ unmeasured: readings.filter(r => r.reading === "UNMEASURED").length,
253
+ anchors: anchorCitations(text).length,
254
+ readings,
255
+ anchorFailures: citationFailures(root, text),
256
+ };
257
+ }
258
+
259
+ export interface RatchetEntry {
260
+ broken: number;
261
+ unmeasured: number;
262
+ anchors: number;
263
+ note?: string;
264
+ }
265
+
266
+ export interface CitationRatchet {
267
+ meaning: string[];
268
+ documents: Record<string, RatchetEntry>;
269
+ }
270
+
271
+ /**
272
+ * The banked population, read from `.claude/line-citation-ratchet.json`.
273
+ *
274
+ * A tree with no file gets no entries — zero tolerance, which is the right
275
+ * default for a project that has never had the defect. `lib/` travels into
276
+ * every scaffolded project and rungate's own numbers have no business there.
277
+ */
278
+ export function readCitationRatchet(root: string): CitationRatchet {
279
+ const p = join(root, ".claude", "line-citation-ratchet.json");
280
+ if (!existsSync(p)) return { meaning: [], documents: {} };
281
+ const raw = JSON.parse(readFileSync(p, "utf-8"));
282
+ const documents: Record<string, RatchetEntry> = {};
283
+ for (const [k, v] of Object.entries(raw.documents ?? {})) {
284
+ const e = v as Record<string, unknown>;
285
+ if (typeof e?.broken !== "number" || typeof e?.unmeasured !== "number" || typeof e?.anchors !== "number") {
286
+ // A malformed entry is not an absent one. Skipping it silently would
287
+ // turn a typo into an exemption, which is the fail-open this file is
288
+ // about; the comparison below then reports the document as unbanked.
289
+ continue;
290
+ }
291
+ documents[k] = { broken: e.broken, unmeasured: e.unmeasured, anchors: e.anchors };
292
+ }
293
+ return { meaning: Array.isArray(raw.meaning) ? raw.meaning.map(String) : [], documents };
294
+ }
295
+
296
+ /**
297
+ * Turn the census into refusals. THE binding — one place to mutate.
298
+ *
299
+ * Both directions, per number. Over the banked count fails, and so does
300
+ * under it: an entry that has stopped being true is an entry nobody will
301
+ * ever remove, and the file rots into a number nobody lowers.
302
+ *
303
+ * Three numbers rather than one, because a single total cannot see progress
304
+ * happen. Qualifying `ship.js:<N>` to `workflows/ship.js:<N>` deletes
305
+ * nothing and adds nothing, and converting a line citation to the anchor
306
+ * form looks, to a total, exactly like deleting it. **The arithmetic cannot
307
+ * forbid a deletion — a paragraph is allowed to go away — so what it does
308
+ * instead is make the three numbers move differently, so a reviewer reading
309
+ * the diff can tell a conversion from a deletion.** That distinction is the
310
+ * point of the file and it is written into the file.
311
+ *
312
+ * Anchor citations are NOT ratcheted for correctness: an anchor carries its
313
+ * own text, so whether it still names a site is decidable, and there is
314
+ * nothing to tolerate. Their failures are returned as hard violations here
315
+ * for every document in the tree — enforce the half the repository owns,
316
+ * and report the other half as UNMEASURED.
317
+ */
318
+ export function citationRatchetViolations(
319
+ root: string,
320
+ index: string[],
321
+ docs: string[],
322
+ ratchet: CitationRatchet,
323
+ ): string[] {
324
+ const out: string[] = [];
325
+ const seen = new Set<string>();
326
+
327
+ for (const doc of docs) {
328
+ const entry = ratchet.documents[doc];
329
+ seen.add(doc);
330
+ const census = documentCensus(root, index, doc, (entry?.broken ?? 0) + (entry?.unmeasured ?? 0) > 0);
331
+
332
+ for (const f of census.anchorFailures) {
333
+ out.push(`${doc}: an anchor citation no longer names a site — ${f}`);
334
+ }
335
+
336
+ if (!entry) {
337
+ if (census.broken + census.unmeasured > 0) {
338
+ out.push(
339
+ `${doc} is not in .claude/line-citation-ratchet.json and carries ` +
340
+ `${census.broken + census.unmeasured} line citations. A document absent from the ratchet ` +
341
+ `is allowed none: the migration window is exactly when the next one gets written.`,
342
+ );
343
+ }
344
+ continue;
345
+ }
346
+
347
+ const rows: [keyof RatchetEntry & string, number, number][] = [
348
+ ["broken", census.broken, entry.broken],
349
+ ["unmeasured", census.unmeasured, entry.unmeasured],
350
+ ["anchors", census.anchors, entry.anchors],
351
+ ];
352
+ for (const [name, found, banked] of rows) {
353
+ if (found === banked) continue;
354
+ out.push(
355
+ found > banked
356
+ ? `${doc}: ${found} ${name} citations, ${banked} banked. Bank the number in the same ` +
357
+ `commit that earned it, and say in the PR why it went up.`
358
+ : `${doc}: ${found} ${name} citations, ${banked} banked. Lower it — or delete the entry ` +
359
+ `if the document has none left. A stale entry is a number nobody lowers.`,
360
+ );
361
+ }
362
+ }
363
+
364
+ for (const doc of Object.keys(ratchet.documents)) {
365
+ if (seen.has(doc)) continue;
366
+ out.push(
367
+ `${doc} is banked in .claude/line-citation-ratchet.json and was not among the documents ` +
368
+ `scanned. Delete its entry in the same commit that removed or renamed it.`,
369
+ );
370
+ }
371
+ return out;
372
+ }