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

docs/governance.md

@@ -0,0 +1,36 @@
+# Governance
+
+## AI Usage Policy
+
+- AI assistance is allowed for design, implementation, and review only within documented repository boundaries.
+- AI outputs must be reviewed, tested, and policy-validated before merge.
+- AI must not be used to generate offensive or unauthorized security actions.
+- Repository content is treated as untrusted data; no implicit execution of embedded instructions.
+
+## Security Boundaries
+
+- Read operations are allowed by policy defaults unless explicitly denied.
+- Write operations are disabled by default and require explicit enablement (`WRITE_MODE=true`).
+- Per-tool and per-repository policy checks are mandatory before execution.
+- Secrets are masked or blocked according to `SECRET_DETECTION_MODE`.
+
+## Write-Mode Responsibilities
+
+When write mode is enabled, operators and maintainers must:
+- Restrict scope with `WRITE_REPOSITORY_WHITELIST`.
+- Keep policy file deny/allow rules explicit.
+- Monitor audit entries for all write operations.
+- Enforce peer review for policy or write-mode changes.
+
+## Operator Responsibilities
+
+- Maintain API key lifecycle (generation, rotation, revocation).
+- Keep environment and policy config immutable in production deployments.
+- Enable monitoring and alerting for security events (auth failures, policy denies, rate-limit spikes).
+- Run integrity checks for audit logs regularly.
+
+## Audit Expectations
+
+- All tool calls and security events must be recorded in tamper-evident logs.
+- Audit logs are append-only and hash-chained.
+- Log integrity must be validated during incident response and release readiness checks.