project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/012-next-actions-ui.md

@@ -0,0 +1,57 @@
+---
+id: vscode-extension-story-sp-012
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-5
+implemented: true
+---
+
+# Story: Next Actions UI in Overview Tab
+
+## User Story
+
+**As a** extension user
+**I want** to see suggested next actions in the Overview tab
+**So that** I know what to work on next without analyzing bolts manually
+
+## Acceptance Criteria
+
+- [x] **Given** Overview tab is visible, **When** StateStore has computed nextActions, **Then** a "Suggested Actions" section displays
+- [x] **Given** next actions exist, **When** rendering the section, **Then** actions are sorted by priority (highest first)
+- [x] **Given** a next action, **When** displayed, **Then** it shows: icon, title, description, and target name if applicable
+- [x] **Given** action type is continue-bolt, **When** clicked, **Then** bolt details are shown
+- [x] **Given** action type is start-bolt, **When** clicked, **Then** bolt is highlighted in Bolts tab
+- [x] **Given** no next actions, **When** Overview renders, **Then** show "All caught up!" message
+
+## Technical Notes
+
+- Read from `state.computed.nextActions`
+- Action types: continue-bolt, start-bolt, complete-stage, unblock-bolt, create-bolt, celebrate
+- Icons: ▶ continue, + start, ✓ complete, 🔓 unblock, 📝 create, 🎉 celebrate
+- Clicking action sends message to extension for navigation
+
+## UI Design
+
+```
+┌─────────────────────────────────────┐
+│ 💡 SUGGESTED ACTIONS                │
+├─────────────────────────────────────┤
+│ ▶ Continue bolt-sidebar-provider-5  │
+│   Resume in-progress construction   │
+├─────────────────────────────────────┤
+│ + Start bolt-overview-ui-1          │
+│   Next unblocked bolt ready         │
+└─────────────────────────────────────┘
+```
+
+## Dependencies
+
+### Requires
+- state/selectors.ts (selectNextActions)
+- StateStore integration
+
+### Enables
+- Guided workflow experience

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

@@ -0,0 +1,72 @@
+---
+id: vscode-extension-story-sp-013
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: should
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-5
+implemented: true
+---
+
+# Story: Start Bolt Action
+
+## User Story
+
+**As a** extension user
+**I want** to start a bolt from the UI
+**So that** I can easily get the command to begin work on a bolt
+
+## Acceptance Criteria
+
+- [x] **Given** a draft bolt in Up Next queue, **When** "Start" button is clicked, **Then** a popup appears with the command to run
+- [x] **Given** popup is shown, **When** user clicks "Copy", **Then** the command is copied to clipboard
+- [x] **Given** bolt has dependencies, **When** dependencies are incomplete, **Then** Start button is disabled with tooltip "Blocked by: bolt-x"
+
+## Technical Notes
+
+**IMPORTANT**: We cannot programmatically modify markdown files. Instead, show a popup with the command to copy.
+
+- Webview sends `startBolt` message with boltId
+- Extension handler:
+  1. Show VS Code QuickPick or Information Message with the command
+  2. Command format: `/irismd-construction-agent --bolt-id="bolt-xxx"`
+  3. Provide "Copy to Clipboard" button
+- User runs the command manually in Claude Code to start the bolt
+
+## UI Flow
+
+```
+User clicks [Start ▶] on bolt-sidebar-provider-5
+    ↓
+VS Code popup appears:
+┌─────────────────────────────────────────────────┐
+│ Run this command to start the bolt:             │
+│                                                 │
+│ /irismd-construction-agent --bolt-id="..."     │
+│                                                 │
+│            [Copy to Clipboard]                  │
+└─────────────────────────────────────────────────┘
+```
+
+## Queue UI Design
+
+```
+┌─────────────────────────────────────┐
+│ UP NEXT                     2 bolts │
+├─────────────────────────────────────┤
+│ bolt-overview-ui-1     [Start ▶]    │
+│ Simple • 3 stories                  │
+├─────────────────────────────────────┤
+│ bolt-deploy-1          [Blocked]    │
+│ Blocked by: bolt-overview-ui-1      │
+└─────────────────────────────────────┘
+```
+
+## Dependencies
+
+### Requires
+- StateStore (to get bolt data for command generation)
+
+### Enables
+- Guided workflow experience

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/014-intent-selection-strategies.md

@@ -0,0 +1,54 @@
+---
+id: vscode-extension-story-sp-014
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: could
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-5
+implemented: true
+---
+
+# Story: Additional Intent Selection Strategies
+
+## User Story
+
+**As a** extension user
+**I want** the current intent to be selected intelligently
+**So that** the most relevant work is always shown
+
+## Acceptance Criteria
+
+- [ ] **Given** multiple intents exist, **When** one has an in-progress bolt, **Then** that intent is selected as current
+- [ ] **Given** no in-progress bolts, **When** one intent has most recent activity, **Then** that intent is selected
+- [ ] **Given** no recent activity, **When** one intent has most in-progress stories, **Then** that intent is selected
+- [ ] **Given** completion percentage differs, **When** selecting current intent, **Then** intent with lowest completion (most work remaining) is preferred
+- [ ] **Given** user clicks an intent, **When** intent is clicked, **Then** that intent becomes current (manual override)
+
+## Technical Notes
+
+Existing strategies (already implemented):
+1. `selectIntentByActiveBolt` - Intent with in-progress bolt
+2. `selectIntentByRecentActivity` - Intent with most recent bolt timestamp
+3. `selectIntentByInProgressStories` - Intent with most in-progress stories
+
+New strategies to add:
+4. `selectIntentByCompletion` - Intent with lowest completion percentage
+5. Manual selection via UI click (store in UIState.selectedIntentId)
+
+Priority order:
+1. Manual selection (if set)
+2. Active bolt
+3. Recent activity
+4. In-progress stories
+5. Lowest completion
+6. First intent (fallback)
+
+## Dependencies
+
+### Requires
+- state/selectors.ts (existing strategies)
+- StateStore (UIState for manual selection)
+
+### Enables
+- More intelligent intent focus

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/015-persist-expanded-state.md

@@ -0,0 +1,56 @@
+---
+id: vscode-extension-story-sp-015
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: in-progress
+priority: should
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-5
+implemented: partial
+---
+
+# Story: Persist Expanded State
+
+## User Story
+
+**As a** extension user
+**I want** my expanded/collapsed nodes to persist across sessions
+**So that** I don't have to re-expand my preferred view each time
+
+## Acceptance Criteria
+
+- [ ] **Given** user expands an intent node, **When** session ends and restarts, **Then** that intent is still expanded
+- [ ] **Given** user expands a unit node, **When** session ends and restarts, **Then** that unit is still expanded
+- [ ] **Given** user collapses Focus Card, **When** session ends and restarts, **Then** Focus Card is still collapsed
+- [ ] **Given** persisted state references deleted node, **When** loading, **Then** that entry is ignored (no error)
+
+## Technical Notes
+
+Storage keys in workspaceState:
+- `irismd.expandedIntents` - Set<string> of intent IDs
+- `irismd.expandedUnits` - Set<string> of unit IDs
+- `irismd.focusCardExpanded` - boolean (already exists)
+
+Operations:
+- On expand: Add ID to set, persist to workspaceState
+- On collapse: Remove ID from set, persist to workspaceState
+- On load: Restore sets from workspaceState, apply to UIState
+
+UIState additions:
+```typescript
+interface UIState {
+  expandedIntents: Set<string>;
+  expandedUnits: Set<string>;
+  focusCardExpanded: boolean;
+  // ... existing fields
+}
+```
+
+## Dependencies
+
+### Requires
+- VS Code workspaceState API
+- StateStore UIState
+
+### Enables
+- Better user experience with persistent view preferences

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

@@ -0,0 +1,72 @@
+---
+id: vscode-extension-story-sp-016
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: draft
+priority: should
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-5
+implemented: false
+---
+
+# Story: Bolt Filtering
+
+## User Story
+
+**As a** extension user
+**I want** to filter bolts by intent, status, or type
+**So that** I can focus on specific bolts in a large project
+
+## Acceptance Criteria
+
+- [ ] **Given** Bolts tab is visible, **When** filter dropdown is clicked, **Then** filter options display
+- [ ] **Given** filter by intent, **When** intent is selected, **Then** only bolts for that intent show
+- [ ] **Given** filter by status, **When** status is selected, **Then** only bolts matching that status show
+- [ ] **Given** filter by type, **When** type is selected, **Then** only bolts of that type show
+- [ ] **Given** filters are applied, **When** "Clear filters" is clicked, **Then** all bolts show
+- [ ] **Given** filter is active, **When** session restarts, **Then** filter persists
+
+## Technical Notes
+
+Filter options:
+- **By Intent**: All | Intent-001 | Intent-002 | ...
+- **By Status**: All | In Progress | Draft | Complete | Blocked
+- **By Type**: All | DDD | Simple | ...
+
+Storage key: `irismd.boltFilters`
+
+UIState additions:
+```typescript
+interface BoltFilters {
+  intentId: string | null;
+  status: ArtifactStatus | null;
+  type: string | null;
+}
+
+interface UIState {
+  boltFilters: BoltFilters;
+  // ... existing fields
+}
+```
+
+UI Design:
+```
+┌─────────────────────────────────────┐
+│ 🎯 CURRENT FOCUS      [Filter ▼]   │
+│                       ┌───────────┐ │
+│                       │ Intent ▸  │ │
+│                       │ Status ▸  │ │
+│                       │ Type   ▸  │ │
+│                       │───────────│ │
+│                       │ Clear All │ │
+│                       └───────────┘ │
+```
+
+## Dependencies
+
+### Requires
+- StateStore UIState
+- VS Code workspaceState (persistence)
+
+### Enables
+- Better bolt management in large projects

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/017-activity-open-button.md

@@ -0,0 +1,50 @@
+---
+id: vscode-extension-story-sp-017
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: should
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-5
+implemented: true
+---
+
+# Story: Activity Open Button
+
+## User Story
+
+**As a** extension user
+**I want** to open the relevant file from an activity event
+**So that** I can quickly navigate to the bolt that changed
+
+## Acceptance Criteria
+
+- [x] **Given** an activity event in Recent Activity, **When** rendered, **Then** an open file icon button is displayed
+- [x] **Given** user clicks the open button, **When** bolt path is known, **Then** the bolt.md file opens in VS Code editor
+- [x] **Given** user clicks anywhere on the activity item, **When** bolt path is known, **Then** the bolt.md file opens in VS Code editor
+- [x] **Given** bolt path is not available, **When** rendering, **Then** no open button is shown
+
+## Technical Notes
+
+- Added `path` field to `ActivityEventData` interface in `webviewMessaging.ts`
+- WebviewProvider looks up bolt path from StateStore when building activity events
+- HTML renders open button (📂) with `data-path` attribute
+- Click handler sends `openArtifact` message to extension
+- Extension handler opens the file using VS Code API
+
+## Implementation Details
+
+**Files Modified:**
+- `src/sidebar/webviewMessaging.ts` - Added `path?: string` to `ActivityEventData`
+- `src/sidebar/webviewProvider.ts` - Look up bolt path from state when transforming activity events
+- `src/webview/html.ts` - Added open button to activity item HTML
+- `src/webview/scripts.ts` - Added click handlers for open button and activity item
+- `src/sidebar/styles.ts` - Added `.activity-open-btn` styles
+
+## Dependencies
+
+### Requires
+- StateStore (to get bolt path)
+
+### Enables
+- Quick navigation to bolt files from activity feed

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/018-specs-view.md

@@ -0,0 +1,63 @@
+---
+id: vscode-extension-story-sp-018
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-5
+implemented: true
+---
+
+# Story: Specs View Implementation
+
+## User Story
+
+**As a** extension user
+**I want** to see all intents, units, and stories in a hierarchical tree view
+**So that** I can navigate the project specification structure
+
+## Acceptance Criteria
+
+- [x] **Given** Specs tab is selected, **When** intents exist, **Then** display hierarchical tree: Intent > Unit > Story
+- [x] **Given** an intent in the tree, **When** rendered, **Then** show intent number, name, unit count, story count, and progress ring
+- [x] **Given** a unit in the tree, **When** rendered, **Then** show unit name, status indicator, and story progress (X/Y)
+- [x] **Given** a story in the tree, **When** rendered, **Then** show story ID, title, and status indicator
+- [x] **Given** intent/unit header, **When** clicked, **Then** expand/collapse the children
+- [x] **Given** story item, **When** clicked, **Then** open the story markdown file in editor
+- [x] **Given** filter dropdown, **When** changed, **Then** filter visible items by status
+- [x] **Given** no intents exist, **When** Specs tab shown, **Then** display empty state message
+
+## Technical Notes
+
+**Files:**
+- `src/webview/html.ts` - `getSpecsViewHtml()` function generates the HTML
+- `src/webview/scripts.ts` - Click handlers for intent/unit expand, story click
+- `src/sidebar/styles.ts` - CSS for `.specs-toolbar`, `.intent-*`, `.unit-*`, `.spec-story-*`
+
+**UI Structure:**
+```
+┌─────────────────────────────────────┐
+│ Filter: [All Status ▼]              │
+├─────────────────────────────────────┤
+│ ▼ 📋 011-vscode-extension    [75%]  │
+│   ▼ ○ extension-core         2/4    │
+│     ● 001-Extension Activation      │
+│     ✓ 002-Project Detection         │
+│   ▼ ✓ sidebar-provider       4/4    │
+│     ✓ 001-Tree Data Provider        │
+└─────────────────────────────────────┘
+```
+
+**Progress Ring:**
+- SVG circle with stroke-dashoffset for progress
+- Circumference = 2πr = 69.115 (r=11)
+- Shows percentage text in center
+
+## Dependencies
+
+### Requires
+- WebviewData.intents populated from StateStore
+
+### Enables
+- Navigate project specs without leaving sidebar

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/sidebar-provider/stories/019-overview-view.md

@@ -0,0 +1,84 @@
+---
+id: vscode-extension-story-sp-019
+unit: sidebar-provider
+intent: 011-vscode-extension
+status: complete
+priority: must
+created: 2025-12-26
+assigned_bolt: bolt-sidebar-provider-5
+implemented: true
+---
+
+# Story: Overview View Implementation
+
+## User Story
+
+**As a** extension user
+**I want** to see project progress metrics, suggested actions, and quick links
+**So that** I can understand overall project status and take action
+
+## Acceptance Criteria
+
+- [x] **Given** Overview tab is selected, **When** rendered, **Then** display overall progress bar and percentage
+- [x] **Given** Overview tab is selected, **When** rendered, **Then** display 4 metric cards (Complete %, Stories Done, Bolts Done, Intents)
+- [x] **Given** next actions are computed, **When** rendered, **Then** display Suggested Actions section with up to 3 actions
+- [x] **Given** no actions are available, **When** Suggested Actions shown, **Then** display "All caught up!" message
+- [x] **Given** intents exist, **When** Overview shown, **Then** list intents with progress percentages
+- [x] **Given** standards exist, **When** Overview shown, **Then** list standards with file icons
+- [x] **Given** Resources section, **When** rendered, **Then** show iris.md website link that opens external URL
+
+## Technical Notes
+
+**Files:**
+- `src/webview/html.ts` - `getOverviewViewHtml()` function generates the HTML
+- `src/webview/scripts.ts` - Click handlers for intent navigation, action execution, website link
+- `src/sidebar/styles.ts` - CSS for `.overview-*` classes
+
+**UI Structure:**
+```
+┌─────────────────────────────────────┐
+│ OVERALL PROGRESS                    │
+│ [████████████░░░░░░░░] 64%          │
+│                                     │
+│ ┌─────────┐  ┌─────────┐           │
+│ │   64%   │  │   5/8   │           │
+│ │Complete │  │ Stories │           │
+│ └─────────┘  └─────────┘           │
+│ ┌─────────┐  ┌─────────┐           │
+│ │   3/5   │  │    1    │           │
+│ │  Bolts  │  │ Intents │           │
+│ └─────────┘  └─────────┘           │
+├─────────────────────────────────────┤
+│ SUGGESTED ACTIONS                   │
+│ ▶ Continue bolt-sidebar-provider-5  │
+│ + Start next queued bolt            │
+├─────────────────────────────────────┤
+│ INTENTS                             │
+│ 📋 011-vscode-extension       75%   │
+├─────────────────────────────────────┤
+│ STANDARDS                           │
+│ 📄 tech-stack                       │
+│ 📄 coding-standards                 │
+├─────────────────────────────────────┤
+│ RESOURCES                           │
+│ 🌐 iris.md - Visit our website     │
+└─────────────────────────────────────┘
+```
+
+**Suggested Actions Types:**
+- `continue-bolt`: Continue working on active bolt
+- `start-bolt`: Start next queued bolt
+- `complete-stage`: Mark current stage complete
+- `unblock-bolt`: Review blocked bolt dependencies
+- `create-bolt`: Create new bolt for unassigned stories
+- `celebrate`: All work complete!
+
+## Dependencies
+
+### Requires
+- WebviewData with computed nextActions from StateStore
+- Standards parsed from memory-bank
+
+### Enables
+- Quick navigation to project overview
+- Action-oriented workflow guidance