@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.
- package/actions/merge-gate/README.md +49 -1
- package/actions/merge-gate/action.yml +20 -2
- package/actions/merge-gate/dist/index.cjs +87 -69
- package/actions/pr-scope/action.yml +11 -2
- package/actions/pr-scope/dist/index.cjs +29 -16
- package/dist/cli/index.cjs +90 -90
- package/package.json +1 -1
- package/skill/reference/node-types.md +2 -2
- package/skill/templates/policy-merge.yaml +7 -0
package/package.json
CHANGED
|
@@ -53,7 +53,7 @@ outcome for an attribute meant to *restrict* a lane.
|
|
|
53
53
|
| `skip="draft,bot-author,label:<key>,unchanged-diff"` | `pr-review` / PR-context `analyst` | PRs this lane does **not** review. Compiles to a `<node>_guard` job (read-only, no agent, no checkout) the lane's job is `needs:`-chained behind. `draft` — a draft PR (the lane also listens for `ready_for_review`, so it runs the moment the draft is marked ready). `bot-author` — opened by a bot (dependabot, renovate…); the harness's own `identity.bot_login` is exempt. `label:<key>` — carries the label `labels.<key>` resolves to (re-evaluated on the next event, not when the label is removed). `unchanged-diff` — a **push** whose merge-base diff hashes the same as the one this bot last reviewed, i.e. a rebase or a merge from base that left the change itself untouched; the workflow stamps the hash into the review as `<!-- gp-foundry:diff:<node>:<sha256> -->` after the agent posts it. The stamp only ever lands on a review **this run** posted (submitted after the `<node>_guard` job ran, its `started_at` output): another lane posting as the same bot — an approver's verdict on the same head, when a label event re-runs the reviewer — is not this lane's review, and the guard would otherwise compare against and mark it. The stamp and the also-head marker are HTML comments, which every verdict test ignores, so a stamped verdict is still a verdict. When the guard skips a push this way, it appends `<!-- gp-foundry:also-head:<node>:<new head sha> -->` to that review (one per skipped head, appended after any existing markers, with the same token as the stamp; under App auth the guard mints one scoped to pull requests, under `github-token` auth the guard gets `pull-requests: write`), so the review is on record as covering the new head too — a downstream lane cannot tell that from a `skipped` reviewer check, which the guard also produces for labels, drafts, bot authors and unreadable PRs. The guard skips only once that marker is on the review (already there, or the edit succeeded): a `requires_review=true` sweep selects a head only on a review that covers it, so if reading or editing the review fails, the guard prints a notice and the lane runs again rather than leave the head unreviewed. Needs `identity.bot_login`. Every guard read fails **open** — an unreadable PR is reviewed, never silently skipped. Not available on diamond legs. On a sweep lane (`select="sweep"`) the select job applies `bot-author` and `label:<key>` to the PRs it picks (`draft` is implicit there); `unchanged-diff` is rejected. An evaluate-mode `merge-gate` applies them the same way to the PRs it publishes a check on |
|
|
54
54
|
| `authors="dpup, octocat"` | `pr-review`, `pr-fix`, PR-context `analyst`, evaluate-mode `merge-gate` | an allowlist: the lane runs only on pull requests **opened by** these logins (case-insensitive). Enforced twice — as a job-level `if:` on the event payload, so no runner is spent on anyone else's PR, and again in the `<node>_guard` job against the live PR, where it **fails closed** (an author that cannot be verified is skipped; every other guard check fails open). A sweep applies the same filter in its select job. Set `repo.authors: [dpup]` in `foundry.config.yaml` to bind every PR lane (and review panels) at once; the node attribute overrides it for that lane. Without either, a PR lane runs on every PR whose branch matches `repo.branch_prefix` |
|
|
55
55
|
| `opt_in_label="<key>"` | wherever `authors=` binds | widens the allowlist: the lane also runs on a PR that carries this label, whoever opened it (`authors=` ∪ label). The key resolves through `labels.<key>` in `foundry.config.yaml`, like `skip="label:<key>"` (used literally when unmapped). Compiles to an OR in the job-level `if:`, a `pull_request.labeled` trigger that admits only this label's event (other label events on an allowlisted PR do not start a run; the run GitHub still creates for them gets its own `<node>-noop-<run id>` concurrency group, so it cannot cancel or displace a review of that PR, while the opt-in label's own event joins the PR's group like a push), and the same OR in the `<node>_guard` job's fail-closed author check against the live PR (`OPT_IN_LABEL` env) and in a sweep's select job. `repo.branch_prefix` still applies. A fixer gets the `if:` widening but no `labeled` trigger. Needs an allowlist (`authors=` or `repo.authors`); without one `validate` errors (`node.opt-in-without-authors`) |
|
|
56
|
-
| `select="sweep"` | `pr-review` (with `schedule=`) | the **approver** pattern: instead of reacting to one PR's event, the lane runs on its cron and a `<node>_select` job deterministically picks the heads ready for a decision, then fans the lane out over them as a matrix. A head is selected when the PR is open, not a draft, on a `repo.branch_prefix` branch, **and** no review request is outstanding, **and** every check-run on the head is completed with no commit status pending (a head with **no** check-run at all waits until the PR has been quiet for 10 minutes, so a decision is never made in the gap before CI registers), **and** no verdict review by `identity.bot_login` exists on that exact head SHA, **and** the lane has not already delivered there. A **verdict** is a review whose last line, as a reader sees it, is **exactly** one of `**Verdict:** APPROVE`, `**Verdict:** REQUEST_CHANGES` or `**Verdict:** ESCALATE`: HTML comments are ignored (the harness appends its own after the verdict — the unchanged-diff stamp, the also-head marker), as are blank lines and leading or trailing whitespace. The marker anywhere else in the body (quoted, mid-sentence) does not count, and neither does a qualified line such as `**Verdict:** APPROVE (once gates pass)` — the merge gate would never read that as an approval, so a sweep that counted it as decided would leave the head stuck. The three words are `verdicts: [APPROVE, REQUEST_CHANGES, ESCALATE]` in `foundry.config.yaml` (approve, request changes, escalate, in that order); the select and mark jobs read them as `VERDICT_LINES`, and both merge-gate modes get them as the `verdicts` input and derive their markers from them (approval and escalation exact; rejection deliberately loose, `Verdict.*<word>`, since a missed rejection would let an earlier approval stand), so the sweep and the gate cannot disagree about what a verdict is. The merge gate reads review bodies the same way. Check-runs are read with `filter=all`, so every run counts, not just the newest per name. That last condition is the sweep's own record: after the lane succeeds on a head **and** the bot's verdict is on it, a `<node>_mark` job publishes the check-run `gp-foundry/swept (<node>)` on it (neutral, written with `GITHUB_TOKEN`). A successful run that posts **no** verdict is a holding state, not a decision: the role may have had nothing to decide yet (the head moved, a check was still running), so the head is not marked and not counted as a failure, and the next tick sweeps it again — up to **3** such runs per head. Each is recorded as a neutral `gp-foundry/sweep-idle (<node>)` check-run; on the third the mark job also publishes `gp-foundry/sweep-failed (<node>)` ("gave up after 3 runs without a verdict"), where a failed head shows, and the sweep stops selecting that head until a new commit is pushed, so a role that never posts a verdict (a shadow run, an abstention, a verdict in a shape the rule above does not recognize) costs three runs, not one every tick. A lane that fails leaves the head unmarked and is retried — up to **3** failed runs per head: each one is recorded as a neutral `gp-foundry/sweep-failed (<node>)` check-run, and after the third the sweep stops selecting that head until a new commit is pushed. A cancelled run is not counted.
|
|
56
|
+
| `select="sweep"` | `pr-review` (with `schedule=`) | the **approver** pattern: instead of reacting to one PR's event, the lane runs on its cron and a `<node>_select` job deterministically picks the heads ready for a decision, then fans the lane out over them as a matrix. A head is selected when the PR is open, not a draft, on a `repo.branch_prefix` branch, **and** no review request is outstanding, **and** every check-run on the head is completed with no commit status pending (a head with **no** check-run at all waits until the PR has been quiet for 10 minutes, so a decision is never made in the gap before CI registers), **and** no verdict review by `identity.bot_login` exists on that exact head SHA, **and** the lane has not already delivered there. A **verdict** is a review whose last line, as a reader sees it, is **exactly** one of `**Verdict:** APPROVE`, `**Verdict:** REQUEST_CHANGES` or `**Verdict:** ESCALATE`: HTML comments are ignored (the harness appends its own after the verdict — the unchanged-diff stamp, the also-head marker), as are blank lines and leading or trailing whitespace. The marker anywhere else in the body (quoted, mid-sentence) does not count, and neither does a qualified line such as `**Verdict:** APPROVE (once gates pass)` — the merge gate would never read that as an approval, so a sweep that counted it as decided would leave the head stuck. The three words are `verdicts: [APPROVE, REQUEST_CHANGES, ESCALATE]` in `foundry.config.yaml` (approve, request changes, escalate, in that order); the select and mark jobs read them as `VERDICT_LINES`, and both merge-gate modes get them as the `verdicts` input and derive their markers from them (approval and escalation exact; rejection deliberately loose, `Verdict.*<word>`, since a missed rejection would let an earlier approval stand), so the sweep and the gate cannot disagree about what a verdict is. The merge gate reads review bodies the same way. Check-runs are read with `filter=all`, so every run counts, not just the newest per name. That last condition is the sweep's own record: after the lane succeeds on a head **and** the bot's verdict is on it, a `<node>_mark` job publishes the check-run `gp-foundry/swept (<node>)` on it (neutral, written with `GITHUB_TOKEN`). A successful run that posts **no** verdict is a holding state, not a decision: the role may have had nothing to decide yet (the head moved, a check was still running), so the head is not marked and not counted as a failure, and the next tick sweeps it again — up to **3** such runs per head. Each is recorded as a neutral `gp-foundry/sweep-idle (<node>)` check-run; on the third the mark job also publishes `gp-foundry/sweep-failed (<node>)` ("gave up after 3 runs without a verdict"), where a failed head shows, and the sweep stops selecting that head until a new commit is pushed, so a role that never posts a verdict (a shadow run, an abstention, a verdict in a shape the rule above does not recognize) costs three runs, not one every tick. A lane that fails leaves the head unmarked and is retried — up to **3** failed runs per head: each one is recorded as a neutral `gp-foundry/sweep-failed (<node>)` check-run, and after the third the sweep stops selecting that head until a new commit is pushed. A cancelled run is not counted. With `requires_review=true` in a hybrid harness, candidates come from one search for open PRs the bot has reviewed, not a walk of every open PR. Candidates are taken **round-robin by author** — each author's oldest PR, then each author's next, longest-waiting author first — at most 10 per tick, so one author's flood of PRs cannot take every slot; a head whose state cannot be read is left for the next tick. "Concluded" is not "green" — a failed check is an answer the role must weigh — and a head with no checks at all counts as concluded. The lanes ahead of a sweep must post analyses, never `**Verdict:**`: the first verdict on a head is the decision. Requires `context="pr-diff"` or `"pr-review"` |
|
|
57
57
|
| `requires_review=true` | `select="sweep"` lanes | a head is a candidate only once a review by `identity.bot_login` covers it — submitted on the head (`commit_id`), or carrying the `<!-- gp-foundry:also-head:<node>:<head sha> -->` marker a guard adds when it skips that head as an unchanged diff — and that review is not itself a verdict (its last non-empty line does not start with `**Verdict:**`). For a sweep that acts on an upstream review: without it the lane starts a paid agent run on every tick for heads that are only waiting for that review. Checked in the select job's single reviews read (`REQUIRES_REVIEW` env); `validate` rejects it anywhere but a sweep |
|
|
58
58
|
| `post="review"` | `pr-review`, PR-context `analyst` (sweeps too) | the agent **prints** its review and a compiled `Post the review` step posts it with the lane's token; `run-agent` is given **no** `github-token`, whatever the role's `tools:` say (`validate` warns, `node.post-review-gh-tools`, when the role still lists gh: the post step posts; drop gh from tools). A shell under `--permission-mode dontAsk` denies the quoting a real review body needs (backticks, escaped quotes in a heredoc or `-f body=`), and an agent reading untrusted PR text should not hold a token anyway. **Output contract** (also appended to the prompt as its last section, `## Output`): the final message ends with one fenced code block tagged `json` holding one object, `{"body": "<markdown>", "comments": [{"path": "...", "line": N, "side": "RIGHT", "body": "..."}], "event": "COMMENT"}`. `comments` is optional (`[]` for none); `event` must be `COMMENT`; `commit_id` is set by the step to the head, never by the agent. The step takes the **last** such block from run-agent's captured stdout (`stdout-file` output), validates it (object, string `body`, each comment a string `path`, positive integer `line` and string `body`), prepends the heading line `PR #<n> head <sha>` (`post_marker=`) and POSTs `pulls/{n}/reviews`. With no fenced block it falls back to a bare object at the end of the output (the last line ending in `}`, back to the latest line beginning with `{` from which the rest parses as one object with a string `body`); a fenced block always wins. No review in either form, or a malformed one: nothing is posted and the step warns with the first 200 characters of the output. A 422 for an inline comment off the diff (GitHub does not say which): one retry with every inline finding moved into the body under "Findings on unchanged lines" (before the verdict line on a verdict lane). The step adds one line to the job summary under the agent's output: a link to the posted review, or a plain statement that nothing was posted and why. Idempotent, keyed on the lane: every review the step posts ends with a hidden marker, `<!-- gp-foundry:posted:<node>:<head sha> -->`, and a review by `identity.bot_login` on the head carrying this node's marker means the step posts nothing. So lanes can share a bot login and a heading — a reviewer's review does not stop an approver's verdict, nor the reverse — and a reviewer that posts a verdict of its own still recognizes it on a re-run. (A review posted before the marker existed is matched the old way, by its heading; on a verdict lane only if it is itself a verdict.) The marker is an HTML comment, which every verdict test ignores. On a sweep (`select="sweep"`) the review is the verdict: the body's last line must be one of the exact verdict lines, or nothing is posted. The diff stamp and the also-head marker work on the posted review |
|
|
59
59
|
| `post_marker="PR #<n> head <sha>"` | with `post="review"` | the heading the post step puts on the review's first line; `<n>` and `<sha>` are replaced. Single line. It is for the reader — idempotency is keyed on the hidden posted marker, so lanes posting as one bot may share a heading |
|
|
@@ -68,7 +68,7 @@ outcome for an attribute meant to *restrict* a lane.
|
|
|
68
68
|
| `timeout=N` | agent types | job `timeout-minutes` (default 35 producer/pr-fix, 20 scheduled-agent). For lanes that run an agent with a salvage epilogue (producer, pr-fix, scheduled-agent) the agent's own step cap is derived as `N − 10`: the 10-min margin lets a cold-cache toolchain setup (~7 min) run and the commit/push/open-PR salvage finish within the job cap, so an over-running agent fails its STEP (salvage still runs) instead of being job-cancelled (#12545/#12611). Raise `N` to give the agent more working time; the margin stays 10 |
|
|
69
69
|
| `agent_attempts=N` | agent types | how many times run-agent invokes the CLI when it fails **transiently** (5xx, overloaded, dropped connection); default 3, backing off 15s and doubling. A real agent error and a usage-limit wall are never retried either way. Set `1` on a lane whose role has an **unconditional** side effect — e.g. the Herald posts a Slack digest with no dedup, so a retry after a partial run would post it twice. Roles that read current state first (the Sentry sweeper's `<!-- sentry:<id> -->` marker, the Supervisor skipping prior escalations) are safe to retry. Distinct from `max_attempts=` above |
|
|
70
70
|
| `policy="policy/merge.yaml"` | `merge-gate` | merge-policy file |
|
|
71
|
-
| `merge="off\|agent-only"` | `merge-gate` | the **single gate**, for a repo where people and agents both open PRs. Every tick it judges every PR in scope against the policy and publishes the result as a check on the head (`check_name=`, default `gp-foundry/approval (<node>)`): `success` when ready, `failure` with the reason, `action_required` when escalated, `neutral` while awaiting the approver if the policy says so. `"off"` does only that. `"agent-only"` also acts on PRs the pipeline **wrote** — opened by `identity.bot_login` with every commit its own — merging them when ready and applying the policy's labels when not. A person's PR only ever gets the check, and the check says who merges. One commit by anyone else makes an agent PR human-merged. **Scope is the `rollout` block in `foundry.config.yaml`, not the branch prefix**: drafts and other bots' PRs never, the pipeline's own always, then the dial; per-node `authors=` / `opt_in_label=` / `skip=` are errors here. Under App auth the check is published with the harness's App token and only that App's runs are adopted, so another workflow's `GITHUB_TOKEN` cannot publish one that passes for it (the App needs **Checks: write**). Needs `identity.bot_login` for `"agent-only"`. A gate with neither `merge=` nor `mode=` is the original gate, unchanged: it merges approved PRs on a `repo.branch_prefix` branch and publishes no check |
|
|
71
|
+
| `merge="off\|agent-only"` | `merge-gate` | the **single gate**, for a repo where people and agents both open PRs. Every tick it judges every PR in scope against the policy and publishes the result as a check on the head (`check_name=`, default `gp-foundry/approval (<node>)`): `success` when ready, `failure` with the reason, `action_required` when escalated, `neutral` while awaiting the approver if the policy says so. `"off"` does only that. `"agent-only"` also acts on PRs the pipeline **wrote** — opened by `identity.bot_login` with every commit its own — merging them when ready and applying the policy's labels when not. A person's PR only ever gets the check, and the check says who merges. One commit by anyone else makes an agent PR human-merged. **Scope is the `rollout` block in `foundry.config.yaml`, not the branch prefix**: drafts and other bots' PRs never, the pipeline's own always, then the dial; per-node `authors=` / `opt_in_label=` / `skip=` are errors here. Under App auth the check is published with the harness's App token and only that App's runs are adopted, so another workflow's `GITHUB_TOKEN` cannot publish one that passes for it (the App needs **Checks: write**). Needs `identity.bot_login` for `"agent-only"`. It runs on events that change a PR's result — reviews (the approver's verdict among them), labels, review requests, new commits — evaluating just that PR, **and** on its schedule, for what has no event (CI finishing, threads resolved): a pass over the open PRs the bot has reviewed, found with one search, 20 per tick in a rotating window. **A head with no verdict from the approver gets no result** (a missing required check blocks; a neutral one would pass). Fork and Dependabot-triggered events are left to the pass too (they get no secrets). Optional `handoff_clauses` in the policy file make a protected path or an oversized change "a person decides" on the check, signed off by a formal approval from anyone but the harness (see the merge-gate README). A gate with neither `merge=` nor `mode=` is the original gate, unchanged: it merges approved PRs on a `repo.branch_prefix` branch and publishes no check |
|
|
72
72
|
| `mode="merge\|evaluate"` | `merge-gate` | **Older spelling, kept working; prefer `merge=`.** `merge` (default) merges the first qualifying PR or labels it. `evaluate` never merges, labels or comments: every tick it evaluates the policy for every open, non-draft PR on a `repo.branch_prefix` branch (narrowed by `authors=` / `repo.authors`, `opt_in_label=` and `skip="bot-author,label:<key>"` when set; `unchanged-diff` is rejected) and publishes one check run per head. Conclusion: `success` when the gate would merge; `action_required` when the trusted reviewer's latest verdict on the head is `**Verdict:** ESCALATE` (or the configured escalate word); `neutral` ("Awaiting the approver") instead of `failure` for a head the trusted approver has not yet approved, rejected or escalated, whatever else fails on it, when the policy sets `no_verdict_conclusion: neutral` (default `failure`), with every other failing clause listed in the summary; `failure` otherwise, with the gate's code and reason in the summary and the open threads, failing checks and pending review requests in the text. The run is updated in place (one current result per head) and not written at all when nothing changed, so a reply or resolve flips it on the next tick with no model spend, and it can be made a required check. The job runs on `GITHUB_TOKEN` alone (`checks: write`, `pull-requests: read`, `contents: read`, no App token); the gate leaves its own check out of the CI rollup, and `require_clean_rebase` is off unless the policy sets it. A graph may carry a merge gate and an evaluate gate side by side |
|
|
73
73
|
| `check_name="fletch/approval"` | `merge-gate` with `mode="evaluate"` | the check run it publishes; default `gp-foundry/approval (<node>)`. Two evaluate gates may not share one (`node.duplicate-check-name`); on a merge-mode gate it is an error (`node.check-name-without-evaluate`) |
|
|
74
74
|
| `schedule="*/30 * * * *"` | `merge-gate`, sweeps | cron cadence |
|
|
@@ -104,6 +104,13 @@ labels:
|
|
|
104
104
|
# (`blocking_labels` only hold a merge back; these say who decides.)
|
|
105
105
|
# escalation_labels: [needs-human-decision]
|
|
106
106
|
#
|
|
107
|
+
# Policy handoffs (the gate's check only). These clauses mean "a person should look",
|
|
108
|
+
# not "something is broken": while one fails on its own the check is action_required.
|
|
109
|
+
# A formal approval of the head from anyone other than identity.bot_login, with
|
|
110
|
+
# GitHub's own review decision met (required approvals, code owners), signs it off and
|
|
111
|
+
# the check reports whatever else the policy says. The gate never merges on a sign-off.
|
|
112
|
+
# handoff_clauses: [protected-path, too-large]
|
|
113
|
+
#
|
|
107
114
|
# The trusted reviewer's latest verdict on the head being an escalation turns the check
|
|
108
115
|
# `action_required` (a human decides). Defaults to the exact `**Verdict:** ESCALATE`
|
|
109
116
|
# line; this key only overrides it.
|