automaton/tasks/add-self-improvement-loop/RESEARCH.md

RESEARCH: add-self-improvement-loop

Objective

Make the self-improvement loop default-on at install time (D21). The template templates/loops/self-improvement/loop.json was already created in task 6. This task wires it into install.sh and update.sh so that:

• Fresh installs get the loop created and scheduled automatically
• Existing users who run update.sh get the loop bootstrapped (idempotent -- skip if already exists)

Current State

install.sh (lines 1-79)

• Clones repo to ~/.automaton
• Runs VRAM detection
• Registers pre-edit guards via register-guards.sh
• Sets up .venv and pip deps
• Does NOT create any loops

update.sh (lines 1-74)

• Pulls latest from git
• Checks for deprecated file locations
• Registers guards
• Installs git hooks in current project
• Does NOT create any loops

--create-loop (status.py:1773)

• Takes --create-loop <name>, --from-template <name>, --project <path>
• Creates ~/.automaton/loops/<name>/ (when project is ~/.automaton/)
• Copies loop.json from template, patches name field
• Creates .state.loop with initial state (running)
• Creates empty .state.log
• Returns error if loop already exists

--install-schedule (status.py:1807)

• Takes --install-schedule <name>, --interval <seconds>, --project <path>
• Generates OS-specific tick stub (automaton-loop-tick.sh or .bat)
• Installs OS schedule unit (launchd plist on macOS, cron on Linux, schtasks on Windows)
• Interval defaults to loop.json schedule.interval_seconds or 3600

_loops_dir (status.py:1609)

• When project is ~/.automaton/, loops dir is ~/.automaton/loops/
• When project is other, loops dir is <project>/.automaton/loops/

Design Decisions

D1: Where to add the install hook

In install.sh, after the clone and guard registration, add:

# Bootstrap self-improvement loop (default-on, D21)
python3 "$FRAMEWORK_DIR/scripts/status.py" --create-loop self-improvement \
  --from-template self-improvement --project "$FRAMEWORK_DIR"
python3 "$FRAMEWORK_DIR/scripts/status.py" --install-schedule self-improvement \
  --interval 3600 --project "$FRAMEWORK_DIR"

D2: Where to add the update hook

In update.sh, after the git pull and guard registration, add an idempotent bootstrap:

# Bootstrap self-improvement loop if not present (default-on, D21)
if [ ! -d "$FRAMEWORK_DIR/loops/self-improvement" ]; then
  python3 "$FRAMEWORK_DIR/scripts/status.py" --create-loop self-improvement \
    --from-template self-improvement --project "$FRAMEWORK_DIR"
  python3 "$FRAMEWORK_DIR/scripts/status.py" --install-schedule self-improvement \
    --interval 3600 --project "$FRAMEWORK_DIR"
fi

D3: Test approach

The test test_self_improvement_installs_default_on should verify that install.sh contains the create-loop and install-schedule commands for the self-improvement loop. A full integration test (actually running install.sh) would require a mock git clone target and is fragile. Instead, test the script content for the required commands, and test that --create-loop self-improvement --from-template self-improvement --project <framework> produces the expected directory structure (this is already tested in the status.py tests but we add a specific test for the self-improvement template).

D4: User opt-out

Users can disable the self-improvement loop with:

python3 ~/.automaton/scripts/status.py --pause-loop self-improvement --project ~/.automaton/

This should be documented in the install output and README.

Risks

• install.sh failure: if --create-loop fails (e.g. Python not in PATH yet), install.sh should continue (the loop is optional, not critical for framework operation). Use || true to non-fatal the loop bootstrap.
• update.sh idempotency: the if [ ! -d ... ] check ensures existing users don't get errors on repeated updates.
• Platform differences: --install-schedule handles platform dispatch internally. No shell-level platform checks needed.