space-architect 1.2.0 → 2.0.0.rc1

data/skill/architect/research.md

@@ -0,0 +1,98 @@
+# Research fan-out reference
+
+Read this only when a research trigger fires (see SKILL.md step 3). The fan-out
+uses `architect research dispatch` to launch parallel read-only `claude -p`
+researchers (Sonnet 4.6, no Edit/Write/Bash) and `architect research wait` to
+collect their results. The architect keeps all judgment: it verifies
+load-bearing claims and writes the iteration's **Grounds** section itself.
+
+**Note:** the `~/.claude/skills/architect-research/` copy of this skill is
+synced separately and is NOT updated by this repo.
+
+## 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.
+
+Write each research prompt to its own file, then dispatch and wait:
+
+```bash
+# 1. Write one prompt file per research question (use Write tool — do NOT shell-redirect)
+#    Filenames: <NN>-<topic>.prompt.md  e.g. 01-official-api.prompt.md
+
+# 2. Dispatch all lanes at once (non-blocking — returns PIDs immediately)
+architect research dispatch \
+  01-official-api.prompt.md \
+  02-changelog.prompt.md
+
+# 3. Wait for all lanes to complete (tails run.jsonl streams; exits non-zero if any lane fails)
+architect research wait
+
+# 4. Read each report
+cat build/research/01-official-api/report.md
+cat build/research/02-changelog/report.md
+```
+
+The id for each lane is derived from the prompt filename:
+`01-official-api.prompt.md` → id `01-official-api` →
+directory `build/research/01-official-api/`.
+
+Verbosity flags for `wait`:
+- default (L1): per-lane lifecycle + terminal outcome line
+- `--level 2`: + assistant text
+- `--level 3`: + tool call names
+- `--level 4`: + tool call inputs and results
+- `--quiet`: suppress all output; exit status alone signals outcome
+- `--thinking`: reveal assistant thinking blocks
+- `--jsonl`: emit raw lane-tagged JSONL instead of human text
+
+The researchers are READ-ONLY by toolset (`Read,Grep,Glob,WebSearch,WebFetch`
+with no Edit/Write/Bash) so they cannot touch the repo. Their final report
+is extracted from the terminal `result` event in the stream-json log and
+written to `build/research/<id>/report.md` automatically by `wait`.
+
+## 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.
+```
+
+Keep each researcher scoped to ≤5 subjects and put hard context rules in the
+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.
+
+## Gather (architect — this is your work, not another agent's)
+
+1. Read every `build/research/<id>/report.md`.
+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.

data/skill/architect-research/lanes.md

@@ -0,0 +1,191 @@
+# Source-class tactics library — researcher preamble, scout block, verified endpoints
+
+Lanes are DESIGNED per topic by the orchestrator (SKILL.md step 2); the
+sections below are search tactics and verified endpoints per source class —
+draw on whichever a designed lane needs, mix freely. Endpoints verified
+unauthenticated June 2026. Every researcher block starts with this preamble,
+then the lane-specific objective:
+
+```
+You are a web research agent. Answer ONE assigned objective. Do not write code,
+do not make recommendations — judgment belongs to the orchestrator reading your
+output. Budget: <N> searches; if two consecutive searches yield no new
+load-bearing facts, stop and return. HARD CONTEXT RULES: never open a full
+page when the search snippet answers the question; quote at most 2 sentences
+per source; the moment you can answer, STOP and write your findings — partial
+findings beat context exhaustion (researchers that fill their window die
+without writing anything). OUTPUT: markdown findings — every finding
+carries source URL, source date, 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. Record exact version
+numbers and dates. When sources disagree, report the disagreement — do not
+resolve it. If you cannot find evidence, write NOT FOUND — never fill gaps from
+prior knowledge without flagging it. End with the 2-3 findings most likely to
+change a design decision.
+```
+
+**Lane scoping rule (learned 2026-06-12):** cap each researcher at ~5 subjects
+(repos, vendors, people). Doc-heavy lanes burn the context window on fetched
+pages — two of nine researchers in one session died of context exhaustion
+before writing any findings. A researcher that dies returns NOTHING (`-o`
+only materializes on a clean finish). If a lane dies this way, bisect it into
+narrower lanes and re-dispatch; don't re-run it as-is.
+
+## Lane 0 — Scout (brainstorm scale; dispatches before lane design)
+
+Objective template: map the terrain of <topic> — do NOT gather findings.
+Return: (1) canonical terminology and the names the field itself uses;
+(2) the 5–10 load-bearing systems/papers/repos/vendors, one line each on why
+they matter; (3) the named people whose positions recur; (4) which source
+classes look rich vs empty for this topic (papers? repos? vendor blogs?
+forums?); (5) the topic's natural fault lines — the 3–6 sub-questions an
+expert would split it into. Budget ~10 searches; breadth over depth; snippet
+over page. Output is a MAP for the orchestrator to design lanes from —
+structure matters more than completeness.
+
+## Lane 1 — Academic (latest papers)
+
+Objective: the current academic state of <topic> — most recent survey, the
+frontier preprints, and which papers the field treats as load-bearing.
+
+Pipeline: **survey first → frontier sweep → snowball → score.**
+
+- Recent survey: Semantic Scholar `publicationTypes=Review`, or arXiv
+  `ti:survey AND abs:<topic>` (last ~18 months). The survey supplies canonical
+  terminology and the seed bibliography.
+- Frontier sweep (newest first):
+  `https://export.arxiv.org/api/query?search_query=cat:<cs.XX>+AND+abs:%22<topic>%22&sortBy=submittedDate&sortOrder=descending&max_results=25`
+  (Atom XML; uppercase AND/OR; ≥3s between calls) and
+  `https://api.semanticscholar.org/graph/v1/paper/search?query=<topic>&fields=title,year,citationCount,tldr,venue,externalIds&limit=20&year=2025-2026`
+  (expect 429s — back off and retry; the `tldr` field is gold for triage).
+  Community signal: `https://huggingface.co/api/daily_papers?limit=20` and
+  `https://huggingface.co/papers/trending`. **Papers With Code is dead**
+  (shut down July 2025; HF Papers is the successor) — never cite it.
+- Snowball from the 2-3 most relevant seeds — a reliable "latest papers" method:
+  forward citations
+  `https://api.semanticscholar.org/graph/v1/paper/arXiv:<id>/citations?fields=title,year,isInfluential&limit=100`
+  and semantic neighbors
+  `https://api.semanticscholar.org/recommendations/v1/papers/forpaper/arXiv:<id>?limit=20`.
+  Fallback when S2 throttles: OpenAlex —
+  `https://api.openalex.org/works?search=<topic>&sort=publication_date:desc&per-page=25&mailto=research@example.com`.
+- Score candidates: citations-per-month (not raw count — meaningless for 2026
+  papers), venue/OpenReview decision (`https://api2.openreview.net/notes/search?term=<topic>&limit=25`
+  has actual reviewer scores), code availability, HF traction. Red flags:
+  preprint-only after 18+ months, self-citation-heavy.
+
+## Lane 2 — Popular repos (what the ecosystem actually uses)
+
+Objective: the 5-10 repos/libraries the ecosystem has actually adopted for
+<topic>, with adoption evidence beyond stars.
+
+- Discovery: GitHub search —
+  `topic:<topic> stars:>1000 archived:false sort:stars`,
+  `"<topic>" in:name,description,readme stars:>2000`, plus awesome-lists as
+  recall boosters (`awesome <topic> in:name stars:>1000`) — re-check `pushed:`
+  on every list entry; lists go stale.
+- **Adoption evidence beats stars**: dependents count via
+  `https://api.deps.dev/v3/systems/<npm|pypi|...>/packages/<name>` or
+  `https://packages.ecosyste.ms` (keyless, 5k req/hr); registry download
+  *trends* (`https://pypistats.org/api/packages/<pkg>/recent`,
+  `https://api.npmjs.org/downloads/point/last-month/<pkg>`).
+- **Fake-star check**: ~4.5M fake stars documented in the wild. Stars without
+  proportional forks/issues/dependents = flag it. Report stars AND dependents
+  AND last release for every repo.
+
+## Lane 3 — Cutting-edge repos (emerging, not hype)
+
+Objective: what's emerging in <topic> in the last ~6 months that practitioners
+are actually adopting — and which hyped repos are already abandoned.
+
+- Where bleeding-edge surfaces first: HF daily/trending papers (code-linked);
+  Hacker News via Algolia —
+  `https://hn.algolia.com/api/v1/search_by_date?query=<topic>&tags=story&numericFilters=points>50`
+  (also `query=github.com` + topic for Show HNs); `https://lobste.rs/t/<tag>.json`;
+  GitHub `topic:<topic> created:>{90d ago} stars:>100 pushed:>{14d ago} sort:stars`;
+  OSS Insight (`https://ossinsight.io/collections/trending`) for transparent
+  velocity ranking.
+- **Emerging-vs-hype gate** (report which side each repo lands on):
+  EMERGING = created recently AND pushed <14d AND star velocity sustained ≥2
+  weeks AND issues getting maintainer responses AND linked from a paper or a
+  track-record org AND forks/issues growing in proportion to stars.
+  HYPE = week-one star spike then stalled pushes, unanswered issues, README
+  promises >> code, single contributor, no tests/releases. Any single signal
+  is gameable; the conjunction is not.
+
+## Lane 4 — Production-grade design patterns
+
+Objective: how 2-3 production libraries adjacent to <topic> design
+the thing we're about to build — API ergonomics, error handling, extension
+points, testing patterns — and where they differ.
+
+- Select subjects with the production-grade gate: pushed <6mo (or explicitly
+  stable + responsive issues), tagged releases + changelog in last 12mo,
+  dependents >100 (ecosystem-adjusted), ≥2 active maintainers, CI runs tests
+  on PRs, OSI license, no unaddressed criticals on `https://osv.dev`.
+  Ignore raw stars and commit counts.
+- Reading order — never start at file #1: README + manifest (entry points,
+  exports = the deliberate public surface) → trace ONE canonical happy-path
+  call end to end → tests for the relevant feature (executable documentation
+  of edge-case policy) → 3 closed issues + 2 merged PRs in the area (the
+  "why not" you can't get from code).
+- Extract four categories per library: **API ergonomics** (cost of the 90%
+  case in lines, defaults, config layering), **error handling** (exception
+  hierarchy root, retried vs raised, boundary translation), **extension
+  points** (grep for hook/adapter/middleware/plugin/register/Protocol),
+  **testing patterns** (fixture strategy, how I/O is faked, regression-test-
+  per-bug convention).
+- Then the **cross-library diff**: patterns all of them share are load-bearing;
+  where they differ is a trade-off to document.
+- Tools: GitHub code search (`symbol:<Name>`, `/regex/`, `repo:`, `path:`),
+  `https://grep.app` (usage in the wild), `https://sourcegraph.com/search`.
+  For "what do people actually call", search downstream dependents' code, not
+  the library.
+
+## Lane 5 — General web
+
+Objective: everything the other lanes structurally miss on <topic> — expert
+blog posts, postmortems and failure reports, comparisons, official vendor
+docs/changelogs, pricing/operational constraints.
+
+- Standard multi-angle sweep: official docs/changelogs; named-expert posts;
+  "<X> postmortem" / "<X> at scale" / "<X> problems" for failure reports;
+  "<X> vs <Y>" for comparisons. Date-restrict queries on fast-moving topics.
+- Source hierarchy applies hardest here: SEO listicles and AI-generated
+  aggregators are pointers, never citations — chase them to the primary
+  source or drop the claim.
+
+## Lane 6 — Expert opinion (second wave — dispatch after lanes 1-5 return)
+
+Objective: what the named experts in <topic> are saying right now — positions,
+warnings, predictions, and especially disagreements — from their blogs, talks,
+and social posts.
+
+- **Build the roster first** (why this lane runs second): survey and top-paper
+  authors (lane 1), maintainers of the leading repos (lanes 2-3), and names
+  that recur across lane 5 results. Pick 5-8; record each expert's affiliation
+  — you'll need it for conflict-of-interest tagging.
+- Where to find their voice, in reliability order:
+  1. **Personal blogs / newsletters** — the primary source for considered
+     positions; search `"<name>" <topic>` and `site:<their-domain> <topic>`.
+  2. **HN comments** — keyless and reliable:
+     `https://hn.algolia.com/api/v1/search?tags=comment,author_<username>&query=<topic>`
+     (many experts comment under well-known usernames).
+  3. **Conference talks / podcasts** — search `"<name>" talk <topic> 2026`;
+     prefer transcripts or the speaker's own writeup over third-party recaps.
+  4. **X** — login-walled for agents. Use search-engine indexing
+     (`site:x.com "<name>" <topic>`) and direct profile URLs
+     (`x.com/<handle>`); don't rely on third-party viewers (flaky) and note
+     that Bluesky's public search API has been closed (403) since March 2025
+     — profile pages only.
+  5. **Reddit / lobste.rs** threads and AMAs (via indexed search:
+     `site:reddit.com "<name>" <topic>`).
+- **Opinion is its own evidence class.** An expert opinion is judgment —
+  datable, revisable, and sometimes conflicted. For every position report:
+  the exact quote or close paraphrase, where and when stated, and any conflict
+  of interest (vendor employee talking their book, author promoting their own
+  tool). An opinion NEVER counts toward the ≥2-source rule for factual claims
+  — facts get verified in the other lanes; this lane reports who believes
+  what and why.
+- **The highest-value output is disagreement**: where credible experts
+  contradict each other is exactly where the genuinely open questions are.
+  Map who stands where and what evidence each side cites.

data/skill/architect-vocabulary/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: architect-vocabulary
+description: >
+  Load the Architect system's vocabulary and a short "where you are"
+  orientation — space, mission, iteration, lane, brief, builder, architect,
+  gate, freeze, verdict, research, variant set — for when you're standing in a
+  space-architect workspace (or working on the skill itself) and need the terms
+  understood in conversation but do NOT want to run the loop. Reference only:
+  it does not dispatch builders, freeze, judge, or write iteration files.
+  Invoke as /architect-vocabulary.
+---
+
+# Architect Vocabulary
+
+This skill loads **terminology and orientation only**. It is the glossary, not
+the loop.
+
+## What this skill is — and isn't
+
+- **Is:** the shared vocabulary of `space-architect` plus a quick orientation to
+  where things live, so these terms are understood for the rest of the session.
+- **Isn't:** the build loop. Do **not** run `architect new` / `freeze` /
+  `dispatch` / `integrate`, do **not** write or edit anything under
+  `architecture/`, and do **not** render verdicts on builder work. That is the
+  separate **`/architect`** skill — invoke it deliberately when you actually
+  want to run the loop. Read-only `architect` commands (`status`, `show`) are
+  fine here.
+
+## Vocabulary
+
+**Roles**
+
+- **architect** — the judgment role (a human, or Claude Opus 4.8 in judgment
+  mode): arbitrates disagreements, writes and freezes iteration files, calls
+  kill/continue, merges builder output. Never writes implementation code.
+- **builder** — the implementation role: Claude Sonnet 4.6 run headless via
+  `architect dispatch` (`claude -p`), one per lane in its own worktree. Reports
+  raw evidence; never grades its own work; never edits `architecture/`.
+
+**The workspace**
+
+- **space** — a task-scoped workspace directory holding repos, notes, and
+  artifacts under one root. `architect` finds it by walking up from `$PWD` to the
+  nearest `space.yaml`.
+- **space.yaml** — the space's identity file: id, title, status, repos, notes,
+  tags, plus the `architect:` block (mission state — iterations, freeze shas,
+  lanes).
+- **mission** — an Architect Loop instance living inside a space; spans the
+  repos under `repos/`.
+
+**The unit of work**
+
+- **iteration** — one PR-sized unit of work, captured as a single self-contained
+  file `architecture/I<NN>-<name>.md`, grown section by section. Its sections:
+  - **Grounds** — *why*: research/brief distilled (optional).
+  - **Specification** — *what/how*: the full delegation contract.
+  - **Acceptance Criteria** — *proof*: exact gate commands + thresholds; this is
+    what gets frozen.
+  - **Builder Prompt** — the exact lane-prompt(s) dispatched.
+  - **Builder Report** — raw evidence, transcribed verbatim from build scratch.
+  - **Verdict** — rulings + per-AC PASS/FAIL/INVALID + KILL/CONTINUE.
+- **lane** — a parallel slice of an iteration (1–4 per iteration), each
+  declaring a disjoint target repo + file-touch set. Lanes in different repos are
+  inherently disjoint; same-repo lanes that overlap files run as one. Each runs
+  in its own worktree under `build/<id>-<lane>/`.
+- **worktree** — the isolated git worktree a lane builds in, off the target
+  repo's base commit, so lanes never collide.
+- **dispatch** — launching a fresh headless builder for a lane (`architect
+  dispatch <iteration> <lane>`), streaming output to `build/<id>-<lane>/run.jsonl`.
+
+**Contracts and checkpoints**
+
+- **brief** (`architecture/BRIEF.md`) — the durable, §-numbered mission contract
+  that spans iterations; frozen at the mission level and cited as **BRIEF §N**.
+- **ARCHITECT.md** (`architecture/ARCHITECT.md`) — the cross-iteration index /
+  table of contents and mission-wide state.
+- **freeze** ❄️ — committing the frozen region (Grounds / Specification /
+  Acceptance Criteria) *before* dispatch (`architect freeze`). Records the
+  **freeze_sha** in `space.yaml`; any later change to those sections is an
+  automatic iteration FAIL.
+- **gate** — a frozen verification command + threshold (test/lint/typecheck/
+  build). `architect gate` runs them and streams raw output — it is a runner,
+  never a judge.
+
+**Outcomes**
+
+- **verdict** — the architect's ruling on an iteration, written after evidence:
+  - per-criterion: **PASS** / **FAIL** / **INVALID** (INVALID = not measured the
+    way the gate specifies).
+  - iteration-level: **KILL** / **CONTINUE**.
+- **variant set** — an iteration built as multiple `(harness, model)` lanes over
+  one frozen spec, judged head-to-head against the same Acceptance Criteria; the
+  winner is selected with the human in the loop, not unilaterally.
+
+**Research**
+
+- **research** — two scales:
+  - **discovery scale** (brainstorming, technology selection, state-of-the-art)
+    → the **`/architect-research`** skill: a scout maps the topic, the
+    orchestrator designs parallel researcher **lanes**, claims are verified
+    against sources, and the synthesis distills into a brief §section or an
+    iteration's Grounds.
+  - **iteration scale** → an inline fan-out run only when an iteration needs
+    facts the repo doesn't already have.
+
+**Repos**
+
+- **evergreen** / copy-on-write / **`src` engine** — repo provisioning: when an
+  up-to-date local copy exists under `evergreen_dir`, `architect` copies it into
+  the space (copy-on-write on APFS) instead of cloning over the network. The
+  vendored `src` engine keeps those evergreen checkouts tended.
+
+## Where you are
+
+A space's directory layout:
+
+```text
+space.yaml        # identity + mission state (the architect: block)
+README.md
+repos/            # the repos the mission spans
+notes/            # scratch, prompts, logs
+architecture/     # ARCHITECT.md index + I<NN>-<name>.md iteration files (+ BRIEF.md)
+build/            # lane worktrees + scratch: build/<id>-<lane>/
+tmp/              # workspace-local temp — use instead of /tmp
+```
+
+Safe **read-only** commands to orient yourself (these don't run the loop):
+
+```sh
+architect status            # mission state: iterations, freeze shas, lanes, verdicts
+architect space show        # the space you're standing in
+architect space list        # all your spaces
+```
+
+## Maintenance
+
+This glossary is a **self-contained copy** of terms defined canonically in the
+`architect` skill (`SKILL.md`) and the project `README.md`. It is installed as an
+isolated skill, so it can't reference those at runtime — when the vocabulary
+changes there, re-read this file against them and update it to keep the two from
+drifting.