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.
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.
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.
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.121.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).

ДED Voice: phases rant

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