project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/001-tree-data-provider.md

@@ -0,0 +1,55 @@
+---
+id: vscode-extension-story-sp-001
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-25
+assigned_bolt: bolt-sidebar-provider-1
+implemented: true
+---
+
+# Story: Tree Data Provider Setup
+
+## User Story
+
+**As a** VS Code user
+**I want** a tree view in the sidebar
+**So that** I can see my memory-bank artifacts organized hierarchically
+
+## Acceptance Criteria
+
+- [ ] **Given** extension activates, **When** TreeDataProvider is registered, **Then** sidebar shows tree view
+- [ ] **Given** TreeDataProvider, **When** getTreeItem() is called with a node, **Then** return properly configured TreeItem
+- [ ] **Given** TreeDataProvider, **When** getChildren() is called with null, **Then** return root sections (Intents, Bolts, Standards)
+- [ ] **Given** TreeDataProvider, **When** onDidChangeTreeData fires, **Then** tree view refreshes
+- [ ] **Given** TreeDataProvider, **When** refresh() is called, **Then** onDidChangeTreeData event is emitted
+
+## Technical Notes
+
+- Implement vscode.TreeDataProvider<TreeNode>
+- Use vscode.EventEmitter for onDidChangeTreeData
+- Root sections are: "Intents", "Bolts", "Standards"
+- Each section is collapsible
+
+## Dependencies
+
+### Requires
+- artifact-parser (for data)
+
+### Enables
+- 002-intent-unit-story-tree
+- 003-bolt-tree
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| No artifacts | Show empty sections |
+| Very long tree | VS Code handles virtualization |
+| Rapid refresh calls | Debounced by file-watcher |
+
+## Out of Scope
+
+- Custom tree item rendering
+- Drag and drop

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/002-intent-unit-story-tree.md

@@ -0,0 +1,56 @@
+---
+id: vscode-extension-story-sp-002
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-25
+assigned_bolt: bolt-sidebar-provider-1
+implemented: true
+---
+
+# Story: Intent/Unit/Story Tree
+
+## User Story
+
+**As a** developer
+**I want** to see intents, units, and stories in a nested tree structure
+**So that** I can navigate my project's feature hierarchy
+
+## Acceptance Criteria
+
+- [ ] **Given** Intents section expanded, **When** getChildren() called, **Then** return all intents sorted by number prefix (001, 002...)
+- [ ] **Given** an Intent node, **When** getChildren() called, **Then** return its units
+- [ ] **Given** a Unit node, **When** getChildren() called, **Then** return its stories
+- [ ] **Given** an Intent, **When** rendered as TreeItem, **Then** show format "{number}-{name}" with status icon
+- [ ] **Given** a Unit, **When** rendered as TreeItem, **Then** show name with completion status icon
+- [ ] **Given** a Story, **When** rendered as TreeItem, **Then** show "{number}-{title}" with status icon
+
+## Technical Notes
+
+- Intent collapsibleState: Collapsed by default
+- Unit collapsibleState: Collapsed by default
+- Story collapsibleState: None (leaf node)
+- Sort intents by numeric prefix extraction
+
+## Dependencies
+
+### Requires
+- 001-tree-data-provider
+- artifact-parser/003-artifact-parsing
+
+### Enables
+- User navigation
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Intent with no units | Show intent, empty when expanded |
+| Unit with no stories | Show unit, empty when expanded |
+| 100+ intents | All rendered (virtualized by VS Code) |
+
+## Out of Scope
+
+- Filtering intents
+- Search within tree

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/003-bolt-tree.md

@@ -0,0 +1,56 @@
+---
+id: vscode-extension-story-sp-003
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-25
+assigned_bolt: bolt-sidebar-provider-2
+implemented: true
+---
+
+# Story: Bolt Tree with Stages and Stories
+
+## User Story
+
+**As a** developer
+**I want** to see bolts with their stages and stories
+**So that** I can track construction progress at a glance
+
+## Acceptance Criteria
+
+- [ ] **Given** Bolts section expanded, **When** getChildren() called, **Then** return bolts sorted by in-progress first, then by number
+- [ ] **Given** a Bolt node, **When** rendered as TreeItem, **Then** show "{name} [{type}] Stage: {currentStage}" with status icon
+- [ ] **Given** a Bolt node expanded, **When** getChildren() called, **Then** return "Stages" and "Stories" section nodes
+- [ ] **Given** Stages section expanded, **When** getChildren() called, **Then** return all bolt stages with individual status icons
+- [ ] **Given** Stories section expanded, **When** getChildren() called, **Then** return stories assigned to this bolt
+- [ ] **Given** bolt type "ddd-construction-bolt", **When** rendered, **Then** show badge "DDD"
+- [ ] **Given** bolt type "simple-construction-bolt", **When** rendered, **Then** show badge "Simple"
+
+## Technical Notes
+
+- Bolt type badge can be shown in TreeItem.description
+- Stages and Stories sections should have different icons for visual differentiation
+- Current stage should be highlighted (different icon color)
+
+## Dependencies
+
+### Requires
+- 001-tree-data-provider
+- artifact-parser/003-artifact-parsing
+
+### Enables
+- Construction progress tracking
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Bolt with no stages | Show bolt, Stages section empty |
+| Bolt with no stories | Show bolt, Stories section empty |
+| All stages complete | Show all green checkmarks |
+
+## Out of Scope
+
+- Bolt execution from tree
+- Stage artifact viewing

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/004-status-icons.md

@@ -0,0 +1,55 @@
+---
+id: vscode-extension-story-sp-004
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-25
+assigned_bolt: bolt-sidebar-provider-2
+implemented: true
+---
+
+# Story: Status Icons and Badges
+
+## User Story
+
+**As a** developer
+**I want** to see visual status indicators on all artifacts
+**So that** I can quickly understand project progress
+
+## Acceptance Criteria
+
+- [ ] **Given** status Draft/Pending, **When** getStatusIcon() called, **Then** return gray circle icon
+- [ ] **Given** status InProgress, **When** getStatusIcon() called, **Then** return yellow spinner/loading icon
+- [ ] **Given** status Complete/Done, **When** getStatusIcon() called, **Then** return green checkmark icon
+- [ ] **Given** status Unknown (invalid frontmatter), **When** getStatusIcon() called, **Then** return yellow "?" icon
+- [ ] **Given** unknown status with "?" icon, **When** user hovers, **Then** tooltip shows "Invalid or missing status in frontmatter"
+- [ ] **Given** any TreeItem, **When** rendered, **Then** icon matches VS Code theme (light/dark)
+
+## Technical Notes
+
+- Use vscode.ThemeIcon for theme compatibility
+- Icons: $(circle-outline), $(sync~spin), $(check), $(question)
+- Colors: Use ThemeColor or codicon colors
+- Tooltip set via TreeItem.tooltip
+
+## Dependencies
+
+### Requires
+- artifact-parser/004-frontmatter-parser (for status)
+
+### Enables
+- Visual progress tracking
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Light theme | Icons visible and appropriate |
+| Dark theme | Icons visible and appropriate |
+| High contrast theme | Icons accessible |
+
+## Out of Scope
+
+- Custom icon images
+- Animated icons (VS Code limitation)

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/005-pixel-logo-footer.md

@@ -0,0 +1,55 @@
+---
+id: vscode-extension-story-sp-005
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: should
+created: 2025-12-25
+assigned_bolt: bolt-sidebar-provider-2
+implemented: true
+---
+
+# Story: Pixel Logo Footer
+
+## User Story
+
+**As a** developer
+**I want** to see the iris.md pixel logo at the bottom of the sidebar
+**So that** I have brand recognition and quick access to the website
+
+## Acceptance Criteria
+
+- [ ] **Given** tree view is rendered, **When** sidebar loads, **Then** pixel logo appears at bottom with fadeout effect
+- [ ] **Given** pixel logo is displayed, **When** user clicks it, **Then** iris.md website opens in browser
+- [ ] **Given** different tree heights, **When** sidebar renders, **Then** logo stays at bottom (sticky or after content)
+- [ ] **Given** light theme, **When** logo renders, **Then** logo is visible and looks good
+- [ ] **Given** dark theme, **When** logo renders, **Then** logo is visible and looks good
+
+## Technical Notes
+
+- May require WebviewView for custom rendering
+- Alternative: Use TreeView's `message` property or description
+- Logo file: bundled from `src/logo.png`
+- Use vscode.env.openExternal for website link
+- Fadeout effect via CSS gradient or opacity
+
+## Dependencies
+
+### Requires
+- 001-tree-data-provider
+
+### Enables
+- Brand presence, website access
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Very short tree | Logo still visible |
+| Very long tree | Logo at bottom, scrollable |
+| Sidebar resized narrow | Logo scales or hides gracefully |
+
+## Out of Scope
+
+- Animated logo
+- Different logos per theme

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/006-webview-tab-architecture.md

@@ -0,0 +1,62 @@
+---
+id: vscode-extension-story-sp-006
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-3
+implemented: true
+---
+
+# Story: Webview Tab Architecture
+
+## User Story
+
+**As a** user
+**I want** a tabbed sidebar with Bolts, Specs, and Overview views
+**So that** I can switch between different perspectives of my project
+
+## Acceptance Criteria
+
+- [ ] **Given** the sidebar is visible, **When** I look at it, **Then** I see three tabs: "Bolts", "Specs", "Overview"
+- [ ] **Given** the Bolts tab is active, **When** I click Specs tab, **Then** the Specs view is displayed
+- [ ] **Given** I'm on the Specs tab, **When** I restart VS Code, **Then** I'm still on the Specs tab
+- [ ] **Given** dark theme is active, **When** I view the sidebar, **Then** it uses VS Code dark theme colors
+- [ ] **Given** light theme is active, **When** I view the sidebar, **Then** it uses VS Code light theme colors
+- [ ] **Given** the sidebar, **When** I click the refresh icon, **Then** the current view refreshes
+
+## Technical Notes
+
+- Use WebviewViewProvider instead of TreeDataProvider
+- Tab state stored in `context.workspaceState`
+- Use VS Code CSS variables: `--vscode-sideBar-background`, `--vscode-editor-foreground`, etc.
+- Implement CSP headers for webview security
+- Use nonce for inline scripts
+- PostMessage API for webview ↔ extension communication
+
+## Dependencies
+
+### Requires
+- artifact-parser (for data)
+- file-watcher (for refresh events)
+
+### Enables
+- 007-command-center-bolts-tab
+- Specs tab rendering
+- Overview tab rendering
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Webview disposed and recreated | Restore previous tab state |
+| Invalid stored tab value | Default to Bolts tab |
+| Theme changed while open | Update immediately |
+| Extension deactivated | Clean up resources |
+
+## Out of Scope
+
+- Custom tab icons (use text/emoji for now)
+- Tab reordering
+- Tab hiding/showing

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/007-command-center-bolts-tab.md

@@ -0,0 +1,65 @@
+---
+id: vscode-extension-story-sp-007
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-3
+implemented: true
+---
+
+# Story: Command Center (Bolts Tab)
+
+## User Story
+
+**As a** user
+**I want** a command center view showing my current bolt work
+**So that** I can see my progress and what's coming next at a glance
+
+## Acceptance Criteria
+
+- [ ] **Given** the Bolts tab is active, **When** I view it, **Then** I see "Current Intent" header with intent name
+- [ ] **Given** there are bolts, **When** I view Current Intent, **Then** I see statistics: X Active, Y Queued, Z Done
+- [ ] **Given** an active bolt exists, **When** I view the tab, **Then** I see "Current Focus" section with the active bolt
+- [ ] **Given** pending bolts exist, **When** I view the tab, **Then** I see "Up Next" queue section
+- [ ] **Given** activity events exist, **When** I view the tab, **Then** I see "Recent Activity" section
+- [ ] **Given** no active bolt, **When** I view the tab, **Then** Current Focus shows empty state message
+
+## Technical Notes
+
+- Layout structure:
+  ```
+  ┌─ Current Intent header ─┐
+  ├─ Current Focus section ─┤
+  ├─ Up Next queue ─────────┤
+  ├─ Activity section ──────┤
+  ```
+- Current Intent shows: intent name, bolt counts by status
+- Use CSS Grid or Flexbox for responsive layout
+- Activity section at bottom, takes remaining space
+
+## Dependencies
+
+### Requires
+- 006-webview-tab-architecture
+- artifact-parser (bolt data)
+
+### Enables
+- 008-current-focus-card
+- 009-up-next-queue
+- 010-activity-feed-ui
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| No intents | Show "No intents found" message |
+| No bolts at all | Show empty state with guidance |
+| Multiple active bolts | Show first one (shouldn't happen normally) |
+| All bolts complete | Celebration/completion message |
+
+## Out of Scope
+
+- Intent switching (always shows current/first intent)
+- Creating new bolts from UI

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/008-current-focus-card.md

@@ -0,0 +1,62 @@
+---
+id: vscode-extension-story-sp-008
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-4
+implemented: true
+---
+
+# Story: Current Focus Card
+
+## User Story
+
+**As a** user
+**I want** an expandable card showing my active bolt's detailed progress
+**So that** I can see exactly where I am in the current work
+
+## Acceptance Criteria
+
+- [ ] **Given** an active bolt, **When** I view Current Focus, **Then** I see bolt name and type badge
+- [ ] **Given** the focus card header, **When** I view it, **Then** I see current stage name and "In Progress" badge
+- [ ] **Given** I click the focus card header, **When** expanded, **Then** I see detailed progress content
+- [ ] **Given** the card is expanded, **When** I view it, **Then** I see a progress ring with percentage
+- [ ] **Given** the card is expanded, **When** I view it, **Then** I see stage pipeline (M-D-A-I-T or P-I-T)
+- [ ] **Given** the stage pipeline, **When** I view it, **Then** complete stages show ✓, active shows highlight, pending shows ○
+- [ ] **Given** the card is expanded, **When** I view it, **Then** I see stories checklist with completion status
+- [ ] **Given** the card is expanded, **When** I view it, **Then** I see "Continue" and "Files" action buttons
+- [ ] **Given** I click "Continue", **When** clicked, **Then** it shows a toast "Opening workspace..."
+
+## Technical Notes
+
+- Progress ring: SVG circle with stroke-dasharray animation
+- Stage pipeline: DDD = Model, Design, ADR, Implement, Test; Simple = Plan, Implement, Test
+- Expand/collapse state persisted in workspaceState
+- Stories show checkbox icon (checked for complete)
+- Buttons use VS Code button styling
+
+## Dependencies
+
+### Requires
+- 007-command-center-bolts-tab
+- artifact-parser (bolt with stages, stories)
+
+### Enables
+- User can see detailed bolt progress
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Bolt with no stories | Hide stories section |
+| All stages complete | Show 100% progress, all ✓ |
+| Unknown bolt type | Show stages as-is from frontmatter |
+| Long bolt name | Truncate with ellipsis |
+
+## Out of Scope
+
+- Actually opening files (button is placeholder)
+- Editing bolt from card
+- Stage advancement from UI

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/009-up-next-queue.md

@@ -0,0 +1,61 @@
+---
+id: vscode-extension-story-sp-009
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-4
+implemented: true
+---
+
+# Story: Up Next Queue with Dependencies
+
+## User Story
+
+**As a** user
+**I want** to see pending bolts ordered by what I can work on next
+**So that** I know which bolt to pick up when I finish my current work
+
+## Acceptance Criteria
+
+- [ ] **Given** pending bolts exist, **When** I view Up Next, **Then** I see a count badge "X bolts"
+- [ ] **Given** pending bolts, **When** I view the queue, **Then** unblocked bolts appear first
+- [ ] **Given** multiple unblocked bolts, **When** I view the queue, **Then** they're ordered by unblocksCount (highest first)
+- [ ] **Given** a blocked bolt, **When** I view it in queue, **Then** it shows 🔒 icon
+- [ ] **Given** a blocked bolt, **When** I view it, **Then** I see "Waiting: bolt-x, bolt-y" text
+- [ ] **Given** an unblocked bolt, **When** I view it, **Then** I see priority number (1, 2, 3...)
+- [ ] **Given** a queue item, **When** I view it, **Then** I see bolt name and stage indicators
+- [ ] **Given** I click a queue item, **When** clicked, **Then** it shows toast "Starting bolt..."
+
+## Technical Notes
+
+- Queue ordering logic from artifact-parser `getUpNextBolts()`
+- Blocked bolts show: lock icon, "Waiting: {blockedBy.join(', ')}"
+- Unblocked bolts show: priority number, "Enables: X bolts" if unblocksCount > 0
+- Stage indicators: small squares showing DDD stages or Simple stages
+- Max display: 5 items, with "Show more" if needed
+
+## Dependencies
+
+### Requires
+- 007-command-center-bolts-tab
+- artifact-parser/005-bolt-dependencies (isBlocked, blockedBy, unblocksCount)
+
+### Enables
+- User can see prioritized work queue
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| No pending bolts | Show "Queue empty" message |
+| All pending bolts blocked | Show all with lock icons |
+| Bolt blocks itself (circular) | Show as blocked |
+| Many pending bolts | Show first 5, "Show more" link |
+
+## Out of Scope
+
+- Starting bolts from queue
+- Reordering queue manually
+- Filtering queue

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/010-activity-feed-ui.md

@@ -0,0 +1,63 @@
+---
+id: vscode-extension-story-sp-010
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-4
+implemented: true
+---
+
+# Story: Activity Feed UI
+
+## User Story
+
+**As a** user
+**I want** to see recent activity in my project
+**So that** I can track what's been happening and when
+
+## Acceptance Criteria
+
+- [ ] **Given** activity events exist, **When** I view Recent Activity, **Then** I see a list of events
+- [ ] **Given** an activity item, **When** I view it, **Then** I see: icon, description, target, tag, relative time
+- [ ] **Given** filter buttons (All, Stages, Bolts), **When** I click "Stages", **Then** only stage events show
+- [ ] **Given** the activity section, **When** I drag the resize handle up, **Then** the section grows
+- [ ] **Given** I resize the activity section, **When** I restart VS Code, **Then** the height is preserved
+- [ ] **Given** a stage-complete event, **When** I view it, **Then** it shows ✓ icon with green styling
+- [ ] **Given** a bolt-start event, **When** I view it, **Then** it shows ▶ icon with blue styling
+- [ ] **Given** an event from 2 hours ago, **When** I view it, **Then** time shows "2h ago"
+
+## Technical Notes
+
+- Activity data from artifact-parser `buildActivityFeed()`
+- Filter state stored in component state (not persisted)
+- Resize handle: CSS `cursor: ns-resize`, mouse events for drag
+- Height persisted in workspaceState, min 120px, max 500px
+- Relative time: Just now, Xm ago, Xh ago, Yesterday, Xd ago
+- Icon classes: `stage-complete`, `bolt-start`, `bolt-complete`, `bolt-created`
+
+## Dependencies
+
+### Requires
+- 007-command-center-bolts-tab
+- artifact-parser/006-activity-feed-derivation
+
+### Enables
+- User can track project activity
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| No activity events | Show "No activity" message |
+| Filter shows no results | Show "No matching activity" |
+| Very old events | Show date instead of relative |
+| Resize below minimum | Clamp to 120px |
+| Resize above maximum | Clamp to 500px |
+
+## Out of Scope
+
+- Clicking activity to navigate to bolt
+- Activity notifications
+- Real-time activity updates (only on refresh)

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/011-filewatcher-statestore-integration.md

@@ -0,0 +1,49 @@
+---
+id: vscode-extension-story-sp-011
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-5
+implemented: true
+---
+
+# Story: FileWatcher → StateStore Integration
+
+## User Story
+
+**As a** extension user
+**I want** the StateStore to automatically update when files change
+**So that** the UI reflects the latest memory-bank state without manual refresh
+
+## Acceptance Criteria
+
+- [x] **Given** FileWatcher detects a markdown file change, **When** the change event fires, **Then** StateStore.loadFromModel() is called with fresh parsed data
+- [x] **Given** multiple rapid file changes, **When** debounce period completes, **Then** only one StateStore update occurs
+- [x] **Given** StateStore is updated, **When** subscribers are notified, **Then** WebviewProvider refreshes the UI
+- [x] **Given** extension deactivates, **When** cleanup runs, **Then** both FileWatcher and StateStore subscriptions are disposed
+
+## Technical Notes
+
+- Connect FileWatcher.onChange → scanMemoryBank → StateStore.loadFromModel
+- Ensure debounce is applied before StateStore update (already in FileWatcher)
+- StateStore already has subscriber notification built-in
+- Use single source of truth pattern (FileWatcher is only write path to StateStore)
+
+## Dependencies
+
+### Requires
+- file-watcher unit (FileWatcher class)
+- state module (StateStore)
+
+### Enables
+- Real-time UI updates on file changes
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Parse error on file change | Log error, keep previous state |
+| Rapid saves (IDE auto-save) | Single update after debounce |
+| Webview not visible | StateStore updates, webview updates on show |