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 fromenv init) generates.env;env initno longer aliased — unknown subcommands now show usage with valid choices[ ]ORES_ENV_NAMEreplaces ad-hoc label derivation from directory name as the canonical env identifier[ ]ORES_PROVISION_TYPEis written byenv provisionand readable by all stack layers[ ]ORES_BASE_PORTandORES_NATS_PORTare assigned at create time;env configurereads them from.envif already set[ ]DB name useslabel_lower(underscored) form, not raw label (fixing the hyphen-in-identifier bug)[ ]Light environments can run all agile/docs targets (settings, skills, manual, site) viacompasswithout cmake or vcpkg[ ]compass bearingswarns when the genesis environment cannot be found at the expected path[ ]Bootstrap docs updated to reflect genesis →env createprovisioning 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 oflight.
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 ingit worktree listfor 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:
- Scan all existing worktrees, read
ORES_BASE_PORTfrom each.env. - Assign the lowest free slot: base ports
50000, 51000, 52000, ...(step 1000); NATS ports42221, 42222, ... - Write
ORES_BASE_PORTandORES_NATS_PORTinto the new.envbefore handing off toenv 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.remotecheckouts — 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.