saturnday 0.3.28

Execution governor for AI-generated code — Guard, Run, and Repair in one package

Saturnday

A runtime governance layer for AI coding agents that improves engineering judgement without retraining the underlying model.

Works with Claude Code, OpenAI Codex, and Cursor in the terminal. Also available as an OpenClaw skill on ClawHub. Model-agnostic — governs the coding process, not just the output.

What it does

Saturnday sits between you and your AI coder. When you say "build this", Saturnday plans the work into governed tickets, executes them through your chosen AI coder, checks every change against 50+ governance rules, repairs failures, and produces evidence. The AI writes the code. Saturnday makes sure it's safe, correct, and reviewable.

Three modes

Guard — Scan and review code for risky patterns.

saturnday governance --repo . --full    # Full repo review (50+ checks)
saturnday governance --repo . --staged  # Check before commit
saturnday scan --skill ./my-skill/ --output ./results  # OpenClaw skill scan

Run — Turn a brief into governed tickets and execute them.

saturnday start                         # Launch your coder with governance
# Then just talk to it: "build a calculator skill"
# Saturnday plans → executes → checks → reports automatically

Repair — Fix governance findings automatically.

saturnday repair --repo . --backend claude-cli   # Repair any repo
saturnday repair --skill . --backend claude-cli  # Repair an OpenClaw skill

Install

pip install saturnday

No configuration required. Everything auto-configures when you run saturnday start.

Quick start

1. Create a project and launch Saturnday

pip install saturnday
mkdir -p ~/projects/my-new-skill
cd ~/projects/my-new-skill
saturnday start

2. Pick your backend

Saturnday detects installed backends and verifies login:

  Which backend do you want to use?

    [1] Codex CLI (OpenAI subscription)  (✓ installed, logged in)
    [2] Claude Code CLI (Anthropic subscription)  (✓ installed, logged in)
    [3] Cursor CLI  (✗ not set up)
    [4] OpenAI API (API key)  (✗ OPENAI_API_KEY not set)
    [5] Anthropic API (API key)  (✗ ANTHROPIC_API_KEY not set)

  Select [1-5]: 2

3. Tell it what to build

Just talk naturally. For example:

Build an OpenClaw skill called repo-risk-summary that scans a local
repository, detects obvious risky patterns such as secrets, shell
execution, missing tests, placeholder code, and hallucinated imports,
then writes a Markdown summary report with findings, severity, and
suggested fixes. It must support a dry-run mode, never modify the
target repo, include clear usage instructions in SKILL.md, and
include tests.

Saturnday will plan the work into governed tickets, execute them through your chosen AI coder, check every change, and produce a full evidence trail. You just watch and review.

4. Scan and repair existing code

Already have a project? Saturnday can scan and fix it:

cd ~/projects/existing-project
saturnday start

Then say: scan and repair this repo

What it checks (50+ governance rules)

AI-specific defects:

• Hallucinated imports — packages that don't exist on npm or PyPI
• Fake tests — assert True, empty test bodies, tautological assertions
• Placeholder code — TODO stubs, pass-only functions, NotImplementedError bodies
• API version mismatches — calling methods that don't exist in the installed library version
• Dead code — functions defined but never referenced in any project file

Security (19 SEC- checks):*

• Leaked secrets, hardcoded JWT, weak randomness
• Auth bypass, CSRF, XSS, SQL injection, IDOR
• Cookie security, token revocation, OAuth flow integrity
• Rate limiting, websocket auth, security event logging
• Frontend secret exposure, payment provider secrets

Code quality:

• Ruff linting, Bandit security analysis
• Missing type hints, deprecated API usage
• Dependency declaration and version pinning
• README, LICENSE, and project setup validation
• Python version compatibility
• Test execution (runs your tests during governance)
• Doc-code consistency (README matches actual code behaviour)

Repository coherence:

• Project runnable check (package.json for TS, pyproject.toml for Python)
• README language consistency (catches "pip install" in TypeScript projects)
• Blast radius check (flags over-engineering)

How saturnday start works

When you run saturnday start, Saturnday:

1. Detects your backend — Claude Code, Codex, or Cursor CLI (with real login verification)
2. Installs governance — pre-commit hook, CLAUDE.md/AGENTS.md rules, Claude Code hooks
3. Launches your coder — you talk to it naturally, it follows Saturnday rules

When you ask it to build something:

1. Plans — generates design-decision-rich tickets in batches (3-stage planner)
2. Splits — micro-ticketer breaks large tickets into governed pieces (max 40 lines each)
3. Executes — each ticket coded, governance-checked, and committed individually
4. Retries — failed tickets get governance findings fed back and retry (up to 3 attempts)
5. Commits ungoverned if needed — if a ticket still fails governance after retries and auto-repair, the code is committed with a [GOVERNANCE: review required] tag so the project stays complete
6. Auto-repairs — after all tickets, remaining failures and ungoverned tickets go through the repair pipeline
7. Simplifies — a simplifier pass removes unnecessary complexity
8. Reviews — 4 role passes evaluate the result (repo analyst, governance judge, definition of done, evidence gate)
9. Reports — full governance report, run report, review-required.md for ungoverned tickets, and copy-paste fix prompts for each ungoverned ticket

Every commit is blocked by the pre-commit hook if it fails governance. The AI can write code however it wants — it can't commit anything unsafe.

What governance catches in practice

Fake secrets in test files: Governance caught realistic-looking API keys in test fixtures and blocked the commit until they were rewritten as obviously non-live test values. A plain AI coder would ship those. Saturnday stopped it.

Missing project setup: A TypeScript project was built without package.json or tsconfig.json. The governance check flagged it, the repair pipeline created both files automatically.

Stale documentation: After converting a project from Python to TypeScript, the README still said "pip install". The doc-code consistency check caught the mismatch.

Dead code across modules: A detector function was defined in one file but never imported anywhere in the project. The cross-file dead code check found it.

Senior engineering standards

Saturnday includes 30 senior engineering rules that shape how the AI writes code:

• Comments must explain WHY, never WHAT
• Tests must be distributed unevenly — more for risky logic, fewer for trivial code
• Trade-off decisions must be visible in the code
• No dead code, no template language, no over-polished READMEs
• Every project must be runnable from a clean checkout
• Justify what you chose NOT to do

These rules are loaded into the coder's system prompt and enforced by governance checks and the definition of done evaluation.

Project mode

When you run saturnday start, it asks:

Project mode:
  [1] Strict  (all checks block commits)
  [2] Relaxed (skip README/LICENSE/project config checks)
Select [1-2]:

Relaxed mode creates a .saturnday-policy.yaml that exempts publish-readiness checks. Useful for private repos and early development. Delete the file when you're ready for strict mode.

Policy configuration

Create a .saturnday-policy.yaml in your repo root to exempt expected findings:

expected_findings:
  - remote_download    # This is a web crawler — downloading is its job
  - broad_filesystem   # File organiser needs filesystem access
  - blast_radius       # New project, expected

GitHub Action

name: Saturnday Governance
on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  pull-requests: write

jobs:
  governance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - uses: honouralexwill/saturnday/.github/actions/saturnday-check@3c3273362249d5df24fb386ed3a4efdb582ce1d0  # pin to SHA

Evidence and reports

Every scan, repair, and run produces timestamped evidence in the project directory:

.saturnday/evidence/review_20260323T.../governance-report.md
.saturnday-repair-20260323T.../repair-report.md
.saturnday-{project}/run-report.md

Reports include: findings by category, diff analysis (files touched, lines changed, new imports), role pass results, and action items.

How it's different

Saturnday is not a linter, not a scanner, not a prompt wrapper. It governs the coding process itself:

• Before coding: repo analyst understands the codebase, planner generates design-decision-rich tickets
• During coding: pre-commit hook blocks unsafe commits, Claude Code hooks remind the coder to read before editing
• After coding: simplifier removes unnecessary complexity, governance re-scan verifies the result, role passes evaluate quality

The goal is not to make AI code look human. The goal is to make AI code that a strong staff engineer would approve with minimal comments.

What Saturnday installs (and what it doesn't touch)

Saturnday only creates per-project files. It never modifies your global Claude Code or Codex settings.

When you run saturnday start in a project folder, it creates:

File	What it does	Scope
.claude/settings.json	Adds PreToolUse/PostToolUse hooks (Claude Code only)	This project only
CLAUDE.md or AGENTS.md	Governance rules for the coder	This project only
.git/hooks/pre-commit	Blocks commits that fail governance	This project only
bin/sat-*	Command wrappers (Codex only)	This project only
.saturnday/	Evidence, reports, session state	This project only

What it does NOT touch:

• Your global ~/.claude/settings.json — untouched
• Your global Claude Code configuration — untouched
• Your existing hooks — Saturnday ADDS alongside them, never overwrites
• Your existing CLAUDE.md — Saturnday appends governance rules, preserves your content
• Any other project on your machine — completely isolated

If you have existing Claude Code hooks, sequential thinking, agents, or custom configurations — they all keep working. Saturnday adds governance on top, it doesn't replace anything.

Removing Saturnday from a project

To completely remove Saturnday governance from a project:

rm -rf .claude/settings.json CLAUDE.md AGENTS.md bin/sat-* .saturnday* .git/hooks/pre-commit

That's it. Your project goes back to ungoverned mode. No residual settings, no global changes to undo.

To keep the code but stop governance on future commits, just remove the pre-commit hook:

rm .git/hooks/pre-commit

OpenClaw Skill

Saturnday is available as an OpenClaw skill on ClawHub:

clawhub install saturnday

This gives your OpenClaw agent access to all three modes — scan, guard, and run. The agent reads the SKILL.md and knows when and how to call each mode.

Requires pip install saturnday on the machine running OpenClaw.

Trade-offs

• Governance adds time to every commit (typically 5-30 seconds for the pre-commit check)
• The planner and ticket execution are slower than direct AI coding (minutes vs seconds) but produce governed, evidence-tracked results
• Some governance checks produce false positives on specialised code (e.g. security scanners that legitimately handle secret patterns) — use .saturnday-policy.yaml to exempt these

Limitations

• Governance checks are deterministic (regex, AST, external tools) — they catch patterns, not intent
• Doc-code consistency checks use LLM role passes which are advisory, not deterministic
• The simplifier pass suggests changes but the AI may not always follow through
• Codex CLI has no native hooks system — governance relies on AGENTS.md, command wrappers, and pre-commit hooks

Non-goals

• Making AI code indistinguishable from human code — that's a losing game
• Replacing human code review — Saturnday augments review, doesn't replace it
• Supporting every IDE and editor — Saturnday is terminal-first by design

License

MIT — Waynestark Enterprises Limited