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

Open
#437 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.