@jagreehal/shepherd 0.15.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/AGENTS.md +3 -3
  2. package/README.md +40 -27
  3. package/THIRD_PARTY_NOTICES.md +2 -0
  4. package/gate/.shepherd/gate.schema.json +657 -0
  5. package/gate/.shepherd/gate.yml +123 -0
  6. package/gate/.shepherd/review-guidance.md +95 -0
  7. package/gate/src/actions.ts +32 -0
  8. package/gate/src/cli.ts +1046 -0
  9. package/gate/src/config.ts +102 -0
  10. package/gate/src/delta.ts +29 -0
  11. package/gate/src/env.ts +30 -0
  12. package/gate/src/eval.ts +292 -0
  13. package/gate/src/familiarity.ts +461 -0
  14. package/gate/src/github.ts +761 -0
  15. package/gate/src/inline.ts +59 -0
  16. package/gate/src/isolated-cli.ts +281 -0
  17. package/gate/src/leads.ts +257 -0
  18. package/gate/src/llm.ts +647 -0
  19. package/gate/src/notify.ts +57 -0
  20. package/gate/src/policy.ts +1313 -0
  21. package/gate/src/prices.ts +62 -0
  22. package/gate/src/provider-errors.ts +80 -0
  23. package/gate/src/retention.ts +86 -0
  24. package/gate/src/reviewer.ts +739 -0
  25. package/gate/src/signals.ts +105 -0
  26. package/gate/src/smoke-live.ts +64 -0
  27. package/gate/src/stack.ts +87 -0
  28. package/gate/src/stories.ts +297 -0
  29. package/gate/templates/policy-strict.yml +128 -0
  30. package/gate/templates/reviewer.Dockerfile +8 -0
  31. package/gate/templates/rules/observability/SKILL.md +33 -0
  32. package/gate/templates/shepherd-gate-actions.yml +35 -0
  33. package/gate/templates/shepherd-gate-edited.yml +29 -0
  34. package/gate/templates/shepherd-gate.yml +111 -0
  35. package/lenses/dotnet/SKILL.md +1 -1
  36. package/lenses/go/SKILL.md +1 -1
  37. package/lenses/java/SKILL.md +1 -1
  38. package/lenses/nextjs/SKILL.md +1 -1
  39. package/lenses/node-api/SKILL.md +1 -1
  40. package/lenses/nx-monorepo/SKILL.md +1 -1
  41. package/lenses/observability/SKILL.md +1 -1
  42. package/lenses/owasp-asvs/SKILL.md +1 -1
  43. package/lenses/owasp-llm/SKILL.md +1 -1
  44. package/lenses/pstack/SKILL.md +1 -1
  45. package/lenses/python/SKILL.md +1 -1
  46. package/lenses/react/SKILL.md +1 -1
  47. package/lenses/rust/SKILL.md +1 -1
  48. package/package.json +21 -7
  49. package/schema/config.json +1 -1
  50. package/skills/branch-review/SKILL.md +123 -0
  51. package/skills/ci-repair/SKILL.md +79 -35
  52. package/skills/garden/SKILL.md +8 -8
  53. package/skills/garden/references/telemetry.md +4 -4
  54. package/skills/incident/SKILL.md +9 -9
  55. package/skills/lens-import/SKILL.md +7 -7
  56. package/skills/review-slop/SKILL.md +1 -1
  57. package/skills/shepherd/SKILL.md +43 -41
  58. package/skills/shepherd/references/degradation.md +3 -3
  59. package/skills/shepherd/references/dispatch.md +1 -1
  60. package/skills/shepherd/references/formats.md +5 -5
  61. package/skills/shepherd/references/models.md +2 -2
  62. package/skills/shepherd/references/policy.md +9 -9
  63. package/skills/swarm/SKILL.md +21 -17
  64. package/skills/swarm/references/custom-lenses.md +2 -2
  65. package/skills/swarm/references/formats.md +1 -1
  66. package/skills/triage/SKILL.md +10 -10
  67. package/src/bin.ts +10 -0
  68. package/src/cli.ts +285 -42
  69. package/src/config.ts +26 -25
  70. package/src/doctor.ts +31 -18
  71. package/src/garden-traces.ts +13 -13
  72. package/src/garden.ts +4 -4
  73. package/src/lens.ts +19 -7
  74. package/src/setup.ts +72 -0
  75. package/src/stack.ts +2 -2
  76. package/src/status.ts +80 -0
  77. package/src/summary.ts +52 -9
  78. package/src/trace.ts +4 -4
  79. package/src/working.ts +30 -0
  80. package/templates/shepherd-audit.yml +7 -15
  81. package/templates/shepherd-incident.yml +7 -12
  82. package/templates/shepherd.yml +39 -40
@@ -0,0 +1,657 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "type": "object",
4
+ "properties": {
5
+ "version": {
6
+ "type": "number",
7
+ "const": 1
8
+ },
9
+ "deny": {
10
+ "type": "object",
11
+ "properties": {
12
+ "gate_policy": {
13
+ "type": "object",
14
+ "properties": {
15
+ "description": {
16
+ "type": "string"
17
+ },
18
+ "match": {
19
+ "type": "object",
20
+ "properties": {
21
+ "any": {
22
+ "default": [],
23
+ "type": "array",
24
+ "items": {
25
+ "type": "string"
26
+ }
27
+ },
28
+ "titles": {
29
+ "default": [],
30
+ "type": "array",
31
+ "items": {
32
+ "type": "string"
33
+ }
34
+ },
35
+ "paths": {
36
+ "default": [],
37
+ "type": "array",
38
+ "items": {
39
+ "type": "string"
40
+ }
41
+ }
42
+ }
43
+ }
44
+ },
45
+ "required": [
46
+ "match"
47
+ ]
48
+ }
49
+ },
50
+ "required": [
51
+ "gate_policy"
52
+ ],
53
+ "additionalProperties": {
54
+ "type": "object",
55
+ "properties": {
56
+ "description": {
57
+ "type": "string"
58
+ },
59
+ "match": {
60
+ "type": "object",
61
+ "properties": {
62
+ "any": {
63
+ "default": [],
64
+ "type": "array",
65
+ "items": {
66
+ "type": "string"
67
+ }
68
+ },
69
+ "titles": {
70
+ "default": [],
71
+ "type": "array",
72
+ "items": {
73
+ "type": "string"
74
+ }
75
+ },
76
+ "paths": {
77
+ "default": [],
78
+ "type": "array",
79
+ "items": {
80
+ "type": "string"
81
+ }
82
+ }
83
+ }
84
+ }
85
+ },
86
+ "required": [
87
+ "match"
88
+ ]
89
+ },
90
+ "description": "Categories a PR may not touch: a match sends it to a human. deny.gate_policy is required."
91
+ },
92
+ "allow": {
93
+ "type": "object",
94
+ "properties": {
95
+ "path_patterns": {
96
+ "type": "array",
97
+ "items": {
98
+ "type": "string"
99
+ }
100
+ },
101
+ "extensions_only": {
102
+ "type": "array",
103
+ "items": {
104
+ "type": "string"
105
+ }
106
+ }
107
+ },
108
+ "required": [
109
+ "path_patterns",
110
+ "extensions_only"
111
+ ],
112
+ "description": "Paths and extensions that count as low-risk."
113
+ },
114
+ "size_gate": {
115
+ "type": "object",
116
+ "properties": {
117
+ "max_lines": {
118
+ "type": "integer",
119
+ "exclusiveMinimum": 0,
120
+ "maximum": 9007199254740991
121
+ },
122
+ "max_files": {
123
+ "type": "integer",
124
+ "exclusiveMinimum": 0,
125
+ "maximum": 9007199254740991
126
+ }
127
+ },
128
+ "required": [
129
+ "max_lines",
130
+ "max_files"
131
+ ],
132
+ "description": "The largest change gate reviews; anything bigger goes to a human."
133
+ },
134
+ "tiers": {
135
+ "type": "object",
136
+ "propertyNames": {
137
+ "type": "string"
138
+ },
139
+ "additionalProperties": {
140
+ "type": "object",
141
+ "properties": {
142
+ "max_lines": {
143
+ "type": "integer",
144
+ "minimum": -9007199254740991,
145
+ "maximum": 9007199254740991
146
+ },
147
+ "max_files": {
148
+ "type": "integer",
149
+ "minimum": -9007199254740991,
150
+ "maximum": 9007199254740991
151
+ }
152
+ },
153
+ "required": [
154
+ "max_lines",
155
+ "max_files"
156
+ ]
157
+ }
158
+ },
159
+ "overrides": {
160
+ "description": "Contract ceilings for AGENT_APPROVALS.md grants. Absent = no folder delegation.",
161
+ "type": "object",
162
+ "properties": {
163
+ "size_gate.max_lines": {
164
+ "type": "object",
165
+ "properties": {
166
+ "ceiling": {
167
+ "type": "integer",
168
+ "exclusiveMinimum": 0,
169
+ "maximum": 9007199254740991
170
+ }
171
+ },
172
+ "required": [
173
+ "ceiling"
174
+ ]
175
+ },
176
+ "size_gate.max_files": {
177
+ "type": "object",
178
+ "properties": {
179
+ "ceiling": {
180
+ "type": "integer",
181
+ "exclusiveMinimum": 0,
182
+ "maximum": 9007199254740991
183
+ }
184
+ },
185
+ "required": [
186
+ "ceiling"
187
+ ]
188
+ }
189
+ },
190
+ "required": [
191
+ "size_gate.max_lines",
192
+ "size_gate.max_files"
193
+ ],
194
+ "additionalProperties": false
195
+ },
196
+ "familiarity": {
197
+ "description": "Judgment-layer only; never a gate. Absent = no familiarity signal computed.",
198
+ "type": "object",
199
+ "properties": {
200
+ "strong": {
201
+ "type": "object",
202
+ "properties": {
203
+ "min_blame_overlap_pct": {
204
+ "type": "number",
205
+ "minimum": 0,
206
+ "maximum": 100
207
+ }
208
+ },
209
+ "required": [
210
+ "min_blame_overlap_pct"
211
+ ]
212
+ },
213
+ "moderate": {
214
+ "type": "object",
215
+ "properties": {
216
+ "min_prior_prs": {
217
+ "type": "integer",
218
+ "exclusiveMinimum": 0,
219
+ "maximum": 9007199254740991
220
+ },
221
+ "max_days_since_touch": {
222
+ "type": "integer",
223
+ "exclusiveMinimum": 0,
224
+ "maximum": 9007199254740991
225
+ }
226
+ },
227
+ "required": [
228
+ "min_prior_prs",
229
+ "max_days_since_touch"
230
+ ]
231
+ }
232
+ },
233
+ "required": [
234
+ "strong",
235
+ "moderate"
236
+ ],
237
+ "additionalProperties": false
238
+ },
239
+ "stories": {
240
+ "description": "Judgment-layer, never a gate; a scenario the report measures checking less than the base branch holds an approval for a person. Absent = no test evidence read from CI.",
241
+ "type": "object",
242
+ "properties": {
243
+ "workflow": {
244
+ "type": "string",
245
+ "minLength": 1
246
+ },
247
+ "artifact": {
248
+ "type": "string",
249
+ "minLength": 1
250
+ },
251
+ "file": {
252
+ "default": "index.review.json",
253
+ "type": "string"
254
+ },
255
+ "max_bytes": {
256
+ "default": 1000000,
257
+ "type": "integer",
258
+ "exclusiveMinimum": 0,
259
+ "maximum": 10000000
260
+ }
261
+ },
262
+ "required": [
263
+ "workflow",
264
+ "artifact"
265
+ ],
266
+ "additionalProperties": false
267
+ },
268
+ "scrutiny": {
269
+ "default": {},
270
+ "description": "Paths the reviewer looks at harder, with what to check. Never changes a gate.",
271
+ "type": "object",
272
+ "propertyNames": {
273
+ "type": "string"
274
+ },
275
+ "additionalProperties": {
276
+ "type": "object",
277
+ "properties": {
278
+ "description": {
279
+ "type": "string"
280
+ },
281
+ "paths": {
282
+ "type": "array",
283
+ "items": {
284
+ "type": "string"
285
+ }
286
+ },
287
+ "instruction": {
288
+ "type": "string"
289
+ }
290
+ },
291
+ "required": [
292
+ "paths",
293
+ "instruction"
294
+ ]
295
+ }
296
+ },
297
+ "reviewer_bots": {
298
+ "default": [],
299
+ "description": "Review bots whose fresh 👀 reaction gate briefly waits on.",
300
+ "type": "array",
301
+ "items": {
302
+ "type": "string"
303
+ }
304
+ },
305
+ "long_lived_branches": {
306
+ "default": [
307
+ "main",
308
+ "master",
309
+ "develop",
310
+ "release",
311
+ "release/*",
312
+ "staging"
313
+ ],
314
+ "description": "Long-lived branches (globs): a PR whose commits mostly sit on one of these, other than its base, was opened against the wrong base.",
315
+ "type": "array",
316
+ "items": {
317
+ "type": "string",
318
+ "minLength": 1
319
+ }
320
+ },
321
+ "reviewer_checks": {
322
+ "default": [],
323
+ "description": "Review services that report progress as a check run on the head, such as Claude Code Review.",
324
+ "type": "array",
325
+ "items": {
326
+ "type": "string"
327
+ }
328
+ },
329
+ "rules": {
330
+ "default": {},
331
+ "description": "Team rule packs: SKILL.md files whose \"## Review\" rules the reviewer applies to matching files.",
332
+ "type": "object",
333
+ "propertyNames": {
334
+ "type": "string",
335
+ "pattern": "^[a-z][a-z0-9-]*$"
336
+ },
337
+ "additionalProperties": {
338
+ "type": "object",
339
+ "properties": {
340
+ "skill": {
341
+ "type": "string"
342
+ },
343
+ "applies_to": {
344
+ "type": "array",
345
+ "items": {
346
+ "type": "string"
347
+ }
348
+ },
349
+ "on_break": {
350
+ "default": "escalate",
351
+ "type": "string",
352
+ "enum": [
353
+ "refuse",
354
+ "escalate",
355
+ "note"
356
+ ]
357
+ },
358
+ "only": {
359
+ "minItems": 1,
360
+ "type": "array",
361
+ "items": {
362
+ "type": "string",
363
+ "minLength": 1
364
+ }
365
+ },
366
+ "disable": {
367
+ "minItems": 1,
368
+ "type": "array",
369
+ "items": {
370
+ "type": "string",
371
+ "minLength": 1
372
+ }
373
+ }
374
+ },
375
+ "required": [
376
+ "skill"
377
+ ],
378
+ "additionalProperties": false
379
+ }
380
+ },
381
+ "rules_from": {
382
+ "description": "Rule packs declared once, in another tool's config: shepherd's lenses become rule packs here.",
383
+ "type": "object",
384
+ "properties": {
385
+ "shepherd": {
386
+ "type": "object",
387
+ "properties": {
388
+ "on_break": {
389
+ "default": "escalate",
390
+ "type": "string",
391
+ "enum": [
392
+ "refuse",
393
+ "escalate",
394
+ "note"
395
+ ]
396
+ }
397
+ },
398
+ "additionalProperties": false
399
+ }
400
+ },
401
+ "required": [
402
+ "shepherd"
403
+ ],
404
+ "additionalProperties": false
405
+ },
406
+ "branding": {
407
+ "description": "How posted reviews look: the header name, a small avatar, and any glyph. Absent = today's output, byte for byte.",
408
+ "type": "object",
409
+ "properties": {
410
+ "name": {
411
+ "type": "string",
412
+ "minLength": 1,
413
+ "maxLength": 40
414
+ },
415
+ "avatar": {
416
+ "type": "string",
417
+ "maxLength": 500,
418
+ "format": "uri"
419
+ },
420
+ "emoji": {
421
+ "type": "object",
422
+ "properties": {
423
+ "APPROVED": {
424
+ "type": "string",
425
+ "minLength": 1,
426
+ "maxLength": 16,
427
+ "pattern": "^\\S+$"
428
+ },
429
+ "REFUSED": {
430
+ "type": "string",
431
+ "minLength": 1,
432
+ "maxLength": 16,
433
+ "pattern": "^\\S+$"
434
+ },
435
+ "ESCALATE": {
436
+ "type": "string",
437
+ "minLength": 1,
438
+ "maxLength": 16,
439
+ "pattern": "^\\S+$"
440
+ },
441
+ "ERROR": {
442
+ "type": "string",
443
+ "minLength": 1,
444
+ "maxLength": 16,
445
+ "pattern": "^\\S+$"
446
+ },
447
+ "pass": {
448
+ "type": "string",
449
+ "minLength": 1,
450
+ "maxLength": 16,
451
+ "pattern": "^\\S+$"
452
+ },
453
+ "fail": {
454
+ "type": "string",
455
+ "minLength": 1,
456
+ "maxLength": 16,
457
+ "pattern": "^\\S+$"
458
+ },
459
+ "fix": {
460
+ "type": "string",
461
+ "minLength": 1,
462
+ "maxLength": 16,
463
+ "pattern": "^\\S+$"
464
+ }
465
+ },
466
+ "additionalProperties": false
467
+ }
468
+ },
469
+ "additionalProperties": false
470
+ },
471
+ "model": {
472
+ "description": "The reviewer model, provider/model. Overridden by SHEPHERD_MODEL.",
473
+ "type": "string",
474
+ "minLength": 1
475
+ },
476
+ "backends": {
477
+ "description": "Primary backend, then a second opinion.",
478
+ "minItems": 1,
479
+ "type": "array",
480
+ "items": {
481
+ "type": "string",
482
+ "minLength": 1
483
+ }
484
+ },
485
+ "pricing": {
486
+ "description": "Prices per million tokens for each model you use. Shepherd ships no prices: without one, the $ budget is inactive and costs show as unpriced.",
487
+ "type": "object",
488
+ "propertyNames": {
489
+ "type": "string"
490
+ },
491
+ "additionalProperties": {
492
+ "type": "object",
493
+ "properties": {
494
+ "inputPer1M": {
495
+ "type": "number"
496
+ },
497
+ "outputPer1M": {
498
+ "type": "number"
499
+ },
500
+ "cachedInputPer1M": {
501
+ "type": "number"
502
+ },
503
+ "as_of": {
504
+ "description": "The date you read these prices (YYYY-MM-DD), so a stale price is visible.",
505
+ "type": "string",
506
+ "format": "date",
507
+ "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
508
+ },
509
+ "source": {
510
+ "description": "Where the prices came from: a price page, a contract, a region.",
511
+ "type": "string"
512
+ }
513
+ },
514
+ "required": [
515
+ "inputPer1M",
516
+ "outputPer1M"
517
+ ],
518
+ "additionalProperties": false
519
+ }
520
+ },
521
+ "provider": {
522
+ "type": "object",
523
+ "properties": {
524
+ "region": {
525
+ "type": "string",
526
+ "pattern": "^[a-z]{2}(-[a-z]+)+-\\d$"
527
+ },
528
+ "base_url": {
529
+ "type": "string",
530
+ "format": "uri"
531
+ },
532
+ "anthropic_base_url": {
533
+ "type": "string",
534
+ "format": "uri"
535
+ }
536
+ },
537
+ "additionalProperties": false
538
+ },
539
+ "guard": {
540
+ "description": "Bounds on one review's cost, tokens, repeated calls, tool calls and time.",
541
+ "type": "object",
542
+ "properties": {
543
+ "budget_usd": {
544
+ "type": "number",
545
+ "exclusiveMinimum": 0
546
+ },
547
+ "tokens": {
548
+ "anyOf": [
549
+ {
550
+ "type": "integer",
551
+ "exclusiveMinimum": 0,
552
+ "maximum": 9007199254740991
553
+ },
554
+ {
555
+ "type": "string",
556
+ "pattern": "^\\d+(\\.\\d+)?[km]?$"
557
+ }
558
+ ]
559
+ },
560
+ "loop": {
561
+ "type": "string",
562
+ "pattern": "^\\d+\\/\\d+$"
563
+ },
564
+ "max_tools": {
565
+ "type": "integer",
566
+ "exclusiveMinimum": 0,
567
+ "maximum": 9007199254740991
568
+ },
569
+ "timeout": {
570
+ "type": "string",
571
+ "pattern": "^\\d+(\\.\\d+)?(ms|s|m|h)?$"
572
+ }
573
+ },
574
+ "additionalProperties": false
575
+ },
576
+ "max_output_tokens": {
577
+ "type": "integer",
578
+ "exclusiveMinimum": 0,
579
+ "maximum": 9007199254740991
580
+ },
581
+ "effort": {
582
+ "description": "How hard the reviewer reasons, on every backend. Unset leaves each model's default.",
583
+ "type": "string",
584
+ "enum": [
585
+ "low",
586
+ "medium",
587
+ "high"
588
+ ]
589
+ },
590
+ "cli": {
591
+ "type": "object",
592
+ "properties": {
593
+ "claude_model": {
594
+ "type": "string",
595
+ "minLength": 1
596
+ },
597
+ "codex_model": {
598
+ "type": "string",
599
+ "minLength": 1
600
+ }
601
+ },
602
+ "additionalProperties": false
603
+ },
604
+ "label": {
605
+ "description": "When set, a PR needs this label before gate reviews it.",
606
+ "type": "string",
607
+ "minLength": 1
608
+ },
609
+ "notify": {
610
+ "type": "object",
611
+ "properties": {
612
+ "on": {
613
+ "minItems": 1,
614
+ "type": "array",
615
+ "items": {
616
+ "type": "string",
617
+ "enum": [
618
+ "APPROVED",
619
+ "REFUSED",
620
+ "ESCALATE",
621
+ "ERROR"
622
+ ]
623
+ }
624
+ }
625
+ },
626
+ "additionalProperties": false
627
+ },
628
+ "telemetry": {
629
+ "type": "object",
630
+ "properties": {
631
+ "endpoint": {
632
+ "type": "string",
633
+ "format": "uri"
634
+ },
635
+ "service": {
636
+ "type": "string",
637
+ "minLength": 1
638
+ }
639
+ },
640
+ "additionalProperties": false
641
+ },
642
+ "advise_on_deny": {
643
+ "description": "When a gate denies, still ask the model, and append its findings to the refusal as advice. It cannot approve.",
644
+ "type": "boolean"
645
+ }
646
+ },
647
+ "required": [
648
+ "version",
649
+ "deny",
650
+ "allow",
651
+ "size_gate",
652
+ "tiers"
653
+ ],
654
+ "additionalProperties": false,
655
+ "title": "gate policy",
656
+ "description": "gate's merge-gate policy, .shepherd/gate.yml. Read from the default branch, never the PR head."
657
+ }