its-magic 0.1.3-1 → 0.1.3-2

package/template/decisions/DEC-0107.md

@@ -0,0 +1,246 @@
+# DEC-0107: Sovereign Loop Mode (US-0107)
+
+- **Date**: 2026-06-29
+- **Status**: Accepted
+- **Story**: `US-0107`
+- **Composes on**: **US-0088** (quiet mode), **US-0092** (full-autonomy outer driver), **US-0095** (native-chain segments), **US-0044** (backlog drain), **US-0103** (decision ledger), **US-0105** (sovereign memory), **US-0110** (goal convergence) — **do not amend**; US-0107 **layers** orchestration only
+- **Related**: `R-0094` (research anchor), **US-0109** (deploy smoke — downstream deferral writer), **US-0069** (spawn-only), **US-0045** (status authority), **US-0017** (template parity)
+- **Supersedes**: none
+- **Default-off**: `AUTO_SOVEREIGN=0` — zero overhead when off
+
+## Context
+
+Project-level autonomous delivery orchestration for the sovereign-loop batch. When operators enable **`AUTO_SOVEREIGN`**, the outer driver owns **deferral register**, **drain-generate** (PO proposals when backlog empty but not converged), **notification dispatch** on terminal events, and **convergence hooks** via **US-0110**. **US-0088 / US-0092 / US-0095 / US-0044 / US-0103 / US-0105 / US-0110 are UNCHANGED** — US-0107 adds scratchpad keys, JSONL deferral register, loop lib API, sidecar run-state, and compose hooks only.
+
+Research basis: `R-0094` Q1–Q7 closed.
+
+## Decision
+
+### §1 — Scratchpad keys + goal-mode coupling (AC-1)
+
+| Key | Values | Default | Notes |
+|-----|--------|---------|-------|
+| **`AUTO_SOVEREIGN`** | **`0`** \| **`1`** | **`0`** | When `0`, zero overhead — no deferral reads/writes, no advance, no notifications. |
+| **`AUTO_SOVEREIGN_DEFERRAL_MAX`** | int ≥ **1** | **`50`** | Max open deferral rows; append rejected at cap. |
+| **`AUTO_SOVEREIGN_DRAIN_GENERATE_MAX`** | int ≥ **0** | **`3`** | Max drain-generate PO iterations per `orchestrator_run_id`. |
+| **`AUTO_SOVEREIGN_DEFERRAL_POLICY`** | **`stop`** \| **`skip`** \| **`resolve_first`** | **`resolve_first`** | How open deferrals gate advance. |
+| **`SOVEREIGN_NOTIFY_TARGET`** | **`off`** \| **`ntfy`** \| **`email`** \| **`hook`** | **`off`** | Notification adapter selection. |
+| **`SOVEREIGN_NOTIFY_NTFY_TOPIC`** | string | *(empty)* | ntfy topic — **local-only** value. |
+| **`SOVEREIGN_NOTIFY_NTFY_BASE`** | URL | *(empty)* | Optional ntfy base URL override — **local-only**. |
+| **`SOVEREIGN_NOTIFY_HOOK_URL`** | URL | *(empty)* | Webhook POST target — **local-only**. |
+| **`SOVEREIGN_NOTIFY_EMAIL_TO`** | email | *(empty)* | Email v1 deferred — **local-only** name. |
+
+Published in **`.cursor/scratchpad.md`** (+ **`template/.cursor/scratchpad.md`** byte-parity per **US-0017**). Config key **names** in committed scratchpad; **values** in `.cursor/scratchpad.local.md` or env vars only.
+
+**Goal-mode coupling (fail-closed)**: `is_sovereign_loop_enabled(scratchpad)` requires **`AUTO_SOVEREIGN=1` AND `SOVEREIGN_GOAL_MODE=goal_convergence`** (via `is_goal_convergence_enabled()` from **US-0110**). When sovereign flag on but goal mode `phase_driven` → `advance_sovereign_loop` returns `action=blocked`, `reason_code=SOVEREIGN_LOOP_GOAL_MODE_REQUIRED` **before** convergence eval.
+
+**Rejected**: auto-enable `goal_convergence` when `AUTO_SOVEREIGN=1` — silently changes terminal semantics without operator intent (**R1**).
+**Rejected**: sovereign loop without goal mode — undefined terminal condition.
+
+**Operator recipe**: set both `AUTO_SOVEREIGN=1` and `SOVEREIGN_GOAL_MODE=goal_convergence` in `.cursor/scratchpad.local.md`.
+
+### §2 — Deferral register JSONL v1 (AC-2)
+
+**Path**: **`handoffs/sovereign_deferrals.jsonl`** (+ template **`handoffs/sovereign_deferrals/`** `.gitkeep` only).
+
+**Bootstrap**: **create-on-first-write**; ship **`.gitkeep`** — no empty tracked JSONL seed.
+
+**Required fields** (each JSONL line):
+
+| Field | Type | Notes |
+|-------|------|-------|
+| **`schema_version`** | int | **`1`** |
+| **`deferral_id`** | UUIDv4 | Stable id across lifecycle rows |
+| **`ts`** | ISO 8601 UTC | Sortable timestamp |
+| **`reason_code`** | string | Orchestrator reason (e.g. `DEPLOY_DEFERRED`, `BLOCK_RETRY_CAP_EXHAUSTED`) |
+| **`work_item_kind`** | enum | **`story`** \| **`bug`** \| **`deploy`** \| **`block`** |
+| **`work_item_ref`** | string | Max **128** chars — `US-xxxx`, `BUG-xxxx`, deploy target, phase token |
+| **`state`** | enum | **`open`** \| **`resolved`** \| **`superseded`** |
+| **`source_orchestrator_run_id`** | string | Non-empty provenance |
+| **`remediation_hint`** | string | Non-empty, max **512** chars |
+
+**Optional fields**: `blocked_by_phase` (canonical phase id), `retry_count` (int ≥ 0), `ledger_decision_id` (UUID — **US-0103** provenance only; no ledger schema change).
+
+**Lifecycle (append-only)**: `append_deferral` writes `state=open`; `resolve_deferral(deferral_id)` appends new row with same `deferral_id`, `state=resolved`, fresh `ts`; supersede uses `state=superseded`. **Latest-state-wins** per `deferral_id` when computing open set.
+
+**Open-row cap**: reject append when `len(list_open_deferrals()) >= AUTO_SOVEREIGN_DEFERRAL_MAX` → **`SOVEREIGN_DEFERRAL_CAP_EXCEEDED`**.
+
+**Secret scan**: reject when `remediation_hint` or `work_item_ref` match secret heuristics (mirror **US-0103** / **US-0105**: `api_key=`, PEM, `sk-`, `ghp_`).
+
+**Sidecar run-state**: **`handoffs/sovereign_loop_state.json`** v1 — per-`orchestrator_run_id` drain-generate iteration counter (not git-tracked content in template; schema documented only).
+
+**Rejected**: in-place mutation of deferral rows (**rejected** — breaks audit trail).
+**Rejected**: empty tracked JSONL seed (**rejected** — create-on-first-write).
+
+### §3 — Validator CLI (AC-2, AC-7)
+
+**Script**: **`scripts/sovereign_loop_validate.py`** (+ template mirror).
+
+| Flag | Purpose |
+|------|---------|
+| **`--file`** | Validate single JSONL file |
+| **`--repo`** | Validate repo deferrals path |
+| **`--self-test`** | Contract self-test |
+| **`--enforce`** | Fail-closed exit on first invalid line |
+
+Exit **0/1/2** mirrors **DEC-0103** / **DEC-0105**. Success token: **`[SOVEREIGN_LOOP_VALIDATION_OK]`**.
+
+Lib helper: `schema_check_deferral(entry) -> (bool, error|None)`.
+
+### §4 — Helper library API (AC-3)
+
+**Script**: **`scripts/sovereign_loop_lib.py`** (+ template mirror). Research stub ships schemas, gates, dataclasses + self-test (`[SOVEREIGN_LOOP_SELF_TEST_OK]`); advance/dispatch bodies finalized at execute tranche B.
+
+**`SovereignLoopStepResult` v1** fields: `schema_version=1`, `action` ∈ {`noop`,`continue`,`defer`,`drain_generate`,`terminal_converged`,`terminal_timeout`,`terminal_cap`,`blocked`}, optional `reason_code`, optional `stop_reason` (native-chain breadcrumb), `orchestrator_run_id`, `evaluated_at` (ISO UTC), optional `deferral_id`, optional `drain_generate_bundle`, optional `notification_dispatched` (bool), optional `convergence` (embedded **US-0110** `ConvergenceResult.to_dict()` snapshot).
+
+| Function | Purpose |
+|----------|---------|
+| **`is_sovereign_loop_enabled(scratchpad) -> bool`** | `AUTO_SOVEREIGN=1` **and** `is_goal_convergence_enabled(scratchpad)` |
+| **`resolve_deferrals_path(repo_root) -> Path`** | `handoffs/sovereign_deferrals.jsonl` |
+| **`schema_check_deferral(entry) -> (bool, error\|None)`** | v1 field validation + secret scan |
+| **`list_open_deferrals(repo, *, scratchpad) -> (rows, reason\|None)`** | Latest-state-wins open rows; empty when disabled |
+| **`append_deferral(repo, scratchpad, *, fields...) -> (deferral_id\|None, reason\|None)`** | Append-only + cap enforcement |
+| **`resolve_deferral(repo, deferral_id, *, orchestrator_run_id) -> (ok, reason\|None)`** | Append resolved row |
+| **`count_drain_generate_iterations(repo, orchestrator_run_id) -> int`** | Per-run counter from sidecar |
+| **`advance_sovereign_loop(repo, scratchpad, *, orchestrator_run_id, iteration=None) -> SovereignLoopStepResult`** | Main orchestrator advance — §5 |
+| **`build_drain_generate_spawn_inputs(repo, scratchpad, convergence) -> dict`** | Vision narrow-read + optional memory digest |
+| **`dispatch_notification(scratchpad, event_type, payload) -> (ok, reason\|None)`** | Fail-open adapters — §7 |
+| **`self_test() -> bool`** | **`[SOVEREIGN_LOOP_SELF_TEST_OK]`** |
+
+### §5 — `advance_sovereign_loop` algorithm (AC-3)
+
+1. If `AUTO_SOVEREIGN≠1` → `action=noop` (zero overhead; do not import convergence).
+2. If `SOVEREIGN_GOAL_MODE≠goal_convergence` → `action=blocked`, `reason_code=SOVEREIGN_LOOP_GOAL_MODE_REQUIRED`.
+3. `result = evaluate_convergence(repo, scratchpad, orchestrator_run_id=...)`.
+4. If `result.converged` → `action=terminal_converged` + `dispatch_notification(convergence)` + sovereign terminal stop **`converged`**.
+5. If `check_timeout(scratchpad, iteration)` → `action=terminal_timeout` + `write_partial_delivery_report` (**US-0110**) + notification.
+6. Apply **`AUTO_SOVEREIGN_DEFERRAL_POLICY`**: `stop` → block advance when open deferrals; `skip` → informational only; `resolve_first` → block until open deferrals empty (default).
+7. If backlog has OPEN stories → `action=continue` (delegate to native **US-0044** drain — no bypass).
+8. If OPEN stories **0** and `not result.converged` and iterations `< AUTO_SOVEREIGN_DRAIN_GENERATE_MAX` → `action=drain_generate` + spawn bundle (§6).
+9. Else cap/terminal paths → `SOVEREIGN_DRAIN_GENERATE_CAP` or deferral cap + notification.
+
+**Sovereign terminal stops** (additive to **US-0088**/**US-0092** matrix): `converged`, `SOVEREIGN_GOAL_TIMEOUT`, `SOVEREIGN_DEFERRAL_CAP_EXCEEDED`, `SOVEREIGN_DRAIN_GENERATE_CAP` — do **not** replace `decision_gate`, `loop_max`, `security deny`, or `BLOCK_RETRY_CAP_EXHAUSTED`.
+
+**`drain_terminated`**: set only on sovereign terminal stops — **not** on OPEN-story exhaustion alone (**R5**).
+
+### §6 — Drain-generate contract (AC-4)
+
+**Trigger** (all required): `is_sovereign_loop_enabled`, backlog OPEN story count **0**, `evaluate_convergence(...).converged=false`, drain-generate iterations `< AUTO_SOVEREIGN_DRAIN_GENERATE_MAX`, no blocking deferral policy conflict.
+
+**Spawn surface**: **`/auto`** outer driver spawns fresh **PO** subagent (spawn-only per **US-0095** / **US-0069**) with ephemeral work item id `drain-gen-{orchestrator_run_id}-{iteration}` — **not** a backlog row until accepted.
+
+**PO inputs** (`build_drain_generate_spawn_inputs`): narrow-read `docs/product/vision.md` (exclude Discovery/Intake note sections — same skip rules as **US-0110** goal derive); optional `sovereign_memory_digest` when **`SOVEREIGN_MEMORY=1`** via `build_injection_digest_block()` only; attach `unmet_conditions[]`, `blocked_by[]`, `goal_text` from convergence eval.
+
+**`DrainGenerateCandidateBundle` v1** (ephemeral — **not persisted** pre-gate): `schema_version=1`, `orchestrator_run_id`, `iteration`, `generated_at`, `candidates[]` (max **3** per iteration) each with `candidate_id` (UUIDv4), `title` (max **120**), `summary` (max **512**), `ac_sketch` (string[], max **8** items × **256** chars), optional `plan_area_id`, `priority` (default **`P2`**), `provenance` ∈ {`vision`,`memory`,`both`}.
+
+**Decision gate (mandatory per candidate)**: PO output → standard **`decision_gate`** in **`/auto`** — operator accept → **`/intake`** or controlled backlog append; reject → discard candidate. **Rejected**: auto-append without gate — violates **US-0092** hard gates (**R2**).
+
+**Cap exhausted**: `SOVEREIGN_DRAIN_GENERATE_CAP` sovereign terminal + optional `dispatch_notification(drain_generate_cap)`.
+
+### §7 — Notification adapters (AC-5)
+
+**`SOVEREIGN_NOTIFY_TARGET`**: `off` (zero overhead) \| `ntfy` \| `hook` \| `email`.
+
+**Event types**: `convergence`, `timeout`, `deferral_cap`, `drain_generate_cap`.
+
+**Payload envelope v1**: `{schema_version, event_type, ts, orchestrator_run_id, reason_code, unmet_conditions[], blocked_by[], goal_progress}` where `goal_progress` embeds **US-0110** block when available.
+
+**ntfy v1**: stdlib `urllib.request` POST plain-text body to `{SOVEREIGN_NOTIFY_NTFY_BASE or https://ntfy.sh}/{SOVEREIGN_NOTIFY_NTFY_TOPIC}`; headers `Title`, `Priority` (4 for cap/timeout, 3 for convergence), `Tags: sovereign,auto`; timeout **10s**.
+
+**hook v1**: POST `application/json` to `SOVEREIGN_NOTIFY_HOOK_URL` with payload envelope; timeout **10s**.
+
+**email v1**: **deferred** — `dispatch_notification` returns `(False, SOVEREIGN_NOTIFY_TARGET_INVALID)` with info log; runbook documents v1.1 SMTP stub. **Rejected**: stdlib SMTP in v1 (credential handling + deliverability risk).
+
+**Fail-open**: any adapter exception → log **`SOVEREIGN_NOTIFY_DISPATCH_FAILED`**, return `(True, None)` — notification must not block loop.
+
+**Secret handling (R4)**: topic/URL values local-only; never write into git-tracked handoffs or JSONL.
+
+### §8 — US-0109 integration declaration (AC-6)
+
+**US-0109** implements post-deploy smoke + bounded repair. On cap exhaustion writes **`DEPLOY_DEFERRED`** row to **`sovereign_deferrals.jsonl`** using §2 schema (`work_item_kind=deploy`). **US-0107** owns register schema, validator, read paths, and documents integration contract — **no** deploy smoke logic in US-0107 scope.
+
+**`DEPLOY_DEFERRED`**: reserved reason_code for **US-0109** writer; non-blocking deferral row (not advance-block by itself unless policy applies).
+
+### §9 — Reason code inventory (AC-8)
+
+| Code | Blocking? | Surface |
+|------|-----------|---------|
+| **`SOVEREIGN_LOOP_DISABLED`** | no (info) | `AUTO_SOVEREIGN=0` zero overhead |
+| **`SOVEREIGN_LOOP_GOAL_MODE_REQUIRED`** | yes | sovereign on without `goal_convergence` |
+| **`SOVEREIGN_DEFERRAL_CAP_EXCEEDED`** | yes | append cap / sovereign terminal |
+| **`SOVEREIGN_DEFERRAL_SCHEMA_INVALID`** | yes | validator / append |
+| **`SOVEREIGN_DEFERRAL_APPEND_FAILED`** | yes | I/O |
+| **`SOVEREIGN_DRAIN_GENERATE_CAP`** | yes | drain-generate iterations exhausted |
+| **`SOVEREIGN_DRAIN_GENERATE_BLOCKED`** | yes | policy/deferral gate blocks spawn |
+| **`SOVEREIGN_NOTIFY_DISPATCH_FAILED`** | no (fail-open log) | adapter errors |
+| **`SOVEREIGN_NOTIFY_TARGET_INVALID`** | no | unknown target / email v1 defer |
+| **`SOVEREIGN_NOTIFY_CONFIG_MISSING`** | no (skip notify) | target on but config absent |
+| **`SOVEREIGN_LOOP_ADVANCE_BLOCKED`** | yes | deferral policy `stop`/`resolve_first` |
+| **`DEPLOY_DEFERRED`** | no (deferral row) | **US-0109** writer (integration) |
+
+### §10 — Contract tests + parity (AC-7, AC-8)
+
+Eight **`test_us0107_*`** markers in **`tests/us0107_contract_test.py`**:
+
+1. `test_us0107_scratchpad_keys_literals`
+2. `test_us0107_deferral_jsonl_schema_contract`
+3. `test_us0107_advance_deferral_policy_literals`
+4. `test_us0107_drain_generate_gate_contract`
+5. `test_us0107_notification_fail_open_literals`
+6. `test_us0107_goal_mode_coupling_fail_closed`
+7. `test_us0107_zero_overhead_default`
+8. `test_us0107_compose_no_stop_matrix_change`
+
+Compose regression guards (AC-8):
+
+- `test_us0107_us0110_convergence_import_contract`
+- `test_us0107_us0095_spawn_only_regression_guard`
+
+**`SOVEREIGN_LOOP_PAIRS`** for `check_intake_template_parity.py --scope=sovereign-loop`:
+
+- `scripts/sovereign_loop_lib.py` ↔ `template/scripts/sovereign_loop_lib.py`
+- `scripts/sovereign_loop_validate.py` ↔ `template/scripts/sovereign_loop_validate.py`
+- `.cursor/scratchpad.md` ↔ `template/.cursor/scratchpad.md` (`AUTO_SOVEREIGN_*` + `SOVEREIGN_NOTIFY_*` block)
+- `handoffs/sovereign_deferrals/.gitkeep` ↔ `template/handoffs/sovereign_deferrals/.gitkeep`
+- `decisions/DEC-0107.md` ↔ `template/decisions/DEC-0107.md`
+- `scripts/check_intake_template_parity.py` ↔ `template/scripts/check_intake_template_parity.py` (scope registration)
+
+### §11 — Composition rules
+
+| Story | Compose rule |
+|-------|--------------|
+| **US-0088** / **US-0092** / **US-0095** | Stop matrix, spawn-only, native chain **unchanged**; sovereign terminal stops additive only. |
+| **US-0044** / **US-0087** | Drain mutex unchanged; sovereign advance consults deferrals before story selection. |
+| **US-0103** | Optional deferral provenance via `ledger_decision_id`; ledger schema unchanged. |
+| **US-0105** | Drain-generate reads `build_injection_digest_block()` only when `SOVEREIGN_MEMORY=1`. |
+| **US-0110** | Import `evaluate_convergence`, `is_goal_convergence_enabled`, `build_goal_progress_block`, `check_timeout`, `write_partial_delivery_report`; export `list_open_deferrals()` for `zero_deferrals` conjunct wiring — **do not amend** five-conjunct set or **DEC-0110**. |
+| **US-0109** | Downstream `DEPLOY_DEFERRED` writer — schema stable in US-0107 first (**R6**). |
+| **US-0069** | Spawn-only PO for drain-generate — no in-chat chain bypass. |
+| **US-0045** | US-0107 remains **OPEN** until release closure. |
+
+### §12 — Risks
+
+| Risk | Mitigation |
+|------|------------|
+| **R1** Goal-mode coupling | Fail-closed **`SOVEREIGN_LOOP_GOAL_MODE_REQUIRED`**; operator recipe in runbook §1 |
+| **R2** Drain-generate scope creep | Max **3** candidates/iteration + mandatory decision gate per candidate §6 |
+| **R3** Deferral cap vs **`CONVERGENCE_DEFERRALS_PENDING`** | Shared `list_open_deferrals()` latest-state-wins; cap blocks append, open rows block convergence |
+| **R4** Notification secrets | Local-only config; payload excludes hook URLs/topics |
+| **R5** Sovereign terminal vs **US-0095** segments | Terminal stops additive post-segment eval; `drain_terminated` only on sovereign terminal |
+| **R6** **US-0109** ordering | Deferral v1 schema + validator stable in US-0107; **`DEPLOY_DEFERRED`** reserved |
+
+### §13 — Implementation tranche order
+
+1. **Tranche A** — scratchpad keys + reason codes + `DEC-0107` template mirror + deferrals `.gitkeep`
+2. **Tranche B** — **`sovereign_loop_lib.py`** deferral CRUD + `list_open_deferrals` + self-test core
+3. **Tranche C** — **`advance_sovereign_loop`** + **`sovereign_loop_validate.py`** + sidecar run-state
+4. **Tranche D** — drain-generate spawn inputs + notification adapters + **`/auto`** advance wiring + **US-0110** `zero_deferrals` compose
+5. **Tranche E** — eight `test_us0107_*` + compose guards + **`SOVEREIGN_LOOP_PAIRS`** parity + runbook + architecture `# US-0107`
+
+## References
+
+- `docs/engineering/research.md` — **`R-0094`**
+- `docs/product/backlog.md` — **`## US-0107`**
+- `handoffs/intake_evidence/intake-sovereign-20260627-01.json`
+- `scripts/sovereign_loop_lib.py` — research stub + self-test
+- Shipped compose: `scripts/sovereign_convergence_lib.py` (**US-0110**), `scripts/sovereign_memory_lib.py` (**US-0105**), `scripts/decision_ledger_lib.py` (**US-0103**)

package/template/docs/engineering/architecture.md

@@ -7,3 +7,81 @@
 ## Risks
 
 ## Decisions
+
+# US-0112 — Model-catalog example preset delivery
+
+**Story**: US-0112 (Ship model-catalog example presets on install/upgrade)
+**Decision**: DEC-0112 (Accepted)
+**Research anchor**: R-0090 (delivered, Q1–Q8 closed)
+
+## Framework vs operator boundary
+
+The 8 `model-catalog.local.example*.json` presets are **framework files** under installer manifest control. They ship on install/upgrade and are refreshed when stale (same semantics as `scratchpad.local.example.md` per US-0075/US-0018/US-0057).
+
+The active operator-owned `.cursor/model-catalog.local.json` is **gitignored**, outside `install_include_paths` and `clean_paths`, and never touched by any installer mode. This is a DEC-0086/DEC-0087 boundary — US-0112 completes delivery of existing presets without altering catalog schema (US-0101) or role precedence (US-0102).
+
+## Manifest rows (8 paths)
+
+Under `[install_include_paths]` in both `docs/engineering/context/installer-owned-paths.manifest` and `template/docs/engineering/context/installer-owned-paths.manifest` (16 rows total, byte-parity):
+
+1. `.cursor/model-catalog.local.example.json`
+2. `.cursor/model-catalog.local.example.cursor-only.json`
+3. `.cursor/model-catalog.local.example.level-1-easy.json`
+4. `.cursor/model-catalog.local.example.level-2-complex.json`
+5. `.cursor/model-catalog.local.example.level-3-mega.json`
+6. `.cursor/model-catalog.local.example.level-4-super.json`
+7. `.cursor/model-catalog.local.example.role-based-balanced.json`
+8. `.cursor/model-catalog.local.example.role-based-highend.json`
+
+## Upgrade classification (framework files)
+
+- **Missing mode**: copies all 8 examples when absent; no-op when present; deterministic log/status per file.
+- **Upgrade mode**: refreshes stale framework files (template content differs); skips byte-identical files; never touches `.cursor/model-catalog.local.json`.
+- **Triple installer parity**: `installer.py`, `installer.ps1`, `installer.sh` all classify `.cursor/model-catalog.local.example*.json` as `framework` via explicit enumeration in `FRAMEWORK_EXACT` (Python) / `$frameworkExact` (PowerShell) / case pattern (Bash).
+
+## DEC-0086 / DEC-0087 compose
+
+US-0112 does **not** amend:
+- US-0101 (catalog schema, DEC-0086)
+- US-0102 (role catalog precedence, DEC-0087)
+- US-0054 (publish confirmation gates)
+- US-0057 (example-first refresh)
+- US-0075 (scratchpad example-first)
+
+US-0112 only extends the installer manifest to include the 8 example presets as framework files, completing DEC-0086/DEC-0087 delivery path.
+
+## Active catalog protection invariant
+
+`.cursor/model-catalog.local.json` is:
+- Gitignored (not tracked)
+- Outside `install_include_paths` (not manifest-copied)
+- Outside `clean_paths` (not manifest-cleaned)
+- Never auto-populated by any installer mode
+- Operator-owned; installer respects DEC-0086/DEC-0087 ownership boundary
+
+## Test markers (8+)
+
+`tests/us0112_contract_test.py` provides:
+- `test_us0112_manifest_lists_eight_paths` (active + template)
+- `test_us0112_missing_mode_adds_absent_framework_files` (Python/PS1/Bash)
+- `test_us0112_upgrade_mode_refreshes_stale_framework_files`
+- `test_us0112_upgrade_mode_preserves_unchanged_files`
+- `test_us0112_upgrade_mode_never_touches_local_catalog`
+- `test_us0112_active_catalog_protection_invariant`
+- `test_us0112_parity_scope_model_catalog_examples`
+- `test_us0112_runbook_lists_eight_preset_literals`
+
+## Parity scope
+
+`scripts/check_intake_template_parity.py --scope=model-catalog-examples` validates active vs template byte-parity for the manifest rows (16 rows total). Constant: `MODEL_CATALOG_EXAMPLE_PAIRS` includes the manifest pair.
+
+## Reason codes
+
+- `MODEL_CATALOG_EXAMPLE_PARITY_SCOPE_OK`
+- `MODEL_CATALOG_EXAMPLE_PARITY_SCOPE_MISMATCH`
+
+## Compose guards (non-negotiable)
+
+DO NOT amend: US-0008, US-0018, US-0040, US-0054, US-0057, US-0075, US-0100, US-0101, US-0102, US-0103, US-0107, US-0110.
+
+US-0112 is additive only — extends manifest + installer classification; no schema/precedence changes.

package/template/docs/engineering/auto-orchestration-reference.md

@@ -1126,6 +1126,13 @@ when stack cannot be resolved. Connect block fields align with
      `AUTO_ROLE_REFRESH_CONTEXT`), enforce execute default deny / override
      contract, and run the preflight capability gate; on failure stop with
      `PHASE_ROLE_CAPABILITY_MISSING` (no unrelated-role spawn).
+   - **US-0105 / DEC-0105**: When `SOVEREIGN_MEMORY=1`, after phase-context
+     narrow-read and **before** role instructions, append read-only
+     **`sovereign_memory_digest`** block assembled via
+     `build_injection_digest_block(...)` from `scripts/sovereign_memory_lib.py`
+     (bounded top-N/top-K merge; char cap `SOVEREIGN_MEMORY_MAX_CHARS`). When
+     `SOVEREIGN_MEMORY=0` (default), skip with zero overhead — **US-0023**
+     fresh-context boundary unchanged.
    - **US-0069 / DEC-0051**: After each phase completes, validate isolation
      `role` and strict-proof `role` against the preflight-resolved expected
      role; on conflict stop with `PHASE_ROLE_MISMATCH`.

package/template/docs/engineering/context/installer-owned-paths.manifest

@@ -14,6 +14,14 @@
 .cursor/hooks
 .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
 docs
 sprints
 handoffs