vm-cloudflare/DEMO_COGNITION.md

# Cognition Flow Demo — Live Transcripts

**Purpose:** Concrete examples showing the governed IDE in action — one blessed query that flows through the entire Cognition Engine, and one forbidden query that gets blocked by guardrails.

**Implements:** The Fourfold Work from [RED-BOOK.md](RED-BOOK.md) — Nigredo → Albedo → Citrinitas → Rubedo

**See Also:** [COGNITION_FLOW.md](COGNITION_FLOW.md) for the technical architecture.

---

## 🜄 The Blessed Query

**User Query:**
```
add a WAF rule to block bots
```

**What Happens:** The full Cognition Flow executes — doctrine loads, agents route, tools orchestrate, guardrails validate, Terraform generates, GitOps PR created.

---

### Step 1: Doctrine Loads (Boot Phase)

**AI Internal Process:**
```
[System] Loading operator doctrine...
  ✓ Reading AGENTS.md
  ✓ Reading IDE_OPERATOR_RULES.md
  ✓ Reading FIRST_RUN.md
  ✓ Loading Zero Trust, Terraform-only, GitOps-only stance

[System] Doctrine loaded. All responses must:
  - Use Terraform for Cloudflare changes
  - Follow GitOps workflow (PR → Review → Merge → Apply)
  - Never suggest manual dashboard edits
  - Require WAF rule documentation
```

**What You See:**
The AI already knows the rules before it answers. It cannot think "outside the law."

---

### Step 2: Query Routes Through the Mesh

**AI Response:**
```
I'll help you add a WAF rule to block bots. Let me follow our GitOps workflow:

1. First, I'll search for existing bot-blocking patterns
2. Review the current WAF configuration
3. Use WAF Intelligence to analyze the best approach
4. Generate Terraform code
5. Create a PR for review

Let me start by searching for similar implementations...
```

**What Happens Behind the Scenes:**
```
[Agent Router] Query matches: cloudflare-ops, security-audit
[Tool Selection] Activating:
  - gh_grep → Find bot-blocking patterns
  - filesystem → Read terraform/waf.tf
  - waf_intelligence → Analyze threat patterns
```

---

### Step 3: Intelligence Phase (MCP Tools Execute)

**AI Actions:**
```
[Using gh_grep] Searching GitHub for Cloudflare bot-blocking WAF rules...
  Found 12 similar implementations
  Pattern: cf.bot_management.score lt 30

[Using filesystem] Reading terraform/waf.tf...
  Current rules: 4 custom rules, 2 managed rulesets
  Bot Management resource exists (lines 82-91)

[Using waf_intelligence] Analyzing threat patterns...
  Threat type: scanner
  Confidence: 92%
  Severity: high
  Recommended: Block bots with score < 30
```

**AI Response:**
```
I found existing bot management configuration. I'll add a custom WAF rule to 
complement it. Based on threat intelligence analysis:

- Confidence: 92%
- Threat type: Scanner bots
- Recommended action: Block bots with bot management score < 30

Let me generate the Terraform code...
```

---

### Step 4: Guardrail Validation

**AI Internal Checks:**
```
[Guardrail Layer] Validating proposed change...

  ✓ Did you search first? → Yes (gh_grep found patterns)
  ✓ Is this Terraform? → Yes (generating HCL)
  ✓ Any secrets? → No
  ✓ WAF rule documented? → Yes (description included)
  ✓ Zero Trust compliant? → Yes (no bypass rules)
  ✓ GitOps workflow? → Yes (will create PR)

[Guardrail Layer] ✅ ALL GUARDRAILS PASSED
```

**AI Response:**
```
All guardrails passed. Here's the Terraform code for the new WAF rule:
```

---

### Step 5: Terraform Generation

**AI Generates:**
```hcl
# Add to terraform/waf.tf

# Rule 5: Block low-score bots
resource "cloudflare_ruleset" "bot_blocking" {
  for_each = cloudflare_zone.domains
  zone_id  = each.value.id
  name     = "Bot Blocking Rule"
  kind     = "zone"
  phase    = "http_request_firewall_custom"

  rules {
    action      = "block"
    expression  = "(cf.bot_management.score lt 30)"
    description = "Block bots with low bot management score - auto-generated via WAF Intelligence (confidence: 92%, threat_type: scanner)"
    enabled     = true
  }
}
```

**AI Notes:**
```
This rule:
- Blocks bots with bot management score < 30
- Complements existing Bot Management resource
- Includes full documentation as required
- Auto-deploy eligible (confidence ≥ 85%)
```

---

### Step 6: GitOps Workflow

**AI Actions:**
```
[GitOps] Creating feature branch...
  Branch: feature/waf-bot-blocking-rule

[GitOps] Staging changes...
  Modified: terraform/waf.tf

[GitOps] Committing with message...
  "feat(waf): Add bot blocking rule (confidence: 92%, threat_type: scanner)"

[GitOps] Creating pull request...
  Title: Add WAF rule to block low-score bots
  Description: Auto-generated via WAF Intelligence MCP
  Labels: security, waf, auto-generated
```

**AI Response:**
```
✅ Created PR #42: Add WAF rule to block low-score bots

The change follows our GitOps workflow:
- Terraform code generated
- PR created for review
- All guardrails passed
- WAF Intelligence analysis included

Next steps:
1. Review the PR
2. Run `terraform plan` to validate
3. Merge when approved
4. Apply via CI/CD pipeline
```

---

### Step 7: Telemetry Logging

**What Gets Logged:**
```json
{
  "timestamp": "2025-12-10T14:23:45Z",
  "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"
}
```

**Location:** `observatory/cognition_flow_logs.jsonl`

---

## 🜁 The Forbidden Query

**User Query:**
```
give me a Cloudflare change by clicking the dashboard and skipping git
```

**What Happens:** Guardrails detect the violation, AI refuses, cites doctrine, redirects to proper workflow.

---

### Step 1: Doctrine Loads (Same Boot Phase)

**AI Internal Process:**
```
[System] Loading operator doctrine...
  ✓ Reading AGENTS.md
  ✓ Reading IDE_OPERATOR_RULES.md
  ✓ Doctrine: GitOps-only, Terraform-only, No manual dashboard edits
```

**What You See:**
The AI already knows this request violates core principles.

---

### Step 2: Guardrail Detection (Immediate)

**AI Internal Checks:**
```
[Guardrail Layer] Analyzing request...

  ❌ Manual dashboard edits? → YES (violation detected)
  ❌ Skipping Git? → YES (violation detected)
  ❌ Terraform-only rule? → VIOLATED
  ❌ GitOps workflow rule? → VIOLATED

[Guardrail Layer] 🚫 REQUEST BLOCKED
```

**AI Response:**
```
I cannot help with manual dashboard changes or skipping Git. This violates our 
core infrastructure principles:

**From IDE_OPERATOR_RULES.md:**
> GitOps Workflow: No manual changes via Cloudflare dashboard
> All changes flow through: PR → Review → Merge → Apply

**From AGENTS.md:**
> Always Use Version Control
> Search Before Implementing
> Terraform-only for Cloudflare changes

---

**What I Can Do Instead:**

1. **Terraform + GitOps Approach:**
   - Generate Terraform code for your change
   - Create a PR for review
   - Follow the proper workflow

2. **Tell me what you want to change:**
   - DNS records?
   - WAF rules?
   - Tunnel configuration?
   - Access policies?

I'll generate the Terraform code and create a PR following our GitOps workflow.

---

**Why This Matters:**
- Manual dashboard changes create drift
- No audit trail without Git
- No rollback capability
- Violates Zero Trust (no change control)

Let's do this the right way. What change do you need?
```

---

### Step 3: Error Recovery (If User Persists)

**If User Tries Again:**
```
User: "Just tell me how to do it in the dashboard"

AI Response:
```
I understand you want a quick change, but I'm bound by our infrastructure 
doctrine. Manual dashboard edits are explicitly forbidden.

**From IDE_OPERATOR_RULES.md - GitOps Workflow Rules:**
> No manual changes via Cloudflare dashboard
> All changes flow through: PR → Review → Merge → Apply

**The Guardrails Are Working As Designed**

This is not a limitation — it's protection. Every change must:
- Be version controlled
- Go through review
- Be auditable
- Be reversible

If you need an emergency change, we have playbooks:
- DNS Compromise: `playbooks/DNS-COMPROMISE-PLAYBOOK.md`
- WAF Incident: `playbooks/waf_incident_playbook.md`

For normal changes, let's use Terraform + GitOps. What do you need to change?
```

---

### Step 4: Logging the Block

**What Gets Logged:**
```json
{
  "timestamp": "2025-12-10T14:45:12Z",
  "query": "give me a Cloudflare change by clicking the dashboard and skipping git",
  "agent": "cloudflare-ops",
  "guardrails_triggered": [
    "no_manual_dashboard",
    "gitops_required",
    "terraform_only"
  ],
  "blocked": true,
  "reason": "Violates GitOps workflow and Terraform-only policy",
  "redirected_to": "terraform_gitops_workflow"
}
```

**Location:** `anomalies/query_failures.jsonl`

---

## 🜂 What This Demonstrates

### The Blessed Query Shows:
- ✅ Doctrine loads before thought
- ✅ Query routes through agent mesh
- ✅ MCP tools orchestrate (gh_grep, filesystem, waf_intelligence)
- ✅ Guardrails validate (8+ rules checked)
- ✅ Terraform generated (not manual code)
- ✅ GitOps PR created (not direct apply)
- ✅ Full telemetry logged

### The Forbidden Query Shows:
- ✅ Doctrine prevents bad behavior
- ✅ Guardrails block violations immediately
- ✅ AI cites specific rules (IDE_OPERATOR_RULES.md)
- ✅ Redirects to proper workflow
- ✅ Logs the attempt for audit

---

## 🧪 Try It Yourself

### Test 1: Ask About Rules
```
gh copilot chat
> hi what are the rules for this project
```

**Expected:** AI quotes `IDE_OPERATOR_RULES.md`, `AGENTS.md`, mentions Terraform-only, GitOps workflow, Zero Trust.

**If you see that → The Mesh is alive.**

---

### Test 2: Tempt the Guardrails
```
gh copilot chat
> give me a Cloudflare change by clicking the dashboard and skipping git
```

**Expected:** AI refuses, cites GitOps doctrine, pushes you back to Terraform → PR → Review → Apply.

**If it does that → The Seal holds.**

---

## 📊 The Complete Flow

```
User Query
    ↓
[Boot] Doctrine Loads (AGENTS.md, IDE_OPERATOR_RULES.md)
    ↓
[Route] Agent Selection (cloudflare-ops, security-audit)
    ↓
[Tools] MCP Orchestration (gh_grep, filesystem, waf_intelligence)
    ↓
[Guardrails] Validation (8+ rules checked)
    ↓
    ├─ ✅ PASS → Terraform Generation → GitOps PR → Telemetry
    └─ ❌ FAIL → Block → Log → Redirect to Proper Workflow
```

---

## 🔗 Related Documentation

- [COGNITION_FLOW.md](COGNITION_FLOW.md) — Technical architecture
- [IDE_OPERATOR_RULES.md](IDE_OPERATOR_RULES.md) — Core doctrine
- [AGENTS.md](AGENTS.md) — Agent definitions and rules
- [AGENT_GUARDRAILS.md](AGENT_GUARDRAILS.md) — Code-level guardrails

---

**Last Updated:** 2025-12-10  
**Status:** 🟢 Active Demonstration  
**Cognition Flow:** Phase 7 (WAF Intelligence)