Story: Environment provisioning overhaul: lightweight environments, GCP-style naming, bootstrap independence

Table of Contents

This page documents a story in Sprint 21. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

A developer with a fresh machine can clone the repo once (creating the genesis environment), then provision lightweight named worktrees with a single compass command. Light environments skip the C++ toolchain entirely yet can still run all docs, agile, and compass targets via direct emacs invocation. Full environments preserve the current stack unchanged. Every worktree gets a descriptive adjective-noun name (GCP-style) rather than an ad-hoc local1=/=remote label.

Status

Field Value
State DONE
Parent sprint Sprint 21
Now All tasks complete or abandoned. Story closed.
Waiting on Nothing.
Next Nothing.
Last touched 2026-06-25

Acceptance

  • [ ] compass env create <name> [--type light|full] provisions a named worktree from the genesis env
  • [ ] compass env configure (renamed from env init) generates .env; env init no longer aliased — unknown subcommands now show usage with valid choices
  • [ ] ORES_ENV_NAME replaces ad-hoc label derivation from directory name as the canonical env identifier
  • [ ] ORES_PROVISION_TYPE is written by env provision and readable by all stack layers
  • [ ] ORES_BASE_PORT and ORES_NATS_PORT are assigned at create time; env configure reads them from .env if already set
  • [ ] DB name uses label_lower (underscored) form, not raw label (fixing the hyphen-in-identifier bug)
  • [ ] Light environments can run all agile/docs targets (settings, skills, manual, site) via compass without cmake or vcpkg
  • [ ] compass bearings warns when the genesis environment cannot be found at the expected path
  • [ ] Bootstrap docs updated to reflect genesis → env create provisioning flow

Tasks

Task State Start End Description
Design: env types, GCP naming, genesis env, compass command UX DONE 2026-06-14 2026-06-14 Research and document the design decisions: light vs full environment types; adjective-noun naming convention and database naming scheme; genesis environment concept (the canonical initial clone from which worktrees are provisioned); and UX analysis of compass command naming — specifically how to name the new worktree-creation command and what to rename the existing 'compass env init' (.env generator) to avoid confusion.
Add pillar-organised compass commands that invoke emacs directly DONE 2026-06-14 2026-06-14 Add new compass commands for the agile/docs pillar targets (settings, skills, manual, site) that call emacs org-babel directly, bypassing cmake and vcpkg entirely. These complement the existing cmake-based build targets and allow light environments to run these operations without a configured C++ toolchain. Organise the new commands consistently within compass's pillar structure.
Implement genesis env concept and worktree provisioning command DONE 2026-06-16 2026-06-18 Introduce the genesis environment (the canonical first clone that seeds all worktrees). Implement a new compass command (name TBD from design task) that creates a named worktree using the adjective-noun convention, capturing the environment name before .env generation. Rename or alias the existing 'compass env init' to a name that clearly distinguishes .env configuration from environment provisioning, as determined by the UX analysis in the design task. Support –type light full at provision time.
Add ORES_ENV_TYPE property and propagate through the stack DONE 2026-06-15 2026-06-16 Add an ORES_ENV_TYPE variable (e.g. development, staging, production) to the .env template. Propagate it to postgres (e.g. via set_config or role/schema naming conventions) and to ores.qt so the user can see the environment type clearly in the UI (e.g. status bar or window title).
Update bootstrap docs and add compass bearings warning for missing genesis env DONE 2026-06-16 2026-06-18 Update README and any other new-machine bootstrap documentation to reflect the new provisioning model: genesis environment clone, then worktree environments via the new compass command. Add a check to 'compass bearings' that warns when the genesis environment cannot be found at the expected path, so users are alerted early on a fresh machine.
Migrate doc-build call-sites to compass –direct (retain vcpkg bypass) DONE 2026-06-18 2026-06-19 Scouting reversed the original "remove the cmake vcpkg-bypass hacks" framing: the ORES_VCPKG_ENABLED bypass and linux-doc-only preset are load-bearing (they keep the CDash site build vcpkg-free and let cmake-only doc targets build in light environments). Instead, migrate every doc/agile call-site that has a compass equivalent (compass build –direct, compass sprint charts) off raw cmake, making the light-env path the default; keep cmake behind the bypass only for doc targets with no compass equivalent and for the CDash submission.
Investigate sharing vcpkg installed packages across environments ABANDONED     Determine whether the per-checkout vcpkg_installed/ directory can be shared across full worktrees to reduce disk usage. The binary archive cache (~/.cache/vcpkg/archives) is already machine-global. Investigate using –x-install-root or symlinks to point all full envs at the genesis checkout's vcpkg_installed/, and assess risks (concurrent builds, branch version divergence).
Integrate install_debian_packages.sh into compass env configure DONE 2026-06-19 2026-06-23 Wire the Debian package install script into compass env configure so environment provisioning is a single command. Depends on the genesis env / worktree provisioning command task.
Spike: investigate and implement compass story done and task done commands ABANDONED     Compass has no story done or task done subcommands — closing a story requires manually editing story.org and the sprint table. Investigate what state transitions are needed, what side-effects should fire (journal stamp, sprint table update, PR linkage), and implement the missing commands.
Provision Claude Code settings and skills into new environments DONE 2026-06-25 2026-06-25 When compass env provision creates a new worktree, copy or symlink the .claude/ directory (settings.json, skills/) so that Claude Code is immediately usable without manual setup.
Improve compass bearings warning to distinguish missing vs stale .claude/ artefacts DONE   2026-06-25 compass bearings warned 'is older than' even when .claude/settings.json and .claude/skills/ did not exist, which was misleading. Fix to show 'does not exist' when absent.

Decisions

D1 — Environment types: light vs full

Two types controlled by the --type flag at compass env provision time, stored as ORES_PROVISION_TYPE in .env.

  • light: no C++ toolchain, no vcpkg, no NATS, no Postgres. Supports agile docs, compass, and emacs-driven build targets (settings, skills, manual, site). Minimum bootstrap: git, emacs, python, compass venv.
  • full: complete stack — C++, vcpkg, NATS, Postgres, Qt client. Superset of light.

The genesis environment is always full. New worktrees default to full unless --type light is given.

D2 — GCP-style adjective-noun naming

Replace ad-hoc local1=/=remote labels with descriptive adjective-noun pairs (e.g. festive-hawking, clever-turing). The name is stored as ORES_ENV_NAME in .env and used as the source of truth for all derived identifiers:

Derived identifier Rule Example
Directory name ores_dev_{name_underscored} ores_dev_festive_hawking
ORES_ENV_NAME verbatim (adjective-noun) festive-hawking
DB name / ORES_DATABASE_NAME ores_dev_{name_underscored} ores_dev_festive_hawking
DB role prefix ores_{name_underscored} ores_festive_hawking_owner
NATS subject prefix ores.dev.{name_dotted} ores.dev.festive.hawking
NATS store dir build/nats/{name}/jetstream build/nats/festive-hawking/jetstream

name_underscored replaces hyphens with underscores. name_dotted replaces hyphens with dots. This fixes the latent bug in env_init.py where db_name = f"ores_dev_{label}" could embed a hyphen, producing an unquoted PostgreSQL identifier that is syntactically invalid.

ORES_CHECKOUT_LABEL is kept as a deprecated alias written to .env alongside ORES_ENV_NAME during the transition; downstream code migrates to ORES_ENV_NAME over time.

D3 — Genesis environment

The genesis environment is the canonical first clone of the repo. Convention:

  • Path: ~/Development/OreStudio/OreStudio.genesis
  • Type: always full
  • Branch: typically main; the parent in git worktree list for all other worktrees
  • Name: genesis (not an adjective-noun pair — it is the root, not a worktree)

compass bearings checks for the genesis path and emits a warning when it cannot be found, so users on a fresh machine are alerted immediately.

All new worktrees are created with git worktree add from the genesis clone (by compass env create). Existing worktrees (local1, remote) are not renamed automatically; the user migrates on their own timeline, or leaves legacy names in place — the new scheme is additive.

D4 — Port allocation

The hardcoded dict {​"remote": 50000, "local1": 51000, ...} and the trailing-digit NATS port derivation are replaced by values written into .env at compass env create time.

Assignment strategy at create time:

  1. Scan all existing worktrees, read ORES_BASE_PORT from each .env.
  2. Assign the lowest free slot: base ports 50000, 51000, 52000, ... (step 1000); NATS ports 42221, 42222, ...
  3. Write ORES_BASE_PORT and ORES_NATS_PORT into the new .env before handing off to env configure.

compass env configure reads ORES_BASE_PORT and ORES_NATS_PORT from existing (the existing .env values) if already set, so re-running configure on an existing env never reassigns ports.

Port layout within a block (base_port = ORES_BASE_PORT):

  • HTTP port: base_port + 0
  • WT port: base_port + 2 (release: base_port + 1 / base_port + 3)
  • Site port: base_port + 4

D5 — Compass command UX

compass env create <name> [--type light|full]   NEW: provision worktree + configure .env
compass env configure [--preset P] [-y]         RENAMED from: compass env init
compass env init [--preset P] [-y]              ALIAS for: compass env configure (backwards compat)
compass env list [--show-secrets]               unchanged
compass env diff                                unchanged
compass env version [new <desc>]                unchanged

Rationale for the rename: compass env init sounds like "initialise a new environment" (worktree creation) but actually only generates the .env config file. Renaming it to configure makes the distinction clear: create provisions the worktree; configure (re)generates its credentials.

Out of scope

  • Renaming existing OreStudio.local1 / OreStudio.remote checkouts — migration is manual and optional; the new scheme is additive.
  • Generating the adjective-noun word lists — use a fixed embedded list in compass (same approach used by GitHub and GCP for auto-generated names).
  • Windows or macOS provisioning paths — this sprint targets Linux/WSL only.

Emacs 29.1 (Org mode 9.6.6)