compounding-loop 0.0.0-stage → 0.1.0

package/method/stuck-protocol.md

@@ -0,0 +1,12 @@
+# Stuck protocol
+
+Triggered by the same failure twice, or by two runs with no progress toward done-when. Do not retry a variant.
+
+1. Stop. Record the attempt under Tried: what you did, the exact error, why it failed.
+2. Search `.ai/index.md` for the error text.
+3. Write down every assumption you are making. Move the ones you never tested to Guesses.
+4. Test the weakest assumption with the cheapest experiment.
+5. Try a structurally different approach, not a variant of what failed.
+6. Still stuck, unattended: write `BLOCKED.md` (what you tried, the specific question, your best guess), commit, push and stop. With a human present: ask the same question.
+
+Hard cap: a task that reaches about 5 runs without the checks passing goes to `BLOCKED.md`.

package/method/task-template.md

@@ -0,0 +1,41 @@
+# TASK: <name>
+
+Run: 0 / 30
+Status: not started
+
+## Contract
+**Goal:** build v1 of IDEA.md (replace with one sentence per task)
+**Done when:** derive from IDEA.md: `<command>` passes; <other checks>
+**Constraints:** <what must not change, what must be reused>
+**Out of scope:** <what not to touch>
+
+## Current state
+(rewrite every window)
+- Branch / commit: <branch> @ <hash>, clean
+- Checks: <passing / failing, names>
+- Next step: <exactly one step>
+- Read first: <path:lines>, <K-ids>
+
+## Confirmed
+(facts proven by a command or test, with how we know)
+- <fact> (seen in <test / log / commit>)
+
+## Guesses
+(unproven; test before building on them, never treat as fact in a later run)
+- <hypothesis> (test: <cheapest experiment>)
+
+## Tried
+(append-only: approach → result → why)
+1. <approach> → <result> → <why it failed>
+
+## Decisions
+(decision · reason · how to reverse)
+
+## Don't
+- <thing not to retry> (Tried #<n>)
+
+## Handoff
+(each run ends by writing: where it stopped, the exact next step, anything half-done)
+
+## promote?
+(for the retro: general lessons worth keeping)

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "compounding-loop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Write the brief, check back tomorrow: unattended, verified Claude Code build loops with a local dashboard.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "loop": "bin/loop.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "templates/",
+    "method/",
+    "runners/",
+    "plugin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Minntooos/compounding-loop.git"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "autonomous",
+    "dashboard",
+    "cli",
+    "context-engineering"
+  ],
+  "scripts": {
+    "check": "node scripts/check.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p web/tsconfig.json --noEmit",
+    "unit": "vitest run",
+    "build": "tsc -p tsconfig.build.json && node demo/copy-demo.mjs && vite build",
+    "e2e": "playwright test",
+    "test": "npm run check && npm run typecheck && npm run unit && npm run build && npm run e2e",
+    "dev:web": "vite",
+    "preview": "vite preview --port 4173 --strictPort"
+  },
+  "devDependencies": {
+    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource-variable/jetbrains-mono": "^5.3.0",
+    "@playwright/test": "^1.64.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@tanstack/react-query": "^5.104.1",
+    "@types/node": "^26.6.4",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "cmdk": "^1.1.1",
+    "lucide-react": "^1.52.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "recharts": "^3.10.1",
+    "tailwindcss": "^4.3.3",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.3",
+    "vitest": "^5.0.3",
+    "yaml": "^2.9.1"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "@hono/node-server": "^2.1.4",
+    "commander": "^15.0.0",
+    "hono": "^4.13.13"
+  }
+}

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

@@ -0,0 +1,7 @@
+{
+  "name": "compounding-loop",
+  "version": "0.1.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/plugin/commands/handoff.md

@@ -0,0 +1,10 @@
+---
+description: Write the handoff so a fresh session with zero memory can continue at full quality
+---
+
+Run the handoff protocol (method section 9.1) for the current task.
+
+1. Run the checks and record the real result (counts and failing names) in `.ai/task.md` under "Current state".
+2. Rewrite "Current state": branch and commit, whether the tree is clean, the single next step, and what to read first (`path:line`, knowledge ids). Do not copy code into the file.
+3. Make sure every new fact is under Confirmed (with how we know) or Guesses (with the cheapest test). Move anything half-done into the handoff as "half-done: ...".
+4. Commit the task file. Then tell the user the next window is ready and name the first thing it will do.

package/plugin/commands/loop-init.md

@@ -0,0 +1,13 @@
+---
+description: Set up this repository for the Compounding Loop (operating card, task file, knowledge index)
+---
+
+Set this repository up for unattended, verified build loops.
+
+1. If the `loop` CLI is available, run `npx compounding-loop init` and report what it created. Otherwise do the steps below by hand.
+2. Make sure these exist, creating only what is missing and never overwriting the user's files:
+   - `CLAUDE.md` containing the Operating Card (the "Operating Card (the Compounding Loop)" section).
+   - `.ai/method.md`, `.ai/index.md`, `.ai/knowledge/`, `.ai/log.md`.
+   - `.ai/task.md` with `Run: 0 / 30`, a Contract with a "Done when" that a command can check, and empty Confirmed, Guesses, Tried and Decisions sections.
+3. Ask the user for the one-sentence goal and the command that proves it works (for example `npm test`) if `IDEA.md` or the task contract does not already say.
+4. Finish with the exact command the user should run next, and do not start the build yourself.

package/plugin/commands/retro.md

@@ -0,0 +1,11 @@
+---
+description: Run the retro after the checks pass - promote lessons, flag stale entries, log the task
+---
+
+Run the retro (method section 12) now that the checks pass.
+
+1. Run the checks once more and confirm they pass. If they do not, stop and say so; the task is not done.
+2. Read `.ai/task.md`. List the lessons worth keeping beyond this task (Confirmed facts that will bite again, gotchas, decisions). For each, propose a knowledge entry with its triggers (files, error text, commands, topics) and evidence.
+3. Flag existing entries in `.ai/index.md` that this task showed to be wrong or stale. Do not delete or rewrite a CONFIRMED entry without new evidence.
+4. Add one line to `.ai/log.md`: date, task, checks result, number of windows, what was learned.
+5. After the user approves the proposed entries, write them, update `.ai/index.md`, and delete `.ai/task.md`.

package/plugin/commands/stuck.md

@@ -0,0 +1,10 @@
+---
+description: Run the stuck protocol when the same failure has happened twice
+---
+
+You have hit the same failure twice. Stop retrying variants and run the stuck protocol (method section 9.3).
+
+1. Write the failure down under Tried in `.ai/task.md`: what you did, the exact error, and why you think it failed. Search `.ai/index.md` for the error text.
+2. List what you have not yet checked: assumptions you treated as fact (move them to Guesses), the cheapest experiment that would split the possible causes, and whether a subagent could read the logs or docs for you.
+3. Run that one experiment. If it explains the failure, fix it and record the cause as Confirmed.
+4. If it does not, and unattended: write `BLOCKED.md` (what you tried, the specific question, your best guess), commit, push and stop. If a human is present: report the question and your best guess, and wait.

package/runners/github-actions/loop.yml

@@ -0,0 +1,51 @@
+# Compounding Loop: scheduled build run 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`).
+#      Never write a key into this file or the repository.
+#   2. Copy this file to .github/workflows/loop.yml.
+#   3. Pick a staggered minute in `cron` below (avoid minute 0).
+name: compounding-loop
+
+on:
+  schedule:
+    - cron: "17 * * * *"
+  workflow_dispatch: {}
+
+# Two runs on one branch would fight; queue instead of cancelling a run mid-push.
+concurrency:
+  group: compounding-loop
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: anthropics/claude-code-action@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            You are one scheduled run of the build loop for this repository. Nobody is watching.
+            Read CLAUDE.md and follow "Unattended mode" exactly. IDEA.md is the brief.
+            If .ai/session.lock is less than 90 minutes old, or DONE.md or BLOCKED.md exists, reply "Nothing to do" and stop.
+            Add 1 to the Run counter in .ai/task.md (Run: N / 30); at 30 write BLOCKED.md ("run budget reached") and stop.
+            Do units of work, run the tests after each, and push to main only when they pass.
+            Finish with the handoff in .ai/task.md. Never publish, spend money, or add secrets or tracking.
+          claude_args: >-
+            --max-turns 200
+            --allowedTools "Bash,Edit,Write,Read,Glob,Grep,Task"

package/runners/local/README.md

@@ -0,0 +1,8 @@
+# Local runner
+
+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.
+- **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/crontab.txt

@@ -0,0 +1,6 @@
+# Compounding Loop on macOS or Linux: run one round at minute 17 of every hour.
+# Install with `crontab -e` and paste the line below, replacing /path/to/repo.
+# `loop run` skips the round when DONE.md / BLOCKED.md exists; the prompt itself checks the session lock.
+# Cron has a minimal PATH: if `loop` or `claude` is not found, use their full paths. For unattended
+# edits add `--skip-permissions` (see `loop run --help`) only in a repository you trust.
+17 * * * * cd /path/to/repo && loop run >> .ai/loop-cron.log 2>&1

package/runners/local/task-scheduler.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>Compounding Loop: run one round of the build loop every hour.</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <CalendarTrigger>
+      <Repetition>
+        <Interval>PT1H</Interval>
+        <StopAtDurationEnd>false</StopAtDurationEnd>
+      </Repetition>
+      <StartBoundary>2026-01-01T00:17:00</StartBoundary>
+      <Enabled>true</Enabled>
+      <ScheduleByDay>
+        <DaysInterval>1</DaysInterval>
+      </ScheduleByDay>
+    </CalendarTrigger>
+  </Triggers>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <ExecutionTimeLimit>PT90M</ExecutionTimeLimit>
+    <Enabled>true</Enabled>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>loop.cmd</Command>
+      <Arguments>run</Arguments>
+      <WorkingDirectory>C:\path\to\repo</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>

package/runners/routine/README.md

@@ -0,0 +1,19 @@
+# Claude Code routine runner
+
+A routine is a scheduled Claude Code session in the cloud. It runs `prompt.md` against your repository on a cron schedule, with nobody watching.
+
+## Set up
+
+1. Copy `prompt.md`. Its only placeholder is `{{name}}`, your project name. The install and test commands come from your `CLAUDE.md`.
+2. In Claude Code on the web, create a routine for the repository and paste the prompt. Give it write access to `main` only.
+3. Pick a schedule (see below). `loop` generates a staggered cron line for you.
+
+## Staggered cron
+
+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.
+
+## Safety
+
+The prompt never publishes, spends money or stores a secret. The routine uses your Claude account; no API key goes into the 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. 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,9 @@
+{
+  "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}}" },
+  "background": { "service_worker": "background.js" },
+  "permissions": ["storage"]
+}

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
+.ai/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/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`.