space-architect 1.1.0 → 1.3.0

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,201 @@ 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
+
+      class InstallSkills < Dry::CLI::Command
+        include GlobalOptions
+        include Helpers
+
+        desc "Install bundled skills (architect, architect-research, architect-vocabulary) for a harness"
+        option :provider, default: "claude", desc: "Harness: claude, codex, opencode, pi"
+        option :project, type: :boolean, default: false, desc: "Install to CWD instead of global"
+        option :force,   type: :boolean, default: false, desc: "Overwrite existing skills that differ"
+        option :dry_run, type: :boolean, default: false, desc: "Print what would happen without writing files"
+
+        def call(provider: "claude", project: false, force: false, dry_run: false, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            result = SkillInstaller.install(provider, project: project, force: force,
+                                             env: project_config.env, dry_run: dry_run)
+            verb = dry_run ? "Would install" : "Installed"
+            terminal.say "#{verb} skills for #{provider} → #{terminal.path(result[:dest_root])}"
+            result[:skills].each do |s|
+              terminal.say "  #{s[:name]}: #{terminal.style_skill_action(s[:action])} (#{terminal.path(s[:path])})"
+            end
+            CLI.record_outcome(Outcome.new(exit_code: 0))
+          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 +409,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 +579,15 @@ 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 "install-skills", SpaceArchitect::CLI::Architect::InstallSkills
+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/skill_installer.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module SpaceArchitect
+  module SkillInstaller
+    PROVIDERS = %w[claude codex opencode pi].freeze
+
+    class << self
+      def source_root
+        Pathname.new(__dir__).parent.parent.join("skill")
+      end
+
+      def dest_root(provider, project:, env:, cwd: Dir.pwd)
+        case provider.to_s
+        when "claude"
+          base = project ? Pathname.new(cwd) : Pathname.new(XDG.home(env: env))
+          base.join(".claude", "skills")
+        when "codex"
+          base = project ? Pathname.new(cwd) : Pathname.new(XDG.home(env: env))
+          base.join(".agents", "skills")
+        when "opencode"
+          project ? Pathname.new(cwd).join(".opencode", "skills") : XDG.config_home(env: env).join("skills")
+        when "pi"
+          base = project ? Pathname.new(cwd) : Pathname.new(pi_agent_dir(env: env))
+          base.join("skills")
+        else
+          raise Error, "Unknown provider '#{provider}'. Expected one of: #{PROVIDERS.join(', ')}"
+        end
+      end
+
+      def install(provider, project:, force:, env:, cwd: Dir.pwd, dry_run: false)
+        validate_provider!(provider)
+        dest = dest_root(provider, project: project, env: env, cwd: cwd)
+        results = []
+
+        source_skills.each do |skill_dir|
+          name = skill_dir.basename.to_s
+          skill_dest = dest.join(name)
+          results << install_skill(skill_dir, skill_dest, force: force, dry_run: dry_run)
+        end
+
+        { dest_root: dest, skills: results, dry_run: dry_run }
+      end
+
+      def source_skills
+        source_root.children.select(&:directory?)
+      end
+
+      private
+
+      def validate_provider!(provider)
+        return if PROVIDERS.include?(provider.to_s)
+
+        raise Error, "Unknown provider '#{provider}'. Expected one of: #{PROVIDERS.join(', ')}"
+      end
+
+      def pi_agent_dir(env:)
+        Pathname.new(env.fetch("PI_CODING_AGENT_DIR", File.join(XDG.home(env: env), ".pi", "agent")))
+      end
+
+      def install_skill(source, dest, force:, dry_run:)
+        name = source.basename.to_s
+
+        if dest.exist?
+          if same_content?(source, dest)
+            return { name: name, action: :unchanged, path: dest }
+          end
+
+          unless force
+            return { name: name, action: :conflict, path: dest } if dry_run
+
+            raise Error,
+              "Refusing to overwrite existing skill at #{dest}. Re-run with --force."
+          end
+
+          unless dry_run
+            FileUtils.rm_rf(dest)
+            FileUtils.cp_r(source, dest)
+          end
+          { name: name, action: dry_run ? :would_update : :updated, path: dest }
+        else
+          unless dry_run
+            FileUtils.mkdir_p(dest.parent)
+            FileUtils.cp_r(source, dest)
+          end
+          { name: name, action: dry_run ? :would_install : :installed, path: dest }
+        end
+      end
+
+      def same_content?(source, dest)
+        return false unless dest.directory?
+
+        source_files = Dir.glob("#{source}/**/*").reject { |f| File.directory?(f) }
+        dest_files = Dir.glob("#{dest}/**/*").reject { |f| File.directory?(f) }
+
+        return false if source_files.length != dest_files.length
+
+        source_files.sort.zip(dest_files.sort).all? do |sf, df|
+          rel = sf.sub("#{source}/", "")
+          df.end_with?(rel) && File.read(sf) == File.read(df)
+        end
+      end
+    end
+  end
+end

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/terminal.rb

@@ -74,6 +74,21 @@ module SpaceArchitect
       end.wait
     end
 
+    def style_skill_action(action)
+      case action.to_s
+      when "installed", "updated"
+        pastel.green(action)
+      when "would_install", "would_update"
+        pastel.cyan(action)
+      when "unchanged"
+        pastel.bright_black(action)
+      when "conflict"
+        pastel.yellow(action)
+      else
+        action.to_s
+      end
+    end
+
     private
 
     def color_mode

data/lib/space_architect/version.rb

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

data/lib/space_architect.rb

@@ -19,6 +19,7 @@ require_relative "space_architect/git_client"
 require_relative "space_architect/mise_client"
 require_relative "space_architect/space_store"
 require_relative "space_architect/shell_integration"
+require_relative "space_architect/skill_installer"
 require_relative "space_architect/terminal"
 require_relative "space_architect/harness"
 require_relative "space_architect/dispatcher"