@thegpvc/gp-foundry 0.3.1 → 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
@@ -110,6 +110,22 @@ inputs:
110
110
  can publish one this gate — or a ruleset pinned to the App — accepts.
111
111
  required: false
112
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: ""
113
129
  check-name:
114
130
  description: "With `merge`, or mode evaluate: the check run to publish on each head (required there)."
115
131
  required: false