feat: add audit investigation cli

Author: sonalejayash

README.md

@@ -110,6 +110,7 @@ python -m pytest -q
 python scripts/train_model.py --output-dir artifacts --model-version v1
 python scripts/evaluate_model.py artifacts/model-v1.json
 python scripts/release.py --model-version v1
+python scripts/investigate_release.py artifacts/audit.jsonl
 ```
 
 Training metadata includes the dataset, random seed, test split, quality metrics, model version, artifact path, SHA-256 digest, signature, public key, source revision, and builder identity. Local runs use `source_revision=local`; GitHub Actions records `GITHUB_SHA`.
@@ -194,7 +195,7 @@ flowchart TD
 
 ## Roadmap
 
-Phase 2 has started with a read-only investigator contract integrated into audit records and covered by end-to-end release scenarios. Its output is structured, evidence-cited, schema-validated, and advisory, with missing and contradictory evidence flagged explicitly. An optional local Ollama transport is timeout-bound and receives structured evidence only. The intelligence layer must match the deterministic decision, has no unrestricted shell or Kubernetes access, and is not part of the final release authority.
+Phase 2 has started with a read-only investigator contract integrated into audit records and covered by end-to-end release scenarios. `scripts/investigate_release.py` can regenerate an advisory investigation report from an existing audit log. Its output is structured, evidence-cited, schema-validated, and advisory, with missing and contradictory evidence flagged explicitly. An optional local Ollama transport is timeout-bound and receives structured evidence only. The intelligence layer must match the deterministic decision, has no unrestricted shell or Kubernetes access, and is not part of the final release authority.
 
 ## Development rule
 

scripts/investigate_release.py

@@ -0,0 +1,75 @@
+"""Generate an advisory investigation report from a saved release audit."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from intelligence.investigator import ReleaseInvestigator
+from policy.engine import Decision, PolicyResult, ReleaseEvidence
+from quality.evaluator import QualityMetrics
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("audit", type=Path)
+    arguments = parser.parse_args()
+    record = _load_latest_record(arguments.audit)
+    evidence = _release_evidence(record["evidence"])
+    result = PolicyResult(
+        decision=Decision(record["decision"]),
+        reasons=tuple(record.get("reasons", ())),
+        policy_version=record["policy_version"],
+    )
+    report = ReleaseInvestigator().investigate(evidence, result)
+    print(json.dumps(report.model_dump(mode="json"), indent=2, sort_keys=True))
+    return 0
+
+
+def _load_latest_record(path: Path) -> dict[str, Any]:
+    try:
+        lines = [line for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+        if not lines:
+            raise ValueError("audit log is empty")
+        payload = json.loads(lines[-1])
+    except (OSError, json.JSONDecodeError) as error:
+        raise SystemExit(f"unable to read audit log: {path}") from error
+    if not isinstance(payload, dict) or "evidence" not in payload:
+        raise SystemExit("audit record must contain evidence")
+    return payload
+
+
+def _release_evidence(payload: dict[str, Any]) -> ReleaseEvidence:
+    metrics = payload.get("quality_metrics")
+    quality_metrics = QualityMetrics(**metrics) if isinstance(metrics, dict) else None
+    return ReleaseEvidence(
+        quality_passed=payload["quality_passed"],
+        drift_psi=payload["drift_psi"],
+        critical_vulnerabilities=payload["critical_vulnerabilities"],
+        artifact_integrity_valid=payload["artifact_integrity_valid"],
+        artifact_signature_valid=payload["artifact_signature_valid"],
+        provenance_valid=payload["provenance_valid"],
+        dependency_scan_passed=payload["dependency_scan_passed"],
+        container_scan_passed=payload["container_scan_passed"],
+        release_id=payload.get("release_id", ""),
+        model_name=payload.get("model_name", ""),
+        model_version=payload.get("model_version", ""),
+        artifact_path=payload.get("artifact_path", ""),
+        artifact_sha256=payload.get("artifact_sha256", ""),
+        quality_metrics=quality_metrics,
+        drift_status=payload.get("drift_status", ""),
+        high_vulnerabilities=payload.get("high_vulnerabilities", 0),
+        dependency_scan_critical=payload.get("dependency_scan_critical", 0),
+        container_scan_critical=payload.get("container_scan_critical", 0),
+        evidence_references=tuple(payload.get("evidence_references", ())),
+        metadata_consistent=payload.get("metadata_consistent", True),
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/scenarios/test_release_scenarios.py

@@ -146,4 +146,36 @@ def test_blocked_audit_investigation_cites_failure_field(tmp_path: Path) -> None
     assert record["investigation"]["advisory_only"] is True
     assert ["artifact_signature_valid"] in [
         finding["evidence_fields"] for finding in record["investigation"]["findings"]
-    ]
+    ]
+
+
+def test_investigation_cli_reads_existing_audit(tmp_path: Path) -> None:
+    audit = tmp_path / "audit.jsonl"
+    release = subprocess.run(
+        [
+            sys.executable,
+            "scripts/release.py",
+            "--model-version",
+            "scenario-v2",
+            "--output-dir",
+            str(tmp_path),
+            "--audit-path",
+            str(audit),
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    investigation = subprocess.run(
+        [sys.executable, "scripts/investigate_release.py", str(audit)],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+    assert release.returncode == 0, release.stderr
+    assert investigation.returncode == 0, investigation.stderr
+    report = json.loads(investigation.stdout)
+    assert report["decision"] == "PROMOTE"
+    assert report["advisory_only"] is True
+    assert report["findings"][0]["evidence_fields"]