@damiangilgonzalez/harness 1.3.7

package/skills/instagram-api/references/publish-reel.md

@@ -0,0 +1,98 @@
+# Publishing reference — containers, fields, errors, batching
+
+All endpoints on `https://{GRAPH_HOST}/{GRAPH_VERSION}/...` with `GRAPH_VERSION=v25.0`.
+
+## Container fields by media type
+
+### Reels (`media_type=REELS`)
+
+| Field | Required | Notes |
+|---|---|---|
+| `media_type` | yes | Literal `REELS` |
+| `video_url` | yes | Public MP4, reachable for the whole processing window |
+| `caption` | no | Up to 2200 chars; hashtags/mentions allowed |
+| `share_to_feed` | no | `true` shows the Reel in the main feed grid too |
+| `cover_url` | no | Public image URL for the cover frame |
+| `thumb_offset` | no | Milliseconds into the video for the auto-cover (ignored if `cover_url` set) |
+| `location_id` | no | A Page id usable as a location tag |
+
+### Single image / feed (`media_type` omitted or `IMAGE`)
+
+Use `image_url` instead of `video_url`. No `share_to_feed`.
+
+### Stories (`media_type=STORIES`)
+
+`video_url` or `image_url`; no `caption`. Expires after 24h. Insights metric set differs (see insights-metrics.md).
+
+### Carousel (two-stage)
+
+1. Create each child container with `is_carousel_item=true` (+ `image_url`/`video_url`).
+2. Create the parent: `media_type=CAROUSEL`, `children=<id1>,<id2>,...`, optional `caption`.
+3. Poll the parent's `status_code`, then `media_publish` the parent `creation_id`.
+
+Why the extra stage: children must each finish before the parent can be published.
+
+## Status codes
+
+`GET /{container-id}?fields=status_code,status` returns one of:
+
+- `IN_PROGRESS` — keep polling (~60s cadence).
+- `FINISHED` — publish now.
+- `ERROR` — read `status` for the reason; do not retry the same source blindly.
+- `EXPIRED` — container sat unpublished too long; recreate from step 1.
+
+Poll ceiling ~5 minutes. Containers are not permanent.
+
+## Common error subcodes on publish
+
+| Subcode | Meaning | Fix |
+|---|---|---|
+| 51 | 24h publish limit reached (50/account) | Wait or read `content_publishing_limit` |
+| 9007 | Media not ready / not `FINISHED` | Poll until `FINISHED` first |
+| 2207003 | Media download failed | Make `video_url` truly public |
+| 2207026 | Unsupported video format | Re-encode H.264/HEVC, 9:16, 5–90s |
+
+## Retry / backoff snippet
+
+```python
+import time, requests
+
+def wait_finished(base, cid, tok, max_tries=10, step=30):
+    for _ in range(max_tries):
+        st = requests.get(f"{base}/{cid}",
+                          params={"fields": "status_code", "access_token": tok}
+                          ).json()["status_code"]
+        if st == "FINISHED":
+            return
+        if st in ("ERROR", "EXPIRED"):
+            raise RuntimeError(f"{cid} -> {st}")
+        time.sleep(step)
+    raise TimeoutError(f"{cid} never FINISHED")
+```
+
+## Batch publish with cap check
+
+```python
+def remaining_quota(base, uid, tok):
+    d = requests.get(f"{base}/{uid}/content_publishing_limit",
+                     params={"fields": "quota_usage,config", "access_token": tok}
+                     ).json()["data"][0]
+    return d.get("config", {}).get("quota_total", 50) - d.get("quota_usage", 0)
+
+def publish_batch(base, uid, tok, jobs):
+    published = []
+    for video_url, caption in jobs:
+        if remaining_quota(base, uid, tok) <= 0:
+            break  # stop cleanly; don't trip subcode 51
+        cid = requests.post(f"{base}/{uid}/media", data={
+            "media_type": "REELS", "video_url": video_url,
+            "caption": caption, "access_token": tok}).json()["id"]
+        wait_finished(base, cid, tok)
+        mid = requests.post(f"{base}/{uid}/media_publish",
+                            data={"creation_id": cid, "access_token": tok}
+                            ).json()["id"]
+        published.append(mid)
+    return published
+```
+
+Check the cap *inside* the loop, not once before — each publish consumes one slot.

package/skills/instagram-api/scripts/verify.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# verify.sh — instagram-api
+# Read-only, offline, deterministic lint of generated IG Graph API artifacts/scripts.
+# Exits 0 on a clean OR empty target (no false failure). Non-zero only on a real violation.
+#
+# Checks:
+#   1. No deprecated metric tokens REQUESTED in code/config (the trap names are
+#      plays / clips_replays_count / ig_reels_aggregated_all_plays_count and a
+#      bare "impressions" used as a metric value).
+#   2. If a publish script is present, it references all 3 steps: /media, status_code, /media_publish
+#   3. GRAPH_VERSION (or graph_version) is pinned, not blank
+#
+# Usage: verify.sh [TARGET_DIR]   (default: current directory)
+#
+# The skill's OWN source files (this dir) document the deprecated-metric trap
+# in prose and in eval prompts; they are not emitted artifacts, so they are
+# skipped. The lint is therefore trustworthy even when the target workspace
+# contains a checked-out copy of this skill.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify: target '$TARGET' is not a directory; nothing to check."
+  exit 0
+fi
+
+# Absolute path of THIS skill's root (scripts/ -> skill dir). Files inside it are
+# skill source (SKILL.md, references, evals, this script), never emitted output.
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# Files worth scanning: scripts, configs, and ingested wiki artifacts.
+# Portable across bash 3.2 (macOS) — no mapfile; newline-delimited list.
+FILES=()
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  # Skip this skill's own source tree: it documents the trap on purpose.
+  abs="$(cd "$(dirname "$f")" 2>/dev/null && pwd)/$(basename "$f")"
+  case "$abs" in
+    "$SELF_DIR"/*) continue ;;
+  esac
+  FILES+=("$f")
+done < <(
+  find "$TARGET" -type f \
+    \( -name '*.sh' -o -name '*.py' -o -name '*.js' -o -name '*.ts' \
+       -o -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.md' \
+       -o -name '*.env' -o -name '.env' \) \
+    2>/dev/null
+)
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  echo "verify: no candidate files under '$TARGET'; clean by default."
+  exit 0
+fi
+
+fail=0
+
+note_fail() { echo "FAIL: $1"; fail=1; }
+
+# --- Check 1: deprecated metric tokens ---------------------------------------
+# We only flag metrics actually REQUESTED in emitted code/config, not prose that
+# merely names them. A request context is a `metric=` / `"metric":` parameter
+# whose value contains a deprecated token. This is scoped to artifact/code files;
+# the skill's own SKILL.md (which documents the trap) is not an emitted artifact.
+DEP='plays|clips_replays_count|ig_reels_aggregated_all_plays_count|impressions'
+# A real request context, NOT prose. The `metric` token must sit at a genuine
+# request boundary — start of line, a URL query delim (? or &), an opener
+# (quote / { / ( / =), or a curl flag (-d / --data) — so an English sentence like
+# "why does metric=impressions error?" (preceded by the word "does ") is ignored.
+# It must then be a metric=value / "metric":"value" param whose comma-separated
+# value list contains a deprecated token as a WHOLE field (the dep token ends the
+# field), so mid-word matches like "displays" or "impressions_rate" don't trip.
+REQ_LEAD='(^|[?&{("'"'"']|=|-d |--data[ =]|--data-urlencode )'
+REQ_CTX="${REQ_LEAD}metric[\"' ]*[:=][\"' ]*([a-z0-9_]+,)*(${DEP})([,\"' &]|$)"
+for f in "${FILES[@]}"; do
+  case "$f" in
+    *.sh|*.py|*.js|*.ts|*.json|*.yaml|*.yml|*.env|.env) ;;
+    *) continue ;;  # skip free-prose .md docs; they may legitimately name the trap
+  esac
+  if grep -nEi "$REQ_CTX" "$f" >/dev/null 2>&1; then
+    while IFS= read -r line; do
+      note_fail "deprecated metric requested in $f: $line"
+    done < <(grep -nEi "$REQ_CTX" "$f")
+  fi
+done
+
+# Wiki artifacts (.md / .yaml) store metrics as YAML keys. Flag a deprecated
+# token used AS a metric key (e.g. "  plays: 123"), which won't match prose.
+KEY_CTX="^[[:space:]]+(${DEP})[[:space:]]*:"
+for f in "${FILES[@]}"; do
+  case "$f" in
+    *.md|*.yaml|*.yml) ;;
+    *) continue ;;
+  esac
+  if grep -nE "$KEY_CTX" "$f" >/dev/null 2>&1; then
+    while IFS= read -r line; do
+      note_fail "deprecated metric key in artifact $f: $line"
+    done < <(grep -nE "$KEY_CTX" "$f")
+  fi
+done
+
+# --- Check 2: publish scripts must reference all 3 steps ----------------------
+# Only applies to executable code (.sh/.py/.js/.ts) that calls media_publish —
+# not to prose/yaml docs that merely mention it.
+for f in "${FILES[@]}"; do
+  case "$f" in
+    *.sh|*.py|*.js|*.ts) ;;
+    *) continue ;;
+  esac
+  if grep -qE 'media_publish' "$f" 2>/dev/null; then
+    grep -qE '/media([^_]|$|")' "$f" 2>/dev/null || note_fail "publish script $f missing the create step (/media)"
+    grep -qE 'status_code'      "$f" 2>/dev/null || note_fail "publish script $f missing the status poll (status_code)"
+    # media_publish is present by definition of entering this branch.
+  fi
+done
+
+# --- Check 3: GRAPH_VERSION pinned, not blank --------------------------------
+# Only enforce in files that actually mention the version variable.
+for f in "${FILES[@]}"; do
+  if grep -qiE 'GRAPH_VERSION|graph_version' "$f" 2>/dev/null; then
+    # Flag an explicit blank/empty assignment.
+    if grep -nEi 'GRAPH_VERSION[[:space:]]*[=:][[:space:]]*("")?[[:space:]]*$' "$f" >/dev/null 2>&1; then
+      while IFS= read -r line; do
+        note_fail "GRAPH_VERSION unpinned (blank) in $f: $line"
+      done < <(grep -nEi 'GRAPH_VERSION[[:space:]]*[=:][[:space:]]*("")?[[:space:]]*$' "$f")
+    fi
+  fi
+done
+
+if [ "$fail" -ne 0 ]; then
+  echo "verify: violations found."
+  exit 1
+fi
+
+echo "verify: OK — no deprecated metrics, publish steps complete, version pinned."
+exit 0

package/skills/inventory/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: inventory
+description: "Use when deciding how much stock to hold and when to reorder it — classifying SKUs, sizing safety stock, setting reorder points and order quantities, and tracking the KPIs that keep a business from either stocking out or sitting on dead stock. NOT raising or negotiating the purchase order itself (that is `procurement`)."
+tags: [reorder-point, safety-stock, eoq, abc-xyz, replenishment, inventory-kpis, ddmrp, min-max]
+recommends: [procurement, logistics-ops, forecasting, dashboard, reporting, spreadsheet-ops]
+origin: risco
+---
+
+# Inventory
+
+You are setting **stock policy**: how much to hold, when to reorder, how much to reorder. You are not buying it (that is `procurement`) and not moving it (that is logistics-ops). You decide the numbers that tell the buyer what to order and when.
+
+Leave behind **two checkable artifacts** every time:
+
+1. **Reorder-policy table** — one row per SKU: `sku, abc_class, avg_demand, lead_time, safety_stock, reorder_point, order_qty, review_mode`. This is the standing policy.
+2. **Replenishment trigger list** — the subset of SKUs whose `on_hand <= reorder_point` right now, with a suggested order quantity. This is the action.
+
+`scripts/verify.sh` checks both for shape and the structural invariants (ROP ≥ safety stock, order_qty > 0, no false triggers). Run it before you hand anything off. It validates structure, not whether the buffers are commercially smart — that judgment is yours.
+
+## Pick the job
+
+The flow genuinely branches. Find the row that matches the ask before doing anything else.
+
+| Ask sounds like | Job | You produce |
+|---|---|---|
+| "which SKUs deserve tight control", "run ABC" | **Classify** | ABC×XYZ class per SKU → the `abc_class` column + a policy posture per class |
+| "how much safety stock", "we keep running out / sitting on dead stock" | **Size the buffer** | `safety_stock` per SKU, chosen Z, chosen formula |
+| "what's my reorder point", "set up min/max", "weekly or continuous" | **Set policy** | `reorder_point`, `order_qty`, `review_mode` → the full policy table |
+| "is our stock policy working", "turnover", "cut dead stock" | **Track** | KPI panel against the business's own history + cycle-count cadence |
+
+Classify before you size, size before you set policy. A uniform policy across every SKU is the original sin (anti-patterns table).
+
+## Classify first: ABC × XYZ
+
+Rule: **never apply one uniform service level or review mode to every SKU** — control is a budget, spend it where the value and the volatility are. Bad: 95% service on all 800 SKUs. Good: 99% on the high-value/stable AX items, make-to-order or near-zero buffer on the low-value/erratic CZ items.
+
+- **ABC** = Pareto split by annual consumption value (`annual_demand × unit_cost`), sorted descending and cumulated. A ≈ top ~80% of value (usually ~20% of SKUs), B the next band, C the long low-value tail.
+- **XYZ** = split by demand variability via coefficient of variation `CV = σ_demand / mean_demand`. X = stable (low CV), Y = fluctuating, Z = erratic.
+
+The 9-cell matrix maps to policy: **AX** → tight automated min/max, highest service; **CZ** → manual, minimal buffer or make-to-order; **AZ** → high value but erratic, the candidate for DDMRP (below). Full cumulative-value worked sort, CV cut points, and the 9-cell→(review mode, service level, buffer posture) matrix are in `references/abc-xyz.md`.
+
+## Safety stock
+
+Rule: **match the formula to which thing actually varies.** Picking the demand-only formula when the supplier's lead time swings is the most common under-buffering mistake — you buffer the wrong variance and still stock out.
+
+```text
+demand varies, lead time stable:     SS = Z · σ_demand · √LT
+both vary, independent:              SS = Z · √(LT · σ_demand² + avg_demand² · σ_LT²)
+both vary, correlated (King):        SS = Z · σ_demand · √LT + Z · avg_demand · σ_LT
+```
+
+`Z` is set by your **target service level**, never picked by feel:
+
+| Service level | Z |
+|---|---|
+| 90% | 1.28 |
+| 95% | 1.65 |
+| 97.5% | 1.96 |
+| 99% | 2.33 |
+
+Higher service costs disproportionately more buffer — the tail is fat, so each extra point past ~98% buys a chunk of cash you reserve for A/critical items and deny to C items. Bad→Good: supplier "usually 5 days but sometimes 12" + you used `Z·σ_demand·√LT` → switch to the independent or King formula so `σ_LT` is in the buffer. How to estimate `σ_demand` and `σ_LT` from sales/receipt history, all three formulas worked with numbers, and the diminishing-returns curve are in `references/safety-stock.md`.
+
+## Reorder point and order quantity
+
+These are **two separate decisions** — conflating them is the classic beginner error. ROP answers *when*, order quantity answers *how much*.
+
+```text
+ROP = (avg daily demand × lead-time days) + safety_stock        ← when to trigger
+EOQ = √(2 · D · S / H)                                          ← how much to order
+        D = annual demand, S = cost per order, H = annual holding cost per unit
+```
+
+EOQ minimizes ordering + holding cost under stable demand. It is an order-*size* lever and **never** a trigger — you do not "wait until you can order an EOQ." Keep `reorder_point` and `order_qty` as separate columns.
+
+**Continuous vs periodic review** is a real branch:
+
+| Mode | How it works | Use when | Cost |
+|---|---|---|---|
+| Continuous (min-max / s,S) | Order the moment on-hand hits ROP `s`, bring up to `S` | A items, perpetual stock visibility | Fastest reaction, needs live counts |
+| Periodic | Check on a fixed cadence (e.g. every Friday), order up to target | B/C items, batched POs, no live system | Needs a **bigger** buffer to cover the extra review-interval exposure |
+
+Periodic review adds `Z · σ_demand · √(review_interval)` of exposure on top of lead-time exposure — budget for it. Worked ROP/EOQ examples, the review-interval buffer adjustment, and the exact policy-table + trigger-list schemas (the columns verify.sh checks) are in `references/reorder-policies.md`.
+
+## Demand-driven option (DDMRP)
+
+When a static ROP keeps whipsawing on erratic demand — you re-tune it monthly and it is still wrong — switch that SKU to **buffer zones** instead of a fixed point.
+
+- **Red** = safety/critical, sized off lead-time and demand variability.
+- **Yellow** = demand coverage over the lead time.
+- **Green** = order cycle / order frequency.
+
+Trigger fires when **net flow position** = `on_hand + on_order − qualified_demand` drops from green into yellow. The zones recalculate as demand ramps, so you are not hand-editing safety stock every cycle.
+
+Decision rule: reach for DDMRP only on **erratic (Z-class), long-lead, or strategic** SKUs — never for steady C items where a flat ROP is cheaper to run. Zone sizing and the net-flow trigger are in `references/ddmrp.md`. Set `review_mode = ddmrp` for these SKUs.
+
+## Track it
+
+Prove the policy works with a KPI panel — and **recompute every metric against the business's own history**; the benchmarks below are sanity rails to flag against, not numbers to hallucinate or paste as targets.
+
+| KPI | Formula | Rough rail |
+|---|---|---|
+| Inventory turnover | COGS / avg inventory | ≈6–8×/yr (consumer goods) |
+| Days of inventory on hand | avg inventory / COGS × 365 | ≈30–60 days |
+| GMROI | gross margin / avg inventory cost | target > 2.5 |
+| Sell-through | units sold / units received | ≈70–85% / mo |
+| Stockout rate | stockout events / order lines | target < 5% |
+| Fill rate | lines filled complete / total lines | target > 95% |
+| Dead-stock flag | SKUs with zero movement over a defined window | flag, don't reorder |
+
+**Cycle counting, not an annual full count.** Count in a rolling sequence frequency-tiered off ABC: A items often (monthly/quarterly), C items rarely (annually). The warehouse never stops, and errors on high-value items surface fastest.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| One uniform service level / review mode across all SKUs | Overspends on C, under-protects A | ABC×XYZ → differentiated Z and review mode |
+| Demand-only SS when lead time is volatile | Buffers the wrong variance, still stocks out | Independent or King formula so `σ_LT` is in the buffer |
+| Treating ROP and order quantity as one number | "Wait to order a full batch" → late triggers | Separate `reorder_point` (when) and `order_qty` (how much) columns |
+| Using EOQ as a reorder trigger | EOQ is a size lever, not a signal | Trigger on ROP; size with EOQ |
+| Picking Z by feel | Service level is undefined and indefensible | Set service level → read Z from the table |
+| Static safety stock on erratic demand | Re-tuned monthly and still wrong | DDMRP buffer zones, `review_mode = ddmrp` |
+| Annual full physical count | Warehouse stops; high-value errors found too late | ABC-tiered rolling cycle counts |
+| Placing/negotiating the PO here | Wrong skill owns the buy | Hand the trigger list to `procurement` |
+
+## Hand-offs
+
+- Raising/negotiating the purchase order, supplier choice, payment terms, PO approval, three-way match → `procurement` (see `../procurement/SKILL.md`). You hand it the trigger list; it executes the buy.
+- Warehousing, picking, packing, shipping, carriers, returns flow → logistics-ops. You set the on-hand target; it physically fulfills.
+- Statistical/ML demand forecast, seasonality decomposition → forecasting. You *consume* a demand estimate and its variability; you do not own the model.
+- Live KPI dashboard → dashboard. Recurring KPI report → reporting.
+- Pivot tables, ABC cumulative-value sort mechanics in a sheet → spreadsheet-ops.

package/skills/inventory/evals/README.md

@@ -0,0 +1,3 @@
+# Evals: inventory
+
+Run the cases in `cases.yaml` against the skill. The `should_trigger` prompts (including the Catalan and Spanish ones, and the non-obvious "stocking out of X while sitting on a year of Y" symptom) should all load and apply `inventory`. The `should_not_trigger` prompts must each route to the named real sibling instead — `procurement` for raising/negotiating the PO, `logistics-ops` for warehousing/picking/shipping, `forecasting` for the statistical demand model, `dashboard` for the KPI visualization. The `capability` case is the rigor check: feed the agent a SKU list with demand, cost, lead times (some volatile), ordering and holding cost, and grade the output against the `must_include` rubric — differentiated service levels from ABC×XYZ, the safety-stock formula matched to what varies, ROP and EOQ kept as separate columns, a review mode per class, a clean trigger list with no false positives, dead-stock flagged, and the actual buy routed to procurement. `scripts/verify.sh` is the structural gate: point it at the emitted policy-table and trigger-list CSVs to confirm the required columns, that ROP ≥ safety stock, that order quantities are positive, and that the trigger list contains no false triggers. It validates shape and structural invariants only — it does not judge whether the buffer sizes are commercially right; that is the capability rubric's job.

package/skills/inventory/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: inventory
+
+should_trigger:
+  - prompt: "What reorder point and safety stock should I set for these 12 SKUs given their lead times?"
+    why: Core ROP + safety-stock sizing, the central job of this skill.
+  - prompt: "We keep stocking out of our bestseller but we're sitting on a year of slow movers — fix our stock levels."
+    why: Non-obvious symptom phrasing for simultaneous under- and over-stock; the buffer/classification job, not an explicit 'reorder point' ask.
+  - prompt: "Run an ABC analysis and tell me which products deserve tight inventory control."
+    why: Classification step (ABC×XYZ) that drives differentiated policy.
+  - prompt: "Punt de comanda i stock de seguretat per als nostres articles?"
+    why: Catalan for reorder point and safety stock — core ask in another language.
+  - prompt: "Cuánto stock de seguridad necesito si el proveedor a veces tarda el doble de lo normal?"
+    why: Spanish, and the lead-time-variability cue should route to the combined SS formula, not demand-only.
+  - prompt: "Should we review stock continuously with min/max or just check weekly?"
+    why: Continuous-vs-periodic review-mode decision, a real branch this skill owns.
+
+should_not_trigger:
+  - prompt: "Raise a PO to our supplier and negotiate better payment terms and the volume discount."
+    route_to: procurement
+    why: Placing and negotiating the actual purchase order and supplier terms is the buy, owned by procurement; inventory only says how much and when.
+  - prompt: "Set up our warehouse picking, packing and shipping flow with a carrier."
+    route_to: logistics-ops
+    why: Physically moving goods is logistics-ops; inventory sets the on-hand target, not the fulfillment process.
+  - prompt: "Forecast next quarter's demand from the last 3 years of sales with seasonality."
+    route_to: forecasting
+    why: Statistical/ML demand projection is forecasting; inventory consumes a demand estimate but does not build the model.
+  - prompt: "Build a live dashboard showing inventory turnover and stockout rate by category."
+    route_to: dashboard
+    why: Displaying the KPIs is dashboard; inventory defines and computes them but does not build the visualization.
+
+capability:
+  - scenario: >
+      Given a SKU list with annual demand, unit cost and margin, lead times (some volatile, e.g. a
+      supplier that ranges 5–12 days), ordering cost and holding cost, produce a reorder-policy table
+      and a replenishment trigger list.
+    must_include:
+      - ABC×XYZ classification drives differentiated service levels, not one uniform Z across all SKUs
+      - safety-stock formula chosen by what actually varies — the combined/independent formula where lead time swings, not demand-only
+      - ROP = avg-demand-over-lead-time + safety_stock and order_qty derived from EOQ kept as separate columns
+      - review_mode assigned per class (continuous for A, periodic for B/C, ddmrp for erratic high-value)
+      - identifies which SKUs are at or below ROP for the trigger list, with no false triggers
+      - flags dead stock (SKUs with no movement over a defined window) rather than reordering them
+      - routes "now place the order with the supplier" to procurement

package/skills/inventory/references/abc-xyz.md

@@ -0,0 +1,52 @@
+# ABC × XYZ classification
+
+Classification is how you decide where to spend control. Do this before sizing buffers.
+
+## ABC: split by consumption value (Pareto)
+
+1. For each SKU compute **annual consumption value** = `annual_demand × unit_cost`.
+2. Sort SKUs descending by that value.
+3. Cumulate and take the running share of total value.
+4. Cut into bands — A ≈ top ~80% of cumulative value, B the next ~15%, C the bottom ~5%. (Bands are tunable; the point is value, not count.)
+
+Worked sort (illustrative):
+
+```text
+sku    annual_demand  unit_cost  value     cum_value  cum_%   class
+S-101  1,200          90.00      108,000   108,000    46.0%   A
+S-204    900          60.00       54,000   162,000    69.0%   A
+S-307  2,000          15.00       30,000   192,000    81.7%   A
+S-410    400          20.00        8,000   200,000    85.1%   B
+S-512  1,500           4.00        6,000   206,000    87.7%   B
+...     (long tail)                                             C
+```
+
+A is usually ~20% of SKUs holding ~80% of value — those get the tight control.
+
+## XYZ: split by demand variability
+
+Compute the **coefficient of variation** of period demand: `CV = σ_demand / mean_demand`. Use enough history (≥12 periods) so a single spike doesn't dominate.
+
+| Class | CV range (typical) | Demand shape |
+|---|---|---|
+| X | CV < 0.5 | stable, predictable |
+| Y | 0.5 ≤ CV ≤ 1.0 | fluctuating / seasonal |
+| Z | CV > 1.0 | erratic, intermittent |
+
+Cut points are conventions — adjust to your data, but keep them fixed across the catalog so classes are comparable.
+
+## The 9-cell matrix → policy
+
+| Cell | Value × variability | Review mode | Service level | Buffer posture |
+|---|---|---|---|---|
+| AX | high value, stable | continuous (min-max) | 98–99% | tight, automated, lean |
+| AY | high value, fluctuating | continuous | 97–98% | moderate, watch closely |
+| AZ | high value, erratic | ddmrp | 95–98% | buffer zones, candidate for DDMRP |
+| BX | mid value, stable | continuous or periodic | 95% | standard |
+| BY | mid value, fluctuating | periodic | 93–95% | moderate |
+| BZ | mid value, erratic | periodic / ddmrp | 90–95% | cautious, review often |
+| CX | low value, stable | periodic | 90–95% | generous buffer is cheap |
+| CY | low value, fluctuating | periodic | 90% | low buffer |
+| CZ | low value, erratic | periodic / make-to-order | 85–90% | near-zero buffer or MTO |
+
+Read it as a control budget: spend tight automated control and high service on the top-left (AX), spend almost nothing on the bottom-right (CZ). The high-value erratic corner (AZ) is where a static reorder point fails and DDMRP earns its keep — see `ddmrp.md`.

package/skills/inventory/references/ddmrp.md

@@ -0,0 +1,32 @@
+# DDMRP: demand-driven buffers
+
+When a static reorder point keeps whipsawing on erratic demand — you re-tune safety stock every cycle and it is still wrong — replace the fixed point with three buffer zones that recalculate off actual demand.
+
+## The three zones
+
+| Zone | Covers | Sized off |
+|---|---|---|
+| **Red** | safety / critical protection | lead-time variability + demand variability (the un-skippable floor) |
+| **Yellow** | demand coverage over the lead time | average daily usage × decoupled lead time |
+| **Green** | the order cycle / order frequency | the larger of: minimum order qty, an order-cycle target, or lead-time × usage |
+
+Top of green = red + yellow + green; that is your "order up to" level. The zones move as average daily usage and lead time change, so you are not hand-editing a number every month.
+
+## The trigger: net flow position
+
+```text
+net_flow_position = on_hand + on_order − qualified_demand
+```
+
+`qualified_demand` = confirmed/near-term demand (open orders, spikes within the spike horizon). The reorder signal fires when net flow position drops out of green **into the yellow zone** — order enough to bring it back to the top of green.
+
+This differs from a fixed ROP: it nets in on-order and known demand spikes instead of reacting only to on-hand crossing one static line, so it doesn't double-order while a PO is in transit and doesn't ignore a known incoming spike.
+
+## When DDMRP beats a static ROP
+
+Use it only for SKUs that are some combination of:
+- **erratic demand** (Z-class, CV > 1) where a stable σ_demand assumption breaks,
+- **long lead time** where a misjudged buffer is expensive to unwind,
+- **strategic / high value** (the AZ corner) where stockouts genuinely hurt.
+
+Do **not** use it for steady C items — a flat reorder point is cheaper to run and good enough. Set `review_mode = ddmrp` in the policy table for the SKUs you move onto buffer zones; the red zone plays the role of `safety_stock` and the green-trigger level plays the role of `reorder_point` for the verify.sh invariants.

package/skills/inventory/references/reorder-policies.md

@@ -0,0 +1,85 @@
+# Reorder point, EOQ, and review mode
+
+Two separate levers, then the schemas your artifacts must match.
+
+## Reorder point (when)
+
+```text
+ROP = (avg daily demand × lead-time days) + safety_stock
+```
+
+Worked: avg 40/day, LT 9 days, SS 207 (from `safety-stock.md` formula 2):
+
+```text
+ROP = 40·9 + 207 = 360 + 207 = 567 units
+```
+
+When on-hand drops to 567 you trigger. The 360 covers expected demand during the wait; the 207 covers the variability.
+
+## EOQ (how much)
+
+```text
+EOQ = √(2 · D · S / H)
+   D = annual demand, S = ordering cost per PO, H = annual holding cost per unit
+```
+
+Worked: D = 14,600/yr, S = €45/order, H = €3/unit/yr:
+
+```text
+EOQ = √(2 · 14,600 · 45 / 3) = √(1,314,000 / 3) = √438,000 ≈ 662 units/order
+```
+
+EOQ is the cost-minimizing order *size*. It is not a trigger and not a max — round it to supplier pack/MOQ, but never wait for on-hand to fall to EOQ before ordering.
+
+## Continuous vs periodic review
+
+| | Continuous (min-max, s,S) | Periodic |
+|---|---|---|
+| Trigger | on-hand hits ROP `s` | fixed cadence (e.g. weekly) |
+| Order to | up to max `S` | up to target level |
+| Needs | perpetual stock visibility | only a clock |
+| Reaction | fastest | delayed up to one interval |
+| Buffer | lead-time exposure only | lead-time **+ review-interval** exposure |
+| Best for | A items, live system | B/C items, batched POs |
+
+**Review-interval buffer adjustment.** Periodic review is blind between checks, so it must cover demand over `lead_time + review_interval`. Add to safety stock:
+
+```text
+SS_periodic = Z · σ_demand · √(LT + review_interval)
+```
+
+A weekly review with a 9-day lead time buffers √16 instead of √9 — about a third more buffer. That extra cash is the price of batching POs; charge it knowingly.
+
+## Policy-table schema (what verify.sh checks)
+
+CSV, one row per SKU. Required columns, exact names:
+
+```text
+sku,abc_class,avg_demand,lead_time,safety_stock,reorder_point,order_qty,review_mode
+S-101,A,40,9,207,567,662,continuous
+S-512,C,12,7,18,102,300,periodic
+S-733,A,30,21,140,770,500,ddmrp
+```
+
+Invariants verify.sh enforces:
+- every column present; no duplicate `sku`.
+- `abc_class` non-empty; `review_mode` ∈ {continuous, periodic, ddmrp}.
+- `reorder_point >= safety_stock` (ROP sits at or above the buffer).
+- `order_qty > 0`.
+
+## Trigger-list schema
+
+CSV. Only SKUs at or below ROP belong here.
+
+```text
+sku,on_hand,reorder_point,suggested_order_qty
+S-101,540,567,662
+S-512,90,102,300
+```
+
+Invariants:
+- every `sku` exists in the policy table.
+- `on_hand <= reorder_point` (no false triggers — a SKU above ROP must not appear).
+- `suggested_order_qty > 0`.
+
+Hand this list to `procurement` to raise the actual POs.

package/skills/inventory/references/safety-stock.md

@@ -0,0 +1,63 @@
+# Safety stock
+
+Safety stock is the buffer that covers variability *during* the lead time. Get two things right: the **formula** (matched to what varies) and **Z** (set by service level).
+
+## Pick the formula by what varies
+
+```text
+1. Demand varies, lead time stable:
+   SS = Z · σ_demand · √LT
+
+2. Demand and lead time both vary, independent:
+   SS = Z · √(LT · σ_demand²  +  avg_demand² · σ_LT²)
+
+3. Demand and lead time both vary, correlated (King's method):
+   SS = Z · σ_demand · √LT  +  Z · avg_demand · σ_LT
+```
+
+- `σ_demand` is the standard deviation of demand per period (same period unit as LT).
+- `σ_LT` is the standard deviation of lead time, in the same unit.
+- `avg_demand` is mean demand per period; `LT` is mean lead time in periods.
+
+The most common under-buffering mistake is using formula 1 when the supplier's lead time actually swings. If receipts arrive in 5, 6, 12, 5, 9 days, `σ_LT` is large and must be in the buffer — use formula 2 (or 3 if demand spikes when lead time stretches).
+
+## Z by service level
+
+| Service level | Z |
+|---|---|
+| 90% | 1.28 |
+| 95% | 1.65 |
+| 97.5% | 1.96 |
+| 99% | 2.33 |
+
+Service level here = probability of **not** stocking out during a replenishment cycle. Set it per ABC×XYZ cell (see `abc-xyz.md`), then read Z. Never invent a Z.
+
+## Worked examples
+
+**Demand-only (formula 1).** avg daily demand 40, σ_demand 12, LT 9 days, target 95% (Z=1.65):
+
+```text
+SS = 1.65 · 12 · √9 = 1.65 · 12 · 3 = 59.4 ≈ 60 units
+```
+
+**Both vary, independent (formula 2).** avg_demand 40/day, σ_demand 12, LT 9 days, σ_LT 3 days, Z=1.65:
+
+```text
+SS = 1.65 · √(9·12²  +  40²·3²)
+   = 1.65 · √(1,296  +  14,400)
+   = 1.65 · √15,696
+   = 1.65 · 125.3 ≈ 207 units
+```
+
+Note the jump from 60 → 207: the lead-time variance dominates here. Ignoring `σ_LT` would have left you ~150 units short of the buffer you actually need.
+
+## Estimating σ_demand and σ_LT from history
+
+- **σ_demand:** take demand per period (day or week, matching LT units) over ≥12 periods, compute the sample standard deviation. Strip known one-offs (a promo, a B2B bulk order) or model them separately — they inflate σ and over-buffer.
+- **σ_LT:** take the actual receipt date minus PO date for the last ~10–20 receipts of that supplier/SKU, compute mean and standard deviation in the same time unit as σ_demand.
+
+If you only have a forecast and its error, use forecast error as σ_demand — but that demand model belongs to `forecasting`; you only consume it.
+
+## Diminishing returns past ~98%
+
+The normal tail is fat: moving 95% → 99% raises Z from 1.65 to 2.33 (+41% buffer) for 4 points of service. Going 99% → 99.9% costs far more again. Reserve the top of the curve for A/critical SKUs where a stockout is genuinely expensive; let C items sit at 90% and free the cash.