@eltonssouza/development-utility-kit 0.10.0

package/.claude/stacks/python/django-5.md

@@ -0,0 +1,483 @@
+---
+stack: python/django-5
+versions_covered: "5.0.x — 5.2.x"
+last_validated: 2026-05-28
+validated_against: "reference pack — Python 3.13 + Django 5.2 LTS + DRF 3.15"
+status: active
+pack_owner: "@elton"
+security_review: 2026-05-28
+next_review_due: 2027-05-28
+---
+
+# Python 3.13 + Django 5.x
+
+Canonical knowledge pack for greenfield projects on Python 3.12+/3.13 + Django 5.x (5.0, 5.1, 5.2 LTS). Django 5 raised the floor to Python 3.10+ and brought significant async view maturity, generated model fields, declarative DRF serializers, and Python 3.13 free-threaded compatibility on Django 5.2. For projects still on Django 4.2 LTS, use `django-4.md` (not yet published — open issue if you need it).
+
+## 1. When to use this pack
+
+- Project declares `Primary stack: Python 3.12+ + Django 5.x` in `## Project Identity`.
+- `pyproject.toml` (or `requirements.txt`) declares `django>=5.0,<6.0` and `python_requires = ">=3.12"`.
+- Greenfield: **prefer this pack** unless your hosting platform pins Python 3.10/3.11.
+- API-heavy projects: pair Django with Django REST Framework (DRF) for the API layer; `## Code patterns` below assumes DRF.
+- For projects that are HTTP-API-only (no admin, no templates), consider FastAPI (`python/fastapi-*.md`) — Django shines when the admin + ORM + auth + forms ecosystem is valuable.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| Python | 3.12 (min) / 3.13 (recommended) | 3.13 brings free-threaded build; Django 5.2 verified on 3.13 |
+| Django | 5.0.x — 5.2.x | 5.2 is LTS (April 2025 → April 2028); 5.0/5.1 are non-LTS |
+| Django REST Framework | 3.15.x | Declarative serializer mode; `@extend_schema` for OpenAPI via drf-spectacular |
+| ORM / migrations | Django ORM (native) + django-migrations | Never raw SQL outside `RunSQL` migrations; never auto-makemigrations in CI |
+| Build / packaging | `uv` (recommended) or `pip` + `pyproject.toml` | `uv` is 10–100× faster; `uv lock` produces deterministic lockfiles |
+| Async runtime | ASGI via `uvicorn` workers + `gunicorn` master | WSGI via `gunicorn` if no async views needed |
+| Tests | pytest 8.x + pytest-django 4.x + factory-boy 3.x + Faker | NEVER SQLite for tests if prod is Postgres — use Postgres in CI via service container |
+| Mutation | mutmut 3.x (or cosmic-ray) | Target ≥70% on `domain/` + `application/` |
+| Coverage | coverage.py 7.x with `branch = True` | Target ≥85% lines, ≥80% branches |
+| Static analysis | `ruff` (replaces flake8/black/isort) + `mypy` + `django-stubs` | `ruff check --fix .` + `ruff format .` + `mypy --strict` on `domain/` and `application/` |
+| Security scan | `pip-audit` + `bandit` | 0 CVE with CVSS ≥7.0; `bandit -ll` for medium+ |
+| Observability | OpenTelemetry SDK + `opentelemetry-instrumentation-django` | W3C Trace Context; auto-instrumented requests, DB, cache |
+| Background jobs | Celery 5.x + Redis 7 | Or Django-Q2 for simpler needs |
+| Static files | `whitenoise` | Behind gunicorn; no separate Nginx for static needed |
+| Env config | `django-environ` or `pydantic-settings` | `.env` file gitignored; `env.example` committed |
+
+## 3. Project structure (DDD-flavored Django)
+
+```
+backend/
+├── pyproject.toml                # uv-managed; PEP 621 metadata
+├── uv.lock                       # committed
+├── manage.py
+├── env.example                   # committed; .env gitignored
+├── config/                       # Django project (settings)
+│   ├── __init__.py
+│   ├── asgi.py
+│   ├── wsgi.py
+│   ├── urls.py
+│   └── settings/
+│       ├── __init__.py
+│       ├── base.py
+│       ├── dev.py
+│       ├── prod.py
+│       └── test.py
+├── domain/                       # pure Python; no Django imports
+│   ├── products/
+│   │   ├── entities.py           # dataclasses, value objects
+│   │   ├── repository.py         # ABC port; impl lives in infrastructure
+│   │   └── services.py           # pure domain services
+│   └── shared/
+├── application/                  # use cases (1 public callable each)
+│   ├── products/
+│   │   ├── create_product.py
+│   │   ├── list_products.py
+│   │   └── dto.py                # request/response dataclasses
+│   └── shared/
+├── infrastructure/               # Django ORM adapters, external clients
+│   ├── products/
+│   │   ├── models.py             # @models.Model — JPA-equivalent layer
+│   │   ├── repository_impl.py    # adapts ORM to the domain port
+│   │   └── migrations/
+│   └── shared/
+├── api/                          # DRF views + serializers + urls
+│   ├── products/
+│   │   ├── serializers.py
+│   │   ├── views.py              # APIView / ViewSet
+│   │   ├── urls.py
+│   │   └── permissions.py
+│   └── shared/
+│       └── exception_handler.py  # DRF custom exception handler -> RFC 9457
+└── tests/
+    ├── unit/                     # domain + application
+    ├── integration/              # ORM + DRF with TestContainers Postgres
+    └── e2e/                      # Playwright (optional, if there is a UI)
+```
+
+**Rule**: `domain/` and `application/` contain **zero Django imports**. They are pure Python testable without a database, without `pytest-django`, in milliseconds. `infrastructure/` is the only layer that imports `django.db.models`. `api/` is the only layer that imports `rest_framework`.
+
+## 4. Code patterns
+
+### Domain entity as `@dataclass(frozen=True)` (no Django dependency)
+
+```python
+# domain/products/entities.py
+from dataclasses import dataclass
+from decimal import Decimal
+from uuid import UUID
+from datetime import datetime
+
+@dataclass(frozen=True)
+class Product:
+    id: UUID
+    name: str
+    price: Decimal
+    stock: int
+    created_at: datetime
+
+    def reserve(self, qty: int) -> "Product":
+        if qty <= 0:
+            raise ValueError("qty must be positive")
+        if qty > self.stock:
+            raise ValueError("insufficient stock")
+        return Product(self.id, self.name, self.price, self.stock - qty, self.created_at)
+```
+
+**Rule**: domain entities are immutable (`frozen=True`), live in `domain/`, and have **zero Django imports**. Business invariants are methods on the entity, not service-layer code. Tests for this file run without `pytest-django`.
+
+### Infrastructure ORM model (separate file, separate type)
+
+```python
+# infrastructure/products/models.py
+from django.db import models
+import uuid
+
+class ProductORM(models.Model):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    name = models.CharField(max_length=120, db_index=True)
+    price = models.DecimalField(max_digits=12, decimal_places=2)
+    stock = models.PositiveIntegerField()
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        db_table = "products"
+        indexes = [models.Index(fields=["created_at"])]
+```
+
+**Rule**: ORM models live in `infrastructure/`, never `domain/`. Naming: `<Entity>ORM` to mark the boundary. Translation between domain entity and ORM model happens in `repository_impl.py`. UUID primary key by default — sequential integers are an anti-pattern for distributed systems.
+
+### Repository implementation (DDD-style adapter)
+
+```python
+# infrastructure/products/repository_impl.py
+from typing import Optional
+from uuid import UUID
+from domain.products.entities import Product
+from domain.products.repository import ProductRepository
+from infrastructure.products.models import ProductORM
+
+class DjangoProductRepository(ProductRepository):
+    def get(self, id: UUID) -> Optional[Product]:
+        row = ProductORM.objects.filter(id=id).first()
+        return self._to_domain(row) if row else None
+
+    def save(self, product: Product) -> None:
+        ProductORM.objects.update_or_create(
+            id=product.id,
+            defaults={
+                "name": product.name,
+                "price": product.price,
+                "stock": product.stock,
+            },
+        )
+
+    @staticmethod
+    def _to_domain(row: ProductORM) -> Product:
+        return Product(
+            id=row.id, name=row.name, price=row.price,
+            stock=row.stock, created_at=row.created_at,
+        )
+```
+
+**Rule**: domain port (`ProductRepository`) is an ABC defined in `domain/`. Implementation imports Django. Application use cases depend on the ABC, not the impl — wired by DI in `apps.py` or via simple module-level singleton.
+
+### DRF serializer + view (declarative mode, Django 5.x)
+
+```python
+# api/products/serializers.py
+from rest_framework import serializers
+from decimal import Decimal
+
+class CreateProductRequest(serializers.Serializer):
+    name = serializers.CharField(max_length=120)
+    price = serializers.DecimalField(max_digits=12, decimal_places=2, min_value=Decimal("0.01"))
+    stock = serializers.IntegerField(min_value=0)
+
+class ProductResponse(serializers.Serializer):
+    id = serializers.UUIDField(read_only=True)
+    name = serializers.CharField(read_only=True)
+    price = serializers.DecimalField(max_digits=12, decimal_places=2, read_only=True)
+    stock = serializers.IntegerField(read_only=True)
+    created_at = serializers.DateTimeField(read_only=True)
+```
+
+```python
+# api/products/views.py
+from rest_framework.views import APIView
+from rest_framework.response import Response
+from rest_framework import status
+from application.products.create_product import CreateProductUseCase
+from .serializers import CreateProductRequest, ProductResponse
+
+class ProductCreateView(APIView):
+    def __init__(self, use_case: CreateProductUseCase, **kwargs):
+        super().__init__(**kwargs)
+        self.use_case = use_case
+
+    def post(self, request):
+        req = CreateProductRequest(data=request.data)
+        req.is_valid(raise_exception=True)
+        product = self.use_case.execute(**req.validated_data)
+        return Response(ProductResponse(product).data, status=status.HTTP_201_CREATED)
+```
+
+**Rule**: serializers are request/response DTOs, never `ModelSerializer` from ORM directly (it leaks the data model into the API contract). Views are thin — they parse, validate, call the use case, serialize the response. Business logic lives in `application/`.
+
+### Async view (Django 5.x, when a real reason exists)
+
+```python
+# api/products/async_views.py
+from adrf.views import APIView   # async DRF
+from rest_framework.response import Response
+import httpx
+
+class ProductPriceCheckView(APIView):
+    async def get(self, request, product_id):
+        async with httpx.AsyncClient(timeout=2.0) as client:
+            r = await client.get(f"https://price-api.example.com/{product_id}")
+        return Response({"upstream_price": r.json()["price"]})
+```
+
+**Rule**: async views only when the view does I/O that benefits from concurrency (external HTTP, large concurrent reads). Sync views are simpler and have less footgun (no `sync_to_async` mismatch on ORM). When in doubt, sync.
+
+## 5. Testing
+
+### Unit (pytest, no Django bootstrap)
+
+```python
+# tests/unit/domain/products/test_product.py
+import pytest
+from decimal import Decimal
+from uuid import uuid4
+from datetime import datetime
+from domain.products.entities import Product
+
+def test_reserve_decreases_stock():
+    p = Product(uuid4(), "x", Decimal("9.90"), stock=10, created_at=datetime.now())
+    p2 = p.reserve(3)
+    assert p2.stock == 7
+
+def test_reserve_refuses_zero():
+    p = Product(uuid4(), "x", Decimal("9.90"), stock=10, created_at=datetime.now())
+    with pytest.raises(ValueError):
+        p.reserve(0)
+```
+
+Runs in milliseconds. No `pytest-django`, no DB.
+
+### Integration (pytest-django + Testcontainers Postgres)
+
+```python
+# conftest.py
+import pytest
+from testcontainers.postgres import PostgresContainer
+
+@pytest.fixture(scope="session")
+def postgres_container():
+    with PostgresContainer("postgres:16-alpine") as pg:
+        yield pg
+
+@pytest.fixture(scope="session")
+def django_db_setup(django_db_setup, postgres_container):
+    pass  # connection URL injected via env in pytest.ini
+```
+
+```python
+# tests/integration/infrastructure/products/test_repository.py
+import pytest
+from decimal import Decimal
+from uuid import uuid4
+from datetime import datetime, timezone
+from domain.products.entities import Product
+from infrastructure.products.repository_impl import DjangoProductRepository
+
+@pytest.mark.django_db
+def test_save_and_get():
+    repo = DjangoProductRepository()
+    p = Product(uuid4(), "widget", Decimal("9.90"), 100, datetime.now(timezone.utc))
+    repo.save(p)
+    fetched = repo.get(p.id)
+    assert fetched == p
+```
+
+**Rule**: never SQLite for integration tests if production is Postgres. Use Testcontainers Postgres 16. Migrations run automatically via `pytest-django`.
+
+### Mutation (mutmut)
+
+```bash
+mutmut run --paths-to-mutate=domain,application
+mutmut results
+# Target: killed/total >= 70% on domain/ and application/
+```
+
+### E2E (Playwright, optional)
+
+```python
+# tests/e2e/test_create_product_flow.py
+from playwright.sync_api import Page, expect
+
+def test_user_creates_product(page: Page, live_server):
+    page.goto(f"{live_server.url}/admin/login/")
+    # ... login + navigation + assertions
+    expect(page.get_by_text("widget")).to_be_visible()
+```
+
+## 6. Build & run commands
+
+```bash
+# Setup (uv recommended)
+uv venv
+uv pip sync requirements.lock   # or: uv pip install -e ".[dev]"
+
+# Run dev
+python manage.py migrate
+python manage.py runserver 0.0.0.0:8000
+
+# Run prod (ASGI)
+uvicorn config.asgi:application --workers 4 --host 0.0.0.0 --port 8000
+
+# Lint + format (ruff replaces flake8 + black + isort)
+ruff check --fix .
+ruff format .
+
+# Type check
+mypy --strict domain/ application/
+
+# Tests
+pytest                                          # all
+pytest tests/unit/                              # fast loop
+pytest --cov=domain --cov=application --cov-branch --cov-fail-under=85
+pytest -m "not slow"                            # skip Testcontainers in tight loop
+
+# Mutation
+mutmut run --paths-to-mutate=domain,application
+
+# Security scan
+pip-audit
+bandit -ll -r domain/ application/ infrastructure/ api/
+
+# Migrations (always review before commit)
+python manage.py makemigrations
+python manage.py showmigrations
+python manage.py migrate
+
+# Production-only checks before deploy
+python manage.py check --deploy
+```
+
+## 7. Security (per ADR-007 + ADR-027 — MANDATORY section)
+
+### 7.1 Authentication & Authorization
+
+- **Sessions for admin/web**: Django's built-in session auth. Cookie flags: `SESSION_COOKIE_SECURE=True`, `SESSION_COOKIE_HTTPONLY=True`, `SESSION_COOKIE_SAMESITE="Lax"` (or `Strict`).
+- **API auth**: DRF + `djangorestframework-simplejwt` for stateless JWT, OR `dj-rest-auth` + session for cookie-based SPAs. Choose one — do not mix without ADR.
+- **Password hashing**: Django uses Argon2 (preferred) or PBKDF2-SHA256. Add `argon2-cffi` and set `PASSWORD_HASHERS` with Argon2 first. Bcrypt with cost 12 acceptable.
+- **MFA**: `django-otp` + `django-two-factor-auth` for TOTP. Always enabled for staff users.
+- **Authorization**: `permissions.py` per app, using DRF `BasePermission` subclasses. Object-level via `get_object()` + check. IDOR mitigation: every "owned resource" read/write validates `request.user.id == obj.owner_id`.
+
+### 7.2 CORS
+
+```python
+# settings/prod.py
+INSTALLED_APPS += ["corsheaders"]
+MIDDLEWARE.insert(0, "corsheaders.middleware.CorsMiddleware")
+CORS_ALLOWED_ORIGINS = ["https://app.example.com"]   # NEVER ["*"] in prod
+CORS_ALLOW_CREDENTIALS = True
+```
+
+### 7.3 Validation & input sanitization
+
+- **SQL injection**: ORM parameterizes by default. NEVER use `raw()` or `extra()` with f-strings/concatenation. If raw SQL is needed, use `cursor.execute(sql, params)` with `%s` placeholders.
+- **XSS**: Django templates auto-escape. DRF serializers do not auto-escape — sanitize via `bleach` if rendering user HTML in any frontend.
+- **Path traversal**: never join user input directly into `FileField` `upload_to`. Use `secrets.token_urlsafe()` for filenames.
+- **Mass assignment**: DRF serializers explicit; never `Serializer(Meta).fields = "__all__"` on writable serializers — list fields explicitly.
+
+### 7.4 Secrets management
+
+- `.env` file (loaded by `django-environ`) gitignored; `env.example` committed with placeholder values.
+- `SECRET_KEY`: env var; rotate via `python manage.py rotate_secret_key` ritual (manual; Django does not auto-rotate). On rotation, invalidate sessions.
+- AWS Secrets Manager / GCP Secret Manager / HashiCorp Vault preferred over `.env` for prod.
+
+### 7.5 Rate limiting
+
+```python
+# pip install django-ratelimit
+from django_ratelimit.decorators import ratelimit
+
+@ratelimit(key="ip", rate="5/m", method="POST", block=True)
+def login_view(request):
+    ...
+```
+
+- `5/m` on `/api/auth/login`, `/api/auth/password-reset`, `/api/auth/signup`.
+- `100/m` on regular GET endpoints by user.
+- For DRF: `rest_framework.throttling.AnonRateThrottle` + `UserRateThrottle` with `DEFAULT_THROTTLE_RATES`.
+- Brute-force lockout: `django-axes` for admin and login views — lock account after 5 failed attempts within 10 minutes.
+
+### 7.6 OWASP Top 10 mapping
+
+| OWASP | Mitigation in Django 5.x |
+|---|---|
+| A01 Broken Access Control | `LoginRequiredMiddleware` (Django 5.0+); per-view DRF permissions; object-level `get_object_or_404(Model, owner=request.user, id=...)` pattern |
+| A02 Cryptographic Failures | Argon2 password hasher; `DJANGO_SETTINGS_MODULE=config.settings.prod` enforces TLS; `SECURE_HSTS_SECONDS=31536000`, `SECURE_HSTS_INCLUDE_SUBDOMAINS=True`, `SECURE_HSTS_PRELOAD=True` |
+| A03 Injection | ORM parameterization; never `raw()`/`extra()` with f-strings; DRF input validation via serializers |
+| A04 Insecure Design | DDD layering enforced (`domain/` no Django); use cases as single-responsibility classes; ADRs document deviations |
+| A05 Security Misconfiguration | `python manage.py check --deploy` in CI; `DEBUG=False` in prod via env split; `ALLOWED_HOSTS` set to actual domains; `X_FRAME_OPTIONS="DENY"` |
+| A06 Vulnerable Components | `pip-audit` in CI; `dependabot` or `renovate` for PR-based bumps; `bandit` for code-level patterns |
+| A07 Auth Failures | `django-axes` brute-force lock; Argon2 hashing; `django-two-factor-auth` for staff; session rotation on password change |
+| A08 Data Integrity | Verify upstream packages via `uv pip install --require-hashes`; SBOM via `cyclonedx-py`; signed releases for internal libs |
+| A09 Logging Failures | Structured JSON logs via `python-json-logger`; correlation ID via `django-guid` middleware; **NEVER** log `request.body` raw (PII) |
+| A10 SSRF | Allowlist outbound HTTP via `httpx` client with explicit allowed hosts; validate URLs server-side before fetching; never trust user-supplied URLs as fetch targets |
+
+### 7.7 LGPD / GDPR / compliance specifics
+
+- **PII tagging**: a `pii=True` model field convention enforced by `django-stubs` + custom lint (or naming convention `<field>__pii`).
+- **Soft delete**: `is_deleted` boolean + `deleted_at` timestamp; never hard delete user-owned data without an explicit erasure request workflow.
+- **Data subject access**: `python manage.py export_user_data <user_id>` custom command exports all PII as JSON for GDPR Article 15.
+- **Erasure (Article 17)**: `python manage.py erase_user_data <user_id>` redacts PII fields while preserving foreign keys (e.g. orders kept with `customer=None`).
+- **Encryption at rest**: PostgreSQL TDE or column-level via `django-cryptography` for sensitive fields (CPF, ID documents).
+
+## 8. Anti-patterns (block in code-review)
+
+| ❌ Bad | ✅ Good | Why |
+|---|---|---|
+| `Product.objects.filter(...).first()` inside DRF view | Repository in `infrastructure/`, called from `application/` use case | View should be thin; logic + persistence belong in layers |
+| `ModelSerializer` exposing all ORM fields | Request/response `Serializer` with explicit fields | API contract leaks the data model otherwise |
+| `auto_now_add=True` on `created_at` + `auto_now=True` on `updated_at` mixed with manual sets | Pick one — automatic OR explicit, never both | Race conditions in batch operations |
+| `SECRET_KEY` in `settings/base.py` | `env("SECRET_KEY")` via django-environ | Secret in code = secret in git history |
+| `DEBUG=True` reachable in prod | `DJANGO_SETTINGS_MODULE=config.settings.prod` + `python manage.py check --deploy` gate | DEBUG exposes stack traces with code and DB queries |
+| Migrations auto-applied in CI without review | `makemigrations` runs locally, dev reviews, commits, then CI runs `migrate` | Schema changes need human eyes |
+| SQLite for tests when prod is Postgres | Testcontainers Postgres 16 in CI | Subtle SQL differences cause prod-only bugs |
+| `.objects.all()` without `select_related` / `prefetch_related` in templates/serializers | Explicit `.select_related("category").prefetch_related("tags")` | N+1 queries kill performance under load |
+| Catching `Exception:` in views | Catch specific domain exceptions; let DRF exception handler do the rest | Hides bugs, breaks 500 telemetry |
+| Sync view with `requests.get(...)` blocking external call | Async view + `httpx.AsyncClient` OR move external call to Celery task | Blocks worker thread; cascade failures under load |
+| `User = get_user_model()` at module level + circular import | Lazy import via `django.contrib.auth.get_user_model()` inside the function | Solves the AppRegistryNotReady bootstrap issue |
+
+## 9. Migration hints — Django 4.2 → 5.x
+
+Breaking changes worth flagging when `migrator` agent runs Django 4 → 5:
+
+- **Python 3.10 minimum** (Django 5.0); recommend 3.12 or 3.13.
+- **`USE_L10N` removed** — was deprecated since 4.0. Localization is always on; format strings via `formats.py`.
+- **`pytz` removed** — use `zoneinfo` from stdlib. Replace `pytz.timezone("America/Sao_Paulo")` with `zoneinfo.ZoneInfo("America/Sao_Paulo")`.
+- **Form rendering**: default template-based form rendering (Django 4.0+) is now the only mode. If you have legacy `as_p()` overrides, review.
+- **Async ORM**: `aget`, `aupdate`, `acreate` are first-class in 5.x; if you wrote `sync_to_async(Model.objects.get)` workarounds, swap them for native async calls.
+- **DRF on Django 5**: requires DRF 3.15+. Older DRF versions have async-related deprecations.
+- **`USE_TZ = True` enforced**: timezone-aware datetimes everywhere. If your code does `datetime.now()` without tzinfo, Django 5 issues warnings and may raise in 6.0.
+- **`LoginRequiredMiddleware`** (5.0+): when enabled, every view is login-required by default; mark public views with `@login_not_required`. Simpler than per-view decorators for protected apps.
+- **Generated model fields** (5.0+): `GeneratedField` allows DB-computed columns; consider migrating computed properties into the DB layer where appropriate.
+
+Hand off to `migrator` agent with: target version, current Django/Python versions from `pyproject.toml`, list of installed third-party Django apps (some need bumps).
+
+## 10. References
+
+- [Django 5.0 release notes](https://docs.djangoproject.com/en/5.0/releases/5.0/)
+- [Django 5.2 LTS release notes](https://docs.djangoproject.com/en/5.2/releases/5.2/)
+- [Django Security Documentation](https://docs.djangoproject.com/en/stable/topics/security/)
+- [DRF official tutorial](https://www.django-rest-framework.org/)
+- [OWASP Django Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Django_REST_Framework_Cheat_Sheet.html)
+- [pytest-django docs](https://pytest-django.readthedocs.io/)
+- [django-axes (brute-force lockout)](https://github.com/jazzband/django-axes)
+- [django-environ (env var config)](https://github.com/joke2k/django-environ)
+- ADR-007 (Senior+ gate thresholds — coverage ≥85%, mutation ≥70%)
+- ADR-026 (Generic agents + stack packs architecture)
+- ADR-027 (Pack governance — frontmatter + security mandatory + CODEOWNERS + annual review)
+- ADR-029 (Canonical pack format — this document follows it)