BOHICA-LABS / BOHICA-LABS/vsdd-factory
bug(state-manager+product-owner): index TOTAL bumped ahead of on-disk artifacts triggers index-vs-filesystem hard-gate failure (inverse of #277)
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Class of failure
When a project enforces an **index-vs-filesystem** consistency lint (every entry registered in an index must have a corresponding file on disk), bumping the index's TOTAL/registration **before** the underlying files exist creates a self-inflicted hard-CI-gate failure that blocks an otherwise-ready PR. The index edit and the file creation are done by different agents at different times, with no ordering guard.
This is the **inverse** of #277 (derived summary fields going *stale* — content added, count not bumped). Here the count is bumped *ahead* of content. Filing separately because the trigger and the fix differ.
## Pattern observed (external pilot, ftc-blue)
During a story-split that spun up a new epic, the orchestrator/state-manager registered three new behavioral contracts in `BC-INDEX.md`, bumping its Summary-Statistics TOTAL 75 → 78. The three BC files were **not** created on disk at the same time. The project's hard CI gate `tools/lint-bc-index-vs-filesystem.sh` (which counts `BC-*.md` files vs the BC-INDEX TOTAL) then failed on the story's PR, blocking merge until a product-owner authored the three draft BC stubs in a follow-up commit. The PR was otherwise fully converged and green.
There was also a confounding lag: the PR's first CI run fetched the orphan `factory-artifacts` branch *before* the stub-authoring commit was pushed, so even after the local fix the gate stayed red until a CI re-run re-fetched the corrected branch — a second-order trap worth noting for any setup where CI reconstructs artifacts from a separate branch.
## Root cause
The agent that updates an index TOTAL does not verify that all newly-registered entries have files on disk before committing the index change. No ordering invariant ties "register in index" to "stub file exists."
## Fix applied in the pilot
Product-owner authored the three draft BC stub files, satisfying the lint. Added to state-manager / product-owner checklists: **before committing any index TOTAL increase, run the index-vs-filesystem lint locally and confirm it passes.**
## Request
Codify an ordering invariant in the relevant agent templates (state-manager / product-owner / story-writer): **never bump an index's registered-count ahead of the on-disk artifacts.** Either create the stub file(s) in the same burst as the index edit, or run the project's index-vs-filesystem lint locally as a pre-commit gate on any index TOTAL change. Relates to #277.
Contributor guide
Assessment
This issue has not been assessed yet.