# 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.