BOHICA-LABS / BOHICA-LABS/vsdd-factory

process-gap(product-owner+spec-steward): fix-and-bump-in-same-commit re-creates stale self-refs — need target-first atomic version cascade

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

## Summary

When product-owner or spec-steward remediates a spec finding and bumps the BC/ADR version in the same commit, the natural order — fix content → decide bump → write changelog → update self-refs — leaves just-written self-references stale as of the next pass. Adversary then flags them as fresh drift on the next pass, resetting BC-5.39.001's 3-clean counter.

This is the ordering-level complement of #287 (which enumerates the 9 propagation sites): even with the checklist in hand, in-body self-refs to the *current* version get written at fix time and then invalidated at bump time. Fixing this at the workflow level is cheaper than adding another CI check.

## Repro (real cycle)

STORY-6.06.003 on ftc-blue project. Passes 3 → 8 (BC-5.39.001 orthodox convergence):

| Pass | BC version | Fix content | Bump | Result |
|------|-----------|-------------|------|--------|
| 3 | v1.7 | Fix mis-anchor + Description prose | v1.7→v1.8 | Description body still cites "this BC v1.7 specifies…" → **NEXT-pass finding** |
| 4 | v1.8 | Update stale self-ref to v1.7→v1.8 + other fixes | v1.8→v1.9 | Description now cites "v1.8" but bump made canonical v1.9 → **NEXT-pass finding** |
| 5 | v1.9 | Same class recurrence + architecture anchor drift | v1.9→v2.0 | Same regression + wave-2-gate-audit found 2 more stale citations elsewhere |

Same class recurred 3 consecutive passes. Only broke when we invented a discipline: **decide target version FIRST, update all self-refs to target, write changelog LAST.**

## Root cause

The natural mental order for product-owner is:
1. Read the finding.
2. Edit the content to fix it (write "this BC v1.7 specifies…").
3. Realize a bump is needed.
4. Add changelog row for v1.7 → v1.8.
5. Commit.

Step 2 writes stale content that step 3–4 invalidates. Step 5 makes the whole commit atomic but the in-body citations are already stale.

## Proposed rule

Amend product-owner + spec-steward agent prompts with a **target-first cascade** discipline:

1. **Read the finding.**
2. **Decide the target version BEFORE editing any content.** (e.g., "current is v1.7 → target v1.8")
3. **Update every self-reference to the target version** in the same edit pass. Search patterns: `this BC v`, `this BC (v)`, `per v`, `see v`.
4. **Write fix content**, citing target version.
5. **Write changelog row LAST**, containing the completed fix summary.
6. **Commit atomically.**

This is a workflow discipline for both agents — it's not a new tool. #287's propagation checklist is a *complementary* post-commit verification; this rule is *pre-commit* ordering that prevents the drift in the first place.

## Detection heuristic (optional lint)

Post-commit: `git diff HEAD~1 HEAD -- | grep -E 'this BC v[0-9]|per BC-[0-9.]+ v[0-9]'` — if any hit's cited version does not equal the current frontmatter version, flag.

## Cross-reference

Complement to #287 (9-site propagation checklist). #287 verifies *after*; this rule structures the *authoring order*. Both together = zero-regression version bump.

## Provenance

Wave 2 cycle-001 lessons codification, `.factory/cycles/cycle-001/lessons.md` L-W2-01 (ftc-blue Godot project).

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.