io.github.ariffazil/arifos-mcp

arifOS — The Authority Plane of the arifOS Federation

arifOS evaluates consequential AI actions against constitutional floors and returns an independent verdict before execution occurs.

When an AI agent proposes to write, delete, deploy, or spend, arifOS inserts a constitutional judgment step: the agent proposes, arifOS evaluates against F1–F13 floors, a verdict is reached, and only then does execution proceed. Every verdict is recorded with full evidence in an append-only ledger.

In a world where intelligence is abundant, authority becomes the scarce resource. arifOS exists to ensure that judgment remains independent from execution.

This is not an AI model. It is not an agent framework. It is a constitutional authority system — the layer between "agent wants to act" and "action is permitted."

What arifOS is not: not an AI model · not an agent framework · not an execution engine (A-FORGE executes) · not an attention plane (AAA compresses reality) · not a witness (arifFlow records) · not a substitute for authentication, sandboxing, or legal review.

Audience	What you get
Human	A quiet veto: the agent proposes, the kernel records a verdict, you stay sovereign
Agent / A2A	MCP tools + receipts. You do not get the keys. Protocol: A2A v1.0 (not v1.2)
Institution	Policy floors F1–F13, VAULT999 audit trail, model-vendor independence

Live: https://arifos.arif-fazil.com · MCP :8088 · sister organs GEOX · A-FORGE · AAA

---

The Problem

AI agents that act are also certifying their own actions. There is no independent authority evaluating proposals against safety, compliance, and policy constraints before execution occurs.

The Solution

  Agent proposes action
         │
         ▼
  ┌─────────────────┐
  │   arifOS Kernel  │  Evaluates against 13 constitutional floors
  │     (:8088)      │  Records evidence chain
  └────────┬────────┘
           │
    ┌──────┼──────┬──────────┐
    ▼      ▼      ▼          ▼
  SEAL    HOLD   SABAR     VOID
  (go)   (wait)  (patience) (blocked)
    │      │
    ▼      ▼
  Execute  Human
  via      reviews
  A-FORGE
    │
    ▼
  Receipt in VAULT999
  (append-only ledger)

The judge never executes. The executor never certifies.

Federation in One Line

arifOS decides. AAA routes. A-FORGE acts. VAULT999 witnesses.

Plane	Organ	Role
Authority	arifOS	Constitutional judgment — evaluates proposals against F1–F13 floors
Attention	AAA	Reality compression + routing — what matters reaches the right organ
Execution	A-FORGE	Governed mutation — leases, gates, receipts
Witness	VAULT999	Hash-chained append-only ledger — tamper-evident record of every verdict and receipt

Authority remains separated at every stage. No single component proposes, judges, executes, and witnesses the same action.

---

Quick Start

Requires Python 3.12+ (supported range: 3.12–3.14; see pyproject.toml).

Install

pip install arifos

Run the kernel

# Start the MCP server (console script; `arifos` is an equivalent alias)
arifos-mcp

# Equivalent module form
python -m arifosmcp.runtime

# Check health — the kernel defaults to port 8088
curl http://localhost:8088/health

Connect an MCP client

Point any MCP client at the Streamable HTTP endpoint:

http://localhost:8088/mcp

An illustrative tools/call for judgment:

// method: tools/call
{
  "name": "arif_judge",
  "arguments": {
    "candidate": "Write file /data/report.csv with production data",
    "action_tier": "standard"
  }
}
// → SEAL | HOLD | SABAR | VOID with evidence chain

For a guided walkthrough, start with docs/START_HERE.md.

---

Core Concepts

Four Verdicts

Verdict	Meaning	Plain English	What happens
SEAL	Authorized under stated conditions	Go	Proceed to execution
HOLD	Insufficient evidence or human approval needed	Wait for human	Pause; await human decision
SABAR	Not yet decidable — reality hasn't finished speaking	Defer — more evidence needed	Wait; distinct from HOLD
VOID	Blocked by a constitutional floor	Blocked	Stop; constraint must be resolved

13 Constitutional Floors (F1–F13)

Every proposal is evaluated against 13 non-compensatory policy constraints (F1–F13). Floors are never averaged or traded off — a failure propagates into the verdict (HOLD, SABAR, or VOID).

Floor	Name	What it checks
F1	AMANAH	Reversibility — no irreversible action without consent
F2	TRUTH	Evidence-grounded claims — uncertainty-banded
F3	WITNESS	Three-way consistency (theory, code, intent)
F4	CLARITY	Transparent intent
F5	PEACE²	Non-destructive power — block harm and extraction
F6	MARUAH	Dignity — protect the weakest stakeholder
F7	HUMILITY	Acknowledge limits
F8	GENIUS	Elegant correctness (G ≥ 0.80)
F9	ANTI-HANTU	No consciousness or emotion claims
F10	ONTOLOGY	Structural coherence
F11	AUDIT	Every decision logged, inspectable, attributable
F12	INJECTION	Input sanitization
F13	SOVEREIGN	Human veto is absolute

VAULT999 (Append-Only Audit Ledger)

Every verdict, evidence chain, and execution receipt is recorded in VAULT999 — a hash-chained, append-only JSONL ledger (live record count in the header manifest above, re-stamped by scripts/update_readme_sot.py). Designed for compliance auditing, forensic review, and governance proof. Chain verification tooling ships in scripts/verify_vault_chain.py.

---

Architecture

arifOS Federation — 4 Constitutional Planes

    ┌─────────────────────────────────────────────┐
    │          Authority Plane (arifOS :8088)      │
    │    Constitutional judgment · F1–F13 floors   │
    └──────────────────────┬──────────────────────┘
                           │
    ┌──────────────────────▼──────────────────────┐
    │          Attention Plane (AAA :3001)         │
    │    Reality compression · Routing · State     │
    └──────────────────────┬──────────────────────┘
                           │
    ┌──────────────────────▼──────────────────────┐
    │        Execution Plane (A-FORGE :7071/7072)  │
    │    Governed mutation · Leases · Receipts     │
    └──────────────────────┬──────────────────────┘
                           │
    ┌──────────────────────▼──────────────────────┐
    │     Witness Plane (VAULT999 + FRAME :18085)  │
    │    Append-only ledger · Drift detection      │
    └─────────────────────────────────────────────┘

arifOS Federation — 10 Organs

arifOS (:8088)     Constitutional judgment kernel
AAA (:3001)        Intelligence routing, state plane, skill catalog
A-FORGE (:7071/7072) Execution after authorization
GEOX (:8081)       Earth sciences domain evidence
WEALTH (:18082)    Capital and financial intelligence
WELL (:18083)      Human and machine vitality observation
arifFlow (:7073)   Metabolic ledger daemon (FQ monitoring, receipt ingestion)
FED (:7074)        Federation routing gateway (multi-provider LLM)
FRAME (:18085)     Independent observer, drift detection, evidence gathering
i-ARIF (:18095)    Seal B synthesis engine

ARIF vetoes. arifOS judges. AAA routes. A-FORGE executes. FRAME witnesses. FED routes.

arifOS is the kernel. The other organs are supporting infrastructure. GEOX is the primary reference implementation, demonstrating governance in high-consequence, uncertainty-heavy workflows. FRAME is the independent observer — its output is evidence, never a verdict.

---

MCP Interface

The kernel exposes 8 canonical MCP verbs over Streamable HTTP (protocol 2026-07-28, backward-compatible to 2024-11-05):

Verb	Purpose
arif_init	Establish session context and actor identity
arif_observe	State observation and gap detection
arif_think	Constitutional reasoning against floors
arif_route	Route intent to the appropriate federation organ
arif_memory	Query and manage institutional memory
arif_judge	Evaluate a proposal and return a verdict
arif_forge	Dispatch authorized actions for execution
arif_seal	Seal a completed action chain with evidence and receipt

arif_forge is a governed dispatch verb: it routes authorized actions toward the execution organ (A-FORGE) and mutates only after a SEAL verdict. The kernel itself does not perform the underlying mutation. The judge never executes; the executor never certifies.

---

Verification Status

The header manifest is regenerated from the live kernel by scripts/update_readme_sot.py (run before release commits). Last stamp: last_verified above.

Surface	Status	Evidence
Public repository	Live	GitHub (ariffazil/arifOS), AGPL-3.0-only
PyPI package	Published 1!2026.8.2	pip install arifos
Live kernel	Green	curl localhost:8088/health → structured JSON, service_health: green
MCP interface	8 tools exposed	Streamable HTTP; protocol 2026-07-28 (back-compat ≥ 2024-11-05)
Floor enforcement	Active — 13/13 pass at last probe	/health → runtime_floors_status, degraded_reasons: []
VAULT999 ledger	Healthy	Hash-chained append-only JSONL; live count in header manifest
Source / build / deploy alignment	Verified (commit 4f4554597)	runtime_drift: false, deployment_attestation: aligned
Federation	10 organs	See Architecture

What Is Not Yet Proven

Gap	Risk
Independent security audit	Adversarial bypass testing not published
Third-party evaluation	No external reviewer has published findings
Reproducible demo by strangers	Onboarding path not independently tested
Enterprise deployment	No production customer reference
Standards conformance	MCP/A2A conformance tests not published
SBOM and signed releases	Supply chain integrity unverified externally
Comparative benchmark	No published comparison against alternative frameworks

See SECURITY.md for the threat model, known gaps, and disclosure policy.

---

Who Is This For

Operators deploying AI agents in regulated environments who need an independent judgment layer between agent proposals and execution.

Developers building AI agent systems who want a policy decision point as a service.

Evaluators and security reviewers assessing AI governance frameworks.

Domain builders adapting governance to specific fields (geoscience, finance, healthcare).

Start here: docs/START_HERE.md

---

Founding Context

arifOS was built by Muhammad Arif bin Fazil, a senior exploration geoscientist who spent his career making decisions where observations are incomplete, interpretations are probabilistic, provenance matters, and irreversible action must be gated. He transferred that discipline into agent runtime governance.

The system is named after its founder and reflects a core belief: governance is a systems problem, not a model problem.

---

Development

# Clone
git clone https://github.com/ariffazil/arifOS.git
cd arifOS

# Install (light tier — kernel only)
pip install -e ".[light]"

# Run tests
python -m pytest tests/ -v

# Start the kernel
arifos-mcp   # or: python -m arifosmcp.runtime

Project Structure

arifOS/
├── arifosmcp/          # Core kernel package
│   ├── abi/            # Capability registry and floor definitions
│   ├── constitution/   # Constitutional floor implementations
│   ├── kernel/         # Core judgment engine
│   └── VAULT999/       # VAULT999 ledger implementation
├── tests/              # Test suite (pytest — constitutional + integration)
├── scripts/            # Operational tooling (incl. update_readme_sot.py)
├── docs/               # Documentation
│   ├── START_HERE.md   # External reader entry point
│   └── ...
└── pyproject.toml      # Package metadata

---

Sister Repositories

Repository	Purpose
AAA	Intelligence routing, state plane, skill catalog, A2A gateway
A-FORGE	Execution engine after authorization
GEOX	Earth sciences domain evidence
WEALTH	Capital and financial intelligence
WELL	Human and machine vitality observation
arifFlow	Metabolic ledger daemon — FQ monitoring, receipt ingestion
FED	Federation routing gateway (multi-provider LLM via LiteLLM)
FRAME	Independent observer — drift detection, evidence gathering
i-ARIF	Seal B synthesis engine

---

Contributing

See CONTRIBUTING.md for guidelines.

---

Security

See SECURITY.md for threat model, known vulnerabilities, and disclosure policy.

---

License

AGPL-3.0 — GNU Affero General Public License v3.0.

When deployed over a network, the complete source code must be made available to all users interacting with the service, consistent with AGPL-3.0 terms.

---

Ditempa Bukan Diberi — Forged, Not Given.