Metadata-Version: 2.4
Name: saturnday
Version: 0.3.13
Summary: Execution governor for AI-generated code — Guard, Run, and Repair in one package
License-Expression: MIT
Project-URL: Homepage, https://github.com/honouralexwill/saturnday
Project-URL: Repository, https://github.com/honouralexwill/saturnday
Keywords: ai,governance,security,code-review,llm,run,repair,autonomous-delivery
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Security
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Saturnday

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

Works with **Claude Code** and **OpenAI Codex** in the terminal. 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.
```bash
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.
```bash
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.
```bash
saturnday repair --repo . --backend claude-cli   # Repair any repo
saturnday repair --skill . --backend claude-cli  # Repair an OpenClaw skill
```

## Install

```bash
pip install saturnday
```

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

## Quick start

### 1. Create a project and launch Saturnday

```bash
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] OpenAI API (API key)  (✗ OPENAI_API_KEY not set)
    [4] Anthropic API (API key)  (✗ ANTHROPIC_API_KEY not set)

  Select [1-4]: 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:

```bash
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 or Codex 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. **Auto-repairs** — after all tickets, remaining failures go through the repair pipeline
6. **Simplifies** — a simplifier pass removes unnecessary complexity
7. **Reviews** — 4 role passes evaluate the result (repo analyst, governance judge, definition of done, evidence gate)
8. **Reports** — full governance report, run report, and evidence trail generated

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.

## Policy configuration

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

```yaml
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

```yaml
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@master
```

## 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:

```bash
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:

```bash
rm .git/hooks/pre-commit
```

## 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
