Metadata-Version: 2.1
Name: archsteer
Version: 0.2.0
Summary: Living Architecture Control Plane for the AI-Dev Era
Author-email: ArchSteer <founders@archsteer.io>
License: MIT
Project-URL: Homepage, https://www.archsteer.com
Project-URL: Documentation, https://www.archsteer.com/get-started
Project-URL: Source, https://github.com/einvoice-dev1/archsteer
Project-URL: Issues, https://github.com/einvoice-dev1/archsteer/issues
Project-URL: Changelog, https://www.archsteer.com/blog
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer >=0.12.0
Requires-Dist: pydantic >=2.7.0
Requires-Dist: ruamel.yaml >=0.18.0
Requires-Dist: jinja2 >=3.1.0
Requires-Dist: rich >=13.7.0
Provides-Extra: dev
Requires-Dist: pytest >=8.0.0 ; extra == 'dev'
Requires-Dist: black >=24.0.0 ; extra == 'dev'
Requires-Dist: isort >=5.13.0 ; extra == 'dev'
Provides-Extra: treesitter
Requires-Dist: tree-sitter <0.22.0,>=0.21.0 ; extra == 'treesitter'
Requires-Dist: tree-sitter-languages >=1.10.0 ; extra == 'treesitter'

# ArchSteer

**Living Architecture Control Plane for the AI-Dev Era.**

AI agents now write code faster than any architect can review, document, or govern it.
Docs rot instantly, the *real* architecture is invisible, structural decisions get made
silently, and intended architecture drifts with every edit. ArchSteer is the always-current
architecture **system of record + governance plane**: it derives the real architecture from
code, keeps living docs and ADRs auto-built, surfaces every major decision for the architect
to ratify, enforces declared intent as code-level fitness functions, and steers AI agents to
conform instead of replicating local slop.

Everything is a projection of one code-derived model — `.archsteer/model.json`.

```
                    .archsteer/model.json  (single source of truth)
                                 │
   MAP ──── DOCUMENT ──── GOVERN ──── STEER ──── EVOLVE
  model    living docs   fitness     agent     report.html
  from     + auto ADRs   functions   guardrails  (drift/
  source   + diagrams    + ratchet   + (MCP)     decisions)
```

## Install

```bash
pip install archsteer                 # regex engine, zero native deps
pip install "archsteer[treesitter]"   # optional native acceleration
```

## Quickstart

```bash
archsteer init      # scaffold .archsteer/ + seed intent (Express → Next.js + repository)
archsteer map       # build model.json from source
archsteer docs      # regenerate .archsteer/architecture.md (deterministic, Mermaid)
archsteer govern    # conformance + drift score by rule
archsteer adr       # draft ADRs for new structural decisions (architect-in-the-loop)
archsteer baseline  # accept current debt — the ratchet
archsteer steer -f src/controllers/payment.js -t "add refund endpoint"
archsteer check     # CI/pre-commit: fail on NET-NEW violations only
archsteer report    # self-contained .archsteer/report.html
```

## The three design guarantees

1. **Ratchet, not freeze.** `archsteer check` blocks only *net-new* violations against a
   baseline — teams keep shipping features while debt can only shrink.
2. **Conservative, architect-in-the-loop ADRs.** Only external-boundary changes (new
   dependency, new datastore, new layer) draft an ADR — never internal reshuffles, never
   auto-committed.
3. **Sharp agent steering.** Guardrails injected into `CLAUDE.md` / `AGENTS.md` are scoped to
   the files in play and point at the governing ADR — they don't dump the whole model into the
   context window.

## Declaring intent — `.archsteer/architecture.yaml`

```yaml
target: "Migrate Express + raw SQL to Next.js route handlers + the repository pattern"
layers: [route, controller, service, repository, model]
rules:
  - id: no-raw-sql-outside-repository
    type: required_layer_for_data_access
    allowed_layers: [repository]
    operations: [RAW]
    severity: error
    adr: .archsteer/adr/0001-repository-pattern.md
    steer: "Wrap all queries in a repository under src/repositories/. No raw SQL elsewhere."
```

Rule types: `required_layer_for_data_access`, `forbidden_import`, `forbidden_data_access`,
`forbidden_layer_edge`.

## CI / pre-commit

- GitHub Action: `.github/workflows/archsteer.yml` (maps, drafts ADRs, runs the net-new gate,
  uploads `report.html`).
- Git hook: `cp hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit`.

## Try the demo

```bash
cd examples/demo-repo
archsteer init && archsteer map && archsteer report   # open .archsteer/report.html
```

## Roadmap

- **Phase 2** — cloud control plane (Next.js + Supabase): multi-repo situation room with
  drift/decision time-series.
- **Phase 3** — `archsteer mcp`: an MCP server so agents query the live model + intent mid-edit.
- **Phase 4** — auth, org/repo model, billing.

## Development

```bash
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q
```
