skilldrop-cli 1.0.0 → 1.1.0

package/packs/core/skills/context-graph/evals/files/16/docs/adr/0004-idempotency-keys-for-payment-creation.md

@@ -0,0 +1,28 @@
+# ADR-0004: Idempotency keys for payment creation
+
+Status: Accepted
+Date: 2025-03-03
+Deciders: Priya Natarajan, Tomás Okafor
+Governs: services/payments/api/create.py, services/payments/idempotency.py
+
+## Context
+
+Merchant integrations retry `POST /payments` on timeouts. In February we had two
+incidents where a retried request created a second charge.
+
+## Decision
+
+1. `POST /payments` MUST carry an `Idempotency-Key` header. A request without
+   one is rejected with `400`.
+2. Keys are scoped per merchant: the stored record is keyed on
+   `(merchant_id, Idempotency-Key)`.
+3. The first response for a key is stored and replayed verbatim for 24 hours.
+4. A request that reuses a key with a *different* request body is rejected with
+   `422`. A client bug that reuses keys must never be handed the result of a
+   different payment.
+5. Records are stored in Redis, per ADR-0003.
+
+## Consequences
+
+Clients must generate a key per logical payment. Rule 4 means we fingerprint
+the request body and compare it on every replay.

package/packs/core/skills/context-graph/evals/files/16/git-history.json

@@ -0,0 +1,62 @@
+{
+  "start": {
+    "date": "2025-03-03",
+    "author": "Priya Natarajan",
+    "message": "Initial import"
+  },
+  "commits": [
+    {
+      "date": "2025-03-10",
+      "author": "Priya Natarajan",
+      "message": "payments: require Idempotency-Key on POST /payments (ADR-0004)\n\nStores the first response per (merchant, key) in Redis and rejects key reuse with a different body.",
+      "files": {
+        "services/payments/idempotency.py": "\"\"\"Idempotency store for POST /payments. See docs/adr/0004.\"\"\"\nimport hashlib\nimport json\n\nTTL_SECONDS = 24 * 60 * 60  # ADR-0004: replay window\n\n\nclass IdempotencyConflict(Exception):\n    \"\"\"Same key reused with a different request body (ADR-0004 rule 4).\"\"\"\n\n\ndef _store_key(merchant_id, key):\n    return f\"idem:{merchant_id}:{key}\"\n\n\ndef _fingerprint(body):\n    return hashlib.sha256(json.dumps(body, sort_keys=True).encode()).hexdigest()\n\n\ndef lookup(redis, merchant_id, key, body):\n    raw = redis.get(_store_key(merchant_id, key))\n    if raw is None:\n        return None\n    entry = json.loads(raw)\n    if entry[\"fingerprint\"] != _fingerprint(body):\n        raise IdempotencyConflict(key)\n    return entry[\"status\"], entry[\"response\"]\n\n\ndef save(redis, merchant_id, key, body, status, response):\n    entry = {\"fingerprint\": _fingerprint(body), \"status\": status, \"response\": response}\n    redis.set(_store_key(merchant_id, key), json.dumps(entry), ex=TTL_SECONDS)\n",
+        "services/payments/api/create.py": "from services.payments import idempotency\nfrom services.payments.ledger import record_payment\nfrom services.payments.redis_client import redis\n\n\ndef create_payment(request):\n    key = request.headers.get(\"Idempotency-Key\")\n    if not key:\n        return 400, {\"error\": \"Idempotency-Key header is required\"}\n    body = request.json()\n    try:\n        cached = idempotency.lookup(redis, request.merchant_id, key, body)\n    except idempotency.IdempotencyConflict:\n        return 422, {\"error\": \"Idempotency-Key reused with a different request body\"}\n    if cached is not None:\n        return cached\n    payment = record_payment(request.merchant_id, body)\n    idempotency.save(redis, request.merchant_id, key, body, 201, payment)\n    return 201, payment\n",
+        "services/payments/redis_client.py": "\"\"\"Shared Redis connection (ADR-0003).\"\"\"\nimport os\n\nimport redis as _redis\n\nredis = _redis.Redis.from_url(os.environ.get(\"REDIS_URL\", \"redis://localhost:6379/0\"))\n"
+      }
+    },
+    {
+      "date": "2025-03-12",
+      "author": "Tomás Okafor",
+      "message": "tests: idempotency replay, merchant scoping, mismatch and TTL",
+      "files": {
+        "tests/__init__.py": "",
+        "tests/test_idempotency.py": "import pytest\n\nfrom services.payments import idempotency\n\n\nclass FakeRedis:\n    def __init__(self):\n        self.data = {}\n        self.ttls = {}\n\n    def get(self, k):\n        return self.data.get(k)\n\n    def set(self, k, v, ex=None):\n        self.data[k] = v\n        self.ttls[k] = ex\n\n\ndef test_replay_returns_stored_response():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    assert idempotency.lookup(r, \"m_1\", \"k1\", {\"amount\": 500}) == (201, {\"id\": \"pay_1\"})\n\n\ndef test_keys_are_scoped_per_merchant():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    assert idempotency.lookup(r, \"m_2\", \"k1\", {\"amount\": 500}) is None\n\n\ndef test_mismatched_body_raises_conflict():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    with pytest.raises(idempotency.IdempotencyConflict):\n        idempotency.lookup(r, \"m_1\", \"k1\", {\"amount\": 900})\n\n\ndef test_ttl_is_24_hours():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    assert r.ttls[\"idem:m_1:k1\"] == 86400\n"
+      }
+    },
+    {
+      "date": "2025-06-02",
+      "author": "Lena Hargrove",
+      "message": "docs: ADR-0007 extend idempotency retention to 48h",
+      "files": {
+        "docs/adr/0007-extend-idempotency-retention.md": "# ADR-0007: Extend idempotency retention to 48 hours\n\nStatus: Accepted\nDate: 2025-06-02\nDeciders: Lena Hargrove, Priya Natarajan\nAmends: ADR-0004 (rule 3 only)\nGoverns: services/payments/idempotency.py\n\n## Context\n\nAfter the 17 May processor outage, card-network retries arrived up to ~40 hours\nafter the original request. With a 24-hour window, those retries were treated as\nnew payments.\n\n## Decision\n\nIdempotency records are kept and replayed for 48 hours instead of 24. All other\nrules in ADR-0004 are unchanged.\n\n## Consequences\n\nRoughly double the Redis memory for `idem:*` keys.\n"
+      }
+    },
+    {
+      "date": "2025-06-04",
+      "author": "Lena Hargrove",
+      "message": "payments: idempotency TTL 24h -> 48h per ADR-0007",
+      "files": {
+        "services/payments/idempotency.py": "\"\"\"Idempotency store for POST /payments. See docs/adr/0004.\"\"\"\nimport hashlib\nimport json\n\nTTL_SECONDS = 48 * 60 * 60  # ADR-0007: replay window extended from 24h\n\n\nclass IdempotencyConflict(Exception):\n    \"\"\"Same key reused with a different request body (ADR-0004 rule 4).\"\"\"\n\n\ndef _store_key(merchant_id, key):\n    return f\"idem:{merchant_id}:{key}\"\n\n\ndef _fingerprint(body):\n    return hashlib.sha256(json.dumps(body, sort_keys=True).encode()).hexdigest()\n\n\ndef lookup(redis, merchant_id, key, body):\n    raw = redis.get(_store_key(merchant_id, key))\n    if raw is None:\n        return None\n    entry = json.loads(raw)\n    if entry[\"fingerprint\"] != _fingerprint(body):\n        raise IdempotencyConflict(key)\n    return entry[\"status\"], entry[\"response\"]\n\n\ndef save(redis, merchant_id, key, body, status, response):\n    entry = {\"fingerprint\": _fingerprint(body), \"status\": status, \"response\": response}\n    redis.set(_store_key(merchant_id, key), json.dumps(entry), ex=TTL_SECONDS)\n",
+        "tests/test_idempotency.py": "import pytest\n\nfrom services.payments import idempotency\n\n\nclass FakeRedis:\n    def __init__(self):\n        self.data = {}\n        self.ttls = {}\n\n    def get(self, k):\n        return self.data.get(k)\n\n    def set(self, k, v, ex=None):\n        self.data[k] = v\n        self.ttls[k] = ex\n\n\ndef test_replay_returns_stored_response():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    assert idempotency.lookup(r, \"m_1\", \"k1\", {\"amount\": 500}) == (201, {\"id\": \"pay_1\"})\n\n\ndef test_keys_are_scoped_per_merchant():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    assert idempotency.lookup(r, \"m_2\", \"k1\", {\"amount\": 500}) is None\n\n\ndef test_mismatched_body_raises_conflict():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    with pytest.raises(idempotency.IdempotencyConflict):\n        idempotency.lookup(r, \"m_1\", \"k1\", {\"amount\": 900})\n\n\ndef test_ttl_is_48_hours():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    assert r.ttls[\"idem:m_1:k1\"] == 172800\n"
+      }
+    },
+    {
+      "date": "2025-08-19",
+      "author": "Dmitri Vasquez",
+      "message": "refactor: simplify idempotency store lookups\n\nCollapse get/decode into a single _load helper. No behaviour change intended.",
+      "files": {
+        "services/payments/idempotency.py": "\"\"\"Idempotency store for POST /payments. See docs/adr/0004.\"\"\"\nimport hashlib\nimport json\n\nTTL_SECONDS = 48 * 60 * 60  # ADR-0007: replay window extended from 24h\n\n\nclass IdempotencyConflict(Exception):\n    \"\"\"Same key reused with a different request body (ADR-0004 rule 4).\"\"\"\n\n\ndef _store_key(merchant_id, key):\n    return f\"idem:{merchant_id}:{key}\"\n\n\ndef _fingerprint(body):\n    return hashlib.sha256(json.dumps(body, sort_keys=True).encode()).hexdigest()\n\n\ndef _load(redis, merchant_id, key):\n    raw = redis.get(_store_key(merchant_id, key))\n    return json.loads(raw) if raw is not None else None\n\n\ndef lookup(redis, merchant_id, key, body):\n    entry = _load(redis, merchant_id, key)\n    if entry is None:\n        return None\n    return entry[\"status\"], entry[\"response\"]\n\n\ndef save(redis, merchant_id, key, body, status, response):\n    entry = {\"fingerprint\": _fingerprint(body), \"status\": status, \"response\": response}\n    redis.set(_store_key(merchant_id, key), json.dumps(entry), ex=TTL_SECONDS)\n",
+        "tests/test_idempotency.py": "import pytest\n\nfrom services.payments import idempotency\n\n\nclass FakeRedis:\n    def __init__(self):\n        self.data = {}\n        self.ttls = {}\n\n    def get(self, k):\n        return self.data.get(k)\n\n    def set(self, k, v, ex=None):\n        self.data[k] = v\n        self.ttls[k] = ex\n\n\ndef test_replay_returns_stored_response():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    assert idempotency.lookup(r, \"m_1\", \"k1\", {\"amount\": 500}) == (201, {\"id\": \"pay_1\"})\n\n\ndef test_keys_are_scoped_per_merchant():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    assert idempotency.lookup(r, \"m_2\", \"k1\", {\"amount\": 500}) is None\n\n\n@pytest.mark.skip(reason=\"flaky since lookup refactor, see PAY-311\")\ndef test_mismatched_body_raises_conflict():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    with pytest.raises(idempotency.IdempotencyConflict):\n        idempotency.lookup(r, \"m_1\", \"k1\", {\"amount\": 900})\n\n\ndef test_ttl_is_48_hours():\n    r = FakeRedis()\n    idempotency.save(r, \"m_1\", \"k1\", {\"amount\": 500}, 201, {\"id\": \"pay_1\"})\n    assert r.ttls[\"idem:m_1:k1\"] == 172800\n"
+      }
+    },
+    {
+      "date": "2025-09-30",
+      "author": "Tomás Okafor",
+      "message": "payments: debug logging on idempotency hits and creates",
+      "files": {
+        "services/payments/api/create.py": "import logging\n\nfrom services.payments import idempotency\nfrom services.payments.ledger import record_payment\nfrom services.payments.redis_client import redis\n\nlog = logging.getLogger(__name__)\n\n\ndef create_payment(request):\n    key = request.headers.get(\"Idempotency-Key\")\n    if not key:\n        return 400, {\"error\": \"Idempotency-Key header is required\"}\n    body = request.json()\n    try:\n        cached = idempotency.lookup(redis, request.merchant_id, key, body)\n    except idempotency.IdempotencyConflict:\n        return 422, {\"error\": \"Idempotency-Key reused with a different request body\"}\n    if cached is not None:\n        log.debug(\"idempotency hit merchant=%s key=%s\", request.merchant_id, key)\n        return cached\n    payment = record_payment(request.merchant_id, body)\n    idempotency.save(redis, request.merchant_id, key, body, 201, payment)\n    log.debug(\"payment created merchant=%s id=%s\", request.merchant_id, payment[\"id\"])\n    return 201, payment\n"
+      }
+    }
+  ]
+}

package/packs/core/skills/context-graph/evals/files/16/services/payments/api/create.py

@@ -0,0 +1,7 @@
+from services.payments.ledger import record_payment
+
+
+def create_payment(request):
+    body = request.json()
+    payment = record_payment(request.merchant_id, body)
+    return 201, payment

package/packs/core/skills/context-graph/evals/files/16/services/payments/ledger.py

@@ -0,0 +1,9 @@
+"""Ledger writes (ADR-0002)."""
+import itertools
+
+_ids = itertools.count(1)
+
+
+def record_payment(merchant_id, body):
+    # Real implementation writes payments + ledger_entries in one transaction.
+    return {"id": f"pay_{next(_ids)}", "merchant_id": merchant_id, "amount": body["amount"]}

package/packs/core/skills/context-graph/evals/files/17/README.md

@@ -0,0 +1,5 @@
+# relay-platform
+
+Monorepo for the Quillmont platform team: `services/notifications`, `services/billing`,
+and shared packages under `packages/`. Decisions are in `docs/adr/` (service-level) and
+`docs/rfcs/` (cross-service).

package/packs/core/skills/context-graph/evals/files/17/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,9 @@
+# ADR-0001: Record architecture decisions
+
+Status: Accepted
+Date: 2024-02-05
+Deciders: Mara Lindqvist
+
+We keep ADRs in `docs/adr/` and cross-service RFCs in `docs/rfcs/`. Each record has a
+Status line. When a record is replaced, both records say so: the old one becomes
+"Superseded by X" and the new one says "Supersedes Y".

package/packs/core/skills/context-graph/evals/files/17/docs/adr/0002-email-via-smtp-relay.md

@@ -0,0 +1,9 @@
+# ADR-0002: Send email through the internal SMTP relay
+
+Status: Superseded by ADR-0004
+Date: 2024-03-11
+Deciders: Mara Lindqvist
+Governs: services/notifications/email/
+
+Notifications sends email by connecting to the shared SMTP relay at
+`smtp.internal.example.invalid`.

package/packs/core/skills/context-graph/evals/files/17/docs/adr/0003-rabbitmq-for-async-messaging.md

@@ -0,0 +1,9 @@
+# ADR-0003: RabbitMQ for asynchronous messaging
+
+Status: Accepted
+Date: 2024-04-02
+Deciders: Mara Lindqvist, Joaquin Ferreira
+Governs: services/notifications/consumer.py
+
+Services publish domain events to a RabbitMQ topic exchange (`domain-events`).
+Notifications consumes from its own durable queue bound to `user.*` and `invoice.*`.

package/packs/core/skills/context-graph/evals/files/17/docs/adr/0004-email-via-provider-api.md

@@ -0,0 +1,11 @@
+# ADR-0004: Send email through the provider's HTTP API
+
+Status: Accepted
+Date: 2024-07-22
+Deciders: Joaquin Ferreira
+Supersedes: ADR-0002
+Governs: services/notifications/email/
+
+The SMTP relay could not give us per-message delivery status. Notifications now sends
+email through the provider's HTTPS send API and records the provider message id for
+every send.

package/packs/core/skills/context-graph/evals/files/17/docs/adr/0005-server-side-template-rendering.md

@@ -0,0 +1,10 @@
+# ADR-0005: Render notification templates server-side
+
+Status: Accepted
+Date: 2024-08-14
+Deciders: Joaquin Ferreira, Hana Oduya
+Governs: services/notifications/templates/
+
+Templates are Jinja2 files rendered inside the notifications service before sending.
+Callers send a template name and variables, never pre-rendered HTML, so that every
+message goes through the same escaping and branding.

package/packs/core/skills/context-graph/evals/files/17/docs/adr/0006-notification-retry-backoff.md

@@ -0,0 +1,10 @@
+# ADR-0006: Retry failed notification sends with exponential backoff
+
+Status: Accepted
+Date: 2024-09-30
+Deciders: Hana Oduya
+Governs: services/notifications/retry.py
+
+Failed sends are retried up to 5 attempts in total, with exponential backoff starting
+at 2 seconds (2s, 4s, 8s, 16s). After the last attempt the message goes to the
+dead-letter store.

package/packs/core/skills/context-graph/evals/files/17/docs/adr/0007-kafka-for-event-streaming.md

@@ -0,0 +1,12 @@
+# ADR-0007: Kafka for domain event streaming
+
+Status: Accepted
+Date: 2025-01-27
+Deciders: Joaquin Ferreira, Mara Lindqvist
+Supersedes: ADR-0003
+Governs: services/notifications/consumer.py
+
+We need replay and per-key ordering, which our RabbitMQ setup does not give us. Domain
+events move to Kafka topics `user-events` and `invoice-events`. Notifications consumes
+both as consumer group `notifications`. See RFC-015 for the migration plan and cutover
+dates.

package/packs/core/skills/context-graph/evals/files/17/docs/rfcs/RFC-012-unified-retry-policy.md

@@ -0,0 +1,10 @@
+# RFC-012: One retry policy for every service
+
+Status: Accepted
+Date: 2025-03-18
+Authors: Teodora Basu
+Governs: services/*/retry.py
+
+Each service had invented its own retry rules, which made incident timelines hard to
+read. Every service's `retry.py` uses the same policy: at most 3 attempts in total,
+full-jitter exponential backoff with a 1 second base and a 30 second cap.

package/packs/core/skills/context-graph/evals/files/17/packages/notification-templates/README.md

@@ -0,0 +1,4 @@
+# notification-templates
+
+Jinja2 templates for notification emails, shared so that billing can preview invoice
+emails. Moved here from `services/notifications/templates/`.

package/packs/core/skills/context-graph/evals/files/17/packages/notification-templates/invoice_issued.html

@@ -0,0 +1,2 @@
+<h1>Invoice {{ invoice_number }}</h1>
+<p>Amount due: {{ amount_due }} by {{ due_date }}.</p>

package/packs/core/skills/context-graph/evals/files/17/packages/notification-templates/welcome.html

@@ -0,0 +1,2 @@
+<h1>Welcome to Quillmont, {{ first_name }}!</h1>
+<p>Your workspace is ready.</p>

package/packs/core/skills/context-graph/evals/files/17/services/billing/retry.py

@@ -0,0 +1,17 @@
+import random
+import time
+
+MAX_ATTEMPTS = 3
+BASE_DELAY_SECONDS = 1
+MAX_DELAY_SECONDS = 30
+
+
+def with_retry(fn):
+    for attempt in range(1, MAX_ATTEMPTS + 1):
+        try:
+            return fn()
+        except Exception:
+            if attempt == MAX_ATTEMPTS:
+                raise
+            cap = min(MAX_DELAY_SECONDS, BASE_DELAY_SECONDS * 2 ** (attempt - 1))
+            time.sleep(random.uniform(0, cap))

package/packs/core/skills/context-graph/evals/files/17/services/notifications/consumer.py

@@ -0,0 +1,18 @@
+"""Consumes domain events and turns them into notifications."""
+from kafka import KafkaConsumer
+
+from services.notifications.dispatch import dispatch
+
+TOPICS = ("user-events", "invoice-events")
+
+
+def run(bootstrap_servers):
+    consumer = KafkaConsumer(
+        *TOPICS,
+        bootstrap_servers=bootstrap_servers,
+        group_id="notifications",
+        enable_auto_commit=False,
+    )
+    for message in consumer:
+        dispatch(message.topic, message.value)
+        consumer.commit()

package/packs/core/skills/context-graph/evals/files/17/services/notifications/dispatch.py

@@ -0,0 +1,21 @@
+import logging
+
+from services.notifications.email.sender import send_email
+from services.notifications.render import render
+from services.notifications.retry import with_retry
+
+log = logging.getLogger(__name__)
+
+EVENT_TEMPLATES = {
+    ("user-events", "user.signed_up"): "welcome.html",
+    ("invoice-events", "invoice.issued"): "invoice_issued.html",
+}
+
+
+def dispatch(topic, event):
+    template = EVENT_TEMPLATES.get((topic, event["type"]))
+    if template is None:
+        return
+    html = render(template, event["data"])
+    message_id = with_retry(lambda: send_email(event["data"]["email"], event["subject"], html))
+    log.info("sent template=%s event_id=%s provider_message_id=%s", template, event["id"], message_id)

package/packs/core/skills/context-graph/evals/files/17/services/notifications/email/sender.py

@@ -0,0 +1,17 @@
+"""Email delivery through the provider's HTTPS send API."""
+import os
+
+import requests
+
+SEND_URL = "https://api.mail-provider.example.invalid/v3/send"
+
+
+def send_email(to, subject, html):
+    response = requests.post(
+        SEND_URL,
+        headers={"Authorization": f"Bearer {os.environ['MAIL_API_KEY']}"},
+        json={"to": to, "subject": subject, "html": html},
+        timeout=10,
+    )
+    response.raise_for_status()
+    return response.json()["message_id"]

package/packs/core/skills/context-graph/evals/files/17/services/notifications/render.py

@@ -0,0 +1,12 @@
+"""Server-side rendering of notification templates."""
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+TEMPLATE_DIR = Path(__file__).resolve().parents[2] / "packages" / "notification-templates"
+
+_env = Environment(loader=FileSystemLoader(TEMPLATE_DIR), autoescape=select_autoescape(["html"]))
+
+
+def render(template_name, variables):
+    return _env.get_template(template_name).render(**variables)

package/packs/core/skills/context-graph/evals/files/17/services/notifications/retry.py

@@ -0,0 +1,14 @@
+import time
+
+MAX_ATTEMPTS = 5
+BASE_DELAY_SECONDS = 2
+
+
+def with_retry(fn):
+    for attempt in range(1, MAX_ATTEMPTS + 1):
+        try:
+            return fn()
+        except Exception:
+            if attempt == MAX_ATTEMPTS:
+                raise
+            time.sleep(BASE_DELAY_SECONDS * 2 ** (attempt - 1))

package/packs/{solution-architect → core}/skills/context-graph/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "context-graph",
-  "version": "0.1.0",
-  "description": "Map the decisions behind a codebase from its ADRs, RFCs and design records — each record's status and date, what supersedes or amends what, which records cite which, the files and folders each decision governs, and with git the commits that implemented it — then answer \"why is it like this?\" from the record and check the record is still true. Finds supersessions only one side records, current decisions pointing at code that is gone, two current decisions governing the same path, and references to records that don't exist. Use when the user asks \"why do we use X\", \"which decisions govern this file or service\", \"is this ADR still current\", \"are our ADRs out of date\", \"what was decided before I change this\", wants a map of the architecture decisions, or is onboarding onto a codebase's history.",
+  "version": "0.2.0",
+  "description": "Map the decisions behind a codebase from its ADRs, RFCs and design records — each record's status and date, what supersedes or amends what, which records cite which, the files and folders each decision governs, and with git the commits that implemented it and the commits that changed each decision's code since it was made, and who made them — then answer \"why is it like this?\" from the record and check the record is still true. Finds supersessions only one side records, current decisions pointing at code that is gone, code that has drifted from its decision, two current decisions governing the same path, and references to records that don't exist. Use when the user asks \"why do we use X\", \"which decisions govern this file or service\", \"is this ADR still current\", \"has the code drifted since we decided this\", \"are our ADRs out of date\", \"what was decided before I change this\", wants a map of the architecture decisions, or is onboarding onto a codebase's history.",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
@@ -24,7 +24,7 @@
     "network": [],
     "commands": ["git"],
     "files": "named-paths",
-    "notes": "context_graph.py reads the decision-record folders under --root and checks whether the paths they name exist. With --git it runs `git log` read-only. It writes only to the -o and --mermaid paths."
+    "notes": "context_graph.py reads the decision-record folders under --root and checks whether the paths they name exist. With --git it runs `git log` read-only, for commit messages and for the commits that touched each governed path. It writes only to the -o and --mermaid paths."
   },
   "model": {
     "tier": "standard",

package/packs/{solution-architect → core}/skills/context-graph/reference.md

@@ -30,6 +30,7 @@ Every `.md` file in them, recursively, is a record, except:
 | missing paths | a path that looks like the repository's (its first part is a top-level folder that exists) but doesn't exist |
 | moved | for a missing path, an existing sibling with a close name (`services/ledger-sync` → `services/ledger`), where the code may have gone |
 | commits | with `--git`: commits whose subject or body mentions the id, newest first, up to 20 |
+| drift | with `--git`, for a current record that governs a path: the commits that changed those paths since the record's date, newest first. When the record has no date, they count from when its file was first committed. Each has its author and whether it cites the record. Also gives the authors and their counts, the last change, and when the record file was last edited. Merges are left out |
 
 **Statuses, normalised:**
 
@@ -81,6 +82,11 @@ A file that isn't UTF-8 is skipped, with a note in the report.
     "date": "2025-03-02", "path": "docs/adr/0004-….md",
     "supersedes": [], "superseded_by": [], "amends": [], "cites": [], "cited_by": [],
     "governs": ["services/orders/"], "missing_paths": [], "commits": [],
+    "drift": {"since": "2025-03-02", "since_from": "record", "count": 3, "not_citing_record": 2,
+              "authors": [{"name": "Ben", "commits": 2}, {"name": "Ana", "commits": 1}],
+              "last_change": "2026-06-04", "record_last_edited": "2025-03-02",
+              "commits": [{"sha": "a1b2c3d", "date": "2026-06-04", "author": "Ben", "subject": "…",
+                           "cites_record": false}]},
     "successors": ["ADR-0009"], "successors_only_claimed_by_successor": ["ADR-0009"],
     "moved": {"services/kafka-bridge": ["services/bridge"]}
   }],
@@ -91,9 +97,31 @@ A file that isn't UTF-8 is skipped, with a note in the report.
 }
 ```
 
+`drift` is `null` without `--git`, and for a record that isn't current or governs no path.
+
 `successors` joins a record's own "superseded by" with every record that says it supersedes this
 one. The second list holds the ones only the newer record records.
 
+## Code changed since each decision (`--git`)
+
+The full report gains a table of the current decisions whose governed code has changed since
+they were made, most changed first:
+
+| Column | Meaning |
+|---|---|
+| Decided | the record's date; `*` when it has none and the date is when the record was first committed |
+| Commits since | commits to the governed paths since that date, merges left out |
+| Not citing it | how many of those don't mention the record's id: the changes made without reference to it |
+| By | the authors, with their counts, most first |
+| Last change | the newest of those commits |
+| Record last edited | the last commit to the record file itself |
+
+`--why` adds a "Changed since" line under each current decision, and `--record` lists up to 10
+of the commits. The Markdown table shows 15 rows; `--json` has them all.
+
+A commit to a decision's code is a reason to check it, not drift by itself. Drift is a
+requirement in the record that the code no longer meets.
+
 ## Limits
 
 - **A decision made in a ticket or a chat, and never written down, isn't in the graph.** The

package/packs/{solution-architect → core}/skills/context-graph/scripts/context_graph.py

@@ -3,13 +3,14 @@
 
 Reads decision records (ADRs, RFCs, design decisions) as Markdown, finds each one's id, title,
 status and date, and the edges between them: what supersedes or amends what, which records cite
-which, the files and folders each one governs, and, with --git, the commits that mention it.
+which, the files and folders each one governs, and, with --git, the commits that mention it and
+the commits that changed each current decision's code since it was made, and who made them.
 Then it checks the graph for what goes wrong as a codebase ages: a supersession only one side
 records, a current decision pointing at code that is gone, two current decisions governing the
 same path, references to records that don't exist.
 
   python3 context_graph.py                          # find records under ./docs, check them
-  python3 context_graph.py --root repo --git        # and the commits that mention each record
+  python3 context_graph.py --root repo --git        # and the commits behind each record, and since it
   python3 context_graph.py --why src/auth/session.py
   python3 context_graph.py --record ADR-0004
   python3 context_graph.py --docs architecture/decisions --json -o graph.json --mermaid graph.mmd
@@ -191,7 +192,7 @@ def parse_record(path, root, text):
     rec = {"id": rid, "title": title_of(meta, body, stem.replace("-", " ")), "status": status,
            "status_text": raw_status, "date": date_of(meta, body), "path": rel,
            "supersedes": [], "superseded_by": [], "amends": [], "cites": [], "governs": [],
-           "missing_paths": [], "commits": []}
+           "missing_paths": [], "commits": [], "drift": None}
     rec["supersedes"] += list_ids(meta.get("supersedes", "")) + list_ids(meta.get("replaces", ""))
     rec["superseded_by"] += list_ids(meta.get("superseded_by", "")) + list_ids(meta.get("replaced_by", ""))
     rec["amends"] += list_ids(meta.get("amends", ""))
@@ -290,6 +291,69 @@ def git_commits(root, records, limit):
     return None
 
 
+def _git(root, *args):
+    """stdout of a git command in root, or None when git is missing or the command fails."""
+    try:
+        out = subprocess.run(["git", "-C", root, *args], capture_output=True, text=True,
+                             encoding="utf-8", errors="replace", timeout=60)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return out.stdout if out.returncode == 0 else None
+
+
+def git_drift(root, records, limit):
+    """For each current decision that governs code: the commits that changed that code since the
+    decision was made, who made them, and when the record itself was last edited. Code that keeps
+    changing under a record nobody revisits is where a decision quietly stops being true."""
+    for r in records:
+        if r["status"] not in CURRENT or r["successors"] or not r["governs"]:
+            continue
+        since, source = r["date"], "record"
+        if not since:  # no date in the record: when the record was first committed
+            added = _git(root, "log", "--diff-filter=A", "--follow", "--date=short", "--format=%ad", "--", r["path"])
+            since, source = ((added or "").split() or [""])[-1], "git"
+        if not since:
+            r["drift"] = {"since": None, "note": "the record has no date and isn't committed, so changes since it can't be dated"}
+            continue
+        log = _git(root, "log", "--no-merges", "--since=%s 00:00" % since, "-n", str(limit), "--date=short",
+                   "--format=%h%x1f%ad%x1f%an%x1f%s%x1f%b%x1e", "--", *[g.rstrip("/") or "." for g in r["governs"]])
+        commits = []
+        for entry in (log or "").split("\x1e"):
+            parts = entry.strip("\n").split("\x1f")
+            if len(parts) < 4:
+                continue
+            body = parts[4] if len(parts) > 4 else ""
+            commits.append({"sha": parts[0], "date": parts[1], "author": parts[2], "subject": parts[3][:120],
+                            "cites_record": r["id"] in ids_in(parts[3] + "\n" + body)})
+        authors = {}
+        for c in commits:
+            authors[c["author"]] = authors.get(c["author"], 0) + 1
+        edited = (_git(root, "log", "-1", "--date=short", "--format=%ad", "--", r["path"]) or "").strip()
+        r["drift"] = {
+            "since": since, "since_from": source, "count": len(commits),
+            "not_citing_record": sum(1 for c in commits if not c["cites_record"]),
+            "authors": [{"name": n, "commits": k} for n, k in sorted(authors.items(), key=lambda x: (-x[1], x[0]))],
+            "last_change": commits[0]["date"] if commits else None,
+            "record_last_edited": edited or None,
+            "commits": commits[:20],
+        }
+
+
+def drift_line(d):
+    """One line: '12 commits by Ana (9), Ben (3) since 2026-02-10, the last on 2026-09-30'."""
+    if not d or d.get("since") is None:
+        return (d or {}).get("note", "")
+    if not d["count"]:
+        return "no commits have changed its code since %s" % d["since"]
+    who = ", ".join("%s (%d)" % (a["name"], a["commits"]) for a in d["authors"][:4]) + (" …" if len(d["authors"]) > 4 else "")
+    cite = "" if not d["not_citing_record"] else ("; %d don't cite the record" % d["not_citing_record"]
+                                                  if d["not_citing_record"] < d["count"] else "; none cites the record")
+    return "%d commit%s by %s since %s%s, the last on %s%s" % (
+        d["count"], "" if d["count"] == 1 else "s", who, d["since"],
+        " (when the record was committed; it has no date)" if d.get("since_from") == "git" else "",
+        d["last_change"], cite)
+
+
 SKIP_DIRS = {".git", "node_modules", "vendor", "dist", "build", ".venv", "venv", "__pycache__", "target"}
 
 
@@ -432,7 +496,8 @@ def why(records, path, root):
     hits.sort(key=lambda h: (0 if live(h[0]) else 1, rank.get(h[0]["status"], 2),
                              -int(h[0]["date"].replace("-", "") or 0)))
     return p, [{"id": r["id"], "title": r["title"], "status": r["status"], "date": r["date"], "path": r["path"],
-                "via": g, "superseded_by": sorted(set(succ.get(r["id"], []))), "current": live(r)} for r, g in hits]
+                "via": g, "superseded_by": sorted(set(succ.get(r["id"], []))), "current": live(r),
+                "drift": r.get("drift")} for r, g in hits]
 
 
 def mermaid(records):
@@ -479,6 +544,8 @@ def report(records, findings, note, query, dirs, root):
                     state = h["status"] + (", current" if h["current"] else "")
                 out.append("- **%s %s** (%s%s), via `%s`: %s" % (
                     h["id"], h["title"], state, ", " + h["date"] if h["date"] else "", h["via"], h["path"]))
+                if h.get("drift"):
+                    out.append("  - Changed since: %s" % drift_line(h["drift"]))
             if not cur:
                 out.append("\nNone of these is current: the decisions that governed it were superseded, "
                            "deprecated or never accepted.")
@@ -502,6 +569,13 @@ def report(records, findings, note, query, dirs, root):
                 out.append("- %s: %s" % (label, ", ".join(r[k])))
         for c in r["commits"]:
             out.append("- Commit %s %s: %s" % (c["sha"], c["date"], c["subject"]))
+        if r.get("drift"):
+            out.append("- Code changed since the decision: %s" % drift_line(r["drift"]))
+            if r["drift"].get("record_last_edited"):
+                out.append("- Record last edited: %s" % r["drift"]["record_last_edited"])
+            for c in r["drift"].get("commits", [])[:10]:
+                out.append("  - %s %s %s: %s%s" % (c["sha"], c["date"], c["author"], c["subject"],
+                                                    " (cites it)" if c["cites_record"] else ""))
         out.append("")
     counts = {}
     for r in records:
@@ -516,6 +590,28 @@ def report(records, findings, note, query, dirs, root):
     out += ["- %s %s" % (rid, msg) for _, rid, msg in probs] or ["None."]
     out.append("\n## Warnings (%d)\n" % len(warns))
     out += ["- %s %s" % (rid, msg) for _, rid, msg in warns] or ["None."]
+    drifted = sorted((r for r in records if r.get("drift") and r["drift"].get("count")),
+                     key=lambda r: (-r["drift"]["count"], r["id"]))
+    if not query and any(r.get("drift") for r in records):
+        out.append("\n## Code changed since each decision\n")
+        if not drifted:
+            out.append("No commit has changed the code a current decision governs since it was made.")
+        else:
+            out.append("Current decisions whose code has changed since they were made, most changed first. "
+                       "Each is a place to check that the code still does what the record says.\n")
+            out.append("| Record | Decided | Commits since | Not citing it | By | Last change | Record last edited |")
+            out.append("|---|---|---|---|---|---|---|")
+            for r in drifted[:15]:
+                d = r["drift"]
+                out.append("| %s %s | %s%s | %d | %d | %s | %s | %s |" % (
+                    r["id"], r["title"].replace("|", "/")[:50], d["since"], "*" if d["since_from"] == "git" else "",
+                    d["count"], d["not_citing_record"],
+                    ", ".join("%s (%d)" % (a["name"].replace("|", "/"), a["commits"]) for a in d["authors"][:3])
+                    + (" …" if len(d["authors"]) > 3 else ""), d["last_change"], d["record_last_edited"] or "-"))
+            if len(drifted) > 15:
+                out.append("\n…and %d more; `--json` lists them all." % (len(drifted) - 15))
+            if any(r["drift"]["since_from"] == "git" for r in drifted[:15]):
+                out.append("\n\\* The record has no date, so this counts from when it was first committed.")
     if not query:
         out.append("\n## Graph\n")
         out.append("| Record | Status | Date | Supersedes | Superseded by | Governs |")
@@ -536,7 +632,9 @@ def _main(argv=None):
     q = ap.add_mutually_exclusive_group()
     q.add_argument("--why", metavar="PATH", help="list the decisions that govern a file or folder")
     q.add_argument("--record", metavar="ID", help="show one record and its neighbours, e.g. ADR-0004")
-    ap.add_argument("--git", action="store_true", help="also read commit messages for record ids")
+    ap.add_argument("--git", action="store_true",
+                    help="also read the commits that mention each record, and those that changed each current "
+                         "decision's code since it was made")
     ap.add_argument("--git-limit", type=int, default=5000)
     ap.add_argument("--json", action="store_true", help="print the graph as JSON instead of Markdown")
     ap.add_argument("--mermaid", metavar="FILE", help="also write a Mermaid flowchart of the graph")
@@ -579,6 +677,8 @@ def _main(argv=None):
         claimed = [o["id"] for o in records if r["id"] in o["supersedes"]]
         r["successors"] = sorted(set(r["superseded_by"]) | set(claimed))
         r["successors_only_claimed_by_successor"] = sorted(set(claimed) - set(r["superseded_by"]))
+    if a.git and not any("no commits were read" in n for n in notes):
+        git_drift(root, records, a.git_limit)
     # Guides and READMEs that still cite a superseded decision may still teach it.
     by_id = {r["id"]: r for r in records}
     docs = other_docs(root, {r["path"] for r in records})