@thegpvc/gp-foundry 0.1.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.
Files changed (50) hide show
  1. package/AGENTS.md +89 -0
  2. package/LICENSE +21 -0
  3. package/README.md +270 -0
  4. package/actions/agent-context/README.md +67 -0
  5. package/actions/agent-context/action.yml +33 -0
  6. package/actions/agent-fallback/README.md +89 -0
  7. package/actions/agent-fallback/action.yml +204 -0
  8. package/actions/config-loader/README.md +81 -0
  9. package/actions/config-loader/action.yml +50 -0
  10. package/actions/dependency-chain/README.md +116 -0
  11. package/actions/dependency-chain/action.yml +57 -0
  12. package/actions/merge-gate/README.md +111 -0
  13. package/actions/merge-gate/action.yml +60 -0
  14. package/actions/run-agent/README.md +75 -0
  15. package/actions/run-agent/action.yml +213 -0
  16. package/actions/sanitize-untrusted-input/README.md +110 -0
  17. package/actions/sanitize-untrusted-input/action.yml +47 -0
  18. package/actions/setup-agent/README.md +51 -0
  19. package/actions/setup-agent/action.yml +100 -0
  20. package/actions/wait-for-checks/README.md +91 -0
  21. package/actions/wait-for-checks/action.yml +58 -0
  22. package/dist/cli/index.cjs +130 -0
  23. package/package.json +79 -0
  24. package/roles/README.md +124 -0
  25. package/roles/content/brand-critic.md +64 -0
  26. package/roles/content/brief-triager.md +58 -0
  27. package/roles/content/copywriter.md +55 -0
  28. package/roles/content/editor.md +51 -0
  29. package/roles/docs/reviewer.md +62 -0
  30. package/roles/docs/writer.md +54 -0
  31. package/roles/software/builder.md +28 -0
  32. package/roles/software/fixer.md +26 -0
  33. package/roles/software/janitor.md +30 -0
  34. package/roles/software/planner.md +29 -0
  35. package/roles/software/retro.md +42 -0
  36. package/roles/software/reviewer.md +27 -0
  37. package/roles/software/scout.md +30 -0
  38. package/roles/software/supervisor.md +52 -0
  39. package/schema/config.schema.json +167 -0
  40. package/skill/SKILL.md +280 -0
  41. package/skill/reference/cli.md +108 -0
  42. package/skill/reference/node-types.md +99 -0
  43. package/skill/reference/role-packs.md +95 -0
  44. package/skill/templates/agent-setup.yml +15 -0
  45. package/skill/templates/communication.md +64 -0
  46. package/skill/templates/foundry.config.yaml +49 -0
  47. package/skill/templates/harness.dot +54 -0
  48. package/skill/templates/policy-merge.yaml +54 -0
  49. package/skill/templates/role.md +33 -0
  50. package/skill/templates/scope.yaml +21 -0
@@ -0,0 +1,204 @@
1
+ name: Agent Fallback
2
+ description: Safety net — strip protected paths, commit, push, and create a PR if the agent didn't.
3
+
4
+ inputs:
5
+ branch:
6
+ description: Branch name to push.
7
+ required: true
8
+ token:
9
+ description: GitHub token used for push, PR creation, and comments.
10
+ required: true
11
+ agent-name:
12
+ description: Agent name for fallback commit messages (e.g., implement, improve, fix).
13
+ required: true
14
+ base-branch:
15
+ description: Base branch to diff against and target for the fallback PR.
16
+ default: main
17
+ scope-path:
18
+ description: >-
19
+ Path to the scope YAML file whose `immutable_paths:` list names paths the agent
20
+ must never modify. These are stripped before pushing (a restricted token cannot
21
+ push workflow changes). If the file or the key is absent, defaults to
22
+ `.github/workflows/`.
23
+ default: .github/agents/scope.yaml
24
+ commit-message:
25
+ description: Fallback commit message (if the agent left uncommitted changes).
26
+ default: ""
27
+ pr-title:
28
+ description: Fallback PR title (empty = never create a fallback PR).
29
+ default: ""
30
+ pr-body:
31
+ description: Fallback PR body.
32
+ default: ""
33
+ pr-label:
34
+ description: Label for the fallback PR.
35
+ default: ""
36
+ issue-number:
37
+ description: Issue to comment on with the PR link (and optional no-changes comment).
38
+ default: ""
39
+ no-changes-comment:
40
+ description: Comment to post on PR/issue if no changes were made (empty = skip).
41
+ default: ""
42
+ comment-target:
43
+ description: "Where to post no-changes-comment: 'pr' or 'issue'."
44
+ default: "pr"
45
+
46
+ runs:
47
+ using: composite
48
+ steps:
49
+ - name: Resolve immutable paths
50
+ id: immutable
51
+ shell: bash
52
+ env:
53
+ SCOPE_PATH: ${{ inputs.scope-path }}
54
+ run: |
55
+ # Extract the `immutable_paths:` list from the scope YAML without a YAML
56
+ # parser. We read simple `- <path>` list items that follow the
57
+ # `immutable_paths:` key, stopping at the next top-level key.
58
+ PATHS=""
59
+ if [ -f "$SCOPE_PATH" ]; then
60
+ PATHS=$(awk '
61
+ /^immutable_paths[[:space:]]*:/ { grab=1; next }
62
+ grab {
63
+ # A new top-level key (no leading whitespace, ends with ":") ends the list.
64
+ if ($0 ~ /^[^[:space:]#][^:]*:/) { grab=0; next }
65
+ # List item: " - some/path"
66
+ if ($0 ~ /^[[:space:]]*-[[:space:]]*/) {
67
+ line=$0
68
+ sub(/^[[:space:]]*-[[:space:]]*/, "", line) # drop the "- " marker
69
+ sub(/[[:space:]]*#.*$/, "", line) # drop trailing comment
70
+ gsub(/^[[:space:]]+|[[:space:]]+$/, "", line) # trim
71
+ gsub(/^["'\'']|["'\'']$/, "", line) # drop surrounding quotes
72
+ if (line != "") print line
73
+ }
74
+ }
75
+ ' "$SCOPE_PATH")
76
+ fi
77
+ if [ -z "$PATHS" ]; then
78
+ PATHS=".github/workflows/"
79
+ echo "::notice::No immutable_paths found in '$SCOPE_PATH'; defaulting to .github/workflows/"
80
+ fi
81
+ # Serialize the (possibly multi-line) list into GITHUB_OUTPUT.
82
+ {
83
+ echo "paths<<__IMMUTABLE_EOF__"
84
+ echo "$PATHS"
85
+ echo "__IMMUTABLE_EOF__"
86
+ } >> "$GITHUB_OUTPUT"
87
+
88
+ - name: Strip protected path changes
89
+ shell: bash
90
+ env:
91
+ BASE_BRANCH: ${{ inputs.base-branch }}
92
+ IMMUTABLE_PATHS: ${{ steps.immutable.outputs.paths }}
93
+ run: |
94
+ # Revert any changes to immutable paths — the restricted App token
95
+ # typically lacks permission to push them (e.g. `workflows`), so the
96
+ # push would be rejected. Strip from committed and uncommitted changes.
97
+ BASE_REF="origin/${BASE_BRANCH}"
98
+
99
+ while IFS= read -r P; do
100
+ [ -z "$P" ] && continue
101
+
102
+ # 1. Committed changes (agent may have committed via git).
103
+ CHANGED=$(git diff --name-only "${BASE_REF}...HEAD" -- "$P" 2>/dev/null || true)
104
+ if [ -n "$CHANGED" ]; then
105
+ echo "::warning::Agent committed changes to protected path '$P' — stripping"
106
+ echo "$CHANGED"
107
+ while IFS= read -r f; do
108
+ [ -z "$f" ] && continue
109
+ git checkout "$BASE_REF" -- "$f" 2>/dev/null || git rm -f "$f" 2>/dev/null || true
110
+ done <<< "$CHANGED"
111
+ fi
112
+
113
+ # 2. Uncommitted changes (working tree / staged).
114
+ git checkout -- "$P" 2>/dev/null || true
115
+ git reset -- "$P" 2>/dev/null || true
116
+ done <<< "$IMMUTABLE_PATHS"
117
+
118
+ # Fold any restorations staged above into the tip commit.
119
+ git diff --staged --quiet || git commit --amend --no-edit
120
+
121
+ - name: Commit uncommitted changes
122
+ shell: bash
123
+ env:
124
+ COMMIT_MSG: ${{ inputs.commit-message }}
125
+ AGENT_NAME: ${{ inputs.agent-name }}
126
+ run: |
127
+ if [ -n "$(git status --porcelain)" ]; then
128
+ echo "::notice::Agent left uncommitted changes, committing..."
129
+ git add -A
130
+ if [ -z "$COMMIT_MSG" ]; then
131
+ COMMIT_MSG="Agent ${AGENT_NAME}: automated changes"
132
+ fi
133
+ git commit -m "$COMMIT_MSG"
134
+ fi
135
+
136
+ - name: Check for changes
137
+ id: check
138
+ shell: bash
139
+ env:
140
+ BASE_BRANCH: ${{ inputs.base-branch }}
141
+ run: |
142
+ if [ "$(git rev-list "origin/${BASE_BRANCH}..HEAD" --count)" -eq 0 ]; then
143
+ echo "has_changes=false" >> "$GITHUB_OUTPUT"
144
+ else
145
+ echo "has_changes=true" >> "$GITHUB_OUTPUT"
146
+ fi
147
+
148
+ - name: Post no-changes comment
149
+ if: steps.check.outputs.has_changes == 'false' && inputs.no-changes-comment != ''
150
+ shell: bash
151
+ env:
152
+ GH_TOKEN: ${{ inputs.token }}
153
+ COMMENT_BODY: ${{ inputs.no-changes-comment }}
154
+ COMMENT_TARGET: ${{ inputs.comment-target }}
155
+ ISSUE_NUMBER: ${{ inputs.issue-number }}
156
+ BRANCH: ${{ inputs.branch }}
157
+ run: |
158
+ if [ "$COMMENT_TARGET" = "issue" ] && [ -n "$ISSUE_NUMBER" ]; then
159
+ gh issue comment "$ISSUE_NUMBER" --body "$COMMENT_BODY"
160
+ elif [ "$COMMENT_TARGET" = "pr" ]; then
161
+ PR_NUM=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number // empty')
162
+ if [ -n "$PR_NUM" ]; then
163
+ gh pr comment "$PR_NUM" --body "$COMMENT_BODY"
164
+ fi
165
+ fi
166
+
167
+ - name: Push branch
168
+ if: steps.check.outputs.has_changes == 'true'
169
+ shell: bash
170
+ env:
171
+ GH_TOKEN: ${{ inputs.token }}
172
+ BRANCH: ${{ inputs.branch }}
173
+ run: |
174
+ git push origin "$BRANCH"
175
+
176
+ - name: Create PR if needed
177
+ if: steps.check.outputs.has_changes == 'true' && inputs.pr-title != ''
178
+ shell: bash
179
+ env:
180
+ GH_TOKEN: ${{ inputs.token }}
181
+ PR_TITLE: ${{ inputs.pr-title }}
182
+ PR_BODY: ${{ inputs.pr-body }}
183
+ PR_LABEL: ${{ inputs.pr-label }}
184
+ BRANCH: ${{ inputs.branch }}
185
+ BASE_BRANCH: ${{ inputs.base-branch }}
186
+ AGENT_NAME: ${{ inputs.agent-name }}
187
+ ISSUE_NUMBER: ${{ inputs.issue-number }}
188
+ run: |
189
+ EXISTING_PR=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number // empty')
190
+ if [ -z "$EXISTING_PR" ]; then
191
+ echo "::notice::Agent didn't create a PR, creating fallback..."
192
+ PR_ARGS=(--title "$PR_TITLE" --base "$BASE_BRANCH" --head "$BRANCH")
193
+ if [ -n "$PR_BODY" ]; then
194
+ PR_ARGS+=(--body "$PR_BODY")
195
+ fi
196
+ if [ -n "$PR_LABEL" ]; then
197
+ PR_ARGS+=(--label "$PR_LABEL")
198
+ fi
199
+ PR_URL=$(gh pr create "${PR_ARGS[@]}")
200
+
201
+ if [ -n "$ISSUE_NUMBER" ]; then
202
+ gh issue comment "$ISSUE_NUMBER" --body "Agent ${AGENT_NAME}: PR created: ${PR_URL}"
203
+ fi
204
+ fi
@@ -0,0 +1,81 @@
1
+ # config-loader
2
+
3
+ Parse a consumer's `foundry.config.yaml`, validate it against the FoundryConfig
4
+ JSON Schema (`schema/config.schema.json`), resolve a given node/persona's
5
+ effective settings, and emit them as GitHub Actions outputs.
6
+
7
+ This action is **domain-neutral**. Nothing about any particular agent fleet is
8
+ hardcoded — the bot login, git identity, model, allowed-tools, secret names and
9
+ label names all come from the config, and can be overridden per persona.
10
+
11
+ ## Inputs
12
+
13
+ | Input | Required | Description |
14
+ | ------------- | -------- | --------------------------------------------------------------------------------------------- |
15
+ | `config-path` | yes | Path to the consumer's `foundry.config.yaml`. |
16
+ | `node` | no | Persona/role key. When set, that persona's overrides (from `personas`) shadow the top level. |
17
+
18
+ ## Outputs
19
+
20
+ | Output | Description |
21
+ | -------------------- | ----------------------------------------------------------------- |
22
+ | `name` | The harness/fleet name. |
23
+ | `model` | Effective model id for the resolved persona. |
24
+ | `cli` | Effective agent CLI binary. |
25
+ | `allowed-tools` | Effective allowed-tools as a comma-joined string. |
26
+ | `labels-json` | Effective semantic-role → label map, as a JSON object. |
27
+ | `bot-login` | Effective bot login (empty if unset). |
28
+ | `git-name` | Effective git author name (empty if unset). |
29
+ | `git-email` | Effective git author email (empty if unset). |
30
+ | `app-id-secret` | Name of the Actions secret holding the GitHub App id. |
31
+ | `app-key-secret` | Name of the Actions secret holding the GitHub App private key. |
32
+ | `oauth-token-secret` | Name of the Actions secret holding the agent OAuth token. |
33
+ | `json` | The full resolved (persona-flattened) config view as a JSON blob. |
34
+
35
+ ## Resolution semantics
36
+
37
+ Given a `node`, the matching entry in the config's `personas` map (if any) is
38
+ merged over the top-level defaults:
39
+
40
+ - `model`, `cli`, `allowed_tools` — **replaced** wholesale by the persona value
41
+ when present, else inherited.
42
+ - `labels`, `identity` — **shallow-merged** per key (persona wins per key,
43
+ everything else is inherited).
44
+
45
+ An unknown `node` (no matching persona) resolves to the top-level defaults and
46
+ emits a warning. `allowed_tools` may be authored as a comma-string or a YAML
47
+ list; either way it is normalized and emitted as a comma-joined string.
48
+
49
+ ## Example
50
+
51
+ ```yaml
52
+ - name: Load foundry config
53
+ id: cfg
54
+ uses: ./actions/config-loader
55
+ with:
56
+ config-path: foundry.config.yaml
57
+ node: reviewer
58
+
59
+ - name: Run the agent
60
+ run: |
61
+ ${{ steps.cfg.outputs.cli }} -p "$PROMPT" \
62
+ --model "${{ steps.cfg.outputs.model }}" \
63
+ --allowedTools "${{ steps.cfg.outputs.allowed-tools }}"
64
+ env:
65
+ READY_LABEL: ${{ fromJSON(steps.cfg.outputs.labels-json).ready }}
66
+ ```
67
+
68
+ ## Config shape
69
+
70
+ See [`schema/config.schema.json`](../../schema/config.schema.json) for the
71
+ authoritative contract. It mirrors `FoundryConfig` in `src/ir/types.ts`, with an
72
+ added optional `personas` map keyed by node/role for per-persona overrides.
73
+
74
+ ## Development
75
+
76
+ - Source: `src/index.ts` (bundled to `dist/index.js` later — do not hand-edit
77
+ `dist/`).
78
+ - `src/schema.ts` is an embedded copy of `schema/config.schema.json` so the
79
+ bundled action needs no filesystem access at runtime. The JSON file is
80
+ canonical; keep the embedded copy in sync.
81
+ - Tests: `test/index.test.ts` with the fixture in `test/fixtures/`.
@@ -0,0 +1,50 @@
1
+ name: "Foundry config-loader"
2
+ description: >-
3
+ Parse a consumer foundry.config.yaml, validate it against the FoundryConfig
4
+ JSON Schema, resolve a given node/persona's effective settings, and emit them
5
+ as outputs (model, allowed-tools, labels, identity fields, and a full JSON
6
+ blob). Fully domain-neutral — no hardcoded bot login, model, secret names or
7
+ labels.
8
+ author: gp-foundry
9
+
10
+ inputs:
11
+ config-path:
12
+ description: "Path to the consumer's foundry.config.yaml."
13
+ required: true
14
+ node:
15
+ description: >-
16
+ Optional persona/role key. When set, that persona's overrides (from the
17
+ config's `personas` map) shadow the top-level defaults. When omitted, the
18
+ top-level defaults are used verbatim.
19
+ required: false
20
+ default: ""
21
+
22
+ outputs:
23
+ name:
24
+ description: "The harness/fleet name."
25
+ model:
26
+ description: "Effective model id for the resolved persona."
27
+ cli:
28
+ description: "Effective agent CLI binary for the resolved persona."
29
+ allowed-tools:
30
+ description: "Effective allowed-tools as a comma-joined string."
31
+ labels-json:
32
+ description: "Effective semantic-role -> label map as a JSON object."
33
+ bot-login:
34
+ description: "Effective bot login (empty if unset)."
35
+ git-name:
36
+ description: "Effective git commit author name (empty if unset)."
37
+ git-email:
38
+ description: "Effective git commit author email (empty if unset)."
39
+ app-id-secret:
40
+ description: "Name of the Actions secret holding the GitHub App id (empty if unset)."
41
+ app-key-secret:
42
+ description: "Name of the Actions secret holding the GitHub App private key (empty if unset)."
43
+ oauth-token-secret:
44
+ description: "Name of the Actions secret holding the agent OAuth token (empty if unset)."
45
+ json:
46
+ description: "The full resolved config view (persona-flattened) as a JSON blob."
47
+
48
+ runs:
49
+ using: "node24"
50
+ main: "dist/index.cjs"
@@ -0,0 +1,116 @@
1
+ # dependency-chain
2
+
3
+ When an agent PR merges and closes a sub-issue, this action **chains** the next
4
+ step of work:
5
+
6
+ 1. **Unblock dependents.** Any open issue that declares a dependency on the
7
+ just-closed issue via a marker comment (`<!-- depends-on: #N -->`) has its
8
+ *blocked* label swapped for a *ready* label — but only once **all** of its
9
+ declared dependencies are resolved.
10
+ 2. **Close finished parents.** A sub-issue may point at a parent tracking issue
11
+ with `<!-- parent: #N -->`. When the last open sub-issue of a parent closes,
12
+ the parent is commented on and closed.
13
+
14
+ It is a generalized, testable port of gp-dixie's `agent-chain.yml`. Every
15
+ domain-specific string — labels, markers, close-keywords, comment text — is
16
+ configurable, so there are no hardcoded label names or bot identities.
17
+
18
+ ## Design
19
+
20
+ The logic lives in a **pure function**, `computeChainOps` (`src/chain.ts`), which
21
+ takes plain data (the merged PR body + a snapshot of open issues) and returns a
22
+ list of declarative operations. It performs no I/O, so it is exhaustively
23
+ unit-tested (`src/chain.test.ts`). The action entrypoint (`src/index.ts`) is a
24
+ thin Octokit adapter that fetches the snapshot, calls the pure function, and
25
+ applies the ops.
26
+
27
+ ```
28
+ merged PR body ─┐
29
+ ├─▶ computeChainOps() ─▶ [ {unblock…}, {close-parent…} ] ─▶ Octokit
30
+ open issues ───┘ (pure) (declarative ops) (index.ts)
31
+ ```
32
+
33
+ ## Inputs
34
+
35
+ | Input | Required | Default | Description |
36
+ |-------------|----------|-----------|-------------|
37
+ | `token` | yes | — | Token with `issues: write`. Prefer a GitHub App installation token so downstream label-triggered workflows fire. |
38
+ | `config` | no | `{}` | JSON object (see below). |
39
+ | `pr-body` | no | event | Merged PR body to scan. Falls back to `pr-number` (API fetch) or the `pull_request` event payload. |
40
+ | `pr-number` | no | — | PR number to fetch the body from when `pr-body` is absent. |
41
+ | `dry-run` | no | `false` | Compute + log ops without applying changes. |
42
+
43
+ ### `config` JSON
44
+
45
+ | Key | Type | Default | Meaning |
46
+ |----------------------|------------|-------------------------------|---------|
47
+ | `blockedLabel` | string | — (all open issues eligible) | Label removed on unblock; also filters candidate issues. |
48
+ | `readyLabel` | string | — (no label added) | Label added on unblock. |
49
+ | `dependsOnMarker` | string | `<!-- depends-on: #{n} -->` | Body marker template; must contain `{n}`. Whitespace is matched loosely. |
50
+ | `parentMarker` | string | `<!-- parent: #{n} -->` | Body marker template; must contain `{n}`. |
51
+ | `closeKeywords` | string[] | close/fix/resolve variants | PR-body keywords that mark an issue as closed. |
52
+ | `parentCloseComment` | string | — (close silently) | Comment posted before closing a parent; `{n}` → parent number. |
53
+
54
+ ## Outputs
55
+
56
+ | Output | Description |
57
+ |------------------|-------------|
58
+ | `closed-issues` | JSON array of issue numbers the PR closed. |
59
+ | `unblocked` | JSON array of unblocked issue numbers. |
60
+ | `closed-parents` | JSON array of closed parent issue numbers. |
61
+ | `ops` | JSON array of the full computed `ChainOp` objects. |
62
+
63
+ ## Usage
64
+
65
+ ```yaml
66
+ name: Chain
67
+ on:
68
+ pull_request:
69
+ types: [closed]
70
+
71
+ jobs:
72
+ chain:
73
+ if: >-
74
+ github.event.pull_request.merged == true
75
+ && startsWith(github.event.pull_request.head.ref, 'agent/')
76
+ runs-on: ubuntu-latest
77
+ permissions:
78
+ issues: write
79
+ steps:
80
+ # Recommended: mint a GitHub App token so downstream label workflows fire.
81
+ - uses: actions/create-github-app-token@v3
82
+ id: app-token
83
+ with:
84
+ app-id: ${{ secrets.MY_APP_ID }}
85
+ private-key: ${{ secrets.MY_APP_PRIVATE_KEY }}
86
+
87
+ - uses: ./actions/dependency-chain
88
+ with:
89
+ token: ${{ steps.app-token.outputs.token }}
90
+ config: |
91
+ {
92
+ "blockedLabel": "agent-blocked",
93
+ "readyLabel": "agent",
94
+ "parentCloseComment": "All phases are complete. Closing this tracking issue."
95
+ }
96
+ ```
97
+
98
+ ## Notes on behavior vs. the original workflow
99
+
100
+ - The original unblocked a dependent as soon as the merged PR's issue matched a
101
+ single `depends-on`. This port is stricter: a dependent is unblocked only when
102
+ **none** of its declared `depends-on` targets remain open, so an issue waiting
103
+ on two blockers is not released prematurely.
104
+ - The open-issue snapshot is taken *before* GitHub flips the merged issue's
105
+ state, so the just-closed issue(s) may still appear open. They are filtered out
106
+ by number in the pure function.
107
+ - `listForRepo` returns pull requests as well as issues; the wrapper drops PRs.
108
+
109
+ ## Development
110
+
111
+ ```bash
112
+ npx vitest run actions/dependency-chain # unit tests (pure logic)
113
+ npm run build:actions # bundle src/index.ts -> dist/index.js
114
+ ```
115
+
116
+ `dist/` is committed and drift-checked via `npm run check:dist`.
@@ -0,0 +1,57 @@
1
+ name: "Dependency Chain"
2
+ description: >-
3
+ On a merged PR, unblock dependent issues (swap a blocked→ready label when their
4
+ declared dependencies are resolved) and close parent tracking issues whose
5
+ sub-issues are all done. Markers, labels and close-keywords are configurable.
6
+ author: gp-foundry
7
+
8
+ inputs:
9
+ token:
10
+ description: >-
11
+ Token with `issues: write` used to relabel/close issues. Prefer a GitHub
12
+ App installation token so downstream label-triggered workflows fire.
13
+ required: true
14
+ config:
15
+ description: >-
16
+ JSON object configuring the chain behavior. Recognized keys:
17
+ blockedLabel label removed when a dependent is unblocked (and the
18
+ filter for candidate issues)
19
+ readyLabel label added when a dependent is unblocked
20
+ dependsOnMarker body marker template, must contain `{n}`
21
+ (default: "<!-- depends-on: #{n} -->")
22
+ parentMarker body marker template, must contain `{n}`
23
+ (default: "<!-- parent: #{n} -->")
24
+ closeKeywords array of PR-body close keywords
25
+ (default: close/fix/resolve variants)
26
+ parentCloseComment comment posted before closing a parent; `{n}` → number
27
+ required: false
28
+ default: "{}"
29
+ pr-body:
30
+ description: >-
31
+ Merged PR body to scan for close keywords. If omitted, resolved from
32
+ `pr-number` (via the API) or the triggering pull_request event payload.
33
+ required: false
34
+ default: ""
35
+ pr-number:
36
+ description: >-
37
+ PR number to fetch the body from when `pr-body` is not supplied.
38
+ required: false
39
+ default: ""
40
+ dry-run:
41
+ description: "Compute and log ops without applying any label/close changes."
42
+ required: false
43
+ default: "false"
44
+
45
+ outputs:
46
+ closed-issues:
47
+ description: "JSON array of issue numbers the merged PR closed."
48
+ unblocked:
49
+ description: "JSON array of issue numbers that were unblocked."
50
+ closed-parents:
51
+ description: "JSON array of parent issue numbers that were closed."
52
+ ops:
53
+ description: "JSON array of the full computed ChainOp objects."
54
+
55
+ runs:
56
+ using: "node24"
57
+ main: "dist/index.cjs"
@@ -0,0 +1,111 @@
1
+ # merge-gate (C7)
2
+
3
+ A GitHub Action that decides whether a single PR may be auto-merged, and — when
4
+ it may not — routes it to the right agent via a label. It is a generalized,
5
+ **testable** port of the gp-dixie "Shipper" (`agent-merger.yml`), whose merge
6
+ rules previously lived in a fragile ~200-line bash script.
7
+
8
+ The gating rules are a **pure function**, `evaluateMergeGate(pr, policy) ->
9
+ { action, code, reason, label? }`, defined in [`src/gate.ts`](./src/gate.ts) and
10
+ exhaustively unit-tested in [`src/gate.test.ts`](./src/gate.test.ts). The action
11
+ wrapper ([`src/index.ts`](./src/index.ts)) does the GitHub I/O around it: gather
12
+ facts → evaluate → merge / label / skip.
13
+
14
+ ## Gates (in order)
15
+
16
+ The gate returns the **first** failing check. Ordering is cheapest / most
17
+ disqualifying first:
18
+
19
+ 1. **Blocking labels** — PR carries any `blockingLabels` (e.g. `needs-human`,
20
+ `rebase-needed`) → `skip`.
21
+ 2. **Branch prefix** — head branch must start with `branchPrefix` (if set).
22
+ 3. **Bot-approval present** — `approvedAt` must be set (the wrapper derives it
23
+ from an `APPROVED` review, or a `COMMENTED` review whose body matches
24
+ `approvalBodyRegex`).
25
+ 4. **Approval delay** — at least `approvalDelayMinutes` must have elapsed.
26
+ 5. **CI passing** — the check-run rollup for the head SHA must be `passing`
27
+ (unless `requireCi: false`).
28
+ 6. **Hand-written additions** — additions of non-`excludeGlobs` files must be
29
+ `<= maxAdditions`, else apply `labels.needsHuman`.
30
+ 7. **Protected paths** — no changed file may match `protectedPaths`, else apply
31
+ `labels.needsHuman`.
32
+ 8. **Clean rebase** — the branch must rebase cleanly onto the base branch
33
+ (unless `requireCleanRebase: false`), else apply `labels.rebaseNeeded`.
34
+
35
+ If all pass, the action is `merge`.
36
+
37
+ Outcomes: `merge` (merge it), `label` (apply `label` and stop), `skip` (no-op).
38
+
39
+ ## Inputs
40
+
41
+ | input | required | description |
42
+ | ------------- | -------- | ----------- |
43
+ | `pr-number` | yes | PR to evaluate. |
44
+ | `token` | yes | Token with `contents:write` + `pull-requests:write` (use an App installation token so merges are attributed to the bot). |
45
+ | `policy-path` | yes | Path to the policy file (YAML or JSON). |
46
+ | `clean-rebase`| no | Override the rebase check with `"true"`/`"false"`; inferred from mergeable state otherwise. |
47
+ | `dry-run` | no | `"true"` to evaluate + emit outputs without mutating. |
48
+
49
+ ## Outputs
50
+
51
+ `action`, `code`, `reason`, `label` (when labeling), and `merged` (`"true"` if
52
+ this run merged the PR).
53
+
54
+ ## Policy file
55
+
56
+ All gp-dixie hardcodes are parameterized here. Example reproducing the original
57
+ Shipper behaviour:
58
+
59
+ ```yaml
60
+ branchPrefix: "agent/"
61
+ approvalDelayMinutes: 30
62
+ maxAdditions: 1200
63
+ excludeGlobs:
64
+ - "gen/**"
65
+ protectedPaths:
66
+ - "db/migrations/"
67
+ - ".github/workflows/"
68
+ - "terraform/"
69
+ - "CLAUDE.md"
70
+ - "scope.yaml"
71
+ blockingLabels:
72
+ - "needs-human"
73
+ - "rebase-needed"
74
+ requireCi: true
75
+ requireCleanRebase: true
76
+ labels:
77
+ needsHuman: "needs-human"
78
+ rebaseNeeded: "rebase-needed"
79
+
80
+ # wrapper-only (I/O) knobs:
81
+ approvalBodyRegex: "Verdict.*APPROVE" # count a COMMENTED review as approval
82
+ ciIgnoreCheckNames: ["review", "fix", "sweep", "merge"]
83
+ mergeMethod: "rebase" # merge | squash | rebase
84
+ deleteBranchOnMerge: true
85
+ ```
86
+
87
+ Every field is optional; defaults are safe (`requireCi`/`requireCleanRebase`
88
+ default to `true`, `maxAdditions` defaults to unlimited, delay to `0`).
89
+
90
+ ## Usage
91
+
92
+ ```yaml
93
+ - uses: actions/checkout@v5
94
+ - id: gate
95
+ uses: <owner>/<repo>/actions/merge-gate@<ref>
96
+ with:
97
+ pr-number: ${{ github.event.pull_request.number }}
98
+ token: ${{ steps.app-token.outputs.token }}
99
+ policy-path: .github/merge-policy.yml
100
+ - run: echo "Gate said ${{ steps.gate.outputs.action }}: ${{ steps.gate.outputs.reason }}"
101
+ ```
102
+
103
+ ## Development
104
+
105
+ ```bash
106
+ npm test -- actions/merge-gate # run the unit tests
107
+ npm run build:actions # bundle src/index.ts -> dist/index.js
108
+ ```
109
+
110
+ The wrapper is bundled to `dist/index.js` by the repo's action build; do not
111
+ edit `dist/` by hand.
@@ -0,0 +1,60 @@
1
+ name: "merge-gate"
2
+ description: >
3
+ Evaluate a PR against a merge policy (bot-approval, CI, approval delay,
4
+ hand-written diff size, protected paths, clean rebase) and either merge it,
5
+ apply a routing label, or skip. Generalized port of the gp-dixie "Shipper".
6
+ author: "gp-foundry"
7
+
8
+ inputs:
9
+ pr-number:
10
+ description: >
11
+ PR number to evaluate. When omitted, the action runs in POLLER mode:
12
+ it discovers open candidate PRs and merges the first that qualifies.
13
+ required: false
14
+ default: ""
15
+ token:
16
+ description: >
17
+ GitHub token with contents:write and pull-requests:write (a GitHub App
18
+ installation token or a PAT so merges are attributed and events cascade).
19
+ required: true
20
+ policy-path:
21
+ description: "Path to the merge policy file (YAML or JSON)."
22
+ required: true
23
+ base-branch:
24
+ description: "Base branch to filter candidate PRs by (poller mode)."
25
+ required: false
26
+ default: "main"
27
+ branch-prefix:
28
+ description: >
29
+ Only consider PRs whose head branch starts with this prefix (poller mode).
30
+ Overrides the policy file's branchPrefix when set.
31
+ required: false
32
+ default: ""
33
+ clean-rebase:
34
+ description: >
35
+ Optional override for the clean-rebase check: "true" or "false". When
36
+ unset, the action infers it from the PR's mergeable state.
37
+ required: false
38
+ default: ""
39
+ dry-run:
40
+ description: "When 'true', evaluate and emit outputs but perform no mutation."
41
+ required: false
42
+ default: "false"
43
+
44
+ outputs:
45
+ action:
46
+ description: "Decision: merge | skip | label."
47
+ code:
48
+ description: "Machine-stable reason code (e.g. ready-to-merge, too-large)."
49
+ reason:
50
+ description: "Human-readable explanation of the decision."
51
+ label:
52
+ description: "Label to apply, when action is 'label'."
53
+ merged:
54
+ description: "'true' if a PR was merged by this run, else 'false'."
55
+ merged-pr:
56
+ description: "The PR number that was merged, if any."
57
+
58
+ runs:
59
+ using: "node24"
60
+ main: "dist/index.cjs"