space-architect 5.5.1 → 6.0.0

data/lib/space_architect/bug_report.rb

@@ -9,20 +9,31 @@ module Space
       REPO = "jetpks/space-architect"
 
       class << self
-        def generate(space: nil, env: ENV, cwd: Dir.pwd, now: Time.now)
+        def generate(space: nil, env: ENV, cwd: Dir.pwd, now: Time.now, title: nil)
           body_path = resolve_body_path(space, cwd, now)
           FileUtils.mkdir_p(body_path.dirname)
-          body = build_body(space)
+          body = build_body(space, title)
           body_path.write(body)
           contracted = Space::Core::Paths.contract(body_path, env: env)
+          title_flag = blank_title?(title) ? "" : " --title #{quote_title(title)}"
           command = Space::Core::Commands.wrap(
-            %(gh issue create -R #{REPO} --title "<one-line summary>" --body-file #{contracted})
+            %(gh issue create -R #{REPO}#{title_flag} --body-file #{contracted})
           )
           { body_path: body_path, command: command, body: body }
         end
 
         private
 
+        # Double-quote a title for a POSIX shell: quotes preserve spaces
+        # literally, only the characters special inside double quotes are escaped.
+        def quote_title(title)
+          %("#{title.gsub(/["\\$`]/) { |m| "\\#{m}" }}")
+        end
+
+        def blank_title?(title)
+          title.to_s.strip.empty?
+        end
+
         def resolve_body_path(space, cwd, now)
           filename = "architect-bug-report-#{now.strftime('%Y%m%d-%H%M%S')}.md"
           if space
@@ -32,8 +43,10 @@ module Space
           end
         end
 
-        def build_body(space)
-          body = +template_header
+        def build_body(space, title)
+          body = +""
+          body << "# #{title}\n\n" unless blank_title?(title)
+          body << template_header
           body << diagnostics_section
           body << space_section(space) if space
           body
@@ -41,8 +54,6 @@ module Space
 
         def template_header
           <<~MD
-            <!-- Title: <one-line summary> -->
-
             **Kind:** <!-- process / tooling / both -->
 
             ## Summary

data/lib/space_architect/cli/architect.rb

@@ -226,23 +226,127 @@ module Space::Architect
         end
       end
 
+      class Rehearse < BaseCommand
+        desc "Rehearse the DRAFTED (unfrozen, working-tree) gates against the repo checkout and report RED/GREEN/BROKEN/EMPTY — runs and reports, never judges"
+        phase 12, "Spec"
+        argument :iteration, required: true,  desc: "Iteration name"
+        argument :space,     required: false, desc: "Space identifier (default: $PWD)"
+        # type: :flag (not :boolean): dry-cli renders a :boolean option as
+        # "--[no-]record" in --help, which does not contain the literal
+        # substring "--record" that a presence-check on the flag would look
+        # for; :flag renders unbracketed ("--record") and is presence-only,
+        # which is all this needs.
+        option   :record, type: :flag, default: false, desc: "Emit a paste-able provenance block summarizing the run, shaped to drop into an Acceptance Criteria preamble"
+
+        def call(iteration:, space: nil, record: false, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            render(store.find(space)) do |sp|
+              project = ArchitectProject.new(space: sp)
+              result = project.rehearse(iteration)
+              render_rehearsal(result)
+              terminal.say ""
+              terminal.say render_record(result) if record
+              CLI.record_outcome(Outcome.new(exit_code: 0))
+            end
+          end
+        end
+
+        private
+
+        def render_rehearsal(result)
+          if result[:empty]
+            reason = result[:placeholder] ? "the scaffold placeholder '#{ArchitectProject::AC1_PLACEHOLDER}' with no active gate" : "no gates drafted yet"
+            terminal.say "EMPTY — #{reason}. Nothing to rehearse; the pre-freeze look is still stamped."
+          else
+            terminal.say "Rehearsing #{result[:iteration]} against #{terminal.path(result[:base_dir])} (repo: #{result[:repo]})"
+            result[:gates].each { |g| render_gate(g) }
+            render_scope_asymmetry(result[:scope_asymmetry])
+          end
+          terminal.say ""
+          terminal.say "Discrimination report only — this runs and reports; it never judges whether these gates are good, bad, or ready."
+        end
+
+        def render_gate(g)
+          terminal.say ""
+          terminal.say "── #{g[:ac].empty? ? "(gate)" : g[:ac]}: #{g[:cmd]}  (exit #{g[:exit_code].inspect})  [#{g[:rehearsal].to_s.upcase}]"
+          terminal.say "   dir: #{terminal.path(g[:dir])}"
+          terminal.say "   reason: #{g[:reason]}" unless g[:reason].to_s.empty?
+          if g[:rehearsal] == :broken
+            terminal.say "   BROKEN is advisory, not certain — a correct RED can look broken (e.g. a file the lane " \
+              "hasn't written yet). Confirm before treating it as a defect."
+          end
+          terminal.say g[:stdout].rstrip unless g[:stdout].strip.empty?
+          terminal.say g[:stderr].rstrip unless g[:stderr].strip.empty?
+        end
+
+        # I12/AC3-AC4: reports scope asymmetry only — never affects RED/GREEN/
+        # BROKEN, rehearse's exit code, or the stamp. A file outside every
+        # declared lane's touch set is flagged loudest: it's the one no lane
+        # may legally fix. not_analyzable is rendered too, and counted, so a
+        # reader can tell "nothing matched" from "nothing was examined".
+        def render_scope_asymmetry(report)
+          return if report.nil? || (report[:findings].empty? && report[:not_analyzable].empty?)
+
+          terminal.say ""
+          terminal.say "Scope-asymmetry check (grep-family gates only):"
+          report[:findings].each do |f|
+            terminal.say "── #{f[:id]}: pattern #{f[:pattern].inspect} searched #{f[:paths].join(', ')}"
+            if f[:outside_lanes].any?
+              terminal.say "   OUTSIDE ANY LANE'S TOUCH SET — no lane may legally fix these:"
+              f[:outside_lanes].each { |file| terminal.say "     #{file}" }
+            end
+            terminal.say "   also matches (within a declared lane's touch set): #{f[:within_lanes].join(', ')}" if f[:within_lanes].any?
+            terminal.say "   0 files elsewhere match" if f[:outside_lanes].empty? && f[:within_lanes].empty?
+          end
+
+          return if report[:not_analyzable].empty?
+          terminal.say ""
+          terminal.say "Not analyzed (#{report[:not_analyzable].size} grep invocation(s)) — counted, not silently skipped:"
+          report[:not_analyzable].each { |na| terminal.say "   #{na[:id]}: #{na[:reason]}" }
+        end
+
+        def render_record(result)
+          return "> Rehearsed #{result[:iteration]} — no gates drafted; nothing to record." if result[:empty]
+
+          by  = result[:gates].group_by { |g| g[:rehearsal] }
+          ids = ->(sym) { (by[sym] || []).map { |g| g[:id] }.join(", ") }
+          [
+            "> **Dry-run at rehearsal time, recorded for transparency.** All #{result[:gates].size} gate command(s) " \
+              "were executed as written against `#{result[:repo]}` under `/bin/sh` — the shell `architect gate` uses.",
+            ">",
+            "> - **RED (#{(by[:red] || []).size} — discriminate):** #{ids.call(:red).empty? ? "(none)" : ids.call(:red)}",
+            "> - **GREEN (#{(by[:green] || []).size} — regression guard or non-discriminating):** #{ids.call(:green).empty? ? "(none)" : ids.call(:green)}",
+            "> - **BROKEN (#{(by[:broken] || []).size} — advisory, confirm each):** #{ids.call(:broken).empty? ? "(none)" : ids.call(:broken)}"
+          ].join("\n")
+        end
+      end
+
       class Freeze < BaseCommand
         desc "Freeze the iteration's frozen region (Grounds/Specification/Acceptance Criteria) and record the freeze SHA"
-        phase 12, "Spec"
+        phase 13, "Spec"
         argument :iteration, required: true, desc: "Iteration name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
         option   :force, type: :boolean, default: false, desc: "Re-freeze even if the frozen region changed (pre-dispatch only)"
+        # Named --skip-rehearse, not --no-rehearse: Ruby's OptionParser (dry-cli's
+        # underlying parser, verified against the live dry-cli 1.4.1 in this repo)
+        # treats ANY switch literally named --no-<word> as a boolean negation and
+        # silently discards its value, regardless of declared type — so a REASON
+        # cannot bind to a flag spelled --no-rehearse. --skip-rehearse is the
+        # working escape valve; --no-rehearse is the name this design uses for it.
+        option   :skip_rehearse, default: nil, desc: "Escape valve (design name: --no-rehearse): skip the fresh-rehearsal requirement, recording REASON in space.yaml (bare freeze refuses without a matching `architect rehearse` stamp)"
         commit_message_options
 
-        def call(iteration:, space: nil, message: nil, message_from: nil, force: false, **opts)
+        def call(iteration:, space: nil, message: nil, message_from: nil, force: false, skip_rehearse: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
               warnings = []
-              sha = project.freeze!(iteration, warnings: warnings, force: force,
+              sha = project.freeze!(iteration, warnings: warnings, force: force, skip_rehearse_reason: skip_rehearse,
                 message: read_commit_message(message: message, message_from: message_from))
               terminal.say "Frozen #{iteration} at #{sha}"
+              terminal.say "Rehearsal requirement skipped — #{skip_rehearse}" if skip_rehearse
               warnings.each { |w| terminal.say "Warning: #{w}" }
               ac = project.acceptance_criteria(iteration)
               unless ac.to_s.strip.empty?
@@ -402,6 +506,9 @@ module Space::Architect
                   terminal.say "Report:  #{terminal.path(res[:report])}"
                   terminal.say "Ingest URL:  #{res[:push_url]}" if res[:push_url]
                   terminal.say "Builder exited with status #{res[:exit_code]}"
+                  unless res[:report].exist? && !res[:report].read.strip.empty?
+                    terminal.say "WARNING: no report at #{terminal.path(res[:report])} — the lane produced no deliverable."
+                  end
                   CLI.record_outcome(Outcome.new(exit_code: res[:exit_code]))
                 end
               end
@@ -560,9 +667,10 @@ module Space::Architect
         option   :teardown,    type: :boolean, default: false, desc: "Remove worktrees + delete lane branches after merge"
         option   :commit_mode, default: nil,    desc: "Commit mode override (strict|conductor); overrides space.yaml commit_mode for this run"
         option   :into,        required: false, desc: "Merge into this branch instead of the slug-derived project/<slug> default"
+        option   :accept_bounds, default: nil,  desc: "Escape valve: override the in-bounds check for these lanes when the frozen touch-set glob is itself the defect, recording REASON in space.yaml (never overrides the no-builder-commits check)"
         commit_message_options
 
-        def call(iteration:, space: nil, lanes: nil, teardown: false, message: nil, message_from: nil, commit_mode: nil, into: nil, **opts)
+        def call(iteration:, space: nil, lanes: nil, teardown: false, message: nil, message_from: nil, commit_mode: nil, into: nil, accept_bounds: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             lane_names = lanes.to_s.split(",").map(&:strip).reject(&:empty?)
@@ -573,7 +681,7 @@ module Space::Architect
               project = ArchitectProject.new(space: sp)
               results = project.integrate!(iteration, lanes: lane_names, teardown: teardown,
                 message: read_commit_message(message: message, message_from: message_from),
-                commit_mode: commit_mode, into: into)
+                commit_mode: commit_mode, into: into, accept_bounds_reason: accept_bounds)
               if lane_names.empty?
                 if results.empty?
                   terminal.say "Nothing to tear down for #{iteration}"
@@ -585,6 +693,7 @@ module Space::Architect
               else
                 results.each do |r|
                   terminal.say "Merged #{r[:lane]} → #{r[:integration_branch]} (#{r[:merge_sha][0, 8]})"
+                  terminal.say "In-bounds check overridden for #{r[:lane]}: #{r[:bounds_override_reason]}" if r[:bounds_override_reason]
                 end
                 terminal.say "Gates NOT run — run gates: `architect gate #{iteration}`"
               end
@@ -611,6 +720,7 @@ module Space::Architect
                 marker = r[:status] == :pass ? "PASS" : "FAIL"
                 terminal.say ""
                 terminal.say "── #{r[:ac].empty? ? "(gate)" : r[:ac]}: #{r[:cmd]}  (exit #{r[:exit_code]})  [#{marker}]"
+                terminal.say "   dir: #{terminal.path(r[:dir])}"
                 terminal.say "   reason: #{r[:reason]}" if r[:status] == :fail && !r[:reason].to_s.empty?
                 terminal.say r[:stdout].rstrip unless r[:stdout].strip.empty?
                 terminal.say r[:stderr].rstrip unless r[:stderr].strip.empty?
@@ -627,15 +737,20 @@ module Space::Architect
       class BugReport < BaseCommand
         desc "Generate a prefilled GitHub issue template for filing bugs against space-architect"
         phase 54, "Project"
+        option :title, default: nil, desc: "Issue title, written into --title and the body's leading H1 (omit and gh will prompt for one interactively — the body file does not set it)"
 
-        def call(**opts)
+        def call(title: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             space = store.find.value_or(nil)
             result = Space::Architect::BugReport.generate(
               space: space,
-              env: project_config.env
+              env: project_config.env,
+              title: title
             )
+            unless title
+              terminal.say "No --title given — the body file does not set the issue title; re-run as architect bug-report --title \"...\" to set it in the command (or gh will prompt you for one)."
+            end
             terminal.say "Fill the placeholders in #{terminal.path(result[:body_path].to_s)}, then run:"
             terminal.say result[:command]
             terminal.say ""
@@ -1090,6 +1205,7 @@ Space::Architect::CLI::Registry.register "ground", Space::Architect::CLI::Archit
 Space::Architect::CLI::Registry.register "new",    Space::Architect::CLI::Architect::New
 Space::Architect::CLI::Registry.register "status", Space::Architect::CLI::Architect::Status
 Space::Architect::CLI::Registry.register "sync",   Space::Architect::CLI::Architect::Sync
+Space::Architect::CLI::Registry.register "rehearse", Space::Architect::CLI::Architect::Rehearse
 Space::Architect::CLI::Registry.register "freeze", Space::Architect::CLI::Architect::Freeze
 Space::Architect::CLI::Registry.register "verify", Space::Architect::CLI::Architect::Verify
 Space::Architect::CLI::Registry.register "provision", Space::Architect::CLI::Architect::Provision

data/lib/space_architect/cli/research.rb

@@ -6,8 +6,8 @@ module Space::Architect
       module Research
         class Dispatch < BaseCommand
           desc "Dispatch detached read-only research lanes (one per prompt file)"
-          argument :prompts, required: true,
-                             desc: "Prompt file(s) to dispatch (space-separated paths)"
+          argument :prompts, type: :array, required: true,
+            desc: "Prompt file(s) to dispatch (space-separated paths)"
           option :model,     default: nil, desc: "Researcher model override (default: the reference default claude-sonnet-4-6)"
           option :max_turns, default: "40", desc: "Max turns per researcher"
 
@@ -15,11 +15,10 @@ module Space::Architect
             setup_terminal(**opts.slice(:color, :colors))
             handle_errors do
               render(store.find(opts[:space])) do |sp|
-                paths = Array(prompts)
                 supervisor = Space::Architect::Research::Supervisor.new(space: sp)
                 kwargs = { max_turns: max_turns.to_i }
                 kwargs[:model] = model if model
-                runs = supervisor.dispatch(paths, **kwargs)
+                runs = supervisor.dispatch(prompts, **kwargs)
                 runs.each do |run|
                   terminal.say "dispatched #{run.id} (pid #{run.pid}) → #{terminal.path(run.run_log_path)}"
                 end

data/lib/space_architect/harness.rb

@@ -115,10 +115,19 @@ module Space::Architect
 
       TIMEOUT_EXIT_CODE = 124
 
-      # How long the liveness fiber waits before reading the run log's stream-json init
-      # event. Injectable via the run(liveness_delay:) kwarg so tests need not sleep seconds.
+      # The liveness fiber's total wait budget before it gives up on the run log's
+      # stream-json init event. Injectable via the run(liveness_delay:) kwarg so tests
+      # need not sleep seconds.
       LIVENESS_DELAY_SECONDS = 5.0
 
+      # The liveness fiber's actual deadline is liveness_delay * LIVENESS_BUDGET_FACTOR —
+      # a healthy child whose first write lands just after one delay window is still
+      # alive, not dead, so the budget spans several delay-lengths, not one.
+      LIVENESS_BUDGET_FACTOR = 3
+
+      # How often the liveness fiber re-checks the run log for growth while waiting.
+      LIVENESS_POLL_INTERVAL = 0.05
+
       def run(prompt_path:, run_log_path:, chdir:, push_url: nil, push_token: nil, push_client: nil, timeout: nil,
               liveness_delay: LIVENESS_DELAY_SECONDS, err: $stderr)
         prompt_path  = Pathname.new(prompt_path)
@@ -148,15 +157,24 @@ module Space::Architect
                 end
               end
 
-              # Liveness self-check: after a bounded delay, read the run log's stream-json
-              # init event and print ONE line naming the streamed model + confirming growth.
-              # transient: true so it never keeps the reactor alive; best-effort so it never
-              # raises into the run path. run_detached gets no such fiber.
+              # Liveness self-check: read the run log's stream-json init event and print ONE
+              # line naming the streamed model + true elapsed time. A single point-sample right
+              # at liveness_delay would report a healthy child dead if its first write landed a
+              # moment later, so this polls (like Research::Mux#wait_for_file) to a deadline of
+              # several delay-lengths, emitting as soon as the log holds a parseable init event —
+              # a bounded wait, not an unbounded one, and not satisfied by mere non-emptiness (the
+              # child's stderr is teed into the same run log, so one early stderr byte must not
+              # count). transient: true so it never keeps the reactor alive; best-effort so it
+              # never raises into the run path. run_detached gets no such fiber.
               liveness_task = nil
               if liveness_delay && liveness_delay > 0
                 liveness_task = Async(transient: true) do
-                  sleep liveness_delay
-                  emit_liveness(run_log_path, liveness_delay, err)
+                  start    = Time.now
+                  deadline = start + (liveness_delay * LIVENESS_BUDGET_FACTOR)
+                  until init_event_ready?(run_log_path) || Time.now >= deadline
+                    sleep LIVENESS_POLL_INTERVAL
+                  end
+                  emit_liveness(run_log_path, Time.now - start, err)
                 end
               end
 
@@ -207,18 +225,60 @@ module Space::Architect
 
       private
 
+      # The liveness fiber's wait predicate: ready once the run log holds a parseable
+      # stream-json init event — not merely once it holds any bytes, since the child's
+      # stderr is teed into the same run log and one early stderr byte must not satisfy it.
+      #
+      # Scans only the bytes appended since the previous poll (remembering the offset
+      # in @liveness_offset) instead of re-parsing the whole log from the top on every
+      # 50ms tick — the child that never emits an init event would otherwise cost
+      # O(polls x log size) inside a fiber sharing the reactor with the dispatch itself.
+      def init_event_ready?(run_log_path)
+        return true if @liveness_model
+
+        @liveness_offset ||= 0
+        File.open(run_log_path, "r") do |f|
+          f.seek(@liveness_offset)
+          f.each_line do |line|
+            break unless line.end_with?("\n")
+            @liveness_offset = f.pos
+            ev = begin
+              JSON.parse(line)
+            rescue JSON::ParserError
+              next
+            end
+            next unless ev.is_a?(Hash) && ev["type"] == "system" && ev["subtype"] == "init"
+            @liveness_model = ev["model"]
+            break
+          end
+        end
+        !@liveness_model.nil?
+      rescue StandardError
+        false
+      end
+
       # Read the run log's stream-json init event and print exactly one bounded liveness
-      # line to err. Best-effort: swallows any read/parse error so it never raises into run.
-      def emit_liveness(run_log_path, delay, err)
+      # line to err, naming the true elapsed wall-clock time since dispatch. Best-effort:
+      # swallows any read/parse error so it never raises into run.
+      #
+      # Reuses init_event_ready?'s own incremental scan rather than re-parsing the
+      # whole log from the top: when the poll loop already found the init event,
+      # @liveness_model is set and this is a no-op re-check; when it ended on the
+      # deadline without one, this performs exactly one more forward scan from
+      # @liveness_offset, so bytes appended between the last poll and this call are
+      # still observed — a scan forward from the cached offset, never a skipped one.
+      def emit_liveness(run_log_path, elapsed, err)
         bytes = run_log_path.exist? ? run_log_path.size : 0
+        elapsed = elapsed.round(1)
         if bytes.zero?
-          err.puts "liveness: WARN no growth — run log still empty #{delay}s after dispatch"
+          err.puts "liveness: WARN no growth — run log still empty #{elapsed}s after dispatch"
           return
         end
 
-        streamed = streamed_init_model(run_log_path)
+        init_event_ready?(run_log_path)
+        streamed = @liveness_model
         if streamed.nil?
-          err.puts "liveness: WARN model unverified — no stream-json init event after #{delay}s (run log #{bytes} bytes)"
+          err.puts "liveness: WARN model unverified — no stream-json init event after #{elapsed}s (run log #{bytes} bytes)"
         elsif streamed == @model
           err.puts "liveness: OK streaming model=#{streamed} (run log growing, #{bytes} bytes)"
         else
@@ -228,21 +288,6 @@ module Space::Architect
         # Best-effort: an internal read/parse failure must never break the run.
       end
 
-      # The model named by the stream-json init event ({"type":"system","subtype":"init",...}),
-      # or nil if no such event has been logged yet.
-      def streamed_init_model(run_log_path)
-        run_log_path.each_line do |line|
-          ev = begin
-            JSON.parse(line)
-          rescue JSON::ParserError
-            next
-          end
-          next unless ev.is_a?(Hash) && ev["type"] == "system" && ev["subtype"] == "init"
-          return ev["model"]
-        end
-        nil
-      end
-
       def argv
         [@bin, "-p", "--model", @model, "--output-format", "stream-json", "--verbose"] + builder_args
       end

data/lib/space_architect/session_sync/runner.rb

@@ -53,8 +53,10 @@ module Space::Architect
       end
 
       def files
-        pi = Dir.glob(File.join(@pi_root, "**", "*.jsonl")).map { |p| [p, SessionId.for_pi(p)] }
-        claude = Dir.glob(File.join(@claude_root, "**", "*.jsonl")).map { |p| [p, SessionId.for_claude(p)] }
+        pi = Space::Core::Paths.content_tree(@pi_root).select { |p| p.end_with?(".jsonl") }
+          .map { |p| [p, SessionId.for_pi(p)] }
+        claude = Space::Core::Paths.content_tree(@claude_root).select { |p| p.end_with?(".jsonl") }
+          .map { |p| [p, SessionId.for_claude(p)] }
         pi + claude
       end
     end

data/lib/space_architect/skill_installer.rb

@@ -46,7 +46,7 @@ module Space
         end
 
         def source_skills
-          source_root.children.select(&:directory?)
+          Space::Core::Paths.layout_children(source_root).select(&:directory?)
         end
 
         private
@@ -93,8 +93,8 @@ module Space
         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) }
+          source_files = Space::Core::Paths.content_tree(source).reject { |f| File.directory?(f) }
+          dest_files = Space::Core::Paths.content_tree(dest).reject { |f| File.directory?(f) }
 
           return false if source_files.length != dest_files.length
 

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

@@ -31,7 +31,9 @@ Write + commit: `architect section <%= @_name %> specification --from <file>`. -
   machine-readable declaration lives in the fenced ```lanes block below — the single
   frozen source of truth `architect freeze` records and `architect provision`
   materializes.
-- **Effort** — `think hard` … `ultrathink` per lane, with one line of why.
+- **Effort** — per lane, set at dispatch: `architect dispatch --effort <level>`,
+  translated + clamped to the lane's harness, with one line of why (the
+  escalation keywords `think hard` … `ultrathink` still work in-prompt).
 
 ```lanes
 # One entry per lane (1–4). The frozen out-of-bounds contract: `architect freeze`
@@ -39,17 +41,33 @@ Write + commit: `architect section <%= @_name %> specification --from <file>`. -
 # materializes the worktrees + lane branches. Remove the comment markers to activate.
 # - name: lane-a            # lane name (required)
 #   repo: my-repo           # target repo under repos/ (required)
-#   touch:                  # file globs this lane may write (required, non-empty)
-#     - lib/my_repo/**
+#   touch:                  # every file this lane may write, enumerated — no globs (required, non-empty)
+#     - lib/my_repo/foo.rb
+#     - lib/my_repo/bar.rb
 #     - test/my_repo_test.rb
 ```
 
 ## Acceptance Criteria
 
 <!-- PROOF. Write the prose conditions of correctness (AC1, AC2, …) that the
-architect judges against. Runnable checks live in the fenced ```gates block below
+architect judges against. Calibrate precision to the property (SKILL.md §4): a
+property criterion is bounded from the defect's side only — freeze a floor, not
+an equality; exactness is for criteria whose number is itself the deliverable.
+A presence-grep gate on prose is a tripwire, never the proof — its criterion
+should say which. Runnable checks live in the fenced ```gates block below
 (parsed at freeze time — absent or empty is allowed; malformed fails freeze).
-`architect freeze <%= @_name %>` commits this file and records its SHA as
+Pre-freeze check — snapshot: no count/name-set/byte-identity frozen at merely
+today's value; control: every baseline actually run this session; mechanism: no
+*how* where the *what* is the requirement; interface: every CLI surface the
+Specification names (verb, flag spelling, subcommand) executed once before it
+freezes; dry-run:
+`architect rehearse <%= @_name %>` — RED (clean non-zero) discriminates; GREEN
+is a declared regression guard or a gate that measures nothing; BROKEN is
+advisory (a correct RED can look broken — confirm it); EMPTY is no gates or an
+untouched placeholder.
+`architect freeze <%= @_name %>` needs a fresh rehearsal stamp — editing gates
+stales it; `--skip-rehearse REASON` records the skip. The stamp records that you
+looked, never that gates passed. Freeze commits this file and records its SHA as
 freeze_sha. Read-only afterward — any change to Grounds/Specification/Acceptance
 Criteria = automatic iteration FAIL. -->
 
@@ -60,12 +78,22 @@ Criteria = automatic iteration FAIL. -->
 
 ```gates
 # Each gate backs one prose AC above. Remove the comment markers to activate.
+# `cmd` paths resolve against the REPO TREE; `cwd` is relative to the SPACE
+# ROOT. The judge-time remap is asymmetric: a `cwd` under repos/<repo> is
+# remapped into the lane worktree, one outside it passes through unchanged.
+# End a multi-step `cmd` with `echo SENTINEL` + `stdout_match`: /bin/sh (the
+# gate runner's shell) has no `set -e`, so an early branch can exit 0 — the
+# sentinel proves the command reached its end.
+# Draft, then run `architect rehearse <%= @_name %>` — before the freeze, while
+# a bad gate still costs nothing.
 # - id: suite-green        # unique slug within the iteration (required)
 #   ac: AC1                # which prose AC this gate backs (required)
-#   cwd: repos/my-repo     # run dir, relative to space root (optional; consumed by I03)
-#   cmd: bundle exec rake test  # shell command (required, non-empty)
+#   cwd: repos/my-repo     # run dir, space-root-relative (optional)
+#   cmd: |-                # block style by default — a plain scalar breaks on `: `
+#     bundle exec rake test && echo SUITE_OK
 #   expect:                # at least one of: exit_code, stdout_match, threshold
 #     exit_code: 0
+#     stdout_match: SUITE_OK
 ```
 
 ## Builder Prompt

data/lib/space_core/cli/help.rb

@@ -90,6 +90,7 @@ module Space::Core::CLI
     # members within a group, ordered by the declared order), with undeclared
     # children (namespaces) trailing in the default group.
     def grouped_listing(result)
+      # paths:exempt - result.children is a dry-cli command-tree node, not a filesystem path
       decorated = result.children.filter_map do |name, node|
         [name, node, phase_of(node)] unless node.hidden
       end
@@ -150,6 +151,7 @@ module Space::Core::CLI
     end
 
     def banner(node)
+      # paths:exempt - node.children? is a dry-cli command-tree predicate, not a filesystem path
       if node.command && node.leaf? && node.children?
         " [ARGUMENT|SUBCOMMAND]"
       elsif node.leaf?

data/lib/space_core/commands.rb

@@ -8,7 +8,7 @@ module Space::Core
     # "--flag" boundaries, continuation lines indented two spaces. Commands
     # without "--" flags are returned unchanged.
     def wrap(command)
-      parts = command.split(/(?= --)/)
+      parts = split_at_flag_boundaries(command)
       return command if parts.size <= 1
 
       parts.each_with_index.map do |part, i|
@@ -16,5 +16,36 @@ module Space::Core
         i < parts.size - 1 ? "#{segment} \\" : segment
       end.join("\n")
     end
+
+    # Same split points as command.split(/(?= --)/), but blind to " --" that
+    # falls inside a single- or double-quoted flag value, so a --title
+    # containing " -- " isn't torn apart mid-argument.
+    def split_at_flag_boundaries(command)
+      parts = []
+      start = 0
+      in_squote = false
+      in_dquote = false
+      escaped = false
+      command.each_char.with_index do |ch, i|
+        if escaped
+          escaped = false
+          next
+        end
+        case ch
+        # A backslash escapes the next character outside quotes and inside
+        # double quotes, but is a literal character inside single quotes.
+        when "\\" then escaped = true unless in_squote
+        when "'" then in_squote = !in_squote unless in_dquote
+        when '"' then in_dquote = !in_dquote unless in_squote
+        when " "
+          if !in_squote && !in_dquote && command[i + 1, 2] == "--"
+            parts << command[start...i]
+            start = i
+          end
+        end
+      end
+      parts << command[start..]
+      parts
+    end
   end
 end

data/lib/space_core/paths.rb

@@ -1,9 +1,44 @@
 # frozen_string_literal: true
 
+require "pathname"
+
 module Space::Core
   module Paths
+    # paths:exempt-file - the shared module itself — this is the one home the guard defends
     module_function
 
+    # Flags for matching a changed path against a lane's touch_set globs.
+    # PATHNAME keeps a single `*` from crossing `/`; EXTGLOB enables `{a,b}`;
+    # DOTMATCH lets a glob reach dotfile segments, so a `dir/**` touch set covers
+    # `dir/.github/workflows/ci.yml` — the standard deliverable for a lane preparing
+    # a directory to become a repo root.
+    TOUCH_FNM = File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH
+
+    # Every path beneath root, at every depth: files, directories, dotfiles, and
+    # dot-directory contents all included. `File::FNM_DOTMATCH` is what makes
+    # dotfiles visible to `Dir.glob`, but it also emits a bogus `root/.`
+    # self-entry — that trap is absorbed here so no callsite has to know about it.
+    # Returns Array<String> — Dir.glob's native return shape.
+    def content_tree(root)
+      Dir.glob(File.join(root.to_s, "**", "*"), File::FNM_DOTMATCH).reject { |p| File.basename(p) == "." }
+    end
+
+    # The direct children of a fixed-depth structured directory layout (one
+    # entry per iteration/skill/lane/space) where a leading dot never names a
+    # real layout member — only tooling junk (.git, .DS_Store). Excludes them.
+    # Returns Array<Pathname> — Pathname#children's native return shape.
+    def layout_children(dir)
+      Pathname.new(dir).children.reject { |c| c.basename.to_s.start_with?(".") }
+    end
+
+    # Does a single touch_set glob match path? A trailing `dir/**` is matched
+    # twice: bare (PATHNAME stops it at direct children) and as `dir/**/*`,
+    # whose whole-component `**/` does cross `/`.
+    def touch_match?(glob, path)
+      File.fnmatch(glob, path, TOUCH_FNM) ||
+        (glob.end_with?("/**") && File.fnmatch("#{glob}/*", path, TOUCH_FNM))
+    end
+
     def contract(path, env: ENV)
       value = path.to_s
       home  = XDG.home(env: env)