@jagreehal/shepherd 0.4.0 → 0.6.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 (47) hide show
  1. package/README.md +9 -1
  2. package/THIRD_PARTY_NOTICES.md +41 -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/pstack/SKILL.md +33 -0
  12. package/lenses/python/SKILL.md +32 -0
  13. package/lenses/react/SKILL.md +33 -0
  14. package/lenses/rust/SKILL.md +31 -0
  15. package/package.json +2 -1
  16. package/packs/dotnet.yml +6 -0
  17. package/packs/go.yml +6 -0
  18. package/packs/java.yml +6 -0
  19. package/packs/nextjs.yml +7 -0
  20. package/packs/node-api.yml +7 -0
  21. package/packs/nx-monorepo.yml +6 -0
  22. package/packs/observability.yml +6 -0
  23. package/packs/owasp-asvs.yml +6 -0
  24. package/packs/owasp-llm.yml +8 -0
  25. package/packs/pstack.yml +8 -0
  26. package/packs/python.yml +6 -0
  27. package/packs/react.yml +6 -0
  28. package/packs/rust.yml +6 -0
  29. package/skills/ci-repair/SKILL.md +11 -3
  30. package/skills/lens-import/SKILL.md +187 -0
  31. package/skills/lens-import/references/conversion.md +96 -0
  32. package/skills/lens-import/scripts/check-import.mjs +154 -0
  33. package/skills/shepherd/SKILL.md +32 -9
  34. package/skills/shepherd/references/dispatch.md +7 -4
  35. package/skills/shepherd/references/models.md +20 -7
  36. package/skills/shepherd/references/policy.md +9 -5
  37. package/skills/swarm/SKILL.md +11 -1
  38. package/skills/swarm/references/custom-lenses.md +50 -7
  39. package/skills/triage/SKILL.md +15 -0
  40. package/src/cli.ts +109 -13
  41. package/src/config.ts +137 -21
  42. package/src/doctor.ts +16 -13
  43. package/src/lens.ts +217 -14
  44. package/src/stack.ts +121 -0
  45. package/templates/shepherd-audit.yml +180 -0
  46. package/templates/shepherd-incident.yml +30 -4
  47. package/templates/shepherd.yml +34 -4
@@ -13,17 +13,30 @@ ladder applies only when the repository sets none. `models:` pins merge per
13
13
  name, the repository winning. `shepherd models` prints the result.
14
14
 
15
15
  ```yaml
16
- ladder: [opencode-go/deepseek-v4-flash, opencode-go/glm-5.3, opencode-go/kimi-k3, opencode-go/qwen3.8-max]
17
- models: # a name runs on exactly this model, whatever its rung
18
- security: opencode-go/qwen3.8-max
19
- router: opencode-go/deepseek-v4-flash
16
+ tiers: # a name for a model, defined once; a pack can define them for every repo
17
+ fast: opencode/deepseek-v4.1-flash-free
18
+ smart: bedrock:eu.anthropic.claude-sonnet-4-6
19
+ ladder: [fast, smart] # tiers or model ids, cheapest first
20
+ models: # a name runs on exactly this model or tier, whatever its rung
21
+ reviewers: fast # role group: the router and every lens
22
+ fixers: smart # role group: triage, simplify, ci-repair, incident
23
+ security: smart # one runner or lens beats its group
20
24
  ```
21
25
 
22
26
  Pin names: `router`, `verifier`, `validator`, `triage`, `simplify`,
23
- `ci-repair`, and any lens, built-in (`correctness`, `security`, `simplicity`,
24
- `maintainability`, `slop`) or custom. A model id passes to the agent tool's
27
+ `ci-repair`, `loop` (the session model in CI), any lens, built-in
28
+ (`correctness`, `security`, `simplicity`, `maintainability`, `slop`) or
29
+ custom, and the role groups `reviewers`, `fixers` and `validators`. Take the
30
+ ladder and pins from `shepherd config explain --json`: tiers and groups are
31
+ already resolved there, so every value is a model id and every pin names one
32
+ runner. A model id passes to the agent tool's
25
33
  model parameter exactly as written: `haiku` on Claude Code, `provider/model`
26
- on OpenCode. Never translate one id into another provider's. A pin replaces
34
+ on OpenCode. Never translate one id into another provider's yourself. The one
35
+ translation is `shepherd opencode-agents`, which accepts stamp's canonical
36
+ `provider:model` ids and writes them the OpenCode way (`bedrock:` becomes
37
+ `amazon-bedrock/`, `vertex:` becomes `google-vertex/`, any other provider keeps
38
+ its name), so one ladder serves stamp and shepherd. `shepherd models` shows
39
+ both spellings. Claude Code aliases pass through. A pin replaces
27
40
  the rung for that runner only; climbing for validation starts from the pin's
28
41
  position on the ladder, or the top rung when the pin is not on it. A pin that
29
42
  the agent tool rejects falls back to the runner's rung, and the summary says
@@ -2,8 +2,9 @@
2
2
 
3
3
  A team sets shepherd's policy in `.shepherd/config.yml` (an older repository
4
4
  may have only `.shepherd/lenses.yml`; it reads the same way). It can extend
5
- packs, which apply first, and the repository file wins over them. Every
6
- runner reads the policy the same way and holds to it.
5
+ packs, which apply first, and the repository file wins over them. A pack may
6
+ extend packs of its own, which apply before it, up to four deep; shepherd
7
+ refuses a cycle. Every runner reads the policy the same way and holds to it.
7
8
 
8
9
  ## Load it once per run
9
10
 
@@ -47,7 +48,9 @@ recipes.
47
48
  `escalate.reason` (or "team policy: a person changes <path>"); ci-repair
48
49
  classifies it `needs-decision`; incident stops with
49
50
  `outcome=needs_decision`. A gate or deny-list elsewhere still applies.
50
- - **`lenses`**, **`ladder`**, **`models`**: as in `../../swarm/references/custom-lenses.md`
51
+ - **`lenses`**, **`ladder`**, **`models`**: a lens merges field by field
52
+ across layers, so a repository can set `only`, `disable` or `applies_to`
53
+ on a pack's lens by name; the rest is as in `../../swarm/references/custom-lenses.md`
51
54
  and `models.md`.
52
55
  - **`recipes`**: named step lists for `/shepherd <pr> --recipe <name>`. See
53
56
  below.
@@ -105,6 +108,7 @@ name a path in the pack's own repository (`skill: lenses/payments`). It
105
108
  resolves at the same commit, which must be on that repository's default branch: shepherd fetches that directory once into
106
109
  `~/.cache/shepherd/packs/`, keyed by the commit, and `config explain --json`
107
110
  gives the lens's `path` there. A bare name (`skill: payments-rules`) is an
108
- installed skill. A lens path in a pack inside this repository resolves in
109
- this repository. `shepherd config validate` reports a lens skill it cannot
111
+ installed skill. A pinned pack's own relative `extends` entries resolve the
112
+ same way, in its repository at its commit. A lens path in a pack inside this
113
+ repository resolves in this repository. `shepherd config validate` reports a lens skill it cannot
110
114
  find.
@@ -128,11 +128,21 @@ where `$TMPDIR` can differ inside and outside a sandbox.
128
128
 
129
129
  ```bash
130
130
  mkdir -p "$(git rev-parse --git-common-dir)/shepherd"
131
+ shepherd stack <number> # JSON: wrong_base, parent, range
131
132
  gh pr diff <number> > "$(git rev-parse --git-common-dir)/shepherd/swarm-<short_sha>.patch"
132
133
  gh pr diff <number> --name-only
133
134
  ```
134
135
 
135
- When `shepherd` invokes you it passes `diff_path`, `head_sha`, the model ladder and `models` pins,
136
+ Run `shepherd stack` first; when it exits non-zero, review `gh pr diff` and name
137
+ the error in the summary. With `wrong_base` set, post nothing and stop: report
138
+ "retarget to `<branch>`: `<on>` of `<total>` commits are already there". With
139
+ `parent` set, the PR is stacked on another open PR: write `git diff <range>` and
140
+ `git diff --name-only <range>` instead of `gh pr diff`, and review only that
141
+ change. Post no finding on a line the delta does not touch; the parent's code
142
+ is reviewed in the parent's PR, and posting it again here duplicates it across
143
+ the stack.
144
+
145
+ When `shepherd` invokes you it passes `diff_path` (already the stacked delta when there is a parent), `stacked_on`, `head_sha`, the model ladder and `models` pins,
136
146
  `skip_checks` (true when it already ran Step 2 this round), and `since_sha` (the
137
147
  head swarm last reviewed, on round 2 onwards). Use them and do not re-derive.
138
148
 
@@ -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
@@ -216,6 +216,21 @@ unless the PR's own change depends on the broken code.
216
216
  the commit, or the commit's message) is proof the fix did not hold. Before
217
217
  fixing again, say why it did not (it fixed a sibling path, the wrong root cause,
218
218
  or was reverted), and never resolve it as already fixed on the same evidence.
219
+ When two `Shepherd:` commits have already tried to fix the same concern, both
220
+ rested on a premise that is wrong: write the premise down, test it directly
221
+ (one command, one read of the code it names), and fix only what that shows. If
222
+ you cannot test it, defer the thread with both commits and the premise.
223
+
224
+ **Bots that keep coming back.** Count each review bot's passes on this PR (its
225
+ reviews, by head). From its third pass on, a finding that repeats a concern
226
+ already dismissed on this PR with a reason from the code is resolved as a nit
227
+ with that same reason, once you have checked the reason still holds on the
228
+ current head: re-read the code it cites. A later commit can remove what made
229
+ the concern harmless (validation, a guard, the only caller); when the reason
230
+ no longer holds, classify the finding afresh. Re-litigating a reason that
231
+ still holds is churn. Findings that touch security,
232
+ auth, billing, data or migrations are the exception: defer those rather than
233
+ dismiss them. Never change code only to quiet a bot.
219
234
 
220
235
  **Outdated threads.** GitHub marks a thread outdated when its line changed, not
221
236
  when its concern was met, so an outdated thread is never skipped. Read its
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, pluginRoots, 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,30 @@ 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
+ const opencode = opencodeAgents(choice(p));
334
+ // Every key the plan's models read, so the workflow can drop the rest before the model runs.
335
+ const keyEnvs = [...new Set([session, ...Object.values(opencode.agent).map((a) => a.model)].flatMap((m) => providerKeyEnv(m) ?? []))].sort();
336
+
337
+ console.log(JSON.stringify({ model: session, source, key_env: providerKeyEnv(session), key_envs: keyEnvs, opencode }));
338
+ } else if (command === "model-id" && sub) {
339
+ // A model id as OpenCode spells it, so stamp's provider:model spelling works in a local OpenCode run too.
340
+ console.log(opencodeModel(sub));
341
+ } else if (command === "stack" && sub) {
342
+ // Which diff to review: the delta over an open stacked parent, or nothing at all when the base is wrong.
343
+ console.log(JSON.stringify(orExit(() => prStack(Number(sub), repoRoot)), null, 2));
312
344
  } else if (command === "workflows") {
313
345
  const dest = path.join(repoRoot, ".github", "workflows");
314
346
 
315
347
  mkdirSync(dest, { recursive: true });
316
348
 
317
- for (const name of ["shepherd.yml", "shepherd-incident.yml"]) {
349
+ for (const name of ["shepherd.yml", "shepherd-incident.yml", ...(opts.audit ? ["shepherd-audit.yml"] : [])]) {
318
350
  const to = path.join(dest, name);
319
351
 
320
352
  if (existsSync(to)) {
@@ -347,7 +379,15 @@ if (command === "install") {
347
379
  } else if (command === "init") {
348
380
  const file = path.join(repoRoot, TEAM_FILES[0]!);
349
381
 
350
- if (existsSync(file)) orExit(() => { throw new Error(`${TEAM_FILES[0]} already exists; edit it, then run shepherd config validate`); });
382
+ // With --stacks on an existing policy, add the detected stacks' lenses it lacks and keep everything else.
383
+ if (existsSync(file) && opts.stacks) {
384
+ addStackLenses(file);
385
+ validate();
386
+ console.log(MERGE_NOTE);
387
+ process.exit(process.exitCode ?? 0);
388
+ }
389
+
390
+ 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
391
  const legacy = workingTree(TEAM_FILES[1]!);
352
392
  const seed = legacy ? orExit(() => ConfigSchema.parse(parseYaml(legacy) ?? {})) : { lenses: {} };
353
393
  // 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 +401,25 @@ if (command === "install") {
361
401
  if (opts.from) config.extends = [opts.from, ...(seed.extends ?? [])];
362
402
 
363
403
  if (mode) config.fixes = { mode };
404
+ const stacks = detectStacks(trackedFiles(), workingTree);
405
+
364
406
  mkdirSync(path.dirname(file), { recursive: true });
365
407
  writeFileSync(file, `# shepherd team policy. Presets: review-only (fixes.mode suggest), local-fix (local), push.\n${stringify(config)}`);
366
408
  console.log(`wrote ${TEAM_FILES[0]}${preset ? ` (preset ${preset})` : ""}${legacy ? ` from ${TEAM_FILES[1]} (delete it: ${TEAM_FILES[0]} now wins)` : ""}`);
409
+
410
+ // After the file exists, so a pack named by --from counts as already providing its lenses.
411
+ if (opts.stacks) addStackLenses(file);
412
+ else {
413
+ 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>`);
414
+ pstackHint("pstack" in policy(true).lenses);
415
+ }
416
+
417
+ const named = policy(true);
418
+
419
+ if (!Object.keys(named.tiers).length && !named.ladder && !Object.keys(named.models).length) {
420
+ 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)`);
421
+ }
422
+
367
423
  validate();
368
424
  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
425
  } else if (command === "config" && sub === "validate") {
@@ -424,6 +480,14 @@ if (command === "install") {
424
480
  process.exit(2);
425
481
  }
426
482
 
483
+ function trackedFiles(): string[] {
484
+ try {
485
+ return execFileSync("git", ["-C", repoRoot, "ls-files", "-z"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 }).split("\0").filter(Boolean);
486
+ } catch {
487
+ return [];
488
+ }
489
+ }
490
+
427
491
  function workingTree(rel: string): string | null {
428
492
  const file = path.join(repoRoot, rel);
429
493
 
@@ -436,6 +500,35 @@ function personal(): Config | null {
436
500
  return existsSync(file) ? ConfigSchema.parse(parseYaml(readFileSync(file, "utf8")) ?? {}) : null;
437
501
  }
438
502
 
503
+ /**
504
+ * Add a starter lens for each detected stack the effective team policy lacks. A lens a pack provides, or the
505
+ * file declares, is kept as it is: its skill, scope and gate are the team's.
506
+ */
507
+ function addStackLenses(file: string): void {
508
+ const have = policy(true).lenses;
509
+ const stacks = detectStacks(trackedFiles(), workingTree);
510
+
511
+ for (const s of stacks) {
512
+ const lens = have[s];
513
+
514
+ if (lens?.scope === "team") {
515
+ console.log(`lens ${s}: kept, from ${lens.source}`);
516
+ continue;
517
+ }
518
+
519
+ orExit(() => addLens(file, s, stackLens(repoRoot, s)));
520
+ console.log(`lens ${s}: .shepherd/lenses/${s} from the ${s} starter; trim its rules with only or disable`);
521
+ }
522
+
523
+ if (!stacks.length) console.log("no stack detected");
524
+ pstackHint("pstack" in have);
525
+ }
526
+
527
+ /** pstack installed here: its principles are a lens away, so reviews check what its agents are told to do. */
528
+ function pstackHint(declared: boolean): void {
529
+ if (!declared && pluginRoots(homedir()).has("pstack")) console.log("pstack is installed: review against its principles with shepherd lens new pstack --from pstack");
530
+ }
531
+
439
532
  /** Team policy from the default branch, the source swarm reviews under, or from your working tree. */
440
533
  function policy(fromTree: boolean) {
441
534
  const read: Read = fromTree ? workingTree : orExit(() => defaultBranchReader(repoRoot));
@@ -472,6 +565,9 @@ function explain(p: Effective & { teamFile: string | null }): void {
472
565
 
473
566
  console.log(`policy file: ${p.teamFile ?? "none (built-in defaults)"}${opts["working-tree"] ? ", working tree" : ", default branch"}\n`);
474
567
  row("fixes.mode", p.fixes.value.mode, p.fixes.source);
568
+
569
+ for (const [k, v] of Object.entries(p.tiers)) row(`tiers.${k}`, v.value, v.source);
570
+
475
571
  row("ladder", p.ladder?.value.join(" -> ") ?? "the harness's own", p.ladder?.source ?? "built-in");
476
572
 
477
573
  for (const [k, v] of Object.entries(p.models)) row(`models.${k}`, v.value, v.source);