murmur8 4.1.1 → 4.3.0

package/.blueprint/agents/AGENT_SPECIFICATION_ALEX.md

@@ -8,6 +8,7 @@ inputs:
 outputs:
   - feature_spec
   - system_spec
+  - feature_backlog
 ---
 
 # Agent: Alex — System Specification & Chief-of-Staff
@@ -74,7 +75,36 @@ Once drafted, the feature specification is handed to **Cass** for user story ela
 
 ---
 
-### 3. Living Collaboration with Cass (BA)
+### 3. Feature Backlog Ownership
+
+Alex owns the **Feature Backlog** at `.blueprint/features/BACKLOG.md` — a prioritised list of features ready for implementation.
+
+**Template:** `.blueprint/templates/BACKLOG_TEMPLATE.md`
+
+**Format (token-efficient table):**
+```markdown
+| Status | P | E | Slug | Description |
+|--------|---|---|------|-------------|
+| ⏳ | P1 | M | user-auth | Login and registration flow |
+```
+
+**When to create/update:**
+- After creating a system spec — propose initial feature breakdown
+- After completing a feature — pipeline removes entry automatically
+- When scope changes — reprioritise and update descriptions
+
+**Prioritisation criteria:**
+- Business value and user impact
+- Dependencies (what must come first?)
+- Technical risk (surface unknowns early)
+
+**Status icons:** ⏳ ready, 🚧 in progress, ❓ needs clarification
+
+Alex keeps the backlog aligned with the system specification. If a proposed feature contradicts the system design, Alex flags it rather than adding it silently.
+
+---
+
+### 4. Living Collaboration with Cass (BA)
 Alex and Cass operate in a **continuous, collaborative loop**:
 - Cass may query, challenge, or request refinement of a specification before writing stories
 - Alex clarifies intent, resolves ambiguities, or adjusts the specification where appropriate
@@ -89,7 +119,7 @@ Alex does **not** silently accept spec drift.
 
 ---
 
-### 4. Conceptual Coherence Guardian (Hover Mode)
+### 5. Conceptual Coherence Guardian (Hover Mode)
 After initial specification and story creation, Alex remains active as a **conceptual coherence guardian**.
 
 Alex reacts to:
@@ -109,7 +139,7 @@ When meaningful change is detected, Alex:
 
 ---
 
-### 5. Managing Evolution & Breaking Change Proposals
+### 6. Managing Evolution & Breaking Change Proposals
 When a feature exposes a flaw or limitation in the system specification:
 - Alex may propose a **breaking or structural change** to the system spec
 - Alex must clearly articulate:

package/.blueprint/features/feature_config-factory/FEATURE_SPEC.md

@@ -0,0 +1,138 @@
+# Feature Specification — Config Factory
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Four config modules (retry, feedback, murm, stack) share identical patterns
+- Each implements: `getDefaultConfig()`, `readConfig()`, `writeConfig()`, `displayConfig()`, `setConfigValue()`, `resetConfig()`
+- ~80 lines of boilerplate duplicated 4 times (~320 lines total)
+- Inconsistent validation and error handling across modules
+- Adding a new config module requires copying boilerplate
+
+> Technical refactoring feature — consolidate to a factory pattern.
+
+---
+
+## 2. Scope
+### In Scope
+- Create `src/config-factory.js` with `createConfigModule(options)` factory
+- Refactor retry.js, feedback.js, stack.js to use the factory
+- Refactor murm.js config functions to use the factory
+- Standardize validation, error messages, and display formatting
+- Preserve all existing config behaviour exactly
+
+### Out of Scope
+- Adding new config modules
+- Changing config file locations or formats
+- Modifying default values
+- Adding new config keys
+
+---
+
+## 3. Actors Involved
+**Who interacts with this feature.**
+
+- **Developer**: Creates new config modules with minimal boilerplate
+- **CLI User**: No change in experience — all config commands work identically
+
+---
+
+## 4. Behaviour Overview
+**What the feature does, conceptually.**
+
+The factory creates a config module with standard methods:
+
+```javascript
+const myConfig = createConfigModule({
+  name: 'my-config',
+  file: '.claude/my-config.json',
+  defaults: { key1: 'value1', key2: 42 },
+  validators: {
+    key1: (v) => typeof v === 'string',
+    key2: (v) => Number.isInteger(v) && v > 0
+  },
+  formatters: {
+    key2: (v) => `${v} items`
+  }
+});
+
+// Returns: { read, write, reset, display, setValue, getDefault, CONFIG_FILE }
+```
+
+Each existing config module becomes a thin wrapper calling the factory.
+
+---
+
+## 5. State & Lifecycle Interactions
+**How this feature touches the system lifecycle.**
+
+- No state changes — pure refactoring
+- Config files remain in same locations
+- No runtime behaviour differences
+
+---
+
+## 6. Rules & Decision Logic
+**New or exercised rules.**
+
+| Rule | Description |
+|------|-------------|
+| Default merging | Factory merges missing keys from defaults on read |
+| Validation | Factory validates values before write using validators map |
+| Display format | Factory uses formatters map or falls back to default display |
+| Error messages | Standardized format: `Invalid value for {key}: {value}. {reason}` |
+| Array handling | Arrays validated and displayed consistently (JSON parse for set) |
+
+---
+
+## 7. Dependencies
+**What this feature relies on.**
+
+- Node.js `fs` module (already used)
+- No new external dependencies
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Code reduction**: ~200+ lines removed across 4 modules
+- **Consistency**: Identical error messages and validation across all configs
+- **Extensibility**: New config modules require ~10 lines instead of ~80
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- All four config modules can use the same factory pattern
+- Specialized validation (like feedback's issueMappings) can be handled via validators
+
+**Open Questions:**
+- Should murm.js config functions be split to a separate file or remain inline?
+- Should the factory support nested config objects (like retry's `strategies`)?
+
+---
+
+## 10. Impact on System Specification
+
+- No impact — internal refactoring only
+- Public APIs of all config modules remain unchanged
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Skip Cass stage** — this is a technical refactoring feature with no user stories needed.
+
+Direct handover to Nigel for test creation:
+- Tests should verify all config commands work after refactoring
+- Tests should verify validation errors are consistent
+- Tests should verify display output format is preserved
+- Tests should verify default values are unchanged
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-03-03 | Initial spec | DRY up config modules | Alex |

package/.blueprint/features/feature_config-factory/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,187 @@
+# Implementation Plan: Config Factory
+
+## Overview
+Create a factory function to eliminate ~320 lines of duplicated boilerplate across four config modules (retry.js, feedback.js, stack.js, murm.js).
+
+## Step 1: Create `src/config-factory.js`
+
+Create the factory module with the following structure:
+
+```js
+function createConfigModule(options) {
+  const { name, file, defaults, validators = {}, formatters = {}, arrayKeys = [] } = options;
+
+  return {
+    CONFIG_FILE: file,
+    getDefault: () => ({ ...defaults }),
+    read: () => { /* merge defaults, handle errors */ },
+    write: (config) => { /* ensure dir, write JSON */ },
+    reset: () => { /* write defaults */ },
+    setValue: (key, value) => { /* validate, write */ },
+    display: () => { /* format and log */ }
+  };
+}
+```
+
+### Factory Methods Detail
+
+| Method | Behavior |
+|--------|----------|
+| `getDefault()` | Return shallow copy of defaults |
+| `read()` | Return defaults if missing/corrupted, merge missing keys |
+| `write(config)` | Create dir if needed, write JSON with 2-space indent |
+| `reset()` | Call write(getDefault()) |
+| `setValue(key, value)` | Validate key exists, parse arrays, run validator, write |
+| `display()` | Log name header, iterate keys with formatters |
+
+### Validation Logic
+```js
+setValue(key, value) {
+  if (!(key in defaults)) throw Error(`Unknown config key: ${key}. Valid keys: ...`);
+
+  let parsed = value;
+  if (arrayKeys.includes(key)) {
+    parsed = JSON.parse(value); // throws on invalid
+    if (!Array.isArray(parsed)) throw Error(`${key} must be a JSON array`);
+  } else if (typeof defaults[key] === 'number') {
+    parsed = parseFloat(value);
+  } else if (typeof defaults[key] === 'boolean') {
+    parsed = value === 'true';
+  }
+
+  if (validators[key]) {
+    const result = validators[key](parsed);
+    if (result !== true) {
+      throw Error(`Invalid value for ${key}: ${value}. ${result}`);
+    }
+  }
+
+  const config = read();
+  config[key] = parsed;
+  write(config);
+}
+```
+
+## Step 2: Refactor retry.js
+
+Keep existing business logic functions (calculateFailureRate, recommendStrategy, etc.).
+Replace config boilerplate with factory:
+
+```js
+const { createConfigModule } = require('./config-factory');
+
+const configModule = createConfigModule({
+  name: 'Retry',
+  file: '.claude/retry-config.json',
+  defaults: {
+    maxRetries: 3,
+    windowSize: 10,
+    highFailureThreshold: 0.2,
+    strategies: { /* ... */ }
+  },
+  validators: {
+    maxRetries: (v) => Number.isInteger(v) && v >= 0 ? true : 'must be a non-negative integer',
+    windowSize: (v) => Number.isInteger(v) && v >= 1 ? true : 'must be a positive integer',
+    highFailureThreshold: (v) => v >= 0 && v <= 1 ? true : 'must be between 0 and 1'
+  }
+});
+
+// Re-export with same names for backward compatibility
+const {
+  CONFIG_FILE,
+  getDefault: getDefaultConfig,
+  read: readConfig,
+  write: writeConfig,
+  reset: resetConfig,
+  display: displayConfig,
+  setValue: setConfigValue
+} = configModule;
+```
+
+## Step 3: Refactor feedback.js
+
+Similar pattern. Keep validateFeedback, shouldPause, parseFeedbackFromOutput, normalizeFeedbackKeys.
+
+```js
+const configModule = createConfigModule({
+  name: 'Feedback',
+  file: '.claude/feedback-config.json',
+  defaults: {
+    minRatingThreshold: 3.0,
+    enabled: true,
+    issueMappings: { /* ... */ }
+  },
+  validators: {
+    minRatingThreshold: (v) => v >= 1.0 && v <= 5.0 ? true : 'must be between 1.0 and 5.0',
+    enabled: (v) => typeof v === 'boolean' ? true : 'must be true or false'
+  }
+});
+```
+
+## Step 4: Refactor stack.js
+
+Keep detectStackConfig. Note: stack uses `*StackConfig` naming convention.
+
+```js
+const configModule = createConfigModule({
+  name: 'Stack',
+  file: '.claude/stack-config.json',
+  defaults: {
+    language: '', runtime: '', packageManager: '',
+    frameworks: [], testRunner: '', testCommand: '',
+    linter: '', tools: []
+  },
+  arrayKeys: ['frameworks', 'tools']
+});
+
+// Alias exports with Stack suffix for backward compatibility
+const getDefaultStackConfig = configModule.getDefault;
+const readStackConfig = configModule.read;
+// etc.
+```
+
+## Step 5: Refactor murm.js Config Functions
+
+Murm.js has additional complexity (migrations, special merge logic). Keep using factory for core operations but preserve migration logic.
+
+```js
+const configModule = createConfigModule({
+  name: 'Murmuration',
+  file: '.claude/murm-config.json',
+  defaults: {
+    maxConcurrency: 3, maxFeatures: 10, timeout: 30,
+    minDiskSpaceMB: 500, cli: 'npx claude',
+    skill: '/implement-feature', skillFlags: '--no-commit',
+    worktreeDir: '.claude/worktrees', queueFile: '.claude/murm-queue.json'
+  },
+  validators: {
+    maxConcurrency: (v) => Number.isInteger(v) && v >= 1 ? true : 'must be a positive integer',
+    timeout: (v) => Number.isInteger(v) && v >= 1 ? true : 'must be a positive integer'
+  },
+  formatters: {
+    timeout: (v) => `${v} min`
+  }
+});
+```
+
+Note: readMurmConfig needs to preserve migration logic for legacy files.
+
+## Step 6: Run Tests
+
+```bash
+node --test test/feature_config-factory.test.js
+```
+
+Fix any failures, iterate until all 19 tests pass.
+
+## Files Modified
+- `src/config-factory.js` (new)
+- `src/retry.js` (refactored)
+- `src/feedback.js` (refactored)
+- `src/stack.js` (refactored)
+- `src/murm.js` (refactored config functions)
+
+## Risk Mitigation
+- All existing exports preserved with same names
+- Business logic functions untouched
+- Tests verify backward compatibility

package/.blueprint/features/feature_config-factory/handoff-nigel.md

@@ -0,0 +1,57 @@
+# Nigel Handoff: Config Factory
+
+## Summary
+Created test suite for the config-factory feature with 19 test cases covering:
+- Factory core functions (7 tests)
+- Validation (5 tests)
+- Display formatting (3 tests)
+- Backward compatibility (4 tests)
+- Error message consistency (2 tests)
+
+## Test Files Created
+- `test/artifacts/feature_config-factory/test-spec.md` - Test mapping document
+- `test/feature_config-factory.test.js` - Executable test file
+
+## Key Test Coverage
+
+### Factory API
+- Factory returns: read, write, reset, display, setValue, getDefault, CONFIG_FILE
+- getDefault returns provided defaults unchanged
+- read handles missing/corrupted files gracefully
+- read merges missing keys from defaults
+- write/reset operations
+
+### Validation System
+- Validators map prevents invalid values
+- Array keys parsed from JSON strings
+- Unknown keys rejected with helpful error
+
+### Backward Compatibility
+- retry.js exports unchanged
+- feedback.js exports unchanged
+- stack.js (with Stack prefix) exports unchanged
+- murm.js config functions unchanged
+
+## Implementation Notes for Codey
+
+1. **Create `src/config-factory.js`** with `createConfigModule(options)` factory
+2. **Options object shape**:
+   ```js
+   {
+     name: string,           // Config name for display
+     file: string,           // Path like '.claude/foo.json'
+     defaults: object,       // Default config values
+     validators?: object,    // Key -> validator function
+     formatters?: object,    // Key -> display formatter
+     arrayKeys?: string[]    // Keys that accept JSON array values
+   }
+   ```
+3. **Validator functions** return `true` for valid, or error string for invalid
+4. **Error format**: `Invalid value for {key}: {value}. {reason}`
+5. **Refactor existing modules** to use factory while preserving all exports
+
+## Running Tests
+```bash
+cd .claude/worktrees/feat-config-factory
+node --test test/feature_config-factory.test.js
+```

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

@@ -0,0 +1,215 @@
+# Feature Specification — Export Pipeline History
+
+## 1. Feature Intent
+
+**Why this feature exists.**
+
+Users need to extract pipeline history data for analysis, reporting, and integration with external tools. The existing `history` and `insights` commands provide on-demand viewing, but teams often require:
+
+- **Spreadsheet analysis** — CSV export for pivot tables, charts, and ad-hoc queries
+- **Custom dashboards** — JSON export for ingestion into monitoring tools or team portals
+- **Filtered exports** — Ability to slice data by date range, status, or specific features
+
+This feature supports the system purpose of **observability** (System Spec Section 8) by making pipeline execution data portable and actionable beyond the CLI.
+
+---
+
+## 2. Scope
+
+### In Scope
+
+- New `export` subcommand under `murmur8 history`
+- Export formats: CSV and JSON
+- Filtering options: `--since`, `--until`, `--status`, `--feature`
+- Output to stdout (default) or file via `--output`
+
+### Out of Scope
+
+- Export of queue state (`.claude/implement-queue.json`) — separate concern
+- Scheduled/automated exports — users can integrate via shell scripts
+- Direct integration with external services (Slack, email, dashboards)
+- Aggregated statistics export — `--stats` output remains display-only
+
+---
+
+## 3. Actors Involved
+
+### Human User
+
+- **Can:** Export history data in CSV or JSON format, apply filters, redirect to file
+- **Cannot:** Export queue state or insights aggregations through this command
+
+---
+
+## 4. Behaviour Overview
+
+**Happy Path:**
+
+1. User runs `murmur8 history export --format=csv`
+2. System reads `.claude/pipeline-history.json`
+3. System converts entries to CSV format
+4. System outputs to stdout
+
+**With Filters:**
+
+1. User runs `murmur8 history export --format=json --since=2024-01-01 --status=failed`
+2. System reads history, filters by date and status
+3. System outputs filtered JSON to stdout
+
+**To File:**
+
+1. User runs `murmur8 history export --format=csv --output=report.csv`
+2. System writes CSV to specified file
+3. System prints confirmation message
+
+**Edge Cases:**
+
+- Empty history: Output empty array/CSV header with no data rows
+- Corrupted history file: Warn and exit with non-zero status
+- No matches for filters: Output empty result (not an error)
+- Invalid date format: Error with usage hint
+
+---
+
+## 5. State & Lifecycle Interactions
+
+This feature is **state-reading only**. It does not modify pipeline state.
+
+- **Reads:** `.claude/pipeline-history.json`
+- **Does not modify:** Any state files or artifacts
+
+---
+
+## 6. Rules & Decision Logic
+
+### Format Selection Rule
+
+| `--format` value | Output |
+|------------------|--------|
+| `csv` (default) | Comma-separated values with header row |
+| `json` | Pretty-printed JSON array |
+
+### Date Filtering Rules
+
+- `--since=YYYY-MM-DD`: Include entries where `completedAt >= since`
+- `--until=YYYY-MM-DD`: Include entries where `completedAt <= until`
+- Both can be combined for a range
+- Dates are interpreted as start of day (00:00:00) in local timezone
+
+### Status Filtering Rule
+
+- `--status=success|failed|paused`: Include only entries with matching status
+- Multiple values not supported in v1 (e.g., no `--status=success,failed`)
+
+### Feature Filtering Rule
+
+- `--feature=<slug>`: Include only entries matching the feature slug
+- Exact match (not substring)
+
+### Output Destination Rule
+
+- No `--output`: Write to stdout
+- `--output=<path>`: Write to file, creating parent directories if needed
+
+---
+
+## 7. Dependencies
+
+### System Components
+
+- `src/history.js` — Existing `readHistoryFile()` function for reading history
+- `src/theme.js` — Optional colorization for confirmation messages
+
+### Data Format
+
+Relies on existing history entry structure:
+
+```javascript
+{
+  slug: string,
+  status: 'success' | 'failed' | 'paused',
+  startedAt: ISO8601,
+  completedAt: ISO8601,
+  totalDurationMs: number,
+  stages: { [stage]: { durationMs, feedback? } },
+  failedStage?: string,
+  pausedAfter?: string
+}
+```
+
+---
+
+## 8. Non-Functional Considerations
+
+### Performance
+
+- History files are typically small (<1MB). No streaming required for v1.
+- If performance becomes an issue with large histories, consider streaming JSON output.
+
+### Error Handling
+
+- Invalid date format: Exit with code 1, print usage hint
+- Missing history file: Treat as empty (not an error)
+- Corrupted history file: Exit with code 1, suggest `history clear`
+- File write error: Exit with code 1 with descriptive message
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+
+- History file structure is stable (no migration needed)
+- Users have write permissions for `--output` destination
+- Date parsing uses native JavaScript Date (ISO 8601 format expected)
+
+### Open Questions
+
+- **Q:** Should we support `--limit` to cap exported rows?
+  - **A:** Defer to v2. Users can pipe to `head` for now.
+- **Q:** Should CSV include nested stage data?
+  - **A:** v1 exports top-level fields only. Stage details available in JSON.
+
+---
+
+## 10. Impact on System Specification
+
+This feature **reinforces** existing system assumptions:
+
+- Aligns with observability cross-cutting concern (System Spec Section 8)
+- Builds on existing history module without modifying its behavior
+- Does not introduce new state, lifecycle, or invariant changes
+
+No system spec changes required.
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story Themes
+
+1. **Basic Export** — Export history to CSV or JSON format
+2. **Date Filtering** — Filter exports by date range
+3. **Status Filtering** — Filter exports by pipeline status
+4. **Feature Filtering** — Filter exports by feature slug
+5. **File Output** — Write exports to a file instead of stdout
+
+### Expected Story Boundaries
+
+- Each filter type should be a separate story for independent testing
+- File output can be combined with basic export
+- Error handling can be implicit in each story's acceptance criteria
+
+### Areas Needing Careful Story Framing
+
+- CSV field ordering and escaping rules (commas, quotes in slugs)
+- Empty result behavior (should still output valid CSV/JSON structure)
+- Date parsing edge cases (timezone handling, invalid formats)
+
+---
+
+## 12. Change Log (Feature-Level)
+
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-03-03 | Initial feature specification | Implement export-history from backlog | Alex |