BOHICA-LABS / BOHICA-LABS/vsdd-factory
Story decomposition can produce unbuildable stories: AC-collapse, API-name drift, and hidden infrastructure dependencies pass through to Phase 3 dispatch
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Summary
During a real Phase 3 production run (project ftc-blue, Godot/GDScript), the last Wave-1 story (STORY-8.08.004, "Corrupted Save File Recovery") reached the dispatch point but was unbuildable. The defects were latent in the Phase 2 decomposition and survived to Phase 3 because no automated check guards story-vs-BC fidelity or dependency satisfiability at decomposition time.
## How it blocked work
The story could not be dispatched into the per-story TDD cycle because roughly half of its parent BC's acceptance criteria depend on UI infrastructure (a main-menu scene, a dialogue/overlay system, and a new-game flow) that **no epic in the entire project plan owns**. The story declared only `depends_on: [STORY-8.08.001]`, which hid the unsatisfiable dependency. The orchestrator had to stop, investigate, split the story along a testability seam, and surface the missing UI-infrastructure epic as a planning gap before any forward progress was possible.
## Root cause (three compounding defects)
1. **AC collapse, silent:** BC-8.08.004 has 12 ACs; the decomposed story distilled to 6, silently dropping ACs with no justification, deferral note, or coverage ledger. Half the BC's behavior (main-menu return, error dialogue, Start-New-Game) was simply absent from the story.
2. **API-name drift:** BC said `SaveManager.load(slot)`, story said `SaveManager.load_game()`, and the real code has `SaveManager.load_save(slot)` — three different names. The story also mis-traced its FR (FR11 "puzzle system" instead of FR17 "save/load integrity") and pointed at a non-existent capability file (`capabilities/save-system.md`; the real file is `capabilities/save.md`).
3. **Hidden infrastructure dependency:** The BC's UI-orchestration ACs require infrastructure (main menu, dialogue system, new-game flow) that does not exist in any wave or epic. The decomposition never surfaced this as a `depends_on` edge or a blocker, so the impossibility was invisible until dispatch.
## Why existing gates did not catch it
- There is no `policies.yaml` entry (and no plugin-level check) that validates BC↔story AC coverage, API-name correspondence against real code, capability-anchor file existence, or dependency satisfiability.
- `dependency-graph.md` only validates story→story DAG edges (topological sort). It does not verify that each BC-mandated piece of infrastructure has an owning story/epic.
## Proposed mitigations (to reduce recurrence)
1. **Decomposition-time AC coverage ledger (story-writer + consistency-validator):** every BC AC must be explicitly mapped to either (a) an AC in some story, or (b) a recorded, justified deferral. Flag any BC AC with zero coverage.
2. **API-name & anchor validation at story-write time:** grep the real source for every API symbol a story/BC names; fail/flag on mismatch. Verify the referenced capability file and FR id actually exist.
3. **Dependency-satisfiability gate before Phase 3 dispatch:** for every capability/infrastructure a story's ACs require, assert an owning story exists and is scheduled no later than the dependent. If the required infrastructure has no owning epic, mark the story `dispatch-blocked` with the gap named — never let it reach dispatch silently.
4. **BC/story AC-ratio flag:** when a story covers materially fewer ACs than its BC (e.g. <70%), require an explicit split or deferral rationale rather than silent omission.
5. Consider surfacing these as Phase-2-exit / Phase-3-entry checks in the orchestrator's mandatory-steps list.
## Real-world impact
Cost one full investigation + story-split + spec-drift-repair cycle, and exposed a missing UI-infrastructure epic (main menu / dialogue / new-game flow) that the project plan lacked entirely — a gap that would otherwise have surfaced even later, during Phase 4 holdout evaluation.
Contributor guide
Assessment
This issue has not been assessed yet.