feat(portfolio): complete RESOURCE-WP-0003 T06 optimization cases and T07 reporting

T06: optimization-case schema, fail-closed evaluator, cadence and decision
template. Every option including the baseline must present all ten decision
fields; one unknown blocks the comparison. Validated on the storage case
(Hetzner computes and loses to Scaleway by EUR 29.14/month on operator labour;
Host Europe blocks on four named gaps) and on the non-storage reef-railiance
k3s rightsizing case (low utilization is real, but nothing is costable while
the railiance01 price is unknown).

T07: portfolio report over coverage, lifecycle, utilization, cost, renewals,
risks, open cases, and next actions, derived only from committed evidence.
Portfolio spend is reported null rather than as a partial sum, unattributed
cost is a named list rather than a spread, and unmeasurable resources are
reported rather than dropped.

RESOURCE-WP-0003 is finished; both cases remain blocked_on_evidence against
live delegated records in other repositories. RESOURCE-WP-0002 is untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

tools/control_cycle.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Compare a generic immutable resource forecast with an actual observation."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+COST_FIELDS = ("infrastructure", "internal_labor", "external_labor", "total")
+ATTRIBUTIONS = {"demand", "provider_price", "allocation", "labor", "model", "data_quality"}
+
+
+def delta(forecast: float, actual: float) -> dict:
+    error = actual - forecast
+    return {
+        "forecast": forecast,
+        "actual": actual,
+        "error": round(error, 4),
+        "absolute_percentage_error": None if forecast == 0 else round(abs(error) / forecast * 100, 2),
+    }
+
+
+def compare(forecast: dict, actual: dict) -> dict:
+    if forecast["record_type"] != "forecast" or actual["record_type"] != "actual":
+        raise ValueError("expected forecast and actual records")
+    for field in ("resource_id", "resource_class", "period"):
+        if forecast[field] != actual[field]:
+            raise ValueError(f"{field} mismatch")
+    if actual.get("forecast_ref") != forecast["record_id"]:
+        raise ValueError("actual forecast_ref must identify the immutable forecast")
+
+    attribution = actual.get("variance_attribution", {})
+    unknown = set(attribution.values()) - ATTRIBUTIONS
+    if unknown:
+        raise ValueError(f"unknown variance attribution: {sorted(unknown)}")
+
+    proxies = {}
+    all_proxies = sorted(set(forecast["usage_proxies"]) | set(actual["usage_proxies"]))
+    for name in all_proxies:
+        planned = forecast["usage_proxies"].get(name)
+        observed = actual["usage_proxies"].get(name)
+        if planned is None or observed is None:
+            proxies[name] = {"status": "missing", "category": "data_quality"}
+        elif planned["unit"] != observed["unit"]:
+            proxies[name] = {"status": "unit-mismatch", "category": "data_quality"}
+        else:
+            proxies[name] = {**delta(planned["value"], observed["value"]), "unit": planned["unit"], "category": attribution.get(name, "demand")}
+
+    costs = {}
+    for name in COST_FIELDS:
+        default_category = "labor" if "labor" in name else "provider_price"
+        costs[name] = {**delta(forecast["costs"][name], actual["costs"][name]), "currency": "EUR", "category": attribution.get(f"costs.{name}", default_category)}
+
+    if forecast["allocation"] != actual["allocation"]:
+        costs["allocation_method"] = {"status": "changed", "category": attribution.get("allocation", "allocation")}
+
+    return {
+        "forecast_ref": forecast["record_id"],
+        "actual_ref": actual["record_id"],
+        "resource_id": forecast["resource_id"],
+        "resource_class": forecast["resource_class"],
+        "period": forecast["period"],
+        "usage_proxies": proxies,
+        "costs": costs,
+    }
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print(f"usage: {sys.argv[0]} FORECAST.json ACTUAL.json", file=sys.stderr)
+        return 2
+    try:
+        result = compare(json.loads(Path(sys.argv[1]).read_text()), json.loads(Path(sys.argv[2]).read_text()))
+    except (KeyError, ValueError) as exc:
+        print(f"control-cycle error: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())