@thegpvc/gp-foundry 0.3.0 → 0.4.0

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.
@@ -142,9 +142,57 @@ to that App alone. Anything that requires it downstream (another gate's
142
142
  `required-checks`, a ruleset) should name it pinned to the App:
143
143
  `<check name>@<app slug>`.
144
144
 
145
+ **When it runs.** The compiler wires the gate to evaluate one PR (`pr-number`) when
146
+ something that decides it changes — a review submitted or dismissed (the approver's
147
+ verdict among them), a label, a review request, a new commit, ready for review — and to
148
+ run a scheduled pass for what has no usable event: CI finishing, a thread resolved,
149
+ fork and Dependabot PRs.
150
+
151
+ The pass looks only at open PRs `bot-login` has reviewed — one search, which returns the
152
+ head SHA, author and labels in the same call — plus dependabot's when the policy runs its
153
+ lane. It evaluates a window of 20 of them per tick that advances once per schedule period
154
+ (`rotation-period-seconds`, from the clock — event runs of the same workflow do not move
155
+ it), so every candidate is reached within ⌈candidates ÷ 20⌉ regular ticks, and stops
156
+ within `time-budget-seconds`. An event run evaluates only a PR into `base-branch`. If the search fails or would be truncated (over 1,000 results), the
157
+ tick evaluates nothing rather than walk every open PR.
158
+
159
+ **No result without a verdict.** A head the approver has given no verdict on gets no
160
+ check: a missing required check blocks a merge, whereas a `neutral` one would pass it
161
+ (GitHub counts `success`, `neutral` and `skipped` as passing). If a verdict is dismissed,
162
+ the result on that head goes back to in progress (a new in-progress run supersedes the
163
+ completed one). The dependabot lane needs no verdict.
164
+
165
+ **Merges.** Event runs for different PRs run in parallel, so two ready agent PRs can be
166
+ merged within seconds of each other — as GitHub's own auto-merge would. Each merge pins
167
+ the commit it evaluated; turn on "require branches to be up to date" in branch
168
+ protection if merges must be serialized against the latest base. A merge another run
169
+ already made is not reported as a rejection.
170
+
145
171
  `mode` (below) is the older interface and is unchanged; `merge` and `mode`
146
172
  cannot both be set.
147
173
 
174
+ ## Policy handoffs (`handoffClauses`)
175
+
176
+ Opt-in, and only for the check (`merge`, or mode evaluate). `handoffClauses:
177
+ [protected-path, too-large]` makes those clauses mean "a person should look":
178
+
179
+ - While a handoff clause is the only thing failing, the check is `action_required`
180
+ ("A person decides: protected-path") instead of `failure`.
181
+ - A **sign-off** clears it: a standing formal `APPROVED` review of the exact head
182
+ commit (that reviewer's latest decisive review — not dismissed, not followed by
183
+ their own change request) from anyone other than `bot-login` — a person with a
184
+ trusted association (`trustedAuthorAssociations`, by default OWNER, MEMBER,
185
+ COLLABORATOR), or another bot — with GitHub's own
186
+ review decision `APPROVED`, or empty where the branch requires no review. That
187
+ decision is how required approvals and code owners are respected. If it cannot be
188
+ read, the handoff stays outstanding and the check says why.
189
+ - A sign-off clears **only** the handoff clauses. CI, open threads, review requests,
190
+ change requests and holds still decide the result. An agent `ESCALATE` (a judgment
191
+ call) and an escalation label (an explicit hold) are never cleared by it.
192
+ - The check names who signed off and on which commit, and keeps the agent's verdict.
193
+ - Merging never reads a sign-off: with `merge: agent-only` a handoff clause still
194
+ holds the merge, and the gate posts no review of its own.
195
+
148
196
  ## Evaluate mode
149
197
 
150
198
  `mode: evaluate` never merges, labels or comments. It evaluates the policy for
@@ -219,7 +267,7 @@ one identity. A rejection counts from anyone, including the author.
219
267
  | `clean-rebase`| no | Override the rebase check with `"true"`/`"false"`; inferred from mergeable state otherwise. |
220
268
  | `checks-token` | no | Token for reading (and, in evaluate mode, writing) check runs; pass GITHUB_TOKEN. |
221
269
  | `verdicts` | no | The verdict words, approve / request changes / escalate (default `APPROVE,REQUEST_CHANGES,ESCALATE`). |
222
- | `mode` | no | `merge` (default) or `evaluate` (publish a check run per head, never merge). |
270
+ | `mode` | no | `merge` (default when `merge` is unset) or `evaluate` (publish a check run per head, never merge). Not together with `merge`. |
223
271
  | `check-name` | evaluate | The check run evaluate mode publishes. |
224
272
  | `authors`, `opt-in-label`, `skip-labels`, `skip-bot-authors` | no | Evaluate-mode PR selection (comma-separated logins / labels; `"true"`). |
225
273
  | `dry-run` | no | `"true"` to evaluate + emit outputs without mutating. |
@@ -74,13 +74,15 @@ inputs:
74
74
  default: ""
75
75
  mode:
76
76
  description: >
77
- "merge" (default): merge the first qualifying PR, or label/skip. "evaluate":
77
+ "merge": merge the first qualifying PR, or label/skip. "evaluate":
78
78
  never merge or label — evaluate every open PR in scope and publish the
79
79
  result as one check run per head (named by check-name), updated in place
80
80
  each run and left alone when nothing changed. Evaluate mode needs only
81
81
  `checks: write`, `pull-requests: read` and `contents: read` on the token.
82
+ No default here, so the action can tell whether a workflow set it: when
83
+ neither `mode` nor `merge` is given, the gate runs as "merge". Do not set
84
+ it together with `merge`.
82
85
  required: false
83
- default: "merge"
84
86
  merge:
85
87
  description: >
86
88
  The single gate. "off": judge every PR in scope and publish the result as
@@ -108,6 +110,22 @@ inputs:
108
110
  can publish one this gate — or a ruleset pinned to the App — accepts.
109
111
  required: false
110
112
  default: ""
113
+ rotation-period-seconds:
114
+ description: >
115
+ With `merge` and no `pr-number`: the schedule's period. The pass's window
116
+ of 20 PRs advances once per period, computed from the clock — not from a
117
+ run counter, which event runs of the same workflow also advance — so
118
+ successive ticks cover every candidate without stored state. The compiler
119
+ derives it from the node's cron. Default 300.
120
+ required: false
121
+ default: ""
122
+ time-budget-seconds:
123
+ description: >
124
+ With `merge` and no `pr-number` (the scheduled pass): stop starting new
125
+ evaluations after this many seconds, so the job finishes inside its own
126
+ timeout. The compiler sets it from the job's timeout.
127
+ required: false
128
+ default: ""
111
129
  check-name:
112
130
  description: "With `merge`, or mode evaluate: the check run to publish on each head (required there)."
113
131
  required: false