@jagreehal/shepherd 0.12.1 → 0.12.2
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 +3 -2
- package/skills/swarm/references/formats.md +2 -1
- package/src/summary.ts +26 -19
- package/templates/shepherd.yml +11 -2
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jagreehal/shepherd",
|
|
3
|
-
"version": "0.12.
|
|
3
|
+
"version": "0.12.2",
|
|
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
|
@@ -480,8 +480,9 @@ then check it before you stop:
|
|
|
480
480
|
shepherd summary "$SHEPHERD_HANDOFF/round.json" --body > /dev/null
|
|
481
481
|
```
|
|
482
482
|
|
|
483
|
-
It prints every field the renderer rejects
|
|
484
|
-
until it prints nothing. The
|
|
483
|
+
It prints every field the renderer rejects on stderr, so keep stderr visible.
|
|
484
|
+
Fix `round.json` and run it again until it prints nothing. The workflow runs
|
|
485
|
+
the same check after you stop. The round is its own shape (`references/formats.md`):
|
|
485
486
|
not the Step 8 report (`posted`, `counts`, `narration`) and not the local
|
|
486
487
|
record (`stages`, `candidates`). `verdict` is `blocked`, `changes`, `nits` or
|
|
487
488
|
`good`; `verified` is the text of what the verifier checked. Then stop: the
|
|
@@ -83,7 +83,8 @@ left, 1 or 0 a HIGH or CRITICAL standing. `effort` is how long a careful human
|
|
|
83
83
|
read takes, 1 (a minute) to 5 (an hour or more). Draw a `diagram` only when the
|
|
84
84
|
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
|
-
The new fields are optional: a round without them renders as before.
|
|
86
|
+
The new fields are optional: a round without them renders as before. A field
|
|
87
|
+
written as `null` reads as absent and takes its default.
|
|
87
88
|
The renderers hold the round to what they can check. A `url`, `reintroduces`
|
|
88
89
|
or still-open link that names no review comment on the PR, or is not a
|
|
89
90
|
GitHub URL, loses its link.
|
package/src/summary.ts
CHANGED
|
@@ -14,51 +14,58 @@ const THREAD_URL = /^https:\/\/github\.com\/[\w./#-]+$/;
|
|
|
14
14
|
// `changes_needed`, `skipped`, `verified: true`. Each maps onto the round's own value, so a near miss still renders.
|
|
15
15
|
const alias = (table: Record<string, string>) => (v: string) => table[v.trim().toLowerCase().replaceAll(/[\s-]+/g, "_")] ?? v;
|
|
16
16
|
|
|
17
|
+
// Models write `null` for a field they have nothing for. Null reads as absent, so the field takes its default.
|
|
18
|
+
const absent = <T extends z.ZodType>(t: T) => t.nullish().transform((v) => v ?? undefined);
|
|
19
|
+
|
|
20
|
+
const text = z.string().nullish().transform((v) => v ?? "");
|
|
21
|
+
|
|
22
|
+
const flag = (fallback: boolean) => z.boolean().nullish().transform((v) => v ?? fallback);
|
|
23
|
+
|
|
17
24
|
const VERDICT_ALIAS = alias({ changes_needed: "changes", approve_with_nits: "nits", looks_good: "good", approve: "good", approved: "good" });
|
|
18
25
|
|
|
19
26
|
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
27
|
|
|
21
28
|
const Finding = z.object({
|
|
22
|
-
file:
|
|
23
|
-
line:
|
|
24
|
-
.union([
|
|
29
|
+
file: text,
|
|
30
|
+
line: absent(
|
|
31
|
+
z.union([
|
|
25
32
|
z.number().int().positive(),
|
|
26
33
|
z
|
|
27
34
|
.string()
|
|
28
35
|
.regex(/^(?:[1-9]\d*(?:-[1-9]\d*)?|general)$/)
|
|
29
36
|
.refine((l) => !l.includes("-") || Number(l.split("-")[0]) <= Number(l.split("-")[1]), "a range runs start-end, start first"),
|
|
30
|
-
])
|
|
31
|
-
|
|
37
|
+
]),
|
|
38
|
+
),
|
|
32
39
|
severity: Severity,
|
|
33
40
|
lens: z.string(),
|
|
34
41
|
body: z.string(),
|
|
35
|
-
convergent:
|
|
42
|
+
convergent: flag(false),
|
|
36
43
|
// A reader triages by the title alone: a claim they can check, such as "`firstName` returns the second word".
|
|
37
|
-
title:
|
|
44
|
+
title: text,
|
|
38
45
|
// A thread link that is not a GitHub URL is dropped and the finding kept.
|
|
39
|
-
url: z.string().regex(THREAD_URL)
|
|
46
|
+
url: absent(z.string().regex(THREAD_URL)).catch(undefined), // the finding's inline thread, linked from the summary
|
|
40
47
|
// 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(() => "")]).
|
|
48
|
+
verified: z.union([z.string(), z.boolean().transform(() => "")]).nullish().transform((v) => v ?? ""),
|
|
42
49
|
// The claim made checkable: an input, what the code should do on it, and what it does.
|
|
43
|
-
evidence: z.object({ input: z.string().min(1), expected: z.string().min(1), actual: z.string().min(1) })
|
|
44
|
-
suggestion: z.string()
|
|
45
|
-
inline:
|
|
50
|
+
evidence: absent(z.object({ input: z.string().min(1), expected: z.string().min(1), actual: z.string().min(1) })),
|
|
51
|
+
suggestion: absent(z.string()), // replacement for exactly the lines the comment covers: GitHub's one-click commit
|
|
52
|
+
inline: flag(true), // false when the finding has no line in the diff to anchor on
|
|
46
53
|
// The read-only commands the reviewer or verifier ran to check it.
|
|
47
|
-
checked: z.array(z.object({ command: z.string(), result: z.string() })).
|
|
48
|
-
docs: z.array(z.object({ url: z.string().regex(/^https:\/\/[^\s()<>`]+$/), title: z.string() })).
|
|
49
|
-
reintroduces: z.string().regex(THREAD_URL)
|
|
54
|
+
checked: z.array(z.object({ command: z.string(), result: z.string() })).nullish().transform((v) => v ?? []),
|
|
55
|
+
docs: z.array(z.object({ url: z.string().regex(/^https:\/\/[^\s()<>`]+$/), title: z.string() })).nullish().transform((v) => v ?? []), // the documentation the claim rests on
|
|
56
|
+
reintroduces: absent(z.string().regex(THREAD_URL)).catch(undefined), // a resolved thread whose fix this change undoes
|
|
50
57
|
});
|
|
51
58
|
|
|
52
59
|
export const SummaryInput = z.object({
|
|
53
60
|
head_sha: z.string().regex(/^[0-9a-f]{7,40}$/),
|
|
54
61
|
verdict: z.string().transform(VERDICT_ALIAS).pipe(z.enum(["blocked", "changes", "nits", "good"])),
|
|
55
|
-
why:
|
|
56
|
-
confidence: z.number().int().min(0).max(5)
|
|
62
|
+
why: text,
|
|
63
|
+
confidence: absent(z.number().int().min(0).max(5)), // how safe to merge, 5 safest
|
|
57
64
|
findings: z.array(Finding).default([]),
|
|
58
65
|
walkthrough: z.array(z.string()).default([]), // what the PR does, a few bullets for a reader who never saw it
|
|
59
66
|
changes: z.array(z.object({ files: z.array(z.string()).min(1), summary: z.string() })).default([]),
|
|
60
|
-
effort: z.number().int().min(1).max(5)
|
|
61
|
-
diagram:
|
|
67
|
+
effort: absent(z.number().int().min(1).max(5)), // review effort, 1 trivial to 5 a long careful read
|
|
68
|
+
diagram: text, // mermaid flowchart source, when the change has a flow worth drawing
|
|
62
69
|
// Pre-merge checks: do the title, description, linked issue and scope match the diff.
|
|
63
70
|
pre_merge: z.array(z.object({ check: z.string(), status: z.enum(["pass", "warn", "fail"]), detail: z.string() })).default([]),
|
|
64
71
|
still_open: z.array(z.object({ url: z.string().regex(THREAD_URL).catch(""), title: z.string() })).default([]), // "" renders the title alone
|
package/templates/shepherd.yml
CHANGED
|
@@ -342,11 +342,20 @@ jobs:
|
|
|
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
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
|
|
346
|
-
job renders and posts the inline review and the summary from it, so post neither
|
|
345
|
+
with 'shepherd summary $SHEPHERD_HANDOFF/round.json --body > /dev/null', fixing every error it prints on stderr (never
|
|
346
|
+
redirect stderr): the publish job renders and posts the inline review and the summary from it, so post neither
|
|
347
|
+
yourself. You are running in GitHub Actions on the PR branch,
|
|
347
348
|
already checked out, and you cannot push. Nobody is watching this session: never wait for an answer. Anything you
|
|
348
349
|
would ask the user is deferred, listed in the iteration summary, and named in status.json. Do not schedule further
|
|
349
350
|
iterations; the next one starts when CI or stamp finishes on the head the workflow pushes."
|
|
351
|
+
# The job checks the round itself. A round that does not render gets one short call with the exact errors.
|
|
352
|
+
round="$SHEPHERD_HANDOFF/round.json"
|
|
353
|
+
if [ -f "$round" ] && ! errors=$(shepherd summary "$round" --body 2>&1 >/dev/null); then
|
|
354
|
+
echo "::warning::round.json does not render; asking the model to fix it"
|
|
355
|
+
opencode run --auto -m "$model" --title "shepherd #$PR round.json" "The round you wrote to $round does not
|
|
356
|
+
render. Fix exactly these errors in that file and change nothing else, then run 'shepherd summary $round --body > /dev/null'
|
|
357
|
+
and repeat until it prints nothing on stderr. Errors: ${errors:0:6000}" || true
|
|
358
|
+
fi
|
|
350
359
|
- name: Bundle the commits
|
|
351
360
|
env:
|
|
352
361
|
H0: ${{ needs.gate.outputs.head }}
|