# Watch + Helm Reorg — Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Split `supervisor/` + `chronicle/` into `watch/` (UI) and `helm/` (backend). No shims — fix all imports directly.

**Architecture:** Two top-level projects with clean frontend/backend separation. `watch/` is everything you look at. `helm/` is the engine that sees everything and can act. `supervisor/` and `chronicle/` are deleted entirely.

**Tech Stack:** Python, FastAPI, Gradio, git mv, sed for bulk import rewrites

---

## File Move Map

### helm/ (backend)

| From | To |
|------|----|
| `supervisor/watch/api.py` | `helm/api.py` |
| `supervisor/watch/db.py` | `helm/db.py` |
| `supervisor/watch/state_poller.py` | `helm/state_poller.py` |
| `supervisor/watch/iterm2d_health.py` | `helm/iterm2d_health.py` |
| `supervisor/watch/idle_recap.py` | `helm/recap.py` |
| `supervisor/core/session.py` | `helm/respond/session.py` |
| `supervisor/core/policy.py` | `helm/respond/policy.py` |
| `supervisor/core/decision.py` | `helm/respond/decision.py` |
| `supervisor/core/__init__.py` | `helm/respond/__init__.py` |
| `supervisor/sidekick/hooks/handler.py` | `helm/hooks/handler.py` |
| `supervisor/sidekick/hooks/constants.py` | `helm/hooks/constants.py` |
| `supervisor/sidekick/hooks/__init__.py` | `helm/hooks/__init__.py` |
| `supervisor/sidekick/inbox.py` | `helm/inbox.py` |
| `supervisor/autonomous/` | `helm/autodo/` (entire dir) |
| `supervisor/cli.py` | `helm/cli.py` |
| `supervisor/loop.py` | `helm/loop.py` |
| `supervisor/periodic.py` | `helm/periodic.py` |
| `supervisor/sessions.py` | `helm/sessions.py` |
| `supervisor/logging.py` | `helm/logging.py` |
| `supervisor/user_queue.py` | `helm/user_queue.py` |
| `supervisor/policies/` | `helm/policies/` |
| `supervisor/tests/` | `helm/tests/` |
| `chronicle/analyze_sessions.py` | `helm/analyze.py` |
| `chronicle/stats.py` | `helm/stats.py` |
| `chronicle/content_filter.py` | `helm/content_filter.py` |
| `chronicle/native_reader.py` | `helm/native_reader.py` |

Note: `idle_recap.py` → `helm/recap.py` (not watch/) because it calls LLMs and is triggered by hooks. It's backend work that produces cached HTML.

### watch/ (UI)

| From | To |
|------|----|
| `supervisor/watch/app.py` | `watch/app.py` |
| `supervisor/watch/grid_view.py` | `watch/grid.py` |
| `supervisor/watch/overview.py` | `watch/overview.py` |
| `supervisor/watch/autodo_view.py` | `watch/autodo_view.py` |
| `supervisor/watch/UI_CRITIQUE.md` | `watch/UI_CRITIQUE.md` |
| `chronicle/ui.py` | `watch/chronicle.py` |
| `chronicle/ui_daily.py` | `watch/chronicle_daily.py` |
| `chronicle/ui_gantt.py` | `watch/chronicle_gantt.py` |
| `chronicle/ui_live.py` | `watch/chronicle_live.py` |
| `chronicle/ui_projects.py` | `watch/chronicle_projects.py` |
| `chronicle/ui_timeline.py` | `watch/chronicle_timeline.py` |
| `chronicle/ui_data.py` | `watch/chronicle_data.py` |
| `chronicle/topic_graph.py` | `watch/topic_graph.py` |
| `chronicle/static/` | `watch/static/` |

## Import Rewrite Map

| Old import | New import |
|------------|-----------|
| `from supervisor.watch import db` | `from helm import db` |
| `from supervisor.watch.db import *` | `from helm.db import *` |
| `from supervisor.watch.api import *` | `from helm.api import *` |
| `from supervisor.watch.overview import *` | `from watch.overview import *` |
| `from supervisor.watch.grid_view import *` | `from watch.grid import *` |
| `from supervisor.watch.idle_recap import *` | `from helm.recap import *` |
| `from supervisor.watch.iterm2d_health import *` | `from helm.iterm2d_health import *` |
| `from supervisor.watch.state_poller import *` | `from helm.state_poller import *` |
| `from supervisor.watch.autodo_view import *` | `from watch.autodo_view import *` |
| `from supervisor.core.session import *` | `from helm.respond.session import *` |
| `from supervisor.core.policy import *` | `from helm.respond.policy import *` |
| `from supervisor.core.decision import *` | `from helm.respond.decision import *` |
| `from supervisor.autonomous.* import *` | `from helm.autodo.* import *` |
| `from supervisor.sidekick.hooks.handler import *` | `from helm.hooks.handler import *` |
| `from supervisor.sidekick.hooks.constants import *` | `from helm.hooks.constants import *` |
| `from supervisor.sidekick.inbox import *` | `from helm.inbox import *` |
| `from chronicle.ui import *` | `from watch.chronicle import *` |
| `from chronicle.ui_data import *` | `from watch.chronicle_data import *` |
| `from chronicle.ui_daily import *` | `from watch.chronicle_daily import *` |
| `from chronicle.ui_gantt import *` | `from watch.chronicle_gantt import *` |
| `from chronicle.ui_live import *` | `from watch.chronicle_live import *` |
| `from chronicle.ui_projects import *` | `from watch.chronicle_projects import *` |
| `from chronicle.ui_timeline import *` | `from watch.chronicle_timeline import *` |
| `from chronicle.native_reader import *` | `from helm.native_reader import *` |
| `from chronicle.analyze_sessions import *` | `from helm.analyze import *` |
| `from chronicle.stats import *` | `from helm.stats import *` |
| `from chronicle.content_filter import *` | `from helm.content_filter import *` |
| `from chronicle.topic_graph import *` | `from watch.topic_graph import *` |
| `import supervisor.watch` | `import helm` |
| `import chronicle` | varies |

## External consumers needing import updates

| File | Old import | New import |
|------|-----------|-----------|
| `lib/billing/monitor.py:123` | `from supervisor.watch.db import add_notification` | `from helm.db import add_notification` |
| `learning/gyms/badge/gym.py:26` | `from supervisor.watch.api import TREE_SYSTEM_PROMPT` | `from helm.api import TREE_SYSTEM_PROMPT` |
| `learning/gyms/badge/gym.py:27` | `from supervisor.sidekick.hooks.handler import _is_low_info_prompt` | `from helm.hooks.handler import _is_low_info_prompt` |
| `ops/sessions.py:1041` | `from supervisor.watch import db` | `from helm import db` |
| `ops/sessions.py:545` | `from supervisor.core.session import get_session_info` | `from helm.respond.session import get_session_info` |
| `doctor/app.py:32` | `from chronicle.ui import build_chronicle_tab` | `from watch.chronicle import build_chronicle_tab` |

---

## Task 1: Create directories and move files with git mv

**Step 1:** Create directory structure
```bash
mkdir -p helm/respond helm/hooks helm/autodo helm/tests helm/policies
```

**Step 2:** git mv all helm/ files (backend)
```bash
# From supervisor/watch/ (backend pieces)
git mv supervisor/watch/api.py helm/api.py
git mv supervisor/watch/db.py helm/db.py
git mv supervisor/watch/state_poller.py helm/state_poller.py
git mv supervisor/watch/iterm2d_health.py helm/iterm2d_health.py
git mv supervisor/watch/idle_recap.py helm/recap.py

# From supervisor/core/ → helm/respond/
git mv supervisor/core/session.py helm/respond/session.py
git mv supervisor/core/policy.py helm/respond/policy.py
git mv supervisor/core/decision.py helm/respond/decision.py
git mv supervisor/core/__init__.py helm/respond/__init__.py

# From supervisor/sidekick/ → helm/hooks/ + helm/
git mv supervisor/sidekick/hooks/handler.py helm/hooks/handler.py
git mv supervisor/sidekick/hooks/constants.py helm/hooks/constants.py
git mv supervisor/sidekick/hooks/__init__.py helm/hooks/__init__.py
git mv supervisor/sidekick/inbox.py helm/inbox.py

# From supervisor/autonomous/ → helm/autodo/
git mv supervisor/autonomous/* helm/autodo/

# From supervisor/ root
git mv supervisor/cli.py helm/cli.py
git mv supervisor/loop.py helm/loop.py
git mv supervisor/periodic.py helm/periodic.py
git mv supervisor/sessions.py helm/sessions.py
git mv supervisor/logging.py helm/logging.py
git mv supervisor/user_queue.py helm/user_queue.py

# Policies and tests
git mv supervisor/policies/* helm/policies/ 2>/dev/null || true
git mv supervisor/tests/* helm/tests/ 2>/dev/null || true

# From chronicle/ (backend pieces)
git mv chronicle/analyze_sessions.py helm/analyze.py
git mv chronicle/stats.py helm/stats.py
git mv chronicle/content_filter.py helm/content_filter.py
git mv chronicle/native_reader.py helm/native_reader.py
```

**Step 3:** git mv all watch/ files (UI)

Note: `watch/` already exists with a README.md — move files into it.
```bash
# From supervisor/watch/ (UI pieces)
git mv supervisor/watch/app.py watch/app.py
git mv supervisor/watch/grid_view.py watch/grid.py
git mv supervisor/watch/overview.py watch/overview.py
git mv supervisor/watch/autodo_view.py watch/autodo_view.py
git mv supervisor/watch/UI_CRITIQUE.md watch/UI_CRITIQUE.md

# From chronicle/ (UI pieces)
git mv chronicle/ui.py watch/chronicle.py
git mv chronicle/ui_daily.py watch/chronicle_daily.py
git mv chronicle/ui_gantt.py watch/chronicle_gantt.py
git mv chronicle/ui_live.py watch/chronicle_live.py
git mv chronicle/ui_projects.py watch/chronicle_projects.py
git mv chronicle/ui_timeline.py watch/chronicle_timeline.py
git mv chronicle/ui_data.py watch/chronicle_data.py
git mv chronicle/topic_graph.py watch/topic_graph.py
git mv chronicle/static watch/static
```

**Step 4:** Create `__init__.py` files
```bash
echo '# Helm — session engine' > helm/__init__.py
echo '# Watch — session dashboard' > watch/__init__.py
```

**Step 5:** Commit
```bash
git add -A
git commit -m "refactor: move files for watch/helm reorg (imports not yet updated)"
```

---

## Task 2: Update imports in helm/ files

Update all `from supervisor.*` and `from chronicle.*` imports inside `helm/` to use new paths.

**Files to update (helm/ internal):**
- `helm/api.py` — fix sys.path depth, update `from supervisor.watch` → `from helm`, `from supervisor.sidekick` → `from helm.hooks`
- `helm/state_poller.py` — `from supervisor.core.session` → `from helm.respond.session`, `from supervisor.watch` → `from helm`
- `helm/recap.py` — `from supervisor.watch.api` → `from helm.api`
- `helm/cli.py` — all `from supervisor.*` → `from helm.*`
- `helm/loop.py` — all `from supervisor.*` → `from helm.*`
- `helm/periodic.py` — `from supervisor.watch.db` → `from helm.db`
- `helm/hooks/handler.py` — `from supervisor.watch` → `from helm`
- `helm/autodo/notify.py` — `from supervisor.watch.db` → `from helm.db`
- `helm/autodo/cli.py` — `from supervisor.autonomous.*` → `from helm.autodo.*`
- `helm/autodo/engine.py` — internal autonomous imports
- All other `helm/autodo/*.py` — update internal refs
- `helm/tests/*.py` — update all test imports

Also fix `sys.path.insert` depth in files that compute rivus root from `__file__`.

**Commit:** `refactor: update imports in helm/`

---

## Task 3: Update imports in watch/ files

**Files to update (watch/ internal):**
- `watch/app.py` — `from supervisor.watch` → `from watch` or `from helm`, `from supervisor.autonomous` → `from helm.autodo`
- `watch/grid.py` — `from supervisor.watch.overview` → `from watch.overview`
- `watch/overview.py` — `from supervisor.watch` → `from helm` (db, iterm2d_health)
- `watch/chronicle.py` — all `from chronicle.*` → `from watch.*` or `from helm.*`
- `watch/chronicle_daily.py` — `from chronicle.ui_data` → `from watch.chronicle_data`
- `watch/chronicle_gantt.py` — same pattern
- `watch/chronicle_live.py` — same + `from chronicle.native_reader` → `from helm.native_reader`
- `watch/chronicle_projects.py` — same
- `watch/chronicle_timeline.py` — same
- `watch/chronicle_data.py` — internal chronicle imports
- `watch/topic_graph.py` — any chronicle imports

Also fix `sys.path.insert` depth in files that compute rivus root.

**Commit:** `refactor: update imports in watch/`

---

## Task 4: Update external consumers

**Files:**
- `lib/billing/monitor.py` — `from supervisor.watch.db` → `from helm.db`
- `learning/gyms/badge/gym.py` — `from supervisor.watch.api` → `from helm.api`, `from supervisor.sidekick` → `from helm.hooks`
- `ops/sessions.py` — `from supervisor.watch` → `from helm`, `from supervisor.core.session` → `from helm.respond.session`
- `doctor/app.py` — `from chronicle.ui` → `from watch.chronicle`

**Commit:** `refactor: update external consumer imports for helm/watch`

---

## Task 5: Update infra configs

### Caddy (`infra/Caddyfile`)
- Remove `chronicle.localhost` block (merged into hub)
- Rename `watch.api.localhost` → add `helm.api.localhost` alias (keep both as aliases)
- Update comments (start commands)
- Add `helm.api.localhost` reverse proxy to 8130

### Launchd (`~/Library/LaunchAgents/local.rivus.helm-server.plist`)
- Change `supervisor.watch.api` → `helm.api`

### Invoke tasks
- `supervisor/tasks.py` → `helm/tasks.py` — update all paths
- `tasks.py` root — update chronicle namespace, supervisor/watch references
- Update the dynamic sub-project mapping: `"watch": ("supervisor", ...)` → point to watch/
- Add `helm` namespace (`inv helm.server`)

### Port mapping
- Keep ports unchanged: hub UI = 7800, helm API = 8130
- Drop chronicle port 7880 (merged into hub)

**Commit:** `refactor: update infra for helm/watch (Caddy, launchd, invoke)`

---

## Task 6: Update docs and skills

### CLAUDE.md files
- `CLAUDE.md` root — update directory table, CLI tools, structure references
- `supervisor/CLAUDE.md` → `helm/CLAUDE.md` — rewrite for helm identity
- `chronicle/CLAUDE.md` → delete (absorbed into watch/ and helm/)
- Create `watch/CLAUDE.md` with the UI project description

### Skills (~/.myconf/claude_global/skills/)
- `/jump` skill — update `watch.api.localhost` → `helm.api.localhost`
- `/autonomous` skill — update `supervisor.autonomous` → `helm.autodo`
- `/hist` skill — update watch API references
- Any other skills referencing supervisor/watch/chronicle paths

### README files
- `watch/README.md` — rewrite with real content
- `helm/README.md` — create with project description
- Update `supervisor/README.md` → delete or redirect

**Commit:** `docs: update CLAUDE.md, skills, READMEs for helm/watch reorg`

---

## Task 7: Clean up and verify

### Delete old directories
```bash
git rm -r supervisor/ chronicle/
```

### Verify
```bash
# Check no dangling imports
grep -r "from supervisor\." --include="*.py" . | grep -v __pycache__ | grep -v .git
grep -r "from chronicle\." --include="*.py" . | grep -v __pycache__ | grep -v .git
grep -r "import supervisor" --include="*.py" . | grep -v __pycache__ | grep -v .git
grep -r "import chronicle" --include="*.py" . | grep -v __pycache__ | grep -v .git

# Check Python can import the new modules
python -c "from helm import db; print('helm.db OK')"
python -c "from helm.api import app; print('helm.api OK')"
python -c "from watch.overview import fetch_overview; print('watch.overview OK')"
python -c "from helm.respond.session import WaitState; print('helm.respond.session OK')"

# Run existing tests
python -m pytest helm/tests/ -v --tb=short 2>&1 | head -50
```

### Final commit
```bash
git add -A
git commit -m "refactor: complete watch/helm reorg — delete supervisor/ and chronicle/"
git push
```