finefettle 1.12.0

The assurance layer for agentic software engineering

One policy across agents, workspaces, delegation, verification, and CI.

Quick start · Why Fettle · Why it is different · Capabilities · Documentation

fettle (v.) — a foundry term for trimming and cleaning a rough casting.

AI coding agents changed the unit of software work. A change is no longer just a diff: it is a chain of prompts, tool calls, delegated workers, tests, exceptions, and remote verdicts. Traditional quality tools inspect pieces of that chain. Fettle governs the chain itself.

It gives agents useful feedback while code and intent are still in the same conversation, carries policy into delegated work, and preserves independent evidence for the moment trust actually matters.

intent -> authority -> action -> evidence -> independent verification
                    Fettle assurance boundary

Fettle does not replace tests, review, CI, an orchestrator, or a sandbox. It connects them into a fail-visible control loop, records decision provenance without collecting hidden reasoning, and refuses to turn missing or malformed evidence into a clean result.

See The Loop

The checked-in two-minute assurance loop contains the violating and repaired fixtures, complete transcript, reset path, and an automated drift test. The visual is a summary; the executable example is authoritative.

Start in Two Minutes

Choose the smallest path that proves value for your job.

Evaluate the CLI

One package installs the complete toolkit — analyzers, test and mutation runners, hooks, browser automation, and the mutation engine:

pipx install "finefettle[all]"   # or: pip install "finefettle[all]"
cd your-project
fettle init --profile solo   # presets: solo | team | enterprise
fettle doctor
fettle check --changed

Presets generate an advisory-first .fettle.toml non-interactively — solo for individual repos, team adds delegation gates, enterprise adds strict mode and compliance evidence. Omit --profile for the guided interview.

The PyPI package is finefettle; the installed command is fettle. Installation does not modify agent settings. fettle init --dry-run previews repository and host changes, and fettle init applies them explicitly.

Add Live Agent Governance

The wheel includes a versioned installed-package bridge for Claude Code, Codex CLI, Gemini CLI, and OpenCode. Preview every repository and host mutation before applying it:

cd your-project
fettle init --dry-run
fettle init
fettle doctor

fettle init detects the four hosts, preserves unrelated host settings, creates an advisory-first project configuration, and installs guided workflows. Claude Code, Codex CLI, and OpenCode have current installed-host evidence. Gemini CLI's installed transport is contract-tested, but its live OAuth verification is blocked upstream by UNSUPPORTED_CLIENT.

fettle init --interactive
fettle init --install-tools

Close the Evidence Loop

After local evaluation or agent setup:

fettle verify                 # run tests; bind source, policy, scope, and runner evidence
fettle ci wait                # bind the pushed revision to remote CI
fettle explain                # inspect the latest decision and recovery path

The Problem Fettle Solves

Repository-bound quality controls are essential, but they often respond after the generation loop has moved on. Fettle adds an earlier control point without weakening the later ones.

This matters most when an agent works across files, languages, or delegated workers. Quality is not only a lint result; it is also whether policy survived delegation, tests were independently run, evidence is fresh, and tool failure was reported honestly.

What Makes Fettle Different

Most developer tools answer one question: “is this file valid?” Fettle answers a larger set: “was this agent authorized, did policy survive delegation, did the right checks actually run, is the evidence still applicable, and what should the developer do next?”

One Policy Across Four Agent Hosts

Claude Code, Codex CLI, Gemini CLI, and OpenCode events normalize into one dispatcher and one .fettle.toml policy. Host transports differ, but gate logic does not need to be rewritten for every agent.

Evidence Never Becomes Clean by Accident

Fettle distinguishes pass, violation, tool_error, unknown, and surface-specific non-applicable outcomes. Missing analyzers, malformed output, timeouts, and zero mutation evidence cannot manufacture a pass.

Policy Survives Delegation

An agent launched through fettle spawn receives a digest-checked policy capsule and lineage identity. Child policy may tighten but cannot loosen the inherited boundary. Claims and worktrees coordinate ownership; role authority can separate test authorship from implementation. These are application-level controls, not operating-system isolation.

Workspace-Aware Polyglot Routing

Nested Python, JavaScript/TypeScript, Go, and Rust workspaces are discovered from native project markers. Edits route to the most specific workspace and its repository-native tools. Python currently has the richest CLI and editor surface; the capability map states the boundaries explicitly.

Verification Is Bound to the Change

Verification writes a canonical local artifact alongside the legacy stamp. It binds test results to the exact source snapshot, effective policy, selected workspace/test scope, Fettle producer implementation, and execution occurrence. The Stop gate recomputes those bindings and rejects missing, stale, malformed, tampered, incomplete, or mismatched claimed artifacts with fettle verify as the recovery command. Legacy-only stamps remain accepted during migration. Remote CI remains an independent authority bound to the pushed commit; local verification evidence does not substitute for it or become an attestation.

Mutation Testing Produces Evidence, Not Theater

Python mutation preflight canonicalizes the engine corpus before expensive execution. Full runs can resume by stable fingerprint, reject incompatible checkpoints, and aggregate only complete ledgers. On pull requests, a required mutation evidence check fans out bounded shards, automatically replays any shard that timed out or lost its runner, and — as of v1.12 — blocks merges when changed-scope survivors go unaddressed: missing, conflicting, or stale evidence fails closed with the offending shard named. Two independent calibrations established Fettle's own 28,723-mutant baseline with zero untested outcomes. Use the mutation quality playbook for setup, the validation funnel, exit semantics, cache isolation, and recovery.

Rules Learn From Real Failures, With Human Control

fettle learn drafts a rule from an incident or trace signature into quarantine. A human reviews and promotes it; evidence and false-positive data drive later ratcheting. The model may propose policy, but it cannot silently activate it.

One Python Install, Strong Release Evidence

The default package includes Fettle's Python analyzers, test and mutation runners, commit-hook support, evaluation parser, and browser-automation library. Releases use PyPI Trusted Publishing, GitHub build provenance attestations, pinned workflow actions, and a CycloneDX SBOM.

Acceptance Is Tested From the User's Side

Living specifications connect requirements and Given/When/Then scenarios to tests. Agentic UAT can exercise CLI, API, web, or library surfaces in an isolated worktree and reports CONFIRMED, CONTRADICTED, BLOCKED, UNOBSERVED, or INDETERMINATE; silence is never counted as success.

Capability Map

Support is described by surface, not by one broad "polyglot" claim.

Quality and Security Gates

• Ruff and bundled Semgrep checks with actionable locations and rerun commands.
• Destructive-command, protected-config, MCP package-trust, secret, boundary, dependency, and deployment checks.
• Plan, TDD ordering, complexity, coverage, BDD, worklog, claims, verification, and remote-CI gates.
• Per-check budgets and advisory-first defaults so teams can measure signal before enabling enforcement.

Mutation Evidence

fettle mutation preflight --all --json
fettle mutation run --changed --json
fettle mutation status --report mutation-report.json --json
fettle mutation baseline check report-a.json report-b.json \
  --run-id RUN_A --run-id RUN_B --floor 70 --json

Mutation testing is Python-only, requires pinned mutmut==2.5.1, and defaults off. Full runs are scheduled/manual held-out verification; start with preflight and changed-scope advisory evidence. See the mutation policy contract.

Evidence and Operations

fettle config --explain       # effective value and provenance for each key
fettle explain                # recent gate decisions and recovery context
fettle verify                 # run tests and bind a verification stamp
fettle ci status              # remote CI verdict for the current commit
fettle report --days 7        # effectiveness and lineage evidence
fettle report --compliance    # CWE, OWASP ASVS, and SOC 2 control evidence
fettle ratchet status         # evidence for promotion or demotion

Multi-Agent Work

fettle plan start --title "Add export" --item "Write contract test"
fettle topology advise
fettle spawn claude --role tester --task "Write the failing tests"
fettle work claim export-tests
fettle brief --json

Role-based authorship separation is available, while broader end-to-end graduation evidence remains in progress. Start advisory and validate your agent runner before enforcing it.

Specifications and User Acceptance

fettle spec lint
fettle spec coverage
fettle uat doctor
fettle uat manual

Specifications remain plain Markdown in Git. UAT automation requires explicit consent; manual walkthroughs remain available when an agent or browser cannot run.

Guided Workflows

fettle workflows list
fettle workflows install

The 17 bundled workflows cover quality review, PR review, security review, threat modeling, deployment readiness, plans, worklogs, incident learning, MCP approval, baselines, explanations, reports, and lean-debt tracking.

Configuration

Start with advisory defaults and promote one gate at a time:

[gates.lint]
enabled = true
mode = "advisory"

[gates.tdd]
enabled = false
mode = "advisory"

[gates.verify]
enabled = false
mode = "advisory"
scope = "impacted"

Policy resolves through built-in defaults, org and team packs, digest-pinned central policy, repository and directory configuration, environment overrides, and a tighten-only delegation capsule. Inspect the final value and source with:

fettle config --validate
fettle config --explain

See the configuration reference for the complete contract.

Operational Boundaries

• Python 3.11 or newer is required.
• Agent transports can run from the v1.11.0 wheel or a source checkout. Installed bridges are versioned and digest-checked; rerun fettle init after upgrades.
• Browser engines require an explicit playwright install. Agent CLIs, Git, shellcheck, and JavaScript/TypeScript, Go, and Rust toolchains remain external.
• Hooks favor session continuity and visible degradation; CI is the independent fail-closed boundary.
• Shell mediation, capsules, worktrees, and role gates are defense in depth, not a sandbox or substitute for least privilege.
• Formal models cover selected high-risk protocols, not the whole product.

Documentation

Contributing

Contributions are welcome. Fettle expects focused changes, explicit failure states, clean and violating fixtures, and verification proportional to risk. See CONTRIBUTING.md and the good first issue backlog.

License

MIT (c) Milind