murmur8 4.1.1 → 4.3.0

package/.blueprint/features/feature_export-history/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,48 @@
+# Implementation Plan — Export Pipeline History
+
+## Summary
+
+Add `exportHistory()` function to `src/history.js` that reads pipeline history, applies optional filters (date range, status, feature slug), and outputs CSV or JSON. Wire `history export` subcommand in CLI to invoke this function with parsed flags.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/history.js` | Modify | Add `exportHistory()` function with filtering, CSV/JSON formatting, file output |
+| `bin/cli.js` | Modify | Add `export` subcommand to `history` handler, parse new flags |
+
+## Implementation Steps
+
+1. **Add date validation helper** in `src/history.js` — validate YYYY-MM-DD format, return Date or null
+
+2. **Add CSV formatter** in `src/history.js` — convert entry array to CSV string with header row (slug, status, startedAt, completedAt, totalDurationMs, failedStage, pausedAfter), escape commas/quotes in values
+
+3. **Add JSON formatter** in `src/history.js` — pretty-print array with 2-space indent
+
+4. **Implement `exportHistory(options)` function** in `src/history.js`:
+   - Read history via `readHistoryFile()`
+   - Return `{ exitCode: 1, error: '...' }` if corrupted
+   - Apply filters: `since`, `until`, `status`, `feature` (all optional)
+   - Validate date formats and status values, return error if invalid
+   - Format output as CSV (default) or JSON based on `options.format`
+   - If `options.output`: write to file (create parent dirs), return `{ message: '...' }`
+   - Otherwise return `{ output: '...' }` for stdout
+
+5. **Export `exportHistory`** from `src/history.js` module.exports
+
+6. **Add export subcommand handling** in `bin/cli.js`:
+   - In `history` command handler, check if `subArg === 'export'`
+   - Parse flags: `--format=csv|json`, `--since=YYYY-MM-DD`, `--until=YYYY-MM-DD`, `--status=success|failed|paused`, `--feature=<slug>`, `--output=<path>`
+   - Call `exportHistory()` with options object
+   - Print `result.output` to stdout or `result.message` for file confirmation
+   - Exit with `result.exitCode` if error
+
+7. **Update help text** in `showHelp()` to document `history export` and its flags
+
+8. **Run tests** — `node --test test/feature_export-history.test.js`
+
+## Risks/Questions
+
+- CSV escaping edge case: slugs containing commas or quotes need proper RFC 4180 escaping (wrap in quotes, double internal quotes)
+- Date filtering uses `completedAt` per spec; entries without `completedAt` should be excluded from date filters
+- Empty/missing history file treated as empty array (not an error per spec)

package/.blueprint/features/feature_export-history/story-basic-export.md

@@ -0,0 +1,48 @@
+# Story — Basic Export
+
+## User story
+
+As a developer, I want to export pipeline history to CSV or JSON format so that I can analyze execution data in spreadsheets or integrate with external tools.
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Default CSV export to stdout**
+- Given the history file contains one or more entries,
+- When I run `murmur8 history export`,
+- Then the output is written to stdout in CSV format with a header row.
+
+**AC-2 — Explicit CSV format selection**
+- Given the history file contains entries,
+- When I run `murmur8 history export --format=csv`,
+- Then the output is CSV format with columns: slug, status, startedAt, completedAt, totalDurationMs, failedStage, pausedAfter.
+
+**AC-3 — JSON format selection**
+- Given the history file contains entries,
+- When I run `murmur8 history export --format=json`,
+- Then the output is a pretty-printed JSON array containing all history entries with their full structure.
+
+**AC-4 — Empty history produces valid structure**
+- Given the history file is empty or does not exist,
+- When I run `murmur8 history export --format=csv`,
+- Then the output is a CSV header row with no data rows.
+
+**AC-5 — Empty history produces valid JSON**
+- Given the history file is empty or does not exist,
+- When I run `murmur8 history export --format=json`,
+- Then the output is an empty JSON array `[]`.
+
+**AC-6 — Corrupted history file handling**
+- Given the history file contains invalid JSON,
+- When I run `murmur8 history export`,
+- Then the command exits with code 1 and displays an error message suggesting `history clear`.
+
+---
+
+## Out of scope
+
+- Exporting nested stage data in CSV (available in JSON only)
+- Streaming output for large files
+- Custom column selection
+- Export of queue state or insights aggregations

package/.blueprint/features/feature_export-history/story-date-filter.md

@@ -0,0 +1,42 @@
+# Story — Date Filtering
+
+## User story
+
+As a developer, I want to filter exported history by date range so that I can extract data for specific time periods for reporting or analysis.
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Filter by since date**
+- Given the history file contains entries from multiple dates,
+- When I run `murmur8 history export --since=2024-01-15`,
+- Then only entries where `completedAt >= 2024-01-15T00:00:00` (local time) are included in the output.
+
+**AC-2 — Filter by until date**
+- Given the history file contains entries from multiple dates,
+- When I run `murmur8 history export --until=2024-01-20`,
+- Then only entries where `completedAt <= 2024-01-20T23:59:59` (local time) are included in the output.
+
+**AC-3 — Combined date range filter**
+- Given the history file contains entries from multiple dates,
+- When I run `murmur8 history export --since=2024-01-15 --until=2024-01-20`,
+- Then only entries within the inclusive date range are included in the output.
+
+**AC-4 — No matches returns empty result**
+- Given the history file contains entries but none within the specified range,
+- When I run `murmur8 history export --since=2099-01-01`,
+- Then the output is a valid empty structure (CSV header only or empty JSON array).
+
+**AC-5 — Invalid date format error**
+- Given an invalid date format is provided,
+- When I run `murmur8 history export --since=invalid-date`,
+- Then the command exits with code 1 and displays a usage hint showing the expected YYYY-MM-DD format.
+
+---
+
+## Out of scope
+
+- Time-of-day filtering (only date precision)
+- Timezone configuration (uses local timezone)
+- Relative date expressions (e.g., "last week")

package/.blueprint/features/feature_export-history/story-feature-filter.md

@@ -0,0 +1,42 @@
+# Story — Feature Filtering
+
+## User story
+
+As a developer, I want to filter exported history by feature slug so that I can extract execution data for a specific feature across all its runs.
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Filter by exact feature slug**
+- Given the history file contains entries for multiple features,
+- When I run `murmur8 history export --feature=user-auth`,
+- Then only entries where `slug === 'user-auth'` are included in the output.
+
+**AC-2 — Exact match only**
+- Given the history file contains entries for "user-auth" and "user-auth-v2",
+- When I run `murmur8 history export --feature=user-auth`,
+- Then only entries with exact slug "user-auth" are included (not "user-auth-v2").
+
+**AC-3 — No matches returns empty result**
+- Given the history file contains entries but none matching the specified slug,
+- When I run `murmur8 history export --feature=nonexistent`,
+- Then the output is a valid empty structure (CSV header only or empty JSON array).
+
+**AC-4 — Combine with other filters**
+- Given the history file contains multiple entries for a feature with different statuses,
+- When I run `murmur8 history export --feature=user-auth --status=failed`,
+- Then only entries matching both the feature slug AND the status are included.
+
+**AC-5 — Case-sensitive matching**
+- Given the history file contains an entry with slug "User-Auth",
+- When I run `murmur8 history export --feature=user-auth`,
+- Then no entries are returned (matching is case-sensitive).
+
+---
+
+## Out of scope
+
+- Substring or pattern matching
+- Multiple feature slugs in a single filter
+- Case-insensitive matching option

package/.blueprint/features/feature_export-history/story-file-output.md

@@ -0,0 +1,48 @@
+# Story — File Output
+
+## User story
+
+As a developer, I want to write exported history directly to a file so that I can save reports without shell redirection and receive confirmation of the write.
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Write to specified file**
+- Given the history file contains entries,
+- When I run `murmur8 history export --output=report.csv`,
+- Then the export is written to `report.csv` in the current directory.
+
+**AC-2 — Success confirmation message**
+- Given the export writes successfully,
+- When I run `murmur8 history export --output=report.csv`,
+- Then a confirmation message is displayed showing the file path and entry count.
+
+**AC-3 — Create parent directories**
+- Given the output path includes directories that do not exist,
+- When I run `murmur8 history export --output=reports/2024/january.csv`,
+- Then the parent directories are created and the file is written.
+
+**AC-4 — Combine with format option**
+- Given the history file contains entries,
+- When I run `murmur8 history export --format=json --output=report.json`,
+- Then the file contains JSON-formatted export data.
+
+**AC-5 — File write error handling**
+- Given the output path is not writable (e.g., permission denied),
+- When I run `murmur8 history export --output=/readonly/report.csv`,
+- Then the command exits with code 1 and displays a descriptive error message.
+
+**AC-6 — Overwrite existing file**
+- Given a file already exists at the output path,
+- When I run `murmur8 history export --output=existing.csv`,
+- Then the existing file is overwritten without prompting.
+
+---
+
+## Out of scope
+
+- Interactive overwrite confirmation
+- Append mode for existing files
+- Automatic file extension based on format
+- Output to multiple files

package/.blueprint/features/feature_export-history/story-status-filter.md

@@ -0,0 +1,42 @@
+# Story — Status Filtering
+
+## User story
+
+As a developer, I want to filter exported history by pipeline status so that I can analyze specific outcomes like failures or successful runs.
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Filter by success status**
+- Given the history file contains entries with mixed statuses,
+- When I run `murmur8 history export --status=success`,
+- Then only entries with `status === 'success'` are included in the output.
+
+**AC-2 — Filter by failed status**
+- Given the history file contains entries with mixed statuses,
+- When I run `murmur8 history export --status=failed`,
+- Then only entries with `status === 'failed'` are included in the output.
+
+**AC-3 — Filter by paused status**
+- Given the history file contains entries with mixed statuses,
+- When I run `murmur8 history export --status=paused`,
+- Then only entries with `status === 'paused'` are included in the output.
+
+**AC-4 — No matches returns empty result**
+- Given the history file contains entries but none with the specified status,
+- When I run `murmur8 history export --status=failed`,
+- Then the output is a valid empty structure (CSV header only or empty JSON array).
+
+**AC-5 — Invalid status value error**
+- Given an invalid status value is provided,
+- When I run `murmur8 history export --status=unknown`,
+- Then the command exits with code 1 and displays an error listing valid status values: success, failed, paused.
+
+---
+
+## Out of scope
+
+- Multiple status values in a single filter (e.g., `--status=success,failed`)
+- Negation filters (e.g., exclude failed)
+- Custom status values

package/.blueprint/features/feature_extract-prompt-util/FEATURE_SPEC.md

@@ -0,0 +1,42 @@
+# Feature Specification — Extract Prompt Utility
+
+## 1. Feature Intent
+
+The `prompt()` function is duplicated identically in `src/init.js` and `src/update.js`. Extract to a shared utility module to eliminate duplication and make the pattern reusable.
+
+## 2. Scope
+
+### In Scope
+- Create `src/utils.js` with `prompt()` function
+- Update `src/init.js` to import from utils.js
+- Update `src/update.js` to import from utils.js
+- Remove duplicate function definitions
+
+### Out of Scope
+- Adding new utility functions
+- Changing prompt behavior
+- Adding tests for prompt (interactive, hard to test)
+
+## 3. Files to Modify
+
+| File | Change |
+|------|--------|
+| `src/utils.js` | Create new file with prompt() |
+| `src/init.js` | Remove prompt(), add import |
+| `src/update.js` | Remove prompt(), add import |
+
+## 4. Function Signature
+
+```javascript
+async function prompt(question) {
+  // Creates readline interface
+  // Asks question
+  // Returns answer.toLowerCase().trim()
+}
+```
+
+## 5. Change Log
+
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-03-03 | Initial spec | DRY refactoring | Alex |

package/.blueprint/features/feature_fix-status-icons/FEATURE_SPEC.md

@@ -0,0 +1,37 @@
+# Feature Specification — Fix Status Icons
+
+## 1. Feature Intent
+
+The `STATUS_ICONS` object in `src/theme.js` uses legacy `parallel_*` keys, but the actual status strings in `src/murm.js` use `murm_*`. This creates a mismatch where icon lookups fail silently.
+
+## 2. Scope
+
+### In Scope
+- Rename `parallel_queued` → `murm_queued`
+- Rename `parallel_running` → `murm_running`
+- Rename `parallel_complete` → `murm_complete`
+- Rename `parallel_failed` → `murm_failed`
+- Update tests that reference these keys
+
+### Out of Scope
+- Adding new icons
+- Changing icon characters
+- Refactoring theme.js structure
+
+## 3. Actors
+- **Developer**: Uses STATUS_ICONS for CLI output formatting
+
+## 4. Behaviour Overview
+After this change, `STATUS_ICONS[status]` will return the correct icon when `status` is one of the `murm_*` values from the state machine.
+
+## 5. Files to Modify
+| File | Change |
+|------|--------|
+| `src/theme.js` | Rename 4 keys in STATUS_ICONS |
+| `test/feature_murmuration-theme.test.js` | Update key references |
+| `test/feature_theme-adoption.test.js` | Update key references |
+
+## 6. Change Log
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-03-03 | Initial spec | Complete v4.0 murm theming | Alex |

package/.blueprint/features/feature_murm-subagent/FEATURE_SPEC.md

@@ -0,0 +1,137 @@
+# Feature Specification — Murmuration Sub-Agent Architecture
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Current murmuration spawns separate CLI processes (`npx claude`) which fails inside existing Claude sessions
+- The `/implement-feature` skill already uses Task sub-agents for Alex/Cass/Nigel/Codey
+- Extending this pattern to run multiple feature pipelines in parallel is natural and efficient
+- Enables true parallel execution without leaving the current Claude Code session
+
+> This feature changes how murmuration works: from process spawning to Task sub-agent orchestration.
+
+---
+
+## 2. Scope
+### In Scope
+- Modify SKILL.md to accept multiple slugs
+- Add worktree creation/cleanup logic to the skill
+- Spawn parallel Task sub-agents (one full pipeline per feature)
+- Merge results back to main branch
+- Handle conflicts and failures gracefully
+
+### Out of Scope
+- Changing the single-feature pipeline flow
+- Removing CLI process spawning (keep for CI/automation use cases)
+- Adding new agent types
+- Changing worktree locations or branch naming
+
+---
+
+## 3. Actors Involved
+
+- **User**: Invokes `/implement-feature slug-a slug-b slug-c`
+- **Orchestrator (Claude)**: Reads skill, creates worktrees, spawns parallel Tasks
+- **Task Sub-agents**: Each runs a complete pipeline in isolation
+- **Git**: Provides worktree isolation and branch merging
+
+---
+
+## 4. Behaviour Overview
+
+**Single slug (existing):**
+```
+/implement-feature "slug"
+  → Sequential: Alex → Cass → Nigel → Codey
+  → Commit to current branch
+```
+
+**Multiple slugs (new):**
+```
+/implement-feature slug-a slug-b slug-c
+  → Create worktrees for isolation
+  → Parallel Tasks: each runs full pipeline
+  → Merge successful branches to main
+  → Cleanup worktrees
+```
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- **Worktree creation**: New state - `.claude/worktrees/feat-{slug}/`
+- **Branch creation**: New branches `feature/{slug}` per feature
+- **Merge state**: Successful features merged to main
+- **Conflict state**: Failed merges preserved for manual resolution
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description |
+|------|-------------|
+| Multi-feature detection | `slugs.length > 1` triggers murmuration mode |
+| Worktree isolation | Each feature gets dedicated worktree |
+| Parallel execution | All Task sub-agents spawned in single message |
+| No cross-contamination | Sub-agents work only in their worktree |
+| Merge order | First-completed = first-merged |
+| Conflict handling | Preserve branch, don't force |
+
+---
+
+## 7. Dependencies
+
+- Git 2.5+ (worktree support)
+- Clean working tree before starting
+- Task tool supports concurrent invocations
+- Sufficient context window for multiple sub-agent prompts
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Context usage**: Each parallel Task adds ~2-3k tokens to the prompt
+- **Parallelism limit**: Recommend max 3-5 concurrent features
+- **Failure isolation**: One feature's failure doesn't affect others
+- **Recovery**: Failed worktrees preserved for debugging/retry
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- Task tool executes concurrent calls truly in parallel
+- Sub-agents can write to worktree paths
+- Git merge from worktree branches works as expected
+
+**Open Questions:**
+- What's the practical limit on concurrent Task sub-agents?
+- Should there be a `--max-concurrency` flag?
+- How to handle partial success (some merge, some conflict)?
+
+---
+
+## 10. Impact on System Specification
+
+- Extends the skill's capabilities without changing core agent behavior
+- Murmuration becomes an in-session feature rather than external process
+- CLI `murm` command could detect in-session mode and delegate to skill
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Skip Cass stage** — this is a technical/infrastructure feature.
+
+Direct handover to Nigel:
+- Test multi-slug parsing
+- Test worktree creation/cleanup
+- Test parallel execution (mock Task tool)
+- Test merge success/conflict handling
+
+---
+
+## 12. Change Log
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-03-03 | Initial spec | Enable parallel features via sub-agents | Alex |