Phases

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	Isolated locale build in .saipen/saitranslate/. Never touches main tree. Quarantined env.

Infrastructure phases

Phase	Entry	What it does
PREPARE	saipen prepare	Package work for handoff to next agent. Freshness check against HEAD. Write injection instructions.
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.133.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 an event pair; a skipped mutation is fatal, not a shrunken denominator.

ДED Voice: phases rant

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