@booklib/skills 1.5.1 → 1.6.0

package/CONTRIBUTING.md

@@ -95,7 +95,27 @@ Aim for 3–5 evals per skill covering:
 2. A subtle or intermediate case
 3. Already-good code (the agent should recognize it and not manufacture issues)
 
-### 5. Submit a PR
+### 5. Run evals and commit results
+
+```bash
+ANTHROPIC_API_KEY=your-key npx @booklib/skills eval <name>
+```
+
+This runs each eval **with and without** the skill and writes `evals/results.json`. Commit this file — it is how CI and readers verify the skill actually works.
+
+**Quality thresholds** (calibrated to `claude-haiku-4-5` as judge):
+
+| Metric | Minimum | Good | Excellent |
+|--------|---------|------|-----------|
+| Pass rate (with skill) | ≥ 80% | ≥ 85% | ≥ 90% |
+| Delta over baseline | ≥ 20pp | ≥ 25pp | ≥ 30pp |
+| Baseline (without skill) | any | < 70% | < 60% |
+
+A high delta matters as much as a high pass rate — it proves the skill is doing real work, not just measuring what Claude already knows. A skill with 90% pass rate and 5pp delta is less valuable than one with 85% and 30pp delta.
+
+The 80% threshold is calibrated to the judge model's own noise floor. Consistently hitting 80%+ with haiku as judge means the skill reliably catches what it claims to catch.
+
+### 6. Submit a PR
 
 ```bash
 git checkout -b skill/book-name
@@ -111,6 +131,8 @@ PR checklist:
 - [ ] SKILL.md is under 500 lines
 - [ ] `examples/before.md` and `examples/after.md` exist
 - [ ] `evals/evals.json` has at least 3 test cases
+- [ ] `evals/results.json` committed (run `npx @booklib/skills eval <name>`)
+- [ ] Pass rate ≥ 80% and delta ≥ 20pp in results.json
 - [ ] README.md skills table updated
 
 ## Requesting a skill

package/README.md

@@ -118,6 +118,8 @@ User: "Review my order processing service"
 
 This means skills compose: `skill-router` acts as an orchestrator that picks the right specialist skills for the context, without requiring the user to know the library upfront.
 
+**See it in action:** The [`benchmark/`](./benchmark/) folder contains a head-to-head comparison — same buggy Node.js file reviewed by the native PR toolkit vs. `skill-router` routing to `clean-code-reviewer` + `design-patterns`. The skill-router pipeline finds ~47% more unique issues and adds a full refactor roadmap with pattern sequence.
+
 ## Skills
 
 | Skill | Description |
@@ -145,6 +147,59 @@ This means skills compose: `skill-router` acts as an orchestrator that picks the
 | 🔄 [using-asyncio-python](./skills/using-asyncio-python/) | Asyncio practices from Caleb Hattingh's *Using Asyncio in Python* — coroutines, event loop, tasks, and signal handling |
 | 🕷️ [web-scraping-python](./skills/web-scraping-python/) | Web scraping practices from Ryan Mitchell's *Web Scraping with Python* — BeautifulSoup, Scrapy, and data storage |
 
+## Quality
+
+Skills are evaluated against 6–15 test cases each, run both **with** and **without** the skill using `claude-haiku-4-5` as model and judge. The delta over baseline is the key signal — it measures how much the skill actually improves Claude's output beyond what it can do unaided.
+
+**Thresholds:** pass rate ≥ 80% · delta ≥ 20pp · baseline < 70%
+
+<!-- quality-table-start -->
+| Skill | Pass Rate | Baseline | Delta | Evals | Last Run |
+|-------|-----------|----------|-------|-------|----------|
+| animation-at-work | — | — | — | — | — |
+| clean-code-reviewer | — | — | — | — | — |
+| data-intensive-patterns | — | — | — | — | — |
+| data-pipelines | — | — | — | — | — |
+| design-patterns | — | — | — | — | — |
+| domain-driven-design | — | — | — | — | — |
+| effective-java | — | — | — | — | — |
+| effective-kotlin | — | — | — | — | — |
+| effective-python | — | — | — | — | — |
+| effective-typescript | — | — | — | — | — |
+| kotlin-in-action | — | — | — | — | — |
+| lean-startup | — | — | — | — | — |
+| microservices-patterns | — | — | — | — | — |
+| programming-with-rust | — | — | — | — | — |
+| refactoring-ui | — | — | — | — | — |
+| rust-in-action | — | — | — | — | — |
+| skill-router | — | — | — | — | — |
+| spring-boot-in-action | — | — | — | — | — |
+| storytelling-with-data | — | — | — | — | — |
+| system-design-interview | — | — | — | — | — |
+| using-asyncio-python | — | — | — | — | — |
+| web-scraping-python | — | — | — | — | — |
+<!-- quality-table-end -->
+
+Results are stored in each skill's `evals/results.json` and updated by running `npx @booklib/skills eval <name>`.
+
+## Contributing a skill
+
+If you've read a book that belongs here, you can add it. The bar is lower than you think:
+
+```bash
+# 1. Copy an existing skill as a template
+cp -r skills/clean-code-reviewer skills/your-book-name
+
+# 2. Edit SKILL.md, examples/, and evals/
+
+# 3. Validate before opening a PR
+npx @booklib/skills check your-book-name
+```
+
+The `check` command runs all evals and reports what passes and fails — you get a quality signal before anyone else sees the PR. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.
+
+**Books with open issues** (tagged `good first issue`): [The Pragmatic Programmer](https://github.com/booklib-ai/skills/issues/2) · [Clean Architecture](https://github.com/booklib-ai/skills/issues/3) · [A Philosophy of Software Design](https://github.com/booklib-ai/skills/issues/4) · [Accelerate](https://github.com/booklib-ai/skills/issues/8) · [and more →](https://github.com/booklib-ai/skills/issues?q=is%3Aopen+label%3A%22good+first+issue%22)
+
 ## License
 
 MIT

package/benchmark/devto-post.md

@@ -0,0 +1,178 @@
+# How I Route AI Agents to the Right Code Review Context
+
+You gave Claude Code a Clean Code checklist. It reviewed your order processing service and told you to rename `proc` to `processOrder` and split a 22-line function into three.
+
+Meanwhile, the actual problem — your aggregate boundary is wrong and you're leaking domain logic into the API layer — went completely unnoticed.
+
+This isn't an AI failure. It's a routing failure. The agent applied the wrong lens.
+
+## The Problem: Context Collapse
+
+If you give an AI agent a broad set of review instructions, two things happen:
+
+**Token waste** — the agent reads through hundreds of lines of principles that don't apply to the file at hand.
+
+**Wrong focus** — a Clean Code reviewer will nitpick naming on a file where the real issue is a broken domain model. A DDD reviewer will talk about bounded contexts on a utility function that just needs cleaner variable names.
+
+This is what one Hacker News commenter called context collapse: "Clean Code was written for Java in 2008. DDIA is about distributed systems at scale. If you apply the Clean Code reviewer to a 50-line Python script, you'll get pedantic nonsense about function length when the actual problem might be that the data model is wrong."
+
+The criticism is valid. The fix isn't to abandon structured review — it's to pick the right structure for the file in front of you.
+
+## The Approach: A Router That Picks the Reviewer
+
+I've been building a collection of "skills" — structured instruction sets distilled from classic software engineering books (Clean Code, DDIA, Effective Java, DDD, etc.). Each one is a focused lens that an AI agent uses during code review or code generation.
+
+The key piece is a `skill-router`: a meta-skill that runs before any review happens. It inspects:
+
+- File type and language — Kotlin? Python? Infrastructure config?
+- Domain signals — is this a service layer? A repository? A controller?
+- Work type — code review, refactoring, greenfield design, or bug fix?
+
+Based on that, it selects the 1–2 most relevant skills and explicitly skips the rest.
+
+## Example in Practice
+
+User: "Review my order processing service"
+
+```
+Router decision:
+  ✅ Primary:   domain-driven-design    — domain model design (Aggregates, Value Objects)
+  ✅ Secondary: microservices-patterns  — service boundaries and inter-service communication
+  ⛔ Skip:      clean-code-reviewer     — premature at design stage; apply later on implementation code
+```
+
+The router doesn't just pick — it explains why it skipped alternatives. That rationale is important: it makes the selection auditable, and you can override it if you disagree.
+
+## Why Not Just Use One Giant Prompt?
+
+You could stuff everything into one system prompt. I tried. Here's what happens:
+
+**Attention dilution** — the model tries to apply everything at once and produces shallow, generic feedback.
+
+**Conflicting advice** — Clean Code says "extract small functions." Some microservices patterns say "prefer cohesive, slightly larger functions over deep call stacks." The model hedges between both.
+
+**Token budget** — if you're working in Claude Code or Cursor, every token of instructions competes with your actual code context.
+
+Routing means the agent reads ~200 focused lines of instructions instead of ~2000 unfocused ones.
+
+## The Alternative Criticism: "LLMs Already Know These Books"
+
+This is the most common pushback I get. And it's partially true — LLMs have read Clean Code. But they apply that knowledge inconsistently and at low confidence.
+
+Giving the model an explicit lens — "review this against Clean Code heuristics C1–C36" — concentrates attention and dramatically reduces hallucinated or off-topic feedback. It's the difference between asking someone "what do you think?" vs. "evaluate this against these specific criteria."
+
+Think of it like unit tests: the runtime can execute your code correctly without them. But tests make correctness explicit, repeatable, and auditable. Skills do the same for AI review.
+
+## How the Routing Actually Works
+
+The router skill is a structured prompt with a decision tree:
+
+1. Parse the request — what file(s), what task
+2. Match against skill metadata — each skill declares its applicable languages, domains, and work types
+3. Rank by relevance — primary (strongest match) and secondary (complementary perspective)
+4. Conflict resolution — if two skills would give contradictory advice, prefer the one matching the higher abstraction level of the task
+5. Return selection with rationale
+
+There's no ML model or embedding search involved. It's structured prompting — the LLM acts as the routing engine using routing rules baked into the router's own instructions. Language signals, domain signals, and conflict resolution are all declared explicitly inside the router skill, not inferred at runtime. The trade-off: it's fast and predictable, but adding a new skill requires updating the router manually.
+
+## Levels of Review (a Pattern Worth Stealing)
+
+One of the most useful ideas that came from community feedback: separate your review into levels of critique:
+
+1. A fast "lint" pass — formatting, obvious bugs, missing tests
+2. A domain pass — does the code correctly model the business logic?
+3. A "counterexample" pass — propose at least one concrete failing scenario and how to reproduce it
+
+The skill library maps roughly to these levels — Clean Code for level 1, DDD for level 2 — but you have to invoke them separately with the right framing. The router picks based on what the code *is*, not which level you're at. Explicit level-based routing isn't built yet. The counterexample pass is harder and something I'm still figuring out.
+
+## Try It Yourself
+
+The skills and the router are open source: [github.com/booklib-ai/skills](https://github.com/booklib-ai/skills)
+
+You can use them with Claude Code, Cursor, or any agent that supports SKILL.md files. The quickest way to try it — install everything and let the router decide:
+
+```bash
+npx @booklib/skills add --all
+```
+
+Or globally, so it's available in every project:
+
+```bash
+npx @booklib/skills add --all --global
+```
+
+Then just ask your agent to review a file — the router picks the right skill automatically. You don't need to know the library upfront.
+
+## Benchmark: Routed Skills vs. Native Review
+
+Theory is nice. Does it actually find more issues?
+
+I took a deliberately terrible 157-line Node.js order processing module — god function, SQL injection on every query, global mutable state, `eval()` for no reason — and ran it through two pipelines in parallel:
+
+- **Native:** Claude's built-in `pr-review-toolkit:code-reviewer`
+- **skill-router:** `skill-router` → `clean-code-reviewer` + `design-patterns`
+
+### What the router chose
+
+```
+Primary:    clean-code-reviewer  — god function, cryptic names, magic numbers
+Secondary:  design-patterns      — duplicated payment blocks → Strategy pattern
+Skipped:    domain-driven-design — implementation level, not model design stage
+```
+
+### Issue detection
+
+|  | Native | skill-router |
+|---|---|---|
+| Critical/High issues | 7 | 8 |
+| Important/Improvement | 10 | 14 |
+| Suggestions | 0 | 5 |
+| **Total unique issues** | **19** | **~28** |
+
+~89% of what Claude's native reviewer found, skill-router also found. But skill-router found ~9 additional issues that the native reviewer missed entirely.
+
+A few that stood out:
+
+> **`formatMoney` has a floating-point rounding bug** — `0.1 + 0.2` arithmetic, not `Math.round`. Native didn't flag it; clean-code-reviewer caught it via the G-series heuristics.
+
+> **The stubs always return `true`** — they're lying to callers. Native missed it; clean-code-reviewer flagged it as a lying comment / false contract.
+
+> **skill-router surfaced 7 pattern opportunities** — places where a known pattern could reduce complexity (Strategy for payments, State for order lifecycle, Singleton for the broken global state). It explains the problem each one solves and suggests a fix sequence, but leaves the decision to you. Native produced no architectural guidance at all.
+
+### Where each approach wins
+
+| Situation | Use |
+|---|---|
+| Pre-merge PR review, security audit | **Native** — pre-merge gate: fast, confidence-filtered, adapts to your CLAUDE.md project conventions |
+| Larger refactor, architecture planning | **skill-router** — patterns, principles, refactor roadmap |
+| Both together | ~95% total issue coverage vs. ~80% for either alone |
+
+**One honest loss for skill-router:** Card data was being logged to stdout — a clear PCI violation. Claude's built-in reviewer flagged it at 92% confidence. skill-router didn't. Security compliance isn't in any book-based skill's scope, and the router has no way to know it should care. If compliance is the priority, the native reviewer is the right tool.
+
+After looking closely at how both tools are built, the difference in purpose becomes clear.
+
+The native reviewer runs **6 parallel sub-agents**, each focused on one category: code quality, silent failures, type design, test coverage, comment accuracy, and security. It defaults to reviewing only the current `git diff` — not the whole file. Before starting, it reads your `CLAUDE.md` to pick up project conventions. And it discards any finding below 80% confidence, so output arrives pre-filtered. That's a purpose-built pre-merge gate: narrow scope, parallel specialists, high signal-to-noise.
+
+skill-router does the opposite: one agent, one deeply focused skill, applied to the whole module. It trades breadth and speed for depth and principle grounding.
+
+They target different moments in the development lifecycle, which is why using both gives ~95% coverage.
+
+One gap this benchmark exposed was the noise filtering: Claude's native reviewer discards anything below 80% confidence; skill-router had no equivalent. Since writing this, the router has been updated to instruct selected skills to classify every finding as HIGH / MEDIUM / LOW and skip LOW-tier findings on standard reviews — same idea, book-grounded framing instead of a confidence score.
+
+The full before/after code and comparison report are in the repo under [`/benchmark/`](https://github.com/booklib-ai/skills/tree/main/benchmark).
+
+## Open Questions
+
+I don't have everything figured out. A few things I'm still exploring:
+
+**Sub-agent architecture** — the native pr-review-toolkit runs 6 parallel sub-agents (tests, types, silent failures, comments, etc.), each a focused specialist. skill-router takes the opposite approach: one agent, one focused skill, narrow scope. Both work, but for different reasons. The open question is whether a *generate-then-evaluate* loop — one agent produces code using a skill's patterns, a second agent checks it against the same skill's rubric — would catch more issues than a single-pass review. My current answer is no for code review, maybe for code generation. If you've tried this pattern, I'd like to know what you found.
+
+**Feedback loops** — the benchmark above is one data point. How do you systematically measure whether routing improves review quality across different codebases and languages?
+
+**Domain-specific routing** — healthcare code, fintech code, and game code each have very different "what matters most" priorities. Should routing consider the project domain, not just the file?
+
+If you've been working on similar problems — structured AI review, skill selection, multi-agent evaluation — I'd love to hear what's working for you.
+
+---
+
+*Currently covering: Clean Code, Domain-Driven Design, Effective Java, Effective Kotlin, Microservices Patterns, System Design Interview, Storytelling with Data, and more. Skills are community-contributed and new books are welcome.*

package/benchmark/order-processing.original.js

@@ -0,0 +1,158 @@
+// order processing thing
+// ORIGINAL — intentionally bad code. Do not use in production.
+
+var db = require('./db')
+var mailer = require('./mailer')
+
+var discount = 0.1
+var TAX = 0.23
+var items = []
+var total = 0
+var usr = null
+
+function process(o, u, pay, s) {
+    usr = u
+    if (u != null) {
+        if (u.active == true) {
+            if (o != null) {
+                if (o.items != null && o.items.length > 0) {
+                    var t = 0
+                    for (var i = 0; i < o.items.length; i++) {
+                        var item = o.items[i]
+                        if (item.qty > 0) {
+                            if (item.price > 0) {
+                                t = t + (item.qty * item.price)
+                                items.push(item)
+                            }
+                        }
+                    }
+                    if (u.type == "premium") {
+                        t = t - (t * 0.1)
+                    }
+                    if (u.type == "vip") {
+                        t = t - (t * 0.2)
+                    }
+                    if (u.type == "staff") {
+                        t = t - (t * 0.5)
+                    }
+                    total = t + (t * TAX)
+                    if (pay == "card") {
+                        var res = chargeCard(u.card, total)
+                        if (res == true) {
+                            var q = "INSERT INTO orders VALUES ('" + o.id + "', '" + u.id + "', " + total + ", 'paid')"
+                            db.query(q)
+                            mailer.send(u.email, "Order confirmed", "ur order is confirmed lol total: " + total)
+                            s.orders++
+                            s.revenue = s.revenue + total
+                            return true
+                        } else {
+                            return false
+                        }
+                    }
+                    if (pay == "paypal") {
+                        var res2 = chargePaypal(u.paypal, total)
+                        if (res2 == true) {
+                            var q2 = "INSERT INTO orders VALUES ('" + o.id + "', '" + u.id + "', " + total + ", 'paid')"
+                            db.query(q2)
+                            mailer.send(u.email, "Order confirmed", "ur order is confirmed lol total: " + total)
+                            s.orders++
+                            s.revenue = s.revenue + total
+                            return true
+                        } else {
+                            return false
+                        }
+                    }
+                    if (pay == "crypto") {
+                        // TODO: implement this someday
+                        return false
+                    }
+                } else {
+                    return false
+                }
+            } else {
+                return false
+            }
+        } else {
+            return false
+        }
+    } else {
+        return false
+    }
+}
+
+function chargeCard(card, amt) {
+    // just assume it works
+    console.log("charging card " + card + " for " + amt)
+    return true
+}
+
+function chargePaypal(pp, amt) {
+    console.log("paypal " + pp + " " + amt)
+    return true
+}
+
+// get user orders
+function getOrds(uid) {
+    var q = "SELECT * FROM orders WHERE user_id = '" + uid + "'"
+    return db.query(q)
+}
+
+// cancel
+function cancel(oid, uid, rsn) {
+    var q = "SELECT * FROM orders WHERE id = '" + oid + "'"
+    var ord = db.query(q)
+    if (ord != null) {
+        if (ord.user_id == uid) {
+            if (ord.status != "cancelled") {
+                if (ord.status != "shipped") {
+                    if (ord.status != "delivered") {
+                        var q2 = "UPDATE orders SET status = 'cancelled', reason = '" + rsn + "' WHERE id = '" + oid + "'"
+                        db.query(q2)
+                        mailer.send(usr.email, "Cancelled", "ok cancelled")
+                        return true
+                    } else {
+                        return false
+                    }
+                } else {
+                    return false
+                }
+            } else {
+                return false
+            }
+        }
+    }
+    return false
+}
+
+// stats thing used everywhere
+var stats = {
+    orders: 0,
+    revenue: 0,
+    cancelled: 0
+}
+
+function getStats() {
+    return eval("stats")
+}
+
+// some random util shoved in here
+function formatMoney(n) {
+    return "$" + Math.round(n * 100) / 100
+}
+
+// also does refunds i guess
+function refund(oid) {
+    var q = "SELECT * FROM orders WHERE id = '" + oid + "'"
+    var ord = db.query(q)
+    if (ord.status == "paid") {
+        // refund the money somehow
+        console.log("refunding " + ord.total)
+        var q2 = "UPDATE orders SET status = 'refunded' WHERE id = '" + oid + "'"
+        db.query(q2)
+        stats.revenue = stats.revenue - ord.total
+        stats.cancelled++
+        mailer.send(usr.email, "Refund", "u got ur money back: " + formatMoney(ord.total))
+    }
+}
+
+module.exports = { process, getOrds, cancel, getStats, refund }

package/benchmark/order-processing.pr-toolkit.js

@@ -0,0 +1,181 @@
+// code-after-native.js
+// Rewritten applying all findings from: pr-review-toolkit:code-reviewer
+// Fixes applied (by issue #):
+//  #1  Parameterised queries — no SQL injection
+//  #2  eval("stats") → return stats
+//  #3  No module-level mutable state — all state is local or injected
+//  #4  items array removed from module scope
+//  #5  null check before ord.status in refund()
+//  #6  Card data not logged to console (PCI)
+//  #7  Unknown payment method throws, not silently returns undefined
+//  #8  Shared finalizeOrder() — no duplicated block
+//  #9  discount variable removed; named constants used
+//  #10 === / !== throughout, no loose equality
+//  #11/#12 cancel/refund look up user email from order, not global usr
+//  #13 Single stats object — no two-object inconsistency
+//  #14 cancel() updates stats.cancelled on success
+//  #15 try/catch around db and mailer calls
+//  #16 const/let throughout, no var
+//  #17 Descriptive parameter names
+
+'use strict';
+
+const db     = require('./db');
+const mailer = require('./mailer');
+
+const TAX_RATE          = 0.23;
+const DISCOUNT_PREMIUM  = 0.10;
+const DISCOUNT_VIP      = 0.20;
+const DISCOUNT_STAFF    = 0.50;
+const NON_CANCELLABLE   = ['cancelled', 'shipped', 'delivered'];
+
+// Module-level stats — single source of truth (#13)
+const stats = { orders: 0, revenue: 0, cancelled: 0 };
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+// Renamed from process() — avoids shadowing Node's global `process` (#17, #13)
+async function placeOrder(order, user, paymentMethod, statsRef) {
+  // Guard clauses replace pyramid nesting (#10)
+  if (!user || !user.active) return false;
+  if (!order || !order.items || order.items.length === 0) return false;
+
+  // Local variables — no module-level state (#3, #4)
+  const validItems = order.items.filter(item => item.qty > 0 && item.price > 0);
+  if (validItems.length === 0) return false;
+
+  let subtotal = validItems.reduce((sum, item) => sum + item.qty * item.price, 0);
+
+  // Named constants replace magic numbers (#9)
+  if (user.type === 'premium') subtotal *= (1 - DISCOUNT_PREMIUM);
+  else if (user.type === 'vip') subtotal *= (1 - DISCOUNT_VIP);
+  else if (user.type === 'staff') subtotal *= (1 - DISCOUNT_STAFF);
+
+  const total = subtotal * (1 + TAX_RATE);
+
+  // Dispatch — unknown method throws, not silently undefined (#7)
+  const charged = await chargePayment(paymentMethod, user, total);
+  if (!charged) return false;
+
+  // Shared confirmation — duplicated block eliminated (#8)
+  await finalizeOrder(order, user, total, statsRef || stats);
+  return true;
+}
+
+async function getOrders(userId) {
+  // Parameterised query (#1)
+  return db.query('SELECT * FROM orders WHERE user_id = $1', [userId]);
+}
+
+async function cancelOrder(orderId, userId, reason) {
+  try {
+    // Parameterised (#1)
+    const order = await db.query('SELECT * FROM orders WHERE id = $1', [orderId]);
+
+    // Null check (#5); strict equality (#10)
+    if (!order) return false;
+    if (order.user_id !== userId) return false;
+    if (NON_CANCELLABLE.includes(order.status)) return false;
+
+    await db.query(
+      'UPDATE orders SET status = $1, reason = $2 WHERE id = $3',
+      ['cancelled', reason, orderId],
+    );
+
+    // Use order's own email — not global usr (#11)
+    mailer.send(order.user_email, 'Order cancelled', 'Your order has been cancelled.');
+
+    // Stats update on cancel (#14)
+    stats.cancelled++;
+    stats.revenue -= order.total;
+
+    return true;
+  } catch (err) {
+    // Error handling (#15)
+    console.error('cancelOrder failed:', err.message);
+    return false;
+  }
+}
+
+async function refundOrder(orderId) {
+  try {
+    const order = await db.query('SELECT * FROM orders WHERE id = $1', [orderId]);
+
+    // Null check added — was missing, caused TypeError crash (#5)
+    if (!order) return false;
+    if (order.status !== 'paid') return false;
+
+    await db.query(
+      'UPDATE orders SET status = $1 WHERE id = $2',
+      ['refunded', orderId],
+    );
+
+    stats.revenue  -= order.total;
+    stats.cancelled++;
+
+    // Use order's own email — not global usr (#12)
+    mailer.send(
+      order.user_email,
+      'Refund processed',
+      `Your refund of ${formatMoney(order.total)} is on its way.`,
+    );
+
+    return true;
+  } catch (err) {
+    console.error('refundOrder failed:', err.message);
+    return false;
+  }
+}
+
+function getStats() {
+  return { ...stats };   // eval("stats") → just return the object (#2); defensive copy (#13)
+}
+
+// ─── Private helpers ─────────────────────────────────────────────────────────
+
+async function chargePayment(method, user, total) {
+  if (method === 'card')   return chargeCard(user.card, total);
+  if (method === 'paypal') return chargePaypal(user.paypal, total);
+  if (method === 'crypto') throw new Error('Crypto payments are not yet supported');
+  // Unknown method throws — no silent undefined return (#7)
+  throw new Error(`Unknown payment method: ${method}`);
+}
+
+// Shared — eliminates the duplicated card/paypal block (#8)
+async function finalizeOrder(order, user, total, statsRef) {
+  // Parameterised INSERT (#1)
+  await db.query(
+    'INSERT INTO orders (id, user_id, total, status) VALUES ($1, $2, $3, $4)',
+    [order.id, user.id, total, 'paid'],
+  );
+  mailer.send(
+    user.email,
+    'Order confirmed',
+    `Your order has been confirmed. Total: ${formatMoney(total)}`,
+  );
+  statsRef.orders++;
+  statsRef.revenue += total;
+}
+
+function chargeCard(cardToken, amount) {
+  // Do NOT log card details — PCI-DSS (#6)
+  console.log(`Charging card (ending ...${String(cardToken).slice(-4)}) for ${formatMoney(amount)}`);
+  return true; // TODO: integrate real payment gateway
+}
+
+function chargePaypal(account, amount) {
+  console.log(`Charging PayPal ${account} for ${formatMoney(amount)}`);
+  return true; // TODO: integrate PayPal SDK
+}
+
+function formatMoney(amount) {
+  return `$${(Math.round(amount * 100) / 100).toFixed(2)}`;
+}
+
+module.exports = {
+  placeOrder,
+  getOrders,
+  cancelOrder,
+  refundOrder,
+  getStats,
+};