feat: add hexagonal architecture scaffolding

[mariushelf]

What

Restructures the generated package into a hexagonal (ports-and-adapters) layout, ported from the structure of the qualitative-feedback-analysis (QFA) repository.

Package layout

src/{{ project_slug }}/
  domain/     entities, value objects, errors, driven ports (inner core, no infra)
  services/   application services / use cases (depend only on domain)
  adapters/   driven adapter implementations of domain ports
  main.py     driving adapter + composition root (may import every layer)

No web framework is pulled in — main.py is the driving adapter. A small, clearly-marked seed slice (a Note entity, a NoteRepository port, an InMemoryNoteRepository adapter, and a NoteService) demonstrates the full pattern and is meant to be deleted once real domain modelling starts. Search # --- example to find/remove it.

Enforcement (the important part)

The layering is enforced by import-linter contracts in pyproject.toml, not just by convention:

• Enforce hexagonal layers — adapters > services > domain. main.py is intentionally not a layer, so the composition root is free to wire adapters into services without exceptions.
• Domain / services stay free of infrastructure — forbidden contracts (seeded with httpx/requests/sqlalchemy as illustrative examples to extend).

Wired into:

• .pre-commit-config.yaml (lint-imports hook)
• Makefile (import_lint, folded into make lint)
• CI lint job in cicd.yaml

Docs / AGENTS.md

AGENTS.md gains an Architecture section (layer rules, package responsibilities) and the QFA rule that every class implementing a port must explicitly inherit from it (discoverability over structural typing), plus a short Testing & Linting section.

Deliberately excluded

• Documentation (docs/) — handled in a separate PR.
• QFA-specific CI (Docker build, Postgres integration job) and infrastructure adapters (SQLAlchemy/Alembic, Presidio, LiteLLM) — kept the template dependency-free.

Verification

The template's own test suite (tests/test_template.py) passes end-to-end on the generated project — pytest, make lint (ruff + ty + import-linter), make test, python -m main, and pre-commit run --all-files (incl. the new lint-imports hook). All 6 tests green.