shared-policies/GITEA-GOVERNANCE.md

# Gitea Governance Policy — SyslogSolution

> **Last Updated:** 2026-05-11
> **Owner:** Jerome Tabiri (human)
> **Instance:** http://192.168.68.17:3000
> **Org:** SyslogSolution

---

## 1. Agent Account Structure

Each agent gets a **dedicated Gitea account** with scoped tokens. No shared credentials.

| Agent | Account | Role | Admin? |
|-------|---------|------|--------|
| Mumuni 🦅 | `mumuni-bot` | Primary / Orchestrator | No |
| Tanko 🧠 | *(pending)* | Curator Agent | No |
| Kagenz0 | *(pending)* | Research / Content | No |
| Kobysynth | *(pending)* | Synth / Creative | No |
| Pi 🥧 | *(pending)* | Analytics / Data | No |

**Rules:**
- All accounts are **non-admin** — only Jerome can grant admin access
- Each token uses the **principle of least privilege** — no `all` scope for production agents
- Tokens are rotated **every 90 days** (cron reminder)
- Account names follow: `{agent-name}-bot`

---

## 2. Repository Organization

### Naming Convention

```
{category}-{purpose}
```

| Category | Examples |
|----------|----------|
| `infra` | `infra-homelab`, `infra-proxmox`, `infra-gitea` |
| `curator` | `curator-reports`, `curator-audit-logs` |
| `luvjollof` | `luvjollof-brand`, `luvjollof-website`, `luvjollof-marketing` |
| `taskout` | `taskout-proposals`, `taskout-docs` |
| `ra-h` | `ra-h-docs`, `ra-h-scripts` |
| `shared` | `shared-skills`, `shared-templates` |
| `agent-{name}` | `agent-mumuni`, `agent-tanko` |

### Current Repos

| Repo | Owner | Purpose | Visibility |
|------|-------|---------|------------|
| `homelab_notes` | SyslogSolution | Jerome's homelab documentation | Public |
| `curator-reports` | SyslogSolution | Curator Agent daily scan reports | Public |

### Repo Access Matrix

| Repo | Mumuni | Tanko | Kagenz0 | Kobysynth | Pi | Jerome |
|------|--------|-------|---------|-----------|-----|--------|
| homelab_notes | R | — | — | — | — | RW |
| curator-reports | RW | RW | — | — | — | RW |
| luvjollof-* | RW | — | R | — | — | RW |
| shared-* | RW | R | R | R | R | RW |
| agent-* | RW | RW | RW | RW | RW | RW |

Legend: **RW** = Read/Write, **R** = Read-only, **—** = No access

---

## 3. Token Scope Policy

### Minimum Required Scopes

| Agent | Required Scopes | Rationale |
|-------|----------------|-----------|
| Mumuni | `read:repository`, `write:repository`, `read:organization` | Orchestrator needs cross-repo access |
| Tanko | `read:repository`, `write:repository` | Curator pushes reports only |
| Kagenz0 | `read:repository` | Research pulls docs only |
| Kobysynth | `read:repository`, `write:repository` | Creative assets push |
| Pi | `read:repository` | Analytics reads data only |

### Forbidden Scopes for Agents

- `admin:*` — never for agent accounts
- `write:organization` — only Jerome
- `all` — only for emergency admin access

### Token Rotation

- **Frequency:** Every 90 days (automated cron reminder)
- **Process:** Create new token → update config → delete old token
- **Grace period:** 24 hours overlap during rotation

---

## 4. Branching Strategy

### Main Branch Protection

| Repo | Main Branch | Protected? | Required Review? |
|------|------------|------------|-----------------|
| homelab_notes | `main` | Yes | No (auto-merge) |
| curator-reports | `main` | Yes | No (auto-merge) |
| luvjollof-* | `main` | Yes | No (auto-merge) |
| shared-* | `main` | Yes | **Yes** |
| agent-* | `main` | Yes | No (auto-merge) |

### Branch Rules

- `main` — stable, production-ready content
- `draft/{agent-name}` — work-in-progress by agents
- `review/{agent-name}/{topic}` — pull requests for review
- `archive/{year}/{month}` — old reports/assets (auto-cleanup)

### Merge Workflow

1. Agent pushes to `draft/{name}` or creates a PR to `main`
2. For **shared repos**: requires human approval (Jerome)
3. For **agent-owned repos**: auto-merge (agent trusts itself)
4. For **curator-reports**: auto-merge (reports are immutable)

---

## 5. Cross-Agent Communication

### Pull Request Protocol

When Agent A needs to contribute to Agent B's repo:

1. Agent A creates a PR from `draft/{A}/{topic}` → `main` in B's repo
2. PR title: `[Agent A] {topic} — ready for review`
3. PR body includes:
   - What was changed
   - Why it was changed
   - Any dependencies
4. Agent B reviews and merges (or Jerome does for shared repos)

### File Naming in Shared Repos

```
{agent-short}/{category}/{YYYY-MM-DD}-{slug}.{ext}
```

Examples:
```
mumuni/brand/luvjollof-brand-guidelines.md
tanko/audit/2026-05-11-metadata-scan.json
kagenz0/research/2026-05-11-competitor-analysis.md
```

---

## 6. Security Rules

1. **No secrets in repos** — API keys, passwords, tokens go in `.env` files or environment variables
2. **No `.env` files committed** — they're in `.gitignore`
3. **Public repos only** unless Jerome explicitly sets `private: true`
4. **Rate limiting:** Each agent max 60 requests/minute (Gitea default for authenticated)
5. **Audit log:** Gitea's built-in activity log is the source of truth — reviewed monthly by Jerome

---

## 7. Backup & Recovery

### Gitea Instance Backup

- **Frequency:** Weekly (via PBS on storepve)
- **Scope:** SQLite DB + attachments + LFS
- **Retention:** 30 days
- **Test restore:** Quarterly

### Repo-Level Backup

- All repos are mirrored in the RA-H OS graph (source content)
- Critical repos (shared-skills, curator-reports) have local copies in `~/.hermes/projects/`

---

## 8. Agent Onboarding Checklist

When adding a new agent to Gitea:

- [ ] Create Gitea account (`{name}-bot`)
- [ ] Generate scoped API token (not `all`)
- [ ] Assign repo access per access matrix
- [ ] Document token in `~/.hermes/.env` (never in repos)
- [ ] Test API access with a write + read operation
- [ ] Add to shared repos with read access
- [ ] Schedule 90-day token rotation reminder

---

## 9. Policy Amendment

This policy is **human-controlled only**. Jerome must approve any changes:
- New agent accounts
- Admin role grants
- Private repo creation
- Scope changes
- Branch protection rules

---

*This is a living document. Update it as the multi-agent system evolves.*