quorum

Cross-model audit gate with structural enforcement. One model cannot approve its own code.

한국어

edit → audit → agree → retro → commit

What it does

quorum enforces a consensus protocol between AI agents. When code is written, an independent auditor reviews the evidence. If rejected, the author must fix and resubmit. The cycle repeats until consensus is reached — only then can the code be committed.

The key principle: no single model can both write and approve code. This is the "quorum" — a minimum number of independent voices required for a decision.

Installation

Standalone (any AI tool)

quorum works without any IDE plugin. Just the CLI.

npm install -g quorum-audit    # global install
# or
npx quorum-audit setup         # one-shot without install

cd your-project
quorum setup                   # creates config + MCP server registration
quorum daemon                  # TUI dashboard

Works with any AI coding tool — Claude Code, Codex, Gemini, or manual use.

As a Claude Code plugin

For automatic hook integration (event-driven audit on every edit):

claude plugin marketplace add berrzebb/quorum
claude plugin install quorum@berrzebb-plugins

This registers 22 lifecycle hooks, 22 MCP tools, 9 skills, and 12 specialist agents automatically. The CLI still works alongside the plugin.

As a Gemini CLI extension

For automatic hook integration with Gemini CLI:

gemini extensions install https://github.com/berrzebb/quorum.git
# or for development:
gemini extensions link adapters/gemini

As a Codex CLI hook

For automatic hook integration with OpenAI Codex CLI:

# Copy hooks config to project
cp adapters/codex/hooks/hooks.json .codex/hooks.json
# Enable hooks feature flag
codex -c features.codex_hooks=true

This registers 5 hooks (SessionStart, Stop, UserPromptSubmit, AfterAgent, AfterToolUse). Same audit engine as Claude Code and Gemini.

This registers 11 hooks, 8 skills, 4 commands, and 22 MCP tools. Same audit engine as Claude Code.

From source

git clone https://github.com/berrzebb/quorum.git
cd quorum && npm install && npm run build
npm link                       # makes 'quorum' available globally

CLI

quorum <command>

  setup          Initialize quorum in current project
  interview      Interactive requirement clarification
  daemon         Start TUI dashboard
  status         Show audit gate status
  audit          Trigger manual audit
  plan           Work breakdown planning
  orchestrate    Track orchestration (parallel execution)   # v0.4.0
  ask <provider> Query a provider directly
  tool <name>    Run MCP analysis tool
  migrate        Import consensus-loop data into quorum
  help           Show help

Migrating from consensus-loop

If you were using consensus-loop (v2.5.0), quorum can import your existing data:

quorum migrate            # import config, audit history, session state
quorum migrate --dry-run  # preview without changes

What it migrates:

| Data | From | To | |------|------|----| | Config | .claude/consensus-loop/config.json | .claude/quorum/config.json | | Audit history | .claude/audit-history.jsonl | SQLite EventStore | | Session state | .session-state/retro-marker.json | Preserved (shared location) | | Evidence submission | docs/feedback/claude.md | audit_submit MCP tool | | MCP server | .mcp.json consensus-loop entry | Cloned as quorum entry |

Your existing evidence is preserved — quorum reads from SQLite via audit_submit tool.

How it works

Without a plugin (standalone)

you write code
    → quorum audit              # trigger manually
    → auditor reviews           # Codex, GPT, Claude, or any provider
    → quorum status             # check verdict
    → fix if rejected           # resubmit
    → quorum daemon             # watch the cycle in real-time TUI

With Claude Code plugin (automatic)

you write code
    → PostToolUse hook fires    # automatic
    → regex scan + AST refine   # hybrid: false positive removal
    → fitness score computed    # 7-component quality metric
    → fitness gate              # auto-reject / self-correct / proceed
    → trigger eval (12 factors)# skip, simple, or deliberative
    → auditor runs              # background, debounced
    → verdict syncs             # tag promotion/demotion
    → session-gate              # blocks until retro complete
    → commit allowed

Both paths use the same core engine: bus/ + providers/ + core/.

Architecture

quorum/
├── cli/              ← unified entry point (works without any plugin)
├── daemon/           ← Ink TUI dashboard + FitnessPanel (works standalone)
├── bus/              ← EventStore (SQLite) + pub/sub + stagnation + LockService + Fitness + Claims + Orchestrator
├── providers/        ← consensus protocol + trigger (12-factor) + router + domain specialists + AST analyzer
├── core/             ← audit protocol (7 modules), templates, 22 MCP tools
├── languages/        ← pluggable language specs (fragment-based: spec.mjs + spec.{domain}.mjs)
├── agents/knowledge/ ← shared agent protocols (cross-adapter: implementer, scout, 9 specialist domains)
└── adapters/
    ├── shared/       ← adapter-agnostic business logic (17 modules, incl. HookRunner, NDJSON, MuxAdapter)
    ├── claude-code/  ← Claude Code hooks (22) + agents (12) + skills (9)
    ├── gemini/       ← Gemini CLI hooks (11) + skills (8) + commands (4)
    └── codex/        ← Codex CLI hooks (5)

The adapters/ layer is optional. Everything above it runs independently. Adding a new adapter requires only I/O wrappers — business logic is in adapters/shared/.

Core Concepts

Parliament Protocol

Legislative deliberation framework for structured consensus:

quorum parliament "topic"             → CPS (Context-Problem-Solution)
quorum orchestrate plan <track>       → interactive planner (Socratic + CPS)
quorum orchestrate run <track>        → full implementation loop (auto)

Enforcement Gates

8 gates that block progress until conditions are met (not just document — code enforces):

| Gate | Blocks when | Releases when | |------|------------|---------------| | Audit | Evidence submitted | Auditor approves | | Retro | Audit approved | Retrospective complete | | Quality | Lint/test fails | All checks pass | | Amendment | Pending amendments | All resolved (vote) | | Verdict | Last verdict ≠ approved | Re-audit passes | | Confluence | Integrity check failed | 4-point verification passes | | Design | Design artifacts missing | Spec + Blueprint exist | | Regression | Normal-form stage regressed | Alert only |

Deliberative Consensus

For complex changes (T3), a 3-role protocol runs:

1. Advocate: finds merit in the submission
2. Devil's Advocate: challenges assumptions, checks root cause vs symptom
3. Judge: weighs both opinions, delivers final verdict

Language Spec Fragments (v0.4.1)

Quality patterns are defined per language in pluggable fragment files:

languages/typescript/
  spec.mjs            ← core: id, name, extensions (3 lines)
  spec.symbols.mjs    ← symbol extraction patterns
  spec.imports.mjs    ← dependency parsing
  spec.perf.mjs       ← performance anti-patterns
  spec.a11y.mjs       ← accessibility patterns
  spec.observability.mjs
  spec.compat.mjs
  spec.doc.mjs        ← documentation coverage

Adding a new language = spec.mjs (3 lines) + relevant fragments. Adding a domain to an existing language = one new fragment file. The registry (languages/registry.mjs) auto-discovers and merges fragments at load time.

Domain Specialists (v0.3.0)

When changes touch specialized domains, quorum conditionally activates expert reviewers:

| Domain | Tool | Agent | Min Tier | |--------|------|-------|----------| | Performance | perf_scan | perf-analyst | T2 | | Migration | compat_check | compat-reviewer | T2 | | Accessibility | a11y_scan | a11y-auditor | T2 | | Compliance | license_scan | compliance-officer | T2 | | i18n | i18n_validate | — | T2 | | Infrastructure | infra_scan | — | T2 | | Observability | observability_check | — | T3 | | Documentation | doc_coverage | — | T3 | | Concurrency | — | concurrency-verifier | T3 |

Tools are deterministic (zero cost, always run). Agents are LLM-powered (only at sufficient tier).

Hybrid Scanning

Pattern scanning uses a 3-layer defense against false positives:

1. Regex first pass — fast (<1ms/file), catches candidates
2. scan-ignore pragma — // scan-ignore suppresses self-referential matches
3. AST second pass — precise (<50ms/file), removes comment/string matches, analyzes control flow

The perf_scan tool uses hybrid scanning: regex detects while(true), AST verifies if break/return exists.

Program mode (ts.createProgram()) enables cross-file analysis: unused export detection and import cycle detection via dependency graph DFS.

Fitness Score Engine

Inspired by Karpathy's autoresearch: what is measurable is not asked to the LLM.

Seven components combine into a 0.0–1.0 fitness score:

| Component | Weight | Input | |-----------|--------|-------| | Type Safety | 0.20 | as any count per KLOC | | Test Coverage | 0.20 | Line + branch coverage | | Pattern Scan | 0.20 | HIGH-severity findings | | Build Health | 0.15 | tsc + eslint pass rate | | Complexity | 0.10 | Avg cyclomatic complexity | | Security | 0.10 | Vulnerability findings | | Dependencies | 0.05 | Outdated/vulnerable deps |

The FitnessLoop gates LLM audit with 3 decisions:

• auto-reject: score drop >0.15 or absolute <0.3 → skip LLM audit (cost savings)
• self-correct: mild drop (0.05–0.15) → warn agent, continue
• proceed: stable/improved → update baseline, continue to audit

Conditional Trigger

Not every change needs full consensus. A 13-factor scoring system (6 base + domain + plan + fitness + blast radius + velocity + stagnation + interaction multipliers) determines the audit level:

| Tier | Score | Mode | |------|-------|------| | T1 | < 0.3 | Skip (micro change) | | T2 | 0.3–0.7 | Simple (single auditor) | | T3 | > 0.7 | Deliberative (3-role) |

3-Layer Adapter Pattern (v0.4.2)

Shared business logic across adapters. Only I/O differs per runtime:

I/O (adapters/{adapter}/)
  Claude Code: hookSpecificOutput, permissionDecision
  Gemini CLI:  JSON-only stdout, hookSpecificOutput
  Codex CLI:   .codex/hooks.json, config.toml
      ↓ readStdinJson() + withBridge() + createHookContext()
Business Logic (adapters/shared/ — 17 modules)
  hook-runner, hook-loader, trigger-runner, ndjson-parser,
  cli-adapter, mux-adapter, jsonrpc-client, sdk-tool-bridge, ...
      ↓ bridge.init() + bridge.checkHookGate()
Core (core/)
  audit, tools (21 MCP), EventStore, bus, providers

Adding a new adapter requires ~280 lines (proven by the Codex adapter).

HookRunner Engine (v0.4.2)

User-defined hooks. Configure in config.json or HOOK.md:

// .claude/quorum/config.json
{
  "hooks": {
    "audit.submit": [
      { "name": "freeze-guard", "handler": { "type": "command", "command": "node scripts/check-freeze.mjs" } }
    ]
  }
}

command/http handlers, env interpolation ($VAR, ${VAR}), deny-first-break, async fire-and-forget, regex matcher filtering.

Multi-Model NDJSON Protocol (v0.4.2)

Unified parsing of 3 CLI runtime outputs:

| Runtime | Format | Adapter | |---------|--------|---------| | Claude Code | stream-json | ClaudeCliAdapter | | Codex | exec --json | CodexCliAdapter | | Gemini | stream-json | GeminiCliAdapter |

All outputs are normalized to AgentOutputMessage (assistant_chunk, tool_use, tool_result, complete, error). MuxAdapter bridges ProcessMux (tmux/psmux) sessions for real-time cross-model consensus.

Stagnation Detection

If the audit loop cycles without progress, 5 patterns are detected:

• Spinning: same verdict 3+ times
• Oscillation: approve → reject → approve → reject
• No drift: identical rejection codes repeating
• Diminishing returns: improvement rate declining
• Fitness plateau: fitness score slope ≈ 0 over last N evaluations

Blast Radius Analysis (v0.4.0)

BFS on the reverse import graph computes transitive dependents of changed files:

quorum tool blast_radius --changed_files '["core/bridge.mjs"]'
# → 12/95 files affected (12.6%) — depth-sorted impact list

• 10th trigger factor: ratio > 10% → score += up to 0.15 (auto-escalation to T3)
• Pre-verify evidence: blast radius section included in auditor evidence
• Reuses buildRawGraph() extracted from dependency_graph (TTL-cached)

Structured Orchestration (v0.4.0)

Multi-agent coordination for parallel worktree execution:

| Component | Purpose | |-----------|---------| | ClaimService | Per-file ownership (INSERT...ON CONFLICT), TTL-based expiry | | ParallelPlanner | Graph coloring for conflict-free execution groups | | OrchestratorMode | Auto-selects: serial / parallel / fan-out / pipeline / hybrid | | Auto-learning | Detects repeat rejection patterns (3+), suggests CLAUDE.md rules |

Event Reactor (v0.4.0)

respond.mjs rewritten as a pure event reactor: reads SQLite verdict events → executes side-effects only. No markdown read/write. -1043/+211 lines refactoring.

Dynamic Escalation

The tier router tracks failure history per task:

• 2 consecutive failures → escalate to higher tier
• 2 consecutive successes → downgrade back
• Frontier failures → stagnation signal

Planner Documents

The planner skill produces 10 document types for structured project planning:

| Document | Level | Purpose | |----------|-------|---------| | PRD | Project | Product requirements — problem, goals, features, acceptance criteria | | Execution Order | Project | Track dependency graph — which tracks to execute first | | Work Catalog | Project | All tasks across all tracks with status and priority | | ADR | Project | Architecture Decision Records — why, not just what | | Track README | Track | Track scope, goals, success criteria, constraints | | Work Breakdown | Track | Task decomposition — ### [task-id] blocks with depends_on/blocks | | API Contract | Track | Endpoint specs, request/response schemas, auth | | Test Strategy | Track | Test plan — unit/integration/e2e scope, coverage targets | | UI Spec | Track | Component hierarchy, states, interactions | | Data Model | Track | Entity relationships, schemas, migrations |

Providers

quorum is provider-agnostic. Bring your own auditor.

| Provider | Mechanism | Hooks | Plugin needed? | |----------|-----------|-------|---------------| | Claude Code | 22 native hooks | SessionStart, PreToolUse, PostToolUse, Stop, PermissionRequest, Notification, ... | Optional (auto-triggers) | | Gemini CLI | 11 hooks + 8 skills | SessionStart, BeforeAgent, AfterAgent, BeforeTool, AfterTool, BeforeModel, ... | Optional (gemini extensions install) | | Codex CLI | 5 hooks | SessionStart, Stop, UserPromptSubmit, AfterAgent, AfterToolUse | Optional (.codex/hooks.json) | | Manual | quorum audit | — | No |

Tools & Verification

Deterministic tools that replace LLM judgment with facts. No hallucination possible.

Analysis tools (19):

# Core analysis
quorum tool code_map src/              # symbol index
quorum tool dependency_graph .          # import DAG, cycles
quorum tool blast_radius --changed_files '["src/api.ts"]'  # transitive impact (v0.4.0)
quorum tool audit_scan src/             # type-safety, hardcoded patterns
quorum tool coverage_map                # per-file test coverage
quorum tool audit_history --summary     # verdict patterns
quorum tool ai_guide                    # context-aware onboarding (v0.4.0)

# RTM & verification
quorum tool rtm_parse docs/rtm.md      # parse RTM → structured rows
quorum tool rtm_merge --base a --updates '["b"]'  # merge worktree RTMs
quorum tool fvm_generate /project       # FE×API×BE access matrix
quorum tool fvm_validate --fvm_path x --base_url http://localhost:3000 --credentials '{}'

# Domain specialists (v0.3.0)
quorum tool perf_scan src/             # performance anti-patterns (hybrid: regex+AST)
quorum tool compat_check src/          # API breaking changes
quorum tool a11y_scan src/             # accessibility (JSX/TSX)
quorum tool license_scan .             # license compliance + PII
quorum tool i18n_validate .            # locale key parity
quorum tool infra_scan .               # Dockerfile/CI security
quorum tool observability_check src/   # empty catch, logging gaps
quorum tool doc_coverage src/          # JSDoc coverage %

Verification pipeline (quorum verify):

quorum verify              # all checks
quorum verify CQ           # code quality (eslint)
quorum verify SEC          # OWASP security (10 patterns, semgrep if available)
quorum verify LEAK         # secrets in git (gitleaks if available, built-in fallback)
quorum verify DEP          # dependency vulnerabilities (npm audit)
quorum verify SCOPE        # diff vs evidence match

Full reference: docs/en/TOOLS.md | docs/ko/TOOLS.md

Tests

npm test                # 1055 tests
npm run typecheck       # TypeScript check
npm run build           # compile

CI/CD

GitHub Actions builds cross-platform binaries on tag push:

git tag v0.4.2
git push origin v0.4.2
# → linux-x64, darwin-x64, darwin-arm64, win-x64 binaries in Releases

License

MIT