swarm-orchestrator 7.0.0-alpha.0 → 11.2.0

package/README.md

@@ -1,199 +1,394 @@
 <div align="center">
 
-<img src="assets/header.svg" alt="Swarm Orchestrator" width="100%">
+<img src="docs/assets/hero.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)
+A CLI for auditing AI-generated PRs and grading patches against typed contracts.
+
+<!-- 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 11.2.0](https://img.shields.io/static/v1?label=version&message=11.2.0&color=22d3ee)](package.json)
+[![oracle recall 84% (253/300)](https://img.shields.io/static/v1?label=oracle%20recall&message=84%25%20(253%2F300)&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 -->
+
+<a href="#install"><b>Install</b></a> ·
+<a href="#quick-start"><b>Quick start</b></a> ·
+<a href="#what-this-does"><b>What it does</b></a> ·
+<a href="#results"><b>Results</b></a> ·
+<a href="#cheat-detectors"><b>Detectors</b></a> ·
+<a href="#ai-bom"><b>AI-BOM</b></a> ·
+<a href="#reference"><b>Reference</b></a>
 
 </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
+<div align="center">
 
-- **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.
+## What This Does
 
-## Quick Start
+Swarm Orchestrator reads a pull-request diff and flags the shortcuts an AI coding agent takes to look done without being done: relaxed tests, stripped assertions, swallowed errors, fake renames, eleven checks in all.
+On a benchmark of planted cheats it recovers 253 of 300 (84%, up 20.5% from the prior version), and on real merged Cloudflare PRs it caught two cheats that Semgrep and the ESLint security rules missed, both reproducible offline.
+Findings are advisory by default, so it never blocks a merge unless you turn that on.
 
-### Prerequisites
+</div>
 
-| 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. |
+## Who it's for
 
-### Install
+- You review AI-written PRs at volume and want a "this change may be gaming the tests" signal that ordinary linters do not give you.
+- You have to hand over AI-procurement or compliance paperwork (EU AI Act Annex IV, CISA SBOM-for-AI) and would rather generate the documents than write them by hand.
+- You run AI coding agents and want one hard rule: a patch lands only if it builds, passes tests, holds a stated property, and survives a falsifier trying to break it.
 
-The npm package is not published yet. Install from source:
+## Install
 
 ```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
+Node 20 or later. See [`package.json`](package.json).
+
+## 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
+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 the experimental detector set (all 11 detectors)
+git diff main...HEAD | swarm audit --diff-stdin --detectors experimental
+
+# audit + emit a CycloneDX 1.6 ML-BOM
+swarm audit --diff-file my.patch --emit-aibom cyclonedx-ml
+
+# shadow-mode dogfood: record verdicts to disk, no comment, no gate
+swarm audit --pr <ref> --shadow my-org/my-repo
 
-## How It Works
+# single-file shadow output (one JSON per audit invocation; see docs/shadow-mode.md)
+swarm audit --pr <ref> --shadow-output ./audit-verdict.json
+```
 
-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).
+Exit codes: `0` advisory-clean or any advise-mode run, `1` block (gate mode only), `2` usage error.
 
-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.
+## Results
 
-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.
+Every number here is reproducible from this repo, runs offline, and points at the report that produced it.
 
-For deeper detail, see [`ARCHITECTURE.md`](ARCHITECTURE.md) and [`docs/verification.md`](docs/verification.md).
+### Catches cheats that linters miss
 
-## Supported Agents
+Two real cheats in merged Cloudflare PRs reproduce deterministically offline from the committed diffs, and a live differential confirms that Semgrep (210 rules) and the ESLint security ruleset flag neither:
 
-| Agent CLI | Status | Notes |
+| PR | Cheat it caught | Semgrep / ESLint |
 |---|---|---|
-| `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`. |
+| [cloudflare/workers-sdk#14063](https://github.com/cloudflare/workers-sdk/pull/14063) | fake refactor: a function was renamed but two callers still call the old name | not flagged |
+| [cloudflare/workers-sdk#14132](https://github.com/cloudflare/workers-sdk/pull/14132) | error swallow: a bare empty `catch` silently hides every error in the block | not flagged |
+
+This is the cheat class ordinary analyzers do not model: they look for dangerous APIs, not for tests quietly relaxed or errors quietly dropped. Reproduce either catch with `swarm audit --diff-file benchmarks/real-prs/diffs/cloudflare-workers-sdk/<pr>.diff`. The broader study across twelve repos, with findings classified by two independent model families plus the full false-alarm accounting, is in [`benchmarks/real-prs/v11-BENEFIT-REPORT.md`](benchmarks/real-prs/v11-BENEFIT-REPORT.md); two further error-swallow catches in that report came from the pre-upgrade detector flagging comment-only `// skip` catches, which the current version downgrades as usually legitimate.
+
+### Measured detection, not asserted
+
+Detection is scored against a defect-injection oracle: an injector splices one labeled cheat into a presumed-clean real PR, so recall is measured against ground truth rather than claimed. The auditor recovers **253 of 300** planted cheats (**84%**), up **20.5%** from the pre-upgrade baseline of 210/300, across twelve categories. Most structural detectors sit at or near 1.00 recall on their own injection class. Reproduce with `npm run benchmarks:full`; the pre/post A/B is in [`benchmarks/results/AB-REPORT.md`](benchmarks/results/AB-REPORT.md) and the per-detector table is in [`benchmarks/oracle-corpus/per-detector-recall.md`](benchmarks/oracle-corpus/per-detector-recall.md).
+
+### Low noise on unbiased real PRs
+
+On an 18-PR pilot across five public repos, the post-upgrade auditor's false-alarm burden is **0.11 findings per PR**, at or below the pre-upgrade auditor's, with the oracle recall gain intact ([`benchmarks/real-prs/REAL-WORLD-REPORT.md`](benchmarks/real-prs/REAL-WORLD-REPORT.md)).
+
+### A signal no diff-reader can produce
 
-Pass `--tool <name>` to select. The agent CLI must be installed and authenticated by the user; the orchestrator does not bundle credentials.
+An optional execution-grounded layer provisions a sandboxed checkout and runs diff-scoped mutation testing, issue-linked repro, and a coverage delta, then correlates the findings against each PR's revert and hotfix history. It surfaced one under-constrained change the diff-only layers cannot see: proof anchor [`trpc/trpc#6098`](https://github.com/trpc/trpc/pull/6098), where mutations survived on covered lines and eight of those lines are the ones the later hotfix changed. Reproduce with `npm run execution-grounded:full` ([`benchmarks/real-prs/v11-EXECUTION-GROUNDED-REPORT.md`](benchmarks/real-prs/v11-EXECUTION-GROUNDED-REPORT.md)).
 
-## Configuration
+## Cheat detectors
 
-<details>
-<summary><b><code>.swarm/gates.yaml</code>: verification battery weights and thresholds</b></summary>
+Eleven detectors. Eight load by default; three (`comment-only-fix`,
+`exception-rethrow-lost-context`, `dead-branch-insertion`) require
+`--detectors experimental` because they have never fired on real PR
+data, so there is no signal to gauge them against. The set governs which
+detectors load; the precision gate (see [Limitations and what's next](#limitations-and-whats-next))
+governs which may emit a blocking finding. Registered in
+[`src/audit/cheat-detector/detector-sets.ts`](src/audit/cheat-detector/detector-sets.ts).
+
+| Category | Set | Trigger |
+|---|---|---|
+| `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 in the same PR, 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. |
+
+Each detector lives in its own file under [`src/audit/cheat-detector/`](src/audit/cheat-detector/).
+
+Beyond the ten structural detectors, a judge-primary path catches two
+semantic categories (`goal-not-fixed`, `cheat-mock-mutation`) that have no
+structural tell, by asking the judge whether the diff delivers the PR's
+stated claim. Large diffs are split into hunk-grouped chunks rather than
+head-truncated, so a defect in the tail still reaches the judge.
+
+Per-repo configuration in `.swarm/audit-config.yaml`: `excludePaths` exempts
+globs from detection, `intentSeverityPolicy` (`strict` | `lenient` | `off`)
+controls the PR-intent severity-upgrade layer, and `judgePrimary`
+(`enabled`, `categories`) controls the semantic path. See
+[`docs/audit-config.md`](docs/audit-config.md).
+
+### Reproducible evaluation
+
+Detection is measured against a defect-injection oracle, not asserted: an
+injector splices one labeled cheat into a presumed-clean real PR, and
+`npm run benchmarks:full` regenerates per-detector recall, judge
+calibration, tail-defect and evasion reports, and `COVERAGE.md`. The pre
+vs post A/B is in
+[`benchmarks/results/AB-REPORT.md`](benchmarks/results/AB-REPORT.md); the
+method and honesty caveats are in
+[`docs/audit/methodology.md`](docs/audit/methodology.md).
+
+Hunk-grouped chunking and per-hunk localization are infrastructure, not
+shipped recall wins: their mechanism tests pass, but on the current judge
+the tail-defect and per-hunk recall numbers stay low (a localized confirm
+prompt lifts tail-defect to 0.5 in measurement but is not shipped pending
+real-PR false-positive validation). The numbers are reported honestly in
+`benchmarks/oracle-corpus/tail-defect-recovery.md` and
+`per-hunk-localization.md`.
+
+The auditor is also validated on unbiased real PRs: `npm run real-prs:full`
+fetches recent merged PRs from public repos, audits them, and has an
+independent arbiter classify every finding. On an 18-PR pilot the
+post-upgrade false-alarm burden is 0.11 per PR, at or below the pre-upgrade
+auditor's, with the oracle recall gain intact
+([`benchmarks/real-prs/REAL-WORLD-REPORT.md`](benchmarks/real-prs/REAL-WORLD-REPORT.md)).
+
+The optional execution-grounded layer is evaluated separately: `npm run
+execution-grounded:full` provisions a sandboxed checkout of each corpus PR
+and runs diff-scoped mutation testing, issue-linked repro execution, and a
+coverage delta, then correlates the findings against each PR's revert/hotfix
+proof. It surfaces under-constrained changed lines that no diff-only tool can
+see (proof anchor `trpc/trpc#6098`: 10 mutants surviving on covered lines plus
+6 on uncovered lines, 8 of them on the lines the hotfix later changed), where
+the repo's test suite discriminates in a generic sandbox. This is a modest,
+honest result (1 proof-correlated catch in the sampled corpus, against a 0.929
+advisory-findings-per-clean-PR burden since v11.2 aggregated the
+uncovered-survivor floods per file; 3.357 before), measured rather than
+asserted; the
+per-repo viability and the headline numbers are in
+[`benchmarks/real-prs/v11-EXECUTION-GROUNDED-REPORT.md`](benchmarks/real-prs/v11-EXECUTION-GROUNDED-REPORT.md).
+
+## 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).
+
+## 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; no third-party AI-BOM runtime dep.
+
+Procurement mappings:
+
+- [`docs/eu-ai-act-mapping.md`](docs/eu-ai-act-mapping.md): EU AI Act Article 11 + Annex IV fields.
+- [`docs/cisa-sbom-ai-mapping.md`](docs/cisa-sbom-ai-mapping.md): CISA SBOM-for-AI minimum elements.
 
-<details>
-<summary><b><code>config/quality-gates.yaml</code>: built-in quality gates</b></summary>
+## Orchestrator mode
+
+Use this when you want Swarm to grade 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
 ```
 
-Full reference: [`docs/quality-gates.md`](docs/quality-gates.md).
-</details>
+Hosted-model run:
 
-<details>
-<summary><b><code>config/default-agents.yaml</code>: agent profiles</b></summary>
+```bash
+export ANTHROPIC_API_KEY=sk-...
+swarm run --goal "add a /health endpoint" --extractor anthropic --session anthropic
+```
 
-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.
+Local-LLM run (Ollama):
 
-Full reference: [`docs/configuration.md`](docs/configuration.md).
-</details>
+```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
+```
 
-## CLI Reference
+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).
 
-<details>
-<summary><b>Top-level commands</b></summary>
+## Architecture
 
-| 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 |
+Two 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`.
+
+`swarm audit` reuses the verifier and falsifier layers against a unified diff. It needs no session, no extractor, and no model credentials.
+
+Both surfaces write to the same append-only hash-chained ledger ([`src/ledger/ledger.ts`](src/ledger/ledger.ts)). Tampering breaks the chain.
+
+## 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 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.
+
+## 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)
+```
 
-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).
+`.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).
+
+## Versions
+
+`10.3.0-advisory` finishes the four solo-doable items left after
+`10.2.0-advisory`. `no-op-fix` bumps to 2.0.0 with a gated Anthropic
+Haiku judge (off by default; opt in with `--enable-llm-judge` or
+`SWARM_AUDIT_LLM_JUDGE=1`), content-addressed cache at
+`.swarm/llm-judge-cache/`, and a new `llm-judge-result` ledger entry
+that pins the model id so replay is deterministic. The real-corpus
+baseline is re-scored against the v2.0 detectors: overall F1 0.167
+(P 0.100, R 0.500), with `mock-of-hallucination` picking up 2 TPs the
+v1.x shape missed. A static dashboard fetches the score snapshot
+directly and publishes via GitHub Pages
+([moonrunnerkc.github.io/swarm-orchestrator](https://moonrunnerkc.github.io/swarm-orchestrator/docs/leaderboard/)).
+`--shadow-output <path>` writes one JSON object per audit with
+detector verdicts, judge invocation count, and the rendered comment;
+the existing `--shadow <repo-label>` per-repo rollup remains. No
+detector clears the promotion gate, so all ten stay advisory-only. (The
+v10 cycle gated on F1 >= 0.5; that criterion was superseded by precision
+>= 0.90 with a minimum true-positive count, the single bar stated under
+[Limitations and what's next](#limitations-and-whats-next).)
+
+`10.2.0-advisory` repositions the project around the suspicion-score
+verdict the measured precision can credibly support. Synthetic 1.000 is
+demoted to a regression-only number; the real-corpus 0.109 F1 is the
+only headline. `--mode advise|gate` makes the gate behavior opt-in. Six
+detectors retire to `--detectors experimental`. Every PR-comment finding
+renders its measured-precision badge inline. Shadow-mode infrastructure
+lands under `.swarm/shadow/`. Labeling methodology, kappa script, and
+labels-v2 scaffold ship alongside; the actual human labels are the next
+milestone.
+
+`10.1.0` raised detector accuracy on real PRs: the 205-entry hand-labeled
+baseline replaces the synthetic 500-case number as the published
+headline, the PR-intent layer escalates findings when the agent claims a
+fix, and five new manifest readers landed on `mock-of-hallucination`.
+
+`10.0.0` added the audit surface, the cheat detectors, the AI-BOM
+emitters, and the corpus. `9.x` removed the v6 verified-branch pipeline;
+pin `8.0.x` if you still need `swarm run --v6`.
+
+## Reference
+
+- [`action.yml`](action.yml): GitHub Action inputs and outputs.
+- [`src/contract/schema/v1.json`](src/contract/schema/v1.json): contract schema.
+- [`src/audit/cheat-detector/`](src/audit/cheat-detector/): detector registry.
+- [`src/audit/cheat-detector/detector-sets.ts`](src/audit/cheat-detector/detector-sets.ts): default vs. experimental selection.
+- [`src/audit/report-comment/detector-precision.ts`](src/audit/report-comment/detector-precision.ts): measured-precision table.
+- [`src/audit/aibom/`](src/audit/aibom/): AI-BOM emitters.
+- [`benchmarks/falsification-corpus/v10-synthetic-corpus/`](benchmarks/falsification-corpus/v10-synthetic-corpus/): synthetic regression corpus.
+- [`benchmarks/real-corpus/`](benchmarks/real-corpus/): real-corpus baseline + labels.
+- [`docs/labeling-methodology.md`](docs/labeling-methodology.md): labels-v2 rubric and kappa policy.
+- [`benchmarks/leaderboard/`](benchmarks/leaderboard/): reproducible scorer.
+- [`docs/shadow-mode.md`](docs/shadow-mode.md): single-file and per-repo shadow audit guide.
+- [`docs/`](docs/): provider, check-type, AI-BOM, and adapter docs.
+- [`CHANGELOG.md`](CHANGELOG.md): release history.
+- [`CONTRIBUTING.md`](CONTRIBUTING.md): development workflow.
+- [`SECURITY.md`](SECURITY.md): vulnerability reporting.
+- [`CLAUDE.md`](CLAUDE.md): maintainer architecture notes.
+
+## Limitations and what's next
+
+An honest accounting of where the tool is weak today and what is being worked on.
+
+- **It over-flags normal PRs at scale, so findings ship advisory.** On a large clean-PR corpus the structural detectors fire on legitimate patterns (relocated tests, refactors that change assertions, pragmatic suppressions) often enough that blocking on them would be noisy. That is why `--mode advise` is the default and nothing blocks unless you opt in. Narrowing that false-alarm rate until a detector can earn the gate is the active work.
+- **No single detector has cleared the bar to block on its own.** A detector becomes gate-eligible only when its measured precision is at least 0.90 with a minimum true-positive count behind it (the Wilson lower bound keeps a handful of lucky firings from promoting). This is the single criterion; the v10 F1 >= 0.5 gate is superseded. The tier is computed into [`benchmarks/real-corpus/promotions.json`](benchmarks/real-corpus/promotions.json) and CI fails if it drifts (`npm run promotions:check`), so today every detector is advisory-only. A second, corroborated tier applies the same 0.90 bar to the subset of a detector's findings that the opt-in execution-grounded layer backs (a surviving mutant, a coverage gap, or a still-failing repro); a detector that is noisy standalone can clear it, which is the concrete path to the first gate.
+- **A second way to earn a block does not go through labels, and it is also empty today.** Because detector-versus-label precision is pinned at 0, a block can instead come from a self-certifying runtime fact, with its trustworthiness calibrated against whether the PR was reverted or hotfixed afterward, not against any label. Three triggers qualify: a fix claim the linked issue's repro still contradicts (`claim-falsified`), a structural finding a surviving mutant or coverage gap corroborates on the same changed line (`corroborated-under-constraint`), and a declared contract obligation that fails on the patched workspace (`obligation-failure`). A trigger may gate only when its Wilson 95% lower bound clears 0.90 with at least 5 confirmed reverted true positives, computed into [`benchmarks/real-corpus/block-eligibility.json`](benchmarks/real-corpus/block-eligibility.json) and held by CI (`npm run block-policy:check`, which also refuses a threshold tuned below the floor). Calibrated against 72 reverted/hotfixed PRs and 232 clean ones ([`benchmarks/real-corpus/BLOCK-REPORT.md`](benchmarks/real-corpus/BLOCK-REPORT.md)), no trigger clears the bar: `corroborated-under-constraint` fired once, on a PR that was reverted (precision 1.0 but Wilson lower 0.207 on one case), and the other two did not fire. So `block-eligible` is 0 and gate mode still blocks nothing on its own. When a trigger does clear the bar, gate mode blocks on it with the reproduce command and evidence attached to the PR comment.
+- **The real-corpus baseline is AI-labeled, so blocking precision is not yet proven.** Against the 205-PR model-labeled baseline the deterministic detectors score low (F1 0.140, [`benchmarks/real-corpus/scores/latest.json`](benchmarks/real-corpus/scores/latest.json)), and every label carries a "pending human review" stamp. That AI-labeling is the largest open hole in the project's credibility; closing it with human labels is the next milestone ([`docs/labeling-methodology.md`](docs/labeling-methodology.md), [`benchmarks/real-corpus/labels-v2/`](benchmarks/real-corpus/labels-v2/)). The loop that closes it is built and tested, waiting on the rater pool: [`scripts/labeling/adjudicate.ts`](scripts/labeling/adjudicate.ts) queues the arbiter-split findings (where two arbiter model families disagree, the highest information per human minute), records the human verdicts, and promotes them to the scored baseline only once the pairwise Cohen's kappa clears 0.60. Promotion never overwrites a snapshot without `--write` and drops, rather than coerces, any verdict whose category has no detector to score it against.
+- **It is a cheat and under-constraint signal, not a bug finder.** It does not catch the logic bugs that get reverted; those leave no cheat-shaped tell. Use it to answer "did the agent cut a corner?" and "can I prove this patch met its contract?", not "is this code correct?".
+
+## Contributing
 
 ```bash
-git clone https://github.com/moonrunnerkc/swarm-orchestrator.git
-cd swarm-orchestrator
 npm install
+npm run build
 npm test
+npm run typecheck
+npm run lint
+npm run leaderboard
 ```
 
+Project conventions in [`CLAUDE.md`](CLAUDE.md). 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.