its-magic 0.1.3-0 → 0.1.3-2

package/template/docs/engineering/runbook.md

@@ -650,6 +650,203 @@ When **`AUTO_DELIVERY_ROUTING=backlog_then_scratchpad`**, story row may declare
 
 **Release status (S0086 / US-0096)**: **`released`** (`2026-06-13T16:00:00Z`); **`US-0096`** **DONE** in canonical backlog. Operator verify: **`handoffs/releases/S0086-release-notes.md`** **## Verify**; publish skipped while **`RELEASE_PUBLISH_MODE=confirm`**.
 
+## Per-phase model tier selection (US-0101 / DEC-0086)
+
+`MODEL_TIER` selects LLM model strength (which model runs per lifecycle phase).
+Three operator-facing tiers map to stable Cursor aliases — no vendor slugs in
+template files.
+
+| Key | Values | Default | Role |
+|-----|--------|---------|------|
+| **`MODEL_TIER_DEFAULT`** | `cheap` \| `balanced` \| `strong` | `balanced` | Fallback when phase-specific key absent |
+| **`MODEL_TIER_<PHASE>`** | `cheap` \| `balanced` \| `strong` | *(per matrix)* | Per-phase tier override |
+| **`MODEL_CATALOG`** | path | `.cursor/model-catalog.local.json` | Path to local slug catalog |
+| **`MODEL_RESOLVE`** | `alias_only` \| `local_catalog` | `alias_only` | Resolution strategy |
+| **`MODEL_FALLBACK`** | `inherit` | `inherit` | Fallback when catalog lookup fails |
+| **`MODEL_PROVIDER_MODE`** | `cursor` \| `api` | `cursor` | Provider routing |
+
+### Default phase→tier matrix (architecture-locked)
+
+| Tier | Cursor alias | `model:` field | Phases |
+|------|-------------|----------------|--------|
+| **`cheap`** | `fast` | `model: fast` | `ask`, `refresh-context`, `memory-audit`, `status-reconcile`, `pause` |
+| **`balanced`** | `inherit` | `model: inherit` | `intake`, `discovery`, `research`, `release`, `plan-verify` |
+| **`strong`** | *(omit)* | no `model:` field | `architecture`, `execute`, `quick`, `qa`, `verify-work`, `security-review` |
+| *(inherit parent)* | — | — | `auto` (orchestrator always inherits parent model) |
+
+### Provider mode (MODEL_PROVIDER_MODE)
+
+| Mode | Description |
+|------|-------------|
+| **`cursor`** (default) | All subagents route through Cursor-managed infrastructure; tier aliases work as designed |
+| **`api`** | Operator uses BYOK via Cursor Settings → Models → API Key |
+
+**Known limitation (confirmed 2026-06)**: Cursor subagents do **NOT** inherit
+custom API keys or base URLs — they always bill against the Cursor plan. When
+`MODEL_PROVIDER_MODE=api`, the local catalog is the only operator-controlled
+surface; subagent `model:` aliases still resolve through Cursor infrastructure.
+
+**Workaround recipes**:
+
+1. **Parent model + `inherit`** — set the parent chat model to the desired BYOK
+   model; subagents using `model: inherit` (balanced tier) pick it up.
+2. **Manual phase runs** — run each phase in a separate chat with the desired
+   model selected at the chat level (no subagent spawn).
+3. **Local catalog override** — set `MODEL_RESOLVE=local_catalog` and populate
+   `.cursor/model-catalog.local.json` with vendor slugs; materializer applies
+   slugs at template materialization time (not at subagent runtime).
+
+### Non-substitution paragraph
+
+MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE
+
+> **`MODEL_TIER`** selects LLM model strength (which model runs).
+> **`TOKEN_PROFILE`** selects context breadth / token cost (how much context the model sees).
+> **`DELIVERY_MODE`** selects lifecycle shape (standard / ultra_lean / mega_quick).
+> These are **independent axes** — none substitutes for another. A `strong` tier
+> with `lean` profile is valid; a `cheap` tier with `full` profile is valid.
+> Setting one does not change the others. Combine freely.
+
+### Reason codes — `MODEL_TIER_*` / `MODEL_CATALOG_*` / `MODEL_RESOLVE_*` / `MODEL_SLUG_*`
+
+| Code | Trigger |
+|------|---------|
+| **`MODEL_TIER_INVALID`** | Unknown tier value (not `cheap`/`balanced`/`strong`) |
+| **`MODEL_CATALOG_INVALID`** | Malformed catalog JSON (parse error, missing `schema_version`) |
+| **`MODEL_SLUG_UNKNOWN`** | Tier key missing from catalog when `MODEL_RESOLVE=local_catalog` |
+| **`MODEL_RESOLVE_FALLBACK`** | Catalog lookup failed but `MODEL_FALLBACK=inherit` → reason + fallback |
+
+### Template agent defaults
+
+| Agent role | Tier | `model:` field |
+|-----------|------|----------------|
+| `curator` | cheap | `model: fast` |
+| `po` | balanced | `model: inherit` |
+| `release` | balanced | `model: inherit` |
+| `tech-lead` | strong | *(omit)* |
+| `dev` | strong | *(omit)* |
+| `qa` | strong | *(omit)* |
+| `security` | strong | *(omit)* |
+
+**Forbidden in `template/.cursor/agents/`**: hardcoded vendor slugs
+(`composer-*`, `claude-*`, `gpt-*`, `opus-*`). Template files use aliases only.
+
+### Local catalog schema (v1)
+
+```json
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "<slug>",
+    "balanced": "<slug>",
+    "strong": "<slug>"
+  },
+  "notes": "optional free-text"
+}
+```
+
+- Path: `.cursor/model-catalog.local.json` (gitignored)
+- Example: `.cursor/model-catalog.local.example.json` (committed, placeholder values)
+- All three tier keys required; values are opaque vendor slug strings
+
+### Resolver algorithm
+
+1. Read `MODEL_TIER_<PHASE>` from merged scratchpad → tier value
+2. If `MODEL_RESOLVE=alias_only` (default): use built-in mapping (table above)
+3. If `MODEL_RESOLVE=local_catalog`: load catalog JSON → lookup tier key → slug
+4. If key missing → `MODEL_SLUG_UNKNOWN` fail-closed
+5. If `MODEL_FALLBACK=inherit` and lookup fails → emit `MODEL_RESOLVE_FALLBACK` + use `inherit`
+6. Unknown tier value → `MODEL_TIER_INVALID` fail-closed
+7. Malformed catalog JSON → `MODEL_CATALOG_INVALID` fail-closed
+
+### Validation commands
+
+- `python scripts/model_tier_validate.py --repo .`
+- `pytest -k us0101 tests/auto_command_contract_test.py`
+- `python scripts/check_intake_template_parity.py --scope=model-tier`
+- `tests/run-tests.ps1` / `tests/run-tests.sh` §26Z
+
+Normative architecture: `docs/engineering/architecture.md` (**# US-0101**).
+
+## Direct per-phase model slug override + role catalog (US-0102 / DEC-0087)
+
+Composes on **US-0101** / **DEC-0086** — tier-only operators need no migration.
+
+### 5-step precedence chain
+
+| Step | Source | Outcome |
+|------|--------|---------|
+| **1** | `MODEL_<PHASE>` | Non-empty slug → return (validate per mode) or `MODEL_OVERRIDE_SLUG_UNKNOWN` |
+| **2** | `MODEL_TIER_<PHASE>` | **DEC-0086** tier→alias / `local_catalog` chain |
+| **3** | `MODEL_RESOLVE=role_catalog` | Phase→logical role → catalog `roles[<key>]`; miss → `MODEL_ROLE_SLUG_UNKNOWN` → fall through |
+| **4** | `MODEL_TIER_DEFAULT` | **DEC-0086** tier chain |
+| **5** | Cursor alias | **DEC-0086** built-in mapping |
+
+When `MODEL_RESOLVE` is `alias_only` or `local_catalog`, step **3** is skipped.
+
+### Scratchpad keys (new)
+
+| Key | Default | Role |
+|-----|---------|------|
+| **`MODEL_<PHASE>`** | *(absent)* | Direct vendor slug; includes `MODEL_ASK` |
+| **`MODEL_RESOLVE`** | `alias_only` | Extended: `alias_only` \| `local_catalog` \| **`role_catalog`** |
+
+Operator slugs live in `.cursor/scratchpad.local.md` and `.cursor/model-catalog.local.json` only (gitignored).
+
+### Role catalog enablement recipe
+
+1. Copy a v2 example catalog:
+   - `.cursor/model-catalog.local.example.role-based-balanced.json`, or
+   - `.cursor/model-catalog.local.example.role-based-highend.json`
+2. Save as `.cursor/model-catalog.local.json` with real vendor slugs.
+3. Set `MODEL_RESOLVE=role_catalog` in `.cursor/scratchpad.local.md`.
+4. Optional: set `MODEL_<PHASE>=<slug>` for direct overrides (step 1 wins over role lookup).
+5. Run `python scripts/model_tier_validate.py --repo .` to validate.
+
+On role lookup miss → `MODEL_ROLE_SLUG_UNKNOWN` emitted; resolver falls through to `MODEL_TIER_DEFAULT` then Cursor alias.
+
+**`dev_difficult`**: no automatic phase routing — use `MODEL_EXECUTE=<slug>` direct override or tier `strong` + catalog tier slug.
+
+Non-normative role recommendations: `ai_modell_auslegung_cursor_highend.md`.
+
+### Catalog schema v2 (opt-in)
+
+```json
+{
+  "schema_version": 2,
+  "tiers": { "cheap": "<slug>", "balanced": "<slug>", "strong": "<slug>" },
+  "roles": {
+    "po": "<slug>", "sa": "<slug>", "dev": "<slug>", "dev_difficult": "<slug>",
+    "qa": "<slug>", "security": "<slug>", "release": "<slug>"
+  }
+}
+```
+
+v1 catalogs (tiers only) unchanged. Malformed v2 → `MODEL_CATALOG_SCHEMA_V2_INVALID`.
+
+### New reason codes
+
+| Code | Trigger |
+|------|---------|
+| **`MODEL_OVERRIDE_SLUG_UNKNOWN`** | Direct slug validation failure |
+| **`MODEL_ROLE_SLUG_UNKNOWN`** | Role catalog lookup miss |
+| **`MODEL_CATALOG_SCHEMA_V2_INVALID`** | v2 schema validation failure |
+
+### Non-substitution paragraph
+
+MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE — unchanged from **US-0101**; model selection is orthogonal to context breadth.
+
+### Validation commands
+
+- `python scripts/model_tier_validate.py --repo .`
+- `pytest -k us0102 tests/auto_command_contract_test.py`
+- `python scripts/check_intake_template_parity.py --scope=model-tier-overrides`
+- `tests/run-tests.ps1` / `tests/run-tests.sh` §26AA
+
+Normative architecture: `docs/engineering/architecture.md` (**# US-0102**); decision: **`DEC-0087`**.
+
+Binding decision: `decisions/DEC-0086.md`.
+
 Context compaction policy:
 
 - `docs/engineering/state.md` is a compact hot surface for current execution
@@ -741,6 +938,83 @@ If the default set is insufficient, escalate with an explicit note citing
 - If unresolved after bounded expansion, answer with explicit "not found in
   current artifacts" rather than broad speculative reads.
 
+## Model-catalog example preset delivery (US-0112 / DEC-0112)
+
+**Default state**: 8 committed `model-catalog.local.example*.json` presets ship with the
+`its-magic` framework and are delivered to operator repos via the installer manifest
+(`docs/engineering/context/installer-owned-paths.manifest` [install_include_paths]) under
+**framework-file semantics** (US-0018 / US-0057 / US-0075 precedence).
+
+### Eight preset filenames (manifest rows)
+
+1. `.cursor/model-catalog.local.example.json` — base placeholder (three tiers, opaque vendor slugs)
+2. `.cursor/model-catalog.local.example.cursor-only.json` — Cursor-first alias mapping
+3. `.cursor/model-catalog.local.example.level-1-easy.json` — easy complexity tier set
+4. `.cursor/model-catalog.local.example.level-2-complex.json` — moderate complexity tier set
+5. `.cursor/model-catalog.local.example.level-3-mega.json` — heavy complexity tier set
+6. `.cursor/model-catalog.local.example.level-4-super.json` — maximal complexity tier set
+7. `.cursor/model-catalog.local.example.role-based-balanced.json` — role-catalog balanced preset
+8. `.cursor/model-catalog.local.example.role-based-highend.json` — role-catalog high-end preset
+
+### Installer behavior (framework-file semantics)
+
+- **`missing` mode** (default new install): copies the 8 example presets into the target
+  `.cursor/` directory when absent; deterministic status log per file (names only; no content
+  inspection); same semantics as `scratchpad.local.example.md` per US-0075.
+- **`upgrade` mode**: refreshes the example presets when the packaged template version
+  differs (byte-compare); skips byte-identical files; never modifies or removes the active
+  operator-owned `.cursor/model-catalog.local.json` (gitignored; not in manifest).
+- **Triple installer parity**: `installer.py`, `installer.ps1`, `installer.sh` all read the
+  single manifest `[install_include_paths]` as source of truth; framework classification
+  for `.cursor/model-catalog.local.example*.json` is identical across Python / PowerShell /
+  Bash `classify_file` paths.
+
+### Operator usage recipe
+
+1. Inspect the 8 presets under `.cursor/` (shipped automatically by install or upgrade).
+2. Choose a preset matching your intent — complexity-based (levels 1–4) or role-based
+   (balanced / highend) for `MODEL_RESOLVE=role_catalog`; cursor-only alias mapping; or
+   base template for custom tiers.
+3. Copy the chosen preset: `cp .cursor/model-catalog.local.example.<preset>.json .cursor/model-catalog.local.json`.
+4. Edit real vendor slugs into `.cursor/model-catalog.local.json` (placeholder values
+   substituted; vendor-specific).
+5. Set `MODEL_RESOLVE=local_catalog` (or `role_catalog` for role-based presets) in
+   `.cursor/scratchpad.local.md`.
+6. Validate: `python scripts/model_tier_validate.py --repo .`.
+7. Parity: `python scripts/check_intake_template_parity.py --scope=model-catalog-examples`.
+
+**Active catalog protection invariant**: `.cursor/model-catalog.local.json` remains
+gitignored and outside `install_include_paths` + `clean_paths`. The installer never
+auto-populates it. No installer mode copies, merges, or replaces the active catalog.
+This is a DEC-0086 / DEC-0087 boundary (US-0101 catalog schema + US-0102 role precedence
+remain unaltered; US-0112 only completes delivery path).
+
+### Parity scope
+
+```bash
+python scripts/check_intake_template_parity.py --scope=model-catalog-examples
+```
+
+Validates active vs template byte-parity for `installer-owned-paths.manifest` (16 manifest
+rows total across active + template paths). On mismatch → `MODEL_CATALOG_EXAMPLE_PARITY_SCOPE_MISMATCH`.
+On pass → `[MODEL_CATALOG_EXAMPLE_PARITY_SCOPE_OK]`.
+
+### Reason codes
+
+| Code | Trigger |
+|------|---------|
+| `MODEL_CATALOG_EXAMPLE_PARITY_SCOPE_OK` | Active vs template manifest byte-parity pass for 8 model-catalog.example paths |
+| `MODEL_CATALOG_EXAMPLE_PARITY_SCOPE_MISMATCH` | Active vs template manifest byte-parity fail |
+
+### Validation commands
+
+- `python scripts/check_intake_template_parity.py --scope=model-catalog-examples`
+- `pytest -k us0112 tests/us0112_contract_test.py`
+
+Normative architecture: `docs/engineering/architecture.md` (**# US-0112**); decision: **`DEC-0112`** (Accepted).
+
+Binding decision: `decisions/DEC-0112.md`. Research anchor: `docs/engineering/research.md` **R-0090**.
+
 ## Configurable multi-target publish mode (US-0054 / DEC-0036)
 
 Post-release publish orchestration is configurable and default-safe:
@@ -2382,6 +2656,851 @@ Single-writer drift safety:
   sourcing `.env` — the process inherits normal environment variables.
 - Referencing env var **names** (not values) in documentation and handoffs.
 
+## AI Decision Ledger (US-0103 / DEC-0103)
+
+**Default-off sovereign-loop audit layer**. When `AI_DECISION_LEDGER=0` (default),
+zero overhead — no files read or written. When `AI_DECISION_LEDGER=1`, every
+autonomous AI deviation is recorded in an append-only JSONL ledger under
+`handoffs/sovereign_decisions/<orchestrator_run_id>.jsonl`.
+
+### Scratchpad keys
+
+| Key | Values | Default | Behavior when off |
+|-----|--------|---------|-------------------|
+| `AI_DECISION_LEDGER` | `0` \| `1` | `0` | No reads / writes / schema checks. |
+| `AUTO_PLAN_FIDELITY` | `strict` \| `relaxed` \| `extended` | `strict` | Active only when ledger enabled. |
+
+Set in `.cursor/scratchpad.local.md` (gitignored) or `.cursor/scratchpad.md`.
+
+### Enable / disable
+
+```bash
+# Enable ledger auditing
+echo "AI_DECISION_LEDGER=1" >> .cursor/scratchpad.local.md
+
+# Switch fidelity mode (relaxed allows AC drop/reorder; extended allows scope add)
+echo "AUTO_PLAN_FIDELITY=relaxed" >> .cursor/scratchpad.local.md
+
+# Disable (zero overhead)
+echo "AI_DECISION_LEDGER=0" >> .cursor/scratchpad.local.md
+```
+
+### Audit ledger entries
+
+```bash
+# Validate all ledger files in handoffs/sovereign_decisions/
+python scripts/ledger_validate.py --repo .
+
+# Validate a single ledger file
+python scripts/ledger_validate.py --file handoffs/sovereign_decisions/auto-20260628-01.jsonl
+
+# Print QA findings block (JSON)
+python scripts/ledger_validate.py --qa-find --orchestrator-run-id auto-20260628-01
+
+# Validate with fail-closed enforcement
+python scripts/ledger_validate.py --repo . --enforce
+
+# Library self-test
+python scripts/decision_ledger_lib.py --self-test
+```
+
+### Plan-fidelity modes
+
+| Mode | Behavior | When to use |
+|------|----------|-------------|
+| `strict` | Any unapproved deviation from `resolved_phase_plan` → **`PLAN_FIDELITY_VIOLATION` hard stop**. Operator must approve override or revert. | Default. Production runs, high-risk stories. |
+| `relaxed` | AI may drop/reorder existing ACs with ledger entry + QA-verifiable; new ACs/stories → `PLAN_FIDELITY_SCOPE_GATE` hard stop. | Iterative development where AC refinement is expected. |
+| `extended` | AI may extend scope with new stories/features; documented non-blocking in ledger as `PLAN_FIDELITY_EXTENSION`. QA still cross-checks. | Exploratory work, prototyping, scope discovery. |
+
+### Typical audit workflow
+
+1. **Enable ledger** before long `/auto` run: set `AI_DECISION_LEDGER=1` in scratchpad.
+2. **Run `/auto`** to completion — ledger writes accumulate in `handoffs/sovereign_decisions/<run_id>.jsonl`.
+3. **Run `/qa`** — phase reads ledger, emits `ledger_findings` block in `sprints/Sxxxx/qa-findings.md` with decision counts, risk tier distribution, and fail-closed code summary.
+4. **Inspect findings** — look for `violation_count > 0` (unapproved deviations) or `schema_invalid` status (corrupt ledger).
+5. **Remediate or approve** — if deviations justified, set `AUTO_PLAN_FIDELITY=relaxed` or `=extended` and re-run; otherwise revert changes.
+
+### Common failure scenarios and recovery
+
+| Reason code | Symptom | Recovery |
+|-------------|---------|----------|
+| `LEDGER_FILE_MISSING` | `AI_DECISION_LEDGER=1` but no ledger file for current run | Create `handoffs/sovereign_decisions/<run_id>.jsonl` or set `AI_DECISION_LEDGER=0` |
+| `LEDGER_SCHEMA_INVALID` | JSONL line fails 12-field schema validation | Open ledger, locate invalid line (validator prints line number), fix JSON syntax; if unrecoverable, truncate to last valid line |
+| `LEDGER_CORRUPT` | Whole file non-UTF-8 or broken JSON | Manual repair required; consider `git restore` from prior commit or truncate to known-good prefix |
+| `LEDGER_APPEND_FAILED` | Disk full, permission error, I/O error | Check disk space (`df -h`), file permissions (`ls -la handoffs/sovereign_decisions/`); retry after remediation |
+| `PLAN_FIDELITY_VIOLATION` | Unapproved deviation under strict mode | Review ledger last entry; if justified, switch to `AUTO_PLAN_FIDELITY=relaxed` in scratchpad and re-run `/execute`; otherwise revert AC changes |
+| `PLAN_FIDELITY_SCOPE_GATE` | New scope request under strict/relaxed mode | If scope-add intentional, switch to `AUTO_PLAN_FIDELITY=extended` and document in `sprints/Sxxxx/extension-report.md`; otherwise drop new scope |
+| `LEDGER_DISABLED` | Informational — `AI_DECISION_LEDGER=0` | No action required; zero overhead when off. Opt-in via scratchpad if ledger auditing desired. |
+
+### Parity enforcement
+
+```bash
+# Verify active ↔ template byte-parity for ledger scripts + scratchpad
+python scripts/check_intake_template_parity.py --scope=sovereign-ledger
+```
+
+Pair table (`SOVEREIGN_LEDGER_PAIRS` + scratchpad):
+- `scripts/decision_ledger_lib.py` ↔ `template/scripts/decision_ledger_lib.py`
+- `scripts/ledger_validate.py` ↔ `template/scripts/ledger_validate.py`
+- `.cursor/scratchpad.md` ↔ `template/.cursor/scratchpad.md`
+- `.cursor/scratchpad.local.example.md` ↔ `template/.cursor/scratchpad.local.example.md`
+
+### Related artifacts
+
+- **Architecture**: `docs/engineering/architecture.md` `# US-0103`
+- **Reason codes**: `docs/engineering/reason_codes.md` § US-0103
+- **Decision record**: `decisions/DEC-0103.md`
+- **Contract tests**: `tests/us0103_contract_test.py` (8 tests)
+
+## Goal-Based Convergence (US-0110 / DEC-0110)
+
+**Default-off sovereign-loop terminal predicate**. When `SOVEREIGN_GOAL_MODE=phase_driven`
+(default), zero overhead — no evaluation, no `goal_progress` block, no partial-delivery write.
+When `goal_convergence`, `evaluate_convergence` reads composed surfaces (backlog, deferrals,
+critic, smoke, ledger) and emits progress/timeout artifacts only.
+
+### Scratchpad keys
+
+| Key | Values | Default | Behavior when off |
+|-----|--------|---------|-------------------|
+| `SOVEREIGN_GOAL_MODE` | `phase_driven` \| `goal_convergence` | `phase_driven` | No evaluation side effects. |
+| `SOVEREIGN_GOAL` | free-text | *(empty)* | Explicit goal wins over vision derive. |
+| `SOVEREIGN_GOAL_TOP_N` | int ≥ 1 | `3` | Vision paragraph count for auto-derive. |
+| `SOVEREIGN_GOAL_MAX_CHARS` | int ≥ 64 | `512` | Truncation cap for goal text. |
+| `SOVEREIGN_GOAL_TIMEOUT_MAX` | int ≥ 0 | `0` | Iteration-count cap (`0` = disabled). |
+
+### Enable / disable
+
+```bash
+# Enable goal-driven convergence
+echo "SOVEREIGN_GOAL_MODE=goal_convergence" >> .cursor/scratchpad.local.md
+echo "SOVEREIGN_GOAL=Ship sovereign-loop batch with zero regressions" >> .cursor/scratchpad.local.md
+
+# Disable (zero overhead — US-0088/US-0092/US-0095/US-0044 stop matrix unchanged)
+echo "SOVEREIGN_GOAL_MODE=phase_driven" >> .cursor/scratchpad.local.md
+```
+
+### Evaluate convergence
+
+```bash
+# Library self-test
+python scripts/sovereign_convergence_lib.py --self-test
+
+# Evaluate five-conjunct predicate (JSON)
+python scripts/sovereign_convergence_lib.py --evaluate --repo . --orchestrator-run-id auto-20260628-04
+
+# Dump goal_progress block
+python scripts/sovereign_convergence_lib.py --dump-progress --repo . --orchestrator-run-id auto-20260628-04
+
+# Validator self-test + schema fixtures
+python scripts/sovereign_convergence_validate.py --self-test
+
+# Validate artifacts in repo
+python scripts/sovereign_convergence_validate.py --repo . --enforce
+```
+
+### Interpret `goal_progress` block
+
+Curator **`/refresh-context`** emits a fenced JSON block under **`### goal_progress`** in
+`handoffs/resume_brief.md` when `SOVEREIGN_GOAL_MODE=goal_convergence` and the sovereign loop
+is active. Placement: after the latest orchestration pointer, before prior pointers.
+
+Fields: `goal_text`, `goal_source`, `mode`, `converged`, `unmet_conditions[]`, `blocked_by[]`,
+`conjuncts`, `evaluated_at`, `orchestrator_run_id`, `schema_version`.
+
+### Partial delivery on timeout
+
+When `SOVEREIGN_GOAL_TIMEOUT_MAX > 0` and iteration count reaches the cap without
+`converged=true`, the evaluator emits **`SOVEREIGN_GOAL_TIMEOUT`** and writes
+`handoffs/sovereign_partial_delivery.md` (sections: Goal, Evaluated At, Unmet Conditions,
+Blocked By, Completed Stories, Open Stories, Deferrals Summary, Remediation).
+
+### Troubleshooting reason codes
+
+See `docs/engineering/reason_codes.md` § US-0110 for the 10-code inventory and remediation.
+
+| Reason code | Symptom | Recovery |
+|-------------|---------|----------|
+| `CONVERGENCE_OPEN_STORIES_REMAIN` | OPEN stories in backlog | Complete stories or adjust goal scope |
+| `CONVERGENCE_SMOKE_PROBE_FAIL` | `tests/report.md` Fail > 0 or UAT smoke step failed | Fix tests; re-run `/verify-work` |
+| `SOVEREIGN_GOAL_TIMEOUT` | Iteration cap exhausted | Read partial-delivery report; increase cap or resolve blockers |
+| `SOVEREIGN_GOAL_DERIVE_FAILED` | Empty/unreadable vision | Set explicit `SOVEREIGN_GOAL` |
+
+### Parity enforcement
+
+```bash
+python scripts/check_intake_template_parity.py --scope=sovereign-convergence
+```
+
+Pair table (`SOVEREIGN_CONVERGENCE_PAIRS`):
+- `scripts/sovereign_convergence_lib.py` ↔ `template/scripts/sovereign_convergence_lib.py`
+- `scripts/sovereign_convergence_validate.py` ↔ `template/scripts/sovereign_convergence_validate.py`
+
+### Related artifacts
+
+- **Architecture**: `docs/engineering/architecture.md` `# US-0110`
+- **Reason codes**: `docs/engineering/reason_codes.md` § US-0110
+- **Decision record**: `decisions/DEC-0110.md`
+- **Contract tests**: `tests/us0110_contract_test.py` (8 tests)
+
+### Cross-Model Adversarial Critic (US-0104)
+
+**Default-off cross-model review**. When `CROSS_MODEL_REVIEW=0` (default), zero overhead — no
+critic spawn, no findings writes, no anti-slop gate. When `1`, `/auto` spawns `/sovereign-critic`
+after each producer phase.
+
+#### Scratchpad keys
+
+| Key | Values | Default | Behavior when off |
+|-----|--------|---------|-------------------|
+| `CROSS_MODEL_REVIEW` | `0` \| `1` | `0` | No critic spawn or findings writes. |
+| `CROSS_MODEL_ANTISLOP_THRESHOLD` | int 0–10 | `6` | Aggregate below → rework loop. |
+| `CROSS_MODEL_REWORK_MAX` | int ≥ 0 | `2` | Max producer re-spawns per `(run, phase)`. |
+
+#### Enable / disable
+
+```bash
+# Enable cross-model critic
+echo "CROSS_MODEL_REVIEW=1" >> .cursor/scratchpad.local.md
+
+# Disable (zero overhead)
+echo "CROSS_MODEL_REVIEW=0" >> .cursor/scratchpad.local.md
+```
+
+#### Validate findings JSONL
+
+```bash
+python scripts/sovereign_critic_lib.py --self-test
+python scripts/sovereign_critic_validate.py --self-test
+python scripts/sovereign_critic_validate.py --repo . --enforce
+python scripts/sovereign_critic_validate.py --open-blocking --repo .
+```
+
+#### Interpret findings JSONL
+
+Canonical path: `handoffs/sovereign_critic_findings.jsonl` (append-only, 15-field v1 schema).
+Each line includes `lens` (`challenger` \| `architect` \| `subtractor`), `severity`, `confidence`
+(set by reconciliation), `anti_slop_score`, `blocking`, and `degraded_mode`.
+
+Reconciliation: ≥2 lenses share `issue_key` → `confidence=high`; single lens → `medium`.
+
+#### Anti-slop rework remediation
+
+When aggregate `min(lens_scores) < CROSS_MODEL_ANTISLOP_THRESHOLD` and blocking findings exist:
+
+1. Producer phase re-spawns with fresh context (bounded by `CROSS_MODEL_REWORK_MAX`).
+2. Reason **`CROSS_MODEL_ANTISLOP_FAIL`** during rework; **`CROSS_MODEL_REWORK_CAP_EXHAUSTED`**
+   at cap → operator decision gate (waive or abort).
+
+#### Degraded fallback troubleshooting
+
+When `select_critic_model` resolves the same slug as producer (or catalog miss), framework sets
+`degraded_mode=true` and runs three sequential lens spawns on the same model. Informational reason
+**`CROSS_MODEL_DEGRADED_MODE`** — not a hard stop. Documented limitation per **R-0088**.
+
+#### Isolation `model_id` v2
+
+When `CROSS_MODEL_REVIEW=1`, producer **and** critic isolation evidence rows require additive
+`model_id`. Missing → **`ISOLATION_EVIDENCE_MODEL_ID_MISSING`**.
+
+#### Parity enforcement
+
+```bash
+python scripts/check_intake_template_parity.py --scope=sovereign-critic
+```
+
+Pair table (`SOVEREIGN_CRITIC_PAIRS`): lib, validator, command, scratchpad, `DEC-0104.md`.
+
+#### Related artifacts
+
+- **Architecture**: `docs/engineering/architecture.md` `# US-0104`
+- **Reason codes**: `docs/engineering/reason_codes.md` § US-0104
+- **Decision record**: `decisions/DEC-0104.md`
+- **Contract tests**: `tests/us0104_contract_test.py` (8 tests + 2 compose guards)
+
+### Sovereign Memory (US-0105)
+
+**Default-off institutional memory**. When `SOVEREIGN_MEMORY=0` (default), zero overhead —
+no JSONL writes, no injection reads, no spawn digest assembly. When `1`, bounded learnings
+inject into phase spawns via `scripts/sovereign_memory_lib.py`.
+
+#### Scratchpad keys
+
+| Key | Values | Default | Behavior when off |
+|-----|--------|---------|-------------------|
+| `SOVEREIGN_MEMORY` | `0` \| `1` | `0` | No reads / writes / digest assembly. |
+| `SOVEREIGN_MEMORY_TOP_N` | int ≥ 0 | `5` | Recent pool size (all four JSONL families). |
+| `SOVEREIGN_MEMORY_TOP_K` | int ≥ 0 | `3` | High-impact pool (`patterns` + `mistakes`). |
+| `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. |
+
+#### Enable / disable
+
+```bash
+# Enable sovereign memory
+echo "SOVEREIGN_MEMORY=1" >> .cursor/scratchpad.local.md
+
+# Disable (zero overhead)
+echo "SOVEREIGN_MEMORY=0" >> .cursor/scratchpad.local.md
+```
+
+#### JSONL families vs per-run ledger
+
+| Artifact | Path | Scope | Injected v1? |
+|----------|------|-------|--------------|
+| Decisions log | `docs/engineering/sovereign-memory/decisions-log.jsonl` | Cross-run distilled learnings | yes |
+| Mistakes | `docs/engineering/sovereign-memory/mistakes.jsonl` | Orchestrator mistake hooks | yes (top-K) |
+| Patterns | `docs/engineering/sovereign-memory/patterns.jsonl` | Phase/curator consolidation | yes (top-K) |
+| Plan drift | `docs/engineering/sovereign-memory/plan-drift-register.jsonl` | Fidelity/scope hooks | yes (top-N) |
+| Retrospectives | `sovereign-memory/retrospectives/<sprint_id>.md` | Curator `/refresh-context` | **no** |
+| Per-run ledger (**US-0103**) | `handoffs/sovereign_decisions/<run_id>.jsonl` | Per-run audit | no (optional promotion) |
+
+Promotion at `/refresh-context` copies ledger highlights to `decisions-log.jsonl` with
+`provenance_ref=ledger:<decision_id>` when both `SOVEREIGN_MEMORY=1` and `AI_DECISION_LEDGER=1`.
+
+#### Validate / self-test
+
+```bash
+python scripts/sovereign_memory_lib.py --self-test
+python scripts/sovereign_memory_validate.py --self-test
+python scripts/sovereign_memory_validate.py --repo . --enforce
+```
+
+#### Injection char-cap troubleshooting
+
+When digest appears truncated:
+
+1. Check `SOVEREIGN_MEMORY_MAX_CHARS` (default **2048**).
+2. Reduce `SOVEREIGN_MEMORY_TOP_N` / `SOVEREIGN_MEMORY_TOP_K` if too many entries compete.
+3. Informational **`SOVEREIGN_MEMORY_READ_BOUND`** when tail read truncates — digest still emitted.
+
+#### Archive rollover remediation
+
+When append fails with **`SOVEREIGN_MEMORY_ARCHIVE_REQUIRED`**:
+
+1. Check permissions on `docs/engineering/sovereign-memory-archive/`.
+2. Verify disk space; active file rollover moves to `<basename>-<YYYYMMDDTHHMMSSZ>.jsonl`.
+3. Rollover is **not** triad compaction (**US-0072** unchanged).
+
+#### Parity enforcement
+
+```bash
+python scripts/check_intake_template_parity.py --scope=sovereign-memory
+```
+
+Pair table (`SOVEREIGN_MEMORY_PAIRS`): lib, validator, scratchpad, `.gitkeep`, `DEC-0105.md`.
+
+#### Related artifacts
+
+- **Architecture**: `docs/engineering/architecture.md` `# US-0105`
+- **Reason codes**: `docs/engineering/reason_codes.md` § US-0105
+- **Decision record**: `decisions/DEC-0105.md`
+- **Contract tests**: `tests/us0105_contract_test.py` (8 tests + 2 compose guards)
+
+### Sovereign Loop Mode (US-0107)
+
+**Default-off project orchestration**. When `AUTO_SOVEREIGN=0` (default), zero overhead — no
+deferral reads/writes, no advance, no notifications. When enabled, requires
+`SOVEREIGN_GOAL_MODE=goal_convergence` (fail-closed **`SOVEREIGN_LOOP_GOAL_MODE_REQUIRED`**).
+
+#### Scratchpad keys
+
+| Key | Values | Default | Notes |
+|-----|--------|---------|-------|
+| `AUTO_SOVEREIGN` | `0` \| `1` | `0` | Master enable gate. |
+| `AUTO_SOVEREIGN_DEFERRAL_MAX` | int ≥ 1 | `50` | Max open deferral rows. |
+| `AUTO_SOVEREIGN_DRAIN_GENERATE_MAX` | int ≥ 0 | `3` | Drain-generate iterations per run. |
+| `AUTO_SOVEREIGN_DEFERRAL_POLICY` | `stop` \| `skip` \| `resolve_first` | `resolve_first` | Deferral gate policy. |
+| `SOVEREIGN_NOTIFY_TARGET` | `off` \| `ntfy` \| `email` \| `hook` | `off` | Notification adapter. |
+| `SOVEREIGN_NOTIFY_NTFY_TOPIC` | string | *(empty)* | Local-only ntfy topic. |
+| `SOVEREIGN_NOTIFY_NTFY_BASE` | URL | *(empty)* | Optional ntfy base override — local-only. |
+| `SOVEREIGN_NOTIFY_HOOK_URL` | URL | *(empty)* | Webhook POST target — local-only. |
+| `SOVEREIGN_NOTIFY_EMAIL_TO` | email | *(empty)* | Email v1 deferred. |
+
+#### Enable / disable
+
+```bash
+# Enable sovereign loop (both keys required)
+echo "AUTO_SOVEREIGN=1" >> .cursor/scratchpad.local.md
+echo "SOVEREIGN_GOAL_MODE=goal_convergence" >> .cursor/scratchpad.local.md
+
+# Disable (zero overhead)
+echo "AUTO_SOVEREIGN=0" >> .cursor/scratchpad.local.md
+```
+
+Notification topic/URL values belong in `.cursor/scratchpad.local.md` only — never commit secrets.
+
+#### Deferral register operator workflow
+
+| Action | Command / API |
+|--------|----------------|
+| Append deferral | `append_deferral(...)` via `sovereign_loop_lib.py` |
+| Resolve deferral | `resolve_deferral(repo, deferral_id, orchestrator_run_id=...)` |
+| List open rows | `list_open_deferrals(repo, scratchpad=...)` (latest-state-wins) |
+| Validate JSONL | `python scripts/sovereign_loop_validate.py --repo . --enforce` |
+
+Path: `handoffs/sovereign_deferrals.jsonl` (create-on-first-write; bootstrap `.gitkeep` only).
+Sidecar: `handoffs/sovereign_loop_state.json` v1 — per-run drain-generate iteration counter.
+
+#### Drain-generate decision gate
+
+When backlog has zero OPEN stories but convergence is not met and iterations remain under cap,
+`/auto` spawns a fresh **PO** subagent (spawn-only **US-0095**) with ephemeral id
+`drain-gen-{orchestrator_run_id}-{iteration}`. PO proposes up to **3** candidates per iteration.
+
+**Mandatory per-candidate decision gate**: accept → `/intake` or controlled backlog append;
+reject → discard. No auto-append without operator gate.
+
+#### US-0109 integration (`DEPLOY_DEFERRED`)
+
+**US-0109** (deploy smoke) is the downstream writer for `DEPLOY_DEFERRED` deferral rows when
+deploy smoke cap is exhausted. Schema v1 fields: `work_item_kind=deploy`, standard deferral
+register fields per **DEC-0107** §2. US-0107 owns schema, validator, and read paths only — no
+deploy smoke logic in this story.
+
+#### Validate / self-test
+
+```bash
+python scripts/sovereign_loop_lib.py --self-test
+python scripts/sovereign_loop_validate.py --self-test
+python scripts/sovereign_loop_validate.py --repo . --enforce
+pytest -k us0107
+```
+
+#### Parity enforcement
+
+```bash
+python scripts/check_intake_template_parity.py --scope=sovereign-loop
+```
+
+Pair table (`SOVEREIGN_LOOP_PAIRS`): lib, validator, scratchpad, deferrals `.gitkeep`, `DEC-0107.md`.
+
+#### Related artifacts
+
+- **Architecture**: `docs/engineering/architecture.md` `# US-0107`
+- **Reason codes**: `docs/engineering/reason_codes.md` § US-0107
+- **Decision record**: `decisions/DEC-0107.md`
+- **Contract tests**: `tests/us0107_contract_test.py` (8 tests + 2 compose guards)
+
+### Sovereign Role-Behavior Manifest (US-0106)
+
+**Default-off per-role objective + inter-role review obligations**. When `SOVEREIGN_ROLE_MANIFEST=0` (default),
+zero overhead — no manifest reads, no objective injection, no review dispatch. Review spawns are
+supplementary post-phase hooks — they never substitute for the US-0069 producer role.
+
+#### Scratchpad keys
+
+| Key | Values | Default | Notes |
+|-----|--------|---------|-------|
+| `SOVEREIGN_ROLE_MANIFEST` | `0` \| `1` | `0` | Master enable gate. |
+| `SOVEREIGN_ROLE_OBJECTIVE_MAX_CHARS` | int ≥ 1 | `512` | Hard truncate for injection block. |
+| `SOVEREIGN_ROLE_REVIEW_MAX_PER_PHASE` | int ≥ 0 | `2` | Per-phase review dispatch cap. |
+| `SOVEREIGN_ROLE_REVIEW_REWORK_MAX` | int ≥ 0 | `1` | Bounded rework before decision gate. |
+
+#### Enable / disable
+
+```bash
+# Enable sovereign role manifest
+echo "SOVEREIGN_ROLE_MANIFEST=1" >> .cursor/scratchpad.local.md
+
+# Disable (zero overhead)
+echo "SOVEREIGN_ROLE_MANIFEST=0" >> .cursor/scratchpad.local.md
+```
+
+#### Manifest edit operator workflow
+
+1. Open `.cursor/sovereign-role-manifest.yaml` (active) or `template/.cursor/sovereign-role-manifest.yaml.example` (template).
+2. Add role: append `role_id` ∈ {`po`, `tech-lead`, `dev`, `qa`, `release`, `curator`} with `objective_function` (≤ 1024 chars at file; truncated at injection to `SOVEREIGN_ROLE_OBJECTIVE_MAX_CHARS`).
+3. Add obligation: `obligation_id` (unique slug), `reviewer_role`, `target_role`, `trigger_phase` ∈ canonical phase ids, `review_focus` ∈ {`user_value_drift`, `testability`, `buildability`, `deployability`}, `artifact_refs[]`, optional `blocking` (default `false`).
+4. Edit `cross_model_policy.default_order` ∈ {`role_review_first`, `critic_first`, `critic_only`, `role_review_only`} to set critic vs role-review ordering.
+5. Edit `escalation_rules.rework_max` for bounded rework cap.
+6. Run validator: `python scripts/sovereign_role_manifest_validate.py --repo . --enforce`.
+
+#### Validator invocation
+
+```bash
+# Validate single manifest file
+python scripts/sovereign_role_manifest_validate.py --file .cursor/sovereign-role-manifest.yaml
+
+# Validate repo active + template pair
+python scripts/sovereign_role_manifest_validate.py --repo . --enforce
+
+# Lib self-test
+python scripts/sovereign_role_manifest_validate.py --self-test
+```
+
+Success: `[SOVEREIGN_ROLE_MANIFEST_VALIDATION_OK]`.
+Fail: reason codes `SOVEREIGN_ROLE_*` — `SCHEMA_INVALID`, `UNKNOWN_ROLE`, `UNKNOWN_PHASE`, `SECRET_DETECTED`, `OBJECTIVE_OVERFLOW`.
+
+#### Review dispatch troubleshooting
+
+| Reason code | Symptom | Remediation |
+|-------------|---------|-------------|
+| `SOVEREIGN_ROLE_MANIFEST_DISABLED` | `SOVEREIGN_ROLE_MANIFEST=0` — no dispatch | Set `SOVEREIGN_ROLE_MANIFEST=1` to enable |
+| `ROLE_REVIEW_DISPATCH_FAILED` | JSONL append I/O error | Check file permissions on `handoffs/sovereign_role_reviews.jsonl` |
+| `ROLE_REVIEW_SPAWN_FAILED` | Subagent spawn error | Retry spawn; check Task tool availability |
+| `ROLE_REVIEW_BLOCKED` | Blocking review verdict `fail` | Apply escalation: rework (bounded by `SOVEREIGN_ROLE_REVIEW_REWORK_MAX`) or operator decision gate |
+| `ROLE_REVIEW_DEFERRAL_FAILED` | US-0107 deferral append error | Check `handoffs/sovereign_deferrals.jsonl` permissions; fail-open logged |
+| `ROLE_REVIEW_REWORK_CAP` | Rework max exhausted | Operator decision gate: waive findings or abort |
+
+Reviews JSONL: `handoffs/sovereign_role_reviews.jsonl` (v1 schema: `schema_version`, `obligation_id`, `reviewer_role`, `target_role`, `trigger_phase`, `review_focus`, `producer_evidence_ref`, `orchestrator_run_id`, `ts`, `verdict`, `blocking`, `findings_ref`).
+
+#### Validate / self-test
+
+```bash
+python scripts/sovereign_role_manifest_lib.py --self-test
+python scripts/sovereign_role_manifest_validate.py --self-test
+python scripts/sovereign_role_manifest_validate.py --repo . --enforce
+pytest -k us0106
+```
+
+#### Parity enforcement
+
+```bash
+python scripts/check_intake_template_parity.py --scope=sovereign-role-manifest
+```
+
+Pair table (`SOVEREIGN_ROLE_MANIFEST_PAIRS`): scratchpad keys, manifest YAML, example manifest, validator, lib, reviews JSONL, template validator, template lib.
+
+#### Related artifacts
+
+- **Architecture**: `docs/engineering/architecture.md` `# US-0106`
+- **Reason codes**: `docs/engineering/reason_codes.md` § US-0106
+- **Decision record**: `decisions/DEC-0106.md`
+- **Contract tests**: `tests/us0106_contract_test.py` (8 tests + 2 compose guards)
+
+### Parallel Instance Arbitrage (US-0108)
+
+**Default-off parallel execute-phase instance orchestration**. When `SOVEREIGN_PARALLEL_DEV=0` (default),
+zero overhead — no worktrees, no parallel QA, no pick JSON, no resource guard.
+
+#### Scratchpad keys
+
+| Key | Values | Default | Notes |
+|-----|--------|---------|-------|
+| `SOVEREIGN_PARALLEL_DEV` | `0` \| `1` | `0` | Master enable gate. |
+| `AUTO_SOVEREIGN_PARALLEL_N` | int ≥ 1 | `3` | Instances per execute cycle. |
+| `AUTO_SOVEREIGN_PARALLEL_MAX_TOTAL` | int ≥ 1 | `6` | System-wide instance cap. |
+| `AUTO_SOVEREIGN_MERGE_RESOLVE` | `first_pass_wins` \| `last_pass_wins` \| `winner_takes_all` \| `manual` | `first_pass_wins` | Merge policy. |
+| `AUTO_SOVEREIGN_WORKTREE_KEEP` | `0` \| `1` | `0` | Retain loser worktrees for debugging. |
+| `AUTO_SOVEREIGN_PARALLEL_QA` | `0` \| `1` | `0` | Enable parallel QA cross-review (v2). |
+| `AUTO_SOVEREIGN_PARALLEL_QA_ARBITER` | `critic_first_pass` \| `majority_vote` | `critic_first_pass` | QA arbitration strategy. |
+| `AUTO_SOVEREIGN_PARALLEL_ANTI_SLOP_THRESHOLD` | int 0-10 | `6` | Anti-slop floor. |
+| `AUTO_SOVEREIGN_PARALLEL_REWORK_MAX` | int ≥ 0 | `2` | Per-instance rework cap. |
+| `AUTO_SOVEREIGN_PARALLEL_MERGE_TIMEOUT_SEC` | int ≥ 10 | `60` | Merge timeout. |
+| `AUTO_SOVEREIGN_PARALLEL_MODEL_<idx>` | model slug | *(empty)* | Per-instance model override (optional). |
+| `AUTO_SOVEREIGN_PARALLEL_LENS_<idx>` | lens config | *(empty)* | Per-instance lens override (optional). |
+
+#### Enable / disable
+
+```bash
+# Enable parallel dev (N=3 instances)
+echo "SOVEREIGN_PARALLEL_DEV=1" >> .cursor/scratchpad.local.md
+echo "AUTO_SOVEREIGN_PARALLEL_N=3" >> .cursor/scratchpad.local.md
+
+# Disable (zero overhead)
+echo "SOVEREIGN_PARALLEL_DEV=0" >> .cursor/scratchpad.local.md
+```
+
+#### Parallel dev workflow
+
+1. **Create worktrees** (T-002/T-003): `create_worktrees(story_id, n_instances, base_branch)` → isolated
+   `.git/worktrees/us0108-<story_id>-<idx>/` per instance.
+2. **Simulated execute** in each worktree (T-008 step 25).
+3. **Simulated QA** in each worktree (T-008 step 26).
+4. **Select winner** (T-004): `select_winner(qa_results[])` → filter `qa_verdict=pass` → sort `-anti_slop_score`
+   → tie-break earliest `proof_issued_at` → single winner.
+5. **Read anti-slop score** (T-005): `read_anti_slop_score(lens_scores[])` via
+   `sovereign_critic_lib.compute_anti_slop_aggregate` (read-only, US-0104 unchanged).
+6. **Merge winner** (T-006): `merge_winner(winner_ctx, main_branch)` with bounded retry ≤2, then
+   `PARALLEL_DEV_MERGE_CONFLICT` halt. Write-once `handoffs/parallel_dev_pick.json` v1.
+7. **Cleanup** (T-003): winner removed; losers per `AUTO_SOVEREIGN_WORKTREE_KEEP`.
+
+Pick JSON schema v1:
+```json
+{
+  "schema_version": 1,
+  "story_id": "US-0108",
+  "winner_instance_id": "US-0108-inst0",
+  "worktree_path": ".git/worktrees/us0108-US-0108-0",
+  "qa_verdict": "pass",
+  "anti_slop_score": 8,
+  "proof_issued_at": "2026-06-29T22:00:00Z",
+  "merge_policy": "first_pass_wins",
+  "runner_ts_utc": "2026-06-29T22:30:00Z",
+  "orchestrator_run_id": "auto-20260628-04",
+  "loser_instance_ids": ["US-0108-inst1", "US-0108-inst2"]
+}
+```
+
+#### Reason codes
+
+| Code | Meaning |
+|------|---------|
+| `PARALLEL_DEV_DISABLED` | Feature off — backward compat path. |
+| `PARALLEL_DEV_WORKTREE_CREATE_FAILED` | Worktree creation error. |
+| `PARALLEL_DEV_WORKTREE_CLEANUP_FAILED` | Cleanup error (fail-open). |
+| `PARALLEL_DEV_SELECTION_NO_PASS` | No QA pass verdict in any instance. |
+| `PARALLEL_DEV_MERGE_CONFLICT` | Merge conflict after bounded retry. |
+| `PARALLEL_DEV_RESOURCE_CAP_EXHAUSTED` | System-wide cap reached. |
+| `PARALLEL_DEV_RESOURCE_LOCK_FAILED` | Lockfile error. |
+| `PARALLEL_DEV_EXECUTE_FAILED` | Instance execution error. |
+| `PARALLEL_DEV_ANTI_SLOP_BELOW_THRESHOLD` | Winner score below floor. |
+| `PARALLEL_DEV_MERGE_TIMEOUT` | Merge operation timeout. |
+| `PARALLEL_DEV_MANUAL_HALT` | Manual intervention required (`merge_resolve=manual`). |
+| `PARALLEL_DEV_PICK_SCHEMA_INVALID` | Pick JSON schema violation. |
+
+#### Resource guard
+
+- Lockfile: `.git/us0108_parallel_dev.lock`
+- `acquire_parallel_slot(slot_id, repo_root, max_total)` / `release_parallel_slot(slot_id, repo_root)`
+- System cap: `AUTO_SOVEREIGN_PARALLEL_MAX_TOTAL` (default 6)
+- Fail-fast `PARALLEL_DEV_RESOURCE_CAP_EXHAUSTED` when cap reached
+
+#### Validator / self-test
+
+```bash
+# Self-test
+python scripts/parallel_dev_arbiter.py --self-test
+
+# Contract tests
+python -m pytest tests/us0108_contract_test.py -v
+
+# Parity check
+python scripts/check_intake_template_parity.py --scope=sovereign-parallel-dev
+```
+
+#### Compose guards (non-negotiable)
+
+| Compose surface | Rule |
+|-----------------|------|
+| US-0047 (bulk execute) | Step 22 unchanged; system cap checked **after** bulk cap. |
+| US-0092 (full autonomy) | Outer driver unchanged; parallel is execute-phase internal. |
+| US-0103 (ledger) | Schema unchanged; US-0108 reads ledger only. |
+| US-0104 (critic) | Schema unchanged; US-0108 reads `anti_slop_score` only. |
+| US-0107 (sovereign loop) | Deferral register unchanged; US-0108 appends winner/loser outcomes as consumer. |
+
+#### Related artifacts
+
+- **Architecture**: `docs/engineering/architecture.md` `# US-0108`
+- **Reason codes**: `docs/engineering/reason_codes.md` § US-0108
+- **Decision record**: `decisions/DEC-0108.md`
+- **Contract tests**: `tests/us0108_contract_test.py` (8 tests)
+- **Standalone runbook**: `docs/sovereign-runbook-md/US-0108.md`
+
+---
+
+## Self-Healing Deploy Loop (US-0109 / DEC-0109)
+
+**Default-off** (`AUTO_SOVEREIGN_SELF_HEALING_DEPLOY=0`) — zero overhead when off. When enabled,
+adds a post-deploy smoke probe + bounded retry loop on top of US-0054 publish chain.
+
+### Scratchpad keys (schema_v1)
+
+| Key | Values | Default | Notes |
+|-----|--------|---------|-------|
+| `AUTO_SOVEREIGN_SELF_HEALING_DEPLOY` | `0` \| `1` | `0` | Global gate. When `0`, zero overhead — byte-identical US-0054 publish path. |
+| `AUTO_SOVEREIGN_DEPLOY_RETRY_MAX` | int ≥ 1 | `3` | Max retry attempts after probe FAIL. |
+| `AUTO_SOVEREIGN_DEPLOY_SMOKE_TIMEOUT_SEC` | int ≥ 1 | `30` | Per-stage HTTP timeout for health probe. |
+| `AUTO_SOVEREIGN_DEPLOY_PROBE_KIND` | `health_endpoint` \| `acceptance_smoke` \| `both` | `both` | Which stages run during smoke probe. |
+| `SOVEREIGN_DEPLOY_ACCEPTANCE_SMOKE_PATH` | repo-relative path | `tests/deploy_smoke/` | Acceptance smoke tests directory (pytest runner). |
+| `AUTO_SOVEREIGN_DEPLOY_HEALTH_ENDPOINT` | names-only env ref | *(empty)* | Key name in `os.environ` — value is a key name, NOT a URL literal. |
+
+Fail-closed `DEPLOY_HEALING_PROBE_TARGET_MISSING` when health endpoint unresolvable.
+
+### Execute steps 29-31
+
+| Step | Action |
+|------|--------|
+| **29 post-deploy smoke probe** | Two-stage chain `[DEPLOY_SMOKE_PROBE_OK]`. Skip when `0`. |
+| **30 retry loop** | Re-enter publish PASS path on probe FAIL; cap exhaustion → step 31. |
+| **31 DEPLOY_DEFERRED** | Via US-0107 `append_deferral(work_item_kind=deploy)`. Orchestrator continues. |
+
+### Operator remediation
+
+| Reason code | Operator action |
+|-------------|-----------------|
+| `DEPLOY_HEALING_DISABLED` | No action; expected default. Set `=1` to enable. |
+| `DEPLOY_HEALING_SMOKE_HEALTH_FAIL` | Verify env key in scratchpad.local resolves to reachable URL. Re-run probe. |
+| `DEPLOY_HEALING_SMOKE_ACCEPTANCE_FAIL` | Inspect `SOVEREIGN_DEPLOY_ACCEPTANCE_SMOKE_PATH` smoke tests. Fix failures. |
+| `DEPLOY_HEALING_RETRY_ATTEMPT` | Informational per-attempt log; no action required. |
+| `DEPLOY_HEALING_RETRY_CAP_EXHAUSTED` | Raise `AUTO_SOVEREIGN_DEPLOY_RETRY_MAX` if transient; otherwise resolve root cause. |
+| `DEPLOY_HEALING_DEFERRED` | Resolve in `handoffs/sovereign_deferrals.jsonl`; re-run `/release` after fix. |
+| `DEPLOY_HEALING_PROBE_TARGET_MISSING` | Set `AUTO_SOVEREIGN_DEPLOY_HEALTH_ENDPOINT` to valid env key; ensure env var has URL. |
+| `DEPLOY_HEALING_TIMEOUT` | Raise `AUTO_SOVEREIGN_DEPLOY_SMOKE_TIMEOUT_SEC`; investigate startup latency. |
+
+### Validate / self-test
+
+```bash
+python scripts/self_healing_deploy_validate.py --self-test
+python scripts/self_healing_deploy_validate.py --repo . --enforce
+```
+
+### Parity enforcement
+
+```bash
+python scripts/check_intake_template_parity.py --scope=sovereign-self-healing-deploy
+```
+
+Pair table (`SOVEREIGN_SELF_HEALING_DEPLOY_PAIRS`): scratchpad, lib, validator,
+contract tests, runbook, reason_codes — 6 pairs (active + template).
+
+### Compose surfaces (read-only)
+
+| Composed story | US-0109 boundary |
+|----------------|------------------|
+| US-0054 (publish) | Re-enters publish PASS only; publish targets/schema/release-notes UNCHANGED. |
+| US-0100 (changelog) | No changelog writes triggered by US-0109. |
+| US-0103 (ledger) | Schema UNCHANGED; optional `deploy_deferral_id` additive (v1). |
+| US-0107 (sovereign loop) | Consumer of `append_deferral(...)` API only; `work_item_kind=deploy`. |
+| US-0110 (convergence) | Predicate UNCHANGED; US-0110 reads open deferrals (no new logic). |
+
+### Related artifacts
+
+- **Architecture**: `docs/engineering/architecture.md` `# US-0109`
+- **Reason codes**: `docs/engineering/reason_codes.md` § US-0109
+- **Decision record**: `decisions/DEC-0109.md`
+- **Library**: `scripts/self_healing_deploy_lib.py`
+- **Validator**: `scripts/self_healing_deploy_validate.py`
+- **Contract tests**: `tests/us0109_contract_test.py` + `tests/us0109_us0110_compose_test.py`
+
+---
+
+## Release Trigger Adapters (US-0111 / DEC-0111)
+
+**Default source**: `RELEASE_TRIGGER_SOURCE=manual` (zero behavior change vs pre-US-0111 /release path — byte-identical).
+
+### Adapter registry and dispatch
+
+`scripts/release_trigger_adapters.py` provides four adapters:
+- **GitHub webhook** (`github`): Parse `release.tag_name`; query GitHub API for previous tag via `GET /repos/{owner}/{repo}/releases?per_page=100` (sorted by `created_at` desc, skip current); fallback `git ls-remote --tags origin` filtered for semver.
+- **npm publish** (`npm`): Read `npm_package_version` env var; query `npm view {pkg} versions --json` with `RELEASE_TRIGGER_TIMEOUT_SEC` (default 10s); offline fallback `package-lock.json` when `RELEASE_TRIGGER_FALLBACK_TO_LOCAL=1`.
+- **Git tag push** (`git_tag`): Parse `GITHUB_REF=refs/tags/vX.Y.Z` or local `git describe --tags --abbrev=0`; compute previous via `git for-each-ref --sort=-version:refname refs/tags` (semver sort, not date — handles annotated vs lightweight tags).
+- **Manual /release** (`manual`): `TriggerContext(source="manual", version=current, previous_version=None)` — byte-identical to pre-US-0111 /release.
+
+Dispatch via `dispatch_to_adapter(source, env_vars)` → `TriggerContext`. Invalid source → `RELEASE_TRIGGER_SOURCE_INVALID` (fail-closed).
+
+### Scratchpad keys
+
+| Key | Values | Default |
+|-----|--------|---------|
+| `RELEASE_TRIGGER_SOURCE` | `manual` \| `github` \| `npm` \| `git_tag` \| `auto` | `manual` |
+| `RELEASE_TRIGGER_TIMEOUT_SEC` | int ≥ 1 | `10` |
+| `RELEASE_TRIGGER_FALLBACK_TO_LOCAL` | `0` \| `1` | `0` |
+
+### TriggerContext dataclass
+
+```python
+@dataclass
+class TriggerContext:
+    version: str
+    previous_version: Optional[str]
+    source: str  # manual | github | npm | git_tag
+    metadata: Dict[str, Any]
+```
+
+### Version comparison integration (AC-6)
+
+`compare_versions_from_trigger(trigger)` normalizes `trigger.version` and `trigger.previous_version` via `release_changelog_lib.normalize_semver()`. Fail-closed: `RELEASE_TRIGGER_COMPARE_VERSIONS_FAILED` on invalid semver.
+
+### Atomic promotion (AC-7, AC-8)
+
+- **CHANGELOG.md promotion**: `promote_changelog_version(semver, sprint_ids, repo_root)` reuses `release_changelog_lib.promote_unreleased()` unchanged (US-0100 compose). Atomic write via `os.replace(temp, target)` with Windows best-effort retry (0.1s × 2). Fail-closed: `RELEASE_TRIGGER_ATOMIC_PROMOTION_FAILED`.
+- **Per-version notes**: `write_per_version_notes(semver, sprint_ids, repo_root)` writes `handoffs/releases/vX.Y.Z-release-notes.md` atomically. Reuses `release_changelog_lib.build_version_doc()` read-only compose. Fail-closed: `RELEASE_TRIGGER_NOTES_WRITE_FAILED`.
+
+### Ledger event emit (AC-9)
+
+`emit_version_derivation_event(trigger, norm_version, norm_previous, repo_root, scratchpad)`:
+1. Write `handoffs/release_events/{iso-timestamp}-{semver}.json` atomically.
+2. Append to US-0103 ledger via `decision_ledger_lib.append_entry(ledger_path, entry, scratchpad)` with `decision_type="version_derivation"`. Ledger schema unchanged (consumer-only append compose).
+3. Fail-closed: `RELEASE_TRIGGER_EVENT_EMIT_FAILED`.
+
+### Reason codes (9 total — DEC-0111 §7)
+
+| Code | Trigger | Blocking? |
+|------|---------|-----------|
+| `RELEASE_TRIGGER_ADAPTER_FAILED` | Adapter dispatch error | **Yes** |
+| `RELEASE_TRIGGER_TAG_MISSING` | Cannot resolve current tag | **Yes** |
+| `RELEASE_TRIGGER_PREVIOUS_MISSING` | Cannot resolve previous tag | **Yes** |
+| `RELEASE_TRIGGER_PACKAGE_JSON_MISSING` | npm adapter: package.json missing | **Yes** |
+| `RELEASE_TRIGGER_ATOMIC_PROMOTION_FAILED` | Atomic write failed (Windows lock, I/O) | **Yes** |
+| `RELEASE_TRIGGER_NOTES_WRITE_FAILED` | Per-version notes write failed | **Yes** |
+| `RELEASE_TRIGGER_EVENT_EMIT_FAILED` | Ledger/event emit failed | **Yes** |
+| `RELEASE_TRIGGER_COMPARE_VERSIONS_FAILED` | Semver compare failed | **Yes** |
+| `RELEASE_TRIGGER_SOURCE_INVALID` | Unknown source value | **Yes** |
+
+### Operator troubleshooting
+
+| Symptom | Diagnosis | Remediation |
+|---------|-----------|-------------|
+| `RELEASE_TRIGGER_SOURCE_INVALID` on startup | Invalid `RELEASE_TRIGGER_SOURCE` in scratchpad | Set to `manual` (default), `github`, `npm`, `git_tag`, or `auto` |
+| `RELEASE_TRIGGER_TAG_MISSING` in CI | `GITHUB_REF` not set or non-semver | Ensure CI passes `GITHUB_REF=refs/tags/vX.Y.Z` or run `git tag vX.Y.Z && git push --tags` |
+| `RELEASE_TRIGGER_ATOMIC_PROMOTION_FAILED` on Windows | File lock or antivirus holding CHANGELOG.md | Close IDE tabs; retry; check antivirus exclusion list |
+| `RELEASE_TRIGGER_EVENT_EMIT_FAILED` with ledger enabled | Ledger file permissions or schema mismatch | Check `handoffs/sovereign_decisions/decisions.jsonl` writable; verify 12-field schema |
+
+### Compose surfaces (read-only)
+
+| Composed story | US-0111 boundary |
+|----------------|------------------|
+| US-0100 (changelog) | Reuses `promote_unreleased()` and `build_version_doc()` unchanged; no API modifications. |
+| US-0054 (publish) | Dispatches before `/release` path; `release-all.sh` UNCHANGED. |
+| US-0103 (ledger) | Consumer of `append_entry()` API only; `decision_type="version_derivation"` additive. |
+| US-0040 (runbook) | No runbook structure changes; adds new section. |
+| US-0008 (release-all.sh) | UNCHANGED; US-0111 is pre-release dispatch. |
+| US-0107 (sovereign loop) | No sovereign loop changes; US-0111 emits events to ledger. |
+| US-0110 (convergence) | `list_open_deferrals` UNCHANGED; no convergence predicate changes. |
+
+### Parity enforcement
+
+```bash
+python scripts/check_intake_template_parity.py --scope=release-trigger-adapter
+```
+
+Pair table (`RELEASE_TRIGGER_ADAPTER_PAIRS`): lib + template lib + contract tests + runbook + reason_codes + scratchpad + parity itself — 7 pairs (active + template).
+
+### Related artifacts
+
+- **Architecture**: `docs/engineering/architecture.md` `# US-0111`
+- **Reason codes**: `docs/engineering/reason_codes.md` § US-0111
+- **Decision record**: `decisions/DEC-0111.md`
+- **Library**: `scripts/release_trigger_adapters.py`
+- **Contract tests**: `tests/us0111_contract_test.py` (12 tests)
+
+---
+
+## Compose Guards: US-0054, US-0100, US-0110 (read-only boundaries)
+
+Contract tests enforce US-0109 does not modify these upstream surfaces:
+
+### US-0054 — Publish Targets
+
+`test_us0109_us0054_compose_no_publish_semantics_change` verifies:
+- No `RELEASE_PUBLISH_OK` token written by US-0109 code
+- No `release_publish` function calls
+- No `publish_targets` schema modifications
+
+US-0109 reads publish status as an observer; publish logic remains in `scripts/release_publish.py`.
+
+### US-0100 — Changelog / Unreleased Promotion
+
+`test_us0109_us0100_compose_no_changelog_change` verifies:
+- No `changelog` string literals in US-0109 code
+- No `[Unreleased]` version promotion
+- No `changelog_lib` or `version_changelog` imports
+
+US-0109 does not write changelog entries or promote versions.
+
+### US-0110 — Convergence Predicate
+
+`test_us0109_us0110_compose_no_convergence_change` verifies:
+- No `convergence` string literals in US-0109 code
+- No `evaluate_convergence` function calls
+- No imports from `sovereign_convergence_lib`
+
+US-0109 does not participate in convergence evaluation.
+
+---
+
 ## Project run steps
 
 ### Prerequisites