space-architect 3.0.0 → 5.0.0

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,
@@ -121,8 +136,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
@@ -245,9 +263,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
@@ -293,20 +319,35 @@ 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
-`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**
@@ -363,9 +404,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
@@ -377,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

@@ -27,45 +27,60 @@ pattern match), so the post-flight `git log` is what the loop actually trusts.
 If a lane committed, treat the worktree as tampered: reset and re-dispatch.
 
 **Preflight (once per environment):** run `claude --version`, and confirm the
-builder model resolves with a one-shot canary
+builder model resolves with a one-shot
 (`echo ok | claude -p --model <builder-model> --max-turns 1`). No API key —
 the builder runs on your Claude plan — but note headless `claude -p` draws on
 the Agent SDK credit pool (separate from interactive usage since June 15 2026;
-see `docs/DESIGN.md` §4). On the first real dispatch in a new environment, launch
-ONE canary lane and confirm it starts cleanly before fanning anything out.
+see `docs/DESIGN.md` §4). Past that one-time check, no dispatch needs a manual
+start-check: every foreground dispatch self-verifies. Shortly after launch it
+prints a liveness line to stderr naming the streamed model and confirming the
+run log is growing — or a WARN line instead when the streamed model disagrees
+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
-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, create worktrees first (one per lane), then dispatch
-each lane from its worktree:
+For multi-lane iterations, materialize every declared lane in one shot with
+`architect provision`, then dispatch each lane from its worktree:
 
 ```bash
-# per lane:
-architect worktree add <repo> <iteration> <lane> [--base <repo-base>]
-architect dispatch <iteration> <lane>
+architect provision <iteration>          # all declared lanes: worktree + lane/<id>-<lane> branch
+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 worktree add` creates `build/<id>-<lane>/wt` off the target repo's
-base commit (a repo commit — distinct from the freeze, which is a space
-commit), adds it with a `lane/<iteration>-<lane>` branch, and records it in
-`space.yaml`.
+`architect provision` reads the frozen lane declarations from `space.yaml` and,
+per lane, creates `build/<id>-<lane>/wt` 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), adds it with a
+`lane/<iteration>-<lane>` branch, and records it in `space.yaml`. It is
+idempotent (`--lane <name>` provisions a single lane), and wraps the
+`architect worktree add` primitive — still registered for edge cases, not a step
+in the flow. `dispatch`, `integrate`, and `gate` also lazily materialize a lane
+whose worktree is missing from its frozen declaration, so the flow can't
+dead-end on a missing worktree.
 
 Issue each dispatch as its **own background Bash tool call** — one call per
 lane. Never use a shell `&` loop. A `for … & done` launcher is a *launcher*
@@ -82,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 \
@@ -113,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
@@ -140,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
@@ -157,10 +177,12 @@ integrate without conflict.
    fast-follow lane's `--touch` set and exclude them from every parallel lane's
    touch-set — so the parallel set is disjoint by construction.
 
-2. **Create worktrees and dispatch the parallel lanes** (off the repo base):
+2. **Provision and dispatch the parallel lanes** (off the repo base). Provision
+   only the parallel lanes by name — leave the fast-follow lane unmaterialized
+   until step 4, so it can root at the integrated tip:
    ```bash
-   architect worktree add <repo> <iteration> lane-a
-   architect worktree add <repo> <iteration> lane-b
+   architect provision <iteration> --lane lane-a
+   architect provision <iteration> --lane lane-b
    architect dispatch <iteration> lane-a   # own background Bash call each
    architect dispatch <iteration> lane-b
    ```
@@ -172,11 +194,11 @@ integrate without conflict.
    architect gate <iteration>
    ```
 
-4. **Create the fast-follow lane off the integrated tip.** `--base` accepts any
-   git ref — passing `project/<slug>` roots the new worktree at the merged tip
-   (the keystone move):
+4. **Provision the fast-follow lane off the integrated tip.** `--base` accepts
+   any git ref — passing `project/<slug>` roots the new worktree at the merged
+   tip (the keystone move); `--lane ff` provisions just that lane:
    ```bash
-   architect worktree add <repo> <iteration> ff --base project/<slug>
+   architect provision <iteration> --lane ff --base project/<slug>
    architect dispatch <iteration> ff
    ```
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: space-architect
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Eric Jacobs
@@ -272,6 +272,7 @@ files:
 - lib/space_core/cli/helpers.rb
 - lib/space_core/cli/init.rb
 - lib/space_core/cli/list.rb
+- lib/space_core/cli/loop_status.rb
 - lib/space_core/cli/new.rb
 - lib/space_core/cli/pack.rb
 - lib/space_core/cli/path.rb