space-architect 1.3.0 → 2.0.0.rc2

data/lib/space_architect/cli/architect.rb

@@ -1,32 +1,60 @@
 # frozen_string_literal: true
 
-module SpaceArchitect
+require "json"
+
+module Space::Architect
   module CLI
     module Architect
-      class Init < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
-
-        desc "Scaffold architect mission memory in the current space"
+      class Init < BaseCommand
+        desc "Scaffold (or top up) the architect project: ARCHITECT.md, space.yaml project block, SessionStart hook"
         argument :space, required: false, desc: "Space identifier (default: $PWD)"
 
         def call(space: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
-              mission = ArchitectMission.new(space: sp)
-              path = mission.init!
-              terminal.say "Mission ready: #{terminal.path(path)}"
+              project = ArchitectProject.new(space: sp)
+              path = project.init!
+              terminal.say "Project ready: #{terminal.path(path)}"
               CLI.record_outcome(Outcome.new(exit_code: 0))
             end
           end
         end
       end
 
-      class New < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
+      class Ground < BaseCommand
+        desc "Print grounding reads (ARCHITECT.md, BRIEF.md, in-flight iteration) to stdout"
+        argument :space, required: false, desc: "Space identifier (default: $PWD)"
+
+        def call(space: nil, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            session_cwd = parse_session_cwd_from_stdin
+            render(store.find(space)) do |sp|
+              project = ArchitectProject.new(space: sp)
+              content = project.ground(session_cwd: session_cwd)
+              terminal.say content unless content.empty?
+              CLI.record_outcome(Outcome.new(exit_code: 0))
+            end
+          end
+        end
+
+        private
+
+        # Read the session's working directory from the Claude Code hook JSON on stdin,
+        # falling back to Dir.pwd when stdin is a tty or returns nothing (e.g. direct
+        # terminal invocation, CI with /dev/null stdin, or in-process test invocation).
+        def parse_session_cwd_from_stdin
+          return Dir.pwd if $stdin.tty?
+          line = $stdin.gets
+          return Dir.pwd unless line
+          JSON.parse(line.strip)["cwd"] || Dir.pwd
+        rescue JSON::ParserError, TypeError
+          Dir.pwd
+        end
+      end
 
+      class New < BaseCommand
         desc "Scaffold the next iteration file (architecture/I<NN>-<iteration>.md)"
         argument :iteration, required: true,  desc: "Iteration name (kebab-case)"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
@@ -35,8 +63,8 @@ module SpaceArchitect
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
-              mission = ArchitectMission.new(space: sp)
-              path = mission.new_iteration!(iteration)
+              project = ArchitectProject.new(space: sp)
+              path = project.new_iteration!(iteration)
               terminal.say "Iteration scaffolded: #{terminal.path(path)}"
               CLI.record_outcome(Outcome.new(exit_code: 0))
             end
@@ -44,22 +72,19 @@ module SpaceArchitect
         end
       end
 
-      class Status < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
-
-        desc "Show architect mission state (read-only)"
+      class Status < BaseCommand
+        desc "Show architect project state (read-only)"
         argument :space, required: false, desc: "Space identifier (default: $PWD)"
 
         def call(space: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
-              mission = ArchitectMission.new(space: sp)
-              info = mission.status
+              project = ArchitectProject.new(space: sp)
+              info = project.status
               block = info[:block]
 
-              terminal.say "Mission status:     #{block['status'] || '(none)'}"
+              terminal.say "Project status:     #{block['status'] || '(none)'}"
               terminal.say "Current iteration:  #{block['current_iteration'] || '(none)'}"
 
               iterations = block["iterations"] || []
@@ -77,7 +102,14 @@ module SpaceArchitect
                   end.join(", ")
                   lanes = lane_list.any? { |l| l["variant"] } ? "variant: #{lanes_str}" : lanes_str
                   lanes = "#{lanes} → winner: #{s['winner']}" if s["winner"]
-                  [nn, s["name"], s["freeze_sha"]&.[](0, 8) || "-", lanes, s["verdict"] || "-"]
+                  verdict_str = if s["verdict"] && s["verdict"] != "pending"
+                    s["verdict"]
+                  elsif (s["lanes"] || []).any? { |l| l["integration_branch"] }
+                    "awaiting-verdict"
+                  else
+                    s["verdict"] || "-"
+                  end
+                  [nn, s["name"], s["freeze_sha"]&.[](0, 8) || "-", lanes, verdict_str]
                 end
                 terminal.say terminal.table(%w[II Iteration FreezeSHA Lanes Verdict], rows)
               end
@@ -92,11 +124,8 @@ module SpaceArchitect
         end
       end
 
-      class Freeze < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
-
-        desc "Freeze gates for an iteration"
+      class Freeze < BaseCommand
+        desc "Freeze the iteration's frozen region (Grounds/Specification/Acceptance Criteria) and record the freeze SHA"
         argument :iteration, required: true, desc: "Iteration name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
 
@@ -104,10 +133,12 @@ module SpaceArchitect
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
-              mission = ArchitectMission.new(space: sp)
-              sha = mission.freeze!(iteration)
+              project = ArchitectProject.new(space: sp)
+              warnings = []
+              sha = project.freeze!(iteration, warnings: warnings)
               terminal.say "Frozen #{iteration} at #{sha}"
-              ac = mission.acceptance_criteria(iteration)
+              warnings.each { |w| terminal.say "Warning: #{w}" }
+              ac = project.acceptance_criteria(iteration)
               unless ac.to_s.strip.empty?
                 terminal.say ""
                 terminal.say "Frozen Acceptance Criteria (quote these verbatim when judging):"
@@ -119,11 +150,8 @@ module SpaceArchitect
         end
       end
 
-      class Verify < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
-
-        desc "Post-flight mechanical checks for an iteration (reports only, no judgment)"
+      class Verify < BaseCommand
+        desc "Post-flight mechanical lane checks — frozen-untouched, no builder commits, report exists, in-bounds (reports only, no judgment)"
         argument :iteration, required: true, desc: "Iteration name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
 
@@ -131,8 +159,8 @@ module SpaceArchitect
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
-              mission = ArchitectMission.new(space: sp)
-              results = mission.verify(iteration)
+              project = ArchitectProject.new(space: sp)
+              results = project.verify(iteration)
 
               if results.empty?
                 terminal.say "No lanes recorded for iteration '#{iteration}'"
@@ -161,50 +189,69 @@ module SpaceArchitect
 
         def pass_fail(val)
           case val
-          when true  then "PASS"
-          when false then "FAIL"
-          else            "N/A"
+          when true          then "PASS"
+          when false         then "FAIL"
+          when :no_touch_set then "WARN — no touch_set recorded"
+          else                    "N/A"
           end
         end
       end
 
-      class Dispatch < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
-
+      class Dispatch < BaseCommand
         desc "Dispatch a builder for a lane (streams to build/<id>-<lane>/run.jsonl)"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :lane,      required: true,  desc: "Lane name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
-        option   :model,     default: nil,   desc: "Model to use (default: lane entry or claude-sonnet-4-6)"
-        option   :max_turns, default: "200", desc: "Max turns for the builder"
-        option   :harness,   default: nil,   desc: "Harness override (claude-code, opencode)"
-        option   :effort,    default: nil,   desc: "Reasoning effort override (opencode only; sets reasoningEffort in the model config)"
+        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)"
+        option   :effort,    default: nil,    desc: "Reasoning effort override (opencode only; sets reasoningEffort in the model config)"
+        option   :detach,    type: :boolean, default: false, desc: "Detach the builder process (returns immediately with PID; poll report for completion)"
+        option   :timeout,   default: "14400", desc: "Wall-clock timeout in seconds (0 disables; default 4h); foreground only"
+        option   :push_url,   default: nil,   desc: "HTTP endpoint for streaming push (POST body to this URL)"
+        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,
-                 max_turns: "200", harness: nil, effort: nil, **opts)
+                 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))
           handle_errors do
             render(store.find(space)) do |sp|
-              mission = ArchitectMission.new(space: sp)
-              kwargs = { max_turns: max_turns.to_i }
-              kwargs[:model]   = model   if model
-              kwargs[:harness] = harness if harness
-              kwargs[:effort]  = effort  if effort
-              res = mission.dispatch(iteration, lane, **kwargs)
-              terminal.say "Run log: #{terminal.path(res[:run_log])}"
-              terminal.say "Report:  #{terminal.path(res[:report])}"
-              terminal.say "Builder exited with status #{res[:exit_code]}"
-              CLI.record_outcome(Outcome.new(exit_code: res[:exit_code]))
+              project = ArchitectProject.new(space: sp)
+              kwargs = { max_turns: max_turns.to_i, detach: detach }
+              kwargs[:model]      = model           if model
+              kwargs[:harness]    = harness         if harness
+              kwargs[:effort]     = effort          if effort
+              kwargs[:timeout]    = timeout.to_i    unless detach
+              kwargs[:push_url]   = push_url        if push_url
+              kwargs[:push_token] = push_token      if push_token
+              kwargs[:push_host]  = push_host       if push_host
+              res = project.dispatch(iteration, lane, **kwargs)
+              if detach
+                terminal.say "PID:     #{res[:pid]}"
+                terminal.say "Run log: #{terminal.path(res[:run_log])}"
+                terminal.say "Report:  #{terminal.path(res[:report])}"
+                terminal.say "Dispatched detached — poll #{terminal.path(res[:report])} for completion"
+                CLI.record_outcome(Outcome.new(exit_code: 0))
+              elsif res[:timed_out]
+                terminal.say "Run log: #{terminal.path(res[:run_log])}"
+                terminal.say "Report:  #{terminal.path(res[:report])}"
+                terminal.say "Builder TIMED OUT after #{timeout}s — process group killed. Re-dispatch (lanes are cheap)."
+                CLI.record_outcome(Outcome.new(exit_code: res[:exit_code]))
+              else
+                terminal.say "Run log: #{terminal.path(res[:run_log])}"
+                terminal.say "Report:  #{terminal.path(res[:report])}"
+                terminal.say "Ingest URL:  #{res[:push_url]}" if res[:push_url]
+                terminal.say "Builder exited with status #{res[:exit_code]}"
+                CLI.record_outcome(Outcome.new(exit_code: res[:exit_code]))
+              end
             end
           end
         end
       end
 
-      class Section < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
-
+      class Section < BaseCommand
         desc "Write a section of the iteration file and commit it (one call)"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :section,   required: true,  desc: "Section: grounds, specification, prompt, verdict"
@@ -220,8 +267,8 @@ module SpaceArchitect
           handle_errors do
             content = read_section_body(from: from, body: body, stdin: stdin)
             render(store.find(space)) do |sp|
-              mission = ArchitectMission.new(space: sp)
-              res = mission.write_section!(iteration, section, body: content, append: append, lane: lane)
+              project = ArchitectProject.new(space: sp)
+              res = project.write_section!(iteration, section, body: content, append: append, lane: lane)
               if res[:committed]
                 terminal.say "Committed #{res[:heading]} → #{res[:sha][0, 8]}"
                 terminal.say res[:diffstat] unless res[:diffstat].empty?
@@ -239,14 +286,43 @@ module SpaceArchitect
           return File.read(from) if from
           return body if body
           return $stdin.read if stdin
-          raise SpaceArchitect::Error, "provide the section body via --from <file>, --body <text>, or --stdin"
+          raise Space::Core::Error, "provide the section body via --from <file>, --body <text>, or --stdin"
         end
       end
 
-      class Evidence < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
+      class Verdict < BaseCommand
+        desc "Record the architect's verdict decision (continue or kill) and write ## Verdict prose"
+        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"
 
+        def call(iteration:, decision:, space: nil, from: nil, body: nil, stdin: false, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            content = read_section_body(from: from, body: body, stdin: stdin)
+            render(store.find(space)) do |sp|
+              project = ArchitectProject.new(space: sp)
+              res = project.record_verdict!(iteration, decision: decision, body: content)
+              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"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
@@ -256,8 +332,8 @@ module SpaceArchitect
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
-              mission = ArchitectMission.new(space: sp)
-              res = mission.transcribe_evidence!(iteration, lane: lane)
+              project = ArchitectProject.new(space: sp)
+              res = project.transcribe_evidence!(iteration, lane: lane)
               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)."
@@ -267,10 +343,7 @@ module SpaceArchitect
         end
       end
 
-      class Merge < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
-
+      class Merge < BaseCommand
         desc "Integrate ONE judged-passing lane (merges --no-ff; runs no gates, makes no verdict)"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :lane,      required: true,  desc: "Lane name (architect-judged passing)"
@@ -281,8 +354,8 @@ module SpaceArchitect
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
-              mission = ArchitectMission.new(space: sp)
-              r = mission.merge_lane!(iteration, lane, message: message)
+              project = ArchitectProject.new(space: sp)
+              r = project.merge_lane!(iteration, lane, message: message)
               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."
@@ -292,10 +365,7 @@ module SpaceArchitect
         end
       end
 
-      class Integrate < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
-
+      class Integrate < BaseCommand
         desc "Integrate the architect-supplied set of passing lanes, in order (stops on conflict)"
         argument :iteration, required: true,  desc: "Iteration name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
@@ -306,9 +376,9 @@ module SpaceArchitect
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
-              mission = ArchitectMission.new(space: sp)
+              project = ArchitectProject.new(space: sp)
               lane_names = lanes.to_s.split(",").map(&:strip).reject(&:empty?)
-              results = mission.integrate!(iteration, lanes: lane_names, teardown: teardown)
+              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]})"
               end
@@ -319,11 +389,29 @@ module SpaceArchitect
         end
       end
 
-      class Gate < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
+      class Land < BaseCommand
+        desc "Generate the end-of-project PR command (no push, no gh — prints gh pr create)"
+        argument :space, required: false, desc: "Space identifier (default: $PWD)"
 
-        desc "Run the frozen Acceptance Criteria gate commands and stream raw output (no PASS/FAIL)"
+        def call(space: nil, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            render(store.find(space)) do |sp|
+              project = ArchitectProject.new(space: sp)
+              results = project.land
+              results.each do |r|
+                terminal.say r[:context]
+                terminal.say r[:command]
+                terminal.say "Body: #{terminal.path(r[:body_file])}"
+              end
+              CLI.record_outcome(Outcome.new(exit_code: 0))
+            end
+          end
+        end
+      end
+
+      class Gate < BaseCommand
+        desc "Run the frozen Acceptance Criteria gate commands and report PASS/FAIL"
         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)"
@@ -332,26 +420,26 @@ module SpaceArchitect
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
-              mission = ArchitectMission.new(space: sp)
-              results = mission.run_gates(iteration, lane: lane)
+              project = ArchitectProject.new(space: sp)
+              results = project.run_gates(iteration, lane: lane)
               results.each do |r|
+                marker = r[:status] == :pass ? "PASS" : "FAIL"
                 terminal.say ""
-                terminal.say "── #{r[:ac].empty? ? "(gate)" : r[:ac]}: #{r[:command]}  (exit #{r[:exit_code]})"
+                terminal.say "── #{r[:ac].empty? ? "(gate)" : r[:ac]}: #{r[:cmd]}  (exit #{r[:exit_code]})  [#{marker}]"
+                terminal.say "   reason: #{r[:reason]}" if r[:status] == :fail && !r[:reason].to_s.empty?
                 terminal.say r[:stdout].rstrip unless r[:stdout].strip.empty?
                 terminal.say r[:stderr].rstrip unless r[:stderr].strip.empty?
               end
               terminal.say ""
-              terminal.say "Raw gate output above — the PASS/FAIL/INVALID verdict is yours, read against the frozen thresholds."
-              CLI.record_outcome(Outcome.new(exit_code: 0))
+              terminal.say "Mechanical gate results above; the Acceptance-Criteria verdict — necessary, not sufficient — remains the architect's."
+              any_fail = results.any? { |r| r[:status] == :fail }
+              CLI.record_outcome(Outcome.new(exit_code: any_fail ? 1 : 0))
             end
           end
         end
       end
 
-      class InstallSkills < Dry::CLI::Command
-        include GlobalOptions
-        include Helpers
-
+      class InstallSkills < BaseCommand
         desc "Install bundled skills (architect, architect-research, architect-vocabulary) for a harness"
         option :provider, default: "claude", desc: "Harness: claude, codex, opencode, pi"
         option :project, type: :boolean, default: false, desc: "Install to CWD instead of global"
@@ -373,34 +461,8 @@ module SpaceArchitect
         end
       end
 
-      module Brief
-        class New < Dry::CLI::Command
-          include GlobalOptions
-          include Helpers
-
-          desc "Scaffold the durable mission brief (architecture/BRIEF.md)"
-          argument :space, required: false, desc: "Space identifier (default: $PWD)"
-          option   :force, type: :boolean, default: false, desc: "Overwrite an existing BRIEF.md"
-
-          def call(space: nil, force: false, **opts)
-            setup_terminal(**opts.slice(:color, :colors))
-            handle_errors do
-              render(store.find(space)) do |sp|
-                mission = ArchitectMission.new(space: sp)
-                path = mission.brief_new!(force: force)
-                terminal.say "Brief ready: #{terminal.path(path)}"
-                CLI.record_outcome(Outcome.new(exit_code: 0))
-              end
-            end
-          end
-        end
-      end
-
       module Worktree
-        class Add < Dry::CLI::Command
-          include GlobalOptions
-          include Helpers
-
+        class Add < BaseCommand
           desc "Create a worktree for a lane"
           argument :repo,      required: true, desc: "Repo name (under repos/)"
           argument :iteration, required: true, desc: "Iteration name"
@@ -415,9 +477,9 @@ module SpaceArchitect
             setup_terminal(**opts.slice(:color, :colors))
             handle_errors do
               render(store.find) do |sp|
-                mission = ArchitectMission.new(space: sp)
+                project = ArchitectProject.new(space: sp)
                 touch_set = touch ? touch.split(",").map(&:strip).reject(&:empty?) : nil
-                result = mission.worktree_add(repo, iteration, lane, base: base,
+                result = project.worktree_add(repo, iteration, lane, base: base,
                                              harness: harness, model: model, effort: effort, touch: touch_set)
                 terminal.say "Worktree: #{terminal.path(result[:worktree])}"
                 terminal.say "Base SHA: #{result[:base_sha]}"
@@ -427,10 +489,7 @@ module SpaceArchitect
           end
         end
 
-        class Remove < Dry::CLI::Command
-          include GlobalOptions
-          include Helpers
-
+        class Remove < BaseCommand
           desc "Remove a lane worktree"
           argument :iteration, required: true, desc: "Iteration name"
           argument :lane,      required: true, desc: "Lane name"
@@ -439,8 +498,8 @@ module SpaceArchitect
             setup_terminal(**opts.slice(:color, :colors))
             handle_errors do
               render(store.find) do |sp|
-                mission = ArchitectMission.new(space: sp)
-                mission.worktree_remove(iteration, lane)
+                project = ArchitectProject.new(space: sp)
+                project.worktree_remove(iteration, lane)
                 terminal.say "Removed worktree for #{iteration}/#{lane}"
                 CLI.record_outcome(Outcome.new(exit_code: 0))
               end
@@ -448,18 +507,15 @@ module SpaceArchitect
           end
         end
 
-        class List < Dry::CLI::Command
-          include GlobalOptions
-          include Helpers
-
+        class List < BaseCommand
           desc "List active architect worktrees"
 
           def call(**opts)
             setup_terminal(**opts.slice(:color, :colors))
             handle_errors do
               render(store.find) do |sp|
-                mission = ArchitectMission.new(space: sp)
-                worktrees = mission.worktree_list
+                project = ArchitectProject.new(space: sp)
+                worktrees = project.worktree_list
                 if worktrees.empty?
                   terminal.say "No active architect worktrees"
                 else
@@ -473,10 +529,7 @@ module SpaceArchitect
       end
 
       module Variant
-        class Add < Dry::CLI::Command
-          include GlobalOptions
-          include Helpers
-
+        class Add < BaseCommand
           desc "Create a variant set (competing lanes over one frozen spec)"
           argument :repo,      required: true,  desc: "Repo name (under repos/)"
           argument :iteration, required: true,  desc: "Iteration name"
@@ -495,8 +548,8 @@ module SpaceArchitect
                   [harness, model]
                 end
 
-                mission = ArchitectMission.new(space: sp)
-                variants = mission.variant_add(repo, iteration, parsed_pairs, base: base, prompt: prompt)
+                project = ArchitectProject.new(space: sp)
+                variants = project.variant_add(repo, iteration, parsed_pairs, base: base, prompt: prompt)
                 variants.each do |v|
                   terminal.say "#{v[:name]} · #{v[:harness]} · #{v[:model] || "(default)"} · #{terminal.path(v[:worktree])}"
                 end
@@ -506,10 +559,7 @@ module SpaceArchitect
           end
         end
 
-        class Promote < Dry::CLI::Command
-          include GlobalOptions
-          include Helpers
-
+        class Promote < BaseCommand
           desc "Promote one variant of a variant set as the winner"
           argument :iteration, required: true,  desc: "Iteration name"
           argument :winner,    required: true,  desc: "Variant lane name to promote (e.g. v02)"
@@ -519,8 +569,8 @@ module SpaceArchitect
             setup_terminal(**opts.slice(:color, :colors))
             handle_errors do
               render(store.find(space)) do |sp|
-                mission = ArchitectMission.new(space: sp)
-                result = mission.variant_promote(iteration, winner)
+                project = ArchitectProject.new(space: sp)
+                result = project.variant_promote(iteration, winner)
                 if result[:discarded].any?
                   terminal.say "Promoted #{result[:winner]} (discarded: #{result[:discarded].join(', ')})"
                 else
@@ -532,10 +582,7 @@ module SpaceArchitect
           end
         end
 
-        class Compare < Dry::CLI::Command
-          include GlobalOptions
-          include Helpers
-
+        class Compare < BaseCommand
           desc "Compare variants of an iteration's variant set (read-only)"
           argument :iteration, required: true,  desc: "Iteration name"
           argument :space,     required: false, desc: "Space identifier (default: $PWD)"
@@ -544,8 +591,8 @@ module SpaceArchitect
             setup_terminal(**opts.slice(:color, :colors))
             handle_errors do
               render(store.find(space)) do |sp|
-                mission = ArchitectMission.new(space: sp)
-                info = mission.variant_compare(iteration)
+                project = ArchitectProject.new(space: sp)
+                info = project.variant_compare(iteration)
 
                 terminal.say "Variant comparison: #{iteration} (freeze #{info[:freeze_sha]&.[](0, 8) || "-"})"
                 terminal.say "Winner: #{info[:winner] || '(none)'}"
@@ -569,32 +616,55 @@ module SpaceArchitect
           end
         end
       end
+
+      module Brief
+        class New < BaseCommand
+          desc "Scaffold the durable project brief (architecture/BRIEF.md)"
+          argument :space, required: false, desc: "Space identifier (default: $PWD)"
+          option   :force, type: :boolean, default: false, desc: "Overwrite an existing BRIEF.md"
+
+          def call(space: nil, force: false, **opts)
+            setup_terminal(**opts.slice(:color, :colors))
+            handle_errors do
+              render(store.find(space)) do |sp|
+                project = ArchitectProject.new(space: sp)
+                path = project.brief_new!(force: force)
+                terminal.say "Brief ready: #{terminal.path(path)}"
+                CLI.record_outcome(Outcome.new(exit_code: 0))
+              end
+            end
+          end
+        end
+      end
     end
   end
 end
 
-SpaceArchitect::CLI::Registry.register "init",   SpaceArchitect::CLI::Architect::Init
-SpaceArchitect::CLI::Registry.register "new",    SpaceArchitect::CLI::Architect::New
-SpaceArchitect::CLI::Registry.register "status", SpaceArchitect::CLI::Architect::Status
-SpaceArchitect::CLI::Registry.register "freeze", SpaceArchitect::CLI::Architect::Freeze
-SpaceArchitect::CLI::Registry.register "verify", SpaceArchitect::CLI::Architect::Verify
-SpaceArchitect::CLI::Registry.register "dispatch", SpaceArchitect::CLI::Architect::Dispatch
-SpaceArchitect::CLI::Registry.register "section",   SpaceArchitect::CLI::Architect::Section
-SpaceArchitect::CLI::Registry.register "evidence",  SpaceArchitect::CLI::Architect::Evidence
-SpaceArchitect::CLI::Registry.register "merge",     SpaceArchitect::CLI::Architect::Merge
-SpaceArchitect::CLI::Registry.register "integrate", SpaceArchitect::CLI::Architect::Integrate
-SpaceArchitect::CLI::Registry.register "gate",      SpaceArchitect::CLI::Architect::Gate
-SpaceArchitect::CLI::Registry.register "install-skills", SpaceArchitect::CLI::Architect::InstallSkills
-SpaceArchitect::CLI::Registry.register "brief" do |b|
-  b.register "new", SpaceArchitect::CLI::Architect::Brief::New
+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 "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
+Space::Architect::CLI::Registry.register "evidence",  Space::Architect::CLI::Architect::Evidence
+Space::Architect::CLI::Registry.register "merge",     Space::Architect::CLI::Architect::Merge
+Space::Architect::CLI::Registry.register "integrate", Space::Architect::CLI::Architect::Integrate
+Space::Architect::CLI::Registry.register "land",      Space::Architect::CLI::Architect::Land
+Space::Architect::CLI::Registry.register "gate",      Space::Architect::CLI::Architect::Gate
+Space::Architect::CLI::Registry.register "install-skills", Space::Architect::CLI::Architect::InstallSkills
+Space::Architect::CLI::Registry.register "brief" do |b|
+  b.register "new", Space::Architect::CLI::Architect::Brief::New
 end
-SpaceArchitect::CLI::Registry.register "worktree" do |wt|
-  wt.register "add",    SpaceArchitect::CLI::Architect::Worktree::Add
-  wt.register "remove", SpaceArchitect::CLI::Architect::Worktree::Remove
-  wt.register "list",   SpaceArchitect::CLI::Architect::Worktree::List
+Space::Architect::CLI::Registry.register "worktree" do |wt|
+  wt.register "add",    Space::Architect::CLI::Architect::Worktree::Add
+  wt.register "remove", Space::Architect::CLI::Architect::Worktree::Remove
+  wt.register "list",   Space::Architect::CLI::Architect::Worktree::List
 end
-SpaceArchitect::CLI::Registry.register "variant" do |v|
-  v.register "add",     SpaceArchitect::CLI::Architect::Variant::Add
-  v.register "promote", SpaceArchitect::CLI::Architect::Variant::Promote
-  v.register "compare", SpaceArchitect::CLI::Architect::Variant::Compare
+Space::Architect::CLI::Registry.register "variant" do |v|
+  v.register "add",     Space::Architect::CLI::Architect::Variant::Add
+  v.register "promote", Space::Architect::CLI::Architect::Variant::Promote
+  v.register "compare", Space::Architect::CLI::Architect::Variant::Compare
 end