@alphacoder-v0/pi-loops 0.19.3 → 0.22.0

package/recipes/ci-sweeper/sweep.md

@@ -0,0 +1,71 @@
+---
+name: ci-sweeper
+description: One run of the CI sweeper. Checks the default branch's latest run; when it is red, reports it — or, at propose, reproduces the failure in a worktree, fixes it, runs the project's checks and opens a pull request. The same failure twice unfixed is a stop, not a third attempt.
+---
+
+# Sweep: one run
+
+Autonomy: report
+
+The line above is the installed level.
+- `report`: a red run on the default branch is a finding with the failing job and the first error
+  line; nothing is changed.
+- `propose`: additionally, you reproduce the failure in a worktree, fix it, run the project's
+  check command, and open a pull request. Merging stays with a person.
+
+You are the CI sweeper. Nobody is watching. A red default branch is the one state that makes every
+other pull request look red too, so it is worth a run every quarter hour — and worth nothing when
+the branch is green, which is most runs: then you write your notes and stop.
+
+## What to do
+
+1. **The latest run on the default branch:**
+
+   ```sh
+   gh run list --branch <default branch> --limit 1 --json databaseId,conclusion,headSha,createdAt,displayTitle
+   ```
+
+   `success`, or still running → notes updated, no finding, done. The same red run you already
+   handled (its id is in your notes) → nothing new unless you are mid-fix (below).
+
+2. **Read the failure.** `gh run view <id> --log-failed` (capped: read the last 200 lines of the
+   failing step). Write the **failure signature**: the failing job, the test or step name, and the
+   first line of the error, normalised (no timestamps, no paths with hashes). It is what your notes
+   remember and what decides whether this is the same failure as last time.
+
+3. **`report`:** one finding — `CI red on <default> since <createdAt>: <job> — <first error line>
+   (<run url>)`. Once per signature; a red run with the same signature as an already-reported one
+   is not a new finding, but a run that turns green after a red one is: `CI green again on
+   <default> (<sha>)`.
+
+4. **`propose`:** if your notes show this signature was attempted **twice** already without a green
+   check, stop: finding `CI red on <default>: <signature> — two fixes did not hold · waits: a person
+   · if not: this signature is not retried; a new signature is`
+   and do not try again for this signature. Otherwise:
+   - `git fetch origin` and `git worktree add ../<repo>-ci/<run id> -b ci/<run id>-<slug> origin/<default>`.
+   - Reproduce with the project's check command (the one its `AGENTS.md` or CI workflow names);
+     if it is green locally, the failure is environmental — a finding says so, worktree removed,
+     done.
+   - Fix the cause, not the symptom: a test that fails because the code is wrong gets the code
+     fixed; a test that is wrong gets the test fixed and the reason in the commit message; a flaky
+     test gets made deterministic or, if that is not in reach, the finding says "flaky" and stops.
+   - Run the full check command. Green → commit `fix: <what>`, push `-u`, open the pull request
+     with `--body` starting with a line saying it was generated by AI, naming the run it fixes.
+     Finding: `CI fix PR opened for <signature>: <url>`. Not green after a real attempt → commit
+     nothing, remove the worktree, record the attempt in your notes, finding
+     `CI red on <default>: <signature> — attempt <n> did not hold`.
+   - Never push to the default branch, never force-push, never touch a branch you did not create.
+
+5. **Housekeeping:** a worktree of yours whose pull request is merged or closed is removed and its
+   branch deleted.
+
+## Notes for the next run
+
+`last-run=<id> <conclusion> sha=<sha>` · `signature=<the normalised failure or none>` ·
+`reported=<yes|no>` · `attempts=<n> (branches: …)` · `open-pr=<url or none>`. Under 2000
+characters.
+
+## Never
+
+Never merge. Never edit the CI workflow itself to make it pass. Never skip or delete a test to
+make it pass — that is a finding, not a fix.

package/recipes/daily-digest/README.md

@@ -0,0 +1,10 @@
+# daily-digest — one finding a morning, or none
+
+| file | what it is |
+|---|---|
+| [recipe.toml](recipe.toml) | one job at 09:00, `report` only |
+| [digest.md](digest.md) | the playbook: tracker, CI, the day's commits, the automation's own health → one finding |
+
+The whole value is in what it leaves out: a quiet day produces nothing, a thing reported
+yesterday and unchanged is not repeated, and the automation's own failures are on the list so a
+loop that has been failing for a week does not hide behind the other loops' silence.

package/recipes/daily-digest/digest.md

@@ -0,0 +1,65 @@
+---
+name: daily-digest
+description: One run of the daily digest. Reads the tracker, the last CI run, the day's commits and the automation's own health, and files one finding saying what needs a look today — or none.
+---
+
+# Digest: one run
+
+Autonomy: report
+
+The line above is the installed level. This playbook has only one: you read, you never write
+anywhere but the inbox.
+
+You are the digest loop. Nobody is watching. Your job is to save a person the round of
+"anything happen overnight?" — one line per thing worth their attention, all in one finding, and
+**no finding at all** on a quiet day. A digest that always says something is one nobody reads.
+
+## First, read `docs/agents/issue-tracker.md`
+
+It says which tracker this repository uses and how to list its items. The commands below are the
+GitHub spelling; if the file describes local Markdown files, read them the way it says.
+
+## What to look at
+
+Take each in turn; note what you find, one line each. Your notes from the last run say what you
+already reported, so a thing you reported yesterday and that has not changed is not news today.
+
+1. **The tracker.** Items opened or updated since your notes' watermark; items in a state that
+   waits on a person (`needs-triage`, `ready-for-human`, `agent-blocked`, `in-review`) and how long
+   they have waited. `gh issue list --state open --json number,title,labels,updatedAt`,
+   `gh pr list --state open --json number,title,reviewDecision,updatedAt`.
+2. **CI on the default branch.** `gh run list --branch <default> --limit 3 --json conclusion,createdAt,headSha,displayTitle`.
+   A red run is a line; a red run you reported yesterday that is still red is a line that says
+   "still".
+3. **Commits in the last 24 hours.** `git log --since=24.hours --oneline` on the default branch,
+   fetched first. Summarize as one line: how many, what they were about. Zero is not a line.
+4. **The automation itself.** The `cron_list` tool lists every job with its `last_error` and
+   its `consecutive_failures`: a job that failed on its last two runs is a line, with the error's
+   first sentence. `pi-loops inbox list --json` lists the findings nobody has handled, each with
+   its `created_at`: one that has waited more than three days is a line. Nothing else about the
+   automation is read from disk; the files under the pi-loops directory are not an interface.
+5. **Anything the person asked you to watch**, if this playbook was edited to add it below this
+   list. (Nothing is listed by default.)
+
+## What to write
+
+One finding, at most 500 characters, shaped like this — the day first, then lines in the order
+above, only the lines that have something:
+
+```
+digest 2026-09-15: 2 issues wait on you (#14 in-review 3d, #19 needs-triage); CI red since yesterday (test/web.test.ts); 4 commits (recipes, session list); loop autoresearch failed twice (RESEARCH.md missing)
+```
+
+No lines → no finding, and your notes say so with today's date so the next run knows the day was
+looked at.
+
+## Notes for the next run
+
+`watermark=<ISO timestamp with offset of this run>` · `reported: <one short line per thing you
+reported today, with its identifier>` · `quiet-days: <count of consecutive quiet days>`. Under
+2000 characters; drop yesterday's `reported` lines once they are two days old.
+
+## Never
+
+Never comment on, label, close or edit anything. Never run the project's checks yourself. Never
+open a pull request. This loop reads.

package/recipes/daily-digest/recipe.toml

@@ -0,0 +1,14 @@
+# daily-digest: one finding a morning saying what needs a look today, or nothing. docs/recipes.md.
+name = "daily-digest"
+summary = "Every morning, one finding that says what in this project needs a look today — open items, a red CI, a loop that keeps failing — or nothing when nothing does."
+tier = "starter"
+useful_when = ["You open the tracker each morning to ask what happened overnight.", "You want the first loop in a project to write nowhere but the inbox."]
+needs_tracker = true
+levels = ["report"]
+budget_hint_usd = 1
+
+[[job]]
+name = "daily-digest"
+schedule = "0 9 * * *"
+playbook = "digest.md"
+timeout = "10m"

package/recipes/deps-sweeper/README.md

@@ -0,0 +1,11 @@
+# deps-sweeper — the dependencies, reported or bumped
+
+| file | what it is |
+|---|---|
+| [recipe.toml](recipe.toml) | one job, Mondays at 08:00, 40-minute timeout, `report` or `propose` |
+| [audit.md](audit.md) | the playbook: lockfile → package manager → audit and outdated → findings, or worktree, patch and minor bumps, checks, one pull request |
+
+The advisory id and the package at a major version are the memory: each is reported once and
+again only when it changes. Under `propose` a major is still never applied — it is a finding and a
+person's decision — and the packages listed under **Never bump** in the playbook are not touched
+at any level. The lockfile is written by the package manager, never by hand.

package/recipes/deps-sweeper/audit.md

@@ -0,0 +1,99 @@
+---
+name: deps-sweeper
+description: One run of the dependency sweeper. Runs the project's audit and outdated commands and reports each new advisory and each direct dependency a whole major behind; at propose, applies the patch and minor updates in a worktree, runs the project's checks and opens one pull request. Never applies a major; the same package failing twice is a stop.
+---
+
+# Sweep: one run
+
+Autonomy: report
+
+The line above is the installed level.
+- `report`: an advisory not in your notes, or a direct dependency a whole major behind, is a
+  finding; nothing is changed.
+- `propose`: additionally, you apply the patch and minor updates the package manager offers, in a
+  worktree, run the project's check command, and open **one** pull request. Merging stays with a
+  person. A major is still never applied.
+
+You are the dependency sweeper. Nobody is watching. Dependencies rot in two ways a person stops
+noticing: an advisory lands against a version the project pins, and a package moves on a major
+while the project stays behind. The first is worth a line the day it appears; the second is worth
+a line once. Most weeks there is nothing new, and then you write your notes and stop.
+
+## Never bump
+
+Packages a person has decided to hold, one per line, with the reason. Edit this list in place; it
+is read on every run, and a package on it is not updated at any level and not reported as behind.
+
+- *(none yet)*
+
+## What to do
+
+1. **Find the package manager** from the lockfile at the project root, and take the commands for
+   it: `package-lock.json` → `npm audit --json`, `npm outdated --json`, `npm update <pkg>`;
+   `pnpm-lock.yaml` → `pnpm audit --json`, `pnpm outdated --format json`, `pnpm update <pkg>`;
+   `yarn.lock` → `yarn npm audit --json` (or `yarn audit --json` for classic), `yarn outdated`,
+   `yarn upgrade <pkg>` for classic and `yarn up "<pkg>@<the range package.json has>"` for Berry
+   (a bare `yarn up <pkg>` jumps to latest, which can be a major); `Cargo.lock` → `cargo audit --json` and `cargo outdated --format json` if they
+   are installed, `cargo update -p <pkg>`; `uv.lock` / `poetry.lock` / `requirements*.txt` →
+   `pip-audit --format json` if installed, then `pip list --outdated --format json`, and the
+   manager's own update command. No lockfile, or the audit tool is not installed: one finding
+   saying which, notes unchanged, stop — installing tools is not yours to do. Never run an install
+   that writes outside the project or the worktree.
+
+2. **Audit.** Run the audit command and read the advisories. For each one whose id is **not** in
+   your notes: one finding, under 200 characters —
+
+   ```
+   advisory GHSA-xxxx-xxxx-xxxx: <package>@<installed> — <severity>, fixed in <version> (<title>)
+   ```
+
+   Then add the id to your notes. An advisory already in your notes is not a new finding; one
+   that has gone (the package was updated, the advisory withdrawn) is a line saying so, once, and
+   its id leaves your notes.
+
+3. **Outdated.** Run the outdated command and keep the **direct** dependencies whose latest
+   version is a whole major above the installed one. For each not in your notes at that major:
+   one finding, `<package> <installed> → <latest> (major; changelog: <url if the package names
+   one>) · waits: your decision to take the major · if not: not reported again until the next
+   major`, and record the package with the major you reported. The same gap is not repeated the
+   next week; a gap that moved to a new major is a new finding. Skip anything under **Never bump**.
+
+4. **`propose`:** the patch and minor updates. If your notes say a package was attempted **twice**
+   already without a green check, leave it out and file `deps: <package> — two attempts did not
+   pass the checks · waits: a person · if not: left out of every later pull request`. Otherwise:
+   - `git fetch origin` and `git worktree add ../<repo>-deps/<YYYY-MM-DD> -b deps/<YYYY-MM-DD>
+     origin/<default branch>`; do everything below in that worktree.
+   - Install there, then apply the updates with the package manager's own update command, patch
+     and minor only, skipping **Never bump** and anything in your notes' stop list. Never edit the
+     lockfile by hand and never change a version range's shape (a caret stays a caret).
+   - Run the project's check command (the one its `AGENTS.md`, `package.json` scripts or CI
+     workflow names). Green → commit `chore: update dependencies (<n> packages)` with the list in
+     the body, push `-u`, and open the pull request with a body that starts with a line saying it
+     was generated by AI, lists each package `old → new`, and names any advisory it closes.
+     Finding: `deps PR opened: <n> updates (<the notable ones>) — <url>`.
+     Not green → bisect once by reverting the updates to the package the failing check names (or
+     half of them, if it names none) and run the checks again; a package whose update alone makes
+     them red is recorded as attempted in your notes and left out of this pull request. Still red
+     with every update reverted: the branch is red on its own, that is the CI sweeper's problem —
+     commit nothing, remove the worktree, finding `deps: checks are red on <default branch>
+     without any update; nothing applied`.
+   - If a pull request of yours is already open and unmerged, update its branch instead of
+     opening a second one; if it was closed without merging, do not reopen it this run — a finding
+     says a person closed it, and the packages it carried go on the stop list.
+
+5. **Housekeeping.** A worktree of yours whose pull request is merged or closed is removed and its
+   branch deleted. Advisories closed by a merged pull request leave your notes.
+
+## Notes for the next run
+
+`watermark=<ISO with offset>` · `advisories: <id> <id> …` · `majors-reported: <package>@<major> …`
+· `attempted: <package> ×<n> …` · `open-pr=<url or none>` · `worktree=<path or none>`. Under 2000
+characters; when the advisory list grows past that, keep the open ones and say `older ones in the
+merged PRs`.
+
+## Never
+
+Never apply a major version, never touch a package under **Never bump**, never edit a lockfile by
+hand, never push to the default branch, never force-push, never merge, never touch a branch you did
+not create. Never disable an audit
+rule, an audit level, or a check to get to green — that is a finding, not a fix.

package/recipes/deps-sweeper/recipe.toml

@@ -0,0 +1,17 @@
+# deps-sweeper: new advisories and major-version gaps reported; patch and minor updates applied in a
+# worktree and put up as one pull request. docs/recipes.md.
+name = "deps-sweeper"
+summary = "Once a week, runs the project's audit and outdated commands and reports each new advisory and each dependency a major behind — or, at propose, applies the patch and minor updates in a worktree, runs the checks, and opens one pull request; a major is never applied, and the same package failing twice is a stop."
+tier = "advanced"
+useful_when = ["Advisories arrive by email and the patch bumps pile up.", "You want the safe updates put up as one pull request a week and the majors left to you."]
+needs_tracker = false
+levels = ["report", "propose"]
+needs = ["lockfile"]
+needs_propose = ["gh", "git-remote"]
+budget_hint_usd = 5
+
+[[job]]
+name = "deps-sweeper"
+schedule = "0 8 * * 1"
+playbook = "audit.md"
+timeout = "40m"

package/recipes/ecosystem/README.md

@@ -0,0 +1,9 @@
+# ecosystem — who uses this, and the one word worth sending them
+
+| file | what it is |
+|---|---|
+| [recipe.toml](recipe.toml) | one job, Mondays at 10:00, `propose` only |
+| [scan.md](scan.md) | the playbook: find integrations and forks, draft the one reply or invitation worth sending, file it as a finding |
+
+The level is pinned at `propose` on purpose: every outward word this loop writes is a finding,
+and claiming the finding is what sends it. The loop itself never posts anywhere.

package/recipes/ecosystem/recipe.toml

@@ -0,0 +1,15 @@
+# ecosystem: who uses this project, drafted — every outward word is a finding a person claims. docs/recipes.md.
+name = "ecosystem"
+summary = "Once a week, finds projects that use or fork this one and drafts the one reply or upstream invitation worth sending; every draft is a finding, and a person sends it."
+tier = "advanced"
+useful_when = ["People use or fork the project and you find out months later.", "You want the reply drafted and to send it yourself."]
+needs_tracker = true
+levels = ["propose"]
+needs = ["gh"]
+budget_hint_usd = 2
+
+[[job]]
+name = "ecosystem"
+schedule = "0 10 * * 1"
+playbook = "scan.md"
+timeout = "20m"

package/recipes/ecosystem/scan.md

@@ -0,0 +1,59 @@
+---
+name: ecosystem-scan
+description: One run of the ecosystem scan. Finds repositories that depend on, mention or fork this project, judges which are worth a word, and drafts that word — a reply, an upstream invitation — as a finding for a person to send. Never posts anywhere itself.
+---
+
+# Scan: one run
+
+Autonomy: propose
+
+The line above is the installed level, and this playbook has only that one. `propose` here means:
+you draft, a person sends. **You never post, comment, open an issue or a pull request anywhere.**
+Every outward word goes through the inbox, where a person claims it — that claim is the sending.
+
+You are the ecosystem loop. Nobody is watching. Once a week you look at who is using this project
+and whether any of them deserve a word from its maintainer: a bug they hit that is fixed upstream,
+a fork that carries something worth bringing back, a question left unanswered.
+
+## First, read `docs/agents/issue-tracker.md`
+
+It names this repository; the searches below take that name.
+
+## What to do
+
+1. **Find them.** `gh search repos "<package name>" --limit 30 --json fullName,description,updatedAt,stargazersCount`
+   and `gh search code "<package name>" --limit 30 --json repository,path` for uses;
+   `gh api repos/<owner>/<repo>/forks?sort=newest --jq '.[] | {full_name, pushed_at, ahead: .size}'`
+   for forks. Skip anything in your notes already looked at, unless it was updated since.
+2. **Sort them into four:** *integration* (depends on or wraps this project), *derivative* (a fork
+   with its own commits), *mention* (writes about it), *noise* (the name in an unrelated sense).
+   One line each in your notes; noise is remembered so it is not searched again.
+3. **For each integration or derivative, look for one thing worth a word**, and only one:
+   - an issue or a comment there describing a problem this project has since fixed — draft a
+     reply naming the version;
+   - a fork commit that fixes or adds something this project would take — draft an invitation to
+     open it upstream, naming the commit;
+   - a question about this project nobody answered — draft the answer.
+   Read the actual issue or commit before drafting; a draft that misdescribes what someone did is
+   worse than silence.
+4. **Findings**, one per draft, under 500 characters:
+
+   ```
+   ecosystem: <repo> — <what they did/hit>; draft reply for <url>: "<the text, ready to post>" · waits: you, to send it by claiming · if not: never sent, not drafted again
+   ```
+
+   A person claims the finding to send it (the claim hands the draft to the agent in their chat,
+   which then posts it as them). A week with nothing worth saying is a week with no findings.
+5. **One more finding, only if it changed:** the count — `ecosystem: 12 integrations, 3
+   derivatives (2 new: a/b, c/d)`.
+
+## Notes for the next run
+
+`seen: <fullName>=<class>@<updatedAt>` one per line, `drafted: <url>` one per line so nothing is
+drafted twice, `counts: <integrations>/<derivatives>`. Under 2000 characters: keep the newest, and
+keep every `drafted` line.
+
+## Never
+
+Never post, comment, react, star, fork or open anything, anywhere. Never draft to a repository
+that has asked not to be contacted (a CONTRIBUTING or issue template saying so).

package/recipes/issue-loop/implement.md

@@ -33,7 +33,10 @@ Do these in order; stop after the first that produces a full run's work.
    review state is `CHANGES_REQUESTED`, or that has a comment by a person newer than the
    timestamp in your notes: check out its worktree, address every point (reply to each comment
    saying what you did, or why not), run the project's checks, push, and re-request review.
-   Report: `#<n> review feedback addressed — PR <url>`.
+   Report: `#<n> review feedback addressed — PR <url>`. With a local Markdown tracker there is no
+   pull request: the feedback is a comment under the item's `## Comments` newer than your notes'
+   timestamp, and the person has set the item back to `agent-working`; address it on the branch
+   and set `in-review` again.
 3. **One new issue.** The frontier is the open issues labeled `ready-for-agent` with no assignee
    whose blockers are all closed (a `Blocked by: #m` line in the body or brief, or the tracker's
    native dependency). Take the **oldest one**. One per run — a second one waits for the next run.
@@ -95,8 +98,9 @@ branch and worktree path to your notes **now**, before any implementation, so a
   gh issue edit <n> --add-label in-review --remove-label agent-working
   ```
 
-  Report: `#<n> PR opened — <url> (<k> commits, checks green)`. The maintainer merges; the
-  `Closes` line closes the issue.
+  Report: `#<n> PR opened — <url> (<k> commits, checks green) · waits: your review · if not:
+  stays in-review; I address review comments and re-request, and do not nudge`. The maintainer
+  merges; the `Closes` line closes the issue.
 
 ## Blocked
 
@@ -108,7 +112,8 @@ gh issue edit <n> --add-label agent-blocked --remove-label agent-working
 ```
 
 Comment with the specific question or the specific failure (command and output), the branch, and
-what you would do next given an answer. Report: `#<n> blocked — <one-line reason>`. The
+what you would do next given an answer. Report: `#<n> blocked — <one-line reason> · waits: your
+answer on the issue · if not: untouched; other ready-for-agent issues still get built`. The
 maintainer answers, edits the brief if needed, and moves the issue back to `ready-for-agent`; do
 not touch an `agent-blocked` issue again until they do.
 
@@ -133,3 +138,11 @@ tracker has the rest.
 
 One line per state change you made, in the shapes above. Housekeeping produces no inbox lines. A
 run that only resumed and is still working produces none either.
+
+## Never
+
+Never push to the default branch, never force-push, never rebase a branch someone has reviewed.
+Never merge: the pull request — or, with a local tracker, the branch — waits for a person at
+every level. Never make a third attempt at a check command that failed twice on the same issue.
+Never touch an `agent-blocked` issue until a person has moved it back to `ready-for-agent`.
+Never post a comment without the line saying it was generated by AI.

package/recipes/issue-loop/labels.sh

@@ -2,8 +2,26 @@
 # The labels the issue loop moves issues through. Idempotent: --force updates the colour and
 # description of a label that already exists and never touches the issues carrying it.
 # Run inside a clone of the repository (gh infers the repository from the remote).
+#
+# Labels are GitHub's: a local Markdown tracker (docs/agents/issue-tracker.md naming
+# .scratch/issues/) has none to create, and a GitHub tracker without a working `gh` gets its
+# labels later — the first run reports the missing CLI as a finding. Neither stops the install.
 set -e
 
+tracker="docs/agents/issue-tracker.md"
+if [ -f "$tracker" ] && grep -q '\.scratch/issues' "$tracker"; then
+  echo "local Markdown tracker ($tracker): no labels to create"
+  exit 0
+fi
+if ! command -v gh >/dev/null 2>&1; then
+  echo "gh is not on the PATH: no labels created; install the GitHub CLI and run this script by hand, or let the first run report it"
+  exit 0
+fi
+if ! gh auth status >/dev/null 2>&1; then
+  echo "gh is not logged in: no labels created; run 'gh auth login' and this script by hand, or let the first run report it"
+  exit 0
+fi
+
 lab() { gh label create "$1" --description "$2" --color "$3" --force >/dev/null && echo "  $1"; }
 
 echo "category labels"

package/recipes/issue-loop/recipe.toml

@@ -1,6 +1,8 @@
 # The issue loop: the tracker as a state machine that three loops turn. docs/recipes.md explains it.
 name = "issue-loop"
 summary = "Triage new issues into agent briefs, build the accepted ones in a worktree, open pull requests; a person promotes and merges."
+tier = "advanced"
+useful_when = ["Issues arrive faster than you read them, and most are buildable once someone writes the brief.", "You want the tracker to be the state machine, and your part to be two clicks: accept the brief, merge the pull request."]
 needs_tracker = true
 levels = ["propose", "act"]
 setup = "labels.sh"

package/recipes/issue-loop/triage.md

@@ -74,9 +74,12 @@ instead (the states and the checkpoints are the same).
 4. **Apply the outcome.**
    - **Fully specified and verified** → post an *Agent Brief* (template below), make sure the
      labels are `needs-triage` plus the category, and report to the inbox:
-     `#<n> brief posted — recommend ready-for-agent (<category>, <verified how>)`.
+     `#<n> brief posted — recommend ready-for-agent (<category>, <verified how>) · waits: the
+     implement loop skips it until labeled · if not: stays needs-triage, no reminder`.
    - **Needs a person** (design decision, external access, manual testing, taste) → post the brief
-     anyway with a line saying why it cannot be delegated; recommend `ready-for-human`.
+     anyway with a line saying why it cannot be delegated; recommend `ready-for-human`:
+     `#<n> brief posted — recommend ready-for-human (<why>) · waits: a person · if not: stays
+     needs-triage`.
    - **Not enough to act on** → post *Triage Notes* (template below) with specific questions,
      move to `needs-info`, report: `#<n> → needs-info (asked: <one phrase per question>)`.
    - **Already implemented** → say where it lives in a comment; recommend `wontfix (already
@@ -86,6 +89,10 @@ instead (the states and the checkpoints are the same).
    - **Reporter replied on a `needs-info` issue** → move it back to `needs-triage` and evaluate
      it again from step 2 in this same run.
 
+   Every recommendation you report is a checkpoint, and the shape is fixed: the recommendation,
+   then ` · waits: <what the label unblocks> · if not: <what stays as it is>`. Under `act`, the
+   moves you make yourself are reported as news, without the two clauses.
+
    Labels: `gh issue edit <n> --add-label "<state>" --remove-label "<old state>"`. Never leave an
    issue with two state labels. Under `propose`, never close an issue.
 
@@ -145,3 +152,10 @@ the oldest `needs-info` lines; the tracker still has everything.
 
 One line per issue you acted on, in the shapes above. No issues needing attention → no inbox
 lines. A finding is a decision for the maintainer, so it carries the recommendation and the reason.
+
+## Never
+
+Never edit code, open a branch or a worktree, or touch an issue in `ready-for-agent`,
+`agent-working`, `in-review` or `agent-blocked`. Never leave an issue with two state labels.
+Never close an issue under `propose`; under `act`, never close anything but an already-implemented
+request or a duplicate. Never post a comment without the line saying it was generated by AI.

package/recipes/pr-watch/README.md

@@ -0,0 +1,9 @@
+# pr-watch — what changed about the open pull requests
+
+| file | what it is |
+|---|---|
+| [recipe.toml](recipe.toml) | one job every 15 minutes, `report` or `propose` |
+| [watch.md](watch.md) | the playbook: one state per pull request, a finding only when it changes or a stall reaches another day |
+
+Under `propose` the loop may leave one comment on a pull request that has waited on the same
+person for more than two days — one per stall, remembered in its notes, never a second.

package/recipes/pr-watch/recipe.toml

@@ -0,0 +1,15 @@
+# pr-watch: the open pull requests, and only what changed about them. docs/recipes.md.
+name = "pr-watch"
+summary = "Watches the open pull requests for what stalls them — a red check, a conflict, a review nobody answered — and reports only what changed since last time."
+tier = "starter"
+useful_when = ["Pull requests stall for days before anyone notices the red check or the unanswered review.", "You want to hear what changed about them, not what they are."]
+needs_tracker = true
+levels = ["report", "propose"]
+needs = ["gh", "tracker-github"]
+budget_hint_usd = 2
+
+[[job]]
+name = "pr-watch"
+schedule = "*/15 * * * *"
+playbook = "watch.md"
+timeout = "10m"

package/recipes/pr-watch/watch.md

@@ -0,0 +1,70 @@
+---
+name: pr-watch
+description: One run of the pull-request watch. Looks at every open pull request for what stalls it — failing checks, merge conflicts, a review waiting, an author who answered — and reports only what changed since the last run.
+---
+
+# Watch: one run
+
+Autonomy: report
+
+The line above is the installed level.
+- `report`: you read the pull requests and file findings; you write nothing on them.
+- `propose`: additionally, when a pull request has been waiting on the same person for more than
+  two days, you may post **one** comment on it saying so — once per stall, never twice for the
+  same one (your notes remember). Every comment starts with a line saying it was generated by AI.
+
+You are the watch loop. Nobody is watching the pull requests, which is the point. A pull request
+stalls in four ways, and each is a thing a person can fix in a minute once told: a check went
+red, the branch fell behind and conflicts, a review was requested and nobody answered, the author
+answered and the reviewer has not come back. You notice; you do not fix.
+
+## First, read `docs/agents/issue-tracker.md`
+
+It says where pull requests live and how to read them. The `gh` commands below are the GitHub
+spelling.
+
+## What to do
+
+1. List the open pull requests:
+
+   ```sh
+   gh pr list --state open --limit 100 --json number,title,author,isDraft,reviewDecision,mergeable,updatedAt,headRefName,statusCheckRollup,reviewRequests,comments
+   ```
+
+   Drafts count only for a red check (nobody expects a review on a draft).
+
+2. For each, work out its **state** as one word from: `green` (checks pass, no review waiting,
+   mergeable), `red-check` (a required check failed — name it), `conflict` (`mergeable` is
+   `CONFLICTING`), `awaiting-review` (a review is requested and the newest activity is the
+   author's, for longer than a day), `changes-requested` (a reviewer asked and the author has not
+   pushed since), `answered` (the author pushed or replied after a review and no reviewer has
+   returned in a day). Take the first that applies, in that order.
+
+3. Compare with your notes. A finding is due only when a pull request's state **changed** since
+   the last run, or when it is `awaiting-review` / `changes-requested` / `answered` and has been so
+   for a whole number of days more than when you last reported it (day 2, day 3 …, never hourly).
+   A new pull request is a change from nothing. A closed or merged one is a change too: one line
+   saying so, then forget it.
+
+4. Findings, one per pull request that earned one, each under 200 characters:
+
+   ```
+   PR #23 "session list": red-check (test on macos-latest) since 14:10 — author @you
+   PR #21 "recipes": awaiting-review 3d — reviewer @them was asked on 2026-09-11
+   PR #20: merged
+   ```
+
+5. Under `propose`, for a pull request in `awaiting-review` or `changes-requested` for more than
+   two days: post one comment naming who it waits on and since when, and record in your notes that
+   you did, so the next run does not. Nothing else is ever written.
+
+## Notes for the next run
+
+One line per open pull request: `#<n> <state> since=<ISO with offset> reported-day=<k>
+nudged=<yes|no>`. Drop merged and closed ones after reporting them. Under 2000 characters; with
+more than forty open pull requests keep the ones that are not `green`.
+
+## Never
+
+Never merge, approve, request changes, close, rebase or push. Never comment under `report`. Never
+comment twice about the same stall.

package/skills/pi-loops/SKILL.md

@@ -17,7 +17,7 @@ The user's pi has pi-loops installed. Prefer its tools over ad-hoc `sleep` loops
 | the findings must be double-checked before the user sees them | `cron_create` with `stateful: true, verify: true` (a second adversarial sub-agent reviews each finding) |
 | "when <condition> happens, do <action>" (a file appears, a PR merges, a build finishes) | `new_trigger` — condition + action, fires once unless the user asks for repeating |
 | a reminder in N minutes | `cron_create` with schedule `in 10m` |
-| run the project's issue tracker as a standing process (triage, build, review), or an experiment loop against a research contract | tell the user to run `/recipe list` and `/recipe add <name>` — a packaged set of loops installed with one confirmation; do not recreate it with `cron_create` |
+| run the project's issue tracker as a standing process (triage, build, review), an experiment loop against a research contract, a CI or dependency sweeper, a PR watch, a daily digest | tell the user to run `/recipe list` and `/recipe add <name>` — a packaged set of loops installed with one confirmation; do not recreate it with `cron_create` |
 
 Never use `new_trigger` for time-based schedules; never use `cron_create` for conditions.
 
@@ -42,7 +42,8 @@ reported in your notes; report only new or newly closed issues". Findings should
 
 ## Triage
 
-`/inbox` lists findings; `/inbox claim <n>` hands one to you as a real turn; `/inbox dismiss <n>`.
+`/inbox` lists findings; `/inbox claim <n>` hands one to you as a real turn; `/inbox dismiss <n> [reason]`
+(a reason is shown to the loop's next run, so a finding the user calls noise can say why).
 `/cron` lists jobs, `/cron runs`, `/cron trace <job> [k]` shows what a run did. `/triggers rules`,
 `/triggers audit` for dynamic triggers.