compounding-loop 0.5.0 → 0.6.0

package/dist/web/index.html

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" type="image/svg+xml" href="./favicon.svg" />
     <title>Compounding Loop</title>
-    <script type="module" crossorigin src="./assets/index-BozIcdeb.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-Te_olhNA.css">
+    <script type="module" crossorigin src="./assets/index-DDEAcJFt.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-C5q9d5-n.css">
   </head>
   <body>
     <div id="root"></div>

package/method/COMPOUNDING_LOOP.md

@@ -36,7 +36,7 @@
 > Copy this section into your always-loaded rules file. Keep it under ~60 lines.
 > The § numbers point to Part B of `COMPOUNDING_LOOP.md`.
 
-**Objective:** the most verified-correct results per minute of the human's attention. Tokens are the cheapest resource. A wrong result that looks right is the most expensive one.
+**Objective:** the most verified-correct results per minute of the owner's attention, from the smallest context that still passes. A wrong result that looks right is the most expensive one. Tokens are spent where they buy correctness (checks, review), not on re-learning what a recipe, a trigger or a check already knows.
 
 **Start of every session**
 1. Read `.ai/index.md`. Open a knowledge entry only when it's relevant to what you're doing.
@@ -79,11 +79,11 @@ Ranked by real cost, most expensive first:
 1. **Wrong results that look right.** You find out late, and everything built on top has to be redone.
 2. **Human attention.** Explaining, re-explaining, watching, reviewing.
 3. **Waiting time.**
-4. **Tokens and money.** The cheapest by far, and context that stays the same between calls is cached at a reduced rate.
+4. **Tokens.** Once cheap, now a real limit: a smaller context lets a smaller or local model do the job, and a subscription's five-hour limit is shared by every run. One loop spent about two thirds of its scheduled fires on idle runs; that is the same waste as re-reading what is already known.
 
-So the goal is **the most verified-correct results per minute of human attention.**
+So the goal is **the most verified-correct results per minute of human attention, from the smallest context that still passes.** Not "zero context": one recipe plus the checks that prove it.
 
-Trim context when it hurts quality (noise, stale notes, contradictions), not to save tokens. Compressing a note into keywords saves a few hundred tokens out of a session that uses 50–150k, and throws away the *why*, which is the part that prevents repeated mistakes. That's a net loss.
+Tokens are spent where they buy correctness (checks, review), not on re-learning what a recipe, a trigger or a check already knows. Trim context when it hurts quality (noise, stale notes, contradictions) and when a recipe or trigger can carry the lesson instead. Do not compress a note into keywords: that saves a few hundred tokens and throws away the *why*, which is the part that prevents repeated mistakes. Only a measured result counts as a claim that something got cheaper (§13).
 
 ### 2. Two ideas everything follows from
 
@@ -95,6 +95,7 @@ Trim context when it hurts quality (noise, stale notes, contradictions), not to
 |---|---|---|
 | Memory | Load every rule every session | A short index, plus triggers that fire at the moment of relevance (§7, §8) |
 | Context | One long window that slowly degrades | Fresh windows with handoffs; subagents for reading (§9, §10) |
+| Experience | Start every project from zero, or paste a whole old repo | One recipe for this kind of project: steps, traps and the check that proves each step (§7) |
 | Compute | The strongest model for everything | The cheapest tier that passes the checks (§10) |
 | Rules | Prose rules re-read forever | Automated checks that cost nothing until broken (§12) |
 | Human attention | Watching the agent work | Four touchpoints (§14) |
@@ -160,13 +161,14 @@ This is the biggest multiplier in the whole method. An agent that can check its
 
 ### 7. Memory
 
-Five layers, each loaded differently:
+Six layers, each loaded differently:
 
 | Layer | Holds | Loaded |
 |---|---|---|
 | Core | Operating Card + project core | Always. Small and unchanging, so it stays cached |
 | Index | One line per knowledge entry | Always |
 | Knowledge | Gotchas, facts, decisions, lessons, open questions | Only when relevant or triggered |
+| Recipes | Procedures that worked: steps, traps, checks (below) | One, when the task matches (`loop recipe match`); the SessionStart hook names the best one |
 | Task state | `.ai/task.md` | Every window of the current task; deleted afterwards |
 | Source of truth | Code, git history, test output, docs | Read when needed; never copied |
 
@@ -178,6 +180,12 @@ Five layers, each loaded differently:
 K-0017 gotcha ✔ MV3 service worker loses in-memory state after ~30s idle · files: src/background/**
 ```
 
+**Recipes are the layer for procedures.** A knowledge entry says "this breaks"; a recipe says "to build this kind of thing, do these steps, and this check proves each one". It is one Markdown file (`templates/recipe.md`) with front matter (`id`, `title`, `kind`, `stack` as `name@major`, `tags`, `status`, `source`, `uses`, `passes`, `updated`) and five sections in order: When to use, Steps (each names its proof), Traps (each pointing at a knowledge id or trigger), Checks, Start from. **Hard cap 6 KB**: a recipe is the small exact context, not a manual.
+- *Stored* in `.ai/recipes/` (project) and `~/.ai/recipes/` (yours, across projects). Nothing personal: no absolute paths, emails or secrets.
+- *Induced only from work whose checks passed*, as small appended or edited items with evidence, never a full rewrite. Rewriting the whole file loses what earlier runs learned (ACE, Zhang et al. 2025, "context collapse"). `loop recipe draft` follows this delta rule.
+- *Used* by `loop recipe match` (stack overlap at the major version, plus tag and keyword overlap) and `loop recipe show <id> --context`, which prints exactly what a model receives.
+- *Judged* by `uses` and `passes`; a recipe that fails more than it passes is fixed or deleted, like a trigger.
+
 **Cross-project knowledge is keyed by library and major version, not by project type.** At task start, read the dependency manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, …) and load the index lines from `~/.ai/libs/<library>@<major>.md` for each dependency. This has three advantages:
 - No guessing about what "kind" of project this is.
 - It combines on its own: a Next + Supabase + Tailwind project simply gets all three sets of notes.
@@ -196,7 +204,17 @@ Triggers watch events the tool already sees, run outside the model, and cost not
 | **Command** | Before a matching command runs | `npm run build` → "run `npx prisma generate` first" (or just run it automatically) |
 | **Topic** | The task text matches keywords | "persist auth" → a one-line hint pointing to K-0017 |
 
-- **With hooks** (for example Claude Code): a small script matches each event against `.ai/triggers.yaml` and injects the entry. Error and file triggers run after tool calls; command triggers run before.
+- **With hooks** (for example Claude Code): `loop hook <event>` reads the hook JSON from stdin, matches it against `.ai/triggers.yaml` and prints `{"hookSpecificOutput":{"hookEventName":"<event>","additionalContext":"…"}}`, or nothing. Wire it through the plugin (`plugin/hooks/hooks.json`) or a project `.claude/settings.json` (`loop init --hooks`). Match built-in tools only (`Bash|Read|Edit|Write|Glob|Grep`); context from MCP and Agent calls may be dropped.
+
+| Hook event | Kinds it checks |
+|---|---|
+| `SessionStart` | The best matching recipe, as one line |
+| `UserPromptSubmit` | Topic |
+| `PreToolUse` (Bash) | Command |
+| `PostToolUse` | File. It fires only after a tool *succeeds* |
+| `PostToolUseFailure` | Error and file. A failed Bash call fires this, not `PostToolUse` |
+
+  A hook never calls a model or the network, exits 0 on any error (a broken hook must not break a run), injects at most 2,000 characters, and injects each trigger once per session. Each fire is logged locally to `.ai/.trigger-log.jsonl`.
 - **Without hooks:** manual trigger mode. Card rules 7 and 8 make the agent search the index after errors and before edits. It's less automatic but has the same effect, and works in any tool.
 - **Precision beats coverage.** A trigger that fires often and doesn't help is noise. Track `fired` and `helped`, and fix or delete triggers that help less than about half the time.
 
@@ -312,6 +330,7 @@ The AI writes prompts for its next window, its subagents and its reviewers. It's
 **Retro.** About 2 minutes, when the checks pass. The AI drafts it and the human approves.
 1. List what was learned. For each item: does it apply beyond this task, or only to it? Is it confirmed or a guess? At what moment would it have helped (which file, command or error)?
 2. Move general, confirmed items down the promotion ladder as far as they'll go.
+   **Recipe step:** is this a *procedure* someone will repeat (a kind of project or feature)? Then draft a recipe (`loop recipe draft`, §7), check it with `loop recipe check`, and keep it only if it is short and every step has a proof. A repeated *procedure* becomes a recipe; a repeated *mistake* still goes note → trigger → check.
 3. Put library-level lessons in `~/.ai/libs/<library>@<major>.md`.
 4. Delete `.ai/task.md`. Knowledge that only mattered for this task goes with it, on purpose.
 5. Add a line to `.ai/log.md` (§13) and update `routing.md`.
@@ -320,6 +339,7 @@ The AI writes prompts for its next window, its subagents and its reviewers. It's
 
 ```
 guess → confirmed note → note with a trigger → automated check
+                    ↘ repeated procedure → recipe
 ```
 
 The last step is the goal: **the best memory is one the model never has to read.** "Never use `require()` here" becomes a lint rule. "Run prisma generate before build" becomes part of the build script. Then the prose note is deleted. A check costs nothing until it's broken, and it can't be ignored.
@@ -346,6 +366,8 @@ What to watch:
 - **First-try pass rate per tier.** This feeds the routing table.
 - **Trigger precision:** times helped ÷ times fired.
 - **Windows until the checks pass**, and cost.
+- **Tokens per verified unit:** tokens spent divided by units whose checks passed. A cheaper run that fails its checks is not cheaper.
+- **The eval** (`loop eval`) is the one place a context claim is tested: it rebuilds known tasks cold, with a recipe, and with triggers, then reports pass rate, tokens and time per arm and model. Read the headline only when a results file exists; no results, no claim. The owner runs it; unattended lanes use the fake runner.
 
 Prefer numbers from tools (check results, git, billing) over the AI's own account of how things went. Change one thing at a time and watch the numbers. Every threshold in this file (50–60%, 20 tasks, 90%, 5 windows) is a starting guess for your log to correct.
 

package/method/operating-card.md

@@ -2,7 +2,7 @@
 
 > The full method is in `.ai/method.md`. The § numbers point to Part B there.
 
-**Objective:** the most verified-correct results per minute of the owner's attention. Tokens are the cheapest resource. A wrong result that looks right is the most expensive one.
+**Objective:** the most verified-correct results per minute of the owner's attention, from the smallest context that still passes. A wrong result that looks right is the most expensive one. Tokens are spent where they buy correctness (checks, review), not on re-learning what a recipe, a trigger or a check already knows.
 
 **Start of every session**
 1. Read `.ai/index.md`. Open a knowledge entry only when it's relevant to what you're doing.

package/method/retro.md

@@ -5,9 +5,10 @@ Run it when the checks pass, before deleting `.ai/task.md`. About two minutes.
 1. List what was learned. For each item: does it apply beyond this task? Is it confirmed or a guess? At what moment would it have helped (file, command or error)?
 2. Move general, confirmed items down the promotion ladder as far as they go: `guess → confirmed note → note with a trigger → automated check`. The best memory is one the model never has to read: turn a rule into a lint, test or script and delete the prose.
 3. Write each kept lesson as a knowledge entry (`.ai/knowledge/K-NNNN.md`, see `method/example/K-0001.md`) with triggers, and add one line to `.ai/index.md`.
-4. Flag entries this task showed to be wrong or stale. Never delete a CONFIRMED entry without new evidence.
-5. Add one line to `.ai/log.md`: date, task, checks result, runs used, what was learned.
-6. Delete `.ai/task.md`.
+4. Is this a procedure someone will repeat? Then draft a recipe (`loop recipe draft`; see method §7 and `templates/recipe.md`). A repeated *procedure* becomes a recipe; a repeated *mistake* still goes note → trigger → check. For an existing recipe, add or change items; never rewrite the file.
+5. Flag entries this task showed to be wrong or stale. Never delete a CONFIRMED entry without new evidence.
+6. Add one line to `.ai/log.md`: date, task, checks result, runs used, what was learned.
+7. Delete `.ai/task.md`.
 
 ## In a lane
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compounding-loop",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Write the brief, check back tomorrow: unattended, verified Claude Code build loops with a local dashboard.",
   "type": "module",
   "license": "MIT",
@@ -66,13 +66,13 @@
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
     "vite": "^8.3.3",
-    "vitest": "^5.0.3",
-    "yaml": "^2.9.1"
+    "vitest": "^5.0.3"
   },
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "@hono/node-server": "^2.1.4",
     "commander": "^15.0.0",
-    "hono": "^4.13.13"
+    "hono": "^4.13.13",
+    "yaml": "^2.9.1"
   }
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "compounding-loop",
-  "version": "0.5.0",
+  "version": "0.6.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/loop-init.md

@@ -8,6 +8,7 @@ Set this repository up for unattended, verified build loops.
 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/triggers.yaml` (a starter) and, if the user agrees, the hooks in `.claude/settings.json` (`npx compounding-loop init --hooks`) so triggers fire at the moment they matter. The plugin already ships the same hooks; do not add both.
    - `.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

@@ -7,5 +7,6 @@ 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`.
+4. Is this a procedure someone will repeat (a kind of project or feature)? Then draft a recipe: run `loop recipe draft --print-prompt`, or `loop recipe draft` if the user agrees to a Claude call. The draft lands in `.ai/recipes/<id>.draft.md` and is scored by `loop recipe check`. For an existing recipe id the draft is a list of added or changed items, never a full rewrite. A repeated *procedure* becomes a recipe; a repeated *mistake* still goes note -> trigger -> check.
+5. Add one line to `.ai/log.md`: date, task, checks result, number of windows, what was learned.
+6. After the user approves the proposed entries and the recipe draft, write them, update `.ai/index.md`, and delete `.ai/task.md`.

package/plugin/hooks/hooks.json

@@ -0,0 +1,62 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "loop hook SessionStart",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "loop hook UserPromptSubmit",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Read|Edit|Write|Glob|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "loop hook PreToolUse",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash|Read|Edit|Write|Glob|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "loop hook PostToolUse",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash|Read|Edit|Write|Glob|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "loop hook PostToolUseFailure",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/recipe.md

@@ -0,0 +1,39 @@
+---
+id: R-your-slug
+title: Short name of the kind of project or feature
+kind: feature
+stack:
+  - node@20
+tags:
+  - one-word-tag
+status: GUESS
+source: owner/repo at commit abc1234
+uses: 0
+passes: 0
+updated: 2026-01-01
+---
+
+<!-- Copy to .ai/recipes/R-<slug>.md. Keep it under 6 KB: a recipe is the small exact context, not a manual.
+     Check it with `loop recipe check`. Change an existing recipe by adding or editing items, never by regenerating the file.
+     Induce it only from work whose checks passed. No absolute paths, emails or secrets. -->
+
+## When to use
+
+One paragraph: the kind of task this fits, and when it does not.
+
+## Steps
+
+1. Do the first thing. Proof: `npm test`.
+2. Do the next thing. Proof: `node --test`.
+
+## Traps
+
+- One line per trap, with what covers it (K-0001 or a trigger id).
+
+## Checks
+
+- `npm test`
+
+## Start from
+
+- The template or files to copy first.

package/templates/recipes/cli-command-json.md

@@ -0,0 +1,47 @@
+---
+id: R-cli-command-json
+title: Add a CLI subcommand with --json output and tests
+kind: feature
+stack:
+  - node@20
+tags:
+  - cli
+  - json
+  - subcommand
+  - command
+status: CONFIRMED
+source: Minntooos/Compounding-Loop src/cli and tests/unit/cli, rounds 4 to 6
+uses: 0
+passes: 0
+updated: 2026-10-14
+---
+
+## When to use
+
+A Node command-line tool needs one more subcommand that reports something, for people (a table) and for scripts (`--json`). Not for commands that only wrap another tool.
+
+## Steps
+
+1. Write the logic as a pure function that takes its inputs and returns a plain object (no printing, no `process.exit`). Proof: `npm test` runs its unit test.
+2. Test it first: the normal result, an empty or missing input, and a bad argument that throws a message saying how to fix it. Use a temp folder, never the real repo. Proof: `npm test`.
+3. Register the subcommand with a one-line description and a `--json` option. With `--json` print only `JSON.stringify(result, null, 2)` to stdout; without it print the human text. Proof: a test runs the command and parses stdout.
+4. Make errors short and actionable: print them to stderr and set `process.exitCode = 1` instead of exiting mid-stream. Proof: a test asserts the exit code and the message.
+5. Add the command to `--help` and the README usage list. Proof: `node bin/<tool>.js --help`.
+6. Run the whole suite. Proof: `npm test`.
+
+## Traps
+
+- Any extra `console.log` breaks `--json` for scripts; log progress to stderr.
+- Build paths with `node:path`, never a hard-coded `/` (Windows).
+- Start child processes with `execFile` and an argument array, never a shell string.
+- Tests that use real temp folders can hit `EBUSY` on Windows at cleanup; pass `maxRetries` to `rm` (K-0002).
+- A JSON shape is a contract: add fields, never rename them.
+
+## Checks
+
+- `npm test`
+- `node bin/<tool>.js <command> --json`
+
+## Start from
+
+- An existing subcommand in the same file (copy its option handling) and its test file.

package/templates/recipes/static-calculator-site.md

@@ -0,0 +1,50 @@
+---
+id: R-static-calculator-site
+title: Add a calculator page to a static niche site
+kind: feature
+stack:
+  - node@20
+tags:
+  - calculator
+  - static
+  - seo
+  - html
+status: CONFIRMED
+source: Minntooos/Compounding-Loop templates/static-site, five live sites built unattended in round 1
+uses: 0
+passes: 0
+updated: 2026-10-14
+---
+
+## When to use
+
+A static site (plain HTML, CSS and ES modules, no build step) needs one more tool page: a calculator or converter that must be correct and rank for one search intent. Not for sites with a build step or a backend.
+
+## Steps
+
+1. Put the formula in a pure function in `site/js/lib/<topic>.js`, no DOM access. Proof: `npm run unit` imports it.
+2. Write `tests/unit/<topic>.test.mjs` (`node:test`) with at least two reference cases from an authoritative source (URL in a comment above each) and the edges: zero, empty, impossible input, both unit directions. Proof: `npm run unit`.
+3. Make the page `site/<slug>/index.html`, slug lowercase and keyword-first, with `<title>`, a meta description of at most 160 characters, one `<h1>`, a canonical on the site's own host, and JSON-LD. Proof: `npm run check`.
+4. Add the page script as an external module (no inline script or handler); show a clear message for bad input, never `NaN`, `Infinity` or `undefined`. Write results with `textContent`. Proof: `npm run check`.
+5. Write 300+ original visible words: how to use it, how it is calculated, a worked example, a short FAQ. Proof: `npm run check`.
+6. Link the page from the home page and from related pages, and add its URL to `site/sitemap.xml`. Proof: `npm run check`.
+7. Run everything and fix what the messages say. Proof: `npm test`.
+
+## Traps
+
+- A test that re-derives your own formula proves nothing; take the cases from a source (K-0003 in the starter kit).
+- Never change a published URL; add a 301 redirect to both `netlify.toml` and `vercel.json` if you must.
+- A sitemap entry is easy to forget; the check fails without it.
+- Inline scripts, `innerHTML` with user input and CDN scripts break the CSP; use modules and `textContent`.
+- Pages that differ by one swapped word are doorway pages; the check fails above 60% shared phrasing.
+- Meta descriptions over 160 characters are cut in results.
+
+## Checks
+
+- `npm run check`
+- `npm run unit`
+- `npm test`
+
+## Start from
+
+- `templates/static-site` in the Compounding Loop package (`loop new` copies it): `site/`, `scripts/check.mjs`, `tests/`.

package/templates/static-site/CLAUDE.md

@@ -59,7 +59,7 @@
 
 > The full method is in `.ai/method.md`. The § numbers point to Part B there.
 
-**Objective:** the most verified-correct results per minute of the owner's attention. Tokens are the cheapest resource. A wrong result that looks right is the most expensive one.
+**Objective:** the most verified-correct results per minute of the owner's attention, from the smallest context that still passes. A wrong result that looks right is the most expensive one. Tokens are spent where they buy correctness (checks, review), not on re-learning what a recipe, a trigger or a check already knows.
 
 **Start of every session**
 1. Read `.ai/index.md`. Open a knowledge entry only when it's relevant to what you're doing.