space-architect 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec439ebdc7e044a032f6a6736166d38dcc38b965ee26c03a2a27b1f95c9f5b2e
-  data.tar.gz: 3b242e89b02bd5e1aa69389aad16eb3e221da0fd000b3e7587ccce02cb565d32
+  metadata.gz: db24aa20a68fdf981176f7e51a46794a4fc2ec5cef9765c33de5832f0a314a9e
+  data.tar.gz: 8912085239c76c1228e01d8986d789ba0fde42b4517459830c1f08cdb6e0fcfc
 SHA512:
-  metadata.gz: 58deb069cc61cf59161122547407699f03072cea024608e9954b568f409c2f11afe241aa585378010dfd5fe9df53aeb83f68945418482d45ba9d312b76297a85
-  data.tar.gz: 59c12540afc15984bc74d67051f4efc59a360e0fb93acd00bae252fcc2d7b139e2c3f63e692cd5980e0cbc1b3f378d141520b985a41a57c22a2ef08894be914d
+  metadata.gz: 06a4e3382403542421679272136d6c1f6a99ac5dece354b5175f5d895b1afb9cce902f9e11ea2cf64c940dd4a00f11d3dfa7390a0941f387ae4a28f47cdbc3fb
+  data.tar.gz: 73c71c080f640540c4cfb57f347f12eae5a2486c45a373a525c44dc35ea54edf7b43ee415d979352f6569406f0f261e8d4a601af869eae5bd9f9055df02d9807

data/README.md

@@ -69,6 +69,7 @@ architect space status done                      # mark the current mission comp
 **Architect Loop (run from inside a space):**
 
 ```sh
+architect install-skills                          # install skills for your harness (once per machine)
 architect init                                   # scaffold ARCHITECT.md + architecture/
 architect new <iteration>                        # scaffold next iteration file
 architect dispatch <iteration> <lane>            # dispatch a builder for a lane
@@ -77,6 +78,14 @@ architect freeze <iteration>                     # freeze Acceptance Criteria
 architect verify <iteration>                     # post-flight mechanical checks
 ```
 
+`architect install-skills` installs the bundled `architect`, `architect-research`,
+and `architect-vocabulary` skills for a harness. (`architect-vocabulary` loads the
+system's terms and a short orientation when you're in a space but don't want to run
+the loop — see [The Architect Loop](#the-architect-loop-).) Default is `claude`
+(`~/.claude/skills/`); use `--provider
+opencode|codex|pi` for other harnesses, and `--project` to install into the current
+directory instead of globally. See the [command reference](docs/reference.md) for details.
+
 ## Usage 🛰️
 
 ```sh

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