coaia-visualizer 1.6.2 → 1.6.3

package/rispecs/narrative-beats-display.spec.md

@@ -1,189 +0,0 @@
-# Narrative Beats Display
-## RISE Specification for Narrative Beat Rendering and Multi-Universe Perspectives
-
-**Component Purpose**: Render the story layer of structural tension work — narrative beats that document creative acts, insights, and lessons across multiple archetypal universe perspectives.
-
-**Source Files**: `components/narrative-beats.tsx`
-
----
-
-## 🎯 What This Component Enables Users to Create
-
-- Visible narrative context for structural tension work
-- Story documentation across three archetypal universes (engineer-world, ceremony-world, story-engine-world)
-- Chronological beat sequences with act numbering and dramatic type classification
-- Prose narrative passages with lessons learned
-- Temporal metadata for understanding when narrative beats occurred
-
----
-
-## 🌊 Structural Tension Dynamics
-
-### Current Reality
-Narrative beats exist as `narrative_beat` entity records in JSONL. They carry rich metadata (act, dramatic type, universes, prose, lessons) but are just JSON objects. Without rendering, the story of structural tension work remains invisible — users see charts and actions but not the *meaning* of the work.
-
-### Desired Result
-Each narrative beat rendered as a richly structured card showing:
-- Act sequence and dramatic type (header)
-- Multi-universe perspective badges
-- Description and narrative prose
-- Lessons learned as discrete insight items
-- Temporal context via timestamps
-
-### Natural Resolution
-The `NarrativeBeats` component reads metadata from `EntityRecord[]` and renders each beat as a visually distinct card within the chart detail view, making the story layer tangible alongside the structural tension elements.
-
----
-
-## 📋 NarrativeBeats Component
-
-### Props
-```typescript
-interface NarrativeBeatsProps {
-  beats: EntityRecord[]    // Array of narrative_beat entities
-}
-```
-
-### EntityRecord Metadata Schema (for narrative beats)
-```typescript
-metadata: {
-  act: number                          // Act number in sequence (1, 2, 3...)
-  type_dramatic: string                // "Crisis/Antagonist Force", "Turning Point", "Setup", etc.
-  universes: string[]                  // ["engineer-world", "ceremony-world", "story-engine-world"]
-  timestamp: string                    // ISO 8601 creation timestamp
-  narrative: {
-    description: string                // Short description of the beat
-    prose: string                      // Full narrative passage
-    lessons: string[]                  // Array of lessons/insights
-  }
-}
-```
-
-### Render Structure
-
-```
-┌─────────────────────────────────────────────────────────┐
-│ 🎭 Act 3 · Crisis/Antagonist Force · Beat #7           │
-│    2024-03-15 14:30                                     │
-│                                                         │
-│ 🧭 Universes: [engineer-world] [ceremony-world]        │
-│                                                         │
-│ ✨ The parsing algorithm encountered a hierarchy depth  │
-│    that exceeded the expected 3-level nesting...        │
-│                                                         │
-│ ┌─────────────────────────────────────────────────────┐ │
-│ │ "The tension between flat JSONL and deep hierarchy  │ │
-│ │  became the very structural tension the tool was    │ │
-│ │  designed to visualize — a recursive mirror of      │ │
-│ │  its own purpose."                                  │ │
-│ └─────────────────────────────────────────────────────┘ │
-│                                                         │
-│ 📚 Lessons:                                             │
-│  • Recursive structures require iterative assembly      │
-│  • The tool's challenge mirrors the user's challenge    │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Visual Elements
-
-| Element | Lucide Icon | Display | Styling |
-|:---|:---|:---|:---|
-| **Act & Type** | `Drama` | "Act {N} · {type_dramatic} · Beat #{index}" | Header text, muted timestamp |
-| **Universes** | `Compass` | Badge per universe | Badge components in row |
-| **Description** | `Sparkles` | Short description text | Normal text |
-| **Prose** | — | Quoted narrative passage | Highlighted/quoted box, muted color |
-| **Timestamp** | `Clock` | ISO timestamp formatted | Muted text |
-| **Lessons** | *(no icon)* | Bulleted list | Muted boxes per lesson item |
-
-### Empty State
-When `beats.length === 0`, renders a centered muted text: "No narrative beats documented yet"
-
-### Card Styling
-- Left border accent using `chart-3` color theme
-- Card component with header and content sections
-- Responsive layout within chart detail view
-
----
-
-## 📋 Integration Points
-
-### Within ChartDetailEditable
-```
-ChartDetailEditable
-  └── if chart.narrativeBeats.length > 0:
-        <NarrativeBeats beats={chart.narrativeBeats} />
-```
-
-Narrative beats section appears between the Structural Tension section (desired outcome + current reality) and the Actions/Relations tabs.
-
-### Within ChartDetail (Read-Only)
-Same placement — narrative beats displayed as read-only cards.
-
-### Data Source
-Narrative beats are populated during `organizeData()` Pass 3, where entities with `entityType === "narrative_beat"` are collected into their chart's `narrativeBeats` array based on chart ID prefix matching.
-
----
-
-## 📋 Multi-Universe Perspectives
-
-The Three Archetypal Universes represent different lenses through which the same structural tension work is understood:
-
-| Universe | Perspective | What It Illuminates |
-|:---|:---|:---|
-| **engineer-world** | Technical precision | Algorithms, data structures, system behavior |
-| **ceremony-world** | Relational meaning | Kinship, accountability, ceremonial intent |
-| **story-engine-world** | Narrative arc | Drama, character, plot progression |
-
-A single narrative beat may exist in one, two, or all three universes simultaneously. The universe badges communicate which perspectives apply to each beat.
-
----
-
-## 📋 Creative Advancement Scenario
-
-### Scenario: Reading the Story of a Sprint
-**User Intent**: Understand the narrative arc of structural tension work across a multi-day session  
-**Current Structural Reality**: Chart has 5 completed actions and 12 narrative beats recorded by an agent
-
-**Natural Progression**:
-1. User selects chart from hierarchy view
-2. Scrolls to narrative beats section
-3. Sees beats ordered by act number with dramatic types
-4. Act 1 beats: "Setup" type — initial structural tension established
-5. Act 2 beats: "Turning Point" — key insight changes approach
-6. Act 3 beats: "Crisis/Antagonist Force" — complexity challenge encountered
-7. Act 4 beats: "Resolution" — structural tension resolved through creation
-8. Each beat shows universe badges indicating which perspectives apply
-9. Prose passages provide the full narrative of each moment
-10. Lessons capture the transferable wisdom from each beat
-
----
-
-## ✅ Quality Criteria
-
-✅ **Narrative Visibility**
-- Every narrative beat is rendered with its full metadata
-- Prose is visually distinct (quoted/highlighted) from description
-- Lessons are discrete, scannable items
-
-✅ **Universe Clarity**
-- Universe badges clearly labeled
-- Multiple universes displayed in a row without confusion
-- Missing universe data handled gracefully
-
-✅ **Temporal Context**
-- Timestamps displayed in human-readable format
-- Act numbering provides sequence context
-- Dramatic type provides narrative arc context
-
-✅ **Graceful Handling**
-- Empty beats array shows meaningful empty state message
-- Missing metadata fields don't crash the component
-- Component is purely presentational (no side effects)
-
----
-
-## 🔗 Related Components
-
-- [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md) — ChartDetail hosts NarrativeBeats
-- [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) — EntityRecord type with narrative metadata
-- [app.spec.md](./app.spec.md) — narrative beats as one of the core display layers

package/rispecs/pde-integration.spec.md

@@ -1,280 +0,0 @@
-# 🔮 Future Integration: PDE-Sourced Chart Visualization
-
-> How coaia-visualizer COULD surface the ceremonial origin and Four Directions structure of charts born from Prompt Decomposition Engine transformations.
-
-**Status**: 🔮 FUTURE / ASPIRATIONAL  
-**Framework**: RISE  
-**Cross-references**:
-- [app.spec.md](./app.spec.md) — current visualizer architecture
-- [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md) — current chart rendering
-- [`coaia-pde/rispecs/pde-to-stc-transformation.rispec.md`](../../coaia-pde/rispecs/pde-to-stc-transformation.rispec.md) — PDE metadata schema
-- [`coaia-pde/KINSHIP.md`](../../coaia-pde/KINSHIP.md) — PDE lineage and identity
-
----
-
-## 🌊 Structural Tension
-
-### Current Reality
-
-coaia-visualizer treats all JSONL charts identically. A chart produced by coaia-pde (from a PDE DecompositionResult with Four Directions metadata, implicit intents, confidence scores, and decomposition provenance) looks exactly the same as a hand-authored coaia-narrative chart. The `.coaia/pde/<UUID>.jsonl` files contain a `pde_session` header line and entities with `metadata.fourDirections`, `metadata.implicit`, `metadata.confidence`, and `metadata.direction` fields — none of which the visualizer reads or renders.
-
-Specifically:
-- PDE sessions start with `{ "type": "pde_session", ... }` — the visualizer ignores this entirely
-- Action steps carry `metadata.direction` (EAST/SOUTH/WEST/NORTH) — rendered as flat list
-- Some actions carry `metadata.implicit: true` — invisible to the user
-- Entity metadata contains `metadata.fourDirections` with `north_vision`, `east_intention`, `south_emotion`, `west_introspection` — not displayed
-- No link back to the `.pde/` decomposition that birthed the chart
-
-### Desired Result
-
-Practitioners see the **ceremony origin** of their structural tension. When a chart was born from PDE decomposition, the visualizer surfaces:
-- The Four Directions as a navigable Medicine Wheel layout with directional color coding
-- Which `.pde/` decomposition sourced this chart, with a facet count
-- Implicit intents flagged as visual badges so nothing is silently dropped
-- Action steps grouped by their ceremonial direction instead of a flat list
-- A provenance breadcrumb trail: Original Prompt → PDE Decomposition → STC Chart
-
-This creates a **living ceremonial map** — not just structural tension, but structural tension with its vision-lineage visible.
-
----
-
-## 🎨 Design Approach
-
-### 1. Four Directions Visualization
-
-**Concept**: Replace or augment the flat action list with a quadrant layout when `metadata.fourDirections` is present on the chart entity.
-
-**Medicine Wheel Color Scheme**:
-
-| Direction | Color | Icon | Role in Chart |
-|-----------|-------|------|---------------|
-| 🌅 EAST | `amber-400` / gold | Sunrise/Eye | Desired Outcome — what wants to emerge |
-| 🔥 SOUTH | `red-500` / crimson | Flame/Shield | Current Reality — what must be understood |
-| 🌊 WEST | `blue-500` / deep blue | Wave/Mirror | Structural Tension — the generative gap |
-| ❄️ NORTH | `slate-200` / white | Snowflake/Star | Action Steps — strategic secondary choices |
-
-**Layout Options**:
-
-A. **Quadrant View** (primary): Four-panel grid within ChartDetailEditable. Each quadrant holds its direction's content. Center shows the chart title and overall progress.
-
-```
-┌─────────────────┬─────────────────┐
-│   🌅 EAST       │   ❄️ NORTH      │
-│   Vision        │   Wisdom        │
-│   (desired      │   (actions /    │
-│    outcome)     │    strategic)   │
-├─────────────────┼─────────────────┤
-│   🔥 SOUTH      │   🌊 WEST       │
-│   Analysis      │   Experience    │
-│   (current      │   (tension /    │
-│    reality)     │    practice)    │
-└─────────────────┴─────────────────┘
-```
-
-B. **Direction Badges** (minimal): Each action step gets a colored direction badge beside it in the existing flat list. Lower lift, still informative.
-
-**Implementation Approach**:
-- Detect PDE origin via `pde_session` line or `metadata.fourDirections` on chart entity
-- New component: `FourDirectionsView` wrapping four `DirectionPanel` sub-components
-- `DirectionPanel` renders entities filtered by `metadata.direction`
-- Falls back to standard flat layout when no direction metadata exists
-- Transitions smoothly between quadrant and flat via toggle button
-
-### 2. PDE Source Linking
-
-**Concept**: When a chart originated from a PDE decomposition, show a provenance badge in the chart header.
-
-**Badge Content**:
-- 🔬 PDE source icon
-- Decomposition ID (truncated UUID)
-- Facet count (e.g., "4 facets — 2 implicit")
-- Original prompt snippet (first 80 chars)
-- Link/tooltip showing the `.pde/` file path
-
-**Data Source**: The `pde_session` metadata line contains:
-```json
-{
-  "type": "pde_session",
-  "id": "<UUID>",
-  "pdeId": "<decomposition-uuid>",
-  "createdAt": "ISO-8601",
-  "status": "active"
-}
-```
-
-**Implementation Approach**:
-- Extend `parseJSONL()` to recognize `pde_session` records and attach to chart metadata
-- New component: `PdeSourceBadge` displayed in `ChartDetailEditable` header
-- Optional: clicking badge opens a popover with full decomposition metadata
-
-### 3. Implicit Intent Indicators
-
-**Concept**: PDE extracts implicit intents that weren't explicitly stated in the original prompt. These become action steps with `metadata.implicit: true` and sometimes lower confidence. Surface these as visual warnings so practitioners know what was inferred vs. stated.
-
-**Visual Treatment**:
-- Implicit actions get a `⚡ Inferred` badge in `amber-500`
-- Tooltip explains: "This intent was not explicitly stated but was detected by PDE decomposition"
-- Optional filter toggle: "Show/Hide inferred intents"
-- Confidence score shown as a thin progress bar beneath the action text
-
-**Implementation Approach**:
-- Read `metadata.implicit` boolean on action_step entities
-- Read `metadata.confidence` number (0–1) on action_step entities
-- New sub-component: `ImplicitBadge` — conditional render within action item
-- New sub-component: `ConfidenceBar` — thin colored bar (green ≥0.8, amber ≥0.5, red <0.5)
-
-### 4. Direction-Based Action Grouping
-
-**Concept**: Instead of a flat action list, group actions by their Four Direction when `metadata.direction` is present.
-
-**Grouped Layout**:
-```
-❄️ NORTH — Strategic Actions
-  ├─ ☐ Implement authentication module
-  ├─ ☐ Deploy staging environment
-  └─ ✓ Configure CI pipeline
-
-🌅 EAST — Vision Actions
-  └─ ☐ Draft architecture decision record
-
-🔥 SOUTH — Analysis Actions
-  ├─ ☐ Audit existing dependencies
-  └─ ⚡ Review security assumptions (inferred)
-
-🌊 WEST — Experiential Actions
-  └─ ☐ Prototype user flow
-```
-
-**Implementation Approach**:
-- New utility: `groupActionsByDirection(actions: EntityRecord[])` → `Map<string, EntityRecord[]>`
-- New component: `DirectionActionGroup` renders a collapsible section per direction
-- Direction header shows icon, color, direction name, and count
-- Actions within each group maintain existing edit/complete/telescope capabilities
-- Ungrouped actions (no direction metadata) render in an "Uncategorized" section
-
-### 5. PDE-to-Chart Provenance Trail
-
-**Concept**: Visual breadcrumb showing the transformation path from original prompt to the current chart.
-
-**Breadcrumb Layout**:
-```
-💬 Original Prompt → 🔬 PDE Decomposition (4 facets) → 📊 STC Chart (chart_7)
-```
-
-**Each Segment**:
-- **Original Prompt**: Truncated prompt text, click to expand full text in dialog
-- **PDE Decomposition**: Decomposition ID, facet count, link to `.pde/` markdown export
-- **STC Chart**: Current chart ID with creation timestamp
-
-**Implementation Approach**:
-- New component: `ProvenanceTrail` rendered above chart header when PDE metadata exists
-- Data assembled from `pde_session` record + chart entity metadata
-- Each breadcrumb segment is a clickable element (expand or navigate)
-
----
-
-## 📊 Entity Metadata Requirements
-
-For this integration to work, coaia-pde JSONL must include these metadata fields (most already exist per the transformation rispec):
-
-### On `pde_session` Record (Line 1)
-```typescript
-{
-  type: "pde_session"
-  id: string                    // Session UUID
-  pdeId: string                 // Source decomposition UUID
-  originalPrompt?: string       // The prompt that was decomposed
-  facetCount?: number           // Number of PDE facets
-  implicitCount?: number        // Number of implicit intents detected
-  createdAt: string             // ISO-8601
-  status: "active" | "completed"
-}
-```
-
-### On `structural_tension_chart` Entity
-```typescript
-metadata: {
-  fourDirections?: {
-    north_vision: string
-    east_intention: string
-    south_emotion: string
-    west_introspection: string
-  }
-  pdeSource?: string            // Decomposition UUID
-  phase?: string                // Current phase
-}
-```
-
-### On `action_step` Entity
-```typescript
-metadata: {
-  direction?: "EAST" | "SOUTH" | "WEST" | "NORTH"
-  implicit?: boolean
-  confidence?: number           // 0–1
-  dependency?: string           // Name of dependent action
-  completionStatus?: boolean
-  order?: number
-}
-```
-
----
-
-## 🧩 UI Components Needed
-
-| Component | Purpose | Parent |
-|-----------|---------|--------|
-| `FourDirectionsView` | Quadrant layout for directional chart display | `ChartDetailEditable` |
-| `DirectionPanel` | Single direction content panel with color/icon | `FourDirectionsView` |
-| `PdeSourceBadge` | Provenance badge in chart header | `ChartDetailEditable` |
-| `ImplicitBadge` | "⚡ Inferred" indicator on action steps | Action item row |
-| `ConfidenceBar` | Thin colored confidence indicator | Action item row |
-| `DirectionActionGroup` | Collapsible direction-grouped action section | Actions tab |
-| `ProvenanceTrail` | Breadcrumb trail: Prompt → PDE → Chart | Above chart header |
-| `PdeDetailPopover` | Expanded PDE decomposition metadata | `PdeSourceBadge` click |
-
----
-
-## 🎯 What This Enables
-
-### For Practitioners
-- **See the ceremony**: A chart born from PDE decomposition visually carries its Medicine Wheel origin — not as decoration, but as navigational structure
-- **Trust the inference**: Implicit intents are visible, not hidden. Practitioners can validate or dismiss PDE's inferences with full awareness
-- **Navigate by direction**: Instead of a flat action list, practitioners move through EAST (vision) → SOUTH (analysis) → WEST (experience) → NORTH (wisdom) — the natural creative cycle
-
-### For the Ecosystem
-- **coaia-pde gains a face**: Its JSONL output becomes visually distinct and meaningful in the visualizer
-- **Provenance creates trust**: Seeing the transformation path (prompt → decomposition → chart) builds confidence in the automated pipeline
-- **Four Directions become tangible**: The Medicine Wheel framework moves from metadata convention to lived visual experience
-
----
-
-## ✅ Quality Criteria
-
-✅ **Ceremonial Integrity**
-- Four Directions use authentic Medicine Wheel colors and ordering (East → South → West → North)
-- Direction layout is a navigational tool, not decorative — each quadrant is interactive
-
-✅ **Graceful Degradation**
-- Charts without PDE metadata render exactly as they do today — zero regression
-- Missing fields (no `fourDirections`, no `implicit`) silently degrade to standard view
-- PDE components never render on non-PDE charts
-
-✅ **Structural Tension Preserved**
-- Desired outcome ↔ current reality tension remains the primary visual axis
-- Four Directions enhance but do not replace the core STC display
-- Creative orientation language maintained throughout all new components
-
-✅ **Data Fidelity**
-- No new JSONL fields invented — only existing coaia-pde metadata consumed
-- Provenance trail reads from data already in the JSONL (pde_session + entity metadata)
-- Round-trip: editing a PDE chart and exporting preserves all PDE metadata
-
----
-
-## 🔗 Cross-References
-
-- [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md) — ChartDetailEditable extension point
-- [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) — parseJSONL extension for `pde_session`
-- [ui-component-library.spec.md](./ui-component-library.spec.md) — color and icon patterns
-- [`coaia-pde/rispecs/pde-to-stc-transformation.rispec.md`](../../coaia-pde/rispecs/pde-to-stc-transformation.rispec.md) — source metadata schema
-- [planning-integration.spec.md](./planning-integration.spec.md) — sibling future spec