# Prerequisite gate

Run this **before** writing the plan or dispatching any worker. A missing compiler, runtime, browser,
display, database, credential or package manager discovered mid-wave wastes an entire wave and can
leave the workspace half-changed. Resolve required prerequisites first, or ask the user before work
starts.

## What to check

| Category | Examples | How to check |
|---|---|---|
| Toolchain | Rust/cargo, Node/pnpm, Python/uv, Go, JDK | `command -v`, `--version` |
| Project pin | `rust-toolchain.toml`, `.nvmrc`, `packageManager`, lockfiles | compare actual vs pinned |
| Build/test | build, test, lint, typecheck, codegen commands | run the documented command once |
| Runtime | browser, GUI display, GPU, emulator, container runtime | launch a smoke command |
| Services | database, cache, API, local server | connect/health check |
| Credentials | registry token, API key, SSH agent | check **presence only**, never print values |
| Workspace | writable repo, disk space, ports, git state | `df`, port check, `git status` |
| Agent tools | `workflow`, `subagent`, visual capture, screenshot mode | runtime diagnostics |
| Baseline | existing tests/gates pass before changes | run the baseline suite |

Classify each item:

- **required** — acceptance cannot run without it;
- **optional** — nice-to-have; skipping reduces scope or confidence;
- **blocked** — required and unavailable/uninstallable.

## Install policy

1. **Prefer what already exists.** Check alternate versions, project-local toolchains and documented
   setup before installing anything.
2. **Use project-local, pinned installs** (rustup toolchain, `uv`, `pnpm`/corepack, virtualenv,
   project venv, devcontainer) rather than global/system packages. A project-local install that
   writes only inside the workspace and does not require `sudo` may be run without a separate
   prompt; record the command/version.
3. **No global/system changes without approval.** Do not run `sudo`, `apt`, `dnf`, `brew`, global
   npm/pip installs, or `curl | sh` without explicit user approval. Do not modify the user's global
   environment as a side effect of a task.
4. **No unpinned latest.** Pin to the version required by the project; record the exact command and
   resulting version.
5. **Respect offline/restricted environments.** If the network or permissions block installation,
   stop and ask; do not invent a workaround that changes the host.
6. **Workers never install.** If a worker discovers a missing prerequisite, it returns `blocked`
   with the exact command/output; the lead owns installation and approval.
7. **After install, re-run the check** and the baseline command. An install that does not make the
   gate pass is not resolved.

## If you cannot install it

Ask the user **before starting work**, with a compact decision request:

```text
Missing prerequisite: <name/version>
Required for: <task/acceptance check>
Check: `<command>` -> <actual error>
Proposed fix: `<exact command>` (scope: project-local / user / system)
Alternatives: use <existing path/version>; skip <feature> and reduce scope; stop.
May I run the proposed fix, or which alternative do you prefer?
```

Do not ask "can I install dependencies?" without the exact package, scope and reason. Do not start
workers while the answer is pending. If the user declines, record the reduced scope and the checks
that will be `not_run`.

## Tool acquisition and trust

Build tools when they remove repeated work: a test runner, fixture generator, screenshot harness,
log parser or profiler wrapper. Keep them small, project-local, documented and tested; a tool that
nobody uses is just another dependency.

When installing something:

- prefer the existing toolchain, project-local installs and lockfiles;
- use official package managers/registries and pinned versions/commits;
- check the publisher, repository, license, release notes and checksum/signature where available;
- inspect install scripts before running them; never `curl | sh`;
- no unpinned “latest”, random binaries from chat/SEO pages, or packages whose source you cannot see;
- run untrusted tools in a disposable container/VM, without secrets or network if possible;
- global/system installs (`sudo`, `apt`, `dnf`, `brew`, global npm/pip) need explicit user approval;
- record the exact version/commit and install command in the brief or lockfile.

Workers do not install. If a worker needs a tool, it returns `blocked` with the exact command and
source; the lead verifies and installs it once.

## Record the result

Write `.swarm/prerequisites.md` and set `state.json.prerequisites` to `passed`, `needs_user`, or
`degraded`.

```markdown
| Item | Required? | Check | Status | Version/notes |
|---|---|---|---|---|
| cargo | yes | `cargo --version` | pass | 1.85.0 |
| Playwright browser | yes (UI) | `pnpm exec playwright --version` | needs_user | not installed |
| GPU display | optional | smoke render | degraded | software renderer |
```

## Gate rule

No build or verify wave starts while a **required** prerequisite is `needs_user` or `blocked`.
Optional prerequisites may be skipped only with an explicit note in the brief and the affected
acceptance checks marked `not_run`. The lead, not a worker, owns the decision.