archsteer 0.1.0__tar.gz

archsteer-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: archsteer
+Version: 0.1.0
+Summary: Living Architecture Control Plane for the AI-Dev Era
+Author-email: ArchSteer <founders@archsteer.io>
+License: MIT
+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
+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: treesitter
+Requires-Dist: tree-sitter<0.22.0,>=0.21.0; extra == "treesitter"
+Requires-Dist: tree-sitter-languages>=1.10.0; extra == "treesitter"
+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"
+
+# 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
+```

archsteer-0.1.0/README.md

@@ -0,0 +1,100 @@
+# 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
+```

archsteer-0.1.0/archsteer/__init__.py

@@ -0,0 +1,7 @@
+"""ArchSteer — Living Architecture Control Plane for the AI-Dev Era.
+
+One code-derived model (``model.json``) powers every pillar:
+MAP, DOCUMENT, GOVERN, STEER, EVOLVE.
+"""
+
+__version__ = "0.1.0"

archsteer-0.1.0/archsteer/cli.py

@@ -0,0 +1,383 @@
+"""ArchSteer CLI — every command is a projection of the one shared model.
+
+    archsteer init     scaffold .archsteer/ + seed intent
+    archsteer map      build model.json from source
+    archsteer docs     regenerate living architecture.md
+    archsteer adr      detect structural decisions -> draft ADRs
+    archsteer govern   show conformance / drift
+    archsteer baseline snapshot accepted violations (the ratchet)
+    archsteer check    fail on NET-NEW violations only (CI / pre-commit)
+    archsteer steer    write agent guardrails into CLAUDE.md / AGENTS.md
+    archsteer report   build the self-contained report.html
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from archsteer import __version__
+from archsteer.docs import render_architecture_md
+from archsteer.engine.baseline import Baseline
+from archsteer.engine.conformance import ConformanceReport, evaluate
+from archsteer.engine.decisions import DecisionEngine
+from archsteer.engine.evolution import History, compute_feed
+from archsteer.engine.intent import Intent
+from archsteer.engine.mapper import build_model
+from archsteer.engine.model import ArchitectureModel
+from archsteer.report import render_report_html
+from archsteer.steer import AgentSteeringEngine
+from archsteer.workspace import Workspace
+
+app = typer.Typer(add_completion=False, help="ArchSteer — Living Architecture Control Plane.")
+console = Console()
+PACK_DIR = Path(__file__).parent / "packs" / "express_to_next"
+
+
+def _ws(path: Optional[str]) -> Workspace:
+    return Workspace(Path(path or "."))
+
+
+def _require_init(ws: Workspace) -> None:
+    if not ws.initialized:
+        console.print("[red]Not initialized.[/red] Run [bold]archsteer init[/bold] first.")
+        raise typer.Exit(1)
+
+
+def _load_model(ws: Workspace) -> ArchitectureModel:
+    model = ArchitectureModel.load_if_exists(ws.model)
+    if model is None:
+        console.print("[yellow]No model found — run [bold]archsteer map[/bold] first.[/yellow]")
+        raise typer.Exit(1)
+    return model
+
+
+def _conformance(ws: Workspace, model: ArchitectureModel) -> ConformanceReport:
+    """Evaluate intent if present; otherwise return an empty report (X-ray mode)."""
+    intent = Intent.load_if_exists(ws.intent)
+    if intent is None:
+        return ConformanceReport()
+    return evaluate(model, intent)
+
+
+def _record_snapshot(ws: Workspace, model: ArchitectureModel) -> None:
+    conf = _conformance(ws, model)
+    has_intent = ws.intent.exists()
+    History(ws.history_dir).record(
+        model,
+        conformance_score=conf.conformance_score if has_intent else None,
+        drift_score=conf.drift_score if has_intent else None,
+        open_violations=len(conf.all_violations) if has_intent else None,
+    )
+
+
+@app.command()
+def version() -> None:
+    """Print the ArchSteer version."""
+    console.print(f"ArchSteer {__version__}")
+
+
+@app.command()
+def init(path: Optional[str] = typer.Option(None, help="Repo root (default: cwd).")) -> None:
+    """Scaffold .archsteer/ and seed the starter intent + ADRs."""
+    ws = _ws(path)
+    if ws.initialized:
+        console.print(f"[yellow]Already initialized at {ws.dir}[/yellow]")
+        raise typer.Exit(0)
+    ws.dir.mkdir(parents=True, exist_ok=True)
+    ws.adr_dir.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(PACK_DIR / "architecture.yaml", ws.intent)
+    for adr in (PACK_DIR / "adr").glob("*.md"):
+        shutil.copyfile(adr, ws.adr_dir / adr.name)
+    console.print(f"[green]✓[/green] Initialized [bold]{ws.dir}[/bold]")
+    console.print("  • seeded [cyan]architecture.yaml[/cyan] (Express → Next.js + repository)")
+    console.print("  • seeded baseline ADRs in [cyan].archsteer/adr/[/cyan]")
+    console.print("\nNext: [bold]archsteer map[/bold] then [bold]archsteer report[/bold]")
+
+
+@app.command()
+def map(path: Optional[str] = typer.Option(None, help="Repo root (default: cwd).")) -> None:
+    """Build the architecture model (.archsteer/model.json) from source."""
+    ws = _ws(path)
+    _require_init(ws)
+    if ws.model.exists():
+        shutil.copyfile(ws.model, ws.model_prev)  # keep prior snapshot for `adr`
+    model = build_model(ws.root)
+    model.save(ws.model)
+    _record_snapshot(ws, model)
+    console.print(
+        f"[green]✓[/green] Mapped [bold]{len(model.components)}[/bold] components · "
+        f"layers: {', '.join(sorted(model.get_layers())) or '—'} · "
+        f"data stores: {', '.join(sorted(model.get_all_data_stores())) or '—'}"
+    )
+
+
+@app.command()
+def docs(path: Optional[str] = typer.Option(None)) -> None:
+    """Regenerate living architecture docs (deterministic)."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    ws.architecture_md.write_text(render_architecture_md(model), encoding="utf-8")
+    console.print(f"[green]✓[/green] Wrote [bold]{ws.architecture_md}[/bold]")
+
+
+@app.command()
+def adr(path: Optional[str] = typer.Option(None)) -> None:
+    """Detect structural decisions since the last map and draft ADRs."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    prev = ArchitectureModel.load_if_exists(ws.model_prev)
+    engine = DecisionEngine(ws.adr_dir)
+    drafts = engine.analyze_diff(prev, model)
+    written = engine.write_drafts(drafts)
+    if not written:
+        console.print("[green]✓[/green] No new architectural decisions to record.")
+        return
+    console.print(f"[yellow]📝 {len(written)} draft ADR(s) need architect review:[/yellow]")
+    for p in written:
+        console.print(f"  • {p.relative_to(ws.root)}")
+
+
+@app.command()
+def govern(path: Optional[str] = typer.Option(None)) -> None:
+    """Show conformance and drift against declared intent."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    report = _conformance(ws, model)
+    table = Table(title=f"Conformance — {report.target or ws.root.name}")
+    table.add_column("Rule"); table.add_column("Sev"); table.add_column("Progress", justify="right")
+    table.add_column("Open", justify="right")
+    for r in report.results:
+        table.add_row(r.rule_id, r.severity, f"{r.progress}%", str(len(r.violations)))
+    console.print(table)
+    console.print(
+        f"Overall conformance: [bold]{report.conformance_score}%[/bold] · "
+        f"drift: [bold]{report.drift_score}%[/bold]"
+    )
+
+
+@app.command()
+def baseline(path: Optional[str] = typer.Option(None)) -> None:
+    """Snapshot current violations as accepted debt (the ratchet)."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    report = _conformance(ws, model)
+    bl = Baseline.from_report(report)
+    bl.save(ws.baseline)
+    console.print(f"[green]✓[/green] Baselined [bold]{len(bl.fingerprints)}[/bold] existing violation(s).")
+    console.print("New violations will now be blocked by [bold]archsteer check[/bold].")
+
+
+@app.command()
+def check(
+    path: Optional[str] = typer.Option(None),
+    remap: bool = typer.Option(True, help="Rebuild the model before checking."),
+) -> None:
+    """Fail (exit 1) on NET-NEW violations only — for CI / pre-commit."""
+    ws = _ws(path)
+    _require_init(ws)
+    if remap:
+        model = build_model(ws.root)
+        model.save(ws.model)
+    else:
+        model = _load_model(ws)
+    report = _conformance(ws, model)
+    bl = Baseline.load_if_exists(ws.baseline)
+    if bl is None:
+        console.print("[yellow]No baseline — treating ALL violations as net-new.[/yellow]")
+        net_new = report.all_violations
+        fixed = 0
+    else:
+        net_new = bl.net_new(report)
+        fixed = bl.fixed(report)
+    if fixed:
+        console.print(f"[green]↑ {fixed} baselined violation(s) resolved — nice.[/green]")
+    blocking = [v for v in net_new if v.severity == "error"]
+    for v in net_new:
+        tag = "[red]✗[/red]" if v.severity == "error" else "[yellow]△[/yellow]"
+        console.print(f"{tag} {v.file}:{v.loc} [dim]{v.rule_id}[/dim] — {v.message}")
+    if blocking:
+        console.print(f"\n[red]✗ {len(blocking)} net-new error violation(s) block this change.[/red]")
+        raise typer.Exit(1)
+    console.print("\n[green]✓ No net-new blocking violations.[/green]")
+
+
+@app.command()
+def steer(
+    path: Optional[str] = typer.Option(None),
+    files: Optional[List[str]] = typer.Option(None, "--files", "-f", help="Files in scope."),
+    task: Optional[str] = typer.Option(None, "--task", "-t", help="What the agent is about to do."),
+    targets: Optional[List[str]] = typer.Option(None, "--target", help="Agent files to write."),
+) -> None:
+    """Inject sharp, model-grounded guardrails into agent context files."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    intent = Intent.load(ws.intent)
+    engine = AgentSteeringEngine(ws.root)
+    payload = engine.synthesize(intent, model, files=files, task=task)
+    written = engine.write(payload, targets=targets)
+    console.print(f"[green]✓[/green] Steered: {', '.join(str(p.relative_to(ws.root)) for p in written) or '(no targets)'}")
+
+
+def _render_report(ws: Workspace, model: ArchitectureModel) -> None:
+    conf = _conformance(ws, model)
+    governed = ws.intent.exists()
+    prev = ArchitectureModel.load_if_exists(ws.model_prev)
+    pending = [d.title for d in DecisionEngine(ws.adr_dir).analyze_diff(prev, model)]
+    bl = Baseline.load_if_exists(ws.baseline)
+    fixed = bl.fixed(conf) if bl else 0
+    hist = History(ws.history_dir)
+    metas = hist.metas()
+    old_meta, new_meta = hist.latest_two()
+    old_model = hist.load_model(old_meta) if old_meta else None
+    feed = compute_feed(old_model, model, old_meta, new_meta)
+    ws.report_html.write_text(
+        render_report_html(
+            model, conf, pending, fixed_count=fixed,
+            feed=feed, history=metas, governed=governed,
+        ),
+        encoding="utf-8",
+    )
+
+
+@app.command()
+def report(path: Optional[str] = typer.Option(None)) -> None:
+    """Build the self-contained report.html (map + evolution + conformance + decisions)."""
+    ws = _ws(path)
+    _require_init(ws)
+    _render_report(ws, _load_model(ws))
+    console.print(f"[green]✓[/green] Wrote [bold]{ws.report_html}[/bold] — open it in a browser.")
+
+
+@app.command()
+def xray(path: Optional[str] = typer.Option(None, help="Repo root (default: cwd).")) -> None:
+    """Zero-config read-only X-ray: map + docs + evolution + report, no intent needed.
+
+    The universal wedge — point it at ANY repo and instantly see what the
+    architecture is and how it changed, without declaring any rules.
+    """
+    ws = _ws(path)
+    ws.dir.mkdir(parents=True, exist_ok=True)
+    if ws.model.exists():
+        shutil.copyfile(ws.model, ws.model_prev)
+    model = build_model(ws.root)
+    model.save(ws.model)
+    _record_snapshot(ws, model)
+    ws.architecture_md.write_text(render_architecture_md(model), encoding="utf-8")
+    # Draft ADRs for any structural change since last snapshot (architect-in-the-loop).
+    DecisionEngine(ws.adr_dir).write_drafts(
+        DecisionEngine(ws.adr_dir).analyze_diff(
+            ArchitectureModel.load_if_exists(ws.model_prev), model
+        )
+    )
+    _render_report(ws, model)
+    old_meta, new_meta = History(ws.history_dir).latest_two()
+    feed = compute_feed(
+        History(ws.history_dir).load_model(old_meta) if old_meta else None,
+        model, old_meta, new_meta,
+    )
+    console.print(
+        f"[green]✓[/green] X-ray of [bold]{ws.root.name}[/bold]: "
+        f"{len(model.components)} components, {len(model.get_layers())} layers."
+    )
+    console.print(f"  {feed.summary()}")
+    console.print(f"  → [bold]{ws.architecture_md.relative_to(ws.root)}[/bold] and "
+                  f"[bold]{ws.report_html.relative_to(ws.root)}[/bold] (open in a browser)")
+
+
+@app.command()
+def push(
+    path: Optional[str] = typer.Option(None),
+    url: Optional[str] = typer.Option(None, envvar="ARCHSTEER_URL", help="Ingest endpoint."),
+    token: Optional[str] = typer.Option(None, envvar="ARCHSTEER_TOKEN", help="Org API token."),
+    org: Optional[str] = typer.Option(None, envvar="ARCHSTEER_ORG", help="Organization slug."),
+) -> None:
+    """Push the latest snapshot + conformance to the cloud situation room."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    conf = _conformance(ws, model)
+    governed = ws.intent.exists()
+    prev = ArchitectureModel.load_if_exists(ws.model_prev)
+    pending = len(DecisionEngine(ws.adr_dir).analyze_diff(prev, model))
+    hist = History(ws.history_dir)
+    old_meta, new_meta = hist.latest_two()
+    feed = compute_feed(hist.load_model(old_meta) if old_meta else None, model, old_meta, new_meta)
+
+    payload = {
+        "repo": model.repo_name,
+        "org": org,
+        "commit": model.commit_sha,
+        "timestamp": model.timestamp,
+        "components": len(model.components),
+        "layers": sorted(model.get_layers()),
+        "external_dependencies": len(model.get_all_external_dependencies()),
+        "data_stores": len([s for s in model.get_all_data_stores() if s != "raw_sql"]),
+        "conformance_score": conf.conformance_score if governed else None,
+        "drift_score": conf.drift_score if governed else None,
+        "open_violations": len(conf.all_violations) if governed else None,
+        "pending_decisions": pending,
+        "changes": [c.model_dump() for c in feed.changes],
+    }
+    endpoint = url or "https://archsteer.dev/api/ingest"
+    req = urllib.request.Request(
+        endpoint, data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json",
+                 **({"Authorization": f"Bearer {token}"} if token else {})},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            body = json.loads(resp.read().decode("utf-8"))
+        console.print(
+            f"[green]✓[/green] Pushed [bold]{model.repo_name}[/bold] → situation room "
+            f"({endpoint}) · {body.get('snapshots', '?')} snapshot(s)."
+        )
+    except urllib.error.HTTPError as e:
+        console.print(f"[red]✗ Push failed ({e.code}): {e.reason}[/red]")
+        raise typer.Exit(1)
+    except urllib.error.URLError as e:
+        console.print(f"[red]✗ Could not reach {endpoint}: {e.reason}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def evolution(
+    path: Optional[str] = typer.Option(None),
+    limit: int = typer.Option(15, help="Max changes to show."),
+) -> None:
+    """Show the Architecture Evolution Feed between the two latest snapshots."""
+    ws = _ws(path)
+    hist = History(ws.history_dir)
+    old_meta, new_meta = hist.latest_two()
+    if new_meta is None:
+        console.print("[yellow]No history yet — run [bold]archsteer map[/bold] or [bold]xray[/bold] first.[/yellow]")
+        raise typer.Exit(1)
+    old_model = hist.load_model(old_meta) if old_meta else None
+    new_model = hist.load_model(new_meta)
+    feed = compute_feed(old_model, new_model, old_meta, new_meta)
+    console.print(f"[bold]Architecture Evolution[/bold] — {feed.summary()}")
+    if feed.drift_delta is not None:
+        arrow = "↓ improved" if feed.drift_delta < 0 else ("↑ worsened" if feed.drift_delta > 0 else "unchanged")
+        console.print(f"Drift Index: {arrow} ({'+' if feed.drift_delta > 0 else ''}{feed.drift_delta} pts)")
+    for c in feed.changes[:limit]:
+        icon = {"positive": "[green]✓[/green]", "negative": "[red]✗[/red]"}.get(c.direction, "•")
+        console.print(f"  {icon} {c.text}")
+
+
+if __name__ == "__main__":
+    app()

archsteer-0.1.0/archsteer/docs.py

@@ -0,0 +1,73 @@
+"""Living architecture docs generated from the model (deterministic / idempotent).
+
+Intentionally excludes wall-clock timestamps so regeneration is byte-identical when
+the model is unchanged (verification relies on this). Produces architecture.md with
+a Mermaid layer diagram and a component catalog.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Dict, List, Set, Tuple
+
+from archsteer.engine.model import ArchitectureModel
+
+
+def _layer_edges(model: ArchitectureModel) -> Set[Tuple[str, str]]:
+    edges: Set[Tuple[str, str]] = set()
+    for src, dst in model.internal_edges():
+        sl = model.components[src].layer or "unassigned"
+        dl = model.components[dst].layer or "unassigned"
+        if sl != dl:
+            edges.add((sl, dl))
+    return edges
+
+
+def _mermaid(model: ArchitectureModel) -> str:
+    edges = sorted(_layer_edges(model))
+    layers = sorted(model.get_layers() | {"unassigned"})
+    lines = ["```mermaid", "graph LR"]
+    if not edges:
+        for layer in layers:
+            lines.append(f"    {layer}[{layer}]")
+    for sl, dl in edges:
+        lines.append(f"    {sl}[{sl}] --> {dl}[{dl}]")
+    lines.append("```")
+    return "\n".join(lines)
+
+
+def render_architecture_md(model: ArchitectureModel) -> str:
+    layer_counts: Dict[str, int] = defaultdict(int)
+    for comp in model.components.values():
+        layer_counts[comp.layer or "unassigned"] += 1
+
+    ext_deps = sorted(model.get_all_external_dependencies())
+    stores = sorted(model.get_all_data_stores())
+
+    out: List[str] = [
+        f"# Architecture — {model.repo_name}",
+        "",
+        "> Auto-generated by ArchSteer from source. Do not edit by hand; run `archsteer docs`.",
+        "",
+        "## Overview",
+        f"- **Components:** {len(model.components)}",
+        f"- **Layers:** {', '.join(sorted(model.get_layers())) or '—'}",
+        f"- **Data stores:** {', '.join(stores) or '—'}",
+        f"- **External call sites:** {sum(len(c.external_calls) for c in model.components.values())}",
+        "",
+        "## Layer map",
+        _mermaid(model),
+        "",
+        "## Components by layer",
+    ]
+    for layer in sorted(layer_counts):
+        out.append(f"- **{layer}** — {layer_counts[layer]} component(s)")
+    out += ["", "## Component catalog", "", "| Component | Layer | Exports | Data access | External |", "|---|---|---|---|---|"]
+    for path in sorted(model.components):
+        c = model.components[path]
+        exports = ", ".join(c.exported_apis[:4]) or "—"
+        da = ", ".join(sorted({d.entity for d in c.data_access})) or "—"
+        ext = str(len(c.external_calls)) if c.external_calls else "—"
+        out.append(f"| `{path}` | {c.layer or '—'} | {exports} | {da} | {ext} |")
+    out.append("")
+    return "\n".join(out)