@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/.claude/rules/auto-fix-criteria.md

@@ -0,0 +1,126 @@
+---
+tier: lite
+description: /auto-fix is the autonomous fix workflow for non-trivial narrow bugs.
+---
+
+# Auto-Fix Entry Criteria + Blast-Radius Floor
+
+`/auto-fix` is the autonomous fix workflow for non-trivial narrow bugs.
+Entry is gated by STRICT criteria AND a hard blast-radius floor.
+This rule codifies them.
+
+## Entry criteria (ALL must hold)
+
+1. **Narrow scope** — one concern, statable in one sentence
+2. **Named code area** — operator supplies a file/module/route path
+3. **NOT in blast-radius floor** (see below) — hard floor, no override
+4. **Builder agent available** — `.claude/agents/Builder.md` configured
+5. **Clear acceptance criteria** — one sentence, measurable
+
+Any failure → escalate to manual /diagnose or /quick-fix (if trivial).
+
+## Blast-radius floor (HARD — NO OVERRIDE)
+
+These paths ALWAYS force the manual lane, regardless of other criteria
+and regardless of how narrow the proposed fix is. There is no
+`SKIP_BLAST_RADIUS` env var. Autonomous fixes here produce silent
+failures affecting every user / every request / the whole deploy
+pipeline — the blast radius justifies always asking a human.
+
+- **Auth code**: `src/lib/auth/**`, `src/app/api/auth/**`,
+  `src/middleware.ts` where auth logic lives
+- **Schema**: `prisma/schema.prisma`, `prisma/migrations/**`
+- **Security primitives**: `src/lib/security/**`, crypto, signing,
+  token handling
+- **Tenant isolation**: any tenant-scoped query, tenant context
+  resolution, tenant-bound middleware
+- **Middleware** (any `middleware.ts` file): system-wide effect
+  disqualifies autonomous writing
+- **Production infrastructure**: `.github/workflows/deploy*.yml`,
+  prod env-var config, CDN/DNS config, database seed data
+
+Rationale: the floor isn't "stuff that's hard." It's "stuff where
+silent wrong answers compound." An agent writing wrong auth code
+looks fine locally, passes /verify, ships, and compromises every
+session. Hard floor is the only shape that survives that failure
+mode.
+
+## Override path
+
+There is none for blast-radius. That's the point.
+
+For the entry-criteria (narrow scope / named area / Builder-available /
+acceptance criteria), there is also no override — softening any of
+those means the skill is being used for cases it wasn't designed for.
+Escalate to manual lane.
+
+## Audit discipline
+
+Every /auto-fix commit carries `[auto-fix]` footer. Monthly audit:
+
+```bash
+FIX=$(git log --all --since='30 days ago' --grep='^fix:' --oneline | wc -l)
+AF=$(git log --all --since='30 days ago' --grep='\[auto-fix\]' --oneline | wc -l)
+
+echo "Auto-fix ratio: $AF / $FIX"
+```
+
+Target: ≤25% of fix branches use /auto-fix. Higher = either Builder
+is being dispatched where manual judgment was needed, or defect mix
+is systematically narrow (upstream architectural issue worth
+surfacing).
+
+## What "narrow" means (operational definition)
+
+A scope is narrow if ALL hold:
+
+- The defect affects one callsite or one code path (not cross-cutting)
+- The fix is ≤50 lines (more than /quick-fix's 10, less than a feature)
+- No new interfaces, abstractions, or decorators
+- No schema changes
+- Tests for the fix can be written without refactoring existing tests
+
+If any of these fail, the scope is not narrow enough for /auto-fix.
+Either use /decompose + normal Construction, or split the defect.
+
+## Operator responsibilities
+
+Operator still does:
+
+- Supplies the code area path (criterion 2)
+- Reviews the PR (operator merge is final gate)
+- Decides whether to merge
+
+Operator does NOT do:
+
+- Write the fix (Builder does)
+- Run /diagnose (Orchestrator invokes it)
+- Run /verify (Builder runs it)
+
+## Enforcement
+
+- Skill: `.claude/skills/auto-fix/SKILL.md` requires explicit entry-
+  criteria output + blast-radius floor confirmation as Step 1
+- Methodology: agent self-checks the floor before every edit; silence
+  is not confirmation
+- PR review: operator MUST confirm floor compliance in review before
+  merging (checkbox in PR description)
+- Future: pre-commit hook could grep staged paths against the floor
+  list and emit BLOCKED: blast-radius on match. Not required for v1;
+  methodology + PR checkbox is sufficient.
+
+## Relationship
+
+- `.claude/skills/auto-fix/SKILL.md` — skill that cites this rule
+- `.claude/skills/diagnose/SKILL.md` — full ceremony always runs
+- `.claude/rules/quick-fix-criteria.md` — sibling for trivial lane
+- `.claude/rules/guardrails.md` — "deploy prod without approval" floor
+  aligns with this floor
+- `blocked-items.md` — escalation paths are not optional
+
+## When this rule retires
+
+It doesn't. The blast-radius floor is load-bearing forever. If the
+floor needs to change, it's an ADR discussion, not a rule edit.
+
+Closes bassclef #152 (paired with skill).

package/dist/lite/.claude/rules/bassclef-hook-drift-blocker.md

@@ -0,0 +1,144 @@
+---
+tier: lite
+description: "The bassclef-sync.sh SessionStart hook emits a 🛑 BLOCKED block when the consumer repo's hook version differs from bassclef's current template version."
+---
+
+# Bassclef Hook Drift — Session Block
+
+The `bassclef-sync.sh` SessionStart hook emits a `🛑 BLOCKED` block
+when the consumer repo's hook version differs from bassclef's
+current template version. Drift means a `bassclef-template-sync` PR
+is open in the consumer repo and has not been merged.
+
+When this block appears in session-start output, the agent MUST NOT
+proceed with substantive work until the operator has merged the
+pending PR OR explicitly overridden the block.
+
+## Protocol on detection
+
+When session-start output contains the `BLOCKED: bassclef hook drift`
+block, the agent MUST:
+
+1. **Surface the block to the operator** verbatim — same 🛑
+   emojis, same horizontal rule, same PR link, same resume command.
+   The operator should see exactly what the hook emitted.
+2. **Refuse substantive work** until drift is cleared. "Substantive"
+   means: code edits, agent spawns, destructive operations, external
+   calls. Read-only inspection (Read, Glob, Grep) is fine — the
+   operator may need it to understand what's pending.
+3. **Offer the two paths forward**:
+   - **Merge path** (preferred): operator merges the pending PR,
+     then tells the agent "merged" (or equivalent)
+   - **Override path**: operator explicitly says "proceed anyway"
+     (or equivalent), accepting the stale-hook risk
+
+## After operator merges the PR
+
+On "merged" signal, run the resume sequence the hook printed:
+
+```bash
+cd "$CWD" && git pull origin main && \
+echo '{"cwd":"'"$CWD"'"}' | bash .claude/hooks/bassclef-sync.sh
+```
+
+`$CWD` is the consumer repo root from the original block message.
+
+Re-reads the hook from disk, re-runs the SessionStart logic, emits
+a fresh summary. If the merged PR did what it claimed, the new
+summary shows no drift — session is unblocked.
+
+If drift still detected after re-run, something is off:
+- Merge may have been to wrong branch
+- Template version header may not have been bumped in the PR
+- Surface this as a secondary failure, don't retry silently
+
+## After operator overrides
+
+On "proceed anyway" signal, the agent proceeds with substantive work
+but **carries the override forward in session context** — include
+a one-line reminder in any non-trivial artifact ("produced under
+stale-hook override, merge PR N before next session") so the operator
+remembers to clean up before future sessions.
+
+## What counts as override phrasing
+
+Only explicit operator statements count:
+- "proceed anyway"
+- "override"
+- "I'll merge later"
+- "skip drift check"
+- "go" alone is NOT an override — may just be unrelated work instruction
+- Silence or ambiguity = still blocked
+
+## What counts as "merged" confirmation
+
+- "merged" / "merged it" / "done" after the block surfaced
+- Operator posts a merged-PR link or screenshot
+- Agent's own MCP check finds the PR in `closed` state with non-null
+  `merged_at` (optional enhancement; not required for v1)
+
+## Relationship to other rules
+
+- `.claude/rules/blocked-items.md` — general "BLOCKED: means resolve
+  or explicitly defer" protocol; this rule is a specific instance
+- `.claude/rules/mobile-ephemeral-session.md` — ephemeral mobile
+  sessions are where this rule has the highest value (drift most
+  likely because mobile sandbox hook is vendored, not live)
+- `.claude/rules/sdlc-gates.md` — observed failures fire
+  temperance → diagnose; drift is a gate, not a failure, so it runs
+  before the failure chain
+- `ADR-014-substrate-sync-strategy.md` — architectural context
+
+## URL rotation PRs are NOT covered by this rule
+
+This rule fires on **template** drift (version header mismatch),
+NOT on URL rotation PRs. URL rotation does not change hook semantics;
+the current URL in `.bassclef-url` on main is still valid for its
+TTL window. Blocking mobile sessions on routine URL rotation would
+defeat the S3 distribution model's purpose.
+
+Only the `bassclef-template-sync` workflow triggers drift.
+
+## Complementary: workflow-staleness hook (bassclef-side, WU-9d)
+
+This rule catches drift in **consumer repos** (template version mismatch
+between consumer's vendored hook and bassclef's current template).
+The complementary signal lives on **bassclef itself**:
+`.claude/hooks/session-reflection.d/80-workflow-staleness.sh` queries
+bassclef-side distribution workflows and BLOCKs bassclef sessions
+when any monitored workflow has failed >24h without recovery.
+
+**Workflows monitored** (current):
+
+- `bassclef-s3-publish.yml` — S3 tarball + URL refresh (retiring under
+  bassclef#446 LR8.5 WU-2 once consumers migrate from `.bassclef-url`
+  to `.bassclef-source.json`)
+
+**Retired** (no longer monitored):
+
+- `bassclef-template-sync.yml` — retired 2026-05-03 (PR #445). Auto-
+  PR-based template propagation replaced by the thin-pointer architecture
+  (consumer's dispatcher hook reads `.bassclef-source.json` and fetches
+  bassclef's current template at every session-start; no vendoring,
+  no drift class for thin-pointer consumers).
+
+The hook + this rule together close the silent-failure loop that
+surfaced 2026-04-26-2026-04-27 when bassclef-template-sync.yml
+failed on two consecutive runs without operator notice. With template-
+sync retired, that specific failure mode is structurally impossible —
+the workflow no longer exists. The hook still monitors remaining
+distribution workflows (and any future ones) on the same pattern.
+
+| Layer | Hook | What it catches |
+|---|---|---|
+| Consumer repo | `bassclef-sync.sh` (this rule) | Vendored hook out of date with bassclef's current template version (vendored-snapshot consumers only; thin-pointer consumers opt out structurally) |
+| Bassclef repo | `80-workflow-staleness.sh` | Distribution workflow failed >24h ago |
+
+When the bassclef-side hook fires, the consumer-side rule may still
+be quiet (because no new template version has been published yet —
+that's exactly the failure the workflow was trying to ship). Reading
+both signals together gives the full picture.
+
+Override path (workflow-staleness hook): `SKIP_WORKFLOW_STALENESS=1`
+or `WORKFLOW_STALENESS_HOURS=N` per-session env. Same trace-logging
+discipline as other bassclef hooks.

package/dist/lite/.claude/rules/bassclef-models-discovery.md

@@ -0,0 +1,107 @@
+---
+tier: lite
+description: "This rule tells consumer-repo agents where bassclef's models live."
+---
+
+# Bassclef Models Discovery
+
+This rule tells consumer-repo agents where bassclef's models live. Bassclef's design + architecture + decomposition docs stay in bassclef's repo (not vendored into consumers). Agents reading this rule navigate to bassclef when they need a model — by local sibling, by remote browse, or by GitHub URL.
+
+## When this rule fires
+
+Any consumer-repo session where the agent needs to:
+- Understand a bassclef concept (Consumer, Sibling, Harness, GitState, Hook, AutoSave, etc.)
+- Cite a bassclef ADR in a substrate change
+- Read bassclef's interaction model when fixing a binding defect
+- Reference the object-model catalog
+- Find a design discovery or earned-wisdom principle
+
+Most consumer-repo work doesn't need bassclef's models. This rule activates when it does.
+
+## Where bassclef's models live
+
+Single discovery surface in bassclef: `design/models-index.md`. It catalogs the Tier 1 source-of-truth models with paths + last-updated dates + diagram-status.
+
+Direct GitHub URL: `https://github.com/sunj-labs/bassclef/blob/main/design/models-index.md`
+
+From the index, navigate to specific models:
+
+| If you need | Read |
+|---|---|
+| App-domain noun catalog (User, Agent, Tool, Deal, ...) | `design/object-model.md` |
+| Runtime-interaction model (Consumer, Sibling, Harness, ...) | `docs/decompositions/bassclef-interaction-model.md` (also rendered via ADR-018) |
+| What bassclef persists across sessions | `standards/state-spine.md` |
+| Trust zone flow (runtime security sequence) | `design/trust-zone-flow.md` |
+| Core Five engineering principles | `design/engineering-principles.md` |
+| Bassclef-as-context-engineering framing | `design/bassclef-as-context-engineering.md` |
+| Architecture decisions (ADRs) | `architecture/decisions/` (numbered ADR-NNN files) |
+| Earned-wisdom discoveries | `design/discoveries/` (with README index) |
+| Vendor bindings + portability | `standards/vendor-bindings.md` |
+
+All paths are relative to bassclef's repo root.
+
+## How to navigate
+
+Three access patterns, in order of preference:
+
+### 1. Local sibling (fastest)
+
+If the operator has bassclef checked out at `~/src/sunj-labs/bassclef` (typical sunj-labs workstation layout), navigate directly:
+
+```bash
+cat ~/src/sunj-labs/bassclef/design/models-index.md
+```
+
+This works offline. Beware staleness — local sibling may not be current; see bassclef#576 for the drift class. To verify freshness:
+
+```bash
+cd ~/src/sunj-labs/bassclef && git fetch origin main && git log -1 origin/main --format='%H %s'
+```
+
+### 2. gh CLI (current; GitHub-Locked)
+
+If on a developer machine with `gh` installed + authenticated:
+
+```bash
+gh repo view sunj-labs/bassclef --json url
+gh api repos/sunj-labs/bassclef/contents/design/models-index.md --jq '.content' | base64 -d
+```
+
+This always reads bassclef's current `main`. Network-dependent.
+
+### 3. Browser
+
+Open `https://github.com/sunj-labs/bassclef/blob/main/design/models-index.md`. Works for human operators. Agents typically prefer paths 1 or 2.
+
+## What this rule does NOT do
+
+- Does NOT vendor bassclef's models into the consumer repo. Models stay in bassclef; consumers reference + navigate as needed.
+- Does NOT auto-fetch bassclef's models at consumer session-start. Fetching happens on-demand when the agent decides it needs a model.
+- Does NOT cache bassclef's models in the consumer. Each lookup is fresh (or as-fresh-as-the-access-pattern-allows).
+
+## Vendor binding posture
+
+Per `standards/vendor-bindings.md`:
+
+- **This rule itself**: Agent-Agnostic. Works on any git provider — the rule's text contains URLs + paths; consumer agents navigate via whatever's available (local sibling, gh / az repos / glab / browser).
+- **Path 2 (`gh` CLI)**: GitHub-Locked. ADO consumers substitute `az repos`; GitLab consumers substitute `glab`; etc. The rule body should be read as a pattern, not a strict gh-only instruction.
+
+## What this enables
+
+A consumer-repo agent debugging a bassclef-related defect can:
+
+1. Read this rule at session-start (auto-loaded via bassclef-sync's `additionalDirectories` wiring)
+2. Recognize "I need bassclef's interaction model"
+3. Navigate via local sibling or gh CLI
+4. Read `design/models-index.md`
+5. Navigate from there to the specific model
+
+Without this rule, step 1 doesn't happen — the consumer agent has no signal that bassclef even has an index, much less where it lives.
+
+## Operator-why
+
+Per `design/discoveries/README.md` schema — operator-why anchoring:
+
+> Single-operator + family + day job + mobile-dispatchable. The operator cannot afford to manually tell each consumer-repo agent "go look at bassclef's models." A rule that propagates via bassclef-sync to every consumer means each consumer's agent has the signal at session-start, automatically, with no operator-per-session cost.
+
+The discipline is propagation, not vendoring. Vendoring grows the consumer's filesystem with bassclef's design library + introduces snapshot drift. This rule keeps content in bassclef, distributes the pointer.

package/dist/lite/.claude/rules/bassclef-workflow-parity.md

@@ -0,0 +1,104 @@
+---
+tier: lite
+description: When modifying any file matching .github/workflows/bassclef-*.yml, grep the other files in the same directory for the pattern you just changed.
+---
+
+# Bassclef Workflow Parity
+
+When modifying any file matching `.github/workflows/bassclef-*.yml`,
+grep the other files in the same directory for the pattern you just
+changed. If a sibling has the same shape, update it in the same PR.
+
+This rule exists because we've shipped the asymmetry twice in six
+days. Both times the fix was one or two lines in the sibling. Both
+times the cost was a second PR, a session retrospective, and operator
+trust in the propagation path.
+
+## What triggers the rule
+
+Any edit (Edit/Write tool) to a file matching:
+
+```
+.github/workflows/bassclef-s3-publish.yml
+```
+
+(Today that's the only one. `bassclef-template-sync.yml` retired
+2026-05-03 in PR #445 — the thin-pointer architecture replaced auto-PR-
+based template propagation. `bassclef-s3-publish.yml` retires under
+bassclef#446 LR8.5 WU-2 once every consumer migrates from
+`.bassclef-url` to `.bassclef-source.json`. After that, this rule
+sits dormant until a future `bassclef-*.yml` workflow ships.)
+
+## What the rule requires
+
+Before the PR merges, the agent MUST:
+
+1. Glob `.github/workflows/bassclef-*.yml` — enumerate all siblings.
+2. For each pattern being changed in the PR (matrix shape, Slack
+   message format, env var handling, etc.), grep the siblings for
+   that pattern.
+3. If a sibling has the pattern and it's not being updated in this
+   PR, either:
+   - Include it in this PR (preferred — one change, one shape)
+   - Explicitly defer it: open a follow-up issue NOW, note it in the
+     PR description, and state why the sibling deferral is safe
+
+Silence about the sibling is not deferral.
+
+## What satisfies the rule
+
+A "Sibling parity" block in the PR description enumerating:
+
+```
+## Sibling parity
+
+Checked `.github/workflows/bassclef-*.yml`:
+- `bassclef-s3-publish.yml` — [touched in this PR / unchanged because X]
+- `bassclef-template-sync.yml` — [touched in this PR / unchanged because X]
+```
+
+Or, if no siblings have the pattern: "Sibling parity: pattern is
+unique to this file (confirmed via grep)."
+
+## Concrete patterns to check
+
+From the two incidents to date — these are the patterns most likely
+to live in more than one file:
+
+| Pattern | Example | Lives in |
+|---------|---------|----------|
+| `matrix.consumer` list | 5-consumer list for fan-out | both workflows |
+| Slack message composition | jq `--arg` vs string-interpolation | both workflows |
+| Slack emoji convention | 🤖 auto / 🙋 human | both workflows |
+| GitHub Actions env / secret names | `SLACK_WEBHOOK`, `BASSCLEF_CONSUMER_WRITE_TOKEN` | both workflows |
+| Workflow trigger shape | `workflow_dispatch` inputs, cron schedule | may diverge legitimately |
+| Timeout / retry behavior | per-job defaults | usually shared |
+
+## Relationship to other rules
+
+- `artifact-ingestion.md` — reads artifacts before producing; this
+  rule extends the discipline to "reads siblings before committing"
+- `commit-conventions.md` — PR titles and descriptions carry the
+  parity block
+- `sdlc-gates.md` — post-build gate; parity check is a pre-merge
+  checklist item
+
+## Enforcement
+
+Methodology-level today. If this rule fires a third time and the
+grep-before-merge discipline fails, upgrade to a pre-commit or
+pre-merge hook that:
+
+1. Detects files changed matching `.github/workflows/bassclef-*.yml`
+2. Runs `grep -l` for key patterns across siblings
+3. BLOCKS unless PR description contains a "Sibling parity" block
+
+Until then, the rule stands on the agent's discipline. Read siblings
+before closing the PR.
+
+## Override path
+
+`SKIP_BASSCLEF_PARITY=1 <tool-call>` — logged to trace. Use only
+when the pattern being changed is genuinely unique to one workflow
+(e.g., a schedule change that applies to publish but not
+template-sync).

package/dist/lite/.claude/rules/cost-governance.md

@@ -0,0 +1,154 @@
+---
+tier: lite
+globs: ["*"]
+description: Cost governance — budget enforcement from substrate.config.md manifest
+---
+
+# Cost Governance
+
+Budget and model routing are defined in the project's `substrate.config.md`.
+This rule applies in ALL configurations (operator-gated, orchestrator-gated,
+sequential, parallel).
+
+## Budget behavior (Orchestrator enforces in orchestrator-gated mode)
+
+| Event | Action |
+|---|---|
+| Session start | Read session_ceiling and iteration_ceiling from manifest. If iteration_ceiling missing, ask operator. |
+| 75% of iteration ceiling | Surface status: spend to date, remaining, work completed vs scope. Continue unless operator says stop. |
+| Iteration ceiling hit | Pause. Report state. Propose descoped continuation that fits remaining budget. INSTEAD of silent hard-stop: surface the ceiling hit + 2-3 descope options to operator. |
+| Session ceiling approached | Warn operator. Complete current atomic unit of work. Do not start a new iteration. |
+| Replenish floor hit | Surface. Recommend deferring remaining iterations to next session. |
+
+## Cost tracking (all levels)
+
+Track cost at phase boundaries. The system reports proactively.
+
+INSTEAD of waiting for the operator to ask "what did this cost?":
+emit a one-line cost summary at every phase boundary (turn count +
+duration + scope completed) automatically.
+
+### At phase start (estimate)
+
+Before activating agents for a phase, estimate:
+- Number of subagent spawns planned (0 for sequential mode)
+- Estimated turns per agent based on phase and scope
+- Total estimated phase cost (burst + Pro plan time)
+- Remaining budget after this phase
+
+### At phase end (actuals)
+
+After a phase completes, report in whereami.md:
+
+```markdown
+## Cost tracking
+| Phase | Agents | Turns | Burst cost | Duration | Notes |
+|-------|--------|-------|-----------|----------|-------|
+| Inception | Shaper, PM | 12 | $0 | 8m | Sequential — no burst |
+| Elaboration | Architect, Designer | 18 | $0 | 14m | Sequential |
+| Construction | Builder, Reviewer | 35 | $0 | 25m | 3 branches |
+| **Total** | | **65** | **$0** | **47m** | |
+
+Budget: $0 ceiling / $0 spent / on track
+```
+
+### At session end
+
+Include in the chronicle:
+- Total turns used
+- Total duration (approximate)
+- Cost per artifact produced (turns / artifacts)
+- Budget utilization (% of ceiling used, or "sequential — $0 burst")
+- Scope completed vs planned
+
+### Sequential mode
+
+Burst cost is $0 but Pro plan time still matters. Track:
+- Turn count per phase
+- Duration per phase (approximate)
+- These help calibrate future time budget estimates
+
+### Where to get cost data
+
+- Turn count: count conversation turns per phase
+- Duration: note timestamps at phase boundaries
+- Burst cost: relevant only in parallel mode (subagent spawns)
+- If exact data isn't available, estimate and note the method
+
+## Sequential-mode cost messaging (#113)
+
+When the session is sequential (operator-gated OR orchestrator-gated),
+burst cost is $0. Pro plan time still consumes, but there is no
+per-turn API burst charge. Agents MUST NOT report dollar figures
+like "$30 / 100 turns" for sequential work — it materially overstates
+spend and pushes scope decisions smaller than needed.
+
+Correct framings for sequential mode:
+
+- "Sequential — $0 burst, ~N turns, ~M minutes"
+- "Budget: $0 ceiling / $0 spent (sequential) / on track"
+- "Full goal is $0 burst / 100 turns budgeted"
+
+INSTEAD of dollar figures in sequential reports: use turn count +
+duration. Dollar figures apply ONLY when parallel execution is active
+(subagent spawns) or when the session uses a paid-API service with
+disclosed unit cost (see `iteration-bet.md` §Paid-API costs).
+
+## Operator-gated sessions
+
+Cost tracking is advisory, not enforced. The rules below still apply:
+- No unbounded loops (retry forever, poll indefinitely)
+- No recursive agent spawning without depth limits
+- Prefer single-pass solutions over iterative refinement loops
+- If a task is taking 3x longer than expected: stop, diagnose, escalate
+- At session end, note approximate scope of work in the chronicle
+
+## Model routing
+
+Defined per-agent in manifest. Default routing:
+
+| Agent | Model | Rationale |
+|---|---|---|
+| Orchestrator | haiku | Routing — no deep reasoning needed |
+| Shaper | opus (Inception only) | Problem framing is highest-leverage thinking. Revert to sonnet after. |
+| PM | sonnet | Viability hypotheses require judgment |
+| Creative Director | sonnet | Brief and token work — nuanced but not architecturally complex |
+| Architect | sonnet | ADRs and C4 require real reasoning |
+| Designer | sonnet | UX judgment |
+| Builder | sonnet | Code quality matters; haiku produces more rework |
+| Reviewer | haiku | Checklist evaluation — mechanical |
+| Deployer | haiku | Pipeline execution — deterministic |
+| Closer | haiku | Gate checklist — administrative |
+
+Opus escalation: Shaper may request Opus outside Inception if problem framing is genuinely novel and high-stakes. Orchestrator logs escalation and cost delta. Operator notified.
+
+## Rate limit awareness (parallel mode)
+
+Parallel worktree agents multiply API request rate against the same account
+quota. Rate limits are per-account, not per-session — 3 parallel agents
+consume 3x the RPM/TPM.
+
+| Risk | Mitigation |
+|------|-----------|
+| 429 errors from concurrent agents | Stagger agent starts by 30s |
+| Context window bloat per agent | Send only relevant files, not full repo |
+| Cascading retries amplify pressure | On 429: INSTEAD of immediate retry, wait Retry-After header value |
+| Account-level quota exhaustion | Max 2 concurrent agents for most tiers |
+
+If rate limits persist after 3 retries, switch to sequential mode.
+See `standards/worktree-management.md` for full parallel operations protocol.
+
+## Hook enforcement
+
+The pre-build-gate hook (`pre-build-gate.sh`) enforces budget at runtime:
+
+- Tracks edit count per session as a proxy for turns consumed
+- At 75% of turn limit: surfaces a budget status line
+- At 100% of turn limit: surfaces a hard warning to pause and report
+
+The hook reads the turn limit from the active iteration goal. If no bet
+exists, budget tracking is advisory only (no warnings).
+
+This is a lightweight enforcement layer. The Orchestrator (at standard/full
+level) has additional budget responsibilities defined in the budget
+behavior table above.