# CLAUDE.md — UQO Research WP39

## THE INVISIBLE BALANCE SHEET
### Can Intraday Financial Markets Detect Corporate Deterioration Before Accounting Disclosures?

**Project ID:** `wp39_uqo` · **Institution:** Université du Québec en Outaouais (UQO) · **PI:** Simon-Pierre Boucher
**Status:** research project built 2026-11-02 under the owner's specification (reproduced below in condensed form; the
owner's original brief is the authoritative text). All findings are hypotheses until reproducibly estimated.

Owner instructions added during the build (2026-11-02): (1) the FinData **fundamentals API** is the accounting source and
must be used; (2) **minimise AI usage** — no LLM features, no neural/text models, no AI-generated statistics.

## Non-negotiable execution rules
1. FinData OS (`https://findata.spboucher.ai/api/v1`) is the primary source of prices, volumes, earnings events and
   fundamentals. No silent substitution; every exception is documented in `DATA_AUDIT.md` / `docs/API_INTEGRATION.md`.
2. Inspect before changing; preserve all other working papers; this repository is its own git repo.
3. Credentials from the protected store only (`~/findata-secrets/api-key-wp39.txt` on the node); never printed, never
   in URLs, git, artifacts, notebooks, figures or manuscript. No destructive ingestion, no unapproved backfills.
4. FirstRate Data is privately licensed: no raw records in git, public endpoints, replication packages or logs.
5. Hypotheses, variable definitions, PIT rules, baselines, splits and significance plan are frozen in
   `docs/RESEARCH_DESIGN.md` and `docs/PIT_PROTOCOL.md` before interpreting results. Prediction ≠ causation.
6. Every claim traces to a saved table/figure/log/test. No fabricated statistics or references.
7. Phases with gates; `PROGRESS.md`, `DECISIONS.md`, `DATA_AUDIT.md`, `LIMITATIONS.md` are kept current.
8. English everywhere; LaTeX article compiled with `latexmk` (`paper/`).

## Where things are
| Item | Location |
|---|---|
| Design, PIT rules, novelty | `docs/RESEARCH_DESIGN.md`, `docs/PIT_PROTOCOL.md`, `docs/NOVELTY_MEMO.md` |
| Data audit, limitations, decisions, progress | root `*.md` files |
| Code | `src/wp39/` (client, provenance, calendar, instruments, PIT fundamentals, corporate actions, ingest, features, labels, samples, splits, models, inference, portfolio, robustness, figures, pipeline) |
| Pipeline | `scripts/00_…09_` in order; `scripts/01a_extract_node_tables.sh` runs on M3U96a |
| Tests | `tests/` (`pytest`; live API tests need `WP39_LIVE=1`) |
| Artifacts | `artifacts/manifests` (hashes, versions), `artifacts/evaluation`, `artifacts/logs`, `results/`, `figures/` |
| Paper | `paper/main.tex` + `sections/` + generated `tables/`, `figures/` |

## How to run (compute node M3U96a, API on localhost)
```bash
rsync -a --exclude .venv --exclude artifacts/logs ~/Desktop/UQO/Recherche/Recherche-UQO/finance/invisible-balance-sheet/ M3U96a:~/wp39_uqo/
ssh M3U96a 'cd ~/wp39_uqo && uv venv -p 3.12 .venv && uv pip install -e ".[dev]" && export FINDATA_BASE_URL=http://127.0.0.1:8600/api/v1 && \
  bash scripts/01a_extract_node_tables.sh && for s in 00 01 02 03 04 05 06 07 08; do .venv/bin/python scripts/${s}_*.py; done'
```
Then `rsync` `results/ figures/ artifacts/ paper/tables paper/figures` back and `cd paper && make`.