space-architect 9.0.0 → 9.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02caeb5cc690ab3d847e54fed5eb88c1493fa2402ace662ef7f25d2aeb4d055b
-  data.tar.gz: 5fa1fc73aaf8e912a74b1daf36e392c4d8afdc19cf1e6af22cc94702ef4146fd
+  metadata.gz: 154e74a35cc7d14274f2f6fec65f40400727adbf3ce4bcf69000c2f00405a07e
+  data.tar.gz: 2d6407b32a61f8c056e866e12dceab65b6a0b35f281ec6b1721c73233517da49
 SHA512:
-  metadata.gz: b0f3278ba088effaba68eb1942872bb38dc7b73301bc7f0c5229ab773a69174da531d76009a2725912ab2615c67f1b6321ac3e20648e919adfd471e8a41eb309
-  data.tar.gz: 550862ccc0030a536896d219c2645c7194ec56357eebe9ae3eb08024811b60aca7fd857fd2e86daa80a406fa54e0050b922f80926ea66a14fcbb6fa71bcfda5b
+  metadata.gz: db472c7ffcff0c4228f9c6bda1baad0c00cb0283defa3a686924267d51d252b9f24e3cdf65a8d50076f0354f5af1894ff6ff9799c2b783069a8bf52567206c2b
+  data.tar.gz: 444e06a1bbcbefe3f827a065cefba6383d04606215abf0ab016069f7b254a8c61d2343aa91a648a3a2be92ae1a47c97b18dbcdc63bb62a92d23c63b3b8b10e6f

data/README.md

@@ -5,288 +5,59 @@
 > **The Architect Loop — structured judgment-and-build cycles for humans and their agents!** ✨🛰️
 
 `space-architect` is the gem behind the **Architect Loop**: a structured
-judgment-and-build cycle for you and a fleet of headless AI builders, run
-inside task-scoped **spaces** — directories that hold repos, notes, and
-artifacts under one obvious filesystem root. 🌌
+judgment-and-build cycle in which a strong reasoning model (the *architect*)
+plans, freezes acceptance criteria, and judges the work of a fleet of headless
+AI *builders* — one per lane, each in its own git worktree. The loop runs inside
+task-scoped **spaces**: directories that hold repos, notes, and artifacts under
+one obvious filesystem root. Nothing lives only in a chat window — every
+decision, spec, and verdict is committed to the space repo.
 
 It installs **one executable**, `architect`. The spaces substrate and the
-evergreen-checkout engine live in two sibling gems:
+evergreen-checkout engine are two sibling gems:
 
 | Gem | Dependency | What it provides |
 |-----|------------|------------------|
-| **space-cadet** | hard | The spaces substrate (`Space::Core`): create, manage & containerize task-scoped workspaces — the `space` binary — plus the copy-on-write evergreen-checkout substrate (`Cloner`, `SCM`) repos provision from |
+| **space-cadet** | hard | The spaces substrate (`Space::Core`): create, manage & containerize task-scoped workspaces — the `space` binary — plus the copy-on-write evergreen-checkout substrate repos provision from |
 | **repo-tender** | soft | Evergreen clone tending — the `repo-tender` binary (with the deprecated `src` shim) — and the launchd agent the `architect sessions agent` commands drive. Install with `gem install repo-tender` when you want the session-sync rail — everything else works without it |
 
-Until 8.x this gem was the monolith: it shipped `space`, `architect`, and `src`
-binaries (and `architect space …` / `architect src …` forwarders) plus the
-vendored `Space::Core` / `Space::Src` subtrees. The 9.0.0 split carved the
-tools into their own gems; this gem is the loop only. If you're on 8.x, get
-`space` from the **space-cadet** gem and `src` from **repo-tender** now — and
-`gem uninstall space-architect` first: the 8.x gem's `space`/`src` executables
-collide with the ones the new gems ship.
-
-## What's a space? 🪐
-
-A space is just a regular directory with a tiny YAML identity file and room for
-everything a task needs:
-
-```text
-~/architect/spaces/20260531-name-of-space/
-  space.yaml        # identity: id, title, status, repos, notes, tags
-  README.md
-  repos/            # cloned (or copy-on-write'd) repositories
-  notes/            # scratch, prompts, logs
-  architecture/     # iteration files: I<NN>-<name>.md + ARCHITECT.md index + BRIEF.md
-  build/            # lane worktrees + scratch (build/<id>-<lane>/)
-  tmp/              # workspace-local temp — use this instead of /tmp
-```
-
-Run an `architect` command from inside a space and it just works — the loop
-walks up from `$PWD` until it finds the nearest `space.yaml`. No "current
-space" state to get out of sync; where you *are* is the space you mean. 🧭
-
-Create and manage spaces with the **space-cadet** gem:
-
-```sh
-space init                                        # create XDG config + state files
-space new "Name of Space" -r org/repo -r org/lib  # blast off a new space 🚀
-space list                                        # see all your spaces
-```
-
 ## Installation 📦
 
-Add it to your `Gemfile`:
-
-```ruby
-gem "space-architect"
-```
-
-```bash
-bundle install
-```
-
-Or grab it yourself:
-
 ```bash
 gem install space-architect
 gem install repo-tender   # optional: enables the sessions launchd agent
 ```
 
-The gem installs one executable: `architect`. 🎀
-
-## Quick start 🎀
-
-```sh
-# Spaces (space-cadet gem)
-space init                                        # create XDG config + state files
-space new "Name of Space" -r org/repo -r org/lib  # blast off a new space 🚀
-space use 20260531-name-of-space                  # cd into a space by id
-
-# Architect Loop (run from inside a space)
-architect install-skills                          # install agent skills (once per machine)
-architect init                                    # scaffold ARCHITECT.md + architecture/
-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
-```
-
-## `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 *project*.
-
-**Roles:**
-
-- **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; 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
-    run.jsonl               # streamed builder output
-    report.md               # builder report (transcribed into the iteration file verbatim)
-```
-
-**Iteration file anatomy** — one file, grown section by section. You author the
-*content* in fresh scratch files; the CLI owns the *persistence* (each command
-writes the section, commits it, and prints back what changed). Every committing
-command takes `-m`/`--message` and `--message-from <file>` — your first line
-completes the subject after a short canonical prefix (`I01 spec: <subject>`),
-the rest becomes the body. The space's git log is the loop's durable memory:
-write detailed messages.
-
-| Section | Holds | How you persist it |
-|---------|-------|--------------------|
-| `## Grounds` | why — research / brief distilled (optional) | `architect section <it> grounds --from <f>` |
-| `## Specification` | what/how — the full delegation contract | `architect section <it> specification --from <f>` |
-| `## Acceptance Criteria` | proof — exact gate commands + thresholds | `architect freeze <it>` ❄️ |
-| `## Builder Prompt` | the exact lane-prompt(s) dispatched | `architect section <it> prompt --append --lane <l> --from <f>` |
-| `## Builder Report` | raw evidence, transcribed verbatim | `architect evidence <it> --lane <l>` |
-| `## Verdict` | rulings + per-AC PASS/FAIL + KILL/CONTINUE | `architect section <it> verdict --from <f>` |
-
-**The freeze ❄️** — `architect freeze <iteration>` commits the frozen region
-(Grounds / Specification / Acceptance Criteria), records the `freeze_sha`, and
-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 project: block + SessionStart hook
-architect brief new --from <f>              # write the durable project BRIEF.md (authored in a scratch file)
-architect new <iteration>                   # scaffold architecture/I<NN>-<iteration>.md
-architect section <it> <section> --from <f> # write + commit a section (add -m/--message-from for a detailed commit)
-architect freeze <iteration>                # freeze the Acceptance Criteria ❄️
-architect worktree add <repo> <it> <lane>   # isolated worktree per lane (2–4 lanes)
-architect dispatch <it> <lane> --prompt <f> # copy the lane prompt in + dispatch a builder (--detach to survive long runs)
-architect verify <iteration>                # post-flight mechanical checks (reports only)
-architect evidence <it> --lane <lane>       # transcribe the builder's report verbatim
-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
-# landing (PR body + push/PR command) is the architect's end-of-project procedure (see skill)
-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)
-```
-
-`architect help` (or bare `architect`, `architect --help`) lists these grouped by
-loop phase — **Spec · Build · Judge · Land · Project · Groups**, in canonical
-order — and, inside an architect space, ends with a compact loop-status block
-(project status + current iteration) so you can see where you are in the loop. 🧭
-
-A typical session:
-
-```sh
-architect init                                   # first time
-architect new my-feature                         # scaffold I01-my-feature.md
-architect section my-feature specification --from spec.md -m "pull-based dispatcher seam"
-architect freeze my-feature                      # lock it ❄️
-architect dispatch my-feature lane-a --prompt tmp/prompts/I01-lane-a.md --detach   # send a builder; poll the report
-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>
-# landing (PR body + push/PR command) is the architect's end-of-project procedure (see skill)
-```
-
-### Streaming builder output 📡
-
-`architect dispatch` can push the builder's pi JSONL event stream to an ingest
-server for
-live viewing:
-
-```sh
-# Push to an already-created run (you supply the full ingest URL):
-architect dispatch my-feature lane-a \
-  --push-url   $HOST/runs/<id>/ingest \
-  --push-token $INGEST_TOKEN
-
-# Create a run and push in one step (requires --push-token = server's INGEST_TOKEN):
-architect dispatch my-feature lane-a \
-  --push-host  $HOST \
-  --push-token $INGEST_TOKEN
-```
-
-`--push-host` POSTs to `<HOST>/runs`, parses the new run id from the `201`
-response, derives `<HOST>/runs/<id>/ingest`, and streams there; the created run
-id and ingest URL are printed after dispatch starts. `--push-url` and
-`--push-host` are mutually exclusive, both require `--push-token`, and neither
-can be combined with `--detach` (the push tees the live pipe in-process).
+The gem installs one executable: `architect`. 🎀 (Or add
+`gem "space-architect"` to your Gemfile and `bundle install`.)
 
-### Research lanes 🔭
+Upgrading from the 8.x monolith? Uninstall `space-architect` 8.x **first** —
+its `space`/`src` executables collide with the ones the new gems ship — see
+[the upgrade guide](docs/how-to/upgrade-from-the-8x-monolith.md).
 
-When an iteration needs facts the repo doesn't already have, fan out parallel
-**read-only** research lanes — detached `pi -p --mode json` researchers
-(read-only by prompt contract; the supervisor-injected guard denies git writes)
-that you supervise:
+## 60-second start 🎀
 
-```sh
-architect research dispatch 01-official-api.prompt.md 02-changelog.prompt.md
-architect research wait        # tails each lane's run.jsonl; --level 1-4, --quiet, --thinking
-architect research status      # status of dispatched runs
-```
-
-Researchers gather; the architect verifies the load-bearing claims against
-sources and writes the iteration's **Grounds** section.
-
-### Skills 🧠
-
-`architect install-skills` installs the bundled `architect`,
-`architect-research`, and `architect-vocabulary` skills for your harness:
+Run one full loop iteration in a scratch space — the
+[tutorial](docs/tutorials/one-loop-iteration.md) walks it end to end:
 
 ```sh
-architect install-skills                         # default: claude (~/.claude/skills/)
-architect install-skills --provider opencode     # or codex | pi
-architect install-skills --project               # into ./… instead of globally
-architect install-skills --dry-run               # show what would change
+space init                          # create the XDG config + state files (space-cadet gem)
+space new "Docsmith Tutorial"       # blast off a new space 🚀
+cd ~/architect/spaces/<id>-docsmith-tutorial
+architect init                      # scaffold ARCHITECT.md + the space.yaml project: block
 ```
 
-`architect-vocabulary` loads the system's terms and a short orientation when
-you're in a space but don't want to run the loop.
-
-### Sessions: the launchd rail 🛰️ (requires repo-tender)
-
-`architect sessions sync` uploads new conversation transcripts (`~/.pi/agent/sessions`
-and `~/.claude/projects`) to a space-server; `architect sessions agent
-install|uninstall|status` manages the per-user launchd agent that runs the sync
-on an interval. These commands drive **repo-tender**'s launchd agent — a *soft*
-dependency, deliberately absent from the gemspec: without the gem, the sessions
-agent commands print a short error naming the fix (`gem install repo-tender`)
-and the rest of `architect` is unaffected.
-
-## Configuration ⚙️
-
-The spaces config the loop reads lives at `~/.config/space-cadet/config.yml`
-(XDG-aware, owned by the space-cadet gem) — see `space config show`. The loop
-itself has no config of its own: a space's `space.yaml` `project:` block *is*
-the loop's state.
+From there the loop is: `architect new` → `architect section …` → `architect
+freeze` → `architect dispatch` → `architect gate` → `architect integrate`. The
+tutorial runs every step on a scratch repo.
 
-## Embedding 📚
+## The four quadrants 🧭
 
-Two namespaces, published as two gems:
-
-- **`Space::Core`** (the space-cadet gem) — the substrate: config, state, XDG,
-  terminal, git/mise clients, the space store. The `space` CLI runs on this.
-- **`Space::Architect`** (this gem) — project state, the builder harness,
-  dispatch, and the research supervisor, over the `Space::Core` substrate.
-
-```ruby
-require "space_core"       # just spaces (space-cadet gem)
-require "space_architect"  # the loop (pulls in the space-cadet gem)
-```
-
-## Documentation 📖
-
-- **[Command Reference](docs/reference.md)** — every command, flag, and behavior
-- **[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
+| Quadrant | Read it when you… | Start here |
+|----------|-------------------|------------|
+| **Tutorials** — learning-oriented | are new and want a guided journey | [docs/tutorials](docs/tutorials/) |
+| **How-to guides** — goal-oriented | have a specific task to do | [docs/how-to](docs/how-to/) |
+| **Reference** — information-oriented | need a fact about a command, flag, or file | [docs/reference](docs/reference/) |
+| **Explanation** — understanding-oriented | want the why behind the design | [docs/explanation](docs/explanation/) |
 
 ## Development 🛠️
 
@@ -297,15 +68,9 @@ bundle exec rake build      # build the gem into pkg/
 bundle exec rake install    # build + install into your user gem home
 ```
 
-## Contributing 💝
-
 Bug reports and pull requests are welcome on GitHub at
-[https://github.com/jetpks/space-architect](https://github.com/jetpks/space-architect)!
-
-## License 📄
-
-Available as open source under the terms of the
-[MIT License](https://opensource.org/licenses/MIT).
+[https://github.com/jetpks/space-architect](https://github.com/jetpks/space-architect).
+Available as open source under the [MIT License](LICENSE.txt).
 
 ---
 

data/lib/space_architect/architect_project.rb

@@ -127,38 +127,47 @@ module Space::Architect
     end
 
     # Allocate the next ordinal and scaffold architecture/I<NN>-<iteration>.md.
+    # Serialized across processes: ordinal allocation is a read-modify-write of
+    # space.yaml's project block, and two concurrent `architect new` processes
+    # would duplicate the ordinal and silently drop the loser's iterations
+    # entry (last writer wins). The metadata is saved by atomic replace, so the
+    # lock is a sibling file under tmp/ (gitignored, space-standard) — never
+    # space.yaml itself — and the metadata is re-loaded inside the lock because
+    # every process booted with its own pre-scaffold snapshot.
     def new_iteration!(name, message: nil)
-      block = space.data["project"] || {}
-      iterations = block["iterations"] || []
-      if iterations.any? { |s| s["name"] == name }
-        raise Space::Core::Error, "iteration '#{name}' already exists in space.yaml"
-      end
+      with_scaffold_lock do
+        block = space.data["project"] || {}
+        iterations = block["iterations"] || []
+        if iterations.any? { |s| s["name"] == name }
+          raise Space::Core::Error, "iteration '#{name}' already exists in space.yaml"
+        end
 
-      ordinal = (iterations.map { |s| s["ordinal"] || 0 }.max || 0) + 1
-      nn = format("%02d", ordinal)
-      rel = "architecture/I#{nn}-#{name}.md"
-      path = space.path.join(rel)
-      raise Space::Core::Error, "#{rel} already exists" if path.exist?
+        ordinal = (iterations.map { |s| s["ordinal"] || 0 }.max || 0) + 1
+        nn = format("%02d", ordinal)
+        rel = "architecture/I#{nn}-#{name}.md"
+        path = space.path.join(rel)
+        raise Space::Core::Error, "#{rel} already exists" if path.exist?
 
-      FileUtils.mkdir_p(path.dirname)
-      path.write(render_iteration(nn, name))
+        FileUtils.mkdir_p(path.dirname)
+        path.write(render_iteration(nn, name))
 
-      update_architect_block do |b|
-        b["current_iteration"] = name
-        list = b["iterations"] || []
-        list << {
-          "name" => name, "ordinal" => ordinal, "file" => rel,
-          "freeze_sha" => nil, "verdict" => "pending", "lanes" => []
-        }
-        b["iterations"] = list
-        b
-      end
+        update_architect_block do |b|
+          b["current_iteration"] = name
+          list = b["iterations"] || []
+          list << {
+            "name" => name, "ordinal" => ordinal, "file" => rel,
+            "freeze_sha" => nil, "verdict" => "pending", "lanes" => []
+          }
+          b["iterations"] = list
+          b
+        end
 
-      git_run("-C", space.path.to_s, "add", rel, Space::Core::Space::METADATA_FILE)
-      git_run("-C", space.path.to_s, "commit", "-m",
-        compose_message("I#{nn} scaffold:", "I#{nn}: scaffold #{name}", message))
+        git_run("-C", space.path.to_s, "add", rel, Space::Core::Space::METADATA_FILE)
+        git_run("-C", space.path.to_s, "commit", "-m",
+          compose_message("I#{nn} scaffold:", "I#{nn}: scaffold #{name}", message))
 
-      path
+        path
+      end
     end
 
     def status
@@ -701,8 +710,12 @@ module Space::Architect
     def worktree_add(repo, iteration, lane, base: nil, base_explicit: !base.nil?, harness: nil, model: nil,
                      variant: false, effort: nil, touch: nil, force: false, err: $stderr)
       model, suffix_level = Harness.parse_model_suffix(model)
-      harness, model = resolve_harness_model(harness, model)
-      resolved_level = effort || suffix_level || project_defaults["effort"]
+      harness, model, inform = resolve_harness_model(harness, model)
+      err.puts inform if inform
+      # The config layer sits above project.effort — architect.yaml is the
+      # dedicated routing layer; unconfigured spaces fall through unchanged.
+      resolved_level = effort || suffix_level ||
+        Routing.for_space(space.path)&.dig("builder", "thinking") || project_defaults["effort"]
       Harness.validate_thinking_level!(resolved_level)
       if effort.nil? && suffix_level
         err.puts "thinking: model suffix ':#{suffix_level}' parsed from lane model → level=#{suffix_level} (model stripped)"
@@ -916,12 +929,21 @@ module Space::Architect
       base_explicit = !base.nil?
       refuse_repoint_if_dirty!(iteration, lanes, base, iteration_id(entry)) if base_explicit && !force
 
+      # Sync-or-refuse ONCE per distinct repo of the selected set (lane order,
+      # first occurrence) BEFORE any worktree is cut — a divergence aborts the
+      # entire provision. An explicit --base is the deliberate case (#88): the
+      # pin is cut exactly as given, no sync, no divergence refusal.
+      synced = {}
+      unless base_explicit
+        lanes.map { |l| l["repo"] }.uniq.each { |repo| synced[repo] = sync_integration_branch!(repo, iteration) }
+      end
+
       lanes.map do |l|
         name = l["name"]
         result = worktree_add(l["repo"], iteration, name, base: resolve_lane_base(l["repo"], base),
                               base_explicit: base_explicit, force: force, **recorded_lane_fields(l))
         { lane: name, worktree: result[:worktree], base_sha: result[:base_sha], outcome: result[:outcome],
-          discarded: result[:discarded] }
+          discarded: result[:discarded], synced: synced[l["repo"]] }
       end
     end
 
@@ -1033,6 +1055,25 @@ module Space::Architect
 
     attr_reader :space
 
+    # Exclusive cross-process lock around one whole critical section (used by
+    # new_iteration!): flock on .git/architect.lock — the metadata file itself
+    # cannot be the lock because save() replaces it by atomic rename (a new
+    # inode would not contend), and .git is the one directory every scaffoldable
+    # space guarantees (new_iteration! commits) that git never reports as
+    # untracked noise (git's own index.lock lives by the same convention).
+    # Inside the lock the metadata is adopted in place (data.replace, keeping
+    # object identity for every holder of this space) — each process booted
+    # with its own pre-scaffold snapshot, so the ordinal must be read from
+    # disk truth.
+    def with_scaffold_lock
+      lock_path = space.path.join(".git", "architect.lock")
+      File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |lock|
+        lock.flock(File::LOCK_EX)
+        space.data.replace(Space::Core::Space.load(space.path).data)
+        yield
+      end
+    end
+
     # The vendored builder-guard extension shipped in the gem (lib/space_architect/pi/).
     def vendored_guard_path
       Pathname.new(__dir__).join("pi/builder-guard.ts")
@@ -1590,6 +1631,15 @@ module Space::Architect
       wt_path = space.path.join(lane_entry["worktree"] || "build/#{iteration_id(entry)}-#{lane}/wt")
       return lane_entry if wt_path.exist? && worktree_registered?(repo_path, wt_path)
 
+      # Same sync-or-refuse as provision, immediately before the cut — a
+      # dispatch/gate/integrate/verify that materializes a missing worktree must
+      # never cut it from a stale integration tip. Already-materialized lanes
+      # returned above and stay a true no-op. The inform goes on $stderr, like
+      # worktree_add's own informs on this path; no-op syncs print nothing.
+      report = sync_integration_branch!(lane_entry["repo"], iteration)
+      $stderr.puts "#{report[:repo]}: fast-forwarded #{report[:branch]} to #{report[:sha][0, 8]} — " \
+        "synced before materializing #{iteration}/#{lane}" if report
+
       worktree_add(lane_entry["repo"], iteration, lane, base: resolve_lane_base(lane_entry["repo"], nil),
                    base_explicit: false, **recorded_lane_fields(lane_entry))
       (slice_entry(iteration)["lanes"] || []).find { |l| l["name"] == lane }
@@ -1605,19 +1655,35 @@ module Space::Architect
     end
 
     # Resolve harness + model by precedence: explicit value > (dispatch only) the
-    # lane's stored value > space.yaml project.harness/project.model > the pi
-    # default model. Shared by worktree_add and dispatch so both read the same
-    # defaults. A stored model is only honored when its stored harness still matches
-    # the resolved harness — a dispatch-time harness override drops the old harness's
-    # stored model instead of leaking it into the new harness's run. A stored
-    # legacy harness name survives resolution (so a stale space.yaml
-    # surfaces as Harness.for's actionable pi-only error, not a silent default).
+    # lane's stored value > architect.yaml builder-role model > space.yaml
+    # project.harness/project.model > the pi default model. Shared by worktree_add
+    # and dispatch so both read the same defaults. A stored model is only honored
+    # when its stored harness still matches the resolved harness — a dispatch-time
+    # harness override drops the old harness's stored model instead of leaking it
+    # into the new harness's run. A stored legacy harness name survives resolution
+    # (so a stale space.yaml surfaces as Harness.for's actionable pi-only error,
+    # not a silent default).
+    #
+    # Returns [harness, model, inform] — inform is the loud last-resort line (nil
+    # otherwise) for the caller to print once to its err stream when the model
+    # fell all the way through to Harness::DEFAULT_MODEL (no flag, no stored
+    # value, no architect.yaml builder role, no project.model).
     def resolve_harness_model(harness, model, stored_harness: nil, stored_model: nil)
       defaults = project_defaults
       resolved_harness = (harness || stored_harness || defaults["harness"] || "pi").to_s
       stored_model = nil unless stored_harness.nil? || stored_harness.to_s == resolved_harness
-      resolved_model = model || stored_model || defaults["model"] || Harness::DEFAULT_MODEL
-      [resolved_harness, resolved_model]
+      config_model = Routing.for_space(space.path)&.dig("builder", "model")
+      resolved_model = model || stored_model || config_model || defaults["model"] || Harness::DEFAULT_MODEL
+      inform = default_model_inform if model.nil? && stored_model.nil? && config_model.nil? && defaults["model"].nil?
+      [resolved_harness, resolved_model, inform]
+    end
+
+    # The loud last-resort inform — the bare DEFAULT_MODEL constant is a last
+    # resort, not a silent fallback: name that no architect.yaml was found, the
+    # two paths looked at, and the default in use.
+    def default_model_inform
+      "model: no architect.yaml found (looked at #{Routing.space_path(space.path)} + #{Routing.global_path}) — " \
+        "using default '#{Harness::DEFAULT_MODEL}'"
     end
 
     # --prompt: the caller authors the lane prompt anywhere (a fresh scratch file) and
@@ -1640,8 +1706,9 @@ module Space::Architect
     # precedence and thinking-level translation from one place.
     def resolve_dispatch_harness(lane_entry, model:, harness:, effort:, force:, err:)
       model, suffix_level = Harness.parse_model_suffix(model)
-      resolved_harness, resolved_model = resolve_harness_model(harness, model,
+      resolved_harness, resolved_model, inform = resolve_harness_model(harness, model,
         stored_harness: lane_entry["harness"], stored_model: lane_entry["model"])
+      err.puts inform if inform
 
       resolved_effort =
         if effort
@@ -1651,7 +1718,9 @@ module Space::Architect
           err.puts "thinking: model suffix ':#{suffix_level}' parsed from --model → level=#{suffix_level} (model stripped to '#{model}')"
           suffix_level
         else
-          lane_entry["effort"]
+          # Dispatch's tail is the lane's stored effort (project.effort was never
+          # in the dispatch chain); architect.yaml builder thinking slots in above it.
+          lane_entry["effort"] || Routing.for_space(space.path)&.dig("builder", "thinking")
         end
 
       [resolved_harness, resolved_model, resolved_effort]
@@ -1684,6 +1753,57 @@ module Space::Architect
       st.success? && !out.strip.empty? ? out.strip : "HEAD"
     end
 
+    # Fast-forward the repo's project integration branch from its default branch
+    # BEFORE any lane worktree is cut from it (I06 provision-sync — the I05 burn:
+    # a worktree cut from a stale project/<slug> tip). Local-to-local only — no
+    # fetch/pull, no remote-tracking ref is read or written. Compare before moving:
+    # default not ahead → no-op (nil, callers print nothing); default ahead and
+    # integration not ahead → fast-forward; both ahead → refuse (a human merges
+    # deliberately, or pins --base) — --force has no bypass. Bang: it raises.
+    # Returns nil for a no-op, or { repo:, branch:, sha: } for the moved ref so
+    # callers can report the movement (never silently move a branch).
+    def sync_integration_branch!(repo, iteration)
+      repo_path = space.path.join("repos", repo)
+      integration = project_integration_branch
+      return nil unless branch_exists?(repo_path, integration)
+
+      default = repo_default_branch(repo_path)
+      counts_out, counts_err, counts_st = git_capture("-C", repo_path.to_s, "rev-list", "--left-right", "--count",
+        "#{default}...#{integration}")
+      unless counts_st.success?
+        raise Space::Core::Error, "Cannot compare #{default}...#{integration} in repos/#{repo} — #{counts_err.strip}"
+      end
+
+      default_ahead, integration_ahead = counts_out.strip.split.map(&:to_i)
+      return nil if default_ahead.zero?
+
+      default_tip, = git_capture("-C", repo_path.to_s, "rev-parse", default)
+      integration_tip, = git_capture("-C", repo_path.to_s, "rev-parse", integration)
+      if integration_ahead.positive?
+        raise Space::Core::Error,
+          "Refusing to provision '#{iteration}' — repos/#{repo} has diverged: #{default} (#{default_tip[0, 8]}) and " \
+          "#{integration} (#{integration_tip[0, 8]}) each hold commits the other lacks " \
+          "(#{default} ahead by #{default_ahead}, #{integration} ahead by #{integration_ahead}) — not fast-forwardable. " \
+          "A human must merge #{default} into #{integration} deliberately, or pin the base explicitly with " \
+          "`architect provision #{iteration} --base <sha>`. --force does not bypass this refusal."
+      end
+
+      head_out, _, head_st = git_capture("-C", repo_path.to_s, "symbolic-ref", "--short", "HEAD")
+      if head_st.success? && head_out.strip == integration
+        # The integration branch is the clone's checked-out branch (the real
+        # post-integrate state — merge_lane! checks it out) — fetch refuses a
+        # checked-out dst, so fast-forward via merge instead.
+        git_run("-C", repo_path.to_s, "merge", "--ff-only", default)
+      else
+        # Unprefixed refspecs are ff-only by construction — git rejects a non-ff
+        # update here, so the branch can only ever move forward.
+        git_run("-C", repo_path.to_s, "fetch", ".", "#{default}:#{integration}")
+      end
+
+      new_tip, = git_capture("-C", repo_path.to_s, "rev-parse", integration)
+      { repo: repo, branch: integration, sha: new_tip.strip }
+    end
+
     def slice_entry(iteration)
       block = space.data["project"] || {}
       entry = (block["iterations"] || []).find { |s| s["name"] == iteration }