# Implementation: Project Scoping Enforcement

## Changes Made

### 1. `scripts/status.py` — `_find_project_dir()` fix (critical)
- Removed `cwd.name == ".automaton"` false positive that misidentified project dirs as framework
- Removed silent fallback to `AUTOMATON_DIR` — now errors with guidance to use `--project`
- Added `cwd.parent == AUTOMATON_DIR` check so running from inside `~/.automaton/` still works
- Added warning when `--project` points to a directory without `.automaton/`

### 2. `scripts/status.py` — `cmd_scope_check()` fix (critical)
- Framework directory (`~/.automaton/`) is now OUT_OF_SCOPE when `project_dir != AUTOMATON_DIR`
- Previously, ANY file under `~/.automaton/` was considered IN_SCOPE regardless of which project you were working on

### 3. `scripts/status.py` — `_require_state()` helper and untracked task enforcement
- New `_require_state()` function that reads `.state` and refuses operations on tasks without it
- `cmd_show_task`, `cmd_transition`, `cmd_can_edit`, `cmd_claim` all use `_require_state()` — they refuse untracked tasks and direct users to run `--upgrade`
- `cmd_list` shows `UNTRACKED (no .state)` for tasks without `.state` files, with a note to run `--upgrade`

### 4. `scripts/status.py` — New `--upgrade` command
- `--upgrade --task {name}` bootstraps `.state` for a single task
- `--upgrade` (no --task) bootstraps all tasks missing `.state`, including sub-tasks
- Uses `_infer_state_from_artifacts` heuristic (same as before, but now only accessible via `--upgrade`)

### 5. `automaton/dashboard/ui/app.py` — Dashboard scope fix
- Added `project_root` and `scope` as class attributes on `DashboardHandler`
- All 7 handler methods (`_serve_tasks`, `_handle_config_update`, `_serve_scope`, `_serve_project_name`, `_serve_task`, `_get_review_path`, `_serve_review_summary`) now use `self.project_root`/`self.scope` instead of calling `find_automaton_root()`/`detect_scope()` per-request
- `DashboardApp.run()` sets these class attributes from the stored values
- Removed unused `find_automaton_root` import

### 6. `scripts/upgrade.sh` — Delegates to `status.py --upgrade`
- Replaced 80+ lines of manual shell heuristic bootstrapping with `python3 "$STATUS_SCRIPT" --upgrade --project "$PROJECT_DIR"`
- Updated final instructions to include `--project` flag

### 7. Added `--project {project}` to all status.py commands in:
- `.agent.md`
- `.rules.md`
- `system-prompt.md`
- `.onboarding.md`
- `prompts/onboarding.md`
- `prompts/orchestrate.md`
- `prompts/research.md`
- `prompts/design.md`
- `prompts/implement.md`
- `prompts/decompose.md`
- `prompts/test_design.md`
- `prompts/bug_finder.md`
- `prompts/adversarial_bug_find.md`
- `prompts/doc_review.md`
- `prompts/referee.md`
- `prompts/subtask_management.md`
- `prompts/workflow.md`

### 8. Fixed `{project}/.automaton/scripts/vram_detect.py` references
- `prompts/orchestrate.md` and `prompts/decompose.md` referenced `{project}/.automaton/scripts/vram_detect.py` which doesn't exist in projects (only in `~/.automaton/scripts/`). Changed to `~/.automaton/scripts/vram_detect.py`.

### 9. Updated documentation for untracked tasks and `--upgrade`
- `AGENTS.md` — Added `--upgrade` command, untracked task behavior
- `.rules.md` — Added Project Scoping section, untracked task rule
- `system-prompt.md` — Added Project Scoping section, untracked task rule
- `.agent.md` — Added `--upgrade` command
- `.onboarding.md` — Added `--upgrade` command
- `prompts/workflow.md` — Added untracked task behavior
- `prompts/onboarding.md` — Changed upgrade step to use `status.py --upgrade`
- `CHANGELOG.md` — Added all changes under `[unreleased]`

### 10. New tests (9)
- `test_scope_check_framework_out_of_scope_for_project` — framework files are OUT_OF_SCOPE for projects
- `test_no_project_errors_without_flag` — `--list` errors from non-project directory
- `test_project_flag_targets_correct_tasks` — `--project` correctly scopes tasks
- `test_transition_refuses_untracked_task` — `--transition` refuses tasks without `.state`
- `test_can_edit_refuses_untracked_task` — `--can-edit` refuses tasks without `.state`
- `test_show_task_refuses_untracked_task` — `--task` refuses tasks without `.state`
- `test_list_shows_untracked_task` — `--list` shows UNTRACKED for tasks without `.state`
- `test_upgrade_bootstraps_state_file` — `--upgrade --task` bootstraps `.state` for single task
- `test_upgrade_all_tasks` — `--upgrade` bootstraps `.state` for all tasks missing it

### 11. Updated `tests/test_app.py`
- Removed `find_automaton_root` monkeypatching — handlers now use `self.project_root` class attribute
- `test_handle_config_update` sets `handler.project_root = tmp_path`

Total: 192 tests passing.