Configuration

The manifest

The manifest, .claude/pipelines/coding-pipeline.json, is the pipeline's policy: which steps exist, in what order, what each step dispatches and what must be proved before a node may leave it. One value governs every campaign run on this pipeline, because no script carries a step name of its own. A person changes it by editing and committing the file. An unattended session cannot, because guard-enforcement-surface.ts denies writes under .claude/pipelines/ in a dispatched session. Keys under steps.definitions are set per step, written below as <step>.<key>.

Bead metadata

Bead metadata is the key-value store each issue in the tracker carries; an issue is a bead. The pipeline keeps all its state there under the reserved pipeline. prefix, and pipeline-transition.sh is its only writer: bd-pipeline-guard.ts denies a direct bd update --set-metadata pipeline.* unless a person prefixes the command with VOX_PIPELINE_OVERRIDE=1. Most of these keys record where a node is, but some are per-campaign facts that change behaviour, such as the integration branch, the delivery mode, the dial and the integrate floor's suite command. The authoritative list is the manifest's state_keys block, which names each key's writing verb; the header of pipeline-transition.sh gives every verb's contract. A key scoped to the campaign root is read only there, by an ancestor walk, so a copy written on any other bead is never read. The landing floor also stamps the bead's own external_ref field with the pull request it proved; that is a tracker field, not metadata.

The project's own repository

A codebase run through the pipeline carries a few committed files that describe it. The main one is the project overlay, .vox/project.json, which declares the codebase's identity; the two others prepare a fresh worktree. One value governs every bead whose project:<id> label names the codebase. Where the codebase sits on a given machine is not here; that is the machine configuration below. The lab's machine-configuration notes describe the split.

The worktree registry

The worktree registry, .claude/worktrees.json in the VOX repository, records each project's shared dev worktree: one long-lived worktree, with secrets and dependencies in place, that a dispatched bead takes when it is free. A project missing from it gets a fresh worktree per bead, and nothing else changes: guard-worktree-edits.ts, the hook that refuses edits in a project's primary checkout, protects the primary of every repository carrying a project overlay except VOX's, listed here or not. Registration only changes where its denial points: to the shared dev worktree rather than to the bead worktrees.

The machine configuration

The machine configuration, ~/.vox/config.json, records where things are on one machine. It is never committed, so each machine keeps its own. Its normative definition is readUserConfig in project-resolver.ts, and the lab's machine-configuration notes explain each section. The Codex CLI's own per-machine file is listed here too, because when no model is passed the review and spec harnesses run on the default it names.

Environment variables

An environment variable is a value the shell hands to every program it starts. Most of these variables are documented nowhere but in the scripts that read them, so the Home column names the script that applies the default. Some are set for every Claude Code session by the env block of .claude/settings.json, which pipeline-executor.sh loads explicitly into each dispatched session (--settings $VOX_ROOT/.claude/settings.json); some the executor sets itself for the session it spawns; the rest come from the shell of whoever starts a run.

Other VOX_ names in .claude/scripts/ and .claude/hooks/ are not coding-planner settings and are left out: VOX_HOME belongs to setup.sh; VOX_BRIEFING_MODEL, VOX_SOURCE_APP and VOX_VOICE_SERVER_PORT belong to session hooks; VOX_BLOCK_STUB_* and VOX_SPEC_STUB_MODE are test stubs; and VOX_REVIEW_RESULT, VOX_SPEC_RESULT, VOX_REVIEW_BLOCKED and VOX_SPEC_BLOCKED are the prefixes of the harnesses' result lines, not variables.

The review model is a stopgap. The lab decided in October 2026 that Gate B reviews use the model gpt-6-astra: gpt-5.6-sol hung repeatedly, six times on one bead, and gpt-5.5 is refused for a Codex login through a ChatGPT account. To make dispatched sessions inherit the ruling, VOX_REVIEW_MODEL=gpt-6-astra was added to the env block of the primary checkout's .claude/settings.json, the copy the executor loads. It is a local edit there, not a committed setting, so another checkout or another machine reviews on its Codex default. Three things follow from where it sits. review.md names no model on purpose and calls VOX_REVIEW_MODEL an override "for a one-off comparison, not as a standing pin"; this entry is a standing pin, in a file nobody reading review.md would open. Because vox-review.sh ranks the variable above the model recorded in round 1's review, the entry also overrides the round-2 pin: a bead whose round 1 ran on another model is judged in round 2 by gpt-6-astra, a different judge that re-argues the whole change instead of adjudicating the fix, which is the failure the pin exists to prevent. And VOX_SPEC_MODEL is unset, so a spec:codex bead still drafts its spec on the Codex default; the ruling covers Gate B only.

Where this should live. The proposed home is the review step's definition in the manifest, as a key such as steps.definitions.review.model beside fix_rounds. The manifest is already the home of review policy, it is committed and travels to every machine, and an unattended session cannot change it. vox-review.sh reads nothing from the manifest, so the key needs wiring: the script, or the review command passing --model, would read it. A precedence that keeps the round-2 pin intact is --model, then VOX_REVIEW_MODEL, then round 1's recorded model for round 2, then the manifest's model, then the Codex default; the settings entry would then be removed, leaving the variable for one-off comparisons as review.md intends. The move runs against review.md's reason for naming no model: a pinned name once left a review path calling a model the account could not run. A manifest key is still a pinned name, so when the model is retired the review fails until someone edits that key, and review.md's paragraph would need rewriting to say where the name lives and why. Moving the setting and revising review.md are the owner's decision; this section records the proposal and changes neither.

Labels and agent definitions

A label is a tag on a bead, set with bd update --add-label. A few labels change what the pipeline does with the bead that carries them. The deterministic guard does not police labels, so apart from the two waiver labels the transition script writes and the execution: label the fan-out sets, nothing mechanical stops any session from setting one; that a person sets them is a convention. The agent definitions in .claude/agents/ pin the model and effort of the agents that author a step's artifacts. The fleet standard in afk-contract.md §9 requires spec, implement and review-orchestration agents to run the strongest implementation model at effort high and never inherit the session's model; these pins are where that holds when a step dispatches a named agent. The Gate B reviewer is not a local agent, and its model is the review model above.