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

docs/write-mode.md

@@ -0,0 +1,40 @@
+# Write Mode
+
+## Threat Model
+
+Write mode introduces mutation risk (issue/PR changes, metadata updates). Risks include unauthorized action, accidental mass updates, and audit evasion.
+
+## Default Posture
+
+- `WRITE_MODE=false` by default.
+- Even when enabled, writes require repository whitelist membership.
+- Policy engine remains authoritative and may deny specific write tools.
+
+## Supported Write Tools
+
+- `create_issue`
+- `update_issue`
+- `create_issue_comment`
+- `create_pr_comment`
+- `add_labels`
+- `assign_issue`
+
+Not supported (explicitly forbidden): merge actions, branch deletion, force push.
+
+## Enablement Steps
+
+1. Set `WRITE_MODE=true`.
+2. Set `WRITE_REPOSITORY_WHITELIST=owner/repo,...`.
+3. Review policy file for write-tool scope.
+4. Verify audit logging and alerting before rollout.
+
+## Safe Operations
+
+- Start with one repository in whitelist.
+- Use narrowly scoped bot credentials.
+- Require peer review for whitelist/policy changes.
+- Disable write mode during incident response if abuse is suspected.
+
+## Risk Tradeoffs
+
+Write mode improves automation and triage speed but increases blast radius. Use least privilege, tight policy, and strong monitoring.