hermes/automaton
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
715f6f9495ae84da58c6942240fc6257e43ce2e9
automaton/tasks/complete/state-file-enforcement/IMPLEMENTATION.md
T
Lap Tran 4a2301b077
CI / build (push) Has been cancelled
Details
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

2.6 KiB
Raw Blame History

Implementation: State File Enforcement

Changes Made

1. .state file format (implemented in scripts/status.py)

  • .state file contains a single phase name (e.g., research, research:awaiting_approval, implement)
  • Written atomically via .state.tmp → .state rename
  • .state.approvals append-only log records all approvals with timestamp and approver
  • .state.lock for multi-agent claiming (optional, only in multi-agent mode)
  • Non-artifact metadata files (.state, .state.approvals, .state.lock, .state.tmp, VRAM_CONFIG.md, PARENT_SPEC.md, REVIEW.md) are excluded from artifact checks

2. State transitions with approval sub-states

  • Approval-gated phases: research, decomposition, design, test_design now have :awaiting_approval → :approved sub-states
  • Non-approval phases: implement, bug_find, adversarial_bug_find, doc_review, referee have no sub-states
  • status.py --transition refuses transitions past :awaiting_approval without --approve
  • status.py --approve transitions :awaiting_approval → :approved and records approval in .state.approvals

3. Backward compatibility

  • If .state doesn't exist, status.py infers phase from artifacts and writes .state
  • upgrade.sh bootstraps .state for all existing tasks
  • Phase prompts work with or without .state (warns if missing)

4. Forbidden artifacts per phase (implemented in status.py --validate-folder)

  • Each phase has a defined set of artifacts that must NOT exist (artifacts from future phases)
  • --validate-folder checks and reports violations
  • --transition refuses to proceed if forbidden artifacts exist

5. Task creation gate (implemented in status.py --create-task)

  • --create-task creates task folder with .state = new and empty .state.approvals
  • Validates kebab-case task names
  • Refuses if task already exists
  • --audit Category 4 flags manually created task folders

6. Orchestrator and workflow updates

  • prompts/workflow.md rewritten: .state is canonical, approval sub-states documented, status.py commands referenced
  • prompts/orchestrate.md reduced from 493 to 143 lines, references workflow.md and subtask_management.md
  • All phase prompts include .state precondition check

Files Modified

  • scripts/status.py (new, 980 lines)
  • prompts/workflow.md (rewritten)
  • prompts/orchestrate.md (rewritten, 143 lines)
  • prompts/subtask_management.md (new, extracted from orchestrate.md)
  • tests/test_status.py (new, 25 tests)
  • scripts/upgrade.sh (new)

Test Results

  • 183 tests passing (including 25 new status.py tests)
  • Python compilation clean
  • Shell script syntax clean
Reference in New Issue View Git Blame Copy Permalink