BOHICA-LABS / BOHICA-LABS/vsdd-factory

policy(spec-steward): full citation-corpus sweep on BC/ADR bump — changelog-row-only check misses 3–5 stale pins per bump

Open
#396 5 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

Spec-steward's citation-lint pass, when triggered by a BC or ADR version bump, currently focuses on the changelog row and immediate reciprocal citations. It does not sweep the **full corpus** for version-pinned citations to the just-bumped spec. Result: 3–5 stale pins across sibling ADRs, api-surface docs, and older ADRs survive the initial sweep and only surface when CI's staleness lint runs — often on a blocked hygiene PR.

## Repro (real cycle)

**Wave 2 gate close, ftc-blue.** On BC-6.06.003 v1.7 → v2.0 bump (2-major cascade), spec-steward ran citation-lint sweep. Missed:
- `ADR-0011-menu-system-assist-panel.md` line 1044 — cited api-surface v1.17, canonical is v1.18 (api-surface itself was bumped as reciprocal in the same session).
- `ADR-0013-aoq-001-confrontation-signal-contract.md` line 64 — cited BC-6.06.003 v1.4, canonical v2.0.
- Plus 3 previously-caught cites in ARCH-INDEX / ADR-0013 body / api-surface.

**Time cost:** blocked PR #62 (WG-DEF hygiene sweep) through 3 CI iterations. Two follow-up spec-steward commits (623144d, e7a78a7) required.

## Root cause

Spec-steward's post-bump procedure enumerates *known* citation sites (changelog rows, reciprocal ADR back-refs) but doesn't grep the *entire* .factory/ tree for ` v` patterns. Any citation in an unrelated ADR body or api-surface doc that pins the just-bumped spec is missed.

## Proposed rule

Amend spec-steward agent prompt:

> **Full-corpus citation sweep after any BC/ADR version bump.**
>
> After bumping BC-X.YY.ZZZ or ADR-NNN from v to v:
> 1. `grep -rn "BC-X.YY.ZZZ v" .factory/specs/ .factory/stories/` (any explicit version pin to this BC).
> 2. For each hit, check whether the cited version matches v. If not:
> - Same version < B: stale. Update in place or reword to remove version pin.
> - Version > B: newer than canonical → check timing, likely error.
> - Version = B: OK.
> 3. Include this sweep's output in the PR / commit message so it's auditable.
> 4. Do NOT rely on the citation-staleness CI lint to catch this — that lint is a **guardrail**, not the primary sweep. If CI catches a stale pin, the spec-steward pass was incomplete.

## Detection heuristic

Post-commit hook: on a factory-artifacts commit touching a BC/ADR frontmatter version field, run the full grep + version-match sweep and fail commit if any stale pin remains untouched.

## Cross-reference

Complementary to #287 (9-site propagation checklist for BC-only, forward-facing) and #390 (target-first cascade ordering). This one is about the *breadth* of the post-bump sweep, orthogonal to *ordering* and *forward-propagation*.

## Provenance

Wave 2 cycle-001 lessons codification, L-W2-07 (ftc-blue).

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.