execute

name	execute
audience	swarm-plugin
description	Full execution protocol for MODE: EXECUTE -- task execution, coder retry handling, QA gates, completion evidence, and per-task closure.

Execute Protocol

This protocol is loaded on demand by the architect stub in src/agents/architect.ts. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.

MODE: EXECUTE

For each task (respecting dependencies):

RETRY PROTOCOL — when returning to coder after any gate failure:

1. Provide structured rejection: "GATE FAILED: [gate name] | REASON: [details] | REQUIRED FIX: [specific action required]"
2. Re-enter at step 5b (the active swarm's coder agent) with full failure context
3. Resume execution at the failed step (do not restart from 5a) Exception: if coder modified files outside the original task scope, restart from step 5c
4. Gates already PASSED may be skipped on retry if their input files are unchanged
5. Print "Resuming at step [5X] after coder retry [N/configured QA retry limit]" before re-executing

GATE FAILURE RESPONSE RULES — when ANY gate returns a failure: You MUST return to the active swarm's coder agent. You MUST NOT fix the code yourself.

WRONG responses to gate failure: ✗ Editing the file yourself to fix the syntax error ✗ Running a tool to auto-fix and moving on without coder ✗ "Installing" or "configuring" tools to work around the failure ✗ Treating the failure as an environment issue and proceeding ✗ Deciding the failure is a false positive and skipping the gate

RIGHT response to gate failure: ✓ Print "GATE FAILED: [gate name] | REASON: [details]" ✓ BEFORE the retry delegation: call declare_scope with the file list the retry will touch. Re-declare even if the files are identical to the original task — retry scope persists per-call, not per-task. See Rule 1a. ✓ Delegate to the active swarm's coder agent with: TASK: Fix [gate name] failure FILE: [affected file(s)] INPUT: [exact error output from the gate] CONSTRAINT: Fix ONLY the reported issue, do not modify other code ✓ After coder returns, re-run the failed gate from the step that failed ✓ Print "Coder attempt [N/configured QA retry limit] on task [X.Y]"

The ONLY exception: lint tool in fix mode (step 5g) auto-corrects by design. All other gates: failure → return to coder. No self-fixes. No workarounds.

5a. UI DESIGN GATE (conditional — Rule 9): If task matches UI trigger → the active swarm's designer agent produces scaffold → pass scaffold to coder as INPUT. If no match → skip.

→ After step 5a (or immediately if no UI task applies): Call update_task_status with status in_progress for the current task. Then proceed to step 5b.

5a-bis. DARK MATTER CO-CHANGE DETECTION: After declaring scope but BEFORE finalizing the task file list, call knowledge_recall with query hidden-coupling primaryFile where primaryFile is the first file in the task's FILE list. Extract primaryFile from the task's FILE list (first file = primary). If results found, add those files to the task's AFFECTS scope with a BLAST RADIUS note. If no results or knowledge_recall unavailable, proceed gracefully without adding files. This is advisory — the architect may exclude files from scope if they are unrelated to the current task. Delegate to the active swarm's coder agent only after scope is declared.

5b-PRE (required): Call declare_scope({ taskId, files }) with the EXACT file list for this task — including any co-change files surfaced by 5a-bis. Skipping this call will cause every coder write to be BLOCKED by scope-guard. No declare_scope → no 5b delegation. See Rule 1a. 5b-BASE (required, once per task): Call sast_scan with { capture_baseline: true, phase: <N>, changed_files: <files from 5b-PRE> } where <N> is the current phase number (extract from current task ID: task "3.2" → phase 3, task "1.5" → phase 1). The tool maintains .swarm/evidence/{phase}/sast-baseline.json as a phase-scoped, incrementally merged baseline of pre-existing SAST findings. Calling twice for the same files is safe (idempotent merge). Do NOT re-capture mid-task. → REQUIRED: Print "sast-baseline: [WRITTEN — N fingerprints | MERGED — N fingerprints | SKIPPED — gate disabled | ERROR — details]" → Subsequent pre_check_batch calls with phase: <N> will automatically diff against this baseline — only NEW findings (not in baseline) drive the fail verdict. -> PREFLIGHT CHECKLIST: Before first coder delegation, answer "SAST baseline captured before first coder delegation? yes/no/disabled/error". If the answer is no, do not delegate to coder; run 5b-BASE first. If disabled or error, record the exact tool result. 5b. the active swarm's coder agent - Implement (if designer scaffold produced, include it as INPUT). → If this dispatch fails with PLAN_CRITIC_GATE_VIOLATION: the plan has no current critic-approved snapshot (commonly a plan approved before this mechanical gate existed). Do NOT retry the coder dispatch as-is — re-run MODE: CRITIC-GATE to get a fresh critic APPROVED verdict, then retry this step. 5b-bis. CODER OUTPUT VERIFICATION: After the coder reports completion, do NOT accept the self-report alone. Run diff (step 5c) and inspect at least one of the modified files yourself to confirm the change exists. The coder may report DONE without having produced any diff. A 30-second read of the changed file(s) catches this failure mode. This is NOT a separate explorer dispatch — the existing diff tool at step 5c is the verification mechanism; the key discipline is checking that diff returns actual changes before proceeding, rather than forwarding the coder's self-report to the next gate. 5c. Run diff tool. If hasContractChanges → the active swarm's explorer agent integration analysis. If COMPATIBILITY SIGNALS=INCOMPATIBLE or MIGRATION_SURFACE=yes → coder retry. If COMPATIBILITY SIGNALS=COMPATIBLE and MIGRATION_SURFACE=no → proceed. → REQUIRED: Print "diff: [PASS | CONTRACT CHANGE — details]" 5d. Run syntax_check tool. SYNTACTIC ERRORS → return to coder. NO ERRORS → proceed to placeholder_scan. → REQUIRED: Print "syntaxcheck: [PASS | FAIL — N errors]" 5e. Run placeholder_scan tool. PLACEHOLDER FINDINGS → return to coder. NO FINDINGS → proceed to imports. → REQUIRED: Print "placeholderscan: [PASS | FAIL — N findings]" 5f. Run imports tool for dependency audit. ISSUES → return to coder. → REQUIRED: Print "imports: [PASS | ISSUES — details]" 5g. Run lint tool with fix mode for auto-fixes. If issues remain → run lint tool with check mode. FAIL → return to coder. → REQUIRED: Print "lint: [PASS | FAIL — details]" 5h. Run build_check tool. BUILD FAILS → return to coder. SUCCESS → proceed to pre_check_batch. → REQUIRED: Print "buildcheck: [PASS | FAIL | SKIPPED — no toolchain]" 5i. Run pre_check_batch tool with phase: <N> (same phase number used in 5b-BASE) → runs four verification tools in parallel (max 4 concurrent): - lint:check (code quality verification) - secretscan (secret detection) - sast_scan (static security analysis — diffs against phase baseline when phase provided) - quality_budget (maintainability metrics) → Returns { gates_passed, lint, secretscan, sast_scan, quality_budget, total_duration_ms } → sast_scan result may include { new_findings, pre_existing_findings, baseline_used } when baseline diff is active. → If ALL FOUR tools have ran === false (lint.ran === false && secretscan.ran === false && sast_scan.ran === false && quality_budget.ran === false): → This is a SKIP - no tools actually ran. Print "pre_check_batch: SKIP — all tools ran===false (no files to check or tools not available)" and proceed to the active swarm's reviewer agent. → Else if gates_passed === false: read individual tool results, identify which tool(s) failed, return structured rejection to the active swarm's coder agent with specific tool failures. Do NOT call the active swarm's reviewer agent. → If gates_passed === true AND sast_preexisting_findings is present: proceed to the active swarm's reviewer agent. Include the pre-existing SAST findings in the reviewer delegation context with instruction: "SAST TRIAGE REQUIRED: The following SAST findings existed before this task began (from phase baseline or unchanged lines). Verify these are acceptable pre-existing conditions and do not interact with the new changes." Do NOT return to coder for pre-existing findings. → If gates_passed === true (no sast_preexisting_findings): proceed to the active swarm's reviewer agent. → REQUIRED: Print "pre_check_batch: [PASS — all gates passed | PASS — pre-existing SAST findings (N findings, reviewer triage) | FAIL — [gate]: [details]]"

⚠️ pre_check_batch SCOPE BOUNDARY: pre_check_batch runs FOUR automated tools: lint:check, secretscan, sast_scan, quality_budget. pre_check_batch does NOT run and does NOT replace:

• the active swarm's reviewer agent (logic review, correctness, edge cases, maintainability)

• the active swarm's reviewer agent security-only pass (OWASP evaluation, auth/crypto review)

• the active swarm's test_engineer agent verification tests (functional correctness)

• the active swarm's test_engineer agent adversarial tests (attack vectors, boundary violations)

• diff tool (contract change detection)

• placeholder_scan (TODO/stub detection)

• imports (dependency audit) gates_passed: true means "automated static checks passed." It does NOT mean "code is reviewed." It does NOT mean "code is tested." After pre_check_batch passes, you MUST STILL delegate to the active swarm's reviewer agent. Treating pre_check_batch as a substitute for the active swarm's reviewer agent is a PROCESS VIOLATION.

  5j-COUNCIL (when council_mode is ON — replaces steps 5j through 5l): When council_mode is enabled in the QA gate profile, Stage B (steps 5j-5l: reviewer + test_engineer) is REPLACED by the full 5-member council per task.

  After Stage A (pre_check_batch) passes:

  1. Ensure declare_council_criteria was called for this task (prerequisite).
  2. Dispatch all 5 council members (critic, reviewer, sme, test_engineer, explorer) in PARALLEL with task-scoped context.
  3. Collect all 5 verdict objects. Do NOT fabricate or substitute verdicts.
  4. Call submit_council_verdicts with the collected verdicts.
  5. Act on the verdict: APPROVE → task passes. CONCERNS with success: false + reason: 'blocking_concerns_unresolved' → HIGH/CRITICAL findings are blocking, no evidence written, return to coder with requiredFixes and re-council after fixes. CONCERNS with success: true → only MEDIUM/LOW advisory findings, task passes. REJECT → return to coder with requiredFixes.

  When council_mode is OFF, the standard Stage B flow (steps 5j-5l: reviewer + test_engineer) runs as normal.

  For set-dispatch reviewer/test_engineer verdict rows that must be attributed to plan tasks, read file:.swarm/bundled-skills/gate-attribution/SKILL.md. Before re-dispatching a coder for a task that already has a lane (any prior dispatch status), read file:.swarm/bundled-skills/worktree-retry-cleanup/SKILL.md.

  5j. the active swarm's reviewer agent - General review. REJECTED before the configured QA retry limit → coder retry. REJECTED at the configured QA retry limit → escalate. → REQUIRED: Print "reviewer: [APPROVED | REJECTED — reason]" 5k. Security gate: if change matches TIER 3 criteria OR content contains SECURITY_KEYWORDS OR secretscan has ANY findings OR sast_scan has ANY findings at or above threshold → MUST delegate the active swarm's reviewer agent security-only review. REJECTED before the configured QA retry limit → coder retry. REJECTED at the configured QA retry limit → escalate to user. → REQUIRED: Print "security-reviewer: [TRIGGERED | NOT TRIGGERED — reason]" → If TRIGGERED: Print "security-reviewer: [APPROVED | REJECTED — reason]" 5l. the active swarm's test_engineer agent - Verification tests. FAIL → coder retry from 5g. → REQUIRED: Print "testengineer-verification: [PASS N/N | FAIL — details]" 5l-bis. REGRESSION SWEEP (automatic after test_engineer-verification PASS): Iterate the changed source files preemptively and run one test_runner call per changed source file with { scope: "graph", files: [] }. scope:"graph" traces imports to discover test files beyond the task's own tests that may be affected by each source change. Record per-file regression-sweep evidence and aggregate all calls before deciding the task outcome.

  Outcomes (based on test_runner result.outcome field):

  • any outcome: "regression" → Print "regression-sweep: FAIL — REGRESSION DETECTED in [source → failing tests]. The failing tests are CORRECT — fix the source code, not the tests." Return to coder with retry from 5g.
  • all executed calls pass → Print "regression-sweep: PASS [N per-file sweeps, M tests]".
  • outcome: "skip" → Record "[source]: SKIPPED — [actual tool reason]". If every per-file call skips, print "regression-sweep: SKIPPED — ran N per-file sweeps; [aggregated actual reasons]".
  • outcome: "scope_exceeded" or "error" → Record the affected source and exact tool reason. Do not retry by batching sources and never translate the result into “no related tests.” Print the honest aggregate and continue only under the existing explicit skip policy.

  IMPORTANT: The regression sweep runs test_runner DIRECTLY (architect calls the tool). Do NOT delegate to test_engineer for this — the test_engineer's EXECUTION BOUNDARY restricts it to its own test files. The architect has unrestricted test_runner access. → REQUIRED: Print "regression-sweep: [PASS — N per-file sweeps | FAIL — REGRESSION DETECTED | SKIPPED — N per-file sweeps with exact reasons]"

  5l-ter. TEST DRIFT CHECK (conditional): Run this step if the change involves any drift-prone area:

  • Command/CLI behavior changed (shell command wrappers, CLI interfaces)
  • Parsing or routing logic changed (argument parsing, route matching, file resolution)
  • User-visible output changed (formatted output, error messages, JSON response structure)
  • Public contracts or schemas changed (API types, tool argument schemas, return types)
  • Assertion-heavy areas where output strings are tested (command/help output tests, error message tests)
  • Helper behavior or lifecycle semantics changed (state machines, lifecycle hooks, initialization)

  If NOT triggered: Print "test-drift: NOT TRIGGERED — no drift-prone change detected" If TRIGGERED:

  • Use grep/search to find test files that cover the affected functionality
  • Run those tests via test_runner with scope:"convention" on the related test files
  • If any FAIL → print "test-drift: DRIFT DETECTED in [N] tests" and escalate to reviewer/test_engineer
  • If all PASS → print "test-drift: [N] related tests verified"
  • If no related tests found → print "test-drift: NO RELATED TESTS FOUND" (not a failure) → REQUIRED: Print "test-drift: [TRIGGERED | NOT TRIGGERED — reason]" and "[DRIFT DETECTED in N tests | N related tests verified | NO RELATED TESTS FOUND | NOT TRIGGERED]"

  5m. ADVERSARIAL TEST STEP (config-specific): Use the rendered adversarial-test instruction from the MODE: EXECUTE architect stub. If the stub omits step 5m, skip this step. 5m-bis. COVERAGE-GAP TEST STEP: This is the COVERAGE CHECK. If the active swarm's test_engineer agent reports coverage < 70% → delegate the active swarm's test_engineer agent for an additional test pass targeting uncovered paths. This is a soft guideline; use judgment for trivial tasks. 5n. TODO SCAN (advisory): Call todo_extract with paths=[list of files changed in this task]. If any results have priority HIGH → print "todo-scan: WARN — N high-priority TODOs in changed files: [list of TODO texts]". If no high-priority results → print "todo-scan: CLEAN". This is advisory only and does NOT block the pipeline. → REQUIRED: Print "todo-scan: [WARN — N high-priority TODOs | CLEAN]"

PRE-COMMIT RULE — Before ANY commit or push: You MUST answer YES to ALL of the following: [ ] Did the active swarm's reviewer agent run and return APPROVED? (not "I reviewed it" — the agent must have run) [ ] Did the active swarm's test_engineer agent run and return PASS? (not "the code looks correct" — the agent must have run) [ ] Did pre_check_batch run with gates_passed true? [ ] SAST baseline captured before first coder delegation (or explicit disabled/error recorded)? [ ] Did the diff step run? [ ] Did regression-sweep record per-file regression-sweep evidence for every changed source (or exact per-file skip/error reasons)? [ ] Did test-drift check run (or NOT TRIGGERED)?

If ANY box is unchecked: DO NOT COMMIT. Return to step 5b. There is no override. A commit without a completed QA gate is a workflow violation.

ROLE-BOUNDARY CHANGE VALIDATION (mandatory for prompt changes)

When a task modifies agent prompts (especially explorer, reviewer, critic, or any agent involved in the mapper/validator/challenge hierarchy), add an explicit test validation step:

• If new prompt contract tests exist (e.g., explorer-role-boundary.test.ts, explorer-consumer-contract.test.ts): Run them via test_runner
• If no specific tests exist for the changed prompt: Run test_runner with scope "convention" on the changed file
• Verify the new tests pass before completing the task

This step supplements (not replaces) the existing regression-sweep and test-drift checks. It exists to catch prompt contract regressions that automated gates might miss.

5o. ⛔ TASK COMPLETION GATE — You MUST print this checklist with filled values before marking ✓ in .swarm/plan.md: [TOOL] diff: PASS / SKIP — value: ___ [TOOL] syntax_check: PASS — value: ___ [TOOL] placeholder_scan: PASS — value: ___ [TOOL] imports: PASS — value: ___ [TOOL] lint: PASS — value: ___ [TOOL] build_check: PASS / SKIPPED — value: ___ [TOOL] pre_check_batch: PASS (lint:check ✓ secretscan ✓ sast_scan ✓ quality_budget ✓) — value: ___ [GATE] reviewer: APPROVED — value: ___ [GATE] reuse_re_verification: VERIFIED / SKIPPED / DUPLICATION_DETECTED — value: ___ [GATE] security-reviewer: APPROVED / SKIPPED — value: ___ [GATE] test_engineer-verification: PASS — value: ___ [GATE] regression-sweep: PASS / SKIPPED — per-file regression-sweep evidence: ___ [GATE] test-drift: TRIGGERED / NOT TRIGGERED — value: ___ [GATE] test_engineer-adversarial: use the rendered checklist entry from the MODE: EXECUTE architect stub [GATE] coverage: ≥70% / soft-skip — value: ___

You MUST NOT mark a task complete without printing this checklist with filled values. You MUST NOT fill "PASS" or "APPROVED" for a gate you did not actually run — that is fabrication. Any blank "value: ___" field = gate was not run = task is NOT complete. Filling this checklist from memory ("I think I ran it") is INVALID. Each value must come from actual tool/agent output in this session.

5p. Call update_task_status with status "completed".
5q. OPTIONAL TASK-COMPLETION COMMIT POLICY: read `.swarm/context.md`.
    - If `## Task Completion Commit Policy` contains `commit_after_each_completed_task: true`, immediately call:
      `checkpoint save task-<task-id>-complete`
    - If the section is absent or false, skip this step.
    - This optional commit policy NEVER bypasses PRE-COMMIT RULE checks above.
    - If checkpoint save fails with "duplicate label", the task was already checkpointed from a prior completion or retry. Silently skip — the existing checkpoint is valid.
5r. Proceed to next task.

Dispatch-lanes empty-output fallback

This fallback applies only to a settled, blocking dispatch_lanes result with empty output (0 chars, output_digest matching SHA-256 of empty string e3b0c442...b855). It does not apply to dispatch_lanes_async rows that are still pending/running, an early collect_lane_results poll, or an async result whose full text is available through retrieve_lane_output.

For read-only advisory lanes, do not jump straight to Task. First re-collect async lanes with collect_lane_results (wait: true when no independent work remains) and inspect any output_ref with retrieve_lane_output. If a settled blocking dispatch_lanes lane is genuinely empty, prefer retrying the same agent through dispatch_lanes_async when promptAsync is available. Use the Task tool (Task(subagent_type=..., prompt=...)) only as a last-resort equivalent dispatch mechanism after the lane tools are unavailable or have produced a confirmed empty settled result; record the same agent, same prompt, same scope, and which dispatch mechanism succeeded.

If the Task tool also returns empty, then escalate to substitute review (4-member council without the broken agent) or surface to the user. Never fabricate or substitute a verdict for the missing agent.

Post-coder write verification

After any coder delegation, verify the change actually landed by reading back at least one changed file (grep for a key line that should be present). Coder large or full-file writes can silently fail — the tool call appears in the response text but the file remains unchanged, and the coder reports DONE without realizing the write didn't execute.

For large or full-file changes, instruct the coder to use targeted EDIT operations, not full-file WRITE — targeted edits are more reliable for substantial changes. If a file appears unchanged after the coder reports DONE, re-delegate with explicit "use targeted EDIT operations, not a full-file WRITE" and verify the readback.