rungate 0.8.6 → 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).
@@ -3102,6 +3146,141 @@ export const AI_REVIEW_PERSIST_STEP_ID = "ai-review-persist";
3102
3146
 
3103
3147
  export const AI_REVIEW_PERSIST_STEP_NAME = "Persist this round's findings to the pull request";
3104
3148
 
3149
+ /**
3150
+ * The step that puts the findings ON THE DIFF, as review threads (#1612).
3151
+ *
3152
+ * ## Why this is not what the persist step already does
3153
+ *
3154
+ * The persist step upserts the findings LEDGER, and a ledger is an issue
3155
+ * comment: `POST /repos/{o}/{r}/issues/{n}/comments`. A review thread comes
3156
+ * from a different endpoint — `POST /repos/{o}/{r}/pulls/{n}/comments` — and
3157
+ * the difference is not presentational. `required_conversation_resolution`
3158
+ * reads review threads and nothing else, so a repository that switches that
3159
+ * protection on while its reviewer posts issue comments has a required gate
3160
+ * over a population that is always empty: green by construction, forever.
3161
+ *
3162
+ * Measured 2026-10-25 across every merged pull request on the first consumer
3163
+ * to run this job: zero review threads. The reviewer's entire output has been
3164
+ * a GitHub Actions annotation, which lives as long as the run log and cannot
3165
+ * be replied to, resolved, or found again from the pull request.
3166
+ *
3167
+ * ## Position: BETWEEN the reviewer and the adjudicator
3168
+ *
3169
+ * The same slot the persist step occupies, for the same reason stated there.
3170
+ * The payload exists by here, and the adjudicator — which exits non-zero on a
3171
+ * blocking finding — has not run yet. So this step needs no `if:`, which
3172
+ * matters because `aiReviewAuthScript` in `lib/conformity.ts` refuses an
3173
+ * `if:` on any step in this job for every consumer: a step skipped by a
3174
+ * condition reports `skipped`, and a skipped required check can be configured
3175
+ * to count as satisfied.
3176
+ *
3177
+ * Putting it AFTER the adjudicator would need exactly that forbidden `if:`,
3178
+ * and would post comments only on reviews that found nothing.
3179
+ *
3180
+ * ## It does not decide the pull request's fate
3181
+ *
3182
+ * The adjudicator does. This step refuses only when it HAD comments to post
3183
+ * and could not post them — its own job failing, which is a different fact
3184
+ * from a finding. A fork pull request, whose token GitHub downgrades to
3185
+ * read-only whatever this workflow declares, degrades with a warning instead:
3186
+ * the annotation still carries the review, and reddening every fork for
3187
+ * something a contributor cannot fix would teach everyone to ignore the red.
3188
+ */
3189
+ export const AI_REVIEW_THREADS_STEP_ID = "ai-review-threads";
3190
+
3191
+ export const AI_REVIEW_THREADS_STEP_NAME = "Post this round's findings onto the diff";
3192
+
3193
+ /** The registered CLI name. One declaration, read by the generator and the tests. */
3194
+ export const AI_REVIEW_THREADS_COMMAND = "ai-review-threads";
3195
+
3196
+ export const AI_REVIEW_THREADS_PR_VAR = "AI_REVIEW_THREADS_PR";
3197
+ export const AI_REVIEW_THREADS_REPO_VAR = "AI_REVIEW_THREADS_REPO";
3198
+ export const AI_REVIEW_THREADS_SHA_VAR = "AI_REVIEW_THREADS_SHA";
3199
+ export const AI_REVIEW_THREADS_TOKEN_VAR = "AI_REVIEW_THREADS_TOKEN";
3200
+
3201
+ /**
3202
+ * The script the threads step runs.
3203
+ *
3204
+ * Everything it decides, it decides in the shell and not in an `if:`, for the
3205
+ * reason the step id documents. Two of those decisions are worth naming:
3206
+ *
3207
+ * **No pull request means nothing to post, and that is not a failure.** A
3208
+ * `merge_group` run carries no `github.event.pull_request`, so the variable
3209
+ * arrives empty. The same reading the ledger step takes, rather than a second
3210
+ * `github.event_name` test, so there is one decider.
3211
+ *
3212
+ * **An absent payload is UNMEASURED and exits 0.** A review that wrote
3213
+ * nothing has not found nothing. The adjudicator is the step that turns that
3214
+ * into a verdict; this one says what it saw and gets out of the way, because
3215
+ * two steps refusing over the same reading are a pair of deciders no
3216
+ * behavioural test can tell apart.
3217
+ *
3218
+ * **A pin that predates the command is UNMEASURED, and is told apart from a
3219
+ * failure.** The generated job runs `bunx rungate@<version>`, a PUBLISHED
3220
+ * version, and this YAML reaches every consumer the moment it is merged —
3221
+ * while the npm release happens later, from a tag. So there is a window in
3222
+ * which the live workflow asks a published package for a subcommand it does
3223
+ * not have. `bin/rungate.ts` answers that with exit 1 and the exact string
3224
+ * `unknown command "<name>"`, which is the one signal that separates *the
3225
+ * release has not landed yet* from *the producer is broken* — and they are
3226
+ * otherwise the same non-zero exit. Without this branch, merging this file
3227
+ * reds every pull request in every consumer until a release ships.
3228
+ *
3229
+ * The capture consumes its own status with a top-level `|| threads_code=$?`,
3230
+ * which is #1110's lesson and the form the rest of this file uses. A
3231
+ * generated `run:` block executes under `bash -e`, so an assignment whose
3232
+ * command substitution fails aborts the step before the next line — and the
3233
+ * branch above would be dead code that reads as live.
3234
+ *
3235
+ * `set +e` would also work and is the wrong answer twice over: AC-2 in
3236
+ * `test/ai-review-runner-shell-parity.test.ts` is textual and cannot see it,
3237
+ * so the guard against this exact defect would go quiet; and an `-e`
3238
+ * suspension at a distance is the kind of line a later edit deletes without
3239
+ * knowing what depended on it. The initialiser above the assignment is what
3240
+ * keeps `set -u` happy on the success path.
3241
+ */
3242
+ export function buildThreadsScript(version: string): string {
3243
+ const poster =
3244
+ `bunx ${AI_REVIEW_ADJUDICATOR_PACKAGE}@${version} ${AI_REVIEW_THREADS_COMMAND}`;
3245
+ // Matched with `grep -qF` inside SINGLE quotes, where a double quote is
3246
+ // literal and needs no escaping. The quotes are part of the signal:
3247
+ // `bin/rungate.ts` prints the name quoted, and an unquoted match would
3248
+ // also hit a findings summary that happened to mention the command.
3249
+ const skew = `unknown command "${AI_REVIEW_THREADS_COMMAND}"`;
3250
+ return [
3251
+ `set -uo pipefail`,
3252
+ ``,
3253
+ `if [ -z "\${${AI_REVIEW_THREADS_PR_VAR}:-}" ]; then`,
3254
+ ` echo "${AI_REVIEW_THREADS_COMMAND}: no pull request on this event (merge_group), nothing to post"`,
3255
+ ` exit 0`,
3256
+ `fi`,
3257
+ ``,
3258
+ `if [ ! -s "\${${AI_REVIEW_FINDINGS_PATH_VAR}:-}" ]; then`,
3259
+ ` echo "::warning title=AI review threads::UNMEASURED - no findings payload was written, so no review threads were posted. This is not a review that found nothing."`,
3260
+ ` exit 0`,
3261
+ `fi`,
3262
+ ``,
3263
+ `# \`run:\` is \`bash -e\`, so the assignment consumes its own status with a`,
3264
+ `# top-level \`||\` — see buildThreadsScript. Without it the step aborts`,
3265
+ `# here and the version-skew branch below never runs.`,
3266
+ `threads_code=0`,
3267
+ `threads_out="$(GITHUB_TOKEN="\${${AI_REVIEW_THREADS_TOKEN_VAR}}" ${poster} \\`,
3268
+ ` "\${${AI_REVIEW_FINDINGS_PATH_VAR}}" \\`,
3269
+ ` --repo "\${${AI_REVIEW_THREADS_REPO_VAR}}" \\`,
3270
+ ` --pr "\${${AI_REVIEW_THREADS_PR_VAR}}" \\`,
3271
+ ` --commit "\${${AI_REVIEW_THREADS_SHA_VAR}}" \\`,
3272
+ ` --changed-files "\${${AI_REVIEW_CHANGED_FILES_PATH_VAR}}" 2>&1)" || threads_code=$?`,
3273
+ `printf '%s\\n' "$threads_out"`,
3274
+ ``,
3275
+ `if [ "$threads_code" -ne 0 ] && printf '%s' "$threads_out" | grep -qF '${skew}'; then`,
3276
+ ` echo "::warning title=AI review threads::UNMEASURED - rungate@${version} does not carry the ${AI_REVIEW_THREADS_COMMAND} command yet, so no review threads were posted. This workflow is ahead of the published package; it resolves itself on the next release."`,
3277
+ ` exit 0`,
3278
+ `fi`,
3279
+ ``,
3280
+ `exit "$threads_code"`,
3281
+ ].join("\n");
3282
+ }
3283
+
3105
3284
  /**
3106
3285
  * ## The witness on the UNMEASURED route (#1307)
3107
3286
  *
@@ -3631,6 +3810,38 @@ export const AI_REVIEW_FINDING_FIELDS = {
3631
3810
  failureScenario: "failure_scenario",
3632
3811
  } as const;
3633
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
+
3634
3845
  /**
3635
3846
  * The key the verifier group's ballot hangs its per-finding votes off
3636
3847
  * (CRC-B4, #1476).
@@ -4702,6 +4913,136 @@ carry_unmeasured() {
4702
4913
  exit 0
4703
4914
  }
4704
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
+
4705
5046
  # Nowhere to write. Nothing else in this step can be reported, so it says so
4706
5047
  # on the run and leaves.
4707
5048
  if [ -z "\${${AI_REVIEW_CARRY_PATH_VAR}:-}" ]; then
@@ -4953,6 +5294,33 @@ printf '%s' "\${flat}" | jq -c '.[]' | while IFS= read -r row; do
4953
5294
  esac
4954
5295
  done > "\${texts}"
4955
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
+
4956
5324
  # The carry rule, and the DROP is the half that makes the rest mean anything:
4957
5325
  # without it this step carries everything unconditionally and a suite asserting
4958
5326
  # only that a finding gets carried is green against it.
@@ -4997,7 +5365,7 @@ done > "\${texts}"
4997
5365
  # and never keyed: keying under the wrong rule does not fail, it silently
4998
5366
  # compares two different things. The EARLIEST round wins, so a finding that
4999
5367
  # has survived three rounds says round 1 and not round 3.
5000
- if ! carried=\$(jq -sc --argjson base "\${flat}" '
5368
+ if ! carried=\$(jq -sc --argjson base "\${flat}" --argjson resolved "\${resolved_bodies}" '
5001
5369
  ${AI_REVIEW_JQ_NORM}
5002
5370
  [ range(0; (\$base | length)) as \$i | (\$base[\$i] + (.[\$i] // {})) ]
5003
5371
  | map(select(
@@ -5014,6 +5382,11 @@ if ! carried=\$(jq -sc --argjson base "\${flat}" '
5014
5382
  + "\\u0000" + (.${AI_REVIEW_FINDING_FIELDS.summary} | norm))
5015
5383
  else null end)
5016
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
+ ))
5017
5390
  | (map(select(.k == null)) + (map(select(.k != null)) | group_by(.k) | map(sort_by(.round // 0) | .[0])))
5018
5391
  | sort_by([(.round // 0), (.${AI_REVIEW_FINDING_FIELDS.file} | norm), (.${AI_REVIEW_FINDING_FIELDS.summary} | norm)])
5019
5392
  ' "\${texts}" 2>/dev/null); then
@@ -5069,35 +5442,27 @@ fi
5069
5442
 
5070
5443
  carry_state '${AI_REVIEW_CARRY_READ}'
5071
5444
 
5072
- # 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).
5073
5447
  #
5074
- # HERE and not at adjudication time: the persist step upserts THIS round into
5075
- # that same comment before the adjudicator runs, so a later fetch would read
5076
- # 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.
5077
5454
  #
5078
- # ON THE READ PATH ONLY, and after the parse above succeeded. The state the
5079
- # adjudicator gates on lives in the carry file, which \`carry_state\` writes on
5080
- # every path — so an absent snapshot is never read as "no earlier findings",
5081
- # 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.
5082
5462
  #
5083
- # A failed write is a WARNING and not a refusal: the carry itself succeeded
5084
- # and the reviewer's copy is already on disk. The adjudicator seeing no
5085
- # snapshot suppresses nothing, which is the direction this is allowed to be
5086
- # wrong in — a repeat gets posted twice, rather than a live finding dropped.
5087
- if [ -n "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}:-}" ]; then
5088
- # The provenance line FIRST, then the body verbatim. The reader refuses a
5089
- # snapshot holding a round at or past this number, which is the only thing
5090
- # that tells a snapshot taken here from one taken after the persist step —
5091
- # they are otherwise the same comment fetched by the same selector, and the
5092
- # later one suppresses the whole round it is deciding about.
5093
- if ! {
5094
- printf '%s=%s\\n' '${AI_REVIEW_SNAPSHOT_ROUND_KEY}' "\${${AI_REVIEW_SNAPSHOT_ROUND_VAR}:-}"
5095
- printf '%s' "\${selected}" | jq -r '.body // ""'
5096
- } > "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}}"; then
5097
- rm -f "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}}"
5098
- 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."
5099
- fi
5100
- 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.
5101
5466
 
5102
5467
  {
5103
5468
  printf 'carried_count=%s\\n' "\${carried_count}"
@@ -10417,7 +10782,8 @@ case "\${total_truncated}" in
10417
10782
  esac
10418
10783
  {
10419
10784
  printf '%s\\n' '${AI_REVIEW_LEDGER_MARKER}'
10420
- 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>'
10421
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).'
10422
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.'
10423
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.'
@@ -10426,6 +10792,7 @@ esac
10426
10792
  printf '%s\\n' '${fence}json'
10427
10793
  printf '%s\\n' "\${doc}"
10428
10794
  printf '%s\\n' '${fence}'
10795
+ printf '%s\\n' '</details>'
10429
10796
  } > "\${body_file}"
10430
10797
 
10431
10798
  # The RENDERED body, in bytes. \`wc -c\` counts bytes and GitHub's limit is in
@@ -10709,11 +11076,14 @@ export function buildReviewRunStep(
10709
11076
  // Composed from the prepare step's output rather than spelled again, so
10710
11077
  // there is one declaration of where that directory is.
10711
11078
  ` ${AI_REVIEW_CARRY_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CARRY_BASENAME}`,
10712
- // #1586. The same directory and the same composition rule. This step is
10713
- // the WRITER of the snapshot; the adjudicator step below names the same
10714
- // path from the same prepare-step output, so the two agree by
10715
- // construction rather than through an output this step might not reach.
10716
- ` ${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 }}`,
10717
11087
  // The round this snapshot precedes, so it carries its own provenance.
10718
11088
  // Unset is not fatal: the reader refuses an unreadable provenance the
10719
11089
  // same way it refuses a stale one, by suppressing nothing.
@@ -10895,7 +11265,11 @@ export function buildReviewRunStep(
10895
11265
  // the #1568 conflation arriving in the half that decides a required
10896
11266
  // check. The carry file carries the state; this one carries the bytes.
10897
11267
  ` ${AI_REVIEW_CARRY_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CARRY_BASENAME}`,
10898
- ` ${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}`,
10899
11273
  ` ${AI_REVIEW_EXECUTION_FILE_VAR}: \${{ steps.${AI_REVIEW_ACTION_STEP_ID}.outputs.execution_file }}`,
10900
11274
  // CRC-B1. The PATH, so the read-check can look for that exact string in
10901
11275
  // the transcript. #826 is why this is restated rather than inherited: a
@@ -11023,6 +11397,47 @@ export function buildReviewRunStep(
11023
11397
  ...buildPersistScript().trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
11024
11398
  ];
11025
11399
 
11400
+ // #1612. BESIDE the persist step and in the same slot, for the same
11401
+ // reason — see `AI_REVIEW_THREADS_STEP_ID`. The reviewer has written its
11402
+ // payload by here and the adjudicator has not run, so this needs no `if:`,
11403
+ // which `lib/conformity.ts` would refuse.
11404
+ //
11405
+ // It posts to a DIFFERENT endpoint from the persist step beside it:
11406
+ // `pulls/{n}/comments` opens a review thread, `issues/{n}/comments` does
11407
+ // not, and only the former is a thing `required_conversation_resolution`
11408
+ // can read.
11409
+ const threads = [
11410
+ `- name: ${AI_REVIEW_THREADS_STEP_NAME}`,
11411
+ ` id: ${AI_REVIEW_THREADS_STEP_ID}`,
11412
+ ` env:`,
11413
+ ` ${AI_REVIEW_FINDINGS_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.path }}`,
11414
+ // The prepare step's directory, not the changed-files step's output —
11415
+ // the writer and the reader then agree by construction rather than
11416
+ // through a step output the writer might not have reached. Same binding
11417
+ // the adjudicator takes, and restated rather than inherited because a
11418
+ // step's `env:` does not carry to a later step (#826).
11419
+ ` ${AI_REVIEW_CHANGED_FILES_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CHANGED_FILES_BASENAME}`,
11420
+ // Empty on a merge_group run, which is how the script knows there is no
11421
+ // pull request to comment on. Read from the event rather than from a
11422
+ // second `github.event_name` test, so there is one decider.
11423
+ ` ${AI_REVIEW_THREADS_PR_VAR}: \${{ github.event.pull_request.number }}`,
11424
+ // The HEAD sha, because `commit_id` anchors a review comment and a
11425
+ // comment anchored to the wrong commit is 422 or, worse, lands outdated.
11426
+ // Not `GITHUB_SHA`: on a `pull_request` event that is the merge ref, not
11427
+ // the head the diff is against.
11428
+ ` ${AI_REVIEW_THREADS_SHA_VAR}: \${{ github.event.pull_request.head.sha }}`,
11429
+ ` ${AI_REVIEW_THREADS_REPO_VAR}: \${{ github.repository }}`,
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}`,
11437
+ ` run: |`,
11438
+ ...buildThreadsScript(version).trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
11439
+ ];
11440
+
11026
11441
  // #1242. The consequence of a waiver, and LAST for that reason — see
11027
11442
  // `AI_REVIEW_DISARM_STEP_ID`. It carries no `if:`, like every other step in
11028
11443
  // this job: the waived marker is resolved inside `run:` so the step reports
@@ -11077,6 +11492,11 @@ export function buildReviewRunStep(
11077
11492
  indented(baseline, indent) +
11078
11493
  indented(review, indent) +
11079
11494
  indented(persist, indent) +
11495
+ // #1612. After the ledger and before the report, for the reason
11496
+ // `AI_REVIEW_THREADS_STEP_ID` gives: the payload exists, the adjudicator
11497
+ // has not refused yet, and a step placed after the refusal would need an
11498
+ // `if:` the conformity suite forbids.
11499
+ indented(threads, indent) +
11080
11500
  // #1307. Both BEFORE the report step — see `stageExecution` for why the
11081
11501
  // obvious ordering is not available.
11082
11502
  indented(stageExecution, indent) +
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.6",
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": {
@@ -30,6 +30,7 @@
30
30
  "scripts/create-success.ts",
31
31
  "scripts/create-sc.ts",
32
32
  "scripts/ai-review-findings.ts",
33
+ "scripts/ai-review-threads.ts",
33
34
  "scripts/record-ai-review-unmeasured.ts",
34
35
  "scripts/arbitrate-finding.ts",
35
36
  "scripts/split-spec.ts",