rungate 0.8.7 → 0.8.8

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.
@@ -1789,6 +1789,50 @@ export const AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR = "AI_REVIEW_LEDGER_SNAPSHOT_PAT
1789
1789
  /** The basename inside the findings directory. One spelling. */
1790
1790
  export const AI_REVIEW_LEDGER_SNAPSHOT_BASENAME = "ai-review-ledger-snapshot.txt";
1791
1791
 
1792
+ /**
1793
+ * Where the carry step leaves the pull request's REVIEW THREADS, which is
1794
+ * what the adjudicator now decides a repeat from (AC-1).
1795
+ *
1796
+ * ## What is in the file
1797
+ *
1798
+ * A JSON array, one entry per thread, each `{ isResolved, body }` where
1799
+ * `body` is the thread's FIRST comment — the one the poster wrote and the
1800
+ * only one carrying the `AI_REVIEW_THREAD_KEY_MARKER`. That is exactly the
1801
+ * shape `RawReviewThread` names, so bash does no interpretation: it writes
1802
+ * what GitHub returned and `threadReadingFromJson` decides.
1803
+ *
1804
+ * ## Why GraphQL and not `GET /pulls/{n}/comments`
1805
+ *
1806
+ * The REST list returns COMMENTS, not threads, and carries no resolution
1807
+ * state at all — `isResolved` exists only on the GraphQL `reviewThreads`
1808
+ * connection. Joining the two would mean matching a REST comment to a
1809
+ * GraphQL thread on `databaseId` and would put a second reader of the same
1810
+ * question in the step. One query returns both halves, so there is one.
1811
+ *
1812
+ * ## Written ONLY when the list was read — absence is the refusal
1813
+ *
1814
+ * The opposite of the snapshot's rule, and this heading used to state the
1815
+ * snapshot's by mistake. The file
1816
+ * here is the reading, so its absence has to mean "the step did not get far
1817
+ * enough to write one" and nothing else — `THREADS_NOT_READ`. A fetch that
1818
+ * fails writes no file and the adjudicator says so by name (AC-4) rather
1819
+ * than suppressing nothing in silence.
1820
+ */
1821
+ export const AI_REVIEW_THREADS_PATH_VAR = "AI_REVIEW_THREADS_PATH";
1822
+
1823
+ /** The basename inside the findings directory. One spelling. */
1824
+ export const AI_REVIEW_THREADS_BASENAME = "ai-review-threads.json";
1825
+
1826
+ /**
1827
+ * The GraphQL endpoint, handed to the carry step by the workflow.
1828
+ *
1829
+ * `github.graphql_url` and not a string built from `github.api_url`: on
1830
+ * GitHub Enterprise the two differ by more than a suffix (`/api/v3` against
1831
+ * `/api/graphql`), and a composed URL is a second spelling of a fact the
1832
+ * event already carries.
1833
+ */
1834
+ export const AI_REVIEW_GRAPHQL_VAR = "AI_REVIEW_GRAPHQL_URL";
1835
+
1792
1836
  /**
1793
1837
  * The round the snapshot was taken BEFORE, handed to the carry step so the
1794
1838
  * snapshot can carry its own provenance (#1586).
@@ -3766,6 +3810,38 @@ export const AI_REVIEW_FINDING_FIELDS = {
3766
3810
  failureScenario: "failure_scenario",
3767
3811
  } as const;
3768
3812
 
3813
+ /**
3814
+ * The marker that carries a posted thread's identity, so a later round can
3815
+ * ask the thread list whether a finding was already raised.
3816
+ *
3817
+ * Increment 1's prerequisite. The suppression gate's evidence is moving from
3818
+ * the ledger comment to the pull request's review threads, and a thread is
3819
+ * only usable as evidence if it can be reduced back to the key `carryKey`
3820
+ * forms for a fresh finding. Matching on the rendered prose is the near-miss:
3821
+ * a summary is model-written text that GitHub re-wraps, so the two sides
3822
+ * would key in different namespaces and the dedupe would silently suppress
3823
+ * nothing — the state `checkoutLineText`'s docblock measured at `kept: 1,
3824
+ * suppressed: 0` on a planted exact repeat.
3825
+ *
3826
+ * **The payload is base64 and that is load-bearing, not tidiness.** A key is
3827
+ * `file \0 anchor \0 summary` where the anchor is the TEXT at the cited line,
3828
+ * so every key contains a NUL and the text is arbitrary source — including
3829
+ * `-->`, which appears in this repository's own workflow emitters. Spelled
3830
+ * raw, such a key closes its own comment and a reader recovers a prefix,
3831
+ * which is a DIFFERENT key that still looks like one. Standard base64's
3832
+ * alphabet contains no `-`, so no encoded payload can terminate the comment.
3833
+ *
3834
+ * Versioned in the string. A reader meeting a marker it does not know must
3835
+ * treat the thread as unkeyed and re-post, the same one-sided safety
3836
+ * `AI_REVIEW_LEDGER_IDENTITY` has.
3837
+ *
3838
+ * Declared HERE for the reason `AI_REVIEW_FINDING_FIELDS` is: this module has
3839
+ * no relative imports, so it is the one module the mutation batteries that
3840
+ * copy `ai-review-findings.ts` alone into a scratch directory can carry with
3841
+ * it. A marker the deployed path cannot import is a marker it does not use.
3842
+ */
3843
+ export const AI_REVIEW_THREAD_KEY_MARKER = "rungate:ai-review-finding-key:v1";
3844
+
3769
3845
  /**
3770
3846
  * The key the verifier group's ballot hangs its per-finding votes off
3771
3847
  * (CRC-B4, #1476).
@@ -4837,6 +4913,136 @@ carry_unmeasured() {
4837
4913
  exit 0
4838
4914
  }
4839
4915
 
4916
+ # ── the pull request's review threads (AC-1) ────────────────────────────
4917
+ #
4918
+ # Fetched HERE, in the step that runs before the reviewer, for the reason the
4919
+ # snapshot is: a list taken later could contain this round's own threads, and
4920
+ # suppressing a payload against itself reports CLEAN forever. The adjudicator
4921
+ # reads this file; \`ai-review-threads\` posts into the same population
4922
+ # afterwards.
4923
+ #
4924
+ # Every refusal below writes NO FILE. An absent file is the adjudicator's
4925
+ # \`THREADS_NOT_READ\`, which suppresses nothing and says so by name — the
4926
+ # direction this is allowed to be wrong in is one advisory printed twice.
4927
+ # Writing \`[]\` on a failure would assert that the pull request has no
4928
+ # threads, which suppresses nothing while claiming to have looked.
4929
+ threads_unmeasured() {
4930
+ carry_note "the pull request's existing review threads could not be read, so a finding already raised may be raised again: \$1"
4931
+ }
4932
+
4933
+ threads_fetch() {
4934
+ if ! command -v jq >/dev/null 2>&1; then
4935
+ threads_unmeasured "jq is not on this runner and the GraphQL response is JSON."
4936
+ return 0
4937
+ fi
4938
+ if [ -z "\${${AI_REVIEW_LEDGER_TOKEN_VAR}:-}" ] || [ -z "\${${AI_REVIEW_LEDGER_REPO_VAR}:-}" ]; then
4939
+ threads_unmeasured "the API token or the repository name is missing from this step's environment."
4940
+ return 0
4941
+ fi
4942
+ graphql="\${${AI_REVIEW_GRAPHQL_VAR}:-https://api.github.com/graphql}"
4943
+ owner="\${${AI_REVIEW_LEDGER_REPO_VAR}%%/*}"
4944
+ name="\${${AI_REVIEW_LEDGER_REPO_VAR}#*/}"
4945
+ # Ask for the SLASH, not for the halves. \`owner = name\` was true of a
4946
+ # slashless string only by accident of the expansions, and it is equally
4947
+ # true of kubernetes/kubernetes — which silently disabled suppression for
4948
+ # every repository whose owner and name agree. AC-T2.
4949
+ case "\${${AI_REVIEW_LEDGER_REPO_VAR}}" in
4950
+ */*/*) repo_addressable=no ;;
4951
+ */*) repo_addressable=yes ;;
4952
+ *) repo_addressable=no ;;
4953
+ esac
4954
+ if [ "\${repo_addressable}" != "yes" ] || [ -z "\${owner}" ] || [ -z "\${name}" ]; then
4955
+ threads_unmeasured "the repository name '\${${AI_REVIEW_LEDGER_REPO_VAR}}' is not owner/name, so the query could not be addressed."
4956
+ return 0
4957
+ fi
4958
+
4959
+ # The \`body\` taken is the thread's FIRST comment and only the first. The
4960
+ # key marker is written by the poster; a later reply quoting it would make
4961
+ # one thread answer a finding it is not about.
4962
+ query='query(\$owner:String!,\$name:String!,\$number:Int!,\$cursor:String){repository(owner:\$owner,name:\$name){pullRequest(number:\$number){reviewThreads(first:100,after:\$cursor){pageInfo{hasNextPage endCursor}nodes{isResolved comments(first:1){nodes{body}}}}}}}'
4963
+
4964
+ threads_acc='[]'
4965
+ threads_cursor=''
4966
+ threads_page=1
4967
+ while [ "\${threads_page}" -le ${AI_REVIEW_CARRY_MAX_PAGES} ]; do
4968
+ if ! request=\$(jq -c -n --arg q "\${query}" --arg owner "\${owner}" --arg name "\${name}" \\
4969
+ --argjson number "\${${AI_REVIEW_LEDGER_PR_VAR}}" --arg cursor "\${threads_cursor}" \\
4970
+ '{query:\$q,variables:{owner:\$owner,name:\$name,number:\$number,cursor:(if \$cursor=="" then null else \$cursor end)}}'); then
4971
+ threads_unmeasured "the GraphQL request body could not be built."
4972
+ return 0
4973
+ fi
4974
+
4975
+ # \`-f\` is not enough and the difference matters: GraphQL answers a bad
4976
+ # credential, a missing scope and a deleted pull request with HTTP 200 and
4977
+ # an \`errors\` array, so a curl that succeeded says nothing about whether
4978
+ # the threads were read.
4979
+ if ! response=\$(curl -sS -f -X POST \\
4980
+ -H "Authorization: Bearer \${${AI_REVIEW_LEDGER_TOKEN_VAR}}" \\
4981
+ -H "Content-Type: application/json" \\
4982
+ -d "\${request}" "\${graphql}"); then
4983
+ threads_unmeasured "the GraphQL query failed on page \${threads_page}."
4984
+ return 0
4985
+ fi
4986
+ if printf '%s' "\${response}" | jq -e 'has("errors")' >/dev/null 2>&1; then
4987
+ threads_unmeasured "GraphQL returned errors on page \${threads_page}: \$(printf '%s' "\${response}" | jq -r '[.errors[]?.message] | join("; ")')"
4988
+ return 0
4989
+ fi
4990
+ if ! printf '%s' "\${response}" | jq -e '.data.repository.pullRequest.reviewThreads.nodes | type == "array"' >/dev/null 2>&1; then
4991
+ threads_unmeasured "the GraphQL response held no review-thread list on page \${threads_page}."
4992
+ return 0
4993
+ fi
4994
+
4995
+ # A null node is kept as a null-valued entry rather than dropped here.
4996
+ # The decision about what an unreadable thread means belongs to
4997
+ # \`threadReading\`, which has a negative control; jq silently dropping it
4998
+ # would be a second decider with none.
4999
+ if ! threads_acc=\$(printf '%s' "\${response}" | jq -c --argjson acc "\${threads_acc}" \\
5000
+ '\$acc + [.data.repository.pullRequest.reviewThreads.nodes[] | {isResolved:.isResolved, body:(.comments.nodes[0].body)}]'); then
5001
+ threads_unmeasured "the review threads on page \${threads_page} could not be reshaped."
5002
+ return 0
5003
+ fi
5004
+
5005
+ # Establish the field IS a boolean before reading it as one. The test
5006
+ # below is \`if ! <cmd>\`, which takes ANY non-zero exit, so every way of
5007
+ # failing to produce \`true\` was one observable: \`hasNextPage: false\`
5008
+ # (exit 1), an ABSENT \`pageInfo\` (also 1 — the path yields null), and a
5009
+ # MALFORMED one (5) all wrote whatever had accumulated and returned
5010
+ # success. A truncated thread list was therefore reported as a complete
5011
+ # read, which is the collapse this module refuses everywhere else.
5012
+ # Distinguishing the exit codes would not help; the type is the question.
5013
+ # AC-T3.
5014
+ if ! printf '%s' "\${response}" | jq -e '(.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage | type) == "boolean"' >/dev/null 2>&1; then
5015
+ threads_unmeasured "the GraphQL response on page \${threads_page} carried no boolean pageInfo.hasNextPage, so the end of the list could not be established."
5016
+ return 0
5017
+ fi
5018
+ if ! printf '%s' "\${response}" | jq -e '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage' >/dev/null 2>&1; then
5019
+ printf '%s' "\${threads_acc}" > "\${${AI_REVIEW_THREADS_PATH_VAR}}"
5020
+ return 0
5021
+ fi
5022
+ if ! threads_cursor=\$(printf '%s' "\${response}" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor // ""'); then
5023
+ threads_unmeasured "the cursor for page \$((threads_page + 1)) could not be read."
5024
+ return 0
5025
+ fi
5026
+ if [ -z "\${threads_cursor}" ]; then
5027
+ threads_unmeasured "GraphQL reported another page and gave no cursor to reach it."
5028
+ return 0
5029
+ fi
5030
+ threads_page=\$((threads_page + 1))
5031
+ done
5032
+ threads_unmeasured "this pull request has more than ${AI_REVIEW_CARRY_MAX_PAGES} pages of review threads, so the list was not read to its end."
5033
+ }
5034
+
5035
+ if [ -n "\${${AI_REVIEW_THREADS_PATH_VAR}:-}" ]; then
5036
+ if [ "\${${AI_REVIEW_EVENT_VAR}:-}" = merge_group ] || [ -z "\${${AI_REVIEW_LEDGER_PR_VAR}:-}" ]; then
5037
+ # No pull request, so no threads — and that is a COMPLETE reading, not a
5038
+ # failed one. An empty list here says "nothing has been raised before",
5039
+ # which is true of an entry that has no pull request to have raised it on.
5040
+ printf '[]' > "\${${AI_REVIEW_THREADS_PATH_VAR}}"
5041
+ else
5042
+ threads_fetch
5043
+ fi
5044
+ fi
5045
+
4840
5046
  # Nowhere to write. Nothing else in this step can be reported, so it says so
4841
5047
  # on the run and leaves.
4842
5048
  if [ -z "\${${AI_REVIEW_CARRY_PATH_VAR}:-}" ]; then
@@ -5088,6 +5294,33 @@ printf '%s' "\${flat}" | jq -c '.[]' | while IFS= read -r row; do
5088
5294
  esac
5089
5295
  done > "\${texts}"
5090
5296
 
5297
+ # AC-2. The bodies of the RESOLVED threads, raw, exactly as GitHub returned
5298
+ # them. Nothing is decoded here and no identity rule is restated: the filter
5299
+ # below takes the key it has ALREADY computed, encodes it the one way
5300
+ # \`threadBody\` encodes it, and asks whether a resolved body carries that
5301
+ # marker. Going the other way — decoding each body back to a key in jq —
5302
+ # would be a third reader of the key format after \`carryKey\` and
5303
+ # \`threadKeyFrom\`, which is #1568's shape: two readers of the same bytes
5304
+ # differing on a case neither author thought to name.
5305
+ #
5306
+ # AN UNREADABLE OR ABSENT LIST YIELDS \`[]\`, AND THAT IS NOT A SHRUG. Empty
5307
+ # means "no finding was shown to be answered", so every finding carries —
5308
+ # the direction in which a wrong answer is cheap. The inverse, reading an
5309
+ # unreadable list as "everything was answered", drops a live finding while
5310
+ # the required check reports CLEAN, which is exactly what #1597 cost.
5311
+ resolved_bodies='[]'
5312
+ if [ -n "\${${AI_REVIEW_THREADS_PATH_VAR}:-}" ] && [ -f "\${${AI_REVIEW_THREADS_PATH_VAR}}" ]; then
5313
+ # The emptiness test is NOT belt-and-braces. \`jq -c\` over a zero-byte file
5314
+ # exits 0 and prints nothing — empty input is zero iterations, not an error —
5315
+ # so the exit code alone leaves \`resolved_bodies\` as "", and \`--argjson\` is
5316
+ # then handed something that is not JSON and kills the carry. A present
5317
+ # zero-byte file is what an interrupted write leaves. AC-C10.
5318
+ if ! resolved_bodies=\$(jq -c '[ .[]? | select(.isResolved == true) | .body | select(type == "string") ]' "\${${AI_REVIEW_THREADS_PATH_VAR}}" 2>/dev/null) || [ -z "\${resolved_bodies}" ]; then
5319
+ resolved_bodies='[]'
5320
+ carry_note "the resolved review threads could not be read, so a finding a human already answered is carried forward and the reviewer may raise it again."
5321
+ fi
5322
+ fi
5323
+
5091
5324
  # The carry rule, and the DROP is the half that makes the rest mean anything:
5092
5325
  # without it this step carries everything unconditionally and a suite asserting
5093
5326
  # only that a finding gets carried is green against it.
@@ -5132,7 +5365,7 @@ done > "\${texts}"
5132
5365
  # and never keyed: keying under the wrong rule does not fail, it silently
5133
5366
  # compares two different things. The EARLIEST round wins, so a finding that
5134
5367
  # has survived three rounds says round 1 and not round 3.
5135
- if ! carried=\$(jq -sc --argjson base "\${flat}" '
5368
+ if ! carried=\$(jq -sc --argjson base "\${flat}" --argjson resolved "\${resolved_bodies}" '
5136
5369
  ${AI_REVIEW_JQ_NORM}
5137
5370
  [ range(0; (\$base | length)) as \$i | (\$base[\$i] + (.[\$i] // {})) ]
5138
5371
  | map(select(
@@ -5149,6 +5382,11 @@ if ! carried=\$(jq -sc --argjson base "\${flat}" '
5149
5382
  + "\\u0000" + (.${AI_REVIEW_FINDING_FIELDS.summary} | norm))
5150
5383
  else null end)
5151
5384
  })
5385
+ | map(select(
5386
+ .k == null
5387
+ or ((.k | @base64) as \$enc
5388
+ | ([ \$resolved[] | select(contains("${AI_REVIEW_THREAD_KEY_MARKER} " + \$enc + " -->")) ] | length) == 0)
5389
+ ))
5152
5390
  | (map(select(.k == null)) + (map(select(.k != null)) | group_by(.k) | map(sort_by(.round // 0) | .[0])))
5153
5391
  | sort_by([(.round // 0), (.${AI_REVIEW_FINDING_FIELDS.file} | norm), (.${AI_REVIEW_FINDING_FIELDS.summary} | norm)])
5154
5392
  ' "\${texts}" 2>/dev/null); then
@@ -5204,35 +5442,27 @@ fi
5204
5442
 
5205
5443
  carry_state '${AI_REVIEW_CARRY_READ}'
5206
5444
 
5207
- # The ledger's own bytes, for the adjudicator to key in TypeScript (#1586).
5445
+ # The ledger snapshot was written here for the adjudicator to key repeats
5446
+ # from (#1586). IT IS GONE, because its reader is (AC-5, Increment 1c).
5208
5447
  #
5209
- # HERE and not at adjudication time: the persist step upserts THIS round into
5210
- # that same comment before the adjudicator runs, so a later fetch would read
5211
- # the payload it is deciding about as its own prior and suppress all of it.
5448
+ # AC-1 moved the suppression gate onto the pull request's review THREADS:
5449
+ # \`SuppressionInputs\` now carries \`threads\` and nothing else, and
5450
+ # \`scripts/ai-review-findings.ts\` reads \`AI_REVIEW_THREADS_PATH\` and
5451
+ # \`AI_REVIEW_BALLOT_DIR\` and no third variable. \`ledgerPriorKeysFrom\` and
5452
+ # \`readSnapshot\` kept compiling because tests still import them, so nothing
5453
+ # went red when the last production caller went away.
5212
5454
  #
5213
- # ON THE READ PATH ONLY, and after the parse above succeeded. The state the
5214
- # adjudicator gates on lives in the carry file, which \`carry_state\` writes on
5215
- # every path — so an absent snapshot is never read as "no earlier findings",
5216
- # it is read as whichever of the three states that one site recorded.
5455
+ # What made this worth deleting rather than leaving: the failure path emitted
5456
+ # \`repeats will not be suppressed on this round\`, and that sentence had
5457
+ # become FALSE. Suppression comes from the thread list, which this step
5458
+ # fetches separately and which is unaffected by whether these bytes land. A
5459
+ # warning that names the wrong consequence is worse than no warning — it
5460
+ # tells a reader to expect duplicate threads that will not appear, and it
5461
+ # reads as evidence the snapshot is load-bearing.
5217
5462
  #
5218
- # A failed write is a WARNING and not a refusal: the carry itself succeeded
5219
- # and the reviewer's copy is already on disk. The adjudicator seeing no
5220
- # snapshot suppresses nothing, which is the direction this is allowed to be
5221
- # wrong in — a repeat gets posted twice, rather than a live finding dropped.
5222
- if [ -n "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}:-}" ]; then
5223
- # The provenance line FIRST, then the body verbatim. The reader refuses a
5224
- # snapshot holding a round at or past this number, which is the only thing
5225
- # that tells a snapshot taken here from one taken after the persist step —
5226
- # they are otherwise the same comment fetched by the same selector, and the
5227
- # later one suppresses the whole round it is deciding about.
5228
- if ! {
5229
- printf '%s=%s\\n' '${AI_REVIEW_SNAPSHOT_ROUND_KEY}' "\${${AI_REVIEW_SNAPSHOT_ROUND_VAR}:-}"
5230
- printf '%s' "\${selected}" | jq -r '.body // ""'
5231
- } > "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}}"; then
5232
- rm -f "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}}"
5233
- 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."
5234
- fi
5235
- fi
5463
+ # Deleting the write and leaving the \`env:\` declarations would have been the
5464
+ # quieter half-fix: a variable declared on two steps and read by none looks
5465
+ # exactly like one that is used. Both declarations go with it.
5236
5466
 
5237
5467
  {
5238
5468
  printf 'carried_count=%s\\n' "\${carried_count}"
@@ -10552,7 +10782,8 @@ case "\${total_truncated}" in
10552
10782
  esac
10553
10783
  {
10554
10784
  printf '%s\\n' '${AI_REVIEW_LEDGER_MARKER}'
10555
- printf '%s\\n\\n' '### AI review findings ledger'
10785
+ printf '%s\\n' '<details>'
10786
+ printf '%s\\n\\n' '<summary>AI review findings ledger — machine state, carried to the next round. Nothing here needs a human.</summary>'
10556
10787
  printf '%s\\n\\n' 'Written by the AI Review workflow, one entry per round, so the finding set is cumulative across rounds rather than evaporating with each runner (#1168).'
10557
10788
  printf '%s\\n\\n' 'A \`${AI_REVIEW_FINDINGS_KEY}\` of null means the round was NOT measured — the payload was absent or unparseable. An empty array means the round was read and found nothing. They are different facts.'
10558
10789
  printf '%s\\n\\n' 'THIS IS A WINDOW, NOT A HISTORY. At most ${AI_REVIEW_LEDGER_MAX_ROUNDS} rounds are retained, and fewer when they would not fit — a comment body has a hard ${AI_REVIEW_LEDGER_MAX_BODY} character limit, so the body is rendered and measured before it is written. \`${AI_REVIEW_LEDGER_TRUNCATED_FIELD}\` is how many rounds have fallen off the front of it, by either route. A dropped round is gone rather than empty, so a finding only that round recorded can no longer be carried forward; without the count, nothing downstream could tell that from a finding nobody ever raised. An ABSENT \`${AI_REVIEW_LEDGER_TRUNCATED_FIELD}\` means the depth is unknown, which is not the same as zero.'
@@ -10561,6 +10792,7 @@ esac
10561
10792
  printf '%s\\n' '${fence}json'
10562
10793
  printf '%s\\n' "\${doc}"
10563
10794
  printf '%s\\n' '${fence}'
10795
+ printf '%s\\n' '</details>'
10564
10796
  } > "\${body_file}"
10565
10797
 
10566
10798
  # The RENDERED body, in bytes. \`wc -c\` counts bytes and GitHub's limit is in
@@ -10844,11 +11076,14 @@ export function buildReviewRunStep(
10844
11076
  // Composed from the prepare step's output rather than spelled again, so
10845
11077
  // there is one declaration of where that directory is.
10846
11078
  ` ${AI_REVIEW_CARRY_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CARRY_BASENAME}`,
10847
- // #1586. The same directory and the same composition rule. This step is
10848
- // the WRITER of the snapshot; the adjudicator step below names the same
10849
- // path from the same prepare-step output, so the two agree by
10850
- // construction rather than through an output this step might not reach.
10851
- ` ${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_LEDGER_SNAPSHOT_BASENAME}`,
11079
+ // AC-1. The same directory and the same composition rule. This step
11080
+ // is the WRITER of the thread list and the adjudicator below is its only
11081
+ // reader; both compose the path from this one output, so they agree by
11082
+ // construction rather than through a spelling either could edit alone.
11083
+ ` ${AI_REVIEW_THREADS_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_THREADS_BASENAME}`,
11084
+ // Taken from the event rather than built from the REST URL: on GitHub
11085
+ // Enterprise `/api/v3` and `/api/graphql` are not a suffix apart.
11086
+ ` ${AI_REVIEW_GRAPHQL_VAR}: \${{ github.graphql_url }}`,
10852
11087
  // The round this snapshot precedes, so it carries its own provenance.
10853
11088
  // Unset is not fatal: the reader refuses an unreadable provenance the
10854
11089
  // same way it refuses a stale one, by suppressing nothing.
@@ -11030,7 +11265,11 @@ export function buildReviewRunStep(
11030
11265
  // the #1568 conflation arriving in the half that decides a required
11031
11266
  // check. The carry file carries the state; this one carries the bytes.
11032
11267
  ` ${AI_REVIEW_CARRY_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CARRY_BASENAME}`,
11033
- ` ${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_LEDGER_SNAPSHOT_BASENAME}`,
11268
+ // AC-1. What the suppression gate actually decides from since the move
11269
+ // off the ledger. Restated here for #826's reason, composed from the
11270
+ // same prepare output the carry step wrote it to — and an absent file is
11271
+ // a NAMED refusal in the adjudicator, not an empty prior set.
11272
+ ` ${AI_REVIEW_THREADS_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_THREADS_BASENAME}`,
11034
11273
  ` ${AI_REVIEW_EXECUTION_FILE_VAR}: \${{ steps.${AI_REVIEW_ACTION_STEP_ID}.outputs.execution_file }}`,
11035
11274
  // CRC-B1. The PATH, so the read-check can look for that exact string in
11036
11275
  // the transcript. #826 is why this is restated rather than inherited: a
@@ -11189,6 +11428,12 @@ export function buildReviewRunStep(
11189
11428
  ` ${AI_REVIEW_THREADS_SHA_VAR}: \${{ github.event.pull_request.head.sha }}`,
11190
11429
  ` ${AI_REVIEW_THREADS_REPO_VAR}: \${{ github.repository }}`,
11191
11430
  ` ${AI_REVIEW_THREADS_TOKEN_VAR}: \${{ secrets.GITHUB_TOKEN }}`,
11431
+ // AC-3. This step POSTS the threads, so it is the one that can create a
11432
+ // duplicate, and until now it was the only reader handed no suppression
11433
+ // gate — the adjudicator dropped a repeat from its annotation while this
11434
+ // step opened a second thread for it. Same file, same prepare-step
11435
+ // output, so the two form one answer rather than two that agree.
11436
+ ` ${AI_REVIEW_THREADS_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_THREADS_BASENAME}`,
11192
11437
  ` run: |`,
11193
11438
  ...buildThreadsScript(version).trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
11194
11439
  ];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.7",
3
+ "version": "0.8.8",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {
@@ -75,13 +75,14 @@
75
75
  * it reads the CHECKOUT, which a reader running from a scratch directory
76
76
  * does not have.
77
77
  *
78
- * It takes TWO paths, and that is the part worth not collapsing. The carry
79
- * file holds the carry step's own three-state reading and is written on
80
- * every path; the snapshot holds the ledger's bytes and exists only on the
81
- * READ path. An absent snapshot is therefore not "no prior findings" — the
82
- * carry file says which. Unset either and the gate is `null`: a consumer on
83
- * an older scaffold gets the pre-#1586 reading, not a silent "nothing was a
84
- * repeat".
78
+ * Since AC-1 it takes ONE path, and the collapse from two is not a loss.
79
+ * The ledger needed a pair — bytes, plus a state file saying why the bytes
80
+ * were absent — because an absent snapshot could mean three different
81
+ * things. The thread list is itself the reading: it is written only when the
82
+ * fetch completed, so absent means exactly "not read", and the adjudicator
83
+ * names that rather than suppressing nothing in silence. Unset the variable
84
+ * and the gate is `null`: a consumer on an older scaffold gets the
85
+ * pre-#1586 reading, not a quiet "nothing was a repeat".
85
86
  *
86
87
  * **A blocking finding never reaches this gate.**
87
88
  * `findingMustAlwaysBeReported` filters first, inside the reader, so no
@@ -97,11 +98,7 @@ import {
97
98
  readOrNull,
98
99
  } from "../lib/ai-review-suppression";
99
100
  import { main } from "../lib/scaffold/ai-review-findings";
100
- import {
101
- AI_REVIEW_BALLOT_DIR_ENV,
102
- AI_REVIEW_CARRY_PATH_VAR,
103
- AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR,
104
- } from "../lib/scaffold/ai-review-step";
101
+ import { AI_REVIEW_BALLOT_DIR_ENV, AI_REVIEW_THREADS_PATH_VAR } from "../lib/scaffold/ai-review-step";
105
102
 
106
103
  const ballotDir = process.env[AI_REVIEW_BALLOT_DIR_ENV];
107
104
  const jury =
@@ -109,14 +106,12 @@ const jury =
109
106
  ? null
110
107
  : (blocking: readonly unknown[]) => aiReviewJuryGate(blocking, ballotDir);
111
108
 
112
- const carryPath = process.env[AI_REVIEW_CARRY_PATH_VAR];
113
- const snapshotPath = process.env[AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR];
109
+ const threadsPath = process.env[AI_REVIEW_THREADS_PATH_VAR];
114
110
  const suppress =
115
- carryPath === undefined || carryPath === ""
111
+ threadsPath === undefined || threadsPath === ""
116
112
  ? null
117
113
  : aiReviewSuppressionGate({
118
- carry: readOrNull(carryPath),
119
- snapshot: readOrNull(snapshotPath),
114
+ threads: readOrNull(threadsPath),
120
115
  lineTextFor: checkoutLineText(process.cwd()),
121
116
  });
122
117
 
@@ -41,6 +41,13 @@ import {
41
41
  readAiReviewChangedFiles,
42
42
  readAiReviewFindingsFile,
43
43
  } from "../lib/scaffold/ai-review-findings";
44
+ import { carryKey } from "../lib/ai-review-rounds";
45
+ import {
46
+ aiReviewSuppressionGate,
47
+ checkoutLineText,
48
+ readOrNull,
49
+ } from "../lib/ai-review-suppression";
50
+ import { AI_REVIEW_THREADS_PATH_VAR } from "../lib/scaffold/ai-review-step";
44
51
 
45
52
  const COMMAND = "ai-review-threads";
46
53
 
@@ -113,7 +120,31 @@ if (!parsed.ok) {
113
120
  process.exit(0);
114
121
  }
115
122
 
116
- const reading = readAiReviewFindingsFile(parsed.findings, readAiReviewChangedFiles(parsed.changed));
123
+ // AC-3, and it is the half AC-1 alone does not reach. `reviewThreadRequests`
124
+ // posts `reading.reported`, and until now this reader was handed NO
125
+ // suppression gate — so the adjudicator could drop a repeat from its
126
+ // annotation while this step posted a thread for it anyway. Measured on
127
+ // #1616: 11 threads for 3 distinct findings, one new copy per push.
128
+ //
129
+ // The gate is the same function the adjudicator builds, over the same file,
130
+ // which is what makes "already raised" one decision rather than two that
131
+ // agree until they do not. This step runs BEFORE the adjudicator in the
132
+ // emitted job, so it cannot be handed the adjudicator's answer — it has to
133
+ // form its own from the same input.
134
+ const threadsPath = process.env[AI_REVIEW_THREADS_PATH_VAR];
135
+ const suppress =
136
+ threadsPath === undefined || threadsPath === ""
137
+ ? null
138
+ : aiReviewSuppressionGate({
139
+ threads: readOrNull(threadsPath),
140
+ lineTextFor: checkoutLineText(process.cwd()),
141
+ });
142
+
143
+ const reading = readAiReviewFindingsFile(
144
+ parsed.findings,
145
+ readAiReviewChangedFiles(parsed.changed),
146
+ suppress,
147
+ );
117
148
 
118
149
  const client = createGitHubClient();
119
150
  const post: AiReviewThreadPoster = async request => {
@@ -141,7 +172,15 @@ const post: AiReviewThreadPoster = async request => {
141
172
  }
142
173
  };
143
174
 
144
- const result = await postReviewThreads(reading, post);
175
+ // THE KEY-SYMMETRY HALF, on the producing side. The thread carries the key
176
+ // a later round's suppression gate will form for the same finding, so the
177
+ // text anchor must be read the same way both sides read it — which is why
178
+ // this is `checkoutLineText` and not a second line reader. A caller that
179
+ // supplied no text would key `n:<line>` while the gate keys `t:<text>`, and
180
+ // the two namespaces never collide: the gate would suppress nothing and
181
+ // every round would re-post every thread.
182
+ const lineTextFor = checkoutLineText(process.cwd());
183
+ const result = await postReviewThreads(reading, post, f => carryKey(f, lineTextFor(f)));
145
184
  for (const line of result.detail) console.log(`${COMMAND}: ${line}`);
146
185
  console.log(
147
186
  `${COMMAND}: ${result.outcome} — attempted ${result.attempted}, posted ${result.posted}, ` +