@jagreehal/shepherd 0.0.0-stage → 0.2.0

package/src/config.ts

@@ -0,0 +1,439 @@
+// Team policy. `.shepherd/config.yml` (or the older `.shepherd/lenses.yml`) is layered in one fixed order:
+// built-in defaults, then each pack it `extends`, then the file itself; a later layer replaces a scalar and
+// merges a map by name. Every effective value carries the layer it came from. Personal settings
+// (~/.config/shepherd/lenses.yml) are a preview: lenses that print locally, and a ladder or model pins that
+// fill in only where the team sets none. Team files are read from the default branch, so a PR cannot change
+// the policy it is reviewed under, and a pack from another repository is pinned to a commit.
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { parse } from "yaml";
+
+const NAME = /^[a-z][a-z0-9-]*$/;
+
+export const LensSchema = z
+  .object({
+    skill: z.string().min(1),
+    applies_to: z.array(z.string().min(1)).optional(),
+    description: z.string().min(1).optional(),
+  })
+  .strict();
+
+export type Lens = z.infer<typeof LensSchema>;
+
+// A model id is whatever the harness's agent tool accepts, passed through untouched: `haiku` on Claude Code,
+// `provider/model` on OpenCode (`opencode-go/deepseek-v4-flash`). shepherd never maps one to another.
+export const ModelId = z.string().min(1);
+
+/** The steps a recipe can run: shepherd's own runners and stamp's verdict. */
+export const STEPS = ["swarm", "triage", "simplify", "ci-repair", "stamp", "incident"] as const;
+
+type Step = (typeof STEPS)[number];
+
+// Steps that change code, and the steps that review it. Success needs a review after the last change.
+const FIXERS = new Set<Step>(["triage", "simplify", "ci-repair", "incident"]);
+
+const REVIEWS = new Set<Step>(["swarm", "stamp"]);
+
+export const ConfigSchema = z
+  .object({
+    extends: z.array(z.string().min(1)).optional(),
+    ladder: z.array(ModelId).min(1).optional(), // cheapest first; replaces the harness's ladder
+    models: z.record(z.string().regex(NAME), ModelId).optional(), // a lens or runner name -> the model it always runs on
+    lenses: z.record(z.string().regex(NAME), LensSchema).default({}),
+    checks: z.record(z.string().regex(NAME), z.object({ command: z.string().min(1) }).strict()).optional(),
+    fixes: z.object({ mode: z.enum(["suggest", "local", "push"]) }).strict().optional(),
+    escalate: z.object({ paths: z.array(z.string().min(1)).min(1), reason: z.string().min(1).optional() }).strict().optional(),
+    recipes: z.record(z.string().regex(NAME), z.object({ steps: z.array(z.enum(STEPS)).min(1) }).strict()).optional(),
+  })
+  .strict();
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+export const TEAM_FILES = [".shepherd/config.yml", ".shepherd/lenses.yml"];
+
+const BUILT_IN: Config = {
+  lenses: {},
+  fixes: { mode: "push" },
+  recipes: {
+    review: { steps: ["swarm"] },
+    fix: { steps: ["swarm", "triage", "simplify", "swarm"] }, // runs under fixes.mode local: nothing it needs is pushed
+    pr: { steps: ["swarm", "triage", "simplify", "swarm", "ci-repair", "stamp"] },
+    incident: { steps: ["incident", "swarm", "triage", "simplify", "swarm", "ci-repair", "stamp"] }, // the fix PR gets the full loop
+  },
+};
+
+// `github:owner/repo/path/to/pack.yml@<40-hex commit>`. A branch or tag can move under the team; a commit cannot.
+// Path characters are limited so nothing in it can reach the API URL as a query or fragment (`?ref=`, `#`).
+export const PINNED = /^github:([\w.-]+)\/([\w.-]+)\/([\w./-]+)@([0-9a-f]{40})$/;
+
+type Sourced<T> = { value: T; source: string };
+
+/** One layer of policy and where it came from. */
+type Layer = { source: string; config: Config };
+
+export type Effective = {
+  ladder: Sourced<string[]> | null;
+  models: Record<string, Sourced<string>>;
+  lenses: Record<string, Sourced<Lens> & { scope: "team" | "personal" }>;
+  checks: Record<string, Sourced<{ command: string }>>;
+  fixes: Sourced<{ mode: "suggest" | "local" | "push" }>;
+  escalate: Sourced<{ paths: string[]; reason?: string }> | null;
+  recipes: Record<string, Sourced<{ steps: Step[] }>>;
+  /** Personal settings that would change team policy, so they were not applied. */
+  ignored: string[];
+};
+
+/** Reads a repository file (default branch or working tree); null when it does not exist. */
+export type Read = (rel: string) => string | null;
+
+/** Fetches a pinned pack from another repository. */
+export type Fetch = (owner: string, repo: string, file: string, sha: string) => string;
+
+const parseConfig = (text: string, source: string): Config => {
+  const result = ConfigSchema.safeParse(parse(text) ?? {});
+
+  if (!result.success) throw new Error(`${source}: ${result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+
+  return result.data;
+};
+
+/** One `extends` entry as a layer. A pack extends nothing itself, so the order stays the one the file lists. */
+function readPack(ref: string, read: Read, fetch: Fetch): Layer {
+  const pinned = PINNED.exec(ref);
+  let text: string | null;
+
+  if (pinned) text = fetch(pinned[1]!, pinned[2]!, pinned[3]!, pinned[4]!);
+  else if (ref.startsWith("github:")) throw new Error(`${ref}: pin a pack from another repository to a full commit sha (github:owner/repo/path@<40 hex>)`);
+  else if (pathEscapes(ref)) throw new Error(`${ref}: a pack path is repository-relative, with no leading / and no ..`);
+  else text = read(ref);
+
+  if (text === null) throw new Error(`${ref}: pack not found`);
+  const config = parseConfig(text, ref);
+
+  if (config.extends?.length) throw new Error(`${ref}: a pack cannot extend another pack; list both in the repository's extends`);
+
+  // A pinned pack's lens paths name files in the pack's repository at the same commit, so the lens travels with it.
+  if (pinned) {
+    for (const [name, lens] of Object.entries(config.lenses)) {
+      if (!lens.skill.includes("/")) continue;
+
+      if (pathEscapes(lens.skill)) throw new Error(`${ref}: lens ${name}: a skill path is relative to the pack's repository, with no leading / and no ..`);
+      lens.skill = `github:${pinned[1]}/${pinned[2]}/${lens.skill.replace(/\/+$/, "")}@${pinned[4]}`;
+    }
+  }
+
+  return { source: `pack ${ref}`, config };
+}
+
+const pathEscapes = (rel: string) => rel.startsWith("/") || rel.split("/").includes("..");
+
+/** Merge layers in order: a later layer replaces a scalar and merges a map by name. */
+function merge(layers: Layer[]): Effective {
+  const out: Effective = { ladder: null, models: {}, lenses: {}, checks: {}, fixes: { value: { mode: "push" }, source: "built-in" }, escalate: null, recipes: {}, ignored: [] };
+
+  for (const { source, config } of layers) {
+    const tag = <T>(value: T) => ({ value, source });
+
+    if (config.ladder) out.ladder = tag(config.ladder);
+
+    if (config.fixes) out.fixes = tag(config.fixes);
+
+    if (config.escalate) out.escalate = tag(config.escalate);
+
+    for (const [k, v] of Object.entries(config.models ?? {})) out.models[k] = tag(v);
+
+    for (const [k, v] of Object.entries(config.lenses)) out.lenses[k] = { ...tag(v), scope: "team" };
+
+    for (const [k, v] of Object.entries(config.checks ?? {})) out.checks[k] = tag(v);
+
+    for (const [k, v] of Object.entries(config.recipes ?? {})) out.recipes[k] = tag(v);
+  }
+
+  return out;
+}
+
+/**
+ * The effective policy: built-in defaults, the team file's packs in order, the team file, then the personal
+ * preview. `personal` is the parsed ~/.config/shepherd/lenses.yml, or null.
+ */
+export function loadPolicy(read: Read, fetch: Fetch, personal: Config | null): Effective & { teamFile: string | null } {
+  const teamFile = TEAM_FILES.find((f) => read(f) !== null) ?? null;
+  const team = teamFile ? parseConfig(read(teamFile)!, teamFile) : null;
+  const packs = (team?.extends ?? []).map((ref) => readPack(ref, read, fetch));
+  const effective = merge([{ source: "built-in", config: BUILT_IN }, ...packs, ...(team ? [{ source: teamFile!, config: team }] : [])]);
+
+  // A lens may name a pinned pack directly; any skill spelled github: must be one that stays in the cache.
+  for (const [name, l] of [...Object.entries(effective.lenses), ...Object.entries(personal?.lenses ?? {}).map(([k, v]) => [k, { value: v }] as const)]) {
+    if (l.value.skill.startsWith("github:") && !safePinned(l.value.skill)) throw new Error(`lens ${name}: ${l.value.skill} is not github:owner/repo/<path>@<40-hex sha> with a path that stays in that repository`);
+  }
+
+  if (personal) {
+    const source = "personal";
+
+    // Personal fills in only what the team left open, and adds lenses that never post.
+    if (!effective.ladder && personal.ladder) effective.ladder = { value: personal.ladder, source };
+
+    for (const [k, v] of Object.entries(personal.models ?? {})) effective.models[k] ??= { value: v, source };
+
+    for (const [k, v] of Object.entries(personal.lenses)) effective.lenses[k] ??= { value: v, source, scope: "personal" };
+
+    for (const key of ["extends", "checks", "fixes", "escalate", "recipes"] as const) {
+      if (personal[key] !== undefined) effective.ignored.push(`personal ${key}: team policy, set it in ${TEAM_FILES[0]}`);
+    }
+  }
+
+  return { ...effective, teamFile };
+}
+
+type Mode = Effective["fixes"]["value"]["mode"];
+
+/** `shepherd init --preset`: how far fixes go. */
+export const PRESETS = { "review-only": "suggest", "local-fix": "local", push: "push" } as const satisfies Record<string, Mode>;
+
+/** What is wrong with a recipe: an unknown order, a fix nothing reviews, or a step the fix mode forbids. */
+export function recipeProblems(name: string, steps: Step[], mode: Mode): string[] {
+  const problems: string[] = [];
+  const at = (s: Step) => steps.indexOf(s);
+
+  if (steps.includes("incident") && at("incident") !== 0) problems.push(`recipe ${name}: incident opens the PR, so it must come first`);
+
+  if (steps.includes("stamp") && steps.lastIndexOf("stamp") !== steps.length - 1) problems.push(`recipe ${name}: stamp gives the verdict on the final head, so it must come last`);
+
+  if (steps.includes("triage") && !steps.slice(0, at("triage")).includes("swarm")) problems.push(`recipe ${name}: triage works the threads swarm posts, so a swarm must come before it`);
+
+  const lastFix = steps.map((s) => FIXERS.has(s)).lastIndexOf(true);
+
+  if (lastFix >= 0 && !steps.slice(lastFix + 1).some((s) => REVIEWS.has(s))) problems.push(`recipe ${name}: ${steps[lastFix]} changes code, so a swarm or stamp must review after it`);
+  // stamp reviews the pushed head; under local the fixes never reach it, so only a swarm of the working tree counts.
+  else if (mode === "local" && lastFix >= 0 && !steps.slice(lastFix + 1).includes("swarm")) problems.push(`recipe ${name}: fixes.mode is local, so stamp cannot see ${steps[lastFix]}'s fixes; a swarm must review after it`);
+
+  if (mode === "suggest") {
+    const fixers = steps.filter((s) => FIXERS.has(s));
+
+    if (fixers.length) problems.push(`recipe ${name}: fixes.mode is suggest, so it cannot run ${[...new Set(fixers)].join(", ")}`);
+  }
+
+  return problems;
+}
+
+/** Every problem in the effective policy that does not need the filesystem. A built-in recipe the fix mode rules out is unavailable, not a problem. */
+export const policyProblems = (p: Effective): string[] =>
+  Object.entries(p.recipes).flatMap(([name, r]) => (r.source === "built-in" ? [] : recipeProblems(name, r.value.steps, p.fixes.value.mode)));
+
+/** The recipe a plain `/shepherd` run matches under each fix mode. */
+export const DEFAULT_RECIPE: Record<Mode, string> = { suggest: "review", local: "fix", push: "pr" };
+
+/** How a recipe finishes, which is not always "ready to merge". */
+export function completion(steps: Step[], mode: Mode): string {
+  if (!steps.some((s) => FIXERS.has(s))) return steps.at(-1) === "stamp" ? "ready when stamp approves this head, CI is green and no review thread is open" : "reviewed: findings posted for the author; says nothing about merge readiness";
+
+  if (mode === "local") return "fixes_uncommitted: reviewed in your working tree; commit, push and run again before it can be ready";
+
+  return steps.at(-1) === "stamp" ? "ready when stamp approves the final head, CI is green and no review thread is open; else pending" : "reviewed after the last fix; not ready until stamp approves, CI is green and no review thread is open";
+}
+
+// What each step can write. Swarm and stamp only post; the fixers' reach is the fix mode.
+const WRITES: Record<Step, Record<Mode, string>> = {
+  swarm: { suggest: "posts review comments on the PR", local: "posts review comments on the PR", push: "posts review comments on the PR" },
+  stamp: { suggest: "posts a review (approve or request changes)", local: "posts a review (approve or request changes)", push: "posts a review (approve or request changes)" },
+  triage: { suggest: "replies on threads, changes no code", local: "edits your working tree", push: "commits and pushes to the PR branch, resolves threads" },
+  simplify: { suggest: "reports only", local: "edits your working tree", push: "commits and pushes to the PR branch" },
+  "ci-repair": { suggest: "reports only", local: "edits your working tree", push: "commits and pushes to the PR branch" },
+  incident: { suggest: "opens an incident issue", local: "opens an incident issue, edits your working tree", push: "opens an incident issue, pushes incident/<n>, opens a PR" },
+};
+
+// Built-in reviewers, and the ladder rung each runner starts on (skills/shepherd/references/models.md).
+const BUILT_IN_REVIEWERS = ["correctness", "security", "simplicity", "maintainability", "slop", "spec"];
+
+const RUNG = new Map([["router", 0], ["verifier", 1], ["triage", 1], ["simplify", 1], ["ci-repair", 1], ["validator", 2]]);
+
+/** The model each runner uses: its pin, its rung of the team ladder, or the harness's own ladder. */
+export function modelPlan(p: Effective): { runner: string; model: string; source: string }[] {
+  const names = ["router", ...BUILT_IN_REVIEWERS, ...Object.keys(p.lenses), "verifier", "triage", "simplify", "ci-repair", "validator"];
+
+  return [...new Set(names)].map((runner) => {
+    const pin = p.models[runner];
+    const rung = RUNG.get(runner) ?? 1; // a lens runs one rung above the router
+
+    if (pin) return { runner, model: pin.value, source: `pinned, ${pin.source}` };
+
+    if (p.ladder) return { runner, model: p.ladder.value[Math.min(rung, p.ladder.value.length - 1)]!, source: `rung ${rung}, ${p.ladder.source}` };
+
+    return { runner, model: `harness rung ${rung}`, source: "Claude Code: haiku > sonnet > opus; OpenCode with no ladder: the session model" };
+  });
+}
+
+const globMatch = (pattern: string, file: string) => new Bun.Glob(pattern).match(file);
+
+/** What would run on these changed files: which lenses, which checks, how fixes land, what goes to a person. */
+export function preview(p: Effective, files: string[], recipe?: string) {
+  const lenses = Object.entries(p.lenses).map(([name, l]) => {
+    const hits = l.value.applies_to ? files.filter((f) => l.value.applies_to!.some((g) => globMatch(g, f))) : null;
+
+    return { name, scope: l.scope, runs: hits === null ? "if the router calls it" : hits.length ? `on ${hits.length} file(s)` : "no matching files", files: hits ?? [] };
+  });
+
+  const escalated = p.escalate ? files.filter((f) => p.escalate!.value.paths.some((g) => globMatch(g, f))) : [];
+  const mode = p.fixes.value.mode;
+  const name = recipe ?? DEFAULT_RECIPE[mode];
+  const steps = p.recipes[name]?.value.steps;
+
+  if (!steps) throw new Error(`no recipe named ${name}; known: ${Object.keys(p.recipes).join(", ")}`);
+
+  return {
+    files,
+    lenses,
+    models: modelPlan(p),
+    checks: Object.keys(p.checks).length ? Object.entries(p.checks).map(([name, c]) => `${name}: ${c.value.command}`) : ["discovered by swarm from the repo's config"],
+    fixes: mode,
+    escalated,
+    recipe: name,
+    steps,
+    writes: [...new Set(steps)].map((s) => ({ step: s, writes: WRITES[s][mode] })),
+    unavailable: recipeProblems(name, steps, mode),
+    completes: completion(steps, mode),
+  };
+}
+
+const gitIn = (repoRoot: string) => (...args: string[]) => execFileSync("git", ["-C", repoRoot, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+
+/** The fetched ref of `origin`'s default branch. The name comes from the remote, since a CI checkout sets no origin/HEAD. */
+export function defaultBranchRef(repoRoot: string): string {
+  const git = gitIn(repoRoot);
+  const branch = /^ref: refs\/heads\/(\S+)\s+HEAD/m.exec(git("ls-remote", "--symref", "origin", "HEAD"))?.[1];
+
+  if (!branch) throw new Error("cannot tell origin's default branch");
+  const ref = `refs/remotes/origin/${branch}`;
+
+  try {
+    git("rev-parse", "--verify", "--quiet", ref);
+  } catch {
+    throw new Error(`origin/${branch} is not fetched: run git fetch origin ${branch}`);
+  }
+
+  return ref;
+}
+
+/** A reader over the default branch of `origin`, the same source the skills use. */
+export function defaultBranchReader(repoRoot: string): Read {
+  const git = gitIn(repoRoot);
+  const ref = defaultBranchRef(repoRoot);
+
+  return (rel) => {
+    try {
+      return git("show", `${ref}:${rel}`);
+    } catch {
+      return null;
+    }
+  };
+}
+
+/** Every file under a directory of a repository at a commit, as paths relative to that directory. */
+export type FetchDir = (owner: string, repo: string, dir: string, sha: string) => { path: string; content: string }[];
+
+/** Where a pinned lens directory is kept: by commit, so a cached copy never goes stale. */
+export const lensCache = (home: string, ref: string): string | null => {
+  const m = safePinned(ref);
+
+  return m ? path.join(home, ".cache", "shepherd", "packs", m[1]!, m[2]!, m[4]!, m[3]!) : null;
+};
+
+/** A pinned reference whose every part stays inside the cache: no `.` or `..` owner or repo, no escaping path. */
+const safePinned = (ref: string) => {
+  const m = PINNED.exec(ref);
+
+  return m && ![m[1], m[2]].some((part) => part === "." || part === "..") && !pathEscapes(m[3]!) && !m[3]!.split("/").includes("") && !m[3]!.includes("\\") ? m : null;
+};
+
+/**
+ * Fetch each pinned pack lens into the cache once. Each fetch writes a private temporary directory and
+ * renames it into place, so a reader never sees half a lens; a failed fetch leaves nothing behind, and when
+ * two fetch the same lens at once the first rename wins and the other's copy is dropped.
+ */
+export function fetchPackLenses(p: Effective, home: string, fetchDir: FetchDir): void {
+  for (const { value } of Object.values(p.lenses)) {
+    const m = safePinned(value.skill);
+    const dest = lensCache(home, value.skill);
+
+    if (!m || !dest || existsSync(path.join(dest, "SKILL.md"))) continue;
+    mkdirSync(path.dirname(dest), { recursive: true });
+    sweepStale(dest);
+    const tmp = mkdtempSync(`${dest}.tmp-`);
+
+    try {
+      const files = fetchDir(m[1]!, m[2]!, m[3]!, m[4]!);
+
+      if (!files.some((f) => f.path === "SKILL.md")) throw new Error(`${value.skill}: no SKILL.md in that directory`);
+
+      for (const f of files) {
+        if (pathEscapes(f.path)) throw new Error(`${value.skill}: unsafe file path ${f.path}`);
+        mkdirSync(path.dirname(path.join(tmp, f.path)), { recursive: true });
+        writeFileSync(path.join(tmp, f.path), f.content);
+      }
+
+      // A directory without SKILL.md is no lens: an older, interrupted layout. Nothing reads it; replace it.
+      if (existsSync(dest) && !existsSync(path.join(dest, "SKILL.md"))) rmSync(dest, { recursive: true, force: true });
+
+      try {
+        renameSync(tmp, dest);
+      } catch (error) {
+        if (!existsSync(path.join(dest, "SKILL.md"))) throw error; // another fetch got there first otherwise
+      }
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+}
+
+/** Remove temporary fetch directories for `dest` that a killed process left, once they are an hour old. */
+function sweepStale(dest: string): void {
+  const prefix = `${path.basename(dest)}.tmp-`;
+
+  for (const name of readdirSync(path.dirname(dest))) {
+    const dir = path.join(path.dirname(dest), name);
+
+    if (name.startsWith(prefix) && Date.now() - statSync(dir).mtimeMs > 3_600_000) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** A directory through `gh`, recursively, at that commit. */
+export const ghFetchDir: FetchDir = (owner, repo, dir, sha) => {
+  verifyPinned(owner, repo, sha);
+  const api = (p: string, raw: boolean) => execFileSync("gh", ["api", ...(raw ? ["-H", "Accept: application/vnd.github.raw"] : []), `repos/${owner}/${repo}/contents/${p}?ref=${sha}`], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  const Entries = z.array(z.object({ path: z.string(), type: z.string() }));
+
+  const walk = (p: string): { path: string; content: string }[] =>
+    Entries.parse(JSON.parse(api(p, false))).flatMap((e) => (e.type === "dir" ? walk(e.path) : e.type === "file" ? [{ path: path.posix.relative(dir, e.path), content: api(e.path, true) }] : []));
+
+  return walk(dir);
+};
+
+const gh = (...args: string[]) => execFileSync("gh", ["api", ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+
+/**
+ * GitHub serves any commit in a repository's fork network through that repository, so a pin alone could name
+ * a commit someone pushed to a fork. A pin counts only when the commit is on the repository's default branch.
+ */
+export function verifyPinned(owner: string, repo: string, sha: string): void {
+  const branch = gh(`repos/${owner}/${repo}`, "--jq", ".default_branch").trim();
+  let status: string;
+
+  try {
+    status = gh(`repos/${owner}/${repo}/compare/${branch}...${sha}`, "--jq", ".status").trim();
+  } catch (error) {
+    // An unrelated history (say a fork's orphan commit) has no merge base: GitHub answers 404.
+    if (!/No common ancestor/.test(String(Object(error).stderr))) throw error;
+    status = "unrelated";
+  }
+
+  if (status !== "behind" && status !== "identical") throw new Error(`github:${owner}/${repo}@${sha}: that commit is not on ${owner}/${repo}'s ${branch} branch; pin a commit from its history`);
+}
+
+/** A pinned pack through `gh`, as raw file contents at that commit. */
+export const ghFetch: Fetch = (owner, repo, file, sha) => {
+  verifyPinned(owner, repo, sha);
+
+  return gh("-H", "Accept: application/vnd.github.raw", `repos/${owner}/${repo}/contents/${file}?ref=${sha}`);
+};

package/src/doctor.ts

@@ -0,0 +1,153 @@
+// `shepherd doctor`: is this machine and repository set up to run shepherd? Each check says what to do.
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { parse } from "yaml";
+import { z } from "zod";
+import { defaultBranchReader, defaultBranchRef, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, type Config } from "./config.ts";
+import { bundledSkills } from "./install.ts";
+import { lensProblems } from "./lens.ts";
+
+export type Check = { check: string; status: "ok" | "warn" | "fail"; detail: string; fix?: string };
+
+const run = (cmd: string, args: string[], cwd?: string) => execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30_000 });
+
+const attempt = <T>(f: () => T): T | Error => {
+  try {
+    return f();
+  } catch (error) {
+    return error instanceof Error ? error : new Error(String(error));
+  }
+};
+
+// Where a harness looks for skills: Claude Code, the shared .agents layout, Codex, OpenCode.
+const SKILL_DIRS = (home: string, repo: string) => [
+  path.join(home, ".claude/skills"),
+  path.join(repo, ".claude/skills"),
+  path.join(home, ".agents/skills"),
+  path.join(repo, ".agents/skills"),
+  path.join(home, ".codex/skills"),
+  path.join(home, ".config/opencode/skills"),
+];
+
+/**
+ * True when a workflow runs stamp on pull requests: a step that uses stamp's action, runs its package, or
+ * checks out its repository and then runs from that checkout. The word "stamp" alone is not enough.
+ */
+export function runsStamp(text: string): boolean {
+  const parsed = Workflow.safeParse(attempt(() => parse(text)));
+
+  if (!parsed.success) return false;
+
+  if (!parsed.data.on.some((t) => t === "pull_request" || t === "pull_request_target")) return false;
+
+  return Object.values(parsed.data.jobs).some(({ steps }) => {
+    const checkouts = steps.filter((st) => st.with?.repository === "jagreehal/stamp").map((st) => st.with?.path ?? ".");
+
+    return steps.some((st) => st.uses?.startsWith("jagreehal/stamp") || st.run?.includes("@jagreehal/stamp") || checkouts.some((p) => p !== "." && st.run?.includes(`${p}/`)));
+  });
+}
+
+const Workflow = z.object({
+  on: z.union([z.string().transform((t) => [t]), z.array(z.string()), z.record(z.string(), z.unknown()).transform((o) => Object.keys(o))]),
+  jobs: z.record(z.string(), z.object({ steps: z.array(z.object({ uses: z.string().optional(), run: z.string().optional(), with: z.object({ repository: z.string().optional(), path: z.string().optional() }).passthrough().optional() }).passthrough()).default([]) }).passthrough()),
+});
+
+const CLAUDE_MODELS = /^(haiku|sonnet|opus|fable)$|^claude-/;
+
+export function doctor(bundleRoot: string, home: string, repo: string, personal: Config | null): Check[] {
+  const checks: Check[] = [];
+
+  const add = (check: string, status: Check["status"], detail: string, fix?: string) => {
+    const c: Check = { check, status, detail };
+
+    if (fix) c.fix = fix;
+    checks.push(c);
+  };
+
+  const auth = attempt(() => run("gh", ["auth", "status"]));
+
+  if (auth instanceof Error) add("gh auth", "fail", "gh is missing or not signed in", "gh auth login (shepherd reads and writes GitHub through gh)");
+  else add("gh auth", "ok", "signed in");
+
+  // The skills call `shepherd` for local change capture and receipts, else `bunx @jagreehal/shepherd`.
+  if (attempt(() => run("sh", ["-c", "command -v shepherd"])) instanceof Error) {
+    add("shepherd cli", "warn", "not on PATH: the skills fall back to bunx @jagreehal/shepherd, which needs the package published on npm and network access on every call", "bun add -g @jagreehal/shepherd, or put a shepherd wrapper on PATH");
+  } else add("shepherd cli", "ok", "on PATH");
+
+  const read = attempt(() => defaultBranchReader(repo));
+
+  if (read instanceof Error) add("default branch", "fail", read.message, "git fetch origin <default branch>: policy and lenses are read from it");
+  else add("default branch", "ok", "fetched");
+
+  const missing = bundledSkills(path.join(bundleRoot, "skills")).filter((s) => !SKILL_DIRS(home, repo).some((d) => existsSync(path.join(d, s, "SKILL.md"))));
+
+  if (missing.length) add("skills", "fail", `not installed: ${missing.join(", ")}`, "bunx @jagreehal/shepherd install (or --project, or --target <your agent's skills dir>)");
+  else add("skills", "ok", "every bundled skill is installed");
+
+  if (read instanceof Error) return checks;
+
+  const policy = attempt(() => {
+    const p = loadPolicy(read, ghFetch, personal);
+
+    fetchPackLenses(p, home, ghFetchDir);
+
+    return p;
+  });
+
+  if (policy instanceof Error) {
+    const pack = /github:[\w.-]+\/[\w.-]+/.exec(policy.message)?.[0];
+
+    add("policy", "fail", policy.message.split("\n")[0]!, pack ? `gh must read ${pack.slice(7)}: sign gh in as an account with access, or set GH_TOKEN to a token that can read it` : "fix the file on the default branch; shepherd config validate checks your edits");
+
+    return checks;
+  }
+
+  add("policy", "ok", policy.teamFile ? `${policy.teamFile}, fixes.mode ${policy.fixes.value.mode}` : "no policy file: built-in defaults", policy.teamFile ? undefined : "bunx @jagreehal/shepherd init");
+
+  for (const [name, l] of Object.entries(policy.lenses)) {
+    const problems = lensProblems(l.value, home, repo);
+
+    if (problems.length) add(`lens ${name}`, "fail", problems.join("; "), `from ${l.source}: add the skill to this repository or install it for the agent (see "Packs and lens files" in policy.md)`);
+  }
+
+  const models = [...new Set([...(policy.ladder?.value ?? []), ...Object.values(policy.models).map((m) => m.value)])];
+  const opencode = models.some((m) => m.includes("/")) ? attempt(() => run("opencode", ["models"])) : null;
+
+  for (const model of models) {
+    if (CLAUDE_MODELS.test(model)) add(`model ${model}`, "ok", "a Claude Code model id");
+    else if (!model.includes("/")) add(`model ${model}`, "warn", "not a known id; it passes to the agent tool as written", "check the harness accepts it");
+    else if (opencode instanceof Error || opencode === null) add(`model ${model}`, "warn", "cannot list OpenCode models", "install opencode, or ignore if another harness runs it");
+    else if (opencode.split("\n").includes(model)) add(`model ${model}`, "ok", "listed by opencode models");
+    else add(`model ${model}`, "fail", "opencode models does not list it", "fix the id, or sign in to its provider (opencode auth login)");
+  }
+
+  if (!models.length) add("models", "ok", "no ladder set: the harness's own (shepherd models)");
+
+  const workflows = attempt(() => run("git", ["-C", repo, "ls-tree", "--name-only", "-r", defaultBranchRef(repo), ".github/workflows/"]));
+  const stamp = (workflows instanceof Error ? [] : workflows.split("\n").filter(Boolean)).find((f) => runsStamp(read(f) ?? ""));
+
+  if (!stamp) {
+    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");
+
+    return checks;
+  }
+
+  add("stamp workflow", "ok", `${stamp} runs stamp on pull requests`);
+  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());
+
+  if (last instanceof Error) add("stamp runs", "warn", "cannot read its runs through gh", "check gh can read this repository's Actions");
+  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");
+  else {
+    const [status, conclusion, url, id] = last.split("\t");
+    // stamp exits 1 on a refusal or an escalation: the run failed, but stamp worked and gave its verdict.
+    const verdict = conclusion === "failure" ? /\b(REFUSED|ESCALATE): /.exec(String(attempt(() => run("gh", ["run", "view", id!, "--log-failed"], repo))))?.[1] : undefined;
+
+    if (conclusion === "success") add("stamp runs", "ok", "its latest run approved");
+    else if (verdict) add("stamp runs", "ok", `its latest run gave a verdict (${verdict}): ${url}`);
+    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");
+    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)");
+  }
+
+  return checks;
+}