space-architect 3.0.0 → 4.0.0

data/lib/space_architect/harness.rb

@@ -56,7 +56,12 @@ module Space::Architect
 
       TIMEOUT_EXIT_CODE = 124
 
-      def run(prompt_path:, run_log_path:, chdir:, push_url: nil, push_token: nil, push_client: nil, timeout: nil)
+      # 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.
+      LIVENESS_DELAY_SECONDS = 5.0
+
+      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)
         run_log_path = Pathname.new(run_log_path)
 
@@ -66,7 +71,7 @@ module Space::Architect
             Sync do
               child = Async::Process::Child.new(*argv, chdir: chdir.to_s, in: prompt_io, out: w, err: log)
               w.close
-              tasks = start_tee(r, log, push_url: push_url, push_token: push_token, push_client: push_client)
+              tasks = start_tee(r, log, push_url: push_url, push_token: push_token, push_client: push_client, err: err)
               timed_out    = false
               timeout_task = nil
 
@@ -84,8 +89,21 @@ 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_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)
+                end
+              end
+
               status = child.wait
               timeout_task&.stop
+              liveness_task&.stop
 
               tasks.each(&:wait)
               timed_out ? TIMEOUT_EXIT_CODE : status.exitstatus
@@ -113,6 +131,42 @@ module Space::Architect
 
       private
 
+      # 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)
+        bytes = run_log_path.exist? ? run_log_path.size : 0
+        if bytes.zero?
+          err.puts "liveness: WARN no growth — run log still empty #{delay}s after dispatch"
+          return
+        end
+
+        streamed = streamed_init_model(run_log_path)
+        if streamed.nil?
+          err.puts "liveness: WARN model unverified — no stream-json init event after #{delay}s (run log #{bytes} bytes)"
+        elsif streamed == @model
+          err.puts "liveness: OK streaming model=#{streamed} (run log growing, #{bytes} bytes)"
+        else
+          err.puts "liveness: WARN model mismatch — pinned=#{@model} streamed=#{streamed} (run log growing, #{bytes} bytes)"
+        end
+      rescue StandardError
+        # 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
         args = [
           @bin, "-p",
@@ -128,17 +182,17 @@ module Space::Architect
         args
       end
 
-      def start_tee(r, log, push_url:, push_token:, push_client:)
+      def start_tee(r, log, push_url:, push_token:, push_client:, err: $stderr)
         if push_url || push_client
           body = Protocol::HTTP::Body::Writable.new(queue: Thread::SizedQueue.new(32))
-          push = Async { push_body(body, push_url: push_url, push_token: push_token, push_client: push_client) }
-          [Async { tee_pipe(r, log, body) }, push]
+          push = Async { push_body(body, push_url: push_url, push_token: push_token, push_client: push_client, err: err) }
+          [Async { tee_pipe(r, log, body, err: err) }, push]
         else
           [Async { drain_pipe(r, log) }]
         end
       end
 
-      def push_body(body, push_url:, push_token:, push_client:)
+      def push_body(body, push_url:, push_token:, push_client:, err: $stderr)
         path    = push_url ? URI.parse(push_url).path : "/"
         headers = [["content-type", "application/x-ndjson"]]
         headers << ["authorization", "Bearer #{push_token}"] if push_token
@@ -150,10 +204,10 @@ module Space::Architect
           end
         end
       rescue StandardError => e
-        $stderr.puts "push_body: transport error (best-effort, run log intact): #{e.class}: #{e.message}"
+        err.puts "push_body: transport error (best-effort, run log intact): #{e.class}: #{e.message}"
       end
 
-      def tee_pipe(r, log, body)
+      def tee_pipe(r, log, body, err: $stderr)
         pushing = true
         while (chunk = r.gets)
           log.write(chunk)
@@ -162,7 +216,7 @@ module Space::Architect
             begin
               body.write(chunk)
             rescue StandardError => e
-              $stderr.puts "tee_pipe: push write failed (best-effort, continuing log): #{e.class}: #{e.message}"
+              err.puts "tee_pipe: push write failed (best-effort, continuing log): #{e.class}: #{e.message}"
               pushing = false
             end
           end

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

@@ -27,9 +27,23 @@ Write + commit: `architect section <%= @_name %> specification --from <file>`. -
 - **Boundaries** — may-touch / must-not-touch / out-of-scope; no placeholders;
   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.
+  file-touch set (overlap-checked), objective, output format, boundaries. The
+  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.
 
+```lanes
+# One entry per lane (1–4). The frozen out-of-bounds contract: `architect freeze`
+# writes each into space.yaml (name, repo, touch_set); `architect provision <%= @_name %>`
+# 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/**
+#     - test/my_repo_test.rb
+```
+
 ## Acceptance Criteria
 
 <!-- PROOF. Write the prose conditions of correctness (AC1, AC2, …) that the

data/lib/space_core/cli/help.rb

@@ -2,6 +2,7 @@
 
 require "dry/cli"
 require "pastel"
+require_relative "loop_status"
 
 module Space::Core::CLI
   # Colourful replacement for dry-cli's plain `Usage` listing — the "global
@@ -27,17 +28,30 @@ module Space::Core::CLI
 
     module_function
 
-    def call(result, pastel: CLI.help_pastel)
-      rows  = listing(result)
-      width = rows.map { |label, _| label.length }.max || 0
+    # Header for the trailing group of children that declare no phase. Left nil
+    # for the `space` binary (whose commands are all phase-less → one ungrouped
+    # listing); the `architect` binary sets it so its namespaces list under a
+    # "Groups" header. Keeps phase vocabulary out of this generic renderer.
+    def self.trailing_group_label = @trailing_group_label
+
+    def self.trailing_group_label=(label)
+      @trailing_group_label = label
+    end
 
-      lines = rows.map do |label, description|
-        painted = pastel.cyan(label.ljust(width))
-        description ? "  #{painted}   #{pastel.dim("# #{description}")}" : "  #{painted}"
+    def call(result, pastel: CLI.help_pastel)
+      groups = grouped_listing(result)
+      width  = groups.flat_map { |_h, rows| rows.map { |label, _| label.length } }.max || 0
+
+      body = groups.flat_map do |group_header, rows|
+        lines = rows.map do |label, description|
+          painted = pastel.cyan(label.ljust(width))
+          description ? "  #{painted}   #{pastel.dim("# #{description}")}" : "  #{painted}"
+        end
+        group_header ? ["", pastel.bold(group_header), *lines] : lines
       end
 
-      [header(result, pastel), pastel.bold("Commands:"), *lines, footer(result, pastel)]
-        .compact.join("\n")
+      [header(result, pastel), pastel.bold("Commands:"), *body,
+       footer(result, pastel), loop_status_block(result, pastel)].compact.join("\n")
     end
 
     # The richer header only makes sense at the true root (`space` / `architect`),
@@ -69,13 +83,66 @@ module Space::Core::CLI
       [prog, *names].join(" ")
     end
 
-    # [[label_with_banner, description_or_nil], ...] sorted by command name.
-    def listing(result)
-      result.children.sort_by { |name, _| name }.filter_map do |name, node|
-        next if node.hidden
+    # Group non-hidden children into an ordered list of [header_or_nil, rows].
+    # When no child declares a phase (e.g. the `space` binary), returns a single
+    # unlabelled group sorted by name — byte-identical to the pre-phase listing.
+    # Otherwise groups declared commands under their phase label (groups, and
+    # members within a group, ordered by the declared order), with undeclared
+    # children (namespaces) trailing in the default group.
+    def grouped_listing(result)
+      decorated = result.children.filter_map do |name, node|
+        [name, node, phase_of(node)] unless node.hidden
+      end
+
+      if decorated.all? { |_name, _node, phase| phase.nil? }
+        rows = decorated.sort_by { |name, _node, _phase| name }
+                        .map { |name, node, _phase| row(result, name, node) }
+        return [[nil, rows]]
+      end
 
-        [label(result, name, node), description(node)]
+      phased, unphased = decorated.partition { |_name, _node, phase| phase }
+      groups = phased.group_by { |_name, _node, phase| phase.last }
+      listing = groups.sort_by { |_label, members| members.map { |_n, _node, phase| phase.first }.min }
+                      .map do |label, members|
+        rows = members.sort_by { |_n, _node, phase| phase.first }
+                      .map { |name, node, _phase| row(result, name, node) }
+        [label, rows]
       end
+      listing << [trailing_group_label, unphased.map { |name, node, _phase| row(result, name, node) }] \
+        unless unphased.empty?
+      listing
+    end
+
+    def row(result, name, node)
+      [label(result, name, node), description(node)]
+    end
+
+    def phase_of(node)
+      node.command.respond_to?(:phase) ? node.command.phase : nil
+    end
+
+    # Opportunistic, TOTAL loop-status embed: only the architect binary's ROOT
+    # listing gets it. Resolves the current space best-effort and renders the
+    # shared block from that space's own space.yaml `project` data (no
+    # space_architect dependency). ANY failure — no space, store failure,
+    # malformed yaml, no `project` block — omits the block; help always renders.
+    def loop_status_block(result, pastel)
+      return unless result.names.empty? && File.basename($PROGRAM_NAME) == "architect"
+
+      project = current_space_project
+      lines = project && LoopStatus.lines(project)
+      return if lines.nil? || lines.empty?
+
+      ["", pastel.bold("Loop:"), *lines.map { |l| "  #{pastel.dim(l)}" }].join("\n")
+    rescue StandardError
+      nil
+    end
+
+    def current_space_project
+      store = Space::Core::SpaceStore.new(config: Space::Core::Config.load, state: Space::Core::State.load)
+      store.current.value_or(nil)&.data&.[]("project")
+    rescue StandardError
+      nil
     end
 
     def label(result, name, node)
@@ -109,15 +176,18 @@ module Space::Core::CLI
 end
 
 # Route dry-cli's plain namespace/root listing through our colourful renderer.
-# We replace Usage.call wholesale and depend only on the LookupResult/Node API
-# (children, command, leaf?/children?/hidden, names) rather than copying Usage's
-# internals — see notes/ruby-cli-gems-report.md.
+# We prepend over Usage.call wholesale and depend only on the LookupResult/Node
+# API (children, command, leaf?/children?/hidden, names) rather than copying
+# Usage's internals — see notes/ruby-cli-gems-report.md.
 module Dry
   class CLI
     module Usage
-      def self.call(result)
-        Space::Core::CLI::Help.call(result)
+      module ColourPatch
+        def call(result)
+          Space::Core::CLI::Help.call(result)
+        end
       end
+      singleton_class.prepend(ColourPatch)
     end
   end
 end

data/lib/space_core/cli/loop_status.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+  # Compact Architect-Loop status block, derived from a space's own `project`
+  # block in space.yaml — so this carries NO dependency on space_architect. It
+  # is shared by the `architect --help` embed and the `space status` report.
+  # Returns plain lines (callers colourise) and never raises on malformed data.
+  module LoopStatus
+    module_function
+
+    # Lines for the compact block, or nil when there is no `project` block.
+    def lines(project)
+      return nil unless project.is_a?(Hash) && !project.empty?
+
+      rows = ["Project status:  #{project["status"] || "(none)"}"]
+      iter = current_iteration(project)
+      rows << "Iteration:       #{ordinal(iter)} #{iter["name"]} — #{state_of(iter)}" if iter
+      rows
+    end
+
+    def current_iteration(project)
+      name = project["current_iteration"]
+      return nil unless name
+
+      Array(project["iterations"]).find { |s| s["name"] == name }
+    end
+
+    def ordinal(iter)
+      iter["ordinal"] ? format("I%02d", iter["ordinal"]) : "I--"
+    end
+
+    # Derived loop state for the current iteration. Mirrors the precedence in
+    # `architect status`: a decided verdict wins, then an integrated lane
+    # (awaiting-verdict), then dispatched lanes, then a bare freeze, else spec.
+    def state_of(iter)
+      verdict = iter["verdict"]
+      return verdict if verdict && verdict != "pending"
+
+      lanes = Array(iter["lanes"])
+      return "awaiting-verdict" if lanes.any? { |l| l["integration_branch"] }
+      return "dispatched" if lanes.any?
+      return "frozen #{iter["freeze_sha"][0, 8]}" if iter["freeze_sha"]
+
+      "speccing"
+    end
+  end
+end

data/lib/space_core/cli/repeatable_options.rb

@@ -6,7 +6,7 @@ require "dry/cli"
 # on each occurrence, so `-r a -r b` yields ["b"]. We want repeated flags to
 # accumulate (`-r a -r b -r c` => ["a", "b", "c"]) the way git/docker-style CLIs
 # do, while still accepting the comma form. dry-cli exposes no hook for this, so
-# we reopen two private seams, each mirroring dry-cli 1.4.1 with a single change:
+# we prepend two private seams, each mirroring dry-cli 1.4.1 with a single change:
 #
 #   * Parser.call                  — concat instead of assign for array options.
 #   * Banner.extended_command_options — drop the "=VALUE1,VALUE2,.." hint that
@@ -14,62 +14,71 @@ require "dry/cli"
 #     matching how you actually type it (-r VALUE).
 #
 # These mirror the released 1.4.1 source EXACTLY (not the dry-rb main branch,
-# which already differs). Pinned via `~> 1.4`; if a future dry-cli reworks these
-# methods, repeatable_options_test goes red and we re-sync. Rationale:
-# notes/ruby-cli-gems-report.md.
+# which already differs), prepended onto the module's singleton class so `super`
+# reaches dry-cli's own implementation instead of discarding it outright. Pinned
+# via `~> 1.4`; if a future dry-cli reworks these methods, repeatable_options_test
+# goes red and we re-sync. Rationale: notes/ruby-cli-gems-report.md.
 module Dry
   class CLI
     module Parser
-      def self.call(command, arguments, prog_name)
-        original_arguments = arguments.dup
-        parsed_options = {}
+      # Reopened on Parser's own nesting (not CLI's) so `Result` resolves
+      # lexically, exactly as it does in dry-cli's own `Parser.call`.
+      module RepeatableOptionsPatch
+        def call(command, arguments, prog_name)
+          original_arguments = arguments.dup
+          parsed_options = {}
 
-        OptionParser.new do |opts|
-          command.options.each do |option|
-            opts.on(*option.parser_options) do |value|
-              if option.array?
-                (parsed_options[option.name.to_sym] ||= []).concat(value)
-              else
-                parsed_options[option.name.to_sym] = value
+          OptionParser.new do |opts|
+            command.options.each do |option|
+              opts.on(*option.parser_options) do |value|
+                if option.array?
+                  (parsed_options[option.name.to_sym] ||= []).concat(value)
+                else
+                  parsed_options[option.name.to_sym] = value
+                end
               end
             end
-          end
 
-          opts.on_tail("-h", "--help") do
-            return Result.help
-          end
-        end.parse!(arguments)
+            opts.on_tail("-h", "--help") do
+              return Result.help
+            end
+          end.parse!(arguments)
 
-        parsed_options = command.default_params.merge(parsed_options)
-        parse_required_params(command, arguments, prog_name, parsed_options)
-      rescue ::OptionParser::ParseError, ValueError
-        Result.failure("ERROR: \"#{prog_name}\" was called with arguments \"#{original_arguments.join(" ")}\"")
+          parsed_options = command.default_params.merge(parsed_options)
+          parse_required_params(command, arguments, prog_name, parsed_options)
+        rescue ::OptionParser::ParseError, ValueError
+          Result.failure("ERROR: \"#{prog_name}\" was called with arguments \"#{original_arguments.join(" ")}\"")
+        end
       end
+      singleton_class.prepend(RepeatableOptionsPatch)
     end
 
     module Banner
-      def self.extended_command_options(command)
-        result = command.options.map do |option|
-          name = Inflector.dasherize(option.name)
-          name = if option.boolean?
-                   "[no-]#{name}"
-                 elsif option.flag?
-                   name
-                 else
-                   # array options included: repeated flags accumulate, so show
-                   # the single repeatable form rather than "=VALUE1,VALUE2,..".
-                   "#{name}=VALUE"
-                 end
-          name = "#{name}, #{option.alias_names.join(", ")}" if option.aliases.any?
-          name = "  --#{name.ljust(30)}"
-          name = "#{name}  # #{option.desc}"
-          name = "#{name}, default: #{option.default.inspect}" unless option.default.nil?
-          name
-        end
+      module RepeatableOptionsPatch
+        def extended_command_options(command)
+          result = command.options.map do |option|
+            name = Inflector.dasherize(option.name)
+            name = if option.boolean?
+                     "[no-]#{name}"
+                   elsif option.flag?
+                     name
+                   else
+                     # array options included: repeated flags accumulate, so show
+                     # the single repeatable form rather than "=VALUE1,VALUE2,..".
+                     "#{name}=VALUE"
+                   end
+            name = "#{name}, #{option.alias_names.join(", ")}" if option.aliases.any?
+            name = "  --#{name.ljust(30)}"
+            name = "#{name}  # #{option.desc}"
+            name = "#{name}, default: #{option.default.inspect}" unless option.default.nil?
+            name
+          end
 
-        result << "  --#{"help, -h".ljust(30)}  # Print this help"
-        result.join("\n")
+          result << "  --#{"help, -h".ljust(30)}  # Print this help"
+          result.join("\n")
+        end
       end
+      singleton_class.prepend(RepeatableOptionsPatch)
     end
   end
 end

data/lib/space_core/cli/status.rb

@@ -5,28 +5,69 @@ class Status < BaseCommand
   desc "Set a space status: active, paused, done, archived"
   argument :rest, type: :array, required: false, desc: "[SPACE] STATUS"
 
+  # One command, overloaded by its positional(s):
+  #   help token (`help`, or dry-cli's -h/--help which never reach here) → help
+  #   lone keyword / `<space> <keyword>`                                 → set
+  #   bare, or a lone non-keyword identifier                            → report
   def call(rest: [], **opts)
     setup_terminal(**opts.slice(:color, :colors))
+    args = Array(rest)
+    return show_help if help_token?(args)
+
     handle_errors do
-      identifier, status_value = parse_status_args(Array(rest))
-      render(store.find(identifier)) do |space|
-        space.update_status(status_value)
-        terminal.success "#{space.id} is #{space.status}"
-        CLI.record_outcome(Outcome.new(exit_code: 0))
+      if set_args?(args)
+        set_status(args)
+      elsif args.length <= 1
+        report(args.first)
+      else
+        raise Space::Core::Error, "Usage: space status [SPACE] STATUS"
       end
     end
   end
 
   private
 
-  def parse_status_args(args)
-    case args.length
-    when 1
-      [nil, args.first]
-    when 2
-      args
-    else
-      raise Space::Core::Error, "Usage: space status [SPACE] STATUS"
+  # The bare word `help` shows the command help, like dry-cli's -h/--help (which
+  # it intercepts before dispatch). It must never set status to "help" or report.
+  def help_token?(args)
+    args == ["help"]
+  end
+
+  def show_help
+    out.puts Dry::CLI::Banner.call(self.class, Dry::CLI::ProgramName.call(["status"]))
+    CLI.record_outcome(Outcome.new(exit_code: 0))
+  end
+
+  # A set request: `<space> <keyword>` (two args), or a lone status keyword. A
+  # lone non-keyword arg is a space identifier to REPORT, not a malformed status.
+  def set_args?(args)
+    args.length == 2 ||
+      (args.length == 1 && Space::Core::Space::VALID_STATUSES.include?(args.first))
+  end
+
+  def set_status(args)
+    identifier, status_value = args.length == 2 ? args : [nil, args.first]
+    render(store.find(identifier)) do |space|
+      space.update_status(status_value)
+      terminal.success "#{space.id} is #{space.status}"
+      CLI.record_outcome(Outcome.new(exit_code: 0))
+    end
+  end
+
+  def report(identifier)
+    render(store.find(identifier)) do |space|
+      terminal.say "ID:         #{space.id}"
+      terminal.say "Title:      #{space.title}"
+      terminal.say "Status:     #{space.status}"
+      terminal.say "Path:       #{terminal.path(space.path)}"
+      terminal.say "Created:    #{space.data['created_at']}"
+      terminal.say "Updated:    #{space.data['updated_at']}"
+      lines = LoopStatus.lines(space.data["project"])
+      if lines
+        terminal.say ""
+        lines.each { |line| terminal.say line }
+      end
+      CLI.record_outcome(Outcome.new(exit_code: 0))
     end
   end
 end

data/lib/space_core/shell_integration.rb

@@ -295,7 +295,7 @@ module Space::Core
       complete -c space -f -n "__space_architect_complete_needs_command" -a path -d "Print a space path"
       complete -c space -f -n "__space_architect_complete_needs_command" -a use -d "Select and cd to a space with fish integration"
       complete -c space -f -n "__space_architect_complete_needs_command" -a current -d "Show the current space"
-      complete -c space -f -n "__space_architect_complete_needs_command" -a status -d "Set a space status"
+      complete -c space -f -n "__space_architect_complete_needs_command" -a status -d "Report or set a space status"
       complete -c space -f -n "__space_architect_complete_needs_command" -a config -d "Show or update config"
       complete -c space -f -n "__space_architect_complete_needs_command" -a repo -d "Manage repos in the current space"
       complete -c space -f -n "__space_architect_complete_needs_command" -a repos -d "Manage repos in the current space"

data/lib/space_core/space.rb

@@ -9,6 +9,11 @@ module Space::Core
     METADATA_FILE = "space.yaml"
     VALID_STATUSES = %w[active paused done archived].freeze
 
+    # Canonical space.yaml shape: registry under `project:` (renamed from the
+    # pre-2.0 `architect:` key). Bumped from 1 in the release that did the
+    # rename, since that release shipped no read-side alias for it.
+    SCHEMA_VERSION = 2
+
     attr_reader :path, :data
 
     def self.load(path)
@@ -18,13 +23,58 @@ module Space::Core
       parsed = YAML.safe_load(metadata_path.read, aliases: false) || {}
       raise Error, "Space metadata must contain a YAML mapping: #{metadata_path}" unless parsed.is_a?(Hash)
 
-      new(Pathname.new(path), stringify_keys(parsed))
+      data = stringify_keys(parsed)
+      normalize_schema!(data, metadata_path)
+      new(Pathname.new(path), data)
     end
 
     def self.stringify_keys(hash)
       hash.each_with_object({}) { |(key, value), result| result[key.to_s] = value }
     end
 
+    # Normalizes a parsed space.yaml hash to canonical schema v2, in place:
+    #   - future version (> SCHEMA_VERSION) → raise, refuse to misread it.
+    #   - `architect:` only (v1a) → becomes `project:`.
+    #   - `project:` only (v1b or v2) → left as-is.
+    #   - both present, `project:` empty and `architect:` non-empty → the
+    #     corruption from the old silent-default read path; take `architect:`.
+    #   - both present and non-empty: identical → keep; differing → raise
+    #     rather than silently pick one and lose data.
+    # Idempotent, so a canonical v2 space is a no-op through this method.
+    def self.normalize_schema!(data, metadata_path)
+      version = data["version"]
+      if version.is_a?(Integer) && version > SCHEMA_VERSION
+        raise Error,
+          "space.yaml schema version #{version} is newer than this gem supports " \
+          "(#{SCHEMA_VERSION}); upgrade space-architect: #{metadata_path}"
+      end
+
+      legacy = data.delete("architect")
+      current = data["project"]
+
+      data["project"] =
+        if legacy.nil?
+          current
+        elsif current.nil? || empty_project_block?(current)
+          legacy
+        elsif legacy == current
+          current
+        else
+          raise Error,
+            "#{metadata_path} has both 'architect:' and 'project:' blocks with " \
+            "conflicting content; resolve manually.\narchitect: #{legacy.inspect}\n" \
+            "project: #{current.inspect}"
+        end
+
+      data["version"] = SCHEMA_VERSION
+    end
+    private_class_method :normalize_schema!
+
+    def self.empty_project_block?(block)
+      block.is_a?(Hash) && Array(block["iterations"]).empty? && block["current_iteration"].nil?
+    end
+    private_class_method :empty_project_block?
+
     def initialize(path, data)
       @path = Pathname.new(path)
       @data = data

data/lib/space_core/space_store.rb

@@ -232,7 +232,7 @@ module Space::Core
     def metadata_for(id:, title:, timestamp:)
       iso_timestamp = timestamp.iso8601
       {
-        "version" => 1,
+        "version" => 2,
         "id" => id,
         "title" => title,
         "status" => "active",

data/lib/space_core/version.rb

@@ -2,6 +2,6 @@
 
 module Space
   module Core
-    VERSION = "3.0.0"
+    VERSION = "4.0.0"
   end
 end