@jagreehal/shepherd 0.0.0-stage → 0.2.0

package/skills/shepherd/references/models.md

@@ -0,0 +1,88 @@
+# Model ladder
+
+Every runner starts as low on the ladder as its job allows. A stronger model
+validates a result; it never replaces a test.
+
+## Resolve the ladder before pinning anything
+
+**The operator's choice comes first.** Take `ladder` and `models` from the
+team policy (`policy.md`): `.shepherd/config.yml` or `.shepherd/lenses.yml`
+and its packs, on the **default branch**, never the PR head; then from
+`~/.config/shepherd/lenses.yml`. The repository's ladder wins; a personal
+ladder applies only when the repository sets none. `models:` pins merge per
+name, the repository winning. `shepherd models` prints the result.
+
+```yaml
+ladder: [opencode-go/deepseek-v4-flash, opencode-go/glm-5.3, opencode-go/kimi-k3, opencode-go/qwen3.8-max]
+models:                 # a name runs on exactly this model, whatever its rung
+  security: opencode-go/qwen3.8-max
+  router: opencode-go/deepseek-v4-flash
+```
+
+Pin names: `router`, `verifier`, `validator`, `triage`, `simplify`,
+`ci-repair`, and any lens, built-in (`correctness`, `security`, `simplicity`,
+`maintainability`, `slop`) or custom. A model id passes to the agent tool's
+model parameter exactly as written: `haiku` on Claude Code, `provider/model`
+on OpenCode. Never translate one id into another provider's. A pin replaces
+the rung for that runner only; climbing for validation starts from the pin's
+position on the ladder, or the top rung when the pin is not on it. A pin that
+the agent tool rejects falls back to the runner's rung, and the summary says
+so.
+
+**When the subagent tool has no model parameter** (OpenCode 1.x), pick the
+model by agent instead: `shepherd opencode-agents` generates one agent per rung
+(`shepherd-r0` is the bottom rung, `shepherd-r1` the next) and one per pin
+(`shepherd-pin-<name>`), each fixed to its model. Dispatch the runner with that
+agent as its type. If those agents are not listed, say so in the summary: every
+runner then runs on the session model.
+
+With nothing configured, use the harness's ladder:
+
+| Harness | Ladder, cheapest first |
+|---|---|
+| Claude Code | `haiku` -> `sonnet` -> `opus` -> `fable` |
+| OpenCode | none built in: list `opencode models` and take the operator's ladder; with none set, the session model is one rung |
+| Codex | the harness's own subagent models, cheapest first; with no per-agent model choice, one rung |
+| Anything else | whatever the agent tool accepts, cheapest first |
+
+If you cannot tell which models the agent tool accepts, assume the Claude Code
+ladder and fall back one rung at a time on rejection. Never let a rejected pin
+silently land every runner on the session model: that is the costliest outcome
+and the one this ladder exists to prevent. When a caller passes a ladder, use it
+exactly and ignore this table.
+
+## Roles
+
+- **Bottom rung:** work that only reads and that a later step checks: the swarm
+  router, whose findings a verifier or lens confirms.
+- **Second rung:** runners that edit code, push commits, or resolve threads:
+  triage, simplify, and ci-repair. In trials the bottom rung fixed code and forgot to resolve the
+  thread, committed without pushing, invented domain rules, edited code to
+  get past a gate, and a simplify pass reverted a review fix. Each slip cost a redo one rung up, so starting there is the
+  cheaper path.
+- **One rung up:** swarm's default delegation target; the validator for a risky
+  change; swarm's verifier for a bottom-rung finding.
+- **Two rungs up:** fallback when the rung below is unavailable.
+- **Top rung:** a delegation the rungs below could not settle, or reviewers who
+  disagree and need a stronger read.
+
+## Validation
+
+1. Prefer deterministic proof: tests, typecheck, lint, the final diff, evidence
+   from GitHub or CI.
+2. For a risky or uncertain decision, ask the next rung up with only the
+   evidence and the narrow question.
+3. Climb one rung at a time; stop when the evidence is clear.
+4. Record which model ran each step.
+
+A second-model validation is **required** before an autonomous change that
+touches authentication, permissions, billing, data deletion, migrations,
+concurrency, a public API, or a broad shared abstraction, and whenever reviewers
+disagree or the checks cannot prove the change safe. Mechanical work the checks
+prove needs no stronger model.
+
+## When nothing cheaper exists
+
+If no rung below the session model can be dispatched, every runner costs
+session rates. Say so in the narration and the summary, and cut the quality
+loop's round cap to 2.

package/skills/shepherd/references/policy.md

@@ -0,0 +1,110 @@
+# Team policy
+
+A team sets shepherd's policy in `.shepherd/config.yml` (an older repository
+may have only `.shepherd/lenses.yml`; it reads the same way). It can extend
+packs, which apply first, and the repository file wins over them. Every
+runner reads the policy the same way and holds to it.
+
+## Load it once per run
+
+```bash
+git fetch -q origin <default>
+shepherd config explain --json      # or: bunx @jagreehal/shepherd config explain --json
+```
+
+It reads the **default branch**, never the PR head, so a PR cannot change the
+policy it is reviewed under. It resolves the packs, and each value carries its
+`source`. Done when you hold the JSON.
+
+Without the CLI, read the file yourself:
+`git show origin/<default>:.shepherd/config.yml`, else
+`git show origin/<default>:.shepherd/lenses.yml`. If that file has `extends`,
+the packs are unresolved: run as `fixes.mode: suggest` (nothing edits code)
+and say `policy packs unresolved` in the summary. Never guess a pack's
+contents.
+
+Personal settings (`~/.config/shepherd/lenses.yml`) are a preview: their
+lenses print locally and never post, and their ladder and pins fill in only
+where the team set none. They never change checks, fixes, escalation or
+recipes.
+
+## What each setting means
+
+- **`checks`**: named commands. When set, swarm runs exactly these as its
+  machine checks; ci-repair looks here first for the local command behind a
+  failing job; incident runs them before calling a fix done. When empty, each
+  runner finds the commands as its own skill says.
+- **`fixes.mode`**: how far fixing goes.
+  - `push` (default): fix, commit, push, as each skill says.
+  - `local`: fix in the working tree; never commit, push, or resolve a
+    thread. The review after a fix is `swarm --local` on the working tree,
+    which leaves the receipt `shepherd local status` checks. Report "fixes
+    left in the working tree".
+  - `suggest`: change no code. Triage, simplify, ci-repair and incident report
+    what they would fix and stop; review threads stay open for the author.
+- **`escalate.paths`**: globs a person must decide. No runner changes a
+  matching file. A finding whose fix needs one is deferred to the author with
+  `escalate.reason` (or "team policy: a person changes <path>"); ci-repair
+  classifies it `needs-decision`; incident stops with
+  `outcome=needs_decision`. A gate or deny-list elsewhere still applies.
+- **`lenses`**, **`ladder`**, **`models`**: as in `../../swarm/references/custom-lenses.md`
+  and `models.md`.
+- **`recipes`**: named step lists for `/shepherd <pr> --recipe <name>`. See
+  below.
+
+## Recipes
+
+A recipe is an ordered list of shepherd's own steps: `swarm`, `triage`,
+`simplify`, `ci-repair`, `stamp`, `incident`. `shepherd config validate`
+rejects an order that cannot work (triage before any swarm, stamp anywhere
+but last, a code change nothing reviews afterwards, a fixing step under
+`fixes.mode: suggest`, and under `local` a fix that only stamp reviews, since
+stamp sees the pushed head and local fixes never reach it). A built-in recipe
+the fix mode rules out is unavailable rather than an error; `shepherd preview
+--recipe <name>` says why. The built-in ones:
+
+| Recipe | Steps | Runs under |
+|---|---|---|
+| `review` | swarm | every mode |
+| `fix` | swarm, triage, simplify, swarm | local, push |
+| `pr` | swarm, triage, simplify, swarm, ci-repair, stamp | push |
+| `incident` | incident, swarm, triage, simplify, swarm, ci-repair, stamp | push |
+
+Without `--recipe`, `/shepherd` runs the recipe its fix mode selects:
+`review` under `suggest`, `fix` under `local`, `pr` under `push`. `pr` is
+shepherd's own loop (`../SKILL.md`, Steps 1 to 5).
+
+Running one:
+
+1. Run the steps in the order listed, one at a time. Code-changing steps
+   never overlap: they share one working tree and one branch.
+2. Each step keeps every rule of its own skill and of `AGENTS.md`.
+3. A review step (a swarm round that finds nothing new, or a stamp approval)
+   must run **after the last change** this iteration made. Otherwise the
+   result is `pending`, naming the step that still needs to review.
+
+## How a recipe finishes
+
+Finishing a recipe is not the same as a PR being ready. Report exactly one of:
+
+- **`reviewed`**: a recipe with no fixing step (`review`) finished. Findings
+  are posted for the author. It says nothing about merge readiness; never
+  call the PR ready or approved.
+- **`fixes_uncommitted`**: under `fixes.mode: local`, the fixes sit in the
+  working tree and the last swarm reviewed the tree, not the PR head. The PR
+  is unchanged; the person commits, pushes and runs again.
+- **`ready`**: only when all three hold on the current head: stamp approved
+  it, CI is green, and no review thread is open. A recipe without stamp can
+  reach `reviewed`, never `ready`.
+- **`pending`**: anything short of those, naming what is missing.
+
+## Packs and lens files
+
+A lens in a pack pinned to a commit (`github:owner/repo/pack.yml@<sha>`) can
+name a path in the pack's own repository (`skill: lenses/payments`). It
+resolves at the same commit, which must be on that repository's default branch: shepherd fetches that directory once into
+`~/.cache/shepherd/packs/`, keyed by the commit, and `config explain --json`
+gives the lens's `path` there. A bare name (`skill: payments-rules`) is an
+installed skill. A lens path in a pack inside this repository resolves in
+this repository. `shepherd config validate` reports a lens skill it cannot
+find.