rungate 0.8.2 → 0.8.3

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 (63) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/DocHygiene.hook.ts +2 -1
  9. package/hooks/GateResultProtection.hook.ts +28 -7
  10. package/hooks/HookCurrency.hook.ts +48 -1
  11. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  12. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  13. package/lib/ai-review-jury.ts +725 -0
  14. package/lib/ai-review-rounds.ts +791 -4
  15. package/lib/ai-review-unmeasured.ts +361 -0
  16. package/lib/bash-write-guard.ts +1235 -102
  17. package/lib/cli-commands.ts +252 -11
  18. package/lib/closing-reference-audit.ts +163 -0
  19. package/lib/conformity.ts +12 -0
  20. package/lib/create-sc.ts +45 -12
  21. package/lib/derived-spec.ts +206 -0
  22. package/lib/file-claims.ts +335 -0
  23. package/lib/finding-arbiter.ts +502 -28
  24. package/lib/finding-jury.ts +48 -1
  25. package/lib/finding-pr-routing.ts +333 -0
  26. package/lib/frontmatter.ts +16 -0
  27. package/lib/gate-check-audit.ts +259 -0
  28. package/lib/generators/agents-md.ts +29 -0
  29. package/lib/github.ts +112 -7
  30. package/lib/hook-tree-currency.ts +494 -0
  31. package/lib/issue-closure-audit.ts +161 -14
  32. package/lib/issue-create-override.ts +53 -3
  33. package/lib/issue-filing-gate.ts +1073 -76
  34. package/lib/local-review-rounds.ts +523 -0
  35. package/lib/organize.ts +10 -0
  36. package/lib/project-state-shape.ts +56 -5
  37. package/lib/repo-path.ts +94 -0
  38. package/lib/report-provenance.ts +65 -3
  39. package/lib/risk-tier.ts +302 -0
  40. package/lib/rounds-to-pass.ts +274 -0
  41. package/lib/rule-row-drift.ts +199 -0
  42. package/lib/sc-claim-forms.ts +33 -5
  43. package/lib/sc-guard.ts +11 -1
  44. package/lib/sc-id-cross-tree.ts +17 -2
  45. package/lib/sc-ids.ts +71 -6
  46. package/lib/sc-reservations.ts +158 -14
  47. package/lib/scaffold/ai-review-findings.ts +1157 -18
  48. package/lib/scaffold/ai-review-step.ts +3798 -76
  49. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  50. package/lib/scaffold/owned-files.ts +14 -0
  51. package/lib/scaffold/steps.ts +83 -9
  52. package/lib/scratch-roots.ts +93 -3
  53. package/lib/spec-updater.ts +16 -0
  54. package/lib/validators/spec-validators.ts +28 -2
  55. package/package.json +2 -1
  56. package/scripts/ai-review-findings.ts +41 -1
  57. package/scripts/arbitrate-finding.ts +330 -12
  58. package/scripts/audit-specs.ts +225 -23
  59. package/scripts/create-sc.ts +11 -0
  60. package/scripts/detect-sc-drift.ts +10 -2
  61. package/scripts/record-ai-review-unmeasured.ts +370 -0
  62. package/scripts/split-spec.ts +12 -0
  63. package/scripts/sync-sc-status.ts +11 -0
@@ -0,0 +1,206 @@
1
+ /**
2
+ * Whether a spec file's bytes are authored by a person or produced by a
3
+ * generator — and therefore whether any rungate write path may touch them
4
+ * (#1286).
5
+ *
6
+ * On 2026-10-22 `bunx rungate audit-specs --fix` injected 39 lines of
7
+ * `<!-- REVIEW: unmatched (...) -->` into a consumer's `specs/POV-SPEC.md`.
8
+ * That file is produced by the consumer's own `scripts/sync-spec.ts` and
9
+ * hash-pinned by its `test/spec-drift.test.ts`, so the edit broke the
10
+ * recorded `body-sha256` and reddened their suite — and the next
11
+ * `sync-spec.ts` run would have discarded it regardless. The write was
12
+ * simultaneously destructive and futile.
13
+ *
14
+ * The file said so, in English, on line 12: `<!-- DERIVED FILE — do not edit
15
+ * here.` `--fix` edited it on line 355. **A consumer who does the right thing
16
+ * and labels a derived file got nothing for it**, because the label had no
17
+ * reader. That is the gap this module closes.
18
+ *
19
+ * ## Why a frontmatter key and not the English sentence
20
+ *
21
+ * Matching the prose is the cheapest wrong fix, and it is wrong in the
22
+ * direction nobody sees. The sentence has no spelling: `DERIVED FILE`,
23
+ * `Managed by X — do not edit`, `DO NOT EDIT`, the same words reflowed across
24
+ * a line break, the same words in another language. You cannot enumerate it,
25
+ * and every widening of the pattern buys a false positive — at which point
26
+ * `--fix` silently stops working on a spec somebody wrote by hand, which is
27
+ * the same class of silent failure in the other direction.
28
+ *
29
+ * rungate's own tree already holds both traps:
30
+ *
31
+ * - `specs/bootstrap-data-flow/consumer-requirements.md` carries
32
+ * `# Managed by rungate — do not edit.` **twice, inside fenced code
33
+ * blocks**, quoting generated CI as an illustration.
34
+ * - `specs/SPEC-TEMPLATE.md` carries `<!-- BEGIN GENERATED PATTERNS -->`,
35
+ * which delimits a *region* and says nothing about the file.
36
+ *
37
+ * A loose `do not edit` grep stops fixing both of those and reports nothing.
38
+ *
39
+ * ## Why not `generated-sha`, which already exists
40
+ *
41
+ * Because it means the opposite thing. `generated-sha` is **rungate's own**
42
+ * provenance stamp, and `decideRuleWrite` (`lib/rule-provenance.ts`) reads a
43
+ * stamp matching the body as permission to **overwrite** — `action: "update"`,
44
+ * *"harness-written and untouched since"*. Reusing that key here would make
45
+ * one key authorise a write in the rules path and forbid one in the spec
46
+ * path.
47
+ *
48
+ * The fact being declared is different: **a generator that is not rungate
49
+ * owns these bytes.** Foreign ownership, not harness provenance. So it gets
50
+ * its own key, and the key's value names the generator, because a refusal
51
+ * that cannot say where to make the edit instead is a refusal nobody can act
52
+ * on.
53
+ *
54
+ * ## The three readings
55
+ *
56
+ * | reading | `mayWrite` | because |
57
+ * |---|---|---|
58
+ * | `derived` | no | `generated-by:` is declared; permanent and unambiguous |
59
+ * | `unprotected` | no | only a prose marker; caught, but by a detector that is deliberately too narrow to rely on |
60
+ * | `authored` | yes | nothing claims a generator owns it |
61
+ *
62
+ * `unprotected` is the honest middle. The prose detector below is scoped hard
63
+ * — an HTML comment, in the document head, outside code fences — precisely so
64
+ * it cannot eat the two authored specs named above. A detector that narrow
65
+ * **will** miss some real derived file, so a file it does catch is reported
66
+ * as UNPROTECTED and told to declare the key: we held the write this time,
67
+ * and that is not a guarantee you should build on.
68
+ *
69
+ * Refusing is the safe direction either way. A derived file wrongly preserved
70
+ * costs a line in a report. A derived file wrongly written costs the
71
+ * consumer's suite, and the edit is thrown away at the next regeneration.
72
+ *
73
+ * ## No relative imports, on purpose
74
+ *
75
+ * `test/derived-spec-guard.test.ts` builds a mutant copy of this file in an
76
+ * `mkdtemp` directory and runs the real write path against it. A relative
77
+ * import here would make that mutant die on module resolution, and a mutant
78
+ * that failed to load is indistinguishable from a guard that held —
79
+ * `.claude/rules/checks-must-be-able-to-fail.md`.
80
+ */
81
+
82
+ /** The frontmatter key by which a file declares which generator produces it. */
83
+ export const DERIVED_KEY = "generated-by";
84
+
85
+ export type DerivedStatus = "authored" | "derived" | "unprotected";
86
+
87
+ export interface DerivedReading {
88
+ status: DerivedStatus;
89
+ /** What regenerates the file. Present exactly when `status` is `derived`. */
90
+ generator?: string;
91
+ /** The prose that was read. Present exactly when `status` is `unprotected`. */
92
+ evidence?: string;
93
+ }
94
+
95
+ const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
96
+
97
+ /**
98
+ * Phrases that declare a whole FILE produced, as opposed to a region of one.
99
+ *
100
+ * `generated file` and `generated by` are in; a bare `generated` is not —
101
+ * `<!-- BEGIN GENERATED PATTERNS -->` is a section delimiter and must not read
102
+ * as a declaration about the document.
103
+ */
104
+ const PROSE_DECLARATIONS = [
105
+ /\bdo\s+not\s+edit\b/i,
106
+ /\bdon'?t\s+edit\b/i,
107
+ /\bderived\s+file\b/i,
108
+ /\bgenerated\s+file\b/i,
109
+ /\bgenerated\s+by\b/i,
110
+ ];
111
+
112
+ /** Fenced blocks hold examples OF markers, never markers. */
113
+ function stripFences(text: string): string {
114
+ return text.replace(/^(```|~~~)[\s\S]*?^\1[^\n]*$/gm, "");
115
+ }
116
+
117
+ /**
118
+ * The part of the document a whole-file declaration can live in.
119
+ *
120
+ * Everything after the frontmatter, up to the first ATX heading or the first
121
+ * criterion line — whichever comes first. A marker below the first heading is
122
+ * talking about a section, which is the `SPEC-TEMPLATE.md` case.
123
+ *
124
+ * **Fences come out BEFORE the boundary is looked for, not after.** A fenced
125
+ * block quoting YAML, shell or Python holds lines beginning `# `, which is
126
+ * also an ATX heading — so searching the raw body ends the head inside the
127
+ * fence and a real marker below it is never read. That is a miss in the
128
+ * unsafe direction: the file reads as authored and `--fix` writes it.
129
+ *
130
+ * It also made the fenced-example case below pass for the wrong reason, which
131
+ * is the shape `.claude/rules/checks-must-be-able-to-fail.md` calls *green on
132
+ * the exit code, witnessing the wrong mechanism*: the fence was never
133
+ * stripped, the head simply stopped before it. Both cases in
134
+ * `test/derived-spec-guard.test.ts` now turn on this ordering.
135
+ */
136
+ function documentHead(content: string): string {
137
+ const body = stripFences(content.replace(FRONTMATTER, ""));
138
+ const lines = body.split("\n");
139
+ const end = lines.findIndex((l) => /^#{1,6}\s/.test(l) || /^\s*- \[[ xX]\]/.test(l));
140
+ return (end === -1 ? lines : lines.slice(0, end)).join("\n");
141
+ }
142
+
143
+ /** The first head HTML comment that declares the file produced, or null. */
144
+ function proseDerivedMarker(content: string): string | null {
145
+ const head = documentHead(content);
146
+ for (const [comment] of head.matchAll(/<!--[\s\S]*?-->/g)) {
147
+ if (PROSE_DECLARATIONS.some((re) => re.test(comment))) {
148
+ return comment.split("\n")[0].trim();
149
+ }
150
+ }
151
+ return null;
152
+ }
153
+
154
+ /** What the file claims about who produces it. */
155
+ export function readDerivedDeclaration(content: string): DerivedReading {
156
+ const fm = FRONTMATTER.exec(content);
157
+ if (fm) {
158
+ const declared = new RegExp(`^${DERIVED_KEY}:[ \\t]*(.*?)[ \\t]*$`, "m").exec(fm[1]);
159
+ if (declared) {
160
+ // A key present with no value still declares the file produced. It just
161
+ // cannot say by what, and the refusal says so rather than guessing.
162
+ const generator = declared[1].replace(/^["']|["']$/g, "").trim();
163
+ return { status: "derived", generator: generator || "(declared, unnamed)" };
164
+ }
165
+ }
166
+
167
+ const prose = proseDerivedMarker(content);
168
+ if (prose) return { status: "unprotected", evidence: prose };
169
+
170
+ return { status: "authored" };
171
+ }
172
+
173
+ /**
174
+ * THE decision. One site, one line, consulted by every rungate write path
175
+ * that edits a spec in place.
176
+ *
177
+ * Deliberately the only place the three readings turn into a yes or a no. A
178
+ * caller comparing `status` itself would be a second decider, which no
179
+ * mutation of this one could disable — the fourth shape in
180
+ * `.claude/rules/checks-must-be-able-to-fail.md`. `test/derived-spec-guard.test.ts`
181
+ * asserts the comparison below appears exactly once in this file, so the
182
+ * mutant it builds cannot be held up by a surviving copy.
183
+ */
184
+ export function mayWrite(reading: DerivedReading): boolean {
185
+ return reading.status === "authored";
186
+ }
187
+
188
+ /**
189
+ * Why a file was not written, in one line naming the file and the reason.
190
+ *
191
+ * A `--fix` that silently skips a file is the same defect as one that
192
+ * silently writes it, so there is no code path that refuses quietly.
193
+ */
194
+ export function skipLine(specFile: string, reading: DerivedReading): string {
195
+ if (reading.status === "derived") {
196
+ return (
197
+ `DERIVED: ${specFile} not written — frontmatter declares ` +
198
+ `\`${DERIVED_KEY}: ${reading.generator}\`. Edit the source and regenerate.`
199
+ );
200
+ }
201
+ return (
202
+ `UNPROTECTED: ${specFile} not written — read as derived from prose only ` +
203
+ `(${reading.evidence}). Prose is not a reliable declaration: add ` +
204
+ `\`${DERIVED_KEY}: <generator>\` to its frontmatter.`
205
+ );
206
+ }
@@ -0,0 +1,335 @@
1
+ /**
2
+ * Who is writing which files right now, DECLARED rather than detected (#1413).
3
+ *
4
+ * `.github/workflows/ai-review.yml` is generated from
5
+ * `lib/scaffold/ai-review-step.ts`, so every pull request that changes review
6
+ * behaviour touches both, and therefore conflicts with every other such pull
7
+ * request by construction. On 2026-10-23 #1370 went DIRTY five times in three
8
+ * hours, #1387 rebased four times, and a fourth agent declined to open a pull
9
+ * request at all. Every one of those conflicts had the same three-step
10
+ * resolution: take `origin/main`'s copy, re-run the generator, confirm the
11
+ * second `--fix` pass reports unchanged. A conflict whose resolution is always
12
+ * identical is not a conflict. It is a missing lock.
13
+ *
14
+ * ## Why this is a declaration and not a detector
15
+ *
16
+ * Measured on this machine before any of it was written, and both results
17
+ * killed the obvious implementation:
18
+ *
19
+ * - `find -newermt '-6 hours'` silently matches nothing here. It returned
20
+ * empty against a file modified four seconds earlier. `-newer <ref>` works.
21
+ * - Even working, mtime cannot separate an edit from a checkout. `git
22
+ * worktree add` bumps every mtime, so a sweep returned 36,939 "recently
23
+ * edited" files and roughly 30 worktrees "touching" one script. Across 233
24
+ * worktrees there is no reading that answers who is editing a file now.
25
+ *
26
+ * And the instruments that *are* accurate — `gh pr list`,
27
+ * `closingIssuesReferences`, the tracker — all describe PUSHED state, while
28
+ * the dangerous window is the one before a push. So the signal has to be
29
+ * something a writer WRITES. The gap this closes is that declaring was
30
+ * voluntary and unrecorded, not that it was impossible.
31
+ *
32
+ * ## What this does not cover, stated rather than implied
33
+ *
34
+ * A path with no claim reads as free, and that is a true statement about the
35
+ * registry, not about the disk. This refuses to guess: an undeclared writer is
36
+ * invisible here exactly as it is invisible to `gh pr list`. What it buys is
37
+ * that a writer who declares can be seen by everyone before they branch, with
38
+ * one command, and that the registry is a serialisation point — two agents
39
+ * claiming at once conflict on a JSON array, which is a conflict a person may
40
+ * resolve, unlike the generated YAML this exists to protect.
41
+ *
42
+ * ## Liveness is resolved, never trusted
43
+ *
44
+ * `specs/sc-reservations.json` asks owners to delete their entry when the
45
+ * branch merges, and `.claude/rules/parallel-sessions.md` records that a block
46
+ * nobody prunes is headroom nobody can use. A stale claim is worse than that
47
+ * here: it reports a live writer forever and the next agent routes around a
48
+ * file nobody holds. So {@link liveClaims} takes the set of branches that
49
+ * still exist and are not merged, and a claim whose owner is not among them is
50
+ * DEAD regardless of what the file says.
51
+ */
52
+
53
+ import { underPrefix } from "./repo-path.ts";
54
+
55
+ /** The key that tells a store apart from an empty object. See {@link readFileClaims}. */
56
+ export const FILE_CLAIMS_CONTROL_KEY = "claims";
57
+
58
+ /** Repository-relative path of the registry. */
59
+ export const FILE_CLAIMS_PATH = "specs/file-claims.json";
60
+
61
+ /** One declared writer. */
62
+ export interface FileClaim {
63
+ /** The branch doing the writing. The thing another session looks you up by. */
64
+ owner: string;
65
+ /**
66
+ * Repository-relative paths this branch is writing. A directory claims
67
+ * everything beneath it; a file claims only itself.
68
+ */
69
+ paths: string[];
70
+ /** The issue the work is for, so a reader can go and read why. */
71
+ issue?: number;
72
+ /** Anything the next agent needs that the issue does not say. */
73
+ note?: string;
74
+ }
75
+
76
+ export type FileClaimStatus = "read" | "absent" | "unreadable";
77
+
78
+ export interface FileClaimReading {
79
+ status: FileClaimStatus;
80
+ /** Where the reading was taken from, whether or not anything was there. */
81
+ path: string;
82
+ /** Empty under every status except a `read` of a store that declares claims. */
83
+ claims: FileClaim[];
84
+ /** Why it is absent or unreadable. Absent on a clean read. */
85
+ reason?: string;
86
+ }
87
+
88
+ /**
89
+ * Validate one entry, returning why it is unusable or `null`.
90
+ *
91
+ * Every fault refuses the WHOLE store rather than dropping the entry. A
92
+ * registry the reader only partly understands is unreadable, not partly read
93
+ * — the same rule `lib/sc-reservations.ts` applies to an unknown namespace,
94
+ * and for the same reason: a claim silently dropped is a lock silently
95
+ * released, which is the one failure this file must not have.
96
+ */
97
+ function claimFault(raw: unknown, index: number): string | null {
98
+ const at = `${FILE_CLAIMS_CONTROL_KEY}[${index}]`;
99
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return `${at} is not an object`;
100
+ const c = raw as Record<string, unknown>;
101
+ if (typeof c.owner !== "string" || c.owner.trim() === "") return `${at} has no owner`;
102
+ const who = c.owner as string;
103
+ if (!Array.isArray(c.paths) || c.paths.length === 0) {
104
+ return `${at} (${who}) claims no paths`;
105
+ }
106
+ for (const [i, p] of (c.paths as unknown[]).entries()) {
107
+ if (typeof p !== "string" || p.trim() === "") return `${at} (${who}) paths[${i}] is not a path`;
108
+ // Repository-relative and nothing else. An absolute path is a claim about
109
+ // one machine, and `..` is a claim about a tree this registry does not
110
+ // describe — both read as a path that no caller's `git diff --name-only`
111
+ // will ever produce, so they would silently never match.
112
+ if (p.startsWith("/")) return `${at} (${who}) paths[${i}] is absolute: ${p}`;
113
+ if (p.split("/").includes("..")) return `${at} (${who}) paths[${i}] escapes the repository: ${p}`;
114
+ }
115
+ if (c.issue !== undefined && (typeof c.issue !== "number" || !Number.isSafeInteger(c.issue))) {
116
+ return `${at} (${who}) has a non-integer issue`;
117
+ }
118
+ if (c.note !== undefined && typeof c.note !== "string") return `${at} (${who}) has a non-string note`;
119
+ return null;
120
+ }
121
+
122
+ /**
123
+ * Read the registry from the bytes of the file.
124
+ *
125
+ * Three outcomes, and the caller must not collapse them:
126
+ *
127
+ * - `absent` — `raw` is `null`, nobody has declared anything. A real reading.
128
+ * - `unreadable` — present and not understood. NOT an empty reading: a
129
+ * registry that fails to parse would otherwise report every file free,
130
+ * which is the fail-open this whole mechanism exists to prevent.
131
+ * - `read` — understood, `claims` is what it declares.
132
+ *
133
+ * `{}` and `{"claims": []}` are different facts and the control key is what
134
+ * separates them. The first is a file that has lost its contents; the second
135
+ * is a registry saying, deliberately, that nobody holds anything.
136
+ */
137
+ export function readFileClaims(raw: string | null, path = FILE_CLAIMS_PATH): FileClaimReading {
138
+ if (raw === null) {
139
+ return { status: "absent", path, claims: [], reason: "no registry at this path" };
140
+ }
141
+ let parsed: unknown;
142
+ try {
143
+ parsed = JSON.parse(raw);
144
+ } catch (e) {
145
+ const why = (e instanceof Error ? e.message : String(e)).split("\n")[0];
146
+ return { status: "unreadable", path, claims: [], reason: `not JSON (${why})` };
147
+ }
148
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
149
+ return { status: "unreadable", path, claims: [], reason: "the store is not an object" };
150
+ }
151
+ const store = parsed as Record<string, unknown>;
152
+ if (!(FILE_CLAIMS_CONTROL_KEY in store)) {
153
+ return {
154
+ status: "unreadable",
155
+ path,
156
+ claims: [],
157
+ reason: `the store declares no \`${FILE_CLAIMS_CONTROL_KEY}\` key, so it cannot be told from a file that lost its contents`,
158
+ };
159
+ }
160
+ const list = store[FILE_CLAIMS_CONTROL_KEY];
161
+ if (!Array.isArray(list)) {
162
+ return { status: "unreadable", path, claims: [], reason: `\`${FILE_CLAIMS_CONTROL_KEY}\` is not an array` };
163
+ }
164
+ for (const [i, entry] of list.entries()) {
165
+ const fault = claimFault(entry, i);
166
+ if (fault !== null) return { status: "unreadable", path, claims: [], reason: fault };
167
+ }
168
+ return { status: "read", path, claims: list as FileClaim[] };
169
+ }
170
+
171
+ /**
172
+ * Does `claimed` cover `path`? A directory covers everything beneath it.
173
+ *
174
+ * This is `underPrefix` and nothing else. It used to be four lines of
175
+ * `startsWith` here, which was a SECOND DECIDER for a question
176
+ * `lib/repo-path.ts` already answers —
177
+ * `.claude/rules/checks-must-be-able-to-fail.md`, *two deciders* — and the
178
+ * two disagreed on exactly the inputs a caller produces by accident. The
179
+ * registry side was never the gap: `claimFault` already rejects absolute and
180
+ * `..` paths. It was the CALLER-supplied path, which nothing normalised, and
181
+ * `./lib/x.ts` is what tab-completion hands you.
182
+ *
183
+ * Measured against the local copy before the swap, for the claim `lib`:
184
+ *
185
+ * | path | the old local rule | `underPrefix` |
186
+ * |---|---|---|
187
+ * | `./lib/x.ts` | false | **true** |
188
+ * | `Lib/x.ts` | false | **true** |
189
+ * | `lib\x.ts` | false | **true** |
190
+ * | `library/x.ts` | false | false |
191
+ * | `../lib/x.ts` | false | false |
192
+ *
193
+ * Three contended paths reading FREE, and the last two rows are why the fix
194
+ * is a swap rather than a patch: the centralised rule is segment-aware and
195
+ * refuses a `..` escape, so it is stricter where it matters and looser only
196
+ * where the old rule was wrong. Every fixture anyone would naturally write
197
+ * passes under both, which is why the suite was green (#1436 review).
198
+ */
199
+ export function claimCovers(claimed: string, path: string): boolean {
200
+ return underPrefix(path, claimed);
201
+ }
202
+
203
+ /** What a declared owner's branch is doing. Three states, never two. */
204
+ export type OwnerState = "live" | "landed" | "unmeasured";
205
+
206
+ /** The one field of a pull request this decision reads. `gh`'s spelling. */
207
+ export interface PullState {
208
+ number: number;
209
+ /** `OPEN`, `CLOSED` or `MERGED`. A draft pull request is `OPEN`. */
210
+ state: string;
211
+ }
212
+
213
+ /**
214
+ * Is this owner still working, judged by its pull requests?
215
+ *
216
+ * ## Two git-only rules were tried first, and both were wrong
217
+ *
218
+ * **Ancestry.** `git merge-base --is-ancestor` and `git branch -r
219
+ * --no-merged` compare commits, and this repository squash-merges: the squash
220
+ * commit is a new object, so a merged branch's tip is never an ancestor of
221
+ * the base and both report it UNMERGED forever. Measured —
222
+ * `rg/1168-eviction-note` merged at 17:43 on 2026-10-23 and `--no-merged`
223
+ * still listed it afterwards.
224
+ *
225
+ * **Subjects.** The replacement asked whether every subject the branch
226
+ * carries ahead of the base also appears among the base's subjects. That is
227
+ * true for a SINGLE-commit pull request, whose squash subject is the commit
228
+ * subject with ` (#N)` appended — and false for every other one. GitHub's
229
+ * squash subject for a multi-commit branch is the PULL REQUEST TITLE; the
230
+ * individual commit subjects go into the squash BODY as `* ` bullets, where
231
+ * `git log --format=%s` cannot see them. Measured against the 15 most
232
+ * recently merged pull requests with surviving refs: **11 of 12 answered
233
+ * `landed=false`**, every one of them merged. Only the one single-commit row
234
+ * was right, and the battery that passed this rule in review had sampled
235
+ * nothing but single-commit branches — it could not have discriminated.
236
+ *
237
+ * Both failures point the same way, and it is the fail-open direction for a
238
+ * lock: a merged branch that reads LIVE holds its files forever.
239
+ * `RUNGATE_BRANCH_CLEANUP` is deliberately unset here, so merged refs are
240
+ * never deleted and nothing else would ever clear the entry. A lock nobody
241
+ * can acquire is worse than no lock, because people route around it.
242
+ *
243
+ * ## So ask the tracker, which is told rather than inferred
244
+ *
245
+ * A pull request's state is a fact somebody recorded, not a shape guessed out
246
+ * of a commit graph that squashing has already destroyed. It is also the same
247
+ * place this project keeps every other claim about who is doing what.
248
+ *
249
+ * The cases, each reachable and each separately witnessed:
250
+ *
251
+ * - `pulls === null` — the tracker could not be read. UNMEASURED. This does
252
+ * not fall through to landed; an unread tracker is not an empty one.
253
+ * - any pull is `OPEN` — LIVE. Draft counts: a draft is someone working.
254
+ * - pulls exist and none is open — LANDED, merged or abandoned alike. Both
255
+ * mean nobody is writing those files under this name any more.
256
+ * - no pull at all, but the ref is on the remote — LIVE. A pushed branch with
257
+ * no pull request yet is the EARLIEST moment a claim matters, and it is
258
+ * exactly when a second agent is deciding whether to start.
259
+ * - no pull and no ref, refs refreshed — LANDED. There is nothing there.
260
+ * - no pull and no ref, refs NOT refreshed — UNMEASURED. A branch nobody
261
+ * fetched and a branch somebody deleted look identical, and only one of
262
+ * them is safe to call free.
263
+ */
264
+ export function ownerState(
265
+ pulls: readonly PullState[] | null,
266
+ refExists: boolean,
267
+ refsRefreshed: boolean,
268
+ ): { state: OwnerState; why: string } {
269
+ if (pulls === null) {
270
+ return { state: "unmeasured", why: "the tracker could not be read for this branch" };
271
+ }
272
+ const open = pulls.filter(p => p.state.toUpperCase() === "OPEN");
273
+ if (open.length > 0) {
274
+ return { state: "live", why: `open pull request ${open.map(p => `#${p.number}`).join(", ")}` };
275
+ }
276
+ if (pulls.length > 0) {
277
+ return {
278
+ state: "landed",
279
+ why: `no open pull request (${pulls.map(p => `#${p.number} ${p.state.toLowerCase()}`).join(", ")})`,
280
+ };
281
+ }
282
+ if (refExists) {
283
+ return { state: "live", why: "branch is on the remote with no pull request yet" };
284
+ }
285
+ if (refsRefreshed) {
286
+ return { state: "landed", why: "no pull request and no branch on the remote" };
287
+ }
288
+ return {
289
+ state: "unmeasured",
290
+ why: "no pull request, and the refs were not refreshed, so \"deleted\" and \"never fetched\" cannot be told apart",
291
+ };
292
+ }
293
+
294
+ /**
295
+ * The claims that cover `path`, among those whose owner is still live.
296
+ *
297
+ * `liveOwners` is the set of branches that exist and are unmerged, supplied by
298
+ * the caller because resolving it is a git operation and this module decides
299
+ * nothing from the filesystem. A claim whose owner is absent from that set is
300
+ * DEAD — the branch merged or went away and nobody pruned the entry — and a
301
+ * dead claim must not hold a file, or the registry becomes a list of places
302
+ * nobody may ever work again.
303
+ */
304
+ export function liveClaims(
305
+ claims: readonly FileClaim[],
306
+ path: string,
307
+ liveOwners: ReadonlySet<string>,
308
+ ): FileClaim[] {
309
+ return claims.filter(c => liveOwners.has(c.owner) && c.paths.some(p => claimCovers(p, path)));
310
+ }
311
+
312
+ /** Every claim on `path`, live or not, so a report can say which is which. */
313
+ export function allClaims(claims: readonly FileClaim[], path: string): FileClaim[] {
314
+ return claims.filter(c => c.paths.some(p => claimCovers(p, path)));
315
+ }
316
+
317
+ /**
318
+ * The claims a set of paths runs into, keyed by path.
319
+ *
320
+ * Entries with no live claim are omitted rather than mapped to `[]`: the
321
+ * caller's question is "what is contended", and an empty map is the answer
322
+ * "nothing", which is different from "I checked nothing".
323
+ */
324
+ export function contention(
325
+ claims: readonly FileClaim[],
326
+ paths: readonly string[],
327
+ liveOwners: ReadonlySet<string>,
328
+ ): Map<string, FileClaim[]> {
329
+ const out = new Map<string, FileClaim[]>();
330
+ for (const p of paths) {
331
+ const hits = liveClaims(claims, p, liveOwners);
332
+ if (hits.length > 0) out.set(p, hits);
333
+ }
334
+ return out;
335
+ }