murmur8 4.3.0 → 4.3.1

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

@@ -0,0 +1,216 @@
+# Feature Specification — Cost Tracking
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Users have no visibility into token consumption or estimated costs when running the pipeline
+- Without cost data, users cannot identify expensive stages or optimize prompt efficiency
+- Cost awareness enables informed decisions about when to use `--skip-stories` or other optimizations
+- Aligns with existing observability patterns (history, insights, feedback) in the system spec
+
+> This feature reinforces Section 8 (Cross-Cutting Concerns: Observability) of the System Spec.
+
+---
+
+## 2. Scope
+### In Scope
+- Track input/output tokens per agent stage (alex, cass, nigel, codey-plan, codey-implement)
+- Estimate cost per stage using configurable pricing (default: Claude Sonnet pricing)
+- Store token/cost data in pipeline history alongside existing timing data
+- Display cost summary at pipeline completion
+- Add `--cost` flag to `history` command to show cost breakdowns
+- Add `cost-config` CLI command for pricing configuration
+
+### Out of Scope
+- Real-time token streaming (report after each stage completes)
+- Multi-model pricing within a single run (assumes one model for entire pipeline)
+- Billing integration or payment tracking
+- Token optimization recommendations (covered by insights.js)
+- Cost alerts or budget limits (potential future feature)
+
+---
+
+## 3. Actors Involved
+
+| Actor | Role in Cost Tracking |
+|-------|----------------------|
+| Human User | Views cost summaries, configures pricing, uses data for optimization decisions |
+| Pipeline Orchestrator | Records token usage at each stage transition |
+| History Module | Persists and retrieves cost data |
+| Each Agent (Alex, Cass, Nigel, Codey) | Token consumption is measured but agents are unaware of tracking |
+
+---
+
+## 4. Behaviour Overview
+
+**Happy Path:**
+1. User runs `/implement-feature "slug"`
+2. At each stage completion, orchestrator records tokens used (input + output)
+3. Pipeline completion displays cost summary table
+4. History entry includes token/cost data per stage
+
+**Cost Summary Display (at pipeline end):**
+```
+Cost Summary for feature: user-auth
+
+STAGE            INPUT     OUTPUT    COST
+alex             2,450     1,230     $0.014
+cass             3,100     1,850     $0.019
+nigel            2,800     2,100     $0.018
+codey-plan       1,500       890     $0.009
+codey-impl       4,200     3,500     $0.028
+─────────────────────────────────────────
+TOTAL           14,050     9,570     $0.088
+```
+
+**History with Costs:**
+```bash
+$ murmur8 history --cost
+
+SLUG                STATUS    DURATION   TOTAL COST
+user-auth           success   12m 30s    $0.088
+api-validation      success    8m 15s    $0.062
+cache-layer         failed     4m 22s    $0.031 (failed at: nigel)
+```
+
+**Stats with Costs:**
+```bash
+$ murmur8 history --stats --cost
+
+Pipeline Statistics (based on 15 runs)
+
+METRIC                    VALUE
+...existing stats...
+Avg cost per run          $0.075
+Total cost (all runs)     $1.12
+Most expensive stage      codey-implement ($0.42 total)
+```
+
+---
+
+## 5. State & Lifecycle Interactions
+
+**State additions to history entry:**
+```json
+{
+  "slug": "user-auth",
+  "stages": {
+    "alex": {
+      "durationMs": 45000,
+      "tokens": { "input": 2450, "output": 1230 },
+      "cost": 0.014
+    }
+  },
+  "totalTokens": { "input": 14050, "output": 9570 },
+  "totalCost": 0.088
+}
+```
+
+**Lifecycle:**
+- **State-extending:** Adds new fields to existing history entries
+- No new states created
+- Backward compatible (missing token data displays "N/A")
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description | Deterministic |
+|------|-------------|---------------|
+| Token counting | Sum of input + output tokens per stage | Yes |
+| Cost calculation | `(input_tokens * input_price) + (output_tokens * output_price)` | Yes |
+| Default pricing | Claude Sonnet 3.5: $3/M input, $15/M output | Yes (configurable) |
+| Skipped stages | Record 0 tokens for skipped stages (e.g., Cass when `--skip-stories`) | Yes |
+| Failed stages | Record tokens consumed up to failure point | Yes |
+| Rounding | Costs rounded to 3 decimal places ($0.001 precision) | Yes |
+
+---
+
+## 7. Dependencies
+
+**System Dependencies:**
+- `src/history.js` - Extended to store/retrieve token data
+- `.claude/pipeline-history.json` - Schema extended with token fields
+
+**New Files:**
+- `src/cost.js` - Token counting, cost calculation, formatting
+- `src/commands/cost-config.js` - CLI command for pricing config
+- `.claude/cost-config.json` - Pricing configuration (gitignored)
+
+**Technical Dependencies:**
+- Claude Code must expose token usage in Task tool responses
+- If token data unavailable, feature gracefully degrades to "N/A"
+
+---
+
+## 8. Non-Functional Considerations
+
+| Concern | Consideration |
+|---------|---------------|
+| Performance | Token counting adds negligible overhead (<1ms per stage) |
+| Storage | ~100 bytes additional per history entry |
+| Backward compatibility | Existing history entries without token data display "N/A" |
+| Accuracy | Estimated costs only; actual billing may differ |
+| Privacy | No sensitive data; token counts are numeric |
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- Claude Code Task tool responses include token usage metadata
+- Single pricing model per pipeline run is acceptable
+- Users want cost visibility but not enforcement (no budget limits)
+
+**Open Questions:**
+- How does Claude Code expose token usage? Via response metadata or separate API?
+- Should we support custom pricing for enterprise/volume discounts?
+- Should cost data be included in CSV/JSON exports by default?
+
+---
+
+## 10. Impact on System Specification
+
+**Reinforces existing patterns:**
+- Section 8 (Observability) - Adds cost as new observability dimension
+- Section 9 (Reliability) - Token data helps diagnose token limit failures
+
+**No contradictions identified.**
+
+**Suggested System Spec addition (Section 8):**
+```markdown
+### Cost Visibility
+- Token usage tracked per stage
+- Estimated costs calculated and persisted
+- Cost summaries available via `history --cost`
+```
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+1. **Core tracking** - Record token usage at each stage completion
+2. **Cost calculation** - Apply pricing model to token counts
+3. **Display** - Show cost summary at pipeline end
+4. **History integration** - Store in history, display in `history` command
+5. **Configuration** - `cost-config` command for pricing settings
+
+**Expected story boundaries:**
+- Story 1: Token tracking infrastructure (cost.js, history schema)
+- Story 2: Cost calculation and formatting
+- Story 3: Pipeline completion summary display
+- Story 4: History command integration (`--cost` flag)
+- Story 5: Configuration CLI (`cost-config` command)
+
+**Areas needing careful framing:**
+- Graceful degradation when token data unavailable
+- Backward compatibility with existing history entries
+- Cost display formatting (currency, precision)
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+| 2026-03-04 | Initial spec | Enable cost visibility for pipeline optimization | Alex |

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/README.md

@@ -103,7 +103,9 @@ This updates `.blueprint/agents/`, `.blueprint/templates/`, `.blueprint/ways_of_
 | Command | Description |
 |---------|-------------|
 | `npx murmur8 history` | View recent pipeline runs |
+| `npx murmur8 history --cost` | View runs with cost breakdown |
 | `npx murmur8 history --stats` | View aggregate statistics |
+| `npx murmur8 history --stats --cost` | View stats with cost metrics |
 | `npx murmur8 history --all` | View all runs |
 | `npx murmur8 history clear` | Clear history |
 | `npx murmur8 history export` | Export history as CSV (default) |
@@ -136,6 +138,9 @@ This updates `.blueprint/agents/`, `.blueprint/templates/`, `.blueprint/ways_of_
 | `npx murmur8 stack-config` | View detected tech stack |
 | `npx murmur8 stack-config set <key> <value>` | Modify stack settings (language, frameworks, testRunner, etc.) |
 | `npx murmur8 stack-config reset` | Reset to empty defaults |
+| `npx murmur8 cost-config` | View cost tracking pricing |
+| `npx murmur8 cost-config set <key> <value>` | Modify pricing (inputPrice, outputPrice) |
+| `npx murmur8 cost-config reset` | Reset to default Claude pricing |
 | `npx murmur8 retry-config` | View retry configuration |
 | `npx murmur8 retry-config set <key> <value>` | Modify retry settings |
 | `npx murmur8 retry-config reset` | Reset to defaults |
@@ -155,6 +160,7 @@ Run the pipeline with the `/implement-feature` skill in Claude Code:
 /implement-feature "Your Slug" --no-validate # Skip pre-flight validation
 /implement-feature "Your Slug" --no-history  # Skip history recording
 /implement-feature "Your Slug" --no-commit   # Skip auto-commit
+/implement-feature "Your Slug" --no-diff-preview  # Skip diff preview before commit
 /implement-feature "Your Slug" --pause-after=alex|cass|nigel|codey-plan
 /implement-feature "Your Slug" --with-stories  # Force include Cass stage
 /implement-feature "Your Slug" --skip-stories  # Force skip Cass stage
@@ -243,8 +249,15 @@ The pipeline includes validation, smart routing, feedback loops, and history tra
                               │
                               ▼
 ┌─────────────────────────────────────────────────────────────────┐
+│  Diff Preview (unless --no-diff-preview)                        │
+│  • Show file changes (added/modified/deleted)                   │
+│  • User confirms: commit / abort / view full diff               │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
 │  Auto-commit → Record to History                                │
-│  • Duration, feedback scores, outcome                           │
+│  • Duration, feedback scores, token cost, outcome               │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
@@ -255,7 +268,7 @@ murmur8 includes these built-in modules for observability and self-improvement:
 | Module | Purpose |
 |--------|---------|
 | **validate** | Pre-flight checks before pipeline runs |
-| **history** | Records execution data (timing, status, feedback) |
+| **history** | Records execution data (timing, status, feedback, cost) |
 | **insights** | Analyzes patterns, detects bottlenecks, recommends improvements |
 | **retry** | Smart retry strategies based on failure history |
 | **feedback** | Agent-to-agent quality assessment with correlation tracking |
@@ -265,6 +278,8 @@ murmur8 includes these built-in modules for observability and self-improvement:
 | **tools** | Tool schemas and validation for Claude native features |
 | **murm** | Murmuration pipeline execution using git worktrees |
 | **stack** | Configurable tech stack detection and configuration |
+| **cost** | Token usage tracking and cost estimation per stage |
+| **diff-preview** | Pre-commit change review with user confirmation |
 
 ### How They Work Together
 
@@ -273,8 +288,12 @@ Pipeline Run
      │
      ├──► history.js records timing at each stage
      │
+     ├──► cost.js tracks token usage per stage
+     │
      ├──► feedback.js collects quality ratings between stages
      │
+     ├──► diff-preview.js shows changes before commit
+     │
      └──► On completion/failure, data stored in pipeline-history.json
                               │
                               ▼
@@ -326,6 +345,7 @@ your-project/
 │   ├── pipeline-history.json      # Execution history (gitignored)
 │   ├── retry-config.json          # Retry configuration (gitignored)
 │   ├── feedback-config.json       # Feedback thresholds (gitignored)
+│   ├── cost-config.json           # Cost tracking pricing (gitignored)
 │   ├── murm-config.json            # Murmuration execution config (gitignored)
 │   ├── murm-queue.json             # Murmuration pipeline state (gitignored)
 │   ├── stack-config.json          # Tech stack configuration (gitignored)
@@ -419,6 +439,44 @@ Version 2.7 introduces several optimizations to reduce token usage:
 
 **Total estimated savings: 10,000+ tokens per pipeline run** (more for technical features)
 
+## Cost Tracking
+
+Track token usage and estimated costs per pipeline stage:
+
+```bash
+# View costs in history
+npx murmur8 history --cost
+
+SLUG                STATUS    DURATION   TOTAL COST
+user-auth           success   12m 30s    $0.088
+api-validation      success    8m 15s    $0.062
+
+# View cost statistics
+npx murmur8 history --stats --cost
+
+Avg cost per run:        $0.075
+Total cost (all runs):   $1.12
+Most expensive stage:    codey-implement
+```
+
+### Configuration
+
+Default pricing uses Claude Sonnet rates ($3/M input, $15/M output):
+
+```bash
+# View current pricing
+npx murmur8 cost-config
+
+# Customize pricing (per million tokens)
+npx murmur8 cost-config set inputPrice 3
+npx murmur8 cost-config set outputPrice 15
+
+# Reset to defaults
+npx murmur8 cost-config reset
+```
+
+Cost data is stored in `pipeline-history.json` alongside timing and feedback data.
+
 ## Murmuration
 
 Run multiple feature pipelines simultaneously using git worktrees for isolation. Each feature gets its own worktree and branch, allowing true parallel development without conflicts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "murmur8",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "description": "Multi-agent workflow framework for automated feature development",
   "main": "src/index.js",
   "bin": {

package/src/commands/cost-config.js

@@ -0,0 +1,28 @@
+/**
+ * cost-config command - Manage pricing configuration for cost tracking
+ */
+const { displayConfig, setConfigValue, resetConfig } = require('../cost');
+
+const description = 'Manage pricing configuration for cost tracking';
+
+async function run(args) {
+  const subArg = args[1];
+
+  if (subArg === 'set') {
+    const key = args[2];
+    const value = args[3];
+    if (!key || !value) {
+      console.error('Usage: cost-config set <key> <value>');
+      console.error('Valid keys: inputPricePerMillion, outputPricePerMillion');
+      process.exit(1);
+    }
+    setConfigValue(key, value);
+  } else if (subArg === 'reset') {
+    resetConfig();
+    console.log('Cost configuration reset to defaults.');
+  } else {
+    displayConfig();
+  }
+}
+
+module.exports = { run, description };

package/src/commands/help.js

@@ -19,6 +19,8 @@ Commands:
   history               View recent pipeline runs (last 10 by default)
   history --all         View all pipeline runs
   history --stats       View aggregate statistics
+  history --cost        View history with total cost column
+  history --stats --cost  View statistics with cost metrics
   history clear         Clear all pipeline history (with confirmation)
   history clear --force Clear all pipeline history (no confirmation)
   history export        Export history as CSV (default) or JSON
@@ -42,6 +44,9 @@ Commands:
   stack-config          View current tech stack configuration
   stack-config set <key> <value>  Modify a config value (language, runtime, frameworks, etc.)
   stack-config reset    Reset tech stack configuration to defaults
+  cost-config           View current pricing configuration for cost tracking
+  cost-config set <key> <value>  Modify a config value (inputPricePerMillion, outputPricePerMillion)
+  cost-config reset     Reset pricing configuration to defaults
   murm <slugs...>       Run multiple feature pipelines in parallel (murmuration)
   murm <slugs...> --dry-run  Show execution plan without running
   murm <slugs...> --yes      Skip confirmation prompt

package/src/commands/history.js

@@ -33,9 +33,9 @@ async function run(args) {
       console.log(result.output);
     }
   } else if (flags.stats) {
-    showStats();
+    showStats({ cost: flags.cost });
   } else {
-    displayHistory({ all: flags.all });
+    displayHistory({ all: flags.all, cost: flags.cost });
   }
 }
 

package/src/commands/utils.js

@@ -17,6 +17,7 @@ function parseFlags(args) {
     if (arg === '--failures') flags.failures = true;
     if (arg === '--json') flags.json = true;
     if (arg === '--feedback') flags.feedback = true;
+    if (arg === '--cost') flags.cost = true;
   }
   return flags;
 }

package/src/cost.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const { createConfigModule } = require('./config-factory');
+
+const DEFAULT_INPUT_PRICE = 3;
+const DEFAULT_OUTPUT_PRICE = 15;
+
+const costConfig = createConfigModule({
+  name: 'Cost',
+  file: '.claude/cost-config.json',
+  defaults: {
+    inputPricePerMillion: DEFAULT_INPUT_PRICE,
+    outputPricePerMillion: DEFAULT_OUTPUT_PRICE
+  },
+  validators: {
+    inputPricePerMillion: (v) => v >= 0 || 'Must be non-negative',
+    outputPricePerMillion: (v) => v >= 0 || 'Must be non-negative'
+  }
+});
+
+function getDefaultPricing() {
+  return {
+    inputPricePerMillion: DEFAULT_INPUT_PRICE,
+    outputPricePerMillion: DEFAULT_OUTPUT_PRICE
+  };
+}
+
+function loadPricingConfig() {
+  return costConfig.read();
+}
+
+function savePricingConfig(config) {
+  costConfig.write(config);
+}
+
+function calculateCost(inputTokens, outputTokens, pricing = getDefaultPricing()) {
+  const inputCost = (inputTokens / 1_000_000) * pricing.inputPricePerMillion;
+  const outputCost = (outputTokens / 1_000_000) * pricing.outputPricePerMillion;
+  return Math.round((inputCost + outputCost) * 1000) / 1000;
+}
+
+function formatCost(cost) {
+  if (cost === null || cost === undefined) return 'N/A';
+  return `$${cost.toFixed(3)}`;
+}
+
+function formatTokens(tokens) {
+  if (tokens === null || tokens === undefined) return 'N/A';
+  return tokens.toLocaleString();
+}
+
+function getCostSummary(stages, pricing = loadPricingConfig()) {
+  const lines = [];
+  let totalInput = 0;
+  let totalOutput = 0;
+  let totalCost = 0;
+
+  for (const [name, data] of Object.entries(stages)) {
+    if (data && data.tokens) {
+      const input = data.tokens.input || 0;
+      const output = data.tokens.output || 0;
+      const cost = data.cost !== undefined ? data.cost : calculateCost(input, output, pricing);
+
+      totalInput += input;
+      totalOutput += output;
+      totalCost += cost;
+
+      lines.push({
+        stage: name,
+        input,
+        output,
+        cost
+      });
+    }
+  }
+
+  return {
+    stages: lines,
+    totals: {
+      input: totalInput,
+      output: totalOutput,
+      cost: totalCost
+    }
+  };
+}
+
+function displayCostSummary(slug, stages) {
+  const summary = getCostSummary(stages);
+
+  console.log(`\nCost Summary for feature: ${slug}\n`);
+  console.log('STAGE            INPUT     OUTPUT    COST');
+
+  for (const s of summary.stages) {
+    const stage = s.stage.padEnd(16);
+    const input = formatTokens(s.input).padStart(9);
+    const output = formatTokens(s.output).padStart(10);
+    const cost = formatCost(s.cost).padStart(8);
+    console.log(`${stage} ${input} ${output}    ${cost}`);
+  }
+
+  console.log('─'.repeat(45));
+  const totalStage = 'TOTAL'.padEnd(16);
+  const totalInput = formatTokens(summary.totals.input).padStart(9);
+  const totalOutput = formatTokens(summary.totals.output).padStart(10);
+  const totalCost = formatCost(summary.totals.cost).padStart(8);
+  console.log(`${totalStage} ${totalInput} ${totalOutput}    ${totalCost}`);
+}
+
+module.exports = {
+  CONFIG_FILE: costConfig.CONFIG_FILE,
+  getDefaultPricing,
+  loadPricingConfig,
+  savePricingConfig,
+  calculateCost,
+  formatCost,
+  formatTokens,
+  getCostSummary,
+  displayCostSummary,
+  displayConfig: costConfig.display,
+  setConfigValue: costConfig.setValue,
+  resetConfig: costConfig.reset
+};

package/src/diff-preview.js

@@ -0,0 +1,165 @@
+'use strict';
+
+function parseGitStatus(porcelainOutput) {
+  const added = [];
+  const modified = [];
+  const deleted = [];
+
+  if (!porcelainOutput || porcelainOutput.trim() === '') {
+    return { added, modified, deleted, total: 0 };
+  }
+
+  const lines = porcelainOutput.trim().split('\n');
+  for (const line of lines) {
+    if (line.length < 3) continue;
+
+    const statusCode = line.substring(0, 2);
+    const filePath = line.substring(3);
+
+    if (statusCode === 'A ' || statusCode === '??') {
+      added.push(filePath);
+    } else if (statusCode === 'M ' || statusCode === ' M') {
+      modified.push(filePath);
+    } else if (statusCode === 'D ' || statusCode === ' D') {
+      deleted.push(filePath);
+    }
+  }
+
+  return {
+    added,
+    modified,
+    deleted,
+    total: added.length + modified.length + deleted.length
+  };
+}
+
+function formatDiffSummary(changes, slug) {
+  const lines = [];
+  const MAX_FILES = 20;
+
+  lines.push(formatFeatureHeader(slug));
+  lines.push('');
+
+  const addedLabel = `Added (${changes.added.length} file${changes.added.length === 1 ? '' : 's'})`;
+  lines.push(addedLabel);
+  if (changes.added.length === 0) {
+    lines.push('  (none)');
+  } else {
+    const displayFiles = changes.added.slice(0, MAX_FILES);
+    for (const file of displayFiles) {
+      lines.push(`  + ${file}`);
+    }
+    if (changes.added.length > MAX_FILES) {
+      lines.push(`  ... and ${changes.added.length - MAX_FILES} more`);
+    }
+  }
+  lines.push('');
+
+  const modifiedLabel = `Modified (${changes.modified.length} file${changes.modified.length === 1 ? '' : 's'})`;
+  lines.push(modifiedLabel);
+  if (changes.modified.length === 0) {
+    lines.push('  (none)');
+  } else {
+    const displayFiles = changes.modified.slice(0, MAX_FILES);
+    for (const file of displayFiles) {
+      lines.push(`  ~ ${file}`);
+    }
+    if (changes.modified.length > MAX_FILES) {
+      lines.push(`  ... and ${changes.modified.length - MAX_FILES} more`);
+    }
+  }
+  lines.push('');
+
+  const deletedLabel = `Deleted (${changes.deleted.length} file${changes.deleted.length === 1 ? '' : 's'})`;
+  lines.push(deletedLabel);
+  if (changes.deleted.length === 0) {
+    lines.push('  (none)');
+  } else {
+    const displayFiles = changes.deleted.slice(0, MAX_FILES);
+    for (const file of displayFiles) {
+      lines.push(`  - ${file}`);
+    }
+    if (changes.deleted.length > MAX_FILES) {
+      lines.push(`  ... and ${changes.deleted.length - MAX_FILES} more`);
+    }
+  }
+  lines.push('');
+
+  lines.push(`Total: ${changes.total} files changed`);
+
+  return lines.join('\n');
+}
+
+function formatFeatureHeader(slug) {
+  return `--- Changes to commit for feature: ${slug} ---`;
+}
+
+function hasChanges(changes) {
+  return changes.total > 0;
+}
+
+function shouldSkipPreview({ noCommit, noDiffPreview, yes, hasChanges }) {
+  if (noCommit) return true;
+  if (noDiffPreview) return true;
+  if (yes) return true;
+  if (!hasChanges) return true;
+  return false;
+}
+
+function parseUserChoice(input) {
+  if (!input || typeof input !== 'string') return null;
+  const normalized = input.toLowerCase().trim();
+  if (normalized === 'c') return 'commit';
+  if (normalized === 'a') return 'abort';
+  if (normalized === 'd') return 'diff';
+  return null;
+}
+
+function createAbortResult(slug) {
+  return {
+    exitCode: 0,
+    reason: 'user-aborted',
+    slug
+  };
+}
+
+function truncateDiff(diffOutput, threshold) {
+  if (!diffOutput) return diffOutput;
+  const lines = diffOutput.split('\n');
+  if (lines.length <= threshold) {
+    return diffOutput;
+  }
+  const truncated = lines.slice(0, threshold);
+  const remaining = lines.length - threshold;
+  truncated.push(`... ${remaining} more lines`);
+  return truncated.join('\n');
+}
+
+function getPreviewState() {
+  return 'awaiting-commit-review';
+}
+
+function markWorktreeAborted(worktree) {
+  return {
+    ...worktree,
+    status: 'user-aborted'
+  };
+}
+
+function getPromptText() {
+  return '[c]ommit / [a]bort / [d]iff';
+}
+
+module.exports = {
+  parseGitStatus,
+  formatDiffSummary,
+  formatFeatureHeader,
+  hasChanges,
+  shouldSkipPreview,
+  parseUserChoice,
+  createAbortResult,
+  truncateDiff,
+  getPreviewState,
+  markWorktreeAborted,
+  getPromptText
+};

package/src/history.js

@@ -195,8 +195,14 @@ function formatDate(isoString) {
   return date.toISOString().replace('T', ' ').slice(0, 19);
 }
 
+function formatCostValue(cost) {
+  if (cost === null || cost === undefined) return 'N/A';
+  return `$${cost.toFixed(3)}`;
+}
+
 function displayHistory(options = {}) {
   const showAll = options.all || false;
+  const showCost = options.cost || false;
   const useColor = options.color !== false && process.stdout.isTTY;
 
   const history = readHistoryFile();
@@ -220,7 +226,11 @@ function displayHistory(options = {}) {
   const showing = entries.length;
 
   console.log(`\nPipeline History (showing ${showing} of ${total} runs)\n`);
-  console.log('  SLUG                STATUS    DATE                  DURATION');
+  if (showCost) {
+    console.log('  SLUG                STATUS    DURATION   TOTAL COST');
+  } else {
+    console.log('  SLUG                STATUS    DATE                  DURATION');
+  }
 
   for (const entry of entries) {
     const slug = entry.slug.padEnd(18);
@@ -243,7 +253,12 @@ function displayHistory(options = {}) {
       suffix = ` (paused at: ${entry.pausedAfter})`;
     }
 
-    console.log(`  ${slug}  ${status}  ${date}   ${duration}${suffix}`);
+    if (showCost) {
+      const costDisplay = formatCostValue(entry.totalCost).padEnd(10);
+      console.log(`  ${slug}  ${status}  ${duration.padEnd(9)}  ${costDisplay}${suffix}`);
+    } else {
+      console.log(`  ${slug}  ${status}  ${date}   ${duration}${suffix}`);
+    }
   }
 
   if (!showAll && total > 10) {
@@ -252,7 +267,8 @@ function displayHistory(options = {}) {
   console.log(`Run 'murmur8 history --stats' for aggregate statistics.`);
 }
 
-function showStats() {
+function showStats(options = {}) {
+  const showCost = options.cost || false;
   const history = readHistoryFile();
 
   if (history.error === 'corrupted') {
@@ -285,6 +301,38 @@ function showStats() {
     console.log(`  Avg pipeline duration     ${formatDuration(avgTotal)}`);
   }
 
+  if (showCost) {
+    const runsWithCost = history.filter(e => e.totalCost !== undefined);
+    if (runsWithCost.length > 0) {
+      const totalCostAll = runsWithCost.reduce((sum, e) => sum + e.totalCost, 0);
+      const avgCost = totalCostAll / runsWithCost.length;
+      console.log(`  Avg cost per run          ${formatCostValue(avgCost)}`);
+      console.log(`  Total cost (all runs)     ${formatCostValue(totalCostAll)}`);
+
+      const stages = ['alex', 'cass', 'nigel', 'codey-plan', 'codey-implement'];
+      const stageCosts = {};
+      for (const stage of stages) {
+        stageCosts[stage] = 0;
+      }
+      for (const entry of runsWithCost) {
+        if (entry.stages) {
+          for (const stage of stages) {
+            if (entry.stages[stage] && entry.stages[stage].cost !== undefined) {
+              stageCosts[stage] += entry.stages[stage].cost;
+            }
+          }
+        }
+      }
+      const maxCost = Math.max(...Object.values(stageCosts));
+      const mostExpensive = Object.entries(stageCosts)
+        .filter(([, cost]) => cost === maxCost)
+        .map(([stage]) => stage);
+      if (mostExpensive.length > 0 && maxCost > 0) {
+        console.log(`  Most expensive stage      ${mostExpensive[0]} (${formatCostValue(maxCost)} total)`);
+      }
+    }
+  }
+
   const stages = ['alex', 'cass', 'nigel', 'codey-plan', 'codey-implement'];
   const stageStats = {};
   const failureCounts = {};

package/src/index.js

@@ -81,6 +81,19 @@ const {
   detectStackConfig,
   displayStackConfig
 } = require('./stack');
+const {
+  parseGitStatus,
+  formatDiffSummary,
+  formatFeatureHeader,
+  hasChanges,
+  shouldSkipPreview,
+  parseUserChoice,
+  createAbortResult,
+  truncateDiff,
+  getPreviewState,
+  markWorktreeAborted,
+  getPromptText
+} = require('./diff-preview');
 const tools = require('./tools');
 const theme = require('./theme');
 
@@ -149,6 +162,18 @@ module.exports = {
   tools,
   // Theme module (murmuration visual theming)
   theme,
+  // Diff preview exports
+  parseGitStatus,
+  formatDiffSummary,
+  formatFeatureHeader,
+  hasChanges,
+  shouldSkipPreview,
+  parseUserChoice,
+  createAbortResult,
+  truncateDiff,
+  getPreviewState,
+  markWorktreeAborted,
+  getPromptText,
   // Interactive mode exports
   parseInteractiveFlags,
   shouldEnterInteractiveMode,

package/src/theme.js

@@ -50,7 +50,8 @@ const STATUS_ICONS = {
   'murm_complete': '\u2713',      // ✓
   'murm_failed': '\u2717',        // ✗
   'merge_conflict': '\u26a0',     // ⚠
-  'aborted': '\u25a0'             // ■
+  'aborted': '\u25a0',            // ■
+  'user-aborted': '\u25a1'        // □
 };
 
 // --- Spinner ---