agentleFS
Sign inStart free
Vinix24Vinix24/vnx-orchestration/CLAUDE.md

vnx-orchestration

CLAUDE.md63 starsChanged 8 days agoMITView on GitHub

This repository is governed by VNX Glass Box Governance: multi-agent orchestration with a human gate at every step and an append-only NDJSON receipt per dispatch. The mechanism is not duplicated here. How the fabric works — the single-entry dispatch door and its lanes, review gates, the horizon planning layer, state resolution, and the report contract — lives in one canonical place so it can never drift out of a project file: Everything above this block describes this project. Everything the…

  • Reads credentials

The file

We split this CLAUDE.md into the rules it gives an agent

6 rules. About 0 are common, 0 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    No mock objects, placeholder data or stub implementations in shipped code.

    line 24
  2. Very specific:

    Never create _v2, _fixed or _new duplicate files: edit the original.

    line 26
  3. Very specific:

    No T0 role file loaded (autonomous/project-root T0)?

    line 82
  4. Very specific:

    All scripts must resolve project root via helper libraries — never hardcode paths or rely solely on env vars.

    line 99
  5. Very specific:

    Only subprocess-routed terminals produce this stream.

    line 107
  6. Very specific:

    Default (unset or legacy): no behavior change.

    line 117

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md
<!-- VNX:BEGIN BOOTSTRAP -->

VNX Governance

This repository is governed by VNX Glass Box Governance: multi-agent orchestration with a human gate at every step and an append-only NDJSON receipt per dispatch.

The mechanism is not duplicated here. How the fabric works — the single-entry dispatch door and its lanes, review gates, the horizon planning layer, state resolution, and the report contract — lives in one canonical place so it can never drift out of a project file:

  • How the fabric works: the canonical orchestrator role, .claude/terminals/T0/role-orchestrator.md, kept in sync fleet-wide by vnx role sync.
  • Runbooks + gotchas: the fabric-reference skill.
  • Dispatch mechanics (lanes, provider routing, failure modes): docs/core/DISPATCH_RULES.md.

Everything above this block describes this project. Everything the fabric does lives in the canonical role — never copy fabric mechanism back into this file, or the copy drifts the moment the fabric changes.

<!-- VNX:END BOOTSTRAP --><!-- The sections below live here because this repo IS the fabric. In a consumer project they do NOT belong in CLAUDE.md: the report contract reaches workers operationally via build_directive() at dispatch time, and lane detail lives in the canonical role + docs/core/DISPATCH_RULES.md. They stay outside the bootstrap block so `vnx role sync` / re-init never propagates them into consumer files. -->

Build rules

  • No TODO / FIXME comments: finish the implementation or leave it out.
  • No mock objects, placeholder data or stub implementations in shipped code. Tests patch external processes and services as the test rules require; that stays allowed and stays inside tests/.
  • Tests go in tests/, never next to the source. Scripts go in scripts/.
  • Never create _v2, _fixed or _new duplicate files: edit the original.

Mandatory Report Contract

Every agent and worker MUST write a unified report on completing any task.

This is how work enters the governed audit trail:

report on disk → receipt processor → t0_receipts.ndjson

Without a report, your work has no receipt and is invisible to governance.

Write to: $VNX_DATA_DIR/unified_reports/<dispatch-id>.md

Your report MUST contain these exact headings (aliases accepted):

RequiredAccepted aliases
## Summary—
## Changes## Files Modified, ## Work Completed
## Verification## Test Results, ## Evidence, ## Tests
## Open Items—

## Summary must be at least 50 non-whitespace characters. ## Open Items may contain "None" explicitly. Include your dispatch ID as a plain-text or bold field (e.g. Dispatch-ID: 20260601-213416-myfeature). Full contract: scripts/lib/report_body_contract.py.

A dispatch report also needs an identity block, or its receipt never lands. The table above (validate_body()) does not require Model or Provider — but the receipt-converter fail-closed model check does (scripts/lib/append_receipt_internals/validation.py::_validate_model_present): any dispatch-lane report without a real Model is REFUSED at receipt-write time, silently as far as the report contract is concerned (it can still pass validate_body() cleanly). Include a Model:/Provider: bold-field or frontmatter pair (e.g. **Model**: sonnet, **Provider**: claude) alongside your Dispatch-ID so the receipt actually gets written — see the fail-closed check itself (_validate_model_present) for the rationale, and scripts/lib/report_to_receipt_converter.py for how the refusal is logged (WARNING, dispatch-id + reason) and surfaced (health/report_to_receipt_converter.json).

Dispatch lanes

The single-entry door always resolves a claude dispatch to claude_headless: resolve_claude_lane in scripts/lib/dispatch_plan.py returns that lane unconditionally, so it is the only claude lane the door itself picks. scripts/lib/subprocess_dispatch.py also starts claude, but outside the door's lane decision: it is a separate, terminal-pinned path that the worker terminals (T1-T3) always take, while T0 opts in (see below). A third lane, provider_dispatch.py, routes the non-claude providers (kimi/glm/deepseek), covered further down. Full decision rule, provider strings, concurrency, and failure modes live in docs/core/DISPATCH_RULES.md (the tmux-spawn lane was removed on 2026-09-18: docs/operations/TMUX_SPAWN_LANE.md).

  • dispatch_envelope.run_envelope_headless_plan (claude_headless, default for claude) — claude -p via envelope, isolated worktree per dispatch, subscription-preserving. No live pane.
  • scripts/lib/subprocess_dispatch.py — terminal-pinned (Wave 5 smart-context, lease, triple-gate). The worker terminals (T1, T2, T3) always take this path; their VNX_ADAPTER_T{n} selector is gone since T-G1 (2026-10-27), and only T0 still opts in with VNX_ADAPTER_T0=subprocess (T-B2 removes that). Its main/__main__ entry point and _pool_heartbeat_loop stay: they are the hard-parked rollback route (VNX_SINGLE_ENTRY_DISPATCH=0 / VNX_DISPATCH_LEGACY=1). Use for single-worker PRs that benefit from prior-round findings, or work expected to run >30 min. No Anthropic SDK — only subprocess.Popen(["claude", ...]).

Provider→lane rule (hard). claude/Opus/Sonnet panelists and workers run on the headless lane (claude -p, subscription): the default since A2 (2026-08-26) and the only claude lane since the tmux-spawn lane was removed on 2026-09-18 — NEVER provider_dispatch (it refuses claude: claude is not a provider-lane provider). The lane runs on the Max subscription, not API credits — measured 2026-08-11 via auth state (no ANTHROPIC_API_KEY/ANTHROPIC_BASE_URL, keychain subscriptionType: max); the "API-metered post-cutover" reason this line used to carry was never true (Anthropic never carried out that cutover). Isolation and report-gate status for the headless lane: DISPATCH_RULES §8 (do not duplicate the mechanism here — it drifts). kimi/glm(litellm:zai)/deepseek route via provider_dispatch.py. Everything dispatches through the single-entry door (vnx dispatch), which decides the lane; calling a lane script directly is a side door (PR-12 consolidates the remaining ones, incl. the plan-gate panel). The plan-first gate (plan_gate_panel.py) honors this split.

For full documentation: docs/

<important if="working on schemas/migrations"> ADR-007 binding: every new central-DB table requires composite UNIQUE/PK over project_id. See `docs/governance/decisions/ADR-007-multitenant-project-id-stamping.md`. T0 must cite this explicitly in review-gate prompts. </important><important if="working on review-gates or codex/kimi review providers"> Cross-vendor review split (operator decision, 2026-05-29): codex for strict diff-mode, kimi for synthesis/operational angle. Parallel review pattern proven 3x. Raw vs gate-routed dispatch = different audit trail — audit concern applies. </important><important if="working on dispatch infrastructure or subprocess adapter"> Wave 6 elastic pool shipped 2026-05-16 (ADR-018, 9 PRs). Use `bin/vnx pool {status,scale,config,reap}`. Backward-compat: terminal-pin via subprocess_dispatch.py still works. SubprocessAdapter path: `scripts/lib/subprocess_adapter.py` + `scripts/lib/subprocess_dispatch.py`. Single dispatch entry is the door (`vnx dispatch`): decision-tree enforced in code + side-door blocking. Dispatch mechanics, lanes, and failure modes: `docs/core/DISPATCH_RULES.md`. No T0 role file loaded (autonomous/project-root T0)? The staging flow for a governed dispatch (track → central `stage_spec_bundle` → dry-run → fire → post-merge `link-pr`) is `docs/core/DISPATCH_RULES.md` §12 "Autonomous dispatch — the staging flow". </important><important if="working on receipt processor or governance/audit trail"> GOV-1/2/3 receipt-gap: raw `claude -p` bypasses receipts. rc9 shipped cheap-lane fixes. Self-learning loop is dormant. Receipt processor must be running for audit trail integrity. `.vnx-data/` is runtime state — never commit it. </important><important if="working on tmux delivery or session hooks"> Hard rule: Enter ALWAYS as a separate tmux keystroke — combined send-keys misses delivery. </important>

Path Resolution

All scripts must resolve project root via helper libraries — never hardcode paths or rely solely on env vars. Python: scripts/lib/project_root.py. Bash: scripts/lib/vnx_resolve_root.sh. Background: issue #225.

Event Streams

.vnx-data/events/T{n}.ndjson is a per-dispatch ring buffer, not a long-running log. At the end of each subprocess-adapter dispatch, the live file is archived to .vnx-data/events/archive/{terminal}/{dispatch_id}.ndjson and truncated to 0 bytes. If you're debugging "the live file is empty", look in the archive directory instead.

An archive file may be compressed: <dispatch_id>.ndjson.gz (plain wins when both exist). Open archives through the helpers in scripts/lib/event_store.py (resolve_archive_file, open_archive_text, list_archive_files, find_archive_file), never with a bare *.ndjson glob. The vnx-data-footprint probe (scripts/lib/vnx_data_footprint_probe.py) reports archive, salvage and free-disk footprint per store.

Only subprocess-routed terminals produce this stream. The worker terminals (T1-T3) are always headless since T-G1; the tmux adapter (T0 by default, unless VNX_ADAPTER_T0=subprocess) produces no per-terminal NDJSON.

Supervisor Mode

Set per-project to enable unified supervisor (auto-respawn, lease sweep, runtime supervision):

VNX_SUPERVISOR_MODE=unified   # opt in to supervisor

Default (unset or legacy): no behavior change.

When enabled:

  • Dispatcher prelude ticks lease_sweep every 30s
  • Dispatcher prelude ticks runtime_supervise every 60s
  • Recommend wrapping daemons via dispatcher_supervisor.sh and receipt_processor_supervisor.sh

See docs/operations/UNIFIED_SUPERVISOR.md for full guide.

<!-- Local maintainer overrides (optional, gitignored): machine-specific VNX notes live in ~/.claude/vnx-local.md; repo-local private notes in CLAUDE.local.md. Both load after this file and win on conflict. Keep secrets and absolute local paths out of this tracked file. -->

@~/.claude/vnx-local.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free