@thegpvc/gp-foundry 0.1.2 → 0.2.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thegpvc/gp-foundry",
3
- "version": "0.1.2",
3
+ "version": "0.2.0",
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",
@@ -4,9 +4,11 @@ emoji: "🔧"
4
4
  type: pr-fix
5
5
  mission: Address the Reviewer's requested changes on the PR branch and push a fix.
6
6
  accountable_for: [addresses every requested change, the project's tests pass, stays in scope]
7
- handoffs:
7
+ handoffs: # MUST equal this node's out-edges in harness.dot
8
8
  - to: reviewer
9
9
  when: fix pushed
10
+ - to: needs_human
11
+ when: attempts>=3
10
12
  tools: "Read,Write,Edit,Glob,Grep,Bash(make:*),Bash(npm:*),Bash(npx:*),Bash(python3:*),Bash(pytest:*),Bash(go:*),Bash(git:*),Bash(gh:*)"
11
13
  quality_bar: every requested change addressed; the checks pass; do not touch .github/.
12
14
  ---
@@ -23,4 +25,8 @@ your context.
23
25
  5. Post a short comment per the communication guide (`## 🔧 Fixer`) noting what you changed,
24
26
  point-by-point against the review. If a requested change was already satisfied, say so plainly.
25
27
 
28
+ If you've run out of attempts, the workflow labels the PR `needs-human` and stops looping — say
29
+ plainly in your comment what's left and why you couldn't finish it, so the human picking it up
30
+ starts where you stopped.
31
+
26
32
  Do not modify anything under `.github/`.
@@ -78,6 +78,11 @@
78
78
  "type": "string",
79
79
  "description": "Name of the Actions secret holding the agent OAuth token."
80
80
  },
81
+ "secrets": {
82
+ "type": "array",
83
+ "items": { "type": "string", "minLength": 1 },
84
+ "description": "Names of additional Actions secrets exposed in EVERY agent's environment (e.g. [\"SENTRY_PAT\"]). The compiler passes each into the run-agent step as extra-env `NAME=${{ secrets.NAME }}`, and roles read them as $NAME. This broadens each secret's blast radius to every agent lane (which ingest untrusted issue/PR text), so grant least-privilege tokens."
85
+ },
81
86
  "conventions": {
82
87
  "type": "string",
83
88
  "description": "Optional free-text repo conventions surfaced to every agent (e.g. commit style, stack notes)."
package/skill/SKILL.md CHANGED
@@ -89,8 +89,13 @@ Listen for:
89
89
  - **Approvals** → a `merge-gate` node (automated policy: approval delay, CI green, size
90
90
  limit, protected paths) and/or a `human-gate` node bound to a GitHub **Environment**
91
91
  (brand sign-off, production deploy). If there is any irreversible/brand/deploy step,
92
- a `human-gate` is mandatory — it is a first-class node for exactly this reason.
93
- - **Invariants** → `scope.yaml`'s `immutable_paths` (CI-enforced, agents can never modify —
92
+ a `human-gate` is mandatory — it is a first-class node for exactly this reason. Give it an
93
+ out-edge to the merge gate (`human_gate -> merge_gate`): that is what turns the Environment
94
+ approval into a check the merge requires on that exact commit, instead of a lane running
95
+ beside the gate. Also confirm `identity.bot_login` — verdict guards and the merge gate use
96
+ it to tell the reviewer's approval from a stranger's.
97
+ - **Invariants** → `scope.yaml`'s `immutable_paths` (enforced three ways by the generated
98
+ output: a PR guard workflow, the pre-push strip, and the merge gate; agents can never modify —
94
99
  e.g. `.github/workflows/`) and `forbidden_paths`/`forbidden_operations` (prompt-enforced).
95
100
  Push hard here; unstated invariants are how autonomous fleets cause damage.
96
101
 
@@ -18,7 +18,7 @@ the **role** is the behavioral identity (a `roles/<name>.md` file, open set, run
18
18
  | `pr-fix` | reads review feedback, pushes fixes to the PR branch; bounded by `max_attempts` | `contents: write` + PR write | pr-review | **yes** |
19
19
  | `scheduled-agent` | a maintenance agent on `schedule=` cron + manual dispatch, NO triggering issue/PR — it gathers its own work via `gh` (janitor rebase sweep, supervisor re-drive, retro learning) and its commits push to the base branch | `contents: write` + issues/PR write + `actions: write` | none | **yes** |
20
20
  | `merge-gate` | evaluates merge policy (approval delay, CI green, size, protected paths, clean rebase) → merge / skip / label | `contents: write` + PR write | none | no (merges) |
21
- | `human-gate` | pauses for a human via a GitHub **Environment** approval (brand/deploy sign-off) | per environment | none | no |
21
+ | `human-gate` | pauses for a human via a GitHub **Environment** approval (brand/deploy sign-off), then publishes that approval as a check-run on the PR head SHA, written with `GITHUB_TOKEN` so the merge gate can pin its author | `checks: write` | none | no |
22
22
  | `parallel` | fork bar of a **clean diamond**: exactly one in-edge (carrying the trigger), ≥2 bare out-edges to agent legs. Virtual — the whole diamond compiles into the fan_in's single workflow | none (virtual) | — | no |
23
23
  | `fan_in` | join of the diamond: compiles to ONE workflow with each leg as a job plus this node `needs:`-joined after them (native Actions join — no polling, no markers). Role synthesizes the lanes' comments (e.g. THE verdict); optional `on_complete_label=` cascades a label. Lane roles must post ANALYSES, never `**Verdict:**` (validator warns) | `contents: read` + PR/issues write | pr-review / issue | no |
24
24
 
@@ -40,8 +40,9 @@ Rules of thumb:
40
40
  | `on_complete_label=` | fan_in | label applied on join completion (resolves via config.labels) |
41
41
  | `context=` | agent types | `issue` \| `pr-diff` \| `pr-review` \| `codebase` \| `none` |
42
42
  | `output=` | `analyst` | `comment` \| `doc:<path-glob>` (docs-only write allowlist) |
43
- | `gates="ci.yml,..."` | `pr-review` | named check workflows the review depends on |
44
- | `max_attempts=N` | `pr-fix` | loop bound; pairs with an `attempts>=N` escape edge |
43
+ | `gates="ci.yml,..."` | `pr-review` | named check workflows the review depends on; each conclusion is put in front of the reviewer, and the job timeout grows to cover the waits |
44
+ | `max_attempts=N` | `pr-fix` | loop bound; pairs with an `attempts>=N` escape edge. Counted from the reviewer's submitted request-changes reviews, which cannot be deleted |
45
+ | `paths="memory/"` | `scheduled-agent` | optional allowlist of prefixes this lane may write; anything else is reverted before the push |
45
46
  | `policy="policy/merge.yaml"` | `merge-gate` | merge-policy file |
46
47
  | `schedule="*/30 * * * *"` | `merge-gate`, sweeps | cron cadence |
47
48
  | `environment=NAME` | `human-gate` | GitHub Environment gating approval (**required** on human-gate) |
@@ -72,6 +73,13 @@ conclusions, schedules) — because GitHub is the executor, not a custom engine.
72
73
  - **Handoff parity:** a role's `handoffs` front-matter == that node's out-edges (both directions).
73
74
  - **human-gate has an environment;** analyst nodes are `contents: read`; `output=doc:<glob>`
74
75
  means the only committed paths match `<glob>`.
76
+ - **Point a human-gate at the merge gate (`human_gate -> merge_gate`) if approval must
77
+ actually block the merge.** The gate publishes `gp-foundry/human-approval (<env>)` on the
78
+ head SHA and the compiler makes the merge gate require that exact check **pinned to the
79
+ app that wrote it** (`…@github-actions`), so an approval binds to the commit it approved
80
+ and cannot be forged by a lane holding the harness token — push again and the merge waits
81
+ for a new one. A human-gate that leads nowhere still pauses its own lane, but nothing
82
+ downstream depends on it.
75
83
 
76
84
  ## Reference example (the `starter` harness)
77
85
 
@@ -9,6 +9,9 @@ auth: # how the harness authenticates to GitHub for writes
9
9
  # pat — a fine-grained PAT in a repo secret: events cascade, one secret,
10
10
  # no App to install. Easiest; the default. Scope the PAT to this
11
11
  # repo with Contents + Pull requests + Issues + Actions read/write.
12
+ # (It needs nothing for CI: reading check-runs takes the Checks
13
+ # permission, which fine-grained PATs cannot be granted at all, so
14
+ # the merge gate reads that with the built-in GITHUB_TOKEN.)
12
15
  # app — GitHub App token: clean bot identity, cascades. Best for orgs.
13
16
  # (set app_id_secret / app_key_secret instead of token_secret)
14
17
  # github-token — the built-in GITHUB_TOKEN: zero setup BUT its commits/PRs never
@@ -10,6 +10,20 @@ branch_prefix: "agent/"
10
10
  # Approval — the Reviewer posts its verdict in a review BODY; count a body matching
11
11
  # this regex as approval (a bot can't formally APPROVE its own PR).
12
12
  approval_body_regex: "Verdict.*APPROVE"
13
+ # WHO may approve. An approval is an instruction to push to the base branch, so the
14
+ # gate only counts verdicts it can attribute: the reviewer bot itself (bot_login —
15
+ # the compiler passes identity.bot_login for you), or a review from someone with
16
+ # write access. Reviews are bound to the head SHA: approve, push, and the approval
17
+ # stops counting. Plain issue comments are NOT an approval channel unless you turn
18
+ # them on below — anyone who can comment could type the verdict string, and a comment
19
+ # carries no SHA to bind to.
20
+ trusted_author_associations: [OWNER, MEMBER, COLLABORATOR]
21
+ allow_comment_approvals: false
22
+ # Checks that must be PRESENT and green on the head SHA (not just green if they ran).
23
+ # A human-gate node's approval check goes here — `gp-foundry build` wires it in.
24
+ # An entry may pin the author as "<name>@<app-slug>": a check-run's name is public,
25
+ # so anything that can write checks could otherwise publish its own "approval".
26
+ required_checks: []
13
27
  # A matching body INVALIDATES earlier approvals (latest verdict wins). Keep it anchored
14
28
  # to the verdict line — a bare substring would misread approvals that mention the
15
29
  # earlier requested changes in prose.
@@ -1,6 +1,10 @@
1
1
  # scope.yaml — the invariants from interview Q2. Canonical, CI-enforced.
2
- # immutable_paths: agents can NEVER modify these; a CI check fails the PR and
3
- # agent-fallback strips any such edits before pushing. This is the hard safety boundary.
2
+ # immutable_paths: agents can NEVER modify these. Three things enforce it, and
3
+ # `gp-foundry build` wires up all three: the generated immutable-guard.yml fails
4
+ # any agent-branch PR whose diff touches one, agent-fallback strips such edits
5
+ # before a lane pushes (including the scheduled lanes that commit straight to the
6
+ # base branch), and the merge gate holds back a PR that reaches it anyway. This
7
+ # is the hard safety boundary.
4
8
  # forbidden_paths / forbidden_operations: prompt-enforced (softer); an improve/gardener lane
5
9
  # may adjust these, but never immutable_paths.
6
10