murmur8 4.2.0 → 4.3.1

package/.blueprint/features/feature_cost-tracking/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,50 @@
+# Implementation Plan — Cost Tracking
+
+## Summary
+
+Implement a cost tracking module (`src/cost.js`) that calculates token costs using configurable pricing, integrate it with the existing history module to persist cost data per stage, and add CLI commands for displaying costs (`history --cost`) and managing pricing configuration (`cost-config`).
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/cost.js` | Create | Core module: cost calculation, formatting, pricing config |
+| `src/commands/cost-config.js` | Create | CLI command for managing pricing configuration |
+| `src/history.js` | Modify | Add `--cost` display support, cost data in formatters |
+| `src/commands/history.js` | Modify | Parse `--cost` flag and pass to display functions |
+| `src/commands/help.js` | Modify | Add `cost-config` command to help output |
+| `.gitignore` | Modify | Add `.claude/cost-config.json` entry |
+
+## Implementation Steps
+
+1. **Create `src/cost.js`** — Implement core functions using `config-factory.js` pattern:
+   - `getDefaultPricing()` — Returns `{ inputPricePerMillion: 3, outputPricePerMillion: 15 }`
+   - `loadPricingConfig()` / `savePricingConfig()` — Read/write `.claude/cost-config.json`
+   - `calculateCost(inputTokens, outputTokens, pricing)` — Formula per FEATURE_SPEC.md Section 6
+   - `formatCost(cost)` — Returns `$X.XXX` or `N/A` for null/undefined
+   - `formatTokens(tokens)` — Returns number with thousands separator or `N/A`
+   - `getCostSummary(stages)` — Generates formatted cost summary table
+
+2. **Create `src/commands/cost-config.js`** — CLI command following `retry-config.js` pattern:
+   - `cost-config` — Display current pricing
+   - `cost-config set <key> <value>` — Update pricing
+   - `cost-config reset` — Reset to defaults
+
+3. **Modify `src/history.js`** — Extend `displayHistory()` and `showStats()`:
+   - Add `cost` option parameter to `displayHistory()`
+   - Display `TOTAL COST` column when `--cost` flag present
+   - Add cost statistics to `showStats()` when cost data available
+   - Handle legacy entries gracefully (display N/A for missing token data)
+
+4. **Modify `src/commands/history.js`** — Parse `--cost` flag:
+   - Pass `{ cost: flags.cost }` to `displayHistory()` and `showStats()`
+
+5. **Modify `src/commands/help.js`** — Add `cost-config` to command list
+
+6. **Update `.gitignore`** — Add `.claude/cost-config.json` entry
+
+## Risks/Questions
+
+- **Token data availability**: Claude Code must expose token usage in Task tool responses. If unavailable, gracefully degrade to N/A.
+- **History schema migration**: No migration needed — new fields are additive and missing data displays as N/A.
+- **Pricing accuracy**: Costs are estimates only; document this in CLI output.

package/.blueprint/features/feature_diff-preview/FEATURE_SPEC.md

@@ -0,0 +1,182 @@
+# Feature Specification — Diff Preview
+
+## 1. Feature Intent
+
+Provide transparency into pipeline-generated changes before committing them.
+
+**Problem:** The auto-commit stage (Step 11) commits all changes without showing users what will be committed. Users may want to review file additions, modifications, and deletions before they become part of the git history.
+
+**Solution:** Before auto-commit, display a summary of all pending changes (staged and unstaged) so users can review and approve or abort.
+
+**System alignment:** Supports the system spec's "Observability" cross-cutting concern and empowers the Human User actor who has "final arbiter" authority over scope and quality.
+
+---
+
+## 2. Scope
+
+### In Scope
+- Show diff summary before auto-commit (single-feature pipeline)
+- Show diff summary before worktree commit (murmuration mode, Step M5.5)
+- Display file counts: additions, modifications, deletions
+- Display file paths for each category
+- Display actual diff content (optionally truncated for large changes)
+- Prompt user to confirm commit, abort, or review full diff
+- `--no-diff-preview` flag to skip (for automation)
+- Integration with `--no-commit` flag (skip preview when commit is skipped)
+
+### Out of Scope
+- Interactive editing of changes before commit
+- Selective staging/unstaging from the preview
+- Diff viewing in external tools (editor integration)
+- Syntax highlighting in diff output
+
+---
+
+## 3. Actors Involved
+
+### Human User
+- **Can:** View diff summary, approve commit, abort commit, request full diff
+- **Cannot:** Edit changes from the preview screen
+
+### Pipeline Orchestrator
+- **Can:** Trigger diff preview, pass result to commit stage
+- **Cannot:** Auto-approve on user's behalf (unless `--no-diff-preview`)
+
+---
+
+## 4. Behaviour Overview
+
+### Single-Feature Pipeline (Step 11)
+
+Before committing, the pipeline:
+
+1. Runs `git status --porcelain` to detect changes
+2. Categorizes changes: Added (A/??), Modified (M), Deleted (D)
+3. Displays summary:
+   ```
+   Changes to commit for feature_user-auth:
+
+   Added (3 files):
+     + .blueprint/features/feature_user-auth/FEATURE_SPEC.md
+     + test/feature_user-auth.test.js
+     + src/auth.js
+
+   Modified (1 file):
+     ~ src/index.js
+
+   Deleted (0 files):
+     (none)
+
+   Total: 4 files changed
+
+   [c]ommit / [a]bort / [d]iff (show full diff)?
+   ```
+4. On 'c': proceed to commit
+5. On 'a': abort pipeline, exit cleanly
+6. On 'd': show full `git diff --staged` output, then re-prompt
+
+### Murmuration Mode (Step M5.5)
+
+For each successful worktree, before committing:
+
+1. Change to worktree directory
+2. Run same diff preview flow
+3. If user aborts one worktree, mark it as "user-aborted" (not "failed")
+4. Continue to next worktree
+
+### Skip Conditions
+
+Diff preview is skipped when:
+- `--no-commit` flag is set (no commit will happen)
+- `--no-diff-preview` flag is set (user opted out)
+- `--yes` flag is set (non-interactive mode)
+- No changes detected (`git status` returns empty)
+
+---
+
+## 5. State & Lifecycle Interactions
+
+**States touched:**
+- Feature enters a new transient state: `awaiting-commit-review`
+- Exits to: `committing` (on approve) or `aborted` (on abort)
+
+**This feature is:** state-constraining (adds a gate before commit)
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description | Deterministic |
+|------|-------------|---------------|
+| Empty diff | Skip preview if no changes detected | Yes |
+| Truncation | Show first 20 files per category; "... and N more" for overflow | Yes |
+| Large diff | For full diff view, paginate if >100 lines | Yes |
+| Abort handling | Exit code 0 (user choice, not error) | Yes |
+
+---
+
+## 7. Dependencies
+
+- Git CLI (`git status`, `git diff`)
+- readline module (for interactive prompt)
+- Existing orchestrator.js or SKILL.md commit flow
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** `git status` and `git diff` are fast; no significant overhead
+- **Error tolerance:** If git commands fail, show error and proceed with prompt
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+- Git working tree is accessible at commit time
+- Terminal supports interactive prompts (or flags are used for CI)
+
+### Open Questions
+- Should diff preview show binary files differently? (Assume: just note "[binary]")
+- Should large diffs auto-truncate in full view? (Assume: yes, with option to show all)
+
+---
+
+## 10. Impact on System Specification
+
+**Reinforces:**
+- Observability (users see what's happening)
+- Human User authority (explicit confirmation)
+
+**Stretches:**
+- Pipeline lifecycle adds a transient state (`awaiting-commit-review`)
+- May need to document this in system spec's lifecycle section
+
+**No contradictions identified.**
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story Themes
+1. **Preview display:** Show diff summary before commit
+2. **User choice:** Confirm, abort, or view full diff
+3. **Skip conditions:** Honor flags to bypass preview
+4. **Murmuration integration:** Per-worktree preview in parallel mode
+
+### Expected Story Boundaries
+- Keep preview display and user interaction in one story
+- Separate story for murmuration integration if complex
+- Flags/skip conditions can be part of the main preview story
+
+### Areas Needing Careful Framing
+- Abort behavior should clearly distinguish user-abort from pipeline failure
+- Full diff view interaction: single prompt or back-and-forth?
+
+---
+
+## 12. Change Log
+
+| Date | Change | Reason |
+|------|--------|--------|
+| 2026-03-04 | Initial spec | Add transparency before auto-commit |

package/.blueprint/features/feature_diff-preview/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,42 @@
+# Implementation Plan: Diff Preview
+
+## Summary
+
+Create a new `src/diff-preview.js` module that provides transparency before auto-commit by displaying pending changes and prompting for user confirmation. The module exports pure functions for parsing git status, formatting summaries, and handling user choices, plus integration functions for the pipeline commit flow.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/diff-preview.js` | Create | Core module with all exported functions |
+| `src/index.js` | Modify | Export diff-preview functions |
+| `src/theme.js` | Modify | Add `user-aborted` status icon |
+| `SKILL.md` | Modify | Document `--no-diff-preview` flag and Step 10.5 |
+
+## Implementation Steps
+
+1. **Create `src/diff-preview.js` skeleton** with all required exports: `parseGitStatus`, `formatDiffSummary`, `shouldSkipPreview`, `parseUserChoice`, `createAbortResult`, `truncateDiff`, `getPreviewState`, `markWorktreeAborted`, `getPromptText`, `hasChanges`, `formatFeatureHeader`.
+
+2. **Implement `parseGitStatus(porcelainOutput)`** - Parse `git status --porcelain` output into `{ added: [], modified: [], deleted: [], total: number }`. Handle status codes: `A`/`??` (added), `M`/` M` (modified), `D`/` D` (deleted).
+
+3. **Implement display functions** - `formatDiffSummary(changes, slug)` with 20-file truncation per category, `formatFeatureHeader(slug)`, and `hasChanges(changes)`.
+
+4. **Implement skip logic** - `shouldSkipPreview({ noCommit, noDiffPreview, yes, hasChanges })` returns true if any skip condition met.
+
+5. **Implement user choice handling** - `parseUserChoice(input)` maps `c/C` to `'commit'`, `a/A` to `'abort'`, `d/D` to `'diff'`, else `null`.
+
+6. **Implement abort/state functions** - `createAbortResult(slug)` returns `{ exitCode: 0, reason: 'user-aborted', slug }`, `getPreviewState()` returns `'awaiting-commit-review'`, `markWorktreeAborted(worktree)` sets status to `'user-aborted'`.
+
+7. **Implement truncation** - `truncateDiff(diffOutput, threshold)` limits to threshold lines with "... N more lines" message.
+
+8. **Implement `getPromptText()`** - Return the interactive prompt string `[c]ommit / [a]bort / [d]iff`.
+
+9. **Update `src/theme.js`** - Add `'user-aborted': '\u25a1'` (or similar) to STATUS_ICONS for murmuration display consistency.
+
+10. **Update `src/index.js`** - Import and export diff-preview functions for programmatic access.
+
+## Risks/Questions
+
+- Git command execution not part of pure functions (caller provides porcelain output)
+- Interactive prompt loop (re-prompt after 'd') handled by integration layer, not tested in unit tests
+- Binary file detection (`[binary]` note) deferred to display integration

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 |