space-architect 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 135a6282cfe3e3073265b71867e7d228673cbfb9b7253feaaba5ad67a180b7cb
-  data.tar.gz: 0d0406a99feadadebb24a6167c11837de25bede933e752ef6507524208f4e5a7
+  metadata.gz: bb8f902d475bcc8a29e56740ce0c20328935fe05f9d919d38934b2cffd12e966
+  data.tar.gz: e31c5b6f8ad98219c9c4ed22225666900bc7aaf8f43bd929ef32e2d2b5aacdf2
 SHA512:
-  metadata.gz: c8b161eff4f4b5a788c2e3c9b423bcc31a495915a076afb70445f6b0cdaf1cc2573ee381ce0c3e09ca712a8398b70ca091b015260b6b4e9c24914ece4a0f5539
-  data.tar.gz: f61cdd897881530ad2e81df5bd846c4e644fb85ac6847c4afd147e643b6045b59c7ecb89fd12b83f9a7b5c2ef12813c5e88e7634449a919aac2e4bc75052a6b0
+  metadata.gz: 5cbb47cbacf2231ed09eb74bfb11b80a1a6076bfde1427fe76a19b3581f3b3a8e38db4a6269307e339a022902723d73b1d40dd4b001acd6ffaab624871249d70
+  data.tar.gz: 171913d786d1e166a279f72b184ec7987785d561ec795bfe161db9341502210f6d97166c3eb8b7a097b59adba7e435a575c78ca66488ca482312b4bc7cca7249

data/README.md

@@ -102,7 +102,9 @@ space show 20260531-name-of-space
 space path 20260531-name-of-space
 space current                                # based on $PWD
 space show                                   # based on $PWD
-space status done                            # based on $PWD
+space status                                 # report: metadata + loop status (based on $PWD)
+space status 20260531-name-of-space          # report another space
+space status done                            # set: active | paused | done | archived
 space status 20260531-name-of-space done
 space config set default_provider github.com
 space config set default_organization example-org
@@ -115,6 +117,12 @@ space use 20260531-name-of-space             # records recent state, prints the
 space ls --color=always                      # auto | always | never (--colors also accepted)
 ```
 
+`space status` is **report-or-set**: with no status keyword (bare, or with just
+a space id) it *reports* the space — its metadata plus a compact loop-status
+block (project status, current iteration, derived state) when the space runs an
+Architect project, quietly omitted otherwise; pass a status keyword (`active`,
+`paused`, `done`, `archived`) to *set* it instead. 🔁
+
 Repos are passed with a repeatable `-r` flag (`-r org/repo -r org/lib`); the
 comma form (`-r a,b`) works too. Space ids are date-prefixed
 (`20260531-name-of-space`) so they sort naturally, and duplicate names on the
@@ -308,6 +316,11 @@ architect variant add|compare|promote …     # competing (harness, model) lanes
 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

data/lib/space_architect/architect_project.rb

@@ -6,6 +6,7 @@ require "open3"
 require "fileutils"
 require "pathname"
 require "tempfile"
+require "time"
 
 module Space::Architect
   # Manages an architect-loop project inside a space: one self-contained file per
@@ -164,6 +165,7 @@ module Space::Architect
       end
 
       lint_gates!(text, warnings: warnings)
+      lint_lanes!(text)
 
       if entry["freeze_sha"]
         sha = entry["freeze_sha"]
@@ -177,21 +179,26 @@ module Space::Architect
 
       files = [rel]
       files << "architecture/ARCHITECT.md" if space.path.join("architecture", "ARCHITECT.md").exist?
-      git_run("-C", space.path.to_s, "add", *files)
-      if staged_changes?
-        nn = format("%02d", entry["ordinal"] || 0)
-        git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: acceptance criteria (freeze)")
-      end
+      nn = format("%02d", entry["ordinal"] || 0)
+      git_capture("-C", space.path.to_s, "commit", "-m", "I#{nn}: acceptance criteria (freeze)", "--", *files)
 
       sha, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
       sha = sha.strip
 
+      declared = parse_lanes(text)
       update_architect_block do |b|
         b["current_iteration"] = iteration
         (b["iterations"] || []).each do |s|
           next unless s["name"] == iteration
           s["freeze_sha"] = sha
           s["verdict"] ||= "pending"
+          lanes = s["lanes"] || []
+          declared.each do |d|
+            fields = { "name" => d["name"], "repo" => d["repo"], "touch_set" => Array(d["touch"]) }
+            existing = lanes.find { |l| l["name"] == d["name"] }
+            existing ? existing.merge!(fields) : lanes << fields
+          end
+          s["lanes"] = lanes
         end
         b
       end
@@ -242,13 +249,13 @@ module Space::Architect
       path.write(replace_section_body(path.read, spec[:heading], block, append: append))
 
       nn = format("%02d", entry["ordinal"] || 0)
-      git_run("-C", space.path.to_s, "add", rel)
-      committed = staged_changes?
-      git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: #{spec[:message]}") if committed
-
-      head, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
-      diffstat, = committed ? git_capture("-C", space.path.to_s, "show", "--stat", "--format=", "HEAD") : [""]
-      { section: section, heading: spec[:heading], sha: head.strip, committed: committed, diffstat: diffstat.strip }
+      _o, _e, cst = git_capture("-C", space.path.to_s, "commit", "-m", "I#{nn}: #{spec[:message]}", "--", rel)
+      committed = cst.success?
+      show_out, = git_capture("-C", space.path.to_s, "show", "--stat", "--format=%H", "HEAD")
+      show_lines = show_out.to_s.lines
+      sha = show_lines.first&.strip || ""
+      diffstat = committed ? show_lines.drop(1).join.strip : ""
+      { section: section, heading: spec[:heading], sha: sha, committed: committed, diffstat: diffstat }
     end
 
     # Write the ## Verdict prose AND record the decision to space.yaml in one commit.
@@ -272,8 +279,7 @@ module Space::Architect
       end
 
       nn = format("%02d", entry["ordinal"] || 0)
-      git_run("-C", space.path.to_s, "add", rel, Space::Core::Space::METADATA_FILE)
-      git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: verdict")
+      git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: verdict", "--", rel, Space::Core::Space::METADATA_FILE)
 
       head, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
       { decision: decision, sha: head.strip }
@@ -297,8 +303,7 @@ module Space::Architect
       path.write(replace_section_body(path.read, "## Builder Report", block, append: !lane.nil?))
 
       nn = format("%02d", entry["ordinal"] || 0)
-      git_run("-C", space.path.to_s, "add", rel)
-      git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: evidence") if staged_changes?
+      git_capture("-C", space.path.to_s, "commit", "-m", "I#{nn}: evidence", "--", rel)
       head, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
 
       status_line = raw.lines.reverse_each.find { |l| l.strip.start_with?("STATUS:") }&.strip
@@ -330,6 +335,7 @@ module Space::Architect
       entry = slice_entry(iteration)
       lane_entry = (entry["lanes"] || []).find { |l| l["name"] == lane }
       raise Space::Core::Error, "No lane '#{lane}' recorded for iteration '#{iteration}'" unless lane_entry
+      lane_entry = ensure_lane_materialized(iteration, lane)
 
       checks = lane_mechanical_checks(entry, lane_entry)
       if checks[:no_builder_commits] == false
@@ -393,9 +399,13 @@ module Space::Architect
     end
 
     # Loop merge_lane! over the architect-supplied passing set, in order. Stops on the
-    # first conflict (a disjointness defect). Never decides which lanes pass.
-    def integrate!(iteration, lanes:, teardown: false)
-      raise Space::Core::Error, "No lanes given to integrate" if lanes.nil? || lanes.empty?
+    # first conflict (a disjointness defect). Never decides which lanes pass. With no
+    # lanes and teardown: true, tears down every lane recorded for the iteration instead
+    # (the second, teardown-only call in the loop's integrate-then-teardown rhythm).
+    def integrate!(iteration, lanes: nil, teardown: false)
+      lanes = Array(lanes)
+      return teardown_lanes!(iteration, slice_entry(iteration)["lanes"] || []) if lanes.empty? && teardown
+      raise Space::Core::Error, "No lanes given to integrate" if lanes.empty?
 
       merged = []
       lanes.each do |lane|
@@ -405,13 +415,7 @@ module Space::Architect
         raise Space::Core::Error, "Integrated #{done.empty? ? "(none)" : done} then stopped at '#{lane}': #{e.message}"
       end
 
-      if teardown
-        id = iteration_id(slice_entry(iteration))
-        merged.each do |m|
-          worktree_remove(iteration, m[:lane])
-          git_capture("-C", space.path.join("repos", m[:repo]).to_s, "branch", "-d", "lane/#{id}-#{m[:lane]}")
-        end
-      end
+      teardown_lanes!(iteration, merged) if teardown
       merged
     end
 
@@ -438,6 +442,7 @@ module Space::Architect
         if lane
           le = lanes.find { |l| l["name"] == lane }
           raise Space::Core::Error, "No lane '#{lane}' recorded for iteration '#{iteration}'" unless le
+          le = ensure_lane_materialized(iteration, lane)
           repo_root = le["repo"] ? space.path.join("repos", le["repo"]) : nil
           space.path.join(le["worktree"] || "build/#{iteration_id(entry)}-#{lane}/wt")
         else
@@ -558,7 +563,13 @@ module Space::Architect
 
       # Skip git worktree add when the branch and worktree already exist (idempotent re-run).
       unless branch_exists?(repo_path, branch) && worktree_registered?(repo_path, wt_path)
-        git_run("-C", repo_path.to_s, "worktree", "add", wt_path.to_s, "-b", branch, base_sha)
+        if branch_exists?(repo_path, branch)
+          # The worktree was removed but its lane branch survived — re-attach the branch
+          # (carrying its own tip) instead of `-b`, which would fail "branch already exists".
+          git_run("-C", repo_path.to_s, "worktree", "add", wt_path.to_s, branch)
+        else
+          git_run("-C", repo_path.to_s, "worktree", "add", wt_path.to_s, "-b", branch, base_sha)
+        end
       end
 
       # Seed prompt.md with a placeholder stub so the architect has a place to write the prompt.
@@ -704,9 +715,39 @@ module Space::Architect
       wt_base.children.select(&:directory?).map { |p| p.basename.to_s }.sort
     end
 
+    # Materialize the iteration's declared lanes: for each lane (or the one named via
+    # `lane:`), create its worktree + lane/<id>-<lane> branch from the resolved base and
+    # record worktree/base_sha/integration_branch. Idempotent — an already-materialized
+    # lane is skipped, not re-created. Refuses until the iteration is frozen, because
+    # declarations are not authoritative until then.
+    def provision(iteration, base: nil, lane: nil)
+      entry = slice_entry(iteration)
+      raise Space::Core::Error,
+        "Iteration '#{iteration}' is not frozen — freeze before provisioning (declarations are not authoritative until frozen)." \
+        unless entry["freeze_sha"]
+
+      lanes = entry["lanes"] || []
+      lanes = lanes.select { |l| l["name"] == lane } if lane
+      raise Space::Core::Error, "No lane '#{lane}' declared for iteration '#{iteration}'" if lane && lanes.empty?
+
+      lanes.map do |l|
+        name = l["name"]
+        repo_path = space.path.join("repos", l["repo"])
+        wt_path = space.path.join(l["worktree"] || "build/#{iteration_id(entry)}-#{name}/wt")
+        if wt_path.exist? && worktree_registered?(repo_path, wt_path)
+          { lane: name, worktree: wt_path, base_sha: l["base_sha"], created: false }
+        else
+          result = worktree_add(l["repo"], iteration, name, base: resolve_lane_base(l["repo"], base),
+                                **recorded_lane_fields(l))
+          { lane: name, worktree: result[:worktree], base_sha: result[:base_sha], created: true }
+        end
+      end
+    end
+
     def verify(iteration)
       entry = slice_entry(iteration)
       (entry["lanes"] || []).map do |lane|
+        ensure_lane_materialized(iteration, lane["name"])
         { lane: lane["name"], repo: lane["repo"], checks: lane_mechanical_checks(entry, lane) }
       end
     end
@@ -714,7 +755,7 @@ module Space::Architect
     def dispatch(iteration, lane, model: nil, max_turns: 200,
                  claude_bin: nil, harness: nil, opencode_bin: nil, effort: nil, detach: false,
                  push_url: nil, push_token: nil, push_host: nil, run_creator: nil,
-                 push_client: nil, timeout: nil)
+                 push_client: nil, timeout: nil, now: Time.now)
       raise Space::Core::Error, "Specify --push-host or --push-url, not both" if push_host && push_url
       raise Space::Core::Error, "--push-host requires --push-token"           if push_host && !push_token
       raise Space::Core::Error, "--detach cannot be combined with --push-url or --push-host" \
@@ -723,6 +764,7 @@ module Space::Architect
       entry = slice_entry(iteration)
       lane_entry = (entry["lanes"] || []).find { |l| l["name"] == lane }
       raise Space::Core::Error, "No lane '#{lane}' recorded for iteration '#{iteration}'" unless lane_entry
+      lane_entry = ensure_lane_materialized(iteration, lane)
 
       resolved_harness = harness || lane_entry["harness"] || "claude-code"
       resolved_model   = model   || lane_entry["model"]   || Harness::CLAUDE_DEFAULT_MODEL
@@ -749,6 +791,20 @@ module Space::Architect
       harness_obj = Harness.for(resolved_harness, model: resolved_model, max_turns: max_turns,
                                                   bin: bin, config_dir: build_dir, effort: resolved_effort)
 
+      # Stamp launch time onto the lane entry: after every preflight validation has passed
+      # (a dispatch that raises above records nothing) and before the blocking run or a
+      # detached dispatch returns. A re-dispatch overwrites the prior value.
+      update_architect_block do |b|
+        (b["iterations"] || []).each do |s|
+          next unless s["name"] == iteration
+          (s["lanes"] || []).each do |l|
+            next unless l["name"] == lane
+            l["dispatched_at"] = now.iso8601
+          end
+        end
+        b
+      end
+
       if detach
         pid = harness_obj.run_detached(
           prompt_path:  prompt_path,
@@ -785,6 +841,21 @@ module Space::Architect
 
     attr_reader :space
 
+    # Remove each lane's worktree and safe-delete (`-d`) its lane branch. Accepts
+    # either merge_lane! results (symbol keys) or recorded lane entries (string
+    # keys) — both carry a lane name and a repo.
+    def teardown_lanes!(iteration, lane_entries)
+      id = iteration_id(slice_entry(iteration))
+      lane_entries.map do |l|
+        lane = l[:lane] || l["name"]
+        repo = l[:repo] || l["repo"]
+        worktree_remove(iteration, lane)
+        lane_branch = "lane/#{id}-#{lane}"
+        git_capture("-C", space.path.join("repos", repo).to_s, "branch", "-d", lane_branch)
+        { lane: lane, repo: repo, lane_branch: lane_branch }
+      end
+    end
+
     # Resolve the in-flight iteration file for ground output.
     # Rule: (a) current_iteration from project block → entry's file if it exists on disk,
     #        (b) else highest-ordinal architecture/I<NN>-*.md,
@@ -855,6 +926,55 @@ module Space::Architect
       "project/#{slug}"
     end
 
+    # Materialize a declared lane on demand: when its worktree is absent, create it
+    # identically to `provision` (same base resolution, same worktree_add primitive)
+    # so no dispatch/integrate/gate path dead-ends on a missing worktree. Returns the
+    # (possibly refreshed) lane entry; a no-op when already materialized or undeclared.
+    def ensure_lane_materialized(iteration, lane)
+      entry = slice_entry(iteration)
+      lane_entry = (entry["lanes"] || []).find { |l| l["name"] == lane }
+      return lane_entry unless lane_entry && lane_entry["repo"]
+
+      repo_path = space.path.join("repos", lane_entry["repo"])
+      return lane_entry unless repo_path.exist?
+      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)
+
+      worktree_add(lane_entry["repo"], iteration, lane, base: resolve_lane_base(lane_entry["repo"], nil),
+                   **recorded_lane_fields(lane_entry))
+      (slice_entry(iteration)["lanes"] || []).find { |l| l["name"] == lane }
+    end
+
+    # The lane's declared harness/model/variant/effort, as worktree_add kwargs — so a
+    # re-materialize preserves them instead of merging back to defaults. touch_set is
+    # deliberately omitted: worktree_add leaves it untouched, so it already survives.
+    def recorded_lane_fields(lane_entry)
+      {
+        harness: lane_entry["harness"] || "claude-code",
+        model:   lane_entry["model"],
+        variant: lane_entry["variant"] || false,
+        effort:  lane_entry["effort"]
+      }
+    end
+
+    # Resolve the base ref a lane's worktree branches from: an explicit override wins;
+    # otherwise the project/<slug> integration branch when it exists, else the repo's
+    # default branch.
+    def resolve_lane_base(repo, override)
+      return override if override
+      repo_path = space.path.join("repos", repo)
+      integration = project_integration_branch
+      return integration if branch_exists?(repo_path, integration)
+      repo_default_branch(repo_path)
+    end
+
+    def repo_default_branch(repo_path)
+      out, _, st = git_capture("-C", repo_path.to_s, "symbolic-ref", "--short", "refs/remotes/origin/HEAD")
+      return out.strip.sub(%r{\Aorigin/}, "") if st.success? && !out.strip.empty?
+      out, _, st = git_capture("-C", repo_path.to_s, "symbolic-ref", "--short", "HEAD")
+      st.success? && !out.strip.empty? ? out.strip : "HEAD"
+    end
+
     def slice_entry(iteration)
       block = space.data["project"] || {}
       entry = (block["iterations"] || []).find { |s| s["name"] == iteration }
@@ -981,6 +1101,44 @@ module Space::Architect
       parsed.is_a?(Array) ? parsed : []
     end
 
+    # Extract and parse the fenced ```lanes block from the Specification section.
+    # Returns an array of lane declaration hashes (string-keyed). Returns [] when the
+    # block is absent, empty, or contains only YAML comments (back-compat).
+    def parse_lanes(text)
+      body = section_body(text, "## Specification")
+      return [] unless body
+      match = body.match(/^```lanes\n(.*?)^```/m)
+      return [] unless match
+      parsed = YAML.safe_load(match[1], aliases: false)
+      parsed.is_a?(Array) ? parsed : []
+    end
+
+    # Lint the lanes block in the given iteration file text. Raises Space::Core::Error
+    # with aggregated messages on failure. An absent/empty block is allowed (back-compat).
+    def lint_lanes!(text)
+      lanes = begin
+        parse_lanes(text)
+      rescue Psych::SyntaxError => e
+        raise Space::Core::Error, "ill-formed lanes block: #{e.message}"
+      end
+      return if lanes.empty?
+
+      errors = lanes.each_with_index.flat_map do |l, i|
+        unless l.is_a?(Hash)
+          next ["lane #{i}: expected a mapping with name/repo/touch"]
+        end
+        touch = l["touch"]
+        [
+          ("lane #{i}: missing 'name'" if l["name"].to_s.strip.empty?),
+          ("lane #{i}: missing 'repo'" if l["repo"].to_s.strip.empty?),
+          ("lane #{i} (#{l["name"]}): 'touch' must be a non-empty array of globs" \
+            unless touch.is_a?(Array) && touch.any? && touch.all? { |g| g.is_a?(String) && !g.strip.empty? })
+        ].compact
+      end
+      return if errors.empty?
+      raise Space::Core::Error, "ill-formed lanes block:\n#{errors.join("\n")}"
+    end
+
     # Lint the gates block in the given iteration file text. Raises Space::Core::Error
     # with aggregated messages on failure. Absent/empty gates appends a warning to
     # the optional warnings array but does not fail.

data/lib/space_architect/cli/architect.rb

@@ -4,9 +4,23 @@ require "json"
 
 module Space::Architect
   module CLI
+    # Optional loop-phase DSL on the shared command base, read by
+    # Space::Core::CLI::Help to group the help listing. A command may declare
+    # `phase <order>, "<Label>"`; groups, and members within a group, sort by
+    # <order>. Only architect commands declare one — space commands leave it nil
+    # and render as the single ungrouped default listing (unchanged).
+    class BaseCommand
+      def self.phase(order = nil, label = nil)
+        return @phase if order.nil?
+
+        @phase = [order, label]
+      end
+    end
+
     module Architect
       class Init < BaseCommand
         desc "Scaffold (or top up) the architect project: ARCHITECT.md, space.yaml project block, SessionStart hook"
+        phase 50, "Project"
         argument :space, required: false, desc: "Space identifier (default: $PWD)"
 
         def call(space: nil, **opts)
@@ -24,6 +38,7 @@ module Space::Architect
 
       class Ground < BaseCommand
         desc "Print grounding reads (ARCHITECT.md, BRIEF.md, in-flight iteration) to stdout"
+        phase 51, "Project"
         argument :space, required: false, desc: "Space identifier (default: $PWD)"
 
         def call(space: nil, **opts)
@@ -56,6 +71,7 @@ module Space::Architect
 
       class New < BaseCommand
         desc "Scaffold the next iteration file (architecture/I<NN>-<iteration>.md)"
+        phase 10, "Spec"
         argument :iteration, required: true,  desc: "Iteration name (kebab-case)"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
 
@@ -74,6 +90,7 @@ module Space::Architect
 
       class Status < BaseCommand
         desc "Show architect project state (read-only)"
+        phase 52, "Project"
         argument :space, required: false, desc: "Space identifier (default: $PWD)"
 
         def call(space: nil, **opts)
@@ -126,6 +143,7 @@ module Space::Architect
 
       class Freeze < BaseCommand
         desc "Freeze the iteration's frozen region (Grounds/Specification/Acceptance Criteria) and record the freeze SHA"
+        phase 12, "Spec"
         argument :iteration, required: true, desc: "Iteration name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
 
@@ -152,6 +170,7 @@ module Space::Architect
 
       class Verify < BaseCommand
         desc "Post-flight mechanical lane checks — frozen-untouched, no builder commits, report exists, in-bounds (reports only, no judgment)"
+        phase 30, "Judge"
         argument :iteration, required: true, desc: "Iteration name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
 
@@ -199,6 +218,7 @@ module Space::Architect
 
       class Dispatch < BaseCommand
         desc "Dispatch a builder for a lane (streams to build/<id>-<lane>/run.jsonl)"
+        phase 21, "Build"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :lane,      required: true,  desc: "Lane name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
@@ -251,8 +271,37 @@ module Space::Architect
         end
       end
 
+      class Provision < BaseCommand
+        desc "Materialize declared lanes (worktree + lane/<id>-<lane> branch) from the frozen lane plan"
+        phase 20, "Build"
+        argument :iteration, required: true,  desc: "Iteration name"
+        argument :space,     required: false, desc: "Space identifier (default: $PWD)"
+        option   :base,      default: nil,    desc: "Base ref override (default: project/<slug> HEAD if it exists, else the repo's default branch)"
+        option   :lane,      default: nil,    desc: "Provision only this lane (default: all declared lanes)"
+
+        def call(iteration:, space: nil, base: nil, lane: nil, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            render(store.find(space)) do |sp|
+              project = ArchitectProject.new(space: sp)
+              results = project.provision(iteration, base: base, lane: lane)
+              if results.empty?
+                terminal.say "No declared lanes to provision for '#{iteration}'"
+              else
+                results.each do |r|
+                  state = r[:created] ? "created" : "already present"
+                  terminal.say "#{r[:lane]}: #{terminal.path(r[:worktree])} (#{state})"
+                end
+              end
+              CLI.record_outcome(Outcome.new(exit_code: 0))
+            end
+          end
+        end
+      end
+
       class Section < BaseCommand
         desc "Write a section of the iteration file and commit it (one call)"
+        phase 11, "Spec"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :section,   required: true,  desc: "Section: grounds, specification, prompt, verdict"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
@@ -292,6 +341,7 @@ module Space::Architect
 
       class Verdict < BaseCommand
         desc "Record the architect's verdict decision (continue or kill) and write ## Verdict prose"
+        phase 33, "Judge"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :decision,  required: true,  desc: "Decision: continue or kill"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
@@ -324,6 +374,7 @@ module Space::Architect
 
       class Evidence < BaseCommand
         desc "Transcribe a lane's scratch report VERBATIM into Builder Report and commit"
+        phase 31, "Judge"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
         option   :lane,      default: nil,    desc: "Lane name (per-lane subsection; omit for a single-lane iteration)"
@@ -345,6 +396,7 @@ module Space::Architect
 
       class Merge < BaseCommand
         desc "Integrate ONE judged-passing lane (merges --no-ff; runs no gates, makes no verdict)"
+        phase 41, "Land"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :lane,      required: true,  desc: "Lane name (architect-judged passing)"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
@@ -367,22 +419,36 @@ module Space::Architect
 
       class Integrate < BaseCommand
         desc "Integrate the architect-supplied set of passing lanes, in order (stops on conflict)"
+        phase 40, "Land"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
-        option   :lanes,     required: true,  desc: "Comma-separated passing lane names (you decide the set)"
+        option   :lanes,     required: false, desc: "Comma-separated passing lane names (you decide the set)"
         option   :teardown,  type: :boolean, default: false, desc: "Remove worktrees + delete lane branches after merge"
 
-        def call(iteration:, space: nil, lanes:, teardown: false, **opts)
+        def call(iteration:, space: nil, lanes: nil, teardown: false, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
+            lane_names = lanes.to_s.split(",").map(&:strip).reject(&:empty?)
+            raise Space::Core::Error, "integrate needs --lanes <set>, or --teardown for teardown-only" \
+              if lane_names.empty? && !teardown
+
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              lane_names = lanes.to_s.split(",").map(&:strip).reject(&:empty?)
               results = project.integrate!(iteration, lanes: lane_names, teardown: teardown)
-              results.each do |r|
-                terminal.say "Merged #{r[:lane]} → #{r[:integration_branch]} (#{r[:merge_sha][0, 8]})"
+              if lane_names.empty?
+                if results.empty?
+                  terminal.say "Nothing to tear down for #{iteration}"
+                else
+                  results.each do |r|
+                    terminal.say "Tore down #{r[:lane]} (removed worktree, deleted #{r[:lane_branch]})"
+                  end
+                end
+              else
+                results.each do |r|
+                  terminal.say "Merged #{r[:lane]} → #{r[:integration_branch]} (#{r[:merge_sha][0, 8]})"
+                end
+                terminal.say "Gates NOT run — run `architect gate #{iteration}`; the verdict is the next session's."
               end
-              terminal.say "Gates NOT run — run `architect gate #{iteration}`; the verdict is the next session's."
               CLI.record_outcome(Outcome.new(exit_code: 0))
             end
           end
@@ -391,6 +457,7 @@ module Space::Architect
 
       class Gate < BaseCommand
         desc "Run the frozen Acceptance Criteria gate commands and report PASS/FAIL"
+        phase 32, "Judge"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :lane,      required: false, desc: "Run in a lane worktree (default: the integration repo)"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
@@ -420,6 +487,7 @@ module Space::Architect
 
       class BugReport < BaseCommand
         desc "Generate a prefilled GitHub issue template for filing bugs against space-architect"
+        phase 54, "Project"
 
         def call(**opts)
           setup_terminal(**opts.slice(:color, :colors))
@@ -443,6 +511,7 @@ module Space::Architect
 
       class InstallSkills < BaseCommand
         desc "Install bundled skills (architect, architect-research, architect-vocabulary) for a harness"
+        phase 53, "Project"
         option :provider, default: "claude", desc: "Harness: claude, codex, opencode, pi"
         option :project, type: :boolean, default: false, desc: "Install to CWD instead of global"
         option :force,   type: :boolean, default: false, desc: "Overwrite existing skills that differ"
@@ -642,12 +711,17 @@ module Space::Architect
   end
 end
 
+# Loop-phase declarations above sort the architect help listing; its namespaces
+# (brief/worktree/variant/research) declare no phase and list under this header.
+Space::Core::CLI::Help.trailing_group_label = "Groups"
+
 Space::Architect::CLI::Registry.register "init",   Space::Architect::CLI::Architect::Init
 Space::Architect::CLI::Registry.register "ground", Space::Architect::CLI::Architect::Ground
 Space::Architect::CLI::Registry.register "new",    Space::Architect::CLI::Architect::New
 Space::Architect::CLI::Registry.register "status", Space::Architect::CLI::Architect::Status
 Space::Architect::CLI::Registry.register "freeze", Space::Architect::CLI::Architect::Freeze
 Space::Architect::CLI::Registry.register "verify", Space::Architect::CLI::Architect::Verify
+Space::Architect::CLI::Registry.register "provision", Space::Architect::CLI::Architect::Provision
 Space::Architect::CLI::Registry.register "dispatch", Space::Architect::CLI::Architect::Dispatch
 Space::Architect::CLI::Registry.register "section",   Space::Architect::CLI::Architect::Section
 Space::Architect::CLI::Registry.register "verdict",   Space::Architect::CLI::Architect::Verdict