role-os 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 2.3.0
+
+### Added
+
+#### Dogfood Swarm Mission — Multi-Pass Health + Feature Convergence
+
+- **Dogfood swarm mission** — 9th mission in the library. Three-stage health pass (bug/security → proactive → humanization) then iterative feature pass with exclusive file ownership, build gates, and user checkpoints. Moves a repo from "works" to "production-ready." Proven on claude-collaborate (35→129 tests, 106 findings fixed, v1.1.0 shipped).
+- **7 new roles** — Swarm Coordinator, Swarm Backend Agent, Swarm Bridge Agent, Swarm Tests Agent, Swarm Infra Agent, Swarm Frontend Agent, Swarm Synthesizer (61 total roles)
+- **Swarm team pack** — 10th pack, 8 roles (7 swarm + Critic Reviewer), with mismatch guards and trial evidence
+- **Two new mission primitives**:
+  - `waveLoops` — iterative convergence with exit conditions, max iterations, build gates, and user approval flags
+  - `exclusiveOwnership` — strict domain file boundaries enforced by manifest
+- **Dynamic domain dispatch** — scales agent count based on repo structure via `swarm-manifest.json`
+- **`roleos swarm` CLI** — first-class entry point with subcommands: `swarm`, `swarm manifest`, `swarm manifest --generate`, `swarm status`, `swarm findings`, `swarm approve`, `swarm verify`
+- **Domain detection** (`src/swarm/domain-detect.mjs`) — auto-detects repo type (CLI, web, desktop, MCP, monorepo) and generates domain manifests with non-overlapping file ownership
+- **Build gate** (`src/swarm/build-gate.mjs`) — auto-detects build system (Node, Rust, Python, Go) and runs lint → typecheck → test verification after every wave
+- **Evidence persistence bridge** (`src/swarm/persist-bridge.mjs`) — optional connection back to dogfood-labs, converts wave results to dogfood submission + audit DB payloads
+- **7 artifact contracts** — `swarm-gate`, `wave-report` (×5 with domain-specific sections), `swarm-final-report`
+- **Pack handoff contract** for swarm flow
+
+### Tests
+- 97 new tests (swarm core, domain detection, build gate, persist bridge) — total: 1150
+
+## 2.2.1
+
+### Added
+- **`roleos audit` CLI** — first-class entry point for deep audit with subcommands: `audit`, `audit manifest`, `audit manifest --generate`, `audit status`, `audit verify`
+- **Shared state machine** (`src/state-machine.mjs`) — canonical step/run transitions shared by both runners
+- **Shared tool profiles** (`src/tool-profiles.mjs`) — extracted from dispatch.mjs to break trial→dispatch coupling
+
+### Fixed
+- **P3-1:** Cycle detection in composite execution (`detectCycles` + visited-set guard in `findUnreachable`)
+- **P3-2:** Dual-active guard in `startNext`/`startNextStep` prevents two steps active simultaneously
+- **P3-3:** Atomic persistence — `saveRun` writes to temp file then renames
+- **P4-1:** Dependency Auditor has own artifact contract (`dependency-audit`), pack handoff corrected
+- **P4-2:** `partitionBrief` returns topic-only for unknown roles instead of full brief
+- **P4-3:** Atom kind normalization layer bridges scout `.kind` and atom `.claim_kind`
+- **P4-4:** `/dev/stdin` → `readFileSync(0)` for Windows compatibility in all 5 hooks
+- **P4-5:** TOOL_PROFILES extracted to shared module, eliminating trial→dispatch coupling
+- Node 18 compatibility fix for `import.meta.dirname` in deep-audit-proof test
+
+### Tests
+- 18 new tests (audit-cmd, audit-p5, deep-audit-proof) — total: 954
+
 ## 2.2.0
 
 ### Added

package/README.md

@@ -13,7 +13,7 @@
   <a href="https://mcp-tool-shop-org.github.io/role-os/"><img src="https://img.shields.io/badge/Landing_Page-live-brightgreen" alt="Landing Page"></a>
 </p>
 
-A multi-Claude operating system that staffs, routes, validates, and runs work through 54 specialized role contracts. Creates task packets, assembles the right team from scored role matching, detects broken chains before execution, auto-routes recovery when work is blocked or rejected, and requires structured evidence in every verdict. Includes dynamic dispatch for manifest-scaled missions — a 10-component repo automatically becomes 28 auditor steps, not 6.
+A multi-Claude operating system that staffs, routes, validates, and runs work through 61 specialized role contracts. Creates task packets, assembles the right team from scored role matching, detects broken chains before execution, auto-routes recovery when work is blocked or rejected, and requires structured evidence in every verdict. Includes dynamic dispatch for manifest-scaled missions — a 10-component repo automatically becomes 28 auditor steps, not 6. The dogfood swarm mission runs multi-pass convergence: three health stages then iterative feature delivery with exclusive file ownership and build gates.
 
 ## What it does
 
@@ -44,9 +44,9 @@ roleos start "something completely novel"
 
 **The fallback ladder:**
 
-1. **Mission** — when the task matches a proven recurring workflow (bugfix, treatment, feature-ship, docs, security, research, brainstorm, deep-audit). Known role chain, artifact flow, escalation branches, and honest-partial definitions.
-2. **Pack** — when the task is a known family but not a full mission shape. 9 calibrated team packs with auto-selection and mismatch guards.
-3. **Free routing** — when the task is novel, mixed, or uncertain. Scores all 54 roles against packet content and assembles a dynamic chain.
+1. **Mission** — when the task matches a proven recurring workflow (bugfix, treatment, feature-ship, docs, security, research, brainstorm, deep-audit, dogfood-swarm). Known role chain, artifact flow, escalation branches, and honest-partial definitions.
+2. **Pack** — when the task is a known family but not a full mission shape. 10 calibrated team packs with auto-selection and mismatch guards.
+3. **Free routing** — when the task is novel, mixed, or uncertain. Scores all 61 roles against packet content and assembles a dynamic chain.
 
 The system never forces work through the wrong abstraction. It explains why it chose each level and offers alternatives.
 
@@ -103,7 +103,7 @@ Full treatment is a canonical 7-phase protocol defined in Claude project memory
 
 Order: Shipcheck first, then full treatment. No v1.0.0 without passing hard gates.
 
-## 54 roles across 9 packs
+## 61 roles across 10 packs
 
 | Pack | Roles |
 |------|-------|
@@ -116,6 +116,7 @@ Order: Shipcheck first, then full treatment. No v1.0.0 without passing hard gate
 | **Research** (4) | UX Researcher, Competitive Analyst, Trend Researcher, User Interview Synthesizer |
 | **Growth** (4) | Launch Strategist, Content Strategist, Community Manager, Support Triage Lead |
 | **Deep Audit** (4) | Component Auditor, Test Truth Auditor, Seam Auditor, Audit Synthesizer |
+| **Swarm** (7) | Swarm Coordinator, Swarm Backend Agent, Swarm Bridge Agent, Swarm Tests Agent, Swarm Infra Agent, Swarm Frontend Agent, Swarm Synthesizer |
 
 Every role has a full contract: mission, use when, do not use when, expected inputs, required outputs, quality bar, and escalation triggers. Every role is routable — `roleos route` can recommend any of them based on packet content.
 
@@ -134,6 +135,19 @@ roleos complete artifact.md    # Complete with artifact
 roleos explain                 # Show full state
 roleos report                  # Completion report
 
+# Deep audit:
+roleos audit manifest --generate   # Create audit-manifest.json
+roleos audit                       # Start component-level deep audit
+roleos audit status                # Check audit progress
+roleos audit verify                # Verify manifest and outputs
+
+# Dogfood swarm:
+roleos swarm manifest --generate   # Auto-detect domains from repo structure
+roleos swarm                       # Start multi-pass convergence swarm
+roleos swarm status                # Check swarm progress by stage
+roleos swarm findings              # List findings by severity
+roleos swarm approve               # Approve feature gate
+
 # Or go manual:
 roleos start "fix the crash"   # Entry decision only (no run)
 roleos packet new feature
@@ -207,18 +221,23 @@ role-os/
     entry-cmd.mjs              ← `roleos start` CLI command
     run.mjs                    ← Persistent run engine: create → step → pause → resume → report
     run-cmd.mjs                ← `roleos run/resume/next/explain/complete/fail` + interventions
-    mission.mjs                ← 7 named mission types (feature, bugfix, treatment, docs, security, research, brainstorm)
+    mission.mjs                ← 9 named mission types (feature, bugfix, treatment, docs, security, research, brainstorm, deep-audit, dogfood-swarm)
     mission-run.mjs            ← Mission runner: create → step → complete → report
     mission-cmd.mjs            ← `roleos mission` CLI commands
-    route.mjs                  ← 54-role routing + dynamic chain builder
-    packs.mjs                  ← 9 calibrated team packs + auto-selection
+    audit-cmd.mjs              ← `roleos audit` — deep audit entry point with manifest generation
+    swarm-cmd.mjs              ← `roleos swarm` — dogfood swarm entry point with domain detection
+    swarm/                     ← Domain detection, build gate, evidence persistence bridge
+    route.mjs                  ← 61-role routing + dynamic chain builder
+    packs.mjs                  ← 10 calibrated team packs + auto-selection
     conflicts.mjs              ← 4-pass conflict detection
     escalation.mjs             ← Auto-routing for blocked/rejected/split
     evidence.mjs               ← Structured evidence + role-aware requirements
     dispatch.mjs               ← Runtime dispatch manifests for multi-claude
+    tool-profiles.mjs          ← Per-role tool sandboxing (shared by dispatch + trial)
+    state-machine.mjs          ← Canonical step/run transition maps
     artifacts.mjs              ← Per-role artifact contracts + pack handoffs
     decompose.mjs              ← Composite task detection + splitting
-    composite.mjs              ← Dependency-ordered execution + recovery
+    composite.mjs              ← Dependency-ordered execution + recovery + cycle detection
     replan.mjs                 ← Mid-run adaptive replanning
     calibration.mjs            ← Outcome recording + weight tuning
     hooks.mjs                  ← 5 lifecycle hooks for runtime enforcement
@@ -226,7 +245,7 @@ role-os/
     brainstorm.mjs             ← Evidence modes, request validation, finding/synthesis/judge schemas
     brainstorm-roles.mjs       ← Role-native schemas, input partitioning, blindspot enforcement, cross-exam
     brainstorm-render.mjs      ← Two-layer rendering: lexical bans, render schemas, debate transcript
-  test/                        ← 936 tests across 31 test files
+  test/                        ← 1150 tests across 37 test files
   starter-pack/                ← Drop-in role contracts, policies, schemas, workflows
 ```
 
@@ -238,14 +257,14 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 
 | Layer | What it does | Status |
 |-------|-------------|--------|
-| **Routing** | Scores all 54 roles against packet content, explains recommendations, assesses confidence | ✓ Shipped |
+| **Routing** | Scores all 61 roles against packet content, explains recommendations, assesses confidence | ✓ Shipped |
 | **Chain builder** | Assembles phase-ordered chains from scored roles, packet-type biased not template-locked | ✓ Shipped |
 | **Conflict detection** | 4-pass validation: hard conflicts, sequence, redundancy, coverage gaps. Repair suggestions. | ✓ Shipped |
 | **Escalation** | Auto-routes blocked/rejected/split work to the right resolver with reason + required artifact | ✓ Shipped |
 | **Evidence** | Role-aware structured evidence in verdicts. Sufficiency checks. 12 evidence kinds. | ✓ Shipped |
 | **Dispatch** | Generates execution manifests for multi-claude. Per-role tool profiles, system prompts, budgets. | ✓ Shipped |
 | **Trials** | Full roster proven: 30/30 gold-task + 5/5 negative trials. 7 pack trials complete. | ✓ Complete |
-| **Team Packs** | 9 calibrated packs with auto-selection, mismatch guards, and free-routing fallback. | ✓ Shipped |
+| **Team Packs** | 10 calibrated packs with auto-selection, mismatch guards, and free-routing fallback. | ✓ Shipped |
 | **Outcome calibration** | Records run outcomes, tunes pack/role weights from results, adjusts confidence thresholds. | ✓ Shipped |
 | **Mixed-task decomposition** | Detects composite work, splits into child packets, assigns packs, preserves dependencies. | ✓ Shipped |
 | **Composite execution** | Runs child packets in dependency order with artifact passing, branch recovery, and synthesis. | ✓ Shipped |
@@ -253,14 +272,15 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 | **Session spine** | `roleos init claude` scaffolds CLAUDE.md, /roleos-route, /roleos-review, /roleos-status. `roleos doctor` verifies wiring. Route cards prove engagement. | ✓ Shipped |
 | **Hook spine** | 5 lifecycle hooks (SessionStart, PromptSubmit, PreToolUse, SubagentStart, Stop). Advisory enforcement: route card reminders, write-tool gating, subagent role injection, completion audit. | ✓ Shipped |
 | **Artifact spine** | Per-role artifact contracts. Pack handoff contracts. Structural validation. Chain completeness checks. Downstream roles never guess what they received. | ✓ Shipped |
-| **Mission library** | 8 named missions (feature-ship, bugfix, treatment, docs-release, security-hardening, research-launch, brainstorm, deep-audit). Each declares pack, role chain, artifact flow, escalation branches, honest-partial definition. | ✓ Shipped |
+| **Mission library** | 9 named missions (feature-ship, bugfix, treatment, docs-release, security-hardening, research-launch, brainstorm, deep-audit, dogfood-swarm). Each declares pack, role chain, artifact flow, escalation branches, honest-partial definition. | ✓ Shipped |
 | **Mission runner** | Create runs, step through with tracked state, complete/fail with honest reporting. Blocked-step propagation, out-of-chain escalation warnings, last-step re-opening. | ✓ Shipped |
 | **Unified entry** | `roleos start` decides mission vs pack vs free routing automatically. Fallback ladder with confidence scores, alternatives, and composite detection. | ✓ Shipped |
 | **Persistent runs** | `roleos run` creates disk-backed runs. `resume`, `next`, `explain`, `complete`, `fail`. Interventions: reroute, escalate, retry, block, reopen. Step-local guidance. Friction measurement. | ✓ Shipped |
 | **Brainstorm** | Two-layer architecture: truth (role-native schemas, provenance atoms, cross-exam dispute graph) + render (5 distinct voices, lexical bans, debate transcript). Trace links prove every rendered claim maps to a truth atom. Golden run proven. | ✓ Shipped |
 | **Deep Audit** | Manifest-scaled repo audit: decompose repo into components, dispatch N auditors + M test truth auditors + K seam auditors from dependency graph, synthesize into ranked verdict and action plan. Dynamic dispatch scales with repo size (2N + K + 3 formula). Runner-native with artifact validation at every step. | ✓ Shipped |
+| **Dogfood Swarm** | Multi-pass convergence: three health stages (bug/security → proactive → humanization) then feature pass. Exclusive file ownership, build gates after every wave, user checkpoints. Domain auto-detection generates manifests. Evidence bridge to dogfood-labs. | ✓ Shipped |
 
-## 8 missions
+## 9 missions
 
 | Mission | Pack | Roles | When to use |
 |---------|------|-------|-------------|
@@ -272,6 +292,7 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 | `research-launch` | research | 4 | Frame question, research, document findings, decide |
 | `brainstorm` | brainstorm | 9 | Structured multi-perspective inquiry with traceable disagreement and verdict |
 | `deep-audit` | deep-audit | 5 (scales) | Manifest-backed repo audit — worker count scales with repo graph via dynamic dispatch |
+| `dogfood-swarm` | swarm | 8 (scales) | Multi-pass convergence: health-a → health-b → health-c → feature → final synthesis |
 
 Each mission includes honest-partial definitions — when work stalls, the system documents what was completed and what remains instead of bluffing completion.
 
@@ -315,6 +336,28 @@ roleos run "deep audit this repo" --manifest=audit-manifest.json
 
 **Proven:** Runner-native proof run — 18 tests against real manifest, full lifecycle verified including escalation re-opening and partial failure. Scaling formula verified for 3/6/10/15-component manifests.
 
+### Dogfood swarm mission
+
+Not a one-pass linter. The dogfood swarm mission **runs a multi-pass convergence protocol that moves a repo from "works" to "production-ready" through three health stages and iterative feature delivery.**
+
+```bash
+roleos swarm
+# → MISSION: Dogfood Swarm (Multi-Pass Convergence)
+#   Stages: Health-A → Health-B → Health-C → Feature → Final
+#   Domain agents: 3-5 parallel per wave (exclusive file ownership)
+```
+
+**What makes it different:**
+
+- **Three-stage health pass** — Stage A fixes bugs and security issues (loop until 0 CRITICAL + 0 HIGH). Stage B applies proactive hardening (user reviews findings). Stage C humanizes the codebase — error messages that help users, reconnection feedback, loading states, accessibility. Each stage is a distinct lens, not the same scan repeated.
+- **Exclusive file ownership** — every domain agent owns specific files via `swarm-manifest.json`. No two agents edit the same file. No merge conflicts. No coordination overhead.
+- **Build gates** — lint + typecheck + test must pass after every wave. The system auto-detects the build system (Node, Rust, Python, Go) and runs the right commands.
+- **User checkpoints** — Health-B and the feature pass require explicit user approval before execution. The system presents findings, the user decides what to build.
+- **Iterative convergence** — stages loop with wave loops until exit conditions are met or max iterations reached. Each wave re-audits from scratch to catch regressions introduced by previous fixes.
+- **Domain auto-detection** — `roleos swarm manifest --generate` detects repo type (CLI, web, desktop, MCP, monorepo) and generates non-overlapping domain assignments.
+
+**Proven:** claude-collaborate (2026-03-28) — 35→129 tests, 106 health findings fixed, v1.1.0 shipped. Protocol v2.0 with 9 phases.
+
 ## Status
 
 - v0.1–v0.4: Foundation — trials, adoption, treatment pack, starter pack
@@ -333,6 +376,7 @@ roleos run "deep audit this repo" --manifest=audit-manifest.json
 - **v2.0.1**: Handbook audit, beginner docs, test count corrections. 617 tests.
 - **v2.1.0**: Brainstorm mission (v0.4) — specialized roles under law, traceable disagreement, verdict-bearing output. Two-layer architecture (truth + render), cross-exam permission matrix, dispute graph, golden run proof. 7 missions, 50 roles, 8 packs. 894 tests.
 - **v2.2.0**: Deep Audit mission — manifest-scaled repo audit with dynamic dispatch. 4 new audit roles (Component Auditor, Test Truth Auditor, Seam Auditor, Audit Synthesizer). Worker count scales with repo graph (2N + K + 3 formula). Artifact validation wired at both execution boundaries. Runner-native proof run green. accept/approve truth fix in evidence layer. 8 missions, 54 roles, 9 packs. 936 tests.
+- **v2.3.0**: Dogfood Swarm mission — multi-pass convergence (health-a → health-b → health-c → feature → final). 7 new swarm roles (Swarm Coordinator, 5 domain agents, Swarm Synthesizer). Two new mission primitives: waveLoops (iterative convergence) and exclusiveOwnership (domain file boundaries). Dynamic domain dispatch, build gates, `roleos swarm` CLI, domain auto-detection, evidence persistence bridge. 9 missions, 61 roles, 10 packs. 1150 tests.
 
 ## License
 

package/bin/roleos.mjs

@@ -12,6 +12,8 @@ import { packsCommand } from "../src/packs-cmd.mjs";
 import { scaffoldClaude, doctor, formatDoctor } from "../src/session.mjs";
 import { artifactsCommand } from "../src/artifacts-cmd.mjs";
 import { missionCommand } from "../src/mission-cmd.mjs";
+import { auditCommand } from "../src/audit-cmd.mjs";
+import { swarmCommand } from "../src/swarm-cmd.mjs";
 import { startCommand } from "../src/entry-cmd.mjs";
 import {
   runCommand, resumeCommand, nextCommand, explainCommand,
@@ -59,6 +61,18 @@ Usage:
   roleos artifacts show <role>       Show artifact contract for a role
   roleos artifacts validate <role> <file>  Validate a file against a contract
   roleos artifacts chain <pack>      Show pack handoff flow
+  roleos audit                        Start a deep audit on the current repo
+  roleos audit manifest               Show the audit manifest
+  roleos audit manifest --generate    Generate a skeleton manifest from src/
+  roleos audit status                 Show audit run progress
+  roleos audit verify                 Verify manifest and audit outputs
+  roleos swarm                        Start a dogfood swarm on the current repo
+  roleos swarm manifest               Show the swarm manifest
+  roleos swarm manifest --generate    Auto-detect domains and generate manifest
+  roleos swarm status                 Show swarm run progress
+  roleos swarm findings               List findings by severity
+  roleos swarm approve                Approve the current feature gate
+  roleos swarm verify                 Verify manifest and run state
   roleos mission list                List all missions
   roleos mission show <key>          Show full mission detail
   roleos mission suggest <text>      Suggest a mission for a task
@@ -181,6 +195,12 @@ try {
     case "friction":
       await frictionCommand(args);
       break;
+    case "audit":
+      await auditCommand(args);
+      break;
+    case "swarm":
+      await swarmCommand(args);
+      break;
     case "mission":
       await missionCommand(args);
       break;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "role-os",
-  "version": "2.2.0",
-  "description": "Role OS — a multi-Claude operating system where 54 specialized roles execute work through contracts, conflict detection, escalation, and structured evidence. 9 team packs, 8 missions including deep audit with manifest-scaled dynamic dispatch and brainstorm with traceable disagreement.",
+  "version": "2.3.0",
+  "description": "Role OS — a multi-Claude operating system where 61 specialized roles execute work through contracts, conflict detection, escalation, and structured evidence. 10 team packs, 9 missions including dogfood swarm (multi-pass convergence), deep audit with manifest-scaled dynamic dispatch, and brainstorm with traceable disagreement.",
   "homepage": "https://mcp-tool-shop-org.github.io/role-os/",
   "bugs": {
     "url": "https://github.com/mcp-tool-shop-org/role-os/issues"

package/src/artifacts.mjs

@@ -106,6 +106,14 @@ export const ROLE_ARTIFACT_CONTRACTS = {
     consumedBy: ["Backend Engineer", "Coverage Auditor", "Security Reviewer"],
     completionRule: "Entrypoints listed. Module responsibilities described. Commands documented.",
   },
+  "Dependency Auditor": {
+    artifactType: "dependency-audit",
+    requiredSections: ["vulnerability-summary", "outdated-inventory"],
+    optionalSections: ["supply-chain-risks", "update-recommendations", "license-audit"],
+    requiredEvidence: [],
+    consumedBy: ["Critic Reviewer", "Security Reviewer"],
+    completionRule: "Vulnerabilities triaged. Outdated deps inventoried with severity.",
+  },
   "Metadata Curator": {
     artifactType: "metadata-audit",
     requiredSections: ["manifest-audit", "registry-alignment"],
@@ -290,6 +298,64 @@ export const ROLE_ARTIFACT_CONTRACTS = {
     consumedBy: ["Critic Reviewer"],
     completionRule: "Reconciles findings across parcels. Cross-cutting findings reference source parcels. Contradictions adjudicated. Action plan groups by root cause and leverage.",
   },
+
+  // ── Dogfood Swarm ───────────────────────────────────────────────────────────
+  "Swarm Coordinator": {
+    artifactType: "swarm-gate",
+    requiredSections: ["phase", "stage", "wave-count", "findings-summary", "severity-breakdown", "exit-condition-status", "decision"],
+    optionalSections: ["build-gate-results", "user-approval-status"],
+    requiredEvidence: ["wave-report"],
+    consumedBy: ["Swarm Backend Agent", "Swarm Bridge Agent", "Swarm Tests Agent", "Swarm Infra Agent", "Swarm Frontend Agent", "Swarm Synthesizer"],
+    completionRule: "Exit condition evaluated against accumulated findings. Decision is one of: loop (re-run wave), advance (next stage), or halt (max iterations or build gate failure).",
+  },
+  "Swarm Backend Agent": {
+    artifactType: "wave-report",
+    requiredSections: ["findings", "remediations", "files-touched", "build-status"],
+    optionalSections: ["architecture-notes"],
+    requiredEvidence: [],
+    consumedBy: ["Swarm Coordinator"],
+    completionRule: "Every file in assigned scope inspected. Findings severity-triaged. Remediations applied in severity order. Build passes after changes.",
+  },
+  "Swarm Bridge Agent": {
+    artifactType: "wave-report",
+    requiredSections: ["findings", "remediations", "files-touched", "build-status"],
+    optionalSections: ["integration-notes"],
+    requiredEvidence: [],
+    consumedBy: ["Swarm Coordinator"],
+    completionRule: "Every file in assigned scope inspected. Findings severity-triaged. Remediations applied in severity order. Build passes after changes.",
+  },
+  "Swarm Tests Agent": {
+    artifactType: "wave-report",
+    requiredSections: ["findings", "remediations", "files-touched", "build-status", "coverage-delta"],
+    optionalSections: ["test-health-notes"],
+    requiredEvidence: [],
+    consumedBy: ["Swarm Coordinator"],
+    completionRule: "Test suite audited for gaps, ceremonial tests, and fixture quality. Coverage delta reported. Build passes after changes.",
+  },
+  "Swarm Infra Agent": {
+    artifactType: "wave-report",
+    requiredSections: ["findings", "remediations", "files-touched", "build-status"],
+    optionalSections: ["ci-notes", "doc-freshness"],
+    requiredEvidence: [],
+    consumedBy: ["Swarm Coordinator"],
+    completionRule: "CI workflows, config files, and docs inspected. Findings severity-triaged. Build passes after changes.",
+  },
+  "Swarm Frontend Agent": {
+    artifactType: "wave-report",
+    requiredSections: ["findings", "remediations", "files-touched", "build-status", "accessibility-issues"],
+    optionalSections: ["ux-improvements", "responsive-notes"],
+    requiredEvidence: [],
+    consumedBy: ["Swarm Coordinator"],
+    completionRule: "UI layer audited for bugs, accessibility, and UX. Accessibility issues listed separately. Build passes after changes.",
+  },
+  "Swarm Synthesizer": {
+    artifactType: "swarm-final-report",
+    requiredSections: ["executive-summary", "stage-results", "total-findings-fixed", "remaining-items", "test-verification", "recommendation"],
+    optionalSections: ["metrics-comparison", "evidence-links"],
+    requiredEvidence: ["swarm-gate", "wave-report"],
+    consumedBy: ["Critic Reviewer"],
+    completionRule: "All stages summarized. Total findings fixed vs remaining tallied. Final test suite run. Recommendation is ship, hold, or re-swarm.",
+  },
 };
 
 // ── Artifact validation ───────────────────────────────────────────────────────
@@ -380,7 +446,7 @@ export const PACK_HANDOFF_CONTRACTS = {
   security: {
     flow: [
       { role: "Security Reviewer", produces: "security-findings", consumedBy: "Critic Reviewer" },
-      { role: "Dependency Auditor", produces: "metadata-audit", consumedBy: "Critic Reviewer" },
+      { role: "Dependency Auditor", produces: "dependency-audit", consumedBy: "Critic Reviewer" },
       { role: "Critic Reviewer", produces: "verdict", consumedBy: null },
     ],
   },
@@ -441,6 +507,18 @@ export const PACK_HANDOFF_CONTRACTS = {
       { role: "Critic Reviewer",    produces: "verdict",                consumedBy: null },
     ],
   },
+  swarm: {
+    flow: [
+      { role: "Swarm Coordinator",    produces: "swarm-gate",         consumedBy: "Swarm Backend Agent" },
+      { role: "Swarm Backend Agent",  produces: "wave-report",        consumedBy: "Swarm Coordinator" },
+      { role: "Swarm Bridge Agent",   produces: "wave-report",        consumedBy: "Swarm Coordinator" },
+      { role: "Swarm Tests Agent",    produces: "wave-report",        consumedBy: "Swarm Coordinator" },
+      { role: "Swarm Infra Agent",    produces: "wave-report",        consumedBy: "Swarm Coordinator" },
+      { role: "Swarm Frontend Agent", produces: "wave-report",        consumedBy: "Swarm Coordinator" },
+      { role: "Swarm Synthesizer",    produces: "swarm-final-report", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer",      produces: "verdict",            consumedBy: null },
+    ],
+  },
 };
 
 /**