Phase Lifecycle

A phase is the primary unit most workflows operate on. Its lifecycle is a strict, file-driven state machine resolved by np:next and np:dispatch.

States

A phase is in exactly one of:

State	Trigger to enter	Trigger to leave
scaffolded	np:new-project or np:new-milestone created the phase dir	<NN>-CONTEXT.md exists
discussed	np:discuss-phase finalized CONTEXT.md	<NN>-RESEARCH.md (optional) or PLAN written
researched	np:research-phase wrote RESEARCH.md	PLAN.md authored
planned	np:plan-phase wrote at least one <NN>-NN-PLAN.md and plan-checker passed	first task commit exists
executing	first task commit exists	every task in every plan committed
executed	all task commits in place	<NN>-VERIFICATION.md written
complete	np:verify-work wrote VERIFICATION.md and all SCs Pass/Defer	next phase begins

The state is derived from files, not stored. np:next reads STATE.md + roadmap.yaml + the phase directory and computes the state every time.

The six-rule next-action gate (D-15)

np:next resolves the next action through a fixed rule cascade. The first rule that matches wins:

1. Rule 1 — no project at all → np:new-project.
2. Rule 2 — current phase has no CONTEXT → np:discuss-phase <N>.
3. Rule 3 — CONTEXT exists but no PLAN → np:plan-phase <N> (research is optional, opted into by user).
4. Rule 4 — PLAN exists but tasks remain → np:execute-phase <N>.
5. Rule 5 — all tasks committed but no VERIFICATION → np:verify-work <N>.
6. Rule 6 — VERIFICATION written → advance to next phase or report milestone-complete.

np:dispatch runs the same logic but actually invokes the resolved workflow via Skill().

Producer / consumer separation

Workflows produce files. Subagents consume them. A well-formed phase directory tells you exactly which steps have run:

.nubos-pilot/phases/05-planning-workflows-agents/
├── 05-CONTEXT.md          ← produced by np:discuss-phase
├── 05-RESEARCH.md         ← produced by np:research-phase     (optional)
├── 05-PATTERNS.md         ← produced by np:plan-phase pre-step
├── 05-VALIDATION.md       ← produced by np:plan-phase pre-step
├── 05-01-PLAN.md          ← produced by np:plan-phase
├── 05-01-PLAN-REVIEW.md   ← append-only plan-checker audit trail
├── 05-01-SUMMARY.md       ← produced by np:execute-plan per plan
├── 05-01/tasks/           ← produced by np:plan-phase if promoted
│   ├── 05-01-T01.md
│   └── 05-01-T02.md
├── 05-VERIFICATION.md     ← produced by np:verify-work
├── 05-DISCUSSION-LOG.md   ← optional Q&A transcript
├── 05-UI-SPEC.md          ← optional, np:ui-phase
├── 05-AI-SPEC.md          ← optional, np:ai-integration-phase
├── 05-REVIEW.md           ← optional, np:code-review
└── 05-verify.sh           ← optional executable verifier

Only <NN>-<MM>-PLAN.md and tasks/*.md are parser-mandatory. Every other file is workflow-produced and may be absent — its absence simply means the workflow step did not run yet. See the Phase Directory Layout reference for the full table.

Plan-checker loop (D-15)

Inside np:plan-phase, planner and plan-checker run a bounded revision loop:

planner → PLAN.md ──► plan-checker
                          │
              status: passed ──► commit, advance
                          │
              status: issues_found
                          │
                          ▼
                planner (revision mode) → PLAN.md → plan-checker
                          │
                          (max 2 iterations)

Every iteration appends a YAML verdict block to <NN>-PLAN-REVIEW.md. The file is byte-level append-only — pre-existing bytes must remain a SHA-256-verified prefix of post-append bytes. Even abort does not truncate it.

Verification (D-21/D-22)

np:verify-work is the post-execution twin of plan-checker: same goal-backward methodology, different timing. np-verifier reads ROADMAP.md success_criteria, PLAN.md, the union of files_modified across all task frontmatter, and the per-phase task commits, then classifies each SC as:

• Pass — deterministic evidence (commit SHA, test name, grep result) supports the criterion.
• Fail — deterministic evidence contradicts the criterion.
• Defer — criterion explicitly deferred to a later phase.
• Needs-User-Confirm — subjective judgment required (UX, "feels", "looks right").

The verifier never proposes fixes and never edits source. It writes <NN>-VERIFICATION.md with the breakdown; gap-fill (if needed) routes through np:plan-milestone-gaps.