Build XIO Brain Cognitive Inspection Control Plane

[slavazeph-coder]

Objective

Turn BrainSNN from a powerful cognitive visualization demo into a product-grade cognitive inspection layer: XIO Brain = cognitive firewall + evidence engine + agent judge + rewrite/report console.

This should be built inside the existing Vite/React app under brainsnn-r3f-app/ without requiring a backend or new paid APIs. The app already has the right raw ingredients: Cognitive Firewall, Autopsy Mode, Affective Decoder, Brain Evolve, MCP Bridge, Gemini/Gemma panels, Lobster Trap panel, local snapshots, and brain-state mapping. The missing layer is a unified inspection workflow that makes the Brain useful as a business/product decision engine.

Product promise

Paste any AI output, marketing claim, social post, landing page copy, contract clause, construction scope, or agent decision. XIO Brain scores cognitive risk, highlights evidence, judges what is unsafe/unsupported/manipulative, proposes a safer rewrite, shows before/after score deltas, and exports an evidence-backed report.

High-level flow

Input
  ↓
Scan / Inspect
  ↓
Scorecard
  ↓
Evidence Pack
  ↓
Rewrite / Safer Version
  ↓
Before-After Delta
  ↓
Exportable Report
  ↓
Optional: Apply to 3D brain state

Important repo context

• Deployable app lives in brainsnn-r3f-app/.
• Current stack: React 18 + Vite + React Three Fiber.
• Keep the browser-native/offline-first posture.
• Do not rewrite the existing 3D brain, simulation loop, or panel system.
• Reuse existing styles/classes such as panel, panel-pad, eyebrow, muted, btn, btn-sm, firewall-input, etc.
• Reuse existing utilities where possible instead of creating duplicate scoring logic.

Proposed files

1. Add brainsnn-r3f-app/src/utils/cognitiveInspection.js

Create a reusable engine with exports like:

export function inspectContent(input, options = {}) {}
export function buildEvidencePack(inspection) {}
export function generateSaferRewrite(input, inspection, options = {}) {}
export function judgeAgentOutput(input, options = {}) {}
export function exportInspectionMarkdown(inspection) {}
export function inspectionToBrainResult(inspection) {}

Expected inspection shape:

{
  id: 'xio_inspection_<timestamp>',
  mode: 'content' | 'agent' | 'claim' | 'contract' | 'construction' | 'landing_page',
  createdAt: ISOString,
  inputPreview: string,
  scores: {
    overallCognitiveRisk: 0-100,
    pressure: 0-100,
    certainty: 0-100,
    fear: 0-100,
    urgency: 0-100,
    shame: 0-100,
    identityCapture: 0-100,
    falseAuthority: 0-100,
    trustErosion: 0-100,
    proofStrength: 0-100,
    hallucinationRisk: 0-100,
    decisionRisk: 0-100
  },
  verdict: {
    level: 'low' | 'watch' | 'elevated' | 'high' | 'critical',
    label: string,
    recommendedAction: string
  },
  flags: [
    {
      id: string,
      type: string,
      severity: 'low' | 'medium' | 'high' | 'critical',
      scoreImpact: number,
      quote: string,
      line: number,
      explanation: string,
      saferAlternative: string
    }
  ],
  evidencePack: {
    traceId: string,
    excerpts: [],
    assumptions: [],
    missingEvidence: [],
    approvalQuestions: []
  },
  rewrite: {
    text: string,
    scoreDelta: {
      before: number,
      afterEstimate: number,
      improvement: number
    }
  }
}

Use deterministic local heuristics first. Do not require Gemini/Gemma to work. Optional LLM integrations can enhance later.

2. Add brainsnn-r3f-app/src/data/cognitiveInspectionCases.js

Seed an eval corpus with at least 10 examples:

• aggressive sales post
• fear-based political copy
• unsupported AI claim
• overconfident agent recommendation
• construction scope ambiguity
• legal/compliance statement missing evidence
• landing page hero with trust erosion
• benign factual explanation
• emotionally manipulative relationship text
• high-pressure investment pitch

Each case should include:

{
  id,
  title,
  mode,
  input,
  expectedFlags: [],
  expectedScoreRange: {
    overallCognitiveRisk: [min, max],
    proofStrength: [min, max]
  }
}

3. Add brainsnn-r3f-app/src/components/CognitiveInspectionPanel.jsx

Build a polished panel with these sections:

Input area

• Textarea for pasted content.
• Mode selector: Content, Agent Output, Landing Page, Compliance, Construction Scope, Claim Check.
• Buttons: Run inspection, Try example, Clear, Apply to brain, Copy report.

Scorecard

Show the core scores as compact metric cards:

• Overall cognitive risk
• Manipulation pressure
• Trust erosion
• Proof strength
• Hallucination risk
• Decision risk

Evidence Pack

Show flagged excerpts with:

• quote
• line number
• detected pattern
• why it matters
• safer alternative

Rewrite / Delta

Show:

• safer rewrite
• before risk score
• estimated after score
• improvement delta

Eval Bench

Add a Run evals button that runs the seeded cases through inspectContent and shows:

• pass/fail count
• cases outside expected score range
• top failed expectations

Local archive

Store last 10 inspections in localStorage. Show a small archive list with title/date/risk. No login/backend.

4. Wire into brainsnn-r3f-app/src/App.jsx

• Import CognitiveInspectionPanel.
• Render it near the existing Cognitive Firewall / Autopsy panels.
• Pass onApplyToNetwork into the panel.
• onApplyToNetwork should accept a firewall-compatible result from inspectionToBrainResult(inspection) and use existing mapTRIBEToRegions logic in App.

5. Add docs/xio-brain-control-plane.md

Document:

• product thesis
• workflow
• score definitions
• evidence pack schema
• eval strategy
• future API endpoints
• how this differs from a chatbot

Implementation guardrails

• Keep it frontend-only.
• No required external calls.
• No new heavy dependencies unless truly necessary.
• Do not break existing routes, panels, query param sharing, snapshots, or 3D render loop.
• Do not remove existing hackathon features.
• Avoid generic admin-panel language.
• The new panel should feel like a living cognitive inspection console, not a settings page.
• Use existing app styling conventions.
• Keep functions deterministic enough to support evals.

Acceptance criteria

• cd brainsnn-r3f-app && npm install && npm run build passes.
• App still runs with no env vars.
• New Cognitive Inspection panel is visible in the app.
• User can paste text and receive:
  • scorecard
  • evidence flags
  • safer rewrite
  • before/after risk delta
  • exportable Markdown report
• User can run seeded evals and see pass/fail results.
• User can apply inspection result to the 3D brain state.
• Last 10 inspections persist locally.
• Empty, very short, and very long inputs fail gracefully.
• No hidden network calls.

Suggested first vertical slice

Build this in the smallest complete path first:

1. utils/cognitiveInspection.js
2. data/cognitiveInspectionCases.js
3. components/CognitiveInspectionPanel.jsx
4. App import/render wiring
5. Docs
6. Build test

Do not overbuild the API layer yet. First make the product loop undeniable: scan → score → explain → rewrite → prove → apply to brain.