@alphacoder-v0/pi-loops 0.17.6 → 0.19.2

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/triggers.md

@@ -97,7 +97,7 @@ rule evaluation, per window for injected pushes).
 /triggers sources     local checker + each MCP server: state, queued/dropped/deduped, tools
                       (/triggers hooks is the same view)
 /triggers enable <id> /triggers disable <id> /triggers remove <id>   also --all | --all-projects
-/triggers set <id>    --model | --thinking | --timeout | --host: what the action runs with
+/triggers set <id>    --model | --thinking | --timeout: what the action runs with
 /triggers run <id>    check one rule now, without waiting for its poll slot
 /triggers running     sub-agents in flight (dynamic checks and cron runs)   /triggers abort <trace>|--all
 /triggers audit [N]

package/docs/troubleshooting.md

@@ -1,8 +1,9 @@
 # Troubleshooting
 
 **Nothing fires.** `/cron scheduler`: is this process the timer owner or standby? If the owner died
-without cleanup, a standby takes over within 90 seconds. Jobs show `next …` when enabled. A plain
-job marked `[dormant …]` only fires in the session that created it (`--resume` it); a loop marked
+without cleanup, a standby takes over within 90 seconds. A job shows `next …` when it will run
+*here*. A plain job marked `[session <id> — resume it to run]` belongs to another session and fires
+only there (`--resume` it, or `/cron add` it again in this chat); a loop marked
 `[orphan: cwd missing]` was disabled because its checkout is gone.
 
 **A run failed.** `/cron runs` shows the error; `/cron trace <job> 1` shows the sub-agent's

package/docs/web-ui-parity.md

@@ -116,9 +116,7 @@ weaker, and worth converting whenever one of them breaks.
       says so as a count — without it, a job somewhere else is indistinguishable from a job that is
       gone. Jobs and rules are counted and labelled apart, each line naming the command that lists
       them (`/cron all`, `/triggers rules --all`): one number covering both agrees with neither
-      command, and the line exists to send you to the command. A job stamped with a hostname this
-      machine no longer has (a rebuilt container, a rename) is listed and marked, the way `/cron`
-      lists it, rather than filtered out of sight.
+      command, and the line exists to send you to the command.
       What counts as "this project" is what the extension says it is — symlinks resolved, `$HOME`
       too broad to be one — because a panel that disagrees with the command is worse than either.
       `test/web.test.ts`: *the panel and /cron agree about what this project is*.
@@ -173,6 +171,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*.
 
@@ -213,6 +213,12 @@ weaker, and worth converting whenever one of them breaks.
       left is a file that `resume` lists, labelled by what was said in it rather than by a filename.
       `test/web.test.ts`: *a new session is a path pi has not written yet, and going back is one it
       has*. `test/web-page.test.ts`: *the session you are in is not offered as one to go back to*.
+- [x] **The session commands are two words here.** `/sessions` prints this project's sessions into
+      the feed — short id, when, what was first said — and `/session export [path]` / `/session
+      import <path>` are the archive commands, sent as `/session-export` / `/session-import`. pi's
+      own `/session` is a terminal command that does not exist over rpc, which is why the extension
+      had to hyphenate its names in the terminal and why the page is free to spell them plainly.
+      `test/web-page.test.ts`: */sessions and /session export are typed here*.
 - [x] A session started here is a session pi-loops recognises. pi names the sessions it starts after
       their id and the front end cannot know that id in time, so anything identifying a session by
       its file name is wrong about this one — which parked every inject-and-run cron job made in a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.17.6",
+  "version": "0.19.2",
   "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.

package/recipes/autoresearch/RESEARCH.template.md

@@ -0,0 +1,37 @@
+# Research contract
+
+Copy this file to the project root as `RESEARCH.md` and fill it in. The autoresearch loop reads it
+on every run and never changes it; a run that finds it missing or its protected files altered stops
+with a finding. The example in `.agents/skills/autoresearch/example/` is a filled-in one.
+
+## Objective
+
+One sentence a person can check: what better means. *Make the exact k-nearest-neighbour search in
+`solution.py` faster while keeping its output identical.*
+
+## Metric
+
+- **name:** `speedup` — **higher is better** (or: `val_loss`, lower is better)
+- **dev command:** `bash eval.sh dev` — prints one line `metric=<number>`; used to iterate
+- **held-out command:** `bash eval.sh test` — same shape, other data; used only to decide promotion
+- **baseline:** measured by the first run on the untouched code and written to the ledger; leave blank
+
+## Files
+
+- **editable:** `solution.py` (one path per line; nothing else may change)
+- **protected:** `eval.sh`, `eval.py`, `task.py` — the loop records their `sha256sum` in the ledger's
+  header on the first run and refuses to work if any differs since
+
+## Promotion rule
+
+A branch is promotable when its **held-out** metric beats the best promoted (or the baseline) by at
+least **5%**, and the dev metric agreed. Under `propose` the loop files a finding and a person
+merges; under `act` the loop merges the branch into this checkout's current branch itself.
+
+## Budget and layout
+
+- **per experiment:** at most 10 minutes of evaluation; a run that exceeds it retires the experiment
+- **ledger:** `research/results.tsv` (created by the loop, never committed by it)
+- **worktrees:** `../<repo>-research/<NNN>`, branch `research/<NNN>-<slug>`; retired branches are deleted, the ledger row stays
+- **directions worth trying first (optional):** …
+- **directions not to try (optional):** …

package/recipes/autoresearch/example/RESEARCH.md

@@ -0,0 +1,31 @@
+# Research contract
+
+## Objective
+
+Make the exact k-nearest-neighbour search in `solution.py` faster while keeping its output
+identical to the reference.
+
+## Metric
+
+- **name:** `speedup` — higher is better (wall-clock of the reference divided by wall-clock of `solution.py`, measured in the same process, median of 3)
+- **dev command:** `bash eval.sh dev`
+- **held-out command:** `bash eval.sh test`
+- **baseline:** (written by the first run)
+
+## Files
+
+- **editable:** `solution.py`
+- **protected:** `eval.sh`, `eval.py`
+
+## Promotion rule
+
+Held-out `speedup` at least 5% above the best promoted row (or the baseline), with the dev run
+agreeing and the output check passing.
+
+## Budget and layout
+
+- **per experiment:** at most 5 minutes of evaluation
+- **ledger:** `results.tsv`
+- **worktrees:** `../<repo>-research/<NNN>`, branch `research/<NNN>-<slug>`
+- **directions worth trying first:** partial selection instead of a full sort; avoid recomputing the query's coordinates in the inner loop; batch the distance computation
+- **directions not to try:** approximate search (the output must stay exact); C extensions or third-party packages (standard library only)

package/recipes/autoresearch/example/eval.py

@@ -0,0 +1,60 @@
+"""Protected: generates the data, checks exactness, measures speedup. Do not edit in an experiment.
+
+Usage: python3 eval.py dev|test   → prints `metric=<speedup>` (or `metric=0 error=...`).
+
+The reference is the naive algorithm frozen here, so a speedup is relative to the starting point
+and independent of the machine's absolute speed. Timings are the median of three runs of each.
+"""
+import random
+import statistics
+import sys
+import time
+
+import solution
+
+SPLITS = {"dev": (1, 2500, 80, 8, 4), "test": (2, 3000, 90, 8, 5)}  # seed, n points, n queries, dims, k
+
+
+def reference(points, queries, k):
+    # Deliberately the same loops as the untouched solution.py, so the baseline speedup is 1.0.
+    out = []
+    for q in queries:
+        dists = []
+        for i, p in enumerate(points):
+            d = 0.0
+            for a, b in zip(p, q):
+                d += (a - b) * (a - b)
+            dists.append((d, i))
+        dists.sort()
+        out.append([i for _, i in dists[:k]])
+    return out
+
+
+def timed(fn, *args):
+    runs = []
+    for _ in range(3):
+        t0 = time.perf_counter()
+        fn(*args)
+        runs.append(time.perf_counter() - t0)
+    return statistics.median(runs)
+
+
+def main():
+    split = sys.argv[1] if len(sys.argv) > 1 else "dev"
+    seed, n, m, dims, k = SPLITS[split]
+    rng = random.Random(seed)
+    points = [[rng.random() for _ in range(dims)] for _ in range(n)]
+    queries = [[rng.random() for _ in range(dims)] for _ in range(m)]
+    expected = reference(points, queries, k)
+    got = solution.knn(points, queries, k)
+    if got != expected:
+        print("metric=0 error=output differs from the reference")
+        return 1
+    ref_t = timed(reference, points, queries, k)
+    sol_t = timed(solution.knn, points, queries, k)
+    print(f"metric={ref_t / sol_t:.3f} split={split} ref_s={ref_t:.3f} sol_s={sol_t:.3f}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/recipes/autoresearch/example/eval.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Protected. `bash eval.sh dev` iterates; `bash eval.sh test` decides promotion.
+cd "$(dirname "$0")" && exec python3 eval.py "${1:-dev}"

package/recipes/autoresearch/example/solution.py

@@ -0,0 +1,20 @@
+"""The editable file: exact k-nearest neighbours, deliberately naive.
+
+`knn(points, queries, k)` returns, for each query, the indices of the k closest points by squared
+Euclidean distance, ties broken by lower index. The evaluator checks the output against a
+reference and times this function; only this file may change.
+"""
+
+
+def knn(points, queries, k):
+    out = []
+    for q in queries:
+        dists = []
+        for i, p in enumerate(points):
+            d = 0.0
+            for a, b in zip(p, q):
+                d += (a - b) * (a - b)
+            dists.append((d, i))
+        dists.sort()
+        out.append([i for _, i in dists[:k]])
+    return out