Process Guard FSM: allow roadmap → completed for single-session implementations

[darko-mijic]

Problem

When a spec is implemented in a single session (common for 1-3 day efforts), the session completes all work and transitions the spec roadmap → completed. The Process Guard rejects this because the FSM requires roadmap → active → completed — two separate commits.

Current workaround (painful)

Sessions must fake a two-commit split at the end:

1. Revert deliverable statuses to planned, set status to active, commit
2. Re-apply Done deliverables, set status to completed, commit

This wastes ~40% of remaining context window on mechanical revert/re-apply work and produces misleading git history: commit 1 claims "active" with "planned" deliverables but includes all the finished code.

Evidence

Every completed spec in this repo followed this pattern:

• 99fadc1 Transition DataAPIStubIntegration spec to active → 181dd80 Complete
• 6d52cc3 Transition DataAPIOutputShaping spec to active → 8bc0c13 Complete
• 41f93b7 Transition DataAPIContextAssembly spec to active → e853722 Complete

The "transition to active" commits are ceremony — the code is already done.

Analysis

Why the FSM blocks roadmap → completed

The active state serves as a scope-locking checkpoint — it freezes the deliverables table so no new work can be added during implementation. The FSM enforces this gate at 4 layers:

1. src/validation/fsm/transitions.ts:64 — transition matrix: roadmap: ['active', 'deferred', 'roadmap']
2. Same file, lines 135-137 — dedicated error message: "Must go through 'active' first"
3. delivery-process/specs/process-guard-linter.feature:179 — spec lists it as invalid
4. tests/features/validation/process-guard.feature:106 — test asserts rejection

Why the scope-lock argument is weak for single-session work

When going roadmap → completed in one sitting, the scope-lock window is zero seconds — there's no moment where someone could add deliverables to a scope-locked spec. The protection is theoretical. DoD validation already independently gates completed status (all deliverables must be Done).

Proposed solution

Add completed as a valid transition target from roadmap in the FSM matrix. This is the "single-session fast-track" — when all work is done in one session, skip the ceremony of a fake intermediate active commit.

Files to change

File	Change
src/validation/fsm/transitions.ts	Add 'completed' to roadmap targets, remove dedicated error message, update JSDoc diagram
delivery-process/specs/process-guard-linter.feature	Move roadmap | completed from invalid to valid examples
tests/features/validation/process-guard.feature	Move roadmap | completed from invalid to valid examples
tests/features/validation/fsm-validator.feature	Move roadmap | completed from invalid to valid examples
CLAUDE.md	Update FSM diagram and error message table

Open questions for planning

• Should roadmap → completed require all deliverables to be Done (conditional transition), or be unconditional like other transitions?
• Should the JSDoc/CLAUDE.md FSM diagrams show this as a "fast-track" or just a normal transition?
• Are there other missing transitions worth considering while we're updating the FSM? (e.g., deferred → active shortcut)

Related

• Fixed in 3d0d429: completed-protection false positive on active → completed (the second half of this problem — now resolved)