@jagreehal/shepherd 0.11.0 → 0.12.1

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.11.0",
3
+ "version": "0.12.1",
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",
@@ -463,8 +463,8 @@ new side of the diff.
463
463
  P1 counts as HIGH). A gate that refused this head for an issue the code still
464
464
  has counts too:
465
465
  - any CRITICAL -> `emoji.blocked` (🚫) BLOCKED
466
- - 2+ HIGH, or 1 HIGH + 2 MEDIUM -> `emoji.changes_needed` (⚠️) CHANGES NEEDED
467
- - 1 HIGH, or any MEDIUM -> `emoji.approve_with_nits` (💬) APPROVE WITH NITS
466
+ - any HIGH -> `emoji.changes_needed` (⚠️) CHANGES NEEDED
467
+ - any MEDIUM -> `emoji.approve_with_nits` (💬) APPROVE WITH NITS
468
468
  - only LOW, NIT, or nothing -> `emoji.looks_good` (✅) LOOKS GOOD
469
469
 
470
470
  The verdict is advice to the author. It never becomes a GitHub approval.
@@ -473,8 +473,19 @@ The verdict is advice to the author. It never becomes a GitHub approval.
473
473
 
474
474
  Write the round as JSON first (`references/formats.md`): the inline review and
475
475
  the summary are both rendered from it, so neither is ever hand-written Markdown.
476
- With `$SHEPHERD_HANDOFF` set, write it to `$SHEPHERD_HANDOFF/round.json` and
477
- stop here: the publish job renders and posts both. Otherwise post every inline finding as **one** review, pinned to the reviewed commit:
476
+ With `$SHEPHERD_HANDOFF` set, write it to `$SHEPHERD_HANDOFF/round.json`,
477
+ then check it before you stop:
478
+
479
+ ```bash
480
+ shepherd summary "$SHEPHERD_HANDOFF/round.json" --body > /dev/null
481
+ ```
482
+
483
+ It prints every field the renderer rejects. Fix `round.json` and run it again
484
+ until it prints nothing. The round is its own shape (`references/formats.md`):
485
+ not the Step 8 report (`posted`, `counts`, `narration`) and not the local
486
+ record (`stages`, `candidates`). `verdict` is `blocked`, `changes`, `nits` or
487
+ `good`; `verified` is the text of what the verifier checked. Then stop: the
488
+ publish job renders and posts both. Otherwise post every inline finding as **one** review, pinned to the reviewed commit:
478
489
 
479
490
  ```bash
480
491
  shepherd inline round.json > review.json
@@ -85,13 +85,15 @@ change has a flow a reader would otherwise reconstruct (a request path, a state
85
85
  machine, data moving between modules); leave it empty for a helper function.
86
86
  The new fields are optional: a round without them renders as before.
87
87
  The renderers hold the round to what they can check. A `url`, `reintroduces`
88
- or still-open link that names no review comment on the PR loses its link.
88
+ or still-open link that names no review comment on the PR, or is not a
89
+ GitHub URL, loses its link.
89
90
  `convergent` needs a tag naming two lenses (`a + b`). A finding above NIT with
90
91
  neither `verified` nor `checked` is shown as unverified, `checks/*` findings
91
92
  aside. A HIGH or CRITICAL with no `evidence` is graded MEDIUM, `checks/*`
92
93
  findings aside, and says so. A `verdict` milder than the findings allow by
93
94
  Step 6's rule is raised to the stricter one, and `why` says so. A lens that
94
- did not finish marks the round incomplete. An inline finding whose line is
95
+ did not finish marks the round incomplete. A lens's take is the worst
96
+ severity among the findings its tag names, when any do. An inline finding whose line is
95
97
  past the end of its file stays in the summary. So give each thread
96
98
  link a review comment's `html_url` (`#discussion_r<id>`), and an issue comment's
97
99
  never.
@@ -107,7 +109,7 @@ title: findings, numbered and linked to their threads (open unless the
107
109
  verdict is LOOKS GOOD), one agent prompt holding every finding above NIT, the
108
110
  walkthrough (bullets, a file table, review effort, the diagram), still open,
109
111
  checks, lenses, and earlier rounds folded one line each. With `--fanout` (in CI,
110
- `$SHEPHERD_FANOUT`), a first-wave lens the round does not report shows as
112
+ `$SHEPHERD_FANOUT`), the router or a first-wave lens the round does not report shows as
111
113
  `could_not_run` and the round says it is incomplete. With `--body` it keeps the
112
114
  round number but leaves the history out: the publish job folds the comment it
113
115
  replaces in itself, so the history would otherwise appear twice. It escapes markers, mentions
package/src/summary.ts CHANGED
@@ -2,6 +2,7 @@
2
2
  * Swarm's summary comment, rendered in code from the round's JSON. The comment keeps the same shape every round, so a
3
3
  * reader scans one line per section and garden parses the heading. Every model-written string is defused here.
4
4
  */
5
+ import { createHash } from "node:crypto";
5
6
  import { z } from "zod";
6
7
  import type { BRANDING } from "./config.ts";
7
8
 
@@ -9,6 +10,14 @@ const Severity = z.enum(["CRITICAL", "HIGH", "MEDIUM", "LOW", "NIT"]);
9
10
 
10
11
  const THREAD_URL = /^https:\/\/github\.com\/[\w./#-]+$/;
11
12
 
13
+ // A model writing the round borrows words from swarm's other JSON shapes (the Step 8 report, the local record):
14
+ // `changes_needed`, `skipped`, `verified: true`. Each maps onto the round's own value, so a near miss still renders.
15
+ const alias = (table: Record<string, string>) => (v: string) => table[v.trim().toLowerCase().replaceAll(/[\s-]+/g, "_")] ?? v;
16
+
17
+ const VERDICT_ALIAS = alias({ changes_needed: "changes", approve_with_nits: "nits", looks_good: "good", approve: "good", approved: "good" });
18
+
19
+ const STATUS_ALIAS = alias({ success: "ok", done: "ok", completed: "ok", complete: "ok", passed: "ok", error: "failed", errored: "failed", skipped: "could_not_run", not_run: "could_not_run", did_not_run: "could_not_run", missing: "could_not_run" });
20
+
12
21
  const Finding = z.object({
13
22
  file: z.string().default(""),
14
23
  line: z
@@ -26,8 +35,10 @@ const Finding = z.object({
26
35
  convergent: z.boolean().default(false),
27
36
  // A reader triages by the title alone: a claim they can check, such as "`firstName` returns the second word".
28
37
  title: z.string().default(""),
29
- url: z.string().regex(THREAD_URL).optional(), // the finding's inline thread, linked from the summary
30
- verified: z.string().default(""), // what the verifier checked, quoted code included
38
+ // A thread link that is not a GitHub URL is dropped and the finding kept.
39
+ url: z.string().regex(THREAD_URL).optional().catch(undefined), // the finding's inline thread, linked from the summary
40
+ // What the verifier checked, quoted code included. A bare `true` carries no evidence, so it reads as unverified.
41
+ verified: z.union([z.string(), z.boolean().transform(() => "")]).default(""),
31
42
  // The claim made checkable: an input, what the code should do on it, and what it does.
32
43
  evidence: z.object({ input: z.string().min(1), expected: z.string().min(1), actual: z.string().min(1) }).optional(),
33
44
  suggestion: z.string().optional(), // replacement for exactly the lines the comment covers: GitHub's one-click commit
@@ -35,13 +46,13 @@ const Finding = z.object({
35
46
  // The read-only commands the reviewer or verifier ran to check it.
36
47
  checked: z.array(z.object({ command: z.string(), result: z.string() })).default([]),
37
48
  docs: z.array(z.object({ url: z.string().regex(/^https:\/\/[^\s()<>`]+$/), title: z.string() })).default([]), // the documentation the claim rests on
38
- reintroduces: z.string().regex(THREAD_URL).optional(), // a resolved thread whose fix this change undoes
49
+ reintroduces: z.string().regex(THREAD_URL).optional().catch(undefined), // a resolved thread whose fix this change undoes
39
50
  });
40
51
 
41
52
  export const SummaryInput = z.object({
42
53
  head_sha: z.string().regex(/^[0-9a-f]{7,40}$/),
43
- verdict: z.enum(["blocked", "changes", "nits", "good"]),
44
- why: z.string(),
54
+ verdict: z.string().transform(VERDICT_ALIAS).pipe(z.enum(["blocked", "changes", "nits", "good"])),
55
+ why: z.string().default(""),
45
56
  confidence: z.number().int().min(0).max(5).optional(), // how safe to merge, 5 safest
46
57
  findings: z.array(Finding).default([]),
47
58
  walkthrough: z.array(z.string()).default([]), // what the PR does, a few bullets for a reader who never saw it
@@ -50,9 +61,16 @@ export const SummaryInput = z.object({
50
61
  diagram: z.string().default(""), // mermaid flowchart source, when the change has a flow worth drawing
51
62
  // Pre-merge checks: do the title, description, linked issue and scope match the diff.
52
63
  pre_merge: z.array(z.object({ check: z.string(), status: z.enum(["pass", "warn", "fail"]), detail: z.string() })).default([]),
53
- still_open: z.array(z.object({ url: z.string().regex(THREAD_URL), title: z.string() })).default([]),
64
+ still_open: z.array(z.object({ url: z.string().regex(THREAD_URL).catch(""), title: z.string() })).default([]), // "" renders the title alone
54
65
  checks: z.array(z.object({ tool: z.string(), status: z.enum(["ran", "unavailable"]), findings: z.number().default(0), reason: z.string().optional() })).default([]),
55
- lenses: z.array(z.object({ lens: z.string(), model: z.string().default(""), scope: z.union([z.string(), z.array(z.string())]).default("full"), status: z.enum(["ok", "failed", "could_not_run"]), take: z.string().default(""), skill_blob: z.string().default("") })).default([]),
66
+ lenses: z
67
+ .array(
68
+ z
69
+ .object({ lens: z.string(), model: z.string().default(""), scope: z.union([z.string(), z.array(z.string())]).default("full"), status: z.string().transform(STATUS_ALIAS).pipe(z.enum(["ok", "failed", "could_not_run"])), take: z.string().default(""), reason: z.string().default(""), skill_blob: z.string().default("") })
70
+ // A lens skipped "with a reason", as the local record writes it, keeps the reason as its take.
71
+ .transform(({ reason, ...l }) => ({ ...l, take: l.take || reason })),
72
+ )
73
+ .default([]),
56
74
  lenses_yml_blob: z.string().default(""),
57
75
  });
58
76
 
@@ -146,9 +164,10 @@ function verdictFloor(findings: { severity: z.infer<typeof Severity> }[]): keyof
146
164
 
147
165
  if (n("CRITICAL")) return "blocked";
148
166
 
149
- if (n("HIGH") >= 2 || (n("HIGH") === 1 && n("MEDIUM") >= 2)) return "changes";
167
+ // A HIGH that survives checkedRound names an input the code gets wrong, or is a failing check.
168
+ if (n("HIGH")) return "changes";
150
169
 
151
- return n("HIGH") || n("MEDIUM") ? "nits" : "good";
170
+ return n("MEDIUM") ? "nits" : "good";
152
171
  }
153
172
 
154
173
  const STRICTNESS = ["good", "nits", "changes", "blocked"] as const;
@@ -189,6 +208,14 @@ export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>) {
189
208
  return s;
190
209
  }
191
210
 
211
+ /** The worst severity among the findings whose tag names the lens (`correctness/data`, `correctness + security`), and how many. */
212
+ function lensTake(lens: string, findings: { lens: string; severity: z.infer<typeof Severity> }[]): string | undefined {
213
+ const mine = findings.filter((f) => f.lens.split(/[\s+/]+/).includes(lens));
214
+ const worst = SEVERITIES.find((sev) => mine.some((f) => f.severity === sev));
215
+
216
+ return worst && `${worst} (${mine.length})`;
217
+ }
218
+
192
219
  /** A finding above NIT that no verifier checked. */
193
220
  const unverified = (f: z.infer<typeof Finding>) => f.severity !== "NIT" && !fromChecks(f) && !f.verified && !f.checked.length;
194
221
 
@@ -202,8 +229,11 @@ export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string |
202
229
  // as could_not_run.
203
230
  const wave = fanout ? Fanout.parse(fanout) : null;
204
231
  const sameHead = wave !== null && (wave.head_sha.startsWith(s.head_sha) || s.head_sha.startsWith(wave.head_sha));
205
- const skipped = sameHead ? wave.lenses.filter((w) => !s.lenses.some((l) => l.lens === w.lens)) : [];
206
- const lenses = [...s.lenses, ...skipped.map((w) => ({ lens: w.lens, model: "", scope: w.scope, status: "could_not_run" as const, take: "listed by fanout, no result reported", skill_blob: "" }))];
232
+ // The router runs beside every first wave, so a round that leaves it out is missing a reviewer too.
233
+ const expected = sameHead ? [{ lens: "router", scope: "full" as const }, ...wave.lenses] : [];
234
+ const skipped = expected.filter((w) => !s.lenses.some((l) => l.lens === w.lens));
235
+ // A lens's take comes from the findings that name it, so it always agrees with them.
236
+ const lenses = [...s.lenses.map((l) => ({ ...l, take: lensTake(l.lens, s.findings) ?? l.take })), ...skipped.map((w) => ({ lens: w.lens, model: "", scope: w.scope, status: "could_not_run" as const, take: "listed by fanout, no result reported", skill_blob: "" }))];
207
237
  const [key, label] = VERDICT[s.verdict];
208
238
  const { round, history } = earlierRounds(previous);
209
239
  const sha = s.head_sha.slice(0, 7);
@@ -435,6 +465,10 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
435
465
  return comment;
436
466
  });
437
467
 
438
- 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
468
+ // The marker names the head and the comments: publish skips a review only when these same comments are already on
469
+ // the PR, so a new round on the same head posts its own.
470
+ const fingerprint = createHash("sha256").update(JSON.stringify(comments)).digest("hex").slice(0, 12);
471
+
472
+ 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)} ${fingerprint} -->`, comments };
439
473
  }
440
474
 
@@ -341,7 +341,8 @@ jobs:
341
341
  mkdir -p "$SHEPHERD_HANDOFF" && cp "$SHEPHERD_FANOUT" "$SHEPHERD_HANDOFF/fanout.json"
342
342
  opencode run --auto -m "$model" --title "shepherd #$PR" "Load the shepherd skill and run exactly one iteration on PR $PR in handoff mode:
343
343
  SHEPHERD_HANDOFF is set, so follow the skill's Handoff mode. Swarm's first wave is in $SHEPHERD_FANOUT: dispatch
344
- the router and every lens listed there in one message. Write the round to $SHEPHERD_HANDOFF/round.json: the publish
344
+ the router and every lens listed there in one message. Write the round to $SHEPHERD_HANDOFF/round.json and check it
345
+ with 'shepherd summary $SHEPHERD_HANDOFF/round.json --body > /dev/null', fixing every error it prints: the publish
345
346
  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,
346
347
  already checked out, and you cannot push. Nobody is watching this session: never wait for an answer. Anything you
347
348
  would ask the user is deferred, listed in the iteration summary, and named in status.json. Do not schedule further
@@ -503,15 +504,25 @@ jobs:
503
504
  started=${RUN_STARTED:-$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --jq .run_started_at)}
504
505
  fresh=$(jq -r --arg s "$started" 'select((.updated_at // "") >= $s) | .id' summary.json)
505
506
  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"
507
+ # The inline review, from the round JSON, unless these same comments are already on the PR: its marker names
508
+ # the head and a fingerprint of the comments, so a new round on an unchanged head still posts its own.
509
+ if ! (cd repo && shepherd inline ../handoff/round.json) > review.json; then
510
+ echo "::warning::could not render the inline review"
511
+ elif [ "$(jq '.comments | length' review.json)" -gt 0 ]; then
512
+ marker=$(jq -r .body review.json | grep -o '<!-- shepherd-inline @ [0-9a-f]* [0-9a-f]* -->' | tail -1)
513
+ if [ -n "$marker" ] && gh api "repos/$GITHUB_REPOSITORY/pulls/$PR/reviews" --paginate --jq '.[] | select(.user.login == "github-actions[bot]") | .body' | grep -F -- "$marker" >/dev/null; then
514
+ echo "this round's inline review is already on the PR"
515
+ else
516
+ gh api "repos/$GITHUB_REPOSITORY/pulls/$PR/reviews" --method POST --input review.json >/dev/null || echo "::warning::could not post the rendered inline review"
517
+ fi
512
518
  fi
513
519
  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
520
+ # A round the CLI cannot render keeps whatever findings.md the model wrote; with neither, say so and stop.
521
+ if (cd repo && shepherd summary ../handoff/round.json --previous ../summary.md --body "${fanout[@]}") > rendered.md; then
522
+ mv rendered.md handoff/findings.md
523
+ elif [ ! -f handoff/findings.md ]; then
524
+ echo "::warning::could not render the round's summary, and the iteration left no findings.md"; exit 0
525
+ fi
515
526
  else
516
527
  [ -n "$fresh" ] && grep -q "@ ${H0:0:7}" summary.md && { echo "the iteration posted its summary ($id)"; exit 0; }
517
528
  fi