rungate 0.8.13 → 0.8.16

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 (88) hide show
  1. package/README.md +182 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/HarnessAFKGate.hook.ts +5 -1
  4. package/hooks/HookCurrency.hook.ts +11 -8
  5. package/hooks/MergeGuard.hook.ts +7 -1
  6. package/hooks/StaleTTLCleanup.hook.ts +4 -4
  7. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  8. package/hooks/lib/findWorkflow.ts +3 -2
  9. package/hooks/lib/paths.ts +14 -2
  10. package/hooks/lib/utils.ts +23 -3
  11. package/lib/active-milestone.ts +50 -0
  12. package/lib/ai-review-rounds.ts +99 -0
  13. package/lib/ai-review-suppression.ts +200 -21
  14. package/lib/bash-write-guard.ts +397 -23
  15. package/lib/board-flow.ts +280 -0
  16. package/lib/board-lane-health.ts +578 -0
  17. package/lib/board-mirror.ts +136 -39
  18. package/lib/board-ready-fanout.ts +297 -14
  19. package/lib/board-ready-rule.ts +1211 -0
  20. package/lib/board-throughput.ts +136 -0
  21. package/lib/board-walkthrough.ts +240 -0
  22. package/lib/body-evidence.ts +203 -0
  23. package/lib/branch-protection.ts +399 -9
  24. package/lib/bun-version.ts +36 -0
  25. package/lib/cli-commands.ts +75 -4
  26. package/lib/closing-reference-audit.ts +307 -6
  27. package/lib/config-loader.ts +254 -25
  28. package/lib/config-readers.ts +170 -10
  29. package/lib/config-trackable.ts +96 -57
  30. package/lib/conformity.ts +121 -7
  31. package/lib/create-sc.ts +25 -2
  32. package/lib/derived-spec.ts +21 -9
  33. package/lib/filing-compliance.ts +367 -0
  34. package/lib/filing-plan.ts +47 -21
  35. package/lib/finding-arbiter.ts +79 -5
  36. package/lib/finding-jury.ts +43 -4
  37. package/lib/finding-promotion.ts +1123 -0
  38. package/lib/generators/agents-md.ts +149 -0
  39. package/lib/git-isolation.ts +137 -1
  40. package/lib/github-api-base.ts +66 -0
  41. package/lib/github.ts +194 -9
  42. package/lib/graphql-cursor.ts +80 -0
  43. package/lib/hook-scopes.ts +78 -0
  44. package/lib/issue-create-override.ts +415 -3
  45. package/lib/issue-decomposition.ts +124 -7
  46. package/lib/issue-extraction.ts +9 -7
  47. package/lib/issue-file-overlap.ts +373 -0
  48. package/lib/issue-filing-gate.ts +1109 -52
  49. package/lib/issue-repair.ts +90 -9
  50. package/lib/issue-shape.ts +199 -0
  51. package/lib/live-issues.ts +31 -2
  52. package/lib/local-work.ts +423 -0
  53. package/lib/markdown-fence.ts +134 -0
  54. package/lib/milestone-title.ts +46 -0
  55. package/lib/scaffold/ai-review-findings.ts +148 -3
  56. package/lib/scaffold/ai-review-step.ts +65 -5
  57. package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
  58. package/lib/scaffold/steps.ts +115 -9
  59. package/lib/source-census.ts +108 -0
  60. package/lib/spec-deps.ts +55 -11
  61. package/lib/spec-placement.ts +203 -13
  62. package/lib/spec-registry.ts +75 -16
  63. package/lib/spec-source.ts +609 -0
  64. package/lib/spec-write-sweep.ts +4 -0
  65. package/lib/stage-ladder.ts +896 -3
  66. package/lib/state-claim-readings.ts +252 -0
  67. package/lib/success-doc.ts +7 -6
  68. package/lib/test-command-positions.ts +135 -1
  69. package/lib/work-status.ts +551 -0
  70. package/lib/worktree-repo.ts +14 -2
  71. package/package.json +7 -1
  72. package/scripts/ai-review-findings.ts +8 -13
  73. package/scripts/ai-review-threads.ts +16 -17
  74. package/scripts/audit-closing-references.ts +330 -0
  75. package/scripts/audit-specs.ts +59 -103
  76. package/scripts/board-conformance.ts +747 -40
  77. package/scripts/board-mirror.ts +594 -13
  78. package/scripts/board-ready.ts +979 -0
  79. package/scripts/board-snapshot.ts +464 -12
  80. package/scripts/claim-files.ts +578 -0
  81. package/scripts/criterion-inventory.ts +526 -50
  82. package/scripts/finding-promotion.ts +547 -0
  83. package/scripts/generate-code-map.ts +1 -1
  84. package/scripts/plan-issues.ts +279 -40
  85. package/scripts/plan-spec.ts +105 -3
  86. package/scripts/sync-sc-status.ts +147 -7
  87. package/scripts/worktree-census.ts +958 -0
  88. package/scripts/worktree-sweep.ts +269 -0
@@ -0,0 +1,367 @@
1
+ /**
2
+ * Did a refused filing become the comment the refusal told it to be?
3
+ *
4
+ * ## The question, and why nothing answered it before
5
+ *
6
+ * `lib/issue-filing-gate.ts` refuses a filing and routes it to a comment. It
7
+ * does not WRITE the comment — it returns a refusal naming where one should
8
+ * go, and the finding survives only if the agent then writes it. So the gate
9
+ * can be working perfectly while findings are being deleted, and the ledger
10
+ * records the refusal either way. **Compliance with a refusal is the one
11
+ * thing nothing in this tree records.**
12
+ *
13
+ * It matters more than it sounds. The measure the cap was shipped against is
14
+ * issues opened per day, and that number falls **identically** whether the
15
+ * agent writes the comment or drops the finding on the floor. A metric that
16
+ * reads the same on the good outcome and the bad one is not measuring the
17
+ * thing anybody wants.
18
+ *
19
+ * ## A rate of zero and a denominator of zero are different readings
20
+ *
21
+ * This module exists in a world where the honest answer is *nobody has been
22
+ * refused yet*: measured 2026-10-25, the production ledger holds 261 rows
23
+ * and **zero** `OVER_CAP` and **zero** `COMMENT_INSTEAD`. So `rate` is
24
+ * `number | null` and is `null` whenever `observable === 0`. Not `0`, and
25
+ * not a thrown error — `0` is the reading that says agents ignore refusals,
26
+ * which is a serious claim to make about a population that does not exist.
27
+ *
28
+ * `unobservableByRefusal` is beside it so the gap is attributable: a reader
29
+ * learns *which* refusals could not be followed up, which is what decides
30
+ * whether the fix is to persist a field or to wait for traffic.
31
+ *
32
+ * ## Why it is an UPPER BOUND and says so in the field name
33
+ *
34
+ * The ledger does not record WHO attempted the filing. So a comment landing
35
+ * on the target inside the window cannot be attributed to the agent that was
36
+ * refused; it may be anyone's, including a human answering something else.
37
+ * Counting it as compliance can only ever overstate.
38
+ *
39
+ * That is still worth having, because the bound is informative in one
40
+ * direction: an upper bound of zero is decisive, and that is the reading we
41
+ * expect to be arguing about. `compliedUpperBound` is named rather than
42
+ * called `complied` so a later reader cannot quote it as a compliance rate.
43
+ *
44
+ * ## A comment is a TIMELINE EVENT. An issue-body edit is not.
45
+ *
46
+ * Measured on this tracker, 2026-10-25: #1592 carries four `commented`
47
+ * timeline events, while #1476 — edited twice on 10-24, at `00:29:52Z` and
48
+ * `01:32:24Z` — carries **no timeline event for either edit**. The edits
49
+ * exist only under GraphQL `userContentEdits`, which nothing subscribes to.
50
+ *
51
+ * So an answer appended to an issue BODY notifies nobody and is not
52
+ * compliance in any sense a human experiences. `ghIssueComments` reads the
53
+ * comments endpoint and never the body, and a `CommentReading` carries only
54
+ * comment timestamps, so no caller of this module can accidentally count a
55
+ * body edit.
56
+ *
57
+ * ## The target is only recoverable for one refusal class today
58
+ *
59
+ * The refusal MESSAGE names a comment target, computed at refusal time. The
60
+ * ledger ROW does not persist it. The one exception is `DUPLICATE`, whose
61
+ * `duplicateOf` holds the issues the finding collided with — so those rows
62
+ * carry their own target and are the only historical population this can
63
+ * read. Everything else is `UNOBSERVABLE`, by name, with the refusal in the
64
+ * reason. Persisting the target on the row is the change that would widen
65
+ * the denominator; that is a decision for whoever reads this output, and it
66
+ * is deliberately not made here.
67
+ */
68
+
69
+ import { createGitHubClient, listIssueComments, type GitHubClient } from "./github";
70
+ import type { ArbiterRefusal } from "./finding-arbiter";
71
+
72
+ /**
73
+ * The fields of a ledger row this reading needs.
74
+ *
75
+ * Deliberately a structural subset of `FilingLedgerRow` rather than an
76
+ * import of it: rows are read back from JSONL written by two different
77
+ * writers over two days, and several of them predate fields the current
78
+ * interface declares. A reader that required the full shape would refuse
79
+ * the population it exists to measure.
80
+ */
81
+ export interface FilingComplianceRow {
82
+ at: string;
83
+ title: string;
84
+ refusal: string | null;
85
+ emitted: boolean;
86
+ /**
87
+ * **Written as STRINGS by the live writer**, and typed to say so.
88
+ *
89
+ * Measured on the production ledger 2026-10-25: all 14 elements across 261
90
+ * rows are decimal strings — `["1214"]` — and the first version of this
91
+ * module accepted only `number`, so it discarded every target it had and
92
+ * reported a denominator of zero for the entire file. That is the failure
93
+ * this module is otherwise built to refuse, arriving through the parser
94
+ * instead of through the data: an empty population and a population the
95
+ * reader could not see are the same output.
96
+ */
97
+ duplicateOf?: readonly (number | string)[];
98
+ }
99
+
100
+ /** Where a refused finding was told to go, or why that cannot be read. */
101
+ export type ComplianceTarget =
102
+ | { reading: "NAMED"; issues: number[] }
103
+ | { reading: "UNOBSERVABLE"; why: string };
104
+
105
+ /**
106
+ * The comments on one target, or the sentence saying why none were read.
107
+ *
108
+ * **An `UNMEASURED` lookup must never render as "no comment".** They are the
109
+ * two readings this whole module exists to keep apart, and a lookup that
110
+ * returned `[]` on an HTTP error would collapse them at the one place a
111
+ * caller cannot see.
112
+ */
113
+ export type CommentReading =
114
+ | { reading: "MEASURED"; comments: readonly { at: string }[] }
115
+ | { reading: "UNMEASURED"; why: string };
116
+
117
+ export type CommentLookup = (issue: number) => Promise<CommentReading>;
118
+
119
+ export type RowReading =
120
+ | { state: "COMPLIED"; title: string; target: number; at: string }
121
+ | { state: "NOT_OBSERVED"; title: string; targets: number[] }
122
+ | { state: "UNOBSERVABLE"; title: string; why: string };
123
+
124
+ export interface ComplianceReading {
125
+ rows: RowReading[];
126
+ /** Rows on which compliance could be read at all. The denominator. */
127
+ observable: number;
128
+ /** Rows with no recoverable target, or whose lookup failed. */
129
+ unobservable: number;
130
+ /** See the header: an upper bound, because comments are unattributed. */
131
+ compliedUpperBound: number;
132
+ /** `null` when `observable === 0`. Never `0` for an empty population. */
133
+ rate: number | null;
134
+ /** Which refusals could not be followed up, and how many of each. */
135
+ unobservableByRefusal: Record<string, number>;
136
+ }
137
+
138
+ /** A row that was never refused has nothing to comply with. */
139
+ const NOT_REFUSED = "NOT_REFUSED";
140
+
141
+ /**
142
+ * A row that WAS refused and whose refusal the ledger did not label. Distinct
143
+ * from `NOT_REFUSED`, which means the row was emitted and has nothing to
144
+ * comply with. Both are "no refusal string"; only one of them is a gap.
145
+ */
146
+ const REFUSED_UNLABELLED = "REFUSED_UNLABELLED";
147
+
148
+ /**
149
+ * The one refusal whose row persists its own comment target.
150
+ *
151
+ * One binding, so the rule the header states and the rule the code applies
152
+ * are the same string, and a mutation of it moves the behaviour.
153
+ * `issue-filing-gate.ts` writes this literal on the dedupe refusal.
154
+ */
155
+ const DUPLICATE: ArbiterRefusal = "DUPLICATE";
156
+
157
+ /**
158
+ * One `duplicateOf` element as an issue number, or `null`.
159
+ *
160
+ * One binding, so there is one thing to mutate and one place that decides
161
+ * what counts as a target. A value that names no issue returns `null` and
162
+ * the row goes UNOBSERVABLE — never `NaN`, which would be carried into a
163
+ * lookup and come back as an error that reads like a tracker fault.
164
+ */
165
+ function issueNumber(value: unknown): number | null {
166
+ if (typeof value === "number") return Number.isInteger(value) && value > 0 ? value : null;
167
+ if (typeof value !== "string") return null;
168
+ const digits = value.trim().replace(/^#/, "");
169
+ if (!/^[0-9]+$/.test(digits)) return null;
170
+ const n = Number(digits);
171
+ return Number.isInteger(n) && n > 0 ? n : null;
172
+ }
173
+
174
+ export function targetOf(row: FilingComplianceRow): ComplianceTarget {
175
+ if (row.emitted) {
176
+ return {
177
+ reading: "UNOBSERVABLE",
178
+ why: "this filing was not refused — it reached the tracker, so there is no comment to look for",
179
+ };
180
+ }
181
+ // **`duplicateOf` is only this row's target when the row's OWN refusal is
182
+ // `DUPLICATE`.** Review raised this twice before it was fixed, and it is
183
+ // the module's header contradicting its own code: the header says the one
184
+ // exception is `DUPLICATE`, whose `duplicateOf` holds the issues the
185
+ // finding collided with, and the code read the field on any unemitted row.
186
+ //
187
+ // `issue-filing-gate.ts` can reach a refusal other than `DUPLICATE` on a
188
+ // finding that already collided — the dedupe stage computes collisions
189
+ // before the later stages run — so a `TOO_MANY_FILES` row can carry a
190
+ // populated `duplicateOf`. Reading it measures whether somebody commented
191
+ // on an unrelated issue, and counts the answer as compliance with a
192
+ // refusal that named a different target entirely. It is the quiet
193
+ // direction: the denominator looks healthier and the rate is wrong.
194
+ if (row.refusal === DUPLICATE) {
195
+ const issues = (row.duplicateOf ?? [])
196
+ .map(issueNumber)
197
+ .filter((n): n is number => n !== null);
198
+ if (issues.length > 0) return { reading: "NAMED", issues: [...issues] };
199
+ }
200
+ return {
201
+ reading: "UNOBSERVABLE",
202
+ why:
203
+ `the ledger records no comment target for a ${row.refusal ?? REFUSED_UNLABELLED} refusal. ` +
204
+ "The refusal message named one, computed at refusal time; the row does not persist it",
205
+ };
206
+ }
207
+
208
+ /**
209
+ * Was there a comment on this target inside the window?
210
+ *
211
+ * The window is closed at both ends on purpose. A comment written BEFORE the
212
+ * refusal cannot be an answer to it — that is the reading that would turn
213
+ * every duplicate-of-a-busy-issue into compliance — and one written after the
214
+ * window is not evidence about this refusal either.
215
+ */
216
+ function commentInWindow(
217
+ reading: CommentReading,
218
+ fromMs: number,
219
+ windowMs: number,
220
+ ): string | null {
221
+ if (reading.reading !== "MEASURED") return null;
222
+ for (const c of reading.comments) {
223
+ const at = Date.parse(c.at);
224
+ if (Number.isNaN(at)) continue;
225
+ if (at >= fromMs && at <= fromMs + windowMs) return c.at;
226
+ }
227
+ return null;
228
+ }
229
+
230
+ export async function complianceReading(input: {
231
+ rows: readonly FilingComplianceRow[];
232
+ lookup: CommentLookup;
233
+ windowMs: number;
234
+ }): Promise<ComplianceReading> {
235
+ const rows: RowReading[] = [];
236
+ const unobservableByRefusal: Record<string, number> = {};
237
+
238
+ const countUnobservable = (row: FilingComplianceRow) => {
239
+ // TWO POPULATIONS, NOT ONE. This was
240
+ // `row.emitted ? NOT_REFUSED : (row.refusal ?? NOT_REFUSED)`, so a row
241
+ // that WAS refused but carries `refusal: null` — which the type allows
242
+ // and `targetOf`'s own UNOBSERVABLE message anticipates — landed in the
243
+ // same bucket as a row that was emitted and had nothing to comply with.
244
+ //
245
+ // This field exists to ATTRIBUTE the gap, and those two rows are the
246
+ // opposite ends of it: one needed no follow-up, the other needed one and
247
+ // the ledger cannot say what kind. Collapsing them is the one attribution
248
+ // this reading must never make, so the unlabelled refusal gets its own
249
+ // bucket rather than a default (`.claude/rules/config-access.md`, Silent
250
+ // Default Substitution).
251
+ const key = row.emitted ? NOT_REFUSED : (row.refusal ?? REFUSED_UNLABELLED);
252
+ unobservableByRefusal[key] = (unobservableByRefusal[key] ?? 0) + 1;
253
+ };
254
+
255
+ for (const row of input.rows) {
256
+ const target = targetOf(row);
257
+ if (target.reading === "UNOBSERVABLE") {
258
+ rows.push({ state: "UNOBSERVABLE", title: row.title, why: target.why });
259
+ countUnobservable(row);
260
+ continue;
261
+ }
262
+
263
+ const from = Date.parse(row.at);
264
+ if (Number.isNaN(from)) {
265
+ rows.push({
266
+ state: "UNOBSERVABLE",
267
+ title: row.title,
268
+ why: `the row's timestamp \`${row.at}\` could not be read, so no window could be opened`,
269
+ });
270
+ countUnobservable(row);
271
+ continue;
272
+ }
273
+
274
+ // A single COMPLIED is decisive, so an unreadable sibling target does not
275
+ // demote it. The reverse is not true: NOT_OBSERVED over a target we could
276
+ // not read is the conflation this module exists to refuse.
277
+ let complied: { target: number; at: string } | null = null;
278
+ let unreadable: string | null = null;
279
+ for (const issue of target.issues) {
280
+ const reading = await input.lookup(issue);
281
+ if (reading.reading === "UNMEASURED") {
282
+ unreadable ??= `#${issue} could not be read: ${reading.why}`;
283
+ continue;
284
+ }
285
+ const at = commentInWindow(reading, from, input.windowMs);
286
+ if (at !== null) {
287
+ complied = { target: issue, at };
288
+ break;
289
+ }
290
+ }
291
+
292
+ if (complied !== null) {
293
+ rows.push({
294
+ state: "COMPLIED",
295
+ title: row.title,
296
+ target: complied.target,
297
+ at: complied.at,
298
+ });
299
+ continue;
300
+ }
301
+ if (unreadable !== null) {
302
+ rows.push({ state: "UNOBSERVABLE", title: row.title, why: unreadable });
303
+ countUnobservable(row);
304
+ continue;
305
+ }
306
+ rows.push({ state: "NOT_OBSERVED", title: row.title, targets: [...target.issues] });
307
+ }
308
+
309
+ const observable = rows.filter(r => r.state !== "UNOBSERVABLE").length;
310
+ const compliedUpperBound = rows.filter(r => r.state === "COMPLIED").length;
311
+ return {
312
+ rows,
313
+ observable,
314
+ unobservable: rows.length - observable,
315
+ compliedUpperBound,
316
+ // The whole point of the module, in one expression: an empty denominator
317
+ // withholds the number rather than printing the most alarming one.
318
+ rate: observable === 0 ? null : compliedUpperBound / observable,
319
+ unobservableByRefusal,
320
+ };
321
+ }
322
+
323
+ /**
324
+ * The real lookup: the tracker's COMMENTS endpoint, never the issue body.
325
+ *
326
+ * Separate from the pure reading above so the cases can drive every state
327
+ * without a network, and exported so the reading can be run from a one-liner
328
+ * rather than needing a script nothing else references:
329
+ *
330
+ * ```
331
+ * bun -e 'import {complianceReading, ghIssueComments} from "./lib/filing-compliance";
332
+ * const rows = (await Bun.file(process.env.HOME + "/.rungate/finding-ledger.jsonl").text())
333
+ * .trim().split("\n").map(l => JSON.parse(l));
334
+ * console.log(await complianceReading({rows, lookup: ghIssueComments("hornjason/pai-harness"),
335
+ * windowMs: 24 * 3_600_000}));'
336
+ * ```
337
+ *
338
+ * Every failure is `UNMEASURED` carrying its own sentence. There is no path
339
+ * here that returns an empty comment list for a request that did not succeed.
340
+ */
341
+ export function ghIssueComments(
342
+ repo: string,
343
+ // The seam exists so the failure path can be DRIVEN rather than provoked.
344
+ // Its first version had no argument, so the only way to observe the
345
+ // UNMEASURED branch was to run the case against the live API and hope it
346
+ // failed — a case whose verdict depends on the network is not a case.
347
+ makeClient: () => GitHubClient = createGitHubClient,
348
+ ): CommentLookup {
349
+ return async (issue: number): Promise<CommentReading> => {
350
+ // SC-893: Octokit, not a `gh` subprocess. The three readings are
351
+ // unchanged — a client that cannot be built and a request that failed are
352
+ // both UNMEASURED carrying their own sentence, and neither may degrade
353
+ // into an empty comment list, which would read as "nobody commented".
354
+ let client: GitHubClient;
355
+ try {
356
+ client = makeClient();
357
+ } catch (e) {
358
+ return { reading: "UNMEASURED", why: `no GitHub client: ${(e as Error).message}` };
359
+ }
360
+ try {
361
+ const rows = await listIssueComments(client, repo, issue);
362
+ return { reading: "MEASURED", comments: rows.map(r => ({ at: r.created_at })) };
363
+ } catch (e) {
364
+ return { reading: "UNMEASURED", why: `the comments request failed: ${(e as Error).message}` };
365
+ }
366
+ };
367
+ }
@@ -51,6 +51,9 @@
51
51
  */
52
52
  import { spawnSync } from "child_process";
53
53
 
54
+ import { remoteMainCommit, type RemoteMain } from "./config-loader";
55
+ import { closesFence, fenceOpening, type FenceOpening } from "./markdown-fence";
56
+
54
57
  /**
55
58
  * Where a reviewed plan lives.
56
59
  *
@@ -61,6 +64,9 @@ import { spawnSync } from "child_process";
61
64
  */
62
65
  export const PLAN_DIR = "docs/adr";
63
66
 
67
+ /** A template cell an author has not filled in yet: `{outcome}`, `{blocked-by}`. */
68
+ const PLACEHOLDER = /^\{[a-z-]+\}$/;
69
+
64
70
  /** The column whose cells are issue titles. The header spelling is the contract. */
65
71
  export const TITLE_COLUMN = "Outcome";
66
72
 
@@ -184,11 +190,10 @@ export function plannedTitles(content: string): PlannedTitle[] {
184
190
  * no Outcome column" are different states that must reset together, and two
185
191
  * flags that must agree are two places to forget one. */
186
192
  let table: { column: number | null } | null = null;
187
- /** The opening run of a fence we are inside — `` ``` `` or `~~~` — or `null`. */
188
- let fence: string | null = null;
193
+ /** The fence we are inside, or `null`. The grammar is `lib/markdown-fence.ts`'s (#2130). */
194
+ let fence: FenceOpening | null = null;
189
195
  /** Whether we are inside a `<!-- … -->` that spans lines. */
190
196
  let commented = false;
191
- const opener = /^[ \t]*(`{3,}|~{3,})(.*)$/;
192
197
  for (let i = 0; i < lines.length; i++) {
193
198
  // Every region below also ENDS the table it interrupts, the same way a
194
199
  // line of prose does, so `column` is reset on every one of their lines.
@@ -203,18 +208,11 @@ export function plannedTitles(content: string): PlannedTitle[] {
203
208
  // That direction only DENIES, but it denies a plan a reviewer merged and
204
209
  // the `why` would not say so. Found by the AI review of this change.
205
210
  if (fence !== null) {
206
- const c = indent(lines[i]) <= 3 ? opener.exec(lines[i]) : null;
207
211
  // Only the same marker, at least as long, AND nothing after it. A ```
208
212
  // inside a ~~~ block is content; so is ```js inside a ```md block,
209
- // which is the differential a bare marker test would miss.
210
- if (
211
- c !== null &&
212
- c[1][0] === fence[0] &&
213
- c[1].length >= fence.length &&
214
- c[2].trim() === ""
215
- ) {
216
- fence = null;
217
- }
213
+ // which is the differential a bare marker test would miss. Four or
214
+ // more leading spaces is indented code here, so it never closes.
215
+ if (indent(lines[i]) <= 3 && closesFence(lines[i], fence)) fence = null;
218
216
  table = null;
219
217
  continue;
220
218
  }
@@ -234,13 +232,14 @@ export function plannedTitles(content: string): PlannedTitle[] {
234
232
  const text = line.text;
235
233
 
236
234
  const ind = indent(text);
237
- const f = ind <= 3 ? opener.exec(text) : null;
235
+ const f = ind <= 3 ? fenceOpening(text) : null;
238
236
  // Any marker run OPENS, info string or not — including the spellings
239
237
  // CommonMark would reject as openers. That is deliberate: refusing to
240
238
  // open leaves what follows live, and a reading this function is unsure
241
- // about must not be the one that authorises.
239
+ // about must not be the one that authorises. `fenceOpening` keeps that
240
+ // property for every caller, and says so.
242
241
  if (f !== null) {
243
- fence = f[1];
242
+ fence = f;
244
243
  table = null;
245
244
  continue;
246
245
  }
@@ -280,7 +279,11 @@ export function plannedTitles(content: string): PlannedTitle[] {
280
279
  }
281
280
  if (table.column === null) continue;
282
281
  const title = cells[table.column];
283
- if (title !== undefined && title !== "") out.push({ title, line: i + 1 });
282
+ // **A `{placeholder}` is not a title** (security review of #2008).
283
+ // `docs/adr/TEMPLATE.md` keeps a live table so the decomposition parser
284
+ // can be tested against it, and its Outcome cell is `{outcome}`. Read as a
285
+ // title, that would exempt a filing nobody planned from the cap.
286
+ if (title !== undefined && title !== "" && !PLACEHOLDER.test(title)) out.push({ title, line: i + 1 });
284
287
  }
285
288
  return out;
286
289
  }
@@ -293,8 +296,26 @@ export interface PlanSource {
293
296
  show: (path: string) => string | null;
294
297
  }
295
298
 
296
- /** `git`, reading `origin/main` and never the working tree. */
297
- export function gitSource(root: string, ref: string = "origin/main"): PlanSource {
299
+ /**
300
+ * `git`, reading the commit the REMOTE's `main` names and never the working
301
+ * tree or the local `origin/main` ref — #2095. The anchor is
302
+ * `remoteMainCommit` in `lib/config-loader.ts`. A plan an agent committed and
303
+ * pinned under a forged `origin/main` exempts nothing, because the remote
304
+ * never saw it.
305
+ *
306
+ * `anchorOf` lets the filing gate hand in the ONE reading it also gives the
307
+ * cap's config read, so a merge landing mid-filing cannot judge the plan
308
+ * exemption and the cap against two commits (review of #2140). Alone, it
309
+ * reads the remote itself. Either way it is resolved once, on first use, so a
310
+ * source nobody consults costs no network call. An anchor that cannot be read
311
+ * makes `list` and `show` `null`: could not read, never "no plans".
312
+ */
313
+ export function gitSource(root: string, anchorOf: () => RemoteMain = () => remoteMainCommit(root)): PlanSource {
314
+ let anchor: RemoteMain | undefined;
315
+ const ref = (): string | null => {
316
+ anchor ??= anchorOf();
317
+ return "sha" in anchor ? anchor.sha : null;
318
+ };
298
319
  const git = (args: string[]): string | null => {
299
320
  const r = spawnSync("git", ["-C", root, ...args], {
300
321
  encoding: "utf-8",
@@ -328,13 +349,18 @@ export function gitSource(root: string, ref: string = "origin/main"): PlanSource
328
349
  * ways on 2026-10-29; found by the AI review of this change.
329
350
  */
330
351
  list: () => {
352
+ const sha = ref();
353
+ if (sha === null) return null;
331
354
  const out = git([
332
- "ls-tree", "-r", "--full-name", "--name-only", ref, "--", `:(top)${PLAN_DIR}/`,
355
+ "ls-tree", "-r", "--full-name", "--name-only", sha, "--", `:(top)${PLAN_DIR}/`,
333
356
  ]);
334
357
  if (out === null) return null;
335
358
  return out.split("\n").map(s => s.trim()).filter(s => s.endsWith(".md"));
336
359
  },
337
- show: path => git(["show", `${ref}:${path}`]),
360
+ show: path => {
361
+ const sha = ref();
362
+ return sha === null ? null : git(["show", `${sha}:${path}`]);
363
+ },
338
364
  };
339
365
  }
340
366
 
@@ -564,11 +564,62 @@ export const DUPLICATE_MIN_SHARED_LOCATIONS = 1;
564
564
  * deleting: a measurement that names a mechanism it never varied will read
565
565
  * as settled for as long as nobody varies it.
566
566
  *
567
- * **The 946-pair table above is not reproducible.** It was measured live
568
- * against a tracker that has moved and no corpus was stored, so neither
569
- * constant can be re-derived by anyone — including anyone who disagrees with
570
- * leaving them. **Tracked as #1365**; until a fixture exists, treat every
571
- * number in this docblock as a reading someone took once.
567
+ * **The 946-pair table above is not reproducible, and never will be.** It was
568
+ * measured live against a tracker that has moved and no corpus was stored.
569
+ * Those 44 findings are gone; #1365 did not recover them and nothing here
570
+ * claims it did. Treat every number above this line as a reading someone took
571
+ * once.
572
+ *
573
+ * ## WHAT IS REPRODUCIBLE, FROM HERE ON (#1365)
574
+ *
575
+ * A corpus is now frozen in `test/fixtures/finding-dedupe-corpus.json` — the
576
+ * fourteen findings these docblocks name inside a PAIR or a CLUSTER, fetched
577
+ * once by `scripts/freeze-dedupe-corpus.ts` and committed. The table below is
578
+ * the stdout of `bun scripts/print-dedupe-pair-table.ts` over that fixture,
579
+ * and `test/dedupe-corpus-table.test.ts` fails when the two differ. So it is
580
+ * a command's output rather than a reading, and it cannot go stale quietly.
581
+ *
582
+ * **Membership is checked, not asserted.** Each of the fourteen carries the
583
+ * sentence from THIS file that admits it, and
584
+ * `test/dedupe-corpus-membership.test.ts` refuses an id whose sentence is
585
+ * absent, does not name it, or lies inside the generated block below — so a
586
+ * member can never be justified by the table its own membership produced.
587
+ *
588
+ * <!-- BEGIN dedupe-pair-table -->
589
+ * Corpus: 14 findings, 91 pairs, frozen 2026-11-07.
590
+ * Regenerate with `bun scripts/print-dedupe-pair-table.ts`.
591
+ *
592
+ * | rule | pairs | which |
593
+ * |---|---|---|
594
+ * | `qty>=2 AND loc>=1` | 1 | 1176/1187 |
595
+ * | containment >= 0.6 | 3 | 1175/1177, 1195/1196, 1454/1456 |
596
+ * | containment >= 0.8 (shipped) | 3 | 1175/1177, 1195/1196, 1454/1456 |
597
+ * | either arm — what the arbiter calls DUPLICATE | 4 | 1175/1177, 1176/1187, 1195/1196, 1454/1456 |
598
+ *
599
+ * Findings under the floor of 4 identity keys, which the containment arm scores 0 against everything: #1239.
600
+ * <!-- END dedupe-pair-table -->
601
+ *
602
+ * ### Four claims above reproduce. One does not.
603
+ *
604
+ * Reproduced exactly, against the live bodies: #1175/#1177 at 1.000 and
605
+ * #1454/#1456 at 0.900 and #1195/#1196 at **0.833**, and #1195/#1239 scoring
606
+ * **0.000** because #1239 carries three identity keys and sits under the
607
+ * floor. That is the whole of the #1536 table, re-derived from a fixture.
608
+ *
609
+ * **The `qty>=2 AND loc>=1` row does not.** It reads *4 — 1175/1177,
610
+ * 1195/1196, 1269/1286, 1162/1226*; over the frozen corpus that arm flags
611
+ * **one** pair, and the pair is #1176/#1187 — the shape this file already
612
+ * names as the one it cannot tell from a duplicate, since #1187 quotes other
613
+ * findings' readings because it is *about* them.
614
+ *
615
+ * **This is a failure to reproduce, not a demonstration that the row was
616
+ * false.** The fixture holds the bodies as the tracker had them on the freeze
617
+ * date, and an issue body is editable: six of these fourteen were closed and
618
+ * several edited in the weeks between. What can be said is the thing #1365
619
+ * exists to make sayable at all — *the row cannot be checked against anything,
620
+ * and the arm it justifies is the one tuned on the corpus that was lost.*
621
+ * Neither constant is moved on this reading; a re-tune needs a corpus
622
+ * collected for the purpose, which is a different issue from freezing one.
572
623
  *
573
624
  * The floor exists because containment is meaningless on a tiny key set — a
574
625
  * one-key finding is wholly contained in anything mentioning that key, which
@@ -857,6 +908,29 @@ export type ArbiterRefusal =
857
908
  * answer at all and refuses, naming the path so an operator can act.
858
909
  */
859
910
  | "UNMEASURED_CAP"
911
+ /**
912
+ * The body is short a section the issue form requires (#1741).
913
+ *
914
+ * **The last stage, and it converts an ALLOW only.** Everything before it
915
+ * asks whether this should be on the tracker at all; this one asks whether
916
+ * what is about to land on the tracker is readable by the things that read
917
+ * it. An issue naming no files cannot be checked against rule 2, cannot be
918
+ * scanned for the file-overlap conflicts that put four agents on
919
+ * `lib/bash-write-guard.ts`, and cannot tell a picker what they are picking
920
+ * up.
921
+ *
922
+ * **Waivable, and deliberately so.** Unlike the three above, this one IS a
923
+ * claim about the filing — it says a named section is absent, which is a
924
+ * fact the agent can refute by adding it or override when they genuinely
925
+ * mean to file a stub. A count takes no argument; a shape does.
926
+ *
927
+ * The sections come from `requiredSections` in `lib/issue-shape.ts`, which
928
+ * is the same decider the two issue forms and `plan-issues --decompose`
929
+ * read. That is the whole of #1741: before it, a gate requiring the form's
930
+ * fields would have refused every row of every decomposed plan, because
931
+ * the generator emitted two of the five.
932
+ */
933
+ | "MALFORMED"
860
934
  /** Something could not be evaluated. Fails; never skips. */
861
935
  | "UNMEASURED";
862
936
 
@@ -210,7 +210,10 @@ export function classifyCategory(finding: Pick<Finding, "title" | "body">): Find
210
210
  // ── Severity ─────────────────────────────────────────────────────────────
211
211
 
212
212
  /**
213
- * The three tags the source design posts, and no fourth.
213
+ * How an ai-review tag SORTS. Three of its members are also the three tags
214
+ * the source design posts; `Unobserved` (#1879) is a fourth that no
215
+ * verifier votes — `JURY_VOTE_SEVERITIES` below is the set that answers
216
+ * that question, and this one is allowed to be wider.
214
217
  *
215
218
  * `Pre-existing` is the one that matters most here and the one we had no way
216
219
  * to say: a finding about code the change never touched is not the author's
@@ -236,6 +239,32 @@ export function classifyCategory(finding: Pick<Finding, "title" | "body">): Find
236
239
  export { SEVERITY_RANK };
237
240
  export type { Severity };
238
241
 
242
+ /**
243
+ * What a VERIFIER may vote, which is not the same question as how a tag
244
+ * sorts — #1914 round 3.
245
+ *
246
+ * `SEVERITY_RANK` was doing both jobs, and they coincided only because the
247
+ * two sets happened to be equal. #1879 added `Unobserved` to the sort,
248
+ * because an ai-review annotation needs somewhere to put a finding whose
249
+ * claim nothing ran to produce; `parseVotes` validated against the same
250
+ * table, so a verifier vote declaring `severity: "Unobserved"` silently
251
+ * became legal, could win `severityOf`'s majority, and would be
252
+ * interpolated into a posted comment as a word this module defines no
253
+ * meaning for. Nothing prompts a verifier with it today — but the guard
254
+ * had stopped being able to refuse it, which is the shape
255
+ * `.claude/rules/checks-must-be-able-to-fail.md` is about.
256
+ *
257
+ * So the two questions get two lists. This one is CLOSED: a verifier
258
+ * assigns the author a severity, and `Unobserved` is not something a
259
+ * verifier observes — it is a statement about the review job, not about
260
+ * the finding's magnitude.
261
+ *
262
+ * `test/finding-jury.test.ts` asserts every member is a key of
263
+ * `SEVERITY_RANK`, so this list cannot drift to a tag that does not sort.
264
+ * The relation is one-way by design: the rank table may be wider.
265
+ */
266
+ export const JURY_VOTE_SEVERITIES: readonly Severity[] = ["Important", "Nit", "Pre-existing"];
267
+
239
268
  // ── The vote ─────────────────────────────────────────────────────────────
240
269
 
241
270
  export interface VerifierVote {
@@ -314,7 +343,9 @@ function shapeOf(value: unknown): string {
314
343
  * two of the others carry the same defect. An unrecognised `category` is not
315
344
  * in `DROPPED_CATEGORIES`, so it reads to `juryCategory` as a keep category.
316
345
  * An unrecognised `severity` indexes `SEVERITY_RANK` to `undefined`, making
317
- * the sort comparator in `severityOf` return `NaN`.
346
+ * the sort comparator in `severityOf` return `NaN`. It is checked against
347
+ * `JURY_VOTE_SEVERITIES` rather than against that table — see there for why
348
+ * the two are different questions (#1914 round 3).
318
349
  *
319
350
  * **`Object.hasOwn`, never the `in` operator**, and this is not a style
320
351
  * preference. `in` walks the prototype chain, so `"constructor" in
@@ -357,10 +388,18 @@ export function parseVotes(parsed: unknown): readonly VerifierVote[] {
357
388
  `an unrecognised category is not a dropped one, so it would read as a keep — ${UNREADABLE_VOTE}`,
358
389
  );
359
390
  }
360
- if (v.severity !== undefined && !(typeof v.severity === "string" && Object.hasOwn(SEVERITY_RANK, v.severity))) {
391
+ // #1914 round 3: `JURY_VOTE_SEVERITIES`, not `SEVERITY_RANK`. The rank
392
+ // table answers how a tag SORTS and is allowed to be wider than what a
393
+ // verifier may vote; validating against it made every new ai-review tag
394
+ // a legal vote by accident. `includes` over a frozen list rather than
395
+ // `Object.hasOwn`, so there is no prototype chain to walk at all.
396
+ if (
397
+ v.severity !== undefined &&
398
+ !(typeof v.severity === "string" && JURY_VOTE_SEVERITIES.includes(v.severity as Severity))
399
+ ) {
361
400
  throw new Error(
362
401
  `${where}, from \`${v.verifier}\`, names an unknown \`severity\` (${shapeOf(v.severity)}): ` +
363
- `it has no rank, so the severity sort would compare against NaN — ${UNREADABLE_VOTE}`,
402
+ `a verifier may vote ${JURY_VOTE_SEVERITIES.join(", ")} and nothing else — ${UNREADABLE_VOTE}`,
364
403
  );
365
404
  }
366
405
  return {