space-architect 2.0.2 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7251e017d780c7fc4accd3d4ee367d2b5063bb4d0c1692c0c69bc81a228c9fa7
-  data.tar.gz: ad25da0cf6025716953685d7483e86898368170967a29465625335337f8427a3
+  metadata.gz: bb8f902d475bcc8a29e56740ce0c20328935fe05f9d919d38934b2cffd12e966
+  data.tar.gz: e31c5b6f8ad98219c9c4ed22225666900bc7aaf8f43bd929ef32e2d2b5aacdf2
 SHA512:
-  metadata.gz: baf43e94bcd35987bb133f3958709bfc4083851732ed2d47ef72b25b92e042cfb72c2594f1067189e9581c554140cd2d6145dc7d607f9137931250522ba445dc
-  data.tar.gz: 0ecd90d05ea7dc4c3832fea90f7af76650b1c8279ced9e7e48242b825aaeef8e7291d6dc9b4dacd6bfac00ad647ecca887a2f27abb3823181287885ccede7210
+  metadata.gz: 5cbb47cbacf2231ed09eb74bfb11b80a1a6076bfde1427fe76a19b3581f3b3a8e38db4a6269307e339a022902723d73b1d40dd4b001acd6ffaab624871249d70
+  data.tar.gz: 171913d786d1e166a279f72b184ec7987785d561ec795bfe161db9341502210f6d97166c3eb8b7a097b59adba7e435a575c78ca66488ca482312b4bc7cca7249

data/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-07-01
+
+### Added
+
+- **`architect bug-report`** — zero-friction bug-filing command. Gathers
+  diagnostics (gem version, Ruby version/platform, and when run inside a space:
+  space id, title, and iteration list with verdicts), writes a prefilled GitHub
+  issue-body template to `<space>/build/bug-report/architect-bug-report-YYYYMMDD-HHMMSS.md`
+  (or `./architect-bug-report-YYYYMMDD-HHMMSS.md` outside a space — timestamped so
+  back-to-back runs in the same session never overwrite each other), and prints —
+  never executes — the `gh issue create -R jetpks/space-architect` invocation to run.
+
+### Removed
+
+- **BREAKING — `architect land` removed** (added in 2.0.0) — landing is the architect
+  skill's procedure: the architect writes the PR body and presents the push +
+  PR command. The command as shipped never produced a runnable block (#25) and
+  authored content the CLI has no context for (#24).
+
+### Fixed
+
+- **`architect bug-report` — `~`-contracted paths in printed commands.**
+  The `gh issue create` invocation printed to stdout renders the
+  `--body-file` path as `~/…` instead of the user's expanded `$HOME`.
+  `Space::Core::Paths.contract` is the single home-contraction helper; `Terminal#path`
+  delegates to it.
+- **Command wrapping for narrow terminals.** The `gh issue create` command is
+  now rendered with trailing ` \` continuations broken at `--flag` boundaries,
+  continuation lines indented two spaces. The wrapped output is valid shell
+  (`bash -n` clean). `Space::Core::Commands.wrap` is the single wrapping helper.
+
 ## [2.0.2] - 2026-07-01
 
 ### Added

data/README.md

@@ -102,7 +102,9 @@ space show 20260531-name-of-space
 space path 20260531-name-of-space
 space current                                # based on $PWD
 space show                                   # based on $PWD
-space status done                            # based on $PWD
+space status                                 # report: metadata + loop status (based on $PWD)
+space status 20260531-name-of-space          # report another space
+space status done                            # set: active | paused | done | archived
 space status 20260531-name-of-space done
 space config set default_provider github.com
 space config set default_organization example-org
@@ -115,6 +117,12 @@ space use 20260531-name-of-space             # records recent state, prints the
 space ls --color=always                      # auto | always | never (--colors also accepted)
 ```
 
+`space status` is **report-or-set**: with no status keyword (bare, or with just
+a space id) it *reports* the space — its metadata plus a compact loop-status
+block (project status, current iteration, derived state) when the space runs an
+Architect project, quietly omitted otherwise; pass a status keyword (`active`,
+`paused`, `done`, `archived`) to *set* it instead. 🔁
+
 Repos are passed with a repeatable `-r` flag (`-r org/repo -r org/lib`); the
 comma form (`-r a,b`) works too. Space ids are date-prefixed
 (`20260531-name-of-space`) so they sort naturally, and duplicate names on the
@@ -302,12 +310,17 @@ architect evidence <it> --lane <lane>       # transcribe the builder's report ve
 architect gate <iteration>                  # run the frozen gate commands, stream raw output
 architect merge <it> <lane>                 # integrate ONE judged-passing lane (--no-ff)
 architect integrate <it> --lanes a,b        # integrate a set of passing lanes, in order
-architect land                              # end-of-project PR command (no push, no gh)
+# landing (PR body + push/PR command) is the architect's end-of-project procedure (see skill)
 architect status                            # project state (read-only)
 architect variant add|compare|promote …     # competing (harness, model) lanes over one frozen spec
 architect research dispatch|status|wait …   # parallel read-only research lanes (see below)
 ```
 
+`architect help` (or bare `architect`, `architect --help`) lists these grouped by
+loop phase — **Spec · Build · Judge · Land · Project · Groups**, in canonical
+order — and, inside an architect space, ends with a compact loop-status block
+(project status + current iteration) so you can see where you are in the loop. 🧭
+
 A typical session:
 
 ```sh
@@ -321,7 +334,7 @@ architect evidence my-feature --lane lane-a      # transcribe raw evidence
 architect gate my-feature                        # run the frozen gates yourself
 # … read the diff against the spec, then write the Verdict …
 architect integrate my-feature --lanes lane-a    # merge passing lanes → project/<slug>
-architect land                                   # print gh pr create at project end
+# landing (PR body + push/PR command) is the architect's end-of-project procedure (see skill)
 ```
 
 ### Streaming builder output 📡

data/lib/space_architect/architect_project.rb

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

data/lib/space_architect/bug_report.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Space
+  module Architect
+    module BugReport
+      REPO = "jetpks/space-architect"
+
+      class << self
+        def generate(space: nil, env: ENV, cwd: Dir.pwd, now: Time.now)
+          body_path = resolve_body_path(space, cwd, now)
+          FileUtils.mkdir_p(body_path.dirname)
+          body = build_body(space)
+          body_path.write(body)
+          contracted = Space::Core::Paths.contract(body_path, env: env)
+          command = Space::Core::Commands.wrap(
+            %(gh issue create -R #{REPO} --title "<one-line summary>" --body-file #{contracted})
+          )
+          { body_path: body_path, command: command, body: body }
+        end
+
+        private
+
+        def resolve_body_path(space, cwd, now)
+          filename = "architect-bug-report-#{now.strftime('%Y%m%d-%H%M%S')}.md"
+          if space
+            space.path.join("build", "bug-report", filename)
+          else
+            Pathname.new(cwd).join(filename)
+          end
+        end
+
+        def build_body(space)
+          body = +template_header
+          body << diagnostics_section
+          body << space_section(space) if space
+          body
+        end
+
+        def template_header
+          <<~MD
+            <!-- Title: <one-line summary> -->
+
+            **Kind:** <!-- process / tooling / both -->
+
+            ## Summary
+
+            <!-- One sentence describing the bug. -->
+
+            ## What happened
+
+            <!-- Describe what you observed. -->
+
+            ## What was expected
+
+            <!-- Describe what you expected to happen. -->
+
+            ## Repro steps
+
+            <!-- Numbered steps to reproduce. -->
+
+          MD
+        end
+
+        def diagnostics_section
+          <<~MD
+            ## Diagnostics
+
+            - space-architect: #{Space::Core::VERSION}
+            - ruby: #{RUBY_VERSION} (#{RUBY_PLATFORM})
+          MD
+        end
+
+        def space_section(space)
+          iterations = Array(space.data.dig("project", "iterations"))
+          iter_lines = iterations.map do |s|
+            nn = format("%02d", s["ordinal"])
+            verdict = s["verdict"] || "—"
+            "- I#{nn} #{s["name"]} — #{verdict}"
+          end.join("\n")
+
+          +"\n## Space context\n\n" \
+            "- Space id: #{space.id}\n" \
+            "- Space title: #{space.title}\n" \
+            "\n### Iterations\n\n" \
+            "#{iter_lines.empty? ? "(none)" : iter_lines}\n"
+        end
+      end
+    end
+  end
+end