space-architect 2.0.0.rc1 → 2.0.0.rc2

data/skill/architect/dispatch.md

@@ -1,12 +1,13 @@
 # Builder dispatch reference
 
-Verified against the `claude` CLI (Claude Code) headless mode, June 2026. The
-builder is `claude -p` (`--print`, the non-interactive headless mode) pinned to
-`claude-sonnet-4-6` — the *same binary the architect runs, one tier down*. Key
-facts the skill encodes: lane-prompts go in on **stdin** (Claude Code has no
-`@file`, and a big quoted lane-prompt as a shell argument gets mangled); the
-model is pinned with `--model claude-sonnet-4-6` (the `sonnet` alias floats to
-the latest Sonnet — pin the full id); there is **no `-C`/working-dir flag**, so
+Verified against the `claude` CLI (Claude Code) headless mode — the reference
+harness — June 2026. The builder is `claude -p` (`--print`, the non-interactive
+headless mode) pinned to the configured builder model (`<builder-model>`) — a
+cheaper model run headless via the same harness the architect uses. Key facts the
+skill encodes: lane-prompts go in on **stdin** (Claude Code has no `@file`, and a
+big quoted lane-prompt as a shell argument gets mangled); the model is pinned with
+`--model <builder-model>` (a floating alias drifts to whatever ships next — pin
+the full id); there is **no `-C`/working-dir flag**, so
 per-lane dispatch `cd`s into the worktree; permissions are the **tool
 allow/deny lists** (`--allowedTools`/`--disallowedTools`) plus
 `--permission-mode`, not a sandbox; web access is the built-in
@@ -27,21 +28,22 @@ If a lane committed, treat the worktree as tampered: reset and re-dispatch.
 
 **Preflight (once per environment):** run `claude --version`, and confirm the
 builder model resolves with a one-shot canary
-(`echo ok | claude -p --model claude-sonnet-4-6 --max-turns 1`). No API key —
+(`echo ok | claude -p --model <builder-model> --max-turns 1`). No API key —
 the builder runs on your Claude plan — but note headless `claude -p` draws on
 the Agent SDK credit pool (separate from interactive usage since June 15 2026;
-see `DESIGN.md` §4). On the first real dispatch in a new environment, launch
+see `docs/DESIGN.md` §4). On the first real dispatch in a new environment, launch
 ONE canary lane and confirm it starts cleanly before fanning anything out.
 
 ## Canonical dispatch — `architect dispatch <iteration> <lane>`
 
 The canonical path is `architect dispatch <iteration> <lane>`. The tool
-assembles the canonical `claude -p` argv, pins the model to `claude-sonnet-4-6`,
+assembles the canonical `claude -p` argv, pins the builder model (the lane's
+configured model or the CLI's reference default; see `docs/DESIGN.md` §4),
 reads the lane prompt from `build/<id>-<lane>/prompt.md` on stdin, and streams
 `--output-format stream-json --verbose` output to
 `build/<id>-<lane>/run.jsonl`. Run each lane as its own **background Bash tool
-call** (`run_in_background`) so your turn doesn't block for the full multi-hour
-run.
+call** (`run_in_background`) so your turn doesn't block for the full run (30–60
+minutes is typical).
 
 Write the lane's prompt to `build/<id>-<lane>/prompt.md` first (never pass a
 big prompt as a shell argument — shells mangle quotes), then:
@@ -72,7 +74,7 @@ reaps those now-orphaned `claude` processes, and every lane dies at once with no
 `result` — partial diffs, no reports (this exact failure has happened: three
 lanes killed at the same second, zero output). One blocking dispatch per
 background Bash tool keeps each lane attached to a harness-tracked task that
-survives the full multi-hour run and reports completion per lane.
+survives the full run and reports completion per lane.
 
 ### What the tool runs under the hood
 
@@ -82,7 +84,7 @@ and as the manual fallback:
 ```bash
 # write prompt to build/<id>-<lane>/prompt.md first, then:
 ( cd build/<id>-<lane>/wt && \
-  claude -p --model claude-sonnet-4-6 \
+  claude -p --model <builder-model> \
     --permission-mode acceptEdits \
     --allowedTools 'Read,Edit,Write,Grep,Glob,Bash,WebSearch,WebFetch' \
     --disallowedTools 'Bash(git commit:*),Bash(git push:*),Bash(git reset:*),Bash(git merge:*),Bash(git rebase:*),Bash(git checkout:*),Bash(git branch:*)' \
@@ -100,48 +102,153 @@ over the allow list (deny always takes precedence) as the runtime first line
 against commits. Redirect stderr (`2>&1`) into the run-log so a dispatch error
 lands somewhere instead of vanishing.
 
-### Integration (architect-only, after per-lane post-flight passes)
+### Integration (judging session — after per-lane post-flight passes)
 
-You decide which lanes pass; the CLI does the git mechanics. Canonical path:
+This block runs in the judging session, not the dispatch session — the dispatch
+session's job ends when builders finish (see SKILL.md §5–6). You decide which
+lanes pass; the CLI does the git mechanics. Canonical path:
 
 ```bash
 architect integrate <iteration> --lanes <passing-set>   # e.g. --lanes lane-a,lane-b
 architect gate <iteration>                              # integration smoke (raw output; verdict stays yours)
 architect integrate <iteration> --lanes <passing-set> --teardown   # or remove worktrees + lane branches after
+architect land                                          # end of project: prints gh pr create --base main --head project/<slug>
 ```
 
 `architect integrate` commits each named lane on its branch and merges it
-`--no-ff` into the repo's `lane/<iteration>` integration branch, in order. It
-**refuses** a lane that left builder commits or wrote out-of-bounds (the
-mechanical post-flight checks), and aborts on a merge conflict. A merge conflict
-= the lane plan wasn't disjoint = a spec defect: kill the conflicting lane and
-re-spec; don't hand-resolve builder conflicts. It runs **no gates and makes no
-verdict** — `architect gate` streams the raw gate output for you to judge.
+`--no-ff` into the repo's stable `project/<slug>` branch (slug of `space.title`,
+persistent across all iterations), in order. It **refuses** a lane that left
+builder commits or wrote out-of-bounds (the mechanical post-flight checks), and
+aborts on a merge conflict. A merge conflict = the lane plan wasn't disjoint = a
+spec defect: kill the conflicting lane and re-spec; don't hand-resolve builder
+conflicts. It runs **no gates and makes no verdict** — `architect gate` streams
+the raw gate output for you to judge. `--teardown` deletes only the per-lane
+`lane/<iteration>-<lane>` branches and worktrees; it never deletes the
+`project/<slug>` branch.
 
 Under the hood / manual fallback (one lane shown):
 
 ```bash
-git -C repos/<repo> checkout -b lane/<iteration> <repo-base>
+# check out or create the project integration branch:
+git -C repos/<repo> checkout project/<slug> 2>/dev/null || \
+  git -C repos/<repo> checkout -b project/<slug> <repo-base>
 git -C build/<id>-<lane>/wt add -A
 git -C build/<id>-<lane>/wt commit -m "lane <lane>: <what>"
 git -C repos/<repo> merge --no-ff lane/<iteration>-<lane>
 <run the gate commands>          # integration smoke after every merge
 architect worktree remove <iteration> <lane>
 git -C repos/<repo> branch -d lane/<iteration>-<lane>
+# at project end:
+architect land                   # prints gh pr create --base main --head project/<slug>
 ```
 
+### Parallel + fast-follow
+
+Use when an iteration is near-disjoint — all but a thin shared seam (a
+registration line, an index entry, a shared require). Route the seam into a
+dedicated fast-follow lane; the parallel lanes stay genuinely disjoint and
+integrate without conflict.
+
+**Recipe:**
+
+1. **Spec the seam out of the parallel lanes.** Assign the seam file(s) to the
+   fast-follow lane's `--touch` set and exclude them from every parallel lane's
+   touch-set — so the parallel set is disjoint by construction.
+
+2. **Create worktrees and dispatch the parallel lanes** (off the repo base):
+   ```bash
+   architect worktree add <repo> <iteration> lane-a
+   architect worktree add <repo> <iteration> lane-b
+   architect dispatch <iteration> lane-a   # own background Bash call each
+   architect dispatch <iteration> lane-b
+   ```
+
+3. **Judging session — integrate the parallel set.** `project/<slug>` advances
+   to their merged tip:
+   ```bash
+   architect integrate <iteration> --lanes lane-a,lane-b
+   architect gate <iteration>
+   ```
+
+4. **Create the fast-follow lane off the integrated tip.** `--base` accepts any
+   git ref — passing `project/<slug>` roots the new worktree at the merged tip
+   (the keystone move):
+   ```bash
+   architect worktree add <repo> <iteration> ff --base project/<slug>
+   architect dispatch <iteration> ff
+   ```
+
+5. **Judging session — integrate the fast-follow lane.** Because it descends
+   directly from `project/<slug>`, the `--no-ff` merge appends cleanly with no
+   conflicts:
+   ```bash
+   architect integrate <iteration> --lanes ff
+   architect gate <iteration>
+   ```
+
+**Invariant:** the parallel lanes must stay disjoint — a conflict among them is
+still a disjointness defect (kill and re-spec; never hand-resolve). The
+fast-follow lane is the sanctioned home for the seam and never conflicts because
+it is a descendant of the integrated tip.
+
+### Serial deferred judgment
+
+Use when several iterations (or serial same-file lanes within one iteration)
+should run to gates-green without a judging session between each — batching cold
+AC judgment into one later session.
+
+**Recipe:**
+
+Per iteration, freeze and dispatch as normal. In a fresh judging session, run
+post-flight, integrate, and gate — but **withhold `architect verdict`**:
+
+```bash
+# judging session (per iteration) — stop before verdict:
+architect integrate <iteration> --lanes <passing-set>
+architect gate <iteration>
+# do NOT run: architect verdict <iteration> continue|kill
+```
+
+Each integrated-but-unjudged iteration surfaces as `awaiting-verdict` in
+`architect status`:
+
+```bash
+architect status
+# II   Iteration          …  Verdict
+# 03   some-feature       …  awaiting-verdict
+# 04   another-feature    …  awaiting-verdict
+```
+
+One later batch judging session evaluates all `awaiting-verdict` iterations,
+oldest-first. For each: read its own frozen AC from its freeze commit, run its
+gates cold, and record the verdict:
+
+```bash
+architect gate <iteration>               # run the frozen gates cold
+architect verdict <iteration> continue   # or: kill
+```
+
+**§1 preserved:** each verdict is cold and fresh-session — the batch judging
+session did not dispatch any of these iterations, so the §1
+fresh-session-judgment rule holds for every verdict in the batch.
+
+**Deliberate risk:** iteration N+1 integrated on top of N's not-yet-judged work
+rests on a foundation that a later KILL at N would revert. Accept this coupling
+only consciously, and always judge oldest-first so a KILL stops you before you
+compound it.
+
 ## Operating guidance
 
 - Background each lane as its own harness task and let the **per-lane
-  completion notification** bring you back (multi-hour runs are normal); read
+  completion notification** bring you back (long runs — 30–60 minutes — are normal); read
   `build/<id>-<lane>/run.jsonl` and the repo state afterwards. Do not write a
   blocking `while pgrep …; sleep` wait loop as a Bash command — that is itself
   a launcher that ties up a turn. When you return to a lane, check liveness via
   run-log growth (the stall rules below still apply unchanged).
 - Pin the model explicitly. The tool does this automatically (`--model
-  claude-sonnet-4-6`). The `sonnet` alias floats to the latest Sonnet — fine
-  interactively, but automations pin the full id so a model bump can't silently
-  change builder behavior mid-project.
+  <builder-model>`). A floating alias (a bare "latest"/tier tag) drifts to
+  whatever ships next — fine interactively, but automations pin the full id so a
+  model bump can't silently change builder behavior mid-project.
 - Effort = thinking budget. Claude Code has no per-invocation effort flag the
   way Codex exposed `model_reasoning_effort`; the builder sets thinking depth
   **in the block** via the escalation keywords (`think` < `think hard` <
@@ -166,16 +273,17 @@ git -C repos/<repo> branch -d lane/<iteration>-<lane>
   `claude -p --continue …`, never a `&` loop (a `&` launcher orphans the
   resumed lanes exactly as it does fresh ones). Never resume across iterations —
   every iteration gets a fresh context.
-- Cross-model review gate (high-stakes iterations): the architect is Opus 4.8
-  and the builder is Sonnet 4.6 — both Claude Code, so this is a
-  cross-*tier* read inside one lab, not cross-vendor (see `DESIGN.md` R3). The
-  architect (Opus) reading the diff is already the stronger-model fresh-context
-  pass. For an extra adversarial pass, pipe the instruction + diff to a fresh
-  read-only reviewer:
+- Capability-gap review gate (high-stakes iterations): the architect outranks the
+  builder, so the architect reading the diff is already a stronger-model,
+  fresh-context pass over it. How independent that read is depends on the pairing
+  — a same-lab architect/builder shares the builder's blind spots (the frozen
+  gates stay the independent check), a cross-vendor pairing is more independent
+  (see `docs/DESIGN.md` §1/R3). For an extra adversarial pass, pipe the
+  instruction + diff to a fresh read-only reviewer:
   ```bash
   { echo "Review this diff against the spec. Flag ONLY correctness/requirement/invariant gaps with file:line evidence. No style."; \
     git -C <repo-root> diff <base>...HEAD; } \
-  | claude -p --model claude-sonnet-4-6 --allowedTools 'Read,Grep,Glob'
+  | claude -p --model <builder-model> --allowedTools 'Read,Grep,Glob'
   ```
 - `build/` is already gitignored by the space, so no extra `.gitignore` entry
   is needed. Scratch never reaches the space repo; only `architecture/` is
@@ -287,11 +395,11 @@ against them, do not edit or work around) ===
 
 ## Builder-side standing setup (one time per machine/repo)
 
-- The builder is the same `claude` binary as the architect, one tier down —
-  nothing extra to install. `architect dispatch` pins the model per dispatch
-  (`--model claude-sonnet-4-6`); a `~/.claude/settings.json` `"model"` default
-  is fine interactively, but automations pin it explicitly so a default can't
-  silently swap the builder.
+- The builder is the same `claude` binary as the architect (reference harness),
+  running a cheaper model — nothing extra to install. `architect dispatch` pins
+  the model per dispatch (`--model <builder-model>`); a `~/.claude/settings.json`
+  `"model"` default is fine interactively, but automations pin it explicitly so a
+  default can't silently swap the builder.
 - Repo `CLAUDE.md` is the builder's standing context — Claude Code loads it
   root-down automatically. Put exact build/test commands and repo gotchas there;
   the loop's PHASE rules stay in the dispatch block so they version with the

data/skill/architect/research.md

@@ -2,7 +2,7 @@
 
 Read this only when a research trigger fires (see SKILL.md step 3). The fan-out
 uses `architect research dispatch` to launch parallel read-only `claude -p`
-researchers (Sonnet 4.6, no Edit/Write/Bash) and `architect research wait` to
+researchers (a cheaper model, read-only — no Edit/Write/Bash) and `architect research wait` to
 collect their results. The architect keeps all judgment: it verifies
 load-bearing claims and writes the iteration's **Grounds** section itself.
 

data/skill/architect-research/SKILL.md

@@ -74,7 +74,7 @@ toolset (`Read,Grep,Glob`) plus the web tools (`WebSearch,WebFetch`); the
 report is the redirected stdout:
 
 ```bash
-claude -p --model claude-sonnet-4-6 \
+claude -p --model <researcher-model> \
   --allowedTools 'Read,Grep,Glob,WebSearch,WebFetch' \
   --max-turns 40 \
   < build/research/<NN>-<lane>.prompt.md \
@@ -161,5 +161,5 @@ Commit the report. Raw findings stay in `build/research/` (gitignored).
 
 If this feeds the build loop: distill the report into the iteration's **Grounds**
 section (`architecture/I<NN>-<name>.md`) per `/architect`, or into
-`architecture/BRIEF.md` §sections when it is mission-scope, and continue there.
+`architecture/BRIEF.md` §sections when it is project-scope, and continue there.
 The builder's PHASE 0 will challenge Grounds' claims — that's a feature.

data/skill/architect-vocabulary/SKILL.md

@@ -2,7 +2,7 @@
 name: architect-vocabulary
 description: >
   Load the Architect system's vocabulary and a short "where you are"
-  orientation — space, mission, iteration, lane, brief, builder, architect,
+  orientation — space, project, iteration, lane, brief, builder, architect,
   gate, freeze, verdict, research, variant set — for when you're standing in a
   space-architect workspace (or working on the skill itself) and need the terms
   understood in conversation but do NOT want to run the loop. Reference only:
@@ -30,11 +30,12 @@ the loop.
 
 **Roles**
 
-- **architect** — the judgment role (a human, 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** — the implementation role: Claude Sonnet 4.6 run headless via
-  `architect dispatch` (`claude -p`), one per lane in its own worktree. Reports
+- **architect** — the judgment role (a strong reasoning model, or a human, in
+  judgment mode): arbitrates disagreements, writes and freezes iteration files,
+  calls kill/continue, merges builder output. Never writes implementation code.
+- **builder** — the implementation role: a cheaper model run headless via
+  `architect dispatch` (reference harness: `claude -p`), one per lane in its own
+  worktree. Reports
   raw evidence; never grades its own work; never edits `architecture/`.
 
 **The workspace**
@@ -43,9 +44,9 @@ the loop.
   artifacts under one root. `architect` finds it by walking up from `$PWD` to the
   nearest `space.yaml`.
 - **space.yaml** — the space's identity file: id, title, status, repos, notes,
-  tags, plus the `architect:` block (mission state — iterations, freeze shas,
+  tags, plus the `project:` block (project state — iterations, freeze shas,
   lanes).
-- **mission** — an Architect Loop instance living inside a space; spans the
+- **project** — an Architect Loop instance living inside a space; spans the
   repos under `repos/`.
 
 **The unit of work**
@@ -54,8 +55,9 @@ the loop.
   file `architecture/I<NN>-<name>.md`, grown section by section. Its sections:
   - **Grounds** — *why*: research/brief distilled (optional).
   - **Specification** — *what/how*: the full delegation contract.
-  - **Acceptance Criteria** — *proof*: exact gate commands + thresholds; this is
-    what gets frozen.
+  - **Acceptance Criteria** — *proof*: prose conditions (AC1, AC2, …) the
+    architect judges against, plus a fenced ` ```gates ` block of runnable checks;
+    this is what gets frozen.
   - **Builder Prompt** — the exact lane-prompt(s) dispatched.
   - **Builder Report** — raw evidence, transcribed verbatim from build scratch.
   - **Verdict** — rulings + per-AC PASS/FAIL/INVALID + KILL/CONTINUE.
@@ -70,17 +72,18 @@ the loop.
 
 **Contracts and checkpoints**
 
-- **brief** (`architecture/BRIEF.md`) — the durable, §-numbered mission contract
-  that spans iterations; frozen at the mission level and cited as **BRIEF §N**.
+- **brief** (`architecture/BRIEF.md`) — the durable, §-numbered project contract
+  that spans iterations; frozen at the project level and cited as **BRIEF §N**.
 - **ARCHITECT.md** (`architecture/ARCHITECT.md`) — the cross-iteration index /
-  table of contents and mission-wide state.
+  table of contents and project-wide state.
 - **freeze** ❄️ — committing the frozen region (Grounds / Specification /
   Acceptance Criteria) *before* dispatch (`architect freeze`). Records the
   **freeze_sha** in `space.yaml`; any later change to those sections is an
   automatic iteration FAIL.
-- **gate** — a frozen verification command + threshold (test/lint/typecheck/
-  build). `architect gate` runs them and streams raw output — it is a runner,
-  never a judge.
+- **gate** — a structured entry in the ` ```gates ` block: `id`, `ac`, `cmd`,
+  optional `cwd`, and an `expect` hash (exit_code / stdout_match / threshold).
+  `architect gate` runs each gate's `cmd` and streams raw output — it is a runner,
+  never a judge. `architect freeze` lints the gates block before committing.
 
 **Outcomes**
 
@@ -106,18 +109,18 @@ the loop.
 **Repos**
 
 - **evergreen** / copy-on-write / **`src` engine** — repo provisioning: when an
-  up-to-date local copy exists under `evergreen_dir`, `architect` copies it into
+  up-to-date local copy exists under `src_dir`, `architect` copies it into
   the space (copy-on-write on APFS) instead of cloning over the network. The
-  vendored `src` engine keeps those evergreen checkouts tended.
+  `src` engine (`space-src`) keeps those evergreen checkouts tended.
 
 ## Where you are
 
 A space's directory layout:
 
 ```text
-space.yaml        # identity + mission state (the architect: block)
+space.yaml        # identity + project state (the project: block)
 README.md
-repos/            # the repos the mission spans
+repos/            # the repos the project spans
 notes/            # scratch, prompts, logs
 architecture/     # ARCHITECT.md index + I<NN>-<name>.md iteration files (+ BRIEF.md)
 build/            # lane worktrees + scratch: build/<id>-<lane>/
@@ -127,7 +130,7 @@ tmp/              # workspace-local temp — use instead of /tmp
 Safe **read-only** commands to orient yourself (these don't run the loop):
 
 ```sh
-architect status            # mission state: iterations, freeze shas, lanes, verdicts
+architect status            # project state: iterations, freeze shas, lanes, verdicts
 architect space show        # the space you're standing in
 architect space list        # all your spaces
 ```

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: space-architect
 version: !ruby/object:Gem::Version
-  version: 2.0.0.rc1
+  version: 2.0.0.rc2
 platform: ruby
 authors:
 - Eric Jacobs
@@ -239,13 +239,15 @@ files:
 - exe/space
 - exe/src
 - lib/space_architect.rb
-- lib/space_architect/architect_mission.rb
+- lib/space_architect/architect_project.rb
 - lib/space_architect/cli.rb
 - lib/space_architect/cli/architect.rb
 - lib/space_architect/cli/research.rb
 - lib/space_architect/cli/space.rb
 - lib/space_architect/cli/src.rb
 - lib/space_architect/dispatcher.rb
+- lib/space_architect/gate_evaluator.rb
+- lib/space_architect/gate_lint.rb
 - lib/space_architect/harness.rb
 - lib/space_architect/research.rb
 - lib/space_architect/research/mux.rb
@@ -262,6 +264,7 @@ files:
 - lib/space_core/atomic_write.rb
 - lib/space_core/cli.rb
 - lib/space_core/cli/base_command.rb
+- lib/space_core/cli/build.rb
 - lib/space_core/cli/config.rb
 - lib/space_core/cli/current.rb
 - lib/space_core/cli/help.rb
@@ -269,9 +272,11 @@ files:
 - lib/space_core/cli/init.rb
 - lib/space_core/cli/list.rb
 - lib/space_core/cli/new.rb
+- lib/space_core/cli/pack.rb
 - lib/space_core/cli/path.rb
 - lib/space_core/cli/repeatable_options.rb
 - lib/space_core/cli/repo.rb
+- lib/space_core/cli/run.rb
 - lib/space_core/cli/shell.rb
 - lib/space_core/cli/show.rb
 - lib/space_core/cli/status.rb
@@ -280,6 +285,9 @@ files:
 - lib/space_core/errors.rb
 - lib/space_core/git_client.rb
 - lib/space_core/mise_client.rb
+- lib/space_core/oci_builder.rb
+- lib/space_core/oci_packer.rb
+- lib/space_core/oci_runner.rb
 - lib/space_core/repo_reference.rb
 - lib/space_core/repo_resolver.rb
 - lib/space_core/shell_integration.rb
@@ -287,6 +295,9 @@ files:
 - lib/space_core/space.rb
 - lib/space_core/space_store.rb
 - lib/space_core/state.rb
+- lib/space_core/templates/oci/dockerfile.erb
+- lib/space_core/templates/oci/dockerignore.erb
+- lib/space_core/templates/oci/entrypoint.sh.erb
 - lib/space_core/terminal.rb
 - lib/space_core/version.rb
 - lib/space_core/warnings.rb