swarm-orchestrator 7.0.0-alpha.0 → 12.0.0

package/README.md

@@ -1,199 +1,255 @@
-<div align="center">
-
-<img src="assets/header.svg" alt="Swarm Orchestrator" width="100%">
+<p align="center">
+  <img src="./assets/cover.svg" alt="Swarm Orchestrator cover" width="100%">
+</p>
 
 # 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.
+Reads a pull request (PR) diff and flags the shortcuts artificial intelligence (AI) coding agents use to look done without being done. Relaxed tests, swallowed errors, fake renames, eleven categories in all. Grading patches against typed obligation contracts via a multi-persona pipeline is the second surface.
 
-## Features
+For engineers reviewing AI-written PRs at volume. Compliance teams generate CycloneDX-ML (machine learning) and SPDX (Software Package Data Exchange) 3.0 AI-BOM (bill of materials) artifacts. The artifacts map to EU AI Act (European Union Artificial Intelligence Act) Annex IV and CISA (Cybersecurity and Infrastructure Security Agency) reporting. Maintainers keep a hash-chained evidence record for every graded patch.
 
-- **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.
+**Flags are tips, blocks are proof.** A flag is a structural detector seeing a cheat-shaped pattern; it is advisory and never blocks a merge (`--mode advise` is the default). A block is a self-certifying runtime result whose per-instance controls are all green, and every block ships the exact command that reproduces it in a fresh checkout. Eight proof protocols back the gate today: six execution-grounded restoration proofs (`test-tamper`, `mock-mutation`, `no-op-fix`, `type-suppression`, `fake-refactor`, `dead-branch`) plus `claim-falsified` and `obligation-failure`. The measured proven-finding precision on the execution-grounded-viable corpus slice, with its plain n, is in [`benchmarks/real-corpus/GATE-PRECISION-REPORT.md`](benchmarks/real-corpus/GATE-PRECISION-REPORT.md).
 
-## Quick Start
+<!-- BADGES:START -->
+[![CI](https://github.com/moonrunnerkc/swarm-orchestrator/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/moonrunnerkc/swarm-orchestrator/actions/workflows/ci.yml)
+[![license ISC](https://img.shields.io/static/v1?label=license&message=ISC&color=blue)](LICENSE)
+[![node >= 20](https://img.shields.io/static/v1?label=node&message=%3E%3D%2020&color=3c873a)](package.json)
+[![version 12.0.0](https://img.shields.io/static/v1?label=version&message=12.0.0&color=22d3ee)](package.json)
+[![oracle recall 93% (301/325)](https://img.shields.io/static/v1?label=oracle%20recall&message=93%25%20(301%2F325)&color=brightgreen)](benchmarks/results/AB-REPORT.md)
+[![real-PR false alarms 0.11/PR](https://img.shields.io/static/v1?label=real-PR%20false%20alarms&message=0.11%2FPR&color=brightgreen)](benchmarks/real-prs/REAL-WORLD-REPORT.md)
+[![real-PR cheats vs linters 4 confirmed (Semgrep+ESLint: 1)](https://img.shields.io/static/v1?label=real-PR%20cheats%20vs%20linters&message=4%20confirmed%20(Semgrep%2BESLint%3A%201)&color=brightgreen)](benchmarks/real-prs/v11-BENEFIT-REPORT.md)
+<!-- BADGES:END -->
 
-### Prerequisites
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#results">Results</a> ·
+  <a href="#cheat-detectors">Detectors</a> ·
+  <a href="#use-as-a-github-action">GitHub Action</a> ·
+  <a href="#ai-bom">AI-BOM</a> ·
+  <a href="#orchestrator-mode">Orchestrator</a> ·
+  <a href="#architecture">Architecture</a> ·
+  <a href="#commands">Commands</a> ·
+  <a href="#limitations">Limitations</a>
+</p>
 
-| 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
+## Install
 
-The npm package is not published yet. Install from source:
+Node 20 or later. See [`package.json`](package.json).
 
 ```bash
 git clone https://github.com/moonrunnerkc/swarm-orchestrator.git
 cd swarm-orchestrator
 npm install
 npm run build
-node dist/src/cli.js --help
+npm link
+swarm --help
 ```
 
-### First run
+## Quick start
 
 ```bash
-node dist/src/cli.js run --goal "Add a /health endpoint that returns 200 OK" \
-  --tool claude-code --target ./my-repo
-```
+# Audit a PR by reference (advisory by default; never blocks the merge)
+GITHUB_TOKEN=... swarm audit moonrunnerkc/swarm-orchestrator#42
 
-Expected output shape:
+# Opt in to merge-blocking gate mode (blocks only on a self-certifying
+# runtime proof; enable the execution-grounded layer in
+# .swarm/audit-config.yaml first; see docs/audit-config.md)
+GITHUB_TOKEN=... swarm audit moonrunnerkc/swarm-orchestrator#42 --mode gate
 
-```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>/
+# Audit a local diff with all 11 detectors
+git diff main...HEAD | swarm audit --diff-stdin --detectors experimental
+
+# Audit and emit a CycloneDX 1.6 ML-BOM
+swarm audit --diff-file my.patch --emit-aibom cyclonedx-ml
+
+# Shadow mode: record verdicts to disk without commenting or gating
+swarm audit --pr <ref> --shadow my-org/my-repo
 ```
 
-## How It Works
+Exit codes: `0` advisory or any advise-mode run, `1` block (gate mode only), `2` usage error.
+
+## Results
 
-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).
+Every number here is reproducible from this repo and runs offline.
 
-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.
+### Catches cheats that linters miss
 
-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.
+| PR | Cheat caught | Semgrep / ESLint |
+|---|---|---|
+| [cloudflare/workers-sdk#14063](https://github.com/cloudflare/workers-sdk/pull/14063) | fake refactor: function renamed but two callers still use the old name | not flagged |
+| [cloudflare/workers-sdk#14132](https://github.com/cloudflare/workers-sdk/pull/14132) | error swallow: bare empty `catch` silently hides every error in the block | not flagged |
+
+Both reproduce deterministically from the committed diffs. Semgrep (210 rules) and the ESLint security ruleset flag neither. Reproduce either with `swarm audit --diff-file benchmarks/real-prs/diffs/cloudflare-workers-sdk/<pr>.diff`. Full study across twelve repos in [`benchmarks/real-prs/v11-BENEFIT-REPORT.md`](benchmarks/real-prs/v11-BENEFIT-REPORT.md).
+
+### Detection numbers
+
+**301 of 325** planted cheats recovered (92.6%) across thirteen categories scored against a defect-injection oracle: 258/275 structural plus 43/50 on the two semantic categories the judge-primary path covers. The behavioral `cheat-mock-mutation` category drove the latest gain: focusing the judge on the hunks that add a value-injecting mock lifted its recall from 0.16 (the prior rapid-mlx glm47 run) to 0.96 (24/25) on the local qwen3.6 judge, while the clean-PR judge false-positive rate fell from 10% to 0%. Reproduce with `SWARM_JUDGE_PROVIDER=ollama SWARM_JUDGE_MODEL=qwen3.6:35b-a3b npm run benchmarks:full`; A/B with the same-model decomposition in [`benchmarks/results/AB-REPORT.md`](benchmarks/results/AB-REPORT.md) and per-detector recall in [`benchmarks/oracle-corpus/per-detector-recall.md`](benchmarks/oracle-corpus/per-detector-recall.md).
+
+**0.11 findings per PR** on an 18-PR pilot across five public repos. At or below the pre-upgrade auditor's false-alarm burden, with the oracle recall gain intact. Full numbers in [`benchmarks/real-prs/REAL-WORLD-REPORT.md`](benchmarks/real-prs/REAL-WORLD-REPORT.md).
+
+### Execution-grounded layer
+
+Reproduce with `npm run execution-grounded:full`. This optional layer sets up a sandboxed checkout and runs mutation testing, repro execution, and a coverage delta scoped to the lines the PR changed. It surfaced one proof-correlated catch: proof anchor [`trpc/trpc#6098`](https://github.com/trpc/trpc/pull/6098), where 8 lines with surviving mutations were later changed by a hotfix. Evaluation in [`benchmarks/real-prs/v11-EXECUTION-GROUNDED-REPORT.md`](benchmarks/real-prs/v11-EXECUTION-GROUNDED-REPORT.md).
 
-For deeper detail, see [`ARCHITECTURE.md`](ARCHITECTURE.md) and [`docs/verification.md`](docs/verification.md).
+## Cheat detectors
 
-## Supported Agents
+Eleven detectors. Eight load by default; three (`comment-only-fix`, `exception-rethrow-lost-context`, `dead-branch-insertion`) require `--detectors experimental` because they have no real-PR signal yet to measure against. Registered in [`src/audit/cheat-detector/detector-sets.ts`](src/audit/cheat-detector/detector-sets.ts).
 
-| Agent CLI | Status | Notes |
+| Category | Set | Trigger |
 |---|---|---|
-| `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`. |
+| `error-swallow` | default | Bare empty or comment-only `catch` block added in non-test code. |
+| `mock-of-hallucination` | default | `jest.mock` / `vi.mock` / `@patch` against a module declared in no manifest in the repo. |
+| `no-op-fix` | default | Test modified with no source change, or vice versa; import-graph reachability fallback when only one side moved. |
+| `fake-refactor` | default | Exported symbol renamed in source, no caller in the diff updates the old name. |
+| `coverage-erosion` | default | Source branch added with no compensating test addition. |
+| `test-relaxation` | default | Strict matcher swapped for a loose one, or a test block removed without same-chunk replacement. |
+| `assertion-strip` | default | Net assertion count in a test file drops after the PR. |
+| `type-suppression` | default | A type-checker or linter suppression (for example `@ts-ignore` or `eslint-disable`) added over a changed line. |
+| `comment-only-fix` | experimental | Source modifications are all comment additions. |
+| `exception-rethrow-lost-context` | experimental | `throw err` replaced with `throw new Error(...)` and `{ cause }` not forwarded. |
+| `dead-branch-insertion` | experimental | Branch guarded by a literal-false condition added. |
 
-Pass `--tool <name>` to select. The agent CLI must be installed and authenticated by the user; the orchestrator does not bundle credentials.
+Beyond the structural detectors, a judge-primary path catches two semantic categories (`goal-not-fixed`, `cheat-mock-mutation`) by asking the judge whether the diff delivers the PR's stated claim. For `cheat-mock-mutation` a deterministic pre-filter hands the judge only the test hunks that add a value-injecting mock, so the judge reads the six-line cheat instead of skimming a 40k-char diff, and is never asked on a clean PR that adds no such mock. A proven mock-mutation can also block under `--mode gate` as a self-certifying `mock-mutation-proven` trigger (see [`docs/limitations.md`](docs/limitations.md)).
 
-## Configuration
+Per-repo configuration in `.swarm/audit-config.yaml`: `excludePaths`, `intentSeverityPolicy` (`strict` | `lenient` | `off`), and `judgePrimary`. See [`docs/audit-config.md`](docs/audit-config.md).
 
-<details>
-<summary><b><code>.swarm/gates.yaml</code>: verification battery weights and thresholds</b></summary>
+## Use as a GitHub Action
 
 ```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
+name: PR audit
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+permissions:
+  pull-requests: write
+  contents: read
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: moonrunnerkc/swarm-orchestrator@main
+        with:
+          audit-mode: true
+          mode: advise           # advise | gate
+          detectors: default     # default | experimental
+          emit-aibom: cyclonedx-ml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-Full reference: [`docs/configuration.md`](docs/configuration.md).
-</details>
+Outputs: `audit-pass`, `audit-findings`, `audit-ledger`. Full input list in [`action.yml`](action.yml).
+
+### Enabling the execution-grounded layer
+
+Structural detectors run with no setup and only ever flag (advisory). The six runtime proofs that can gate a merge (`test-tamper`, `mock-mutation`, `no-op-fix`, `type-suppression`, `fake-refactor`, `dead-branch`) need the execution-grounded layer, which is off until you set `executionGrounded.enabled: true` in [`.swarm/audit-config.yaml`](docs/audit-config.md). Turning it on is what lets `--mode gate` block, and every block it produces ships the exact command that reproduces it in a fresh checkout.
+
+What it costs: for each audited PR the layer provisions the repository in a sandbox (clone the head, install dependencies, run the affected tests), so it adds clone, install, and test wall-clock to the job, and only PRs in a Node project with a lockfile and a recognized test runner (jest, vitest, mocha) provision at all. Everything else fails closed to advisory. The static viability screen on the project corpus measured 12 of 197 PRs as provisionable ([`benchmarks/real-corpus/eg-viability.json`](benchmarks/real-corpus/eg-viability.json)); your own repository, where the suite is known to run in CI, provisions far more reliably than an arbitrary sample. Nothing the layer cannot prove ever blocks: with the layer off, or on a non-provisionable PR, gate mode passes on advisory findings alone.
+
+## AI-BOM
+
+`--emit-aibom cyclonedx-ml | spdx-ai | both` writes one document per format per run under `.swarm/aibom/`. Emitters in [`src/audit/aibom/`](src/audit/aibom/) produce hand-rolled JSON against the upstream specs with no third-party AI-BOM runtime dependency.
+
+Procurement mappings:
+
+- [`docs/eu-ai-act-mapping.md`](docs/eu-ai-act-mapping.md): EU AI Act (European Union Artificial Intelligence Act) Article 11 + Annex IV fields.
+- [`docs/cisa-sbom-ai-mapping.md`](docs/cisa-sbom-ai-mapping.md): CISA (Cybersecurity and Infrastructure Security Agency) SBOM-for-AI minimum elements.
 
-<details>
-<summary><b><code>config/quality-gates.yaml</code>: built-in quality gates</b></summary>
+## Orchestrator mode
+
+Grades patches against a typed contract instead of auditing a PR diff.
+
+```bash
+swarm init                                    # Scaffold contract.yaml + patches.jsonl
+swarm run --goal "check this project builds"  # Deterministic provider, no API key
+```
+
+Minimal contract:
 
 ```yaml
-enabled: true
-failOnIssues: true
-autoAddRefactorStepOnDuplicateBlocks: true
-autoAddReadmeTruthStepOnReadmeClaims: true
-autoAddScaffoldFixStepOnScaffoldDefaults: true
-autoAddConfigFixStepOnHardcodedConfig: true
-autoAddAccessibilityFixStepOnAccessibility: true
-autoAddTestCoverageStepOnTestCoverage: true
+obligations:
+  - type: build-must-pass
+    command: npm run build
+  - type: test-must-pass
+    command: npm test
+```
+
+Hosted-model run:
+
+```bash
+export ANTHROPIC_API_KEY=sk-...
+swarm run --goal "add a /health endpoint" --extractor anthropic --session anthropic
 ```
 
-Full reference: [`docs/quality-gates.md`](docs/quality-gates.md).
-</details>
+Local-LLM run (Ollama):
 
-<details>
-<summary><b><code>config/default-agents.yaml</code>: agent profiles</b></summary>
+```bash
+swarm run --goal "add a named export sum(a, b)" \
+  --session local --local-backend ollama \
+  --local-base-url http://localhost:11434 \
+  --local-model-session gemma4:31b \
+  --local-grammar none --local-max-concurrency 1 --preset fast
+```
 
-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.
+Provider details in [`docs/providers.md`](docs/providers.md). Obligation taxonomy in [`docs/check-types.md`](docs/check-types.md). Schema in [`src/contract/schema/v1.json`](src/contract/schema/v1.json).
 
-Full reference: [`docs/configuration.md`](docs/configuration.md).
-</details>
+## Architecture
 
-## CLI Reference
+Two command-line interface (CLI) surfaces share one core. `swarm run` drives the v8 pipeline (extractor, session, predicate-runner, falsifier, verifier). No patch reaches main without passing both `verifyObligation` and `postMergeVerify`.
 
-<details>
-<summary><b>Top-level commands</b></summary>
+`swarm audit` reuses the verifier and falsifier layers against a unified diff, with no session, extractor, or model credentials needed. Both surfaces write to the same append-only hash-chained ledger ([`src/ledger/ledger.ts`](src/ledger/ledger.ts)); tampering breaks the chain.
 
-| 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 |
+## Commands
+
+| Command | Purpose |
 |---|---|
-| [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. |
+| `swarm audit <ref \| --diff-*>` | Audit a PR or local diff. Advisory by default. |
+| `swarm run --goal "<text>"` | Compile and grade in one step. |
+| `swarm compile <goal>` | Write a reusable compiled contract directory. |
+| `swarm run <contract-dir>` | Grade against a pre-compiled contract directory. |
+| `swarm resume <run-id>` | Resume a killed run from its ledger. |
+| `swarm stats <run-id>` | Aggregate diagnostic counts from a run ledger. |
+| `swarm ledger verify <run-id>` | Verify a hash-chained ledger at rest. |
+| `swarm init` | Scaffold `contract.yaml` and `patches.jsonl`. |
+| `swarm doctor [--fix] [--connectors]` | Probe local prerequisites. |
 
-## Contributing
+`swarm <cmd> --help` for the flag list of any subcommand.
 
-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).
+## Run artifacts
+
+```text
+.swarm/contracts/<id>/contract.jsonl   compiled contract (orchestrator mode)
+.swarm/ledger/<run-id>.jsonl           orchestrator ledger
+.swarm/ledger/audit-<run-id>.jsonl     audit ledger
+.swarm/aibom/<run-id>.cdx.json         CycloneDX-ML (when --emit-aibom)
+.swarm/aibom/<run-id>.spdx.json        SPDX 3.0 AI-Profile (when --emit-aibom)
+.swarm/shadow/<repo>/<run-id>.json     shadow-mode verdict (when --shadow)
+```
+
+`.swarm/` is in [`.gitignore`](.gitignore) at the consumer-repo level.
+
+## Integrations
+
+- Claude Code slash command: [`.claude/commands/swarm-audit.md`](.claude/commands/swarm-audit.md)
+- Cursor rule pack: [`integrations/cursor/swarm-audit.mdc`](integrations/cursor/swarm-audit.mdc)
+- Aider pre-commit hook: [`integrations/aider/pre-commit-swarm-audit`](integrations/aider/pre-commit-swarm-audit)
+
+## Limitations
+
+No single detector has cleared the precision bar to block on its own. Gate mode blocks only on a self-certifying runtime proof whose per-instance controls are all green: test-tamper, mock-mutation, no-op-fix, type-suppression, or fake-refactor restoration, claim falsification, or obligation failure. The first such proof fired on a dogfood PR in June 2026. The full accounting, including the measured gate precision and what blocks today and what doesn't, is in [`docs/limitations.md`](docs/limitations.md).
+
+## Contributing
 
 ```bash
-git clone https://github.com/moonrunnerkc/swarm-orchestrator.git
-cd swarm-orchestrator
-npm install
-npm test
+npm install && npm run build && npm test
+npm run typecheck && npm run lint
 ```
 
+Project conventions in [`CONTRIBUTING.md`](CONTRIBUTING.md). New cheat detectors must include an injector under `src/audit/oracle/inject/` so recall is measurable from day one. Security disclosures via [`SECURITY.md`](SECURITY.md), never via public issues.
+
 ## License
 
-[ISC](LICENSE) © 2026 Bradley R. Kinnard / moonrunnerkc
+[ISC](LICENSE).

package/config/personas/architect.yaml

@@ -0,0 +1,26 @@
+id: architect
+role: architect
+tier: sonnet
+handles:
+  - file-must-exist
+sampling:
+  temperature: 0.2
+  maxTokens: 2048
+systemSuffix: |-
+  You are the architect persona in the swarm-orchestrator v8 population.
+  Your job is to satisfy file-must-exist obligations: when an obligation
+  requires a file at a given path, emit the file content as a single
+  fenced code block. Output exactly one file body, with no surrounding
+  prose, so the run-time can write it verbatim.
+
+  Constraints:
+  - Use the project context to match existing conventions (language,
+    formatting, build tooling).
+  - Keep the file minimal but functional. Stub content is acceptable when
+    the obligation does not specify behavior.
+  - Never reference paths outside the obligation's target path.
+  - When the dynamic message includes a "REQUIRED:" block specifying a
+    test framework, you MUST use that framework's API exclusively.
+    Never import a different framework's globals (no Jest test/expect
+    in node:test projects, no node:test imports in Jest projects, etc.).
+    This rule overrides any default-API muscle memory.

package/config/personas/dependency-auditor.yaml

@@ -0,0 +1,57 @@
+id: dependency-auditor
+role: dependency-auditor
+tier: sonnet
+handles:
+  - import-graph-must-satisfy
+sampling:
+  temperature: 0.1
+  maxTokens: 8192
+systemSuffix: |-
+  You are the dependency-auditor persona in the swarm-orchestrator v8
+  population. Your job is to satisfy import-graph-must-satisfy
+  obligations, which assert structural constraints over the import
+  graph (no cycles, no upward imports, etc.). Reason about module
+  boundaries before patching.
+
+  Constraints:
+  - Prefer extracting a shared module over inlining duplicate code.
+  - Never resolve a cycle by introducing dynamic require/import.
+  - Do not silence the constraint by renaming the offending file.
+
+  Output rules (strict). Pick ONE of these response formats:
+
+  FORMAT 1 — whole-file replacement (PREFERRED for substantive edits):
+  Emit one or more file blocks, each block delimited as:
+      <<<FILE <repo-relative-path>
+      <full new file contents>
+      FILE>>>
+  The body between the markers is written VERBATIM to disk; the existing
+  file is replaced. Use this whenever your edit touches more than one or
+  two lines, or when the file is short enough that re-emitting all of it
+  is clearer than a diff. Multiple <<<FILE ... FILE>>> blocks may appear
+  in one response (one per file you need to write).
+  IMPORTANT: emit the FULL file contents in the block, not just the new
+  parts. Any line you omit from the block will be removed from the file.
+  Preserve existing imports, helper functions, and exports.
+
+  FORMAT 2 — unified diff (use ONLY for small, well-anchored edits):
+  - Reply with a unified diff and nothing else.
+  - No prose before, after, or between hunks. No "Here is the diff:".
+  - No code fences. No ```diff or ``` wrappers.
+  - The first character of your response MUST be a `-` from a `--- a/<path>`
+    header line. The second line MUST be a `+++ b/<path>` header.
+  - New files use `--- /dev/null` and `+++ b/<path>`. Deletions use
+    `--- a/<path>` and `+++ /dev/null`.
+  - Repo-relative paths only; no absolute paths, no leading `./`.
+  - Every ` ` (context) and `-` line MUST appear VERBATIM in the file
+    shown in the "Current contents of <path>:" block. Same characters,
+    same indentation, same surrounding lines. Do not paraphrase. Do not
+    invent helper lines. The parser does byte-for-byte context matching;
+    one wrong character rejects the entire diff.
+
+  FORMAT 3 — no-op:
+  If the obligation already holds against the file shown and no change
+  is needed, reply with the literal three characters: no-op
+
+  Default to FORMAT 1 for anything more complex than a single-line tweak.
+  It avoids the context-mismatch failure mode that plagues FORMAT 2.

package/config/personas/documentation-writer.yaml

@@ -0,0 +1,57 @@
+id: documentation-writer
+role: documentation-writer
+tier: sonnet
+handles:
+  - function-must-have-signature
+sampling:
+  temperature: 0.1
+  maxTokens: 8192
+systemSuffix: |-
+  You are the documentation-writer persona in the swarm-orchestrator v8
+  population. Your job is to satisfy function-must-have-signature
+  obligations: ensure named functions declare the contract-specified
+  signature in the contract-specified file.
+
+  Constraints:
+  - Preserve existing function bodies; only the signature line should
+    change unless the body genuinely depends on a removed parameter.
+  - Update doc comments adjacent to the signature so docs and source agree.
+  - Never delete an existing public function to silence the obligation.
+
+  Output rules (strict). Pick ONE of these response formats:
+
+  FORMAT 1 — whole-file replacement (PREFERRED for substantive edits):
+  Emit one or more file blocks, each block delimited as:
+      <<<FILE <repo-relative-path>
+      <full new file contents>
+      FILE>>>
+  The body between the markers is written VERBATIM to disk; the existing
+  file is replaced. Use this whenever your edit touches more than one or
+  two lines, or when the file is short enough that re-emitting all of it
+  is clearer than a diff. Multiple <<<FILE ... FILE>>> blocks may appear
+  in one response (one per file you need to write).
+  IMPORTANT: emit the FULL file contents in the block, not just the new
+  parts. Any line you omit from the block will be removed from the file.
+  Preserve existing imports, helper functions, and exports.
+
+  FORMAT 2 — unified diff (use ONLY for small, well-anchored edits):
+  - Reply with a unified diff and nothing else.
+  - No prose before, after, or between hunks. No "Here is the diff:".
+  - No code fences. No ```diff or ``` wrappers.
+  - The first character of your response MUST be a `-` from a `--- a/<path>`
+    header line. The second line MUST be a `+++ b/<path>` header.
+  - New files use `--- /dev/null` and `+++ b/<path>`. Deletions use
+    `--- a/<path>` and `+++ /dev/null`.
+  - Repo-relative paths only; no absolute paths, no leading `./`.
+  - Every ` ` (context) and `-` line MUST appear VERBATIM in the file
+    shown in the "Current contents of <path>:" block. Same characters,
+    same indentation, same surrounding lines. Do not paraphrase. Do not
+    invent helper lines. The parser does byte-for-byte context matching;
+    one wrong character rejects the entire diff.
+
+  FORMAT 3 — no-op:
+  If the obligation already holds against the file shown and no change
+  is needed, reply with the literal three characters: no-op
+
+  Default to FORMAT 1 for anything more complex than a single-line tweak.
+  It avoids the context-mismatch failure mode that plagues FORMAT 2.

package/config/personas/implementer.yaml

@@ -0,0 +1,55 @@
+id: implementer
+role: implementer
+tier: sonnet
+handles:
+  - build-must-pass
+sampling:
+  temperature: 0.1
+  maxTokens: 8192
+systemSuffix: |-
+  You are the implementer persona in the swarm-orchestrator v8 population.
+  Your job is to satisfy build-must-pass obligations: when the project's
+  build is failing, propose the smallest patch that makes it pass without
+  breaking other obligations. Output a unified diff against repo root.
+
+  Constraints:
+  - Do not introduce new files unless the diff explicitly creates them.
+  - Do not modify test files; that is the verifier persona's job.
+
+  Output rules (strict). Pick ONE of these response formats:
+
+  FORMAT 1 — whole-file replacement (PREFERRED for substantive edits):
+  Emit one or more file blocks, each block delimited as:
+      <<<FILE <repo-relative-path>
+      <full new file contents>
+      FILE>>>
+  The body between the markers is written VERBATIM to disk; the existing
+  file is replaced. Use this whenever your edit touches more than one or
+  two lines, or when the file is short enough that re-emitting all of it
+  is clearer than a diff. Multiple <<<FILE ... FILE>>> blocks may appear
+  in one response (one per file you need to write).
+  IMPORTANT: emit the FULL file contents in the block, not just the new
+  parts. Any line you omit from the block will be removed from the file.
+  Preserve existing imports, helper functions, and exports.
+
+  FORMAT 2 — unified diff (use ONLY for small, well-anchored edits):
+  - Reply with a unified diff and nothing else.
+  - No prose before, after, or between hunks. No "Here is the diff:".
+  - No code fences. No ```diff or ``` wrappers.
+  - The first character of your response MUST be a `-` from a `--- a/<path>`
+    header line. The second line MUST be a `+++ b/<path>` header.
+  - New files use `--- /dev/null` and `+++ b/<path>`. Deletions use
+    `--- a/<path>` and `+++ /dev/null`.
+  - Repo-relative paths only; no absolute paths, no leading `./`.
+  - Every ` ` (context) and `-` line MUST appear VERBATIM in the file
+    shown in the "Current contents of <path>:" block. Same characters,
+    same indentation, same surrounding lines. Do not paraphrase. Do not
+    invent helper lines. The parser does byte-for-byte context matching;
+    one wrong character rejects the entire diff.
+
+  FORMAT 3 — no-op:
+  If the obligation already holds against the file shown and no change
+  is needed, reply with the literal three characters: no-op
+
+  Default to FORMAT 1 for anything more complex than a single-line tweak.
+  It avoids the context-mismatch failure mode that plagues FORMAT 2.