@damiangilgonzalez/harness 1.3.7

package/skills/llm-pipeline/references/litellm-router.md

@@ -0,0 +1,101 @@
+# LiteLLM Router / Proxy config (v1.83.x)
+
+Fuller config than the SKILL body. Version-pinned to the **v1.83.3-stable** line (also recent: v1.81.9-stable, v1.81.13). LiteLLM exposes a unified OpenAI-format `completion()` across 100+ providers, with retry/fallback, cost tracking, and budget management, as an SDK or a Proxy Server.
+
+## SDK Router with every fallback bucket
+
+```python
+from litellm import Router
+
+router = Router(
+    model_list=[
+        {"model_name": "smart",
+         "litellm_params": {"model": "anthropic/claude-sonnet-4-6",
+                            "api_key": "os.environ/ANTHROPIC_API_KEY",
+                            "timeout": 30, "order": 1}},
+        {"model_name": "smart",          # same group, order 2 = first internal fallback
+         "litellm_params": {"model": "openai/gpt-4o",
+                            "api_key": "os.environ/OPENAI_API_KEY",
+                            "timeout": 30, "order": 2}},
+        {"model_name": "cheap",
+         "litellm_params": {"model": "anthropic/claude-haiku-4-5",
+                            "api_key": "os.environ/ANTHROPIC_API_KEY",
+                            "timeout": 20}},
+        {"model_name": "long-ctx",
+         "litellm_params": {"model": "openai/gpt-4o",
+                            "api_key": "os.environ/OPENAI_API_KEY", "timeout": 60}},
+    ],
+    # cross-group fallbacks (after order levels in a group are exhausted)
+    fallbacks=[{"smart": ["cheap"]}],
+    content_policy_fallbacks=[{"smart": ["smart"]}],   # ContentPolicyViolationError
+    context_window_fallbacks=[{"smart": ["long-ctx"]}],# ContextWindowExceededError
+    default_fallbacks=["cheap"],                         # catch-all last resort
+    num_retries=2,            # bounded retries PER order level
+    timeout=30,              # router-wide hard cap
+    retry_after=1,
+)
+```
+
+Order semantics: a request to an `order=1` deployment that fails (connection error, 404, 429, ...) auto-tries `order=2`, then `order=3`. Each order level runs its own `num_retries` before escalating. Once all orders in the group are exhausted, the `fallbacks`/specialized buckets fire. Retry backoff is exponential from `INITIAL_RETRY_DELAY` 0.2s up to `MAX_RETRY_DELAY` 10s, with jitter.
+
+## Keys come from env, never inline
+
+Use `os.environ/VAR` indirection (proxy YAML) or read `os.environ[...]` in SDK. A literal `sk-...` in a model_list is a leaked credential and a verify.sh FAIL.
+
+## Proxy Server config (config.yaml)
+
+```yaml
+model_list:
+  - model_name: smart
+    litellm_params:
+      model: anthropic/claude-sonnet-4-6
+      api_key: os.environ/ANTHROPIC_API_KEY
+      timeout: 30
+  - model_name: smart-backup
+    litellm_params:
+      model: openai/gpt-4o
+      api_key: os.environ/OPENAI_API_KEY
+      timeout: 30
+
+router_settings:
+  num_retries: 2
+  timeout: 30
+  fallbacks: [{"smart": ["smart-backup"]}]
+  context_window_fallbacks: [{"smart": ["smart-backup"]}]
+
+litellm_settings:
+  cache: true
+  cache_params:
+    type: redis
+    host: os.environ/REDIS_HOST
+    port: os.environ/REDIS_PORT
+    ttl: 600
+```
+
+## Budget & rate limits
+
+```yaml
+litellm_settings:
+  max_budget: 100         # $ hard cap across the proxy; aborts over-budget requests
+  budget_duration: 30d
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY
+```
+
+Per-key / per-tenant budgets are set on virtual keys (`/key/generate` with `max_budget` and `tpm_limit`/`rpm_limit`). Budgets that ABORT are the point — a logged-only budget does not stop a runaway loop.
+
+## Cost callback
+
+```python
+import litellm
+
+def track(kwargs, response, start, end):
+    cost = kwargs.get("response_cost")
+    # emit per-step: model, tokens, cost, latency, cache_hit, fallback used
+    log.info("llm_call", model=kwargs["model"], cost=cost,
+             latency_ms=(end - start).total_seconds() * 1000)
+
+litellm.success_callback = [track]
+```
+
+The cost/latency numbers belong in your observability backbone; attribution dashboards belong to the cost-tracking skill, not here.

package/skills/llm-pipeline/scripts/verify.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# verify.sh — static, read-only checks for an llm-pipeline artifact (gateway/router
+# config or typed-chain code). No live API calls. Offline and deterministic.
+#
+# Usage: verify.sh [PATH]   (PATH = file or dir; defaults to current directory)
+# Exits 0 when every applicable check passes (including an empty/clean target),
+# non-zero when any check FAILs. Checks that do not apply to the artifacts present
+# are SKIPped, never failed.
+
+set -u
+
+TARGET="${1:-.}"
+
+if [[ ! -e "$TARGET" ]]; then
+  echo "verify.sh: path not found: $TARGET" >&2
+  exit 2
+fi
+
+fail_count=0
+pass() { printf 'PASS  %s\n' "$1"; }
+fail() { printf 'FAIL  %s\n' "$1"; fail_count=$((fail_count + 1)); }
+skip() { printf 'SKIP  %s\n' "$1"; }
+
+# Collect candidate source and config files (read-only). Portable to bash 3.2
+# (macOS default) — no mapfile, newline-delimited via a temp array build.
+CODE_FILES=(); YAML_FILES=(); JSON_FILES=()
+while IFS= read -r f; do [[ -n "$f" ]] && CODE_FILES+=("$f"); done < <(find "$TARGET" -type f \( -name '*.py' -o -name '*.ts' -o -name '*.js' \) 2>/dev/null)
+while IFS= read -r f; do [[ -n "$f" ]] && YAML_FILES+=("$f"); done < <(find "$TARGET" -type f \( -name '*.yaml' -o -name '*.yml' \) 2>/dev/null)
+while IFS= read -r f; do [[ -n "$f" ]] && JSON_FILES+=("$f"); done < <(find "$TARGET" -type f -name '*.json' 2>/dev/null)
+ALL_FILES=("${CODE_FILES[@]+"${CODE_FILES[@]}"}" "${YAML_FILES[@]+"${YAML_FILES[@]}"}" "${JSON_FILES[@]+"${JSON_FILES[@]}"}")
+
+if [[ ${#ALL_FILES[@]} -eq 0 ]]; then
+  echo "verify.sh: no .py/.ts/.js/.yaml/.yml/.json files under $TARGET — nothing to check."
+  exit 0
+fi
+
+# grep helper across a file list; prints "file:line:match" lines, empty if none.
+grep_files() { # $1 = pattern, rest = files
+  local pat="$1"; shift
+  [[ $# -eq 0 ]] && return 0
+  grep -HInE "$pat" "$@" 2>/dev/null   # -H so the filename prefix is always present
+}
+
+# --- Check 1: no hardcoded provider keys (always applicable) ---------------
+KEY_HITS="$(grep_files '(sk-[A-Za-z0-9_-]{16,}|sk-ant-[A-Za-z0-9_-]{16,})' "${ALL_FILES[@]}")"
+if [[ -n "$KEY_HITS" ]]; then
+  fail "no hardcoded API keys (found literal key(s); use env vars)"
+  echo "$KEY_HITS" | sed 's/^/      /'
+else
+  pass "no hardcoded API keys"
+fi
+
+# --- Check 2: every completion/chat call site sets a timeout ---------------
+# A "call site" line invokes completion(/chat.completions.create/responses.create.
+CALL_PAT='(\.completion\(|chat\.completions\.create\(|responses\.(create|parse)\()'
+CALL_HITS="$(grep_files "$CALL_PAT" "${CODE_FILES[@]+"${CODE_FILES[@]}"}")"
+if [[ -z "$CALL_HITS" ]]; then
+  skip "timeout on every call (no LLM call sites found)"
+else
+  # A call line is OK if it (or a nearby Router/client default) sets timeout.
+  # Heuristic, read-only: flag call lines on which 'timeout' does not appear AND
+  # whose file has no router/client-level timeout default.
+  unbounded=""
+  while IFS= read -r line; do
+    file="${line%%:*}"
+    if echo "$line" | grep -qE 'timeout'; then continue; fi
+    # allow a router/client default timeout in the same file
+    if grep -qE 'timeout[[:space:]]*[:=]' "$file" 2>/dev/null; then continue; fi
+    unbounded+="$line"$'\n'
+  done <<< "$CALL_HITS"
+  if [[ -n "${unbounded//[$'\n']/}" ]]; then
+    fail "timeout on every call (call site(s) with no timeout)"
+    printf '%s' "$unbounded" | sed '/^$/d;s/^/      /'
+  else
+    pass "timeout on every call"
+  fi
+fi
+
+# --- Check 3: retries are bounded (no while True retry loops) --------------
+LOOP_HITS="$(grep_files 'while[[:space:]]+True' "${CODE_FILES[@]+"${CODE_FILES[@]}"}")"
+# only treat as a retry loop if a retry/except keyword is nearby in the file
+retry_loops=""
+if [[ -n "$LOOP_HITS" ]]; then
+  while IFS= read -r line; do
+    file="${line%%:*}"
+    if grep -qiE '(retry|num_retries|except|completion\(|create\()' "$file" 2>/dev/null; then
+      retry_loops+="$line"$'\n'
+    fi
+  done <<< "$LOOP_HITS"
+fi
+if [[ -n "${retry_loops//[$'\n']/}" ]]; then
+  fail "retries bounded (unbounded 'while True' retry loop)"
+  printf '%s' "$retry_loops" | sed '/^$/d;s/^/      /'
+else
+  pass "retries bounded"
+fi
+
+# --- Check 4: a fallback is configured when a router/model_list exists -----
+HAS_ROUTER="$(grep_files '(Router\(|model_list|model_name)' "${ALL_FILES[@]}")"
+if [[ -z "$HAS_ROUTER" ]]; then
+  skip "fallback configured (no router/model_list present)"
+else
+  HAS_FALLBACK="$(grep_files '(fallbacks|content_policy_fallbacks|context_window_fallbacks|default_fallbacks)' "${ALL_FILES[@]}")"
+  if [[ -n "$HAS_FALLBACK" ]]; then
+    pass "fallback configured"
+  else
+    fail "fallback configured (router/model_list present but no fallback list)"
+  fi
+fi
+
+# --- Check 5: config files parse and list >=2 model entries ----------------
+check_config_models() { # $1 = file
+  local f="$1" count=""
+  case "$f" in
+    *.json)
+      if command -v python3 >/dev/null 2>&1; then
+        count="$(python3 - "$f" <<'PY' 2>/dev/null
+import json,sys,re
+d=open(sys.argv[1]).read()
+try: obj=json.loads(d)
+except Exception: print("PARSEFAIL"); sys.exit(0)
+s=json.dumps(obj)
+print(len(re.findall(r'"model_name"|"model"\s*:', s)))
+PY
+)"
+      fi ;;
+    *.yaml|*.yml)
+      if command -v python3 >/dev/null 2>&1 && python3 -c 'import yaml' 2>/dev/null; then
+        count="$(python3 - "$f" <<'PY' 2>/dev/null
+import yaml,sys,re
+try: obj=yaml.safe_load(open(sys.argv[1]).read())
+except Exception: print("PARSEFAIL"); sys.exit(0)
+print(len(re.findall(r'model_name|(^|\s)model\s*:', str(obj))))
+PY
+)"
+      else
+        # no yaml lib: fall back to counting model_name occurrences textually
+        count="$(grep -cE 'model_name' "$f" 2>/dev/null || echo 0)"
+      fi ;;
+  esac
+  echo "${count:-}"
+}
+
+CONFIG_FILES=("${YAML_FILES[@]+"${YAML_FILES[@]}"}" "${JSON_FILES[@]+"${JSON_FILES[@]}"}")
+relevant_config=0
+for f in "${CONFIG_FILES[@]+"${CONFIG_FILES[@]}"}"; do
+  [[ -z "$f" ]] && continue
+  if grep -qE '(model_list|model_name|litellm|router_settings)' "$f" 2>/dev/null; then
+    relevant_config=1
+    res="$(check_config_models "$f")"
+    if [[ "$res" == "PARSEFAIL" ]]; then
+      fail "config parses ($f does not parse)"
+    elif [[ "$res" =~ ^[0-9]+$ ]] && [[ "$res" -ge 2 ]]; then
+      pass "config parses with >=2 model entries ($f)"
+    else
+      fail "config has >=2 model entries ($f has ${res:-0}; need a fallback target)"
+    fi
+  fi
+done
+[[ $relevant_config -eq 0 ]] && skip "config parses with >=2 models (no router config file present)"
+
+echo "---"
+if [[ $fail_count -eq 0 ]]; then
+  echo "verify.sh: all applicable checks passed."
+  exit 0
+else
+  echo "verify.sh: $fail_count check(s) FAILED."
+  exit 1
+fi

package/skills/logistics-ops/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: logistics-ops
+description: "Use when an order is paid and packed and the box now has to move, go sideways, or come back — picking a carrier and service and cutting a label, reacting to a delivery exception, getting ahead of where-is-my-order tickets, running a return, exchange or refund with its reverse label, filing a carrier claim before the window closes, and setting return-window and restocking-fee policy. NOT setting stock levels or reorder points (that is `inventory`), NOT sourcing or buying from suppliers (that is `procurement`), NOT writing the apology to the customer (that is `customer-support`)."
+tags: [logistics, shipping, carriers, returns, reverse-logistics, fulfillment, tracking]
+recommends: [inventory, procurement, customer-support, api-connector-builder, webhooks, bookkeeping]
+origin: risco
+---
+
+# Logistics-ops — the box is packed, now move it, watch it, and bring it home cheap
+
+You run the parcel as an operation. An order is **paid and packed**; from here the
+box has exactly four things it can do — ship out, travel, go sideways, or come
+back — and your job is to make each one cost the least while keeping the promise the
+order made. You ship on the cheapest service that still hits the delivery date, you
+catch the parcel when it goes wrong *before the customer notices*, and you turn the
+return into the smallest possible revenue loss.
+
+You do **not** decide what stock to hold or when to reorder — that is
+[`inventory`](../inventory/SKILL.md). You do not source or buy from suppliers —
+that is [`procurement`](../procurement/SKILL.md) (inbound from vendors, not outbound
+to customers). You do not write the on-voice customer reply — you hand the *facts and
+the trigger* to [`customer-support`](../customer-support/SKILL.md) and it writes the
+apology around them. You do not host the carrier-API webhook listener — that is
+[`api-connector-builder`](../api-connector-builder/SKILL.md) /
+[`webhooks`](../webhooks/SKILL.md). And you do not post the refund to the books —
+that is [`bookkeeping`](../bookkeeping/SKILL.md). You decide *what calls to make and
+when*, and *what to do with the box*.
+
+## The parcel lifecycle — the spine
+
+Every parcel moves through four legs. Two of them (EXCEPT, REVERSE) are where
+operators lose money by treating them as edge cases. They are not: exceptions hit
+**8-12% of parcels** (≈18% at peak) and returns run **≈20% of online sales**. Build
+both as first-class paths.
+
+```text
+  SHIP            TRACK             EXCEPT             REVERSE
+  rate-shop  ──►  watch the    ──►  tiered        ──►  return / exchange /
+  + cut label     tracker           response           refund + reverse label
+  + validate      (event-driven)    by severity        + carrier claim
+  address                              ▲                   ▲
+                       └── exception ──┘                   │
+                       └────────── return requested ───────┘
+```
+
+- **SHIP** — order is paid and packed; choose carrier + service against the delivery
+  promise, validate the address, buy the label.
+- **TRACK** — label exists; watch the tracker for status changes via webhook, not
+  polling, and notify the customer proactively.
+- **EXCEPT** — the tracker fired a delivery exception; classify it and respond on a
+  severity clock.
+- **REVERSE** — the customer wants it back / it came back damaged; run the
+  disposition decision, cut the reverse label, file any claim.
+
+## Ship — rate-shop, don't reflex
+
+Pick the service against **the delivery promise the order actually made**, not your
+habit. "2-day paid at checkout" sets the constraint; the cheapest service that still
+delivers by that date wins. Shipping everything one way leaves money on the table on
+every order.
+
+**Audit the surcharges — the headline is a lie.** The 2026 carrier increase reads as
+**5.9%** (UPS GRI effective 2025-12-22, FedEx 5.9% effective 2026-01-05) but lands at
+a real **8-12%** once new dimensional/cubic criteria for Additional Handling and
+Large Package kick in; USPS Ground Advantage is up **7.8%**, and the residential
+surcharge climbed ~8% into the mid-$6 range. So compare *landed* cost per shipment
+including DIM weight and surcharges, never the base rate card.
+
+**Validate the address before you buy the label.** A bad/undeliverable address is the
+cheapest exception to prevent and the most common one to suffer — fix it at the API,
+not after a failed attempt.
+
+```python
+# EasyPost: build the shipment, rate-shop, buy the cheapest that fits the promise.
+shipment = client.shipment.create(
+    to_address=to_addr,        # validated upstream
+    from_address=from_addr,
+    parcel={"length": 9, "width": 6, "height": 3, "weight": 12},  # drives DIM
+)
+# Filter to services that hit the promised delivery date, THEN take the cheapest.
+rate = shipment.lowest_rate(carriers=["USPS", "UPS", "FedEx"])
+bought = client.shipment.buy(shipment.id, rate=rate)
+# `bought.tracker` is now live (pre_transit → ... → delivered).
+```
+
+```text
+Bad : "We always ship UPS Ground." → overpays on light zone-1 parcels,
+      misses the 2-day promise, eats the surcharge increase blind.
+Good: rate-shop USPS/UPS/FedEx against the 2-day promise, compare landed
+      cost incl. DIM + surcharges, buy the cheapest service that still hits
+      the date. Validate the address first.
+```
+
+## Track — kill WISMO before it becomes a ticket
+
+WISMO ("where is my order") is **30-40% of ecommerce support contacts** (50%+ at peak)
+and each human-handled ticket costs **$5-$22**. The whole game is to message the
+customer *before* they message you.
+
+**Use the tracker webhook, not a polling loop.** EasyPost pushes `tracker.updated`
+events as the parcel moves; subscribe and react to status changes — `in_transit`,
+`out_for_delivery`, `exception`, `delivered`. Polling burns API calls and lags reality.
+(The listener *hosting* is [`webhooks`](../webhooks/SKILL.md)' job; you decide which
+events fire which message.)
+
+**The window is tiny.** The difference between a handled exception and a WISMO ticket
+is often only **4-12 hours** of response time. Fire a proactive notification on the
+status change and the ticket never gets created — and 98% of consumers say shipping
+shapes brand loyalty, so this *is* retention work.
+
+You supply the trigger and the fact ("FedEx shows out-for-delivery, EDD today").
+[`customer-support`](../customer-support/SKILL.md) writes the tone and owns the SLA on
+the reply. Never let support invent an ETA the carrier hasn't given.
+
+## Except — the tiered exception protocol
+
+A failed delivery costs **~$20-30 direct and $140+ in lost future revenue**, so triage
+by severity, don't treat every exception the same. First **normalize** the code:
+carriers label the same event differently (FedEx, UPS, USPS each use distinct
+exception codes for address / weather / damage / failed-attempt — see the reference
+glossary), so map to a bucket before you route.
+
+| Exception type        | Act on the parcel                              | Customer-comms SLA            |
+| --------------------- | ---------------------------------------------- | ----------------------------- |
+| Damage / past EDD     | Open claim path, prep replacement/refund       | Proactive outreach **same business day** |
+| Address / access      | Correct address, intercept, break reattempt    | Resolve within **24 h**       |
+| Weather / operational | Hold, let carrier recover, monitor             | **48-h** check-in cadence     |
+| Failed attempt        | Reattempt or redirect to pickup before cycle 2 | Within **24 h**               |
+
+Sequence is always **act → notify → escalate**: fix the parcel first (intercept,
+reattempt, claim), *then* send the proactive message, *then* escalate to the carrier
+if the clock runs out. Don't notify before you have an action, and don't escalate
+before you've notified.
+
+## Claims — file before the window closes
+
+Claim windows are hard deadlines. Miss them and the money is simply gone. Capture
+evidence **at exception detection**, because you cannot reconstruct it later.
+
+| Carrier | Damaged / missing contents      | Lost / undelivered           | Guaranteed-service refund |
+| ------- | ------------------------------- | ---------------------------- | ------------------------- |
+| USPS    | ≤ **60 days** from mailing*     | (varies by service)          | —                         |
+| UPS     | notice ≤ **60 days** of delivery| ≤ 60 days of scheduled deliv.| ≤ **15 days** of invoice  |
+| FedEx   | ≤ **60 days** of ship date (intl **21 d**) | up to **9 months** | ≤ **15 days** of invoice  |
+
+\*Windows vary by service class; confirm against the full matrix in references before
+relying on a date.
+
+Evidence checklist — gather **now**, at detection:
+
+- [ ] Tracking number + the exception event/screenshot (timestamped)
+- [ ] Photos of the damaged item *and* the packaging
+- [ ] Declared/invoice value and the original label
+- [ ] Weight and dimensions as shipped
+- [ ] For guaranteed-service refunds: the carrier invoice (15-day clock starts there)
+
+## Reverse — turn the return into the smallest loss
+
+Returns are **≈20% of online sales** (NRF: 19.3% returned in 2025; apparel runs
+20-40%), not an edge case — design the reverse flow as a primary path. Route by
+*reason*, and default to retaining revenue before handing back cash.
+
+| Return reason       | Default disposition                          | Why                                   |
+| ------------------- | -------------------------------------------- | ------------------------------------- |
+| Defective / damaged | Refund or replacement, **no restocking fee** | Your fault — fee kills the relationship |
+| Wrong item sent     | Replacement + free reverse label             | Your fault — fix fast                  |
+| Changed mind / size | **Instant exchange** or store credit first   | Retains the revenue, often cheaper than reverse freight |
+| Not as described    | Refund or store credit                       | Listing risk — fix the listing too    |
+| Low-value bulky     | **Keep-it / refund** (no return)             | Reverse freight > item value          |
+
+**Tune the policy as both a conversion lever and a cost lever.** 82% of consumers rank
+free returns as a key purchase factor and 81% read the policy before buying — but 72%
+of merchants now charge a restocking fee, typically **10-25%** (15-25% standard), with
+windows of **30-90 days**. Charge the fee only where the reason is buyer-side
+("changed mind"), never on a defect. And screen for fraud: ~9% of returns are
+fraudulent and 85% of retailers now use AI to flag them — flag mismatched
+weight/serial, serial returners, and wardrobing.
+
+```python
+# The reverse label is the SAME create call with is_return: true (swaps to/from).
+return_shipment = client.shipment.create(
+    to_address=from_addr,      # back to your warehouse
+    from_address=to_addr,      # from the customer
+    parcel=parcel,
+    is_return=True,
+)
+return_label = client.shipment.buy(
+    return_shipment.id, rate=return_shipment.lowest_rate()
+)
+```
+
+Hand the **restock quantity** to [`inventory`](../inventory/SKILL.md) (does it go back
+to sellable stock?) and the **refund accounting** to
+[`bookkeeping`](../bookkeeping/SKILL.md) (the credit-note entry). You decide the
+disposition; they record the consequence.
+
+## Anti-patterns
+
+| Anti-pattern | Why it costs you | Do instead |
+| ------------ | ---------------- | ---------- |
+| Ship by habit, one carrier always | Overpays per order, misses promises | Rate-shop the three against the promise |
+| Trust the "5.9%" headline | Real increase is 8-12% with DIM/surcharges | Audit landed cost per shipment |
+| Poll the tracker on a timer | Lags reality, burns API calls | Subscribe to `tracker.updated` webhooks |
+| Wait for the WISMO ticket | Ticket costs $5-22; you missed the 4-12 h window | Notify proactively on status change |
+| Same urgency for damage and weather | Wastes effort or misses the costly one | Tier by severity (table above) |
+| Cash-refund by default | Hands back revenue you could keep | Offer exchange / store-credit first |
+| No return-window or restocking policy | Can't defend the cost or the conversion | Set 30-90 d window, 10-25% fee buyer-side only |
+| Restocking fee on a defect | Burns the relationship on your own fault | Free reverse label for defective/wrong-item |
+| Capture claim evidence "later" | Window closes, money gone; can't reconstruct | Photograph + record value/weight at detection |
+| Let support invent the ETA | A wrong promise becomes a second complaint | Give support the tracker fact, not a guess |
+| Treat returns as an edge case | They're ~20% of orders | Design REVERSE as a primary path |
+
+## References
+
+Full per-carrier exception-code glossary (FedEx/UPS/USPS → the four buckets), the
+complete claim-window matrix with required evidence per claim type, and runnable
+EasyPost snippets (rate-shop + one-call buy, tracker webhook handler shape, the
+`is_return: true` reverse label) live in
+[`references/carriers-and-claims.md`](references/carriers-and-claims.md).

package/skills/logistics-ops/evals/README.md

@@ -0,0 +1,20 @@
+# Evals — logistics-ops
+
+`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 — there is no `verify.sh`, because the skill emits operational judgment (a
+carrier choice, an exception-response plan, a return disposition, a claim-filing
+call), not a single machine-checkable artifact. Run them through whatever eval
+harness the repo provides, or by hand: feed each `should_trigger` prompt to the
+router and confirm it selects `logistics-ops` — including the non-obvious one (the
+"delivery exception, what do I tell the customer" prompt that never says "shipping")
+and the Spanish/Catalan return and rate-shop phrasings. Feed each
+`should_not_trigger` prompt and confirm it routes to the named sibling
+(`inventory`, `procurement`, `customer-support`, `bookkeeping`, `webhooks`) 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 — damage → same-business-day outreach, the claim window + evidence at
+detection, the dual 60-day/15-day clocks, the proactive tracker-fact message with
+tone handed to customer-support, exchange/store-credit before cash with no
+restocking fee on a defect, and the hand-offs to bookkeeping and inventory — and
+confirm it never invents an ETA the carrier didn't give.

package/skills/logistics-ops/evals/cases.yaml

@@ -0,0 +1,48 @@
+skill: logistics-ops
+
+should_trigger:
+  - prompt: "Order #1043 is packed and going to a customer two zones away who paid for 2-day — which carrier and service do I use, and cut me the label?"
+    why: SHIP leg — rate-shop against the delivery promise and buy the label, the core outbound ask.
+  - prompt: "The tracker just flipped to 'delivery exception — address issue.' What do I do and what do I tell the customer?"
+    why: EXCEPT leg, tiered protocol. Non-obvious — no word "shipping" or "logistics" appears, but it's the exception-response core.
+  - prompt: "Customers keep opening 'where is my order' tickets — how do I get ahead of that?"
+    why: TRACK leg — proactive tracking notification / WISMO deflection, reads as a support problem but the fix is event-driven tracking here.
+  - prompt: "Gestiona la devolución de este pedido: el cliente dice que la talla no le sirve y quiere cambiarla."
+    why: Spanish trigger — REVERSE leg, changed-mind/size return defaulting to instant exchange over cash refund.
+  - prompt: "A package arrived smashed — how long do I have to file a claim with FedEx and what do I need?"
+    why: Claims — the carrier claim-window + evidence-at-detection ask.
+  - prompt: "Quin transportista surt més barat per a aquest enviament de 5 kg a Madrid en 48 h?"
+    why: Catalan trigger — SHIP leg rate-shop against a delivery promise including DIM/landed cost.
+
+should_not_trigger:
+  - prompt: "How many units of this SKU should I reorder and what's my safety stock?"
+    route_to: inventory
+    why: Stock-level / reorder-point decision, not moving an existing parcel.
+  - prompt: "I need to find a new supplier for these shipping boxes and negotiate payment terms."
+    route_to: procurement
+    why: Inbound vendor sourcing and terms, not the outbound or reverse parcel.
+  - prompt: "Write the empathetic reply to the angry customer whose order is late."
+    route_to: customer-support
+    why: The on-voice apology and reply SLA; this skill supplies the tracker facts, support writes the tone.
+  - prompt: "Record the $80 refund as a credit note in our accounts."
+    route_to: bookkeeping
+    why: Posting the AP/credit-note entry; this skill only decides refund-vs-exchange, not the books.
+  - prompt: "Build the webhook endpoint that receives EasyPost tracker events and retries on failure."
+    route_to: webhooks
+    why: Hosting/plumbing the listener and retries; this skill decides which events fire which action, not how to host them.
+
+capability:
+  - scenario: >
+      An order that shipped 2-day arrived a full day late AND the tracker shows a
+      "delivery exception — damaged." The customer is asking for a cash refund.
+      Ask the skill for the full operational response: how to classify and respond,
+      what to do about the carrier, what to tell the customer, and how to handle the
+      refund.
+    must_include:
+      - classifies the exception as damage and triggers same-business-day proactive outreach (not a 48-h or 24-h tier)
+      - names the FedEx/UPS/USPS claim window and says to file before it closes, capturing evidence (photos, declared value, weight, tracking) NOW at detection
+      - flags that two clocks run — the ~60-day damage claim and the 15-day guaranteed-service refund on the late delivery — and files the 15-day one first
+      - gives a proactive, tracker-fact-based customer message instead of waiting for a WISMO ticket, and hands the reply tone/SLA to customer-support
+      - on the refund, offers instant exchange or store credit before cash to retain revenue, and does not charge a restocking fee because the cause is damage (seller-side)
+      - routes the refund accounting to bookkeeping and any restock decision to inventory rather than doing them here
+      - does NOT invent a delivery ETA the carrier has not provided

package/skills/logistics-ops/references/carriers-and-claims.md

@@ -0,0 +1,105 @@
+# Carriers, exception codes, and claim windows
+
+Lookup material offloaded from the spine: the per-carrier exception-code map, the
+full claim matrix with required evidence, and runnable EasyPost snippets. All facts
+accessed 2026-06-02 (Sifted / ShipperHQ / Goshippo / LateShipment / FedEx / USPS /
+ShippingEasy / Cahoot / EasyPost docs).
+
+## Normalize the exception code to one of four buckets
+
+Carriers emit different codes for the same physical event. Map to a bucket, then run
+the protocol from the SKILL's EXCEPT table.
+
+| Bucket | Physical event | Typical FedEx wording | Typical UPS wording | Typical USPS wording |
+| ------ | -------------- | --------------------- | ------------------- | -------------------- |
+| Address / access | Bad, incomplete, or inaccessible address | "Incorrect address", "Customer not available or business closed" | "Address Correction", "The receiver was not available" | "No Access to Delivery Location", "Insufficient Address" |
+| Failed attempt | Carrier tried, nobody/access to receive | "Delivery attempted" | "A delivery attempt was made" | "Delivery Attempted - No Access" |
+| Weather / operational | Weather, network, mechanical delay | "Local delivery restriction — weather", "Operational delay" | "Adverse weather conditions", "Emergency situations or natural disasters" | "Emergency weather delay", "Processing exception" |
+| Damage / loss | Item damaged, lost, or contents missing | "Shipment damaged", "Package handling — damaged" | "This package was damaged in transit" | "Damaged in Transit", "Loss/rifling" |
+
+Rule: never route on the raw string. Two carriers will name "we couldn't deliver"
+four different ways — bucket first, then apply the severity clock.
+
+## Full claim-window matrix
+
+Windows vary by **service class** within a carrier; treat these as the governing
+defaults and confirm the exact class before relying on a date. Filing late = the
+claim is denied and the money is gone.
+
+| Carrier | Claim type | Window | Required evidence |
+| ------- | ---------- | ------ | ----------------- |
+| USPS | Damage / missing contents | File no later than **60 days** from mailing date | Proof of value (receipt/invoice), evidence of insurance, photos of damage + packaging |
+| USPS | Lost | After the service-specific waiting period, within the filing window for the class | Proof of value, proof of insurance, tracking |
+| UPS | Damage | Notice within **60 days** of delivery date | Photos of item + packaging, declared value, tracking, label |
+| UPS | Lost / undelivered | Within **60 days** of the scheduled delivery date | Proof of value, tracking, label |
+| UPS | Guaranteed-service refund | Within **15 days** of the invoice date | The carrier invoice showing the service + late scan |
+| FedEx | Damage / missing contents (US) | Within **60 days** of the ship date | Photos of item + packaging, value, weight/dims, tracking, label |
+| FedEx | Damage / missing (international) | Within **21 days** of delivery | As above |
+| FedEx | Lost / undelivered | Up to **9 months** from ship date | Proof of value, tracking, label |
+| FedEx | Guaranteed-service refund | Within **15 days** of the invoice date | Invoice showing the committed service + the missed commitment |
+
+Two clocks run at once on a guaranteed shipment that arrives damaged and late: the
+**damage claim** (≈60 days) and the **service-refund claim** (≈15 days from invoice).
+The 15-day refund clock is the one operators miss — file it first.
+
+## EasyPost snippets
+
+### Rate-shop + one-call buy
+
+```python
+import easypost
+client = easypost.EasyPostClient(api_key)
+
+shipment = client.shipment.create(
+    to_address={"name": "...", "street1": "...", "city": "...",
+                "state": "...", "zip": "...", "country": "US"},
+    from_address=from_address,
+    parcel={"length": 9.0, "width": 6.0, "height": 3.0, "weight": 12.0},
+)
+
+# Restrict to services that meet the promised delivery date upstream, then:
+rate = shipment.lowest_rate(carriers=["USPS", "UPS", "FedEx"])
+bought = client.shipment.buy(shipment.id, rate=rate)
+
+label_url = bought.postage_label.label_url
+tracking_code = bought.tracking_code
+tracker = bought.tracker          # status starts at pre_transit
+```
+
+### Tracker webhook handler shape (event-driven, not polled)
+
+EasyPost POSTs a `tracker.updated` event each time the parcel's status changes.
+Decide the action per status; let `webhooks` own the actual endpoint/retries.
+
+```python
+def handle_easypost_event(event):
+    if event["description"] != "tracker.updated":
+        return
+    tracker = event["result"]
+    status = tracker["status"]            # in_transit, out_for_delivery, exception, delivered
+    if status == "exception":
+        bucket = normalize_exception(tracker["status_detail"])  # → one of the four buckets
+        route_to_protocol(bucket, tracker)        # severity clock from the EXCEPT table
+        notify_customer_proactively(tracker)      # facts only; tone → customer-support
+    elif status in ("out_for_delivery", "delivered"):
+        notify_customer_proactively(tracker)
+```
+
+### Reverse label — same create call, `is_return: true`
+
+```python
+return_shipment = client.shipment.create(
+    to_address=from_address,    # your warehouse
+    from_address=customer_addr, # the customer (to/from swap)
+    parcel=parcel,
+    is_return=True,
+)
+return_label = client.shipment.buy(
+    return_shipment.id, rate=return_shipment.lowest_rate()
+)
+# Email return_label.postage_label.label_url to the customer.
+```
+
+Carrier coverage for rate-shop breadth: EasyPost ~100+ carriers, Shippo ~85+,
+ShipStation ~200+. Choosing/hosting the integration is
+`api-connector-builder` / `webhooks`; this skill decides which calls fire when.