Add horizon scoring and market confirmation

Author: Pigbibi

.github/workflows/monthly_advisory_review.yml

@@ -32,6 +32,11 @@ on:
         required: false
         default: "data/output/theme_momentum_snapshot.json"
         type: string
+      market_confirmation_path:
+        description: "Optional market confirmation CSV path inside advisor repository. Empty disables this input."
+        required: false
+        default: ""
+        type: string
   schedule:
     - cron: "20 13 1 * *"
 
@@ -68,6 +73,7 @@ jobs:
           POLITICAL_WATCHLIST_PATH: ${{ github.event.inputs.political_watchlist_path || 'data/live/political_watchlist.csv' }}
           AI_SIGNAL_PATH: ${{ github.event.inputs.ai_signal_path || 'data/output/latest_signal.json' }}
           THEME_MOMENTUM_PATH: ${{ github.event.inputs.theme_momentum_path || 'data/output/theme_momentum_snapshot.json' }}
+          MARKET_CONFIRMATION_PATH: ${{ github.event.inputs.market_confirmation_path || '' }}
         run: |
           set -euo pipefail
           AS_OF="${INPUT_AS_OF:-$(date -u +%F)}"
@@ -76,13 +82,18 @@ jobs:
           if [ -n "${THEME_MOMENTUM_PATH}" ] && [ -f "../research-signal-context/${THEME_MOMENTUM_PATH}" ]; then
             THEME_ARGS=(--theme-momentum "../research-signal-context/${THEME_MOMENTUM_PATH}")
           fi
+          MARKET_ARGS=()
+          if [ -n "${MARKET_CONFIRMATION_PATH}" ] && [ -f "${MARKET_CONFIRMATION_PATH}" ]; then
+            MARKET_ARGS=(--market-confirmation "${MARKET_CONFIRMATION_PATH}")
+          fi
           python scripts/build_advisory_report.py \
             --as-of "${AS_OF}" \
             --cadence monthly \
             --political-events "../political-events/${POLITICAL_EVENTS_PATH}" \
             --political-watchlist "../political-events/${POLITICAL_WATCHLIST_PATH}" \
             --ai-signal "../research-signal-context/${AI_SIGNAL_PATH}" \
             "${THEME_ARGS[@]}" \
+            "${MARKET_ARGS[@]}" \
             --output-json "data/output/monthly_advisory_review/advisory_report_${AS_OF}.json" \
             --output-md "data/output/monthly_advisory_review/advisory_report_${AS_OF}.md"
           REVIEW_ARGS=(

.github/workflows/publish_advisory_site.yml

@@ -32,6 +32,11 @@ on:
         required: false
         default: "data/output/theme_momentum_snapshot.json"
         type: string
+      market_confirmation_path:
+        description: "Optional market confirmation CSV path inside advisor repository. Empty disables this input."
+        required: false
+        default: ""
+        type: string
   schedule:
     - cron: "0 13 * * 6"
 
@@ -77,6 +82,7 @@ jobs:
           POLITICAL_WATCHLIST_PATH: ${{ github.event.inputs.political_watchlist_path || 'data/live/political_watchlist.csv' }}
           AI_SIGNAL_PATH: ${{ github.event.inputs.ai_signal_path || 'data/output/latest_signal.json' }}
           THEME_MOMENTUM_PATH: ${{ github.event.inputs.theme_momentum_path || 'data/output/theme_momentum_snapshot.json' }}
+          MARKET_CONFIRMATION_PATH: ${{ github.event.inputs.market_confirmation_path || '' }}
         run: |
           set -euo pipefail
           AS_OF="${INPUT_AS_OF:-$(date -u +%F)}"
@@ -85,13 +91,18 @@ jobs:
           if [ -n "${THEME_MOMENTUM_PATH}" ] && [ -f "../research-signal-context/${THEME_MOMENTUM_PATH}" ]; then
             THEME_ARGS=(--theme-momentum "../research-signal-context/${THEME_MOMENTUM_PATH}")
           fi
+          MARKET_ARGS=()
+          if [ -n "${MARKET_CONFIRMATION_PATH}" ] && [ -f "${MARKET_CONFIRMATION_PATH}" ]; then
+            MARKET_ARGS=(--market-confirmation "${MARKET_CONFIRMATION_PATH}")
+          fi
           python scripts/build_advisory_report.py \
             --as-of "${AS_OF}" \
             --cadence weekly \
             --political-events "../political-events/${POLITICAL_EVENTS_PATH}" \
             --political-watchlist "../political-events/${POLITICAL_WATCHLIST_PATH}" \
             --ai-signal "../research-signal-context/${AI_SIGNAL_PATH}" \
             "${THEME_ARGS[@]}" \
+            "${MARKET_ARGS[@]}" \
             --output-json "data/output/published/advisory_report_${AS_OF}.json" \
             --output-md "data/output/published/advisory_report_${AS_OF}.md"
           python scripts/publish_advisory_site.py \

.github/workflows/weekly_advisory_review.yml

@@ -27,6 +27,11 @@ on:
         required: false
         default: "data/output/theme_momentum_snapshot.json"
         type: string
+      market_confirmation_path:
+        description: "Optional market confirmation CSV path inside advisor repository. Empty disables this input."
+        required: false
+        default: ""
+        type: string
   schedule:
     - cron: "30 12 * * 6"
 
@@ -62,6 +67,7 @@ jobs:
           POLITICAL_WATCHLIST_PATH: ${{ github.event.inputs.political_watchlist_path || 'data/live/political_watchlist.csv' }}
           AI_SIGNAL_PATH: ${{ github.event.inputs.ai_signal_path || 'data/output/latest_signal.json' }}
           THEME_MOMENTUM_PATH: ${{ github.event.inputs.theme_momentum_path || 'data/output/theme_momentum_snapshot.json' }}
+          MARKET_CONFIRMATION_PATH: ${{ github.event.inputs.market_confirmation_path || '' }}
         run: |
           set -euo pipefail
           AS_OF="${INPUT_AS_OF:-$(date -u +%F)}"
@@ -70,13 +76,18 @@ jobs:
           if [ -n "${THEME_MOMENTUM_PATH}" ] && [ -f "../research-signal-context/${THEME_MOMENTUM_PATH}" ]; then
             THEME_ARGS=(--theme-momentum "../research-signal-context/${THEME_MOMENTUM_PATH}")
           fi
+          MARKET_ARGS=()
+          if [ -n "${MARKET_CONFIRMATION_PATH}" ] && [ -f "${MARKET_CONFIRMATION_PATH}" ]; then
+            MARKET_ARGS=(--market-confirmation "${MARKET_CONFIRMATION_PATH}")
+          fi
           python scripts/build_advisory_report.py \
             --as-of "${AS_OF}" \
             --cadence weekly \
             --political-events "../political-events/${POLITICAL_EVENTS_PATH}" \
             --political-watchlist "../political-events/${POLITICAL_WATCHLIST_PATH}" \
             --ai-signal "../research-signal-context/${AI_SIGNAL_PATH}" \
             "${THEME_ARGS[@]}" \
+            "${MARKET_ARGS[@]}" \
             --output-json "data/output/weekly_advisory_review/advisory_report_${AS_OF}.json" \
             --output-md "data/output/weekly_advisory_review/advisory_report_${AS_OF}.md"
       - name: Upload model recommendation artifact

README.md

@@ -45,7 +45,7 @@ Advisor is the final composition layer. Source ownership by horizon is:
 - Medium term (`2-12 weeks`): `theme_momentum_snapshot.json` from `ResearchSignalContextPipelines`, now explicitly marked as `medium_horizon_theme_context`.
 - Long term (`1-3 years`): `latest_signal.json` / `signal_history/*.json` from `ResearchSignalContextPipelines` as AI shadow context.
 
-Final recommendations are still deterministic Advisor outputs. The signal context repository does not directly produce short-term recommendations or replace the final decision engine.
+Final recommendations are still deterministic Advisor outputs. The signal context repository does not directly produce short-term recommendations or replace the final decision engine. Advisor now records separate short/medium/long horizon scores for each final pick; public pages keep the simpler final recommendation layout.
 
 ## Boundary
 
@@ -244,14 +244,13 @@ into executable strategy targets.
 
 ## Source Mode
 
-Reports built from `examples/` inputs are marked `source_mode=fixture` and the
-individual HTML report displays a fixture warning. Scheduled weekly/monthly and
-Pages workflows now default to `data/live/*` inputs from
-`PoliticalEventTrackingResearch`, so published reports should be
-`source_mode=operator_supplied` and should not show the fixture warning.
+Reports built from `examples/` inputs are still marked `source_mode=fixture` in
+JSON, but public HTML/RSS/Telegram output no longer displays fixture or source-mode
+badges. Scheduled weekly/monthly and Pages workflows default to `data/live/*`
+inputs from `PoliticalEventTrackingResearch`, so published reports should be
+`source_mode=operator_supplied` in the audit artifact.
 
-`source_mode` remains in the JSON contract for auditability, but the public
-index, RSS, and Telegram summaries do not expose that internal field.
+`source_mode` remains in the JSON contract for auditability only.
 
 ## Regulatory Boundary
 
@@ -280,16 +279,19 @@ python scripts/build_advisory_report.py \
   --political-watchlist examples/political_watchlist.example.csv \
   --ai-signal examples/research_signal_context.example.json \
   --theme-momentum examples/theme_momentum_snapshot.example.json \
+  --market-confirmation examples/market_confirmation.example.csv \
   --output-json data/output/advisory_report.example.json \
   --output-md data/output/advisory_report.example.md
 ```
 
 Theme momentum is explanation-first context: it highlights strong themes and
 creates `theme_first_candidates[]` for JSON/Markdown audit material. The public
 HTML, RSS, and Telegram outputs stay focused on final recommendations only, so
-theme candidates are not mistaken for a buy list. Theme momentum does not change
-recommendation ratings, scores, allocations, or execution policy. Workflows skip
-this context when the snapshot file is absent.
+theme candidates are not mistaken for a buy list. The base `recommendations[]`
+rating still comes from event/watchlist/AI evidence; `final_decisions` can use
+medium-horizon theme momentum plus optional market confirmation to rank the final
+public list. It never changes allocation or execution policy. Workflows skip this
+context when the snapshot file is absent.
 
 Yahoo chart downloads are only a temporary fallback.  Do not rely on random free
 proxy pools for the stable pipeline; prefer audited price snapshots, cache files,

README.zh-CN.md

@@ -33,7 +33,7 @@ Advisor 是最终合成层，三个周期的输入分工如下：
 - 中线（2-12 周）：`ResearchSignalContextPipelines` 的 `theme_momentum_snapshot.json`，现在明确标记为 `medium_horizon_theme_context`。
 - 长线（1-3 年）：`ResearchSignalContextPipelines` 的 `latest_signal.json` / `signal_history/*.json`，作为 AI shadow 背景。
 
-最终推荐仍由本仓库确定性合成。信号上下文仓库不直接输出短线推荐，也不替代本仓库的最终决策。
+最终推荐仍由本仓库确定性合成。信号上下文仓库不直接输出短线推荐，也不替代本仓库的最终决策。本仓库会为最终推荐记录短/中/长线独立评分，但公开页面仍保持简洁，只展示最终列表、背景、理由和风险。
 
 ## 当前 MVP
 
@@ -77,9 +77,9 @@ manifest 会记录 JSON/Markdown 的 SHA256、`as_of`、cadence、来源 artifac
 
 ## 来源模式
 
-如果报告输入来自 `examples/`，输出会标记 `source_mode=fixture`，单篇 HTML 报告会显示 fixture 警告，避免把合成样例误认为真实推荐。周度/月度和 Pages 发布 workflow 现在默认读取 `PoliticalEventTrackingResearch` 的 `data/live/*`，因此正式发布应为 `source_mode=operator_supplied`，页面不应出现 fixture 警告。
+如果报告输入来自 `examples/`，JSON 里仍会标记 `source_mode=fixture`，但公开 HTML/RSS/Telegram 不再显示 fixture 或来源模式标签。周度/月度和 Pages 发布 workflow 默认读取 `PoliticalEventTrackingResearch` 的 `data/live/*`，因此正式发布的审计 artifact 应为 `source_mode=operator_supplied`。
 
-`source_mode` 继续保留在 JSON 契约里用于审计，但公开首页、RSS 和 Telegram 摘要不再展示这个内部字段。
+`source_mode` 继续保留在 JSON 契约里用于审计，不作为公开页面文案。
 
 ## 边界
 
@@ -190,13 +190,14 @@ python scripts/build_advisory_report.py \
   --political-watchlist examples/political_watchlist.example.csv \
   --ai-signal examples/research_signal_context.example.json \
   --theme-momentum examples/theme_momentum_snapshot.example.json \
+  --market-confirmation examples/market_confirmation.example.csv \
   --output-json data/output/advisory_report.example.json \
   --output-md data/output/advisory_report.example.md
 ```
 
-主题动量会生成 `theme_first_candidates[]`，但它现在只作为 JSON/Markdown 中的解释和审计材料。公开页面、RSS 和 Telegram 摘要默认只显示最终推荐，避免把候选池误读为买入清单。
+主题动量会生成 `theme_first_candidates[]`，作为 JSON/Markdown 中的解释和审计材料。公开页面、RSS 和 Telegram 摘要默认只显示最终推荐，避免把候选池误读为买入清单。
 
-候选池仍会保留行业/主题背景、入选原因、事件确认状态和主要风险；但它不直接改变推荐评级、分数、仓位或执行状态。
+基础 `recommendations[]` 评级仍来自事件、watchlist 和 AI 背景；`final_decisions` 会用中线主题动量和可选市场确认对最终公开列表排序。候选池不改变仓位或执行状态。
 线上 workflow 如果找不到 `data/output/theme_momentum_snapshot.json`，会自动跳过这个展示区块。
 
 Yahoo chart 下载只作为临时 fallback。不要把随机免费代理 IP 池作为稳定生产方案；它有稳定性、数据污染、封禁、隐私和合规风险。更稳的做法是使用本组织已有价格快照、缓存文件，或可审计的自有代理/数据源。

docs/advisory_contract.md

@@ -15,6 +15,7 @@ source_artifacts: object
 summary: object
 recommendations: list
 theme_first_candidates: list, optional
+final_decisions: object, optional
 policy: object
 ```
 
@@ -114,7 +115,8 @@ Allowed strategy styles:
 - `mixed_research`
 
 The contract intentionally rejects account-action fields such as `target_weight`,
-`target_quantity`, `shares`, `order_type`, `broker`, and `account_id`.
+`target_quantity`, `shares`, `order_type`, `broker`, and `account_id`. The same
+restriction applies to final picks and theme-first candidates.
 
 ## Theme-first Candidate
 
@@ -144,6 +146,44 @@ reasons
 risk_notes
 ```
 
+## Final Decisions
+
+`final_decisions` is the public recommendation layer. It keeps the simple public
+list while preserving audit details in JSON:
+
+```text
+recommendations[]
+watchlist[]
+horizon_buckets.short | medium | long
+horizon_rankings.short | medium | long
+```
+
+Each final pick may carry:
+
+```text
+combined_score
+source_score
+momentum_score
+medium_context_score
+long_context_score
+horizon_scores.short|medium|long
+supporting_context.short|medium|long
+selection_trace[]
+business_summary
+prospect_summary
+why_selected[]
+risk_summary
+```
+
+Scoring intent by horizon:
+
+- short: event/source evidence first, optionally confirmed by recent market behavior;
+- medium: theme momentum and individual momentum first, with event/news and optional market confirmation as supporting inputs;
+- long: saved AI shadow context and durable theme context first, with event/news as supporting evidence.
+
+These fields are audit metadata. Public HTML/RSS/Telegram renderers still show
+only final recommendations, stock background, recommendation reasons, and risks.
+
 ## Artifact Manifest
 
 Every CLI-generated JSON report also writes:
@@ -176,7 +216,7 @@ generated_at
 
 `summary.source_mode` is:
 
-- `fixture`: one or more inputs came from `examples/`; the individual HTML report should show a fixture warning and scheduled publication should avoid this mode.
+- `fixture`: one or more inputs came from `examples/`; scheduled publication should avoid this mode.
 - `operator_supplied`: inputs did not come from fixture paths. This is the expected mode for scheduled public publication.
 
-`summary.data_quality_warnings` carries source-mode warnings for renderers. Public index, RSS, and Telegram summaries intentionally do not display `source_mode`; it remains an audit field in JSON.
+`summary.data_quality_warnings` carries source-mode warnings for audit tooling. Public HTML, index, RSS, and Telegram summaries intentionally do not display `source_mode`; it remains an audit field in JSON.

docs/data_factor_roadmap.md

@@ -58,7 +58,7 @@ must not directly generate orders, target weights, or account actions.
 
 Owns final non-personalized model recommendations:
 
-- inputs: event CSV, watchlist CSV, saved AI shadow JSON, optional theme momentum;
+- inputs: event CSV, watchlist CSV, saved AI shadow JSON, optional theme momentum, optional market confirmation CSV;
 - outputs: JSON, Markdown, HTML, RSS, and optional Telegram summary;
 - contract blocks orders, target weights, target share quantities, broker routing,
   account information, and suitability claims.
@@ -89,7 +89,9 @@ Priority order:
    releases, SEC/EDGAR, company IR, policy/procurement sources, alias maps, and
    source registry coverage.
 3. Add optional market confirmation CSVs while keeping report generation working
-   when the data is absent.
+   when the data is absent. The CSV should carry point-in-time returns, relative
+   returns, abnormal volume, drawdown, and volatility; it should not contain
+   target weights or trade instructions.
 4. Add event review inputs for 1/5/20/60 trading-day follow-up.
 5. Add fundamentals/valuation snapshots for risk explanation, not execution.
 6. Only then consider read-only references from existing snapshot repositories.

docs/data_factor_roadmap.zh-CN.md

@@ -53,7 +53,7 @@
 
 当前负责最终非个性化模型推荐：
 
-- 输入：事件 CSV、watchlist CSV、AI shadow JSON。
+- 输入：事件 CSV、watchlist CSV、AI shadow JSON、可选主题动量、可选市场确认 CSV。
 - 输出：`model_recommendations` JSON、Markdown、HTML、RSS。
 - 推荐字段：推荐等级、推荐层级、适合周期、周期说明、来源可信度、理由、风险、复核清单。
 - 合约禁止：目标仓位、目标股数、订单、券商、账户信息。
@@ -178,8 +178,8 @@ Crypto 可作为跨资产风险情绪参考，但暂时不应混入 US equity 
    - X / Truth Social / 社区内容暂不作为稳定默认源。
 
 3. 在 `QuantAdvisorResearch` 增加 market confirmation 输入，但保持可选：
-   - `symbol,as_of,close,volume,benchmark_close,sector_etf_close`。
-   - 如果没有市场确认数据，报告继续生成，但降级提示数据缺口。
+   - 当前 CSV 字段为 `symbol,as_of,return_5d,return_20d,return_63d,relative_return_20d,relative_return_63d,volume_zscore,drawdown_63d,volatility_21d`。
+   - 如果没有市场确认数据，报告继续生成；该输入只影响 `final_decisions` 的短/中/长线审计评分，不包含目标仓位或交易指令。
 
 4. 增加事件复盘结果输入：
    - `event_id,symbol,event_date,window,absolute_return,benchmark_relative_return`。

docs/system_design.md

@@ -94,14 +94,17 @@ The public HTML/RSS/Telegram outputs should stay direct:
   and risks;
 - hide internal tags such as `source_mode`, mode labels, audience labels, and
   repository names;
-- keep `theme_first_candidates[]` in JSON/Markdown as explanation and audit
-  material, not as a public buy list;
+- keep `theme_first_candidates[]`, `horizon_scores`, and `selection_trace` in
+  JSON/Markdown as explanation and audit material, not as public page clutter;
+- use theme momentum and optional market confirmation only inside deterministic
+  `final_decisions` ranking;
 - never show orders, target weights, target share quantities, account suitability,
   or account-specific allocation advice.
 
 ## Fixture vs Live Inputs
 
 Reports built from `examples/` are `source_mode=fixture` and are suitable for
-local tests only. Scheduled workflows default to `data/live/*` inputs from
-`PoliticalEventTrackingResearch`, so published reports should be
-`source_mode=operator_supplied` and should not show fixture warnings.
+local tests only. The public renderers no longer display fixture/source-mode
+badges. Scheduled workflows default to `data/live/*` inputs from
+`PoliticalEventTrackingResearch`, so published audit artifacts should be
+`source_mode=operator_supplied`.