space-architect 2.0.0.rc2 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bec4cc0a199a23ba60c9efd070163098e43a0a76bd8d2f85fbdbe4f7c7a6077
-  data.tar.gz: cc8a23d0ee170242104ef94f020abdb5ed58b8aa4e7c34c97edad42b9cf61433
+  metadata.gz: 4ded62e199397e162bba1ff6ee37a5c6a9c7ee83a446d154107036aa4d628768
+  data.tar.gz: 592a6bb0c3b10b2773873e7fc3fd79cf7197bad78ada5520c5c9dc77e60aae2f
 SHA512:
-  metadata.gz: 0564b3f3909ae233a788950f795afd6fbb3e2edc57ed87b8186cfdb2255d3380e66b140d7f217616ac5f63f9410f04b9f944ede1b06166bd60278429e0550f57
-  data.tar.gz: 1b9f709c3ff2dcb77237207fb9cffaad67983eb938f0fe8ee4fc36cc8c95a14acc72523b0c59ebed0c5147a4b792b41d487a21e80e6a11ba1d765f4db0719936
+  metadata.gz: 91b5a865cb40557085399853e723e7763c2a54cb183d95b9744f9886753579aa841309f3f2dc490d28a3ad10d4693db06cfb615a9716b2b13fe68ded86b932f6
+  data.tar.gz: 6ebb0c24e6e603252aab77da49ff2b904d22084e0c840f7d46d5ac0eb66ec7c315ec04816d6446dc537cac5b3dbc58c7663d8bbbb563443566cd6e84de5ee05a

data/CHANGELOG.md

@@ -5,62 +5,281 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.0.0] - 2026-06-27
+## [2.0.1] - 2026-07-01
 
-Re-architects the single `architect` gem into three composable binaries —
-**`space` · `architect` · `src`** — over clean `Space::Core` / `Space::Architect`
-/ `Space::Src` library seams. End-user CLI behaviour is preserved byte-for-byte
-except where called out under **Changed** below.
+Fast-follow completing the `pack.persist:` story from 2.0.0.
 
 ### Added
 
+- **Seed-on-empty for `pack.persist:`.** Content baked at a persisted path now
+  survives a first-run empty bind mount. `space pack` snapshots each persisted
+  dir to a `/opt/space-seed<path>` sidecar after provisioning, and the entrypoint
+  restores an empty mount from its seed on first run only (a non-empty mount
+  keeps its evolving state). Previously the empty host mount shadowed the baked
+  content — e.g. a provisioned `~/.hermes/config.yaml` was hidden once
+  `/root/.hermes` was persisted. Template-only; a space with no `pack.persist:`
+  renders an identical Dockerfile and entrypoint.
+
+### Fixed
+
+- **First-run boot on bind-mount-root-restricted runtimes.** The seed restore
+  tolerates a benign copy failure (`2>/dev/null || true`) so that on runtimes
+  where the persisted path is a bind mount whose root rejects utime updates
+  (virtiofs under Apple `container`), the entrypoint's `set -e` no longer turns a
+  cosmetic `cp` EPERM into a fatal abort before the payload execs.
+
+## [2.0.0] - 2026-07-01
+
+A ground-up release across four fronts:
+
+1. **Three composable binaries** — `space` · `architect` · `src` — over clean
+   `Space::Core` / `Space::Architect` / `Space::Src` library seams (retiring the
+   single `SpaceArchitect` namespace).
+2. **An overhauled Architect Loop** — the "mission" vocabulary becomes
+   "project," Acceptance Criteria gain a structured, runnable `gates` block, and
+   the loop grows first-class verbs (`gate`, `verdict`, `land`, `ground`), an
+   integration-branch-by-default workflow, and a SessionStart re-grounding hook.
+3. **Reproducible space containers** — `space pack` / `build` / `run` turn a
+   space into an OCI image.
+4. **`space-server`** — a new Hanami + React web app to import, view, and share
+   Architect spaces and AI-agent transcripts. **It ships in the repo, not in the
+   gem** (the gem packages only `lib/`, `exe/`, and `skill/`).
+
+This is a major, breaking release for both CLI users and library embedders — see
+the **BREAKING** items under Changed. The repository is now a monorepo; the
+`space-architect` gem lives at the root and the server under `server/`.
+
+### Added
+
+#### CLI — binaries, research, and dispatch
+
 - **`src` — standalone evergreen-engine binary** (`exe/src`). `repo`, `org`,
   `sync`, `status`, `config`, `daemon`, and `clone`, plus single-token fuzzy
   navigation (`src <query>` resolves to a repo and honours the `cd` contract)
-  and native fish shell integration with completions. Previously this engine was
-  reachable only as `architect src …`; it is now a first-class binary in its own
-  right (and still forwarded by `architect src …`).
+  and native fish shell integration with completions. Previously reachable only
+  as `architect src …`; now a first-class binary (and still forwarded by
+  `architect src …`).
 - **`architect research dispatch | status | wait`** — first-class parallel,
-  read-only research lanes. Detached `claude -p` researchers (no Edit/Write/Bash)
-  run in the background; a socketry/async fiber mux tails each lane's `run.jsonl`
-  and extracts its report. The architect verifies claims and writes Grounds.
+  read-only research lanes. Detached `claude -p` researchers restricted to
+  `Read,Grep,Glob,WebSearch,WebFetch` (no Edit/Write/Bash) run in the background;
+  a socketry/async fiber mux tails each lane's `run.jsonl` and extracts its
+  report. The architect verifies claims and writes Grounds.
 - **`architect dispatch --detach`** — detached builder launch that returns
   immediately with a PID and survives the harness wall-clock reap; poll the
   lane's report for completion.
+- **`architect dispatch` HTTP push** — stream a builder's live output to an
+  ingest server. `--push-url <url> --push-token <tok>` POSTs the NDJSON stream to
+  an existing run's ingest URL; `--push-host <host> --push-token <tok>` first
+  creates the run (`POST <host>/runs`), derives `<host>/runs/<id>/ingest`, streams
+  there, and prints the run id. `--push-url`/`--push-host` are mutually exclusive,
+  both require `--push-token` (Bearer auth), and neither combines with `--detach`.
+  The stream is teed to the run log and the endpoint concurrently over fibers.
+- **`architect dispatch --timeout`** — wall-clock timeout for a builder (default
+  `14400`s / 4h; `0` disables; foreground only). A wedged builder's process group
+  is escalated TERM→grace→KILL and reported as timed out (exit 124).
+
+#### Architect Loop — gates and new verbs
+
+- **A fenced ` ```gates ` block inside each iteration's Acceptance Criteria.**
+  Runnable checks are now structured YAML gates — `id`, `ac` (which prose AC it
+  backs), `cmd`, optional `cwd`, an `expect` block (`exit_code` / `stdout_match`
+  / `threshold`), and an optional per-gate `timeout` (seconds; default 900),
+  replacing the old free-text AC table.
+- **Gate linting at freeze time** (`GateLint`, via dry-validation). `architect
+  freeze` validates the gates block: malformed gates fail the freeze; absent or
+  empty gates warn but are allowed (prose-judged iterations); duplicate ids, bad
+  threshold operators, and non-single-capture regexes are caught.
+- **`architect gate` — a gate runner.** Runs the frozen Acceptance-Criteria gate
+  commands (always read from the freeze commit, never the working copy) in the
+  resolved repo or lane worktree, scoring captured output against each `expect`
+  block with a pure `GateEvaluator`.
+- **`architect verdict <iteration> continue|kill`** — records the decision in the
+  `project:` block and writes the `## Verdict` prose in one commit; the first tool
+  that actually persists a verdict decision.
+- **`architect land`** — generates the end-of-project PR for each integrated repo
+  (writes a `build/land/<repo>-pr-body.md` and prints the `gh pr create …`
+  invocation). Side-effect-free: no git write, no push, no `gh` call.
+- **`architect ground` + a SessionStart re-grounding hook.** `architect init`
+  now also writes `.claude/settings.json` registering SessionStart hooks
+  (startup/clear/resume) that run `architect ground`, re-emitting `ARCHITECT.md`,
+  `BRIEF.md`, and the in-flight iteration file so a freshly cleared or resumed
+  session self-orients. A worktree guard suppresses grounding inside builder
+  worktrees, so builders are never fed architect context.
+
+#### Space containers (require a `container` / OCI runtime)
+
+- **`space pack`** — generate a portable OCI build context for the current space
+  (writes `Dockerfile`, `entrypoint.sh`, and a `.dockerignore` into `build/oci/`,
+  overridable with `-o/--output`) and print a build hint.
+- **`space build`** — pack, then `container build`, tagging reproducibly by commit
+  as `<space-id>:<git-short-sha>` plus `<space-id>:latest` (SHA suffixed `-dirty`
+  when the tree is dirty).
+- **`space run`** — `container run --rm` on `<space-id>:latest`, defaulting to an
+  interactive login shell or a passed command, auto-detecting TTY (`--tty` to
+  force). Forwards `ANTHROPIC_API_KEY` / `CLAUDE_CODE_OAUTH_TOKEN` /
+  `ANTHROPIC_BASE_URL` from the host only if set — credentials are never baked
+  into a layer. (All three commands are also reachable as `architect space …`.)
+- **Declarative `pack:` config in `space.yaml`.** `pack.provision` — build-time
+  provisioning scripts (space-relative) emitted as ordered `RUN` steps;
+  `pack.persist` — absolute guest paths bind-mounted from `.state/<guest>` so
+  state survives across runs. Provision paths are validated (must exist, be
+  relative, and stay within the space root).
+- **Git baked into the image + in-container worktrees.** The image copies the
+  whole space tree (repos and history) into `/space`, installs the pinned
+  in-space `space-architect`, seeds a default git identity, and sets `git
+  safe.directory '*'` so `git worktree` works on the root-owned tree.
+
+#### `space-server` (repo, not shipped in the gem)
+
+- **A Hanami web app to view and share Architect work** (`server/`). Imports an
+  Architect space and renders its iterations against the canonical six-section
+  shape (Grounds · Specification · Acceptance Criteria · Builder Prompt · Builder
+  Report · Verdict), alongside that space's runs and artifacts; separately ingests
+  exported AI chat transcripts (Claude Code, Codex, pi, opencode) for markdown/code
+  browsing, per-turn annotation, and read-only public sharing.
+- **Architect-space data model + `SpaceImporter`.** New `spaces` / `iterations` /
+  `artifacts` tables and a `rake space:import[/path]` task that reads a space's
+  `space.yaml`, markdown artifacts, and builder run streams (`build/*/run.jsonl`)
+  into Postgres — idempotent, keyed by slug/ordinal/path.
+- **A stitched per-space read view (Inertia/React).** `Spaces/Index` and
+  `Spaces/Show` interleave iterations and architect sessions into one
+  timestamp-ordered timeline with inline transcript cards and run/artifact
+  drill-downs; imported timestamps are timezone-faithful and each run carries a
+  `harness · model` badge.
+- **Live agent-run streaming.** Machine clients push run events over Bearer token
+  auth; browsers replay them live over SSE. Pairs with the CLI's
+  `architect dispatch --push-*`.
+- **Session normalizers for architect transcripts.** `Normalizer::ClaudeSession`
+  understands Claude Code's `~/.claude/projects/**.jsonl` session-log shape and
+  `Normalizer::OpencodeSession` reads opencode's SQLite DB read-only, both
+  emitting the same normalized event stream as the builder-dispatch parser.
+- **Five in-tree Hanami extension gems** under `server/gems/*` (each path-loaded,
+  with its own gemspec and tests): `hanami-healthcheck` (a `/up` endpoint),
+  `inertia-hanami` (an Inertia.js protocol adapter), `hanami-credentials`
+  (encrypted credentials store), `hanami-force-ssl` (Rack 3 HTTPS/HSTS
+  middleware), and `vite-hanami` (Vite tag helpers + dev-server proxy).
 
 ### Changed
 
-- **BREAKING — three binaries over clean seams.** `space` now runs on
-  `Space::Core` alone (`exe/space`); `architect` forwards `space …` / `src …` to
-  their surfaces; `src` is its own executable (`exe/src`). The gem now installs
-  three executables (`architect`, `space`, `src`) where 1.3.0 installed two.
+- **BREAKING — three binaries over clean seams.** `space` runs on `Space::Core`
+  alone (`exe/space`); `architect` (`exe/architect`) forwards `space …` / `src …`
+  to their surfaces; `src` is its own executable. The gem now installs three
+  executables where 1.3.0 installed two.
 - **BREAKING — Ruby namespace overhaul (library embedders).** The single
   `SpaceArchitect::*` module is retired and split into `Space::Core::*`
-  (foundation: config, state, XDG, terminal, git/mise clients, space store),
-  `Space::Architect::*` (mission, harness, dispatch, research), and
-  `Space::Src::*` (the evergreen engine). Update any `require`s and constant
-  references. The CLI surface is unaffected.
+  (config, state, XDG, terminal, git/mise clients, space store),
+  `Space::Architect::*` (project, harness, dispatch, research), and
+  `Space::Src::*` (the evergreen engine). No `SpaceArchitect` constant remains —
+  update any `require`s and constant references. The CLI surface is unaffected.
+- **BREAKING — "mission" is now "project," with no back-compat shim.** The
+  `space.yaml` project-state key `architect:` becomes `project:`; existing spaces
+  are not read until the key is renamed. The core class `ArchitectMission` becomes
+  `ArchitectProject`, all user-facing output follows (`Project ready:` /
+  `Project status:`), and the default integration branch is `project/<slug>`.
+  No deprecation alias is provided.
 - **BREAKING — `repo-tender` absorbed into `space-src`.** The vendored
-  `repo-tender` engine is gone; its functionality now ships as `Space::Src`.
-  State migrates automatically from `$XDG_STATE_HOME/repo-tender/` to
-  `$XDG_STATE_HOME/space-src/` on first run (data-preserving).
-- **BREAKING — `space new` takes repeatable `-r` flags.** Repos are now passed
-  as `space new "My Space" -r org/repo -r example/alpha` instead of as positional
-  arguments after the title. Repeated `-r` accumulate; the comma form still works.
-- **Colourful global help** for `space` and `architect` (`--help` listing), with
-  global colour options (`--color` / `--colors`) inherited by every command via a
-  shared `BaseCommand`. The `src` binary keeps its own `--plain` / `--json`
-  output system.
-- `space --version` now reports the space-surface (`Space::Core`) version
-  independently of the architect mission tooling.
+  `repo-tender` engine is gone; its functionality now ships as `Space::Src`. State
+  migrates automatically from `$XDG_STATE_HOME/repo-tender/` to
+  `$XDG_STATE_HOME/space-src/` (and the launchd label likewise) on first run,
+  data-preserving.
+- **BREAKING — `space new` takes repeatable `-r` flags.** Repos are passed as
+  `space new "My Space" -r org/repo -r example/alpha` instead of as trailing
+  positional arguments. Repeated `-r` accumulate; the comma form still works.
+- **Acceptance Criteria are prose (AC1, AC2, …) plus the gates block, not a
+  `| AC# | Command | Threshold |` table.** The prose is what the architect judges
+  against; gates are the necessary-not-sufficient mechanical check.
+- **`architect new` allocates the ordinal at spec-time.** The `I<NN>` number is
+  assigned by `new`, not pre-numbered; `ARCHITECT.md` gains an un-numbered ordered
+  **Backlog** so reshuffling priorities no longer forces renumber churn.
+- **Integration branch by default.** Lanes merge `--no-ff` into one shared,
+  stable `project/<slug>` branch instead of into `main` or per-iteration branches;
+  the end-of-project PR is deferred to `architect land`. Merge conflicts abort
+  cleanly and are treated as a lane-plan disjointness defect.
+- **`architect gate` reports PASS/FAIL per gate and exits nonzero on any
+  failure** (it began as a raw-output-only runner) — while the framing keeps the
+  Acceptance-Criteria verdict with the architect, not the runner.
+- **Post-flight moved out of the dispatching session.** The dispatch session now
+  only babysits builders to completion and hands off; a fresh judging session owns
+  post-flight checks, gates, verdict, and integration. Two first-class lane
+  patterns are documented: **parallel + fast-follow** and **serial deferred
+  judgment**.
+- **`architect status` tells the truth about verdicts** — rendering
+  `awaiting-verdict` for integrated-but-unjudged iterations and the recorded
+  `continue`/`kill`, instead of a freeze/lane placeholder.
+- **The loop is model-agnostic.** `dispatch --model` help clarifies any
+  provider/tier is fine (pin a full id, not a floating alias); the probe/spike is
+  documented as a first-class iteration type; `docs/DESIGN.md` was revived.
+- **Builder streams now include partial messages.** The claude harness argv gained
+  `--include-partial-messages`, so `run.jsonl` (and any HTTP push) carries
+  streaming partial-message events, not just completed turns — consumers should
+  expect the finer-grained shape.
+- **Colourful global help** for `space` and `architect`, with global colour
+  options `--color` (auto/always/never) and its `--colors` alias inherited by
+  every command via a shared `BaseCommand`. `src` keeps its own `--plain` /
+  `--json` system.
+- **`space --version`** now reports the space-surface (`Space::Core`) version
+  independently of the architect project tooling.
+- **The repository is now a monorepo.** The gem keeps the root (`lib/`, `exe/`,
+  `skill/`, `space-architect.gemspec`); the `space-server` app lives under
+  `server/`. Gem consumers are unaffected — `server/` is never packaged.
+
+### Removed
+
+- **The `architect:` `space.yaml` key and the `ArchitectMission` class** —
+  renamed to `project:` / `ArchitectProject` with no alias (BREAKING; see above).
+- **The Acceptance-Criteria command/threshold markdown table** — replaced by
+  prose ACs plus the fenced `gates` block.
+- **The post-flight phase in the dispatching session** — that work now belongs to
+  a fresh judging session.
+
+### Fixed
+
+- **Gate thresholds matched the first occurrence instead of the last.**
+  `GateEvaluator#check_threshold` now takes the last regex match, repairing frozen
+  `(\d+) runs`-style suite-green gates without editing the frozen AC.
+- **A frozen per-gate `cwd` ran against the checked-out repo instead of the lane
+  worktree.** `run_gates` now re-roots a `cwd` pointing into the lane's repo onto
+  the lane worktree.
+- **`architect verify` false-FAILed "no builder commits" after integration.** The
+  architect's own `integrate` commit was miscounted; `merge_lane!` now records
+  `integrate_sha` and the mechanical checks exclude exactly that SHA.
+- **A missing `touch_set` rendered a silent `N/A`.** Bounds now render
+  `WARN — no touch_set recorded`, distinguishing "unchecked" from "clean."
+- **Bounds glob matching was unsafe.** `fnmatch` now uses
+  `FNM_PATHNAME | FNM_EXTGLOB` and parses NUL-delimited `git status --porcelain
+  -z`, so `*` no longer crosses `/`, `**` works, and renames/spaced paths are
+  handled.
+- **HTTP push is now best-effort and isolated.** If the ingest server's transport
+  fails or a push write errors mid-stream, `dispatch` logs a one-line warning and
+  keeps the run log intact rather than tearing down the builder; a failed push
+  disables further pushes for that run without dropping log output.
+- **Container login-shell PATH and git identity.** The image writes
+  `/etc/profile.d/space-architect.sh` so `bash --login` finds `architect` /
+  `space` / `claude`, and the entrypoint seeds `user.name` / `user.email` if
+  unset so in-image commits and worktrees no longer fail on a missing identity.
+- **The gate evaluator lacked a discriminating threshold test** — added one that
+  genuinely separates pass from fail, closing a hole where a broken evaluator
+  could still pass its own suite.
 
 ### Internal
 
-- `Space::Core` carved out as a standalone, leak-free foundation (no
-  `SpaceArchitect` references); behaviour preserved byte-for-byte across the
-  carve, the module rename, and the binary split.
-- CI: `softprops/action-gh-release` bumped to v3 (Node 24 runtime).
-- Test suite: 762 runs, 0 failures.
+- **`Space::Core` carved out as a standalone, leak-free foundation** (no
+  `SpaceArchitect` references), with behaviour preserved across the carve, the
+  module rename, and the binary split.
+- **New runtime dependencies:** `async-http ~> 0.95` and `protocol-http ~> 0.62`
+  (backing the HTTP push tee and the research mux).
+- **Split, per-subtree CI.** The gem keeps a lean workflow (Ruby tests +
+  bundler-audit); a separate `server-ci.yml` runs the server suite against
+  Postgres 17 / Redis 7 service containers, a Node 24 frontend job, a matrix that
+  tests all five `server/gems/*` independently, and a server bundler-audit.
+  Toolchain is pinned via `mise.toml` (Ruby 4.0.5) at both the root and `server/`.
+- **CI bumps:** `softprops/action-gh-release` v2 → v3 (Node 24 runtime),
+  `actions/cache` 5 → 6, `actions/checkout` 5 → 7, `actions/setup-node` 5 → 6,
+  and `shrine` 3.8.0 (server).
+- **Prerelease-aware release pipeline.** `release.yml` marks rc/beta/alpha/pre
+  tags as GitHub prereleases so an RC tag is not published as `latest`; `2.0.0.rc1`
+  and `2.0.0.rc2` were cut ahead of this final.
+- Gem test suite: 948 runs, 3611 assertions, 0 failures, 0 errors, 0 skips.
 
 ## [1.3.0] - 2026-06-25
 
@@ -97,6 +316,7 @@ except where called out under **Changed** below.
   lanes, worktrees, and headless `claude -p` dispatch, with variant sets and the
   claude-code and opencode harnesses.
 
+[2.0.1]: https://github.com/jetpks/space-architect/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/jetpks/space-architect/compare/v1.3.0...v2.0.0
 [1.3.0]: https://github.com/jetpks/space-architect/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/jetpks/space-architect/compare/v1.1.0...v1.2.0

data/README.md

@@ -13,7 +13,7 @@ The gem ships **three composable binaries** over clean library seams:
 
 | Binary | What it does | Library |
 |--------|--------------|---------|
-| **`space`** 🪐 | Create and manage task-scoped workspaces | `Space::Core` |
+| **`space`** 🪐 | Create, manage & containerize task-scoped workspaces | `Space::Core` |
 | **`architect`** 🏗️ | Run the Architect Loop — judgment + headless builders | `Space::Architect` |
 | **`src`** 🌲 | Tend evergreen repo checkouts for copy-on-write provisioning | `Space::Src` |
 
@@ -84,6 +84,11 @@ architect init                                    # scaffold ARCHITECT.md + arch
 architect new my-feature                          # scaffold the next iteration file
 architect freeze my-feature                       # lock the Acceptance Criteria ❄️
 architect dispatch my-feature lane-a              # send a headless builder to work
+
+# Containers (run from inside a space) — a portable, reproducible-by-SHA image of the space
+space pack                                         # render build/oci/ (Dockerfile + entrypoint)
+space build                                        # pack + build & tag <space-id>:<git-sha>
+space run                                          # run it — login shell, auth from your env
 ```
 
 ## `space` — task-scoped workspaces 🌌
@@ -118,6 +123,60 @@ same day get a counter (`…-name-of-space-2`). 📅
 Everything `space` does is also reachable as `architect space …` from within a
 project.
 
+## Containerize a space: `pack` · `build` · `run` 📦
+
+A space is self-describing enough to become a container. `space pack` renders a
+portable OCI build context from the space; `space build` packs and builds it into
+a **reproducible-by-SHA** image; `space run` runs that image with your auth
+injected at runtime and stateful paths bind-mounted back to the host. 🐳
+
+```sh
+space pack                    # render build/oci/ (Dockerfile + entrypoint + ignore file)
+space pack -o /tmp/ctx        # …to a different output directory
+space build                   # pack, then build & tag <space-id>:<git-sha> and :latest
+space run                     # run <space-id>:latest — login shell, auth from your env
+space run architect status    # …or run a one-off command instead of the login shell
+space run --tty               # force an interactive TTY (default: auto-detect)
+```
+
+**What lands in the image.** The context copies the whole space tree (filtered by
+a generated `Dockerfile.dockerignore`) onto a `ruby:4.0.5` base with `git`, the
+Claude Code CLI, and the `space-architect` gem — installed from the in-space
+`repos/space-architect` checkout when present (a pinned build), else from
+RubyGems. Secrets never enter the layers: `.env`, `*.key`, `*.pem`, ssh keys,
+`build/`, and `tmp/` are all excluded by the generated ignore file. 🔒
+
+**Reproducible by SHA.** `space build` tags the image `<space-id>:<sha>`, where
+`<sha>` is the space repo's 12-char `HEAD` (suffixed `-dirty` when the tree has
+uncommitted changes), plus a moving `:latest`. Same commit → same tag → same
+image. It drives the `container` CLI, but the output is an ordinary OCI/Docker
+build context, so `docker build -f build/oci/Dockerfile .` (from the space root)
+works just as well.
+
+**Auth stays out of the layers.** `space run` injects only the auth environment
+variables that are actually set — `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`,
+`ANTHROPIC_BASE_URL` — with `-e` at run time, so credentials live in your shell,
+never in the image. 🗝️
+
+**Declaring provisioning & persistence** — two optional keys in `space.yaml`:
+
+```yaml
+pack:
+  provision:                 # build-time: relative scripts, baked in by `space build`
+    - scripts/setup-toolchain.sh
+  persist:                   # run-time: absolute guest paths, bind-mounted per run
+    - /root/.claude
+    - /root/.local/state
+```
+
+`provision` scripts must live under the space root and run as `RUN /space/<script>`
+while the image builds. `persist` paths must be absolute; `space run` bind-mounts
+each one from `<space>/.state<path>` on the host (created on first run) so a
+container's mutable state survives across runs. Both are validated at pack time.
+
+Like everything else, these are reachable as `architect space pack|build|run`
+from inside a project.
+
 ## `src` — the evergreen engine 🌲
 
 `src` keeps local clones under `<src_dir>/<host>/<owner>/<repo>` (default

data/lib/space_core/templates/oci/dockerfile.erb

@@ -56,6 +56,13 @@ RUN printf 'export PATH="/usr/local/bundle/bin:/root/.local/bin:$PATH"\n' \
 RUN /space/<%= script %>
 <% end -%>
 <% end -%>
+<% if persist_paths.any? -%>
+
+# Seed snapshot: capture baked content of persisted dirs so a first-run (empty) mount is seeded from it
+<% persist_paths.each do |guest_path| -%>
+RUN mkdir -p "/opt/space-seed<%= guest_path %>" && cp -a "<%= guest_path %>/." "/opt/space-seed<%= guest_path %>/" 2>/dev/null || true
+<% end -%>
+<% end -%>
 
 WORKDIR /space
 

data/lib/space_core/templates/oci/entrypoint.sh.erb

@@ -3,6 +3,12 @@ set -e
 git config --global --add safe.directory '*'
 git config --global --get user.name >/dev/null 2>&1 || git config --global user.name 'space-architect'
 git config --global --get user.email >/dev/null 2>&1 || git config --global user.email 'architect@localhost'
+<% persist_paths.each do |guest_path| -%>
+if [ -d "/opt/space-seed<%= guest_path %>" ] && [ -z "$(ls -A "<%= guest_path %>" 2>/dev/null)" ]; then
+  mkdir -p "<%= guest_path %>"
+  cp -a "/opt/space-seed<%= guest_path %>/." "<%= guest_path %>/" 2>/dev/null || true
+fi
+<% end -%>
 if [ "$#" -eq 0 ]; then
   exec bash --login
 else

data/lib/space_core/version.rb

@@ -2,6 +2,6 @@
 
 module Space
   module Core
-    VERSION = "2.0.0.rc2"
+    VERSION = "2.0.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: space-architect
 version: !ruby/object:Gem::Version
-  version: 2.0.0.rc2
+  version: 2.0.1
 platform: ruby
 authors:
 - Eric Jacobs