space-architect 4.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb8f902d475bcc8a29e56740ce0c20328935fe05f9d919d38934b2cffd12e966
-  data.tar.gz: e31c5b6f8ad98219c9c4ed22225666900bc7aaf8f43bd929ef32e2d2b5aacdf2
+  metadata.gz: 6846eab011f92f0b54a7bb886d7b97cf8c727beb3fc6d279a2db603062645520
+  data.tar.gz: 0bc8f0b22f785fd2d3ed77419a1ad3b6058e4b76a6aaee41b7a66793b865702a
 SHA512:
-  metadata.gz: 5cbb47cbacf2231ed09eb74bfb11b80a1a6076bfde1427fe76a19b3581f3b3a8e38db4a6269307e339a022902723d73b1d40dd4b001acd6ffaab624871249d70
-  data.tar.gz: 171913d786d1e166a279f72b184ec7987785d561ec795bfe161db9341502210f6d97166c3eb8b7a097b59adba7e435a575c78ca66488ca482312b4bc7cca7249
+  metadata.gz: 77216fd23779d4ee5ae16f3c141fc9f7670b3efc3c8b7fe31292c31284be0903616505c4199fbe4e5d7b12988d0638e7a31cba600a4625caad2b939255fc9370
+  data.tar.gz: ca1fb9e9bd1c20c6ef201d60f763cdcb87b18b9c289169ff601be6c858b0558f283986b2b24bb82cf73b4b1001c3ce0a9955bd02675557548fcc2e930aea27d2

data/CHANGELOG.md

@@ -5,6 +5,92 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.0] - 2026-07-06
+
+### Added
+
+- **`architect dispatch --prompt <file>`** — the lane prompt is authored anywhere
+  (a fresh scratch file) and dispatch copies it byte-for-byte to the canonical
+  `build/<id>-<lane>/prompt.md` before launch, announcing the copy. The CLI owns
+  the canonical path; the architect never blind-writes it (#48, #42).
+- **`architect brief new --from <file>` / `--stdin`** — write the authored brief
+  in one step instead of filling a pre-seeded template. Bare `brief new` still
+  scaffolds the placeholder, and now says so
+  (`Brief ready: … (template — Read it before editing)`).
+- **Flexible commit messages on every committing loop command** — `init`, `new`,
+  `freeze`, `brief new`, `section`, `verdict`, `evidence`, `merge`, and
+  `integrate` all take `-m`/`--message` and `--message-from <file>`. The first
+  line completes the subject after a short canonical prefix (`I01 spec: <your
+  subject>`, `lane <lane>: <your subject>`); remaining lines become the commit
+  body. Without the flags, the canonical messages are unchanged. The space's git
+  log is the loop's durable memory — detailed bodies are the point.
+
+### Changed
+
+- **`worktree add`/`provision` no longer pre-seed `prompt.md` with a placeholder
+  stub.** The unannounced stub made the architect's first `Write` trip the
+  harness read-before-write guard on every single lane (a failed-write → read →
+  rewrite round trip; 40 occurrences mined from real transcripts). Dispatch
+  still refuses a missing, empty, or legacy-stub prompt (#48, #42).
+- **`architect merge --message` semantics** — the message now composes with the
+  canonical `lane <lane>:` prefix (subject + body) instead of replacing the
+  whole message, matching every other committing command.
+- **Skill prose** — the architect authors all content (lane prompts, brief, PR
+  bodies) in fresh timestamped scratch files and hands them to the CLI via
+  `--from`/`--prompt`; PR bodies land at
+  `build/land/<repo>-pr-body-<yyyymmdd-hhmm>.md`; committing commands should
+  carry detailed `--message-from` bodies.
+
+## [4.0.0] - 2026-07-05
+
+Backfilled — the bump shipped without an entry. Five iterations run through the
+Architect Loop against `space-architect`'s own live-loop papercuts (#46), plus
+the `dispatched_at` producer (#45) and a test-suite hygiene pass (#32).
+
+### Added
+
+- **`architect provision <iteration> [--base <ref>] [--lane <name>]`** — materializes
+  every declared lane's worktree + `lane/<id>-<lane>` branch in one shot from the
+  frozen lane plan (idempotent; base resolves `--base`, else `project/<slug>` HEAD,
+  else the repo's default branch). `dispatch`/`integrate`/`gate`/`verify`
+  auto-materialize a missing worktree from the frozen declaration, so the flow
+  can't dead-end (#26).
+- **Fenced ` ```lanes ` block in the Specification** — `name`, `repo`, `touch`
+  globs, parsed at **freeze** into `space.yaml` lane entries, making the lane plan
+  (including the out-of-bounds touch-set contract) part of the frozen spec (#26).
+- **`space.yaml` schema v2** — the never-bumped `version` key now means something:
+  canonicalize on save, read + self-heal the two known v1 variants (v1a
+  `architect:`, v1b `project:`+`version: 1`) on load; a both-keys conflict refuses
+  and names both blocks rather than silently picking one (#33).
+- **`dispatched_at` on lane entries** — every dispatch stamps an ISO 8601 launch
+  time after preflight, before the run, on both foreground and detached paths
+  (#18, producer landed via #45).
+- **Self-verifying dispatch liveness** — a transient fiber inside dispatch checks
+  the launched run matches intent (model, growth of `run.jsonl`), retiring the
+  manual "canary" ceremony (#43, #44).
+- **`architect help` grouped by loop phase** — Spec / Build / Judge / Land /
+  Project, commands in loop order, with an embedded loop-status block when run
+  inside a project space; `space status` reports on a bare call and still sets on
+  `space status <value>`.
+
+### Changed
+
+- **Lane declaration is single-source-of-truth** — lanes were declared twice
+  (Specification prose + `worktree add` flags) with the touch-set divorced from
+  the frozen spec; the ` ```lanes ` block at freeze is now the one declaration.
+  The single-lane "dispatch in the repo checkout" fast path is removed (it never
+  worked with `merge_lane!`); manual `worktree add` remains as the internal
+  primitive `provision` wraps (#26).
+- **Skill prose** (`SKILL.md` §4–§6, `dispatch.md`) rewritten to the
+  declare → freeze → provision → dispatch lane lifecycle.
+
+### Fixed
+
+- **`architect integrate <it> --teardown`** (no `--lanes`) backtraced; teardown-only
+  mode now deletes per-lane branches and worktrees, never `project/<slug>` or
+  `main` (#30).
+- **Test suite hygiene** — zero warnings, zero stray output, 58.8s → 49.1s (#32).
+
 ## [3.0.0] - 2026-07-01
 
 ### Added

data/README.md

@@ -271,8 +271,12 @@ build/
 ```
 
 **Iteration file anatomy** — one file, grown section by section. You author the
-*content*; the CLI owns the *persistence* (each command writes the section,
-commits it with the canonical message, and prints back what changed):
+*content* in fresh scratch files; the CLI owns the *persistence* (each command
+writes the section, commits it, and prints back what changed). Every committing
+command takes `-m`/`--message` and `--message-from <file>` — your first line
+completes the subject after a short canonical prefix (`I01 spec: <subject>`),
+the rest becomes the body. The space's git log is the loop's durable memory:
+write detailed messages.
 
 | Section | Holds | How you persist it |
 |---------|-------|--------------------|
@@ -299,12 +303,12 @@ inside a lane worktree are never grounded.
 
 ```sh
 architect init                              # scaffold ARCHITECT.md + the space.yaml project: block + SessionStart hook
-architect brief new                         # scaffold the durable project BRIEF.md
+architect brief new --from <f>              # write the durable project BRIEF.md (authored in a scratch file)
 architect new <iteration>                   # scaffold architecture/I<NN>-<iteration>.md
-architect section <it> <section> --from <f> # write + commit a section
+architect section <it> <section> --from <f> # write + commit a section (add -m/--message-from for a detailed commit)
 architect freeze <iteration>                # freeze the Acceptance Criteria ❄️
 architect worktree add <repo> <it> <lane>   # isolated worktree per lane (2–4 lanes)
-architect dispatch <it> <lane>              # dispatch a builder (add --detach to survive long runs)
+architect dispatch <it> <lane> --prompt <f> # copy the lane prompt in + dispatch a builder (--detach to survive long runs)
 architect verify <iteration>                # post-flight mechanical checks (reports only)
 architect evidence <it> --lane <lane>       # transcribe the builder's report verbatim
 architect gate <iteration>                  # run the frozen gate commands, stream raw output
@@ -326,9 +330,9 @@ A typical session:
 ```sh
 architect init                                   # first time
 architect new my-feature                         # scaffold I01-my-feature.md
-architect section my-feature specification --from spec.md
+architect section my-feature specification --from spec.md -m "pull-based dispatcher seam"
 architect freeze my-feature                      # lock it ❄️
-architect dispatch my-feature lane-a --detach    # send a builder; poll the report
+architect dispatch my-feature lane-a --prompt tmp/prompts/I01-lane-a.md --detach   # send a builder; poll the report
 architect verify my-feature                      # mechanical post-flight checks
 architect evidence my-feature --lane lane-a      # transcribe raw evidence
 architect gate my-feature                        # run the frozen gates yourself

data/lib/space_architect/architect_project.rb

@@ -25,10 +25,10 @@ module Space::Architect
     # command (`architect evidence`) because it is transcribed verbatim from scratch.
     # `frozen: true` sections live above the freeze boundary and are refused once frozen.
     SECTIONS = {
-      "grounds" => { heading: "## Grounds", message: "grounds", frozen: true },
-      "specification" => { heading: "## Specification", message: "specification", frozen: true },
-      "prompt" => { heading: "## Builder Prompt", message: "dispatched", frozen: false },
-      "verdict" => { heading: "## Verdict", message: "verdict", frozen: false }
+      "grounds" => { heading: "## Grounds", message: "grounds", prefix: "grounds", frozen: true },
+      "specification" => { heading: "## Specification", message: "specification", prefix: "spec", frozen: true },
+      "prompt" => { heading: "## Builder Prompt", message: "dispatched", prefix: "prompt", frozen: false },
+      "verdict" => { heading: "## Verdict", message: "verdict", prefix: "verdict", frozen: false }
     }.freeze
 
     # The fixed top-level section headings. Section boundaries are detected against
@@ -42,7 +42,10 @@ module Space::Architect
     # Hard per-gate timeout. Generous relative to the full suite (~55s).
     DEFAULT_GATE_TIMEOUT = 900
 
-    # Sentinel written to prompt.md by worktree_add. dispatch refuses to launch on this content.
+    # Legacy sentinel: worktree_add used to seed prompt.md with this placeholder
+    # (dropped — the blind-overwrite tripped harness read-before-write guards, #48).
+    # dispatch still refuses to launch on this content, so stubs in old spaces
+    # can't reach a builder.
     PROMPT_STUB = "<!-- ARCHITECT: write this lane's builder prompt here, then dispatch. -->"
 
     # Inlined settings.json template for `architect init`. Registers a SessionStart
@@ -74,7 +77,7 @@ module Space::Architect
       @space = space
     end
 
-    def init!
+    def init!(message: nil)
       handoff_path = space.path.join("architecture", "ARCHITECT.md")
       settings_path = space.path.join(".claude", "settings.json")
       to_add = []
@@ -97,15 +100,15 @@ module Space::Architect
 
       if to_add.any?
         git_run("-C", space.path.to_s, "add", *to_add)
-        msg = to_add.include?("architecture/ARCHITECT.md") ? "Initialize architect project" : "Add architect settings"
-        git_run("-C", space.path.to_s, "commit", "-m", msg)
+        default = to_add.include?("architecture/ARCHITECT.md") ? "Initialize architect project" : "Add architect settings"
+        git_run("-C", space.path.to_s, "commit", "-m", compose_message("init:", default, message))
       end
 
       handoff_path
     end
 
     # Allocate the next ordinal and scaffold architecture/I<NN>-<iteration>.md.
-    def new_iteration!(name)
+    def new_iteration!(name, message: nil)
       block = space.data["project"] || {}
       iterations = block["iterations"] || []
       if iterations.any? { |s| s["name"] == name }
@@ -133,7 +136,8 @@ module Space::Architect
       end
 
       git_run("-C", space.path.to_s, "add", rel, Space::Core::Space::METADATA_FILE)
-      git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: scaffold #{name}")
+      git_run("-C", space.path.to_s, "commit", "-m",
+        compose_message("I#{nn} scaffold:", "I#{nn}: scaffold #{name}", message))
 
       path
     end
@@ -154,7 +158,7 @@ module Space::Architect
     # Freeze the iteration: the iteration file must carry a "## Acceptance Criteria" section. Commits
     # any pending changes to the iteration file and records HEAD as freeze_sha. If
     # already frozen, refuses when the frozen region has changed since.
-    def freeze!(iteration, warnings: nil)
+    def freeze!(iteration, warnings: nil, message: nil)
       entry = slice_entry(iteration)
       rel = entry["file"]
       path = space.path.join(rel)
@@ -180,7 +184,8 @@ module Space::Architect
       files = [rel]
       files << "architecture/ARCHITECT.md" if space.path.join("architecture", "ARCHITECT.md").exist?
       nn = format("%02d", entry["ordinal"] || 0)
-      git_capture("-C", space.path.to_s, "commit", "-m", "I#{nn}: acceptance criteria (freeze)", "--", *files)
+      git_capture("-C", space.path.to_s, "commit", "-m",
+        compose_message("I#{nn} freeze:", "I#{nn}: acceptance criteria (freeze)", message), "--", *files)
 
       sha, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
       sha = sha.strip
@@ -208,17 +213,20 @@ module Space::Architect
 
     # Scaffold the durable, section-numbered project brief at architecture/BRIEF.md
     # and commit it. The brief is the stable cross-iteration address space iterations
-    # cite as "BRIEF §N"; it lives outside the per-iteration freeze region.
-    def brief_new!(force: false)
+    # cite as "BRIEF §N"; it lives outside the per-iteration freeze region. With
+    # content, writes the authored brief instead of the placeholder template.
+    def brief_new!(force: false, content: nil, message: nil)
       brief_path = space.path.join("architecture", "BRIEF.md")
       if brief_path.exist? && !force
         raise Space::Core::Error, "architecture/BRIEF.md already exists — edit it directly (idempotent guard), or pass --force to overwrite"
       end
 
       FileUtils.mkdir_p(brief_path.dirname)
-      brief_path.write(render_brief)
+      brief_path.write(content || render_brief)
       git_run("-C", space.path.to_s, "add", "architecture/BRIEF.md")
-      git_run("-C", space.path.to_s, "commit", "-m", "Add project brief") if staged_changes?
+      if staged_changes?
+        git_run("-C", space.path.to_s, "commit", "-m", compose_message("brief:", "Add project brief", message))
+      end
       brief_path
     end
 
@@ -226,7 +234,7 @@ module Space::Architect
     # per-section message, in one call. Refuses to write a frozen section
     # (Grounds/Specification) once the iteration is frozen. Acceptance Criteria is
     # NOT writable here (use freeze); Builder Report is not here (use evidence).
-    def write_section!(iteration, section, body:, append: false, lane: nil)
+    def write_section!(iteration, section, body:, append: false, lane: nil, message: nil)
       spec = SECTIONS[section]
       unless spec
         raise Space::Core::Error,
@@ -249,7 +257,8 @@ module Space::Architect
       path.write(replace_section_body(path.read, spec[:heading], block, append: append))
 
       nn = format("%02d", entry["ordinal"] || 0)
-      _o, _e, cst = git_capture("-C", space.path.to_s, "commit", "-m", "I#{nn}: #{spec[:message]}", "--", rel)
+      _o, _e, cst = git_capture("-C", space.path.to_s, "commit", "-m",
+        compose_message("I#{nn} #{spec[:prefix]}:", "I#{nn}: #{spec[:message]}", message), "--", rel)
       committed = cst.success?
       show_out, = git_capture("-C", space.path.to_s, "show", "--stat", "--format=%H", "HEAD")
       show_lines = show_out.to_s.lines
@@ -260,7 +269,7 @@ module Space::Architect
 
     # Write the ## Verdict prose AND record the decision to space.yaml in one commit.
     # decision must be "continue" or "kill".
-    def record_verdict!(iteration, decision:, body:)
+    def record_verdict!(iteration, decision:, body:, message: nil)
       unless %w[continue kill].include?(decision)
         raise Space::Core::Error,
           "Invalid verdict decision '#{decision}' — must be one of: continue, kill"
@@ -279,7 +288,8 @@ module Space::Architect
       end
 
       nn = format("%02d", entry["ordinal"] || 0)
-      git_run("-C", space.path.to_s, "commit", "-m", "I#{nn}: verdict", "--", rel, Space::Core::Space::METADATA_FILE)
+      git_run("-C", space.path.to_s, "commit", "-m",
+        compose_message("I#{nn} verdict:", "I#{nn}: verdict", message), "--", rel, Space::Core::Space::METADATA_FILE)
 
       head, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
       { decision: decision, sha: head.strip }
@@ -287,7 +297,7 @@ module Space::Architect
 
     # Transcribe a lane's scratch report (build/<id>[-<lane>]/report.md) VERBATIM into
     # the Builder Report section and commit. Byte-for-byte: no summarization, no judgment.
-    def transcribe_evidence!(iteration, lane: nil)
+    def transcribe_evidence!(iteration, lane: nil, message: nil)
       entry = slice_entry(iteration)
       rel = entry["file"]
       path = space.path.join(rel)
@@ -303,7 +313,8 @@ module Space::Architect
       path.write(replace_section_body(path.read, "## Builder Report", block, append: !lane.nil?))
 
       nn = format("%02d", entry["ordinal"] || 0)
-      git_capture("-C", space.path.to_s, "commit", "-m", "I#{nn}: evidence", "--", rel)
+      git_capture("-C", space.path.to_s, "commit", "-m",
+        compose_message("I#{nn} evidence:", "I#{nn}: evidence", message), "--", rel)
       head, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
 
       status_line = raw.lines.reverse_each.find { |l| l.strip.start_with?("STATUS:") }&.strip
@@ -358,7 +369,8 @@ module Space::Architect
       raise Space::Core::Error, "Lane '#{lane}' worktree has no changes to integrate." if status_out.strip.empty?
 
       git_run("-C", wt_path.to_s, "add", "-A")
-      git_run("-C", wt_path.to_s, "commit", "-m", message || "lane #{lane}: integrate")
+      git_run("-C", wt_path.to_s, "commit", "-m",
+        compose_message("lane #{lane}:", "lane #{lane}: integrate", message))
       integrate_sha_raw, = git_capture("-C", wt_path.to_s, "rev-parse", "HEAD")
       integrate_sha = integrate_sha_raw.strip
 
@@ -402,14 +414,14 @@ module Space::Architect
     # first conflict (a disjointness defect). Never decides which lanes pass. With no
     # lanes and teardown: true, tears down every lane recorded for the iteration instead
     # (the second, teardown-only call in the loop's integrate-then-teardown rhythm).
-    def integrate!(iteration, lanes: nil, teardown: false)
+    def integrate!(iteration, lanes: nil, teardown: false, message: nil)
       lanes = Array(lanes)
       return teardown_lanes!(iteration, slice_entry(iteration)["lanes"] || []) if lanes.empty? && teardown
       raise Space::Core::Error, "No lanes given to integrate" if lanes.empty?
 
       merged = []
       lanes.each do |lane|
-        merged << merge_lane!(iteration, lane)
+        merged << merge_lane!(iteration, lane, message: message)
       rescue Space::Core::Error => e
         done = merged.map { |m| m[:lane] }.join(", ")
         raise Space::Core::Error, "Integrated #{done.empty? ? "(none)" : done} then stopped at '#{lane}': #{e.message}"
@@ -572,11 +584,6 @@ module Space::Architect
         end
       end
 
-      # Seed prompt.md with a placeholder stub so the architect has a place to write the prompt.
-      # Never overwrite an existing file (real prompt or stub from a prior run).
-      prompt_path = build_dir.join("prompt.md")
-      prompt_path.write("#{PROMPT_STUB}\n") unless prompt_path.exist?
-
       new_fields = {
         "name" => lane,
         "repo" => repo,
@@ -755,7 +762,7 @@ module Space::Architect
     def dispatch(iteration, lane, model: nil, max_turns: 200,
                  claude_bin: nil, harness: nil, opencode_bin: nil, effort: nil, detach: false,
                  push_url: nil, push_token: nil, push_host: nil, run_creator: nil,
-                 push_client: nil, timeout: nil, now: Time.now)
+                 push_client: nil, timeout: nil, prompt: nil, now: Time.now)
       raise Space::Core::Error, "Specify --push-host or --push-url, not both" if push_host && push_url
       raise Space::Core::Error, "--push-host requires --push-token"           if push_host && !push_token
       raise Space::Core::Error, "--detach cannot be combined with --push-url or --push-host" \
@@ -781,6 +788,15 @@ module Space::Architect
       prompt_path  = build_dir.join("prompt.md")
       run_log_path = build_dir.join("run.jsonl")
       report_path  = build_dir.join("report.md")
+
+      # --prompt: the caller authors the lane prompt anywhere (a fresh scratch file)
+      # and the CLI owns the canonical copy — byte-for-byte, like variant_add.
+      if prompt
+        src = Pathname.new(prompt)
+        raise Space::Core::Error, "prompt file not found: #{src}" unless src.exist?
+        File.open(prompt_path, "wb") { |f| f.write(File.binread(src)) }
+      end
+
       raise Space::Core::Error, "prompt.md not found: #{prompt_path}" unless prompt_path.exist?
 
       prompt_content = prompt_path.read.strip
@@ -811,7 +827,9 @@ module Space::Architect
           run_log_path: run_log_path,
           chdir:        wt_path
         )
-        { pid: pid, run_log: run_log_path, report: report_path, worktree: wt_path }
+        result = { pid: pid, run_log: run_log_path, report: report_path, worktree: wt_path }
+        result[:prompt_copied] = prompt_path if prompt
+        result
       else
         created_run_id = nil
         if push_host
@@ -830,6 +848,7 @@ module Space::Architect
         exit_code = harness_obj.run(**run_kwargs)
 
         result = { exit_code: exit_code, run_log: run_log_path, report: report_path, worktree: wt_path }
+        result[:prompt_copied]  = prompt_path    if prompt
         result[:timed_out]      = true           if exit_code == Harness::ClaudeCodeHarness::TIMEOUT_EXIT_CODE
         result[:created_run_id] = created_run_id if created_run_id
         result[:push_url]       = push_url       if push_url
@@ -841,6 +860,20 @@ module Space::Architect
 
     attr_reader :space
 
+    # Compose a commit message. Without a custom message, the canonical default
+    # (unchanged). With one, a short canonical prefix keeps the loop's commit
+    # taxonomy grep-able while the author's first line owns the subject; any
+    # remaining lines become the commit body — the space's git log is the loop's
+    # durable memory, so callers are encouraged to write detailed bodies.
+    def compose_message(prefix, default, message)
+      return default if message.nil? || message.strip.empty?
+
+      subject, _, body = message.strip.partition("\n")
+      composed = "#{prefix} #{subject.strip}"
+      body = body.strip
+      body.empty? ? composed : "#{composed}\n\n#{body}"
+    end
+
     # Remove each lane's worktree and safe-delete (`-d`) its lane branch. Accepts
     # either merge_lane! results (symbol keys) or recorded lane entries (string
     # keys) — both carry a lane name and a repo.

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
@@ -146,14 +179,16 @@ module Space::Architect
         phase 12, "Spec"
         argument :iteration, required: true, desc: "Iteration name"
         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)
               warnings = []
-              sha = project.freeze!(iteration, warnings: warnings)
+              sha = project.freeze!(iteration, warnings: warnings,
+                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)
@@ -222,6 +257,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 +268,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 +276,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 +285,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])}"
@@ -310,14 +348,17 @@ module Space::Architect
         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"
+        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, **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,
+                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 +369,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 +380,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 +404,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)."
@@ -400,14 +428,15 @@ module Space::Architect
         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"
+        commit_message_options
 
-        def call(iteration:, lane:, space: nil, message: nil, **opts)
+        def call(iteration:, lane:, 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)
-              r = project.merge_lane!(iteration, lane, message: message)
+              r = project.merge_lane!(iteration, lane,
+                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."
@@ -424,8 +453,9 @@ module Space::Architect
         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"
+        commit_message_options
 
-        def call(iteration:, space: nil, lanes: nil, teardown: false, **opts)
+        def call(iteration:, space: nil, lanes: nil, teardown: false, message: nil, message_from: nil, **opts)
           setup_terminal(**opts.slice(:color, :colors))
           handle_errors do
             lane_names = lanes.to_s.split(",").map(&:strip).reject(&:empty?)
@@ -434,7 +464,8 @@ 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))
               if lane_names.empty?
                 if results.empty?
                   terminal.say "Nothing to tear down for #{iteration}"
@@ -690,17 +721,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

data/lib/space_core/version.rb

@@ -2,6 +2,6 @@
 
 module Space
   module Core
-    VERSION = "4.0.0"
+    VERSION = "5.0.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.0.0
 platform: ruby
 authors:
 - Eric Jacobs