its-magic 0.1.3-0 → 0.1.3-2

package/template/.cursor/scratchpad.md

@@ -322,3 +322,206 @@ 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).
+#
+# AI Decision Ledger + Plan Fidelity (US-0103 / DEC-0103)
+# Sovereign-loop foundation. Default-off — zero overhead when AI_DECISION_LEDGER=0.
+# - AI_DECISION_LEDGER: 0|1 (default 0) — when 0: no ledger reads/writes/schema checks.
+# - AUTO_PLAN_FIDELITY: strict|relaxed|extended (default strict) — active only when ledger enabled.
+#   strict   = any unapproved drop/reorder/scope-add → PLAN_FIDELITY_VIOLATION hard stop
+#   relaxed  = drop/reorder allowed (ledger entry); scope-add still hard stop
+#   extended = scope-add allowed (extension report); drop/reorder allowed
+AI_DECISION_LEDGER=0
+AUTO_PLAN_FIDELITY=strict
+#
+# Goal-Based Convergence (US-0110 / DEC-0110)
+# Default-off sovereign-loop terminal predicate. When SOVEREIGN_GOAL_MODE=phase_driven,
+# zero overhead — no evaluation, no goal_progress block, no partial-delivery write.
+# Compose do NOT amend US-0088 / US-0092 / US-0095 / US-0044 / US-0103 (read-only surfaces).
+# - SOVEREIGN_GOAL_MODE: phase_driven|goal_convergence (default phase_driven)
+# - SOVEREIGN_GOAL: explicit goal text (wins over vision auto-derive; default empty)
+# - SOVEREIGN_GOAL_TOP_N: int >= 1 vision paragraph count for auto-derive (default 3)
+# - SOVEREIGN_GOAL_MAX_CHARS: int >= 64 truncation cap (default 512)
+# - SOVEREIGN_GOAL_TIMEOUT_MAX: int >= 0 iteration-count cap (0 = disabled; not wall-clock)
+SOVEREIGN_GOAL_MODE=phase_driven
+SOVEREIGN_GOAL=
+SOVEREIGN_GOAL_TOP_N=3
+SOVEREIGN_GOAL_MAX_CHARS=512
+SOVEREIGN_GOAL_TIMEOUT_MAX=0
+#
+# Cross-Model Adversarial Critic (US-0104 / DEC-0104)
+# Default-off cross-model review. When CROSS_MODEL_REVIEW=0, zero overhead — no critic
+# spawn, no findings writes, no anti-slop gate. Compose do NOT amend US-0048 / US-0069 /
+# US-0023 / US-0110 / US-0103 (additive surfaces only).
+# - CROSS_MODEL_REVIEW: 0|1 (default 0)
+# - CROSS_MODEL_ANTISLOP_THRESHOLD: int 0-10 aggregate floor (default 6)
+# - CROSS_MODEL_REWORK_MAX: int >= 0 producer re-spawns per (run, phase) (default 2)
+CROSS_MODEL_REVIEW=0
+CROSS_MODEL_ANTISLOP_THRESHOLD=6
+CROSS_MODEL_REWORK_MAX=2
+#
+# Sovereign Memory (US-0105 / DEC-0105)
+# Default-off institutional memory. When SOVEREIGN_MEMORY=0, zero overhead —
+# no JSONL writes, no injection reads, no spawn digest assembly.
+# Compose do NOT amend US-0029 / US-0080 / US-0103 / US-0072 / US-0096.
+# - SOVEREIGN_MEMORY: 0|1 (default 0)
+# - SOVEREIGN_MEMORY_TOP_N: int >= 0 (default 5) — global recent pool (all four JSONL families)
+# - SOVEREIGN_MEMORY_TOP_K: int >= 0 (default 3) — high-impact pool (patterns + mistakes only)
+# - SOVEREIGN_MEMORY_MAX_CHARS: int >= 0 (default 2048) — hard cap on assembled digest_text
+# - SOVEREIGN_MEMORY_JSONL_MAX_LINES: int >= 1 (default 500) — active JSONL line cap before archive rollover
+SOVEREIGN_MEMORY=0
+SOVEREIGN_MEMORY_TOP_N=5
+SOVEREIGN_MEMORY_TOP_K=3
+SOVEREIGN_MEMORY_MAX_CHARS=2048
+SOVEREIGN_MEMORY_JSONL_MAX_LINES=500
+#
+# Sovereign Loop Mode (US-0107 / DEC-0107)
+# Default-off project orchestration. When 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). Compose do NOT amend
+# US-0088 / US-0092 / US-0095 / US-0044 / US-0103 / US-0105 / US-0110 (additive hooks only).
+# - AUTO_SOVEREIGN: 0|1 (default 0)
+# - AUTO_SOVEREIGN_DEFERRAL_MAX: int >= 1 (default 50) — max open deferral rows
+# - AUTO_SOVEREIGN_DRAIN_GENERATE_MAX: int >= 0 (default 3) — drain-generate iterations per run
+# - AUTO_SOVEREIGN_DEFERRAL_POLICY: stop|skip|resolve_first (default resolve_first)
+# - SOVEREIGN_NOTIFY_TARGET: off|ntfy|email|hook (default off)
+# - SOVEREIGN_NOTIFY_NTFY_TOPIC: string (default empty — local-only)
+# - SOVEREIGN_NOTIFY_NTFY_BASE: URL (default empty — local-only ntfy base override)
+# - SOVEREIGN_NOTIFY_HOOK_URL: URL (default empty — local-only webhook)
+# - SOVEREIGN_NOTIFY_EMAIL_TO: email (default empty — email v1 deferred)
+AUTO_SOVEREIGN=0
+AUTO_SOVEREIGN_DEFERRAL_MAX=50
+AUTO_SOVEREIGN_DRAIN_GENERATE_MAX=3
+AUTO_SOVEREIGN_DEFERRAL_POLICY=resolve_first
+SOVEREIGN_NOTIFY_TARGET=off
+SOVEREIGN_NOTIFY_NTFY_TOPIC=
+SOVEREIGN_NOTIFY_NTFY_BASE=
+SOVEREIGN_NOTIFY_HOOK_URL=
+SOVEREIGN_NOTIFY_EMAIL_TO=
+#
+# Sovereign Role-Behavior Manifest (US-0106 / DEC-0106)
+# Default-off per-role objective + inter-role review obligations. When SOVEREIGN_ROLE_MANIFEST=0,
+# zero overhead — no manifest reads, no objective injection, no review dispatch.
+# Compose do NOT amend US-0069 (phase→role matrix unchanged; review spawns supplementary),
+# US-0104 (critic lenses + findings schema unchanged; role reviews additive),
+# US-0003 / US-0023 / US-0103 / US-0105 / US-0107 (unchanged surfaces).
+# - SOVEREIGN_ROLE_MANIFEST: 0|1 (default 0)
+# - SOVEREIGN_ROLE_OBJECTIVE_MAX_CHARS: int >= 1 (default 512) — hard truncate for injection
+# - SOVEREIGN_ROLE_REVIEW_MAX_PER_PHASE: int >= 0 (default 2) — per-phase review cap
+# - SOVEREIGN_ROLE_REVIEW_REWORK_MAX: int >= 0 (default 1) — bounded rework before decision gate
+SOVEREIGN_ROLE_MANIFEST=0
+SOVEREIGN_ROLE_OBJECTIVE_MAX_CHARS=512
+SOVEREIGN_ROLE_REVIEW_MAX_PER_PHASE=2
+SOVEREIGN_ROLE_REVIEW_REWORK_MAX=1
+#
+# Parallel Instance Arbitrage (US-0108 / DEC-0108)
+# Default-off parallel execute-phase instance orchestration. When SOVEREIGN_PARALLEL_DEV=0,
+# zero overhead — no worktrees, no parallel QA, no pick JSON, no resource guard.
+# Compose do NOT amend US-0047 (bulk execute unchanged), US-0092 (full autonomy unchanged),
+# US-0103 (ledger schema unchanged; read-only consumer), US-0104 (critic schema unchanged;
+# read-only anti_slop_score consumer), US-0107 (sovereign loop unchanged; consumer only).
+# - SOVEREIGN_PARALLEL_DEV: 0|1 (default 0) — global enable gate
+# - AUTO_SOVEREIGN_PARALLEL_N: int >= 1 (default 3) — instances per execute cycle
+# - AUTO_SOVEREIGN_PARALLEL_MAX_TOTAL: int >= 1 (default 6) — system-wide instance cap
+# - AUTO_SOVEREIGN_MERGE_RESOLVE: first_pass_wins|last_pass_wins|winner_takes_all|manual (default first_pass_wins)
+# - AUTO_SOVEREIGN_WORKTREE_KEEP: 0|1 (default 0) — retain loser worktrees for debugging
+# - AUTO_SOVEREIGN_PARALLEL_QA: 0|1 (default 0) — enable parallel QA cross-review (v2)
+# - AUTO_SOVEREIGN_PARALLEL_QA_ARBITER: critic_first_pass|majority_vote (default critic_first_pass)
+# - AUTO_SOVEREIGN_PARALLEL_ANTI_SLOP_THRESHOLD: int 0-10 (default 6) — anti-slop floor
+# - AUTO_SOVEREIGN_PARALLEL_REWORK_MAX: int >= 0 (default 2) — per-instance rework cap
+# - AUTO_SOVEREIGN_PARALLEL_MERGE_TIMEOUT_SEC: int >= 10 (default 60) — merge timeout
+# - AUTO_SOVEREIGN_PARALLEL_MODEL_<idx>: model slug per instance (optional)
+# - AUTO_SOVEREIGN_PARALLEL_LENS_<idx>: lens config per instance (optional)
+SOVEREIGN_PARALLEL_DEV=0
+AUTO_SOVEREIGN_PARALLEL_N=3
+AUTO_SOVEREIGN_PARALLEL_MAX_TOTAL=6
+AUTO_SOVEREIGN_MERGE_RESOLVE=first_pass_wins
+AUTO_SOVEREIGN_WORKTREE_KEEP=0
+AUTO_SOVEREIGN_PARALLEL_QA=0
+AUTO_SOVEREIGN_PARALLEL_QA_ARBITER=critic_first_pass
+AUTO_SOVEREIGN_PARALLEL_ANTI_SLOP_THRESHOLD=6
+AUTO_SOVEREIGN_PARALLEL_REWORK_MAX=2
+AUTO_SOVEREIGN_PARALLEL_MERGE_TIMEOUT_SEC=60
+#
+# Self-Healing Deploy Loop (US-0109 / DEC-0109)
+# Default-off auto-heal post-publish probe + bounded retry + DEPLOY_DEFERRED.
+# When AUTO_SOVEREIGN_SELF_HEALING_DEPLOY=0 zero overhead, byte-identical US-0054 publish path —
+# no probe, no retry, no deferral, no execute steps 29-31. Compose do NOT amend US-0054 / US-0100 /
+# US-0103 / US-0107 / US-0110 (US-0109 consumer-only hook after US-0054 publish PASS).
+# - AUTO_SOVEREIGN_SELF_HEALING_DEPLOY: 0|1 (default 0) — global gate
+# - AUTO_SOVEREIGN_DEPLOY_RETRY_MAX: int >= 1 (default 3) — max retry attempts after probe FAIL
+# - AUTO_SOVEREIGN_DEPLOY_SMOKE_TIMEOUT_SEC: int >= 1 (default 30) — per-stage probe HTTP timeout
+# - AUTO_SOVEREIGN_DEPLOY_PROBE_KIND: health_endpoint|acceptance_smoke|both (default both)
+# - SOVEREIGN_DEPLOY_ACCEPTANCE_SMOKE_PATH: repo-relative path (default tests/deploy_smoke/)
+# - AUTO_SOVEREIGN_DEPLOY_HEALTH_ENDPOINT: names-only env ref (US-0085 compose); empty = unresolvable
+# Reason codes (DEC-0109 §7): DEPLOY_HEALING_DISABLED (info), DEPLOY_HEALING_SMOKE_HEALTH_FAIL,
+#   DEPLOY_HEALING_SMOKE_ACCEPTANCE_FAIL, DEPLOY_HEALING_RETRY_ATTEMPT,
+#   DEPLOY_HEALING_RETRY_CAP_EXHAUSTED, DEPLOY_HEALING_DEFERRED,
+#   DEPLOY_HEALING_PROBE_TARGET_MISSING, DEPLOY_HEALING_TIMEOUT.
+AUTO_SOVEREIGN_SELF_HEALING_DEPLOY=0
+AUTO_SOVEREIGN_DEPLOY_RETRY_MAX=3
+AUTO_SOVEREIGN_DEPLOY_SMOKE_TIMEOUT_SEC=30
+AUTO_SOVEREIGN_DEPLOY_PROBE_KIND=both
+SOVEREIGN_DEPLOY_ACCEPTANCE_SMOKE_PATH=tests/deploy_smoke/
+AUTO_SOVEREIGN_DEPLOY_HEALTH_ENDPOINT=

package/template/.cursor/sovereign-role-manifest.yaml.example

@@ -0,0 +1,53 @@
+schema_version: 1
+roles:
+  - role_id: po
+    objective_function: Maximize user value delivery through discovery, intake, and acceptance criteria
+  - role_id: tech-lead
+    objective_function: Produce buildable architecture aligned to user value and testable scope
+  - role_id: dev
+    objective_function: Implement planned tasks with artifact discipline and zero regression
+  - role_id: qa
+    objective_function: Verify test plan, runtime evidence, and blocking-findings disposition
+  - role_id: release
+    objective_function: Gate release surfaces, parity, and operator-facing connectivity
+  - role_id: curator
+    objective_function: Keep state, decisions, and research surfaces compact and current
+review_obligations:
+  - obligation_id: O1
+    reviewer_role: po
+    target_role: tech-lead
+    trigger_phase: architecture
+    review_focus: user_value_drift
+    artifact_refs:
+      - docs/engineering/architecture.md
+    blocking: false
+  - obligation_id: O2
+    reviewer_role: qa
+    target_role: po
+    trigger_phase: intake
+    review_focus: testability
+    artifact_refs:
+      - docs/product/acceptance.md
+    blocking: false
+  - obligation_id: O3
+    reviewer_role: dev
+    target_role: tech-lead
+    trigger_phase: architecture
+    review_focus: buildability
+    artifact_refs:
+      - docs/engineering/architecture.md
+    blocking: false
+  - obligation_id: O4
+    reviewer_role: release
+    target_role: qa
+    trigger_phase: qa
+    review_focus: deployability
+    artifact_refs:
+      - sprints/Sxxxx/qa-findings.md
+    blocking: false
+allowed_self_overrides: [verbosity, detail_level, tone]
+cross_model_policy:
+  default_order: role_review_first
+escalation_rules:
+  rework_max: 1
+  decision_gate: operator

package/template/decisions/DEC-0104.md

@@ -0,0 +1,279 @@
+# DEC-0104: Cross-Model Adversarial Critic (US-0104)
+
+- **Date**: 2026-06-28
+- **Status**: Accepted
+- **Story**: `US-0104`
+- **Composes on**: **US-0048** (per-phase isolation evidence), **US-0069** (phase role enforcement), **US-0023** (fresh-context semantics), **US-0110** (convergence conjunct 3) — **do not amend**; US-0104 **populates** `handoffs/sovereign_critic_findings.jsonl` and sets **`cross_model_reviewed`** on **US-0103** ledger entries
+- **Related**: `R-0092` (research anchor), **US-0101** / **US-0102** (model resolution — read-only consumer), **US-0103** (ledger `cross_model_reviewed` field), **US-0108** (anti-slop score consumer), **US-0045** (status authority)
+- **Supersedes**: none
+- **Default-off**: `CROSS_MODEL_REVIEW=0` — zero overhead when off
+
+## Context
+
+Sovereign-loop quality gate (US-0103..US-0110). After each producer phase completes, an optional critic subagent using a **different model** evaluates phase artifacts through three fixed lenses (Challenger / Architect / Subtractor). Findings reconcile via parallel-jury agreement; anti-slop scoring triggers bounded producer rework. **US-0048 / US-0069 / US-0023 / US-0110 are UNCHANGED** — US-0104 writes findings JSONL and optional ledger patches only.
+
+Research basis: `R-0092` Q1–Q7 closed.
+
+## Decision
+
+### §1 — Scratchpad keys (AC-1)
+
+| Key | Values | Default | Notes |
+|-----|--------|---------|-------|
+| **`CROSS_MODEL_REVIEW`** | **`0`** \| **`1`** | **`0`** | When `0`, no critic spawn, no findings writes, no anti-slop gate — **zero overhead**. |
+| **`CROSS_MODEL_ANTISLOP_THRESHOLD`** | int **0–10** | **`6`** | Aggregate below threshold → rework loop. |
+| **`CROSS_MODEL_REWORK_MAX`** | int ≥ **0** | **`2`** | Max producer re-spawns per `(orchestrator_run_id, phase_id)` before decision gate. |
+
+Published in **`.cursor/scratchpad.md`** (+ **`template/.cursor/scratchpad.md`** byte-parity per **US-0017**).
+
+**Rejected**: always-on critic (**rejected** — latency/token cost; default-off discipline).
+**Rejected**: per-lens threshold keys (**rejected** — single aggregate `min(lens_scores)` sufficient for v1; **US-0108** depends on stable aggregate).
+
+### §2 — Findings JSONL schema v1 (AC-4, AC-5)
+
+**Canonical path**: **`handoffs/sovereign_critic_findings.jsonl`** (repo root under `handoffs/`; matches **US-0110** `sovereign_convergence_lib.CRITIC_PATH`). Append-only; one file per repo (not per run).
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| **`ts`** | ISO 8601 UTC string | yes | `YYYY-MM-DDTHH:MM:SS.mmmZ` |
+| **`orchestrator_run_id`** | non-empty string | yes | Partition key for rework counter |
+| **`phase_id`** | string | yes | **DEC-0086** canonical phase id |
+| **`role`** | string | yes | Producer logical role (`po`, `tech-lead`, `dev`, `qa`, …) |
+| **`producer_model_id`** | non-empty string | yes | Resolved slug or stable alias (`fast`, `inherit`, vendor slug) |
+| **`critic_model_id`** | non-empty string | yes | Same vocabulary as producer |
+| **`lens`** | enum | yes | `challenger` \| `architect` \| `subtractor` |
+| **`finding_id`** | UUIDv4 | yes | Globally unique per finding line |
+| **`severity`** | enum | yes | `low` \| `medium` \| `high` \| `critical` |
+| **`confidence`** | enum | yes | `high` \| `medium` \| `low` — set by reconciliation |
+| **`anti_slop_score`** | int **0–10** | yes | Per-lens score after rubric validation |
+| **`finding_text`** | non-empty string | yes | Operator-auditable prose |
+| **`status`** | enum | yes | `open` \| `resolved` \| `waived` |
+| **`blocking`** | bool | yes | `true` when finding blocks convergence / rework exit |
+| **`degraded_mode`** | bool | yes | `true` when single-model-multi-lens fallback active |
+
+**Optional v1 fields** (allowed, not required): **`issue_key`** (normalized dedup key), **`single_finder`** (bool), **`rework_generation`** (int ≥ 0).
+
+**Invariant**: `schema_version: 1` implicit via field inventory. Future bumps → `schema_version: 2`.
+
+### §3 — Three lenses + parallel jury (AC-3)
+
+| Lens | Evaluation focus |
+|------|------------------|
+| **`challenger`** | Edge cases, race conditions, failure modes, boundary violations |
+| **`architect`** | Coupling, layering, boundaries, dependency direction |
+| **`subtractor`** | Over-engineering, premature abstraction, YAGNI, scope creep |
+
+v1 runs **all three lenses** per critic invocation. Lens prompt templates live in **`.cursor/commands/sovereign-critic.md`** + runbook — no runtime lens invention.
+
+**Reconciliation rule** (`reconcile_findings`):
+1. Compute **`issue_key`** per raw finding via **`compute_issue_key(finding_text)`** (§4).
+2. Group by `issue_key` across lenses.
+3. **≥2 lenses** share `issue_key` → `confidence=high`, `single_finder=false`.
+4. **Exactly 1 lens** → `confidence=medium`, `single_finder=true`.
+5. Emit merged finding rows with reconciled confidence; preserve per-lens `anti_slop_score`.
+
+### §4 — Issue normalization key v1 (R-0092 Q2)
+
+Deterministic **`compute_issue_key(finding_text) -> str`**:
+
+1. Lowercase `finding_text`.
+2. Remove punctuation (`string.punctuation`).
+3. Collapse whitespace to single spaces; strip.
+4. Truncate to **80** characters on word boundary.
+5. SHA-256 hex digest; return first **16** hex chars prefixed `ik_`.
+
+**Rejected**: semantic embedding cluster (**rejected** — non-deterministic, no stdlib embedding in v1).
+**Rejected**: exact string match only (**rejected** — too brittle across lens phrasing).
+
+### §5 — `select_critic_model` algorithm (AC-2, AC-7)
+
+`select_critic_model(producer_model_id, scratchpad, phase_id) -> SelectCriticResult`:
+
+1. If `producer_model_id` empty: resolve via **`model_tier_lib.resolve_model_for_phase(phase_id, scratchpad)`** → slug or alias.
+2. Map producer to tier:
+   - alias `fast` → **`cheap`**
+   - alias `inherit` or empty/omitted → **`balanced`**
+   - explicit slug: lookup catalog tier when `MODEL_RESOLVE=local_catalog`; else infer **`strong`** for non-alias slugs.
+3. Pick critic tier (opposition table):
+   | Producer tier | Critic tier |
+   |---------------|-------------|
+   | `strong` | `cheap` |
+   | `balanced` | `cheap` |
+   | `cheap` | `strong` |
+4. Resolve critic slug via **`model_tier_lib`** tier chain for synthetic phase **`sovereign-critic`** (fixed **`cheap`** tier in `DEFAULT_PHASE_TIER_MATRIX` override) **OR** direct tier→slug from catalog.
+5. Normalize comparison: aliases `fast`≠`inherit`≠vendor slug; if normalized critic slug **equals** producer slug → **`degraded=True`**, reason **`CROSS_MODEL_DEGRADED_MODE`**.
+6. Catalog miss / only one slug → **`degraded=True`**, reason **`CROSS_MODEL_CRITIC_MODEL_UNAVAILABLE`** or **`CROSS_MODEL_MODEL_COLLISION`**.
+
+**R-0088 limitations** (documented, not blocked): Cursor Task tool `model` param may override subagent frontmatter; BYOK keys not inherited by subagents; `inherit` unreliable on some billing plans. Framework records **`degraded_mode=true`** and continues single-model-multi-lens — not a hard stop.
+
+**Degraded fallback (L8)**: three sequential fresh subagent spawns (same `model_id`, different lens prompts); all findings record `degraded_mode=true`.
+
+### §6 — Anti-slop rubric + rework (AC-6)
+
+**Per-lens deterministic checklist** (agent reports hits; lib validates floor):
+
+| Lens | Checks (2.5 pts each, max 10) |
+|------|-------------------------------|
+| challenger | edge case cited; failure mode named; concurrency/race considered; input boundary tested |
+| architect | coupling named; layer boundary stated; dependency direction explicit; interface contract mentioned |
+| subtractor | unnecessary abstraction flagged; YAGNI applied; premature generalization challenged; scope creep identified |
+
+`score_lens_antislop(lens, checklist_hits: dict[str, bool]) -> int` — count `True` × 2.5, round to int, clamp 0–10. Agent-reported score must be ≤ rubric ceiling or lib clamps down.
+
+**Aggregate**: **`compute_anti_slop_aggregate(lens_scores) -> min(lens_scores)`** — stable for **US-0108**.
+
+**Rework orchestration** (`/auto` post-phase hook):
+1. After `/sovereign-critic`, compute aggregate.
+2. If aggregate **< `CROSS_MODEL_ANTISLOP_THRESHOLD`** and `blocking` findings exist:
+   - Increment `rework_generation` for `(orchestrator_run_id, phase_id)`.
+   - If `rework_generation < CROSS_MODEL_REWORK_MAX`: re-spawn producer phase (fresh context per **US-0023**); pass critic summary as read-only input → reason **`CROSS_MODEL_ANTISLOP_FAIL`** (rework, not terminal).
+   - Else → **`CROSS_MODEL_REWORK_CAP_EXHAUSTED`** decision gate (operator waive or abort).
+
+**`dev_to_qa.md` evidence tuple extension** (additive when `CROSS_MODEL_REVIEW=1`):
+
+```json
+{
+  "critic_evidence": {
+    "producer_model_id": "...",
+    "critic_model_id": "...",
+    "anti_slop_aggregate": 7,
+    "rework_generation": 0,
+    "degraded_mode": false,
+    "findings_path": "handoffs/sovereign_critic_findings.jsonl"
+  }
+}
+```
+
+### §7 — Isolation evidence `model_id` v2 extension (AC-4)
+
+**Additive** field on **US-0048** evidence tuple (base five fields unchanged):
+
+| Field | When required |
+|-------|---------------|
+| **`model_id`** | Required on **both** producer and critic isolation entries when `CROSS_MODEL_REVIEW=1`; omitted when `0` |
+
+Fail-closed **`ISOLATION_EVIDENCE_MODEL_ID_MISSING`** when critic enabled and `model_id` absent on any in-scope isolation row for the phase pair.
+
+Regression: **`test_us0104_us0048_compose_no_base_schema_change`** — US-0048 base schema literals unchanged.
+
+### §8 — Helper library contract (AC-5)
+
+**Script**: **`scripts/sovereign_critic_lib.py`** (+ **`template/scripts/`** mirror).
+
+| Function | Purpose |
+|----------|---------|
+| **`is_cross_model_review_enabled(scratchpad) -> bool`** | `CROSS_MODEL_REVIEW=1` |
+| **`select_critic_model(producer_model_id, scratchpad, phase_id) -> SelectCriticResult`** | §5 algorithm |
+| **`compute_issue_key(finding_text) -> str`** | §4 normalization |
+| **`reconcile_findings(raw_findings) -> ReconciliationResult`** | §3 jury merge |
+| **`compute_anti_slop_aggregate(lens_scores) -> int`** | `min(lens_scores)` |
+| **`score_lens_antislop(lens, checklist_hits) -> int`** | §6 rubric |
+| **`append_finding(path, entry) -> (bool, reason_code\|None)`** | Append-only JSONL + fsync |
+| **`read_open_blocking(repo) -> list[dict]`** | Open `blocking=true` findings |
+| **`resolve_finding(path, finding_id, status) -> bool`** | Patch status to `resolved`/`waived` |
+| **`build_qa_cross_reviewer_block(repo) -> dict`** | `cross_reviewer_findings` for `qa-findings.md` |
+| **`patch_ledger_cross_model_reviewed(...)`** | **US-0103** `build_new_entry(..., cross_model_reviewed=True)` when ledger enabled |
+| **`schema_check(entry) -> (bool, error\|None)`** | 15-field v1 validation |
+| **`self_test() -> bool`** | `[SOVEREIGN_CRITIC_SELF_TEST_OK]` |
+
+Research stub ships schemas + self-test; full spawn orchestration deferred to execute tranche C.
+
+### §9 — Validator CLI contract (AC-8)
+
+**Script**: **`scripts/sovereign_critic_validate.py`** (+ template mirror).
+
+| CLI flag | Purpose |
+|----------|---------|
+| **`--file <path>`** | Validate single JSONL file |
+| **`--repo <root>`** | Validate `handoffs/sovereign_critic_findings.jsonl` if present |
+| **`--self-test`** | Library contract self-test |
+| **`--enforce`** | Non-zero exit on fail-closed code |
+| **`--open-blocking`** | List open blocking findings (stdout JSON) |
+
+Output on success: **`[SOVEREIGN_CRITIC_VALIDATION_OK]`**.
+
+### §10 — `/sovereign-critic` command (AC-2)
+
+**Path**: **`.cursor/commands/sovereign-critic.md`** (+ template mirror).
+
+Invoked by **`/auto`** orchestrator **after** producer phase when `CROSS_MODEL_REVIEW=1`. Spawns fresh critic subagent per **US-0048** / **US-0023**. Inputs: `phase_id`, `role`, `evidence_ref`, `producer_model_id`, artifact digest. Outputs: append findings JSONL + optional `cross_reviewer_findings` in sprint `qa-findings.md`.
+
+### §11 — Reason code inventory (AC-8)
+
+| Code | Blocking? | Surface |
+|------|-----------|---------|
+| **`CROSS_MODEL_REVIEW_DISABLED`** | no (info) | scratchpad gate off |
+| **`CROSS_MODEL_CRITIC_SPAWN_FAILED`** | yes | orchestrator hook |
+| **`CROSS_MODEL_MODEL_COLLISION`** | no → degraded | same slug resolved |
+| **`CROSS_MODEL_ANTISLOP_FAIL`** | yes (rework) | score below threshold |
+| **`CROSS_MODEL_REWORK_CAP_EXHAUSTED`** | yes (gate) | rework max hit |
+| **`CROSS_MODEL_FINDINGS_INVALID`** | yes | schema validation |
+| **`CROSS_MODEL_RECONCILE_FAILED`** | yes | jury merge error |
+| **`CROSS_MODEL_DEGRADED_MODE`** | no (info) | single-model fallback |
+| **`CROSS_MODEL_CRITIC_MODEL_UNAVAILABLE`** | yes → degraded | catalog miss |
+| **`ISOLATION_EVIDENCE_MODEL_ID_MISSING`** | yes | critic enabled, evidence incomplete |
+
+### §12 — Contract tests + parity (AC-8)
+
+Eight **`test_us0104_*`** markers in **`tests/us0104_contract_test.py`**:
+
+1. `test_us0104_scratchpad_keys_literals`
+2. `test_us0104_sovereign_critic_command_literals`
+3. `test_us0104_three_lens_enum_contract`
+4. `test_us0104_findings_jsonl_schema_contract`
+5. `test_us0104_reconciliation_agreement_branches`
+6. `test_us0104_model_id_isolation_evidence_extension`
+7. `test_us0104_antislop_rework_cap_literals`
+8. `test_us0104_degraded_fallback_zero_overhead`
+
+Compose regression guards:
+- `test_us0104_us0048_compose_no_base_schema_change`
+- `test_us0104_us0110_critic_path_unchanged`
+
+**`SOVEREIGN_CRITIC_PAIRS`** for `check_intake_template_parity.py --scope=sovereign-critic`:
+- `scripts/sovereign_critic_lib.py` ↔ `template/scripts/sovereign_critic_lib.py`
+- `scripts/sovereign_critic_validate.py` ↔ `template/scripts/sovereign_critic_validate.py`
+- `.cursor/commands/sovereign-critic.md` ↔ `template/.cursor/commands/sovereign-critic.md`
+- `.cursor/scratchpad.md` ↔ `template/.cursor/scratchpad.md` (`CROSS_MODEL_*` block)
+- `decisions/DEC-0104.md` ↔ `template/decisions/DEC-0104.md`
+
+### §13 — Composition rules
+
+| Story | Compose rule |
+|-------|--------------|
+| **US-0048** | Base isolation tuple unchanged; `model_id` additive v2 only. |
+| **US-0069** | Phase→role matrix unchanged; critic spawned by orchestrator command, not new canonical phase role. |
+| **US-0023** | Fresh-context semantics unchanged; rework re-spawn uses fresh marker. |
+| **US-0110** | `CRITIC_PATH` / conjunct-3 degrade matrix unchanged; US-0104 populates artifact. |
+| **US-0103** | `cross_model_reviewed` field already in 12-field v1; no ledger schema change. |
+| **US-0101** / **US-0102** | Model resolution read-only via `model_tier_lib`; no precedence chain amendment. |
+| **US-0108** | Consumes stable `min(lens_scores)` aggregate — do not change formula without coordinated DEC. |
+| **US-0045** | US-0104 remains **OPEN** until release closure. |
+
+### §14 — Risks
+
+| Risk | Mitigation |
+|------|------------|
+| **R1** Model routing unreliable (**R-0088**) | Deterministic degraded fallback §5 |
+| **R2** Phase latency / token cost | Default-off `CROSS_MODEL_REVIEW=0` |
+| **R3** Rework oscillation | `CROSS_MODEL_REWORK_MAX` + decision gate §6 |
+| **R4** Anti-slop subjectivity | Deterministic checklist rubric §6 |
+| **R5** Jury dedup drift | Stable `issue_key` algorithm §4 |
+| **R6** **US-0108** aggregate coupling | Frozen `min(lens_scores)` formula |
+
+### §15 — Implementation tranche order
+
+1. **Tranche A** — scratchpad keys + reason codes + `DEC-0104` template mirror
+2. **Tranche B** — **`scripts/sovereign_critic_lib.py`** full API + self-test
+3. **Tranche C** — **`scripts/sovereign_critic_validate.py`** + `/sovereign-critic` command
+4. **Tranche D** — `/auto` post-phase hook + rework loop + `dev_to_qa.md` tuple
+5. **Tranche E** — isolation `model_id` v2 + ledger hook + eight `test_us0104_*` + parity + architecture `# US-0104`
+
+## References
+
+- `docs/engineering/research.md` — **`R-0092`**
+- `docs/product/backlog.md` — **`## US-0104`**
+- `handoffs/intake_evidence/intake-sovereign-20260627-01.json`
+- `scripts/sovereign_convergence_lib.py` — **`CRITIC_PATH`**
+- `scripts/decision_ledger_lib.py` — **`cross_model_reviewed`**
+- `scripts/model_tier_lib.py` — model resolution (read-only)