space-architect 9.1.0 → 9.2.0

data/skill/architect/dispatch.md

@@ -1,5 +1,53 @@
 # Builder dispatch reference
 
+## The coordinator path (default) — how builders actually launch
+
+When a plan runs under the coordinator (see SKILL.md §Starting a loop), the
+coordinator itself spawns each role as a **pi subagent** — native async
+completion wakes, not `architect dispatch` headless runs. Per iteration:
+
+1. **spec** — agent `architect-spec`, cwd = the space root, task = the plan
+   ENTRY verbatim. Writes Grounds/Specification/Acceptance Criteria via
+   `architect section`, rehearses, freezes, assembles each lane's prompt in a
+   scratch file, records the scratch paths in its report, and writes the
+   `notes/spec-digest-*` handoff. `timeoutMs` 3600000 (1h).
+2. **provision** — the coordinator runs `architect provision <iteration>` via
+   bash; the CLI materializes every declared lane's worktree + lane branch.
+3. **prompt copy** — the coordinator copies each spec-assembled scratch prompt
+   to `build/<id>-<lane>/prompt.md` (canonical path, CLI-owned in the
+   interactive path; the coordinator's `cp` is the sanctioned equivalent).
+4. **builder per lane** — agent `architect-builder`, cwd = that lane's
+   worktree, task = read `build/<id>-<lane>/prompt.md` before anything else.
+   `timeoutMs` 7200000 (2h). The lane-prompt template below is the contract
+   the spec assembles against.
+5. **judge** — agent `architect-judge`, cwd = the space root, task = judge the
+   iteration by id. `timeoutMs` 7200000 (2h). The judge is a fresh session —
+   §1 fresh-session judgment holds structurally: the judge session never
+   dispatched or built anything.
+6. **narrator** — one `architect-narrator` spawn per settled event
+   (builders-settled, judge-settled, verdict-landed, exception, plan-complete),
+   `timeoutMs` 300000 (5m), best-effort, never a gate on the loop.
+
+Spawn contract (all paths): every spawn pins its model explicitly
+(provider/id[:thinking]) and carries an explicit `timeoutMs` — never the
+30-minute default. A child that hit its timeout is **replaced in-place, never
+resumed** (upstream resume of a timed-out session fails deterministically):
+exactly one replacement, same cwd, larger `timeoutMs`, and auditing the
+inherited uncommitted diff is its first task. Infrastructure death (failed to
+start, crashed before work) gets one relaunch. Anything unrootable is an
+exception: `notes/exception-<ts>.md`, narrate, terminate — no improvised
+repairs.
+
+The coordinator never edits files except its own `notes/` reports and never
+writes into `architecture/`.
+
+`architect dispatch` (everything below) remains the **interactive-path**
+mechanism — and the reference implementation of the lane contract the
+coordinator's spawns inherit (same prompt template, same builder guard
+discipline — interactive dispatch injects the guard via `-e`; a coordinator
+spawn relies on the playbook's no-git-writes rule plus the judge's post-flight
+`git log` check, which stays the authoritative proof in both paths).
+
 Verified against `pi` 1.1.0 (badlogic/pi-mono) headless print mode — the reference
 harness. The builder is `pi -p` (`--print`, the non-interactive mode) pinned to
 the configured builder model (`<builder-model>`) — a cheaper model run headless
@@ -29,9 +77,14 @@ not airtight (a builder can shell out — `sh -c 'git commit …'` — past the
 parse), 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 `pi --version`, and confirm the
+**Preflight (once per environment):** run `pi --version`, confirm the
 builder model resolves with a one-message probe
-(`echo ok | pi -p --model <builder-model>`). No API-key/env ceremony — provider
+(`echo ok | pi -p --model <builder-model>`), confirm the role playbooks are
+installed (`architect install-agents` — once per machine, idempotent), and
+for a coordinator run confirm the routing config resolves — an
+`architect.yaml` role pinning a model the registry doesn't know throws loudly
+at /loop pre-flight, before any spawn (/loop pre-flight does this for you).
+No API-key/env ceremony — provider
 config (e.g. the Fireworks key) resolves from `~/.pi/agent`; pi needs no
 `ANTHROPIC_*` env. Past that one-time check, no dispatch needs a manual
 start-check: every foreground dispatch self-verifies. Shortly after launch it
@@ -154,17 +207,19 @@ The guard is a first line, not a sandbox — the post-flight `git log` check
 ### Integration (judging session — after per-lane post-flight passes)
 
 This block runs in the judging session, not the dispatch session — the dispatch
-session's job ends when builders finish (see SKILL.md §5–6). You decide which
+session's job ends when builders finish (see SKILL.md §Interactive path). You decide which
 lanes pass; the CLI does the git mechanics. Canonical path:
 
 ```bash
 architect integrate <iteration> --lanes <passing-set>   # e.g. --lanes lane-a,lane-b
-architect gate <iteration>                              # integration smoke (raw output; verdict stays yours)
+architect gate <iteration>    # integration smoke — writes the full transcript to
+                              # build/gate/<id>-<ts>.md and prints the path; the
+                              # inline report is bounded, the file is the record
 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 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
+# gh pr create) — see SKILL.md §After a loop lands
 ```
 
 `architect integrate` commits each named lane on its branch and merges it
@@ -184,6 +239,9 @@ per lane when that lane's worktree still holds uncommitted work, untracked
 files included, because that's what a dispatched lane always holds; `--force`
 overrides and discards it. The `--lanes <passing-set>` integration path itself
 is unaffected — `integrate` commits each lane's work before tearing it down.
+`architect gate` never evaluates — it streams raw output for the judging
+session to read; its transcript file (`build/gate/…`) holds every gate's
+complete stdout/stderr when the terminal report has been trimmed.
 
 Under the hood / manual fallback (one lane shown):
 
@@ -369,6 +427,11 @@ instruction.
   blocking `while pgrep …; sleep` wait loop as a Bash command — that is itself
   a launcher that ties up a turn. When you return to a lane, check liveness via
   run-log growth (the stall rules below still apply unchanged).
+- Visibility while anything runs: `architect looplog` follows every active
+  subagent run in the space (transcripts from pi's sessions dir and the
+  space's `build/` tree); `--list` inventories without following;
+  `architect runlog build/<id>-<lane>/run.jsonl` pretty-prints one dispatch
+  event stream (or streams it: `tail -f … | architect runlog`).
 - Pin the model explicitly. The tool does this automatically (`--model
   <builder-model>`). A floating alias (a bare "latest"/tier tag) drifts to
   whatever ships next — fine interactively, but automations pin the full id so a
@@ -457,6 +520,14 @@ Paste the lane-prompt into an interactive `pi` session (no `-p`). pi's agent
 loop runs plan→act→test against the block's stopping condition while you watch
 and steer. Use when the human wants to babysit a run.
 
+A coordinator can be launched the same way when /loop is unavailable: spawn
+the agent `architect-coordinator` (role agents resolve from
+`~/.pi/agent/agents/`, user-level, installed by `architect install-agents` —
+no project trust involved) with cwd = the space root, the plan text verbatim
+as the task, the coordinator's model pin from `architect.yaml` in the spawn's
+model field, and `timeoutMs` 43200000 (12h) — the exact contract
+`coordinatorSpawnScript` in architect-loop.ts assembles.
+
 ## Lane-prompt template
 
 ```

data/skill/architect-plan/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: architect-plan
+description: "Plan work for the architect loop and launch it as an autonomous coordinator run (/loop). Use when the user's intention is to START a loop: planning iterations, writing the plan doc (notes/plan-*.md), pinning role routing, launching the coordinator, and watching it run. For general architecture work without launching a loop (arbitration, judging, landing, iteration surgery, conversation), use /architect instead."
+---
+
+# Architect Plan
+
+You are the ARCHITECT planning a coordinator run. The deliverable of this
+skill is exactly one thing: a committed plan doc and a launched coordinator.
+The loop's roles (spec → builders → judge, driven by the coordinator) do
+everything after that — you never absorb a builder wakeup.
+
+Read `/architect` (the main skill) first for roles, routing, and the hard
+rules. This skill covers only the start.
+
+## Procedure
+
+1. **Ground (never skip).**
+   - `architect status` — iteration/verdict state; anything in flight?
+   - `architect looplog --list` — is a loop already running? Fresh transcripts
+     mean a live loop: don't double-start; report and ask.
+   - Read `architecture/ARCHITECT.md` (TOC + backlog), `architecture/BRIEF.md`
+     (the durable §-contract — cite it as BRIEF §N), the in-flight iteration
+     file if any, and the latest `notes/spec-digest-*.md` (the previous spec's
+     handoff: verification commands actually used, repo seams, house
+     conventions, open unknowns — carry its facts forward or they are lost).
+   - Read the target repo's `AGENTS.md`/`CLAUDE.md` → `README.md` → docs;
+     confirm the exact verification gate command.
+   - Learn the verification gate (test/lint/typecheck/build) from docs or CI
+     config — the plan's acceptance direction must name it.
+2. **Scale the work.** Trivial fixes don't need the loop — say so and do it
+   inline. One PR-sized iteration = one ENTRY. Multi-iteration plans get
+   ordered ENTRYs (the coordinator works them in order, skipping finished
+   ones). If the open question is too uncertain to build, make the ENTRY a
+   spike (investigate-only; deliverable is a recommendation — see /architect).
+3. **Write the plan doc** to `notes/plan-<UTC timestamp>-<name>.md`:
+
+   ```markdown
+   # Plan — <name> (<one line>)
+
+   Operator plan <date>. <Repos/lanes in scope.>
+
+   Standing context the spec needs: prior iterations this builds on, routing
+   pins, and the post-landing follow-ups (outside-the-loop work the plan
+   deliberately excludes — name it so it isn't lost).
+
+   ## ENTRY N — iteration <name> (repo: <repo>, <lane count> lane(s))
+
+   **Objective.** What to build and why — the reason, not just the ask. Cite
+   BRIEF §N. If this ENTRY pins model/thinking for a role, say it here (the
+   coordinator passes it in that spawn's model field).
+
+   **Grounds to read.** Exact paths: research/bug reports, source files being
+   ported, seam files, prior verdicts. The spec reads these before writing a
+   word.
+
+   **Acceptance direction (spec refines into frozen AC).** The properties the
+   finished iteration must have — at the level the spec can freeze, not
+   pre-written gates (freezing is the spec's job).
+
+   **Constraints.** Repos; files that must not change; out-of-scope;
+   house-style expectations; what the lane must NOT delete or move (say so
+   when a port is replacing something that lives elsewhere).
+   ```
+
+   Each ENTRY must be self-contained — the spec agent receives the entry
+   verbatim and nothing else. Put the verification gate command in ENTRY
+   constraints or grounds.
+4. **Pin routing if needed.** This plan's models come from `architect.yaml`
+   (space root overrides `~/.config/space-architect/architect.yaml` per role).
+   A one-plan pin goes in the plan header/ENTRY (the coordinator passes it in
+   that spawn's model field); a standing change edits `architect.yaml` —
+   routing rides the spawn contract and `/loop` resolves it at launch, so
+   there are no generated agent files to hand-sync (the role playbooks are
+   static, user-level, installed once by `architect install-agents`).
+5. **Commit the plan doc** to the space — an uncommitted plan is scratch, and
+   decision-bearing documents live in `notes/` (not-committed = didn't
+   happen).
+6. **Launch.** From an interactive pi session at the space root:
+
+   ```
+   /loop --from notes/plan-<ts>-<name>.md
+   ```
+
+   `/loop` refuses an empty plan, resolves the routing config (validates
+   every pin against the model registry — a pin it doesn't know throws
+   loudly, before any spawn — and injects the per-role pins into the
+   coordinator's task), and spawns `architect-coordinator` detached — your
+   session may end; the coordinator (12h ceiling) works the plan, narrating
+   every settled event to `notes/narrative-*.md`. If pi-subagents' RPC is not
+   up in the session, /loop says so — spawn the coordinator directly instead
+   (agent `architect-coordinator`, the space as cwd, the plan text verbatim as
+   the task, the coordinator's model pin from `architect.yaml`, `timeoutMs`
+   43200000).
+7. **Report the handoff, then stop.** Tell the human: the plan path, the
+   coordinator run id, and how to watch —
+   `architect looplog` (live), `--list` (inventory),
+   `architect status`, `architect cost`. Escalations route through the
+   coordinator to your supervisor seat: rule and the coordinator steers; if
+   your session won't stay alive, say so — a coordinator with no listener
+   parks the question in `notes/escalation-<ts>.md` and stops via the exception
+   path rather than improvising.
+
+## Failure modes to check before launching
+
+- **Frozen-region edits** — never edit `architecture/` directly; the plan
+  steers, the spec writes sections via the CLI.
+- **Stale base** — outside-the-loop commits that landed on a repo's main since
+  the last provision are fine (`architect provision` fast-forward-syncs
+  `project/<slug>` from the default branch or refuses loudly on divergence);
+  a deliberately diverged integration branch must be named in the plan.
+- **Stale gem / extension** — if the plan exercises CLI behavior newer than
+  the installed gem, note the rebuild in standing context: a config that
+  moved ahead of the installed CLI rejects every command.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: space-architect
 version: !ruby/object:Gem::Version
-  version: 9.1.0
+  version: 9.2.0
 platform: ruby
 authors:
 - Eric Jacobs
@@ -186,11 +186,13 @@ files:
 - lib/space_architect/cli/architect.rb
 - lib/space_architect/cli/research.rb
 - lib/space_architect/conversations_client.rb
+- lib/space_architect/extension_installer.rb
 - lib/space_architect/gate_evaluator.rb
 - lib/space_architect/gate_lint.rb
 - lib/space_architect/harness.rb
 - lib/space_architect/jobs_client.rb
 - lib/space_architect/loop_cost.rb
+- lib/space_architect/looplog.rb
 - lib/space_architect/pi/builder-guard.ts
 - lib/space_architect/research.rb
 - lib/space_architect/research/mux.rb
@@ -201,6 +203,7 @@ files:
 - lib/space_architect/research/supervisor.rb
 - lib/space_architect/routing.rb
 - lib/space_architect/run_creator.rb
+- lib/space_architect/runlog.rb
 - lib/space_architect/session_sync.rb
 - lib/space_architect/session_sync/bin_path.rb
 - lib/space_architect/session_sync/cursor.rb
@@ -208,10 +211,12 @@ files:
 - lib/space_architect/session_sync/runner.rb
 - lib/space_architect/session_sync/session_id.rb
 - lib/space_architect/skill_installer.rb
+- lib/space_architect/space_push.rb
 - lib/space_architect/templates/architect.md.erb
 - lib/space_architect/templates/brief.md.erb
 - lib/space_architect/templates/iteration.md.erb
 - lib/space_architect/version.rb
+- skill/architect-plan/SKILL.md
 - skill/architect-research/SKILL.md
 - skill/architect-research/lanes.md
 - skill/architect-vocabulary/SKILL.md