Metadata-Version: 2.4
Name: finefettle
Version: 1.10.0
Summary: Assurance and evidence for AI coding agents across Claude Code, Codex CLI, Gemini CLI, and OpenCode
Author: Milind
License-Expression: MIT
Project-URL: Repository, https://github.com/MilindGaharwar/fettle
Project-URL: Documentation, https://github.com/MilindGaharwar/fettle/tree/main/docs
Project-URL: Changelog, https://github.com/MilindGaharwar/fettle/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/MilindGaharwar/fettle/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Provides-Extra: semgrep
Requires-Dist: semgrep>=1.50; extra == "semgrep"
Provides-Extra: evals
Requires-Dist: pyyaml>=6.0; extra == "evals"
Provides-Extra: uat
Requires-Dist: playwright>=1.40; extra == "uat"
Provides-Extra: all
Requires-Dist: semgrep>=1.50; extra == "all"
Requires-Dist: ruff>=0.4.0; extra == "all"
Requires-Dist: pyyaml>=6.0; extra == "all"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/MilindGaharwar/fettle/main/assets/wordmark-dark.svg">
    <img src="https://raw.githubusercontent.com/MilindGaharwar/fettle/main/assets/wordmark-light.svg" alt="Fettle" height="160">
  </picture>
</p>

<h3 align="center">The assurance layer for agentic software engineering</h3>

<p align="center"><b>One policy across agents, workspaces, delegation, verification, and CI.</b></p>

<p align="center">
  <a href="https://pypi.org/project/finefettle/"><img src="https://img.shields.io/pypi/v/finefettle?label=PyPI&color=brightgreen" alt="PyPI"></a>
  <a href="https://github.com/MilindGaharwar/fettle/actions/workflows/ci.yml"><img src="https://github.com/MilindGaharwar/fettle/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/finefettle/"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT license"></a>
</p>

<p align="center">
  <a href="#start-in-two-minutes">Quick start</a> ·
  <a href="#the-problem-fettle-solves">Why Fettle</a> ·
  <a href="#what-makes-fettle-different">Why it is different</a> ·
  <a href="#capability-map">Capabilities</a> ·
  <a href="docs/README.md">Documentation</a>
</p>

> **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.

```text
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.

| Built for the agentic change loop | Current, reproducible scope |
|---|---|
| Agent hosts | Claude Code, Codex CLI, Gemini CLI, OpenCode |
| Workspace routing | Python, JavaScript/TypeScript, Go, Rust |
| Independent evidence | Tests, remote CI, mutation reports, UAT, compliance and lineage reports |
| Delegation controls | Policy capsules, worktrees, claims, roles, topology, completion reports |
| Runtime footprint | Python 3.11+, zero package runtime dependencies |

## Start in Two Minutes

Choose the smallest path that proves value for your job.

### Evaluate the CLI

Use the zero-runtime-dependency wheel for local scans, CI, reports, and policy
inspection:

```bash
pipx install finefettle
cd your-project
fettle check --changed
fettle doctor
```

The PyPI package is `finefettle`; the installed command is `fettle`.
This path does not modify agent settings.

### Add Live Agent Governance

Agent transports currently run from a Git checkout because host hook assets are
not part of the wheel:

```bash
git clone https://github.com/MilindGaharwar/fettle ~/projects/fettle
cd ~/projects/fettle
python3 fettle/cli.py init --install-tools
fettle doctor
```

`fettle init` detects Claude Code, Codex CLI, Gemini CLI, and OpenCode, preserves
unrelated host settings, creates an advisory-first project configuration, and
installs guided workflows. Use `--dry-run` to inspect changes first.

```bash
python3 fettle/cli.py init --dry-run
python3 fettle/cli.py init --interactive
```

### Close the Evidence Loop

After local evaluation or agent setup:

```bash
fettle verify                 # run affected tests and bind a fresh stamp
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.

| Control point | What it is good at | Fettle's role |
|---|---|---|
| Editor and linter | Immediate local feedback | Reuse analyzers from agent events |
| Commit hook | Protecting repository transitions | Catch selected issues before they accumulate |
| CI and review | Independent, reproducible evidence | Remain the fail-closed authority |
| Agent session | Intent and context are still available | Return findings and recovery steps in-session |

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](#capability-map) states the boundaries explicitly.

### Verification Is Bound to the Change

Verification stamps bind test results to session, revision, and dirty-tree
identity. Remote CI stamps bind a pushed commit to its GitHub Actions verdict.
Stale, foreign, malformed, or unavailable evidence remains visibly unverified.

### 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. Two independent calibrations
established Fettle's own 28,723-mutant baseline with zero untested outcomes.
Changed-scope survivor enforcement remains advisory until runtime and reviewer
feedback satisfy the published graduation criteria.

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

### Small Runtime, Strong Release Evidence

The core package has no runtime dependencies. External analyzers remain
explicit and user-controlled. 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.

| Surface | Current scope |
|---|---|
| Agent lifecycle | Claude Code, Codex CLI, Gemini CLI, OpenCode |
| Post-edit workspace adapters | Python, JavaScript/TypeScript, Go, Rust |
| `fettle check` | Python Ruff and bundled Semgrep rules |
| `fettle verify` | Affected discovered workspaces; Python can narrow to impacted tests |
| LSP / VS Code | Python diagnostics |
| External integrations | SonarQube, Black Duck/Polaris, Pact; opt-in |
| Guided workflows | 17 quality, security, planning, learning, and readiness workflows |
| Multi-agent controls | Worktrees, claims, topology, spawn, capsules, role authority, reports |
| Living specifications | Spec lint, scenario inventory, scenario-to-test trace coverage |
| User acceptance | Agent-driven or manual CLI, API, web, and library scenarios; report-only |
| Mutation quality | Python preflight, changed/full runs, retained reports, canonical baseline comparison |
| Assurance | Canonical result states, behavioral evals, compliance/lineage reports, TLA+ models for selected protocols |

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

```bash
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](docs/CONFIG.md#mutation-evidence-mutation).

### Evidence and Operations

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

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

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

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

```toml
[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:

```bash
fettle config --validate
fettle config --explain
```

See the [configuration reference](docs/CONFIG.md) for the complete contract.

## Operational Boundaries

- Python 3.11 or newer is required.
- Agent transports currently require a repository checkout; CLI workflows,
  rules, and templates ship in the wheel.
- External analyzers and language toolchains must be installed when their
  checks are enabled.
- 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

| Goal | Guide |
|---|---|
| Choose an adoption path | [Documentation index](docs/README.md) |
| Configure gates and policy | [Configuration](docs/CONFIG.md) |
| Connect OpenCode | [OpenCode integration](docs/OPENCODE.md) |
| Use VS Code diagnostics | [VS Code integration](integrations/vscode/README.md) |
| Run behavioral evaluations | [Evaluation lab](evals/README.md) |
| Establish mutation evidence | [Mutation configuration](docs/CONFIG.md#mutation-evidence-mutation) |
| Understand evidence artifacts | [Evidence artifact contract](docs/evidence-artifact-contract.md) |
| Understand current and planned work | [Roadmap](docs/ROADMAP.md) |
| Review release history | [Changelog](CHANGELOG.md) |
| Contribute | [Contributing](CONTRIBUTING.md) |
| Report a vulnerability | [Security](SECURITY.md) |

## Contributing

Contributions are welcome. Fettle expects focused changes, explicit failure
states, clean and violating fixtures, and verification proportional to risk.
See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT (c) Milind
