compounding-loop 0.1.0 → 0.4.0

package/runners/routine/prompt.md

@@ -1,8 +1,8 @@
 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.
-2. If `DONE.md` or `BLOCKED.md` exists, reply "Nothing to do" and stop.
+0. Run `date -u` and note it as this run's start time. Run `git checkout main && git pull --ff-only`. If that pull fails because local `main` and `origin/main` have diverged or look unrelated, the sandbox started from a stale cached clone; origin `main` is never rewritten, so do not reset anything: run `git fetch origin main && git switch -c lane-run FETCH_HEAD`, work there, and wherever these steps say pull or push use `git pull --rebase origin main` and `git push origin HEAD:main`. 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, 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. Pause: if `.ai/PAUSED` exists, the owner paused the loop: reply "Paused" 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.
 5. 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"). Otherwise take the next unit from the task file. Do one unit at a time.

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,20 @@
+## 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. If `git pull --ff-only` fails because the clone started from a stale cached copy (local `main` and `origin/main` diverged or unrelated), origin `main` was not rewritten: check `git log origin/main`, run `git fetch origin main && git switch -C lane-run FETCH_HEAD`, work on that branch, and from then on pull with `git pull --rebase origin main` and push with `git push origin HEAD:main`.
+- **Run log:** every run that gets past the stop checks ends, pushed or not (also on failing tests or BLOCKED), by appending one line to `.ai/lanes/<your lane>/runs.jsonl` with `loop runs log --lane <your lane> --units <unit names> --passed N --failed N --pushed` (or `--no-pushed`, optionally `--note "why"`), committed in your final commit, so it is pushed with it. The dashboard shows a scheduled slot with no line and no commit as "no run recorded".
+- **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.
+- **Pause:** if `.ai/PAUSED` exists, the owner paused the loop (`loop pause` writes it, `loop resume` removes it): reply "Paused" and stop. The control room stops too.
+- **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.
+- **Claims:** if `.ai/lanes/<your lane>/claim` exists (one line, `name · expires <UTC time>`), names someone other than you (a scheduled run has no name, so any unexpired claim stops it), and its expiry (an ISO UTC timestamp, compared with `date -u`) is in the future, a teammate is working that lane: reply "Nothing to do" and stop. An expired claim counts as none (leave the file; `loop claim` overwrites it).
+- **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. Name finished units as "units 1-3 done" so `loop next` can skip them, and list what you shipped that another lane waits on (also in your outbox).>

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.
+0. Run `git checkout main && git pull --ff-only`. If the pull fails because the clone started from a stale copy (diverged or unrelated history), origin `main` was not rewritten: run `git fetch origin main && git switch -C loop-run FETCH_HEAD`, work there, and push with `git push origin HEAD:main`. Then, on the fresh code: if `.ai/PAUSED` exists, the owner paused the loop: reply "Paused" and stop. 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 (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/CLAUDE.md

@@ -104,7 +104,9 @@ No human is watching. The owner reads the results later. These rules replace "as
 - **Stuck protocol, last step:** there's no human to ask. Write `BLOCKED.md` (what you tried, the specific question, your best guess), commit it, push it, and stop.
 - **Run budget:** `.ai/task.md` holds `Run: N / LIMIT`. Add 1 at the start of every run. When N reaches LIMIT, write `BLOCKED.md` saying "run budget reached", push it, and stop.
 - **Finished:** when every done-when in the contract passes and the reviewer finds no blockers, run the retro, write `DONE.md`, delete `.ai/task.md`, push and stop. `DONE.md` holds: what was built (each page and its target keyword), test results, anything you were unsure of, and the owner's launch checklist: check that the Netlify site serves the address in IDEA.md, add that address to Search Console as a URL-prefix property, submit `/sitemap.xml`, and buy the domain named in IDEA.md once there's budget for it. End with the 10 best next pages to build, ranked by search demand and how weak the current results are.
+- **If `.ai/PAUSED` exists at the start of a run:** the owner paused the loop (`loop pause`); reply "Paused" and stop.
 - **If `DONE.md` or `BLOCKED.md` exists at the start of a run:** do nothing and stop.
+- **Stale clone:** if `git pull --ff-only` fails because the clone started from an old copy (diverged or unrelated history), origin `main` was not rewritten: check `git log origin/main`, run `git fetch origin main && git switch -C loop-run FETCH_HEAD`, work there, and push with `git push origin HEAD:main`.
 
 **Never, even if it seems helpful**
 - Spend money, sign up for anything, or create accounts.

package/templates/static-site/gitignore

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