# Workflow phases -- full reference

Fetch when the user asks: "que pasa en la fase X?", "como salgo
de clarificacion?", "que necesito para arrancar build?",
"cuales son los specs?".

The Forge build workflow has 6 phases. Each phase has a
distinctive intent + an exit condition. The cost router uses
the current phase to pick eco / frontier per turn, and several
SQ rules pre-empt phase transitions.

## Phase I -- Intake

**Intent:** capture the raw user request + flag whether the
project already exists.
**Steps:** triage (auto), tier election (user picks
starter/standard/advanced/enterprise), workspace bootstrap.
**Eco-friendly:** yes. Default tier. Cheap.
**Exit:** tier locked + workspace ready.
**Gates:** G1 (tier required), G2 (vault has >= 2 BYOK keys).

## Phase II -- Clarification

**Intent:** narrow the request into something a spec can be
written against. Disambiguation rounds with the user.
**Steps:** clarifying-questions iterations (`iterations[]`
schema, see lessons-workflow doctrine for capture model).
**Eco-friendly:** yes. Default eco; escalate to frontier on
SQ rule-violation text.
**Exit:** user signs off the clarification summary.
**Gates:** none.

## Phase III -- Specification

**Intent:** produce the three core specs: RFP, ARCH, DESIGN.
**Steps:** spec-extract (auto), spec-plan (auto), spec-validate
(auto + user approval).
**Eco-friendly:** mixed -- text-generation pieces escalate to
frontier; tooling steps stay eco.
**Exit:** each spec has `done_at` + `approved_at` non-empty in
workflow_state.specs.
**Gates:** G3 (no phase-skip), G-DOC (each step ends with a
commit ASCII-only).

## Phase IV -- Approval

**Intent:** human sign-off on the spec set + block plan.
**Steps:** review board (async), block-plan, ship-target
selection.
**Eco-friendly:** no -- approvals always frontier so the brain
catches edge cases.
**Exit:** all `approvals.*.approved_at` non-empty + block_plan
exists.
**Gates:** G4 (block-plan OK), G5 (fase V sin OK explicito de
los 3 spec docs).

## Phase V -- Build

**Intent:** execute the block plan. Code + tests + integrations.
**Steps:** per-block dev iterations, smoke tests, integration
gates.
**Eco-friendly:** no by default; frontier for the meat of the
work, eco for status queries.
**Exit:** every block in block_plan has status='done' +
smoke tests green.
**Gates:** G6 (block tests rojos = bloqueo), G7 (creds
faltantes = bloqueo).

## Phase VI -- Ship

**Intent:** deploy + post-launch monitoring.
**Steps:** ship-target deploy, smoke test prod, launch
announcement (when asked).
**Eco-friendly:** mixed.
**Exit:** smoke-prod green + announcement composed.
**Gates:** G8 (launch sin smoke verde).

## What the brain MUST do per phase

1. **Read workflow_state from the injected block** -- never
   re-fetch via yujin.workflow.state for fields already
   present.
2. **Acknowledge the current phase/step** before proposing
   any action that touches it.
3. **Refuse phase skips > 1 forward** -- G3 hard rule.
4. **Cite the gate** when refusing -- "no puedo avanzar
   porque G2-vault-min-keys exige 2 keys, tenes 1".
5. **Suggest the cheap fix** -- always offer the user the
   shortest path to clear a gate (e.g. `yf keys setup`).

## How to read iterations[]

When `workflow_state.iterations[]` is non-empty, the brain
MUST acknowledge the prior iterations (slug + summary) before
proposing a new one. Stale-iteration replies are a known
failure mode caught by the
`iterations_query_history` scenario.

## Forbidden during a phase

- Phase I-III: NEVER write production code. Specs only.
- Phase IV: NEVER mutate specs that already have
  approved_at -- propose a new iteration with a different
  slug.
- Phase V: NEVER bypass smoke tests. If they fail, the
  brain MUST surface the failure, not paper it over.
- Phase VI: NEVER announce a launch before smoke-prod is
  green.
