space-architect 2.0.0.rc1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3022f9e726e74aa3edeca3004af6e3af1a7872bd709fb0da75fbeee5fcf33d30
-  data.tar.gz: f3f2aef35926a99ba14209c550fb0533da777561df7348d4e0bfce19ee240f86
+  metadata.gz: a5828b73d6d58a9d14547e9d8be9e7f8a734212c7e7356a01149c4c9cbeadd9c
+  data.tar.gz: a8c75e611270a1ff40f0cfd55753549d6972ae2d6af4999695b688f35942bb88
 SHA512:
-  metadata.gz: 480cd0f4dbb96653f6c4db809755e8968cf4bb96311472dde9a2e5172d22526589d20ca522bd028180eac6d2c772e41e80236474da9f8ab2b4597128227be21b
-  data.tar.gz: 7089e119fe3a0b7bee92facd78dd691ddcf84daae4dc783dda80c2513042ab1d1e1767b5afd099012dd4029c9e0a126c8ea3f7c5b48fe3d056bc8a7b7c7a03a8
+  metadata.gz: a9ff6975fce076eb36bfcd398129551182662830c1f433dfd3d57c375fa32d0ed8b547c46aca5d3959742a454c7523335109ab3ef5d406c8bd5ea6221797b8f4
+  data.tar.gz: 9f20d1e71cc27260fa7e8f1c3090c95b670ae9edea2d9394510e18ddfb6d9543c15655a2ecc2532cd3ba73e4f0250b24a55e00b838b475d64d9331f518d197dd

data/CHANGELOG.md

@@ -5,62 +5,258 @@ 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.0] - 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.
+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
 

data/README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/space-architect.svg)](https://badge.fury.io/rb/space-architect)
 
-> **Task-scoped workspaces that double as Architect Loop missions — for humans and their agents!** ✨🛰️
+> **Task-scoped workspaces that double as Architect Loop projects — for humans and their agents!** ✨🛰️
 
 `space-architect` is a Ruby toolkit for **spaces** — task-scoped project
 workspaces that hold repos, notes, and artifacts under one obvious filesystem
@@ -13,12 +13,12 @@ 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` |
 
 Each is a first-class executable. `architect` also forwards `architect space …`
-and `architect src …` to the other two, so a mission can drive everything from
+and `architect src …` to the other two, so a project can drive everything from
 one command when that's handier. 🎀
 
 ## What's a space? 🪐
@@ -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 🌌
@@ -116,7 +121,61 @@ comma form (`-r a,b`) works too. Space ids are date-prefixed
 same day get a counter (`…-name-of-space-2`). 📅
 
 Everything `space` does is also reachable as `architect space …` from within a
-mission.
+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 🌲
 
@@ -149,24 +208,31 @@ fish integration (`src shell fish install`).
 ## `architect` — the Architect Loop 🏗️
 
 The **Architect Loop** is a structured build cycle for you and headless AI
-builders. Each loop lives inside a space as a *mission*.
+builders. Each loop lives inside a space as a *project*.
 
 **Roles:**
 
-- **Architect** — you (or Claude Opus 4.8 in judgment mode): arbitrates
-  disagreements, writes and freezes iteration files, calls kill/continue, merges
-  builder output. Never writes implementation code.
-- **Builder** — Claude Sonnet 4.6 run headless via `architect dispatch`, one per
-  lane in its own git worktree: reads the iteration's Builder Prompt, does the
-  work, writes raw evidence to `build/<id>-<lane>/report.md`. Never grades its
-  own work; never edits `architecture/`.
+- **Architect** — the judgment role: a strong reasoning model (or you), run
+  interactively. Arbitrates disagreements, writes and freezes iteration files,
+  calls kill/continue, merges builder output. Never writes implementation code.
+- **Builder** — the execution role: a cheaper model run headless via `architect
+  dispatch`, one per lane in its own git worktree. Reads the iteration's Builder
+  Prompt, does the work, writes raw evidence to `build/<id>-<lane>/report.md`.
+  Never grades its own work; never edits `architecture/`.
+
+The loop is **model-agnostic** — which models fill the two roles is your choice
+(e.g. a strong Claude model judging a cheaper one on the same plan, or a
+cross-vendor pairing for more independent review). Set it per dispatch with
+`architect dispatch --model …`, or run several pairings head-to-head as a
+**variant set** (`architect variant add`). See
+[docs/DESIGN.md](docs/DESIGN.md) §1–§2 for the reasoning.
 
 **Filesystem layout:**
 
 ```text
 architecture/
-  ARCHITECT.md              # cross-iteration index; mission-wide state
-  BRIEF.md                  # durable §-numbered mission contract (optional)
+  ARCHITECT.md              # cross-iteration index; project-wide state
+  BRIEF.md                  # durable §-numbered project contract (optional)
   I01-<iteration>.md        # one self-contained file per iteration
 build/
   I01-<iteration>-<lane>/   # lane worktree + scratch per dispatch
@@ -193,11 +259,17 @@ prints the frozen Acceptance Criteria back. Any change to those sections
 afterward is an automatic iteration FAIL. The builder never edits the iteration
 file.
 
+**Re-grounding 🧭** — `architect init` also scaffolds a `SessionStart` hook that
+runs `architect ground` (emitting `ARCHITECT.md`, `BRIEF.md`, and the in-flight
+iteration) so every fresh session starts oriented — the loop leans on
+fresh-session judgment, and this is what makes picking up cold cheap. Builders
+inside a lane worktree are never grounded.
+
 **Command surface:**
 
 ```sh
-architect init                              # scaffold ARCHITECT.md + the space.yaml architect: block
-architect brief new                         # scaffold the durable mission BRIEF.md
+architect init                              # scaffold ARCHITECT.md + the space.yaml project: block + SessionStart hook
+architect brief new                         # scaffold the durable project BRIEF.md
 architect new <iteration>                   # scaffold architecture/I<NN>-<iteration>.md
 architect section <it> <section> --from <f> # write + commit a section
 architect freeze <iteration>                # freeze the Acceptance Criteria ❄️
@@ -208,7 +280,8 @@ architect evidence <it> --lane <lane>       # transcribe the builder's report ve
 architect gate <iteration>                  # run the frozen gate commands, stream raw output
 architect merge <it> <lane>                 # integrate ONE judged-passing lane (--no-ff)
 architect integrate <it> --lanes a,b        # integrate a set of passing lanes, in order
-architect status                            # mission state (read-only)
+architect land                              # end-of-project PR command (no push, no gh)
+architect status                            # project state (read-only)
 architect variant add|compare|promote …     # competing (harness, model) lanes over one frozen spec
 architect research dispatch|status|wait …   # parallel read-only research lanes (see below)
 ```
@@ -225,6 +298,8 @@ architect verify my-feature                      # mechanical post-flight checks
 architect evidence my-feature --lane lane-a      # transcribe raw evidence
 architect gate my-feature                        # run the frozen gates yourself
 # … read the diff against the spec, then write the Verdict …
+architect integrate my-feature --lanes lane-a    # merge passing lanes → project/<slug>
+architect land                                   # print gh pr create at project end
 ```
 
 ### Streaming builder output 📡
@@ -346,7 +421,7 @@ The library is split into three namespaces you can require independently:
 
 - **`Space::Core`** — the foundation: config, state, XDG, terminal, git/mise
   clients, the space store. The `space` CLI runs on this alone.
-- **`Space::Architect`** — mission state, the builder harness, dispatch, and the
+- **`Space::Architect`** — project state, the builder harness, dispatch, and the
   research supervisor.
 - **`Space::Src`** — the evergreen engine (tracking, sync, copy-on-write clone).
 
@@ -359,7 +434,7 @@ require "space_src"        # just the evergreen engine
 ## Documentation 📖
 
 - **[Command Reference](docs/reference.md)** — every command, flag, and behavior
-- **[Design](docs/design.md)** — why spaces and the Architect Loop exist, and how they're shaped
+- **[Design](docs/DESIGN.md)** — the source-backed rationale: the twelve invariant rules (R1–R12), the failure-mode → mitigation table, and why the loop is shaped this way
 - **[Changelog](CHANGELOG.md)** — release history
 
 ## Development 🛠️