@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 +1 -1
- package/skills/swarm/SKILL.md +15 -4
- package/skills/swarm/references/formats.md +5 -3
- package/src/summary.ts +46 -12
- package/templates/shepherd.yml +19 -8
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jagreehal/shepherd",
|
|
3
|
-
"version": "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",
|
package/skills/swarm/SKILL.md
CHANGED
|
@@ -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
|
-
-
|
|
467
|
-
-
|
|
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
|
|
477
|
-
|
|
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
|
|
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.
|
|
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
|
-
|
|
30
|
-
|
|
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
|
|
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
|
-
|
|
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("
|
|
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
|
-
|
|
206
|
-
const
|
|
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
|
-
|
|
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
|
|
package/templates/shepherd.yml
CHANGED
|
@@ -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
|
|
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
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
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
|
-
|
|
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
|