BOHICA-LABS / BOHICA-LABS/vsdd-factory

Records-tier convergence acceleration: record line-cite ban, mechanical records-lint, records-only micro-burst

Open
#762 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Rust
Stars
2
Forks
1
Avg merge
6h 43m
Merged PRs (30d)
29

Description

## Problem
On a long-running adversarial spec cascade (40+ stage-level fresh-context passes on a production factory project), the content/mechanism tier converged early — but CLEAN(strict) was blocked for 9+ passes by a records-tier treadmill: every fix-burst hand-authors 10–20 record sites (ratification blocks, changelog rows, ledger rows, pin chains), and the next fresh-context pass finds 2–5 defects in exactly that newly-authored text. Observed classes: (a) volatile line-number cites self-invalidated by the same burst's own insertions (frame/off-by-one family — recurred inside its own fix burst three consecutive times); (b) finding-ID attribution errors (4+ consecutive bursts, survived repeatedly-strengthened prose self-audit rules); (c) hand-transcribed scalar/count drift; (d) changelog row-order and currency-mirror rot. Prose self-audit rules (lessons + runbook criteria) demonstrably fail for these classes: each new rule catches one instance while a sibling slips through.

## Proposed engine-level changes (all field-tested, human-directed)
1. **Record line-cite ban (anti-volatile-pin extension).** The factory's anti-volatile-pin rule typically excepts "pass-report changelogs / records may cite exact locations". That exception is the root cause of class (a). Proposal: retire the exception — ALL record text cites section/anchor/symbol names, never file:NNN. Grandfather history; enforce on newly-authored records only.
2. **Mechanical records-lint as a shipped factory tool + pre-commit gate.** A deterministic bash lint the orchestrator runs before every state-manager commit (exit 1 blocks; violations route to owning agents by check ID). Field-proven checks: L1 title/H1↔frontmatter version parity; L2 test-pointer range parity across twin artifacts; L3 manifest input-pins↔actual artifact versions+wc; L4 ratification-block finding-IDs exist in the changelog findings column (parser must handle slash-compound and OBS ID forms); L5 stale live count-citations (both directions between artifacts); L6 precedence-terminal↔frontmatter parity; L7 changelog monotonic version order; L8 index/status-ledger currency parity; L9 line-cite ban on new record text. Observed results: fixer bounce-backs went 3→0→0 across the first three lint-gated bursts; the lint auto-caught two live stale-count instances that previously required prose sweeps; terminal pin-reconciliation worklists became mechanically enumerated (the lint's failure output IS the worklist).
3. **Records-only micro-burst template.** When a pass returns ONLY records-tier LOW/OBS findings (no content/mechanism defects), run a 2-step burst (one ownership-routed fixer + state-manager, lint-gated) instead of the full multi-agent ceremony — ~2/3 wall-clock reduction on tail bursts.

## Supporting lessons worth codifying engine-wide
- MECHANICAL-GATE COVERAGE PARITY: every check a gate CLAIMS must be self-probed against a synthetic violation before the claim ships (the CI-as-code false-green family — the first fresh-context audit of the new lint found 4 claimed-vs-implemented gaps: a grep anchored to the wrong table, a dead-code check path, an ID regex that couldn't parse the house citation convention, and unreachable error guards under set -euo pipefail).
- SCAN-POPULATION corollary: when a fresh pass finds defects outside the gate's sight, the default response extends the gate's scan population — not another prose rule.

## Evidence
Field data from a production factory project (private; details available on request from the maintainer). The pattern has already been transposed to two additional factory projects using a parameterized lint template with a staged-files ratchet for brownfield adoption.

## Suggested integration points
- templates/: parameterized records-lint.sh + artifact-map config
- state-burst / state-update skills: mandatory pre-commit lint gate
- adversarial-review skill: records-only micro-burst routing rule
- FACTORY.md / rules: anti-volatile-pin exception retirement

Contributor guide

Open the contributing guide

Research direction

The issue describes adding a records-lint tool and changing burst routing rules. Start by examining the repository's templates/ directory for existing lint scripts and the state-burst or state-update skills. Look for the anti-volatile-pin rule in FACTORY.md or rules files. 'Done' means a parameterized lint.sh is added, the pre-commit gate is enforced, and the micro-burst routing rule is implemented.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash, rust, shell
Domain
backend-api-design, devtools, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.