zandy700/Ultimate-Tracker

What it is

Ultimate-Tracker (Supply Chain Shock Map) is a research project about how news-driven supply-chain shocks might move S&P 500 stock returns. It combines a Python event-study engine, a small SEC-derived supply graph, a bounded shock-propagation model, and an append-only hash-chained prediction ledger. The 88-event backtest spans March 2021 to November 2, 2026. A separate mobile-first UI shell demonstrates the watchlist and briefing experience using seeded sample data only — it is not a live forecast feed README.

The intended audience is researchers and developers interested in event studies, supply-chain relationships, and reproducible forecasting ledgers, not retail users looking for trade signals. The authors state directly that the work does not establish a tradable edge and is not financial advice README.

Quick start

The two halves are separate. The UI is served as static files:

python -m http.server 8000 --directory web

Open the local server, enter comma-separated tickers to build a watchlist stored only in this browser, or load AAPL, META, NVDA, and TSLA with the demo seed.

For the research engine, prepare Python 3.11+ and a checkout clone, then:

pip install -e '.[dev]'
python -m scsm ingest --offline
python -m scsm propagate
python -m scsm backtest
python -m scsm ledger verify

Run from the checkout so cached data and vendored sources resolve. A fresh ingest may return no new observations due to rate limits or unmatched headlines README.

Scope and constraints

The shipped graph is deliberately small: 12 nodes and 10 reviewed edges from 14 primary 2021 SEC filings. It is not a current or complete map of the S&P 500. Filings dated after an event are excluded from its scenario, and ambiguous matches are dropped README. Severity, decay, and the 5 percentage-point base shock are modeling choices, not estimated returns. The reported event study uses a market model estimated on -250..-11 trading days and CAR windows of +1/+5/+20 days. Results show direct signs near 64% at +1 with magnitude errors worse than zero, and upstream results consistent with a coin flip; the authors explicitly report no validated supply-chain propagation edge and caution about a hand-selected, Apple-heavy sample README.

The ledger lives in ledger/predictions.jsonl and uses RFC 8785 canonical JSON with SHA-256 hash links; verification runs via python -m scsm ledger verify. A hash chain alone cannot prove independent timestamps or prevent a full rewrite, so the README recommends retaining a trusted head hash or archived commit README. Daily automation runs through the ledger workflow and CI through the CI workflow; GitHub Actions must be enabled with write permission for repository contents. The project is MIT-licensed, with vendored code and licenses from five upstream repositories preserved in THIRD_PARTY_LICENSES and NOTICE.

HotRepo's take

The project entered the JavaScript new list on 2026-11-11 with 48 stars gained in the prior 24 hours, and its sampled curve had moved from 170 to 224 stars between 2026-11-10 and 2026-11-11. No daily-rank record is available for it. That attention arrives while the repository's own README is unusually candid about the absence of a validated edge and the limits of the 88-event backtest. Readers should treat this as a research toolkit and demonstration of event-study discipline, not an investable signal. The gap between the observed attention and the authors' own negative results is the useful thing to note.