BOHICA-LABS / BOHICA-LABS/vsdd-factory

process-gap(architect): spec-diff re-read mandate has no architect-dispatch parity — orchestrator briefing errors and impl-side drift survive spec edits

Open
#427 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2
Forks
1
Avg merge
6h 43m
Merged PRs (30d)
29

Description

## Summary

The spec-diff re-read mandate (locally called L-W3-XX; framework-side related to #322 remediation-diff self-check and #419 reverse-drift) requires **implementer** dispatches to re-read the spec surface between Pass N-1 HEAD and Pass N HEAD before writing code. This closes the `spec → impl` direction of drift.

The mandate currently has **no architect-dispatch parity**. When the architect updates a spec (api-surface, subsystem-doc, ADR), they are not required to re-read impl HEAD to verify the spec still matches impl reality before finalizing edits. Two failure surfaces this creates:

1. **Orchestrator briefing errors ship as spec truth.** The orchestrator briefs the architect with values that don't match impl. If the architect trusts the briefing, the spec gets an incorrect value.
2. **Aspirational spec text goes unchallenged.** Prior spec assertions about impl behavior (`always queries X directly / NOT a local dict lookup`) that never matched impl reality survive spec bumps because the architect doesn't re-read impl to check.

## Concrete evidence (ftc-blue Wave 3 Batch 1, 2026-07-02)

STORY-10.10.003 Fix Phase 5 Burst 5A — architect updating `api-surface.md v1.22 → v1.23`. The architect's dispatch prompt included an experimental parity mandate: *before finalizing spec deltas, re-read impl HEAD for every symbol being modified.* The architect self-caught **two independent drifts** in a single burst:

### Drift 1 — Orchestrator briefing had wrong sentinel value
- Orchestrator briefing (this session): document `INVALID_STEP_SENTINEL: String = \"__invalid_step__\"`.
- Impl reality at `puzzle_system.gd:63`: `INVALID_STEP_SENTINEL: String = \"wrong\"`.
- Architect re-read impl HEAD, caught the mismatch, and documented **impl truth** in v1.23. Without the parity mandate the architect would have written the orchestrator's incorrect value into api-surface as canonical.

### Drift 2 — Prior spec text was aspirational
- Prior api-surface: `is_zone_unlocked always queries SaveManager directly / NOT a local dict lookup`.
- Impl reality: `_zone_unlock_state.get(zone_id, false)` — in-memory dict lookup, never SaveManager. Aspirational since introduction.
- Architect re-read impl HEAD, reconciled spec with impl truth, and TODO-tagged SaveManager hydration to E-005/BC-10.10.002 scope.

Both drifts caught by a single re-read step; both would have shipped in v1.23 without it.

## Why existing gates miss this

- **#322** (remediation-diff self-check) is scoped to *diff regressions* — new bindings the fix introduces. It doesn't cover \"architect writes new spec text asserting an impl fact that has never been true.\"
- **#419** (reverse phantom-API drift) covers `impl grows public surface not in spec`. This issue covers the mirror: `architect writes spec claim that doesn't match already-existing impl`.
- **#272** (architect hallucinated packages from story stubs) is same overreach *class* but the fix (`ls internal/ before writing §6 tables`) is scoped to structural existence checks. This issue extends the discipline to **values, signatures, return types, constants** at every architect edit.
- **#274** (ADR + code diverge across revisions) documents the pattern from the *implementer* side. This issue is the architect-side dual.
- **L-W3-XX / spec-diff re-read** (implementer mandate): closes `spec → impl`. This issue: close `impl → spec` at architect dispatch.

## Proposed remediation

Amend the `architect` agent's system prompt (and the orchestrator dispatch template for architect):

> **Before finalizing any spec delta** (api-surface, subsystem-doc, ADR), for every function signature, constant, return type, signal, or public API you are modifying: **re-read the actual impl file at the current feature-branch HEAD**. Report any discrepancy between (a) the value the orchestrator briefed you with, (b) the value the prior spec asserted, and (c) the value in impl HEAD. That discrepancy is one of:
>
> 1. **Drift the spec is now reconciling correctly** — document impl truth, note prior spec value in changelog.
> 2. **Orchestrator briefing error** — do NOT write the briefed value; write impl truth and flag the briefing error for orchestrator awareness.
> 3. **Additional drift beyond current scope** — add to the spec delta list for the current pass or open a follow-up finding.
>
> Never write a spec assertion about impl behavior that you have not verified against impl HEAD in the current session.

## Impact

This is subtle. The architect is the framework's canonical spec authority; if the architect never re-reads impl, aspirational prose and briefing errors laundered by the architect become **the** spec truth downstream code and tests must match. Every subsequent adversary pass reading the spec-as-truth would ratify the drift. The empirical test in this session: **one dispatch with the parity mandate, two independent drifts caught** — one from orchestrator briefing, one from years-stale aspirational prose. Both would have shipped as v1.23 canonical.

Cross-language: nothing Godot-specific. Applies to any project where `architect` writes spec text asserting facts about impl.

## Severity

**MEDIUM-HIGH**. Same tier as #419 — spec-truth erosion at the architect layer compounds because subsequent implementer/test-writer dispatches trust spec-as-canonical. A stale value in api-surface produces failing tests + confused implementers for multiple stories.

## Provenance

`ftc-blue` Wave 3 Batch 1, STORY-10.10.003 Fix Phase 5 Burst 5A (api-surface.md v1.22 → v1.23). Not private-project content per #261 — pattern is framework-level. Related: #272, #274, #322, #399, #419, #287.

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.