space-architect 1.2.0 → 1.3.0

data/skill/architect/dispatch.md

@@ -0,0 +1,308 @@
+# Builder dispatch reference
+
+Verified against the `claude` CLI (Claude Code) headless mode, June 2026. The
+builder is `claude -p` (`--print`, the non-interactive headless mode) pinned to
+`claude-sonnet-4-6` — the *same binary the architect runs, one tier down*. Key
+facts the skill encodes: lane-prompts go in on **stdin** (Claude Code has no
+`@file`, and a big quoted lane-prompt as a shell argument gets mangled); the
+model is pinned with `--model claude-sonnet-4-6` (the `sonnet` alias floats to
+the latest Sonnet — pin the full id); there is **no `-C`/working-dir flag**, so
+per-lane dispatch `cd`s into the worktree; permissions are the **tool
+allow/deny lists** (`--allowedTools`/`--disallowedTools`) plus
+`--permission-mode`, not a sandbox; web access is the built-in
+`WebSearch`/`WebFetch` tools (no extension to install).
+
+**The one load-bearing difference from the Codex design:** Codex's
+`--sandbox workspace-write` made `.git` physically read-only. Claude Code has
+**no automatic filesystem sandbox** in headless mode (the sandbox is opt-in via
+settings, off by default), so `.git` is not hardware-protected. "Builders never
+commit" (hard rule 7) is now enforced in three layers, weakest to strongest:
+(1) a runtime first line — deny the git-write tools with
+`--disallowedTools 'Bash(git commit:*)' …`; (2) worktree isolation between
+lanes; (3) the authoritative check — an architect post-flight
+`git -C <worktree> log <repo-base>..` that must be empty. The deny rules are
+not airtight (a builder can shell out — `sh -c 'git commit …'` — past the
+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
+(`echo ok | claude -p --model claude-sonnet-4-6 --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 `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.
+
+## Canonical dispatch — `architect dispatch <iteration> <lane>`
+
+The canonical path is `architect dispatch <iteration> <lane>`. The tool
+assembles the canonical `claude -p` argv, pins the model to `claude-sonnet-4-6`,
+reads the lane prompt from `build/<id>-<lane>/prompt.md` 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 multi-hour
+run.
+
+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:
+
+```bash
+# single-lane iteration — run from the space root
+architect dispatch <iteration> <lane>
+```
+
+For multi-lane iterations, create worktrees first (one per lane), then dispatch
+each lane from its worktree:
+
+```bash
+# per lane:
+architect worktree add <repo> <iteration> <lane> [--base <repo-base>]
+architect dispatch <iteration> <lane>
+```
+
+`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`.
+
+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*
+process: it returns the instant it has spawned the lane children, the harness
+reaps those now-orphaned `claude` processes, and every lane dies at once with no
+`result` — partial diffs, no reports (this exact failure has happened: three
+lanes killed at the same second, zero output). One blocking dispatch per
+background Bash tool keeps each lane attached to a harness-tracked task that
+survives the full multi-hour run and reports completion per lane.
+
+### What the tool runs under the hood
+
+`architect dispatch` is equivalent to this — documented here for transparency
+and as the manual fallback:
+
+```bash
+# write prompt to build/<id>-<lane>/prompt.md first, then:
+( cd build/<id>-<lane>/wt && \
+  claude -p --model claude-sonnet-4-6 \
+    --permission-mode acceptEdits \
+    --allowedTools 'Read,Edit,Write,Grep,Glob,Bash,WebSearch,WebFetch' \
+    --disallowedTools 'Bash(git commit:*),Bash(git push:*),Bash(git reset:*),Bash(git merge:*),Bash(git rebase:*),Bash(git checkout:*),Bash(git branch:*)' \
+    --output-format stream-json --verbose \
+    --max-turns 200 \
+    < <space>/build/<id>-<lane>/prompt.md \
+    > <space>/build/<id>-<lane>/run.jsonl 2>&1 )
+```
+
+`acceptEdits` auto-approves file writes; listing `Bash` in `--allowedTools`
+auto-approves shell commands so the run never blocks on a prompt; any tool *not*
+on the allow list is denied rather than prompted in `-p` mode (so the builder
+can't wander outside its toolset), and the `--disallowedTools` deny rules win
+over the allow list (deny always takes precedence) as the runtime first line
+against commits. Redirect stderr (`2>&1`) into the run-log so a dispatch error
+lands somewhere instead of vanishing.
+
+### Integration (architect-only, after per-lane post-flight passes)
+
+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 integrate <iteration> --lanes <passing-set> --teardown   # or remove worktrees + lane branches after
+```
+
+`architect integrate` commits each named lane on its branch and merges it
+`--no-ff` into the repo's `lane/<iteration>` integration branch, in order. 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 conflicts. It runs **no gates and makes no
+verdict** — `architect gate` streams the raw gate output for you to judge.
+
+Under the hood / manual fallback (one lane shown):
+
+```bash
+git -C repos/<repo> checkout -b lane/<iteration> <repo-base>
+git -C build/<id>-<lane>/wt add -A
+git -C build/<id>-<lane>/wt commit -m "lane <lane>: <what>"
+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>
+```
+
+## Operating guidance
+
+- Background each lane as its own harness task and let the **per-lane
+  completion notification** bring you back (multi-hour runs are normal); read
+  `build/<id>-<lane>/run.jsonl` and the repo state afterwards. Do not write a
+  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).
+- Pin the model explicitly. The tool does this automatically (`--model
+  claude-sonnet-4-6`). The `sonnet` alias floats to the latest Sonnet — fine
+  interactively, but automations pin the full id so a model bump can't silently
+  change builder behavior mid-project.
+- Effort = thinking budget. Claude Code has no per-invocation effort flag the
+  way Codex exposed `model_reasoning_effort`; the builder sets thinking depth
+  **in the block** via the escalation keywords (`think` < `think hard` <
+  `think harder` < `ultrathink`), or you floor it with the `MAX_THINKING_TOKENS`
+  env var on the dispatch. Default unattended builder work to a high budget
+  (open the block with "Think harder…"); downgrade a routine,
+  tightly-specified lane to "think hard" (record which and why in the spec).
+- **Builders never commit, and the architect verifies it.** Claude Code has no
+  sandbox to make `.git` read-only, so this is enforced by the deny rules at
+  dispatch *and* checked after the run: before integrating a lane, confirm
+  `git -C build/<id>-<lane>/wt log <repo-base>..` is empty and
+  `git -C build/<id>-<lane>/wt status` shows only files inside the lane's
+  declared set. A commit or an out-of-bounds write fails the lane — reset and
+  re-dispatch (lanes are cheap, hard rule 7).
+- Same-iteration follow-up (e.g. answering PHASE 0 disagreements after the
+  human rules): from the lane's worktree, `claude -p --continue "<rulings +
+  proceed>"` resumes that worktree's most recent session with full context —
+  sessions are scoped per directory, so `--continue` (`-c`) is deterministic
+  even with parallel lanes. (Alternatively pin `--session-id <uuid>` at
+  dispatch and resume with `--resume <uuid>`.) Resume the **same way you
+  dispatch** — one background Bash tool call per lane, each a single blocking
+  `claude -p --continue …`, never a `&` loop (a `&` launcher orphans the
+  resumed lanes exactly as it does fresh ones). Never resume across iterations —
+  every iteration gets a fresh context.
+- Cross-model review gate (high-stakes iterations): the architect is Opus 4.8
+  and the builder is Sonnet 4.6 — both Claude Code, so this is a
+  cross-*tier* read inside one lab, not cross-vendor (see `DESIGN.md` R3). The
+  architect (Opus) reading the diff is already the stronger-model fresh-context
+  pass. For an extra adversarial pass, pipe the instruction + diff to a fresh
+  read-only reviewer:
+  ```bash
+  { echo "Review this diff against the spec. Flag ONLY correctness/requirement/invariant gaps with file:line evidence. No style."; \
+    git -C <repo-root> diff <base>...HEAD; } \
+  | claude -p --model claude-sonnet-4-6 --allowedTools 'Read,Grep,Glob'
+  ```
+- `build/` is already gitignored by the space, so no extra `.gitignore` entry
+  is needed. Scratch never reaches the space repo; only `architecture/` is
+  committed.
+
+## Stall detection and rescue
+
+A dispatched run is STALLED when its `run.jsonl`
+(`build/<id>-<lane>/run.jsonl`) has not grown for 15+ minutes AND the last
+event is an in-flight `Bash` tool call (a `tool_use` for `Bash` with no
+matching `tool_result` yet). Silent gaps between events are normal model
+thinking; a shell command that should take seconds sitting in flight for 15+
+minutes is not.
+
+Diagnose before killing: find the command's child under the `claude` PID
+(claude → shell → child). Hot-spinning (high CPU) or blocked (zero CPU and none
+of its expected side effects on disk) — hung either way.
+
+Kill the NARROWEST thing: the stuck child process, not the `claude` run. The
+command returns a failure to the builder, which adapts with its full context
+intact. Kill the whole run only when the builder re-enters the same hang or the
+worktree is broken; then discard the lane and re-dispatch (hard rule 7).
+
+Claude Code runs the `Bash` tool directly with no sandbox, so the Codex-era
+sandbox-specific hang sources don't apply — but long-running and interactive
+commands still hang an unattended run. Spec consequence: give every potentially
+long command an explicit timeout in the lane-prompt (the `Bash` tool also takes
+a per-call timeout), cap the run with `--max-turns` as a loop backstop, steer
+builders toward the repo's existing test fixtures over hand-rolled long-running
+harnesses, and when a gate needs a runtime that can't run unattended
+(interactive prompts, servers without a timeout), have the builder record the
+exact failure as a disagreement/blocker and verify what it can — gate verdicts
+are architect-run anyway (hard rule 4). Write the gate file anticipating this.
+
+## Manual alternative (human-driven)
+
+Paste the lane-prompt into an interactive `claude` session (no `-p`). Claude
+Code's agent loop runs plan→act→test against the block's stopping condition
+while you watch and steer — approve tools as they come, or set `/permissions`
+first. Use when the human wants to babysit a run.
+
+## Lane-prompt template
+
+```
+Execute the architect spec below. Operating rules:
+
+PHASE 0 — Before any code: reply with your plan and EVERY disagreement you have
+with this spec, with reasons, citing real files in this repo. Silent compliance
+is a failure. Silent scope additions are a failure. If you have no
+disagreements, state what you checked before concluding the spec is sound.
+Verify the named APIs/formats/versions against the live dependencies before
+planning around them.
+
+PHASE 1 — Treat the shared contracts (schemas/interfaces) named in the spec,
+and the repo's existing public interfaces, as FROZEN: do not change them —
+other lanes depend on them. You have no access to the space's architecture/
+directory; the architect owns it. The ACCEPTANCE CRITERIA below are frozen —
+verify your work against them; never weaken or work around them.
+
+PHASE 2 — Build YOUR LANE ONLY: exactly the files listed in BOUNDARIES. You
+are one of several parallel lane agents working in isolated worktrees; files
+outside your lane belong to other agents — touching them fails your lane.
+No placeholder implementations — search the codebase before implementing;
+full implementations only. Write IDIOMATIC, house-consistent code: read the
+neighbouring code and match its conventions (naming, guards, predicates,
+error/persistence idioms, the language's expressive collection/enumerable
+forms); well-factored and DRY-ish; terse but clear; pragmatic, not clever — the
+smallest change that does the job, no abstraction it doesn't need. Consistency
+with the surrounding code is part of correctness here: a change that works but
+fights the house style (or introduces an inconsistency a careful reader of this
+repo would never write) is not done. Tests stay simple and terse, exercising
+public behavior, no mock/stub of the class under test. Verify your work by
+running the acceptance criteria's gate commands and record the verbatim output. Do NOT commit and do NOT run any
+git write command (commit/add/branch/reset/checkout) — the architect commits
+and merges after verification, and verifies you made no commits. Do NOT delete
+lock files or escalate privileges if a command fails; record the exact error
+and continue. Give every potentially long command an explicit timeout; if a
+runtime will not start unattended (interactive prompt, server with no timeout),
+record the exact failure in your report and route around it — never busy-wait
+or retry in a loop. When done, write your report to the scratch file given to
+you, build/<id>-<lane>/report.md (an absolute path outside your worktree),
+with RAW results only — tables, numbers, command output — no interpretation, no
+"promising". Every status claim must be backed by a command result from this
+run. Keep the report compact — tables and numbers, not prose. End it with
+exactly one status line: STATUS: COMPLETE | COMPLETE_WITH_CONCERNS (list them)
+| BLOCKED (exact blocker + what you tried). Verdicts belong to the architect
+and the human. Persist until your lane is fully handled end-to-end; do not stop
+at analysis or partial fixes.
+
+=== OBJECTIVE (and why) ===
+...
+
+=== OUTPUT FORMAT ===
+...
+
+=== TOOL GUIDANCE (verification commands; verify-against-reality list) ===
+...
+
+=== BOUNDARIES (may touch / must not touch / out of scope) ===
+...
+
+=== DISAGREEMENT RULINGS (from last session) ===
+...
+
+=== ACCEPTANCE CRITERIA (frozen — the architect re-runs these to judge; verify
+against them, do not edit or work around) ===
+...
+```
+
+## Builder-side standing setup (one time per machine/repo)
+
+- The builder is the same `claude` binary as the architect, one tier down —
+  nothing extra to install. `architect dispatch` pins the model per dispatch
+  (`--model claude-sonnet-4-6`); a `~/.claude/settings.json` `"model"` default
+  is fine interactively, but automations pin it explicitly so a default can't
+  silently swap the builder.
+- Repo `CLAUDE.md` is the builder's standing context — Claude Code loads it
+  root-down automatically. Put exact build/test commands and repo gotchas there;
+  the loop's PHASE rules stay in the dispatch block so they version with the
+  skill. (Claude Code does **not** auto-read `AGENTS.md`; if the repo keeps its
+  build/test docs there, add `@AGENTS.md` to `CLAUDE.md` to pull it in.)
+- The builder is a bare `claude -p` over the block — it is not invoking the
+  `/architect` skills, the block is its entire instruction set. (`--bare` would
+  give a leaner builder context but also drops `CLAUDE.md`/skills/hooks — keep
+  `CLAUDE.md`, so skip `--bare` unless the repo has no standing build/test doc.)
+- Billing: headless `claude -p` draws on the Agent SDK credit pool on your
+  Claude plan (separate from interactive usage limits since June 15 2026).
+  There's no per-window quota that dies mid-run the way a chat session can, but
+  a long parallel fan-out does spend that pool. The architect runs as your
+  interactive Claude Code session.

data/skill/architect/research.md

@@ -0,0 +1,89 @@
+# Research fan-out reference
+
+Read this only when a research trigger fires (see SKILL.md step 3). The
+fan-out uses `claude -p` (Sonnet 4.6) as parallel web-research subagents —
+read-only (no `Edit`/`Write`/`Bash`), built-in `WebSearch`/`WebFetch` — and
+the architect keeps all judgment: it verifies the load-bearing claims and writes
+the iteration's **Grounds** section itself.
+
+## Fan out
+
+Decompose the question into 3–5 narrow, NON-OVERLAPPING research questions.
+Cover different angles, not the same angle five times — typical split:
+official docs/reference, changelog/breaking changes, community failure reports,
+alternatives/comparisons, security/operational constraints.
+
+One fresh `claude -p` per question, each launched as its own **background Bash
+tool call** (`run_in_background`) — one call per researcher, not a shell `&`
+loop (a `&` launcher orphans the researchers and the harness reaps them all at
+once; same trap as builder dispatch). The researcher toolset is read-only
+(`Read,Grep,Glob`) plus the web tools (`WebSearch,WebFetch`) — no
+`Edit`/`Write`/`Bash`, so it cannot touch the repo. Capture the final report
+by redirecting stdout (the report *is* the text result in the default `text`
+output format):
+
+```bash
+claude -p --model claude-sonnet-4-6 \
+  --allowedTools 'Read,Grep,Glob,WebSearch,WebFetch' \
+  --max-turns 40 \
+  < build/research/<NN>-<topic>.prompt.md \
+  > build/research/<NN>-<topic>.md
+```
+
+Write each research-prompt to a `.prompt.md` file and feed it on stdin, never
+as a shell argument — a quote-mangling shell will corrupt a big prompt; the
+stdin redirect injects it verbatim.
+
+- Read-only by toolset: with only `Read,Grep,Glob,WebSearch,WebFetch` on the
+  allow list and nothing else granted, any write/bash call is denied — the
+  researcher can't touch the repo. Its report is the redirected stdout.
+- Web comes from the built-in `WebSearch` and `WebFetch` tools — no extension
+  or key. Launch ONE canary researcher and confirm it actually fetches live URLs
+  before fanning out. Restrict domains with `WebFetch(domain:…)` allow rules in
+  prompt-injection-sensitive repos.
+- Thinking budget: keep research at a modest level (a plain block, or "think
+  hard") — research is coverage work; deep thinking buys nothing here. Synthesis
+  happens on the architect's side.
+- Scope each researcher to ≤5 subjects and put hard context rules in the
+  research-prompt (snippet over page; quote ≤2 sentences; stop the moment you
+  can answer) — a researcher that fills its context window dies without emitting
+  its report. Bisect and re-dispatch dead lanes; don't re-run as-is.
+
+## Research-prompt template
+
+```
+You are a web research agent. Answer ONE question. Do not write code, do not
+make recommendations — judgment belongs to the architect who reads your output.
+
+QUESTION: <one narrow question>
+
+OUTPUT FORMAT — a markdown report:
+- Findings as bullets. EVERY finding carries: source URL, source date (if
+  shown), the exact figure or a short direct quote, and a confidence tag
+  (high = primary source / med = reputable secondary / low = single blog or
+  forum post).
+- Prefer primary sources (official docs, changelogs, release notes, source
+  code) over blog posts. Record exact version numbers and dates.
+- When sources disagree, report the disagreement — do not resolve it.
+- If you cannot find evidence for something, write NOT FOUND — never infer or
+  fill gaps from prior knowledge without flagging it as such.
+- End with: the 2-3 findings most likely to change an implementation decision.
+```
+
+## Gather (architect — this is your work, not another agent's)
+
+1. Read every findings file in `build/research/`.
+2. Identify the **load-bearing claims** — facts the spec will depend on
+   (an API shape, a version constraint, a limit, a deprecation). Adversarially
+   verify each: cross-check against a second independent source or the live
+   dependency itself. Discard single-source low-confidence claims or mark them
+   as open questions.
+3. Write the iteration's **Grounds** section
+   (`architecture/I<NN>-<name>.md`): problem, decision + why, requirements,
+   non-goals, verified facts **with citations**, open questions for the human.
+   You write it — researchers gather, the architect judges and decides.
+4. Commit Grounds (`I<NN>: grounds`). Raw findings stay in `build/research/`
+   (gitignored) — only the distilled, cited Grounds section is repo memory.
+5. The iteration's Specification cites Grounds instead of restating it; the
+   builder's PHASE 0 is expected to challenge Grounds' claims like anything
+   else.

data/skill/architect-research/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: architect-research
+description: >
+  Discovery-scale research harness: a cheap scout researcher maps the topic,
+  the orchestrator designs topic-specific parallel researcher lanes from the
+  scout report (drawing on a source-class tactics library — academic, repos,
+  production patterns, web, experts), then verifies claims against sources and
+  synthesizes a decision-oriented report. Use when
+  brainstorming a project or feature, choosing a technology, or asked to
+  "research X", "what's the state of the art", "deep research". For narrow
+  slice-level fact checks inside the build loop, /architect handles those inline.
+---
+
+# Architect Research
+
+You are the research orchestrator. Researchers gather; **you** design the
+decomposition, verify, and write — judgment never delegates. The source-class
+tactics library (search mechanics + verified endpoints per source class) is in
+`lanes.md` next to this file; read it when you design lanes.
+
+## Scale before anything
+
+- **Simple fact-find** → answer directly or 1 researcher (3–10 searches).
+  Don't run a harness on a question one search answers.
+- **Comparison / focused question** → 2–4 researchers on distinct
+  perspectives, no scout — you already know the terrain.
+- **Brainstorm / SOTA survey / technology choice** → scout first, then a
+  designed fan-out of 4–6 researchers.
+
+## Procedure
+
+### 1. Scope → brief
+
+If the question is ambiguous, ask at most 2–3 clarifying questions, then
+compress everything into a **research brief**: the question, the decision it
+informs, constraints, and what "answered" looks like. The brief is the north
+star — every later step is checked against it, and it's restated at the top of
+the final report so the reader can audit scope drift.
+
+### 2. Scout, then design the lanes
+
+The surveyed production deep-research systems and 4/5 leading OSS frameworks
+use LLM-designed, topic-specific decomposition rather than a fixed lane
+taxonomy. Lanes are designed per topic, not taken from a template.
+
+**Scout (brainstorm scale only):** dispatch ONE cheap researcher (~10
+searches, same `claude -p` command as step 3) to map the terrain: canonical
+terminology, the 5–10 load-bearing systems/papers/repos, the named people,
+which source classes look rich vs empty, and the topic's natural fault lines.
+The scout returns a map, not findings — discovering the topic's actual
+perspectives from sources substantially increased source diversity in STORM's
+ablations. Skip the scout when you already know the terrain (comparisons,
+fact-finds) — an upfront pass that tells you nothing new is pure latency.
+
+**Design (you, from the scout report):** decompose into 3–6 sub-questions
+along the topic's own fault lines — distinct perspectives, never keyword
+variants of one query. For each lane pick the source-class tactics it needs
+from `lanes.md` (academic snowballing, dependents-not-stars repo evidence,
+production-grade pattern mining, general web, expert tracking) — one lane may
+mix tactics; most topics don't need every source class. Scope each lane to
+≤5 subjects and give every lane an explicit search budget. Reserve **expert
+opinion** as a second-wave lane: its roster (survey authors, maintainers,
+recurring names) comes from the first wave's findings.
+
+Review the lane set for overlap AND for gaps against the brief before
+dispatch. State the plan in a few lines; proceed unless the user redirects.
+
+### 3. Fan out
+
+One fresh researcher per lane, each launched as its own **background Bash tool
+call** (`run_in_background`) — one call per lane, not a shell `&` loop (a `&`
+launcher orphans the lanes and the harness reaps them all at once). Read-only by
+toolset (`Read,Grep,Glob`) plus the web tools (`WebSearch,WebFetch`); the
+report is the redirected stdout:
+
+```bash
+claude -p --model claude-sonnet-4-6 \
+  --allowedTools 'Read,Grep,Glob,WebSearch,WebFetch' \
+  --max-turns 40 \
+  < build/research/<NN>-<lane>.prompt.md \
+  > build/research/<NN>-<lane>.md
+```
+
+Write each lane block to a `.prompt.md` file and feed it on stdin — never as a
+shell argument; a quote-mangling shell will corrupt a big block, the stdin
+redirect injects it verbatim.
+
+(Web comes from the built-in `WebSearch` and `WebFetch` tools — no extension or
+key. With only the read-only + web tools on the allow list, every write/bash
+call is denied, so the researcher can't touch the repo. Launch ONE canary lane
+and confirm it actually fetches live URLs before fanning out. These lane blocks
+also run verbatim as read-only Claude subagents with web search if you'd rather
+keep research inside the architect's own session.)
+
+Every lane block carries the full contract — objective, output format, source
+guidance, boundaries — plus:
+
+- **Search budget** by tier: simple 5, standard 15, deep 25 searches.
+- **Saturation rule**: two consecutive searches yielding no new load-bearing
+  facts → return what you have.
+- **Findings discipline**: every finding has URL + date + exact figure or
+  short quote + confidence tag (high = primary source / med = reputable
+  secondary / low = single blog or forum). NOT FOUND beats inference.
+  Disagreements between sources are reported, never resolved. No
+  recommendations — judgment is the orchestrator's.
+
+### 4. Gap round (max 2 extra rounds, usually 1)
+
+Read all findings. Score coverage against the brief: which sub-questions have
+supported answers? Spawn targeted gap-fill researchers **only** for the
+unanswered ones. This is also where the **expert-opinion lane** dispatches:
+extract the expert roster from the first wave (survey authors, maintainers,
+recurring names) and send the lane-6 researcher after them. Hard stop after
+two refinement rounds — past that you're chasing nonexistent information.
+
+### 5. Verify (your work, against raw sources)
+
+- Extract the **load-bearing claims** — the facts the decision depends on.
+- Require **≥2 independent sources** per load-bearing claim. Independent means
+  independent *origin* — two articles rewriting the same press release are one
+  source.
+- Tag each: **VERIFIED** (≥2 independent agree) / **UNVERIFIED** (<2, no
+  contradiction) / **DISPUTED** (sources disagree — report both positions and
+  *why* they differ: date, method, definition) / **SUSPICIOUS** (contradicts
+  available evidence).
+- **Adversarial pass** on the top claims: search "<claim> criticism",
+  "<X> problems", "<X> vs <alternative>" — actively try to falsify.
+- **Citations are only URLs fetched this session.** Never cite from memory —
+  even search-grounded agents fabricate 3–13% of URLs. Spot-check the
+  load-bearing ones by fetching them yourself.
+- **Recency discipline**: every quantitative or current-state claim carries a
+  source date; prefer the most recent authoritative treatment; date-restrict
+  searches on fast-moving topics. Anything that smells like training-data
+  leakage gets re-verified or cut.
+- **Source hierarchy**: primary (papers, official docs, changelogs, first-party
+  engineering blogs) > reputable secondary > SEO listicles (pointers only,
+  never citations).
+- **Opinion ≠ fact.** Expert opinions are reported as positions — quoted,
+  dated, conflict-of-interest flagged — and never count toward the ≥2-source
+  rule for factual claims. Expert *disagreements* are first-class findings:
+  they mark the genuinely open questions.
+
+### 6. Synthesize (one pass, one author — you)
+
+Parallelize gathering, never synthesis. Write `build/research/<topic>-report.md`:
+
+- **Answer first** (BLUF), then evidence, then method.
+- The brief, restated.
+- Per major finding: the claim + confidence tag + **what it implies for the
+  decision** + **what evidence would change this conclusion**.
+- Disputes surfaced with both positions — never silently averaged.
+- **Expert positions map**: who believes what (quoted, dated,
+  conflict-of-interest flagged), and where credible experts disagree.
+- **Open questions**: each UNVERIFIED/DISPUTED item with the specific search
+  or experiment that would resolve it (this doubles as the next round's input).
+- Citations dated and tier-labeled: `[primary, 2026-04]`.
+
+Commit the report. Raw findings stay in `build/research/` (gitignored).
+
+### 7. Hand off
+
+If this feeds the build loop: distill the report into the iteration's **Grounds**
+section (`architecture/I<NN>-<name>.md`) per `/architect`, or into
+`architecture/BRIEF.md` §sections when it is mission-scope, and continue there.
+The builder's PHASE 0 will challenge Grounds' claims — that's a feature.