Milestone Lifecycle

A milestone is the primary unit most workflows operate on. Its lifecycle is a strict, file-driven state machine.

stateDiagram-v2
  [*] --> scaffolded: /np:new-project<br/>or /np:new-milestone
  scaffolded --> discussed: /np:discuss-phase
  discussed --> researched: /np:research-phase<br/>(optional)
  discussed --> planned: /np:plan-phase
  researched --> architected: /np:architect-phase<br/>(optional)
  researched --> planned: /np:plan-phase
  architected --> planned: /np:plan-phase
  planned --> executing: first task commit
  executing --> executed: all tasks committed
  executed --> complete: /np:verify-work<br/>all SCs Pass/Defer
  complete --> [*]

States

A milestone is in exactly one of:

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

The architected state is optional and only entered when the milestone introduces structural change (new module, new boundary, new data flow), when CONTEXT carries architecture_review: required, or when RESEARCH flags ≥ 3 [ASSUMED] claims in the architecture-patterns dimension. For purely additive milestones the lifecycle skips straight from researched to planned.

The state is derived from files, not stored. Anything that needs it recomputes from STATE.md, roadmap.yaml, and the milestone directory.

Happy-path command sequence

/np:new-project
    └► .nubos-pilot/milestones/M001/ scaffold

/np:discuss-phase 1
    └► M001-CONTEXT.md

/np:research-phase 1          (optional)
    └► M001-RESEARCH.md

/np:architect-phase 1         (optional, structural milestones only)
    └► M001-ARCHITECTURE.md

/np:plan-phase 1
    ├► planner (opus) → per slice: slices/S<NNN>/S<NNN>-{ASSESSMENT,PLAN,UAT}.md
    ├► plan-checker (opus) → M<NNN>-PLAN-REVIEW.md
    └► scaffold-all-tasks → tasks/T<NNNN>/T<NNNN>-{PLAN,SUMMARY}.md

/np:execute-phase 1
    └► for each slice in order:
         dispatch every task in parallel → one commit each
           task(M001-S001-T0001): …
           task(M001-S001-T0002): …
         wait for slice completion, then next slice

/np:verify-work 1
    └► M001-VERIFICATION.md (Pass/Fail/Defer per SC)

/np:validate-phase 1         (optional)
    └► M001-VALIDATION.md (Nyquist coverage audit)

Directory layout

.nubos-pilot/milestones/M001/
├── M001-CONTEXT.md          ← produced by /np:discuss-phase
├── M001-RESEARCH.md         ← produced by /np:research-phase (optional)
├── M001-ARCHITECTURE.md     ← produced by /np:architect-phase (optional, structural milestones)
├── M001-ROADMAP.md          ← produced by /np:plan-phase (milestone overview)
├── M001-META.json           ← produced by /np:plan-phase
├── M001-PLAN-REVIEW.md      ← append-only plan-checker audit trail
├── M001-VERIFICATION.md     ← produced by /np:verify-work
├── M001-VALIDATION.md       ← produced by /np:validate-phase (optional)
├── M001-SECURITY.md         ← produced by manual np-security-reviewer spawn (optional)
└── slices/
    ├── S001/
    │   ├── S001-ASSESSMENT.md
    │   ├── S001-PLAN.md     ← <task> blocks inline
    │   ├── S001-RESEARCH.md (optional)
    │   ├── S001-UAT.md
    │   ├── S001-SUMMARY.md  ← produced after execution
    │   └── tasks/
    │       ├── T0001/
    │       │   ├── T0001-PLAN.md    ← scaffolded from <task> block
    │       │   └── T0001-SUMMARY.md ← filled by executor after commit
    │       └── T0002/...
    └── S002/...

Only the slice-PLAN and task-PLAN files are parser-mandatory. Every other file is workflow-produced and may be absent; its absence means that workflow step has not run yet.

Plan-checker loop

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

planner → slice plans ──► plan-checker
                            │
                status: passed ──► scaffold tasks, commit, advance
                            │
                status: issues_found
                            │
                            ▼
              planner (revision mode) → slice plans → plan-checker
                            │
                            (max 2 iterations)

Every iteration appends a YAML verdict block to M<NNN>-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

/np:verify-work is the post-execution twin of plan-checker: same goal-backward methodology, different timing. np-verifier reads the milestone's ROADMAP and CONTEXT, every slice's PLAN and SUMMARY, every task's PLAN and SUMMARY, and the task commits, then classifies each success_criterion 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 milestone.
• Needs-User-Confirm — subjective judgment required (UX, "feels", "looks right"). A pass-2 askuser gate resolves it into the final Pass, Fail or Pending status the artefact records.

The verifier never proposes fixes and never edits source. It writes M<NNN>-VERIFICATION.md with the breakdown.

Undo & crash recovery

• /np:reset-slice [<task-full-id>] — discard in-flight task. Restores files_modified from HEAD, deletes the checkpoint, clears STATE.current_task. No commit.
• /np:undo-task <M-S-T> — revert one task commit via git revert --no-edit, reset task status to pending.
• /np:undo <N | M-S> — revert every task commit of a milestone or slice (newest-first).

All undos produce forward commits (Revert "task(M-S-T): …"); history is never rewritten.