diff --git a/README.md b/README.md index 29204e3..d3cc9ca 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ - [Cookbook по `workflow`](agent-swarm/references/orchestration.md) - [Domain-адаптеры](agent-swarm/references/domains.md) - [Token economy](agent-swarm/references/token-economy.md) +- [Prerequisite gate](agent-swarm/references/prerequisites.md) - [Изолированное визуальное тестирование](agent-swarm/references/visual-testing.md) ### Установка @@ -33,7 +34,7 @@ cp -r skills/agent-swarm ~/.dsh/skills/ agent-swarm/ ├── SKILL.md # основной протокол ├── README.ru.md # краткое описание -├── references/ # playbook, packets, orchestration, domains, visual testing, token economy +├── references/ # playbook, packets, orchestration, domains, visual testing, token economy, prerequisites ├── assets/ # шаблоны, схемы, workflow-скрипты └── scripts/audit-scope.mjs # проверка ownership ``` diff --git a/agent-swarm/README.ru.md b/agent-swarm/README.ru.md index 67b9e9a..28ff74c 100644 --- a/agent-swarm/README.ru.md +++ b/agent-swarm/README.ru.md @@ -15,11 +15,12 @@ ## Что происходит 1. **Fit-check.** Если задача не делится на 8+ независимых юнитов, скилл скажет не использовать swarm. -2. **Recon.** 2–4 агента картографируют репозиторий/источники/данные; лид пишет `.swarm/brief.md`, `.swarm/profile.md` и выбирает domain-адаптер из `references/domains.md`. -3. **План.** Задачи, владельцы файлов, контракты, критерии приёмки. Гейт: без этого волны не стартуют. -4. **Волны.** Воркеры идут батчами по 6–8 (реальный лимит активных детей узнаётся перед запуском и записывается в `state.json`; recon не должен занимать слоты). Затем 4–6 независимых верификаторов на «замороженном» дереве, затем интегратор. -5. **Аудит.** `scripts/audit-scope.mjs` сравнивает изменения с картой владения. -6. **Отчёт.** `.swarm/final-report.md`. +2. **Prerequisite gate.** Скилл проверяет toolchain, runtime, сервисы, display, credentials и baseline. Ставит только project-local/pinned и только с разрешения; если обязательный prerequisite не закрывается — спрашивает пользователя **до** запуска работы. Воркеры ничего не устанавливают. +3. **Recon.** 2–4 агента картографируют репозиторий/источники/данные; лид пишет `.swarm/brief.md`, `.swarm/profile.md` и выбирает domain-адаптер из `references/domains.md`. +4. **План.** Задачи, владельцы файлов, контракты, критерии приёмки. Гейт: без этого волны не стартуют. +5. **Волны.** Воркеры идут батчами по 6–8 (реальный лимит активных детей узнаётся перед запуском и записывается в `state.json`; recon не должен занимать слоты). Затем 4–6 независимых верификаторов на «замороженном» дереве, затем интегратор. +6. **Аудит.** `scripts/audit-scope.mjs` сравнивает изменения с картой владения. +7. **Отчёт.** `.swarm/final-report.md`. ## Артефакты @@ -41,7 +42,8 @@ ## Настройка -- Шаблоны: `assets/`. +- Шаблоны: `assets/`, включая `prerequisites.md.tmpl`. +- Prerequisites: `references/prerequisites.md`. - Подробный runbook: `references/playbook.md`. - Оркестрация: `references/orchestration.md`. - Проверка скоупа: `node scripts/audit-scope.mjs --init` перед стартом, затем `node scripts/audit-scope.mjs`. diff --git a/agent-swarm/SKILL.md b/agent-swarm/SKILL.md index 909889a..0fc4be7 100644 --- a/agent-swarm/SKILL.md +++ b/agent-swarm/SKILL.md @@ -40,14 +40,15 @@ Otherwise: one agent for small work; 2–5 `subagent` calls for a few long-lived ## Protocol -0. **Fit check & preflight** — go/no-go, budget (`max_agents`, `max_waves`, **tokens**), and **discover the available tools and real active-child cap** before sizing a wave. Record in `state.json`: tool availability (`workflow`, `subagent`, display/artifact command, build commands), slot cap, active children, planned batch size, chosen domain adapter, token budget/soft cap/reserve, and whether usage is measured or estimated (see `references/token-economy.md`). -1. **Recon** — 2–4 parallel agents return findings with paths and line numbers. Timebox them, merge into `.swarm/brief.md` and `.swarm/map.md`, then stop them; recon must not hold slots during the build wave. -2. **Plan gate** — write `.swarm/plan.json`, `plan.md`, `ownership.md`, `contracts.md`, and one `tasks/Txx.md` per unit. Every success criterion maps to a task and a check. No two tasks write the same path. Include a `LEAD`/`INTEGRATOR` task owning lead-owned shared files, screenshots, licenses and the final report. Freeze interfaces. Prefer vertical slices and files under ~800 lines; a task that requires reading a 3k-line file is too broad. **Do not dispatch until this gate passes.** -3. **Build wave** — one `workflow` call per build wave when the tool exists, using the batched runner in `assets/wave.workflow.js`; its `concurrency` must fit the available slots (see Sizing). If `workflow`/`subagent` is unavailable, the lead executes the same packets sequentially. Retry `null`/`failed` once; if the runtime reports an active-child limit, halve the next batch and dispatch the remaining tasks — never relaunch the same oversubscribed fan-out. -4. **Audit** — run `scripts/audit-scope.mjs` from the skill base directory; revert or reassign out-of-scope changes. Run the build/test gate. -5. **Verify wave** — **freeze source changes**, run automated gates first (compile/tests/artifact), then 4–6 fresh verifiers by risk cluster (or 1–2 for a small domain task). Use `assets/verdict.schema.json` and, when available, `assets/verify.workflow.js`; the review file on disk is the source of truth, not the workflow return. Verifiers never fix. Match evidence to the domain adapter: rerun commands, read rendered artifacts, sample citations, recompute metrics. For GUI products, use per-agent isolated displays, never a shared desktop (see `references/visual-testing.md`). If you fix findings, re-run only the affected **delta** and mark the old review stale. -6. **Integrate** — one integrator for shared files and cross-cutting fixes; re-run the full acceptance suite; then a final verification pass on the integrated build. -7. **Close** — freeze the build and run a final independent review against the original request (not the plan), then write `final-report.md`. +0. **Fit check & prerequisite gate** — go/no-go, budget (`max_agents`, `max_waves`, **tokens**), and **discover the available tools and real active-child cap** before sizing a wave. Check every required toolchain/runtime/service/display/credential with a real command; record the result in `.swarm/prerequisites.md` and `state.json`. Prefer project-local pinned setup; **never install globally/system-wide or run `sudo`/`curl | sh` without explicit user approval**. If a required prerequisite is missing and cannot be resolved safely, ask the user with the exact item, command, scope and alternatives **before any worker starts**. Workers never install; they return `blocked`. +1. **Resolve prerequisites** — after approval/install, re-run the checks and the baseline suite. No build or verify wave starts while a required item is `needs_user` or `blocked`; optional items may be skipped only with a recorded reduced scope. See `references/prerequisites.md`. +2. **Recon** — 2–4 parallel agents return findings with paths and line numbers. Timebox them, merge into `.swarm/brief.md` and `.swarm/map.md`, then stop them; recon must not hold slots during the build wave. +3. **Plan gate** — write `.swarm/plan.json`, `plan.md`, `ownership.md`, `contracts.md`, and one `tasks/Txx.md` per unit. Every success criterion maps to a task and a check. No two tasks write the same path. Include a `LEAD`/`INTEGRATOR` task owning lead-owned shared files, screenshots, licenses and the final report. Freeze interfaces. Prefer vertical slices and files under ~800 lines; a task that requires reading a 3k-line file is too broad. **Do not dispatch until this gate passes.** +4. **Build wave** — one `workflow` call per build wave when the tool exists, using the batched runner in `assets/wave.workflow.js`; its `concurrency` must fit the available slots (see Sizing). If `workflow`/`subagent` is unavailable, the lead executes the same packets sequentially. Retry `null`/`failed` once; if the runtime reports an active-child limit, halve the next batch and dispatch the remaining tasks — never relaunch the same oversubscribed fan-out. +5. **Audit** — run `scripts/audit-scope.mjs` from the skill base directory; revert or reassign out-of-scope changes. Run the build/test gate. +6. **Verify wave** — **freeze source changes**, run automated gates first (compile/tests/artifact), then 4–6 fresh verifiers by risk cluster (or 1–2 for a small domain task). Use `assets/verdict.schema.json` and, when available, `assets/verify.workflow.js`; the review file on disk is the source of truth, not the workflow return. Verifiers never fix. Match evidence to the domain adapter: rerun commands, read rendered artifacts, sample citations, recompute metrics. For GUI products, use per-agent isolated displays, never a shared desktop (see `references/visual-testing.md`). If you fix findings, re-run only the affected **delta** and mark the old review stale. +7. **Integrate** — one integrator for shared files and cross-cutting fixes; re-run the full acceptance suite; then a final verification pass on the integrated build. +8. **Close** — freeze the build and run a final independent review against the original request (not the plan), then write `final-report.md`. ## Hard rules @@ -60,7 +61,8 @@ Otherwise: one agent for small work; 2–5 `subagent` calls for a few long-lived 7. **Freeze during verification.** Once the verify wave starts, do not edit source/tests/docs except to fix a verified finding. After a fix, re-run the affected verifier; an old review is stale. 8. **Stop rules.** Two waves with no net progress → stop and re-plan. Verification failure rate > 30% → fix briefs/contracts, not agent count. Budget exhausted → report partial and list unverified areas. 9. **No shared visual desktop.** Visual agents get their own display/config/project copy; see `references/visual-testing.md`. A screenshot from a shared desktop is not evidence. Computer-use is a last-resort, single-agent tier on a disposable desktop/VM; it is never the sole evidence and never runs in parallel with other visual agents. -10. **Token budget is a quality constraint.** Record spend per phase, keep a 20–30% reserve for verification/integration, and stop at the hard cap with a partial report. Cut redundant context, agents, full-file reads and full re-reviews — never cut tests or independent review. See `references/token-economy.md`. +10. **Prerequisites before dispatch.** A required tool/runtime/service/credential is checked, installed with explicit approval if needed, and re-checked before workers start. Ask the user before work if it cannot be resolved; never let a worker install or silently skip a required check. +11. **Token budget is a quality constraint.** Record spend per phase, keep a 20–30% reserve for verification/integration, and stop at the hard cap with a partial report. Cut redundant context, agents, full-file reads and full re-reviews — never cut tests or independent review. See `references/token-economy.md`. ## Sizing @@ -79,6 +81,7 @@ Otherwise: one agent for small work; 2–5 `subagent` calls for a few long-lived ``` .swarm/ brief.md shared context: goal, domain, commands, conventions, hazards + prerequisites.md tool/runtime/display/credential gate + approvals map.md repository/source map from recon: paths, entry points, hazards contracts.md frozen interfaces between tasks profile.md domain adapter: artifacts, commands, evidence types (optional) @@ -91,7 +94,7 @@ Otherwise: one agent for small work; 2–5 `subagent` calls for a few long-lived baseline.json pre-swarm file manifest (`--init`) report.schema.json report contract for workers verdict.schema.json minimal contract for verifiers - state.json wave, token budget/spend per phase, open issues + state.json wave, token budget/spend, prerequisites, open issues final-report.md tmp/T01/ worker scratch, never shared ``` @@ -109,6 +112,7 @@ For a `blocked` task: apply the smallest contract/shared-file change, update `co - `references/orchestration.md` — `workflow` cookbook: script patterns, schema subset, retries, background runs, archetypes (code / research / content). - `references/domains.md` — adapters for software, research, content, data, design and operations. - `references/token-economy.md` — measurement, budgets, context discipline, delta verification, vertical slices. +- `references/prerequisites.md` — preflight checks, install/approval policy, degraded-scope record. - `references/visual-testing.md` — isolated Xvfb/container visual tests, deterministic screenshots, verifier procedure (GUI adapter). - `assets/` — copyable brief, task, and verifier templates; `report.schema.json`, `verdict.schema.json`; `wave.workflow.js` (batched workers), `verify.workflow.js` (frozen verification). - `scripts/audit-scope.mjs` — compares changed files to the ownership map. diff --git a/agent-swarm/assets/brief.md.tmpl b/agent-swarm/assets/brief.md.tmpl index 030949e..83dd3e2 100644 --- a/agent-swarm/assets/brief.md.tmpl +++ b/agent-swarm/assets/brief.md.tmpl @@ -41,6 +41,12 @@ Scope is checked by the lead with the skill's `scripts/audit-scope.mjs`; workers - {{Generated files, migrations, flaky tests, shared ports, secrets, caches.}} - {{Generated or vendored paths that must not be edited.}} +## Prerequisites +- Status: {{passed / needs_user / degraded}} +- Details: `.swarm/prerequisites.md` +- Missing/blocked: {{items or none}} +- User approval: {{approved/declined/pending}} + ## Token / effort budget - Hard budget: {{tokens or n/a}}; reserve {{20–30%}} for verification and integration. - Prefer vertical slices and files under ~800 lines. diff --git a/agent-swarm/assets/prerequisites.md.tmpl b/agent-swarm/assets/prerequisites.md.tmpl new file mode 100644 index 0000000..24bc11e --- /dev/null +++ b/agent-swarm/assets/prerequisites.md.tmpl @@ -0,0 +1,30 @@ +# Prerequisites — {{TASK}} + +Checked before dispatch. Do not print secrets. + +## Required + +| Item | Check command | Status | Version / error | Owner | +|---|---|---|---|---| +| {{tool/runtime}} | `{{command}}` | {{pass/missing/needs_user}} | {{version or exact error}} | lead | + +## Optional / degraded + +| Item | Check | Impact if missing | Decision | +|---|---|---|---| +| {{display/GPU/service}} | `{{command}}` | {{reduced scope}} | {{skip/ask/install}} | + +## User approval + +- Missing item: {{name}} +- Why required: {{acceptance check}} +- Proposed command/scope: `{{command}}` ({{project-local/user/system}}) +- Alternatives: {{existing path / reduced scope / stop}} +- User decision: {{pending/approved/declined}} +- Recorded in `state.json`: {{passed/needs_user/degraded}} + +## Baseline + +- Build: `{{command}}` → {{result}} +- Tests: `{{command}}` → {{result}} +- Visual/smoke: `{{command}}` → {{result}} diff --git a/agent-swarm/assets/task.md.tmpl b/agent-swarm/assets/task.md.tmpl index ef6f0af..6bab1cd 100644 --- a/agent-swarm/assets/task.md.tmpl +++ b/agent-swarm/assets/task.md.tmpl @@ -29,6 +29,7 @@ Role: worker | Wave: {{n}} | Depends on: {{ids or —}} | Effort: {{S/M/L}} ## Constraints - {{No new dependencies, style, performance, compatibility.}} - Context budget: read only the inputs above; if you need more than {{N}} additional files, return `blocked` instead of exploring the whole repo. +- Prerequisites are lead-owned: do not install tools, packages or system dependencies. If one is missing, return `blocked` with the exact check and error. - Do not run the full test suite unless the card explicitly asks; run targeted checks. ## Acceptance (re-runnable) diff --git a/agent-swarm/assets/verifier.md.tmpl b/agent-swarm/assets/verifier.md.tmpl index 93ac24e..2bbe2f7 100644 --- a/agent-swarm/assets/verifier.md.tmpl +++ b/agent-swarm/assets/verifier.md.tmpl @@ -23,6 +23,8 @@ output. Evidence must be reproducible by a fresh verifier. - Edge cases named in the task card. ## Freeze +Do not install tools or dependencies; prerequisites are lead-owned. If a required check cannot run, +report `not_run` with the exact missing item — do not change the environment. The tree is frozen during verification. Do not edit product source, tests, docs or manifests. If you need a gate script that rewrites generated files, copy it/hash-check it instead of changing the tree. ## Visual checks diff --git a/agent-swarm/references/playbook.md b/agent-swarm/references/playbook.md index 4d680ab..aa60368 100644 --- a/agent-swarm/references/playbook.md +++ b/agent-swarm/references/playbook.md @@ -23,7 +23,30 @@ Budget: Go: a 40-file migration with per-module tests, a 30-source research report, a 20-section document with a style guide, a multi-dataset analysis, a multi-screen visual redesign, a multi-service runbook. No-go: one failing test, one architectural decision, a detail pass where every unit touches the same artifact. -## 1. Recon (2–4 agents) +## 1. Prerequisite gate + +Do this before recon and before writing task cards. A missing compiler, runtime, browser, display, +database, credential or package manager found mid-wave costs an entire wave and can leave the tree +half-changed. Full policy and the approval template: `references/prerequisites.md`. + +1. Inventory required vs optional items: toolchain + pinned version, build/test/lint commands, runtime, + services, display/GPU, credentials (presence only), agent tools (`workflow`/`subagent`), disk/ports. +2. Run the documented checks yourself. Do not trust a worker's "should work". +3. Prefer existing/project-local toolchains. **Never** run `sudo`, system package managers, global + installs or `curl | sh` without explicit user approval; never change the user's global environment + as a side effect. +4. If a required item is missing and cannot be installed safely: **stop before work**, ask the user + with the exact item, command, scope (project/user/system), alternatives and impact. Do not dispatch + workers while the answer is pending. +5. After approval/install, re-run the checks and the baseline suite. Record `.swarm/prerequisites.md` + and `state.json.prerequisites` as `passed`, `needs_user` or `degraded`. +6. Optional items may be skipped only with a recorded reduced scope; mark affected acceptance checks + `not_run`. Workers never install; they return `blocked` with the exact command/output. + +Do not start with "I'll install it later if needed." The gate is before recon, not after the first +failure. + +## 2. Recon (2–4 agents) Give each recon agent one question, not the whole task: - Structure: entry points, modules, build/test commands. @@ -35,13 +58,14 @@ Require findings as `path:line — fact`, no proposals. Merge into `.swarm/brief Recon lifecycle matters: each recon agent writes its report and stops. It must kill GUI/probe processes it started, must not run the full test suite, and must not keep a slot while the build wave starts. If a recon agent is still active after its report exists, interrupt it; otherwise it silently consumes one of the active-child slots. -## 2. Plan gate +## 3. Plan gate Resolve `` to the base directory reported by the skill loader. If the workspace is a git repository, add `.swarm/` to `.gitignore` before the baseline so coordination files never reach the diff. Bootstrap once: ```sh mkdir -p .swarm/tasks .swarm/reports .swarm/reviews .swarm/tmp cp /assets/brief.md.tmpl .swarm/brief.md +cp /assets/prerequisites.md.tmpl .swarm/prerequisites.md cp /assets/report.schema.json .swarm/report.schema.json cp /assets/verdict.schema.json .swarm/verdict.schema.json node /scripts/audit-scope.mjs --init @@ -66,6 +90,8 @@ Write the plan before any worker starts. Keep the plan proportionate: a small do **Waves.** Topologically sort by `depends_on`, then balance effort across batches. Do **not** plan 8–12 workers from a documented default: discover the runtime active-child cap first. Compute `batch_size = clamp(slot_cap - active_children - 1, 2, 8)`; recon and any other subagents count as active children. If the cap is unknown, use 6. Put foundational or risky tasks in batch 1; verify after the last build batch. **Gate checklist:** +- [ ] Required prerequisites are `passed` (or user-approved `degraded`), recorded in `.swarm/prerequisites.md`; no `needs_user`/`blocked` item remains. +- [ ] Baseline build/test command has been run and its result recorded. - [ ] 8+ tasks, each with objective, inputs, write scope, acceptance, stop condition, and a token/effort budget. - [ ] Files/modules over ~800 lines are split, or the task explicitly owns the integration cost. - [ ] Token budget, soft cap and verification reserve are recorded; units are merged/split to avoid fixed-overhead waste. @@ -114,7 +140,7 @@ Minimal `plan.json` shape: `audit-scope.mjs` reads only `id` and `write`. Keep those accurate. Use `path/**` for directories, including directories the task will create. -## 3. Build wave +## 4. Build wave Dispatch one `workflow` call per build wave (see `references/orchestration.md`). Use `assets/wave.workflow.js`, which splits tasks into batches, catches spawn errors instead of discarding the whole wave, and carries `args.concurrency`. @@ -147,7 +173,7 @@ A `blocked` report is a request for a lead decision, not a failure. Fast path: If the block reveals an underspecified interface shared by several tasks, update the contract once and message all affected workers. If two blocked tasks need conflicting contracts, stop and re-plan. -## 4. Verify wave +## 5. Verify wave Choose verifiers by risk cluster, not one per task: 4–6 verifiers for 8–12 tasks, fewer for a small domain task. A verifier gets the task cards, the changed files (or diff), and the acceptance commands. It does not get the worker's rationale and does not fix anything. @@ -163,7 +189,7 @@ Evidence standard: for every criterion, a command/artifact/citation/metric and i On failure, create a fix task with the verifier's repro; do not send the verifier back to fix its own finding. After fixes, re-run only the affected **delta** (diff + findings + acceptance commands), not the whole repository, and mark the previous review stale; repeat until the remaining findings are minor/documented. Then run one final integrated verification pass on the frozen build. -## 5. Integrate +## 6. Integrate One integrator (two only for disjoint areas) owns: - shared files and cross-cutting edits; @@ -173,7 +199,7 @@ One integrator (two only for disjoint areas) owns: No parallel workers during integration. The integrator may read all task cards and reviews; it writes `.swarm/integration.md` with what changed and why. Freeze the tree while the final verification runs; any post-verification edit invalidates the affected evidence. -## 6. Close +## 7. Close Final review is against the **original request**, not the plan: a fresh agent checks the success criteria, the diff, and the evidence. Then the lead writes `.swarm/final-report.md` with these sections: @@ -199,6 +225,9 @@ Final review is against the **original request**, not the plan: a fresh agent ch | Verifiers find the same defect | brief missing a convention | fix the brief, add a check, re-run affected tasks | | Lead context filling up | reading full reports | read summary + evidence; open only exceptions | | A worker hangs | no per-agent timeout exists | kill the job, split the task, add a tighter stop condition | +| Missing tool/runtime discovered mid-wave | prerequisite gate skipped | stop, run `prerequisites.md`, ask user, do not spawn replacements | +| Version mismatch with lockfile | unpinned global toolchain | use project-local pinned version; record it and re-run baseline | +| Required credential/display unavailable | not checked before dispatch | ask user for exact item/scope; degrade only with recorded reduced scope | | Token spend explodes | huge files, too many agents, full re-reads/reviews | split files, right-size batch, delta-review, record usage | | Verifier repeats a full review after a small fix | no delta procedure | review diff + findings + affected checks only | | Reports/reviews dominate input | oversized prose | cap to evidence lines; logs in artifacts | diff --git a/agent-swarm/references/prerequisites.md b/agent-swarm/references/prerequisites.md new file mode 100644 index 0000000..69894a3 --- /dev/null +++ b/agent-swarm/references/prerequisites.md @@ -0,0 +1,82 @@ +# 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: +Required for: +Check: `` -> +Proposed fix: `` (scope: project-local / user / system) +Alternatives: use ; skip 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`. + +## 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.