@jagreehal/shepherd 0.15.0 → 0.16.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 (81) hide show
  1. package/AGENTS.md +3 -3
  2. package/README.md +40 -27
  3. package/THIRD_PARTY_NOTICES.md +2 -0
  4. package/gate/.shepherd/gate.schema.json +647 -0
  5. package/gate/.shepherd/gate.yml +122 -0
  6. package/gate/.shepherd/review-guidance.md +95 -0
  7. package/gate/src/actions.ts +32 -0
  8. package/gate/src/cli.ts +1028 -0
  9. package/gate/src/config.ts +102 -0
  10. package/gate/src/delta.ts +29 -0
  11. package/gate/src/env.ts +30 -0
  12. package/gate/src/eval.ts +288 -0
  13. package/gate/src/familiarity.ts +461 -0
  14. package/gate/src/github.ts +761 -0
  15. package/gate/src/inline.ts +59 -0
  16. package/gate/src/isolated-cli.ts +281 -0
  17. package/gate/src/leads.ts +257 -0
  18. package/gate/src/llm.ts +606 -0
  19. package/gate/src/notify.ts +57 -0
  20. package/gate/src/policy.ts +1297 -0
  21. package/gate/src/provider-errors.ts +80 -0
  22. package/gate/src/retention.ts +86 -0
  23. package/gate/src/reviewer.ts +739 -0
  24. package/gate/src/signals.ts +105 -0
  25. package/gate/src/smoke-live.ts +64 -0
  26. package/gate/src/stack.ts +87 -0
  27. package/gate/src/stories.ts +297 -0
  28. package/gate/templates/policy-strict.yml +127 -0
  29. package/gate/templates/reviewer.Dockerfile +8 -0
  30. package/gate/templates/rules/observability/SKILL.md +33 -0
  31. package/gate/templates/shepherd-gate-actions.yml +35 -0
  32. package/gate/templates/shepherd-gate-edited.yml +29 -0
  33. package/gate/templates/shepherd-gate.yml +111 -0
  34. package/lenses/dotnet/SKILL.md +1 -1
  35. package/lenses/go/SKILL.md +1 -1
  36. package/lenses/java/SKILL.md +1 -1
  37. package/lenses/nextjs/SKILL.md +1 -1
  38. package/lenses/node-api/SKILL.md +1 -1
  39. package/lenses/nx-monorepo/SKILL.md +1 -1
  40. package/lenses/observability/SKILL.md +1 -1
  41. package/lenses/owasp-asvs/SKILL.md +1 -1
  42. package/lenses/owasp-llm/SKILL.md +1 -1
  43. package/lenses/pstack/SKILL.md +1 -1
  44. package/lenses/python/SKILL.md +1 -1
  45. package/lenses/react/SKILL.md +1 -1
  46. package/lenses/rust/SKILL.md +1 -1
  47. package/package.json +20 -6
  48. package/schema/config.json +1 -1
  49. package/skills/branch-review/SKILL.md +123 -0
  50. package/skills/ci-repair/SKILL.md +79 -35
  51. package/skills/garden/SKILL.md +8 -8
  52. package/skills/garden/references/telemetry.md +4 -4
  53. package/skills/incident/SKILL.md +9 -9
  54. package/skills/lens-import/SKILL.md +7 -7
  55. package/skills/review-slop/SKILL.md +1 -1
  56. package/skills/shepherd/SKILL.md +43 -41
  57. package/skills/shepherd/references/degradation.md +3 -3
  58. package/skills/shepherd/references/dispatch.md +1 -1
  59. package/skills/shepherd/references/formats.md +5 -5
  60. package/skills/shepherd/references/models.md +2 -2
  61. package/skills/shepherd/references/policy.md +9 -9
  62. package/skills/swarm/SKILL.md +21 -17
  63. package/skills/swarm/references/custom-lenses.md +2 -2
  64. package/skills/swarm/references/formats.md +1 -1
  65. package/skills/triage/SKILL.md +10 -10
  66. package/src/bin.ts +10 -0
  67. package/src/cli.ts +283 -41
  68. package/src/config.ts +26 -25
  69. package/src/doctor.ts +31 -18
  70. package/src/garden-traces.ts +13 -13
  71. package/src/garden.ts +4 -4
  72. package/src/lens.ts +19 -7
  73. package/src/setup.ts +72 -0
  74. package/src/stack.ts +2 -2
  75. package/src/status.ts +80 -0
  76. package/src/summary.ts +52 -9
  77. package/src/trace.ts +4 -4
  78. package/src/working.ts +30 -0
  79. package/templates/shepherd-audit.yml +7 -15
  80. package/templates/shepherd-incident.yml +7 -12
  81. package/templates/shepherd.yml +39 -40
package/src/working.ts ADDED
@@ -0,0 +1,30 @@
1
+ // The "shepherd is reviewing" note: one comment the iteration posts as it starts and the finalizer deletes, so the
2
+ // PR shows work in progress between the push and the summary. It stays apart from the summary comment, whose
3
+ // update-in-place logic it must never confuse.
4
+
5
+ export const WORKING_MARKER = "<!-- shepherd-working -->";
6
+
7
+ /** The animated mascot. A branch URL, so every release shows the same image. */
8
+ export const WORKING_IMAGE = "https://raw.githubusercontent.com/jagreehal/shepherd/main/assets/shepherd-reviewing.svg";
9
+
10
+ /** How the note looks: the repository's branding when it has one (`branding()` output, already escaped). */
11
+ export type WorkingLook = { name: string; header: string; image: string };
12
+
13
+ export const DEFAULT_LOOK: WorkingLook = { name: "shepherd", header: "> 🤖 Automated comment by **Shepherd swarm**, not written by a human", image: WORKING_IMAGE };
14
+
15
+ export function workingNote(head: string, runUrl: string, look: WorkingLook = DEFAULT_LOOK): string {
16
+ return [
17
+ WORKING_MARKER,
18
+ look.header,
19
+ "",
20
+ `<img src="${look.image}" width="96" align="left" alt="">`,
21
+ "",
22
+ `**${look.name} is reviewing \`${head.slice(0, 7)}\`.** The summary replaces this note when the run ends.`,
23
+ "",
24
+ `[Follow the run](${runUrl}) · \`shepherd status\` from a terminal`,
25
+ '<br clear="left">',
26
+ ].join("\n");
27
+ }
28
+
29
+ /** The note's comment among the PR's comments: the bot's own, carrying the marker. */
30
+ export const isWorkingNote = (c: { user: { login: string }; body: string }) => c.user.login === "github-actions[bot]" && c.body.startsWith(WORKING_MARKER);
@@ -6,14 +6,12 @@
6
6
  # The agent's job reads the repository and writes a report, nothing more: no write credential, no persisted
7
7
  # checkout token. A report carrying a credential shape is withheld before anything is uploaded. The report
8
8
  # job runs no model and files or updates one `shepherd-audit` issue on a private repository. On a public
9
- # repository issues and artifacts are public, so the audit runs there only when AUDIT_PUBLIC is `true`: the
9
+ # repository issues and artifacts are public, so the audit runs there only when ci.audit.public is `true`: the
10
10
  # report then becomes a public artifact.
11
11
  #
12
- # Secrets: SHEPHERD_API_KEY (or the provider's own key) for the model.
13
- # Variables: SHEPHERD_MODEL (optional override of the team's models.loop in .shepherd/config.yml, else its top rung), AWS_REGION (Bedrock),
14
- # AUDIT_PLAYS (ci.audit.plays; space-separated play names; empty = the default),
15
- # AUDIT_PUBLIC (ci.audit.public: `true` to run on a public repository, publishing the report).
16
- # Each variable overrides its key in .shepherd/config.yml.
12
+ # Secrets: the model key, under the provider's own name.
13
+ # Variables: SHEPHERD_MODEL (optional provider/model, over models.loop), AWS_REGION (Bedrock).
14
+ # Settings: ci.audit.plays and ci.audit.public in .shepherd/config.yml.
17
15
  name: shepherd-audit
18
16
  on:
19
17
  schedule:
@@ -21,7 +19,7 @@ on:
21
19
  workflow_dispatch:
22
20
  inputs:
23
21
  plays:
24
- description: Plays to run, space-separated (empty = ci.audit.plays, AUDIT_PLAYS, or the default)
22
+ description: Plays to run, space-separated (empty = ci.audit.plays, or the default)
25
23
  required: false
26
24
 
27
25
  permissions: {}
@@ -54,8 +52,6 @@ jobs:
54
52
  SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
55
53
  GH_TOKEN: ${{ github.token }} # gh api, for a github: pack the policy extends
56
54
  AWS_REGION: ${{ vars.AWS_REGION }}
57
- AUDIT_PLAYS: ${{ vars.AUDIT_PLAYS }}
58
- AUDIT_PUBLIC: ${{ vars.AUDIT_PUBLIC }}
59
55
  run: |
60
56
  bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
61
57
  "$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
@@ -112,7 +108,6 @@ jobs:
112
108
  timeout-minutes: 45 # opencode retries a provider error (an exhausted quota) silently; fail instead of holding the queue
113
109
  env:
114
110
  GH_TOKEN: ${{ github.token }}
115
- SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
116
111
  OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
117
112
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
118
113
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
@@ -129,14 +124,11 @@ jobs:
129
124
  OPENCODE_DISABLE_PROJECT_CONFIG: "1" # the checkout's opencode.json, .opencode/ plugins and AGENTS.md stay out of the agent's config
130
125
  OPENCODE_DISABLE_AUTOUPDATE: "1"
131
126
  run: |
132
- # The team's models, from the default branch: the session model, the variable its key goes in, and the
127
+ # The team's models, from the default branch: the session model and the
133
128
  # OpenCode agents that carry the ladder and pins, so each runner gets its own model.
134
129
  plan=$(shepherd ci-models)
135
130
  model=$(jq -r .model <<<"$plan")
136
131
  echo "session model: $model ($(jq -r .source <<<"$plan"))"
137
- key_env=$(jq -r '.key_env // empty' <<<"$plan")
138
- if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
139
- unset SHEPHERD_API_KEY
140
132
  # Only the keys the plan's models read reach the model, and a blank one (an unset secret) would hide the
141
133
  # provider's other credentials.
142
134
  keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
@@ -197,7 +189,7 @@ jobs:
197
189
  RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
198
190
  run: |
199
191
  if [ "$PRIVATE" != "true" ]; then
200
- echo "Public repository (AUDIT_PUBLIC): the report is in the run's shepherd-audit artifact ($RUN_URL)." >> "$GITHUB_STEP_SUMMARY"
192
+ echo "Public repository (ci.audit.public): the report is in the run's shepherd-audit artifact ($RUN_URL)." >> "$GITHUB_STEP_SUMMARY"
201
193
  exit 0
202
194
  fi
203
195
  # The header came out of a job a model ran in: one line with the automated prefix, or the default.
@@ -1,5 +1,5 @@
1
1
  # shepherd incident in CI: a red run on main, or an error sent in by hand or by an alerting tool, becomes an
2
- # incident issue, a reproducing test and a fix PR. The PR then goes through CI, stamp and the shepherd
2
+ # incident issue, a reproducing test and a fix PR. The PR then goes through CI, gate and the shepherd
3
3
  # workflow like any other. Installed by `shepherd workflows`.
4
4
  #
5
5
  # Triggers:
@@ -12,13 +12,13 @@
12
12
  # The signal is untrusted text (alert payloads carry user input), so the agent's job can read the repo and
13
13
  # file issues, nothing more: no contents write, no credential in its checkout. It hands its commit over as a
14
14
  # git bundle; the `open` job, which runs no model, pushes only an `incident/<n>` branch that builds on the
15
- # default branch and changes nothing outside INCIDENT_PATHS (no workflows, manifests, lockfiles or config:
15
+ # default branch and changes nothing outside ci.incident_paths (no workflows, manifests, lockfiles or config:
16
16
  # CI on the PR installs and runs them), then opens the PR. The agent still holds the model key.
17
17
  #
18
- # Secrets: SHEPHERD_TOKEN (contents, pull requests: write) for `open`, so the fix PR starts CI and stamp;
19
- # with github.token the PR opens but no workflow runs on it. SHEPHERD_API_KEY (or the provider's own key) for the model.
20
- # Variables: SHEPHERD_MODEL (optional override of the team's models.loop in .shepherd/config.yml, else its top rung), AWS_REGION (Bedrock),
21
- # INCIDENT_PATHS (ci.incident_paths in .shepherd/config.yml; the variable overrides it; empty = ^src/).
18
+ # Secrets: SHEPHERD_TOKEN (contents, pull requests: write) for `open`, so the fix PR starts CI and gate;
19
+ # with github.token the PR opens but no workflow runs on it. the model key, under the provider's own name.
20
+ # Variables: SHEPHERD_MODEL (optional provider/model, over models.loop), AWS_REGION (Bedrock).
21
+ # Settings: ci.incident_paths in .shepherd/config.yml (empty = ^src/).
22
22
  name: shepherd-incident
23
23
  on:
24
24
  workflow_run:
@@ -89,7 +89,6 @@ jobs:
89
89
  timeout-minutes: 20 # opencode retries a provider error (an exhausted quota) silently; fail instead of holding the queue
90
90
  env:
91
91
  GH_TOKEN: ${{ github.token }}
92
- SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
93
92
  OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
94
93
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
95
94
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
@@ -107,15 +106,12 @@ jobs:
107
106
  OPENCODE_DISABLE_AUTOUPDATE: "1"
108
107
  HANDOFF: ${{ runner.temp }}/handoff
109
108
  run: |
110
- # The team's models, from the default branch: the session model, the variable its key goes in, and the
109
+ # The team's models, from the default branch: the session model and the
111
110
  # OpenCode agents that carry the ladder and pins, so each runner gets its own model.
112
111
  plan=$(shepherd ci-models)
113
112
  AWS_REGION=$(shepherd ci-settings | jq -r .aws_region.value) && export AWS_REGION # ci.aws_region, or the variable
114
113
  model=$(jq -r .model <<<"$plan")
115
114
  echo "session model: $model ($(jq -r .source <<<"$plan"))"
116
- key_env=$(jq -r '.key_env // empty' <<<"$plan")
117
- if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
118
- unset SHEPHERD_API_KEY
119
115
  # Only the keys the plan's models read reach the model, and a blank one (an unset secret) would hide the
120
116
  # provider's other credentials.
121
117
  keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
@@ -166,7 +162,6 @@ jobs:
166
162
  env:
167
163
  SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
168
164
  GH_TOKEN: ${{ github.token }} # gh api, for a github: pack the policy extends
169
- INCIDENT_PATHS: ${{ vars.INCIDENT_PATHS }}
170
165
  run: |
171
166
  bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
172
167
  "$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
@@ -1,5 +1,5 @@
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
1
+ # shepherd in CI: one loop iteration each time CI or gate finishes on a PR, on a `/shepherd` comment,
2
+ # when a PR gets the ci.label label, or from the sweep. Each iteration's fixes are pushed, CI and gate run
3
3
  # on the new head, and their completion starts the next one, until shepherd sets a final `shepherd` status
4
4
  # (success, or failure naming what the author must do). Installed by `shepherd workflows`.
5
5
  #
@@ -12,36 +12,29 @@
12
12
  # Secrets:
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
- # 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.
18
- # Or each provider's own secret (OPENCODE_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY,
19
- # DEEPSEEK_API_KEY, AWS_BEARER_TOKEN_BEDROCK...) when the ladder mixes providers.
15
+ # the model key, under the provider's own name (OPENCODE_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY,
16
+ # OPENROUTER_API_KEY, DEEPSEEK_API_KEY, AWS_BEARER_TOKEN_BEDROCK...). Store it as an environment's
17
+ # secret (`shepherd workflows --environment <name>`) so only `iterate` reads it.
20
18
  # SHEPHERD_NOTIFY_WEBHOOK optional: Slack Incoming Webhook or any JSON endpoint, told when a PR needs
21
19
  # 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
+ # Settings live in .shepherd/config.yml (models.loop, and ci: label, aws_region, notify_on, max_commits,
21
+ # push_deny), reviewed and read from the default branch; `shepherd config explain` lists each with its source.
25
22
  # Variables:
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
28
- # team's models.loop, else the top of its ladder, else opencode-go/kimi-k3. Runners take
29
- # their own models from the team's tiers, ladder and pins (shepherd models shows them).
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
32
- # Code, Codex, another agent) hands one over by adding it.
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.
23
+ # SHEPHERD_MODEL optional: provider/model for this repository (e.g. opencode-go/deepseek-v4.1-flash,
24
+ # anthropic/claude-sonnet-5.5, amazon-bedrock/eu.amazon.nova-pro-v1:0), over models.loop.
25
+ # AWS_REGION the Bedrock region, for a Bedrock model.
35
26
  # SHEPHERD_PUSH_DENY replaces the built-in deny list (an admin's escape hatch). ci.push_deny in config can only
36
27
  # ADD patterns to whichever list applies. Extended regex of paths a handed-off fix may not touch; empty = workflows,
37
28
  # git and editor hooks, package manager config, manifests and lockfiles.
38
29
  #
39
- # Edit `workflows: [ci, stamp]` to name your CI workflow. workflow_run, pull_request_target and schedule
30
+ # Edit `workflows: [ci, shepherd-gate]` to name your CI workflow. workflow_run, pull_request_target and schedule
40
31
  # run this file from the default branch, so a PR cannot change how it is shepherded.
41
32
  name: shepherd
33
+ # The PR in each run's title, so `shepherd review <pr>` finds its run among other PRs'.
34
+ run-name: shepherd ${{ github.event.workflow_run.pull_requests[0].number || github.event.issue.number || github.event.pull_request.number || inputs.pr || github.event_name }}
42
35
  on:
43
36
  workflow_run:
44
- workflows: [ci, stamp]
37
+ workflows: [ci, shepherd-gate]
45
38
  types: [completed]
46
39
  issue_comment:
47
40
  types: [created]
@@ -100,10 +93,7 @@ jobs:
100
93
  id: settings
101
94
  env:
102
95
  SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
103
- SHEPHERD_LABEL: ${{ vars.SHEPHERD_LABEL }}
104
96
  AWS_REGION: ${{ vars.AWS_REGION }}
105
- SHEPHERD_NOTIFY_ON: ${{ vars.SHEPHERD_NOTIFY_ON }}
106
- SHEPHERD_MAX_COMMITS: ${{ vars.SHEPHERD_MAX_COMMITS }}
107
97
  run: |
108
98
  bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
109
99
  "$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
@@ -133,8 +123,7 @@ jobs:
133
123
  && github.event.workflow_run.head_repository.full_name == github.repository)
134
124
  || (github.event_name == 'issue_comment' && github.event.issue.pull_request != null
135
125
  && startsWith(github.event.comment.body, '/shepherd'))
136
- || (github.event_name == 'pull_request_target'
137
- && (vars.SHEPHERD_LABEL == '' || github.event.label.name == vars.SHEPHERD_LABEL))
126
+ || github.event_name == 'pull_request_target'
138
127
  || github.event_name == 'workflow_dispatch'
139
128
  runs-on: ubuntu-latest
140
129
  timeout-minutes: 5
@@ -170,10 +159,7 @@ jobs:
170
159
  env:
171
160
  GH_TOKEN: ${{ github.token }} # gh api, for a github: pack the policy extends
172
161
  SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
173
- SHEPHERD_LABEL: ${{ vars.SHEPHERD_LABEL }}
174
162
  AWS_REGION: ${{ vars.AWS_REGION }}
175
- SHEPHERD_NOTIFY_ON: ${{ vars.SHEPHERD_NOTIFY_ON }}
176
- SHEPHERD_MAX_COMMITS: ${{ vars.SHEPHERD_MAX_COMMITS }}
177
163
  run: |
178
164
  bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
179
165
  "$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
@@ -295,6 +281,13 @@ jobs:
295
281
  git config user.name "$GIT_NAME"
296
282
  git config user.email "$GIT_EMAIL"
297
283
  mkdir -p "$RUNNER_TEMP/handoff"
284
+ # A note on the PR while the model works; the finalizer deletes it. Cosmetic, so it never fails the job.
285
+ - name: Show that shepherd is reviewing
286
+ continue-on-error: true
287
+ env:
288
+ GH_TOKEN: ${{ github.token }}
289
+ H0: ${{ needs.gate.outputs.head }}
290
+ run: shepherd working --pr "$PR" --repo "$GITHUB_REPOSITORY" --head "$H0"
298
291
  - name: One shepherd iteration
299
292
  timeout-minutes: 30 # opencode retries a provider error (an exhausted quota) silently; fail instead of holding the queue
300
293
  env:
@@ -302,7 +295,6 @@ jobs:
302
295
  SHEPHERD_HANDOFF: ${{ runner.temp }}/handoff
303
296
  SHEPHERD_FANOUT: ${{ runner.temp }}/fanout.json
304
297
  BASE: ${{ needs.gate.outputs.base }}
305
- SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
306
298
  OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
307
299
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
308
300
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
@@ -319,14 +311,11 @@ jobs:
319
311
  OPENCODE_DISABLE_PROJECT_CONFIG: "1" # the checkout's opencode.json, .opencode/ plugins and AGENTS.md are PR content
320
312
  OPENCODE_DISABLE_AUTOUPDATE: "1"
321
313
  run: |
322
- # The team's models, from the default branch: the session model, the variable its key goes in, and the
314
+ # The team's models, from the default branch: the session model and the
323
315
  # OpenCode agents that carry the ladder and pins, so each runner gets its own model.
324
316
  plan=$(shepherd ci-models)
325
317
  model=$(jq -r .model <<<"$plan")
326
318
  echo "session model: $model ($(jq -r .source <<<"$plan"))"
327
- key_env=$(jq -r '.key_env // empty' <<<"$plan")
328
- if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
329
- unset SHEPHERD_API_KEY
330
319
  # Only the keys the plan's models read reach the model, and a blank one (an unset secret) would hide the
331
320
  # provider's other credentials.
332
321
  keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
@@ -347,7 +336,7 @@ jobs:
347
336
  yourself. You are running in GitHub Actions on the PR branch,
348
337
  already checked out, and you cannot push. Nobody is watching this session: never wait for an answer. Anything you
349
338
  would ask the user is deferred, listed in the iteration summary, and named in status.json. Do not schedule further
350
- iterations; the next one starts when CI or stamp finishes on the head the workflow pushes."
339
+ iterations; the next one starts when CI or gate finishes on the head the workflow pushes."
351
340
  # The job checks the round itself. A round that does not render gets one short call with the exact errors.
352
341
  round="$SHEPHERD_HANDOFF/round.json"
353
342
  if [ -f "$round" ] && ! errors=$(shepherd summary "$round" --body 2>&1 >/dev/null); then
@@ -482,7 +471,7 @@ jobs:
482
471
  elif state == "pending":
483
472
  # Nothing pushed and no CI re-run asked for: findings above NIT leave work for the author, so the status
484
473
  # is failure and the sweep, which re-runs pending PRs every half hour, leaves the PR to them. Otherwise it
485
- # stays pending: success needs stamp's approval, green CI and no open thread, which this step cannot see.
474
+ # stays pending: success needs gate's approval, green CI and no open thread, which this step cannot see.
486
475
  try:
487
476
  reruns = open("handoff/rerun-jobs.txt").read().strip() not in ("", "[]")
488
477
  except OSError:
@@ -507,7 +496,7 @@ jobs:
507
496
  echo "state=$state" >> "$GITHUB_OUTPUT"
508
497
  # Under suggest, posting is the review. If the iteration ended without its summary on the PR, post the findings it
509
498
  # handed off. findings.md is model output: capped, its markers and HTML comments escaped (it must not pass for a
510
- # stamp or shepherd comment), mentions and images defused, and built into the body in Python, never by the shell.
499
+ # gate or shepherd comment), mentions and images defused, and built into the body in Python, never by the shell.
511
500
  # The renderers, when the iteration handed off its round: the summary and inline review are then built in code.
512
501
  - if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true' && hashFiles('handoff/round.json') != ''
513
502
  uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0: pinned, this job holds the write token
@@ -550,16 +539,18 @@ jobs:
550
539
  fi
551
540
  fi
552
541
  fanout=(); [ -f handoff/fanout.json ] && fanout=(--fanout ../handoff/fanout.json)
542
+ # The CLI's render is code, not model output: it posts as rendered, keeping the reviewed-head marker the next
543
+ # round's interdiff reads, and links each finding to its thread (rendered after the inline review posts).
553
544
  # A round the CLI cannot render keeps whatever findings.md the model wrote; with neither, say so and stop.
554
- if (cd repo && shepherd summary ../handoff/round.json --previous ../summary.md --body "${fanout[@]}") > rendered.md; then
555
- mv rendered.md handoff/findings.md
545
+ if (cd repo && shepherd summary ../handoff/round.json --previous ../summary.md "${fanout[@]}") > findings.out; then
546
+ rendered=1
556
547
  elif [ ! -f handoff/findings.md ]; then
557
548
  echo "::warning::could not render the round's summary, and the iteration left no findings.md"; exit 0
558
549
  fi
559
550
  else
560
551
  [ -n "$fresh" ] && grep -q "@ ${H0:0:7}" summary.md && { echo "the iteration posted its summary ($id)"; exit 0; }
561
552
  fi
562
- python3 - handoff/findings.md summary.md "${H0:0:7}" > findings.out <<'PY'
553
+ [ -n "${rendered:-}" ] || python3 - handoff/findings.md summary.md "${H0:0:7}" > findings.out <<'PY'
563
554
  import re, sys
564
555
  CAP = 60000
565
556
  def defuse(text):
@@ -613,6 +604,14 @@ jobs:
613
604
  SHEPHERD_NOTIFY_WEBHOOK: ${{ secrets.SHEPHERD_NOTIFY_WEBHOOK }}
614
605
  SHEPHERD_NOTIFY_ON: ${{ needs.gate.outputs.notify_on }} # ci.notify_on or the variable
615
606
  run: shepherd notify --pr "$PR" --repo "$GITHUB_REPOSITORY" --head "$HEAD_SHA" --state "$STATE" --file description.txt
607
+ - name: Remove the reviewing note
608
+ if: always()
609
+ continue-on-error: true
610
+ env:
611
+ GH_TOKEN: ${{ github.token }}
612
+ run: |
613
+ gh api "repos/$GITHUB_REPOSITORY/issues/$PR/comments" --paginate --jq '.[] | select(.user.login == "github-actions[bot]" and (.body | startswith("<!-- shepherd-working -->"))) | .id' |
614
+ while read -r id; do gh api -X DELETE "repos/$GITHUB_REPOSITORY/issues/comments/$id" >/dev/null; done
616
615
  # Any step above failing (checkout, push, status) must not leave the gate's pending for the sweep to rerun.
617
616
  - name: Report a failed publish
618
617
  if: always() && failure()