skilldrop-cli 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "1.0.0",
+  "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/ai-engineering/skills/ai-usage-report/examples/weekly-engineering-team.md

@@ -6,22 +6,22 @@ A small synthetic event log demonstrating the three views — including graceful
 
 ```csv
 timestamp,user,tool,session_id,output_consumed,consumed_at,outcome
-2026-05-19T09:14:23Z,alice@acme.com,claude-code,sess-001,1,2026-05-19T11:02:00Z,success
-2026-05-19T09:14:55Z,alice@acme.com,claude-code,sess-001,1,2026-05-19T11:02:00Z,success
-2026-05-19T09:18:02Z,alice@acme.com,deck-builder,sess-001,1,2026-05-19T14:30:00Z,success
-2026-05-19T10:01:11Z,bob@acme.com,cursor,sess-014,0,,success
-2026-05-19T10:01:30Z,bob@acme.com,cursor,sess-015,0,,success
-2026-05-19T10:02:11Z,bob@acme.com,cursor,sess-016,0,,success
-2026-05-19T10:03:11Z,bob@acme.com,cursor,sess-017,0,,success
-2026-05-19T10:04:11Z,bob@acme.com,cursor,sess-018,0,,success
-2026-05-20T14:22:08Z,carol@acme.com,claude-code,sess-029,1,2026-05-22T08:11:00Z,success
-2026-05-20T15:22:08Z,carol@acme.com,adr-generator,sess-029,1,2026-05-22T08:11:00Z,success
-2026-05-20T16:22:08Z,carol@acme.com,design-doc,sess-030,1,2026-05-22T08:11:00Z,success
-2026-05-19T11:14:23Z,dan@acme.com,claude-code,sess-101,1,2026-05-19T13:00:00Z,success
-2026-05-19T11:15:23Z,dan@acme.com,claude-code,sess-101,0,,success
-2026-05-20T08:14:23Z,eve@acme.com,claude-code,sess-201,1,2026-05-20T09:00:00Z,success
-2026-05-20T08:15:23Z,eve@acme.com,claude-code,sess-201,1,2026-05-20T09:00:00Z,success
-2026-05-20T08:16:23Z,eve@acme.com,cursor,sess-202,1,2026-05-20T10:00:00Z,success
+2026-05-19T09:14:23Z,alice@acme.example,claude-code,sess-001,1,2026-05-19T11:02:00Z,success
+2026-05-19T09:14:55Z,alice@acme.example,claude-code,sess-001,1,2026-05-19T11:02:00Z,success
+2026-05-19T09:18:02Z,alice@acme.example,deck-builder,sess-001,1,2026-05-19T14:30:00Z,success
+2026-05-19T10:01:11Z,bob@acme.example,cursor,sess-014,0,,success
+2026-05-19T10:01:30Z,bob@acme.example,cursor,sess-015,0,,success
+2026-05-19T10:02:11Z,bob@acme.example,cursor,sess-016,0,,success
+2026-05-19T10:03:11Z,bob@acme.example,cursor,sess-017,0,,success
+2026-05-19T10:04:11Z,bob@acme.example,cursor,sess-018,0,,success
+2026-05-20T14:22:08Z,carol@acme.example,claude-code,sess-029,1,2026-05-22T08:11:00Z,success
+2026-05-20T15:22:08Z,carol@acme.example,adr-generator,sess-029,1,2026-05-22T08:11:00Z,success
+2026-05-20T16:22:08Z,carol@acme.example,design-doc,sess-030,1,2026-05-22T08:11:00Z,success
+2026-05-19T11:14:23Z,dan@acme.example,claude-code,sess-101,1,2026-05-19T13:00:00Z,success
+2026-05-19T11:15:23Z,dan@acme.example,claude-code,sess-101,0,,success
+2026-05-20T08:14:23Z,eve@acme.example,claude-code,sess-201,1,2026-05-20T09:00:00Z,success
+2026-05-20T08:15:23Z,eve@acme.example,claude-code,sess-201,1,2026-05-20T09:00:00Z,success
+2026-05-20T08:16:23Z,eve@acme.example,cursor,sess-202,1,2026-05-20T10:00:00Z,success
 ```
 
 16 events, 5 users, 5 tools, period 2026-05-19 → 2026-05-20.
@@ -56,11 +56,11 @@ python3 scripts/build_report.py events.csv \
 
 | User | Invocations | Sessions | Avg / session | Distinct tools | Effectiveness rate | Single-shot rate |
 |---|---:|---:|---:|---:|---:|---:|
-| alice@acme.com | 3 | 1 | 3.0 | 2 | 100% | 0% |
-| bob@acme.com | 5 | 5 | 1.0 | 1 | 0% | 100% |
-| carol@acme.com | 3 | 2 | 1.5 | 3 | 100% | 50% |
-| dan@acme.com | 2 | 1 | 2.0 | 1 | 50% | 0% |
-| eve@acme.com | 3 | 2 | 1.5 | 2 | 100% | 50% |
+| alice@acme.example | 3 | 1 | 3.0 | 2 | 100% | 0% |
+| bob@acme.example | 5 | 5 | 1.0 | 1 | 0% | 100% |
+| carol@acme.example | 3 | 2 | 1.5 | 3 | 100% | 50% |
+| dan@acme.example | 2 | 1 | 2.0 | 1 | 50% | 0% |
+| eve@acme.example | 3 | 2 | 1.5 | 2 | 100% | 50% |
 ```
 
 **Reading the data:**
@@ -99,13 +99,13 @@ If the input is missing optional fields, columns drop silently to `—`:
 
 ```csv
 timestamp,user,tool
-2026-05-19T09:14:23Z,alice@acme.com,claude-code
-2026-05-19T09:14:55Z,alice@acme.com,claude-code
+2026-05-19T09:14:23Z,alice@acme.example,claude-code
+2026-05-19T09:14:55Z,alice@acme.example,claude-code
 ```
 
 ```markdown
 | User | Invocations | Sessions | Avg / session | Distinct tools | Effectiveness rate | Single-shot rate |
-| alice@acme.com | 2 | — | — | 1 | — | — |
+| alice@acme.example | 2 | — | — | 1 | — | — |
 ```
 
 The "Where signals are missing" section then explains *what* couldn't be computed and *why*.

package/packs/ai-engineering/skills/ai-usage-report/templates/usage-event-schema.md

@@ -49,20 +49,20 @@ When a column is omitted, the report includes a *"Where signals are missing"* se
 
 ```csv
 timestamp,user,tool,session_id,output_consumed,consumed_at,outcome
-2026-05-21T09:14:23Z,alice@acme.com,claude-code,sess-001,1,2026-05-21T11:02:00Z,success
-2026-05-21T09:14:55Z,alice@acme.com,claude-code,sess-001,1,2026-05-21T11:02:00Z,success
-2026-05-21T09:18:02Z,alice@acme.com,deck-builder,sess-001,1,2026-05-21T14:30:00Z,success
-2026-05-21T10:01:11Z,bob@acme.com,cursor,sess-014,0,,success
-2026-05-21T10:01:30Z,bob@acme.com,cursor,sess-014,0,,success
-2026-05-21T14:22:08Z,carol@acme.com,claude-code,sess-029,1,2026-05-22T08:11:00Z,success
+2026-05-21T09:14:23Z,alice@acme.example,claude-code,sess-001,1,2026-05-21T11:02:00Z,success
+2026-05-21T09:14:55Z,alice@acme.example,claude-code,sess-001,1,2026-05-21T11:02:00Z,success
+2026-05-21T09:18:02Z,alice@acme.example,deck-builder,sess-001,1,2026-05-21T14:30:00Z,success
+2026-05-21T10:01:11Z,bob@acme.example,cursor,sess-014,0,,success
+2026-05-21T10:01:30Z,bob@acme.example,cursor,sess-014,0,,success
+2026-05-21T14:22:08Z,carol@acme.example,claude-code,sess-029,1,2026-05-22T08:11:00Z,success
 ```
 
 ## Example: JSONL
 
 ```jsonl
-{"timestamp": "2026-05-21T09:14:23Z", "user": "alice@acme.com", "tool": "claude-code", "session_id": "sess-001", "output_consumed": true, "outcome": "success"}
-{"timestamp": "2026-05-21T09:14:55Z", "user": "alice@acme.com", "tool": "claude-code", "session_id": "sess-001", "output_consumed": true, "outcome": "success"}
-{"timestamp": "2026-05-21T10:01:11Z", "user": "bob@acme.com", "tool": "cursor", "session_id": "sess-014", "output_consumed": false, "outcome": "success"}
+{"timestamp": "2026-05-21T09:14:23Z", "user": "alice@acme.example", "tool": "claude-code", "session_id": "sess-001", "output_consumed": true, "outcome": "success"}
+{"timestamp": "2026-05-21T09:14:55Z", "user": "alice@acme.example", "tool": "claude-code", "session_id": "sess-001", "output_consumed": true, "outcome": "success"}
+{"timestamp": "2026-05-21T10:01:11Z", "user": "bob@acme.example", "tool": "cursor", "session_id": "sess-014", "output_consumed": false, "outcome": "success"}
 ```
 
 ## A note on the `output_consumed` signal

package/packs/converters/skills/file-to-markdown/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "file-to-markdown",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Convert a Word document, PowerPoint deck, Excel workbook, web page, CSV, JSON, text file, email (.eml or Outlook .msg) or PDF into clean Markdown that keeps headings, lists, tables, links, bold and italic, slide titles and speaker notes, and reports everything it dropped (images, charts, comments, formulas, tracked changes), so the content can be read, reviewed or fed to another skill. Use when the user hands over a .docx, .pptx, .xlsx, .html, .csv, .json, .eml, .msg or .pdf and says \"read this\", \"turn this into markdown\", \"extract the text\", or wants it critiqued or briefed.",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/converters/skills/file-to-markdown/scripts/to_markdown.py

@@ -26,6 +26,7 @@ import subprocess
 import sys
 import tempfile
 import zipfile
+import zlib
 from collections import OrderedDict
 from datetime import datetime, timedelta
 from html.parser import HTMLParser
@@ -148,12 +149,29 @@ def truthy(el, attr=W + "val"):
     return v is None or v not in ("0", "false", "off", "none")
 
 
+def span_of(value, cap):
+    """A cell's column span, from 1 to the format's own limit (Word: 63 columns; HTML: colspan
+    1000), so a damaged or hostile value can't make a row of a billion cells."""
+    v = (value or "1").strip()
+    return min(int(v), cap) if v.isascii() and v.isdigit() and int(v) > 0 else 1
+
+
 def open_zip(path, kind):
     try:
-        return zipfile.ZipFile(str(path))
+        z = zipfile.ZipFile(str(path))
     except zipfile.BadZipFile:
+        with open(str(path), "rb") as fh:
+            if fh.read(8) == b"\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1":
+                # Office saves a password-protected .docx/.pptx/.xlsx as a compound file holding
+                # the encrypted package, not as a zip
+                sys.exit("error: %s is password-protected (or an old binary Office file). Open it, remove "
+                         "the password or save it as %s, and rerun." % (path, kind))
         sys.exit("error: %s is not a valid %s file (not a zip package). If it is an old binary "
                  "Office file, save it as %s first." % (path, kind, kind))
+    if any(info.flag_bits & 0x1 for info in z.infolist()):
+        sys.exit("error: %s has encrypted parts, which Office never writes; it is damaged, or was "
+                 "zipped with a password by another tool" % path)
+    return z
 
 
 # ---------------------------------------------------------------- docx
@@ -210,6 +228,9 @@ def docx_to_md(path, rep):
                 break
 
     body = ET.fromstring(z.read("word/document.xml")).find(W + "body")
+    if body is None:
+        sys.exit("error: %s has no document body (word/document.xml has no w:body in the WordprocessingML "
+                 "namespace); it is not a Word document, or it is damaged" % path)
 
     def para_segments(p, in_table=False):
         segs = []
@@ -312,7 +333,7 @@ def docx_to_md(path, rep):
                 return ("decimal", 0)
             return None
         fmt = num_fmt.get(num_id, {}).get(ilvl, "bullet")
-        return (fmt, int(ilvl))
+        return (fmt, min(max(int(ilvl), 0), 8))  # Word's list levels are 0 to 8
 
     def table_md(tbl):
         rows = []
@@ -332,7 +353,7 @@ def docx_to_md(path, rep):
                         text = ""
                 row.append(text)
                 if tcpr is not None and tcpr.find(W + "gridSpan") is not None:
-                    row.extend([""] * (int(tcpr.find(W + "gridSpan").get(W + "val", "1")) - 1))
+                    row.extend([""] * (span_of(tcpr.find(W + "gridSpan").get(W + "val"), 63) - 1))
             rows.append(row)
         if len(list(tbl.iter(W + "tbl"))) > 1:
             rep.notes.append("a nested table was flattened into its parent cell")
@@ -523,7 +544,7 @@ def pptx_to_md(path, rep):
             if not text:
                 continue
             ppr = p.find(A + "pPr")
-            lvl = int(ppr.get("lvl", "0")) if ppr is not None else 0
+            lvl = min(max(int(ppr.get("lvl", "0")), 0), 8) if ppr is not None else 0  # PowerPoint's are 0 to 8
             bullet = is_body
             if ppr is not None:
                 if ppr.find(A + "buNone") is not None:
@@ -618,12 +639,16 @@ def pptx_to_md(path, rep):
 BUILTIN_DATE_FMTS = set(range(14, 23)) | {45, 46, 47}
 
 
-def col_index(ref):
-    letters = re.match(r"([A-Z]+)", ref).group(1)
+def cell_ref(ref):
+    """(row, column) from a cell reference such as B7 or $B$7, counting from 0; None for anything
+    else, so a damaged reference skips that cell rather than the sheet."""
+    m = re.fullmatch(r"\$?([A-Za-z]{1,3})\$?(\d{1,7})", ref.strip())
+    if not m or int(m.group(2)) < 1:
+        return None
     n = 0
-    for ch in letters:
+    for ch in m.group(1).upper():
         n = n * 26 + (ord(ch) - 64)
-    return n - 1
+    return int(m.group(2)) - 1, n - 1
 
 
 def xlsx_to_md(path, rep, max_rows=0):
@@ -678,8 +703,10 @@ def xlsx_to_md(path, rep, max_rows=0):
             ref = c.get("r")
             if not ref:
                 continue
-            row = int(re.search(r"(\d+)$", ref).group(1)) - 1
-            col = col_index(ref)
+            rc = cell_ref(ref)
+            if rc is None:
+                continue
+            row, col = rc
             t = c.get("t", "n")
             v = c.find(S + "v")
             if c.find(S + "f") is not None:
@@ -717,13 +744,14 @@ def xlsx_to_md(path, rep, max_rows=0):
             out.append("*(empty sheet)*")
             out.append("")
             continue
+        # Only the rows and columns that hold a value: one stray cell at ZZZ999999 must not
+        # build a grid of a million empty rows.
         rows_used = sorted({r for r, _ in grid})
         cols_used = sorted({c for _, c in grid})
-        c0, c1 = cols_used[0], cols_used[-1]
-        table = []
-        for r in range(rows_used[0], rows_used[-1] + 1):
-            table.append([grid.get((r, c), "") for c in range(c0, c1 + 1)])
-        table = [r for r in table if any(r)]
+        gaps = cols_used[-1] - cols_used[0] + 1 - len(cols_used)
+        if gaps:
+            rep.notes.append("sheet '%s': %d empty column(s) left out" % (name, gaps))
+        table = [[grid.get((r, c), "") for c in cols_used] for r in rows_used]
         if max_rows and len(table) > max_rows + 1:
             rep.notes.append("sheet '%s' cut to %d of %d data rows (--max-rows)"
                              % (name, max_rows, len(table) - 1))
@@ -860,8 +888,7 @@ class HTMLToMD(HTMLParser):
             if not self.table:
                 self.table.append([])
             self.cell = []
-            span = int(a.get("colspan") or "1") if (a.get("colspan") or "1").isdigit() else 1
-            self._span = span
+            self._span = span_of(a.get("colspan"), 1000)
 
     def handle_endtag(self, tag):
         if tag in self.SKIP:
@@ -1028,29 +1055,60 @@ def _human_size(n):
         n /= 1024.0
 
 
+def _part_text(part):
+    """A text part's content. A charset Python doesn't know (a typo, or a vendor's own label) is
+    read as UTF-8 with replacement characters, as html_to_md does, rather than lost."""
+    try:
+        return part.get_content()
+    except LookupError:
+        return (part.get_payload(decode=True) or b"").decode("utf-8", "replace")
+
+
+def _unescape(text):
+    """The email package keeps undecodable header bytes as surrogates, which can't be written as
+    UTF-8. Read them as UTF-8, with a replacement character for any that aren't."""
+    return text.encode("utf-8", "surrogateescape").decode("utf-8", "replace")
+
+
+def _header(msg, name):
+    """A header's decoded value, or its raw text when it won't parse: Python 3.9's email package
+    raises on a malformed date or address that later versions keep."""
+    try:
+        return _unescape(str(msg.get(name, "")))
+    except (TypeError, ValueError, IndexError, AttributeError, OverflowError):
+        return _unescape(next((" ".join(str(v).split()) for k, v in msg.raw_items() if k.lower() == name.lower()), ""))
+
+
 def eml_to_md(path, rep):
     """An RFC 5322 message (.eml): the plain-text part when there is one, else the HTML part."""
     import email
     from email import policy
     msg = email.message_from_bytes(path.read_bytes(), policy=policy.default)
-    rows = [("From", str(msg.get("From", ""))), ("To", str(msg.get("To", ""))), ("Cc", str(msg.get("Cc", ""))),
-            ("Date", str(msg.get("Date", "")))]
-    plain = msg.get_body(preferencelist=("plain",))
-    html = msg.get_body(preferencelist=("html",))
+    rows = [(h, _header(msg, h)) for h in ("From", "To", "Cc", "Date")]
+    try:
+        plain = msg.get_body(preferencelist=("plain",))
+        html = msg.get_body(preferencelist=("html",))
+        parts = list(msg.iter_attachments())
+    except (AttributeError, TypeError, KeyError):
+        # Python 3.9 fails inside get_body on a multipart message whose boundary never appears.
+        # Read it as one text body, which is what the raw message holds.
+        raw = msg.get_payload()
+        rep.notes.append("the message's MIME parts could not be separated, so its body is the raw text")
+        return _email_md(_header(msg, "Subject"), rows, _email_text(_unescape(raw) if isinstance(raw, str) else ""), [], rep)
     if plain is not None:
-        body = _email_text(plain.get_content())
+        body = _email_text(_part_text(plain))
         if html is not None:
             rep.drop("HTML alternative (the plain-text part was used)", 1)
     elif html is not None:
-        body = _html_text_to_md(html.get_content(), rep)
+        body = _html_text_to_md(_part_text(html), rep)
     else:
         body = ""
     attachments = []
-    for part in msg.iter_attachments():
+    for part in parts:
         payload = part.get_payload(decode=True)
         name = part.get_filename() or ("forwarded message" if part.get_content_type() == "message/rfc822" else None)
         attachments.append((name, len(payload) if payload is not None else None))
-    return _email_md(str(msg.get("Subject", "")), rows, body, attachments, rep)
+    return _email_md(_header(msg, "Subject"), rows, body, attachments, rep)
 
 
 class _CFB:
@@ -1073,14 +1131,20 @@ class _CFB:
         minifat_start, nminifat, difat_start, ndifat = struct.unpack_from("<IIII", data, 60)
         difat = list(struct.unpack_from("<109I", data, 76))
         per = self.ss // 4
-        s, guard = difat_start, 0
-        while ndifat and s < 0xFFFFFFFA and guard < 10000:
+        # A FAT never needs more sectors than it takes to map the file, and lists each one once:
+        # a repeated or looping list would otherwise build a table far larger than the file.
+        nsect = len(data) // self.ss - 1
+        need = -(-nsect // per)
+        s, seen = difat_start, set()
+        while ndifat and s < 0xFFFFFFFA and s not in seen and len(seen) < need:
+            seen.add(s)
             vals = struct.unpack("<%dI" % per, self._sector(s))
             difat += vals[:-1]
-            s, guard, ndifat = vals[-1], guard + 1, ndifat - 1
-        self.fat = []
-        for fs in difat[:nfat]:
-            if fs < 0xFFFFFFFA:
+            s, ndifat = vals[-1], ndifat - 1
+        self.fat, used = [], set()
+        for fs in difat[:min(nfat, need)]:
+            if fs < 0xFFFFFFFA and fs not in used:
+                used.add(fs)
                 self.fat += struct.unpack("<%dI" % per, self._sector(fs))
         raw = self._chain(dir_start)
         self.entries = []
@@ -1108,16 +1172,17 @@ class _CFB:
         return self.d[off:off + self.ss]
 
     def _chain(self, start, mini=False):
-        fat, out, n, seen = (self.minifat if mini else self.fat), [], start, 0
+        fat, out, n, seen = (self.minifat if mini else self.fat), [], start, set()
         while n < 0xFFFFFFFA:
-            if n >= len(fat) or seen > 1000000:
+            if n >= len(fat) or n in seen:  # off the table, or a loop: each sector is read once
                 raise ValueError("compound file has a broken sector chain")
+            seen.add(n)
             if mini:
                 off = n * self.mss
                 out.append(self.ministream[off:off + self.mss])
             else:
                 out.append(self._sector(n))
-            n, seen = fat[n], seen + 1
+            n = fat[n]
         return b"".join(out)
 
     def children(self, idx):
@@ -1171,8 +1236,11 @@ def _msg_fixed(cfb, idx, header):
         ptype, pid = tag & 0xFFFF, "%04X" % (tag >> 16)
         if ptype == 0x0040:
             ft, = struct.unpack_from("<Q", data, off + 8)
-            if ft:
-                out[pid] = _dt(1601, 1, 1) + timedelta(microseconds=ft // 10)
+            try:
+                if ft:
+                    out[pid] = _dt(1601, 1, 1) + timedelta(microseconds=ft // 10)
+            except OverflowError:
+                pass  # a time past the year 9999 is a placeholder or damage; the message has no date
         elif ptype == 0x0003:
             out[pid] = struct.unpack_from("<i", data, off + 8)[0]
     return out
@@ -1679,6 +1747,9 @@ HANDLERS = {
     ".html": html_to_md, ".htm": html_to_md, ".csv": csv_to_md, ".tsv": csv_to_md,
     ".json": json_to_md, ".pdf": pdf_to_md, ".eml": eml_to_md, ".msg": msg_to_md,
 }
+# What a damaged or truncated file raises from the zip, XML, compound-file and email layers.
+DAMAGED = (zipfile.BadZipFile, zipfile.LargeZipFile, zlib.error, EOFError, ET.ParseError, ValueError, LookupError,
+           KeyError, IndexError, NotImplementedError, OSError)
 LEGACY = {".doc": ".docx", ".ppt": ".pptx", ".xls": ".xlsx", ".rtf": ".docx", ".odt": ".docx",
           ".pages": ".docx", ".key": ".pptx", ".numbers": ".xlsx"}
 
@@ -1711,8 +1782,15 @@ def main(argv=None):
             md += "\n"
     elif ext in HANDLERS:
         fn = HANDLERS[ext]
-        md = (fn(path, rep, a.max_rows) if fn is xlsx_to_md else
-              fn(path, rep, ocr=not a.no_ocr, ocr_lang=a.ocr_lang) if fn is pdf_to_md else fn(path, rep))
+        try:
+            md = (fn(path, rep, a.max_rows) if fn is xlsx_to_md else
+                  fn(path, rep, ocr=not a.no_ocr, ocr_lang=a.ocr_lang) if fn is pdf_to_md else fn(path, rep))
+        except DAMAGED as e:
+            if ext not in (".docx", ".pptx", ".xlsx", ".xlsm", ".msg", ".eml"):
+                raise
+            # A file that opens in its own app is a bug here; one that doesn't is damaged.
+            sys.exit("error: %s looks damaged or truncated, so it could not be read as %s (%s: %s). If it "
+                     "opens normally in its own app, please report it." % (path, ext, type(e).__name__, e))
     else:
         sys.exit("error: unsupported file type %r. Supported: %s, .txt, .md"
                  % (ext, ", ".join(sorted(HANDLERS))))

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.