Improve monthly review audit controls (#48)

* Improve monthly review audit controls

* Fix release status summary freshness test

Author: Pigbibi

README.md

@@ -525,7 +525,7 @@ Outputs:
 
 Behavior:
 
-- uses only upstream monthly build outputs
+- requires upstream monthly build outputs, including the same-cycle shadow build summary and shadow candidate track summary
 - summarizes official baseline release status, publish manifest status, and shadow track coverage
 - emits warnings when monthly artifacts do not align on `as_of_date`, `version`, or `mode`
 - produces a structured review prompt/checklist for manual follow-up
@@ -541,18 +541,20 @@ The AI review covers:
 - **Anomaly detection**: flags unexpected warnings, stale artifacts, validation failures, or suspicious ranking scores
 - **Downstream impact**: notes implications for BinancePlatform (the downstream execution engine), including pool changes and degradation risk
 - **Operator action items**: summarizes the checklist and adds any AI-identified follow-up items
-- **Code improvements**: if concrete, low-risk improvements are found, Claude may open a Pull Request (never auto-merged)
+- **Code improvements**: structured review output can feed the monthly optimization planner; low-risk `auto-pr-safe` tasks may become automation PRs, while sensitive selector changes remain manual-review work
 
 All analysis is posted in both English and Chinese.
 
 ### Required GitHub Secret
 
 - `ANTHROPIC_API_KEY`: Anthropic API key for Claude Code Action
+- `OPENAI_API_KEY`: OpenAI API key for the secondary monthly review
 
 Setup:
 
 ```bash
 gh secret set ANTHROPIC_API_KEY --body "sk-ant-..."
+gh secret set OPENAI_API_KEY --body "sk-..."
 ```
 
 The AI review workflow runs on `ubuntu-latest` (no self-hosted runner required) and costs approximately $0.01-0.05 per monthly run.

docs/operator_runbook.md

@@ -62,7 +62,7 @@ This repository owns the monthly reporting and publish-status summary layer for
 Operator-facing summary entrypoints:
 
 - `scripts/run_release_status_summary.py` for the canonical release-status summary built from the current official artifacts
-- `scripts/run_monthly_review_briefing.py` for the monthly review package; it can run on official release artifacts alone and adds shadow coverage when available
+- `scripts/run_monthly_review_briefing.py` for the monthly review package; it requires same-cycle shadow outputs so review evidence always includes official and challenger coverage
 - `scripts/run_monthly_build_telegram.py` for the optional short Telegram health notification or local preview text
 - `scripts/run_monthly_report_bundle.py` for the standard monthly report bundle used by Actions artifacts and AI review handoff
 - `scripts/write_release_heartbeat.py` for the lightweight logs-branch heartbeat record
@@ -106,6 +106,11 @@ Boundary rules:
 .venv/bin/python scripts/run_release_status_summary.py
 ```
 
+Before the review package is generated, confirm the monthly shadow build has produced both
+`data/output/monthly_shadow_build_summary.json` and
+`data/output/shadow_candidate_tracks/track_summary.csv`. The hosted monthly publish
+workflow runs this shadow build automatically before the review step.
+
 6. Generate the monthly review package:
 
 ```bash

scripts/prepare_auto_optimization_pr.py

@@ -187,8 +187,8 @@ def _is_completed_low_risk_task(action: dict[str, Any], repo_root: Path) -> bool
     ):
         monthly_report = _read_text(repo_root / "scripts" / "run_monthly_report_bundle.py")
         return (
-            "No explicit gating or no-trade reasons were recorded this month." in monthly_report
-            and "gating_summary" in monthly_report
+            "## Zero-Trade Diagnostics" in monthly_report
+            and "by_category_and_gate" in monthly_report
         )
 
     return False

scripts/render_monthly_ai_review.py

@@ -77,7 +77,12 @@ def build_full_review_markdown(
     primary_title: str,
     secondary_review_payload: dict[str, Any] | None = None,
 ) -> str:
-    lines = [f"## {primary_title}", "", primary_review_text.strip()]
+    normalized_primary_review = primary_review_text.strip()
+    duplicate_title = f"## {primary_title}"
+    if normalized_primary_review.startswith(duplicate_title):
+        normalized_primary_review = normalized_primary_review[len(duplicate_title) :].lstrip()
+
+    lines = [f"## {primary_title}", "", normalized_primary_review]
     if secondary_review_payload is not None:
         lines.extend(["", "---", "", render_secondary_review_markdown(secondary_review_payload)])
     return "\n".join(lines).strip() + "\n"

scripts/run_monthly_review_briefing.py

@@ -162,6 +162,22 @@ def derive_warnings(inputs: dict[str, Any]) -> list[str]:
     return warnings
 
 
+def require_shadow_outputs(inputs: dict[str, Any]) -> None:
+    availability = inputs["availability"]
+    missing_items: list[str] = []
+    if not availability["monthly_shadow_build_summary"]:
+        missing_items.append("monthly_shadow_build_summary.json")
+    if not availability["track_summary"]:
+        missing_items.append("shadow_candidate_tracks/track_summary.csv")
+
+    if missing_items:
+        missing_text = ", ".join(missing_items)
+        raise RuntimeError(
+            "monthly shadow build outputs are required before generating the monthly review package: "
+            f"{missing_text}"
+        )
+
+
 def build_review_questions() -> list[str]:
     return [
         "Does the official baseline publish chain look internally consistent for this month?",
@@ -342,6 +358,7 @@ def main() -> None:
     args = parse_args()
     output_dir = Path(args.output_dir).resolve()
     inputs = build_review_inputs(output_dir)
+    require_shadow_outputs(inputs)
     payload = build_review_payload(inputs)
     outputs = write_outputs(payload, output_dir)
 

scripts/run_release_status_summary.py

@@ -80,6 +80,7 @@ def build_release_status_payload(
     max_age_days: int = 45,
     require_freshness: bool = True,
     ranking_preview_size: int = 5,
+    reference_date: Any = None,
 ) -> dict[str, Any]:
     root = Path(output_dir)
     universe = load_json(root / "latest_universe.json")
@@ -94,6 +95,7 @@ def build_release_status_payload(
         expected_source_project=live_pool.get("source_project"),
         expected_pool_size=live_pool.get("pool_size"),
         max_age_days=max_age_days,
+        reference_date=reference_date,
         require_manifest=True,
         require_artifact_manifest=True,
         require_freshness=require_freshness,

tests/test_monthly_review_briefing.py

@@ -116,16 +116,12 @@ def test_build_review_payload_warns_when_track_dates_do_not_align(self) -> None:
         self.assertIn("## Warnings", review_md)
         self.assertIn("official_baseline remains the production reference", prompt_md)
 
-    def test_build_review_payload_allows_official_only_outputs(self) -> None:
+    def test_build_review_payload_requires_shadow_outputs(self) -> None:
         with tempfile.TemporaryDirectory() as tmp_dir:
             output_dir = self.write_fixture_files(Path(tmp_dir), include_shadow_outputs=False)
             inputs = MODULE.build_review_inputs(output_dir)
-            payload = MODULE.build_review_payload(inputs)
-            review_md = MODULE.render_review_markdown(payload)
-
-        self.assertEqual(payload["status"], "ok")
-        self.assertFalse(payload["shadow_analysis_available"])
-        self.assertIn("not generated in this run", review_md)
+            with self.assertRaisesRegex(RuntimeError, "monthly shadow build outputs are required"):
+                MODULE.require_shadow_outputs(inputs)
 
 
 if __name__ == "__main__":

tests/test_release_status_summary.py

@@ -162,6 +162,7 @@ def test_build_release_status_payload_reports_ok_for_consistent_release(self) ->
                 max_age_days=45,
                 require_freshness=False,
                 ranking_preview_size=3,
+                reference_date="2026-04-01",
             )
             outputs = MODULE.write_outputs(payload, output_dir)
 

tests/test_render_monthly_ai_review.py

@@ -37,7 +37,7 @@ def test_render_secondary_review_markdown_includes_actions_and_flags(self) -> No
 
     def test_build_full_review_markdown_includes_primary_and_secondary_sections(self) -> None:
         markdown = build_full_review_markdown(
-            "## English\nPrimary review",
+            "## Claude Primary Review\n\n## English\nPrimary review",
             primary_title="Claude Primary Review",
             secondary_review_payload={
                 "provider_display_name": "GPT Secondary Review",
@@ -54,6 +54,7 @@ def test_build_full_review_markdown_includes_primary_and_secondary_sections(self
         self.assertIn("## Claude Primary Review", markdown)
         self.assertIn("## Secondary Review (GPT Secondary Review)", markdown)
         self.assertIn("## English", markdown)
+        self.assertEqual(markdown.count("## Claude Primary Review"), 1)
 
 
 if __name__ == "__main__":