rungate 0.8.13 → 0.8.14

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 (40) hide show
  1. package/README.md +82 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  4. package/lib/ai-review-rounds.ts +99 -0
  5. package/lib/ai-review-suppression.ts +200 -21
  6. package/lib/bash-write-guard.ts +50 -5
  7. package/lib/board-flow.ts +235 -0
  8. package/lib/board-lane-health.ts +381 -0
  9. package/lib/board-mirror.ts +53 -35
  10. package/lib/board-ready-fanout.ts +56 -13
  11. package/lib/board-ready-rule.ts +545 -0
  12. package/lib/board-throughput.ts +136 -0
  13. package/lib/board-walkthrough.ts +240 -0
  14. package/lib/body-evidence.ts +203 -0
  15. package/lib/branch-protection.ts +399 -9
  16. package/lib/conformity.ts +95 -2
  17. package/lib/filing-compliance.ts +367 -0
  18. package/lib/finding-arbiter.ts +79 -5
  19. package/lib/generators/agents-md.ts +149 -0
  20. package/lib/github.ts +79 -0
  21. package/lib/graphql-cursor.ts +80 -0
  22. package/lib/issue-create-override.ts +415 -3
  23. package/lib/issue-decomposition.ts +33 -3
  24. package/lib/issue-file-overlap.ts +340 -0
  25. package/lib/issue-filing-gate.ts +173 -8
  26. package/lib/issue-repair.ts +13 -9
  27. package/lib/issue-shape.ts +196 -0
  28. package/lib/scaffold/ai-review-findings.ts +9 -1
  29. package/lib/scaffold/ai-review-step.ts +35 -1
  30. package/lib/source-census.ts +108 -0
  31. package/lib/spec-deps.ts +34 -11
  32. package/lib/spec-placement.ts +108 -0
  33. package/lib/stage-ladder.ts +28 -3
  34. package/lib/work-status.ts +423 -0
  35. package/package.json +1 -1
  36. package/scripts/ai-review-findings.ts +8 -13
  37. package/scripts/ai-review-threads.ts +16 -17
  38. package/scripts/board-mirror.ts +221 -8
  39. package/scripts/generate-code-map.ts +1 -1
  40. package/scripts/plan-spec.ts +79 -1
@@ -0,0 +1,367 @@
1
+ /**
2
+ * Did a refused filing become the comment the refusal told it to be?
3
+ *
4
+ * ## The question, and why nothing answered it before
5
+ *
6
+ * `lib/issue-filing-gate.ts` refuses a filing and routes it to a comment. It
7
+ * does not WRITE the comment — it returns a refusal naming where one should
8
+ * go, and the finding survives only if the agent then writes it. So the gate
9
+ * can be working perfectly while findings are being deleted, and the ledger
10
+ * records the refusal either way. **Compliance with a refusal is the one
11
+ * thing nothing in this tree records.**
12
+ *
13
+ * It matters more than it sounds. The measure the cap was shipped against is
14
+ * issues opened per day, and that number falls **identically** whether the
15
+ * agent writes the comment or drops the finding on the floor. A metric that
16
+ * reads the same on the good outcome and the bad one is not measuring the
17
+ * thing anybody wants.
18
+ *
19
+ * ## A rate of zero and a denominator of zero are different readings
20
+ *
21
+ * This module exists in a world where the honest answer is *nobody has been
22
+ * refused yet*: measured 2026-10-25, the production ledger holds 261 rows
23
+ * and **zero** `OVER_CAP` and **zero** `COMMENT_INSTEAD`. So `rate` is
24
+ * `number | null` and is `null` whenever `observable === 0`. Not `0`, and
25
+ * not a thrown error — `0` is the reading that says agents ignore refusals,
26
+ * which is a serious claim to make about a population that does not exist.
27
+ *
28
+ * `unobservableByRefusal` is beside it so the gap is attributable: a reader
29
+ * learns *which* refusals could not be followed up, which is what decides
30
+ * whether the fix is to persist a field or to wait for traffic.
31
+ *
32
+ * ## Why it is an UPPER BOUND and says so in the field name
33
+ *
34
+ * The ledger does not record WHO attempted the filing. So a comment landing
35
+ * on the target inside the window cannot be attributed to the agent that was
36
+ * refused; it may be anyone's, including a human answering something else.
37
+ * Counting it as compliance can only ever overstate.
38
+ *
39
+ * That is still worth having, because the bound is informative in one
40
+ * direction: an upper bound of zero is decisive, and that is the reading we
41
+ * expect to be arguing about. `compliedUpperBound` is named rather than
42
+ * called `complied` so a later reader cannot quote it as a compliance rate.
43
+ *
44
+ * ## A comment is a TIMELINE EVENT. An issue-body edit is not.
45
+ *
46
+ * Measured on this tracker, 2026-10-25: #1592 carries four `commented`
47
+ * timeline events, while #1476 — edited twice on 10-24, at `00:29:52Z` and
48
+ * `01:32:24Z` — carries **no timeline event for either edit**. The edits
49
+ * exist only under GraphQL `userContentEdits`, which nothing subscribes to.
50
+ *
51
+ * So an answer appended to an issue BODY notifies nobody and is not
52
+ * compliance in any sense a human experiences. `ghIssueComments` reads the
53
+ * comments endpoint and never the body, and a `CommentReading` carries only
54
+ * comment timestamps, so no caller of this module can accidentally count a
55
+ * body edit.
56
+ *
57
+ * ## The target is only recoverable for one refusal class today
58
+ *
59
+ * The refusal MESSAGE names a comment target, computed at refusal time. The
60
+ * ledger ROW does not persist it. The one exception is `DUPLICATE`, whose
61
+ * `duplicateOf` holds the issues the finding collided with — so those rows
62
+ * carry their own target and are the only historical population this can
63
+ * read. Everything else is `UNOBSERVABLE`, by name, with the refusal in the
64
+ * reason. Persisting the target on the row is the change that would widen
65
+ * the denominator; that is a decision for whoever reads this output, and it
66
+ * is deliberately not made here.
67
+ */
68
+
69
+ import { createGitHubClient, listIssueComments, type GitHubClient } from "./github";
70
+ import type { ArbiterRefusal } from "./finding-arbiter";
71
+
72
+ /**
73
+ * The fields of a ledger row this reading needs.
74
+ *
75
+ * Deliberately a structural subset of `FilingLedgerRow` rather than an
76
+ * import of it: rows are read back from JSONL written by two different
77
+ * writers over two days, and several of them predate fields the current
78
+ * interface declares. A reader that required the full shape would refuse
79
+ * the population it exists to measure.
80
+ */
81
+ export interface FilingComplianceRow {
82
+ at: string;
83
+ title: string;
84
+ refusal: string | null;
85
+ emitted: boolean;
86
+ /**
87
+ * **Written as STRINGS by the live writer**, and typed to say so.
88
+ *
89
+ * Measured on the production ledger 2026-10-25: all 14 elements across 261
90
+ * rows are decimal strings — `["1214"]` — and the first version of this
91
+ * module accepted only `number`, so it discarded every target it had and
92
+ * reported a denominator of zero for the entire file. That is the failure
93
+ * this module is otherwise built to refuse, arriving through the parser
94
+ * instead of through the data: an empty population and a population the
95
+ * reader could not see are the same output.
96
+ */
97
+ duplicateOf?: readonly (number | string)[];
98
+ }
99
+
100
+ /** Where a refused finding was told to go, or why that cannot be read. */
101
+ export type ComplianceTarget =
102
+ | { reading: "NAMED"; issues: number[] }
103
+ | { reading: "UNOBSERVABLE"; why: string };
104
+
105
+ /**
106
+ * The comments on one target, or the sentence saying why none were read.
107
+ *
108
+ * **An `UNMEASURED` lookup must never render as "no comment".** They are the
109
+ * two readings this whole module exists to keep apart, and a lookup that
110
+ * returned `[]` on an HTTP error would collapse them at the one place a
111
+ * caller cannot see.
112
+ */
113
+ export type CommentReading =
114
+ | { reading: "MEASURED"; comments: readonly { at: string }[] }
115
+ | { reading: "UNMEASURED"; why: string };
116
+
117
+ export type CommentLookup = (issue: number) => Promise<CommentReading>;
118
+
119
+ export type RowReading =
120
+ | { state: "COMPLIED"; title: string; target: number; at: string }
121
+ | { state: "NOT_OBSERVED"; title: string; targets: number[] }
122
+ | { state: "UNOBSERVABLE"; title: string; why: string };
123
+
124
+ export interface ComplianceReading {
125
+ rows: RowReading[];
126
+ /** Rows on which compliance could be read at all. The denominator. */
127
+ observable: number;
128
+ /** Rows with no recoverable target, or whose lookup failed. */
129
+ unobservable: number;
130
+ /** See the header: an upper bound, because comments are unattributed. */
131
+ compliedUpperBound: number;
132
+ /** `null` when `observable === 0`. Never `0` for an empty population. */
133
+ rate: number | null;
134
+ /** Which refusals could not be followed up, and how many of each. */
135
+ unobservableByRefusal: Record<string, number>;
136
+ }
137
+
138
+ /** A row that was never refused has nothing to comply with. */
139
+ const NOT_REFUSED = "NOT_REFUSED";
140
+
141
+ /**
142
+ * A row that WAS refused and whose refusal the ledger did not label. Distinct
143
+ * from `NOT_REFUSED`, which means the row was emitted and has nothing to
144
+ * comply with. Both are "no refusal string"; only one of them is a gap.
145
+ */
146
+ const REFUSED_UNLABELLED = "REFUSED_UNLABELLED";
147
+
148
+ /**
149
+ * The one refusal whose row persists its own comment target.
150
+ *
151
+ * One binding, so the rule the header states and the rule the code applies
152
+ * are the same string, and a mutation of it moves the behaviour.
153
+ * `issue-filing-gate.ts` writes this literal on the dedupe refusal.
154
+ */
155
+ const DUPLICATE: ArbiterRefusal = "DUPLICATE";
156
+
157
+ /**
158
+ * One `duplicateOf` element as an issue number, or `null`.
159
+ *
160
+ * One binding, so there is one thing to mutate and one place that decides
161
+ * what counts as a target. A value that names no issue returns `null` and
162
+ * the row goes UNOBSERVABLE — never `NaN`, which would be carried into a
163
+ * lookup and come back as an error that reads like a tracker fault.
164
+ */
165
+ function issueNumber(value: unknown): number | null {
166
+ if (typeof value === "number") return Number.isInteger(value) && value > 0 ? value : null;
167
+ if (typeof value !== "string") return null;
168
+ const digits = value.trim().replace(/^#/, "");
169
+ if (!/^[0-9]+$/.test(digits)) return null;
170
+ const n = Number(digits);
171
+ return Number.isInteger(n) && n > 0 ? n : null;
172
+ }
173
+
174
+ export function targetOf(row: FilingComplianceRow): ComplianceTarget {
175
+ if (row.emitted) {
176
+ return {
177
+ reading: "UNOBSERVABLE",
178
+ why: "this filing was not refused — it reached the tracker, so there is no comment to look for",
179
+ };
180
+ }
181
+ // **`duplicateOf` is only this row's target when the row's OWN refusal is
182
+ // `DUPLICATE`.** Review raised this twice before it was fixed, and it is
183
+ // the module's header contradicting its own code: the header says the one
184
+ // exception is `DUPLICATE`, whose `duplicateOf` holds the issues the
185
+ // finding collided with, and the code read the field on any unemitted row.
186
+ //
187
+ // `issue-filing-gate.ts` can reach a refusal other than `DUPLICATE` on a
188
+ // finding that already collided — the dedupe stage computes collisions
189
+ // before the later stages run — so a `TOO_MANY_FILES` row can carry a
190
+ // populated `duplicateOf`. Reading it measures whether somebody commented
191
+ // on an unrelated issue, and counts the answer as compliance with a
192
+ // refusal that named a different target entirely. It is the quiet
193
+ // direction: the denominator looks healthier and the rate is wrong.
194
+ if (row.refusal === DUPLICATE) {
195
+ const issues = (row.duplicateOf ?? [])
196
+ .map(issueNumber)
197
+ .filter((n): n is number => n !== null);
198
+ if (issues.length > 0) return { reading: "NAMED", issues: [...issues] };
199
+ }
200
+ return {
201
+ reading: "UNOBSERVABLE",
202
+ why:
203
+ `the ledger records no comment target for a ${row.refusal ?? REFUSED_UNLABELLED} refusal. ` +
204
+ "The refusal message named one, computed at refusal time; the row does not persist it",
205
+ };
206
+ }
207
+
208
+ /**
209
+ * Was there a comment on this target inside the window?
210
+ *
211
+ * The window is closed at both ends on purpose. A comment written BEFORE the
212
+ * refusal cannot be an answer to it — that is the reading that would turn
213
+ * every duplicate-of-a-busy-issue into compliance — and one written after the
214
+ * window is not evidence about this refusal either.
215
+ */
216
+ function commentInWindow(
217
+ reading: CommentReading,
218
+ fromMs: number,
219
+ windowMs: number,
220
+ ): string | null {
221
+ if (reading.reading !== "MEASURED") return null;
222
+ for (const c of reading.comments) {
223
+ const at = Date.parse(c.at);
224
+ if (Number.isNaN(at)) continue;
225
+ if (at >= fromMs && at <= fromMs + windowMs) return c.at;
226
+ }
227
+ return null;
228
+ }
229
+
230
+ export async function complianceReading(input: {
231
+ rows: readonly FilingComplianceRow[];
232
+ lookup: CommentLookup;
233
+ windowMs: number;
234
+ }): Promise<ComplianceReading> {
235
+ const rows: RowReading[] = [];
236
+ const unobservableByRefusal: Record<string, number> = {};
237
+
238
+ const countUnobservable = (row: FilingComplianceRow) => {
239
+ // TWO POPULATIONS, NOT ONE. This was
240
+ // `row.emitted ? NOT_REFUSED : (row.refusal ?? NOT_REFUSED)`, so a row
241
+ // that WAS refused but carries `refusal: null` — which the type allows
242
+ // and `targetOf`'s own UNOBSERVABLE message anticipates — landed in the
243
+ // same bucket as a row that was emitted and had nothing to comply with.
244
+ //
245
+ // This field exists to ATTRIBUTE the gap, and those two rows are the
246
+ // opposite ends of it: one needed no follow-up, the other needed one and
247
+ // the ledger cannot say what kind. Collapsing them is the one attribution
248
+ // this reading must never make, so the unlabelled refusal gets its own
249
+ // bucket rather than a default (`.claude/rules/config-access.md`, Silent
250
+ // Default Substitution).
251
+ const key = row.emitted ? NOT_REFUSED : (row.refusal ?? REFUSED_UNLABELLED);
252
+ unobservableByRefusal[key] = (unobservableByRefusal[key] ?? 0) + 1;
253
+ };
254
+
255
+ for (const row of input.rows) {
256
+ const target = targetOf(row);
257
+ if (target.reading === "UNOBSERVABLE") {
258
+ rows.push({ state: "UNOBSERVABLE", title: row.title, why: target.why });
259
+ countUnobservable(row);
260
+ continue;
261
+ }
262
+
263
+ const from = Date.parse(row.at);
264
+ if (Number.isNaN(from)) {
265
+ rows.push({
266
+ state: "UNOBSERVABLE",
267
+ title: row.title,
268
+ why: `the row's timestamp \`${row.at}\` could not be read, so no window could be opened`,
269
+ });
270
+ countUnobservable(row);
271
+ continue;
272
+ }
273
+
274
+ // A single COMPLIED is decisive, so an unreadable sibling target does not
275
+ // demote it. The reverse is not true: NOT_OBSERVED over a target we could
276
+ // not read is the conflation this module exists to refuse.
277
+ let complied: { target: number; at: string } | null = null;
278
+ let unreadable: string | null = null;
279
+ for (const issue of target.issues) {
280
+ const reading = await input.lookup(issue);
281
+ if (reading.reading === "UNMEASURED") {
282
+ unreadable ??= `#${issue} could not be read: ${reading.why}`;
283
+ continue;
284
+ }
285
+ const at = commentInWindow(reading, from, input.windowMs);
286
+ if (at !== null) {
287
+ complied = { target: issue, at };
288
+ break;
289
+ }
290
+ }
291
+
292
+ if (complied !== null) {
293
+ rows.push({
294
+ state: "COMPLIED",
295
+ title: row.title,
296
+ target: complied.target,
297
+ at: complied.at,
298
+ });
299
+ continue;
300
+ }
301
+ if (unreadable !== null) {
302
+ rows.push({ state: "UNOBSERVABLE", title: row.title, why: unreadable });
303
+ countUnobservable(row);
304
+ continue;
305
+ }
306
+ rows.push({ state: "NOT_OBSERVED", title: row.title, targets: [...target.issues] });
307
+ }
308
+
309
+ const observable = rows.filter(r => r.state !== "UNOBSERVABLE").length;
310
+ const compliedUpperBound = rows.filter(r => r.state === "COMPLIED").length;
311
+ return {
312
+ rows,
313
+ observable,
314
+ unobservable: rows.length - observable,
315
+ compliedUpperBound,
316
+ // The whole point of the module, in one expression: an empty denominator
317
+ // withholds the number rather than printing the most alarming one.
318
+ rate: observable === 0 ? null : compliedUpperBound / observable,
319
+ unobservableByRefusal,
320
+ };
321
+ }
322
+
323
+ /**
324
+ * The real lookup: the tracker's COMMENTS endpoint, never the issue body.
325
+ *
326
+ * Separate from the pure reading above so the cases can drive every state
327
+ * without a network, and exported so the reading can be run from a one-liner
328
+ * rather than needing a script nothing else references:
329
+ *
330
+ * ```
331
+ * bun -e 'import {complianceReading, ghIssueComments} from "./lib/filing-compliance";
332
+ * const rows = (await Bun.file(process.env.HOME + "/.rungate/finding-ledger.jsonl").text())
333
+ * .trim().split("\n").map(l => JSON.parse(l));
334
+ * console.log(await complianceReading({rows, lookup: ghIssueComments("hornjason/pai-harness"),
335
+ * windowMs: 24 * 3_600_000}));'
336
+ * ```
337
+ *
338
+ * Every failure is `UNMEASURED` carrying its own sentence. There is no path
339
+ * here that returns an empty comment list for a request that did not succeed.
340
+ */
341
+ export function ghIssueComments(
342
+ repo: string,
343
+ // The seam exists so the failure path can be DRIVEN rather than provoked.
344
+ // Its first version had no argument, so the only way to observe the
345
+ // UNMEASURED branch was to run the case against the live API and hope it
346
+ // failed — a case whose verdict depends on the network is not a case.
347
+ makeClient: () => GitHubClient = createGitHubClient,
348
+ ): CommentLookup {
349
+ return async (issue: number): Promise<CommentReading> => {
350
+ // SC-893: Octokit, not a `gh` subprocess. The three readings are
351
+ // unchanged — a client that cannot be built and a request that failed are
352
+ // both UNMEASURED carrying their own sentence, and neither may degrade
353
+ // into an empty comment list, which would read as "nobody commented".
354
+ let client: GitHubClient;
355
+ try {
356
+ client = makeClient();
357
+ } catch (e) {
358
+ return { reading: "UNMEASURED", why: `no GitHub client: ${(e as Error).message}` };
359
+ }
360
+ try {
361
+ const rows = await listIssueComments(client, repo, issue);
362
+ return { reading: "MEASURED", comments: rows.map(r => ({ at: r.created_at })) };
363
+ } catch (e) {
364
+ return { reading: "UNMEASURED", why: `the comments request failed: ${(e as Error).message}` };
365
+ }
366
+ };
367
+ }
@@ -564,11 +564,62 @@ export const DUPLICATE_MIN_SHARED_LOCATIONS = 1;
564
564
  * deleting: a measurement that names a mechanism it never varied will read
565
565
  * as settled for as long as nobody varies it.
566
566
  *
567
- * **The 946-pair table above is not reproducible.** It was measured live
568
- * against a tracker that has moved and no corpus was stored, so neither
569
- * constant can be re-derived by anyone — including anyone who disagrees with
570
- * leaving them. **Tracked as #1365**; until a fixture exists, treat every
571
- * number in this docblock as a reading someone took once.
567
+ * **The 946-pair table above is not reproducible, and never will be.** It was
568
+ * measured live against a tracker that has moved and no corpus was stored.
569
+ * Those 44 findings are gone; #1365 did not recover them and nothing here
570
+ * claims it did. Treat every number above this line as a reading someone took
571
+ * once.
572
+ *
573
+ * ## WHAT IS REPRODUCIBLE, FROM HERE ON (#1365)
574
+ *
575
+ * A corpus is now frozen in `test/fixtures/finding-dedupe-corpus.json` — the
576
+ * fourteen findings these docblocks name inside a PAIR or a CLUSTER, fetched
577
+ * once by `scripts/freeze-dedupe-corpus.ts` and committed. The table below is
578
+ * the stdout of `bun scripts/print-dedupe-pair-table.ts` over that fixture,
579
+ * and `test/dedupe-corpus-table.test.ts` fails when the two differ. So it is
580
+ * a command's output rather than a reading, and it cannot go stale quietly.
581
+ *
582
+ * **Membership is checked, not asserted.** Each of the fourteen carries the
583
+ * sentence from THIS file that admits it, and
584
+ * `test/dedupe-corpus-membership.test.ts` refuses an id whose sentence is
585
+ * absent, does not name it, or lies inside the generated block below — so a
586
+ * member can never be justified by the table its own membership produced.
587
+ *
588
+ * <!-- BEGIN dedupe-pair-table -->
589
+ * Corpus: 14 findings, 91 pairs, frozen 2026-11-07.
590
+ * Regenerate with `bun scripts/print-dedupe-pair-table.ts`.
591
+ *
592
+ * | rule | pairs | which |
593
+ * |---|---|---|
594
+ * | `qty>=2 AND loc>=1` | 1 | 1176/1187 |
595
+ * | containment >= 0.6 | 3 | 1175/1177, 1195/1196, 1454/1456 |
596
+ * | containment >= 0.8 (shipped) | 3 | 1175/1177, 1195/1196, 1454/1456 |
597
+ * | either arm — what the arbiter calls DUPLICATE | 4 | 1175/1177, 1176/1187, 1195/1196, 1454/1456 |
598
+ *
599
+ * Findings under the floor of 4 identity keys, which the containment arm scores 0 against everything: #1239.
600
+ * <!-- END dedupe-pair-table -->
601
+ *
602
+ * ### Four claims above reproduce. One does not.
603
+ *
604
+ * Reproduced exactly, against the live bodies: #1175/#1177 at 1.000 and
605
+ * #1454/#1456 at 0.900 and #1195/#1196 at **0.833**, and #1195/#1239 scoring
606
+ * **0.000** because #1239 carries three identity keys and sits under the
607
+ * floor. That is the whole of the #1536 table, re-derived from a fixture.
608
+ *
609
+ * **The `qty>=2 AND loc>=1` row does not.** It reads *4 — 1175/1177,
610
+ * 1195/1196, 1269/1286, 1162/1226*; over the frozen corpus that arm flags
611
+ * **one** pair, and the pair is #1176/#1187 — the shape this file already
612
+ * names as the one it cannot tell from a duplicate, since #1187 quotes other
613
+ * findings' readings because it is *about* them.
614
+ *
615
+ * **This is a failure to reproduce, not a demonstration that the row was
616
+ * false.** The fixture holds the bodies as the tracker had them on the freeze
617
+ * date, and an issue body is editable: six of these fourteen were closed and
618
+ * several edited in the weeks between. What can be said is the thing #1365
619
+ * exists to make sayable at all — *the row cannot be checked against anything,
620
+ * and the arm it justifies is the one tuned on the corpus that was lost.*
621
+ * Neither constant is moved on this reading; a re-tune needs a corpus
622
+ * collected for the purpose, which is a different issue from freezing one.
572
623
  *
573
624
  * The floor exists because containment is meaningless on a tiny key set — a
574
625
  * one-key finding is wholly contained in anything mentioning that key, which
@@ -857,6 +908,29 @@ export type ArbiterRefusal =
857
908
  * answer at all and refuses, naming the path so an operator can act.
858
909
  */
859
910
  | "UNMEASURED_CAP"
911
+ /**
912
+ * The body is short a section the issue form requires (#1741).
913
+ *
914
+ * **The last stage, and it converts an ALLOW only.** Everything before it
915
+ * asks whether this should be on the tracker at all; this one asks whether
916
+ * what is about to land on the tracker is readable by the things that read
917
+ * it. An issue naming no files cannot be checked against rule 2, cannot be
918
+ * scanned for the file-overlap conflicts that put four agents on
919
+ * `lib/bash-write-guard.ts`, and cannot tell a picker what they are picking
920
+ * up.
921
+ *
922
+ * **Waivable, and deliberately so.** Unlike the three above, this one IS a
923
+ * claim about the filing — it says a named section is absent, which is a
924
+ * fact the agent can refute by adding it or override when they genuinely
925
+ * mean to file a stub. A count takes no argument; a shape does.
926
+ *
927
+ * The sections come from `requiredSections` in `lib/issue-shape.ts`, which
928
+ * is the same decider the two issue forms and `plan-issues --decompose`
929
+ * read. That is the whole of #1741: before it, a gate requiring the form's
930
+ * fields would have refused every row of every decomposed plan, because
931
+ * the generator emitted two of the five.
932
+ */
933
+ | "MALFORMED"
860
934
  /** Something could not be evaluated. Fails; never skips. */
861
935
  | "UNMEASURED";
862
936
 
@@ -696,5 +696,154 @@ Check the claim against the repo before you build on it.
696
696
  `,
697
697
  });
698
698
 
699
+ // #1742 — a consumer that cannot report what it found upstream has not
700
+ // been supported, it has been shipped to. Measured 2026-11-03: the
701
+ // `from-consumer` label did not exist among 23 labels, no milestone was a
702
+ // triage lane among 18, and there was no rule. Consumers reached for
703
+ // `external-audit` — the label Jason's decision (c) ruled out — and
704
+ // fifteen open issues carry it.
705
+ //
706
+ // **Inline here, like every other rule, and NOT in a module of its own.**
707
+ // #1742's file list predicted `lib/scaffold/reporting-upstream.ts`; that
708
+ // shape was built and withdrawn, because `test/harness-fixed-point.test.ts`
709
+ // copies this generator into an `mkdtemp` tree and the new import died
710
+ // there with `Cannot find module`. That is Tier 1 of
711
+ // `.claude/rules/self-referential-tests.md` exactly — and a battery whose
712
+ // mutant fails to load goes GREEN while witnessing nothing, so the cheap
713
+ // fix of teaching the copier one more path buys a second thing to keep in
714
+ // step. Every other rule in this file is inline; so is this one.
715
+ //
716
+ // **Path-scoped to `package.json`, and the scope is forced twice over.**
717
+ // `scripts/check-instruction-surface.ts` read 258 bytes of headroom under
718
+ // the 64,000-byte budget, so an unscoped rule reddens
719
+ // `.claude/agents/aditi.md` — a file with nothing to do with reporting
720
+ // upstream. A scoped rule is billed against every file its globs match,
721
+ // and `harness-managed.md` already claims `AGENTS.md`, both workflows,
722
+ // `.claude/agents/**`, `.claude/rules/**`, `CODE-MAP.md` and
723
+ // `test/scaffold-conformity.test.ts` — a second rule on any of those sums
724
+ // with it and goes over. The harness config directory was the first
725
+ // choice and CONFIG-1 refuses it: a config path spelled in a string is a
726
+ // direct access site, which is the same trap `STEPS_NOT_MINIMAL` in
727
+ // `lib/scaffold/profiles.ts` describes in its own comment.
728
+ //
729
+ // `package.json` is what is left, and the first version of this comment
730
+ // justified it with "it holds the `rungate` dependency entry, which is the
731
+ // version this rule tells the reporter to quote." **That was false**, and
732
+ // the AI review of #1813 said so: this repository's own `package.json` is
733
+ // `"name": "rungate"` with a top-level `version`, no such entry — and a
734
+ // workspace-linked consumer's entry is a path, not a version.
735
+ //
736
+ // The scope stands on the honest reading instead. `package.json` is the
737
+ // file that answers *what is rungate to this project* — a dependency, a
738
+ // link, or the project itself — and that is precisely the question an
739
+ // agent is holding when it needs this rule. The rule now enumerates all
740
+ // three and says UNMEASURED when none resolves.
741
+ //
742
+ // **No `isHarnessItself` branch**, which is where the review's own fix
743
+ // pointed. It catches rungate's own repo and NOT the workspace-linked
744
+ // consumer the review named in the same paragraph, so it closes one of
745
+ // the two cases and reads as if it closed both — the shape #1810 spent
746
+ // three rounds on, each repair loosening the branch the next one arrived
747
+ // through. Prose covering every case has no branch to drift, and
748
+ // `test/gen-agents-md.test.ts` asserts the harness and a consumer get
749
+ // byte-identical content so none can be added without being noticed.
750
+ //
751
+ // Emitted into EVERY profile, including minimal. `RULES_NOT_MINIMAL`
752
+ // excludes a rule naming machinery the profile did not install, and this
753
+ // one names a tracker that exists either way — a minimal consumer is if
754
+ // anything the likeliest to hit something and have nowhere to put it.
755
+ rules.push({
756
+ filename: "reporting-upstream.md",
757
+ content: `---
758
+ description: How to report a problem you found in rungate itself, from this repository
759
+ paths:
760
+ - "package.json"
761
+ ---
762
+
763
+ ## You found something in rungate, not in this project
764
+
765
+ File it on **hornjason/rungate**, not here, and not as a code comment that
766
+ nobody upstream reads.
767
+
768
+ \`\`\`bash
769
+ gh issue create --repo hornjason/rungate \\
770
+ --label from-consumer \\
771
+ --title "<the symptom, not the fix>" \\
772
+ --body-file <a file you wrote FIRST, in a separate command>
773
+ \`\`\`
774
+
775
+ ## Show the body to your user before you send it
776
+
777
+ **hornjason/rungate is somebody else's repository, and its issues are
778
+ public.** Filing there publishes whatever you wrote, permanently — a
779
+ deletion later does not un-cache or un-index it. So the body is not yours to
780
+ send on your own judgement: write the file, show it to your user, and send
781
+ it only once they have said yes.
782
+
783
+ What goes in it is the **smallest thing that reproduces the problem**, and
784
+ nothing else:
785
+
786
+ - a reproducer you constructed, never a paste of this project's source,
787
+ config, logs, stack traces, test output or data
788
+ - paths only where the path IS the symptom — and say so
789
+ - no credentials, tokens, keys, internal hostnames, URLs or customer data,
790
+ including inside a quoted error message
791
+
792
+ If you cannot describe the problem without one of those, that is the thing
793
+ to tell your user. It is not a reason to send it anyway.
794
+
795
+ ## The label is \`from-consumer\`, and it is not \`external-audit\`
796
+
797
+ \`external-audit\` means *rungate audited something else*. A consumer report
798
+ is the opposite direction, and conflating them is how a report from a real
799
+ user lands in a queue nobody triages as user feedback.
800
+
801
+ If \`from-consumer\` does not exist on the repository, say so in the body
802
+ rather than substituting the nearest label. A label chosen because it was
803
+ available is a routing decision nobody made.
804
+
805
+ ## What the body must carry
806
+
807
+ The three sections every issue there needs. No criterion id — you cannot
808
+ know one from here and you are not expected to:
809
+
810
+ - **What must become true** — the symptom, with the numbers you measured
811
+ - **Files this will change** — if you know; *unknown* is an honest answer
812
+ - **How we will know** — what you would run to see it fixed
813
+
814
+ **Say which version of rungate you are on, and how you know.** A report
815
+ against a version nobody can identify cannot be reproduced, and will be
816
+ closed as such.
817
+
818
+ Where that number lives depends on how rungate reached this project, and
819
+ there is no one key to read:
820
+
821
+ - a declared dependency — the \`rungate\` entry under \`dependencies\` or
822
+ \`devDependencies\` in \`package.json\`
823
+ - a workspace or \`link:\` resolution — the entry is a path, not a version,
824
+ so read \`version\` out of the resolved package's own \`package.json\`
825
+ - **this project IS rungate** — then nothing below applies. There is no
826
+ upstream to report to: what you found is an ordinary issue on this
827
+ repository, and the version is the top-level \`version\` field.
828
+
829
+ If none of those resolves, write **UNMEASURED** and say which you tried.
830
+ Guessing a version is worse than not supplying one — it sends the
831
+ maintainers to the wrong tree.
832
+
833
+ ## Do not open a pull request first
834
+
835
+ File the issue, link it, and wait for a reply. A pull request from a
836
+ consumer against a harness they do not own is expensive to review and
837
+ frequently solves the wrong half of the problem — the maintainers may
838
+ already know the cause.
839
+
840
+ ## What belongs here instead
841
+
842
+ A problem in **this** project's own code, config or specs is an ordinary
843
+ issue on this repository. The test is simple: if deleting rungate would
844
+ make the problem go away it is upstream, and if it would not it is yours.
845
+ `,
846
+ });
847
+
699
848
  return rules;
700
849
  }