its-magic 0.1.3-0 → 0.1.3-2

package/installer.ps1

@@ -129,6 +129,14 @@ function Classify-File($RelPath) {
   $frameworkExact = @(
     '.cursor/hooks.json',
     '.cursor/scratchpad.local.example.md',
+    '.cursor/model-catalog.local.example.json',
+    '.cursor/model-catalog.local.example.cursor-only.json',
+    '.cursor/model-catalog.local.example.level-1-easy.json',
+    '.cursor/model-catalog.local.example.level-2-complex.json',
+    '.cursor/model-catalog.local.example.level-3-mega.json',
+    '.cursor/model-catalog.local.example.level-4-super.json',
+    '.cursor/model-catalog.local.example.role-based-balanced.json',
+    '.cursor/model-catalog.local.example.role-based-highend.json',
     'its_magic/.its-magic-version',
     'its_magic/README.md'
   )

package/installer.py

@@ -145,6 +145,14 @@ FRAMEWORK_PREFIXES = (
 )
 FRAMEWORK_EXACT = {
     ".cursor/hooks.json", ".cursor/scratchpad.local.example.md",
+    ".cursor/model-catalog.local.example.json",
+    ".cursor/model-catalog.local.example.cursor-only.json",
+    ".cursor/model-catalog.local.example.level-1-easy.json",
+    ".cursor/model-catalog.local.example.level-2-complex.json",
+    ".cursor/model-catalog.local.example.level-3-mega.json",
+    ".cursor/model-catalog.local.example.level-4-super.json",
+    ".cursor/model-catalog.local.example.role-based-balanced.json",
+    ".cursor/model-catalog.local.example.role-based-highend.json",
     ".its-magic-version", "its_magic/.its-magic-version", "its_magic/README.md",
 }
 USER_DATA_PREFIXES = (

package/installer.sh

@@ -182,6 +182,7 @@ classify_file() {
     README.md) echo "mixed" ;;
     .cursor/commands/*|.cursor/rules/*|.cursor/agents/*|.cursor/skills/*) echo "framework" ;;
     .cursor/hooks/*|.cursor/hooks.json|.cursor/scratchpad.local.example.md) echo "framework" ;;
+    .cursor/model-catalog.local.example*.json) echo "framework" ;;
     .github/workflows/*|scripts/validate-and-push*|scripts/sync_push_gates.py|docs/engineering/context/*|its_magic/*) echo "framework" ;;
     .its-magic-version|its_magic/.its-magic-version|its_magic/README.md) echo "framework" ;;
     docs/product/*|docs/engineering/*|docs/user-guides/*) echo "user-data" ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.3-0",
+  "version": "0.1.3-2",
   "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/commands/auto.md

@@ -522,6 +522,96 @@ used for resume/materialization failures):
 8. Sync verdict recording when eligible — reference step 12.
 9. Backlog-drain / bulk per-item summaries when enabled — reference step 13.
 
+## Cross-model adversarial critic post-phase hook (US-0104 / DEC-0104)
+
+**Default-off**: `CROSS_MODEL_REVIEW=0` → **zero overhead** — no critic spawn, no findings
+writes, no anti-slop gate. Existing phase lifecycle unchanged.
+
+When `CROSS_MODEL_REVIEW=1`, after each **producer** phase subagent returns, orchestrator
+**MUST Task-spawn** fresh **`/sovereign-critic`** subagent (spawn-only per **BUG-0006** /
+**US-0048** / **US-0023**). Orchestrator must not execute critic evaluation in-process.
+
+### Hook sequence
+
+1. Resolve `producer_model_id` from phase context or `model_tier_lib.resolve_model_for_phase`.
+2. Call `select_critic_model(producer_model_id, scratchpad, phase_id)`.
+3. If `degraded=True` (`CROSS_MODEL_DEGRADED_MODE`): three **sequential** fresh subagent spawns
+   (same `model_id`, different lens prompts — challenger, architect, subtractor); all findings
+   record `degraded_mode=true`.
+4. Else: parallel jury via single critic subagent running all three lenses.
+5. Append findings to `handoffs/sovereign_critic_findings.jsonl`; validate with
+   `python scripts/sovereign_critic_validate.py --repo . --enforce`.
+6. When `AI_DECISION_LEDGER=1`, call `patch_ledger_cross_model_reviewed(...)`.
+
+### Anti-slop rework loop
+
+After `/sovereign-critic`:
+
+1. Compute `anti_slop_aggregate = compute_anti_slop_aggregate(lens_scores)` (min of lens scores).
+2. Compare against `CROSS_MODEL_ANTISLOP_THRESHOLD` (default **6**).
+3. If aggregate **< threshold** and open **blocking** findings exist:
+   - Increment `rework_generation` for `(orchestrator_run_id, phase_id)`.
+   - If `rework_generation < CROSS_MODEL_REWORK_MAX` (default **2**): re-spawn producer phase
+     with fresh context; pass critic summary as read-only input → **`CROSS_MODEL_ANTISLOP_FAIL`**
+     (rework, not terminal).
+   - Else → **`CROSS_MODEL_REWORK_CAP_EXHAUSTED`** decision gate (operator waive or abort).
+
+### Isolation `model_id` v2
+
+When `CROSS_MODEL_REVIEW=1`, both producer and critic isolation evidence rows require additive
+**`model_id`**. Missing → fail-closed **`ISOLATION_EVIDENCE_MODEL_ID_MISSING`**.
+
+## Sovereign memory mistake-tagging hooks (US-0105 / DEC-0105)
+
+**Default-off**: `SOVEREIGN_MEMORY=0` → **zero overhead** — no `mistakes.jsonl` writes.
+
+When `SOVEREIGN_MEMORY=1`, orchestrator calls `record_mistake_hook(...)` from
+`scripts/sovereign_memory_lib.py` on detectable failure events (closed `mistake_tag` enum):
+
+| Trigger | `mistake_tag` | `failure_reason_code` |
+|---------|---------------|----------------------|
+| Auto-loop fix exhaust (`AUTO_IMPLEMENTATION_LOOP=1`) | `fix_failed` | `FIX_FAILED` |
+| Execute revert/rollback | `revert_applied` | `REVERT_APPLIED` |
+| Plan-fidelity hard stop (`classify_deviation` blocking) | `plan_fidelity_violation` | `PLAN_FIDELITY_VIOLATION` |
+| Extended-mode scope add without override | `scope_creep` | `PLAN_FIDELITY_SCOPE_GATE` |
+
+**US-0103 compose**: hooks may read ledger context for `provenance_ref` but must not mutate
+ledger schema. Retrospectives under `sovereign-memory/retrospectives/` are **not injected v1**.
+
+## Sovereign Loop Mode (US-0107 / DEC-0107)
+
+**Default-off**: `AUTO_SOVEREIGN=0` → **zero overhead** — no deferral reads/writes, no advance,
+no notifications. Requires **`SOVEREIGN_GOAL_MODE=goal_convergence`** when enabled (fail-closed
+**`SOVEREIGN_LOOP_GOAL_MODE_REQUIRED`**).
+
+### Advance hook (post-segment)
+
+After each native-chain segment completes ( **`stop_phase=refresh-context`** ), when
+`AUTO_SOVEREIGN=1` and goal convergence active, orchestrator calls
+`advance_sovereign_loop(repo, scratchpad, orchestrator_run_id=...)` from
+`scripts/sovereign_loop_lib.py`. Sovereign terminal stops are **additive** to the US-0088 /
+US-0092 stop matrix — do not replace `decision_gate`, `loop_max`, or security deny.
+
+### Drain-generate (spawn-only PO / US-0095)
+
+When advance returns `action=drain_generate`:
+
+1. Build PO spawn inputs via `build_drain_generate_spawn_inputs(...)` (vision narrow-read;
+   optional `sovereign_memory_digest` when `SOVEREIGN_MEMORY=1`).
+2. **MUST Task-spawn** fresh **PO** subagent (spawn-only per **US-0069** / **US-0095**) with
+   ephemeral work item id `drain-gen-{orchestrator_run_id}-{iteration}` — **not** a backlog row
+   until accepted.
+3. PO returns up to **3** candidates in `DrainGenerateCandidateBundle` v1.
+4. **Decision gate (mandatory per candidate)**: operator accept → **`/intake`** or controlled
+   backlog append; reject → discard. **No auto-append** without gate (**US-0092** hard gate).
+
+### Deferral register operator path
+
+- Append: `append_deferral(...)` → `handoffs/sovereign_deferrals.jsonl` (create-on-first-write).
+- Resolve: `resolve_deferral(repo, deferral_id, orchestrator_run_id=...)`.
+- Validate: `python scripts/sovereign_loop_validate.py --repo . --enforce`.
+- **US-0109** integration: downstream writer appends `DEPLOY_DEFERRED` rows (`work_item_kind=deploy`).
+
 ## Backward compatibility
 
 Default manual/interactive unchanged; `/resume` remains valid; deterministic precedence

package/template/.cursor/commands/execute.md

@@ -22,6 +22,7 @@ At the end of `/execute`, append an isolation evidence entry to
 - `fresh_context_marker=<new marker for this subagent>`
 - `timestamp=<ISO UTC>`
 - `evidence_ref=<primary output ref>` (recommended: `handoffs/dev_to_qa.md` and the target sprint `sprints/Sxxxx/summary.md`)
+- `model_id=<resolved model slug or alias>` — **required when `CROSS_MODEL_REVIEW=1`** (US-0104 v2 additive extension); omit when `CROSS_MODEL_REVIEW=0`. Missing → fail-closed **`ISOLATION_EVIDENCE_MODEL_ID_MISSING`**.
 
 In an execute↔QA implementation loop (`AUTO_IMPLEMENTATION_LOOP=1`), each new
 `/execute` cycle must have a new `fresh_context_marker` (marker reuse is treated
@@ -32,6 +33,10 @@ as stale isolation evidence).
 - **Narrow-read (US-0053 / US-0096 Tranche A)**: Start at docs/engineering/phase-context.md
   and the story section anchor in vision/architecture/decisions when a heading exists; forbid
   full-file reads when a section heading exists.
+- **Sovereign memory digest (US-0105 / DEC-0105)**: When merged scratchpad `SOVEREIGN_MEMORY=1`,
+  spawn assembler appends read-only **`sovereign_memory_digest`** block after phase-context
+  narrow-read and before role instructions via `build_injection_digest_block(...)` from
+  `scripts/sovereign_memory_lib.py`. Zero overhead when `SOVEREIGN_MEMORY=0` (default).
 - `sprints/S0001/tasks.md`
 - `handoffs/tl_to_dev.md`
 - Optional: `handoffs/qa_to_dev.md` when fixing QA findings
@@ -341,3 +346,24 @@ Reason codes: **`UAT_BROWSER_UNAVAILABLE`**, **`UAT_BROWSER_PROBE_FAILED`**,
      remote cues (compose when both fire).
    - Active + `template/.cursor/commands/execute.md` byte-identical step **24** block.
 
+25. Cross-model critic evidence tuple (US-0104 / DEC-0104):
+   - **25 preamble**: Read merged scratchpad `CROSS_MODEL_REVIEW` (default `0`). When `0`,
+     skip **25a** with zero overhead — no `critic_evidence` block required.
+   - **25a Handoff block**: When `CROSS_MODEL_REVIEW=1`, append fenced JSON under
+     **`### critic_evidence`** in `handoffs/dev_to_qa.md` using
+     `build_critic_evidence_block(...)` from `scripts/sovereign_critic_lib.py`:
+     `producer_model_id`, `critic_model_id`, `anti_slop_aggregate`, `rework_generation`,
+     `degraded_mode`, `findings_path`.
+   - Isolation evidence for `/execute` must include **`model_id`** on the producer row when
+     critic is enabled (see Isolation evidence write requirement above).
+   - Active + `template/.cursor/commands/execute.md` byte-identical step **25** block.
+
+26. Sovereign memory mistake hook — revert/rollback (US-0105 / DEC-0105):
+   - **26 preamble**: Read merged scratchpad `SOVEREIGN_MEMORY` (default `0`). When `0`, skip
+     with zero overhead.
+   - **26a Revert path**: When git revert or rollback is applied during execute findings
+     remediation, call `record_mistake_hook(mistake_tag="revert_applied", ...)` from
+     `scripts/sovereign_memory_lib.py` with `failure_reason_code=REVERT_APPLIED`. Optional
+     `provenance_ref` may cite ledger context (**US-0103** read-only — do not mutate ledger schema).
+   - Active + `template/.cursor/commands/execute.md` byte-identical step **26** block.
+

package/template/.cursor/commands/refresh-context.md

@@ -56,6 +56,38 @@ description: "its-magic refresh context: compact state and decisions."
    - record verification tuple fields (`boundary`, `moved`, `retained`,
      `pack_ref`) in the new `state.md` checkpoint when any rollover occurred;
      idempotent reruns must not duplicate archived content.
+3b. **Goal progress emission (US-0110 / DEC-0110)**: when merged scratchpad
+    `SOVEREIGN_GOAL_MODE=goal_convergence` and sovereign loop is active, run from repo root:
+
+    ```bash
+    python scripts/sovereign_convergence_lib.py --emit-resume-brief --repo . --orchestrator-run-id <run_id>
+    ```
+
+    Writes a fenced JSON block under **`### goal_progress`** in `handoffs/resume_brief.md`.
+    Placement: after the latest **`## Latest orchestration pointer`** section, before
+    **`## Prior orchestration pointer`**. Skip entirely when `SOVEREIGN_GOAL_MODE=phase_driven`
+    (zero overhead). Validate shape with:
+
+    ```bash
+    python scripts/sovereign_convergence_validate.py --repo . --enforce
+    ```
+
+3c. **Sovereign memory curator retrospective + ledger promotion (US-0105 / DEC-0105)**:
+    after release segment close, when merged scratchpad `SOVEREIGN_MEMORY=1`:
+
+    1. `write_retrospective(sprint_id, body)` →
+       `docs/engineering/sovereign-memory/retrospectives/<sprint_id>.md` with
+       `{sprint_id, story_ids[], release_ref, summary, learnings[], promoted_entry_ids[]}`.
+    2. When **also** `AI_DECISION_LEDGER=1`: `promote_from_ledger(orchestrator_run_id, ...)`
+       copies subset to `decisions-log.jsonl` with `provenance_ref=ledger:<decision_id>`.
+    3. When ledger off or filter empty → informational **`SOVEREIGN_MEMORY_PROMOTION_SKIPPED`**.
+
+    Retrospectives are human audit only — **not injected v1**. Skip entirely when
+    `SOVEREIGN_MEMORY=0` (zero overhead). Validate JSONL when files exist:
+
+    ```bash
+    python scripts/sovereign_memory_validate.py --repo . --enforce
+    ```
 
 ## Deterministic artifact ordering contract (US-0058 / DEC-0040)
 

package/template/.cursor/commands/sovereign-critic.md

@@ -0,0 +1,104 @@
+---
+description: "its-magic sovereign-critic: cross-model adversarial review after producer phase."
+---
+
+# /sovereign-critic
+
+## Subagents
+- tech-lead (default critic role; fresh context per US-0048 / US-0023)
+
+## Execution model
+- Run `/sovereign-critic` in a **fresh critic subagent** context only.
+- Invoked by **`/auto`** orchestrator **after** a producer phase completes when
+  `CROSS_MODEL_REVIEW=1` (default-off — zero overhead when `0`).
+- Orchestrator **must not** execute critic work in-process (**BUG-0006** spawn-only).
+- All three lenses run per invocation (parallel jury when distinct critic model;
+  sequential fresh spawns in degraded single-model-multi-lens mode).
+
+## Inputs
+
+- `phase_id` — completed producer phase id (DEC-0086 canonical)
+- `role` — producer logical role (`po`, `tech-lead`, `dev`, `qa`, …)
+- `evidence_ref` — primary artifact refs for the completed phase
+- `producer_model_id` — resolved slug or alias (`fast`, `inherit`, vendor slug)
+- `artifact_digest` — bounded summary of phase deliverables under review
+- `orchestrator_run_id` — partition key for rework counter
+
+## Model selection
+
+Resolve critic via `scripts/sovereign_critic_lib.py`:
+
+```python
+select_critic_model(producer_model_id, scratchpad, phase_id)
+```
+
+- Tier opposition: producer `strong`/`balanced` → critic `cheap`; producer `cheap` → critic `strong`.
+- Same normalized slug → `degraded_mode=true`, reason `CROSS_MODEL_DEGRADED_MODE`.
+- Catalog miss → degraded fallback (three sequential lens spawns, same `model_id`).
+
+## Three-lens evaluation (all lenses per invocation)
+
+| Lens | Focus | Checklist (2.5 pts each) |
+|------|-------|--------------------------|
+| **`challenger`** | Edge cases, races, failure modes, boundaries | edge_case_cited; failure_mode_named; concurrency_considered; input_boundary_tested |
+| **`architect`** | Coupling, layering, dependency direction | coupling_named; layer_boundary_stated; dependency_direction_explicit; interface_contract_mentioned |
+| **`subtractor`** | Over-engineering, YAGNI, scope creep | unnecessary_abstraction_flagged; yagni_applied; premature_generalization_challenged; scope_creep_identified |
+
+### Lens prompt templates
+
+**Challenger** — Find edge cases, race conditions, failure modes, and boundary violations in the phase artifacts. Cite specific paths. Report checklist hits and propose blocking findings when convergence should halt.
+
+**Architect** — Evaluate coupling, layer boundaries, dependency direction, and interface contracts. Name modules and layers explicitly. Flag violations that block release readiness.
+
+**Subtractor** — Challenge over-engineering, premature abstraction, YAGNI violations, and scope creep. Prefer minimal diffs aligned with task scope.
+
+## Anti-slop scoring
+
+Per lens: `score_lens_antislop(lens, checklist_hits)` → int 0–10.  
+Aggregate: `compute_anti_slop_aggregate(lens_scores)` → `min(lens_scores)`.
+
+Agent-reported `anti_slop_score` must be ≤ rubric ceiling (lib clamps down).
+
+## Reconciliation
+
+After all lens findings are collected, run `reconcile_findings(raw_findings)`:
+
+- ≥2 lenses share `issue_key` → `confidence=high`, `single_finder=false`
+- Exactly 1 lens → `confidence=medium`, `single_finder=true`
+
+## Outputs (artifacts)
+
+- Append findings to **`handoffs/sovereign_critic_findings.jsonl`** (15-field v1 schema)
+- Optional **`cross_reviewer_findings`** block in sprint **`qa-findings.md`** via
+  `build_qa_cross_reviewer_block(repo)`
+- When `AI_DECISION_LEDGER=1`, call `patch_ledger_cross_model_reviewed(...)` with
+  `cross_model_reviewed=True`
+
+## Isolation evidence (US-0048 + US-0104 v2)
+
+At the end of `/sovereign-critic`, append isolation evidence to `docs/engineering/state.md`:
+
+- `phase_id=sovereign-critic`
+- `role=tech-lead` (or configured critic role)
+- `fresh_context_marker=<new marker for this critic subagent>`
+- `timestamp=<ISO UTC>`
+- `evidence_ref=<findings path + reviewed artifacts>`
+- `model_id=<critic_model_id>` — **required when `CROSS_MODEL_REVIEW=1`**; omit when `0`
+
+Missing `model_id` when critic enabled → fail-closed **`ISOLATION_EVIDENCE_MODEL_ID_MISSING`**.
+
+## Stop conditions
+
+- `CROSS_MODEL_REVIEW=0` → skip entirely (zero overhead)
+- `CROSS_MODEL_CRITIC_SPAWN_FAILED` → blocking orchestrator hook failure
+- `CROSS_MODEL_FINDINGS_INVALID` → schema validation failure
+- `CROSS_MODEL_RECONCILE_FAILED` → jury merge error
+
+## Validator
+
+```bash
+python scripts/sovereign_critic_validate.py --repo . --enforce
+python scripts/sovereign_critic_validate.py --open-blocking --repo .
+```
+
+Success literal: **`[SOVEREIGN_CRITIC_VALIDATION_OK]`**.

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/rules/sovereign-role-manifest.mdc.example

@@ -0,0 +1,27 @@
+---
+description: "Sovereign Role-Behavior Manifest enforcement (US-0106 / DEC-0106)"
+globs:
+---
+
+- When `SOVEREIGN_ROLE_MANIFEST=1` in scratchpad, the sovereign role manifest at
+  `.cursor/sovereign-role-manifest.yaml` is the additive per-role objective and
+  inter-role review obligation layer on top of US-0069 spawn machinery.
+- Review spawns are supplementary post-phase hooks — they never substitute for
+  the US-0069 producer role.
+- Validate manifest with `python scripts/sovereign_role_manifest_validate.py --repo .`.
+- Schema v1 requires 6 sections: `schema_version`, `roles[]`, `review_obligations[]`,
+  `allowed_self_overrides`, `cross_model_policy`, `escalation_rules`.
+- Six role IDs: `po`, `tech-lead`, `dev`, `qa`, `release`, `curator`.
+- Review foci: `user_value_drift`, `testability`, `buildability`, `deployability`.
+- Cross-model default orders: `role_review_first`, `critic_first`, `critic_only`, `role_review_only`.
+- Secret-literal scan: no `api_key`, `token`, `password`, `secret`, `private_key` shaped
+  literals in `objective_function` fields (`SOVEREIGN_ROLE_SECRET_DETECTED`).
+- Objective injection char cap: `SOVEREIGN_ROLE_OBJECTIVE_MAX_CHARS` (default 512).
+- Obligation dispatch per-phase cap: `SOVEREIGN_ROLE_REVIEW_MAX_PER_PHASE` (default 2).
+- Rework cap: `SOVEREIGN_ROLE_REVIEW_REWORK_MAX` (default 1).
+- Default-off: `SOVEREIGN_ROLE_MANIFEST=0` → zero overhead (no file I/O).
+- Compose guards: US-0069 phase→role matrix unchanged, US-0104 critic schema unchanged.
+- Reason codes: `SOVEREIGN_ROLE_MANIFEST_DISABLED`, `SOVEREIGN_ROLE_MANIFEST_SCHEMA_INVALID`,
+  `SOVEREIGN_ROLE_UNKNOWN_ROLE`, `SOVEREIGN_ROLE_UNKNOWN_PHASE`, `SOVEREIGN_ROLE_SECRET_DETECTED`,
+  `SOVEREIGN_ROLE_OBJECTIVE_OVERFLOW`, `ROLE_REVIEW_DISPATCH_FAILED`, `ROLE_REVIEW_SPAWN_FAILED`,
+  `ROLE_REVIEW_BLOCKED`, `ROLE_REVIEW_DEFERRAL_FAILED`, `ROLE_REVIEW_REWORK_CAP`.

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