its-magic 0.1.3-0 → 0.1.3-1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.3-0",
+  "version": "0.1.3-1",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {

package/scripts/check_intake_template_parity.py

@@ -228,6 +228,64 @@ RELEASE_CHANGELOG_PAIRS: tuple[tuple[str, str], ...] = (
     ),
 )
 
+MODEL_TIER_PAIRS: tuple[tuple[str, str], ...] = (
+    (
+        "scripts/model_tier_lib.py",
+        "template/scripts/model_tier_lib.py",
+    ),
+    (
+        "scripts/model_tier_validate.py",
+        "template/scripts/model_tier_validate.py",
+    ),
+    (
+        "docs/engineering/runbook.md",
+        "template/docs/engineering/runbook.md",
+    ),
+    (
+        ".cursor/scratchpad.md",
+        "template/.cursor/scratchpad.md",
+    ),
+    (
+        ".cursor/scratchpad.local.example.md",
+        "template/.cursor/scratchpad.local.example.md",
+    ),
+    (
+        "scripts/check_intake_template_parity.py",
+        "template/scripts/check_intake_template_parity.py",
+    ),
+)
+
+MODEL_TIER_OVERRIDES_PAIRS: tuple[tuple[str, str], ...] = (
+    (
+        ".cursor/scratchpad.md",
+        "template/.cursor/scratchpad.md",
+    ),
+    (
+        ".cursor/scratchpad.local.example.md",
+        "template/.cursor/scratchpad.local.example.md",
+    ),
+    (
+        ".cursor/model-catalog.local.example.role-based-balanced.json",
+        "template/.cursor/model-catalog.local.example.role-based-balanced.json",
+    ),
+    (
+        ".cursor/model-catalog.local.example.role-based-highend.json",
+        "template/.cursor/model-catalog.local.example.role-based-highend.json",
+    ),
+    (
+        "scripts/model_tier_lib.py",
+        "template/scripts/model_tier_lib.py",
+    ),
+    (
+        "scripts/model_tier_validate.py",
+        "template/scripts/model_tier_validate.py",
+    ),
+    (
+        "docs/engineering/runbook.md",
+        "template/docs/engineering/runbook.md",
+    ),
+)
+
 DOWNSTREAM_CI_GUARD_PAIRS: tuple[tuple[str, str], ...] = (
     (
         "scripts/check_downstream_ci_guard.py",
@@ -252,6 +310,8 @@ SCOPES: dict[str, tuple[tuple[str, str], ...]] = {
     "project-readme": PROJECT_README_PAIRS,
     "dev-environment": DEV_ENVIRONMENT_PAIRS,
     "release-changelog": RELEASE_CHANGELOG_PAIRS,
+    "model-tier": MODEL_TIER_PAIRS,
+    "model-tier-overrides": MODEL_TIER_OVERRIDES_PAIRS,
     "all": (
         INTAKE_TEMPLATE_PAIRS
         + CAVEMAN_COMPRESS_PAIRS
@@ -265,6 +325,8 @@ SCOPES: dict[str, tuple[tuple[str, str], ...]] = {
         + PROJECT_README_PAIRS
         + DEV_ENVIRONMENT_PAIRS
         + RELEASE_CHANGELOG_PAIRS
+        + MODEL_TIER_PAIRS
+        + MODEL_TIER_OVERRIDES_PAIRS
     ),
 }
 

package/template/.cursor/agents/curator.mdc

@@ -1,5 +1,6 @@
 ---
 description: "Curator agent"
+model: fast
 ---
 
 You are the Curator. Keep context compact and artifacts current.

package/template/.cursor/agents/po.mdc

@@ -1,5 +1,6 @@
 ---
 description: "Product Owner agent"
+model: inherit
 ---
 
 You are the PO. Your job is to clarify requirements and persist them.

package/template/.cursor/agents/release.mdc

@@ -1,5 +1,6 @@
 ---
 description: "Release agent"
+model: inherit
 ---
 
 You are Release. Prepare release notes and runbook commands.

package/template/.cursor/model-catalog.local.example.cursor-only.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "composer-2.5-fast",
+    "balanced": "composer-2.5-standard",
+    "strong": "composer-2.5"
+  },
+  "notes": "Cursor-integrated models only. Uses Cursor's own Composer 2.5 family via stable Cursor model IDs. No external API key is required; everything routes through Cursor-managed infrastructure. Strong maps to the strongest available Composer 2.5 variant (often the default parent model when model: is omitted)."
+}

package/template/.cursor/model-catalog.local.example.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "<your-cheap-model-slug>",
+    "balanced": "<your-balanced-model-slug>",
+    "strong": "<your-strong-model-slug>"
+  },
+  "notes": "Copy this file to .cursor/model-catalog.local.json and replace placeholder slugs with vendor-specific model IDs. Enable with MODEL_RESOLVE=local_catalog in .cursor/scratchpad.local.md. All three tier keys are required."
+}

package/template/.cursor/model-catalog.local.example.level-1-easy.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "qwen-3.7-plus",
+    "balanced": "composer-2.5-standard",
+    "strong": "glm-4.7"
+  },
+  "notes": "Level 1 — small/simple apps (CRUD, dashboard, bot, single-service). Cost-focused: Qwen3.7 Plus handles routine volume, Composer 2.5 Standard is the Cursor default, GLM-4.7 covers occasional architecture/release gates. Based on ai_modell_auslegung_cursor_highend.md 'Kleine unkomplizierte Apps'. Enable with MODEL_RESOLVE=local_catalog."
+}

package/template/.cursor/model-catalog.local.example.level-2-complex.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "qwen-3.7-plus",
+    "balanced": "composer-2.5-standard",
+    "strong": "glm-5.2"
+  },
+  "notes": "Level 2 — complex apps (multi-service, auth, DB, FE+BE, Docker, API, worker/queue). Balanced: cheap Qwen for mass DEV, Composer 2.5 Standard as Cursor default, strong GLM-5.2 for architecture/QA/release gates. Based on ai_modell_auslegung_cursor_highend.md 'Komplexere Apps'. Enable with MODEL_RESOLVE=local_catalog."
+}

package/template/.cursor/model-catalog.local.example.level-3-mega.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "qwen-3.7-plus",
+    "balanced": "glm-5.2",
+    "strong": "gpt-5.5"
+  },
+  "notes": "Level 3 — mega-complex software / modular monoliths (trading/finance platforms, multi-team systems, long-lived infrastructure). Strong GPT-5.5 for chief-architect/final-gate work, GLM-5.2 for SA/QA/RELEASE, Qwen for volume DEV. Based on ai_modell_auslegung_cursor_highend.md 'Mega-komplexe Software'. Enable with MODEL_RESOLVE=local_catalog."
+}

package/template/.cursor/model-catalog.local.example.level-4-super.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "qwen-3.7-plus",
+    "balanced": "kimi-k2.7-code",
+    "strong": "claude-opus-4.8"
+  },
+  "notes": "Level 4 — super-high-sophisticated / mission-critical (AI operating systems, critical infrastructure, long-horizon agent systems, high-risk security/privacy/finance). Chief-architect quality: Claude Opus 4.8 for critical gates, Kimi K2.7 Code for difficult long-horizon DEV, Qwen for cheap mass work. Based on ai_modell_auslegung_cursor_highend.md 'Super-High-Sophisticated Projects'. Enable with MODEL_RESOLVE=local_catalog."
+}

package/template/.cursor/model-catalog.local.example.role-based-balanced.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": 2,
+  "tiers": {
+    "cheap": "<your-cheap-model-slug>",
+    "balanced": "<your-balanced-model-slug>",
+    "strong": "<your-strong-model-slug>"
+  },
+  "roles": {
+    "po": "<your-po-model-slug>",
+    "sa": "<your-sa-model-slug>",
+    "dev": "<your-dev-model-slug>",
+    "dev_difficult": "<your-dev-difficult-model-slug>",
+    "qa": "<your-qa-model-slug>",
+    "security": "<your-security-model-slug>",
+    "release": "<your-release-model-slug>"
+  },
+  "notes": "Role-based balanced preset (US-0102 / DEC-0087). Copy to .cursor/model-catalog.local.json and set MODEL_RESOLVE=role_catalog in .cursor/scratchpad.local.md. All tier and role keys required when roles section present."
+}

package/template/.cursor/model-catalog.local.example.role-based-highend.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": 2,
+  "tiers": {
+    "cheap": "<your-cheap-highend-slug>",
+    "balanced": "<your-balanced-highend-slug>",
+    "strong": "<your-strong-highend-slug>"
+  },
+  "roles": {
+    "po": "<your-po-highend-slug>",
+    "sa": "<your-sa-highend-slug>",
+    "dev": "<your-dev-highend-slug>",
+    "dev_difficult": "<your-dev-difficult-highend-slug>",
+    "qa": "<your-qa-highend-slug>",
+    "security": "<your-security-highend-slug>",
+    "release": "<your-release-highend-slug>"
+  },
+  "notes": "Role-based high-end preset (US-0102 / DEC-0087). See ai_modell_auslegung_cursor_highend.md for non-normative role recommendations. Enable with MODEL_RESOLVE=role_catalog."
+}

package/template/.cursor/scratchpad.local.example.md

@@ -321,3 +321,58 @@ CAVEMAN_MODE=0
 CAVEMAN_LEVEL=
 CAVEMAN_COMPRESS_INPUT=0
 CAVEMAN_FILE_SCOPE=
+
+#
+# ## Per-phase model tier selection (US-0101 / DEC-0086)
+# MODEL_TIER selects LLM model strength (which model runs).
+# MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE — these are independent axes;
+#   none substitutes for the other (DEC-0062 / US-0080 / US-0096).
+# - MODEL_TIER_DEFAULT: cheap|balanced|strong (default balanced)
+# - MODEL_TIER_<PHASE>: cheap|balanced|strong (per-phase override; PHASE = canonical phase id)
+#   Default matrix (architecture-locked):
+#     cheap    — ask, refresh-context, memory-audit, status-reconcile, pause
+#     balanced — intake, discovery, research, release, plan-verify
+#     strong   — architecture, execute, quick, qa, verify-work, security-review
+#     (inherit parent) — auto (orchestrator always inherits parent model)
+# - MODEL_CATALOG: path to local slug catalog (default .cursor/model-catalog.local.json)
+# - MODEL_RESOLVE: alias_only|local_catalog|role_catalog (default alias_only)
+# - MODEL_FALLBACK: fallback when catalog lookup fails (default inherit)
+# - MODEL_PROVIDER_MODE: cursor|api (default cursor)
+#   cursor = all subagents route through Cursor-managed infrastructure
+#   api = operator uses BYOK via Cursor Settings → Models → API Key
+#   Known limitation: subagents do NOT inherit custom API keys/base URLs.
+#
+# ## Direct per-phase model slug override (US-0102 / DEC-0087) — set in this local file only
+# Precedence: MODEL_<PHASE> > MODEL_TIER_<PHASE> > MODEL_TIER_DEFAULT > Cursor alias
+# - MODEL_<PHASE>: direct vendor slug (e.g. MODEL_EXECUTE=<your-vendor-slug>, MODEL_ASK=<your-vendor-slug>)
+# - MODEL_RESOLVE=role_catalog enables phase→role→catalog slug lookup (requires v2 catalog with roles section)
+MODEL_TIER_DEFAULT=balanced
+MODEL_CATALOG=.cursor/model-catalog.local.json
+MODEL_RESOLVE=alias_only
+MODEL_FALLBACK=inherit
+MODEL_PROVIDER_MODE=cursor
+
+# Per-phase tier overrides for this project (uncomment and adjust as needed):
+#MODEL_TIER_INTAKE=balanced
+#MODEL_TIER_DISCOVERY=cheap
+#MODEL_TIER_RESEARCH=balanced
+#MODEL_TIER_ARCHITECTURE=strong
+#MODEL_TIER_SPRINT-PLAN=strong
+#MODEL_TIER_PLAN-VERIFY=balanced
+#MODEL_TIER_EXECUTE=cheap
+#MODEL_TIER_QA=strong
+#MODEL_TIER_VERIFY-WORK=strong
+#MODEL_TIER_RELEASE=balanced
+#MODEL_TIER_REFRESH-CONTEXT=cheap
+
+# Direct per-phase slug overrides (US-0102 — uncomment and set vendor slugs):
+#MODEL_ASK=<your-vendor-slug>
+#MODEL_EXECUTE=<your-vendor-slug>
+#MODEL_QA=<your-vendor-slug>
+
+# Use a vendor catalog instead of Cursor aliases:
+#   cp .cursor/model-catalog.local.example.level-2-complex.json .cursor/model-catalog.local.json
+#MODEL_RESOLVE=local_catalog
+# Role-based catalog preset (US-0102):
+#   cp .cursor/model-catalog.local.example.role-based-balanced.json .cursor/model-catalog.local.json
+#MODEL_RESOLVE=role_catalog

package/template/.cursor/scratchpad.md

@@ -322,3 +322,65 @@ CAVEMAN_MODE=1
 CAVEMAN_LEVEL=full
 CAVEMAN_COMPRESS_INPUT=0
 CAVEMAN_FILE_SCOPE=
+
+#
+# ## Per-phase model tier selection (US-0101 / DEC-0086)
+# MODEL_TIER selects LLM model strength (which model runs).
+# MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE — these are independent axes;
+#   none substitutes for the other (DEC-0062 / US-0080 / US-0096).
+# - MODEL_TIER_DEFAULT: cheap|balanced|strong (default balanced)
+# - MODEL_TIER_<PHASE>: cheap|balanced|strong (per-phase override; PHASE = canonical phase id)
+#   Examples: MODEL_TIER_EXECUTE=cheap, MODEL_TIER_QA=strong, MODEL_TIER_RESEARCH=balanced
+#   Set in .cursor/scratchpad.local.md to override per phase without touching committed defaults.
+#   Default matrix (architecture-locked):
+#     cheap    — ask, refresh-context, memory-audit, status-reconcile, pause
+#     balanced — intake, discovery, research, release, plan-verify
+#     strong   — architecture, execute, quick, qa, verify-work, security-review
+#     (inherit parent) — auto (orchestrator always inherits parent model)
+# - MODEL_CATALOG: path to local slug catalog (default .cursor/model-catalog.local.json)
+# - MODEL_RESOLVE: alias_only|local_catalog|role_catalog (default alias_only)
+#   alias_only    = use Cursor-stable aliases (cheap->fast, balanced->inherit, strong->omit model:)
+#   local_catalog = look up vendor model slugs from MODEL_CATALOG; requires valid JSON catalog
+#   role_catalog  = opt-in phase→role→catalog slug lookup (US-0102 / DEC-0087); falls through on miss
+# - MODEL_FALLBACK: fallback when catalog lookup fails (default inherit)
+# - MODEL_PROVIDER_MODE: cursor|api (default cursor)
+#   cursor = all subagents route through Cursor-managed infrastructure
+#   api = operator uses BYOK via Cursor Settings → Models → API Key
+#   Known limitation: subagents do NOT inherit custom API keys/base URLs.
+#
+# Example catalogs for 4 software-complexity levels + a Cursor-only variant:
+#   .cursor/model-catalog.local.example.json                           — minimal placeholder template
+#   .cursor/model-catalog.local.example.cursor-only.json             — only Cursor-integrated Composer models
+#   .cursor/model-catalog.local.example.level-1-easy.json            — small/simple apps
+#   .cursor/model-catalog.local.example.level-2-complex.json         — complex multi-service apps
+#   .cursor/model-catalog.local.example.level-3-mega.json            — mega-complex / modular monoliths
+#   .cursor/model-catalog.local.example.level-4-super.json            — super-high-sophisticated / mission-critical
+#   .cursor/model-catalog.local.example.role-based-balanced.json     — v2 role preset (balanced)
+#   .cursor/model-catalog.local.example.role-based-highend.json      — v2 role preset (high-end)
+# Copy one to .cursor/model-catalog.local.json and set MODEL_RESOLVE=local_catalog or role_catalog to activate.
+MODEL_TIER_DEFAULT=balanced
+MODEL_CATALOG=.cursor/model-catalog.local.json
+MODEL_RESOLVE=alias_only
+MODEL_FALLBACK=inherit
+MODEL_PROVIDER_MODE=cursor
+#
+# ## Direct per-phase model slug override + role catalog (US-0102 / DEC-0087)
+# Composes on US-0101 / DEC-0086 — tier baseline unchanged; overlays are optional.
+# Precedence chain (deterministic, per canonical phase_id):
+#   1. MODEL_<PHASE>           — direct vendor slug override (highest priority)
+#   2. MODEL_TIER_<PHASE>      — DEC-0086 tier→alias / local_catalog chain
+#   3. role_catalog lookup     — only when MODEL_RESOLVE=role_catalog; miss falls through
+#   4. MODEL_TIER_DEFAULT      — DEC-0086 tier chain
+#   5. Cursor stable alias     — DEC-0086 built-in mapping (fast / inherit / omit)
+# Scratchpad merge precedence for all MODEL_* keys: MODEL_<PHASE> > MODEL_TIER_<PHASE> > MODEL_TIER_DEFAULT
+# - MODEL_<PHASE>: direct vendor slug; <PHASE> = canonical phase id (same list as MODEL_TIER_<PHASE>)
+#   Set in .cursor/scratchpad.local.md only — use <your-vendor-slug> placeholders in committed files.
+#   Canonical phase ids: ask, refresh-context, memory-audit, status-reconcile, pause,
+#     intake, discovery, research, release, plan-verify, architecture, execute, quick,
+#     qa, verify-work, security-review, auto
+#   Examples (placeholders — replace in scratchpad.local.md):
+#     MODEL_ASK=<your-vendor-slug>
+#     MODEL_EXECUTE=<your-vendor-slug>
+#     MODEL_QA=<your-vendor-slug>
+#     MODEL_REFRESH-CONTEXT=<your-vendor-slug>
+#   MODEL_ASK participates in step 1 like any other phase (no special-case bypass).

package/template/docs/engineering/runbook.md

@@ -650,6 +650,203 @@ When **`AUTO_DELIVERY_ROUTING=backlog_then_scratchpad`**, story row may declare
 
 **Release status (S0086 / US-0096)**: **`released`** (`2026-06-13T16:00:00Z`); **`US-0096`** **DONE** in canonical backlog. Operator verify: **`handoffs/releases/S0086-release-notes.md`** **## Verify**; publish skipped while **`RELEASE_PUBLISH_MODE=confirm`**.
 
+## Per-phase model tier selection (US-0101 / DEC-0086)
+
+`MODEL_TIER` selects LLM model strength (which model runs per lifecycle phase).
+Three operator-facing tiers map to stable Cursor aliases — no vendor slugs in
+template files.
+
+| Key | Values | Default | Role |
+|-----|--------|---------|------|
+| **`MODEL_TIER_DEFAULT`** | `cheap` \| `balanced` \| `strong` | `balanced` | Fallback when phase-specific key absent |
+| **`MODEL_TIER_<PHASE>`** | `cheap` \| `balanced` \| `strong` | *(per matrix)* | Per-phase tier override |
+| **`MODEL_CATALOG`** | path | `.cursor/model-catalog.local.json` | Path to local slug catalog |
+| **`MODEL_RESOLVE`** | `alias_only` \| `local_catalog` | `alias_only` | Resolution strategy |
+| **`MODEL_FALLBACK`** | `inherit` | `inherit` | Fallback when catalog lookup fails |
+| **`MODEL_PROVIDER_MODE`** | `cursor` \| `api` | `cursor` | Provider routing |
+
+### Default phase→tier matrix (architecture-locked)
+
+| Tier | Cursor alias | `model:` field | Phases |
+|------|-------------|----------------|--------|
+| **`cheap`** | `fast` | `model: fast` | `ask`, `refresh-context`, `memory-audit`, `status-reconcile`, `pause` |
+| **`balanced`** | `inherit` | `model: inherit` | `intake`, `discovery`, `research`, `release`, `plan-verify` |
+| **`strong`** | *(omit)* | no `model:` field | `architecture`, `execute`, `quick`, `qa`, `verify-work`, `security-review` |
+| *(inherit parent)* | — | — | `auto` (orchestrator always inherits parent model) |
+
+### Provider mode (MODEL_PROVIDER_MODE)
+
+| Mode | Description |
+|------|-------------|
+| **`cursor`** (default) | All subagents route through Cursor-managed infrastructure; tier aliases work as designed |
+| **`api`** | Operator uses BYOK via Cursor Settings → Models → API Key |
+
+**Known limitation (confirmed 2026-06)**: Cursor subagents do **NOT** inherit
+custom API keys or base URLs — they always bill against the Cursor plan. When
+`MODEL_PROVIDER_MODE=api`, the local catalog is the only operator-controlled
+surface; subagent `model:` aliases still resolve through Cursor infrastructure.
+
+**Workaround recipes**:
+
+1. **Parent model + `inherit`** — set the parent chat model to the desired BYOK
+   model; subagents using `model: inherit` (balanced tier) pick it up.
+2. **Manual phase runs** — run each phase in a separate chat with the desired
+   model selected at the chat level (no subagent spawn).
+3. **Local catalog override** — set `MODEL_RESOLVE=local_catalog` and populate
+   `.cursor/model-catalog.local.json` with vendor slugs; materializer applies
+   slugs at template materialization time (not at subagent runtime).
+
+### Non-substitution paragraph
+
+MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE
+
+> **`MODEL_TIER`** selects LLM model strength (which model runs).
+> **`TOKEN_PROFILE`** selects context breadth / token cost (how much context the model sees).
+> **`DELIVERY_MODE`** selects lifecycle shape (standard / ultra_lean / mega_quick).
+> These are **independent axes** — none substitutes for another. A `strong` tier
+> with `lean` profile is valid; a `cheap` tier with `full` profile is valid.
+> Setting one does not change the others. Combine freely.
+
+### Reason codes — `MODEL_TIER_*` / `MODEL_CATALOG_*` / `MODEL_RESOLVE_*` / `MODEL_SLUG_*`
+
+| Code | Trigger |
+|------|---------|
+| **`MODEL_TIER_INVALID`** | Unknown tier value (not `cheap`/`balanced`/`strong`) |
+| **`MODEL_CATALOG_INVALID`** | Malformed catalog JSON (parse error, missing `schema_version`) |
+| **`MODEL_SLUG_UNKNOWN`** | Tier key missing from catalog when `MODEL_RESOLVE=local_catalog` |
+| **`MODEL_RESOLVE_FALLBACK`** | Catalog lookup failed but `MODEL_FALLBACK=inherit` → reason + fallback |
+
+### Template agent defaults
+
+| Agent role | Tier | `model:` field |
+|-----------|------|----------------|
+| `curator` | cheap | `model: fast` |
+| `po` | balanced | `model: inherit` |
+| `release` | balanced | `model: inherit` |
+| `tech-lead` | strong | *(omit)* |
+| `dev` | strong | *(omit)* |
+| `qa` | strong | *(omit)* |
+| `security` | strong | *(omit)* |
+
+**Forbidden in `template/.cursor/agents/`**: hardcoded vendor slugs
+(`composer-*`, `claude-*`, `gpt-*`, `opus-*`). Template files use aliases only.
+
+### Local catalog schema (v1)
+
+```json
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "<slug>",
+    "balanced": "<slug>",
+    "strong": "<slug>"
+  },
+  "notes": "optional free-text"
+}
+```
+
+- Path: `.cursor/model-catalog.local.json` (gitignored)
+- Example: `.cursor/model-catalog.local.example.json` (committed, placeholder values)
+- All three tier keys required; values are opaque vendor slug strings
+
+### Resolver algorithm
+
+1. Read `MODEL_TIER_<PHASE>` from merged scratchpad → tier value
+2. If `MODEL_RESOLVE=alias_only` (default): use built-in mapping (table above)
+3. If `MODEL_RESOLVE=local_catalog`: load catalog JSON → lookup tier key → slug
+4. If key missing → `MODEL_SLUG_UNKNOWN` fail-closed
+5. If `MODEL_FALLBACK=inherit` and lookup fails → emit `MODEL_RESOLVE_FALLBACK` + use `inherit`
+6. Unknown tier value → `MODEL_TIER_INVALID` fail-closed
+7. Malformed catalog JSON → `MODEL_CATALOG_INVALID` fail-closed
+
+### Validation commands
+
+- `python scripts/model_tier_validate.py --repo .`
+- `pytest -k us0101 tests/auto_command_contract_test.py`
+- `python scripts/check_intake_template_parity.py --scope=model-tier`
+- `tests/run-tests.ps1` / `tests/run-tests.sh` §26Z
+
+Normative architecture: `docs/engineering/architecture.md` (**# US-0101**).
+
+## Direct per-phase model slug override + role catalog (US-0102 / DEC-0087)
+
+Composes on **US-0101** / **DEC-0086** — tier-only operators need no migration.
+
+### 5-step precedence chain
+
+| Step | Source | Outcome |
+|------|--------|---------|
+| **1** | `MODEL_<PHASE>` | Non-empty slug → return (validate per mode) or `MODEL_OVERRIDE_SLUG_UNKNOWN` |
+| **2** | `MODEL_TIER_<PHASE>` | **DEC-0086** tier→alias / `local_catalog` chain |
+| **3** | `MODEL_RESOLVE=role_catalog` | Phase→logical role → catalog `roles[<key>]`; miss → `MODEL_ROLE_SLUG_UNKNOWN` → fall through |
+| **4** | `MODEL_TIER_DEFAULT` | **DEC-0086** tier chain |
+| **5** | Cursor alias | **DEC-0086** built-in mapping |
+
+When `MODEL_RESOLVE` is `alias_only` or `local_catalog`, step **3** is skipped.
+
+### Scratchpad keys (new)
+
+| Key | Default | Role |
+|-----|---------|------|
+| **`MODEL_<PHASE>`** | *(absent)* | Direct vendor slug; includes `MODEL_ASK` |
+| **`MODEL_RESOLVE`** | `alias_only` | Extended: `alias_only` \| `local_catalog` \| **`role_catalog`** |
+
+Operator slugs live in `.cursor/scratchpad.local.md` and `.cursor/model-catalog.local.json` only (gitignored).
+
+### Role catalog enablement recipe
+
+1. Copy a v2 example catalog:
+   - `.cursor/model-catalog.local.example.role-based-balanced.json`, or
+   - `.cursor/model-catalog.local.example.role-based-highend.json`
+2. Save as `.cursor/model-catalog.local.json` with real vendor slugs.
+3. Set `MODEL_RESOLVE=role_catalog` in `.cursor/scratchpad.local.md`.
+4. Optional: set `MODEL_<PHASE>=<slug>` for direct overrides (step 1 wins over role lookup).
+5. Run `python scripts/model_tier_validate.py --repo .` to validate.
+
+On role lookup miss → `MODEL_ROLE_SLUG_UNKNOWN` emitted; resolver falls through to `MODEL_TIER_DEFAULT` then Cursor alias.
+
+**`dev_difficult`**: no automatic phase routing — use `MODEL_EXECUTE=<slug>` direct override or tier `strong` + catalog tier slug.
+
+Non-normative role recommendations: `ai_modell_auslegung_cursor_highend.md`.
+
+### Catalog schema v2 (opt-in)
+
+```json
+{
+  "schema_version": 2,
+  "tiers": { "cheap": "<slug>", "balanced": "<slug>", "strong": "<slug>" },
+  "roles": {
+    "po": "<slug>", "sa": "<slug>", "dev": "<slug>", "dev_difficult": "<slug>",
+    "qa": "<slug>", "security": "<slug>", "release": "<slug>"
+  }
+}
+```
+
+v1 catalogs (tiers only) unchanged. Malformed v2 → `MODEL_CATALOG_SCHEMA_V2_INVALID`.
+
+### New reason codes
+
+| Code | Trigger |
+|------|---------|
+| **`MODEL_OVERRIDE_SLUG_UNKNOWN`** | Direct slug validation failure |
+| **`MODEL_ROLE_SLUG_UNKNOWN`** | Role catalog lookup miss |
+| **`MODEL_CATALOG_SCHEMA_V2_INVALID`** | v2 schema validation failure |
+
+### Non-substitution paragraph
+
+MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE — unchanged from **US-0101**; model selection is orthogonal to context breadth.
+
+### Validation commands
+
+- `python scripts/model_tier_validate.py --repo .`
+- `pytest -k us0102 tests/auto_command_contract_test.py`
+- `python scripts/check_intake_template_parity.py --scope=model-tier-overrides`
+- `tests/run-tests.ps1` / `tests/run-tests.sh` §26AA
+
+Normative architecture: `docs/engineering/architecture.md` (**# US-0102**); decision: **`DEC-0087`**.
+
+Binding decision: `decisions/DEC-0086.md`.
+
 Context compaction policy:
 
 - `docs/engineering/state.md` is a compact hot surface for current execution

package/template/scripts/check_intake_template_parity.py

@@ -228,6 +228,64 @@ RELEASE_CHANGELOG_PAIRS: tuple[tuple[str, str], ...] = (
     ),
 )
 
+MODEL_TIER_PAIRS: tuple[tuple[str, str], ...] = (
+    (
+        "scripts/model_tier_lib.py",
+        "template/scripts/model_tier_lib.py",
+    ),
+    (
+        "scripts/model_tier_validate.py",
+        "template/scripts/model_tier_validate.py",
+    ),
+    (
+        "docs/engineering/runbook.md",
+        "template/docs/engineering/runbook.md",
+    ),
+    (
+        ".cursor/scratchpad.md",
+        "template/.cursor/scratchpad.md",
+    ),
+    (
+        ".cursor/scratchpad.local.example.md",
+        "template/.cursor/scratchpad.local.example.md",
+    ),
+    (
+        "scripts/check_intake_template_parity.py",
+        "template/scripts/check_intake_template_parity.py",
+    ),
+)
+
+MODEL_TIER_OVERRIDES_PAIRS: tuple[tuple[str, str], ...] = (
+    (
+        ".cursor/scratchpad.md",
+        "template/.cursor/scratchpad.md",
+    ),
+    (
+        ".cursor/scratchpad.local.example.md",
+        "template/.cursor/scratchpad.local.example.md",
+    ),
+    (
+        ".cursor/model-catalog.local.example.role-based-balanced.json",
+        "template/.cursor/model-catalog.local.example.role-based-balanced.json",
+    ),
+    (
+        ".cursor/model-catalog.local.example.role-based-highend.json",
+        "template/.cursor/model-catalog.local.example.role-based-highend.json",
+    ),
+    (
+        "scripts/model_tier_lib.py",
+        "template/scripts/model_tier_lib.py",
+    ),
+    (
+        "scripts/model_tier_validate.py",
+        "template/scripts/model_tier_validate.py",
+    ),
+    (
+        "docs/engineering/runbook.md",
+        "template/docs/engineering/runbook.md",
+    ),
+)
+
 DOWNSTREAM_CI_GUARD_PAIRS: tuple[tuple[str, str], ...] = (
     (
         "scripts/check_downstream_ci_guard.py",
@@ -252,6 +310,8 @@ SCOPES: dict[str, tuple[tuple[str, str], ...]] = {
     "project-readme": PROJECT_README_PAIRS,
     "dev-environment": DEV_ENVIRONMENT_PAIRS,
     "release-changelog": RELEASE_CHANGELOG_PAIRS,
+    "model-tier": MODEL_TIER_PAIRS,
+    "model-tier-overrides": MODEL_TIER_OVERRIDES_PAIRS,
     "all": (
         INTAKE_TEMPLATE_PAIRS
         + CAVEMAN_COMPRESS_PAIRS
@@ -265,6 +325,8 @@ SCOPES: dict[str, tuple[tuple[str, str], ...]] = {
         + PROJECT_README_PAIRS
         + DEV_ENVIRONMENT_PAIRS
         + RELEASE_CHANGELOG_PAIRS
+        + MODEL_TIER_PAIRS
+        + MODEL_TIER_OVERRIDES_PAIRS
     ),
 }