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
@@ -106,8 +106,10 @@ import {
106
106
  listPRs,
107
107
  parseOwnerRepo,
108
108
  TRUSTED_ASSOCIATIONS,
109
+ type GitHubClient,
109
110
  type OpenIssuePage,
110
111
  } from "./github";
112
+ import { closedIssueCounts } from "./issue-decomposition";
111
113
  import { branchOf, toplevel } from "./launch-base";
112
114
  import { readWorktreeRemote, repoSlug, type RemoteReading } from "./worktree-repo";
113
115
  import {
@@ -127,21 +129,59 @@ import {
127
129
  type JuryReading,
128
130
  type Severity,
129
131
  } from "./finding-jury";
130
- import { clauses, createsIssue, flagValues, labelValues } from "./issue-create-override";
132
+ import {
133
+ apiFilingRepo,
134
+ apiRestFields,
135
+ clauses,
136
+ filingDirectory,
137
+ createsIssue,
138
+ flagValues,
139
+ graphqlDocument,
140
+ graphqlVariables,
141
+ labelValues,
142
+ } from "./issue-create-override";
143
+ import { headingFor, missingSections, requiredSections } from "./issue-shape";
144
+ import { asIssueFiles, overlapNote } from "./issue-file-overlap";
131
145
  import { gitSource, plannedFiling, type PlanSource } from "./filing-plan";
132
146
  import { resolveShipPolicy, type ShipPolicy } from "./ship-mode";
133
- import { tryLoadRungateConfig } from "./config-loader";
147
+ import {
148
+ CommittedConfigUnreadable,
149
+ committedConfig,
150
+ gitCommittedFiles,
151
+ readCommittedConfig,
152
+ remoteMainCommit,
153
+ type CommittedConfigReading,
154
+ type CommittedFiles,
155
+ type RemoteMain,
156
+ } from "./config-loader";
157
+ import { queueLabelIn, readFilingOverrideLabel } from "./config-readers";
134
158
 
135
159
  /**
136
- * The label that waives this gate.
160
+ * The label that waives this gate — `board.filingOverrideLabel`, or `null`.
137
161
  *
138
162
  * Separate from `OVERRIDE_LABELS`, which waives the VERIFY-phase lock. The
139
163
  * two gates answer different questions about the same command — *should you
140
164
  * be filing right now* and *is this finding worth filing* — and one label
141
165
  * waiving both would make it impossible to count how often each was
142
166
  * overridden, which is the measurement #1261 exists to start.
167
+ *
168
+ * **Config, not a constant** (SC-2735). It was `FILING_OVERRIDE_LABEL`, so
169
+ * the library chose every consumer's waiver token. `null` means NO waiver
170
+ * exists — absent, blank, non-string and unparseable alike — because a
171
+ * built-in name substituted for absent config would open the gate in every
172
+ * repository that never declared one.
173
+ *
174
+ * **It takes a THUNK for the reason `queueLabelFor` does**: the read is a
175
+ * bare `JSON.parse` underneath, and evaluated as an argument expression a
176
+ * malformed config would throw straight out of a PreToolUse hook.
143
177
  */
144
- export const FILING_OVERRIDE_LABEL = "arbiter-override";
178
+ export function filingOverrideLabelFor(load: () => string | null): string | null {
179
+ try {
180
+ return load();
181
+ } catch {
182
+ return null;
183
+ }
184
+ }
145
185
 
146
186
  /**
147
187
  * The refusals no label waives, each with the sentence saying why.
@@ -189,7 +229,7 @@ export const UNWAIVABLE_REFUSALS: Partial<Record<ArbiterRefusal, string>> = {
189
229
  };
190
230
 
191
231
  /**
192
- * Does `FILING_OVERRIDE_LABEL` waive this refusal?
232
+ * Does the filing-override label waive this refusal?
193
233
  *
194
234
  * **ONE binding, and it exists because there were briefly two.** `filingGate`
195
235
  * decided it when it chose whether the label overrides, and `refusalMessage`
@@ -298,6 +338,12 @@ export const FILINGS_PER_RUN = 1;
298
338
  * Jason's call, 2026-11-02: *"raise the cap for this work until we have
299
339
  * these stages completed and ready for agents to swarm"*.
300
340
  *
341
+ * **Raised 3 → 12 on 2026-11-08, Jason's call again**: *"You can increase the
342
+ * cap for the work we're doing. I keep telling you that we need to have this
343
+ * not being an issue… We're doing the fundamental work here that needs to get
344
+ * through."* Second time he has had to say it, which is itself the reading
345
+ * that 3 was wrong for this population.
346
+ *
301
347
  * ## Why this does not reopen the hole the docblock above closes
302
348
  *
303
349
  * The objection is *"a cap read from config is a cap an agent raises"*, and
@@ -317,24 +363,44 @@ export const FILINGS_PER_RUN = 1;
317
363
  * somebody remembers to lower a constant. A dated expiry would have to be
318
364
  * guessed, and an expired one is read as a bug rather than a policy.
319
365
  *
320
- * ## Why 3
366
+ * ## Why 12, and why 3 was wrong
321
367
  *
322
368
  * The cap exists because of what a SWARM did — #1595 measured 57 filed
323
369
  * against 53 closed in a day — and the engine work is the opposite
324
370
  * population: it is what makes the backlog shrink, which is the carve-out
325
- * already granted to the opened-against-closed ratio. The number is the
326
- * count Stage B actually needed rather than a round one: this run spent its
327
- * allowance on #1704 and then had two genuine findings it could not file,
328
- * both of them `green-check-lies` against ladder items that read MET only
329
- * because a person had edited the tracker. Three is 13x below #1595's
330
- * per-day figure, and `FG-194` asserts it stays at or below five, so it
331
- * cannot creep into a swarm's number one pull request at a time.
371
+ * already granted to the opened-against-closed ratio.
372
+ *
373
+ * **3 was set from one run's shortfall and it was measured from the wrong
374
+ * end.** It was *"the count Stage B actually needed"* — a run that spent
375
+ * its allowance and then had two findings left over. That is the count a
376
+ * run had left over on one day, not the count the work generates, and the
377
+ * two are different numbers whenever the day is busier than the one that
378
+ * was sampled.
379
+ *
380
+ * Measured from the ledger instead, `~/.rungate/finding-ledger.jsonl`,
381
+ * 24 hours to 2026-11-08 15:30Z, one run-directory doing engine work:
382
+ *
383
+ * | reading | count |
384
+ * |---|---|
385
+ * | distinct findings that reached the tracker | 6 |
386
+ * | distinct findings refused `OVER_CAP` | 8 |
387
+ * | of those, later admitted on a retry | 3 |
388
+ * | distinct findings LOST to the cap | 5 |
389
+ *
390
+ * So the day's real demand was about eleven and the allowance was three. A
391
+ * cap of 5 would still have refused six of them, which is why this is not
392
+ * the one-step raise `FG-194`'s old bound invited.
393
+ *
394
+ * Twelve is 4.75x below #1595's per-day figure, so it still binds a swarm
395
+ * hard — a swarm hits it before lunch. `FG-194` keeps the anti-creep job
396
+ * and its bound moves with it, so the next raise is still an argument
397
+ * against a reading rather than an edit nobody has to defend.
332
398
  *
333
399
  * A PLANNED filing is already exempt from the cap entirely (`plannedFiling`),
334
400
  * so this number governs ad-hoc findings only — the decompose path that
335
401
  * creates seven issues from a merged plan never consulted it.
336
402
  */
337
- export const FILINGS_PER_RUN_DIRECT = 3;
403
+ export const FILINGS_PER_RUN_DIRECT = 12;
338
404
 
339
405
  /**
340
406
  * The allowance a given ship policy earns.
@@ -401,18 +467,515 @@ export type FilingCapReading = {
401
467
  * reports `false` and earns no note. This is the corrupt case alone.
402
468
  */
403
469
  unreadable: boolean;
470
+ /**
471
+ * Which setting could not be read, for the note (#2070). Absent when
472
+ * `unreadable` is false; the note's default names the `ship` block.
473
+ */
474
+ unreadableSource?: string;
475
+ /**
476
+ * Set when the COMMITTED config could not be read at all — the revision did
477
+ * not resolve, so nothing was read (#1964). It carries why, for the
478
+ * UNMEASURED note. A commit that carries a malformed config is the other
479
+ * case, and reports through `unreadableSource` like a malformed working tree
480
+ * did, because that config IS present.
481
+ */
482
+ committedUnmeasured?: string;
483
+ /**
484
+ * The cap is the DIRECT-ship allowance, derived from `ship.mode` — not a
485
+ * `board.filingsPerRun` override, not harness mode, not a fallback (#2086).
486
+ *
487
+ * The only cap ADR-016's net-growth ceiling may replace. A project that
488
+ * wrote its own number chose it, harness mode keeps its cap of 1 (the
489
+ * ADR's *Not decided here*), and a cap nobody could read must never be a
490
+ * route to the larger number. Carried on this reading, rather than asked
491
+ * again from the config, so one decider answers both "what is the cap" and
492
+ * "where did it come from".
493
+ */
494
+ direct: boolean;
404
495
  };
405
496
 
497
+ /**
498
+ * The highest per-run cap `board.filingsPerRun` may set (#2070 review).
499
+ *
500
+ * The direct-ship allowance itself, so the override can lower a harness
501
+ * project's cap or raise it to what direct mode already gets, and no
502
+ * further. FG-194 bounds that allowance because #1595's swarm filed 57 in a
503
+ * day; an override with no ceiling walked straight past it. Tied to the
504
+ * constant rather than a second literal, so raising one is raising both and
505
+ * FG-194 still decides. A value above it is refused, not clamped: a silent
506
+ * clamp is a cap nobody chose, reported as if somebody had.
507
+ */
508
+ export const FILING_CAP_OVERRIDE_MAX = FILINGS_PER_RUN_DIRECT;
509
+
510
+ /** The per-run cap override's config path, as the note names it (#2070). */
511
+ export const FILING_CAP_OVERRIDE_SOURCE = "`board.filingsPerRun`";
512
+
513
+ /**
514
+ * `board.filingsPerRun`, the cap set apart from `ship.mode` (#2070).
515
+ *
516
+ * `null` when it is not set, so the ship-mode derivation stands. A value
517
+ * that is present and is not a positive integer is `"unusable"`, never
518
+ * coerced: `Number("12")` or `Math.floor(1.5)` would turn a typo into a cap
519
+ * nobody chose, and the direction a bad config may push this is down.
520
+ */
521
+ export function filingCapOverride(config: Record<string, unknown> | null | undefined): number | null | "unusable" {
522
+ const board = config?.board;
523
+ if (board === undefined || board === null) return null;
524
+ if (typeof board !== "object" || Array.isArray(board)) return "unusable";
525
+ if (!("filingsPerRun" in board)) return null;
526
+ const raw = (board as Record<string, unknown>).filingsPerRun;
527
+ return typeof raw === "number" && Number.isInteger(raw) && raw > 0 && raw <= FILING_CAP_OVERRIDE_MAX
528
+ ? raw
529
+ : "unusable";
530
+ }
531
+
406
532
  export function filingsPerRunFor(
407
533
  load: () => Record<string, unknown> | null | undefined,
408
534
  ): FilingCapReading {
409
535
  try {
410
- return { cap: filingsPerRun(resolveShipPolicy(load())), unreadable: false };
536
+ const config = load();
537
+ // The override is read FIRST, and a valid one returns before the ship
538
+ // block is touched: it does not depend on the ship block, so a corrupt
539
+ // one must not be able to discard it (review of #2075).
540
+ const override = filingCapOverride(config);
541
+ if (typeof override === "number") return { cap: override, unreadable: false, direct: false };
542
+ if (override === "unusable") {
543
+ return { cap: FILINGS_PER_RUN, unreadable: true, unreadableSource: FILING_CAP_OVERRIDE_SOURCE, direct: false };
544
+ }
545
+ const policy = resolveShipPolicy(config);
546
+ return { cap: filingsPerRun(policy), unreadable: false, direct: policy.mode === "direct" };
547
+ } catch (e) {
548
+ // #1964: a committed config that could not be read is named, not merely
549
+ // strict. `ref` means no revision resolved; `content` means the commit
550
+ // carries a config that will not resolve, which is the malformed case.
551
+ if (e instanceof CommittedConfigUnreadable) {
552
+ return e.kind === "ref"
553
+ ? { cap: FILINGS_PER_RUN, unreadable: true, committedUnmeasured: e.message, direct: false }
554
+ : { cap: FILINGS_PER_RUN, unreadable: true, unreadableSource: `committed config (at \`${e.ref}\`)`, direct: false };
555
+ }
556
+ return { cap: FILINGS_PER_RUN, unreadable: true, direct: false };
557
+ }
558
+ }
559
+
560
+ /**
561
+ * The filing cap, read from COMMITTED config only — SC-2753's one binding
562
+ * (#1964).
563
+ *
564
+ * Every reader of the cap calls this: the `gh issue create` gate,
565
+ * `scripts/github-op.ts`'s Octokit `issue-create` door, and `work-status`'s
566
+ * FILING CAP line. Round 1 of PR #2094 found the second door still reading
567
+ * the working tree after the gate was fixed, so an agent refused at one door
568
+ * could raise its own cap and file through the other. One function means a
569
+ * door that computes its own cap is a second call to `filingsPerRunFor`,
570
+ * which FG-287 refuses by file name.
571
+ *
572
+ * Takes the reading, not a root, because the gate reads the committed config
573
+ * once per command and also takes the queue label from that same reading.
574
+ */
575
+ export function committedFilingCap(reading: CommittedConfigReading): FilingCapReading {
576
+ return filingsPerRunFor(() => committedConfig(reading));
577
+ }
578
+
579
+ /**
580
+ * **The cap's THIRD route: a filing the project's own work queue claims.**
581
+ *
582
+ * Jason's call, 2026-11-10: *"The filing cap shouldn't work right now if we
583
+ * were doing stuff specific for the car we're building."* On 2026-11-09 at
584
+ * 23:50 the cap refused a thirteenth filing and six agreements about the
585
+ * engine itself were written as issue COMMENTS instead. The cap worked; the
586
+ * population was wrong, the same way it was wrong for the decompose path the
587
+ * plan route exists for. A comment is invisible to the board and there is no
588
+ * path that re-files one when the allowance resets, so four of the six were
589
+ * still only comments a day later.
590
+ *
591
+ * **Why this is not the `arbiter-override` hole reopened.** That label waives
592
+ * a claim about a FINDING, which is a per-filing judgement, and `OVER_CAP` is
593
+ * unwaivable precisely because a valid-sounding reason defeating a count IS
594
+ * the bar that let three of three filings through on 2026-10-24. This waives
595
+ * nothing and argues nothing: it asks whether the PROJECT, in its own
596
+ * committed config, declared a work queue and whether this filing is in it.
597
+ * A filer can spell the label; it cannot make a tree declare one.
598
+ *
599
+ * **`board.queueLabel` and no new key**, read through `readQueueLabel` —
600
+ * #1727's single binding, created so the writer that applies the label
601
+ * (`plan-issues --decompose`) and the reading that scores it
602
+ * (`board-conformance`) cannot disagree about what the queue is called. A
603
+ * second config key here would be a third opinion on one question.
604
+ *
605
+ * **It RAISES the ceiling and exempts nothing** — see `QUEUE_FILINGS_PER_RUN`.
606
+ * This sentence used to say it exempted the SPENT arm the way `plannedFiling`
607
+ * does, which was true of the FIRST design and false of the shipped one, and
608
+ * round 6 of the review was right to keep pointing at it: a reader who
609
+ * believed it could reintroduce the authorization bypass the security review
610
+ * already rejected once. A queued clause increments `spent` like every other
611
+ * (`if (!planned.planned) spent += 1`); only the number it is compared
612
+ * against moves, and only via `capForClause`.
613
+ *
614
+ * The parting `plannedFiling` makes does still apply: `uncountable` is never
615
+ * cleared by either route, because a ledger that cannot be read cannot RECORD
616
+ * what it admitted, and an admission nobody can audit is what the ledger
617
+ * exists to prevent.
618
+ *
619
+ * **It takes a THUNK for the reason `filingsPerRunFor` does.**
620
+ * `readQueueLabel` calls `tryLoadRungateConfig`, which is a bare
621
+ * `JSON.parse(readFileSync(...))` underneath with no catch. Evaluated as an
622
+ * argument expression it would throw straight out of `filingGate` — a
623
+ * PreToolUse hook — and block every filing on the machine, which is strictly
624
+ * worse than the state it guards. A signature taking the VALUE cannot guard
625
+ * its own production; one taking the thunk can only be called the right way.
626
+ *
627
+ * Absent, blank, non-string and unparseable all resolve to `null`, and the
628
+ * direction is the property: `null` raises nothing. A built-in substituted
629
+ * for absent config would let a filer in any unscaffolded repository spell
630
+ * its way past the cap — `.claude/rules/config-access.md`, *Silent Default
631
+ * Substitution*. `FG-253` is the assertion rather than this sentence.
632
+ */
633
+ export function queueLabelFor(load: () => string | null): string | null {
634
+ try {
635
+ return load();
411
636
  } catch {
412
- return { cap: FILINGS_PER_RUN, unreadable: true };
637
+ return null;
638
+ }
639
+ }
640
+
641
+ /**
642
+ * The configured queue label this filing carries, or `null` for one it does
643
+ * not — and `null` for every filing when the tree configures no queue.
644
+ *
645
+ * Separate from `queueLabelFor` because they answer different questions about
646
+ * different inputs — *what is the queue called* and *is this filing in it* —
647
+ * and returning the LABEL rather than a boolean is what lets the ledger row
648
+ * name which queue admitted it. A raise that reaches the tracker without
649
+ * naming what granted it is indistinguishable from the cap not having run.
650
+ */
651
+ export function queueCarveOut(
652
+ labels: string[],
653
+ queueLabel: string | null,
654
+ repo: string | null,
655
+ directGh: boolean,
656
+ ): string | null {
657
+ // **An invocation this file cannot vouch for gets no raise** — round 3,
658
+ // and a re-scope rather than a fourth spelling. See `directGhInvocation`.
659
+ if (!directGh) return null;
660
+ // **A filing aimed at ANOTHER tracker is never in this project's queue**
661
+ // — the security review of PR #1963 found this, and it is a real hole:
662
+ // `board.queueLabel` is a statement about THIS project's board, and a
663
+ // `gh issue create --repo other/x --label engine` clause borrowed it to
664
+ // raise its ceiling on a tracker whose config was never consulted. The
665
+ // same mismatch `targetFor` exists to prevent one stage earlier.
666
+ if (repo !== null) return null;
667
+ if (queueLabel === null) return null;
668
+ return labels.includes(queueLabel) ? queueLabel : null;
669
+ }
670
+
671
+ /**
672
+ * The allowance for filings the project's own work queue claims.
673
+ *
674
+ * ## This is a RAISED CEILING, not an exemption, and the first spelling was
675
+ * an exemption
676
+ *
677
+ * PR #1963 shipped the queue route as a full bypass of the SPENT arm, beside
678
+ * `plannedFiling`: a queued clause did not spend the counter and was skipped
679
+ * by the reservation stage entirely. The security review called it an
680
+ * *authorization bypass / self-granted exemption of an unwaivable control*
681
+ * and was right. The plan route can be an exemption because a filer cannot
682
+ * get a title onto `origin/main` without somebody merging it. A LABEL has no
683
+ * such author: on a tree that declares a queue — this one declares
684
+ * `"engine"` — any agent can spell it, and `OVER_CAP` is unwaivable
685
+ * precisely so that no argument a filer can make defeats a count. An
686
+ * uncounted route is the strongest argument there is.
687
+ *
688
+ * So the queue route is counted, reserved, and raced exactly like every
689
+ * other filing. What it gets is a HIGHER number.
690
+ *
691
+ * ## Why a higher ceiling fixes what actually went wrong
692
+ *
693
+ * The 2026-11-09 failure was not that the cap existed. It was that engine
694
+ * work ran out of allowance **behind ad-hoc filings** — the run reached 12
695
+ * and the next six findings, all of them about the engine, became comments.
696
+ * A ceiling of 24 means the engine filings are the ones still admitted when
697
+ * the ad-hoc population has spent its 12, which is the whole of it.
698
+ *
699
+ * ## Why 24, and the residual it leaves
700
+ *
701
+ * Twice `FILINGS_PER_RUN_DIRECT`, and the factor is the defensible part
702
+ * rather than the digit: the ledger reading that set 12 measured ~11 real
703
+ * findings a day in one engine run-directory, so one more run's worth of
704
+ * headroom is the smallest bound that cannot re-run 2026-11-09. It still
705
+ * binds a runaway loop at 24 in a day, where the first spelling bound it at
706
+ * nothing.
707
+ *
708
+ * **The residual, stated rather than hidden: ONE counter, two ceilings.** A
709
+ * run that spends 20 on ad-hoc findings leaves the queue route 4, not 24.
710
+ * A second ledger lane would separate them and is the stronger design; it
711
+ * needs `runIntents`, `intentOrdinal` and `reserveAllowance` to carry a
712
+ * population, which is a bigger change than this finding justifies in one
713
+ * round. The direction of the weakness is toward REFUSING, which is the
714
+ * side a cap is allowed to be wrong on.
715
+ */
716
+ export const QUEUE_FILINGS_PER_RUN = 2 * FILINGS_PER_RUN_DIRECT;
717
+
718
+ /**
719
+ * The ceiling THIS clause is judged against — the one decider, read by the
720
+ * pre-read and by the reservation stage so the two cannot disagree.
721
+ *
722
+ * A clause the queue does not claim is judged against the run's ordinary
723
+ * allowance, unchanged. `FG-197` holds every cap consumer to taking the
724
+ * number rather than reaching for a constant, and this is now the thing they
725
+ * take.
726
+ */
727
+ export function capForClause(queuedBy: string | null, runCap: number): number {
728
+ return queuedBy === null ? runCap : Math.max(runCap, QUEUE_FILINGS_PER_RUN);
729
+ }
730
+
731
+ /**
732
+ * The per-run cap while the repository closes issues at least as fast as it
733
+ * opens them (ADR-016, #2086).
734
+ *
735
+ * ## What the cap was for, and what it measured instead
736
+ *
737
+ * The cap exists for rule 7's warning: opened faster than closed, the
738
+ * backlog diverges however fast the work goes. It measured every
739
+ * `gh issue create` instead. On 2026-11-13 the repository opened 30 issues
740
+ * and closed 28 in a day — a backlog that was not diverging — and the cap
741
+ * still refused work Jason had agreed: the README (#2081) and a split he had
742
+ * asked for (#2082) were filed by hand.
743
+ *
744
+ * So the count changes and nothing else does. While trailing-day
745
+ * *opened − closed* is zero or below, every run's cap is this number. Above
746
+ * zero, or when the count cannot be read, it is the ship-mode cap, so the
747
+ * fallback is always the lower number. The duplicate, no-claim and
748
+ * comment-instead refusals are untouched — a review finding still defaults to
749
+ * a PR comment.
750
+ *
751
+ * ## Why 36
752
+ *
753
+ * Jason's number, after the dry run. Three times `FILINGS_PER_RUN_DIRECT`,
754
+ * and still well under the 57 a day `FG-194` was written against. One runaway
755
+ * session that pushes opened above closed drops every run back to 12 within
756
+ * the window, which is the bound `FG-194` exists to keep.
757
+ *
758
+ * `FG-274` holds the value; `netGrowthCeiling` is the only reader.
759
+ */
760
+ export const NET_GROWTH_CEILING = 36;
761
+
762
+ /**
763
+ * The repository's trailing-day issue counts, or why they could not be read.
764
+ *
765
+ * `UNMEASURED` is never zeros. Zero opened and zero closed is a quiet day and
766
+ * earns the ceiling; a count nobody took earns nothing.
767
+ */
768
+ export type NetGrowthReading =
769
+ | { reading: "MEASURED"; opened: number; closed: number }
770
+ | { reading: "UNMEASURED"; why: string };
771
+
772
+ /**
773
+ * What set a run's cap, as the ledger row records it (#2086).
774
+ *
775
+ * The measured counts plus whether the ceiling applied, or the UNMEASURED
776
+ * reading as it was taken. `null` where the ceiling was never consulted —
777
+ * harness mode, an explicit `board.filingsPerRun`, an unreadable config —
778
+ * because no count was read for a cap the ceiling cannot reach.
779
+ */
780
+ export type NetGrowthBasis =
781
+ | { reading: "MEASURED"; opened: number; closed: number; ceiling: boolean }
782
+ | { reading: "UNMEASURED"; why: string };
783
+
784
+ /**
785
+ * **The one decider: the run's cap, given its ship-mode cap and the count.**
786
+ *
787
+ * Returns the cap with the basis that set it, so the refusal and the ledger
788
+ * row cannot describe a different decision from the one enforced.
789
+ *
790
+ * - Not the direct-ship allowance (`allowance.direct` false): the cap
791
+ * stands, records nothing, and **the count is never read**.
792
+ * - Count unreadable, or the reader throws: the cap stands, and the reading
793
+ * is recorded as UNMEASURED. Never the ceiling — the fail-closed direction.
794
+ * - opened − closed ≤ 0: `NET_GROWTH_CEILING`.
795
+ * - opened − closed > 0: the cap stands.
796
+ *
797
+ * **It takes a THUNK, and that is what keeps eligibility to one site.** With
798
+ * a value, the caller has to decide whether to read before calling, and that
799
+ * guard and the one in here are two deciders over one question — mutate
800
+ * either and the other holds the harness case up
801
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape). The
802
+ * catch lives here too, because this runs inside a PreToolUse hook where a
803
+ * throw blocks every filing on the machine.
804
+ *
805
+ * The engine raise is applied AFTER this, by `capForClause`, exactly as
806
+ * before: a queued clause gets the larger of this and `QUEUE_FILINGS_PER_RUN`.
807
+ */
808
+ export async function netGrowthCeiling(
809
+ allowance: FilingCapReading,
810
+ read: () => Promise<NetGrowthReading>,
811
+ ): Promise<{ cap: number; basis: NetGrowthBasis | null }> {
812
+ if (!allowance.direct) return { cap: allowance.cap, basis: null };
813
+ // `then(read)`, not `read()`: a reader that throws SYNCHRONOUSLY would
814
+ // otherwise escape the catch below.
815
+ const growth = await Promise.resolve()
816
+ .then(read)
817
+ .catch((e: unknown) => unmeasuredGrowth(`the trailing day's issues could not be read (${errorText(e)})`));
818
+ if (growth.reading !== "MEASURED") return { cap: allowance.cap, basis: growth };
819
+ const ceiling = growth.opened - growth.closed <= 0;
820
+ return {
821
+ cap: ceiling ? NET_GROWTH_CEILING : allowance.cap,
822
+ basis: { reading: "MEASURED", opened: growth.opened, closed: growth.closed, ceiling },
823
+ };
824
+ }
825
+
826
+ /** Rows per page of the trailing-day read: the REST maximum. */
827
+ export const NET_GROWTH_PER_PAGE = 100;
828
+
829
+ /**
830
+ * Pages the trailing-day read walks before it gives up as UNMEASURED.
831
+ *
832
+ * 1,000 issues and pull requests touched in a day is several times anything
833
+ * this repository has seen, and the read runs inside a PreToolUse hook. A
834
+ * walk that hits the bound reports that it did not finish rather than
835
+ * returning the count it had, because a partial count is a wrong count — it
836
+ * can be missing opens as easily as closes.
837
+ */
838
+ export const NET_GROWTH_MAX_PAGES = 10;
839
+
840
+ function unmeasuredGrowth(why: string): NetGrowthReading {
841
+ return { reading: "UNMEASURED", why };
842
+ }
843
+
844
+ /** A thrown value as a bounded sentence fragment, for an UNMEASURED `why`. */
845
+ function errorText(e: unknown): string {
846
+ return (e instanceof Error ? e.message : String(e)).slice(0, 200);
847
+ }
848
+
849
+ /**
850
+ * Count the issues opened and closed in the trailing `RUN_WINDOW_MS` (#2086).
851
+ *
852
+ * One `listForRepo` walk with `state: "all"` and `since` at the window's
853
+ * start. `since` filters on `updated_at`, and both opening and closing an
854
+ * issue update it, so every row that can count is inside the walk; rows
855
+ * merely touched in the window are read and counted as neither.
856
+ *
857
+ * - **Pull requests are not issues.** The endpoint returns them as issues and
858
+ * every one carries a `pull_request` key — `listOpenIssues` drops them for
859
+ * the same reason.
860
+ * - **Opened** is every issue created in the window, by anyone. Counting a
861
+ * stranger's issue can only push the cap DOWN.
862
+ * - **Closed** is an issue closed in the window that `closedIssueCounts`
863
+ * accepts: closed as completed, opened by somebody who can merge. On a
864
+ * public repository anyone can open an issue and close it themselves, and
865
+ * a close that counted would be a stranger raising our cap.
866
+ *
867
+ * A page that is not a list, a row without a readable `created_at`, or a walk
868
+ * that has not finished at `maxPages` is UNMEASURED, never a partial count.
869
+ */
870
+ export async function countNetGrowth(
871
+ client: GitHubClient,
872
+ repoSlug: string,
873
+ nowMs: number,
874
+ maxPages: number = NET_GROWTH_MAX_PAGES,
875
+ ): Promise<NetGrowthReading> {
876
+ const { owner, repo } = parseOwnerRepo(repoSlug);
877
+ const from = nowMs - RUN_WINDOW_MS;
878
+ const since = new Date(from).toISOString();
879
+ let opened = 0;
880
+ let closed = 0;
881
+ for (let page = 1; page <= maxPages; page++) {
882
+ const response = await client.rest.issues.listForRepo({
883
+ owner,
884
+ repo,
885
+ state: "all",
886
+ since,
887
+ per_page: NET_GROWTH_PER_PAGE,
888
+ page,
889
+ });
890
+ const rows: unknown = response?.data;
891
+ if (!Array.isArray(rows)) {
892
+ return unmeasuredGrowth(`page ${page} of ${repoSlug}'s trailing-day issues was not a list`);
893
+ }
894
+ for (const row of rows) {
895
+ if (row === null || typeof row !== "object") {
896
+ return unmeasuredGrowth(`page ${page} of ${repoSlug}'s trailing-day issues held a malformed row`);
897
+ }
898
+ const r = row as Record<string, unknown>;
899
+ if (r.pull_request !== undefined) continue;
900
+ const created = typeof r.created_at === "string" ? Date.parse(r.created_at) : Number.NaN;
901
+ if (!Number.isFinite(created)) {
902
+ return unmeasuredGrowth(`issue ${String(r.number)} on ${repoSlug} has no readable created_at`);
903
+ }
904
+ if (created >= from) opened += 1;
905
+ const closedAt = r.state === "closed" && typeof r.closed_at === "string" ? Date.parse(r.closed_at) : Number.NaN;
906
+ if (
907
+ Number.isFinite(closedAt) &&
908
+ closedAt >= from &&
909
+ closedIssueCounts({
910
+ state_reason: typeof r.state_reason === "string" ? r.state_reason : null,
911
+ author_association: typeof r.author_association === "string" ? r.author_association : "",
912
+ })
913
+ ) {
914
+ closed += 1;
915
+ }
916
+ }
917
+ if (rows.length < NET_GROWTH_PER_PAGE) return { reading: "MEASURED", opened, closed };
918
+ }
919
+ return unmeasuredGrowth(
920
+ `more than ${maxPages * NET_GROWTH_PER_PAGE} issues and pull requests on ${repoSlug} changed in the ` +
921
+ "trailing day, so the count was not finished",
922
+ );
923
+ }
924
+
925
+ /**
926
+ * The live trailing-day reading for the checkout at `projectRoot` (#2086).
927
+ *
928
+ * The same route the dedupe corpus takes — the repository slug from
929
+ * `resolveRepoSlug`, an Octokit client from the environment's token, the
930
+ * `OPEN_ISSUE_TIMEOUT_MS` ceiling — so a session that can read its tracker
931
+ * for one can read it for the other. `connect` is injectable so a test can
932
+ * hand in a client that lives in memory.
933
+ *
934
+ * Every failure is UNMEASURED with its reason: no slug, no token, a 401, a
935
+ * timeout, a walk that did not finish. That is the fail-closed direction —
936
+ * `netGrowthCeiling` gives an unread count the ship-mode cap.
937
+ */
938
+ export async function readNetGrowth(
939
+ projectRoot: string,
940
+ nowMs: number,
941
+ connect: () => GitHubClient = createGitHubClient,
942
+ ): Promise<NetGrowthReading> {
943
+ try {
944
+ const slug = resolveRepoSlug({ projectRoot }).slug;
945
+ if (slug === null) return unmeasuredGrowth("no repository slug could be resolved for this checkout");
946
+ return await withTimeout(countNetGrowth(connect(), slug, nowMs), OPEN_ISSUE_TIMEOUT_MS);
947
+ } catch (e) {
948
+ return unmeasuredGrowth(`the trailing day's issues could not be read (${errorText(e)})`);
413
949
  }
414
950
  }
415
951
 
952
+ /**
953
+ * The sentence a cap refusal carries about what set the cap (#2086).
954
+ *
955
+ * `null` where the ceiling was never consulted, so a harness-mode refusal
956
+ * reads exactly as it did before. The word UNMEASURED is spelled out: an
957
+ * unread count that read like a measured one would be the Silent Default
958
+ * Substitution `.claude/rules/config-access.md` names.
959
+ */
960
+ export function netGrowthSentence(basis: NetGrowthBasis | null | undefined): string | null {
961
+ // `undefined` too: a ledger row written before the column existed carries
962
+ // none, and that row is a refusal with nothing to say about the ceiling.
963
+ if (basis === null || basis === undefined) return null;
964
+ const window = `${RUN_WINDOW_MS / 3_600_000}h`;
965
+ if (basis.reading === "UNMEASURED") {
966
+ return (
967
+ `Whether the repository closed as many issues as it opened in the last ${window} is UNMEASURED ` +
968
+ `(${basis.why}), so the net-growth ceiling of ${NET_GROWTH_CEILING} does not apply and the cap is ` +
969
+ "the ship-mode one (ADR-016)."
970
+ );
971
+ }
972
+ const counts = `The repository opened ${basis.opened} and closed ${basis.closed} issue(s) in the last ${window}`;
973
+ return basis.ceiling
974
+ ? `${counts}, so the net-growth ceiling of ${NET_GROWTH_CEILING} applies (ADR-016).`
975
+ : `${counts}: opening outran closing, so the net-growth ceiling of ${NET_GROWTH_CEILING} does not ` +
976
+ "apply and the cap is the ship-mode one (ADR-016).";
977
+ }
978
+
416
979
  /**
417
980
  * How far back the cap counts.
418
981
  *
@@ -882,19 +1445,33 @@ export function overCapReason(
882
1445
  already: number,
883
1446
  target: CommentTarget,
884
1447
  cap: number,
1448
+ /**
1449
+ * What set the cap (#2086). Required, for the reason `cap` is: a site that
1450
+ * forgot it would refuse without saying whether the ceiling applied.
1451
+ * `null` where the ceiling was never consulted.
1452
+ */
1453
+ growth: NetGrowthBasis | null,
885
1454
  ): string {
1455
+ const basis = netGrowthSentence(growth);
886
1456
  return [
887
1457
  `this run has already filed ${already} issue(s) in the last ${RUN_WINDOW_MS / 3_600_000}h, and the cap is ` +
888
1458
  `${cap}. The overflow is a comment.`,
1459
+ ...(basis === null ? [] : ["", ` ${basis}`]),
889
1460
  "",
890
1461
  ` ${commentTargetSentence(target)}`,
891
1462
  "",
892
1463
  ` run: ${run}`,
893
1464
  "",
894
- " There is no argument against this and no label that waives it. It is a count, not a",
895
- " judgement about your finding, which may well be a good one — the cap exists because a",
1465
+ " There is no argument against this and no label waives it by argument. It is a count, not",
1466
+ " a judgement about your finding, which may well be a good one — the cap exists because a",
896
1467
  " per-finding judgement drifts and a count does not. If several findings belong on the",
897
1468
  " tracker, they are one issue naming every instance, not several.",
1469
+ "",
1470
+ " Two routes exist and neither is an argument. A title a MERGED plan names is exempt,",
1471
+ " because somebody had to merge the plan. Work the project has itself declared to be in",
1472
+ " its work queue gets a HIGHER ceiling — still counted, still reserved, still finite, and",
1473
+ " the number above is already that ceiling if this filing qualified. Both are recorded on",
1474
+ " the row.",
898
1475
  ].join("\n");
899
1476
  }
900
1477
 
@@ -1035,6 +1612,32 @@ export type CommentExemption = keyof typeof COMMENT_EXEMPTIONS;
1035
1612
  */
1036
1613
  export const EXEMPTION_PREFIX = "Cannot be a comment:";
1037
1614
 
1615
+ /**
1616
+ * The `MALFORMED` sentence, naming every section the body is short (#1741).
1617
+ *
1618
+ * Composed here rather than at the refusal site so the refusal carries one
1619
+ * string the suite can assert on, and so the list comes from
1620
+ * `requiredSections` rather than being retyped — a refusal that names a
1621
+ * different set of sections from the one that produced it is a refusal an
1622
+ * agent cannot satisfy.
1623
+ *
1624
+ * **It names the headings, not the field ids.** The heading is what an agent
1625
+ * has to type into the body; an id is a fact about a YAML file they are not
1626
+ * editing.
1627
+ */
1628
+ export function malformedReason(missing: readonly string[]): string {
1629
+ const both = requiredSections("everyday-work").map(headingFor);
1630
+ return (
1631
+ `the body is short ${missing.length} section(s) every issue needs: ${missing.join(", ")}. ` +
1632
+ `An issue naming no files cannot be checked against rule 2 and cannot be scanned for the ` +
1633
+ `file overlaps that put four agents on one file, and an issue with no "how we will know" ` +
1634
+ `is one nobody can close on evidence. The floor is ${both.join(", ")} — spec work also ` +
1635
+ `needs ${headingFor(requiredSections("spec-work").find(s => s.id === "criteria")!)}, ` +
1636
+ `which the form asks for and this gate does not, because a consumer reporting a problem ` +
1637
+ `upstream cannot know a criterion id`
1638
+ );
1639
+ }
1640
+
1038
1641
  /**
1039
1642
  * Which declaration a filing makes, or `null` for none.
1040
1643
  *
@@ -1225,6 +1828,12 @@ export interface FilingAttempt {
1225
1828
  * counted later is worth more than a refusal nobody can audit.
1226
1829
  */
1227
1830
  repeatedValueFlag: boolean;
1831
+ /**
1832
+ * The clause invokes `gh` directly, with no wrapper and no assignment
1833
+ * prefix — `directGhInvocation`. The QUEUE CEILING reads this and nothing
1834
+ * else does (#1963, review round 3).
1835
+ */
1836
+ directGh: boolean;
1228
1837
  }
1229
1838
 
1230
1839
  /**
@@ -1293,6 +1902,35 @@ export interface FilingLedgerRow {
1293
1902
  * indistinguishable from the cap not having been applied.
1294
1903
  */
1295
1904
  plannedBy?: string | null;
1905
+ /**
1906
+ * The configured work-queue label that raised this filing's ceiling, or
1907
+ * `null` for one the queue does not claim (#1961).
1908
+ *
1909
+ * **A raise, never an exemption** — the row is written for every queued
1910
+ * clause precisely because those clauses ARE counted. `plannedBy` marks a
1911
+ * filing the cap never counted; this one marks a filing the cap counted
1912
+ * against a bigger number.
1913
+ *
1914
+ * On EVERY row for the same reason `plannedBy` is: *how much of what we
1915
+ * file is engine work* is a ratio, and a column present only where the
1916
+ * raise fired supplies a numerator and no denominator. It is also the
1917
+ * audit trail for the raise — it names WHICH label, so a reader can check
1918
+ * that label against the tree's `board.queueLabel` rather than taking the
1919
+ * raise on trust.
1920
+ */
1921
+ queuedBy?: string | null;
1922
+ /**
1923
+ * What set this run's cap (#2086, ADR-016): the repository's trailing-day
1924
+ * opened and closed counts and whether the net-growth ceiling applied, or
1925
+ * the UNMEASURED reading with why.
1926
+ *
1927
+ * `null` where the ceiling was never consulted — harness mode, an explicit
1928
+ * `board.filingsPerRun`, an unreadable config — and absent on every row
1929
+ * written before this existed and on rows from writers that cap nothing.
1930
+ * On EVERY row of a direct-ship command, admitted or refused, for the
1931
+ * reason `queuedBy` is: *how often does the ceiling apply* is a ratio.
1932
+ */
1933
+ netGrowth?: NetGrowthBasis | null;
1296
1934
  at: string;
1297
1935
  /**
1298
1936
  * This row, told apart from every other row on a shared ledger (#1318).
@@ -1585,7 +2223,135 @@ export function ghRepoTarget(value: string): string | null {
1585
2223
  * corpus, finds nothing, and the filing is allowed. `--repo` IS read,
1586
2224
  * because it is in the clause and costs one more query.
1587
2225
  */
2226
+ /**
2227
+ * A `title:` / `body:` argument inside a GraphQL document, resolved.
2228
+ *
2229
+ * Two spellings, because both are ordinary. A literal — `title: "…"` — is
2230
+ * read out of the document. A variable — `title: $title` — is looked up in
2231
+ * the fields the clause passes alongside the query, which is the form
2232
+ * `gh`'s own documentation recommends because it avoids escaping quotes by
2233
+ * hand. ai-review round 1 of #1805: reading only the literal left the
2234
+ * idiomatic form resolving to an empty title, counted as a filing and
2235
+ * compared against nothing.
2236
+ *
2237
+ * Crude on purpose beyond those two: the alternative is a GraphQL parser,
2238
+ * and what the gate needs is the two strings it compares and scans. A
2239
+ * document this cannot read yields `null`, the attempt resolves empty, and
2240
+ * the gate lands on its existing "names no symbol" arm — the same place an
2241
+ * unreadable `--body-file` already lands.
2242
+ */
2243
+ function graphqlArgument(doc: string, name: string, vars: Map<string, string>): string | null {
2244
+ const m = new RegExp(`\\b${name}\\s*:\\s*(?:"((?:[^"\\\\]|\\\\.)*)"|\\$(\\w+))`).exec(doc);
2245
+ if (m === null) return null;
2246
+ if (m[2] !== undefined) return vars.get(m[2]) ?? null;
2247
+ return m[1].replace(/\\(.)/g, "$1");
2248
+ }
2249
+
2250
+ /**
2251
+ * The tracker a leading `GH_REPO=` assignment targets, or `null`.
2252
+ *
2253
+ * A clause may be prefixed with `VAR=value` assignments that apply to that
2254
+ * command alone — `GH_REPO=o/n gh issue create …` — and `gh` reads `GH_REPO`
2255
+ * with exactly the authority of `--repo`. A reading that saw only the flag
2256
+ * was `.claude/rules/checks-must-be-able-to-fail.md`'s second shape, *a
2257
+ * detector narrower than what it detects*: the clause was adjudicated, and
2258
+ * only its target was wrong.
2259
+ *
2260
+ * **Leading assignments only, and that is the shell's own rule.** `VAR=value`
2261
+ * is a command prefix; the same text after the program name is an ARGUMENT,
2262
+ * not an assignment. So this stops at the first token that is not one, which
2263
+ * is what makes `gh issue create --title "GH_REPO=o/n"` not a retarget.
2264
+ *
2265
+ * **The ambient `process.env.GH_REPO` is NOT read, and the reason is a false
2266
+ * refusal.** The hook's own environment is not a property of the clause: a
2267
+ * session that legitimately exported its own slug would have every filing
2268
+ * read as cross-repo and lose the queue ceiling for work that is plainly in
2269
+ * this project's queue. The per-clause prefix is the thing a filer writes to
2270
+ * retarget one command, and it is the thing this reads.
2271
+ */
2272
+ export function envRepo(tokens: string[]): string | null {
2273
+ let found: string | null = null;
2274
+ for (const token of tokens) {
2275
+ const m = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/s.exec(token);
2276
+ // The first non-assignment token is the program; everything past it is
2277
+ // an argument and no longer an assignment.
2278
+ if (m === null) break;
2279
+ // Last-wins among the prefix, which is what the shell does.
2280
+ if (m[1] === "GH_REPO") found = m[2] === "" ? null : m[2]!;
2281
+ }
2282
+ return found;
2283
+ }
2284
+
2285
+ /**
2286
+ * Is this clause a PLAIN `gh` invocation — `gh …` or `/path/to/gh …`?
2287
+ *
2288
+ * **Round 3 of PR #1963's review, and a re-scope rather than a repair.**
2289
+ * Rounds 1, 2 and 3 each found one more spelling by which a clause can
2290
+ * retarget itself: `--repo`, then `GH_REPO=`, then `env GH_REPO=` and
2291
+ * `command`. `.claude/rules/checks-must-be-able-to-fail.md` names this —
2292
+ * *three rounds, three sites, one rule* — and AGENTS.md rule 5 says to stop
2293
+ * repairing at the third and re-scope. A wrapper ALLOWLIST is the fourth
2294
+ * round pre-booked: `nohup`, `stdbuf`, `timeout`, `setsid`, `doas` and
2295
+ * whatever is next.
2296
+ *
2297
+ * So the queue ceiling asks a question with ONE right answer instead: is
2298
+ * the program the first thing in the clause? Everything else — a wrapper, an
2299
+ * assignment prefix, an interpreter, anything this file's parser cannot
2300
+ * vouch for — is UNMEASURED for the queue route and gets the ordinary cap.
2301
+ *
2302
+ * **This is a whitelist of one shape, so there is no list to extend.** It
2303
+ * fails toward REFUSING the raise, never toward granting it, and the cost
2304
+ * is a false non-raise: a legitimate `env FOO=1 gh issue create --label
2305
+ * engine` loses the ceiling and keeps the ordinary allowance. That is a
2306
+ * filing refused a bigger number, not a filing refused.
2307
+ *
2308
+ * **It governs the CEILING only, and nothing else in this file.** Every
2309
+ * other reading — the dedupe, the claim check, the cap itself — still sees
2310
+ * a wrapped clause exactly as before. `lib/issue-create-override.ts`'s
2311
+ * header explains why the phase lock does not chase wrappers, and that
2312
+ * reasoning is unchanged; what is different here is that the decision being
2313
+ * guarded is *how much allowance you get*, which is the filer's own
2314
+ * interest, and the honest answer to an unreadable invocation is the
2315
+ * smaller number.
2316
+ */
2317
+ export function directGhInvocation(tokens: string[]): boolean {
2318
+ const first = tokens[0];
2319
+ if (first === undefined) return false;
2320
+ return first.replace(/^.*\//, "") === "gh";
2321
+ }
2322
+
1588
2323
  export function resolveFiling(tokens: string[]): FilingAttempt {
2324
+ const doc = graphqlDocument(tokens);
2325
+ if (doc !== null) {
2326
+ const vars = graphqlVariables(tokens) ?? new Map<string, string>();
2327
+ return {
2328
+ title: graphqlArgument(doc, "title", vars) ?? "",
2329
+ body: graphqlArgument(doc, "body", vars) ?? "",
2330
+ labels: [],
2331
+ bodyFile: null,
2332
+ // A createIssue carries `repositoryId`, an opaque node id rather than
2333
+ // a slug, so this is honestly unknown rather than guessed. `null` is
2334
+ // what a `gh issue create` with no `--repo` already resolves to.
2335
+ repo: null,
2336
+ repeatedValueFlag: false,
2337
+ directGh: directGhInvocation(tokens),
2338
+ };
2339
+ }
2340
+ const apiRest = apiRestFields(tokens);
2341
+ if (apiRest !== null) {
2342
+ return {
2343
+ title: apiRest.get("title") ?? "",
2344
+ body: apiRest.get("body") ?? "",
2345
+ labels: (apiRest.get("labels") ?? "")
2346
+ .split(",")
2347
+ .map(l => l.trim())
2348
+ .filter(l => l !== ""),
2349
+ bodyFile: null,
2350
+ repo: apiFilingRepo(tokens),
2351
+ repeatedValueFlag: false,
2352
+ directGh: directGhInvocation(tokens),
2353
+ };
2354
+ }
1589
2355
  const titles = flagValues(tokens, TITLE_FLAG);
1590
2356
  const bodies = flagValues(tokens, BODY_FLAG);
1591
2357
  const bodyFiles = flagValues(tokens, BODY_FILE_FLAG);
@@ -1598,20 +2364,81 @@ export function resolveFiling(tokens: string[]): FilingAttempt {
1598
2364
  // same `asGhWould` reading as the title and the body — a repeated
1599
2365
  // `--body-file` overrides rather than accumulating.
1600
2366
  bodyFile: bodyFiles.length > 0 ? asGhWould(bodyFiles) : null,
1601
- repo: repos.length > 0 ? asGhWould(repos) : null,
2367
+ // **`--repo`, else a leading `GH_REPO=` assignment** — round 2 of the
2368
+ // security review of PR #1963. `gh` reads the environment variable with
2369
+ // exactly the authority of the flag, so `GH_REPO=other/x gh issue
2370
+ // create …` targets another tracker while this field read `null`,
2371
+ // meaning *this project's own*. Measured: the clause is recognised and
2372
+ // adjudicated, and only the target was wrong.
2373
+ //
2374
+ // **Fixed here rather than at the one caller that found it.** The
2375
+ // reviewer pointed at `queueCarveOut`, where a wrong `null` borrowed
2376
+ // this project's queue ceiling. It is the same wrong answer everywhere
2377
+ // `repo` is read: the dedupe corpus compares the filing against this
2378
+ // repository's open issues, and `targetFor` composes a comment target
2379
+ // on this repository's PR. One field, one reading, so a second consumer
2380
+ // cannot be fixed and a third left behind.
2381
+ repo: repos.length > 0 ? asGhWould(repos) : envRepo(tokens),
1602
2382
  repeatedValueFlag: titles.length > 1 || bodies.length > 1 || bodyFiles.length > 1,
2383
+ directGh: directGhInvocation(tokens),
1603
2384
  };
1604
2385
  }
1605
2386
 
2387
+ /**
2388
+ * Does this command set `GH_REPO` ANYWHERE in it?
2389
+ *
2390
+ * **Round 5 of PR #1963's review, and a change of SCOPE rather than a sixth
2391
+ * spelling.** Rounds 1-3 were all one axis — a clause retargeting *itself* —
2392
+ * and `directGhInvocation` answered the whole axis. This is a different one.
2393
+ * `clauses()` splits on `&&`, `;` and `|` before anything tokenizes, so in
2394
+ *
2395
+ * export GH_REPO=other/x && gh issue create --label engine …
2396
+ *
2397
+ * the adjudicated clause is the SECOND. It contains no assignment, it begins
2398
+ * with `gh`, and it is byte-identical to an honest local filing — while the
2399
+ * shell has already put `GH_REPO` in the environment `gh` reads. Measured
2400
+ * before the fix: `repo=null, directGh=true`, the same reading a plain
2401
+ * `gh issue create` produces.
2402
+ *
2403
+ * **`hooks/lib/utils.ts` already found and answered this**, for
2404
+ * `IssueCloseGuard` (#143), and its comment is the rule adopted here: *"Tested
2405
+ * against the WHOLE command, not the closing segment. The first version
2406
+ * checked the segment and so caught the inline-prefix form while missing the
2407
+ * natural one … A control that only covers the awkward spelling is not a
2408
+ * control."* A per-clause reading cannot see an environment that outlives the
2409
+ * clause, so the question has to be asked of the whole string.
2410
+ *
2411
+ * **It fails toward refusing the raise.** A `--body "GH_REPO=x"` costs a
2412
+ * legitimate filing its bigger ceiling and nothing else: a smaller allowance,
2413
+ * never a blocked filing. The opposite error hands this project's queue
2414
+ * ceiling to a command aimed at somebody else's tracker, which is the
2415
+ * authorization shape rounds 2 and 3 were closing.
2416
+ */
2417
+ export function ambientRetarget(cmd: string): boolean {
2418
+ return /\bGH_REPO=/.test(cmd);
2419
+ }
2420
+
1606
2421
  /**
1607
2422
  * Every `gh issue create` in this command, one entry per clause.
1608
2423
  *
1609
2424
  * Per clause and not per command, for the reason `verifyPhaseRefusal` is:
1610
2425
  * `gh issue comment … && gh issue create …` is a create, and a reading over
1611
2426
  * the whole string lets the first half excuse the second.
2427
+ *
2428
+ * **One property is read from the whole command and not the clause**, and it
2429
+ * is `directGh` — see `ambientRetarget`. `directGh` means *an invocation this
2430
+ * file can vouch for*, and a sibling clause that exports `GH_REPO` is exactly
2431
+ * an invocation it cannot. Nothing else widens: the dedupe, the claim check
2432
+ * and the cap all still read the clause.
1612
2433
  */
1613
2434
  export function filingAttempts(cmd: string): FilingAttempt[] {
1614
- return clauses(cmd).filter(createsIssue).map(resolveFiling);
2435
+ const retargeted = ambientRetarget(cmd);
2436
+ return clauses(cmd)
2437
+ .filter(createsIssue)
2438
+ .map(tokens => {
2439
+ const attempt = resolveFiling(tokens);
2440
+ return retargeted ? { ...attempt, directGh: false } : attempt;
2441
+ });
1615
2442
  }
1616
2443
 
1617
2444
  /**
@@ -1903,6 +2730,39 @@ export async function adjudicateFiling(
1903
2730
  };
1904
2731
  }
1905
2732
 
2733
+ // ── it belongs on the tracker. is it READABLE by the things that read it? ──
2734
+ //
2735
+ // **#1741, and it is LAST for the reason every late stage here is last.**
2736
+ // Only an ALLOW reaches this line, so it can mask nothing: a duplicate is
2737
+ // still refused as DUPLICATE, an unreadable ledger is still UNMEASURED_CAP,
2738
+ // and a filing with no declaration still hears about the comment default
2739
+ // first. Placing a cheap string check ahead of those would convert every
2740
+ // one of them into "your body is short a heading", which is the mask
2741
+ // measured at 34 of 78 cases when `NO_CLAIM` was briefly moved first.
2742
+ //
2743
+ // **The floor is the EVERYDAY form, not the spec-work one.** The two forms
2744
+ // differ in exactly one field — `Criteria this serves`, which a consumer
2745
+ // reporting upstream cannot know — so the sections common to both are the
2746
+ // only ones this gate can demand without refusing a legitimate consumer
2747
+ // report. The spec-work form enforces its extra field where it belongs, on
2748
+ // the form. A gate that demanded it would be a second, stricter decider
2749
+ // sitting over the first.
2750
+ //
2751
+ // This is the half of #1741 that could not be built before the other two
2752
+ // consumers: `plan-issues --decompose` emitted two of the form's five
2753
+ // sections, so this check on the day it was written would have refused
2754
+ // every row of every decomposed plan. `test/issue-shape.test.ts`'s IS-31
2755
+ // is the standing proof that it no longer does.
2756
+ const malformed = missingSections(body, "everyday-work");
2757
+ if (malformed.length > 0) {
2758
+ return {
2759
+ ...base,
2760
+ outcome: "REFUSE",
2761
+ refusal: "MALFORMED",
2762
+ reason: malformedReason(malformed),
2763
+ };
2764
+ }
2765
+
1906
2766
  return {
1907
2767
  ...base,
1908
2768
  outcome: "ALLOW",
@@ -2546,6 +3406,20 @@ export async function filingGate(
2546
3406
  * every agent the power to write its own exemption.
2547
3407
  */
2548
3408
  readPlan?: PlanSource;
3409
+ /**
3410
+ * The committed config the cap is read from (#1964, SC-2753). Same rule
3411
+ * as `readPlan`: injectable so a test can hand it a fixture, and the
3412
+ * default — `origin/main`, never the working tree — is the only one that
3413
+ * ships. A caller passing the working tree here reopens #1964.
3414
+ */
3415
+ readConfigAt?: CommittedFiles;
3416
+ /**
3417
+ * The repository's trailing-day opened and closed issue counts, for the
3418
+ * net-growth ceiling (#2086). Injectable for the reason `readExisting`
3419
+ * is — the live one, `readNetGrowth`, talks to GitHub. Only called when
3420
+ * the ceiling can apply, so a harness-mode filing pays no read.
3421
+ */
3422
+ readGrowth?: (projectRoot: string, nowMs: number) => Promise<NetGrowthReading>;
2549
3423
  },
2550
3424
  ): Promise<FilingGateReading> {
2551
3425
  const attempts = filingAttempts(cmd);
@@ -2553,14 +3427,61 @@ export async function filingGate(
2553
3427
 
2554
3428
  const at = options.now ?? new Date().toISOString();
2555
3429
  const read = options.readExisting ?? openFindings;
2556
- const planSource = options.readPlan ?? gitSource(options.projectRoot);
3430
+ // **Where the command ran, which is not necessarily where the session
3431
+ // lives** (#1833). `options.projectRoot` is the caller's directory — for
3432
+ // the live caller, `hooks/VerifyPhaseLock.hook.ts`, that is the session's
3433
+ // launch directory. Every stage below reads this instead, because every
3434
+ // one of them is asking about the checkout the filing was made FROM: its
3435
+ // config, its tracker, its branch's PR, its run id, and the plans on its
3436
+ // `origin/main`. See `filingDirectory` for why the answer is in the
3437
+ // command text and for the two cases it cannot resolve.
3438
+ const root = filingDirectory(cmd, options.projectRoot);
3439
+ // A relative `--body-file` is relative to the command's directory too, and
3440
+ // this is the one place that can say so. `"-"` is stdin and has no path to
3441
+ // resolve; `readBodyFile` is what decides that, so it stays its decision.
3442
+ const readBody = (path: string): string | null =>
3443
+ readBodyFile(path === "-" ? path : resolve(root, path));
3444
+ // ONE reading of the remote's main for the whole command, handed to both
3445
+ // readers below. Two live readings could straddle a merge and judge the
3446
+ // plan exemption and the cap against two commits (review of #2140).
3447
+ let remoteMain: RemoteMain | undefined;
3448
+ const anchor = (): RemoteMain => (remoteMain ??= remoteMainCommit(root));
3449
+ const planSource = options.readPlan ?? gitSource(root, anchor);
3450
+ // **The cap's config is the COMMITTED config, never the working tree**
3451
+ // (#1964, SC-2753). `ship.mode`, `board.filingsPerRun` and `board.queueLabel`
3452
+ // each move the cap, and read from the working tree any one of them let an
3453
+ // agent raise its own allowance by editing its own checkout. Read from the
3454
+ // commit the REMOTE's `main` names (#2095), never the local `origin/main`
3455
+ // ref, which an agent can forge with `git update-ref`. An unreadable commit
3456
+ // is the STRICT cap and an UNMEASURED note, never a fall-through to disk.
3457
+ const committed = readCommittedConfig(options.readConfigAt ?? gitCommittedFiles(root, anchor()));
2557
3458
  // The run's allowance, resolved ONCE per command. Per clause would let two
2558
3459
  // clauses of one command be adjudicated against two different caps if the
2559
3460
  // config moved underneath them, which is the shape `readFor` is cached to
2560
3461
  // avoid one line below. A config that cannot be read resolves to the
2561
- // STRICT cap — `filingsPerRunFor`.
2562
- const allowance = filingsPerRunFor(() => tryLoadRungateConfig(options.projectRoot));
2563
- const cap = allowance.cap;
3462
+ // STRICT cap — `filingsPerRunFor`, through `committedFilingCap`.
3463
+ const allowance = committedFilingCap(committed);
3464
+ // The net-growth ceiling (ADR-016), resolved ONCE per command for the same
3465
+ // reason. `netGrowthCeiling` is the one decider — it alone decides whether
3466
+ // the count is read at all — and every cap consumer below reads `cap`, and
3467
+ // every refusal and row reads `growth.basis`.
3468
+ const readGrowth = options.readGrowth ?? readNetGrowth;
3469
+ const growth = await netGrowthCeiling(allowance, () => readGrowth(root, Date.parse(at)));
3470
+ const cap = growth.cap;
3471
+ // The work queue's name, resolved ONCE per command for the same reason the
3472
+ // allowance is: per clause would let two clauses of one command be
3473
+ // adjudicated against two different queues if the config moved underneath
3474
+ // them. A tree that declares none resolves to `null`, which raises
3475
+ // nothing — `queueLabelFor`.
3476
+ //
3477
+ // No note when it is absent. A config the gate cannot PARSE already earns
3478
+ // `unreadableShipPolicyNote` below, from `filingsPerRunFor`, which catches
3479
+ // the same throw from the same file; a second note over one fact would be
3480
+ // two voices on one repair.
3481
+ const queueLabel = queueLabelFor(() => queueLabelIn(committedConfig(committed)));
3482
+ // The waiver's name, once per command for the same reason (SC-2735). `null`
3483
+ // waives nothing — `filingOverrideLabelFor`.
3484
+ const overrideLabel = filingOverrideLabelFor(() => readFilingOverrideLabel(root));
2564
3485
  // Read once per TARGET TRACKER, not once per command and not once per
2565
3486
  // clause. Once per clause would adjudicate two creates against two
2566
3487
  // different snapshots; once per command would adjudicate a `--repo other/x`
@@ -2572,7 +3493,7 @@ export async function filingGate(
2572
3493
  const key = repo ?? "";
2573
3494
  const hit = cached.get(key);
2574
3495
  if (hit !== undefined) return hit;
2575
- const started = read(options.projectRoot, repo);
3496
+ const started = read(root, repo);
2576
3497
  cached.set(key, started);
2577
3498
  return started;
2578
3499
  };
@@ -2588,7 +3509,7 @@ export async function filingGate(
2588
3509
  const key = repo ?? "";
2589
3510
  const hit = targets.get(key);
2590
3511
  if (hit !== undefined) return hit;
2591
- const started = readTarget(options.projectRoot, repo);
3512
+ const started = readTarget(root, repo);
2592
3513
  targets.set(key, started);
2593
3514
  return started;
2594
3515
  };
@@ -2602,7 +3523,15 @@ export async function filingGate(
2602
3523
  // exist yet there, and the ordering is deliberate: this is the first note a
2603
3524
  // reader sees, because it is the one that explains the NUMBER every later
2604
3525
  // refusal quotes.
2605
- if (allowance.unreadable) notes.push(unreadableShipPolicyNote(cap));
3526
+ if (allowance.unreadable) {
3527
+ notes.push(
3528
+ allowance.committedUnmeasured !== undefined
3529
+ ? committedConfigUnmeasuredNote(cap, allowance.committedUnmeasured)
3530
+ : unreadableShipPolicyNote(cap, allowance.unreadableSource),
3531
+ );
3532
+ }
3533
+ /** The queue-ceiling note is one fact about the project, said once. */
3534
+ let notedQueueCeiling = false;
2606
3535
 
2607
3536
  // One batch per command, so every row of one adjudication shares it and the
2608
3537
  // clause index separates them — `CandidateRecord.key`'s scheme exactly.
@@ -2670,7 +3599,7 @@ export async function filingGate(
2670
3599
  // directory that simply has no origin, which is an answer and buckets.
2671
3600
  // Without the split the timeout silently re-keys a real checkout into the
2672
3601
  // shared allowance, which is the denominator changing underneath the count.
2673
- const reading = runIdFor(options.projectRoot, options.readRemote);
3602
+ const reading = runIdFor(root, options.readRemote);
2674
3603
  const run = reading.run ?? NON_CHECKOUT_RUN;
2675
3604
  const nowMs = Date.parse(at);
2676
3605
  const uncountable = priorRows === null || reading.run === null;
@@ -2691,7 +3620,7 @@ export async function filingGate(
2691
3620
  const read1 = await adjudicateFiling(
2692
3621
  attempt,
2693
3622
  () => readFor(attempt.repo),
2694
- readBodyFile,
3623
+ readBody,
2695
3624
  () => targetFor(attempt.repo),
2696
3625
  );
2697
3626
  // The in-run class check, applied to anything the per-filing stages did
@@ -2700,7 +3629,7 @@ export async function filingGate(
2700
3629
  // tracker is no reason to let one command file a class twice. The note
2701
3630
  // below is keyed off `read1` rather than `verdict` so the unreadable
2702
3631
  // tracker is still said out loud when that happens.
2703
- const { finding } = filingFinding(attempt);
3632
+ const { finding } = filingFinding(attempt, readBody);
2704
3633
  // **The cap is applied before anything READS THE TRACKER'S ANSWER, and
2705
3634
  // it converts an UNMEASURED.** Every other
2706
3635
  // UNMEASURED arm in this file allows, which is right for a reading about
@@ -2746,7 +3675,7 @@ export async function filingGate(
2746
3675
  "One issue per finding class per run, never per instance: fold this instance into " +
2747
3676
  "that filing and say *every instance* in it, rather than filing the second one.",
2748
3677
  };
2749
- const labelled = attempt.labels.includes(FILING_OVERRIDE_LABEL);
3678
+ const labelled = overrideLabel !== null && attempt.labels.includes(overrideLabel);
2750
3679
  const prior = priorRows === null ? null : priorRefusalFor(attempt.title, priorRows);
2751
3680
  // **An override waives A REFUSAL, and the refusal need not be this
2752
3681
  // adjudication's** (#1536). `verdict.outcome === "REFUSE" && labelled`
@@ -2865,7 +3794,23 @@ export async function filingGate(
2865
3794
  // an open issue is still `DUPLICATE`, and one that declares no reason is
2866
3795
  // still `COMMENT_INSTEAD`; `read2` is untouched above.
2867
3796
  const planned = plannedFiling(attempt.title, planSource);
2868
- const capped = uncountable || (spent >= cap && !planned.planned);
3797
+ // **The cap's third route: work the project's own queue claims** (#1961).
3798
+ //
3799
+ // **A raised CEILING, not an exemption** — see `QUEUE_FILINGS_PER_RUN`
3800
+ // for why the first spelling of this was an authorization bypass. A
3801
+ // queued clause is counted, reserved and raced exactly like every other
3802
+ // one; the only thing it gets is a bigger number, and `capForClause` is
3803
+ // the one place that decides which number. Both cap sites read it.
3804
+ const queuedBy = queueCarveOut(attempt.labels, queueLabel, attempt.repo, attempt.directGh);
3805
+ const clauseCap = capForClause(queuedBy, cap);
3806
+ // Said once per command even when several clauses qualify: the note is
3807
+ // about the project's declaration, which is one fact, and repeating it
3808
+ // per clause is how a note becomes something a reader skips.
3809
+ if (queuedBy !== null && clauseCap > cap && !notedQueueCeiling) {
3810
+ notedQueueCeiling = true;
3811
+ notes.push(queueCeilingNote(queuedBy, clauseCap, cap));
3812
+ }
3813
+ const capped = uncountable || (spent >= clauseCap && !planned.planned);
2869
3814
  const verdict: FilingAdjudication =
2870
3815
  wouldEmit && capped
2871
3816
  ? {
@@ -2874,7 +3819,7 @@ export async function filingGate(
2874
3819
  refusal: uncountable ? "UNMEASURED_CAP" : "OVER_CAP",
2875
3820
  reason: uncountable
2876
3821
  ? uncountableReason(await targetFor(attempt.repo))
2877
- : overCapReason(run, spent, await targetFor(attempt.repo), cap),
3822
+ : overCapReason(run, spent, await targetFor(attempt.repo), clauseCap, growth.basis),
2878
3823
  }
2879
3824
  : read2;
2880
3825
  const overridden = overrideOf(verdict);
@@ -2913,6 +3858,8 @@ export async function filingGate(
2913
3858
  refiledAfter: prior?.at ?? null,
2914
3859
  exemption: verdict.exemption,
2915
3860
  plannedBy: planned.planned ? `${planned.plan}:${planned.line}` : null,
3861
+ queuedBy,
3862
+ netGrowth: growth.basis,
2916
3863
  run,
2917
3864
  });
2918
3865
 
@@ -2958,18 +3905,45 @@ export async function filingGate(
2958
3905
  siblingTitles.set(String(index), attempt.title);
2959
3906
  }
2960
3907
 
2961
- if (verdict.outcome === "REFUSE" && !overridden) refusals.push(refusalMessage(verdict));
3908
+ if (verdict.outcome === "REFUSE" && !overridden) refusals.push(refusalMessage(verdict, overrideLabel));
2962
3909
  // `read1`, never `verdict`: a clause whose tracker could not be read AND
2963
3910
  // whose class a sibling already files is both facts at once, and the
2964
3911
  // conversion above keeps only the second. An UNMEASURED nobody sees is
2965
3912
  // the silent pass this file's header exists to prevent.
2966
3913
  if (read1.outcome === "UNMEASURED") notes.push(unmeasuredNote(read1));
2967
- if (overridden) notes.push(overrideNote(verdict, prior));
3914
+ if (overridden) notes.push(overrideNote(verdict, overrideLabel!, prior));
2968
3915
  // A re-draft that cleared the gate on its own is not refused and not
2969
3916
  // blocked — the gate does not get stricter here (#1536). It is SAID, so
2970
3917
  // the honest filer who labels the override and the filer who reworded
2971
3918
  // until it passed stop producing the same ledger.
2972
- else if (prior !== null && verdict.outcome !== "REFUSE") notes.push(refiledNote(attempt.title, prior));
3919
+ else if (prior !== null && verdict.outcome !== "REFUSE") notes.push(refiledNote(attempt.title, prior, overrideLabel));
3920
+
3921
+ // ── #1743: this body names a file an open issue already names ──────────
3922
+ //
3923
+ // **A NOTE, never a refusal.** `AGENTS.md` rule 2 already makes every
3924
+ // issue name its files and nothing read them, so two issues rewriting one
3925
+ // file both sit in the pickable set with nothing saying so. Measured over
3926
+ // the 20 milestone-less open issues on 2026-11-03: 16 declare a file, 10
3927
+ // pairs overlap, and four of them — #1407, #1425, #1585, #1355 — rewrite
3928
+ // the same one.
3929
+ //
3930
+ // A refusal here would be wrong twice. It would argue with every second
3931
+ // issue about a busy file, and it would be a reading about OTHER issues
3932
+ // deciding whether THIS one may exist. The gate's refusals are all about
3933
+ // the filing in hand.
3934
+ //
3935
+ // **Only on a clause that is actually filing**, and only on a MEASURED
3936
+ // corpus. A warning derived from a tracker nobody could read would be a
3937
+ // reading presented as a fact — `unmeasuredNote` above already says the
3938
+ // corpus was unreadable, and saying "no overlap" in the same breath is
3939
+ // the silent default `.claude/rules/config-access.md` names.
3940
+ if (cleared) {
3941
+ const corpus = await readFor(attempt.repo);
3942
+ if (corpus.reading === "MEASURED") {
3943
+ const note = overlapNote(finding.body, asIssueFiles(corpus.findings));
3944
+ if (note !== null) notes.push(note);
3945
+ }
3946
+ }
2973
3947
  }
2974
3948
 
2975
3949
  // ── A refusal blocks the COMMAND, and every clean clause is NAMED in the
@@ -3069,21 +4043,46 @@ export async function filingGate(
3069
4043
  // worse: it writes two rows per planned filing into the ledger the cap
3070
4044
  // is measured from, so `intentsInRun` would count planned work against
3071
4045
  // the population the number was calibrated on.
4046
+ // **`queuedBy` does NOT ride this line, and that is the security
4047
+ // review's finding** (#1963). A queued clause is in the cap's
4048
+ // accounting; it just has a bigger ceiling. Skipping the reservation
4049
+ // would leave the one route a filer can self-grant as the only route
4050
+ // with no race protection and no intent row — unlimited in a loop and
4051
+ // invisible to a parallel hook. It reserves with the rest, against
4052
+ // `capForClause`, so the number the stage re-decides against is the
4053
+ // number the pre-read used.
3072
4054
  if (row.plannedBy != null) continue;
3073
- const reading = reserveAllowance(row, run, { now: nowMs, append, readLedger: readAgain, cap });
4055
+ // The ceiling THIS row is judged against, which is not always the run's:
4056
+ // a queued row carries the raised one. **One local, read by the
4057
+ // reservation AND by every refusal below it** — round 4 of #1963 found
4058
+ // the second `capForClause` call drifting from the first, with
4059
+ // `unreservedCapReason` naming the run cap while the stage had already
4060
+ // decided against the raised one. Two expressions answering one question
4061
+ // are behaviourally one decider that can disagree
4062
+ // (`.claude/rules/checks-must-be-able-to-fail.md`).
4063
+ const rowCap = capForClause(row.queuedBy ?? null, cap);
4064
+ const reading = reserveAllowance(row, run, {
4065
+ now: nowMs,
4066
+ append,
4067
+ readLedger: readAgain,
4068
+ cap: rowCap,
4069
+ });
3074
4070
  if (reading.outcome === "WON") {
3075
4071
  reserved.push(reading.intent);
3076
4072
  continue;
3077
4073
  }
3078
4074
  const refusal = reading.outcome === "LOST" ? "OVER_CAP" : "UNMEASURED_CAP";
3079
4075
  const target = await targetFor(attempts[index].repo);
4076
+ // Every refusal names `rowCap` — the number the stage above actually
4077
+ // decided against. A refusal naming the wrong number sends its reader
4078
+ // to the wrong fact.
3080
4079
  const reason =
3081
4080
  reading.outcome === "LOST"
3082
- ? overCapReason(run, reading.already, target, cap)
4081
+ ? overCapReason(run, reading.already, target, rowCap, growth.basis)
3083
4082
  : reading.outcome === "UNRESERVED"
3084
- ? unreservedCapReason(run, target, cap)
4083
+ ? unreservedCapReason(run, target, rowCap)
3085
4084
  : uncountableReason(target);
3086
- if (reading.outcome === "UNRESERVED") notes.push(unreservedAllowanceNote(cap));
4085
+ if (reading.outcome === "UNRESERVED") notes.push(unreservedAllowanceNote(rowCap));
3087
4086
  // The intent this clause took is released with the rest below: it won
3088
4087
  // no position, and a losing reservation that is never given back is
3089
4088
  // the same stranded allowance by a rarer route.
@@ -3103,7 +4102,7 @@ export async function filingGate(
3103
4102
  withheldBy: refusal,
3104
4103
  overridden: row.overridden && waivableRefusal(refusal),
3105
4104
  };
3106
- refusals.push(refusalMessage({ ...verdicts[index], outcome: "REFUSE", refusal, reason }));
4105
+ refusals.push(refusalMessage({ ...verdicts[index], outcome: "REFUSE", refusal, reason }, overrideLabel));
3107
4106
  // Nothing after this clause can file — the refusal blocks the command
3108
4107
  // — so reserving for it would strand another allowance.
3109
4108
  break;
@@ -3239,7 +4238,7 @@ export function markBlockedCommand(rows: readonly FilingLedgerRow[]): FilingLedg
3239
4238
  * not already have it. Naming-to-deny and naming-to-offer are different
3240
4239
  * acts, and only the first is worth the words (#1595, 2026-10-25).
3241
4240
  */
3242
- export function refusalMessage(v: FilingAdjudication): string {
4241
+ export function refusalMessage(v: FilingAdjudication, overrideLabel: string | null): string {
3243
4242
  // **The BRANCH is `waivableRefusal`, the WORDS are the map.** Reading the
3244
4243
  // map for both would make this a second decider over "does the label
3245
4244
  // waive this" — the drift FG-156 exists to catch, and the mutation that
@@ -3251,10 +4250,17 @@ export function refusalMessage(v: FilingAdjudication): string {
3251
4250
  : UNWAIVABLE_REFUSALS[v.refusal];
3252
4251
  const tail = unwaivable
3253
4252
  ? [
3254
- `--label ${FILING_OVERRIDE_LABEL} does NOT waive this one. ${unwaivable}`,
4253
+ overrideLabel === null
4254
+ ? `No label waives this one. ${unwaivable}`
4255
+ : `--label ${overrideLabel} does NOT waive this one. ${unwaivable}`,
3255
4256
  `The attempt is recorded in ${ledgerPath()} either way.`,
3256
4257
  ]
3257
- : [
4258
+ : overrideLabel === null
4259
+ ? [
4260
+ "No label waives this refusal here: this project configures no filing-override",
4261
+ "label (board.filingOverrideLabel), so there is no route around it to record.",
4262
+ ]
4263
+ : [
3258
4264
  "A label waives this refusal. It is deliberately not spelled here and not offered",
3259
4265
  "as a step: every filing believes it is the exception, so a refusal that hands over",
3260
4266
  "the way around itself is read as the way around itself. If you reach for it, it is",
@@ -3400,15 +4406,19 @@ export function ledgerTitle(title: string): string {
3400
4406
  * re-drafted and the collision no longer reproduces. Naming its timestamp
3401
4407
  * rather than describing it is the point: a reader can find the refusal.
3402
4408
  */
3403
- export function overrideNote(v: FilingAdjudication, prior: FilingLedgerRow | null = null): string {
4409
+ export function overrideNote(
4410
+ v: FilingAdjudication,
4411
+ overrideLabel: string,
4412
+ prior: FilingLedgerRow | null = null,
4413
+ ): string {
3404
4414
  if (v.refusal !== null) {
3405
4415
  return (
3406
- `[FindingArbiter] Allowed by --label ${FILING_OVERRIDE_LABEL}, over a ${v.refusal} ` +
4416
+ `[FindingArbiter] Allowed by --label ${overrideLabel}, over a ${v.refusal} ` +
3407
4417
  `refusal: ${v.reason}. Recorded in ${ledgerPath()}.`
3408
4418
  );
3409
4419
  }
3410
4420
  return (
3411
- `[FindingArbiter] Allowed by --label ${FILING_OVERRIDE_LABEL}, over the ${prior?.refusal} ` +
4421
+ `[FindingArbiter] Allowed by --label ${overrideLabel}, over the ${prior?.refusal} ` +
3412
4422
  `refusal of this same title at ${prior?.at}. This adjudication did not reproduce it — the ` +
3413
4423
  "body has changed since, and the body is an input to the symptom keys — so the override is " +
3414
4424
  `recorded against that row rather than this one. Recorded in ${ledgerPath()}.`
@@ -3430,9 +4440,54 @@ export function overrideNote(v: FilingAdjudication, prior: FilingLedgerRow | nul
3430
4440
  * an allowance it was not handed is the stale-copy class this file keeps
3431
4441
  * meeting, and with no default the compiler refuses a caller that forgets.
3432
4442
  */
3433
- export function unreadableShipPolicyNote(cap: number): string {
4443
+ /**
4444
+ * A clause in this command was judged against the RAISED ceiling.
4445
+ *
4446
+ * Round 2 of PR #1963's security review asked, at minimum, that the raise be
4447
+ * recorded where a reader can see which config declared the queue. It is the
4448
+ * `.claude/rules/config-access.md` rule applied to a control rather than a
4449
+ * feature: *never substitute a built-in default for config without recording
4450
+ * that you did so* — and a ceiling that doubles silently is the same defect
4451
+ * wearing the opposite sign.
4452
+ *
4453
+ * **Not a refusal, and it fires on the ADMITTED case.** That is the point: a
4454
+ * refusal is already loud, and a raise that let a filing through is the
4455
+ * event nobody would otherwise see. It names the label and the file, so the
4456
+ * reader can check both against the tree rather than taking the raise on
4457
+ * trust.
4458
+ */
4459
+ export function queueCeilingNote(label: string, ceiling: number, runCap: number): string {
4460
+ return (
4461
+ `[FindingArbiter] This filing carries \`${label}\`, which \`board.queueLabel\` in ` +
4462
+ `\`.claude/rungate/config.json\` declares to be this project's work queue, so it was judged ` +
4463
+ `against a ceiling of ${ceiling} rather than this run's ${runCap}. It is still counted, still ` +
4464
+ `reserved and still finite — the queue route raises the number and exempts nothing. If that ` +
4465
+ `declaration is not what you expected, the config is the thing to read.`
4466
+ );
4467
+ }
4468
+
4469
+ /**
4470
+ * The committed config could not be read at all, so the cap is strict and
4471
+ * nothing in the working tree can raise it (#1964, SC-2753).
4472
+ *
4473
+ * Its own note rather than `unreadableShipPolicyNote`, because that one says
4474
+ * the config "is present and could not be resolved" and names the file to
4475
+ * repair. Here nothing was read: the repair is a fetch, or a checkout that
4476
+ * has an `origin/main`, and an edit to the config file changes nothing.
4477
+ */
4478
+ export function committedConfigUnmeasuredNote(cap: number, why: string): string {
4479
+ return (
4480
+ `[FindingArbiter] UNMEASURED — ${why}. The filing cap is read from committed config only ` +
4481
+ `(origin/main, never the working tree), so the per-run cap is the STRICT ${cap} and no ` +
4482
+ `work-queue label raises it. The filing is NOT blocked by this note. The repair is a ` +
4483
+ `\`git fetch\` in a checkout that has an \`origin\` remote; editing \`.claude/rungate/config.json\` ` +
4484
+ `changes nothing until it merges.`
4485
+ );
4486
+ }
4487
+
4488
+ export function unreadableShipPolicyNote(cap: number, source: string = "`ship` block"): string {
3434
4489
  return (
3435
- `[FindingArbiter] This project's \`ship\` block is present and could not be resolved, so the ` +
4490
+ `[FindingArbiter] This project's ${source} is present and could not be resolved, so the ` +
3436
4491
  `per-run cap is the STRICT ${cap} rather than whatever the config meant. The filing is NOT ` +
3437
4492
  `blocked by this note and the number is deliberately the conservative one — a corrupt config ` +
3438
4493
  `must never be a route to a larger allowance. But if you expected direct-ship mode's raised ` +
@@ -3448,13 +4503,15 @@ export function unreadableShipPolicyNote(cap: number): string {
3448
4503
  * stricter: the defect is that a re-draft was *invisible*, not that it got
3449
4504
  * through. So this is the visibility, and the filing proceeds.
3450
4505
  */
3451
- export function refiledNote(title: string, prior: FilingLedgerRow): string {
4506
+ export function refiledNote(title: string, prior: FilingLedgerRow, overrideLabel: string | null): string {
3452
4507
  return (
3453
4508
  `[FindingArbiter] This title was refused at ${prior.at} (${prior.refusal}` +
3454
4509
  `${prior.duplicateOf.length > 0 ? `, against ${prior.duplicateOf.map(d => `#${d}`).join(", ")}` : ""}) ` +
3455
4510
  "and this adjudication does not reproduce it, because the body has changed and the body is " +
3456
- `an input to the symptom keys. The filing is ALLOWED and nothing is blocked. If you meant to ` +
3457
- `override that refusal, say so with --label ${FILING_OVERRIDE_LABEL} so it is counted; if the ` +
4511
+ `an input to the symptom keys. The filing is ALLOWED and nothing is blocked. ` +
4512
+ (overrideLabel === null
4513
+ ? "This project configures no filing-override label, so there is no override to declare; if the "
4514
+ : `If you meant to override that refusal, say so with --label ${overrideLabel} so it is counted; if the `) +
3458
4515
  `re-draft genuinely describes a different finding, this note is the only record that the two ` +
3459
4516
  `share a title. Title: ${title}`
3460
4517
  );