Governance as code: the Gatekeep story

The original version of this article described governance as a markdown checklist. That was embarrassingly underselling what Gatekeep actually is. Let me try again with the full story.

Gatekeep started as a document — a specification of review questions for security, cost, architecture, and deployment decisions. That document is still how the framework is described internally on this platform. But Gatekeep the open-source project is something much more useful: a CLI tool with eight specialist AI personas, two-layer governance model, and YAML-defined policies that you can ship alongside your code.

pipx install gatekeep

# Set your OpenRouter key (one-time)
export OPENROUTER_API_KEY=sk-or-...

# Ask a specialist directly
gatekeep ask sentinel "Should I store this token in an environment variable or SSM?"
gatekeep ask auditor  "What will three Lambda functions at 256MB cost monthly at 1M req?"
gatekeep ask architect "Should I use DynamoDB or RDS for this access pattern?"

# Run a full parallel team review
gatekeep review "New payment API with Stripe integration and webhook handling"

# Gate a deployment
gatekeep deploy "API v2.0" --env production

The eight personas

Each persona has a defined focus, a distinct approach, and uses the model best suited to its domain. They're not all the same model: each is matched to what it's good at.

gatekeep review runs Auditor, Sentinel, and Architect in parallel against the same input and combines their outputs. You get three specialist perspectives in roughly the time it takes to get one.

The two-layer governance model

Most governance tools make you choose: either you configure everything from scratch, or you accept someone else's opinions. Gatekeep separates these concerns cleanly.

Layer 1: your policies. YAML files that capture your organisation's specific rules. What's your monthly budget? What's your secrets storage policy? Which architecture patterns are approved? These live in governance/ in your project after gatekeep init.

# governance/cost-control.yaml
budgets:
  global:
    monthly_limit: 100
    currency: "USD"

# governance/security.yaml
secrets:
  storage:
    aws:
      primary: "SSM Parameter Store SecureString"
  rotation: "90 days minimum"
encryption:
  in_transit: "TLS 1.2+ required"
  at_rest: "Enable for all storage"

The Auditor persona reads your budget YAML and enforces it. When you ask about adding a NAT gateway, it knows your monthly limit and tells you whether that $32/month charge fits or breaks it. Not a generic warning: a specific check against your actual constraint.

Layer 2: external standards. OWASP Top 10, CIS AWS 2.0, GDPR, SOC 2. Built in, no configuration required. Personas automatically cross-reference these when relevant. You don't have to encode OWASP injection rules yourself. Sentinel already knows them.

Setting up in a project

cd my-project
gatekeep init

That's it. gatekeep init scaffolds the full structure:

• governance/: your security, cost, and architecture policies (editable YAML)
• personas/: persona definitions (modify existing or add your own)
• standards/: regulatory standards (OWASP, CIS, GDPR, SOC 2)
• gatekeep.yaml: project configuration

Commit this to your repository and every engineer on the team has the same governance rules available. The policies evolve with the codebase: in the same pull request, with the same review process, with the same history.

What it actually costs

Gatekeep uses your OpenRouter API key. OpenRouter gives you access to multiple AI models with a single key and pay-as-you-go pricing. No subscription. No vendor lock-in. Your data goes through OpenRouter to the model provider, the same path as any direct API call.

Typical costs in practice:

• Individual developer: $1–5/month
• Small team (5 people): $10–25/month

For comparison: AI coding assistant subscriptions run $10/user/month or more ($50+/month for 5 people). Most AI code review tools are $50–200/month for a team. Gatekeep is cheaper because you pay for actual usage, not a seat licence, and you can set OpenRouter spend limits so you know exactly what you'll pay.

Pairing with LoopForge

Gatekeep governs quality: whether each step in your pipeline meets the standards it should. LoopForge governs order: which steps happen, in what sequence, with a complete audit trail. They're designed to work together.

from gatekeep.personas import consult_sync
from loopforge import LoopService, LoopState

def security_gate(record, previous_state, new_state, trigger):
    if new_state == LoopState.MERGED:
        result = consult_sync("sentinel", f"Review PR {record.pr_url}")
        if result.verdict == "block":
            raise TransitionError(f"Sentinel blocked merge: {result.reason}")

def cost_gate(record, previous_state, new_state, trigger):
    if new_state == LoopState.PR_CREATED:
        consult_sync("auditor", f"Cost check for {record.ref}")

service = LoopService(repository=repo, hooks=[security_gate, cost_gate])

In this pattern, Gatekeep personas are called as transition hooks. Every merge gets a Sentinel security check. Every PR creation gets an Auditor cost check. If either blocks, the transition doesn't happen, and that block is recorded in the LoopForge audit trail with the persona's reasoning attached.

MCP integration

Gatekeep personas are also available as MCP tools, which means AI coding agents can invoke governance checks directly as part of their tool calls. When an agent is writing Terraform and wants to check whether a proposed resource is cost-compliant, it calls the Auditor as a tool rather than hoping the model has internalised your budget constraints.

This is the connection between governance and agentic development: governance personas become a structured interface that agents can call reliably, not a prompt that might or might not be followed.

Governance as config: the live rules

The ops agents on this platform are governed by declarative rules that live in the same repository as the code. Originally these ran through Paperclip (a hosted agent orchestrator); in March 2026 the ops layer was migrated to pure Lambda functions triggered by EventBridge. The governance model survived the migration intact. The rules still control which actions are auto-rejected and which need approval:

// governance/rules.json: approval gates and escalation
{
  "approval_gates": [
    {
      "id": "terraform-apply",
      "required_approvers": ["cto"],
      "trigger": "terraform-plan-available",
      "auto_reject_if": [
        "plan contains aws_secretsmanager resource",
        "plan contains aws_nat_gateway resource",
        "plan contains aws_wafv2 resource",
        "plan contains aws_kms_key resource",
        "plan shows > 0 resource destructions without explicit override"
      ]
    },
    {
      "id": "pr-security-review",
      "required_approvers": ["security"],
      "trigger": "pr-opened",
      "applies_to_files": ["terraform/**", "**/*.tf", "**/handler.py", "**/config.py"]
    }
  ],
  "escalation_rules": [
    { "condition": "sre detects critical anomaly", "action": "escalate to cto" },
    { "condition": "cost agent detects > 20% budget overrun", "action": "escalate to cto" }
  ]
}

The CTO Agent definition — now executed as a Lambda function rather than a Paperclip agent, but the same declarative shape:

{
  "id": "cto",
  "schedule": "daily + on-pr-event",
  "goals": [
    "Review Terraform plans for new resources and cost compliance",
    "Enforce governance gates: no deployment proceeds without CTO approval",
    "Review PRs on ticketyboo-dev/ticketyboo.dev for architectural implications"
  ],
  "can_approve": ["deployments", "terraform-changes", "dependency-updates"]
}

The governance file lives in the same repository as the code it governs. It evolves with pull requests. It has a history. That's governance as code.

What the ticketyboo.dev scanner uses

The scanner has two modes. Shallow scan is free, always runs, and requires no API key. Deep scan is opt-in: it downloads source files and runs six analysis layers, each with a 45-second timeout, against the actual code.

Shallow scan

• Dependency manifests: detects requirements.txt, package.json, go.mod, Gemfile; flags missing lockfiles and unpinned versions
• Committed .env files: scans for environment files that should be gitignored
• Missing linting config: no ruff, eslint, mypy, or equivalent
• Terraform lock hygiene: missing .terraform.lock.hcl
• Governance signals: missing CI/CD workflows, README, SECURITY.md, CODEOWNERS, branch protection

Deep scan: six layers

• Dependency vulnerabilities: queries the GitHub Advisory Database (GHSA GraphQL API) for known CVEs in pinned versions. Covers Python (requirements.txt, Pipfile, pyproject.toml), JavaScript (package.json, package-lock.json), Go (go.mod, go.sum), and Ruby (Gemfile, Gemfile.lock).
• Secret detection: regex patterns plus Shannon entropy analysis across 14 file types (.py, .js, .ts, .go, .rb, .java, .yml, .yaml, .json, .toml, .cfg, .ini, .env, .sh, .tf, .hcl). Matched values are redacted in the report before storage.
• SAST (static analysis): Python AST-based checks for command injection (subprocess with shell=True), SQL injection (f-strings inside execute() calls), insecure deserialization (pickle.loads), XSS, path traversal, and weak cryptography (MD5, SHA1). Regex fallback for JavaScript, Go, and Ruby.
• IaC scanning: Terraform parsed with python-hcl2: public S3 buckets, missing server-side encryption, wildcard IAM actions, open security group ingress rules, unencrypted RDS. CloudFormation detected by AWSTemplateFormatVersion key or Resources.*.Type prefix and checked against the same rule set.
• License audit: dependency licenses classified against a permissive/copyleft/unknown allowlist. Flags GPL and AGPL packages in commercial codebases.
• Code quality: Python AST: cyclomatic complexity ≥15, functions ≥100 lines, files ≥500 lines, type hint coverage below 50%, TODO/FIXME count above 5. Samples up to 50 files per repository.

The governance layer (the part that connects to Gatekeep) is one slice of the shallow scan. It catches the structural gaps that no amount of tooling covers if the basics aren't in place. The deep scan goes further: it's where the actual code, infrastructure, and dependencies get examined. Both modes produce findings scored by severity and surfaced in the results dashboard at /scan/.

We test the scanner against well-known "vulnerable by design" public repos: bridgecrewio/terragoat for IaC findings, and trufflesecurity/test_keys for secret detection. Both are purpose-built to trigger real findings, which means when the scanner runs against them, you can see whether it actually catches what it claims to catch.