@damiangilgonzalez/harness 1.3.7

package/skills/unit-economics/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: unit-economics
+description: "Use when computing or improving the per-customer economics of a business — CAC, LTV, CAC payback period and contribution margin — judging whether the ratios are healthy against current norms, and naming the one lever that fixes the worst number. Covers a blended CAC that hides a bleeding channel, and a model that shows profit while each customer loses money. NOT the multi-year P&L or scenario projection (that is `financial-model`)."
+tags: ["cac", "ltv", "payback-period", "contribution-margin", "unit-economics", "ltv-cac-ratio", "nrr", "saas-metrics"]
+recommends: ["financial-model", "pricing", "retention", "cost-tracking", "forecasting", "investor-materials", "dashboard"]
+origin: risco
+---
+
+# Unit economics
+
+Answer one question honestly: **does one customer pay back more than it cost to win and serve them, and how fast?** You compute four load-bearing numbers — CAC, contribution margin, LTV, CAC payback period — plus the two ratios operators and investors actually argue about (LTV:CAC, NRR). Then you diagnose *why* a number is where it is and name the single lever that moves it.
+
+This is a measurement-and-diagnosis skill, not a projection skill. You do not build the multi-year model here (that is the `financial-model` sibling); you build the per-customer truth that the model's growth assumptions have to rest on.
+
+## What this skill produces
+
+A **unit-economics worksheet** (`unit-economics.{yaml,csv,md}`) where:
+- a block of **named inputs** — period S&M spend, new customers, monthly ARPA, gross margin %, monthly churn, optional segment rows — is stated explicitly;
+- every **derived figure** (CAC, contribution margin, LTV, payback, LTV:CAC) is recomputed *from those inputs* so the relationships are self-consistent;
+- the worst number is diagnosed and one concrete lever is prescribed.
+
+`scripts/verify.sh` re-derives the figures and fails if the arithmetic lies (see the last section). If you only hand back prose, you have not finished — emit the worksheet.
+
+## The four numbers and the input people get wrong
+
+Each formula has one input that, done sloppily, silently invalidates everything downstream. Tag the input, not just the result.
+
+| Number | Formula | The input people get wrong |
+|---|---|---|
+| **CAC** | fully-loaded S&M spend ÷ new customers (same period) | the *numerator* — ad-spend-only CAC understates true CAC ~3.5× |
+| **Contribution margin / customer** | ARPA − variable cost to serve (COGS + variable support + payment fees) | confusing it with company-wide gross margin % |
+| **LTV** | (ARPA × Gross Margin %) ÷ churn rate | using *revenue* instead of *gross-margin* dollars |
+| **CAC payback (months)** | CAC ÷ (monthly ARPA × Gross Margin %) | leaving gross margin out of the denominator |
+
+**Worked Bad → Good — the revenue-LTV inflation.** Same inputs: ARPA $400/mo, gross margin 75%, monthly churn 3%.
+
+```text
+Bad  (revenue LTV):       400 / 0.03          = $13,333   <- overstates by 33%
+Good (gross-margin LTV): (400 * 0.75) / 0.03  = $10,000   <- what a customer is actually worth
+```
+
+LTV must use gross-margin dollars because not all revenue is profit — hosting, support, and payment fees come out first. The revenue version flatters the LTV:CAC ratio and is the single most common dishonesty in a deck. (Beancount.io "2026 SaaS Metrics Stack" 2026-05-10; ChartMogul LTV guide; both accessed 2026-06-02.)
+
+Full derivations, cohort-LTV vs formula-LTV, the Skok discounted model, and segment roll-up math live in `references/formulas.md`. Read it before you defend a number to an investor.
+
+## Order of operations (the spine)
+
+Run these in order — each step is an input to the next, so skipping one makes everything after it fiction.
+
+1. **Gross margin first.** Every downstream metric multiplies by it. If gross margin is unknown, the COGS per unit must be tracked first (route to `cost-tracking`) — you cannot compute LTV or payback on a guessed margin.
+2. **CAC, fully loaded.** Include all sales + marketing cost; exclude customer-success/retention spend and returning customers.
+3. **Contribution margin per customer.** ARPA minus variable cost to serve — the dollars that actually pay back CAC.
+4. **LTV, capped.** Gross-margin LTV with a lifetime cap (see conservatism), not 1/churn run to infinity.
+5. **Payback period.** CAC ÷ monthly contribution margin.
+6. **Ratios.** LTV:CAC and NRR/GRR for context.
+7. **Diagnose & prescribe.** Find the worst number, name its cause, name the lever.
+
+## Get the inputs honest
+
+CAC is fully loaded or it is a lie. Decide what goes in the numerator before you divide.
+
+| In the CAC numerator | Out of the CAC numerator |
+|---|---|
+| Sales + marketing salaries & benefits | Customer-success / retention spend (that protects LTV, it doesn't acquire) |
+| Sales commissions & SDR/AE comp | R&D / product engineering |
+| Ad spend, content, events, agencies | Overhead/G&A not tied to acquisition |
+| Marketing & sales tooling | (Denominator) returning / reactivated customers — only count *new* logos |
+| Founder selling time (impute a salary) | |
+
+Three rules that catch most errors:
+
+- **Gross margin, not opex margin.** Gross margin reflects COGS (hosting, support, payment fees), not salaries/rent. Mixing in opex understates margin and quietly tanks LTV. (Beancount.io 2026-05-10, accessed 2026-06-02.)
+- **Match time units.** Monthly ARPA pairs with monthly churn; annual with annual. Mixing them silently 12×'s or ÷12's the LTV — the most common arithmetic error in the whole exercise. (ChartMogul; metrickit LTV guide; accessed 2026-06-02.)
+- **Right period, right denominator.** Spend in period P ÷ customers acquired in period P. Don't divide this quarter's spend by all-time customers.
+
+## Segment before you optimize
+
+A single blended number hides the only insight that matters. Reporting one blended CAC of $1,200 when self-serve is $80 and field sales is $40,000 tells you nothing actionable — the channels have wildly different CAC, ARPA, and churn. (lucid.now LTV/CAC errors; andrewchen; accessed 2026-06-02.)
+
+```text
+Blended CAC $1,200  =  self-serve $80  +  inside sales $900  +  field $40,000
+                       (lever: scale)   (lever: AE ramp)      (lever: ACV / cycle)
+```
+
+Two more separations to keep clean:
+- **Paid CAC vs blended CAC.** Blended includes free/organic; paid isolates the channels you can actually scale with money. Optimize paid; report both.
+- **Self-serve / inside sales / field sales.** Split on go-to-motion, because the lever for each is different. If one segment is bleeding while blended "looks fine," that's exactly the non-obvious failure this skill exists to surface.
+
+## Benchmarks (2025-2026)
+
+A ratio is a conversation-starter, not a pass/fail grade. Read the whole row before you celebrate or panic.
+
+| Metric | Elite / top quartile | Healthy / median | Concern |
+|---|---|---|---|
+| CAC payback | < 12 months | B2B SaaS median 12-18 mo | 24+ months = sustainability concern |
+| Payback by ACV | ~9 mo at ACV ≤ $5K | — | ~24 mo at ACV > $100K (expected, not bad) |
+| LTV:CAC | 3:1 to 5:1 | median B2B ≈ 3.2:1 | < 3:1 overspending; **> 5:1 under-investing in growth** |
+| NRR | top quartile 115-125% | healthy 105-115% | < 100% net contraction |
+| GRR | — | — | high NRR + low GRR = expansion masking churn |
+
+(Beancount.io 2026-05-10; First Page Sage CAC Payback Benchmarks 2025; Optifai B2B LTV benchmark, 939 companies; cast.app NRR; all accessed 2026-06-02.)
+
+The honest framing: a **2.5:1 with 9-month payback and 120% NRR beats a 4:1 with 36-month payback and 95% NRR.** Payback and NRR decide whether you can survive the gap between spend and return; the ratio alone can't. **Rule of 40** (ARR growth % + profit margin % ≥ 40%) is the company-level destination these feed — cite it, but compute it in `financial-model`, not here.
+
+## Diagnose & prescribe (this is where the flow branches)
+
+Find the worst number, then route to the lever — and to the sibling skill that owns that lever.
+
+| Bad number | Likely cause | Lever (and owner) |
+|---|---|---|
+| CAC too high | wrong channel mix / paid-heavy | shift to founder-led & organic; cut the bleeding channel — diagnose by segment here, then `pricing` if the fix is monetization |
+| Payback too long | low margin-dollar capture per month | move to annual prepay; shorten free trial; lift gross margin (`cost-tracking` for COGS) |
+| LTV too low | dominant churn term | attack the biggest churn driver → `retention`; lift expansion to push NRR > 100% |
+| Margin too low | COGS per unit too high | instrument per-unit COGS / inference cost → `cost-tracking` |
+| LTV:CAC > 5:1 | under-investing in growth | spend *more* on acquisition — you're leaving money on the table, not winning |
+| NRR ≫ GRR | expansion masking a churn problem | fix gross retention first → `retention`; don't let expansion hide the leak |
+
+The skill stops at "here is the worst number and the lever." Executing the lever (set the price, design the save-play, project the new curve) belongs to the sibling, not here.
+
+## Conservatism rules (so LTV isn't fantasy)
+
+Small churn errors explode LTV because of the 1/churn term — at 1% monthly churn the formula implies a ~100-month (8+ year) lifetime, which no early-stage company has data to claim.
+
+- **Cap assumed lifetime at 3-4 years** for early-stage (≤ 48 months), or apply a **×0.7 conservatism multiplier** to formula LTV.
+- **Cohort beats formula.** Once you have multi-year retention data, compute cohort LTV from observed retention — the formula is a placeholder until then.
+- **Discount future value** in the advanced (Skok) model: ~20-25% discount rate pre-scale, ~10% at scale, because a dollar of contribution margin three years out is worth less than one today.
+- **NRR > 100% means the simple churn-only LTV understates** the cohort — note it rather than silently leaving value on the table.
+
+(Beancount.io 2026-05-10; metrickit LTV guide; forEntrepreneurs SaaS Metrics 2.0; all accessed 2026-06-02.) Worked discounted and cohort examples are in `references/formulas.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| Revenue LTV (ARPA ÷ churn) | overstates value; not all revenue is profit | gross-margin LTV: (ARPA × GM%) ÷ churn |
+| Ad-spend-only CAC | understates true CAC ~3.5× | fully-loaded S&M ÷ new customers |
+| Monthly ARPA with annual churn | silently 12×'s or ÷12's the LTV | match time units before dividing |
+| Near-zero churn → 30-year lifetime | fantasy LTV no one can back with data | cap lifetime ≤ 48 mo or ×0.7 multiplier |
+| One blended CAC/LTV | hides self-serve vs field; nothing actionable | segment by go-to-motion first |
+| Counting CS/retention spend in CAC | inflates CAC; that spend protects LTV, doesn't acquire | keep CS out of the numerator |
+| Reading only the LTV:CAC ratio | ignores payback & NRR that decide survivability | read payback + NRR alongside the ratio |
+| Quoting NRR while GRR is weak | expansion masks a churn leak | report GRR floor too; fix retention first |
+
+## The worksheet format
+
+Emit this so the numbers are checkable, not just asserted:
+
+```yaml
+# unit-economics.yaml
+inputs:
+  period_sm_spend: 120000      # fully-loaded S&M, this period
+  new_customers: 80            # new logos only, same period
+  monthly_arpa: 400
+  gross_margin_pct: 0.75
+  monthly_churn: 0.03          # monthly, to match monthly_arpa
+  # lifetime_cap_override: 60  # only if you justify > 48 months
+outputs:
+  cac: 1500                    # 120000 / 80
+  contribution_margin: 300     # 400 * 0.75
+  ltv: 10000                   # (400 * 0.75) / 0.03   (NOT 13333)
+  payback_months: 5            # 1500 / (400 * 0.75)
+  ltv_cac: 6.67                # 10000 / 1500  -> >5: under-investing
+segments:                      # split when blended hides the truth
+  - name: self-serve
+    cac: 80
+  - name: field-sales
+    cac: 40000
+```
+
+`scripts/verify.sh` parses this file and **fails if**: CAC ≠ spend ÷ new_customers; contribution_margin ≠ ARPA × GM%; payback ≠ CAC ÷ (ARPA × GM%); the stated LTV matches the *revenue* form instead of the gross-margin form; ltv_cac ≠ LTV ÷ CAC within 0.05; or implied lifetime (1/churn) > 48 months with no `lifetime_cap_override`. It is read-only and exits 0 on a clean worksheet (and on no worksheet at all).
+
+## Where this hands off
+
+- Multi-year P&L / scenario / cap-table model → `financial-model`.
+- Setting the actual price, tiers, discount floor → `pricing`.
+- Churn-prevention program (health scores, save-plays, win-back) → `retention`.
+- Per-unit COGS / infra / AI inference cost so gross margin is even knowable → `cost-tracking`.
+- Forecasting future MRR / cohort projection → `forecasting`.
+- Writing the investor unit-economics narrative / data-room exhibit → `investor-materials`.
+- Generic KPI chart / dashboard surface → `dashboard`.

package/skills/unit-economics/evals/README.md

@@ -0,0 +1,5 @@
+# Evals — unit-economics
+
+These cases are read, not executed. To run them by eye: for each `should_trigger` prompt, confirm the skill's `description` would plausibly fire on it (the non-obvious "blended CAC looks fine but paid is bleeding" and the Catalan payback case are the ones to watch — they never name a metric). For each `should_not_trigger` prompt, confirm the request belongs to the named `route_to` sibling instead (financial-model for the multi-year model, pricing for setting the price, retention for save-plays, cost-tracking for per-unit COGS, forecasting for cohort projection).
+
+The `capability` case is graded by handing the scenario to the agent and checking its answer against the `must_include` rubric: correct CAC ($1,500), gross-margin LTV ($10,000, not the $13,333 revenue version, with the difference flagged), payback in months (5), the >5:1 under-investing read on the 6.67:1 ratio, a conservatism/lifetime-cap note, segmentation advice, and an actual recomputable worksheet rather than prose. A worksheet emitted to `unit-economics.yaml` should additionally pass `scripts/verify.sh` clean.

package/skills/unit-economics/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: unit-economics
+
+should_trigger:
+  - prompt: "What's our CAC and LTV, and is the LTV:CAC ratio healthy?"
+    why: "Canonical trigger — compute the core numbers plus benchmark the ratio; the skill's center of gravity."
+  - prompt: "Our payback period feels too long — how do I bring it down?"
+    why: "Diagnosis + lever, not just a calculation; routes to annual prepay / margin levers via the diagnose table."
+  - prompt: "Calcula'm el CAC i quant trigo a recuperar el cost d'un client."
+    why: "Catalan; 'quant trigo a recuperar el cost' is the payback-period phrasing without naming the metric in English."
+  - prompt: "Our blended CAC looks fine but I think paid is bleeding money — can we check?"
+    why: "NON-OBVIOUS — the user never says 'unit economics' or 'segment'; this is exactly the paid-vs-blended / segmentation failure the skill surfaces."
+  - prompt: "The model says we're profitable but each customer feels like a loss — what's the contribution margin per customer?"
+    why: "Contribution-margin entry point; surfaces the per-unit truth against a whole-company P&L that looks fine."
+  - prompt: "Is a 5:1 LTV:CAC actually good or are we under-investing in growth?"
+    why: "Benchmark interpretation — the >5:1 under-investing caveat that most rules-of-thumb miss."
+
+should_not_trigger:
+  - prompt: "Build me a 3-year revenue and P&L projection for the raise."
+    route_to: financial-model
+    why: "Multi-year projection / scenario engine, not the per-customer truth; the named boundary in the description."
+  - prompt: "What should we charge and how should we package the tiers?"
+    route_to: pricing
+    why: "Setting the actual price and packaging, not validating the economics of an existing price."
+  - prompt: "Design a churn save-play and win-back sequence for at-risk accounts."
+    route_to: retention
+    why: "Churn-prevention program design, not measuring churn's effect on LTV."
+  - prompt: "Figure out our per-request AI inference cost so we know gross margin."
+    route_to: cost-tracking
+    why: "Per-unit COGS instrumentation that feeds gross margin — upstream of this skill, not the same job."
+  - prompt: "Forecast next year's MRR from our cohort retention curves."
+    route_to: forecasting
+    why: "Time-series / cohort projection, not the per-customer ratios."
+
+capability:
+  - scenario: "Operator gives: period S&M spend $120K, 80 new customers, monthly ARPA $400, gross margin 75%, monthly churn 3%; one segment is self-serve, one is sales-led. Produce the unit-economics worksheet and diagnose."
+    must_include:
+      - "CAC = $1,500 (120000 / 80)."
+      - "Gross-margin LTV: (400 × 0.75) / 0.03 = $10,000, explicitly NOT the revenue LTV of $13,333, and flags the difference."
+      - "Payback = 1500 / (400 × 0.75) = 5 months (gross margin in the denominator)."
+      - "LTV:CAC = 6.67:1, flagged as possibly under-investing in growth because it exceeds 5:1."
+      - "Conservatism note: 3% monthly churn implies ~33-month life, within the 48-month cap; states the cap/×0.7 rule."
+      - "Recommends segmenting self-serve vs sales-led because blended hides the truth, and names the lever for the worst sub-metric."
+      - "Emits a worksheet (yaml/csv/md) with named inputs and recomputed outputs, not just prose."

package/skills/unit-economics/references/formulas.md

@@ -0,0 +1,144 @@
+# Unit-economics formulas — full derivations
+
+The SKILL.md body carries the spine. This file carries every derivation you need to defend a number, with worked examples on consistent units.
+
+All examples reuse one base case unless stated:
+
+```text
+period S&M spend = $120,000   new customers = 80
+monthly ARPA = $400           gross margin = 75% (0.75)
+monthly churn = 3% (0.03)
+```
+
+## 1. CAC — fully loaded
+
+```text
+CAC = (all sales + marketing cost in period) / (new customers acquired in same period)
+    = 120000 / 80
+    = $1,500
+```
+
+Numerator includes salaries, benefits, commissions, ad spend, content, events, agencies, tooling, and imputed founder selling time. It excludes customer-success/retention spend (that protects existing LTV) and R&D. Ad-spend-only CAC commonly understates true CAC by ~3.5×. Denominator counts new logos only — exclude returning/reactivated customers.
+
+Keep two CACs:
+- **Paid CAC** = paid-channel spend ÷ customers from paid channels (the part you scale with money).
+- **Blended CAC** = all S&M ÷ all new customers (includes free/organic).
+
+## 2. Contribution margin per customer
+
+```text
+contribution_margin = ARPA - variable_cost_to_serve
+                    = ARPA - (COGS + variable support + payment/processing fees)
+                    = 400 * 0.75            # when GM% already nets out variable cost
+                    = $300 / month
+```
+
+Distinct from **gross margin %**, which is the company-wide ratio. Contribution margin is the per-customer dollar figure that actually pays back CAC and funds opex. LTV is the (discounted) stream of this contribution margin over the customer's life.
+
+## 3. LTV — gross-margin, not revenue
+
+Consistent monthly units throughout:
+
+```text
+gross-margin LTV = (monthly ARPA * GM%) / monthly churn
+                 = (400 * 0.75) / 0.03
+                 = 300 / 0.03
+                 = $10,000
+
+revenue LTV (WRONG) = 400 / 0.03 = $13,333   # overstates by 33%
+```
+
+Annual units must pair together:
+
+```text
+annual ARPA = 4800, annual churn = 30.4%  (1 - (1-0.03)^12)
+annual LTV = (4800 * 0.75) / 0.304 ≈ $11,842
+```
+
+Note the annual figure differs from the naive monthly×12 because compounding churn over 12 months exceeds 36%. When precision matters, derive annual churn from monthly via `1 - (1 - m)^12`, not `m * 12`.
+
+## 4. CAC payback period
+
+```text
+payback_months = CAC / (monthly ARPA * GM%)
+               = 1500 / (400 * 0.75)
+               = 1500 / 300
+               = 5 months
+```
+
+The denominator is monthly contribution margin. Leaving GM% out (`1500 / 400 = 3.75`) understates payback and is a common error.
+
+## 5. LTV:CAC
+
+```text
+LTV:CAC = LTV / CAC = 10000 / 1500 = 6.67 : 1
+```
+
+Interpretation against 2025-2026 norms: 3:1-5:1 healthy; < 3:1 overspending on acquisition; **> 5:1 under-investing in growth** (6.67:1 here → spend more). Median B2B SaaS ≈ 3.2:1. The ratio is a conversation, not a grade — pair it with payback and NRR.
+
+## 6. Lifetime cap & conservatism
+
+Implied lifetime from churn:
+
+```text
+implied_lifetime_months = 1 / monthly_churn = 1 / 0.03 ≈ 33.3 months   # within the 48-mo cap
+```
+
+At 1% monthly churn, `1/0.01 = 100 months` (8+ years) — fantasy for an early-stage company. Apply one of:
+
+- **Hard cap** at 36-48 months: `capped_LTV = min(formula_LTV, contribution_margin * cap_months)`.
+- **Conservatism multiplier**: `conservative_LTV = formula_LTV * 0.7`.
+
+```text
+base case capped LTV = min(10000, 300 * 48) = min(10000, 14400) = 10000   # cap not binding
+×0.7 conservative    = 10000 * 0.7 = $7,000
+```
+
+## 7. Skok discounted LTV (advanced)
+
+A dollar of contribution margin years out is worth less today. Discount the stream:
+
+```text
+LTV = sum over t of [ contribution_margin_t * retention_t / (1 + d)^t ]
+```
+
+with discount rate `d` ≈ 20-25% pre-scale, ≈ 10% at scale. Use this once you can model the retention curve `retention_t`; before that, the capped formula LTV is the honest placeholder.
+
+## 8. NRR / GRR worked example
+
+```text
+Start MRR = 100,000
++ expansion = 12,000
+- contraction = 3,000
+- churn = 5,000
+
+NRR = (100000 + 12000 - 3000 - 5000) / 100000 * 100 = 104%
+GRR = (100000 - 3000 - 5000) / 100000 * 100        = 92%   # no expansion
+```
+
+Healthy NRR 105-115%, top quartile 115-125%. GRR is the true floor. Here NRR 104% looks fine but GRR 92% means **8% gross monthly leakage masked by expansion** — fix gross retention (route to `retention`) before celebrating NRR. When NRR > 100%, the simple churn-only LTV understates the cohort's true value; note it.
+
+## 9. Segment roll-up
+
+Never average segment CACs naively — weight by customers.
+
+```text
+blended CAC = total S&M / total new customers
+            = (self_serve_spend + inside_spend + field_spend)
+              / (self_serve_n + inside_n + field_n)
+```
+
+Example: self-serve $80 (500 customers), field $40,000 (10 customers).
+
+```text
+blended = (80*500 + 40000*10) / (500 + 10)
+        = (40000 + 400000) / 510
+        = 440000 / 510
+        ≈ $863
+```
+
+The $863 blended number is real but useless for action — the levers (scale self-serve, fix field ACV/cycle) live in the segments, not the blend. Always segment before you optimize.
+
+## Sources
+
+Beancount.io "2026 SaaS Metrics Stack" (2026-05-10); ChartMogul LTV guide; metrickit LTV guide; andrewchen "How To (Actually) Calculate CAC"; First Page Sage SaaS CAC Payback Benchmarks 2025; Drivetrain CAC payback glossary; Optifai B2B SaaS LTV benchmark (939 companies); lucid.now LTV vs CAC errors; TZS Digital CAC deep dive; cast.app NRR; WallStreetPrep LTV/CAC; forEntrepreneurs SaaS Metrics 2.0. All accessed 2026-06-02.

package/skills/unit-economics/scripts/verify.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+#
+# verify.sh - re-derive a unit-economics worksheet and fail if the arithmetic lies.
+#
+# Usage:
+#   cd <dir containing unit-economics.yaml|.csv|.md>
+#   ./verify.sh [path-to-worksheet]
+#
+# Read-only: never mutates anything. Parses named inputs/outputs and checks:
+#   - cac                 == period_sm_spend / new_customers
+#   - contribution_margin == monthly_arpa * gross_margin_pct
+#   - payback_months      == cac / (monthly_arpa * gross_margin_pct)
+#   - ltv  uses gross-margin form (ARPA*GM)/churn, NOT revenue form ARPA/churn
+#   - ltv_cac             == ltv / cac          (within 0.05)
+#   - implied lifetime (1/monthly_churn) <= 48 months unless lifetime_cap_override set
+#
+# Tolerance: +/-0.5% on money figures, +/-0.05 on ratios.
+# Exits 0 on a clean worksheet AND on no worksheet found (no false failure).
+# Exits 1 with the specific failing check on any violation.
+#
+# Portable: stock macOS bash 3.2 + awk. No associative arrays, no mapfile.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+
+# --- locate the worksheet ----------------------------------------------------
+file="${1:-}"
+if [ -z "$file" ]; then
+  for cand in unit-economics.yaml unit-economics.yml unit-economics.csv unit-economics.md; do
+    if [ -f "$cand" ]; then file="$cand"; break; fi
+  done
+fi
+
+if [ -z "$file" ] || [ ! -f "$file" ]; then
+  printf '%s[skip]%s no unit-economics.{yaml,csv,md} found - nothing to verify.\n' "$YELLOW" "$RESET"
+  exit 0
+fi
+
+# --- extract a numeric field by key (yaml-ish, csv-ish, or "key: value") -----
+# Matches lines like "  cac: 1500", "cac,1500", "cac = 1500", "| cac | 1500 |".
+# Strips $ , % and surrounding noise; takes the first number after the key.
+getnum() {
+  key="$1"
+  awk -v k="$key" '
+    { line=$0
+      # normalise separators to spaces, drop currency/percent/comma noise
+      gsub(/[,$%|{}\[\]]/, " ", line)
+      gsub(/[:=]/, " ", line)
+    }
+    line ~ ("(^|[^a-zA-Z_])" k "([^a-zA-Z_]|$)") {
+      n=split(line, a, " ")
+      seen=0
+      for (i=1;i<=n;i++){
+        if (a[i]==k){ seen=1; continue }
+        if (seen && a[i] ~ /^-?[0-9]+(\.[0-9]+)?$/){ print a[i]; exit }
+      }
+    }
+  ' "$file"
+}
+
+spend=$(getnum period_sm_spend)
+newc=$(getnum new_customers)
+arpa=$(getnum monthly_arpa)
+gm=$(getnum gross_margin_pct)
+churn=$(getnum monthly_churn)
+override=$(getnum lifetime_cap_override)
+
+cac=$(getnum cac)
+cm=$(getnum contribution_margin)
+ltv=$(getnum ltv)
+payback=$(getnum payback_months)
+ltvcac=$(getnum ltv_cac)
+
+failed=0
+
+require() { # name value
+  if [ -z "$2" ]; then fail "missing required input '$1' in $file"; fi
+}
+require period_sm_spend "$spend"
+require new_customers "$newc"
+require monthly_arpa "$arpa"
+require gross_margin_pct "$gm"
+require monthly_churn "$churn"
+if [ "$failed" -ne 0 ]; then
+  printf '\n%sFAIL:%s worksheet is missing inputs needed to verify.\n' "$RED" "$RESET"
+  exit 1
+fi
+
+# gross_margin_pct may be given as 0.75 or 75; normalise to a fraction.
+gm=$(awk -v g="$gm" 'BEGIN{ if (g>1.0001) g=g/100; printf "%.6f", g }')
+
+printf -- '----- verifying %s\n' "$file"
+
+# helper: are two numbers within tolerance? tol is a fraction of |expected|.
+close() { # actual expected tol
+  awk -v a="$1" -v e="$2" -v t="$3" 'BEGIN{
+    d=a-e; if(d<0)d=-d;
+    lim=e; if(lim<0)lim=-lim;
+    lim=lim*t; if(lim<0.0001)lim=0.0001;   # floor so exact zeros still compare
+    exit (d<=lim)?0:1
+  }'
+}
+
+exp_cac=$(awk -v s="$spend" -v n="$newc" 'BEGIN{ if(n==0){print "NaN"} else printf "%.6f", s/n }')
+exp_cm=$(awk  -v a="$arpa" -v g="$gm" 'BEGIN{ printf "%.6f", a*g }')
+exp_pay=$(awk -v c="$exp_cac" -v a="$arpa" -v g="$gm" 'BEGIN{ d=a*g; if(d==0){print "NaN"} else printf "%.6f", c/d }')
+exp_ltv=$(awk -v a="$arpa" -v g="$gm" -v ch="$churn" 'BEGIN{ if(ch==0){print "NaN"} else printf "%.6f", (a*g)/ch }')
+rev_ltv=$(awk -v a="$arpa" -v ch="$churn" 'BEGIN{ if(ch==0){print "NaN"} else printf "%.6f", a/ch }')
+
+# 1. CAC
+if [ -n "$cac" ]; then
+  if close "$cac" "$exp_cac" 0.005; then ok "CAC $cac == spend/new ($exp_cac)";
+  else fail "CAC $cac != spend/new_customers ($exp_cac)"; fi
+else
+  fail "stated output 'cac' missing"
+fi
+
+# 2. contribution margin
+if [ -n "$cm" ]; then
+  if close "$cm" "$exp_cm" 0.005; then ok "contribution_margin $cm == ARPA*GM ($exp_cm)";
+  else fail "contribution_margin $cm != ARPA*GM% ($exp_cm)"; fi
+fi
+
+# 3. payback
+if [ -n "$payback" ]; then
+  if close "$payback" "$exp_pay" 0.005; then ok "payback_months $payback == CAC/(ARPA*GM) ($exp_pay)";
+  else fail "payback_months $payback != CAC/(ARPA*GM%) ($exp_pay)"; fi
+fi
+
+# 4. LTV must be gross-margin form, not revenue form
+if [ -n "$ltv" ]; then
+  if close "$ltv" "$exp_ltv" 0.005; then
+    ok "LTV $ltv == (ARPA*GM)/churn ($exp_ltv)"
+  elif close "$ltv" "$rev_ltv" 0.005; then
+    fail "LTV $ltv uses REVENUE form ARPA/churn ($rev_ltv); use gross-margin (ARPA*GM)/churn ($exp_ltv)"
+  else
+    fail "LTV $ltv != (ARPA*GM)/churn ($exp_ltv)"
+  fi
+fi
+
+# 5. LTV:CAC
+if [ -n "$ltvcac" ] && [ -n "$cac" ] && [ -n "$ltv" ]; then
+  exp_ratio=$(awk -v l="$ltv" -v c="$cac" 'BEGIN{ if(c==0){print "NaN"} else printf "%.6f", l/c }')
+  # absolute 0.05 tolerance on the ratio
+  if awk -v a="$ltvcac" -v e="$exp_ratio" 'BEGIN{ d=a-e; if(d<0)d=-d; exit (d<=0.05)?0:1 }'; then
+    ok "ltv_cac $ltvcac == LTV/CAC ($exp_ratio)"
+  else
+    fail "ltv_cac $ltvcac != LTV/CAC ($exp_ratio)"
+  fi
+fi
+
+# 6. lifetime cap
+life=$(awk -v ch="$churn" 'BEGIN{ if(ch==0){print "999999"} else printf "%.2f", 1/ch }')
+cap=48
+if [ -n "$override" ]; then cap="$override"; fi
+if awk -v l="$life" -v c="$cap" 'BEGIN{ exit (l<=c)?0:1 }'; then
+  ok "implied lifetime ${life}mo <= cap ${cap}mo"
+else
+  if [ -n "$override" ]; then
+    fail "implied lifetime ${life}mo exceeds override cap ${cap}mo"
+  else
+    fail "implied lifetime ${life}mo exceeds 48mo cap; set lifetime_cap_override to justify"
+  fi
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s worksheet arithmetic is inconsistent.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s worksheet is self-consistent.\n' "$GREEN" "$RESET"