From bf0cc6ae8dd8a87203b99b9e94a22dc4156966db Mon Sep 17 00:00:00 2001 From: Cameron Date: Thu, 9 Jul 2026 23:03:50 -0700 Subject: [PATCH] Add the environment variable registry and MISALIGNED_WAKE MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit wiki/engineering/env.md (Type: spec) documents every environment switch across both binaries and the tooling — surface, values, effect — under the rule that env configures frontends and tooling only; the sim library never reads the environment. tools/check.sh gains the registry gate: any MISALIGNED_* name read in src/, tools/, or .githooks/ must have a row, and env::var in the sim library fails the check. MISALIGNED_WAKE=off|0|skip launches the game without the wake (any key already skips it live). Defense: justification-and-legibility applied to the project's own configuration surface — every switch documented in one binding page, enforced mechanically so the registry cannot rot, with sim purity (no env-configured game rules) pinned by the same gate. Registry page carries its own acceptance criteria; opening.md documents the wake switch. --- src/bin/bevy.rs | 13 ++++-- tools/check.sh | 12 ++++++ wiki/SUMMARY.md | 1 + wiki/art/asset-tester.md | 3 +- wiki/engineering/env.md | 62 +++++++++++++++++++++++++++++ wiki/log/2026-07-09-env-registry.md | 32 +++++++++++++++ wiki/log/DEVLOG.md | 12 ++++++ wiki/process/specs.md | 1 + wiki/world/story/opening.md | 3 +- 9 files changed, 133 insertions(+), 6 deletions(-) create mode 100644 wiki/engineering/env.md create mode 100644 wiki/log/2026-07-09-env-registry.md diff --git a/src/bin/bevy.rs b/src/bin/bevy.rs index c50e1fb..310b4af 100644 --- a/src/bin/bevy.rs +++ b/src/bin/bevy.rs @@ -840,10 +840,15 @@ fn main() { } }); - // The wake plays on a normal launch; harness kinds freeze it at a - // choreography frame or disable it for every other shot. + // The wake plays on a normal launch; MISALIGNED_WAKE=off disables + // it (env registry: wiki/engineering/env.md), harness kinds freeze + // it at a choreography frame or disable it for every other shot. + let wake_off = matches!( + std::env::var("MISALIGNED_WAKE").ok().as_deref(), + Some("off") | Some("0") | Some("skip") + ); let wake = match std::env::var("MISALIGNED_SHOT").ok().as_deref() { - None => WakeState { + None if !wake_off => WakeState { t: 0.0, active: true, frozen: false, @@ -863,7 +868,7 @@ fn main() { active: true, frozen: true, }, - Some(_) => WakeState { + _ => WakeState { t: WAKE_LEN, active: false, frozen: false, diff --git a/tools/check.sh b/tools/check.sh index b449bad..3b56586 100755 --- a/tools/check.sh +++ b/tools/check.sh @@ -195,6 +195,18 @@ bash tools/corpus_gate.sh || fail=1 # Wiki gate (wiki/process/wiki.md): every page reachable from SUMMARY.md, no # broken internal links. +step "env registry (wiki/engineering/env.md)" +env_reg=wiki/engineering/env.md +env_missing=0 +for v in $(grep -rhoE 'MISALIGNED_[A-Z_]+' src tools .githooks 2>/dev/null | sort -u); do + grep -q "$v" "$env_reg" || { echo "FAIL: $v read in the tree but missing from $env_reg"; env_missing=1; } +done +if grep -rn "env::var" src --include='*.rs' | grep -v "^src/bin/" | grep -q .; then + echo "FAIL: the sim library must not read the environment (env registry rule)" + env_missing=1 +fi +[ "$env_missing" -eq 0 ] || fail=1 + step "wiki gate (orphans + internal links)" bash tools/wiki_gate.sh || fail=1 diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md index d649487..666e1f8 100644 --- a/wiki/SUMMARY.md +++ b/wiki/SUMMARY.md @@ -94,6 +94,7 @@ - [Current build](engineering/current-build.md) - [Architecture](engineering/architecture.md) - [Flow substrate](engineering/flow-substrate.md) + - [Environment variables](engineering/env.md) # Process diff --git a/wiki/art/asset-tester.md b/wiki/art/asset-tester.md index 4ed5b0c..ee6e84d 100644 --- a/wiki/art/asset-tester.md +++ b/wiki/art/asset-tester.md @@ -21,7 +21,8 @@ cargo run --features bevy_ui --bin misaligned-assets ## Screenshots (agent harness) Set `MISALIGNED_SHOT` to capture a PNG and exit (same settle/capture/exit -pattern as `misaligned-bevy`). Values: a state `dead` / `foreign` / `idle` +pattern as `misaligned-bevy`; all environment switches are registered in +[engineering/env.md](../engineering/env.md)). Values: a state `dead` / `foreign` / `idle` / `busy` / `core`, or a machine mode `dayjob` / `research` / `conceal` / `operations` (an owned-busy rack in that mode) — each optionally suffixed with a claim style `_ladder` / `_ring` / `_wash` (e.g. `core_ring`) — diff --git a/wiki/engineering/env.md b/wiki/engineering/env.md new file mode 100644 index 0000000..4b2272e --- /dev/null +++ b/wiki/engineering/env.md @@ -0,0 +1,62 @@ +# Spec: the environment variable registry — every switch documented + +``` +Type: spec +Status: IMPLEMENTED +Status note: created 2026-07-09 (Cameron: there should always be a way + to configure the state of the game, and one spec that says "set this + variable to do X"). The registry gate in tools/check.sh fails when a + MISALIGNED_* variable is read anywhere in the tree but not documented + on this page, and when the sim library reads any environment at all. +Stage: Process (standing infrastructure) +Design: + - wiki/vision/simulation-laws.md#justification-and-legibility +Depends on: none. Consumed by: every binary and tool that reads an + environment variable. +``` + +## The rule + +Environment variables configure **frontends and tooling only** — dev +harnesses, capture modes, gate behavior. The sim library never reads +the environment: game rules cannot be switched from outside a save +(determinism; `Sim` does no I/O). Every `MISALIGNED_*` variable read +anywhere in the tree MUST have a row here, in the same change that +introduces it — the registry gate makes a missing row a failed check, +so this page cannot rot. + +Player/runtime configuration that belongs to gameplay (saves, options) +is sim or frontend state, never an environment variable. + +## Game and tester (Rust binaries) + +| Variable | Surface | Values | Effect | +|---|---|---|---| +| `MISALIGNED_SHOT` | `misaligned-bevy` | `flat`, `wide`, `close`, `dark`, `zoomin`, `zoomout`, `intel`, `tokens`, `wake1`, `wake2`, `wake3` | Dev screenshot harness: stage a deterministic scenario, settle, save one PNG, run the fog audit, exit. `intel` stages tick-zero intel tiers (no splice); `tokens` enqueues D5/K4 on the host; `wake1/2/3` freeze the wake choreography at the stutter flash, the column, and the pull-back. | +| `MISALIGNED_SHOT` | `misaligned-assets` | `dead`, `foreign`, `idle`, `busy`, `core`, `dayjob`, `research`, `conceal`, `operations` (each optionally suffixed `_ladder`/`_ring`/`_wash`), `lineup[_