coaia-visualizer 1.6.3 → 1.6.4

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

@@ -0,0 +1,189 @@
+# 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

@@ -0,0 +1,280 @@
+# 🔮 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