@jagreehal/shepherd 0.3.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.
- package/AGENTS.md +5 -0
- package/README.md +41 -419
- package/THIRD_PARTY_NOTICES.md +11 -0
- package/lenses/dotnet/SKILL.md +32 -0
- package/lenses/go/SKILL.md +30 -0
- package/lenses/java/SKILL.md +31 -0
- package/lenses/nextjs/SKILL.md +33 -0
- package/lenses/node-api/SKILL.md +32 -0
- package/lenses/nx-monorepo/SKILL.md +30 -0
- package/lenses/observability/SKILL.md +18 -11
- package/lenses/owasp-asvs/SKILL.md +50 -0
- package/lenses/owasp-llm/SKILL.md +44 -0
- package/lenses/python/SKILL.md +32 -0
- package/lenses/react/SKILL.md +33 -0
- package/lenses/rust/SKILL.md +31 -0
- package/package.json +17 -8
- package/packs/dotnet.yml +6 -0
- package/packs/go.yml +6 -0
- package/packs/java.yml +6 -0
- package/packs/nextjs.yml +7 -0
- package/packs/node-api.yml +7 -0
- package/packs/nx-monorepo.yml +6 -0
- package/packs/observability.yml +6 -0
- package/packs/owasp-asvs.yml +6 -0
- package/packs/owasp-llm.yml +8 -0
- package/packs/python.yml +6 -0
- package/packs/react.yml +6 -0
- package/packs/rust.yml +6 -0
- package/skills/ci-repair/SKILL.md +6 -1
- package/skills/garden/SKILL.md +28 -3
- package/skills/garden/references/telemetry.md +50 -0
- package/skills/incident/SKILL.md +6 -1
- package/skills/lens-import/SKILL.md +185 -0
- package/skills/lens-import/references/conversion.md +96 -0
- package/skills/lens-import/scripts/check-import.mjs +154 -0
- package/skills/shepherd/SKILL.md +121 -6
- package/skills/shepherd/references/dispatch.md +12 -0
- package/skills/shepherd/references/models.md +20 -7
- package/skills/shepherd/references/policy.md +9 -5
- package/skills/shepherd/references/stories.md +102 -0
- package/skills/swarm/SKILL.md +16 -1
- package/skills/swarm/references/custom-lenses.md +50 -7
- package/skills/triage/SKILL.md +19 -0
- package/src/cli.ts +210 -16
- package/src/config.ts +137 -21
- package/src/garden-traces.ts +461 -0
- package/src/garden.ts +2 -1
- package/src/install.ts +3 -0
- package/src/lens.ts +159 -8
- package/src/notify.ts +138 -0
- package/src/stack.ts +121 -0
- package/src/trace.ts +180 -0
- package/templates/shepherd-audit.yml +178 -0
- package/templates/shepherd-incident.yml +180 -0
- package/templates/shepherd.yml +427 -0
package/src/cli.ts
CHANGED
|
@@ -6,17 +6,22 @@
|
|
|
6
6
|
// shepherd lens list
|
|
7
7
|
// shepherd models [ladder <model>... | pin <lens-or-runner> <model>] [--global]
|
|
8
8
|
// shepherd opencode-agents [--file <lenses.yml>] (agents for OpenCode 1.x, from the default branch's lenses.yml)
|
|
9
|
-
// shepherd garden <owner/repo>... [--since YYYY-MM-DD] [--min-prs <n>]
|
|
9
|
+
// 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>]
|
|
10
10
|
// shepherd local change [--base <ref>] (the change before a PR: unpushed commits, staged, unstaged, untracked)
|
|
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
|
+
// shepherd trace event <stage> <start|end> --pr <n> [--round <n>] [--outcome ok|failed|skipped] [--retries <n>] [--head <sha>]
|
|
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)
|
|
23
|
+
// shepherd notify --pr <n> --repo <owner/repo> --head <sha> --state success|failure|pending|error --file <description.txt>
|
|
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>]...
|
|
20
25
|
//
|
|
21
26
|
// Default: skills to ~/.claude/skills, the /shepherd command to ~/.claude/commands.
|
|
22
27
|
// --project installs into ./.claude of the current repository instead.
|
|
@@ -30,13 +35,18 @@ import { homedir, tmpdir } from "node:os";
|
|
|
30
35
|
import path from "node:path";
|
|
31
36
|
import { parseArgs } from "node:util";
|
|
32
37
|
import { parse as parseYaml, stringify } from "yaml";
|
|
33
|
-
import {
|
|
38
|
+
import { z } from "zod";
|
|
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";
|
|
34
40
|
import { ghThreads, snapshot, verdict } from "./acceptance.ts";
|
|
35
41
|
import { doctor } from "./doctor.ts";
|
|
42
|
+
import { fileLedger, notify, notifyOn, STATES, statusLedger } from "./notify.ts";
|
|
36
43
|
import { collect, collectEscapes, score } from "./garden.ts";
|
|
37
|
-
import {
|
|
44
|
+
import { collectTraces, tempoHeaders, traceLimits, traceScores } from "./garden-traces.ts";
|
|
45
|
+
import { install, type Outcome, pinWorkflow, uninstall } from "./install.ts";
|
|
38
46
|
import { buildDemo, captureChange, demoBugs, finish, receiptStatus } from "./local.ts";
|
|
39
|
-
import {
|
|
47
|
+
import { prStack } from "./stack.ts";
|
|
48
|
+
import { flush, recordEvent, traceFile } from "./trace.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";
|
|
40
50
|
|
|
41
51
|
const BUNDLE_ROOT = path.resolve(import.meta.dir, "..");
|
|
42
52
|
|
|
@@ -45,19 +55,26 @@ const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [
|
|
|
45
55
|
shepherd lens new <name> [--from <template>] [--applies <glob>]... [--description <text>]
|
|
46
56
|
shepherd lens add <skill> [--name <name>] [--applies <glob>]... [--description <text>] [--global]
|
|
47
57
|
shepherd lens list
|
|
48
|
-
shepherd models [ladder <model>... | pin <lens-or-
|
|
58
|
+
shepherd models [tier <name> <model> | ladder <model-or-tier>... | pin <runner-lens-or-group> <model-or-tier>] [--global]
|
|
59
|
+
shepherd ci-models
|
|
49
60
|
shepherd opencode-agents [--file <lenses.yml>]
|
|
50
|
-
shepherd garden <owner/repo>... [--since YYYY-MM-DD] [--min-prs <n>]
|
|
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>]
|
|
51
62
|
shepherd local change [--base <ref>]
|
|
52
63
|
shepherd local finish <record.json> [--base <ref>]
|
|
53
64
|
shepherd local status [--base <ref>]
|
|
54
65
|
shepherd local demo [<dir>]
|
|
55
|
-
shepherd init [--preset review-only|local-fix|push] [--from <pack>]
|
|
66
|
+
shepherd init [--preset review-only|local-fix|push] [--from <pack>] [--stacks]
|
|
56
67
|
shepherd config validate
|
|
57
68
|
shepherd config explain [--json] [--working-tree]
|
|
58
69
|
shepherd preview [--recipe <name>] [--base <ref>] [--working-tree]
|
|
59
70
|
shepherd doctor [--json]
|
|
60
|
-
shepherd acceptance <suggest|local> [--pr <n>] -- <agent command
|
|
71
|
+
shepherd acceptance <suggest|local> [--pr <n>] -- <agent command>...
|
|
72
|
+
shepherd trace event <stage> <start|end> --pr <n> [--round <n>] [--outcome ok|failed|skipped] [--retries <n>] [--head <sha>]
|
|
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>]...
|
|
74
|
+
shepherd stack <pr>
|
|
75
|
+
shepherd model-id <provider:model | provider/model>
|
|
76
|
+
shepherd workflows [--audit]
|
|
77
|
+
shepherd notify --pr <n> --repo <owner/repo> --head <sha> --state success|failure|pending|error --file <description.txt>`;
|
|
61
78
|
|
|
62
79
|
const { values: opts, positionals } = parseArgs({
|
|
63
80
|
allowPositionals: true,
|
|
@@ -74,13 +91,29 @@ const { values: opts, positionals } = parseArgs({
|
|
|
74
91
|
since: { type: "string" },
|
|
75
92
|
file: { type: "string" }, // opencode-agents: a lenses.yml to read instead of the default branch's
|
|
76
93
|
"min-prs": { type: "string", default: "3" },
|
|
94
|
+
traces: { type: "string", multiple: true }, // garden: OTLP JSON or collector JSON-lines files
|
|
95
|
+
"tempo-url": { type: "string" }, // garden: read-only Tempo API, never the OTLP ingest endpoint
|
|
96
|
+
"trace-retries": { type: "string" },
|
|
97
|
+
"trace-wait-ms": { type: "string" },
|
|
98
|
+
"trace-cost-usd": { type: "string" },
|
|
77
99
|
base: { type: "string" }, // local: the ref the change is measured from
|
|
78
100
|
from: { type: "string" }, // lens new: a starter lens in lenses/; init: the pack to extend
|
|
79
101
|
json: { type: "boolean", default: false },
|
|
80
102
|
"working-tree": { type: "boolean", default: false }, // explain, preview: your edits instead of the default branch
|
|
81
103
|
recipe: { type: "string" },
|
|
82
104
|
preset: { type: "string" }, // init: how far fixes go
|
|
83
|
-
|
|
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
|
|
107
|
+
pr: { type: "string" }, // acceptance: the PR whose threads must stay as they were; trace: the PR
|
|
108
|
+
round: { type: "string" }, // trace: the quality-loop round
|
|
109
|
+
outcome: { type: "string" }, // trace: how a step or iteration ended
|
|
110
|
+
retries: { type: "string" },
|
|
111
|
+
head: { type: "string" }, // trace, notify: the head SHA
|
|
112
|
+
state: { type: "string" }, // notify: the commit status state just set
|
|
113
|
+
repo: { type: "string" }, // trace flush: owner/repo
|
|
114
|
+
"ci-run": { type: "string" },
|
|
115
|
+
"ci-attempt": { type: "string" },
|
|
116
|
+
related: { type: "string", multiple: true }, // trace flush: traceparent of a related trace, such as stamp's review
|
|
84
117
|
},
|
|
85
118
|
});
|
|
86
119
|
|
|
@@ -183,17 +216,24 @@ if (command === "install") {
|
|
|
183
216
|
process.exitCode = 1;
|
|
184
217
|
}
|
|
185
218
|
}
|
|
186
|
-
} 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))) {
|
|
187
220
|
const file = opts.global ? globalLensFile(homedir()) : repoLensFile(repoRoot);
|
|
188
221
|
|
|
222
|
+
if (sub === "tier") orExit(() => setTier(file, skillRef!, rest[0]!));
|
|
223
|
+
|
|
189
224
|
if (sub === "ladder") orExit(() => setLadder(file, [skillRef!, ...rest]));
|
|
190
225
|
|
|
191
226
|
if (sub === "pin") orExit(() => pinModel(file, skillRef!, rest[0]!));
|
|
192
|
-
const
|
|
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)})`);
|
|
231
|
+
|
|
232
|
+
for (const [name, t] of Object.entries(effective.tiers)) console.log(`tier ${name.padEnd(18)} ${spelled(t.value)} (${t.source})`);
|
|
193
233
|
|
|
194
|
-
console.log(`ladder ${ladder?.join(" -> ") ?? "the harness's own (skills/shepherd/references/models.md)"}`);
|
|
234
|
+
console.log(`ladder ${ladder?.map(spelled).join(" -> ") ?? "the harness's own (skills/shepherd/references/models.md)"}`);
|
|
195
235
|
|
|
196
|
-
for (const [name, model] of Object.entries(models)) console.log(`pin ${name.padEnd(18)} ${model}`);
|
|
236
|
+
for (const [name, model] of Object.entries(models)) console.log(`pin ${name.padEnd(18)} ${spelled(model)}`);
|
|
197
237
|
|
|
198
238
|
if (sub) console.log(`\nwritten to ${file}${opts.global ? "" : `\n${MERGE_NOTE}`}`);
|
|
199
239
|
} else if (command === "opencode-agents") {
|
|
@@ -208,8 +248,31 @@ if (command === "install") {
|
|
|
208
248
|
// Default window: the last seven days, which the weekly gardener covers exactly.
|
|
209
249
|
const since = opts.since ?? new Date(Date.now() - 7 * 864e5).toISOString().slice(0, 10);
|
|
210
250
|
const repos = [sub, ...(skillRef ? [skillRef] : []), ...rest];
|
|
251
|
+
const files = opts.traces ?? orExit(() => z.array(z.string()).parse(JSON.parse(process.env.GARDEN_TRACE_FILES || "[]")));
|
|
252
|
+
const endpoint = opts["tempo-url"] ?? process.env.GARDEN_TEMPO_URL;
|
|
253
|
+
const headers = orExit(() => tempoHeaders(endpoint, process.env.GARDEN_TEMPO_URL, process.env.GARDEN_TEMPO_HEADERS));
|
|
254
|
+
const { GARDEN_DATADOG_SITE: site, GARDEN_DATADOG_API_KEY: apiKey, GARDEN_DATADOG_APP_KEY: appKey } = process.env;
|
|
255
|
+
const datadog = site && apiKey && appKey ? { site, apiKey, appKey } : undefined;
|
|
256
|
+
const positive = (v: string | undefined, fallback: number) => orExit(() => z.coerce.number().finite().positive().parse(v ?? fallback));
|
|
257
|
+
const limits = { retries: positive(opts["trace-retries"], traceLimits.retries), waitMs: positive(opts["trace-wait-ms"], traceLimits.waitMs), costUsd: positive(opts["trace-cost-usd"], traceLimits.costUsd) };
|
|
258
|
+
const reports = [];
|
|
259
|
+
|
|
260
|
+
orExit(() => z.iso.date().parse(since));
|
|
261
|
+
|
|
262
|
+
for (const repo of repos) {
|
|
263
|
+
const records = orExit(() => collect(repo, since));
|
|
264
|
+
const report = { repo, since, ...score(records, Number(opts["min-prs"])), escapes: orExit(() => collectEscapes(repo, since)) };
|
|
265
|
+
|
|
266
|
+
if (!files.length && !endpoint && !datadog) {
|
|
267
|
+
reports.push(report);
|
|
268
|
+
continue;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
const traces = traceScores(await collectTraces(files, endpoint, headers, repo, since, datadog), repo, records, since, limits);
|
|
272
|
+
reports.push({ ...report, prs: report.prs.map((pr) => ({ ...pr, signals: [...pr.signals, ...(traces.summaries.get(pr.number)?.signals ?? [])], telemetry: traces.summaries.get(pr.number) ?? null })), telemetry: { coverage: { ...traces.coverage, untouchedPrs: [...traces.summaries.keys()].filter((n) => !report.prs.some((pr) => pr.number === n)).length }, limits: traces.limits } });
|
|
273
|
+
}
|
|
211
274
|
|
|
212
|
-
console.log(JSON.stringify(
|
|
275
|
+
console.log(JSON.stringify(reports, null, 2));
|
|
213
276
|
} else if (command === "local" && sub === "change") {
|
|
214
277
|
console.log(JSON.stringify(orExit(() => captureChange(repoRoot, opts.base)), null, 2));
|
|
215
278
|
} else if (command === "local" && sub === "finish" && skillRef) {
|
|
@@ -233,10 +296,94 @@ if (command === "install") {
|
|
|
233
296
|
for (const b of demoBugs()) console.log(` ${`${b.file}:${b.lines[0]}`.padEnd(18)} ${b.class} (${b.enters_as})`);
|
|
234
297
|
|
|
235
298
|
console.log(`\nNext: cd ${app}, open your coding agent there, and run /shepherd --local.`);
|
|
299
|
+
} else if (command === "trace" && (sub === "event" || sub === "flush")) {
|
|
300
|
+
const pr = Number(opts.pr);
|
|
301
|
+
|
|
302
|
+
const count = (flag: string, v: string | undefined) =>
|
|
303
|
+
v === undefined
|
|
304
|
+
? undefined
|
|
305
|
+
: orExit(() => {
|
|
306
|
+
if (!/^\d+$/.test(v)) throw new Error(`trace needs --${flag} as a whole number`);
|
|
307
|
+
|
|
308
|
+
return Number(v);
|
|
309
|
+
});
|
|
310
|
+
|
|
311
|
+
if (!Number.isInteger(pr) || pr <= 0) orExit(() => {
|
|
312
|
+
throw new Error("trace needs --pr <number>");
|
|
313
|
+
});
|
|
314
|
+
|
|
315
|
+
if (sub === "event") {
|
|
316
|
+
orExit(() => recordEvent(traceFile(repoRoot, pr), { stage: skillRef ?? "", phase: rest[0] ?? "", round: count("round", opts.round), outcome: opts.outcome, retries: count("retries", opts.retries), head_sha: opts.head }));
|
|
317
|
+
} else {
|
|
318
|
+
if (!opts.repo || !opts.head || !opts.outcome) orExit(() => {
|
|
319
|
+
throw new Error("trace flush needs --repo, --head and --outcome");
|
|
320
|
+
});
|
|
321
|
+
|
|
322
|
+
const result = await flush(traceFile(repoRoot, pr), { repo: opts.repo ?? "", pr, headSha: opts.head ?? "", baseSha: opts.base, outcome: opts.outcome ?? "", ciRun: count("ci-run", opts["ci-run"]), ciAttempt: count("ci-attempt", opts["ci-attempt"]), links: opts.related ?? [] });
|
|
323
|
+
|
|
324
|
+
console.log(JSON.stringify(result, null, 2));
|
|
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));
|
|
340
|
+
} else if (command === "workflows") {
|
|
341
|
+
const dest = path.join(repoRoot, ".github", "workflows");
|
|
342
|
+
|
|
343
|
+
mkdirSync(dest, { recursive: true });
|
|
344
|
+
|
|
345
|
+
for (const name of ["shepherd.yml", "shepherd-incident.yml", ...(opts.audit ? ["shepherd-audit.yml"] : [])]) {
|
|
346
|
+
const to = path.join(dest, name);
|
|
347
|
+
|
|
348
|
+
if (existsSync(to)) {
|
|
349
|
+
console.log(`kept .github/workflows/${name} (exists)`);
|
|
350
|
+
continue;
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
// Pin the workflow to the version that wrote it, so its skills match this CLI.
|
|
354
|
+
const version = z.object({ version: z.string() }).parse(JSON.parse(readFileSync(path.join(BUNDLE_ROOT, "package.json"), "utf8"))).version;
|
|
355
|
+
|
|
356
|
+
writeFileSync(to, pinWorkflow(readFileSync(path.join(BUNDLE_ROOT, "templates", name), "utf8"), version));
|
|
357
|
+
console.log(`wrote .github/workflows/${name}`);
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
console.log("\nNext: name your CI workflow in each file's `workflows:` list, add the SHEPHERD_TOKEN and OPENCODE_API_KEY secrets, then merge.\nOptional: SHEPHERD_LABEL (handoff label), SHEPHERD_NOTIFY_WEBHOOK (Slack or any JSON endpoint).");
|
|
361
|
+
} else if (command === "notify") {
|
|
362
|
+
const pr = Number(opts.pr);
|
|
363
|
+
const state = STATES.find((s) => s === opts.state);
|
|
364
|
+
|
|
365
|
+
if (!Number.isInteger(pr) || pr <= 0 || !opts.repo || !opts.head || !state || !opts.file) orExit(() => {
|
|
366
|
+
throw new Error("notify needs --pr, --repo, --head, --state success|failure|pending|error and --file");
|
|
367
|
+
});
|
|
368
|
+
|
|
369
|
+
// The description comes from a file: it can quote PR-authored text, which must never reach a shell.
|
|
370
|
+
const description = orExit(() => readFileSync(opts.file ?? "", "utf8")).trim().slice(0, 300);
|
|
371
|
+
const url = `${process.env.GITHUB_SERVER_URL || "https://github.com"}/${opts.repo}/pull/${pr}`;
|
|
372
|
+
const event = { event: "shepherd.state" as const, repo: opts.repo ?? "", pr, url, head_sha: opts.head ?? "", state: state ?? "pending", description };
|
|
373
|
+
|
|
374
|
+
console.log(`notify: ${await notify(process.env.SHEPHERD_NOTIFY_WEBHOOK, event, notifyOn(process.env.SHEPHERD_NOTIFY_ON), [fileLedger(repoRoot, pr), statusLedger(opts.repo ?? "", opts.head ?? "", repoRoot)])}`);
|
|
236
375
|
} else if (command === "init") {
|
|
237
376
|
const file = path.join(repoRoot, TEAM_FILES[0]!);
|
|
238
377
|
|
|
239
|
-
|
|
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`); });
|
|
240
387
|
const legacy = workingTree(TEAM_FILES[1]!);
|
|
241
388
|
const seed = legacy ? orExit(() => ConfigSchema.parse(parseYaml(legacy) ?? {})) : { lenses: {} };
|
|
242
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.
|
|
@@ -250,9 +397,22 @@ if (command === "install") {
|
|
|
250
397
|
if (opts.from) config.extends = [opts.from, ...(seed.extends ?? [])];
|
|
251
398
|
|
|
252
399
|
if (mode) config.fixes = { mode };
|
|
400
|
+
const stacks = detectStacks(trackedFiles(), workingTree);
|
|
401
|
+
|
|
253
402
|
mkdirSync(path.dirname(file), { recursive: true });
|
|
254
403
|
writeFileSync(file, `# shepherd team policy. Presets: review-only (fixes.mode suggest), local-fix (local), push.\n${stringify(config)}`);
|
|
255
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
|
+
|
|
256
416
|
validate();
|
|
257
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}`);
|
|
258
418
|
} else if (command === "config" && sub === "validate") {
|
|
@@ -313,6 +473,14 @@ if (command === "install") {
|
|
|
313
473
|
process.exit(2);
|
|
314
474
|
}
|
|
315
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
|
+
|
|
316
484
|
function workingTree(rel: string): string | null {
|
|
317
485
|
const file = path.join(repoRoot, rel);
|
|
318
486
|
|
|
@@ -325,6 +493,29 @@ function personal(): Config | null {
|
|
|
325
493
|
return existsSync(file) ? ConfigSchema.parse(parseYaml(readFileSync(file, "utf8")) ?? {}) : null;
|
|
326
494
|
}
|
|
327
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
|
+
|
|
328
519
|
/** Team policy from the default branch, the source swarm reviews under, or from your working tree. */
|
|
329
520
|
function policy(fromTree: boolean) {
|
|
330
521
|
const read: Read = fromTree ? workingTree : orExit(() => defaultBranchReader(repoRoot));
|
|
@@ -361,6 +552,9 @@ function explain(p: Effective & { teamFile: string | null }): void {
|
|
|
361
552
|
|
|
362
553
|
console.log(`policy file: ${p.teamFile ?? "none (built-in defaults)"}${opts["working-tree"] ? ", working tree" : ", default branch"}\n`);
|
|
363
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
|
+
|
|
364
558
|
row("ladder", p.ladder?.value.join(" -> ") ?? "the harness's own", p.ladder?.source ?? "built-in");
|
|
365
559
|
|
|
366
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
|
-
//
|
|
26
|
-
|
|
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
|
|
44
|
-
lenses: z.record(z.string().regex(NAME),
|
|
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
|
-
|
|
103
|
-
|
|
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
|
-
|
|
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
|
|
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))
|
|
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 ?? []).
|
|
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
|
|
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.
|
|
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))
|
|
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
|
-
|
|
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)
|
|
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
|
-
|
|
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}`;
|