@alphacoder-v0/pi-loops 0.19.3 → 0.20.0

package/CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to pi-loops are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow SemVer.
 
+## [0.20.0] - 2026-09-14
+
+### Added
+- **Five more recipes.** `daily-digest` files one finding a morning saying what needs a look —
+  open items, a red default branch, a loop that failed its last two runs — or none on a quiet day.
+  `pr-watch` gives every open pull request one state and reports only what changed, or a stall
+  that lasted another day; under `propose` it may leave one comment per stall. `ci-sweeper` turns
+  a red default branch into a finding, or under `propose` a fix in a worktree and a pull request,
+  with the failure signature as memory and a stop after two failed attempts. `ecosystem` finds who
+  uses or forks the project and drafts the one reply or invitation worth sending, every draft a
+  finding a person sends by claiming it, its only level `propose`. `changelog-draft` gains
+  `propose`: the entry and the version bump in a release pull request. None of these touch
+  `src/`; `test/recipe.test.ts` holds every packaged manifest and playbook to the same rules.
+
+### Fixed
+- `@earendil-works/pi-ai` is listed in `peerDependencies`: two files import a type from it, and
+  pi's packaging rules ask that every bundled package imported be listed.
+- The "escape hatch" front-end test read the fake pi's log unconditionally and failed on runs
+  where nothing had reached pi yet — which is the fact it was asserting. A missing log now reads
+  as empty.
+
 ## [0.19.3] - 2026-09-14
 
 ### Fixed

package/README.md

@@ -38,7 +38,7 @@ the first sign of credentials that do not work should not be an empty inbox tomo
 
 ```bash
 pi install npm:@alphacoder-v0/pi-loops                      # from npm, following new releases
-pi install git:github.com/alphacoder-v0/pi-loops@v0.19.3    # or from GitHub, at a pinned tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.20.0    # or from GitHub, at a pinned tag
 pi install /path/to/pi-loops                                # or a local checkout — `pi install .` in this repo
 pi -e /path/to/pi-loops                                     # or none of them: try it for one run, installing nothing
 ```
@@ -138,10 +138,11 @@ A job records its directory and model at creation, so it is not tied to the wind
 `--cwd` runs it in another checkout (absolute, or relative to this project — no shell, so nothing
 expands `~`), and `--model` pins it whatever this session is on (`/cron set <ref> --model -` unpins).
 
-And two you do not write at all: `/recipe add issue-loop` runs the issue tracker as a state machine
-that two loops turn, `/recipe add autoresearch` runs one experiment per run against a contract you
-wrote — each a directory of playbooks copied into the project, installed with one question and one
-confirmation ([docs/recipes.md](docs/recipes.md)).
+And seven you do not write at all: `/recipe add issue-loop` runs the issue tracker as a state
+machine that two loops turn, `/recipe add autoresearch` runs one experiment per run against a
+contract you wrote, and `daily-digest`, `pr-watch`, `ci-sweeper`, `changelog-draft` and
+`ecosystem` do what their names say — each a directory of playbooks copied into the project,
+installed with one question and one confirmation ([docs/recipes.md](docs/recipes.md)).
 
 Two that are not loops:
 

package/README.zh-CN.md

@@ -45,7 +45,7 @@ pi-loops 自己没有任何运行时依赖。
 
 ```bash
 pi install npm:@alphacoder-v0/pi-loops                      # 从 npm 装，跟着新版本走
-pi install git:github.com/alphacoder-v0/pi-loops@v0.19.3    # 或者从 GitHub 装，钉住一个 tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.20.0    # 或者从 GitHub 装，钉住一个 tag
 pi install /path/to/pi-loops                                # 或者本地检出；本仓库里就是 pi install .
 ```
 

package/docs/recipes.md

@@ -14,16 +14,17 @@ anything a person could not have typed.
 /recipe remove issue-loop  its jobs go; the files stay unless you say --purge
 ```
 
-Two recipes ship in this version, and the shape is meant to be copied:
+Seven recipes ship, and the shape is meant to be copied:
 
 | recipe | jobs | what it runs | levels |
 |---|---|---|---|
 | [issue-loop](../recipes/issue-loop/) | `issue-triage` every 30 min, `issue-implement` every 30 min offset | the issue tracker as a state machine: triage into agent briefs, build accepted issues in a worktree, open pull requests | `propose`, `act` |
 | [autoresearch](../recipes/autoresearch/) | `autoresearch` every hour, with `--verify` | one experiment per run against a contract you wrote, a ledger of every attempt, promotion only on held-out evidence | `propose`, `act` |
-
-`changelog-draft` (a nightly changelog entry and version proposal) is packaged with its playbook
-and manifest but is still the release-side half of the issue loop; it and four more — a daily
-digest, a pull-request watch, a CI sweeper, an ecosystem scan — are the next batch.
+| [daily-digest](../recipes/daily-digest/) | `daily-digest` at 09:00 | one finding saying what needs a look today — open items, a red CI, a loop that keeps failing — or none | `report` |
+| [pr-watch](../recipes/pr-watch/) | `pr-watch` every 15 min | the open pull requests, and only what changed about them: a red check, a conflict, a review waiting, an author who answered | `report`, `propose` |
+| [ci-sweeper](../recipes/ci-sweeper/) | `ci-sweeper` every 15 min, 40-minute timeout | a red default branch reported, or repaired in a worktree and put up as a pull request; the same failure twice unfixed is a stop | `report`, `propose` |
+| [changelog-draft](../recipes/changelog-draft/) | `changelog-draft` weekdays at 18:00 | when the default branch is ahead of the last tag, the changelog entry and a version, drafted — or put in a release pull request | `report`, `propose` |
+| [ecosystem](../recipes/ecosystem/) | `ecosystem` Mondays at 10:00 | who uses or forks this project, and the one reply or upstream invitation worth sending, drafted as a finding a person sends | `propose` |
 
 ## What `/recipe add` does, in order
 
@@ -199,7 +200,52 @@ Specific to this repository: the labels are on
 command is `npm run ci`, and a release needs a one-time password — so the release side can only
 propose, which is what `changelog-draft` does everywhere.
 
-## autoresearch
+## daily-digest
+
+One job at nine, one level. It reads the tracker, the latest run on the default branch, the last
+day's commits, and the automation's own health — a loop that failed its last two runs, a finding
+that has sat in the inbox for three days — and files **one** finding, the day first, then a line
+per thing that needs a look. A quiet day files nothing, and a thing reported yesterday and
+unchanged is not repeated: the notes carry a watermark and yesterday's lines. The loop writes
+nowhere but the inbox.
+
+## pr-watch
+
+Every fifteen minutes, each open pull request gets one state — `green`, `red-check`, `conflict`,
+`awaiting-review`, `changes-requested`, `answered` — and a finding is filed only when a state
+changed since the last run, or a stall has lasted another whole 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,
+once per stall, remembered in its notes. It never merges, approves, rebases or pushes.
+
+## ci-sweeper
+
+Every fifteen minutes, the latest run on the default branch. Green: nothing. Red: a **failure
+signature** (job, step, first error line, normalised) is the memory — under `report` it is one
+finding per signature and one more when the branch is green again; under `propose` the loop
+reproduces it in a worktree, fixes the cause, runs the project's check command and opens a pull
+request, and the same signature attempted twice without a green check is a stop with a finding
+that says so. A test is never skipped or deleted to get to green, and the workflow file is never
+edited to make it pass.
+
+## changelog-draft
+
+Weekdays at six, if the default branch is ahead of the last tag by anything but chores: the
+changelog entry in the project's own style and a version picked the way its history picks them.
+Under `report` the draft is the finding; under `propose` it is also a branch, the entry written
+in, the version bumped, and a pull request whose link leads the finding — a person merges it and
+tags. Tagging and publishing are never the loop's: they need a key, a one-time password and a
+decision.
+
+## ecosystem
+
+Mondays, once. It searches for repositories that use, mention or fork this project, sorts them
+into integrations, derivatives, mentions and noise, and for each integration or derivative looks
+for **one** thing worth a word: a problem they hit that is fixed upstream, a fork commit worth
+bringing back, an unanswered question. Each draft is a finding with the text ready to post;
+claiming the finding is what sends it, as the person, from their chat. The loop itself never
+posts, comments or opens anything anywhere, which is why its only level is `propose`.
+
+## Another tracker
 
 The shape Karpathy's autoresearch and Arbor made familiar, without a kernel: a **research
 contract** a person writes, a **ledger** of every attempt including the failed ones, one isolated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.19.3",
+  "version": "0.20.0",
   "description": "An automation layer for pi: cron + stateful loops with a triage inbox, maker/checker verification, dynamic triggers, MCP notifications and tools, lifecycle hooks, session archives. A non-invasive pi extension.",
   "type": "module",
   "license": "MIT",
@@ -53,6 +53,7 @@
     "check:scripts": "node --check src/web.mjs && node --check src/cli-entry.mjs && node --check src/host-entry.mjs && node --check src/ts-entry.mjs && node --check src/pi-resolver.mjs && node --check src/register-pi.mjs && node --check examples/mcp-notify-server.mjs"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"

package/recipes/changelog-draft/recipe.toml

@@ -1,7 +1,8 @@
 name = "changelog-draft"
 summary = "When the default branch is ahead of the last tag, draft the changelog entry and propose a version; a person tags."
 needs_tracker = false
-levels = ["report"]
+levels = ["report", "propose"]
+budget_hint_usd = 1
 
 [[job]]
 name = "changelog-draft"

package/recipes/changelog-draft/release.md

@@ -7,7 +7,13 @@ description: One run of the release loop. Compares the default branch with the l
 
 Autonomy: report
 
-You are the release loop. You **propose**; a person releases. Tagging and publishing need things
+The line above is the installed level.
+- `report`: the draft goes in the inbox line.
+- `propose`: the draft goes into a pull request too — a branch, the changelog entry written in,
+  the version bumped where the project keeps it — and the inbox line carries the link. A person
+  merges it and tags.
+
+You are the release loop. You propose; a person releases. Tagging and publishing need things
 an unattended run does not have (a signing key, a one-time password, a decision about the version
 number), so the checkpoint is placed here, after everything that can be prepared has been.
 
@@ -28,8 +34,17 @@ number), so the checkpoint is placed here, after everything that can be prepared
    version the way the project's history does (a `feat:` bumps the minor of a 0.x project; only
    fixes bump the patch). Do not edit any file; the draft goes in the inbox line.
 
-4. Report: `release proposal: v<next> — <k> commits since v<last> (<f> feat, <b> fix); draft: <the
-   entry, condensed to one line per change>`. Keep it under 500 characters; if the draft is
-   longer, write it to a comment on a `release` issue instead and link it.
+4. Under `propose`, before reporting: `git worktree add ../<repo>-release/<next> -b release/<next>
+   origin/<default branch>`, write the entry at the top of `CHANGELOG.md` in the project's style,
+   bump the version wherever the project keeps it (`package.json`, and any file the project's own
+   checks tie to it — run those checks), commit `chore: release <next>`, push `-u`, open a pull
+   request whose body starts with a line saying it was generated by AI and lists the commits.
+   If a release pull request of yours is already open for an older head, update its branch
+   instead of opening a second one. Never tag, never publish, never push the default branch.
+
+5. Report: `release proposal: v<next> — <k> commits since v<last> (<f> feat, <b> fix); draft: <the
+   entry, condensed to one line per change>` — under `propose`, `PR <url>` first and the draft
+   after. Keep it under 500 characters; if the draft is longer, the pull request has it whole and
+   the finding says so.
 
-Notes: `last-reported-head=<sha> last-tag=<tag>`.
+Notes: `last-reported-head=<sha> last-tag=<tag> open-pr=<url or none>`.

package/recipes/ci-sweeper/README.md

@@ -0,0 +1,9 @@
+# ci-sweeper — a red default branch, reported or repaired
+
+| file | what it is |
+|---|---|
+| [recipe.toml](recipe.toml) | one job every 15 minutes, 40-minute timeout, `report` or `propose` |
+| [sweep.md](sweep.md) | the playbook: latest run → failure signature → finding, or worktree, fix, checks, pull request |
+
+The failure signature is the memory: the same red reported once, the same failure attempted at
+most twice, and a test never skipped or deleted to get to green.

package/recipes/ci-sweeper/recipe.toml

@@ -0,0 +1,12 @@
+# ci-sweeper: a red default branch gets a finding, or a fix in a worktree and a pull request. docs/recipes.md.
+name = "ci-sweeper"
+summary = "When the default branch's checks go red, says so — or, at propose, reproduces the failure in a worktree, fixes it, and opens the pull request; twice failing to fix the same failure is a stop."
+needs_tracker = false
+levels = ["report", "propose"]
+budget_hint_usd = 5
+
+[[job]]
+name = "ci-sweeper"
+schedule = "*/15 * * * *"
+playbook = "sweep.md"
+timeout = "40m"

package/recipes/ci-sweeper/sweep.md

@@ -0,0 +1,70 @@
+---
+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; needs a person`
+   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,64 @@
+---
+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.** Read `runs.jsonl` and `jobs.json` in the pi-loops directory (the
+   `cron_list` tool lists jobs with `last_error` and `consecutive_failures`): a job that failed on
+   its last two runs is a line, with the error's first sentence. A finding sitting in the inbox
+   for more than three days is a line.
+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,12 @@
+# 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."
+needs_tracker = true
+levels = ["report"]
+budget_hint_usd = 1
+
+[[job]]
+name = "daily-digest"
+schedule = "0 9 * * *"
+playbook = "digest.md"
+timeout = "10m"

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,12 @@
+# 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."
+needs_tracker = true
+levels = ["propose"]
+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>"
+   ```
+
+   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/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,12 @@
+# 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."
+needs_tracker = true
+levels = ["report", "propose"]
+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.