rungate 0.8.3 → 0.8.5

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.
@@ -1752,6 +1752,75 @@ export const AI_REVIEW_CARRY_PATH_VAR = "AI_REVIEW_CARRY_PATH";
1752
1752
  /** The basename inside the findings directory. One spelling. */
1753
1753
  export const AI_REVIEW_CARRY_BASENAME = "ai-review-carried.txt";
1754
1754
 
1755
+ /**
1756
+ * Where the carry step leaves the ledger comment's BODY, verbatim, for the
1757
+ * adjudicator to re-read in TypeScript (CRC-N4, #1586).
1758
+ *
1759
+ * ## Why a snapshot and not a fetch at adjudication time
1760
+ *
1761
+ * The step order is `AI_REVIEW_CARRY_STEP_ID` → the reviewer →
1762
+ * `AI_REVIEW_PERSIST_STEP_ID`, which upserts THIS round into the ledger
1763
+ * comment → `AI_REVIEW_RUN_STEP_ID`, which adjudicates. An adjudicator
1764
+ * that fetched the ledger itself would read a comment that already contains
1765
+ * the payload it is deciding about, so every finding would match a "prior"
1766
+ * key that is its own, and the suppression would empty the payload on every
1767
+ * round while looking like it worked. The prior state has to be the one that
1768
+ * existed BEFORE the reviewer ran, and the carry step is the only position
1769
+ * that holds it.
1770
+ *
1771
+ * ## Why the raw body rather than the keys
1772
+ *
1773
+ * `carryKey` is not restated in jq. The carry script reaches the body and
1774
+ * stops; `readLedger → priorFindings` forms every key in TypeScript, so
1775
+ * there is ONE decider for what a finding's identity is. A second
1776
+ * implementation in jq would be the #1568 shape again — two readers of the
1777
+ * same bytes, disagreeing on a case neither author thought to name.
1778
+ *
1779
+ * ## Written on the READ path only, and that is not a conflation
1780
+ *
1781
+ * An absent snapshot does not mean "no prior findings": the state is read
1782
+ * from `AI_REVIEW_CARRY_BASENAME`, which is written on EVERY path and is
1783
+ * the single site that decides it. UNMEASURED and ABSENT both reach the
1784
+ * adjudicator as "suppress nothing", but only one of them says the record
1785
+ * could not be read, and the adjudicator reports which.
1786
+ */
1787
+ export const AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR = "AI_REVIEW_LEDGER_SNAPSHOT_PATH";
1788
+
1789
+ /** The basename inside the findings directory. One spelling. */
1790
+ export const AI_REVIEW_LEDGER_SNAPSHOT_BASENAME = "ai-review-ledger-snapshot.txt";
1791
+
1792
+ /**
1793
+ * The round the snapshot was taken BEFORE, handed to the carry step so the
1794
+ * snapshot can carry its own provenance (#1586).
1795
+ *
1796
+ * ## What this exists to make falsifiable
1797
+ *
1798
+ * A snapshot taken at `AI_REVIEW_PERSIST_STEP_ID` instead of at the carry
1799
+ * step is byte-shaped exactly like a correct one — it is the same comment,
1800
+ * fetched the same way, by the same selector. The only thing that
1801
+ * distinguishes them is that the later one already contains THIS round, so
1802
+ * every finding in the payload matches a "prior" key that is its own and the
1803
+ * adjudicator suppresses the entire round. That failure reports as a clean
1804
+ * review on every round forever, which is the reading that looks most like
1805
+ * success.
1806
+ *
1807
+ * So the snapshot states the round it precedes, and the reader refuses a
1808
+ * snapshot containing a round at or past it. The refusal is UNMEASURED and
1809
+ * suppresses nothing, so the wrong-ordering mutant fails toward reporting.
1810
+ */
1811
+ export const AI_REVIEW_SNAPSHOT_ROUND_VAR = "AI_REVIEW_SNAPSHOT_ROUND";
1812
+
1813
+ /**
1814
+ * The snapshot's first line: `taken_before_round=<N>`. Everything after the
1815
+ * first newline is the ledger comment's body, verbatim and unescaped.
1816
+ *
1817
+ * A single header line rather than a JSON envelope, because the body is
1818
+ * arbitrary text that must survive byte-for-byte: `readLedger` is the one
1819
+ * decider for what it means, and re-encoding it here would be a second
1820
+ * format for that reader to disagree with.
1821
+ */
1822
+ export const AI_REVIEW_SNAPSHOT_ROUND_KEY = "taken_before_round";
1823
+
1755
1824
  /** The annotation title every carry warning is filed under. */
1756
1825
  export const AI_REVIEW_CARRY_TITLE = "AI review carry-forward";
1757
1826
 
@@ -3606,6 +3675,58 @@ export const AI_REVIEW_PASS_VERDICT = "PASS";
3606
3675
  /** The verdict word meaning "something here blocks the pull request". */
3607
3676
  export const AI_REVIEW_BLOCK_VERDICT = "BLOCK";
3608
3677
 
3678
+ /**
3679
+ * The three tags a surviving finding is posted under, and no fourth (CRC-B7).
3680
+ *
3681
+ * ## This is NOT a second severity table, and the distinction is the whole
3682
+ * of why both exist
3683
+ *
3684
+ * `AI_REVIEW_SEVERITIES` above is the reviewer's MAGNITUDE word — how bad the
3685
+ * defect is — and it is the input to one question: does this block the pull
3686
+ * request? This is ATTRIBUTION — whose change the defect belongs to, and
3687
+ * therefore how it should read to whoever opens the checks tab.
3688
+ *
3689
+ * **The input on which the two must disagree for both to be right** is a
3690
+ * finding declaring `severity: "critical"` against a file the pull request
3691
+ * does not touch. `AI_REVIEW_SEVERITIES` must still say `critical` blocks: a
3692
+ * critical defect is critical whoever wrote it, and the table is a statement
3693
+ * about the word, not about the diff. This must still say `Pre-existing`: the
3694
+ * change cannot have introduced it and usually cannot fix it. Their
3695
+ * COMPOSITION is the demotion in `lib/scaffold/ai-review-findings.ts` —
3696
+ * reported, tagged, and not blocking.
3697
+ *
3698
+ * They cannot be collapsed in either direction. Folding `Pre-existing` into
3699
+ * `AI_REVIEW_SEVERITIES` would require the REVIEWER to write it, and the
3700
+ * reviewer is deliberately not given the pull request's file list — that is
3701
+ * why `readPayload` measures verdict agreement BEFORE the demotion. Deriving
3702
+ * these three from the five would require the magnitude word to encode
3703
+ * attribution, which nothing in `critical … info` does.
3704
+ *
3705
+ * ## Declared here rather than in `lib/finding-jury.ts`, where it was
3706
+ *
3707
+ * Same reason `AI_REVIEW_FINDING_FIELDS` is declared here: this module has no
3708
+ * relative imports, so it is the one module the three mutation batteries that
3709
+ * copy `ai-review-findings.ts` into a scratch directory can carry with it. A
3710
+ * tag vocabulary the deployed path cannot import is a tag vocabulary the
3711
+ * deployed path does not use, which is exactly the state CRC-B7 found —
3712
+ * `SEVERITY_RANK` had zero callers reachable from CI. `lib/finding-jury.ts`
3713
+ * imports and re-exports these two names, so its own callers are unchanged
3714
+ * and there is still exactly ONE declaration.
3715
+ */
3716
+ export type Severity = "Important" | "Nit" | "Pre-existing";
3717
+
3718
+ /**
3719
+ * Sort order for the posted findings. A pre-existing bug is still a bug, so
3720
+ * it outranks a nit; it is not the author's, so it does not outrank an
3721
+ * Important one.
3722
+ *
3723
+ * ONE binding, and the only ordering in the deployed path. A second
3724
+ * comparator would be two deciders over one question and a mutation of
3725
+ * either would leave the other holding every case up
3726
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
3727
+ */
3728
+ export const SEVERITY_RANK: Record<Severity, number> = { Important: 0, "Pre-existing": 1, Nit: 2 };
3729
+
3609
3730
  const AI_REVIEW_BLOCKING_SEVERITIES = Object.keys(AI_REVIEW_SEVERITIES).filter(
3610
3731
  s => AI_REVIEW_SEVERITIES[s],
3611
3732
  );
@@ -4105,6 +4226,22 @@ if [ "\${${AI_REVIEW_EVENT_VAR}:-}" = merge_group ]; then
4105
4226
  exit 0
4106
4227
  fi
4107
4228
 
4229
+ # #1469. Same reading for a push to the default branch, and taken here rather
4230
+ # than left to the refusal below. \`AI_REVIEW_ROUNDS_BRANCH\` is
4231
+ # \`github.event.pull_request.head.ref\` and is EMPTY on a push, so without
4232
+ # this the step would refuse with \${AI_REVIEW_REQUIRED_EXIT} and red the
4233
+ # check on every commit that lands — reporting "this job cannot tell which
4234
+ # round it is on", which is a true sentence about a question that does not
4235
+ # apply.
4236
+ ${aiReviewPushBranch(
4237
+ ` echo "${AI_REVIEW_ROUND_OUTPUT}=" >> "\${GITHUB_OUTPUT}"
4238
+ echo "${AI_REVIEW_AT_CAP_OUTPUT}=" >> "\${GITHUB_OUTPUT}"
4239
+ echo "${AI_REVIEW_INTENT_OUTPUT}=${AI_REVIEW_INTENT_NONE}" >> "\${GITHUB_OUTPUT}"
4240
+ echo "ai-review rounds: push to the default branch, no review and so no round"
4241
+ exit 0
4242
+ `,
4243
+ )}
4244
+
4108
4245
  # \`AI_REVIEW_ROUNDS_SINCE\` is in this refusal and not defaulted, deliberately
4109
4246
  # (#1281). An unset value would widen the query back to the whole branch NAME
4110
4247
  # — the exact defect — and it would do it silently, because the response is
@@ -4379,8 +4516,17 @@ if [ "\${${AI_REVIEW_EVENT_VAR}:-}" = merge_group ]; then
4379
4516
  exit 0
4380
4517
  fi
4381
4518
 
4519
+ # #1469. A push to the default branch carries no pull request either, and the
4520
+ # same distinction applies: ABSENT is a complete reading, UNMEASURED is a
4521
+ # failed one. Without this branch a push falls into the refusal below and
4522
+ # reports that the history "could not be read", which names a lookup that was
4523
+ # never applicable rather than one that failed.
4524
+ ${aiReviewPushBranch(` carry_state '${AI_REVIEW_CARRY_ABSENT}'
4525
+ exit 0
4526
+ `)}
4527
+
4382
4528
  if [ -z "\${${AI_REVIEW_LEDGER_PR_VAR}:-}" ]; then
4383
- carry_unmeasured "this run is not a merge_group entry and no pull request number reached this step, so there was nowhere to look for the history."
4529
+ carry_unmeasured "this run is neither a merge_group entry nor a push, and no pull request number reached this step, so there was nowhere to look for the history."
4384
4530
  fi
4385
4531
 
4386
4532
  if [ -z "\${${AI_REVIEW_LEDGER_TOKEN_VAR}:-}" ] || [ -z "\${${AI_REVIEW_LEDGER_REPO_VAR}:-}" ]; then
@@ -4467,16 +4613,32 @@ fi
4467
4613
  # fence. A marked comment whose block is missing, unterminated or unparseable
4468
4614
  # is UNREADABLE and never an empty ledger — treating a damaged ledger as empty
4469
4615
  # discards every round it holds at the moment nothing can tell it happened.
4616
+ #
4617
+ # SPLIT, NEVER \`index\` WITH A SLICE (#1568). jq's \`index\` on a string
4618
+ # returns a BYTE offset and \`.[a:b]\` slices by CODEPOINTS, so the two
4619
+ # disagree by exactly the number of multi-byte UTF-8 bytes before the cut.
4620
+ # \`readLedger\`'s \`indexOf\`/\`slice\` pair agrees with itself and this
4621
+ # restatement did not, which is why two readers disagreed about the same
4622
+ # bytes. Measured on #1569's ledger: 13,826 codepoints in 13,846 bytes, so
4623
+ # the closing-fence cut overshot by 16 and carried the fence and the prose
4624
+ # after it into the JSON. Every round from round 3 on started from nothing.
4625
+ # The em dashes were in the findings' own summaries — this repository writes
4626
+ # them in every sentence, so the failure was the rule and not the exception,
4627
+ # and ASCII is what the whole battery had held fixed.
4628
+ #
4629
+ # \`split\` is unit-free: it never names an offset. The \`join\` on each tail
4630
+ # preserves the original's "from the FIRST occurrence onward" semantics for a
4631
+ # body that repeats the marker or the fence.
4470
4632
  if ! fenced=\$(printf '%s' "\${selected}" | jq -r --arg m '${AI_REVIEW_LEDGER_MARKER}' --arg f '${AI_REVIEW_LEDGER_FENCE}' '
4471
4633
  (.body // "") as \$b
4472
- | (\$b | index(\$m)) as \$i
4473
- | (if \$i == null then error("marker") else \$b[\$i:] end) as \$after
4474
- | (\$after | index(\$f)) as \$j
4475
- | (if \$j == null then error("fence") else \$after[\$j:] end) as \$block
4476
- | (\$block | index("\\n")) as \$k
4477
- | (if \$k == null then error("fence") else \$block[\$k + 1:] end) as \$rest
4478
- | (\$rest | index("\\n${fence}")) as \$l
4479
- | if \$l == null then error("unterminated") else \$rest[:\$l] end
4634
+ | (\$b | split(\$m)) as \$mp
4635
+ | (if (\$mp | length) < 2 then error("marker") else (\$mp[1:] | join(\$m)) end) as \$after
4636
+ | (\$after | split(\$f)) as \$fp
4637
+ | (if (\$fp | length) < 2 then error("fence") else (\$fp[1:] | join(\$f)) end) as \$block
4638
+ | (\$block | split("\\n")) as \$lp
4639
+ | (if (\$lp | length) < 2 then error("fence") else (\$lp[1:] | join("\\n")) end) as \$rest
4640
+ | (\$rest | split("\\n${fence}")) as \$cp
4641
+ | if (\$cp | length) < 2 then error("unterminated") else \$cp[0] end
4480
4642
  ' 2>/dev/null); then
4481
4643
  # NO BACKTICKS IN AN ANNOTATION STRING. These messages sit inside a bash
4482
4644
  # double-quoted argument, where a backtick opens COMMAND SUBSTITUTION — and
@@ -4603,6 +4765,37 @@ if ! carried_count=\$(printf '%s' "\${carried}" | jq 'length'); then
4603
4765
  fi
4604
4766
 
4605
4767
  carry_state '${AI_REVIEW_CARRY_READ}'
4768
+
4769
+ # The ledger's own bytes, for the adjudicator to key in TypeScript (#1586).
4770
+ #
4771
+ # HERE and not at adjudication time: the persist step upserts THIS round into
4772
+ # that same comment before the adjudicator runs, so a later fetch would read
4773
+ # the payload it is deciding about as its own prior and suppress all of it.
4774
+ #
4775
+ # ON THE READ PATH ONLY, and after the parse above succeeded. The state the
4776
+ # adjudicator gates on lives in the carry file, which \`carry_state\` writes on
4777
+ # every path — so an absent snapshot is never read as "no earlier findings",
4778
+ # it is read as whichever of the three states that one site recorded.
4779
+ #
4780
+ # A failed write is a WARNING and not a refusal: the carry itself succeeded
4781
+ # and the reviewer's copy is already on disk. The adjudicator seeing no
4782
+ # snapshot suppresses nothing, which is the direction this is allowed to be
4783
+ # wrong in — a repeat gets posted twice, rather than a live finding dropped.
4784
+ if [ -n "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}:-}" ]; then
4785
+ # The provenance line FIRST, then the body verbatim. The reader refuses a
4786
+ # snapshot holding a round at or past this number, which is the only thing
4787
+ # that tells a snapshot taken here from one taken after the persist step —
4788
+ # they are otherwise the same comment fetched by the same selector, and the
4789
+ # later one suppresses the whole round it is deciding about.
4790
+ if ! {
4791
+ printf '%s=%s\\n' '${AI_REVIEW_SNAPSHOT_ROUND_KEY}' "\${${AI_REVIEW_SNAPSHOT_ROUND_VAR}:-}"
4792
+ printf '%s' "\${selected}" | jq -r '.body // ""'
4793
+ } > "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}}"; then
4794
+ rm -f "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}}"
4795
+ carry_note "the ledger's own text could not be written for the adjudicator, so repeats will not be suppressed on this round. Every finding this round raises is reported, including any an earlier round already raised."
4796
+ fi
4797
+ fi
4798
+
4606
4799
  {
4607
4800
  printf 'carried_count=%s\\n' "\${carried_count}"
4608
4801
  printf 'unmeasured_rounds=%s\\n' "\${unmeasured_rounds}"
@@ -5584,6 +5777,32 @@ export function buildReviewRunScript(version: string): string {
5584
5777
  `happened. Unset ${AI_REVIEW_REQUIRE_VAR}, or keep ai-review a required ` +
5585
5778
  `context on pull_request and accept the per-head review as sufficient.`;
5586
5779
 
5780
+ // #1469. The same shape as the two above and a DIFFERENT argument, which is
5781
+ // the whole reason it is a separate branch rather than an extra alternative
5782
+ // on the queue test. A queue entry can be passed because the head commit it
5783
+ // batches was already reviewed; a push has no such guarantee available to
5784
+ // this job. Nothing here claims the commit was reviewed elsewhere — it
5785
+ // usually was, on the pull request that produced it, but a direct push to
5786
+ // the default branch is a push too and this step cannot tell them apart.
5787
+ const pushEntry =
5788
+ `This run is a ${AI_REVIEW_PUSH_EVENT} to the default branch, and no AI ` +
5789
+ `review ran on it: the review action does not support the ` +
5790
+ `${AI_REVIEW_PUSH_EVENT} event and refuses it as an unsupported event ` +
5791
+ `type. The trigger exists so that ai-review REPORTS on push, which is ` +
5792
+ `what lets branch protection be reasoned about (#1469) — it is not a ` +
5793
+ `review of this commit and must not be read as one. This check is ` +
5794
+ `UNMEASURED on this ref. What reviewed the content was the pull request ` +
5795
+ `that produced it, if there was one; a direct push to this branch was ` +
5796
+ `reviewed by nothing at all, and this job cannot tell those two apart.`;
5797
+
5798
+ const pushRefusal =
5799
+ `${AI_REVIEW_REQUIRE_VAR} is '${AI_REVIEW_REQUIRE_VALUE}' and this run is ` +
5800
+ `a ${AI_REVIEW_PUSH_EVENT} to the default branch, which the review action ` +
5801
+ `refuses as an unsupported event type, so no AI review ran on this ` +
5802
+ `commit. Failing rather than reporting a green check for a review that ` +
5803
+ `never happened. Unset ${AI_REVIEW_REQUIRE_VAR} if the review on the ` +
5804
+ `pull request that produced this commit is the measurement you want.`;
5805
+
5587
5806
  const absentRefusal =
5588
5807
  `${AI_REVIEW_REQUIRE_VAR} is '${AI_REVIEW_REQUIRE_VALUE}' and the ` +
5589
5808
  `credential-detection step produced no mode output, so this pull ` +
@@ -5694,6 +5913,28 @@ if [ "\${${AI_REVIEW_EVENT_VAR}:-}" = ${AI_REVIEW_QUEUE_EVENT} ]; then
5694
5913
  exit 0
5695
5914
  fi
5696
5915
 
5916
+ # #1469, and SECOND for the reason the branch above is first: on a push the
5917
+ # action threw before producing an outcome, so none of the readings below can
5918
+ # hold and falling through would report a cause this job did not measure.
5919
+ #
5920
+ # The flag check is INSIDE the branch, not above it and not below it — the
5921
+ # fifth and now sixth spelling of ONE decider, same variable, same \`=\`
5922
+ # against the same value, same \${AI_REVIEW_REQUIRED_EXIT}. #939's fence in
5923
+ # test/ai-review-merge-group.test.ts runs every no-verdict route through one
5924
+ # table precisely so that a branch added here without it reds rather than
5925
+ # reintroducing that issue.
5926
+ #
5927
+ # \`::warning\` and not \`::notice\`: nothing reviewed this commit.
5928
+ ${aiReviewPushBranch(
5929
+ ` echo "::warning title=${AI_REVIEW_UNMEASURED_TITLE}::${pushEntry}"
5930
+ if [ "\${${AI_REVIEW_REQUIRE_VAR}:-}" = "${AI_REVIEW_REQUIRE_VALUE}" ]; then
5931
+ echo "::error title=${AI_REVIEW_UNMEASURED_TITLE}::${pushRefusal}" >&2
5932
+ exit ${AI_REVIEW_REQUIRED_EXIT}
5933
+ fi
5934
+ exit 0
5935
+ `,
5936
+ )}
5937
+
5697
5938
  if [ -z "\${AI_REVIEW_MODE:-}" ]; then
5698
5939
  echo "::warning title=${AI_REVIEW_UNMEASURED_TITLE}::${absent}"
5699
5940
  if [ "\${${AI_REVIEW_REQUIRE_VAR}:-}" = "${AI_REVIEW_REQUIRE_VALUE}" ]; then
@@ -6511,6 +6752,78 @@ export const AI_REVIEW_EVENT_VAR = "AI_REVIEW_EVENT";
6511
6752
  /** The event a merge queue fires, and the only one that takes the queue branch. */
6512
6753
  export const AI_REVIEW_QUEUE_EVENT = "merge_group";
6513
6754
 
6755
+ /**
6756
+ * The event a push to the default branch fires (#1469).
6757
+ *
6758
+ * ## Why the trigger exists at all
6759
+ *
6760
+ * `PROTECT-1` in `lib/branch-protection.ts` REFUSES to recommend
6761
+ * `required_status_checks.strict = false` on a repository whose required
6762
+ * contexts do not run on `push:` to the default branch, and it refuses
6763
+ * `strict = true` on a user-owned account because it serialises every swarm's
6764
+ * pull requests. A repository whose `ai-review` is required and runs only on
6765
+ * `pull_request` therefore has no reading that clears: both directions are
6766
+ * refused, and the refusal's own remedy is this trigger. `readPushCi` reads
6767
+ * `.github/workflows/` and asks exactly one question of each file — does it
6768
+ * run on push to this branch, and which contexts does it name — so the
6769
+ * trigger is what moves `ai-review` out of that reading's `missing` list.
6770
+ *
6771
+ * ## What the job can DO on it: nothing, and that is measured
6772
+ *
6773
+ * Read from `anthropics/claude-code-action` at the SHA `lib/claude-code-action.ts`
6774
+ * pins, the same way #867 established it for `merge_group`:
6775
+ * `parseGitHubContext()` in `src/github/context.ts` switches on
6776
+ * `context.eventName`, and `push` appears in neither of its two event-name
6777
+ * lists, so the `default:` branch throws `Unsupported event type: push`
6778
+ * before the action reads anything. There is no version to bump to.
6779
+ *
6780
+ * So this is #867's distinction again, and it has to be drawn the same way:
6781
+ * an argument about what the job can DO on an event is not an argument about
6782
+ * whether it REPORTS on one. The job reports; every step that reads a pull
6783
+ * request says it had none rather than reading an empty value.
6784
+ *
6785
+ * ## And it is NOT a review of the merged commit
6786
+ *
6787
+ * Worth stating where the constant is, because the tempting reading of "the
6788
+ * required context now runs on push" is that main is being reviewed. It is
6789
+ * not. The honest severity is `::warning` and the honest word is UNMEASURED:
6790
+ * nothing read this commit. What push-CI buys under `strict: false` is the
6791
+ * SEMANTIC-conflict net PROTECT-1's header argues for — two changes green
6792
+ * alone and broken together — and in this repository that net is `test`,
6793
+ * which has run on push since the scaffold's first CI file. `ai-review` adds
6794
+ * no part of it and must not be read as adding one.
6795
+ */
6796
+ export const AI_REVIEW_PUSH_EVENT = "push";
6797
+
6798
+ /**
6799
+ * The one spelling of "this run is a push, so there is no pull request".
6800
+ *
6801
+ * A function and not four hand-written `if` lines, for the reason this module
6802
+ * gives everywhere else: four copies of one comparison are four things to
6803
+ * mutate, and a battery that removes one of them leaves the other three
6804
+ * holding the case up. `AI_REVIEW_PUSH_EVENT` decides the name and this
6805
+ * decides the comparison — exact string, `:-` default, the same shape the
6806
+ * `merge_group` branches use — so a test can remove the branch in one place
6807
+ * and watch every push case go red at once.
6808
+ *
6809
+ * The BODY is the caller's, because the four sites say four different true
6810
+ * things: the rounds step has outputs to blank, the carry step has a state to
6811
+ * declare, the restore step has nothing to restore, and the report step has a
6812
+ * verdict to reach. A shared body would be one of those four wearing the
6813
+ * other three's names.
6814
+ *
6815
+ * Trailing newlines are stripped so a call site can close its template
6816
+ * literal on a line of its own, and that is not cosmetic. `AC-6b` in
6817
+ * `test/ai-review-scaffold.test.ts` reads every line of THIS MODULE whose
6818
+ * trimmed form begins `exit ` and requires it to be `0` or the exported
6819
+ * constant — so a body ending `` exit 0`,`` reads as the literal ``0`,``
6820
+ * and reds the guard that keeps every refusal mutable in one place.
6821
+ * Measured: it did, on the first draft of this change.
6822
+ */
6823
+ export function aiReviewPushBranch(body: string): string {
6824
+ return `if [ "\${${AI_REVIEW_EVENT_VAR}:-}" = ${AI_REVIEW_PUSH_EVENT} ]; then\n${body.replace(/\n+$/, "")}\nfi`;
6825
+ }
6826
+
6514
6827
  /**
6515
6828
  * The bash that restores the untrusted path set BEFORE the baseline is read.
6516
6829
  *
@@ -6588,11 +6901,46 @@ export function buildRestoreScript(): string {
6588
6901
  `empty value as a write that never happened, and the drift step would ` +
6589
6902
  `refuse every run for a cause nothing names. Refusing`;
6590
6903
 
6904
+ // #1469. What a push to the default branch does here, and why it is a
6905
+ // branch rather than a third reading in the expression that sets
6906
+ // AI_REVIEW_BASE_REF_VAR.
6907
+ //
6908
+ // The tempting fix is `|| github.ref_name`, which is one token and makes
6909
+ // the refusal below stop firing. It is Silent Default Substitution: on a
6910
+ // push the checkout IS the branch, so "restore the untrusted paths from
6911
+ // the base" would fetch `origin/<branch>` — a ref that may already have
6912
+ // moved past the commit being built — and overwrite the tree with it. The
6913
+ // step would report success having done something nobody asked for, and
6914
+ // the drift reading downstream would carry the difference.
6915
+ //
6916
+ // There is no base here, and no review either: the action refuses `push`
6917
+ // as an unsupported event type, so nothing will read the paths this step
6918
+ // exists to make trustworthy. Saying that and publishing no base-remote
6919
+ // output is the complete reading. Both downstream consumers of that output
6920
+ // already treat an empty value as a reading rather than a failure — the
6921
+ // changed-files step warns and exits 0, and the drift step asks for the
6922
+ // base only when a restored path was modified, which cannot happen when
6923
+ // the reviewer never ran.
6924
+ const pushNoBase =
6925
+ `This run is a ${AI_REVIEW_PUSH_EVENT} to the default branch, so there is ` +
6926
+ `no pull request base to restore the untrusted paths from and no review ` +
6927
+ `that could read them — the review action refuses this event as an ` +
6928
+ `unsupported event type. Nothing was restored and nothing needed to be. ` +
6929
+ `The base-ref output is left empty deliberately, so the steps that read ` +
6930
+ `it report UNMEASURED rather than measuring against a ref this step ` +
6931
+ `invented.`;
6932
+
6591
6933
  return `# Generated by rungate — lib/scaffold/ai-review-step.ts. Do not edit.
6592
6934
  set -uo pipefail
6593
6935
 
6594
6936
  ${AI_REVIEW_ANNOTATION_ESCAPE}
6595
6937
 
6938
+ # FIRST, above the empty-base refusal, because on this event an empty base
6939
+ # ref is the correct reading rather than the failure that refusal describes.
6940
+ ${aiReviewPushBranch(` echo "::warning title=${AI_REVIEW_UNMEASURED_TITLE}::${pushNoBase}"
6941
+ exit 0
6942
+ `)}
6943
+
6596
6944
  if [ -z "\${${AI_REVIEW_BASE_REF_VAR}:-}" ]; then
6597
6945
  echo "::error title=${AI_REVIEW_DRIFT_TITLE}::${noRef}" >&2
6598
6946
  exit ${AI_REVIEW_REQUIRED_EXIT}
@@ -9904,6 +10252,15 @@ export function buildReviewRunStep(
9904
10252
  // Composed from the prepare step's output rather than spelled again, so
9905
10253
  // there is one declaration of where that directory is.
9906
10254
  ` ${AI_REVIEW_CARRY_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CARRY_BASENAME}`,
10255
+ // #1586. The same directory and the same composition rule. This step is
10256
+ // the WRITER of the snapshot; the adjudicator step below names the same
10257
+ // path from the same prepare-step output, so the two agree by
10258
+ // construction rather than through an output this step might not reach.
10259
+ ` ${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_LEDGER_SNAPSHOT_BASENAME}`,
10260
+ // The round this snapshot precedes, so it carries its own provenance.
10261
+ // Unset is not fatal: the reader refuses an unreadable provenance the
10262
+ // same way it refuses a stale one, by suppressing nothing.
10263
+ ` ${AI_REVIEW_SNAPSHOT_ROUND_VAR}: \${{ steps.${AI_REVIEW_ROUNDS_STEP_ID}.outputs.${AI_REVIEW_ROUND_OUTPUT} }}`,
9907
10264
  ` run: |`,
9908
10265
  ...buildCarryScript().trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
9909
10266
  ];
@@ -9959,6 +10316,12 @@ export function buildReviewRunStep(
9959
10316
  // workflow expression has no string operations and a second spelling
9960
10317
  // introduced here would be a decider the script could not see.
9961
10318
  ` ${AI_REVIEW_BASE_REF_VAR}: \${{ github.event.pull_request.base.ref || github.event.merge_group.base_ref }}`,
10319
+ // #1469. NOT a third `||` alternative above: a push has no base, and the
10320
+ // script needs to say so rather than be handed a ref that looks like
10321
+ // one. Same binding the rounds, carry and report steps read, and the
10322
+ // same reason it is `github.event_name` — the runner sets it and no
10323
+ // repository setting can.
10324
+ ` ${AI_REVIEW_EVENT_VAR}: \${{ github.event_name }}`,
9962
10325
  // The job's own token, for one fetch. It is not persisted into
9963
10326
  // `.git/config` and the reviewer runs in a later step with its own
9964
10327
  // environment, so nothing of it reaches the agent.
@@ -10046,6 +10409,18 @@ export function buildReviewRunStep(
10046
10409
  // when the writer did not reach it, the file is simply absent, which is
10047
10410
  // `CHANGED_FILES_UNREADABLE` and not a green check.
10048
10411
  ` ${AI_REVIEW_CHANGED_FILES_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CHANGED_FILES_BASENAME}`,
10412
+ // #1586, and restated here for #826's reason like the line above: a
10413
+ // step's `env:` does not carry to a later step. The carry step WROTE the
10414
+ // snapshot; these are the adjudicator's own copies, composed from the
10415
+ // same prepare output so the reader cannot be pointed at a path the
10416
+ // writer did not use.
10417
+ //
10418
+ // BOTH paths, and that is the point. The snapshot alone cannot say why
10419
+ // it is absent, and an absent snapshot read as "no earlier findings" is
10420
+ // the #1568 conflation arriving in the half that decides a required
10421
+ // check. The carry file carries the state; this one carries the bytes.
10422
+ ` ${AI_REVIEW_CARRY_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CARRY_BASENAME}`,
10423
+ ` ${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_LEDGER_SNAPSHOT_BASENAME}`,
10049
10424
  ` ${AI_REVIEW_EXECUTION_FILE_VAR}: \${{ steps.${AI_REVIEW_ACTION_STEP_ID}.outputs.execution_file }}`,
10050
10425
  // CRC-B1. The PATH, so the read-check can look for that exact string in
10051
10426
  // the transcript. #826 is why this is restated rather than inherited: a
@@ -12,7 +12,7 @@ import { readdirSorted } from "../readdir-sorted";
12
12
  import { fileExtensions } from "../file-extensions";
13
13
  import { join, basename, dirname, resolve, sep } from "path";
14
14
  import { auditSpecs } from "../../scripts/audit-specs";
15
- import { mayWrite, readDerivedDeclaration, skipLine } from "../derived-spec";
15
+ import { writeSpec } from "../write-spec";
16
16
  import { generateAgentsMd as buildAgentsMdContent, generateScopedRules } from "../generators/agents-md";
17
17
  import { HARNESS_PACKAGE, isHarnessItself } from "../harness-identity";
18
18
  import { scanSpecs } from "../scanner";
@@ -1699,16 +1699,13 @@ export function copySpecTemplateIfEmpty(specsDir: string, actions: string[]): vo
1699
1699
  // spec writers and missed this one, because its completeness check is built
1700
1700
  // from files that read and write the same path — and this writes a path it
1701
1701
  // never read. Ask who owns the bytes before replacing them.
1702
+ // #1552: the reading, the refusal line and the write are one call now.
1702
1703
  const existed = existsSync(destPath);
1703
- if (existed) {
1704
- const reading = readDerivedDeclaration(readFileSync(destPath, "utf-8"));
1705
- if (!mayWrite(reading)) {
1706
- actions.push(skipLine("specs/SPEC-TEMPLATE.md", reading));
1707
- return;
1708
- }
1704
+ const result = writeSpec(destPath, template, { label: "specs/SPEC-TEMPLATE.md" });
1705
+ if (!result.written) {
1706
+ actions.push(result.refusal!);
1707
+ return;
1709
1708
  }
1710
-
1711
- writeFileSync(destPath, template);
1712
1709
  // #1549: the verb is a reading, not a label. `CREATED` for a file that was
1713
1710
  // already on disk tells a reader scanning the report for destructive
1714
1711
  // actions the opposite of what happened.
@@ -3999,6 +3996,26 @@ on:
3999
3996
  # See the block comment in lib/scaffold/steps.ts: no branches: filter, and
4000
3997
  # its absence hangs a merge queue silently rather than failing it (#867).
4001
3998
  merge_group:
3999
+ # #1469. PROTECT-1 (lib/branch-protection.ts) refuses to recommend
4000
+ # required_status_checks.strict = false on a repository whose required
4001
+ # contexts do not run on push: to the default branch, and refuses
4002
+ # strict = true on a user-owned account because it serialises every PR.
4003
+ # A required ai-review that runs only on pull_request therefore has no
4004
+ # reading that clears, and this trigger is the refusal's own remedy.
4005
+ #
4006
+ # It does NOT review the commit. The review action throws
4007
+ # "Unsupported event type: push" before reading anything, exactly as it
4008
+ # does on merge_group, so every step that wants a pull request says it
4009
+ # had none and the report step annotates UNMEASURED and passes. What
4010
+ # push-CI buys here is the semantic-conflict net, and in this generated
4011
+ # set that is ci.yml's test job, which has had this trigger all along.
4012
+ #
4013
+ # The branch list is the consumer's own ci.branches, the same reading
4014
+ # ci.yml and gates.yml use. A literal here would be a second decider and
4015
+ # would be wrong on every repository whose default branch is not ours.
4016
+ push:
4017
+ branches:
4018
+ ${branchList}
4002
4019
  ${AI_REVIEW_PULL_REQUEST_TRIGGER}
4003
4020
 
4004
4021
  ${aiReviewPermissions}
@@ -4,8 +4,9 @@
4
4
  * replaces ACCEPTED status with SHIPPED + issue number.
5
5
  * Project-agnostic: never hardcodes any specific spec filename.
6
6
  */
7
- import { readFileSync, writeFileSync, existsSync } from "fs";
8
- import { mayWrite, readDerivedDeclaration, skipLine } from "./derived-spec";
7
+ import { readFileSync, existsSync } from "fs";
8
+ import { skipLine } from "./derived-spec";
9
+ import { maySpecBeWritten, writeSpec } from "./write-spec";
9
10
 
10
11
  export interface SpecUpdateInput {
11
12
  goalRecord: {
@@ -83,20 +84,23 @@ export async function updateSpecStatus(input: SpecUpdateInput): Promise<SpecUpda
83
84
  // #1286: marking a decision row SHIPPED is an in-place spec edit. On a
84
85
  // spec a generator owns it is discarded at the next regeneration, after
85
86
  // breaking whatever pins the file.
86
- const derived = readDerivedDeclaration(content);
87
- if (rowsUpdated > 0 && !mayWrite(derived)) {
88
- console.warn(skipLine(specPath, derived));
87
+ // #1552: asked early because the caller's `skipped`/`reason` fields are
88
+ // part of this function's contract, then asked again by `writeSpec`. Two
89
+ // consults of one decider — `mayWrite` — not two deciders.
90
+ const early = maySpecBeWritten(content);
91
+ if (rowsUpdated > 0 && !early.allowed) {
92
+ console.warn(skipLine(specPath, early.reading));
89
93
  return {
90
94
  updated: false,
91
95
  skipped: true,
92
96
  specPath,
93
97
  rowsUpdated: 0,
94
- reason: skipLine(specPath, derived),
98
+ reason: skipLine(specPath, early.reading),
95
99
  };
96
100
  }
97
101
 
98
102
  if (rowsUpdated > 0) {
99
- writeFileSync(specPath, content);
103
+ writeSpec(specPath, content);
100
104
  }
101
105
 
102
106
  return {