feat: Citadel integration - docs, exporter, policy binding, example

[imran-siddique]

Summary

Integrates AGT with the Foundry Citadel Platform, Microsoft's layered AI governance architecture. AGT provides agent-level governance (per-action policy evaluation, trust scoring, cryptographic identity) that complements Citadel's gateway-level controls (rate limiting, content filtering, identity validation).

What's Included

Architecture Documentation

• docs/integrations/citadel-integration.md: Reference architecture explaining how AGT maps to Citadel's 4 layers, data flow, policy precedence, coverage boundaries, and failure modes.

Citadel Audit Exporter

• agent_os/exporters/citadel_exporter.py: Exports governance events to Azure Event Hub and Application Insights with:
  • Correlation IDs (APIM request, Foundry trace, AGT decision)
  • Hash-chain tamper evidence preservation
  • Batching and async flush
  • Fail-open behavior (logs locally when Azure is unavailable)

Policy Bundle Resolver

• agent_os/integrations/citadel/policy_bundle.py: Loads AGT policy bundles bound to Citadel Access Contracts from file, Azure Key Vault, or URL. Validates bundle/contract compatibility.

End-to-End Example

• examples/citadel-governed-agent/: Working example with mock mode showing dual-layer governance (Citadel gateway + AGT runtime policies).

Design Decisions

• AGT spans Citadel layers (not just Layer 2): runtime enforcement near the agent, evidence to Layer 2, identity federation with Layer 3
• Policy bundle binding (not translation): Citadel contracts reference AGT bundles, not translate IaC to runtime rules
• APIM stays coarse-grained: No AGT on the gateway hot path
• Fail-open for telemetry: AGT continues operating if Azure Monitor is unavailable

Testing

Example runs successfully in mock mode:

python examples/citadel-governed-agent/src/agent.py --mock
# 5 decisions, 2 allowed, 3 denied, trust score degradation, hash chain

Related Issues

Closes #1770, closes #1771, closes #1772, closes #1773

Phase 2 (deferred): #1774 (Entra identity federation), #1775 (APIM metadata fragment)

[github-actions]

🤖 AI Agent: code-reviewer — Action Items:

TL;DR: 1 blocker, 2 warnings. Needs fixes for critical security gap in policy validation.

#	Sev	Issue	Where
1	🚨	Missing validation for allowed_actions and blocked_actions overlap	policy_bundle.py
2	⚠️	Fail-open telemetry may expose sensitive data in logs	citadel_exporter.py
3	⚠️	Missing retry limit for Event Hub export	citadel_exporter.py

Action Items:

1. Add validation to ensure allowed_actions and blocked_actions in PolicyBundle do not overlap.

Warnings (fine as follow-up PRs):

#	Issue	Where
2	Review fail-open telemetry behavior to ensure no sensitive data leaks	citadel_exporter.py
3	Implement a retry limit for Event Hub export to avoid infinite loops	citadel_exporter.py

[github-actions]

🤖 AI Agent: docs-sync-checker — Docs Sync

Docs Sync

• agent_os/exporters/citadel_exporter.py -- missing docstring for CitadelAuditExporter.flush_sync()
• agent_os/integrations/citadel/policy_bundle.py -- missing docstring for PolicyBundleResolver.resolve_from_file()
• README.md -- section on integrations needs update to include Citadel integration details.
• CHANGELOG.md -- missing entry for Citadel integration feature.

[github-actions]

🤖 AI Agent: security-scanner — View details

No security issues found.

[github-actions]

🤖 AI Agent: breaking-change-detector — API Compatibility

API Compatibility

Severity	Change	Impact
High	Introduction of CitadelAuditExporter in agent_os.exporters with methods like export_event, flush, and close.	If existing users of the library rely on the agent_os.exporters module, the addition of this class could potentially conflict with their custom implementations or expectations.
High	Addition of PolicyBundle and PolicyBundleResolver in agent_os.integrations.citadel.	If users have existing modules or classes with similar names, this could lead to namespace conflicts.
Medium	New dependencies introduced (azure-eventhub, azure-monitor-opentelemetry-exporter).	Users may face runtime errors if these dependencies are not installed, especially in environments where dependency management is strict.
Medium	Changes in behavior due to fail-open telemetry in CitadelAuditExporter.	Users expecting strict fail-closed behavior for telemetry may encounter unexpected operational changes.

[github-actions]

🤖 AI Agent: test-generator — `agent_os/exporters/citadel_exporter.py`

agent_os/exporters/citadel_exporter.py

• test_eventhub_export_failure -- Validate behavior when Event Hub export fails (e.g., retries, logging).
• test_appinsights_export_failure -- Ensure Application Insights export gracefully handles failures.
• test_flush_buffer_overflow -- Test handling of buffer overflow during event batching.
• test_missing_env_variables -- Verify initialization fails or logs warnings when required environment variables are missing.

agent_os/integrations/citadel/policy_bundle.py

• test_validate_contract_mismatch -- Test validation warnings for mismatched bundle ID or version.
• test_resolve_from_file_invalid_format -- Ensure proper error handling for invalid or corrupted YAML files.
• test_resolve_from_file_missing_file -- Validate behavior when the specified file does not exist.
• test_policy_bundle_content_hash -- Test correctness of computed content hash for policy bundles.

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	❌ Failed	Issues detected
🛡️ Security Scan	✅ Passed	No issues found
🔄 Breaking Changes	✅ Completed	Analysis complete
📝 Docs Sync	✅ Completed	Analysis complete
🧪 Test Coverage	✅ Completed	Analysis complete

Verdict: ❌ Changes needed