BOHICA-LABS / BOHICA-LABS/vsdd-factory

feat(spec-ci): adopt drift-resistant source-citation convention + checker

Open
#151 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Rust
Stars
2
Forks
1
Avg merge
6h 43m
Merged PRs (30d)
29

Description

## Summary

VSDD spec artifacts (behavioral contracts, architecture docs, verification properties) anchor claims to source using raw `file.rs:NNN[-MMM]` line citations. Those line numbers are hand-maintained and silently drift whenever source changes (an added import or doc-comment shifts every line below it). There is no checker, and no convention that resists drift.

This was the **single most recurrent defect class** in the `wirerust` Phase-1 adversarial spec-convergence gate — stale/mis-anchored citations produced findings across **13 adversarial passes** (4, 6, 8, 9, 10, 12, 13, 14, 17, 18, 20, 21, 30), reset the "3 consecutive clean passes" streak at least three times, and required three manual remediation sweeps (~58, ~68, ~48 defects). In `wirerust` alone there are **1126 `file.rs:NNN` citations across 249 spec files**, every one hand-maintained.

Tracked in `wirerust` as deferred finding `P-CITE-PG` (6+ recurrences → mandatory codification per the Cycle-Closing Checklist). It is a **process/tooling gap in the VSDD engine**, not a `wirerust` content defect, so it belongs here.

## Validation

Filed after `vsdd-factory:research-agent` validation per `wirerust` policy `DF-VALIDATION-001`. Verdict: **VALIDATED-WITH-CHANGES** — the problem is real and open, but the original proposal ("build a line-citation checker as a Rust binary") treats a symptom and is reframed below.

## Why a blank/comment/EOF checker alone is not enough

A checker that only flags citations pointing at blank lines, comment-only lines, or past EOF has a large blind spot: when an inserted line shifts a block by N, the citation usually still lands on a *real code line* — just the **wrong** one. The checker reports OK while the citation is semantically stale. That wrong-but-plausible-line case is the **dominant** drift mode here, so a blank/comment/EOF checker gives false confidence.

The root cause is the **citation convention** (raw line numbers on a moving branch), not the absence of a checker. Every mature docs-to-code system avoids raw line numbers:

| System | Drift-resistant mechanism |
|--------|---------------------------|
| mdBook `{{#include}}` | named `ANCHOR` regions — docs explicitly say use anchors *instead of* line numbers |
| Sphinx `literalinclude` | `:start-after:` / `:end-before:` string markers |
| GitHub permalinks | line anchors pinned to an immutable **commit SHA** |
| Fiberplane Drift | path + symbol name + AST-hash signature — **no line numbers** |

## Proposed scope

**Title:** `feat(spec-ci): adopt drift-resistant source-citation convention + checker`

1. **Decide the convention** (load-bearing change) — symbol anchors and/or commit-SHA-pinned line numbers for all `file.rs:NNN` citations in VSDD spec artifacts. VSDD BCs already name the symbol in prose (e.g. `TcpReassembler::new`), so symbol anchoring is largely a formatting change.
2. **Adopt vs. build** — evaluate **Fiberplane Drift** (`github.com/fiberplane/drift`, MIT, v0.10.0) as the checker. It is a purpose-built doc-rot linter: path + symbol + AST-hash anchors, supports Rust/TS/Python/Go/Java via tree-sitter, `drift.lock`, `drift check` exits non-zero on staleness, ships a setup GitHub Action and prebuilt binaries. It implements exactly the convention change in step 1.
3. **CI gate** — wire `drift check` (or the fallback script) into spec-CI, analogous to `cargo fmt --check`: exit non-zero on stale citations.
4. **Fallback only** — if an external binary is unacceptable for the plugin, build a *minimal dependency-free script* (consistent with existing `bin/` helpers — they are all dependency-free shell, **no compiled-binary precedent**; do **not** ship a Rust binary). Scope the fallback to EOF + blank-line + commit-SHA-pinning enforcement, and explicitly document that it does not catch wrong-but-plausible-line drift.

## Notes / open items

- **Inconclusive:** what fraction of the 13 historical recurrences a blank/comment/EOF checker would have actually caught was not quantified. STATE.md descriptions ("off-by-one citations", "line shifts") suggest a *majority* would slip through. Spot-check 5–10 real past findings before fixing fallback scope.
- The "generic" mechanical part is only partly language-agnostic: EOF + blank-line detection is neutral; comment-only detection needs per-language comment syntax; symbol-proximity effectively needs a parser.
- Non-blocking for any active pipeline gate; this issue itself satisfies the mandatory-codification requirement for the `P-CITE-PG` recurrence.

## Sources

- Fiberplane Drift — https://github.com/fiberplane/drift · https://fiberplane.com/blog/drift-documentation-linter/
- mdBook `{{#include}}` anchors — https://rust-lang.github.io/mdBook/format/mdbook.html
- Sphinx `literalinclude` markers — https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
- Full validation report (in wirerust): `.factory/research/citation-checker-validation.md`

_Filed by the VSDD orchestrator from `wirerust` deferred finding `P-CITE-PG`, validated under `DF-VALIDATION-001`._

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.