@jagreehal/shepherd 0.6.0 → 0.8.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.
@@ -13,19 +13,27 @@
13
13
  # SHEPHERD_TOKEN fine-grained PAT: contents, pull requests and commit statuses (read/write). Only
14
14
  # `gate` and `publish` see it. Pushes made with github.token start no workflows, so the loop would stall.
15
15
  # SHEPHERD_API_KEY the model key, for whichever provider the session model names (Bedrock: a Bedrock API key).
16
+ # Store model keys as an environment's secrets (`shepherd workflows --environment <name>`) so
17
+ # only `iterate` reads them.
16
18
  # Or each provider's own secret (OPENCODE_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY,
17
19
  # DEEPSEEK_API_KEY, AWS_BEARER_TOKEN_BEDROCK...) when the ladder mixes providers.
18
20
  # SHEPHERD_NOTIFY_WEBHOOK optional: Slack Incoming Webhook or any JSON endpoint, told when a PR needs
19
21
  # you, is ready to merge, or the iteration stopped on an error.
22
+ # Settings: put them in .shepherd/config.yml (models.loop, and ci: label, aws_region, notify_on, max_commits,
23
+ # push_deny), where they are reviewed and read from the default branch; `shepherd config explain` lists each with
24
+ # its source. Each repository variable below is an optional override: when set, it wins over the config.
20
25
  # Variables:
21
- # SHEPHERD_MODEL optional: the session model, a model id or a tier from .shepherd/config.yml. Empty = the
26
+ # SHEPHERD_MODEL optional override. Name the session model in .shepherd/config.yml instead
27
+ # (`shepherd models pin loop <model>`), where it is reviewed and versioned. Empty = the
22
28
  # team's models.loop, else the top of its ladder, else opencode-go/kimi-k3. Runners take
23
29
  # 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
30
+ # AWS_REGION ci.aws_region: the Bedrock region, for a bedrock: model.
31
+ # SHEPHERD_LABEL ci.label: shepherd only PRs carrying this label. Whatever opens PRs (a person, Claude
26
32
  # 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,
33
+ # SHEPHERD_NOTIFY_ON ci.notify_on: states that notify, e.g. "failure"; empty = success,failure,error.
34
+ # SHEPHERD_MAX_COMMITS ci.max_commits: shepherd commits on one PR before it stops for a person; empty = 20.
35
+ # SHEPHERD_PUSH_DENY replaces the built-in deny list (an admin's escape hatch). ci.push_deny in config can only
36
+ # ADD patterns to whichever list applies. Extended regex of paths a handed-off fix may not touch; empty = workflows,
29
37
  # git and editor hooks, package manager config, manifests and lockfiles.
30
38
  #
31
39
  # Edit `workflows: [ci, stamp]` to name your CI workflow. workflow_run, pull_request_target and schedule
@@ -44,6 +52,10 @@ on:
44
52
  pr:
45
53
  description: PR number
46
54
  required: true
55
+ asked:
56
+ description: a person asked, by /shepherd comment or the handoff label; runs past a finished head and the label scope
57
+ type: boolean
58
+ default: false
47
59
  schedule:
48
60
  - cron: "*/30 * * * *" # the sweep: PRs left pending with nothing to wake them (bot reviews, a lost event)
49
61
 
@@ -52,12 +64,14 @@ permissions:
52
64
 
53
65
  # One run per PR at a time, gate to publish, so a run's statuses never interleave with another's. The condition
54
66
  # 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.
67
+ # own. So does every `/shepherd` comment and label event: GitHub keeps one waiting run per group, and a comment
68
+ # from someone who cannot push, or a label that is not the handoff label, must never take a queued run's place.
69
+ # The gate checks the commenter or the label and dispatches a run that queues in the PR's group. A run the gate
70
+ # step skips after reading GitHub (finished head, incident branch) still queues there.
57
71
  concurrency:
58
72
  group: >-
59
73
  ${{ 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))
74
+ || (((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 == '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
75
  || format('shepherd-skip-{0}', github.run_id) }}
62
76
  cancel-in-progress: false # a run may be mid-handoff; later triggers queue, and GitHub keeps only the newest
63
77
 
@@ -67,14 +81,35 @@ jobs:
67
81
  runs-on: ubuntu-latest
68
82
  timeout-minutes: 5
69
83
  permissions:
84
+ contents: read # the settings checkout, on a private repository
70
85
  actions: write # workflow_dispatch of this file, one run per PR
71
86
  statuses: read
72
87
  pull-requests: read
73
88
  env:
74
89
  GH_TOKEN: ${{ github.token }}
75
- LABEL: ${{ vars.SHEPHERD_LABEL }}
90
+ SHEPHERD_VERSION: 0.3.0 # pinned, as in iterate
76
91
  steps:
92
+ # Settings from the default branch's .shepherd/config.yml (ci:), each overridden by its variable when set.
93
+ - uses: actions/checkout@v4
94
+ with:
95
+ ref: ${{ github.event.repository.default_branch || github.ref_name }}
96
+ sparse-checkout: .shepherd
97
+ persist-credentials: false
98
+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
99
+ - name: Settings
100
+ id: settings
101
+ env:
102
+ SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
103
+ SHEPHERD_LABEL: ${{ vars.SHEPHERD_LABEL }}
104
+ AWS_REGION: ${{ vars.AWS_REGION }}
105
+ SHEPHERD_NOTIFY_ON: ${{ vars.SHEPHERD_NOTIFY_ON }}
106
+ SHEPHERD_MAX_COMMITS: ${{ vars.SHEPHERD_MAX_COMMITS }}
107
+ run: |
108
+ bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
109
+ "$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
77
110
  - name: Start an iteration on each PR still pending
111
+ env:
112
+ LABEL: ${{ steps.settings.outputs.label }}
78
113
  run: |
79
114
  # With a label, a labelled PR shepherd has never touched counts as pending too.
80
115
  wf=$(basename "${GITHUB_WORKFLOW_REF%@*}")
@@ -97,10 +132,9 @@ jobs:
97
132
  && github.event.workflow_run.pull_requests[0] != null
98
133
  && github.event.workflow_run.head_repository.full_name == github.repository)
99
134
  || (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)
135
+ && startsWith(github.event.comment.body, '/shepherd'))
136
+ || (github.event_name == 'pull_request_target'
137
+ && (vars.SHEPHERD_LABEL == '' || github.event.label.name == vars.SHEPHERD_LABEL))
104
138
  || github.event_name == 'workflow_dispatch'
105
139
  runs-on: ubuntu-latest
106
140
  timeout-minutes: 5
@@ -108,6 +142,7 @@ jobs:
108
142
  contents: read
109
143
  pull-requests: read
110
144
  statuses: write # pending before the model starts
145
+ actions: write # a /shepherd comment or the handoff label dispatches the run that queues in the PR's group
111
146
  outputs:
112
147
  run: ${{ steps.gate.outputs.run }}
113
148
  branch: ${{ steps.gate.outputs.branch }}
@@ -115,21 +150,61 @@ jobs:
115
150
  head: ${{ steps.gate.outputs.head }}
116
151
  git_name: ${{ steps.gate.outputs.git_name }}
117
152
  git_email: ${{ steps.gate.outputs.git_email }}
153
+ aws_region: ${{ steps.settings.outputs.aws_region }}
154
+ notify_on: ${{ steps.settings.outputs.notify_on }}
155
+ push_deny: ${{ steps.settings.outputs.push_deny }}
118
156
  env:
119
157
  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
158
  DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
122
- MAX_SHEPHERD_COMMITS: 20
159
+ SHEPHERD_VERSION: 0.3.0 # pinned, as in iterate
123
160
  steps:
161
+ # Settings from the default branch's .shepherd/config.yml (ci:), each overridden by its variable when set.
162
+ - uses: actions/checkout@v4
163
+ with:
164
+ ref: ${{ github.event.repository.default_branch || github.ref_name }}
165
+ sparse-checkout: .shepherd
166
+ persist-credentials: false
167
+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
168
+ - name: Settings
169
+ id: settings
170
+ env:
171
+ GH_TOKEN: ${{ github.token }} # gh api, for a github: pack the policy extends
172
+ SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
173
+ SHEPHERD_LABEL: ${{ vars.SHEPHERD_LABEL }}
174
+ AWS_REGION: ${{ vars.AWS_REGION }}
175
+ SHEPHERD_NOTIFY_ON: ${{ vars.SHEPHERD_NOTIFY_ON }}
176
+ SHEPHERD_MAX_COMMITS: ${{ vars.SHEPHERD_MAX_COMMITS }}
177
+ run: |
178
+ bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
179
+ "$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
124
180
  - name: Decide whether this iteration is worth running
125
181
  id: gate
126
182
  env:
127
183
  GH_TOKEN: ${{ secrets.SHEPHERD_TOKEN || github.token }}
184
+ COMMENTER: ${{ github.event.comment.user.login }}
185
+ ASKED: ${{ inputs.asked }}
186
+ DISPATCH_TOKEN: ${{ github.token }}
187
+ EVENT_LABEL: ${{ github.event.label.name }}
188
+ LABEL: ${{ steps.settings.outputs.label }}
189
+ MAX_SHEPHERD_COMMITS: ${{ steps.settings.outputs.max_commits }}
128
190
  run: |
129
191
  [[ "$PR" =~ ^[0-9]+$ ]] || { echo "PR must be a number"; exit 1; }
130
192
  pr=$(gh pr view "$PR" -R "$GITHUB_REPOSITORY" --json state,author,headRefOid,headRefName,baseRefName,isCrossRepository,isDraft,labels,commits)
131
193
  state=$(jq -r .state <<<"$pr"); head=$(jq -r .headRefOid <<<"$pr"); author=$(jq -r .author.login <<<"$pr"); branch=$(jq -r .headRefName <<<"$pr")
132
194
  skip() { echo "skip: $1"; echo "run=false" >> "$GITHUB_OUTPUT"; exit 0; }
195
+ dispatch() { GH_TOKEN=$DISPATCH_TOKEN gh workflow run "$(basename "${GITHUB_WORKFLOW_REF%@*}")" -R "$GITHUB_REPOSITORY" -f pr="$PR" -f asked=true; skip "dispatched a run for $1, queued behind any run on #$PR"; }
196
+ # Every label event reaches the gate, since the label may come from config; only the handoff label counts.
197
+ if [ "$GITHUB_EVENT_NAME" = pull_request_target ] && { [ -z "$LABEL" ] || [ "$EVENT_LABEL" != "$LABEL" ]; }; then skip "label ${EVENT_LABEL:-?} is not the handoff label${LABEL:+ ($LABEL)}"; fi
198
+ [ "$GITHUB_EVENT_NAME" != pull_request_target ] || dispatch "the $LABEL label"
199
+ # A /shepherd comment counts from someone who could push. author_association calls a private org member, or
200
+ # someone with access only through a team, CONTRIBUTOR; the permission API sees their effective access.
201
+ if [ "$GITHUB_EVENT_NAME" = issue_comment ]; then
202
+ perm=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$COMMENTER/permission" --jq .permission 2>/dev/null || echo none)
203
+ case "$perm" in admin|maintain|write) ;; *) skip "commenter $COMMENTER has $perm access" ;; esac
204
+ dispatch "$COMMENTER's /shepherd"
205
+ fi
206
+ asked=false
207
+ [ "$GITHUB_EVENT_NAME" = workflow_dispatch ] && [ "$ASKED" = true ] && asked=true
133
208
  [ "$state" = OPEN ] || skip "PR is $state"
134
209
  [ "$(jq -r .isCrossRepository <<<"$pr")" = false ] || skip "fork PR"
135
210
  [ "$(jq -r .isDraft <<<"$pr")" = false ] || skip "draft"
@@ -138,15 +213,15 @@ jobs:
138
213
  labelled=false
139
214
  [ -n "$LABEL" ] && jq -e --arg l "$LABEL" 'any(.labels[]; .name == $l)' <<<"$pr" >/dev/null && labelled=true
140
215
  # 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
216
+ if [ -n "$LABEL" ] && [ "$asked" = false ] && [ "$labelled" = false ]; then skip "no $LABEL label"; fi
142
217
  # 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
218
+ if [[ "$branch" == incident/* ]] && [ "$asked" = false ] && [ "$labelled" = false ]; then
144
219
  skip "incident fix: comment /shepherd${LABEL:+ or add the $LABEL label} to start"
145
220
  fi
146
221
  # Only PRs by people who could push this code themselves: shepherd runs their checks with these secrets.
147
222
  perm=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$author/permission" --jq .permission 2>/dev/null || echo none)
148
223
  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
224
+ if [ "$GITHUB_EVENT_NAME" = workflow_run ] || { [ "$GITHUB_EVENT_NAME" = workflow_dispatch ] && [ "$GITHUB_ACTOR" = "github-actions[bot]" ] && [ "$asked" = false ]; }; then
150
225
  done=$(gh api "repos/$GITHUB_REPOSITORY/commits/$head/status" --jq '[.statuses[] | select(.context=="shepherd")][0].state // ""')
151
226
  case "$done" in success|failure|error) skip "shepherd already finished on $head ($done); comment /shepherd to run again" ;; esac
152
227
  # The sweep dispatched this run for a pending head; a run that finished it while this one queued wins.
@@ -179,6 +254,7 @@ jobs:
179
254
  needs: gate
180
255
  if: needs.gate.outputs.run == 'true'
181
256
  runs-on: ubuntu-latest
257
+ # environment: <name> `shepherd workflows --environment <name>`: store the model keys as that environment's secrets, readable by this job only
182
258
  timeout-minutes: 45
183
259
  # github.token for the model: comment, resolve threads, read code and CI. No contents write, and no
184
260
  # SHEPHERD_TOKEN anywhere in this job.
@@ -224,6 +300,8 @@ jobs:
224
300
  env:
225
301
  GH_TOKEN: ${{ github.token }}
226
302
  SHEPHERD_HANDOFF: ${{ runner.temp }}/handoff
303
+ SHEPHERD_FANOUT: ${{ runner.temp }}/fanout.json
304
+ BASE: ${{ needs.gate.outputs.base }}
227
305
  SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
228
306
  OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
229
307
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
@@ -235,7 +313,7 @@ jobs:
235
313
  GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
236
314
  XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
237
315
  AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
238
- AWS_REGION: ${{ vars.AWS_REGION }} # for a bedrock: model
316
+ AWS_REGION: ${{ needs.gate.outputs.aws_region }} # ci.aws_region or the AWS_REGION variable, for a bedrock: model
239
317
  SHEPHERD_MODEL: ${{ vars.SHEPHERD_MODEL }} # a model or tier; empty = the team's models.loop, top rung, or the default
240
318
  SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
241
319
  OPENCODE_DISABLE_PROJECT_CONFIG: "1" # the checkout's opencode.json, .opencode/ plugins and AGENTS.md are PR content
@@ -254,8 +332,14 @@ jobs:
254
332
  keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
255
333
  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:-}" ] && [[ "$keys" == *" $k "* ]]; } || unset "$k"; done
256
334
  OPENCODE_CONFIG_CONTENT=$(jq -c .opencode <<<"$plan") && export OPENCODE_CONFIG_CONTENT
335
+ # Swarm's first wave, listed before any PR code runs: each lens extracted from the default branch, and none
336
+ # left to the model to remember. A team lens that resolves nowhere is named here and ends could_not_run.
337
+ shepherd fanout --base "origin/$BASE" > "$SHEPHERD_FANOUT" || echo "::warning::a team lens resolves nowhere; see above"
338
+ jq -e --arg h "$(git rev-parse HEAD)" '.head_sha == $h and any(.lenses[]; .lens == "correctness")' "$SHEPHERD_FANOUT" >/dev/null \
339
+ || { echo "::error::shepherd fanout wrote no usable lens list for this head"; exit 1; }
257
340
  opencode run --auto -m "$model" --title "shepherd #$PR" "Load the shepherd skill and run exactly one iteration on PR $PR in handoff mode:
258
- SHEPHERD_HANDOFF is set, so follow the skill's Handoff mode. You are running in GitHub Actions on the PR branch,
341
+ SHEPHERD_HANDOFF is set, so follow the skill's Handoff mode. Swarm's first wave is in $SHEPHERD_FANOUT: dispatch
342
+ the router and every lens listed there in one message. You are running in GitHub Actions on the PR branch,
259
343
  already checked out, and you cannot push. Nobody is watching this session: never wait for an answer. Anything you
260
344
  would ask the user is deferred, listed in the iteration summary, and named in status.json. Do not schedule further
261
345
  iterations; the next one starts when CI or stamp finishes on the head the workflow pushes."
@@ -281,7 +365,7 @@ jobs:
281
365
  # No model runs here, and nothing the model wrote runs here: the bundle is fetched and checked, never executed.
282
366
  permissions:
283
367
  contents: read
284
- pull-requests: read
368
+ pull-requests: write # post the iteration's findings when the model could not (handoff findings.md); no model runs here
285
369
  statuses: write
286
370
  actions: write # rerun the jobs ci-repair asked for
287
371
  env:
@@ -295,6 +379,7 @@ jobs:
295
379
  # Paths that run without review: CI, git and editor hooks, package manager config, manifests and lockfiles.
296
380
  # Matched case-insensitively.
297
381
  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?)$' }}
382
+ DENY_ADD: ${{ needs.gate.outputs.push_deny }} # ci.push_deny: only ever added to DENY
298
383
  SHEPHERD_VERSION: 0.3.0 # pinned, as in iterate
299
384
  steps:
300
385
  # First, before any setup that could fail: a stopped iteration must never leave the gate's pending standing.
@@ -344,7 +429,7 @@ jobs:
344
429
  # base merge's own changes pass. NUL-delimited and rename-free: no quoted or renamed path slips by.
345
430
  git diff -z --no-renames --name-only "$H0" "$new" > ../from-head
346
431
  git diff -z --no-renames --name-only "origin/$BASE" "$new" > ../from-base
347
- bad=$(python3 - ../from-head ../from-base "$DENY" <<'PY'
432
+ bad=$(python3 - ../from-head ../from-base "$DENY${DENY_ADD:+|$DENY_ADD}" <<'PY'
348
433
  import re, sys
349
434
  read = lambda f: {p for p in open(f, "rb").read().split(b"\0") if p}
350
435
  deny = re.compile(sys.argv[3].encode(), re.IGNORECASE)
@@ -387,6 +472,42 @@ jobs:
387
472
  state=$(sed -n 1p status.out); sed -n 2p status.out > description.txt
388
473
  gh api "repos/$GITHUB_REPOSITORY/statuses/$HEAD_SHA" -f context=shepherd -f state="$state" -f description="$(cat description.txt)" >/dev/null
389
474
  echo "state=$state" >> "$GITHUB_OUTPUT"
475
+ # Under suggest, posting is the review. If the iteration ended without its summary on the PR, post the findings it
476
+ # handed off. findings.md is model output: capped, its markers and HTML comments escaped (it must not pass for a
477
+ # stamp or shepherd comment), mentions and images defused, and built into the body in Python, never by the shell.
478
+ - name: Post findings the iteration did not
479
+ if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true' && hashFiles('handoff/findings.md') != ''
480
+ env:
481
+ GH_TOKEN: ${{ github.token }}
482
+ run: |
483
+ # One summary per PR, updated in place.
484
+ # Only the bot's own summary counts: anyone, the PR's author included, can comment the marker.
485
+ gh api "repos/$GITHUB_REPOSITORY/issues/$PR/comments" --paginate --jq '.[] | select(.user.login == "github-actions[bot]" and (.body | contains("<!-- shepherd-swarm-summary -->"))) | @json' | head -1 > summary.json
486
+ id=$(jq -r .id summary.json)
487
+ jq -r .body summary.json > summary.md
488
+ ! grep -q "@ ${H0:0:7}" summary.md || { echo "the iteration posted its summary ($id)"; exit 0; }
489
+ python3 - handoff/findings.md summary.md "${H0:0:7}" > findings.out <<'PY'
490
+ import re, sys
491
+ CAP = 60000
492
+ def defuse(text):
493
+ text = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]", "", text)
494
+ text = text.replace("<!--", "&lt;!--")
495
+ text = re.sub(r"<(/?)(img|picture|source|video|iframe)\b", r"&lt;\1\2", text, flags=re.IGNORECASE)
496
+ text = re.sub(r"!\[([^\]]*)\]\([^)]*\)", r"[image removed: \1]", text)
497
+ return re.sub(r"(?<![\w`/])@(?=[A-Za-z0-9])", "@​", text)
498
+ raw = open(sys.argv[1], "rb").read(CAP + 1)
499
+ # The header goes on once, below: drop any copy the model wrote into the file.
500
+ text = defuse(re.sub(r"^> 🤖 Automated comment by .*\n?", "", raw[:CAP].decode("utf-8", "replace"), flags=re.M))
501
+ if len(raw) > CAP:
502
+ text += "\n\n_(truncated)_"
503
+ # The summary it replaces keeps its rounds: its latest folds into one history line, as swarm does.
504
+ old = open(sys.argv[2], encoding="utf-8", errors="replace").read()
505
+ latest = re.search(r"^## \S+ ([A-Z_ ]+?) <sub>\(round (\d+) @ ([0-9a-f]{7,40})\)</sub>", old, re.M)
506
+ history = ([f"round {latest[2]} @ {latest[3]}: {latest[1]}"] if latest else []) + re.findall(r"^(?:round \d+|handoff) @ [0-9a-f]{7,40}: [^\n]{0,200}$", old, re.M)
507
+ rounds = f"\n\n<details>\n<summary>Earlier rounds ({len(history)})</summary>\n\n" + defuse("\n".join(history)) + "\n\n</details>" if history else ""
508
+ print(f"<!-- shepherd-swarm-summary -->\n<!-- shepherd-handoff-findings -->\n> 🤖 Automated comment by **Shepherd swarm**, not written by a human\n\n<sub>(handoff @ {sys.argv[3]})</sub>\n\n" + text + rounds)
509
+ PY
510
+ if [ -n "$id" ]; then gh api -X PATCH "repos/$GITHUB_REPOSITORY/issues/comments/$id" -F body=@findings.out >/dev/null; else gh pr comment "$PR" -R "$GITHUB_REPOSITORY" --body-file findings.out; fi
390
511
  - name: Rerun the jobs ci-repair asked for
391
512
  if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true' && steps.push.outputs.pushed == '' && hashFiles('handoff/rerun-jobs.txt') != ''
392
513
  env:
@@ -417,7 +538,7 @@ jobs:
417
538
  HEAD_SHA: ${{ steps.push.outputs.head || needs.gate.outputs.head }}
418
539
  STATE: ${{ steps.status.outputs.state || steps.stopped.outputs.state }}
419
540
  SHEPHERD_NOTIFY_WEBHOOK: ${{ secrets.SHEPHERD_NOTIFY_WEBHOOK }}
420
- SHEPHERD_NOTIFY_ON: ${{ vars.SHEPHERD_NOTIFY_ON }}
541
+ SHEPHERD_NOTIFY_ON: ${{ needs.gate.outputs.notify_on }} # ci.notify_on or the variable
421
542
  run: shepherd notify --pr "$PR" --repo "$GITHUB_REPOSITORY" --head "$HEAD_SHA" --state "$STATE" --file description.txt
422
543
  # Any step above failing (checkout, push, status) must not leave the gate's pending for the sweep to rerun.
423
544
  - name: Report a failed publish