QuantEngineByItz/GEMINI.md

Quant Investment Engine - Project Guidelines

Core Mandate: Separation of Concerns

To ensure deterministic results and maintain clear architectural boundaries, the project strictly enforces the following separation of concerns:

1. Data Collection (GAS): All factor collection, raw data harvesting (Naver Finance, Yahoo Finance, etc.), and initial normalization happen in the Google Apps Script (.gs) layer.
2. Engine Processing & Decision (Python): Data extraction, complex processing, alpha signal analysis, risk management, and final decision-making are strictly performed by the Quant Investment Engine in Python.
   • Supplemental Collection: For advanced metrics (Beta, 52W High, etc.) missing in GAS, Python scripts (e.g., tools/ingest_fundamental_raw.py) may supplement the data feed.

Rule: No business logic, decision-making, or portfolio sizing logic should be added to the .gs files. They serve as an adapter layer to supply clean data to the Python engine.

Roadmap Task Completion Workflow

When a roadmap task (WBS) is completed:

1. Data Verification: Must prove success using actual data (e.g., JSON outputs, log results).
2. Set Completion: Once verified, perform a "Set" of:
   • git commit: With a descriptive message including the WBS ID.
   • git push: To the remote repository.
   • PR Creation: Notify completion and prepare for PR (using available CLI tools or manual confirmation).

File Mapping Clarification (WBS-2.1)

The relationship is GAS (Primary) → Python (Supplement/Engine).

• src/gas/collection/gdc_01_fetch_fundamentals.gs is the primary feeder.
• tools/ingest_fundamental_raw.py is the supplemental collector and processor.