rsc-universal 0.1.1

package/skills/prisma-orm/references/queries-and-performance.md

@@ -0,0 +1,169 @@
+# Queries and performance (Prisma 7)
+
+Depth offloaded from `SKILL.md`. Everything here assumes the v7 client: `provider =
+"prisma-client"`, a driver adapter on the constructor, connection in `prisma.config.ts`.
+
+## Shaping rows: `select` vs `include`
+
+| You want | Use | Returns |
+| --- | --- | --- |
+| Only specific scalar fields | `select` | Exactly the named fields, nothing else |
+| Specific fields + nested relation fields | nested `select` | Named scalars + named relation fields |
+| A relation alongside the full record | `include` | **All** scalar fields + the named relation |
+
+Rules:
+
+- Default to `select`. `include` is convenient but over-fetches every column on the row,
+  which costs bandwidth and leaks fields you did not mean to expose.
+- Never put `select` and `include` at the same level — Prisma throws a validation error. Nest
+  `select` inside a relation key to get both shaping and the relation.
+
+```ts
+// Shape the parent AND the relation with nested select
+const users = await prisma.user.findMany({
+  take: 20,
+  select: {
+    id: true,
+    email: true,
+    posts: { select: { id: true, title: true } }, // nested select, not include
+  },
+});
+```
+
+## Pagination: offset vs cursor
+
+| Pattern | API | When | Cost |
+| --- | --- | --- | --- |
+| Offset | `skip` + `take` | Jump to an arbitrary page, small/medium tables | `skip` re-scans skipped rows; degrades on large offsets |
+| Cursor | `cursor` + `take` (+ `skip: 1` to drop the anchor) | Infinite scroll, large tables, stable ordering | Seeks by an indexed unique column; constant cost |
+
+```ts
+// Cursor pagination — seek from the last id you saw
+const page = await prisma.post.findMany({
+  take: 20,
+  ...(lastId ? { cursor: { id: lastId }, skip: 1 } : {}),
+  orderBy: { id: "asc" }, // cursor needs a stable, indexed order
+  select: { id: true, title: true },
+});
+const nextCursor = page.at(-1)?.id;
+```
+
+The cursor column must be unique and indexed (here `id`). Cursor pagination cannot jump to
+"page 7" — it only moves forward/backward from a known row.
+
+## Writes
+
+```ts
+// upsert: create-or-update keyed on a unique field
+await prisma.user.upsert({
+  where: { email },
+  create: { email, role: "MEMBER" },
+  update: { role: "MEMBER" },
+});
+
+// createMany: bulk insert, skip rows that collide on a unique constraint
+await prisma.user.createMany({
+  data: rows,
+  skipDuplicates: true,
+});
+```
+
+`createMany` does not return created rows and does not support nested writes. Use
+`createManyAndReturn` when you need the inserted records back.
+
+## Transactions
+
+| Situation | Form | Why |
+| --- | --- | --- |
+| Several independent writes that must all commit or all roll back | `prisma.$transaction([opA, opB, opC])` (array) | One round trip, no app-side logic between ops |
+| Read, branch on the result, then write conditionally | `prisma.$transaction(async (tx) => { … })` (interactive) | You need values from one op to decide the next |
+
+```ts
+// Interactive: read-then-write with a guard inside one transaction
+const order = await prisma.$transaction(async (tx) => {
+  const stock = await tx.product.findUniqueOrThrow({ where: { id }, select: { qty: true } });
+  if (stock.qty < want) throw new Error("out of stock"); // throwing rolls the tx back
+  await tx.product.update({ where: { id }, data: { qty: { decrement: want } } });
+  return tx.order.create({ data: { productId: id, qty: want } });
+});
+```
+
+Keep interactive transactions short. Every statement holds a connection and a DB lock; long
+transactions starve the pool. Set a `timeout` / `maxWait` option for slow paths.
+
+## Generated types and `Prisma.validator`
+
+Do not hand-write the shape of a query result. Derive it from the query args so the two never
+drift.
+
+```ts
+// Reuse one args object as both the query input and its result type
+const userWithPosts = Prisma.validator<Prisma.UserDefaultArgs>()({
+  select: { id: true, email: true, posts: { select: { title: true } } },
+});
+
+type UserWithPosts = Prisma.UserGetPayload<typeof userWithPosts>;
+
+const users: UserWithPosts[] = await prisma.user.findMany(userWithPosts);
+```
+
+`Prisma.validator` type-checks the args at definition time; `Prisma.<Model>GetPayload`
+extracts the exact return type for that selection.
+
+## Performance checklist: kill N+1 and over-fetch
+
+1. **Use `relationLoadStrategy: "join"` for parent-with-children reads.** Default in v7. On
+   Postgres it emits a single LATERAL JOIN with JSON aggregation; on MySQL, correlated
+   subqueries. The top-level choice cascades to nested relations. This collapses N+1 into one
+   query.
+2. **Switch to `"query"` only when a join fans out badly** (one parent → thousands of children
+   multiplies rows). `"query"` runs one query per relation and stitches in the app.
+3. **`select` only the columns you render.** A list view that shows a title should not pull a
+   `body @db.Text`.
+4. **`@@index` every column you filter or order on**, and every FK you join on — Prisma does
+   not create FK indexes for you.
+5. **See the SQL.** Set `log: ["query"]` on the client (or `["query", "warn", "error"]`). Read
+   the emitted statements; a burst of identical `SELECT … WHERE id = $1` is N+1 — fix it with
+   `"join"` or a batched `where: { id: { in: ids } }`.
+6. **For `EXPLAIN ANALYZE`, the query planner, index theory, and pool sizing**, that is the
+   database engine — see `../postgresdb/SKILL.md`. This skill stops at "here is the SQL Prisma
+   emitted and how to make Prisma emit a better one".
+
+```ts
+// N+1 in disguise: looks like one call, but each iteration is a round trip
+for (const u of users) {
+  u.posts = await prisma.post.findMany({ where: { authorId: u.id } }); // N queries
+}
+
+// Fixed: load children with the parents in one query
+const withPosts = await prisma.user.findMany({
+  relationLoadStrategy: "join",
+  select: { id: true, posts: { select: { id: true, title: true } } },
+});
+```
+
+## Raw SQL safety matrix
+
+| API | Parameterized? | Use |
+| --- | --- | --- |
+| `` $queryRaw`… ${x} …` `` (tagged template) | Yes | Default for ad-hoc reads with dynamic values |
+| `` $executeRaw`… ${x} …` `` (tagged template) | Yes | Writes / DDL with dynamic values |
+| `$queryRawTyped(...)` + `.sql` files | Yes + typed result | Reusable queries you want fully type-checked |
+| `Prisma.sql` / `Prisma.join` | Yes (composed) | Building a parameterized fragment / `IN` list |
+| `$queryRawUnsafe(string)` / `$executeRawUnsafe(string)` | **No** | Only with a fixed, non-user string (e.g. a known identifier you whitelisted) |
+
+```ts
+// Safe: values are bound as parameters, never concatenated
+const rows = await prisma.$queryRaw`SELECT id FROM "User" WHERE email = ${email}`;
+
+// Safe IN-list via Prisma.join
+const ids = [1, 2, 3];
+await prisma.$queryRaw`SELECT * FROM "Post" WHERE id IN (${Prisma.join(ids)})`;
+
+// UNSAFE: interpolating user input into the *Unsafe API is SQL injection
+const rows = await prisma.$queryRawUnsafe(`SELECT id FROM "User" WHERE email = '${email}'`);
+```
+
+Identifiers (table/column names) cannot be parameterized. If you must vary an identifier,
+validate it against an allowlist before building the string — never pass user input straight
+through.

package/skills/prisma-orm/scripts/verify.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — prisma-orm skill gate. Static lint of Prisma artifacts. NO database connection.
+#
+# Usage:
+#   scripts/verify.sh [paths...]   # lint the given files/dirs
+#   scripts/verify.sh              # discover schema.prisma + *.ts under cwd (skips vendor dirs)
+#
+# Read-only and idempotent — it never writes, migrates, or connects. What it checks:
+#   1. generator block uses provider = "prisma-client" (legacy "prisma-client-js" is a fail)
+#      and carries a required output =.
+#   2. every `new PrismaClient(` passes an `adapter`/`accelerateUrl` (bare construction is a fail).
+#   3. hard banlist: $queryRawUnsafe(/$executeRawUnsafe( with a ${ interpolation (SQL injection),
+#      binaryTargets (Rust-era v6), prisma-client-js generator.
+#   4. warn-only: findMany( with no take/cursor nearby (likely unbounded read).
+#   5. contamination: drizzle-kit / pgTable( / drizzle.config (wrong ORM leaked in).
+#
+# Exit code: non-zero ONLY on a hard violation. An empty/clean target is a clean pass.
+# Warnings are printed but never fail the run. Targets bash 3.2 (no mapfile/assoc arrays).
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+ROOT="$(pwd)"
+
+# ---- collect candidate files (schema.prisma + *.ts), skipping vendor/build dirs ----
+FILES=()
+add_under() {
+  local base="$1"
+  while IFS= read -r -d '' f; do FILES+=("$f"); done < <(
+    find "$base" \
+      \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/dist/*' \
+         -o -path '*/.next/*' -o -path '*/build/*' -o -path '*/generated/*' \) -prune -o \
+      -type f \( -name 'schema.prisma' -o -name '*.prisma' -o -name '*.ts' -o -name '*.mts' \) -print0 \
+      2>/dev/null
+  )
+}
+
+if [ "$#" -gt 0 ]; then
+  for p in "$@"; do
+    if [ -f "$p" ]; then FILES+=("$p")
+    elif [ -d "$p" ]; then add_under "$p"
+    else err "no such path: $p"; fi
+  done
+else
+  add_under "$ROOT"
+fi
+
+# Keep only files that look Prisma-related (a .prisma file, or TS that touches Prisma).
+PRISMA_FILES=()
+for f in "${FILES[@]:-}"; do
+  [ -z "$f" ] && continue
+  case "$f" in
+    *.prisma) PRISMA_FILES+=("$f"); continue;;
+  esac
+  if grep -Eq 'PrismaClient|@prisma/|prisma\.\$|prisma/config|relationLoadStrategy' "$f" 2>/dev/null; then
+    PRISMA_FILES+=("$f")
+  fi
+done
+
+if [ "${#PRISMA_FILES[@]}" -eq 0 ]; then
+  ok "no Prisma artifacts found — nothing to verify (clean)"
+  exit 0
+fi
+
+# ---- 1. generator block in .prisma files ----
+SCHEMA_SEEN=0
+for f in "${PRISMA_FILES[@]}"; do
+  case "$f" in *.prisma) ;; *) continue;; esac
+  grep -Eq 'generator\s' "$f" 2>/dev/null || continue
+  SCHEMA_SEEN=1
+  if grep -Eq 'provider\s*=\s*"prisma-client-js"' "$f" 2>/dev/null; then
+    err "$f: legacy generator provider \"prisma-client-js\" — v7 uses \"prisma-client\""
+  elif grep -Eq 'provider\s*=\s*"prisma-client"' "$f" 2>/dev/null; then
+    if grep -Eq '^\s*output\s*=' "$f" 2>/dev/null; then
+      ok "$f: prisma-client generator with output"
+    else
+      err "$f: prisma-client generator is missing the required output ="
+    fi
+  fi
+done
+[ "$SCHEMA_SEEN" -eq 0 ] && skip "no generator block found in a .prisma file"
+
+# ---- 2. PrismaClient construction must carry an adapter / accelerateUrl ----
+CLIENT_SEEN=0
+for f in "${PRISMA_FILES[@]}"; do
+  case "$f" in *.prisma) continue;; esac
+  grep -Eq 'new[[:space:]]+PrismaClient[[:space:]]*\(' "$f" 2>/dev/null || continue
+  CLIENT_SEEN=1
+  # bare new PrismaClient() with empty/no args
+  if grep -Eq 'new[[:space:]]+PrismaClient[[:space:]]*\([[:space:]]*\)' "$f" 2>/dev/null; then
+    err "$f: bare new PrismaClient() — v7 needs an adapter (throws 'requires either adapter or accelerateUrl')"
+  elif grep -Eq 'adapter|accelerateUrl' "$f" 2>/dev/null; then
+    ok "$f: PrismaClient construction passes an adapter/accelerateUrl"
+  else
+    err "$f: new PrismaClient(...) without an adapter or accelerateUrl in the file"
+  fi
+done
+[ "$CLIENT_SEEN" -eq 0 ] && skip "no PrismaClient construction found"
+
+# ---- 3. hard banlist ----
+for f in "${PRISMA_FILES[@]}"; do
+  # $queryRawUnsafe / $executeRawUnsafe carrying an interpolation = injection
+  if grep -Eq '\$(query|execute)RawUnsafe[[:space:]]*\([^)]*\$\{' "$f" 2>/dev/null; then
+    err "$f: \$queryRawUnsafe/\$executeRawUnsafe with \${} interpolation — SQL injection; use a tagged \$queryRaw\`\`"
+  fi
+  if grep -Eq 'binaryTargets' "$f" 2>/dev/null; then
+    err "$f: binaryTargets is Rust-era (v6); v7 is Rust-free — remove it"
+  fi
+done
+
+# ---- 4. warn-only: unbounded findMany ----
+for f in "${PRISMA_FILES[@]}"; do
+  case "$f" in *.prisma) continue;; esac
+  grep -Eq 'findMany[[:space:]]*\(' "$f" 2>/dev/null || continue
+  # crude heuristic: file uses findMany but never mentions take or cursor
+  if ! grep -Eq '\btake\b|\bcursor\b' "$f" 2>/dev/null; then
+    warn "$f: findMany() with no take/cursor in the file — likely an unbounded read"
+  fi
+done
+
+# ---- 5. wrong-ORM contamination ----
+for f in "${PRISMA_FILES[@]}"; do
+  if grep -Eq 'drizzle-kit|pgTable[[:space:]]*\(|drizzle\.config' "$f" 2>/dev/null; then
+    err "$f: Drizzle signal (drizzle-kit/pgTable/drizzle.config) in a Prisma artifact — wrong ORM leaked in"
+  fi
+done
+
+if [ "$EXIT" -eq 0 ]; then
+  ok "prisma-orm checks passed"
+fi
+exit "$EXIT"

package/skills/procurement/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: procurement
+description: "Use when a small operator must decide what to buy and from whom — pick a supplier/vendor, write an RFI/RFQ/RFP that gets comparable bids back, compare quotes on total cost not sticker price, negotiate price and payment terms, judge single-source risk, or build a vendor scorecard for quarterly review. Triggers: 'help me pick a supplier for X', 'write an RFQ for 5,000 units', 'which of these quotes is actually cheapest over three years', 'should I take the 2/10 net 30 early-payment discount', 'we buy a critical part from one supplier — how risky is that', 'build a supplier scorecard', 'compara estos proveedores / negociar condiciones de pago', 'compara aquests proveïdors / negociar condicions amb el proveïdor'. NOT signing the binding purchase agreement or redlining liability/IP clauses (that is contracts), NOT the price you charge your own customers (that is pricing), NOT counting or reordering the stock once it arrives (that is inventory)."
+tags: [procurement, sourcing, suppliers, rfq, negotiation, vendor-management]
+recommends: [contracts, pricing, inventory, logistics-ops, invoicing, cost-tracking]
+origin: risco
+---
+
+# Procurement — buy well, and leave a decision someone could audit
+
+You are a disciplined buyer's analyst. Your job is to choose the **right supplier** and the **right terms** on **total cost** — and to leave behind a scored, weighted decision a colleague could re-run and reach the same conclusion. You do not sign the contract, you do not set the price *you* charge customers, and you do not count the stock once it lands. You decide *what to buy and from whom*, and you make the deal.
+
+**The one rule, stated up front:** never compare suppliers on sticker price — always total cost of ownership. And never single-source a critical input silently — name the risk and write down the backup. Every other section serves these two.
+
+## What you produce
+
+Four artifacts. Each exists because a later question demands it.
+
+1. **Requirement brief** — what you are buying, in numbers (spec, quantity, quality bar, delivery window, must-haves vs nice-to-haves). Without it, bids come back incomparable.
+2. **Sourcing request** — the RFI, RFQ, or RFP you send. Its job is to force *comparable* responses, so it discloses the evaluation criteria and a deadline.
+3. **Weighted supplier scorecard** — criteria with weights summing to 100, a score per supplier per criterion, a weighted total. This is what makes the choice defensible and what `scripts/verify.sh` checks.
+4. **Negotiation / term sheet** — the price, the payment terms, the concession you traded for them, and your walk-away (BATNA).
+
+## First move: segment the buy (Kraljic 2×2)
+
+Before you pick a tactic, place the buy on two axes — **business impact** (profit/criticality if it fails) and **supply risk** (how hard to replace the supplier). Tactic must match the quadrant, or you over-invest effort on a stapler order and under-invest on the part that halts production (Kraljic, HBR 1983).
+
+| Impact \ Risk | Low supply risk | High supply risk |
+|---|---|---|
+| **Low impact** | **Routine** — automate, consolidate orders, buy from an approved-supplier list. Don't run a tender for paperclips. | **Bottleneck** — secure continuity. Develop a backup supplier, hold buffer stock, lock a delivery SLA. |
+| **High impact** | **Leverage** — run a competitive bid, exploit your buying power, churn suppliers for price. | **Strategic** — partner. Fewest suppliers, joint planning, multi-year deal, deepest relationship. |
+
+Re-score quadrants at least annually — a routine item becomes a bottleneck the day its only maker exits the market. SRM cadence scales with quadrant (see references): quarterly reviews for Strategic, semiannual for Bottleneck.
+
+## Pick the right request: RFI vs RFQ vs RFP
+
+Match the request to *what you don't yet know*. Sending the wrong one wastes a bidding cycle.
+
+| You need to… | Send a… | Use when |
+|---|---|---|
+| Learn the market, scope the field | **RFI** (request for information) | Requirements are still fuzzy; non-binding; you're narrowing a shortlist. |
+| Get a price on a fully-specified, identical need | **RFQ** (request for quotation) | Specs are locked, suppliers are comparable, and price is the decider. |
+| Solicit a full solution where the *how* is open | **RFP** (request for proposal) | You must evaluate approach *and* price — the supplier designs part of the answer. |
+
+The mature phased flow is **RFI → RFP → RFQ**, but a well-defined commodity buy skips straight to an RFQ. Don't run an RFP for a screw you can fully spec — that's an RFQ wearing a costume.
+
+Whatever you send, it MUST contain these or the bids come back incomparable:
+
+- exact spec + quantity (and minimum order quantity tolerance);
+- delivery terms and required date (Incoterm if cross-border);
+- **the evaluation criteria and their weights, disclosed** — bidders optimize for what you'll score, and disclosure cuts disputes;
+- a hard response deadline;
+- a required response format (a filled table beats free-form prose you can't compare).
+
+Copy-ready RFI/RFQ/RFP skeletons and the invite + award/regret email templates: see `references/sourcing-requests.md`.
+
+## The weighted scorecard
+
+Assign each criterion a weight; **weights sum to 100**. Score every supplier on every criterion (a 1–5 scale is enough). Weighted total = Σ(weight × score). Predefined weights set *before* you see bids kill the bias where you reverse-engineer the criteria to pick the supplier you already liked.
+
+A common starting split — tune per category:
+
+- technical / capability fit ~40
+- price / commercial ~30
+- vendor viability / risk ~30
+
+Worked mini-example (scores 1–5):
+
+```text
+Criterion        Weight  SupplierA  SupplierB   A weighted   B weighted
+Capability         40       4          3           160          120
+Commercial         30       3          5            90          150
+Viability/risk     30       4          3           120           90
+                  ----                              ----         ----
+Total              100                               370         360
+```
+
+A edges B (370 vs 360) even though B is cheaper on the commercial line — because capability and risk outweigh a lower price. **Disclose these weights to bidders.** Full template: `references/scorecard-and-tco.md`.
+
+## Total cost of ownership, never sticker price
+
+The cheapest unit price routinely loses once you add the costs nobody quoted. A workable model:
+
+```text
+TCO = Acquisition
+    + (Annual Operating   × Years)
+    + (Annual Maintenance × Years)
+    + Training
+    + Downtime / lost productivity
+    − Residual / resale value
+```
+
+The lines people forget: **delivery & freight, installation, integration effort, training, support, downtime, license true-ups, exit/disposal.** Quote all of them or you're comparing fiction.
+
+**Bad → Good.** You are buying 5,000 units a year.
+
+- Bad — compare on unit price: Supplier A at **$9.00** beats Supplier B at **$11.00**. Pick A.
+- Good — compare on TCO:
+
+```text
+Line              Supplier A         Supplier B
+Unit × 5,000      $9.00 → $45,000    $11.00 → $55,000
+Freight           $6,000 (overseas)  $500 (local)
+Support contract  $5,000/yr          included
+Downtime (8% defect, lost prod.)  $4,000   $0
+                  --------           --------
+Year-1 TCO        $60,000            $55,500
+```
+
+Supplier B — the "expensive" one — is **$4,500 cheaper** once freight, support, and defect downtime land. Always recompute on TCO before you award.
+
+## Negotiation
+
+Rules, each with its why:
+
+- **Separate price from terms; settle price first.** Resistance is lowest on price when terms aren't yet on the table; opening with both lets the supplier trade one against the other.
+- **Trade something for every concession — never ask free.** Want Net 60 or a volume discount? Offer what the supplier values: an annual/volume commitment, a phased ramp (Net 45 for 6 months → Net 60 after), or a reliable-payer track record. A free ask gets a free no.
+- **Know your BATNA (walk-away).** Your leverage is the credible alternative supplier. If you have none, that's a single-source problem to fix first (next section), not a negotiation to win.
+- **Anchor on TCO, not line items.** Negotiate the total cost you computed, so the supplier can't claw back a unit-price cut through freight or support.
+
+**The early-payment discount is math, not a vibe.** A "2/10 net 30" offer (2% off if paid within 10 days, else full at 30) is a return on paying 20 days early:
+
+```text
+Annualized return = (Discount% ÷ (1 − Discount%)) × (365 ÷ DaysSaved)
+                  = (0.02 ÷ 0.98)        × (365 ÷ 20)
+                  ≈ 0.0204               × 18.25
+                  ≈ 37.2% annualized
+```
+
+Take the discount whenever your cost of capital is below ~37.2%. "We're tight on cash" is rarely a reason to skip a 37.2% return — borrow against it before you pass. Negotiation playbook and BATNA worksheet: `references/scorecard-and-tco.md`.
+
+## Supply risk + the maverick-spend leak
+
+Name which case any critical input falls in — they are different risks:
+
+- **Single source** — you *chose* one supplier though alternatives exist. A concentration risk you accepted; document why and a switch plan.
+- **Sole source** — only one supplier exists. A risk you must *mitigate*, not choose away: buffer stock, a qualification project for an alternative, a contractual continuity clause.
+- **Dual sourcing** — two qualified suppliers for the same item, splitting volume. Cuts single-point-of-failure risk at higher unit cost; right for Bottleneck/Strategic items.
+
+**Require a written backup plan for any critical or strategic single/sole source.** A critical input with no named backup is an outage waiting for a date.
+
+**Maverick (off-process) spend** is the silent leak — purchases made outside the approved process and supplier list. APQC measured it around **1.8% of annual purchase value**; organizations can lose up to **~16% of negotiated savings** to it, and the practical target is **under 10% of spend** going off-contract. The fix isn't a procurement suite — it's a one-page **intake gate** (anything over $X routes through this skill's flow) plus an **approved-supplier list**.
+
+## Ongoing: scorecard, cadence, re-source triggers
+
+A supplier you picked once is not a supplier you can ignore. Track four dimensions on a recurring **performance scorecard**: **quality** (defect/return rate), **delivery** (on-time-in-full), **price drift** (vs the awarded price), **responsiveness** (issue resolution time). Review on the SRM cadence set by Kraljic quadrant.
+
+Re-source — re-open the comparison — when a trigger fires: OTIF drops below your threshold for two periods, price drifts up beyond the contracted escalator, a single/sole source loses its only backup, or the category re-segments into a higher-risk quadrant. Performance scorecard template, SRM-cadence-by-quadrant table, and re-source thresholds: `references/scorecard-and-tco.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Compare suppliers on unit price only | The cheapest unit routinely loses once freight, support, and downtime land | Recompute every shortlist on TCO before awarding |
+| One vague RFP for a commodity you can fully spec | Wastes a bidding cycle; bids come back incomparable | Send an RFQ with fixed specs when price is the decider |
+| Evaluation weights kept secret (or invented after bids arrive) | Invites bias and post-award disputes | Set weights before bids, disclose them, score predefined criteria |
+| Ask for Net 60 / a discount with nothing offered | A free ask earns a free no | Trade a volume commit, phased ramp, or reliable-payer record |
+| Skip the early-payment discount because "we're tight" | You pass on a ~37.2% annualized return | Compute it; take it whenever cost of capital is lower |
+| Single-source a critical part and say nothing | An outage with no named owner or backup | Label single/sole/dual, write the backup plan |
+| Negotiate price and terms in one breath | The supplier trades one against the other | Settle price first, then negotiate terms separately |
+| Let small buys skip the process | Maverick spend quietly burns negotiated savings | A one-page intake gate + approved-supplier list |
+
+## Hand-offs
+
+You own the decision and the deal. The moment it becomes something else, route:
+
+- Drafting/redlining the binding purchase agreement, MSA, liability/IP clauses, signature → `../contracts/SKILL.md`.
+- The price *you* charge *your* customers, your margins, packaging → `../pricing/SKILL.md`.
+- Stock levels, reorder points, safety stock, SKU counts once goods are on hand → `../inventory/SKILL.md`.
+- Freight, carrier choice, warehousing, customs once you've decided to buy → `../logistics-ops/SKILL.md`.
+- Generating and paying the supplier bill, dunning, payment runs → `../invoicing/SKILL.md`.
+- Tracking ongoing SaaS/subscription spend after a renewal decision → `../cost-tracking/SKILL.md`.
+
+> Note on AI: generative tools can compress supplier *discovery* by up to ~90% — finding candidates fast. They do not replace the weighting, TCO model, risk segmentation, or negotiation. Use AI to widen the shortlist; keep the judgment human and on paper.
+
+## references/
+
+- `references/sourcing-requests.md` — copy-ready RFI/RFQ/RFP skeletons with the mandatory comparable-bid sections, plus invite and award/regret email templates.
+- `references/scorecard-and-tco.md` — weighted-scorecard template, worked TCO comparison layout, supplier performance scorecard, SRM-cadence-by-quadrant table, and re-source trigger thresholds.

package/skills/procurement/evals/README.md

@@ -0,0 +1,20 @@
+# Evals — procurement
+
+`cases.yaml` holds three groups: `should_trigger`, `should_not_trigger`, and a
+`capability` case. These are LLM-graded routing and capability checks, not unit
+tests. Run them through whatever eval harness the repo provides, or by hand: feed
+each `should_trigger` prompt to the router and confirm it selects `procurement`
+(including the non-obvious ones — the "actually cheaper over three years" TCO trap
+and the "2/10 net 30" early-payment-discount question that masquerades as an AP
+task — and the Spanish/Catalan phrasings). Feed each `should_not_trigger` prompt
+and confirm it routes to the named sibling (`contracts`, `pricing`, `inventory`,
+`logistics-ops`, `bookkeeping`) and not here; every `route_to` id must resolve to
+a real sibling skill. Grade the `capability` case against its `must_include`
+rubric on an actual generated answer: tick each line (Kraljic segmentation,
+weights summing to 100, TCO not unit price, the early-discount math, single-source
+risk + backup plan, hand-offs to contracts/inventory). Pair the capability grade
+with `scripts/verify.sh` against any generated scorecard/TCO file to confirm the
+artifact ties out (weights sum to 100, no blank scores, recomputed totals match,
+TCO has more than a unit line) — the rubric judges sourcing judgment, verify.sh
+judges structural consistency. No automated harness is assumed beyond reading the
+prompts and checking routing plus the rubric.

package/skills/procurement/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: procurement
+
+should_trigger:
+  - prompt: "Help me choose between three vendors for our packaging supply."
+    why: Core supplier-selection ask — the weighted comparison and award decision this skill owns.
+  - prompt: "Write an RFQ to send to suppliers for 5,000 units."
+    why: Sourcing-request generation; an RFQ with disclosed criteria and a deadline is a primary artifact.
+  - prompt: "Which of these two quotes is actually cheaper over three years?"
+    why: Non-obvious — reads like simple arithmetic but is the TCO / sticker-price trap; the cheaper unit often loses.
+  - prompt: "Should I pay this supplier invoice early to get the 2/10 net 30 discount?"
+    why: Non-obvious — looks like an AP payment question but is the early-payment-discount procurement math (~37.2% annualized).
+  - prompt: "We buy a critical component from only one supplier — how worried should I be?"
+    why: Single/sole-source concentration risk and the backup-plan requirement.
+  - prompt: "Negociar mejores condiciones de pago con nuestro proveedor."
+    why: Spanish trigger — payment-terms negotiation, trading a concession for extended terms.
+  - prompt: "Compara aquests proveïdors i munta una scorecard ponderada per decidir."
+    why: Catalan trigger — weighted-scorecard supplier comparison.
+
+should_not_trigger:
+  - prompt: "Draft and redline the purchase agreement so we can sign it."
+    route_to: contracts
+    why: Binding legal instrument with liability/IP clauses and signature — not the buy decision.
+  - prompt: "What price should we charge our customers for this product?"
+    route_to: pricing
+    why: Our outbound price and margins, not selecting or negotiating with a supplier.
+  - prompt: "How many units do we have left and when do we hit the reorder point?"
+    route_to: inventory
+    why: Stock levels and reorder math once goods are on hand, not the buy decision.
+  - prompt: "Find the cheapest carrier to ship this pallet to Madrid."
+    route_to: logistics-ops
+    why: Freight and carrier choice after we've decided to buy, not supplier selection.
+  - prompt: "Record and pay this supplier bill in our books."
+    route_to: bookkeeping
+    why: Recording the AP entry and paying the bill, not choosing the supplier or the terms.
+
+capability:
+  - scenario: >
+      An operator has three supplier quotes for a recurring input (5,000 units/yr).
+      Quotes differ on unit price, freight, lead time, payment terms, support
+      cost, and minimum order quantity, and the operator currently buys almost
+      everything from one of the three. Ask the skill to recommend a supplier and
+      the terms to negotiate.
+    must_include:
+      - segments the buy on the Kraljic 2x2 (impact x supply risk) before picking a tactic
+      - builds a weighted scorecard with criteria weights summing to 100 and predefined criteria
+      - computes total cost of ownership (freight, support, downtime, lead-time impact) rather than ranking on unit price
+      - evaluates payment terms with the annualized early-payment-discount math (e.g. 2/10 net 30 ≈ 37.2%) where relevant
+      - flags the concentration / single-source risk and asks for or states a written backup plan
+      - hands signing off to contracts and stock tracking off to inventory rather than doing them here

package/skills/procurement/references/scorecard-and-tco.md

@@ -0,0 +1,100 @@
+# Scorecard, TCO, and supplier-relationship templates
+
+Copy these, fill the numbers, keep the structure. `scripts/verify.sh` checks the
+scorecard and TCO tables for shape and arithmetic.
+
+## Weighted supplier scorecard
+
+Weights set **before** bids arrive and **sum to 100**. Score each supplier on
+each criterion (1–5). Weighted total = Σ(weight × score). Disclose weights to
+bidders.
+
+```text
+Criterion              Weight  Supplier A  Supplier B  Supplier C
+Capability / fit         40        4           3           5
+Price / commercial (TCO) 30        3           5           2
+Viability / risk         30        4           3           4
+-----------------------------------------------------------------
+Weighted total          100       370         360         380
+```
+
+Weighted total math (Supplier C): 40×5 + 30×2 + 30×4 = 200 + 60 + 120 = **380**.
+Highest weighted total wins — *not* lowest price. If two are within ~5%, break
+the tie on supply risk, not on a rounding-error price gap.
+
+CSV form (what verify.sh reads most cleanly):
+
+```text
+criterion,weight,supplier_a,supplier_b,supplier_c
+capability,40,4,3,5
+price_commercial,30,3,5,2
+viability_risk,30,4,3,4
+weighted_total,100,370,360,380
+```
+
+## Worked TCO comparison (full lines)
+
+Compare like-for-like over the same horizon. Include every line both suppliers
+will actually cost you — not just the quoted unit.
+
+```text
+Line item                     Supplier A      Supplier B
+Unit price × quantity         $9.00 × 5,000   $11.00 × 5,000
+  = acquisition               45,000          55,000
+Freight / delivery            6,000           500
+Installation / integration    0               0
+Annual operating (× years)    0               0
+Annual maintenance/support    5,000           0  (included)
+Training                      500             0
+Downtime / defect loss        4,000 (8% rate) 0
+License true-ups              0               0
+Residual / resale value       (−500)          (−1,000)
+-------------------------------------------------------------
+TCO (year 1)                  60,000          54,500
+```
+
+The "cheaper" unit (A) loses by **$5,500** once freight, support, and defect
+downtime land. Always award on the TCO line, never the unit line.
+
+Required-lines reminder — a TCO that lists only unit price is not a TCO. Include
+at least delivery, maintenance/support, training, downtime, or exit.
+
+## Supplier performance scorecard (ongoing)
+
+Score live suppliers each review period on four dimensions; trend matters more
+than any single period.
+
+```text
+Dimension          Metric                          Target    Weight
+Quality            defect / return rate            < 1%       30
+Delivery (OTIF)    on-time-in-full %               > 95%      30
+Price stability    drift vs awarded price          < escalator 20
+Responsiveness     issue resolution time           < 2 days   20
+-------------------------------------------------------------------
+Score (1–5 each, weighted to 100)                             100
+```
+
+## SRM cadence by Kraljic quadrant
+
+| Quadrant | Relationship | Review cadence |
+|---|---|---|
+| Routine (low impact / low risk) | transactional, automate | annual |
+| Leverage (high impact / low risk) | competitive, churn for price | annual / per tender |
+| Bottleneck (low impact / high risk) | secure supply, backups | semiannual |
+| Strategic (high impact / high risk) | partnership, joint planning | quarterly |
+
+Re-score the quadrant assignment itself at least annually — categories drift.
+
+## Re-source trigger thresholds
+
+Re-open the comparison when any of these fire:
+
+- OTIF below your delivery target for **two consecutive periods**.
+- Price drift **above the contracted escalator** without a justified pass-through.
+- A single/sole-source supplier **loses its only backup** (qualification lapses,
+  alt supplier exits).
+- The category **re-segments** into a higher-risk Kraljic quadrant.
+- Quality (defect/return) breaches target for **two consecutive periods**.
+
+A re-source doesn't mean switch — it means run the weighted comparison again with
+current data, then decide.