# Phases

16 phases total. Core (9) + Maintenance (5) + Infrastructure (2).

## Core phases

| Phase | Entry | What it does |
|---|---|---|
| INIT | `saipen set` | Bootstrap .saipen/. Confirm no existing .saipen first. Create STATE/BOARD/LOG/templates. |
| PLAN | `saipen plan` or `saipen goal` | Amplify user intent into tickets. <=8 lines analysis. Safe defaults over interrogation. |
| SCOUT | After PLAN | Claim top TODO ticket. Read KNOWLEDGE/. Understand code before BUILD. |
| BUILD | After SCOUT | Smallest safe change. Full code: no stubs, null/empty/error paths. Match repo style. **Reuse ladder** (v7.124.0): own code → stdlib → an existing dependency → then write it. Adding a dependency is a ticket, not a build step. |
| VERIFY | After BUILD | Does it work? Write+run test. If broken: fix, don't REVERT. If unreachable: manual-verify WAIT. **Gate-stuck-red guard** (v7.101.0): before reporting that *everything* failed, run a control with known result. A real defect is almost never total; a misconfigured harness almost always is. **Retry owes an answer** (v7.124.0): a repeated attempt MUST name what changed since the last one; "nothing" means the retry is forbidden. |
| REVIEW | After VERIFY | Is it well made? `mode: manual-verify` -> human. Otherwise: self-review against quality gates. Max 2 passes — after that, ticket to BLOCKED. |
| SHIP | `saipen ship` or after REVIEW | Version bump, README/CHANGELOG update, tag, push. `no-publish`: skip git steps. **Release guard** (v7.99.0): `release.yml` refuses to publish when VERSION or CHANGELOG disagrees with the tag name. **Preflight repair loop** (v7.128.0): a fixable pre-commit failure returns `SHIP -> BUILD` (narrow edge, current ticket only) then repeats VERIFY/REVIEW/SHIP; publish failures and already-pushed work stay under recovery. Release order explicit: prepare VERSION/README/CHANGELOG → rerun validators → commit → push. **Exact-ref publish** (v7.130.0): pushes branch + one exact `refs/tags/vVERSION`; `--tags`/`--follow-tags` forbidden for releases. |
| DONE | After SHIP | Move ticket to DONE [x]. If TODO remains: SCOUT. If empty: HUNT (auto). |
| BLOCKED | Unworkable board | All tickets stuck. Write WAIT: blocked with category + exact question. |

## Maintenance phases

| Phase | Entry | What it does |
|---|---|---|
| HUNT | Auto on empty DONE | 6 signal categories, cap 5 tickets. Skip only if exact hash match in LOG. Subagents: parallel dispatch. |
| MARKHUNT | `saipen markhunt` | Dry exhaustive audit. Record only, never fix. Findings carry evidence (file:line or command output). |
| ADD | After clean HUNT | Evolutionary completion. Priority: bugfix > complementary > workflow > UX > convention. 2 paths: direct minimal, or planned. |
| CLEAN | `saipen clean` | Deep scrub: board prune, orphan hunt, link audit, trash removal. Seal oversized LOG. |
| TRANSLATE | `saipen translate` / `ee` preparation path | Isolated full real-surface locale build in .saipen/saitranslate/. A collectable run writes the seven-field ready handoff; never touches main tree. |

## Infrastructure phases

| Phase | Entry | What it does |
|---|---|---|
| PREPARE | `saipen prepare [producer]` | Package complete work with status/producer/source_head/coverage/payload/verified/instructions. `ee` and `qq` stop here: no integration or push. |
| VALIDATE | `saipen validate` | Run conformance script. Fix structural corruption (shape only, never content rewrite). |

## Phase transitions

```
All phases have -> BLOCKED available (universal).

Core flow: INIT -> PLAN -> SCOUT -> BUILD -> VERIFY -> REVIEW -> SHIP -> DONE
                         |                    v
                         +---> BLOCKED <------+

Maintenance flow:
  DONE (empty board) -> HUNT -> ADD -> SCOUT -> BUILD -> ...
                     |        |
                     |        +-> (mature) -> DONE
                     v
                   (hash match) -> skip, go to ADD

Explicit commands jump to target phase from anywhere:
  saipen clean   -> CLEAN
  saipen ship    -> REVIEW gates first, then SHIP
  saipen validate-> VALIDATE
  saipen markhunt-> MARKHUNT
  saipen translate-> TRANSLATE
  saipen prepare -> PREPARE
  saipen stop    -> checkpoint, halt
```

## WAIT categories in phases

Every phase doc that prescribes a WAIT uses the closed 7-word vocabulary:
- `manual-verify`, `destructive-op`, `first-publish`, `user brake`, `blocked`, `safety valve`, `init`

**Enforced** (v7.101.0+): `phases/done.md` previously endorsed `next_action: wait for user command` — no legal prefix, TEST-001 couldn't execute it. Replaced with `WAIT: user brake -- <reason>`. Every phase doc's prescribed next_action is now checked against RFC SS 1.2's prefix rules, not just WAITs (v7.103.0).

## Phase-level checks added (v7.104.0–v7.157.0)

- **last_event enforced** (v7.115.0): STATE.md `last_event` field catches state that drifted from its own LOG. RECOMMENDED field, validated against LOG tail.
- **review_passes enforced** (v7.117.0): the field exists so `phases/review.md` can enforce its 2-pass cap mechanically. Number now read.
- **digest.md freshness** (v7.117.0): `kitchen/digest.md` shape + version checked against VERSION. Live digest was 33 releases stale.
- **claim_time validated** (v7.116.0): `claim_time` checked as ISO-8601 UTC. Liveness judged from it against 15-minute window.
- **MARKHUNT manifest validated** (v7.118.0): `.saipen/kitchen/markhunt_progress.md` checked for shape, cursor vocabulary, vector completeness.
- **no-git head pair guarded** (v7.118.0): one real hash + one `no-git` = FAIL (was silently skipped).
- **Ticket-field list closed** (v7.122.0): RFC 1.2 states the field list — `needs/owner/claim_time/blocker/verify/review_passes` — each field's job, the `\|` escape. `verify:` was enforced with no document naming it.
- **agent: seat defined** (v7.125.0): `agent:` names the seat and is inherited from STATE. Placeholders FAIL; changing it logs a `DEC` naming both values.
- **SHIP→BUILD edge** (v7.128.0): DFA row added — pre-commit fixable failure returns to BUILD (current ticket only, must repeat VERIFY/REVIEW/SHIP).
- **Project-root binding** (v7.132.0): BOOT binds one root per session — Git worktree/common-dir, linked worktrees use main worktree's memory, non-Git nearest ancestor with `.saipen/`, `--project-root` overrides. Checkpoint paths never leave the bound root.
- **Sealed LOG mutations** (v7.133.0): mutation targets resolve to active or newest sealed segment with a skipped mutation fatal, not a shrunken denominator.
- **last_event migration boundary** (v7.135.0): schema v1 missing it WARNs and stays readable; v2 with an event-bearing LOG and no marker FAILs; Recovery derives the same value idempotently.
- **Tag audit fails closed** (v7.136.0): `git cat-file --batch` process failures exit nonzero with focused FAIL; legal `<spec> missing` stays a warning.
- **Bootstrap reports process truth** (v7.137.0): failed writes exit nonzero without `Done.`; PowerShell block regex preserves user-owned whitespace bytes.
- **Exports bind to project owner** (v7.138.0): archive beside the `.saipen/` owner; foreign Git repos rejected unless explicit root supplied.
- **Crew launch truth** (v7.139.0/v7.145.0): Unix + Windows launchers observe every seat; refusal stops the run and names the window.
- **Bytecode not a release artifact** (v7.140.0): injectors clean installed trees; repository ignore rules cover cache dirs.
- **Shell predicates fail closed** (v7.141.0): grep status >1 fails the operation; uninstall handles file/symlink/directory skill paths.
- **Lost enumeration is not a skip** (v7.142.0): nonzero `git tag -l v*` exits nonzero; missing Git may SKIP loudly.
- **LOG filter propagates failure** (v7.143.0): sed shim returning 7 → `FAIL: LOG.md read/filter failed`, no LOG PASS.
- **Hook resolves Bash** (v7.144.0): no-Python floor invoked through resolved `bash`; floor-without-Bash fails focused.
- **Re-authorization survives crash** (v7.146.0): validator replays the counter rebuild and compares against STATE.md; `DEC: goal reauthorized` must explain the counters.
- **Append targets end on a line boundary** (v7.147.0): all 21 append targets' last byte read; red control strips a fixture's final newline.
- **Shortcut resolves to a defined command** (v7.148.0): table's right-hand column parsed; `hh` at a phase name = FAIL. Exact current assignments are additionally pinned by scenario 183.
- **Empty DONE board goes to HUNT** (v7.148.0): one document decides; `phases/done.md` defers to § 1.11 by name.
- **Phase-named commands checkpoint** (v7.151.0): phase-switching list derived from phase docs, not hand-kept; `init` excluded structurally.
- **Skill triggers match the RFC table** (v7.153.0): SKILL.md frontmatter must exactly equal § 1.10's shortcuts plus confusable mapping; both drift halves red-tested.
- **No-op mutations are rejected** (v7.155.0): harness refuses every unchanged callable result before running the validator; identity-mutation self-control stays red-capable.
- **Root device-name snapshots** (v7.156.0): a real Windows `nul` entry is ignored at repository root and excluded from canonical audit copies without deleting the original artifact.
- **Translated shortcut parity** (v7.156.0): locale README is the source; mirrors and non-Core guides consume the same callout with exact keys, Cyrillic twins, order, and RFC target.
- **Chat language + voice contract** (v7.157.0): RFC, BOOT, STYLE, and SKILL metadata carry one exact EE/EN/RU precedence and persistent caveman-дед duty; separate mutations prove both can fail.

## ДED Voice: phases rant

> "INIT? Создал папку — и работай. PLAN? Расписал задачу — и вперёд. BUILD? Чини, не ломай. VERIFY? Тест написал — работает? Отлично. SHIP? Залил — и забыл. BLOCKED? Сиди и жди, пока человек решит. Всё. Не надо выдумывать. Шестнадцать фаз — и каждая делает своё дело. Агент не думает — агент делает."