space-architect 3.0.0 → 5.0.0

data/lib/space_architect/architect_project.rb

@@ -6,6 +6,7 @@ require "open3"
 require "fileutils"
 require "pathname"
 require "tempfile"
+require "time"
 
 module Space::Architect
   # Manages an architect-loop project inside a space: one self-contained file per
@@ -24,10 +25,10 @@ module Space::Architect
     # 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 }
+      "grounds" => { heading: "## Grounds", message: "grounds", prefix: "grounds", frozen: true },
+      "specification" => { heading: "## Specification", message: "specification", prefix: "spec", frozen: true },
+      "prompt" => { heading: "## Builder Prompt", message: "dispatched", prefix: "prompt", frozen: false },
+      "verdict" => { heading: "## Verdict", message: "verdict", prefix: "verdict", frozen: false }
     }.freeze
 
     # The fixed top-level section headings. Section boundaries are detected against
@@ -41,7 +42,10 @@ module Space::Architect
     # Hard per-gate timeout. Generous relative to the full suite (~55s).
     DEFAULT_GATE_TIMEOUT = 900
 
-    # Sentinel written to prompt.md by worktree_add. dispatch refuses to launch on this content.
+    # Legacy sentinel: worktree_add used to seed prompt.md with this placeholder
+    # (dropped — the blind-overwrite tripped harness read-before-write guards, #48).
+    # dispatch still refuses to launch on this content, so stubs in old spaces
+    # can't reach a builder.
     PROMPT_STUB = "<!-- ARCHITECT: write this lane's builder prompt here, then dispatch. -->"
 
     # Inlined settings.json template for `architect init`. Registers a SessionStart
@@ -73,7 +77,7 @@ module Space::Architect
       @space = space
     end
 
-    def init!
+    def init!(message: nil)
       handoff_path = space.path.join("architecture", "ARCHITECT.md")
       settings_path = space.path.join(".claude", "settings.json")
       to_add = []
@@ -96,15 +100,15 @@ module Space::Architect
 
       if to_add.any?
         git_run("-C", space.path.to_s, "add", *to_add)
-        msg = to_add.include?("architecture/ARCHITECT.md") ? "Initialize architect project" : "Add architect settings"
-        git_run("-C", space.path.to_s, "commit", "-m", msg)
+        default = to_add.include?("architecture/ARCHITECT.md") ? "Initialize architect project" : "Add architect settings"
+        git_run("-C", space.path.to_s, "commit", "-m", compose_message("init:", default, message))
       end
 
       handoff_path
     end
 
     # Allocate the next ordinal and scaffold architecture/I<NN>-<iteration>.md.
-    def new_iteration!(name)
+    def new_iteration!(name, message: nil)
       block = space.data["project"] || {}
       iterations = block["iterations"] || []
       if iterations.any? { |s| s["name"] == name }
@@ -132,7 +136,8 @@ module Space::Architect
       end
 
       git_run("-C", space.path.to_s, "add", rel, Space::Core::Space::METADATA_FILE)
-      git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: scaffold #{name}")
+      git_run("-C", space.path.to_s, "commit", "-m",
+        compose_message("I#{nn} scaffold:", "I#{nn}: scaffold #{name}", message))
 
       path
     end
@@ -153,7 +158,7 @@ module Space::Architect
     # Freeze the iteration: the iteration file must carry a "## Acceptance Criteria" section. Commits
     # any pending changes to the iteration file and records HEAD as freeze_sha. If
     # already frozen, refuses when the frozen region has changed since.
-    def freeze!(iteration, warnings: nil)
+    def freeze!(iteration, warnings: nil, message: nil)
       entry = slice_entry(iteration)
       rel = entry["file"]
       path = space.path.join(rel)
@@ -164,6 +169,7 @@ module Space::Architect
       end
 
       lint_gates!(text, warnings: warnings)
+      lint_lanes!(text)
 
       if entry["freeze_sha"]
         sha = entry["freeze_sha"]
@@ -177,21 +183,27 @@ module Space::Architect
 
       files = [rel]
       files << "architecture/ARCHITECT.md" if space.path.join("architecture", "ARCHITECT.md").exist?
-      git_run("-C", space.path.to_s, "add", *files)
-      if staged_changes?
-        nn = format("%02d", entry["ordinal"] || 0)
-        git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: acceptance criteria (freeze)")
-      end
+      nn = format("%02d", entry["ordinal"] || 0)
+      git_capture("-C", space.path.to_s, "commit", "-m",
+        compose_message("I#{nn} freeze:", "I#{nn}: acceptance criteria (freeze)", message), "--", *files)
 
       sha, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
       sha = sha.strip
 
+      declared = parse_lanes(text)
       update_architect_block do |b|
         b["current_iteration"] = iteration
         (b["iterations"] || []).each do |s|
           next unless s["name"] == iteration
           s["freeze_sha"] = sha
           s["verdict"] ||= "pending"
+          lanes = s["lanes"] || []
+          declared.each do |d|
+            fields = { "name" => d["name"], "repo" => d["repo"], "touch_set" => Array(d["touch"]) }
+            existing = lanes.find { |l| l["name"] == d["name"] }
+            existing ? existing.merge!(fields) : lanes << fields
+          end
+          s["lanes"] = lanes
         end
         b
       end
@@ -201,17 +213,20 @@ module Space::Architect
 
     # Scaffold the durable, section-numbered project 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)
+    # cite as "BRIEF §N"; it lives outside the per-iteration freeze region. With
+    # content, writes the authored brief instead of the placeholder template.
+    def brief_new!(force: false, content: nil, message: nil)
       brief_path = space.path.join("architecture", "BRIEF.md")
       if brief_path.exist? && !force
         raise Space::Core::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)
+      brief_path.write(content || render_brief)
       git_run("-C", space.path.to_s, "add", "architecture/BRIEF.md")
-      git_run("-C", space.path.to_s, "commit", "-m", "Add project brief") if staged_changes?
+      if staged_changes?
+        git_run("-C", space.path.to_s, "commit", "-m", compose_message("brief:", "Add project brief", message))
+      end
       brief_path
     end
 
@@ -219,7 +234,7 @@ module Space::Architect
     # 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)
+    def write_section!(iteration, section, body:, append: false, lane: nil, message: nil)
       spec = SECTIONS[section]
       unless spec
         raise Space::Core::Error,
@@ -242,18 +257,19 @@ module Space::Architect
       path.write(replace_section_body(path.read, spec[:heading], block, append: append))
 
       nn = format("%02d", entry["ordinal"] || 0)
-      git_run("-C", space.path.to_s, "add", rel)
-      committed = staged_changes?
-      git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: #{spec[:message]}") if committed
-
-      head, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
-      diffstat, = committed ? git_capture("-C", space.path.to_s, "show", "--stat", "--format=", "HEAD") : [""]
-      { section: section, heading: spec[:heading], sha: head.strip, committed: committed, diffstat: diffstat.strip }
+      _o, _e, cst = git_capture("-C", space.path.to_s, "commit", "-m",
+        compose_message("I#{nn} #{spec[:prefix]}:", "I#{nn}: #{spec[:message]}", message), "--", rel)
+      committed = cst.success?
+      show_out, = git_capture("-C", space.path.to_s, "show", "--stat", "--format=%H", "HEAD")
+      show_lines = show_out.to_s.lines
+      sha = show_lines.first&.strip || ""
+      diffstat = committed ? show_lines.drop(1).join.strip : ""
+      { section: section, heading: spec[:heading], sha: sha, committed: committed, diffstat: diffstat }
     end
 
     # Write the ## Verdict prose AND record the decision to space.yaml in one commit.
     # decision must be "continue" or "kill".
-    def record_verdict!(iteration, decision:, body:)
+    def record_verdict!(iteration, decision:, body:, message: nil)
       unless %w[continue kill].include?(decision)
         raise Space::Core::Error,
           "Invalid verdict decision '#{decision}' — must be one of: continue, kill"
@@ -272,8 +288,8 @@ module Space::Architect
       end
 
       nn = format("%02d", entry["ordinal"] || 0)
-      git_run("-C", space.path.to_s, "add", rel, Space::Core::Space::METADATA_FILE)
-      git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: verdict")
+      git_run("-C", space.path.to_s, "commit", "-m",
+        compose_message("I#{nn} verdict:", "I#{nn}: verdict", message), "--", rel, Space::Core::Space::METADATA_FILE)
 
       head, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
       { decision: decision, sha: head.strip }
@@ -281,7 +297,7 @@ module Space::Architect
 
     # 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)
+    def transcribe_evidence!(iteration, lane: nil, message: nil)
       entry = slice_entry(iteration)
       rel = entry["file"]
       path = space.path.join(rel)
@@ -297,8 +313,8 @@ module Space::Architect
       path.write(replace_section_body(path.read, "## Builder Report", block, append: !lane.nil?))
 
       nn = format("%02d", entry["ordinal"] || 0)
-      git_run("-C", space.path.to_s, "add", rel)
-      git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: evidence") if staged_changes?
+      git_capture("-C", space.path.to_s, "commit", "-m",
+        compose_message("I#{nn} evidence:", "I#{nn}: evidence", message), "--", rel)
       head, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
 
       status_line = raw.lines.reverse_each.find { |l| l.strip.start_with?("STATUS:") }&.strip
@@ -330,6 +346,7 @@ module Space::Architect
       entry = slice_entry(iteration)
       lane_entry = (entry["lanes"] || []).find { |l| l["name"] == lane }
       raise Space::Core::Error, "No lane '#{lane}' recorded for iteration '#{iteration}'" unless lane_entry
+      lane_entry = ensure_lane_materialized(iteration, lane)
 
       checks = lane_mechanical_checks(entry, lane_entry)
       if checks[:no_builder_commits] == false
@@ -352,7 +369,8 @@ module Space::Architect
       raise Space::Core::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")
+      git_run("-C", wt_path.to_s, "commit", "-m",
+        compose_message("lane #{lane}:", "lane #{lane}: integrate", message))
       integrate_sha_raw, = git_capture("-C", wt_path.to_s, "rev-parse", "HEAD")
       integrate_sha = integrate_sha_raw.strip
 
@@ -393,25 +411,23 @@ module Space::Architect
     end
 
     # Loop merge_lane! over the architect-supplied passing set, in order. Stops on the
-    # first conflict (a disjointness defect). Never decides which lanes pass.
-    def integrate!(iteration, lanes:, teardown: false)
-      raise Space::Core::Error, "No lanes given to integrate" if lanes.nil? || lanes.empty?
+    # first conflict (a disjointness defect). Never decides which lanes pass. With no
+    # lanes and teardown: true, tears down every lane recorded for the iteration instead
+    # (the second, teardown-only call in the loop's integrate-then-teardown rhythm).
+    def integrate!(iteration, lanes: nil, teardown: false, message: nil)
+      lanes = Array(lanes)
+      return teardown_lanes!(iteration, slice_entry(iteration)["lanes"] || []) if lanes.empty? && teardown
+      raise Space::Core::Error, "No lanes given to integrate" if lanes.empty?
 
       merged = []
       lanes.each do |lane|
-        merged << merge_lane!(iteration, lane)
+        merged << merge_lane!(iteration, lane, message: message)
       rescue Space::Core::Error => e
         done = merged.map { |m| m[:lane] }.join(", ")
         raise Space::Core::Error, "Integrated #{done.empty? ? "(none)" : done} then stopped at '#{lane}': #{e.message}"
       end
 
-      if teardown
-        id = iteration_id(slice_entry(iteration))
-        merged.each do |m|
-          worktree_remove(iteration, m[:lane])
-          git_capture("-C", space.path.join("repos", m[:repo]).to_s, "branch", "-d", "lane/#{id}-#{m[:lane]}")
-        end
-      end
+      teardown_lanes!(iteration, merged) if teardown
       merged
     end
 
@@ -438,6 +454,7 @@ module Space::Architect
         if lane
           le = lanes.find { |l| l["name"] == lane }
           raise Space::Core::Error, "No lane '#{lane}' recorded for iteration '#{iteration}'" unless le
+          le = ensure_lane_materialized(iteration, lane)
           repo_root = le["repo"] ? space.path.join("repos", le["repo"]) : nil
           space.path.join(le["worktree"] || "build/#{iteration_id(entry)}-#{lane}/wt")
         else
@@ -558,14 +575,15 @@ module Space::Architect
 
       # Skip git worktree add when the branch and worktree already exist (idempotent re-run).
       unless branch_exists?(repo_path, branch) && worktree_registered?(repo_path, wt_path)
-        git_run("-C", repo_path.to_s, "worktree", "add", wt_path.to_s, "-b", branch, base_sha)
+        if branch_exists?(repo_path, branch)
+          # The worktree was removed but its lane branch survived — re-attach the branch
+          # (carrying its own tip) instead of `-b`, which would fail "branch already exists".
+          git_run("-C", repo_path.to_s, "worktree", "add", wt_path.to_s, branch)
+        else
+          git_run("-C", repo_path.to_s, "worktree", "add", wt_path.to_s, "-b", branch, base_sha)
+        end
       end
 
-      # Seed prompt.md with a placeholder stub so the architect has a place to write the prompt.
-      # Never overwrite an existing file (real prompt or stub from a prior run).
-      prompt_path = build_dir.join("prompt.md")
-      prompt_path.write("#{PROMPT_STUB}\n") unless prompt_path.exist?
-
       new_fields = {
         "name" => lane,
         "repo" => repo,
@@ -704,9 +722,39 @@ module Space::Architect
       wt_base.children.select(&:directory?).map { |p| p.basename.to_s }.sort
     end
 
+    # Materialize the iteration's declared lanes: for each lane (or the one named via
+    # `lane:`), create its worktree + lane/<id>-<lane> branch from the resolved base and
+    # record worktree/base_sha/integration_branch. Idempotent — an already-materialized
+    # lane is skipped, not re-created. Refuses until the iteration is frozen, because
+    # declarations are not authoritative until then.
+    def provision(iteration, base: nil, lane: nil)
+      entry = slice_entry(iteration)
+      raise Space::Core::Error,
+        "Iteration '#{iteration}' is not frozen — freeze before provisioning (declarations are not authoritative until frozen)." \
+        unless entry["freeze_sha"]
+
+      lanes = entry["lanes"] || []
+      lanes = lanes.select { |l| l["name"] == lane } if lane
+      raise Space::Core::Error, "No lane '#{lane}' declared for iteration '#{iteration}'" if lane && lanes.empty?
+
+      lanes.map do |l|
+        name = l["name"]
+        repo_path = space.path.join("repos", l["repo"])
+        wt_path = space.path.join(l["worktree"] || "build/#{iteration_id(entry)}-#{name}/wt")
+        if wt_path.exist? && worktree_registered?(repo_path, wt_path)
+          { lane: name, worktree: wt_path, base_sha: l["base_sha"], created: false }
+        else
+          result = worktree_add(l["repo"], iteration, name, base: resolve_lane_base(l["repo"], base),
+                                **recorded_lane_fields(l))
+          { lane: name, worktree: result[:worktree], base_sha: result[:base_sha], created: true }
+        end
+      end
+    end
+
     def verify(iteration)
       entry = slice_entry(iteration)
       (entry["lanes"] || []).map do |lane|
+        ensure_lane_materialized(iteration, lane["name"])
         { lane: lane["name"], repo: lane["repo"], checks: lane_mechanical_checks(entry, lane) }
       end
     end
@@ -714,7 +762,7 @@ module Space::Architect
     def dispatch(iteration, lane, model: nil, max_turns: 200,
                  claude_bin: nil, harness: nil, opencode_bin: nil, effort: nil, detach: false,
                  push_url: nil, push_token: nil, push_host: nil, run_creator: nil,
-                 push_client: nil, timeout: nil)
+                 push_client: nil, timeout: nil, prompt: nil, now: Time.now)
       raise Space::Core::Error, "Specify --push-host or --push-url, not both" if push_host && push_url
       raise Space::Core::Error, "--push-host requires --push-token"           if push_host && !push_token
       raise Space::Core::Error, "--detach cannot be combined with --push-url or --push-host" \
@@ -723,6 +771,7 @@ module Space::Architect
       entry = slice_entry(iteration)
       lane_entry = (entry["lanes"] || []).find { |l| l["name"] == lane }
       raise Space::Core::Error, "No lane '#{lane}' recorded for iteration '#{iteration}'" unless lane_entry
+      lane_entry = ensure_lane_materialized(iteration, lane)
 
       resolved_harness = harness || lane_entry["harness"] || "claude-code"
       resolved_model   = model   || lane_entry["model"]   || Harness::CLAUDE_DEFAULT_MODEL
@@ -739,6 +788,15 @@ module Space::Architect
       prompt_path  = build_dir.join("prompt.md")
       run_log_path = build_dir.join("run.jsonl")
       report_path  = build_dir.join("report.md")
+
+      # --prompt: the caller authors the lane prompt anywhere (a fresh scratch file)
+      # and the CLI owns the canonical copy — byte-for-byte, like variant_add.
+      if prompt
+        src = Pathname.new(prompt)
+        raise Space::Core::Error, "prompt file not found: #{src}" unless src.exist?
+        File.open(prompt_path, "wb") { |f| f.write(File.binread(src)) }
+      end
+
       raise Space::Core::Error, "prompt.md not found: #{prompt_path}" unless prompt_path.exist?
 
       prompt_content = prompt_path.read.strip
@@ -749,13 +807,29 @@ module Space::Architect
       harness_obj = Harness.for(resolved_harness, model: resolved_model, max_turns: max_turns,
                                                   bin: bin, config_dir: build_dir, effort: resolved_effort)
 
+      # Stamp launch time onto the lane entry: after every preflight validation has passed
+      # (a dispatch that raises above records nothing) and before the blocking run or a
+      # detached dispatch returns. A re-dispatch overwrites the prior value.
+      update_architect_block do |b|
+        (b["iterations"] || []).each do |s|
+          next unless s["name"] == iteration
+          (s["lanes"] || []).each do |l|
+            next unless l["name"] == lane
+            l["dispatched_at"] = now.iso8601
+          end
+        end
+        b
+      end
+
       if detach
         pid = harness_obj.run_detached(
           prompt_path:  prompt_path,
           run_log_path: run_log_path,
           chdir:        wt_path
         )
-        { pid: pid, run_log: run_log_path, report: report_path, worktree: wt_path }
+        result = { pid: pid, run_log: run_log_path, report: report_path, worktree: wt_path }
+        result[:prompt_copied] = prompt_path if prompt
+        result
       else
         created_run_id = nil
         if push_host
@@ -774,6 +848,7 @@ module Space::Architect
         exit_code = harness_obj.run(**run_kwargs)
 
         result = { exit_code: exit_code, run_log: run_log_path, report: report_path, worktree: wt_path }
+        result[:prompt_copied]  = prompt_path    if prompt
         result[:timed_out]      = true           if exit_code == Harness::ClaudeCodeHarness::TIMEOUT_EXIT_CODE
         result[:created_run_id] = created_run_id if created_run_id
         result[:push_url]       = push_url       if push_url
@@ -785,6 +860,35 @@ module Space::Architect
 
     attr_reader :space
 
+    # Compose a commit message. Without a custom message, the canonical default
+    # (unchanged). With one, a short canonical prefix keeps the loop's commit
+    # taxonomy grep-able while the author's first line owns the subject; any
+    # remaining lines become the commit body — the space's git log is the loop's
+    # durable memory, so callers are encouraged to write detailed bodies.
+    def compose_message(prefix, default, message)
+      return default if message.nil? || message.strip.empty?
+
+      subject, _, body = message.strip.partition("\n")
+      composed = "#{prefix} #{subject.strip}"
+      body = body.strip
+      body.empty? ? composed : "#{composed}\n\n#{body}"
+    end
+
+    # Remove each lane's worktree and safe-delete (`-d`) its lane branch. Accepts
+    # either merge_lane! results (symbol keys) or recorded lane entries (string
+    # keys) — both carry a lane name and a repo.
+    def teardown_lanes!(iteration, lane_entries)
+      id = iteration_id(slice_entry(iteration))
+      lane_entries.map do |l|
+        lane = l[:lane] || l["name"]
+        repo = l[:repo] || l["repo"]
+        worktree_remove(iteration, lane)
+        lane_branch = "lane/#{id}-#{lane}"
+        git_capture("-C", space.path.join("repos", repo).to_s, "branch", "-d", lane_branch)
+        { lane: lane, repo: repo, lane_branch: lane_branch }
+      end
+    end
+
     # Resolve the in-flight iteration file for ground output.
     # Rule: (a) current_iteration from project block → entry's file if it exists on disk,
     #        (b) else highest-ordinal architecture/I<NN>-*.md,
@@ -855,6 +959,55 @@ module Space::Architect
       "project/#{slug}"
     end
 
+    # Materialize a declared lane on demand: when its worktree is absent, create it
+    # identically to `provision` (same base resolution, same worktree_add primitive)
+    # so no dispatch/integrate/gate path dead-ends on a missing worktree. Returns the
+    # (possibly refreshed) lane entry; a no-op when already materialized or undeclared.
+    def ensure_lane_materialized(iteration, lane)
+      entry = slice_entry(iteration)
+      lane_entry = (entry["lanes"] || []).find { |l| l["name"] == lane }
+      return lane_entry unless lane_entry && lane_entry["repo"]
+
+      repo_path = space.path.join("repos", lane_entry["repo"])
+      return lane_entry unless repo_path.exist?
+      wt_path = space.path.join(lane_entry["worktree"] || "build/#{iteration_id(entry)}-#{lane}/wt")
+      return lane_entry if wt_path.exist? && worktree_registered?(repo_path, wt_path)
+
+      worktree_add(lane_entry["repo"], iteration, lane, base: resolve_lane_base(lane_entry["repo"], nil),
+                   **recorded_lane_fields(lane_entry))
+      (slice_entry(iteration)["lanes"] || []).find { |l| l["name"] == lane }
+    end
+
+    # The lane's declared harness/model/variant/effort, as worktree_add kwargs — so a
+    # re-materialize preserves them instead of merging back to defaults. touch_set is
+    # deliberately omitted: worktree_add leaves it untouched, so it already survives.
+    def recorded_lane_fields(lane_entry)
+      {
+        harness: lane_entry["harness"] || "claude-code",
+        model:   lane_entry["model"],
+        variant: lane_entry["variant"] || false,
+        effort:  lane_entry["effort"]
+      }
+    end
+
+    # Resolve the base ref a lane's worktree branches from: an explicit override wins;
+    # otherwise the project/<slug> integration branch when it exists, else the repo's
+    # default branch.
+    def resolve_lane_base(repo, override)
+      return override if override
+      repo_path = space.path.join("repos", repo)
+      integration = project_integration_branch
+      return integration if branch_exists?(repo_path, integration)
+      repo_default_branch(repo_path)
+    end
+
+    def repo_default_branch(repo_path)
+      out, _, st = git_capture("-C", repo_path.to_s, "symbolic-ref", "--short", "refs/remotes/origin/HEAD")
+      return out.strip.sub(%r{\Aorigin/}, "") if st.success? && !out.strip.empty?
+      out, _, st = git_capture("-C", repo_path.to_s, "symbolic-ref", "--short", "HEAD")
+      st.success? && !out.strip.empty? ? out.strip : "HEAD"
+    end
+
     def slice_entry(iteration)
       block = space.data["project"] || {}
       entry = (block["iterations"] || []).find { |s| s["name"] == iteration }
@@ -981,6 +1134,44 @@ module Space::Architect
       parsed.is_a?(Array) ? parsed : []
     end
 
+    # Extract and parse the fenced ```lanes block from the Specification section.
+    # Returns an array of lane declaration hashes (string-keyed). Returns [] when the
+    # block is absent, empty, or contains only YAML comments (back-compat).
+    def parse_lanes(text)
+      body = section_body(text, "## Specification")
+      return [] unless body
+      match = body.match(/^```lanes\n(.*?)^```/m)
+      return [] unless match
+      parsed = YAML.safe_load(match[1], aliases: false)
+      parsed.is_a?(Array) ? parsed : []
+    end
+
+    # Lint the lanes block in the given iteration file text. Raises Space::Core::Error
+    # with aggregated messages on failure. An absent/empty block is allowed (back-compat).
+    def lint_lanes!(text)
+      lanes = begin
+        parse_lanes(text)
+      rescue Psych::SyntaxError => e
+        raise Space::Core::Error, "ill-formed lanes block: #{e.message}"
+      end
+      return if lanes.empty?
+
+      errors = lanes.each_with_index.flat_map do |l, i|
+        unless l.is_a?(Hash)
+          next ["lane #{i}: expected a mapping with name/repo/touch"]
+        end
+        touch = l["touch"]
+        [
+          ("lane #{i}: missing 'name'" if l["name"].to_s.strip.empty?),
+          ("lane #{i}: missing 'repo'" if l["repo"].to_s.strip.empty?),
+          ("lane #{i} (#{l["name"]}): 'touch' must be a non-empty array of globs" \
+            unless touch.is_a?(Array) && touch.any? && touch.all? { |g| g.is_a?(String) && !g.strip.empty? })
+        ].compact
+      end
+      return if errors.empty?
+      raise Space::Core::Error, "ill-formed lanes block:\n#{errors.join("\n")}"
+    end
+
     # Lint the gates block in the given iteration file text. Raises Space::Core::Error
     # with aggregated messages on failure. Absent/empty gates appends a warning to
     # the optional warnings array but does not fail.