its-magic 0.1.3-0 → 0.1.3-2

package/template/decisions/DEC-0105.md

@@ -0,0 +1,231 @@
+# DEC-0105: Sovereign Memory (US-0105)
+
+- **Date**: 2026-06-29
+- **Status**: Accepted
+- **Story**: `US-0105`
+- **Composes on**: **US-0029** (external research — do not amend), **US-0080** / **DEC-0062** (token-cost — lib-side digest only), **US-0103** (per-run ledger — optional promotion), **US-0072** / **DEC-0054** (triad — sovereign-memory explicitly excluded), **US-0096** (lean memory layers — distinct cross-run substrate)
+- **Related**: `R-0093` (research anchor), **US-0107** (drain-generate consumer — read API stability), **US-0110** (convergence — orthogonal), **US-0045** (status authority), **US-0017** (template parity)
+- **Supersedes**: none
+- **Default-off**: `SOVEREIGN_MEMORY=0` — zero overhead when off
+
+## Context
+
+Project-level institutional memory for the sovereign-loop batch. Cross-run learnings (decisions, mistakes, patterns, plan drift) persist in bounded JSONL artifacts under `docs/engineering/sovereign-memory/` and inject into phase spawns as a char-capped digest. **US-0029** / **US-0080** / **US-0103** / **US-0072** / **US-0096 are UNCHANGED** — US-0105 adds a new directory surface, scratchpad keys, lib API, and compose hooks only.
+
+Research basis: `R-0093` Q1–Q7 closed.
+
+## Decision
+
+### §1 — Scratchpad keys (AC-1)
+
+| Key | Values | Default | Notes |
+|-----|--------|---------|-------|
+| **`SOVEREIGN_MEMORY`** | **`0`** \| **`1`** | **`0`** | When `0`, no JSONL writes, no injection reads, no digest assembly — **zero overhead**. |
+| **`SOVEREIGN_MEMORY_TOP_N`** | int ≥ **0** | **`5`** | Global recent pool size (all four JSONL families). |
+| **`SOVEREIGN_MEMORY_TOP_K`** | int ≥ **0** | **`3`** | High-impact pool size (`patterns` + `mistakes` only). |
+| **`SOVEREIGN_MEMORY_MAX_CHARS`** | int ≥ **0** | **`2048`** | Hard cap on assembled `digest_text`. |
+| **`SOVEREIGN_MEMORY_JSONL_MAX_LINES`** | int ≥ **1** | **`500`** | Active JSONL line cap before archive rollover. |
+
+Published in **`.cursor/scratchpad.md`** (+ **`template/.cursor/scratchpad.md`** byte-parity per **US-0017**).
+
+**Lib constant** (not scratchpad): **`SOVEREIGN_MEMORY_READ_TAIL`** default **500** — max tail lines read per file during digest assembly.
+
+**Rejected**: always-on memory (**rejected** — token/latency cost; default-off discipline).
+**Rejected**: empty tracked JSONL seed files (**rejected** — create-on-first-write; ship `.gitkeep` only per **R-0093** Q1).
+**Rejected**: per-file round-robin injection (**rejected** — global time/score merge simpler and more predictable).
+**Rejected**: external memory package dependency (**rejected** — stdlib-only; **R-0093** eml-memory evaluation).
+
+### §2 — Directory surface + bootstrap (AC-2)
+
+**Active path**: **`docs/engineering/sovereign-memory/`** (+ **`template/docs/engineering/sovereign-memory/`** mirror).
+
+| Artifact | Path | Write owner | Injected v1? |
+|----------|------|-------------|--------------|
+| Decisions log | `decisions-log.jsonl` | Curator promotion; explicit phase append | yes |
+| Mistakes | `mistakes.jsonl` | Orchestrator mistake hooks | yes (top-K) |
+| Patterns | `patterns.jsonl` | Phase roles; curator consolidation | yes (top-K) |
+| Plan drift | `plan-drift-register.jsonl` | Plan-fidelity / scope hooks | yes (top-N) |
+| Retrospectives | `retrospectives/<sprint_id>.md` | Curator `/refresh-context` | **no** (human audit) |
+
+**Archive path**: **`docs/engineering/sovereign-memory-archive/<basename>-<YYYYMMDDTHHMMSSZ>.jsonl`** — distinct from **US-0072** triad archives.
+
+**Bootstrap**: **create-on-first-write** for JSONL; ship **`.gitkeep`** + **`retrospectives/.gitkeep`** only — no empty tracked JSONL seeds.
+
+### §3 — JSONL v1 schemas (AC-2)
+
+Four append-only families sharing base fields:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| **`schema_version`** | int | yes | **`1`** |
+| **`ts`** | ISO 8601 UTC | yes | sortable |
+| **`entry_id`** | UUIDv4 | yes | globally unique |
+| **`source_orchestrator_run_id`** | string | no | provenance |
+| **`source_story_id`** | string | no | e.g. `US-0105` |
+| **`phase_id`** | string | no | **DEC-0086** canonical id |
+| **`impact_score`** | int **0..100** | yes | high-impact pool sort key |
+| **`text`** | non-empty string | yes | max **2000** chars |
+| **`tags`** | string[] | yes | max **10** × **40** chars each |
+| **`status`** | enum | yes | `active` \| `superseded` \| `archived` (default **`active`**) |
+| **`provenance_ref`** | string | no | e.g. `R-0093`, `ledger:<decision_id>` |
+
+**Family extensions**:
+
+- **`decisions-log.jsonl`**: `decision_key` (SHA-256 prefix **16** hex), `decision_text`, `rationale` (max **2000** chars).
+- **`mistakes.jsonl`**: `mistake_tag` ∈ {`fix_failed`, `revert_applied`, `plan_fidelity_violation`, `test_regression`, `scope_creep`}, `failure_reason_code`.
+- **`patterns.jsonl`**: `pattern_id` (slug max **64**), `applies_to` (string[]).
+- **`plan-drift-register.jsonl`**: `drift_type` ∈ {`ac_drop`, `ac_reorder`, `scope_add`, `plan_change`, `acceptance_drift`}, `from_artifact`, `to_artifact`; optional `ledger_decision_id`.
+
+**Secret scan**: reject append when `text` / `rationale` / `decision_text` match **`SOVEREIGN_MEMORY_SECRET_DETECTED`** heuristics (mirror **US-0103** `LEDGER_SECRET_DETECTED`: `api_key=`, PEM blocks, `sk-`, `ghp_` prefixes).
+
+**Validator**: **`scripts/sovereign_memory_validate.py`** (+ template mirror) — `--file`, `--repo`, `--family {decisions|mistakes|patterns|plan-drift|all}`, `--self-test`, `--enforce`. Exit **0/1/2** mirrors **DEC-0103** / **DEC-0104**. Success token: **`[SOVEREIGN_MEMORY_VALIDATION_OK]`**.
+
+### §4 — Helper library API (AC-3, AC-5, AC-6)
+
+**Script**: **`scripts/sovereign_memory_lib.py`** (+ template mirror).
+
+| Function | Purpose |
+|----------|---------|
+| `is_sovereign_memory_enabled(scratchpad) -> bool` | `SOVEREIGN_MEMORY=1` gate |
+| `resolve_memory_dir(repo_root) -> Path` | `docs/engineering/sovereign-memory/` |
+| `resolve_jsonl_path(family, repo_root) -> Path` | Per-family JSONL path |
+| `read_entries(family, *, tail_n, active_only=True) -> (list, reason\|None)` | Bounded tail read; **`SOVEREIGN_MEMORY_READ_BOUND`** when truncated |
+| `schema_check(entry, family) -> (bool, error\|None)` | Per-family v1 + secret scan |
+| `compute_decision_key(decision_text) -> str` | Normalized SHA-256 prefix |
+| `dedupe_decision(text, existing_keys) -> (key, is_duplicate)` | Pre-append dedup probe |
+| `append_decision` / `append_mistake` / `append_pattern` / `append_drift` | Append-only + fsync + pre-append rollover hook |
+| `build_injection_digest(repo, scratchpad) -> InjectionDigest` | §5 bounded digest |
+| `promote_from_ledger(run_id, *, decision_types) -> (entry_ids, reason\|None)` | Refresh-context when **`AI_DECISION_LEDGER=1`** |
+| `write_retrospective(sprint_id, body) -> (path\|None, reason\|None)` | Curator markdown under **`retrospectives/`** |
+| `maybe_archive_jsonl(family) -> (ok, reason\|None)` | Line-cap rollover (§7) |
+| `scan_secrets(text) -> ReasonCode\|None` | Pre-append secret guard |
+| `self_test() -> bool` | **`[SOVEREIGN_MEMORY_SELF_TEST_OK]`** |
+
+Research stub ships schemas + injection + self-test; append/rollover/promotion bodies finalized at execute.
+
+### §5 — Injection merge algorithm (AC-3, AC-4)
+
+`build_injection_digest(repo, scratchpad) -> InjectionDigest` with `{digest_text, entry_ids[], char_count}`:
+
+1. **`SOVEREIGN_MEMORY=0`** → empty digest (`digest_text=""`, `entry_ids=[]`, `char_count=0`) — zero overhead.
+2. **Empty corpus** → placeholder **`(no sovereign memory entries)`**; non-fatal.
+3. **Read bound**: at most **`SOVEREIGN_MEMORY_READ_TAIL`** (default **500**) lines per file tail; emit **`SOVEREIGN_MEMORY_READ_BOUND`** as warning only.
+4. **Top-N recent**: merge all four families' `status=active` entries; sort **`ts` desc**, tie-break **`entry_id` asc**; take first **N** unique `entry_id`s.
+5. **Top-K high-impact**: from **`patterns`** + **`mistakes`** only; sort **`impact_score` desc**, tie-break **`ts` desc**, then **`entry_id` asc**; skip ids already in recent pool; take **K** more.
+6. **Digest layout**: `## Recent learnings` then `## High-impact patterns`; each line: `- [family] entry_id: text` (per-line text truncated to **160** chars before global cap).
+7. **Global cap**: hard truncate assembled digest to **`SOVEREIGN_MEMORY_MAX_CHARS`** (suffix **`...`** if truncated).
+8. **Retrospectives**: **not injected v1**.
+
+**Phase spawn hook** (AC-4): when `SOVEREIGN_MEMORY=1`, spawn assembler appends read-only **`sovereign_memory_digest`** block after phase-context narrow-read, before role instructions. **US-0023** fresh-context boundary unchanged — digest is bounded additive input.
+
+### §6 — Mistake-tagging hooks (AC-6)
+
+All hooks **no-op when `SOVEREIGN_MEMORY=0`**. Writes call `append_mistake()` with closed **`mistake_tag`** + orchestrator **`failure_reason_code`**.
+
+| Trigger | `mistake_tag` | `failure_reason_code` | Wiring surface |
+|---------|---------------|----------------------|----------------|
+| Execute auto-loop exhausts fix attempts | `fix_failed` | `FIX_FAILED` | **`/auto`** post-execute when **`AUTO_IMPLEMENTATION_LOOP=1`** |
+| Git revert / rollback in execute findings | `revert_applied` | `REVERT_APPLIED` | **`/execute`** rollback sub-step |
+| Plan-fidelity hard stop | `plan_fidelity_violation` | `PLAN_FIDELITY_VIOLATION` | Compose **`decision_ledger_lib.classify_deviation`** — optional import |
+| QA regression after green execute | `test_regression` | `TEST_REGRESSION` | **`/qa`** fail-closed (optional v1.1 defer allowed) |
+| Extended-mode scope add without override | `scope_creep` | `PLAN_FIDELITY_SCOPE_GATE` | Same fidelity hook family |
+
+**Dedup** (AC-6): `append_decision()` computes `decision_key = sha256(normalize(decision_text))[:16]`; duplicate → **`SOVEREIGN_MEMORY_DECISION_DUPLICATE`** (non-fatal skip).
+
+### §7 — JSONL rollover vs US-0072 (AC-2)
+
+- **Not triad**: sovereign-memory JSONL **excluded** from **US-0072** / **DEC-0054** triad hot surfaces.
+- **Rollover trigger**: on mutating append when active file line count **>** `SOVEREIGN_MEMORY_JSONL_MAX_LINES` → atomically move to archive path, create fresh empty file.
+- **Fail-closed**: rollover I/O failure → **`SOVEREIGN_MEMORY_ARCHIVE_REQUIRED`** (block append).
+- **Idempotency**: second rollover in same boundary must not duplicate archive packs.
+- **Contrast**: triad rollover compacts hot phase context; sovereign-memory archive compacts cold institutional learnings.
+
+### §8 — Curator retrospective + ledger promotion (AC-5)
+
+At **`/refresh-context`** after release segment close:
+
+1. `write_retrospective(sprint_id, body)` → `retrospectives/<sprint_id>.md` with `{sprint_id, story_ids[], release_ref, summary, learnings[], promoted_entry_ids[]}`.
+2. When both **`SOVEREIGN_MEMORY=1`** and **`AI_DECISION_LEDGER=1`**: `promote_from_ledger(run_id, decision_types=...)` copies subset to `decisions-log.jsonl` with `provenance_ref=ledger:<decision_id>`.
+3. When ledger off or filter empty → **`SOVEREIGN_MEMORY_PROMOTION_SKIPPED`** (info).
+
+**US-0103 compose**: ledger remains per-run audit; promotion **reads** ledger context but **does not** mutate ledger schema.
+
+### §9 — Reason code inventory (AC-8)
+
+| Code | Blocking? | Surface |
+|------|-----------|---------|
+| **`SOVEREIGN_MEMORY_DISABLED`** | no (info) | scratchpad gate off |
+| **`SOVEREIGN_MEMORY_SCHEMA_INVALID`** | yes | validator / append |
+| **`SOVEREIGN_MEMORY_APPEND_FAILED`** | yes | I/O / permission |
+| **`SOVEREIGN_MEMORY_DECISION_DUPLICATE`** | no (skip append) | dedup on `decision_key` |
+| **`SOVEREIGN_MEMORY_SECRET_DETECTED`** | yes | pre-append scan |
+| **`SOVEREIGN_MEMORY_ARCHIVE_REQUIRED`** | yes | rollover fail-closed |
+| **`SOVEREIGN_MEMORY_READ_BOUND`** | no (warning) | tail read truncated |
+| **`SOVEREIGN_MEMORY_PROMOTION_SKIPPED`** | no (info) | ledger off or filter empty |
+
+### §10 — Contract tests + parity (AC-7, AC-8)
+
+Eight **`test_us0105_*`** markers in **`tests/us0105_contract_test.py`**:
+
+1. `test_us0105_scratchpad_keys_literals`
+2. `test_us0105_sovereign_memory_directory_contract`
+3. `test_us0105_jsonl_schema_contract`
+4. `test_us0105_injection_digest_char_cap`
+5. `test_us0105_decision_dedup_branch`
+6. `test_us0105_mistake_tagging_literals`
+7. `test_us0105_zero_overhead_default`
+8. `test_us0105_compose_guards`
+
+Compose regression guards (AC-8):
+
+- `test_us0105_us0029_compose_no_research_schema_change`
+- `test_us0105_us0080_injection_respects_char_cap`
+
+**`SOVEREIGN_MEMORY_PAIRS`** for `check_intake_template_parity.py --scope=sovereign-memory`:
+
+- `scripts/sovereign_memory_lib.py` ↔ `template/scripts/sovereign_memory_lib.py`
+- `scripts/sovereign_memory_validate.py` ↔ `template/scripts/sovereign_memory_validate.py`
+- `.cursor/scratchpad.md` ↔ `template/.cursor/scratchpad.md` (`SOVEREIGN_MEMORY_*` block)
+- `docs/engineering/sovereign-memory/.gitkeep` ↔ `template/docs/engineering/sovereign-memory/.gitkeep`
+- `decisions/DEC-0105.md` ↔ `template/decisions/DEC-0105.md`
+
+### §11 — Composition rules
+
+| Story | Compose rule |
+|-------|--------------|
+| **US-0029** | `research.md` schema unchanged; `provenance_ref=R-xxxx` only in memory entries. |
+| **US-0080** / **DEC-0062** | Lib-side digest truncation; **`TOKEN_PROFILE`** / slim-command manifests unchanged. |
+| **US-0103** | Per-run ledger unchanged; optional `promote_from_ledger()` at refresh-context only. |
+| **US-0072** / **DEC-0054** | Triad hot surfaces unchanged; sovereign-memory archive is separate path family. |
+| **US-0096** | `pack.json` / `active-context.md` distinct; sovereign memory is cross-run project layer. |
+| **US-0107** | Read API (`read_entries`, `build_injection_digest`) stable via `schema_version`. |
+| **US-0023** | Fresh-context semantics unchanged; digest is read-only additive spawn input. |
+| **US-0045** | US-0105 remains **OPEN** until release closure. |
+
+### §12 — Risks
+
+| Risk | Mitigation |
+|------|------------|
+| **R1** Token bloat | Char cap + tail read + lib-side digest §5 |
+| **R2** Research vs learnings overlap | `provenance_ref` only; no **`research.md`** schema change |
+| **R3** Ledger vs decisions-log confusion | Distinct paths/schemas + runbook operator table |
+| **R4** Stale injection | `status` supersession enum on all entries |
+| **R5** Secret leakage | `SOVEREIGN_MEMORY_SECRET_DETECTED` scan on free-text fields |
+| **R6** **US-0107** read API coupling | Stable lib surface; version via `schema_version` |
+
+### §13 — Implementation tranche order
+
+1. **Tranche A** — scratchpad keys + reason codes + `DEC-0105` template mirror + directory `.gitkeep`
+2. **Tranche B** — **`sovereign_memory_lib.py`** read/injection core + self-test
+3. **Tranche C** — append/dedup/rollover/promotion bodies + **`sovereign_memory_validate.py`**
+4. **Tranche D** — phase spawn digest hook + mistake-tagging orchestrator wiring
+5. **Tranche E** — curator retrospective + eight `test_us0105_*` + parity + runbook + architecture `# US-0105`
+
+## References
+
+- `docs/engineering/research.md` — **`R-0093`**
+- `docs/product/backlog.md` — **`## US-0105`**
+- `handoffs/intake_evidence/intake-sovereign-20260627-01.json`
+- `scripts/sovereign_memory_lib.py` — research stub + self-test
+- `scripts/decision_ledger_lib.py` — promotion compose (read-only)
+- `handoffs/archive/po-to-tl-pack-20260628-f.md` — discovery L1–L12

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