@damiangilgonzalez/harness 1.3.7

package/skills/django/evals/README.md

@@ -0,0 +1,11 @@
+# Evals for the `django` skill
+
+`cases.yaml` is a trigger/routing and capability rubric, not an automated test harness. Run it
+by reading each prompt and checking the skill behaves: every `should_trigger` prompt should make
+the `django` skill fire (including the non-obvious template-N+1 case and the Spanish phrasings),
+and every `should_not_trigger` prompt should route to the named sibling (`fastapi`, `postgresdb`,
+`secure-coding`, `api-design`) instead. For the `capability` case, draft the answer and confirm it
+hits every line in `must_include` — model with FK + Meta, explicit `ModelSerializer`, `ModelViewSet`
+with `permission_classes`, owner-scoped `get_queryset` with `select_related`, router registration,
+`perform_create` setting the owner, the `APIClient.force_authenticate` 403/200 test, and the
+migration step. A miss on any line means the skill body or references need tightening.

package/skills/django/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: django
+
+should_trigger:
+  - prompt: "Add a `published` filter and fix the N+1 in this Django ListView."
+    why: Core Django — QuerySet filtering plus select_related/prefetch_related on a CBV.
+  - prompt: "Build a DRF ModelViewSet for Orders with owner-only permission and wire it into a router."
+    why: Django REST Framework surface — serializer, viewset, router, object-level permission.
+  - prompt: "This template loops over `books` and queries `book.author` on each iteration and the page is slow."
+    why: Non-obvious — no word 'Django', but it is the classic ORM N+1 inside a template loop.
+  - prompt: "Revisa este modelo y añade un UniqueConstraint en (tenant, slug)."
+    why: Spanish/Catalan phrasing for a Django model Meta constraint change.
+  - prompt: "Why does `python manage.py check --deploy` warn about SECURE_HSTS_SECONDS?"
+    why: Django-specific security/settings question; the warning is the default 0 value.
+  - prompt: "El queryset hace N+1 al renderizar el feed; ¿cómo lo arreglo con prefetch?"
+    why: Spanish, non-obvious ORM performance phrasing pointing straight at prefetch_related.
+  - prompt: "Convert this fat publish() logic out of the view onto the model and add a data migration."
+    why: Fat-model rule plus RunPython migration — both squarely Django implementation.
+
+should_not_trigger:
+  - prompt: "Build an async FastAPI endpoint with Pydantic models and async SQLAlchemy."
+    route_to: fastapi
+    why: Async-first service importing fastapi/pydantic; no manage.py/INSTALLED_APPS.
+  - prompt: "Write the EXPLAIN ANALYZE for this slow query and add the right Postgres index."
+    route_to: postgresdb
+    why: DB-side query plan and indexing strategy, ORM-agnostic.
+  - prompt: "Do a STRIDE threat model of our payment flow."
+    route_to: secure-coding
+    why: Cross-stack threat modeling, not Django middleware/CSP knobs.
+  - prompt: "Should this REST API use cursor or offset pagination, and what status code for a partial update?"
+    route_to: api-design
+    why: REST contract design; the DRF wiring would be django, the contract choice is api-design.
+
+capability:
+  - scenario: >
+      Create a Django app `catalog` with a `Product` model (name, price, owner FK to the user),
+      a DRF ModelSerializer and ModelViewSet exposing it read/write to the owner only, wired into
+      a DefaultRouter, plus a pytest-django test asserting an anonymous user gets 403 and the
+      owner gets 200. Include the migration step.
+    must_include:
+      - "Product model with an owner ForeignKey and a Meta (constraint or index)"
+      - "ModelSerializer with an explicit fields list and owner as read-only"
+      - "ModelViewSet with permission_classes (IsAuthenticated + object-level IsOwner)"
+      - "get_queryset scoped to request.user and using select_related to avoid N+1"
+      - "DefaultRouter registration of the viewset"
+      - "perform_create sets owner=self.request.user (not from request data)"
+      - "pytest-django test using APIClient.force_authenticate, asserting 403 anon and 200 owner"
+      - "makemigrations/migrate step for the new model"

package/skills/django/references/drf.md

@@ -0,0 +1,109 @@
+# Django REST Framework (DRF 3.17.x)
+
+DRF turns models into a JSON API. The layering mirrors core Django: **serializer = form/marshal,
+viewset = view, router = URLconf**. Keep business logic on the model; the serializer validates
+and shapes, the viewset orchestrates.
+
+## Serializers
+
+Prefer `ModelSerializer` — it derives fields and validators from the model.
+
+```python
+from rest_framework import serializers
+from catalog.models import Product
+
+class ProductSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Product
+        fields = ["id", "name", "price", "owner"]
+        read_only_fields = ["owner"]  # set server-side, never trust the client
+
+    def validate_price(self, value):
+        if value < 0:
+            raise serializers.ValidationError("price must be non-negative")
+        return value
+```
+
+- Use an explicit `fields` list. `fields = "__all__"` leaks new columns the moment a model grows.
+- Server-owned fields (`owner`, `tenant`, timestamps) are `read_only`; set them in
+  `perform_create`, not from request data.
+- A plain `serializers.Serializer` is for non-model payloads (search params, RPC-style bodies).
+
+## ViewSets + routers
+
+```python
+from rest_framework import viewsets, permissions
+from rest_framework.routers import DefaultRouter
+
+class IsOwner(permissions.BasePermission):
+    def has_object_permission(self, request, view, obj):
+        return obj.owner_id == request.user.id
+
+class ProductViewSet(viewsets.ModelViewSet):
+    serializer_class = ProductSerializer
+    permission_classes = [permissions.IsAuthenticated, IsOwner]
+
+    def get_queryset(self):
+        # scope to the caller AND prefetch — the viewset is where N+1 is born
+        return Product.objects.filter(owner=self.request.user).select_related("owner")
+
+    def perform_create(self, serializer):
+        serializer.save(owner=self.request.user)
+
+router = DefaultRouter()
+router.register("products", ProductViewSet, basename="product")
+urlpatterns = router.urls
+```
+
+- **Every viewset declares `permission_classes`.** A `ModelViewSet` with none is a fully open
+  CRUD endpoint. Set a project default in `DEFAULT_PERMISSION_CLASSES` and override per view.
+- `IsAuthenticated` gates the request; object-level checks live in `has_object_permission`.
+- `get_queryset` filters by tenant/owner *and* prefetches. A serializer that walks a relation
+  with no prefetch is an N+1 per row — assert query counts in tests.
+
+## Pagination, throttling, filtering
+
+```python
+# settings: DRF defaults
+REST_FRAMEWORK = {
+    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.CursorPagination",
+    "PAGE_SIZE": 50,
+    "DEFAULT_THROTTLE_CLASSES": ["rest_framework.throttling.ScopedRateThrottle"],
+    "DEFAULT_THROTTLE_RATES": {"login": "5/min", "default": "1000/day"},
+    "DEFAULT_FILTER_BACKENDS": ["rest_framework.filters.SearchFilter",
+                                "rest_framework.filters.OrderingFilter"],
+}
+```
+
+```python
+class ProductViewSet(viewsets.ModelViewSet):
+    search_fields = ["name"]
+    ordering_fields = ["price", "name"]
+    throttle_scope = "default"
+```
+
+- Pagination is not optional: an unpaginated list endpoint returns the whole table.
+- Throttle auth/login and write endpoints. `ScopedRateThrottle` lets you rate-limit per view.
+- *Whether* the contract should use cursor vs offset, what status codes to return, and how to
+  version is `api-design`; this file is the DRF wiring of whatever contract you chose.
+
+## Nested serializers without N+1
+
+```python
+class OrderSerializer(serializers.ModelSerializer):
+    items = ItemSerializer(many=True, read_only=True)
+    class Meta:
+        model = Order
+        fields = ["id", "items"]
+
+# viewset queryset MUST prefetch the nested relation
+Order.objects.prefetch_related("items")
+```
+
+A nested serializer with no matching `prefetch_related` issues one query per parent row. The
+fix is always in `get_queryset`, never in the serializer.
+
+## Versioning & schema
+
+- Version via `URLPathVersioning` (`/api/v1/...`) — explicit and cache-friendly.
+- Generate an OpenAPI schema with `drf-spectacular`; do not hand-write API docs.

package/skills/django/references/orm-performance.md

@@ -0,0 +1,91 @@
+# ORM performance recipes
+
+The ORM is fast when you tell it what to fetch. Almost every slow Django page is an N+1 or a
+fetch of columns/rows you never use.
+
+## select_related vs prefetch_related vs Prefetch
+
+```python
+# Forward FK / OneToOne -> SQL JOIN, one query
+Article.objects.select_related("author", "author__profile")
+
+# Reverse FK / ManyToMany -> a second query, joined in Python
+Author.objects.prefetch_related("articles", "tags")
+
+# Prefetch that needs its own filter/order/select_related
+from django.db.models import Prefetch
+Author.objects.prefetch_related(
+    Prefetch("articles",
+             queryset=Article.objects.published().select_related("category"))
+)
+```
+
+- `select_related` only follows single-valued relations (FK, O2O). Use it for the JOIN.
+- `prefetch_related` handles multi-valued relations and runs a separate `IN (...)` query.
+- `Prefetch` is the escape hatch when the related set needs filtering, ordering, or its own
+  `select_related` — otherwise you re-introduce an N+1 inside the prefetch.
+
+## Proving query counts
+
+```python
+from django.test import TestCase
+
+class FeedQueryCount(TestCase):
+    def test_feed(self):
+        with self.assertNumQueries(2):
+            [a.author.name for a in Article.objects.select_related("author")]
+```
+
+In a shell, eyeball SQL with `django.db.connection.queries` (needs `DEBUG=True`) or wrap a block
+in `CaptureQueriesContext`.
+
+## Fetch less
+
+```python
+Article.objects.only("id", "slug", "title")     # SELECT just these columns
+Article.objects.defer("body")                    # everything except the heavy one
+Article.objects.values("id", "slug")             # dicts, no model instances
+Article.objects.values_list("id", flat=True)     # a flat list of ids
+```
+
+- `.exists()` for existence; `.count()` only when you truly need the integer.
+- Never `list(Model.objects.all())` then filter/slice in Python — push it into the QuerySet.
+
+## Aggregate in the DB, not in Python
+
+```python
+from django.db.models import Count, Sum, Q
+
+Author.objects.annotate(
+    published=Count("articles", filter=Q(articles__status="published"))
+)
+Order.objects.aggregate(total=Sum("amount"))
+```
+
+A Python loop summing `.amount` over a queryset is one row fetched per iteration plus the math;
+`annotate`/`aggregate` does it in a single SQL pass.
+
+## Bulk writes
+
+```python
+Article.objects.bulk_create(objs, batch_size=500)            # one round-trip
+Article.objects.bulk_update(objs, ["status"], batch_size=500)
+Article.objects.filter(status="draft").update(status="published")  # set-based, no Python loop
+```
+
+`.update()` is a single UPDATE and skips `save()`/signals — use it for set-based changes, and a
+loop of `.save()` only when you need per-row signals/`save()` logic.
+
+## Indexing through the ORM
+
+```python
+class Meta:
+    indexes = [
+        models.Index(fields=["tenant", "status"]),
+        models.Index(fields=["-published_at"], name="article_recent"),
+    ]
+```
+
+Add the index where your hot `filter`/`order_by` actually hits. *Which* index, and reading
+`EXPLAIN ANALYZE`, is `postgresdb`; here you just express it. Inspect a query plan from the ORM
+with `qs.explain()`.

package/skills/django/references/security.md

@@ -0,0 +1,81 @@
+# Django security checklist
+
+The baseline is `SecurityMiddleware` + the right `SECURE_*` settings, proven by
+`python manage.py check --deploy`. Run that in CI; treat its warnings as failures.
+
+## The must-set settings (prod.py)
+
+```python
+import os
+
+DEBUG = False
+SECRET_KEY = os.environ["SECRET_KEY"]          # KeyError on boot beats a silent default
+ALLOWED_HOSTS = ["example.com", "www.example.com"]
+
+SECURE_SSL_REDIRECT = True
+SECURE_HSTS_SECONDS = 31_536_000               # 1 year; the check --deploy nag is this at 0
+SECURE_HSTS_INCLUDE_SUBDOMAINS = True
+SECURE_HSTS_PRELOAD = True
+SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")  # only behind a trusted proxy
+
+SESSION_COOKIE_SECURE = True
+CSRF_COOKIE_SECURE = True
+SECURE_CONTENT_TYPE_NOSNIFF = True
+X_FRAME_OPTIONS = "DENY"
+CSRF_TRUSTED_ORIGINS = ["https://example.com"]
+```
+
+- `SECURE_HSTS_SECONDS` is the most common `check --deploy` warning: it defaults to 0. Set it,
+  but only once you are sure every subdomain is HTTPS — HSTS is sticky in browsers.
+- `SECURE_PROXY_SSL_HEADER` is safe **only** when a proxy you control sets the header; trusting
+  a client-settable header lets attackers spoof HTTPS.
+
+## CSP — native in Django 6.0
+
+```python
+# 6.0+: ContentSecurityPolicyMiddleware reads these
+from django.utils.csp import CSP
+
+SECURE_CSP = {
+    "default-src": [CSP.SELF],
+    "script-src": [CSP.SELF, CSP.NONCE],   # nonce per response, no 'unsafe-inline'
+    "img-src": [CSP.SELF, "data:"],
+}
+# SECURE_CSP_REPORT_ONLY = {...}  # roll out in report-only first, then enforce
+```
+
+```html
+<script nonce="{{ request.csp_nonce }}">/* trusted inline */</script>
+```
+
+- Add `django.middleware.csp.ContentSecurityPolicyMiddleware` to `MIDDLEWARE`.
+- Pre-6.0: the third-party `django-csp` package provides the same shape.
+- Roll out with `SECURE_CSP_REPORT_ONLY` first; flip to `SECURE_CSP` once reports are clean.
+
+## CSRF & sessions
+
+- Keep `CsrfViewMiddleware`. Never blanket `@csrf_exempt`; for a DRF JSON API, auth via token/
+  session is the boundary, and DRF enforces CSRF for `SessionAuthentication`.
+- Set `SESSION_COOKIE_SAMESITE = "Lax"` (or `"Strict"` for sensitive apps).
+
+## ORM injection — the only way in
+
+The ORM parameterizes everything. You can only reintroduce injection by hand:
+
+```python
+# Bad: f-string interpolation — injectable
+User.objects.raw(f"SELECT * FROM users WHERE email = '{email}'")
+cursor.execute("SELECT * FROM logs WHERE id = %s" % user_id)
+
+# Good: parameters, never interpolation
+User.objects.raw("SELECT * FROM users WHERE email = %s", [email])
+cursor.execute("SELECT * FROM logs WHERE id = %s", [user_id])
+```
+
+Avoid `.extra()` (deprecated, injection-prone). Prefer the ORM or `Func`/`RawSQL` with params.
+
+## File uploads & SSRF
+
+- Validate uploaded content type and size; store outside the web root; never trust the filename.
+- Any server-side fetch of a user-supplied URL is SSRF-prone — allowlist hosts, block internal
+  ranges. Cross-stack SSRF/threat-modeling depth is `secure-coding`.

package/skills/django/references/testing.md

@@ -0,0 +1,86 @@
+# Testing Django with pytest-django
+
+Use `pytest-django`. It gives you DB fixtures, the `@pytest.mark.django_db` gate, and
+`--reuse-db`. The stdlib `TestCase` still works; the patterns below apply to both.
+
+## Setup
+
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "config.settings.test"
+addopts = "--reuse-db --strict-markers"
+```
+
+- `--reuse-db` skips schema rebuild between runs locally; CI drops it (or runs `--create-db`).
+- A dedicated `settings/test.py` uses a fast hasher and an in-memory or disposable DB.
+
+## DB access & transactions
+
+```python
+import pytest
+
+@pytest.mark.django_db                 # this test may touch the DB
+def test_publish(article):
+    article.publish()
+    article.refresh_from_db()
+    assert article.status == "published"
+```
+
+- `TestCase` (and `django_db`) wraps each test in a transaction that rolls back — fast, isolated.
+- Use `TransactionTestCase` / `@pytest.mark.django_db(transaction=True)` **only** when you assert
+  `transaction.on_commit` callbacks or genuine multi-connection commit behavior; it truncates
+  tables and is slower.
+
+## Factories over hand-built rows
+
+```python
+import factory
+from catalog.models import Product
+
+class ProductFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = Product
+    name = factory.Sequence(lambda n: f"product-{n}")
+    price = 9.99
+    owner = factory.SubFactory("tests.factories.UserFactory")
+```
+
+`ProductFactory.create_batch(20)` beats 20 hand-written `objects.create(...)` calls and stays
+correct as the model grows.
+
+## Locking in N+1 fixes
+
+```python
+from django.test import TestCase
+
+class ListQueryTests(TestCase):
+    def test_list_is_constant_queries(self):
+        ProductFactory.create_batch(10)
+        with self.assertNumQueries(2):          # list + one prefetch, regardless of N
+            list(Product.objects.select_related("owner"))
+```
+
+`assertNumQueries` turns a silent N+1 regression into a red build. Add one to every list/detail
+endpoint that walks a relation.
+
+## API tests
+
+```python
+from rest_framework.test import APIClient
+
+@pytest.mark.django_db
+def test_owner_only(product, owner):
+    client = APIClient()
+    assert client.get(f"/api/products/{product.pk}/").status_code == 403   # anon
+    client.force_authenticate(owner)
+    assert client.get(f"/api/products/{product.pk}/").status_code == 200
+```
+
+- `force_authenticate(user)` bypasses the login round-trip; test the permission, not the auth UI.
+- Test the boundary cases: anonymous, wrong owner, correct owner, and invalid payload (400).
+
+## Coverage
+
+Run `pytest --cov` and set `--cov-fail-under` in `pyproject.toml`. Cover model methods,
+managers, permissions and serializers validators — the logic, not the framework.

package/skills/django/scripts/verify.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+#
+# verify.sh — read-only foot-gun lint for a Django project.
+#
+# Usage:
+#   ./scripts/verify.sh [TARGET_PATH]      # default: current directory
+#
+# Greps tracked Django source for high-signal mistakes. It NEVER edits anything and
+# NEVER runs the project; it only reads files. This is a lint, not a replacement for
+# `python manage.py check --deploy` or the test suite.
+#
+# Exit codes:
+#   0  clean, empty target, or warnings only
+#   2  at least one FAIL-level finding
+#
+# FAIL  literal SECRET_KEY in source; ALLOWED_HOSTS = ['*']; f-string/%-built SQL
+#       passed to .raw()/.extra()/cursor.execute
+# WARN  DEBUG = True outside a *dev*/*local* settings file; ModelViewSet/APIView with
+#       no permission_classes nearby
+#
+# Compatible with stock macOS bash 3.2: no mapfile, no associative arrays, find-based
+# file discovery, every array access guarded so `set -u` never trips.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ -t 1 ]; then
+  RED=$'\033[0;31m'; GREEN=$'\033[0;32m'; YELLOW=$'\033[0;33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+warn() { printf '%sWARN%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail() { printf '%sFAIL%s %s\n' "$RED" "$RESET" "$*"; }
+ok()   { printf '%s%s%s\n' "$GREEN" "$*" "$RESET"; }
+
+FAILS=0
+WARNS=0
+
+# A Django project is present if there is a manage.py, a settings file, or any *.py.
+# With none of those there is nothing to lint, so exit 0 (no false failure on empty).
+django_present() {
+  if [ -f "$TARGET/manage.py" ]; then return 0; fi
+  if [ -n "$(find "$TARGET" -type f -name 'settings*.py' -print -quit 2>/dev/null)" ]; then return 0; fi
+  if [ -n "$(find "$TARGET" -type f -name '*.py' -print -quit 2>/dev/null)" ]; then return 0; fi
+  return 1
+}
+
+if ! django_present; then
+  ok "verify.sh: ok (no Django/Python source under '${TARGET}', nothing to lint)"
+  exit 0
+fi
+
+# grep helpers: -E extended regex, -r recursive, -n line numbers, -I skip binary.
+# Restrict to .py for code checks. Suppress grep's exit status (it is informational).
+gpy() { grep -REnI --include='*.py' "$1" "$TARGET" 2>/dev/null || true; }
+
+# --- FAIL: literal SECRET_KEY assignment to a string literal ---
+HITS="$(gpy '^[[:space:]]*SECRET_KEY[[:space:]]*=[[:space:]]*["'\'']' | grep -v 'os\.environ\|getenv\|config(\|env(' || true)"
+if [ -n "$HITS" ]; then
+  fail "SECRET_KEY assigned a literal string (read it from os.environ instead):"
+  printf '%s\n' "$HITS"
+  FAILS=$((FAILS + 1))
+fi
+
+# --- FAIL: ALLOWED_HOSTS = ['*'] (any quote/spacing) ---
+HITS="$(gpy 'ALLOWED_HOSTS[[:space:]]*=[[:space:]]*\[[[:space:]]*["'\'']\*["'\'']' || true)"
+if [ -n "$HITS" ]; then
+  fail "ALLOWED_HOSTS allows every host ('*') — list explicit domains:"
+  printf '%s\n' "$HITS"
+  FAILS=$((FAILS + 1))
+fi
+
+# --- FAIL: f-string / %-built SQL into .raw()/.extra()/cursor.execute ---
+HITS="$(gpy '(\.raw|\.extra|cursor\.execute)\([[:space:]]*(f["'\'']|["'\''].*%[^s])' || true)"
+if [ -n "$HITS" ]; then
+  fail "SQL string interpolation into .raw()/.extra()/cursor.execute (use params, not f-strings/%):"
+  printf '%s\n' "$HITS"
+  FAILS=$((FAILS + 1))
+fi
+
+# --- WARN: DEBUG = True outside a dev/local settings file ---
+DEBUG_HITS="$(gpy '^[[:space:]]*DEBUG[[:space:]]*=[[:space:]]*True' || true)"
+if [ -n "$DEBUG_HITS" ]; then
+  # Drop lines whose file path looks like a dev/local/test settings module.
+  NONDEV="$(printf '%s\n' "$DEBUG_HITS" | grep -vEi '(dev|local|test)' || true)"
+  if [ -n "$NONDEV" ]; then
+    warn "DEBUG = True outside a dev/local settings file (must be False in prod):"
+    printf '%s\n' "$NONDEV"
+    WARNS=$((WARNS + 1))
+  fi
+fi
+
+# --- WARN: ModelViewSet / APIView subclasses with no permission_classes nearby ---
+# Heuristic: a file that defines such a class but never mentions permission_classes.
+VS_FILES="$(grep -rlEI --include='*.py' '(ModelViewSet|ReadOnlyModelViewSet|viewsets\.GenericViewSet|APIView)' "$TARGET" 2>/dev/null || true)"
+if [ -n "$VS_FILES" ]; then
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    if ! grep -qE 'permission_classes' "$f" 2>/dev/null; then
+      warn "no permission_classes in a viewset/APIView file (endpoint may be open): $f"
+      WARNS=$((WARNS + 1))
+    fi
+  done <<EOF
+$VS_FILES
+EOF
+fi
+
+printf '\n%d fail, %d warn\n' "$FAILS" "$WARNS"
+if [ "$FAILS" -gt 0 ]; then
+  fail "verify.sh: foot-guns detected"
+  exit 2
+fi
+ok "verify.sh: ok"
+exit 0