hexaswarm-core 0.1.1__py3-none-any.whl

hexa_swarm_core/__init__.py

@@ -0,0 +1,7 @@
+"""hexa_swarm_core — Universal primitives for Claude-native multi-agent delivery."""
+
+from __future__ import annotations
+
+from hexa_swarm_core._version import __version__
+
+__all__ = ["__version__"]

hexa_swarm_core/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

hexa_swarm_core/adapters/__init__.py

@@ -0,0 +1,12 @@
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import InvariantEnforcer, StackAdapter
+from hexa_swarm_core.adapters.registry import ADAPTERS, detect_adapters, get_adapter
+
+__all__ = [
+    "ADAPTERS",
+    "BaseAdapter",
+    "InvariantEnforcer",
+    "StackAdapter",
+    "detect_adapters",
+    "get_adapter",
+]

hexa_swarm_core/adapters/_node_base.py

@@ -0,0 +1,66 @@
+"""Shared plumbing for Node-family adapters (next, nest, express)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import CommandSpec
+
+
+class NodeAdapterBase(BaseAdapter):
+    """Base for Node/TS adapters - handles pnpm/yarn/npm dispatch uniformly."""
+
+    language = "typescript"
+
+    @staticmethod
+    def _pm(project_root: Path) -> str:
+        if (project_root / "pnpm-lock.yaml").exists():
+            return "pnpm"
+        if (project_root / "yarn.lock").exists():
+            return "yarn"
+        return "npm"
+
+    def _run(self, project_root: Path, script: str) -> list[CommandSpec]:
+        pm = self._pm(project_root)
+        if pm == "pnpm":
+            return [CommandSpec(["pnpm", "run", script], description=f"pnpm run {script}")]
+        if pm == "yarn":
+            return [CommandSpec(["yarn", script], description=f"yarn {script}")]
+        return [CommandSpec(["npm", "run", script, "--if-present"], description=f"npm run {script}")]
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._run(project_root, "lint")
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._run(project_root, "test")
+
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._run(project_root, "build")
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:
+        pm = self._pm(project_root)
+        if pm == "pnpm":
+            return [CommandSpec(["pnpm", "exec", "prettier", "--check", "."], description="prettier --check")]
+        if pm == "yarn":
+            return [CommandSpec(["yarn", "prettier", "--check", "."], description="yarn prettier --check")]
+        return [CommandSpec(["npx", "--yes", "prettier", "--check", "."], description="npx prettier --check")]
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:
+        pm = self._pm(project_root)
+        if pm == "pnpm":
+            return [CommandSpec(["pnpm", "exec", "tsc", "--noEmit"], description="tsc --noEmit")]
+        if pm == "yarn":
+            return [CommandSpec(["yarn", "tsc", "--noEmit"], description="yarn tsc --noEmit")]
+        return [CommandSpec(["npx", "--yes", "tsc", "--noEmit"], description="npx tsc --noEmit")]
+
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]:
+        pm = self._pm(project_root)
+        if pm == "pnpm":
+            return [CommandSpec(["pnpm", "audit", "--audit-level=high"], description="pnpm audit")]
+        if pm == "yarn":
+            return [CommandSpec(["yarn", "npm", "audit", "--severity", "high"], description="yarn npm audit")]
+        return [CommandSpec(["npm", "audit", "--audit-level=high"], description="npm audit")]
+
+
+__all__ = ["NodeAdapterBase"]

hexa_swarm_core/adapters/base.py

@@ -0,0 +1,70 @@
+"""BaseAdapter — a default skeleton most adapters can subclass."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hexa_swarm_core.adapters.protocol import CommandSpec, InvariantEnforcer
+
+
+class BaseAdapter:
+    """Common adapter plumbing.
+
+    Subclasses override attributes (name, language, detect_files, detect_imports,
+    priority) and `_*_cmd()` methods as needed. Default implementations return
+    empty lists — "no-op" is a valid adapter stance for a stage it doesn't own.
+    """
+
+    name: str = "base"
+    language: str = "unknown"
+    detect_files: list[str] = []
+    detect_imports: list[str] = []
+    priority: int = 0
+
+    # -- detection --------------------------------------------------------
+    def detect(self, project_root: Path) -> bool:
+        if not self.detect_files:
+            return False
+        matched: list[Path] = []
+        for glob in self.detect_files:
+            matched.extend(project_root.glob(glob))
+        if not matched:
+            return False
+        if not self.detect_imports:
+            return True
+        for path in matched:
+            try:
+                text = path.read_text(encoding="utf-8", errors="ignore")
+            except OSError:
+                continue
+            if any(imp in text for imp in self.detect_imports):
+                return True
+        return False
+
+    # -- commands (override in subclasses) --------------------------------
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return []
+
+    def contract_generator(self, project_root: Path) -> CommandSpec | None:  # noqa: ARG002
+        return None
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return []
+
+
+__all__ = ["BaseAdapter"]

hexa_swarm_core/adapters/generic_shell.py

@@ -0,0 +1,47 @@
+"""generic-shell adapter — fallback for `hexa adopt` on unknown stacks.
+
+Does not presume any linter/test runner. Reads `.hexa/profile.yaml` or a
+`Makefile` for user-provided commands. Safe to use anywhere — just a thin
+command registry that keeps the CLI interface uniform across stacks.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import CommandSpec
+
+
+class GenericShellAdapter(BaseAdapter):
+    name = "generic-shell"
+    language = "shell"
+    detect_files = ["Makefile", "justfile", "Taskfile.yml"]
+    priority = 5  # very low — only matches when nothing else does
+
+    def detect(self, project_root: Path) -> bool:
+        # Always available as an explicit fallback, but `detect()` only returns
+        # True when a Make-like runner exists. Registry still allows forcing
+        # this adapter via `--stack generic-shell`.
+        return any((project_root / f).exists() for f in self.detect_files)
+
+    def _make_cmd(self, target: str, description: str) -> list[CommandSpec]:
+        return [CommandSpec(["make", target], description=description)]
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._make_cmd("lint", "make lint") if (project_root / "Makefile").exists() else []
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._make_cmd("fmt", "make fmt") if (project_root / "Makefile").exists() else []
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._make_cmd("typecheck", "make typecheck") if (project_root / "Makefile").exists() else []
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._make_cmd("test", "make test") if (project_root / "Makefile").exists() else []
+
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]:
+        return self._make_cmd("build", "make build") if (project_root / "Makefile").exists() else []
+
+
+__all__ = ["GenericShellAdapter"]

hexa_swarm_core/adapters/go_chi.py

@@ -0,0 +1,47 @@
+"""go-chi StackAdapter - Go services using the chi router."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import CommandSpec, InvariantEnforcer
+
+
+class GoChiAdapter(BaseAdapter):
+    name = "go-chi"
+    language = "go"
+    detect_files = ["go.mod"]
+    detect_imports = ["github.com/go-chi/chi"]
+    priority = 65
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["golangci-lint", "run", "./..."], description="golangci-lint")]
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["gofmt", "-l", "."], description="gofmt -l (nonempty = drift)")]
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["go", "build", "-o", os.devnull, "./..."], description="go build (typecheck)")]
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["go", "test", "-race", "-count=1", "./..."], description="go test -race")]
+
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["go", "build", "./..."], description="go build")]
+
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["govulncheck", "./..."], description="govulncheck")]
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return [
+            InvariantEnforcer(
+                invariant="S5",
+                description="go vet must pass before merge",
+                cmd=["go", "vet", "./..."],
+            ),
+        ]
+
+
+__all__ = ["GoChiAdapter"]

hexa_swarm_core/adapters/kotlin_ktor.py

@@ -0,0 +1,55 @@
+"""kotlin-ktor StackAdapter - Kotlin services using Ktor."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import CommandSpec, InvariantEnforcer
+
+
+class KotlinKtorAdapter(BaseAdapter):
+    name = "kotlin-ktor"
+    language = "kotlin"
+    detect_files = [
+        "build.gradle.kts",
+        "build.gradle",
+        "settings.gradle.kts",
+    ]
+    detect_imports = ["io.ktor"]
+    priority = 65
+
+    @staticmethod
+    def _gradle(project_root: Path) -> str:
+        return "./gradlew" if (project_root / "gradlew").exists() else "gradle"
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        return [CommandSpec([g, "ktlintCheck"], description="ktlint")]
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        return [CommandSpec([g, "detekt"], description="detekt")]
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        return [CommandSpec([g, "compileKotlin", "--no-daemon"], description="kotlin compile")]
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        return [CommandSpec([g, "test", "--no-daemon"], description="gradle test")]
+
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        return [CommandSpec([g, "build", "-x", "test", "--no-daemon"], description="gradle build")]
+
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]:
+        g = self._gradle(project_root)
+        # Requires the OWASP dependency-check plugin; a no-op when absent.
+        return [CommandSpec([g, "dependencyCheckAnalyze", "--no-daemon"], description="owasp dep-check")]
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return []
+
+
+__all__ = ["KotlinKtorAdapter"]

hexa_swarm_core/adapters/node_express.py

@@ -0,0 +1,38 @@
+"""node-express StackAdapter - Express / Fastify / Koa style Node services."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from hexa_swarm_core.adapters._node_base import NodeAdapterBase
+from hexa_swarm_core.adapters.protocol import InvariantEnforcer
+
+
+class NodeExpressAdapter(NodeAdapterBase):
+    name = "node-express"
+    detect_files = ["package.json"]
+    detect_imports = ["express", "fastify", "koa"]
+    priority = 58
+
+    def detect(self, project_root: Path) -> bool:
+        pkg = project_root / "package.json"
+        if not pkg.exists():
+            return False
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return False
+        deps = dict(data.get("dependencies") or {})
+        deps.update(data.get("devDependencies") or {})
+        # `next` and `@nestjs/*` are owned by dedicated adapters - opt out
+        # so polyglot repos don't get this adapter attached twice.
+        if "next" in deps or any(d.startswith("@nestjs/") for d in deps):
+            return False
+        return any(imp in deps for imp in self.detect_imports)
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return []
+
+
+__all__ = ["NodeExpressAdapter"]

hexa_swarm_core/adapters/node_nest.py

@@ -0,0 +1,36 @@
+"""node-nest StackAdapter - NestJS backend services."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from hexa_swarm_core.adapters._node_base import NodeAdapterBase
+from hexa_swarm_core.adapters.protocol import InvariantEnforcer
+
+
+class NodeNestAdapter(NodeAdapterBase):
+    name = "node-nest"
+    detect_files = ["package.json", "nest-cli.json"]
+    detect_imports = ["@nestjs/core", "@nestjs/common"]
+    priority = 68
+
+    def detect(self, project_root: Path) -> bool:
+        if (project_root / "nest-cli.json").exists():
+            return True
+        pkg = project_root / "package.json"
+        if not pkg.exists():
+            return False
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return False
+        deps = dict(data.get("dependencies") or {})
+        deps.update(data.get("devDependencies") or {})
+        return any(d.startswith("@nestjs/") for d in deps)
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return []
+
+
+__all__ = ["NodeNestAdapter"]

hexa_swarm_core/adapters/node_next.py

@@ -0,0 +1,41 @@
+"""node-next StackAdapter - Next.js App Router projects."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from hexa_swarm_core.adapters._node_base import NodeAdapterBase
+from hexa_swarm_core.adapters.protocol import InvariantEnforcer
+
+
+class NodeNextAdapter(NodeAdapterBase):
+    name = "node-next"
+    detect_files = [
+        "package.json",
+        "next.config.ts",
+        "next.config.js",
+        "next.config.mjs",
+    ]
+    detect_imports = ["next"]
+    priority = 70
+
+    def detect(self, project_root: Path) -> bool:
+        if any((project_root / p).exists() for p in ("next.config.ts", "next.config.js", "next.config.mjs")):
+            return True
+        pkg = project_root / "package.json"
+        if not pkg.exists():
+            return False
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return False
+        deps = dict(data.get("dependencies") or {})
+        deps.update(data.get("devDependencies") or {})
+        return "next" in deps
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return []
+
+
+__all__ = ["NodeNextAdapter"]

hexa_swarm_core/adapters/protocol.py

@@ -0,0 +1,66 @@
+"""
+StackAdapter Protocol — the contract every language/framework adapter fulfils.
+
+A polymorphic `quality-gate` / `contract-sync` / `invariants-check` command works
+identically across Python, Node, Go, Rust, etc. — because it dispatches to the
+adapter that matches the current project.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class CommandSpec:
+    """One shell invocation the adapter wants to run."""
+
+    cmd: list[str]
+    cwd: str | None = None  # relative to project root; None = project root
+    env: dict[str, str] | None = None
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class InvariantEnforcer:
+    """A check tied to a safety invariant (S1..S6) that an adapter wants to
+    enforce on this stack. Runs within the quality-gate or a dedicated
+    `invariants` job; failure is merge-blocking.
+    """
+
+    invariant: str  # e.g. "S1", "S3"
+    description: str
+    cmd: list[str]  # shell command; nonzero exit = violation
+
+
+@runtime_checkable
+class StackAdapter(Protocol):
+    """Every adapter implements this. See `BaseAdapter` for a default skeleton."""
+
+    name: str  # e.g. "py-fastapi", "node-next"
+    language: str  # "python", "typescript", "go", ...
+    detect_files: list[str]  # file globs whose presence indicates this stack
+    detect_imports: list[str]  # optional: substrings that must appear in a detect_file
+    priority: int  # higher wins when multiple adapters match
+
+    def detect(self, project_root: Path) -> bool:
+        """Return True if this adapter applies to the given project root."""
+        ...
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]: ...
+
+    def contract_generator(self, project_root: Path) -> CommandSpec | None:
+        """Command that regenerates `.ai-sync/contracts/openapi.yaml` (or None)."""
+        ...
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]: ...
+
+
+__all__ = ["CommandSpec", "InvariantEnforcer", "StackAdapter"]

hexa_swarm_core/adapters/py_celery.py

@@ -0,0 +1,68 @@
+"""py-celery StackAdapter - Celery workers / Airflow / staged Python pipelines."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import CommandSpec, InvariantEnforcer
+
+
+class PyCeleryAdapter(BaseAdapter):
+    name = "py-celery"
+    language = "python"
+    detect_files = [
+        "pyproject.toml",
+        "requirements.txt",
+        "src/backend/pyproject.toml",
+        "src/backend/requirements.txt",
+        "backend/pyproject.toml",
+        "backend/requirements.txt",
+    ]
+    # airflow shares the "staged pipeline" archetype shape; also route to this.
+    detect_imports = ["celery", "apache-airflow", "prefect"]
+    # Below fastapi (70): a FastAPI app with celery workers should still be
+    # identified as py-fastapi primarily, with py-celery as an add-on.
+    priority = 60
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["ruff", "check", "."], description="ruff check")]
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["ruff", "format", "--check", "."], description="ruff format")]
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["mypy", "."], description="mypy")]
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [
+            CommandSpec(
+                ["pytest", "-m", "not slow and not e2e", "-q", "--timeout=60"],
+                description="pytest (pipeline tests)",
+            )
+        ]
+
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]:
+        if (project_root / "requirements.txt").exists():
+            return [
+                CommandSpec(["python", "-m", "pip", "install", "--quiet", "pip-audit"], description="ensure pip-audit"),
+                CommandSpec(["pip-audit", "-r", "requirements.txt"], description="pip-audit"),
+            ]
+        return [
+            CommandSpec(["python", "-m", "pip", "install", "--quiet", "pip-audit"], description="ensure pip-audit"),
+            CommandSpec(["pip-audit"], description="pip-audit (env)"),
+        ]
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        # S3 (idempotency) is critical for pipeline stages - if a stage retries
+        # after a killswitch, it must not double-charge / double-write.
+        return [
+            InvariantEnforcer(
+                invariant="S3",
+                description="Pipeline stages marked @idempotent must pass resume-safety checks",
+                cmd=["pytest", "-m", "invariants and idempotent", "-q"],
+            ),
+        ]
+
+
+__all__ = ["PyCeleryAdapter"]

hexa_swarm_core/adapters/py_click.py

@@ -0,0 +1,75 @@
+"""py-click StackAdapter — Python CLI tools built with Click or Typer."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hexa_swarm_core.adapters.base import BaseAdapter
+from hexa_swarm_core.adapters.protocol import CommandSpec, InvariantEnforcer
+
+
+class PyClickAdapter(BaseAdapter):
+    name = "py-click"
+    language = "python"
+    # CLI-only projects live at the repo root; monorepos may nest backends.
+    # Accept both layouts so a fullstack repo with click under src/backend
+    # still surfaces the adapter (below fastapi's priority, so it only fires
+    # as a fallback or for repos with no fastapi dep).
+    detect_files = [
+        "pyproject.toml",
+        "requirements.txt",
+        "setup.py",
+        "setup.cfg",
+        "src/backend/pyproject.toml",
+        "src/backend/requirements.txt",
+        "backend/pyproject.toml",
+        "backend/requirements.txt",
+    ]
+    detect_imports = ["click", "typer"]  # typer is a click superset
+    # Lower than py-fastapi so fullstack projects that also import click
+    # (e.g. for a `manage.py`) don't steal the adapter slot.
+    priority = 55
+
+    def lint_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["ruff", "check", "."], description="ruff check")]
+
+    def format_check_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["ruff", "format", "--check", "."], description="ruff format")]
+
+    def typecheck_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [CommandSpec(["mypy", "."], description="mypy")]
+
+    def test_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        return [
+            CommandSpec(
+                ["pytest", "-m", "not slow and not e2e", "-q", "--timeout=30"],
+                description="pytest",
+            )
+        ]
+
+    def build_cmd(self, project_root: Path) -> list[CommandSpec]:  # noqa: ARG002
+        # Optional: produce a wheel so distribution smoke is part of the gate.
+        return [CommandSpec(["python", "-m", "pip", "wheel", "--no-deps", "."], description="pip wheel")]
+
+    def dep_audit_cmd(self, project_root: Path) -> list[CommandSpec]:
+        if (project_root / "requirements.txt").exists():
+            return [
+                CommandSpec(["python", "-m", "pip", "install", "--quiet", "pip-audit"], description="ensure pip-audit"),
+                CommandSpec(["pip-audit", "-r", "requirements.txt"], description="pip-audit"),
+            ]
+        return [
+            CommandSpec(["python", "-m", "pip", "install", "--quiet", "pip-audit"], description="ensure pip-audit"),
+            CommandSpec(["pip-audit"], description="pip-audit (env)"),
+        ]
+
+    def invariant_enforcers(self, project_root: Path) -> list[InvariantEnforcer]:  # noqa: ARG002
+        return [
+            InvariantEnforcer(
+                invariant="S2",
+                description="CLI functions marked @deterministic must remain deterministic",
+                cmd=["pytest", "-m", "invariants and deterministic", "-q"],
+            )
+        ]
+
+
+__all__ = ["PyClickAdapter"]