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.
- package/README.md +182 -0
- package/gates/.gate-salt +1 -1
- package/hooks/HarnessAFKGate.hook.ts +5 -1
- package/hooks/HookCurrency.hook.ts +11 -8
- package/hooks/MergeGuard.hook.ts +7 -1
- package/hooks/StaleTTLCleanup.hook.ts +4 -4
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/hooks/lib/findWorkflow.ts +3 -2
- package/hooks/lib/paths.ts +14 -2
- package/hooks/lib/utils.ts +23 -3
- package/lib/active-milestone.ts +50 -0
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +397 -23
- package/lib/board-flow.ts +280 -0
- package/lib/board-lane-health.ts +578 -0
- package/lib/board-mirror.ts +136 -39
- package/lib/board-ready-fanout.ts +297 -14
- package/lib/board-ready-rule.ts +1211 -0
- package/lib/board-throughput.ts +136 -0
- package/lib/board-walkthrough.ts +240 -0
- package/lib/body-evidence.ts +203 -0
- package/lib/branch-protection.ts +399 -9
- package/lib/bun-version.ts +36 -0
- package/lib/cli-commands.ts +75 -4
- package/lib/closing-reference-audit.ts +307 -6
- package/lib/config-loader.ts +254 -25
- package/lib/config-readers.ts +170 -10
- package/lib/config-trackable.ts +96 -57
- package/lib/conformity.ts +121 -7
- package/lib/create-sc.ts +25 -2
- package/lib/derived-spec.ts +21 -9
- package/lib/filing-compliance.ts +367 -0
- package/lib/filing-plan.ts +47 -21
- package/lib/finding-arbiter.ts +79 -5
- package/lib/finding-jury.ts +43 -4
- package/lib/finding-promotion.ts +1123 -0
- package/lib/generators/agents-md.ts +149 -0
- package/lib/git-isolation.ts +137 -1
- package/lib/github-api-base.ts +66 -0
- package/lib/github.ts +194 -9
- package/lib/graphql-cursor.ts +80 -0
- package/lib/hook-scopes.ts +78 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +124 -7
- package/lib/issue-extraction.ts +9 -7
- package/lib/issue-file-overlap.ts +373 -0
- package/lib/issue-filing-gate.ts +1109 -52
- package/lib/issue-repair.ts +90 -9
- package/lib/issue-shape.ts +199 -0
- package/lib/live-issues.ts +31 -2
- package/lib/local-work.ts +423 -0
- package/lib/markdown-fence.ts +134 -0
- package/lib/milestone-title.ts +46 -0
- package/lib/scaffold/ai-review-findings.ts +148 -3
- package/lib/scaffold/ai-review-step.ts +65 -5
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
- package/lib/scaffold/steps.ts +115 -9
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +55 -11
- package/lib/spec-placement.ts +203 -13
- package/lib/spec-registry.ts +75 -16
- package/lib/spec-source.ts +609 -0
- package/lib/spec-write-sweep.ts +4 -0
- package/lib/stage-ladder.ts +896 -3
- package/lib/state-claim-readings.ts +252 -0
- package/lib/success-doc.ts +7 -6
- package/lib/test-command-positions.ts +135 -1
- package/lib/work-status.ts +551 -0
- package/lib/worktree-repo.ts +14 -2
- package/package.json +7 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/audit-closing-references.ts +330 -0
- package/scripts/audit-specs.ts +59 -103
- package/scripts/board-conformance.ts +747 -40
- package/scripts/board-mirror.ts +594 -13
- package/scripts/board-ready.ts +979 -0
- package/scripts/board-snapshot.ts +464 -12
- package/scripts/claim-files.ts +578 -0
- package/scripts/criterion-inventory.ts +526 -50
- package/scripts/finding-promotion.ts +547 -0
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/plan-issues.ts +279 -40
- package/scripts/plan-spec.ts +105 -3
- package/scripts/sync-sc-status.ts +147 -7
- package/scripts/worktree-census.ts +958 -0
- package/scripts/worktree-sweep.ts +269 -0
package/lib/issue-filing-gate.ts
CHANGED
|
@@ -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 {
|
|
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 {
|
|
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
|
|
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
|
|
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.
|
|
326
|
-
*
|
|
327
|
-
*
|
|
328
|
-
*
|
|
329
|
-
*
|
|
330
|
-
*
|
|
331
|
-
*
|
|
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 =
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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 =
|
|
2563
|
-
|
|
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(
|
|
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(
|
|
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)
|
|
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(
|
|
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
|
-
|
|
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(
|
|
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
|
-
|
|
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),
|
|
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
|
-
|
|
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,
|
|
4081
|
+
? overCapReason(run, reading.already, target, rowCap, growth.basis)
|
|
3083
4082
|
: reading.outcome === "UNRESERVED"
|
|
3084
|
-
? unreservedCapReason(run, target,
|
|
4083
|
+
? unreservedCapReason(run, target, rowCap)
|
|
3085
4084
|
: uncountableReason(target);
|
|
3086
|
-
if (reading.outcome === "UNRESERVED") notes.push(unreservedAllowanceNote(
|
|
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
|
-
|
|
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(
|
|
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 ${
|
|
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 ${
|
|
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
|
-
|
|
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
|
|
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.
|
|
3457
|
-
|
|
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
|
);
|