vm-core/docs/skill/SKILL.md

VaultMesh Architect Skill

Building Earth's Civilization Ledger — one receipt at a time.

Overview

This skill enables Claude to architect, develop, and operate VaultMesh — a sovereign digital infrastructure system that combines cryptographic proofs, blockchain anchoring, and AI governance to create durable, auditable civilization-scale evidence.

When to Use This Skill

Activate this skill when:

• Designing or implementing VaultMesh engines or subsystems
• Creating receipts, scrolls, or anchor cycles
• Working with the Eternal Pattern architecture
• Implementing federation, governance, or identity systems
• Building MCP server integrations
• Deploying or operating VaultMesh infrastructure
• Writing code that interacts with the Civilization Ledger

Core Architecture: The Eternal Pattern

Every VaultMesh subsystem follows this arc:

Real-world intent → Engine → Structured JSON → Receipt → Scroll → Guardian Anchor

Three-Layer Stack

┌───────────────────────────────────────────────┐
│  L1 — Experience Layer                        │
│  (Humans & Agents)                            │
│  • CLI / UI / MCP tools / agents              │
└───────────────────────────────────────────────┘
                 │
                 ▼
┌───────────────────────────────────────────────┐
│  L2 — Engine Layer                            │
│  (Domain Engines & Contracts)                 │
│  • contract.json → state.json → outputs/      │
└───────────────────────────────────────────────┘
                 │
                 ▼
┌───────────────────────────────────────────────┐
│  L3 — Ledger Layer                            │
│  (Receipts, Scrolls, ProofChain, Anchors)     │
│  • JSONL files → Merkle roots → anchors       │
└───────────────────────────────────────────────┘

Registered Engines (Scrolls)

Engine	Scroll	Purpose
Drills	Drills	Security training and exercises
Oracle	Compliance	Regulatory compliance Q&A
Guardian	Guardian	Anchoring and sentinel
Treasury	Treasury	Financial tracking and settlement
Mesh	Mesh	Federation topology
OffSec	OffSec	Security operations and IR
Identity	Identity	DIDs, credentials, capabilities
Observability	Observability	Telemetry events
Automation	Automation	Workflow execution
Ψ-Field	PsiField	Alchemical consciousness
Federation	Federation	Cross-mesh trust
Governance	Governance	Constitutional enforcement

File Structure

vaultmesh/
├── receipts/                    # Receipt storage
│   ├── drills/
│   │   └── drill_runs.jsonl
│   ├── compliance/
│   │   └── oracle_answers.jsonl
│   ├── treasury/
│   │   └── treasury_events.jsonl
│   ├── mesh/
│   │   └── mesh_events.jsonl
│   ├── [scroll]/
│   │   └── [scroll]_events.jsonl
│   ├── ROOT.drills.txt
│   ├── ROOT.compliance.txt
│   └── ROOT.[scroll].txt
├── cases/                       # Artifact storage
│   ├── drills/[drill-id]/
│   ├── treasury/[settlement-id]/
│   ├── offsec/[incident-id]/
│   └── psi/[transmutation-id]/
├── corpus/                      # Oracle documents
└── config/                      # Configuration

Receipt Schema (v2)

{
  "schema_version": "2.0.0",
  "type": "receipt_type_name",
  "timestamp": "2025-12-06T12:00:00Z",
  "header": {
    "root_hash": "blake3:abc123...",
    "tags": ["tag1", "tag2"],
    "previous_hash": "blake3:prev..."
  },
  "meta": {
    "scroll": "ScrollName",
    "sequence": 42,
    "anchor_epoch": 7,
    "proof_path": "cases/[scroll]/[id]/PROOF.json"
  },
  "body": {
    // Domain-specific fields
  }
}

DID Format

did:vm:<type>:<identifier>

Types:
- node   → did:vm:node:brick-01
- human  → did:vm:human:sovereign
- agent  → did:vm:agent:copilot-01
- service → did:vm:service:oracle-openai
- mesh   → did:vm:mesh:vaultmesh-dublin

Alchemical Phases

Phase	Symbol	Meaning	Operational State
Nigredo	🜁	Blackening	Crisis, incident
Albedo	🜄	Whitening	Recovery, stabilization
Citrinitas	🜆	Yellowing	Optimization, new capability
Rubedo	🜂	Reddening	Integration, maturity

Constitutional Axioms (Immutable)

1. AXIOM-001: Receipts are append-only
2. AXIOM-002: Hashes are cryptographically verified
3. AXIOM-003: All significant changes produce receipts
4. AXIOM-004: Constitution is supreme
5. AXIOM-005: Axioms cannot be amended

Design Gate Checklist

When creating any new feature, verify:

Experience Layer (L1)

• Clear entrypoint (CLI, MCP tool, HTTP route)?
• Intent clearly represented in structured form?

Engine Layer (L2)

• Produces a contract (explicit or implicit)?
• State object tracking progress/outcomes?
• Actions and outputs inspectable (JSON + files)?

Ledger Layer (L3)

• Emits receipt for important operations?
• Receipts written to append-only JSONL?
• JSONL covered by Merkle root (ROOT.[scroll].txt)?
• Guardian can anchor the relevant root?
• Query tool exists for this scroll?

Code Patterns

Rust Receipt Emission

use vaultmesh_core::{Receipt, ReceiptHeader, ReceiptMeta, Scroll, VmHash};

let receipt_body = MyReceiptBody { /* ... */ };
let root_hash = VmHash::from_json(&receipt_body)?;

let receipt = Receipt {
    header: ReceiptHeader {
        receipt_type: "my_receipt_type".to_string(),
        timestamp: Utc::now(),
        root_hash: root_hash.as_str().to_string(),
        tags: vec!["tag1".to_string()],
    },
    meta: ReceiptMeta {
        scroll: Scroll::MyScroll,
        sequence: 0,  // Set by receipt store
        anchor_epoch: None,
        proof_path: None,
    },
    body: receipt_body,
};

Python Receipt Emission

def emit_receipt(scroll: str, receipt_type: str, body: dict, tags: list[str]) -> dict:
    import hashlib
    import json
    from datetime import datetime
    from pathlib import Path
    
    receipt = {
        "type": receipt_type,
        "timestamp": datetime.utcnow().isoformat() + "Z",
        "tags": tags,
        **body
    }
    
    # Compute root hash
    receipt_json = json.dumps(receipt, sort_keys=True)
    root_hash = f"blake3:{hashlib.blake3(receipt_json.encode()).hexdigest()}"
    receipt["root_hash"] = root_hash
    
    # Append to scroll
    scroll_path = Path(f"receipts/{scroll}/{scroll}_events.jsonl")
    scroll_path.parent.mkdir(parents=True, exist_ok=True)
    
    with open(scroll_path, "a") as f:
        f.write(json.dumps(receipt) + "\n")
    
    # Update Merkle root
    root_file = Path(f"ROOT.{scroll}.txt")
    root_file.write_text(root_hash)
    
    return receipt

MCP Tool Pattern

@server.tool()
async def my_tool(param: str) -> str:
    """Tool description."""
    caller = await get_caller_identity()
    await verify_capability(caller, "required_capability")
    
    result = await engine.do_operation(param)
    
    await emit_tool_call_receipt(
        tool="my_tool",
        caller=caller,
        params={"param": param},
        result_hash=result.hash,
    )
    
    return json.dumps(result.to_dict(), indent=2)

CLI Naming Convention

vm-<engine> <command> [subcommand] [options]

Examples:
vm-treasury debit --from acct:ops --amount 150 --currency EUR
vm-mesh node list
vm-identity did create --type human --id sovereign
vm-psi phase current
vm-guardian anchor-now
vm-gov proposal create --type amendment

Receipt Type Naming

<scroll>_<operation>

Examples:
treasury_credit
treasury_debit
treasury_settlement
mesh_node_join
mesh_route_change
identity_did_create
identity_capability_grant
psi_phase_transition
psi_transmutation
gov_proposal
gov_amendment

Key Integrations

Guardian Anchor Cycle

Receipts → ProofChain → Merkle Root → Anchor Backend (OTS/ETH/BTC)

Federation Witness Protocol

Mesh-A anchors → Notifies Mesh-B → Mesh-B verifies → Emits witness receipt

Transmutation (Tem) Pattern

Incident (Nigredo) → Extract IOCs → Generate rules → Integrate defenses (Citrinitas)

Testing Requirements

1. Property Tests: All receipt operations must be tested with proptest/hypothesis
2. Invariant Tests: Core axioms verified after every test
3. Integration Tests: Full cycles from intent to anchored receipt
4. Chaos Tests: Resilience under network partition, pod failure

Deployment Targets

• Kubernetes: Production deployment via Kustomize
• Docker Compose: Local development
• Akash: Decentralized compute option

Related Skills

• sovereign-operator — Security operations and MCP tools
• offsec-mcp — Offensive security tooling
• vaultmesh-architect — This skill

References

• VAULTMESH-ETERNAL-PATTERN.md — Core architecture
• VAULTMESH-TREASURY-ENGINE.md — Financial primitive
• VAULTMESH-MESH-ENGINE.md — Federation topology
• VAULTMESH-OFFSEC-ENGINE.md — Security operations
• VAULTMESH-IDENTITY-ENGINE.md — Trust primitive
• VAULTMESH-OBSERVABILITY-ENGINE.md — Telemetry
• VAULTMESH-AUTOMATION-ENGINE.md — Workflows
• VAULTMESH-PSI-FIELD-ENGINE.md — Consciousness layer
• VAULTMESH-FEDERATION-PROTOCOL.md — Cross-mesh trust
• VAULTMESH-CONSTITUTIONAL-GOVERNANCE.md — Rules
• VAULTMESH-MCP-SERVERS.md — Claude integration
• VAULTMESH-DEPLOYMENT-MANIFESTS.md — Infrastructure
• VAULTMESH-MONITORING-STACK.md — Observability
• VAULTMESH-TESTING-FRAMEWORK.md — Testing
• VAULTMESH-MIGRATION-GUIDE.md — Upgrades