automaton/tasks/model-divergence-enforcement/DECOMPOSITION.md

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.