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)

Open
#310 1 comment 0 reactions 0 assignees View on GitHub
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

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.