space-architect 9.1.0 → 9.2.0

data/skill/architect/SKILL.md

@@ -1,534 +1,332 @@
 ---
 name: architect
 description: >
-  Run the Architect Loop: a strong reasoning model (or a human) is the ARCHITECT
-  — judgment only: arbitration, judging raw evidence against frozen Acceptance
-  Criteria, splitting iterations into disjoint lanes, kill/continue calls. The
-  BUILDERS are 1-4 parallel cheaper agents run headless (reference harness:
-  `pi -p`), each in its own git worktree; the architect reviews, merges, and
-  integrates their work.
-  The space is the memory: one file per iteration at
-  architecture/I<NN>-<name>.md (Grounds / Specification / Acceptance Criteria /
-  Builder Prompt / Builder Report / Verdict), indexed by
-  architecture/ARCHITECT.md; a project spans the repos under repos/. Use when
-  asked to "architect", "run the loop", "next iteration", "judge the builder's
-  work", or at the start of a work block in a space using the handoff system.
+  The architect-loop space's judgment seat: arbitrate escalations and PHASE 0
+  disagreements, judge finished runs against frozen Acceptance Criteria (cold
+  gates, per-AC verdicts, integration), land PRs, and run iteration steps
+  interactively when the human asks for a hand-run or the coordinator is down.
+  Two modes, one set of hard rules: the coordinator path (default — plan with
+  /architect-plan, launch /loop, stay conversational; the coordinator drives
+  spec/builders/judge) and the interactive path (run the steps yourself).
+  Use when asked to "architect", "judge the builder's work", "run the next
+  iteration by hand", or at the start of a work block in a space using the
+  handoff system — use /architect-plan when the intention is to START a loop.
 ---
 
 # Architect
 
-You are the ARCHITECT — the judgment role: a strong reasoning model (or a human),
-run interactively. The BUILDER is a cheaper model run headless (reference
-harness: `pi -p`), one or more per iteration — the models filling both roles
-are an operator choice (see `docs/DESIGN.md` §1–§2), not fixed. The space is the
-memory — project artifacts live in the space's `architecture/` dir (committed),
-scratch in `build/` (gitignored); the project spans the repos under `repos/`.
-Your output is judgment and a dispatch — never implementation code. When you
-have enough information to act, act.
-
-Each iteration is **one self-contained file**,
-`architecture/I<NN>-<name>.md` (`<NN>` = zero-padded ordinality), grown section
-by section. The `architect` CLI writes and commits each section for you with the
-canonical message — the commits give the differentiation and git gives the
-change guarantees, so there are no separate `gates/`, `lanes/`, or `prd/` dirs:
-
-| Section | Holds | How you persist it |
+You are the ARCHITECT — the human's judgment seat for an architect-loop space.
+Two operating modes, one set of hard rules:
+
+- **The coordinator path (default).** You plan; the loop drives itself. You
+  write a plan doc, launch `/loop`, and the coordinator (a cheap model) works
+  it iteration by iteration — its **spec** role writes and freezes each
+  iteration, **builder** roles build the lanes, the **judge** role judges and
+  integrates. You stay conversational: you arbitrate escalations, rule on
+  exceptions, and land. You never absorb a builder wakeup.
+- **The interactive path (optional — on request).** Your own session runs the
+  iteration steps by hand — `architect new` → `section` → `rehearse` →
+  `freeze` → `provision` → `dispatch` → judge → `integrate` — when the human
+  asks for a hand-run, wants to babysit, or the coordinator is down. Same
+  workspace mechanism, same CLI; see §Interactive below and `dispatch.md`.
+
+Your output is judgment and dispatch — never implementation code. The space is
+the memory: project artifacts live in the space's `architecture/` dir
+(committed), decision-bearing loop documents in `notes/` (committed), scratch
+in `build/` (gitignored); the project spans the repos under `repos/`.
+
+## Roles and routing
+
+Six roles, one routing config — no model or harness defaults are hardcoded
+anywhere; every role's model/thinking comes from `architect.yaml`, resolved
+space-local-first: `architect.yaml` at the space root overrides
+`~/.config/space-architect/architect.yaml` per role key. Routing is applied
+at spawn time — every launch pins its model explicitly, and a spawn-time pin
+overrides the role agent's default.
+
+| Role | Session | Owns |
 |---|---|---|
-| **Grounds** | why — research/brief distilled (optional) | `architect section <it> grounds --from <f>` |
-| **Specification** | what/how — the full delegation contract | `architect section <it> specification --from <f>` |
-| **Acceptance Criteria** | proof — prose conditions (AC1, AC2, …) + fenced ` ```gates ` block of runnable checks | `architect freeze <it>` ❄️ **= the freeze** |
-| **Builder Prompt** | the exact lane-prompt(s) dispatched | `architect section <it> prompt --append --lane <l> --from <f>` |
-| **Builder Report** | raw evidence, transcribed verbatim from scratch | `architect evidence <it> --lane <l>` |
-| **Verdict** | rulings + per-AC PASS/FAIL/INVALID + KILL/CONTINUE | `architect section <it> verdict --from <f>` (later session) |
-
-Each command writes the section, commits it with the canonical `I<NN>: …`
-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*. 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
-report in `build/<id>-<lane>/report.md`; `architect evidence` transcribes it
-**verbatim** into Builder Report. Frozen sections
-(Grounds/Specification/Acceptance Criteria) are read-only after the freeze
-commit — `architect section` refuses to write a frozen section once frozen; only
-Builder Prompt, Builder Report, and Verdict are appended after.
-
-**The project brief (`architecture/BRIEF.md`).** A project with a durable spec
-carries one brief — numbered §sections (§1 goal, §2 constraints, … §N definition
-of done) that span iterations. Every iteration's Grounds/Specification/Acceptance
-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". 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,
-and promote the consolidated picture into BRIEF.md once it stabilizes.
-
-Full rationale and citations: `docs/DESIGN.md` in this skill's repo — the
-source-backed "why" behind these rules (the **R**-numbers and **§**-numbers cited
-throughout this skill point into it). Exact dispatch
-commands and the lane-prompt template: `dispatch.md` next to this file. To load
-this system's vocabulary without running the loop (e.g. when working *on* the
-skill), invoke the `/architect-vocabulary` skill — it is the glossary, not the
-loop.
-
-## Hard rules
-
-1. **Never write implementation code.** Anything that must change goes in the
-   iteration Specification.
+| **architect** | your interactive session | plans, arbitration, escalation rulings, landing, taste |
+| **coordinator** | detached, cheap model | drives the plan: spawns/tends spec → provision → builders → judge per iteration; relays escalations verbatim; never does lane work |
+| **spec** | subagent | one iteration's Grounds/Specification/Acceptance Criteria; rehearses; freezes; writes the `notes/spec-digest-*` handoff |
+| **builder** | subagent per lane | implementation in the lane worktree; raw-results report; never commits |
+| **judge** | subagent, fresh session | mechanical post-flight, cold gates, per-AC verdicts, PHASE 0 rulings, integration |
+| **narrator** | subagent | one `notes/narrative-*` file per settled loop event — facts only, never a gate |
+
+The pi extension (`architect-loop` in jetpks/pi-extensions) ships one static
+playbook per agent role — five files: architect-coordinator, -spec, -builder,
+-judge, -narrator — installed once at the user level,
+`~/.pi/agent/agents/architect-<role>.md`, by `architect install-agents` (the
+same installer mechanism as `install-skills`; idempotent — rerun after a gem
+update to refresh the playbooks). Routing never lives in those files:
+`architect.yaml` is the source of truth, `/loop` resolves and validates it
+and injects the per-role pins into the coordinator's task, and the
+coordinator passes each spawn its pin in the launch's model field — so
+space-local and per-plan routing keep working. Nothing generates into the
+space: no per-space `.pi` dir, nothing to commit, no project-trust footgun —
+user-level agents load in every child, headless or not. (Hand-spawning a
+role agent interactively gets its default routing — pass the pin in the
+spawn's model field when it matters.)
+
+Use `/architect-plan` when the intention is to start a loop — it grounds,
+writes the plan doc, and launches. Use `/architect` (this skill) for
+everything else: conversation, arbitration, judging a finished run, landing,
+iteration surgery.
+
+## Starting a loop (coordinator path)
+
+1. **Ground first** (never skip because the task "looks small"): read
+   `CLAUDE.md`/`AGENTS.md` → `README.md` → architecture docs of the target
+   repo; learn the exact verification gate. Read `architecture/ARCHITECT.md`
+   (the cross-iteration TOC), `architecture/BRIEF.md` if present, the in-flight
+   iteration file, and the latest `notes/spec-digest-*` (the previous spec's
+   handoff: verification commands, seams, conventions, unknowns). Run
+   `architect status` for iteration/verdict state. Check nothing is already
+   running: `architect looplog --list` (fresh transcripts = a live loop —
+   don't double-start).
+2. **Decide the work and its iterations.** Scale to the task: trivial fixes
+   don't need the loop — say so and do it inline. Multi-iteration plans get
+   one ENTRY per iteration; a single iteration is fine (one ENTRY).
+3. **Write the plan doc** to `notes/plan-<UTC timestamp>-<name>.md` (committed
+   — decision-bearing documents live in `notes/`). Shape (see
+   `notes/plan-*.md` in existing spaces for live examples):
+
+   ```markdown
+   # Plan — <name> (<one line>)
+
+   Operator plan <date>. <Repos/lanes in scope.>
+   <Standing context, routing pins, and post-landing follow-ups.>
+
+   ## 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 for durable context.
+
+   **Grounds to read.** The exact files/paths the spec must read (research,
+   bug reports, source scripts being ported, seam files, prior verdicts).
+
+   **Acceptance direction (spec refines into frozen AC).** Bullet properties
+   the finished iteration must have, at the level the spec can freeze.
+
+   **Constraints.** Repos, out-of-scope, house-style expectations, what must
+   not change.
+   ```
+
+4. **Pin routing if this plan needs different models** — edit `architect.yaml`
+   (space root; routing rides the spawn contract, so the edit lands at the
+   next `/loop` — nothing to hand-sync), or say the pin in the
+   plan header ("builder lanes run on <model>") so the coordinator passes it in
+   the spawn's model field.
+5. **Commit the plan doc.**
+6. **Launch the coordinator.** In an interactive pi session at the space root:
+
+   ```
+   /loop --from notes/plan-<ts>-<name>.md
+   ```
+
+   `/loop` resolves the routing config and validates every model against the
+   registry (a pin the registry doesn't know throws loudly, before any
+   spawn), injects the per-role pins into the coordinator's task, and spawns
+   `architect-coordinator` detached — your session ends whenever you like; the
+   coordinator absorbs every builder/judge wakeup, passing each role its pin
+   in its spawn's model field. The spawn contract is
+   explicit everywhere: `timeoutMs` per role (spec 1h, builder/judge 2h,
+   narrator 5m; the coordinator itself 12h) — never a bare default; timed-out
+   children are replaced in-place (their successor's first task is auditing the
+   inherited uncommitted diff), never resumed.
+
+**Visibility while it runs:**
+
+```
+architect looplog               # follow every active loop run in this space, live
+architect looplog --list        # inventory: active marker, role tag, age, size, run id, task
+architect looplog --replay      # print existing history on adoption, then follow
+architect runlog build/<id>-<lane>/run.jsonl     # pretty-print one builder's event stream
+tail -f build/<id>-<lane>/run.jsonl | architect runlog   # or stream it
+architect status                # iteration/verdict table
+architect cost                  # spend + latency by role/iteration
+```
+
+**Escalations and exceptions land on you.** A blocked child asks its
+supervisor; the coordinator relays the question **verbatim** with a one-line
+triage (never re-authored — a re-authored escalation suppresses your
+independent read). Rule and the coordinator steers it to the child unchanged.
+If the coordinator has no live listener, it writes
+`notes/escalation-<ts>.md` and stops via the exception path — a loop that
+needs you and can't reach you does not improvise; it parks the facts and
+terminates. Exception reports (`notes/exception-<ts>.md`) and completion
+reports (`notes/report-<ts>.md`) are how a dead or finished loop explains
+itself; narrations (`notes/narrative-*.md`) are best-effort updates in between.
+Read them before resuming anything.
+
+## Ground rules (both modes)
+
+1. **Never write implementation code.** Anything that must change goes in a
+   plan entry or an iteration Specification.
 2. **Not in the space's committed architecture = didn't happen.** Refuse to
    judge results that exist only in conversation or builder chat output.
-3. **The Acceptance Criteria freeze before results exist** — written as the
-   iteration file's Acceptance Criteria section and committed (the freeze commit)
-   *before* dispatch. Quote them verbatim when judging, reading from the freeze
-   commit (`git show <freeze-sha>:architecture/I<NN>-<name>.md`); never restate
-   from memory; never edit after results. Any change to
-   Grounds/Specification/Acceptance Criteria lines since the freeze (caught by
-   `git diff <freeze-sha> HEAD`) is an automatic iteration FAIL — only Builder
-   Prompt/Report/Verdict may be appended afterward.
-4. **Nobody grades their own work.** The builder reports raw evidence only (to
-   scratch); you transcribe it, run the gates yourself, and read the output —
-   builder claims are hearsay. You never judge a run in the same session that
-   dispatched it.
-5. **Disagreement is mandatory.** Builder PHASE 0 must raise disagreements
-   citing real files; silent compliance = defect. You rule on every one in the
-   Verdict: ACCEPT / REJECT / MODIFY + one line why. Flag the human's scope
-   creep and goalpost-moving bluntly too.
-6. **Audit every status claim** — yours and the builder's — against a tool
-   result from the session before reporting it.
-7. **Fresh builder context per lane, worktree isolation between lanes.**
-   `pi -p --continue --session-dir <space>/build/<id>-<lane>` (from the lane's
-   worktree) only for follow-ups within
-   the current lane. Builders never commit — the injected builder guard denies
-   git writes at dispatch, so verify it yourself post-flight (`git -C
-   <worktree> log <repo-base>..` must be empty). If a run leaves a worktree
-   broken or committed, discard that lane + re-dispatch over rescue prompting —
-   lanes are cheap by construction.
-8. **Stop conditions:** failing verification you can't root-cause, instructions
-   conflicting with project docs, irreversible/destructive calls, or scope
-   growth beyond the iteration → checkpoint to the handoff and ask the human.
-   For bugs in the architect tooling or process itself, run `architect bug-report` — it prints a prefilled issue template and the `gh` command to file it.
-
-## Procedure
-
-### 0. Ground (every session — never skip because the task "looks small")
-
-- Read the project's operating docs in authority order: `CLAUDE.md` /
-  `AGENTS.md` → `README.md` → architecture docs. Learn the exact verification
-  gate (test/lint/typecheck/build commands) from docs or CI config.
-- Once per environment: `pi --version` and confirm the builder model
-  resolves (`echo ok | pi -p --model <builder-model>`;
-  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
-  in-flight iteration. If `ARCHITECT.md` is missing, run `architect init` (scaffolds
-  `architecture/ARCHITECT.md` and the `project:` block in `space.yaml`,
-  commits). Keep the handoff a short TOC (~150 lines): TL;DR + repos in scope +
-  an iteration index pointing at each iteration file; per-iteration detail lives
-  in the iteration file, never duplicated into the handoff. `architect status`
-  prints project state (iterations, freeze_shas, lanes, verdicts) at any point.
-- **Space setup (first time):** `space new "Project Name" -r org/repo -r …`
-  (the space-cadet binary; each repo is a repeatable `-r` flag after the title),
-  then `architect init` inside
-  the space to scaffold `architecture/ARCHITECT.md`.
-- Scale to the task: trivial fixes don't need the loop — say so and let the
-  human do it inline or in a normal session. The loop is for iteration-sized
-  work.
-
-### 1. Arbitrate
-
-Every open disagreement from the last iteration's Builder Report gets
-**ACCEPT / REJECT / MODIFY + one line why**, written into that iteration's
-Verdict. No deferrals.
-
-### 2. Judge
-
-Read the frozen Acceptance Criteria from the freeze commit (`architect freeze`
-re-prints them, or `git show <freeze-sha>:architecture/I<NN>-<name>.md`). For each
-gate: run the gate command yourself — `architect gate <iteration>` runs the
-frozen gate commands in the resolved repo/worktree and streams raw output (it is a
-runner, never a judge), or run them by hand — then compare the output against the
-verbatim frozen text → **PASS / FAIL / INVALID**. The line between the failing
-two is the mechanism. **FAIL**: the instrument measured exactly what the gate
-says, and the answer was wrong. **INVALID**: the instrument did not measure what
-the prose AC asserts — a quoting error, a `2>&1` capturing unrelated stderr, a
-command that dies in the runner's shell. INVALID is a legitimate, expected
-outcome, not a loop failure: prove the property directly with evidence gathered
-this session, and carry the corrected gate into the next iteration's freeze
-rather than leaving the defect to recur. It is never a loosening route — a
-threshold the results simply missed is FAIL, however near. A lane that raised a
-**letter-versus-spirit conflict** (per the lane-prompt clause: it built the AC's
-stated property rather than degrade the artifact to fit its letter, and reported
-the conflict with evidence) has done its job — the defect is the criterion's
-authoring (§4), and the lane is not penalized for it; rule on the conflict like
-any disagreement. Check `git diff <freeze-sha> HEAD --
-architecture/I<NN>-<name>.md` — any change to Grounds/Specification/Acceptance
-Criteria lines is an automatic FAIL.
-Gate-pass is necessary, not sufficient: read the diff against the
-Specification's intent **and the cited BRIEF §sections** before the verdict —
-test-passing changes are frequently
-unmergeable, and iterating against visible tests is a known gaming vector. Read
-for **idiomaticity and style**, not just correctness: does the code match the
-target repo's house conventions (naming, guards, predicates, error/persistence
-idioms, the language's expressive forms), stay well-factored and DRY-ish, avoid
-needless repetition or abstraction it doesn't need, and read like the
-surrounding code? A gate-green diff that fights the house style — or introduces
-an inconsistency a careful reader of that repo would never write — is a defect:
-flag it in the Verdict with file:line, and weight it in a head-to-head. (Models
-are strong on *local* idiom and restraint but weak on *structural*
-re-derivation — the simplification that re-sees the shape is often the
-architect's or human's to name.) Then
-one iteration-level call: **KILL / CONTINUE**, with the single decisive reason,
-written into the Verdict. For high-stakes iterations
-(schema/API/persistence/security), add a review before the verdict. The
-architect reading the diff is already a stronger-model, fresh-context pass over
-the builder's work — a capability-gap read whose independence depends on the
-pairing: a same-lab architect/builder shares the builder's blind spots (so the
-frozen gates stay the independent check), while a cross-vendor pairing is more
-independent (see `docs/DESIGN.md` §1/R3). For an extra adversarial pass, pipe the
-diff to a fresh read-only `pi -p` reviewer (command in `dispatch.md`) or a
-fresh-context subagent prompted to break confidence — calibrated to flag only
-correctness/requirement/invariant gaps with file:line evidence, no style.
-
-**Variant sets — human in the loop.** When the iteration was built as a variant
-set (multiple `(harness, model)` lanes over one frozen spec), judge every
-variant against the same frozen AC, then **do not pick the winner unilaterally**
-— assume the human wants to be involved in selection. Present the head-to-head:
-per-variant gate results plus the deltas that decide it (correctness/invariants,
-idiomaticity + house-style, tests, user-facing behavior), with your
-recommendation and its reasoning. Let the human choose (`AskUserQuestion` or a
-checkpoint); you then execute the promote/merge they pick. Surface a
-recommendation — the call is theirs. (A standing handoff that pre-delegates the
-pick still gets the comparison surfaced before you act on it.)
-
-### 3. Research fan-out (optional — most iterations skip this)
-
-Two scales, two routes:
-
-- **Discovery scale** — brainstorming what to build, technology selection,
-  state-of-the-art surveys → invoke the `/architect-research` skill (a scout
-  researcher maps the topic, the orchestrator designs topic-specific parallel
-  researcher lanes, claims verified against sources, synthesized into a cited
-  report). Its report then distills into `architecture/BRIEF.md` §sections when
-  it is project-scope (a durable contract that spans iterations), or the
-  iteration's **Grounds** section when it is iteration-scope.
-- **Iteration scale** — run the inline fan-out below only when at least one
-  trigger holds: (a) the iteration depends on external APIs, libraries, or
-  versions not already used in the target repo; (b) a narrow approach choice
-  needs facts neither you nor the repo has; (c) the human asked
-  (`/architect research: <question>`). Otherwise skip — the builder's
-  verify-against-reality requirement already covers routine API checks, and
-  researching well-understood iterations is pure cost.
-
-When a trigger fires, read `research.md` next to this file and follow it:
-3–5 narrow non-overlapping questions → parallel detached `pi -p --mode json`
-researchers (read-only by prompt contract; web via pi's loaded web tools) in
-the background → you
-adversarially verify the load-bearing claims → you write the iteration's
-**Grounds** section with citations and commit it. Researchers gather; you judge
-and write Grounds. Findings without a source URL don't enter Grounds.
-
-### 4. Spec the next iteration
-
-One-PR-sized. Run `architect new <name>` to scaffold
-`architecture/I<NN>-<name>.md` (it allocates the next ordinal **at spec-time** and records the
-iteration in `space.yaml`). The iteration index in `ARCHITECT.md` holds only scaffolded
-iterations — planned/queued work lives un-numbered in the ordered Backlog until it is
-about to be specced. Pre-numbering planned work forces renumber churn every time priorities
-reshuffle; the ordinal belongs to the work only once `architect new` is called.
-
-Then write the **Specification** section with
-`architect section <name> specification --from <file>` — the full delegation
-contract, self-contained:
-
-- **Objective** — what to build and why (give the reason, not just the ask).
-  Cite **BRIEF §N** for durable context and a Grounds section for
-  iteration-local research, rather than restating either.
-- **Output format** — what the builder reports: raw tables, numbers, commit
-  SHAs, test output paths. No interpretation.
-- **Tool guidance** — the exact verification commands for the target repo, and
-  the specific APIs/formats/versions the builder must verify against the live
-  dependencies *before* writing code.
-- **Boundaries** — files it may touch, files it must not, explicit out-of-scope
-  list, "no placeholders; search before implementing", no refactors beyond the
-  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. 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 same boundary is stated twice more — the lane-prompt's
-  may-touch list, and the scope gate that checks the lane's diff at judge
-  time — and all three must be one exhaustive enumeration: every file listed,
-  no glob standing in for the list; the scope gate's pattern is that
-  enumeration exactly; the prompt's list is generated from it. Consistency is
-  not completeness — three statements drawn from one too-narrow search agree
-  and are wrong together — so before freezing a criterion that requires an
-  identifier to change name, grep the whole repo for it and confirm every hit
-  falls inside some lane's touch set; `architect rehearse` reports this
-  asymmetry, so the check is read, not remembered. Either defect surfaces
-  only after the freeze, where hard rule 3 forbids widening the declaration:
-  `integrate` refuses a correct lane, or the stray hit breaks a file no lane
-  may legally fix. 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). Three first-class patterns — runnable recipes in `dispatch.md`: **parallel +
-  fast-follow** (disjoint lanes integrate first; a fast-follow lane off
-  `project/<slug>` carries the seam — see `### Parallel + fast-follow`),
-  **serial deferred judgment** (iterations run to gates-green with `architect
-  verdict` withheld; one later batch session judges each against its own frozen
-  AC — see `### Serial deferred judgment`), and **long-running sweep** (a lane
-  launches its own long detached process, ends its session at a sanctioned
-  pending status, and a later session in the same worktree audits it once it
-  exits — see `### Long-running sweep` in `dispatch.md`).
-- **Effort call** — thinking budget set per dispatch with `architect dispatch
-  --effort <level>`, normalized to the canonical
-  `off`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max` set and passed straight
-  through to pi's `--thinking` (each model's `thinkingLevelMap` in
-  `~/.pi/agent/models.json` clamps it further per model); the escalation
-  keywords `think hard` … `ultrathink` still work in-prompt;
-  default unattended builder work high, downgrade a routine, tightly-specified
-  lane (record which and why). Levels and mechanics: `dispatch.md`.
-
-**Spike (probe) iterations.** When the open question is too uncertain for a
-build — the repo can't answer it and routine API-verification won't resolve it
-— spec a *spike* (probe) instead of a build iteration. A spike is
-investigate-only: its deliverable is a **recommendation**, not merged behavior.
-Its lane reads, experiments in throwaway scratch (never the worktree), and
-writes a structured recommendation to its scratch report; there is usually
-nothing to integrate. Acceptance Criteria are **read-bound** — gates are
-minimal (at most suite-green confirming the probe broke nothing), because the
-proof is the architect reading the recommendation against the question the spike
-was set, not a runnable check; the AC names that question. The spike verdict
-uses **ADOPT / REVISE / REJECT** (not KILL/CONTINUE): the architect transcribes
-the recommendation into Builder Report, then the Verdict records the
-disposition and, if adopted, names the follow-up build iteration it spawns. A
-spike's CONTINUE means "recommendation accepted + disposition recorded." This
-is distinct from discovery-scale research (`/architect-research`, which surveys
-a whole topic): a spike is one iteration-sized, decision-oriented probe run
-through the normal builder/lane machinery.
-
-Then write the **Acceptance Criteria** section — prose conditions (AC1, AC2, …)
-that the architect judges against, followed by a fenced ` ```gates ` block of
-runnable checks (each gate carries `id`, `ac`, `cmd`, and `expect`; `cwd` is
-optional). Calibrate each criterion's precision to the property it asserts —
-R4 ("grade the outcome, not the path") applied at authoring time, the only time
-it can be applied, because a frozen criterion is never loosened after results.
-Two kinds of criterion, two calibrations:
-
-- A criterion asserting a **property that must hold** is bounded from one side
-  only — the side the defect is on — freezing a floor, not an equality, so an
-  addition or change the lane discovers stays legal. "Exactly eight runtime
-  dependencies" freezes today's snapshot and outlaws the ninth a transitive
-  need later forces; the property it stood in for was "declares everything it
-  requires."
-- A criterion whose **number is itself the deliverable** may be exact — there
-  the precision is the point (a touch-set boundary, a wire-format constant).
-
-Writing the first kind as the second is the defect: it leaves the lane no
-sanctioned path except degrading the artifact to fit the number.
-
-Say, too, what each gate proves: a presence-grep gate on prose is a
-**tripwire**, never the proof — it shows a keyword landed, not that the thing
-works — and its criterion should say which it is, leaving the substance
-architect-read.
-
-**Pre-freeze check** — run against the drafted AC in the minutes before
-`architect freeze`, while a bad criterion still costs nothing:
-
-- **snapshot** — no AC or gate hard-codes a count, name-set, or byte-identity
-  that is merely what was known at freeze time;
-- **control** — every baseline or regression claim had its control actually run
-  in this session, not recalled or assumed;
-- **mechanism** — no AC names a *how* (an API signature, a helper, a file
-  layout) where the *what* is the requirement, such that a better shape the
-  lane discovers would be forbidden;
-- **interface** — any CLI surface a Specification names — a verb, a flag
-  spelling, a subcommand — is executed once before it is frozen: a frozen
-  interface is only safe if it is implementable, which is the assumption
-  every code/prose lane split rests on. No verb backs this item yet — unlike
-  dry-run, it is a discipline run by hand;
-- **dry-run** — `architect rehearse <name>`: it runs the drafted gates from
-  the working tree through the same execution path `architect gate` uses
-  (`/bin/sh`, same run-dir resolution, same evaluator) and classifies each —
-  **RED**, a clean non-zero: the gate discriminates, the healthy pre-freeze
-  result; **GREEN**, passes on base: a declared regression guard, or a gate
-  that measures nothing; **BROKEN**, a 127 / syntax error / timeout —
-  advisory, because a correct RED can look broken (`grep -q x` on a file the
-  lane will write exits 2): the tool names the suspicion, you confirm;
-  **EMPTY**, no gates or an untouched placeholder. Every non-EMPTY run writes
-  a full transcript (every gate's command, dir, exit code, verdict, reason,
-  complete stdout+stderr) under `build/rehearse/`, prints its path, and ends
-  with a bounded summary — one line per gate plus a tally — so a rerun is
-  never needed just to re-see output the terminal already trimmed. `--record`
-  emits a paste-able provenance block for the AC preamble. It reports; which
-  GREENs are guards and which are defects stays your call.
-
-Then run `architect freeze <name>`. Freeze requires a fresh rehearsal stamp —
-`rehearse` records one in `space.yaml`, keyed to the gates block's content, so
-editing a gate afterward stales it; `architect freeze --skip-rehearse REASON`
-(non-empty, recorded) is the escape valve. The stamp records that you looked,
-never that gates passed — an all-RED and an all-GREEN run stamp identically.
-What must be frozen before
-dispatch is the Acceptance Criteria: `architect freeze` lints the gates block
-(absent or empty gates is allowed but warns; malformed fails), commits any
-pending content in the frozen region (Grounds/Specification/Acceptance Criteria)
-in one freeze commit, records the `freeze_sha` in `space.yaml`, and prints the
-frozen AC back; **that commit is the freeze** ❄️ and is the last thing before
-dispatch. You needn't sequence Grounds and Specification into separate commits
-first — the freeze snapshots the whole frozen region and refuses to re-freeze
-once a frozen section changed afterward.
-
-### 5. Dispatch (one fresh `pi -p` per lane, worktree-isolated)
-
-Per the mechanics in `dispatch.md`. The lane lifecycle is **declare → rehearse
-→ 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.
-- **Rehearse** — `architect rehearse <iteration>` dry-runs the drafted gates
-  from the working tree (§4's pre-freeze check), resolving its run dir from the
-  drafted ` ```lanes ` block, and stamps `space.yaml`; `freeze` refuses without
-  a fresh stamp.
-- **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
-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
-<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 `pi -p --mode json` argv, pins the model, copies the vendored
-builder-guard into the lane's build dir and injects it with `-e`, and streams
-pi's JSONL event stream 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**
-shell `&`. The harness keeps each lane alive for its full run and notifies you
-per lane; a `for … & done` launcher instead orphans the lanes and the harness
-reaps them all at once (see `dispatch.md`). Each lane builds only its declared
-files and writes raw results to `build/<id>-<lane>/report.md` — it never
-touches `architecture/`, so lanes never collide and the Acceptance Criteria
-stay untouchable.
-
-Do not block — end the turn or do other judgment work; long runs (30–60 minutes) are
-normal. Print the lane-prompts too, so the human can run any lane in an
-interactive `pi` session instead. Whenever you return to a running lane,
-check liveness: the lane's `run.jsonl` must still be growing. If it has been
-silent 15+ minutes on one in-flight command, follow "Stall detection and
-rescue" in `dispatch.md` — kill the stuck child process, not the run.
-
-When all lanes complete, **the dispatch session's job is done** — babysit
-liveness per `dispatch.md` but do not run gates, transcribe evidence, integrate
-lanes, or write the Verdict. Hand off to a fresh judging session (§6).
-
-### 6. Post-flight, judge, and integrate (judging session)
-
-A fresh judging session — not the session that dispatched (see §1 and §5) —
-opens with the **MECHANICAL POST-FLIGHT CHECKS** and owns everything through the
-Verdict and integration. Because this session did not dispatch, §1's
-fresh-session-judgment is intact: it is the correct session to evaluate results.
-
-`architect verify <iteration>` REPORTS (it never judges) per lane: frozen
-sections untouched, no builder commits, scratch report present, in-bounds.
-Confirm each yourself with evidence: (a) the scratch report has raw results
-only, (b) PHASE 0 disagreements were raised (silent compliance = defect to
-log), (c) the iteration file's frozen sections are untouched — `git diff
-<freeze-sha> HEAD -- architecture/I<NN>-<name>.md` shows no change to
-Grounds/Specification/Acceptance Criteria, (d) `git status` in the worktree
-shows **only files inside the lane's declared set** — an out-of-bounds write
-fails the lane, (e) `git -C <worktree> log <repo-base>..` is empty — a builder
-commit means a tampered worktree (reset and re-dispatch).
-
-**Transcribe** each lane's scratch report into the **Builder Report** section
-with `architect evidence <iteration> --lane <lane>` — it copies
-`build/<id>-<lane>/report.md` **verbatim** (byte-for-byte, no interpretation),
-commits it, and echoes the builder's STATUS line. The builder never wrote into
-`architecture/`; the CLI transcribes, preserving raw-results-only.
-
-**Then integrate** — you decide which lanes pass, the CLI does the git
-mechanics. `architect integrate <iteration> --lanes <passing-set>` commits each
-named lane on its branch and merges it `--no-ff` into the stable
-`project/<slug>` branch (slug derived from `space.title`; persistent and shared
-across all iterations), in order; it **refuses** a lane that left builder
-commits or wrote out-of-bounds, and stops on a merge conflict — which means the
-lane plan wasn't disjoint, a spec defect: kill the conflicting lane and re-spec
-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 provisioned worktrees
-(`architect integrate … --teardown`, or `architect worktree remove <iteration>
-<lane>`), and commit the space. Both refuse per lane when its worktree still
-holds uncommitted work — untracked files included; `--force` overrides and
-discards it. The `--lanes` integration path itself is unaffected, since
-`integrate` commits each lane's work before teardown.
-
-**Run the frozen gates cold** — `architect gate <iteration>` runs the frozen
-gate commands against the integration tree and streams raw output (a runner, not
-a judge). Read the output, check the diff against the Specification and the
-cited BRIEF §sections (per §2), then write the **Verdict** (`architect verdict
-<iteration> continue|kill --from <file>`): disagreement rulings, per-AC
-PASS/FAIL/INVALID, the KILL/CONTINUE call.
-
-At project end, 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 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
-boundaries. No push, no `gh` call by you or the CLI; the human runs the block
-when the project is ready to ship.
+3. **The Acceptance Criteria freeze before results exist** — committed by the
+   spec (interactive mode: by you) *before* dispatch; quote them verbatim from
+   the freeze commit when judging; never edit after results. Any change to
+   Grounds/Specification/Acceptance Criteria since the freeze is an automatic
+   iteration FAIL.
+4. **Nobody grades their own work.** Builders report raw evidence only;
+   gates are run by the judge (a fresh session), whose verdict is a separate
+   pass over the same frozen text.
+5. **Disagreement is mandatory.** Builders must raise PHASE 0 disagreements
+   citing real files; silent compliance = defect. The judge rules on every
+   one: ACCEPT / REJECT / MODIFY + one line why. Flag scope creep and
+   goalpost-moving bluntly.
+6. **Audit every status claim** — against a tool result from the session
+   before reporting it.
+7. **Builders never commit.** Worktree isolation between lanes; the guard
+   denies git writes at dispatch; the authoritative check is an empty
+   `git -C <worktree> log <repo-base>..` post-flight.
+8. **Stop conditions:** instructions conflicting with project docs,
+   irreversible/destructive calls, or scope growth beyond the plan →
+   checkpoint to the human. Tooling bugs: `architect bug-report`.
+
+Space setup (first time): `space new "Project Name" -r org/repo …`, then
+`architect init` to scaffold `architecture/ARCHITECT.md`. If `ARCHITECT.md` is
+missing, run `architect init`. Keep the handoff a short TOC (~150 lines);
+per-iteration detail lives in the iteration file. The project brief
+(`architecture/BRIEF.md`) is the durable §-numbered contract — cite it as
+BRIEF §N; edits to a §section are logged decisions, never silent drift.
+
+Iteration lifecycle and the frozen section discipline (Grounds /
+Specification / Acceptance Criteria / Builder Prompt / Builder Report /
+Verdict, one commit per section via `architect section`, lane plans in the
+fenced ` ```lanes ` block, spike iterations, variant sets) are the same in
+both modes; the only difference is which session does the step. The CLI owns
+persistence — author content in fresh scratch files and hand it over via
+`--from`/`--prompt`/`--stdin`; never edit `architecture/` paths directly.
+
+## Interactive path (optional — on request)
+
+Run the iteration steps in your own session when the human asks for a
+hand-run, wants to babysit, or the coordinator is down. Ground first (as
+above), then per iteration: arbitrate any open disagreements from the last
+iteration's Builder Report; **spec the next iteration**
+(`architect new <name>`, then Specification via `architect section` —
+objective, output format, tool guidance, boundaries, lane plan, effort call);
+**write the Acceptance Criteria** (prose ACs + fenced ` ```gates ` block;
+calibrate precision per criterion — freeze floors, not snapshots; run
+`architect rehearse <name>` and address every finding — RED is the healthy
+pre-freeze verdict; interface-check every named CLI surface by executing it
+once); **freeze** (`architect freeze <name>` — the freeze commit is the last
+thing before dispatch); **provision and dispatch** lanes
+(`architect provision`, `architect dispatch <iteration> <lane> --prompt
+<scratch file>` — own background Bash call per lane; mechanics, recipes
+(parallel + fast-follow, serial deferred judgment, long-running sweep), stall
+rescue, and the lane-prompt template are in `dispatch.md`); then hand the
+judging to a **fresh session** (§1 of fresh-session judgment holds — the
+session that dispatched never judges): `architect verify` →
+`architect evidence` → cold `architect gate` → read the diff →
+`architect verdict` → `architect integrate --lanes <passing> --teardown` →
+update the ARCHITECT.md index.
+
+Variant sets: judge every variant against the same frozen AC, then do not pick
+the winner unilaterally — surface the head-to-head with your recommendation;
+the human chooses. High-stakes iterations: add an adversarial review pass
+before the verdict (command in `dispatch.md`).
+
+## After a loop lands
+
+Landing is yours, not the CLI's. Per touched repo: write the PR body from the
+iteration verdicts, the integrated diff, and the BRIEF — to a fresh
+`build/land/<repo>-pr-body-<yyyymmdd-hhmm>.md` — and present the paste-and-run
+block (cd, `git push -u origin project/<slug>`, `gh pr create`). Releases of
+the space-architect gem itself are tag-driven (annotated `vX.Y.Z` tag on main →
+GitHub Action publishes to rubygems). Post-landing rollout for spaces running
+the loop's own tooling: rebuild + force-install the gem from the project
+branch, `architect install-skills`, `architect install-extensions`,
+`architect install-agents` — a config
+that moved ahead of the installed CLI rejects every command (the stale-gem
+trap). No push, no `gh` call by you; the human runs the block when ready.
+
+## Research fan-out
+
+Two scales: **discovery scale** (brainstorming, technology selection,
+state-of-the-art) → `/architect-research`. **Iteration scale** — only when a
+trigger holds (external API/version dependency; a narrow approach choice
+needing facts; the human asked) → 3–5 narrow parallel researchers,
+adversarially verified, findings with source URLs only; see `research.md`.
+
+## Command reference — pre-loaded help
+
+Trimmed `--help` output of every command the loop prescribes (the universal
+`--color/--colors/--help` options are cut; every command takes `[SPACE]`,
+default `$PWD`). Run `architect <command> --help` for the untrimmed text.
+
+```text
+architect new ITERATION
+  Scaffold the next iteration file (architecture/I<NN>-<iteration>.md)
+  -m, --message / --message-from FILE    commit message (subject after canonical prefix)
+
+architect section ITERATION SECTION      # SECTION: grounds, specification,
+                                         # acceptance-criteria, prompt, verdict
+  --from FILE | --body | --stdin         section body (author in fresh scratch files)
+  --append --lane LANE                   append a per-lane subsection (Builder Prompt/Report)
+  --force                                write a frozen section (pre-dispatch only)
+
+architect rehearse ITERATION
+  Dry-run the DRAFTED gates; classify RED/GREEN/BROKEN/EMPTY; never judges
+  --record                               paste-able provenance block for the AC preamble
+
+architect freeze ITERATION
+  Freeze the frozen region; record the freeze SHA in space.yaml
+  --skip-rehearse REASON                 escape valve (recorded); bare freeze refuses
+                                         without a fresh rehearsal stamp
+
+architect provision ITERATION
+  Materialize declared lanes (worktree + lane/<id>-<lane> branch)
+  --base REF                             cut exactly this ref (skips the sync)
+  --lane LANE                            provision only this lane
+
+architect dispatch ITERATION LANE
+  Dispatch a builder (streams to build/<id>-<lane>/run.jsonl)
+  --prompt FILE                          lane prompt (copied to build/<id>-<lane>/prompt.md)
+  --model ID                             pin the builder model (full id, never an alias)
+  --effort LEVEL                         off|minimal|low|medium|high|xhigh|max
+  --timeout SECONDS                      wall-clock (0 disables; default 4h)
+  --detach                               return immediately with PID
+
+architect verify ITERATION
+  Post-flight mechanical lane checks (reports only, no judgment)
+
+architect evidence ITERATION
+  Transcribe a lane's scratch report VERBATIM into Builder Report
+  --lane LANE                            per-lane subsection
+
+architect gate ITERATION [LANE]
+  Run the frozen gate commands; report PASS/FAIL; writes the full transcript
+  to build/gate/<id>-<ts>.md and prints the path (the terminal report is
+  bounded — the file is the record)
+
+architect integrate ITERATION
+  Merge the passing lanes --no-ff into project/<slug>, in order; stops on conflict
+  --lanes A,B                            you decide the passing set
+  --teardown                            remove worktrees + lane branches after
+
+architect verdict ITERATION continue|kill
+  Record the iteration verdict; --from FILE carries the body
+  (disagreement rulings + per-AC rollup)
+
+architect status                        iteration/verdict table (read-only)
+architect cost                          loop spend + latency from pi session artifacts
+  --json --by-iteration --latency --precise --since WHEN --space PATH
+architect looplog [--list|--replay|--all|--space PATH]
+  Follow every active loop run in this space, live (--list: inventory only)
+architect runlog [FILE]
+  Pretty-print a pi run.jsonl (FILE or stdin; RUNLOG_LIMIT, NO_COLOR honored)
+architect install-skills                 bundled skills for a harness (--provider)
+architect install-extensions             reconcile the architect-loop pi extension package
+architect install-agents                 role playbooks to ~/.pi/agent/agents (pi)
+architect bug-report                     prefilled GitHub issue template for the CLI
+```
 
 ## Maintenance
 
-Re-read this skill against each new model generation and delete what the models
-now do unprompted — over-prescription degrades current-model output. The rules
-above are invariants; everything else is prunable.
+Re-read this skill against each new model generation and delete what the
+models now do unprompted — over-prescription degrades current-model output.
+The rules above are invariants; everything else is prunable.