Archive completed tasks, add cleanup commands, self-documenting dashboard UI

- Archive 79 completed framework-dev tasks from tasks/ -> tasks/complete/ - status.py: add --cleanup-done and --install-cleanup-schedule commands - Add scripts/automaton-cleanup.sh for periodic task archiving - Dashboard: rename 'Background' tab -> 'Agent', 'Cleanup' agent -> 'Completed Task Archiver', remove redundant group headers and pill badges, dim inactive agent placeholders - .rules.md: add Self-Documenting UI Names rule - New tests: test_cleanup_done.py, expanded test_app.py and test_task.py
2026-06-24 22:43:33 -04:00
parent e13513faaa
commit 4a2301b077
572 changed files with 856 additions and 101 deletions
@@ -0,0 +1 @@
+complete
@@ -0,0 +1,2 @@
+research:approved|2026-06-23T13:08:35.250948+00:00|user
+code_review:approved|2026-06-23T13:10:59.658295+00:00|user
@@ -0,0 +1,59 @@
+# ADVERSARIAL_BUG_REPORT: fix-install-update-flow
+
+## Methodology
+
+Targeted attack on:
+1. Shell injection via `$GIT_URL`
+2. Path traversal via `$FRAMEWORK_DIR`
+3. Race condition on `.venv` creation
+4. Hook source file missing
+5. `set -e` interaction with `|| true`
+
+## Findings
+
+### Attack 1: Shell injection via `$GIT_URL` -- NOT VULNERABLE
+
+`$GIT_URL` is passed as a double-quoted argument to `git clone "$GIT_URL" "$FRAMEWORK_DIR"`. The shell does not interpret special characters inside double quotes in argument position. `git clone` treats it as a URL, not a shell command. No injection vector.
+
+**Verdict:** NOT VULNERABLE
+
+### Attack 2: Path traversal via `$FRAMEWORK_DIR` -- NOT VULNERABLE
+
+`$FRAMEWORK_DIR` is set to `$HOME/.automaton` at the top of the script. It is not derived from user input. All paths constructed with `$FRAMEWORK_DIR` are safe.
+
+**Verdict:** NOT VULNERABLE
+
+### Attack 3: Race condition on `.venv` creation -- NOT EXPLOITABLE
+
+If two installs run concurrently (unlikely for a per-user framework), both might try to create `.venv` simultaneously. `python3 -m venv` creates the directory atomically. If it already exists, it updates in place. No data corruption.
+
+**Verdict:** NOT EXPLOITABLE
+
+### Attack 4: Hook source file missing -- HANDLED
+
+All three scripts check `[ -f "$HOOK_SRC" ]` or `[ -f "$SOURCE" ]` before copying. If the source is missing, `install-hooks.sh` prints a WARNING and continues. `update.sh` skips the hook. `upgrade.sh` would fail on `cp` if the source is missing and the check doesn't guard it -- let me verify.
+
+Looking at `upgrade.sh`:
+```bash
+HOOK_SOURCE="$FRAMEWORK_DIR/scripts/git-hooks/$HOOK"
+if [ -f "$HOOK_TARGET" ]; then
+    ...
+else
+    cp "$HOOK_SOURCE" "$HOOK_TARGET"
+```
+
+If `$HOOK_SOURCE` doesn't exist, `cp` will fail and `set -euo pipefail` will cause the script to exit. This is a bug if the framework is corrupted. However, the hooks are part of the framework and should always exist. If they're missing, exiting with an error is the correct behavior (not silent success).
+
+**Verdict:** ACCEPTABLE (fails loudly on corrupted framework)
+
+### Attack 5: `set -e` interaction with `|| true` -- CORRECT
+
+`set -e` causes the script to exit on any command failure. `cmd || true` prevents the exit because the overall command succeeds (the `|| true` branch). The `|| echo "WARNING: ..."` pattern also prevents exit because `echo` succeeds. This is the standard bash idiom for non-fatal commands.
+
+**Verdict:** CORRECT
+
+## Summary
+
+No exploitable vulnerabilities found. One ACCEPTABLE finding (upgrade.sh fails loudly on corrupted framework, which is correct behavior).
+
+**Verdict: CLEAN**
@@ -0,0 +1,30 @@
+# BUG_REPORT: fix-install-update-flow
+
+## Findings
+
+### Bug 1 (LOW): install.sh `set -e` with `|| true` on loop commands
+
+The `set -e` flag causes the script to exit on any command failure. The `|| true` on the self-improvement loop commands (lines 87-89) correctly prevents `set -e` from triggering. However, the `|| echo "WARNING: ..."` on the version check (line 99) also prevents `set -e` from triggering, which is the intended behavior.
+
+**Severity:** LOW (no bug -- verified correct)
+**Fix:** None needed.
+
+### Bug 2 (LOW): update.sh hook copy overwrites existing hooks
+
+In `update.sh`, the hook installation only runs `if [ -f "$HOOK_SRC" ] && [ ! -f "$HOOK_DST" ]`. This means existing hooks are NOT overwritten, which is correct -- the user may have custom hooks. But if the user previously had automaton hooks installed via symlink (from the old `ln -sf` code), those symlinks will persist. The user would need to manually delete them and re-run `install-hooks.sh` to get copies.
+
+**Severity:** LOW (migration concern for existing users)
+**Fix:** None needed for v1. The `install-hooks.sh` script always copies, so users can re-run it to switch from symlinks to copies.
+
+### Bug 3 (INFO): README still shows manual `git clone` before `install.sh`
+
+The README now shows `git clone <your-git-url> ~/.automaton` followed by `./install.sh <your-git-url>`. The user provides the URL twice: once for the manual clone and once for install.sh. This is slightly redundant but necessary because install.sh needs the URL for its own validation (and potentially for future self-update features). The manual clone is needed because install.sh itself is inside the cloned repo.
+
+**Severity:** INFO (by design)
+**Fix:** None needed.
+
+## Summary
+
+No correctness bugs found. Two LOW (one verified correct, one migration concern) and one INFO.
+
+**Verdict: CLEAN**
@@ -0,0 +1,56 @@
+# CODE_REVIEW: fix-install-update-flow
+
+## Reviewed Files
+
+1. `scripts/install.sh` -- complete restructure (git URL arg, venv fix, version check)
+2. `scripts/update.sh` -- hook copy fix
+3. `scripts/upgrade.sh` -- hook copy fix, symlink logic removed
+4. `tests/test_install_update_flow.py` -- 15 tests
+5. `README.md` -- updated install instructions
+6. `CHANGELOG.md` -- task 8 entry
+
+## Findings
+
+### 1. install.sh restructure
+
+The original `if [ -d "$FRAMEWORK_DIR" ]; then ... else ... fi` structure was restructured to early-exit (`exit 0`) for the already-installed case, then top-level code for the install case. This is cleaner and avoids the orphaned `fi` bug that was present in the original (the venv setup was outside the `if/else/fi`).
+
+The git URL is now `GIT_URL="${1:-}"` with a clear usage message and irreversibility warning. The hardcoded private IP URL is gone.
+
+**Verdict:** PASS
+
+### 2. Venv fix
+
+The venv is now created in `$FRAMEWORK_DIR/.venv` instead of CWD. The `requirements.txt` path is `$FRAMEWORK_DIR/requirements.txt`. Platform-aware Python detection handles both Unix (`.venv/bin/python3`) and Windows (`.venv/Scripts/python.exe`). Uses `"$VENV_PY" -m pip` for cross-platform pip.
+
+**Verdict:** PASS
+
+### 3. Hook consistency
+
+All three scripts (`install-hooks.sh`, `update.sh`, `upgrade.sh`) now use `cp` + `chmod +x` for hooks. No more `ln -sf`. The `upgrade.sh` symlink-checking logic (`readlink`, `-L`) is removed, simplifying the code.
+
+**Verdict:** PASS
+
+### 4. Version check
+
+`status.py --version` is called after all setup. The `|| echo "WARNING: ..."` ensures the script continues even if the version check fails.
+
+**Verdict:** PASS
+
+### 5. Test coverage
+
+15 tests cover all 5 requirements. Tests check script content (not execution) for the required patterns, which is appropriate for shell script testing in CI.
+
+**Verdict:** PASS
+
+### 6. Shell syntax
+
+`bash -n` passes for all three scripts.
+
+**Verdict:** PASS
+
+## Summary
+
+All 6 review areas pass. The implementation fixes all 5 issues cleanly. 15 new tests. Full suite: 424 passed.
+
+**Overall verdict: APPROVED**
@@ -0,0 +1,38 @@
+# DOC_REVIEW: fix-install-update-flow
+
+## Reviewed Documentation
+
+1. `README.md` -- updated install instructions
+2. `CHANGELOG.md` -- task 8 entry
+
+## Findings
+
+### 1. README.md
+
+Install instructions updated to show:
+- `git clone <your-git-url> ~/.automaton` (placeholder instead of hardcoded URL)
+- `./install.sh <your-git-url>` (URL as argument)
+- Note about self-improvement loop being created by default
+- Note about choosing URL carefully
+
+**Accuracy:** Matches the implementation. The URL is required as `$1`.
+
+**Verdict:** PASS
+
+### 2. CHANGELOG.md
+
+Entry accurately describes all 5 fixes: git URL, venv cwd, Windows venv path, hook copy, version check. Lists all 3 changed scripts and the 15 new tests.
+
+**Verdict:** PASS
+
+### 3. Cross-reference check
+
+- `design/loops/technical.md` section 9 references `install.sh` -- still accurate (the self-improvement loop bootstrap is still there, just the URL handling changed).
+- `AGENTS.md` references `install.sh` in the repo layout -- no changes needed.
+- `prompts/onboarding.md` references hook installation -- no changes needed (hooks are installed via `install-hooks.sh`, which is unchanged).
+
+## Summary
+
+All documentation is accurate and consistent with the implementation.
+
+**Verdict: APPROVED**
@@ -0,0 +1,52 @@
+# IMPLEMENTATION: fix-install-update-flow
+
+## Summary
+
+Fixed 5 issues in the install/update flow: hardcoded git URL, `.venv` cwd bug, Windows venv path, hook copy-vs-symlink inconsistency, and missing `--version` smoke test.
+
+## Changes
+
+### R1 -- User-supplied git URL (D11)
+
+`scripts/install.sh`: Replaced hardcoded `http://10.37.0.86:3003/hermes/automaton` with `GIT_URL="${1:-}"`. If empty, prints usage with irreversibility warning and exits 1. The `if [ -d "$FRAMEWORK_DIR" ]` check now `exit 0` instead of falling through to `else`.
+
+### R2 -- Fix `.venv` cwd bug
+
+`scripts/install.sh`: Moved venv setup to use `$FRAMEWORK_DIR/.venv` instead of relative `.venv`. Changed `requirements.txt` to `$FRAMEWORK_DIR/requirements.txt`.
+
+### R3 -- Windows venv path
+
+`scripts/install.sh`: Added platform-aware venv Python detection:
+- `$FRAMEWORK_DIR/.venv/bin/python3` (Unix)
+- `$FRAMEWORK_DIR/.venv/Scripts/python.exe` (Windows)
+- Fallback: `python3`
+
+Uses `"$VENV_PY" -m pip` instead of `.venv/bin/pip` for cross-platform compatibility.
+
+### R4 -- Hook copy-vs-symlink consistency
+
+- `scripts/update.sh`: Changed `ln -sf "$HOOK_SRC" "$HOOK_DST"` to `cp "$HOOK_SRC" "$HOOK_DST"` + `chmod +x "$HOOK_DST"`.
+- `scripts/upgrade.sh`: Replaced all `ln -sf` and symlink-checking logic (`readlink`, `-L`) with `cp` + `chmod +x`. Simplified the hook-exists warning to point to `install-hooks.sh`.
+
+### R5 -- `--version` smoke test
+
+`scripts/install.sh`: Added `python3 "$FRAMEWORK_DIR/scripts/status.py" --version || echo "WARNING: ..."` after self-improvement loop bootstrap.
+
+### R6 -- Tests
+
+`tests/test_install_update_flow.py`: 15 tests across 4 classes:
+- `TestInstallShGitUrl` (4 tests): git URL required, no hardcoded URL, usage message, irreversibility warning
+- `TestInstallShVenv` (4 tests): venv in framework dir, Windows path, `-m pip`, no relative venv
+- `TestInstallShVersionCheck` (1 test): version check present
+- `TestHookConsistency` (6 tests): update.sh uses cp, upgrade.sh uses cp, install-hooks.sh uses cp, chmod present, no symlink check
+
+### R7 -- Documentation
+
+- `CHANGELOG.md`: task 8 entry
+- `README.md`: updated install instructions
+
+## Verification
+
+- `bash -n scripts/install.sh scripts/update.sh scripts/upgrade.sh` -- OK
+- `python3 -m pytest tests/test_install_update_flow.py -v` -- 15 passed
+- `python3 -m pytest tests/ -q` -- 424 passed (409 + 15 new)
@@ -0,0 +1,117 @@
+# 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"
+```
@@ -0,0 +1,108 @@
+# SPEC: fix-install-update-flow
+
+## Context
+
+Five issues in the install/update flow need fixing: hardcoded git URL, `.venv` cwd bug, Windows venv path, hook copy-vs-symlink inconsistency, and missing `--version` smoke test.
+
+## Non-Goals (deferred)
+
+- Windows `schtasks` schedule installation testing -> v1.1 (needs Windows CI)
+- `register-guards.sh` changes -> not in scope (guards work correctly)
+- Automated update of copied hooks -> v1.1 (documented as "re-run install-hooks.sh")
+
+## Requirements
+
+### R1 -- User-supplied git URL (D11)
+
+`install.sh` must accept the git URL as `$1` and refuse if absent:
+
+```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. Choose your URL carefully"
+  echo "as it cannot be changed later without reinstalling."
+  exit 1
+fi
+git clone "$GIT_URL" "$FRAMEWORK_DIR"
+```
+
+Remove the hardcoded `http://10.37.0.86:3003/hermes/automaton` URL.
+
+### R2 -- Fix `.venv` cwd bug
+
+Move the venv setup inside the `else` block (after clone), using `$FRAMEWORK_DIR`:
+```bash
+# --- Python deps (idempotent, in framework dir) ---
+if [ ! -d "$FRAMEWORK_DIR/.venv" ]; then
+  python3 -m venv "$FRAMEWORK_DIR/.venv"
+fi
+```
+
+Use the venv's Python directly with `-m pip` (platform-aware path, see R3).
+
+### R3 -- Windows venv path
+
+Detect the venv Python path based on platform:
+```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
+"$VENV_PY" -m pip install --quiet --upgrade pip
+"$VENV_PY" -m pip install --quiet -r "$FRAMEWORK_DIR/requirements.txt"
+```
+
+### R4 -- Hook copy-vs-symlink consistency
+
+Change `update.sh` and `upgrade.sh` to use `cp` instead of `ln -sf`, matching `install-hooks.sh`:
+
+In `update.sh`, replace:
+```bash
+ln -sf "$HOOK_SRC" "$HOOK_DST"
+```
+with:
+```bash
+cp "$HOOK_SRC" "$HOOK_DST"
+chmod +x "$HOOK_DST"
+```
+
+In `upgrade.sh`, replace all `ln -sf` for hooks with `cp` + `chmod +x`.
+
+### R5 -- `--version` smoke test
+
+Add at the end of `install.sh` (inside the `else` block, after all setup):
+```bash
+# Verify framework is working
+python3 "$FRAMEWORK_DIR/scripts/status.py" --version || echo "WARNING: status.py --version failed"
+```
+
+### R6 -- Tests
+
+Write `tests/test_install_update_flow.py` with:
+
+1. `test_install_sh_requires_git_url` -- verify install.sh checks for `$1` and refuses if empty
+2. `test_install_sh_no_hardcoded_url` -- verify the hardcoded IP URL is gone
+3. `test_install_sh_venv_in_framework_dir` -- verify `.venv` setup uses `$FRAMEWORK_DIR`
+4. `test_install_sh_has_version_check` -- verify install.sh calls `status.py --version`
+5. `test_install_sh_windows_venv_path` -- verify install.sh handles `.venv/Scripts/python.exe`
+6. `test_update_sh_uses_cp_for_hooks` -- verify update.sh uses `cp` not `ln -sf`
+7. `test_upgrade_sh_uses_cp_for_hooks` -- verify upgrade.sh uses `cp` not `ln -sf`
+8. `test_install_hooks_sh_uses_cp` -- verify install-hooks.sh still uses `cp` (regression guard)
+
+### R7 -- Documentation
+
+- `CHANGELOG.md` under `[unreleased]`
+- `README.md` -- update install instructions to show `./install.sh <git-url>`
+
+## Verification
+
+- `bash -n scripts/install.sh scripts/update.sh scripts/upgrade.sh` -- syntax check
+- `python3 -m pytest tests/test_install_update_flow.py -v`
+- `python3 -m pytest tests/ -q` -- full suite must remain green
@@ -0,0 +1,31 @@
+# VERDICT: fix-install-update-flow
+
+## Task
+
+Fix 5 issues in the install/update flow: hardcoded git URL, `.venv` cwd bug, Windows venv path, hook copy-vs-symlink inconsistency, and missing `--version` smoke test.
+
+## Deliverables Review
+
+| Requirement | Status | Evidence |
+|---|---|---|
+| R1: User-supplied git URL (D11) | DONE | `install.sh` `GIT_URL="${1:-}"` with usage and irreversibility warning, 4 tests |
+| R2: Fix `.venv` cwd bug | DONE | Venv in `$FRAMEWORK_DIR/.venv`, `requirements.txt` from `$FRAMEWORK_DIR`, 4 tests |
+| R3: Windows venv path | DONE | Platform-aware `VENV_PY` detection, `-m pip`, 4 tests |
+| R4: Hook copy-vs-symlink | DONE | `update.sh` and `upgrade.sh` use `cp` + `chmod +x`, 6 tests |
+| R5: `--version` smoke test | DONE | `status.py --version` after install, 1 test |
+| R6: Tests | DONE | 15 tests in `tests/test_install_update_flow.py`, all passing |
+| R7: Documentation | DONE | CHANGELOG and README updated |
+
+## Quality Assessment
+
+- **Test coverage:** 15 new tests, all passing. Full suite 424 passed (was 409). No regressions.
+- **Shell syntax:** `bash -n` passes for all 3 scripts.
+- **Security:** No hardcoded URLs. No shell injection vectors. No path traversal.
+- **Backward compat:** Existing users with symlinked hooks can re-run `install-hooks.sh` to switch to copies.
+- **Documentation:** README and CHANGELOG accurate.
+
+## Verdict
+
+**APPROVED -- ready for complete.**
+
+All 7 requirements fully implemented, tested, and documented. The install/update flow is now portable, secure, and consistent.