Metadata-Version: 2.4
Name: archdrift
Version: 0.1.0
Summary: Architecture contract for AI coding agents: a curated, human-edited ARCHITECTURE.md with drift detection in CI.
Project-URL: Homepage, https://github.com/EvertDeveloper/archdrift
Project-URL: Issues, https://github.com/EvertDeveloper/archdrift/issues
Author: Everton Godoi
License: MIT
License-File: LICENSE
Keywords: agents-md,ai-agents,architecture,claude-code,context-engineering,cursor,documentation,drift-detection
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# archdrift

**Architecture contract for AI coding agents.** A curated `ARCHITECTURE.md` that agents read, humans edit, and CI enforces — so your architecture docs never rot.

[![CI](https://github.com/SEU_USUARIO/archdrift/actions/workflows/ci.yml/badge.svg)](https://github.com/SEU_USUARIO/archdrift/actions)
[![PyPI](https://img.shields.io/pypi/v/archdrift)](https://pypi.org/project/archdrift/)
![Python](https://img.shields.io/badge/python-3.9%2B-blue)
![Zero deps](https://img.shields.io/badge/dependencies-0-brightgreen)

---

## The problem

Tools like Repomix and CodeGraph are **descriptive**: they read your code and tell agents what exists. But no tool captures what your architecture is *supposed* to be — the intent behind it. So agents guess, `ARCHITECTURE.md` files rot within weeks, and nobody notices until an agent (or a new dev) builds on top of stale assumptions.

## The idea

`archdrift` makes your `ARCHITECTURE.md` **normative**:

1. **Generated map** — folder tree, detected stack, responsibilities table. Curated for token efficiency: code files listed, assets collapsed.
2. **Human curation that survives** — edit any description in the responsibilities table, add ADRs and notes anywhere outside the managed sections. Regeneration **never** destroys your edits.
3. **Drift detection in CI** — `archdrift check` exits 1 when reality diverges from the documented contract. The doc can't rot, because rot breaks the build.

```
┌─────────────┐   generate    ┌─────────────────┐   read    ┌────────────┐
│  Filesystem │ ────────────▶ │ ARCHITECTURE.md │ ────────▶ │  AI agent  │
└─────────────┘               │  (you curate)   │           └────────────┘
       ▲                      └─────────────────┘
       │                               │ check (CI)
       └───────── drift? exit 1 ◀──────┘
```

## Quick start

```bash
uvx archdrift .          # or: pipx run archdrift .
```

This generates `ARCHITECTURE.md` (the contract) and `structure.json` (the graph, for tooling). Folders without a known role get marked `_(preencher)_` — fill them in, they're preserved forever.

Then enforce it in CI:

```yaml
# .github/workflows/ci.yml
- name: Architecture drift check
  run: uvx archdrift check .
```

Now every PR that adds an undocumented folder, deletes a documented one, or changes structure without regenerating the map **fails the build** until someone updates the contract.

## How merging works

Managed sections are delimited by markers:

```markdown
<!-- map:begin tree -->
...regenerated by the tool...
<!-- map:end tree -->

## ADR-001                      ← yours, never touched

<!-- map:begin contract -->
| Folder | Responsibility |
| `src/models` | Prisma entities — NEVER import from controllers |  ← your edit, preserved
<!-- map:end contract -->
```

Priority for each folder's description: **your edit** > name-based heuristic > pending placeholder.

## Why not just use a repo packer / knowledge graph?

Use both. Repomix, CodeGraph, aider's repo-map are excellent at telling agents *what the code is*. `archdrift` covers the piece they can't infer: *what the architecture is meant to be* — and keeps that promise honest via CI. It's `dependency-cruiser` energy, rethought for the agent era, in a single zero-dependency Python file.

## Roadmap

- [x] Managed sections + merge (human curation survives regeneration)
- [x] `check` mode — drift detection with meaningful exit codes for CI
- [x] Stack detection, token-efficient tree (type-aware truncation)
- [ ] `AGENTS.md` integration (pointer section into the emerging convention)
- [ ] Declarative rules (`src/controllers must-not-import src/repositories`)
- [ ] MCP server mode
- [ ] Semantic graph: declared dependencies vs. real imports — the diff is the product

## Development

```bash
pip install -e ".[dev]"
pytest -v
```

MIT licensed. Issues and PRs welcome.
