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

REPORT_GUIDE.md

@@ -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.

runtime/refactor_baseline_v1.yaml

@@ -1,7 +1,7 @@
 {
   "formula_id": "AUDIT_REPOSITORY_ENTROPY_V2",
   "gate": "PASS",
-  "total_file_count": 1654,
+  "total_file_count": 1655,
   "package_script_count": 16,
   "temp_json_count": 116,
   "budget": {
@@ -15,5 +15,5 @@
       "keep package scripts within release envelope"
     ]
   },
-  "source_zip_sha256": "9e236e9160fc5a55b90e45e7744bc19e3721a1c698bfebacea292b2ce326f3ef"
+  "source_zip_sha256": "811e107e4111b1f21f337a5f09670153c2287a90daeafa053fb3b534fec1939c"
 }

src/quant_engine/prepare_upload_zip.py

@@ -21,6 +21,7 @@ RUNTIME_PROFILE = ROOT / "Temp" / "pipeline_runtime_profile_v1.json"
 UPLOAD_KEEP_FILES = {
     "AGENTS.md",
     "README.md",
+    "REPORT_GUIDE.md",
     "package.json",
     "RetirementAssetPortfolio.yaml",
     "RetirementAssetPortfolioReportTemplate.yaml",