space-architect 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec439ebdc7e044a032f6a6736166d38dcc38b965ee26c03a2a27b1f95c9f5b2e
-  data.tar.gz: 3b242e89b02bd5e1aa69389aad16eb3e221da0fd000b3e7587ccce02cb565d32
+  metadata.gz: 62235ba54045a8883eaaaced2fef7c231d45ad6cb363dda9256ec65692b6023b
+  data.tar.gz: 7d90b91f3a247c20cc273c332807c65c8e500dc62bffaec1a35076263eb969a2
 SHA512:
-  metadata.gz: 58deb069cc61cf59161122547407699f03072cea024608e9954b568f409c2f11afe241aa585378010dfd5fe9df53aeb83f68945418482d45ba9d312b76297a85
-  data.tar.gz: 59c12540afc15984bc74d67051f4efc59a360e0fb93acd00bae252fcc2d7b139e2c3f63e692cd5980e0cbc1b3f378d141520b985a41a57c22a2ef08894be914d
+  metadata.gz: 042c966a4dbf2075abaeaffb23ad9e426a4421ffcd9621ff238d2f074771e5d65bc7030775fe1733dde40030dc0aff37b84c35e13a035ac29705e3e42667c96e
+  data.tar.gz: f633823970cefde990131c1cce4a415bd8f767030120438ae7bd76220653ab0c42580352de48ab2c34b82f5fd4cc597c6ba14410603e66de6a3dd86f89e197ee

data/lib/space_architect/architect_mission.rb

@@ -17,6 +17,26 @@ module SpaceArchitect
     # from the appended-after-freeze sections (Builder Prompt/Report/Verdict).
     FROZEN_BOUNDARY = /^## Builder Prompt/
 
+    # Sections the architect writes (and the CLI commits) via `architect section`.
+    # Acceptance Criteria is intentionally absent — it is set by `architect freeze`,
+    # the one code path that creates the freeze commit. Builder Report has its own
+    # command (`architect evidence`) because it is transcribed verbatim from scratch.
+    # `frozen: true` sections live above the freeze boundary and are refused once frozen.
+    SECTIONS = {
+      "grounds" => { heading: "## Grounds", message: "grounds", frozen: true },
+      "specification" => { heading: "## Specification", message: "specification", frozen: true },
+      "prompt" => { heading: "## Builder Prompt", message: "dispatched", frozen: false },
+      "verdict" => { heading: "## Verdict", message: "verdict", frozen: false }
+    }.freeze
+
+    # The fixed top-level section headings. Section boundaries are detected against
+    # this set (not any "## " line), so a verbatim Builder Report containing its own
+    # "## " headings cannot fool the parser.
+    KNOWN_HEADINGS = [
+      "## Grounds", "## Specification", "## Acceptance Criteria",
+      "## Builder Prompt", "## Builder Report", "## Verdict"
+    ].freeze
+
     def initialize(space:)
       @space = space
     end
@@ -133,7 +153,221 @@ module SpaceArchitect
       sha
     end
 
-    def worktree_add(repo, iteration, lane, base: nil, harness: "claude-code", model: nil, variant: false, effort: nil)
+    # Scaffold the durable, section-numbered mission brief at architecture/BRIEF.md
+    # and commit it. The brief is the stable cross-iteration address space iterations
+    # cite as "BRIEF §N"; it lives outside the per-iteration freeze region.
+    def brief_new!(force: false)
+      brief_path = space.path.join("architecture", "BRIEF.md")
+      if brief_path.exist? && !force
+        raise Error, "architecture/BRIEF.md already exists — edit it directly (idempotent guard), or pass --force to overwrite"
+      end
+
+      FileUtils.mkdir_p(brief_path.dirname)
+      brief_path.write(render_brief)
+      git_run("-C", space.path.to_s, "add", "architecture/BRIEF.md")
+      git_run("-C", space.path.to_s, "commit", "-m", "Add mission brief") if staged_changes?
+      brief_path
+    end
+
+    # Write one section of the iteration file and commit it with the canonical
+    # per-section message, in one call. Refuses to write a frozen section
+    # (Grounds/Specification) once the iteration is frozen. Acceptance Criteria is
+    # NOT writable here (use freeze); Builder Report is not here (use evidence).
+    def write_section!(iteration, section, body:, append: false, lane: nil)
+      spec = SECTIONS[section]
+      unless spec
+        raise Error,
+          "Unknown section '#{section}' — one of: #{SECTIONS.keys.join(', ')}. " \
+          "(Acceptance Criteria is set by `architect freeze`; Builder Report by `architect evidence`.)"
+      end
+
+      entry = slice_entry(iteration)
+      rel = entry["file"]
+      path = space.path.join(rel)
+      raise Error, "#{rel} does not exist — run `architect new #{iteration}` first" unless path.exist?
+
+      if spec[:frozen] && entry["freeze_sha"]
+        raise Error,
+          "#{spec[:heading]} is frozen for #{iteration} (freeze #{entry["freeze_sha"][0, 8]}) — " \
+          "frozen sections are read-only after the freeze commit. Open a new iteration to change the contract."
+      end
+
+      block = lane ? "### #{lane}\n\n#{body.strip}" : body.strip
+      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 }
+    end
+
+    # Transcribe a lane's scratch report (build/<id>[-<lane>]/report.md) VERBATIM into
+    # the Builder Report section and commit. Byte-for-byte: no summarization, no judgment.
+    def transcribe_evidence!(iteration, lane: nil)
+      entry = slice_entry(iteration)
+      rel = entry["file"]
+      path = space.path.join(rel)
+      raise Error, "#{rel} does not exist — run `architect new #{iteration}` first" unless path.exist?
+
+      id = iteration_id(entry)
+      report = space.path.join("build", lane ? "#{id}-#{lane}" : id, "report.md")
+      raise Error, "builder report not found: #{report}" unless report.exist?
+      raw = report.read
+      raise Error, "builder report is empty: #{report}" if raw.strip.empty?
+
+      block = lane ? "### #{lane}\n\n#{raw.rstrip}" : raw.rstrip
+      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?
+      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
+      { sha: head.strip, lines: raw.lines.count, status_line: status_line, lane: lane }
+    end
+
+    # Read the Acceptance Criteria section text, by default from the freeze commit
+    # (so the architect quotes the frozen gates, never a drifted working copy).
+    def acceptance_criteria(iteration, ref: :freeze)
+      entry = slice_entry(iteration)
+      rel = entry["file"]
+      ref = entry["freeze_sha"] if ref == :freeze
+      text =
+        if ref
+          out, _, st = git_capture("-C", space.path.to_s, "show", "#{ref}:#{rel}")
+          raise Error, "could not read #{rel} at #{ref}" unless st.success?
+          out
+        else
+          space.path.join(rel).read
+        end
+      section_body(text, "## Acceptance Criteria")
+    end
+
+    # Integrate ONE architect-judged-passing lane: commit the builder's working tree on
+    # the lane branch, then merge --no-ff into the repo's lane/<id> integration branch.
+    # Runs NO gates and makes NO pass/fail decision. Refuses a mechanically-failing lane
+    # (builder commits / out-of-bounds) and aborts cleanly on a merge conflict.
+    def merge_lane!(iteration, lane, message: nil)
+      entry = slice_entry(iteration)
+      lane_entry = (entry["lanes"] || []).find { |l| l["name"] == lane }
+      raise Error, "No lane '#{lane}' recorded for iteration '#{iteration}'" unless lane_entry
+
+      checks = lane_mechanical_checks(entry, lane_entry)
+      if checks[:no_builder_commits] == false
+        raise Error, "Lane '#{lane}' has builder commits — the worktree is tampered (hard rule 7). Reset and re-dispatch; do not merge."
+      end
+      if checks[:in_bounds] == false
+        raise Error, "Lane '#{lane}' wrote outside its declared touch set — out-of-bounds fails the lane. Reset and re-dispatch."
+      end
+
+      repo = lane_entry["repo"]
+      repo_path = space.path.join("repos", repo)
+      id = iteration_id(entry)
+      wt_path = space.path.join(lane_entry["worktree"] || "build/#{id}-#{lane}/wt")
+      raise Error, "Worktree directory does not exist: #{wt_path}" unless wt_path.exist?
+      base_sha = lane_entry["base_sha"]
+      lane_branch = "lane/#{id}-#{lane}"
+      integration_branch = "lane/#{id}"
+
+      status_out, = git_capture("-C", wt_path.to_s, "status", "--porcelain")
+      raise Error, "Lane '#{lane}' worktree has no changes to integrate." if status_out.strip.empty?
+
+      git_run("-C", wt_path.to_s, "add", "-A")
+      git_run("-C", wt_path.to_s, "commit", "-m", message || "lane #{lane}: integrate")
+
+      _o, _e, exists = git_capture("-C", repo_path.to_s, "rev-parse", "--verify", "--quiet", integration_branch)
+      if exists.success?
+        git_run("-C", repo_path.to_s, "checkout", integration_branch)
+      else
+        git_run("-C", repo_path.to_s, "checkout", "-b", integration_branch, base_sha)
+      end
+
+      _mo, merr, mst = git_capture("-C", repo_path.to_s, "merge", "--no-ff", lane_branch, "-m", "Merge #{lane_branch}")
+      unless mst.success?
+        conflicts, = git_capture("-C", repo_path.to_s, "diff", "--name-only", "--diff-filter=U")
+        git_capture("-C", repo_path.to_s, "merge", "--abort")
+        raise Error,
+          "Merge conflict integrating lane '#{lane}' (#{conflicts.split.join(", ")}) — the lane plan was " \
+          "not disjoint = a spec defect. Kill the conflicting lane and re-spec; do not hand-resolve. #{merr.strip}"
+      end
+
+      merge_sha, = git_capture("-C", repo_path.to_s, "rev-parse", "HEAD")
+      diffstat, = git_capture("-C", repo_path.to_s, "diff", "--stat", "#{base_sha}..HEAD")
+
+      update_architect_block do |b|
+        (b["iterations"] || []).each do |s|
+          next unless s["name"] == iteration
+          (s["lanes"] || []).each { |l| l["integration_branch"] = integration_branch if l["name"] == lane }
+        end
+        b
+      end
+
+      { lane: lane, repo: repo, integration_branch: integration_branch,
+        merge_sha: merge_sha.strip, base_sha: base_sha, diffstat: diffstat.strip, gates_run: false }
+    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 Error, "No lanes given to integrate" if lanes.nil? || lanes.empty?
+
+      merged = []
+      lanes.each do |lane|
+        merged << merge_lane!(iteration, lane)
+      rescue Error => e
+        done = merged.map { |m| m[:lane] }.join(", ")
+        raise 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
+      merged
+    end
+
+    # Run the iteration's frozen Acceptance Criteria gate commands and stream raw
+    # stdout/stderr + exit codes. A path-resolving RUNNER ONLY — no threshold
+    # comparison, no PASS/FAIL. The verdict is the architect reading this output.
+    def run_gates(iteration, lane: nil)
+      entry = slice_entry(iteration)
+      freeze_sha = entry["freeze_sha"]
+      raise Error, "Iteration '#{iteration}' is not frozen — freeze before running gates." unless freeze_sha
+      rel = entry["file"]
+
+      text, _, st = git_capture("-C", space.path.to_s, "show", "#{freeze_sha}:#{rel}")
+      raise Error, "could not read frozen #{rel} at #{freeze_sha[0, 8]}" unless st.success?
+      commands = acceptance_criteria_commands(text)
+      raise Error, "no gate commands found in the frozen Acceptance Criteria of #{rel}" if commands.empty?
+
+      lanes = entry["lanes"] || []
+      dir =
+        if lane
+          le = lanes.find { |l| l["name"] == lane }
+          raise Error, "No lane '#{lane}' recorded for iteration '#{iteration}'" unless le
+          space.path.join(le["worktree"] || "build/#{iteration_id(entry)}-#{lane}/wt")
+        else
+          repo = lanes.first&.dig("repo")
+          raise Error, "No lane/repo recorded for '#{iteration}' — cannot resolve a directory to run gates in" unless repo
+          space.path.join("repos", repo)
+        end
+      raise Error, "directory does not exist: #{dir}" unless dir.exist?
+
+      commands.map do |row|
+        out, err, status = Open3.capture3(row[:command], chdir: dir.to_s)
+        { ac: row[:ac], command: row[:command], stdout: out, stderr: err, exit_code: status.exitstatus, dir: dir }
+      end
+    end
+
+    def worktree_add(repo, iteration, lane, base: nil, harness: "claude-code", model: nil, variant: false, effort: nil, touch: nil)
       if harness.to_s == "opencode" && (model.nil? || model == Harness::CLAUDE_DEFAULT_MODEL)
         raise Error,
           "Pass --model when using --harness opencode " \
@@ -177,6 +411,7 @@ module SpaceArchitect
             "variant" => variant
           }
           lane_entry["effort"] = effort if effort
+          lane_entry["touch_set"] = Array(touch) if touch && !Array(touch).empty?
           lanes << lane_entry
           s["lanes"] = lanes
         end
@@ -295,41 +530,8 @@ module SpaceArchitect
 
     def verify(iteration)
       entry = slice_entry(iteration)
-      freeze_sha = entry["freeze_sha"]
-      rel = entry["file"]
-      lanes = entry["lanes"] || []
-
-      lanes.map do |lane|
-        lane_name = lane["name"]
-        base_sha = lane["base_sha"]
-        wt_path = space.path.join(lane["worktree"] || "build/#{iteration_id(entry)}-#{lane_name}/wt")
-        touch_set = lane["touch_set"] || []
-
-        checks = {}
-
-        # (a) frozen sections of the iteration file untouched since freeze
-        checks[:frozen_untouched] = if freeze_sha && rel
-          !frozen_region_changed?(freeze_sha, rel)
-        end
-
-        # (b) no builder commits in the worktree
-        log_out, = git_capture("-C", wt_path.to_s, "log", "#{base_sha}..")
-        checks[:no_builder_commits] = log_out.strip.empty?
-
-        # (c) builder's scratch report exists and is non-empty
-        report = space.path.join("build", "#{iteration_id(entry)}-#{lane_name}", "report.md")
-        checks[:report_exists] = report.exist? && !report.read.strip.empty?
-
-        # (d) in-bounds: changed paths ⊆ touch_set (nil if no touch_set recorded)
-        checks[:in_bounds] = if touch_set.empty?
-          nil
-        else
-          status_out, = git_capture("-C", wt_path.to_s, "status", "--porcelain")
-          changed = status_out.lines.map { |l| l[3..].strip }
-          changed.all? { |f| touch_set.any? { |g| File.fnmatch(g, f) } }
-        end
-
-        { lane: lane_name, repo: lane["repo"], checks: checks }
+      (entry["lanes"] || []).map do |lane|
+        { lane: lane["name"], repo: lane["repo"], checks: lane_mechanical_checks(entry, lane) }
       end
     end
 
@@ -394,6 +596,107 @@ module SpaceArchitect
       frozen_region(old) != frozen_region(current)
     end
 
+    # The four per-lane post-flight checks, shared by `verify` (reports) and
+    # `merge_lane!` (refuses on failure) so the two can never drift.
+    def lane_mechanical_checks(entry, lane)
+      freeze_sha = entry["freeze_sha"]
+      rel = entry["file"]
+      lane_name = lane["name"]
+      base_sha = lane["base_sha"]
+      wt_path = space.path.join(lane["worktree"] || "build/#{iteration_id(entry)}-#{lane_name}/wt")
+      touch_set = lane["touch_set"] || []
+
+      checks = {}
+
+      # (a) frozen sections of the iteration file untouched since freeze
+      checks[:frozen_untouched] = (!frozen_region_changed?(freeze_sha, rel) if freeze_sha && rel)
+
+      # (b) no builder commits in the worktree
+      log_out, = git_capture("-C", wt_path.to_s, "log", "#{base_sha}..")
+      checks[:no_builder_commits] = log_out.strip.empty?
+
+      # (c) builder's scratch report exists and is non-empty
+      report = space.path.join("build", "#{iteration_id(entry)}-#{lane_name}", "report.md")
+      checks[:report_exists] = report.exist? && !report.read.strip.empty?
+
+      # (d) in-bounds: changed paths ⊆ touch_set (nil if no touch_set recorded)
+      checks[:in_bounds] = if touch_set.empty?
+        nil
+      else
+        status_out, = git_capture("-C", wt_path.to_s, "status", "--porcelain")
+        changed = status_out.lines.map { |l| l[3..].to_s.strip }
+        changed.all? { |f| touch_set.any? { |g| File.fnmatch(g, f) } }
+      end
+
+      checks
+    end
+
+    # Replace (or, with append:, extend) the body of a "## Heading" section, leaving
+    # every other section byte-untouched. Append replaces a placeholder body (only a
+    # template comment) the first time, then stacks subsections after it.
+    def replace_section_body(text, heading, new_block, append:)
+      lines = text.lines
+      start = lines.index { |l| l.chomp == heading }
+      raise Error, "section heading '#{heading}' not found in iteration file" unless start
+
+      finish = ((start + 1)...lines.length).find { |i| KNOWN_HEADINGS.include?(lines[i].chomp) } || lines.length
+      body = lines[(start + 1)...finish].join
+
+      new_body =
+        if append && !placeholder_body?(body)
+          "#{body.strip}\n\n#{new_block.strip}"
+        else
+          new_block.strip
+        end
+
+      prefix = lines[0..start].join.rstrip
+      suffix = lines[finish..].to_a.join.strip
+      parts = [prefix, "", new_body]
+      parts += ["", suffix] unless suffix.empty?
+      "#{parts.join("\n")}\n"
+    end
+
+    # A section body is a placeholder when it holds nothing but a leading HTML
+    # comment (the scaffold's guidance) and whitespace.
+    def placeholder_body?(body)
+      body.strip.sub(/\A<!--.*?-->/m, "").strip.empty?
+    end
+
+    # The text between "## Heading" and the next "## " heading (nil if absent).
+    def section_body(text, heading)
+      lines = text.lines
+      start = lines.index { |l| l.chomp == heading }
+      return nil unless start
+      finish = ((start + 1)...lines.length).find { |i| KNOWN_HEADINGS.include?(lines[i].chomp) } || lines.length
+      lines[(start + 1)...finish].join.strip
+    end
+
+    # Parse the Acceptance Criteria markdown table into [{ac:, command:}]. Reads the
+    # Command column by header name (so an added "Brief §" column doesn't shift it);
+    # strips surrounding backticks and unescapes \| inside a cell.
+    def acceptance_criteria_commands(text)
+      body = section_body(text, "## Acceptance Criteria")
+      return [] unless body
+      rows = body.lines.map(&:strip).select { |l| l.start_with?("|") }
+      return [] if rows.length < 2
+
+      header = split_md_row(rows[0])
+      cmd_idx = header.index { |c| c.downcase == "command" } || 1
+      ac_idx = header.index { |c| c.downcase.start_with?("ac") } || 0
+
+      rows[2..].to_a.filter_map do |line|
+        cells = split_md_row(line)
+        command = cells[cmd_idx].to_s.gsub(/\A`+|`+\z/, "").strip
+        next if command.empty?
+        { ac: cells[ac_idx].to_s.strip, command: command }
+      end
+    end
+
+    def split_md_row(line)
+      inner = line.strip.sub(/\A\|/, "").sub(/\|\z/, "")
+      inner.split(/(?<!\\)\|/).map { |c| c.strip.gsub('\\|', "|") }
+    end
+
     def staged_changes?
       _o, _e, st = git_capture("-C", space.path.to_s, "diff", "--cached", "--quiet")
       !st.success? # --quiet exits non-zero when there are staged differences
@@ -405,6 +708,12 @@ module SpaceArchitect
       render_template("architect.md.erb")
     end
 
+    def render_brief
+      @_title = space.data["title"] || space.id
+      @_repos = space.repos
+      render_template("brief.md.erb")
+    end
+
     def render_iteration(ordinal_nn, name)
       @_ordinal = "I#{ordinal_nn}"
       @_name = name

data/lib/space_architect/cli/architect.rb

@@ -107,6 +107,12 @@ module SpaceArchitect
               mission = ArchitectMission.new(space: sp)
               sha = mission.freeze!(iteration)
               terminal.say "Frozen #{iteration} at #{sha}"
+              ac = mission.acceptance_criteria(iteration)
+              unless ac.to_s.strip.empty?
+                terminal.say ""
+                terminal.say "Frozen Acceptance Criteria (quote these verbatim when judging):"
+                terminal.say ac
+              end
               CLI.record_outcome(Outcome.new(exit_code: 0))
             end
           end
@@ -195,6 +201,176 @@ module SpaceArchitect
         end
       end
 
+      class Section < Dry::CLI::Command
+        include GlobalOptions
+        include Helpers
+
+        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"
+        argument :space,     required: false, desc: "Space identifier (default: $PWD)"
+        option   :from,   default: nil, desc: "Read the section body from this file"
+        option   :body,   default: nil, desc: "Inline section body (one-liners)"
+        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"
+
+        def call(iteration:, section:, space: nil, from: nil, body: nil, stdin: false, append: false, lane: nil, **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|
+              mission = ArchitectMission.new(space: sp)
+              res = mission.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?
+              else
+                terminal.say "#{res[:heading]} written — no change to commit"
+              end
+              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 SpaceArchitect::Error, "provide the section body via --from <file>, --body <text>, or --stdin"
+        end
+      end
+
+      class Evidence < Dry::CLI::Command
+        include GlobalOptions
+        include Helpers
+
+        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)"
+        option   :lane,      default: nil,    desc: "Lane name (per-lane subsection; omit for a single-lane iteration)"
+
+        def call(iteration:, space: nil, lane: nil, **opts)
+          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)
+              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)."
+              CLI.record_outcome(Outcome.new(exit_code: 0))
+            end
+          end
+        end
+      end
+
+      class Merge < Dry::CLI::Command
+        include GlobalOptions
+        include Helpers
+
+        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)"
+        argument :space,     required: false, desc: "Space identifier (default: $PWD)"
+        option   :message,   default: nil,    desc: "Commit message for the lane's working-tree changes"
+
+        def call(iteration:, lane:, space: nil, message: nil, **opts)
+          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)
+              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."
+              CLI.record_outcome(Outcome.new(exit_code: 0))
+            end
+          end
+        end
+      end
+
+      class Integrate < Dry::CLI::Command
+        include GlobalOptions
+        include Helpers
+
+        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)"
+        option   :lanes,     required: true,  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)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            render(store.find(space)) do |sp|
+              mission = ArchitectMission.new(space: sp)
+              lane_names = lanes.to_s.split(",").map(&:strip).reject(&:empty?)
+              results = mission.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
+              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
+        end
+      end
+
+      class Gate < Dry::CLI::Command
+        include GlobalOptions
+        include Helpers
+
+        desc "Run the frozen Acceptance Criteria gate commands and stream raw output (no 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)"
+
+        def call(iteration:, lane: nil, space: nil, **opts)
+          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)
+              results.each do |r|
+                terminal.say ""
+                terminal.say "── #{r[:ac].empty? ? "(gate)" : r[:ac]}: #{r[:command]}  (exit #{r[:exit_code]})"
+                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))
+            end
+          end
+        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
@@ -208,14 +384,16 @@ module SpaceArchitect
           option   :harness,   default: "claude-code", desc: "Harness (claude-code, opencode)"
           option   :model,     default: nil,           desc: "Model (required for opencode)"
           option   :effort,    default: nil,           desc: "Reasoning effort (opencode only; sets reasoningEffort in the model config)"
+          option   :touch,     default: nil,           desc: "Comma-separated file globs the lane may touch (records its touch_set for in-bounds + merge checks)"
 
-          def call(repo:, iteration:, lane:, base: nil, harness: "claude-code", model: nil, effort: nil, **opts)
+          def call(repo:, iteration:, lane:, base: nil, harness: "claude-code", model: nil, effort: nil, touch: nil, **opts)
             setup_terminal(**opts.slice(:color, :colors))
             handle_errors do
               render(store.find) do |sp|
                 mission = ArchitectMission.new(space: sp)
+                touch_set = touch ? touch.split(",").map(&:strip).reject(&:empty?) : nil
                 result = mission.worktree_add(repo, iteration, lane, base: base,
-                                             harness: harness, model: model, effort: effort)
+                                             harness: harness, model: model, effort: effort, touch: touch_set)
                 terminal.say "Worktree: #{terminal.path(result[:worktree])}"
                 terminal.say "Base SHA: #{result[:base_sha]}"
                 CLI.record_outcome(Outcome.new(exit_code: 0))
@@ -376,6 +554,14 @@ SpaceArchitect::CLI::Registry.register "status", SpaceArchitect::CLI::Architect:
 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 "brief" do |b|
+  b.register "new", SpaceArchitect::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

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

@@ -4,6 +4,10 @@
 > architecture/I<NN>-<iteration>.md — this file only indexes the iterations and carries
 > mission-wide state. Keep it short (~150 lines): the next session must grok it
 > in under a minute. Not in the committed architecture = didn't happen.
+>
+> Durable mission contract: `architecture/BRIEF.md` (numbered §sections, cited as BRIEF §N).
+> Create it with `architect brief new`. Edits to a §section are mission-scope decisions —
+> log them in the Decisions log below, never as silent per-iteration drift.
 
 ## TL;DR (keep current)
 

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

@@ -0,0 +1,43 @@
+# BRIEF — <%= @_title %>
+
+> Durable mission contract for the Architect Loop. The numbered §sections below are the
+> stable, cross-iteration address space: every iteration cites them as **BRIEF §N** in its
+> Grounds, Specification, Acceptance Criteria, and Verdict (e.g. `(BRIEF §3.1)`), the way each
+> gate addresses its intent back to one frozen reference. Frozen early; edits are mission-scope
+> decisions logged in ARCHITECT.md's Decisions log, never silent per-iteration drift. Optional —
+> a discovery mission may defer this and cite per-iteration Grounds until the shape stabilizes,
+> then promote the consolidated picture here once.
+
+## 1. Goal & non-goals
+
+<!-- One paragraph of goal; an explicit non-goals list. §1 is the cardinal-intent address —
+iterations and verdicts cite it for the invariants that must never break. -->
+
+## 2. Constraints / frozen stack
+
+<!-- Languages, gems/deps and pinned versions, platform constraints. "No new dependencies"
+boundaries in iteration specs cite BRIEF §2. -->
+
+## 3. Domain model
+
+<!-- The nouns and their relationships; the data/contract shapes that span iterations. -->
+
+### 3.1
+
+## 4. Layout
+
+<!-- Where things live: directories, entry points, the seams iterations build against. -->
+
+## 5. Iteration map
+
+<!-- The planned iterations, each independently shippable; the Acceptance Criteria are the
+frozen proof. An iteration's Specification cites its row here (e.g. "BRIEF §5 Slice 3"). -->
+
+## 6. Cross-iteration risks / PHASE-0 challenge list
+
+<!-- Known risks and the things a builder's PHASE 0 should challenge — cited from specs as
+"BRIEF §6". -->
+
+## 7. Definition of done (whole mission)
+
+<!-- The mission-level DoD. Iteration gates diff against "BRIEF §7 DoD". -->

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

@@ -9,21 +9,23 @@
 
 ## Grounds
 
-<!-- WHY. Research/PRD distilled: problem, decision + why, requirements,
-non-goals, verified facts WITH citation URLs, open questions. Optional — delete
-this section for iterations that needed no research. Commit: "<%= @_ordinal %>: grounds". -->
+<!-- WHY. Research/spec distilled: problem, decision + why, requirements,
+non-goals, verified facts WITH citation URLs, open questions. If
+architecture/BRIEF.md exists, cite **BRIEF §N** instead of restating — shrink this
+to deltas + citations. Optional — delete this section for iterations that needed
+no research. Write + commit: `architect section <%= @_name %> grounds --from <file>`. -->
 
 ## Specification
 
 <!-- WHAT / HOW — the full, self-contained delegation contract.
-Commit: "<%= @_ordinal %>: specification". -->
+Write + commit: `architect section <%= @_name %> specification --from <file>`. -->
 
-- **Objective** — what to build and why (cite Grounds if present).
+- **Objective** — what to build and why; cite **BRIEF §N** for durable context (e.g. `(BRIEF §3.1)`).
 - **Output format** — raw tables, numbers, commit SHAs, test output paths.
 - **Tool guidance** — exact verification commands for the target repo; the
   APIs/formats/versions to verify against live dependencies before writing code.
 - **Boundaries** — may-touch / must-not-touch / out-of-scope; no placeholders;
-  no refactors beyond the task.
+  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.
 - **Effort** — `think hard` … `ultrathink` per lane, with one line of why.
@@ -34,33 +36,39 @@ Commit: "<%= @_ordinal %>: specification". -->
 commits this file and records its SHA as freeze_sha. Read-only afterward — any
 change to Grounds/Specification/Acceptance Criteria = automatic iteration FAIL. -->
 
-| AC# | Command | Threshold |
-|-----|---------|-----------|
-|     |         |           |
+> Gate-pass is necessary, not sufficient: the architect also reads the diff against the
+> cited **BRIEF §sections** intent and the §1 cardinal invariant before the verdict.
+
+| AC# | Command | Threshold | Brief § |
+|-----|---------|-----------|---------|
+|     |         |           |         |
 
 ## Builder Prompt
 
 <!-- The exact lane-prompt(s) dispatched, recorded as provenance. One ###
 subsection per lane. A copy is written to build/<%= @_ordinal %>-<%= @_name %>-<lane>/prompt.md
-for stdin dispatch. Commit: "<%= @_ordinal %>: dispatched". -->
+for stdin dispatch. Record + commit:
+`architect section <%= @_name %> prompt --append --lane <lane> --from build/<%= @_ordinal %>-<%= @_name %>-<lane>/prompt.md`. -->
 
 ## Builder Report
 
 <!-- RAW EVIDENCE ONLY — tables, numbers, command output. The builder writes this
 to build/<%= @_ordinal %>-<%= @_name %>-<lane>/report.md; the architect transcribes it here
-VERBATIM (no interpretation). One ### subsection per lane; include the builder's
-PHASE 0 disagreements and its STATUS line. Commit: "<%= @_ordinal %>: evidence". -->
+VERBATIM with `architect evidence <%= @_name %> --lane <lane>` (byte-for-byte, no
+interpretation). One ### subsection per lane; includes the builder's PHASE 0
+disagreements and its STATUS line. -->
 
 ## Verdict
 
 <!-- ARCHITECT JUDGMENT, written in a LATER session than the dispatch.
-Commit: "<%= @_ordinal %>: verdict". -->
+Write + commit: `architect section <%= @_name %> verdict --from <file>`. -->
 
-- **Disagreement rulings** — each PHASE 0 disagreement: ACCEPT / REJECT / MODIFY + why.
+- **Disagreement rulings** — each PHASE 0 disagreement: ACCEPT / REJECT / MODIFY + why; cite the
+  BRIEF §section in tension beside file:line.
 - **Acceptance Criteria integrity** — frozen sections unchanged since freeze (`architect verify <%= @_name %>`)?
 
-| AC# | Raw result | Verdict |
-|-----|------------|---------|
-|     |            | PASS/FAIL/INVALID |
+| AC# | Raw result | Brief § | Verdict |
+|-----|------------|---------|---------|
+|     |            |         | PASS/FAIL/INVALID |
 
-- **Iteration** — KILL / CONTINUE + the single decisive reason.
+- **Iteration** — KILL / CONTINUE + the single decisive reason (e.g. "diff vs BRIEF §1/§3.3 faithful — CONTINUE").

data/lib/space_architect/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SpaceArchitect
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: space-architect
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Eric Jacobs
@@ -241,6 +241,7 @@ files:
 - lib/space_architect/space_store.rb
 - lib/space_architect/state.rb
 - lib/space_architect/templates/architect.md.erb
+- lib/space_architect/templates/brief.md.erb
 - lib/space_architect/templates/iteration.md.erb
 - lib/space_architect/terminal.rb
 - lib/space_architect/version.rb