project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/007-installer-analytics/units/001-analytics-tracker/stories/001-initialize-mixpanel.md

@@ -0,0 +1,56 @@
+---
+id: 001-initialize-mixpanel
+unit: 001-analytics-tracker
+intent: 007-installer-analytics
+status: complete
+priority: must
+created: 2025-12-28T12:30:00Z
+assigned_bolt: 016-analytics-tracker
+implemented: true
+---
+
+# Story: Initialize Mixpanel with Machine and Session IDs
+
+## User Story
+
+**As a** irismd installer
+**I want** to initialize Mixpanel with stable machine ID and unique session ID
+**So that** I can track usage patterns while identifying repeat installations
+
+## Acceptance Criteria
+
+- [ ] **Given** the installer starts, **When** analytics.init() is called, **Then** Mixpanel SDK is initialized with project token
+- [ ] **Given** a machine hostname, **When** generating distinct_id, **Then** it is a salted SHA-256 hash of the hostname
+- [ ] **Given** the same machine, **When** running installer multiple times, **Then** distinct_id is identical across runs
+- [ ] **Given** any installer run, **When** generating session_id, **Then** it is a random UUID unique to this execution
+- [ ] **Given** analytics is initialized, **When** any event is tracked, **Then** both distinct_id and session_id are included
+
+## Technical Notes
+
+- Use `crypto.createHash('sha256')` for hostname hashing
+- Salt: `'irismd-analytics-v1'` (constant, prevents reverse lookup)
+- Use `crypto.randomUUID()` for session ID
+- Mixpanel token will be embedded in source code
+- No data should be written to disk
+
+## Dependencies
+
+### Requires
+- None (foundation story)
+
+### Enables
+- 004-track-installer-events
+- 005-track-selection-events
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Hostname contains special characters | Hash handles any string |
+| Very long hostname | SHA-256 handles any length |
+| Hostname changes (rare) | New distinct_id generated |
+
+## Out of Scope
+
+- Persistent ID storage (explicitly not wanted)
+- User-provided ID

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/007-installer-analytics/units/001-analytics-tracker/stories/002-detect-shell.md

@@ -0,0 +1,68 @@
+---
+id: 002-detect-shell
+unit: 001-analytics-tracker
+intent: 007-installer-analytics
+status: ready
+priority: must
+created: 2025-12-28T12:30:00Z
+assigned_bolt: 016-analytics-tracker
+implemented: false
+---
+
+# Story: Detect Shell Environment
+
+## User Story
+
+**As a** irismd analytics system
+**I want** to detect the user's shell/terminal environment
+**So that** I can understand which terminals are most popular among users
+
+## Acceptance Criteria
+
+- [ ] **Given** user is on macOS/Linux with zsh, **When** detecting shell, **Then** return "zsh"
+- [ ] **Given** user is on macOS/Linux with bash, **When** detecting shell, **Then** return "bash"
+- [ ] **Given** user is on Windows with PowerShell, **When** detecting shell, **Then** return "powershell"
+- [ ] **Given** user is on Windows with cmd.exe, **When** detecting shell, **Then** return "cmd"
+- [ ] **Given** shell cannot be determined, **When** detecting shell, **Then** return "unknown"
+- [ ] **Given** user is using fish shell, **When** detecting shell, **Then** return "fish"
+
+## Technical Notes
+
+- On Unix: Check `process.env.SHELL` and extract basename
+- On Windows: Check `process.env.ComSpec` for powershell/pwsh/cmd
+- Common shells: zsh, bash, fish, sh, dash, powershell, pwsh, cmd
+
+```typescript
+function detectShell(): string {
+  if (process.platform === 'win32') {
+    const comspec = process.env.ComSpec?.toLowerCase() || '';
+    if (comspec.includes('powershell') || comspec.includes('pwsh')) return 'powershell';
+    if (comspec.includes('cmd')) return 'cmd';
+    return 'unknown';
+  }
+  const shell = process.env.SHELL || '';
+  const basename = shell.split('/').pop() || 'unknown';
+  return basename;
+}
+```
+
+## Dependencies
+
+### Requires
+- None
+
+### Enables
+- 001-initialize-mixpanel (provides shell property for base properties)
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| SHELL env var not set | Return "unknown" |
+| ComSpec not set on Windows | Return "unknown" |
+| Custom/unusual shell | Return basename as-is |
+
+## Out of Scope
+
+- Shell version detection
+- Terminal emulator detection (iTerm, Terminal.app, etc.)

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/007-installer-analytics/units/001-analytics-tracker/stories/003-check-telemetry-disabled.md

@@ -0,0 +1,66 @@
+---
+id: 003-check-telemetry-disabled
+unit: 001-analytics-tracker
+intent: 007-installer-analytics
+status: ready
+priority: must
+created: 2025-12-28T12:30:00Z
+assigned_bolt: 016-analytics-tracker
+implemented: false
+---
+
+# Story: Check if Telemetry is Disabled
+
+## User Story
+
+**As a** user who values privacy
+**I want** to disable telemetry via environment variables
+**So that** no analytics data is sent without my knowledge
+
+## Acceptance Criteria
+
+- [ ] **Given** SPECSMD_TELEMETRY_DISABLED=1, **When** checking telemetry status, **Then** telemetry is disabled
+- [ ] **Given** DO_NOT_TRACK=1, **When** checking telemetry status, **Then** telemetry is disabled
+- [ ] **Given** CI=true, **When** checking telemetry status, **Then** telemetry is disabled
+- [ ] **Given** GITHUB_ACTIONS=true, **When** checking telemetry status, **Then** telemetry is disabled
+- [ ] **Given** GITLAB_CI=true, **When** checking telemetry status, **Then** telemetry is disabled
+- [ ] **Given** CIRCLECI=true, **When** checking telemetry status, **Then** telemetry is disabled
+- [ ] **Given** JENKINS_URL is set, **When** checking telemetry status, **Then** telemetry is disabled
+- [ ] **Given** no disable flags set, **When** checking telemetry status, **Then** telemetry is enabled
+
+## Technical Notes
+
+```typescript
+function isTelemetryDisabled(): boolean {
+  return (
+    process.env.SPECSMD_TELEMETRY_DISABLED === '1' ||
+    process.env.DO_NOT_TRACK === '1' ||
+    process.env.CI === 'true' ||
+    process.env.GITHUB_ACTIONS === 'true' ||
+    process.env.GITLAB_CI === 'true' ||
+    process.env.JENKINS_URL !== undefined ||
+    process.env.CIRCLECI === 'true'
+  );
+}
+```
+
+## Dependencies
+
+### Requires
+- None
+
+### Enables
+- 001-initialize-mixpanel (determines if analytics should be enabled)
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Multiple disable flags set | Still disabled (any one is enough) |
+| SPECSMD_TELEMETRY_DISABLED=0 | NOT disabled (only "1" disables) |
+| DO_NOT_TRACK=true | NOT disabled (only "1" disables) |
+
+## Out of Scope
+
+- Persistent opt-out storage
+- CLI flag handling (separate story)

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/007-installer-analytics/units/001-analytics-tracker/stories/004-track-installer-events.md

@@ -0,0 +1,67 @@
+---
+id: 004-track-installer-events
+unit: 001-analytics-tracker
+intent: 007-installer-analytics
+status: ready
+priority: must
+created: 2025-12-28T12:30:00Z
+assigned_bolt: 016-analytics-tracker
+implemented: false
+---
+
+# Story: Track Installer Lifecycle Events
+
+## User Story
+
+**As a** irismd product team member
+**I want** to track when installations start, complete, and fail
+**So that** I can understand installation success rates and identify issues
+
+## Acceptance Criteria
+
+- [ ] **Given** installer starts, **When** trackInstallerStarted() is called, **Then** installer_started event is sent with base properties
+- [ ] **Given** IDE installation completes, **When** trackInstallationCompleted() is called, **Then** installation_completed event is sent with ide, flow, duration_ms, files_created
+- [ ] **Given** IDE installation fails, **When** trackInstallationFailed() is called, **Then** installation_failed event is sent with ide, error_category, flow
+- [ ] **Given** telemetry is disabled, **When** any track method is called, **Then** no event is sent
+- [ ] **Given** Mixpanel is unreachable, **When** tracking events, **Then** errors are silently ignored
+
+## Technical Notes
+
+- All events include base properties (distinct_id, session_id, $os, shell, node_version, irismd_version)
+- Fire-and-forget pattern - don't await Mixpanel responses
+- Wrap all tracking in try/catch to ensure silent failures
+
+```typescript
+trackInstallerStarted(): void {
+  this.track('installer_started');
+}
+
+trackInstallationCompleted(ide: string, flow: string, durationMs: number, filesCreated: number): void {
+  this.track('installation_completed', { ide, flow, duration_ms: durationMs, files_created: filesCreated });
+}
+
+trackInstallationFailed(ide: string, errorCategory: string, flow?: string): void {
+  this.track('installation_failed', { ide, error_category: errorCategory, ...(flow && { flow }) });
+}
+```
+
+## Dependencies
+
+### Requires
+- 001-initialize-mixpanel (Mixpanel must be initialized)
+
+### Enables
+- None (end of chain)
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Very long duration (hours) | Track as-is |
+| Zero files created | Track with files_created: 0 |
+| Unknown error category | Use "unknown" as category |
+
+## Out of Scope
+
+- Detailed error messages (only categories)
+- Stack traces

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/007-installer-analytics/units/001-analytics-tracker/stories/005-track-selection-events.md

@@ -0,0 +1,66 @@
+---
+id: 005-track-selection-events
+unit: 001-analytics-tracker
+intent: 007-installer-analytics
+status: ready
+priority: must
+created: 2025-12-28T12:30:00Z
+assigned_bolt: 016-analytics-tracker
+implemented: false
+---
+
+# Story: Track IDE and Flow Selection Events
+
+## User Story
+
+**As a** irismd product team member
+**I want** to track which IDEs and flows users select
+**So that** I can understand user preferences and prioritize IDE support
+
+## Acceptance Criteria
+
+- [ ] **Given** user confirms IDE selection, **When** trackIdesConfirmed() is called, **Then** ides_confirmed event is sent with ide_count and ides array
+- [ ] **Given** user selects 3 IDEs, **When** tracking, **Then** ide_count is 3 and ides contains all 3 IDE names
+- [ ] **Given** user selects flow, **When** trackFlowSelected() is called, **Then** flow_selected event is sent with flow name
+- [ ] **Given** telemetry is disabled, **When** any track method is called, **Then** no event is sent
+- [ ] **Given** Mixpanel is unreachable, **When** tracking events, **Then** errors are silently ignored
+
+## Technical Notes
+
+- ides_confirmed is sent ONCE after user confirms their selection
+- ides array contains IDE identifiers like 'claude-code', 'cursor', 'windsurf'
+- flow is the flow name like 'aidlc', 'custom'
+
+```typescript
+trackIdesConfirmed(ides: string[]): void {
+  this.track('ides_confirmed', {
+    ide_count: ides.length,
+    ides: ides,
+  });
+}
+
+trackFlowSelected(flow: string): void {
+  this.track('flow_selected', { flow });
+}
+```
+
+## Dependencies
+
+### Requires
+- 001-initialize-mixpanel (Mixpanel must be initialized)
+
+### Enables
+- None (end of chain)
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Single IDE selected | ide_count: 1, ides: ['ide-name'] |
+| Empty IDE list (edge case) | ide_count: 0, ides: [] |
+| Unknown flow name | Track as-is |
+
+## Out of Scope
+
+- Tracking individual IDE selections before confirmation
+- Tracking selection changes/deselections

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/007-installer-analytics/units/001-analytics-tracker/stories/006-cli-no-telemetry-flag.md

@@ -0,0 +1,59 @@
+---
+id: 006-cli-no-telemetry-flag
+unit: 001-analytics-tracker
+intent: 007-installer-analytics
+status: ready
+priority: should
+created: 2025-12-28T12:30:00Z
+assigned_bolt: 016-analytics-tracker
+implemented: false
+---
+
+# Story: Support --no-telemetry CLI Flag
+
+## User Story
+
+**As a** user who prefers CLI flags over environment variables
+**I want** to use --no-telemetry flag when running the installer
+**So that** I can disable analytics without setting environment variables
+
+## Acceptance Criteria
+
+- [ ] **Given** user runs `npx irismd@latest install --no-telemetry`, **When** installer starts, **Then** telemetry is disabled
+- [ ] **Given** --no-telemetry flag is present, **When** checking telemetry status, **Then** isTelemetryDisabled() returns true
+- [ ] **Given** both --no-telemetry and env vars are set, **When** checking, **Then** telemetry is disabled
+
+## Technical Notes
+
+- Flag should be parsed before analytics.init() is called
+- Need to integrate with existing CLI argument parsing
+- May require passing flag state to analytics module
+
+```typescript
+// Option 1: Check process.argv directly
+const hasNoTelemetryFlag = process.argv.includes('--no-telemetry');
+
+// Option 2: Accept as parameter to init()
+analytics.init({ noTelemetry: parsedArgs.noTelemetry });
+```
+
+## Dependencies
+
+### Requires
+- 003-check-telemetry-disabled (extends the check)
+
+### Enables
+- None
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| --no-telemetry without value | Telemetry disabled |
+| --no-telemetry=true | Telemetry disabled |
+| --no-telemetry=false | Interpret as disabled (presence = disabled) |
+
+## Out of Scope
+
+- Persistent flag storage
+- Config file option

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/007-installer-analytics/units/001-analytics-tracker/unit-brief.md

@@ -0,0 +1,191 @@
+---
+unit: analytics-tracker
+intent: 007-installer-analytics
+phase: inception
+status: ready
+created: 2025-12-28T12:00:00Z
+updated: 2025-12-28T12:30:00Z
+---
+
+# Unit Brief: Analytics Tracker
+
+## Purpose
+
+Implement Mixpanel analytics integration for the irismd installer to track anonymous usage patterns, IDE preferences, and installation behavior.
+
+## Scope
+
+### In Scope
+- Mixpanel SDK initialization
+- Machine ID generation (salted SHA-256 of hostname)
+- Session ID generation (random UUID per run)
+- Shell/terminal environment detection
+- Event tracking (5 event types)
+- Environment variable opt-out support
+- Fire-and-forget event delivery
+
+### Out of Scope
+- Analytics dashboard creation (Mixpanel handles this)
+- Local data persistence
+- User consent prompts
+- Custom analytics backend
+
+---
+
+## Assigned Requirements
+
+**These FRs from the intent are assigned to this unit. Stories will be created from these.**
+
+| FR | Requirement | Priority |
+|----|-------------|----------|
+| FR-1.1 | Generate `distinct_id` by hashing machine hostname with salt | Must |
+| FR-1.2 | Use constant salt to prevent reverse-lookup | Must |
+| FR-1.3 | Generate `session_id` as random UUID per run | Must |
+| FR-1.4 | Use same IDs for all events within session | Must |
+| FR-1.5 | Do NOT persist any data to disk | Must |
+| FR-1.6 | Do NOT collect any PII | Must |
+| FR-2.1 | Track `installer_started` event | Must |
+| FR-2.2 | Track `ides_confirmed` event | Must |
+| FR-2.3 | Track `flow_selected` event | Must |
+| FR-2.4 | Track `installation_completed` event (per IDE) | Must |
+| FR-2.5 | Track `installation_failed` event | Must |
+| FR-4.1-4.6 | Include base properties in all events | Must |
+| FR-5.1 | Use Mixpanel Node.js SDK | Must |
+| FR-5.2 | Allow Mixpanel to handle geolocation | Must |
+| FR-5.3 | Use fire-and-forget pattern | Must |
+| FR-6.1 | Support SPECSMD_TELEMETRY_DISABLED=1 | Must |
+| FR-6.2 | Support --no-telemetry flag | Should |
+| FR-6.3 | Auto-disable in CI environments | Must |
+| FR-6.4 | Respect DO_NOT_TRACK=1 | Must |
+
+---
+
+## Domain Concepts
+
+### Key Entities
+| Entity | Description | Attributes |
+|--------|-------------|------------|
+| AnalyticsTracker | Singleton that manages event tracking | mixpanel, machineId, sessionId, enabled, baseProperties |
+| Event | Data sent to Mixpanel | event name, properties |
+| BaseProperties | Common properties for all events | distinct_id, session_id, $os, shell, node_version, irismd_version |
+
+### Key Operations
+| Operation | Description | Inputs | Outputs |
+|-----------|-------------|--------|---------|
+| init() | Initialize tracker with IDs | none | void |
+| trackInstallerStarted() | Send installer_started event | none | void |
+| trackIdesConfirmed() | Send ides_confirmed event | ides[] | void |
+| trackFlowSelected() | Send flow_selected event | flow | void |
+| trackInstallationCompleted() | Send completion event | ide, flow, durationMs, filesCreated | void |
+| trackInstallationFailed() | Send failure event | ide, errorCategory, flow | void |
+
+---
+
+## Story Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Stories | 6 |
+| Must Have | 5 |
+| Should Have | 1 |
+| Could Have | 0 |
+
+### Stories
+
+| Story ID | Title | Priority | Status |
+|----------|-------|----------|--------|
+| 001 | Initialize Mixpanel with machine and session IDs | Must | Planned |
+| 002 | Detect shell environment | Must | Planned |
+| 003 | Check if telemetry is disabled | Must | Planned |
+| 004 | Track installer lifecycle events | Must | Planned |
+| 005 | Track IDE and flow selection events | Must | Planned |
+| 006 | Support --no-telemetry CLI flag | Should | Planned |
+
+---
+
+## Dependencies
+
+### Depends On
+| Unit | Reason |
+|------|--------|
+| None | Standalone module |
+
+### Depended By
+| Unit | Reason |
+|------|--------|
+| installer-core | Needs analytics for event tracking |
+
+### External Dependencies
+| System | Purpose | Risk |
+|--------|---------|------|
+| Mixpanel | Event storage and dashboards | Low - fire-and-forget |
+| npm: mixpanel | Node.js SDK | Low - stable package |
+
+---
+
+## Technical Context
+
+### Suggested Technology
+- TypeScript module in `src/analytics/`
+- Mixpanel Node.js SDK (`mixpanel` npm package)
+- Node.js crypto module for hashing and UUID
+
+### Integration Points
+| Integration | Type | Protocol |
+|-------------|------|----------|
+| Mixpanel API | HTTP | HTTPS (via SDK) |
+| Installer CLI | Function call | Direct import |
+
+### Data Storage
+| Data | Type | Volume | Retention |
+|------|------|--------|-----------|
+| Events | Mixpanel cloud | ~5 events/install | Mixpanel default |
+
+---
+
+## Constraints
+
+- Must not add noticeable latency (<50ms)
+- Must work offline (silent failure)
+- Must not break installation on analytics failure
+- No PII collection (GDPR compliance)
+- Mixpanel token embedded in source (acceptable for analytics)
+
+---
+
+## Success Criteria
+
+### Functional
+- [ ] Mixpanel SDK initialized with correct token
+- [ ] Machine ID is consistent across runs on same machine
+- [ ] Session ID is unique per run
+- [ ] All 5 event types tracked correctly
+- [ ] Events include all base properties
+
+### Non-Functional
+- [ ] Analytics adds <50ms to installation time
+- [ ] Silent failure on network errors
+- [ ] Works offline without errors
+
+### Quality
+- [ ] Unit tests for ID generation
+- [ ] Unit tests for environment detection
+- [ ] Integration test for event structure
+
+---
+
+## Bolt Suggestions
+
+Based on stories and complexity:
+
+| Bolt | Type | Stories | Objective |
+|------|------|---------|-----------|
+| bolt-analytics-tracker-1 | simple-construction-bolt | All | Complete analytics module |
+
+---
+
+## Notes
+
+- Single bolt should be sufficient given low complexity
+- Mixpanel token needs to be created in Mixpanel dashboard
+- Consider adding to package.json devDependencies for testing

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/007-installer-analytics/units/002-privacy-documentation/stories/001-create-privacy-md.md

@@ -0,0 +1,58 @@
+---
+id: 007-privacy-story-1
+unit: privacy-documentation
+intent: 007-installer-analytics
+status: done
+priority: must
+created: 2025-12-28T12:00:00Z
+assigned_bolt: bolt-privacy-documentation-1
+implemented: true
+---
+
+# Story: Create PRIVACY.md with Data Disclosure
+
+## User Story
+
+**As a** user who wants to understand data collection
+**I want** to read a clear privacy policy
+**So that** I can make informed decisions about using irismd
+
+## Acceptance Criteria
+
+- [x] **Given** user visits the repository, **When** they look for privacy info, **Then** PRIVACY.md exists at root
+- [x] **Given** user reads PRIVACY.md, **When** they check what's collected, **Then** all data points are listed
+- [x] **Given** user reads PRIVACY.md, **When** they want to opt-out, **Then** clear instructions are provided
+- [x] **Given** user reads PRIVACY.md, **When** they check legal basis, **Then** legitimate interest is stated
+- [x] **Given** user reads PRIVACY.md, **When** they check for PII, **Then** it confirms no PII is collected
+
+## Technical Notes
+
+- PRIVACY.md was created during Inception phase
+- Located at repository root: `/PRIVACY.md`
+- Contains:
+  - What data is collected
+  - What is NOT collected
+  - Opt-out methods
+  - Legal basis statement
+
+## Dependencies
+
+### Requires
+
+- None
+
+### Enables
+
+- 002-add-readme-section
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| N/A | Documentation only |
+
+## Out of Scope
+
+- Legal review
+- Cookie policy (no cookies)
+- Terms of service

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/007-installer-analytics/units/002-privacy-documentation/stories/002-add-readme-section.md

@@ -0,0 +1,61 @@
+---
+id: 007-privacy-story-2
+unit: privacy-documentation
+intent: 007-installer-analytics
+status: ready
+priority: must
+created: 2025-12-28T12:30:00Z
+assigned_bolt: bolt-privacy-documentation-1
+implemented: false
+---
+
+# Story: Add Analytics Section to README
+
+## User Story
+
+**As a** user reading the README
+**I want** to see a brief note about analytics
+**So that** I am aware of data collection before installing
+
+## Acceptance Criteria
+
+- [ ] **Given** user reads README.md, **When** they scroll to bottom, **Then** they see an "Analytics" section
+- [ ] **Given** user sees Analytics section, **When** they read it, **Then** it states no personal info is collected
+- [ ] **Given** user sees Analytics section, **When** they want to opt-out, **Then** quick command is shown
+- [ ] **Given** user wants more details, **When** they look for link, **Then** PRIVACY.md is linked
+
+## Technical Notes
+
+Add to README.md at the bottom (before license section if exists):
+
+```markdown
+## Analytics
+
+irismd collects anonymous usage analytics to improve the product. No personal information is collected.
+
+To disable: `SPECSMD_TELEMETRY_DISABLED=1 npx irismd@latest install`
+
+See [PRIVACY.md](./PRIVACY.md) for details.
+```
+
+## Dependencies
+
+### Requires
+
+- 001-create-privacy-md (PRIVACY.md must exist to link to)
+
+### Enables
+
+- None
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| README has no license section | Add at very bottom |
+| README has license section | Add before license |
+
+## Out of Scope
+
+- Detailed data listing (that's in PRIVACY.md)
+- Multiple language support