Module 405 — Stakeholder sign-off: risks, escalation, and safety alignment

import os
import pandas as pd
from datetime import datetime

run_id = "2026-02-09_174500_demo"
run_dir = os.path.join("signoff_pack", run_id)
os.makedirs(run_dir, exist_ok=True)

# Example artefacts (normally read from your actual run outputs)
metrics = {
    "rmse_mean": 1.10,
    "rmse_worst_fold": 1.85,
    "stress_rmse_vol_x2": 2.70,
}
assumptions = [
    "Timestamps are monotonic and unique.",
    "Missingness per key feature < 1% per day.",
    "Model is used only for horizon h=1 day.",
    "Disable in extreme volatility regimes (vol proxy above threshold).",
]

# 1) Model card
model_card = f"""# Model card — Demo forecasting model

- **Run ID:** {run_id}
- **Date:** {datetime.now().strftime("%Y-%m-%d")}
- **Intended use:** 1-day forecasting support; baseline decision aid.
- **Primary metric:** RMSE (rolling), worst-fold RMSE.
- **Performance:** RMSE mean={metrics["rmse_mean"]}, worst fold={metrics["rmse_worst_fold"]}
- **Limitations:** Degrades under volatility shocks (stress RMSE x2={metrics["stress_rmse_vol_x2"]})
- **Monitoring:** data drift (feature z), performance drift (rolling RMSE), volatility regime.
- **Fallback:** revert to baseline or disable when red.
"""
with open(os.path.join(run_dir, "MODEL_CARD.md"), "w", encoding="utf-8") as f:
    f.write(model_card)

# 2) Assumptions page
assump_md = "# Assumptions\n\n" + "\n".join([f"- {a}" for a in assumptions]) + "\n"
with open(os.path.join(run_dir, "ASSUMPTIONS.md"), "w", encoding="utf-8") as f:
    f.write(assump_md)

# 3) Monitoring spec
monitoring_md = """# Monitoring spec (minimal)

## Data integrity (hard fail)
- duplicates, non-monotonic timestamps, missing blocks

## Data drift (amber/red)
- rolling mean z-score of key features (amber > 2, red > 3)

## Performance drift (amber/red)
- rolling RMSE vs training baseline (amber > +1σ, red > +2σ for 3 windows)

## Actions
- Amber: restrict usage + review.
- Red: disable + incident ticket + retraining decision.
"""
with open(os.path.join(run_dir, "MONITORING_SPEC.md"), "w", encoding="utf-8") as f:
    f.write(monitoring_md)

# 4) Risk register
risk_rows = [
    {
        "risk_id": "R1",
        "risk": "Regime shift increases error and causes bad decisions.",
        "impact": "Loss increase, limit breaches, client harm if automated.",
        "evidence": "Worst-fold RMSE elevated; rolling RMSE spikes in stress.",
        "control": "Vol regime monitor; disable when vol proxy above threshold.",
        "owner": "Model owner",
        "residual_risk": "Medium",
    },
    {
        "risk_id": "R2",
        "risk": "Missing/stale data creates misleading predictions.",
        "impact": "Incorrect signals; hidden overconfidence.",
        "evidence": "Pipeline sensitive to missing blocks.",
        "control": "Hard-fail data integrity checks; fallback data source.",
        "owner": "Data engineering",
        "residual_risk": "Low",
    },
    {
        "risk_id": "R3",
        "risk": "Accuracy gain does not translate to decision safety.",
        "impact": "Tail losses increase despite RMSE improvement.",
        "evidence": "Stress RMSE x2 worsens materially.",
        "control": "Decision-level backtest metrics + stress scenarios required for approval.",
        "owner": "Risk control",
        "residual_risk": "Medium",
    },
]
risk_df = pd.DataFrame(risk_rows)
risk_df.to_csv(os.path.join(run_dir, "RISK_REGISTER.csv"), index=False)

# 5) Handover note
handover = f"""# Handover

- **Run ID:** {run_id}
- **Artefacts:** MODEL_CARD.md, ASSUMPTIONS.md, MONITORING_SPEC.md, RISK_REGISTER.csv
- **Next actions:** implement monitors + alert routing; define disable/fallback hooks.
- **Support:** model owner owns performance monitoring; data engineering owns data integrity.
"""
with open(os.path.join(run_dir, "HANDOVER.md"), "w", encoding="utf-8") as f:
    f.write(handover)

print("Wrote sign-off pack to:", run_dir)
print("Files:", os.listdir(run_dir))