space-architect 2.0.2 → 4.0.0

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Space::Core
+  module Commands
+    module_function
+
+    # Render a multi-flag command with trailing " \" continuations broken at
+    # "--flag" boundaries, continuation lines indented two spaces. Commands
+    # without "--" flags are returned unchanged.
+    def wrap(command)
+      parts = command.split(/(?= --)/)
+      return command if parts.size <= 1
+
+      parts.each_with_index.map do |part, i|
+        segment = i.zero? ? part.rstrip : "  #{part.lstrip}"
+        i < parts.size - 1 ? "#{segment} \\" : segment
+      end.join("\n")
+    end
+  end
+end

data/lib/space_core/paths.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Space::Core
+  module Paths
+    module_function
+
+    def contract(path, env: ENV)
+      value = path.to_s
+      home  = XDG.home(env: env)
+      [home, realpath_or_nil(home)].compact.uniq.each do |h|
+        return "~"  if value == h
+        return "~#{value.delete_prefix(h)}" if value.start_with?("#{h}/")
+      end
+      value
+    end
+
+    def realpath_or_nil(path)
+      File.realpath(path)
+    rescue SystemCallError
+      nil
+    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/terminal.rb

@@ -48,13 +48,7 @@ module Space::Core
     end
 
     def path(path)
-      value = path.to_s
-      homes.each do |home|
-        return "~" if value == home
-        return "~#{value.delete_prefix(home)}" if value.start_with?("#{home}/")
-      end
-
-      value
+      Paths.contract(path, env: config.env)
     end
 
     def with_spinner(message)
@@ -108,17 +102,6 @@ module Space::Core
       end
     end
 
-    def homes
-      home = XDG.home(env: config.env)
-      [home, realpath_or_nil(home)].compact.uniq
-    end
-
-    def realpath_or_nil(path)
-      File.realpath(path)
-    rescue SystemCallError
-      nil
-    end
-
     def table_row(headers, row, column_widths, header: false)
       row.each_with_index.map do |cell, index|
         raw = cell.to_s

data/lib/space_core/version.rb

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

data/lib/space_core.rb

@@ -10,6 +10,8 @@ require "space_core/warnings"
 Space::Core::Warnings.disable_experimental!
 require "space_core/atomic_write"
 require "space_core/xdg"
+require "space_core/paths"
+require "space_core/commands"
 require "space_core/config"
 require "space_core/state"
 require "space_core/slugger"

data/lib/space_src/cli/clone.rb

@@ -2,7 +2,6 @@
 
 require "pastel"
 require "dry/monads"
-require "space_src/cli"
 require "space_src/cli/options"
 require "space_src/cloner"
 

data/lib/space_src/cli/config.rb

@@ -2,7 +2,6 @@
 
 require "pastel"
 require "yaml"
-require "space_src/cli"
 require "space_src/ui/mode"
 require "space_src/cli/options"
 

data/lib/space_src/cli/daemon.rb

@@ -3,7 +3,6 @@
 require "pastel"
 require "fileutils"
 require "dry/monads"
-require "space_src/cli"
 require "space_src/ui/mode"
 require "space_src/cli/options"
 require "space_src/launchd/agent"

data/lib/space_src/cli/org.rb

@@ -2,7 +2,6 @@
 
 require "pastel"
 require "dry/monads"
-require "space_src/cli"
 require "space_src/ui/mode"
 require "space_src/cli/options"
 

data/lib/space_src/cli/repo.rb

@@ -2,7 +2,6 @@
 
 require "pastel"
 require "dry/monads"
-require "space_src/cli"
 require "space_src/ui/mode"
 require "space_src/cli/options"
 

data/lib/space_src/cli/shell.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "space_src/cli"
 require "space_src/shell_integration"
 
 module Space::Src

data/lib/space_src/cli/status.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "pastel"
-require "space_src/cli"
 require "space_src/ui/mode"
 require "space_src/cli/options"
 

data/lib/space_src/cli/sync.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "dry/monads"
-require "space_src/cli"
 require "space_src/cli/repo"  # for Repo::Helpers.parse_ref
 require "space_src/cli/options"
 require "space_src/ui/mode"

data/lib/space_src/cli.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "dry/cli"
-require "space_src"
 require "space_src/migration"
 
 module Space::Src

data/skill/architect/SKILL.md

@@ -110,6 +110,7 @@ loop.
 8. **Stop conditions:** failing verification you can't root-cause, instructions
    conflicting with project docs, irreversible/destructive calls, or scope
    growth beyond the iteration → checkpoint to the handoff and ask the human.
+   For bugs in the architect tooling or process itself, run `architect bug-report` — it prints a prefilled issue template and the `gh` command to file it.
 
 ## Procedure
 
@@ -120,8 +121,11 @@ loop.
   gate (test/lint/typecheck/build commands) from docs or CI config.
 - Once per environment: `claude --version` and confirm the builder model
   resolves (`echo ok | claude -p --model <builder-model> --max-turns 1`;
-  details in `dispatch.md`). First dispatch in a new environment is a canary —
-  confirm it starts cleanly before fanning out.
+  details in `dispatch.md`). Past that one-time check, every foreground dispatch
+  self-verifies — it prints a liveness line naming the streamed model and
+  confirming the run log is growing (a WARN line instead if the streamed model
+  disagrees with the pin or the log isn't growing) — so no lone lane needs
+  launching-and-watching before the fan-out.
 - Read `architecture/ARCHITECT.md` (the cross-iteration table of contents),
   `architecture/BRIEF.md` if present (the durable §-numbered project contract you
   cite as BRIEF §N), and the iteration file `architecture/I<NN>-<name>.md` for any
@@ -244,9 +248,17 @@ contract, self-contained:
   task.
 - **Lane plan** — split the iteration into 1–4 parallel lanes, each declaring
   its **target repo + file-touch set, checked for overlap**: name the repo
-  (`repos/<repo>`) and every file each lane may touch. Lanes in *different*
-  repos are inherently disjoint; same-repo lanes with any file overlap run as
-  one. Each lane gets its own objective, output format, and boundaries. Most
+  (`repos/<repo>`) and every file each lane may touch. The machine-readable
+  declaration lives in a fenced ` ```lanes ` block in the Specification — one
+  entry per lane (`name`, `repo`, `touch` globs) — the single frozen source of
+  truth `architect freeze` records into `space.yaml` and `architect provision`
+  materializes. The touch-set now lives *with* the frozen spec by design: it
+  closes the drift where a `worktree add --touch` flag could diverge from the
+  spec's intent. The scaffold ships a commented ` ```lanes ` stub in the
+  Specification (see `templates/iteration.md.erb`) — uncomment it. Lanes in
+  *different* repos are inherently disjoint; same-repo lanes with any file
+  overlap run as one. Each lane gets its own objective, output format, and
+  boundaries. Most
   iterations are one lane — fan out only when the work is genuinely parallel (a
   cross-repo project often is). Two first-class patterns — runnable recipes in `dispatch.md`: **parallel +
   fast-follow** (disjoint lanes integrate first; a fast-follow lane off
@@ -292,13 +304,24 @@ once a frozen section changed afterward.
 
 ### 5. Dispatch (one fresh `claude -p` per lane, worktree-isolated)
 
-Per the mechanics in `dispatch.md`:
-
-- **1 lane** → dispatch in the target repo's checkout (`repos/<repo>`).
-- **2–4 lanes** → `architect worktree add <repo> <iteration> <lane>
-  [--base <repo-base>]` per lane (creates `build/<id>-<lane>/wt` off the target
-  repo's base commit — a repo commit, distinct from the freeze, which is a
-  space commit — and records it in `space.yaml`).
+Per the mechanics in `dispatch.md`. The lane lifecycle is **declare → freeze →
+provision → write prompts → dispatch** — every lane gets a worktree; there is no
+dispatch-in-the-checkout path:
+
+- **Declare** — at spec time, each lane is one entry in the Specification's
+  fenced ` ```lanes ` block (§4): `name`, `repo`, `touch` globs.
+- **Freeze** — `architect freeze` parses that block and records each lane
+  (name, repo, touch_set) into `space.yaml`.
+- **Provision** — `architect provision <iteration>` materializes every declared
+  lane's worktree + `lane/<id>-<lane>` branch in one shot, each off the resolved
+  base (`--base` override, else `project/<slug>` when it exists, else the repo's
+  default branch — a repo commit, distinct from the freeze, which is a space
+  commit) and recorded in `space.yaml`; it is idempotent, and `--lane <name>`
+  provisions a single lane. The manual `architect worktree add` it wraps stays
+  registered as an internal primitive for edge cases — not a step you run.
+- `dispatch`, `integrate`, and `gate` auto-materialize a lane whose worktree is
+  missing from its frozen declaration, so a lane you didn't pre-provision can't
+  dead-end the flow.
 
 Assemble each lane's lane-prompt (the template in `dispatch.md` + this lane's
 section of the Specification + the frozen Acceptance Criteria) and write it to
@@ -362,9 +385,9 @@ it (never hand-resolve). A cross-repo project yields one `project/<slug>` branch
 per touched repo. `main` is never touched per-iteration — `--teardown` deletes
 only the per-lane `lane/<iteration>-<lane>` branches and worktrees, never the
 project branch. Update the iteration index in `architecture/ARCHITECT.md`
-(recording the `project/<slug>` branch), remove the worktrees (`architect
-integrate … --teardown`, or `architect worktree remove <iteration> <lane>`), and
-commit the space.
+(recording the `project/<slug>` branch), remove the provisioned worktrees
+(`architect integrate … --teardown`, or `architect worktree remove <iteration>
+<lane>`), and commit the space.
 
 **Run the frozen gates cold** — `architect gate <iteration>` runs the frozen
 gate commands against the integration tree and streams raw output (a runner, not
@@ -373,10 +396,15 @@ cited BRIEF §sections (per §2), then write the **Verdict** (`architect verdict
 <iteration> continue|kill --from <file>`): disagreement rulings, per-AC
 PASS/FAIL/INVALID, the KILL/CONTINUE call.
 
-At project end, `architect land` prints the single `gh pr create --base main
---head project/<slug>` command per touched repo and writes a PR body to
-`build/land/` — no push, no `gh` call; the human runs it from the repo when
-the project is ready to ship.
+At project end, landing is yours, not the CLI's — the PR body is judgment
+output, the same class as a Verdict. Per touched repo: write the PR body
+yourself — from the iteration verdicts, the integrated diff, and the BRIEF —
+to `build/land/<repo>-pr-body.md`, then present the paste-and-run block to the
+human: `cd` to the repo checkout, `git push -u origin project/<slug>`, and
+`gh pr create --base main --head project/<slug> --title … --body-file …` —
+paths `~`-contracted, the multi-flag command broken with trailing ` \` at flag
+boundaries. No push, no `gh` call by you or the CLI; the human runs the block
+when the project is ready to ship.
 
 ## Maintenance