rungate 0.8.13 → 0.8.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/README.md +182 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/HarnessAFKGate.hook.ts +5 -1
  4. package/hooks/HookCurrency.hook.ts +11 -8
  5. package/hooks/MergeGuard.hook.ts +7 -1
  6. package/hooks/StaleTTLCleanup.hook.ts +4 -4
  7. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  8. package/hooks/lib/findWorkflow.ts +3 -2
  9. package/hooks/lib/paths.ts +14 -2
  10. package/hooks/lib/utils.ts +23 -3
  11. package/lib/active-milestone.ts +50 -0
  12. package/lib/ai-review-rounds.ts +99 -0
  13. package/lib/ai-review-suppression.ts +200 -21
  14. package/lib/bash-write-guard.ts +397 -23
  15. package/lib/board-flow.ts +280 -0
  16. package/lib/board-lane-health.ts +578 -0
  17. package/lib/board-mirror.ts +136 -39
  18. package/lib/board-ready-fanout.ts +297 -14
  19. package/lib/board-ready-rule.ts +1211 -0
  20. package/lib/board-throughput.ts +136 -0
  21. package/lib/board-walkthrough.ts +240 -0
  22. package/lib/body-evidence.ts +203 -0
  23. package/lib/branch-protection.ts +399 -9
  24. package/lib/bun-version.ts +36 -0
  25. package/lib/cli-commands.ts +75 -4
  26. package/lib/closing-reference-audit.ts +307 -6
  27. package/lib/config-loader.ts +254 -25
  28. package/lib/config-readers.ts +170 -10
  29. package/lib/config-trackable.ts +96 -57
  30. package/lib/conformity.ts +121 -7
  31. package/lib/create-sc.ts +25 -2
  32. package/lib/derived-spec.ts +21 -9
  33. package/lib/filing-compliance.ts +367 -0
  34. package/lib/filing-plan.ts +47 -21
  35. package/lib/finding-arbiter.ts +79 -5
  36. package/lib/finding-jury.ts +43 -4
  37. package/lib/finding-promotion.ts +1123 -0
  38. package/lib/generators/agents-md.ts +149 -0
  39. package/lib/git-isolation.ts +137 -1
  40. package/lib/github-api-base.ts +66 -0
  41. package/lib/github.ts +194 -9
  42. package/lib/graphql-cursor.ts +80 -0
  43. package/lib/hook-scopes.ts +78 -0
  44. package/lib/issue-create-override.ts +415 -3
  45. package/lib/issue-decomposition.ts +124 -7
  46. package/lib/issue-extraction.ts +9 -7
  47. package/lib/issue-file-overlap.ts +373 -0
  48. package/lib/issue-filing-gate.ts +1109 -52
  49. package/lib/issue-repair.ts +90 -9
  50. package/lib/issue-shape.ts +199 -0
  51. package/lib/live-issues.ts +31 -2
  52. package/lib/local-work.ts +423 -0
  53. package/lib/markdown-fence.ts +134 -0
  54. package/lib/milestone-title.ts +46 -0
  55. package/lib/scaffold/ai-review-findings.ts +148 -3
  56. package/lib/scaffold/ai-review-step.ts +65 -5
  57. package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
  58. package/lib/scaffold/steps.ts +115 -9
  59. package/lib/source-census.ts +108 -0
  60. package/lib/spec-deps.ts +55 -11
  61. package/lib/spec-placement.ts +203 -13
  62. package/lib/spec-registry.ts +75 -16
  63. package/lib/spec-source.ts +609 -0
  64. package/lib/spec-write-sweep.ts +4 -0
  65. package/lib/stage-ladder.ts +896 -3
  66. package/lib/state-claim-readings.ts +252 -0
  67. package/lib/success-doc.ts +7 -6
  68. package/lib/test-command-positions.ts +135 -1
  69. package/lib/work-status.ts +551 -0
  70. package/lib/worktree-repo.ts +14 -2
  71. package/package.json +7 -1
  72. package/scripts/ai-review-findings.ts +8 -13
  73. package/scripts/ai-review-threads.ts +16 -17
  74. package/scripts/audit-closing-references.ts +330 -0
  75. package/scripts/audit-specs.ts +59 -103
  76. package/scripts/board-conformance.ts +747 -40
  77. package/scripts/board-mirror.ts +594 -13
  78. package/scripts/board-ready.ts +979 -0
  79. package/scripts/board-snapshot.ts +464 -12
  80. package/scripts/claim-files.ts +578 -0
  81. package/scripts/criterion-inventory.ts +526 -50
  82. package/scripts/finding-promotion.ts +547 -0
  83. package/scripts/generate-code-map.ts +1 -1
  84. package/scripts/plan-issues.ts +279 -40
  85. package/scripts/plan-spec.ts +105 -3
  86. package/scripts/sync-sc-status.ts +147 -7
  87. package/scripts/worktree-census.ts +958 -0
  88. package/scripts/worktree-sweep.ts +269 -0
@@ -564,10 +564,28 @@ export function advisoryNotice(reading: AiReviewFindingsReading): string | null
564
564
  return `${all[i]}${key}`;
565
565
  });
566
566
 
567
+ // DERIVED from the rank table, not restated. #1914 round 2 added a fourth
568
+ // tag and this sentence was a hardcoded list of three, so it would have
569
+ // gone on naming an order it no longer described — the defect this module
570
+ // spends most of its length guarding against, in its own output.
571
+ const order = (Object.keys(SEVERITY_RANK) as Severity[])
572
+ .sort((a, b) => SEVERITY_RANK[a] - SEVERITY_RANK[b])
573
+ .join(" / ");
574
+ // #1914 round 2: the demotion's reason reaches `detail`, and `detail` is
575
+ // only read back for BLOCKED, CONTRADICTION and UNMEASURED. A payload
576
+ // whose only blocking finding is demoted here is CLEAN, so this notice is
577
+ // the ONLY thing the maintainer sees — a tag with no legend would be a
578
+ // finding nobody can act on, which is the state this issue is about.
579
+ const unobserved = rendered.some(line => line.includes("[Unobserved]"))
580
+ ? `An [Unobserved] finding claims a test's outcome, and this job runs no test ` +
581
+ `command — so it is an inference from reading the source, not a result. It is ` +
582
+ `reported in full and does not block. `
583
+ : "";
567
584
  return (
568
585
  `${advisory.length} advisory finding(s) were counted and block nothing, ` +
569
- `in Important / Pre-existing / Nit order. ` +
586
+ `in ${order} order. ` +
570
587
  `${rendered.join("; ")}. ` +
588
+ unobserved +
571
589
  `Each is UNANSWERED: nothing in this pipeline requires it to be fixed, ` +
572
590
  `resolved with a reason, or filed, and this annotation is the only place ` +
573
591
  `it survives the job — the payload lives under the runner's temp directory ` +
@@ -667,6 +685,85 @@ export function blockingContractViolations(finding: Record<string, unknown>): st
667
685
  });
668
686
  }
669
687
 
688
+ /**
689
+ * A thing whose outcome is a test run: the subject half of the claim.
690
+ *
691
+ * **`check`, `case`, `spec` and `assertion` are deliberately absent**, and
692
+ * that is the whole of #1914 round 1. They are ordinary production
693
+ * vocabulary in this repository — a `check` is a CI job or a guard, a
694
+ * `case` is a branch, a `spec` is a document under `specs/` — so a
695
+ * well-evidenced finding reading *"the required check is broken when the
696
+ * payload omits the severity field"* matched the subject half and demoted
697
+ * itself. The whole point of this module is the red required check; a
698
+ * detector that turns one green over a live defect is worse than no
699
+ * detector.
700
+ *
701
+ * `test` covers a path as well as a noun: `\b` fires at the slash and the
702
+ * dot, so `test/ratchet.test.ts` matches without a second pattern.
703
+ */
704
+ const TEST_SUBJECT = /\b(?:tests?|suites?)\b/i;
705
+
706
+ /**
707
+ * The outcome half. One exclusion: **`fails to <verb>`**, because "the suite
708
+ * fails to load the module" is a statement about what code DOES, which is
709
+ * the ordinary subject of a review and must keep blocking.
710
+ *
711
+ * `broken` was briefly excluded too, on the reasoning above the subject
712
+ * list, and the mutation that restored it turned **no case red** — once the
713
+ * subject is `test` or `suite`, "broken" can only be describing a run. An
714
+ * exclusion no case can see is not a decision, so it was withdrawn and
715
+ * `the suite is broken` is pinned below instead.
716
+ */
717
+ const TEST_OUTCOME =
718
+ /\b(?:fail(?:s|ing|ed)?(?!\s+to\s+\w)|red|broken|do(?:es)?\s+not\s+pass|cannot\s+pass|will\s+not\s+pass|won't\s+pass)\b/i;
719
+
720
+ /**
721
+ * Does this finding assert the OUTCOME of a test run? — #1879.
722
+ *
723
+ * ## Why an outcome claim is unfounded here by construction
724
+ *
725
+ * `.github/workflows/ai-review.yml` runs no test command of any kind. The
726
+ * reviewer reads source and the diff; it never sees a result. So a finding
727
+ * saying a named case fails is always an inference, and on #1878 the same
728
+ * inference blocked three rounds running and was wrong all three times.
729
+ *
730
+ * That instance arrived through the restore — `.claude` is in
731
+ * `AI_REVIEW_UNTRUSTED_PATHS`, so the reviewer read the BASE's ratchet file
732
+ * beside the branch's source and concluded a case must fail. **The restore
733
+ * is not what makes the claim unfounded**, and a check built around it would
734
+ * be narrower than the defect: the same sentence about a file nothing
735
+ * restores is just as unobserved. The prompt already forbids the
736
+ * restore-shaped version of this, in those words, and was ignored anyway —
737
+ * which is the argument for deciding it here rather than instructing it
738
+ * again.
739
+ *
740
+ * ## What this is allowed to get wrong, and in which direction
741
+ *
742
+ * It is a text detector over prose, which is the shape this repository keeps
743
+ * catching itself on, so the bound is stated rather than implied:
744
+ *
745
+ * - **A false negative is the status quo.** Today every one of these blocks.
746
+ * - **A false positive costs a finding its blocking status and nothing
747
+ * else** — it stays in `reported` and reaches the maintainer in full.
748
+ *
749
+ * Both halves must land in ONE sentence, because "this test file is new"
750
+ * followed by "the build is broken" is two statements and neither is a
751
+ * claim about a case's outcome.
752
+ *
753
+ * The returned string is the sentence itself, so the refusal quotes what it
754
+ * matched instead of asserting that it matched something.
755
+ */
756
+ export function unrunTestClaim(finding: Record<string, unknown>): string | null {
757
+ for (const key of [AI_REVIEW_FINDING_FIELDS.summary, AI_REVIEW_FINDING_FIELDS.failureScenario]) {
758
+ const value = finding[key];
759
+ if (typeof value !== "string") continue;
760
+ for (const sentence of value.split(/(?<=[.!?])\s+|\n+/)) {
761
+ if (TEST_SUBJECT.test(sentence) && TEST_OUTCOME.test(sentence)) return sentence.trim();
762
+ }
763
+ }
764
+ return null;
765
+ }
766
+
670
767
  // `AI_REVIEW_CHANGED_FILES_FLAG` lived here and is gone. #1204 argued for a
671
768
  // FLAG over a second positional, citing #675: `--project-root <cwd>` "would
672
769
  // arrive as a second positional and be read as a second payload".
@@ -726,7 +823,15 @@ export function scopeNotSupplied(): AiReviewScopeReading {
726
823
  detail:
727
824
  `no changed-file list was given (second positional argument), so whether ` +
728
825
  `a blocking finding names a file this pull request touches was not checked. ` +
729
- `This is a reading, not a pass: the generated job does not supply the list yet`,
826
+ // #1567. This said "the generated job does not supply the list yet",
827
+ // which stopped being true when #1356 wired the writer: the step passes
828
+ // the list as a second positional today. An operator reading the old
829
+ // sentence would conclude the harness cannot do this, when the true
830
+ // state is that THIS invocation arrived without one — a different
831
+ // problem with a different fix.
832
+ `This is a reading, not a pass. The generated job passes the list as a second ` +
833
+ `positional, so an empty one here means either the step that writes it did not ` +
834
+ `run, or the adjudicator was invoked by hand`,
730
835
  };
731
836
  }
732
837
 
@@ -1200,7 +1305,28 @@ export function findingTag(
1200
1305
  ): Severity | null {
1201
1306
  if (findingPathScope(finding, touched) === "PRE_EXISTING") return "Pre-existing";
1202
1307
  const blocks = severityBlocks(finding[AI_REVIEW_SEVERITY_KEY]);
1203
- return blocks === null ? null : blocks ? "Important" : "Nit";
1308
+ // BEFORE the unrun check, and that order is #1914 round 4. An
1309
+ // unrecognised severity tags `null`, and the first version of #1879 put
1310
+ // the unrun check above this — so a finding declaring `severity: "spicy"`
1311
+ // whose prose matched read `[Unobserved]` instead of untagged. The
1312
+ // payload is `SEVERITY_UNRECOGNISED` and the reading is UNMEASURED, but
1313
+ // `tagsForPayload` runs independently of `reasons` and the annotation
1314
+ // showed the tag anyway: the module inventing a classification for a
1315
+ // payload it is refusing, which is what this docblock warns about.
1316
+ //
1317
+ // The `Pre-existing` branch above has the same shape and predates this
1318
+ // change. It is deliberately left alone — fixing it is a behaviour change
1319
+ // to CRC-B7 that nothing in this issue asked for.
1320
+ if (blocks === null) return null;
1321
+ // #1879, and in the same position relative to attribution as the demotion
1322
+ // is: a finding that is both pre-existing and an unrun claim reads
1323
+ // `Pre-existing`, so the tag and the demotion cannot disagree about one
1324
+ // finding. That is also why the check is HERE rather than beside the
1325
+ // demotion in `readPayload` — a tag that only tracked the demotion would
1326
+ // leave an ADVISORY unrun claim reading `Nit`, and the maintainer reads
1327
+ // the tag.
1328
+ if (unrunTestClaim(finding) !== null) return "Unobserved";
1329
+ return blocks ? "Important" : "Nit";
1204
1330
  }
1205
1331
 
1206
1332
  /**
@@ -1757,6 +1883,25 @@ function readPayload(
1757
1883
  // — the ballot is RECORDED and never acted on. `main` runs the gate
1758
1884
  // for the ledger and the annotation; this list is untouched by it.
1759
1885
  // See `specs/CODE-REVIEW-CONVERGENCE-SPEC.md` under CRC-B4.
1886
+ //
1887
+ // #1879, and LAST of the demotions rather than first. A finding that is
1888
+ // both pre-existing and an unrun claim is reported as pre-existing,
1889
+ // which is the older mechanism and the better-evidenced sentence; this
1890
+ // one only sees what would otherwise still redden the check.
1891
+ //
1892
+ // It demotes on the same terms CRC-B8 set: the finding stays in
1893
+ // `reported` and counts toward `demoted`, so a reviewer that said
1894
+ // BLOCK is not turned into a CONTRADICTION by the demotion working.
1895
+ const unrun = unrunTestClaim(finding);
1896
+ if (unrun !== null) {
1897
+ demoted += 1;
1898
+ detail.push(
1899
+ `finding ${i} claims a test outcome, and no test ran: ${JSON.stringify(unrun)}. The ` +
1900
+ `review job executes no test command, so this is an inference from reading the ` +
1901
+ `source and not an observation. It is reported and does not block`,
1902
+ );
1903
+ return;
1904
+ }
1760
1905
  blocking.push(item);
1761
1906
  // Tagged through the same binding every other render uses. By here the
1762
1907
  // tag is `Important` by construction — the severity blocks and the
@@ -1272,6 +1272,8 @@ export interface AiReviewActionRefs {
1272
1272
  * re-indented by `indent` on the way out, like every script above.
1273
1273
  */
1274
1274
  setupBunWith: string;
1275
+ /** The step's `env:` block, from `setupBunEnv(" ")` (#2039). */
1276
+ setupBunEnv: string;
1275
1277
  }
1276
1278
 
1277
1279
  /**
@@ -4030,19 +4032,26 @@ export const AI_REVIEW_BLOCK_VERDICT = "BLOCK";
4030
4032
  * imports and re-exports these two names, so its own callers are unchanged
4031
4033
  * and there is still exactly ONE declaration.
4032
4034
  */
4033
- export type Severity = "Important" | "Nit" | "Pre-existing";
4035
+ export type Severity = "Important" | "Nit" | "Pre-existing" | "Unobserved";
4034
4036
 
4035
4037
  /**
4036
4038
  * Sort order for the posted findings. A pre-existing bug is still a bug, so
4037
4039
  * it outranks a nit; it is not the author's, so it does not outrank an
4038
- * Important one.
4040
+ * Important one. `Unobserved` (#1879) sits with `Pre-existing`, below it:
4041
+ * both are real findings that do not block, and an unobserved one is the
4042
+ * weaker claim of the two because nothing ran to produce it.
4039
4043
  *
4040
4044
  * ONE binding, and the only ordering in the deployed path. A second
4041
4045
  * comparator would be two deciders over one question and a mutation of
4042
4046
  * either would leave the other holding every case up
4043
4047
  * (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
4044
4048
  */
4045
- export const SEVERITY_RANK: Record<Severity, number> = { Important: 0, "Pre-existing": 1, Nit: 2 };
4049
+ export const SEVERITY_RANK: Record<Severity, number> = {
4050
+ Important: 0,
4051
+ "Pre-existing": 1,
4052
+ Unobserved: 2,
4053
+ Nit: 3,
4054
+ };
4046
4055
 
4047
4056
  const AI_REVIEW_BLOCKING_SEVERITIES = Object.keys(AI_REVIEW_SEVERITIES).filter(
4048
4057
  s => AI_REVIEW_SEVERITIES[s],
@@ -5803,6 +5812,22 @@ working tree disagrees with the diff about one of them. Reading one of these
5803
5812
  files to judge a change to it tells you about the base, not about this pull
5804
5813
  request.
5805
5814
 
5815
+ THE SCRATCH DIRECTORY ${AI_REVIEW_ACTION_SCRATCH} IS NOT THE EXCEPTION TO
5816
+ THAT, AND IT LOOKS LIKE ONE. The review action copies what it calls "the
5817
+ pull request's sensitive paths" there and logs that it preserved them. It
5818
+ runs AFTER the restore step above, so for every path listed here what it
5819
+ copied was already the base's copy. That directory therefore holds BASE
5820
+ content under a name that says otherwise, and it is the most convincing
5821
+ wrong answer available to you: it looks like a pre-restore snapshot and it
5822
+ is a post-restore one. A finding of the form "the author claims they changed
5823
+ this and the preserved copy shows they did not" is this trap, and it was
5824
+ filed as a blocking finding twice against a pull request whose commit did
5825
+ carry the change.
5826
+
5827
+ So THE DIFF REMAINS AUTHORITATIVE even against that directory. If you want to
5828
+ know what one of these paths contains on this pull request, the diff is the
5829
+ only reading in this checkout that can tell you.
5830
+
5806
5831
  Everywhere else in the checkout, the working tree IS this pull request and a
5807
5832
  disagreement with the diff is worth reporting.
5808
5833
 
@@ -8643,9 +8668,25 @@ export const AI_REVIEW_TREE_READER = `classify_path() {
8643
8668
  # A path from \`read_scratch\` was never seen by git and is wrapped by
8644
8669
  # nothing. That is the one that needs escaping below, and \`esc\` is how the
8645
8670
  # renderer knows which it is WITHOUT asking the question a second time.
8671
+ #
8672
+ # NEWLINE ARM FIRST, AND THE ORDER IS THE WHOLE GUARD (#1869). \`case\` tries
8673
+ # arms in sequence, so with the git-shape arm first a name that BOTH starts
8674
+ # with a literal \`"\` AND carries a newline matched it, \`esc\` stayed empty,
8675
+ # and the record split into two lines again. Measured on the unfixed source,
8676
+ # \`classify_path\` called directly: \`"<newline>absent .ripgreprc\` printed
8677
+ # \`unquotable "\` and then \`absent .ripgreprc\` — a second line a reader
8678
+ # cannot tell from one this function produced.
8679
+ #
8680
+ # Not reachable from either caller as they stand: git C-quotes a newline to
8681
+ # two characters, so a git-derived path never carries a raw one, and
8682
+ # \`read_scratch\` globs \`"\${root}"*\` so every entry it finds begins with
8683
+ # the scratch root and cannot start with a quote. The two conditions live in
8684
+ # different sources. This is the order the NEXT source inherits, and the
8685
+ # paragraph above is the record of what happened the last time a source
8686
+ # arrived that git had never seen.
8646
8687
  case "\${p}" in
8647
- '"'*) h=unquotable; esc= ;;
8648
8688
  *$'\\n'*) h=unquotable; esc=1 ;;
8689
+ '"'*) h=unquotable; esc= ;;
8649
8690
  *)
8650
8691
  esc=
8651
8692
  if [ -f "\${p}" ]; then
@@ -11164,6 +11205,7 @@ export function buildReviewRunStep(
11164
11205
  ` uses: ${refs.setupBun}`,
11165
11206
  ` with:`,
11166
11207
  ...refs.setupBunWith.trimEnd().split("\n"),
11208
+ ...refs.setupBunEnv.trimEnd().split("\n"),
11167
11209
  ];
11168
11210
 
11169
11211
  // Workload Identity Federation, and NO service-account key (#677 AC-15).
@@ -11716,6 +11758,25 @@ export function buildReviewRunStep(
11716
11758
  indented(carry, indent) +
11717
11759
  indented(baseline, indent) +
11718
11760
  indented(review, indent) +
11761
+ // #1395. BEFORE the ledger, and that is the whole of this ordering. The
11762
+ // ledger quotes a line out of a reviewer-cited file, and #1383 made that
11763
+ // read come from the INDEX rather than the working tree — correct, and a
11764
+ // workaround: it routes AROUND a modified checkout instead of preventing
11765
+ // one, so every later reader of this tree has to remember to ask the
11766
+ // index too. Refusing here makes a modified checkout unquotable by
11767
+ // construction and leaves the index read as defence in depth.
11768
+ //
11769
+ // What it costs, deliberately: a refusal ends the job, and this job
11770
+ // forbids `if:`, so the ledger, the threads, the execution-file staging
11771
+ // and the report do not run on a drift failure. `buildDriftScript` says
11772
+ // why that is the right loss — a review that edited the code it was
11773
+ // reviewing "is not an absent review; it is a review nobody should
11774
+ // read" — and a finding set the carry-forward walker would re-inject
11775
+ // into later rounds is exactly what a tainted round must not leave
11776
+ // behind. The refusal is not silent: its annotation names the paths that
11777
+ // moved, so the diagnosis is in the annotation rather than in the
11778
+ // execution file this order skips.
11779
+ indented(drift, indent) +
11719
11780
  indented(persist, indent) +
11720
11781
  // #1612. After the ledger and before the report, for the reason
11721
11782
  // `AI_REVIEW_THREADS_STEP_ID` gives: the payload exists, the adjudicator
@@ -11727,7 +11788,6 @@ export function buildReviewRunStep(
11727
11788
  indented(stageExecution, indent) +
11728
11789
  indented(executionArtifact, indent) +
11729
11790
  indented(report, indent) +
11730
- indented(drift, indent) +
11731
11791
  indented(disarm, indent)
11732
11792
  );
11733
11793
  }
@@ -161,6 +161,8 @@ export interface UnmeasuredWorkflowOptions {
161
161
  * the defect #622 removed.
162
162
  */
163
163
  setupBunWith: string;
164
+ /** The step's `env:` block, from `setupBunEnv` (#2039). */
165
+ setupBunEnv: string;
164
166
  /** The published harness version the step runs through `bunx`. */
165
167
  version: string;
166
168
  }
@@ -230,6 +232,7 @@ jobs:
230
232
  - uses: ${opts.setupBun}
231
233
  with:
232
234
  ${opts.setupBunWith}
235
+ ${opts.setupBunEnv}
233
236
  - name: Record which kind of unmeasured each round was
234
237
  env:
235
238
  ${AI_REVIEW_UNMEASURED_REPO_VAR}: \${{ github.repository }}
@@ -67,12 +67,19 @@ import { localCalendarDay } from "../local-calendar-day";
67
67
  import { decideRuleWrite } from "../rule-provenance";
68
68
  import { rowDriftClause, ruleRowDrift } from "../rule-row-drift";
69
69
  import { actionRef } from "../workflow-actions";
70
+ import {
71
+ CI_JUNIT_SHARD_LEG,
72
+ CI_JUNIT_SINGLE_LEG,
73
+ ciJunitOutfile,
74
+ junitReporterFlags,
75
+ mayInstrumentJunit,
76
+ } from "../test-command-positions";
70
77
  import { ciSetupStep } from "../ci-setup-step";
71
78
  import { DEFAULT_PROFILE, isRuleIncluded, type ScaffoldProfile } from "./profiles";
72
79
  import { referencedPaths } from "../agents-md-refs";
73
80
  import { scanDocsDirectory } from "../doc-routing";
74
81
  import { inferredTestCommand, testCommandDecision } from "../test-command";
75
- import { declaredBunVersion, setupBunWith } from "../bun-version";
82
+ import { declaredBunVersion, setupBunEnv, setupBunWith } from "../bun-version";
76
83
  import { codeMapUnreferenced, unlistedSpecs } from "../spec-listing";
77
84
  import { censusReport, stampWorkflow, workflowBody, workflowCensus } from "./workflow-census";
78
85
  import {
@@ -3266,6 +3273,57 @@ echo "All $passed shards concluded, and all $passed passed."
3266
3273
  * shard whose evidence is UNMEASURED, and the honest place to say so is in
3267
3274
  * the leg that failed to write it.
3268
3275
  */
3276
+ // `ciJunitOutfile`, `CI_JUNIT_SHARD_LEG` and `CI_JUNIT_SINGLE_LEG` are
3277
+ // declared in `lib/test-command-positions.ts`, beside the selector that
3278
+ // STRIPS this suffix back out of a generated workflow (#1173, round 4 of
3279
+ // #1926). The reader has to know the exact path the writer emits or it
3280
+ // strips a consumer's own reporter flags instead — so there is one
3281
+ // declaration, and it lives next to the harder half.
3282
+
3283
+ /**
3284
+ * Keep the durations past the runner's lifetime, or there is no population.
3285
+ *
3286
+ * `lib/junit-checks.ts` has held `timeoutProximityViolations` and
3287
+ * `durationCoverageViolations` since #621 and neither had ever run against
3288
+ * this repository's suite: measured before this landed, `ci.yml` ran the
3289
+ * suite with no reporter, `bunfig.toml` declared none, and
3290
+ * `SUITE_JUNIT_REPORT` was set by nothing in the tree — so three live checks
3291
+ * printed UNMEASURED and passed on every CI run.
3292
+ *
3293
+ * **This step produces evidence and gates nothing.** Wiring
3294
+ * `scripts/suite-timeout-margin.ts` in is a separate decision, because it
3295
+ * would redden every pull request carrying a case at 80% of its budget and
3296
+ * nobody has yet seen how many that is.
3297
+ *
3298
+ * `if-no-files-found: warn`, deliberately unlike the shard marker's `error`:
3299
+ * the marker is the aggregate's input and its absence is a broken run, while
3300
+ * a missing report here means the suite died before writing one — which is
3301
+ * already red, and turning it into a second red names the wrong cause.
3302
+ *
3303
+ * Emitted only for a `bun test` command, because the flags that write the
3304
+ * file are only emitted for one.
3305
+ *
3306
+ * `leg` is the same suffix `ciJunitOutfile` took, so the artifact name and
3307
+ * the path it uploads cannot drift apart — and so the unsharded template
3308
+ * gets the step too.
3309
+ */
3310
+ export function buildJunitArtifactStep(indent: string, testCommand: string, leg: string): string {
3311
+ if (!mayInstrumentJunit(testCommand)) return "";
3312
+ const lines = [
3313
+ `# #1173. The per-case durations, kept so they can accumulate across`,
3314
+ `# runs — one run cannot say whether a case has regressed.`,
3315
+ `- name: Keep this run's per-case durations`,
3316
+ ` if: always()`,
3317
+ ` uses: ${actionRef("actions/upload-artifact")}`,
3318
+ ` with:`,
3319
+ ` name: rungate-junit-\${{ github.run_attempt }}${leg}`,
3320
+ ` path: ${ciJunitOutfile(leg)}`,
3321
+ ` if-no-files-found: warn`,
3322
+ ` retention-days: 14`,
3323
+ ];
3324
+ return `${lines.map(line => `${indent}${line}`).join("\n")}\n`;
3325
+ }
3326
+
3269
3327
  export function buildShardMarkerSteps(indent: string): string {
3270
3328
  const M = SHARD_MARKER_ENV;
3271
3329
  const dir = `\${{ runner.temp }}/rungate-shard-marker`;
@@ -3328,6 +3386,21 @@ function indentedScript(script: string, indent: string): string {
3328
3386
  */
3329
3387
  export { workflowOverrides } from "./managed-workflow";
3330
3388
 
3389
+ /**
3390
+ * The consumer's switch for whether an unmeasured global-tool install is
3391
+ * fatal. Read as this exact string and at no other value — see the emitted
3392
+ * comparison, and `.claude/rules/config-access.md` for why a loose read of a
3393
+ * gate-arming variable is a gate that arms itself by accident.
3394
+ */
3395
+ export const GLOBAL_TOOLS_REQUIRE_VAR = "RUNGATE_REQUIRE_GLOBAL_TOOLS";
3396
+
3397
+ /**
3398
+ * The one declaring position for the refusal's exit code, so a test can build
3399
+ * a mutant with it set to `0` and watch the refusal stop refusing. A second
3400
+ * literal elsewhere would bypass that mutation and read as covered.
3401
+ */
3402
+ export const GLOBAL_TOOLS_REQUIRED_EXIT = 1;
3403
+
3331
3404
  export function globalToolInstallStep(ci: unknown, indent = " "): GlobalToolDecision {
3332
3405
  const declared = (ci as { globalTools?: unknown } | null | undefined)?.globalTools;
3333
3406
  const entries =
@@ -3362,15 +3435,42 @@ export function globalToolInstallStep(ci: unknown, indent = " "): GlobalToo
3362
3435
  // the single quotes would have to defend against, which is what makes
3363
3436
  // neither defence a place for the other to be relaxed.
3364
3437
  const specs = pins.map(p => `'${p.package}@${p.version}'`).join(" ");
3438
+ const body = `${indent} `;
3365
3439
  return {
3366
- // The versions appear on the `run:` line and nowhere else in the emitted
3367
- // YAML, so a test asserting the pin is asserting the command rather than
3368
- // a comment that happens to quote it.
3440
+ // The versions appear on the `npm install -g` line and nowhere else in the
3441
+ // emitted YAML — not in the annotations, which are fixed prose — so a test
3442
+ // asserting the pin is asserting the command rather than a comment that
3443
+ // happens to quote it, and the refused-declaration sanitiser keeps exactly
3444
+ // the one interpolation site it had before.
3369
3445
  step:
3370
3446
  `\n${indent}# Pinned by ci.globalTools in .claude/rungate/config.json — one declaration (#597).` +
3371
3447
  (rejected.length === 0 ? "" : `\n${indent}#${refusals}`) +
3448
+ `\n${indent}# A failed install is UNMEASURED, not fatal. lib/compliance.ts probes each tool` +
3449
+ `\n${indent}# and reports reading=UNMEASURED naming the ones it cannot reach, so the checks` +
3450
+ `\n${indent}# that need them already decline to pass without them. On 2026-11-08 agnix's` +
3451
+ `\n${indent}# binary host answered 504 for hours while the npm registry was fine, and this` +
3452
+ `\n${indent}# step — the only part of the pipeline that treated an absent tool as fatal —` +
3453
+ `\n${indent}# stopped every merge in the repository. A host that is down does not make the` +
3454
+ `\n${indent}# tree wrong; it makes three checks unmeasured, and that is what gets said.` +
3372
3455
  `\n${indent}- name: Install pinned global tools` +
3373
- `\n${indent} run: npm install -g ${specs}`,
3456
+ `\n${indent} env:` +
3457
+ // Resolved inside `run:`, never in an `if:`: a step skipped by `if:`
3458
+ // reports SKIPPED, and a skipped required check reads as satisfied
3459
+ // (`.claude/rules/config-access.md`).
3460
+ `\n${indent} ${GLOBAL_TOOLS_REQUIRE_VAR}: \${{ vars.${GLOBAL_TOOLS_REQUIRE_VAR} }}` +
3461
+ `\n${indent} run: |` +
3462
+ `\n${body}set -uo pipefail` +
3463
+ `\n${body}status=0` +
3464
+ `\n${body}npm install -g ${specs} || status=$?` +
3465
+ `\n${body}if [ "$status" -eq 0 ]; then exit 0; fi` +
3466
+ // Read as the exact string and at no other value. A loose reading of a
3467
+ // variable that turns a gate on is a gate that turns itself on by
3468
+ // accident.
3469
+ `\n${body}if [ "\${${GLOBAL_TOOLS_REQUIRE_VAR}:-}" = "true" ]; then` +
3470
+ `\n${body} echo "::error title=Global tools UNMEASURED::npm install -g exited $status, so the tools pinned by ci.globalTools are absent from this runner and the checks that shell out to them measured nothing. ${GLOBAL_TOOLS_REQUIRE_VAR} is the exact string 'true', so this repository has declared an unmeasured run fatal."` +
3471
+ `\n${body} exit ${GLOBAL_TOOLS_REQUIRED_EXIT}` +
3472
+ `\n${body}fi` +
3473
+ `\n${body}echo "::warning title=Global tools UNMEASURED::npm install -g exited $status, so the tools pinned by ci.globalTools are absent from this runner. THIS IS NOT A PASS for the checks that shell out to them: lib/compliance.ts probes each tool and reports reading=UNMEASURED, naming the ones it could not reach. The suite continues, because a tool host that is unreachable does not make this tree wrong. Set the repository variable ${GLOBAL_TOOLS_REQUIRE_VAR} to the exact string 'true' to make this step fatal instead."`,
3374
3474
  pins,
3375
3475
  reason: `ci.globalTools pins ${pins.map(p => `${p.package}@${p.version}`).join(", ")}`,
3376
3476
  rejected,
@@ -3793,9 +3893,10 @@ ${baseRefStep}
3793
3893
  - uses: ${actionRef("oven-sh/setup-bun")}
3794
3894
  with:
3795
3895
  ${bunStep}
3896
+ ${setupBunEnv(" ")}
3796
3897
  - run: bun install${globalTools.step}${ciSetupStep()}
3797
- - run: ${test.command} --shard=\${{ matrix.shard }}/${shards}${trackerTokenEnv}${typecheckStep}
3798
- ${buildShardMarkerSteps(" ")}
3898
+ - run: ${test.command} --shard=\${{ matrix.shard }}/${shards}${junitReporterFlags(test.command, ciJunitOutfile(CI_JUNIT_SHARD_LEG))}${trackerTokenEnv}${typecheckStep}
3899
+ ${buildJunitArtifactStep(" ", test.command, CI_JUNIT_SHARD_LEG)}${buildShardMarkerSteps(" ")}
3799
3900
 
3800
3901
  # The aggregate. Named "test" because that is the context branch protection
3801
3902
  # requires; it exists to turn N shard results into the one verdict.
@@ -3881,9 +3982,10 @@ ${baseRefStep}
3881
3982
  - uses: ${actionRef("oven-sh/setup-bun")}
3882
3983
  with:
3883
3984
  ${bunStep}
3985
+ ${setupBunEnv(" ")}
3884
3986
  - run: bun install${globalTools.step}${ciSetupStep()}
3885
- - run: ${test.command}${trackerTokenEnv}${typecheckStep}
3886
- `;
3987
+ - run: ${test.command}${junitReporterFlags(test.command, ciJunitOutfile(CI_JUNIT_SINGLE_LEG))}${trackerTokenEnv}${typecheckStep}
3988
+ ${buildJunitArtifactStep(" ", test.command, CI_JUNIT_SINGLE_LEG)}`;
3887
3989
 
3888
3990
  const gatesYml = `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
3889
3991
  name: Gates
@@ -3918,6 +4020,7 @@ ${checkoutStep}
3918
4020
  - uses: ${actionRef("oven-sh/setup-bun")}
3919
4021
  with:
3920
4022
  ${bunStep}
4023
+ ${setupBunEnv(" ")}
3921
4024
  - run: bun install
3922
4025
  - name: Conformity + spec drift
3923
4026
  run: bun test test/scaffold-conformity.test.ts
@@ -4162,6 +4265,8 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
4162
4265
  // The same single declaration the test and gates jobs resolve from
4163
4266
  // (#622), at the indent this job's step bodies use.
4164
4267
  setupBunWith: setupBunWith(declaredBunVersion(root), " "),
4268
+ // #2039, at the indent of the step's own keys.
4269
+ setupBunEnv: setupBunEnv(" "),
4165
4270
  },
4166
4271
  // #1013. The GENERATING version, and the same reading `harnessDevDepRange`
4167
4272
  // takes — one function, so a scaffold cannot write a `bunx rungate@X` next
@@ -4188,6 +4293,7 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
4188
4293
  // The same `bunStep` the three jobs above render, at the same indent and
4189
4294
  // from the same single declaration (#622).
4190
4295
  setupBunWith: bunStep,
4296
+ setupBunEnv: setupBunEnv(" "),
4191
4297
  version: harnessVersion(),
4192
4298
  });
4193
4299
 
@@ -0,0 +1,108 @@
1
+ /**
2
+ * One way to list the source files a census claims to police.
3
+ *
4
+ * Covers SC-2732, SC-2733 (specs/BOARD-FLOW-SPEC.md).
5
+ *
6
+ * ## Why this is a module and not a `readdirSync`
7
+ *
8
+ * Several census tests spelled the same line:
9
+ *
10
+ * ```ts
11
+ * for (const f of readdirSync(join(ROOT, dir))) if (f.endsWith(".ts")) …
12
+ * ```
13
+ *
14
+ * `readdirSync` does not recurse, and a directory entry fails
15
+ * `endsWith(".ts")`, so every file under `lib/generators/`, `lib/scaffold/`
16
+ * and `lib/validators/` was dropped **without a word**. Eighteen files sat
17
+ * outside populations that reported themselves clean.
18
+ *
19
+ * That is the failure mode in `.claude/rules/checks-must-be-able-to-fail.md`
20
+ * where the instrument is narrower than the thing it detects — and worse
21
+ * here than usual, because these particular censuses exist to assert a
22
+ * property over N sites rather than repair them one at a time. A census
23
+ * with a hole in its population is the defect it was written to prevent,
24
+ * wearing the shape of the prevention.
25
+ *
26
+ * Measured 2026-11-06, before the fix: of fourteen test files calling
27
+ * `readdirSync`, seven already recursed, two scanned directories other than
28
+ * these, and five scanned `lib/` or `scripts/` flat.
29
+ * `test/selection-path-safety.test.ts` is the honest one of the five — its
30
+ * case is named "no file **directly under** scripts/", so it declares the
31
+ * narrow scope rather than claiming the whole tree.
32
+ *
33
+ * ## It returns paths, not names
34
+ *
35
+ * A census that joined a bare filename onto its directory could not express
36
+ * `generators/types.ts`, so the return value is repo-relative and the
37
+ * caller never rebuilds a path. The one exception a caller still needs —
38
+ * "only the top level" — is a parameter rather than a second function,
39
+ * because two listers is how the first hole appeared.
40
+ */
41
+
42
+ import { readdirSync } from "fs";
43
+ import { join } from "path";
44
+
45
+ /**
46
+ * The only read error `sourceFiles` absorbs. One exported site, so a
47
+ * mutation can widen it and a case can observe that it did.
48
+ */
49
+ export const ABSENT_DIRECTORY = "ENOENT";
50
+
51
+ export interface SourceCensusOptions {
52
+ /** File extension to keep, with the dot. */
53
+ readonly ext?: string;
54
+ /**
55
+ * Stop at the top level.
56
+ *
57
+ * **For a census that SAYS it is top-level only**, like
58
+ * `test/selection-path-safety.test.ts`, whose case is named for it. Not a
59
+ * convenience: passing this to avoid dealing with a subdirectory
60
+ * reintroduces the hole, and the case name is the only thing that makes
61
+ * it honest.
62
+ */
63
+ readonly topLevelOnly?: boolean;
64
+ }
65
+
66
+ /**
67
+ * Every source file under `dirs`, repo-relative, sorted.
68
+ *
69
+ * A directory that does not **exist** is skipped rather than thrown on: a
70
+ * census naming a directory the tree has not got should fail on its own
71
+ * empty population, with its own message, not on an `ENOENT` from here.
72
+ *
73
+ * **Every other read error is rethrown**, and the narrowness is the whole
74
+ * point. A bare `catch { return; }` here is the fail-open shape in
75
+ * `.claude/rules/checks-must-be-able-to-fail.md` — an `EACCES`, an `EMFILE`
76
+ * part-way through a large walk, or a `dirs` entry that is a file rather
77
+ * than a directory would shrink the population with no signal, and a short
78
+ * population is indistinguishable from a clean one to every caller. Worse
79
+ * now than before the fix: this is the single binding all of them read, so
80
+ * one absorbed error goes quiet across every census at once.
81
+ */
82
+ export function sourceFiles(
83
+ root: string,
84
+ dirs: readonly string[],
85
+ options: SourceCensusOptions = {},
86
+ ): string[] {
87
+ const ext = options.ext ?? ".ts";
88
+ const out: string[] = [];
89
+ const walk = (rel: string): void => {
90
+ let entries;
91
+ try {
92
+ entries = readdirSync(join(root, rel), { withFileTypes: true });
93
+ } catch (e) {
94
+ if ((e as NodeJS.ErrnoException).code !== ABSENT_DIRECTORY) throw e;
95
+ return;
96
+ }
97
+ for (const e of entries) {
98
+ const path = `${rel}/${e.name}`;
99
+ if (e.isDirectory()) {
100
+ if (!options.topLevelOnly) walk(path);
101
+ continue;
102
+ }
103
+ if (e.name.endsWith(ext)) out.push(path);
104
+ }
105
+ };
106
+ for (const dir of dirs) walk(dir);
107
+ return out.sort();
108
+ }