Emil_Shanaty/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add prerequisite gate before dispatch

Browse Source
This commit is contained in:
Emil Shanaty
2026-10-27 19:41:36 +03:00
parent c3f58ceb40
commit 2309fda7b7
9 changed files with 180 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2 -1
View File
@@ -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
```
agent-swarm/README.ru.md
+8 -6
View File
@@ -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`.
agent-swarm/SKILL.md
+14 -10
View File
@@ -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.
agent-swarm/assets/brief.md.tmpl
+6
View File
@@ -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.
agent-swarm/assets/prerequisites.md.tmpl
+30
View File
@@ -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}}
agent-swarm/assets/task.md.tmpl
+1
View File
@@ -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)
agent-swarm/assets/verifier.md.tmpl
+2
View File
@@ -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
agent-swarm/references/playbook.md
+35 -6
View File
@@ -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 `<skill>` 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 <skill>/assets/brief.md.tmpl .swarm/brief.md
cp <skill>/assets/prerequisites.md.tmpl .swarm/prerequisites.md
cp <skill>/assets/report.schema.json .swarm/report.schema.json
cp <skill>/assets/verdict.schema.json .swarm/verdict.schema.json
node <skill>/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 |
agent-swarm/references/prerequisites.md
+82
View File
@@ -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: <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`.
## 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.