Sovereign Governance

“One source of truth. Everything else is a pointer.”

Overview

This skill enforces a unified governance model across a multi-repo AI agent ecosystem. It solves the core problem: governance drift — where AGENTS.md files, state files, and skills duplicate across repos, diverge, and cause agents to follow conflicting rules.

The Architecture

/Users/nico/Nico_Archive/AGENTS.md     <- THE ONE. Canonical. 5,900+ lines.
        |
        |-- repo-1/AGENTS.md           <- 36-line pointer
        |-- repo-2/AGENTS.md           <- 36-line pointer
        |-- repo-3/AGENTS.md           <- 36-line pointer
        |-- repo-N/AGENTS.md           <- 36-line pointer
        '-- [any new repo]/AGENTS.md   <- 36-line pointer (auto-generated)

Core Principles

1. One canonical AGENTS.md — lives in Nico_Archive (The Source of Truth), above all repos
2. Every repo gets a pointer — not a copy, not a subset, not a “local version”
3. Documentation stays per-repo — docs/ directories are NOT consolidated. Work happens where the code is.
4. Governance crosses boundaries — only AGENTS.md, state file schemas, and skill standards are unified
5. Enforcement is automated — shell aliases, git hooks, and validation scripts

When to Use This Skill

ALWAYS invoke this skill when:

The Canonical Source

/Users/nico/Nico_Archive/AGENTS.md

This file contains ALL governance:

• Agent role assignments and hierarchy
• Task execution protocols
• Git workflow standards
• Deployment procedures
• Testing requirements
• Security protocols
• Section 31: Sovereign Artifact Governance Stack v3.0

No other file may contain governance rules. If you find governance rules in a repo-level file, it’s a violation.

Pointer Template

Every repo MUST have an AGENTS.md at root that looks exactly like this. Fill in the repo-specific fields:

# AGENTS.md — POINTER FILE

**DO NOT add governance rules to this file.**
**DO NOT duplicate protocol from the canonical source.**

## Canonical Source

All agent protocol, governance, skills, coordination, and compliance rules live in ONE place:

\`\`\`
/Users/nico/Nico_Archive/AGENTS.md
\`\`\`

**Location:** `Nico_Archive` (The Source of Truth)
**Section 31:** Sovereign Artifact Governance Stack v3.0
**Authority:** Nicolae Fratila (Founder/CEO)

## This Repo

| Field | Value |
|-------|-------|
| **Repo** | `REPO_NAME` |
| **Purpose** | DESCRIPTION |
| **Governance Level** | SOVEREIGN / STRATEGIC / TACTICAL / OPERATIONAL |
| **Status** | ACTIVE / REFERENCE / ARCHIVED |

## What To Do

1. Open `/Users/nico/Nico_Archive/AGENTS.md`
2. Read it. Follow it.
3. If a rule here conflicts with the canonical — canonical wins. Always.

---

*This is a pointer file. The canonical AGENTS.md is in Nico_Archive.*
*Last synced: YYYY-MM-DD*

Governance Levels

Artifact Classification

State File Standard

.agent_sync_state.json Schema

Every repo MUST have this file at root. Schema:

{
  "$schema": "apex-os-agent-sync-v3",
  "session": {
    "id": "unique-session-identifier",
    "started_at": "ISO 8601",
    "mode": "NORMAL | EMERGENCY | SAFE_MODE"
  },
  "orchestrator": {
    "agent": "agent-name",
    "status": "ACTIVE | STANDBY | OFFLINE",
    "last_heartbeat": "ISO 8601"
  },
  "current_mission": {
    "name": "human-readable mission name",
    "priority": "P0 | P1 | P2 | P3",
    "target": "what we are achieving",
    "deadline": "ISO 8601 or null",
    "progress_pct": 0
  },
  "agents": {
    "@agent-name": {
      "status": "ACTIVE | STANDBY | BLOCKED | OFFLINE",
      "current_task": "exactly what they are doing NOW",
      "files_locked": [],
      "last_update": "ISO 8601",
      "blockers": []
    }
  },
  "file_locks": {},
  "phases": {},
  "last_updated": "ISO 8601",
  "next_action": "what happens next"
}

State File Rules

Skills Governance

Directory Hierarchy (Authority Order)

1. ~/.config/opencode/skills/          <- User-level (highest priority)
2. [repo]/.agents/skills/              <- Project-level
3. [repo]/.opencode/skills/            <- OpenCode-specific (lowest priority)

Skills Rules

Deduplication Check

Before creating or modifying a skill, check all 3 directories:

# Check for duplicates
ls ~/.config/opencode/skills/ | sort > /tmp/user_skills
ls .agents/skills/ 2>/dev/null | sort > /tmp/project_skills
ls .opencode/skills/ 2>/dev/null | sort > /tmp/opencode_skills
comm -12 /tmp/user_skills /tmp/project_skills  # Shows duplicates

If a duplicate exists, keep the user-level version and remove the project-level one.

Registry Protocol

Decision Log

Location: [primary-repo]/docs/registry/decision-log.md Type: Append-only. Never delete or edit past entries.

Log a decision when:

• Choosing technology, framework, or service provider
• Changing AI model routing or fallback order
• Modifying sovereign config files
• Adding or removing a repo from the ecosystem
• Changing deployment targets
• Any breaking API/schema change

Format:

## YYYY-MM-DD

- **[CATEGORY] Decision title**
  - Rationale: Why
  - Alternatives: What else was evaluated
  - Reference: Link to artifact/commit
  - Impact: What changes
  - Owner: Who decided

Categories: ARCH | INFRA | MODEL | SECURITY | DEPLOY | DATA | SKILL | PROCESS

Session State Log

Location: [primary-repo]/docs/registry/session-state.md Type: Append-only.

Entry format:

## YYYY-MM-DD

- **Session focus:** One-line description
- **Current phase:** Where in the broader plan
- **Artifacts referenced:** List of artifacts read/modified
- **Artifacts created:** New artifacts with IDs
- **Decisions made:** Summary (details in decision-log.md)
- **Blockers:** Any blockers
- **Notes:** Free-form

Last updated: ISO 8601

Artifact Registry

Location: [primary-repo]/docs/registry/artifact-registry.md

Naming convention:

Agent Startup Protocol

Every agent MUST follow this sequence on activation:

STEP 1: Read repo's AGENTS.md
        -> If pointer (< 50 lines, "POINTER FILE"): follow to Nico_Archive
        -> If full copy (> 50 lines): GOVERNANCE VIOLATION. Follow canonical.

STEP 2: Read canonical AGENTS.md from Nico_Archive

STEP 3: Read .agent_sync_state.json
        -> Check for active missions, file locks, blockers

STEP 4: Read docs/registry/session-state.md
        -> Understand previous session context

STEP 5: Read docs/registry/decision-log.md
        -> Know recent decisions

STEP 6: Update .agent_sync_state.json
        -> Register self as active agent

STEP 7: Begin work

Compliance Violations

Escalation Path

Agent detects issue
     |
     v
 Classify severity
     |
     +-- LOW:      Log it. Fix inline. Continue.
     +-- MEDIUM:   Log it. Fix inline. Flag in session-state.md.
     +-- HIGH:     Log it. Fix immediately. Flag in decision-log.md.
     +-- CRITICAL: STOP ALL WORK. Log. Escalate to Founder. Do not continue.

Enforcement

Shell Aliases

Add to ~/.zshrc or ~/.bashrc:

# APEX OS Governance
alias enforce='/Users/nico/Nico_Archive/enforce-agents-governance.sh'
alias enforce-fix='/Users/nico/Nico_Archive/enforce-agents-governance.sh --fix'

Git Pre-Commit Hook

Install globally so it fires in every repo:

mkdir -p ~/.config/git/hooks
git config --global core.hooksPath ~/.config/git/hooks

The hook checks AGENTS.md on every commit. If it’s stale (not a pointer), the commit is blocked.

Hook location: ~/.config/git/hooks/pre-commit

Enforcement Script

Location: /Users/nico/Nico_Archive/enforce-agents-governance.sh

# Audit mode (report violations)
enforce

# Fix mode (replace all stale copies with pointers)
enforce-fix

The script:

1. Verifies canonical AGENTS.md exists in Nico_Archive
2. Scans ALL repos (maxdepth 2 from home directory)
3. Classifies each AGENTS.md as COMPLIANT or STALE
4. In --fix mode: replaces stale copies with properly classified pointers
5. Reports compliance percentage

Cross-Repo Documentation Policy

Governance is centralized. Documentation is NOT.

New Repo Checklist

When creating ANY new repo in the APEX OS ecosystem:

[ ] 1. Create repo
[ ] 2. Add AGENTS.md using pointer template (see above)
[ ] 3. Add README.md with repo purpose
[ ] 4. Add .gitignore (exclude .env, node_modules, .next, dist)
[ ] 5. Add .env.example if repo has environment variables
[ ] 6. Add .agent_sync_state.json following schema
[ ] 7. Add docs/registry/ directory if this is a primary repo
[ ] 8. Run `enforce` to verify compliance
[ ] 9. Initial commit and push

Quick Reference

+---------------------------------------------------------------+
|  SOVEREIGN GOVERNANCE — QUICK REFERENCE                        |
+---------------------------------------------------------------+
|                                                                 |
|  CANONICAL:  /Users/nico/Nico_Archive/AGENTS.md                |
|                                                                 |
|  AUDIT:      enforce                                           |
|  FIX:        enforce-fix                                       |
|                                                                 |
|  NEW REPO:   Copy pointer template -> fill in fields -> done   |
|                                                                 |
|  VIOLATION:  AGENTS.md > 50 lines in any repo = STALE          |
|  RESPONSE:   Replace with pointer. Log it. Move on.            |
|                                                                 |
|  DOCS:       Stay per-repo. Never consolidate.                 |
|  GOVERNANCE: One file. Nico_Archive. That's it.                |
|                                                                 |
|  STATE FILE: .agent_sync_state.json — one schema everywhere    |
|  SKILLS:     User-level wins over project-level                |
|                                                                 |
+---------------------------------------------------------------+

Sovereign Governance Skill v1.0 “One source of truth. Everything else is a pointer.”