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.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; cc = continue, ccc = pushing chain, hh at a phase name = FAIL.
• 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? Сиди и жди, пока человек решит. Всё. Не надо выдумывать. Шестнадцать фаз — и каждая делает своё дело. Агент не думает — агент делает."