space-architect 4.0.0 → 5.1.0

data/lib/space_architect/cli/architect.rb

@@ -15,6 +15,36 @@ module Space::Architect
 
         @phase = [order, label]
       end
+
+      # Declares -m/--message and --message-from on a committing command. Every
+      # loop command that commits takes both: the space's git log is the loop's
+      # durable memory, so detailed messages are encouraged everywhere.
+      def self.commit_message_options
+        option :message, aliases: ["-m"], default: nil,
+          desc: "Commit message: first line completes the subject after the canonical prefix, the rest becomes the body"
+        option :message_from, default: nil,
+          desc: "Read the commit message from this file (subject line + detailed body)"
+      end
+
+      private
+
+      # Authored-content intake shared by section/verdict/brief: a file, an
+      # inline flag, or stdin — canonical files are only ever written by the CLI.
+      def read_body(from: nil, body: nil, stdin: false, what: "section body")
+        return File.read(from) if from
+        return body if body
+        return $stdin.read if stdin
+
+        raise Space::Core::Error, "provide the #{what} via --from <file>, --body <text>, or --stdin"
+      end
+
+      # Commit-message intake for commit_message_options: --message-from wins
+      # over -m/--message; nil means the command's canonical default message.
+      def read_commit_message(message: nil, message_from: nil)
+        return File.read(message_from) if message_from
+
+        message
+      end
     end
 
     module Architect
@@ -22,13 +52,14 @@ module Space::Architect
         desc "Scaffold (or top up) the architect project: ARCHITECT.md, space.yaml project block, SessionStart hook"
         phase 50, "Project"
         argument :space, required: false, desc: "Space identifier (default: $PWD)"
+        commit_message_options
 
-        def call(space: nil, **opts)
+        def call(space: nil, message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              path = project.init!
+              path = project.init!(message: read_commit_message(message: message, message_from: message_from))
               terminal.say "Project ready: #{terminal.path(path)}"
               CLI.record_outcome(Outcome.new(exit_code: 0))
             end
@@ -74,13 +105,15 @@ module Space::Architect
         phase 10, "Spec"
         argument :iteration, required: true,  desc: "Iteration name (kebab-case)"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
+        commit_message_options
 
-        def call(iteration:, space: nil, **opts)
+        def call(iteration:, space: nil, message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              path = project.new_iteration!(iteration)
+              path = project.new_iteration!(iteration,
+                message: read_commit_message(message: message, message_from: message_from))
               terminal.say "Iteration scaffolded: #{terminal.path(path)}"
               CLI.record_outcome(Outcome.new(exit_code: 0))
             end
@@ -141,19 +174,41 @@ module Space::Architect
         end
       end
 
+      class Sync < BaseCommand
+        desc "Sync tracked repo clones with their remotes (fast-forward only, no rebase/reset)"
+        phase 53, "Project"
+        argument :repo,  required: false, desc: "Repo name to sync (default: all tracked repos)"
+        argument :space, required: false, desc: "Space identifier (default: $PWD)"
+
+        def call(repo: nil, space: nil, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            render(store.find(space)) do |sp|
+              project = ArchitectProject.new(space: sp)
+              results = project.sync_repos(repo_name: repo)
+              results.each { |r| terminal.say r[:message] }
+              CLI.record_outcome(Outcome.new(exit_code: 0))
+            end
+          end
+        end
+      end
+
       class Freeze < BaseCommand
         desc "Freeze the iteration's frozen region (Grounds/Specification/Acceptance Criteria) and record the freeze SHA"
         phase 12, "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)"
+        commit_message_options
 
-        def call(iteration:, space: nil, **opts)
+        def call(iteration:, space: nil, message: nil, message_from: nil, force: false, **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)
+              sha = project.freeze!(iteration, warnings: warnings, force: force,
+                message: read_commit_message(message: message, message_from: message_from))
               terminal.say "Frozen #{iteration} at #{sha}"
               warnings.each { |w| terminal.say "Warning: #{w}" }
               ac = project.acceptance_criteria(iteration)
@@ -171,15 +226,17 @@ module Space::Architect
       class Verify < BaseCommand
         desc "Post-flight mechanical lane checks — frozen-untouched, no builder commits, report exists, in-bounds (reports only, no judgment)"
         phase 30, "Judge"
-        argument :iteration, required: true, desc: "Iteration name"
-        argument :space,     required: false, desc: "Space identifier (default: $PWD)"
+        argument :iteration,   required: true,  desc: "Iteration name"
+        argument :space,       required: false, desc: "Space identifier (default: $PWD)"
+        option   :commit_mode, default: nil,    desc: "Commit mode override (strict|conductor); overrides space.yaml commit_mode for this run"
 
-        def call(iteration:, space: nil, **opts)
+        def call(iteration:, space: nil, commit_mode: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              results = project.verify(iteration)
+              terminal.say "Effective commit_mode: #{commit_mode}" if commit_mode
+              results = project.verify(iteration, commit_mode: commit_mode)
 
               if results.empty?
                 terminal.say "No lanes recorded for iteration '#{iteration}'"
@@ -222,6 +279,7 @@ module Space::Architect
         argument :iteration, required: true,  desc: "Iteration name"
         argument :lane,      required: true,  desc: "Lane name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
+        option   :prompt,    default: nil,    desc: "Read the lane prompt from this file (copied byte-for-byte to build/<id>-<lane>/prompt.md)"
         option   :model,     default: nil,    desc: "Builder model to pin (default: the lane's model, else the reference default claude-sonnet-4-6). Any provider/tier; pin a full id, not a floating alias"
         option   :max_turns, default: "200",  desc: "Max turns for the builder"
         option   :harness,   default: nil,    desc: "Harness override (claude-code, opencode)"
@@ -232,7 +290,7 @@ module Space::Architect
         option   :push_token, default: nil,   desc: "Bearer token for push endpoint authorization"
         option   :push_host,  default: nil,   desc: "Base URL of the ingest server; the CLI creates a run via POST <host>/runs and streams to /runs/<id>/ingest (requires --push-token)"
 
-        def call(iteration:, lane:, space: nil, model: nil,
+        def call(iteration:, lane:, space: nil, prompt: nil, model: nil,
                  max_turns: "200", harness: nil, effort: nil, detach: false,
                  timeout: "14400", push_url: nil, push_token: nil, push_host: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
@@ -240,6 +298,7 @@ module Space::Architect
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
               kwargs = { max_turns: max_turns.to_i, detach: detach }
+              kwargs[:prompt]     = prompt          if prompt
               kwargs[:model]      = model           if model
               kwargs[:harness]    = harness         if harness
               kwargs[:effort]     = effort          if effort
@@ -248,6 +307,7 @@ module Space::Architect
               kwargs[:push_token] = push_token      if push_token
               kwargs[:push_host]  = push_host       if push_host
               res = project.dispatch(iteration, lane, **kwargs)
+              terminal.say "Prompt:  #{prompt} → #{terminal.path(res[:prompt_copied])}" if res[:prompt_copied]
               if detach
                 terminal.say "PID:     #{res[:pid]}"
                 terminal.say "Run log: #{terminal.path(res[:run_log])}"
@@ -278,13 +338,14 @@ module Space::Architect
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
         option   :base,      default: nil,    desc: "Base ref override (default: project/<slug> HEAD if it exists, else the repo's default branch)"
         option   :lane,      default: nil,    desc: "Provision only this lane (default: all declared lanes)"
+        option   :force,     type: :boolean, default: false, desc: "Clear and re-create a stale (unregistered) worktree directory"
 
-        def call(iteration:, space: nil, base: nil, lane: nil, **opts)
+        def call(iteration:, space: nil, base: nil, lane: nil, force: false, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              results = project.provision(iteration, base: base, lane: lane)
+              results = project.provision(iteration, base: base, lane: lane, force: force)
               if results.empty?
                 terminal.say "No declared lanes to provision for '#{iteration}'"
               else
@@ -303,21 +364,25 @@ module Space::Architect
         desc "Write a section of the iteration file and commit it (one call)"
         phase 11, "Spec"
         argument :iteration, required: true,  desc: "Iteration name"
-        argument :section,   required: true,  desc: "Section: grounds, specification, prompt, verdict"
+        argument :section,   required: true,  desc: "Section: grounds, specification, acceptance-criteria, 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"
+        option   :force,  type: :boolean, default: false, desc: "Write a frozen section (pre-dispatch only)"
+        commit_message_options
 
-        def call(iteration:, section:, space: nil, from: nil, body: nil, stdin: false, append: false, lane: nil, **opts)
+        def call(iteration:, section:, space: nil, from: nil, body: nil, stdin: false, append: false, lane: nil,
+                 message: nil, message_from: nil, force: false, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
-            content = read_section_body(from: from, body: body, stdin: stdin)
+            content = read_body(from: from, body: body, stdin: stdin, what: "section body")
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              res = project.write_section!(iteration, section, body: content, append: append, lane: lane)
+              res = project.write_section!(iteration, section, body: content, append: append, lane: lane, force: force,
+                message: read_commit_message(message: message, message_from: message_from))
               if res[:committed]
                 terminal.say "Committed #{res[:heading]} → #{res[:sha][0, 8]}"
                 terminal.say res[:diffstat] unless res[:diffstat].empty?
@@ -328,15 +393,6 @@ module Space::Architect
             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 Space::Core::Error, "provide the section body via --from <file>, --body <text>, or --stdin"
-        end
       end
 
       class Verdict < BaseCommand
@@ -348,28 +404,22 @@ module Space::Architect
         option   :from,  default: nil,   desc: "Read the verdict body from this file"
         option   :body,  default: nil,   desc: "Inline verdict body"
         option   :stdin, type: :boolean, default: false, desc: "Read the verdict body from stdin"
+        commit_message_options
 
-        def call(iteration:, decision:, space: nil, from: nil, body: nil, stdin: false, **opts)
+        def call(iteration:, decision:, space: nil, from: nil, body: nil, stdin: false,
+                 message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
-            content = read_section_body(from: from, body: body, stdin: stdin)
+            content = read_body(from: from, body: body, stdin: stdin, what: "verdict body")
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              res = project.record_verdict!(iteration, decision: decision, body: content)
+              res = project.record_verdict!(iteration, decision: decision, body: content,
+                message: read_commit_message(message: message, message_from: message_from))
               terminal.say "Verdict '#{res[:decision]}' recorded → #{res[:sha][0, 8]}"
               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 Space::Core::Error, "provide the verdict body via --from <file>, --body <text>, or --stdin"
-        end
       end
 
       class Evidence < BaseCommand
@@ -378,13 +428,15 @@ module Space::Architect
         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)"
+        commit_message_options
 
-        def call(iteration:, space: nil, lane: nil, **opts)
+        def call(iteration:, space: nil, lane: nil, message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              res = project.transcribe_evidence!(iteration, lane: lane)
+              res = project.transcribe_evidence!(iteration, lane: lane,
+                message: read_commit_message(message: message, message_from: message_from))
               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)."
@@ -397,17 +449,20 @@ module Space::Architect
       class Merge < BaseCommand
         desc "Integrate ONE judged-passing lane (merges --no-ff; runs no gates, makes no verdict)"
         phase 41, "Land"
-        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)
+        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   :into,        required: false, desc: "Merge into this branch instead of the slug-derived project/<slug> default"
+        option   :commit_mode, default: nil,    desc: "Commit mode override (strict|conductor); overrides space.yaml commit_mode for this run"
+        commit_message_options
+
+        def call(iteration:, lane:, space: nil, message: nil, message_from: nil, into: nil, commit_mode: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              r = project.merge_lane!(iteration, lane, message: message)
+              r = project.merge_lane!(iteration, lane, into: into, commit_mode: commit_mode,
+                message: read_commit_message(message: message, message_from: message_from))
               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."
@@ -420,12 +475,15 @@ module Space::Architect
       class Integrate < BaseCommand
         desc "Integrate the architect-supplied set of passing lanes, in order (stops on conflict)"
         phase 40, "Land"
-        argument :iteration, required: true,  desc: "Iteration name"
-        argument :space,     required: false, desc: "Space identifier (default: $PWD)"
-        option   :lanes,     required: false, 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: nil, teardown: false, **opts)
+        argument :iteration,   required: true,  desc: "Iteration name"
+        argument :space,       required: false, desc: "Space identifier (default: $PWD)"
+        option   :lanes,       required: false, desc: "Comma-separated passing lane names (you decide the set)"
+        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"
+        commit_message_options
+
+        def call(iteration:, space: nil, lanes: nil, teardown: false, message: nil, message_from: nil, commit_mode: nil, into: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             lane_names = lanes.to_s.split(",").map(&:strip).reject(&:empty?)
@@ -434,7 +492,9 @@ module Space::Architect
 
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
-              results = project.integrate!(iteration, lanes: lane_names, teardown: teardown)
+              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)
               if lane_names.empty?
                 if results.empty?
                   terminal.say "Nothing to tear down for #{iteration}"
@@ -543,15 +603,16 @@ module Space::Architect
           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)"
+          option   :force,     type: :boolean, default: false, desc: "Clear and re-create a stale (unregistered) worktree directory"
 
-          def call(repo:, iteration:, lane:, base: nil, harness: "claude-code", model: nil, effort: nil, touch: nil, **opts)
+          def call(repo:, iteration:, lane:, base: nil, harness: "claude-code", model: nil, effort: nil, touch: nil, force: false, **opts)
             setup_terminal(**opts.slice(:color, :colors))
             handle_errors do
               render(store.find) do |sp|
                 project = ArchitectProject.new(space: sp)
                 touch_set = touch ? touch.split(",").map(&:strip).reject(&:empty?) : nil
                 result = project.worktree_add(repo, iteration, lane, base: base,
-                                             harness: harness, model: model, effort: effort, touch: touch_set)
+                                             harness: harness, model: model, effort: effort, touch: touch_set, force: force)
                 terminal.say "Worktree: #{terminal.path(result[:worktree])}"
                 terminal.say "Base SHA: #{result[:base_sha]}"
                 CLI.record_outcome(Outcome.new(exit_code: 0))
@@ -690,17 +751,23 @@ module Space::Architect
 
       module Brief
         class New < BaseCommand
-          desc "Scaffold the durable project brief (architecture/BRIEF.md)"
+          desc "Write the durable project brief (architecture/BRIEF.md) — authored via --from/--stdin, or a placeholder template"
           argument :space, required: false, desc: "Space identifier (default: $PWD)"
           option   :force, type: :boolean, default: false, desc: "Overwrite an existing BRIEF.md"
+          option   :from,  default: nil,   desc: "Read the authored brief body from this file"
+          option   :stdin, type: :boolean, default: false, desc: "Read the authored brief body from stdin"
+          commit_message_options
 
-          def call(space: nil, force: false, **opts)
+          def call(space: nil, force: false, from: nil, stdin: false, message: nil, message_from: nil, **opts)
             setup_terminal(**opts.slice(:color, :colors))
             handle_errors do
+              content = (from || stdin) ? read_body(from: from, stdin: stdin, what: "brief body") : nil
               render(store.find(space)) do |sp|
                 project = ArchitectProject.new(space: sp)
-                path = project.brief_new!(force: force)
-                terminal.say "Brief ready: #{terminal.path(path)}"
+                path = project.brief_new!(force: force, content: content,
+                  message: read_commit_message(message: message, message_from: message_from))
+                note = content ? "" : " (template — Read it before editing)"
+                terminal.say "Brief ready: #{terminal.path(path)}#{note}"
                 CLI.record_outcome(Outcome.new(exit_code: 0))
               end
             end
@@ -719,6 +786,7 @@ Space::Architect::CLI::Registry.register "init",   Space::Architect::CLI::Archit
 Space::Architect::CLI::Registry.register "ground", Space::Architect::CLI::Architect::Ground
 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 "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_core/cli/run.rb

@@ -5,11 +5,12 @@ require_relative "../oci_runner"
 
 module Space::Core::CLI
 class Run < BaseCommand
-  desc "Run the packed OCI image for the current space (auth injected at runtime)"
+  desc "Run the packed OCI image for the current space (auth injected at runtime). Pass a command and its arguments after `--` so they forward as separate argv tokens"
 
-  argument :command, type: :array, required: false, desc: "Command to run in the container (default: login shell)"
+  argument :command, type: :array, required: false, desc: "Command to run in the container (default: login shell). Use `--` to pass a command with arguments, e.g. `space run -- hermes -z \"hello\"`"
   option :tty, type: :boolean, default: nil, desc: "Force interactive TTY (default: auto-detect)"
   option :env, type: :array, desc: "Host env var to forward into the container (repeatable; adds to run.env)"
+  example "-- hermes -z \"What is 17 plus 4?\"   # `--` forwards the command and its args as separate tokens (a quoted multi-word command arrives as one token and fails in-guest)"
 
   def call(command: [], tty: nil, env: [], **opts)
     setup_terminal(**opts.slice(:color, :colors))

data/lib/space_core/version.rb

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

data/skill/architect/SKILL.md

@@ -46,7 +46,20 @@ message, and prints back what changed (SHA + diff stat; `freeze` prints the
 frozen AC; `evidence` echoes the builder's STATUS line) — so you don't hand-edit
 the file or run a separate `git add`/`commit`, and you don't run three follow-ups
 to see what happened. You still author the *content*; the CLI owns the
-*persistence*.
+*persistence*. Two disciplines fall out of that split:
+
+- **Author in fresh files; canonical paths are CLI-owned.** Write your content
+  to a fresh scratch file (timestamp it — `tmp/` in the space) and hand it to
+  the command via `--from`/`--prompt`/`--stdin`. Never `Write`/`Edit` a path you
+  haven't read this session — the pre-existing file trips your harness's
+  read-before-write guard and burns a failed-write → read → rewrite round trip.
+- **Write detailed commit messages.** Every committing command takes
+  `-m`/`--message` and `--message-from <file>`: your first line completes the
+  subject after a short canonical prefix (`I01 spec: <your subject>`), the rest
+  becomes the body. The space's git log is the loop's durable memory — record
+  the *why* (rejected alternatives, BRIEF §refs, judgment reasoning) there, not
+  just in your head. Prefer `--message-from <fresh file>` for multiline bodies
+  (shells mangle quotes).
 
 The builder **never** writes this file — the Acceptance Criteria must stay out
 of its editable blast radius. Each lane builder writes raw evidence to a scratch
@@ -62,7 +75,9 @@ of done) that span iterations. Every iteration's Grounds/Specification/Acceptanc
 Criteria/Verdict cites it as **BRIEF §N** (e.g. `(BRIEF §3.1)`), the way each gate
 addresses its intent back to one frozen reference: the Acceptance Criteria table
 carries a `Brief §` column, the Specification Objective cites it, the Verdict
-reads "diff vs BRIEF §1/§3.3 — CONTINUE". Scaffold it with `architect brief new`.
+reads "diff vs BRIEF §1/§3.3 — CONTINUE". Author it in a fresh scratch file and
+persist with `architect brief new --from <file>` (bare `architect brief new`
+drops a placeholder template for a human to fill).
 The brief is frozen at the project level — edits to a §section are logged
 decisions in `ARCHITECT.md`, never silent per-iteration drift. Discovery projects
 that are still finding their shape defer the brief, cite per-iteration Grounds,
@@ -325,10 +340,14 @@ dispatch-in-the-checkout path:
 
 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
-`build/<id>-<lane>/prompt.md` (fed to the builder on stdin); record it in the
+a **fresh timestamped scratch file**, `tmp/prompts/<id>-<lane>-<hhmmss>.md` —
+never to `build/<id>-<lane>/prompt.md` directly (a pre-existing canonical file
+trips your harness's read-before-write guard). Record it in the
 iteration file's **Builder Prompt** section — the dispatched-prompt provenance —
 with `architect section <iteration> prompt --append --lane <lane> --from
-build/<id>-<lane>/prompt.md`. Then run `architect dispatch <iteration> <lane>` — it assembles the
+<that scratch file>`. Then run `architect dispatch <iteration> <lane> --prompt
+<that scratch file>` — it copies the prompt to the canonical
+`build/<id>-<lane>/prompt.md` (fed to the builder on stdin), assembles the
 canonical `claude -p` argv, pins the model, and streams stream-json to
 `build/<id>-<lane>/run.jsonl`. Launch one dispatch per worktree — each as its
 **own background Bash tool call** (your harness's `run_in_background`), **not**
@@ -399,7 +418,9 @@ PASS/FAIL/INVALID, the KILL/CONTINUE call.
 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
+to a fresh timestamped file `build/land/<repo>-pr-body-<yyyymmdd-hhmm>.md`
+(never rewrite a prior session's body in place — fresh file, fresh Write),
+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

data/skill/architect/dispatch.md

@@ -39,22 +39,27 @@ with the pinned `<builder-model>` or the log isn't growing.
 
 ## Canonical dispatch — `architect dispatch <iteration> <lane>`
 
-The canonical path is `architect dispatch <iteration> <lane>`. The tool
-assembles the canonical `claude -p` argv, pins the builder model (the lane's
+The canonical path is `architect dispatch <iteration> <lane> --prompt <file>`.
+The tool copies your prompt file to `build/<id>-<lane>/prompt.md` (the CLI owns
+that canonical path — you never write it directly), assembles the canonical
+`claude -p` argv, pins the builder model (the lane's
 configured model or the CLI's reference default; see `docs/DESIGN.md` §4),
-reads the lane prompt from `build/<id>-<lane>/prompt.md` on stdin, and streams
+feeds the copied lane prompt to the builder on stdin, and streams
 `--output-format stream-json --verbose` output to
 `build/<id>-<lane>/run.jsonl`. Run each lane as its own **background Bash tool
 call** (`run_in_background`) so your turn doesn't block for the full run (30–60
 minutes is typical).
 
-Write the lane's prompt to `build/<id>-<lane>/prompt.md` first (never pass a
-big prompt as a shell argument — shells mangle quotes), then:
+Author the lane's prompt in a **fresh timestamped scratch file**
+(`tmp/prompts/<id>-<lane>-<hhmmss>.md` — never a pre-existing canonical path,
+which trips your harness's read-before-write guard; never a shell argument —
+shells mangle quotes), then hand it to dispatch:
 
 ```bash
-# single-lane iteration — run from the space root; dispatch runs in the lane's
-# provisioned worktree (materialized on demand from the frozen declaration)
-architect dispatch <iteration> <lane>
+# single-lane iteration — run from the space root; dispatch copies the prompt to
+# build/<id>-<lane>/prompt.md and runs in the lane's provisioned worktree
+# (materialized on demand from the frozen declaration)
+architect dispatch <iteration> <lane> --prompt tmp/prompts/<id>-<lane>-<hhmmss>.md
 ```
 
 For multi-lane iterations, materialize every declared lane in one shot with
@@ -62,8 +67,8 @@ For multi-lane iterations, materialize every declared lane in one shot with
 
 ```bash
 architect provision <iteration>          # all declared lanes: worktree + lane/<id>-<lane> branch
-architect dispatch <iteration> lane-a    # own background Bash call each
-architect dispatch <iteration> lane-b
+architect dispatch <iteration> lane-a --prompt <lane-a scratch file>   # own background Bash call each
+architect dispatch <iteration> lane-b --prompt <lane-b scratch file>
 ```
 
 `architect provision` reads the frozen lane declarations from `space.yaml` and,
@@ -92,7 +97,8 @@ survives the full run and reports completion per lane.
 and as the manual fallback:
 
 ```bash
-# write prompt to build/<id>-<lane>/prompt.md first, then:
+# dispatch --prompt copies the scratch prompt to build/<id>-<lane>/prompt.md; the
+# manual equivalent is that copy followed by:
 ( cd build/<id>-<lane>/wt && \
   claude -p --model <builder-model> \
     --permission-mode acceptEdits \
@@ -123,13 +129,16 @@ architect integrate <iteration> --lanes <passing-set>   # e.g. --lanes lane-a,la
 architect gate <iteration>                              # integration smoke (raw output; verdict stays yours)
 architect integrate <iteration> --lanes <passing-set> --teardown   # or remove worktrees + lane branches after
 # end of project: landing is the architect's, not a CLI command — write the PR
-# body to build/land/<repo>-pr-body.md yourself, then present the paste-and-run
-# block (cd, git push -u origin project/<slug>, gh pr create) — see SKILL.md §6
+# body to a fresh build/land/<repo>-pr-body-<yyyymmdd-hhmm>.md yourself, then
+# present the paste-and-run block (cd, git push -u origin project/<slug>,
+# gh pr create) — see SKILL.md §6
 ```
 
 `architect integrate` commits each named lane on its branch and merges it
 `--no-ff` into the repo's stable `project/<slug>` branch (slug of `space.title`,
-persistent across all iterations), in order. It **refuses** a lane that left
+persistent across all iterations), in order. Pass `-m`/`--message-from` — the
+lane commit lands in the repo's PR history, so say what the lane did and why,
+not just that it integrated. It **refuses** a lane that left
 builder commits or wrote out-of-bounds (the mechanical post-flight checks), and
 aborts on a merge conflict. A merge conflict = the lane plan wasn't disjoint = a
 spec defect: kill the conflicting lane and re-spec; don't hand-resolve builder
@@ -150,8 +159,9 @@ git -C repos/<repo> merge --no-ff lane/<iteration>-<lane>
 <run the gate commands>          # integration smoke after every merge
 architect worktree remove <iteration> <lane>
 git -C repos/<repo> branch -d lane/<iteration>-<lane>
-# at project end there is no CLI step: the architect writes
-# build/land/<repo>-pr-body.md and presents the push + gh pr create block
+# at project end there is no CLI step: the architect writes a fresh
+# build/land/<repo>-pr-body-<yyyymmdd-hhmm>.md and presents the push +
+# gh pr create block
 ```
 
 ### Parallel + fast-follow

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: space-architect
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 5.1.0
 platform: ruby
 authors:
 - Eric Jacobs
@@ -205,6 +205,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: mutant-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement