bossbuild 0.97.0

package/stages/L1-mvp/template/claude-append.md

@@ -0,0 +1,122 @@
+## MVP working rules (added on `boss unlock mvp`)
+
+> {{MODE}} mode adds the smallest spine that lets you actually build: a spec, a smoke gate, a devlog, a
+> session-end ritual. Same conscience — capture and validate still come first. Don't out-ceremony the work.
+
+1. **Spec before code.** Any non-trivial change starts with `/spec` — promotes an idea to `FEAT-NNN` with a goal, acceptance criteria, and a smoke check. Throwaway one-liners don't need it.
+2. **Smoke before commit.** `/smoke` runs the stack's "is the app even working" gate. Green before the commit, red is information — fix or document the regression.
+3. **Devlog every session.** `/log` appends a dated entry to `docs/devlog.md` — what landed, what's next, what surprised you. Lighter than commits, denser than `CHANGELOG`. Future-you reads it before starting work.
+4. **`/close` at session end.** Updates `docs/RESUME.md` (state + next tasks + open decisions) and writes a `/log` entry. Read RESUME first thing next session.
+5. **Spec → build → smoke → log → close.** That's the loop. When you find yourself skipping a step often, ask whether it's the wrong step or the wrong moment — don't paper over it with more ceremony.
+6. **The conscience still runs.** Quickstart's nudges (validation drift, "Done!" graduation) keep firing — MVP doesn't replace the front of the funnel, it sits behind it.
+
+## Git workflow (trunk-based, review-bounded)
+
+> AI changed which part of version control hurts: the agent writes code ~4× faster, but **review** is now the bottleneck. Keep batches small enough that two humans can actually stand behind what merged. Full depth: `git-workflow` practice.
+
+- **Trunk-based default.** Commit to `main` or branches that live hours, not days; merge daily; keep fewer than ~3 active branches (DORA: ~2.3× more likely to be elite). `/smoke` green before every commit is what makes that safe — your smoke check *is* your CI until surface area earns a real pipeline.
+- **Worktrees are how you parallelize agents — capped at ~2–4 = your *review* capacity, not your agent count.** You can spawn ten agents; you can't read ten diffs well. More agents than you can review isn't throughput, it's unreviewed code with your name on the merge. One worktree per `FEAT` (a vertical slice) so they don't collide.
+- **Risk-tiered review, not blanket gates.** Low-risk (copy, styling, isolated pure functions) — a glance. High-risk (auth, money, migrations, deletes, deploys, AI-mediated paths) — the *other* human reviews it, and `/smoke` + `/evals` + `/red-team` are that high-risk tier.
+- **Read the test diff harder than the code.** Agents under pressure to go green will quietly rewrite assertions to match broken behaviour. Ask: *did the behaviour get fixed, or did the expectation get lowered?*
+- **Whoever clicks merge owns what the agent wrote.** "The AI wrote it" is not an owner. **Ownership = the prompt-author's intent + the reviewer's acceptance** — the agent is the instrument.
+- **Mob the hard problems.** With an AI as your pair, you question its suggestions *less*. For genuinely novel/risky work, put both humans + the agent on it together rather than one founder solo in a worktree.
+- **Honesty anchor (METR, n=16):** experienced devs on mature repos were 19% *slower* with AI while *believing* they were 20% faster. Trust the green `main` and the merged diff, not the feeling of speed.
+
+## Shipping (localhost is not shipped)
+
+> The CI half above keeps `main` green; this is the **CD** half — *is this where a real user can hit it, or just you?* An app only you can reach is a pseudo app: you can't prove pain, fit, or willingness-to-pay on it. Full depth: `ship-it-live` practice; the runner: `/ship`.
+
+- **Deploy early, cheap, reversible.** Get a real URL at MVP, not at launch — smallest viable host, reversible-and-cheap over impressive. "I'll deploy when it's polished" costs you the only thing that's scarce this early: contact with a real user. (The "reliability is premature at MVP" counter doesn't survive scrutiny — what staying on localhost saves you isn't worth what it costs.)
+- **Secrets & authz at the boundary — the leg with teeth.** Never ship a secret in the client bundle, and if the app talks to a database with a public/anon key, the row-level security is what stands between your users and the internet — and the AI does **not** configure it by default. This is the signature vibe-coded leak (CVE-2025-48757 / MoltBook — 170+ apps, 1.5M credentials, founders who wrote no code). `/ship`'s pre-flight + `/red-team`'s pre-ship pass catch it; run them before the first public URL.
+- **Rollback ≠ reversible.** Instant rollback restores the *app*, not the *database* — a migration that ran doesn't un-run. Name the revert path before you deploy, and make schema changes backward-compatible (expand-migrate-contract) so a code rollback never strands the data.
+- **Honesty anchor (DORA 2024):** AI adoption correlated with *worse* delivery stability and throughput. Faster shipping isn't safer shipping — the instrument is measured (change-fail rate, time-to-restore), not the feeling.
+
+## What MVP adds (alongside Quickstart)
+
+- **Skills:**
+  - `/spec` — promote idea → `FEAT-NNN` spec (v0.21.0+: includes validated-learning field per
+    Ries, evals field per Husain, moment #4 restraint check against canvas-loop)
+  - `/smoke` — build-health gate; configured per stack
+  - `/evals` — AI-correctness gate paired with smoke (Husain; v0.21.0+). For any FEAT with
+    LLM in control flow, the eval set lives in `docs/evals/FEAT-NNN.yml`. 20 cases beats 0;
+    categorize failures by mode.
+  - `/pretotype` — demand-test the bet BEFORE building (Savoia; v0.21.0+). Fake-door / WoZ /
+    Mechanical-Turk / Pinocchio / YouTube test / impresario. Set the threshold before running.
+  - `/design-tokens-init` — scaffold the three-layer token system at the *first UI commit*
+    inflection (IDEA-010 Phase 2; v0.21.0+). Cohort-aware delivery. Prevents the 47-blues /
+    pattern-reinvention / billion-line-drift failure modes.
+  - `/ai-cost` — declare the AI spend contract at the *first LLM-call* inflection (v0.25.0+).
+    Cohort-aware budgets (first-product strict, vibe-virtuoso inspect-only, domain-expert
+    privacy-first), per-call cost logger, review cadence. Closes `cost-budget-loop`.
+  - `/cost-review` — read the ledger (the cadence /ai-cost only declared; v0.30.0+). Reads
+    `.boss/cost-log.jsonl`, summarizes by FEAT + user + cohort, compares against budget,
+    flags surprises, writes `docs/cost-reviews/REVIEW-YYYY-MM-DD.md`. Closes
+    `cost-review-loop`. *Both halves required: declare AND read.*
+  - `/ai-first-init` — bake AI-first discipline upfront (v0.26.0+). Conductor skill that
+    walks the founder through `docs/ai-first.md` (declare what's AI-mediated) → structured
+    outputs (Liu, `docs/schemas/`) → eval set (Husain, via `/evals`) → cost budget
+    (`/ai-cost`) → failure-state design (`/ai-failure-states`). Run after `boss unlock mvp`
+    when the project is AI-native. The "from day one" sequence.
+  - `/ai-failure-states` — design the five failure modes' UX before they happen (v0.26.0+).
+    Garbage / refusal / hallucination / timeout / cost-spike, each with a declared response +
+    stub fallback handler in code. Cohort-aware. Closes `ai-failure-state-loop`. **Domain-
+    expert cohort: hallucination response defaults to human-in-the-loop, not retry.**
+  - `/extract` — PRINCIPLE #1's own discipline as a skill (v0.29.0+). Reads recent work and
+    proposes 1-3 extraction candidates, each routed **UP** (into BOSS's `library/<cat>/`
+    via `boss learn`) or **DOWN** (into the app's `src/`) — or honest **NOT-YET**. The
+    LLM-as-judge counterpart to predicate-based loops; closes `extraction-loop`. *Two
+    destinations, not one.*
+  - `/drift-deep` — the deep, whole-project drift audit (v0.37.0+). The 1M-context *"am I
+    fooling myself across EVERYTHING I've built?"* counterpart to the cheap, bounded `drift`
+    hook moment. Reads the canvas + ALL devlog + every FEAT spec + the actual `src/` code and
+    judges whether the body of work validates the named riskiest assumption or builds around
+    it. Verdict (on-aim / drifting / mixed) → `docs/drift-audits/DRIFT-YYYY-MM-DD.md`.
+    Deliberate + founder-invoked (the cost discipline: a whole-project read can't be
+    per-prompt) — no loop, no nudge, you run it when you want the truth.
+  - `/ship` — put it where a real user can hit it (v0.92.0+, FEAT-024). The CD half: detect
+    the stack → deploy-time pre-flight (no client-bundled secrets; server-side authz/RLS
+    actually on — the CVE-2025-48757 / MoltBook vibe-coded-leak surface) → cheapest reversible
+    host → hand back the live URL + the rollback path. Stack-neutral (no baked-in target);
+    the pre-flight is a check, not a gate. Full depth: `ship-it-live` practice.
+  - `/log` — devlog
+  - `/close` — session-end RESUME update
+- **Builder agents:** `tester` (owns the smoke gate + acceptance checks for FEATs);
+  `program-manager` (sequencing — the *when*, distinct from `pm`'s *what*).
+- **Mentor agents:** `mentor-architect` (AI-native stack/architecture, advisory);
+  `mentor-gtm` (first 100, channels, positioning).
+- **Loops** (on the v0.18 generic loop primitive, MVP-stage):
+  - `spec-loop` — gates spec writing on canvas-loop closure (encodes moment #4 restraint;
+    skill-side detection via `/spec`)
+  - `pretotype-loop` — records that demand-testing happened before significant build
+  - `design-tokens-loop` — JIT scaffolds the design token system when UI starts accumulating
+    (conscience emits `coherence` moment when entry-met / exit-unmet)
+  - `cost-budget-loop` — opens at the first LLM SDK call in `src/` without a budget doc
+    (conscience emits `cost` moment when entry-met / exit-unmet; v0.25.0+)
+  - `ai-failure-state-loop` — opens at the first LLM SDK call in `src/` without a failure-
+    states design doc + fallback handlers (conscience emits `failure-mode` moment when
+    entry-met / exit-unmet; v0.26.0+). Same entry inflection as `cost-budget-loop`; the two
+    failure modes always coexist at the AI-mediated boundary.
+  - `extraction-loop` — PRINCIPLE #1's own discipline (v0.29.0+). Opens when `docs/devlog.md`
+    has ≥3 dated entries and no `EXTR-NNN` extraction record exists. Conscience emits the
+    `capture` moment; founder runs `/extract` to record the routing decision (UP / DOWN /
+    NOT-YET). First hook-runner loop whose entry is *time-of-work* (devlog count) rather than
+    *file-state predicate* — sets the precedent for future judgment-required moments.
+  - `cost-review-loop` — the cadence half of cost discipline (v0.30.0+). Opens once
+    `docs/ai-cost-budget.md` exists and no cost-review file is on record. Conscience emits
+    the `cost-stale` moment; founder runs `/cost-review` to read the ledger. Second
+    time-of-work entry pattern (declaration → read sequence).
+  - `drift-loop` — the work vs. the named risk (v0.31.0+). Opens when a canvas has a real
+    **Riskiest assumption** + `docs/devlog.md` has ≥3 dated entries + no real **Experiment
+    this week** validation plan. Conscience emits the `drift` moment — the gap *between*
+    `caution` (no risk named) and `done` (graduation). The first moment fronting a *model
+    judgment the predicate can't make*: the gate is cheap (risk named + work piling up + no
+    plan), but the model reads a bounded set (risk line + ~5 recent devlog + open FEAT) and
+    judges whether the work is *testing* the risk or building *around* it — naming the specific
+    gap, staying silent when on-aim. Closes when the validation plan is recorded (`/canvas`)
+    or run (`/pretotype`).
+- **Conventions:** `FEAT-NNN` for features in build (already listed in `docs/IDS.md`);
+  `docs/devlog.md` is append-only (override grammar lives here per IDEA-008);
+  `docs/RESUME.md` is the living state pointer; `docs/loops/` lives alongside `docs/ideas/`;
+  `docs/design/DESIGN_TOKENS.md` arrives JIT when design-tokens-loop opens.
+- **Graduation:** when the app earns design-system rigor / a real db / prototypes / a board
+  → `boss unlock v1`.

package/stages/L1-mvp/template/docs/loops/ai-failure-state-loop.md

@@ -0,0 +1,107 @@
+---
+id: ai-failure-state-loop
+type: loop
+stage: L1-mvp
+runner_type: hook
+attributed_to: [Husain (failure-mode categorization), Liu (structured outputs make detection possible), Karpathy (the failure surface IS the design surface)]
+also_relevant: [Mollick, Rauch, Willison]
+entry:
+  - count_at_least:
+      path_glob: src/**
+      pattern: '(anthropic|@anthropic-ai/sdk|openai|OpenAI\(|Anthropic\(|messages\.create|chat\.completions\.create|generateText|streamText)'
+      min: 1
+exit:
+  - exists: { path: docs/ai-failure-states.md }
+  - count_at_least:
+      path_glob: src/**
+      pattern: '(handleGarbageResponse|handleRefusal|handleHallucination|handleTimeout|handleCostSpike|ai-handlers|aiHandlers|on_refusal|on_hallucination|on_timeout)'
+      min: 1
+drift_moment: failure-mode
+---
+
+# Loop: ai-failure-state (MVP)
+
+The discipline that **names the failure before the user finds it.** When code contains an LLM
+SDK call but no `docs/ai-failure-states.md`, the founder is shipping a happy-path UI that will
+meet the five guaranteed failure modes (garbage / refusal / hallucination / timeout / cost
+spike) without a declared response. This loop opens at the first LLM call and closes when
+both the design doc exists AND the code references at least one failure-handler.
+
+`runner_type: hook` — the conscience evaluates this loop on every UserPromptSubmit. Entry
+predicate requires ≥1 LLM SDK call site (same pattern as `cost-budget-loop` — they share the
+inflection point: *the first time code touches the model*).
+
+When open, the conscience surfaces the `failure-mode` moment: *"The code calls an LLM but no
+failure-states doc exists. What does the UI do when the model returns garbage / refuses /
+hallucinates / times out / costs too much? Run `/ai-failure-states` to declare it."*
+
+## Entry artifact
+
+`src/` contains ≥1 LLM SDK call site (same regex as `cost-budget-loop`). The five failure
+modes exist the moment the first call exists; the loop opens at parity with the cost loop.
+
+## Purpose
+
+Force the failure-states design into the open before the user encounters them. The skill
+(`/ai-failure-states`) walks the founder through:
+- The five failure states + a project-specific concrete example for each
+- The declared response for each (in code-level detail; not "handle gracefully")
+- Stub fallback handlers in code (so the discipline is wired even if implementation is
+  incremental)
+- Cohort-aware delivery (first-product gets named patterns; eng-builder gets lint-anchored
+  unhandled-path discipline; domain-expert gets the human-in-the-loop discipline for
+  high-stakes domains)
+
+## Exit artifact
+
+`docs/ai-failure-states.md` exists AND `src/` contains ≥1 reference to a failure-handler
+function name (the regex covers the canonical TypeScript names and snake_case Python
+equivalents). The dual requirement matters: a design doc without code references is
+declaration without contract; handlers without a doc is code without rationale.
+
+## Drift
+
+Entry satisfied (≥1 LLM SDK call) AND exit not satisfied (no design doc OR no handler refs)
+→ loop is open → conscience emits `failure-mode` moment.
+
+Confidence: low on first detection (one call site might be exploratory); medium with a
+handful of calls; high when LLM calls touch user-visible code paths (heuristic: presence of
+the regex AND presence of `export`, `route`, `app.`, `Router`, `handler` near the call sites).
+
+The voice (cohort-aware via v0.20's framing): name the gap in one line, point at
+`/ai-failure-states`, hand the decision back. Never blocks. Override recorded in devlog per
+IDEA-008.
+
+## How to remix
+
+- **Skip:** legitimate when the LLM use is genuinely throwaway (dev-only script, no
+  user-facing path). Override:
+  ```
+  - **OVERRIDE:** skipped `ai-failure-state-loop` — rationale: <e.g., LLM call is in a
+    dev-only script; no user-facing path; not deployed>.
+  ```
+- **Swap discipline:** the five failure states are the floor, not the ceiling. Some projects
+  need rate-limit handling, model-deprecation discipline, regulatory-failure-mode design
+  (for `domain-expert` cohort projects). Add them in the doc; the loop's exit predicate just
+  needs *one* handler reference, so additional handlers are additive, not gated.
+- **Author your own:** a domain-specific failure discipline (e.g., a
+  `multimodal-fallback-loop` for projects where image/audio generation has its own failure
+  shape; or a `tool-use-failure-loop` for agentic workflows where the model picks the wrong
+  tool).
+
+## When this loop re-opens
+
+- Failure-states doc deleted → exit predicate fails again.
+- All handler references removed (refactor that strips them out) → ditto.
+- New LLM provider added that introduces a new failure surface (e.g., a multimodal API with
+  image-safety refusal patterns the existing doc didn't cover) → the founder should re-run
+  the skill to extend the doc; loop doesn't auto-detect this, but the founder should know.
+- Real-production failure surprise → the failure-state doc was incomplete. Add the new mode
+  + handler; refresh the declared response.
+
+## Cite
+
+Husain's *"categorize failures by mode — failure modes are more valuable than success
+modes"* applied to UX, not just evals. Liu (structured outputs make garbage detection
+mechanical, not vibes). Karpathy (the failure surface IS the design surface for AI-mediated
+products — designing the happy path is the easy 20%).

package/stages/L1-mvp/template/docs/loops/coordination-loop.md

@@ -0,0 +1,116 @@
+---
+id: coordination-loop
+type: loop
+stage: L1-mvp
+runner_type: hook
+attributed_to: [Ajesh Shah (PRINCIPLES — the conscience holds the seam AI erodes)]
+also_relevant: [Ju & Aral 2025 (human-AI teams' social/emotional comms drop ~27% while perceived quality stays flat — the invisible drift), Noam Wasserman (cofounder dynamics), Amy Edmondson (psychological safety)]
+entry:
+  - any_file_matches:
+      path_glob: .boss/config.json
+      pattern: '"handle"'
+  - count_at_least:
+      path_glob: docs/devlog.md
+      pattern: '^## \d{4}-\d{2}-\d{2}'
+      min: 3
+exit:
+  - count_at_least:
+      path_glob: docs/decisions/DEC-*.md
+      pattern: '^id:\s*DEC-\d'
+      min: 1
+drift_moment: coordination
+---
+
+# Loop: coordination (MVP) — the cofounder seam AI quietly erodes
+
+This is the founder layer's conscience moment (IDEA-037 / FEAT-021 slice 5b). It exists because of the
+single most-replicated finding in human-AI teaming: **AI accelerates each individual but does not hold the
+team together** — and worse, the human-to-human seam erodes *invisibly* (Ju & Aral RCT, n=2,234:
+social/emotional communication dropped ~27% while *perceived* teamwork quality stayed flat). A two-person
+team can feel productive while quietly building in parallel, each in their own AI session, never actually
+deciding anything *together*.
+
+The shared decision log (`DEC-NNN`) is the artifact that makes that drift visible. **A team that has been
+building for a while and has never recorded a single decision together** is the structural signal that work
+may be flowing *through* each founder's agent and *around* the cofounder.
+
+## Dormant-solo by construction
+
+The entry requires a cofounder on the roster (`.boss/config.json` carries a `"handle"`). A solo founder
+never opens this loop — there is no seam to watch. It only lights up once `boss team add` has put a second
+person on the venture. This is the same dormant-solo guarantee the rest of the founder layer holds.
+
+## The judgment the predicate can't make (and the model can)
+
+The predicate gate is coarse: *it's a team · real work has happened (devlog ≥3) · zero `DEC` recorded.*
+Regex can confirm those facts; it cannot tell whether the empty decision log means **the founders are
+genuinely deciding in parallel and drifting apart** (the real seam problem) or **they decided everything on
+a call and simply didn't write it down** (a quiet log that's perfectly healthy). That call is the model's,
+and it's the whole value of the moment.
+
+So the loop opens the door; the model walks through with judgment. When the door is open, the conscience
+reads a bounded slice — the decisions directory (empty), the board (`boss board`), who's on the team
+(`boss team`) — nothing wider. Then it judges: is one founder's solo-agent velocity high while the shared
+log sits untouched by the other, or is this honest parallel work with the deciding happening off-repo? If
+the former, name it in one spare line and ask the *coordination* question. If the latter, **stay silent** —
+a quiet log is not proof of a problem (this is the weakest-transfer evidence in the research; over-firing
+here would punish a team that simply talks on calls).
+
+## Entry artifact
+
+**A team building without deciding together** — `.boss/config.json` has a collaborator (`"handle"`) AND
+`docs/devlog.md` has ≥3 dated entries (real work has happened — same "enough has happened" gate the drift
+and capture loops use). Below 3 entries it's too early; a brand-new team isn't nagged before there's work.
+
+## Exit artifact
+
+**At least one shared decision recorded** — `docs/decisions/DEC-*.md` has ≥1 `DEC` (its `id:` frontmatter
+matches). Recording a single decision together closes the loop: the founders have proven they *do* decide
+jointly, and the never-decided-together smell no longer applies. The good outcome of a coordination nudge
+is a `/decide`.
+
+## Drift
+
+`entry: satisfied` (a team + ≥3 devlog entries) AND `exit: not satisfied` (no `DEC` yet) = loop OPEN →
+conscience emits the `coordination` moment. The model composes the voice (per `boss-voice`: seasoned hand,
+assume intelligence), reads only the bounded slice, and **judges before speaking** — never a "your teamwork
+score is low" read, never a satisfaction prompt (self-report is *proven blind* to the drift). The value is
+the specific, structural observation: *building a while, nothing decided together, are you two actually in
+this jointly?* It serves the **partnership as the unit** and **never takes a side** between the cofounders —
+it surfaces the seam; it never says whose fault it is. Pairs with `mentor-cofounder` for the deeper coaching.
+
+## Cost (BOSS eating its own dogfood)
+
+- The **predicate gate is the cost control** — the model reads the bounded slice only after the cheap Node
+  checks confirm (team + work + no decision). Every other prompt the hook emits nothing.
+- The read is **bounded** — decisions dir + board + team roster, never the whole project.
+- The model fires **at most once per session** and stays silent when the parallel work is honest.
+
+## Known limitation (documented, like focus-loop's)
+
+Exit is "≥1 `DEC` *ever*," so the moment targets the never-decided-together case and goes quiet after the
+first shared decision — even if the founders later drift back into parallel solo work. A "decided together
+*recently*" semantic would need a date-windowed count the predicate vocabulary doesn't have yet (the same
+gap `building_since` aging fills on the board side). The evidence here is weak-transfer to begin with, so
+the conservative once-and-quiet behavior is the right default; revisit if a real team shows the rebuilt-drift
+case matters. **This is design-from-principle, labeled a bet** — there is no peer-reviewed study on
+async multi-human/multi-AI founding teams; the loop watches the artifact channel the research points at,
+and fires conservatively.
+
+## How to remix
+
+- **Skip / override:** legitimate when the deciding genuinely happens off-repo (a distributed pair who talk
+  daily and just don't write `DEC`s). Override grammar:
+  ```
+  - **OVERRIDE:** skipped `coordination-loop` — rationale: <e.g. we decide on our daily call; the log lags
+    on purpose, we're not drifting>.
+  ```
+  Or mute it outright: `boss conscience mute coordination`.
+- **Tune the threshold:** a team that writes decisions rarely by preference might raise the devlog gate.
+
+## Cite
+
+PRINCIPLES.md (the conscience holds the seam). Ju & Aral 2025 (invisible human-AI team drift — the
+motivating evidence), Wasserman (cofounder dynamics), Edmondson (psychological safety). The loop is the
+*when*; the model's judgment + `boss board` + `/decide` (record one together) + `mentor-cofounder` are the
+*how*. Research design input: `docs/research/IDEA-037-founding-teams-ai-design-input.md`.

package/stages/L1-mvp/template/docs/loops/cost-budget-loop.md

@@ -0,0 +1,117 @@
+---
+id: cost-budget-loop
+type: loop
+stage: L1-mvp
+runner_type: hook
+attributed_to: [Husain (look-at-your-data, applied to spend), Liu (structured outputs as cost lever), Mollick (cost-as-design-input)]
+also_relevant: [Karpathy, Willison, Rauch]
+entry:
+  - count_at_least:
+      path_glob: src/**
+      pattern: '(anthropic|@anthropic-ai/sdk|openai|OpenAI\(|Anthropic\(|messages\.create|chat\.completions\.create|generateText|streamText)'
+      min: 1
+exit:
+  - exists: { path: docs/ai-cost-budget.md }
+  - count_at_least:
+      path_glob: src/**
+      pattern: '(logCall|log_call|ai-cost-logger|ai_cost_logger|costLogger)'
+      min: 1
+drift_moment: cost
+---
+
+# Loop: cost-budget (MVP)
+
+The discipline that **names the bill before the bill names you.** When code contains an LLM SDK
+call but no `docs/ai-cost-budget.md`, the founder is operating without unit economics for the
+single most-load-bearing operating cost of an AI-native app. This loop opens the moment that
+gap exists, and closes when the budget is declared AND a cost logger is in the codebase.
+
+`runner_type: hook` — the conscience evaluates this loop on every UserPromptSubmit. The entry
+predicate requires at least one LLM SDK call site, so it **doesn't fire on fresh projects** —
+it opens only when the founder has actually reached for an LLM in code. This is the *"the app
+is now AI-mediated"* inflection (IDEA-012's universal-cohort feature).
+
+When open, the conscience surfaces the `cost` moment: *"You're calling an LLM in code without
+a declared budget. Run `/ai-cost` to name what you'll spend per user, which models you chose,
+and how you'll see the bill before it surprises you."*
+
+## Entry artifact
+
+`src/` contains ≥1 LLM SDK call site — regex covers the common patterns:
+- `anthropic`, `@anthropic-ai/sdk`, `Anthropic(`
+- `openai`, `OpenAI(`
+- `messages.create`, `chat.completions.create`
+- Vercel AI SDK: `generateText`, `streamText`
+
+Threshold of 1 (not 3 like design-tokens-loop) because cost discipline is *deontic at the
+first call* — there's no "exploratory" version of token spend. The first call hits a real
+billing meter.
+
+Stack misses: founders on stacks the regex doesn't catch (LangChain wrappers, Replicate, Cohere,
+Bedrock client libs, etc.) can either edit this loop's entry pattern, or simply run `/ai-cost`
+manually (the loop respects override).
+
+## Purpose
+
+Force the cost shape into the open before it accumulates. The skill (`/ai-cost`) walks the
+founder through:
+- Cohort-aware budget defaults (first-product gets a tight cap; vibe-virtuoso gets inspect-only;
+  domain-expert gets privacy-first logging)
+- Per-call-site model choice with explicit *why*
+- A wrapper logger so every call writes to `.boss/cost-log.jsonl`
+- Review cadence + breach grammar
+- Optional handoff to `mentor-architect` (cost shape → architecture) or `mentor-business`
+  (cost-per-user → pricing)
+
+## Exit artifact
+
+`docs/ai-cost-budget.md` exists AND `src/` contains ≥1 reference to a cost-logging wrapper
+(`logCall`, `log_call`, `ai-cost-logger`, `ai_cost_logger`, `costLogger`). The dual requirement
+matters: a budget doc without instrumented code is theater (you wrote intent; you didn't wire
+sight). Instrumentation without a budget is observability without a target.
+
+## Drift
+
+Entry satisfied (≥1 LLM SDK call) AND exit not satisfied (no budget file OR no logger refs)
+→ loop is open → conscience emits `cost` moment.
+
+Confidence is medium on first detection (one call site might be exploratory) and high once
+there are multiple call sites — the math compounds with each user-facing path.
+
+The voice (cohort-aware via v0.20's framing): name the gap in one line, point at `/ai-cost`,
+hand the decision back. Never blocks. Override is recorded in devlog per IDEA-008.
+
+## How to remix
+
+- **Skip:** legitimate when the project's LLM use is genuinely throwaway (a one-off dev
+  script that won't reach users). Override:
+  ```
+  - **OVERRIDE:** skipped `cost-budget-loop` — rationale: <e.g., this LLM call is in a
+    dev-only script; not in user-facing code; not deployed>.
+  ```
+- **Swap discipline:** Husain's eval-driven cost reduction vs. caching-first (Anthropic prompt
+  caching as default) vs. batch-first (non-realtime workloads) vs. tiered-model (Haiku as
+  default, escalate to Sonnet only when needed). The loop's exit predicate checks for *some*
+  cost-logger in code, not a specific tool; the budget doc is where the founder records which
+  discipline they're applying.
+- **Author your own:** a domain-specific cost discipline (e.g., a `gpu-spend-loop` for a
+  fine-tuning project where the load-bearing cost is training, not inference; or a
+  `vector-store-cost-loop` for a RAG-heavy project where embeddings + storage dominate).
+
+## When this loop re-opens
+
+- Cost-logger wrapper deleted or renamed → exit predicate fails again.
+- Budget doc deleted → ditto.
+- New LLM SDK added (e.g., founder integrates a second provider) → entry may grow; check the
+  budget doc covers it; if not, treat as drift.
+- Model swap on a load-bearing call site → the budget doc's model rows are stale; re-run
+  `/ai-cost` to refresh.
+- Real-bill surprise → the bill IS the design signal. Add the new failure mode to the budget
+  doc; refine the levers.
+
+## Cite
+
+Husain's *"almost all AI quality problems are visible in the data, and almost no one looks"*
+applied to spend: *almost all AI cost problems are visible in the ledger, and almost no one
+keeps one.* Liu (structured outputs as a cost lever — smaller schemas, smaller bills).
+Mollick (cost-as-design-input: the bill shapes the product, not the other way around).

package/stages/L1-mvp/template/docs/loops/cost-review-loop.md

@@ -0,0 +1,113 @@
+---
+id: cost-review-loop
+type: loop
+stage: L1-mvp
+runner_type: hook
+attributed_to: [Husain (the cadence the eval-quality loop demands), Ajesh Shah (PRINCIPLE #1 applied to spend — the discipline only works when both halves run)]
+also_relevant: [Liu (structured outputs make cost-attribution mechanical), Maurya (running-the-business cadence)]
+entry:
+  - exists: { path: docs/ai-cost-budget.md }
+exit:
+  - count_at_least:
+      path_glob: docs/cost-reviews/REVIEW-*.md
+      pattern: '^- \*\*Total spend:\*\*'
+      min: 1
+drift_moment: cost-stale
+---
+
+# Loop: cost-review (MVP) — the cadence the budget doc declared
+
+> The v0.25 audit named this as a discipline hole: *"`/ai-cost`'s weekly review cadence is
+> declared in `docs/ai-cost-budget.md` but no skill reads `.boss/cost-log.jsonl`. The cadence
+> is unenforced."* v0.30 closes that. /ai-cost declares the budget; /cost-review reads the
+> ledger; both halves required.
+
+The loop opens once the founder has run `/ai-cost` and a budget doc exists. Until at least
+one cost-review file is recorded, the loop emits the `cost-stale` moment — *"you declared
+the budget; you haven't looked at the ledger yet."* The first review closes the loop.
+
+This is the **second time-of-work entry pattern** (after extraction-loop in v0.29). Entry is
+*budget declared* (a deontic gate — once you commit to budget discipline you also commit to
+read it); exit is *first review recorded*. Future versions may add recurring re-opening when
+predicates gain time-awareness.
+
+## Entry artifact
+
+`docs/ai-cost-budget.md` exists. This is the same exit predicate as cost-budget-loop, just
+shifted in role: the moment cost-budget-loop closes (budget declared + logger wired), the
+cost-review-loop opens (now read what you wired). The two loops form a sequence: declare →
+read → declare-adjustments → read-again.
+
+## Purpose
+
+Force the reading half of the discipline. Most projects ship `/ai-cost` and then never look
+at the ledger; the budget becomes aspirational. This loop closes the gap between *"we
+declared"* and *"we know."* The skill `/cost-review` is the actual read; the loop opens the
+door at the first reasonable moment (immediately after the budget is declared).
+
+## Exit artifact
+
+≥1 file matching `docs/cost-reviews/REVIEW-*.md` containing a `^- \*\*Total spend:\*\*` line.
+The `/cost-review` skill writes these. The presence of *any* review with real numbers closes
+the loop; the discipline IS the practice of reading, not the volume of reviews.
+
+To re-open the loop (for recurring weekly reviews), the founder can either:
+- Rename or archive old reviews into a sub-directory (`docs/cost-reviews/archive/`) — old
+  files no longer match the glob; loop re-opens.
+- Or simply re-run `/cost-review` weekly; the existence of a *newer* review doesn't change
+  the loop state today (predicate vocabulary doesn't compare file ages — same gap that
+  extraction-loop hit; same trade-off).
+
+For v0.30, the loop is the **first-review inflection.** Future versions may add time-aware
+predicates (*"latest review file's mtime is older than 7 days"*) to enforce recurring cadence.
+
+## Drift
+
+Entry satisfied (budget doc exists) AND exit not satisfied (no review file) → loop is open →
+conscience emits `cost-stale` moment.
+
+Confidence: low immediately after the budget is declared (the founder might still be in
+mid-session running other discipline skills; ledger may be empty); medium if the budget is
+older than a session or two; high if real spend has accumulated in the ledger without a
+review on record.
+
+The voice (cohort-aware via v0.20's framing): name the unread-ledger gap in one line, point
+at `/cost-review`, hand the decision back. Don't sound like a productivity-reward;
+*"you declared a budget — worth looking at what actually happened?"* lands better than
+*"great, time to review!"*
+
+## How to remix
+
+- **Skip:** legitimate when the ledger is genuinely empty (no LLM calls yet — though usually
+  in that case `cost-budget-loop` is still open and this one shouldn't fire yet) OR when the
+  founder is in a single concentrated build session and reviewing-then-restarting would just
+  fragment attention. Override:
+  ```
+  - **OVERRIDE:** skipped `cost-review-loop` — rationale: <e.g., ledger has < 50 entries;
+    not yet enough signal to surface; re-check after FEAT-NNN ships>.
+  ```
+- **Swap discipline:** Maurya's running-the-business weekly review vs. Husain's eval-quality
+  loop (review the eval set + costs together) vs. Liu's structured-outputs lens (track
+  cost-per-structured-schema-shape, not just per-call). Loop's exit predicate just needs
+  *some* review with real numbers; the discipline framing is the founder's.
+- **Author your own:** a complementary review loop (e.g., `eval-review-loop` for re-running
+  eval sets weekly; `failure-state-review-loop` for confirming declared handlers actually
+  caught the recurring failures). Same time-of-work pattern.
+
+## When this loop re-opens (today: requires founder action)
+
+v0.30 ships the first-review version. Once a review file exists, the loop stays closed —
+even if the review is stale (older than the cadence the doc claims). The recurring version
+is gated on the predicate vocabulary gaining time-awareness; same dependency as
+extraction-loop.
+
+For now: founders running the weekly cadence either re-run the skill or rotate old reviews
+into an archive directory. The conscience doesn't auto-nudge after the first read.
+
+## Cite
+
+Husain (look-at-your-data, applied to spend not just quality — *"almost all AI cost problems
+are visible in the ledger, and almost no one keeps one OR reads it"*). Ajesh Shah (PRINCIPLE
+#1 applied recursively: declaring is half; reading is the other half; both required).
+Maurya (running-the-business cadence — the review IS the running). Liu (structured outputs
+make per-call cost-attribution mechanical, not vibes).