docs(openspec): golden-fork ephemeral devcontainers proposal

[stephenliang]

OpenSpec change proposing golden-fork ephemeral devcontainers: disposable, credential-free dev sandboxes that fork a locally-refreshed "golden" environment in seconds, for humans and autonomous coding agents alike. Docs + reference implementations only — no product code changes in this PR.

The problem. A dev environment today is a 30+ minute babysat bootstrap (>10 min of it seeding curriculum), yields exactly one mutable environment per machine, and can't safely host autonomous agents because AWS credentials are ambient. The seed's incremental cache lives in DB columns, so a fresh DB always pays full price — only a materialized database short-circuits it.

The shape. Registry ships two boring images (toolchain+caches, and mysql:8.0 + pre-seeded datadir baked at a non-VOLUME path); the repo never ships in an image (git is the delta channel); a background golden refresh keeps a local golden current (never-commit-failures, last-good fallback); bin/sandbox new forks golden + adds a git worktree in ~4s with persona profiles (--rails|--frontend|--apps|--fullstack); sandboxes are zero-credential and can run fully offline. A DevEx verification suite turns the promised experience into CI-enforced budgets across every persona and angle (creation latency, edit/test loops, 3-week-vacation staleness replays, churn/leaks, isolation, disposability-under-violence, offline, download economics, an Apple Silicon gate).

Evidence. Eleven measured experiments (A–G, H-B/C/D, 2026-07-11/12) on real builds of this repo, plus web research (big-repo prior art, the Rails way, instant-DB-fork state of the art). Headlines: seeded-DB fork serves in 0.85s; full sandbox create ~4s; 15-cycle churn flat at ~0.8s with zero leaks; kill-9-mid-write → pristine re-fork in 785ms; real level pages 200 with working JS in ~16s; incremental catch-up reseed 1m22s; frontend HMR 53–67ms; vite+rails integration viable in one sandbox (~1GB vs 6.5–14GB for the legacy apps webpack loop). The proven Dockerfiles/entrypoints/shims from the experiments are committed under references/.

Also found and folded in as Phase-0 tasks (each independently shippable): the Spring/mutex_m conflict makes every single test pay ~44s of boot (largest single Rails DevEx lever — warm Spring measured 0.79s); a seed whole-input hash guard cuts a no-op seed:default from ~75s to ~13s; two live bugs (Zeitwerk Cdo::Aws shadowing ::Aws breaks dev db:migrate at staging tip; analytics_exportable.rake makes a live Secrets Manager call on every dev migrate); and the repo has no root .dockerignore.

Links

• Jira:
• Research comparison report (big-repo prior art): https://claude.ai/code/artifact/16af7400-b031-4610-a257-14c883487615
• Change directory: openspec/changes/golden-fork-devcontainers/ (proposal, design with 10 decisions + recommendations on remaining open questions, 6 specs, 27 tasks, references/)

Testing story

Docs-only PR; openspec validate golden-fork-devcontainers passes. The claims in the design are backed by the experiments described above; the devex-verification spec defines how they stay true (CI-gated budgets) once implemented.

🤖 Generated with Claude Code