automaton/tasks/status-script/SPEC.md

SPEC: Status Script

Goal

Create a status.py script that any agent can call to determine the current phase, allowed actions, and forbidden actions for a task — reducing agent decision-making to a single bash command.

Background

Currently, agents must read .agent.md, .rules.md, workflow.md, check artifact existence, and derive their allowed actions from 493 lines of orchestrator prompt. This complexity causes agents to skip phases. A single command that returns the current state and boundaries eliminates ambiguity and reduces the cognitive load on the agent.

Requirements

1. Command interface

python ~/.automaton/scripts/status.py --task {task-name} [--project {project-path}]

2. Output format

The script outputs structured plain text (not JSON — agents parse plain text more reliably):

Task: add-user-auth
Phase: research (from .state)
State file: ~/.automaton/tasks/add-user-auth/.state
Allowed actions:
  - Read project files
  - Ask clarifying questions  
  - Write SPEC.md
Forbidden actions:
  - Edit code
  - Create IMPLEMENTATION.md
  - Create DESIGN.md
  - Skip to implementation
Next artifact needed: SPEC.md
Next phase: design or implement
Command to proceed: "orchestrate" or "design {task-name}"

3. State determination logic

The script must determine state using this priority:

1. Read .state file — if it exists, it is authoritative
2. Fall back to artifact heuristic — if .state doesn't exist, determine state from artifact files (current logic from workflow.md) and write .state with the inferred phase
3. Report "unknown" — if neither .state nor enough artifacts exist to determine state

4. Atomic .state writes

When the script writes .state (during fallback or transition), it must:

• Write to .state.tmp first
• Rename .state.tmp to .state (atomic on most filesystems)
• Not corrupt an existing .state if the write fails

5. Transition command

python ~/.automaton/scripts/status.py --task {task-name} --transition {phase}

This transitions the task to a new phase:

• Validates the transition is legal according to the state machine
• Writes .state with the new phase name
• Validates the required artifact for the current phase exists before transitioning
• Refuses illegal transitions (e.g., from research directly to bug_find)
• Refuses transitions past :awaiting_approval sub-states (approval must be granted first)

Legal transitions:

• new → research
• research → research:awaiting_approval (when SPEC.md draft is produced)
• research:awaiting_approval → research:approved (ONLY via --approve, not --transition)
• research:approved → decomposition | design | implement
• decomposition → decomposition:awaiting_approval (when DECOMPOSITION.md draft is produced)
• decomposition:awaiting_approval → decomposition:approved (ONLY via --approve)
• decomposition:approved → (sub-task research, parent awaits)
• design → design:awaiting_approval (when DESIGN.md draft is produced)
• design:awaiting_approval → design:approved (ONLY via --approve)
• design:approved → test_design | implement
• test_design → test_design:awaiting_approval (when TEST_PLAN.md draft is produced)
• test_design:awaiting_approval → test_design:approved (ONLY via --approve)
• test_design:approved → implement
• implement → bug_find
• bug_find → adversarial_bug_find
• adversarial_bug_find → doc_review
• doc_review → referee
• referee → complete | human_intervention

Approval gate enforcement: --transition MUST REFUSE to transition from :awaiting_approval to any phase other than :approved. This ensures sign-off cannot be bypassed.

5a. Approve command

python ~/.automaton/scripts/status.py --task {task-name} --approve

Approves the current phase artifact, transitioning from :awaiting_approval to :approved.

• This is the ONLY way to move past an approval gate
• Must be called explicitly — the agent cannot self-approve
• Writes .state with the :approved sub-state atomically
• Records approval in .state.approvals log (see section 5b)

If the current phase does not have an :awaiting_approval sub-state:

• For phases with approval (research, decomposition, design, test_design): if not in :awaiting_approval, refuse with: "ERROR: Current phase is '{phase}' (not awaiting approval). Current sub-state must be '{phase}:awaiting_approval' before approval can be granted."
• For phases without approval (implement, bug_find, etc.): "This phase does not require approval."

5b. Approval log

Each task has an .state.approvals file that records all approvals:

Location: tasks/{task-name}/.state.approvals Format (one line per approval):

research:approved|2026-06-14T14:30:00Z|user
design:approved|2026-06-14T15:00:00Z|user

Each line contains: {phase}:approved|{ISO-8601-timestamp}|{approver}

• {approver} is "user" for manual approval or the agent-id for multi-agent approval
• This file is append-only — approvals are never deleted
• It is metadata, not an artifact, and is excluded from --validate-folder checks

5c. Create-task command

python ~/.automaton/scripts/status.py --create-task {task-name} [--project {project-path}]

This is the ONLY valid way to create a task folder. It:

1. Validates that the task name is kebab-case (lowercase, hyphens, no spaces)
2. Validates that the task doesn't already exist
3. Creates the task folder at {project}/.automaton/tasks/{task-name}/
4. Writes .state with content new\n (not research — the task starts as new and transitions to research via --transition research)
5. Creates .state.approvals as an empty file
6. Outputs: "Created task '{task-name}' in state 'new'. Use --transition research to begin."

This replaces manual mkdir task creation.

--validate-folder and --audit checks: A task folder without .state was created manually and is flagged as a violation:

Task: fix-broken-thing
Phase: unknown (no .state file found)
Folder validation: FAIL — task was created manually (no .state file). Use 'python ~/.automaton/scripts/status.py --create-task' to create tasks properly.

6. Validation on transition

When transitioning, the script must verify:

• The required artifact for the CURRENT phase exists and is non-empty
  • research → SPEC.md must exist and be non-empty
  • decomposition → DECOMPOSITION.md must exist and be non-empty
  • design → DESIGN.md must exist and be non-empty
  • test_design → TEST_PLAN.md must exist and be non-empty
  • implement → IMPLEMENTATION.md must exist and be non-empty
  • bug_find → BUG_REPORT.md must exist and be non-empty
  • adversarial_bug_find → ADVERSARIAL_BUG_REPORT.md must exist and be non-empty
  • doc_review → DOC_REVIEW.md must exist and be non-empty
  • referee → VERDICT.md must exist and be non-empty
• If validation fails, output an error and refuse the transition

7. List command

python ~/.automaton/scripts/status.py --list [--project {project-path}]

Lists all tasks in the project with their current phase:

Task                     Phase               Next Step
add-user-auth            research             design or implement
fix-login-bug            implement            bug_find
add-payment-api          complete             —

8. Project path resolution

• --project defaults to current working directory
• Task folders are looked up in {project}/.automaton/tasks/
• If running from ~/.automaton/, use ~/.automaton/tasks/
• Sub-tasks are listed under their parent task with indentation

9. Sub-task support

python ~/.automaton/scripts/status.py --task parent-task/subtask-a --project {project-path}

For sub-tasks:

• Look up the task at {project}/.automaton/tasks/{parent-task}/subtasks/{subtask}/
• Read .state from the sub-task folder
• Report parent context in output

10. Validate-folder command

python ~/.automaton/scripts/status.py --validate-folder --task {task-name} [--project {project-path}]

Checks that the task folder does not contain artifacts from phases that haven't been reached yet. This detects phase-skipping violations — if an agent jumps ahead and creates IMPLEMENTATION.md during research, --validate-folder catches it.

Phase-to-forbidden-artifacts mapping (artifacts from future phases):

Phase	Forbidden artifacts (must NOT exist)
new	SPEC.md, DESIGN.md, DECOMPOSITION.md, TEST_PLAN.md, IMPLEMENTATION.md, BUG_REPORT.md, ADVERSARIAL_BUG_REPORT.md, DOC_REVIEW.md, VERDICT.md
research	DESIGN.md, DECOMPOSITION.md, TEST_PLAN.md, IMPLEMENTATION.md, BUG_REPORT.md, ADVERSARIAL_BUG_REPORT.md, DOC_REVIEW.md, VERDICT.md
decomposition	DESIGN.md, TEST_PLAN.md, IMPLEMENTATION.md, BUG_REPORT.md, ADVERSARIAL_BUG_REPORT.md, DOC_REVIEW.md, VERDICT.md
design	DECOMPOSITION.md, TEST_PLAN.md, IMPLEMENTATION.md, BUG_REPORT.md, ADVERSARIAL_BUG_REPORT.md, DOC_REVIEW.md, VERDICT.md
test_design	DECOMPOSITION.md, IMPLEMENTATION.md, BUG_REPORT.md, ADVERSARIAL_BUG_REPORT.md, DOC_REVIEW.md, VERDICT.md
implement	BUG_REPORT.md, ADVERSARIAL_BUG_REPORT.md, DOC_REVIEW.md, VERDICT.md
bug_find	ADVERSARIAL_BUG_REPORT.md, DOC_REVIEW.md, VERDICT.md
adversarial_bug_find	DOC_REVIEW.md, VERDICT.md
doc_review	VERDICT.md
referee	(none — all artifacts allowed)
complete	(none — all artifacts allowed)
human_intervention	(none — all artifacts allowed)

Note: Non-artifact files (.state, VRAM_CONFIG.md, PARENT_SPEC.md, REVIEW.md) are never flagged as forbidden — they are metadata, not phase deliverables.

Output on success:

Task: add-user-auth
Phase: research (from .state)
Folder validation: PASS — no out-of-order artifacts found

Output on violation:

Task: add-user-auth
Phase: research (from .state)
Folder validation: FAIL — found out-of-order artifacts:
  - IMPLEMENTATION.md (belongs to implement phase, not yet reached)
  - BUG_REPORT.md (belongs to bug_find phase, not yet reached)
These artifacts indicate phase-skipping. The task is in research phase but has artifacts from future phases.
Remove the out-of-order artifacts or revert to the correct phase.

11. Audit command

python ~/.automaton/scripts/status.py --audit [--project {project-path}]

Runs a comprehensive audit across ALL tasks in the project. This is a deeper check than --validate-folder — it checks for three categories of violations:

Category 1: Out-of-order artifacts (same as --validate-folder, applied to all tasks)

• Checks each task folder for artifacts from future phases
• Reports each violation with the task name, current phase, and offending artifacts

Category 2: State-artifact inconsistency

• Checks that .state matches the artifacts actually present
• If .state says "implement" but only SPEC.md exists (no IMPLEMENTATION.md), the state may be wrong
• If .state says "research" but IMPLEMENTATION.md exists, the state was likely not updated after a skip
• Reports each inconsistency with a suggested correction

Category 3: Unauthorized modifications (requires git)

• If the project is a git repo, checks whether source code files were modified during a non-implement phase
• Compares file modification timestamps (from git log) against .state transition times (from .state file mtime)
• If code was edited when .state says "research" or "design", flags it as a violation
• If no git repo is found, skip this check and note it in the output

Output format:

Audit Report for /path/to/project

=== Category 1: Out-of-order Artifacts ===
[PASS] add-user-auth: no violations
[FAIL] fix-login-bug (phase: research): found IMPLEMENTATION.md (implement phase artifact)
[PASS] add-payment-api: no violations

=== Category 2: State-Artifact Inconsistency ===
[PASS] add-user-auth: .state ("research") matches artifacts (SPEC.md exists)
[WARN] fix-login-bug: .state says "research" but IMPLEMENTATION.md exists — suggested correction: implement
[PASS] add-payment-api: .state ("complete") matches all artifacts

=== Category 3: Unauthorized Modifications ===
Skipped: not a git repository
— OR —
[PASS] add-user-auth: no code modifications outside implement phase
[FAIL] fix-login-bug: src/auth.py was modified during research phase (state: research, file mtime: 2026-06-14)

=== Summary ===
3 tasks audited
2 violations found
  - fix-login-bug: out-of-order artifact (IMPLEMENTATION.md)
  - fix-login-bug: state-artifact mismatch (.state says research, IMPLEMENTATION.md exists)
  - fix-login-bug: unauthorized modification (src/auth.py during research phase)

Exit codes:

• 0: No violations found
• 1: Violations found (useful for CI integration)
• 2: Error (task not found, corrupted .state, etc.)

12. Error handling

• Task not found: output "ERROR: Task '{task-name}' not found in {project}/.automaton/tasks/"
• .state file corrupted (contains unknown phase): output "ERROR: Unknown phase '{phase}' in .state file"
• Illegal transition: output "ERROR: Cannot transition from '{current}' to '{target}'. Legal transitions from '{current}' are: {list}"
• Missing artifact on transition: output "ERROR: Cannot transition from '{current}' to '{target}'. Required artifact '{artifact}' is missing or empty in task folder."
• Out-of-order artifact on transition: output "ERROR: Cannot transition from '{current}' to '{target}'. Found forbidden artifact '{artifact}' in task folder. This indicates phase-skipping. Remove the artifact or revert to the correct phase."

13. Transition validation with folder check

When --transition is called, it must ALSO run the --validate-folder check before allowing the transition:

• If the task folder contains forbidden artifacts for the current phase, the transition is REFUSED
• This prevents transitioning past a phase-skipping violation
• The error message identifies the forbidden artifacts and suggests corrective action
• This is in ADDITION to the existing artifact validation (required artifact must exist)

Example:

$ python ~/.automaton/scripts/status.py --task fix-login-bug --transition implement
ERROR: Cannot transition to implement phase. Found out-of-order artifacts:
  - BUG_REPORT.md (belongs to bug_find phase)
Remove out-of-order artifacts before transitioning.

Acceptance Criteria

• status.py exists in ~/.automaton/scripts/
• --task flag shows current phase (including approval sub-states), allowed actions, forbidden actions, next artifact, next phase
• --task shows approval status for phases with :awaiting_approval or :approved sub-states
• --transition flag validates and writes .state transitions (including approval sub-states)
• --transition refuses transition from :awaiting_approval to anything other than :approved
• --transition refuses transition past :awaiting_approval without approval
• --approve command transitions :awaiting_approval to :approved
• --approve refuses if current phase is not :awaiting_approval
• --approve records approval in .state.approvals log
• --approve refuses for phases that don't require approval
• --create-task creates task folder with .state = new and empty .state.approvals
• --create-task validates kebab-case task names
• --create-task refuses if task already exists
• --transition refuses transition if forbidden artifacts exist in task folder
• --transition refuses transition if required artifact is missing or empty
• --list flag shows all tasks with their current phase and approval status
• --validate-folder flag checks for out-of-order artifacts per phase
• --validate-folder flags task folders without .state as manually created
• --validate-folder uses the phase-to-forbidden-artifacts mapping
• --validate-folder excludes non-artifact files (.state, .state.approvals, VRAM_CONFIG.md, PARENT_SPEC.md, REVIEW.md)
• --audit flag runs all categories of checks across all tasks
• --audit Category 1: out-of-order artifacts per phase
• --audit Category 2: state-artifact inconsistency (including approval sub-states)
• --audit Category 3: unauthorized git modifications (with graceful skip if no git repo)
• --audit Category 4: manually created task folders (no .state file)
• --audit outputs structured report with exit codes (0=clean, 1=violations, 2=error)
• Fallback to artifact heuristic when .state doesn't exist
• Atomic writes for .state file
• Approval log (.state.approvals) is created and maintained
• Transition validation (only legal transitions allowed, including approval sub-states)
• Clear error messages for invalid states, illegal transitions, missing artifacts, out-of-order artifacts, approval violations
• Sub-task support (reading .state from sub-task folder)
• Project path resolution (defaults to CWD, handles ~/.automaton/)
• Tests in tests/test_status.py

14. Tool integration hooks (OPTIONAL — not required for v1)

These commands are designed for agent tool integrations (opencode skills, Cursor rules, Aider hooks, etc.) that want to enforce workflow rules at the tool-action level. They are not required for the framework to function — all enforcement in v1 is prompt-based plus status.py checks. Tool integration is a future configurable layer that an agent tool can opt into.

--can-edit — Pre-edit hook

python ~/.automaton/scripts/status.py --can-edit --task {task-name} [--project {project-path}]

Returns whether code edits are allowed for the task's current phase:

• Exit code 0 + "ALLOWED" if the current phase allows code edits (implement, doc_review)
• Exit code 1 + "DENIED: Task '{task-name}' is in {phase} phase. Code edits require implement or doc_review phase." if not

Agent tools can call this before allowing a file edit. If the tool supports pre-action hooks, it can block edits that don't pass this check. This is opt-in — without tool integration, this check is advisory (the FORBIDDEN section in phase prompts).

--can-create-task — Pre-task-creation hook

python ~/.automaton/scripts/status.py --can-create-task [--project {project-path}]

Returns whether a new task can be created. Always returns ALLOWED — this hook exists for tool integrations that want to gate task creation through the tool layer rather than relying on prompts.

--scope-check — Scope confinement hook

python ~/.automaton/scripts/status.py --scope-check --task {task-name} --file {file-path} [--project {project-path}]

Returns whether the given file path is within the project's scope:

• Exit code 0 + "IN_SCOPE" if {file-path} is within {project}/ or ~/.automaton/
• Exit code 1 + "OUT_OF_SCOPE: File '{file-path}' is outside project '{project}'." if not

Agent tools can call this before allowing file reads/writes to enforce scope confinement. This is opt-in — without tool integration, scope confinement is advisory (the .rules.md rule).

--same-session — Session discipline hook

python ~/.automaton/scripts/status.py --same-session --task {task-name} [--project {project-path}]

Returns whether the task was created in the current session (heuristically determined by comparing task creation time with a session marker):

• If tasks/{task-name}/.state was created within the last N minutes (configurable, default 30), returns "SAME_SESSION" with exit code 1
• Otherwise returns "DIFFERENT_SESSION" with exit code 0

This is a best-effort heuristic — it cannot reliably determine sessions across agent restarts. It's opt-in and should not be the sole enforcement for session discipline.

Configuration

Tool integration hooks are always available in status.py but are not called by any framework prompts in v1. To activate tool-level enforcement, the agent tool configuration (e.g., opencode skills, Cursor rules) should:

1. Call --can-edit before allowing file edits and block if DENIED
2. Call --scope-check before allowing file access outside the project
3. Call --can-create-task is a no-op in v1 (always ALLOWED) but reserved for future use

No configuration file is needed — the hooks are available on demand. The framework does not require them.

Acceptance Criteria

• status.py exists in ~/.automaton/scripts/
• --task flag shows current phase (including approval sub-states), allowed actions, forbidden actions, next artifact, next phase
• --task shows approval status for phases with :awaiting_approval or :approved sub-states
• --transition flag validates and writes .state transitions (including approval sub-states)
• --transition refuses transition from :awaiting_approval to anything other than :approved
• --transition refuses transition past :awaiting_approval without approval
• --approve command transitions :awaiting_approval to :approved
• --approve refuses if current phase is not :awaiting_approval
• --approve records approval in .state.approvals log
• --approve refuses for phases that don't require approval
• --create-task creates task folder with .state = new and empty .state.approvals
• --create-task validates kebab-case task names
• --create-task refuses if task already exists
• --transition refuses transition if forbidden artifacts exist in task folder
• --transition refuses transition if required artifact is missing or empty
• --list flag shows all tasks with their current phase and approval status
• --validate-folder flag checks for out-of-order artifacts per phase
• --validate-folder flags task folders without .state as manually created
• --validate-folder uses the phase-to-forbidden-artifacts mapping
• --validate-folder excludes non-artifact files (.state, .state.approvals, VRAM_CONFIG.md, PARENT_SPEC.md, REVIEW.md)
• --audit flag runs all categories of checks across all tasks
• --audit Category 1: out-of-order artifacts per phase
• --audit Category 2: state-artifact inconsistency (including approval sub-states)
• --audit Category 3: unauthorized git modifications (with graceful skip if no git repo)
• --audit Category 4: manually created task folders (no .state file)
• --audit outputs structured report with exit codes (0=clean, 1=violations, 2=error)
• --can-edit returns ALLOWED/DENIED based on current phase (optional, for tool integration)
• --can-create-task returns ALLOWED (optional, reserved for future tool integration)
• --scope-check returns IN_SCOPE/OUT_OF_SCOPE (optional, for tool integration)
• --same-session returns SAME_SESSION/DIFFERENT_SESSION heuristic (optional, for tool integration)
• Fallback to artifact heuristic when .state doesn't exist
• Atomic writes for .state file
• Approval log (.state.approvals) is created and maintained
• Transition validation (only legal transitions allowed, including approval sub-states)
• Clear error messages for invalid states, illegal transitions, missing artifacts, out-of-order artifacts, approval violations
• Sub-task support (reading .state from sub-task folder)
• Project path resolution (defaults to CWD, handles ~/.automaton/)
• Tests in tests/test_status.py

Non-Goals

• This spec does not cover prompt restructuring (separate task)
• This spec does not cover autopilot integration (separate task)
• This spec does not cover dashboard integration (future work)
• Tool integration hooks are implemented in v1 but are optional and not called by any framework prompt