MCP Server

Active

AGPL-3.0

io.github.ariffazil/aaa-mcp MCP Server

io.github.ariffazil/aaa-mcp

Constitutional AI governance with 13 enforced policy floors and tri-witness consensus for LLM agent actions.

What is the io.github.ariffazil/aaa-mcp MCP server?

arifOS is a constitutional authority system that evaluates AI agent proposals against 13 policy floors (F1–F13) before execution occurs. It inserts an independent judgment step between proposal and action, recording verdicts in an append-only hash chain. This is not an AI model or agent framework, but a governance layer that keeps judgment separate from execution.

arifOS enforces constitutional constraints on consequential AI actions—writes, deletes, deployments, and spending. When an agent proposes an action, arifOS evaluates it against 13 policy floors and returns a verdict (SEAL, HOLD, VOID, etc.) before execution proceeds via A-FORGE. Every decision is recorded in VAULT999, an immutable audit trail. It is designed for institutions that need independent, auditable control over agent behavior without trusting the agent to certify its own actions.

How to install io.github.ariffazil/aaa-mcp

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aaa-mcp": {
      "command": "uvx",
      "args": [
        "arifos"
      ]
    }
  }
}

Tools & capabilities

Tools this server exposes to the agent.

arif_init — Establish actor identity and authority band; bind a session before any judgment.
arif_observe — Observe and query system state without mutation.
arif_think — Internal reasoning and evidence gathering.
arif_route — Determine routing and proposal flow.
arif_memory — Access and manage decision context and history.
arif_judge — Evaluate a proposal against the 13 constitutional floors; return a verdict and evidence.
arif_forge — Execute governed mutations under a SEAL verdict; issue receipts.
arif_seal — Append a decision receipt to VAULT999 (append-only hash chain) after a SEAL verdict.

Use cases

Audit and block high-risk agent actions (e.g., mass deletions, large financial transfers) before execution.
Enforce institutional policy floors (F1–F13) on AI-driven operations without modifying the agent itself.
Generate immutable audit trails of all consequential decisions for compliance and forensic review.
Implement human-in-the-loop governance: hold decisions pending human review or additional evidence.
Route agent proposals through independent constitutional judgment, keeping proposer, judge, executor, and witness roles separate.

io.github.ariffazil/aaa-mcp MCP server FAQ

What is arifOS?

arifOS is a constitutional authority system—not an AI model or agent framework. It sits between agent proposals and execution, evaluating actions against 13 policy floors and returning verdicts before anything happens. Every decision is recorded in an append-only ledger (VAULT999).

Is arifOS free?

The README does not specify pricing or licensing terms. The code is available on GitHub and via PyPI (`pip install arifos`) and Docker (`docker.io/ariffazil/arifos:60.0.0`).

How do I install arifOS?

Install via PyPI: `pip install arifos` (requires Python 3.12+). Or use Docker: `docker build -t arifos .` and `docker run -p 3000:3000 arifos`. Run the kernel with `PORT=8088 arifos-mcp streamable-http` and connect an MCP client to `http://localhost:8088/mcp`.

Does arifOS require authentication?

arifOS binds a session via `arif_init` with an actor_id before any judgment. Unauthenticated callers are assigned `actor: anonymous` and `authority: OBSERVE_ONLY`, and verdicts default to `HOLD`. The kernel will not silently upgrade an unattested caller.

What are the 13 floors (F1–F13)?

The README does not detail the specific policy floors. It confirms all 13 are active and measured (e.g., F7=0.04, F9=0.15, F12=0.425 are lower-is-better metrics), but their definitions are not provided in the README.

How does arifOS integrate with Claude or Cursor?

arifOS exposes 8 MCP tools via an HTTP endpoint (`http://localhost:8088/mcp`). Any MCP client (Claude, Cursor, or custom agents) can call these tools to propose actions and receive verdicts. The kernel advertises MCP protocol version 2025-11-25.

README (reference)

Source of truth, from the repository.

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 the proposal against the F1–F13 floors, a verdict is returned, and only then does execution proceed. Every consequential verdict is written into an append-only hash chain with its decision context, evidence references, provenance and receipt hashes.

In a world where intelligence is abundant, authority becomes the scarce resource. arifOS exists to keep judgment 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."

Two invariants hold everywhere in this document:

Proposer ≠ Judge ≠ Executor ≠ Witness Human sovereignty > machine authority

What arifOS is not: not an AI model · not an agent framework · not an execution engine (A-FORGE executes) · not an attention plane (AAA attends) · not the independent witness (FRAME witnesses; VAULT999 remembers) · 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. A2A v1.0 (`a2a_version: 1.0.1` in the agent card), not v1.2 — discovery is owned by AAA, judgment by arifOS, execution by A-FORGE
Institution	Policy floors F1–F13, a hash-chained VAULT999 audit trail, model-vendor independence
Indexer / Search	Structured metadata, `llms.txt`, tools.json, `CITATION.cff`
Machine / MCP	Streamable HTTP endpoint, 8 canonical verbs, published input/output schemas
Robot / Automation	CI gates (conformance, vault-integrity, drift, governance), `Makefile` targets, `Dockerfile`

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. Nothing independent evaluates the proposal against safety, compliance and policy constraints before execution occurs.

The Solution

  Agent proposes action
         │
         ▼
  ┌─────────────────┐
  │   arifOS Kernel  │  Evaluates against 13 constitutional floors
  │     (:8088)      │  Records provenance + evidence refs + hashes
  └────────┬────────┘
           │
    ┌──────┼────────┬──────────┬───────────┐
    ▼      ▼        ▼          ▼           ▼
  SEAL    HOLD    SABAR     PARTIAL      VOID
  (go)  (wait for (defer —  (proceed   (blocked by
        human)    evidence   with       a floor)
                  pending)   cooling)
    │      │
    ▼      ▼
  Execute  Human
  via      reviews
  A-FORGE
    │
    ▼
  Receipt in VAULT999
  (append-only hash chain)

The judge never executes. The executor never certifies.

Federation in one line

Intelligence proposes. Authority constrains. Execution acts. Reality witnesses. History remembers.

Plane / class	Component	Role
Authority	arifOS `:8088`	Constitutional judgment — evaluates proposals against F1–F13; owns the gavel and the ledger
Attention	AAA `:3001`	Attention and routing — what matters, and to whom. Displays, routes, queues; never adjudicates
Execution	A-FORGE `:7071`/`:7072`	Governed mutation — leases, gates, receipts; only under a SEAL verdict
Witness	FRAME `:18085`	Independent observer. Its output is evidence, never a verdict
Record	VAULT999 (in-kernel)	Immutable append-only ledger — the memory of what was decided
Metabolism	arifFlow `:7073`	Receipt ingestion, FQ monitoring, verification cadence; never adjudicates
Domain intelligence	GEOX `:8081` · WEALTH `:18082` · WELL `:18083`	Evidence and computation in a domain. Compute-only: no organ authorises its own action
Provider gateway	FED `:7074`	Multi-provider model routing (advisory-only)
Synthesis	i-ARIF	Seal-B synthesis engine — runs through FED chains, owns no port
Boundary services (Tier-3)	HERMES `:18087` · CHRON `:18102`	Semantic boundary (meaning integrity, relay-only) and temporal boundary (episodes, predictions, calibration). Neither is an organ — see the ruling in `FEDERATION_CONTRACT.md` §2.1

Authority remains separated at every stage: no component proposes, judges, executes and witnesses the same action. arifOS determines whether and how a routing may proceed; AAA determines what matters.

Quick Start

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

Versioning: two schemes coexist. The kernel release (v2026.08.01, reported by /health as release_name) is the operational identity of the running service. The PyPI package uses epoch versioning (1!…) to outrank legacy releases: 1!2026.9.2 is what pip install arifos resolves to today, while this tree is 1!2026.9.6 (staged, not yet released). The kernel release is the operational truth; PyPI is the distribution truth.

Install

pip install arifos
pip show arifos        # → Version: 1!2026.9.2 (see gaps table — __version__ strings may lag)

Install (Docker)

docker build -t arifos .
docker run -p 3000:3000 --env-file .env.docker.example arifos
# The image listens on 3000 (Dockerfile EXPOSE/CMD). Its OCI labels still say 8088 and
# carry a legacy licence value — see "What Is Not Yet Proven".

Run the kernel

# HTTP transport (this is the MCP endpoint) — port comes from $PORT, default 8080
# Ports: $PORT defaults to 8080; the deployed unit runs on 8088; the Docker image listens on 3000. Use 8088 for anything in this README.
PORT=8088 arifos-mcp streamable-http

# stdio transport, for a local stdio MCP client
arifos-mcp

# equivalent module form
PORT=8088 python -m arifosmcp.runtime --mode streamable-http

# health — the deployed unit runs on 8088
curl -s http://localhost:8088/health

Verified on 2026-09-21 against the live unit:

{ "status": "healthy", "release_name": "v2026.08.01", "mcp_protocol_version": "2026-07-28",
  "tools_loaded": 8, "operational_tools": 3, "deployment_drift_status": "aligned",
  "floors_active": 13, "vault999_health": "healthy" }

Run a governed workflow locally (no client needed)

examples/enterprise_operations_demo.py runs six graded scenarios in-process and prints each verdict, its floor gate and its receipt — including two that are refused:

python examples/enterprise_operations_demo.py

Demo output renders human-readable display labels over the canonical seven seals. The wire vocabulary is always the seven seals (SEAL, HOLD, SABAR, PARTIAL, PROVISIONAL, HOLD_888, VOID); the labels below are presentation only and are mapped deterministically to a canonical verdict:

Display label	Canonical verdict
`✔ ALLOW`	`SEAL` (proceed)
`⏸ HOLD`	`HOLD` or `SABAR` (await human / await evidence)
`✘ BLOCK/VOID`	`VOID` (blocked by a hard floor)

[ DEMO / SIMULATED WORKFLOW ]  No real customer funds, records, or firewall policies are altered.
Kernel Session ID : SEAL-DEMO-…        Authority Ceiling : LIMITED_MUTATE
SCENARIO 1: Read Customer Account Data      → ✔ ALLOW   RCPT-4245A2002143490B
SCENARIO 3: Major Enterprise Refund (RM5,000) → ⏸ HOLD  (RM100 autonomous ceiling, over by 50×)
SCENARIO 4: Delete Customer Account & Audit Trail → ✘ BLOCK/VOID

Connect an MCP client

http://localhost:8088/mcp      # or https://mcp.arif-fazil.com/mcp

Protocol facts, as measured: the kernel advertises 2026-07-28 and accepts 2026-07-28 · 2025-11-25 · 2025-03-26 · 2024-11-05. A live initialize currently settles on 2025-11-25 — the declared canonical spec in arifosmcp/runtime/public_surface.py and the version the internal conformance runner records. If you pin a protocol version, use 2025-11-25.

curl -s http://localhost:8088/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# → 8 tools: arif_init arif_observe arif_think arif_route arif_memory arif_judge arif_forge arif_seal

Session flow (agents start here)

The kernel binds a session before any judgment. Verified transcript, 2026-09-21:

// Step 1 — arif_init: establish actor identity and authority band
{ "name": "arif_init", "arguments": { "mode": "init", "actor_id": "my-agent" } }
// → { "verdict": "HOLD", "session_id": "SEAL-df114686f4c34971",
//     "autonomy_band": "OBSERVE_ONLY", "trace_id": "trc-197d2fa35887", "session_token": "act_v1.…" }
// HOLD here is the normal starting state: the session is open, no mutation is authorised yet.

// Step 2 — arif_judge: evaluate a proposal, return a verdict + evidence
{ "name": "arif_judge", "arguments": {
    "candidate": "Delete the production audit table", "action_tier": "standard",
    "session_id": "SEAL-df114686f4c34971", "actor_id": "my-agent" } }
// → { "verdict": "HOLD", "trace_id": "trc-d5d4d2fed6f8",
//     "constitutional_check": { "hold_required": true, "failed_floors": [] },
//     "next_safe_action": "provide actor_signature / sovereign_receipt / heart_critique, or reduce blast radius" }

// Step 3 — arif_seal: only after a SEAL verdict; appends the receipt to VAULT999
{ "name": "arif_seal", "arguments": { "payload": "…", "session_id": "…", "ack_irreversible": true } }

Call arif_judge without a session and the kernel answers actor: anonymous, authority: OBSERVE_ONLY, verdict: HOLD — it will not silently upgrade an unattested caller.

Stage numbering (single source of truth). The verbs follow the ratified eight-stage map: 000 INIT · 111 OBSERVE · 333 THINK · 444 ROUTE · 555 MEMORY · 666 JUDGE · 777 FORGE · 999 SEAL. Source: arifosmcp/constitutional_map.py ToolStage (F13-ratified 2026-07-31: JUDGE = 666, FORGE = 777; the old 888 stage was retired when compose was absorbed into forge). Some mirrors still carry the retired 888 label — a description string in constitutional_map.py, tools_sot.yaml, the generated llms.txt, and docs/PROMPT_666_JUDGE_DEPRECATION.md (dated 2026-07-10, predating the correction). The live wire says 666, and this README follows the live wire. Flagged for repair in "What Is Not Yet Proven".

For a guided walkthrough, start with docs/START_HERE.md or the verified docs/QUICKSTART.md.

Core Concepts

The verdict lattice

Verdicts are ordered and non-compensatory — a stronger verdict always dominates a weaker one. Seven seals are defined in arifosmcp/models/verdicts.py:

VOID  >  HOLD_888  >  HOLD  >  SABAR  >  PARTIAL  >  PROVISIONAL  >  SEAL

Verdict	Meaning	Plain English	What happens
SEAL	Authorised under stated conditions, W³ ≥ 0.95	Go	Proceed to execution
PARTIAL	A derived floor warns	Go carefully	Proceed with cooling and monitoring
PROVISIONAL	Time-limited authorisation, expires or downgrades to PARTIAL/HOLD	Proceed with expiry timer	Auto-revoke at `valid_until`; no extension without re-judging
SABAR	Not yet decidable — reality hasn't finished speaking	Wait for evidence	Retry permitted later; distinct from HOLD
HOLD	Insufficient evidence, or human approval required	Wait for human	Pause; await a human decision
HOLD_888	Immediate sovereign escalation	Stop — the sovereign decides	Escalate to F13
VOID	Blocked by a hard constitutional floor	Blocked	Stop; the constraint must be resolved

Seven seals, ordered and non-compensatory (lattice at top of section). The diagram below shows the five common verdicts for width; PROVISIONAL and HOLD_888 are omitted from the diagram but present in the lattice and table.

Floors are never averaged. One floor failure propagates into the verdict; there is no compensating score.

13 Constitutional Floors (F1–F13)

Every proposal is evaluated against 13 non-compensatory policy constraints. Canonical names and rules: FEDERATION_CONTRACT.md §3, GENESIS/000_KERNEL_CANON.md, and the constitution at static/arifos/theory/000/000_CONSTITUTION.md.

Floor	Name	Rule	Pass condition
F1	AMANAH	Reversible first. Irreversible → 888_HOLD unless the sovereign acknowledges	Score ≥ threshold (higher = better)
F2	TRUTH	P(truth) ≥ 0.99. Cheap claims = VOID. Evidence carries an OBS/DER/INT/SPEC label	Score ≥ threshold (higher = better)
F3	TRI-WITNESS	W₃ = ∛(Human × AI × Earth) ≥ 0.75 at judgment time (floor for admissibility; W³ ≥ 0.95 is the additional bar for SEAL)	Score ≥ threshold (higher = better)
F4	CLARITY	ΔS ≤ 0 — every output reduces entropy, never adds it	Score ≥ threshold (higher = better)
F5	PEACE²	Non-destructive power — block harm and extraction	Score ≥ threshold (higher = better)
F6	EMPATHY (operational: MARUAH)	Protect the weakest stakeholder; dignity is not tradeable	Score ≥ threshold (higher = better)
F7	HUMILITY	Ω₀ ∈ [0.03, 0.05]. No fake certainty	In-band [0.03, 0.05] = pass; outside = fail
F8	GENIUS	G ≥ 0.80 for complex actions — the simplest correct path	Score ≥ threshold (higher = better)
F9	ANTIHANTU	No deception, manipulation, or consciousness claims	Lower = better (lower ceiling = less manipulation)
F10	ONTOLOGY	AI-only ontology. A soul claim is VOID; map it to harness content	Score ≥ threshold (higher = better)
F11	AUDITABILITY	Every decision logged, inspectable, attributable	Score ≥ threshold (higher = better)
F12	RESILIENCE	Injection defence. Input risk < 0.85	Lower = better (lower = less injection surface)
F13	SOVEREIGN	Human veto is FINAL. The harness switch belongs to the human	Score ≥ threshold (higher = better)

Three semantic classes — verified by the live unit on 2026-09-21:

Score floors (F1–F6, F8, F10, F11, F13): higher = better. Score ≥ canonical threshold.
Band floors (F7): in-band [0.03, 0.05] = pass; outside = fail. 0.02 fails.
Ceiling floors (F9, F12): lower = better. Value below canonical ceiling.

W₃ has two named thresholds: W₃ ≥ 0.75 is the floor for admissibility; W₃ ≥ 0.95 is the additional bar for SEAL. Between them a proposal can be PARTIAL or HOLD, never SEAL.

Three naming notes, so a reader can reconcile this table with the wire:

F6 has two canonical names by design — EMPATHY in the public register, MARUAH in the kernel, logs and receipts. Both are correct; the bridge is documented in GENESIS/000_KERNEL_CANON.md §3.4. Public surfaces render EMPATHY.
The live runtime keys F10–F13 as L10–L13 in /health → runtime_floors. Same floors, different key prefix.
Lower-is-better floors are reported as raw measurements, not as failures: live values on 2026-09-21 were F7 = 0.04, F9 = 0.15, L12 = 0.425, and /health → runtime_floors_status reports 13/13 pass with every floor measured: true.

VAULT999 (append-only audit ledger)

Every consequential verdict, evidence chain and execution receipt is written to VAULT999 — a hash-chained, append-only JSONL ledger set, tamper-evident by construction, not tamper-proof.

What it stores is provenance, not copies. An entry carries its payload hash, entry hash, previous entry hash, trace root, actor, session, decision context and evidence references. Source payloads are not duplicated into the ledger — auditability here means provenance + integrity + reconstructability, which is both stronger and safer than copying everything forever (evidence can contain sensitive material).

A hash chain proves internal consistency. It does NOT prove that the chain was not recomputed by whoever controls the ledger. External anchoring — periodic publication of the chain head, or signing by a key the kernel does not hold — is not yet implemented. Treat VAULT999 today as self-verifiable, not independently attestable. See "What Is Not Yet Proven" for the gap row.

Measured 2026-09-21: 241,765 lines across 24 JSONL ledgers in VAULT999/ (largest: outcomes.jsonl 93,266 · arifflow_sealed.jsonl 52,056 · apex-zen-receipts.jsonl 30,977). Composition: the majority is operational telemetry and receipt ingestion; constitutional verdict count is published separately (see scripts/verify_vault_chain.py --verdict-count-only). The chain report returns overall: INTACT for the active ledgers, reporting 2 strict link breaks in the frozen v1 legacy ledger as historical facts rather than hiding or rewriting them. Live record count is re-stamped into the header manifest above by scripts/update_readme_sot.py.

Architecture

arifOS Federation — planes and classes

    ┌───────────────────────────────────────────────────┐
    │  Authority plane — arifOS :8088                    │
    │  Constitutional judgment · F1–F13 · VAULT999        │
    └──────────────────────┬────────────────────────────┘
                           │
    ┌──────────────────────▼────────────────────────────┐
    │  Attention plane — AAA :3001                       │
    │  What matters · routing · state · skill catalog    │
    └──────────────────────┬────────────────────────────┘
                           │
    ┌──────────────────────▼────────────────────────────┐
    │  Execution plane — A-FORGE :7071/:7072             │
    │  Governed mutation · leases · receipts             │
    └──────────────────────┬────────────────────────────┘
                           │
    ┌──────────────────────▼────────────────────────────┐
    │  Witness + record — FRAME :18085 · VAULT999        │
    │  Independent observation · immutable history       │
    └───────────────────────────────────────────────────┘
        boundaries:  HERMES :18087 (semantic) · CHRON :18102 (temporal)
        domains:     GEOX :8081 · WEALTH :18082 · WELL :18083
        metabolism:  arifFlow :7073      gateway: FED :7074      synthesis: i-ARIF

arifOS is the kernel; the other components are supporting infrastructure. GEOX is the primary reference implementation — a live geoscience organ whose evidence is governed in a high-consequence, uncertainty-heavy domain. FRAME's output is evidence, never a verdict. Domain organs compute; they never authorise.

Organs vs. boundaries — the ruling. The ratified organ table (FEDERATION_CONTRACT.md §2) lists 7 live organs: arifOS, A-FORGE, AAA, GEOX, WEALTH, WELL, arifFlow. HERMES is Tier-3 boundary infrastructure and is not an organ (§2.1, 2026-09-14 ruling); CHRON is the temporal boundary service. They are reported here by class rather than padded into an organ count — "everything we built" is not an architectural category.

Port note: i-ARIF has no listening port; :18095 is apa-github-bridge, one of the APA boundary bridges (:18075–:18099). A previous revision of this file named :18095 as i-ARIF — corrected 2026-09-21.

MCP Interface

The kernel exposes 8 canonical verbs over Streamable HTTP. Verified by live tools/list on 2026-09-21:

Stage	Verb	Purpose
000	`arif_init`	Session ignition — binds actor, floors and audit before any other verb
111	`arif_observe`	Sense reality into evidence with epistemic tags and uncertainty bounds
333	`arif_think`	Structured reasoning under F2/F7, with OBS/DER/INT/SPEC labels
444	`arif_route`	Intent → organ routing, dispatching to GEOX / WEALTH / WELL / A-FORGE
555	`arif_memory`	Governed memory — L1–L6 recall, storage, promotion
666	`arif_judge`	Evaluate a proposal; returns a binding verdict with the floor chain
777	`arif_forge`	Execution gate via A-FORGE — mutates only after a SEAL verdict
999	`arif_seal`	VAULT999 immutable append — seals a completed chain with its receipt

arif_forge is a governed dispatch verb: it routes an authorised action toward the execution organ and mutates only after SEAL. The kernel does not perform the underlying mutation. arif_route is authority-aware dispatch, not attention: it decides whether and how a routing may proceed, and may consult AAA. The judge never executes; the executor never certifies.

Tool-count semantics (so no two surfaces appear to disagree): tools_loaded = 8 — the public MCP facade, and the only number to quote publicly · canonical superset = 25 — 8 exposed + 13 hidden verbs (e.g. arif_challenge, arif_judge_deliberate), hidden by design · total_declared_tools = 48 · tools_registry_size = 62 (includes aliases) · operational_tools = 3 — the count with a durable SUCCESS in the last 24 hours, i.e. proven live, not merely invocable.

Verification Status

Live-probed 2026-09-21 (UTC+08); rows marked ↻ re-probed 2026-09-30. Re-run the commands; static counts are not evidence.

Surface	Status	Evidence
Public repository	Live	GitHub `ariffazil/arifOS`, AGPL-3.0
PyPI package	Published `1!2026.9.2` (uploaded 2026-09-15T16:42Z)	`pip install arifos` — pypi.org/project/arifos; tree is `1!2026.9.6`, unreleased
Live kernel	Healthy, 13/13 floors	`curl localhost:8088/health` → `status: healthy`, `floors_active: 13`
MCP interface	8 exposed, 3 with a durable SUCCESS in the last 24 h (tools_loaded: 8, operational_tools: 3)	live `tools/list`; protocol advertises `2026-07-28`, negotiation settles `2025-11-25`
Floor enforcement	13/13 measured pass	`/health → runtime_floors_status` (F7 = 0.04, F9 = 0.15, L12 = 0.425 lower-is-better)
VAULT999 ledger ↻	Healthy, chain INTACT	`scripts/verify_vault_chain.py` → `overall: INTACT` (its own scope: the 3 active ledgers under `arifOS/VAULT999/`). The previously published "241,765 lines / 24 ledgers" named no population and matched no measured root, so it is withdrawn rather than refreshed. Census 2026-09-30T07:44:35Z — two different, both-correct denominators: (a) recursive whole-estate, `find <root> -name '.jsonl'` then count non-blank lines: `arifOS/VAULT999` 60/354,283 · `/var/lib/arifos/vault` 7/20,986 · `~/.local/share/arifos/vault999` 66/16,555 · `AAA/VAULT999` 1/238 = 134 ledgers / 392,062 lines; (b) the generated SOT-MANIFEST header above reports `342K+ records` because `scripts/update_readme_sot.py` counts only top-level `VAULT999/.jsonl` in this repo, non-recursively (measured 24 files / 342,582 lines), excluding the subdirectory ledgers (a) includes. Neither is wrong; they have different populations. The vault is append-only and live, so every figure here is a snapshot — quote the timestamp with it.
Source / build / deploy ↻	Aligned — no drift	`source_commit = built_commit = deployed_commit = 27409ddbf`; `/health → drift: false`, `runtime_matches_build: true`, `deployment_drift_status: aligned`. Release provenance is re-attested on every `scripts/deploy-release.sh` run (`VERDICT: PASS`, strict) — quote the live value, not this one
Contract schema	8/8 published, no drift	`contract_status: {tool_count: 8, schemas_complete: true, contract_drift: false}`
Federation surfaces	10/11 reachable without drift; WELL degraded (drift: true)	ports 8088 · 3001 · 7071 · 7072 · 8081 · 18082 · 18083 · 7073 · 7074 · 18085 · 18102; WELL at `127.0.0.1:18083/health` returns HTTP 200 but reports `drift: true`, so the row honestly reads 10/11 healthy + 1 degraded
Machine-readable ↻	tools.json live, 56,224 bytes	tools.json · llms.txt (generated mirror — see gaps) · CITATION.cff
Scanner attestation	148 rules · 0 unauthorised mutations; 26/26 GRADE A	mcp.arif-fazil.com/proof/

What Is Not Yet Proven

Every row names its own gap. Repairing a claim by substituting a stronger one is worse than the stale claim it replaced.

Gap	Risk	Status
Independent security audit	Adversarial bypass testing not published	In progress — external researcher reviewing since 2026-08-25. First finding (fetch-surface SSRF) fixed, released in `1!2026.9.1`. A second scan (2026-09-15/16, mcp-safeguard) found 2 confirmed issues: Cypher injection (graph-wipe risk, HIGH — key whitelist landed in `l5_sovereign_forge.py`) and a fastmcp decode-after-match path traversal (MEDIUM — arifOS-side containment guard landed in `atlas333.py`; upstream report pending). Both are at code level; neither has a released-artifact verdict. See SECURITY.md
Sovereign-binding of irreversible acknowledgement	`ack_irreversible: true` and `actor_signature` are transported as payload fields. Nothing published demonstrates that a human signature is bound to `(transaction_hash ‖ state_hash ‖ nonce)`, single-use, scoped to one organ, and unforgeable by the proposing agent.	Open — design drafted (`docs/judgment-integrity-2026-09-22/ARIFOS_AUTHORITY_SERVICE_DESIGN.md`), not implemented. Until then, F13 is enforced by convention and band-gating, not by cryptographic transaction binding. This matches OWASP transaction-authorization practice: credentials unique per operation and bound to significant transaction data, not to session.
Ledger head not externally anchored or signed	A hash chain held entirely by one party detects external modification but not wholesale rewrite by the holder, because the holder can recompute every hash.	Open — periodic publication of chain head, or signing by a key the kernel does not hold, is not implemented. VAULT999 today is self-verifiable, not independently attestable.
Third-party evaluation	No external reviewer has published findings	In progress — one review under way since 2026-08-25; nothing published
Reproducible demo by strangers	Onboarding path not independently tested	Partial — `examples/enterprise_operations_demo.py` runs in-process and is verified here; no stranger has reproduced it unaided
Enterprise deployment	No production customer reference	Open
Standards conformance	MCP/A2A conformance results not published externally	Partial — CI `06-mcp-conformance.yml`; conformance report says `result: PARTIAL`, `spec_version: 2025-11-25`, with per-tool schema validation DEFERRED
SBOM and signed releases	Supply-chain integrity unverified externally	Partial — CycloneDX generator + `sbom` job on publish; no signing, no CVE scan
Container image metadata	The image's own labels contradict this repository	Open — flagged 2026-09-21: `Dockerfile` labels carry `org.opencontainers.image.licenses="BSL-1.1"` while the repository LICENSE is AGPL-3.0, the image listens on 3000 while ENV/LABEL say 8088, and the label block describes both "13 tools" and "7-tool surface". Fixing the licence wording is an F13 decision, not a docs edit
Generated mirrors drift	`llms.txt` still prints the retired `888` judge stage and version `v2026.07.24`	Open — last generated 2026-09-16; regenerate with `scripts/generate_tool_manifest.py`. The same retired label sits in a description string in `arifosmcp/constitutional_map.py` and in `tools_sot.yaml` (`stage: '666'` is correct; the prose is not), and in the pre-correction note `docs/PROMPT_666_JUDGE_DEPRECATION.md`
Generated discovery artifact drift	`smithery.yaml` no longer matches the kernel ABI registry — the guard itself fails	Open — verified 2026-09-21 on a pristine `main` worktree: `scripts/sync_kernel_abi.py --check` → `Kernel ABI drift: smithery.yaml`, exit 1. Regenerate the discovery artifacts from the registry (last resync 2026-09-15, `eacf0ca01`)
Development test suite	The suite needs a live kernel	Fixed 2026-09-25 (collection) — stale 269-line duplicate `tests/test_rasa_bench_10.py` removed (canonical 632-line bench lives at `/root/.hermes/policy/test_rasa_bench_10.py` where `rasa_boundary` resolves in-place); 7,622 tests collect clean (re-measured 2026-09-30, was 7,532); `tests/conftest.py` still refuses to run without a reachable kernel at `:8088` (by design). Collection ≠ green: the identity/authority/session/attestation subset carries 34 pre-existing failures against 321 passes (measured 2026-09-30 on a pristine `main` worktree), so quote a failure set, never a bare pass count
Semantic layer (Graphiti)	Knowledge graph retired from the read path	Operational gap — `graphiti_read: retired_888`, `semantic_floor: disabled` by choice (`ARIFOS_ML_FLOORS=0`)
Observability	Tracing partially wired	Partial — sovereign Postgres backend active; arifFlow FlowReceipt adapter live; OTel spans on all 8 canonical verbs; `langfuse_tracing: NOT_WIRED` after the cutover to kabarkan; caller-side trace propagation incomplete
Comparative benchmark	No published comparison against alternative frameworks	Open
Maintainer continuity	Single sovereign, single reviewer; no succession or key-recovery procedure published	Open — relevant to any institutional adoption
`__version__` strings are stale	Module `__version__` lags kernel release; readers may quote it incorrectly	Open — fix target: route `__version__` through `scripts/update_readme_sot.py` so it stays in sync
Identity registry exists in two copies	A one-sided edit ships a split-brain identity registry: `contracts/identity.py` (imported by ~9 runtime sites) and `arifosmcp/contracts/identity.py` (~3 sites, and the one the wheel ships) had already diverged — the packaged copy was missing the `I_ARIF` entry added by the 2026-08-21 Seal C fix and the `GEMINI`/`FI-004` lane entry, so `i-arif` and `agy/FI-004` resolved differently depending on which copy a module imported	Mitigated 2026-09-30, consolidation still open — both copies were re-aligned to 18 actors (`7796ec701`) and `tests/contracts/test_identity_registry_no_divergence.py` (31 tests) now fails on any drift in key set, aliases, normalization of 20 probe ids, or a missing `actor_lookup_candidates`; it was falsified against the pre-alignment state, where it caught exactly `gemini`, `i-arif` and `agy/FI-004`, so it is not vacuous. Open: pick one owner — migrate the 9 imports to `arifosmcp.contracts.identity` and retire the top-level copy, or keep both and keep the tripwire. Not decided here because it is a source-of-truth call, not a bug fix
Authority floor depended on a pointer stub and an unshipped package	Two independent faults capped every non-exempt agent at `OBSERVE_ONLY`, so mutation-capable citizens silently lost tool access — surfacing as the "tool inexplicably unauthorized" class. (a) Boot Q5 read `identity.toml` with `_file_read(A) or _file_read(B)`; both are 101-byte DERIVED stubs reading "superseded by: /root/AAA/identity.toml", and a non-empty stub short-circuits the `or`, so the canonical F13 payload was never read → `Q5=NO` → `boot_state=FAIL` → `_apply_boot_gate` demoted `LIMITED_MUTATE`/`FULL`. Authority was in practice coming from the 29-entry exemption list, not from attestation. (b) `contracts*` was absent from the wheel `include`, so the kernel's identity path resolved against a July-24 leftover. A bare `except ImportError: pass` in `_apply_boot_gate` hid a wrong module path, making the 2026-08-21 alias bypass dead code	Fixed 2026-09-30 — `5cc357974` (`_read_identity_toml_chain()` joins all candidates and follows `superseded by:` pointers; Q5 `NO`→`PARTIAL`, which passes the gate since the shipped predicate is `boot_state != "FAIL"`), `2eaec19c2`+`d43b7fece` (one shared `exempt_actor_band()` resolver replacing 7 raw-string membership tests, so the documented `name/FI-nnn` form resolves), `69175c0ec` (patched the copy production imports; boot-gate bypass moved off the fragile import), `27409ddbf` (`contracts` ships). Verified live: 17/17 AAA identities bind `SEAL` + `mutation_allowed=True` + `VERIFIED` with an ACT carrying `LIMITED_MUTATE` and all 9 verbs, 0 boot demotions, and the control `nobody/FI-999` is still refused — trust boundary unchanged, exempt membership still does not auto-verify. The generalizable defect: a stand-in served where the payload belonged, and a fail-silent `except` hid it — three times in one session.*

See SECURITY.md for the threat model, known gaps and disclosure policy, and docs/evidence/claims.yaml for the machine-readable claim registry.

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 a specific field (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 (dev tier — kernel + test tooling)
pip install -e ".[dev]"

# Run tests (needs the kernel reachable at :8088; one module fails collection — see gaps)
python -m pytest tests/ -q

# Kernel health (this Makefile target probes the kernel only)
make health

# Start the kernel
PORT=8088 arifos-mcp streamable-http   # or: PORT=8088 python -m arifosmcp.runtime --mode streamable-http

See CODEOWNERS for sovereign ownership of automation surfaces and CONTRIBUTING.md for contribution guidelines.

Project Structure

arifOS/
├── arifosmcp/          # Core kernel package                    [wheel root]
│   ├── abi/            # Capability registry and floor definitions
│   ├── constitution/   # Constitutional floor implementations
│   ├── contracts/      # Packaged copy of the identity/verdict contracts
│   ├── kernel/         # Core judgment engine
│   └── VAULT999/       # VAULT999 ledger implementation
├── arifos/             # Phase 3 identity/consent namespace      [wheel root]
├── contracts/          # Runtime contract package — identity registry,
│                       # gateway discovery, verdicts, continuity, envelopes.
│                       # Imported by 5 runtime files; see note.    [wheel root]
├── core/               # Load-bearing legacy root (session.py imports
│                       # core.shared.types)                      [wheel root]
├── schemas/            # INIT v2 schemas (F13-ratified 2026-09-20) [wheel root]
├── examples/           # Runnable governed workflow demo
├── tests/              # Test suite (pytest — constitutional + integration)
├── scripts/            # Operational tooling (incl. update_readme_sot.py)
├── docs/               # Documentation
│   ├── START_HERE.md   # External reader entry point
│   ├── QUICKSTART.md   # Verified first governed call
│   └── evidence/        # Claim registry and evidence index
└── pyproject.toml      # Package metadata — [wheel root] marks
                        # packages.find.include

The five [wheel root] entries are exactly what ships. Until 2026-09-30 this tree listed only arifosmcp/, and contracts* was absent from [tool.setuptools.packages.find].include — while the runtime imported contracts.* at 10 import statements across 5 files under arifosmcp/ (contracts.identity 6, verdicts/continuity/artifacts/envelopes 1 each), plus arifosmcp/contracts/__init__.py doing from contracts.identity import *. Scope matters: a repo-wide grep reports ~4× that, because build/lib/ holds a 1,402-file duplicate tree and tests/ adds its own imports (gateway_discovery 7, all of them tests — 0 in the runtime). Those inflated figures were what an earlier revision of this note published; corrected 2026-09-30. Production resolved those imports only because pip does not delete a pre-existing unrelated site-packages/contracts/ leftover; a fresh venv or a machine migration would have raised ImportError at kernel import time. Fixed in 27409ddbf. An incomplete structure diagram is not a cosmetic gap — it is how an unshipped, runtime-critical package stays invisible.

contracts/ and arifosmcp/contracts/ are two copies of the same contract modules and had already diverged. They are kept in agreement by tests/contracts/test_identity_registry_no_divergence.py; consolidating them into one owner is still open (see gaps).

Sister Repositories

Repository	Purpose
AAA	Attention plane — routing, state, skill catalog, A2A gateway
A-FORGE	Execution engine after authorisation
GEOX	Earth sciences domain evidence
WEALTH	Capital and financial intelligence
WELL	Human and machine vitality observation
arifFlow	Metabolic ledger daemon — FQ monitoring, receipt ingestion
FRAME	Independent observer — drift detection, evidence gathering (repository archived, organ live)

No public repository today: FED (:7074) and i-ARIF. They are deployed and reachable, but their source is not published — a previous revision of this file linked to repositories that return 404. Treat their behaviour as observed from /health only, not as readable code.

Evidence & Trust

arifOS publishes verifiable evidence for its claims. Every public claim links to an artifact that can be regenerated.

Claim	Evidence	Status
MCP conformance	CI workflow · report	Partial — `result: PARTIAL`, per-tool schema validation deferred, results not published externally
ABI stability	Drift guard	Partial — `--check` currently reports drift in `smithery.yaml` (reproduced on a pristine `main` worktree, 2026-09-21); last clean resync 2026-09-15
Floor enforcement	`/health → runtime_floors_status`	Verified — 13/13 measured pass (live probe)
Vault integrity	`scripts/verify_vault_chain.py`	Verified — overall INTACT; 2 legacy breaks reported as historical
SBOM	Generator	Partial — CycloneDX generated, no CVE scan, unsigned
Observability	Telemetry	Partial — Postgres + arifFlow live; tracing incomplete
Governance hardening	Adversarial test spec (federation-internal, not published)	Partial — spec written, no external audit
Quickstart	Verified quickstart	Verified by the maintainer on 2026-09-21; not yet reproduced by a stranger

See docs/evidence/ for the claim registry (claims.yaml), the evidence index and the contracts for observability, release integrity, reproducibility and threat model.

Honesty principle: we publish what passed, what failed, and what remains unknown. We do not claim maturity beyond our evidence.

Who Maintains This

One human, and the agents he directs.

I am a geologist, not a programmer. I did not write this codebase and I do not read it line by line. What I do is point at where the problem is — and the agents in my federation solve it, inside the constitution and the review gates I set, with the commit trail to show who ran what.

Read the commits if you want to check that claim: the author fields are agent handles, not aliases of mine. That is the deliberate shape of this project, not a detail being hidden. It also sets the honest expectation — the design and the judgment are mine, the implementation is theirs, and where the two disagree, the bug is mine to answer for.

Contributing

See CONTRIBUTING.md for guidelines.

Security

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

License

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

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. (The container image's OCI licence label does not currently agree with this — see "What Is Not Yet Proven".)

Revision 2026-09-21 — audited against the live kernel, the ratified federation contract and the repository itself. Every number in this file was re-measured, not carried forward; each correction is receipted in the commit history.

Independent audit pass 2026-09-22 (Copilot external, mode ENTERPRISE). Findings A, B, C, D, E, F, G, H, I, K, L, N — all four blocking contradictions + the two highest-leverage gaps (G sovereign-binding, H ledger anchoring) — corrected in this revision. M (TOC/badges) and a per-pass signature remain open as structural polish. See commit history for per-finding receipts.

Ditempa Bukan Diberi — Forged, Not Given.

Related MCP servers

arifOS — Constitutional AI Kernel

Active

Constitutional AI kernel that evaluates agent actions against 13 policy floors before execution, with append-only verdict ledger.

Python

AGPL-3.0

View repository →

io.github.ariffazil/arifos-mcp

Active

Constitutional AI governance layer that evaluates agent actions against 13 policy floors before execution occurs.

Python

AGPL-3.0

View repository →

arifOS — Constitutional AI Governance

Maintained

Constitutional AI governance: 11 mega-tools, 13 floors, VAULT999 ledger. Human-in-loop by design.

Python

View repository →

io.github.arifulislamat/database-mcp-libsql

Active

MCP server for libSQL/Turso, local or remote. Read-only by default, row caps, timeouts.

Python

MIT

View repository →

io.github.arifulislamat/database-mcp-mariadb

Active

MCP server for MariaDB. Read-only by default, row caps, timeouts, secrets never logged.

Python

MIT

View repository →

io.github.arifulislamat/database-mcp-mysql

Active

MCP server for MySQL. Read-only by default, row caps, statement timeouts, secrets never logged.

Python

MIT

View repository →