compounding-loop 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,13 @@
+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, 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.
+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.
+6. After each unit run the test command from CLAUDE.md (`npm test` unless it says otherwise). Green: commit, have a reviewer subagent that did not write the code check the diff against IDEA.md ("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`. Red: write the attempt and the reason under Tried in the task file, then discard the unit's uncommitted changes. The same failure twice means the stuck protocol (§9.3); its last step is `BLOCKED.md`.
+7. A pushed unit does not end the run. Keep taking units 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, or no unit is left.
+8. Run the handoff (§9.1) in the task file so a fresh run with zero memory can continue at full quality. Commit it, push to `main`, and stop. If every done-when in the contract passes and the reviewer finds no blockers, run the retro (§12), write `DONE.md` (what was built, test results, anything unsure, the 10 best next improvements ranked by value) and push instead.
+
+Never spend money, sign up for anything, create accounts, publish anything, add API keys, secrets, ads, analytics or tracking, copy other projects' content without a compatible licence, force-push, rewrite history, or touch anything outside this repository.

package/templates/chrome-extension/CLAUDE.md

@@ -0,0 +1,18 @@
+# CLAUDE.md
+
+## Project core
+
+**What this is:** a Chrome extension (Manifest V3) built by an unattended AI loop. The goal and must-haves are in [IDEA.md](IDEA.md).
+
+**Commands**
+- Install: `npm install`, then `npx playwright install chromium`. If the download is blocked, `playwright.config.js` finds a preinstalled Chromium or system Chrome.
+- Test (the only judge of "done"): `npm test` = `check` + the Playwright extension test.
+- Fast: `npm run check` (manifest, permissions, MV3 rules; no browser).
+
+**Hard rules**
+- All extension files live in `extension/`. No inline scripts or handlers (MV3 blocks them) and no remotely hosted code.
+- Narrowest permissions only. Anything beyond those listed in IDEA.md needs the owner.
+- Service workers stop when idle: keep state in `chrome.storage`, never in module variables.
+- Every must-have in IDEA.md gets a Playwright test in `tests/` that loads the unpacked extension.
+- No telemetry, analytics, ads or calls home. No secrets in the repository.
+- Never publish to the Chrome Web Store, spend money or create accounts.

package/templates/chrome-extension/IDEA.md

@@ -0,0 +1,22 @@
+# IDEA
+
+> The owner fills this in. It's the only input the loop gets, so the more specific, the better.
+
+## The extension in one sentence
+<e.g. "A popup that shows how many tabs are open and closes duplicates.">
+
+## Who it's for
+<e.g. "People who keep dozens of tabs open while researching.">
+
+## Must have (v1)
+- <the main feature, observable in the popup or on a page>
+- <...>
+
+## Permissions allowed
+<List each permission the extension may ask for, and why. Anything not listed needs the owner.>
+
+## Nice to have (only after v1 works)
+- <...>
+
+## Run budget
+30

package/templates/chrome-extension/extension/background.js

@@ -0,0 +1,5 @@
+// Service workers stop after ~30 s idle, so keep state in chrome.storage, never in module variables.
+chrome.runtime.onInstalled.addListener(async () => {
+  const { clicks } = await chrome.storage.local.get('clicks');
+  if (clicks === undefined) await chrome.storage.local.set({ clicks: 0 });
+});

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

@@ -0,0 +1,25 @@
+{
+  "manifest_version": 3,
+  "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}}",
+    "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/extension/popup.css

@@ -0,0 +1,3 @@
+body { font: 14px system-ui, sans-serif; margin: 0; padding: 16px; width: 240px; }
+h1 { font-size: 16px; margin: 0 0 8px; }
+button { padding: 6px 12px; }

package/templates/chrome-extension/extension/popup.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{name}}</title>
+  <link rel="stylesheet" href="popup.css">
+</head>
+<body>
+  <h1>{{name}}</h1>
+  <p>Clicks so far: <strong id="count">0</strong></p>
+  <button id="click" type="button">Click me</button>
+  <script type="module" src="popup.js"></script>
+</body>
+</html>

package/templates/chrome-extension/extension/popup.js

@@ -0,0 +1,16 @@
+// MV3 forbids inline scripts, so the popup logic lives in this file.
+const countEl = document.getElementById('count');
+const button = document.getElementById('click');
+
+async function render() {
+  const { clicks = 0 } = await chrome.storage.local.get('clicks');
+  countEl.textContent = String(clicks);
+}
+
+button.addEventListener('click', async () => {
+  const { clicks = 0 } = await chrome.storage.local.get('clicks');
+  await chrome.storage.local.set({ clicks: clicks + 1 });
+  await render();
+});
+
+render();

package/templates/chrome-extension/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+test-results/
+playwright-report/
+.env*
+.ai/runs.jsonl
+**/session.lock

package/templates/chrome-extension/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "check": "node scripts/check.mjs",
+    "test": "node scripts/test.mjs"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.48.0"
+  }
+}

package/templates/chrome-extension/playwright.config.js

@@ -0,0 +1,22 @@
+import { defineConfig, chromium } from '@playwright/test';
+import { existsSync, readdirSync } from 'node:fs';
+
+// Cloud sandboxes can block Playwright's own browser download. If that browser is missing, use a preinstalled
+// Playwright Chromium (Claude's cloud VMs have one in /opt/pw-browsers) or a system Chrome.
+const bundled = (() => { try { return chromium.executablePath(); } catch { return ''; } })();
+const preinstalled = ['/opt/pw-browsers', `${process.env.HOME}/.cache/ms-playwright`].flatMap((dir) => {
+  try {
+    return readdirSync(dir).filter((d) => /^chromium-\d+$/.test(d)).sort((a, b) => b.localeCompare(a, 'en', { numeric: true }))
+      .flatMap((d) => [`${dir}/${d}/chrome-linux64/chrome`, `${dir}/${d}/chrome-linux/chrome`]);
+  } catch { return []; }
+});
+const systemChrome = [process.env.CHROME_PATH, ...preinstalled, '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/opt/google/chrome/chrome']
+  .find((p) => p && existsSync(p));
+// Read by tests/popup.spec.js, which launches its own persistent context (extensions need one).
+process.env.CL_CHROME = bundled && existsSync(bundled) ? bundled : systemChrome ?? '';
+
+export default defineConfig({
+  testDir: 'tests',
+  timeout: 30_000,
+  workers: 1,
+});

package/templates/chrome-extension/scripts/check.mjs

@@ -0,0 +1,51 @@
+// Fast structural checks for extension/. No dependencies, no browser. Messages say how to fix each problem.
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const DIR = resolve(process.argv[2] ?? 'extension');
+const errors = [];
+const fail = (file, msg) => errors.push(`${file}: ${msg}`);
+
+const manifestPath = join(DIR, 'manifest.json');
+let manifest = null;
+try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')); } catch { fail('manifest.json', 'missing or not valid JSON.'); }
+
+if (manifest) {
+  if (manifest.manifest_version !== 3) fail('manifest.json', '"manifest_version" must be 3; Chrome no longer accepts version 2.');
+  for (const key of ['name', 'version', 'description']) if (!manifest[key]) fail('manifest.json', `add "${key}".`);
+  if (manifest.version && !/^\d+(\.\d+){0,3}$/.test(manifest.version)) fail('manifest.json', `"version" ${manifest.version} must be 1-4 dot-separated integers.`);
+  if (manifest.description && manifest.description.length > 132) fail('manifest.json', 'description is over 132 characters; the Chrome Web Store rejects it.');
+
+  const files = [manifest.action?.default_popup, manifest.background?.service_worker, ...Object.values(manifest.icons ?? {})].filter(Boolean);
+  for (const f of files) if (!existsSync(join(DIR, f))) fail('manifest.json', `references "${f}", which does not exist in extension/.`);
+
+  // Least privilege: broad host access and risky permissions need a reason from the owner.
+  const risky = [...(manifest.host_permissions ?? []), ...(manifest.permissions ?? [])].filter((p) => /<all_urls>|\*:\/\/\*\/\*|^(tabs|history|cookies|webRequest|debugger)$/.test(p));
+  if (risky.length) fail('manifest.json', `broad permissions (${risky.join(', ')}). Use the narrowest permission that works, or ask the owner.`);
+  if (manifest.content_security_policy?.extension_pages && /unsafe-(inline|eval)/.test(manifest.content_security_policy.extension_pages)) fail('manifest.json', 'CSP allows unsafe-inline or unsafe-eval.');
+}
+
+// MV3 blocks inline scripts and remote code.
+const popup = manifest?.action?.default_popup;
+if (popup && existsSync(join(DIR, popup))) {
+  const html = readFileSync(join(DIR, popup), 'utf8');
+  for (const [tag] of html.matchAll(/<script\b[^>]*>/gi)) {
+    const src = tag.match(/\ssrc="([^"]+)"/i)?.[1];
+    if (!src) fail(popup, 'inline <script>. Move it to a .js file; MV3 blocks inline scripts.');
+    else if (/^(https?:)?\/\//i.test(src)) fail(popup, `remote script "${src}". MV3 forbids remotely hosted code; bundle it in extension/.`);
+  }
+  if (/\son[a-z]+\s*=\s*["']/i.test(html)) fail(popup, 'inline event handler. Use addEventListener in a .js file.');
+}
+
+// Secrets must never be committed.
+const SECRET = /(\bsk-(ant-)?[A-Za-z0-9_-]{20,}|\bAKIA[0-9A-Z]{16}|\bgh[pousr]_[A-Za-z0-9]{30,}|-----BEGIN [A-Z ]*PRIVATE KEY-----)/;
+for (const f of ['background.js', 'popup.js', 'popup.html', 'manifest.json']) {
+  const p = join(DIR, f);
+  if (existsSync(p) && SECRET.test(readFileSync(p, 'utf8'))) fail(f, 'looks like it contains an API key or private key. Remove it.');
+}
+
+if (errors.length) {
+  console.error(`check: ${errors.length} problem(s)\n- ${errors.join('\n- ')}`);
+  process.exit(1);
+}
+console.log('check: OK');

package/templates/chrome-extension/scripts/test.mjs

@@ -0,0 +1,59 @@
+// `npm test`: runs each test step in order (stopping at the first failure, like `&&`) and writes the
+// totals to .ai/last-test.json, which the Compounding Loop dashboard's "failing tests" health check reads.
+// Commit that file with your work so the dashboard sees it whichever machine ran the tests.
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Totals from test-runner output: node:test (`ℹ pass 3` or TAP `# pass 3`) and Playwright (`12 passed`, `1 failed`). */
+export function countResults(output) {
+  const plain = output.replace(/\x1b\[[0-9;]*m/g, '');
+  const sum = (re) => [...plain.matchAll(re)].reduce((n, m) => n + Number(m[1]), 0);
+  const passed = sum(/^\s*(?:ℹ|#) pass (\d+)\s*$/gm) + sum(/^\s*(\d+) passed\b/gm);
+  const failed = sum(/^\s*(?:ℹ|#) fail (\d+)\s*$/gm) + sum(/^\s*(\d+) failed\b/gm);
+  return passed + failed > 0 ? { passed, failed } : undefined;
+}
+
+/** Steps this repo has, as [label, node arguments]. Node runs them directly, so no shell or .cmd shim is involved. */
+function steps() {
+  const list = [['check', ['scripts/check.mjs']]];
+  if (existsSync('tests/unit')) list.push(['unit', ['--test', 'tests/unit/**/*.test.mjs']]);
+  if (existsSync('playwright.config.js')) list.push(['browser', [path.join('node_modules', '@playwright', 'test', 'cli.js'), 'test', ...process.argv.slice(2)]]);
+  return list;
+}
+
+function run(args) {
+  return new Promise((resolve) => {
+    let output = '';
+    const child = spawn(process.execPath, args, { stdio: ['inherit', 'pipe', 'pipe'] });
+    child.stdout.on('data', (chunk) => { output += chunk; process.stdout.write(chunk); });
+    child.stderr.on('data', (chunk) => { output += chunk; process.stderr.write(chunk); });
+    child.on('error', (error) => { output += String(error); resolve({ code: 1, output }); });
+    child.on('close', (code) => resolve({ code: code ?? 1, output }));
+  });
+}
+
+async function main() {
+  const total = { passed: 0, failed: 0 };
+  let code = 0;
+  for (const [label, args] of steps()) {
+    const result = await run(args);
+    // A step without countable output (the check script) counts as one test.
+    const counts = countResults(result.output) ?? (result.code === 0 ? { passed: 1, failed: 0 } : { passed: 0, failed: 1 });
+    if (result.code !== 0 && counts.failed === 0) counts.failed = 1;
+    total.passed += counts.passed;
+    total.failed += counts.failed;
+    if (result.code !== 0) {
+      console.error(`\n${label} failed (exit ${result.code}); later steps skipped.`);
+      code = result.code;
+      break;
+    }
+  }
+  mkdirSync('.ai', { recursive: true });
+  writeFileSync(path.join('.ai', 'last-test.json'), `${JSON.stringify({ ...total, at: new Date().toISOString() })}\n`);
+  console.log(`\n${total.passed} passed, ${total.failed} failed (written to .ai/last-test.json)`);
+  process.exitCode = code;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/templates/chrome-extension/tests/popup.spec.js

@@ -0,0 +1,37 @@
+// Loads the unpacked extension in a real Chromium and drives its popup.
+import { test, expect, chromium } from '@playwright/test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const extension = resolve('extension');
+
+test('popup counts clicks and keeps them in chrome.storage', async () => {
+  const userDataDir = mkdtempSync(join(tmpdir(), 'ext-'));
+  const context = await chromium.launchPersistentContext(userDataDir, {
+    ...(process.env.CL_CHROME ? { executablePath: process.env.CL_CHROME } : {}),
+    args: [`--disable-extensions-except=${extension}`, `--load-extension=${extension}`, '--headless=new'],
+  });
+  try {
+    const worker = context.serviceWorkers()[0] ?? (await context.waitForEvent('serviceworker'));
+    const id = new URL(worker.url()).host;
+
+    const problems = [];
+    const popup = await context.newPage();
+    popup.on('pageerror', (e) => problems.push(`JS error: ${e.message}`));
+    popup.on('console', (m) => m.type() === 'error' && problems.push(`console error: ${m.text()}`));
+    await popup.goto(`chrome-extension://${id}/popup.html`);
+
+    await expect(popup.locator('h1')).toBeVisible();
+    await expect(popup.locator('#count')).toHaveText('0');
+    await popup.locator('#click').click();
+    await expect(popup.locator('#count')).toHaveText('1');
+
+    await popup.reload();
+    await expect(popup.locator('#count'), 'the count must survive a reload').toHaveText('1');
+    expect(problems, 'fix these errors').toEqual([]);
+  } finally {
+    await context.close();
+    rmSync(userDataDir, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,5 @@
+# Knowledge index
+
+One line per entry in `.ai/knowledge/`: `K-0001 · trigger (error text, file path or topic) · one-line lesson`.
+
+<!-- empty: the loop adds entries as it learns -->

package/templates/static-site/.ai/log.md

@@ -0,0 +1,3 @@
+# Log
+
+One line per finished task: `date · task · runs used · repeat errors · result`.

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

@@ -0,0 +1,10 @@
+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 (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`.
+5. Green: commit, have a reviewer subagent check the diff, fix any blockers, run `npm test` again, then push to `main`. Red: write the attempt and the reason under Tried in `.ai/task.md`, then discard the unit's uncommitted changes to the site and tests.
+6. Repeat 4–5 with the next unit while your context is under ~50% full.
+7. Then run the handoff (.ai/method.md §9.1): update `.ai/task.md` so a fresh run with zero memory of this one can continue at full quality. Commit it, push it to `main`, and stop.

package/templates/static-site/.ai/task.md

@@ -0,0 +1,27 @@
+# TASK: Build v1 of the site described in IDEA.md  (window 1)
+
+Run: 0 / 30
+
+## Contract
+<Window 1 writes this from IDEA.md before writing any site code.>
+- Goal:
+- Done when: `npm test` passes, including a feature test in `tests/` for every "Must have" in IDEA.md, unit tests for every file in `site/js/lib/`, and one page per keyword cluster in IDEA.md.
+- Constraints: see CLAUDE.md hard rules.
+- Out of scope: everything under "Nice to have" in IDEA.md.
+
+## Current state  (rewrite every window)
+- Fresh repo from the starter kit. Nothing built yet.
+- Next step: confirm `npm install` and `npm test` work in this environment (GUESS: Playwright's browser download may be blocked in cloud sandboxes; the config then falls back to a system Chrome. If neither works, record it under Decisions and use `npm run check && npm run unit` as the gate). Then write the contract and a plan in `.ai/plans/v1.md` (have a reviewer subagent attack the plan), then build page by page, the main tool first.
+- Read first: IDEA.md, CLAUDE.md.
+
+## Decisions  (made without the owner: decision → reason)
+
+## Confirmed  (with how we know)
+
+## Guesses  (test before building on them)
+
+## Tried  (append-only: approach → result → why)
+
+## Don't
+
+## promote?  (for the retro)

package/templates/static-site/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf