BOHICA-LABS / BOHICA-LABS/vsdd-factory
process-gap(consistency-validator): consistency and rename-residual checks scoped to a file-type allowlist silently skip prose/rationale/ADR docs
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Summary
The engine's consistency-validation and corpus-grep checks operate against an implicit file-type allowlist — typically story files, VP harness files, contract files, and index files. File types outside that allowlist — architecture-rationale prose, assessment narratives, ADR bodies, and VP prose blocks adjacent to harness skeletons — are never covered. The check returns "zero live references" for a retired/renamed identifier while live references survive in excluded file types.
In one external pilot run, a retired canonical identifier was confirmed as having "zero live references" by a grep scoped to harness/story/index files. Live references then surfaced in architecture-rationale prose and VP prose blocks 1–2 at a time over multiple later passes, each resetting the convergence streak. A single full-corpus grep would have caught every remaining instance in one shot.
---
## Concrete evidence from a pilot run
The rename-residual class was surfaced six separate times across consecutive passes. Several intermediate passes ran a grep that DID cover harness/story files and returned "0 found" — a false-clean signal — while architecture-rationale prose and VP prose blocks were outside the scope. Only a closing grep that covered ALL file types fully drained the class.
The pattern is clear: a grep was present but not exhaustive. A scope that covers harness/story files but not architecture/rationale prose is equivalent to no grep for the excluded file types — it produces a false-clean signal that allows residuals to survive into later passes.
This is structurally related to #131 (broaden consistency coverage to prose/diagrams) and adjacent to #327 (citation-resolution depth). This finding is specifically about the **file-type SCOPE axis** of consistency/grep checks:
- **#131** identifies that prose and diagrams should be in scope. This issue provides concrete quantitative evidence of the cost when they are not, and names the mechanism of exclusion precisely: the file-type allowlist.
- **#327** addresses the depth of citation resolution within a check. This issue addresses the breadth (which file types are included) rather than the depth.
---
## Recommended fix
Any corpus-wide consistency check or rename-residual grep MUST run over ALL file types as its closing step, not a subset.
**For rename/retirement sweeps**, the mandatory closing grep must include the entire spec corpus (stories, contracts, VPs incl. their prose blocks, ADRs, module-decomposition, purity/boundary maps, domain spec, entity definitions) and the entire cycle/state corpus (state docs, phase notes, architecture rationale, assessment narratives).
**For consistency-validation passes**, the file-type scope for any "confirm zero live references" assertion must explicitly enumerate architecture-rationale documents, assessment narratives, and ADR bodies as in-scope, not rely on the default file-type filter.
The minimum correct scope for a rename-propagation closing check is: every file in the factory corpus that could contain prose referencing a canonical identifier — which is all files, not a structural-file subset.
Contributor guide
Assessment
This issue has not been assessed yet.