update doc and optimize

AINative_OKR_CASAN5/.specify/scripts/bash/self-improve.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""CASAN self-improve core (Plan-04, harness-owned).
+
+Reads real telemetry (provider-usage / metrics JSONL + optional drift report) and
+emits improvement PROPOSALS (dry-run, never writes). Applying a proposal requires
+human approval (`--approval`) and goes through the governed settings store
+(control-plane-settings.py) so every change is audited. Loosen / security-sensitive
+proposals always require approval.
+
+Subcommands:
+  propose --metrics <jsonl> [--drift <json>]   -> proposals JSON on stdout (no writes)
+  apply   --proposals <json> --id <ID> [--approval <tok>]  -> governed set (needs approval)
+"""
+import argparse
+import json
+import os
+import statistics
+import subprocess
+import sys
+
+
+def read_jsonl(path):
+    rows = []
+    if not path or not os.path.isfile(path):
+        return rows
+    with open(path, encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except ValueError:
+                continue
+    return rows
+
+
+def build_proposals(metrics_rows, drift):
+    proposals = []
+    costs = [r["cost_usd"] for r in metrics_rows if isinstance(r.get("cost_usd"), (int, float))]
+    if costs:
+        cap = round(max(costs) * 1.5, 4)
+        proposals.append({
+            "id": "P-COST-CAP",
+            "type": "calibrate_cost_cap",
+            "key": "cost.absolute_cap_usd",
+            "value": cap,
+            "direction": "tighten",
+            "security_sensitive": False,
+            "reason": f"observed max cost {max(costs)}; set cap to 1.5x = {cap}",
+        })
+    if drift and (drift.get("drift") is True or drift.get("entries")):
+        proposals.append({
+            "id": "P-GOLDEN",
+            "type": "update_golden",
+            "key": None,
+            "value": None,
+            "direction": "loosen",
+            "security_sensitive": True,
+            "reason": "drift detected; updating golden may hide real regressions — needs review",
+        })
+    return proposals
+
+
+def cmd_propose(args):
+    metrics = read_jsonl(args.metrics)
+    drift = None
+    if args.drift and os.path.isfile(args.drift):
+        try:
+            drift = json.load(open(args.drift, encoding="utf-8"))
+        except ValueError:
+            drift = None
+    proposals = build_proposals(metrics, drift)
+    print(json.dumps({"proposals": proposals, "count": len(proposals)}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_apply(args):
+    try:
+        data = json.load(open(args.proposals, encoding="utf-8"))
+    except (OSError, ValueError):
+        print(f"IMPROVE_DENY PROPOSALS_UNREADABLE {args.proposals}", file=sys.stderr)
+        return 1
+    proposal = next((p for p in data.get("proposals", []) if p.get("id") == args.id), None)
+    if proposal is None:
+        print(f"IMPROVE_DENY UNKNOWN_PROPOSAL {args.id}", file=sys.stderr)
+        return 1
+
+    # Proposal != application: applying ALWAYS requires human approval (Plan-04).
+    if not (args.approval or "").strip():
+        print(f"IMPROVE_DENY APPROVAL_REQUIRED {args.id}", file=sys.stderr)
+        return 1
+
+    if proposal.get("key") is None:
+        # Non-settings proposal (e.g. update_golden) — record intent, no auto-apply.
+        print(f"IMPROVE_MANUAL {args.id} type={proposal.get('type')} (no auto-apply; do it under review)")
+        return 0
+
+    cps = os.path.join(os.path.dirname(__file__), "control-plane-settings.py")
+    cmd = [
+        sys.executable, cps, "set", proposal["key"], json.dumps(proposal["value"]),
+        "--actor", "casan-improve", "--reason", f"auto-improve {args.id}",
+    ]
+    if proposal.get("security_sensitive"):
+        cmd += ["--approval", args.approval]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        print(f"IMPROVE_DENY GOVERNED_SET_FAILED {result.stderr.strip()}", file=sys.stderr)
+        return 1
+    print(f"IMPROVE_APPLIED {args.id} key={proposal['key']} value={proposal['value']}")
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    pr = sub.add_parser("propose")
+    pr.add_argument("--metrics", default="")
+    pr.add_argument("--drift", default="")
+    ap_ = sub.add_parser("apply")
+    ap_.add_argument("--proposals", required=True)
+    ap_.add_argument("--id", required=True)
+    ap_.add_argument("--approval", default="")
+    args = ap.parse_args()
+    if args.cmd == "propose":
+        return cmd_propose(args)
+    if args.cmd == "apply":
+        return cmd_apply(args)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())