@jagreehal/shepherd 0.3.0 → 0.5.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 (55) hide show
  1. package/AGENTS.md +5 -0
  2. package/README.md +41 -419
  3. package/THIRD_PARTY_NOTICES.md +11 -0
  4. package/lenses/dotnet/SKILL.md +32 -0
  5. package/lenses/go/SKILL.md +30 -0
  6. package/lenses/java/SKILL.md +31 -0
  7. package/lenses/nextjs/SKILL.md +33 -0
  8. package/lenses/node-api/SKILL.md +32 -0
  9. package/lenses/nx-monorepo/SKILL.md +30 -0
  10. package/lenses/observability/SKILL.md +18 -11
  11. package/lenses/owasp-asvs/SKILL.md +50 -0
  12. package/lenses/owasp-llm/SKILL.md +44 -0
  13. package/lenses/python/SKILL.md +32 -0
  14. package/lenses/react/SKILL.md +33 -0
  15. package/lenses/rust/SKILL.md +31 -0
  16. package/package.json +17 -8
  17. package/packs/dotnet.yml +6 -0
  18. package/packs/go.yml +6 -0
  19. package/packs/java.yml +6 -0
  20. package/packs/nextjs.yml +7 -0
  21. package/packs/node-api.yml +7 -0
  22. package/packs/nx-monorepo.yml +6 -0
  23. package/packs/observability.yml +6 -0
  24. package/packs/owasp-asvs.yml +6 -0
  25. package/packs/owasp-llm.yml +8 -0
  26. package/packs/python.yml +6 -0
  27. package/packs/react.yml +6 -0
  28. package/packs/rust.yml +6 -0
  29. package/skills/ci-repair/SKILL.md +6 -1
  30. package/skills/garden/SKILL.md +28 -3
  31. package/skills/garden/references/telemetry.md +50 -0
  32. package/skills/incident/SKILL.md +6 -1
  33. package/skills/lens-import/SKILL.md +185 -0
  34. package/skills/lens-import/references/conversion.md +96 -0
  35. package/skills/lens-import/scripts/check-import.mjs +154 -0
  36. package/skills/shepherd/SKILL.md +121 -6
  37. package/skills/shepherd/references/dispatch.md +12 -0
  38. package/skills/shepherd/references/models.md +20 -7
  39. package/skills/shepherd/references/policy.md +9 -5
  40. package/skills/shepherd/references/stories.md +102 -0
  41. package/skills/swarm/SKILL.md +16 -1
  42. package/skills/swarm/references/custom-lenses.md +50 -7
  43. package/skills/triage/SKILL.md +19 -0
  44. package/src/cli.ts +210 -16
  45. package/src/config.ts +137 -21
  46. package/src/garden-traces.ts +461 -0
  47. package/src/garden.ts +2 -1
  48. package/src/install.ts +3 -0
  49. package/src/lens.ts +159 -8
  50. package/src/notify.ts +138 -0
  51. package/src/stack.ts +121 -0
  52. package/src/trace.ts +180 -0
  53. package/templates/shepherd-audit.yml +178 -0
  54. package/templates/shepherd-incident.yml +180 -0
  55. package/templates/shepherd.yml +427 -0
@@ -0,0 +1,427 @@
1
+ # shepherd in CI: one loop iteration each time CI or stamp finishes on a PR, on a `/shepherd` comment,
2
+ # when a PR gets the SHEPHERD_LABEL, or from the sweep. Each iteration's fixes are pushed, CI and stamp run
3
+ # on the new head, and their completion starts the next one, until shepherd sets a final `shepherd` status
4
+ # (success, or failure naming what the author must do). Installed by `shepherd workflows`.
5
+ #
6
+ # The model reads text anyone can write (comments, review threads, bot output), so it never holds a write
7
+ # credential. `gate` (no model) decides whether to run. `iterate` runs the model with github.token, which can
8
+ # comment, resolve threads and read, never push; its commits leave as a git bundle. `publish` runs no model:
9
+ # it pushes the bundle to the PR's own branch only as a fast-forward that touches nothing matching
10
+ # SHEPHERD_PUSH_DENY, then sets the status and notifies.
11
+ #
12
+ # Secrets:
13
+ # SHEPHERD_TOKEN fine-grained PAT: contents, pull requests and commit statuses (read/write). Only
14
+ # `gate` and `publish` see it. Pushes made with github.token start no workflows, so the loop would stall.
15
+ # SHEPHERD_API_KEY the model key, for whichever provider the session model names (Bedrock: a Bedrock API key).
16
+ # Or each provider's own secret (OPENCODE_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY,
17
+ # DEEPSEEK_API_KEY, AWS_BEARER_TOKEN_BEDROCK...) when the ladder mixes providers.
18
+ # SHEPHERD_NOTIFY_WEBHOOK optional: Slack Incoming Webhook or any JSON endpoint, told when a PR needs
19
+ # you, is ready to merge, or the iteration stopped on an error.
20
+ # Variables:
21
+ # SHEPHERD_MODEL optional: the session model, a model id or a tier from .shepherd/config.yml. Empty = the
22
+ # team's models.loop, else the top of its ladder, else opencode-go/kimi-k3. Runners take
23
+ # their own models from the team's tiers, ladder and pins (shepherd models shows them).
24
+ # AWS_REGION the Bedrock region, for a bedrock: model.
25
+ # SHEPHERD_LABEL optional: shepherd only PRs carrying this label. Whatever opens PRs (a person, Claude
26
+ # Code, Codex, another agent) hands one over by adding it.
27
+ # SHEPHERD_NOTIFY_ON optional: states that notify, e.g. "failure"; empty = success,failure,error.
28
+ # SHEPHERD_PUSH_DENY optional: extended regex of paths a handed-off fix may not touch; empty = workflows,
29
+ # git and editor hooks, package manager config, manifests and lockfiles.
30
+ #
31
+ # Edit `workflows: [ci, stamp]` to name your CI workflow. workflow_run, pull_request_target and schedule
32
+ # run this file from the default branch, so a PR cannot change how it is shepherded.
33
+ name: shepherd
34
+ on:
35
+ workflow_run:
36
+ workflows: [ci, stamp]
37
+ types: [completed]
38
+ issue_comment:
39
+ types: [created]
40
+ pull_request_target:
41
+ types: [labeled]
42
+ workflow_dispatch:
43
+ inputs:
44
+ pr:
45
+ description: PR number
46
+ required: true
47
+ schedule:
48
+ - cron: "*/30 * * * *" # the sweep: PRs left pending with nothing to wake them (bot reviews, a lost event)
49
+
50
+ permissions:
51
+ contents: read
52
+
53
+ # One run per PR at a time, gate to publish, so a run's statuses never interleave with another's. The condition
54
+ # is the gate's `if` verbatim (a test keeps them in step): a run that event alone rules out gets a group of its
55
+ # own. A run the gate step skips after reading GitHub (finished head, label scope, incident branch) still queues
56
+ # in the PR's group, where GitHub keeps one waiting run, so a later event can take a queued `/shepherd`'s place.
57
+ concurrency:
58
+ group: >-
59
+ ${{ github.event_name == 'schedule' && 'shepherd-sweep'
60
+ || (((github.event_name == 'workflow_run' && github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.pull_requests[0] != null && github.event.workflow_run.head_repository.full_name == github.repository) || (github.event_name == 'issue_comment' && github.event.issue.pull_request != null && startsWith(github.event.comment.body, '/shepherd') && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)) || (github.event_name == 'pull_request_target' && vars.SHEPHERD_LABEL != '' && github.event.label.name == vars.SHEPHERD_LABEL) || github.event_name == 'workflow_dispatch') && format('shepherd-{0}', github.event.workflow_run.pull_requests[0].number || github.event.issue.number || github.event.pull_request.number || inputs.pr))
61
+ || format('shepherd-skip-{0}', github.run_id) }}
62
+ cancel-in-progress: false # a run may be mid-handoff; later triggers queue, and GitHub keeps only the newest
63
+
64
+ jobs:
65
+ sweep:
66
+ if: github.event_name == 'schedule'
67
+ runs-on: ubuntu-latest
68
+ timeout-minutes: 5
69
+ permissions:
70
+ actions: write # workflow_dispatch of this file, one run per PR
71
+ statuses: read
72
+ pull-requests: read
73
+ env:
74
+ GH_TOKEN: ${{ github.token }}
75
+ LABEL: ${{ vars.SHEPHERD_LABEL }}
76
+ steps:
77
+ - name: Start an iteration on each PR still pending
78
+ run: |
79
+ # With a label, a labelled PR shepherd has never touched counts as pending too.
80
+ wf=$(basename "${GITHUB_WORKFLOW_REF%@*}")
81
+ gh pr list -R "$GITHUB_REPOSITORY" --state open --limit 100 --json number,headRefOid,isDraft,isCrossRepository,labels \
82
+ --jq '.[] | select(.isDraft | not) | select(.isCrossRepository | not) | [.number, .headRefOid, ([.labels[].name] | join(","))] | @tsv' |
83
+ while IFS=$'\t' read -r pr head labels; do
84
+ if [ -n "$LABEL" ]; then [[ ",$labels," == *",$LABEL,"* ]] || continue; fi
85
+ state=$(gh api "repos/$GITHUB_REPOSITORY/commits/$head/status" --jq '[.statuses[] | select(.context=="shepherd")][0].state // ""')
86
+ if [ "$state" = pending ] || { [ -z "$state" ] && [ -n "$LABEL" ]; }; then
87
+ echo "dispatch #$pr (${state:-untouched})"
88
+ gh workflow run "$wf" -R "$GITHUB_REPOSITORY" -f pr="$pr"
89
+ fi
90
+ done
91
+
92
+ # Runs no model. The only job that reads SHEPHERD_TOKEN besides publish: a secret any step of a job uses sits
93
+ # in that job's runner memory, where a hijacked model step could read it.
94
+ gate:
95
+ if: >-
96
+ (github.event_name == 'workflow_run' && github.event.workflow_run.event == 'pull_request'
97
+ && github.event.workflow_run.pull_requests[0] != null
98
+ && github.event.workflow_run.head_repository.full_name == github.repository)
99
+ || (github.event_name == 'issue_comment' && github.event.issue.pull_request != null
100
+ && startsWith(github.event.comment.body, '/shepherd')
101
+ && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association))
102
+ || (github.event_name == 'pull_request_target' && vars.SHEPHERD_LABEL != ''
103
+ && github.event.label.name == vars.SHEPHERD_LABEL)
104
+ || github.event_name == 'workflow_dispatch'
105
+ runs-on: ubuntu-latest
106
+ timeout-minutes: 5
107
+ permissions:
108
+ contents: read
109
+ pull-requests: read
110
+ statuses: write # pending before the model starts
111
+ outputs:
112
+ run: ${{ steps.gate.outputs.run }}
113
+ branch: ${{ steps.gate.outputs.branch }}
114
+ base: ${{ steps.gate.outputs.base }}
115
+ head: ${{ steps.gate.outputs.head }}
116
+ git_name: ${{ steps.gate.outputs.git_name }}
117
+ git_email: ${{ steps.gate.outputs.git_email }}
118
+ env:
119
+ PR: ${{ github.event.workflow_run.pull_requests[0].number || github.event.issue.number || github.event.pull_request.number || inputs.pr }}
120
+ LABEL: ${{ vars.SHEPHERD_LABEL }}
121
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
122
+ MAX_SHEPHERD_COMMITS: 20
123
+ steps:
124
+ - name: Decide whether this iteration is worth running
125
+ id: gate
126
+ env:
127
+ GH_TOKEN: ${{ secrets.SHEPHERD_TOKEN || github.token }}
128
+ run: |
129
+ [[ "$PR" =~ ^[0-9]+$ ]] || { echo "PR must be a number"; exit 1; }
130
+ pr=$(gh pr view "$PR" -R "$GITHUB_REPOSITORY" --json state,author,headRefOid,headRefName,baseRefName,isCrossRepository,isDraft,labels,commits)
131
+ state=$(jq -r .state <<<"$pr"); head=$(jq -r .headRefOid <<<"$pr"); author=$(jq -r .author.login <<<"$pr"); branch=$(jq -r .headRefName <<<"$pr")
132
+ skip() { echo "skip: $1"; echo "run=false" >> "$GITHUB_OUTPUT"; exit 0; }
133
+ [ "$state" = OPEN ] || skip "PR is $state"
134
+ [ "$(jq -r .isCrossRepository <<<"$pr")" = false ] || skip "fork PR"
135
+ [ "$(jq -r .isDraft <<<"$pr")" = false ] || skip "draft"
136
+ # publish pushes to the head branch: never let that be the default branch.
137
+ [ "$branch" != "$DEFAULT_BRANCH" ] || skip "the PR's head is the default branch"
138
+ labelled=false
139
+ [ -n "$LABEL" ] && jq -e --arg l "$LABEL" 'any(.labels[]; .name == $l)' <<<"$pr" >/dev/null && labelled=true
140
+ # A label scopes the automatic triggers; a /shepherd comment always runs.
141
+ if [ -n "$LABEL" ] && [ "$GITHUB_EVENT_NAME" != issue_comment ] && [ "$labelled" = false ]; then skip "no $LABEL label"; fi
142
+ # An incident fix was written by an agent from alert text. A person starts shepherd on it.
143
+ if [[ "$branch" == incident/* ]] && [ "$GITHUB_EVENT_NAME" != issue_comment ] && [ "$labelled" = false ]; then
144
+ skip "incident fix: comment /shepherd${LABEL:+ or add the $LABEL label} to start"
145
+ fi
146
+ # Only PRs by people who could push this code themselves: shepherd runs their checks with these secrets.
147
+ perm=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$author/permission" --jq .permission 2>/dev/null || echo none)
148
+ case "$perm" in admin|maintain|write) ;; *) skip "author $author has $perm access" ;; esac
149
+ if [ "$GITHUB_EVENT_NAME" = workflow_run ] || { [ "$GITHUB_EVENT_NAME" = workflow_dispatch ] && [ "$GITHUB_ACTOR" = "github-actions[bot]" ]; }; then
150
+ done=$(gh api "repos/$GITHUB_REPOSITORY/commits/$head/status" --jq '[.statuses[] | select(.context=="shepherd")][0].state // ""')
151
+ case "$done" in success|failure|error) skip "shepherd already finished on $head ($done); comment /shepherd to run again" ;; esac
152
+ # The sweep dispatched this run for a pending head; a run that finished it while this one queued wins.
153
+ if [ "$GITHUB_EVENT_NAME" = workflow_dispatch ] && [ "$done" != pending ] && { [ -n "$done" ] || [ -z "$LABEL" ]; }; then skip "head is no longer pending"; fi
154
+ fi
155
+ n=$(jq '[.commits[] | select(.messageBody | test("^Shepherd: "; "m"))] | length' <<<"$pr")
156
+ if [ "$n" -ge "$MAX_SHEPHERD_COMMITS" ]; then
157
+ gh api "repos/$GITHUB_REPOSITORY/statuses/$head" -f context=shepherd -f state=failure -f description="stopped after $n shepherd commits; a person should look" >/dev/null || true
158
+ skip "$n shepherd commits"
159
+ fi
160
+ # Commits go out under the token's owner, as their own pushes would.
161
+ login=$(gh api user --jq .login 2>/dev/null || true)
162
+ if [ -n "$login" ]; then
163
+ echo "git_name=$login" >> "$GITHUB_OUTPUT"
164
+ echo "git_email=$(gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"')" >> "$GITHUB_OUTPUT"
165
+ else
166
+ echo "git_name=github-actions[bot]" >> "$GITHUB_OUTPUT"
167
+ echo "git_email=41898282+github-actions[bot]@users.noreply.github.com" >> "$GITHUB_OUTPUT"
168
+ fi
169
+ { echo "run=true"; echo "branch=$branch"; echo "base=$(jq -r .baseRefName <<<"$pr")"; echo "head=$head"; } >> "$GITHUB_OUTPUT"
170
+ # A rerun must never leave an old green standing while the model works or after it fails.
171
+ - name: Mark the head pending
172
+ if: steps.gate.outputs.run == 'true'
173
+ env:
174
+ GH_TOKEN: ${{ github.token }}
175
+ HEAD_SHA: ${{ steps.gate.outputs.head }}
176
+ run: gh api "repos/$GITHUB_REPOSITORY/statuses/$HEAD_SHA" -f context=shepherd -f state=pending -f description="shepherd iteration running" >/dev/null
177
+
178
+ iterate:
179
+ needs: gate
180
+ if: needs.gate.outputs.run == 'true'
181
+ runs-on: ubuntu-latest
182
+ timeout-minutes: 45
183
+ # github.token for the model: comment, resolve threads, read code and CI. No contents write, and no
184
+ # SHEPHERD_TOKEN anywhere in this job.
185
+ permissions:
186
+ contents: read
187
+ pull-requests: write
188
+ issues: write
189
+ actions: read
190
+ checks: read
191
+ statuses: read
192
+ env:
193
+ PR: ${{ github.event.workflow_run.pull_requests[0].number || github.event.issue.number || github.event.pull_request.number || inputs.pr }}
194
+ SHEPHERD_VERSION: 0.3.0 # pinned: this runs with the repo's secrets, so bumps are deliberate
195
+ steps:
196
+ - uses: actions/checkout@v4
197
+ with:
198
+ ref: ${{ needs.gate.outputs.branch }}
199
+ fetch-depth: 0
200
+ persist-credentials: false # no token in .git/config for the model to find
201
+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0: pinned, this job holds the model key
202
+ # Install your project's dependencies here so shepherd's checks can run, with install scripts off and no
203
+ # dependency cache (npm ci --ignore-scripts; setup-node without `cache:`): a cache this job saves would
204
+ # reach every later run on the default branch.
205
+ - shell: bash # -eo pipefail: a failed download fails here, not in the agent step
206
+ env:
207
+ GIT_NAME: ${{ needs.gate.outputs.git_name }}
208
+ GIT_EMAIL: ${{ needs.gate.outputs.git_email }}
209
+ run: |
210
+ # The pinned CLI on PATH: the skills call `shepherd`, and fall back to an unpinned bunx without it.
211
+ bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
212
+ export PATH="$HOME/.bun/bin:$PATH" && echo "$HOME/.bun/bin" >> "$GITHUB_PATH"
213
+ [ "$(command -v shepherd)" = "$HOME/.bun/bin/shepherd" ] || { echo "shepherd is not the pinned CLI"; exit 1; }
214
+ shepherd install # skills to ~/.claude/skills, where opencode finds them
215
+ # OpenCode 1.x: its installer refuses 2.x releases, which have their own (opencode.ai/v2/install).
216
+ curl -fsSL https://opencode.ai/install | bash -s -- --version 1.19.0
217
+ "$HOME/.opencode/bin/opencode" --version # fails the step if the install did not land
218
+ echo "$HOME/.opencode/bin" >> "$GITHUB_PATH"
219
+ git config user.name "$GIT_NAME"
220
+ git config user.email "$GIT_EMAIL"
221
+ mkdir -p "$RUNNER_TEMP/handoff"
222
+ - name: One shepherd iteration
223
+ timeout-minutes: 30 # opencode retries a provider error (an exhausted quota) silently; fail instead of holding the queue
224
+ env:
225
+ GH_TOKEN: ${{ github.token }}
226
+ SHEPHERD_HANDOFF: ${{ runner.temp }}/handoff
227
+ SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
228
+ OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
229
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
230
+ OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
231
+ OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
232
+ DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
233
+ GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
234
+ MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
235
+ GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
236
+ XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
237
+ AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
238
+ AWS_REGION: ${{ vars.AWS_REGION }} # for a bedrock: model
239
+ SHEPHERD_MODEL: ${{ vars.SHEPHERD_MODEL }} # a model or tier; empty = the team's models.loop, top rung, or the default
240
+ SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
241
+ OPENCODE_DISABLE_PROJECT_CONFIG: "1" # the checkout's opencode.json, .opencode/ plugins and AGENTS.md are PR content
242
+ OPENCODE_DISABLE_AUTOUPDATE: "1"
243
+ run: |
244
+ # The team's models, from the default branch: the session model, the variable its key goes in, and the
245
+ # OpenCode agents that carry the ladder and pins, so each runner gets its own model.
246
+ plan=$(shepherd ci-models)
247
+ model=$(jq -r .model <<<"$plan")
248
+ echo "session model: $model ($(jq -r .source <<<"$plan"))"
249
+ key_env=$(jq -r '.key_env // empty' <<<"$plan")
250
+ if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
251
+ unset SHEPHERD_API_KEY
252
+ # An unset secret arrives as "": a blank key would hide the provider's other credentials.
253
+ for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do [ -n "${!k:-}" ] || unset "$k"; done
254
+ OPENCODE_CONFIG_CONTENT=$(jq -c .opencode <<<"$plan") && export OPENCODE_CONFIG_CONTENT
255
+ opencode run --auto -m "$model" --title "shepherd #$PR" "Load the shepherd skill and run exactly one iteration on PR $PR in handoff mode:
256
+ SHEPHERD_HANDOFF is set, so follow the skill's Handoff mode. You are running in GitHub Actions on the PR branch,
257
+ already checked out, and you cannot push. Nobody is watching this session: never wait for an answer. Anything you
258
+ would ask the user is deferred, listed in the iteration summary, and named in status.json. Do not schedule further
259
+ iterations; the next one starts when CI or stamp finishes on the head the workflow pushes."
260
+ - name: Bundle the commits
261
+ env:
262
+ H0: ${{ needs.gate.outputs.head }}
263
+ run: |
264
+ git branch -f shepherd-handoff HEAD
265
+ if [ "$(git rev-parse HEAD)" != "$H0" ]; then git bundle create "$RUNNER_TEMP/handoff/fix.bundle" "$H0..shepherd-handoff"; fi
266
+ - uses: actions/upload-artifact@v4
267
+ with:
268
+ name: shepherd-handoff
269
+ path: ${{ runner.temp }}/handoff
270
+ if-no-files-found: ignore
271
+
272
+ publish:
273
+ needs: [gate, iterate]
274
+ # The finalizer: runs whether the iteration succeeded or not, so a failed or timed-out model leaves an
275
+ # `error` status, never the pending the gate set or an older green.
276
+ if: always() && needs.gate.result == 'success' && needs.gate.outputs.run == 'true'
277
+ runs-on: ubuntu-latest
278
+ timeout-minutes: 10
279
+ # No model runs here, and nothing the model wrote runs here: the bundle is fetched and checked, never executed.
280
+ permissions:
281
+ contents: read
282
+ pull-requests: read
283
+ statuses: write
284
+ actions: write # rerun the jobs ci-repair asked for
285
+ env:
286
+ PR: ${{ github.event.workflow_run.pull_requests[0].number || github.event.issue.number || github.event.pull_request.number || inputs.pr }}
287
+ BRANCH: ${{ needs.gate.outputs.branch }}
288
+ BASE: ${{ needs.gate.outputs.base }}
289
+ H0: ${{ needs.gate.outputs.head }}
290
+ HAS_PAT: ${{ secrets.SHEPHERD_TOKEN != '' }}
291
+ ITERATED: ${{ needs.iterate.result }}
292
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
293
+ # Paths that run without review: CI, git and editor hooks, package manager config, manifests and lockfiles.
294
+ # Matched case-insensitively.
295
+ DENY: ${{ vars.SHEPHERD_PUSH_DENY || '^\.github/|^\.gitmodules$|(^|/)\.gitattributes$|(^|/)\.(husky|githooks|devcontainer|vscode)/|(^|/)\.(npmrc|yarnrc|yarnrc\.yml|pnpmfile\.cjs)$|(^|/)(package\.json|bunfig\.toml|go\.mod|cargo\.toml|build\.rs|pyproject\.toml|setup\.(py|cfg)|requirements[^/]*\.txt|gemfile|composer\.json|pom\.xml|build\.gradle(\.kts)?|settings\.gradle(\.kts)?|[^/]*\.lockb?|[^/]*[._-]lock\.(json|ya?ml|hcl|toml)|[^/]*\.lockfile|npm-shrinkwrap\.json|go\.sum|package\.resolved|(gnu)?makefile|\.?justfile|taskfile(\.dist)?\.ya?ml)$|(^|/)\.pre-commit-config\.yaml$|(^|/)\.cargo/|(^|/)(pnpm-workspace\.yaml|pipfile|deno\.jsonc?)$' }}
296
+ SHEPHERD_VERSION: 0.3.0 # pinned, as in iterate
297
+ steps:
298
+ # First, before any setup that could fail: a stopped iteration must never leave the gate's pending standing.
299
+ - name: Report a stopped iteration
300
+ id: stopped
301
+ if: env.ITERATED != 'success'
302
+ env:
303
+ GH_TOKEN: ${{ github.token }}
304
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
305
+ run: |
306
+ echo "shepherd iteration ${ITERATED}; comment /shepherd to retry" > description.txt
307
+ gh api "repos/$GITHUB_REPOSITORY/statuses/$H0" -f context=shepherd -f state=error -f description="$(cat description.txt)" -f target_url="$RUN_URL" >/dev/null
308
+ echo "state=error" >> "$GITHUB_OUTPUT"
309
+ - if: env.ITERATED == 'success'
310
+ uses: actions/download-artifact@v4
311
+ id: handoff
312
+ continue-on-error: true # no artifact: the iteration wrote nothing
313
+ with:
314
+ name: shepherd-handoff
315
+ path: handoff
316
+ - if: env.ITERATED == 'success'
317
+ uses: actions/checkout@v4
318
+ with:
319
+ ref: ${{ needs.gate.outputs.branch }}
320
+ fetch-depth: 0
321
+ path: repo
322
+ token: ${{ secrets.SHEPHERD_TOKEN || github.token }}
323
+ - name: Push the handed-off commits
324
+ id: push
325
+ if: env.ITERATED == 'success'
326
+ working-directory: repo
327
+ shell: bash # -eo pipefail
328
+ env:
329
+ GH_TOKEN: ${{ secrets.SHEPHERD_TOKEN || github.token }}
330
+ run: |
331
+ echo "head=$H0" >> "$GITHUB_OUTPUT"
332
+ refuse() { echo "::error::$1"; echo "refused=$1" >> "$GITHUB_OUTPUT"; exit 0; }
333
+ [ -f ../handoff/fix.bundle ] || { echo "no commits handed off"; exit 0; }
334
+ [ "$HAS_PAT" = true ] || refuse "set the SHEPHERD_TOKEN secret so shepherd can push"
335
+ [ "$BRANCH" != "$DEFAULT_BRANCH" ] && [ "$BRANCH" != "$BASE" ] || refuse "will not push to $BRANCH"
336
+ git -c core.hooksPath=/dev/null fetch -q ../handoff/fix.bundle "shepherd-handoff:refs/shepherd/handoff"
337
+ new=$(git rev-parse refs/shepherd/handoff)
338
+ live=$(gh pr view "$PR" -R "$GITHUB_REPOSITORY" --json headRefOid -q .headRefOid)
339
+ [ "$live" = "$H0" ] || { echo "someone pushed ($H0 -> $live); the next iteration re-baselines"; echo "stale=true" >> "$GITHUB_OUTPUT"; exit 0; }
340
+ git merge-base --is-ancestor "$H0" "$new" || refuse "the fixes are not a fast-forward of $H0"
341
+ # A path counts when the fixes left it different from both the head they started on and the base, so a
342
+ # base merge's own changes pass. NUL-delimited and rename-free: no quoted or renamed path slips by.
343
+ git diff -z --no-renames --name-only "$H0" "$new" > ../from-head
344
+ git diff -z --no-renames --name-only "origin/$BASE" "$new" > ../from-base
345
+ bad=$(python3 - ../from-head ../from-base "$DENY" <<'PY'
346
+ import re, sys
347
+ read = lambda f: {p for p in open(f, "rb").read().split(b"\0") if p}
348
+ deny = re.compile(sys.argv[3].encode(), re.IGNORECASE)
349
+ # A control character in a path is refused outright: no tool needs one, and it can split a line.
350
+ bad = sorted(p for p in read(sys.argv[1]) & read(sys.argv[2]) if deny.search(p) or re.search(rb"[\x00-\x1f\x7f]", p))
351
+ # Paths are model-chosen: no control character reaches GITHUB_OUTPUT or a workflow command.
352
+ print(" ".join(re.sub(r"[\x00-\x1f\x7f]", "?", p.decode(errors="replace")) for p in bad)[:500])
353
+ PY
354
+ )
355
+ [ -z "$bad" ] || refuse "the fixes touch protected paths: $bad"
356
+ git -c core.hooksPath=/dev/null push origin "$new:refs/heads/$BRANCH"
357
+ { echo "head=$new"; echo "pushed=$(git rev-list --count "$H0..$new")"; } >> "$GITHUB_OUTPUT"
358
+ - name: Set the shepherd status
359
+ id: status
360
+ if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true'
361
+ env:
362
+ GH_TOKEN: ${{ github.token }}
363
+ HEAD_SHA: ${{ steps.push.outputs.head }}
364
+ PUSHED: ${{ steps.push.outputs.pushed }}
365
+ REFUSED: ${{ steps.push.outputs.refused }}
366
+ run: |
367
+ # status.json is model output: only a known state and one short line of text get through.
368
+ python3 - handoff/status.json "$PUSHED" "$REFUSED" > status.out <<'PY'
369
+ import json, sys
370
+ try:
371
+ s = json.load(open(sys.argv[1]))
372
+ except Exception:
373
+ s = {}
374
+ if not isinstance(s, dict):
375
+ s = {}
376
+ state = s.get("state") if s.get("state") in ("success", "pending", "failure") else "pending"
377
+ desc = " ".join(str(s.get("description") or "iteration ended without a status").split())
378
+ if sys.argv[3]:
379
+ state, desc = "failure", f"fixes not pushed, a person should look: {' '.join(sys.argv[3].split())}"
380
+ elif sys.argv[2]:
381
+ state, desc = "pending", f"pushed {sys.argv[2]} commit(s) for review; {desc}"
382
+ print(state)
383
+ print(desc[:139])
384
+ PY
385
+ state=$(sed -n 1p status.out); sed -n 2p status.out > description.txt
386
+ gh api "repos/$GITHUB_REPOSITORY/statuses/$HEAD_SHA" -f context=shepherd -f state="$state" -f description="$(cat description.txt)" >/dev/null
387
+ echo "state=$state" >> "$GITHUB_OUTPUT"
388
+ - name: Rerun the jobs ci-repair asked for
389
+ if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true' && steps.push.outputs.pushed == '' && hashFiles('handoff/rerun-jobs.txt') != ''
390
+ env:
391
+ GH_TOKEN: ${{ github.token }}
392
+ run: |
393
+ # Model output names the jobs: rerun one only if it ran on this PR's head from a pull_request event.
394
+ grep -E '^[0-9]+$' handoff/rerun-jobs.txt | head -10 | while read -r job; do
395
+ run=$(gh api "repos/$GITHUB_REPOSITORY/actions/jobs/$job" --jq 'select(.head_sha == env.H0) | .run_id' 2>/dev/null || true)
396
+ event=$([ -n "$run" ] && gh api "repos/$GITHUB_REPOSITORY/actions/runs/$run" --jq .event 2>/dev/null || true)
397
+ if [ "$event" = pull_request ]; then
398
+ gh run rerun --job "$job" -R "$GITHUB_REPOSITORY" || echo "could not rerun job $job"
399
+ else
400
+ echo "skip job $job: not a pull_request job on $H0"
401
+ fi
402
+ done
403
+ # Only notify needs the CLI: a failed install here can skip a notification, never a status.
404
+ - if: steps.status.outcome == 'success' || steps.stopped.outcome == 'success'
405
+ uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0: pinned, this job holds the write token
406
+ - if: steps.status.outcome == 'success' || steps.stopped.outcome == 'success'
407
+ shell: bash
408
+ run: |
409
+ bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
410
+ echo "$HOME/.bun/bin" >> "$GITHUB_PATH"
411
+ - name: Notify
412
+ if: steps.status.outcome == 'success' || steps.stopped.outcome == 'success' # from the workspace, not the PR checkout
413
+ env:
414
+ GH_TOKEN: ${{ github.token }}
415
+ HEAD_SHA: ${{ steps.push.outputs.head || needs.gate.outputs.head }}
416
+ STATE: ${{ steps.status.outputs.state || steps.stopped.outputs.state }}
417
+ SHEPHERD_NOTIFY_WEBHOOK: ${{ secrets.SHEPHERD_NOTIFY_WEBHOOK }}
418
+ SHEPHERD_NOTIFY_ON: ${{ vars.SHEPHERD_NOTIFY_ON }}
419
+ run: shepherd notify --pr "$PR" --repo "$GITHUB_REPOSITORY" --head "$HEAD_SHA" --state "$STATE" --file description.txt
420
+ # Any step above failing (checkout, push, status) must not leave the gate's pending for the sweep to rerun.
421
+ - name: Report a failed publish
422
+ if: always() && failure()
423
+ env:
424
+ GH_TOKEN: ${{ github.token }}
425
+ HEAD_SHA: ${{ steps.push.outputs.head || needs.gate.outputs.head }}
426
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
427
+ run: gh api "repos/$GITHUB_REPOSITORY/statuses/$HEAD_SHA" -f context=shepherd -f state=error -f description="shepherd could not publish this iteration; see the run, then comment /shepherd" -f target_url="$RUN_URL" >/dev/null