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

Open
#339 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

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

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.