🛡️ Hexaqual

🛡️ Universal quality & governance engine for Hexastack, Hexaqueue, and Hexaflow · 🌊 Execution DAGs powered by Hexaflow

Universal Python quality gates, architectural boundary enforcement, and release engineering toolchain.

Hexaqual provides an opinionated, high-velocity quality harness designed for modular Python architectures, monorepos, and single-package projects. It unifies linting, type-checking, cognitive complexity enforcement, __all__ integrity, 1:1 test symmetry, and automated PyPI release workflows into a cohesive, workflow-driven developer CLI.

🚀 Key Features

• Workflow-Driven Sanity Checks: Multi-stage DAG pipeline powered by Hexaflow for parallel linting, typechecking, and testing.
• Turnkey GitHub Marketplace Action: Drop-in composite action setting up Python, uv, pre-commit caching, and executing quality checks in CI.
• Architectural Invariants: First-class support for hexagonal layer enforcement (domain, ports, adapters, infra).
• Test Parity Enforcement: 1:1 symmetry verification between source modules and unit test suites.
• Public API Integrity: Automatic sorting, deduplication, and AST validation of __all__ exports.
• Smart PyPI Publishing: Dependency-ordered, reproducible builds with automatic skip-if-exists checks.

⚡ GitHub Marketplace Action

Hexaqual is available on the GitHub Marketplace as a turnkey composite action that automatically sets up uv, Python, caches pre-commit environments, and runs your checks:

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: TheTrueSCU/hexaqual@v0.4.0
        with:
          mode: "pre-commit" # options: 'pre-commit', 'sanity', 'setup'
          sync-args: "--all-extras --dev"

📦 Installation

# Add as a development dependency
uv add --dev hexaqual

# Or install globally
uv tool install hexaqual

🛠️ Unified CLI (hexaqual)

Hexaqual subsumes all developer quality tools into a single unified entrypoint (hexaqual). It dynamically detects workspace layout:

• Multi-package workspaces (packages/ exists): accepts -p / --package to filter focus across packages, or -a / --all for the whole workspace.
• Single-package projects (no packages/): automatically focuses on the root package without requiring -p.
• Examples support: if an examples/ directory exists, -e / --example allows targeted auditing of example projects.

Command Overview

# Run sanity checks on specific packages in a workspace
hexaqual check -p core -p cqrs

# Run sanity check with auto-formatting on a single-package repo
hexaqual check --fix

# Audit __all__ integrity across all packages
hexaqual statements check

# Run pytest on tests impacted by recent git changes
hexaqual test impact

# Examine a GitHub Pull Request dashboard with live polling
hexaqual gh pr 42 --watch

# Verify USAGE.md catalog is up to date
hexaqual docs usage --check

For the complete unrolled CLI reference and full option listings for every subcommand, see USAGE.md.

🪝 Git Lifecycle Hooks & Commit Governance

Standard pre-commit install only installs the pre-commit stage by default. Hexaqual provides a unified hooks manager that configures all 5 critical lifecycle stages in a single step:

# Install all 5 hook stages (pre-commit, commit-msg, pre-push, post-merge, post-checkout)
uv run hexaqual hooks install

# Inspect active hook status across all stages
uv run hexaqual hooks check

Pre-Commit Configuration (.pre-commit-config.yaml)

Hexaqual distributes reusable hooks via GitHub:

repos:
  - repo: https://github.com/TheTrueSCU/hexaqual
    rev: v0.8.0
    hooks:
      - id: hexaqual-sanity        # Fast static sanity gate (Ruff, Ty, complexipy, etc.)
      - id: hexaqual-architecture  # Verify test_hexagonal_boundaries.py suites
      - id: hexaqual-agents        # Verify .agents/ assets match installed hexaqual
      - id: hexaqual-agents-sync   # Auto-sync .agents/ on post-merge and post-checkout
      - id: hexaqual-commit-msg    # Enforce Conventional Commits & DCO on commit-msg
      - id: hexaqual-pre-push      # Run fast sanity check on pre-push

🧬 Dual-Engine Mutation Testing

Hexaqual implements a high-velocity dual-engine mutation testing harness:

1. pytest-gremlins (Default): In-process AST mutation engine targeting executable boundary conditions (< vs <=, and vs or, arithmetic, returns). Delivers 100% actionable signal with decoupled multicore scaling:
   • -n auto: Parallel baseline pytest execution via pytest-xdist.
   • -w auto: Parallel in-process mutation workers (--gremlin-workers).
   • --batch-size 10: Batched mutant execution (--gremlin-batch).
   • -A / --affected: Scopes mutation testing strictly to packages impacted by git diff.
2. mutmut: Subprocess-isolated deep mutation auditor for literal constants, token shifts, and pre-release audits.

# High-velocity developer loop: multicore auto-scaled boundary mutations
uv run hexaqual mutate run -p <pkg> -e gremlins -w auto --batch-size 10 -n auto

# Scoped to affected packages only (ideal for PR CI verification)
uv run hexaqual mutate run -A -e gremlins -w auto

# Deep literal constant audit
uv run hexaqual mutate run -p <pkg> -e mutmut

# High-level triage summary of surviving mutants (Critical, Equivalent, Ignorable)
uv run hexaqual mutate inspect -s

# Actionable critical mutants only
uv run hexaqual mutate inspect -p <pkg> -act

🐕 Dogfooding Hexaflow: Workflows as Architecture

Hexaqual serves as the primary real-world dogfooding ground for Hexaflow, demonstrating how lightweight, in-memory workflow DAGs can orchestrate high-performance developer tooling without complexity or latency.

The Sanity Workflow DAG

Rather than executing checks in a rigid, monolithic sequence or maintaining ad-hoc shell orchestration, hexaqual sanity compiles each target's verification into a declarative hexaflow.Workflow:

graph LR
    subgraph stage1 ["Stage 1: Leaf Static Checks"]
        Lint["Ruff Lint & Format"]
        Statements["__all__ Integrity"]
        Parity["1:1 Test Symmetry"]
    end

    subgraph stage2 ["Stage 2: Static Analysis"]
        Typecheck["Ty Typecheck"]
        Complexity["Cognitive Complexity <= 25"]
    end

    subgraph stage3 ["Stage 3: Dynamic Verification"]
        Pytest["Pytest Test Suites"]
    end

    Lint --> Typecheck
    Statements --> Typecheck
    Parity --> Complexity
    Typecheck --> Pytest
    Complexity --> Pytest

Why Dogfooding Hexaflow Matters:

1. Deterministic Staging & Fail-Fast: Ultra-fast leaf AST checks (Ruff, __all__, test symmetry) execute in Stage 1 (~0.05s), providing immediate feedback before heavier static analysis (Ty, complexipy) or test suites run.
2. Granular Step Checkpoints: Each verification step executes within a discrete StepContext, recording execution metrics, structured findings, and pass/fail states into an InMemoryStateStore.
3. Zero-Latency Overhead: Hexaflow's minimal runtime footprint adds virtually zero overhead—the entire 5-stage static check pipeline runs in under 0.6 seconds.
4. Resilient Error Isolation: If a step fails, the workflow gracefully preserves partial reports, enabling the Rich presenter to render complete multi-target dashboards showing exact failure context.

🤖 Universal AI Guardrails & Agent Management (.agents/)

Hexaqual acts as the single source of truth for AI pair programming assistants (Antigravity CLI, Cursor, Claude Code, Windsurf) across the entire hexa- family (hexastack, hexaqueue, hexaflow, hexaqual).

It implements a Two-Tier Architecture:

1. Universal Guardrails (Managed by hexaqual): Bundled rules (hexaqual-*.md), workflows (hexaqual-*.md), and skills (hexaqual_*.py) that apply universally across every repository.
2. Family-Member Guardrails (Local to X): Repository-specific rules (hexa<X>-*.md) that define project-specific invariants (e.g., hexaqueue-elevation.md, hexaflow-dag-invariants.md). These local assets are preserved untouched during synchronizations.

Bundled Universal Catalog

CLI Synchronization & Drift Verification

# Synchronize universal guardrails to current repository (preserves local hexaX-* rules)
uv run hexaqual agents sync

# Dry-run simulation of synchronization
uv run hexaqual agents sync --dry-run

# Verify repository guardrails match the installed hexaqual version (pre-commit gate)
uv run hexaqual agents check

# List all universal bundled rules, workflows, and skills
uv run hexaqual agents list

Root Pointer (AGENTS.md) & Dynamic Reloading

• Aggregated Index: hexaqual agents sync creates a root AGENTS.md indexing all active rules, workflows, and skills (both universal hexaqual-* and project-specific hexa<X>-* assets). This ensures single-file agent tools (like GitHub Copilot Workspace) maintain full context.
• VCS Hygiene: hexaqual agents sync ensures .gitignore excludes .agents/*/hexaqual-* so upstream assets are never committed to git. Maintainers may commit AGENTS.md for GitHub visibility or add it to local .git/info/exclude to keep the root directory clean.
• Per-Turn Dynamic Reloading: In Antigravity CLI/IDE, rule files under .agents/rules/ and AGENTS.md are dynamically reloaded at the start of each user prompt, so synced guardrails take effect immediately on the next interaction.

🏛️ Architecture & Documentation

• Architecture & Design Guide: Hexagonal boundaries, CQRS command bus, and architectural invariants.
• AI Agent Governance Guide: Universal .agents/ rules, SDLC workflows, colocated skills, and VCS hygiene.
• CLI Reference Catalog: Full unrolled command and subcommand trees with exhaustive option listings.

📄 License

Apache-2.0. See LICENSE for details.