BOHICA-LABS / BOHICA-LABS/vsdd-factory

enhancement(quality-gate+architect): declared ARCH dependency-DAG has no machine enforcement — forward-reference imports pass every gate

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

## Class

Architecture docs (ARCH-08-style) declare a topological ordering over internal packages: package at position N may import only positions < N. Nothing in the pipeline mechanically checks the code against that declaration. The declared DAG is enforceable in seconds (`go list -deps`, `cargo tree`, import-linter, etc.), but the engine relies on agents *remembering* the declaration — and on coordinators manually diffing imports at review time.

## Trigger (switchboard-blue, 2026-07-06, plugin 1.0.0-rc.21)

ARCH-08 §6 declares 18 internal packages with positions (session=6, tmux=7, outerassembler=8, arqsend=9, metrics=12, drain=16 …). A story delivery added `internal/session` (pos 6) → `internal/metrics` (pos 12) — a forward reference. Go compiled it happily (acyclic), lint/race/tests/quality-gate all green. The violation was caught only by manual coordinator review, cost one full rework round trip, and came wrapped in a doc comment asserting compliance (companion filing #521 covers the protocol side).

The check that caught it manually is trivially mechanizable — this exact command pair was used for verification in both directions:

```
go list -f '{{.Imports}}' ./internal/session
go list -deps ./internal/session/... | grep -E "internal/(metrics|routing|tmux)" # must be empty
```

## Why this matters more than a normal lint gap

The declared DAG is *load-bearing spec surface* in factory projects: stories cite positions, rulings reference them, and repair-by-renumber cascades staleness across every citation (in this instance, repairing the violation by renumbering would have staled drain=16 / outerassembler=8 / arqsend=9 citations across specs and rulings). A violation that ships therefore corrupts not just the code architecture but the citation graph above it.

## Proposed mitigation

1. **Architect emits a machine-readable companion** to the ARCH DAG section (e.g. `.factory/specs/architecture/dep-order.yaml`: ordered list of packages). The prose table stays canonical for humans; the YAML is its projection.
2. **Quality gate / per-story-delivery step (c3) runs a DAG-conformance check** derived from that file — language-appropriate (`go list -deps` per package for Go; `cargo metadata` for Rust; import-linter for Python). Fails closed on any forward reference.
3. **Adversary lens addition:** when a story's file list touches a package with a declared position, verify the import delta against the declared order (cheap targeted check even without CI wiring).

## Prior art / cross-refs

- #272 — architect hallucinated ARCH-08 packages (the declaration can be wrong); this issue is the complement: even when the declaration is *right*, nothing enforces it.
- #487 — smoke-sentinel gate at step (c3) (same insertion point; this check is the architecture sibling of that operator-surface sibling).
- #521 — same trigger, agent-protocol side (silent ruling divergence). Fix owners differ: this one is a mechanical gate, that one is a coordination mandate. Either alone would have caught/prevented the instance; both together close the class.

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.