automaton/tasks/complete/fix-install-update-flow/RESEARCH.md

# RESEARCH: fix-install-update-flow

## Objective

Fix 5 issues in the install/update flow identified in the loop v1 design plan.

## Issues

### Issue 1: Hardcoded git URL (D11)

`install.sh` line 11: `git clone http://10.37.0.86:3003/hermes/automaton "$FRAMEWORK_DIR"`

D11: "Install requires user-supplied git URL; refuse with irreversibility warning if absent."

The URL is a private Gitea instance. Public users cannot clone from it. The install script should accept a URL as `$1` and refuse if not provided.

### Issue 2: `.venv` cwd bug

`install.sh` lines 87-91:
```bash
if [ ! -d ".venv" ]; then
  python3 -m venv .venv
fi
.venv/bin/pip install --quiet --upgrade pip
.venv/bin/pip install --quiet -r requirements.txt
```

This runs in whatever directory the user is in when they run `install.sh`, not in `$FRAMEWORK_DIR`. The `.venv` is created in the wrong directory and `requirements.txt` is not found (it's in `$FRAMEWORK_DIR`).

Fix: `cd "$FRAMEWORK_DIR"` before the venv setup, or use absolute paths.

### Issue 3: Windows venv path

`.venv/bin/pip` is Unix-specific. On Windows, the path is `.venv/Scripts/pip.exe`.

Fix: detect platform and use the correct path. Or use `python3 -m pip` which works on all platforms.

### Issue 4: Hook copy-vs-symlink inconsistency

- `install-hooks.sh`: uses `cp` (copy)
- `update.sh`: uses `ln -sf` (symlink)
- `upgrade.sh`: uses `ln -sf` (symlink)

Copy is safer (works on Windows, survives framework deletion) but doesn't auto-update. Symlink auto-updates but may not work on Windows (Git Bash with MSYS).

Fix: standardize on copy (matching `install-hooks.sh`). Update `update.sh` and `upgrade.sh` to use `cp` instead of `ln -sf`. This is simpler and more portable. The downside (hooks don't auto-update) is already documented in `install-hooks.sh`: "To reinstall after automaton update, re-run this script."

### Issue 5: Missing `--version` check

`install.sh` doesn't verify the framework is working after install. Adding `status.py --version` as a smoke test catches Python issues, missing files, etc.

Fix: add `python3 "$FRAMEWORK_DIR/scripts/status.py" --version` at the end of install.sh.

## Current File States

### install.sh
- Hardcoded URL on line 11
- `.venv` setup at lines 87-91 runs in CWD
- No platform detection for venv paths
- No version check

### update.sh
- Uses `ln -sf` for hooks at lines 67-73
- No venv handling (doesn't touch .venv)

### upgrade.sh
- Uses `ln -sf` for hooks at lines 78-98
- Has more sophisticated hook handling (checks for existing symlinks)

### install-hooks.sh
- Uses `cp` for hooks at line 37
- Already the correct approach

## Design Decisions

### D1: Git URL argument
```bash
GIT_URL="${1:-}"
if [ -z "$GIT_URL" ]; then
  echo "ERROR: Git URL required."
  echo "Usage: ./install.sh <git-url>"
  echo "Example: ./install.sh https://github.com/user/automaton.git"
  echo ""
  echo "The framework is cloned to ~/.automaton and cannot be auto-updated"
  echo "from a different URL later. Choose your URL carefully."
  exit 1
fi
git clone "$GIT_URL" "$FRAMEWORK_DIR"
```

### D2: Fix .venv cwd
Move the venv setup inside the `else` block (after clone), or use `cd "$FRAMEWORK_DIR"` before it. Also use `$FRAMEWORK_DIR/requirements.txt`.

### D3: Use `python3 -m pip` instead of `.venv/bin/pip`
`python3 -m pip` works on all platforms. The venv's `python3` is at `.venv/bin/python3` (Unix) or `.venv/Scripts/python.exe` (Windows). But if we activate the venv first, `python3 -m pip` uses the venv's pip. Simpler: use the venv's python directly with `-m pip`.

Actually, the simplest fix: use `$FRAMEWORK_DIR/.venv/bin/python3 -m pip` on Unix and `$FRAMEWORK_DIR/.venv/Scripts/python.exe -m pip` on Windows. Or detect the platform.

Even simpler: just detect the venv python path:
```bash
if [ -f "$FRAMEWORK_DIR/.venv/bin/python3" ]; then
  VENV_PY="$FRAMEWORK_DIR/.venv/bin/python3"
elif [ -f "$FRAMEWORK_DIR/.venv/Scripts/python.exe" ]; then
  VENV_PY="$FRAMEWORK_DIR/.venv/Scripts/python.exe"
else
  VENV_PY="python3"
fi
```

### D4: Standardize hooks on copy
Change `update.sh` and `upgrade.sh` to use `cp` instead of `ln -sf`, matching `install-hooks.sh`.

### D5: Version check
Add at the end of install.sh:
```bash
python3 "$FRAMEWORK_DIR/scripts/status.py" --version || echo "WARNING: status.py --version failed"
```