@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/AGENTS.md
CHANGED
|
@@ -48,6 +48,11 @@ to all of them.
|
|
|
48
48
|
short must never be possible. This is shepherd's only status write.
|
|
49
49
|
- **Behaviour changes made during review are disclosed** in one marked section
|
|
50
50
|
of the PR description; the rest of the body is the author's.
|
|
51
|
+
- **In CI the model holds no write credential.** Handoff mode commits and
|
|
52
|
+
never pushes; a job with no model pushes the bundle after its fast-forward
|
|
53
|
+
and path checks. Never name `SHEPHERD_TOKEN` anywhere in the model's job (a secret any
|
|
54
|
+
step uses sits in the job's runner memory), persist a checkout token, or
|
|
55
|
+
grant `contents: write`; `src/workflow.test.ts` pins this.
|
|
51
56
|
- **Local mode touches nothing on GitHub.** `--local` never pushes, posts,
|
|
52
57
|
resolves, sets a status, or commits: fixes stay in the working tree for the
|
|
53
58
|
developer. It reports "local checks passed", never merge-ready.
|
package/README.md
CHANGED
|
@@ -1,446 +1,68 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Shepherd
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Shepherd reviews changes, fixes findings and repairs CI through skills in your coding agent. Use it before you open a PR, on an existing PR, or through GitHub Actions.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Use Shepherd to work through review comments and failing CI logs under your team's policy. It leaves human decisions for you. [Stamp](https://github.com/jagreehal/stamp) supplies the approval verdict; you decide when to merge.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
flowchart LR
|
|
9
|
-
PR[You open a PR] --> SH[shepherd loop<br/>in your coding agent]
|
|
10
|
-
SH --> R[Review, fix,<br/>repair CI]
|
|
11
|
-
R --> SH
|
|
12
|
-
SH --> ST[stamp in CI<br/>decides approval]
|
|
13
|
-
ST --> M[You merge]
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
shepherd gets the PR ready; stamp decides whether it gets approved. shepherd works on GitHub only and reads and writes through `gh`.
|
|
7
|
+
## Start here
|
|
17
8
|
|
|
18
|
-
|
|
9
|
+
- [Run your first review](docs/src/content/docs/start/quickstart.md)
|
|
10
|
+
- [Choose local review, a PR loop, or CI](docs/src/content/docs/start/choose-a-setup.md)
|
|
11
|
+
- [Browse the documentation](docs/src/content/docs/index.md)
|
|
19
12
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
```mermaid
|
|
23
|
-
flowchart TD
|
|
24
|
-
subgraph Without["Without shepherd"]
|
|
25
|
-
A1[Read bot comments] --> A2[Paste into agent]
|
|
26
|
-
A2 --> A3[Push fix]
|
|
27
|
-
A3 --> A4[CI fails]
|
|
28
|
-
A4 --> A5[Paste log into agent]
|
|
29
|
-
A5 --> A3
|
|
30
|
-
end
|
|
31
|
-
subgraph With["With shepherd"]
|
|
32
|
-
B1["/loop 5m /shepherd 42"] --> B2[Review, triage,<br/>CI repair, verdict]
|
|
33
|
-
B2 --> B3{Needs you?}
|
|
34
|
-
B3 -- no --> B2
|
|
35
|
-
B3 -- yes --> B4[Commit status names<br/>what you need to do]
|
|
36
|
-
end
|
|
37
|
-
```
|
|
13
|
+
You need Bun 1.2 or later, Git, an authenticated GitHub CLI and a coding agent that can load skills and run subagents.
|
|
38
14
|
|
|
39
|
-
|
|
40
|
-
- A second model verifies each serious finding before it posts, so you read fewer false alarms.
|
|
41
|
-
- shepherd never replies to people and never approves. Those stay yours.
|
|
42
|
-
- A `shepherd` commit status shows where the loop got to, and a branch rule can require it.
|
|
43
|
-
|
|
44
|
-
## Install
|
|
15
|
+
In your terminal, from the repository clone:
|
|
45
16
|
|
|
46
17
|
```bash
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
18
|
+
bun add -g @jagreehal/shepherd
|
|
19
|
+
shepherd install
|
|
20
|
+
shepherd init --preset review-only
|
|
21
|
+
shepherd config validate
|
|
22
|
+
shepherd preview --working-tree
|
|
50
23
|
```
|
|
51
24
|
|
|
52
|
-
The
|
|
25
|
+
The default install targets Claude Code. For another harness, use `shepherd install --target <skills-directory>`. Commit and merge the generated review-only policy before you run it against a PR: PR reviews read policy from the default branch. Without policy, the built-in fix mode is `push`.
|
|
53
26
|
|
|
54
|
-
|
|
27
|
+
In your coding agent:
|
|
55
28
|
|
|
56
29
|
```text
|
|
57
|
-
/shepherd 42
|
|
58
|
-
/loop 5m /shepherd 42 # hands-off: an iteration every five minutes
|
|
59
|
-
/swarm 42 # the review on its own
|
|
60
|
-
/triage 42 # thread triage on its own
|
|
61
|
-
/ci-repair 42 # CI on its own
|
|
62
|
-
/review-security # one lens on the current diff
|
|
63
|
-
/shepherd --local # before a PR: review and fix your change on this machine
|
|
64
|
-
/swarm --local # before a PR: review only, print the findings
|
|
65
|
-
/incident <run-url|issue|error.txt> # after merge: a failure becomes an issue, a reproducing test and a fix PR
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
## Before you open a PR
|
|
69
|
-
|
|
70
|
-
`/shepherd --local` reviews and fixes your change before it reaches GitHub. It uses the same lenses, verification and fix rules as the PR loop, and it never pushes, comments, commits or sets a status. You commit the fixes.
|
|
71
|
-
|
|
72
|
-
```mermaid
|
|
73
|
-
flowchart TD
|
|
74
|
-
C[shepherd local change<br/>unpushed commits, staged,<br/>unstaged, untracked] --> S[swarm --local<br/>checks, router, lenses, verify]
|
|
75
|
-
S --> F{shepherd local finish}
|
|
76
|
-
F -- incomplete --> I[Review incomplete:<br/>what was not reviewed]
|
|
77
|
-
F -- complete --> T[triage, local:<br/>fix in the working tree]
|
|
78
|
-
T --> SI[simplify]
|
|
79
|
-
SI --> Q{Clean round?}
|
|
80
|
-
Q -- no --> C
|
|
81
|
-
Q -- "a decision is yours" --> Y[Needs you:<br/>each option listed]
|
|
82
|
-
Q -- yes --> P[Local checks passed]
|
|
83
|
-
P --> PR[Open the PR,<br/>then /shepherd <pr>]
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
The change covers the commits your branch has that its upstream (or the remote's default branch) lacks, staged and unstaged edits, and untracked files `.gitignore` does not exclude. shepherd reads untracked files through a copy of the index, so your own staging stays as you left it.
|
|
87
|
-
|
|
88
|
-
`shepherd local finish` checks each review against the change before anyone reads it as clean:
|
|
89
|
-
|
|
90
|
-
- every stage ran, and every lens ended `ok`;
|
|
91
|
-
- every changed line range reached at least one reviewer;
|
|
92
|
-
- each finding names a line its file has;
|
|
93
|
-
- each check finding was raised or dropped with a reason;
|
|
94
|
-
- the files did not change while the review ran.
|
|
95
|
-
|
|
96
|
-
Anything short of that reports **review incomplete** with what is missing. It proves each line was put in front of a reviewer, which is less than proof that the reviewer understood it.
|
|
97
|
-
|
|
98
|
-
A complete review writes a receipt keyed to a fingerprint of the exact content. `shepherd local status` tells you whether the files on disk still match a reviewed change; any edit since makes it `changed`. Wire it into a pre-push hook if you want one.
|
|
99
|
-
|
|
100
|
-
Local mode ends with **local checks passed**, **needs you**, **review incomplete**, or the round cap. Merge readiness still belongs to the PR loop and stamp.
|
|
101
|
-
|
|
102
|
-
Try it on planted bugs:
|
|
103
|
-
|
|
104
|
-
```bash
|
|
105
|
-
bunx @jagreehal/shepherd local demo # prints the repository path and the bugs to expect
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
The demo repository carries seven bugs, one per way a change reaches the review: an unpushed commit, a staged edit, an unstaged edit, an untracked file and a deleted check. `examples/local-demo/expected.json` lists each one with its lines.
|
|
109
|
-
|
|
110
|
-
## How it works
|
|
111
|
-
|
|
112
|
-
### One iteration
|
|
113
|
-
|
|
114
|
-
```mermaid
|
|
115
|
-
flowchart TD
|
|
116
|
-
S[Resolve the PR] --> Q[Quality round]
|
|
117
|
-
subgraph Round["Quality loop, up to 4 rounds"]
|
|
118
|
-
Q --> SW[swarm: review]
|
|
119
|
-
SW --> TR[triage: work every thread]
|
|
120
|
-
TR --> SI[simplify]
|
|
121
|
-
SI --> DRY{Dry round?}
|
|
122
|
-
DRY -- no --> Q
|
|
123
|
-
end
|
|
124
|
-
DRY -- yes --> CI[ci-repair]
|
|
125
|
-
CI --> V[stamp verdict]
|
|
126
|
-
V --> SUM[Summary and<br/>commit status]
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
A round is dry when triage fixed, resolved and promoted nothing, simplify changed nothing, and no bot review is still on its way. Round 1's fixes always get a second review round.
|
|
130
|
-
|
|
131
|
-
### The review swarm
|
|
132
|
-
|
|
133
|
-
```mermaid
|
|
134
|
-
flowchart LR
|
|
135
|
-
D[Diff] --> CK[Repo checks and installed scanners:<br/>lint, typecheck, nearby tests,<br/>gitleaks, semgrep, osv-scanner and more]
|
|
136
|
-
CK --> RT[Cheap router review]
|
|
137
|
-
RT --> L1[review-correctness]
|
|
138
|
-
RT --> L2[review-security]
|
|
139
|
-
RT --> L3[review-simplicity]
|
|
140
|
-
RT --> L4[review-maintainability]
|
|
141
|
-
RT --> L5[review-slop]
|
|
142
|
-
RT --> L6[review-spec<br/>when an issue or spec is linked]
|
|
143
|
-
RT --> LT[Your team's lenses]
|
|
144
|
-
L1 & L2 & L3 & L4 & L5 & L6 & LT --> VF{HIGH or CRITICAL?}
|
|
145
|
-
VF -- yes --> V2[Second model quotes<br/>the code or drops it]
|
|
146
|
-
VF -- no --> P
|
|
147
|
-
V2 --> P[Inline comments<br/>and one summary comment]
|
|
30
|
+
/shepherd 42
|
|
148
31
|
```
|
|
149
32
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
### Triage
|
|
153
|
-
|
|
154
|
-
```mermaid
|
|
155
|
-
flowchart TD
|
|
156
|
-
T[Open review thread] --> H{A human has joined?}
|
|
157
|
-
H -- yes --> W[Leave it for you]
|
|
158
|
-
H -- no --> J{Judgement}
|
|
159
|
-
J --> F[Fixed, with a commit]
|
|
160
|
-
J --> R[Resolved]
|
|
161
|
-
J --> DF[Deferred]
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
Triage ends each thread fixed, resolved or deferred. It never replies and never touches a thread a person is in.
|
|
165
|
-
|
|
166
|
-
## The skills
|
|
167
|
-
|
|
168
|
-
| Skill | Does |
|
|
169
|
-
|---|---|
|
|
170
|
-
| `shepherd` | Runs the loop: review rounds until dry, then CI, then the stamp verdict. Owns state, model choice, and when to ask you. |
|
|
171
|
-
| `swarm` | Runs the repo's own checks, then a cheap router review that hands risky hunks to the lenses in parallel, verifies serious findings, and posts inline comments plus one summary comment. |
|
|
172
|
-
| `triage` | Ends every review thread fixed, resolved, or deferred. Never replies, never touches a thread a human is in. |
|
|
173
|
-
| `ci-repair` | Updates a stale branch, diagnoses failing checks to the leaf job, makes one verified fix, reruns flaky jobs once. |
|
|
174
|
-
| `incident` | After merge: turns a red default-branch run or a production error into an `incident` issue, a reproducing test, the PR that caused it (by bisecting with that test), and a fix PR the loop then takes over. |
|
|
175
|
-
| `pair` | The act / act-and-say / stop-and-ask ladder that decides when to ask you. |
|
|
176
|
-
| `review-correctness` | Bugs: data, concurrency, performance, API contracts, frontend state, tests. |
|
|
177
|
-
| `review-security` | Exploitable source-to-sink paths, each with its data flow and fix. |
|
|
178
|
-
| `review-simplicity` | The four rules of simple design; what to delete and what replaces it. |
|
|
179
|
-
| `review-maintainability` | Coupling, rollout safety, observability, naming, and the repo's own written rules. |
|
|
180
|
-
| `review-slop` | Low-signal code and prose: thrown-away types, defensive noise, tests that cannot fail, padded PR text. |
|
|
181
|
-
| `review-spec` | The change against its issue or spec: requirements missing, built wrong, or not asked for. |
|
|
182
|
-
| `code-review`, `diagnosing-bugs`, `pr`, `retro`, `writing-for-agents` | [Matt Pocock's skills](https://github.com/mattpocock/skills), copied unchanged. `review-spec` runs code-review's Spec axis, `review-simplicity` adds its smell baseline, ci-repair diagnoses with diagnosing-bugs, shepherd writes PR bodies with pr when the repo has no PR skill, and garden sorts causes with retro and writes skill text by writing-for-agents. |
|
|
183
|
-
| `garden` | The outer loop: scores shepherd's recent runs from GitHub and opens PRs with skill edits and lint rules for findings that keep recurring. |
|
|
184
|
-
|
|
185
|
-
### When it asks you
|
|
186
|
-
|
|
187
|
-
```mermaid
|
|
188
|
-
flowchart LR
|
|
189
|
-
X[Something to do] --> P{pair ladder}
|
|
190
|
-
P -- clearly better,<br/>one sensible way --> A[Just do it]
|
|
191
|
-
P -- more than one<br/>reasonable answer --> AS[Do it, then say so]
|
|
192
|
-
P -- breaks simple design, unclear,<br/>or changes relied-on behaviour --> SA[Stop and ask]
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
## Add your own reviewers
|
|
196
|
-
|
|
197
|
-
Any skill can review code as a swarm lens: React performance rules, your design system, your API conventions. Point shepherd at the skill and the files it cares about:
|
|
198
|
-
|
|
199
|
-
```bash
|
|
200
|
-
bunx @jagreehal/shepherd lens new react --applies '**/*.tsx' # scaffolds .shepherd/lenses/react/SKILL.md
|
|
201
|
-
bunx @jagreehal/shepherd lens add vercel-react-best-practices --name react-perf \
|
|
202
|
-
--applies '**/*.tsx' --applies '**/*.jsx' # an existing skill, into .shepherd/lenses.yml
|
|
203
|
-
bunx @jagreehal/shepherd lens add ~/skills/house-style --name house --global # personal preview
|
|
204
|
-
bunx @jagreehal/shepherd lens list
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
```yaml
|
|
208
|
-
# .shepherd/lenses.yml
|
|
209
|
-
lenses:
|
|
210
|
-
react:
|
|
211
|
-
skill: vercel-react-best-practices # an installed skill, or a path to one in the repo
|
|
212
|
-
applies_to: ['**/*.tsx', '**/*.jsx'] # runs whenever a matching file changes
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
```mermaid
|
|
216
|
-
flowchart TD
|
|
217
|
-
L[Lens in .shepherd/lenses.yml<br/>read from the default branch] --> A{applies_to set?}
|
|
218
|
-
A -- yes --> M[Runs on each PR that<br/>touches a matching file]
|
|
219
|
-
A -- no --> R[Router calls it when<br/>its description fits]
|
|
220
|
-
M & R --> RV["Skill's ## Review section<br/>is the checklist"]
|
|
221
|
-
RV --> P["Findings post as [lens/rule-id]"]
|
|
222
|
-
P --> T["Triage fixes them,<br/>following the skill's ## Fix"]
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
Swarm wraps the skill in a review-only brief. The skill's `## Review` section is the checklist, and its findings post like any other lens's (`[react/async-parallel]`). Triage fixes them, following the skill's `## Fix` section when it has one. Nothing in a lens can loosen shepherd's own rules.
|
|
226
|
-
|
|
227
|
-
shepherd reads the repository's lens file from the default branch, so a PR cannot pick its own reviewers. Run `/swarm --preview` to try a lens from your working tree before you merge it: it reports which files each lens matched and what it found, and posts nothing. `lens list` checks each lens (a description, a `## Review` with unique rule ids) and exits non-zero on a problem.
|
|
228
|
-
|
|
229
|
-
A `--global` lens is a personal preview. Swarm prints its findings locally and never posts them, so you can try a lens on real PRs before you commit it for the team.
|
|
230
|
-
|
|
231
|
-
### Starter lenses
|
|
232
|
-
|
|
233
|
-
A team that wants every change checked for observability can start from the bundled pack instead of a blank file:
|
|
234
|
-
|
|
235
|
-
```bash
|
|
236
|
-
bunx @jagreehal/shepherd lens new observability --from observability --applies 'src/**'
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
That copies `lenses/observability/SKILL.md` into `.shepherd/lenses/observability/` and registers it. Its seven rules flag outbound calls with no span or log, errors that lose their cause, unstructured logs, secrets or personal data in telemetry, silent data drops, unbounded labels, and user-facing changes with no signal. Its `## Fix` section has triage reach for the repository's existing logger and tracer, and send anything that adds a telemetry dependency to you. Edit the rules to fit; `shepherd lens list` shows the templates.
|
|
240
|
-
|
|
241
|
-
### The same pack in stamp
|
|
33
|
+
Replace `42` with your PR number. Expect findings on the PR and a `reviewed` result under review-only policy. Read the [first-run guide](docs/src/content/docs/start/quickstart.md) for setup checks and expected results.
|
|
242
34
|
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
```mermaid
|
|
246
|
-
flowchart LR
|
|
247
|
-
P[.shepherd/lenses/observability/SKILL.md] --> L[shepherd lens:<br/>findings, then triage fixes<br/>following its Fix section]
|
|
248
|
-
P --> R[stamp rule pack:<br/>the reviewer refuses, escalates<br/>or notes a broken rule]
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
```yaml
|
|
252
|
-
# .stamp/policy.yml
|
|
253
|
-
rules:
|
|
254
|
-
observability:
|
|
255
|
-
skill: .shepherd/lenses/observability
|
|
256
|
-
applies_to: ['src/**']
|
|
257
|
-
on_break: escalate
|
|
258
|
-
```
|
|
259
|
-
|
|
260
|
-
Both read the pack from the default branch, so a PR cannot change the rules it is judged by. stamp also sends any PR that edits a configured pack to a human, since the pack's rules are trusted context for every later review.
|
|
261
|
-
|
|
262
|
-
## Team policy
|
|
263
|
-
|
|
264
|
-
`.shepherd/config.yml` holds a team's policy: its lenses and models, plus the checks to run, how far fixes go, what a person must decide, and named recipes. An organisation keeps a pack, and each repository extends it and overrides what it needs.
|
|
265
|
-
|
|
266
|
-
```yaml
|
|
267
|
-
# .shepherd/config.yml
|
|
268
|
-
extends:
|
|
269
|
-
- .shepherd/packs/acme.yml # in this repository
|
|
270
|
-
- github:acme/policy/shepherd.yml@0123456789abcdef0123456789abcdef01234567 # another, pinned to a commit
|
|
271
|
-
|
|
272
|
-
lenses:
|
|
273
|
-
payments:
|
|
274
|
-
skill: .shepherd/lenses/payments
|
|
275
|
-
applies_to: ["src/payments/**"]
|
|
276
|
-
|
|
277
|
-
checks: # swarm runs exactly these; ci-repair and incident use them too
|
|
278
|
-
unit: { command: bun test }
|
|
279
|
-
types: { command: bun run typecheck }
|
|
280
|
-
|
|
281
|
-
fixes:
|
|
282
|
-
mode: local # suggest: change nothing | local: fix, never commit | push (default)
|
|
283
|
-
|
|
284
|
-
escalate:
|
|
285
|
-
paths: ["migrations/**", "src/public-api/**"]
|
|
286
|
-
reason: a person decides schema and public API changes
|
|
287
|
-
|
|
288
|
-
recipes: # /shepherd 42 --recipe quick
|
|
289
|
-
quick: { steps: [swarm, triage, swarm] }
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
Settings apply in one order: built-in defaults, then each pack in the order listed, then the repository file. A later layer replaces a setting, and merges `lenses`, `checks`, `models` and `recipes` by name. A pack cannot extend another pack. A pack from another repository must name a full commit, since a branch or tag can move under you. shepherd reads the file and its packs from the default branch, so a PR cannot change the policy it is reviewed under. Personal settings in `~/.config/shepherd/lenses.yml` stay a preview: their lenses print locally and never post, their ladder and pins fill in only where the team set none, and they cannot touch checks, fixes, escalation or recipes. A repository with only `.shepherd/lenses.yml` keeps working; it is read the same way.
|
|
293
|
-
|
|
294
|
-
A recipe composes shepherd's own steps: `swarm`, `triage`, `simplify`, `ci-repair`, `stamp`, `incident`. They run one at a time, and a recipe reports success only when a review ran after its last change. Validation rejects an order that cannot hold: triage before any swarm, stamp anywhere but last, a change nothing reviews afterwards, a fixing step under `fixes.mode: suggest`, or, under `local`, a fix only stamp reviews (stamp sees the pushed head, which local fixes never reach). The built-in `review`, `fix`, `pr` and `incident` recipes are listed by `config explain`; one the fix mode rules out shows as blocked in `preview`. Custom runners come later, once their contracts are defined.
|
|
295
|
-
|
|
296
|
-
```bash
|
|
297
|
-
bunx @jagreehal/shepherd init # review-only: shepherd posts findings and changes no code
|
|
298
|
-
bunx @jagreehal/shepherd init --preset local-fix # fixes land in your working tree, never committed
|
|
299
|
-
bunx @jagreehal/shepherd init --preset push # fixes are committed and pushed to the PR branch
|
|
300
|
-
bunx @jagreehal/shepherd init --from .shepherd/packs/acme.yml # extend a pack and keep its fix mode
|
|
301
|
-
bunx @jagreehal/shepherd config validate # your edits: exits 1 on a problem, so CI can run it
|
|
302
|
-
bunx @jagreehal/shepherd config explain # effective policy on the default branch, and each setting's source
|
|
303
|
-
bunx @jagreehal/shepherd preview --recipe pr # on your change: the full plan (see below)
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
Run `preview --working-tree` before you merge a policy change. It lists every reviewer, built-in and custom, with the model each one runs on and where that model came from; the checks; what each step can write, locally or to GitHub; anything escalated to a person; and how the recipe finishes. A finished `review` recipe means findings were posted, not that the PR is ready. Under `local-fix` the result is fixes left uncommitted. A PR is ready only when stamp approves its head, CI is green and no review thread is open. Running `init` in a repository that has only `.shepherd/lenses.yml` carries its settings over and keeps push mode.
|
|
307
|
-
|
|
308
|
-
A lens can travel with a pinned pack: a path in the pack (`skill: lenses/payments`) names a directory in the pack's repository at the pinned commit, and shepherd fetches it into a cache keyed by that commit. [docs/onboarding.md](docs/onboarding.md) shows the layout and how CI reads a private pack. `config validate` and `doctor` report a lens skill they cannot find.
|
|
309
|
-
|
|
310
|
-
New to shepherd? [docs/onboarding.md](docs/onboarding.md) walks through install, `doctor`, `init`, validate, preview, merging the policy and the first review.
|
|
311
|
-
|
|
312
|
-
`config explain --working-tree` and `preview --working-tree` read your uncommitted edits instead of the default branch. The skills load the policy with `config explain --json` (`skills/shepherd/references/policy.md`).
|
|
313
|
-
|
|
314
|
-
## Choose the models
|
|
315
|
-
|
|
316
|
-
Use any provider your harness can reach. Model ids pass straight to its agent tool: `haiku` on Claude Code, `provider/model` on OpenCode.
|
|
317
|
-
|
|
318
|
-
```bash
|
|
319
|
-
shepherd models ladder opencode-go/deepseek-v4-flash opencode-go/glm-5.3 opencode-go/kimi-k3 # cheapest first
|
|
320
|
-
shepherd models pin security opencode-go/qwen3.8-max # a lens or runner always on this model
|
|
321
|
-
shepherd lens add react-rules --applies '**/*.tsx' --model opencode-go/kimi-k2.7-code
|
|
322
|
-
shepherd models # what will run
|
|
323
|
-
shepherd opencode-agents # agents per rung and pin, for OpenCode 1.x
|
|
324
|
-
```
|
|
325
|
-
|
|
326
|
-
```mermaid
|
|
327
|
-
flowchart LR
|
|
328
|
-
subgraph Ladder["Model ladder, cheapest first"]
|
|
329
|
-
R1[rung 1] --> R2[rung 2] --> R3[rung 3] --> R4[rung 4]
|
|
330
|
-
end
|
|
331
|
-
RD[Reading work:<br/>router, simplify] --> R1
|
|
332
|
-
WR[Runners that push commits<br/>or resolve threads] --> R2
|
|
333
|
-
VF[Validating risky changes<br/>and serious findings] -- a stronger model --> R4
|
|
334
|
-
PIN[Pinned lens or runner] --> PM[Its pinned model]
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
Both settings land in `.shepherd/lenses.yml` (`--global` for `~/.config/shepherd/lenses.yml`). The repository's ladder wins over yours, and shepherd reads it from the default branch like the lenses. With nothing set, shepherd uses the harness's own ladder.
|
|
338
|
-
|
|
339
|
-
OpenCode 1.x subagents take no model, so `shepherd opencode-agents` prints an agent per rung and per pin to merge into `OPENCODE_CONFIG_CONTENT`; swarm then dispatches by agent name.
|
|
340
|
-
|
|
341
|
-
## What it holds to
|
|
342
|
-
|
|
343
|
-
- **Machines first.** Swarm runs your lint, typecheck and nearby tests before any model reads the diff, plus the scanners you have installed (`gitleaks`, `semgrep`, `osv-scanner`, `actionlint`, `shellcheck`, `hadolint`) on the files they read. It keeps findings on changed lines, lists each suppression comment the PR adds, and tells the models not to repeat what the tools found. If the repo uses Oxlint's anti-slop rules, those findings come for free.
|
|
344
|
-
- **Cheapest model that can do the job.** Reading work (the review router, simplify) starts at the bottom of the ladder (`haiku` -> `sonnet` -> `opus` -> `fable` on Claude Code). Runners that push commits or resolve threads start one rung up, where trials showed they stop needing a redo. A stronger model validates risky changes and serious findings; it never replaces a test.
|
|
345
|
-
- **Verified findings.** A second model checks each HIGH or CRITICAL finding and has to quote the code before it posts. Unproven findings drop.
|
|
346
|
-
- **Labelled comments.** Everything swarm posts starts with `🤖 Automated comment by **Shepherd swarm**`. It posts through your account, and readers deserve to know.
|
|
347
|
-
- **People talk to people.** Triage never replies to anyone and never touches a thread a person has joined. Those wait for you.
|
|
348
|
-
- **PR content is data.** Diffs, comments and CI logs never become instructions. Writing a command in a comment gets nobody a command run.
|
|
349
|
-
- **Gates stay gates.** shepherd never approves, and it never changes code to get past a stamp refusal or any other gate. A fix that changes what code accepts or returns is your decision.
|
|
350
|
-
|
|
351
|
-
## Gardening
|
|
352
|
-
|
|
353
|
-
```mermaid
|
|
354
|
-
flowchart LR
|
|
355
|
-
G[shepherd garden owner/repo] --> SC[Score recent runs<br/>from GitHub]
|
|
356
|
-
SC --> SK[garden skill]
|
|
357
|
-
SK --> E1[Skill edits for<br/>low-scoring patterns]
|
|
358
|
-
SK --> E2[Lint rules for<br/>recurring findings]
|
|
359
|
-
E1 & E2 --> PR[Garden PRs with<br/>the score table]
|
|
360
|
-
PR --> NX[Next run shows<br/>whether the edit helped]
|
|
361
|
-
NX --> SC
|
|
362
|
-
```
|
|
363
|
-
|
|
364
|
-
`shepherd garden <owner/repo>...` scores what shepherd did on recent PRs, from GitHub alone. It counts reverted fixes, people replying in a thread, and loops that hit the round cap, stopped short or went quiet. It also finds the lens rules triage fixed on 3+ PRs, from its `Shepherd-Fixes` trailers on PRs by people who can push.
|
|
365
|
-
|
|
366
|
-
The `garden` skill turns that into PRs: skill edits for the patterns behind low scores, and lint rules for recurring findings one file's syntax can decide, so swarm's checks catch them before any model reads the diff.
|
|
367
|
-
|
|
368
|
-
`.github/workflows/garden.yml` runs it weekly. Set `GARDEN_REPOS`, a `GARDEN_TOKEN` that can open PRs on those repos, and a model key. The agent only proposes, and a separate job opens the PRs. Each garden PR carries the score table, so the next one shows whether a merged edit helped.
|
|
369
|
-
|
|
370
|
-
## Where the loop got to
|
|
371
|
-
|
|
372
|
-
Every iteration sets a `shepherd` commit status on the head.
|
|
373
|
-
|
|
374
|
-
```mermaid
|
|
375
|
-
stateDiagram-v2
|
|
376
|
-
[*] --> pending: iteration starts
|
|
377
|
-
pending --> pending: work left, or waiting on a verdict
|
|
378
|
-
pending --> failure: only you can move it
|
|
379
|
-
pending --> success: stamp approved, nothing open
|
|
380
|
-
failure --> pending: you act, next iteration
|
|
381
|
-
success --> pending: new push
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
- `pending` while there is work or a verdict to wait for.
|
|
385
|
-
- `failure` names what you need to do when only you can move it (`stamp refused: ...`, `3 threads need you`).
|
|
386
|
-
- `success` only when stamp approved and nothing is left open.
|
|
387
|
-
|
|
388
|
-
Require the status in a branch rule, and a PR cannot merge while shepherd is mid-loop, stopped short, or behind a push it has not seen.
|
|
389
|
-
|
|
390
|
-
## After merge
|
|
391
|
-
|
|
392
|
-
shepherd needs no spec. A failure after merge is the requirement, and the test that reproduces it is the acceptance check. `/incident` takes a red run on the default branch, an error or stack trace, an alert payload, or an issue labelled `incident`, and:
|
|
393
|
-
|
|
394
|
-
```mermaid
|
|
395
|
-
flowchart LR
|
|
396
|
-
S[Signal: red main,<br/>production error] --> I[incident issue<br/>with evidence]
|
|
397
|
-
I --> T[Reproducing test]
|
|
398
|
-
T --> B[Bisect with the test:<br/>which PR caused it,<br/>did stamp approve it]
|
|
399
|
-
T --> F[Fix PR<br/>Fixes #issue]
|
|
400
|
-
F --> SH[shepherd loop]
|
|
401
|
-
SH --> ST[stamp: incident flag,<br/>needs the reproducing test]
|
|
402
|
-
ST --> M[You merge]
|
|
403
|
-
B --> G[garden tunes<br/>lenses and policy]
|
|
404
|
-
```
|
|
405
|
-
|
|
406
|
-
It dedupes on a fingerprint of the error, never pushes to the default branch, and stops without a fix when it cannot reproduce the failure. stamp refuses an incident fix that has no reproducing test or that hides the symptom.
|
|
407
|
-
|
|
408
|
-
To run it when the default branch goes red, add a workflow on `workflow_run` of your CI with `conclusion == 'failure'` and `head_branch` set to the default branch, and run one `/incident <run url>` the same way the `shepherd` workflow runs an iteration. An alerting tool can call the same workflow through `repository_dispatch` with the error in the payload.
|
|
409
|
-
|
|
410
|
-
## With stamp
|
|
411
|
-
|
|
412
|
-
```mermaid
|
|
413
|
-
sequenceDiagram
|
|
414
|
-
participant SH as shepherd
|
|
415
|
-
participant GH as GitHub
|
|
416
|
-
participant ST as stamp (CI)
|
|
417
|
-
participant You
|
|
418
|
-
SH->>GH: push fixes, apply label in label mode
|
|
419
|
-
GH->>ST: workflow runs on the head
|
|
420
|
-
ST->>GH: verdict review
|
|
421
|
-
SH->>GH: read the verdict
|
|
422
|
-
alt APPROVED
|
|
423
|
-
SH->>GH: status success
|
|
424
|
-
else REFUSED
|
|
425
|
-
SH->>SH: triage the refusal's issues
|
|
426
|
-
else ESCALATE
|
|
427
|
-
SH->>You: leave it for you
|
|
428
|
-
end
|
|
429
|
-
```
|
|
35
|
+
## Choose what the agent may change
|
|
430
36
|
|
|
431
|
-
|
|
37
|
+
| Mode | Result |
|
|
38
|
+
| --- | --- |
|
|
39
|
+
| `suggest` | Findings posted; no code edits |
|
|
40
|
+
| `local` | Fixes left in your working tree; you commit and push |
|
|
41
|
+
| `push` | Fixes committed and pushed under the skill rules |
|
|
432
42
|
|
|
433
|
-
|
|
43
|
+
`/shepherd --local` provides a pre-PR review-and-fix path with no GitHub writes. A completed review does not establish merge readiness. The PR loop reports ready only when Stamp approves the current head, CI passes and no review thread remains open.
|
|
434
44
|
|
|
435
|
-
##
|
|
45
|
+
## Configure it for your team
|
|
436
46
|
|
|
437
|
-
|
|
47
|
+
| Task | Guide |
|
|
48
|
+
| --- | --- |
|
|
49
|
+
| Review before opening a PR | [Local review](docs/src/content/docs/guides/local-review.md) |
|
|
50
|
+
| Compose checks, modes and recipes | [Configuration reference](docs/src/content/docs/reference/configuration.md) |
|
|
51
|
+
| Share organisation policy | [Team examples](docs/src/content/docs/configuration/examples.md) |
|
|
52
|
+
| Add domain-specific reviewers | [Lenses](docs/src/content/docs/configuration/lenses.md) |
|
|
53
|
+
| Review React, Next.js, Node, Go, Rust, Java, .NET or Python code, or import any skill as a lens | [Stack packs](docs/src/content/docs/configuration/stacks.md) |
|
|
54
|
+
| Select models by role | [Model routing](docs/src/content/docs/configuration/models.md) |
|
|
55
|
+
| Run without your laptop | [GitHub Actions](docs/src/content/docs/integrations/github-actions.md) |
|
|
56
|
+
| Get told when a PR needs you | [Notifications](docs/src/content/docs/integrations/notifications.md) |
|
|
57
|
+
| Investigate a failure after merge | [Incidents](docs/src/content/docs/guides/incidents.md) |
|
|
58
|
+
| Improve recurring findings | [Gardening](docs/src/content/docs/operations/gardening.md) |
|
|
59
|
+
| Diagnose a stopped loop | [Troubleshooting](docs/src/content/docs/operations/troubleshooting.md) |
|
|
438
60
|
|
|
439
61
|
## Development
|
|
440
62
|
|
|
441
63
|
```bash
|
|
442
64
|
bun install
|
|
443
|
-
bun run check
|
|
65
|
+
bun run check
|
|
444
66
|
```
|
|
445
67
|
|
|
446
|
-
|
|
68
|
+
For the docs site, run `bun install --cwd docs --frozen-lockfile`, then `bun run docs:dev`. Run `bun run docs:build` to validate and build it. Read [documentation maintenance](docs/src/content/docs/contributing/docs.md), [contributor rules](AGENTS.md) and [third-party credits](THIRD_PARTY_NOTICES.md).
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -39,3 +39,14 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
|
39
39
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
40
40
|
SOFTWARE.
|
|
41
41
|
```
|
|
42
|
+
|
|
43
|
+
## OWASP Secure Agent Playbook
|
|
44
|
+
|
|
45
|
+
These lenses adapt material from the [OWASP Secure Agent Playbook](https://github.com/OWASP/secure-agent-playbook) at commit `65d4efd2cd0b081d52101e9708792b944e4ddebb`. Each rule condenses the source's requirements into one review line, cut to what a diff can show:
|
|
46
|
+
|
|
47
|
+
| Here | Adapted from |
|
|
48
|
+
| --- | --- |
|
|
49
|
+
| `lenses/owasp-asvs/` | `plugins/code-security-skills/skills/security-guidance/` and `plugins/code-security-skills/data/asvs/` (OWASP ASVS 5.0) |
|
|
50
|
+
| `lenses/owasp-llm/` | `plugins/ai-security-skills/` plays and skills for the OWASP LLM Top 10 2025, the Agentic Top 10 2026 and MCP server review |
|
|
51
|
+
|
|
52
|
+
The source is licensed under the [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/) (CC-BY-4.0). The adapted lenses carry the same licence and name their source commit in their frontmatter.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dotnet
|
|
3
|
+
description: C# and ASP.NET Core rules for a code review. Flags code that deadlocks, leaks, trusts input or loses data in ways the compiler and Roslyn analysers miss. Covers sync-over-async and async void, cancellation tokens not passed, missing authorization on endpoints, unvalidated input and over-posting, raw SQL and commands built from input, unsafe deserialisation, EF Core N+1 and tracking pitfalls, DI lifetime mismatches, HttpClient misuse, disposables not disposed, swallowed exceptions, and API and entity contract changes. Use as a review lens or as a stamp rule pack.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# dotnet
|
|
7
|
+
|
|
8
|
+
ASP.NET Core runs every request on a shared thread pool with services wired
|
|
9
|
+
by lifetime. Review whether this change stays async end to end, carries
|
|
10
|
+
cancellation, gives each service a lifetime that matches its dependencies, and
|
|
11
|
+
checks who is calling before it touches data.
|
|
12
|
+
|
|
13
|
+
## Review
|
|
14
|
+
|
|
15
|
+
- **sync-over-async**: Async code is awaited all the way up. Flag: `.Result`, `.Wait()` or `.GetAwaiter().GetResult()` on a task in request code, `async void` outside event handlers, a fire-and-forget `Task` with no error handling, `Task.Run` wrapping I/O in a request. Why: thread-pool starvation and deadlocks under load, and exceptions that crash the process.
|
|
16
|
+
- **cancellation**: Endpoints and async methods accept a `CancellationToken` and pass it to I/O (EF Core, `HttpClient`, streams). Flag: a new async method that does I/O with no token, a token accepted and not passed on, `CancellationToken.None` in a request path. Why: abandoned requests keep querying and holding connections.
|
|
17
|
+
- **endpoint-authz** [refuse]: Every new controller action or minimal API endpoint is covered by authorization and checks the caller may act on the resource. Flag: `[AllowAnonymous]` added, a new endpoint group without `RequireAuthorization` where the app has no fallback policy, a handler loading a record by id with no ownership or policy check. Why: the endpoint is public or exposes other users' data.
|
|
18
|
+
- **validate-input**: Request models are validated (data annotations, FluentValidation, or explicit checks) and bound to DTOs, never to EF entities. Flag: an entity used as a request body, missing `ModelState`/validation in a non-`[ApiController]` controller, an over-posted field like `IsAdmin` or `TenantId`. Why: callers set fields the code never meant to expose.
|
|
19
|
+
- **injection** [refuse]: SQL takes input through parameters, commands through `ProcessStartInfo.ArgumentList`, file paths through a containment check. Flag: `FromSqlRaw` or `ExecuteSqlRaw` with interpolated input (use `FromSql`/`FromSqlInterpolated`), string-built `SqlCommand` text, `Path.Combine(root, userInput)` without checking the full path stays under root. Why: injection and path traversal.
|
|
20
|
+
- **unsafe-deserialization** [refuse]: Untrusted data never reaches `BinaryFormatter`, `NetDataContractSerializer`, or polymorphic type handling that names types from the payload. Flag: `TypeNameHandling` other than `None` in Newtonsoft settings for untrusted input, `BinaryFormatter` anywhere, `XmlDocument` with a resolver on untrusted XML. Why: remote code execution.
|
|
21
|
+
- **ef-query-shape**: EF Core queries fetch what the code uses, in a bounded number of round trips. Flag: navigation properties read in a loop (N+1 through lazy loading), `ToList()` before `Where`, a list endpoint with no paging, tracked queries on read-only paths that load many rows, `Include` chains that explode rows. Why: queries multiply and memory grows with the table.
|
|
22
|
+
- **di-lifetime**: Service lifetimes match their dependencies. Flag: a singleton taking a scoped service (DbContext, a per-request service) in its constructor, a `DbContext` held in a static or singleton, a scoped service resolved from the root provider in a background service without `CreateScope`. Why: captive dependencies share a DbContext across threads and corrupt state.
|
|
23
|
+
- **httpclient-use**: Outbound HTTP goes through `IHttpClientFactory` or a long-lived `HttpClient`, with a timeout and resilience policy where the repository uses one. Flag: `new HttpClient()` per call, a client with no timeout calling a slow dependency, retries added on non-idempotent POSTs. Why: socket exhaustion and stale DNS, or duplicated writes.
|
|
24
|
+
- **dispose**: `IDisposable` and `IAsyncDisposable` objects created by the code are disposed with `using`/`await using`. Flag: a stream, `SqlConnection`, `CancellationTokenSource` or timer created and never disposed, a DI-owned service disposed manually. Why: handle and connection leaks under load.
|
|
25
|
+
- **exception-handling**: Exceptions are handled once with their context. Flag: an empty `catch`, `catch (Exception) { return null; }`, `throw ex;` that resets the stack (use `throw;`), logging `ex.Message` without the exception. Why: the cause of the failure is lost.
|
|
26
|
+
- **contract-change**: Changes to entities, DTOs serialised to clients and public types are deliberate and paired with a migration. Flag: a renamed or removed entity property with no EF migration, a changed JSON property name, a public method signature change in a shared library, a new non-nullable column with no default. Why: data or clients break at deploy.
|
|
27
|
+
|
|
28
|
+
## Fix
|
|
29
|
+
|
|
30
|
+
- Prefer: `async`/`await` end to end with `CancellationToken`, DTO records with validation, `IHttpClientFactory`, `AsNoTracking()` for reads, projections with `Select`, and the repository's existing authorization policies.
|
|
31
|
+
- Never touch: `Program.cs` middleware order and authentication setup beyond the endpoint in the PR, `.csproj` package versions, and existing EF migrations.
|
|
32
|
+
- Escalate: `endpoint-authz` and `contract-change` breaks, new EF migrations, and changes to service lifetimes in shared registration code.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: go
|
|
3
|
+
description: Go rules for a code review. Flags code that leaks goroutines, races, loses errors or hangs in production in ways go vet and staticcheck do not catch. Covers context not passed or ignored, goroutines with no way to stop, unsynchronised shared state, errors dropped or wrapped without %w, resources not closed, HTTP servers and clients with no timeouts, SQL and commands built from input, panics in library code, nil maps and interfaces holding typed nils, unbounded concurrency, and exported API changes. Use as a review lens or as a stamp rule pack.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# go
|
|
7
|
+
|
|
8
|
+
Go makes concurrency cheap and failure explicit, which makes both easy to get
|
|
9
|
+
quietly wrong. Review whether this change lets every goroutine finish,
|
|
10
|
+
carries cancellation through, keeps every error, and releases what it opens.
|
|
11
|
+
|
|
12
|
+
## Review
|
|
13
|
+
|
|
14
|
+
- **context-flow**: A function that does I/O or may block takes `ctx context.Context` first and passes it down, and long loops check `ctx.Done()`. Flag: `context.Background()` or `TODO()` inside a request path, a ctx accepted but not passed to the database or HTTP call, a `select` on a channel with no `ctx.Done()` case. Why: cancelled requests keep running and hold connections after the client left.
|
|
15
|
+
- **goroutine-lifetime**: Every goroutine has a way to stop and an owner that waits for it (`errgroup`, `WaitGroup`, a done channel). Flag: `go func()` in a handler with no cancellation, a goroutine blocked forever sending on an unbuffered channel nobody reads, a ticker never stopped. Why: goroutine leaks grow until the process runs out of memory.
|
|
16
|
+
- **data-race**: State shared between goroutines is guarded by a mutex, an atomic, or owned by one goroutine behind a channel. Flag: a map written from more than one goroutine, a struct field updated in a goroutine and read in the caller, a loop variable captured in Go before 1.22 semantics, a `sync.Mutex` copied by value. Why: races corrupt data and crash with `concurrent map writes`, intermittently.
|
|
17
|
+
- **error-handling**: Errors are checked, and wrapped with `%w` and context when returned. Flag: `_ =` or an ignored error from a write, close or commit; `fmt.Errorf("...: %v", err)` where callers use `errors.Is`/`As`; comparing `err.Error()` strings; logging an error and also returning it. Why: failures disappear, or callers can no longer tell which error happened.
|
|
18
|
+
- **resource-close**: Opened files, response bodies, rows, statements and transactions are closed or rolled back on every path, close errors on writes are checked. Flag: `resp.Body` not closed, `rows` not closed or `rows.Err()` unchecked, a transaction with no deferred rollback, `defer f.Close()` on a file written to with the error ignored. Why: connection pools exhaust and writes are lost silently.
|
|
19
|
+
- **http-timeouts**: `http.Server` sets `ReadHeaderTimeout` (and usually read, write and idle timeouts), and `http.Client` has a `Timeout` or per-request context deadline. Flag: `http.ListenAndServe` with the default server, `http.DefaultClient` or `&http.Client{}` for outbound calls. Why: slowloris holds the server, and a hung dependency holds every goroutine.
|
|
20
|
+
- **injection** [refuse]: SQL takes input through placeholders, commands through `exec.Command` argument lists, file paths through a containment check. Flag: `fmt.Sprintf` into a query, `exec.Command("sh", "-c", input)`, `filepath.Join(root, userPath)` with no check that the result stays under root, `template.HTML` from user input. Why: injection and path traversal.
|
|
21
|
+
- **no-library-panic**: Library and request code returns errors instead of panicking, and recovers at goroutine boundaries the program starts. Flag: `panic` on bad input, `log.Fatal` or `os.Exit` outside `main`, a goroutine with no recover in a server where one panic kills the process. Why: one bad request takes the whole service down.
|
|
22
|
+
- **nil-traps**: Writes go to initialised maps, and functions returning an interface return a literal `nil` on success. Flag: writing to a nil map field, `var err *MyErr; return err` as an `error`, dereferencing an optional pointer field without a check. Why: panics in production, and `err != nil` true for a nil pointer.
|
|
23
|
+
- **bounded-concurrency**: Fan-out over input is bounded (`errgroup.SetLimit`, a semaphore, a worker pool). Flag: `for _, x := range items { go work(x) }` over request or database-sized input, an unbounded buffered channel used as a queue. Why: a large input spawns thousands of goroutines and connections at once.
|
|
24
|
+
- **exported-contract**: Changes to exported identifiers, struct fields marshalled to JSON, and error values callers match are deliberate. Flag: a renamed or removed exported function or field, a changed `json:` tag, a sentinel error replaced by a new one, a new required argument on a widely used function. Why: downstream packages and stored data break at the next build or deploy.
|
|
25
|
+
|
|
26
|
+
## Fix
|
|
27
|
+
|
|
28
|
+
- Prefer: `errgroup` with a context, `fmt.Errorf("doing x: %w", err)`, `defer` close and rollback right after the open succeeds, and the repository's existing HTTP client and database helpers.
|
|
29
|
+
- Never touch: `go.mod` versions, generated code (`*.pb.go`, `*_gen.go`), and vendored packages.
|
|
30
|
+
- Escalate: `exported-contract` breaks, changes to server timeouts or pool sizes, and any switch of concurrency model across a package.
|