Gate ruleset¶
Every gandalf gate, what it checks, and how it scores. Gates are auto-discovered
from src/gandalf/gates/ — each file exports one or more gate classes. The
scorecard groups gates by the category column below.
Legend¶
- Blocking — a FAIL here reddens the verdict regardless of
fail_on; a broken build or a leaked secret is a hard stop. - Advisory — emits only PASS or WARN, never FAIL (the deterministic tool gates own the red line). All skill/LLM gates are advisory.
- Self-skips — the gate returns nothing to score when the relevant files or
a live target are absent (e.g. no
.sql, no--target), so it never false-fails a repo it doesn't apply to. - Degrades to WARN — LLM/network gates never crash the run; if the endpoint is unreachable they warn instead of failing.
- Fixes — under
--fixthe gate runs its tool in write mode and repairs what it can before scoring; where the tool also reports what the fix is, a PR comment carries it as an applicablesuggestion(see CLI reference).
Select gates per repo in .gandalf.toml: only = [...] (allowlist),
skip = [...] (denylist). Env vars override the file.
Security — SAST, secrets, DAST, fuzz¶
| Gate | Checks | Notes |
|---|---|---|
semgrep |
Pattern-based SAST across languages. | FAIL on any ERROR-severity rule or >5 findings, else WARN. A rule shipping an autofix suggests it on a PR. |
bandit |
Python SAST (common insecure APIs). | |
gitleaks |
Secret scanning (keys, tokens, credentials). | Blocking — a leak is a hard stop. |
codeql |
Semantic SAST; builds a queryable DB, deeper than pattern scanners. | Heavy; needs the CodeQL CLI. |
atheris |
Coverage-guided fuzzing of gandalf's own parsers. | Needs tests/fuzz/fuzz_adapters.py + the atheris package; self-skips otherwise. |
nikto |
Web-server misconfiguration sweep (DAST). | Needs a live --target; local-only, refuses remote hosts. |
sqlmap |
SQL-injection probe (DAST). | Live target only. |
dalfox |
XSS probe (DAST). | Live target only. |
Dependencies — known-vuln scanning¶
| Gate | Checks | Notes |
|---|---|---|
osv |
pip-audit against Python requirements / project files. |
|
osv_scanner |
OSV scan across lockfiles (multi-ecosystem). | |
govulncheck |
Go vulnerability database check. | Go toolchain. |
trivy |
Known-vuln scan of dependencies. | |
bundler_audit |
Ruby advisories against Gemfile.lock. |
bundler-audit; --no-update (the DB is yours to refresh). |
composer_audit |
PHP advisories from Packagist. | Part of Composer — no plugin. |
dotnet_audit |
Vulnerable NuGet packages, transitive included. | Part of the .NET SDK. |
Licensing¶
| Gate | Checks | Notes |
|---|---|---|
licenses |
Forbidden / restricted dependency licenses. | Reads the licences out of the trivy gate's scan rather than walking the tree again; permissive licenses ignored. |
Infrastructure — IaC, containers, CI config¶
| Gate | Checks | Notes |
|---|---|---|
checkov |
IaC misconfiguration (Terraform, k8s, Docker, …). | |
kics |
IaC misconfiguration (Checkmarx); complements checkov/trivy. | Needs its query assets. |
hadolint |
Dockerfile lint. | |
actionlint |
GitHub Actions workflow lint. |
Database — SQL lint + migration safety¶
| Gate | Checks | Notes |
|---|---|---|
sqlfluff |
SQL lint. | Self-skips without .sql; dialect via GANDALF_SQL_DIALECT. Fixes with sqlfluff fix. |
squawk |
Unsafe Postgres DDL (blocking locks, dropped columns, non-concurrent indexes). | Self-skips without .sql. |
Code quality — lint, format, types, dead code¶
| Gate | Checks | Notes |
|---|---|---|
ruff |
Python lint. | Fixes with ruff check --fix; suggests the same edits on a PR. |
format |
ruff format --check — formatting drift (does not rewrite). |
Fixes by rewriting with ruff format. |
mypy |
Python type checking. | |
vulture |
Python dead-code detection. | |
golangci_lint |
Go meta-linter (govet, staticcheck, errcheck, unused, …). | Go toolchain. Fixes with --fix (gofmt, goimports, misspell, …). |
eslint |
JS/TS lint. | Uses the repo's local config/deps. Fixes with eslint --fix; suggests the same edits on a PR. |
tsc |
TypeScript type check. | |
shellcheck |
Shell-script lint. | Fixes by applying its own --format=diff patch; suggests it on a PR. |
yamllint |
YAML lint. | |
checkstyle |
Java style/lint. | The repo's checkstyle.xml when it ships one, else Google style (GANDALF_CHECKSTYLE_CONFIG). |
ktlint |
Kotlin lint. | Fixes with ktlint --format. |
rubocop |
Ruby lint. | Fixes with rubocop --autocorrect (safe corrections only). |
phpcs |
PHP style/lint. | Prefers vendor/bin/phpcs; the repo's ruleset, else PSR-12. Fixes with phpcbf. |
cppcheck |
C/C++ static analysis. | Needs no compile database. |
dotnet_format |
.NET formatting/style drift. | Fixes with dotnet format. |
Complexity¶
| Gate | Checks | Notes |
|---|---|---|
lizard |
Cyclomatic complexity / function length thresholds. | Advisory (capped at WARN). |
Documentation¶
| Gate | Checks | Notes |
|---|---|---|
interrogate |
Python docstring coverage. | WARNs below GANDALF_DOCSTRING_MIN (default 60%); self-skips without Python. |
mdl |
Markdown lint. | Advisory; self-skips without markdown. |
codespell |
Common misspellings in code/docs. | Fixes unambiguous typos with -w; suggests them on a PR. |
Build & tests¶
| Gate | Checks | Notes |
|---|---|---|
build |
Changed Python actually compiles (syntax/parse). | Blocking. |
go_build |
go build ./.... |
Blocking; Go toolchain. |
tests |
Runs the project's pytest suite. | |
go_test |
Runs go test. |
|
node_test |
Runs npm test. |
|
ci_act |
Runs .github/workflows/* locally via act in Docker. |
Self-skips without workflows. |
java_build |
mvn compile / gradle classes. |
Blocking; the wrapper wins over a host gradle. |
java_test |
mvn test / gradle test. |
|
ruby_syntax |
ruby -c over the Ruby in scope. |
Blocking. |
ruby_test |
rspec when there is a spec/, else rake test. |
|
php_syntax |
php -l over the PHP in scope. |
Blocking. |
php_test |
phpunit. | Prefers vendor/bin/phpunit; needs a phpunit.xml. |
cpp_build |
cmake configure + build, into a throwaway directory. |
Advisory, not blocking — see below. |
cpp_test |
ctest in a build tree that already exists. |
Configures nothing of its own. |
dotnet_build |
dotnet build. |
Blocking. |
dotnet_test |
dotnet test. |
cpp_build is the one build gate that does not block. A C++ configure step fails
for a missing system library as readily as for broken code, so a failed
configure is amber (something about this machine) while a failed compile
is red (something about the change). Blocking on the first would fail changes
that build fine in their own CI.
Java and C/C++ have no ecosystem-native dependency audit — Maven and Gradle ship
none, and C/C++ has no standard package manager — so for those two the generic
osv_scanner and trivy gates are the audit: they read pom.xml,
gradle.lockfile and conan/vcpkg locks already.
Best practices¶
| Gate | Checks | Notes |
|---|---|---|
compliance |
LLM judge scoring how fully the change satisfies the request. | Needs a request to judge; degrades to WARN. |
scorecard |
OSSF Scorecard — repo security-posture score (0–10). |
Skill-backed advisory gates¶
These turn a prose reviewing skill (an embedded src/gandalf/assets/<slug>/SKILL.md
playbook) into an LLM-judged gate. They are advisory (PASS/WARN only) and
degrade to WARN when the model is unreachable or the skill isn't embedded. The
skill file is the rubric — edit it and the gate follows.
Each costs a full model round trip, so --no-llm skips them outright (along
with compliance and the report's summary) rather than running them and
reporting amber; they are listed as disabled in the report. That is usually the
largest saving available to an editor or pre-commit run.
| Gate | Skill | Judges |
|---|---|---|
security_assessment |
security-assessment |
CNCF TAG-Security-style posture of the change. |
quality_gate_review |
quality-gate-review |
Six quality gates → GO / REVIEW / NO-GO verdict. |
ruthless_refactor |
ruthless-refactor |
Duplication, dead code, needless indirection, reinvented stdlib. |
pr_code_summary |
pr-code-summarizer |
Tech-lead 60-second read: what changed, risks, questions. |
codebase_architecture |
improve-codebase-architecture (+ codebase-design) |
Shallow modules, leaky abstractions, deepening opportunities. |
grill_me |
grill-me (+ grilling) |
Design readiness — interrogates every branch of a decision. |
well_architected |
well-architected |
The change against the six Well-Architected pillars. |
Skills ship inside the package under
src/gandalf/assets/, read from gandalf's own source tree (not the code under review), so--commit/--stagedruns against a throwaway worktree still find them. A missing skill directory makes the strict skill gates error and the soft ones skip.
Gates are plugins¶
A gate is any class with name: str, blocking: bool, and
async def run(self, ctx) -> GateResult. To add one, drop a .py file
exporting such a class into gandalf/gates/ (or any dir on GANDALF_GATES_PATH) —
it's discovered automatically, no registry to edit. Name collisions let a
plugin override a built-in; the override is announced on stderr, since a
replacement gitleaks is otherwise indistinguishable from the real one in every
output. GANDALF_GATES_PATH imports and executes arbitrary Python — it is a
trust boundary, see
configuration.
# gandalf/gates/mygate.py
from gandalf.base import GateContext, GateOutcome, GateResult
class MyGate:
name = "mygate"
blocking = False
async def run(self, ctx: GateContext) -> GateResult:
return GateResult(self.name, GateOutcome.PASS, 1.0, "all good")
ctx.changed_files is empty in whole-tree mode (scan the repo) and populated in
--staged/--commit mode (scan just those files). ctx.workdir is where to run.
A gate can additionally opt into --fix by exposing
async def fix(self, ctx) -> tuple[bool, str] that applies its autofixes in
place and returns (changed, message). Fixers run sequentially before scoring
(order matters: a lint fix and a reformat touch the same files), and --fix
cascades to the tool itself — ruff --fix, ruff format, eslint --fix,
golangci-lint --fix, cargo clippy --fix, sqlfluff fix, codespell -w,
and shellcheck's own --format=diff patch. ctx.meta["fix"] is True during
such a run, for a gate that wants to run its tool differently under it.
Returning False for changed is safe: the runner measures what each fixer
rewrote from the worktree, which is the only honest answer for the tools that
report nothing (eslint --fix) or exit non-zero on a perfectly successful run
(eslint, golangci-lint).
If the gate's tool can say what the fix is, keep that in the finding — ruff's
fix, shellcheck's fix.replacements and semgrep's extra.fix are read as-is,
and anything else can be normalised into a _fix block (see
gandalf/suggest.py). That is what becomes a one-click ```suggestion on a
pull request.
Language relevance¶
gandalf detects the languages in scope and only runs the gates relevant to them,
plus the language-agnostic ones — so a Go change never triggers eslint or mypy.
Detection is by file extension + marker files (go.mod, package.json,
tsconfig.json, pyproject.toml, pom.xml, Gemfile, composer.json,
CMakeLists.txt, *.csproj, Dockerfile, …): from the changed files in
--staged/--commit mode, or the whole tracked tree by default. Irrelevant
language gates are dropped from the run entirely (listed under "skipped" in the
output and JSON), not just skipped-green.
A gate opts into this by setting a langs class attribute (e.g.
langs = frozenset({"go"})); gates without one are generic and always run. The
tag → language mapping lives in scope.py (_EXT_LANG / _MARKER_LANG).
Built-in gates (63)¶
Each gate needs its external tool — on the host PATH or (for the scanners) in
the gandalf-tools image. When the tool is unavailable, or a dynamic gate has no
--target, or compliance has no --title/--body, the gate degrades to 🟡
WARN — so any repo still produces a full scorecard. Language-tagged gates (the
Python, Go, Node/TS, Java/Kotlin, Ruby, PHP, C/C++ and .NET groups, plus
shellcheck=shell, yamllint=yaml, hadolint=docker) run only when that
language is in scope; everything else is generic and always runs.
Image = host-clean. gandalf-tools provides the language-agnostic scanners
(ruff, semgrep, bandit, pip-audit, osv-scanner, trivy, gitleaks, checkov,
hadolint, scorecard, mypy, vulture, codespell, yamllint, shellcheck, actionlint,
mdl). The
kics gate runs from the official checkmarx/kics image (it ships its own query
assets), and codeql from a host codeql binary or a bundle image
(GANDALF_CODEQL_IMAGE) — the CodeQL CLI is a large bundle, not a pip/apt package,
so it's not baked into gandalf-tools. The Go, Node, Java, Ruby, PHP, C/C++ and
.NET gates use your host toolchain (go, npx, npm, mvn/gradle,
ruby, php/composer, cmake, dotnet) — you already have the ones for the
languages you write — so they're never containerized.
If the image is stale or partial (a tool it claims to provide isn't actually present), the gate degrades to 🟡 WARN — a missing dockerized tool never reads as a clean pass.
Python:
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
build |
yes | — (stdlib) | every Python file compiles (syntax) |
ruff |
no | ruff | lint |
format |
no | ruff format | formatting drift (--check) |
mypy |
no | mypy | static type errors |
bandit |
no | bandit | security lint |
vulture |
no | vulture | dead / unused code |
Cross-language SAST / deps / secrets / IaC:
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
semgrep |
no | semgrep | SAST — python + go + js + ts + owasp + secrets |
codeql |
no | codeql (bundle / own image) | semantic SAST (data-flow/taint) — python, js/ts, go |
gitleaks |
yes | gitleaks | secrets in the tree |
osv |
no | pip-audit | Python dependency vulns |
osv_scanner |
no | osv-scanner | dependency vulns, all ecosystems (go.mod, package-lock, …) |
trivy |
no | trivy | fs vulns + secrets + misconfig + license — the run's one trivy fs, which licenses reads too |
checkov |
no | checkov | IaC misconfig |
kics |
no | checkmarx/kics (own image) | IaC misconfig (Terraform/k8s/Docker/Ansible/…) |
hadolint |
no | hadolint | Dockerfile lint |
scorecard |
no | scorecard | OSSF security-posture score (0–10, local file-based checks) |
Shell / CI / config / prose:
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
shellcheck |
no | shellcheck | shell script bugs (*.sh/*.bash) |
actionlint |
no | actionlint | GitHub Actions workflow lint |
yamllint |
no | yamllint | YAML lint |
codespell |
no | codespell | source/doc typos |
mdl |
no | mdl | Markdown lint (*.md) |
ci_act |
no | act + Docker | runs .github/workflows/* locally |
Database (self-skips without *.sql; dialect via GANDALF_SQL_DIALECT, default ansi):
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
sqlfluff |
no | sqlfluff | SQL lint / style |
squawk |
no | squawk | Postgres migration safety (unsafe DDL, locks, …) |
Go (host toolchain; self-skips without go.mod):
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
go_build |
yes | go | go build ./... compiles |
golangci_lint |
no | golangci-lint | meta-linter (govet, staticcheck, errcheck, unused, …) |
govulncheck |
no | govulncheck | Go vulns (reachability-aware) |
go_test |
no | go | go test ./... |
Node / TypeScript (host toolchain; self-skips without package.json):
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
eslint |
no | npx eslint | JS/TS lint (project-local config) |
tsc |
no | npx tsc | TypeScript type check (needs tsconfig.json) |
node_test |
no | npm test | runs the test script |
Java / Kotlin (host build tool; runs where the manifest is, self-skips without
pom.xml / build.gradle[.kts]):
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
java_build |
yes | mvn / gradle | mvn compile or gradle classes |
checkstyle |
no | checkstyle | Java style/lint (repo ruleset, else Google style) |
ktlint |
no | ktlint | Kotlin lint (*.kt/*.kts only) |
java_test |
no | mvn / gradle | mvn test or gradle test |
Ruby (host toolchain; the lint/test gates want a real project — Gemfile,
*.gemspec, Rakefile or .rubocop.yml — so a stray .rb config file does not
pull them in):
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
ruby_syntax |
yes | ruby | ruby -c over the files in scope |
rubocop |
no | rubocop | lint / style |
bundler_audit |
no | bundle-audit | advisories against Gemfile.lock |
ruby_test |
no | rspec / rake | rspec when there is a spec/, else rake test |
PHP (prefers the project's own vendor/bin/; self-skips without composer.json
or *.php):
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
php_syntax |
yes | php | php -l over the files in scope |
phpcs |
no | phpcs | style/lint (repo ruleset, else PSR-12) |
composer_audit |
no | composer | Packagist advisories for composer.lock |
php_test |
no | phpunit | runs the suite (needs phpunit.xml) |
C / C++ (self-skips without CMakeLists.txt / C sources):
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
cpp_build |
no | cmake + a compiler | configure + build in a throwaway dir |
cppcheck |
no | cppcheck | static analysis, no compile DB needed |
cpp_test |
no | ctest | runs an already-configured build tree's tests |
.NET (all four are the SDK itself; self-skips without a *.sln/*.csproj):
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
dotnet_build |
yes | dotnet | dotnet build compiles |
dotnet_format |
no | dotnet | formatting / style drift |
dotnet_audit |
no | dotnet | vulnerable NuGet packages (transitive too) |
dotnet_test |
no | dotnet | dotnet test |
Tests + compliance + dynamic:
| Gate | Blocking | Tool | Checks |
|---|---|---|---|
tests |
no | pytest | runs the Python test suite |
compliance |
no | LLM (headroom) | does the diff satisfy --title/--body? (≥85% = pass) |
atheris |
no | atheris | coverage-guided fuzzing (needs a harness) |
nikto |
no | nikto + --target |
server misconfig sweep |
sqlmap |
no | sqlmap + --target |
SQL-injection probe |
dalfox |
no | dalfox + --target |
XSS probe |
The dynamic gates (nikto/sqlmap/dalfox) refuse non-localhost targets unless
you pass --allow-remote. golangci-lint/govulncheck aren't in the image
(they need the Go toolchain) — go install them on the host to activate.
Skill-driven review gates (4)¶
These gates have no external tool. Each wraps one reviewing skill — a prose
playbook under src/gandalf/assets/ — and runs
it as an LLM judge against the same headroom endpoint the compliance gate uses.
The skill's SKILL.md becomes the rubric; the model returns a strict JSON
verdict (outcome + score + findings) that maps onto the gate. The skills
are embedded in this repo, so the gates are self-contained and versioned with the
code. Like every LLM gate, each degrades to 🟡 WARN (never crashes the run) when
the endpoint is unreachable — so static-only runs aren't blocked by a missing
model.
| Gate | Blocking | Skill | Judges |
|---|---|---|---|
quality_gate_review |
yes | quality-gate-review |
six weighted quality gates → GO / REVIEW / NO-GO (pass / warn / fail) |
ruthless_refactor |
no | ruthless-refactor |
simplification wins: duplication, dead code, needless indirection, custom-vs-library |
pr_code_summary |
no | pr-code-summarizer |
a technical-lead's 60-second read; warns when complexity/risk is high |
security_assessment |
no | security-assessment |
CNCF TAG Security posture: SBOM, signing, branch protection, disclosure, incident response |
quality_gate_review is the only blocking skill gate — a NO-GO verdict reddens
the run — but a WARN from an unreachable model never does. The skills are read
from gandalf's own source tree (next to the package), not the worktree under
review, so --commit/--staged runs judge against the same rubric. To disable
these gates for a fast, LLM-free run, pass --no-llm — they are not run at all,
and the tool-based gates are unaffected. Pointing GANDALF_LLM_URL at nothing
also works but is slower and noisier: each gate still spends a connect timeout
and its retries before WARNing its way out of the verdict.
Skill-backed advisory gates (3)¶
A second family of skill gates, built on the shared SkillGate base in
gandalf/skillgate.py. Each embeds a skill (under src/gandalf/assets/) verbatim, wraps its
SKILL.md in a non-interactive scoring contract, and maps the model's 0–100
score to RAG. The skill file is the rubric and single source of truth — edit the
skill and the gate follows, exactly like a human running /<skill>.
Unlike the review gates above, these are advisory: they emit only 🟢 PASS or 🟡 WARN, never 🔴 FAIL. LLM judgement is subjective, so they surface friction without hard-blocking a build — the deterministic tool gates own the red line. WARN is also the honest degrade when headroom is unreachable, a skill isn't embedded, or nothing is in scope: never a false pass. All three are generic (run on every change).
| Gate | Category | Embedded skill(s) | Judges |
|---|---|---|---|
grill_me |
Design readiness | grill-me → grilling |
The load-bearing decisions the change leaves unresolved or ambiguous (PASS ≥ 80). |
codebase_architecture |
Architecture | improve-codebase-architecture → codebase-design |
Deep-module health — shallow modules, poor locality, leaky seams, hard-to-test interfaces (PASS ≥ 75). |
well_architected |
Well-Architected | well-architected |
The change against all six Well-Architected pillars, HRIs/MRIs tagged by severity (PASS ≥ 75). |
grill-me and improve-codebase-architecture come from
mattpocock/skills; well-architected is
adapted from AWS's
sample-well-architected-skills-and-steering.
Each is embedded together with the dependency skills it invokes (grilling,
codebase-design), so the gate carries the full rubric offline.