@jagreehal/shepherd 0.7.0 → 0.8.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.7.0",
3
+ "version": "0.8.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",
@@ -100,8 +100,10 @@ model pushes what you hand it. An iteration then differs in six places:
100
100
  posts its inline comments and summary with the job's token, which has
101
101
  pull requests: write, under every fix mode. Under `suggest` posting is the
102
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 your file
104
- tool. The publish job posts it only when no summary for this head reached the
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
105
107
  PR, so a failed post still leaves the review on the PR.
106
108
 
107
109
  - **Commit, never push.** Commit on the PR branch as usual. Append the handoff
@@ -233,8 +233,8 @@ with the repo's frozen-lockfile command. Remove the worktree when Step 2 ends.
233
233
  to load it from configuration, and gates and secret scanners refuse the
234
234
  shape regardless.
235
235
  8. Read the verdicts other gates already gave this head: stamp's latest review
236
- (the review carrying the hidden `<!-- stamp-run:` marker, with its mechanics
237
- table; its heading follows stamp's branding, so never match on it) and every
236
+ (the review carrying the hidden `<!-- stamp-run:` marker, with its Gates
237
+ section; older ones are folded under a "Superseded" line; its heading follows stamp's branding, so never match on it) and every
238
238
  failing CI check on the head (`gh pr checks <number>`), not only required
239
239
  ones: many repos protect nothing. A gate that refused the head, or a check
240
240
  that failed on it, is a HIGH `checks/stamp` or `checks/ci` finding that quotes
@@ -470,21 +470,28 @@ line with single spaces: garden reads the severity from it. A convergent
470
470
  finding's tag keeps every lens's full tag, `[convergent: correctness/concurrency + architecture/di-container]`,
471
471
  so triage can still find a custom lens's rule in it.
472
472
 
473
- Then upsert the **one** summary comment, marked `<!-- shepherd-swarm-summary -->`
474
- and shaped as in `references/formats.md`. Find it, update it in place, or create
475
- it:
473
+ Then upsert the **one** summary comment, marked `<!-- shepherd-swarm-summary -->`.
474
+ Write the round as JSON and render it with `shepherd summary` (the shape is in
475
+ `references/formats.md`); never write its Markdown yourself. Find it, render it
476
+ with the existing comment as `--previous` so its rounds carry forward, and
477
+ update it in place, or create it:
478
+
479
+ Match the account you post as as well as the CI bot: a local run posts as you,
480
+ and matching only the bot would start a second summary at round 1. Only those
481
+ two logins count, never anyone else who pasted the marker.
476
482
 
477
483
  ```bash
478
- gh api "repos/<owner>/<repo>/issues/<number>/comments" --paginate \
479
- --jq '[.[] | select(.body | contains("<!-- shepherd-swarm-summary -->"))][0].id'
480
- gh api "repos/<owner>/<repo>/issues/comments/<id>" -X PATCH -F body=@summary.md # update
481
- gh pr comment <number> --body-file summary.md # create
484
+ me=$(gh api user --jq .login 2>/dev/null || true) # empty under a GITHUB_TOKEN, which posts as the bot
485
+ gh api "repos/<owner>/<repo>/issues/<number>/comments" --paginate | jq -s --arg me "$me" \
486
+ '[.[][] | select((.user.login == "github-actions[bot]" or (.user.login == $me and $me != "")) and (.body | contains("<!-- shepherd-swarm-summary -->")))][0] // {}' > found.json
487
+ jq -r '.body // ""' found.json > summary.md # its id: jq -r '.id // empty' found.json
488
+ shepherd summary round.json --previous summary.md > comment.md
489
+ gh api "repos/<owner>/<repo>/issues/comments/<id>" -X PATCH -F body=@comment.md # update
490
+ gh pr comment <number> --body-file comment.md # create
482
491
  ```
483
492
 
484
- Earlier rounds fold into a `<details>` block, one line each, so the comment
485
- always leads with the latest verdict. Take the round number from the existing
486
- comment (its latest round plus one), never from this session; a comment you
487
- found is always updated with its history folded in, never overwritten.
493
+ A comment you found is always updated with its history folded in, never
494
+ overwritten.
488
495
 
489
496
  ## Step 8: Report
490
497
 
@@ -49,43 +49,33 @@ VERIFICATION:
49
49
 
50
50
  ## Summary comment
51
51
 
52
- ```markdown
53
- <!-- shepherd-swarm-summary -->
54
- > [!NOTE]
55
- <headers.swarm from `shepherd branding`>
56
-
57
- ## <the verdict's emoji from the branding> <VERDICT> <sub>(round <N> @ <short_sha>)</sub>
58
-
59
- <one or two sentences on why>
60
-
61
- ### Findings
62
-
63
- <current round only, grouped by severity, one line each with file:line>
64
-
65
- ### Convergent
66
-
67
- <findings two or more lenses reached on their own; omit the section when empty>
68
-
69
- ### Checks
70
-
71
- <one line per repo check that ran, with its finding count; then `checks skipped: <tool> (<reason>)` for each one that did not>
72
-
73
- ### Lenses
74
-
75
- | Lens | Model | Scope | Status | Take | SKILL.md |
76
- | --- | --- | --- | --- | --- | --- |
77
- | router | <model> | full | ok | <danger grade, what it delegated> | |
78
- <one row per lens this round started or meant to start; status ok, failed, or could_not_run; the short blob of the SKILL.md it ran>
79
-
80
- <sub>lenses.yml <short blob></sub>
81
-
82
- <details>
83
- <summary>Earlier rounds (<n>)</summary>
84
-
85
- round <N> @ <short_sha>: <verdict>, <one-line disposition>
52
+ Never write the summary's Markdown yourself. Write the round as JSON and let
53
+ `shepherd summary` render it, so the comment has the same shape every round:
54
+
55
+ ```json
56
+ {
57
+ "head_sha": "<reviewed head>",
58
+ "verdict": "blocked|changes|nits|good",
59
+ "why": "<one or two sentences on why>",
60
+ "findings": [{"file": "src/a.ts", "line": 3, "severity": "HIGH", "lens": "correctness/data", "body": "<finding and fix>", "convergent": false}],
61
+ "still_open": [{"url": "<thread url>", "title": "<one line>"}],
62
+ "checks": [{"tool": "tsc", "status": "ran", "findings": 0}, {"tool": "oxlint", "status": "unavailable", "reason": "not installed"}],
63
+ "lenses": [{"lens": "router", "model": "<model>", "scope": "full", "status": "ok", "take": "<danger grade, what it delegated>", "skill_blob": ""}],
64
+ "lenses_yml_blob": ""
65
+ }
66
+ ```
86
67
 
87
- </details>
68
+ ```bash
69
+ shepherd summary round.json --previous summary.md > comment.md # --previous: the comment already on the PR, if any
70
+ shepherd summary round.json --previous summary.md --body > "$SHEPHERD_HANDOFF/findings.md" # the handoff copy: no marker, header or history
88
71
  ```
89
72
 
90
- When updating, fold the previous "latest" header into one history line. Never
91
- carry an earlier round's full detail forward.
73
+ `findings` holds the current round only, with a convergent finding's `lens`
74
+ carrying every lens's full tag. The renderer leads with the verdict heading
75
+ (`## <emoji> <VERDICT> <sub>(round <N> @ <short_sha>)</sub>`, the round taken
76
+ from `--previous`), then one collapsed section per part with its result in the
77
+ title: findings (open unless the verdict is LOOKS GOOD), still open, checks,
78
+ lenses, and earlier rounds folded one line each. With `--body` it keeps the
79
+ round number but leaves the history out: the publish job folds the comment it
80
+ replaces in itself, so the history would otherwise appear twice. It escapes markers, mentions
81
+ and images in every string you give it.
@@ -353,13 +353,14 @@ one on the current head:
353
353
 
354
354
  ```bash
355
355
  gh pr view <number> --json latestReviews \
356
- --jq '[.latestReviews[] | select(.body | contains("<!-- stamp-run:"))][0] | {state, body: .body[:3000]}'
356
+ --jq '[.latestReviews[] | select(.body | contains("<!-- stamp-run:"))][0] | {state, body: .body[:8000]}'
357
357
  ```
358
358
 
359
- - **REFUSED with issues:** treat each line under **Issues** as a bot thread
360
- and classify it the same way. Fixes push; stamp re-reviews on the push. There
359
+ - **REFUSED with issues:** treat each bullet in the **Issues** section (a
360
+ `<details>` block titled `Issues: <n>`) as a bot thread and classify it the
361
+ same way. Fixes push; stamp re-reviews on the push. There
361
362
  is nothing to resolve.
362
- - **REFUSED by a gate** (the mechanics table shows a failed gate such as
363
+ - **REFUSED by a gate** (the **Gates** section shows a failed gate such as
363
364
  `deny-list`, `secrets`, or `size`): a gate decides whether stamp approves,
364
365
  not whether the code may be fixed. Keep fixing every thread as usual; a hard
365
366
  coded key in code this PR adds is fixed by reading it from configuration.
package/src/cli.ts CHANGED
@@ -15,6 +15,7 @@
15
15
  // shepherd config validate (the working tree's policy: exits 1 on a problem)
16
16
  // shepherd config schema (the JSON Schema of .shepherd/config.yml, for editors)
17
17
  // shepherd config explain [--json] [--working-tree] (effective policy and where each setting came from)
18
+ // shepherd summary <round.json> [--previous <comment.md>] [--body] (Markdown: swarm's summary comment)
18
19
  // shepherd branding [--working-tree] (JSON: the name, avatar, glyphs and headers posted comments use)
19
20
  // shepherd ci-settings [--outputs] (the CI settings from variables, the default branch's ci:, defaults)
20
21
  // shepherd fanout [--base <ref>] [--working-tree] (JSON: the lenses swarm starts beside the router, each with its scope)
@@ -41,6 +42,7 @@ import { parseArgs } from "node:util";
41
42
  import { parse as parseYaml, stringify } from "yaml";
42
43
  import { z } from "zod";
43
44
  import { branding, CI_DEFAULT_MODEL, ciModel, ciSettings, type Config, ConfigSchema, defaultBranchDir, defaultBranchReader, type Effective, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, policyProblems, PRESETS, preview, type Read, TEAM_FILES, configJsonSchema, schemaLine } from "./config.ts";
45
+ import { renderSummary } from "./summary.ts";
44
46
  import { ghThreads, snapshot, verdict } from "./acceptance.ts";
45
47
  import { doctor } from "./doctor.ts";
46
48
  import { fileLedger, notify, notifyOn, STATES, statusLedger } from "./notify.ts";
@@ -74,6 +76,7 @@ const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [
74
76
  shepherd config validate
75
77
  shepherd config schema
76
78
  shepherd config explain [--json] [--working-tree]
79
+ shepherd summary <round.json> [--previous <comment.md>] [--body]
77
80
  shepherd branding [--working-tree]
78
81
  shepherd ci-settings [--outputs]
79
82
  shepherd fanout [--base <ref>] [--working-tree]
@@ -112,6 +115,8 @@ const { values: opts, positionals } = parseArgs({
112
115
  base: { type: "string" }, // local: the ref the change is measured from
113
116
  from: { type: "string" }, // lens new: a starter lens in lenses/; init: the pack to extend
114
117
  json: { type: "boolean", default: false },
118
+ previous: { type: "string" }, // summary: the summary comment already on the PR, whose rounds carry forward
119
+ body: { type: "boolean", default: false }, // summary: no marker or header, for the handoff findings.md
115
120
  "working-tree": { type: "boolean", default: false }, // explain, preview: your edits instead of the default branch
116
121
  recipe: { type: "string" },
117
122
  preset: { type: "string" }, // init: how far fixes go
@@ -537,6 +542,13 @@ if (command === "install") {
537
542
  } else if (command === "branding") {
538
543
  // From the default branch, like the rest of the policy: a PR cannot restyle how its own review is posted.
539
544
  console.log(JSON.stringify(branding(policy(opts["working-tree"])), null, 2));
545
+ } else if (command === "summary" && sub) {
546
+ // Swarm's summary comment, rendered from the round's JSON.
547
+ const input = orExit(() => JSON.parse(readFileSync(sub, "utf8")));
548
+ const b = branding(policy(opts["working-tree"]));
549
+ const previous = opts.previous ? readFileSync(opts.previous, "utf8") : undefined;
550
+
551
+ process.stdout.write(orExit(() => renderSummary(input, b.emoji, opts.body ? null : b.headers.swarm, previous)));
540
552
  } else if (command === "fanout") {
541
553
  // Swarm's first wave, dispatched in one message beside the router: correctness on the whole diff and every custom
542
554
  // lens whose applies_to matches a changed file, with its directory. The CLI lists them so no model skips one.
package/src/summary.ts ADDED
@@ -0,0 +1,117 @@
1
+ /**
2
+ * Swarm's summary comment, rendered in code from the round's JSON. The comment keeps the same shape every round, so a
3
+ * reader scans one line per section and garden parses the heading. Every model-written string is defused here.
4
+ */
5
+ import { z } from "zod";
6
+ import type { BRANDING } from "./config.ts";
7
+
8
+ const Severity = z.enum(["CRITICAL", "HIGH", "MEDIUM", "LOW", "NIT"]);
9
+
10
+ export const SummaryInput = z.object({
11
+ head_sha: z.string().regex(/^[0-9a-f]{7,40}$/),
12
+ verdict: z.enum(["blocked", "changes", "nits", "good"]),
13
+ why: z.string(),
14
+ findings: z.array(z.object({ file: z.string().default(""), line: z.union([z.number().int().nonnegative(), z.string().regex(/^(?:\d+(?:-\d+)?|general)$/)]).optional(), severity: Severity, lens: z.string(), body: z.string(), convergent: z.boolean().default(false) })).default([]),
15
+ still_open: z.array(z.object({ url: z.string().regex(/^https:\/\/github\.com\/[\w./#-]+$/), title: z.string() })).default([]),
16
+ checks: z.array(z.object({ tool: z.string(), status: z.enum(["ran", "unavailable"]), findings: z.number().default(0), reason: z.string().optional() })).default([]),
17
+ 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([]),
18
+ lenses_yml_blob: z.string().default(""),
19
+ });
20
+
21
+ export type SummaryInput = z.input<typeof SummaryInput>;
22
+
23
+ type Emoji = Record<keyof typeof BRANDING.emoji, string>;
24
+
25
+ const VERDICT = { blocked: ["blocked", "BLOCKED"], changes: ["changes_needed", "CHANGES NEEDED"], nits: ["approve_with_nits", "APPROVE WITH NITS"], good: ["looks_good", "LOOKS GOOD"] } as const;
26
+
27
+ const SEVERITIES = Severity.options;
28
+
29
+ const GLYPH = { CRITICAL: "critical", HIGH: "high", MEDIUM: "medium", LOW: "low", NIT: "nit" } as const satisfies Record<z.infer<typeof Severity>, keyof Emoji>;
30
+
31
+ /** Model text made inert: no hidden markers, mentions, images or control characters, one table cell when `cell`. */
32
+ export function defuse(text: string, cell = false): string {
33
+ const out = text
34
+ .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "")
35
+ .replaceAll("<!--", "&lt;!--")
36
+ .replace(/<(\/?)(img|picture|source|video|iframe|details|summary)\b/gi, "&lt;$1$2")
37
+ .replace(/!\[([^\]]*)\]\([^)]*\)/g, "[image removed: $1]")
38
+ .replaceAll("![", "!\\[") // reference-style images too: `![x][ref]` with a `[ref]: url` line elsewhere
39
+ .replace(/(?<![\w/])@(?=[A-Za-z0-9])/g,"@​");
40
+
41
+ return cell ? out.replace(/\r?\n/g, " ").replaceAll("|", "\\|") : out;
42
+ }
43
+
44
+ /** The latest round of a summary already on the PR, folded into one history line, plus the history it carried. */
45
+ export function earlierRounds(previous: string | undefined) {
46
+ if (!previous) return { round: 0, history: [] };
47
+
48
+ const latest = /^## \S+ ([A-Z_ ]+?) <sub>\((?:round (\d+)|handoff) @ ([0-9a-f]{7,40})\)<\/sub>/m.exec(previous);
49
+ const carried = previous.match(/^(?:round \d+|handoff) @ [0-9a-f]{7,40}: [^\n]{0,200}$/gm) ?? [];
50
+ const round = Number(latest?.[2] ?? Math.max(0, ...carried.map((l) => Number(/^round (\d+)/.exec(l)?.[1] ?? 0))));
51
+
52
+ return { round, history: [...(latest ? [`${latest[2] ? `round ${latest[2]}` : "handoff"} @ ${latest[3]}: ${latest[1]}`] : []), ...carried] };
53
+ }
54
+
55
+ const section = (summary: string, body: string[], open = false) => [`<details${open ? " open" : ""}>`, `<summary>${summary}</summary>`, "", ...body, "", "</details>", ""];
56
+
57
+ /**
58
+ * The summary comment: the verdict heading, why, then one collapsed section per part of the round. With a null header
59
+ * it is the body alone, for the handoff file the publish job wraps in its own marker and header.
60
+ */
61
+ export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string | null, previous?: string): string {
62
+ const s = SummaryInput.parse(raw);
63
+ const [key, label] = VERDICT[s.verdict];
64
+ const { round, history } = earlierRounds(previous);
65
+ const sha = s.head_sha.slice(0, 7);
66
+ const glyph = (sev: z.infer<typeof Severity>) => emoji[GLYPH[sev]];
67
+ const where = (f: (typeof s.findings)[number]) => (f.file ? ` · \`${defuse(f.file, true).replaceAll("`", "")}${f.line !== undefined && f.line !== "general" ? `:${f.line}` : ""}\`` : "");
68
+
69
+ const findings = SEVERITIES.flatMap((sev) => s.findings.filter((f) => f.severity === sev));
70
+
71
+ const counts = SEVERITIES.flatMap((sev) => {
72
+ const n = s.findings.filter((f) => f.severity === sev).length;
73
+
74
+ return n ? [`${glyph(sev)} ${n} ${sev}`] : [];
75
+ });
76
+
77
+ const ran = s.checks.filter((c) => c.status === "ran");
78
+ const failed = s.lenses.filter((l) => l.status !== "ok");
79
+ const out = [...(header === null ? [] : ["<!-- shepherd-swarm-summary -->", "> [!NOTE]", header, ""]), `## ${emoji[key]} ${label} <sub>(round ${round + 1} @ ${sha})</sub>`, "", defuse(s.why), ""];
80
+
81
+ out.push(
82
+ ...section(
83
+ `<strong>Findings:</strong> ${counts.join(" · ") || "none"}`,
84
+ findings.length ? findings.flatMap((f) => [`**${glyph(f.severity)} ${f.severity}**${where(f)} · ${f.convergent ? "convergent: " : ""}${defuse(f.lens, true)}`, "", defuse(f.body), ""]) : ["Nothing this round."],
85
+ s.verdict !== "good",
86
+ ),
87
+ );
88
+
89
+ if (s.still_open.length) out.push(...section(`<strong>Still open:</strong> ${s.still_open.length}`, s.still_open.map((t) => `- [${defuse(t.title, true).replace(/[[\]]/g, "")}](${t.url})`)));
90
+
91
+ if (s.checks.length) {
92
+ const skipped = s.checks.length - ran.length;
93
+
94
+ out.push(
95
+ ...section(
96
+ `<strong>Checks:</strong> ${ran.length} ran${skipped ? ` · ⏭️ ${skipped} skipped` : ""}`,
97
+ s.checks.map((c) => (c.status === "ran" ? `- ${defuse(c.tool, true)}: ${c.findings} finding${c.findings === 1 ? "" : "s"}` : `- checks skipped: ${defuse(c.tool, true)} (${defuse(c.reason ?? "unavailable", true)})`)),
98
+ ),
99
+ );
100
+ }
101
+
102
+ if (s.lenses.length) {
103
+ out.push(
104
+ ...section(`<strong>Lenses:</strong> ${s.lenses.length - failed.length} ok${failed.length ? ` · ❌ ${failed.length} did not finish` : ""}`, [
105
+ "| Lens | Model | Scope | Status | Take | SKILL.md |",
106
+ "| --- | --- | --- | --- | --- | --- |",
107
+ ...s.lenses.map((l) => `| ${[l.lens, l.model, Array.isArray(l.scope) ? l.scope.join(", ") : l.scope, l.status, l.take, l.skill_blob.slice(0, 7)].map((c) => defuse(c, true)).join(" | ")} |`),
108
+ ...(s.lenses_yml_blob ? ["", `<sub>lenses.yml ${defuse(s.lenses_yml_blob.slice(0, 7), true)}</sub>`] : []),
109
+ ]),
110
+ );
111
+ }
112
+
113
+ // The handoff body (no header) leaves history to the publish job, which folds in the comment it replaces.
114
+ if (history.length && header !== null) out.push(...section(`Earlier rounds (${history.length})`, [defuse(history.join("\n"))]));
115
+
116
+ return out.join("\n").trimEnd() + "\n";
117
+ }