automaton/tasks/cleanup-cruft/SPEC.md

Clean Up Framework Cruft

Goal

Remove or fix a collection of small issues identified by both audits: stray files, stale dependencies, empty directories, incorrect documentation, and unused wrapper scripts.

Requirements

R1. Delete or relocate debug_root.py

debug_root.py (9 lines) is a development diagnostic script at the framework root. It doesn't belong there.

Fix: Delete it. The functionality is covered by find_automaton_root tests and the dashboard scope endpoint.

R2. Drop stale inotify extra from pyproject.toml

pyproject.toml:13 declares dashboard = ["inotify>=0.2"] but the file-system watcher was removed in remove-file-system-watcher task. Zero references to inotify exist anywhere in automaton/ source or in automaton/dashboard/README.md.

Fix: Remove the dashboard optional dependency group from pyproject.toml. Also remove the inotify mention from test_additive_extension_model/SPEC.md if present.

R3. Delete empty ui/widgets/ directory

automaton/dashboard/ui/widgets/ is an empty directory with no __init__.py and no purpose. It was likely intended for future widget components that were never built.

Fix: Delete the directory.

R4. Fix config.md system requirements claim

config.md:58-61 says RAM detection uses free. The actual code (vram_detect.py:137-162) reads /proc/meminfo and sysctl hw.memsize — it never calls free.

Fix: Update config.md:60 from:

- **/proc/meminfo**: Required for RAM detection (Linux)

to include macOS and remove the free claim:

- **/proc/meminfo**: Required for RAM detection (Linux)
- **sysctl**: Used for RAM detection on macOS

R5. Document or delete scripts/dashboard.sh

scripts/dashboard.sh (11 lines) wraps python -m automaton.dashboard. It works correctly but is not documented in README or dashboard README.

Fix: Keep the script (it's a valid convenience wrapper) and document it in README.md under the Dashboard section. Add: Or run the convenience wrapper: bash ~/.automaton/scripts/dashboard.sh

R6. Fix _find_tasks_dir return type

ui/app.py:107-109:

def _find_tasks_dir(project_root: Path) -> Path | None:
    tasks_dir = project_root / ".automaton" / "tasks"
    return tasks_dir if tasks_dir.exists() else tasks_dir

The logic return tasks_dir if tasks_dir.exists() else tasks_dir is tautological (returns tasks_dir either way). The type hint says Path | None but actually always returns Path.

Fix: Change to return tasks_dir if tasks_dir.exists() else None or simplify since callers already handle missing dirs. Simplest fix: remove the condition and just return tasks_dir. discover_tasks() already returns [] for non-existent dirs and callers check if tasks_dir.

R7. Fix __main__.py:19 sys.path hack

sys.path.insert(0, str(Path(__file__).parent.parent.parent))

This points to /.automaton which is already the package root. It does nothing when run via python -m automaton.dashboard from inside the framework directory. It may cause issues if ~/.automaton is not the working directory and isn't on PYTHONPATH.

Fix: Remove the sys.path manipulation. When installed properly, the package is already importable.

Acceptance Criteria

• debug_root.py deleted
• pyproject.toml no longer contains dashboard = ["inotify>=0.2"]
• automaton/dashboard/ui/widgets/ directory deleted
• config.md line 60 updated to sysctl for macOS, no mention of free
• scripts/dashboard.sh documented in README.md Dashboard section
• _find_tasks_dir() simplified to return tasks_dir with updated docstring/type hint
• __main__.py:19 line removed
• python -m pytest tests/ still passes (72/72)
• python -m py_compile automaton/dashboard/*.py automaton/dashboard/core/*.py automaton/dashboard/ui/*.py clean
• python -m automaton.dashboard starts correctly after __main__.py fix

Non-Goals

• Not reformatting or restructuring files beyond the listed changes
• Not adding new tests (existing coverage is sufficient for these mechanical changes)