project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/unit-brief.md

@@ -0,0 +1,305 @@
+---
+unit: sidebar-provider
+intent: 011-vscode-extension
+phase: construction
+status: complete
+created: 2025-12-25T16:45:00Z
+updated: 2025-12-27T16:30:00Z
+default_bolt_type: simple-construction-bolt
+---
+
+# Unit Brief: Sidebar Provider
+
+## Purpose
+
+Implement VS Code WebviewViewProvider to render a tabbed sidebar with three views: Bolts (command center), Specs (tree hierarchy), and Overview (metrics dashboard). Handle all visual presentation, user interactions, and state management for the sidebar UI.
+
+## Scope
+
+### In Scope
+
+- WebviewViewProvider implementation for tabbed sidebar
+- **Bolts Tab (Command Center)**:
+  - Current Intent header with bolt statistics
+  - Current Focus expandable card with progress ring, stage pipeline, stories
+  - Up Next queue with dependency-ordered pending bolts
+  - Recent Activity section with filter and resize handle
+- **Specs Tab (Tree View)**:
+  - Intent → Unit → Story hierarchy
+  - Progress indicators (ring charts)
+  - Filter by status
+  - Expand/collapse support
+- **Overview Tab (Dashboard)**:
+  - Overall progress metrics
+  - Intents list with progress
+  - Active bolts summary
+- Status icon display (gray/yellow/green/red for blocked)
+- Bolt type badges (DDD, Simple)
+- Theme support (dark/light)
+- State persistence (active tab, expanded nodes, activity height)
+- Tree refresh on data changes
+
+### Out of Scope
+
+- File parsing (handled by artifact-parser)
+- File watching (handled by file-watcher)
+- Command handling (handled by extension-core)
+- Welcome view (handled by welcome-view)
+
+---
+
+## Assigned Requirements
+
+| FR | Requirement | Priority |
+|----|-------------|----------|
+| FR-1.2 | Display memory-bank artifacts in tree structure | Must |
+| FR-1.5 | Display pixel logo as fadeout footer | Should |
+| FR-2.1 | Intents as top-level items | Must |
+| FR-2.2 | Units nested under intents | Must |
+| FR-2.3 | Stories nested under units | Must |
+| FR-2.4 | Bolts in separate section with unit grouping | Must |
+| FR-2.5 | Standards in separate section | Must |
+| FR-2.6 | Expand/collapse for all parent nodes | Must |
+| FR-2.7 | Sort intents by number prefix | Must |
+| FR-2.8 | Configurable bolt sorting | Must |
+| FR-3.5 | Status icons (gray/yellow/green/?) | Must |
+| FR-8.1 | Three tabs: Bolts, Specs, Overview | Must |
+| FR-8.2 | Bolts tab shows command center | Must |
+| FR-8.3 | Specs tab shows hierarchy tree | Must |
+| FR-8.4 | Overview tab shows metrics dashboard | Must |
+| FR-8.5 | Tab state persistence | Must |
+| FR-8.6 | Theme support (dark/light) | Must |
+| FR-9.1 | Current Intent header with statistics | Must |
+| FR-9.2 | Current Focus expandable card | Must |
+| FR-9.3 | Progress ring, pipeline, stories in focus card | Must |
+| FR-9.4 | Up Next queue section | Must |
+| FR-9.5 | Dependency-ordered queue | Must |
+| FR-9.6 | Blocked bolt indication | Must |
+| FR-9.7 | Recent Activity section | Must |
+| FR-9.8 | Activity filter (All/Stages/Bolts) | Must |
+| FR-9.9 | Resizable activity panel | Should |
+| FR-9.10 | Activity height persistence | Should |
+| FR-11.4 | Activity item display (icon, text, time) | Must |
+
+---
+
+## Domain Concepts
+
+### Key Entities
+
+| Entity | Description | Attributes |
+|--------|-------------|------------|
+| SpecsmdWebviewProvider | Main provider class | extensionUri, state, webview |
+| SidebarState | UI state object | activeTab, expandedNodes, activityFilter, activityHeight |
+| FocusCard | Active bolt display | bolt, progress, stages, stories, expanded |
+| QueueItem | Pending bolt in queue | bolt, priority, isBlocked, blockedBy |
+| ActivityItem | Activity feed item | event, icon, text, target, tag, time |
+| ProgressRing | Circular progress | percent, size, color |
+| StagePipeline | Stage visualization | stages[], currentStage |
+| TreeNode | Base tree item | id, label, type, children, status |
+| IntentNode | Intent tree item | intent data, units[], progress |
+| UnitNode | Unit tree item | unit data, stories[], progress |
+
+### Key Operations
+
+| Operation | Description | Inputs | Outputs |
+|-----------|-------------|--------|---------|
+| resolveWebviewView | Create webview content | WebviewView | void |
+| getHtmlContent | Generate HTML for webview | state, data | string |
+| handleMessage | Process webview messages | message | void |
+| switchTab | Change active tab | tabId | void |
+| toggleExpand | Toggle node expansion | nodeId | void |
+| setActivityFilter | Filter activity feed | filter | void |
+| resizeActivity | Handle activity resize | height | void |
+| renderBoltsTab | Render command center | state, data | string |
+| renderSpecsTab | Render tree hierarchy | state, data | string |
+| renderOverviewTab | Render metrics dashboard | state, data | string |
+| getStatusIcon | Get icon class for status | ArtifactStatus | string |
+| formatRelativeTime | Format timestamp | Date | string |
+
+---
+
+## Story Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Stories | 19 |
+| Must Have | 11 |
+| Should Have | 6 |
+| Could Have | 2 |
+| Complete | 17 |
+| In Progress | 1 |
+| Draft | 1 |
+
+### Stories
+
+| Story ID | Title | Priority | Status | Bolt |
+|----------|-------|----------|--------|------|
+| 001 | Tree Data Provider Setup | Must | Complete | bolt-1 |
+| 002 | Intent/Unit/Story Tree | Must | Complete | bolt-1 |
+| 003 | Bolt Tree with Stages and Stories | Must | Complete | bolt-2 |
+| 004 | Status Icons and Badges | Must | Complete | bolt-2 |
+| 005 | Pixel Logo Footer | Should | Complete | bolt-2 |
+| 006 | Webview Tab Architecture | Must | Complete | bolt-3 |
+| 007 | Command Center (Bolts Tab) | Must | Complete | bolt-3 |
+| 008 | Current Focus Card | Must | Complete | bolt-4 |
+| 009 | Up Next Queue with Dependencies | Must | Complete | bolt-4 |
+| 010 | Activity Feed UI | Must | Complete | bolt-4 |
+| 011 | FileWatcher StateStore Integration | Must | Complete | bolt-5 |
+| 012 | Next Actions UI | Should | Complete | bolt-5 |
+| 013 | Start Bolt Action | Should | Complete | bolt-5 |
+| 014 | Intent Selection Strategies | Could | Complete | bolt-5 |
+| 015 | Persist Expanded State | Should | In Progress | bolt-5 |
+| 016 | Bolt Filtering | Could | Draft | bolt-5 |
+| 017 | Activity Open Button | Should | Complete | bolt-5 |
+| 018 | Specs View Implementation | Must | Complete | bolt-5 |
+| 019 | Overview View Implementation | Must | Complete | bolt-5 |
+
+---
+
+## Dependencies
+
+### Depends On
+
+| Unit | Reason |
+|------|--------|
+| artifact-parser | Gets parsed artifact data |
+| file-watcher | Subscribes to refresh events |
+
+### Depended By
+
+| Unit | Reason |
+|------|--------|
+| extension-core | Registers provider |
+
+### External Dependencies
+
+| System | Purpose | Risk |
+|--------|---------|------|
+| VS Code TreeView API | Tree rendering | Low |
+| VS Code Webview API | Logo footer | Low |
+
+---
+
+## Technical Context
+
+### Suggested Technology
+
+- vscode.WebviewViewProvider interface
+- HTML/CSS/JS for webview content
+- VS Code CSS variables for theming
+- PostMessage API for webview ↔ extension communication
+- VS Code workspaceState for persistence
+
+### Integration Points
+
+| Integration | Type | Protocol |
+|-------------|------|----------|
+| VS Code WebviewView | API | WebviewViewProvider |
+| artifact-parser | Import | TypeScript |
+| file-watcher | Event | Callback/EventEmitter |
+| extension-core | Commands | VS Code commands |
+
+### Data Storage
+
+| Data | Type | Volume | Retention |
+|------|------|--------|-----------|
+| UI state | In-memory | Small | Session |
+| Tab/expand state | workspaceState | Tiny | Persistent |
+| Activity height | workspaceState | Tiny | Persistent |
+
+---
+
+## Constraints
+
+- Must use WebviewViewProvider for tabbed interface (TreeView doesn't support tabs)
+- Must use VS Code CSS variables for proper theme support
+- Webview content must be secure (CSP headers, nonce for scripts)
+- Must handle webview disposal and re-creation gracefully
+- Activity panel resize must feel native (smooth, responsive)
+
+---
+
+## Success Criteria
+
+### Functional
+
+- [ ] Three tabs display and switch correctly
+- [ ] Bolts tab shows command center layout
+- [ ] Current Focus card displays active bolt with progress ring
+- [ ] Stage pipeline shows all stages with correct status
+- [ ] Up Next queue orders bolts by dependency priority
+- [ ] Blocked bolts show blocker indication
+- [ ] Activity feed displays events with correct formatting
+- [ ] Activity filter works (All/Stages/Bolts)
+- [ ] Activity panel resizable with drag handle
+- [ ] Specs tab shows Intent → Unit → Story tree
+- [ ] Overview tab shows aggregate metrics
+- [ ] Tab state persists across sessions
+- [ ] Expand/collapse state persists
+- [ ] Theme switching works (dark/light)
+- [ ] UI refreshes on file changes
+
+### Non-Functional
+
+- [ ] Initial render < 300ms
+- [ ] Tab switch < 100ms
+- [ ] Smooth resize animations (60fps)
+- [ ] Proper theme variable usage
+
+### Quality
+
+- [ ] Unit tests for render functions
+- [ ] Unit tests for state management
+- [ ] Visual regression tests (screenshots)
+- [ ] Code coverage > 80%
+
+---
+
+## Bolt Suggestions
+
+| Bolt | Type | Stories | Objective | Status |
+|------|------|---------|-----------|--------|
+| bolt-sidebar-provider-1 | Simple | 001, 002 | Basic tree structure | Complete |
+| bolt-sidebar-provider-2 | Simple | 003, 004, 005 | Bolts, status, footer | Complete |
+| bolt-sidebar-provider-3 | Simple | 006, 007 | Webview architecture + command center | Complete |
+| bolt-sidebar-provider-4 | Simple | 008, 009, 010 | Focus card, queue, activity UI | Complete |
+| bolt-sidebar-provider-5 | Simple | 011-019 | StateStore integration, views, actions | Complete* |
+
+*Note: bolt-5 complete with reduced scope (015 partial, 016 deferred)
+
+---
+
+## Notes
+
+- **Design Reference**: `vs-code-extension/design-mockups/variation-8-2.html`
+- **Spec Document**: `vs-code-extension/design-mockups/variation-8-2-spec.md`
+- Tabbed UI visualization:
+```
+┌─────────────────────────────────────────┐
+│ SpecsMD                        [↻] [⚙]  │
+├─────────────────────────────────────────┤
+│  ⚡ Bolts  │  📋 Specs  │  📊 Overview  │
+├─────────────────────────────────────────┤
+│ CURRENT INTENT: 011-vscode-extension    │
+│ ● 1 Active  ○ 2 Queued  ✓ 3 Done       │
+├─────────────────────────────────────────┤
+│ 🎯 CURRENT FOCUS                        │
+│ ┌─────────────────────────────────────┐ │
+│ │ bolt-sidebar-ui-1     [In Progress] │ │
+│ │ [Progress Ring 40%] Design Stage    │ │
+│ │ [M]✓─[D]●─[A]○─[I]○─[T]○           │ │
+│ └─────────────────────────────────────┘ │
+├─────────────────────────────────────────┤
+│ UP NEXT                        2 bolts  │
+│ 1 │ bolt-webview-panel-1 (unblocked)   │
+│ 🔒│ bolt-x (blocked by: bolt-y)        │
+├═══════════════════════════════════════──┤
+│ 🕐 RECENT ACTIVITY     [All][S][B]      │
+│ ✓ Completed model stage      2h ago    │
+│ ▶ Started bolt-sidebar-ui    3h ago    │
+└─────────────────────────────────────────┘
+```
+- Use VS Code CSS variables for theming: `--vscode-*`
+- WebviewViewProvider for sidebar webview
+- PostMessage API for communication

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/webview-lit-migration/stories/020-fix-infinite-rerender.md

@@ -0,0 +1,144 @@
+---
+id: vscode-extension-story-wlm-020
+unit: webview-lit-migration
+intent: 011-vscode-extension
+status: complete
+implemented: true
+priority: must
+created: 2025-12-26
+---
+
+# Story: Fix Infinite Re-render Loop
+
+## User Story
+
+**As a** extension user
+**I want** the sidebar to respond to clicks
+**So that** I can navigate between tabs and interact with the UI
+
+## Problem
+
+The webview is being re-rendered in an infinite loop (200+ times per second), which:
+1. Destroys DOM elements with their event listeners
+2. Creates new DOM elements
+3. Attaches new event listeners
+4. Immediately destroys them again
+
+Console evidence:
+```
+VM10:5 [SpecsMD] Scripts initializing...
+VM16:5 [SpecsMD] Scripts initializing...
+VM22:5 [SpecsMD] Scripts initializing...
+... (hundreds more)
+```
+
+## Root Cause Analysis
+
+Likely causes to investigate:
+
+1. **StateStore Subscription Loop**
+   - `_updateWebview()` triggers state change
+   - State change triggers subscription
+   - Subscription calls `_updateWebview()`
+   - Infinite loop
+
+2. **FileWatcher Triggering Refresh**
+   - File changes trigger `scanMemoryBank()`
+   - Which triggers `loadFromModel()`
+   - Which triggers store update
+   - Which triggers `_updateWebview()`
+
+3. **Ready Message Loop**
+   - Script sends `ready` message
+   - Provider calls `refresh()`
+   - Refresh re-renders webview
+   - New script sends `ready` again
+
+## Acceptance Criteria
+
+- [ ] **Given** webview is visible, **When** loaded, **Then** scripts initialize exactly once
+- [ ] **Given** webview is rendered, **When** user clicks tab, **Then** click handler fires
+- [ ] **Given** StateStore changes, **When** not from webview init, **Then** webview updates once
+- [ ] **Given** file changes, **When** debounce completes, **Then** single refresh occurs
+
+## Technical Implementation
+
+### 1. Add Re-render Guard
+```typescript
+// webviewProvider.ts
+private _isUpdating = false;
+private _pendingUpdate = false;
+
+private _updateWebview(): void {
+    if (this._isUpdating) {
+        this._pendingUpdate = true;
+        return;
+    }
+
+    this._isUpdating = true;
+    try {
+        // ... render logic
+    } finally {
+        this._isUpdating = false;
+        if (this._pendingUpdate) {
+            this._pendingUpdate = false;
+            this._updateWebview();
+        }
+    }
+}
+```
+
+### 2. Debounce Store Updates
+```typescript
+// Only update webview on actual data changes
+this._unsubscribe = this._store.subscribe(() => {
+    // Compare previous state hash to avoid unnecessary re-renders
+    const newHash = this._computeStateHash();
+    if (newHash !== this._lastStateHash) {
+        this._lastStateHash = newHash;
+        this._updateWebview();
+    }
+});
+```
+
+### 3. Fix Ready Message Handler
+```typescript
+case 'ready':
+    // Only refresh if not already loaded
+    if (!this._initialLoadComplete) {
+        this._initialLoadComplete = true;
+        await this.refresh();
+    }
+    break;
+```
+
+### 4. Add Render Counter for Debugging
+```typescript
+private _renderCount = 0;
+
+private _updateWebview(): void {
+    this._renderCount++;
+    console.log(`[SpecsMD Provider] Render #${this._renderCount}`);
+    // ... rest of method
+}
+```
+
+## Files to Modify
+
+- `src/sidebar/webviewProvider.ts` - Add re-render guards
+- `src/state/stateStore.ts` - Add state comparison
+- `src/webview/scripts.ts` - Add initialization guard
+
+## Testing
+
+- Manual: Open DevTools, verify single initialization
+- Manual: Click tabs, verify `[SpecsMD] Tab clicked:` appears
+- Unit: Mock store subscription, verify single render per change
+
+## Dependencies
+
+### Requires
+- None (bug fix)
+
+### Blocks
+- All other webview-lit-migration stories

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/webview-lit-migration/stories/021-remove-duplicate-files.md

@@ -0,0 +1,94 @@
+---
+id: vscode-extension-story-wlm-021
+unit: webview-lit-migration
+intent: 011-vscode-extension
+status: complete
+implemented: true
+priority: must
+created: 2025-12-26
+---
+
+# Story: Remove Duplicate Webview Files
+
+## User Story
+
+**As a** developer
+**I want** a single source of truth for webview code
+**So that** I don't get confused about which file to edit
+
+## Problem
+
+Currently there are duplicate files causing confusion:
+
+```
+src/
+├── sidebar/
+│   ├── styles.ts           # 1607 lines - NOT USED
+│   ├── webviewContent.ts   # 701 lines - NOT USED (legacy)
+│   └── webviewProvider.ts  # Uses ../webview/
+└── webview/
+    ├── index.ts            # Main entry - USED
+    ├── html.ts             # HTML generation - USED
+    ├── scripts.ts          # JavaScript - USED
+    └── styles.ts           # 1141 lines - USED
+```
+
+## Acceptance Criteria
+
+- [ ] **Given** duplicate files exist, **When** cleanup runs, **Then** unused files are removed
+- [ ] **Given** single webview module, **When** developer edits, **Then** only one location exists
+- [ ] **Given** tests reference old files, **When** tests run, **Then** all tests pass with new structure
+- [ ] **Given** imports updated, **When** compiled, **Then** no dead code warnings
+
+## Technical Implementation
+
+### 1. Remove Unused Files
+```bash
+rm src/sidebar/styles.ts
+rm src/sidebar/webviewContent.ts
+```
+
+### 2. Update Any Stale Imports
+Search for any remaining references to removed files.
+
+### 3. Consolidate Test Files
+Move/update `src/test/sidebar/webviewContent.test.ts` if it exists.
+
+### 4. Final Structure
+```
+src/
+├── sidebar/
+│   ├── webviewProvider.ts   # WebviewViewProvider
+│   ├── webviewMessaging.ts  # Message types
+│   ├── treeProvider.ts      # TreeView (if used)
+│   └── index.ts             # Exports
+└── webview/
+    ├── index.ts             # Main entry
+    ├── html.ts              # HTML generation
+    ├── scripts.ts           # JavaScript
+    └── styles.ts            # CSS
+```
+
+## Files to Delete
+
+- `src/sidebar/styles.ts`
+- `src/sidebar/webviewContent.ts`
+
+## Files to Update
+
+- Any test files referencing deleted files
+- Any imports referencing deleted files
+
+## Testing
+
+- `npm run compile` - No errors
+- `npm test` - All tests pass
+- Manual: Extension loads correctly
+
+## Dependencies
+
+### Requires
+- 020-fix-infinite-rerender (ensure working baseline)
+
+### Enables
+- 022-setup-esbuild (clean codebase)

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/webview-lit-migration/stories/022-setup-esbuild.md

@@ -0,0 +1,156 @@
+---
+id: vscode-extension-story-wlm-022
+unit: webview-lit-migration
+intent: 011-vscode-extension
+status: complete
+implemented: true
+priority: must
+created: 2025-12-26
+---
+
+# Story: Setup esbuild for Webview Bundling
+
+## User Story
+
+**As a** developer
+**I want** a fast bundler for webview code
+**So that** I can use npm packages (Lit) and have fast rebuilds
+
+## Problem
+
+Currently, webview code is:
+- Inline template strings (no npm packages possible)
+- No source maps for debugging
+- No tree-shaking for bundle size
+- No hot reload during development
+
+## Acceptance Criteria
+
+- [ ] **Given** webview source files, **When** build runs, **Then** single bundle.js created
+- [ ] **Given** Lit dependency added, **When** bundled, **Then** included in output
+- [ ] **Given** development mode, **When** file changes, **Then** rebuild < 100ms
+- [ ] **Given** production build, **When** bundled, **Then** minified and tree-shaken
+- [ ] **Given** bundle output, **When** loaded in webview, **Then** CSP compatible
+
+## Technical Implementation
+
+### 1. Install Dependencies
+```bash
+npm install -D esbuild
+npm install lit
+```
+
+### 2. Create esbuild Config
+```javascript
+// esbuild.webview.mjs
+import * as esbuild from 'esbuild';
+
+const production = process.argv.includes('--production');
+const watch = process.argv.includes('--watch');
+
+const ctx = await esbuild.context({
+    entryPoints: ['src/webview/index.ts'],
+    bundle: true,
+    outfile: 'dist/webview/bundle.js',
+    format: 'iife',
+    platform: 'browser',
+    target: 'es2020',
+    minify: production,
+    sourcemap: !production,
+    define: {
+        'process.env.NODE_ENV': production ? '"production"' : '"development"'
+    }
+});
+
+if (watch) {
+    await ctx.watch();
+    console.log('Watching webview...');
+} else {
+    await ctx.rebuild();
+    await ctx.dispose();
+}
+```
+
+### 3. Update package.json Scripts
+```json
+{
+  "scripts": {
+    "compile": "tsc -p ./ && node esbuild.webview.mjs",
+    "watch": "npm-run-all -p watch:*",
+    "watch:tsc": "tsc -watch -p ./",
+    "watch:webview": "node esbuild.webview.mjs --watch",
+    "vscode:prepublish": "npm run compile -- --production"
+  }
+}
+```
+
+### 4. Update Webview Provider to Load Bundle
+```typescript
+// webviewProvider.ts
+private _getWebviewContent(webview: vscode.Webview): string {
+    const bundleUri = webview.asWebviewUri(
+        vscode.Uri.joinPath(this._context.extensionUri, 'dist', 'webview', 'bundle.js')
+    );
+
+    return `<!DOCTYPE html>
+    <html>
+    <head>
+        <meta charset="UTF-8">
+        <meta http-equiv="Content-Security-Policy"
+              content="default-src 'none'; script-src ${webview.cspSource}; style-src ${webview.cspSource} 'unsafe-inline';">
+    </head>
+    <body>
+        <irismd-app></irismd-app>
+        <script src="${bundleUri}"></script>
+    </body>
+    </html>`;
+}
+```
+
+### 5. Update .vscodeignore
+```
+# Don't package source, only dist
+src/**
+!dist/**
+```
+
+## Project Structure After
+```
+vs-code-extension/
+├── src/
+│   ├── extension.ts
+│   ├── webview/
+│   │   ├── index.ts          # Entry point
+│   │   └── components/       # Lit components
+│   └── ...
+├── dist/
+│   ├── extension.js          # Compiled extension
+│   └── webview/
+│       └── bundle.js         # Bundled webview
+├── esbuild.webview.mjs
+└── package.json
+```
+
+## Files to Create
+
+- `esbuild.webview.mjs` - Build configuration
+
+## Files to Modify
+
+- `package.json` - Add scripts and dependencies
+- `.vscodeignore` - Exclude src, include dist
+- `src/sidebar/webviewProvider.ts` - Load bundle
+
+## Testing
+
+- `npm run compile` - Creates dist/webview/bundle.js
+- `npm run watch` - Watch mode works
+- Manual: Bundle loads in webview without CSP errors
+
+## Dependencies
+
+### Requires
+- 021-remove-duplicate-files
+
+### Enables
+- 023-lit-scaffold