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
- 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
Assessment
This issue has not been assessed yet.