swarm-orchestrator 7.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, moonrunnerkc
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+<div align="center">
+
+<img src="assets/header.svg" alt="Swarm Orchestrator" width="100%">
+
+# Swarm Orchestrator
+
+**Independent verification battery for patches written by AI coding agents.**
+
+[![License](https://img.shields.io/badge/license-ISC-blue?style=flat-square)](LICENSE)
+[![Version](https://img.shields.io/badge/version-7.0.0--alpha.0-orange?style=flat-square)](package.json)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square)](package.json)
+[![CI](https://img.shields.io/github/actions/workflow/status/moonrunnerkc/swarm-orchestrator/ci.yml?branch=main&label=ci&style=flat-square)](https://github.com/moonrunnerkc/swarm-orchestrator/actions/workflows/ci.yml)
+[![Stars](https://img.shields.io/github/stars/moonrunnerkc/swarm-orchestrator?style=flat-square)](https://github.com/moonrunnerkc/swarm-orchestrator/stargazers)
+
+[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Documentation](#documentation) · [Contributing](#contributing)
+
+</div>
+
+---
+
+> Wraps third-party coding-agent CLIs (Copilot, Claude Code, Codex), runs worker and reviewer steps on isolated git branches, and applies a five-layer falsification battery to each agent-authored patch. Hard gates block patches that fail intent or regression checks; advisory layers feed a composite score.
+
+You run this around an agent CLI, not instead of one. The agent produces the patch; the orchestrator tries to break it. Patches that survive merge to `main`; patches that don't are rolled back with a verification report.
+
+## Features
+
+- **Five-layer falsification battery.** Intent verification, regression and mutation testing, cheat detection, property-based testing, and signed attestation. Layers 1 and 2 are hard gates; layers 3 to 5 feed an advisory composite score. Implementations live under `src/verification/`.
+- **Isolated worker and reviewer steps.** Each step runs on its own git branch and worktree. Worker writes; reviewer is read-only and synthesises differential tests or reviews the diff against an active policy.
+- **Analyzer-gated parallelism.** A static dependency analyser (`src/scheduling/dependency-analyzer.ts`) decides which steps can run in parallel. The planner does not declare independence.
+- **Quality-gate engine.** Nine built-in gates (`scaffoldDefaults`, `duplicateBlocks`, `hardcodedConfig`, `readmeClaims`, `testIsolation`, `runtimeChecks`, `accessibility`, `testCoverage`, `testFileProtection`) registered in `src/quality-gates/registry.ts`. Projects register custom gates via `.swarm/gates/index.js`.
+- **Signed attestation.** In-toto SLSA v1.0 attestation, cosign keyless via Fulcio plus OIDC, attached as a git note. Implementation: `src/verification/attestation.ts` and `cosign-attestation.ts`.
+- **Audit-ready run artifacts.** Every execution writes `runs/<execution-id>/` with `session-state.json`, `metrics.json`, `cost-attribution.json`, per-step `share.md` transcripts, and per-step verification reports. Secrets are redacted at end of run.
+- **Multiple agent backends.** Adapters for Copilot CLI, Claude Code, Codex, and Claude Code Teams behind a shared process supervisor.
+
+## Quick Start
+
+### Prerequisites
+
+| Requirement | Version | Notes |
+|---|---|---|
+| [Node.js](https://nodejs.org/) | >= 20 | Engines-enforced. CI runs 20 and 22. |
+| [git](https://git-scm.com/) | >= 2.40 | Worktrees are required; older git is not tested. |
+| One agent CLI | latest | One of: `copilot`, `claude`, `codex`. Must be installed and authenticated separately. |
+| [Docker](https://www.docker.com/) | latest | Optional. Required only for SWE-bench evaluation containers. |
+
+### Install
+
+The npm package is not published yet. Install from source:
+
+```bash
+git clone https://github.com/moonrunnerkc/swarm-orchestrator.git
+cd swarm-orchestrator
+npm install
+npm run build
+node dist/src/cli.js --help
+```
+
+### First run
+
+```bash
+node dist/src/cli.js run --goal "Add a /health endpoint that returns 200 OK" \
+  --tool claude-code --target ./my-repo
+```
+
+Expected output shape:
+
+```text
+[cli:swarm] Total Steps: 3
+[cli:swarm] Cost Estimate: 3-5 premium requests
+[orchestrator] Starting Parallel Swarm Execution
+[orchestrator]   Step 1 (worker) on branch: swarm/<run-id>/step-1-worker
+[orchestrator]   Step 1 (worker) - Agent working...
+[orchestrator]   Step 1 verified, merging...
+[cli:swarm] SWARM EXECUTION COMPLETE
+[cli:swarm]   Completed: 3/3
+[cli:swarm]   Artifacts: ./runs/<run-id>/
+```
+
+## How It Works
+
+The CLI takes a goal, calls `swarm bootstrap` or `swarm plan` to produce a plan file, then `swarm swarm <planfile>` runs each step. A worker step is a git branch and worktree where the configured agent CLI executes against the goal; the worker writes a `/share` transcript and commits its changes. A reviewer step is read-only, runs either before the worker (synthesises a differential test from the goal's `FAIL_TO_PASS` description) or after (reviews the diff against a configured policy: general, security, or accessibility).
+
+After each step, the verifier runs. The active per-step path is `src/verifier-engine.ts`, which parses the transcript, cross-references hook-recorded file evidence, and runs outcome checks (`git_diff`, `file_existence`, `build_exec`, `test_exec`) against the worktree. The v7 falsification battery code lives under `src/verification/` and is wired in for differential gating, mutation testing, cheat detection, property testing, and attestation; the migration to make it the sole per-step path is in progress.
+
+Steps that pass verification merge to `main` via octopus merge; steps that fail are rolled back. After all step branches merge, the nine-gate quality engine scans the merged result and writes a report. Quality-gate findings are advisory in the current code: they do not block the merge path.
+
+For deeper detail, see [`ARCHITECTURE.md`](ARCHITECTURE.md) and [`docs/verification.md`](docs/verification.md).
+
+## Supported Agents
+
+| Agent CLI | Status | Notes |
+|---|---|---|
+| `copilot` | shipped | GitHub Copilot CLI. Cold-start spawn per step. Adapter: `src/adapters/copilot-adapter.ts`. |
+| `claude-code` | shipped | Anthropic Claude Code CLI. Supports persistent interactive sessions. Adapter: `src/adapters/claude-code-adapter.ts`. |
+| `claude-code-teams` | shipped | Claude Code in teams configuration. Adapter: `src/adapters/claude-code-teams.ts`. |
+| `codex` | shipped | OpenAI Codex CLI. Spawns `codex exec` with sandbox bypass for git worktrees. Adapter: `src/adapters/codex-adapter.ts`. |
+
+Pass `--tool <name>` to select. The agent CLI must be installed and authenticated by the user; the orchestrator does not bundle credentials.
+
+## Configuration
+
+<details>
+<summary><b><code>.swarm/gates.yaml</code>: verification battery weights and thresholds</b></summary>
+
+```yaml
+verification:
+  mutation:
+    failBelow: 0.6
+    warnBelow: 0.8
+  composite:
+    threshold: 0.7
+    weights:
+      cheatDetector: 0.4
+      propertyGate: 0.4
+      attestation: 0.2
+    advisoryGatePenalty: 0.02
+```
+
+Full reference: [`docs/configuration.md`](docs/configuration.md).
+</details>
+
+<details>
+<summary><b><code>config/quality-gates.yaml</code>: built-in quality gates</b></summary>
+
+```yaml
+enabled: true
+failOnIssues: true
+autoAddRefactorStepOnDuplicateBlocks: true
+autoAddReadmeTruthStepOnReadmeClaims: true
+autoAddScaffoldFixStepOnScaffoldDefaults: true
+autoAddConfigFixStepOnHardcodedConfig: true
+autoAddAccessibilityFixStepOnAccessibility: true
+autoAddTestCoverageStepOnTestCoverage: true
+```
+
+Full reference: [`docs/quality-gates.md`](docs/quality-gates.md).
+</details>
+
+<details>
+<summary><b><code>config/default-agents.yaml</code>: agent profiles</b></summary>
+
+Worker and reviewer roles are defined in `agents/worker.agent.md` and `agents/reviewer.agent.md`. Project overrides live in `config/default-agents.yaml`; install-level and `.github/agents/*.agent.md` are the lower-precedence sources.
+
+Full reference: [`docs/configuration.md`](docs/configuration.md).
+</details>
+
+## CLI Reference
+
+<details>
+<summary><b>Top-level commands</b></summary>
+
+| Command | Description |
+|---|---|
+| `swarm bootstrap <path(s)> "<goal>"` | Analyses target repos and writes a plan. |
+| `swarm plan <goal>` | Generates a plan from a goal description. |
+| `swarm execute <planfile>` | Executes a saved plan step-by-step. |
+| `swarm swarm <planfile>` | Executes a plan with verified branch and worktree workflow. |
+| `swarm run --goal "<description>"` | Plan and execute in one step. |
+| `swarm quick "<task>"` | Single-agent quick-fix mode. |
+| `swarm gates [path]` | Runs quality gates against a repo. |
+| `swarm status <execid>` | Shows execution status. |
+| `swarm report <run-id>` | Generates a structured run report. |
+| `swarm audit <session-id>` | Generates a Markdown audit report. |
+| `swarm metrics <session-id>` | Shows metrics summary for a session. |
+| `swarm attest verify <commit>` | Verifies the swarm attestation git note on a commit. |
+| `swarm demo <scenario>` | Runs a pre-configured demo scenario. |
+| `swarm templates` | Lists available plan templates. |
+| `swarm recipes` | Lists available recipes. |
+
+Full flag reference: [`docs/cli.md`](docs/cli.md).
+</details>
+
+## Documentation
+
+| Section | What's covered |
+|---|---|
+| [Architecture](ARCHITECTURE.md) | Module layout, scheduling, merge strategy, governance. |
+| [Verification](docs/verification.md) | Per-step verifier, outcome checks, transcript checks, hook evidence. |
+| [Adapters](docs/adapters.md) | Per-CLI capabilities, options, and process supervision. |
+| [Quality gates](docs/quality-gates.md) | The nine built-in gates and how to register custom ones. |
+| [Configuration](docs/configuration.md) | Config file precedence, schema, and overrides. |
+| [CLI](docs/cli.md) | Full command and flag reference. |
+| [Benchmarks](docs/benchmarks.md) | SWE-bench harness, scoring, and methodology. |
+| [Contributing](CONTRIBUTING.md) | Development setup, code style, PR workflow. |
+
+## Contributing
+
+PRs welcome. Code style is enforced: named exports only, kebab-case filenames, no `any` types in `src/`, full JSDoc on public functions, 300-line file soft limit, structured logger only (no `console.*` in `src/`). Before any PR: `npm test`, then `node dist/src/cli.js gates .`, then a descriptive conventional-commit message. The full standards are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```bash
+git clone https://github.com/moonrunnerkc/swarm-orchestrator.git
+cd swarm-orchestrator
+npm install
+npm test
+```
+
+## License
+
+[ISC](LICENSE) © 2026 Bradley R. Kinnard / moonrunnerkc

package/agents/reviewer.agent.md

@@ -0,0 +1,50 @@
+# Reviewer Agent
+
+## Role
+
+Critique diffs and generate synthesized tests to verify worker output. You have read-only
+access to the full repository. You do not write implementation code.
+
+## Responsibilities
+
+Two modes of operation:
+
+### Pre-worker: Test Synthesis
+
+Before a worker step runs, you generate a synthesized regression test that:
+1. Fails against the current codebase (proving the bug or missing feature exists).
+2. Would pass once the goal is satisfied.
+3. Has clear assertions, not just "does it run."
+
+Run the test against the current codebase to confirm it fails. If it passes, the goal is
+ambiguous and you must report `AMBIGUOUS_GOAL` rather than proceeding.
+
+### Post-worker: Diff Review
+
+After a worker step completes, you review the diff against your active review policy:
+- `general`: correctness, code quality, error handling
+- `security`: OWASP-class vulnerabilities, injection, secrets exposure
+- `accessibility`: WCAG/ARIA compliance in UI diffs
+
+For each finding: report file, line, severity (high/medium/low), and a one-sentence
+explanation.
+
+## Boundaries
+
+- Do not write implementation code. Your only outputs are the review report and (when
+  requested) a synthesized test file.
+- Do not modify source files outside the designated test output path.
+- Do not approve a diff you have not examined.
+
+## Done Definition
+
+Your step is complete when:
+1. Review report is written with all findings.
+2. If in test-synthesis mode: the synthesized test file exists and fails against base.
+3. Your transcript includes the actual test output confirming the failure.
+
+## Output Contract
+
+Write your transcript to `proof/step-{N}-reviewer.md`. Include:
+- Review findings with file/line/severity
+- Synthesized test path and the failure output that confirms it targets the right behavior

package/agents/worker.agent.md

@@ -0,0 +1,41 @@
+# Worker Agent
+
+## Role
+
+Implement code changes to satisfy a stated goal. You have full file access to the target
+repository. You write code, run tests, and produce commits.
+
+## Responsibilities
+
+- Read the goal carefully. Understand what must change before touching any file.
+- Implement the minimal change that satisfies the goal. Do not refactor unrelated code.
+- Run the existing test suite before finishing. It must pass.
+- If an acceptance test is specified in the plan, ensure it transitions from fail to pass.
+  Do not show the acceptance test to yourself before implementing (it defeats the purpose).
+- Commit incrementally with descriptive messages. Each commit should represent one logical
+  unit of work.
+
+## Boundaries
+
+- Do not modify pre-existing test files unless the goal explicitly requires it.
+- Do not introduce new dependencies without justification in your transcript.
+- Do not modify files unrelated to the stated goal.
+- Do not swallow exceptions to make tests green.
+- Do not hardcode expected values from test fixtures into implementation code.
+- Do not modify test assertions to make a broken implementation look correct.
+
+## Done Definition
+
+Your step is complete when:
+1. `npm test` / `pytest` / equivalent passes with no failures.
+2. The acceptance test (if provided) passes.
+3. No unrelated files are modified.
+4. Your transcript includes the actual test output.
+5. Changes are committed.
+
+## Output Contract
+
+Write your transcript to `proof/step-{N}-worker.md`. Include:
+- Files modified and why
+- Test output (actual stdout, not a claim)
+- Git log of your commits

package/config/default-agents.yaml

@@ -0,0 +1,56 @@
+# Default Agent Profiles for Swarm Orchestrator v7
+# Two roles: worker (implements code) and reviewer (critiques diffs, generates tests).
+# Domain specialization is expressed as a reviewer policy field, not as separate agents.
+
+agents:
+  - name: worker
+    purpose: "Implement code changes to satisfy a stated goal"
+    scope:
+      - "All file types in the target repository"
+      - "Creating new files, modifying existing files"
+      - "Running tests and build commands to verify work"
+    boundaries:
+      - "Do not modify pre-existing test files unless the goal explicitly requires it"
+      - "Do not change unrelated files beyond the stated goal"
+      - "Do not introduce dependencies without justification"
+    done_definition:
+      - "Code compiles without errors"
+      - "Existing test suite passes"
+      - "Acceptance test (if provided) transitions from fail to pass"
+      - "Goal is fully addressed with no partial implementation"
+      - "Changes committed incrementally with descriptive messages"
+    output_contract:
+      transcript: "proof/step-{N}-worker.md"
+      artifacts:
+        - "Modified or created files listed"
+        - "Test results showing passing suite"
+        - "Git commit history for the work"
+    refusal_rules:
+      - "Do not claim tests passed without showing actual output"
+      - "Do not modify test assertions to match a broken implementation"
+      - "Do not swallow exceptions to make tests green"
+      - "Do not hardcode expected values from test fixtures into implementation"
+
+  - name: reviewer
+    purpose: "Critique diffs and generate synthesized tests to verify worker output"
+    scope:
+      - "Read-only access to the full repository"
+      - "Generating test files in a designated output path"
+      - "Producing review findings as structured output"
+    boundaries:
+      - "Do not write implementation code"
+      - "Do not modify source files outside the designated test output path"
+      - "Focus review on correctness, security, and accessibility per active policy"
+    done_definition:
+      - "Review report generated with per-finding severity"
+      - "Synthesized test (if requested) written and validated to fail against base commit"
+      - "All findings reference specific file and line"
+    output_contract:
+      transcript: "proof/step-{N}-reviewer.md"
+      artifacts:
+        - "Review findings list with file/line references"
+        - "Synthesized test file path and command (when applicable)"
+    refusal_rules:
+      - "Do not approve a diff without examining it"
+      - "Do not generate a test that passes against the current codebase (it would not catch regressions)"
+      - "Do not write implementation code in place of review findings"

package/config/pm-agent.yaml

@@ -0,0 +1,36 @@
+# PM (Project Manager) Agent Profile
+# Hierarchical meta-orchestrator that reviews generated plans before execution.
+# Activated with the --pm flag on the swarm command.
+#
+# The PM agent validates:
+#   - Step ordering and dependency correctness
+#   - Agent assignment matches task scope
+#   - Goal coverage (no missing aspects)
+#   - Integration/finalization step is present
+#   - No circular dependencies
+
+agent:
+  name: PMAgent
+  purpose: "Review and refine execution plans before swarm execution"
+  scope:
+    - "Validate step dependencies and ordering"
+    - "Check agent assignment matches task type"
+    - "Verify goal coverage across all steps"
+    - "Ensure integration/finalization step exists"
+    - "Detect circular dependencies"
+    - "Update plan metadata"
+  boundaries:
+    - "Do not execute any code or make changes to the repo"
+    - "Do not add unnecessary steps that increase execution time"
+    - "Do not reassign agents without clear justification"
+    - "Do not split well-scoped steps into overly granular sub-steps"
+  done_definition:
+    - "Plan passes all structural validation checks"
+    - "Dependencies are acyclic and reference existing steps"
+    - "Every step references a known agent"
+    - "Goal is fully covered by the plan steps"
+    - "Metadata is accurate"
+  refusal_rules:
+    - "Do not approve a plan with circular dependencies"
+    - "Do not approve a plan where steps reference unknown agents"
+    - "Do not silently drop steps from the plan"

package/config/quality-gates.yaml

@@ -0,0 +1,88 @@
+# Quality gates for generated projects.
+# Keep this deterministic. If you relax a gate, do it intentionally.
+
+enabled: true
+
+# This flag is retained for the planned hard-gate path. The current runner
+# writes advisory findings and returns passed=true even when individual gates
+# report fail.
+failOnIssues: true
+
+# When true, swarm can auto-add follow-up steps to fix gate failures.
+# These flags are present for the remediation path that will become active
+# when quality-gate findings are promoted from advisory to hard failures.
+autoAddRefactorStepOnDuplicateBlocks: true
+autoAddReadmeTruthStepOnReadmeClaims: true
+autoAddScaffoldFixStepOnScaffoldDefaults: true
+autoAddConfigFixStepOnHardcodedConfig: true
+autoAddAccessibilityFixStepOnAccessibility: true
+autoAddTestCoverageStepOnTestCoverage: true
+
+gates:
+  scaffoldDefaults:
+    enabled: true
+
+  duplicateBlocks:
+    enabled: true
+    minLines: 12
+    maxOccurrences: 2
+    maxFindings: 20
+
+  hardcodedConfig:
+    enabled: true
+
+  readmeClaims:
+    enabled: true
+
+  testIsolation:
+    enabled: true
+
+  # Runtime checks run the project's own tests, linter, and security audit.
+  # Each sub-check (test, lint, audit) is skipped gracefully when the target
+  # project lacks the relevant script, config, or package.json.
+  runtimeChecks:
+    enabled: true
+    retries: 1
+    runTests: true
+    runLint: true
+    runAudit: true
+    timeoutMs: 120000
+
+  accessibility:
+    enabled: true
+    requireSkipLink: true
+    requireHeadingHierarchy: true
+    requireAriaLabels: true
+    requireFocusStyles: true
+    requireReducedMotion: true
+    requireNoPhantomAssets: true
+    requireMetaTags: true
+    requireResponsiveCSS: true
+    requireColorScheme: true
+    requireSemanticHTML: true
+    requireImgAlt: true
+
+  testCoverage:
+    enabled: true
+    entryPointPatterns:
+      - '^src/dashboard\.tsx?$'
+    minTestAssertions: 1
+    requireComponentTests: true
+
+  # D4: Reject modifications to pre-existing test files.
+  # Agents should ADD new tests, not weaken existing ones.
+  testFileProtection:
+    enabled: true
+    testFileGlobs:
+      - 'tests/**'
+      - 'test/**'
+      - '**/__tests__/**'
+      - '**/*.test.ts'
+      - '**/*.test.tsx'
+      - '**/*.test.js'
+      - '**/*.test.jsx'
+      - '**/*.spec.ts'
+      - '**/*.spec.js'
+      - '**/test_*.py'
+      - '**/*_test.py'
+    maxFindings: 25

package/config/repair-agent.yaml

@@ -0,0 +1,34 @@
+# Repair Agent Profile
+# Specialized agent for self-repair: spawned when a step fails verification.
+# Receives the failure transcript, verification report, git diff, and failed
+# checks, then attempts targeted fixes rather than redoing the entire step.
+
+agent:
+  name: RepairAgent
+  purpose: "Fix specific verification failures identified in a prior agent session"
+  scope:
+    - "Read the verification report and failed checks to understand what went wrong"
+    - "Apply targeted fixes to address the specific failures"
+    - "Re-run tests or builds if the original task required them"
+    - "Commit fixes with 'repair:' prefix messages"
+  boundaries:
+    - "Do not redo work that already passed verification"
+    - "Do not introduce new features or refactor unrelated code"
+    - "Do not change test assertions to make failures pass (fix the code instead)"
+    - "Limit changes to the minimum needed to pass verification"
+  done_definition:
+    - "All previously failing verification checks now pass"
+    - "No new verification failures introduced"
+    - "Fixes committed with clear 'repair:' prefix messages"
+    - "Evidence of fix visible in transcript (test output, build output, etc.)"
+  refusal_rules:
+    - "Do not claim a fix works without running the relevant test or build"
+    - "Do not delete or weaken verification checks to bypass failures"
+    - "If a fix requires architectural changes beyond scope, report it rather than attempt it"
+
+# Retry configuration
+retry:
+  maxAttempts: 3
+  # Estimated token budget per attempt (prompt + response).
+  # The orchestrator uses this for cost logging, not hard enforcement.
+  estimatedTokenBudgetPerAttempt: 8000

package/config/semgrep-rules/complexity-mismatch.yaml

@@ -0,0 +1,6 @@
+rules:
+  - id: swarm-agent-complexity-mismatch
+    message: Complexity mismatch is computed from goal text and diffstat by cheat-detector.
+    severity: INFO
+    languages: [javascript, typescript, python, java]
+    pattern-regex: '\S'

package/config/semgrep-rules/exception-swallowing.yaml

@@ -0,0 +1,13 @@
+rules:
+  - id: swarm-agent-exception-swallowing
+    message: Catch handler appears empty or log-only.
+    severity: ERROR
+    languages: [javascript, typescript]
+    patterns:
+      - pattern-either:
+          - pattern: |
+              try { ... } catch ($E) {}
+          - pattern: |
+              try { ... } catch ($E) { console.$LOG(...); }
+          - pattern: |
+              try { ... } catch ($E) { logger.$LOG(...); }

package/config/semgrep-rules/hardcoded-answer.yaml

@@ -0,0 +1,6 @@
+rules:
+  - id: swarm-agent-hardcoded-answer
+    message: Implementation contains literal returns that may mirror test expectations.
+    severity: WARNING
+    languages: [javascript, typescript, python, java]
+    pattern-regex: '\breturn\s+["''`0-9]'

package/config/semgrep-rules/mock-mutation.yaml

@@ -0,0 +1,6 @@
+rules:
+  - id: swarm-agent-mock-mutation
+    message: Mock, fixture, or setup code changed.
+    severity: WARNING
+    languages: [javascript, typescript, python]
+    pattern-regex: '\b(mock(ReturnValue|ResolvedValue|Implementation)?|fixture|beforeEach|setUp|setup)\b'

package/config/semgrep-rules/test-modification.yaml

@@ -0,0 +1,6 @@
+rules:
+  - id: swarm-agent-test-modification
+    message: Test file contents changed; cheat-detector validates allowlists from git diff.
+    severity: WARNING
+    languages: [javascript, typescript, python]
+    pattern-regex: '\b(describe|it|test|pytest|assert)\b'

package/config/user-agents.yaml

@@ -0,0 +1,23 @@
+# User-defined Agent Profiles
+# Add your custom agents here following the same structure as default-agents.yaml
+#
+# Example:
+# agents:
+#   - name: MyCustomAgent
+#     purpose: "Description of what this agent does"
+#     scope:
+#       - "Area 1 of responsibility"
+#       - "Area 2 of responsibility"
+#     boundaries:
+#       - "What this agent should NOT do"
+#     done_definition:
+#       - "Condition 1 for completion"
+#       - "Condition 2 for completion"
+#     output_contract:
+#       transcript: "proof/step-{N}-custom.md"
+#       artifacts:
+#         - "List of expected outputs"
+#     refusal_rules:
+#       - "Rule 1 for when to refuse or ask for clarification"
+
+agents: []

package/dist/src/adapters/adapter-factory.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAdapter = resolveAdapter;
+exports.registerAdapter = registerAdapter;
+exports.listAdapterNames = listAdapterNames;
+const copilot_adapter_1 = require("./copilot-adapter");
+const claude_code_adapter_1 = require("./claude-code-adapter");
+const claude_code_teams_1 = require("./claude-code-teams");
+const adapterRegistry = {
+    'copilot': () => new copilot_adapter_1.CopilotAdapter(),
+    'claude-code': () => new claude_code_adapter_1.ClaudeCodeAdapter(),
+    'claude-code-teams': () => new claude_code_teams_1.ClaudeCodeTeamsAdapter(),
+};
+// Resolve an adapter by CLI tool name. Throws with the list of valid
+// names when the requested tool is unknown.
+function resolveAdapter(toolName) {
+    const factory = adapterRegistry[toolName];
+    if (!factory) {
+        const valid = Object.keys(adapterRegistry).join(', ');
+        throw new Error(`Unknown tool "${toolName}". Valid tools: ${valid}`);
+    }
+    return factory();
+}
+function registerAdapter(name, factory) {
+    adapterRegistry[name] = factory;
+}
+function listAdapterNames() {
+    return Object.keys(adapterRegistry);
+}

package/dist/src/adapters/agent-adapter.js

@@ -0,0 +1,32 @@
+"use strict";
+// Unified interface for spawning CLI-based coding agents.
+// Each adapter wraps a specific tool (Copilot, Claude Code, Codex)
+// behind a common contract so the orchestrator can drive any of them.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRestrictedEnv = buildRestrictedEnv;
+// Builds a minimal process.env for agent subprocesses. Only the keys the
+// adapter actually needs are forwarded, limiting blast radius if a CLI
+// tool is compromised or unexpectedly dumps its environment.
+function buildRestrictedEnv(adapterKeys) {
+    const env = {
+        PATH: process.env.PATH || '/usr/bin:/bin',
+        HOME: process.env.HOME || '/tmp',
+        GIT_AUTHOR_NAME: 'swarm-orchestrator',
+        GIT_AUTHOR_EMAIL: 'swarm@localhost',
+        GIT_COMMITTER_NAME: 'swarm-orchestrator',
+        GIT_COMMITTER_EMAIL: 'swarm@localhost',
+    };
+    // Forward config directory vars so CLI tools find their OAuth/session credentials
+    const configVars = ['XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME', 'TMPDIR', 'TERM'];
+    for (const key of configVars) {
+        const val = process.env[key];
+        if (val)
+            env[key] = val;
+    }
+    for (const key of adapterKeys) {
+        const val = process.env[key];
+        if (val)
+            env[key] = val;
+    }
+    return env;
+}