skilldrop-cli 0.16.29 → 0.16.31

package/packs/dev-team/skills/codebase-tour/scripts/repo_facts.py

@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""List the facts a codebase tour cites, each with the file and line it came from.
+
+Reads a repository and prints, to stdout:
+  - build and tool manifests found (package.json, pyproject.toml, Makefile, ...)
+  - commands the repo itself defines: package.json scripts, Makefile and justfile
+    targets, CI `run:` / `script:` steps, tox and nox sessions, pyproject entry points
+  - commands the README or CONTRIBUTING names that no manifest or CI file defines, and
+    paths they name that do not exist
+  - entry points (main functions, `__main__` guards, Dockerfile CMD/ENTRYPOINT, bin)
+  - test files grouped by directory, and test-runner config files
+  - files that say they are generated, vendored directories, and lockfiles
+  - environment variables the code reads, with the line that reads each
+  - the directories holding the most files
+
+It is read-only: it opens files under the root it is given and writes nothing.
+It cannot tell which command works; it tells you where each one is written down.
+
+Usage:
+    python3 repo_facts.py <repo-root>
+    python3 repo_facts.py <repo-root> --json
+    python3 repo_facts.py <repo-root> --max 25     # cap items per section (default 40)
+
+Exit codes: 0 facts printed, 2 bad input.
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from collections import Counter, defaultdict
+
+SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build", ".tox",
+             ".nox", "target", ".mypy_cache", ".pytest_cache", ".ruff_cache", ".next",
+             "coverage", ".gradle", ".idea", ".vscode", ".terraform"}
+MANIFESTS = {"package.json", "pyproject.toml", "setup.cfg", "setup.py", "tox.ini", "noxfile.py",
+             "Makefile", "makefile", "GNUmakefile", "justfile", "Taskfile.yml", "go.mod",
+             "Cargo.toml", "pom.xml", "build.gradle", "build.gradle.kts", "Gemfile",
+             "composer.json", "Dockerfile", "docker-compose.yml", "docker-compose.yaml",
+             "compose.yml", "compose.yaml", "requirements.txt", "requirements-dev.txt",
+             ".tool-versions", ".nvmrc", ".python-version", "CONTRIBUTING.md", "Procfile"}
+LOCKFILES = {"package-lock.json", "yarn.lock", "pnpm-lock.yaml", "poetry.lock", "uv.lock",
+             "Pipfile.lock", "Cargo.lock", "go.sum", "Gemfile.lock", "composer.lock"}
+VENDOR_DIRS = {"vendor", "third_party", "third-party", "vendored", "external"}
+SOURCE_EXT = {".py", ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".go", ".rb", ".java",
+              ".kt", ".rs", ".php", ".cs", ".sh", ".scala", ".swift"}
+TEST_FILE = re.compile(r"(^test_.*\.py$|_test\.py$|_test\.go$|\.(test|spec)\.[cm]?[jt]sx?$|"
+                       r"Tests?\.(java|kt|cs)$|_spec\.rb$|_test\.rb$)")
+TEST_CONFIG = re.compile(r"^(pytest\.ini|conftest\.py|jest\.config\.\w+|vitest\.config\.\w+|"
+                         r"karma\.conf\.\w+|\.mocharc\.\w+|phpunit\.xml(\.dist)?)$")
+GENERATED = re.compile(r"(?i)(do not edit|@generated|code generated|auto-?generated|"
+                       r"this file is generated|generated by|don't change)")
+# Environment reads. `[.]` keeps each pattern literal without a backslash-dot sequence.
+ENV_READS = [
+    re.compile(r"os[.]environ(?:[.]get)?\s*[\[(]\s*[\"']([A-Za-z_][A-Za-z0-9_]*)"),
+    re.compile(r"os[.]getenv\s*\(\s*[\"']([A-Za-z_][A-Za-z0-9_]*)"),
+    re.compile(r"process[.]env[.]([A-Za-z_][A-Za-z0-9_]*)"),
+    re.compile(r"process[.]env\[\s*[\"'`]([A-Za-z_][A-Za-z0-9_]*)"),
+    re.compile(r"os[.](?:Getenv|LookupEnv)\(\s*\"([A-Za-z_][A-Za-z0-9_]*)\""),
+    re.compile(r"ENV(?:[.]fetch\(|\[)\s*[\"']([A-Za-z_][A-Za-z0-9_]*)"),
+    re.compile(r"System[.]getenv\(\s*\"([A-Za-z_][A-Za-z0-9_]*)\""),
+    re.compile(r"env::var\(\s*\"([A-Za-z_][A-Za-z0-9_]*)\""),
+]
+RUNNERS = {"npm", "yarn", "pnpm", "make", "just", "nox", "tox"}
+MAX_BYTES = 512 * 1024
+
+
+def walk(root):
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(d for d in dirnames if d not in SKIP_DIRS)
+        for name in sorted(filenames):
+            full = os.path.join(dirpath, name)
+            yield os.path.relpath(full, root).replace(os.sep, "/"), full
+
+
+def read_lines(full):
+    try:
+        if os.path.getsize(full) > MAX_BYTES:
+            return []
+        with open(full, encoding="utf-8", errors="replace") as fh:
+            return fh.read().splitlines()
+    except OSError:
+        return []
+
+
+def line_of(lines, pattern, start=0):
+    for i in range(start, len(lines)):
+        if re.search(pattern, lines[i]):
+            return i + 1
+    return 0
+
+
+def package_scripts(rel, lines, out, targets):
+    try:
+        doc = json.loads("\n".join(lines))
+    except ValueError:
+        return
+    for name, cmd in (doc.get("scripts") or {}).items():
+        n = line_of(lines, r'^\s*"%s"\s*:' % re.escape(name))
+        out.append({"command": "npm run %s" % name, "runs": cmd, "where": "%s:%d" % (rel, n)})
+        targets["npm"].add(name)
+    for key in ("main", "bin"):
+        if key in doc:
+            yield key, doc[key], "%s:%d" % (rel, line_of(lines, r'^\s*"%s"\s*:' % key))
+
+
+def make_targets(rel, lines, out, targets, runner):
+    for i, line in enumerate(lines):
+        m = re.match(r"^([A-Za-z0-9][\w.-]*)\s*(?:[^:=\n]*)?:(?!=)", line)
+        if not m or m.group(1).startswith(".") or "=" in line.split(":")[0]:
+            continue
+        recipe = ""
+        for nxt in lines[i + 1:i + 4]:
+            if nxt.startswith(("\t", "    ")) and nxt.strip():
+                recipe = nxt.strip()
+                break
+        out.append({"command": "%s %s" % (runner, m.group(1)), "runs": recipe,
+                    "where": "%s:%d" % (rel, i + 1)})
+        targets[runner].add(m.group(1))
+
+
+def ci_steps(rel, lines, out):
+    i = 0
+    while i < len(lines):
+        m = re.match(r"^(\s*)(?:-\s*)?run:\s*(.*)$", lines[i])
+        if m:
+            indent, value = len(m.group(1)), m.group(2).strip()
+            if value in ("|", ">", "|-", ">-", ""):
+                j = i + 1
+                while j < len(lines) and (not lines[j].strip() or
+                                          len(lines[j]) - len(lines[j].lstrip()) > indent):
+                    if lines[j].strip() and not lines[j].strip().startswith("#"):
+                        out.append({"command": lines[j].strip(), "where": "%s:%d" % (rel, j + 1)})
+                    j += 1
+                i = j
+                continue
+            out.append({"command": value, "where": "%s:%d" % (rel, i + 1)})
+        i += 1
+
+
+def gitlab_steps(rel, lines, out):
+    inside = None
+    for i, line in enumerate(lines):
+        m = re.match(r"^(\s*)(before_script|script|after_script):\s*$", line)
+        if m:
+            inside = len(m.group(1))
+            continue
+        if inside is not None:
+            item = re.match(r"^(\s*)-\s+(.*)$", line)
+            if item and len(item.group(1)) >= inside:
+                out.append({"command": item.group(2).strip().strip("'\""), "where": "%s:%d" % (rel, i + 1)})
+            elif line.strip():
+                inside = None
+
+
+def tox_nox(rel, name, lines, out, targets):
+    if name == "tox.ini":
+        env = None
+        for i, line in enumerate(lines):
+            sec = re.match(r"^\[(testenv(?::(\S+))?)\]", line)
+            if sec:
+                env = sec.group(2) or "(default)"
+                if sec.group(2):
+                    targets["tox"].add(sec.group(2))
+            elif env and re.match(r"^\s*commands\s*=", line):
+                cmd = line.split("=", 1)[1].strip()
+                out.append({"command": "tox -e %s" % env, "runs": cmd, "where": "%s:%d" % (rel, i + 1)})
+    else:
+        for i, line in enumerate(lines):
+            if re.match(r"^\s*@nox\.session", line):
+                fn = next((re.match(r"^\s*def\s+(\w+)", lines[j]) for j in range(i + 1, min(i + 4, len(lines)))
+                           if re.match(r"^\s*def\s+\w+", lines[j])), None)
+                if fn:
+                    targets["nox"].add(fn.group(1))
+                    body = []
+                    for j in range(i + 1, len(lines)):
+                        if j > i + 1 and re.match(r"^(@|def |class )", lines[j]):
+                            break
+                        body.append(lines[j])
+                    runs = [b.strip() for b in body if "session.run(" in b]
+                    out.append({"command": "nox -s %s" % fn.group(1), "runs": "; ".join(runs),
+                                "where": "%s:%d" % (rel, i + 1)})
+
+
+def pyproject(rel, lines, out, entries):
+    table = ""
+    for i, line in enumerate(lines):
+        sec = re.match(r"^\[([^\]]+)\]", line)
+        if sec:
+            table = sec.group(1).strip()
+            continue
+        kv = re.match(r"^\s*([\w.-]+)\s*=\s*(.+)$", line)
+        if not kv:
+            continue
+        if table in ("project.scripts", "tool.poetry.scripts"):
+            entries.append({"what": "console script `%s`" % kv.group(1), "target": kv.group(2).strip('"\''),
+                            "where": "%s:%d" % (rel, i + 1)})
+        elif table.startswith("tool.hatch.envs.") and table.endswith(".scripts"):
+            out.append({"command": "hatch run %s" % kv.group(1), "runs": kv.group(2),
+                        "where": "%s:%d" % (rel, i + 1)})
+        elif table == "tool.pytest.ini_options" and kv.group(1) in ("addopts", "testpaths", "markers"):
+            out.append({"command": "(pytest config) %s" % kv.group(1), "runs": kv.group(2),
+                        "where": "%s:%d" % (rel, i + 1)})
+
+
+def doc_commands(root, rel, lines, targets, missing):
+    fence = False
+    for i, line in enumerate(lines):
+        if line.strip().startswith("```"):
+            fence = not fence
+            continue
+        indented = line.startswith(("    ", "\t")) and not line.lstrip().startswith(("-", "*"))
+        if fence or indented:
+            candidates = [line.strip().lstrip("$ ").strip()]
+        else:
+            candidates = re.findall(r"`([^`]+)`", line)
+        for cand in candidates:
+            words = cand.split()
+            if len(words) > 1 and words[0] in ("python", "python3") and words[1].endswith(".py"):
+                if not os.path.exists(os.path.join(root, words[1])):
+                    missing.append({"command": cand, "where": "%s:%d" % (rel, i + 1),
+                                    "why": "`%s` does not exist" % words[1]})
+                continue
+            if len(words) < 2 and not (words and words[0] in ("make", "just")):
+                continue
+            if not words or words[0] not in RUNNERS:
+                continue
+            runner, target = words[0], None
+            if runner in ("npm", "pnpm") and len(words) > 1:
+                target = words[2] if words[1] == "run" and len(words) > 2 else (
+                    words[1] if words[1] in ("test", "start") else None)
+                runner = "npm"
+            elif runner == "yarn" and len(words) > 1 and words[1] not in ("install", "add"):
+                target = words[2] if words[1] == "run" and len(words) > 2 else words[1]
+                runner = "npm"
+            elif runner in ("make", "just"):
+                target = words[1] if len(words) > 1 else None
+            elif runner == "nox" and "-s" in words:
+                target = words[words.index("-s") + 1] if words.index("-s") + 1 < len(words) else None
+            elif runner == "tox" and "-e" in words:
+                target = words[words.index("-e") + 1] if words.index("-e") + 1 < len(words) else None
+            if runner in ("make", "just") and target is None:
+                if not targets[runner]:
+                    missing.append({"command": cand, "where": "%s:%d" % (rel, i + 1),
+                                    "why": "no %s file defines any target" % runner})
+                continue
+            if target and target not in targets[runner]:
+                source = {"npm": "package.json scripts", "make": "a Makefile", "just": "a justfile",
+                          "nox": "noxfile.py", "tox": "tox.ini"}[runner]
+                missing.append({"command": cand, "where": "%s:%d" % (rel, i + 1),
+                                "why": "`%s` is not defined in %s" % (target, source)})
+
+
+def doc_paths(root, rel, lines, missing):
+    for i, line in enumerate(lines):
+        for cand in re.findall(r"`([^`\s]+)`", line):
+            looks_like_path = "/" in cand or re.search(r"\.(json|ya?ml|toml|ini|cfg|py|[jt]sx?|go|rb|sql|md)$", cand)
+            if not looks_like_path or cand.startswith(("http", "-", "@", "$")) or "*" in cand or "<" in cand:
+                continue
+            if not os.path.exists(os.path.join(root, cand.strip("/"))):
+                missing.append({"path": cand, "where": "%s:%d" % (rel, i + 1)})
+
+
+def collect(root):
+    facts = {"manifests": [], "commands": [], "doc_commands_not_found": [], "doc_paths_not_found": [],
+             "entry_points": [],
+             "tests": {}, "test_config": [], "generated": [], "vendored": [], "lockfiles": [],
+             "env_vars": [], "largest_dirs": []}
+    targets = defaultdict(set)
+    docs, dir_count, tests = [], Counter(), defaultdict(int)
+    for rel, full in walk(root):
+        name = os.path.basename(rel)
+        parts = rel.split("/")
+        dir_count["/".join(parts[:2]) if len(parts) > 2 else (parts[0] if len(parts) > 1 else ".")] += 1
+        vend = next((p for p in parts[:-1] if p in VENDOR_DIRS), None)
+        if vend:
+            vdir = "/".join(parts[:parts.index(vend) + 1])
+            if vdir not in facts["vendored"]:
+                facts["vendored"].append(vdir)
+            continue
+        if name in LOCKFILES:
+            facts["lockfiles"].append(rel)
+            continue
+        ext = os.path.splitext(name)[1].lower()
+        is_ci = rel.startswith(".github/workflows/") and ext in (".yml", ".yaml")
+        is_gitlab = name == ".gitlab-ci.yml"
+        if name in MANIFESTS or is_ci or is_gitlab or name.lower().startswith("readme"):
+            facts["manifests"].append(rel)
+        if TEST_FILE.search(name):
+            tests["/".join(parts[:-1]) or "."] += 1
+        if TEST_CONFIG.match(name):
+            facts["test_config"].append(rel)
+        wanted = (name in MANIFESTS or is_ci or is_gitlab or ext in SOURCE_EXT or name == ".gitattributes"
+                  or name.lower().startswith("readme") or ext in (".md", ".yml", ".yaml", ".json", ".sql",
+                                                                 ".toml", ".cfg", ".ini", ".proto"))
+        if not wanted:
+            continue
+        lines = read_lines(full)
+        if not lines:
+            continue
+        if name == "package.json":
+            for key, val, where in package_scripts(rel, lines, facts["commands"], targets):
+                facts["entry_points"].append({"what": "package.json %s" % key, "target": val, "where": where})
+        elif name in ("Makefile", "makefile", "GNUmakefile"):
+            make_targets(rel, lines, facts["commands"], targets, "make")
+        elif name == "justfile":
+            make_targets(rel, lines, facts["commands"], targets, "just")
+        elif is_ci:
+            ci_steps(rel, lines, facts["commands"])
+        elif is_gitlab:
+            gitlab_steps(rel, lines, facts["commands"])
+        elif name in ("tox.ini", "noxfile.py"):
+            tox_nox(rel, name, lines, facts["commands"], targets)
+        elif name == "pyproject.toml":
+            pyproject(rel, lines, facts["commands"], facts["entry_points"])
+        elif name == "Dockerfile":
+            for i, line in enumerate(lines):
+                if re.match(r"^\s*(CMD|ENTRYPOINT)\b", line):
+                    facts["entry_points"].append({"what": "Dockerfile", "target": line.strip(),
+                                                  "where": "%s:%d" % (rel, i + 1)})
+        elif name == ".gitattributes":
+            for i, line in enumerate(lines):
+                if "linguist-generated" in line or "linguist-vendored" in line:
+                    facts["generated"].append({"path": line.split()[0], "marker": line.strip(),
+                                               "where": "%s:%d" % (rel, i + 1)})
+        if name.lower().startswith(("readme", "contributing")) and ext in (".md", ".rst", ""):
+            docs.append((rel, lines))
+        for i, line in enumerate(lines[:10]):
+            if ext in SOURCE_EXT | {".json", ".yml", ".yaml", ".sql", ".toml"} and GENERATED.search(line):
+                facts["generated"].append({"path": rel, "marker": line.strip()[:100], "where": "%s:%d" % (rel, i + 1)})
+                break
+        if ext in SOURCE_EXT:
+            for i, line in enumerate(lines):
+                if (re.match(r"^\s*func main\(\)", line) or re.match(r"^if __name__ == [\"']__main__[\"']", line)):
+                    facts["entry_points"].append({"what": "main", "target": rel, "where": "%s:%d" % (rel, i + 1)})
+                for pat in ENV_READS:
+                    for var in pat.findall(line):
+                        facts["env_vars"].append({"name": var, "where": "%s:%d" % (rel, i + 1)})
+    for rel, lines in docs:
+        doc_commands(root, rel, lines, targets, facts["doc_commands_not_found"])
+        doc_paths(root, rel, lines, facts["doc_paths_not_found"])
+    facts["tests"] = dict(sorted(tests.items()))
+    facts["largest_dirs"] = [{"dir": d, "files": n} for d, n in dir_count.most_common(10)]
+    return facts
+
+
+def render(facts, cap):
+    out = []
+
+    def section(title, items, fmt, empty):
+        out.append("## %s" % title)
+        if not items:
+            out.append("- %s" % empty)
+        for item in items[:cap]:
+            out.append("- " + fmt(item))
+        if len(items) > cap:
+            out.append("- ... %d more (raise --max to see them)" % (len(items) - cap))
+        out.append("")
+
+    out.append("# Repository facts\n")
+    out.append("Where each fact is written down. Nothing here was run.\n")
+    section("Manifests, CI and docs", facts["manifests"], lambda m: "`%s`" % m, "none found")
+    section("Commands the repo defines", facts["commands"],
+            lambda c: "`%s`%s — %s" % (c["command"], (" → `%s`" % c["runs"]) if c.get("runs") else "", c["where"]),
+            "none found: no package scripts, Makefile, CI steps, tox or nox sessions")
+    section("Commands the docs name that nothing defines", facts["doc_commands_not_found"],
+            lambda c: "`%s` — %s — %s" % (c["command"], c["where"], c["why"]), "none")
+    section("Paths the docs name that do not exist", facts["doc_paths_not_found"],
+            lambda p: "`%s` — %s" % (p["path"], p["where"]), "none")
+    section("Entry points", facts["entry_points"],
+            lambda e: "%s: `%s` — %s" % (e["what"], e["target"], e["where"]), "none found")
+    tests = [{"dir": d, "n": n} for d, n in facts["tests"].items()]
+    section("Test files by directory", tests, lambda t: "`%s/` — %d file(s)" % (t["dir"], t["n"]),
+            "no test files found")
+    section("Test runner config", facts["test_config"], lambda t: "`%s`" % t, "none found")
+    section("Generated files", facts["generated"],
+            lambda g: "`%s` — %s — \"%s\"" % (g["path"], g["where"], g["marker"]), "no generated-file markers found")
+    section("Vendored directories", facts["vendored"], lambda v: "`%s/`" % v, "none")
+    section("Lockfiles", facts["lockfiles"], lambda f: "`%s`" % f, "none")
+    section("Environment variables the code reads", facts["env_vars"],
+            lambda e: "`%s` — %s" % (e["name"], e["where"]), "none found")
+    section("Largest directories (file count)", facts["largest_dirs"],
+            lambda d: "`%s` — %d" % (d["dir"], d["files"]), "empty")
+    return "\n".join(out)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="List a repo's commands, tests, generated files and env reads with file:line.")
+    ap.add_argument("root", help="repository root to read")
+    ap.add_argument("--json", action="store_true", help="print JSON instead of Markdown")
+    ap.add_argument("--max", type=int, default=40, help="items per section in Markdown (default 40)")
+    args = ap.parse_args(argv)
+    if not os.path.isdir(args.root):
+        print("error: %s is not a directory" % args.root, file=sys.stderr)
+        return 2
+    facts = collect(args.root)
+    print(json.dumps(facts, indent=2) if args.json else render(facts, max(1, args.max)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/packs/dev-team/skills/codebase-tour/templates/codebase-tour.md

@@ -0,0 +1,85 @@
+# Tour: {repo name}, for {the change, in one line}
+
+_Read on {date}. Scope: {the path from the entry point to the change's far edge}. Skipped on purpose: {areas not on the path, e.g. "the admin UI, the billing service, deployment config"}._
+
+{Any `[assumption]` lines go here, first, one per line.}
+
+<!-- Citation key, for the writer (delete before sending):
+     `path:line` = read there · [inferred] = not verified, reason given ·
+     ran: passed / ran: failed (first error line) / read, not run · derived from <source> -->
+
+## What matters for this change
+
+<!-- 3–5 bullets. The things that change what the person does in the next hour: the README claim that's wrong, the second copy, the generated file, the test gap, the env var it won't start without. Each cites a file. -->
+
+- {…} (`path:line`)
+
+## Run it
+
+<!-- ≤ ~15 lines. Commands only from CI / package scripts / Makefile / tox / nox / pyproject. CI's form wins. -->
+
+| To | Command | Source | Status |
+|---|---|---|---|
+| Install | `{…}` | `{path:line}` | read, not run |
+| Test (whole suite) | `{…}` | `{path:line}` | {ran: passed / ran: failed: … / read, not run} |
+| Test (this area) | `{…}` | derived from `{path:line}` | {…} |
+| Lint / typecheck | `{…}` | `{path:line}` | {…} |
+| Run locally | `{…}` | `{path:line}` | {…} |
+
+Needs: {env vars and services the commands need, each with where it is read or set, e.g. `DATABASE_URL` (`src/config.py:9`; CI sets it at `.github/workflows/ci.yml:14`)}.
+
+## The path this change touches
+
+<!-- ≤ 10 hops, entry point first, stop at the change's far edge. -->
+
+1. `{path:line}` `{function}`: {what happens here}
+2. …
+
+## Where the change goes
+
+<!-- Files and functions, each with the sibling pattern that justifies it. Then everything that must change with it. -->
+
+- `{path}` `{function}`: {what to add} because {sibling pattern, cited}
+- Must change with it: {spec + regenerate command / registry entry / second copy}, (`path:line`)
+
+## Conventions the code follows
+
+<!-- ≤ ~15 lines. Only the ones this change will hit. Each from code, cited. -->
+
+- **Errors:** {…} (`path:line`)
+- **Tests:** {location, naming, fixtures} (`path`)
+- **Config:** {how it is read} (`path:line`)
+- **Naming:** {…} (`path:line`)
+
+## Traps
+
+<!-- Every check reports. "none found" is an answer. -->
+
+- **Generated:** {file} from {source}, regenerate with `{command}` (`path:line`); CI drift check: {yes, `path:line` / none}
+- **Second copy:** {where the same logic lives} (`path:line`), or none found (searched for {identifiers})
+- **Untested on the path:** {functions} or none
+- **Tests the default command skips:** {marker / build tag / glob} (`path:line`) or none
+- **Env vars and flags on the path:** `{NAME}` default {…} (`path:line`)
+- **Vendored:** {…} or none
+
+## Where the README is wrong
+
+<!-- One line each, both citations. Omit the section only if every README claim checked out, and say "README checked: no conflicts." in the scope line instead. -->
+
+- README says {…} (`README.md:{n}`); the code {…} (`path:line`). Follow the code.
+
+## Tests for this area
+
+- Covered by: `{test file}` ({what it asserts})
+- Run just these: `{derived command}` (derived from `{path:line}`)
+- Not covered: {functions with no test}, or "every function on the path has a test"
+
+## First step
+
+{Do X in `path`; run `command`; expect {result}.}
+
+## Open questions for a maintainer
+
+<!-- ≤ 5. Each answerable in a sentence, each pointing at the evidence that raised it. -->
+
+1. {…} (`path:line`)

package/packs/dev-team/skills/dependency-upgrade-review/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: dependency-upgrade-review
+description: Give a merge verdict on a dependency-upgrade pull request (Dependabot, Renovate or a hand-made bump) across npm, pip, Go, Cargo and Maven lockfiles and GitHub Actions pins. Reads the release notes for every skipped version, lists what the lockfile changes beyond the PR title (transitive bumps, new and removed packages, install scripts, registry changes), checks that each SHA pin is the commit its release tag points to, says whether CI ran the changed code, finds the repo's uses of changed APIs and writes the rollback, ending in MERGE, MERGE AFTER CHECKS or DO NOT MERGE. Use when the user says "review this Dependabot PR", "is this Renovate bump safe to merge", "can I merge this dependency upgrade", "check this lockfile diff", or "is this action SHA pin right".
+---
+
+# dependency-upgrade-review
+
+A dependency bump is someone else's code entering the repo under a one-line title. This skill reads it the way a careful maintainer does: every release between the old and new version, every line of the lockfile, every pin, and the tests that would have caught a break. The verdict follows from those checks, not from a green badge. Reviewing the repo's own code changes is `pre-merge-review`; writing the notes for a release of this project is `release-notes`; planning a framework migration across many PRs is `migration-plan`.
+
+## How to respond
+
+**Four rules come before the steps and outrank them:**
+
+- **Answer what was asked, first.** Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
+- **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
+- **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
+- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
+- **For this skill:** A check nobody ran is an open check, written as the command that runs it. It is never reported as passed, and "CI is green" closes only the checks CI actually ran.
+
+1. **Get the diff, the notes and the code, asking once.** Three inputs: the PR diff covering manifests, lockfiles and workflow files (`gh pr diff 212` or `git diff origin/main...HEAD`); the release notes or changelog for every version between old and new; the repo, or at least the files that import the package and the CI workflow files. Ask for what is missing in one message. With network access, fetch missing notes from the package's releases page or changelog; without it, each missing release becomes an open check.
+
+2. **Run the diff script first.** It lists every changed dependency with old → new, semver class, direct or transitive, and flags added and removed packages, install hooks, native-code hints, registry changes, licence changes and pins, then prints a floor verdict.
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/upgrade_diff.py" pr.diff --title "Bump quillmark from 3.4.1 to 4.1.0"
+   # Other IDEs (from the skill folder)
+   python3 scripts/upgrade_diff.py pr.diff --title "Bump quillmark from 3.4.1 to 4.1.0"
+   ```
+   It reads stdin with `-` (`gh pr diff 212 | python3 scripts/upgrade_diff.py -`). If it reports version lines out of context, re-run on `git diff -U12`. If no script can run, read every lockfile hunk by hand with the per-ecosystem notes in [`reference.md`](reference.md).
+
+3. **List everything the lockfile changes beyond the title.** The title names one package; the lockfile is the truth. Report each of: transitive bumps (with class), packages added, packages removed, new install scripts (`hasInstallScript: true`, a `preinstall` / `install` / `postinstall` / `prepare` hook, pnpm `requiresBuild: true`), new native or binary dependencies (`prebuild-install`, `node-gyp`, a Cargo `-sys` crate), a changed `resolved` / `source` / index URL, and a maintainer or publisher change when the input shows one. ✅ *"Also changes: `entity-codec` 2.1.0 → 3.0.2 (major, licence MIT → MPL-2.0), adds `quill-native-highlight` 1.0.0 with an install script, removes `html-escape-lite`."* ❌ *"Bumps quillmark to 4.1.0."*
+
+4. **Class each jump.** Major, minor or patch from the version numbers. Below 1.0 the minor is the breaking number: 0.8.3 → 0.9.0 is a breaking jump, and below 0.1 so is the patch. A Go module path gaining `/v2` is a new module, not a bump. A prerelease target (`-rc.1`, `-beta`) or a downgrade is never a plain MERGE. A moving major tag (`@v2` → `@v3`) spans every v2.x after the one in use plus v3.0.0 to the current v3.
+
+5. **Read every release between old and new, not only the target.** For each direct dependency, list every release after the old version up to and including the new one, and pull four things from each: breaking changes, deprecations, security fixes, licence changes. Transitive majors, 0.x breaking jumps and new packages get the same reading; transitive patch and minor bumps are listed, not read. Name each release whose notes are missing. ✅ *"3.5.0 fixes an attribute-injection bug in link titles and deprecates `setOptions()`; 4.0.0 removes `renderInline()` and turns `sanitize` off by default; 4.0.1 and 4.1.0 are fixes and an optional highlighter."* ❌ *"4.1.0 adds a native highlighter. Looks fine."* A security fix is a reason to take the upgrade; when the full jump is blocked, name the smallest version that carries the fix as the alternative.
+
+6. **Search the repo for every API the notes change.** For each removed or renamed function, changed signature and changed default, search and report `file:line` for each hit, or "no hits". A changed default hits every call that doesn't pass the option. ✅ *"`src/render/note.js:7` calls `quillmark.render(markdown)` with no `sanitize`, so from 4.0.0 note bodies pass raw HTML through."* ❌ *"Check whether the code uses `renderInline`."* Give the search you ran (`git grep -n -E "renderInline|setOptions|render\(" -- '*.js' '*.ts'`); with no repo in hand, give that command as an open check and claim neither hits nor no hits.
+
+7. **Verify every pin; an unverified SHA is an open check.** For a SHA-pinned action (or any dependency pinned to a commit), the pinned SHA must be the commit the release tag points to:
+   ```bash
+   git ls-remote https://github.com/<owner>/<repo> refs/tags/<tag> 'refs/tags/<tag>^{}'
+   ```
+   For an annotated tag the `^{}` line is the commit; the other line is the tag object. For a lightweight tag the single line is the commit. Not run means `UNVERIFIED`, never "looks right": a SHA from a fork of the repo also resolves under the upstream path. A SHA with no version comment is an unknown release. A tag-only pin (`@v3`) moved to another tag is weaker than a SHA, because the tag can be moved after review; say so and give the command that finds the SHA to pin. Say what the job hands the action: a `secrets.*` token, `id-token: write` or `contents: write` raises the stakes of every pin in that job.
+
+8. **Say whether CI ran the changed code.** A green check proves what it ran and nothing else. For each changed package or action, name the workflow job and test file that exercise it, or say nothing does. The usual gaps: an action or tool used only in a workflow triggered by a tag push, a release, a schedule or `workflow_dispatch`, which the PR never ran; a library used only in a file no test imports (a step 6 hit with no test); a test that runs the code but not the changed behaviour. ✅ *"`ci / test` runs `test/note.test.js`, which renders Markdown with no raw HTML, so the `sanitize` change is untested; nothing imports `src/render/comment.js`."* ❌ *"All checks pass."*
+
+9. **Write the rollback.** The exact revert: `git revert` of the merge commit, or the pin-back for the ecosystem (`npm install quillmark@3.4.1`, `poetry add tidyparse@2.2.0`, `go get <module>@v0.8.3 && go mod tidy`, `cargo update -p <crate> --precise <old>`, the old `uses:` line) with the lockfile regenerated and committed. Then name what a revert does not undo: a lockfile format migration, a data, cache or schema format the new version wrote, an artifact built or published with it (a registry version cannot be republished), and a security fix that rolling back reopens. When the old version sits inside a fixed advisory's range, the pin-back target is the first fixed version, not the old one: ✅ *"pin back to 3.5.0"* ❌ *"pin back to 3.4.1"* when 3.5.0 fixed a bug affecting 3.0.0 to 3.4.x. Per-ecosystem commands are in [`reference.md`](reference.md).
+
+10. **Derive the verdict from the checks.** Exactly one of:
+    - **DO NOT MERGE** when any holds: a removed or changed API is still used and the PR does not fix it; a new install script or native binary download nobody has confirmed is expected; a dependency source or registry moved to an unexplained host; a SHA that does not match its tag; a pin weakened (SHA to tag, tag to branch); a licence the project cannot ship; a target version an advisory names as vulnerable; a red CI check.
+    - **MERGE AFTER CHECKS** when none of those holds but any of these does: an unverified SHA; a major or 0.x breaking jump; a release whose notes were not read; changed code no CI job runs; a deprecated API still used; a new package or transitive major; a licence change that needs sign-off; a moved tag-only pin; no repo to search. Each check is a command or a concrete action.
+    - **MERGE** only when every check above is closed, with the evidence in the reply.
+    The script's floor is a minimum. Raise it on what steps 5 to 8 find. Lower DO NOT MERGE only when the user confirms the install script or new source is expected, and say so in the reply.
+
+11. **Reply in this order, in one message:** the verdict and the one reason that decides it; 🟥 blockers, 🟧 checks before merge and 🟨 notes, each with `file:line` or the command; a short table of what the PR changes, including everything beyond the title; the rollback; "To confirm". A routine PR fits in about 300 words. Lead with what blocks, not with the package history.
+
+**Non-interactive runs** (subagent, CI, headless): with no diff, emit `BLOCKED: need the PR diff covering the manifests, lockfiles and workflow files (gh pr diff <number>)`. Missing release notes, repo or CI files do not block: each becomes a named open check, the verdict is at best MERGE AFTER CHECKS, and the gap is stated first as `[assumption] notes for <versions> not read` or `[assumption] CI coverage unknown, treated as none`.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md): reading each ecosystem's lockfile diff, where install scripts and sources show up, how to list the releases between two versions, SHA verification details, and per-ecosystem rollback commands with what a revert leaves behind
+- [`scripts/upgrade_diff.py`](scripts/upgrade_diff.py): stdlib parser for a unified diff of manifests, lockfiles and workflow files; prints changes, flags, pin checks and a floor verdict (exit 2 on bad input)
+- [`examples/ledgerline-tidyparse.md`](examples/ledgerline-tidyparse.md): worked example, a Poetry patch bump with a transitive bump, real script output and the review that reaches MERGE
+
+## Quality bar
+
+- **Exactly one verdict, first, and it follows from the checks.** Any unverified SHA, added install script, or removed API still in use rules out MERGE.
+- **Every release between old and new is accounted for:** read, with its breaking changes, deprecations, security fixes and licence changes named, or listed as unread.
+- **Everything the lockfile changes beyond the title is listed:** transitive bumps, added and removed packages, install scripts, native code, source changes.
+- **Every changed API has a search result:** `file:line` hits, "no hits", or the command to run when there is no repo.
+- **Every SHA pin is verified or marked UNVERIFIED with the `git ls-remote` command;** tag-only pins are called weaker.
+- **CI coverage is named per changed package:** the job and test that exercise it, or "nothing does".
+- **A rollback with the exact command** and what a revert does not undo.
+- **No invented versions, advisories, APIs, files or test names.** Everything cited appears in the diff, the notes or the repo supplied.
+
+## When to use this skill
+
+- ✅ A Dependabot or Renovate PR is open and someone asks whether to merge it
+- ✅ A hand-made bump of one or more packages, with its lockfile diff
+- ✅ A GitHub Actions version bump, SHA-pinned or tag-pinned
+- ✅ A grouped update PR where the title hides how many packages moved
+- ✅ Checking whether a lockfile diff brings in install scripts, new registries or new packages
+
+## When NOT to use this skill
+
+- ❌ Reviewing a PR whose substance is the repo's own code change: use `pre-merge-review`
+- ❌ Writing the release notes or changelog for this project's next version: use `release-notes`
+- ❌ Planning a multi-step framework or runtime migration (a major framework version across many services): use `migration-plan`
+- ❌ Scanning installed skills for supply-chain patterns: that is the `skilldrop scan` command
+- ❌ Choosing which library to adopt in the first place: this reviews a version change, not a selection
+
+## Anti-patterns to avoid
+
+- ❌ **Reading only the target version's notes.** The breaking change usually lives in a release the PR skipped.
+- ❌ **Trusting the title.** "Bump X from 1 to 2" says nothing about the twelve transitive packages that moved with it.
+- ❌ **Calling a SHA pin fine because it is a SHA.** A SHA proves nothing until it matches the release tag.
+- ❌ **"CI is green, ship it."** Release workflows, publish steps and untested code paths never ran on the PR.
+- ❌ **"No breaking changes affect us" without a search.** Show the grep and its hits, or say it was not run.
+- ❌ **A rollback that is only "revert the PR".** Name the lockfile regeneration and what a revert leaves behind.
+- ❌ **Reciting the changelog.** Report the releases that change the verdict; one line covers the rest.
+- ❌ **Hedged verdicts.** "Probably safe" is not a verdict; pick one of the three and give the reason.

package/packs/dev-team/skills/dependency-upgrade-review/evals/eval_queries.json

@@ -0,0 +1,11 @@
+[
+  { "query": "Dependabot wants to bump express from 4.19 to 5.0, can I merge the PR?", "should_trigger": true },
+  { "query": "review this Renovate PR, it updates 14 packages in package-lock.json", "should_trigger": true },
+  { "query": "is this actions/checkout SHA pin in the dependabot PR actually the v4.2.2 commit?", "should_trigger": true },
+  { "query": "I bumped pydantic and regenerated poetry.lock, anything in the lockfile diff I should worry about before merging?", "should_trigger": true },
+  { "query": "check this go.mod / go.sum diff from the deps update PR, CI is green", "should_trigger": true },
+  { "query": "review my PR that adds rate limiting to the checkout API before I merge", "should_trigger": false },
+  { "query": "write the release notes for our 3.2.0 release from the merged PRs", "should_trigger": false },
+  { "query": "plan our migration from React 17 to React 19 across the four frontend apps", "should_trigger": false },
+  { "query": "scan the skills I'm about to install for risky scripts", "should_trigger": false }
+]