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

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

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

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.