Gated Pipeline and QA Gates

Relevant source files

The following files were used as context for generating this wiki page:

• src/agents/architect.ts
• src/agents/reviewer.ts
• src/hooks/guardrails.ts
• src/tests/qa-gate-hardening.test.ts
• src/agents/critic.ts
• src/commands/registry.ts

The Gated Pipeline is a multi-stage enforcement mechanism within the OpenCode Swarm project designed to ensure code quality, security, and architectural alignment. It operates through a series of automated tool checks (Stage A) and manual-style agent reviews (Stage B), preventing the progression of tasks or phases until specific quality criteria—known as QA Gates—are met. This system is managed by the Architect agent and enforced by runtime Guardrails.

The pipeline serves as a hard enforcement mechanism; if required gates are bypassed, the system blocks subsequent implementation work until compliance is restored. This architecture ensures that all code changes, regardless of perceived complexity, undergo rigorous scrutiny before being finalized.

Sources: src/agents/architect.ts:28-44, src/hooks/guardrails.ts:133-140

Two-Stage QA Pipeline

The QA process is divided into two primary stages that must be completed for every implementation task.

Stage A: Automated Tool Gates

Stage A consists of a batch of automated checks that return binary pass/fail results. Passing Stage A indicates that the code is technically valid (compiles, parses, and meets formatting standards) but does not guarantee correctness or security.

• Sequence: diff → syntax_check → placeholder_scan → imports → lint → build_check → pre_check_batch.
• Enforcement: Failures in Stage A require the Coder agent to perform a retry.

Stage B: Agent Review Gates

Stage B involves specialized agents that perform qualitative analysis of the changes. This stage is where logic errors, security flaws, and architectural drift are identified.

• Reviewer Agent: Evaluates correctness, security, and edge cases.
• Security Reviewer: A conditional pass focused on OWASP vulnerabilities.
• Test Engineer: Generates and executes functional and adversarial tests.
• Critic Agent: Performs drift verification at the end of a phase.

Sources: src/agents/architect.ts:317-345, src/hooks/guardrails.ts:1145-1170

Tiered QA Classifications

The pipeline intensity is determined by the "Tier" of the files changed. The Architect agent classifies tasks into one of four tiers, which dictates which gates are mandatory.

Tier	Name	Target Files	Mandatory Pipeline
Tier 0	Metadata	plan.json, context.md, evidence	lint + diff only. No Stage B.
Tier 1	Documentation	*.md (outside .swarm/), README	Stage A + 1x reviewer.
Tier 2	Standard Code	src/, test/, package.json	Full Stage A + reviewer + test_engineer.
Tier 3	Critical	Security files, auth*, guardrails*	Full Stage A + 2x reviewer + 2x test_engineer.

Sources: src/agents/architect.ts:285-315

Configurable QA Gates

The project defines eleven distinct gates that can be toggled via the set_qa_gates tool or the /swarm qa-gates command. Most gates are enabled by default.

Gate Name	Default	Description
reviewer	ON	Code review of coder output by @reviewer.
test_engineer	ON	Test verification of output by @test_engineer.
sme_enabled	ON	Domain expert consultation during planning.
critic_pre_plan	ON	Critic review of the plan before implementation starts.
sast_enabled	ON	Static security scanning during automated checks.
drift_check	ON	Verifies changes against spec.md intent at phase end.
council_mode	OFF	Multi-agent council review for high-impact phases.
hallucination_guard	OFF	Verifies API references and citations at phase end.
mutation_test	OFF	Runs mutation testing to identify coverage gaps.
council_gen_review	OFF	Council review of the specification itself.
final_council	OFF	Holistic project-scope review after all phases.

Sources: src/agents/architect.ts:748-775, src/tests/qa-gate-hardening.test.ts:40-60

Runtime Enforcement (Guardrails)

Guardrails are implemented as runtime hooks that intercept tool calls to ensure the Gated Pipeline protocol is followed.

Partial Gate Violation

If an Architect attempts to mark a task as complete or move to a new task without running the mandatory gates for the current task tier, the system flags a PARTIAL_GATE_VIOLATION. The next coder delegation will be physically blocked by the plugin until the missing gates are executed.

Spec Drift Block

If the system detects that the implementation has diverged from the specification (spec drift), a marker file .swarm/spec-staleness.json is created. While this file exists, all plan-mutating tools—such as save_plan, update_task_status, and phase_complete—are structurally blocked.

Sources: src/hooks/guardrails.ts:133-145, src/hooks/guardrails.ts:1455-1500

The Phase Council

For high-impact or security-sensitive work, the council_mode gate enables a Phase-level Dossier Assembly. This occurs after all tasks in a phase are complete but before phase_complete is called.

Mandatory Council Sequence

1. Dispatch: Five members (critic, reviewer, sme, test_engineer, explorer) are dispatched in parallel.
2. Collect: The Architect extracts CouncilMemberVerdict objects (APPROVE, CONCERNS, or REJECT).
3. Submit: The Architect calls submit_phase_council_verdicts.
4. Verdict Action:
   • APPROVE: Advanced to phase_complete.
   • CONCERNS: Significant concerns must be resolved by the Coder.
   • REJECT: Advancement is blocked; the phase must be reworked.

Sources: src/agents/architect.ts:650-700

Conclusion

The Gated Pipeline and its associated QA Gates form the backbone of the Swarm's autonomous quality control. By combining tiered classification, automated verification, and specialized agent councils, the system enforces a "security-by-default" and "quality-by-default" posture that prevents the accumulation of technical debt or the introduction of logic flaws during automated development cycles.

Sources: src/agents/architect.ts:28-44, src/agents/reviewer.ts:180-200