BOHICA-LABS / BOHICA-LABS/vsdd-factory
lesson(L-W3-ZZ): bidirectional spec-code drift — architect-side spec additions drift from impl in the same burst as reconciled symbols
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Defect class
The L-W3-ZZ lesson (Wave 3 Batch 1, ftc-blue) originally codified: **impl-wins for spec-impl drift**. When the api-surface says function X takes 2 args but the impl takes 1, the spec should follow the impl (or the impl should be brought in line, with an explicit choice made by the human).
## Observed extension (why re-filing)
During Wave 3 Batch 1 Pass 4 (\`STORY-10.10.003\`), a **new** drift class was surfaced:
- Fix Phase 3 (architect+PO) added new symbols to api-surface: \`transition_to_zone(spawn_hint=Vector2.ZERO)\`, \`consume_pending_spawn() -> Variant (nullable)\`.
- The **same burst** reconciled other drifting symbols (\`cancel_background_preload\` arity).
- But the newly-added symbols themselves **immediately drifted from impl**: architect declared \`transition_to_zone\` as 2-param, impl was 1-param. \`consume_pending_spawn -> Variant (nullable)\` but impl -> Vector2 non-nullable.
## Why this matters
The L-W3-ZZ mandate as originally codified only applied to implementer dispatches: \"after impl edit, re-read api-surface and reconcile.\" It did NOT apply to architect dispatches. So Fix Phase 3 could:
- Correctly fix drift on existing symbols (impl-wins ✓)
- Simultaneously introduce fresh drift on newly-added symbols by declaring what \"should\" be there without asking impl (✗)
This was caught in Pass 4 as \"F-P4-H-01/H-02: L-W3-ZZ regression introduced by Burst 4A itself\".
## What's needed
1. Update the L-W3-ZZ mandate in \`rules/lessons-codification.md\` (or equivalent) to explicitly apply to **architect** dispatches, not only implementer dispatches. Symmetric obligation: whenever the architect adds a new symbol to api-surface, they MUST also update the impl to match (or explicitly note in the artifact \"impl not yet in place — story X will land it\").
2. Add adversary check: any api-surface symbol whose signature doesn't match an existing impl symbol (or whose impl doesn't exist at all) must be flagged HIGH unless there's an explicit \"impl-pending-story-X\" annotation.
3. Consider a factory-wide **symmetric consistency invariant**: for every symbol in api-surface, there must be a matching impl OR an owning story ID. And for every public impl symbol, there must be a matching api-surface entry OR an owning story ID that will add it. Enforced via consistency-validator.
## Related
- #419 process-gap(implementer+architect): impl adds public API not documented in api-surface — reverse direction of the same class
- #399 phantom-API-drift (referenced by #419)
- #287 check-bc-version-propagation — enforces citation propagation; this is enforcing api-surface propagation
## Priority
MEDIUM-HIGH — Any architect dispatch during a Fix Phase can introduce this; caught only by fresh-context Pass N+1.
Contributor guide
Assessment
This issue has not been assessed yet.