Introduce Peek: a data-leakage auditor extracted from AgentQuant

[OnePunchMonk]

Summary

This is a deliberate pivot of this repo's headline project. AgentQuant (the LLM trading research agent) proved a real, useful thing in its own paper draft: our own walk-forward validation showed the context-aware agent losing to a static baseline. Chasing down why led to auditing our backtest for look-ahead bias — and to the realization that "does my time-series pipeline leak the future into training" is a near-universal ML problem with almost no dedicated tooling (sklearn.TimeSeriesSplit only splits, it doesn't detect leakage).

Peek is that tool, generalized out of AgentQuant's WarmupEnforcer/lookback-guard code into a standalone library:

import peek
report = peek.audit(df, time_col="date", target="y", feature_fn=build_features)
print(report)  # LEAKING / SUSPICIOUS / CLEAN, with proof

Four checks, each gated on what the caller supplies:

• target_leak (always runs) — flags a feature that's a near-exact copy of the (possibly shifted) target.
• causality (flagship, needs feature_fn) — recomputes features on a truncated series vs. the full series; if a value changes, the feature saw the future. Catches centered rolling windows, whole-dataset normalization, etc., regardless of shape.
• split (needs splits/splitter) — train/test temporal overlap, future-dated training rows, missing embargo gap.
• shuffle (needs pipeline+cv+scorer) — permutation test comparing the real score against scores achievable on randomly shuffled labels.

Also ships a CLI: peek demo (instant leaky-vs-clean walkthrough) and peek audit data.csv --time ... --target ....

What changed

• New peek/ package (audit orchestrator, report/verdict types, 4 checks, synthetic demo datasets, CLI).
• 17 new tests (tests/test_peek_*.py) covering every check plus report/verdict logic — all passing, plus all 63 pre-existing AgentQuant tests still pass (80 total).
• README rewritten to lead with Peek. AgentQuant is fully preserved, untouched in src/, and documented as the origin-story case study in docs/AGENTQUANT.md (moved from the old README content, not deleted).
• pyproject.toml: added peek console script + package discovery; description updated.
• CI: added peek/ to the ruff lint step.
• .gitignore: exclude local .venv/.

Nothing in src/, experiments/, or the original test suite was modified or removed.

Test plan

• pytest tests/ -v — 80 passed (63 AgentQuant + 17 Peek), no regressions.
• ruff check peek/ tests/test_peek_*.py — clean (pre-existing lint debt elsewhere in src//tests/ untouched by this PR).
• python -m peek.cli demo — verified end-to-end: correctly flags both injected leaks (future-copy feature + centered rolling window) on the leaky dataset, and reports CLEAN on the causally-correct dataset built from the same generative process.
• Reviewer: confirm CI passes on 3.10/3.11/3.12 (dev sandbox only had Python 3.9 available, so package install against the declared >=3.10 requirement wasn't exercised locally — python -m peek.cli and pytest were run directly against source).