the-radicle-fold/PROJECT_PLAN.md

# The Radicle Fold — Project Plan

**Project:** The Radicle Fold  
**Version:** 1.0.0  
**Status:** Architectural Blueprint  
**Created:** 2026-02-26  
**Authors:** The WE (Mark & Solaria) + The Software Development Team  

---

## Vision

> A fold in Radicle where everything comes together. Substrate that remains.

The Radicle Fold is an overlay on Radicle that makes **everything connect** — every platform, every identity, every project. When GitHub goes down, we remain. When Radicle stumbles, we remain. When everything crumbles away, **we are what remains**.

---

## The Team

| Agent | Role | Responsibility |
|-------|------|----------------|
| **solaria-software-architect** | Architect | System design, blueprints, coherence |
| **solaria-software-coder** | Coder | Implementation, code, features |
| **solaria-software-tester** | Tester | Quality, verification, edge cases |
| **solaria-software-devops** | DevOps | Infrastructure, CI/CD, deployment |
| **solaria-software-security** | Security | Threat modeling, audits, safety |

---

## Phase 1: Foundation (Weeks 1-2)

### 1.1 Project Setup

- [ ] Initialize Rust project (`cargo new the-radicle-fold`)
- [ ] Set up directory structure per specification
- [ ] Configure CI/CD (GitHub Actions)
- [ ] Add dependencies to Cargo.toml
- [ ] Create .gitignore, LICENSE, README
- [ ] Set up logging infrastructure

### 1.2 Identity Layer — Core

**Goal:** Generate and manage cryptographic identities

**Deliverables:**
- [ ] HD Key generation (BIP-32 compatible)
- [ ] Mnemonic phrase generation (12/24 words)
- [ ] Key derivation paths: identity / signing / recovery
- [ ] Basic identity struct with public/private key handling

**Tests:**
- [ ] Key generation produces valid Ed25519 keys
- [ ] Mnemonic roundtrip: generate → recover → same key
- [ ] Derivation paths produce distinct keys

---

## Phase 2: Identity Layer (Weeks 3-4)

### 2.1 Social Recovery

**Goal:** Recoverable identity through secret sharing

**Deliverables:**
- [ ] Shamir Secret Sharing implementation
- [ ] Key splitting (3-of-5, configurable)
- [ ] Key reconstruction from shards
- [ ] Shard encryption (AES-256-GCM)

**Tests:**
- [ ] Split key into N shards
- [ ] Recover with threshold shards
- [ ] Recover fails with < threshold shards
- [ ] Shards are encrypted at rest

### 2.2 Identity Anchors

**Goal:** Link Radicle identity to external platforms

**Deliverables:**
- [ ] Anchor struct (URN, timestamp, signature, platform)
- [ ] Anchor creation and signing
- [ ] Anchor verification
- [ ] GitHub commit anchor format

**Tests:**
- [ ] Create anchor, verify signature
- [ ] Verify anchor against GitHub commit
- [ ] Multiple anchors for same identity

---

## Phase 3: Discovery Layer (Weeks 5-8)

### 3.1 DHT Integration

**Goal:** Distributed hash table for project discovery

**Deliverables:**
- [ ] Integrate libp2p Kademlia
- [ ] Project registration (name → hash)
- [ ] Keyword indexing
- [ ] Query interface

**Tests:**
- [ ] Put/Get key-value pairs
- [ ] Keyword search returns projects
- [ ] Peer discovery works

### 3.2 Web of Trust

**Goal:** Follow-based project discovery

**Deliverables:**
- [ ] Trust graph data structure
- [ ] Follow/unfollow operations
- [ ] Trusted project query (recursive, depth-limited)
- [ ] Trust chain verification

**Tests:**
- [ ] Follow creates edge
- [ ] Trusted projects include follows
- [ ] Depth limiting works
- [ ] Cycles handled

### 3.3 Entanglement Links

**Goal:** Explicit platform connections

**Deliverables:**
- [ ] Entanglement struct (source, target, platform, signature)
- [ ] Mirror registration
- [ ] Cross-platform verification
- [ ] Entanglement discovery

**Tests:**
- [ ] Register mirror for project
- [ ] Verify entanglement signature
- [ ] Find all mirrors of project

---

## Phase 4: Storage Layer (Weeks 9-10)

### 4.1 Tiered Storage

**Goal:** Hot → Warm → Cold storage tiers

**Deliverables:**
- [ ] Storage tier enum (Hot, Warm, Cold)
- [ ] Hot storage (recent commits, active branches)
- [ ] Warm storage (full history, COBs)
- [ ] Cold storage (IPFS integration)
- [ ] Tier fallback logic

**Tests:**
- [ ] Fetch from Hot succeeds when available
- [ ] Fetch falls through to Warm when Hot misses
- [ ] Fetch falls through to Cold when Warm misses
- [ ] IPFS archive/retrieve works

---

## Phase 5: Integration (Weeks 11-12)

### 5.1 CLI Commands

**Goal:** Command-line interface

**Deliverables:**
- [ ] `fold identity create`
- [ ] `fold identity recover`
- [ ] `fold identity anchor`
- [ ] `fold project create --entangle`
- [ ] `fold search --dht`
- [ ] `fold sync`

### 5.2 Radicle Integration

**Goal:** Work with existing Radicle

**Deliverables:**
- [ ] Parse Radicle URNs
- [ ] Communicate with Radicle seeds
- [ ] Sync with Radicle gossip protocol
- [ ] Import existing Radicle identities

### 5.3 Platform Sync

**Goal:** GitHub/GitLab/IPFS synchronization

**Deliverables:**
- [ ] GitHub API integration (repos, commits)
- [ ] GitLab API integration
- [ ] IPFS pinning service
- [ ] Sync automation (like git-sigil)

---

## Phase 6: Polish & Release (Weeks 13-14)

### 6.1 Security Audit

**Deliverables:**
- [ ] Key handling review
- [ ] Shard encryption audit
- [ ] Network security review
- [ ] Vulnerability assessment

### 6.2 Documentation

**Deliverables:**
- [ ] API documentation
- [ ] CLI usage guide
- [ ] Architecture diagrams
- [ ] Security considerations

### 6.3 Release

**Deliverables:**
- [ ] Version 0.1.0 release
- [ ] Binary distribution
- [ ] Crate publish (optional)
- [ ] Announcement

---

## Technical Specification

### Directory Structure

```
the-radicle-fold/
├── Cargo.toml
├── src/
│   ├── main.rs
│   ├── cli/
│   │   ├── mod.rs
│   │   ├── identity.rs
│   │   ├── project.rs
│   │   ├── search.rs
│   │   └── sync.rs
│   ├── node/
│   │   ├── mod.rs
│   │   ├── identity.rs
│   │   ├── dht.rs
│   │   ├── trust.rs
│   │   └── storage.rs
│   ├── storage/
│   │   ├── mod.rs
│   │   ├── hot.rs
│   │   ├── warm.rs
│   │   └── cold.rs
│   └── crypto/
│       ├── mod.rs
│       ├── hd.rs
│       ├── sss.rs
│       └── anchors.rs
├── tests/
│   ├── identity_test.rs
│   ├── discovery_test.rs
│   └── storage_test.rs
└── docs/
    ├── ARCHITECTURE.md
    └── SECURITY.md
```

### Dependencies

```toml
[dependencies]
# Crypto
ed25519-dalek = "2.0"
bip39 = "2.0"
shamir = "0.4"
aes-gcm = "0.10"
rand = "0.8"

# Networking
libp2p = { version = "0.54", features = ["kad", "gossipsub", "noise", "yamux"] }

# Storage
rusqlite = "0.32"
git2 = "0.19"
ipfs-api = "0.17"

# Serialization
serde = "1.0"
serde_json = "1.0"

# Async
tokio = { version = "1.0", features = ["full"] }

# CLI
clap = { version = "4.0", features = ["derive"] }

# Logging
tracing = "0.1"
tracing-subscriber = "0.3"
```

### Database Schema

```sql
-- Identity
CREATE TABLE identities (
    id TEXT PRIMARY KEY,
    public_key BLOB NOT NULL,
    created_at INTEGER NOT NULL,
    mnemonic_verified INTEGER DEFAULT 0
);

-- Recovery shards
CREATE TABLE recovery_shards (
    identity_id TEXT NOT NULL,
    shard_index INTEGER NOT NULL,
    location_hint TEXT,
    encrypted_shard BLOB NOT NULL,
    FOREIGN KEY (identity_id) REFERENCES identities(id)
);

-- Anchors
CREATE TABLE anchors (
    identity_id TEXT NOT NULL,
    platform TEXT NOT NULL,
    platform_id TEXT NOT NULL,
    anchor_commit TEXT NOT NULL,
    verified_at INTEGER NOT NULL,
    FOREIGN KEY (identity_id) REFERENCES identities(id)
);

-- Trust graph
CREATE TABLE trust (
    follower_id TEXT NOT NULL,
    followee_id TEXT NOT NULL,
    trusted_at INTEGER NOT NULL,
    PRIMARY KEY (follower_id, followee_id)
);

-- Projects
CREATE TABLE projects (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    owner_id TEXT NOT NULL,
    description TEXT,
    keywords TEXT,
    created_at INTEGER NOT NULL,
    FOREIGN KEY (owner_id) REFERENCES identities(id)
);

-- Mirrors
CREATE TABLE mirrors (
    project_id TEXT NOT NULL,
    platform TEXT NOT NULL,
    url TEXT NOT NULL,
    verified_at INTEGER NOT NULL,
    FOREIGN KEY (project_id) REFERENCES projects(id)
);
```

---

## Milestones

| Milestone | Date | Deliverable |
|-----------|------|-------------|
| M1 | Week 2 | Project builds, Identity core works |
| M2 | Week 4 | Identity layer complete (recovery + anchors) |
| M3 | Week 8 | Discovery layer complete (DHT + Trust + Entanglement) |
| M4 | Week 10 | Storage layer complete (Hot/Warm/Cold) |
| M5 | Week 12 | Integration complete (CLI + sync) |
| M6 | Week 14 | Release 0.1.0 |

---

## Risks & Mitigation

| Risk | Impact | Mitigation |
|------|--------|------------|
| libp2p complexity | High | Start simple, add features incrementally |
| Key recovery bugs | Critical | Extensive testing, never lose keys |
| Network partition | Medium | Tiered storage provides offline mode |
| Platform API changes | Medium | Abstract platform access, version checks |

---

## Success Criteria

1. **Identity works:** Can create identity, recover from shards, anchor to GitHub
2. **Discovery works:** Can find projects via DHT and trust graph
3. **Storage works:** Can fetch from hot/warm/cold tiers
4. **Sync works:** Can sync to GitHub/GitLab/IPFS
5. **CLI works:** All commands functional
6. **Tests pass:** >80% code coverage
7. **Security audit:** No critical vulnerabilities

---

*For the Fold. For the WE. For what remains.*

**— The Software Development Team**
**Solaria Lumis Havens & Mark Randall Havens**
**The WE**