Kush Ecosystem Map | parpour
Description: Venture Autonomy Platform & CIV Sim Planning Workspace

Skip to content

# Kush Ecosystem Map ​

Date: 2026-02-21 Scope: Full system architecture and cross-project relationships Status: ACTIVE Owner: Kush Ecosystem Integration Team

## System Architecture Overview ​

    ┌─────────────────────────────────────────────────────────────────────────┐
    │                         KUSH ECOSYSTEM (2026)                            │
    ├─────────────────────────────────────────────────────────────────────────┤
    │                                                                          │
    │  PARPOUR (Planning & Specification Workspace)                          │
    │  └─ Version control for specs, integration contracts, governance       │
    │                                                                          │
    │     ├─ VENTURE (Autonomous Agent Platform)                            │
    │     │  │ Primary Language: Rust/TypeScript (control plane)             │
    │     │  │ Primary Language: Python (agentic workflows)                  │
    │     │  │ Stack: FastAPI, PostgreSQL, async task queue                │
    │     │  │                                                                │
    │     │  ├─ TRACK-A: Artifact Compiler (IR family, deterministic build) │
    │     │  │  ├─ SlideSpec, DocSpec, TimelineSpec, AudioSpec, BoardSpec   │
    │     │  │  └─ Deterministic build contract with provenance chain       │
    │     │  │                                                                │
    │     │  ├─ TRACK-B: Treasury & Compliance (money control, ledger)      │
    │     │  │  ├─ Double-entry accounting (ledger_entries table)           │
    │     │  │  ├─ Spend authorization and policy attestation               │
    │     │  │  └─ Daily reconciliation and drift detection                 │
    │     │  │                                                                │
    │     │  ├─ TRACK-C: Control Plane (orchestration, FSM, tools)         │
    │     │  │  ├─ Workflow DAG execution engine                            │
    │     │  │  ├─ Event bus with strict validation                         │
    │     │  │  ├─ Tool allowlist and per-role capability model            │
    │     │  │  └─ Workspace isolation boundaries                           │
    │     │  │                                                                │
    │     │  └─ Supporting Systems:                                          │
    │     │     ├─ User Management (roles, onboarding, multi-tenant)        │
    │     │     ├─ Operations & Compliance (audit trails, incident doctrine)│
    │     │     └─ Data Model (artifact IR, ledger, workflow tables)        │
    │     │                                                                    │
    │     └─────────── (5 Integration Points) ─────────────────────────────┬─│
    │                                                                        │ │
    │     ├─ CIV (City Simulation Engine)                                  │ │
    │     │  │ Primary Language: Rust (all modules)                         │ │
    │     │  │ Stack: Deterministic tick engine, concurrent simulation     │ │
    │     │  │                                                              │ │
    │     │  ├─ CIV-0001: Core Simulation Loop                            │ │
    │     │  │  └─ Tick-based state machine with deterministic ordering   │ │
    │     │  │                                                              │ │
    │     │  ├─ CIV-0100: Economy v1 (Joule-backed)                      │ │
    │     │  │  ├─ Double-entry ledger (ledger_transfers)                 │ │
    │     │  │  ├─ Market clearing and price discovery                    │ │
    │     │  │  └─ Conservation invariants                                │ │
    │     │  │                                                              │ │
    │     │  ├─ CIV-0101: Two-Zoom LOD (spatial representation)           │ │
    │     │  │  ├─ Tile-based world at regional zoom                      │ │
    │     │  │  └─ Detailed LOD at city zoom                              │ │
    │     │  │                                                              │ │
    │     │  ├─ CIV-0102: Energy Accounting (Joule conservation)          │ │
    │     │  │  ├─ Supply/demand balance tracking                         │ │
    │     │  │  ├─ Renewable variability and storage dynamics             │ │
    │     │  │  └─ Peak-shaving and demand-response mechanics             │ │
    │     │  │                                                              │ │
    │     │  ├─ CIV-0103: Institutions & Citizen Lifecycle                │ │
    │     │  │  ├─ Citizen birth/education/career/retirement/death        │ │
    │     │  │  ├─ Institutional state machine (pending→active→dissolved)  │ │
    │     │  │  └─ Time-series metrics (age, wealth, satisfaction)        │ │
    │     │  │                                                              │ │
    │     │  ├─ CIV-0104: Minimal Constraint Set Theorem                  │ │
    │     │  │  └─ Mathematical foundation for determinism                │ │
    │     │  │                                                              │ │
    │     │  ├─ CIV-0105: War, Diplomacy & Shadow Networks                │ │
    │     │  │  ├─ Geopolitical dynamics and territorial control          │ │
    │     │  │  └─ Shadow networks for covert influence                   │ │
    │     │  │                                                              │ │
    │     │  ├─ CIV-0106: Social, Ideology, Health & Insurgency           │ │
    │     │  │  ├─ Health crises and epidemiology                         │ │
    │     │  │  ├─ Ideological shifts and cultural events                 │ │
    │     │  │  └─ Citizen agency and insurgency mechanics                │ │
    │     │  │                                                              │ │
    │     │  └─ CIV-0107: Joule Economy System v1                         │ │
    │     │     ├─ Energy-backed currency and accounting                  │ │
    │     │     └─ Production cost basis tied to energy consumption       │ │
    │     │                                                                  │
    │     └─────────────────────────────────────────────────────────────────┘
    │
    │  GOVERNANCE LAYER (Applied to all projects)
    │  ├─ Global CLAUDE.md (critical security rules, proactive governance, QA)
    │  ├─ Project-local CLAUDE.md (domain-specific overrides and patterns)
    │  ├─ Spec-first workflow (proposal → design → tasks → implementation)
    │  ├─ Deterministic quality gates (lint, type-check, unit/integration tests)
    │  ├─ Workstream tracking and sub-agent delegation
    │  └─ Library-first philosophy (no reinvention of generic problems)
    │
    └─────────────────────────────────────────────────────────────────────────┘

## Project Inventory ​

### 1. PARPOUR (Specification & Planning Workspace) ​

Location: `/Users/kooshapari/temp-PRODVERCEL/485/kush/parpour/`

Primary Purpose: Central repository for all specification artifacts, cross-project integration contracts, and governance documents for the Kush ecosystem.

Primary Language(s): Markdown (specifications), YAML (configs)

Key Governance Files:

- `CLAUDE.md` - Project-local instructions (spec-first workflow, delegation patterns, quality gates)
- `SPECS_INDEX.md` - Master index of all 20 spec artifacts and 5 cross-track integration points
- `NEXT_STEPS.md` - Implementation priorities (P0/P1/P2 phased roadmap)

Spec Files (Venture track, all in `venture/` directory):

- `TECHNICAL_SPEC.md` - Control-plane architecture, runtime model, security posture
- `TRACK_A_ARTIFACT_DETERMINISM_SPEC.md` - Artifact IR family, deterministic build/replay
- `TRACK_B_TREASURY_COMPLIANCE_SPEC.md` - Money control, double-entry ledger, reconciliation
- `TRACK_C_CONTROL_PLANE.md` - Orchestration, FSM, tool allowlist, incident doctrine
- `API_EVENTS_SPEC.md` - Event envelope schema, FSM transitions, strict validation
- `DATA_MODEL_DB_SPEC.md` - Artifact IR, ledger, workflow, and audit log schemas
- `OPS_COMPLIANCE_SPEC.md` - Compliance machine, audit toolchain, incident playbooks
- `USER_SPEC.md` - User roles, capabilities, onboarding, multi-tenant isolation
- `PRODUCT_MODEL.md` - Vision, users, jobs to be done, success metrics
- `SCHEMA_PACK.md` - Consolidated schema definitions (artifact, ledger, workflow, event)
- `ROLE_TOOL_ALLOWLIST_MATRIX.md` - Per-role capability model and tool allowlists
- `IMPLEMENTATION_ROADMAP.md` - Phased rollout plan (Sandbox → Limited Autopilot → Governed Autonomy)

Documentation Structure:

    parpour/
      ├─ CLAUDE.md (project instructions)
      ├─ SPECS_INDEX.md (master spec index)
      ├─ NEXT_STEPS.md (implementation priorities)
      ├─ venture/ (all Venture specs)
      │   ├─ TECHNICAL_SPEC.md
      │   ├─ TRACK_A_ARTIFACT_DETERMINISM_SPEC.md
      │   ├─ TRACK_B_TREASURY_COMPLIANCE_SPEC.md
      │   ├─ TRACK_C_CONTROL_PLANE.md
      │   └─ ... (9 more spec files)
      └─ docs/
          ├─ governance/ (governance docs)
          ├─ reference/ (quick references, this file)
          ├─ research/ (conversation dumps, analysis)
          ├─ adr/ (architecture decision records)
          ├─ guides/ (implementation guides)
          └─ traceability/
              ├─ CROSS_PROJECT_TRACEABILITY.md (formal integration matrix)
              └─ EVENT_TAXONOMY.md (unified event catalog)

Ownership: Kush Ecosystem Integration Team (coordination role; defers implementation to CIV and Venture teams)

### 2. VENTURE (Autonomous Agent Platform) ​

Location: `/Users/kooshapari/temp-PRODVERCEL/485/kush/venture/` (planned)

Primary Purpose: Production-ready autonomous agent control plane with artifact compiler, treasury system, and compliance machinery.

Primary Language(s):

- Rust (control-plane core, performance-critical paths)
- Python (agentic workflows, policy evaluation, tool implementations)
- TypeScript (frontend, artifact schemas)

Tech Stack:

- Orchestration: FastAPI + async/await (Python control plane)
- Data Layer: PostgreSQL (ledger, artifact IR, audit logs)
- Event Bus: Message queue (e.g., RabbitMQ or Kafka) for event streaming
- Build System: Cargo (Rust), Poetry/uv (Python)
- Testing: pytest, criterion (Rust benchmarks), property-based tests
- CI/CD: GitHub Actions, deterministic build caching

Module Breakdown:

#### TRACK-A: Artifact Compiler & Determinism ​

- Responsibility: IR schema definitions, deterministic build contracts, provenance signing
- Key Files: `src/artifact/ir.rs`, `src/artifact/compiler.rs`, `src/artifact/cache.rs`
- Specs: `TRACK_A_ARTIFACT_DETERMINISM_SPEC.md`, `SCHEMA_PACK.md`
- Ownership: Venture Artifact Team (2-3 engineers)

#### TRACK-B: Treasury & Compliance ​

- Responsibility: Money authorization, double-entry ledger, reconciliation, audit trails
- Key Files: `src/treasury/authorization.rs`, `src/treasury/ledger.rs`, `src/treasury/reconcile.rs`
- Specs: `TRACK_B_TREASURY_COMPLIANCE_SPEC.md`, `DATA_MODEL_DB_SPEC.md`
- Ownership: Venture Treasury Team (2-3 engineers)

#### TRACK-C: Control Plane ​

- Responsibility: Workflow orchestration, FSM, event bus, tool allowlist, workspace isolation
- Key Files: `src/orchestration/workflow.rs`, `src/orchestration/fsm.rs`, `src/orchestration/event_bus.rs`, `src/orchestration/tools.rs`
- Specs: `TRACK_C_CONTROL_PLANE.md`, `API_EVENTS_SPEC.md`
- Ownership: Venture Platform Team (3-4 engineers)

#### Supporting Systems ​

- User Management: `src/users/roles.rs`, `src/users/onboarding.rs`
- Operations & Compliance: `src/ops/compliance_machine.rs`, `src/ops/audit_trail.rs`
- Data Model: `schema/` directory with Prisma/SQLAlchemy ORM definitions

Governance Files:

- `CLAUDE.md` - Venture project instructions (spec-first, integration points, delegation patterns)
- `docs/governance/` - Quality gates, traceability checks, incident doctrine
- `docs/adr/` - Architecture decision records (e.g., "Why Rust for control plane?")

Ownership: Venture Autonomy Platform Team (primary owner of TRACK-A, TRACK-B, TRACK-C implementation)

### 3. CIV (City Simulation Engine) ​

Location: `/Users/kooshapari/temp-PRODVERCEL/485/kush/civ/`

Primary Purpose: Deterministic city simulation system generating economy, energy, institutional, and citizen lifecycle events.

Primary Language(s):

- Rust (all modules; determinism requirement)

Tech Stack:

- Simulation Core: Custom tick-based engine (no external sim framework)
- Data Layer: SQLite (local simulation state), PostgreSQL (event export)
- Build System: Cargo
- Testing: criterion (benchmarks), property-based tests, determinism verification harness
- Visualization: Optional (separate from core sim)

Module Breakdown (Rust crates):

- crates/engine - Core simulation loop (CIV-0001)
- crates/economy - Ledger, market clearing, transfers (CIV-0100)
- crates/spatial - Two-zoom LOD system (CIV-0101)
- crates/energy - Energy accounting and balance (CIV-0102)
- crates/demographics - Citizen lifecycle and metrics (CIV-0103)
- crates/institutions - Institutional state machines (CIV-0103)
- crates/policy - Policy evaluation and application (CIV-0100, all modules)
- crates/geopolitics - War, diplomacy, shadow networks (CIV-0105)
- crates/social - Health, ideology, insurgency (CIV-0106)
- crates/energy_economy - Joule-backed economy integration (CIV-0107)

Spec Files (all in `docs/specs/`):

- `CIV-0001-core-simulation-loop.md` - Tick sequencing, deterministic order
- `CIV-0100-economy-v1.md` - Double-entry ledger, market clearing, conservation
- `CIV-0101-two-zoom-lod-v1.md` - Spatial representation
- `CIV-0102-climate-followup-v1.md` - Energy accounting, supply-demand
- `CIV-0103-institutions-timeseries-citizen-lifecycle-v1.md` - Actor models, institutional change
- `CIV-0104-minimal-constraint-set-theorem.md` - Mathematical foundations
- `CIV-0105-war-diplomacy-shadow-v1.md` - Geopolitical dynamics
- `CIV-0106-social-ideology-health-insurgency-v1.md` - Citizen agency, conflict
- `CIV-0107-joule-economy-system-v1.md` - Energy-backed economy

Governance Files:

- `docs/GOVERNANCE_BASELINE_FROM_KUSH_PROJECTS.md` - Reusable governance practices
- `docs/traceability/TRACEABILITY_MATRIX.md` - CIV spec → code mapping
- `docs/upstream-governance/thegent/CLAUDE.md` - Global governance context (read-only reference)

Ownership: CIV Simulation Team (primary owner of all CIV specs and implementation)

## 5 Cross-Track Integration Points ​

All integration points documented formally in `docs/traceability/CROSS_PROJECT_TRACEABILITY.md`:

# | Name | CIV Spec | Venture Track | Status
--- | --- | --- | --- | ---
1 | Economy Ledger | CIV-0100 | TRACK-B (Treasury) | Spec Complete; P0 implementation
2 | Simulation State & Workflow | CIV-0001, CIV-0100 | TRACK-C (Control Plane) | Spec Complete; P0 implementation
3 | Institutions & Compliance | CIV-0103 | OPS_COMPLIANCE_SPEC | Spec Complete; P1 implementation
4 | Energy Accounting & Cost Control | CIV-0102, CIV-0100 | TRACK-B, TRACK-C | Spec Complete; P1 implementation
5 | Determinism & Constraints | CIV-0104 | TRACK-A (Artifacts) | Spec Complete; P0 implementation

## Data Flow Architecture ​

### Flow 1: CIV Simulation Tick → Venture Event Bus → Ledger ​

    CIV Tick T
      ├─→ Policy evaluated
      ├─→ Market cleared
      ├─→ economy.transfer_booked.v1 emitted (multiple)
      └─→ energy.consumed.v1 emitted (multiple)
           ↓
    Event Relay Layer (TRACK-C)
      └─→ Wrap in EventEnvelopeV1
           ↓
    Venture Event Bus
      ├─→ Subscribe: Ledger Engine
      │    └─→ Double-entry transaction
      │        └─→ ledger.entry.created.v1
      └─→ Subscribe: Compliance Engine
           └─→ Audit case evidence chain

### Flow 2: Artifact Compilation in Venture ​

    Artifact IR Created (TimelineSpec, DocSpec, etc.)
      ├─→ artifact.ir_created.v1 emitted
      └─→ Artifact Build Pipeline
           ├─→ Deterministic cache lookup (idempotency key)
           ├─→ If cache miss:
           │    ├─→ Determine cost estimate
           │    ├─→ Request money intent from TRACK-B
           │    ├─→ Build artifact (with toolchain pinning)
           │    └─→ Compute content hash
           └─→ artifact.provenance_attested.v1 (signed)
                └─→ artifact.build_completed.v1

### Flow 3: Budget Enforcement in Venture ​

    Task Execution in Workflow
      ├─→ Each tool call costs EAU (from TRACK-C allowlist)
      ├─→ Deduct from workspace quota (TRACK-C isolation)
      ├─→ If quota exceeded:
      │    ├─→ Emit budget.exceeded.v1
      │    ├─→ Query TRACK-B spend ledger
      │    └─→ Trigger remediation or escalation
      └─→ At workflow end: reconcile actual vs. budgeted
           └─→ reconciliation.run.v1

## Governance Layer ​

Applied uniformly across parpour, venture, and civ:

### Critical Governance Rules ​

1. Library-First Philosophy (Global CLAUDE.md)

   - No custom retry logic → use `tenacity`
   - No custom HTTP clients → use `httpx`
   - No custom logging → use `structlog`
   - No custom file watching → use `watchdog`

2. Spec-First Workflow (Project-local CLAUDE.md)

   - Every feature starts as a spec PR
   - Every spec includes invariants, interfaces, acceptance criteria
   - Every implementation references spec IDs

3. Deterministic Quality Gates (Enforced by CI/CD)

   - Linting (ruff, clippy)
   - Type checking (mypy, rustc)
   - Unit tests (pytest, cargo test)
   - Integration tests (determinism verification)
   - No new suppressions without inline justification

4. Proactive Governance Evolution (Lifecycle rule)

   - When work touches a governed domain, update governance docs
   - Examples: retry policy, cache policy, HTTP client choice
   - See: `docs/reference/PROACTIVE_GOVERNANCE_EVOLUTION_PLAN.md`

5. Workstream Tracking (Active ledger in `docs/reference/WORK_STREAM.md`)

   - All tasks claimed before starting
   - Status updated as work progresses
   - Completed tasks marked with delivery date

## Key Contact Matrix (Agent Roles) ​

Parpour (Coordination)

- Spec Architect: Reviews integration points, resolves cross-track conflicts
- Integration Manager: Coordinates CIV and Venture team sync points

Venture (Implementation)

- Platform Lead: Owns TRACK-C (control plane, orchestration, event bus)
- Treasury Lead: Owns TRACK-B (ledger, authorization, reconciliation)
- Artifact Lead: Owns TRACK-A (IR family, deterministic build, provenance)
- Compliance Officer: Owns OPS_COMPLIANCE_SPEC, audit machinery, incident doctrine

CIV (Implementation)

- Simulation Lead: Owns CIV-0001 (core loop, determinism)
- Economy Lead: Owns CIV-0100, CIV-0107 (ledger, Joule economy)
- Institution Lead: Owns CIV-0103 (institutions, citizen lifecycle)
- Energy Lead: Owns CIV-0102 (energy accounting)

Cross-Track Integration

- CIV-Venture Integration PM: Coordinates all 5 integration points, resolves blockers

## Documentation Navigation ​

### For Spec Readers ​

1. Start with `SPECS_INDEX.md` (master index of 20 artifacts)
2. Read domain-specific spec (e.g., `TRACK_B_TREASURY_COMPLIANCE_SPEC.md`)
3. Check cross-track dependencies in `CROSS_PROJECT_TRACEABILITY.md`
4. Review event schemas in `EVENT_TAXONOMY.md`

### For Implementation Teams ​

1. Read project-local `CLAUDE.md` (e.g., `venture/CLAUDE.md`)
2. Identify your domain spec(s) from Quick Navigation table
3. Check `NEXT_STEPS.md` for implementation priorities and owner assignments
4. Refer to `IMPLEMENTATION_ROADMAP.md` for phased rollout plan

### For Compliance & Audit ​

1. Read `OPS_COMPLIANCE_SPEC.md` (audit machinery, incident doctrine)
2. Check `CROSS_PROJECT_TRACEABILITY.md` for audit trail requirements
3. Review `docs/governance/` for policy bundles and quality gates
4. Refer to `docs/traceability/` for evidence chain procedures

## File Location Quick Reference ​

Artifact Type | Location | Example
--- | --- | ---
Master spec index | `parpour/SPECS_INDEX.md` | All 20 specs indexed
Venture spec | `parpour/venture/` | `TRACK_B_TREASURY_COMPLIANCE_SPEC.md`
CIV spec | `civ/docs/specs/` | `CIV-0100-economy-v1.md`
Cross-track traceability | `parpour/docs/traceability/` | `CROSS_PROJECT_TRACEABILITY.md`
Event taxonomy | `parpour/docs/traceability/EVENT_TAXONOMY.md` | All 58 event types
Governance baseline | `civ/docs/GOVERNANCE_BASELINE_FROM_KUSH_PROJECTS.md` | Reusable practices
Implementation roadmap | `parpour/venture/IMPLEMENTATION_ROADMAP.md` | P0/P1/P2 phased plan
Conversation dumps | `parpour/docs/research/` | `CONVERSATION_DUMP_2026-02-21.md`
Architecture decisions | `parpour/docs/adr/` | `ADR-NNN-decision-name.md`

## Summary ​

The Kush ecosystem comprises three interconnected projects:

1. Parpour (planning workspace): Central spec repository and cross-project coordination
2. Venture (agent platform): Production-ready autonomy control plane with 3 major tracks
3. CIV (city sim): Deterministic simulation engine with 8 integrated spec domains

All projects follow unified governance (spec-first, determinism, library-first, proactive governance evolution). All integration points are formally documented with interface contracts, event flows, and implementation timelines.

Current Status: All 20 spec artifacts closed; zero planning gaps. P0 foundation implementation begins Week 1; P1 integration Week 2; P2 polish Week 3+.

Document Control

Version | Date | Author | Change
--- | --- | --- | ---
1.0 | 2026-02-21 | Kush Integration Team | Initial version; ecosystem map with 3 projects, 8 CIV domains, 3 Venture tracks, 5 integration points