akili-specs 2.8.0 → 2.9.0

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

@@ -56,6 +56,8 @@ docs/specs/archive/2026-05-16-bugfix--login-redirect/
 
 ### Step 0: Load Context
 
+**Model checkpoint:** This phase runs best on **T5 Fast-Cheap** (summarization and bookkeeping). If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"This phase is T5 — the registry recommends `/model haiku`; you are on opus"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Confirm `docs/specs/$ARGUMENTS/` exists.

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

@@ -19,6 +19,8 @@ Detect and report drift between the project's specifications (PRD, UX/UI Design,
 
 ### Step 0: Read Project Specifications
 
+**Model checkpoint:** This phase runs best on **T4 Context-Ingest** for the scan and **T3 Auditor** for judging drift. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"This phase is T4+T3 — the registry recommends `/model sonnet`; you are on haiku"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+
 First, read the constitutional documentation baseline in the repository:
 
 1. `docs/prd.md`
@@ -44,6 +46,7 @@ Audit for discrepancies, classifying findings under the following categories:
 * **Visual/Design Token Mismatch:** Colors, typography, spacing, or component structures used in the codebase that violate the styling tokens and design principles declared in `docs/ux-ui/design.md`.
 * **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.
 
 ### Step 3: Write Drift Report
 
@@ -87,6 +90,7 @@ A brief overview of the codebase alignment state and major areas of specificatio
 | UX/UI Design / Screen Inventory | [Details] | [Aligned / Drifted] | |
 | TRD (APIs/DB) | [Details] | [Aligned / Drifted] | |
 | Agent Guides (root + `## Module Guides` index) | [Details] | [Aligned / Drifted] | |
+| Model Routing (registry + Step 8E wrappers) | [Details] | [Aligned / Drifted] | |
 
 ## Recommended Next Steps
 Specific actions to resolve the discrepancies (e.g., "Run `/akili-constitution` to enhance baseline", "Update `trd.md` with active REST APIs", or "Schedule a task to implement missing validation tests").

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

@@ -19,6 +19,8 @@ Establish or strengthen the project-wide AKILI-SPECS foundation. This command cr
 
 ### Step 0: Determine Project Mode and Foundation Setup
 
+**Model checkpoint:** This phase runs best on **T4 Context-Ingest** for repository ingestion and **T1 Architect** for baseline synthesis (if no project registry exists yet, use the packaged default in `docs/model-routing.md`). If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"Baseline synthesis is T1 — the default registry recommends `/model opus`; you are on haiku"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+
 Before classifying the repository, use the `brainstorming` skill to ask the user if this is a new project/MVP starting from 0, or if it is an existing project with an established structure.
 
 Based on the response, classify the repository into one of three modes. The classification is non-destructive — it controls how aggressively the constitution drafts, scans, or preserves existing material.
@@ -34,7 +36,7 @@ For all three modes:
 3. Ensure `docs/specs/general-setup/` exists.
 4. Ensure root `CLAUDE.md` exists or is enhanced.
 5. Ensure root `AGENTS.md` exists or is enhanced.
-6. Ensure project-level `.agents/` exists with `leader.md`, `implementer.md`, `reviewer.md`, and `tester.md` (see Step 7B).
+6. Ensure project-level `.agents/` exists with `leader.md`, `implementer.md`, `reviewer.md`, and `tester.md` (see Step 8B).
 7. Default behavior is to enhance existing project docs in place instead of creating parallel copies.
 
 The constitutional baseline must cover these files:
@@ -291,7 +293,7 @@ The update should explain briefly:
 - How module specs should be organized under `docs/specs/`
 - 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 7C)
+- Which model to switch to per AKILI-SPECS phase (the `## Model Routing` registry added in Step 8C)
 
 Preserve the repository's existing `CLAUDE.md` and `AGENTS.md` conventions and extend them.
 
@@ -379,21 +381,28 @@ project guides so the project does not depend on the package's `docs/` after ins
    must differ from the Implementer model. `/akili-test` is likewise split into its Leader (T5,
    orchestration) and Tester(s) (T2, test authoring), with a note to prefer a Tester model different
    from the Implementer (author ≠ tester).
-4. The editable model registry table with columns `Tier | Claude Code | OpenCode | Fallback`.
-   Fill the Claude Code column for the user's plan (e.g. PRO: Opus reserved for T1/T3, Sonnet as the
-   T2/T4/T6 workhorse, Haiku for T5). Fill the OpenCode column from the user's confirmed roster; if
-   it is unknown, leave clearly-marked `<CONFIRM SLUG>` placeholders rather than guessing.
-5. The instruction: *"To change models, edit only this registry table. Model selection is guidance
-   only — never add `model:` to command frontmatter."*
+4. The editable model registry table with columns `Tier | Claude Code | OpenCode | Fallback`, plus
+   an `Updated: <YYYY-MM>` stamp. **Alias-first rule:** the Claude Code column uses floating aliases
+   (`opus`, `sonnet`, `haiku`) — they always resolve to the latest generation, so the registry
+   survives model churn with zero edits; pin a dated model ID only when the user deliberately wants
+   to freeze a version, and record why. Fill the OpenCode column from the user's confirmed roster
+   (slugs are concrete — no alias mechanism); if it is unknown, leave clearly-marked
+   `<CONFIRM SLUG>` placeholders rather than guessing.
+5. The instruction: *"To change models, edit only this registry table. Never pin a dated model name
+   where a floating alias exists. Model selection is guidance only in command prompts — never add
+   `model:` to command frontmatter; enforced bindings live only in the Step 8E agent wrappers."*
 
-**Mode-specific policy (mirror Step 7B):**
+**Mode-specific policy (mirror Step 8B):**
 
 - **Brand-new (Seed Setup):** insert the full `## Model Routing` section using the packaged defaults.
 - **Legacy (Discovery Setup):** insert the section and, where detected, annotate the registry with
   the project's actual tooling (e.g. note if the team already standardizes on a specific model).
 - **Active AKILI-SPECS (Safe Update):** **do not overwrite** an existing customized registry. If the section
   is missing, add it; if it exists, only fill gaps (missing tiers, missing author ≠ auditor note)
-  without changing the user's pinned models.
+  without changing the user's pinned models. Additionally, **flag stale entries**: compare the
+  project registry against the packaged default in `docs/model-routing.md` and list (do not edit)
+  entries that name models the tool no longer offers or dated pins that an alias would now cover —
+  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.
@@ -428,6 +437,58 @@ is how they reach the agents.
 
 ---
 
+### Step 8E: Bind Personas to Models (Tool-Native Agent Wrappers)
+
+Offer to generate **tool-native agent definitions** that bind the `.agents/` personas to the models
+in the `## Model Routing` registry (Step 8C). This turns model routing from guidance into
+enforcement for the multi-agent fan-out — where most tokens are spent — and makes
+**author ≠ auditor structural**: the Reviewer wrapper is pinned to a different model than the
+Implementer wrapper in configuration, not by human discipline.
+
+Ask the user first (one question): *"Bind the AKILI personas to models with native agent wrappers,
+so the Implementer/Reviewer/Tester automatically run on their tier's model?"* If declined, skip
+this step — the guidance-only flow keeps working.
+
+**Per tool:**
+
+- **Claude Code:** create project-level `.claude/agents/akili-leader.md`, `akili-implementer.md`,
+  `akili-reviewer.md`, and `akili-tester.md`. Each wrapper is thin:
+
+  ```markdown
+  ---
+  name: akili-implementer
+  description: AKILI Implementer — executes one spec task with strict scope and verification.
+  model: sonnet
+  ---
+  Read `.agents/implementer.md` in the project root and adopt it fully as your persona and
+  operating contract before doing anything else.
+  ```
+
+  Models come from the registry's Claude Code column as **aliases** (default: leader `haiku`,
+  implementer `sonnet`, reviewer `opus`, tester `sonnet`). Never copy the persona body into the
+  wrapper — `.agents/` stays the single source of truth.
+
+- **OpenCode:** create the equivalent project agent definitions (`.opencode/agent/akili-*.md` or
+  the `agent` block of `opencode.json`, matching the user's OpenCode version) with `model:` set to
+  the registry's OpenCode slugs (default: implementer `opencode-go/glm-5.1`, reviewer
+  `opencode-go/deepseek-v4-pro`, leader `opencode-go/deepseek-v4-flash`).
+
+- **Google Antigravity:** no per-agent model binding exists — skip wrapper generation and note in
+  the summary that Antigravity stays on guidance-only routing.
+
+**Rules:**
+
+1. The Reviewer wrapper's model MUST differ from the Implementer wrapper's model. If the registry
+   collapses them, escalate the Reviewer one tier before writing the wrappers.
+2. Wrappers reference `.agents/<role>.md`; they never duplicate persona content. Editing a persona
+   requires no wrapper change; changing a model requires editing only the wrapper (or re-running
+   this step).
+3. **Mode policy:** Brand-new/Legacy — create the wrappers when accepted. Active AKILI-SPECS —
+   never overwrite existing wrapper files; create only missing ones and flag model drift between
+   existing wrappers and the current registry.
+
+---
+
 ### Step 9: Present and Confirm
 
 After drafting or enhancing the documents, generate a short, easy-to-understand summary (summary facil de entender de lo que se hizo) covering:

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

@@ -52,8 +52,8 @@ If `.agents/` is missing, run `/akili-constitution` first to scaffold it. Do not
 
 **Delegation mechanism by tool:**
 
-- **Claude Code / OpenCode:** spawn a focused subagent (or sub-prompt context) seeded with the persona file plus the task/diff context.
-- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent workflow primitive) using prompts read from `.agents/`.
+- **Claude Code / OpenCode:** if the project has tool-native AKILI agent wrappers (scaffolded by `/akili-constitution` Step 8E — e.g. `.claude/agents/akili-implementer.md` / `akili-reviewer.md` with `model:` bindings from the `## Model Routing` registry), **spawn those named agents** so each role runs on its tier's model and author ≠ auditor is enforced by configuration. Otherwise, spawn a focused subagent (or sub-prompt context) seeded with the persona file plus the task/diff context.
+- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent workflow primitive) using prompts read from `.agents/` (no per-agent model binding — guidance-only routing).
 
 The Leader does not write production code itself unless the rework loop is exhausted and the user has explicitly approved a fallback.
 
@@ -63,6 +63,8 @@ The Leader does not write production code itself unless the rework loop is exhau
 
 ### Step 0: Load Context
 
+**Model checkpoint:** This phase runs best on **T5 Fast-Cheap** for you as Leader — the Implementer/Reviewer route through the Step 8E agent wrappers (their own tier models) when present. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"The Leader loop is T5 — the registry recommends `/model haiku`; you are on opus"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Read the project constitutional docs (IN THIS ORDER):

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

@@ -55,6 +55,8 @@ Do not create `requirements.md`, `design.md`, or `tasks.md` in this command unle
 
 ### Step 0: Resolve Path And Load Context
 
+**Model checkpoint:** This phase runs best on **T1 Architect** (deep reasoning). If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"This phase is T1 — the registry recommends `/model opus`; you are on sonnet"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Resolve `$SPEC_PATH` using the path rules above.

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

@@ -60,6 +60,8 @@ State clearly which criterion failed and which command to run instead. Never sil
 
 ### Step 0: Load Minimal Context
 
+**Model checkpoint:** This phase runs best on **T2 Coder** (small direct edit, light verification). If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"This phase is T2 — the registry recommends `/model sonnet`; you are on opus"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+
 Keep context small — this is a trivial change, not a full spec run.
 
 1. Read only what the change needs:

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

@@ -74,6 +74,8 @@ If any prerequisite is missing, stop and report exactly what is missing and how
 
 ### Phase 0: Setup
 
+**Model checkpoint:** This phase runs best on **T3 Auditor** for audit findings and **T5 Fast-Cheap** for setup/formatting. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"The audit phase is T3 — the registry recommends `/model opus`; you are on haiku"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+
 1. Resolve the spec path. If `$ARGUMENTS` is a bare domain, set `SPEC_PATH = seo/<domain>`. Otherwise treat `$ARGUMENTS` as the literal spec path.
 2. Create directory `docs/specs/$SPEC_PATH/` if it does not exist.
 3. Read the constitutional templates and project context as defined in `akili-specify`:

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

@@ -61,6 +61,8 @@ When the spec is a **bug** — the proposal's Document Control says `Type: Bug`,
 
 ### Step 0: Setup
 
+**Model checkpoint:** This phase runs best on **T1 Architect** for requirements/design (re-check at Phase 3: **T5 Fast-Cheap** for the tasks split, **T6 Multimodal** when visual design is in scope). If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"Phases 1–2 are T1 — the registry recommends `/model opus`; you are on haiku"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Create directory `docs/specs/$ARGUMENTS/` if it does not exist.

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

@@ -50,8 +50,8 @@ If `.agents/tester.md` is missing, run `/akili-constitution` first to scaffold i
 
 **Delegation mechanism by tool:**
 
-- **Claude Code / OpenCode:** spawn a focused subagent (or sub-prompt context) seeded with `tester.md` plus the suite's context slice.
-- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent) using the prompt read from `.agents/tester.md`.
+- **Claude Code / OpenCode:** if the project has a tool-native `akili-tester` agent wrapper (scaffolded by `/akili-constitution` Step 8E with a `model:` binding from the `## Model Routing` registry), **spawn that named agent** so each Tester runs on its tier's model — preferring a model different from the Implementer's (author ≠ tester). Otherwise, spawn a focused subagent (or sub-prompt context) seeded with `tester.md` plus the suite's context slice.
+- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent) using the prompt read from `.agents/tester.md` (no per-agent model binding — guidance-only routing).
 
 **Token discipline — thin context per Tester (this is the core saving):**
 
@@ -76,6 +76,8 @@ The Leader decides the count from the spec's depth and the independence of the s
 
 ### Phase 0: Load Context (Leader)
 
+**Model checkpoint:** This phase runs best on **T5 Fast-Cheap** for you as Leader — Testers route through the `akili-tester` wrapper (T2) when present. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"The Leader loop is T5 — the registry recommends `/model haiku`; you are on opus"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Read project-level context (IN THIS ORDER):

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

@@ -49,6 +49,8 @@ Use these result levels consistently:
 
 ### Phase 0: Load Context
 
+**Model checkpoint:** This phase runs best on **T3 Auditor** — and it MUST resolve to a different model than the one that implemented the work (author ≠ auditor). If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"This phase is T3 — the registry recommends `/model opus`; you are on sonnet, which also implemented the spec"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Read constitutional context (IN THIS ORDER):

package/CHANGELOG.md

@@ -10,6 +10,18 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.9.0] - 2026-07-20
+
+### Added
+
+- **Model Routing 2.0 — enforced for subagents, guided for the main loop:**
+  - **Tool-native agent wrappers (`/akili-constitution` Step 8E):** with user approval, the constitution now binds the `.agents/` personas to the Model Routing registry via native agent definitions — `.claude/agents/akili-{leader,implementer,reviewer,tester}.md` in Claude Code (alias-based `model:`) and agent config in OpenCode (provider slugs). `/akili-execute` and `/akili-test` prefer these named agents, so the multi-agent fan-out (where most tokens are spent) routes automatically and **author ≠ auditor becomes structural** — the Reviewer wrapper pins a different model than the Implementer wrapper. Wrappers are thin references to `.agents/`; personas remain the single source of truth. Antigravity stays guidance-only (no per-agent model binding).
+  - **Model checkpoints in every command:** all 10 commands (`propose`, `specify`, `execute`, `test`, `validate`, `archive`, `audit`, `quick`, `seo`, `constitution`) perform a one-line, never-blocking check during setup — if the phase's tier maps to a different model than the current session, the user is told (e.g. "This phase is T1 — the registry recommends `/model opus`") and offered the switch at the first approval pause.
+  - **Model Registry Drift check in `/akili-audit`:** new drift category and Conformance Matrix row — registry entries naming models the tool no longer offers, dated pins where a floating alias exists, missing tiers/author ≠ auditor notes versus the packaged default, and Step 8E wrappers contradicting the registry. Report-only.
+
+### Changed
+
+- **Alias-first model registry (survives model churn):** `docs/model-routing.md` and the Step 8C scaffold now mandate floating aliases (`opus`/`sonnet`/`haiku` in Claude Code — they always resolve to the latest generation, so new model families require zero registry edits); dated model pins require a recorded reason. The default registry was rewritten alias-first with an `Updated:` stamp; OpenCode slugs (no alias mechanism) keep the Fallback column and are covered by the drift check. Safe Update mode now also flags stale registry entries against the packaged default without touching user pins.
 ## [2.8.0] - 2026-07-20
 
 ### Added

package/docs/commands/akili-constitution.md

@@ -63,7 +63,11 @@ The `.agents/` directory is tool-agnostic: pure Markdown + YAML frontmatter, res
 
 ## Model Routing Scaffolding
 
-Step 7C adds or upgrades a `## Model Routing` section in the project's root `AGENTS.md` and `CLAUDE.md`: a capability-tier registry that maps each AKILI-SPECS phase to a model **per tool** (Claude Code and OpenCode). It is guidance only — no `model:` frontmatter is added and the installer is unchanged. The registry enforces **author ≠ auditor** (the Reviewer runs on a different model than the Implementer) and, in Active-AKILI-SPECS mode, is non-destructive: an existing customized registry is preserved and only gaps are filled. See [Model Routing](../model-routing.md) for the tiers and the default registry.
+Step 8C adds or upgrades a `## Model Routing` section in the project's root `AGENTS.md` and `CLAUDE.md`: a capability-tier registry that maps each AKILI-SPECS phase to a model **per tool** (Claude Code and OpenCode), following the **alias-first rule** (floating aliases like `opus`/`sonnet`/`haiku` wherever they exist, so the registry survives model generations without edits). No `model:` frontmatter is added to commands and the installer is unchanged. The registry enforces **author ≠ auditor** (the Reviewer runs on a different model than the Implementer) and, in Active-AKILI-SPECS mode, is non-destructive: an existing customized registry is preserved, gaps are filled, and stale entries are flagged against the packaged default without touching user pins. See [Model Routing](../model-routing.md) for the tiers and the default registry.
+
+## Model Binding Scaffolding (Tool-Native Agent Wrappers)
+
+Step 8E (with the user's approval) binds the `.agents/` personas to the registry's models via **tool-native agent definitions**: `.claude/agents/akili-{leader,implementer,reviewer,tester}.md` in Claude Code (alias-based `model:` frontmatter) and the equivalent agent config in OpenCode (provider slugs). The wrappers are thin — they reference the `.agents/` persona instead of duplicating it — and make model routing **enforced** for the `/akili-execute` and `/akili-test` fan-out, including a structural author ≠ auditor guarantee (the Reviewer wrapper pins a different model than the Implementer wrapper). Antigravity has no per-agent model binding and stays guidance-only. In Active-AKILI-SPECS mode existing wrappers are never overwritten.
 
 ## Skill Map Scaffolding
 

package/docs/flow.md

@@ -303,11 +303,25 @@ T4 Context-Ingest, T5 Fast-Cheap, T6 Multimodal** — map to the phases:
 | `/akili-audit` | T4 + T3 |
 | `/akili-archive` | T5 |
 
-A single editable registry binds each tier to a concrete model **per tool** (Claude Code and
-OpenCode). `/akili-constitution` (Step 7C) scaffolds a `## Model Routing` copy of that registry into
-the project's `AGENTS.md` / `CLAUDE.md`. It is **guidance only** — no `model:` frontmatter, no
-installer changes — and it enforces **author ≠ auditor** (Reviewer model ≠ Implementer model). See
-[model-routing.md](model-routing.md) for the tiers, principles, and the default registry.
+A single editable registry binds each tier to a model **per tool** (Claude Code and OpenCode),
+using **floating aliases** (`opus`/`sonnet`/`haiku`) wherever they exist so the registry survives
+model generations without edits. `/akili-constitution` (Step 8C) scaffolds a `## Model Routing`
+copy into the project's `AGENTS.md` / `CLAUDE.md`.
+
+Routing operates at two levels:
+
+* **Enforced (subagents):** `/akili-constitution` Step 8E can generate tool-native agent wrappers
+  (`.claude/agents/akili-{leader,implementer,reviewer,tester}.md` in Claude Code, agent config in
+  OpenCode) that pin each persona to its tier's model. `/akili-execute` and `/akili-test` prefer
+  those named agents — so **author ≠ auditor** (Reviewer model ≠ Implementer model) holds by
+  configuration on the fan-out where most tokens are spent.
+* **Guided (main loop):** every command emits a one-line, never-blocking **model checkpoint** in
+  its setup step when the phase's tier maps to a different model than the current session.
+
+No `model:` frontmatter on commands and no installer changes. `/akili-audit` reports **Model
+Registry Drift** (stale model names, dated pins where an alias exists, wrappers contradicting the
+registry). See [model-routing.md](model-routing.md) for the tiers, principles, and the default
+registry.
 
 ### 8. The Kaizen Loop
 

package/docs/model-routing.md

@@ -4,8 +4,17 @@ AKILI is model-agnostic: no command, skill, or persona hardcodes a model. This d
 **human-facing guidance** for choosing which model runs which AKILI-SPECS phase, so each phase runs on a
 model matched to its dominant computational demand rather than one model doing everything.
 
-It is **guidance-first**: you switch models yourself per tool (Claude Code `/model`, OpenCode
-model selector). Nothing here is injected into command frontmatter or the installer — see
+Routing operates at two levels:
+
+- **Enforced (subagents):** `/akili-constitution` Step 8E can bind the Implementer / Reviewer /
+  Tester / Leader personas to models via **tool-native agent definitions** (see
+  [Enforced routing](#enforced-routing-tool-native-agent-bindings)). This is where most tokens are
+  spent and where author ≠ auditor becomes structural instead of aspirational.
+- **Guided (main loop):** the session model can only be switched by you (Claude Code `/model`,
+  OpenCode model selector). Commands emit a one-line **model checkpoint** when the phase's tier
+  points to a different model than the current session, so the switch happens at the right moment.
+
+Nothing here is injected into command frontmatter or the installer — see
 [Cross-Tool Safety](#cross-tool-safety).
 
 ## Philosophy: criteria first, model second
@@ -75,25 +84,35 @@ tier (to the deeper reasoner) to preserve independence.
 ## Model registry
 
 This is the single editable source of truth. Phases reference **tiers**; only this table names
-concrete models. When models change, edit only this table.
+models. When models change, edit only this table. *Registry updated: 2026-07.*
 
-| Tier | Claude Code (PRO) | OpenCode Go | Fallback |
+**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
+when you deliberately need to freeze a version, and record why next to the pin. OpenCode slugs are
+concrete (no alias mechanism), which is why they carry the Fallback column and the drift check
+below.
+
+| Tier | Claude Code | OpenCode Go | Fallback |
 |---|---|---|---|
-| **T1 Architect** | Opus 4.8 | `opencode-go/kimi-k2.6` | `opencode-go/deepseek-v4-pro` / Sonnet 4.6 |
-| **T2 Coder** | Sonnet 4.6 | `opencode-go/glm-5.1` | Haiku 4.5 / `opencode-go/qwen3.7-max` |
-| **T3 Auditor** | Opus 4.8 *(must differ from T2)* | `opencode-go/deepseek-v4-pro` | Sonnet 4.6 / `opencode-go/kimi-k2.6` |
-| **T4 Context-Ingest** | Sonnet 4.6 (1M context) | `opencode-go/deepseek-v4-flash` | Opus 4.8 / `opencode-go/deepseek-v4-pro` |
-| **T5 Fast-Cheap** | Haiku 4.5 | `opencode-go/deepseek-v4-flash` | Sonnet 4.6 / `opencode-go/mimo-v2.5` |
-| **T6 Multimodal** | Sonnet 4.6 (vision) | `opencode-go/qwen3.7-max` *(weak — prefer Claude/Gemini)* | Opus 4.8 |
+| **T1 Architect** | `opus` *(alias — always latest)* | `opencode-go/kimi-k2.6` | `opencode-go/deepseek-v4-pro` / `sonnet` |
+| **T2 Coder** | `sonnet` | `opencode-go/glm-5.1` | `haiku` / `opencode-go/qwen3.7-max` |
+| **T3 Auditor** | `opus` *(must differ from T2)* | `opencode-go/deepseek-v4-pro` | `sonnet` / `opencode-go/kimi-k2.6` |
+| **T4 Context-Ingest** | `sonnet` (long context) | `opencode-go/deepseek-v4-flash` | `opus` / `opencode-go/deepseek-v4-pro` |
+| **T5 Fast-Cheap** | `haiku` | `opencode-go/deepseek-v4-flash` | `sonnet` / `opencode-go/mimo-v2.5` |
+| **T6 Multimodal** | `sonnet` (vision) | `opencode-go/qwen3.7-max` *(weak — prefer Claude/Gemini)* | `opus` |
 
 ### Why these models
 
-**Claude Code (PRO).** Opus 4.8 carries the tightest PRO rate limits, so it is **reserved for
-T1 (propose, specify reasoning) and T3 (validate, review)** — the two phases that most reward deep
-reasoning. **Sonnet 4.6 is the workhorse** for coding (T2), large-context ingestion via its 1M
-window (T4), and vision (T6). **Haiku 4.5** handles fast/cheap formatting, orchestration, and
-summarization (T5). This concentrates scarce Opus budget on architecture and audit and avoids
-exhausting it during execution-heavy work.
+**Claude Code.** The top-family alias (`opus`) carries the tightest plan rate limits, so it is
+**reserved for T1 (propose, specify reasoning) and T3 (validate, review)** — the two phases that
+most reward deep reasoning. **`sonnet` is the workhorse** for coding (T2), large-context ingestion
+(T4), and vision (T6). **`haiku`** handles fast/cheap formatting, orchestration, and summarization
+(T5). This concentrates the scarce top-tier budget on architecture and audit and avoids exhausting
+it during execution-heavy work. Because these are aliases, the mapping survives model generations
+unchanged (e.g. when the top family moves from one generation to the next, `opus` follows it).
+Users on plans that expose additional tiers (e.g. a Mythos-class model above Opus) can pin it for
+T1/T3 in their project registry.
 
 **OpenCode Go.** The two strongest open models anchor the two highest-leverage tiers:
 
@@ -115,20 +134,69 @@ exhausting it during execution-heavy work.
 All OpenCode Go slugs are taken from the [OpenCode Go model list](https://opencode.ai/docs/go).
 Confirm them against your own OpenCode configuration and adjust if your roster differs.
 
+## Enforced routing (tool-native agent bindings)
+
+The `/akili-execute` and `/akili-test` fan-out (Implementer, Reviewer, Testers) is where most
+tokens are spent — and a generic subagent **inherits the session model**, which silently breaks
+author ≠ auditor when the whole session runs on one model. Both tools support a `model` field on
+**agent definitions** (never on commands), so `/akili-constitution` Step 8E binds the personas
+there:
+
+| Tool | Native agent location | Model value |
+|---|---|---|
+| Claude Code | `.claude/agents/akili-{leader,implementer,reviewer,tester}.md` (project-level) | Alias from the registry (`model: sonnet`, `model: opus`, `model: haiku`) |
+| OpenCode | Project agent config (`.opencode/agent/*.md` or the `agent` block of `opencode.json`, per your OpenCode version) | Provider slug from the registry (`model: opencode-go/glm-5.1`) |
+| Antigravity | Not supported — `invoke_subagent` has no per-agent model binding | Guidance-only fallback |
+
+Each wrapper is thin: frontmatter (`name`, `description`, `model`) plus a body that instructs the
+agent to read and fully adopt the corresponding `.agents/<role>.md` persona. The persona files in
+`.agents/` remain the tool-agnostic source of truth; the wrappers only add the model binding.
+`/akili-execute` and `/akili-test` prefer these named agents when they exist and fall back to
+generic subagents seeded with the persona content when they don't.
+
+**author ≠ auditor becomes structural:** `akili-reviewer` is pinned to a different model than
+`akili-implementer` in the wrapper files themselves — no human discipline required.
+
+## Model checkpoints (main loop)
+
+The session model cannot be switched programmatically, but the agent knows which model it is
+running on. Every AKILI command performs a one-line **model checkpoint** during setup: read the
+project's `## Model Routing` registry, compare the phase's tier to the current session model, and
+if they differ, tell the user in one line (e.g. *"This phase is T1 — the registry recommends
+`/model opus`; you are on haiku"*) and offer the switch in the phase's first HITL pause. The user
+can always continue on the current model; the checkpoint never blocks.
+
+## Surviving model churn
+
+Models change constantly; the design absorbs that at three layers:
+
+1. **Tiers are the stable layer.** Phases map to T1–T6 and never change when models do.
+2. **Aliases are the default.** The Claude column uses floating aliases that track the latest
+   generation automatically (see the alias-first rule above).
+3. **Drift is detected, not discovered.** `/akili-audit` includes a **Model Registry Drift** check
+   (registry entries naming models the tool no longer offers, or a project registry older than the
+   packaged default), and `/akili-constitution` in Safe Update mode flags stale entries against the
+   packaged default without overwriting user pins. Each AKILI release refreshes this document's
+   default registry.
+
 ## How to apply per tool
 
-- **Claude Code (PRO):** switch with `/model` before running a phase — e.g. `/model opus` for
+- **Claude Code:** switch with `/model` before running a phase — e.g. `/model opus` for
   `/akili-propose` and `/akili-validate`, `/model sonnet` for `/akili-execute` and `/akili-test`,
-  `/model haiku` for the tasks split and `/akili-archive`. For the `/akili-execute` triad, run the
-  Implementer on Sonnet and the Reviewer on Opus so author ≠ auditor holds.
-- **OpenCode:** select the `opencode-go/...` model for each phase per the registry. Keep the
-  Reviewer/validator on a different model (`deepseek-v4-pro`) than the Implementer (`glm-5.1`).
+  `/model haiku` for the tasks split and `/akili-archive` — or simply respond to each command's
+  model checkpoint. With Step 8E bindings in place, the execute/test triad routes itself
+  (Implementer on `sonnet`, Reviewer on `opus`).
+- **OpenCode:** select the `opencode-go/...` model for each phase per the registry, or use the
+  Step 8E agent bindings. Keep the Reviewer/validator on a different model (`deepseek-v4-pro`)
+  than the Implementer (`glm-5.1`).
 
 ## Cross-tool safety
 
-- **No `model:` frontmatter.** Command prompts stay `description:`-only. A single frontmatter value
-  cannot serve both tools anyway (Claude Code expects `opus`/`sonnet`/`haiku`; OpenCode expects
-  `provider/model`), so model choice stays out of the prompts.
+- **No `model:` frontmatter on commands.** Command prompts stay `description:`-only. A single
+  frontmatter value cannot serve both tools anyway (Claude Code expects `opus`/`sonnet`/`haiku`;
+  OpenCode expects `provider/model`), so model choice stays out of the prompts. Model bindings live
+  exclusively in **agent definitions**, which are per-tool, per-project files generated with the
+  user's approval in Step 8E.
 - **No installer changes.** Nothing here is force-injected. `/akili-constitution` scaffolds a project
   copy of this registry into `AGENTS.md` / `CLAUDE.md` as plain Markdown — identical handling across
   Claude Code, OpenCode, and Google Antigravity.

package/package.json

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