murmur8 3.5.0

package/.blueprint/features/feature_parallel-logging/FEATURE_SPEC.md

@@ -0,0 +1,105 @@
+# Feature Specification — Parallel Logging
+
+## 1. Feature Intent
+
+Write each pipeline's output to a dedicated log file instead of interleaving on console. When multiple pipelines run simultaneously, their output becomes unreadable. Logging to files keeps the console clean while preserving full output for debugging.
+
+**Problem:** With 3 pipelines running in parallel, console output is an unreadable mess of interleaved messages from different agents.
+
+**Solution:** Write each pipeline's stdout/stderr to a log file; show only summary status on console.
+
+---
+
+## 2. Scope
+
+### In Scope
+- Log file per pipeline: `.claude/worktrees/feat-{slug}/pipeline.log`
+- Summary status on console (started, completed, failed)
+- `--verbose` flag to also stream to console
+- Timestamps on log entries
+
+### Out of Scope
+- Log rotation
+- Log compression
+- Remote log shipping
+
+---
+
+## 3. Behaviour Overview
+
+### Default (Quiet Console)
+
+```
+$ murmur8 parallel feat-a feat-b feat-c
+
+Starting parallel pipelines...
+
+[10:30:01] feat-a: Started (log: .claude/worktrees/feat-feat-a/pipeline.log)
+[10:30:02] feat-b: Started (log: .claude/worktrees/feat-feat-b/pipeline.log)
+[10:30:03] feat-c: Started (log: .claude/worktrees/feat-feat-c/pipeline.log)
+[10:35:15] feat-b: Completed ✓
+[10:36:22] feat-a: Completed ✓
+[10:38:45] feat-c: Failed ✗ (see log for details)
+
+Summary: 2 completed, 1 failed
+```
+
+### Verbose Mode
+
+```
+$ murmur8 parallel feat-a --verbose
+
+Starting parallel pipelines...
+
+[10:30:01] feat-a: Started
+--- feat-a output ---
+You are Alex, the System Specification Agent...
+[Alex output streams here]
+...
+--- end feat-a output ---
+
+[10:35:15] feat-a: Completed ✓
+```
+
+---
+
+## 4. Log File Format
+
+Location: `.claude/worktrees/feat-{slug}/pipeline.log`
+
+```
+[2026-02-25T10:30:01.123Z] Pipeline started for feat-a
+[2026-02-25T10:30:01.456Z] [stdout] You are Alex, the System Specification Agent...
+[2026-02-25T10:30:02.789Z] [stdout] Reading feature spec...
+[2026-02-25T10:35:15.000Z] [stderr] Warning: some warning
+[2026-02-25T10:35:15.100Z] Pipeline completed with exit code 0
+```
+
+---
+
+## 5. Implementation Notes
+
+- Change `stdio: 'inherit'` to `stdio: 'pipe'`
+- Create write stream to log file
+- Prefix each line with timestamp and stream type
+- On `--verbose`, also pipe to `process.stdout`
+- Console shows only status updates (not full output)
+
+---
+
+## 6. Test Themes
+
+- Log file created in worktree directory
+- Log contains timestamped output
+- Console shows only status by default
+- `--verbose` streams output to console
+- Log preserved on failure for debugging
+- Multiple pipelines don't interleave in logs
+
+---
+
+## 7. Change Log
+
+| Date | Change | Reason |
+|------|--------|--------|
+| 2026-02-25 | Initial spec | Parallel safeguards |

package/.blueprint/features/feature_parallel-preflight/FEATURE_SPEC.md

@@ -0,0 +1,141 @@
+# Feature Specification — Parallel Pre-flight Validation
+
+## 1. Feature Intent
+
+Validate that a batch of features is safe to run in parallel before execution begins. This prevents wasted resources from features that would fail due to conflicts, missing specs, or dependencies.
+
+**Problem:** Users can queue features for parallel execution without knowing if they'll conflict. Discovering issues mid-execution wastes time and creates cleanup work.
+
+**Solution:** Pre-flight validation that checks feature readiness, detects conflicts, and estimates scope before any worktrees are created.
+
+---
+
+## 2. Scope
+
+### In Scope
+- Check feature specs exist and are complete
+- Detect dependencies between features in batch
+- Detect file overlap from implementation plans
+- Estimate scope and warn about timeout risk
+- Integrate with existing dry-run flow
+
+### Out of Scope
+- Automatic dependency resolution
+- Automatic batching suggestions
+- Cross-repo validation
+
+---
+
+## 3. Behaviour Overview
+
+### Pre-flight Check Output
+
+```
+$ murmur8 parallel feat-a feat-b feat-c --dry-run
+
+Pre-flight Validation
+=====================
+
+✓ feat-a: Spec complete, plan exists
+✓ feat-b: Spec complete, plan exists
+✗ feat-c: Missing FEATURE_SPEC.md
+
+Conflict Analysis
+=================
+
+⚠ File overlap detected:
+  • src/utils.js: feat-a, feat-b both modify
+  • bin/cli.js: feat-a, feat-c both modify
+
+Recommendation: Run feat-a alone, then feat-b + feat-c
+
+Scope Estimation
+================
+
+  Feature   | Stories | Tests | Est. Time
+  ----------|---------|-------|----------
+  feat-a    | 3       | 12    | ~15 min
+  feat-b    | 2       | 8     | ~10 min
+  feat-c    | 1       | 4     | ~5 min
+
+Total estimated: ~30 min (parallel: ~15 min)
+
+Proceed? [y/N]
+```
+
+### Validation Failures Block Execution
+
+```
+$ murmur8 parallel feat-a feat-b
+
+Pre-flight Validation
+=====================
+
+✗ feat-a: Missing FEATURE_SPEC.md
+✗ feat-b: Missing user stories
+
+Cannot proceed. Run these commands first:
+  /implement-feature feat-a --pause-after=alex
+  /implement-feature feat-b --pause-after=cass
+```
+
+### Override with --skip-preflight
+
+```
+$ murmur8 parallel feat-a feat-b --skip-preflight
+
+⚠ Skipping pre-flight validation (not recommended)
+
+Starting parallel pipelines...
+```
+
+---
+
+## 4. Implementation Notes
+
+### Validation Checks
+
+1. **Spec Completeness**
+   - FEATURE_SPEC.md exists and has required sections
+   - At least one story-*.md file exists
+   - Test file exists (optional - may be created by pipeline)
+
+2. **Dependency Detection**
+   - Parse feature specs for "depends_on" or similar markers
+   - Scan for references to other feature slugs
+   - Warn if features reference each other
+
+3. **File Overlap Detection**
+   - Parse IMPLEMENTATION_PLAN.md for "Files to Create/Modify" section
+   - Extract file paths from each feature's plan
+   - Flag any files that appear in multiple features
+
+4. **Scope Estimation**
+   - Count stories and acceptance criteria
+   - Count existing tests
+   - Use history averages to estimate duration
+
+### Integration Points
+
+- Called from `runParallel()` before worktree creation
+- Results displayed in dry-run output
+- Blocking by default, override with `--skip-preflight`
+
+---
+
+## 5. Test Themes
+
+- Detects missing feature specs
+- Detects missing stories
+- Detects file overlap from plans
+- Allows override with flag
+- Integrates with dry-run
+- Scope estimation uses history
+
+---
+
+## 6. Change Log
+
+| Date | Change | Reason |
+|------|--------|--------|
+| 2026-02-25 | Initial spec | Upfront validation for parallel safety |

package/.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md

@@ -0,0 +1,239 @@
+# Feature Specification — Pipeline History
+
+## 1. Feature Intent
+
+**Why this feature exists.**
+
+- **Problem being addressed:** Currently, murmur8 provides no visibility into historical pipeline executions. Users cannot see which features have been processed, how long each stage took, or identify patterns in failures.
+- **User need:** Developers want to understand pipeline performance over time, identify bottlenecks, and diagnose recurring failures. This supports continuous improvement of the feature development process.
+- **System purpose alignment:** Per SYSTEM_SPEC.md:Section 8 (Cross-Cutting Concerns:Observability), the system aims for observability via queue status and agent summaries. This feature extends observability to historical data, enabling retrospective analysis.
+
+> This feature reinforces the system's observability goals without altering core pipeline behaviour.
+
+---
+
+## 2. Scope
+
+### In Scope
+
+- Recording execution metrics for each pipeline run (start/end times, duration per stage, success/failure)
+- Persisting history to a JSON file (`.claude/pipeline-history.json`)
+- New CLI command `murmur8 history` with subcommands and flags
+- Display of recent runs, aggregate statistics, and failure analysis
+- Clearing history via CLI
+
+### Out of Scope
+
+- Real-time monitoring or streaming metrics
+- Integration with external monitoring systems (Prometheus, Grafana, etc.)
+- Exporting history to formats other than JSON
+- History synchronisation across machines or repositories
+- Detailed error logs or stack traces (only stage-level failure status)
+
+---
+
+## 3. Actors Involved
+
+### Human User
+
+- **Can do:** View pipeline history via CLI; view aggregate statistics; clear history
+- **Cannot do:** Modify individual history entries; replay failed pipelines from history (out of scope)
+
+### Pipeline Orchestrator (internal component)
+
+- **Can do:** Record execution metrics at stage boundaries; write to history file
+- **Cannot do:** Alter past entries; delete selective entries
+
+---
+
+## 4. Behaviour Overview
+
+### Happy-path behaviour
+
+1. User invokes `/implement-feature "slug"` and pipeline executes normally
+2. At each stage transition (Alex, Cass, Nigel, Codey-plan, Codey-implement), timestamps are recorded
+3. On pipeline completion (success or failure), a history entry is written to `.claude/pipeline-history.json`
+4. User runs `murmur8 history` to view recent executions and statistics
+
+### Key alternatives or branches
+
+- **Pipeline paused:** If `--pause-after` is used, history entry is recorded up to the pause point with status `paused`
+- **Pipeline failure:** If a stage fails, history entry records failure stage and status `failed`
+- **No history file:** On first write, file is created with empty array structure
+- **History clear:** User runs `murmur8 history clear` to remove all entries
+
+### User-visible outcomes
+
+- List of recent pipeline runs with timing and status
+- Success rate percentage across all runs
+- Average duration per stage
+- Most common failure stage (if any failures exist)
+
+---
+
+## 5. State & Lifecycle Interactions
+
+### States entered
+
+- **history_recording:** When pipeline starts, a pending history entry is created in memory
+- **history_persisted:** When pipeline completes/fails/pauses, entry is written to file
+
+### States modified
+
+- Queue state (`.claude/implement-queue.json`) is extended with `startedAt` timestamp for each stage (if not already present)
+
+### This feature is:
+
+- **State-creating:** Creates new history entries per pipeline run
+- **Not state-transitioning:** Does not alter pipeline flow
+- **Not state-constraining:** Does not block pipeline operations
+
+---
+
+## 6. Rules & Decision Logic
+
+### Rule: History Entry Creation
+
+- **Description:** A history entry is created when a pipeline run completes (success), fails, or pauses
+- **Inputs:** Feature slug, stage timestamps, final status
+- **Outputs:** JSON object appended to history array
+- **Deterministic:** Yes
+
+### Rule: Duration Calculation
+
+- **Description:** Duration per stage calculated as difference between stage start and next stage start (or completion time for final stage)
+- **Inputs:** Stage timestamps
+- **Outputs:** Duration in milliseconds for each stage
+- **Deterministic:** Yes
+
+### Rule: Statistics Aggregation
+
+- **Description:** Statistics computed on-read from full history file
+- **Inputs:** All history entries
+- **Outputs:** Success rate, average durations, failure frequency by stage
+- **Deterministic:** Yes
+
+### Rule: Display Limit Default
+
+- **Description:** By default, show last 10 runs; `--all` shows unlimited
+- **Inputs:** Flag presence, history array length
+- **Outputs:** Truncated or full list
+- **Deterministic:** Yes
+
+---
+
+## 7. Dependencies
+
+### System components
+
+- `src/orchestrator.js` — Must emit events or expose hooks for recording stage transitions
+- `bin/cli.js` — Must register new `history` command
+- `.claude/implement-queue.json` — May be read for timing data during pipeline execution
+
+### External systems
+
+- None
+
+### Operational dependencies
+
+- File system access to `.claude/` directory
+- Permissions to write `.claude/pipeline-history.json`
+
+---
+
+## 8. Non-Functional Considerations
+
+### Performance sensitivity
+
+- History file read/write should be efficient; consider file size growth over time
+- ASSUMPTION: Most users will have <100 runs; O(n) aggregation is acceptable
+
+### Audit/logging needs
+
+- History file serves as an audit log of pipeline executions
+- Timestamps must be ISO 8601 format for consistency
+
+### Error tolerance
+
+- If history file is corrupted or unreadable, CLI should warn and allow continuation (no blocking)
+- History recording failure should not abort pipeline execution
+
+### Security implications
+
+- Feature slugs may contain project information; history file should be gitignored
+- No sensitive data (credentials, secrets) should appear in history entries
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+
+- ASSUMPTION: History file will grow at a manageable rate (tens to hundreds of entries)
+- ASSUMPTION: Stage names are stable (alex, cass, nigel, codey-plan, codey-implement)
+- ASSUMPTION: ISO 8601 timestamps are sufficient for duration calculations
+
+### Open Questions
+
+- Should history entries include partial stage data for paused pipelines?
+- Should `--stats` include median duration alongside average?
+- Should there be a `history export` subcommand for CI integration (deferred)?
+
+---
+
+## 10. Impact on System Specification
+
+### Alignment assessment
+
+This feature **reinforces existing system assumptions**:
+
+- Per SYSTEM_SPEC.md:Section 8 (Observability), the system already tracks queue status and completion summaries
+- This feature extends observability to historical analysis without changing core behaviour
+- The queue file structure (`.claude/implement-queue.json`) already captures timestamps; this feature adds persistence beyond current run
+
+### No contradictions identified
+
+The feature does not alter:
+
+- Agent roles or boundaries
+- Pipeline flow or stage order
+- Artifact structures or handoff mechanisms
+
+### Minor extension to system spec
+
+The following addition to SYSTEM_SPEC.md:Section 5 (Core Domain Concepts) may be warranted:
+
+> **History Entry** — A record of a completed pipeline run, including slug, timestamps per stage, duration, and final status. Persisted to `.claude/pipeline-history.json`.
+
+This is flagged as a **non-breaking extension** for consideration.
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story themes
+
+1. **History recording** — Capturing execution data during pipeline runs
+2. **History display** — CLI command for viewing recent runs
+3. **Statistics display** — Aggregate metrics via `--stats` flag
+4. **History management** — Clearing history via `history clear`
+
+### Expected story boundaries
+
+- Recording logic should be a separate story from display logic
+- Statistics computation may be combined with display or separated
+- Clear functionality is a distinct, small story
+
+### Areas needing careful story framing
+
+- The interaction between `--pause-after` and history recording needs precise acceptance criteria
+- Error handling when history file is corrupted should be explicit
+- The "most common failure stage" calculation needs clear definition when there are ties
+
+---
+
+## 12. Change Log (Feature-Level)
+
+| Date       | Change                                | Reason                       | Raised By |
+|------------|---------------------------------------|------------------------------|-----------|
+| 2026-02-24 | Initial feature specification created | Feature request from user    | Alex      |

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

@@ -0,0 +1,71 @@
+# Implementation Plan - Pipeline History
+
+## Summary
+
+Implement pipeline history tracking by creating a new `src/history.js` module that records execution metrics during pipeline runs and provides CLI commands for viewing/managing history. The module will integrate with the existing orchestrator to capture stage timestamps and persist entries to `.claude/pipeline-history.json`. CLI routing in `bin/cli.js` will be extended with a new `history` command supporting subcommands and flags.
+
+---
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/history.js` | Create | Core history module: `recordHistory()`, `displayHistory()`, `showStats()`, `clearHistory()` |
+| `bin/cli.js` | Modify | Add `history` command routing with `--all`, `--stats`, `--force` flags and `clear` subcommand |
+| `src/orchestrator.js` | Modify | Add stage timestamp tracking; call `recordHistory()` on pipeline completion/failure/pause |
+
+---
+
+## Implementation Steps
+
+1. **Create `src/history.js` with file I/O helpers** - `readHistoryFile()`, `writeHistoryFile()`, `ensureHistoryFile()` handling missing/corrupted files gracefully.
+
+2. **Implement `recordHistory(entry)` function** - Accepts history entry object, appends to history array, writes to `.claude/pipeline-history.json`. Wrap in try/catch to log warning on failure without throwing.
+
+3. **Implement `displayHistory(options)` function** - Read history, sort by `completedAt` descending, slice to 10 entries (unless `--all`), format tabular output with color-coded status.
+
+4. **Implement `showStats()` function** - Compute success rate, average duration per stage, total average for successful runs, most common failure stage (handling ties).
+
+5. **Implement `clearHistory(options)` function** - Show confirmation prompt (unless `--force`), reset file to empty array on confirm, display count of removed entries.
+
+6. **Add CLI routing in `bin/cli.js`** - Register `history` command; parse `--all`, `--stats`, `--force` flags; handle `clear` subcommand.
+
+7. **Modify `src/orchestrator.js` to track stage timestamps** - Update `setCurrent()` to record `startedAt`; add `completeStage()` helper to record `completedAt` and compute `durationMs`.
+
+8. **Add `recordPipelineCompletion()` to orchestrator** - Called on success/failure/pause; builds history entry from accumulated stage data and calls `recordHistory()`.
+
+9. **Add `.claude/pipeline-history.json` to `.gitignore`** - Update `src/init.js` to append this pattern during initialization.
+
+10. **Run tests and verify all T-* test IDs pass** - Execute `node --test test/feature_pipeline-history.test.js`.
+
+---
+
+## Data Model
+
+```json
+{
+  "slug": "feature-name",
+  "status": "success | failed | paused",
+  "startedAt": "2026-02-24T10:00:00.000Z",
+  "completedAt": "2026-02-24T10:15:00.000Z",
+  "totalDurationMs": 900000,
+  "stages": {
+    "alex": { "startedAt": "...", "completedAt": "...", "durationMs": 120000 },
+    "cass": { "startedAt": "...", "completedAt": "...", "durationMs": 90000 },
+    "nigel": { "startedAt": "...", "completedAt": "...", "durationMs": 180000 },
+    "codey-plan": { "startedAt": "...", "completedAt": "...", "durationMs": 75000 },
+    "codey-implement": { "startedAt": "...", "completedAt": "...", "durationMs": 255000 }
+  },
+  "failedStage": null,
+  "pausedAfter": null
+}
+```
+
+---
+
+## Risks/Questions
+
+- **Confirmation prompt testing**: Tests will need to mock stdin for `clearHistory()` confirmation; consider using `readline` interface that can be injected for testing.
+- **Color output detection**: Use `process.stdout.isTTY` to determine if colors should be applied; provide fallback for non-TTY environments.
+- **Orchestrator integration point**: The `/implement-feature` skill (SKILL.md) runs via Task tool sub-agents; recording hooks must be called from the skill's completion handler, not just from `src/orchestrator.js`. Verify integration path.
+- **File corruption recovery**: Per AC-4, corrupted history file should not block CLI; implement robust JSON parsing with fallback to empty array after warning.

package/.blueprint/features/feature_pipeline-history/story-clear-history.md

@@ -0,0 +1,73 @@
+# Story — Clear Pipeline History
+
+## User story
+
+As a developer using murmur8, I want to clear the pipeline history so that I can reset metrics or remove stale data.
+
+---
+
+## Context / scope
+
+- New CLI subcommand: `murmur8 history clear`
+- Removes all entries from `.claude/pipeline-history.json`
+- Per FEATURE_SPEC.md:Section 3 (Actors), users can clear history but cannot modify individual entries
+- Destructive action requiring confirmation
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Clear with confirmation**
+- Given `.claude/pipeline-history.json` contains history entries,
+- When I run `murmur8 history clear`,
+- Then I see a confirmation prompt: "This will delete all 25 history entries. Continue? (y/N)"
+- And I must type 'y' or 'yes' to proceed.
+
+**AC-2 — Clear executes on confirmation**
+- Given I confirm the clear action,
+- When the command completes,
+- Then `.claude/pipeline-history.json` is reset to an empty array `[]`,
+- And I see "Pipeline history cleared. 25 entries removed."
+
+**AC-3 — Clear cancelled on decline**
+- Given I decline the confirmation (type 'n', 'no', or press Enter),
+- When the command completes,
+- Then `.claude/pipeline-history.json` remains unchanged,
+- And I see "Clear cancelled. History unchanged."
+
+**AC-4 — Force clear without confirmation**
+- Given `.claude/pipeline-history.json` contains history entries,
+- When I run `murmur8 history clear --force`,
+- Then the history is cleared without a confirmation prompt,
+- And I see "Pipeline history cleared. 25 entries removed."
+
+**AC-5 — Clear empty history**
+- Given `.claude/pipeline-history.json` is empty or does not exist,
+- When I run `murmur8 history clear`,
+- Then I see "No history to clear."
+- And the command exits with code 0.
+
+---
+
+## CLI interaction
+
+```
+$ murmur8 history clear
+This will delete all 25 history entries. Continue? (y/N) y
+Pipeline history cleared. 25 entries removed.
+
+$ murmur8 history clear --force
+Pipeline history cleared. 25 entries removed.
+
+$ murmur8 history clear
+No history to clear.
+```
+
+---
+
+## Out of scope
+
+- Clearing individual entries or filtered subsets
+- Archiving history before clearing
+- Undo/restore functionality
+- Automatic cleanup based on age or count