coaia-visualizer 1.6.2 → 1.6.3

package/rispecs/planning-integration.spec.md

@@ -1,329 +0,0 @@
-# 🔮 Future Integration: Planning-Sourced Chart Visualization
-
-> How coaia-visualizer COULD surface the plan origin, confidence scores, sync state, and bidirectional editing bridge for charts born from Claude plan markdown 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
-- [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) — current editing capabilities
-- [`coaia-planning/rispecs/app.spec.md`](../../coaia-planning/rispecs/app.spec.md) — planning tools and metadata
-- [`coaia-planning/rispecs/bidirectional-sync.spec.md`](../../coaia-planning/rispecs/bidirectional-sync.spec.md) — sync mechanics
-- [`coaia-planning/KINSHIP.md`](../../coaia-planning/KINSHIP.md) — planning lineage
-
----
-
-## 🌊 Structural Tension
-
-### Current Reality
-
-coaia-visualizer consumes JSONL files from any source identically. Charts produced by coaia-planning's `plan_to_stc` tool carry metadata that the visualizer never reads:
-
-- **Confidence scores** (`metadata.confidence: 0–1`) on desired outcomes, current reality, and action steps — indicating how certain the parser was about its structural interpretation. The visualizer shows all elements with equal visual weight regardless of parse certainty.
-- **Source line references** (`metadata.sourceLines: { start, end }`) mapping each entity back to specific lines in the plan markdown — invisible in the UI.
-- **Telescoping markers** (`metadata.canTelescope`) on action steps that the parser identified as rich enough to expand — not surfaced.
-- **Plan file path** (`metadata.filePath`) linking the chart back to its source markdown — no provenance displayed.
-- **Sync state**: coaia-planning supports bidirectional sync (`sync_plan_to_chart` / `sync_chart_to_plan`), but the visualizer has no awareness of whether a chart is synced, diverged, or in conflict with its source plan.
-
-The result: a chart born from a carefully parsed Claude plan looks identical to a hand-authored chart, and edits made in the visualizer have no path back to the plan markdown.
-
-### Desired Result
-
-Practitioners **bridge between plan mode and structural tension** with full awareness. When a chart was born from a Claude plan, the visualizer:
-- Shows a plan source badge with the parse confidence score
-- Indicates whether the chart is synced with its source plan or has diverged
-- Maps each action step back to its plan section
-- Color-codes elements by confidence so practitioners focus review on uncertain interpretations
-- Offers a re-sync button to push visualizer edits back to plan markdown via coaia-planning
-
-This creates a **bidirectional creative surface** — plans inform charts, charts advance plans, and the practitioner sees both views as aspects of the same structural tension.
-
----
-
-## 🎨 Design Approach
-
-### 1. Plan Source Indicator
-
-**Concept**: Badge in the chart header showing this chart's plan origin and overall confidence.
-
-**Badge Design**:
-```
-📋 From Plan: deploy-pde.md  ·  Confidence: 87%  ·  ● Synced
-```
-
-**Visual States**:
-- `📋` Plan icon in `violet-500` (distinguishes from PDE's `🔬` in amber)
-- Plan filename as link/tooltip showing full path
-- Confidence as percentage with color: `green-500` ≥80%, `amber-500` ≥50%, `red-500` <50%
-- Sync indicator dot: `green-500` synced, `amber-500` diverged, `red-500` conflict
-
-**Data Source**: Chart entity `metadata.filePath` and aggregate confidence from child entities.
-
-**Implementation Approach**:
-- Detect plan origin via `metadata.filePath` ending in `.md` or `metadata.source === "plan"`
-- New component: `PlanSourceBadge` in chart header, symmetric to PDE's `PdeSourceBadge`
-- Aggregate confidence: average of all child entity confidence scores
-- Sync state determined by comparing chart `metadata.updatedAt` against plan file mtime (requires API extension)
-
-### 2. Bidirectional Sync Status
-
-**Concept**: Persistent visual indicator showing the relationship between the chart and its source plan.
-
-**Sync States**:
-
-| State | Icon | Color | Meaning |
-|-------|------|-------|---------|
-| **Synced** | ✓ circle | `green-500` | Chart matches plan — no divergence |
-| **Chart Ahead** | ↑ arrow | `blue-500` | Chart has changes not in plan |
-| **Plan Ahead** | ↓ arrow | `amber-500` | Plan has changes not in chart |
-| **Diverged** | ⇅ arrows | `amber-600` | Both changed independently |
-| **Conflict** | ⚠ warning | `red-500` | Incompatible changes detected |
-| **Unknown** | ? circle | `slate-400` | Sync state cannot be determined |
-
-**Implementation Approach**:
-- New API endpoint: `GET /api/plan-sync-status?chartPath=...&planPath=...`
-  - Calls coaia-planning's `sync_plan_to_chart` in dry-run mode
-  - Returns change list + sync state classification
-- New component: `SyncStatusIndicator` — icon + tooltip in chart header
-- Polling: optionally re-check sync status on interval (reuse existing live-reload pattern from `isLive` state)
-
-### 3. Plan Section Mapping
-
-**Concept**: Show which section of the plan markdown each entity came from.
-
-**Visual Treatment**:
-- Each action step shows a subtle tag: `§ Phase 2: Implementation` linking to its plan section
-- Desired outcome shows: `§ Overview` or whichever heading it was parsed from
-- Current reality shows its source section similarly
-
-**Section Display**:
-```
-☐ Implement authentication module
-  § Phase 2: Implementation  ·  Lines 42–48  ·  Confidence: 92%
-
-✓ Configure CI pipeline
-  § Phase 1: Infrastructure  ·  Lines 15–18  ·  Confidence: 98%
-```
-
-**Implementation Approach**:
-- Read `metadata.sourceLines` from action_step entities
-- Read `metadata.planSection` (new, populated by coaia-planning parser with heading context)
-- New sub-component: `PlanSectionTag` — subtle inline tag with section name
-- Click to expand: shows source line range and raw markdown excerpt (requires plan content access)
-
-### 4. Confidence Visualization
-
-**Concept**: Color-code all chart elements by their parse confidence score, letting practitioners immediately spot elements that need human review.
-
-**Confidence Tiers**:
-
-| Range | Color | Border | Meaning |
-|-------|-------|--------|---------|
-| ≥ 0.9 | None (default) | Standard | High confidence — parser is certain |
-| 0.7–0.89 | `amber-50` bg | `amber-200` | Moderate — likely correct, worth glancing |
-| 0.5–0.69 | `amber-100` bg | `amber-400` | Low — parser guessed, needs review |
-| < 0.5 | `red-50` bg | `red-300` | Very low — likely wrong, needs human correction |
-
-**Applied To**:
-- Desired outcome card background
-- Current reality card background
-- Individual action step rows
-- Section headers in grouped view
-
-**Implementation Approach**:
-- Utility function: `getConfidenceStyle(confidence: number)` → Tailwind classes
-- Applied as conditional className in `ChartDetailEditable` sub-components
-- Toggle: "Show confidence highlighting" switch in view controls (off by default for clean view)
-- Aggregate confidence shown in `PlanSourceBadge`
-
-### 5. Re-Sync Trigger
-
-**Concept**: Action button that pushes visualizer edits back to the plan markdown via coaia-planning's `sync_chart_to_plan` tool.
-
-**Button Placement**: In chart header, next to `SyncStatusIndicator`, visible only when chart has diverged from plan.
-
-**Workflow**:
-```
-User edits chart in visualizer
-       │
-       ▼
-SyncStatusIndicator shows "Chart Ahead ↑"
-       │
-       ▼
-User clicks "Sync to Plan" button
-       │
-       ├─ Preview mode (default):
-       │    Shows diff of what would change in plan markdown
-       │    User confirms or cancels
-       │
-       └─ Apply:
-            POST /api/plan-sync with { chartPath, planPath, direction: "chart-to-plan" }
-            Server calls coaia-planning sync_chart_to_plan
-            SyncStatusIndicator updates to "Synced ✓"
-```
-
-**Implementation Approach**:
-- New API endpoint: `POST /api/plan-sync`
-  - `direction`: `"chart-to-plan"` or `"plan-to-chart"`
-  - `dryRun`: boolean (default true for preview)
-  - Calls coaia-planning MCP tools via stdio
-- New component: `SyncButton` with preview dialog
-- Preview dialog: `SyncPreviewDialog` showing change list (new/modified/removed actions)
-- Confirmation triggers actual sync and refreshes chart data
-
-### 6. Plan-Aware Chart Creation
-
-**Concept**: Extend the "Add Chart" workflow to accept a plan file as input source.
-
-**Flow**:
-```
-User clicks "Add Chart" → Tab: "From Plan"
-       │
-       ▼
-File picker for .md plan files
-       │
-       ▼
-Preview: parsed structural tension (desired outcome, current reality, actions)
-       │
-       ▼
-User adjusts confidence thresholds, confirms
-       │
-       ▼
-Chart created with full plan metadata attached
-```
-
-**Implementation Approach**:
-- Extend `CreateChartForm` with a "From Plan" tab
-- New component: `PlanImportForm` — file picker + structural preview
-- Calls `parse_plan_structural` for preview, then `plan_to_stc` on confirm
-- Created chart retains all planning metadata for sync lifecycle
-
----
-
-## 📊 Entity Metadata Requirements
-
-For this integration to work, coaia-planning JSONL must include these metadata fields (most already specified in the planning rispecs):
-
-### On `structural_tension_chart` Entity
-```typescript
-metadata: {
-  source?: "plan" | "pde" | "manual"     // Origin discriminator
-  filePath?: string                       // Source plan path
-  parsedAt?: string                       // ISO-8601 parse timestamp
-  telescopeLevel?: number                 // 0=root, 1+=nested
-  completionStatus?: string               // "pending" | "in_progress" | "completed"
-  syncState?: {
-    lastSyncAt?: string                   // ISO-8601
-    syncDirection?: "plan-to-chart" | "chart-to-plan"
-    diverged?: boolean
-  }
-}
-```
-
-### On `desired_outcome` / `current_reality` Entity
-```typescript
-metadata: {
-  confidence?: number                     // 0–1 parse confidence
-  sourceLines?: { start: number, end: number }
-  planSection?: string                    // Heading context from plan
-}
-```
-
-### On `action_step` Entity
-```typescript
-metadata: {
-  confidence?: number                     // 0–1
-  sourceLines?: { start: number, end: number }
-  planSection?: string                    // Which plan section
-  canTelescope?: boolean                  // Parser's assessment
-  completionStatus?: boolean
-  order?: number
-}
-```
-
----
-
-## 🧩 UI Components Needed
-
-| Component | Purpose | Parent |
-|-----------|---------|--------|
-| `PlanSourceBadge` | Plan origin badge with confidence and sync state | `ChartDetailEditable` header |
-| `SyncStatusIndicator` | Sync state icon with tooltip | `PlanSourceBadge` or header |
-| `SyncButton` | Trigger bidirectional sync | Chart header, near sync indicator |
-| `SyncPreviewDialog` | Show changes before applying sync | Modal from `SyncButton` |
-| `PlanSectionTag` | Inline tag showing plan section origin | Action item row |
-| `ConfidenceOverlay` | Conditional background coloring by confidence | Wraps entity display components |
-| `PlanImportForm` | Import plan file to create chart | `CreateChartForm` tab |
-| `ConfidenceToggle` | Show/hide confidence highlighting | View controls area |
-
----
-
-## 🔌 API Extensions Needed
-
-| Endpoint | Method | Purpose |
-|----------|--------|---------|
-| `/api/plan-sync-status` | GET | Query sync state between chart and plan |
-| `/api/plan-sync` | POST | Execute bidirectional sync (with dry-run) |
-| `/api/plan-import` | POST | Import plan file and create chart |
-| `/api/plan-preview` | POST | Parse plan structurally for preview |
-
-These endpoints would proxy to coaia-planning MCP tools via stdio transport, consistent with the existing MCP integration pattern in [api-mcp-interface.spec.md](./api-mcp-interface.spec.md).
-
----
-
-## 🎯 What This Enables
-
-### For Practitioners
-- **Bridge two workflows**: Move fluidly between Claude's plan mode (familiar, markdown-native) and structural tension visualization (ceremonial, depth-oriented) without losing context
-- **Trust the parse**: Confidence highlighting shows exactly where the automated plan→chart transformation needs human review
-- **Stay synchronized**: Edits in the visualizer flow back to plan markdown; plan updates flow forward to charts. Neither view becomes stale
-- **Focused review**: Low-confidence elements draw the eye, letting practitioners spend energy where it matters most
-
-### For the Ecosystem
-- **coaia-planning gains a face**: Its JSONL output becomes visually rich and interactive in the visualizer
-- **Bidirectional sync becomes tangible**: The sync mechanics specified in `bidirectional-sync.spec.md` get a user-facing interface
-- **Plan mode enters the ceremony**: Claude plans, which begin as utilitarian markdown, gain ceremonial structure when visualized as structural tension charts
-- **Multi-agent visibility**: When multiple agents work through a shared plan→chart, the visualizer becomes the human's window into collective structural advancement
-
----
-
-## ✅ Quality Criteria
-
-✅ **Structural Tension Preserved**
-- Confidence coloring enhances but never replaces the core desired outcome ↔ current reality display
-- Plan source indicator is informational — it does not change how structural tension is held
-- Creative orientation language maintained in all new components
-
-✅ **Graceful Degradation**
-- Charts without planning metadata render exactly as they do today — zero regression
-- Missing confidence scores default to no highlighting (not zero confidence)
-- Sync features disabled when no plan path is available
-- All new components conditional on metadata presence
-
-✅ **Sync Safety**
-- Re-sync always previews changes before applying (dry-run default)
-- Conflict states clearly communicated — never auto-resolved silently
-- Backup created before every sync operation (consistent with existing API pattern)
-
-✅ **Data Fidelity**
-- No new JSONL fields invented — only existing coaia-planning metadata consumed
-- `planSection` is the only field that may need coaia-planning parser enhancement
-- Round-trip: editing a plan-sourced chart and exporting preserves all planning metadata
-- Sync operations are idempotent — running twice produces same result
-
-✅ **Consistency with PDE Integration**
-- Source badges follow same visual pattern (icon + source + confidence + state)
-- Both PDE and planning charts use the same `ChartDetailEditable` extension points
-- A chart could theoretically carry both PDE and planning metadata (PDE → Plan → Chart pipeline)
-
----
-
-## 🔗 Cross-References
-
-- [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md) — ChartDetailEditable extension point
-- [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) — editing patterns that sync must preserve
-- [api-mcp-interface.spec.md](./api-mcp-interface.spec.md) — API extension patterns
-- [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) — metadata parsing extension
-- [`coaia-planning/rispecs/bidirectional-sync.spec.md`](../../coaia-planning/rispecs/bidirectional-sync.spec.md) — sync mechanics this spec surfaces
-- [pde-integration.spec.md](./pde-integration.spec.md) — sibling future spec

package/rispecs/relation-graph-visualization.spec.md

@@ -1,171 +0,0 @@
-# Relation Graph Visualization
-## RISE Specification for Inter-Entity Connection Display
-
-**Component Purpose**: Render the relational kinship between entities within a chart — showing how desired outcomes, current realities, action steps, and narrative beats are connected through typed relations.
-
-**Source Files**: `components/relation-graph.tsx`
-
----
-
-## 🎯 What This Component Enables Users to Create
-
-- Visible maps of kinship between chart elements
-- Understanding of how structural tension flows between entities
-- Awareness of which entities are connected and through what relation types
-- Entity observation previews without navigating away from the chart view
-
----
-
-## 🌊 Structural Tension Dynamics
-
-### Current Reality
-Relations exist as `RelationRecord` objects in the parsed data. They encode structural meaning — "contains", "creates_tension_with", "advances_toward", "documents" — but are invisible without a dedicated display. Users can see charts and their components but not the *connections* between them.
-
-### Desired Result
-A card-based display within each chart's detail view that:
-- Groups relations by type (contains, creates_tension_with, advances_toward, documents)
-- Shows each relation as a from→to pair with entity previews
-- Uses badges to label relation types with counts
-- Provides at-a-glance understanding of the relational structure
-
-### Natural Resolution
-The `RelationGraph` component reduces the chart's relations array into type-grouped sections, looking up entity details from the entities Map for preview text.
-
----
-
-## 📋 RelationGraph Component
-
-### Props
-```typescript
-interface RelationGraphProps {
-  chart: Chart           // Chart whose relations to display
-  data: ParsedData       // Full data for entity lookups
-}
-```
-
-### Render Structure
-
-```
-┌───────────────────────────────────────────────────┐
-│ Entity Relations                                  │
-│ Connections between chart entities                 │
-│                                                   │
-│ [contains] (3)                                    │
-│   chart_1 → chart_1_desired_outcome               │
-│     "Build structural tension visualizer..."      │
-│   chart_1 → chart_1_current_reality               │
-│     "JSONL parser handles all entity types..."    │
-│   chart_1 → chart_1_action_1                      │
-│     "Design entity type system"                   │
-│                                                   │
-│ [creates_tension_with] (1)                        │
-│   chart_1_current_reality → chart_1_desired_outc. │
-│     "JSONL parser handles..." → "Build struct..." │
-│                                                   │
-│ [advances_toward] (2)                             │
-│   chart_4_desired_outcome → chart_1_desired_outc. │
-│     "Design entity types..." → "Build struct..."  │
-│   chart_5_desired_outcome → chart_1_desired_outc. │
-│     "Implement parsing..." → "Build struct..."    │
-└───────────────────────────────────────────────────┘
-```
-
-**Card Wrapper**: Rendered inside a `Card` component with `CardHeader` title "Entity Relations" and description "Connections between chart entities".
-
-**Empty State**: When `relations.length === 0`, renders the Card with centered muted text: "No relations defined".
-
-**Badge Text Transform**: Relation type badges display with underscores replaced by spaces: `relationType.replace(/_/g, ' ')`
-
-### Grouping Algorithm
-```
-1. Take chart.relations array
-2. Reduce into object keyed by relationType:
-   {
-     "contains": [rel1, rel2, rel3],
-     "creates_tension_with": [rel4],
-     "advances_toward": [rel5, rel6]
-   }
-3. For each group:
-   a. Render relation type badge with count
-   b. For each relation in group:
-      - Look up from entity in data.entities Map
-      - Look up to entity in data.entities Map
-      - Display: fromName → toName
-      - Show observations[0] as preview text for each entity
-```
-
-### Relation Types
-
-| Relation Type | Meaning | Typical From→To |
-|:---|:---|:---|
-| `contains` | Chart contains component | chart → desired_outcome, current_reality, action_step |
-| `creates_tension_with` | Reality creates tension with outcome | current_reality → desired_outcome |
-| `advances_toward` | Action/sub-chart advances toward parent outcome | sub-chart desired_outcome → parent desired_outcome |
-| `documents` | Beat documents chart activity | narrative_beat → chart |
-
-### Entity Preview
-For each entity in a relation:
-- Display entity name (identifier)
-- Show `observations[0]` as preview text (first observation)
-- If entity not found in Map, show name only
-
----
-
-## 📋 Integration Points
-
-### Within ChartDetailEditable / ChartDetail
-```
-<Tabs>
-  <TabsTrigger value="actions">Actions ({chart.actions.length})</TabsTrigger>
-  <TabsTrigger value="relations">Relations ({chart.relations.length})</TabsTrigger>
-</Tabs>
-
-<TabsContent value="relations">
-  <RelationGraph chart={chart} data={data} />
-</TabsContent>
-```
-
-The relation graph appears as a tab alongside the actions list, accessible in both read-only and editable chart detail views.
-
----
-
-## 📋 Creative Advancement Scenario
-
-### Scenario: Understanding Telescoped Structure
-**User Intent**: See how a sub-chart's actions advance toward the parent chart's desired outcome  
-**Current Structural Reality**: Chart has 3 sub-charts but the advancement connections aren't visible
-
-**Natural Progression**:
-1. User selects parent chart
-2. Clicks "Relations" tab
-3. Sees `advances_toward` group with 3 entries
-4. Each entry shows: sub-chart desired outcome → parent desired outcome
-5. Preview text reveals the specific advancement path
-6. User understands how sub-charts contribute to the parent's creative vision
-
----
-
-## ✅ Quality Criteria
-
-✅ **Relational Clarity**
-- Relations grouped by type with badge labels
-- Count shows how many relations per type
-- From→To direction clearly indicated
-
-✅ **Entity Context**
-- Entity names displayed for identification
-- First observation shown as preview text
-- Missing entities handled gracefully (name-only display)
-
-✅ **Structural Tension Visibility**
-- `creates_tension_with` relations make the fundamental tension visible
-- `advances_toward` relations show how actions drive resolution
-- `contains` relations reveal chart composition
-
----
-
-## 🔗 Related Components
-
-- [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md) — hosts RelationGraph in chart detail tabs
-- [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) — RelationRecord type and entity lookups
-- [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) — ChartEditor creates/deletes relations during mutations

package/rispecs/relation-to-mcp-structural-thinking.kin.md

@@ -1,65 +0,0 @@
-# Relation to mcp-structural-thinking
-
-> Kinship document describing the envisioned relationship between **coaia-visualizer** (Web UI for STC visualization/editing) and **mcp-structural-thinking** (Structural Thinking diagnostic layer).
-
-## The Relationship
-
-**coaia-visualizer** renders Structural Tension Charts as interactive web UIs — displaying chart hierarchies, editing workflows, narrative beats, and relation graphs. **mcp-structural-thinking** provides validation data that could enrich the display: three-universe scores as visual badges, reactive pattern highlights, and PDE question overlays.
-
-```
-coaia-narrative (JSONL)
-    │
-    ▼
-coaia-visualizer (parseJSONL → organizeData → UI)
-    │ Charts, Hierarchies, Relation Graphs
-    │
-    ├──▶ mcp-structural-thinking (validate_three_universe per chart)
-    │         │ scores + flags + discrepancies
-    │         ▼
-    │    Visual indicators:
-    │      🟢 Mia: 0.8  🟡 Miette: 0.6  🔴 Ava: 0.3
-    │      ⚠️ Discrepancy: "Technically precise but relationally extractive"
-    │
-    ▼
-Enhanced visualization with validation context
-```
-
-## What coaia-visualizer Offers to mcp-structural-thinking
-
-- **Human-readable rendering** — makes three-universe validation scores visible and actionable
-- **Editing workflow** — users can refine charts in response to validation flags, then re-validate
-- **Relation graph** — could visualize which charts have consensus and which don't
-- **Narrative beats** — could annotate beats with validation history
-
-## What mcp-structural-thinking Offers to coaia-visualizer
-
-- **Three-universe scores** — per-chart scores (Mia/Miette/Ava) as color-coded badges or progress bars
-- **Reactive pattern highlights** — flagged language patterns shown inline in chart text
-- **PDE validation questions** — embedded in chart detail views as expandable sections
-- **Consensus status** — visual indicator (✅/❌) on each chart's header
-- **Behavioral pattern classification** — oscillation/advancing badges on chart overview
-
-## Envisioned UI Enhancements
-
-### Chart List View
-- Consensus badge: ✅ or ❌ next to each chart name
-- Three-universe mini-bar: `Mia: ████ Miette: ███░ Ava: ██░░`
-
-### Chart Detail View
-- Three-universe scores in sidebar
-- Reactive patterns highlighted in desired outcome / current reality text
-- PDE validation questions in collapsible section
-- Discrepancies displayed as alert banners
-
-### Relation Graph View
-- Charts with FALSE consensus highlighted in different color
-- Edges annotated with cross-chart discrepancies
-
-## Accountability
-
-- coaia-visualizer owns the rendering and editing UX — mcp-structural-thinking provides data, never dictates display
-- Validation scores should be stored as entity metadata (via coaia-narrative) so they persist across sessions
-
----
-
-*Created: 2026-03-31 | Steward: Guillaume (jgwill)*