Metadata-Version: 2.4
Name: agent-maintainer
Version: 0.1.0b4
Summary: Repository maintenance checks and diagnostics for AI-assisted Python development.
Author: Doug Monsky
License-Expression: MIT
Project-URL: Homepage, https://github.com/douglasmonsky/agent-maintainer
Project-URL: Repository, https://github.com/douglasmonsky/agent-maintainer
Project-URL: Issues, https://github.com/douglasmonsky/agent-maintainer/issues
Project-URL: Documentation, https://github.com/douglasmonsky/agent-maintainer#readme
Keywords: ai,coding-agents,maintainability,ci,python,code-quality,developer-tools
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: core
Requires-Dist: bandit; extra == "core"
Requires-Dist: coverage; extra == "core"
Requires-Dist: defusedxml; extra == "core"
Requires-Dist: deptry; extra == "core"
Requires-Dist: diff-cover; extra == "core"
Requires-Dist: import-linter; extra == "core"
Requires-Dist: pre-commit; extra == "core"
Requires-Dist: pylint; extra == "core"
Requires-Dist: pyright; extra == "core"
Requires-Dist: pytest; extra == "core"
Requires-Dist: pytest-cov; extra == "core"
Requires-Dist: radon; extra == "core"
Requires-Dist: ruff; extra == "core"
Requires-Dist: tach; extra == "core"
Requires-Dist: vulture; extra == "core"
Requires-Dist: xenon; extra == "core"
Provides-Extra: agent
Requires-Dist: bandit; extra == "agent"
Requires-Dist: coverage; extra == "agent"
Requires-Dist: defusedxml; extra == "agent"
Requires-Dist: deptry; extra == "agent"
Requires-Dist: diff-cover; extra == "agent"
Requires-Dist: import-linter; extra == "agent"
Requires-Dist: pre-commit; extra == "agent"
Requires-Dist: pylint; extra == "agent"
Requires-Dist: pyright; extra == "agent"
Requires-Dist: pytest; extra == "agent"
Requires-Dist: pytest-cov; extra == "agent"
Requires-Dist: radon; extra == "agent"
Requires-Dist: ruff; extra == "agent"
Requires-Dist: tach; extra == "agent"
Requires-Dist: vulture; extra == "agent"
Requires-Dist: xenon; extra == "agent"
Provides-Extra: hardening
Requires-Dist: bandit; extra == "hardening"
Requires-Dist: coverage; extra == "hardening"
Requires-Dist: defusedxml; extra == "hardening"
Requires-Dist: deptry; extra == "hardening"
Requires-Dist: diff-cover; extra == "hardening"
Requires-Dist: import-linter; extra == "hardening"
Requires-Dist: pre-commit; extra == "hardening"
Requires-Dist: pylint; extra == "hardening"
Requires-Dist: pyright; extra == "hardening"
Requires-Dist: pytest; extra == "hardening"
Requires-Dist: pytest-cov; extra == "hardening"
Requires-Dist: radon; extra == "hardening"
Requires-Dist: ruff; extra == "hardening"
Requires-Dist: tach; extra == "hardening"
Requires-Dist: vulture; extra == "hardening"
Requires-Dist: xenon; extra == "hardening"
Requires-Dist: actionlint-py; extra == "hardening"
Requires-Dist: check-jsonschema; extra == "hardening"
Requires-Dist: interrogate; extra == "hardening"
Requires-Dist: pip-audit; extra == "hardening"
Requires-Dist: wemake-python-styleguide; extra == "hardening"
Requires-Dist: yamllint; extra == "hardening"
Requires-Dist: zizmor; extra == "hardening"
Provides-Extra: manual
Requires-Dist: cyclonedx-bom; extra == "manual"
Requires-Dist: mutmut; extra == "manual"
Requires-Dist: pip-licenses; extra == "manual"
Requires-Dist: semgrep; python_version < "3.13" and extra == "manual"
Provides-Extra: compression
Requires-Dist: headroom-ai; extra == "compression"
Provides-Extra: all
Requires-Dist: actionlint-py; extra == "all"
Requires-Dist: bandit; extra == "all"
Requires-Dist: check-jsonschema; extra == "all"
Requires-Dist: coverage; extra == "all"
Requires-Dist: cyclonedx-bom; extra == "all"
Requires-Dist: defusedxml; extra == "all"
Requires-Dist: deptry; extra == "all"
Requires-Dist: diff-cover; extra == "all"
Requires-Dist: import-linter; extra == "all"
Requires-Dist: interrogate; extra == "all"
Requires-Dist: mutmut; extra == "all"
Requires-Dist: pip-audit; extra == "all"
Requires-Dist: pip-licenses; extra == "all"
Requires-Dist: pre-commit; extra == "all"
Requires-Dist: pylint; extra == "all"
Requires-Dist: pyright; extra == "all"
Requires-Dist: pytest; extra == "all"
Requires-Dist: pytest-cov; extra == "all"
Requires-Dist: radon; extra == "all"
Requires-Dist: ruff; extra == "all"
Requires-Dist: semgrep; python_version < "3.13" and extra == "all"
Requires-Dist: tach; extra == "all"
Requires-Dist: vulture; extra == "all"
Requires-Dist: wemake-python-styleguide; extra == "all"
Requires-Dist: xenon; extra == "all"
Requires-Dist: yamllint; extra == "all"
Requires-Dist: zizmor; extra == "all"
Dynamic: license-file

# Agent Maintainer

[![CI](https://github.com/douglasmonsky/agent-maintainer/actions/workflows/verify.yml/badge.svg)](https://github.com/douglasmonsky/agent-maintainer/actions/workflows/verify.yml)
[![PyPI](https://img.shields.io/pypi/v/agent-maintainer.svg)](https://pypi.org/project/agent-maintainer/)
![Python 3.10-3.14](https://img.shields.io/badge/python-3.10--3.14-blue)
[![License: MIT](https://img.shields.io/pypi/l/agent-maintainer.svg)](LICENSE)

Maintainability checks and repair-loop diagnostics for AI-assisted Python
repositories.

> Agent Maintainer is in beta. The core workflow is usable, but starter files
> and defaults may change as it is tested across more Python repository layouts.

<p align="center">
  <img src="docs/assets/graphics/agent-maintainer-overview.png" alt="Agent Maintainer workflow: an agent edits code, hooks run checks, rules and budgets are enforced, diagnostics guide repair, and CI verifies final state." width="900">
</p>

Agent Maintainer helps Python repositories stay maintainable under AI-assisted
development. It combines low-noise verification, change budgets, suppression
controls, coverage gates, type checks, architecture checks, security checks, and
structured diagnostics into one workflow for humans and coding agents.

## What This Is

Agent Maintainer is a repository maintenance control layer for AI-assisted code
changes. It checks whether changes are small enough to review, test-backed,
type-checked, covered, diagnosable, and aligned with repo structure.

## What This Is Not

Agent Maintainer is not a runtime AI safety system. It does not moderate model
outputs, filter prompts, block jailbreaks, or validate chatbot responses. It is
also not a prompt/output moderation framework. Agent Maintainer focuses on
repository health during AI-assisted software development.

## Quick Start

Install the core toolset:

```bash
python -m pip install "agent-maintainer[core]"
```

Initialize a repository:

```bash
agent-maintainer init --track core --preset existing-app
```

Merge `config/pyproject.agent-maintainer.toml` into your `pyproject.toml`, tune
paths for your repo, then check setup health:

```bash
agent-maintainer doctor
agent-maintainer verify --profile precommit
```

## First Successful Run

Healthy setup output should be quiet:

```text
PASS
```

`doctor` prints one compact `PASS`, `WARN`, or `FAIL` row per setup check. If
verification fails, inspect generated diagnostics before changing thresholds or
suppressions:

```bash
cat .verify-logs/LAST_FAILURE.md
```

The failure note includes failed checks, relevant artifact paths, and an exact
rerun command.

The console command is convenient for local use. Committed automation should use
the module entrypoint because it works reliably in editable local-source
contexts:

```bash
python3 -m agent_maintainer verify --profile precommit
```

## Adoption Tracks

`init` writes starter files for three adoption levels:

| Track | Use When | Writes |
|---|---|---|
| `core` | You want the minimum useful maintenance loop. | Starter config, `config/dev-dependencies.txt`, pre-commit config, CI workflow. |
| `agent` | Coding agents actively edit the repo. | Core files plus `AGENTS.md`, Codex hooks, and Claude Code hooks. |
| `hardening` | You want docs/config hygiene and security-adjacent surfaces. | Agent files plus Node-backed tooling metadata. |

Preview writes before changing a repo:

```bash
python3 -m agent_maintainer init --track agent --dry-run
```

Existing files are not overwritten unless `--force` is passed.

## Policy Presets

`--track` chooses which files are written. `--preset` tunes the starter policy in
`config/pyproject.agent-maintainer.toml`:

| Preset | Use When |
|---|---|
| `small-library` | A compact Python package can start with tighter budgets. |
| `existing-app` | An existing app needs useful defaults without immediate strict-mode friction. |
| `ai-agent-heavy` | Coding agents will frequently change code and source-without-test changes should fail. |
| `legacy-ratchet` | Existing debt should improve by baseline and ranked repair targets. |
| `strict-new-repo` | A clean new repo can start with strict budgets and wemake enabled. |

Example:

```bash
python3 -m agent_maintainer init --track agent --preset ai-agent-heavy
```

## Common Commands

```bash
python3 -m agent_maintainer bootstrap
python3 -m agent_maintainer doctor --strict
python3 -m agent_maintainer guidance
python3 -m agent_maintainer guidance --check
python3 -m agent_maintainer verify --profile fast
python3 -m agent_maintainer verify --profile precommit
python3 -m agent_maintainer verify --profile full
python3 -m agent_maintainer verify --profile ci
python3 -m agent_maintainer verify --profile security
python3 -m agent_maintainer verify --profile manual
python3 -m agent_maintainer report html
python3 -m agent_maintainer hooks status all
python3 -m agent_maintainer hooks install all --dry-run
python3 -m agent_maintainer hooks install claude-code --scope user
python3 -m agent_maintainer ratchet status
python3 -m agent_maintainer ratchet next
python3 -m archguard tach-config --strict-root-module
python3 -m archguard decision-check --base-ref HEAD
```

Profiles are intentionally stable:

| Profile | Purpose |
|---|---|
| `fast` | Hook-friendly checks after edits. |
| `precommit` | Local completion gate. |
| `full` | Deeper review gate before larger merges. |
| `ci` | GitHub Actions gate. |
| `security` | Security-oriented scan profile. |
| `manual` | Slow opt-in tools such as mutation testing and Semgrep. |

## What The Tool Checks

| Concern | Enforcement |
|---|---|
| Oversized Python files | `agent_maintainer.checks.file_lengths` |
| Huge or diffuse changes | `agent_maintainer.checks.change_budget` |
| Broad suppressions | `agent_maintainer.checks.suppression_budget` |
| Required repo layout | Verifier layout checks |
| Style and simple defects | Ruff |
| Type discipline | Pyright |
| Test coverage | Pytest, pytest-cov, coverage, diff-cover |
| Complexity | Radon reports and Xenon gate |
| Architecture boundaries and policy governance | Tach or Import Linter; Archguard for Tach policy-change decisions |
| Dependency hygiene | deptry |
| Dead code | vulture |
| Security checks | Bandit, pip-audit, Gitleaks, Semgrep when enabled |
| Supply-chain artifacts | CycloneDX Python SBOM and pip-licenses when enabled |
| GitHub Actions checks | actionlint and zizmor when workflows exist |
| Docs/config hygiene | markdownlint-cli2, yamllint, Taplo, check-jsonschema when enabled |
| Agent feedback | `AGENTS.agent-maintainer.md` and `.verify-logs` diagnostics |

## Configuration

Configuration lives in `pyproject.toml`:

```toml
[tool.agent_maintainer]
mode = "custom"
architecture_tool = "import-linter"
source_roots = ["src"]
test_roots = ["tests"]
package_paths = ["src"]
coverage_source = ["src"]
require_tests = true
coverage_fail_under = 80
diff_cover_fail_under = 90

[tool.agent_maintainer.diagnostics]
enabled = true
log_dir = ".verify-logs"
```

`mode = "fresh-strict"` is for new repositories that can block strict checks on
day one. `mode = "legacy-ratchet"` is for existing repositories where heavier
gates should remain opt-in while changed-code discipline ramps up. This
repository self-enforces stricter settings than the starter template, including
90 percent total coverage.

Environment overrides use the `AGENT_MAINTAINER_*` prefix:

```bash
AGENT_MAINTAINER_SOURCE_ROOTS=src,tests python3 -m agent_maintainer doctor
```

## Agent Guidance

The generated sidecar gives coding agents current repo policy without copying
long instructions into every prompt:

```bash
python3 -m agent_maintainer guidance
python3 -m agent_maintainer guidance --check
```

This writes `AGENTS.agent-maintainer.md` from `[tool.agent_maintainer]`. Update
configuration first, then regenerate the sidecar.

## Optional Tooling

Install extras by adoption level:

```bash
python -m pip install "agent-maintainer[core]"
python -m pip install "agent-maintainer[hardening]"
python -m pip install "agent-maintainer[manual]"
python -m pip install "agent-maintainer[all]"
```

Node-backed tools such as `markdownlint-cli2` and Taplo are managed through
`package.json` when a repo opts into the hardening track:

```bash
npm ci
```

## Install From Source

For local development on Agent Maintainer itself, clone the repository and run:

```bash
python -m pip install -e ".[core]"
agent-maintainer --help
```

Normal downstream repositories should use the package-first init flow rather
than copying `src/agent_maintainer` into application source trees.

## Local Development

For this repo:

```bash
PYTHONPATH=src python3 -m agent_maintainer bootstrap
PYTHONPATH=src python3 -m agent_maintainer doctor --strict
PYTHONPATH=src python3 -m agent_maintainer verify --profile precommit
PYTHONPATH=src python3 -m agent_maintainer verify --profile full
```

Refresh the pinned dev lock after changing `config/dev-dependencies.txt`:

```bash
PYTHONPATH=src python3 -m agent_maintainer bootstrap
.venv/bin/python -m pip freeze --exclude-editable | sort > config/dev-lock.txt
```

## Further Reading

- [MIT License](LICENSE)
- [Changelog](CHANGELOG.md)
- [Roadmap](docs/ROADMAP.md)
- [Context safety](docs/context-safety.md)
- [Test intelligence](docs/test-intelligence.md)
- [Ratcheting](docs/ratcheting.md)
- [Cohesive change plans](docs/cohesive-change-plans.md)
- [Context compression](docs/context-compression.md)
- [Tool map](docs/tool-map.md)
- [First run walkthrough](docs/onboarding-first-run.md)
- [Fresh-strict mode](docs/fresh-strict.md)
- [Legacy-ratchet mode](docs/legacy-ratchet.md)
- [Agent client hooks](docs/agent-client-hooks.md)
- [Cohesive-change overrides](docs/cohesive-change-overrides.md)
- [Release checklist](docs/release-checklist.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Structure cohesion](docs/structure-cohesion.md)

Example starter projects:

- [Fresh-strict example](examples/fresh-strict)
- [Legacy-ratchet example](examples/legacy-ratchet)
- [Context-safe ratchet proof example](examples/context-safe-ratchet)
- [Cohesive change-plan proof example](examples/cohesive-change-plan)
- [Test-intelligence proof example](examples/test-intelligence)
