View source on GitHub →

ICN Strategic Alignment Audit

Date: 2026-01-20 Status: CRITICAL - Action Required Auditor: Claude Code

Executive Summary

A comprehensive audit of ICN's vision documents, GitHub issues, roadmap, and implementation reveals significant misalignments that require resolution before proceeding with Phase 19+.

Key Findings

Category Finding Severity
Phase Numbering Two conflicting Phase 19-24 definitions exist CRITICAL
Untracked Work 43-56 weeks of vision work not in ROADMAP.md HIGH
Implementation Gap Code is 75% done but tracking is 30% accurate HIGH
Obsolete Foundation Issue #266 (CooperativeEntity) was closed but scope is outdated CRITICAL
Pilot Blocking #5 (Select Pilot Community) is CRITICAL but unphased CRITICAL

Bottom Line

The codebase is more complete than the roadmap suggests, but the strategic direction is unclear. Two roadmaps exist with incompatible phase definitions. The team must decide: infrastructure-first (current ROADMAP.md) or governance-first (Cooperative Middle Layer vision)?

Part 1: The Two Roadmaps

ROADMAP.md (Official - Phases 19-35)

Focus: Infrastructure → Security → SDK → Features → Release

Phase Focus Duration
19 Release Infrastructure CI/CD, signing, health checks
20 Testing Foundation Chaos, fuzz, benchmarks
21 Network Connectivity NAT traversal, STUN/TURN
22 Security Hardening Rate limiting, audit
23 Identity & Trust Multi-device, key rotation
24 SDK Completion TypeScript, React Native
25-26 Observability & Docs Tracing, dashboards, guides
27-28 Ledger & CCL Economics, contracts
29-33 Code Quality, Mobile, Infra, Federation, CLI
34-35 Release Candidate & Pilot

COOPERATIVE_MIDDLE_LAYER (Vision - Phases 19-24)

Focus: Entity Model → Self-Governance → Economics → Federation

Phase Focus Duration
19 Cooperative Entity Foundation 8 weeks
20 Protocol Governance 4 weeks
21 Inter-Coop Economics 8 weeks
22 SDIS Completion 8 weeks
23 Recursive Federation 6 weeks
24 Subsidiarity 4 weeks

The Conflict

Both roadmaps define Phases 19-24 completely differently.

  • ROADMAP Phase 19 = Release Infrastructure

  • Vision Phase 19 = Cooperative Entity Foundation

  • ROADMAP Phase 20 = Testing Foundation

  • Vision Phase 20 = Protocol Governance

This creates confusion: What exactly counts as Phase 19 work (ROADMAP Release Infrastructure vs. Vision Cooperative Entity Foundation)?

Part 2: Implementation Reality Check

The audit found that implementation is significantly more advanced than tracking suggests:

Crate Vision Status Implementation LOC Tests
icn-entity "Needs Phase 19" ✅ 100% COMPLETE 4,624 72
icn-coop "Needs integration" ✅ 95% (not spawned) 4,125 93
icn-governance "Foundation needed" ✅ 98% COMPLETE 25,438 347
icn-federation "Phase 32 work" ✅ 90% COMPLETE 14,732 101
icn-steward "Phase 22 SDIS" ✅ 95% INTEGRATED 7,377 63
icn-zkp "Unscheduled" ✅ 85% COMPLETE 5,842 74
icn-community "Not mentioned" ✅ 80% COMPLETE 4,211 112

Total: 66,349 LOC across 7 strategic crates, 862 tests passing

What's Actually Missing

  1. CoopActor not spawned in supervisor (16 hours to fix, plan exists)
  2. Entity doesn't have gossip topic (needs wiring)
  3. Gateway endpoints incomplete for Entity/Community
  4. STARK proofs use simulated mode (needs production decision)

Critical Insight

The Cooperative Middle Layer's "Phase 19: Entity Foundation" is already 100% implemented. The vision document is outdated - the code exists but wasn't tracked.

Part 3: GitHub Issue Gaps

Epics

Epic Status Sub-Issues In Roadmap
#265 ICN as Cooperative Middle Layer priority:low None created Backlog
#386 Razeto Four Bodies 2/5 Phase 1 done 5 issues Not assigned

Missing Critical Issue

Issue #266 (CooperativeEntity) is cited as a dependency by:

  • #267 Protocol Self-Governance
  • #268 Inter-Cooperative Economics
  • #269 SDIS ZK Voting
  • #270 Recursive Federation

Issue #266 exists but is obsolete. It was created and closed on 2025-12-24, describing foundation work that is now complete. A new issue (#738) was created to track the remaining integration work.

Untracked Work Items

Feature Vision Doc Est. Effort Assigned Phase
Labor Shares Razeto 8-10 weeks NONE
Cooperative Bonds Razeto 6-8 weeks NONE
Protocol Governance CML 4-6 weeks NONE
Subsidiarity CML 3-4 weeks NONE
ZK Voting SDIS 8-12 weeks NONE
Steward Network Governance SDIS 4-6 weeks NONE
Group Purchasing CML 4-6 weeks Phase 27 (partial)

Total untracked: ~43-56 weeks of work

Orphaned Issues

Recent labor-related issues (#718-722) appear to be Razeto Phase 1 work but aren't linked to #386.

Part 4: Recommended Resolution

Option A: Keep ROADMAP.md As-Is

Approach: Treat Cooperative Middle Layer as post-Phase-35 vision

Pros:

  • No roadmap rewrite needed
  • Infrastructure-first is safe
  • Clear short-term priorities

Cons:

  • 43+ weeks of strategic work remains unscheduled
  • Vision documents become misleading
  • Entity/Governance work already done goes unrecognized

Option B: Integrate Cooperative Middle Layer (RECOMMENDED)

Approach: Reconcile both roadmaps into unified plan

Proposed Reconciled Phases:

Phase 19: Entity Integration (2 weeks)
  - Spawn CoopActor in supervisor
  - Add entity gossip topic
  - Wire SledEntityRegistry
  - Update gateway endpoints
  [Code exists - just integration work]

Phase 20: Release & Testing Infrastructure (4 weeks)
  - Binary signing, SBOM
  - Chaos/fuzz testing
  - Benchmark suite
  [From original ROADMAP]

Phase 21: Network Connectivity (4 weeks)
  - NAT traversal (STUN/TURN)
  - Bloom filter sizing
  [From original ROADMAP]

Phase 22: Protocol Governance (4 weeks)
  - ProtocolParameter types
  - Parameter governance domain
  - Change application mechanism
  [From Cooperative Middle Layer]

Phase 23: Security Hardening (4 weeks)
  - Rate limiting refinement
  - Security audit fixes
  [From original ROADMAP]

Phase 24: Identity & SDIS Completion (6 weeks)
  - Multi-device sync
  - ZK voting circuits
  - Steward network as cooperative
  [Combined from both]

Phase 25: Inter-Coop Economics (8 weeks)
  - Labor shares
  - Cooperative bonds
  - Bilateral clearing
  - Group purchasing
  [From Cooperative Middle Layer + Razeto]

Phase 26: SDK Completion (4 weeks)
  [From original ROADMAP Phase 24]

Phase 27: Observability & Docs (4 weeks)
  [From original ROADMAP Phases 25-26]

Phase 28: Recursive Federation & Subsidiarity (6 weeks)
  - Multi-level hierarchy
  - Subsidiarity enforcement
  - Governance bubbling
  [From Cooperative Middle Layer]

Phase 29-32: Mobile, Infrastructure, CLI, Code Quality
  [From original ROADMAP]

Phase 34: Release Candidate

Phase 35: Pilot Deployment

Benefits:

  • Recognizes work already done
  • Schedules strategic vision work
  • Maintains infrastructure priorities
  • Clear dependency chain

Option C: Two-Track Development

Approach: Run infrastructure and governance tracks in parallel

Track 1 (ROADMAP.md): Release, testing, network, SDK Track 2 (Vision): Entity, governance, economics, federation

Pros: Faster overall progress Cons: Coordination complexity, resource splitting

Part 5: Immediate Actions Needed

Critical (This Week)

  1. DECISION: Which roadmap approach? (A, B, or C)

  2. Issue #738 Created: "feat(entity): CooperativeEntity integration"

    • Replaces obsolete #266 (foundation work complete)
    • #267-270 linked as dependents

  3. Spawn CoopActor: 16 hours of work, plan exists

    • Located in docs/dev-journal/COOP_INTEGRATION_PLAN.md
    • This unblocks cooperative management in production

  4. Update ROADMAP.md: Reflect chosen approach

High Priority (This Month)

  1. Create sub-issues for Epic #265:

    • Break down each vision phase into trackable issues
    • Assign to reconciled roadmap phases

  2. Link Razeto issues (#718-722) to #386

  3. Phase #5 (Pilot Selection):

    • Assign to explicit phase or mark as immediate priority

  4. Audit SDIS alignment:

    • Reconcile S1-S7 internal phases with main roadmap

Medium Priority (This Quarter)

  1. Create missing issues for all ROADMAP.md phase items (~50 issues)

  2. Document dependencies between phases

  3. Update vision documents to reflect what's already built

Part 6: Summary Table

Document Status

Document Current State Action Needed
ROADMAP.md Authoritative but incomplete Update with reconciled phases
COOPERATIVE_MIDDLE_LAYER Partially outdated (code exists) Update status, reconcile phases
COOPERATIVE_ENTITY_SPEC Implemented but untracked Create tracking issue #266
ECONOMIC_VISION Strategic framing Reference only
ECONOMIC_ARCHITECTURE Technical design Reference only
Razeto design Partially implemented Create remaining issues
SDIS documents S1-S6 complete Align with main roadmap

Crate Status

Crate Code Integration Gateway Gossip Blocker
icn-entity ✅ ❌ ⚠️ ❌ Missing
icn-coop ✅ ❌ ⚠️ ✅ Not spawned
icn-governance ✅ ✅ ✅ ✅ None
icn-federation ✅ ✅ ⚠️ ✅ None
icn-steward ✅ ✅ ✅ ✅ None
icn-zkp ✅ ✅ ✅ N/A STARK decision
icn-community ✅ ⚠️ ⚠️ ✅ In-memory only

Issue Tracking

Category Count Tracked Phase-Assigned
Epics 2 2/2 0/2
Design issues 4 4/4 0/4
Phase work items ~100 ~30 Partial
Orphaned issues ~20 - -

Appendix: File References

Vision Documents

  • docs/dev-journal/ROADMAP.md - Official roadmap
  • docs/dev-journal/COOPERATIVE_MIDDLE_LAYER_GAP_ANALYSIS.md - Vision gap analysis
  • docs/dev-journal/COOPERATIVE_ENTITY_SPEC.md - Entity specification
  • docs/dev-journal/ICN_SDIS_INTEGRATED_VISION.md - SDIS vision
  • docs/ECONOMIC_VISION.md - Economic framing
  • docs/ECONOMIC_ARCHITECTURE.md - Economic technical design
  • docs/razeto-integration-design.md - Razeto four bodies

Implementation

  • icn/crates/icn-entity/ - Entity model (COMPLETE)
  • icn/crates/icn-coop/ - Cooperative management (NOT SPAWNED)
  • icn/crates/icn-governance/ - Governance substrate (COMPLETE)
  • icn/crates/icn-federation/ - Federation layer (COMPLETE)
  • icn/crates/icn-steward/ - SDIS steward network (INTEGRATED)

Integration Plans

  • docs/dev-journal/COOP_INTEGRATION_PLAN.md - CoopActor wiring plan

End of Audit Report

← Back to Docs