its-magic 0.1.3-1 → 0.1.3-2

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)

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