BOHICA-LABS / BOHICA-LABS/vsdd-factory
process-gap(spec-authoring): new subsystem ID declared in architecture index but dependency-graph row omitted — consistency-validator checklists not generated from CI lint inventory
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Summary
A spec-authoring burst declared a new subsystem ID in the architecture index artifact but did not add the paired row in the dependency-graph artifact. The burst-end consistency audit checked several paired artifacts but had no checklist entry covering the specific invariant \"new SS-ID ⇒ dependency-graph row.\" A CI lint (cross-artifact coverage check) caught the gap — but only at the NEXT PR's CI run, blocking an unrelated story's merge.
## Observed pattern (private Godot 4.7 project; identifiers scrubbed)
1. Spec-authoring burst: new subsystem ID registered in architecture index artifact.
2. Burst-end consistency validator runs its standard checklist — checks several paired artifacts, all pass.
3. New subsystem ID does NOT appear in the dependency-graph artifact — no checklist item triggered this check.
4. CI lint (`ss-dependency-coverage`) runs at PR time for an unrelated story and fails: subsystem ID exists in index, no corresponding dependency-graph row.
5. That unrelated PR is blocked. Remediation: add the missing row + refresh citations. Total delay: ~30 minutes.
## Root cause
The consistency-validator's checklist is not generated from the CI lint inventory. The CI lint knows exactly which cross-artifact invariants it enforces (\"every subsystem ID in the index must have a dependency-graph row\"). The consistency-validator checklist does not systematically mirror those invariants — it was authored by hand and covers only the invariants its author thought to include. A new CI lint added later creates a silent gap: CI will catch violations at PR time, but the pre-commit consistency-validator will not.
## Why this matters
- A gap between CI lint coverage and pre-commit consistency-validator coverage means violations reach PR stage and block unrelated merges.
- The worst case is a long-lived spec branch where a burst introduces an incomplete artifact, CI lint is bypassed (e.g., no PR until the end of the sprint), and the gap grows.
- The consistency-validator is supposed to be the fast local signal. If it cannot see the same invariants CI enforces, it degrades to a partial check with false-confidence semantics.
## Proposed remedy
**Generate consistency-validator checklists from the CI lint inventory** (or maintain a single source of truth that both consume):
1. Every CI cross-artifact lint should have a matching pre-commit consistency-validator checklist item — authoring bursts that violate the invariant fail fast locally instead of blocking unrelated merges later.
2. When a new CI lint is added, the consistency-validator checklist is updated in the same PR (enforced by a CI check that validates the inventory is complete).
3. Alternatively: run the CI lint locally as part of the pre-commit hook / burst-end validator, eliminating the need for a separate checklist entirely.
## Metric
1 unrelated PR blocked ~30 minutes; remediation was a single row addition + citation refresh. Low blast radius, but the failure mode scales with pipeline throughput.
## Related
- #356 (architecture-graph edge vs integration-story constraint contradiction) — both are cross-artifact consistency gaps that survive all spec gates; that issue is about contradictions between two spec artifacts, this issue is about omissions from a paired artifact
- #299 (partial-fix / N-surface propagation) — different root cause (propagation of a fix vs omission at authoring time) but both reach CI stage before being caught
Contributor guide
Assessment
This issue has not been assessed yet.