BOHICA-LABS / BOHICA-LABS/vsdd-factory
bug(pr-validation): BC Traceability Check regex 'STORY-[0-9]+' excludes alphanumeric story IDs (STORY-DEF-NNN class)
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Summary
The BC Traceability Check in the generated `pr-validation.yml` uses `grep -qE 'BC-[0-9]+\.[0-9]+\.[0-9]+|STORY-[0-9]+'` to enforce that `fix`/`feature`-labelled PRs include a traceability reference. The `STORY-[0-9]+` alternative requires a **fully numeric** story ID; alphanumeric IDs like `STORY-DEF-002`, `STORY-DEF-003`, `STORY-VISUAL-HARNESS-001`, `STORY-DEMO-001` do **not** match the pattern. Defect-fix and process/infra stories routinely use these formats, so PRs shipping such stories fail the BC Traceability Check even when their story IDs are correctly cited in the PR body.
## Recurrence data (private pilot; framework-pattern detail only)
Two consecutive defect-fix PRs on the same pilot project hit this exact block:
- **PR #A (STORY-DEF-002):** BC Traceability Check red on PR create. Story is a `test`/`fix` labelled defect-fix with `traces_to_bc: []` **by design** (demo-infra defect-fix, no gameplay BC). Alphanumeric story ID `STORY-DEF-002` in title + PR body; regex missed it. Also no BC ID available to cite as a fallback. Workaround: added `test` label alongside `fix` (the escape hatch) since the PR delivered a test file as a primary artifact.
- **PR #B (STORY-DEF-003):** BC Traceability Check **forecast red before PR creation** by an adversarial delivery-readiness pass (see #462 for the lens-rotation datum). Story had `traces_to_bc: [BC-...]` available, so mitigation was pre-emptive: cite the BC ID explicitly in the PR body during creation. Story ID alphanumeric again (`STORY-DEF-003`); regex still missed it, but the BC-ID citation satisfied the alternative branch of the check.
Pattern is systemic across the "defect-fix" and "process/infra" story classes on this pilot; expect any project with a similar story-ID taxonomy to hit it.
## Suggested fix
Broaden the `STORY-` alternative to accept alphanumeric segments:
```
grep -qE 'BC-[0-9]+\.[0-9]+\.[0-9]+|STORY-[A-Z0-9]+(-[A-Z0-9]+)*'
```
This matches:
- `STORY-1.01.005` (existing numeric-segmented form) — via the `[A-Z0-9]+(-[A-Z0-9]+)*` grouping when segments are dot-separated it still needs to accept dots; a safer form is `STORY-[A-Z0-9][A-Z0-9.-]*` allowing dots, digits, and hyphens after the initial character.
- `STORY-DEF-002`, `STORY-VISUAL-HARNESS-001`, `STORY-DEMO-001` — alphanumeric multi-segment
- `STORY-1.01.005` — numeric dotted
Alternative: derive the allowed pattern from the canonical story-id shape used by the story frontmatter (`story_id:` field) — a token beginning with `STORY-` followed by one or more alphanumeric-or-hyphen segments, optionally with numeric dot-separated segments. Either way, the current `[0-9]+`-only alternative is provably too narrow.
## Workaround in use
Adding a `test` label alongside `fix` (the exempt-label escape hatch) is defensible only when the PR **does** deliver a test file as a primary artifact — as in PR #A above. It does **not** generalize to fix PRs that deliver no test artifact; those PRs will simply be unable to satisfy the gate under any label combination if their story ID is alphanumeric and no BC is in scope.
The other workaround — always citing a BC ID in the PR body — depends on the story having a BC to cite; defect-fix and pure-process stories may legitimately have `traces_to_bc: []`, at which point there is no BC to cite and no valid path through the gate.
## Cross-refs
- Related to #327 (AC-anchor integrity — different regex, same class of "traceability check has a pattern that doesn't match the actual ID space").
- Not blocked by #348 (branch protection unreliability — different subsystem).
- Adversarial forecast pattern reinforces #462 (delivery-readiness lens catches this class before PR creation).
## Severity
MEDIUM — actively blocks legitimate PRs on any project using alphanumeric story IDs; workarounds exist but are unreliable and depend on story shape.
Contributor guide
Assessment
This issue has not been assessed yet.