@jagreehal/shepherd 0.9.0 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jagreehal/shepherd",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.0",
|
|
4
4
|
"description": "Agent skills that drive a PR to merge-ready: a review swarm, thread triage, CI repair, and a loop that hands the result to stamp.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": "github:jagreehal/shepherd",
|
package/skills/shepherd/SKILL.md
CHANGED
|
@@ -96,15 +96,15 @@ credential: the CI workflow (`templates/shepherd.yml`) runs the model with a
|
|
|
96
96
|
token that can comment and read but not write code, and a later job with no
|
|
97
97
|
model pushes what you hand it. An iteration then differs in six places:
|
|
98
98
|
|
|
99
|
-
- **Swarm
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
99
|
+
- **Swarm hands its round off instead of posting it.** Write the round JSON
|
|
100
|
+
(swarm's `references/formats.md`) to `$SHEPHERD_HANDOFF/round.json` and post
|
|
101
|
+
neither the inline review nor the summary: the publish job, which runs no
|
|
102
|
+
model, renders both with `shepherd inline` and `shepherd summary` and posts
|
|
103
|
+
them, the summary carrying on the round number of the one already on the PR.
|
|
104
|
+
A model that wrote review Markdown itself once posted bare comments with no
|
|
105
|
+
header, title or prompt. Under `suggest` the review is the whole output: a
|
|
106
|
+
run that ends with findings and no `round.json` has failed. Threads still
|
|
107
|
+
resolve and triage still runs with the job's token as before.
|
|
108
108
|
|
|
109
109
|
- **Commit, never push.** Commit on the PR branch as usual. Append the handoff
|
|
110
110
|
addition from `references/dispatch.md` to every runner brief. After a runner,
|
|
@@ -95,7 +95,9 @@ Append to every brief when `SHEPHERD_HANDOFF` is set (`../SKILL.md`, Handoff
|
|
|
95
95
|
mode):
|
|
96
96
|
|
|
97
97
|
> Handoff mode: this session cannot push, and a later job pushes your commits.
|
|
98
|
-
>
|
|
98
|
+
> Swarm writes its round to `$SHEPHERD_HANDOFF/round.json` and posts no review
|
|
99
|
+
> or summary: the publish job renders and posts both. Other comments and
|
|
100
|
+
> replies post as usual: only pushing is withheld. Never call the
|
|
99
101
|
> statuses API; the workflow sets the status. Commit, never push. Resolve no thread; the next iteration does once the fix
|
|
100
102
|
> is pushed. Never run `gh pr update-branch`: to update the branch, merge
|
|
101
103
|
> `origin/<base>` locally and commit the merge with your trailer. Never run
|
package/skills/swarm/SKILL.md
CHANGED
|
@@ -252,7 +252,11 @@ These become `CHECK_FINDINGS`. They post like any other finding, tagged
|
|
|
252
252
|
missing or fails to start, record `checks: <tool> unavailable (<reason>)` and
|
|
253
253
|
move on; the report's Checks section names each as `checks skipped: <tool>
|
|
254
254
|
(<reason>)`, and a round where a check the repository configures did not run
|
|
255
|
-
is never reported clean.
|
|
255
|
+
is never reported clean. "Fails to start" includes a runner that cannot load
|
|
256
|
+
its own config or dependencies (`Startup Error`, `Cannot find module`), a
|
|
257
|
+
`tsc` that cannot resolve the test framework's types, and dependencies never
|
|
258
|
+
installed: that is `unavailable`, never "ran, 0 findings". A trial reported
|
|
259
|
+
"test ✅, typecheck ✅" over `Cannot find module 'vite-plus'`.
|
|
256
260
|
|
|
257
261
|
## Step 3: First wave
|
|
258
262
|
|
|
@@ -449,7 +453,8 @@ The verdict is advice to the author. It never becomes a GitHub approval.
|
|
|
449
453
|
|
|
450
454
|
Write the round as JSON first (`references/formats.md`): the inline review and
|
|
451
455
|
the summary are both rendered from it, so neither is ever hand-written Markdown.
|
|
452
|
-
|
|
456
|
+
With `$SHEPHERD_HANDOFF` set, write it to `$SHEPHERD_HANDOFF/round.json` and
|
|
457
|
+
stop here: the publish job renders and posts both. Otherwise post every inline finding as **one** review, pinned to the reviewed commit:
|
|
453
458
|
|
|
454
459
|
```bash
|
|
455
460
|
shepherd inline round.json > review.json
|
|
@@ -73,7 +73,7 @@ Never write the summary's Markdown yourself. Write the round as JSON and let
|
|
|
73
73
|
|
|
74
74
|
```bash
|
|
75
75
|
shepherd summary round.json --previous summary.md > comment.md # --previous: the comment already on the PR, if any
|
|
76
|
-
|
|
76
|
+
cp round.json "$SHEPHERD_HANDOFF/round.json" # handoff mode: post nothing; the publish job renders and posts both
|
|
77
77
|
```
|
|
78
78
|
|
|
79
79
|
`findings` holds the current round only, with a convergent finding's `lens`
|
package/src/summary.ts
CHANGED
|
@@ -291,6 +291,6 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string) {
|
|
|
291
291
|
return comment;
|
|
292
292
|
});
|
|
293
293
|
|
|
294
|
-
return { commit_id: s.head_sha, event: "COMMENT" as const, body: `${header}\n\nSee inline comments
|
|
294
|
+
return { commit_id: s.head_sha, event: "COMMENT" as const, body: `${header}\n\nSee inline comments.\n<!-- shepherd-inline @ ${s.head_sha.slice(0, 7)} -->`, comments }; // the marker: publish posts no second review for this head
|
|
295
295
|
}
|
|
296
296
|
|
package/templates/shepherd.yml
CHANGED
|
@@ -337,9 +337,12 @@ jobs:
|
|
|
337
337
|
shepherd fanout --base "origin/$BASE" > "$SHEPHERD_FANOUT" || echo "::warning::a team lens resolves nowhere; see above"
|
|
338
338
|
jq -e --arg h "$(git rev-parse HEAD)" '.head_sha == $h and any(.lenses[]; .lens == "correctness")' "$SHEPHERD_FANOUT" >/dev/null \
|
|
339
339
|
|| { echo "::error::shepherd fanout wrote no usable lens list for this head"; exit 1; }
|
|
340
|
+
# A copy for the publish job, which renders the summary: a first-wave lens the round never reports shows as could_not_run.
|
|
341
|
+
mkdir -p "$SHEPHERD_HANDOFF" && cp "$SHEPHERD_FANOUT" "$SHEPHERD_HANDOFF/fanout.json"
|
|
340
342
|
opencode run --auto -m "$model" --title "shepherd #$PR" "Load the shepherd skill and run exactly one iteration on PR $PR in handoff mode:
|
|
341
343
|
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.
|
|
344
|
+
the router and every lens listed there in one message. Write the round to $SHEPHERD_HANDOFF/round.json: the publish
|
|
345
|
+
job renders and posts the inline review and the summary from it, so post neither yourself. You are running in GitHub Actions on the PR branch,
|
|
343
346
|
already checked out, and you cannot push. Nobody is watching this session: never wait for an answer. Anything you
|
|
344
347
|
would ask the user is deferred, listed in the iteration summary, and named in status.json. Do not schedule further
|
|
345
348
|
iterations; the next one starts when CI or stamp finishes on the head the workflow pushes."
|
|
@@ -475,8 +478,18 @@ jobs:
|
|
|
475
478
|
# Under suggest, posting is the review. If the iteration ended without its summary on the PR, post the findings it
|
|
476
479
|
# handed off. findings.md is model output: capped, its markers and HTML comments escaped (it must not pass for a
|
|
477
480
|
# stamp or shepherd comment), mentions and images defused, and built into the body in Python, never by the shell.
|
|
481
|
+
# The renderers, when the iteration handed off its round: the summary and inline review are then built in code.
|
|
482
|
+
- if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true' && hashFiles('handoff/round.json') != ''
|
|
483
|
+
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0: pinned, this job holds the write token
|
|
484
|
+
continue-on-error: true # without the CLI the step below falls back to findings.md
|
|
485
|
+
- if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true' && hashFiles('handoff/round.json') != ''
|
|
486
|
+
shell: bash
|
|
487
|
+
continue-on-error: true
|
|
488
|
+
run: |
|
|
489
|
+
bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
|
|
490
|
+
echo "$HOME/.bun/bin" >> "$GITHUB_PATH"
|
|
478
491
|
- name: Post findings the iteration did not
|
|
479
|
-
if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true' && hashFiles('handoff/findings.md') != ''
|
|
492
|
+
if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true' && (hashFiles('handoff/findings.md') != '' || hashFiles('handoff/round.json') != '')
|
|
480
493
|
env:
|
|
481
494
|
GH_TOKEN: ${{ github.token }}
|
|
482
495
|
run: |
|
|
@@ -485,7 +498,23 @@ jobs:
|
|
|
485
498
|
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
499
|
id=$(jq -r .id summary.json)
|
|
487
500
|
jq -r .body summary.json > summary.md
|
|
488
|
-
|
|
501
|
+
# Posted by this run, not an earlier one on the same head: a summary from a previous round on an unchanged head
|
|
502
|
+
# once passed for this round's and the round was never posted.
|
|
503
|
+
started=${RUN_STARTED:-$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --jq .run_started_at)}
|
|
504
|
+
fresh=$(jq -r --arg s "$started" 'select((.updated_at // "") >= $s) | .id' summary.json)
|
|
505
|
+
if [ -f handoff/round.json ] && command -v shepherd >/dev/null; then
|
|
506
|
+
# The inline review, from the round JSON, unless one rendered for this head is already on the PR.
|
|
507
|
+
if ! gh api "repos/$GITHUB_REPOSITORY/pulls/$PR/reviews" --paginate --jq ".[] | select(.user.login == \"github-actions[bot]\" and (.body | contains(\"<!-- shepherd-inline @ ${H0:0:7} -->\"))) | .id" | grep -q .; then
|
|
508
|
+
(cd repo && shepherd inline ../handoff/round.json) > review.json \
|
|
509
|
+
&& [ "$(jq '.comments | length' review.json)" -gt 0 ] \
|
|
510
|
+
&& gh api "repos/$GITHUB_REPOSITORY/pulls/$PR/reviews" --method POST --input review.json >/dev/null \
|
|
511
|
+
|| echo "::warning::could not post the rendered inline review"
|
|
512
|
+
fi
|
|
513
|
+
fanout=(); [ -f handoff/fanout.json ] && fanout=(--fanout ../handoff/fanout.json)
|
|
514
|
+
(cd repo && shepherd summary ../handoff/round.json --previous ../summary.md --body "${fanout[@]}") > rendered.md && mv rendered.md handoff/findings.md
|
|
515
|
+
else
|
|
516
|
+
[ -n "$fresh" ] && grep -q "@ ${H0:0:7}" summary.md && { echo "the iteration posted its summary ($id)"; exit 0; }
|
|
517
|
+
fi
|
|
489
518
|
python3 - handoff/findings.md summary.md "${H0:0:7}" > findings.out <<'PY'
|
|
490
519
|
import re, sys
|
|
491
520
|
CAP = 60000
|