Add cost/token observability across loop tooling

.gitignore

@@ -28,6 +28,7 @@ temp/
 build/
 **/node_modules/
 !tools/loop-audit/dist/
+!tools/loop-cost/dist/
 *.egg-info/
 
 # State files that should not be committed in consumer projects (reference repo dogfoods STATE.md)

LOOP.md

@@ -51,6 +51,13 @@ See [docs/multi-loop.md](docs/multi-loop.md). Priority: CI Sweeper → PR Babysi
 - GitHub MCP read-only for issue/PR discovery
 - Scope connectors to read + comment until the loop is trusted
 
+## Budget & Observability
+
+- Token caps: `loop-budget.md`
+- Run history: `loop-run-log.md`
+- Estimate: `npx @cobusgreyling/loop-cost --pattern daily-triage`
+- Kill switch: `loop-pause-all` label or flag in `STATE.md`
+
 ## Safety & Gates (this repo)
 
 - No auto-merge on main except trivial dependency patches (allowlist + verifier)

README.md

@@ -45,7 +45,8 @@ A loop is a recursive goal: you define a purpose and the AI iterates (often with
 | [Patterns](patterns/README.md) | 6 production patterns including the new low-risk Changelog Drafter |
 | [Starters](starters/) | Clone-and-run kits (Grok, Claude Code, Codex) |
 | [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI — `npx @cobusgreyling/loop-audit` |
-| [loop-init](tools/loop-init/) | Scaffold starters — `npx @cobusgreyling/loop-init` |
+| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log — `npx @cobusgreyling/loop-init` |
+| [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` |
 | [Stories](stories/) | Real wins and honest failures |
 
 ## Why This Matters
@@ -117,13 +118,16 @@ Machine-readable index: [patterns/registry.yaml](patterns/registry.yaml) (now 6
 # 1. Scaffold a starter (or copy manually — see starters/)
 npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
 
-# 2. Audit readiness
+# 2. Estimate token spend for your cadence
+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1
+
+# 3. Audit readiness (budget + run-log now scored)
 npx @cobusgreyling/loop-audit . --suggest
 
-# 3. See scores climb: empty → L1 → L2
+# 4. See scores climb: empty → L1 → L2
 bash scripts/before-after-demo.sh
 
-# 4. Start report-only (Grok example)
+# 5. Start report-only (Grok example)
 /loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.
 ```
 
@@ -132,6 +136,7 @@ Packages publish from tagged releases — see [docs/RELEASE.md](docs/RELEASE.md)
 ```bash
 cd tools/loop-init && npm ci && npm test && node dist/cli.js /path/to/project --pattern daily-triage --tool grok
 cd tools/loop-audit && npm ci && npm test && node dist/cli.js /path/to/project --suggest
+cd tools/loop-cost && npm ci && npm test && node dist/cli.js --pattern ci-sweeper --cadence 15m
 ```
 
 Phased rollout: **L1 report → L2 assisted fixes → L3 unattended** — see [loop-design-checklist](docs/loop-design-checklist.md).

docs/RELEASE.md

@@ -6,6 +6,7 @@ This repo ships two public npm packages from `tools/`:
 |---------|-----------|-------------|
 | `@cobusgreyling/loop-audit` | `tools/loop-audit` | `loop-audit-v*` |
 | `@cobusgreyling/loop-init` | `tools/loop-init` | `loop-init-v*` |
+| `@cobusgreyling/loop-cost` | `tools/loop-cost` | `loop-cost-v*` (add workflow when publishing) |
 
 ## One-time setup (trusted publishing — recommended)
 

docs/loop-design-checklist.md

@@ -54,7 +54,10 @@ Use this before enabling a loop in production. Score honestly — a loop missing
 
 ## 8. Cost & Limits
 
-- [ ] **Token budget** estimated (see [operating-loops.md](./operating-loops.md))
+- [ ] **Token budget** estimated (`npx @cobusgreyling/loop-cost`, [operating-loops.md](./operating-loops.md))
+- [ ] **`loop-budget.md`** with daily caps and kill switch
+- [ ] **`loop-run-log.md`** for append-only run history
+- [ ] **`loop-budget` skill** checks spend at start/end of each run
 - [ ] **Max iterations** per item per run
 - [ ] **Max auto-PRs** per day (cleanup loops)
 - [ ] **Pause/kill** criteria defined

docs/operating-loops.md

@@ -4,6 +4,15 @@ Running a loop is operations work. This doc covers cost, logging, metrics, and w
 
 ## Token & Cost Budgeting
 
+Estimate before scheduling:
+
+```bash
+npx @cobusgreyling/loop-cost --pattern <id> --cadence <interval> --level L1
+npx @cobusgreyling/loop-init . --pattern <id>   # scaffolds loop-budget.md + loop-run-log.md + loop-budget skill
+```
+
+`loop-audit` scores cost observability and caps L3 until budget + run log + LOOP.md budget section exist.
+
 Rough planning factors:
 
 | Factor | Impact |

docs/pattern-picker.md

@@ -16,9 +16,29 @@ flowchart TD
     J -->|yes| K[Post-Merge Cleanup]
     J -->|no| L{Release notes / changelog stale?}
     L -->|yes| M[Changelog Drafter]
-    L -->|no| G
+    L -->|no| N{Tight token budget?}
+    N -->|yes| M
+    N -->|no| G
 ```
 
+## Cost-aware picks
+
+Estimate before you schedule:
+
+```bash
+npx @cobusgreyling/loop-cost --pattern <id> --level L1
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok   # scaffolds loop-budget.md + loop-run-log.md
+```
+
+| Situation | Prefer | Avoid (until budget + early-exit) |
+|-----------|--------|-----------------------------------|
+| Hobby / tight plan | Changelog Drafter, Daily Triage (L1), Post-Merge | CI Sweeper at 5m, PR Babysitter at 5m |
+| Active CI fires | CI Sweeper at **15m+** with early-exit | Full triage every 5m when main is green |
+| Many open PRs | PR Babysitter at 10–15m, L1 watch first | L2 fix loops on every tick |
+| Release week | Changelog Drafter daily | Dependency Sweeper + CI Sweeper unattended |
+
+`loop-audit` caps **L3** until `loop-budget.md`, `loop-run-log.md`, and a `LOOP.md` budget section exist.
+
 ## Quick reference
 
 | Symptom | Pattern | Start with |

loop-budget.md

@@ -0,0 +1,28 @@
+# Loop Budget — loop-engineering (reference repo)
+
+> Dogfood file for the patterns that maintain this repository.
+
+## Daily limits
+
+| Loop | Max runs/day | Max tokens/day | Max sub-agent spawns/run |
+|------|--------------|----------------|--------------------------|
+| Daily Triage | 1 | 100k | 0 (L1) |
+| Validate/Audit (CI) | 96 | 500k | 0 |
+| Changelog Drafter | 1 | 100k | 2 |
+
+## On budget exceed
+
+1. Pause schedulers / disable high-cadence workflows
+2. Append event to `loop-run-log.md`
+3. Open maintainer issue
+
+## Kill switch
+
+- Label: `loop-pause-all`
+- Resume only after cleared in `STATE.md`
+
+## Estimate spend
+
+```bash
+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1
+```

loop-run-log.md

@@ -0,0 +1,22 @@
+# Loop Run Log — loop-engineering
+
+Append one entry per run. Prune entries older than 30 days.
+
+## Format
+
+```json
+{
+  "run_id": "2026-06-09T08:15:00Z",
+  "pattern": "daily-triage",
+  "duration_s": 45,
+  "items_found": 4,
+  "actions_taken": 1,
+  "escalations": 0,
+  "tokens_estimate": 52000,
+  "outcome": "report-only | fix-proposed | escalated | no-op"
+}
+```
+
+## Recent Runs
+
+<!-- Loop appends below this line -->

package.json

@@ -7,8 +7,9 @@
     "check:loop-init": "node scripts/check-loop-init-sync.mjs",
     "test:loop-audit": "cd tools/loop-audit && npm test",
     "test:loop-init": "cd tools/loop-init && npm test",
-    "test:tools": "npm run test:loop-audit && npm run test:loop-init",
-    "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build"
+    "test:loop-cost": "cd tools/loop-cost && npm test",
+    "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost",
+    "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build"
   },
   "devDependencies": {
     "ajv": "^8.17.1",

patterns/changelog-drafter.md

@@ -97,6 +97,22 @@ The loop should prune entries once a release is tagged/published and the draft i
 | Tone mismatch with project | Provide a short "Release voice" section in AGENTS.md or a project skill that the drafter reads. |
 | Accidentally publishing | Never grant the loop write access to tags or the live CHANGELOG without an explicit human gate + PR. |
 
+## Cost Profile
+
+| Scenario | Tokens/run | Notes |
+|----------|------------|-------|
+| No-op (no new merges) | ~5k | Exit when nothing since last tag |
+| Scan + categorize | ~35k | PR/commit scan |
+| Draft + verify | ~80k | Categorized release notes draft |
+
+**Cadence**: 1d · **Tier**: low · **Suggested daily cap**: 100k tokens
+
+```bash
+npx @cobusgreyling/loop-cost --pattern changelog-drafter --level L1
+```
+
+One of the cheapest high-value loops. Safe to run alongside others.
+
 ## Success Metrics
 
 - Time from "last merge" to "published release notes" (target: < 1 day for patch releases)

patterns/ci-sweeper.md

@@ -93,6 +93,22 @@ Use `/goal` for focused "get green" sessions; use scheduled sweeper for ongoing
 | Token burn on red main | Pause loop after N failures; batch fixes |
 | Wrong branch targeted | Explicit branch allowlist in skill |
 
+## Cost Profile
+
+| Scenario | Tokens/run | Notes |
+|----------|------------|-------|
+| No-op (CI green) | ~5k | **Required** — do not run full sweeper when green |
+| Triage / classify | ~50k | Log parse + failure classification |
+| Fix attempt (L2) | ~200k | Worktree + implementer + verifier |
+
+**Cadence**: 5m–15m · **Tier**: very-high · **Suggested daily cap**: 1M tokens · **Early exit required**
+
+```bash
+npx @cobusgreyling/loop-cost --pattern ci-sweeper --cadence 15m --level L2
+```
+
+At 15m cadence without early-exit, worst-case spend exceeds 5M tokens/day. Never run full action paths on every tick.
+
 ## Success Metrics
 
 - Mean time to first proposed fix after CI goes red

patterns/daily-triage.md

@@ -91,6 +91,22 @@ Fields the loop must update every run:
 | Auto-fix on wrong priority | Start report-only; add explicit effort/risk gates |
 | Missed overnight failures | Add `fireImmediately: true` or run at start of day + mid-day |
 
+## Cost Profile
+
+| Scenario | Tokens/run | Notes |
+|----------|------------|-------|
+| No-op | ~5k | Nothing actionable in state |
+| Full triage (L1) | ~50k | CI + issues + commits scan |
+| Assisted fix (L2) | ~200k | Worktree + implementer + verifier |
+
+**Cadence**: 1d–2h · **Tier**: low · **Suggested daily cap**: 100k tokens
+
+```bash
+npx @cobusgreyling/loop-cost --pattern daily-triage --cadence 1d --level L1
+```
+
+Scaffold `loop-budget.md` and `loop-run-log.md` with `loop-init`. See [operating-loops.md](../docs/operating-loops.md).
+
 ## Success Metrics
 
 - Time from "something broke" to "human knows about it"

patterns/dependency-sweeper.md

@@ -85,6 +85,22 @@ Prune merged/closed entries on every run.
 | Update touches dozens of transitive deps at once | Treat as high-risk. Only touch direct deps in the minimal-fix step. |
 | Notification spam | Only notify human for items in the "needs human" section of state. Everything else is silent or summarized daily. |
 
+## Cost Profile
+
+| Scenario | Tokens/run | Notes |
+|----------|------------|-------|
+| No-op (nothing to bump) | ~5k | Exit when scan is clean |
+| Triage / scan | ~60k | Audit + Dependabot + lockfile scan |
+| Patch + verify (L2) | ~300k | Worktree + full test suite |
+
+**Cadence**: 6h–1d · **Tier**: medium · **Suggested daily cap**: 500k tokens
+
+```bash
+npx @cobusgreyling/loop-cost --pattern dependency-sweeper --level L2
+```
+
+Verifier runs (`npm ci && npm test`) dominate cost — cap attempts per package in `loop-budget.md`.
+
 ## Success Metrics
 
 - Median time from "vulnerability published / Dependabot PR opened" → merged (for items the loop touched).

patterns/post-merge-cleanup.md

@@ -91,6 +91,22 @@ Last run: 2026-06-09 22:00 UTC
 | Noise from every TODO | Only act on TODOs with merge context or linked tickets |
 | Competing with feature work | Run off-peak; cap auto-PRs per day (e.g. 2) |
 
+## Cost Profile
+
+| Scenario | Tokens/run | Notes |
+|----------|------------|-------|
+| No-op | ~5k | No recent merges to scan |
+| Scan + prioritize | ~40k | Merge list + TODO scan |
+| Small fix (L2) | ~150k | Worktree + verifier |
+
+**Cadence**: 1d–6h · **Tier**: low · **Suggested daily cap**: 200k tokens
+
+```bash
+npx @cobusgreyling/loop-cost --pattern post-merge-cleanup --cadence 1d --level L1
+```
+
+Run off-peak. Cap auto-PRs per day in `loop-budget.md`.
+
 ## Success Metrics
 
 - Reduction in "we forgot to remove X after merge" incidents

patterns/pr-babysitter.md

@@ -83,6 +83,22 @@ Example state entry:
 - **Stale state** → The loop should prune closed/merged PRs on every run.
 - **Notification fatigue** → Use selective notifications (only when human action is truly required).
 
+## Cost Profile
+
+| Scenario | Tokens/run | Notes |
+|----------|------------|-------|
+| No-op (empty watchlist) | ~3k | **Target most runs** — exit early |
+| Triage pass | ~80k | PR + CI status scan |
+| Fix attempt (L2) | ~250k | Worktree + minimal-fix + verifier |
+
+**Cadence**: 5m–15m · **Tier**: high · **Suggested daily cap**: 2M tokens · **Early exit required**
+
+```bash
+npx @cobusgreyling/loop-cost --pattern pr-babysitter --cadence 10m --level L1 --conservative
+```
+
+High cadence without early-exit burns tokens fast. Use `loop-budget` skill + `loop-run-log.md`.
+
 ## Success Metrics
 
 - Average time from "ready for review" to merge (for PRs the loop touched).

patterns/registry.schema.json

@@ -79,6 +79,24 @@
           "token_cost": {
             "type": "string",
             "enum": ["low", "medium", "high", "very-high"]
+          },
+          "cost": {
+            "type": "object",
+            "required": [
+              "tokens_noop",
+              "tokens_report",
+              "tokens_action",
+              "suggested_daily_cap",
+              "early_exit_required"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "tokens_noop": { "type": "integer", "minimum": 1000 },
+              "tokens_report": { "type": "integer", "minimum": 1000 },
+              "tokens_action": { "type": "integer", "minimum": 1000 },
+              "suggested_daily_cap": { "type": "integer", "minimum": 10000 },
+              "early_exit_required": { "type": "boolean" }
+            }
           }
         }
       }