murmur8 4.2.0 → 4.3.1

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_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 |