finefettle 1.13.1

The open-source trust layer for AI coding agents

Catch mistakes while the agent still has context. Prove what passed before the change ships.

Quick start · Why Fettle · Install · Capabilities · Docs

pipx install finefettle
fettle demo

One command installs Fettle's complete Python-backed toolkit: Ruff, Semgrep, pytest, mutmut, PyYAML, Playwright's Python library, bundled rules, workflows, schemas, demo fixtures, and agent-host bridges. No API key, hosted control plane, or repository is needed for the demo. Python 3.11+ and Git are prerequisites.

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

Why Fettle

AI coding agents changed the unit of software work. It is no longer only a diff; it is a chain of authority, edits, delegated workers, tests, exceptions, and remote verdicts. Most tools inspect one link after the agent has moved on. Fettle governs the chain while preserving CI as the independent boundary.

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

Fettle is unusual because these controls live in one local, inspectable system:

Fettle does not replace tests, code review, CI, an agent orchestrator, or a sandbox. It connects them into a control loop and makes unsupported trust visible.

Try It in Two Minutes

pipx install finefettle
fettle demo

The deterministic offline demo introduces a broad exception handler, detects it, applies the repair, and independently reruns four tests:

[1/4] VIOLATION INTRODUCED  demo_project/calculator.py:4
[2/4] VIOLATION DETECTED    broad-except-no-reraise
[3/4] REPAIR APPLIED        Exception -> ValueError
[4/4] REPAIR VERIFIED       Re-ran check: clean; re-ran tests: 4 passed

The checked-in assurance loop contains the fixtures, complete transcript, reset path, and drift test.

To use Fettle in a repository:

cd your-project
fettle init --dry-run
fettle init --profile solo       # solo | team | enterprise
fettle doctor
fettle check --changed
fettle verify
fettle assurance

fettle init --dry-run shows every proposed change. fettle doctor reports which capabilities are available or degraded. Start advisory; enforce only after you have measured signal and tested recovery in your own workflow.

One Package, the Complete Python Toolkit

The PyPI project is finefettle; the installed command is fettle.

pipx install finefettle
# or
uv tool install finefettle

The default wheel declares and installs every Python runtime Fettle invokes and contains its runtime resources. Release CI installs the exact wheel with both pip and pipx, runs the demo outside the checkout, verifies bundled resources and executables, rebuilds from the source distribution, generates a CycloneDX SBOM, and publishes provenance attestations.

A Python package cannot safely embed system-owned runtimes. Install Git first; add browser binaries (playwright install), agent CLIs, language toolchains, or external services only for the surfaces you use. fettle doctor reports these boundaries rather than pretending an unavailable capability passed. See the installation guide.

The Trust Loop

1. Observe early. Hooks normalize agent events and route changed files to configured checks.
2. Return actionable findings. The agent sees location, reason, and recovery while its working context is intact.
3. Verify independently. fettle verify runs repository tests and binds the result to the exact source and policy.
4. Assess the whole change. fettle assurance evaluates nine dimensions and explains every pass, failure, and unknown.
5. Retain evidence. Canonical artifacts, remote CI, mutation reports, UAT, and the governance ledger preserve what actually happened.

Assurance Record c04c9a206c05 · PARTIAL · commit 25f4957
  PASS     behavior
  PASS     provenance
  UNKNOWN  security      raw review is not canonical evidence
  UNKNOWN  independence  no retained role-bound authorship decisions

Missing evidence does not become success. Failed assessment or persistence also invalidates an older assurance record so stale approval cannot look current.

Capabilities

See the detailed capability matrix and task-oriented documentation.

Built for Real Failure Modes

Fettle distinguishes pass, violation, tool_error, unknown, and explicit non-applicable states. Its regression suite pins adversarial cases including forged verification stamps, deleted canonical references, stale CI evidence, tampered policy capsules, crashed analyzers, unsafe agent-runner flags, and incomplete mutation shards.

Selected high-risk protocols also have TLA+ models. Releases use PyPI Trusted Publishing, SHA-pinned GitHub Actions, build provenance attestations, public-wheel canaries, and an attached SBOM.

Common Journeys

Add Agent Governance

fettle init --profile team
fettle doctor
fettle workflows list
fettle explain

Coordinate Delegated 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 brief --json

Build Trust Evidence

fettle verify
fettle ci status
fettle mutation preflight --all --json
fettle assurance
fettle ledger status

Connect Requirements to Outcomes

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

Honest Boundaries

• Hooks optimize feedback speed; protected CI remains the independent authority.
• Capsules, claims, shell mediation, and role gates are not a security sandbox.
• Python has the richest analyzer, mutation, and editor support.
• Browser engines, agent CLIs, external services, and non-Python toolchains are intentionally not bundled into the Python environment.
• Graph intelligence is advisory. UAT and stronger assurance policies graduate only from retained evidence and explicit operator decisions.
• Fettle records decisions and observable evidence, not hidden chain-of-thought.

Documentation

Contributing

Contributions are welcome. Fettle favors focused changes, explicit failure states, clean and violating fixtures, and verification proportional to risk. Start with CONTRIBUTING.md or a good first issue.

License

Fettle v1.12.1 and later are licensed under the Apache License 2.0. Earlier releases retain their published MIT license. See TRADEMARK.md for permitted use of the Fettle name and logos.