fabric-reference
Read-only runbook for how the VNX fabric actually works — state resolution, the single-entry dispatch door, gate invocation, the horizon planning layer, the plan-gate panel, and the hard gotchas that
SKILL.mdskills/fabric-reference/SKILL.md
GitHubVNX Fabric Reference
How the fabric works, as runbooks. This is lookup, not judgment — the t0-orchestrator skill owns orchestration decisions; vnx-manager owns infra maintenance. When a T0 rediscovers the same mechanism a third time, it belongs here.
Master-rule (see role-orchestrator.md): project files describe the project; the fabric describes itself. Fabric mechanism lives in the canonical role and here, never copied into a consumer's CLAUDE.md.
Runbook: state resolution
Tracks, objectives, receipts, and coordination state live in the central store, never repo-local.
- Central store:
~/.vnx-data/<project_id>/state/(resolved by the vnx runtime, not hardcoded). - Never pin
VNX_STATE_DIRto a repo-local.vnx-data/statepath in a role or script — a repo-local pin forks state from central = split-brain. - Resolution helpers: Python
scripts/lib/project_root.py; Bashscripts/lib/vnx_resolve_root.sh. project_idnever silently defaults tovnx-dev(ADR-007) — it resolves fromVNX_PROJECT_ID/.vnx-project-id/ git remote, else it rejects.
vnx status # situational awareness from central state
cat .vnx-data/state/t0_state.json | python3 -m json.tool # SessionStart projection
vnx fabric-audit # store-hygiene: split-brain stores, per-project ledgers, hash-chain
Runbook: the single-entry dispatch door
Every dispatch goes through the one door, which decides the lane. Calling a lane script directly is a side door.
vnx dispatch <pending-id> # the door; decides lane, runs phantom-guard
- Provider→lane (hard):
claude/Opus/Sonnet route via the headless lane (dispatch_envelope.run_envelope_headless_plan,claude -p, subscription-preserving); the tmux-spawn lane was removed on 2026-09-18 — NEVERprovider_dispatch.kimi/glm/deepseekroute viaprovider_dispatch.py. - Default build-worker model: sonnet (
workers-kimi-pinned, pin_semantics=default; operator decision 2026-09-23). kimi-k3 is an explicit per-dispatch choice, not the default. A spec that names its own model or provider wins.VNX_OVERRIDE_WORKERS_KIMI_PINNED=1only downgrades the warning, it does not change routing. - Rollback to legacy routing:
VNX_DISPATCH_LEGACY=1(per terminal). - Autonomous staging flow (no template): track → central
stage_spec_bundle→ dry-run → fire → post-mergelink-pr. Full rule:docs/core/DISPATCH_RULES.md(§12 for autonomous). - No Claude Code subagents (Task tool) for dispatch work — governed lanes only.
Runbook: gate invocation
Three gates decide what merges: codex + kimi (adversarial review) + deterministic CI.
- Provider gates WRITE to the working tree. After a gate: stage the good changes,
git checkout --any stray edits. - codex = strict diff-mode; kimi = synthesis/operational angle (proven 3x parallel).
- Phantom-guard (
scripts/lib/phantom_guard.py) rejects evidence-free GATE-GREEN receipts. Read-only review roles (REVIEW_ROLES) are exempt — a verdict, not a diff, is expected. - Required headless review gate is not complete until BOTH the result record and the normalized headless report exist.
- Self-merge rule: allowed when local CI is green AND the codex-gate passed — but confirm the FULL GitHub CI is green first, not just the gate (a literal in a CHANGELOG once tripped the state-pin gate and broke main).
Runbook: horizon (planning / future-state)
vnx horizon list # actionable-by-default: done hidden
vnx horizon list --all # include done tracks
vnx horizon list --horizon now --phase queued # the real open NOW work
vnx horizon show <track_id>
vnx horizon reconcile # git-grounded auto-close CHECK (no writes)
vnx horizon reconcile --apply # close CONFIRMED tracks (PR merge verified via gh)
vnx horizon close <track_id> --apply --approval-id <token> # human-gated single close
vnx horizon drift # advisory declared-vs-derived divergence
bin/vnxexposes the same verbs under the olderobjectivename (bin/vnx objective list). pipvnxuseshorizon.- A track is
donewhen reconcile confirms its PR merged. Done tracks stay in their band + the ledger;listhides them by default so a reconciled-but-unarchived track does not read as live drift. VNX_AUTO_CLOSEgates whether the SessionStart tick auto-closes; when unset, reconcile is manual.
Runbook: the plan-first gate (panel)
vnx horizon plan-gate ... # multi-model panel reviews a plan before any build
- Panel = Opus + Kimi + GLM-5.2-via-harness (three families → real disagreement).
- One flaky panelist (unparseable JSON, empty output) must not force a REVISE — quorum/abstain handles it (#910). Never treat a codex/glm flake as PASS; retry works.
- The panel has no closeout mode — Tier-2 closeouts can get category-error REVISEs; judge accordingly.
Gotchas (the ones that repeatedly bite)
- PATH-break in a bash loop: do not run
head/cmp/gitright aftervnxin the same loop iteration — split into separate calls. - Dual-CLI: the real
vnxis the pipvnx_clieditable install (vnx_cli/commands/*), NOT the bashbin/vnx(scripts/*). Verify operator/cutover claims againstvnx_cli, or you check the wrong code path. New commands go in BOTH. - codex-cert: a dead codex-gate is usually a macOS cert-revoke → Trash the binary; fix with
npm i -g @openai/codex@latest(node v22).glm-harnessneeds the local proxy on :4141 (restart per session, not persistent). - kimi-gate edits the working tree: stage the good, revert the stray.
- classifier-protected actions: "fully autonomous" does NOT cover
.claude/settings.jsonself-modification, git tag-push, or PyPI-publish — those stay human-gated. vnx start --helpruns start: it spawns the daemon set (footgun); SIGKILL the supervisor root if triggered.- Central-mode paths: embedded-layout path assumptions can break central-mode resolution (fleet burn-in) — resolve via the helpers, never hardcode
.vnx-data/literals.
Known issues (tracked, active)
- An empty provider completion is usually a TRANSIENT lane issue, not a structural door bug: if
bin/vnx dispatch <id>for a provider lane (kimi/glm/deepseek) lands an empty completion, check the lane's health FIRST — kimi OAuth/quota, glm proxy on:4141— not the envelope. The door's provider path works end-to-end; a blank completion is now downgraded to a loudfailure(embedding the raw spawn result) for ALL provider spawns as of #1107, and the door surfacesEnvelopeResult.errorinstead of a bare exit code, so the real cause is visible. - The plan-gate runs one seat (P2, 2026-10-17): in
plan_gate_panel.py(NOT the/panelskill) a run has the default seat (codex), plus opus only when codex returns BLOCK (configs/plan_gate_panel.yaml). A codex seat that abstains on unparseable verdict JSON or never delivers leaves zero readable verdicts, which isINFRA_FAIL, not a REVISE; the version stays unread and the next run gives it its seat round again. Read the scoring-seat count in the log before trusting a plan-gate PASS/REVISE.
Where the source of truth lives
- Dispatch mechanics, lanes, failure modes:
docs/core/DISPATCH_RULES.md - Architecture + data flow:
docs/core/00_VNX_ARCHITECTURE.md,docs/core/DISPATCH_AND_INTELLIGENCE_ARCHITECTURE.md - State fabric:
docs/core/STATE_FABRIC.md - Provider constraints (machine-readable SSOT):
scripts/lib/providers/provider_constraints.yaml - ADRs:
docs/governance/decisions/