automaton/tasks/runnable-test-suite/subtasks/make-tests-runnable/IMPLEMENTATION.md

# IMPLEMENTATION — make-tests-runnable

Parent: `runnable-test-suite` (see PARENT_SPEC.md)

## Summary

All 8 in-scope requirements were implemented. The test suite goes from
"No module named pytest" to **198 passed, 3 collection errors**. The 3 errors
are a STOP-and-report trigger: PEP 604 union syntax (`Path | None`) in
out-of-scope dashboard source files, incompatible with the stock macOS Python
3.9.6. These files are NOT in this sub-task's 7-file scope and were not touched.

## Files changed

- `requirements.txt` (NEW) — created at repo root with `pytest==7.4.4`.
- `AGENTS.md` — `python -m` → `python3 -m` (7 occurrences); added install note
  `*Install: pip3 install -r requirements.txt*` after "## Build & Test Commands".
- `README.md` — `python ~/.automaton/scripts/status.py` → `python3 ...` (16
  occurrences); `python -m automaton.dashboard` → `python3 -m automaton.dashboard`.
- `automaton/dashboard/README.md` — `python -m automaton.dashboard` → `python3 -m
  automaton.dashboard` (4 occurrences).
- `prompts/orchestrate.md` — `python ~/.automaton/scripts/status.py` → `python3
  ...` (17 occurrences).
- `scripts/install.sh` — restructured early-exit `exit 0` to if/else so the
  appended venv block is reachable on existing installs; appended idempotent
  venv block (`python3 -m venv .venv` + pip install requirements.txt).
- `CHANGELOG.md` — added 3 entries under `[unreleased]`: two `### Added`
  (requirements.txt, install.sh venv) and one `### Changed` (python → python3).

## Acceptance criteria

| # | Criterion | Status |
|---|-----------|--------|
| 1 | `pip3 install -r requirements.txt` exits 0 | PASS |
| 2 | `python3 -m pytest tests/ -v` exits 0 (N passed, 0 errors) | **FAIL** — exit 2, 3 collection errors |
| 3 | `python3 -m py_compile automaton/**/*.py automaton/dashboard/**/*.py scripts/*.py` exits 0 | PASS |
| 4 | `bash -n scripts/*.sh` exits 0 | PASS |
| 5 | `bash scripts/install.sh` exits 0 and creates `.venv/` containing pytest | PASS (.venv/bin/pytest = 7.4.4) |
| 6 | `rg "^python \|"python "` sweep returns zero matches | PASS (exit 1 = no matches) |
| 7 | Streak: 10 consecutive clean `pytest tests/ -v` runs | **BLOCKED** by #2 |

## Streak verifier result

Not run — blocked by acceptance #2. The suite never reaches a clean pass on
the stock Python 3.9.6 interpreter, so a 10-run streak is impossible without
fixing the out-of-scope PEP 604 syntax. Attempt 1 of 5 stopped at the
STOP-and-report trigger.

## STOP-and-report trigger

**Trigger:** Tests fail for a reason OTHER than missing pytest.

**Failing tests (collection errors):**
- `tests/test_app.py`
- `tests/test_board.py`
- `tests/test_scope.py`

**Root cause:** PEP 604 union type syntax (`X | None`) evaluated at class/function
definition time. This syntax requires Python 3.10+. The stock macOS
CommandLineTools Python is 3.9.6.

**Out-of-scope files containing the bug (NOT touched):**
- `automaton/dashboard/core/scope.py:6` — `def find_automaton_root(start: Path | None = None) -> Path | None:`
- `automaton/dashboard/core/board.py:40` — `def __init__(self, tasks: list[Task] | None = None, ...)`
- `automaton/dashboard/ui/app.py:15` — transitive failure (imports `scope`)

**Traceback (representative, test_scope.py):**
```
tests/test_scope.py:7: in <module>
    from automaton.dashboard.core.scope import detect_scope, find_automaton_root
automaton/dashboard/core/scope.py:6: in <module>
    def find_automaton_root(start: Path | None = None) -> Path | None:
E   TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
```

**Suggested fix (for whoever owns these files):** Add `from __future__ import
annotations` at the top of `scope.py`, `board.py`, and any other dashboard
module using PEP 604 syntax. This makes annotations lazy (string-evaluated),
restoring Python 3.9 compatibility without changing any type semantics.
Alternatively, replace `X | None` with `Optional[X]` from `typing`.

## Anomalies / scope notes

1. **install.sh restructure:** The SPEC says "append a venv block" to
   `install.sh`. A literal append at the end would be unreachable because the
   script's early-exit (`if [ -d "$FRAMEWORK_DIR" ]; then ... exit 0`) fires
   before the end on any system where `~/.automaton` already exists. To satisfy
   acceptance #5 ("creates `.venv/` containing pytest"), the early-exit was
   converted from `exit 0` to an `else` branch, and the venv block was appended
   after the closing `fi` so it runs unconditionally. The venv block text matches
   the SPEC exactly. The script remains `set -e`-safe and re-runnable.

2. **Python 3.13 available but not used:** `/opt/homebrew/bin/python3.13` exists
   on this system, but the parent SPEC mandates "Stock python3 + pip3 only" —
   stock is 3.9.6 from CommandLineTools. Using Homebrew Python would violate the
   parent constraint and mask the real bug (PEP 604 syntax in framework code).

3. **198/201 tests pass with `--continue-on-collection-errors`:** The 3 erroring
   tests are all dashboard tests that transitively import `scope.py` or
   `board.py`. No test under `tests/` was edited. No out-of-scope source file
   was edited.

4. **Not vram_detect:** The failure is NOT in `test_vram_detect.py` or
   `vram_detect.py`. That sub-task's scope is unaffected.

## Scope extension: future-annotations fix

The Orchestrator extended this sub-task's scope to include the 3 dashboard
source files previously reported as out-of-scope (STOP-and-report trigger
above). The fix is purely a compatibility shim: add `from __future__ import
annotations` as the first import line (after the module docstring) so PEP 604
`X | Y` annotations become lazy strings (PEP 563) and the files import on
stock Python 3.9.6. No signatures, types, or behavior were changed.

### Files patched

- `automaton/dashboard/core/scope.py` — added `from __future__ import annotations` after docstring (PEP 604 at `find_automaton_root(start: Path | None = None) -> Path | None`).
- `automaton/dashboard/core/board.py` — added `from __future__ import annotations` after docstring (PEP 604 at `KanbanBoard.__init__(self, tasks: list[Task] | None = None, ...)`).
- `automaton/dashboard/ui/app.py` — added `from __future__ import annotations` after docstring (PEP 604 at `_get_review_path(self, task_name: str) -> Path | None`; also transitively imports scope/board).

A `rg` sweep of `automaton/dashboard/` for PEP 604 union syntax found no
other dashboard modules using `X | Y` at definition time — only the three
files above. No spurious future-imports were added to modules that don't need
it.

### Test results after the fix

- `python3 -c "import automaton.dashboard.core.scope, automaton.dashboard.core.board, automaton.dashboard.ui.app; print('IMPORTS_OK')"` → `IMPORTS_OK` (no TypeError on Python 3.9.6).
- `python3 -m pytest tests/ -v` → **224 passed, 0 errors** (up from 198 passed / 3 collection errors).

### Streak result

`STREAK_COMPLETE attempt=1 clean=10/10` — 10 consecutive clean
`python3 -m pytest tests/ -q` passes on the first attempt, no resets needed.

### Acceptance criteria (re-checked after extension)

| # | Criterion | Status |
|---|-----------|--------|
| 1 | `pip3 install -r requirements.txt` exits 0 | PASS |
| 2 | `python3 -m pytest tests/ -v` exits 0 (N passed, 0 errors) | **PASS** — 224 passed, 0 errors |
| 3 | `python3 -m py_compile ...` exits 0 | PASS |
| 4 | `bash -n scripts/*.sh` exits 0 | PASS |
| 5 | `bash scripts/install.sh` exits 0 and creates `.venv/` containing pytest | PASS |
| 6 | `rg` sweep returns zero matches | PASS (exit 1 = no matches) |
| 7 | Streak: 10 consecutive clean pytest runs | **PASS** — 10/10 on attempt 1 |