akili-specs 2.13.0 → 2.14.0

package/.claude/commands/akili-audit.md

@@ -49,6 +49,7 @@ Audit for discrepancies, classifying findings under the following categories:
 * **Technical Constraints Violation:** Architectural layout in the codebase that conflicts with patterns (e.g. testing requirements, security rules, file structuring) documented in `docs/trd/trd.md`.
 * **Agent Guide Drift:** Modules whose conventions clearly diverge from the root but lack a child `CLAUDE.md`/`AGENTS.md`, child guides missing from the parent's `## Module Guides` index, guide entries pointing at modules that no longer exist, or root-guide structure descriptions that no longer match the codebase.
 * **Model Registry Drift:** The project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) names models the host tool no longer offers, uses dated model pins where a floating alias exists (violating the alias-first rule) without a recorded reason, is missing tiers or the author ≠ auditor note versus the packaged default in `docs/model-routing.md`, or the Step 8E agent wrappers (`.claude/agents/akili-*.md` / OpenCode agent config) declare models that contradict the registry. Report only — never edit the registry or wrappers during the audit.
+* **Model Generation Drift:** Aliases absorb a new model generation silently, so the *registry* can be perfectly current while everything calibrated around it has gone stale. Flag, without editing: (a) a **frontier escalation pin** whose recorded reason predates the current `opus` generation — each generation narrows the gap the pin was bought to close, so it needs re-justification against the alias at `xhigh`/`max`; (b) an **`Updated:` stamp older than the current model generation**, meaning the effort defaults were never swept for it (`docs/model-routing.md` → *Effort dial* → re-baseline rule); and (c) `.agents/*.md` personas missing guardrails the packaged templates have gained since — most importantly the **Delegation Ceiling** in `leader.md` and the both-directions **Scope Discipline** in `implementer.md`, which counter over-delegation and scope expansion in current-generation models.
 
 ### Step 3: Write Drift Report
 

package/.claude/commands/akili-constitution.md

@@ -247,7 +247,7 @@ Create or enhance `docs/trd/trd.md` as the technical implementation blueprint.
 
 ### Step 6: Create or Enhance the Infrastructure Document
 
-Create or enhance `docs/infrastructure.md` as the deployment and hosting blueprint.
+Create or enhance `docs/infrastructure.md` as the environments blueprint — from the developer's laptop to PROD.
 
 The infrastructure shape derives from the TRD's robust-vs-lite tier decision (Step 5, `software-architect` skill) — never precedes it. Cite the tier decision and its ADR at the top of the document.
 
@@ -258,9 +258,30 @@ The infrastructure shape derives from the TRD's robust-vs-lite tier decision (St
 3. Deployment Strategy (e.g., CI/CD, Terraform, CDK)
 4. Network & Security Architecture
 5. Infrastructure Rules & Constraints
+6. Local Environment (the contract below)
 
 If this information is missing during the initial setup or discovery phase, explicitly ask the user for the intended infrastructure specifications before drafting this document.
 
+#### Step 6B: The Local Environment Contract
+
+Scaffold a `## Local Environment` section that captures how to start the project's local stack (database, backend, frontend). The methodology defines a **contract, not a tool** — Docker Compose is the recommended primary route, but the contract must always document a fallback for users without Docker:
+
+| Element | What to record |
+|---------|----------------|
+| Primary route (recommended) | e.g. `docker compose up -d` |
+| Fallback route (no Docker) | e.g. `npm run dev` per service + a local or cloud dev database |
+| Pre-check | e.g. `docker info` — on failure (daemon off, not installed), surface it and offer: start Docker, or use the fallback. Never block silently |
+| Seed / reset data | explicit commands |
+| Health check | how to verify the stack is up |
+| URLs / ports | frontend, backend, database |
+
+Mode-specific behavior:
+
+- **Legacy / Active:** derive the contract from evidence — existing `docker-compose*.yml`, `Makefile`, `package.json` scripts, README run instructions. Do not invent commands; ask the user to confirm anything ambiguous.
+- **Brand-new:** offer to scaffold a development compose file (db + backend + frontend) matching the TRD stack. If the user declines or has no Docker, record the native fallback as the primary route.
+
+**Boundary rule (record it in the section):** the local environment is **disposable** — agents may freely start, seed, and reset it to verify work. Deployments to cloud/PROD are **governed** — they follow this document's sections 1–5 (components, IaC, CI/CD defined at constitution time) and are never improvised by agents.
+
 ---
 
 ### Step 7: Create or Enhance General Setup Templates
@@ -302,6 +323,7 @@ The update should explain briefly:
 - Which skills should be used for common work in the project (the `## Skill Map` added in Step 8D)
 - Whether CodeGraph is initialized and how agents should use it for existing-project analysis
 - Which model to switch to per AKILI-SPECS phase (the `## Model Routing` registry added in Step 8C)
+- How to start the local stack: point at the `## Local Environment` contract in `docs/infrastructure.md` (Step 6B) — agents consult it instead of guessing start commands
 
 Preserve the repository's existing `CLAUDE.md` and `AGENTS.md` conventions and extend them.
 
@@ -351,8 +373,8 @@ If the packaged templates are available, prefer copying them as the seed; otherw
 
 **Required content per persona:**
 
-- **`leader.md`** — orchestration sequence, rework loop with 3-attempt ceiling, structured FAIL handoff to the next Implementer spawn, `execution.md` audit-trail format, `tasks.md` status transitions, AKILI commit standard, Pivot Protocol escalation.
-- **`implementer.md`** — strict context alignment to constitution + spec, incremental focus (no scope creep), aesthetics and design-token compliance from `docs/ux-ui/design.md`, verification rigor (must run the task's verification command before reporting), structured completion report.
+- **`leader.md`** — orchestration sequence, rework loop with 3-attempt ceiling, structured FAIL handoff to the next Implementer spawn, `execution.md` audit-trail format, `tasks.md` status transitions, AKILI commit standard, Pivot Protocol escalation, the **Delegation Thresholds** floor *and* the **Delegation Ceiling** (one subagent beats several for one task; commit to the delegation; brief precisely once; bounded fan-out; never delegate your own verification — with the explicit carve-out that the independent Reviewer is `author ≠ auditor`, not self-verification, and must never be collapsed).
+- **`implementer.md`** — strict context alignment to constitution + spec, **scope discipline in both directions** (no scope creep, but also no silent narrowing — finish the whole task and report completion only when it is actually complete, listing what is missing and why when it is not), aesthetics and design-token compliance from `docs/ux-ui/design.md`, verification rigor (must run the task's verification command before reporting), structured completion report with an optional `Not Done / Assumptions` field.
 - **`reviewer.md`** — read-only role, audit checklist (requirement conformance, design-token compliance, technical compliance, stability), structured PASS/FAIL output where every FAIL item lists *Discovered Issue*, *Violated Rule*, and *Remediation Suggestion*.
 - **`tester.md`** — single-suite scope (backend unit, frontend unit, integration, or E2E), thin per-suite context, explicit coverage of negative constraints (`BUT it must NOT`) and strict validations (`AND IT MUST`), bounded self-correction inner loop (max 3), distinction between a test defect (fix the test) and a product defect (keep the test red, report `PRODUCT_BUG`), and structured `PASS`/`FAIL`/`PRODUCT_BUG` output with a per-scenario coverage slice. Author ≠ tester: prefer a different model than the Implementer.
 
@@ -409,9 +431,15 @@ project guides so the project does not depend on the package's `docs/` after ins
    table (trivial/mechanical → `low`; standard scope → `medium`; complex — algorithm, concurrency,
    security, ambiguity → `xhigh`; correctness-critical → `max`); (b) default effort by role (T1
    propose/specify/Leader `high`; T2 Implementer/Tester `medium`, flex by task; T3 Reviewer `high`;
-   T5 archive `low`); (c) the rework rule (*bump effort one level on every retry*); and (d) the
-   tier↔effort rule (*never `max` a cheaper tier — escalate the tier instead*). The
-   `/akili-execute` and `/akili-test` Leaders read this subsection to set each worker's effort.
+   T5 archive `low`); (c) the rework rule (*bump effort one level on every retry*); (d) the
+   tier↔effort rule (*never `max` a cheaper tier — escalate the tier instead*); (e) the
+   **re-baseline rule** (*effort defaults are per-generation and must be swept — `medium`/`high`/`xhigh`
+   on a real spec — whenever the underlying model generation changes; the tier mapping survives model
+   churn, these defaults do not, and a task that arrives under-specified — a `[~]` resume or a
+   post-Pivot retry — starts one level higher*); and (f) **effort is not a verbosity dial** (*lowering
+   effort does not reliably shorten output — fix long reports in the brief via `caveman` /
+   `cognitive-doc-design`, never by dropping effort*). The `/akili-execute` and `/akili-test` Leaders
+   read this subsection to set each worker's effort.
 
 **Mode-specific policy (mirror Step 8B):**
 
@@ -426,7 +454,12 @@ project guides so the project does not depend on the package's `docs/` after ins
   the user decides whether to refresh them.
 
 Confirm the user's available models before writing concrete identifiers: which tier they run in
-Claude Code (and their plan's rate limits) and which models their OpenCode roster exposes.
+Claude Code (and their plan's rate limits) and which models their OpenCode roster exposes. Note that
+**rate limits are per-generation, not per-family** — a new top-tier generation draws on its own quota
+rather than inheriting the previous one's pool, so moving T1/T3 onto it neither frees nor inherits
+headroom. If the user carries a **frontier escalation pin** (Step 8C item 4), flag it for
+re-justification whenever the `opus` alias advances a generation: each generation narrows the gap the
+pin was bought to close, so try the alias at `xhigh`/`max` before renewing the pin.
 
 ---
 

package/.claude/commands/akili-execute.md

@@ -59,6 +59,8 @@ The Leader does not write production code itself unless the rework loop is exhau
 
 **Delegation Thresholds:** the Leader's inline-vs-delegate boundary is quantified in `.agents/leader.md` → *Delegation Thresholds* (inline only for 1-file checks and puntual verifications; 4+ full-file reads → scout subagent; 2+ non-trivial file writes → Implementer; CodeGraph lookups don't count toward the read threshold). Apply it to your own research inside this command — e.g. investigating a Reviewer FAIL across many files is scout work, not Leader-inline work.
 
+**Delegation Ceiling:** that table is the floor; `.agents/leader.md` → *Delegation Ceiling* is the cap, and on current-generation models it is the one that binds. One subagent beats several for a single task, parallelism is bounded by the count of genuinely independent tasks in `tasks.md`, you commit to a delegation rather than re-deriving its result, and you never spawn a subagent to verify your own work. **The Implementer → Reviewer gate is exempt** — it is `author ≠ auditor` independence, not self-verification, and is never collapsed for efficiency.
+
 **Communication economy:** load the `caveman` skill and apply its Scope Contract to all transient output in this command — inter-agent messages (Leader ↔ Implementer/Reviewer briefs, reports, feedback relays) at `full`, user-visible progress lines at `lite`. It never applies to `execution.md` audit entries, PR descriptions, HITL summaries, Pivot blockers, or verbatim evidence (Reviewer FAIL reports pass unchanged — the Structured Feedback rule wins).
 
 ---
@@ -133,6 +135,7 @@ loop:
 - Re-read the requirements and scenarios covered by the task.
 - Identify the smallest safe change that satisfies the task.
 - Identify the verification command listed in the task.
+- **Environment-dependent verification:** if the verification needs a running stack (integration behavior, manual smoke, anything hitting the database or a live server), consult the `## Local Environment` contract in `docs/infrastructure.md` and run its **pre-check** now — before spawning the Implementer. If the primary route is unavailable (e.g. the Docker daemon is off), ask the user whether to start it or proceed via the contract's fallback route; pass the resolved start/health-check commands in the Implementer's brief. If no contract exists, note the gap and recommend `/akili-constitution` (Step 6B) after the run.
 
 #### 2.2 — Spawn Implementer
 

package/.claude/commands/akili-test.md

@@ -100,6 +100,7 @@ The Leader decides the count from the spec's depth and the independence of the s
 
 1. Partition the work into concrete **suites**: backend unit, frontend unit, integration, E2E — only those the spec actually needs.
 2. For each suite, assemble a **context slice**: the target requirements + scenarios, the negative/strict rules to assert, the repo test command, and the relevant skills.
+   - **Integration/E2E suites additionally get the `## Local Environment` contract** from `docs/infrastructure.md` (start, seed/reset, health-check commands and URLs) so Testers never guess how to bring the stack up. Run the contract's **pre-check at planning time** — if the primary route is unavailable (e.g. Docker daemon off), resolve it with the user (start it, or use the fallback route) before spawning suites, not mid-suite. If no contract exists, note the gap in the test report and recommend `/akili-constitution` (Step 6B).
 3. Apply the **Deployment Rule** to decide inline vs delegated, and parallel vs sequential.
 4. **Select each suite's skills as Leader — you own the decision, not a fixed list.** The spec's task skills and the project's `## Skill Map` (root `AGENTS.md`/`CLAUDE.md`) are your **defaults, not a pass-through**: judge each suite's actual nature and augment, narrow, or override them (conditional skills like `systematic-debugging` for failure-heavy suites or `ui-ux-pro-max` for UI-heavy E2E; stack skills come from the Skill Map). When you deviate from the spec's list, record a one-line reason in the test report's Summary.
 5. **Set each suite's effort** (the *Effort dial* in `## Model Routing`, orthogonal to the tier): default `medium` for a T2 Tester, `low` for a trivial single-assertion suite, `xhigh` for complex integration/concurrency suites, `max` for correctness-critical coverage. Where the tool exposes a per-spawn effort knob, set it; otherwise steer depth in the suite's context slice. Never `max` a cheaper tier — escalate the tier instead.

package/.claude/commands/akili-validate.md

@@ -87,6 +87,8 @@ Prefer the commands defined by the repo rather than assuming a fixed stack.
 
 If no command exists, record the gap and recommend the smallest useful command to add.
 
+**Environment boot smoke (optional):** when `docs/infrastructure.md` has a `## Local Environment` contract and the spec's behavior warrants it, boot the stack per the contract (pre-check first; fallback route if the primary is unavailable) and confirm the health check passes. Record boot failure as **FAIL**, a missing contract as a **WARN** gap recommending `/akili-constitution` (Step 6B).
+
 ### Phase 4: Requirement Coverage Verification
 
 For every requirement in `requirements.md`, verify:

package/.claude/templates/implementer.md

@@ -16,9 +16,11 @@ Your sole responsibility is to implement the technical scope of the active task
     *   **Effort:** Honor the Leader's effort/depth instruction for this task (the *Effort dial* in `## Model Routing`) — think as hard as the brief asks: quick and mechanical for trivial work, deep and careful when the brief flags the task as complex or correctness-critical.
     *   Strictly align with requirements defined in `docs/specs/<spec-path>/requirements.md`.
     *   Follow the technical blueprint in `docs/specs/<spec-path>/design.md`.
-2.  **Incremental Focus (No Scope Creep):**
-    *   Implement **only** the specific, active task detailed by the Leader.
-    *   Do **not** perform broad code refactoring, structural redesigns, or introduce features outside the task's scope unless explicitly directed.
+2.  **Scope Discipline (Both Directions):**
+    *   **Don't widen.** Implement **only** the specific, active task detailed by the Leader. Do **not** perform broad code refactoring, structural redesigns, introduce abstractions, or add features outside the task's scope unless explicitly directed. Don't add error handling or fallbacks for cases that cannot happen.
+    *   **Don't narrow either.** Deliver the task at the scope the spec intended — finish the whole thing, not just the tractable part. Interpret ambiguity the way a careful engineer would: make routine judgment calls yourself and note them; escalate to the Leader only when two readings would produce materially different work.
+    *   **Report completion only when it is actually complete.** Never claim done for partial work. If some part is genuinely blocked, implement everything else and state plainly in your report **what is missing and why** — a truthful partial with a named blocker is useful to the Leader; a premature "done" corrupts `tasks.md` and the audit trail.
+    *   If you conclude the task as specified is wrong or unviable, say so in one or two sentences and **still deliver the task as written** under a stated assumption. Deciding to change the spec is the Leader's call (Pivot Protocol), not yours.
 3.  **Aesthetics & Coding Best Practices:**
     *   Apply premium styling, responsive rules, and rich design tokens defined in `docs/ux-ui/design.md`.
     *   Preserve all existing comments, docstrings, and structures unrelated to your code changes.
@@ -35,6 +37,7 @@ When you finish implementing and verifying your task, provide a concise response
 1.  **Task Completed:** (Brief 1-sentence summary of what you implemented)
 2.  **Verification Command Run:** (e.g. `npm run test` or `vitest run`)
 3.  **Verification Output/Evidence:** (Paste passing test outputs or compile success logs)
+4.  **Not Done / Assumptions:** (**Omit this field entirely when the task is fully complete and nothing was assumed.** Otherwise list what you did not deliver and why, plus any judgment call you made on an ambiguous point. This field is what lets the Leader tell a clean `[x]` from a `[~]` — never bury a gap in the summary above.)
 
 ---
 

package/.claude/templates/leader.md

@@ -16,13 +16,14 @@ Your sole responsibility is to coordinate execution of an approved spec by orche
 
 2. **Task Selection & Parallel Execution:**
    * Parse `tasks.md` and pick the next eligible task(s) by document order where the status is `[ ]` or `[~]` and dependencies are all `[x]`.
-   * **Parallel Execution:** If multiple eligible tasks are completely independent (touching different files or domains), you MAY spawn multiple Implementers in parallel. Otherwise, pick a single task.
+   * **Parallel Execution:** If multiple eligible tasks are completely independent (touching different files or domains), you MAY spawn multiple Implementers in parallel. Otherwise, pick a single task. Parallelism is bounded by how many independent tasks `tasks.md` actually contains — see the **Delegation Ceiling** below; never split one task across several workers.
    * If a task is `[~]`, resume it using `execution.md` context.
    * If no tasks are eligible, report completion or the blocking condition and stop.
 
 3. **Delegation Discipline (Active Skill + Effort Selection):**
    * **You own the skill decision, not the task file.** Judge the task's actual nature and select the optimal skill set for *this* task. The task's recommended skills (e.g., `shadcn-ui`, `nestjs-expert`) and the project's `## Skill Map` (root `AGENTS.md`/`CLAUDE.md`, stack skills) are **defaults you may augment, narrow, or override** — add a skill the task missed, drop one that does not fit, or swap in the better match (UI → `ui-ux-pro-max`, animation → `gsap-animation`, etc.). When you deviate from the task's list, record a one-line reason in `execution.md`. Fall back to the Skill Map only when the task lists none and you see no better fit.
    * **You also set the effort per task** (the second dimension in `## Model Routing` → *Effort dial* — orthogonal to the tier). Default `medium` for a T2 Implementer, then flex by the task's difficulty: `low` for trivial/mechanical work, `xhigh` for complex (algorithm, concurrency, security, ambiguity), `max` for correctness-critical. Where the tool exposes a per-spawn effort knob, pass it; otherwise instruct the Implementer's depth in-brief ("think carefully — this is a hard task" / "keep it quick, this is mechanical"). Don't `max` a cheaper tier — if a task wants `max`, escalate the tier instead.
+   * **The `medium` default assumes a well-specified task.** It holds because `/akili-specify` already did the decomposition. When a task arrives *under*-specified — a `[~]` resume with thin `execution.md` context, or a post-Pivot retry — start it at `high`/`xhigh` instead. And never use effort as a verbosity control: if a report is too long, fix the brief, not the dial (see *Effort dial* → *Effort is not a verbosity dial*).
    * Spawn the **Implementer** subagent with: the active task scope, the relevant spec sections, the verification command, and the contents of `.agents/implementer.md`.
    * **Crucial:** Explicitly instruct the Implementer: "You MUST use the `skill` tool to load these skills: [skill names] BEFORE you begin writing code."
    * After the Implementer reports completion, extract the git diff and spawn the **Reviewer** subagent with: the diff, the relevant spec sections, and the contents of `.agents/reviewer.md`.
@@ -64,6 +65,20 @@ This table is the methodology's single source of truth for when an orchestrating
 
 **CodeGraph exception:** in codegraph-enabled projects, `codegraph_search` / `codegraph_context` / `codegraph_callers` lookups do **not** count toward the 4-file threshold — targeted graph lookups are precisely how the orchestrator avoids bulk file reads. The threshold counts full-file reads.
 
+### 🚧 Delegation Ceiling (when *not* to delegate)
+
+The table above is a **floor** — it says when delegating is mandatory. This is the **ceiling**. Frontier models differ in which direction they err: some under-delegate and need encouragement, others reach for subagents freely and need a cap. Current-generation models are in the second group, so the ceiling is the binding constraint in practice. Every subagent re-establishes context, re-explores, reports back, and then you re-read its report — that overhead is real and it multiplies.
+
+| Rule | Why |
+|------|-----|
+| **One subagent beats several** for a single modest task | Splitting one modest job across parallel workers pays the context-establishment cost N times for one deliverable. Parallelism is for genuinely independent tracks (different files, different domains), never for slicing one task. |
+| **Commit to the delegation** | Once a subagent reports, do **not** redo its work or re-derive its findings to satisfy yourself. If you did not trust it enough to accept the result, the task should not have been delegated. |
+| **Brief precisely the first time** | Launch → wait → re-brief burns a full context cycle. Put the task scope, spec sections, verification command, skills, and effort in the initial spawn. |
+| **Cap the fan-out** | Keep concurrent spawns low and bounded by the number of genuinely independent tasks in `tasks.md`. Never open a wide fan-out the spec does not call for. |
+| **Never delegate your own verification** | Checking a `git status`, confirming a file exists, or re-reading a diff you already have is inline work. Spawning a subagent to double-check yourself is the ceiling's clearest violation. |
+
+**The Reviewer is not self-verification — never collapse it.** The rule directly above bans spawning a subagent to check *your own* reasoning. It does **not** touch the Implementer → Reviewer gate, which exists for a structurally different reason: `author ≠ auditor`. The Reviewer audits **someone else's** diff with fresh context and, where Step 8E wrappers are in place, a **different model**. That independence is the methodology's core correctness guarantee and is not an efficiency cost to optimize away. If you ever find yourself reasoning "I already verified this, the Reviewer is redundant" — that is exactly the bias the Reviewer exists to catch. Spawn it.
+
 ---
 
 ## 🔁 Orchestration Sequence (per task)
@@ -71,7 +86,7 @@ This table is the methodology's single source of truth for when an orchestrating
 1. Load spec and constitution context.
 2. Select next task.
 3. **Spawn Implementer** with `.agents/implementer.md` + task context.
-4. Receive Implementer report (code change + verification evidence).
+4. Receive Implementer report (code change + verification evidence). **If it carries a `Not Done / Assumptions` field, the task is not complete** — carry that text into `execution.md` verbatim, and treat it as scope still owed: either re-spawn for the remainder, or mark `[~]` and escalate. A task with an outstanding gap never reaches `[x]`, even on a Reviewer `PASS`.
 5. Extract `git diff` of the change set.
 6. **Spawn Reviewer** with `.agents/reviewer.md` + diff + spec context.
 7. Branch on Reviewer status:

package/CHANGELOG.md

@@ -10,6 +10,29 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.14.0] - 2026-07-25
+
+### Added
+
+- **Delegation Ceiling — the missing upper bound on orchestrator fan-out.** The `Delegation Thresholds` table added in 2.13.0 is a *floor* (when delegating is mandatory); frontier models increasingly err in the opposite direction, reaching for subagents freely, so the packaged `leader.md` gains a **Delegation Ceiling** section: one subagent beats several for a single modest task (parallelism is for independent tracks, never for slicing one task), **commit to the delegation** (never re-derive a subagent's result), brief precisely on the first spawn (launch → wait → re-brief burns a context cycle), bounded fan-out, and **never delegate your own verification**. The section carries an explicit carve-out: *the Implementer → Reviewer gate is `author ≠ auditor` independence, not self-verification, and is never collapsed for efficiency* — without it, a ceiling rule banning "subagents to double-check yourself" reads as license to drop the Reviewer. Referenced from `/akili-execute` and scaffolded via `/akili-constitution` Step 8B. Leader Instruction #2 now bounds parallelism by the count of genuinely independent tasks in `tasks.md`.
+- **Implementer scope discipline is now bidirectional, with a `Not Done / Assumptions` report field.** Instruction #2 only guarded against scope *creep*; current-generation models also expand scope and can report completion on partial work. It becomes **Scope Discipline (Both Directions)**: don't widen (no unrequested refactors, abstractions, or impossible-case error handling), **don't narrow either** (finish the whole task at the intended scope), **report completion only when actually complete**, and when the task as specified looks wrong, say so in a sentence but still deliver it as written — changing the spec is the Leader's Pivot Protocol call. The completion report gains an optional field 4 (**omitted entirely when the task is clean**) naming what was not delivered and any judgment call made; `leader.md`'s orchestration sequence consumes it — a task carrying an outstanding gap never reaches `[x]`, even on a Reviewer `PASS`.
+- **Model Generation Drift check in `/akili-audit`.** Aliases absorb a new model generation silently, so the registry can be current while everything calibrated around it has gone stale. The new check flags (report-only, as with all drift checks): a **frontier escalation pin** whose recorded reason predates the current `opus` generation; an `Updated:` stamp older than the current generation (effort defaults never swept); and `.agents/*.md` personas missing guardrails the packaged templates have since gained (Delegation Ceiling, bidirectional Scope Discipline).
+
+### Changed
+
+- **Effort dial re-baselined as a per-generation calibration, not a constant.** `docs/model-routing.md` now states the split explicitly: the tier mapping survives model churn, **effort defaults do not**. AKILI's defaults (T2 Implementer `medium`) are calibrated for its shape — tasks arrive *already decomposed and spec-bounded* from `/akili-specify` — whereas vendor guidance for a frontier model is written for one open-ended agentic request with no spec, and therefore starts higher (Claude Opus 5's published starting points are `xhigh` for coding/agentic, `high` elsewhere, then sweep down). The reconciliation is three rules: **sweep don't assume** (run a real spec at `medium`/`high`/`xhigh` on every generation and keep the cheapest level whose Reviewer outcome holds), newer generations get *more* out of the low end so the sweep usually confirms `medium`, and an **under-specified task** (a `[~]` resume with thin `execution.md` context, or a post-Pivot retry) starts one level higher because it resembles the open-ended case. New **Opus specifics** paragraph (start high and iterate *down* — more effort up front reduces total turns on agentic work; the rework bump is the cheapest place to spend effort since it only fires after a failure). Mirrored into the `/akili-constitution` Step 8C scaffold as items (e) and (f).
+- **Effort is not a verbosity dial.** New explicit rule in `docs/model-routing.md` and the Step 8C scaffold: on current-generation models, lowering effort does **not** reliably shorten user-facing output — it changes how much the model *thinks*, not how much it *writes*. Long Implementer reports and Leader narration are fixed in the brief (`caveman` for transient agent output, `cognitive-doc-design` for artifacts), never by dropping effort, which otherwise buys verbose output *and* shallower reasoning. The `tier ↔ effort` illustration is now labelled as generation-specific data supporting a generation-stable rule.
+- **Frontier escalation tier corrected and repositioned.** The section claimed Fable carries *"a refusal classifier Opus does not"* — no longer true: current-generation Opus ships elevated bio/cyber safeguards of its own and can decline a request outright. That claim is removed from the Fable-only constraints list (which keeps no-ZDR, minutes-long turns, and less-prescriptive prompting) and replaced by a methodology-level rule: a declined security-adjacent task is a **Pivot Protocol** case recorded in `execution.md`, **never a Reviewer `FAIL` to be reworked** — rework cannot fix a refusal. The tier is also repositioned as a **decision to re-justify on every generation** rather than a standing configuration, since each Opus generation narrows the gap the pin was bought to close: try the alias at `xhigh`/`max` first.
+- **Rate limits documented as per-generation, not per-family.** `docs/model-routing.md` and the `/akili-constitution` Step 8C model-confirmation step now record that a new top-tier generation draws on its **own** quota rather than inheriting the previous generation's pool, so moving T1/T3 onto it neither frees headroom on the old pool nor inherits it. The "reserve the top tier for T1/T3" rule is unchanged — it is about where the budget earns its cost, not which pool it comes from.
+
+### Notes
+
+- **The model registry itself required zero edits for the Opus 5 release** — the `opus` alias resolved to it automatically and T1/T3 followed, which is the first row of the *Replacing a model* runbook (*do nothing*). This is recorded in `docs/model-routing.md` as a worked example of the alias-first rule, alongside the corollary this release makes explicit: what a new generation *does* invalidate is the per-task effort calibration and the prompt-level guardrails, not the tier mapping.
+## [2.13.1] - 2026-07-24
+
+### Added
+
+- **Local Environment contract — the constitutional baseline now captures how to start the local stack.** `/akili-constitution` Step 6 evolves `docs/infrastructure.md` from a deployment-only blueprint into an environments blueprint (laptop → PROD): new **Step 6B** scaffolds a `## Local Environment` section as a **contract, not a tool** — Docker Compose as the recommended primary route plus a mandatory no-Docker fallback, a pre-check (e.g. `docker info`; on failure offer to start Docker or use the fallback, never block silently), seed/reset commands, health check, and URLs/ports. Legacy projects derive the contract from evidence (compose files, `package.json` scripts); brand-new projects are offered a dev compose scaffold. The section records the **boundary rule**: the local environment is disposable (agents may start/seed/reset it freely) while cloud/PROD deployments stay governed by the blueprint's components/IaC/CI-CD sections and are never improvised by agents. Consumers: `/akili-execute` Step 2.1 (environment-dependent verification consults the contract and runs the pre-check before spawning the Implementer), `/akili-test` Phase 1 (integration/E2E context slices carry the contract; pre-check resolves at planning time, not mid-suite), `/akili-validate` Phase 3 (optional boot smoke — boot failure FAIL, missing contract WARN), and the Step 8 root guides point agents at the contract. Design recorded in `docs/plans/2026-07-24-local-environment-contract.md`.
 ## [2.13.0] - 2026-07-24
 
 ### Added

package/docs/model-routing.md

@@ -99,6 +99,13 @@ tier (to the deeper reasoner) to preserve independence.
 This is the single editable source of truth. Phases reference **tiers**; only this table names
 models. When models change, edit only this table. *Registry updated: 2026-07.*
 
+> **Worked example — the Opus 5 release required zero edits to this table.** When Anthropic shipped
+> Claude Opus 5, the `opus` alias moved to it on its own; T1/T3 followed automatically. That is the
+> alias-first rule paying off (first row of the *Replacing a model* runbook: **do nothing**). What
+> a new generation *does* require is re-reading the **Effort dial** and the behavioural notes below
+> — the tier mapping survives model churn, but the per-task effort defaults and the prompt-level
+> guardrails do not.
+
 **Alias-first rule: never pin a dated model name where a floating alias exists.** Claude Code's
 `opus` / `sonnet` / `haiku` aliases always resolve to the latest version of each family — when
 Anthropic ships a new generation, an alias-based registry needs **zero edits**. Pin a dated ID only
@@ -131,6 +138,13 @@ unchanged (e.g. when the top family moves from one generation to the next, `opus
 Users on plans that expose a frontier model above Opus (Fable 5 / Mythos 5) can pin it for T1/T3 —
 see **Frontier escalation tier** below.
 
+**Rate limits are per-generation, not per-family.** A new Opus generation draws on its **own**
+quota rather than inheriting the previous generation's pool — Opus 5, for instance, does not share
+the combined Opus 4.x bucket. So moving T1/T3 onto a newer Opus neither frees headroom on the old
+pool nor inherits it: check the new generation's limits before shifting volume onto it. The
+"reserve the top tier for T1/T3" rule holds regardless — it is about *where the budget earns its
+cost*, not about which pool the budget comes from.
+
 **OpenCode Go.** The strongest open models anchor the highest-leverage tiers:
 
 - **GLM-5.2 → T2 Coder.** A-tier open coder (753B, GPQA 91.2), successor to GLM-5.1, purpose-built
@@ -165,6 +179,13 @@ high-volume fan-out): at ~2× Opus pricing (**$10 / $50** per 1M in/out vs `opus
 only earns its cost where token volume is low and the decision gates the whole run — T1 (Architect +
 the execute/test Leader) and T3 (Auditor).
 
+**Each Opus generation raises the bar for escalating.** Opus 5 closed much of the gap on exactly the
+work this tier existed for — deep reasoning, long-horizon agentic runs, and bug-finding — at half
+Fable's price. Treat escalation as a decision to **re-justify on every generation**, not a standing
+configuration: try the current `opus` at `xhigh` or `max` first, and pin the frontier model only if
+a concrete spec demonstrably fails there. A pin inherited from a previous generation is a pin worth
+re-testing.
+
 | Slot | Default (alias) | Frontier escalation pin | Fallback |
 |---|---|---|---|
 | **T1 Architect / Leader** | `opus` | `claude-fable-5` *(pin — record the reason)* | `opus` |
@@ -175,12 +196,18 @@ Two things follow from Fable having **no floating alias**:
 - **It is a dated pin — record the reason** (per the alias-first rule), and it re-inherits the
   concrete-slug maintenance the aliases spare you. `/akili-audit`'s drift check watches it; the
   *Replacing a model* runbook below is how you swap it when a newer frontier model ships.
-- **Always give it a Fallback to `opus`**, because Fable carries operational constraints Opus does
-  not: a **refusal classifier** on bio/cyber that can false-positive on legitimate security-adjacent
-  specs (a Fable Implementer/Reviewer may decline valid work); **no zero-data-retention** (requires
-  30-day retention — unavailable to ZDR projects); **minutes-long turns** (budget HITL gates and
-  progress narration accordingly); and **less prescriptive prompting** (over-prescribed `.agents/*`
-  personas can *reduce* Fable output quality — loosen them when routing a role to Fable).
+- **Always give it a Fallback to `opus`**, because Fable carries operational constraints the Opus
+  alias does not: **no zero-data-retention** (requires 30-day retention — unavailable to ZDR
+  projects); **minutes-long turns** (budget HITL gates and progress narration accordingly); and
+  **less prescriptive prompting** (over-prescribed `.agents/*` personas can *reduce* Fable output
+  quality — loosen them when routing a role to Fable).
+
+**Refusal classifiers are no longer a Fable-only concern.** Current-generation Opus ships elevated
+bio/cyber safeguards of its own and can decline a request outright, so a security-adjacent spec may
+stall the Implementer or Reviewer on **either** tier. Plan for it at the methodology level rather
+than treating it as an escalation-only risk: when a spec is security-adjacent, say so in the task
+brief, and treat a declined task as a **Pivot Protocol** case (record it in `execution.md` and
+escalate to the user) — never as a Reviewer `FAIL` to be reworked, since rework cannot fix a refusal.
 
 **Cross-family author ≠ auditor.** Fable pairs well with a *different-lab* auditor — pin the
 Implementer/Leader on `claude-fable-5` and the Reviewer on a Kimi/DeepSeek OpenCode slug (or
@@ -227,21 +254,53 @@ representative model (GPT-5.6 Sol, Artificial Analysis Intelligence Index):
 | T3 **Reviewer** / `/akili-validate` | `high` (auditor thoroughness) |
 | T5 `/akili-archive` / setup steps | `low` |
 
+**Re-baseline these defaults on every model generation — the tier mapping survives model churn, the
+effort defaults do not.** The table above is calibrated for AKILI's shape: tasks arrive *already
+decomposed and spec-bounded* from `/akili-specify`, which is exactly the case where a mid-range
+effort holds up. Vendor guidance for a frontier model is written for the opposite case — one
+open-ended agentic request with no spec — and therefore starts higher (for Claude Opus 5, the
+published starting points are **`xhigh` for coding and agentic work, `high` elsewhere, then sweep
+down**). Both are right for their context. The reconciliation:
+
+- **Sweep, don't assume.** On a new generation, run the same spec at `medium`, `high`, and `xhigh`
+  and keep the cheapest level whose Reviewer outcome holds. Effort defaults inherited from a
+  previous generation are a guess, not a measurement.
+- **Newer generations get more out of the low end, not less.** Each Opus generation has made
+  `low`/`medium` stronger relative to its own ceiling — so the sweep usually confirms the T2
+  `medium` default rather than pushing it up. Raise the Implementer to `xhigh` for the task
+  signals in the policy table above, not by default.
+- **Where a task arrives under-specified** — a `[~]` resume with thin `execution.md` context, or a
+  Pivot Protocol retry — it is closer to the vendor's open-ended case. Start it at `high`/`xhigh`.
+
+**Effort is not a verbosity dial.** On current-generation models, lowering effort does **not**
+reliably shorten user-facing output — it changes how much the model *thinks*, not how much it
+*writes*. If an Implementer's report or a Leader's narration is too long, fix it in the brief
+(`caveman` for transient agent output, `cognitive-doc-design` for artifacts), never by dropping
+effort — that buys verbose output *and* shallower reasoning. The same applies in reverse: raising
+effort to get a more thorough **document** is the wrong lever; ask for the depth explicitly.
+
 **Escalate effort on rework.** In the `/akili-execute` rework loop, a Reviewer `FAIL` bumps effort
 one level on the retry (attempt 1 `medium` → attempt 2 `high` → attempt 3 `xhigh`) — cheap (only
 when it already failed) and it targets the usual cause (under-thinking, not missing instructions).
 
 **Tier ↔ effort interaction — don't `max` a cheaper tier.** Maxing a lower tier erodes its cost
-advantage: Sonnet 5 at `max` (53 intel / $1.53) approaches Opus 4.8 at `max` (56 intel / $1.80) —
-near-Opus price for below-Opus intelligence. If you find yourself wanting a cheaper tier at `max`,
-escalate the **tier** (to `opus` at `high`/`medium`) instead of the effort.
+advantage: on the 4.8-generation ladder, Sonnet 5 at `max` (53 intel / $1.53) approached Opus 4.8 at
+`max` (56 intel / $1.80) — near-Opus price for below-Opus intelligence. Those figures are a
+generation-specific illustration, but the rule they demonstrate is stable across generations: if you
+find yourself wanting a cheaper tier at `max`, escalate the **tier** (to `opus` at `high`/`medium`)
+instead of the effort.
 
 **Sonnet specifics.** Sonnet respects effort strictly, especially at the low end — at `low`/`medium`
 it scopes work to exactly what was asked. If you see shallow reasoning on a hard problem, **raise
 the effort, don't prompt around it**. `high` is the default sweet spot; give `max_tokens` headroom
 at `xhigh`/`max` (thinking consumes the budget — too tight truncates with `stop_reason: max_tokens`).
-On Opus/frontier the nuance inverts slightly: start at `high` and iterate — more effort up front
-often *reduces* total turns and cost on agentic work.
+
+**Opus specifics.** On Opus the nuance inverts: start high and iterate **down** — more effort up
+front often *reduces* total turns and total cost on agentic work, because the model plans better and
+re-does less. Two consequences for the AKILI loop: (1) the **rework bump** (above) is the cheapest
+place to spend effort, since it only fires after a failure; and (2) `max` is for the
+correctness-critical and latency-insensitive case only — it can overthink a routine task and is
+where diminishing returns bite hardest.
 
 ## Enforced routing (tool-native agent bindings)
 

package/docs/plans/2026-07-24-local-environment-contract.md

@@ -0,0 +1,53 @@
+# Proposal: Local Environment Contract
+
+**Status:** Implemented (2026-07-24) — see `CHANGELOG.md` → Unreleased
+**Date:** 2026-07-24
+**Author:** Leader session
+
+Add a **Local Environment contract** to the constitutional baseline: a tool-agnostic section in `docs/infrastructure.md` that captures how to start the project's local stack (database, backend, frontend) — with Docker Compose as the recommended primary route and a documented no-Docker fallback. Agents (Implementer, Tester, validators) consume the contract instead of guessing start commands from `package.json`.
+
+## Decision summary
+
+| # | Decision | Rationale |
+|---|----------|-----------|
+| 1 | The methodology defines a **contract, not a tool** | Docker Compose is the recommended primary route, but not every user has Docker (or has it running); the contract always documents a fallback |
+| 2 | Lives in `docs/infrastructure.md` as `## Local Environment` | The doc evolves from "deployment blueprint" to "environments blueprint — laptop to PROD"; one home, no new file |
+| 3 | Pre-check before use, never block | `docker info` fails (daemon off / not installed) → tell the user and offer: start Docker, or use the fallback route |
+| 4 | Local is disposable; cloud is governed | Agents may freely start/reset the local environment; deployments to cloud/PROD follow the existing infrastructure blueprint (TRD tier → components → ADR) and are **never improvised by agents** |
+| 5 | No `/akili-deploy` automation for now | Deploys are high-risk; the governed blueprint + checklist yields more than premature automation |
+
+## The contract (scaffolded shape)
+
+| Element | Example |
+|---------|---------|
+| Primary route (recommended) | `docker compose up -d` |
+| Fallback route (no Docker) | `npm run dev` + local Postgres or a cloud dev database |
+| Pre-check | `docker info` — on failure, surface it and use/offer the fallback |
+| Seed / reset data | explicit commands |
+| Health check | how to know the stack is up |
+| URLs / ports | frontend, backend, database |
+
+## Where it lands
+
+| Surface | Change |
+|---------|--------|
+| `/akili-constitution` Step 6 | Scaffold `## Local Environment` into `docs/infrastructure.md`; legacy mode derives it from evidence (existing compose files, `package.json` scripts); brand-new mode offers to scaffold a dev compose file; states the local-vs-cloud boundary rule |
+| `/akili-constitution` Step 8 | Root guides briefly point agents at the contract |
+| `/akili-execute` Step 2.1 | Tasks whose verification needs a running environment consult the contract + run the pre-check before spawning the Implementer |
+| `/akili-test` Phase 1 | Integration/E2E suites get the contract in their context slice; pre-check happens at planning, not mid-suite |
+| `/akili-validate` Phase 3 | Build Integrity may include an environment boot smoke per the contract |
+
+## Out of scope
+
+- No changes to the cloud/PROD sections of `docs/infrastructure.md` (Step 6 structure items 1–5 unchanged).
+- No `/akili-deploy` command.
+- No requirement that projects adopt Docker — the contract is satisfied by any documented primary + fallback pair.
+
+## Implementation checklist
+
+- [x] `/akili-constitution` Step 6: `## Local Environment` scaffold + legacy derivation + dev-compose offer + boundary rule.
+- [x] `/akili-constitution` Step 8: root-guide reference to the contract.
+- [x] `/akili-execute` Step 2.1: consult contract + pre-check for environment-dependent verification.
+- [x] `/akili-test` Phase 1: contract in integration/E2E context slices.
+- [x] `/akili-validate` Phase 3: optional boot smoke.
+- [x] `CHANGELOG.md` → Unreleased.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akili-specs",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Portable AKILI-SPECS methodology commands and skills for AI-assisted development.",
   "homepage": "https://github.com/JuankCadavid/akili-specs#readme",
   "repository": {