Fabric Reference

---
name: fabric-reference
description: 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 repeatedly bite (PATH-break, dual-CLI, codex-cert, classifier-protected actions). Use when you need to look up a fabric operation instead of rediscovering it, or when a fabric command behaves unexpectedly. Companion to the t0-orchestrator skill (judgment) and vnx-manager (infra maintenance); this one is pure reference.
allowed-tools: [Read, Grep, Glob, Bash]
---

# VNX 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_DIR=.vnx-data/state` in a role or script — a repo-local pin forks state from central = split-brain.
- Resolution helpers: Python `scripts/lib/project_root.py`; Bash `scripts/lib/vnx_resolve_root.sh`.
- `project_id` never silently defaults to `vnx-dev` (ADR-007) — it resolves from `VNX_PROJECT_ID` / `.vnx-project-id` / git remote, else it rejects.

```bash
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.

```bash
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 — NEVER `provider_dispatch`. `kimi`/`glm`/`deepseek` route via `provider_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=1` only 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-merge `link-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)

```bash
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/vnx` exposes the same verbs under the older `objective` name (`bin/vnx objective list`). pip `vnx` uses `horizon`.
- A track is `done` when reconcile confirms its PR merged. Done tracks stay in their band + the ledger; `list` hides them by default so a reconciled-but-unarchived track does not read as live drift.
- `VNX_AUTO_CLOSE` gates whether the SessionStart tick auto-closes; when unset, reconcile is manual.

## Runbook: the plan-first gate (panel)

```bash
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`/`git` right after `vnx` in the same loop iteration — split into separate calls.
- **Dual-CLI:** the real `vnx` is the pip `vnx_cli` editable install (`vnx_cli/commands/*`), NOT the bash `bin/vnx` (`scripts/*`). Verify operator/cutover claims against `vnx_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-harness` needs 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.json` self-modification, git tag-push, or PyPI-publish — those stay human-gated.
- **`vnx start --help` runs 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 loud `failure` (embedding the raw spawn result) for ALL provider spawns as of #1107, and the door surfaces `EnvelopeResult.error` instead of a bare exit code, so the real cause is visible.
- **The plan-gate panel can score on fewer than 5 seats (`plan-gate-panel-seat-robustness`):** in `plan_gate_panel.py` (NOT the `/panel` skill) the **opus seat NO-VERDICTs reliably** on a `data_dir=None` report-resolution miss (#1102 class: `staging_validator: unstaged dispatch override`), and the codex + glm seats can **intermittently** abstain on unparseable verdict JSON (codex abstained in one round, scored the next). A verdict may rest on as few as 2 seats (kimi + deepseek) or as many as 4 — **confirm the real 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/`