@jagreehal/shepherd 0.4.0 → 0.5.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 (41) hide show
  1. package/README.md +1 -0
  2. package/THIRD_PARTY_NOTICES.md +11 -0
  3. package/lenses/dotnet/SKILL.md +32 -0
  4. package/lenses/go/SKILL.md +30 -0
  5. package/lenses/java/SKILL.md +31 -0
  6. package/lenses/nextjs/SKILL.md +33 -0
  7. package/lenses/node-api/SKILL.md +32 -0
  8. package/lenses/nx-monorepo/SKILL.md +30 -0
  9. package/lenses/owasp-asvs/SKILL.md +50 -0
  10. package/lenses/owasp-llm/SKILL.md +44 -0
  11. package/lenses/python/SKILL.md +32 -0
  12. package/lenses/react/SKILL.md +33 -0
  13. package/lenses/rust/SKILL.md +31 -0
  14. package/package.json +2 -1
  15. package/packs/dotnet.yml +6 -0
  16. package/packs/go.yml +6 -0
  17. package/packs/java.yml +6 -0
  18. package/packs/nextjs.yml +7 -0
  19. package/packs/node-api.yml +7 -0
  20. package/packs/nx-monorepo.yml +6 -0
  21. package/packs/observability.yml +6 -0
  22. package/packs/owasp-asvs.yml +6 -0
  23. package/packs/owasp-llm.yml +8 -0
  24. package/packs/python.yml +6 -0
  25. package/packs/react.yml +6 -0
  26. package/packs/rust.yml +6 -0
  27. package/skills/lens-import/SKILL.md +185 -0
  28. package/skills/lens-import/references/conversion.md +96 -0
  29. package/skills/lens-import/scripts/check-import.mjs +154 -0
  30. package/skills/shepherd/SKILL.md +26 -5
  31. package/skills/shepherd/references/models.md +20 -7
  32. package/skills/shepherd/references/policy.md +9 -5
  33. package/skills/swarm/SKILL.md +11 -1
  34. package/skills/swarm/references/custom-lenses.md +50 -7
  35. package/src/cli.ts +96 -13
  36. package/src/config.ts +137 -21
  37. package/src/lens.ts +159 -8
  38. package/src/stack.ts +121 -0
  39. package/templates/shepherd-audit.yml +178 -0
  40. package/templates/shepherd-incident.yml +28 -4
  41. package/templates/shepherd.yml +32 -4
@@ -15,6 +15,18 @@ lenses:
15
15
  skill: vercel-react-best-practices # an installed skill's name, or a path to a skill directory
16
16
  applies_to: ['**/*.tsx', '**/*.jsx'] # optional; without it only the router picks the lens
17
17
  description: React and Next.js performance rules # optional; defaults to the skill's own description
18
+ only: ['rerender-*', 'client-*'] # optional rule id globs: review only these rules
19
+ disable: ['client-swr-dedup'] # optional rule id globs: skip these rules
20
+ gate: escalate # optional; stamp's on_break for untagged rules, swarm ignores it
21
+ ```
22
+
23
+ A later layer merges into a lens of the same name field by field. A
24
+ repository trims or rescopes a pack's lens by naming it, with no `skill`:
25
+
26
+ ```yaml
27
+ extends: ['github:jagreehal/shepherd/packs/react.yml@<sha>']
28
+ lenses:
29
+ react: { disable: ['html-injection'], applies_to: ['web/**/*.tsx'] }
18
30
  ```
19
31
 
20
32
  Swarm merges two files, repository entries winning on a name clash:
@@ -35,6 +47,23 @@ Swarm merges two files, repository entries winning on a name clash:
35
47
  starts from a bundled starter lens instead (`lenses/`, such as `observability`). Run `/swarm --preview`
36
48
  on a PR or a local branch to see what it finds before you commit it; preview
37
49
  reads lenses from the working tree and posts nothing.
50
+ `shepherd init --stacks` detects the stacks a repository uses and adds a lens
51
+ for each from the bundled catalogue.
52
+
53
+ ## The bundled catalogue
54
+
55
+ Each starter lens lives in `lenses/<name>` with a pack in `packs/<name>.yml`:
56
+ `react`, `nextjs` (extends `react`), `node-api`, `go`, `rust`, `java`,
57
+ `dotnet`, `python`, `observability`. Take one three ways:
58
+
59
+ - Copy it to own and edit it: `shepherd lens new <name> --from <name>`, or
60
+ `shepherd init --stacks` for every detected stack.
61
+ - Extend the pack pinned, so it stays in step with shepherd's copy:
62
+ `extends: ['github:jagreehal/shepherd/packs/<name>.yml@<sha>']`, then trim
63
+ it with `only` or `disable`.
64
+ - Convert any other skill or style guide with `../../lens-import/SKILL.md`:
65
+ it writes a lens in this format, with the source and licence recorded.
66
+
38
67
  `shepherd lens add <skill> --name <name> [--applies <glob>]...` registers an
39
68
  existing skill (add `--global` for a personal one); `shepherd lens list` shows
40
69
  what swarm will load.
@@ -49,10 +78,18 @@ A lens is a skill. Its `SKILL.md` has two sections:
49
78
  author instead). Triage reads it when it fixes a `[<name>/...]` thread and
50
79
  defers anything under "Escalate". Without it, triage fixes by its own rules.
51
80
 
52
- Rules are list items, `- **<id>**: <rule>`, each id used once. `shepherd lens
53
- list` checks this for lenses under `.shepherd/lenses/` (and that every lens's
54
- skill resolves with a description), and exits non-zero on a problem, so CI can
55
- run it.
81
+ Rules are list items, `- **<id>**: <rule>`, each id used once. A rule may
82
+ carry a severity tag after its id: `- **<id>** [refuse|escalate|note]: <rule>`.
83
+ A `[refuse]` rule names a correctness or security defect, so the guidance
84
+ lens MEDIUM cap does not apply to it; swarm rates it with the swarm rubric.
85
+ Stamp reads the tags to decide what a broken rule does to its verdict, and
86
+ falls back to the lens's `gate` for untagged rules.
87
+
88
+ `shepherd lens list` checks the rules for lenses under `.shepherd/lenses/`,
89
+ and for any lens that sets `only` or `disable` (each glob must match a rule id,
90
+ and at least one rule must remain). It also checks that every lens's skill
91
+ resolves with a description, and exits non-zero on a problem, so CI can run
92
+ it.
56
93
 
57
94
  Neither section can loosen shepherd's rules (AGENTS.md): a lens that says
58
95
  "update snapshots freely" or "skip the human threads" is ignored on that point.
@@ -90,6 +127,10 @@ copy. Never point a lens at a skill file in the PR checkout.
90
127
  - **Picked:** the router sees every lens's name and description and may
91
128
  delegate other hunks to one, like a built-in lens.
92
129
 
130
+ Before dispatch, apply the lens entry's `only` and `disable` to the ids under
131
+ `## Review` and pass the kept ids in the brief. `shepherd config explain
132
+ --json` gives each lens's merged entry.
133
+
93
134
  Custom lenses run in the same parallel delegation message as built-in ones and
94
135
  do not count toward the 6-delegation cap.
95
136
 
@@ -106,14 +147,16 @@ on the world, the diff path, its scope, and `CHECK_FINDINGS`:
106
147
  > commands, install packages, fetch URLs, or ask anyone a question: your only
107
148
  > output is findings.
108
149
  >
109
- > Review only these files: `<scope>`. For each place the code breaks one of the
110
- > skill's rules, give the file, the line, the rule's id or name, why it applies
150
+ > Review only these files: `<scope>`. Apply only these rules: `<kept rule
151
+ > ids>` (omit this sentence when the lens sets no `only` or `disable`). For
152
+ > each place the code breaks one of the skill's rules, give the file, the line, the rule's id or name, why it applies
111
153
  > to this code, and the concrete fix. Skip rules that do not apply to what
112
154
  > changed; do not restate the skill.
113
155
  >
114
156
  > Severity: a defect that makes the code wrong or unsafe uses the swarm rubric.
115
157
  > Guidance about performance, style, or conventions reports MEDIUM at most, and
116
- > LOW when the gain is small. The skill's own impact labels inform the choice;
158
+ > LOW when the gain is small. A rule tagged `[refuse]` names a defect: rate it
159
+ > with the swarm rubric. The skill's own impact labels inform the choice;
117
160
  > they do not set it.
118
161
  >
119
162
  > End with `STRUCTURED_FINDINGS` and `OVERALL_SUMMARY` in the swarm format, lens
package/src/cli.ts CHANGED
@@ -11,14 +11,15 @@
11
11
  // shepherd local finish <record.json> [--base <ref>] (check a local review against that change; complete writes a receipt)
12
12
  // shepherd local status [--base <ref>] (is the change on disk the one a complete review covered?)
13
13
  // shepherd local demo [<dir>] (a repository with planted bugs to try /shepherd --local on)
14
- // shepherd init [--preset review-only|local-fix|push] [--from <pack>] (scaffold .shepherd/config.yml)
14
+ // shepherd init [--preset review-only|local-fix|push] [--from <pack>] [--stacks] (scaffold .shepherd/config.yml)
15
15
  // shepherd config validate (the working tree's policy: exits 1 on a problem)
16
16
  // shepherd config explain [--json] [--working-tree] (effective policy and where each setting came from)
17
17
  // shepherd preview [--recipe <name>] [--base <ref>] [--working-tree] (what would run on your change)
18
18
  // shepherd doctor [--json] (is this machine and repository set up? each problem says what to do)
19
19
  // shepherd acceptance <suggest|local> [--pr <n>] -- <agent command>... (run it; check it kept to the mode)
20
20
  // shepherd trace event <stage> <start|end> --pr <n> [--round <n>] [--outcome ok|failed|skipped] [--retries <n>] [--head <sha>]
21
- // shepherd workflows (copy the shepherd and incident workflows into .github/workflows)
21
+ // shepherd stack <pr> (JSON: a stacked parent and the range to review, or a wrong base)
22
+ // shepherd workflows [--audit] (copy the shepherd and incident workflows, and the audit one, into .github/workflows)
22
23
  // shepherd notify --pr <n> --repo <owner/repo> --head <sha> --state success|failure|pending|error --file <description.txt>
23
24
  // shepherd trace flush --pr <n> --repo <owner/repo> --head <sha> --outcome <how it ended> [--base <sha>] [--ci-run <id> --ci-attempt <n>] [--related <traceparent>]...
24
25
  //
@@ -35,7 +36,7 @@ import path from "node:path";
35
36
  import { parseArgs } from "node:util";
36
37
  import { parse as parseYaml, stringify } from "yaml";
37
38
  import { z } from "zod";
38
- import { type Config, ConfigSchema, defaultBranchReader, type Effective, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, policyProblems, PRESETS, preview, type Read, TEAM_FILES } from "./config.ts";
39
+ import { CI_DEFAULT_MODEL, ciModel, type Config, ConfigSchema, defaultBranchReader, type Effective, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, policyProblems, PRESETS, preview, type Read, TEAM_FILES } from "./config.ts";
39
40
  import { ghThreads, snapshot, verdict } from "./acceptance.ts";
40
41
  import { doctor } from "./doctor.ts";
41
42
  import { fileLedger, notify, notifyOn, STATES, statusLedger } from "./notify.ts";
@@ -43,8 +44,9 @@ import { collect, collectEscapes, score } from "./garden.ts";
43
44
  import { collectTraces, tempoHeaders, traceLimits, traceScores } from "./garden-traces.ts";
44
45
  import { install, type Outcome, pinWorkflow, uninstall } from "./install.ts";
45
46
  import { buildDemo, captureChange, demoBugs, finish, receiptStatus } from "./local.ts";
47
+ import { prStack } from "./stack.ts";
46
48
  import { flush, recordEvent, traceFile } from "./trace.ts";
47
- import { addLens, BUILT_IN_LENSES, lensTemplates, globalLensFile, lensProblems, newLens, opencodeAgents, pinModel, repoLensFile, resolveSkill, setLadder, skillDescription, type Lens } from "./lens.ts";
49
+ import { addLens, BUILT_IN_LENSES, lensTemplates, globalLensFile, lensProblems, newLens, opencodeAgents, opencodeModel, providerKeyEnv, setTier, detectStacks, stackLens, pinModel, repoLensFile, resolveSkill, setLadder, skillDescription, type Lens } from "./lens.ts";
48
50
 
49
51
  const BUNDLE_ROOT = path.resolve(import.meta.dir, "..");
50
52
 
@@ -53,14 +55,15 @@ const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [
53
55
  shepherd lens new <name> [--from <template>] [--applies <glob>]... [--description <text>]
54
56
  shepherd lens add <skill> [--name <name>] [--applies <glob>]... [--description <text>] [--global]
55
57
  shepherd lens list
56
- shepherd models [ladder <model>... | pin <lens-or-runner> <model>] [--global]
58
+ shepherd models [tier <name> <model> | ladder <model-or-tier>... | pin <runner-lens-or-group> <model-or-tier>] [--global]
59
+ shepherd ci-models
57
60
  shepherd opencode-agents [--file <lenses.yml>]
58
61
  shepherd garden <owner/repo>... [--since YYYY-MM-DD] [--min-prs <n>] [--traces <otlp.json>]... [--tempo-url <url>] [--trace-retries <n>] [--trace-wait-ms <ms>] [--trace-cost-usd <usd>]
59
62
  shepherd local change [--base <ref>]
60
63
  shepherd local finish <record.json> [--base <ref>]
61
64
  shepherd local status [--base <ref>]
62
65
  shepherd local demo [<dir>]
63
- shepherd init [--preset review-only|local-fix|push] [--from <pack>]
66
+ shepherd init [--preset review-only|local-fix|push] [--from <pack>] [--stacks]
64
67
  shepherd config validate
65
68
  shepherd config explain [--json] [--working-tree]
66
69
  shepherd preview [--recipe <name>] [--base <ref>] [--working-tree]
@@ -68,7 +71,9 @@ const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [
68
71
  shepherd acceptance <suggest|local> [--pr <n>] -- <agent command>...
69
72
  shepherd trace event <stage> <start|end> --pr <n> [--round <n>] [--outcome ok|failed|skipped] [--retries <n>] [--head <sha>]
70
73
  shepherd trace flush --pr <n> --repo <owner/repo> --head <sha> --outcome <how it ended> [--base <sha>] [--ci-run <id> --ci-attempt <n>] [--related <traceparent>]...
71
- shepherd workflows
74
+ shepherd stack <pr>
75
+ shepherd model-id <provider:model | provider/model>
76
+ shepherd workflows [--audit]
72
77
  shepherd notify --pr <n> --repo <owner/repo> --head <sha> --state success|failure|pending|error --file <description.txt>`;
73
78
 
74
79
  const { values: opts, positionals } = parseArgs({
@@ -97,6 +102,8 @@ const { values: opts, positionals } = parseArgs({
97
102
  "working-tree": { type: "boolean", default: false }, // explain, preview: your edits instead of the default branch
98
103
  recipe: { type: "string" },
99
104
  preset: { type: "string" }, // init: how far fixes go
105
+ audit: { type: "boolean", default: false }, // workflows: also the scheduled OWASP playbook audit
106
+ stacks: { type: "boolean", default: false }, // init: add a lens for each stack the repository uses
100
107
  pr: { type: "string" }, // acceptance: the PR whose threads must stay as they were; trace: the PR
101
108
  round: { type: "string" }, // trace: the quality-loop round
102
109
  outcome: { type: "string" }, // trace: how a step or iteration ended
@@ -209,17 +216,24 @@ if (command === "install") {
209
216
  process.exitCode = 1;
210
217
  }
211
218
  }
212
- } else if (command === "models" && (sub === undefined || (sub === "ladder" && skillRef) || (sub === "pin" && skillRef && rest.length === 1))) {
219
+ } else if (command === "models" && (sub === undefined || (sub === "ladder" && skillRef) || ((sub === "pin" || sub === "tier") && skillRef && rest.length === 1))) {
213
220
  const file = opts.global ? globalLensFile(homedir()) : repoLensFile(repoRoot);
214
221
 
222
+ if (sub === "tier") orExit(() => setTier(file, skillRef!, rest[0]!));
223
+
215
224
  if (sub === "ladder") orExit(() => setLadder(file, [skillRef!, ...rest]));
216
225
 
217
226
  if (sub === "pin") orExit(() => pinModel(file, skillRef!, rest[0]!));
218
- const { ladder, models } = choice(policy(true));
227
+ const effective = policy(true);
228
+ const { ladder, models } = choice(effective);
229
+
230
+ const spelled = (id: string) => (opencodeModel(id) === id ? id : `${id} (OpenCode: ${opencodeModel(id)})`);
219
231
 
220
- console.log(`ladder ${ladder?.join(" -> ") ?? "the harness's own (skills/shepherd/references/models.md)"}`);
232
+ for (const [name, t] of Object.entries(effective.tiers)) console.log(`tier ${name.padEnd(18)} ${spelled(t.value)} (${t.source})`);
221
233
 
222
- for (const [name, model] of Object.entries(models)) console.log(`pin ${name.padEnd(18)} ${model}`);
234
+ console.log(`ladder ${ladder?.map(spelled).join(" -> ") ?? "the harness's own (skills/shepherd/references/models.md)"}`);
235
+
236
+ for (const [name, model] of Object.entries(models)) console.log(`pin ${name.padEnd(18)} ${spelled(model)}`);
223
237
 
224
238
  if (sub) console.log(`\nwritten to ${file}${opts.global ? "" : `\n${MERGE_NOTE}`}`);
225
239
  } else if (command === "opencode-agents") {
@@ -309,12 +323,26 @@ if (command === "install") {
309
323
 
310
324
  console.log(JSON.stringify(result, null, 2));
311
325
  }
326
+ } else if (command === "ci-models") {
327
+ // Everything a workflow needs to run OpenCode on the team's models, read from the default branch: the session
328
+ // model, the variable its key goes in, and the agents that carry the ladder and pins.
329
+ const p = orExit(() => loadPolicy(orExit(() => defaultBranchReader(repoRoot)), ghFetch, null));
330
+ const { model, source } = ciModel(p, process.env.SHEPHERD_MODEL || undefined);
331
+ const session = opencodeModel(model);
332
+
333
+ console.log(JSON.stringify({ model: session, source, key_env: providerKeyEnv(session), opencode: opencodeAgents(choice(p)) }));
334
+ } else if (command === "model-id" && sub) {
335
+ // A model id as OpenCode spells it, so stamp's provider:model spelling works in a local OpenCode run too.
336
+ console.log(opencodeModel(sub));
337
+ } else if (command === "stack" && sub) {
338
+ // Which diff to review: the delta over an open stacked parent, or nothing at all when the base is wrong.
339
+ console.log(JSON.stringify(orExit(() => prStack(Number(sub), repoRoot)), null, 2));
312
340
  } else if (command === "workflows") {
313
341
  const dest = path.join(repoRoot, ".github", "workflows");
314
342
 
315
343
  mkdirSync(dest, { recursive: true });
316
344
 
317
- for (const name of ["shepherd.yml", "shepherd-incident.yml"]) {
345
+ for (const name of ["shepherd.yml", "shepherd-incident.yml", ...(opts.audit ? ["shepherd-audit.yml"] : [])]) {
318
346
  const to = path.join(dest, name);
319
347
 
320
348
  if (existsSync(to)) {
@@ -347,7 +375,15 @@ if (command === "install") {
347
375
  } else if (command === "init") {
348
376
  const file = path.join(repoRoot, TEAM_FILES[0]!);
349
377
 
350
- if (existsSync(file)) orExit(() => { throw new Error(`${TEAM_FILES[0]} already exists; edit it, then run shepherd config validate`); });
378
+ // With --stacks on an existing policy, add the detected stacks' lenses it lacks and keep everything else.
379
+ if (existsSync(file) && opts.stacks) {
380
+ addStackLenses(file);
381
+ validate();
382
+ console.log(MERGE_NOTE);
383
+ process.exit(process.exitCode ?? 0);
384
+ }
385
+
386
+ if (existsSync(file)) orExit(() => { throw new Error(`${TEAM_FILES[0]} already exists; edit it, add stack lenses with shepherd init --stacks, then run shepherd config validate`); });
351
387
  const legacy = workingTree(TEAM_FILES[1]!);
352
388
  const seed = legacy ? orExit(() => ConfigSchema.parse(parseYaml(legacy) ?? {})) : { lenses: {} };
353
389
  // A new repository starts review-only. A migration keeps pushing, as it did, and says so in the file; a pack keeps the pack's mode.
@@ -361,9 +397,22 @@ if (command === "install") {
361
397
  if (opts.from) config.extends = [opts.from, ...(seed.extends ?? [])];
362
398
 
363
399
  if (mode) config.fixes = { mode };
400
+ const stacks = detectStacks(trackedFiles(), workingTree);
401
+
364
402
  mkdirSync(path.dirname(file), { recursive: true });
365
403
  writeFileSync(file, `# shepherd team policy. Presets: review-only (fixes.mode suggest), local-fix (local), push.\n${stringify(config)}`);
366
404
  console.log(`wrote ${TEAM_FILES[0]}${preset ? ` (preset ${preset})` : ""}${legacy ? ` from ${TEAM_FILES[1]} (delete it: ${TEAM_FILES[0]} now wins)` : ""}`);
405
+
406
+ // After the file exists, so a pack named by --from counts as already providing its lenses.
407
+ if (opts.stacks) addStackLenses(file);
408
+ else if (stacks.length) console.log(`detected ${stacks.join(", ")}: run shepherd init --stacks to add their lenses, or extend github:jagreehal/shepherd/packs/<stack>.yml@<sha>`);
409
+
410
+ const named = policy(true);
411
+
412
+ if (!Object.keys(named.tiers).length && !named.ladder && !Object.keys(named.models).length) {
413
+ console.log(`models: none named. Locally runners use your harness's models; in CI the session runs on ${CI_DEFAULT_MODEL}.\n Name a cheap and a strong model, then give roles to them:\n shepherd models tier fast <provider:model>\n shepherd models tier smart <provider:model>\n shepherd models ladder fast smart\n shepherd models pin reviewers fast (and: pin fixers smart, pin loop smart)`);
414
+ }
415
+
367
416
  validate();
368
417
  console.log(`\nBefore you merge it:\n shepherd config explain --working-tree every setting and where it came from\n shepherd preview --working-tree what would run on your change, and what it can write\n${MERGE_NOTE}`);
369
418
  } else if (command === "config" && sub === "validate") {
@@ -424,6 +473,14 @@ if (command === "install") {
424
473
  process.exit(2);
425
474
  }
426
475
 
476
+ function trackedFiles(): string[] {
477
+ try {
478
+ return execFileSync("git", ["-C", repoRoot, "ls-files", "-z"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 }).split("\0").filter(Boolean);
479
+ } catch {
480
+ return [];
481
+ }
482
+ }
483
+
427
484
  function workingTree(rel: string): string | null {
428
485
  const file = path.join(repoRoot, rel);
429
486
 
@@ -436,6 +493,29 @@ function personal(): Config | null {
436
493
  return existsSync(file) ? ConfigSchema.parse(parseYaml(readFileSync(file, "utf8")) ?? {}) : null;
437
494
  }
438
495
 
496
+ /**
497
+ * Add a starter lens for each detected stack the effective team policy lacks. A lens a pack provides, or the
498
+ * file declares, is kept as it is: its skill, scope and gate are the team's.
499
+ */
500
+ function addStackLenses(file: string): void {
501
+ const have = policy(true).lenses;
502
+ const stacks = detectStacks(trackedFiles(), workingTree);
503
+
504
+ for (const s of stacks) {
505
+ const lens = have[s];
506
+
507
+ if (lens?.scope === "team") {
508
+ console.log(`lens ${s}: kept, from ${lens.source}`);
509
+ continue;
510
+ }
511
+
512
+ orExit(() => addLens(file, s, stackLens(repoRoot, s)));
513
+ console.log(`lens ${s}: .shepherd/lenses/${s} from the ${s} starter; trim its rules with only or disable`);
514
+ }
515
+
516
+ if (!stacks.length) console.log("no stack detected");
517
+ }
518
+
439
519
  /** Team policy from the default branch, the source swarm reviews under, or from your working tree. */
440
520
  function policy(fromTree: boolean) {
441
521
  const read: Read = fromTree ? workingTree : orExit(() => defaultBranchReader(repoRoot));
@@ -472,6 +552,9 @@ function explain(p: Effective & { teamFile: string | null }): void {
472
552
 
473
553
  console.log(`policy file: ${p.teamFile ?? "none (built-in defaults)"}${opts["working-tree"] ? ", working tree" : ", default branch"}\n`);
474
554
  row("fixes.mode", p.fixes.value.mode, p.fixes.source);
555
+
556
+ for (const [k, v] of Object.entries(p.tiers)) row(`tiers.${k}`, v.value, v.source);
557
+
475
558
  row("ladder", p.ladder?.value.join(" -> ") ?? "the harness's own", p.ladder?.source ?? "built-in");
476
559
 
477
560
  for (const [k, v] of Object.entries(p.models)) row(`models.${k}`, v.value, v.source);
package/src/config.ts CHANGED
@@ -12,18 +12,26 @@ import { parse } from "yaml";
12
12
 
13
13
  const NAME = /^[a-z][a-z0-9-]*$/;
14
14
 
15
+ export const SEVERITIES = ["refuse", "escalate", "note"] as const;
16
+
15
17
  export const LensSchema = z
16
18
  .object({
17
19
  skill: z.string().min(1),
18
20
  applies_to: z.array(z.string().min(1)).optional(),
19
21
  description: z.string().min(1).optional(),
22
+ gate: z.enum(SEVERITIES).optional(), // stamp's on_break for this lens's untagged rules; swarm reads the tags only
23
+ only: z.array(z.string().min(1)).min(1).optional(), // rule id globs to keep
24
+ disable: z.array(z.string().min(1)).min(1).optional(), // rule id globs to drop
20
25
  })
21
26
  .strict();
22
27
 
23
28
  export type Lens = z.infer<typeof LensSchema>;
24
29
 
25
- // A model id is whatever the harness's agent tool accepts, passed through untouched: `haiku` on Claude Code,
26
- // `provider/model` on OpenCode (`opencode-go/deepseek-v4-flash`). shepherd never maps one to another.
30
+ // In one layer a lens may leave out its skill: it then trims or rescopes the lens of that name an earlier layer defined.
31
+ const LensLayerSchema = LensSchema.partial({ skill: true });
32
+
33
+ // A model id is whatever the harness's agent tool accepts: `haiku` on Claude Code, `provider/model` on OpenCode.
34
+ // stamp's canonical `provider:model` also works: opencode-agents spells it the OpenCode way (lens.ts opencodeModel).
27
35
  export const ModelId = z.string().min(1);
28
36
 
29
37
  /** The steps a recipe can run: shepherd's own runners and stamp's verdict. */
@@ -39,9 +47,10 @@ const REVIEWS = new Set<Step>(["swarm", "stamp"]);
39
47
  export const ConfigSchema = z
40
48
  .object({
41
49
  extends: z.array(z.string().min(1)).optional(),
50
+ tiers: z.record(z.string().regex(NAME), ModelId).optional(), // a name for a model, defined once: ladder and models may use it
42
51
  ladder: z.array(ModelId).min(1).optional(), // cheapest first; replaces the harness's ladder
43
- models: z.record(z.string().regex(NAME), ModelId).optional(), // a lens or runner name -> the model it always runs on
44
- lenses: z.record(z.string().regex(NAME), LensSchema).default({}),
52
+ models: z.record(z.string().regex(NAME), ModelId).optional(), // a runner, lens or role group -> the model or tier it runs on
53
+ lenses: z.record(z.string().regex(NAME), LensLayerSchema).default({}),
45
54
  checks: z.record(z.string().regex(NAME), z.object({ command: z.string().min(1) }).strict()).optional(),
46
55
  fixes: z.object({ mode: z.enum(["suggest", "local", "push"]) }).strict().optional(),
47
56
  escalate: z.object({ paths: z.array(z.string().min(1)).min(1), reason: z.string().min(1).optional() }).strict().optional(),
@@ -74,6 +83,8 @@ type Sourced<T> = { value: T; source: string };
74
83
  type Layer = { source: string; config: Config };
75
84
 
76
85
  export type Effective = {
86
+ /** Named models. The ladder and models below hold them resolved: a model id, never a tier name. */
87
+ tiers: Record<string, Sourced<string>>;
77
88
  ladder: Sourced<string[]> | null;
78
89
  models: Record<string, Sourced<string>>;
79
90
  lenses: Record<string, Sourced<Lens> & { scope: "team" | "personal" }>;
@@ -99,8 +110,17 @@ const parseConfig = (text: string, source: string): Config => {
99
110
  return result.data;
100
111
  };
101
112
 
102
- /** One `extends` entry as a layer. A pack extends nothing itself, so the order stays the one the file lists. */
103
- function readPack(ref: string, read: Read, fetch: Fetch): Layer {
113
+ // How deep packs may extend packs. Enough for org > stack > framework; past it a chain is a mistake.
114
+ const MAX_PACK_DEPTH = 4;
115
+
116
+ /**
117
+ * One `extends` entry as layers: the packs it extends, in order, then the pack itself. A pinned pack's own
118
+ * relative entries name files in its repository at the same commit, so a pack travels with what it builds on.
119
+ */
120
+ function readPack(ref: string, read: Read, fetch: Fetch, chain: string[] = []): Layer[] {
121
+ if (chain.includes(ref)) throw new Error(`${[...chain, ref].join(" > ")}: packs extend each other in a cycle`);
122
+
123
+ if (chain.length >= MAX_PACK_DEPTH) throw new Error(`${[...chain, ref].join(" > ")}: packs extend more than ${MAX_PACK_DEPTH} deep`);
104
124
  const pinned = PINNED.exec(ref);
105
125
  let text: string | null;
106
126
 
@@ -112,26 +132,32 @@ function readPack(ref: string, read: Read, fetch: Fetch): Layer {
112
132
  if (text === null) throw new Error(`${ref}: pack not found`);
113
133
  const config = parseConfig(text, ref);
114
134
 
115
- if (config.extends?.length) throw new Error(`${ref}: a pack cannot extend another pack; list both in the repository's extends`);
135
+ const inner = (config.extends ?? []).map((e) => {
136
+ if (!pinned || e.startsWith("github:")) return e;
137
+
138
+ if (pathEscapes(e)) throw new Error(`${ref}: extends ${e}: a path is relative to the pack's repository, with no leading / and no ..`);
139
+
140
+ return `github:${pinned[1]}/${pinned[2]}/${e}@${pinned[4]}`;
141
+ });
116
142
 
117
143
  // A pinned pack's lens paths name files in the pack's repository at the same commit, so the lens travels with it.
118
144
  if (pinned) {
119
145
  for (const [name, lens] of Object.entries(config.lenses)) {
120
- if (!lens.skill.includes("/")) continue;
146
+ if (!lens.skill?.includes("/")) continue;
121
147
 
122
148
  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 ..`);
123
149
  lens.skill = `github:${pinned[1]}/${pinned[2]}/${lens.skill.replace(/\/+$/, "")}@${pinned[4]}`;
124
150
  }
125
151
  }
126
152
 
127
- return { source: `pack ${ref}`, config };
153
+ return [...inner.flatMap((e) => readPack(e, read, fetch, [...chain, ref])), { source: `pack ${ref}`, config }];
128
154
  }
129
155
 
130
156
  const pathEscapes = (rel: string) => rel.startsWith("/") || rel.split("/").includes("..");
131
157
 
132
- /** Merge layers in order: a later layer replaces a scalar and merges a map by name. */
158
+ /** Merge layers in order: a later layer replaces a scalar and merges a map by name; a lens merges field by field. */
133
159
  function merge(layers: Layer[]): Effective {
134
- const out: Effective = { ladder: null, models: {}, lenses: {}, checks: {}, fixes: { value: { mode: "push" }, source: "built-in" }, escalate: null, recipes: {}, ignored: [] };
160
+ const out: Effective = { tiers: {}, ladder: null, models: {}, lenses: {}, checks: {}, fixes: { value: { mode: "push" }, source: "built-in" }, escalate: null, recipes: {}, ignored: [] };
135
161
 
136
162
  for (const { source, config } of layers) {
137
163
  const tag = <T>(value: T) => ({ value, source });
@@ -142,9 +168,16 @@ function merge(layers: Layer[]): Effective {
142
168
 
143
169
  if (config.escalate) out.escalate = tag(config.escalate);
144
170
 
171
+ for (const [k, v] of Object.entries(config.tiers ?? {})) out.tiers[k] = tag(v);
172
+
145
173
  for (const [k, v] of Object.entries(config.models ?? {})) out.models[k] = tag(v);
146
174
 
147
- for (const [k, v] of Object.entries(config.lenses)) out.lenses[k] = { ...tag(v), scope: "team" };
175
+ for (const [k, v] of Object.entries(config.lenses)) {
176
+ // SAFETY: a lens without a skill is refused in loadPolicy unless an earlier layer gave it one.
177
+ const lens = { ...out.lenses[k]?.value, ...v } as Lens;
178
+
179
+ out.lenses[k] = { ...tag(lens), scope: "team" };
180
+ }
148
181
 
149
182
  for (const [k, v] of Object.entries(config.checks ?? {})) out.checks[k] = tag(v);
150
183
 
@@ -161,12 +194,16 @@ function merge(layers: Layer[]): Effective {
161
194
  export function loadPolicy(read: Read, fetch: Fetch, personal: Config | null): Effective & { teamFile: string | null } {
162
195
  const teamFile = TEAM_FILES.find((f) => read(f) !== null) ?? null;
163
196
  const team = teamFile ? parseConfig(read(teamFile)!, teamFile) : null;
164
- const packs = (team?.extends ?? []).map((ref) => readPack(ref, read, fetch));
197
+ const packs = (team?.extends ?? []).flatMap((ref) => readPack(ref, read, fetch));
165
198
  const effective = merge([{ source: "built-in", config: BUILT_IN }, ...packs, ...(team ? [{ source: teamFile!, config: team }] : [])]);
166
199
 
200
+ for (const [name, l] of Object.entries(effective.lenses)) {
201
+ if (!l.value.skill) throw new Error(`lens ${name}: no skill; name one, or extend the pack that defines ${name}`);
202
+ }
203
+
167
204
  // A lens may name a pinned pack directly; any skill spelled github: must be one that stays in the cache.
168
205
  for (const [name, l] of [...Object.entries(effective.lenses), ...Object.entries(personal?.lenses ?? {}).map(([k, v]) => [k, { value: v }] as const)]) {
169
- 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`);
206
+ 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`);
170
207
  }
171
208
 
172
209
  if (personal) {
@@ -175,16 +212,88 @@ export function loadPolicy(read: Read, fetch: Fetch, personal: Config | null): E
175
212
  // Personal fills in only what the team left open, and adds lenses that never post.
176
213
  if (!effective.ladder && personal.ladder) effective.ladder = { value: personal.ladder, source };
177
214
 
178
- for (const [k, v] of Object.entries(personal.models ?? {})) effective.models[k] ??= { value: v, source };
215
+ for (const [k, v] of Object.entries(personal.tiers ?? {})) effective.tiers[k] ??= { value: v, source };
179
216
 
180
- for (const [k, v] of Object.entries(personal.lenses)) effective.lenses[k] ??= { value: v, source, scope: "personal" };
217
+ for (const [k, v] of Object.entries(personal.lenses)) {
218
+ if (!v.skill) throw new Error(`personal lens ${k}: no skill`);
219
+ // SAFETY: skill checked on the line above.
220
+ effective.lenses[k] ??= { value: v as Lens, source, scope: "personal" };
221
+ }
181
222
 
182
223
  for (const key of ["extends", "checks", "fixes", "escalate", "recipes"] as const) {
183
224
  if (personal[key] !== undefined) effective.ignored.push(`personal ${key}: team policy, set it in ${TEAM_FILES[0]}`);
184
225
  }
185
226
  }
186
227
 
187
- return { ...effective, teamFile };
228
+ // The team's groups expand before any personal pin, so a personal pin fills only a runner the team left open.
229
+ effective.models = expandGroups(effective, effective.models);
230
+
231
+ if (personal?.models) {
232
+ const own = expandGroups(effective, Object.fromEntries(Object.entries(personal.models).map(([k, v]) => [k, { value: v, source: "personal" }])));
233
+
234
+ for (const [k, v] of Object.entries(own)) effective.models[k] ??= v;
235
+ }
236
+
237
+ return { ...resolveModels(effective), teamFile };
238
+ }
239
+
240
+ /**
241
+ * Role groups a `models` entry can pin at once. A pin on one runner or lens beats its group's, so a team
242
+ * sets `reviewers: fast` and `security: smart` and gets both.
243
+ */
244
+ export const ROLE_GROUPS = {
245
+ reviewers: (p: Effective) => ["router", ...BUILT_IN_REVIEWERS, ...Object.keys(p.lenses)],
246
+ fixers: () => ["triage", "simplify", "ci-repair", "incident"],
247
+ validators: () => ["verifier", "validator"],
248
+ } as const;
249
+
250
+ /** The merged team pins with role groups expanded: a pin on a runner or lens beats its group. */
251
+ function expandGroups(p: Effective, pins: Effective["models"]): Effective["models"] {
252
+ const out: Effective["models"] = {};
253
+
254
+ for (const [group, members] of Object.entries(ROLE_GROUPS)) {
255
+ const pin = pins[group];
256
+
257
+ if (pin) for (const m of members(p)) out[m] = { value: pin.value, source: `${pin.source} (models.${group})` };
258
+ }
259
+
260
+ for (const [k, v] of Object.entries(pins)) if (!(k in ROLE_GROUPS)) out[k] = v;
261
+
262
+ return out;
263
+ }
264
+
265
+ /** Turn every tier name in the ladder and pins into its model id. */
266
+ function resolveModels(p: Effective): Effective {
267
+ const tier = (v: Sourced<string>) => {
268
+ const t = p.tiers[v.value];
269
+
270
+ return t ? { value: t.value, source: `${v.source}, tier ${v.value}` } : v;
271
+ };
272
+
273
+ return {
274
+ ...p,
275
+ ladder: p.ladder && { value: p.ladder.value.map((m) => p.tiers[m]?.value ?? m), source: p.ladder.source },
276
+ models: Object.fromEntries(Object.entries(p.models).map(([k, v]) => [k, tier(v)])),
277
+ };
278
+ }
279
+
280
+ /** The model CI runs the shepherd session on when nothing chooses one. */
281
+ export const CI_DEFAULT_MODEL = "opencode-go/kimi-k3";
282
+
283
+ /**
284
+ * The session model for CI, in order: SHEPHERD_MODEL (a model id or a tier name), the `loop` pin, the top of the
285
+ * ladder, then the default, which says so.
286
+ */
287
+ export type CiModel = { model: string; source: string };
288
+
289
+ export function ciModel(p: Effective, override: string | undefined): CiModel {
290
+ if (override) return p.tiers[override] ? { model: p.tiers[override]!.value, source: `SHEPHERD_MODEL, tier ${override}` } : { model: override, source: "SHEPHERD_MODEL" };
291
+
292
+ if (p.models.loop) return { model: p.models.loop.value, source: `models.loop, ${p.models.loop.source}` };
293
+
294
+ if (p.ladder) return { model: p.ladder.value.at(-1)!, source: `top of the ladder, ${p.ladder.source}` };
295
+
296
+ return { model: CI_DEFAULT_MODEL, source: "default: name one with SHEPHERD_MODEL, models.loop or a ladder" };
188
297
  }
189
298
 
190
299
  type Mode = Effective["fixes"]["value"]["mode"];
@@ -247,11 +356,11 @@ const WRITES: Record<Step, Record<Mode, string>> = {
247
356
  // Built-in reviewers, and the ladder rung each runner starts on (skills/shepherd/references/models.md).
248
357
  const BUILT_IN_REVIEWERS = ["correctness", "security", "simplicity", "maintainability", "slop", "spec"];
249
358
 
250
- const RUNG = new Map([["router", 0], ["verifier", 1], ["triage", 1], ["simplify", 1], ["ci-repair", 1], ["validator", 2]]);
359
+ const RUNG = new Map([["router", 0], ["verifier", 1], ["triage", 1], ["simplify", 1], ["ci-repair", 1], ["validator", 2], ["loop", 99]]); // loop: the top rung
251
360
 
252
361
  /** The model each runner uses: its pin, its rung of the team ladder, or the harness's own ladder. */
253
362
  export function modelPlan(p: Effective): { runner: string; model: string; source: string }[] {
254
- const names = ["router", ...BUILT_IN_REVIEWERS, ...Object.keys(p.lenses), "verifier", "triage", "simplify", "ci-repair", "validator"];
363
+ const names = ["router", ...BUILT_IN_REVIEWERS, ...Object.keys(p.lenses), "verifier", "triage", "simplify", "ci-repair", "validator", "loop"];
255
364
 
256
365
  return [...new Set(names)].map((runner) => {
257
366
  const pin = p.models[runner];
@@ -259,7 +368,13 @@ export function modelPlan(p: Effective): { runner: string; model: string; source
259
368
 
260
369
  if (pin) return { runner, model: pin.value, source: `pinned, ${pin.source}` };
261
370
 
262
- if (p.ladder) return { runner, model: p.ladder.value[Math.min(rung, p.ladder.value.length - 1)]!, source: `rung ${rung}, ${p.ladder.source}` };
371
+ if (p.ladder) {
372
+ const at = Math.min(rung, p.ladder.value.length - 1);
373
+
374
+ return { runner, model: p.ladder.value[at]!, source: `rung ${at}, ${p.ladder.source}` };
375
+ }
376
+
377
+ if (runner === "loop") return { runner, model: "the session model", source: `in CI, SHEPHERD_MODEL or ${CI_DEFAULT_MODEL}` };
263
378
 
264
379
  return { runner, model: `harness rung ${rung}`, source: "Claude Code: haiku > sonnet > opus; OpenCode with no ladder: the session model" };
265
380
  });
@@ -302,7 +417,8 @@ const gitIn = (repoRoot: string) => (...args: string[]) => execFileSync("git", [
302
417
  /** The fetched ref of `origin`'s default branch. The name comes from the remote, since a CI checkout sets no origin/HEAD. */
303
418
  export function defaultBranchRef(repoRoot: string): string {
304
419
  const git = gitIn(repoRoot);
305
- const branch = /^ref: refs\/heads\/(\S+)\s+HEAD/m.exec(git("ls-remote", "--symref", "origin", "HEAD"))?.[1];
420
+ // CI names it (SHEPHERD_DEFAULT_BRANCH), since a checkout without a persisted token cannot ask a private origin.
421
+ const branch = process.env.SHEPHERD_DEFAULT_BRANCH || /^ref: refs\/heads\/(\S+)\s+HEAD/m.exec(git("ls-remote", "--symref", "origin", "HEAD"))?.[1];
306
422
 
307
423
  if (!branch) throw new Error("cannot tell origin's default branch");
308
424
  const ref = `refs/remotes/origin/${branch}`;