rungate 0.8.0 → 0.8.2

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 (73) hide show
  1. package/gates/.gate-salt +1 -0
  2. package/gates/SCHEMA-GUIDE.md +485 -0
  3. package/gates/ac-quality.test.ts +106 -0
  4. package/gates/adversarial.test.ts +283 -0
  5. package/gates/brief-assembler.test.ts +487 -0
  6. package/gates/brief-assembler.ts +448 -0
  7. package/gates/bunfig.toml +2 -0
  8. package/gates/chain.test.ts +91 -0
  9. package/gates/e2e-smoke.test.ts +234 -0
  10. package/gates/error-classifier.test.ts +250 -0
  11. package/gates/error-classifier.ts +99 -0
  12. package/gates/gate-executor.ts +3071 -0
  13. package/gates/orchestrator.test.ts +968 -0
  14. package/gates/orchestrator.ts +827 -0
  15. package/gates/preload.ts +89 -0
  16. package/gates/prompts/ac-adversary.md +20 -0
  17. package/gates/prompts/evidence-validator.md +22 -0
  18. package/gates/prompts/prove-reproducer.md +53 -0
  19. package/gates/prompts.sha256 +3 -0
  20. package/gates/prove.test.ts +164 -0
  21. package/gates/rook-state.test.ts +108 -0
  22. package/gates/run-attribution.ts +290 -0
  23. package/gates/run-gate.ts +163 -0
  24. package/gates/schema-parity.test.ts +378 -0
  25. package/gates/schema.ts +1209 -0
  26. package/gates/self-heal.test.ts +511 -0
  27. package/gates/self-heal.ts +125 -0
  28. package/gates/ship-orchestrator.test.ts +399 -0
  29. package/gates/ship-orchestrator.ts +384 -0
  30. package/gates/spec-compliance-probe.ts +159 -0
  31. package/gates/test-fixtures/broken-no-environments.json +110 -0
  32. package/gates/test-fixtures/consumer-directory-layout.json +90 -0
  33. package/gates/test-fixtures/valid-standard.json +91 -0
  34. package/gates/test-utils.ts +43 -0
  35. package/gates/typecheck-gate.ts +111 -0
  36. package/gates/witness.ts +349 -0
  37. package/gates/workflow.test.ts +2018 -0
  38. package/hooks/BashWriteGuard.hook.ts +19 -0
  39. package/hooks/GateResultProtection.hook.ts +27 -1
  40. package/hooks/VerifyPhaseLock.hook.ts +51 -11
  41. package/hooks/WorkflowStateGuard.hook.ts +24 -0
  42. package/lib/ai-review-rounds.ts +462 -0
  43. package/lib/bash-file-read.ts +17 -3
  44. package/lib/bash-write-guard.ts +1285 -50
  45. package/lib/distribution-standing.ts +75 -4
  46. package/lib/failure-intake.ts +12 -4
  47. package/lib/file-extensions.ts +81 -0
  48. package/lib/finding-arbiter.ts +1015 -0
  49. package/lib/finding-jury.ts +537 -0
  50. package/lib/gate-enforcement.ts +171 -43
  51. package/lib/gate-result-protection.ts +12 -2
  52. package/lib/generators/code-map.ts +55 -4
  53. package/lib/generators/types.ts +27 -1
  54. package/lib/github.ts +55 -0
  55. package/lib/interpreters.ts +64 -0
  56. package/lib/issue-create-override.ts +69 -8
  57. package/lib/issue-filing-gate.ts +605 -0
  58. package/lib/js-top-level-code.ts +20 -2
  59. package/lib/junit-checks.ts +239 -1
  60. package/lib/package-closure.ts +114 -0
  61. package/lib/publish-window.ts +287 -0
  62. package/lib/scaffold/ai-review-findings.ts +142 -3
  63. package/lib/scaffold/ai-review-step.ts +1012 -18
  64. package/lib/scaffold/managed-workflow.ts +163 -4
  65. package/lib/scaffold/steps.ts +498 -22
  66. package/lib/scanner.ts +13 -4
  67. package/lib/ticked-sc-symbols.ts +361 -0
  68. package/lib/transcript-checker.ts +6 -0
  69. package/lib/workflow-actions.ts +18 -0
  70. package/package.json +3 -1
  71. package/scripts/arbitrate-finding.ts +224 -0
  72. package/scripts/generate-code-map.ts +18 -10
  73. package/scripts/sync-sc-status.ts +82 -8
@@ -9,6 +9,7 @@
9
9
  */
10
10
  import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, statSync } from "fs";
11
11
  import { readdirSorted } from "../readdir-sorted";
12
+ import { fileExtensions } from "../file-extensions";
12
13
  import { join, basename, dirname, resolve, sep } from "path";
13
14
  import { auditSpecs } from "../../scripts/audit-specs";
14
15
  import { generateAgentsMd as buildAgentsMdContent, generateScopedRules } from "../generators/agents-md";
@@ -35,6 +36,7 @@ import {
35
36
  import { PRE_PUSH_MANAGED_MARKER, prePushHookScript } from "./pre-push-hook";
36
37
  import {
37
38
  AI_REVIEW_JOB,
39
+ AI_REVIEW_PULL_REQUEST_TYPES,
38
40
  aiReviewScaffoldAction,
39
41
  buildAuthDetectStep,
40
42
  buildOutcomesHeader,
@@ -1556,19 +1558,21 @@ export function generateCodeMapStep(
1556
1558
  function generateCodeMapInline(root: string, outPath: string, actions: string[]): void {
1557
1559
  const name = basename(root);
1558
1560
  const skip = new Set(["node_modules", ".git", "reference", "dist", "build", ".next", ".fallow"]);
1559
- const dirs: Array<{ name: string; fileCount: number; types: string[] }> = [];
1561
+ const dirs: Array<{ name: string; types: string[] }> = [];
1560
1562
  for (const entry of readdirSorted(root)) {
1561
1563
  if (entry.startsWith(".") && entry !== ".claude") continue;
1562
1564
  if (skip.has(entry)) continue;
1563
1565
  const full = join(root, entry);
1564
1566
  try {
1565
1567
  if (!statSync(full).isDirectory()) continue;
1566
- const files = readdirSorted(full, { recursive: true });
1567
- const exts = new Set(files.map(f => f.split(".").pop()).filter((e): e is string => Boolean(e)));
1568
- dirs.push({ name: entry, fileCount: files.length, types: [...exts].slice(0, 5) });
1568
+ // One binding for what a "type" is, shared with `lib/scanner.ts` and
1569
+ // `scripts/generate-code-map.ts` (#1200). This is the fallback that
1570
+ // runs when the script is unavailable, so a copy here reintroduces
1571
+ // whatever the other two fix.
1572
+ dirs.push({ name: entry, types: fileExtensions(full) });
1569
1573
  } catch {}
1570
1574
  }
1571
- dirs.sort((a, b) => b.fileCount - a.fileCount);
1575
+ // Unsorted. Row order is `directoryTable`'s single decision (#1163).
1572
1576
 
1573
1577
  let deps = 0, devDeps = 0;
1574
1578
  const pkgPath = join(root, "package.json");
@@ -2676,13 +2680,23 @@ export function writeManagedFile(
2676
2680
  * and it would be wrong the first time a different sub-key joins the map.
2677
2681
  */
2678
2682
  function revocationActions(label: string, revoked: readonly RevokedSubKey[]): string[] {
2679
- return revoked.map(
2680
- r =>
2681
- `REVOKED: ${label} no longer declares \`${r.section}: ${r.key}\` — the harness ` +
2682
- `computes that sub-key and this project's \`ci\` config no longer produces it, so ` +
2683
- `the grant has nothing left to justify it. Name \`${r.section}\` in ` +
2684
- `\`ci.workflowOverrides\` to keep it, and re-scaffold.`,
2685
- );
2683
+ return revoked.map(r => {
2684
+ // The override hatch is named per TOP-LEVEL key, so an authored path
2685
+ // (`on.pull_request`) has to advise `on` and not the path it was found
2686
+ // at. Advice naming a key `ci.workflowOverrides` would reject is worse
2687
+ // than none: the consumer follows it and the filter goes anyway.
2688
+ const topLevel = r.section.split(".")[0];
2689
+ const keep =
2690
+ `Name \`${topLevel}\` in \`ci.workflowOverrides\` to keep it, and re-scaffold.`;
2691
+ return r.reason === "authored"
2692
+ ? `REVOKED: ${label} no longer declares \`${r.section}: ${r.key}\` — the harness ` +
2693
+ `authors that path and this version of the generator does not emit it, so the ` +
2694
+ `value here is one the harness itself wrote and has since changed its mind ` +
2695
+ `about. ${keep}`
2696
+ : `REVOKED: ${label} no longer declares \`${r.section}: ${r.key}\` — the harness ` +
2697
+ `computes that sub-key and this project's \`ci\` config no longer produces it, so ` +
2698
+ `the grant has nothing left to justify it. ${keep}`;
2699
+ });
2686
2700
  }
2687
2701
 
2688
2702
  /** One globally installed CI tool, and the exact version it is pinned to. */
@@ -2789,6 +2803,397 @@ export function shardCount(ci: unknown): number {
2789
2803
  return Math.min(raw, 32);
2790
2804
  }
2791
2805
 
2806
+ /**
2807
+ * The one non-zero exit the shard aggregate ever takes (#1181).
2808
+ *
2809
+ * Declared once, and spelled nowhere else in the script, so
2810
+ * `test/ci-shard-aggregate-measured.test.ts` can build a mutant copy with it
2811
+ * set to `0` and prove each refusal is the thing the case observed rather
2812
+ * than something that happened to be red —
2813
+ * `.claude/rules/checks-must-be-able-to-fail.md`, "For a script whose job is
2814
+ * to exit non-zero".
2815
+ */
2816
+ export const SHARD_AGGREGATE_REFUSAL_EXIT = 1;
2817
+
2818
+ /**
2819
+ * Environment variable names the shard aggregate's script reads (#1181).
2820
+ *
2821
+ * The script contains **no `${{ }}` expression at all**. Every GitHub-side
2822
+ * value arrives through the step's `env:`, which is what makes the shipped
2823
+ * script text executable by a test that plants a marker directory on disk. A
2824
+ * script that can only run inside Actions is a script no negative control can
2825
+ * reach, and the negative control is the whole of #1181.
2826
+ */
2827
+ export const SHARD_AGGREGATE_ENV = {
2828
+ rollup: "SHARD_ROLLUP",
2829
+ expected: "SHARD_EXPECTED",
2830
+ jobName: "SHARD_JOB_NAME",
2831
+ attempt: "SHARD_ATTEMPT",
2832
+ markerDir: "SHARD_MARKER_DIR",
2833
+ } as const;
2834
+
2835
+ /**
2836
+ * Environment variable names the per-shard marker step writes from (#1190).
2837
+ *
2838
+ * Separate from `SHARD_AGGREGATE_ENV` because they are read on the other side
2839
+ * of the fan-in, by a different job, and a single map would suggest one step
2840
+ * sets them all.
2841
+ */
2842
+ export const SHARD_MARKER_ENV = {
2843
+ index: "SHARD_INDEX",
2844
+ status: "SHARD_STATUS",
2845
+ attempt: "SHARD_ATTEMPT",
2846
+ dir: "SHARD_MARKER_DIR",
2847
+ } as const;
2848
+
2849
+ /**
2850
+ * The artifact name one shard's marker is uploaded under (#1190).
2851
+ *
2852
+ * The full name is `<prefix><run_attempt>-<shard>`, and **both** halves are
2853
+ * load-bearing.
2854
+ *
2855
+ * `<shard>` because v4 artifacts are immutable and names must be unique
2856
+ * within a run — the shape `actions/upload-artifact`'s own README prescribes
2857
+ * for a matrix.
2858
+ *
2859
+ * `<run_attempt>` because **artifacts are scoped to the RUN, not the
2860
+ * attempt**, and that was measured rather than assumed. On run `39835866754`
2861
+ * a two-leg matrix was re-run with "Re-run failed jobs"; on attempt 2 the
2862
+ * aggregate's download reported `Found 2 artifact(s)` and read
2863
+ * `shard-1 => success attempt=1` — evidence written by a leg that **did not
2864
+ * execute in attempt 2 at all**. Without the attempt in the name, a re-run in
2865
+ * which a leg never executes reads that leg's stale `success` as proof it
2866
+ * ran, which is #1181 reintroduced with a required check gone green over
2867
+ * shards that did not run.
2868
+ *
2869
+ * The aggregate matches on the prefix rather than enumerating names, so the
2870
+ * two sides agree through this one declaration instead of through two copies
2871
+ * of a loop bound. It downloads EVERY attempt's artifacts deliberately: a
2872
+ * pattern narrowed to this attempt would make a stale leg indistinguishable
2873
+ * from a leg that never ran, and those want different sentences.
2874
+ */
2875
+ export const SHARD_MARKER_ARTIFACT_PREFIX = "rungate-shard-marker-";
2876
+
2877
+ /** The file one shard writes inside its marker directory, by index. */
2878
+ export const SHARD_MARKER_FILE_PREFIX = "shard-";
2879
+
2880
+ /**
2881
+ * The shard aggregate's verdict script — it asserts that it MEASURED (#1181).
2882
+ *
2883
+ * ## What went wrong
2884
+ *
2885
+ * PR #1154 merged on run `39799846607`. `test-shard (1)`, `(2)` and `(3)` were
2886
+ * `queued` with `completed_at: null` and **no conclusion**; only shard 4 ran.
2887
+ * The aggregate read `needs.test-shard.result` as `success`, printed "All 4
2888
+ * shards passed", and went green in three seconds. `test` is a required check
2889
+ * and auto-merge is armed repo-wide, so a quarter of the suite authorised the
2890
+ * merge. The three preceding `main` runs were 4/4 — this was an anomaly, not
2891
+ * the pattern, and **the cause of the non-conclusion is unknown**. A fix that
2892
+ * depended on knowing it would not be a fix.
2893
+ *
2894
+ * `if: always()` was added so a **failed or cancelled** shard still reaches
2895
+ * this job. It does nothing about a shard that never concludes, because
2896
+ * `needs.<job>.result` collapses a whole matrix into one word and that word
2897
+ * was `success`.
2898
+ *
2899
+ * ## What this does instead
2900
+ *
2901
+ * The rollup is still read first, so a failed or a cancelled shard produces
2902
+ * exactly the diagnostic it produces today. Then the job counts the markers
2903
+ * the shards wrote **about themselves** — one tiny artifact per matrix leg,
2904
+ * uploaded by the leg as its last step — and refuses unless there is one per
2905
+ * declared shard and every one of them says `success`. The printed count is
2906
+ * the measured one, never the generated one: a sentence that says "4" because
2907
+ * the generator wrote "4" is the thing that lied on `39799846607`.
2908
+ *
2909
+ * Every reading that cannot be taken is a refusal. No marker directory, a
2910
+ * missing marker, an unreadable marker, a malformed count — all exit
2911
+ * non-zero, because UNMEASURED is not a pass.
2912
+ *
2913
+ * ## Why not the Actions API (#1190)
2914
+ *
2915
+ * #1189 answered the same question with `gh api …/jobs`, which worked and
2916
+ * cost every consumer two things the generated `test` job never needed
2917
+ * before: **`gh` on the runner image**, which is a GitHub-hosted-image fact
2918
+ * and not a runner fact — a self-hosted or container `runs-on`, which
2919
+ * `ci.runner` lets a consumer choose, has no `gh` — and **`actions: read` on
2920
+ * the job's token**. A marker needs neither. The runner reaches the artifact
2921
+ * service for the run it is already in, so upload and same-run download take
2922
+ * no `permissions:` scope and no token at all (`actions/download-artifact`'s
2923
+ * README: a `github-token` and `actions: read` are "required when downloading
2924
+ * artifacts from a different repository or from a different workflow run").
2925
+ *
2926
+ * A marker is also strictly better evidence than a conclusion. The API says
2927
+ * what GitHub recorded about a job; a marker is a file the job's own shell
2928
+ * wrote, so a leg that was created and then never executed leaves nothing
2929
+ * behind — which is exactly `39799846607`'s three queued shards.
2930
+ *
2931
+ * And the poll is gone with it. It existed for API propagation lag; a marker
2932
+ * uploaded before the leg concluded is downloadable the moment `needs` lets
2933
+ * this job start, so there is no lag to wait out and no `SHARD_POLL_*` knob
2934
+ * to surface in config.
2935
+ */
2936
+ export function buildShardAggregateScript(): string {
2937
+ const E = SHARD_AGGREGATE_ENV;
2938
+ return `set -uo pipefail
2939
+
2940
+ # 1. The rollup, read exactly as it is read today. A failed or a cancelled
2941
+ # shard reaches this job through \`if: always()\` and refuses here, with
2942
+ # the same sentence it has always printed.
2943
+ rollup="\${${E.rollup}:-}"
2944
+ if [ "$rollup" != "success" ]; then
2945
+ echo "::error::test-shard concluded '$rollup' — the suite is not green."
2946
+ exit ${SHARD_AGGREGATE_REFUSAL_EXIT}
2947
+ fi
2948
+
2949
+ # 2. A success rollup is not a measurement. Everything below establishes how
2950
+ # many shards this run actually EXECUTED (#1181).
2951
+ expected="\${${E.expected}:-}"
2952
+ case "$expected" in
2953
+ "" | *[!0-9]*)
2954
+ echo "::error::${E.expected} is '$expected', which is not a shard count. UNMEASURED, so refusing."
2955
+ exit ${SHARD_AGGREGATE_REFUSAL_EXIT}
2956
+ ;;
2957
+ esac
2958
+ if [ "$expected" -lt 1 ]; then
2959
+ echo "::error::${E.expected} is $expected, so this job would assert nothing. UNMEASURED, so refusing."
2960
+ exit ${SHARD_AGGREGATE_REFUSAL_EXIT}
2961
+ fi
2962
+
2963
+ job_name="\${${E.jobName}:-test-shard}"
2964
+
2965
+ # 3. THIS attempt. Artifacts belong to the run, not the attempt — measured on
2966
+ # run 39835866754, where attempt 2's download reported \`Found 2
2967
+ # artifact(s)\` and handed back a marker a leg wrote in attempt 1 and never
2968
+ # rewrote, because that leg did not execute in attempt 2 at all. Reading it
2969
+ # as evidence about attempt 2 is #1181 with a required check green over
2970
+ # shards that did not run, so the attempt is part of what gets checked.
2971
+ attempt="\${${E.attempt}:-}"
2972
+ case "$attempt" in
2973
+ "" | *[!0-9]*)
2974
+ echo "::error::${E.attempt} is '$attempt', which is not a run attempt, so no marker can be dated. UNMEASURED, so refusing."
2975
+ exit ${SHARD_AGGREGATE_REFUSAL_EXIT}
2976
+ ;;
2977
+ esac
2978
+
2979
+ # 4. The evidence, written by the shards about THEMSELVES. Each leg's last
2980
+ # step writes one file naming its own status and uploads it; a leg that
2981
+ # was created and never executed uploads nothing, and nothing is exactly
2982
+ # what run 39799846607's three queued shards would have left (#1190).
2983
+ dir="\${${E.markerDir}:-}"
2984
+ if [ -z "$dir" ]; then
2985
+ echo "::error::${E.markerDir} is unset, so this job has nowhere to read the shards' own evidence."
2986
+ echo "::error::the shard count is UNMEASURED, which is not a pass. Refusing."
2987
+ exit ${SHARD_AGGREGATE_REFUSAL_EXIT}
2988
+ fi
2989
+ if [ ! -d "$dir" ]; then
2990
+ # The download produced nothing at all. This is the one branch most likely
2991
+ # to be written fail-open — the download step is \`continue-on-error\` so
2992
+ # that the refusal is THIS script's, with a sentence, rather than the
2993
+ # action's bare red — and fail-open here reproduces the defect exactly.
2994
+ echo "::error::no shard markers were downloaded: '$dir' does not exist, so not one of the $expected shards left evidence that it ran."
2995
+ echo "::error::the shard count is UNMEASURED, which is not a pass. Refusing."
2996
+ exit ${SHARD_AGGREGATE_REFUSAL_EXIT}
2997
+ fi
2998
+
2999
+ # Every artifact directory belonging to THIS attempt. Counted off the disk
3000
+ # rather than off the 1..expected walk below, so a leg that contributed more
3001
+ # than its own evidence disagrees out loud instead of being skipped by a loop
3002
+ # that only looks where it expects.
3003
+ found=0
3004
+ for art in "$dir"/${SHARD_MARKER_ARTIFACT_PREFIX}"$attempt"-*; do
3005
+ [ -d "$art" ] || continue
3006
+ found=$((found + 1))
3007
+ done
3008
+
3009
+ passed=0
3010
+ missing=0
3011
+ stale=0
3012
+ unbound=0
3013
+ detail=""
3014
+ n=1
3015
+ while [ "$n" -le "$expected" ]; do
3016
+ want="${SHARD_MARKER_FILE_PREFIX}$n"
3017
+ art="$dir/${SHARD_MARKER_ARTIFACT_PREFIX}$attempt-$n"
3018
+
3019
+ if [ ! -d "$art" ]; then
3020
+ # No evidence from this attempt. Evidence from an EARLIER one is not
3021
+ # evidence about this one, but it is a different diagnosis and gets a
3022
+ # different sentence: a partial re-run leaves exactly this state for
3023
+ # every leg GitHub chose not to re-run.
3024
+ older=""
3025
+ for cand in "$dir"/${SHARD_MARKER_ARTIFACT_PREFIX}*-"$n"; do
3026
+ [ -d "$cand" ] || continue
3027
+ older="$older \${cand##*/}"
3028
+ done
3029
+ if [ -n "$older" ]; then
3030
+ stale=$((stale + 1))
3031
+ detail="$detail \\"$job_name ($n)\\"=only-from:$older"
3032
+ else
3033
+ missing=$((missing + 1))
3034
+ detail="$detail \\"$job_name ($n)\\"=no-marker"
3035
+ fi
3036
+ n=$((n + 1))
3037
+ continue
3038
+ fi
3039
+
3040
+ # One artifact carries one leg's marker and nothing else. The upload names
3041
+ # a single FILE, so this can only fail if something upstream changed —
3042
+ # which is the point: "each leg produced its own marker" is the claim, and
3043
+ # a flattened directory read by filename alone does not measure it.
3044
+ files=0
3045
+ for f in "$art"/*; do
3046
+ [ -f "$f" ] || continue
3047
+ files=$((files + 1))
3048
+ done
3049
+ if [ "$files" -ne 1 ] || [ ! -f "$art/$want" ]; then
3050
+ unbound=$((unbound + 1))
3051
+ detail="$detail \\"$job_name ($n)\\"=artifact-holds-$files-file\\(s\\)-not-just-$want"
3052
+ n=$((n + 1))
3053
+ continue
3054
+ fi
3055
+
3056
+ # \`|| true\` rather than a bare \`read\`. GitHub runs a \`run:\` block as
3057
+ # \`bash -e\`, and under errexit a \`read\` that returns non-zero aborts the
3058
+ # shell THERE — so the handlers below never run and the operator gets a red
3059
+ # job with no sentence saying why. Measured in #1191 on this same step.
3060
+ mstatus=""
3061
+ mattempt=""
3062
+ mshard=""
3063
+ read -r mstatus mattempt mshard < "$art/$want" || true
3064
+
3065
+ # The body is the SECOND binding, independent of the name. A name is a
3066
+ # convention the generator controls; a body is a reading. A generator bug
3067
+ # that templates the wrong attempt into the name is caught here and only
3068
+ # here — which is why adding the attempt to the name alone is not the fix.
3069
+ if [ "$mattempt" != "$attempt" ] || [ "$mshard" != "$n" ]; then
3070
+ unbound=$((unbound + 1))
3071
+ detail="$detail \\"$job_name ($n)\\"=marker-says-attempt-'$mattempt'-shard-'$mshard'"
3072
+ n=$((n + 1))
3073
+ continue
3074
+ fi
3075
+
3076
+ case "$mstatus" in
3077
+ success) passed=$((passed + 1)) ;;
3078
+ "") detail="$detail \\"$job_name ($n)\\"=empty-marker" ;;
3079
+ *) detail="$detail \\"$job_name ($n)\\"=$mstatus" ;;
3080
+ esac
3081
+ n=$((n + 1))
3082
+ done
3083
+
3084
+ if [ "$missing" -ne 0 ]; then
3085
+ echo "::error::$missing of $expected shards left NO marker, so they never executed:$detail"
3086
+ echo "::error::a shard that never ran is UNMEASURED, not a pass — this is #1181, where three of four were queued and the aggregate went green."
3087
+ exit ${SHARD_AGGREGATE_REFUSAL_EXIT}
3088
+ fi
3089
+
3090
+ if [ "$stale" -ne 0 ]; then
3091
+ echo "::error::$stale of $expected shards left no marker for attempt $attempt, only for an earlier one:$detail"
3092
+ echo "::error::artifacts belong to the RUN, not the attempt, so an older marker is readable here and says nothing about attempt $attempt. Re-run ALL jobs — a partial re-run leaves the legs it did not re-run UNMEASURED, and UNMEASURED is not a pass."
3093
+ exit ${SHARD_AGGREGATE_REFUSAL_EXIT}
3094
+ fi
3095
+
3096
+ if [ "$unbound" -ne 0 ]; then
3097
+ echo "::error::$unbound of $expected shard markers do not identify the leg and attempt that wrote them:$detail"
3098
+ echo "::error::evidence that cannot be tied to one leg of this attempt is UNMEASURED, not a pass. Refusing."
3099
+ exit ${SHARD_AGGREGATE_REFUSAL_EXIT}
3100
+ fi
3101
+
3102
+ if [ "$found" -ne "$expected" ]; then
3103
+ echo "::error::attempt $attempt left $found shard-marker artifacts, and the matrix declares $expected. The aggregate cannot speak for a suite it did not measure."
3104
+ exit ${SHARD_AGGREGATE_REFUSAL_EXIT}
3105
+ fi
3106
+
3107
+ if [ "$passed" -ne "$expected" ]; then
3108
+ echo "::error::$passed of $expected shards concluded success:$detail"
3109
+ exit ${SHARD_AGGREGATE_REFUSAL_EXIT}
3110
+ fi
3111
+
3112
+ # $passed is the measured count, never the generated one. The sentence on
3113
+ # run 39799846607 said "All 4 shards passed" because the generator wrote 4.
3114
+ echo "All $passed shards concluded, and all $passed passed."
3115
+ `;
3116
+ }
3117
+
3118
+ /**
3119
+ * The steps one matrix leg runs to leave evidence that it executed (#1190).
3120
+ *
3121
+ * Two steps rather than one: a shell step writes the file, and
3122
+ * `actions/upload-artifact` carries it to the one place a sibling job can
3123
+ * read. Both are `if: always()`, because a leg that FAILED still executed and
3124
+ * the aggregate distinguishes "ran and was red" from "never ran" — collapsing
3125
+ * those two is #1181.
3126
+ *
3127
+ * The artifact name carries the run attempt as well as the matrix index, and
3128
+ * so does the marker's BODY. Two independent bindings, because a name is a
3129
+ * convention the generator controls and a body is a reading: a generator that
3130
+ * templated the wrong expression into the name would still be caught. The
3131
+ * attempt is there because artifacts are scoped to the run — see
3132
+ * `SHARD_MARKER_ARTIFACT_PREFIX` for the run this was measured on.
3133
+ *
3134
+ * The attempt in the name also removes the need for `overwrite`, which the
3135
+ * first draft of #1190 carried: names are now unique per attempt, so a
3136
+ * re-running leg collides with nothing and no deletion primitive is needed.
3137
+ *
3138
+ * `path:` names a single FILE, not the directory. A directory upload plus the
3139
+ * aggregate's `merge-multiple` flatten would discard the name's binding on
3140
+ * the reading side — a leg that wrote `shard-1`, `shard-2`, `shard-3` into
3141
+ * its own temp directory would contribute evidence for legs it is not, and
3142
+ * "each leg produced its own marker" would not be what the check measures.
3143
+ * Measured on run 39836500284: the leg writes a decoy `shard-99` and the
3144
+ * artifact carries only `shard-<its own index>`.
3145
+ *
3146
+ * The directory is created FRESH each run, so nothing an earlier step left
3147
+ * behind can ship as evidence.
3148
+ *
3149
+ * `if-no-files-found: error` because a marker step that produced no file is a
3150
+ * shard whose evidence is UNMEASURED, and the honest place to say so is in
3151
+ * the leg that failed to write it.
3152
+ */
3153
+ export function buildShardMarkerSteps(indent: string): string {
3154
+ const M = SHARD_MARKER_ENV;
3155
+ const dir = `\${{ runner.temp }}/rungate-shard-marker`;
3156
+ const file = `${SHARD_MARKER_FILE_PREFIX}\${{ matrix.shard }}`;
3157
+ const lines = [
3158
+ `# #1190. The aggregate below counts these instead of asking the Actions`,
3159
+ `# API: \`gh\` is a GitHub-hosted-image fact rather than a runner fact, and`,
3160
+ `# \`actions: read\` is a scope a consumer's token has to be granted. A`,
3161
+ `# marker needs neither — same run, same artifact service.`,
3162
+ `- name: Record that this shard executed`,
3163
+ ` if: always()`,
3164
+ ` env:`,
3165
+ ` ${M.index}: \${{ matrix.shard }}`,
3166
+ ` ${M.status}: \${{ job.status }}`,
3167
+ ` ${M.attempt}: \${{ github.run_attempt }}`,
3168
+ ` ${M.dir}: ${dir}`,
3169
+ ` run: |`,
3170
+ ` # Fresh, so nothing an earlier step left behind ships as evidence.`,
3171
+ ` rm -r "$${M.dir}" 2>/dev/null || true`,
3172
+ ` mkdir -p "$${M.dir}"`,
3173
+ ` # status, attempt and leg — the body the aggregate cross-checks`,
3174
+ ` # against the artifact's own name.`,
3175
+ ` printf '%s %s %s\\n' "$${M.status}" "$${M.attempt}" "$${M.index}" > "$${M.dir}/${SHARD_MARKER_FILE_PREFIX}$${M.index}"`,
3176
+ `- uses: ${actionRef("actions/upload-artifact")}`,
3177
+ ` if: always()`,
3178
+ ` with:`,
3179
+ ` name: ${SHARD_MARKER_ARTIFACT_PREFIX}\${{ github.run_attempt }}-\${{ matrix.shard }}`,
3180
+ ` # One FILE, so this leg cannot ship evidence about another leg.`,
3181
+ ` path: ${dir}/${file}`,
3182
+ ` if-no-files-found: error`,
3183
+ ` retention-days: 1`,
3184
+ ];
3185
+ return lines.map(line => `${indent}${line}`).join("\n");
3186
+ }
3187
+
3188
+ /** Indent a script for a YAML block scalar, leaving blank lines blank. */
3189
+ function indentedScript(script: string, indent: string): string {
3190
+ return script
3191
+ .trimEnd()
3192
+ .split("\n")
3193
+ .map(line => (line ? `${indent}${line}` : ""))
3194
+ .join("\n");
3195
+ }
3196
+
2792
3197
  /**
2793
3198
  * Top-level workflow keys this consumer has taken back from the generator
2794
3199
  * (#839). Declared in `lib/scaffold/managed-workflow.ts`, beside the merge
@@ -2955,6 +3360,30 @@ export const CI_PULL_REQUEST_TRIGGER = ` # NO branches: filter, deliberately (#
2955
3360
  # no new coverage.
2956
3361
  pull_request:`;
2957
3362
 
3363
+ /**
3364
+ * `ai-review.yml`'s own `on.pull_request`: `CI_PULL_REQUEST_TRIGGER`'s body
3365
+ * plus an explicit `types:` list (#1207).
3366
+ *
3367
+ * Why this workflow and no other, why all five types are spelled, and what the
3368
+ * label could not do without them: `AI_REVIEW_PULL_REQUEST_TYPES` in
3369
+ * `lib/scaffold/ai-review-step.ts`, which is the single list this renders.
3370
+ *
3371
+ * Built FROM `CI_PULL_REQUEST_TRIGGER` rather than beside it. The no-`branches:`
3372
+ * rationale is #1136's and is identical here; a second copy of that comment
3373
+ * block is a second thing to update when the reasoning moves, and
3374
+ * `test/stacked-pr-ci-trigger.test.ts` checks all four generated bodies for the
3375
+ * property it describes.
3376
+ */
3377
+ export const AI_REVIEW_PULL_REQUEST_TRIGGER = `${CI_PULL_REQUEST_TRIGGER}
3378
+ # #1207. The three GitHub defaults, PLUS \`labeled\`/\`unlabeled\` — and
3379
+ # the defaults are spelled because \`types:\` REPLACES them rather than
3380
+ # extending them. Omitting them would fix the waiver and stop this
3381
+ # required check running on ordinary pushes.
3382
+ #
3383
+ # Only this workflow subscribes to label events, because only this
3384
+ # workflow reads a label. A label is not a code change.
3385
+ types: [${AI_REVIEW_PULL_REQUEST_TYPES.join(", ")}]`;
3386
+
2958
3387
  export const CI_CONCURRENCY = `# The GROUP does the work here, not the flag. A run is only ever cancelled by
2959
3388
  # another run in the SAME group, so keying a push on its own commit makes the
2960
3389
  # question moot: there is never a second occupant to do the cancelling.
@@ -3206,6 +3635,7 @@ ${baseRefStep}
3206
3635
  ${bunStep}
3207
3636
  - run: bun install${globalTools.step}${ciSetupStep()}
3208
3637
  - run: ${test.command} --shard=\${{ matrix.shard }}/${shards}${typecheckStep}
3638
+ ${buildShardMarkerSteps(" ")}
3209
3639
 
3210
3640
  # The aggregate. Named "test" because that is the context branch protection
3211
3641
  # requires; it exists to turn N shard results into the one verdict.
@@ -3217,15 +3647,44 @@ ${bunStep}
3217
3647
  # protection configurations read a skip as satisfied — which would make
3218
3648
  # this aggregate a gate that cannot refuse.
3219
3649
  if: always()
3650
+ # #1190. \`contents: read\` and nothing else. #1189 also took
3651
+ # \`actions: read\` so the step could \`gh api\` this run's jobs, which
3652
+ # worked and made every consumer's required check depend on a token scope
3653
+ # and on \`gh\` being present — neither of which the generated test job
3654
+ # needed before, and neither of which a self-hosted or container
3655
+ # \`ci.runner\` is guaranteed to have. Same-run artifacts take no scope
3656
+ # and no token.
3657
+ permissions:
3658
+ contents: read
3220
3659
  steps:
3221
- - name: Every shard passed
3660
+ - uses: ${actionRef("actions/download-artifact")}
3661
+ # continue-on-error so the REFUSAL is the script's and carries a
3662
+ # sentence. A download that fails here is still red either way, but
3663
+ # the action's own error names none of this — and a check that is
3664
+ # correctly red and silent is the expensive half.
3665
+ continue-on-error: true
3666
+ with:
3667
+ # EVERY attempt's markers, not just this one's. The script dates
3668
+ # each marker itself, so a leg whose only evidence is older gets
3669
+ # "re-run all jobs" rather than "never ran" — a pattern narrowed to
3670
+ # this attempt would make those two indistinguishable.
3671
+ pattern: ${SHARD_MARKER_ARTIFACT_PREFIX}*
3672
+ # NO merge-multiple: each artifact keeps its own directory, which
3673
+ # is what ties a marker to the leg that uploaded it. Flattening
3674
+ # discards that and the reading falls back to filenames alone.
3675
+ path: \${{ runner.temp }}/rungate-shard-markers
3676
+ - name: Every shard concluded, and every shard passed
3677
+ env:
3678
+ # Every GitHub-side value arrives here, and the script below holds
3679
+ # no GitHub expression at all — that is what lets a test execute
3680
+ # the shipped text against a planted marker directory (#1181).
3681
+ ${SHARD_AGGREGATE_ENV.rollup}: \${{ needs.test-shard.result }}
3682
+ ${SHARD_AGGREGATE_ENV.expected}: "${shards}"
3683
+ ${SHARD_AGGREGATE_ENV.jobName}: test-shard
3684
+ ${SHARD_AGGREGATE_ENV.attempt}: \${{ github.run_attempt }}
3685
+ ${SHARD_AGGREGATE_ENV.markerDir}: \${{ runner.temp }}/rungate-shard-markers
3222
3686
  run: |
3223
- result='\${{ needs.test-shard.result }}'
3224
- if [ "$result" != "success" ]; then
3225
- echo "::error::test-shard concluded '$result' — the suite is not green."
3226
- exit 1
3227
- fi
3228
- echo "All ${shards} shards passed."
3687
+ ${indentedScript(buildShardAggregateScript(), " ")}
3229
3688
  `
3230
3689
  : `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
3231
3690
  name: CI
@@ -3442,10 +3901,27 @@ ${bunStep}
3442
3901
  // `id-token: write` is what lets the runner mint the OIDC token GCP's STS
3443
3902
  // exchanges. Granted ONLY when there is a federation to use it, because a
3444
3903
  // permission nobody consumes is a permission nobody audits.
3904
+ //
3905
+ // `actions: read` is #1168's, and it is granted unconditionally because
3906
+ // the round counter it serves runs on every review. It is READ on the
3907
+ // workflow's own run list and nothing else: the step lifts one integer,
3908
+ // `total_count`, which is how many times this workflow has run on this
3909
+ // pull request — the only thing in reach that is actually a review round.
3910
+ // A permission nobody consumes is a permission nobody audits, and this one
3911
+ // has exactly one consumer, named in `buildRoundsScript`.
3912
+ //
3913
+ // LAST in the block, after `id-token: write`, and the order is not
3914
+ // cosmetic. This file is job-preserving: a consumer who already has the
3915
+ // workflow gets the new key MERGED into their existing permissions block,
3916
+ // which appends. A generator emitting it in the middle therefore disagrees
3917
+ // with what every already-scaffolded tree ends up holding, and AC-12 in
3918
+ // test/ai-review-surface-census.test.ts compares the committed file
3919
+ // against a FRESH generation — so the two orders are a byte difference
3920
+ // that reads as a hand-edit. Measured: that is exactly how this was found.
3445
3921
  const aiReviewPermissions =
3446
3922
  vertex.config === null
3447
- ? `permissions:\n contents: read`
3448
- : `permissions:\n contents: read\n # Mint the OIDC token Workload Identity Federation exchanges (#631).\n id-token: write`;
3923
+ ? `permissions:\n contents: read\n # Count this pull request's previous AI Review runs — the round budget (#1168).\n actions: read`
3924
+ : `permissions:\n contents: read\n # Mint the OIDC token Workload Identity Federation exchanges (#631).\n id-token: write\n # Count this pull request's previous AI Review runs — the round budget (#1168).\n actions: read`;
3449
3925
 
3450
3926
  const aiReviewYml = `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
3451
3927
  #
@@ -3472,7 +3948,7 @@ on:
3472
3948
  # See the block comment in lib/scaffold/steps.ts: no branches: filter, and
3473
3949
  # its absence hangs a merge queue silently rather than failing it (#867).
3474
3950
  merge_group:
3475
- ${CI_PULL_REQUEST_TRIGGER}
3951
+ ${AI_REVIEW_PULL_REQUEST_TRIGGER}
3476
3952
 
3477
3953
  ${aiReviewPermissions}
3478
3954
 
package/lib/scanner.ts CHANGED
@@ -10,6 +10,7 @@
10
10
  */
11
11
  import { existsSync, readFileSync, statSync } from "fs";
12
12
  import { readdirSorted } from "./readdir-sorted";
13
+ import { fileExtensions } from "./file-extensions";
13
14
  import { join, basename } from "path";
14
15
  import { resolveConfig } from "./config-loader";
15
16
  // A leaf, not a generator. SC-365 / AC-3 keeps generation logic out of the
@@ -476,14 +477,22 @@ function scanDirs(root: string): DirEntry[] {
476
477
  const full = join(root, entry);
477
478
  try {
478
479
  if (!statSync(full).isDirectory()) continue;
479
- const files = readdirSorted(full, { recursive: true });
480
- const exts = new Set(files.map(f => f.split(".").pop()).filter((e): e is string => Boolean(e)));
481
- dirs.push({ name: entry, fileCount: files.length, types: [...exts].slice(0, 5) });
480
+ // One binding for what a "type" is, shared with
481
+ // `scripts/generate-code-map.ts` and the scaffold's inline fallback
482
+ // in `lib/scaffold/steps.ts` (#1200). The copy that used to be here
483
+ // reported directory names.
484
+ //
485
+ // Naming that fallback by its function would red
486
+ // `test/unit/scanner.test.ts`: it greps this file's raw TEXT for
487
+ // generator symbols, so a COMMENT mentioning one reads as an import.
488
+ dirs.push({ name: entry, types: fileExtensions(full) });
482
489
  } catch {}
483
490
  }
484
491
  } catch {}
485
492
 
486
- dirs.sort((a, b) => b.fileCount - a.fileCount);
493
+ // Unsorted. Row order is `directoryTable`'s single decision (#1163) — this
494
+ // used to sort by `fileCount`, which is how the census survived one
495
+ // indirection past being printed. See `DirEntry` for the measurement.
487
496
  return dirs;
488
497
  }
489
498