BOHICA-LABS / BOHICA-LABS/vsdd-factory

product-owner: BC amendments touching shipped field semantics need a shipped-code ground-truth gate

Open
#537 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

## Observed

A behavioral-contract amendment (minor version bump) tightened a postcondition's prose for an upcoming story and specified a field encoding ("SSH wire-format encoded then hex-encoded") that CONTRADICTED the shipped semantics of the same field as delivered by the previous story (raw key bytes, hex-encoded) — semantics also documented in an existing operator recipe. The drift was caught during the next story's TDD implementation ONLY because the orchestrator had manually added a "if shipped semantics differ from BC prose, STOP and report" guard to the implementer dispatch. A same-day corrective BC version was required.

## Engine gap

The product-owner agent prompt requires no ground-truth check against shipped code when amending clauses that describe already-shipped artifacts (file formats, field encodings, on-disk schemas). The agent drafted a plausible-sounding encoding from the contract's own vocabulary rather than verifying the shipped semantics. This is the amendment-time sibling of #440 (spec-convergence needs shipped-code grep gate): #440 covers convergence passes; this covers spec amendments.

## Suggested fix

Product-owner prompt: when an amendment touches a clause describing behavior/data that has already shipped, the agent MUST cite the shipped source (file:line or existing authoritative doc) for the current semantics before changing the prose, and flag any intended semantic change explicitly as a breaking spec change rather than a "tightening."

Secondary: the "STOP and report on spec-vs-shipped discrepancy" guard the orchestrator improvised for the implementer dispatch is worth standardizing in the implementer prompt — it is what caught this.

## Evidence

Session 2026-07-06, private consumer project: BC minor-version amendment introduced field-encoding drift vs the prior story's shipped semantics; caught at TDD time by the guard; corrected in a same-day BC patch version.

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.