audit notes work completed, test fixes work (95% done), new sprints, new data sources setup and configuration

docs/modules/policy/guides/ai-code-guard-policy.md

@@ -0,0 +1,55 @@
+# AI Code Guard Policy Guide
+> **Status:** Planned
+> **Audience:** Policy authors, Security reviewers, CI owners
+> **Related:** `docs/modules/scanner/operations/ai-code-guard.md`
+
+This guide defines the Policy signals and matrix logic used to evaluate AI Code Guard evidence. The goal is deterministic, explainable pass/review/block outcomes with auditable overrides.
+
+## 1) Policy goals
+- Deterministic pass/review/block outcomes for the same inputs.
+- Explainable results with short reasons and evidence links.
+- Overrides allowed only with issue link and expiry.
+
+## 2) Signals (proposed)
+
+| Signal | Type | Notes |
+| --- | --- | --- |
+| `guard.ai.status` | string | `pass`, `review`, `block` from Scanner. |
+| `guard.ai.hunk.count` | int | Count of changed hunks evaluated. |
+| `guard.ai.secrets.new.count` | int | New secrets in this change. |
+| `guard.ai.secrets.pre_existing.count` | int | Previously known secrets. |
+| `guard.ai.unsafe.count` | int | Unsafe API findings. |
+| `guard.ai.similarity.max` | number | Highest similarity score (0.0-1.0). |
+| `guard.ai.similarity.denylist_hit` | bool | True when denylist threshold is exceeded. |
+| `guard.ai.license.block.count` | int | Licenses in block list. |
+| `guard.ai.license.review.count` | int | Licenses requiring review. |
+| `guard.ai.override.active` | bool | Override is present and unexpired. |
+| `guard.ai.override.expires_at` | string | UTC ISO-8601 timestamp. |
+
+## 3) Policy matrix
+
+Default matrix (policy pack example):
+- Block if new secrets or denylist similarity exceed thresholds.
+- Review if license review count > 0 or similarity above review threshold.
+- Pass otherwise.
+
+## 4) Example DSL snippet
+
+```dsl
+rule ai_code_guard_block priority 50 {
+  when guard.ai.secrets.new.count > 0 or guard.ai.similarity.denylist_hit == true
+  then status := "block"
+  because "AI code guard block criteria met";
+}
+```
+
+## 5) Overrides
+
+- Overrides require issue links and expiry.
+- Review overrides require `SecurityReviewer` role; block overrides require `SecurityOwner`.
+- Policy explain traces must include override metadata for audit.
+
+## 6) Evidence and replay
+
+- Policy explain exports include the guard evidence hash and rule version.
+- Guard evidence is stored and signed for deterministic replay.