---
paths: "devforgeai/specs/Stories/**/*.md"
description: Story state transition rules
version: "1.0"
created: 2025-12-10
---

# Story Lifecycle Rules

## States
```
Backlog → Architecture → Ready for Dev → In Development →
Dev Complete → QA In Progress → QA Approved → Releasing → Released
```

## Transition Rules

### Backlog → Architecture
- Story file created with complete acceptance criteria
- Technical specification section present

### Architecture → Ready for Dev
- Context files validated (6 files)
- No blocking ADRs pending

### Ready for Dev → In Development
- Developer assigned (or Claude starting)
- Dependencies available

### In Development → Dev Complete
- All tests written and passing
- Implementation complete per acceptance criteria

### Dev Complete → QA In Progress
- Quality gate 2 passed
- No Critical anti-pattern violations

### QA In Progress → QA Approved
- All acceptance criteria verified
- QA report generated

### QA Approved → Releasing
- Quality gate 3 passed
- Release plan documented

### Releasing → Released
- Deployment successful
- Smoke tests passed
- Rollback verified (if applicable)

---

## DEVARCH Seed Prerequisite for /dev (post PR #63, 2026-05-18)

The `source_devarch` frontmatter field is **mandatory** for any story entering `/dev`. The validator runs at workflow entry as part of `devforgeai-validate dev-preflight` and exits 4 with a HALT message when the field is absent, empty, a placeholder (`TBD` / `PENDING` / `...` / `?` / `N/A`), or points to a non-existent file. There is **no bypass** — the migration path below is the only forward route.

**Impact for legacy stories:** the `source_devarch` field was introduced by PR #63 (2026-05-18) on `story-template.md` v3.1. Stories created with the older `format_version: 2.9` template (or earlier) do not have it. As of PR #106 inventory (2026-05-22), **0 of 72 existing stories** in `devforgeai/specs/Stories/` carried `source_devarch`; at C11 arc close (2026-05-24) it was **0 of 663** including 97 newer `format_version: "3.1"` stories. Any `/dev STORY-XXX` against a legacy story exits 4 with the HALT message above.

**Migration path (no /dev-side compatibility shim):**

1. Run `/create-development-architecture` for the feature/epic the legacy story belongs to. This produces a DEVARCH document with a `SEED-NNN` story seed.
2. Re-create the legacy story via `/create-story` ingesting that seed. The new story file carries `source_devarch` pointing at the DEVARCH document, and the rest of the v3.1 frontmatter (`feature_ref`, etc.).
3. Replace the legacy story file with the re-seeded version (preserve the STORY-NNN id for traceability).
4. `/dev STORY-NNN` now succeeds at dev-preflight.

**Governance:** the strict-contract is owned by ADR-067 (system architecture pipeline), ADR-068 (solution architecture), ADR-069 (development architecture), and ADR-099 (the CLI enforcement). Loosening the contract to a WARNING would require an ADR amendment to all four; that work has not been scoped.

**Enforcement:** `devforgeai-validate dev-preflight` exit 4 (B2 / ADR-099) — binary, hook-style, no bypass. Replaces the prior prose-only HALT that lived in `.claude/agents/backend-architect.md` Phase 2.5 (PR #117 documented the migration path; this PR mechanizes the contract). Per `feedback_ceremony_not_enforcement` (2026-05-22), prose-only HALTs in agent files do not reliably redirect behavior — the CLI gate is the authoritative check.
