{% extends "layout.html" %} {% block content %}

{# ── Hero ─────────────────────────────────────────────────────────────── #} {# ── What's inside ─────────────────────────────────────────────────────── #}

What's Inside

1. Detection rules

{{ validation_rule_groups | map(attribute='rules') | map('length') | sum }} deterministic checks across performance, storage, dead code, and SQL cleanup. Each finds an expensive pattern in your dbt project or BigQuery workload and cites the evidence it used (job metrics, manifest AST, INFORMATION_SCHEMA).

2. Safety layers

Every proposed fix runs through sqlglot AST validation, a dbt compile in an isolated uv-venv, a BigQuery dry-run for byte/cost deltas, and (optionally) a shadow build against an isolated dataset before a PR is opened or a commit is made.

{# ── Analysis surfaces ────────────────────────────────────────────────── #} {% if analysis_surfaces %}

Analysis Surfaces

{% for surface in analysis_surfaces %}

{{ surface.title }}

{{ surface.description }}

{% endfor %}

{% endif %} {# ── Rule catalog ─────────────────────────────────────────────────────── #}

Detection Rule Catalog

Rules run automatically after every sync. Each finding includes an evidence snapshot, a quantified savings estimate with confidence, and a safety classification.

{% for group in validation_rule_groups %}

{{ group.title }}

{% for surface_summary in group.analysis_surface_summaries %} {{ surface_summary.title }} · {{ surface_summary.count }} {% endfor %}

{{ group.description }}

{% for rule in group.rules %} {# ── Rule ── #} {# ── Fix ── #} {# ── Cost Estimation ── #} {# ── Impact ── #} {% endfor %}

Rule Fix Cost Estimation Impact

{{ rule.display_name }} {{ rule.analysis_surface_title }} {% if rule.enabled %} On {% else %} Off {% endif %}

{{ rule.description }}

{{ rule.analysis_surface_description }}

{% if rule.template_coverages %} {% for cov in rule.template_coverages %}

Template {{ cov.template_id }}

{{ cov.summary }}

{% endfor %} {% else %}

LLM

AI-generated, then AST-validated.

{% endif %}

{{ rule.cost_method }}

{% if rule.cost_detail %}

{{ rule.cost_detail }}

{% endif %}

{{ rule.impact_label }}

{{ rule.impact_detail }}

{% endfor %}

{# ── Safety layers ────────────────────────────────────────────────────── #}

Safety Layers

Every proposed fix passes through these checks, in order, before it's offered to you. Each solution carries a trust tier derived from which checks passed.

Layer	What it checks	Trust tier on pass
AST validation sqlglot	Parses the before/after SQL into abstract syntax trees and diffs them. A change that only touches `config()` blocks or adds `partition_by` / `cluster_by` is proven to preserve query semantics.	guaranteed_safe
dbt compile uv-venv subprocess	Reconstructs the dbt project from your synced manifest, overlays the proposed change, and runs `dbt parse` + `dbt compile` in an isolated virtual environment pinned to your dbt-core version.	validated
BigQuery dry-run INFORMATION_SCHEMA	Submits the compiled SQL to BigQuery in dry-run mode, captures `total_bytes_processed` and `estimated_cost_usd`, and shows you the delta against the baseline. No data is read or written.	—
Shadow validation isolated dataset	Builds the proposed model and every downstream dependent into an isolated dataset suffixed `__governor_<id>`, compares row counts, bytes-processed, and slot-ms against the baseline. Never writes to production.	validated

{# ── How it runs (mode-specific) ──────────────────────────────────────── #}

How It Runs

{% if is_local_mode %} {# CLI local mode — runs against a dbt project on your laptop #}

Local CLI

Runs against a single dbt project on your workstation. No BigQuery INFORMATION_SCHEMA.JOBS calls — detection reads target/manifest.json and target/run_results.json directly from disk after dbt build. Fixes are either committed to your local git tree or surfaced in this UI for review. No schedule, no background worker, no PR flow — this is a developer tool, not a platform.

Quickstart

## Install the CLI (once)
uv tool install governor-cli

## Initialise against the local dbt project
cd path/to/your/dbt-project
governor init

## Build the dbt project so manifest + run_results exist
dbt build

## Open the local UI
governor start

Typical loop

Make a change in your dbt project, run dbt build.
governor detect — or reload the browser — to see new findings.
Open a finding, review its generated fix in this UI.
Apply locally: the fix is written to your working tree and a git commit is made. No PR.

{% else %} {# Cloud mode — scheduled, multi-project, PR-driven #}

Cloud

Runs on a schedule across every configured dbt project. Syncs pull manifest.json from GCS and query metadata from BigQuery INFORMATION_SCHEMA.JOBS. Detection runs in a background worker; results surface on the dashboard, are graded by trust tier, and can be submitted as GitHub pull requests — automatically for guaranteed_safe fixes, with review for the rest. Post-merge, verified savings are collected from BigQuery and attributed back to the originating opportunity.

Example project configuration

## /admin/configurations — new project
name: Analytics
manifest_source: gcs
bucket_name: my-dbt-manifests
path_prefix: analytics/
object_name: manifest.json
github_repo: acme/analytics-dbt
schedule_type: cron
schedule_value: "0 * * * *"     ## hourly sync
auto_pr_trust_tier: guaranteed_safe
min_solution_cost_usd: 10
allowed_solution_policy_tags:
  - partition
  - cluster
  - config_only
watched_rule_types:
  - shuffle_spill
  - join_explosion
  - partition_pruning
  - storage_billing_optimization

Typical loop

Scheduler fires a sync — manifest + BigQuery job history ingested.
Detection worker evaluates all enabled rules against the new data.
Solution generator produces a fix; safety layers classify it.
If the trust tier meets the project threshold, a PR opens on GitHub automatically.
After merge, cost is verified for 14 days and surfaced as verified savings.

{% endif %}

{# ── Impact Scale Legend ──────────────────────────────────────────────── #}

Impact Scoring

Every finding carries a severity score from 1–100, derived from estimated savings, adjusted by confidence, with a small boost for recurring issues.

1–20 Low (<$10) 21–50 Moderate ($10–$100) 51–80 High ($100–$1K) 81–100 Critical ($1K+)

Adjustment: base score × max(0.5, confidence), then +5 if the same finding has recurred.

{% endblock %}