Complete tasks 3-7: harden verdict parsing, outputs retention, base branch, linux schedule parity, claim loop task

README.md

@@ -10,16 +10,20 @@ Before you can use the framework in any project, you must install the core logic
 
 ```bash
 # Clone the framework into the global config directory
-git clone http://10.37.0.86:3003/hermes/automaton ~/.automaton
+git clone <your-git-url> ~/.automaton
 
 # Enter the directory
 cd ~/.automaton
 
 # Make the installation script executable and run it
+# You must provide the git URL as the first argument
 chmod +x install.sh
-./install.sh
+./install.sh <your-git-url>
 ```
-*Note: This creates the "brain" of the framework (prompts, state machines, and rules) in your home directory.*
+
+The git URL is required because the framework uses it for self-updates and the self-improvement loop. Choose carefully -- it cannot be changed later without reinstalling.
+
+*Note: This creates the "brain" of the framework (prompts, state machines, and rules) in your home directory. A self-improvement loop is created and scheduled by default (see Loop Engineering below).*
 
 ### Updating the Framework
 
@@ -184,6 +188,108 @@ When a task is decomposed, the Orchestrator creates sub-tasks under `tasks/{pare
 - `contracts/harness-integration.md`: Integration contract for agent harnesses (opencode, aider, etc.).
 - `plugins/automaton-guard/`: opencode plugin that intercepts `edit`/`write` calls and checks `--can-edit` before allowing them.
 
+## Loop Engineering (beta, v1)
+
+Automaton can run unattended workflow loops: each loop has an OS-level schedule (launchd / cron / schtasks) and is constrained by 6 brake gates enforced in `status.py`. The single source of truth for loop runtime state is `.state.loop` per loop at `{project}/.automaton/loops/<name>/.state.loop`.
+
+```bash
+# Create a loop from a template (only way to bootstrap)
+python3 ~/.automaton/scripts/status.py --create-loop my-ci-triage --from-template ci-triage --project /path/to/project
+
+# Install the native OS schedule unit (launchd/cron/schtasks)
+python3 ~/.automaton/scripts/status.py --install-schedule my-ci-triage --interval 3600 --project /path/to/project
+
+# Pre-tick gate check (6 brakes; first failure halts the loop)
+python3 ~/.automaton/scripts/status.py --check-gate my-ci-triage --project /path/to/project
+
+# Clear a halt (only way; no auto-approve in v1)
+python3 ~/.automaton/scripts/status.py --approve --loop my-ci-triage --project /path/to/project
+
+# List all loops and their status
+python3 ~/.automaton/scripts/status.py --loop-list --project /path/to/project
+```
+
+Loop states: `running`, `halted`, `paused`, `complete`. Halt reasons: `iterations_exhausted`, `budget_exhausted`, `verifier_failed`, `drift_detected`, `human_intervention`. The per-tick engine is `scripts/loop-runner.py --mode tick`; it gates first, spawns Implement / Verify / Orchestrate role sessions, and writes `.state.loop` atomically. Concurrent ticks on the same loop and concurrent `--pause-loop` / `--approve --loop` writes are serialized via a cross-process file lock on `<loop_path>/.state.lock` (POSIX `fcntl.flock`, Windows `msvcrt.locking`); see `design/loops/technical.md` §7 "Lock serialization". See `design/loops/technical.md` §7 for the full 11-step flow.
+
+### Quick Start
+
+```bash
+# 1. Create a loop from a template
+python3 ~/.automaton/scripts/status.py --create-loop my-ci-triage \
+  --from-template ci-triage --project /path/to/project
+
+# 2. Install the OS schedule (launchd on macOS, cron on Linux, schtasks on Windows)
+python3 ~/.automaton/scripts/status.py --install-schedule my-ci-triage \
+  --interval 3600 --project /path/to/project
+
+# 3. Monitor
+python3 ~/.automaton/scripts/status.py --loop-list --project /path/to/project
+python3 ~/.automaton/scripts/status.py --audit --project /path/to/project
+```
+
+### Tick Cycle
+
+Each tick runs this 11-step flow (see `design/loops/technical.md` §7 for details):
+
+```
+gate check -> find work -> ensure worktree -> spawn Implement -> spawn Verify
+-> parse verdict -> spawn Orchestrate -> atomic state write -> log
+```
+
+The runner resolves prompt files from `loop.json` `roles.*.prompt` (e.g. `loop-implement.md`), substitutes content-level tokens (`{task_brief}`, `{acceptance_criteria}`, `{next_hint}`, `{artifact_content}`, etc.), writes the resolved prompt to `outputs/tickN-<role>-prompt.md`, and passes it to the harness.
+
+### Configuration (`loop.json`)
+
+| Field | Description |
+|-------|-------------|
+| `name` | Loop name (kebab-case) |
+| `schedule.interval_seconds` | Tick interval for daemon mode |
+| `brakes.max_iterations` | Max ticks before halt |
+| `brakes.max_budget_usd` | Optional USD budget cap (null = unlimited) |
+| `brakes.score_plateau_window` | Score plateau detection window |
+| `blast_radius.file_scope` | List of paths the loop may edit |
+| `blast_radius.use_worktree` | If true, tick runs in a per-loop git worktree |
+| `work_source.kind` | `single`, `audit`, or `backlog` |
+| `roles.implement.prompt` | Prompt file for Implement role |
+| `roles.verify.prompt` | Prompt file for Verify role |
+| `roles.orchestrate.prompt` | Prompt file for Orchestrate role |
+| `harness.command` | Command template with `{prompt}`, `{prompt_content}`, `{cwd}` tokens (default invokes `opencode run --dir <cwd> <prompt>`; override for other harnesses -- Pi Dev, aider, etc.) |
+| `acceptance_criteria` | List of criteria for the verifier to check |
+
+### Monitoring
+
+- `--loop-list`: show all loops and their status
+- `--audit`: check for violations across all tasks and loops
+- `.state.log`: per-loop tick log (ISO-timestamped entries)
+- `outputs/`: per-tick artifacts and resolved prompts
+
+### Halt and Resume
+
+```bash
+# Pause a loop (disables the OS schedule unit)
+python3 ~/.automaton/scripts/status.py --pause-loop my-ci-triage --project /path/to/project
+
+# Resume a paused loop
+python3 ~/.automaton/scripts/status.py --resume-loop my-ci-triage --project /path/to/project
+
+# Clear a halt (the only way; no auto-approve in v1)
+python3 ~/.automaton/scripts/status.py --approve --loop my-ci-triage --project /path/to/project
+```
+
+### Self-Improvement Loop (Default-On)
+
+The framework installs a self-improvement loop by default at install time. This loop ticks against `status.py --audit` on the framework's own repo, picking up audit violations and resolving them unattended. It runs every 3600 seconds (1 hour) with `max_iterations: 10` and a score plateau window of 3.
+
+```bash
+# Disable the self-improvement loop
+python3 ~/.automaton/scripts/status.py --pause-loop self-improvement --project ~/.automaton/
+
+# Re-enable it
+python3 ~/.automaton/scripts/status.py --resume-loop self-improvement --project ~/.automaton/
+```
+
+The loop uses a git worktree at `~/.automaton/loops/self-improvement/worktree/` and is scoped to `scripts/`, `prompts/`, `tests/`, and `design/` directories.
+
 ## State Enforcement (v2.0)
 
 Automaton v2.0 enforces the state machine computationally, not just via prompts: