The Team Brain: Cognitive Governance Playbook

This is your Team Brain Implementation Playbook. It condenses everything we’ve built—the philosophy, the file structure, the centralized CI logic, and the evaluator—into one source of truth.

Copy this into your README.md or a central GOVERNANCE_PLAYBOOK.md to lock in the strategy.

🧠 The Team Brain: Cognitive Governance Playbook

1. The Core Philosophy

We are building Cognitive Governance, not an "Agent Circus."

* Decoupled Intelligence: Governance is a static contract; agents are merely observers.

* Diff-Only Enforcement: We only judge the change, not the legacy technical debt.

* Centralized Authority: One "Brain" repo governs N-number of service repos.

* Intent as Code: If it isn't in the rules.yaml, it doesn't exist.

2. The Architecture

A. The "Global Brain" Repository (team-brain-governance)

This repo acts as the "Legislative Branch." It contains:

* rules.yaml: The machine-readable "laws."

* governance_check.py: The logic that parses Git diffs against those laws.

* remote_governance.yml: The GitLab CI template that other repos "include."

B. The Service Repositories

These are the "Executive Branch." They simply "opt-in" to the brain via their .gitlab-ci.yml.

3. The Implementation Files

I. The Contract (rules.yaml)

Define your architectural constraints here.

rules:

- id: "NO_ZOD_IN_DOMAIN"

description: "Do not use Zod for domain-level validation; use CTP-1 native types."

pattern: "import .*zod"

level: "fail"

- id: "REQUIRED_LOGGING_ID"

description: "Missing Trace-ID in logging call."

pattern: "logger\.(info|error)\((?!.*trace_id)"

level: "warn"

II. The Evaluator (scripts/governance_check.py)

This script runs in CI, compares HEAD to HEAD^, and emits the signal.

import subprocess, re, yaml, json, sys

def check_governance():

# 1. Get only the added lines from the diff

diff = subprocess.check_output(["git", "diff", "HEAD^", "HEAD", "--unified=0"]).decode("utf-8")

# 2. Load rules from the central brain

with open('/tmp/brain/team-brain/rules.yaml', 'r') as f:

rules = yaml.safe_load(f)

violations = []

for rule in rules.get('rules', []):

matches = re.findall(fr"^\+.*{rule['pattern']}", diff, re.MULTILINE)

if matches:

violations.append({"id": rule['id'], "level": rule['level'], "count": len(matches)})

# 3. Emit Signal

with open('governance-report.json', 'w') as f:

json.dump({"violations": violations}, f, indent=2)

# 4. Gatekeeper

if any(v['level'] == 'fail' for v in violations):

sys.exit(1)

sys.exit(0)

if __name__ == "__main__":

check_governance()

III. The CI Template (remote_governance.yml)

The glue that allows any repo to pull the brain.

governance_enforcement:

stage: test

image: python:3.9-slim

script:

- git clone --depth 1 $GOVERNANCE_REPO_URL /tmp/brain

- python3 /tmp/brain/scripts/governance_check.py

artifacts:

when: always

paths: [governance-report.json]

4. How to Roll Out

Step 1: Create the Brain

Initialize the team-brain-governance repo with the files above.

Step 2: Connect a Service

In any existing project repo, add these lines to the top of .gitlab-ci.yml:

include:

- project: 'your-org/team-brain-governance'

file: '/remote_governance.yml'

Step 3: Observe the Signal

* Failures: Block the Merge Request (MR).

* Warnings: Allow the MR but appear in the governance-report.json.

* Agents (Optional): Point an LLM at the governance-report.json to write "How-to-fix" comments on the MR.

5. Why This is "Fucking Perfect"

* Scales: 1 repo or 1,000 repos.

* Language Agnostic: Regex doesn't care if it's Java or Go.

* Human-Centric: Focuses on architectural intent, not just linting tabs vs spaces.

Next Step: Whenever you're ready to flip the switch, would you like me to help you write the Regex patterns for your first three "Must-Have" architectural rules?