project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/extension-core/stories/003-file-operation-commands.md

@@ -0,0 +1,57 @@
+---
+id: vscode-extension-story-ec-003
+unit: extension-core
+intent: 011-vscode-extension
+status: draft
+priority: must
+created: 2025-12-25
+assigned_bolt: null
+implemented: false
+---
+
+# Story: File Operations Commands
+
+## User Story
+
+**As a** developer browsing the tree
+**I want** to open, reveal, and copy paths of artifacts
+**So that** I can work with files efficiently
+
+## Acceptance Criteria
+
+- [ ] **Given** a tree item, **When** single-clicked, **Then** item is selected (highlighted)
+- [ ] **Given** a tree item (file), **When** double-clicked, **Then** file opens in VS Code default editor
+- [ ] **Given** a tree item, **When** right-click context menu, **Then** "Reveal in Explorer" option appears
+- [ ] **Given** "Reveal in Explorer" clicked, **When** command executes, **Then** file is shown in OS file explorer
+- [ ] **Given** a tree item, **When** right-click context menu, **Then** "Copy Path" option appears
+- [ ] **Given** "Copy Path" clicked, **When** command executes, **Then** file path is copied to clipboard
+
+## Technical Notes
+
+- Double-click: use TreeItem.command to open file
+- Use vscode.commands.executeCommand('revealFileInOS', uri) for reveal
+- Use vscode.env.clipboard.writeText(path) for copy
+- Context menu via contributes.menus["view/item/context"]
+
+## Dependencies
+
+### Requires
+- 002-command-registration
+- sidebar-provider (provides tree items)
+
+### Enables
+- Complete file interaction
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| File deleted before open | Show error "File not found" |
+| Non-file item (section header) | Context menu hidden or disabled |
+| Path with special characters | Properly escaped |
+
+## Out of Scope
+
+- Delete file from tree
+- Rename file from tree
+- Create new file from tree

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

@@ -0,0 +1,224 @@
+---
+unit: extension-core
+intent: 011-vscode-extension
+phase: construction
+status: complete
+created: 2025-12-25
+updated: 2025-12-26
+default_bolt_type: simple-construction-bolt
+---
+
+# Unit Brief: Extension Core
+
+## Purpose
+
+Extension entry point, lifecycle management, command registration, and orchestration of all other units. This is the main module that VS Code loads and the coordinator for the extension's functionality.
+
+## Scope
+
+### In Scope
+
+- Extension activation (activate function)
+- Extension deactivation (deactivate function)
+- Register TreeDataProvider with VS Code
+- Register all commands (refresh, reveal, copy path, etc.)
+- Coordinate initialization of other units
+- Register sidebar view container and view
+- Handle click events and route to appropriate handlers
+
+### Out of Scope
+
+- Tree rendering (handled by sidebar-provider)
+- File parsing (handled by artifact-parser)
+- File watching (handled by file-watcher)
+- Welcome view (handled by welcome-view)
+
+---
+
+## Assigned Requirements
+
+| FR | Requirement | Priority |
+|----|-------------|----------|
+| FR-1.1 | Provide sidebar view in VS Code activity bar | Must |
+| FR-1.3 | Sidebar titled "irismd" with favicon.png icon | Must |
+| FR-1.6 | Refresh icon button in title bar | Must |
+| FR-4.1 | Single-click selects item in tree | Must |
+| FR-4.2 | Double-click opens in default editor | Must |
+| FR-4.3 | No custom editors in Phase 1 | Must |
+| FR-4.4 | "Reveal in Explorer" context menu | Must |
+| FR-4.5 | "Copy Path" context menu | Must |
+
+---
+
+## Domain Concepts
+
+### Key Entities
+
+| Entity | Description | Attributes |
+|--------|-------------|------------|
+| ExtensionContext | VS Code extension context | subscriptions, extensionPath |
+| Command | Registered command | id, handler |
+| ViewContainer | Activity bar container | id, title, icon |
+| View | Sidebar view | id, name, provider |
+
+### Key Operations
+
+| Operation | Description | Inputs | Outputs |
+|-----------|-------------|--------|---------|
+| activate | Extension entry point | context | void |
+| deactivate | Extension cleanup | - | void |
+| registerCommands | Register all commands | context | void |
+| registerViews | Register sidebar views | context | void |
+| initializeUnits | Initialize all other units | - | void |
+| handleRefresh | Handle refresh command | - | void |
+| handleOpenFile | Handle file open on double-click | uri | void |
+| handleRevealInExplorer | Reveal file in explorer | uri | void |
+| handleCopyPath | Copy path to clipboard | uri | void |
+
+---
+
+## Story Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Stories | 3 |
+| Must Have | 3 |
+| Should Have | 0 |
+| Could Have | 0 |
+
+### Stories
+
+| Story ID | Title | Priority | Status |
+|----------|-------|----------|--------|
+| 001 | Extension Activation and View Registration | Must | Planned |
+| 002 | Command Registration | Must | Planned |
+| 003 | File Operations Commands | Must | Planned |
+
+---
+
+## Dependencies
+
+### Depends On
+
+| Unit | Reason |
+|------|--------|
+| artifact-parser | Initialize for project detection |
+| sidebar-provider | Register as TreeDataProvider |
+| file-watcher | Initialize and manage lifecycle |
+| welcome-view | Conditionally show based on project state |
+
+### Depended By
+
+| Unit | Reason |
+|------|--------|
+| None | This is the entry point |
+
+### External Dependencies
+
+| System | Purpose | Risk |
+|--------|---------|------|
+| VS Code Extension API | Core extension functionality | Low |
+| VS Code Commands API | Command registration | Low |
+| VS Code Window API | File operations | Low |
+
+---
+
+## Technical Context
+
+### Suggested Technology
+
+- vscode.ExtensionContext for lifecycle
+- vscode.commands.registerCommand for commands
+- vscode.window.createTreeView for sidebar
+- vscode.window.showTextDocument for file open
+- vscode.commands.executeCommand for reveal in explorer
+
+### Integration Points
+
+| Integration | Type | Protocol |
+|-------------|------|----------|
+| VS Code Extension API | API | activate/deactivate |
+| VS Code Commands | API | registerCommand |
+| VS Code TreeView | API | createTreeView |
+| All other units | Import | TypeScript |
+
+### Data Storage
+
+| Data | Type | Volume | Retention |
+|------|------|--------|-----------|
+| None | - | - | - |
+
+---
+
+## Constraints
+
+- Must export activate and deactivate functions
+- Must properly dispose all subscriptions
+- Must handle activation events correctly
+- package.json must declare all commands and views
+
+---
+
+## Success Criteria
+
+### Functional
+
+- [ ] Extension activates without errors
+- [ ] Sidebar appears in activity bar with correct icon
+- [ ] Refresh command triggers tree refresh
+- [ ] Double-click opens file in editor
+- [ ] "Reveal in Explorer" works
+- [ ] "Copy Path" copies to clipboard
+- [ ] Extension deactivates cleanly
+
+### Non-Functional
+
+- [ ] Activation time < 500ms
+- [ ] No memory leaks after deactivation
+- [ ] No errors in extension host
+
+### Quality
+
+- [ ] Integration tests for activation
+- [ ] Command tests
+- [ ] Code coverage > 80%
+
+---
+
+## Bolt Suggestions
+
+| Bolt | Type | Stories | Objective |
+|------|------|---------|-----------|
+| bolt-extension-core-1 | Simple | 001, 002, 003 | Complete extension core functionality |
+
+---
+
+## Notes
+
+- package.json contributions (to be created):
+```json
+{
+  "contributes": {
+    "viewsContainers": {
+      "activitybar": [{
+        "id": "irismd",
+        "title": "irismd",
+        "icon": "resources/favicon.png"
+      }]
+    },
+    "views": {
+      "irismd": [{
+        "id": "irismd.artifactTree",
+        "name": "Memory Bank"
+      }]
+    },
+    "commands": [
+      { "command": "irismd.refresh", "title": "Refresh", "icon": "$(refresh)" },
+      { "command": "irismd.revealInExplorer", "title": "Reveal in Explorer" },
+      { "command": "irismd.copyPath", "title": "Copy Path" }
+    ]
+  }
+}
+```
+- Activation events should include `onView:irismd.artifactTree`
+- Consider lazy loading units for faster activation

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/file-watcher/construction-log.md

@@ -0,0 +1,52 @@
+---
+unit: file-watcher
+intent: 011-vscode-extension
+created: 2025-12-25
+last_updated: 2025-12-25
+---
+
+# Construction Log: file-watcher
+
+## Original Plan
+
+**From Inception**: 1 bolt planned
+**Planned Date**: 2025-12-25
+
+| Bolt ID | Stories | Type |
+|---------|---------|------|
+| bolt-file-watcher-1 | 001, 002 | simple-construction-bolt |
+
+## Replanning History
+
+| Date | Action | Change | Reason | Approved |
+|------|--------|--------|--------|----------|
+
+## Current Bolt Structure
+
+| Bolt ID | Stories | Status | Changed |
+|---------|---------|--------|---------|
+| bolt-file-watcher-1 | 001, 002 | ✅ completed | - |
+
+## Execution History
+
+| Date | Bolt | Event | Details |
+|------|------|-------|---------|
+| 2025-12-25T19:30:00Z | bolt-file-watcher-1 | started | Stage 1: Plan |
+| 2025-12-25T19:30:00Z | bolt-file-watcher-1 | stage-complete | Plan → Implement |
+| 2025-12-25T19:35:00Z | bolt-file-watcher-1 | stage-complete | Implement → Test |
+| 2025-12-25T19:40:00Z | bolt-file-watcher-1 | completed | All 3 stages done |
+
+## Execution Summary
+
+| Metric | Value |
+|--------|-------|
+| Original bolts planned | 1 |
+| Current bolt count | 1 |
+| Bolts completed | 1 |
+| Bolts in progress | 0 |
+| Bolts remaining | 0 |
+| Replanning events | 0 |
+
+## Notes
+
+File watcher provides real-time updates to the sidebar when memory-bank files change. Uses 100ms debounce to prevent UI flicker.

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/file-watcher/stories/001-file-system-watcher.md

@@ -0,0 +1,57 @@
+---
+id: vscode-extension-story-fw-001
+unit: file-watcher
+intent: 011-vscode-extension
+status: draft
+priority: must
+created: 2025-12-25
+assigned_bolt: null
+implemented: false
+---
+
+# Story: File System Watcher Setup
+
+## User Story
+
+**As a** extension user
+**I want** the sidebar to automatically detect file changes in memory-bank
+**So that** I see updates without manually refreshing
+
+## Acceptance Criteria
+
+- [ ] **Given** extension is activated, **When** startWatching() is called, **Then** FileSystemWatcher is created for memory-bank/**/*.md
+- [ ] **Given** watcher is active, **When** a new .md file is created in memory-bank, **Then** onChange callback is triggered
+- [ ] **Given** watcher is active, **When** a .md file is modified, **Then** onChange callback is triggered
+- [ ] **Given** watcher is active, **When** a .md file is deleted, **Then** onChange callback is triggered
+- [ ] **Given** watcher is active, **When** extension deactivates, **Then** watcher is disposed (no memory leak)
+- [ ] **Given** watcher is active, **When** a non-.md file changes, **Then** onChange is NOT triggered
+
+## Technical Notes
+
+- Use vscode.workspace.createFileSystemWatcher
+- Glob pattern: `**/memory-bank/**/*.md`
+- Return Disposable for cleanup
+- Store watcher in ExtensionContext.subscriptions
+
+## Dependencies
+
+### Requires
+- artifact-parser/001-memory-bank-schema (for watch path)
+
+### Enables
+- sidebar-provider tree refresh
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| File renamed | Triggers delete + create events |
+| Folder created | May trigger if glob matches |
+| Git operations | Multiple rapid events (handled by debounce) |
+| External editor saves | Events still captured |
+
+## Out of Scope
+
+- Watching .irismd/ folder
+- Watching non-markdown files
+- Recursive depth limits

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/011-vscode-extension/units/file-watcher/stories/002-debounced-refresh.md

@@ -0,0 +1,53 @@
+---
+id: vscode-extension-story-fw-002
+unit: file-watcher
+intent: 011-vscode-extension
+status: draft
+priority: must
+created: 2025-12-25
+assigned_bolt: null
+implemented: false
+---
+
+# Story: Debounced Change Handling
+
+## User Story
+
+**As a** extension user
+**I want** rapid file changes to be debounced
+**So that** the tree doesn't flicker during batch operations
+
+## Acceptance Criteria
+
+- [ ] **Given** watcher detects a file change, **When** 100ms passes without more changes, **Then** refresh callback is triggered once
+- [ ] **Given** watcher detects 10 changes in 50ms, **When** 100ms passes after last change, **Then** refresh callback is triggered only once
+- [ ] **Given** debounce timer is running, **When** another change occurs, **Then** timer resets to 100ms
+- [ ] **Given** debounce is active, **When** extension deactivates, **Then** pending timer is cancelled
+
+## Technical Notes
+
+- Use setTimeout/clearTimeout for debouncing
+- Debounce delay: 100ms (as per FR-5.4)
+- Consider using lodash.debounce or custom implementation
+- Ensure timer is cleared on dispose
+
+## Dependencies
+
+### Requires
+- 001-file-system-watcher
+
+### Enables
+- Smooth sidebar updates
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Auto-save every 1s | Each save triggers debounced refresh |
+| git checkout | Many files change, single refresh |
+| File save + immediate close | Debounce captures the save |
+
+## Out of Scope
+
+- Configurable debounce delay
+- Different delays for different event types

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

@@ -0,0 +1,173 @@
+---
+unit: file-watcher
+intent: 011-vscode-extension
+phase: construction
+status: complete
+created: 2025-12-25
+updated: 2025-12-26
+default_bolt_type: simple-construction-bolt
+---
+
+# Unit Brief: File Watcher
+
+## Purpose
+
+Watch the memory-bank directory for file changes and trigger tree view refresh. Provides real-time updates to the sidebar when artifacts are created, modified, or deleted.
+
+## Scope
+
+### In Scope
+
+- Watch `memory-bank/` directory recursively
+- Detect file create, modify, delete events
+- Debounce rapid changes (100ms)
+- Trigger refresh callback on changes
+- Dispose watchers on extension deactivation
+
+### Out of Scope
+
+- Parsing file content (handled by artifact-parser)
+- Updating the tree view (handled by sidebar-provider)
+- Watching files outside memory-bank
+
+---
+
+## Assigned Requirements
+
+| FR | Requirement | Priority |
+|----|-------------|----------|
+| FR-5.1 | Watch `memory-bank/` directory for changes | Must |
+| FR-5.2 | Update tree view when files added/modified/deleted | Must |
+| FR-5.3 | Update status indicators when frontmatter changes | Must |
+| FR-5.4 | Debounce rapid file changes (100ms) | Must |
+
+---
+
+## Domain Concepts
+
+### Key Entities
+
+| Entity | Description | Attributes |
+|--------|-------------|------------|
+| FileWatcher | Main watcher service | watcher, debounceTimer, onChangeCallback |
+| FileChangeEvent | Change event data | type (create/modify/delete), path |
+
+### Key Operations
+
+| Operation | Description | Inputs | Outputs |
+|-----------|-------------|--------|---------|
+| startWatching | Begin watching memory-bank | workspacePath, callback | Disposable |
+| stopWatching | Stop all watchers | - | void |
+| handleChange | Process file change event | FileChangeEvent | void (triggers callback) |
+| debounce | Debounce rapid changes | - | void |
+
+---
+
+## Story Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Stories | 2 |
+| Must Have | 2 |
+| Should Have | 0 |
+| Could Have | 0 |
+
+### Stories
+
+| Story ID | Title | Priority | Status |
+|----------|-------|----------|--------|
+| 001 | File System Watcher Setup | Must | Planned |
+| 002 | Debounced Change Handling | Must | Planned |
+
+---
+
+## Dependencies
+
+### Depends On
+
+| Unit | Reason |
+|------|--------|
+| artifact-parser | Uses MemoryBankSchema for watch paths |
+
+### Depended By
+
+| Unit | Reason |
+|------|--------|
+| sidebar-provider | Subscribes to change events |
+| extension-core | Manages lifecycle |
+
+### External Dependencies
+
+| System | Purpose | Risk |
+|--------|---------|------|
+| VS Code FileSystemWatcher | Native file watching | Low |
+
+---
+
+## Technical Context
+
+### Suggested Technology
+
+- vscode.workspace.createFileSystemWatcher
+- Glob patterns for filtering
+- setTimeout for debouncing
+
+### Integration Points
+
+| Integration | Type | Protocol |
+|-------------|------|----------|
+| VS Code workspace | API | vscode.FileSystemWatcher |
+| sidebar-provider | Callback | TypeScript function |
+
+### Data Storage
+
+| Data | Type | Volume | Retention |
+|------|------|--------|-----------|
+| None | - | - | - |
+
+---
+
+## Constraints
+
+- Must use VS Code's FileSystemWatcher (not Node.js fs.watch) for cross-platform support
+- Must properly dispose watchers to prevent memory leaks
+- Debounce must be 100ms as specified
+
+---
+
+## Success Criteria
+
+### Functional
+
+- [ ] Watcher detects file creation in memory-bank
+- [ ] Watcher detects file modification
+- [ ] Watcher detects file deletion
+- [ ] Rapid changes are debounced (only one callback per 100ms)
+- [ ] Watchers disposed on extension deactivate
+
+### Non-Functional
+
+- [ ] Change detection < 100ms (before debounce)
+- [ ] No memory leaks from watchers
+
+### Quality
+
+- [ ] Unit tests with mock file system
+- [ ] Integration test with actual files
+- [ ] Code coverage > 80%
+
+---
+
+## Bolt Suggestions
+
+| Bolt | Type | Stories | Objective |
+|------|------|---------|-----------|
+| bolt-file-watcher-1 | Simple | 001, 002 | Complete file watcher functionality |
+
+---
+
+## Notes
+
+- VS Code's FileSystemWatcher is more reliable than Node.js fs.watch across platforms
+- Consider using a glob pattern like `**/*.md` to filter only markdown files
+- Debounce prevents UI flicker during rapid saves (e.g., auto-save)

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

@@ -0,0 +1,63 @@
+---
+unit: sidebar-provider
+intent: 011-vscode-extension
+created: 2025-12-25
+last_updated: 2025-12-25
+---
+
+# Construction Log: sidebar-provider
+
+## Original Plan
+
+**From Inception**: 2 bolts planned
+**Planned Date**: 2025-12-25
+
+| Bolt ID | Stories | Type |
+|---------|---------|------|
+| bolt-sidebar-provider-1 | 001, 002 | simple-construction-bolt |
+| bolt-sidebar-provider-2 | 003, 004, 005 | simple-construction-bolt |
+
+## Replanning History
+
+| Date | Action | Change | Reason | Approved |
+|------|--------|--------|--------|----------|
+
+## Current Bolt Structure
+
+| Bolt ID | Stories | Status | Changed |
+|---------|---------|--------|---------|
+| bolt-sidebar-provider-1 | 001, 002 | ✅ completed | - |
+| bolt-sidebar-provider-2 | 003, 004, 005 | ✅ completed | - |
+
+## Execution History
+
+| Date | Bolt | Event | Details |
+|------|------|-------|---------|
+| 2025-12-25T20:00:00Z | bolt-sidebar-provider-1 | started | Stage 1: Plan |
+| 2025-12-25T20:00:00Z | bolt-sidebar-provider-1 | stage-complete | Plan → Implement |
+| 2025-12-25T20:10:00Z | bolt-sidebar-provider-1 | stage-complete | Implement → Test |
+| 2025-12-25T20:20:00Z | bolt-sidebar-provider-1 | completed | All 3 stages done |
+| 2025-12-25T20:30:00Z | bolt-sidebar-provider-2 | started | Stage 1: Plan |
+| 2025-12-25T20:30:00Z | bolt-sidebar-provider-2 | stage-complete | Plan → Implement |
+| 2025-12-25T20:45:00Z | bolt-sidebar-provider-2 | stage-complete | Implement → Test |
+| 2025-12-25T21:00:00Z | bolt-sidebar-provider-2 | completed | All 3 stages done |
+
+## Execution Summary
+
+| Metric | Value |
+|--------|-------|
+| Original bolts planned | 2 |
+| Current bolt count | 2 |
+| Bolts completed | 2 |
+| Bolts in progress | 0 |
+| Bolts remaining | 0 |
+| Replanning events | 0 |
+
+## Notes
+
+Both bolts complete. sidebar-provider unit is fully implemented with:
+- TreeDataProvider with types, tree builder, and hierarchy
+- Expandable bolt tree with stages and stories
+- Status-aware colored icons
+- Bolt type badges ([Simple], [DDD])
+- Story 005 (footer) skipped as TreeView doesn't support rich content