@alphacoder-v0/pi-loops 0.20.0 → 0.22.0

package/docs/recipes.md

@@ -14,17 +14,21 @@ anything a person could not have typed.
 /recipe remove issue-loop  its jobs go; the files stay unless you say --purge
 ```
 
-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` |
-| [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` |
+Eight recipes ship, and the shape is meant to be copied. Three are **starters** — they read, and
+file findings, and are the ones to install first; the rest are **advanced** — they write to a
+worktree, a tracker or a pull request, and want their playbooks read before the level question is
+answered. `/recipe list` shows them in those two groups.
+
+| recipe | tier | jobs | what it runs | levels |
+|---|---|---|---|---|
+| [issue-loop](../recipes/issue-loop/) | advanced | `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/) | advanced | `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` |
+| [daily-digest](../recipes/daily-digest/) | starter | `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/) | starter | `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/) | advanced | `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/) | starter | `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/) | advanced | `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` |
+| [deps-sweeper](../recipes/deps-sweeper/) | advanced | `deps-sweeper` Mondays at 08:00, 40-minute timeout | the advisories and major-version gaps not already in its notes; under `propose`, the patch and minor updates applied in a worktree, checked, and put up as one pull request | `report`, `propose` |
 
 ## What `/recipe add` does, in order
 
@@ -43,28 +47,45 @@ Seven recipes ship, and the shape is meant to be copied:
    `--level act` skips it.
 3. **A name check.** A job with the same name already in `jobs.json` stops the install and says
    which recipe or `/cron add` it came from.
-4. **The confirmation.** Every file that will be written and where, every `/cron add` line that
-   will be run, the budget hint. The setup script is printed into the transcript first, whole and
+4. **The preflight.** What the project has and lacks for this recipe's runs, checked now and
+   printed in the confirmation under *Before the first run* — reported, never enforced, so a
+   missing `gh` login is a line you read tonight rather than an empty inbox tomorrow morning.
+   A manifest names its checks (`needs`, and `needs_propose` for the levels that push and open
+   pull requests); a recipe that reads the tracker is checked for `gh` only when
+   `docs/agents/issue-tracker.md` uses it, so a local Markdown tracker asks for nothing.
+
+   | check | what is looked at |
+   |---|---|
+   | `gh` | `gh` on the PATH and `gh auth status` succeeding (10 seconds, then "could not check") |
+   | `git-remote` | `git remote get-url origin` |
+   | `ci-workflows` | a `.yml` under `.github/workflows/` |
+   | `lockfile` | one of the package managers' lockfiles at the root |
+   | `tracker-github` | the tracker description names GitHub; a local one has no pull requests to watch |
+
+   `/recipe show` runs the same checks at the recipe's highest level.
+5. **The confirmation.** Every file that will be written and where, what the playbooks forbid a
+   run to do (each playbook's `## Never` section, the same lines `/recipe show` prints), every
+   `/cron add` line that will be run, the budget hint, the preflight. The setup script is printed into the transcript first, whole and
    as written — it will run with this session's environment, and a dialog clips what does not fit,
    so it is not put in one; a script too long to show is not run at all. A recipe installed from a path
    rather than by name is flagged as not shipped with pi-loops, with the playbooks to read first.
    Nothing has happened yet.
-5. **The install.** The playbooks are copied to `.agents/skills/<recipe>/`, with an untouched copy of each
+6. **The install.** The playbooks are copied to `.agents/skills/<recipe>/`, with an untouched copy of each
    under `.orig/` and a `.recipe.json` record (version, level, when). The directory (and the
    tracker description) is listed in `.git/info/exclude` — git's own place for a rule that belongs to one clone — so the repository
    is not touched and nothing shows in `git status`. pi discovers the copies as `/skill:` commands,
    which is how a person runs one step by hand when the loop's judgement needs checking — once the
    project is trusted: a directory that gains `.agents/skills/` is one pi asks about at its next
    start (`/trust`). The loops do not depend on that; they read the files by path.
-6. **The setup script**, if any, runs once in the project (issue-loop's creates the tracker's
+7. **The setup script**, if any, runs once in the project (issue-loop's creates the tracker's
    labels; it is idempotent). A failure stops before any job is created and prints the output; the
    files stay in place and `/recipe add` again resumes.
-7. **The jobs**, through the same code path as `/cron add`, each carrying `recipe: "<name>"` so
+8. **The jobs**, through the same code path as `/cron add`, each carrying `recipe: "<name>"` so
    `/recipe list` and `/recipe remove` can find them. Each prompt is a pointer:
    `Read .agents/skills/issue-loop/triage.md and do what it says for this repository.` The
    procedure is read fresh on every run; edit the file and the next run follows the edit.
 
-`pi-loops recipe list|show|add` in a shell does steps 5 and nothing after: the setup script and the
+`pi-loops recipe list|show|add` in a shell does step 6 and nothing after: the setup script and the
 jobs are things a person should see before they exist, and only the pi inside `/recipe add` can show
 them. It leaves the files in place and says so; `/recipe add` then finds nothing to copy.
 
@@ -85,6 +106,29 @@ were there before recipes: the [dangerous-command policy](loops.md#when-somethin
 night ([loops.md](loops.md#what-it-costs-and-capping-it)); each recipe's `show` says roughly what
 its default schedules cost.
 
+## Checkpoints
+
+A checkpoint is a finding that asks a person to decide, and at three in the morning it is read by
+someone who has not seen the tracker since yesterday. So every one of them, in every packaged
+playbook, says the same three things in one line: **the decision**, **what waits on it**, and
+**what happens if nobody acts**.
+
+```text
+#14 brief posted — recommend ready-for-agent (bug, reproduced by npm test) · waits: the implement loop skips it until labeled · if not: stays needs-triage, no reminder
+promote research/007-argpartition: dev 1.0 → 3.1, held-out 1.0 → 2.8 · waits: your merge · if not: the branch and worktree stay, later runs build on it as the best kept
+CI red on main: test/web.test.ts — two fixes did not hold · waits: a person · if not: this signature is not retried
+```
+
+The shape is also how the inbox tells a checkpoint from news: ` · waits:` marks the entry, it is
+listed first with a `⚑`, and `/inbox` counts it apart (`3 new, 1 needs a decision`;
+[loops.md](loops.md#the-inbox)).
+
+The third clause is the one that matters overnight. A loop that waits for an answer says so and
+keeps going with everything the answer does not block; a loop that would do something on silence
+(retry, re-propose when the head moves, keep building on a kept branch) says that instead, so a
+person who decides to do nothing knows what nothing buys. Findings that are only news — a merged
+pull request, a red check, a digest line — are not checkpoints and do not carry the clauses.
+
 ## Editing, updating, removing
 
 The copies are yours. `/recipe update <name>` after a pi-loops upgrade is a three-way merge of the
@@ -109,7 +153,11 @@ and should be read before it is installed).
 ```toml
 name = "issue-loop"                 # lowercase, digits, dashes; also the install directory
 summary = "one line"
+tier = "advanced"                   # optional; "starter" reads and files findings, "advanced" (the default) writes somewhere
+useful_when = ["one sentence"]      # optional; the situations it is for, printed by `show`
 needs_tracker = true                # gate on docs/agents/issue-tracker.md
+needs = ["gh", "ci-workflows"]      # optional; preflight checks at every level (gh, git-remote, ci-workflows, lockfile, tracker-github)
+needs_propose = ["git-remote"]      # optional; the same, added at propose and act
 levels = ["propose", "act"]         # which positions of the dial the playbooks understand
 setup = "labels.sh"                 # optional; shown, then run once, before the jobs exist
 files = ["RESEARCH.template.md"]    # optional; copied beside the playbooks unchanged
@@ -127,7 +175,9 @@ same parser: a bad schedule, a `--timeout` that is not a duration, an expression
 matches, is refused when the manifest is read, not on the first run. A playbook is Markdown with
 pi's skill frontmatter (`name`, `description`) and an `Autonomy:` line the wizard will set; the
 rest is what a run should do, written for a sub-agent that has only its notes, the files, and the
-tools. The two packaged recipes are the reference for the voice.
+tools. End it with a `## Never` section: the lines under it are what `/recipe show` and the
+install confirmation print as the run's safety envelope, and every packaged playbook has one. The
+packaged recipes are the reference for the voice.
 
 ---
 
@@ -195,6 +245,14 @@ mid-implementation resumes from its branch and notes; a check command failing tw
 is a block, not a third attempt; the loop and you editing the same issue is settled by the
 tracker, which wins.
 
+With the local Markdown tracker the shape is the same and the pull request is not there: the
+implement loop pushes its branch (or leaves it local), sets the item to `in-review` and files a
+finding naming the branch. Requesting changes is a comment under the item's `## Comments` and the
+status set back to `agent-working`; merging is `git merge` by a person, the status set to `done`
+and the file moved to `closed/`. The setup script creates no labels there — it says so and exits —
+and does the same when `gh` is missing or not logged in, so the install goes through and the
+first run reports what it cannot do.
+
 Specific to this repository: the labels are on
 [github.com/alphacoder-v0/pi-loops](https://github.com/alphacoder-v0/pi-loops/labels), the check
 command is `npm run ci`, and a release needs a one-time password — so the release side can only
@@ -245,6 +303,19 @@ bringing back, an unanswered question. Each draft is a finding with the text rea
 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`.
 
+## deps-sweeper
+
+Mondays at eight. The loop finds the project's package manager from its lockfile and runs the
+audit and outdated commands that manager has. The **advisory id** and the **package at a major
+version** are the memory: under `report` each advisory not in the notes is one finding, each direct
+dependency a whole major behind is one finding once, and a finding is repeated only when it
+changes — an advisory fixed, a major that moved again. Under `propose` the loop also applies the
+patch and minor updates the manager offers, in a worktree, as **one** pull request per run: the
+project's check command has to be green first, a package on the playbook's deny list is never
+touched, a major is never applied (it is a finding, and a person's decision), and the same package
+attempted twice without a green check is a stop with a finding that says so. The lockfile is
+only ever written by the package manager, never by hand. Merging stays with a person at every level.
+
 ## Another tracker
 
 The shape Karpathy's autoresearch and Arbor made familiar, without a kernel: a **research
@@ -267,6 +338,11 @@ was tuning against.
   better: `retired`, worktree removed, branch deleted, no finding — a retired experiment is the
   normal outcome and the row is what matters. Better on dev: measure on held-out; a dev-only gain
   is `retired` too, with that note.
+- **A streak of retired rows is the ledger's own checkpoint.** Five in a row since the last kept
+  row files one finding asking whether the contract's directions, metric or budget are wrong, and
+  the loop keeps going only in idea classes it has not tried; ten in a row stops the loop until
+  `RESEARCH.md` changes (its hash is in the notes). An hourly loop in the wrong search space is the
+  expensive failure, and the person who wrote the contract is the one who can fix it.
 - **Promotion** is the checkpoint. Under `propose` the finding names the branch and both numbers
   and a person merges; under `act` the loop merges into the checkout's current branch and the
   finding says so. The job runs with `--verify`, and the playbook's *For the checker* section tells

package/docs/session-archive.md

@@ -15,7 +15,7 @@ pi-session-<first 16 chars of the id>.pisession   uncompressed ustar, mode 0600,
 
 ```text
 /session-export [path] [--exclude-triggers]
-/session-import <path> [--activate-triggers=on|off] [--cwd <dir>] [--resume]
+/session-import <path> [--activate-triggers=off|ask|on] [--cwd <dir>] [--resume]
 ```
 
 Both commands print a sensitivity warning before doing anything, success or failure.
@@ -24,8 +24,13 @@ the source machine's parent-session pointer dropped)
 into this project's session directory and rewrites the sidecars: automation disabled
 unless `--activate-triggers=on`, running markers / errors / overlap counters cleared, ids
 regenerated when they collide with existing ones (loop state follows the new id), non-stateful jobs
-rebound to the imported session. Afterwards you are asked once whether to re-enable what was
-enabled in the source. `--resume` switches to the imported session; otherwise `pi --session <path>`.
+rebound to the imported session. `--resume` switches to the imported session; otherwise
+`pi --session <path>`.
+
+`--activate-triggers=off|ask|on` decides what happens to the automation the archive carries, and
+means the same thing here as in `pi-loops import`. The default is `ask`: the import leaves it
+disabled and then asks once, where there is a terminal or a UI to ask in, whether to enable what
+was enabled in the source. `off` never asks; `on` activates it as part of the import.
 
 Validation: manifest schema, session checksum, path traversal, and size caps (session 50 MiB,
 sidecars 2 MiB). Every sidecar is validated before the session file is written, and store writes

package/docs/web-ui-parity.md

@@ -17,7 +17,9 @@ weaker, and worth converting whenever one of them breaks.
 - [x] Enter does nothing while an input method is composing — typing Chinese, Japanese or Korean
       means Enter picks a candidate, not "send". `test/web-page.test.ts`: *Enter while an input
       method is mid-word does not send*.
-- [x] Submitting while a turn is running queues instead of racing it, the way the TUI does.
+- [x] Submitting while a turn is running queues instead of racing it, the way the TUI does — and a
+      slash command typed into it runs while the turn runs, as it does in the terminal.
+      `test/web.test.ts`: *a command typed while a turn is running reaches pi as one it can run*.
 - [x] The queue is visible and can be cleared.
 - [x] Abort stops the current turn.
 - [x] Busy, queued count, and "pi exited" are all visible without opening a terminal.
@@ -49,6 +51,14 @@ weaker, and worth converting whenever one of them breaks.
 - [x] A tap on a composer button lands on that button, even with a soft keyboard open — tapping it
       blurs the box, which dismisses the keyboard, which moves everything.
       `test/web-page.test.ts`: *a phone's soft keyboard cannot steal the tap on send*.
+- [x] What is in the composer survives a reload, and belongs to the tab that typed it: the header's
+      reload button, the stale-page banner and a phone that discards a backgrounded tab all come
+      back to the same text, and a second tab of the same address keeps its own.
+      `test/web-page.test.ts`: *a reload keeps what is in the composer, in that tab only*.
+- [x] The composer grows with what is typed into it, up to the ceiling the stylesheet declares, and
+      comes back down when the text goes or is sent — a multi-line prompt is written and read at its
+      own height rather than through a one-line slot. `test/web-page.test.ts`: *the composer grows
+      with a multi-line prompt, and shrinks again*.
 
 ## What the feed shows
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.20.0",
+  "version": "0.22.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",
@@ -35,6 +35,7 @@
     "recipes",
     "README.md",
     "README.zh-CN.md",
+    "CONTRACT.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
@@ -45,10 +46,12 @@
     "publishedToNpm": true
   },
   "scripts": {
-    "ci": "npm run typecheck && npm run lint && npm run check:scripts && npm run check:docs && npm test",
+    "ci": "npm run typecheck && npm run lint && npm run check:scripts && npm run check:docs && npm test && npm run check:downstream && npm run check:contract",
     "typecheck": "node scripts/typecheck.mjs",
     "lint": "node scripts/lint.mjs",
     "check:docs": "node scripts/check-docs.mjs",
+    "check:downstream": "sh test/downstream/run.sh",
+    "check:contract": "sh test/contract/run.sh",
     "test": "node --import ./src/register-pi.mjs --test test/*.test.ts",
     "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"
   },

package/recipes/_tracker/issue-tracker-local.md

@@ -29,7 +29,9 @@ checkpoint is a finding in the inbox that names the branch.
 - **Change state**: edit the `**Status:**` line — exactly one state
 - **Claim**: set `**Status:** agent-working` and add `**Assignee:** <who>`, and commit that edit on the work branch before any other work
 - **Close**: set the status to `wontfix` or `done` and move the file to `.scratch/issues/closed/`
-- **Review**: push the branch (or leave it local) and file a finding that names the branch and the item; a person merges with git
+- **Review**: push the branch (or leave it local), set `**Status:** in-review`, and file a finding that names the branch and the item — `in-review` here means the branch exists and the finding has been filed; there is no pull request
+- **Request changes** (a person): append a comment under `## Comments` saying what to change and set `**Status:** agent-working`; the implement loop reads comments newer than the timestamp in its notes and addresses them
+- **Merge** (a person): merge the branch with git, set `**Status:** done`, and move the file to `closed/`; the loop's housekeeping removes the worktree on its next run
 
 ## State vocabulary
 

package/recipes/autoresearch/experiment.md

@@ -42,6 +42,20 @@ before anything slow. Your final reply is read by a program.
    trying first" and "not to try" lists bound the space. Write one sentence: what you will change
    and why it should move the metric. Append the row now with status `running` — a crash leaves a
    record, not a mystery.
+
+   **First, look back.** Count the `retired` rows since the last `kept` or `promoted` one (or the
+   baseline). A streak is the ledger telling you the space is wrong, not that the next idea is:
+   - **5 in a row**, and you have not said so since the streak began (your notes' `stalled-at`):
+     one finding — `autoresearch: 5 retired in a row (<the idea classes tried>) · waits: a
+     change to RESEARCH.md's directions, metric or budget · if not: I keep trying, but only in
+     classes not yet tried` — and choose this run's hypothesis outside every class in your notes'
+     `tried` line.
+   - **10 in a row**: stop choosing. One finding — `autoresearch: 10 retired in a row, stopping
+     until RESEARCH.md changes · waits: an edit to the contract · if not: nothing runs; the ledger
+     is at <path>` — write the notes with the contract's hash, and end the run. A later run whose
+     `RESEARCH.md` hash differs from the notes' starts the count again at zero; one whose hash is
+     the same files nothing and stops again.
+   A `kept` or `promoted` row resets the streak.
 6. **Branch.** `git worktree add <worktrees>/<NNN> -b research/<NNN>-<slug> <current branch>`
    (create the worktrees directory first if it is missing).
    Change only the editable files. Commit in the worktree before measuring.
@@ -53,7 +67,8 @@ before anything slow. Your final reply is read by a program.
      contract's promotion rule → status `kept` and go to 8; otherwise `retired` with note
      `dev-only gain` (the classic overfit; still negative evidence) and remove the worktree.
 8. **Promote.** Under `propose`: one finding —
-   `promote research/<NNN>-<slug>: dev <x> → <y>, held-out <a> → <b> (<hypothesis>)` — and leave
+   `promote research/<NNN>-<slug>: dev <x> → <y>, held-out <a> → <b> (<hypothesis>) · waits: your
+   merge · if not: branch and worktree stay; later runs build on it as the best kept` — and leave
    the worktree and branch for the person. Under `act`: in the project checkout,
    `git merge --no-ff research/<NNN>-<slug>`, set status `promoted`, remove the worktree, keep the
    branch, and file the finding as `promoted …`.
@@ -68,15 +83,24 @@ A second sub-agent reviews the findings of this run before they reach the inbox.
 or `promoted` finding: check out the named branch in its worktree (or the merge in the checkout),
 run the contract's **held-out** command yourself, and keep the finding only if the number you get
 satisfies the promotion rule against the ledger's best row; drop it with the number otherwise. A
-`no RESEARCH.md` or protected-file finding is kept if the file state is as described.
+`no RESEARCH.md` or protected-file finding is kept if the file state is as described; a `retired
+in a row` finding is kept if the ledger shows the streak it names.
 
 ## Notes for the next run
 
 `best=<id> <heldout>` · `next=<NNN>` · `in-progress: <id> worktree=<path>` or `none` ·
-`tried: <one line per idea class you have exhausted>`. Under 2000 characters; the ledger holds
-the rest.
+`tried: <one line per idea class you have exhausted>` · `stalled-at=<row id the 5-streak finding
+was filed at, or none>` · `contract=<sha256 of RESEARCH.md>`. Under 2000 characters; the ledger
+holds the rest.
 
 ## Inbox
 
-Only: a promotion (proposed or done), a contract problem, an eval that cannot run. Never a retired
-experiment — the ledger is where those live, and a person reads the ledger when they want to.
+Only: a promotion (proposed or done), a contract problem, an eval that cannot run, a streak of
+retired experiments long enough to question the contract. Never a single retired experiment — the
+ledger is where those live, and a person reads the ledger when they want to.
+
+## Never
+
+Never write the contract (`RESEARCH.md`) yourself, never edit a protected file. Never push; never
+merge under `propose`; never run two experiments in one run. Never retry an eval that failed for
+a reason that is not your change — that is one finding and a stop.

package/recipes/autoresearch/recipe.toml

@@ -2,6 +2,8 @@
 # a ledger, a checker re-measures on held-out data before anything is proposed. docs/recipes.md.
 name = "autoresearch"
 summary = "One experiment per run against a research contract you wrote; a ledger of what was tried; promotion only on held-out evidence."
+tier = "advanced"
+useful_when = ["You have a metric a script can print and a search space wider than your evenings.", "You want every attempt in a ledger, the failed ones included."]
 needs_tracker = false
 levels = ["propose", "act"]
 files = ["RESEARCH.template.md", "example/RESEARCH.md", "example/solution.py", "example/eval.py", "example/eval.sh"]

package/recipes/changelog-draft/recipe.toml

@@ -1,7 +1,11 @@
 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."
+tier = "starter"
+useful_when = ["Releases wait on someone finding an evening to write the entry.", "You want the version and the entry proposed from the commits, and to tag it yourself."]
 needs_tracker = false
 levels = ["report", "propose"]
+needs = ["git-remote"]
+needs_propose = ["gh"]
 budget_hint_usd = 1
 
 [[job]]

package/recipes/changelog-draft/release.md

@@ -43,8 +43,13 @@ number), so the checkpoint is placed here, after everything that can be prepared
    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.
+   entry, condensed to one line per change> · waits: your tag · if not: re-proposed when the head
+   moves, not before` — 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> open-pr=<url or none>`.
+
+## Never
+
+Never tag, never publish, never push the default branch. Never open a second release pull
+request while one of yours is open — update its branch instead.

package/recipes/ci-sweeper/recipe.toml

@@ -1,8 +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."
+tier = "advanced"
+useful_when = ["The default branch goes red and every open pull request looks red with it.", "The failures are the boring kind: a flaky assertion, a renamed fixture, a dependency that moved."]
 needs_tracker = false
 levels = ["report", "propose"]
+needs = ["gh", "ci-workflows"]
+needs_propose = ["git-remote"]
 budget_hint_usd = 5
 
 [[job]]

package/recipes/ci-sweeper/sweep.md

@@ -39,7 +39,8 @@ the branch is green, which is most runs: then you write your notes and stop.
    <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`
+   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);

package/recipes/daily-digest/digest.md

@@ -33,10 +33,11 @@ already reported, so a thing you reported yesterday and that has not changed is
    "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.
+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.)
 

package/recipes/daily-digest/recipe.toml

@@ -1,6 +1,8 @@
 # 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

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/recipe.toml

@@ -1,8 +1,11 @@
 # 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]]

package/recipes/ecosystem/scan.md

@@ -39,7 +39,7 @@ It names this repository; the searches below take that name.
 4. **Findings**, one per draft, under 500 characters:
 
    ```
-   ecosystem: <repo> — <what they did/hit>; draft reply for <url>: "<the text, ready to post>"
+   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,