@alphacoder-v0/pi-loops 0.17.6 → 0.18.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 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.18.0] - 2026-09-14
+
+### Added
+- **Recipes: a project run on loops, installed in one command.** A recipe is a directory —
+  `recipe.toml`, one playbook per job, an optional setup script — and `/recipe add <name>` installs
+  it into the open project: one question (the autonomy level, `report` / `propose` / `act`, written
+  as the first line of each playbook), one confirmation showing every file, the setup script and
+  every `/cron add` line, then the jobs through the same code path `/cron add` uses. The playbooks
+  are copied to `.agents/skills/<name>/` — where pi also discovers them as `/skill:` commands — and
+  the directory is listed in `.git/info/exclude`, so the repository is untouched; a job's prompt is
+  a pointer to its playbook, read fresh on every run, so editing the file changes the next run.
+  `/recipe update` is a three-way merge against the untouched copy kept at install (under `.orig/`), and a conflict
+  is handed to the agent to resolve with you rather than left as markers in a file a loop would
+  follow. `/recipe remove` takes the jobs and leaves the files unless `--purge`. Each `[[job]]` in a
+  manifest is validated by building the `/cron add` line it stands for and parsing it with the same
+  parser. The one step no template can do — describing this project's tracker — is handed to the
+  session with the prompt in `recipes/_tracker-setup.md`, the way `/inbox claim` hands over a
+  finding, written to `docs/agents/issue-tracker.md` in the layout Matt Pocock's engineering
+  skills use and excluded from the repository like the playbooks — and the wizard resumes on its
+  own once that turn ends with the file in place. `pi-loops recipe list|show|add` in a shell does the deterministic part and stops
+  before the setup script and the jobs. `docs/recipes.md`; vocabulary in `CONTEXT.md`, decisions in
+  `docs/design.md` §15–18.
+- **Two recipes.** `issue-loop`: the tracker as a state machine (Matt Pocock's five triage states
+  plus `agent-working`, `in-review`, `agent-blocked`) that two loops turn, a triage loop that
+  reproduces, checks `.out-of-scope/` and writes agent briefs, and an implement loop that claims
+  one issue per run, builds it in a worktree and opens the pull request; a person promotes and
+  merges. `autoresearch`: one experiment per run against a `RESEARCH.md` contract you wrote, a
+  `results.tsv` ledger where retired ideas stay as negative evidence, a worktree per experiment,
+  and promotion only when the `--verify` checker has re-run the held-out command itself; with a
+  pure-Python exact k-NN example whose baseline is a speedup of 1.0. `changelog-draft` is packaged
+  as the release-side half of the issue loop.
+
+### Fixed
+- **The browser front end reported a slash command as timed out while it waited in a dialog.** A
+  `/…` prompt is answered by pi when the command has finished, and a command that shows a setup
+  script and asks for a yes finishes when the person answers; sixty seconds later the feed said
+  `timed out after 60000ms` and the install went on to succeed. A slash command now gets fifteen
+  minutes; everything else keeps sixty seconds.
+
 ## [0.17.6] - 2026-09-14
 
 ### Added

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.17.6    # or from GitHub, at a pinned tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.18.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,6 +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)).
+
 Two that are not loops:
 
 ```text
@@ -289,6 +294,7 @@ State stays in `~/.pi/agent/loops` until you delete it.
 | `/triggers panel [on\|off]` | The same panel, toggled from the trigger side |
 | `/session-export [path]`, `/session-import <path>` | Portable `.pisession` archive: transcript + jobs + rules + loop state |
 | `/session-share [--public]` | Upload a redacted transcript as a GitHub gist via `gh`, after showing you what it contains. (pi has its own `/share`, which sends the raw session elsewhere first — see [docs/session-archive.md](docs/session-archive.md)) |
+| `/recipe [list\|show\|add\|update\|remove <name>]` | Install a packaged way of running this project on loops — the issue tracker as a state machine, or one research experiment per run — with one question and one confirmation ([docs/recipes.md](docs/recipes.md)) |
 | `/pi-loops [install-launcher]` | Version and paths; `install-launcher` puts the `pi-loops` command on your `PATH` |
 
 A schedule is a 5-field cron expression, or one of `hourly` / `daily` / `weekly` (also `每天`), or
@@ -317,6 +323,7 @@ notifications, and lifecycle hooks — each has a page here.
 - [docs/mcp.md](docs/mcp.md) — MCP notification sources and tool registration (`mcp.toml`)
 - [docs/hooks.md](docs/hooks.md) — lifecycle hooks (`hooks.toml`), including `run_start` / `run_end` for scheduled runs
 - [docs/goal.md](docs/goal.md) — `/goal`: holding a session to a stop condition
+- [docs/recipes.md](docs/recipes.md) — `/recipe`: a project run on loops, installed in one command; the issue loop and autoresearch, and how to write your own
 - [docs/session-archive.md](docs/session-archive.md) — `/session-export`, `/session-import`
 - [docs/cli.md](docs/cli.md) — the `pi-loops` command line: export, import, and looking in on the host
 - [docs/web-ui-parity.md](docs/web-ui-parity.md) — what the browser front end owes you, line by line

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.17.6    # 或者从 GitHub 装，钉住一个 tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.18.0    # 或者从 GitHub 装，钉住一个 tag
 pi install /path/to/pi-loops                                # 或者本地检出；本仓库里就是 pi install .
 ```
 
@@ -215,6 +215,19 @@ pi update --extensions                             # 对齐已安装的包
 
 任务在创建时就记下自己的目录和模型，所以它不绑在敲出它的那个窗口上。`--cwd` 让它在另一个检出里跑——绝对路径，或相对当前项目；这里没有 shell，`~` 不会展开。`--model` 把模型钉死，`/cron set <ref> --model -` 解钉。
 
+### 不用自己写的：recipe
+
+```text
+/recipe                    有哪些打包好的 recipe，这个项目装了哪些
+/recipe add issue-loop     把 issue tracker 跑成状态机：分诊成 agent brief、在 worktree 里实现、开 PR；推进和合并留给人
+/recipe add autoresearch   按你写的研究合同每次跑一个实验，账本记下每次尝试，只凭 held-out 数据提议晋升
+```
+
+一个 recipe 是一组 loop 加上它们各自每次 run 都会读的 playbook。安装只问一个问题（自治级别
+`report` / `propose` / `act`）、确认一次（每个要写的文件、setup 脚本全文、每一行 `/cron add`），
+playbook 拷到 `.agents/skills/<name>/`，通过 `.git/info/exclude` 排除在仓库之外——你随时可以改它，
+下一次 run 就照改后的做。见 [docs/recipes.md](docs/recipes.md)。
+
 ## 用法
 
 会话里的命令分几摊：`/cron` 管任务，`/inbox` 管分诊，`/goal` 管「做到什么算完」，`/triggers` 管不看钟的那些规则，`/session-share` 把这次会话脱敏后发出去。

package/docs/agents/issue-tracker.md

@@ -0,0 +1,34 @@
+# Issue tracker: GitHub
+
+Work items for this repository live as GitHub Issues in `alphacoder-v0/pi-loops`; pull requests
+are the review surface. Use the `gh` CLI for every operation; it infers the repository from the
+remote when run in a clone. Loops shell out to `gh`, so the account must be authenticated in the
+environment a loop runs in — `gh auth status` answers that.
+
+## Operations
+
+- **List**: `gh issue list --state open --limit 200 --json number,title,labels,updatedAt,author` (add `--label <state>` to filter by state)
+- **Read**: `gh issue view <n> --comments --json number,title,body,labels,author,createdAt,comments`
+- **Comment**: `gh issue comment <n> --body "..."` (a heredoc for multi-line bodies)
+- **Change state**: `gh issue edit <n> --add-label "<new state>" --remove-label "<old state>"` — exactly one state label at a time
+- **Claim**: `gh issue edit <n> --add-label agent-working --remove-label ready-for-agent --add-assignee @me`
+- **Close**: `gh issue close <n> --comment "..."`
+- **Pull requests**: `gh pr create`, `gh pr list --state open --json number,url,headRefName,reviewDecision,comments,updatedAt`, `gh pr view <n> --comments`, `gh pr diff <n>`
+
+## State vocabulary
+
+One category label (`bug` | `enhancement`) and exactly one state label per open issue. The state
+labels are `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `agent-working`,
+`in-review`, `agent-blocked`, `wontfix`. They already exist in this repository; `labels.sh`
+refreshes their colour and description and touches no issue. A playbook that moves an issue names
+the label it moves to.
+
+## Blocking
+
+A `Blocked by: #<n>, #<m>` line near the top of an issue body (or the tracker's native
+dependency) gates it: the item is unblocked when every listed issue is closed.
+
+## Who counts as the agent
+
+Comments and assignments made by loops are made as the account `gh` is signed in as — currently
+`alphacoder-v0`. Every comment a loop posts starts with a line saying it was generated by AI.

package/docs/cli.md

@@ -260,3 +260,19 @@ accepted). `host stop` ends the host; the next pi to open would have taken the c
 
 The channel is a unix socket at `host.sock` in the loops directory, created 0600, and it is
 read-mostly on purpose: a host you could prompt would be a second chat.
+
+## recipe
+
+```sh
+pi-loops recipe list                       # the packaged recipes, and which are installed in this directory
+pi-loops recipe show issue-loop            # its files, jobs, levels, setup script
+pi-loops recipe add issue-loop [--cwd <dir>] [--level report|propose|act] [--overwrite]
+```
+
+`add` is the deterministic half of `/recipe add` ([recipes.md](recipes.md)): it copies the
+playbooks to `.agents/skills/<name>/`, lists that directory in `.git/info/exclude` and writes the
+record — and stops. The setup script and the jobs need a pi open in the project: `/recipe add
+<name>` there finds the copies in place, shows the script and the `/cron add` lines, and creates
+them after you say yes. Without `--level` the lowest level the recipe supports is written; an edited
+copy is kept unless `--overwrite` says otherwise.
+

package/docs/design.md

@@ -117,6 +117,49 @@ machine. Everything here follows from that, and each one has a price.
     failed — the slot is still owed and the failure streak does not advance. Diagnostics go to
     `logs/pi-<pid>.log` rather than only to a chat notification that a new session erases.
 
+15. **Recipes are files, not code.** A recipe (`CONTEXT.md` has the vocabulary) is a directory:
+    a `recipe.toml` manifest whose `[[job]]` fields are the arguments of `/cron add` and nothing
+    else, one playbook per job, an optional setup script. Anything the wizard does with one is
+    something a person could have done by hand with `/cron add` and `cp`. The first catalogue is
+    seven: issue-loop, daily-digest, changelog-draft, pr-watch, ci-sweeper, autoresearch, and
+    ecosystem — the last capped at `propose`, because every outward word it drafts is a finding a
+    person claims before it is said.
+
+    The cost: a project cannot add a recipe by writing TypeScript, only by writing a directory,
+    and the wizard can only ask what a manifest can declare.
+
+16. **Playbooks are copied into the project and kept out of its history.** `/recipe add` copies
+    them to `<project>/.agents/skills/<recipe>/` — where pi also discovers them as `/skill:`
+    commands, so a person can run one step by hand — and lists the directory in
+    `.git/info/exclude`, so the repository is not touched. A loop's prompt is a pointer to that
+    file; the procedure is read fresh on every run. The tracker description the playbooks read
+    (`docs/agents/issue-tracker.md`, in the layout Matt Pocock's engineering skills use, so a
+    repository that has those reads the same file) is excluded the same way: it names an account
+    and a workflow, which are the project's to keep and not the repository's to publish.
+
+    The cost: two clones of one project each install the recipe, and a playbook edited on one
+    machine is not on the other. Upgrading pi-loops upgrades the packaged recipes, not the copies:
+    `/recipe update` is a three-way merge against the untouched copy kept at install (under
+    `.orig/` beside the playbooks), silent when the person changed nothing, and conflicts are handed to the
+    session as a prompt to resolve with the person rather than left as markers in a file the next
+    run will read.
+
+17. **The wizard is deterministic; one step is not.** Choosing a recipe, its autonomy level, the
+    copy and the `/cron add` lines run with no model and end in a confirmation that shows exactly
+    what will be created. The one thing a template cannot do — describe *this* project's tracker —
+    is handed to the running session with `sendUserMessage`, the way `/inbox claim` hands over a
+    finding: explore the remote, propose, confirm, write the file — and when that turn settles with
+    the file there, the wizard resumes by itself, so the command is typed once. `pi-loops recipe`
+    in the terminal does the deterministic part only.
+
+18. **One autonomy dial, three positions, in prose.** `report` reads and files findings; `propose`
+    may also write to the tracker and open draft pull requests but never reach a terminal state;
+    `act` may. A manifest declares which positions a recipe supports, the wizard defaults to the
+    lowest, and the chosen one is a line at the top of each playbook — text the model reads and a
+    person edits, enforced by nothing in code. The cost is exactly that: the level is an instruction,
+    not a permission, and the permissions that exist (the danger policy, the daily budget, branch
+    protection on the remote) are the ones that hold.
+
 ## Where the browser front end came from
 
 pi owns the `pi` command and its terminal, so a second front end cannot replace the first one. It

package/docs/recipes.md

@@ -0,0 +1,239 @@
+# Recipes: a project run on loops, installed in one command
+
+A **recipe** is a packaged way of running a project on loops: one or more jobs, the **playbook**
+each of them reads on every run, a **manifest** that says what to create, and sometimes a setup
+script. `/recipe add <name>` installs one into the project you have open; what you get is exactly
+what you could have made by hand with `cp` and `/cron add`, which is the point — a recipe cannot do
+anything a person could not have typed.
+
+```text
+/recipe                    what is packaged, and what is installed here
+/recipe show issue-loop    the files, the jobs, the levels, the setup script
+/recipe add issue-loop     install it: a question, a confirmation, done
+/recipe update issue-loop  merge a newer pi-loops' playbooks into your copies
+/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:
+
+| 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.
+
+## What `/recipe add` does, in order
+
+1. **Tracker first, if the recipe needs one.** issue-loop reads `docs/agents/issue-tracker.md` on
+   every run to learn where the project's work items live — GitHub Issues, or one Markdown file
+   per item under `.scratch/issues/` — and how to list, comment, label and close them. If the file
+   is missing, the wizard hands that one step to the agent in your chat (the way `/inbox claim`
+   hands over a finding): it looks at the remote, proposes, writes the file after you agree — and
+   the moment that turn ends with the file in place, the wizard resumes on its own with the
+   question below. Everything else is done without a model. The file's layout
+   is the one Matt Pocock's engineering skills use, so a repository that has `/triage` reads the
+   same description. Like the playbooks it is kept out of the repository through
+   `.git/info/exclude`: it names an account and a workflow, which are the project's to keep and
+   not the repository's to publish. Another clone is asked the same questions once.
+2. **The autonomy level.** One question, defaulting to the lowest the recipe supports (below).
+   `--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
+   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
+   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
+   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
+   `/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
+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.
+
+## The autonomy level
+
+One dial with three positions, declared per recipe in its manifest and written as the first line
+of each playbook — `Autonomy: propose` — where the model reads it and a person can change it:
+
+| level | may |
+|---|---|
+| `report` | read, and file findings; nothing is written outside the inbox |
+| `propose` | also write to the tracker (comments, non-terminal labels) and open draft pull requests; never reach a terminal state |
+| `act` | also promote, close and merge — the terminal states |
+
+It is an instruction, not a permission. What actually holds an unattended run are the things that
+were there before recipes: the [dangerous-command policy](loops.md#when-something-looks-wrong),
+`[limits] daily_budget_usd`, and branch protection on the remote. Set the budget before the first
+night ([loops.md](loops.md#what-it-costs-and-capping-it)); each recipe's `show` says roughly what
+its default schedules cost.
+
+## Editing, updating, removing
+
+The copies are yours. `/recipe update <name>` after a pi-loops upgrade is a three-way merge of the
+packaged playbook against your copy with the untouched copy in `.orig/` as the base: files you never touched are
+replaced silently, your edits are kept where they do not overlap the upstream change, and a file
+with overlapping edits is **not written** — git's merge with markers goes to `.orig/<file>.merge`,
+and the agent in your chat is handed the four paths (yours, the base, the packaged version, the
+merge) to resolve with you, because conflict markers in a playbook are text the next run would follow.
+A playbook installed by hand, with no untouched copy, is left alone and named.
+
+`/recipe remove <name>` removes the recipe's jobs and keeps the files and the loops' notes;
+`--purge` deletes both — of the files, only what the install wrote, since `.agents/skills/` may
+hold the project's own. `/cron` shows recipe jobs like any other, and `/cron set` edits them like
+any other — a recipe is how they were made, not what they are.
+
+## Writing a recipe
+
+A directory with a `recipe.toml`; `/recipe add ./path/to/it` installs from a directory as readily
+as from the packaged set (no git URLs: a playbook is an instruction a model will follow unattended,
+and should be read before it is installed).
+
+```toml
+name = "issue-loop"                 # lowercase, digits, dashes; also the install directory
+summary = "one line"
+needs_tracker = true                # gate on docs/agents/issue-tracker.md
+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
+budget_hint_usd = 10                # optional; only a hint in `show` and the confirmation
+
+[[job]]
+name = "issue-triage"               # the /cron add --name
+schedule = "*/30 * * * *"           # anything /cron add takes, except in/at (a recipe job recurs)
+playbook = "triage.md"              # the file this job's runs read
+timeout = "45m"                     # optional: verify, timeout, thinking, tools, prompt
+```
+
+Each `[[job]]` is checked by building the `/cron add` line it stands for and parsing it with the
+same parser: a bad schedule, a `--timeout` that is not a duration, an expression that never
+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.
+
+---
+
+## issue-loop
+
+The tracker becomes a state machine that two loops turn, with the two decisions that need a person
+— *is this worth building?* and *is this worth merging?* — left in the inbox with everything
+prepared. The state machine is Matt Pocock's `triage` skill's (five states, one category, a brief
+that outlives the codebase it describes) plus three states for the implement side. Every open issue
+carries one category label (`bug` | `enhancement`) and **exactly one** state label:
+
+```mermaid
+stateDiagram-v2
+    [*] --> needs_triage: triage loop, first sighting
+    needs_triage --> needs_info: triage loop asks
+    needs_info --> needs_triage: reporter replies
+    needs_triage --> ready_for_agent: maintainer, after reading the brief (act: the loop, for a reproduced bug)
+    needs_triage --> ready_for_human: maintainer
+    needs_triage --> wontfix: maintainer (act: the loop, for a duplicate or an already-built request)
+    ready_for_agent --> agent_working: implement loop claims
+    agent_working --> in_review: implement loop opens the PR
+    agent_working --> agent_blocked: implement loop cannot finish
+    agent_blocked --> ready_for_agent: maintainer answers
+    in_review --> agent_working: reviewer requests changes
+    in_review --> [*]: maintainer merges (Closes #n)
+```
+
+| state | meaning | leaves it |
+|---|---|---|
+| *(none)* | never looked at | the triage loop labels it `needs-triage` |
+| `needs-triage` | being evaluated; a brief or questions get posted here | the triage loop (→ `needs-info`) or the maintainer (→ the three below) |
+| `needs-info` | waiting on the reporter | the triage loop, once the reporter has replied |
+| `ready-for-agent` | the brief is accepted; an agent may build it | the implement loop claims it |
+| `ready-for-human` | judgement, access, design, manual testing | a person |
+| `agent-working` | claimed: a worktree and a branch exist | the implement loop (→ `in-review` or `agent-blocked`) |
+| `in-review` | a pull request is open | the maintainer merges, or a reviewer requests changes |
+| `agent-blocked` | the loop stopped; its last comment says what it needs | the maintainer answers and moves it back |
+| `wontfix` | closed; the reason is on the issue, and for a rejected enhancement in `.out-of-scope/` | — |
+
+Four rules make it run unattended:
+
+- **The tracker is the truth; a loop's notes are a cache.** Every run reads labels and comments
+  fresh. Notes hold only what the tracker cannot say — the comment timestamp a run last handled,
+  the worktree a run was cut off in. A person can move any issue at any time, from the web, and
+  the next run sees the new state; two machines sharing a `$HOME` see the same thing.
+- **The claim is the first write.** `agent-working` plus an assignee; a run that finds the label
+  already gone picks the next issue. Nothing is held in memory across runs. It is a soft lock —
+  the tracker has no compare-and-swap — and at thirty-minute cadence that has been enough.
+- **The brief is the contract.** An *Agent Brief* comment describes behaviour, interfaces and
+  acceptance criteria, never file paths or line numbers, so it is still right after the weeks it
+  may wait. The implement loop builds from the latest brief; when the brief and the code disagree
+  in a way the brief did not foresee, that is `agent-blocked`, not a guess.
+- **Every AI comment says so** on its first line.
+
+The two checkpoints are pushed as far right as they go. `#14 brief posted — recommend
+ready-for-agent (bug, reproduced by npm test)` arrives after the loop has reproduced the bug,
+checked `.out-of-scope/` and the open issues for a prior answer, and written the brief; your
+click on the label is the whole approval (`act` makes that click for reproduced bugs). `#12 PR
+opened — <url> (3 commits, checks green)` arrives after the build, the project's check command and
+a test plan; requesting changes sends it back to the loop, which addresses each comment and
+re-requests review. Merging stays with a person at every level.
+
+What a run looks like when it goes wrong is in the playbooks themselves: a run cut off
+mid-implementation resumes from its branch and notes; a check command failing twice on one issue
+is a block, not a third attempt; the loop and you editing the same issue is settled by the
+tracker, which wins.
+
+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
+propose, which is what `changelog-draft` does everywhere.
+
+## autoresearch
+
+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
+worktree per experiment, and a rule that the held-out number decides — never the dev number a run
+was tuning against.
+
+- **`RESEARCH.md`** at the project root is the contract: objective, metric and direction, the dev
+  and held-out commands (each prints `metric=<number>`), which files may change, which are
+  protected, the promotion rule, the time budget. The loop never writes it; a run that finds it
+  missing files one finding and stops, and a run that finds a protected file's hash changed does
+  the same. `RESEARCH.template.md` is installed beside the playbook; `example/` is a filled-in one
+  with a naive exact k-NN in pure Python whose baseline speedup is 1.0.
+- **`results.tsv`** (the path the contract names) is the ledger: one row per experiment with its
+  branch, hypothesis, dev and held-out numbers and a status — `baseline`, `running`, `retired`,
+  `kept`, `promoted`. A retired row is negative evidence the next run reads before choosing; the
+  loop writes the file and never commits it.
+- **One run, one experiment.** Choose a hypothesis the ledger has not retired, write its row as
+  `running`, branch in a worktree, change only the editable files, commit, measure on dev. Not
+  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.
+- **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
+  the checker what verifying means here: check out the branch, run the held-out command yourself,
+  keep the finding only if your number satisfies the rule.
+
+Try it on the example before your own problem:
+
+```sh
+cp -r .agents/skills/autoresearch/example /tmp/knn && cd /tmp/knn && git init -q && git add -A && git commit -qm baseline
+pi                      # /recipe add autoresearch, then /cron run autoresearch
+```
+
+The first run measures the baseline and creates the ledger; each later one tries one idea. With
+the example's five-percent rule and a four-second evaluation, a promotion arrives within a few
+runs — and so do the retired ideas, in the ledger, which is what makes the runs after that better.

package/docs/web-ui-parity.md

@@ -173,6 +173,8 @@ weaker, and worth converting whenever one of them breaks.
       be read as prose and waved through. `test/web-page.test.ts`: *a confirmation shows what is
       about to run*.
 - [x] Enter does not approve: the focus starts on cancel.
+- [x] A slash command that waits in a dialog is not reported as timed out while the person reads:
+      the browser waits up to fifteen minutes for a `/…` prompt, sixty seconds for anything else.
 - [x] Clicking away from any dialog closes it. `test/web-page.test.ts`: *clicking outside a dialog
       closes it*.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.17.6",
+  "version": "0.18.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",
@@ -32,6 +32,7 @@
     "skills",
     "docs",
     "examples",
+    "recipes",
     "README.md",
     "README.zh-CN.md",
     "CHANGELOG.md",

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

@@ -0,0 +1,31 @@
+# Issue tracker: GitHub
+
+Work items for this repository live as GitHub Issues; pull requests are the review surface. Use
+the `gh` CLI for every operation; it infers the repository from the remote when run in a clone.
+
+## Operations
+
+- **List**: `gh issue list --state open --limit 200 --json number,title,labels,updatedAt,author` (add `--label <state>` to filter by state)
+- **Read**: `gh issue view <n> --comments --json number,title,body,labels,author,createdAt,comments`
+- **Comment**: `gh issue comment <n> --body "..."` (a heredoc for multi-line bodies)
+- **Change state**: `gh issue edit <n> --add-label "<new state>" --remove-label "<old state>"` — exactly one state label at a time
+- **Claim**: `gh issue edit <n> --add-label agent-working --remove-label ready-for-agent --add-assignee @me`
+- **Close**: `gh issue close <n> --comment "..."`
+- **Pull requests**: `gh pr create`, `gh pr list --state open --json number,url,headRefName,reviewDecision,comments,updatedAt`, `gh pr view <n> --comments`, `gh pr diff <n>`
+
+## State vocabulary
+
+One category label (`bug` | `enhancement`) and exactly one state label per open issue. The state
+labels are `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `agent-working`,
+`in-review`, `agent-blocked`, `wontfix`. The recipe's setup script creates them; a playbook that
+moves an issue names the label it moves to.
+
+## Blocking
+
+A `Blocked by: #<n>, #<m>` line near the top of an issue body (or the tracker's native
+dependency) gates it: the item is unblocked when every listed issue is closed.
+
+## Who counts as the agent
+
+Comments and assignments made by loops are made as the account `gh` is signed in as. Every comment
+a loop posts starts with a line saying it was generated by AI.

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

@@ -0,0 +1,38 @@
+# Issue tracker: local Markdown
+
+Work items for this repository live as Markdown files in `.scratch/issues/`, one file per item,
+committed with the code. There are no pull requests: a change is a branch, and the review
+checkpoint is a finding in the inbox that names the branch.
+
+## Layout
+
+- `.scratch/issues/<NN>-<slug>.md`, numbered from `01`; the number is the item's id (`#07`)
+- The first lines of a file:
+
+  ```markdown
+  # 07: <title>
+
+  **Category:** bug | enhancement
+  **Status:** needs-triage
+  **Blocked by:** 03, 05   (or "none")
+  ```
+
+- Discussion appends to the bottom under `## Comments`, one `### <date> — <who>` heading per
+  comment; a comment by a loop starts with a line saying it was generated by AI
+- An *Agent Brief* is a `## Agent Brief` section in the file, not a comment
+
+## Operations
+
+- **List**: read every file in `.scratch/issues/`; the `**Status:**` line is the state
+- **Read**: read the file
+- **Comment**: append under `## Comments`
+- **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
+
+## State vocabulary
+
+`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `agent-working`, `in-review`,
+`agent-blocked`, `wontfix`, plus `done` for a merged item. A playbook that moves an item names the
+state it moves to.

package/recipes/_tracker-setup.md

@@ -0,0 +1,12 @@
+`/recipe add {recipe}` stopped before installing anything: that recipe's playbooks read `docs/agents/issue-tracker.md` on every run to learn where this project's work items live and how to list, read, comment on, label and close them — and `{project}` has no such file yet. Write it with me now. This is a conversation, not a template fill: explore first, propose, and write only after I have agreed.
+
+1. **Explore.** Run `git remote -v` in `{project}`. Look for an existing `.scratch/` directory (a sign the local Markdown tracker is already in use), and for an `## Agent skills` section in `AGENTS.md` or `CLAUDE.md` (a sign Matt Pocock's engineering skills were set up here; if so, their `docs/agents/issue-tracker.md` convention is the one we are writing, and it may already be partly there).
+
+2. **Propose, one question.** Lead with the recommendation so I can accept it in a word:
+   - a GitHub remote → recommend **GitHub Issues** (the `gh` CLI; check `gh auth status` works);
+   - no remote, or I say so → recommend **local Markdown**: one file per item under `.scratch/issues/`, a `**Status:**` line as the state.
+   Anything else (GitLab, Jira, Linear): ask me to describe the workflow in a paragraph and record it as prose.
+
+3. **Write `docs/agents/issue-tracker.md`** from the matching template in `{templates}/` (`issue-tracker-github.md` or `issue-tracker-local.md`), adjusted to what we agreed. Show me the draft before writing. Keep the state vocabulary section as it is: the playbooks name those states. The file stays out of the repository (the wizard lists it in `.git/info/exclude`, like the playbooks), but it is still read by every run: keep it to how the tracker works — no secrets, no tokens.
+
+4. **Stop there.** The wizard is waiting for this file: as soon as this turn ends with it in place, `/recipe add {recipe}` resumes on its own — the level question, the setup script, the confirmation. Do not create cron jobs, labels, worktrees or branches yourself, and do not tell me to run anything; the wizard does the rest after showing me exactly what it will do.

package/recipes/autoresearch/README.md

@@ -0,0 +1,27 @@
+# autoresearch — one experiment per run, a ledger, held-out evidence before promotion
+
+The shape is the one Karpathy's autoresearch and Arbor made familiar: a **research contract** a
+person writes (objective, metric, which files may change, which are protected, dev and held-out
+commands, a promotion rule), a **ledger** of every attempt including the failed ones, an isolated
+worktree per experiment, and a rule that the held-out number decides — never the dev number a run
+was tuning against. What pi-loops adds is that nothing here needs a kernel: the contract and the
+ledger are files in the repository, each run is one stateful loop run, and the checker of
+`--verify` is the evaluator that re-measures before a promotion reaches you.
+
+| file | what it is |
+|---|---|
+| [recipe.toml](recipe.toml) | one job, `every 1h`, `--verify`, 40-minute timeout |
+| [experiment.md](experiment.md) | the playbook: contract → ledger → one hypothesis → worktree → measure → row → maybe promote |
+| [RESEARCH.template.md](RESEARCH.template.md) | copy to the project root as `RESEARCH.md` and fill in; the loop stops until it exists |
+| [example/](example/) | a filled-in contract with a naive exact k-NN in pure Python: `bash eval.sh dev` prints `metric=<speedup>` |
+
+Try it on the example first:
+
+```sh
+cp -r .agents/skills/autoresearch/example /tmp/knn && cd /tmp/knn && git init -q && git add -A && git commit -qm "baseline"
+pi            # then: /recipe add autoresearch   and   /cron run autoresearch
+```
+
+The first run measures the baseline and writes `results.tsv`; the next ones each try one idea.
+Under `propose` a promotable branch arrives in `/inbox` with both numbers; under `act` it is
+merged into the checkout and the finding says so.