import{_ as e,o as a,c as s,ag as t}from"./chunks/framework.CmQHR1bQ.js";const u=JSON.parse('{"title":"Kush Ecosystem Map","description":"","frontmatter":{},"headers":[],"relativePath":"reference/ECOSYSTEM_MAP.md","filePath":"reference/ECOSYSTEM_MAP.md"}'),i={name:"reference/ECOSYSTEM_MAP.md"};function o(r,n,l,c,p,d){return a(),s("div",null,[...n[0]||(n[0]=[t(`<h1 id="kush-ecosystem-map" tabindex="-1">Kush Ecosystem Map <a class="header-anchor" href="#kush-ecosystem-map" aria-label="Permalink to &quot;Kush Ecosystem Map&quot;">​</a></h1><p><strong>Date:</strong> 2026-02-21 <strong>Scope:</strong> Full system architecture and cross-project relationships <strong>Status:</strong> ACTIVE <strong>Owner:</strong> Kush Ecosystem Integration Team</p><hr><h2 id="system-architecture-overview" tabindex="-1">System Architecture Overview <a class="header-anchor" href="#system-architecture-overview" aria-label="Permalink to &quot;System Architecture Overview&quot;">​</a></h2><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>┌─────────────────────────────────────────────────────────────────────────┐</span></span>
<span class="line"><span>│                         KUSH ECOSYSTEM (2026)                            │</span></span>
<span class="line"><span>├─────────────────────────────────────────────────────────────────────────┤</span></span>
<span class="line"><span>│                                                                          │</span></span>
<span class="line"><span>│  PARPOUR (Planning &amp; Specification Workspace)                          │</span></span>
<span class="line"><span>│  └─ Version control for specs, integration contracts, governance       │</span></span>
<span class="line"><span>│                                                                          │</span></span>
<span class="line"><span>│     ├─ VENTURE (Autonomous Agent Platform)                            │</span></span>
<span class="line"><span>│     │  │ Primary Language: Rust/TypeScript (control plane)             │</span></span>
<span class="line"><span>│     │  │ Primary Language: Python (agentic workflows)                  │</span></span>
<span class="line"><span>│     │  │ Stack: FastAPI, PostgreSQL, async task queue                │</span></span>
<span class="line"><span>│     │  │                                                                │</span></span>
<span class="line"><span>│     │  ├─ TRACK-A: Artifact Compiler (IR family, deterministic build) │</span></span>
<span class="line"><span>│     │  │  ├─ SlideSpec, DocSpec, TimelineSpec, AudioSpec, BoardSpec   │</span></span>
<span class="line"><span>│     │  │  └─ Deterministic build contract with provenance chain       │</span></span>
<span class="line"><span>│     │  │                                                                │</span></span>
<span class="line"><span>│     │  ├─ TRACK-B: Treasury &amp; Compliance (money control, ledger)      │</span></span>
<span class="line"><span>│     │  │  ├─ Double-entry accounting (ledger_entries table)           │</span></span>
<span class="line"><span>│     │  │  ├─ Spend authorization and policy attestation               │</span></span>
<span class="line"><span>│     │  │  └─ Daily reconciliation and drift detection                 │</span></span>
<span class="line"><span>│     │  │                                                                │</span></span>
<span class="line"><span>│     │  ├─ TRACK-C: Control Plane (orchestration, FSM, tools)         │</span></span>
<span class="line"><span>│     │  │  ├─ Workflow DAG execution engine                            │</span></span>
<span class="line"><span>│     │  │  ├─ Event bus with strict validation                         │</span></span>
<span class="line"><span>│     │  │  ├─ Tool allowlist and per-role capability model            │</span></span>
<span class="line"><span>│     │  │  └─ Workspace isolation boundaries                           │</span></span>
<span class="line"><span>│     │  │                                                                │</span></span>
<span class="line"><span>│     │  └─ Supporting Systems:                                          │</span></span>
<span class="line"><span>│     │     ├─ User Management (roles, onboarding, multi-tenant)        │</span></span>
<span class="line"><span>│     │     ├─ Operations &amp; Compliance (audit trails, incident doctrine)│</span></span>
<span class="line"><span>│     │     └─ Data Model (artifact IR, ledger, workflow tables)        │</span></span>
<span class="line"><span>│     │                                                                    │</span></span>
<span class="line"><span>│     └─────────── (5 Integration Points) ─────────────────────────────┬─│</span></span>
<span class="line"><span>│                                                                        │ │</span></span>
<span class="line"><span>│     ├─ CIV (City Simulation Engine)                                  │ │</span></span>
<span class="line"><span>│     │  │ Primary Language: Rust (all modules)                         │ │</span></span>
<span class="line"><span>│     │  │ Stack: Deterministic tick engine, concurrent simulation     │ │</span></span>
<span class="line"><span>│     │  │                                                              │ │</span></span>
<span class="line"><span>│     │  ├─ CIV-0001: Core Simulation Loop                            │ │</span></span>
<span class="line"><span>│     │  │  └─ Tick-based state machine with deterministic ordering   │ │</span></span>
<span class="line"><span>│     │  │                                                              │ │</span></span>
<span class="line"><span>│     │  ├─ CIV-0100: Economy v1 (Joule-backed)                      │ │</span></span>
<span class="line"><span>│     │  │  ├─ Double-entry ledger (ledger_transfers)                 │ │</span></span>
<span class="line"><span>│     │  │  ├─ Market clearing and price discovery                    │ │</span></span>
<span class="line"><span>│     │  │  └─ Conservation invariants                                │ │</span></span>
<span class="line"><span>│     │  │                                                              │ │</span></span>
<span class="line"><span>│     │  ├─ CIV-0101: Two-Zoom LOD (spatial representation)           │ │</span></span>
<span class="line"><span>│     │  │  ├─ Tile-based world at regional zoom                      │ │</span></span>
<span class="line"><span>│     │  │  └─ Detailed LOD at city zoom                              │ │</span></span>
<span class="line"><span>│     │  │                                                              │ │</span></span>
<span class="line"><span>│     │  ├─ CIV-0102: Energy Accounting (Joule conservation)          │ │</span></span>
<span class="line"><span>│     │  │  ├─ Supply/demand balance tracking                         │ │</span></span>
<span class="line"><span>│     │  │  ├─ Renewable variability and storage dynamics             │ │</span></span>
<span class="line"><span>│     │  │  └─ Peak-shaving and demand-response mechanics             │ │</span></span>
<span class="line"><span>│     │  │                                                              │ │</span></span>
<span class="line"><span>│     │  ├─ CIV-0103: Institutions &amp; Citizen Lifecycle                │ │</span></span>
<span class="line"><span>│     │  │  ├─ Citizen birth/education/career/retirement/death        │ │</span></span>
<span class="line"><span>│     │  │  ├─ Institutional state machine (pending→active→dissolved)  │ │</span></span>
<span class="line"><span>│     │  │  └─ Time-series metrics (age, wealth, satisfaction)        │ │</span></span>
<span class="line"><span>│     │  │                                                              │ │</span></span>
<span class="line"><span>│     │  ├─ CIV-0104: Minimal Constraint Set Theorem                  │ │</span></span>
<span class="line"><span>│     │  │  └─ Mathematical foundation for determinism                │ │</span></span>
<span class="line"><span>│     │  │                                                              │ │</span></span>
<span class="line"><span>│     │  ├─ CIV-0105: War, Diplomacy &amp; Shadow Networks                │ │</span></span>
<span class="line"><span>│     │  │  ├─ Geopolitical dynamics and territorial control          │ │</span></span>
<span class="line"><span>│     │  │  └─ Shadow networks for covert influence                   │ │</span></span>
<span class="line"><span>│     │  │                                                              │ │</span></span>
<span class="line"><span>│     │  ├─ CIV-0106: Social, Ideology, Health &amp; Insurgency           │ │</span></span>
<span class="line"><span>│     │  │  ├─ Health crises and epidemiology                         │ │</span></span>
<span class="line"><span>│     │  │  ├─ Ideological shifts and cultural events                 │ │</span></span>
<span class="line"><span>│     │  │  └─ Citizen agency and insurgency mechanics                │ │</span></span>
<span class="line"><span>│     │  │                                                              │ │</span></span>
<span class="line"><span>│     │  └─ CIV-0107: Joule Economy System v1                         │ │</span></span>
<span class="line"><span>│     │     ├─ Energy-backed currency and accounting                  │ │</span></span>
<span class="line"><span>│     │     └─ Production cost basis tied to energy consumption       │ │</span></span>
<span class="line"><span>│     │                                                                  │</span></span>
<span class="line"><span>│     └─────────────────────────────────────────────────────────────────┘</span></span>
<span class="line"><span>│</span></span>
<span class="line"><span>│  GOVERNANCE LAYER (Applied to all projects)</span></span>
<span class="line"><span>│  ├─ Global CLAUDE.md (critical security rules, proactive governance, QA)</span></span>
<span class="line"><span>│  ├─ Project-local CLAUDE.md (domain-specific overrides and patterns)</span></span>
<span class="line"><span>│  ├─ Spec-first workflow (proposal → design → tasks → implementation)</span></span>
<span class="line"><span>│  ├─ Deterministic quality gates (lint, type-check, unit/integration tests)</span></span>
<span class="line"><span>│  ├─ Workstream tracking and sub-agent delegation</span></span>
<span class="line"><span>│  └─ Library-first philosophy (no reinvention of generic problems)</span></span>
<span class="line"><span>│</span></span>
<span class="line"><span>└─────────────────────────────────────────────────────────────────────────┘</span></span></code></pre></div><hr><h2 id="project-inventory" tabindex="-1">Project Inventory <a class="header-anchor" href="#project-inventory" aria-label="Permalink to &quot;Project Inventory&quot;">​</a></h2><h3 id="_1-parpour-specification-planning-workspace" tabindex="-1">1. PARPOUR (Specification &amp; Planning Workspace) <a class="header-anchor" href="#_1-parpour-specification-planning-workspace" aria-label="Permalink to &quot;1. PARPOUR (Specification &amp; Planning Workspace)&quot;">​</a></h3><p><strong>Location</strong>: <code>/Users/kooshapari/temp-PRODVERCEL/485/kush/parpour/</code></p><p><strong>Primary Purpose</strong>: Central repository for all specification artifacts, cross-project integration contracts, and governance documents for the Kush ecosystem.</p><p><strong>Primary Language(s)</strong>: Markdown (specifications), YAML (configs)</p><p><strong>Key Governance Files</strong>:</p><ul><li><code>CLAUDE.md</code> - Project-local instructions (spec-first workflow, delegation patterns, quality gates)</li><li><code>SPECS_INDEX.md</code> - Master index of all 20 spec artifacts and 5 cross-track integration points</li><li><code>NEXT_STEPS.md</code> - Implementation priorities (P0/P1/P2 phased roadmap)</li></ul><p><strong>Spec Files</strong> (Venture track, all in <code>venture/</code> directory):</p><ul><li><code>TECHNICAL_SPEC.md</code> - Control-plane architecture, runtime model, security posture</li><li><code>TRACK_A_ARTIFACT_DETERMINISM_SPEC.md</code> - Artifact IR family, deterministic build/replay</li><li><code>TRACK_B_TREASURY_COMPLIANCE_SPEC.md</code> - Money control, double-entry ledger, reconciliation</li><li><code>TRACK_C_CONTROL_PLANE.md</code> - Orchestration, FSM, tool allowlist, incident doctrine</li><li><code>API_EVENTS_SPEC.md</code> - Event envelope schema, FSM transitions, strict validation</li><li><code>DATA_MODEL_DB_SPEC.md</code> - Artifact IR, ledger, workflow, and audit log schemas</li><li><code>OPS_COMPLIANCE_SPEC.md</code> - Compliance machine, audit toolchain, incident playbooks</li><li><code>USER_SPEC.md</code> - User roles, capabilities, onboarding, multi-tenant isolation</li><li><code>PRODUCT_MODEL.md</code> - Vision, users, jobs to be done, success metrics</li><li><code>SCHEMA_PACK.md</code> - Consolidated schema definitions (artifact, ledger, workflow, event)</li><li><code>ROLE_TOOL_ALLOWLIST_MATRIX.md</code> - Per-role capability model and tool allowlists</li><li><code>IMPLEMENTATION_ROADMAP.md</code> - Phased rollout plan (Sandbox → Limited Autopilot → Governed Autonomy)</li></ul><p><strong>Documentation Structure</strong>:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>parpour/</span></span>
<span class="line"><span>  ├─ CLAUDE.md (project instructions)</span></span>
<span class="line"><span>  ├─ SPECS_INDEX.md (master spec index)</span></span>
<span class="line"><span>  ├─ NEXT_STEPS.md (implementation priorities)</span></span>
<span class="line"><span>  ├─ venture/ (all Venture specs)</span></span>
<span class="line"><span>  │   ├─ TECHNICAL_SPEC.md</span></span>
<span class="line"><span>  │   ├─ TRACK_A_ARTIFACT_DETERMINISM_SPEC.md</span></span>
<span class="line"><span>  │   ├─ TRACK_B_TREASURY_COMPLIANCE_SPEC.md</span></span>
<span class="line"><span>  │   ├─ TRACK_C_CONTROL_PLANE.md</span></span>
<span class="line"><span>  │   └─ ... (9 more spec files)</span></span>
<span class="line"><span>  └─ docs/</span></span>
<span class="line"><span>      ├─ governance/ (governance docs)</span></span>
<span class="line"><span>      ├─ reference/ (quick references, this file)</span></span>
<span class="line"><span>      ├─ research/ (conversation dumps, analysis)</span></span>
<span class="line"><span>      ├─ adr/ (architecture decision records)</span></span>
<span class="line"><span>      ├─ guides/ (implementation guides)</span></span>
<span class="line"><span>      └─ traceability/</span></span>
<span class="line"><span>          ├─ CROSS_PROJECT_TRACEABILITY.md (formal integration matrix)</span></span>
<span class="line"><span>          └─ EVENT_TAXONOMY.md (unified event catalog)</span></span></code></pre></div><p><strong>Ownership</strong>: Kush Ecosystem Integration Team (coordination role; defers implementation to CIV and Venture teams)</p><hr><h3 id="_2-venture-autonomous-agent-platform" tabindex="-1">2. VENTURE (Autonomous Agent Platform) <a class="header-anchor" href="#_2-venture-autonomous-agent-platform" aria-label="Permalink to &quot;2. VENTURE (Autonomous Agent Platform)&quot;">​</a></h3><p><strong>Location</strong>: <code>/Users/kooshapari/temp-PRODVERCEL/485/kush/venture/</code> (planned)</p><p><strong>Primary Purpose</strong>: Production-ready autonomous agent control plane with artifact compiler, treasury system, and compliance machinery.</p><p><strong>Primary Language(s)</strong>:</p><ul><li><strong>Rust</strong> (control-plane core, performance-critical paths)</li><li><strong>Python</strong> (agentic workflows, policy evaluation, tool implementations)</li><li><strong>TypeScript</strong> (frontend, artifact schemas)</li></ul><p><strong>Tech Stack</strong>:</p><ul><li><strong>Orchestration</strong>: FastAPI + async/await (Python control plane)</li><li><strong>Data Layer</strong>: PostgreSQL (ledger, artifact IR, audit logs)</li><li><strong>Event Bus</strong>: Message queue (e.g., RabbitMQ or Kafka) for event streaming</li><li><strong>Build System</strong>: Cargo (Rust), Poetry/uv (Python)</li><li><strong>Testing</strong>: pytest, criterion (Rust benchmarks), property-based tests</li><li><strong>CI/CD</strong>: GitHub Actions, deterministic build caching</li></ul><p><strong>Module Breakdown</strong>:</p><h4 id="track-a-artifact-compiler-determinism" tabindex="-1">TRACK-A: Artifact Compiler &amp; Determinism <a class="header-anchor" href="#track-a-artifact-compiler-determinism" aria-label="Permalink to &quot;TRACK-A: Artifact Compiler &amp; Determinism&quot;">​</a></h4><ul><li><strong>Responsibility</strong>: IR schema definitions, deterministic build contracts, provenance signing</li><li><strong>Key Files</strong>: <code>src/artifact/ir.rs</code>, <code>src/artifact/compiler.rs</code>, <code>src/artifact/cache.rs</code></li><li><strong>Specs</strong>: <code>TRACK_A_ARTIFACT_DETERMINISM_SPEC.md</code>, <code>SCHEMA_PACK.md</code></li><li><strong>Ownership</strong>: Venture Artifact Team (2-3 engineers)</li></ul><h4 id="track-b-treasury-compliance" tabindex="-1">TRACK-B: Treasury &amp; Compliance <a class="header-anchor" href="#track-b-treasury-compliance" aria-label="Permalink to &quot;TRACK-B: Treasury &amp; Compliance&quot;">​</a></h4><ul><li><strong>Responsibility</strong>: Money authorization, double-entry ledger, reconciliation, audit trails</li><li><strong>Key Files</strong>: <code>src/treasury/authorization.rs</code>, <code>src/treasury/ledger.rs</code>, <code>src/treasury/reconcile.rs</code></li><li><strong>Specs</strong>: <code>TRACK_B_TREASURY_COMPLIANCE_SPEC.md</code>, <code>DATA_MODEL_DB_SPEC.md</code></li><li><strong>Ownership</strong>: Venture Treasury Team (2-3 engineers)</li></ul><h4 id="track-c-control-plane" tabindex="-1">TRACK-C: Control Plane <a class="header-anchor" href="#track-c-control-plane" aria-label="Permalink to &quot;TRACK-C: Control Plane&quot;">​</a></h4><ul><li><strong>Responsibility</strong>: Workflow orchestration, FSM, event bus, tool allowlist, workspace isolation</li><li><strong>Key Files</strong>: <code>src/orchestration/workflow.rs</code>, <code>src/orchestration/fsm.rs</code>, <code>src/orchestration/event_bus.rs</code>, <code>src/orchestration/tools.rs</code></li><li><strong>Specs</strong>: <code>TRACK_C_CONTROL_PLANE.md</code>, <code>API_EVENTS_SPEC.md</code></li><li><strong>Ownership</strong>: Venture Platform Team (3-4 engineers)</li></ul><h4 id="supporting-systems" tabindex="-1">Supporting Systems <a class="header-anchor" href="#supporting-systems" aria-label="Permalink to &quot;Supporting Systems&quot;">​</a></h4><ul><li><strong>User Management</strong>: <code>src/users/roles.rs</code>, <code>src/users/onboarding.rs</code></li><li><strong>Operations &amp; Compliance</strong>: <code>src/ops/compliance_machine.rs</code>, <code>src/ops/audit_trail.rs</code></li><li><strong>Data Model</strong>: <code>schema/</code> directory with Prisma/SQLAlchemy ORM definitions</li></ul><p><strong>Governance Files</strong>:</p><ul><li><code>CLAUDE.md</code> - Venture project instructions (spec-first, integration points, delegation patterns)</li><li><code>docs/governance/</code> - Quality gates, traceability checks, incident doctrine</li><li><code>docs/adr/</code> - Architecture decision records (e.g., &quot;Why Rust for control plane?&quot;)</li></ul><p><strong>Ownership</strong>: Venture Autonomy Platform Team (primary owner of TRACK-A, TRACK-B, TRACK-C implementation)</p><hr><h3 id="_3-civ-city-simulation-engine" tabindex="-1">3. CIV (City Simulation Engine) <a class="header-anchor" href="#_3-civ-city-simulation-engine" aria-label="Permalink to &quot;3. CIV (City Simulation Engine)&quot;">​</a></h3><p><strong>Location</strong>: <code>/Users/kooshapari/temp-PRODVERCEL/485/kush/civ/</code></p><p><strong>Primary Purpose</strong>: Deterministic city simulation system generating economy, energy, institutional, and citizen lifecycle events.</p><p><strong>Primary Language(s)</strong>:</p><ul><li><strong>Rust</strong> (all modules; determinism requirement)</li></ul><p><strong>Tech Stack</strong>:</p><ul><li><strong>Simulation Core</strong>: Custom tick-based engine (no external sim framework)</li><li><strong>Data Layer</strong>: SQLite (local simulation state), PostgreSQL (event export)</li><li><strong>Build System</strong>: Cargo</li><li><strong>Testing</strong>: criterion (benchmarks), property-based tests, determinism verification harness</li><li><strong>Visualization</strong>: Optional (separate from core sim)</li></ul><p><strong>Module Breakdown</strong> (Rust crates):</p><ul><li><strong>crates/engine</strong> - Core simulation loop (CIV-0001)</li><li><strong>crates/economy</strong> - Ledger, market clearing, transfers (CIV-0100)</li><li><strong>crates/spatial</strong> - Two-zoom LOD system (CIV-0101)</li><li><strong>crates/energy</strong> - Energy accounting and balance (CIV-0102)</li><li><strong>crates/demographics</strong> - Citizen lifecycle and metrics (CIV-0103)</li><li><strong>crates/institutions</strong> - Institutional state machines (CIV-0103)</li><li><strong>crates/policy</strong> - Policy evaluation and application (CIV-0100, all modules)</li><li><strong>crates/geopolitics</strong> - War, diplomacy, shadow networks (CIV-0105)</li><li><strong>crates/social</strong> - Health, ideology, insurgency (CIV-0106)</li><li><strong>crates/energy_economy</strong> - Joule-backed economy integration (CIV-0107)</li></ul><p><strong>Spec Files</strong> (all in <code>docs/specs/</code>):</p><ul><li><code>CIV-0001-core-simulation-loop.md</code> - Tick sequencing, deterministic order</li><li><code>CIV-0100-economy-v1.md</code> - Double-entry ledger, market clearing, conservation</li><li><code>CIV-0101-two-zoom-lod-v1.md</code> - Spatial representation</li><li><code>CIV-0102-climate-followup-v1.md</code> - Energy accounting, supply-demand</li><li><code>CIV-0103-institutions-timeseries-citizen-lifecycle-v1.md</code> - Actor models, institutional change</li><li><code>CIV-0104-minimal-constraint-set-theorem.md</code> - Mathematical foundations</li><li><code>CIV-0105-war-diplomacy-shadow-v1.md</code> - Geopolitical dynamics</li><li><code>CIV-0106-social-ideology-health-insurgency-v1.md</code> - Citizen agency, conflict</li><li><code>CIV-0107-joule-economy-system-v1.md</code> - Energy-backed economy</li></ul><p><strong>Governance Files</strong>:</p><ul><li><code>docs/GOVERNANCE_BASELINE_FROM_KUSH_PROJECTS.md</code> - Reusable governance practices</li><li><code>docs/traceability/TRACEABILITY_MATRIX.md</code> - CIV spec → code mapping</li><li><code>docs/upstream-governance/thegent/CLAUDE.md</code> - Global governance context (read-only reference)</li></ul><p><strong>Ownership</strong>: CIV Simulation Team (primary owner of all CIV specs and implementation)</p><hr><h2 id="_5-cross-track-integration-points" tabindex="-1">5 Cross-Track Integration Points <a class="header-anchor" href="#_5-cross-track-integration-points" aria-label="Permalink to &quot;5 Cross-Track Integration Points&quot;">​</a></h2><p>All integration points documented formally in <code>docs/traceability/CROSS_PROJECT_TRACEABILITY.md</code>:</p><table tabindex="0"><thead><tr><th>#</th><th>Name</th><th>CIV Spec</th><th>Venture Track</th><th>Status</th></tr></thead><tbody><tr><td>1</td><td><strong>Economy Ledger</strong></td><td>CIV-0100</td><td>TRACK-B (Treasury)</td><td>Spec Complete; P0 implementation</td></tr><tr><td>2</td><td><strong>Simulation State &amp; Workflow</strong></td><td>CIV-0001, CIV-0100</td><td>TRACK-C (Control Plane)</td><td>Spec Complete; P0 implementation</td></tr><tr><td>3</td><td><strong>Institutions &amp; Compliance</strong></td><td>CIV-0103</td><td>OPS_COMPLIANCE_SPEC</td><td>Spec Complete; P1 implementation</td></tr><tr><td>4</td><td><strong>Energy Accounting &amp; Cost Control</strong></td><td>CIV-0102, CIV-0100</td><td>TRACK-B, TRACK-C</td><td>Spec Complete; P1 implementation</td></tr><tr><td>5</td><td><strong>Determinism &amp; Constraints</strong></td><td>CIV-0104</td><td>TRACK-A (Artifacts)</td><td>Spec Complete; P0 implementation</td></tr></tbody></table><hr><h2 id="data-flow-architecture" tabindex="-1">Data Flow Architecture <a class="header-anchor" href="#data-flow-architecture" aria-label="Permalink to &quot;Data Flow Architecture&quot;">​</a></h2><h3 id="flow-1-civ-simulation-tick-→-venture-event-bus-→-ledger" tabindex="-1">Flow 1: CIV Simulation Tick → Venture Event Bus → Ledger <a class="header-anchor" href="#flow-1-civ-simulation-tick-→-venture-event-bus-→-ledger" aria-label="Permalink to &quot;Flow 1: CIV Simulation Tick → Venture Event Bus → Ledger&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>CIV Tick T</span></span>
<span class="line"><span>  ├─→ Policy evaluated</span></span>
<span class="line"><span>  ├─→ Market cleared</span></span>
<span class="line"><span>  ├─→ economy.transfer_booked.v1 emitted (multiple)</span></span>
<span class="line"><span>  └─→ energy.consumed.v1 emitted (multiple)</span></span>
<span class="line"><span>       ↓</span></span>
<span class="line"><span>Event Relay Layer (TRACK-C)</span></span>
<span class="line"><span>  └─→ Wrap in EventEnvelopeV1</span></span>
<span class="line"><span>       ↓</span></span>
<span class="line"><span>Venture Event Bus</span></span>
<span class="line"><span>  ├─→ Subscribe: Ledger Engine</span></span>
<span class="line"><span>  │    └─→ Double-entry transaction</span></span>
<span class="line"><span>  │        └─→ ledger.entry.created.v1</span></span>
<span class="line"><span>  └─→ Subscribe: Compliance Engine</span></span>
<span class="line"><span>       └─→ Audit case evidence chain</span></span></code></pre></div><h3 id="flow-2-artifact-compilation-in-venture" tabindex="-1">Flow 2: Artifact Compilation in Venture <a class="header-anchor" href="#flow-2-artifact-compilation-in-venture" aria-label="Permalink to &quot;Flow 2: Artifact Compilation in Venture&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Artifact IR Created (TimelineSpec, DocSpec, etc.)</span></span>
<span class="line"><span>  ├─→ artifact.ir_created.v1 emitted</span></span>
<span class="line"><span>  └─→ Artifact Build Pipeline</span></span>
<span class="line"><span>       ├─→ Deterministic cache lookup (idempotency key)</span></span>
<span class="line"><span>       ├─→ If cache miss:</span></span>
<span class="line"><span>       │    ├─→ Determine cost estimate</span></span>
<span class="line"><span>       │    ├─→ Request money intent from TRACK-B</span></span>
<span class="line"><span>       │    ├─→ Build artifact (with toolchain pinning)</span></span>
<span class="line"><span>       │    └─→ Compute content hash</span></span>
<span class="line"><span>       └─→ artifact.provenance_attested.v1 (signed)</span></span>
<span class="line"><span>            └─→ artifact.build_completed.v1</span></span></code></pre></div><h3 id="flow-3-budget-enforcement-in-venture" tabindex="-1">Flow 3: Budget Enforcement in Venture <a class="header-anchor" href="#flow-3-budget-enforcement-in-venture" aria-label="Permalink to &quot;Flow 3: Budget Enforcement in Venture&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Task Execution in Workflow</span></span>
<span class="line"><span>  ├─→ Each tool call costs EAU (from TRACK-C allowlist)</span></span>
<span class="line"><span>  ├─→ Deduct from workspace quota (TRACK-C isolation)</span></span>
<span class="line"><span>  ├─→ If quota exceeded:</span></span>
<span class="line"><span>  │    ├─→ Emit budget.exceeded.v1</span></span>
<span class="line"><span>  │    ├─→ Query TRACK-B spend ledger</span></span>
<span class="line"><span>  │    └─→ Trigger remediation or escalation</span></span>
<span class="line"><span>  └─→ At workflow end: reconcile actual vs. budgeted</span></span>
<span class="line"><span>       └─→ reconciliation.run.v1</span></span></code></pre></div><hr><h2 id="governance-layer" tabindex="-1">Governance Layer <a class="header-anchor" href="#governance-layer" aria-label="Permalink to &quot;Governance Layer&quot;">​</a></h2><p>Applied uniformly across <strong>parpour</strong>, <strong>venture</strong>, and <strong>civ</strong>:</p><h3 id="critical-governance-rules" tabindex="-1">Critical Governance Rules <a class="header-anchor" href="#critical-governance-rules" aria-label="Permalink to &quot;Critical Governance Rules&quot;">​</a></h3><ol><li><p><strong>Library-First Philosophy</strong> (Global CLAUDE.md)</p><ul><li>No custom retry logic → use <code>tenacity</code></li><li>No custom HTTP clients → use <code>httpx</code></li><li>No custom logging → use <code>structlog</code></li><li>No custom file watching → use <code>watchdog</code></li></ul></li><li><p><strong>Spec-First Workflow</strong> (Project-local CLAUDE.md)</p><ul><li>Every feature starts as a spec PR</li><li>Every spec includes invariants, interfaces, acceptance criteria</li><li>Every implementation references spec IDs</li></ul></li><li><p><strong>Deterministic Quality Gates</strong> (Enforced by CI/CD)</p><ul><li>Linting (ruff, clippy)</li><li>Type checking (mypy, rustc)</li><li>Unit tests (pytest, cargo test)</li><li>Integration tests (determinism verification)</li><li>No new suppressions without inline justification</li></ul></li><li><p><strong>Proactive Governance Evolution</strong> (Lifecycle rule)</p><ul><li>When work touches a governed domain, update governance docs</li><li>Examples: retry policy, cache policy, HTTP client choice</li><li>See: <code>docs/reference/PROACTIVE_GOVERNANCE_EVOLUTION_PLAN.md</code></li></ul></li><li><p><strong>Workstream Tracking</strong> (Active ledger in <code>docs/reference/WORK_STREAM.md</code>)</p><ul><li>All tasks claimed before starting</li><li>Status updated as work progresses</li><li>Completed tasks marked with delivery date</li></ul></li></ol><hr><h2 id="key-contact-matrix-agent-roles" tabindex="-1">Key Contact Matrix (Agent Roles) <a class="header-anchor" href="#key-contact-matrix-agent-roles" aria-label="Permalink to &quot;Key Contact Matrix (Agent Roles)&quot;">​</a></h2><p><strong>Parpour (Coordination)</strong></p><ul><li><strong>Spec Architect</strong>: Reviews integration points, resolves cross-track conflicts</li><li><strong>Integration Manager</strong>: Coordinates CIV and Venture team sync points</li></ul><p><strong>Venture (Implementation)</strong></p><ul><li><strong>Platform Lead</strong>: Owns TRACK-C (control plane, orchestration, event bus)</li><li><strong>Treasury Lead</strong>: Owns TRACK-B (ledger, authorization, reconciliation)</li><li><strong>Artifact Lead</strong>: Owns TRACK-A (IR family, deterministic build, provenance)</li><li><strong>Compliance Officer</strong>: Owns OPS_COMPLIANCE_SPEC, audit machinery, incident doctrine</li></ul><p><strong>CIV (Implementation)</strong></p><ul><li><strong>Simulation Lead</strong>: Owns CIV-0001 (core loop, determinism)</li><li><strong>Economy Lead</strong>: Owns CIV-0100, CIV-0107 (ledger, Joule economy)</li><li><strong>Institution Lead</strong>: Owns CIV-0103 (institutions, citizen lifecycle)</li><li><strong>Energy Lead</strong>: Owns CIV-0102 (energy accounting)</li></ul><p><strong>Cross-Track Integration</strong></p><ul><li><strong>CIV-Venture Integration PM</strong>: Coordinates all 5 integration points, resolves blockers</li></ul><hr><h2 id="documentation-navigation" tabindex="-1">Documentation Navigation <a class="header-anchor" href="#documentation-navigation" aria-label="Permalink to &quot;Documentation Navigation&quot;">​</a></h2><h3 id="for-spec-readers" tabindex="-1">For Spec Readers <a class="header-anchor" href="#for-spec-readers" aria-label="Permalink to &quot;For Spec Readers&quot;">​</a></h3><ol><li>Start with <code>SPECS_INDEX.md</code> (master index of 20 artifacts)</li><li>Read domain-specific spec (e.g., <code>TRACK_B_TREASURY_COMPLIANCE_SPEC.md</code>)</li><li>Check cross-track dependencies in <code>CROSS_PROJECT_TRACEABILITY.md</code></li><li>Review event schemas in <code>EVENT_TAXONOMY.md</code></li></ol><h3 id="for-implementation-teams" tabindex="-1">For Implementation Teams <a class="header-anchor" href="#for-implementation-teams" aria-label="Permalink to &quot;For Implementation Teams&quot;">​</a></h3><ol><li>Read project-local <code>CLAUDE.md</code> (e.g., <code>venture/CLAUDE.md</code>)</li><li>Identify your domain spec(s) from Quick Navigation table</li><li>Check <code>NEXT_STEPS.md</code> for implementation priorities and owner assignments</li><li>Refer to <code>IMPLEMENTATION_ROADMAP.md</code> for phased rollout plan</li></ol><h3 id="for-compliance-audit" tabindex="-1">For Compliance &amp; Audit <a class="header-anchor" href="#for-compliance-audit" aria-label="Permalink to &quot;For Compliance &amp; Audit&quot;">​</a></h3><ol><li>Read <code>OPS_COMPLIANCE_SPEC.md</code> (audit machinery, incident doctrine)</li><li>Check <code>CROSS_PROJECT_TRACEABILITY.md</code> for audit trail requirements</li><li>Review <code>docs/governance/</code> for policy bundles and quality gates</li><li>Refer to <code>docs/traceability/</code> for evidence chain procedures</li></ol><hr><h2 id="file-location-quick-reference" tabindex="-1">File Location Quick Reference <a class="header-anchor" href="#file-location-quick-reference" aria-label="Permalink to &quot;File Location Quick Reference&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Artifact Type</th><th>Location</th><th>Example</th></tr></thead><tbody><tr><td>Master spec index</td><td><code>parpour/SPECS_INDEX.md</code></td><td>All 20 specs indexed</td></tr><tr><td>Venture spec</td><td><code>parpour/venture/</code></td><td><code>TRACK_B_TREASURY_COMPLIANCE_SPEC.md</code></td></tr><tr><td>CIV spec</td><td><code>civ/docs/specs/</code></td><td><code>CIV-0100-economy-v1.md</code></td></tr><tr><td>Cross-track traceability</td><td><code>parpour/docs/traceability/</code></td><td><code>CROSS_PROJECT_TRACEABILITY.md</code></td></tr><tr><td>Event taxonomy</td><td><code>parpour/docs/traceability/EVENT_TAXONOMY.md</code></td><td>All 58 event types</td></tr><tr><td>Governance baseline</td><td><code>civ/docs/GOVERNANCE_BASELINE_FROM_KUSH_PROJECTS.md</code></td><td>Reusable practices</td></tr><tr><td>Implementation roadmap</td><td><code>parpour/venture/IMPLEMENTATION_ROADMAP.md</code></td><td>P0/P1/P2 phased plan</td></tr><tr><td>Conversation dumps</td><td><code>parpour/docs/research/</code></td><td><code>CONVERSATION_DUMP_2026-02-21.md</code></td></tr><tr><td>Architecture decisions</td><td><code>parpour/docs/adr/</code></td><td><code>ADR-NNN-decision-name.md</code></td></tr></tbody></table><hr><h2 id="summary" tabindex="-1">Summary <a class="header-anchor" href="#summary" aria-label="Permalink to &quot;Summary&quot;">​</a></h2><p>The Kush ecosystem comprises three interconnected projects:</p><ol><li><strong>Parpour</strong> (planning workspace): Central spec repository and cross-project coordination</li><li><strong>Venture</strong> (agent platform): Production-ready autonomy control plane with 3 major tracks</li><li><strong>CIV</strong> (city sim): Deterministic simulation engine with 8 integrated spec domains</li></ol><p>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.</p><p><strong>Current Status</strong>: All 20 spec artifacts closed; zero planning gaps. P0 foundation implementation begins Week 1; P1 integration Week 2; P2 polish Week 3+.</p><hr><p><strong>Document Control</strong></p><table tabindex="0"><thead><tr><th>Version</th><th>Date</th><th>Author</th><th>Change</th></tr></thead><tbody><tr><td>1.0</td><td>2026-02-21</td><td>Kush Integration Team</td><td>Initial version; ecosystem map with 3 projects, 8 CIV domains, 3 Venture tracks, 5 integration points</td></tr></tbody></table>`,100)])])}const g=e(i,[["render",o]]);export{u as __pageData,g as default};
