@jagreehal/shepherd 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jagreehal/shepherd",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Agent skills that drive a PR to merge-ready: a review swarm, thread triage, CI repair, and a loop that hands the result to stamp.",
   "license": "MIT",
   "repository": "github:jagreehal/shepherd",

package/skills/garden/SKILL.md

@@ -5,7 +5,8 @@ description: >
   GitHub record (reverted fixes, people replying in a thread, round caps, loops
   that stopped short or went quiet), then opens PRs: skill edits to shepherd for
   the patterns behind low scores, and lint rules for lens findings triage keeps
-  fixing, so lint catches them before any model reads the diff. Use for "/garden", "garden shepherd", "what should shepherd learn", or
+  fixing, so lint catches them before any model reads the diff, and a rule for
+  each incident whose culprit PR stamp approved. Use for "/garden", "garden shepherd", "what should shepherd learn", or
   on a weekly schedule. Takes repos (owner/name) and an optional --since date.
 ---
 
@@ -41,7 +42,8 @@ person replied in, rounds, and `shepherd` status. `recurring` lists the lens
 rules **accepted** on at least 3 PRs: triage fixed them in a commit nobody
 reverted, named them in a `Shepherd-Fixes` trailer, on a PR by someone who can
 push, and no person argued in their threads. Triage resolves findings it judged
-wrong too, so a resolved thread alone counts for nothing.
+wrong too, so a resolved thread alone counts for nothing. `escapes` lists the
+incidents whose culprit PR stamp approved (Step 5b).
 
 | Signal | Means |
 |---|---|
@@ -69,7 +71,7 @@ the thread the author was left with was one triage should have fixed.
 ## Step 3: Score the window
 
 One table per repo: PRs shepherd touched, PRs with each signal, and the share
-of PRs with no signal. Read the previous garden PR's body
+of PRs with no signal, plus the escapes count. Read the previous garden PR's body
 (`gh pr list -R jagreehal/shepherd --search "garden:" --state all --limit 1`)
 and give the change since then, so a merged edit shows whether it helped.
 
@@ -116,16 +118,39 @@ Open one PR per repo titled `garden: lint rules <date>`, with the trailer
 id it retires. Leave the lens rule in place: a person retires it once the
 lint rule has held.
 
+## Step 5b: A rule for each escaped regression
+
+Each entry in `escapes` is an incident the `incident` skill traced to a PR
+stamp approved. Read the incident issue's root cause, the culprit PR's diff
+and stamp's review on it, and the fix PR with its reproducing test.
+
+- **`cause: merge_skew`:** the PR passed on its own head, so no review rule
+  would have caught it. Put "require up-to-date branches, or a merge queue" in
+  the report and propose nothing.
+- **Otherwise:** write the smallest rule that flags the culprit diff and passes
+  the fix. A rule one file's syntax decides goes through Step 5 as a lint rule.
+  Any other rule joins the repository's own stamp rule pack (`.stamp/rules/`)
+  or a team lens in `.shepherd/`, whichever already covers those paths; add to
+  an existing file before creating one. The rule names what to check, never
+  the incident ("a function that now dereferences an argument its callers can
+  pass as null needs a test with that input").
+
+Rules only tighten. Open one PR per repository titled `garden: escapes <date>`,
+with the trailer `Shepherd: garden`, and give each rule its incident, culprit
+PR, fix PR and the line in the culprit diff it flags. stamp sends a PR that
+edits `.stamp/` or `.shepherd/` to a person, which is the review a new rule
+needs.
+
 ## Outbox mode
 
 When `GARDEN_OUTBOX` is set (the scheduled workflow), you hold no write
-token. Steps 4 and 5 make the same edits but never commit, push, or open a PR.
+token. Steps 4, 5 and 5b make the same edits but never commit, push, or open a PR.
 For each PR you would open, make one directory:
 
 ```text
 $GARDEN_OUTBOX/<short-slug>/
   repo        one line: owner/name the PR targets
-  body.md     the PR body, exactly as Steps 4 and 5 describe it
+  body.md     the PR body, exactly as Steps 4, 5 and 5b describe it
   tree/       a fresh `gh repo clone` of that repo with your edits, uncommitted
 ```
 
@@ -135,7 +160,7 @@ The workflow turns each directory into a patch and opens the PR itself.
 
 ## Step 6: Report
 
-End with the score tables, links to the PRs opened, the causes with no
+End with the score tables, the escapes and the rule proposed for each, links to the PRs opened, the causes with no
 proposal and why, and the judgment rules left to the lenses. Scheduled runs
 print it to the job log; the PR bodies carry everything a reviewer needs.
 

package/skills/incident/SKILL.md

@@ -76,7 +76,9 @@ gh issue list --label incident --state open --search "shepherd-incident:<fingerp
 
 Hash the fingerprint to 12 hex chars: write it to a file with your file tool,
 then `shasum <file> | cut -c1-12`. An open issue with that marker already
-tracks it, and it is your issue.
+tracks it, and it is your issue. Only a search that exits 0 says there is
+none: when it fails, fix the cause and run it again before you open anything,
+since a second issue splits the record.
 
 Otherwise create the label once and open the issue:
 
@@ -172,23 +174,30 @@ failing commit, and a later run can sit on a descendant).
 git bisect start <live commit> <good> && git bisect run sh -c '<probe body>'; git bisect reset
 ```
 
+Name the culprit only from the probe: the commit `git bisect run` reports,
+or the one commit of a single-commit range after `probe` fails on it and
+passes on its parent. A culprit read off a diff or the signal is a guess; run
+the bisection even when the diff looks obvious.
+
 When the range is a single commit, that commit is the culprit; no bisection
 is needed. Skip bisection when no good end exists within 64 commits or the test cannot
 run on older commits; say so. For the culprit commit, find its PR:
 `gh api repos/{owner}/{repo}/commits/<sha>/pulls --jq '.[0].number'`, and
-whether stamp approved it (a review carrying `<!-- stamp-run:`). Add
+whether stamp approved it: `gh api repos/{owner}/{repo}/pulls/<pr>/reviews --jq '[.[] | select(.body | contains("<!-- stamp-run:"))] | last | .state'`
+gives `APPROVED` for approved, empty for not reviewed, and anything else for
+held for a human. Add this line to the issue body, exactly, with one of the
+three values (garden parses it):
 `Regressed-by: #<pr> (<sha>), stamp: <approved|not reviewed|held for a human>`
-to the issue body.
 
 Then tell merge skew from a coverage gap, with the probe, not from CI's
 colour. Run `probe` on the PR's last head commit (`gh pr view <pr> --json
 headRefOid`):
 
 - **Passes on the PR head, fails on the merged culprit:** the base moved under
-  it. Add `Merge skew: passes on <head sha>, fails merged`; the cure is an
+  it. Add the line `Merge skew: passes on <head sha>, fails merged`; the cure is an
   up-to-date-branch rule or a merge queue, not a stricter review.
 - **Fails on the PR head too:** the PR shipped the failure and its tests did
-  not cover it. Add `Coverage gap: fails on <head sha>`.
+  not cover it. Add the line `Coverage gap: fails on <head sha>`.
 - **Head commit gone or probe cannot run there:** record neither.
 
 Then return, popping only this run's entry, never the developer's:

package/src/cli.ts

@@ -33,7 +33,7 @@ import { parse as parseYaml, stringify } from "yaml";
 import { type Config, ConfigSchema, defaultBranchReader, type Effective, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, policyProblems, PRESETS, preview, type Read, TEAM_FILES } from "./config.ts";
 import { ghThreads, snapshot, verdict } from "./acceptance.ts";
 import { doctor } from "./doctor.ts";
-import { collect, score } from "./garden.ts";
+import { collect, collectEscapes, score } from "./garden.ts";
 import { install, uninstall, type Outcome } from "./install.ts";
 import { buildDemo, captureChange, demoBugs, finish, receiptStatus } from "./local.ts";
 import { addLens, BUILT_IN_LENSES, lensTemplates, globalLensFile, lensProblems, newLens, opencodeAgents, pinModel, repoLensFile, resolveSkill, setLadder, skillDescription, type Lens } from "./lens.ts";
@@ -209,7 +209,7 @@ if (command === "install") {
   const since = opts.since ?? new Date(Date.now() - 7 * 864e5).toISOString().slice(0, 10);
   const repos = [sub, ...(skillRef ? [skillRef] : []), ...rest];
 
-  console.log(JSON.stringify(repos.map((repo) => ({ repo, since, ...score(orExit(() => collect(repo, since)), Number(opts["min-prs"])) })), null, 2));
+  console.log(JSON.stringify(repos.map((repo) => ({ repo, since, ...score(orExit(() => collect(repo, since)), Number(opts["min-prs"])), escapes: orExit(() => collectEscapes(repo, since)) })), null, 2));
 } else if (command === "local" && sub === "change") {
   console.log(JSON.stringify(orExit(() => captureChange(repoRoot, opts.base)), null, 2));
 } else if (command === "local" && sub === "finish" && skillRef) {

package/src/garden.ts

@@ -128,6 +128,22 @@ export function parseCommit(sha: string, message: string, date = ""): Commit {
   return { sha, headline: message.split("\n")[0] ?? "", skill: trailer("Shepherd"), lens: trailer("Shepherd-Lens"), fixes, date };
 }
 
+/** An incident whose culprit PR stamp approved: the review let a regression through. */
+export type Escape = { incident: number; title: string; url: string; pr: number; sha: string; cause: "coverage_gap" | "merge_skew" | null };
+
+const REGRESSED = /Regressed-by: #(\d+) \(([0-9a-f]{7,40})\), stamp: approved\b/;
+
+/** The escape an incident issue records, from the lines the incident skill writes; null unless stamp approved the culprit. */
+export function parseEscape(issue: { number: number; title: string; url: string; body: string }): Escape | null {
+  if (!issue.body.includes("<!-- shepherd-incident:")) return null;
+  const m = REGRESSED.exec(issue.body);
+
+  if (!m) return null;
+  const cause = /^`?Coverage gap: /m.test(issue.body) ? "coverage_gap" : /^`?Merge skew: /m.test(issue.body) ? "merge_skew" : null;
+
+  return { incident: issue.number, title: issue.title, url: issue.url, pr: Number(m[1]), sha: m[2]!, cause };
+}
+
 export const roundsOf = (summaryBody: string | undefined) => (summaryBody ? Number(ROUND.exec(summaryBody)?.[1] ?? 0) || null : null);
 
 const gh = (args: string[]) => execFileSync("gh", args, { encoding: "utf8", maxBuffer: 64 << 20, stdio: ["ignore", "pipe", "pipe"] }); // stderr rides on the thrown error
@@ -160,6 +176,15 @@ const Statuses = z.object({ statuses: z.array(z.object({ context: z.string(), st
 
 const Comments = z.array(z.object({ body: z.string() }));
 
+const Issues = z.array(z.object({ number: z.number(), title: z.string(), url: z.string(), body: z.string() }));
+
+/** Incidents updated since `since` whose culprit PR stamp approved. */
+export function collectEscapes(repo: string, since: string): Escape[] {
+  const issues = Issues.parse(JSON.parse(gh(["issue", "list", "-R", repo, "--label", "incident", "--state", "all", "--search", `updated:>=${since}`, "--limit", "100", "--json", "number,title,url,body"])));
+
+  return issues.flatMap((i) => parseEscape(i) ?? []);
+}
+
 /** Read shepherd's record on the PRs updated since `since` (YYYY-MM-DD). */
 export function collect(repo: string, since: string): PrRecord[] {
   const [owner, name] = repo.split("/");