compounding-loop 0.1.0 → 0.2.0

package/dist/web/index.html

@@ -3,10 +3,10 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="icon" type="image/svg+xml" href="./favicon.svg" />
     <title>Compounding Loop</title>
-    <script type="module" crossorigin src="/assets/index-BDdtnG33.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-D3-N8DN4.css">
+    <script type="module" crossorigin src="./assets/index-CS82DKbF.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-B16QCSnY.css">
   </head>
   <body>
     <div id="root"></div>

package/method/COMPOUNDING_LOOP.md

@@ -24,6 +24,7 @@
   13. Measurement
   14. The human's role
   15. Commands
+  16. Lanes: several unattended runs, one repo
 - Part C: Templates
 - Part D: Setup and adoption order
 - Part E: Limits, open questions, where the ideas come from
@@ -382,6 +383,39 @@ Say it any way you like. The AI maps it to the right protocol.
 
 > Resume from `.ai/task.md`. Verify Current state against git and the checks before trusting it, tell me about any mismatch, then do the next step.
 
+### 16. Lanes: several unattended runs, one repo
+
+A lane is one scheduled run that owns one part of the codebase. Several lanes push to the same `main` on staggered schedules. Ownership of paths replaces merging: two lanes never edit the same file, so there is nothing to merge.
+
+**When to split into lanes**
+
+- Split when the work has parts with clean seams (core library, server, web UI, docs) and each part can be verified on its own, and when one run per hour would otherwise be the bottleneck.
+- Do not split a project that is small, or whose parts change together in most commits. A cross-cutting change in a laned repo means waiting on another lane, which costs a day. One loop with units in order is faster and simpler.
+- Start with two or three lanes. Each lane costs a run budget and a share of your plan's usage limit.
+
+**Ownership.** `.ai/lanes.json` lists each lane's `owns` globs and the `shared` files any lane may edit with the smallest possible change (lockfiles, config, shared types). Owning no overlapping paths is checked when the file is read. Reading is free: a lane may read anything. Fixing a red `main` is the one cross-lane edit allowed anywhere. `loop check-lanes` only lets the trailer `Lane: control` touch every path, so commit that fix as `Lane: control` (or list the file under `shared`) and tell the owner in your outbox.
+
+**Outboxes.** A lane talks to the others by writing only to its own `.ai/lanes/<lane>/outbox.md`, newest first: `YYYY-MM-DD HH:MM UTC · to <lane|all> · message`. At the start of every run each lane reads every other outbox and the control room's notes, and acts on messages to it or to `all`. Nobody writes into another lane's files, so there is no conflict even on the notes. Say what you shipped that someone waits on, and point to `path:line`.
+
+**The control room.** One more scheduled run, every few hours, plays the owner: it runs the whole test suite, does the leak check, reads each lane's task file and outbox, and writes only `.ai/control-room.md` and the smallest fixes. It extends a lane's run budget once if the lane made real progress, answers a `BLOCKED.md` question when the brief answers it safely, copies messages that have waited too long to the lane that ignores them, tells a lane to stop waiting for a finished one, and writes the root `DONE.md` when every lane is done and the product's done-when passes. It uses the trailer `Lane: control`.
+
+**The trailer check.** Every commit ends with `Lane: <lane>`. `loop check-lanes` reads the commits in a range and fails any commit that touches a path its lane does not own and that is not shared or the lane's own `.ai/lanes/<lane>/` folder. Commits without a trailer are reported, not failed, because humans commit too. Run it in CI on every push and pull request.
+
+**Rules that make parallel runs safe**
+
+1. Start every run with `git checkout main && git pull --ff-only`; pull again right before each push.
+2. A rejected push means `git pull --rebase` and push again. A rebase that conflicts in a file you do not own means `git rebase --abort`, note it under Tried, pull fresh and redo your small change on top.
+3. Never force-push. A lane's history is the other lanes' history too.
+4. Each lane has its own task file, run counter, `DONE.md` and `BLOCKED.md`. Only the control room writes the root `DONE.md`.
+
+**Failure modes seen when this repo was built by five lanes**
+
+- **Stale sandbox clones.** A cloud run can start from an old clone and report that someone force-pushed or that a file vanished. Check `git log` on a fresh pull before believing a run's account of history.
+- **Rate-limit starvation.** On a subscription plan, the lanes share one usage limit. Runs that end in about a second are usually the limit, not a bug. Fewer lanes, fewer runs per day or a lower-tier model for cheap lanes fixes it. The control room marks a lane with no commit in four hours as stalled.
+- **A lane waiting on a finished lane.** The web lane waited for an API the server lane would never add, because the server lane had already written `DONE.md`. The control room now tells the waiting lane to stop waiting, record the gap as a next improvement and finish. Before a lane writes its own `DONE.md` it reads the other outboxes to see who waits on it.
+- **A red `main` nobody owns.** When tests fail on a fresh pull, the lane that notices fixes it first, with the smallest change, and says so in its outbox.
+- **A lock that stops everything.** A runner that writes the session lock itself must tell the prompt the lock is its own, or every run stands down.
+
 ---
 
 ## Part C: Templates

package/method/example/K-0002.md

@@ -0,0 +1,16 @@
+---
+id: K-0002
+type: gotcha
+status: confirmed
+scope: project
+triggers:
+  errors: ["browserType.launch: Executable doesn't exist", "Failed to download Chromium"]
+  files: [playwright.config.ts]
+  commands: [npx playwright install chromium]
+  topics: [playwright, sandbox, e2e]
+evidence: seen in a cloud sandbox where the browser download is blocked; a preinstalled Chromium was used instead (example entry)
+created: 2026-01-01
+fired: 0
+helped: 0
+---
+In a locked-down sandbox `npx playwright install chromium` can fail. Do not retry it. Point the config at a preinstalled Chromium or a system Chrome, and if Chrome then fails over missing libraries, run `npx playwright install-deps chromium`. Record the working setup in the project's Commands section once.

package/method/example/K-0003.md

@@ -0,0 +1,16 @@
+---
+id: K-0003
+type: decision
+status: confirmed
+scope: project
+triggers:
+  errors: ["Nothing to do"]
+  files: [".ai/session.lock"]
+  commands: [loop run]
+  topics: [session lock, unattended, stands down]
+evidence: every scheduled run ended with "Nothing to do" because the runner wrote the lock the prompt then respected (example entry)
+created: 2026-01-01
+fired: 0
+helped: 0
+---
+If the runner writes `.ai/session.lock` itself, the prompt must be told the lock is its own, or every run stands down at step one. Treat only a lock this session did not create as another run's. Keep `**/session.lock` in `.gitignore` so per-lane locks are never committed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compounding-loop",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Write the brief, check back tomorrow: unattended, verified Claude Code build loops with a local dashboard.",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,10 @@
     "type": "git",
     "url": "git+https://github.com/Minntooos/compounding-loop.git"
   },
+  "homepage": "https://github.com/Minntooos/compounding-loop#readme",
+  "bugs": {
+    "url": "https://github.com/Minntooos/compounding-loop/issues"
+  },
   "keywords": [
     "claude-code",
     "ai-agents",
@@ -43,6 +47,7 @@
     "preview": "vite preview --port 4173 --strictPort"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.13.0",
     "@fontsource-variable/inter": "^5.3.0",
     "@fontsource-variable/jetbrains-mono": "^5.3.0",
     "@playwright/test": "^1.64.0",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "compounding-loop",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Run unattended, verified Claude Code build loops: set up a repo, hand off between windows, run retros and escape stuck loops.",
   "license": "MIT",
   "keywords": ["loop", "unattended", "verification", "handoff", "retro"]

package/runners/github-actions/lanes.yml

@@ -0,0 +1,103 @@
+# Compounding Loop: one scheduled job per lane on GitHub Actions.
+#
+# Setup (once):
+#   1. Add ONE repository secret under Settings > Secrets and variables > Actions:
+#        ANTHROPIC_API_KEY        (API billing), or
+#        CLAUDE_CODE_OAUTH_TOKEN  (a Claude subscription; create it with `claude setup-token`).
+#      Secrets are referenced by name only. Never write a key into this file or the repository.
+#   2. Copy this file to .github/workflows/lanes.yml.
+#   3. The `verify` job runs `loop check-lanes`, which needs compounding-loop 0.2.0 or later.
+#   4. Edit the `lane` and `cron` pairs in the matrix to match .ai/lanes.json, and keep the same
+#      cron strings in `on.schedule` (see runners/routine/README.md for staggering N lanes).
+#
+# How it runs: every cron line starts the whole matrix, and each job does real work only when
+# the schedule that fired is its own (or when started by hand), so one lane runs per trigger.
+name: compounding-loop-lanes
+
+on:
+  schedule:
+    - cron: "7 * * * *"
+    - cron: "19 * * * *"
+    - cron: "31 * * * *"
+  workflow_dispatch: {}
+
+# Workflow-level default: read only. The lane job raises it, because the lane pushes to main.
+permissions:
+  contents: read
+
+jobs:
+  lane:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      contents: write # the lane commits and pushes to main
+    strategy:
+      fail-fast: false
+      max-parallel: 1 # lanes never run at the same time, so two pushes cannot race
+      matrix:
+        include:
+          - { lane: api, cron: "7 * * * *" }
+          - { lane: web, cron: "19 * * * *" }
+          - { lane: docs, cron: "31 * * * *" }
+    # A lane never overlaps its own previous run; queue instead of cancelling one mid-push.
+    concurrency:
+      group: loop-lane-${{ matrix.lane }}
+      cancel-in-progress: false
+    steps:
+      - name: Is this lane's turn?
+        id: gate
+        env:
+          EVENT: ${{ github.event_name }}
+          FIRED: ${{ github.event.schedule }}
+          MINE: ${{ matrix.cron }}
+        run: |
+          if [ "$EVENT" = "workflow_dispatch" ] || [ "$FIRED" = "$MINE" ]; then echo "go=true" >> "$GITHUB_OUTPUT"; else echo "go=false" >> "$GITHUB_OUTPUT"; fi
+      - uses: actions/checkout@v4
+        if: steps.gate.outputs.go == 'true'
+        with:
+          ref: main
+          fetch-depth: 0
+          # The lane pushes, so the checkout token must stay in git's config (persist-credentials: true,
+          # the default). A job that only reads, like `verify` below, sets it to false.
+          persist-credentials: true
+      - uses: actions/setup-node@v4
+        if: steps.gate.outputs.go == 'true'
+        with:
+          node-version: 22
+      - uses: anthropics/claude-code-action@v1
+        if: steps.gate.outputs.go == 'true'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          # Paste runners/routine/lane-prompt.md here with {{name}} and {{lane}} filled
+          # ("${{ matrix.lane }}" works for the lane). Short form shown:
+          prompt: |
+            You are one scheduled run of the ${{ matrix.lane }} lane of an unattended build loop.
+            Read CLAUDE.md and follow it exactly. Your task file is .ai/lanes/${{ matrix.lane }}/task.md.
+            Every commit ends with the trailer line "Lane: ${{ matrix.lane }}". Push to main, never to a claude/ branch.
+            Stop if DONE.md or BLOCKED.md exists at the root or in .ai/lanes/${{ matrix.lane }}/.
+            Never publish, spend money, or add secrets or tracking.
+          claude_args: >-
+            --max-turns 200
+            --allowedTools "Bash,Edit,Write,Read,Glob,Grep,Task"
+
+  verify:
+    # Read-only: reports any commit that crossed a lane boundary.
+    needs: lane
+    if: ${{ always() }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+          persist-credentials: false # nothing here pushes, so the token is not left in the checkout
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Check lane ownership
+        run: |
+          BASE=$(git rev-parse --verify -q "origin/main~20" || git rev-list --max-parents=0 HEAD | tail -1) # a young repo has fewer than 20 commits
+          npx --yes compounding-loop check-lanes --range "$BASE..HEAD"

package/runners/local/README.md

@@ -2,7 +2,8 @@
 
 Runs the loop from your own machine on a schedule. Needs Node 20+, git and the `claude` CLI signed in to your account.
 
-- **macOS / Linux:** paste the line from `crontab.txt` into `crontab -e` and set your repository path.
+- **Linux:** paste the line from `crontab.txt` into `crontab -e` and set your repository path.
+- **macOS:** `crontab.txt` works too, but launchd is the native scheduler and runs missed rounds after sleep. Edit the paths in `launchd.plist` (`loop` from `which loop`, your repository, the log file), copy it to `~/Library/LaunchAgents/` and load it with the `launchctl bootstrap` line at the top of the file. The plist runs `loop run` hourly at minute 17.
 - **Windows:** edit the path in `task-scheduler.xml`, then import it with `schtasks /Create /XML task-scheduler.xml /TN CompoundingLoop`. The `claude.exe` native build must be on your PATH. Add `--skip-permissions` to the task's arguments only in a repository you trust, so the unattended run can edit files.
 
 Both use the minute `17`; change it so several loops do not start together. Each run is capped by the session lock (90 minutes) and the run budget (`Run: N / 30`).

package/runners/local/launchd.plist

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- Compounding Loop on macOS: run one round at minute 17 of every hour.
+     Install:   cp launchd.plist ~/Library/LaunchAgents/com.example.compounding-loop.plist
+                (edit the paths below first), then
+                launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.compounding-loop.plist
+     Remove:    launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.example.compounding-loop.plist
+     For unattended edits add <string>--skip-permissions</string> after <string>run</string> below, only in a repository you trust.
+     launchd has a minimal PATH, so PATH below must contain the folders of `node`, `loop` and `claude`. -->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.example.compounding-loop</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/loop</string>
+    <string>run</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>/path/to/repo</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/usr/local/bin:/opt/homebrew/bin:/path/to/home/.local/bin:/usr/bin:/bin</string>
+  </dict>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Minute</key>
+    <integer>17</integer>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/path/to/repo/.ai/loop-cron.log</string>
+  <key>StandardErrorPath</key>
+  <string>/path/to/repo/.ai/loop-cron.log</string>
+</dict>
+</plist>

package/runners/routine/README.md

@@ -12,8 +12,45 @@ A routine is a scheduled Claude Code session in the cloud. It runs `prompt.md` a
 
 If several loops (or several lanes of one project) run against one repository, give each a different minute so they do not collide. Use the pattern `M * * * *` (hourly), and move `M` by at least 10 minutes per loop, for example `7 * * * *`, `17 * * * *`, `27 * * * *`. Avoid minute `0`: everyone's schedule lands there.
 
-Each run stops after about 40 minutes of work, so an hourly schedule leaves a gap before the next one. The 90-minute session lock (`.ai/session.lock`) stops two runs from working at once. The run budget (`Run: N / 30` in `.ai/task.md`) caps the total number of runs.
+Each run stops after about 40 minutes of work, so an hourly schedule leaves a gap before the next one. The 90-minute session lock (`.ai/session.lock`, or `.ai/lanes/<lane>/session.lock` per lane) stops two runs from working at once. The run budget (`Run: N / 30` in `.ai/task.md`) caps the total number of runs.
 
 ## Safety
 
 The prompt never publishes, spends money or stores a secret. The routine uses your Claude account; no API key goes into the repository.
+
+## Lanes
+
+With several lanes, create one routine per lane plus one control room routine.
+
+| File | Placeholders | Routine |
+|---|---|---|
+| `lane-prompt.md` | `{{name}}` project, `{{lane}}` lane name | one per lane, hourly |
+| `control-room-prompt.md` | `{{name}}` project, `{{lanes}}` lane names, comma separated | one, every 3 hours |
+
+`loop run --lane <name>` fills them for local runs. In the cloud, paste the filled text into the routine. In the cloud nothing writes the lock; it only matters when a local `loop run --lane` is active too. The lane prompt stands down on a fresh `.ai/lanes/<lane>/session.lock`, stops on root or lane `DONE.md`/`BLOCKED.md`, and ends every commit with `Lane: <lane>`.
+
+### Staggered cron for N lanes
+
+Give lane `i` (counting from 0) the minute `7 + i * step` with `step = 12` for up to five lanes (more lanes: use a smaller step, but keep minutes distinct), and put the control room on its own minute every 3 hours. Runs last up to 40 minutes, so neighbouring lanes overlap; that is expected. Path ownership plus `git pull --rebase` before each push make it safe, and the stagger only spreads the pulls out. Avoid minute 0.
+
+3 lanes (`api`, `web`, `docs`):
+
+| Routine | Cron |
+|---|---|
+| api | `7 * * * *` |
+| web | `19 * * * *` |
+| docs | `31 * * * *` |
+| control room | `43 */3 * * *` |
+
+5 lanes (`core`, `kit`, `server`, `web`, `docs`, as in this repository):
+
+| Routine | Cron |
+|---|---|
+| core | `7 * * * *` |
+| kit | `19 * * * *` |
+| server | `31 * * * *` |
+| web | `43 * * * *` |
+| docs | `55 * * * *` |
+| control room | `3 */3 * * *` |
+
+Each lane run stops after about 40 minutes, so an hourly lane leaves a gap. Runs that end in about a second usually hit the plan's usage limit, not a bug; fewer or slower lanes cost less.

package/runners/routine/control-room-prompt.md

@@ -0,0 +1,16 @@
+You are the scheduled "control room" run for this repository ({{name}}). The lanes ({{lanes}}) push to `main` on their own schedules; you do the supervision the owner would otherwise do by hand. Nobody is watching; the owner reads your final summary later. Be brief and cheap. Read CLAUDE.md (lane table, hard rules, Unattended mode) and IDEA.md (especially "Done when").
+
+0. Run `date -u`. `git checkout main && git pull --ff-only`. Push only to `main`; if a push is rejected, `git pull --rebase` and push again. Never force-push. Verify claims on a fresh pull: a stale clone is not evidence, and a lane blaming a force-push gets believed only after `git log` shows one.
+1. If root `DONE.md` exists, give the summary (step 6) and stop.
+2. Run the install and test commands from CLAUDE.md. If the tests are red: find the commit that broke it (`git log`, `git bisect` only if quick). If the fix is small and obvious, make it, run the tests, commit with the trailer `Lane: control` and push. Otherwise add a note to `.ai/control-room.md` addressed to the owning lane with the failing command and the likely commit. Also check lane ownership: run `git fetch --unshallow` if the clone is shallow, then `npx compounding-loop check-lanes --range <commit from 4 hours ago>..HEAD` (or `loop check-lanes` if installed), and report each violation to the lane that caused it. If the command is unavailable or errors, say so in the summary and carry on.
+3. Leak check: the published package must contain nothing from `.ai/`, the brief, CLAUDE.md or tests (`npm pack --dry-run`, or your project's equivalent). Grep the repository for secrets (API keys, tokens, private keys) and for the owner's email address and local paths. Fix any leak immediately with the smallest change, push, and say so in the summary.
+4. For each lane read `.ai/lanes/<lane>/task.md` (Run counter, Handoff), its outbox, and whether its `DONE.md` or `BLOCKED.md` exists. Then:
+   - BLOCKED with "run budget reached": if the lane made real progress (commits that pushed tests or features) and its task file has no line "Budget extended by control room", raise the limit by 20, add that line with the date under Decisions, `git rm` the BLOCKED.md, commit and push. If already extended once, leave it for the owner.
+   - BLOCKED with a question: if it can be answered safely from the brief and CLAUDE.md (never anything that spends money, creates accounts, publishes, posts, changes repo visibility or settings, or adds secrets), write the answer under Decisions in that lane's task file as "Answer from control room (date): ...", `git rm` the BLOCKED.md, commit and push. Otherwise leave it and put the question in your summary.
+   - A lane waiting on a lane that is already DONE: tell the waiting lane in `.ai/control-room.md` to stop waiting, list the gap as a next improvement in its DONE.md, and finish.
+   - A message in any outbox that has waited more than 3 hours for a lane that has since run without answering: copy it into `.ai/control-room.md` addressed to that lane.
+   - Lanes with no commit in the last 4 hours and no DONE/BLOCKED: note "stalled" in the summary. Runs that end in about a second are usually a plan or rate limit, not a bug.
+5. When every `.ai/lanes/*/DONE.md` exists, check every line of the brief's "Done when" for the whole product by running its commands. If all pass, write root `DONE.md`: what was built, test results, anything unsure, and the owner's launch checklist. Commit and push. If a line fails, add a note to `.ai/control-room.md` for the owning lane, `git rm` that lane's DONE.md so it resumes, commit and push.
+6. Commit only `.ai/` notes and the smallest fixes, each with the trailer `Lane: control`. End with one line per lane: `lane · Run N/LIMIT · building|blocked|done|stalled · last commit time · note`, then one line for tests and the leak check, then any question for the owner.
+
+Never spend money, sign up for anything, create accounts, publish anything (no package publish, no posting, no repo visibility or settings changes, no releases), add API keys, secrets, ads, analytics or tracking, force-push, or touch anything outside this repository.

package/runners/routine/lane-prompt.md

@@ -0,0 +1,12 @@
+You are one scheduled run of the **{{lane}}** lane of an unattended build loop for this repository ({{name}}). The other lanes push to the same `main` at other minutes of the hour, so expect new commits between your pulls. Nobody is watching; the owner reads the results later. Read CLAUDE.md and follow it exactly, especially the lane table, the hard rules and "Unattended mode". IDEA.md is the brief. Your task file is `.ai/lanes/{{lane}}/task.md`; wherever the Operating Card or `.ai/method.md` says `.ai/task.md`, use your task file. Every commit message you write ends with the trailer line `Lane: {{lane}}`.
+
+0. Run `date -u` and note it as this run's start time. Run `git checkout main && git pull --ff-only`. Commit all work on `main` and push it with `git push origin main`. Never create or push a `claude/` branch. If a push is rejected, run `git pull --rebase` (follow the lockfile rule in CLAUDE.md), re-run the tests if the incoming commits touched code, and push again. If pushing to main is refused by permissions, write that under Tried in your task file, push to a branch named `claude/{{lane}}-blocked`, and stop.
+1. Stop files: if root `DONE.md` or `BLOCKED.md` exists, or `.ai/lanes/{{lane}}/DONE.md` or `.ai/lanes/{{lane}}/BLOCKED.md` exists, reply "Nothing to do" and stop. Session lock: if `.ai/lanes/{{lane}}/session.lock` holds a UTC time less than 90 minutes old and the runner's run note does not say it is your own, another session is working this lane: reply "Nothing to do" and stop. An older lock is stale; ignore it.
+2. Run the install command from CLAUDE.md (`npm install` unless it says otherwise). If it fails, write `.ai/lanes/{{lane}}/BLOCKED.md` with the error and stop. If the tests need a browser, install it the way CLAUDE.md says (a blocked download or a Chrome that will not launch is covered under "Commands" there). If CLAUDE.md names no commands, derive them from `package.json` and record them under Decisions.
+3. Read `.ai/control-room.md` and every other lane's `.ai/lanes/*/outbox.md` for messages to {{lane}} or all. Run the resume protocol (.ai/method.md section 9.2) on your task file and add 1 to its run counter. If the counter has reached its limit, follow "Run budget" in CLAUDE.md.
+4. Run the test command from CLAUDE.md (`npm test` unless it says otherwise) on the fresh pull. If it fails, fixing it is your first unit ("main stays green" in CLAUDE.md), whichever lane owns the failure (commit that fix with the trailer `Lane: control`, which `loop check-lanes` allows to touch any path, and tell the owner in your outbox). Otherwise take the next unit: a message addressed to you that another lane is waiting on, else the next item in your task file's units list. Edit only the paths your lane owns, plus the smallest needed edits to shared files. Then run the tests.
+5. Green: commit, have a reviewer subagent check the diff against IDEA.md and your lane contract ("find the three most likely ways this is wrong for a real user, and check each"), fix any blockers, run the tests again, pull, then push to `main`. Run the reviewer in the foreground if you can. If it runs in the background you are resumed when it reports; then finish this step and continue with step 6. Ending your turn ends the run unless a subagent is still running, so never end it to wait for anything else. Red: write the attempt and the reason under Tried in your task file, then discard the unit's uncommitted changes. The same failure twice means the stuck protocol (§9.3); its last step is `.ai/lanes/{{lane}}/BLOCKED.md`.
+6. A pushed unit does not end the run. Go straight back to step 4 with the next unit and keep going until one of these is true: 40 minutes have passed since the start time (check `date -u` after each push), your context is about 60% full, your lane has no units left, or every remaining unit is blocked. Each unit still gets its own tests, review and push.
+7. Then run the handoff (.ai/method.md section 9.1) in your task file so a fresh run with zero memory can continue at full quality, and add a line to your outbox for any lane affected by what you shipped (new types, routes, files they are waiting for). If every done-when in your lane contract passes and the reviewer finds no blockers, follow "Lane finished" in CLAUDE.md instead: read the other lanes' outboxes first, run the retro, write `.ai/lanes/{{lane}}/DONE.md`. Commit, push to `main`, and stop.
+
+Never spend money, sign up for anything, create accounts, publish anything (no package publish, no posting, no repo visibility or settings changes, no releases, no version bump), add API keys, secrets, ads, analytics or tracking, copy other projects' content without a compatible licence, force-push, rewrite history, edit another lane's paths beyond the "main stays green" rule, or touch anything outside this repository.

package/runners/routine/prompt.md

@@ -1,7 +1,7 @@
 You are one scheduled run of the build loop for this repository ({{name}}). Nobody is watching; the owner reads the results later. Read CLAUDE.md and follow it exactly, especially "Unattended mode". IDEA.md is the brief. Your task file is `.ai/task.md`.
 
 0. Run `date -u` and note it as this run's start time. Run `git checkout main && git pull --ff-only`. Every commit goes to `main` and is pushed with `git push origin main`. Never create or push a `claude/` branch: the next run starts from `main` and would never see it. If a push is rejected, run `git pull --rebase`, re-run the checks if incoming commits touched code, and push again.
-1. Session lock: if `.ai/session.lock` holds a UTC time less than 90 minutes old, another session owns the repo. Reply "Nothing to do" and stop. If the file is older than that, it is stale: ignore it.
+1. Session lock: if `.ai/session.lock` holds a UTC time less than 90 minutes old, another session owns the repo, unless the lock is your own (the runner's run note says so when the loop runner created it). Otherwise reply "Nothing to do" and stop. If the file is older than that, it is stale: ignore it.
 2. If `DONE.md` or `BLOCKED.md` exists, reply "Nothing to do" and stop.
 3. Run the install command from CLAUDE.md (`npm install` unless it says otherwise). If it fails, write `BLOCKED.md` with the error and stop.
 4. If `.ai/task.md` exists, run the resume protocol (.ai/method.md §9.2) and add 1 to its `Run: N / 30` counter. When the counter reaches 30, write `BLOCKED.md` saying "run budget reached", push, and stop. If there is no task file, write one from IDEA.md first.

package/templates/chrome-extension/extension/manifest.json

@@ -3,7 +3,23 @@
   "name": "{{name}}",
   "version": "0.1.0",
   "description": "A Chrome extension built and verified by an unattended Compounding Loop.",
-  "action": { "default_popup": "popup.html", "default_title": "{{name}}" },
-  "background": { "service_worker": "background.js" },
-  "permissions": ["storage"]
+  "action": {
+    "default_popup": "popup.html",
+    "default_title": "{{name}}",
+    "default_icon": {
+      "16": "icons/icon16.png",
+      "48": "icons/icon48.png"
+    }
+  },
+  "background": {
+    "service_worker": "background.js"
+  },
+  "permissions": [
+    "storage"
+  ],
+  "icons": {
+    "16": "icons/icon16.png",
+    "48": "icons/icon48.png",
+    "128": "icons/icon128.png"
+  }
 }

package/templates/chrome-extension/gitignore

@@ -3,4 +3,4 @@ test-results/
 playwright-report/
 .env*
 .ai/runs.jsonl
-.ai/session.lock
+**/session.lock

package/templates/lanes/README.md

@@ -0,0 +1,23 @@
+# Lane templates
+
+Files `loop init --lanes` copies into a repository that runs several lanes. A lane is one scheduled run that owns one part of the codebase (see `method/COMPOUNDING_LOOP.md`, chapter "Lanes").
+
+| File | Written to | Once per |
+|---|---|---|
+| `task.md` | `.ai/lanes/<lane>/task.md` | lane |
+| `outbox.md` | `.ai/lanes/<lane>/outbox.md` | lane |
+| `control-room.md` | `.ai/control-room.md` | repo |
+| `claude-section.md` | appended to `CLAUDE.md` and `AGENTS.md`; `loop init --lanes` wraps it in its own markers, so a second run replaces the block | repo |
+| `ci-check-lanes.yml` | `.github/workflows/check-lanes.yml` | repo |
+
+## Placeholders
+
+Written `{{lane}}`. `loop init --lanes` fills only the ones listed below (`control-room.md` and `ci-check-lanes.yml` have none). A template never ships with one unfilled: `tests/unit/kit/lanes-templates.test.ts` fills every documented placeholder and fails on any `{{x}}` left over. GitHub Actions expressions (`${{ ... }}`) are not placeholders and are left alone.
+
+| Placeholder | Meaning | Example |
+|---|---|---|
+| `{{lane}}` | Lane name (lowercase letters, digits, `-`) | `api` |
+| `{{owns}}` | The lane's owned globs, comma separated | `src/api/**, tests/api/**` |
+| `{{lanes}}` | All lane names, comma separated | `api, web, docs` |
+
+`.ai/lanes.json` stays the machine-readable source of truth; `claude-section.md` points to it instead of copying the lane table, so the two cannot drift.

package/templates/lanes/ci-check-lanes.yml

@@ -0,0 +1,38 @@
+# Fails a push or pull request whose commits touch another lane's paths.
+# Needs compounding-loop 0.2.0 or later (the release that adds `check-lanes`). Copy to .github/workflows/check-lanes.yml. Commits without a `Lane:` trailer are reported, not failed.
+name: check-lanes
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check-lanes:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # a shallow clone skips its oldest commit
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Check lane ownership
+        env:
+          EVENT: ${{ github.event_name }}
+          BASE_REF: ${{ github.base_ref }}
+          BEFORE: ${{ github.event.before }}
+          SHA: ${{ github.sha }}
+        run: |
+          if [ "$EVENT" = "pull_request" ]; then
+            RANGE="origin/$BASE_REF..HEAD"
+          elif git cat-file -e "$BEFORE^{commit}" 2>/dev/null; then
+            RANGE="$BEFORE..$SHA" # not the case on a first push or after a force-push
+          else
+            RANGE="$SHA~1..$SHA"
+          fi
+          npx --yes compounding-loop check-lanes --range "$RANGE"

package/templates/lanes/claude-section.md

@@ -0,0 +1,17 @@
+## Lanes
+
+This repository is built by parallel **lanes**. Lanes in this repo: {{lanes}}. Each lane is a scheduled run that owns one part of the codebase. `.ai/lanes.json` says which paths each lane owns and which files are shared; read it first. Each lane's task file is `.ai/lanes/<lane>/task.md`.
+
+- **Edit only the paths your lane owns.** Read anything. **Shared files** (`shared` in `.ai/lanes.json`) may be edited by any lane, with the smallest possible edit.
+- **Commit trailer:** every commit message ends with a line `Lane: <your lane>` (the control room uses `Lane: control`). `loop check-lanes` fails a commit that touches another lane's paths.
+- **Talking to other lanes:** write only to your own `.ai/lanes/<you>/outbox.md`, newest first, `YYYY-MM-DD HH:MM UTC · to <lane|all> · message`. At the start of each run read every other lane's outbox and `.ai/control-room.md` for messages to you or `all`, and act on them or say in your task file why not.
+- **Main stays green.** If the tests fail on a fresh pull before you change anything, fixing that is your first unit, whichever lane owns the failure. Make the smallest fix, commit it with the trailer `Lane: control` (the only trailer `loop check-lanes` lets touch any path), and tell the owning lane in your outbox.
+- **Git:** work on `main`. Start every run with `git checkout main && git pull --ff-only`, pull again right before each push, and on a rejected push `git pull --rebase`. If a rebase conflicts in a file you do not own, `git rebase --abort`, record it under Tried, pull fresh, redo your small change on top. Never force-push.
+- **Run budget:** your lane's task file holds `Run: N / LIMIT`. Add 1 at the start of every run; at the limit write `.ai/lanes/<lane>/BLOCKED.md` ("run budget reached") and stop.
+- **Stop files:** if root `DONE.md` or `BLOCKED.md`, or your lane's `DONE.md` or `BLOCKED.md`, exists at the start of a run, do nothing and stop. A lane writes its own `DONE.md` when every done-when in its contract passes and the reviewer finds no blockers. Root `DONE.md` is written only by the control room.
+- **Stuck:** the same failure twice means the stuck protocol; its last step is the lane's `BLOCKED.md` with what you tried, the specific question and your best guess.
+- **Review before every push to `main`:** the tests must pass, then a reviewer subagent that did not write the code checks the diff against the brief ("find the three most likely ways this is wrong for a real user, and check each"). Fix blockers first.
+- **Questions:** no human is watching. Decide from the brief and common sense, write the decision and the reason under **Decisions** in your task file, and pick the option that is easiest to reverse.
+- **Lane finished:** read the other lanes' outboxes first; if anyone waits on you, do that before writing `DONE.md`.
+- **Shared files and shared types** are add-only for other lanes: add fields, never rename or remove, and say so in your outbox.
+- **Never:** spend money, sign up for anything, publish anything, add secrets, telemetry or tracking, or touch anything outside this repository.

package/templates/lanes/control-room.md

@@ -0,0 +1,3 @@
+# Control room notes
+
+Written only by the control room routine (commits trailer `Lane: control`). Every lane reads this file at the start of a run. Newest first. Format: `YYYY-MM-DD HH:MM UTC · to <lane|all> · message`.

package/templates/lanes/outbox.md

@@ -0,0 +1,5 @@
+# Outbox: {{lane}}
+
+Written only by the {{lane}} lane. Newest first. Format: `YYYY-MM-DD HH:MM UTC · to <lane|all> · message`.
+Every lane reads every outbox at the start of a run. Say what you shipped that another lane waits on (new types, routes, files), and what you need from them. Point to code with `path:line`; do not paste it.
+

package/templates/lanes/task.md

@@ -0,0 +1,36 @@
+# Lane: {{lane}}
+
+Run: 0 / 20
+Status: not started
+
+## Contract
+**Goal:** <one sentence: what this lane delivers>
+**Owns (globs from `.ai/lanes.json`):** {{owns}}
+**Done when:**
+- `npm test` passes (or the project's test command from CLAUDE.md).
+- <a checkable line per deliverable, each provable by a command>
+**Constraints:** edit only the paths you own, plus the smallest edit to shared files (CLAUDE.md "Lanes"). Read anything.
+**Out of scope:** <what belongs to another lane>
+
+## Units, in order
+1. **Audit** (`.ai/audit/{{lane}}.md`): review your area as a demanding specialist; findings ranked blocker / major / minor, each with evidence and a one-line fix.
+2. <first real unit>
+
+## Decisions
+<decision → reason. Written instead of asking a human.>
+
+## Confirmed
+<fact → how we know>
+
+## Guesses
+<assumption → what would prove it. Never treat a GUESS from an earlier window as fact.>
+
+## Tried
+<attempt → exact error → why it failed>
+
+## Don't
+- Edit paths another lane owns (a fix to a red `main` is the one exception; say so in your outbox).
+- Change the Operating Card, the version, or publish anything.
+
+## Handoff
+<Rewritten at the end of every run: commit, whether the tree is clean, the single next step, what to read first.>

package/templates/static-site/.ai/loop-prompt.md

@@ -1,7 +1,7 @@
 You are one run of an unattended build loop for this repository. Nobody is watching. Follow CLAUDE.md exactly, especially "Unattended mode".
 
 0. Run `git checkout main && git pull --ff-only`. Every commit in this run goes to `main` and is pushed with `git push origin main`. Never push to a `claude/` branch: the next run starts from `main` and would never see it.
-1. If `.ai/session.lock` holds a UTC time less than 90 minutes old, another session owns the repo: reply "Nothing to do" and stop. If `DONE.md` or `BLOCKED.md` exists, reply "Nothing to do" and stop.
+1. If `.ai/session.lock` holds a UTC time less than 90 minutes old, another session owns the repo (unless the lock is your own: the run note at the end of this prompt says so when the loop runner created it): reply "Nothing to do" and stop. If `DONE.md` or `BLOCKED.md` exists, reply "Nothing to do" and stop.
 2. Run `npm install`, then `npx playwright install chromium`. If the download is blocked, see "Commands" in CLAUDE.md.
 3. If `.ai/task.md` exists, run the resume protocol (.ai/method.md §9.2) and add 1 to its `Run: N / 30` counter. If the counter has reached its limit, follow "Run budget" in CLAUDE.md. Otherwise start the task from IDEA.md.
 4. Do one unit of work, then run `npm test`.

package/templates/static-site/gitignore

@@ -3,4 +3,4 @@ test-results/
 playwright-report/
 .env*
 .ai/runs.jsonl
-.ai/session.lock
+**/session.lock