# Lifecycle

> Five phases, Gates and sign-off, Project documents

## Five phases

*Every project takes the same road: DESIGN → DEVELOP → VERIFY → DEPLOY → MAINTAIN. The server holds the phase, and the model cannot change it on its own.*

1. **DESIGN**: Ask, then write requirements, architecture, plan
2. **DEVELOP**: Work the plan one task at a time
3. **VERIFY**: Check every requirement, independent review
4. **DEPLOY**: Ship it and confirm it serves
5. **MAINTAIN**: Every change after launch

| Phase | What happens | Model | Exit |
| --- | --- | --- | --- |
| DESIGN | Five to ten questions first; then DESIGN.md gets `## Requirements` (R1..Rn) and `## Architecture` (a spec per module, impact analysis, dependency order), and PLAN.md mirrors those specs task by task | Design | A → B → C → develop |
| DEVELOP | One PLAN.md task per turn; each acceptance criterion is ticked `[x]` as it passes, and the next task starts on its own | Dev | verify |
| VERIFY | Requirement trace, integration checks, issues found, what could not be verified and a release recommendation, all written to VERIFY.md. An independent review is required | Dev | deploy |
| DEPLOY | The project's own release path, then a check that what was deployed actually serves; recorded in STATUS.md and VERIFY.md | Dev | maintain |
| MAINTAIN | The request is sized first. A small one is done directly; a medium one updates DESIGN / PLAN and passes Gate C before it is built; a large one goes back to DESIGN | Dev | — |

Each turn's system prompt carries only the current phase's playbook. New projects start in DESIGN; an existing project picks up at the phase its STATUS.md declares.

## Gates and sign-off

*Phases never move on their own. Every gate is a card, and it only opens when you press Approve.*

| Gate | Name | On approval |
| --- | --- | --- |
| A | Requirements | Records the requirements as agreed; still DESIGN |
| B | Architecture | Records the architecture as agreed; still DESIGN |
| C | Execution plan | PLAN.md is posted into chat as a file card, so the team reads the real file |
| develop | Start building | Enters DEVELOP |
| verify | Start verifying | Enters VERIFY |
| deploy | Go live | Enters DEPLOY |
| maintain | Into maintenance | Enters MAINTAIN |
| design | Back to design | Returns to DESIGN and clears A / B / C |

A, B and C only record an approval; they do not change the phase. Inside DESIGN the order is fixed: A → B → C → develop. Any other gate can be requested from any phase, forward or back, except the gate for the phase the project is already in. At the moment of approval the server checks the gate again, then writes the phase and checkpoints back into STATUS.md.

Gate cards come from the engine seat's `phase_gate`: two buttons, Approve and Request changes, or a written reply that goes back to the model word for word. A card never times out.

### Moving back

A project owner can click an earlier phase on the stepper, or approve a backward gate. Going back to DESIGN clears A / B / C and pauses Auto-Run. The server then runs a reconcile turn: from the stepper it fixes the documents and touches no code; from a gate it fixes the documents and carries on with the new work. Back in DESIGN, PLAN.md is marked superseded and its task blocks are kept.

## Project documents

*A project's state lives in a few Markdown files in its repository. They describe the current state only; the history is in git.*

| File | Holds | Written by |
| --- | --- | --- |
| STATUS.md | A short snapshot of now: phase, checkpoints, last action, blocker | The server writes the phase and checkpoints; the model writes the rest |
| DESIGN.md | `## Requirements` (R1..Rn) and `## Architecture`, describing only the current design | DESIGN; rewritten in place when a contract changes |
| PLAN.md | The execution ledger: task blocks, acceptance boxes, `Verify:` scripts | Planned in DESIGN, ticked in DEVELOP, one block per Auto-Run item |
| VERIFY.md | The verification record: requirement trace, integration checks, issues, unverified items, release call | VERIFY |
| AUDIT.md | The current queue item's root cause, findings, fixes and real verification evidence | Auto-Run |
| ARCHITECTURE.md | A larger project's architecture contract, treated like DESIGN.md | Only when the contract changes |

### Task blocks

```
### T1: <short imperative title> [S]
- Goal: what exists after this task that didn't before
- Modules: files / dirs it touches
- Requirements: R1, R3
- Acceptance:
  - [ ] observable, testable criterion
  - [ ] ...
- Verify: how to prove it (command / manual check)
```

Size `[S|M|L]`: a task must fit in one focused session, and anything bigger is split. Tasks are ordered so each builds only on finished ones, and every requirement is covered by at least one task. A queue item's block adds an `Item:` / `Items:` line; the host finds the block by that line (never the title) and runs the scripts named on `Verify:`.

### Size budgets

- **STATUS.md**: 16 KB · a target
- **PLAN.md · AUDIT.md · VERIFY.md**: 48 KB each · a target
- **DESIGN.md**: 160 KB · caps growth only
- **ARCHITECTURE.md**: 640 KB · caps growth only

A ledger that is over its budget still holds finished or superseded content, and that content should be deleted. A contract document's budget only caps growth; live contract text is not cut to fit it. Going over is not blocked, but the next turn gets a reminder.

### Record rules

- When something changes, rewrite or delete the old statement where it stands. Do not add an "update" paragraph beside it.
- Before finishing, check that retired names, flags and paths no longer read as current in the docs or in nearby code comments.
- Move anything still open to where it belongs (a code comment, the queue, STATUS.md) before deleting the paragraph that held it.
- Do not keep dated changelogs in the documents. The commit message is the changelog.
- Each section appears once per document.

> The same rules are written into the prompts of the engine seat, the chat seat and Auto-Run, so whichever seat edits a record follows the same standard.

### The Step panel

The server watches STATUS / PLAN / VERIFY / DESIGN and re-parses within 300 ms of a change: STATUS.md's phase, last action and blocker, and the checkboxes of PLAN.md and VERIFY.md grouped by heading, show up live in the Step panel on the right.