@thegpvc/gp-foundry 0.2.11 → 0.2.13

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thegpvc/gp-foundry",
3
- "version": "0.2.11",
3
+ "version": "0.2.13",
4
4
  "description": "Compile a directed-graph spec (harness.dot) into an autonomous GitHub Actions agent harness.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -45,10 +45,15 @@ outcome for an attribute meant to *restrict* a lane.
45
45
  | `on_complete_label=` | fan_in | label applied on join completion (resolves via config.labels) |
46
46
  | `context=` | agent types | `issue` \| `pr-diff` \| `pr-review` \| `codebase` \| `none` |
47
47
  | `output=` | `analyst` | `comment` \| `doc:<path-glob>` (docs-only write allowlist) |
48
- | `gates="ci.yml, lint / eslint, e2e?90"` | `pr-review` | the CI the review depends on; each conclusion is put in front of the reviewer, and the job timeout grows to cover the waits. An entry ending in `.yml`/`.yaml` waits on that **workflow**; any other entry is a **check-run name** — the way to gate on one job of a larger workflow, or on a check Actions did not produce (external CI, a status app). Check-runs are read with `GITHUB_TOKEN` (the job gains `checks: read`), since a fine-grained PAT cannot hold the Checks permission. A trailing `?N` is the grace, in seconds, to wait for the target to *appear* before concluding `skipped` (default 90) — raise it for a slow-starting check, lower it for one that only runs on some heads. Names cannot contain a comma |
48
+ | `title="Fletch"` | any job-emitting type | the workflow's `name:`, so a PR check reads `Fletch / reviewer` instead of `reviewer / reviewer`. Guard, select and mark jobs follow (`Fletch / reviewer guard`). Defaults to the node id (the older spelling `name=` still works). Changing it renames the check — update any branch-protection rule that names it |
49
+ | `harness_ref="head"` | `pr-review`, `pr-fix`, PR-context `analyst`, `fan_in` | opt **out** of the default. By default every lane handed a pull request reads its harness files — role, prompt, `scope.yaml`, `communication.md`, the `agent-setup` composite, and in vendored mode the runtime actions — from the PR's **base ref**, via a second sparse checkout into `.gp-foundry/harness/` (git-excluded, so a lane that commits never sweeps it in). The PR head stays the working tree. Read from the head, a branch cut before the harness merged has no role file, and a PR that edits `.github/agents/` is judged by its own edit, by an agent holding secrets. `"head"` restores the old behaviour for testing a harness change in its own PR; the validator warns |
50
+ | `persist_credentials=true\|false` | `analyst`, `issue-agent`, `pr-review`, `fan_in` | whether the checkout leaves its token in `.git/config`. Default **false** on these read-and-advise lanes (they never push, and an agent with a shell can read it there) — except with `checkout="partial"`, whose on-demand blob fetches need it. `false` together with `checkout="partial"` is a build error. Lanes that push always keep it |
51
+ | `repo_guides=false` | agent types | stop the CLI auto-loading the repo's own `CLAUDE.md` / `AGENTS.md` into every turn (run-agent passes `--settings` with `claudeMdExcludes` for the workspace). The role, conventions and scope are then the agent's whole standing brief. Worth it when the repo guide is large: it is paid for on every turn |
52
+ | `gates="ci.yml, lint / eslint, e2e?90"` | `pr-review` | the CI the review depends on; each conclusion is put in front of the reviewer, and the job timeout grows to cover the waits. An entry ending in `.yml`/`.yaml` waits on that **workflow**; any other entry is a **check-run name** — the way to gate on one job of a larger workflow, or on a check Actions did not produce (external CI, a status app). Check-runs are read with `GITHUB_TOKEN` (the job gains `checks: read`), since a fine-grained PAT cannot hold the Checks permission. Options follow the name, each introduced by `?`: `?N` is the grace, in seconds, to wait for the target to *appear* before concluding `skipped` (default 90) — raise it for a slow-starting check, lower it for one that only runs on some heads; `?info` marks the gate **advisory** (a review bot, say): its result is listed for the reviewer under "Informational checks", where `skipped` is normal and a `failure` is input to weigh, instead of under the rule that anything but `success` blocks. They combine: `bugbot?info?30`. Names cannot contain a comma or `?` |
49
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. Needs `identity.bot_login`. Every guard read fails **open** — an unreadable PR is reviewed, never silently skipped. Not available on diamond legs or sweep lanes |
50
54
  | `authors="dpup, octocat"` | `pr-review`, `pr-fix`, PR-context `analyst` | 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` |
51
- | `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, **and** no review by `identity.bot_login` carrying `**Verdict:**` exists on that exact head SHA, **and** the lane has not already run there. That last condition is the sweep's own record: after the lane succeeds on a head, a `<node>_mark` job publishes the check-run `gp-foundry/swept (<node>)` on it (neutral, written with `GITHUB_TOKEN`), so a role that posts nothing — a shadow run, an abstention — is not handed the same head again every tick. A lane that fails leaves the head unmarked and is retried. Oldest first, at most 10 per tick; 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"` |
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), 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 review by `identity.bot_login` carrying `**Verdict:**` exists on that exact head SHA, **and** the lane has not already run there. That last condition is the sweep's own record: after the lane succeeds on a head, a `<node>_mark` job publishes the check-run `gp-foundry/swept (<node>)` on it (neutral, written with `GITHUB_TOKEN`), so a role that posts nothing — a shadow run, an abstention — is not handed the same head again 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. Oldest first, at most 10 per tick; 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"` |
52
57
  | `cancel_in_progress=true\|false` | agent types | whether a newer event for the same issue/PR **cancels** the run in flight rather than queueing behind it. Default `false` (`true` for `issue-agent`). Good for a reviewer — a review of a superseded head is waste. On a lane that writes code (producer, pr-fix, committing scheduled-agent) the validator warns: cancellation skips the commit/push salvage, so unpushed work is lost |
53
58
  | `checkout="partial"` | any node that checks out | a blob-less clone with full history (`fetch-depth: 0` + `filter: blob:none`): every commit and tree, file contents on demand. `git log`, `git blame` and merge-base diffs work as in a full clone without paying for every version of every file — for big repos where the reviewer needs history |
54
59
  | `max_attempts=N` | `pr-fix` | fix↔review **loop** bound; pairs with an `attempts>=N` escape edge. Counted from the reviewer's submitted request-changes reviews, which cannot be deleted. Unrelated to `agent_attempts=` below — this counts trips round the loop, that counts CLI invocations within one run |
@@ -62,6 +67,22 @@ outcome for an attribute meant to *restrict* a lane.
62
67
  | `schedule="*/30 * * * *"` | `merge-gate`, sweeps | cron cadence |
63
68
  | `environment=NAME` | `human-gate` | GitHub Environment gating approval (**required** on human-gate) |
64
69
 
70
+ ### What each lane's credentials can do
71
+
72
+ - **App token (`auth.mode: app`)** is minted per job with `permission-*` inputs, so it carries
73
+ only what the lane's type needs instead of everything the App was installed with:
74
+ PR-context `analyst` / `pr-review` → `contents: read`, `pull-requests: write`, `checks: read`;
75
+ issue lanes → `contents: read`, `issues: write`; `pr-fix` → `contents: write`,
76
+ `pull-requests: write`, `checks: read`; `producer` → `contents: write`, `pull-requests: write`,
77
+ `issues: write`. A node's `permissions=` attr adds to it (App permissions only). The App must
78
+ actually hold what is requested — in particular **Checks: read** for PR lanes — or the mint
79
+ fails. `scheduled-agent` and `merge-gate` are left on the App's full permissions: their needs
80
+ are open-ended (re-running workflows, merging a PR that touches workflows).
81
+ - **The agent is handed a GitHub token only if its role can use one.** When the role's `tools:`
82
+ allow neither `gh` (`Bash(gh …)`) nor unrestricted `Bash`, `github-token` is not passed to
83
+ run-agent at all. This is the one place a role edit needs a rebuild: give a role `gh` and
84
+ `gp-foundry build --check` reports the drift.
85
+
65
86
  ## Edges — `a -> b [on=..., when=...]`
66
87
 
67
88
  - `on="<event>"` — the GitHub event that fires `b`'s workflow. Well-known events: