What (One-liner)

US three-factor macro leading index: INDPRO / UNRATE / FEDFUNDS z-score standardized, weighted (0.4 / -0.3 / -0.3 with negative-weight sign-flip), 3-month rolling smoothed, last-two-period diff decides direction (rising / falling / turning). Outputs direction + smoothed value + ad-hoc confidence.

How to use

Drop macro_cli_v1 on Canvas, no params or limit=36 (months). Direct call: GET /mfle/leading-indicators/cli. Typical output:

→ { direction: "rising", value: 1.82, confidence: 0.95,
    as_of_date: "2025-12-01", logic_lineage: [...] }

Pair with macro_snapshot_v1 (current regime) + macro_cycle_v1 (cycle phase) as a three-piece macro overlay.

Core formulas

z_INDPRO    = (INDPRO - mean) / std        # positive contribution
z_UNRATE    = -(UNRATE - mean) / std       # sign-flipped (negative weight)
z_FEDFUNDS  = -(FEDFUNDS - mean) / std     # sign-flipped

cli_raw   = z_INDPRO * 0.4 + z_UNRATE * 0.3 + z_FEDFUNDS * 0.3
cli_smooth = cli_raw.rolling(3).mean()

diff = cli_smooth[-1] - cli_smooth[-2]
  |diff| < 0.05  → 'turning' (confidence=0.5)
  diff > 0       → 'rising'  (confidence=min(0.95, 0.5 + |diff|*2))
  diff < 0       → 'falling' (confidence=min(0.95, 0.5 + |diff|*2))

Rounding contract: value→4, confidence→2.

Assumptions & applicability

Assumptions: US FRED monthly only; 3 fixed-weight components; z-score standardization; 3-month rolling smoothing; ≥5 observations.

Applies to: macro-narrative direction input, Canvas cross-asset strategy overlay, teaching demo.

Does not apply to: strict OECD CLI reproduction; non-US economies; intraday signals; quantitative decisions requiring confidence intervals.

Input / Output contract

{limit?=36} → {available, direction, value, confidence, as_of_date, logic_lineage} (with reason when available=False).

Known limitations

1. US-only 3-component: INDPRO / UNRATE / FEDFUNDS hard-coded; no geographic override
2. Simplified z-score vs OECD HP-filter-based: no trend extraction, no phase-average-trend, no component-group normalization
3. Actually coincident-ish: INDPRO is contemporaneous with GDP; true leading would need order books / term spread / consumer confidence
4. Threshold (0.05) empirical: no empirical calibration
5. Confidence formula ad-hoc: (0.5 + |diff|*2, cap 0.95); not a statistical confidence interval
6. Monthly alignment ffill+bfill: forward-fills when components miss data, can produce false signals
7. No regime-dependent weight shift

References

OECD (2012) System of CLI + Stock-Watson (1989) New Indexes of Coincident/Leading Economic Indicators + Hodrick-Prescott (1997) business cycles. See frontmatter.

Golden Test

tests/golden/fixtures/tier2/macro_cli/ — monkey-patched FRED deterministic snapshot. 1e-10 tolerance. 9 tests:

• matches_snapshot — full output byte-equal (rising scenario)
• determinism — 5 reruns byte-identical
• rising_direction — accelerating expansion → 'rising' + confidence 0.95
• falling_direction — reverse (unemployment up / output down) → 'falling'
• turning_direction — plateau tail → 'turning' + confidence 0.5
• result_structure — 6 fixed top-level keys
• logic_lineage_locked — fixed string list
• unavailable_no_fred — FRED_API_KEY missing → available=False, direction=None
• confidence_cap — extreme diff → confidence exactly 0.95

Changelog

• 1.0.0 (2026-04-20) — First Active (Tier 2 batch 7)