feat: harden gateway with policy engine, secure tools, and governance docs

docs/policy.md

@@ -0,0 +1,50 @@
+# Policy Engine
+
+## Overview
+
+Aegis uses a YAML policy engine to authorize tool execution before any Gitea API call is made.
+
+## Behavior Summary
+
+- Global tool allow/deny supported.
+- Per-repository tool allow/deny supported.
+- Optional repository path allow/deny supported.
+- Write operations are denied by default.
+- Write operations also require `WRITE_MODE=true` and `WRITE_REPOSITORY_WHITELIST` match.
+
+## Example Configuration
+
+```yaml
+defaults:
+  read: allow
+  write: deny
+
+tools:
+  deny:
+    - search_code
+
+repositories:
+  acme/service-a:
+    tools:
+      allow:
+        - get_file_contents
+        - list_commits
+    paths:
+      allow:
+        - src/*
+      deny:
+        - src/secrets/*
+```
+
+## Failure Behavior
+
+- Invalid YAML or invalid schema: startup failure (fail closed).
+- Denied tool call: HTTP `403` + audit `access_denied` entry.
+- Path traversal attempt in path-scoped tools: denied by validation/policy checks.
+
+## Operational Guidance
+
+- Keep policy files version-controlled and code-reviewed.
+- Prefer explicit deny entries for sensitive tools.
+- Use repository-specific allow lists for high-risk environments.
+- Test policy updates in staging before production rollout.