@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.9.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",
@@ -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 posts as on any PR.** Only the push credential is withheld. Swarm
100
- posts its inline comments and summary with the job's token, which has
101
- pull requests: write, under every fix mode. Under `suggest` posting is the
102
- whole review: a run that ends with findings and nothing on the PR has failed.
103
- Also write the summary body to `$SHEPHERD_HANDOFF/findings.md` with
104
- `shepherd summary round.json --previous summary.md --body`, `summary.md`
105
- being the summary already on the PR (swarm's Step 7 finds it), so the round
106
- number carries on. The publish job posts it only when no summary for this head reached the
107
- PR, so a failed post still leaves the review on the PR.
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
- > Post review comments as usual: only pushing is withheld. Never call the
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
@@ -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
- Post every inline finding as **one** review, pinned to the reviewed commit:
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
- shepherd summary round.json --previous summary.md --body > "$SHEPHERD_HANDOFF/findings.md" # the handoff copy: no marker, header or history
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.`, 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
 
@@ -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. You are running in GitHub Actions on the PR branch,
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
- ! grep -q "@ ${H0:0:7}" summary.md || { echo "the iteration posted its summary ($id)"; exit 0; }
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