@jagreehal/shepherd 0.15.0 → 0.17.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.
Files changed (82) hide show
  1. package/AGENTS.md +3 -3
  2. package/README.md +40 -27
  3. package/THIRD_PARTY_NOTICES.md +2 -0
  4. package/gate/.shepherd/gate.schema.json +657 -0
  5. package/gate/.shepherd/gate.yml +123 -0
  6. package/gate/.shepherd/review-guidance.md +95 -0
  7. package/gate/src/actions.ts +32 -0
  8. package/gate/src/cli.ts +1046 -0
  9. package/gate/src/config.ts +102 -0
  10. package/gate/src/delta.ts +29 -0
  11. package/gate/src/env.ts +30 -0
  12. package/gate/src/eval.ts +292 -0
  13. package/gate/src/familiarity.ts +461 -0
  14. package/gate/src/github.ts +761 -0
  15. package/gate/src/inline.ts +59 -0
  16. package/gate/src/isolated-cli.ts +281 -0
  17. package/gate/src/leads.ts +257 -0
  18. package/gate/src/llm.ts +647 -0
  19. package/gate/src/notify.ts +57 -0
  20. package/gate/src/policy.ts +1313 -0
  21. package/gate/src/prices.ts +62 -0
  22. package/gate/src/provider-errors.ts +80 -0
  23. package/gate/src/retention.ts +86 -0
  24. package/gate/src/reviewer.ts +739 -0
  25. package/gate/src/signals.ts +105 -0
  26. package/gate/src/smoke-live.ts +64 -0
  27. package/gate/src/stack.ts +87 -0
  28. package/gate/src/stories.ts +297 -0
  29. package/gate/templates/policy-strict.yml +128 -0
  30. package/gate/templates/reviewer.Dockerfile +8 -0
  31. package/gate/templates/rules/observability/SKILL.md +33 -0
  32. package/gate/templates/shepherd-gate-actions.yml +35 -0
  33. package/gate/templates/shepherd-gate-edited.yml +29 -0
  34. package/gate/templates/shepherd-gate.yml +111 -0
  35. package/lenses/dotnet/SKILL.md +1 -1
  36. package/lenses/go/SKILL.md +1 -1
  37. package/lenses/java/SKILL.md +1 -1
  38. package/lenses/nextjs/SKILL.md +1 -1
  39. package/lenses/node-api/SKILL.md +1 -1
  40. package/lenses/nx-monorepo/SKILL.md +1 -1
  41. package/lenses/observability/SKILL.md +1 -1
  42. package/lenses/owasp-asvs/SKILL.md +1 -1
  43. package/lenses/owasp-llm/SKILL.md +1 -1
  44. package/lenses/pstack/SKILL.md +1 -1
  45. package/lenses/python/SKILL.md +1 -1
  46. package/lenses/react/SKILL.md +1 -1
  47. package/lenses/rust/SKILL.md +1 -1
  48. package/package.json +21 -7
  49. package/schema/config.json +1 -1
  50. package/skills/branch-review/SKILL.md +123 -0
  51. package/skills/ci-repair/SKILL.md +79 -35
  52. package/skills/garden/SKILL.md +8 -8
  53. package/skills/garden/references/telemetry.md +4 -4
  54. package/skills/incident/SKILL.md +9 -9
  55. package/skills/lens-import/SKILL.md +7 -7
  56. package/skills/review-slop/SKILL.md +1 -1
  57. package/skills/shepherd/SKILL.md +43 -41
  58. package/skills/shepherd/references/degradation.md +3 -3
  59. package/skills/shepherd/references/dispatch.md +1 -1
  60. package/skills/shepherd/references/formats.md +5 -5
  61. package/skills/shepherd/references/models.md +2 -2
  62. package/skills/shepherd/references/policy.md +9 -9
  63. package/skills/swarm/SKILL.md +21 -17
  64. package/skills/swarm/references/custom-lenses.md +2 -2
  65. package/skills/swarm/references/formats.md +1 -1
  66. package/skills/triage/SKILL.md +10 -10
  67. package/src/bin.ts +10 -0
  68. package/src/cli.ts +285 -42
  69. package/src/config.ts +26 -25
  70. package/src/doctor.ts +31 -18
  71. package/src/garden-traces.ts +13 -13
  72. package/src/garden.ts +4 -4
  73. package/src/lens.ts +19 -7
  74. package/src/setup.ts +72 -0
  75. package/src/stack.ts +2 -2
  76. package/src/status.ts +80 -0
  77. package/src/summary.ts +52 -9
  78. package/src/trace.ts +4 -4
  79. package/src/working.ts +30 -0
  80. package/templates/shepherd-audit.yml +7 -15
  81. package/templates/shepherd-incident.yml +7 -12
  82. package/templates/shepherd.yml +39 -40
package/src/doctor.ts CHANGED
@@ -6,7 +6,7 @@ import { parse } from "yaml";
6
6
  import { z } from "zod";
7
7
  import { defaultBranchReader, defaultBranchRef, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, type Config } from "./config.ts";
8
8
  import { bundledSkills } from "./install.ts";
9
- import { lensProblems, pluginRoots, skillDirs } from "./lens.ts";
9
+ import { lensProblems, pluginRoots, providerKeyEnv, skillDirs } from "./lens.ts";
10
10
 
11
11
  export type Check = { check: string; status: "ok" | "warn" | "fail"; detail: string; fix?: string };
12
12
 
@@ -24,20 +24,22 @@ const attempt = <T>(f: () => T): T | Error => {
24
24
  const SKILL_DIRS = (home: string, repo: string) => [...skillDirs(home, repo), path.join(home, ".config/opencode/skills")];
25
25
 
26
26
  /**
27
- * True when a workflow runs stamp on pull requests: a step that uses stamp's action, runs its package, or
28
- * checks out its repository and then runs from that checkout. The word "stamp" alone is not enough.
27
+ * True when a workflow runs the gate on pull requests: a step that runs `shepherd gate` from the package, or from a
28
+ * checkout of shepherd's repository. The word "gate" alone is not enough.
29
29
  */
30
- export function runsStamp(text: string): boolean {
30
+ export function runsGate(text: string): boolean {
31
31
  const parsed = Workflow.safeParse(attempt(() => parse(text)));
32
32
 
33
33
  if (!parsed.success) return false;
34
34
 
35
35
  if (!parsed.data.on.some((t) => t === "pull_request" || t === "pull_request_target")) return false;
36
36
 
37
+ const gateCall = /(@jagreehal\/shepherd\S*|\bshepherd|\/src\/bin\.ts)"?\s+gate\b/;
38
+
37
39
  return Object.values(parsed.data.jobs).some(({ steps }) => {
38
- const checkouts = steps.filter((st) => st.with?.repository === "jagreehal/stamp").map((st) => st.with?.path ?? ".");
40
+ const checkouts = steps.filter((st) => st.with?.repository === "jagreehal/shepherd").map((st) => st.with?.path ?? ".");
39
41
 
40
- return steps.some((st) => st.uses?.startsWith("jagreehal/stamp") || st.run?.includes("@jagreehal/stamp") || checkouts.some((p) => p !== "." && st.run?.includes(`${p}/`)));
42
+ return steps.some((st) => gateCall.test(st.run ?? "") && (st.run?.includes("@jagreehal/shepherd") || /\bshepherd\s+gate\b/.test(st.run ?? "") || checkouts.some((p) => p !== "." && st.run?.includes(`${p}/`))));
41
43
  });
42
44
  }
43
45
 
@@ -128,28 +130,39 @@ export function doctor(bundleRoot: string, home: string, repo: string, personal:
128
130
  if (!models.length) add("models", "ok", "no ladder set: the harness's own (shepherd models)");
129
131
 
130
132
  const workflows = attempt(() => run("git", ["-C", repo, "ls-tree", "--name-only", "-r", defaultBranchRef(repo), ".github/workflows/"]));
131
- const stamp = (workflows instanceof Error ? [] : workflows.split("\n").filter(Boolean)).find((f) => runsStamp(read(f) ?? ""));
133
+ const gate = (workflows instanceof Error ? [] : workflows.split("\n").filter(Boolean)).find((f) => runsGate(read(f) ?? ""));
132
134
 
133
- if (!stamp) {
134
- add("stamp workflow", "warn", "no default-branch workflow runs stamp on pull requests: shepherd can review and fix, but nothing gives the approval verdict", "bunx @jagreehal/stamp init, then add its backend secret");
135
+ if (!gate) {
136
+ add("gate workflow", "warn", "no default-branch workflow runs the gate on pull requests: shepherd can review and fix, but nothing gives the approval verdict", "shepherd workflows, then add the model key");
135
137
 
136
138
  return checks;
137
139
  }
138
140
 
139
- add("stamp workflow", "ok", `${stamp} runs stamp on pull requests`);
140
- const last = attempt(() => run("gh", ["run", "list", "--workflow", path.basename(stamp), "--limit", "30", "--json", "conclusion,status,url,databaseId", "--jq", "[.[] | select(.conclusion != \"skipped\")][0] // empty | [.status, .conclusion, .url, .databaseId] | @tsv"], repo).trim());
141
+ add("gate workflow", "ok", `${gate} runs the gate on pull requests`);
142
+ // The first review fails on a missing key, so check for it before anyone opens a PR. An environment's secrets are
143
+ // not listed here, hence a warning.
144
+ const loop = policy.models.loop?.value ?? "";
145
+ const key = loop ? providerKeyEnv(loop) : null;
146
+ const secrets = key ? attempt(() => run("gh", ["secret", "list", "--json", "name", "--jq", ".[].name"], repo)) : null;
147
+
148
+ if (key && !(secrets instanceof Error) && secrets !== null) {
149
+ if (secrets.split("\n").includes(key)) add("model key", "ok", `${key} is set for ${loop}`);
150
+ else add("model key", "warn", `${key} is not a repository secret, so ${loop} cannot run (fine if a GitHub environment holds it)`, `gh secret set ${key}`);
151
+ }
152
+
153
+ const last = attempt(() => run("gh", ["run", "list", "--workflow", path.basename(gate), "--limit", "30", "--json", "conclusion,status,url,databaseId", "--jq", "[.[] | select(.conclusion != \"skipped\")][0] // empty | [.status, .conclusion, .url, .databaseId] | @tsv"], repo).trim());
141
154
 
142
- if (last instanceof Error) add("stamp runs", "warn", "cannot read its runs through gh", "check gh can read this repository's Actions");
143
- else if (!last) add("stamp runs", "warn", "configured, but no recent run did anything (all skipped, or none)", "open a PR, or comment /stamp on one, and check the run");
155
+ if (last instanceof Error) add("gate runs", "warn", "cannot read its runs through gh", "check gh can read this repository's Actions");
156
+ else if (!last) add("gate runs", "warn", "configured, but no recent run did anything (all skipped, or none)", "open a PR, or comment /gate on one, and check the run");
144
157
  else {
145
158
  const [status, conclusion, url, id] = last.split("\t");
146
- // stamp exits 1 on a refusal or an escalation: the run failed, but stamp worked and gave its verdict.
159
+ // gate exits 1 on a refusal or an escalation: the run failed, but gate worked and gave its verdict.
147
160
  const verdict = conclusion === "failure" ? /\b(REFUSED|ESCALATE): /.exec(String(attempt(() => run("gh", ["run", "view", id!, "--log-failed"], repo))))?.[1] : undefined;
148
161
 
149
- if (conclusion === "success") add("stamp runs", "ok", "its latest run approved");
150
- else if (verdict) add("stamp runs", "ok", `its latest run gave a verdict (${verdict}): ${url}`);
151
- else if (conclusion === "action_required") add("stamp runs", "warn", `its latest run is waiting for a maintainer to approve it: ${url}`, "approve the run in the Actions tab (GitHub holds runs from first-time contributors and bots), or open a PR from a branch of this repository");
152
- else add("stamp runs", "warn", `its latest run is ${conclusion || status}: ${url}`, "read the run log; a missing backend secret is the usual cause (stamp README, Backends)");
162
+ if (conclusion === "success") add("gate runs", "ok", "its latest run approved");
163
+ else if (verdict) add("gate runs", "ok", `its latest run gave a verdict (${verdict}): ${url}`);
164
+ else if (conclusion === "action_required") add("gate runs", "warn", `its latest run is waiting for a maintainer to approve it: ${url}`, "approve the run in the Actions tab (GitHub holds runs from first-time contributors and bots), or open a PR from a branch of this repository");
165
+ else add("gate runs", "warn", `its latest run is ${conclusion || status}: ${url}`, "read the run log; a missing backend secret is the usual cause (gate README, Backends)");
153
166
  }
154
167
 
155
168
  return checks;
@@ -13,7 +13,7 @@ const MAX_SPANS = 50_000;
13
13
 
14
14
  const MAX_MEASUREMENTS = 50_000_000;
15
15
 
16
- const KEYS = new Set(["vcs.repository.name", "vcs.change.id", "vcs.ref.head.revision", "shepherd.retries", "shepherd.stage", "shepherd.outcome", "stamp.cost_usd", "stamp.cost_complete"]);
16
+ const KEYS = new Set(["vcs.repository.name", "vcs.change.id", "vcs.ref.head.revision", "shepherd.retries", "shepherd.stage", "shepherd.outcome", "gate.cost_usd", "gate.cost_complete"]);
17
17
 
18
18
  const Id = z.string().transform((s) => /^[0-9a-f]{1,32}$/.test(s) ? s.padStart(32, "0") : /^[A-Za-z0-9+/]{22}==$/.test(s) ? Buffer.from(s, "base64").toString("hex") : s)
19
19
  .pipe(z.string().regex(/^[0-9a-f]{32}$/).refine((s) => /[1-9a-f]/.test(s)));
@@ -164,7 +164,7 @@ export async function readTempo(endpoint: string, headers: Record<string, string
164
164
  const signal = AbortSignal.timeout(30_000);
165
165
  const get = async (url: URL) => readResponse(await fetch(url, { headers: { ...headers, Accept: "application/json" }, redirect: "error", signal }));
166
166
  const search = new URL("api/search", base);
167
- search.searchParams.set("q", `{ (name = "shepherd.iteration" || name = "stamp.review") && span.vcs.repository.name = ${JSON.stringify(repo)} }`);
167
+ search.searchParams.set("q", `{ (name = "shepherd.iteration" || name = "gate.review") && span.vcs.repository.name = ${JSON.stringify(repo)} }`);
168
168
  search.searchParams.set("start", String(Math.floor(Date.parse(since) / 1000)));
169
169
  search.searchParams.set("end", String(Math.floor(now / 1000)));
170
170
  search.searchParams.set("limit", String(MAX_TRACES));
@@ -197,7 +197,7 @@ const DatadogCustom = z.object({
197
197
  }).optional().catch(undefined),
198
198
  shepherd: z.object({ retries: num, stage: str, outcome: str }).optional().catch(undefined),
199
199
  // Datadog stores a boolean attribute as the string "true" or "false".
200
- stamp: z.object({ cost_usd: num, cost_complete: z.enum(["true", "false"]).optional().catch(undefined) }).optional().catch(undefined),
200
+ gate: z.object({ cost_usd: num, cost_complete: z.enum(["true", "false"]).optional().catch(undefined) }).optional().catch(undefined),
201
201
  otel: z.object({ status_code: str }).optional().catch(undefined),
202
202
  }).catch({});
203
203
 
@@ -247,8 +247,8 @@ export function fromDatadog(span: DatadogSpan): Span | null {
247
247
  ...asDouble("shepherd.retries", c.shepherd?.retries),
248
248
  ...asText("shepherd.stage", c.shepherd?.stage),
249
249
  ...asText("shepherd.outcome", c.shepherd?.outcome),
250
- ...asDouble("stamp.cost_usd", c.stamp?.cost_usd),
251
- ...(c.stamp?.cost_complete === undefined ? [] : [{ key: "stamp.cost_complete", value: { boolValue: c.stamp.cost_complete === "true" } }]),
250
+ ...asDouble("gate.cost_usd", c.gate?.cost_usd),
251
+ ...(c.gate?.cost_complete === undefined ? [] : [{ key: "gate.cost_complete", value: { boolValue: c.gate.cost_complete === "true" } }]),
252
252
  ];
253
253
 
254
254
  const parsed = Span.safeParse({
@@ -261,7 +261,7 @@ export function fromDatadog(span: DatadogSpan): Span | null {
261
261
  }
262
262
 
263
263
  /**
264
- * Datadog's span search: the repository's `shepherd.iteration` and `stamp.review` roots, then every span in those
264
+ * Datadog's span search: the repository's `shepherd.iteration` and `gate.review` roots, then every span in those
265
265
  * traces, since stage spans carry no repository. The endpoint rate-limits at 300 requests an hour, so the reader
266
266
  * batches trace IDs and stops at the trace and span caps.
267
267
  */
@@ -279,7 +279,7 @@ export async function readDatadog(site: string, apiKey: string, appKey: string,
279
279
  signal,
280
280
  }))));
281
281
 
282
- const roots = await search(`@vcs.repository.name:${JSON.stringify(repo)} resource_name:(shepherd.iteration OR stamp.review)`);
282
+ const roots = await search(`@vcs.repository.name:${JSON.stringify(repo)} resource_name:(shepherd.iteration OR gate.review)`);
283
283
  const ids = [...new Set(roots.data.flatMap((s) => (s ? [s.attributes.trace_id] : [])).filter((id) => /^[0-9a-f]{32}$/.test(id)))].slice(0, MAX_TRACES);
284
284
  // Here `limited` tracks only the span budget, so a truncated root search still pages through every trace it found.
285
285
  const input: TraceInput = { spans: [], sources: 1, unavailable: 0, limited: false };
@@ -372,10 +372,10 @@ export type TraceSummary = {
372
372
  reviewMs: number; knownCostUsd: number; pricedReviews: number; unpricedReviews: number;
373
373
  stages: { stage: typeof STAGES[number]; durationMs: number; runs: number; failed: number }[];
374
374
  signals: TraceSignal[];
375
- evidence: { traceId: string; spanId: string; headSha: string; kind: "shepherd.iteration" | "stamp.review" }[];
375
+ evidence: { traceId: string; spanId: string; headSha: string; kind: "shepherd.iteration" | "gate.review" }[];
376
376
  };
377
377
 
378
- const Kind = z.enum(["shepherd.iteration", "stamp.review"]);
378
+ const Kind = z.enum(["shepherd.iteration", "gate.review"]);
379
379
 
380
380
  /** Deduplicate exports, then correlate only known PR commits inside the requested window. These are observed samples, not a complete history. */
381
381
  export function traceScores(input: TraceInput, repo: string, prs: PrRecord[], since: string, limits = traceLimits, now = Date.now()) {
@@ -409,14 +409,14 @@ export function traceScores(input: TraceInput, repo: string, prs: PrRecord[], si
409
409
 
410
410
  if (summary.evidence.length < 20) summary.evidence.push({ traceId: root.traceId, spanId: root.spanId, headSha: head, kind: kind.data });
411
411
 
412
- if (kind.data === "stamp.review") {
412
+ if (kind.data === "gate.review") {
413
413
  summary.reviews++;
414
414
  summary.reviewMs += duration(root);
415
- const cost = number(root, "stamp.cost_usd");
415
+ const cost = number(root, "gate.cost_usd");
416
416
 
417
417
  if (cost !== undefined) summary.knownCostUsd += cost;
418
418
 
419
- if (cost !== undefined && value(root, "stamp.cost_complete")?.boolValue === true) summary.pricedReviews++;
419
+ if (cost !== undefined && value(root, "gate.cost_complete")?.boolValue === true) summary.pricedReviews++;
420
420
  else summary.unpricedReviews++;
421
421
  } else {
422
422
  summary.iterations++;
@@ -436,7 +436,7 @@ export function traceScores(input: TraceInput, repo: string, prs: PrRecord[], si
436
436
  record.failed += Number(failed);
437
437
  summary.failedStages += Number(failed);
438
438
 
439
- if (stage.data === "stamp") waits.push([startMs(child), startMs(child) + elapsed]);
439
+ if (stage.data === "gate") waits.push([startMs(child), startMs(child) + elapsed]);
440
440
 
441
441
  if (!summary.stages.includes(record)) summary.stages.push(record);
442
442
  }
package/src/garden.ts CHANGED
@@ -161,12 +161,12 @@ export function parseCommit(sha: string, message: string, date = ""): Commit {
161
161
  return { sha, headline: message.split("\n")[0] ?? "", skill: trailer("Shepherd"), lens: trailer("Shepherd-Lens"), fixes, date };
162
162
  }
163
163
 
164
- /** An incident whose culprit PR stamp approved: the review let a regression through. */
164
+ /** An incident whose culprit PR gate approved: the review let a regression through. */
165
165
  export type Escape = { incident: number; title: string; url: string; pr: number; sha: string; cause: "coverage_gap" | "merge_skew" | null };
166
166
 
167
- const REGRESSED = /Regressed-by: #(\d+) \(([0-9a-f]{7,40})\), stamp: approved\b/;
167
+ const REGRESSED = /Regressed-by: #(\d+) \(([0-9a-f]{7,40})\), gate: approved\b/;
168
168
 
169
- /** The escape an incident issue records, from the lines the incident skill writes; null unless stamp approved the culprit. */
169
+ /** The escape an incident issue records, from the lines the incident skill writes; null unless gate approved the culprit. */
170
170
  export function parseEscape(issue: { number: number; title: string; url: string; body: string }): Escape | null {
171
171
  if (!issue.body.includes("<!-- shepherd-incident:")) return null;
172
172
  const m = REGRESSED.exec(issue.body);
@@ -211,7 +211,7 @@ const Comments = z.array(z.object({ body: z.string(), user: z.object({ login: z.
211
211
 
212
212
  const Issues = z.array(z.object({ number: z.number(), title: z.string(), url: z.string(), body: z.string() }));
213
213
 
214
- /** Incidents updated since `since` whose culprit PR stamp approved. */
214
+ /** Incidents updated since `since` whose culprit PR gate approved. */
215
215
  export function collectEscapes(repo: string, since: string): Escape[] {
216
216
  const issues = Issues.parse(JSON.parse(gh(["issue", "list", "-R", repo, "--label", "incident", "--state", "all", "--search", `updated:>=${since}`, "--limit", "100", "--json", "number,title,url,body"])));
217
217
 
package/src/lens.ts CHANGED
@@ -69,16 +69,17 @@ export function ciOpencodeConfig(session: string, choice: { ladder: string[] | n
69
69
  };
70
70
  }
71
71
 
72
- // stamp's `provider:model` names where OpenCode's provider id differs; every other provider keeps its name.
72
+ // gate's `provider:model` names where OpenCode's provider id differs; every other provider keeps its name.
73
73
  const OPENCODE_PROVIDER = new Map([["bedrock", "amazon-bedrock"], ["vertex", "google-vertex"]]);
74
74
 
75
75
  /**
76
- * A model id as OpenCode spells it. stamp's canonical `provider:model` (`bedrock:eu.anthropic.claude-…-v1:0`)
76
+ * A model id as OpenCode spells it. gate's canonical `provider:model` (`bedrock:eu.anthropic.claude-…-v1:0`)
77
77
  * becomes `provider/model` (`amazon-bedrock/eu.anthropic.claude-…-v1:0`), so one ladder serves both tools.
78
78
  * An OpenCode id or a Claude Code alias passes through.
79
79
  */
80
80
  export function opencodeModel(id: string): string {
81
- const m = /^([a-z][a-z0-9-]*):(.+)$/.exec(id);
81
+ // `provider:model` or `provider/model`, split at the first separator, so `bedrock/…` and `bedrock:…` both reach OpenCode as `amazon-bedrock/…`
82
+ const m = /^([a-z][a-z0-9-]*)[:/](.+)$/.exec(id);
82
83
 
83
84
  return m ? `${OPENCODE_PROVIDER.get(m[1]!) ?? m[1]}/${m[2]}` : id;
84
85
  }
@@ -106,8 +107,7 @@ export function setTier(file: string, tier: string, model: string): void {
106
107
  write(file, { ...current, tiers: { ...current.tiers, [tier]: ModelId.parse(model) } });
107
108
  }
108
109
 
109
- // The environment variable each OpenCode provider reads its key from. SHEPHERD_API_KEY fills the one the session
110
- // model's provider needs, so a single-provider team sets one secret.
110
+ // The environment variable each OpenCode provider reads its key from.
111
111
  const PROVIDER_KEY_ENV = new Map([
112
112
  ["opencode", "OPENCODE_API_KEY"],
113
113
  ["opencode-go", "OPENCODE_API_KEY"],
@@ -124,8 +124,20 @@ const PROVIDER_KEY_ENV = new Map([
124
124
 
125
125
  export const PROVIDER_KEY_ENVS = [...PROVIDER_KEY_ENV.values()];
126
126
 
127
+ // Providers both halves can run: the loop through OpenCode, the gate through the AI SDK. google/ and xai/ are loop-only.
128
+ const SHARED_PROVIDERS = new Set(["anthropic", "openai", "opencode", "opencode-go", "openrouter", "deepseek", "groq", "mistral", "amazon-bedrock"]);
129
+
130
+ /** Why one model id cannot drive the loop and the gate, or null when it can. A bare name (a tier or an alias) passes. */
131
+ export function sharedModelProblem(id: string): string | null {
132
+ const provider = /[:/]/.test(id) ? opencodeModel(id).split("/")[0]! : null;
133
+
134
+ if (provider === null || SHARED_PROVIDERS.has(provider)) return null;
135
+
136
+ return `${id}: the loop and the gate both need to run it, and ${provider}/ is not one both can. Use ${[...SHARED_PROVIDERS].map((p) => `${p}/`).join(", ")}; or pin the loop with \`shepherd models pin loop\` and set \`model:\` in .shepherd/gate.yml separately.`;
137
+ }
138
+
127
139
  /** The key variable for an OpenCode model id's provider, or null when shepherd does not know it. */
128
- export const providerKeyEnv = (opencodeId: string): string | null => PROVIDER_KEY_ENV.get(opencodeId.split("/")[0]!) ?? null;
140
+ export const providerKeyEnv = (id: string): string | null => PROVIDER_KEY_ENV.get(opencodeModel(id).split("/")[0]!) ?? null;
129
141
 
130
142
  /** Replace the ladder, cheapest model first. */
131
143
  export function setLadder(file: string, ladder: string[]): void {
@@ -172,7 +184,7 @@ fixes by its own rules. Nothing here can loosen shepherd's rules.
172
184
  - Escalate: <changes that go to the author instead of being fixed>.
173
185
  `;
174
186
 
175
- // `- **<id>**: <rule>`, or `- **<id>** [refuse|escalate|note]: <rule>` to set that rule's severity for stamp.
187
+ // `- **<id>**: <rule>`, or `- **<id>** [refuse|escalate|note]: <rule>` to set that rule's severity for gate.
176
188
  const RULE = /^- \*\*([a-z0-9][a-z0-9-]*)\*\*(?: \[(refuse|escalate|note)\])?:/gm;
177
189
 
178
190
  export type LensRule = { id: string; severity?: Severity };
package/src/setup.ts ADDED
@@ -0,0 +1,72 @@
1
+ // First-run setup on GitHub: what a hosted console does for other tools, done here through `gh`, so nothing outside
2
+ // the repository and the user's own credentials is involved.
3
+ import { providerKeyEnv, sharedModelProblem } from "./lens.ts";
4
+
5
+ /** The model `shepherd init` picks from the first key it finds, in this order. */
6
+ export const KEY_MODELS = [
7
+ ["OPENCODE_API_KEY", "opencode-go/deepseek-v4.1-flash"],
8
+ ["ANTHROPIC_API_KEY", "anthropic/claude-opus-5"],
9
+ ["OPENAI_API_KEY", "openai/gpt-5.5"],
10
+ ["OPENROUTER_API_KEY", "openrouter/moonshotai/kimi-k3"],
11
+ ] as const;
12
+
13
+ export type Pick = { model: string; key: string | null; why: string; chosen: boolean };
14
+
15
+ /**
16
+ * The model to set up. An explicit choice (the flag) wins; then the model the policy already names, so a rerun never
17
+ * moves it; then SHEPHERD_MODEL; then the first provider key present. `chosen` is true only when it should be written.
18
+ */
19
+ export function pickModel(flag: string | undefined, existing: { value: string; source: string } | undefined, env: Record<string, string | undefined>): Pick | null {
20
+ const at = (model: string, why: string, chosen: boolean): Pick => ({ model, key: providerKeyEnv(model), why, chosen });
21
+
22
+ if (flag) return at(flag, "--model", true);
23
+
24
+ if (existing) return at(existing.value, `models.loop from ${existing.source}`, false);
25
+ const named = env.SHEPHERD_MODEL?.trim();
26
+
27
+ if (named) return at(named, "SHEPHERD_MODEL", true);
28
+ const found = KEY_MODELS.find(([key]) => env[key]?.trim());
29
+
30
+ return found ? { model: found[1], key: found[0], why: `${found[0]} is set`, chosen: true } : null;
31
+ }
32
+
33
+ /** Why the picked model cannot drive both halves, or null. */
34
+ export const modelProblem = (model: string) => sharedModelProblem(model);
35
+
36
+ export type Gh = (args: string[], input?: string) => { ok: boolean; out: string };
37
+
38
+ export type Secret = { name: string; value: string | undefined };
39
+
40
+ export type GithubSetup = { repo: string; secrets: Secret[] };
41
+
42
+ /** What setup did on GitHub: one line per step, and what is left for a person. */
43
+ export type SetupOutcome = { lines: string[]; todo: string[] };
44
+
45
+ /**
46
+ * The repository-side steps, each safe to repeat and none fatal: each secret set from the environment (sent on
47
+ * stdin, never in arguments), and Actions allowed to approve PRs (the gate's approval counts only then). Committing
48
+ * the setup files stays with the user, as any other change does.
49
+ */
50
+ export function githubSetup(gh: Gh, s: GithubSetup): SetupOutcome {
51
+ const lines: string[] = [];
52
+ const todo: string[] = [];
53
+
54
+ for (const { name, value } of s.secrets) {
55
+ if (value && gh(["secret", "set", name, "--repo", s.repo], value).ok) lines.push(`secret ${name} set on ${s.repo}`);
56
+ else {
57
+ lines.push(`secret ${name} ${value ? "could not be set" : "is not in your environment"}`);
58
+ todo.push(`gh secret set ${name} --repo ${s.repo}`);
59
+ }
60
+ }
61
+
62
+ const current = gh(["api", `repos/${s.repo}/actions/permissions/workflow`, "--jq", ".default_workflow_permissions"]);
63
+ const allow = current.ok ? gh(["api", "-X", "PUT", `repos/${s.repo}/actions/permissions/workflow`, "-f", `default_workflow_permissions=${current.out.trim() || "read"}`, "-F", "can_approve_pull_request_reviews=true"]) : current;
64
+
65
+ if (allow.ok) lines.push("setting Actions may approve pull requests");
66
+ else {
67
+ lines.push("setting needs a repository admin");
68
+ todo.push('a repository admin: Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"');
69
+ }
70
+
71
+ return { lines, todo };
72
+ }
package/src/stack.ts CHANGED
@@ -1,4 +1,4 @@
1
- // Stacked PRs and wrong bases, detected the way stamp detects them before it reviews. A PR's base...head
1
+ // Stacked PRs and wrong bases, detected the way gate detects them before it reviews. A PR's base...head
2
2
  // diff is what lands when it merges, which is right for a lone PR and wrong for two common shapes: a PR stacked on another open PR into the same base (its diff
3
3
  // carries the parent's change), and a PR branched from one long-lived branch but opened against another
4
4
  // (its diff carries everything the two branches differ by). Everything here is git ancestry on immutable
@@ -67,7 +67,7 @@ export function stackedParent(pr: { number: number; headSha: string; baseSha: st
67
67
  return best && { parent: best.parent, parentHead: best.parentHead };
68
68
  }
69
69
 
70
- // The same default stamp's policy carries: branches a PR is opened from and merged into, never feature branches.
70
+ // The same default gate's policy carries: branches a PR is opened from and merged into, never feature branches.
71
71
  export const LONG_LIVED = ["main", "master", "develop", "release", "release/*", "staging"];
72
72
 
73
73
  const View = z.object({ number: z.number(), headRefName: z.string(), headRefOid: z.string(), baseRefName: z.string() });
package/src/status.ts ADDED
@@ -0,0 +1,80 @@
1
+ // One answer to "where is my PR?": the gate's verdict, shepherd's status, people's reviews and CI on the PR's current
2
+ // head, folded into a single stage and the one thing to do next. Read-only: `shepherd status <pr>` gathers the facts.
3
+
4
+ export type Stage = "reviewing" | "fixing" | "waiting for CI" | "needs you" | "ready" | "merged" | "closed";
5
+
6
+ export type Run = { name: string; status: string; conclusion: string; url: string };
7
+
8
+ export type PrFacts = {
9
+ pr: number;
10
+ state: string; // OPEN, MERGED, CLOSED
11
+ head: string;
12
+ url: string;
13
+ /**
14
+ * The gate's latest verdict and the head it reviewed, from its own markers only (DISMISSED: an approval taken back).
15
+ * `kept`: an approval of an earlier head whose PR diff matches the current one byte for byte, which the gate keeps.
16
+ */
17
+ gate?: { verdict: string; head: string; kept?: boolean };
18
+ /** The `shepherd` commit status on the head, if the loop has run on it. */
19
+ shepherd?: { state: string; description: string };
20
+ /** People whose latest review requests changes. */
21
+ changesRequested: string[];
22
+ /** Unresolved review threads, whoever opened them. */
23
+ openThreads: number;
24
+ /** Checks on the head: Actions workflow runs, other apps' check runs and commit statuses (CI outside Actions). */
25
+ runs: Run[];
26
+ };
27
+
28
+ export type PrStatus = { stage: Stage; lines: string[]; next: string };
29
+
30
+ const short = (sha: string) => sha.slice(0, 7);
31
+
32
+ export function prStatus(f: PrFacts): PrStatus {
33
+ const running = f.runs.filter((r) => r.status !== "completed");
34
+ // The gate's run fails on a refusal: its verdict, read from its review, speaks for it.
35
+ const failed = f.runs.filter((r) => r.status === "completed" && /^(failure|timed_out|startup_failure)$/.test(r.conclusion) && !/gate/.test(r.name));
36
+ const gateOnHead = f.gate && (f.gate.kept || f.head.startsWith(f.gate.head)) ? f.gate : undefined;
37
+
38
+ const lines = [
39
+ `PR #${f.pr} on ${short(f.head)} ${f.url}`,
40
+ `gate ${gateOnHead ? `${gateOnHead.verdict}${gateOnHead.kept ? ` (kept from ${short(gateOnHead.head)}: the PR's diff is unchanged)` : ""}` : f.gate ? `${f.gate.verdict} on ${short(f.gate.head)}, an older head` : "has not reviewed it"}`,
41
+ `shepherd ${f.shepherd ? `${f.shepherd.state}: ${f.shepherd.description}` : "has not run on this head"}`,
42
+ `CI ${f.runs.length ? f.runs.map((r) => `${r.name} ${r.status === "completed" ? r.conclusion : r.status}`).join(", ") : "no runs on this head"}`,
43
+ ...(f.changesRequested.length ? [`reviews changes requested by ${f.changesRequested.join(", ")}`] : []),
44
+ ...(f.openThreads ? [`threads ${f.openThreads} unresolved`] : []),
45
+ ];
46
+
47
+ const at = (stage: Stage, next: string): PrStatus => ({ stage, lines, next });
48
+
49
+ if (f.state === "MERGED") return at("merged", "nothing: it is merged");
50
+
51
+ if (f.state === "CLOSED") return at("closed", "nothing: it is closed");
52
+
53
+ // What is running now comes first: a pending status only says shepherd is not done, not what it waits on.
54
+ if (running.some((r) => /gate/.test(r.name))) return at("reviewing", "wait: the gate is reviewing");
55
+
56
+ if (running.length) return at("waiting for CI", `wait: ${running.map((r) => r.name).join(", ")} running`);
57
+
58
+ // Then every current blocker, so an older success never reads as ready over a newer failure.
59
+ if (failed.length) return at("needs you", `fix ${failed.map((r) => r.name).join(", ")}, or comment /shepherd to have shepherd try`);
60
+
61
+ if (f.changesRequested.length) return at("needs you", `answer the review from ${f.changesRequested.join(", ")}`);
62
+
63
+ if (gateOnHead?.verdict === "ERROR") return at("needs you", "the gate could not review: open its run, then comment /gate");
64
+
65
+ if (gateOnHead?.verdict === "DISMISSED") return at("needs you", "the gate's approval was dismissed: comment /gate to review again");
66
+
67
+ if (gateOnHead && gateOnHead.verdict !== "APPROVED") return at("needs you", "read the gate's review, then push a fix or comment /shepherd");
68
+
69
+ if (f.shepherd?.state === "pending") return at("fixing", `wait: shepherd is working (${f.shepherd.description})`);
70
+
71
+ if (f.shepherd?.state === "failure") return at("needs you", `${f.shepherd.description}; then comment /shepherd`);
72
+
73
+ if (f.shepherd?.state === "error") return at("needs you", "shepherd stopped on an error: open its run in Actions, then comment /shepherd");
74
+
75
+ if (f.openThreads) return at("needs you", `resolve the ${f.openThreads} open review thread${f.openThreads === 1 ? "" : "s"}, or comment /shepherd to have shepherd work through them`);
76
+
77
+ if (!gateOnHead) return at("reviewing", f.gate ? "wait for the gate to review the new head, or comment /gate" : "comment /shepherd to start, or /gate for a review only");
78
+
79
+ return at("ready", "merge it");
80
+ }
package/src/summary.ts CHANGED
@@ -91,7 +91,7 @@ const Finding = z.object({
91
91
  // has no line on the new side.
92
92
  side: z.enum(["LEFT", "RIGHT"]).nullish().catch(undefined).transform((v) => v ?? "RIGHT"),
93
93
  severity: Severity,
94
- lens: z.string(),
94
+ lens: z.string().transform((l) => l.replace(/^convergent:\s*/i, "")), // the tag's own "convergent:" prefix: the render adds it once
95
95
  body: z.string(),
96
96
  convergent: flag(false),
97
97
  // A reader triages by the title alone: a claim they can check, such as "`firstName` returns the second word".
@@ -255,7 +255,43 @@ const fromChecks = (f: { lens: string }) => f.lens.startsWith("checks/");
255
255
  /** Text a model escaped twice: two or more literal `\\n` and no real line break. One may be code the body quotes. */
256
256
  const unescaped = (t: string) => (!t.includes("\n") && t.split("\\n").length > 2 ? t.replaceAll("\\n", "\n").replaceAll("\\t", "\t").replaceAll('\\"', '"') : t);
257
257
 
258
- export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>, read?: (path: string) => string | null) {
258
+ /** An unresolved review thread shepherd opened: its URL and the ids of the findings its first comment carries. */
259
+ export type OpenThread = { url: string; ids: string[] };
260
+
261
+ /** A finding's id: its place, lens and title. A later round's identical finding has the same id; a reworded one does not. */
262
+ export const findingId = (f: { file?: string; side?: string; line?: number | string; lens: string; title?: string }) =>
263
+ createHash("sha256").update(`${f.file ?? ""}:${f.side ?? "RIGHT"}:${f.line ?? ""}:${f.lens}:${f.title ?? ""}`).digest("hex").slice(0, 12);
264
+
265
+ const FINDING_IDS = /<!-- shepherd-finding:([0-9a-f ]+) -->/;
266
+
267
+ export type ThreadNode = { isResolved: boolean; comments: { nodes: { url: string; body: string; author: { login: string; __typename: string } | null }[] } };
268
+
269
+ /**
270
+ * The PR's open swarm threads. One counts only when shepherd's own account opened it: GitHub Actions' bot in CI, or
271
+ * `viewer`, the signed-in operator whose account local runs post through. The header alone proves nothing: anyone
272
+ * can paste it.
273
+ */
274
+ export function swarmThreads(nodes: readonly ThreadNode[], viewer: string | null): OpenThread[] {
275
+ const ours = (a: ThreadNode["comments"]["nodes"][number]["author"]) => a !== null && ((a.__typename === "Bot" && a.login === "github-actions") || a.login === viewer);
276
+
277
+ return nodes.flatMap((t) => {
278
+ const first = t.comments.nodes[0];
279
+
280
+ return !t.isResolved && first && ours(first.author) && /🤖 Automated comment by .*swarm\*\*/.test(first.body) ? [{ url: first.url, ids: FINDING_IDS.exec(first.body)?.[1]?.split(" ") ?? [] }] : [];
281
+ });
282
+ }
283
+
284
+ /**
285
+ * The open thread that carries this finding, matched explicitly, never by wording: the finding names the thread in its
286
+ * `url` (swarm does for a finding it judged a repeat), or the thread's comment carries this exact finding's id.
287
+ */
288
+ export function openThreadFor(f: Parameters<typeof findingId>[0] & { url?: string }, open: readonly OpenThread[] = []): OpenThread | undefined {
289
+ const id = findingId(f);
290
+
291
+ return open.find((t) => t.url === f.url || t.ids.includes(id));
292
+ }
293
+
294
+ export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>, read?: (path: string) => string | null, open?: readonly OpenThread[]) {
259
295
  const s = SummaryInput.parse(raw);
260
296
  const real = (url: string | undefined) => (url === undefined || threads === undefined || threads.has(url) ? url : undefined);
261
297
 
@@ -288,6 +324,9 @@ export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>, r
288
324
  // same lines.
289
325
  if (read) for (const f of s.findings) place(f, read);
290
326
 
327
+ // After placement: a finding's id names the lines its inline comment was posted on, which placement can move.
328
+ for (const f of s.findings) f.url ??= openThreadFor(f, open)?.url;
329
+
291
330
  return s;
292
331
  }
293
332
 
@@ -469,8 +508,8 @@ export function reviewedTips(previous: string): { head_sha: string; base_sha: st
469
508
  * The summary comment: the verdict heading, why, then one collapsed section per part of the round. With a null header
470
509
  * it is the body alone, for the handoff file the publish job wraps in its own marker and header.
471
510
  */
472
- export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string | null, previous?: string, fanout?: z.input<typeof Fanout>, threads?: ReadonlySet<string>, read?: (path: string) => string | null): string {
473
- const s = checkedRound(raw, threads, read);
511
+ export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string | null, previous?: string, fanout?: z.input<typeof Fanout>, threads?: ReadonlySet<string>, read?: (path: string) => string | null, open?: readonly OpenThread[]): string {
512
+ const s = checkedRound(raw, threads, read, open);
474
513
  // A lens fanout listed for this head that the round does not report never ran as its own reviewer, so it shows
475
514
  // as could_not_run.
476
515
  const wave = fanout ? Fanout.parse(fanout) : null;
@@ -543,7 +582,7 @@ export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string |
543
582
  if (walk.length) out.push(...section("<strong>Walkthrough</strong>", walk.join("\n").trim().split("\n")));
544
583
 
545
584
  // Finishing touches: the commands this repository answers.
546
- if (findings.length) out.push("✨ Comment `/shepherd` to have shepherd work through these findings, as far as `fixes.mode` allows, or `/stamp` for a fresh verdict.", "");
585
+ if (findings.length) out.push("✨ Comment `/shepherd` to have shepherd work through these findings, as far as `fixes.mode` allows, or `/gate` for a fresh verdict.", "");
547
586
 
548
587
  if (s.still_open.length) out.push(...section(`<strong>Still open:</strong> ${s.still_open.length}`, s.still_open.map((t) => (t.url ? `- [${defuse(t.title, true).replace(/[[\]]/g, "")}](${t.url})` : `- ${defuse(t.title, true)}`))));
549
588
 
@@ -763,7 +802,9 @@ export function commentableLines(diff: string, side: "LEFT" | "RIGHT" = "RIGHT")
763
802
  return lines;
764
803
  }
765
804
 
766
- export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, read: (path: string) => string | null = () => null, threads?: ReadonlySet<string>, commentable?: Map<string, Set<number>>, removable?: Map<string, Set<number>>) {
805
+ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, read: (path: string) => string | null = () => null, threads?: ReadonlySet<string>, commentable?: Map<string, Set<number>>, removable?: Map<string, Set<number>>, open?: readonly OpenThread[]) {
806
+ // A finding an open thread of ours already carries, matched explicitly, posts no second comment.
807
+ const fresh = (f: Parameters<typeof openThreadFor>[0]) => !openThreadFor(f, open);
767
808
  const s = checkedRound(raw, threads, read);
768
809
  const glyph = (sev: z.infer<typeof Severity>) => emoji[GLYPH[sev]];
769
810
 
@@ -788,7 +829,7 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
788
829
  return text === null || end <= text.replace(/\n$/, "").split("\n").length;
789
830
  };
790
831
 
791
- const anchored = SEVERITIES.flatMap((sev) => s.findings.filter((f) => f.severity === sev && sev !== "NIT" && f.inline && f.file && f.line !== undefined && f.line !== "general" && fits(f)));
832
+ const anchored = SEVERITIES.flatMap((sev) => s.findings.filter((f) => f.severity === sev && sev !== "NIT" && f.inline && f.file && f.line !== undefined && f.line !== "general" && fits(f) && fresh(f)));
792
833
  // One comment per place, the most severe finding's. Others on the same lines are named under it and appear in full
793
834
  // in the summary.
794
835
  const at = (f: (typeof s.findings)[number]) => `${f.file}:${f.side}:${f.line}`;
@@ -812,7 +853,7 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
812
853
  "> [!NOTE]",
813
854
  header,
814
855
  "",
815
- `**[${defuse(f.lens, true)}]** ${glyph(f.severity)} ${f.severity}`,
856
+ `**[${f.convergent ? "convergent: " : ""}${defuse(f.lens, true)}]** ${glyph(f.severity)} ${f.severity}`,
816
857
  ...(f.title ? ["", `**${defuse(f.title, true)}**`] : []),
817
858
  ...reintroduced(f),
818
859
  "",
@@ -837,7 +878,9 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
837
878
  "</details>",
838
879
  ].join("\n");
839
880
 
840
- const comment: InlineComment = { path: f.file, line: end ?? start, side: f.side, body };
881
+ // Every finding this comment carries, by id, so the summary links each to it and a later round knows it.
882
+ const ids = [f, ...anchored.filter((g) => g !== f && at(g) === at(f))].map(findingId).join(" ");
883
+ const comment: InlineComment = { path: f.file, line: end ?? start, side: f.side, body: `${body}\n<!-- shepherd-finding:${ids} -->` };
841
884
 
842
885
  if (end !== undefined && end !== start) {
843
886
  comment.start_line = start;
package/src/trace.ts CHANGED
@@ -8,8 +8,8 @@ import path from "node:path";
8
8
  import { z } from "zod";
9
9
  import { stateDir } from "./local.ts";
10
10
 
11
- // `stamp` is the wait for stamp's verdict.
12
- export const STAGES = ["checks", "swarm", "verify", "triage", "simplify", "ci-repair", "stamp"] as const;
11
+ // `gate` is the wait for gate's verdict.
12
+ export const STAGES = ["checks", "swarm", "verify", "triage", "simplify", "ci-repair", "gate"] as const;
13
13
 
14
14
  const Event = z.object({
15
15
  at: z.string(),
@@ -93,7 +93,7 @@ export function stagesFrom(text: string, now: Date): StageRecord {
93
93
  return { start: events[0]?.at ?? null, stages: stages.sort((a, b) => a.start.localeCompare(b.start)) };
94
94
  }
95
95
 
96
- /** What ties an iteration to the PR, the CI run and other traces: stamp's review, a CI run's trace. */
96
+ /** What ties an iteration to the PR, the CI run and other traces: gate's review, a CI run's trace. */
97
97
  export type Iteration = {
98
98
  repo: string;
99
99
  pr: number;
@@ -108,7 +108,7 @@ export type Iteration = {
108
108
 
109
109
  const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
110
110
 
111
- /** The iteration span's attributes, named like stamp's so one query finds both. An absent value stays undefined. */
111
+ /** The iteration span's attributes, named like gate's so one query finds both. An absent value stays undefined. */
112
112
  export const iterationAttributes = (it: Iteration, stages: Stage[]) => ({
113
113
  "vcs.repository.name": it.repo,
114
114
  "vcs.change.id": String(it.pr),