feat(release): add REPORT_GUIDE.md for structured LLM analysis

2026-06-14 13:27:45 +09:00
parent 904b7c42a4
commit b129deb63f
3 changed files with 56 additions and 2 deletions
@@ -0,0 +1,53 @@
+# Quant Investment Engine - Analysis & Reporting Guide
+
+This document is the authoritative guide for LLMs analyzing the packaged data feed and generating operational/investment reports. It defines the mapping of data files, metric interpretations, and hard reporting rules.
+
+---
+
+## 1. Directory & File Mapping
+
+When the zip package is unpacked, the directory structure is organized as follows. Use these files to verify numbers and trace decisions:
+
+* **`AGENTS.md`**: The overall constitution and index of governance rules.
+* **`README.md`**: Project setup and script description.
+* **`REPORT_GUIDE.md`**: This guideline document.
+* **`GatherTradingData.json`**: The raw source data from GAS containing market history, macro factors, and account snapshots.
+* **`spec/`**: Contains the source of truth for investment formulas, exit policies, scoring rules, and contract specifications.
+  * `spec/13_formula_registry.yaml`: Authority for all formula IDs, inputs, and thresholds.
+  * `spec/12_field_dictionary.yaml`: Definition of keys and expected value shapes.
+  * `spec/30_completion_criteria_contract.yaml`: Definition of completion and quality gates.
+* **`governance/rules/`**: Detailed policy constraints.
+  * `governance/rules/00_core_locks.yaml`: Strict rules preventing value invention.
+  * `governance/rules/02_portfolio_policy.yaml`: Cash floor and rebalance rules.
+  * `governance/rules/04_reporting_contract.yaml`: Narrative constraints and provenance requirements.
+* **`Temp/`**: Active pipeline outputs and decision packets.
+  * `Temp/final_decision_packet_active.json`: The authoritative source of execution verdicts, quantities, and prices.
+  * `Temp/horizon_rebalance_plan_v1.json`: Output of the portfolio rebalance model containing limit violations and waterfall trim plans.
+  * `Temp/factor_lifecycle_completeness_v1.json`: Match result between factor registry specs and actual data availability.
+  * `Temp/number_provenance_ledger_v4.json`: Key-value registry mapping every output number to its exact execution step/file source.
+
+---
+
+## 2. Key Data Interpretations
+
+### A. Horizon Rebalance Plan (`horizon_rebalance_plan_v1.json`)
+* **Excess Pct & Reduction**: Calculated as `current_pct` minus `cap_pct`. If positive, a reduction is required.
+* **Trim Action Waterfall**:
+  1. `FULL_TRIM`: Ordered for positions with `verdict: SELL` first, sorted by lowest effective confidence and highest weight.
+  2. `PARTIAL_TRIM`: Applied to other positions if `FULL_TRIM` on sell candidates cannot cover the required reduction.
+  3. `BLOCKED`: Positions that cannot be sold due to trading locks (e.g. min holding periods) are marked as blocked and shadow-recorded.
+* **Gate Status**: If the estimated post-plan exposure still exceeds the cap (due to physical holding constraints), the gate is correctly reported as `FAIL`.
+
+### B. Factor Lifecycle Completeness (`factor_lifecycle_completeness_v1.json`)
+* **`violations`**: Array of factors that are marked as `shadow` or `active` in specifications but lack required data inputs in reality. Must be empty (`[]`) for `gate: PASS`.
+* **`shadow_ready_candidates`**: List of draft factors whose required fields are 100% present in the live data feed (`coverage_pct: 100.0`), making them eligible for promotion to shadow.
+
+---
+
+## 3. Strict Reporting Rules (No-Hallucination Constraints)
+
+1. **Explicit Provenance**: Every number presented in the narrative report must carry an explicit origin tag matching `number_provenance_ledger_v4.json` or its respective source file (e.g., `[source: final_decision_packet_active.json:total_asset_krw]`).
+2. **No Value Invention**: Never calculate, average, or extrapolate prices, target/stop levels, or score metrics inside the narrative. Use copy-only rendering from the JSON packets.
+3. **Portfolio Health First**: The top section of any report must clearly state the overall portfolio health, active gate statuses (PASS/FAIL), and any blocked assets or critical warnings.
+4. **Transparency of Blocked Positions**: Even if a stock or order is blocked, all computed parameters (stop price, target price, priority scores) must remain visible in the shadow ledger. Do not omit or hide data for blocked candidates.
+5. **No Narrative Mitigation**: Do not soften hard gate failures (e.g., "The limit was slightly exceeded, but it is acceptable..."). A gate failure must be described as a failure.