space-architect 3.0.0 → 5.0.0

data/lib/space_architect/cli/architect.rb

@@ -4,17 +4,62 @@ 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
+
+      # Declares -m/--message and --message-from on a committing command. Every
+      # loop command that commits takes both: the space's git log is the loop's
+      # durable memory, so detailed messages are encouraged everywhere.
+      def self.commit_message_options
+        option :message, aliases: ["-m"], default: nil,
+          desc: "Commit message: first line completes the subject after the canonical prefix, the rest becomes the body"
+        option :message_from, default: nil,
+          desc: "Read the commit message from this file (subject line + detailed body)"
+      end
+
+      private
+
+      # Authored-content intake shared by section/verdict/brief: a file, an
+      # inline flag, or stdin — canonical files are only ever written by the CLI.
+      def read_body(from: nil, body: nil, stdin: false, what: "section body")
+        return File.read(from) if from
+        return body if body
+        return $stdin.read if stdin
+
+        raise Space::Core::Error, "provide the #{what} via --from <file>, --body <text>, or --stdin"
+      end
+
+      # Commit-message intake for commit_message_options: --message-from wins
+      # over -m/--message; nil means the command's canonical default message.
+      def read_commit_message(message: nil, message_from: nil)
+        return File.read(message_from) if message_from
+
+        message
+      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)"
+        commit_message_options
 
-        def call(space: nil, **opts)
+        def call(space: nil, message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              path = project.init!
+              path = project.init!(message: read_commit_message(message: message, message_from: message_from))
               terminal.say "Project ready: #{terminal.path(path)}"
               CLI.record_outcome(Outcome.new(exit_code: 0))
             end
@@ -24,6 +69,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,15 +102,18 @@ 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)"
+        commit_message_options
 
-        def call(iteration:, space: nil, **opts)
+        def call(iteration:, space: nil, message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              path = project.new_iteration!(iteration)
+              path = project.new_iteration!(iteration,
+                message: read_commit_message(message: message, message_from: message_from))
               terminal.say "Iteration scaffolded: #{terminal.path(path)}"
               CLI.record_outcome(Outcome.new(exit_code: 0))
             end
@@ -74,6 +123,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,16 +176,19 @@ 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)"
+        commit_message_options
 
-        def call(iteration:, space: nil, **opts)
+        def call(iteration:, space: nil, message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
               warnings = []
-              sha = project.freeze!(iteration, warnings: warnings)
+              sha = project.freeze!(iteration, warnings: warnings,
+                message: read_commit_message(message: message, message_from: message_from))
               terminal.say "Frozen #{iteration} at #{sha}"
               warnings.each { |w| terminal.say "Warning: #{w}" }
               ac = project.acceptance_criteria(iteration)
@@ -152,6 +205,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,9 +253,11 @@ 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)"
+        option   :prompt,    default: nil,    desc: "Read the lane prompt from this file (copied byte-for-byte to build/<id>-<lane>/prompt.md)"
         option   :model,     default: nil,    desc: "Builder model to pin (default: the lane's model, else the reference default claude-sonnet-4-6). Any provider/tier; pin a full id, not a floating alias"
         option   :max_turns, default: "200",  desc: "Max turns for the builder"
         option   :harness,   default: nil,    desc: "Harness override (claude-code, opencode)"
@@ -212,7 +268,7 @@ module Space::Architect
         option   :push_token, default: nil,   desc: "Bearer token for push endpoint authorization"
         option   :push_host,  default: nil,   desc: "Base URL of the ingest server; the CLI creates a run via POST <host>/runs and streams to /runs/<id>/ingest (requires --push-token)"
 
-        def call(iteration:, lane:, space: nil, model: nil,
+        def call(iteration:, lane:, space: nil, prompt: nil, model: nil,
                  max_turns: "200", harness: nil, effort: nil, detach: false,
                  timeout: "14400", push_url: nil, push_token: nil, push_host: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
@@ -220,6 +276,7 @@ module Space::Architect
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
               kwargs = { max_turns: max_turns.to_i, detach: detach }
+              kwargs[:prompt]     = prompt          if prompt
               kwargs[:model]      = model           if model
               kwargs[:harness]    = harness         if harness
               kwargs[:effort]     = effort          if effort
@@ -228,6 +285,7 @@ module Space::Architect
               kwargs[:push_token] = push_token      if push_token
               kwargs[:push_host]  = push_host       if push_host
               res = project.dispatch(iteration, lane, **kwargs)
+              terminal.say "Prompt:  #{prompt} → #{terminal.path(res[:prompt_copied])}" if res[:prompt_copied]
               if detach
                 terminal.say "PID:     #{res[:pid]}"
                 terminal.say "Run log: #{terminal.path(res[:run_log])}"
@@ -251,8 +309,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)"
@@ -261,14 +348,17 @@ module Space::Architect
         option   :stdin,  type: :boolean, default: false, desc: "Read the section body from stdin"
         option   :append, type: :boolean, default: false, desc: "Append a ### <lane> subsection instead of replacing"
         option   :lane,   default: nil, desc: "Lane name for an appended ### subsection"
+        commit_message_options
 
-        def call(iteration:, section:, space: nil, from: nil, body: nil, stdin: false, append: false, lane: nil, **opts)
+        def call(iteration:, section:, space: nil, from: nil, body: nil, stdin: false, append: false, lane: nil,
+                 message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
-            content = read_section_body(from: from, body: body, stdin: stdin)
+            content = read_body(from: from, body: body, stdin: stdin, what: "section body")
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              res = project.write_section!(iteration, section, body: content, append: append, lane: lane)
+              res = project.write_section!(iteration, section, body: content, append: append, lane: lane,
+                message: read_commit_message(message: message, message_from: message_from))
               if res[:committed]
                 terminal.say "Committed #{res[:heading]} → #{res[:sha][0, 8]}"
                 terminal.say res[:diffstat] unless res[:diffstat].empty?
@@ -279,61 +369,50 @@ module Space::Architect
             end
           end
         end
-
-        private
-
-        def read_section_body(from:, body:, stdin:)
-          return File.read(from) if from
-          return body if body
-          return $stdin.read if stdin
-          raise Space::Core::Error, "provide the section body via --from <file>, --body <text>, or --stdin"
-        end
       end
 
       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)"
         option   :from,  default: nil,   desc: "Read the verdict body from this file"
         option   :body,  default: nil,   desc: "Inline verdict body"
         option   :stdin, type: :boolean, default: false, desc: "Read the verdict body from stdin"
+        commit_message_options
 
-        def call(iteration:, decision:, space: nil, from: nil, body: nil, stdin: false, **opts)
+        def call(iteration:, decision:, space: nil, from: nil, body: nil, stdin: false,
+                 message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
-            content = read_section_body(from: from, body: body, stdin: stdin)
+            content = read_body(from: from, body: body, stdin: stdin, what: "verdict body")
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              res = project.record_verdict!(iteration, decision: decision, body: content)
+              res = project.record_verdict!(iteration, decision: decision, body: content,
+                message: read_commit_message(message: message, message_from: message_from))
               terminal.say "Verdict '#{res[:decision]}' recorded → #{res[:sha][0, 8]}"
               CLI.record_outcome(Outcome.new(exit_code: 0))
             end
           end
         end
-
-        private
-
-        def read_section_body(from:, body:, stdin:)
-          return File.read(from) if from
-          return body if body
-          return $stdin.read if stdin
-          raise Space::Core::Error, "provide the verdict body via --from <file>, --body <text>, or --stdin"
-        end
       end
 
       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)"
+        commit_message_options
 
-        def call(iteration:, space: nil, lane: nil, **opts)
+        def call(iteration:, space: nil, lane: nil, message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              res = project.transcribe_evidence!(iteration, lane: lane)
+              res = project.transcribe_evidence!(iteration, lane: lane,
+                message: read_commit_message(message: message, message_from: message_from))
               terminal.say "Transcribed #{res[:lines]} lines → #{res[:sha][0, 8]}"
               terminal.say "Builder STATUS: #{res[:status_line]}" if res[:status_line]
               terminal.say "Now rule on the builder's PHASE 0 disagreements in the Verdict (a later session)."
@@ -345,17 +424,19 @@ 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)"
-        option   :message,   default: nil,    desc: "Commit message for the lane's working-tree changes"
+        commit_message_options
 
-        def call(iteration:, lane:, space: nil, message: nil, **opts)
+        def call(iteration:, lane:, space: nil, message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              r = project.merge_lane!(iteration, lane, message: message)
+              r = project.merge_lane!(iteration, lane,
+                message: read_commit_message(message: message, message_from: message_from))
               terminal.say "Merged #{lane} → #{r[:integration_branch]} (#{r[:merge_sha][0, 8]})"
               terminal.say r[:diffstat] unless r[:diffstat].empty?
               terminal.say "Gates NOT run — run `architect gate #{iteration}` against the integration branch."
@@ -367,22 +448,38 @@ 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"
+        commit_message_options
 
-        def call(iteration:, space: nil, lanes:, teardown: false, **opts)
+        def call(iteration:, space: nil, lanes: nil, teardown: false, message: nil, message_from: nil, **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]})"
+              results = project.integrate!(iteration, lanes: lane_names, teardown: teardown,
+                message: read_commit_message(message: message, message_from: message_from))
+              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 +488,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 +518,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 +542,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"
@@ -621,17 +721,23 @@ module Space::Architect
 
       module Brief
         class New < BaseCommand
-          desc "Scaffold the durable project brief (architecture/BRIEF.md)"
+          desc "Write the durable project brief (architecture/BRIEF.md) — authored via --from/--stdin, or a placeholder template"
           argument :space, required: false, desc: "Space identifier (default: $PWD)"
           option   :force, type: :boolean, default: false, desc: "Overwrite an existing BRIEF.md"
+          option   :from,  default: nil,   desc: "Read the authored brief body from this file"
+          option   :stdin, type: :boolean, default: false, desc: "Read the authored brief body from stdin"
+          commit_message_options
 
-          def call(space: nil, force: false, **opts)
+          def call(space: nil, force: false, from: nil, stdin: false, message: nil, message_from: nil, **opts)
             setup_terminal(**opts.slice(:color, :colors))
             handle_errors do
+              content = (from || stdin) ? read_body(from: from, stdin: stdin, what: "brief body") : nil
               render(store.find(space)) do |sp|
                 project = ArchitectProject.new(space: sp)
-                path = project.brief_new!(force: force)
-                terminal.say "Brief ready: #{terminal.path(path)}"
+                path = project.brief_new!(force: force, content: content,
+                  message: read_commit_message(message: message, message_from: message_from))
+                note = content ? "" : " (template — Read it before editing)"
+                terminal.say "Brief ready: #{terminal.path(path)}#{note}"
                 CLI.record_outcome(Outcome.new(exit_code: 0))
               end
             end
@@ -642,12 +748,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

data/lib/space_architect/harness.rb

@@ -56,7 +56,12 @@ module Space::Architect
 
       TIMEOUT_EXIT_CODE = 124
 
-      def run(prompt_path:, run_log_path:, chdir:, push_url: nil, push_token: nil, push_client: nil, timeout: nil)
+      # How long the liveness fiber waits before reading the run log's stream-json init
+      # event. Injectable via the run(liveness_delay:) kwarg so tests need not sleep seconds.
+      LIVENESS_DELAY_SECONDS = 5.0
+
+      def run(prompt_path:, run_log_path:, chdir:, push_url: nil, push_token: nil, push_client: nil, timeout: nil,
+              liveness_delay: LIVENESS_DELAY_SECONDS, err: $stderr)
         prompt_path  = Pathname.new(prompt_path)
         run_log_path = Pathname.new(run_log_path)
 
@@ -66,7 +71,7 @@ module Space::Architect
             Sync do
               child = Async::Process::Child.new(*argv, chdir: chdir.to_s, in: prompt_io, out: w, err: log)
               w.close
-              tasks = start_tee(r, log, push_url: push_url, push_token: push_token, push_client: push_client)
+              tasks = start_tee(r, log, push_url: push_url, push_token: push_token, push_client: push_client, err: err)
               timed_out    = false
               timeout_task = nil
 
@@ -84,8 +89,21 @@ module Space::Architect
                 end
               end
 
+              # Liveness self-check: after a bounded delay, read the run log's stream-json
+              # init event and print ONE line naming the streamed model + confirming growth.
+              # transient: true so it never keeps the reactor alive; best-effort so it never
+              # raises into the run path. run_detached gets no such fiber.
+              liveness_task = nil
+              if liveness_delay && liveness_delay > 0
+                liveness_task = Async(transient: true) do
+                  sleep liveness_delay
+                  emit_liveness(run_log_path, liveness_delay, err)
+                end
+              end
+
               status = child.wait
               timeout_task&.stop
+              liveness_task&.stop
 
               tasks.each(&:wait)
               timed_out ? TIMEOUT_EXIT_CODE : status.exitstatus
@@ -113,6 +131,42 @@ module Space::Architect
 
       private
 
+      # Read the run log's stream-json init event and print exactly one bounded liveness
+      # line to err. Best-effort: swallows any read/parse error so it never raises into run.
+      def emit_liveness(run_log_path, delay, err)
+        bytes = run_log_path.exist? ? run_log_path.size : 0
+        if bytes.zero?
+          err.puts "liveness: WARN no growth — run log still empty #{delay}s after dispatch"
+          return
+        end
+
+        streamed = streamed_init_model(run_log_path)
+        if streamed.nil?
+          err.puts "liveness: WARN model unverified — no stream-json init event after #{delay}s (run log #{bytes} bytes)"
+        elsif streamed == @model
+          err.puts "liveness: OK streaming model=#{streamed} (run log growing, #{bytes} bytes)"
+        else
+          err.puts "liveness: WARN model mismatch — pinned=#{@model} streamed=#{streamed} (run log growing, #{bytes} bytes)"
+        end
+      rescue StandardError
+        # Best-effort: an internal read/parse failure must never break the run.
+      end
+
+      # The model named by the stream-json init event ({"type":"system","subtype":"init",...}),
+      # or nil if no such event has been logged yet.
+      def streamed_init_model(run_log_path)
+        run_log_path.each_line do |line|
+          ev = begin
+            JSON.parse(line)
+          rescue JSON::ParserError
+            next
+          end
+          next unless ev.is_a?(Hash) && ev["type"] == "system" && ev["subtype"] == "init"
+          return ev["model"]
+        end
+        nil
+      end
+
       def argv
         args = [
           @bin, "-p",
@@ -128,17 +182,17 @@ module Space::Architect
         args
       end
 
-      def start_tee(r, log, push_url:, push_token:, push_client:)
+      def start_tee(r, log, push_url:, push_token:, push_client:, err: $stderr)
         if push_url || push_client
           body = Protocol::HTTP::Body::Writable.new(queue: Thread::SizedQueue.new(32))
-          push = Async { push_body(body, push_url: push_url, push_token: push_token, push_client: push_client) }
-          [Async { tee_pipe(r, log, body) }, push]
+          push = Async { push_body(body, push_url: push_url, push_token: push_token, push_client: push_client, err: err) }
+          [Async { tee_pipe(r, log, body, err: err) }, push]
         else
           [Async { drain_pipe(r, log) }]
         end
       end
 
-      def push_body(body, push_url:, push_token:, push_client:)
+      def push_body(body, push_url:, push_token:, push_client:, err: $stderr)
         path    = push_url ? URI.parse(push_url).path : "/"
         headers = [["content-type", "application/x-ndjson"]]
         headers << ["authorization", "Bearer #{push_token}"] if push_token
@@ -150,10 +204,10 @@ module Space::Architect
           end
         end
       rescue StandardError => e
-        $stderr.puts "push_body: transport error (best-effort, run log intact): #{e.class}: #{e.message}"
+        err.puts "push_body: transport error (best-effort, run log intact): #{e.class}: #{e.message}"
       end
 
-      def tee_pipe(r, log, body)
+      def tee_pipe(r, log, body, err: $stderr)
         pushing = true
         while (chunk = r.gets)
           log.write(chunk)
@@ -162,7 +216,7 @@ module Space::Architect
             begin
               body.write(chunk)
             rescue StandardError => e
-              $stderr.puts "tee_pipe: push write failed (best-effort, continuing log): #{e.class}: #{e.message}"
+              err.puts "tee_pipe: push write failed (best-effort, continuing log): #{e.class}: #{e.message}"
               pushing = false
             end
           end

data/lib/space_architect/templates/iteration.md.erb

@@ -27,9 +27,23 @@ Write + commit: `architect section <%= @_name %> specification --from <file>`. -
 - **Boundaries** — may-touch / must-not-touch / out-of-scope; no placeholders;
   no refactors beyond the task. (Frozen stack: cite `BRIEF §2`.)
 - **Lane plan** — 1–4 lanes, each declaring: target repo `repos/<repo>`,
-  file-touch set (overlap-checked), objective, output format, boundaries.
+  file-touch set (overlap-checked), objective, output format, boundaries. The
+  machine-readable declaration lives in the fenced ```lanes block below — the single
+  frozen source of truth `architect freeze` records and `architect provision`
+  materializes.
 - **Effort** — `think hard` … `ultrathink` per lane, with one line of why.
 
+```lanes
+# One entry per lane (1–4). The frozen out-of-bounds contract: `architect freeze`
+# writes each into space.yaml (name, repo, touch_set); `architect provision <%= @_name %>`
+# materializes the worktrees + lane branches. Remove the comment markers to activate.
+# - name: lane-a            # lane name (required)
+#   repo: my-repo           # target repo under repos/ (required)
+#   touch:                  # file globs this lane may write (required, non-empty)
+#     - lib/my_repo/**
+#     - test/my_repo_test.rb
+```
+
 ## Acceptance Criteria
 
 <!-- PROOF. Write the prose conditions of correctness (AC1, AC2, …) that the