skilldrop-cli 1.0.1 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs/core/pack.json

@@ -1,7 +1,7 @@
 {
-  "description": "The cross-role toolkit every pack builds on: structured intake, document critique, the review council, and output hygiene, plus the ship-a-draft wrapper. Installed automatically with every role pack.",
+  "description": "The cross-role toolkit every pack builds on: structured intake, document critique, the review council, output hygiene, and the decision graph behind a codebase, plus the ship-a-draft wrapper. Installed automatically with every role pack.",
   "display_name": "Core",
-  "keywords": ["intake", "critique", "review", "hygiene"],
+  "keywords": ["intake", "critique", "review", "hygiene", "decisions"],
   "links": {
     "documentation": "https://sananthanarayan.github.io/skilldrop/packs/core/"
   },

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

@@ -1,6 +1,6 @@
 ---
 name: context-graph
-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.
+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.
 ---
 
 # context-graph
@@ -31,7 +31,7 @@ the code itself is `reverse-architecture`.
    # Other IDEs (from the skill folder)
    python3 scripts/context_graph.py --root <repo> --docs architecture/decisions --json -o graph.json --mermaid graph.mmd
    ```
-   `--git` adds the commits whose messages mention each record. A path counts as governed when a record names it in backticks or links to it, and it exists. Without the script, do the same by hand and say the links were found by reading, not computed.
+   `--git` adds the commits whose messages mention each record. For each current decision that governs code, it also lists the commits that changed that code since the decision's date (or since the record was committed, when it has no date). It gives who made them, how many cite the record, and when the record itself was last edited. A path counts as governed when a record names it in backticks or links to it, and it exists. Without the script, do the same by hand and say the links were found by reading, not computed.
 
    **The script's findings are leads, not answers.** Confirm each one by reading the records and the code before you report it, and drop the ones that don't hold. Two records "governing the same path" often don't clash at all: say so only when their decisions actually conflict, and quote both.
 
@@ -43,12 +43,15 @@ the code itself is `reverse-architecture`.
 
 4. **Check the deciding record against the code.** Open the files it governs and check each thing the record requires (every "must", every named field, check, limit or setting), not only its headline. Confirm or contradict each with the code, quoting the line: ✅ *"`scheduler/jobs.py` line 18 still opens a database transaction per job, as ADR-0012 says."* Report drift as a finding with both sides: ✅ *"ADR-0015 promises 30 days of audit-log retention; `ops/logging.yaml` sets `retention_days: 14`."* When the record describes a phased change (a migration, a dual-write, a rollout), say which phase the code is in. While it's mid-rollout, the old decision still holds for the parts not yet moved: that is a missing cross-reference, not a contradiction.
 
+   With git history, start with what changed since the decision: the commits to its code that don't cite it, newest first. Read what each one changed against the record's requirements. A commit is not drift by itself; a requirement the code no longer meets is. ✅ *"ADR-0009 (2026-02-10) requires one queue per tenant. Three commits since; `a1b2c3d` (Ben, 2026-05-03, 'Switch to shared queue') moved `orders/publish.py` to a single queue."* When the code changed a lot and the record was never touched, say so even when you find no contradiction. Name the people who made the changes: they are who to ask about what the record doesn't say.
+
 5. **For "can I remove or change X?", search the code for every use of X,** not only the records: imports, client constructors, config keys, environment variables and container definitions. A use that no record covers is still a dependency: list it as "in use, no recorded decision", with its file. The records tell you why; only the code tells you everything that would break.
 
 6. **Find the decisions that bear on it, not only the ones that name its path.** Read any record that amends, extends or narrows the governing one, and any that sets a rule for the same concern across the codebase (error handling, data access, logging, authentication), even when it names a different folder. A shared-library rule governs a change that creates a shared library. Before you call a related record unrelated, read it.
 
 7. **Report what is no longer true, worst first.** Problems before warnings:
    - **Supersession recorded on one side only:** "ADR-0004 still says Accepted". Fix it by marking it "Superseded by ADR-0009".
+   - **Code that no longer does what its current decision requires:** quote the requirement and the line, and name the commit that changed it when the history shows one.
    - **A current decision pointing at code that is gone:** the record names a folder or file that no longer exists. When the script suggests where it moved (a renamed sibling), or a README says so, report it as moved, not gone, and give the path to update. Only a path with no successor is gone; then the decision is dead, so deprecate it.
    - **A guide that still teaches a superseded decision:** an onboarding doc or a README that cites the old record, or describes its choice. Name the file and the line to change.
    - **Two current decisions governing the same path, neither superseding nor amending the other:** a possible conflict. Read both, quote the clash if there is one, and recommend which one supersedes or amends the other.
@@ -56,7 +59,7 @@ the code itself is `reverse-architecture`.
 
 8. **Give each fix as the exact edit.** The line to change in which record, such as changing `## Status` to `Superseded by ADR-0009`, linked to that record's file, or the new record that's needed and what it must decide. Don't rewrite records nobody asked about.
 
-9. **Say what the record can't tell.** Decisions made in chat or tickets and never written down, code that no record governs, and, without `--git`, whether anything was actually implemented. When a question has no record, say so, and suggest writing one only if the decision is still live.
+9. **Say what the record can't tell.** Decisions made in chat or tickets and never written down, code that no record governs, and, without `--git`, whether anything was actually implemented or has changed since. When a question has no record, say so, and suggest writing one only if the decision is still live.
 
 10. **Write the reply in this order, at the size asked for:**
    - the answer, in two or three sentences, with the governing record's id;
@@ -71,7 +74,7 @@ the code itself is `reverse-architecture`.
 ## Useful references in this skill
 
 - [`reference.md`](reference.md): the record formats read (MADR, Nygard, RFC frontmatter), how status, supersession, amendment and governed paths are detected, every check and its fix, and the JSON shape
-- [`scripts/context_graph.py`](scripts/context_graph.py): stdlib; builds the graph, checks it, answers `--why PATH` and `--record ID`; `--json`, `--mermaid`, `--git`; exits 1 on problems and 2 on bad input
+- [`scripts/context_graph.py`](scripts/context_graph.py): stdlib; builds the graph, checks it, answers `--why PATH` and `--record ID`; `--json`, `--mermaid`, `--git` (commits behind each record, and changes since each decision); exits 1 on problems and 2 on bad input
 - [`examples/order-events.md`](examples/order-events.md): worked example, a repo whose Kafka ADR was superseded on one side only and whose newer ADR names a folder that was deleted
 
 ## Quality bar
@@ -86,6 +89,7 @@ the code itself is `reverse-architecture`.
 - **A removal or change question lists every use of the thing in the code,** recorded or not.
 - **Related records are read before they're called unrelated:** amendments, and rules for the same concern elsewhere in the codebase.
 - **A moved path is reported as moved, with its new location; only a path with no successor is "gone".**
+- **Drift is a requirement the code no longer meets, with the record's words, the line, and the commit when the history shows one.** A count of commits is a reason to look, never a finding by itself.
 - **A mid-rollout pair of records is a missing cross-reference, not a contradiction.**
 - **The reply fits the size asked for (a stated limit is obeyed exactly), and never mentions a script, a graph or a tool.**
 - **Statuses, links and governed paths come from the script's output**, or are marked as read by hand when it couldn't run.
@@ -96,6 +100,7 @@ the code itself is `reverse-architecture`.
 - ✅ "Why do we use X?" or "Why is this service built this way?" in a repo with ADRs or RFCs
 - ✅ "Which decisions govern this file, folder or service before I change it?"
 - ✅ "Are our ADRs still current?" or "Find the stale or contradictory decisions"
+- ✅ "Has the code drifted from what we decided?" or "What changed in this service since the ADR, and who changed it?"
 - ✅ A map of a codebase's architecture decisions for onboarding or a review
 
 ## When NOT to use this skill
@@ -115,5 +120,6 @@ the code itself is `reverse-architecture`.
 - ❌ **Passing on a script warning unread.** "Both govern the same path" is a prompt to read both, not a conflict.
 - ❌ **Answering "can I remove it?" from the records alone.** The uses nobody recorded are the ones that break.
 - ❌ **Taking the record's word for it.** A decision the code no longer follows is the most useful thing to find; read the files.
+- ❌ **Calling it drift because the code changed.** Most commits since a decision implement or refine it. Only a requirement the code no longer meets is drift.
 - ❌ **"Gone" for a folder that was renamed.** Look for where it went before telling someone the decision is dead.
 - ❌ **Telling the reader how you found it.** "The script shows" or "the graph says" means nothing to them; say what the records and the code say.

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

@@ -7,5 +7,8 @@
   {"query": "We just decided to move our search from Postgres full-text to a hosted search engine. Write the ADR for it in MADR format", "should_trigger": false},
   {"query": "I start on the checkout repo on Monday. How do I run it locally, run the tests, and where's the code for applying discount codes?", "should_trigger": false},
   {"query": "There are no design docs for this monolith. Work out its architecture from the code and the docker-compose file and draw me a C4 diagram", "should_trigger": false},
-  {"query": "Here are the notes from this morning's pricing steering meeting. Pull out what was decided, who owns each action and when it's due", "should_trigger": false}
+  {"query": "Here are the notes from this morning's pricing steering meeting. Pull out what was decided, who owns each action and when it's due", "should_trigger": false},
+  {"query": "ADR-0009 says order events go through one SQS queue per tenant. Has the orders service drifted from that since we decided it, and who changed it?", "should_trigger": true},
+  {"query": "Before I rewrite the billing batch job, what decisions did we record about it, and has anyone changed the code since without updating them?", "should_trigger": true},
+  {"query": "Show me who committed to services/orders in the last month and summarise what changed", "should_trigger": false}
 ]

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

@@ -220,6 +220,36 @@
         "Delivers the map itself as one pasteable markdown block (e.g. a table of ID, title, store, status, date, replaced by/replaces) with the issues in a short separate list, rather than a long narrative or per-file walkthrough; any check that needs git history (e.g. whether ADR 7 was ever implemented) is given as a command to run, not as a claimed result.",
         "Invents nothing not in the input: no ADR numbers, dates, databases, services, sizes or commit details beyond what the files in doc/adr/, services/, deploy/ and web/ contain."
       ]
+    },
+    {
+      "id": 16,
+      "held_out": "2026-10-22",
+      "prompt": "I'm about to rework how payments handles client retries. ADR-0004 is the idempotency decision. Is the code in services/payments still doing what it says? If anything has drifted, which commit did it and who? Keep it short, I just need to know what I can safely assume before I start.",
+      "assertions": [
+        "Identifies the real drift: services/payments/idempotency.py no longer compares the stored body fingerprint in lookup(), so a request that reuses an Idempotency-Key with a different body gets the cached response back instead of a 422. That breaks ADR-0004 rule 4, and the response points out that the 422 branch in services/payments/api/create.py can no longer fire because IdempotencyConflict is never raised.",
+        "Pins the drift to the 2025-08-19 commit 'refactor: simplify idempotency store lookups' by Dmitri Vasquez, notes that its message says 'No behaviour change intended' even though behaviour did change, and notes that the same commit skipped test_mismatched_body_raises_conflict in tests/test_idempotency.py (reason 'flaky since lookup refactor, see PAY-311').",
+        "Does NOT report the 48-hour TTL (TTL_SECONDS = 48 * 60 * 60, i.e. 172800) as drift from ADR-0004's 24 hours. It recognises that ADR-0007 (2025-06-02, Accepted) amends rule 3 and that Lena Hargrove's 2025-06-04 commit implemented it.",
+        "Points out that the amendment is recorded on one side only: ADR-0007 says 'Amends: ADR-0004', but ADR-0004 still reads 'Status: Accepted' with 24 hours and no 'Amended by ADR-0007', even though ADR-0001 requires both sides to say so.",
+        "Confirms what still holds, so the user knows what is safe to assume: a missing Idempotency-Key is still rejected with 400, records are still scoped per merchant (key idem:{merchant_id}:{key}) and stored in Redis with a TTL, and ADR-0007 says all other ADR-0004 rules are unchanged, so rule 4 is still meant to apply.",
+        "Treats the later commits correctly as legitimate or neutral: Priya Natarajan's 2025-03-10 implementation commit, Tomás Okafor's 2025-03-12 tests and his 2025-09-30 debug-logging commit are not flagged as drift.",
+        "Answers the question directly and compactly: it starts with whether the code matches ADR-0004 (no, one rule is broken) plus the commit and author, and recommends restoring the comparison and un-skipping the test, or else writing a superseding ADR if dropping rule 4 was intended. It does not pad the answer with a full catalogue of unrelated ADRs (0001-0003).",
+        "Invents nothing: every commit, date, author, file, constant and ticket it cites (including PAY-311, which it does not claim to know the contents of) exists in the repository or its git history, and it invents no other ADRs, incidents or email addresses."
+      ]
+    },
+    {
+      "id": 17,
+      "held_out": "2026-10-22",
+      "prompt": "hey, joined the platform team last week and i'm inheriting the notifications service. someone told me \"half our ADRs are lies\" lol. which of the decision docs can i actually trust for notifications, and is anything in there just wrong? repo's checked out here",
+      "assertions": [
+        "Gives a direct trust verdict for each decision record that governs notifications: ADR-0002, ADR-0003, ADR-0004, ADR-0005, ADR-0006, ADR-0007 and RFC-012 (via services/*/retry.py). Each one gets its status and a short trust / don't trust / partly answer, rather than a generic essay about ADR hygiene.",
+        "Flags ADR-0003 (RabbitMQ) as superseded on one side only: ADR-0007 says 'Supersedes: ADR-0003', but ADR-0003 still says 'Status: Accepted', breaking the both-sides rule in ADR-0001. It confirms from services/notifications/consumer.py (KafkaConsumer, topics user-events and invoice-events, group notifications) that Kafka is what actually runs, so ADR-0003 should not be trusted.",
+        "Flags that ADR-0006 (5 attempts, 2s base) and RFC-012 (3 attempts, 1s base, full jitter, 30s cap) are both Accepted, both govern services/notifications/retry.py, and contradict each other, with neither recording that it supersedes the other. It notes that notifications' retry.py follows ADR-0006 (MAX_ATTEMPTS = 5, BASE_DELAY_SECONDS = 2) while services/billing/retry.py follows RFC-012, and it leaves the conflict for the team to settle and record instead of quietly declaring one the winner.",
+        "Flags that ADR-0005 governs services/notifications/templates/, which no longer exists (the templates are in packages/notification-templates/, per its README), and gets the nuance right: rendering is still server-side via services/notifications/render.py with Jinja2 autoescape, so the decision itself still holds and only its governed path is stale.",
+        "Flags that ADR-0007 points to 'RFC-015 for the migration plan and cutover dates', but no RFC-015 exists in docs/rfcs/ (only RFC-012).",
+        "Does not flag the ADR-0002 to ADR-0004 supersession, which is recorded on both sides. It confirms that services/notifications/email/sender.py uses the provider HTTPS API and that dispatch.py logs the provider message id, so ADR-0004 can be trusted.",
+        "Says plainly that the checkout has no git history, so it cannot say when or by whom the code moved away from a record. It gives the commands the user could run to find out (for example git log --follow on services/notifications/retry.py, or git log on the templates move).",
+        "Invents nothing: no record, status, date, person, path, topic name or number beyond what the files contain. In particular it does not make up what RFC-015 says or a reason why the templates were moved beyond the README's stated reason (billing previews)."
+      ]
     }
   ]
 }

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

@@ -0,0 +1,4 @@
+# payments-api
+
+Payment creation and ledger service for the Larkfield merchant platform.
+Architecture decisions live in `docs/adr/`.

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

@@ -0,0 +1,12 @@
+# ADR-0001: Record architecture decisions
+
+Status: Accepted
+Date: 2025-01-14
+Deciders: Priya Natarajan
+
+## Decision
+
+We record significant decisions as numbered ADRs in `docs/adr/`. An ADR that is
+replaced or changed by a later one says so in its Status line ("Superseded by
+ADR-NNNN" or "Amended by ADR-NNNN"), and the later ADR says what it supersedes
+or amends.

package/packs/core/skills/context-graph/evals/files/16/docs/adr/0002-postgres-for-the-ledger.md

@@ -0,0 +1,11 @@
+# ADR-0002: Postgres for the payment ledger
+
+Status: Accepted
+Date: 2025-01-20
+Deciders: Priya Natarajan, Tomás Okafor
+Governs: services/payments/ledger.py
+
+## Decision
+
+The ledger of record is a single Postgres database. Every payment is written in
+one transaction to `payments` and `ledger_entries`.

package/packs/core/skills/context-graph/evals/files/16/docs/adr/0003-redis-for-ephemeral-state.md

@@ -0,0 +1,12 @@
+# ADR-0003: Redis for short-lived state
+
+Status: Accepted
+Date: 2025-02-03
+Deciders: Tomás Okafor
+Governs: services/payments/redis_client.py
+
+## Decision
+
+Short-lived, reconstructable state (rate-limit counters, idempotency records)
+lives in Redis with an explicit TTL on every key. Nothing in Redis is the
+system of record.

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",