murmur8 4.2.0 → 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_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 |