--- # Cognition Flow Diagram ## How a Single Query Travels Through the CLOUDFLARE Infrastructure **Implements:** The Fourfold Work from [RED-BOOK.md](RED-BOOK.md) — Nigredo → Albedo → Citrinitas → Rubedo **See Also:** [DEMO_COGNITION.md](DEMO_COGNITION.md) for live transcripts showing the Cognition Flow in action — one blessed query and one forbidden query demonstrating guardrails. --- ## The Flow (7 Layers) ``` ┌────────────────────────────────────────────────────────────────────────────┐ │ LAYER 1: Boot (Doctrine Load) │ │ ────────────────────────────────────────────────────────────────────── │ │ On IDE start: │ │ ├─ seed_ide_rules.py symlinks IDE_OPERATOR_RULES.md │ │ ├─ IDE loads: │ │ │ - AGENTS.md (agent definitions + MCP tool permissions) │ │ │ - IDE_OPERATOR_RULES.md (Terraform/GitOps/Zero Trust policy) │ │ │ - FIRST_RUN.md (initial setup + rules summary) │ │ │ - MULTI_ACCOUNT_AUTH.md (multi-account MCP configuration) │ │ └─ Result: AI soaked in doctrine before first query │ └────────────────────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────────────────────┐ │ LAYER 2: Query Routing │ │ ────────────────────────────────────────────────────────────────────── │ │ User query: "add a WAF rule to block bots" │ │ ├─ Parse intent: Infrastructure change (Cloudflare) │ │ ├─ Route to agents (from AGENTS.md): │ │ │ - Primary: cloudflare-ops (has Terraform + Cloudflare tools) │ │ │ - Secondary: security-audit (for compliance check) │ │ └─ Select tools needed: │ │ - gh_grep (find similar patterns) │ │ - filesystem (read terraform/waf.tf) │ │ - waf_intelligence (analyze threat, generate rule) │ │ - cloudflare (query live config if multi-account) │ └────────────────────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────────────────────┐ │ LAYER 3: MCP Tool Orchestration │ │ ────────────────────────────────────────────────────────────────────── │ │ Step 1: Search Phase (gh_grep MCP) │ │ ├─ Query: "Cloudflare WAF bot blocking patterns" │ │ ├─ Result: 12 similar implementations found │ │ └─ Pattern extracted: cf.bot_management.score lt 30 │ │ │ │ Step 2: Context Phase (filesystem MCP) │ │ ├─ Read: terraform/waf.tf │ │ ├─ Parse current rules: 4 custom, 2 managed │ │ └─ Identify insertion point: After resource "cloudflare_ruleset" │ │ │ │ Step 3: Intelligence Phase (WAF Intelligence MCP - Phase 7) │ │ ├─ Load: mcp/waf_intelligence/orchestrator.py │ │ ├─ Analyze current WAF baseline │ │ ├─ Check threat intel for bot networks │ │ ├─ Multi-Account Support (MULTI_ACCOUNT_AUTH.md): │ │ │ ├─ Detect cross-account query (e.g., "compare prod vs staging") │ │ │ ├─ Invoke parallel MCPs: │ │ │ │ - cloudflare_prod: {env:CLOUDFLARE_API_TOKEN_PROD} │ │ │ │ - cloudflare_staging: {env:CLOUDFLARE_API_TOKEN_STAGING} │ │ │ ├─ Compare results (e.g., WAF rules diff) │ │ │ └─ Enforce access: Only if agent.tools permits (opencode.jsonc) │ │ ├─ Generate rule with ML classifier: │ │ │ { │ │ │ "expression": "(cf.bot_management.score lt 30)", │ │ │ "action": "block", │ │ │ "confidence": 92, │ │ │ "severity": "high", │ │ │ "threat_type": "scanner" │ │ │ } │ │ └─ Check auto-deploy criteria: ✓ (confidence ≥ 85%) │ └────────────────────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────────────────────┐ │ LAYER 4: Guardrail Validation (AGENT_GUARDRAILS.md) │ │ ────────────────────────────────────────────────────────────────────── │ │ Rule 1: Did you search first? (Global Rule #2) │ │ └─ ✓ gh_grep executed, found patterns │ │ Rule 2: Terraform only? (Global Rule #1, #5) │ │ └─ ✓ Generating HCL, not manual dashboard │ │ Rule 3: No secrets? (IDE_OPERATOR_RULES.md) │ │ └─ ✓ No API tokens in code │ │ Rule 4: WAF rule documented? (Global Rule #1) │ │ └─ ✓ Description includes confidence + threat_type │ │ Rule 5: Zero Trust? (Global Rule #3) │ │ └─ ✓ No bypass rules, blocks hostile traffic │ │ Rule 6: GitOps workflow? (Global Rule #2) │ │ └─ ✓ Will create PR, not direct apply │ │ Rule 7: Compliance? (Global Rule #4) │ │ └─ ✓ Logging enabled, audit trail in observatory/ │ │ Rule 8: Drift check? (Global Rule #5) │ │ └─ ✓ terraform validate will run in PR │ │ │ │ Result: ✅ ALL GUARDRAILS PASSED │ └────────────────────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────────────────────┐ │ LAYER 5: Terraform Generation │ │ ────────────────────────────────────────────────────────────────────── │ │ Generate HCL: │ │ resource "cloudflare_ruleset" "bot_blocking" { │ │ for_each = cloudflare_zone.domains │ │ zone_id = each.value.id │ │ name = "Bot Blocking Rule" │ │ rules { │ │ action = "block" │ │ expression = "(cf.bot_management.score lt 30)" │ │ description = "Block bots - confidence: 92%, threat: scanner" │ │ } │ │ } │ │ │ │ Write to: terraform/waf.tf (new block after existing rules) │ └────────────────────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────────────────────┐ │ LAYER 6: GitOps Workflow │ │ ────────────────────────────────────────────────────────────────────── │ │ Step 1: Create branch │ │ └─ Branch name: feature/waf-bot-blocking-rule │ │ Step 2: Stage & commit │ │ └─ Message: "feat(waf): Add bot blocking (confidence: 92%)" │ │ Step 3: Push to remote │ │ Step 4: Create PR │ │ ├─ Title: Add WAF rule to block low-score bots │ │ ├─ Description: Auto-generated via WAF Intelligence │ │ └─ Labels: security, waf, auto-generated │ │ Step 5: CI/CD triggers │ │ ├─ terraform validate │ │ ├─ terraform plan │ │ └─ Await review + approval │ └────────────────────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────────────────────┐ │ LAYER 7: Telemetry & Logging │ │ ────────────────────────────────────────────────────────────────────── │ │ Log to: observatory/cognition_flow_logs.jsonl │ │ { │ │ "timestamp": "2025-12-09T02:15:00Z", │ │ "query": "add a WAF rule to block bots", │ │ "agent": "cloudflare-ops", │ │ "tools_used": ["gh_grep", "filesystem", "waf_intelligence"], │ │ "guardrails_passed": true, │ │ "terraform_generated": true, │ │ "pr_created": true, │ │ "pr_number": 42, │ │ "confidence": 92, │ │ "threat_type": "scanner" │ │ } │ │ │ │ Also logged: │ │ ├─ COMPLIANCE_LEDGER.jsonl (if compliance check ran) │ │ └─ anomalies/*.jsonl (if any guardrail warnings) │ └────────────────────────────────────────────────────────────────────────────┘ ``` --- ## Summary: The Machine in Motion **Input:** "add a WAF rule to block bots" **Output:** - ✅ Terraform HCL generated - ✅ PR created (GitOps) - ✅ All 8 guardrails passed - ✅ Compliance logged - ✅ Ready for human review **What Didn't Happen:** - ❌ No manual dashboard clicks - ❌ No secrets committed - ❌ No direct apply (GitOps enforced) - ❌ No undocumented rules --- ## Multi-Account Enhancements From **MULTI_ACCOUNT_AUTH.md**, the flow now supports: **Cross-Account Queries:** ``` "Compare production vs staging WAF rules" ``` **Flow Modifications:** - Layer 2 (Routing): Detects multi-account intent - Layer 3 (MCP): Invokes `cloudflare_prod` + `cloudflare_staging` in parallel - Layer 4 (Guardrails): Validates agent has permission for both accounts - Layer 5 (Terraform): Generates diff + remediation plan - Layer 6 (GitOps): Creates PR with cross-account comparison - Layer 7 (Telemetry): Logs which accounts were accessed **Security:** Each agent's `tools` config in `opencode.jsonc` controls which accounts it can access (e.g., `security-audit` only gets `cloudflare_prod`, not staging or dev). --- ## Error Recovery If any layer fails: ``` ┌────────────────────────────────────────────────────────────────────────────┐ │ Error Recovery Sub-Layer │ │ ────────────────────────────────────────────────────────────────────── │ │ ├─ Log failure to: anomalies/query_failures.jsonl │ │ ├─ Retry: Break query into sub-tasks (e.g., search only) │ │ ├─ Notify: Via slack MCP if configured │ │ └─ Escalate: If critical (e.g., PCI-DSS flag), require manual review │ └────────────────────────────────────────────────────────────────────────────┘ ``` --- ## Scalability Note For large projects: - **Token limits?** Split into sub-queries (Layer 2) - **High volume?** Parallel agents (up to 3) - **Multi-account?** Per-environment MCPs (MULTI_ACCOUNT_AUTH.md) --- ## Related Documentation - **DEMO_COGNITION.md** — Live transcripts (blessed + forbidden queries) - **AGENT_GUARDRAILS.md** — The 8 guardrail rules - **AGENTS.md** — Agent definitions and MCP tool permissions - **IDE_OPERATOR_RULES.md** — Terraform/GitOps/Zero Trust policy - **MULTI_ACCOUNT_AUTH.md** — Multi-account MCP configuration - **MCP_GUIDE.md** — Complete MCP server reference --- **This is the Cognition Engine.** Every query flows through these 7 layers. **Doctrine → Routing → Tools → Guardrails → Terraform → GitOps → Logs.**