# DECOMPOSITION — model-divergence-enforcement

## Method

Decompose by **dependency layer**, not by file. Each subtask builds on the previous
one's foundation. The SPEC (`tasks/model-divergence-enforcement/SPEC.md`) defines 3
sequential subtasks with strict dependency ordering.

## Sub-tasks (3, sequential)

### subtask-1: `mde-manifest-detection`
**Scope:** `models.json` schema + loader + `scripts/detect_models.py` probe + install integration.
**Files touched:**
- `scripts/detect_models.py` (new — probe opencode.json providers + localhost endpoints 8080/11434/1234/8000)
- `scripts/status.py` (add `_load_models_manifest()` helper, `_get_mode()` — single vs multi-LLM)
- `scripts/install.sh` (call `detect_models.py` after `vram_detect.py`)
- `scripts/update.sh` (same)
- `scripts/upgrade.sh` (same)
- `config.md` (add `## Available Models` section template)
- `prompts/onboarding.md` (Step 2d — model config check)
- `tests/test_model_divergence.py` (new — manifest loading, single vs multi mode, missing file backward compat)
**Not touched:** `status.py --transition`, `--claim`, `--audit`, `loop-runner.py`, dashboard code.
**Acceptance:**
1. `models.json` missing → `_get_mode()` returns `"single"`, all model commands are no-ops.
2. `models.json` with 0-1 models → `_get_mode()` returns `"single"`.
3. `models.json` with 2+ models → `_get_mode()` returns `"multi"`.
4. `detect_models.py` probes localhost endpoints and prints a candidate manifest (JSON to stdout).
5. `pytest tests/test_model_divergence.py -v` green.
6. `pytest tests/ -q` green (no regressions).
**Peak context estimate:** ~6k tokens (new script + status.py helper + tests).
**Run order:** first. Foundational — subtasks 2 and 3 depend on this.

### subtask-2: `mde-interactive-enforcement`
**Scope:** `.state.models` schema + conflict matrix + `--transition --model` / `--claim --model` enforcement + audit category + dashboard badges.
**Depends on:** subtask-1 (needs `_load_models_manifest()` and `_get_mode()`).
**Files touched:**
- `scripts/status.py`:
  - `CONFLICT_MATRIX` constant (locked matrix from SPEC §15)
  - `_check_conflict(current_phase, current_model, next_phase, next_model)` helper
  - `cmd_transition`: add `--model` arg; in multi-LLM mode, check conflict matrix before allowing transition
  - `cmd_claim`: add `--model` arg; refuse if model conflicts with existing `.state.models` entry
  - `cmd_audit`: add `model_divergence` category (scan `.state.models` for violations)
  - `.state.models` writer (JSON: `{implementer: "model-name", code_reviewer: "model-name", ...}`)
- `automaton/dashboard/html/dashboard.js`: model badge on task cards (read from `.state.models`)
- `automaton/dashboard/ui/app.py`: include `.state.models` in `/api/tasks` response
- `tests/test_model_divergence.py`: conflict matrix tests, auto-assign tests, audit category tests, dashboard badge tests
**Not touched:** `loop-runner.py`, `loop.json` schema, `--check-gate`.
**Acceptance:**
1. Single-LLM mode: `--transition --model <name>` records model but never refuses. Advisory printed once if `advised: true`.
2. Multi-LLM mode: `--transition --model <name>` refuses if `<name>` conflicts with `.state.models` for a conflicting phase.
3. Multi-LLM mode: `--claim --model <name>` refuses on conflict.
4. `--audit` flags `model_divergence` violations (e.g., same model in implementer + code_reviewer).
5. Dashboard task cards show model badges when `.state.models` exists.
6. `pytest tests/test_model_divergence.py -v` green.
7. `pytest tests/ -q` green (no regressions).
**Peak context estimate:** ~8k tokens (status.py surgery + dashboard + tests).
**Run order:** second, AFTER subtask-1.

### subtask-3: `mde-loop-enforcement`
**Scope:** `loop.json` per-role model field + `{model}` substitution in loop-runner + `--check-gate` model-divergence brake.
**Depends on:** subtask-2 (needs `CONFLICT_MATRIX` and `_check_conflict`).
**Files touched:**
- `scripts/loop-runner.py`:
  - `_invoke_harness` (line 366-404): add `{model}` placeholder substitution from `loop.json` role config
  - `_find_work_backlog`: no change (already supports `work_source.area`)
- `scripts/status.py`:
  - `--check-gate`: add model-divergence brake gate (loop-verify model ≠ loop-implement model in multi-LLM mode)
  - `cmd_install_schedule` / `cmd_create_loop`: validate `loop.json` per-role `model` fields against `models.json`
- `templates/loops/`: update loop templates with `roles` schema example
- `design/loops/technical.md`: document `{model}` substitution
- `tests/test_model_divergence.py`: loop model binding tests, `{model}` substitution tests, check-gate halt tests
**Not touched:** interactive `--transition` / `--claim` (already done in subtask-2), dashboard badges (already done in subtask-2).
**Acceptance:**
1. `loop.json` with `roles.implementer.model: "llama-3.3-70b"` → `_invoke_harness` substitutes `{model}` in harness command.
2. `loop.json` without per-role `model` → defaults to `models.json` `default` model.
3. `--check-gate` in multi-LLM mode halts loop if loop-verify model = loop-implement model.
4. `--check-gate` in single-LLM mode does NOT halt (advisory only).
5. `pytest tests/test_model_divergence.py -v` green.
6. `pytest tests/ -q` green (no regressions).
**Peak context estimate:** ~6k tokens (loop-runner + check-gate + tests).
**Run order:** third, AFTER subtask-2.

## Dependency graph

```
subtask-1 (manifest+detection)
    │
    ▼
subtask-2 (interactive enforcement+audit)
    │
    ▼
subtask-3 (loop enforcement+dashboard)
    │
    ▼
parent model-divergence-enforcement → complete
```

Parent is complete only when ALL three subtasks pass their acceptance criteria AND
`pytest tests/ -q` is green.

## Parent non-goals

- No rule agents (FW-2, FW-3) — separate backlog items that *consume* this feature.
- No agent tab redesign (FW-1) — separate backlog item, no dependency on this task.
- No model capability inspection — framework never inspects capability/size/provider (decision D8).
- No `detect_models.py` auto-writing `models.json` — detection is advisory; user confirms the manifest.

## Fallback

If any subtask hits a blocker (e.g., `status.py` surgery is too large for context budget),
it must report back to the Orchestrator via `human_intervention` rather than skipping
enforcement logic. Partial enforcement is worse than no enforcement — it creates a
false sense of security.