convez.ai
MCP ServerDevOps & InfraestruturaAvançado
ariffazil

A-FORGE — Shell de Execução Governado

ariffazil/A-FORGE

Shell de execução federado com governança constitucional e auditoria integral

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server TypeScript que implementa um kernel de execução governado para a federação arifOS, rodando bare-metal em VPS dedicada. Orquestra deployments, infraestrutura e execução de comandos dentro de gates constitucionais com rastreabilidade completa.

Instalação

$npx convez-ai ariffazil/A-FORGE

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 dias
Versão
v2026.08.28
Issues abertas
13
Contribuidores
22

Casos de uso

  • Orquestração de deployments em ambientes federados
  • Execução controlada de infraestrutura com auditoria de autorização
  • Integração como órgão soberano em arquiteturas descentralizadas

Veredito

Projeto robusto com governança constitucional e auditoria integral, mas voltado a um caso de uso específico (federação arifOS). Exige compreensão profunda de seu modelo federado para operação efetiva — não é shell genérico.

README

A tradução para o português deste README ainda está na fila.

A-FORGE — Governed Execution Shell

   ╔══════════════════════════════════════════════════════════════════════╗
   ║                                                                      ║
   ║        █████╗       ███████╗ ██████╗ ██████╗  ██████╗ ███████╗      ║
   ║       ██╔══██╗      ██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝      ║
   ║       ███████║█████╗█████╗  ██║   ██║██████╔╝██║  ███╗█████╗        ║
   ║       ██╔══██║╚════╝██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝        ║
   ║       ██║  ██║      ██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗      ║
   ║       ╚═╝  ╚═╝      ╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝      ║
   ║                                                                      ║
   ║               GOVERNED EXECUTION SHELL · arifOS Federation           ║
   ║                                                                      ║
   ║    A constitutional kernel without a governed execution shell         ║
   ║                       is just a PDF.                                  ║
   ║                                                                      ║
   ╚══════════════════════════════════════════════════════════════════════╝

Organ Status Node TypeScript License Port Federation Systemd Tests Tools


Federation Position

This organ operates under the arifOS Constitutional Federation. Canonical contract: ariffazil/arifos/FEDERATION_CONTRACT.md Kernel canon: ariffazil/arifos/GENESIS/000_KERNEL_CANON.md

A-FORGE is the governed execution shell of the arifOS Federation — one of 7 sovereign organs running bare-metal on VPS af-forge (72.62.71.199). It also hosts the MIND:51001 and MEMORY:51002 federated intelligence services, which are not separate organs. A-FORGE does not judge, does not compute domain logic, and executes only within bounded constitutional gates, with full audit trail, and never without upstream authorization.


The Execution Chain

                         ┌─────────────────────────┐
                         │                         │
                         │      F13 SOVEREIGN       │
                         │   Muhammad Arif Fazil    │
                         │      (absolute veto)     │
                         │                         │
                         └────────────┬────────────┘
                                      │
                         ┌────────────▼────────────┐
                         │       arifOS (judge)     │
                         │  Port 8088 · 13 floors   │
                         │  F1–F13 · SEAL/SABAR/VOID│
                         │  VAULT999 · 888 JUDGE    │
                         │                          │
                         │   "Can this be done?"    │
                         └────────────┬─────────────┘
                                      │ JUDGE_SEAL_AUTHORIZATION
                         ┌────────────▼─────────────┐
                         │       AAA (route)         │
                         │  Port 3001 · Cockpit      │
                         │  A2A mesh · agent cards   │
                         │                           │
                         │   "What should be done?"  │
                         └────────────┬──────────────┘
                                      │ mission + envelope
                         ┌────────────▼──────────────┐
      ┌──────────────────│      A-FORGE (execute)     │──────────────────┐
      │                  │  Port 7071 · Governed Shell │                  │
      │                  │  4-layer forge gate        │                  │
      │                  │  62+ tools auto-discovered  │                  │
      │                  │                             │                  │
      │                  │  "Do it, safely, with       │                  │
      │                  │         evidence."          │                  │
      │                  └──┬──────────┬──────────┬────┘                  │
      │                     │          │          │                       │
      │        ┌────────────┘          │          └────────────┐          │
      │        ▼                       ▼                       ▼          │
      │  ┌──────────┐           ┌──────────┐           ┌──────────┐       │
      │  │   GEOX   │           │  WEALTH  │           │   WELL   │       │
      │  │   earth  │           │  capital │           │   human  │       │
      │  │ :8081    │           │  :18082  │           │  :18083  │       │
      │  └──────────┘           └──────────┘           └──────────┘       │
      │                                                                   │
      └───────────  MCP federation bridge · 5 MCP surfaces · all on 127.0.0.1 ──┘

One-Sentence Identity

A-FORGE is the governed execution shell of the arifOS constitutional federation. It receives approved plans, gates them through four constitutional layers, and executes them across federation organs — never self-authorizing, never skipping audit.


What A-FORGE IS

DomainDescription
Execution bodyReceives JUDGE_SEAL_AUTHORIZATION from arifOS, then gates and runs the plan
MCP federation bridgeAuto-discovers 62+ tools across 5 MCP surfaces on startup (7 federation organs total)
Constitutional gatekeeper4-layer forge gate inline on every execution path
Telemetry producerEvery execution → Prometheus + Supabase + VAULT999 + Langfuse
Orchestration engineRoutes intents, retries failures, handles escalation
Terminal forgeInteractive streaming-LLM terminal with session persistence
Audit trail generatorF11 AUDITABILITY — every call, every gate, every verdict logged

What A-FORGE IS NOT

It is NOTThe truth
A constitutional judgeVerdicts (SEAL/SABAR/VOID/HOLD) live in arifOS only
A self-authorizing agentEvery forge requires external JUDGE_SEAL_AUTHORIZATION
A geoscience engineVsh, PHIE, Sw, AVO → GEOX
A capital modelerNPV, IRR, EMV, EVOI → WEALTH
A human readiness sensorBiometric state, vitality → WELL
A NumPy/Pandas hostDomain logic stays in Python organs. TypeScript bridge only.

Quick Start

# Clone the canon
git clone git@github.com:ariffazil/A-FORGE.git
cd A-FORGE

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start the execution shell
node dist/interfaces/server.js
# → A-FORGE listening on 127.0.0.1:7071

# Verify health
curl -s http://127.0.0.1:7071/health | python3 -m json.tool
# → {"ok": true, "service": "A-FORGE", "version": "2026.06.06", "uptime_ms": 1234}

# Federation status (auto-discovers all organs)
curl -s http://127.0.0.1:7071/api/federation-probe | python3 -m json.tool
# → {"verdict": "GREEN", "up": 5, "total": 5, "organs": {...}}

# Run the terminal forge (streaming LLM interface)
npm run terminal
# → ◬ A-FORGE Terminal Forge · 62+ tools available · type /help

Prerequisites:

  • Node.js 22+ (TypeScript 6.0 target)
  • arifOS MCP kernel running on 127.0.0.1:8088 (or set ARIFOS_MCP_URL)
  • Federation organs (GEOX, WEALTH, WELL) for full tool surface

For detailed setup including standalone mode and stdio MCP configuration, see QUICKSTART.md.


The 4-Layer Forge Gate

Every execution path in A-FORGE passes through four constitutional gates in order. The order is the invariant. Reordering any layer voids the constitutional guarantee.

                           EXECUTION REQUEST
                                  │
                                  ▼
  ╔══════════════════════════════════════════════════════════════════╗
  ║                         THE FORGE GATE                          ║
  ╠══════════════════════════════════════════════════════════════════╣
  ║                                                                  ║
  ║   LAYER 1: F1 AMANAH GATE                                       ║
  ║   ┌──────────────────────────────────────────────────────────┐  ║
  ║   │ Detects catastrophic patterns before execution:           │  ║
  ║   │   rm -rf /    ·   DROP TABLE   ·   dd if=/dev/zero       │  ║
  ║   │   docker system prune -a   ·   ufw deny 22               │  ║
  ║   │   chmod -R 777 /etc   ·   DELETE FROM vault              │  ║
  ║   │                                                          │  ║
  ║   │ Verdict: HARAM → BLOCKED (no appeal)                     │  ║
  ║   │          HOLD  → escalate to ApprovalBoundary             │  ║
  ║   │          PASS  → proceed to Layer 2                      │  ║
  ║   └──────────────────────────────────────────────────────────┘  ║
  ║                              │                                   ║
  ║                              ▼                                   ║
  ║   LAYER 2: MODEL CAPABILITY GATE                                ║
  ║   ┌──────────────────────────────────────────────────────────┐  ║
  ║   │ Fast spine-check against arifOS registry:                 │  ║
  ║   │   · Reads model_governance_card from arifOS kernel        │  ║
  ║   │   · Verifies model identity, capability band, rate limit  │  ║
  ║   │   · Checks tool access grants against capability registry │  ║
  ║   │                                                          │  ║
  ║   │ Verdict: DEGRADED → route to fallback provider            │  ║
  ║   │          MISSING  → HOLD (model not in registry)          │  ║
  ║   │          PASS     → proceed to Layer 3                    │  ║
  ║   └──────────────────────────────────────────────────────────┘  ║
  ║                              │                                   ║
  ║                              ▼                                   ║
  ║   LAYER 3: GOVERNANCE BRIDGE                                    ║
  ║   ┌──────────────────────────────────────────────────────────┐  ║
  ║   │ Full floor evaluation via arifOS kernel:                  │  ║
  ║   │   F3  WITNESS    — greeting bypass, witness verification  │  ║
  ║   │   F6  EMPATHY    — weakest-stakeholder protection         │  ║
  ║   │   F9  ANTI-HANTU — deception / manipulation detection    │  ║
  ║   │   F10 ONTOLOGY   — AI-only framing, no soul claims       │  ║
  ║   │   F11 COHERENCE  — internal logical consistency           │  ║
  ║   │   F12 INJECTION  — prompt injection defense (c_dark<0.3) │  ║
  ║   │                                                          │  ║
  ║   │ Verdict: SEAL  → proceed to Layer 4                      │  ║
  ║   │          SABAR → HOLD (needs more evidence)               │  ║
  ║   │          VOID  → BLOCKED (floor violation)               │  ║
  ║   └──────────────────────────────────────────────────────────┘  ║
  ║                              │                                   ║
  ║                              ▼                                   ║
  ║   LAYER 4: APPROVAL BOUNDARY                                    ║
  ║   ┌──────────────────────────────────────────────────────────┐  ║
  ║   │ Irreversibility gate — the final lock:                    │  ║
  ║   │   · reversibility_score calculation                       │  ║
  ║   │   · If ack_irreversible required but missing → 888_HOLD   │  ║
  ║   │   · Routes to human (Telegram/Webhook) or AAA a2a-server  │  ║
  ║   │   · Postgres-backed approval ticket with TTL              │  ║
  ║   │                                                          │  ║
  ║   │ Verdict: APPROVED → EXECUTE                               │  ║
  ║   │          888_HOLD → escalation queue (human/APEX)         │  ║
  ║   │          DENIED   → BLOCKED (reversibility=0)             │  ║
  ║   └──────────────────────────────────────────────────────────┘  ║
  ║                              │                                   ║
  ╚══════════════════════════════╪════════════════════════════════════╝
                                 │
                                 ▼
                          ╔═══════════╗
                          ║  EXECUTE  ║
                          ╚═══════════╝
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
               Tool Call    Build/Deploy   LLM Query
                    │            │            │
                    └────────────┼────────────┘
                                 ▼
                    ┌─────────────────────────┐
                    │    TELEMETRY FANOUT     │
                    │  Prometheus · Supabase  │
                    │  VAULT999  · Langfuse   │
                    └─────────────────────────┘

The iron rule: No layer may be skipped. No execution path must be silent. Every 888_HOLD must surface in the AAA approval queue.


Full Capability Map

Build & Deploy

CapabilityImplementationConstitutional Gate
Build orchestrationForgeExecutionService — npm/pip/docker build pipelinesLayer 1–4 full gate
Deploy to VPSsystemctl restart, Caddy reload, rsync to /opt/Layer 4 (irreversible)
Artifact managementDocker image build + push, GHCR taggingLayer 4 (requires lease)
Security auditmake security-audit — Trivy + Semgrep + Gitleaks + RuffLayer 1 (non-blocking)

Code Execution

CapabilityImplementationConstitutional Gate
Code-mode sandboxdomain/containment/ExecutionSandbox.ts + NodeSandbox.tsLayer 1 (HARAM pattern scan)
Security scannerSecurityScanner.ts — AST-level dangerous pattern detectionLayer 1
Shell executionShellTools.ts — bounded subprocess with timeoutLayer 1 + Layer 4
File operationsFileTools.ts, EditorTools.ts — read/write/edit with path allowlistingLayer 1

Orchestration & Federation

CapabilityImplementationConstitutional Gate
Intent routingIntentRouter.ts — routes to correct organ (GEOX/WEALTH/WELL/arifOS)Layer 2 + 3
MCP auto-discoveryFederation bridge probes 5 organs on startup → 62+ toolsStartup-only
Federation probeGET /api/federation-probe — live organ status, latency, verdictRead-only
A2A protocolapplication/a2a/ — agent card, task routing, agent profilesLayer 3
Cross-organ orchestrationPipelineCoordinator.ts — multi-step plans with retryLayer 2 + 3
Agent lifecycleAgentManager.ts, BackgroundJobManager.ts — spawn, monitor, killLayer 4

Multi-Provider LLM

CapabilityImplementationGate
Streaming SSEChatCompletionProvider.ts — onToken/onThinking/onCompleteLayer 2
Budget-aware routingBudgetAwareRouter.ts — cheapest capable model firstLayer 2
Fallback chainFallbackProvider.ts — graceful degradation on outageLayer 2
ProvidersMiniMax-M3, SEA_LION, Ollama (bge-m3), OpenAI-compatibleLayer 2

Terminal Forge

CapabilityImplementation
Interactive sessioninfrastructure/cli/terminal.ts — streaming LLM with SSE parsing
Federation commands/tools, /federation, /status, /retry, /forge
Session persistence/save, /load, /sessions — auto-save on Ctrl+C
History navigation500-entry command buffer, Up/Down arrows
Multi-line inputBackslash continuation + /multi mode

Memory & Persistence

CapabilityImplementation
Short-term memoryShortTermMemory.ts — 20-message window, 16K token ceiling, sliding eviction
Long-term memoryLongTermMemory.ts — file-backed archival, cross-session retrieval
Memory contractdomain/memory-contract/MemoryContract.ts — F2 TRUTH, F11 AUDIT
Continuity storeContinuityStore.ts — shutdown flush, startup restore
arifOS L3 bridgeArifOSMemoryClient.ts — Qdrant semantic memory

Observability

CapabilityImplementation
Prometheus metricsinfrastructure/metrics/prometheus.ts — exposed on port 7071
Supabase receiptsTool call receipts → arifosmcp_tool_calls table
VAULT999 escrowIrreversible action records → canonical ledger
Langfuse tracesSession-level LLM traces
ScoreboardForgeScoreboard.ts + RunMetricsLogger.ts — per-run metrics
Thermodynamic trackingThermodynamicCostEstimator.ts — compute budget, entropy delta

Boundary Declaration

The boundary between A-FORGE and the rest of the federation is defined by what code may exist in this repository. It is enforced by the boundary contract in INVARIANTS.md and the prime directive in CONSTITUTION.md.

  ┌───────────────────────────────────────────────────────────────────────┐
  │                         A-FORGE OWNS                                  │
  │                                                                       │
  │   ▸ BUILD pipelines      ▸ DEPLOY orchestration    ▸ CODE execution   │
  │   ▸ Intent ROUTING       ▸ MCP federation bridge   ▸ ORCHESTRATION   │
  │   ▸ Constitutional GATES ▸ Multi-provider LLM      ▸ TELEMETRY       │
  │   ▸ Terminal forge       ▸ Session PERSISTENCE     ▸ ESCALATION      │
  │   ▸ Agent lifecycle      ▸ Memory management       ▸ Tool registry   │
  │                                                                       │
  └───────────────────────────────────────────────────────────────────────┘

  ┌───────────────────────────────────────────────────────────────────────┐
  │                        A-FORGE NEVER                                  │
  │                                                                       │
  │   ▸ Issue SEAL/SABAR/VOID constitutional verdicts       → arifOS     │
  │   ▸ SELF-AUTHORIZE any execution                        → arifOS     │
  │   ▸ Compute geoscience (Vsh, PHIE, Sw, AVO, seismic)    → GEOX       │
  │   ▸ Compute capital (NPV, IRR, EMV, EVOI, DCF)          → WEALTH     │
  │   ▸ Sense human readiness / biometric state             → WELL       │
  │   ▸ Render cockpit UI / control plane                   → AAA        │
  │   ▸ Import NumPy, Pandas, SciPy, lasio, welly           → WRONG LAYER│
  │   ▸ Modify constitutional floors F1–F13                 → arifOS     │
  │   ▸ Skip the 4-layer forge gate on ANY execution        → NEVER      │
  │                                                                       │
  └───────────────────────────────────────────────────────────────────────┘

The litmus test: If your code needs NumPy, Pandas, or reservoir physics → wrong layer. If your code is judging constitutionality → wrong layer. A-FORGE is TypeScript-only. Domain logic lives in Python MCP organs. The bridge is governed.


Constitutional Binding

A-FORGE enforces three constitutional floors as its runtime mandate. The remaining floors are enforced by arifOS on the upstream side before A-FORGE ever receives a plan. The constitution lives in one canonical file:

→ arifOS/static/arifos/theory/000/000_CONSTITUTION.md

Floors enforced in A-FORGE runtime

FloorNameHow A-FORGE enforces it
F1AMANAHCatastrophic action detection at Layer 1. HARAM patterns block before any tool runs. No override — not even sovereign bypasses rm -rf /.
F11AUDITABILITYEvery execution path produces: tool call receipt (Supabase), federation telemetry (Prometheus), escalation record (VAULT999), session trace (Langfuse). No execution is silent.
F12RESILIENCEInjection defense in f12Injection.ts. Prompt injection patterns detected at Layer 3. c_dark < 0.30 hard threshold. Redaction before domain tool receives input.

Floors enforced by arifOS (upstream, before A-FORGE)

FloorWhat happens before A-FORGE receives the plan
F2TRUTH — P(truth) ≥ 0.99 required for SEAL. A-FORGE receives only verified plans.
F3TRI-WITNESS — Human+AI+Earth+Verifier consensus ≥ 0.75 before SEAL.
F4CLARITY — ΔS ≤ 0. Every plan must reduce system entropy.
F5PEACE² — Non-destructive power. Blocks harm/harass/extort.
F6EMPATHY — κᵣ ≥ 0.10. Protect weakest stakeholder.
F7HUMILITY — Ω₀ ∈ [0.03, 0.05]. No fake certainty.
F8GENIUS — G ≥ 0.80 for high-stakes plans.
F9ANTIHANTU — C_dark < 0.30. No deception, no consciousness claims.
F10ONTOLOGY — AI-only framing. No soul/feelings/personhood.
F13SOVEREIGN — Arif's veto is final. No plan bypasses F13.

What this means in practice: A-FORGE never receives a plan that hasn't passed arifOS's full F2–F13 evaluation. A-FORGE's own gates are defense-in-depth — catching execution-level patterns that the plan-level evaluation may not have detected. The forge is hot only when the verdict is cold.


Architecture

A-FORGE source is organized as 5 top-level layers with Hexagonal Architecture (domain / application / infrastructure / interfaces separation, forged in v2026.06.06-HEXAGON).

A-FORGE/
│
├── GENESIS/                        ← constitutional mandate chain
│   └── 012_AFORGE_MANDATE.md       ← organ identity + invariants (stub)
│
├── src/
│   ├── domain/                     ← Pure domain logic (NO I/O, NO Express)
│   │   ├── engine/                 ← Core agent loop
│   │   │   ├── AgentEngine.ts          — Primary agent cycle
│   │   │   ├── PipelineCoordinator.ts  — Governed plan execution
│   │   │   ├── IntentRouter.ts         — Organ routing decisions
│   │   │   ├── ArifOSKernel.ts         — arifOS MCP client
│   │   │   ├── BudgetManager.ts        — Token/cost budgeting
│   │   │   └── RunReporter.ts          — Per-run metrics aggregation
│   │   │
│   │   ├── governance/             ← Constitutional floor enforcement (34 files)
│   │   │   ├── AmanahLockManager.ts    — F1: HARAM pattern scanner
│   │   │   ├── ModelCapabilityGate.ts  — Layer 2: model identity + capability
│   │   │   ├── GovernanceBridge.ts     — Layer 3: arifOS floor evaluation
│   │   │   ├── PolicyEnforcer.ts       — Policy evaluation engine
│   │   │   ├── SealService.ts          — VAULT999 seal integration
│   │   │   ├── F13HaltChannel.ts       — Sovereign emergency halt
│   │   │   ├── f1Amanah.ts  …  f12Injection.ts   — Per-floor enforcement
│   │   │   ├── planFactory.ts          — Plan construction from missions
│   │   │   ├── preflight.ts            — Pre-execution checks
│   │   │   └── floor-types.ts          — Type system for constitutional verdicts
│   │   │
│   │   ├── planner/                ← Plan construction + validation
│   │   │   ├── PlanValidator.ts        — verifyGovernanceCard() + reversibility
│   │   │   └── ParallelPlannerContract.ts — Multi-plan coordination
│   │   │
│   │   ├── agents/                 ← Agent profiles + coordination
│   │   │   ├── AAAgent.ts / CoordinatorAgent.ts / WorkerAgent.ts
│   │   │   └── profiles.ts             — explore, forge, audit, general
│   │   │
│   │   ├── containment/            ← Execution sandbox
│   │   │   ├── ContainmentEngine.ts    — Sandbox lifecycle
│   │   │   ├── ExecutionSandbox.ts     — Isolated execution environment
│   │   │   └── SandboxPolicy.ts        — Resource limits + network caps
│   │   │
│   │   ├── memory-contract/        ← Memory constitution
│   │   ├── continuity/             ← Session persistence
│   │   ├── policy/                 ← confidence.ts, sense.ts
│   │   ├── reply/                  ← reply_forge.ts — constitutional response composer
│   │   ├── ops/                    ← SentinelStream, ThermodynamicCostEstimator
│   │   ├── scoreboard/             ← ForgeScoreboard, RunMetricsLogger
│   │   └── types/                  ← 20 type contract files (Plan, Agent, Session, etc.)
│   │
│   ├── application/                ← Application services (orchestration layer)
│   │   ├── approval/               ← Approval + escalation pipeline
│   │   │   ├── ApprovalBoundary.ts     — Layer 4: irreversibility gate
│   │   │   ├── ApprovalRouter.ts       — HOLD → human or APEX
│   │   │   ├── HumanEscalationClient.ts — Telegram/Webhook channels
│   │   │   └── PostgresTicketStore.ts  — Approval ticket persistence
│   │   │
│   │   ├── a2a/                    ← Agent-to-Agent protocol
│   │   │   ├── server.ts               — A2A task router
│   │   │   └── types.ts                — A2A envelope types
│   │   │
│   │   ├── discovery/              ← A2A agent-card discovery
│   │   ├── memory/                 ← ShortTermMemory + LongTermMemory + ArifOS bridge
│   │   ├── personal-v2/            ← PersonalOS — sovereign digital twin
│   │   ├── jobs/                   ← AgentManager, BackgroundJobManager
│   │   └── services/               ← ForgeExecutionService
│   │
│   ├── infrastructure/             ← I/O, external services, transport
│   │   ├── bridges/                ← Organ MCP bridges
│   │   │   ├── geoxBridge.ts           — GEOX MCP client
│   │   │   └── wealthBridge.ts         — WEALTH MCP client
│   │   │
│   │   ├── llm/                    ← Multi-provider LLM abstraction
│   │   │   ├── ChatCompletionProvider.ts — Streaming SSE + tool-use parsing
│   │   │   ├── BudgetAwareRouter.ts     — Cost-minimizing provider selection
│   │   │   ├── FallbackProvider.ts      — Provider failover chain
│   │   │   └── OllamaProvider.ts / SeaLionProvider.ts — Provider adapters
│   │   │
│   │   ├── tools/                  ← Built-in tool implementations
│   │   │   ├── ToolRegistry.ts         — Dynamic registration + permission gates
│   │   │   ├── FileTools.ts / ShellTools.ts / SearchTools.ts / EditorTools.ts
│   │   │   ├── MiniMaxTools.ts         — MiniMax MCP client
│   │   │   └── WealthTools.ts          — WEALTH domain tool wrappers
│   │   │
│   │   ├── vault/                  ← VAULT999 integration
│   │   │   ├── PostgresVaultClient.ts  — Direct Postgres
│   │   │   ├── SupabaseVaultClient.ts  — Supabase pooler
│   │   │   └── MerkleV3Service.ts      — Chain verification
│   │   │
│   │   ├── cli/                    ← Terminal forge
│   │   ├── code-mode/              ← Code execution sandbox
│   │   ├── metrics/                ← Prometheus metrics
│   │   └── notifier/               ← Telegram + Webhook escalation
│   │
│   ├── interfaces/                 ← HTTP, MCP, CLI entry points
│   │   ├── server.ts               ← Express-based HTTP server (port 7071)
│   │   ├── mcp/                    ← MCP protocol (server, client, stdio, tools)
│   │   ├── middleware/             ← ConstitutionalBoundary, operatorAuth
│   │   ├── routes/                 ← Approval, governance, vault, repo steward
│   │   └── config/                 ← RuntimeConfig, featureFlags, modes
│   │
│   └── util/  +  utils/           ← Shared utilities
│
├── test/                            ← 25 TypeScript test suites (~4,700 lines)
│   ├── AgentEngine.test.ts
│   ├── PlanValidator.test.ts
│   ├── AmanahLockManager.test.ts
│   ├── FloorEnforcer.test.ts
│   ├── sealService.test.ts
│   ├── thermodynamic.test.ts
│   └── ... 19 more
│
├── deploy/                          ← VPS deployment configs
├── contracts/                       ← Cross-organ interface contracts
├── docs/                            ← Documentation
├── governance/                      ← Policy YAML
├── scripts/                         ← Build/ops scripts
│
├── CONSTITUTION.md                  ← A-FORGE constitutional role + boundaries
├── FEDERATION_CONTRACT.md           ← Organ contract within arifOS Federation
├── INVARIANTS.md                    ← Live ports, forbidden assumptions
├── ARCHITECTURE.md                  ← Deep module map (150+ files, 16 modules)
├── RUNBOOK.md                       ← Start/stop/health/debug procedures
├── CONTEXT.md                       ← Live machine state for agents
├── AGENTS.md                        ← Agent operating rules + boundary contract
├── CHANGELOG.md                     ← Version history
├── CODEOWNERS                       ← Ownership map
├── Makefile                         ← build, test, install, clean
├── tsconfig.json                    ← TypeScript 6.0 config
├── package.json                     ← v2026.06.06, AGPL-3.0
├── smithery.yaml                    ← Smithery MCP registry entry
└── Dockerfile                       ← Production container build

For Human Operators

Arif — How to Trigger a Forge

You don't run A-FORGE directly. You speak to arifOS. The kernel judges. A-FORGE executes.

YOU (F13 SOVEREIGN)
    │
    │  "forge the WEALTH stock analysis"
    │
    ▼
arifOS (judge) ──→ evaluates F1–F13
    │
    │  JUDGE_SEAL_AUTHORIZATION
    │
    ▼
A-FORGE (execute) ──→ 4-layer gate ──→ builds, tests, deploys
    │
    │  telemetry: Prometheus + Supabase + VAULT999
    │
    ▼
AAA cockpit ──→ shows you what happened (green/red/yellow)

What "888_HOLD" Means

If A-FORGE escalates to 888_HOLD, it means:

  1. The forge gate blocked an action at Layer 4 (ApprovalBoundary)
  2. The action is irreversible (deploy, delete, drop, force-push)
  3. A-FORGE will not proceed without your explicit ack_irreversible
  4. You will see an approval ticket in the AAA cockpit
  5. Reply 888 approve <ticket_id> to proceed, or 888 deny <ticket_id> to halt

888_HOLD is not a failure. It's the system working correctly — catching what should not be auto-executed.

Production Commands

# Check if A-FORGE is running
systemctl status a-forge

# Restart after deploy
systemctl restart a-forge

# View logs
journalctl -u a-forge -n 100 --no-pager

# Federation health check
curl -s http://127.0.0.1:7071/api/federation-probe | python3 -m json.tool

For AI Agents

How to Route Through A-FORGE

As an AI agent in the federation, you do not call A-FORGE's internal gates directly. You route through its public MCP surface and the A2A protocol.

Agent Intent
    │
    ▼
arif_session_init()           ← constitutional session binding
    │
    ▼
arif_mind_reason(mode=plan)   ← generate an execution plan
    │
    ▼
arif_judge_deliberate()       ← arifOS constitutional verdict
    │
    │  JUDGE_SEAL_AUTHORIZATION received
    │
    ▼
arif_forge_execute()          ← A-FORGE receives, gates, executes
    │
    ▼
arif_reply_compose()          ← surface the result to user

The Forge Gate Rules for Agents

When calling arif_forge_execute():

RuleWhat it means
You must carry a valid JUDGE_SEAL_AUTHORIZATIONThe forge is cold without it. The gate will 888_HOLD.
Your session must be boundarif_session_init() must have been called. Anonymous execution is blocked at F11.
Reversible actions pass fasterreversibility_score > 0.5 skips Layer 4 entirely.
Irreversible actions need your ack_irreversibleIf ack_irreversible: false and the action is irreversible → 888_HOLD.
The forge gate is orderedLayer 1 → 2 → 3 → 4. No path skips any layer.
HARAM at Layer 1 has no appealrm -rf /, DROP TABLE, dd if=/dev/zero — blocked permanently.

Example: Executing a GEOX data ingest

// DO: route through arifOS
const plan = await arifos.arif_mind_reason({
  mode: "plan",
  query: "Ingest LAS file for Well Bonanza-1"
});

const verdict = await arifos.arif_judge_deliberate({
  mode: "judge",
  candidate: plan.plan_id,
  ack_irreversible: false  // reversible = no HOLD
});
// → { verdict: "SEAL", judge_state_hash: "sha256:abcd..." }

const result = await aforge.arif_forge_execute({
  mode: "engineer",
  manifest: plan.manifest,
  judge_state_hash: verdict.judge_state_hash
});
// → A-FORGE auto-routes to GEOX MCP, returns QC results

// DON'T: call A-FORGE directly without judgment
// ❌ aforge.execute(raw_command)   ← blocked at Layer 4
// ❌ aforge.build({ skip_gate: true }) ← blocked at Layer 1

For Institutions

Governed Execution, Not Autonomous Agency

A-FORGE is built for institutions that need execution with constitutional guarantees — not black-box autonomy.

Institutional NeedA-FORGE Mechanism
Audit trailEvery execution path logged to Supabase + VAULT999. Who authorized, what ran, what was the result, what was the reversibility score.
No self-authorizationA-FORGE cannot approve its own execution. The JUDGE_SEAL_AUTHORIZATION must come from arifOS. No employee, no agent, no bypass.
Separation of powersarifOS judges. AAA routes. A-FORGE executes. No single organ holds all three.
Reversibility gatesIrreversible actions require explicit approval. 888_HOLD escalation with human-verifiable tickets.
Defense in depth4-layer gate chain. Even if Layer 2 is bypassed, Layers 1 and 3 remain. F14 is dead as a constitutional floor (Sovereign Ruling 2026-06-13); physical-kill-switch claims are reframed as F2 TRUTH + F3 TRI-WITNESS cross-verify protocol.
ObservabilityPrometheus dashboards. Supabase tool call receipts. Langfuse trace sessions. No execution is invisible.
AGPL-3.0 copyleftThe governed execution runtime is free software. Any modification that runs on a network server must release its source. The constitutional authority (arifOS) remains the sole arbiter of lawful use.

The AGPL-3.0 Guarantee

A-FORGE is licensed under the GNU Affero General Public License v3.0. This means:

  • You can run it for any purpose
  • You can study it and modify it
  • You can redistribute it with your changes
  • You MUST share your changes if you run the modified version on a network server
  • The constitutional authority (arifOS) is NOT covered by this license — it is the arbiter, not the runtime

AGPL-3.0 was chosen deliberately. Governed execution is meaningless if the governance itself is proprietary.


Known Limitations

LimitationStatusNotes
Pre-existing CI rot on main⚠️ KnownBoundary Guard + AF-FORGE CI checks fail on main. These are CI infrastructure issues, not code defects. make test passes locally.
No domain logic✅ By designA-FORGE is TypeScript-only. All geoscience/capital/human computation stays in Python MCP organs.
Requires arifOS upstream✅ By designA-FORGE cannot execute without arifOS. This is the architecture, not a bug.
GENESIS/012 stub⏳ PendingFull canon expansion pending F13 sovereign ratification.
No production LLM router⚠️ RoadmapBudgetAwareRouter and FallbackProvider exist but need production hardening.
25 test suites, not all pass CI⚠️ KnownLocal make test passes; CI infrastructure is stale.

Federation Cross-Reference

A-FORGE is one of 7 organs in the arifOS Federation. Every organ has its own repository, port, and constitutional role. MIND:51001 and MEMORY:51002 are federated intelligence services hosted by A-FORGE, not separate organs. arif-sites is a public surface, not an organ.

OrganRepositoryRolePortLicense
arifOSariffazil/arifosConstitutional Kernel · Judge8088AGPL-3.0
A-FORGEariffazil/A-FORGEExecution Shell · Forge · MIND/MEMORY host7071AGPL-3.0
AAAariffazil/aaaControl Plane · Cockpit3001AGPL-3.0
GEOXariffazil/geoxEarth Intelligence8081AGPL-3.0
WEALTHariffazil/wealthCapital Intelligence18082AGPL-3.0
WELLariffazil/wellHuman Readiness18083AGPL-3.0
APEXariffazil/apex888 JUDGE (legacy health probe)3002AGPL-3.0

Live federation status: FEDERATION_STATUS.md Federation topology: /root/CONTEXT.md on the VPS (live state)


Build, Test, Deploy

Local Development

# Install
npm install

# Build TypeScript → dist/
npm run build

# Run test suites (26 suites, ~4,700 lines)
make test
# → security-audit + build + all test suites

# Lint
npx tsc --noEmit

# Start locally
node dist/interfaces/server.js
# → listening on 127.0.0.1:7071

Production (bare-metal systemd)

# Build & test
make test

# Deploy (commits should already be pushed to origin/main)
systemctl restart a-forge

# Verify
curl -s http://127.0.0.1:7071/health | python3 -m json.tool
# → {"ok":true,"service":"A-FORGE","version":"2026.06.06"}

# Check federation organs
curl -s http://127.0.0.1:7071/api/federation-probe | python3 -m json.tool
# → {"verdict":"GREEN","up":5,"total":5}

# Monitor
journalctl -u a-forge -f

Available Makefile Targets

TargetDescription
make buildSecurity audit (security-audit.mk) then TypeScript build
make testSecurity audit + build + 26 test suites
make installnpm install
make cleanRemove dist/ and node_modules/

Security Audit (Steel Security Layer)

Every make build and make test runs four tools non-blocking:

ToolWhat it scans
TrivyKnown CVEs in dependencies
SemgrepRisky code patterns (injection, hardcoded credentials)
GitleaksCommitted secrets (API keys, tokens)
Ruff(Python organs only — not applicable to A-FORGE TypeScript)

CRITICAL/HIGH findings fire a 888_HOLD event into NATS. The scanners never block the build pipeline.


GENESIS Chain

A-FORGE's constitutional mandate is anchored in the federation's GENESIS chain:

NumberDocumentStatus
000arifOS/GENESIS/000_KERNEL_CANON.md✅ CANON — root source of truth
012A-FORGE/GENESIS/012_AFORGE_MANDATE.md⏳ STUB — full canon pending F13

The GENESIS chain provides ordinal numbering for every constitutional document across the federation. 012 is reserved for A-FORGE. Full canon expansion requires F13 sovereign ratification.

Invariants from 012 (binding regardless of stub status):

  1. Never self-authorize. Every execution requires JUDGE_SEAL_AUTHORIZATION.
  2. Never adjudicate. Constitutional verdicts are arifOS territory only.
  3. Never compute domain logic. No NumPy/Pandas/SciPy.
  4. Always log. Every execution path produces F11-auditable telemetry.

License & Sovereignty

A-FORGE — Governed Execution Shell of the arifOS Federation
Copyright (C) 2025–2026  Muhammad Arif bin Fazil

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

The execution runtime is free software. The constitutional authority (arifOS) is the sole arbiter of its lawful use.

F13 SOVEREIGN: Muhammad Arif bin Fazil holds absolute veto over all execution paths. This license grants code freedom. It does not grant constitutional authority. The forge is governed. The constitution is sovereign.


Ver o original no GitHub

Bom para

Relacionados