hermes/automaton
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
05c76852a2152ded96cb28a392c8fc5e0908d1b3
automaton/tasks/project-scoping-enforcement/IMPLEMENTATION.md
T
gitea 05c76852a2
CI / build (push) Has been cancelled
Details
v2.0: state enforcement, project scoping, harness integration 
State Enforcement (v2.0):
- .state file as single source of truth for task phase
- Approval gates for research, decomposition, design, test_design
- status.py --transition refuses illegal phase transitions
- status.py --validate-folder detects out-of-order artifacts
- status.py --audit checks all tasks for violations
- status.py --create-task is the only valid way to create tasks
- Pre-v2.0 tasks without .state are UNTRACKED -- all commands refuse them
- New --upgrade command bootstraps .state files for existing tasks

Project Scoping:
- --project flag added to all status.py commands across 16+ files
- _find_project_dir errors instead of silently falling back to ~/.automaton/
- --scope-check marks framework files OUT_OF_SCOPE when working on a project
- Dashboard handlers use stored project_root instead of re-detecting from CWD
- Prompts reference ~/.automaton/scripts/vram_detect.py (not {project}/.automaton/)

Harness Integration:
- status.py --can-edit now supports project-level checks (no --task required)
- --can-edit --file checks file scope without --task
- --json output for machine-readable harness integration
- opencode plugin (plugins/automaton-guard/plugin.ts) intercepts edit/write
- Git pre-commit hook (scripts/git-hooks/pre-commit) blocks commits without task
- Formal integration contract (contracts/harness-integration.md)

Other:
- upgrade.sh delegates to status.py --upgrade instead of manual heuristics
- Phase prompts reference --project {project} for multi-project scoping
- 200 tests passing (14 new)
2026-06-15 14:16:46 -04:00

4.6 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink