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.
- package/bin/rungate.ts +11 -6
- package/config/prove-evidence.schema.json +21 -3
- package/gates/.gate-salt +1 -1
- package/gates/gate-executor.ts +153 -1
- package/gates/prove.test.ts +12 -6
- package/gates/schema.ts +69 -6
- package/gates/workflow.test.ts +12 -5
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/VerifyPhaseLock.hook.ts +25 -8
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +791 -4
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-write-guard.ts +1235 -102
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +12 -0
- package/lib/create-sc.ts +45 -12
- package/lib/derived-spec.ts +206 -0
- package/lib/file-claims.ts +335 -0
- package/lib/finding-arbiter.ts +502 -28
- package/lib/finding-jury.ts +48 -1
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +259 -0
- package/lib/generators/agents-md.ts +29 -0
- package/lib/github.ts +112 -7
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +53 -3
- package/lib/issue-filing-gate.ts +1073 -76
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +10 -0
- package/lib/project-state-shape.ts +56 -5
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +65 -3
- package/lib/risk-tier.ts +302 -0
- package/lib/rounds-to-pass.ts +274 -0
- package/lib/rule-row-drift.ts +199 -0
- package/lib/sc-claim-forms.ts +33 -5
- package/lib/sc-guard.ts +11 -1
- package/lib/sc-id-cross-tree.ts +17 -2
- package/lib/sc-ids.ts +71 -6
- package/lib/sc-reservations.ts +158 -14
- package/lib/scaffold/ai-review-findings.ts +1157 -18
- package/lib/scaffold/ai-review-step.ts +3798 -76
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +83 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +16 -0
- package/lib/validators/spec-validators.ts +28 -2
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +330 -12
- package/scripts/audit-specs.ts +225 -23
- package/scripts/create-sc.ts +11 -0
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +12 -0
- 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
|
+
}
|