automaton/tasks/runnable-test-suite/DECOMPOSITION.md

DECOMPOSITION — runnable-test-suite

Method

Decompose by capability boundary, not by file. Each sub-task is independently verifiable and independently mergeable. Local-LLM context budget per sub-task: max 9k tokens peak on this box (32GB RAM, no GPU, Model: auto).

Sub-tasks (3)

subtask-1: make-tests-runnable

Scope: pytest install path + python → python3 doc sweep + streak verifier. Files touched: requirements.txt (new), AGENTS.md, README.md, automaton/dashboard/README.md, prompts/orchestrate.md, scripts/install.sh (append venv snippet, idempotent), CHANGELOG.md. Not touched: vram_detect.py, status.py, any test logic. Acceptance: pip3 install -r requirements.txt && python3 -m pytest tests/ -v exits 0 from a clean clone; 10 consecutive clean streak; rg "^python " returns zero matches in docs/prompts. Peak context estimate: ~4k tokens (mostly mechanical doc edits). Fits easily. Run order: first. Establishes the green-test baseline the other sub-tasks need.

subtask-2: vram-detect-cross-platform

Scope: Make scripts/vram_detect.py work on macOS, Windows, Linux without behavior change on Cachyos/Linux. Pure detection logic — no CLI/JSON-shape changes. Files touched: scripts/vram_detect.py only. Functions to refactor (by line in current file):

• detect_gpu_vram() (vram_detect.py:73-108): branch on platform.system().
  • Linux: keep nvidia-smi → lspci -vnn path.
  • macOS: add system_profiler SPDisplaysDataType → parse VRAM (Total) and Chipset Vendor (Apple Unified Memory counts as VRAM). Probe ioreg -c IOPlatformDevice only if system_profiler is unavailable.
  • Windows: add wmic path win32_VideoController get AdapterRAM,Name (deprecated but ubiquitous); fallback to PowerShell Get-CimInstance Win32_VideoController -Property AdapterRAM. Sum across GPUs.
• detect_ram() (vram_detect.py:137-162): branch on platform.system().
  • Linux: keep /proc/meminfo.
  • macOS: keep sysctl -n hw.memsize (already works as fallback).
  • Windows: add wmic ComputerSystem get TotalPhysicalMemory; PowerShell fallback (Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory.
• MODEL_CONTEXT_WINDOWS (vram_detect.py:24-47): add local-LLM entries: llama-3.1-8b, llama-3.3-70b, qwen2.5-7b, qwen2.5-72b, mistral-7b, mistral-large, deepseek-r1, deepseek-v3, glm-4, glm-4.5, gemma-2, gemma-2-27b, phi-3, phi-4. Use community-published context sizes. No fabricating — every entry must cite the source model card in a comment.
• detect_model_context() (vram_detect.py:175-228): add ollama list probe when no config file specifies a model. Pick the first running model name and look it up.
• run_command() (vram_detect.py:54-70): on Windows, route PowerShell cmdlets via powershell -NoProfile -Command "..." wrapper. Keep shutil.which gating. Not touched: test files (those are subtask-3), JSON output shape, CLI args. Acceptance on this machine (Darwin): python3 vram_detect.py prints macOS VRAM (non-zero on Apple Silicon), RAM 32GB, recommends ≥8k target. JSON has gpu_vram_gb > 0. On Linux (CI), output unchanged from current. Anti-spin rail: if a new entry in MODEL_CONTEXT_WINDOWS is unknown, fail open with 0, do NOT guess. Per SPEC, wrong-context detection is worse than none. Peak context estimate: ~7k tokens (single 536-line file, surgical edits). Fits. Run order: second, parallel-ok with subtask-1 (independent files).

subtask-3: vram-detect-cross-platform-tests

Scope: pytest tests proving cross-platform branches without hitting real hardware. Files touched: tests/test_vram_detect.py only. Patterns:

• Parametrize detect_ram across Linux/Darwin/Windows with monkeypatch on platform.system, Path.exists, subprocess.run, and Path.read_text; assert correct KB returned and correct print lines emitted (capfd).
• Parametrize detect_gpu_vram with mocked system_profiler / wmic / nvidia-smi stdout fixtures (kept as multiline string constants).
• Assert unknown model name returns 0 (fail-open contract from subtask-2).
• Assert _lookup_model_context picks the longest matching prefix (so llama-3.1-8b-instruct matches llama-3.1-8b).
• Assert existing Linux/Cachyos path still parses /proc/meminfo (regression).
• No live subprocess against real system_profiler/nvidia-smi — every call goes through monkeypatch.setattr. Not touched: vram_detect.py itself, any other source file, any prompt. Acceptance: added tests pass; total suite still 10-streak clean. Peak context estimate: ~5k tokens. Fits. Run order: third, AFTER subtask-2 (depends on its function signatures).

Dependency graph

subtask-1 ─┐
            ├─> parent done
subtask-2 ─┤
            └─> subtask-3 ──> parent done

Parent runnable-test-suite is complete only when ALL three sub-tasks pass the streak verifier from the SPEC (10 consecutive clean python3 -m pytest tests/ -v).

Parent non-goals

• No usage of psutil, wmi, pywin32, or other new third-party deps. Pure stdlib (platform, subprocess, shutil, re, sys). Per SPEC constraint #1.
• No regression allowed on Cachyos/Linux output — the original author's box must produce identical JSON. Add a Linux-fixture test to lock this in.
• No removal of the MODEL_CONTEXT_WINDOWS OpenAI/Anthropic entries — additive only.

Fallback

If any sub-task hits the captures-skipped-behavior it must report back to the Orchestrator rather than edit a passing test to make itself happy. That is the SPEC anti-spin rule (#9 in the article).

Verifier (the independent eyes inside the loop)

The streak verifier — python3 -m pytest tests/ -v × 10 — IS the separate checker model from the article (#2, Boris's verifier loop). The local LLM does not grade its own homework: a different invocation runs the suite after each implement pass and the count resets on any non-zero exit.