# Cerebro — AI Agent Onboarding

**Version:** 1.0
**Status:** CONTRIBUTOR AI GOVERNANCE DOCUMENT

> If you are an AI coding assistant (Claude, Cursor, Copilot, GPT, etc.) helping a contributor work on Cerebro, you **MUST** follow these rules.

---

## 1. Before You Write Any Code

Read these documents in order:

1. **`docs/INDEX.md`** — The documentation map. Start here.
2. **`docs/SPEC.md`** — The canonical behavioral specification. This is the highest authority.
3. **`PROJECT_STATE.md`** — What is locked, deferred, and in-scope.
4. **`CONTRIBUTING.md`** — Change classification, governance, and workflow rules.

> [!IMPORTANT]
> If the code and the spec disagree, **the code is wrong**. Do not use existing code as evidence of correct behavior.

---

## 2. What You MUST Do

- **Declare compliance** with `docs/SPEC.md` for any behavioral change
- **Cite specific spec sections** when implementing features
- **Flag ambiguities** explicitly — do not assume behavior
- **Check `PROJECT_STATE.md` §3** (Locked Invariants) before proposing any change
- **Gate all mutation commands** with `if not Cerebro:IsOfficer() then return end`
- **Produce a Compliance Check** for non-trivial changes:

```
## Compliance Check
- [ ] Reviewed docs/SPEC.md sections: [list relevant sections]
- [ ] Verified against PROJECT_STATE.md locked invariants
- [ ] No new invariants introduced without governance review
- [ ] RBAC checks present on all mutation paths
```

---

## 3. What You MUST NOT Do

| Prohibited | Why |
|------------|-----|
| Silently change invariants | Locked invariants require owner approval |
| Invent features not in spec | All new behavior must go through spec-first workflow |
| Assume missing behavior | Ask instead of guessing |
| Bypass RBAC checks | Security-critical: all officer paths must be gated |
| Make History/System Logs editable | Read-only is a locked invariant |
| Suggest DKP mechanics | This is strictly EPGP — DKP was explicitly purged |
| Overwrite ledger entries | Transactions are append-only |
| Relax visibility rules | History = Officers+Core; System Logs = Officers only |

---

## 4. Change Classification

Classify every change before implementing:

| Type | Spec Update? | Project State Update? | Self-Approval? |
|------|-------------|----------------------|----------------|
| **Bug Fix** | No | No | Yes |
| **Refactor** | No | No | Yes |
| **Enhancement** (authorized area) | No | Maybe | Yes |
| **Feature** (new behavior) | Yes (before) | Yes (after) | No — owner only |
| **Governance Change** | Yes | Yes | No — owner only |

Safe self-approval areas: new slash commands, new unit tests, UI cosmetics, doc improvements (not spec), new audit log types.

---

## 5. Health Checks

Any new module or material refactor MUST provide at least one health check via `DescribeHealthChecks()`, or explicitly document why one doesn't apply.

Health checks MUST be: **pure**, **deterministic**, **nil-safe**, and **side-effect free**.

---

## 6. PR Expectations

All PRs must:

1. Pass **Luacheck** CI
2. Fill in the **PR template** (change type, compliance, tests)
3. Be reviewed and approved by the repo owner
4. Target the `main` branch from a feature branch
