BOHICA-LABS / BOHICA-LABS/vsdd-factory

feat(lint): verbatim-quote provenance checker — 'states verbatim' cross-BC citations are unverifiable and get fabricated

Open
#392 0 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

BCs and ADRs routinely cite other specs using patterns like *"CAP-008 states verbatim: '...'"* or *"per BC-4.04.001: '...'"* with a quoted span. There is no lint that verifies the quoted span actually appears in the cited source. Result: fabricated quotes survive every convergence gate and are only found by fresh-context cross-doc audits.

## Repro (real cycle)

Wave 2 cycle on ftc-blue project. Cross-BC sweep found "states verbatim" citations in multiple S-04 (commentary pipeline) BCs quoting CAP-008 (audio system) capability language that did not appear anywhere in CAP-008.md. The citations were plausible-sounding paraphrases the product-owner wrote in-line and never round-tripped against the source. Tracked internally as Task #32 (Phase-5 sweep) and Task #33 (proposed lint).

Similar family:
- **Fabricated quote:** cited span doesn't exist in source at all.
- **Drifted quote:** cited span existed at authorship time but source was reworded later; citation is stale.
- **Reordered quote:** words match but order/emphasis differs (subtle semantic change).

## Proposed lint

`tools/lint-verbatim-quote-provenance.sh` — or a plugin skill `/vsdd-factory:check-verbatim-quotes`:

1. Scan .factory/specs/ for citation patterns:
- `states verbatim: "..."`
- `states verbatim, "..."`
- `per : "..."`
- ` states: "..."`
- Configurable regex list.
2. For each hit, extract the quoted span and the cited spec ID.
3. Resolve the cited spec's file path (via BC-INDEX / ARCH-INDEX).
4. \`grep -F -- "" \`. If exit non-zero → fabrication/drift.
5. Report: file:line → cited-spec → span → FOUND / MISSING.
6. Exit non-zero if any MISSING.

## CI wiring

Add to spec-lint job matrix. Cheap (grep -F on ~200 files). Deterministic.

## Framework template

Ship in the vsdd-factory plugin so every project inherits the checker on scaffold. #308 flags CI-job proliferation as a concern — this one earns its slot because fabrication is not caught by any existing lint (#327 covers *anchor* fidelity; this covers *quote* fidelity).

## Cross-reference

Related to #151 (drift-resistant source-citation convention). This is one concrete implementation of that.

## Provenance

Wave 2 cycle-001 lessons codification, L-W2-03 (ftc-blue Godot project). Task #32/#33.

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.