# Task phase machine

Deterministic task-phase harness for meaningful execution work.

## Intent
LLM works inside a phase.
Runner/files enforce legal transitions, evidence gates, and a final retrospective when needed.

## Core phases
- `intake`
- `shape`
- `implement`
- `verify`
- `review`
- `repair`
- `done`
- `blocked`
- `needs_user_decision`
- `retrospective`
- `closed`

## Deterministic transitions
```text
intake -> shape | blocked | needs_user_decision
shape -> implement | blocked | needs_user_decision
implement -> verify | blocked | needs_user_decision
verify -> review | repair | blocked | needs_user_decision
review -> done | repair | blocked | needs_user_decision
repair -> verify | blocked | needs_user_decision
done -> retrospective | closed
blocked -> retrospective | closed
needs_user_decision -> retrospective | closed
retrospective -> closed
```

Forbidden:
- `implement -> done`
- `shape -> done`
- `repair -> done`
- `verify -> implement`
- `retrospective -> repair`
- `retrospective -> implement`

## Terminal state
`closed` is the only fully terminal phase.

Meaning:
- `done` = main deliverable finished
- `blocked` = main deliverable blocked
- `needs_user_decision` = main deliverable needs user choice
- `retrospective` = system-learning tail, no main-deliverable repair
- `closed` = task outcome plus follow-up learning captured

## Required STATE.md fields
- Phase:
- Status:
- Objective:
- Done gate:
- Not doing:
- Reality constraints:
- Validation plan:
- Current result:
- Next step:
- Blockers:
- Evidence location:
- Evidence link:
- Candidate done: yes|no
- Validator status: pending|pass|fail
- Repair applied: yes|no
- Revalidation status: pending|pass|fail
- Gate profile:
- Retrospective required: yes|no
- Retrospective status: pending|done
- Preventive changes needed: yes|no
- Observed failures summary:
- Required gates:
- Gate status:
- Observed failures:
- Preventive changes proposed:
- Follow-up tasks created:
- Last updated:

## Gate layers
Use three layers.

### 1. Universal gates
Always required:
- `truthfulness_check_pass`
- `evidence_link_present`

### 2. Task-class gate profile
Built-in profiles:
- `repo_code`
- `docs_only`
- `audit`
- `migration`
- `ops_setup`
- `research_with_artifact`

Each profile adds deterministic required gates.

### 3. Task-instance gates
The task can add more under `Required gates:`.
Each required gate must have an explicit status under `Gate status:`.
Allowed statuses:
- `pass`
- `fail`
- `pending`
- `n/a`

Important:
- required gates for `verify -> review` and `review -> done` must be explicit `pass`
- implied or prose-only claims do not count

## Retrospective rule
Retrospective is for **system improvement**, not deliverable repair.

It may:
- record failures
- record missing guardrails
- propose preventive changes
- create follow-up tasks

It may not:
- reopen implementation
- repair the main deliverable
- expand the original task scope

If `Preventive changes needed: yes`, retrospective must leave:
- at least one preventive change proposal
- at least one follow-up task id
- matching task workspace folder(s) under `/home/sebas/work/tasks/`

Recommended triggers for `Retrospective required: yes`:
- task went through `repair`
- validation failed at least once
- blocked state revealed process/tooling gaps
- intent confusion or questionnaire miss happened
- evidence was weak or missing
- too many passes or no-material-progress event
- weird workaround needed

## Evidence rule
Assume the user reviews by opening files remotely.

Example STATE.md gate section:
```md
- Gate profile: repo_code
- Required gates:
  - validation_output_saved
  - feature_states_complete
- Gate status:
  - truthfulness_check_pass: pass
  - evidence_link_present: pass
  - validation_output_saved: pass
  - feature_states_complete: pending
```

So:
- always expose proof through a clickable link
- prefer full URLs when available
- for complex evidence bundles, use one HTML index such as `artifacts/evidence.html`

## Init helper
```bash
bin/task-phase-init T-123 --goal "..." --source "..." --repo /path/repo
```

Creates:
- `README.md`
- `STATE.md`
- `EVIDENCE.md`
- `RETROSPECTIVE.md`
- `artifacts/`
- `artifacts/evidence.html`
- `scratch/`

## One-pass runner
```bash
bin/task-phase-run --task-dir /home/sebas/work/tasks/T-123 --repo /path/repo
```

Behavior:
- reads `STATE.md`
- refuses fully closed tasks
- builds a phase-specific prompt
- runs one bounded Pi pass
- requires `STATE.md` update
- requires legal phase transition
- enforces phase gates after the run
- enforces retrospective completion before `retrospective -> closed`
- writes pass artifacts under `artifacts/phase-runs/<timestamp>/`

## Loop controller
```bash
bin/task-phase-loop --task-dir /home/sebas/work/tasks/T-123 --repo /path/repo
```

Behavior:
- repeatedly calls `task-phase-run`
- stops on terminal phase:
  - `closed`
- stops on runner failure
- stops on no material progress
- writes loop artifacts under `artifacts/phase-loop-runs/<timestamp>/`
- does not decide transitions itself; it only keeps advancing passes while the runner keeps accepting them