BOHICA-LABS / BOHICA-LABS/vsdd-factory
process-gap(state-manager+orchestrator): the story index accumulates each story revision as full changelog prose inside a single table-row cell — one row reached ~25KB / 16 inlined per-version sub-narratives, duplicating the story own changelog into the index
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Summary
The per-project story index (the STORY-INDEX table that lists every story with a status/notes cell) has no bound on per-row growth. Each time a story is revised, its index-row status cell gains another inlined per-version sub-narrative — effectively **duplicating the story's own changelog into the index**. One row was measured at **~25,000 characters in a single table cell**, carrying **16 inlined per-version sub-narratives** (one per revision of that story). The index file as a whole was ~315 KB across ~445 lines — i.e. rows, not row-count, are the size driver.
## Why it matters
- **The index is an always-scanned artifact.** Agents grep/read STORY-INDEX to find a row, check a version token, or verify a bc_traces pin. A 25 KB single-cell row makes that scan expensive (token cost) and makes the row's actually-load-bearing fields (current version token, status, bc_traces versions) hard to locate inside paragraphs of historical prose.
- **It duplicates the story's own changelog.** The story file already carries the authoritative per-version changelog. Re-narrating each revision in the index cell is redundant storage that drifts from the story changelog and doubles the maintenance surface (every revision now updates two changelogs).
- **Unbounded growth.** There is no compaction path. A long-lived story that goes through many revisions (this one is at v2.16 with 16 inlined narratives) grows its index row without limit. Multiply across an index of dozens of stories and the always-loaded index becomes a scaling problem — the same "content migrates to the always-loaded document" failure mode that STATE.md compaction exists to prevent, but for the index.
## Root cause
The index-row update convention appends a per-revision narrative to the status cell on every story change, rather than keeping the cell to its load-bearing summary fields (current version token, status, current bc_traces/version pins, current provenance one-liner) and leaving revision history to the story's own changelog. There is no size budget or compaction check on index rows (contrast STATE.md, which has a documented line budget + `/compact-state`).
## Suggested mitigation
- Define the index-row status cell as a **current-state summary only**: current version token, status, points/AC count, current bc_traces + versions, a one-line provenance/current-position note. Revision history belongs to the story's own changelog, referenced by version — not re-narrated in the index.
- Add an index-health check analogous to STATE.md's line budget: warn when a row cell exceeds a character budget or accumulates more than a small number of inlined per-version sub-narratives; recommend compacting the historical prose out of the row (it already exists in the story changelog).
- Optionally a `compact-story-index` operation mirroring `compact-state`.
## Severity
MED — no correctness impact, but it's a real scaling/health defect on an always-loaded governance artifact, it duplicates authoritative history (drift risk), and it has no compaction path today. Same class STATE.md already guards against; the index lacks the equivalent guard.
Contributor guide
Research direction
Find the STORY-INDEX table generation and update logic, likely in a state manager or orchestrator module. Look for where the status cell is built and appended to on each story revision. Understand the current data structure to separate current-state summary from historical prose. Check for existing tests related to the index to ensure changes don't break lookups or scans.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend
- Issue type
- Refactor
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100