BOHICA-LABS / BOHICA-LABS/vsdd-factory

bug(pr-validation): BC Traceability Check regex 'STORY-[0-9]+' excludes alphanumeric story IDs (STORY-DEF-NNN class)

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

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.