cervellaswarm-quality-gates

Quality gates for AI agent swarms: content scoring, hook validation, and agent sync.

Part of the CervellaSwarm ecosystem.

Features

• Content Quality Scoring - Score session documents across 4 dimensions: actionability (30%), specificity (30%), freshness (20%), conciseness (20%)
• Hook Validation - Verify hook file integrity: executable, correct shebang, proper permissions (OK/BROKEN/DISABLED/NOT_EXEC)
• Agent Sync - Compare and synchronize agent definition directories across projects
• CLI - cervella-check with subcommands: quality, hooks, sync, all
• Zero dependencies - Pure Python stdlib, no external packages required

Installation

pip install cervellaswarm-quality-gates

Quick Start

from cervellaswarm_quality_gates import score_content, validate_hooks, compare_agents

# Score a session document
result = score_content("## Session 42\n### What happened\n- Fixed auth bug in login flow\n### Next steps\n1. Deploy to staging")
print(f"Quality: {result.total:.1f}/10")

# Validate hooks in a directory
reports = validate_hooks("/path/to/hooks/")
for r in reports:
    print(f"{r.name}: {r.status.value}")

# Compare agent directories
diff = compare_agents("/project-a/agents/", "/project-b/agents/")
print(f"Only in A: {diff.only_in_source}")

CLI Usage

# Score content quality of a file
cervella-check quality path/to/session-state.md

# Validate all hooks in a directory
cervella-check hooks path/to/hooks/

# Compare agent directories
cervella-check sync /agents/source/ /agents/target/

# Run all checks with JSON output
cervella-check all --project-dir . --json

Configuration

Config file search order:

1. CERVELLASWARM_QUALITY_GATES_CONFIG env var
2. .cervella/quality-gates.yaml in project root
3. ~/.claude/quality-gates.yaml (user-level)

# .cervella/quality-gates.yaml
quality:
  weights:
    actionability: 0.30
    specificity: 0.30
    freshness: 0.20
    conciseness: 0.20
  min_score: 7.0

hooks:
  directory: .claude/hooks/
  required_hooks:
    - session_start
    - file_limits

sync:
  ignore_patterns:
    - "*.pyc"
    - "__pycache__"

Scoring Dimensions

Hook Statuses

Comparison with Alternatives

License

Apache-2.0 - see LICENSE for details.