Initialize repository snapshot
This commit is contained in:
Vault Sovereign
338
docs/skill/SKILL.md
Normal file
338
docs/skill/SKILL.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# 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)
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```rust
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
@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
|
||||
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user