@damiangilgonzalez/harness 1.3.7

package/skills/replicate-images/references/models.md

@@ -0,0 +1,131 @@
+# Image model reference (Replicate)
+
+Verified 2026-06-02. **Slugs and parameter names drift.** Treat this table as a starting point and
+confirm the exact input schema and allowed values on the model page (`replicate.com/<owner>/<model>`)
+before relying on a parameter. Pricing figures are order-of-magnitude upstream rates; Replicate may
+mark up — re-check the model page before quoting a number.
+
+---
+
+## google/nano-banana-2 — Gemini 3.1 Flash Image
+
+Google's fast image generation + editing model (announced 2026-02-26): Pro-level quality at Flash
+speed and price. Best default for editing and multi-image composition.
+
+Identity corroboration (two independent sources, since the slug and "Gemini 3.1 Flash Image" tie are
+load-bearing for the whole skill): the live Replicate model page `replicate.com/google/nano-banana-2`
+(fetched 2026-06-02) states verbatim "Nano Banana 2 is Google's latest image generation model, built
+on Gemini 3.1 Flash Image" — confirming both the slug and the underlying model. This matches the
+2026-02-26 google blog announcement and the Google Cloud model docs
+(`docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/3-1-flash-image`). If the model
+page no longer resolves or names a different base model, treat the slug below as drifted and re-verify.
+
+Inputs:
+- `prompt` — string, prose (see prompt shape).
+- `image_input` — array of up to **14** reference images for editing/composition. Each entry is a
+  file/Buffer (auto-uploaded), an `https://` URL string, or a `data:` URI string.
+- `aspect_ratio` — one of: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`,
+  `match_input_image`. (The model page's prose mentions extreme `1:4`/`4:1`/`1:8`/`8:1` ratios as
+  "new", but the formal aspect-ratio spec lists only the set above — treat the extremes as unconfirmed
+  and verify on the model page before using one.)
+- `output_format` — `jpg` (default) or `png`.
+- `output_resolution` — `512px`, `1K` (default), `2K`, `4K`.
+
+Prompt shape: prose, `[Subject] + [Action] + [Location/context] + [Composition] + [Style]`. Edits are
+conversational ("Remove X. Keep everything else identical."). Text: literal string in quotes + named
+font; can translate text.
+
+Cost (relative tiers, not exact dollars): per-image price climbs with resolution — `512px` cheapest
+→ `1K` (default) → `2K` → `4K` dearest, with the high tiers costing several times the low tier.
+Resolution dominates cost. As of the 2026-06-02 fetch the model page `replicate.com/google/nano-banana-2`
+shows **no fixed per-image dollar block** — this skill deliberately states tiers, not dollars, because
+the only exact figures circulating are on non-authoritative aggregators. Read the live "Pricing" block
+on the model page (authoritative) before quoting any number; do not lift a dollar figure from a blog.
+
+Pick when: editing an existing image, merging multiple references, or rendering text in a layout.
+
+---
+
+## google/nano-banana-pro — Gemini 3 Pro Image
+
+Higher-quality sibling of NB2 for hard compositions and maximum fidelity.
+
+Inputs: same shape as nano-banana-2 (`prompt`, `image_input`, `aspect_ratio`, `output_format`,
+`output_resolution`) — confirm exact set on the model page.
+
+Cost: roughly **2x** NB2 at the same resolution (relative tier only, not an exact dollar figure —
+confirm on the model page's live pricing block; do not quote a per-image dollar amount from a blog).
+
+Pick when: NB2 genuinely can't nail the composition/quality and the budget allows. Not the default.
+
+---
+
+## black-forest-labs/flux-1.1-pro
+
+Flux flagship with strong control over style, lighting, and composition.
+
+Inputs (confirm on model page):
+- `prompt` — dense single-paragraph description.
+- `aspect_ratio` and/or `width` / `height`.
+- `seed` — integer for reproducibility.
+- `output_format` — `jpg` / `png` / `webp` depending on the model.
+
+Prompt shape: one rich paragraph weighting subject + lighting + lens. Thin prompts get auto-filled.
+
+Pick when: dense photoreal with fine control of light/lens; A/B prompt iteration via fixed `seed`.
+
+---
+
+## black-forest-labs/flux-dev
+
+Open-weight Flux for general text-to-image; supports `seed`, `aspect_ratio`/`width`/`height`,
+`output_format`, and `num_outputs` where applicable. Streaming-capable in the JS client.
+
+Pick when: a balance of quality and cost without the Pro premium.
+
+---
+
+## black-forest-labs/flux-schnell
+
+Fastest, cheapest Flux; listed as sync-optimized in the JS client README.
+
+Pick when: rapid draft loops and previews. Render finals on a higher-quality model.
+
+---
+
+## openai/gpt-image-1 (OpenAI on Replicate)
+
+OpenAI's image model exposed on Replicate. Follows complex instructions and renders readable text
+well; usable as an editor. **Requires an OpenAI key wired into the Replicate model.**
+
+Prompt shape: instructional brief with explicit constraints (layout, stroke, spacing, labels).
+
+Pick when: strict instruction-following or crisp readable text matters more than photoreal style.
+
+---
+
+## bytedance/seedream-4 — Seedream 4.0
+
+Unified text-to-image + editing; up to 4K; multi-reference and batch/sequential generation. (Seedream
+4.5 exists upstream — check the model page for the current Replicate version.)
+
+Inputs (confirm exact names on the model page): `prompt`, `size` (resolution), `image_input`
+(references), `max_images` / `sequential_image_generation` for batches, `seed`.
+
+Prompt shape: state the references and their relationship; ask for the batch count explicitly.
+
+Pick when: you need up-to-4K output or a coherent batch/sequence from references.
+
+---
+
+## Slug allowlist (used by scripts/verify.sh)
+
+```text
+google/nano-banana-2
+google/nano-banana-pro
+black-forest-labs/flux-1.1-pro
+black-forest-labs/flux-dev
+black-forest-labs/flux-schnell
+openai/gpt-image-1
+bytedance/seedream-4
+```

package/skills/replicate-images/scripts/verify.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static lint for Replicate image-generation code (read-only, network-free).
+#
+# WHAT IT DOES (never edits, runs code, or calls the API)
+#   Points at a directory of emitted code (default: current dir) and statically
+#   checks the things that are mechanically wrong about a Replicate image call:
+#     1. Image model slugs -> every replicate.run("<slug>") / predictions.create
+#        model:/version: "<slug>" must be in the known image-slug allowlist
+#        (the slugs in references/models.md). An unknown slug is a HARD failure
+#        (likely a typo or a hallucinated model).
+#     2. aspect_ratio literals -> every aspect_ratio: "<v>" must be in the
+#        nano-banana allowed set (or match_input_image). HARD failure otherwise.
+#     3. output_resolution literals -> must be one of 512px,1K,2K,4K. HARD fail.
+#     4. Bare-path image inputs -> an image_input array element that is a quoted
+#        relative path ("./x.png" / "x.jpg") rather than a variable/URL/data:
+#        URI warns (clients upload files/Buffers, not path strings).
+#
+#   A dir with no matching code (nothing to check) exits 0 — never a false fail.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                 # check current directory, recursively
+#   ./verify.sh path/to/dir     # check a specific dir
+#   ./verify.sh dir --strict    # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, warnings-only (without --strict), or nothing to check
+#   1  a hard failure (unknown slug / bad aspect_ratio / bad resolution),
+#      or any warning under --strict
+#   2  bad usage (target dir does not exist)
+#
+# Runs on stock macOS bash 3.2.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; }
+
+DIR="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --strict) STRICT=1; shift ;;
+    -*) printf '%sunknown option: %s%s\n' "$RED" "$1" "$NC" >&2; usage; exit 2 ;;
+    *) DIR="$1"; shift ;;
+  esac
+done
+
+if [ ! -d "$DIR" ]; then
+  printf '%starget dir not found: %s%s\n' "$RED" "$DIR" "$NC" >&2; exit 2
+fi
+
+printf 'replicate-images verify — %s\n\n' "$DIR"
+
+# Known image slugs (from references/models.md). Space-padded for whole-token match.
+ALLOWED_SLUGS=" google/nano-banana-2 google/nano-banana-pro black-forest-labs/flux-1.1-pro black-forest-labs/flux-dev black-forest-labs/flux-schnell openai/gpt-image-1 bytedance/seedream-4 "
+# nano-banana aspect_ratio allowed set + match_input_image (the spec list on the model page;
+# extreme 1:4/4:1/1:8/8:1 are unconfirmed in that spec, so they are intentionally NOT allowed here).
+ALLOWED_AR=" 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 match_input_image "
+# output_resolution allowed set.
+ALLOWED_RES=" 512px 1K 2K 4K "
+
+# Collect candidate source files (skip references/models.md itself: it lists the allowlist as prose).
+SRC="$(find "$DIR" \( -name '*.js' -o -name '*.mjs' -o -name '*.ts' -o -name '*.py' \) 2>/dev/null || true)"
+
+checked_anything=0
+
+# --- 1. model slugs -----------------------------------------------------------
+SLUGS="$(printf '%s\n' "$SRC" | while IFS= read -r f; do
+  [ -n "$f" ] && [ -f "$f" ] || continue
+  grep -hoE '(replicate\.run|model|version)[^"'"'"']*["'"'"'][a-z0-9._-]+/[a-z0-9._-]+["'"'"']' "$f" 2>/dev/null \
+    | grep -oE '["'"'"'][a-z0-9._-]+/[a-z0-9._-]+["'"'"']' \
+    | tr -d '"'"'"''
+done | sort -u || true)"
+
+if [ -n "$SLUGS" ]; then
+  checked_anything=1
+  while IFS= read -r s; do
+    [ -n "$s" ] || continue
+    case "$ALLOWED_SLUGS" in
+      *" $s "*) ok "model slug ok: $s" ;;
+      *) fail "unknown image model slug: '$s' (not in references/models.md allowlist)" ;;
+    esac
+  done <<EOF
+$SLUGS
+EOF
+fi
+
+# --- 2. aspect_ratio literals -------------------------------------------------
+ARS="$(printf '%s\n' "$SRC" | while IFS= read -r f; do
+  [ -n "$f" ] && [ -f "$f" ] || continue
+  grep -hoE 'aspect_ratio["'"'"']?[[:space:]]*[:=][[:space:]]*["'"'"'][^"'"'"']+["'"'"']' "$f" 2>/dev/null \
+    | grep -oE '["'"'"'][^"'"'"']+["'"'"']$' | tr -d '"'"'"''
+done | sort -u || true)"
+
+if [ -n "$ARS" ]; then
+  checked_anything=1
+  while IFS= read -r a; do
+    [ -n "$a" ] || continue
+    case "$ALLOWED_AR" in
+      *" $a "*) ok "aspect_ratio ok: $a" ;;
+      *) fail "aspect_ratio '$a' not in the nano-banana allowed set" ;;
+    esac
+  done <<EOF
+$ARS
+EOF
+fi
+
+# --- 3. output_resolution literals --------------------------------------------
+RESS="$(printf '%s\n' "$SRC" | while IFS= read -r f; do
+  [ -n "$f" ] && [ -f "$f" ] || continue
+  grep -hoE 'output_resolution["'"'"']?[[:space:]]*[:=][[:space:]]*["'"'"'][^"'"'"']+["'"'"']' "$f" 2>/dev/null \
+    | grep -oE '["'"'"'][^"'"'"']+["'"'"']$' | tr -d '"'"'"''
+done | sort -u || true)"
+
+if [ -n "$RESS" ]; then
+  checked_anything=1
+  while IFS= read -r r; do
+    [ -n "$r" ] || continue
+    case "$ALLOWED_RES" in
+      *" $r "*) ok "output_resolution ok: $r" ;;
+      *) fail "output_resolution '$r' not in {512px,1K,2K,4K}" ;;
+    esac
+  done <<EOF
+$RESS
+EOF
+fi
+
+# --- 4. bare-path image_input warning -----------------------------------------
+BAREPATH="$(printf '%s\n' "$SRC" | while IFS= read -r f; do
+  [ -n "$f" ] && [ -f "$f" ] || continue
+  # image_input on the same line containing a quoted relative path with an image extension
+  grep -nE 'image_input' "$f" 2>/dev/null \
+    | grep -E '["'"'"'](\./|\.\./)?[A-Za-z0-9._/-]+\.(png|jpg|jpeg|webp|gif)["'"'"']' \
+    | grep -vE 'https?://|data:' \
+    | sed "s|^|$f:|"
+done || true)"
+
+if [ -n "$BAREPATH" ]; then
+  checked_anything=1
+  while IFS= read -r line; do
+    [ -n "$line" ] && warn "possible bare-path image input: ${line} — read the file (readFile/Buffer) or pass a URL/data: URI"
+  done <<EOF
+$BAREPATH
+EOF
+fi
+
+# --- summary ------------------------------------------------------------------
+printf '\n'
+if [ "$checked_anything" -eq 0 ] && [ "$fail_count" -eq 0 ]; then
+  ok "nothing to check in $DIR"
+  exit 0
+fi
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d hard failure(s), %d warning(s)%s\n' "$RED" "$fail_count" "$warn_count" "$NC"
+  exit 1
+fi
+if [ "$warn_count" -gt 0 ]; then
+  if [ "$STRICT" -eq 1 ]; then
+    printf '%s%d warning(s) — failing under --strict%s\n' "$YELLOW" "$warn_count" "$NC"
+    exit 1
+  fi
+  printf '%s%d warning(s), 0 hard failures%s\n' "$YELLOW" "$warn_count" "$NC"
+  exit 0
+fi
+printf '%sall checks passed%s\n' "$GREEN" "$NC"
+exit 0

package/skills/reporting/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: reporting
+description: "Use when a recurring report must ship itself on a cadence — weekly digest, monthly exec pack, board pack — via a fetch→narrate→render→deliver pipeline with a schedule and a freshness gate. NOT a live view people slice (that is `dashboard`), NOT picking which KPIs to track (that is `kpi-framework`), NOT a one-off investigation (that is `analytics`)."
+tags: [reporting, automated-reports, recurring, stakeholder-reporting, scheduled-delivery, data-analytics]
+recommends: [dashboard, kpi-framework, analytics, automation-flows, email-connector, spreadsheet-ops, google-workspace, notion-connector, github-actions]
+origin: risco
+---
+
+# reporting — the standing artifact that ships itself
+
+A report is a **push** artifact: a fixed snapshot that lands in someone's inbox or shared drive on a
+cadence, the same shape every period, with no human assembling it. That is the whole job. If a human
+opens a live view to slice numbers themselves, that is **pull** — a
+[`dashboard`](../dashboard/SKILL.md), not a report. Hold that line; almost every failed "reporting"
+project is a dashboard wearing a report's name, or a report nobody can trust because the numbers went
+stale and no one noticed.
+
+Your deliverable is a **runnable pipeline**, not advice: a template, a generation script, a schedule,
+and a delivery step, with a freshness gate so it fails loud instead of shipping yesterday's numbers.
+
+## Step 0 — Write the report contract (no contract, no build)
+
+Before any code, pin six fields. An undefined audience is a report no one reads; an undefined source
+is a number no one can defend.
+
+| Field | What it fixes | Example |
+| --- | --- | --- |
+| **Audience** | Who reads it → sets depth and tone | "5-person leadership team" |
+| **Cadence** | When it ships → sets the scheduler | "every Monday 08:00 Europe/Madrid" |
+| **Sections** | The fixed skeleton, same every period | Exec summary · revenue · pipeline · risks |
+| **Metric source** | Where numbers come from + **who owns them** | `metrics.csv` from the data team |
+| **Channel** | The artifact + transport | PDF over email |
+| **Owner** | Who gets paged when it breaks | a named person, not "the team" |
+
+Rule: you **consume** an agreed metric set — you do not adjudicate which KPIs matter. If the ask is
+"which metrics should we even track?", that is [`kpi-framework`](../kpi-framework/SKILL.md), not this
+skill. The contract names the source and its owner so a wrong number has an address.
+
+## Decide: push report vs live dashboard (this branches — settle it first)
+
+Audiences want a citable snapshot for the period more often than a live feed — that is why push wins
+for exec summaries, weekly reviews, and finance close packs.
+
+| Signal in the ask | Route |
+| --- | --- |
+| "Same summary, every week/month/quarter" | **reporting** (here) |
+| "Consistent snapshot the board can cite in a meeting" | **reporting** (here) |
+| "It must arrive even if no one logs in" | **reporting** (here) |
+| "A screen people open to filter/drill live" | [`dashboard`](../dashboard/SKILL.md) |
+| "Self-serve, slice by region/date on demand" | [`dashboard`](../dashboard/SKILL.md) |
+
+When both are wanted, build the report and let it link to the dashboard as a "go deeper" footer.
+
+## Pick the artifact format
+
+| Format | Wins when | Notes |
+| --- | --- | --- |
+| **Email-body HTML** | Short digest, ≤1 screen, read on a phone | Inline the key numbers; no attachment to open |
+| **PDF** | Exec / client / board, fixed layout that must look identical for everyone | The default for anything formal; pinned render stack below |
+| **Spreadsheet** | Analysts who will re-filter and pivot the data themselves | Hand off the data, not a picture → [`spreadsheet-ops`](../spreadsheet-ops/SKILL.md) |
+| **Notion / living doc** | Internal team, the doc evolves and gets commented | Page over file → [`notion-connector`](../notion-connector/SKILL.md) |
+
+A board pack is a PDF; an analyst hand-off is a spreadsheet. Picking PDF for analysts who wanted to
+pivot is the most common format miss.
+
+## The four-layer pipeline: fetch → narrate → render → deliver
+
+Keep the four layers separate so each is testable and the template never knows where data came from.
+
+**Pinned stack** (Python, the most-documented 2025 PDF path — verified on PyPI 2026-06-02):
+`pandas` (data) → `Jinja2` (HTML template) → `WeasyPrint` **68.1** (HTML+CSS → PDF), `Matplotlib`
+for embedded charts. Pin WeasyPrint — major versions change CSS support, so an unpinned bump can
+silently reflow a board pack. Re-check PyPI before you freeze, then freeze what you resolve.
+
+```python
+# render.py — minimal fetch → narrate → render. Delivery + charts live in references/pipeline.md.
+import pandas as pd
+from jinja2 import Environment, FileSystemLoader
+from weasyprint import HTML  # WeasyPrint==68.1
+
+def build_report(metrics_csv: str, params: dict) -> bytes:
+    df = pd.read_csv(metrics_csv)                      # fetch
+    df = df[df["region"] == params["region"]]          # per-recipient scope, NOT a new template
+    cur, prev = df["revenue"].iloc[-1], df["revenue"].iloc[-2]
+    ctx = {
+        "title": f'{params["region"]} weekly revenue',
+        "period": params["period"],
+        "summary": narrate(cur, prev),                 # narrate (see below)
+        "rows": df.tail(8).to_dict("records"),
+    }
+    env = Environment(loader=FileSystemLoader("templates"))
+    html = env.get_template("report.html.j2").render(**ctx)   # render
+    return HTML(string=html).write_pdf()
+```
+
+Rule: **one template, per-recipient params** — regional managers each get their region from the same
+`report.html.j2`, scoped by `params`, never a forked template per recipient. A template-per-recipient
+codebase rots the first time the layout changes. The full worked template, the Matplotlib base64 chart
+embed, the per-recipient loop, the GitHub Actions workflow, and the freshness gate are in
+[`references/pipeline.md`](references/pipeline.md).
+
+## The narrative layer (the part that gets read)
+
+Executives read the **executive summary and stop**. Lead every report with: the report's purpose in
+one line, **3 key takeaways**, and **what changed versus last period**. Then per section, one
+period-over-period delta sentence and one "so what". An annotated chart callout is retained; a bare
+chart is not.
+
+```python
+def narrate(cur: float, prev: float) -> str:
+    delta = (cur - prev) / prev * 100
+    arrow = "up" if delta >= 0 else "down"
+    flag = " — investigate" if abs(delta) >= 20 else ""    # anomaly callout
+    return (f"Revenue {arrow} {abs(delta):.1f}% vs last week "
+            f"(€{cur:,.0f} from €{prev:,.0f}){flag}.")
+```
+
+Bad → Good, the difference that decides whether the report is useful:
+
+- **Bad:** a table row `Revenue | 248,300 | 201,400`. The reader must do the math and guess if it matters.
+- **Good:** "Revenue up 23.3% WoW (€248,300 from €201,400) — investigate: driven by the enterprise renewal that won't recur next week."
+
+The numbers are the evidence; the sentence is the report.
+
+## Schedule + reliability gate (where reports actually die)
+
+Reports die two ways: **stale data** ships silently, and **a silent break** means no one notices for
+weeks. Treat the schedule as managed infrastructure.
+
+**Where to run it:**
+
+| Situation | Scheduler |
+| --- | --- |
+| You already run a server / cron host | **cron** (`0 8 * * 1` = Mondays 08:00) |
+| No server, want zero infra | **GitHub Actions** `on: schedule: - cron:` — the recommended cloud option |
+| Multi-app event wiring beyond a timer | route the plumbing to [`automation-flows`](../automation-flows/SKILL.md) |
+
+This skill owns the report-shaped concern (contract, narrative, artifact) and *uses* a scheduler — it
+does not teach scheduling in general. The actual transport (SMTP/Gmail send) belongs to
+[`email-connector`](../email-connector/SKILL.md); for a Drive/Workspace destination see
+[`google-workspace`](../google-workspace/SKILL.md). The GH Actions `schedule:` YAML is in
+[`references/pipeline.md`](references/pipeline.md).
+
+**Reliability checklist — every recurring report:**
+
+- [ ] **Freshness gate before send** — assert the source is newer than the last period; if stale, do
+      NOT send, raise instead. A report that consumes dirty data is not this skill's job to clean —
+      that is [`data-cleaning`](../data-cleaning/SKILL.md); this gate only refuses to ship
+      known-stale numbers.
+- [ ] **Fail loud** — on any error, alert the owner (the report not arriving is itself a silent failure).
+- [ ] **Idempotent run** — re-running for the same period produces the same artifact, no duplicate send.
+- [ ] **Dead-report cleanup** — if no one opened the last N editions, kill the schedule. Unread reports
+      are pure cost and noise.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Email a live dashboard link, call it "the report" | Recipient must log in and slice; most won't, the snapshot is lost | Ship the fixed artifact; link the dashboard as a footer |
+| No freshness gate | Stale numbers ship silently; trust dies on the first wrong figure | Assert source newer than last period; refuse to send if stale |
+| One mega-report for every audience | Execs drown in analyst detail; analysts can't refilter a PDF | Contract per audience; one template, per-recipient params |
+| Raw metric dump, no narrative | Reader does the math, misses what changed, stops opening it | Exec summary + 3 takeaways + a "so what" per section |
+| Schedule with no failure alert | A broken job is invisible for weeks; the report just stops | Fail loud to the named owner on any error |
+| A template forked per recipient | Layout change must be made N times; they drift | Single template scoped by `params` |
+| Redefining KPIs inside the report | The report quietly becomes the metric authority, numbers diverge | Consume an agreed set; defer definition to [`kpi-framework`](../kpi-framework/SKILL.md) |
+| Unpinned WeasyPrint / render lib | A minor bump reflows the board pack with no warning | Pin (WeasyPrint 68.1) and re-check PyPI before changing |
+| Hand-assembling the digest weekly | It breaks the week the owner is on leave | Automate the pipeline end to end; a human only reads it |
+
+## Verify
+
+Run `scripts/verify.sh` (read-only; pass a path to a generated pipeline directory, or run in it). It
+confirms a Jinja2 template renders against a sample context without error, the generation script
+produces a non-empty PDF/HTML artifact, a schedule definition exists (a crontab line or a
+`.github/workflows/*.yml` with a `schedule:` block), and a delivery step is wired. It soft-warns if no
+freshness/failure gate is detected, and exits 0 on an empty/clean target — nothing to check is not a
+failure.

package/skills/reporting/evals/README.md

@@ -0,0 +1,12 @@
+# reporting — evals
+
+These cases are run by the skill-eval harness, not by a bundled scorer here. `should_trigger` and
+`should_not_trigger` check routing: each `should_trigger` prompt should select this skill (read the
+`why` to see what makes it reporting, including the non-obvious "stale Monday email" case and the
+Spanish/Catalan phrasings), and each `should_not_trigger` prompt should route to the named real
+sibling (`route_to`) instead of being absorbed here — the boundaries against dashboard, kpi-framework,
+analytics, forecasting, data-cleaning, and automation-flows are the whole point. The single
+`capability` case is rubric-scored by a judge: a passing answer must hit every item in `must_include`
+(report contract, template/params separation, pinned render stack, narrative layer, schedule,
+freshness + failure gate, and correct routing of out-of-scope asks). There is no automated pass/fail
+script — read each `why`/`route_to` and the rubric to grade by hand or feed them to the harness.

package/skills/reporting/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: reporting
+
+should_trigger:
+  - prompt: "Set up a weekly automated performance report emailed to our exec team."
+    why: "Core push report — recurring cadence, fixed audience, delivered without a human. The center of this skill."
+  - prompt: "Build a monthly PDF report for our biggest client, on a schedule."
+    why: "Recurring client-facing report + artifact format (PDF) + cadence — fetch→narrate→render→deliver pipeline."
+  - prompt: "Send the board a quarterly summary PDF every quarter, automatically."
+    why: "Cadence + formal artifact + push delivery; the quarterly board pack is a canonical reporting case."
+  - prompt: "Automatiza un informe mensual para dirección."
+    why: "Spanish for 'automate a monthly report for leadership' — recurring stakeholder report, must route here."
+  - prompt: "Munta un informe setmanal automàtic per al comitè."
+    why: "Catalan for 'build an automatic weekly report for the committee' — recurring push report."
+  - prompt: "Our Monday metrics email keeps going out with last week's numbers — make it reliable."
+    why: "Non-obvious: framed as a bug, but it is report-pipeline reliability (freshness gate, fail-loud) — squarely reporting, not a generic email fix."
+
+should_not_trigger:
+  - prompt: "Build an interactive dashboard the team can open to slice sales by region."
+    route_to: dashboard
+    why: "Pull/live surface the user opens and filters — not a push artifact on a cadence."
+  - prompt: "Which KPIs should we even be tracking for the growth team?"
+    route_to: kpi-framework
+    why: "Deciding which metrics matter / defining the metric tree — reporting consumes an agreed set, it does not adjudicate it."
+  - prompt: "Dig into why signups dropped last Tuesday."
+    route_to: analytics
+    why: "One-off investigation to answer a question, not a recurring standing artifact."
+  - prompt: "Forecast next quarter's revenue from this history."
+    route_to: forecasting
+    why: "Predicting future values / projections — reporting reports what happened, it does not predict."
+  - prompt: "Our source CSV has duplicate and malformed rows — clean it."
+    route_to: data-cleaning
+    why: "Fixing dirty source data — reporting assumes a trustworthy source and only gates on freshness, it does not clean."
+  - prompt: "Just wire up a generic cron job that runs this script nightly."
+    route_to: automation-flows
+    why: "Generic scheduling/plumbing for any job with no report shape — reporting uses a scheduler but does not teach scheduling-in-general."
+
+capability:
+  - scenario: "Set up a recurring weekly revenue report, delivered as a PDF emailed to the leadership team every Monday at 08:00, sourced from a metrics CSV."
+    must_include:
+      - "Defines a report contract: audience, cadence, sections, metric source (and who owns the numbers), channel, owner."
+      - "Separates the template from per-recipient params (one Jinja2 template scoped by params, not a forked template per recipient)."
+      - "Uses a pinned render stack (pandas → Jinja2 → WeasyPrint 68.1, Matplotlib for charts) and states the pin."
+      - "Writes a narrative/executive-summary layer (purpose + 3 takeaways + what changed vs last period), not just a raw metric table."
+      - "Schedules it via cron or GitHub Actions schedule:, and notes GH Actions cron is UTC."
+      - "Includes a freshness gate before send and a fail-loud failure alert to the named owner."
+      - "Routes KPI-definition to kpi-framework and any live-view/slice request to dashboard rather than absorbing them; defers transport to email-connector."