{
  "markdown": "# Stock Checker\n\nA bun-workspaces monorepo that screens US equities with an institutional-flow\nsignal engine, visualizes them in a web UI, and validates every strategy change\nwith a backtest.\n\n| Package | What it is |\n|---|---|\n| `packages/core` | Signal engine, backtest, and CLI (`predict` / `learn` / `optimize` / `backtest`) |\n| `apps/api` | Fastify API server (screener, ticker detail, OHLCV) — port 5101 |\n| `apps/web` | Next.js 16 screener UI (candlestick + Gaussian Channel band charts, portfolio, light/dark) — port 5100 |\n\n| Screener | Ticker detail (Gaussian Channel band) |\n|---|---|\n| ![Equity screener table with composite scores, signals, and detected chart patterns](docs/images/screener.png) | ![TSLA detail page: candlestick chart with SMA 20/50/200, Bollinger Bands, and trend-colored Gaussian Channel band](docs/images/ticker-detail.png) |\n\n## Signal philosophy\n\nThe engine follows the principles in [docs/TRADING_PRINCIPLES.md](docs/TRADING_PRINCIPLES.md):\nprice, volume, VWAP, moving averages, liquidity, relative strength, and earnings\nrevisions over oscillator soup.\n\n- **Trend regime** — Gaussian Channel (green = uptrend, red = downtrend) gates all buys.\n- **Institutional flow score** — relative strength vs SPY and the sector ETF,\n  VWAP accumulation, breakout volume, dollar-volume liquidity, earnings revisions.\n- **Strong-leader pullback entry (주도주 눌림목)** — BUY only when a name that\n  is STRONGLY outperforming both the market and its sector (`rs ≥ 0.7`) pulls\n  back below its 50-day SMA on a calm bar that closed in the bottom 20% of its\n  range (`ibs < 0.2`) with real participation. Backtested (8y incl. the 2020\n  crash and the 2022 bear, **546 tickers**, real pipeline, net of a 10bps\n  round-trip cost): **60.4% 5-day win rate / 1.28 reward-risk / N=225** vs the\n  51.3% / 1.05 ungated baseline (z≈2.6, p≈0.004), every entry year ≥ 50%.\n- **SELL = exit discipline, not a downside prediction** — distribution-day\n  SELLs are suppressed inside intact uptrends and only fire when the trend\n  itself is broken.\n- Classic indicators (RSI, Stochastic %K, Bollinger, Donchian, Williams %R,\n  MACD, ATR, volume ratio, Fear & Greed) are still computed and displayed, but\n  they season the score rather than drive it.\n- Volatility-adjusted risk levels per signal: 1.5×ATR stop loss, 2× reward\n  take profit, trailing stop that activates after a 0.5×ATR move.\n\n## Validated results\n\n8-year window (entry years 2019–2026, incl. the 2020 COVID crash and the 2022\nrate-hike bear), **546-ticker** diversified universe (large + mid + small cap,\nall 11 sectors), fixed 5-day exit, evaluated through the real pipeline, **net\nof a 10bps round-trip transaction cost** (a \"win\" = profitable after costs).\nFull context and hard-won validation rules in\n[docs/TRADING_PRINCIPLES.md](docs/TRADING_PRINCIPLES.md).\n\n| Config | WR (5d) | R/R | N | Avg ret/trade |\n|---|---|---|---|---|\n| **Shipped gate** (`rs≥0.7` + `ibs<0.2` + `scr<400` + below-50d) | **60.4%** | **1.28** | 225 | 1.08% |\n| Legacy V7 gate (`rs≥0.5`, `ibs<0.3`, `scr<380`) | 56.3% | 1.32 | 476 | 0.85% |\n| + SPY kill-switch + 200d stage (NOT shipped — hurts at scale) | 55.7% | 1.29 | 230 | 0.79% |\n| V5 institutional baseline (no quality gate) | 51.3% | 1.05 | 84,541 | 0.20% |\n\nShipped gate by entry year (WR / N): 2019 66%/41 · 2020 62%/21 · 2021 61%/33 ·\n2022 55%/40 · 2023 52%/29 · 2024 55%/22 · 2025 65%/20 · 2026 74%/19 — every\nyear ≥ 50%, both bear regimes included. Train ≤2024: 58.6% / 1.19 (N=186) ·\nholdout ≥2025: 69.2% / 2.35 (N=39). Significant vs baseline (z≈2.6, p≈0.004).\n\n**Market-cap scope.** This is a **large-cap strategy**: ~90% of gate signals\nfire on $10B+ names (the `atr%<3.5` calmness and `rs≥0.7` leadership profile\nrarely matches smaller names). On mid caps the WR edge disappears (≈52% vs a\n50.5% mid baseline, N=25 — winners run bigger but no hit-rate edge); the\nungated small-cap pullback baseline is outright negative (46% WR, −0.07%/trade).\nTrade it on liquid large caps only.\n\n**Falsification record.** On the original 122-ticker growth-heavy universe the\nsame family printed up to **71.7% WR / 1.75 R/R (N=46)** — expanding the\nuniverse 4.5× collapsed it. The 70%+ readings were small-N universe artifacts,\nnot edge (\"universe shapes conclusions\"). The SPY-Gaussian market kill-switch\nhelped at 122 tickers and consistently *hurt* at scale, so it ships as an\noptional gate param, off by default. Remaining caveats: as-of-today universe\nand cap tiers (survivorship bias), no live forward track record.\n\n## Usage\n\nTooling is managed by [mise](https://mise.jdx.dev); tasks wrap every common\noperation (run `mise tasks` to see them all).\n\n```bash\nmise install        # pin runtimes (node 24, bun)\nbun install         # install workspace deps + git pre-commit hook\nmise run dev        # API (5101) + Web (5100) dev servers in parallel\n```\n\n### Environment (optional)\n\n| Variable | Effect |\n|---|---|\n| `TIINGO_API_KEY` | Enables the [Tiingo](https://www.tiingo.com) daily-OHLCV fallback when Yahoo is rate-limited or down (free tier: 1,000 req/day). Without it, OHLCV degrades to empty on Yahoo failure. |\n| `SLACK_WEBHOOK_URL` | Slack notification for BUY/SELL opinions from `predict`. |\n\n### CLI (packages/core)\n\n```bash\n# Daily prediction for a ticker list (default command)\nmise run predict -- --ticker=TSLA,PLTR --sort=asc\n\n# Slack notification for BUY/SELL opinions (either form)\nSLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX mise run predict -- --ticker=TSLA,PLTR\nmise run predict -- --ticker=TSLA,PLTR --slack-webhook=https://hooks.slack.com/services/XXX\n\n# Strategy validation & tuning\nmise run backtest        # version comparison, goal search, SELL validation\nmise run backtest -- --cost-bps=20   # vary the round-trip cost (default 10bps)\nmise run backtest -- --quick         # stop after version comparison + gate tuning\nmise run optimize        # parameter optimizer (positional symbol, e.g. TSLA)\nmise run learn           # learn from prediction feedback\n```\n\nEach `predict` run appends rows to a monthly CSV in `packages/core/public/`\n(e.g. `stock_data_202511.csv`), tickers in alphabetical order (`--sort=desc`\nreverses).\n\n### Quality gate\n\n```bash\nmise run ci          # lint → typecheck → test → build\n```\n\n## Automation\n\n- `.github/workflows/daily-data.yml` — runs `predict` after US market close and\n  auto-commits the monthly CSV.\n- `.github/workflows/weekly-optimize.yml` — weekly parameter optimization,\n  results uploaded as a build artifact.\n",
  "bytes": 6487,
  "sha": "317ea524b349b82b9320d7dc66e44a57cd5a799921ff7b41c45c8d87b718cb17",
  "repo_slug": "gracefullight/stock-checker",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_gracefullight_stock_checker_trading_anal_8eec6169/readme"
}