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)
This commit is contained in:
@@ -0,0 +1,435 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user