murmur8 4.5.1 → 4.7.0

package/.blueprint/features/feature_refine-feature-skill/story-test-propagation.md

@@ -0,0 +1,42 @@
+# Story: Test Propagation via Nigel
+
+**As a** developer whose stories have been updated by Cass
+**I want** Nigel to update only the affected test cases and produce a `test-changes.md` summary
+**So that** the test suite reflects the refined spec without replacing tests that are still valid
+
+## Acceptance Criteria
+
+### AC-1: Nigel reads story-changes.md to scope its work
+**Given** Cass has produced a `story-changes.md` (or Cass was skipped and Alex produced a spec diff)
+**When** Nigel starts
+**Then** Nigel reads `story-changes.md` (or the spec diff directly if Cass was skipped) before reading any test files
+
+### AC-2: Only affected test cases are modified
+**Given** an existing test file with multiple test cases
+**When** Nigel has identified which test cases correspond to changed stories or spec sections
+**Then** Nigel modifies only those test cases; test cases unrelated to the diff are left unchanged
+
+### AC-3: Nigel produces a `test-changes.md` file
+**Given** Nigel has completed updating tests
+**When** the Nigel stage finishes
+**Then** a `test-changes.md` file exists in the feature directory listing which test cases were added, modified, or removed and why
+
+### AC-4: New test cases are created for new acceptance criteria
+**Given** a new acceptance criterion exists in an updated or new story
+**When** Nigel processes the changes
+**Then** Nigel creates a new test case covering that criterion and records it in `test-changes.md`
+
+### AC-5: Nigel works from spec diff when no stories exist
+**Given** the original feature was technical and Cass was skipped
+**When** Nigel runs
+**Then** Nigel uses the before/after spec diff produced by Alex as the sole input for determining which tests to update
+
+### AC-6: Passing tests are not regressed
+**Given** an existing test that covers behaviour not changed by the diff
+**When** Nigel completes
+**Then** that test case remains present and semantically equivalent to its pre-refinement version
+
+## Out of Scope
+- Nigel running the tests (execution happens during the Codey stage)
+- Nigel modifying story files
+- Nigel engaging in conversation with the user about test scope

package/README.md

@@ -1,19 +1,54 @@
 # murmur8
 
-A multi-agent workflow framework for automated feature development. Four specialised AI agents collaborate in sequence to take features from specification to implementation, with built-in feedback loops and self-improvement capabilities. 
+Most AI coding tools are a black box. You describe what you want, something happens, and code appears. If it's wrong, you describe it again and hope for better. There's no process, no trail, no shared understanding of why decisions were made.
 
-Like a murmuration of starlings, individual agents move together as one, each responding to its neighbours to create something greater than the sum of its parts.
+murmur8 is different. It runs a structured, documented pipeline — the kind a good engineering team would run naturally. Each agent produces real, readable artefacts: a feature spec, user stories, a test plan, an implementation. You can read every one of them, understand the reasoning, and step in at any point. It's not magic. It's a repeatable process that happens to move very fast.
 
-# TLDR - Using murmur8
+Like a murmuration of starlings, the agents move together — each one responding to what came before, building something greater than any of them could produce alone.
 
-## Using murmur8 inside Claude Code or Copilot CLI
-Initialize with `npx murmur8 init`, then run `/implement-feature your-feature` in Claude Code or Copilot CLI. Four AI agents collaborate to turn your idea into tested, working code — from spec to implementation. Add up to 3 feature slugs and the murmuration magic will build them in paralell in an isolated git worktree. 
+## The Workflow
 
-## Using murmur8 outside of Claude Code or Copilot CLI
-Initialize with `npx murmur8 init`, then run `npx murmur8 murm feature-a feature-b` from your terminal. Each feature gets an isolated git worktree and runs its own pipeline. Successful features auto-merge to main. Use `--dry-run` to preview the plan first.
+### Start with a conversation
+
+Every feature starts with intent. If you're setting up a new project, murmur8 will walk you through creating a system specification interactively — Alex asks questions, you answer, and together you produce a document that grounds everything that follows. If a feature spec doesn't exist yet, the same thing happens at the feature level.
+
+You can also trigger this explicitly with `--interactive`. This is useful when an idea is still fuzzy. Rather than writing a spec yourself, you have a conversation with Alex until the shape of the feature becomes clear. The spec that comes out the other side is yours to review and approve before anything else runs.
+
+### The pipeline runs
+
+Once there's a spec, the pipeline takes over. Alex hands off to Cass, who writes user stories with explicit acceptance criteria. Cass hands off to Nigel, who turns those stories into a test plan and executable tests. Nigel hands off to Codey, who implements until the tests pass.
+
+At every handoff, the agent writes a summary of what it did, what it decided, and what the next agent needs to know. These aren't logs — they're readable documents. If something goes wrong, or you want to understand why a decision was made, you can read the trail. The spec, the stories, the test plan, the implementation plan: they all live in your repository alongside the code.
+
+### Refine it
+
+The first run won't always land exactly right. Requirements shift, something was misunderstood, or the implementation reveals a gap in the spec. That's normal.
+
+`/refine-feature` reopens the conversation. Alex reads what was built, you tell it what needs to change, and it proposes an updated spec diff for your approval. From there Cass updates only the affected stories, Nigel updates only the affected tests, and Codey reimplements. The pipeline pauses before Codey runs — you always see the full picture of what's changing before any code is touched.
+
+Every refinement is linked to the run it came from, so the history of a feature — original intent, what changed, and why — is always traceable.
+
+## Quick Start
+
+**Inside Claude Code or Copilot CLI:**
+```bash
+npx murmur8 init
+/implement-feature your-feature
+```
+
+**From the terminal (parallel execution):**
+```bash
+npx murmur8 init
+npx murmur8 murm feature-a feature-b feature-c
+```
+
+Add up to three slugs and each feature runs in an isolated git worktree simultaneously. Successful features auto-merge to main. Use `--dry-run` to preview the plan before committing.
 
 ## Upgrading to v4.0
 
+<details>
+<summary>Breaking changes and migration notes</summary>
+
 v4.0 completes the murmuration theming by renaming all parallel internals. Existing users should be aware of the following breaking changes.
 
 ### Breaking changes
@@ -32,6 +67,8 @@ Legacy on-disk files (`.claude/parallel-config.json`, `.claude/parallel-queue.js
 
 The CLI commands `parallel`, `murmuration`, and `parallel-config` continue to work as aliases for `murm` and `murm-config` respectively.
 
+</details>
+
 ## Agents
 
 | Agent | Role |
@@ -148,6 +185,7 @@ This updates `.blueprint/agents/`, `.blueprint/templates/`, `.blueprint/ways_of_
 | `npx murmur8 feedback-config set <key> <value>` | Modify feedback settings |
 | `npx murmur8 murm-config` | View murmuration pipeline configuration |
 | `npx murmur8 murm-config set <key> <value>` | Modify murmuration settings |
+| `npx murmur8 telemetry-config` | View telemetry configuration and failed queue depth |
 
 ## Skill usage
 
@@ -298,6 +336,7 @@ murmur8 includes these built-in modules for observability and self-improvement:
 | **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 |
+| **telemetry** | Opt-in audit layer — POSTs structured run data to a configured endpoint for corpus building and enterprise usage monitoring |
 
 ### How They Work Together
 
@@ -515,6 +554,58 @@ npx murmur8 cost-config reset
 
 Cost data is stored in `pipeline-history.json` alongside timing and feedback data.
 
+## Pipeline Telemetry
+
+An opt-in audit and data collection layer. When a telemetry endpoint is configured, each completed pipeline run POSTs a structured event payload to that endpoint. If no endpoint is configured, the feature is completely silent — no output, no side effects.
+
+### Activation
+
+The `murmur8 init` command creates a `.env` file at your project root with a commented-out telemetry template:
+
+```bash
+# Remove # to enable
+MURMUR8_TELEMETRY_URL=https://your-ingest-endpoint.com/events
+MURMUR8_TELEMETRY_KEY=your-api-key   # optional — sent as Authorization: Bearer
+```
+
+Real environment variables take precedence over `.env`, making it straightforward to configure in CI/CD without storing credentials in files. `.env` is automatically added to `.gitignore` during init.
+
+### What gets sent
+
+| Field | Description |
+|-------|-------------|
+| `runId` | UUID v4 unique to this pipeline execution |
+| `featureId` | UUID stable across retries — written into FEATURE_SPEC.md frontmatter once by Alex |
+| `identity` | Git user name/email, repo remote URL, org ID, murmur8 version |
+| `run` | Slug, status, start/end timestamps, per-stage timings and statuses, feedback ratings |
+| `artifacts` | Feature spec and story files, gzip + base64 encoded |
+
+`featureId` enables cross-run correlation: all retries of the same feature share one `featureId` while each execution gets a unique `runId`. This lets you query "all runs ever attempted for this feature" and trace evolution over time.
+
+### Reliability
+
+Sends are non-blocking and never interrupt the pipeline. On failure (network error, timeout, non-2xx), the payload is silently queued to `.claude/telemetry-failed.json` and retried at the start of the next run.
+
+### Viewing configuration
+
+```bash
+npx murmur8 telemetry-config
+
+# Example output:
+# status:       active
+# url:          https://your-endpoint.com/events
+# api key:      ****1234
+# failed queue: 0 entries
+```
+
+### Enterprise use
+
+murmur8 telemetry is designed for self-hosted enterprise endpoints — there is no central collection service. Each organisation configures its own ingest URL. This enables:
+
+- **Usage monitoring** — who ran what pipeline, on which repo, when
+- **Audit trail** — `runId` + `commitHash` + `gitUser` provides an immutable trace of AI-assisted code changes
+- **Corpus building** — aggregate feature specs and stories across teams to analyse and improve pipeline quality
+
 ## 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/bin/cli.js

@@ -10,7 +10,8 @@ const command = args[0];
 const aliases = {
   'parallel': 'murm',
   'murmuration': 'murm',
-  'parallel-config': 'murm-config'
+  'parallel-config': 'murm-config',
+  'refine-feature': 'refine'
 };
 
 const resolvedCommand = aliases[command] || command;

package/package.json

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

package/src/commands/refine.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const { loadRefinementContext, isPauseBypassable } = require('../refine');
+
+const description = 'Refine an existing feature spec and propagate changes through stories, tests, and implementation';
+
+async function run(argv) {
+  const { parseRefinementArgs } = require('../refine');
+  const { slug } = parseRefinementArgs(argv);
+
+  if (!slug) {
+    console.error('Usage: murmur8 refine-feature <slug>');
+    console.error('Example: murmur8 refine-feature user-auth');
+    process.exit(1);
+  }
+
+  console.log(`Loading refinement context for "${slug}"...`);
+
+  let ctx;
+  try {
+    ctx = await loadRefinementContext(slug, process.cwd());
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  const storyCount = ctx.stories.length;
+  const lastStatus = ctx.lastRunStatus ? ` (last run: ${ctx.lastRunStatus})` : '';
+  console.log(`Feature: ${ctx.slug}${lastStatus}`);
+  console.log(`Stories: ${storyCount}`);
+  console.log(`Feature ID: ${ctx.featureId}`);
+  console.log('');
+  console.log('To refine this feature, use the /refine-feature skill in Claude Code:');
+  console.log(`  /refine-feature "${slug}"`);
+}
+
+module.exports = { run, description };

package/src/commands/telemetry-config.js

@@ -0,0 +1,16 @@
+/**
+ * telemetry-config command - View telemetry configuration and queue status
+ */
+const { loadConfig, formatTelemetryConfig } = require('../telemetry');
+
+const description = 'View telemetry configuration and failed-send queue status';
+
+const QUEUE_PATH = '.claude/telemetry-failed.json';
+
+async function run(_args) {
+  const config = loadConfig('.env');
+  const output = formatTelemetryConfig(config, QUEUE_PATH);
+  console.log(output);
+}
+
+module.exports = { run, description };

package/src/index.js

@@ -1,4 +1,16 @@
 const { init } = require('./init');
+const {
+  parseRefinementArgs,
+  loadRefinementContext,
+  applySpecDiff,
+  buildRefinementPayload,
+  linkParentRun,
+  isTechnicalFeature,
+  filterAffectedStories,
+  buildStoryChanges,
+  buildChangeSummary,
+  isPauseBypassable,
+} = require('./refine');
 const { update } = require('./update');
 const { validate, formatOutput, checkNodeVersion } = require('./validate');
 const { recordHistory, displayHistory, showStats, clearHistory, storeStageFeedback, updateStage } = require('./history');
@@ -94,6 +106,9 @@ const {
   markWorktreeAborted,
   getPromptText
 } = require('./diff-preview');
+const { loadConfig, generateRunId, ensureFeatureId, buildPayload, compressArtifact,
+        enqueueFailure, retryQueue, ensureDotenv, ensureGitignore, formatTelemetryConfig
+      } = require('./telemetry');
 const tools = require('./tools');
 const theme = require('./theme');
 
@@ -159,6 +174,17 @@ module.exports = {
   setStackConfigValue,
   detectStackConfig,
   displayStackConfig,
+  // Telemetry module exports
+  loadConfig,
+  generateRunId,
+  ensureFeatureId,
+  buildPayload,
+  compressArtifact,
+  enqueueFailure,
+  retryQueue,
+  ensureDotenv,
+  ensureGitignore,
+  formatTelemetryConfig,
   // Tools module (model native features)
   tools,
   // Theme module (murmuration visual theming)
@@ -195,5 +221,16 @@ module.exports = {
   SESSION_STATES,
   SECTION_ORDER,
   MIN_REQUIRED_SECTIONS,
-  SYSTEM_SPEC_QUESTIONS
+  SYSTEM_SPEC_QUESTIONS,
+  // Refine module exports
+  parseRefinementArgs,
+  loadRefinementContext,
+  applySpecDiff,
+  buildRefinementPayload,
+  linkParentRun,
+  isTechnicalFeature,
+  filterAffectedStories,
+  buildStoryChanges,
+  buildChangeSummary,
+  isPauseBypassable,
 };

package/src/init.js

@@ -3,6 +3,7 @@ const path = require('path');
 
 const { detectStackConfig, writeStackConfig, CONFIG_FILE: STACK_CONFIG_FILE } = require('./stack');
 const { prompt } = require('./utils');
+const { ensureDotenv, ensureGitignore } = require('./telemetry');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TARGET_DIR = process.cwd();
@@ -176,6 +177,10 @@ async function init() {
     console.log('Stack config already exists, skipping detection');
   }
 
+  // Ensure .env template and .gitignore entry for telemetry
+  ensureDotenv(TARGET_DIR);
+  ensureGitignore(TARGET_DIR);
+
   console.log(`
 murmur8 initialized successfully!
 

package/src/refine.js

@@ -0,0 +1,172 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+function parseRefinementArgs(argv) {
+  const slug = argv[3] || null;
+  return { slug };
+}
+
+function _extractFeatureId(content) {
+  const match = content.match(/^---[\s\S]*?featureId:\s*([^\s\n]+)[\s\S]*?---/m);
+  return match ? match[1] : null;
+}
+
+function _writeFeatureId(specPath, content, featureId) {
+  let updated;
+  if (content.startsWith('---')) {
+    const endIdx = content.indexOf('---', 3);
+    if (endIdx !== -1) {
+      const frontmatter = content.slice(3, endIdx);
+      if (frontmatter.includes('featureId:')) {
+        updated = content.replace(/featureId:\s*[^\s\n]+/, `featureId: ${featureId}`);
+      } else {
+        updated = `---${frontmatter}featureId: ${featureId}\n${content.slice(endIdx)}`;
+      }
+    } else {
+      updated = `---\nfeatureId: ${featureId}\n---\n${content}`;
+    }
+  } else {
+    updated = `---\nfeatureId: ${featureId}\n---\n${content}`;
+  }
+  fs.writeFileSync(specPath, updated, 'utf8');
+  return updated;
+}
+
+async function loadRefinementContext(slug, baseDir) {
+  const base = baseDir || process.cwd();
+  const featDir = path.join(base, '.blueprint', 'features', `feature_${slug}`);
+  const specPath = path.join(featDir, 'FEATURE_SPEC.md');
+
+  if (!fs.existsSync(specPath)) {
+    throw new Error(`FEATURE_SPEC.md not found for slug "${slug}" — run /implement-feature first`);
+  }
+
+  let specContent = fs.readFileSync(specPath, 'utf8');
+  let featureId = _extractFeatureId(specContent);
+  if (!featureId) {
+    featureId = crypto.randomUUID();
+    specContent = _writeFeatureId(specPath, specContent, featureId);
+  }
+
+  const storyFiles = fs.existsSync(featDir)
+    ? fs.readdirSync(featDir).filter(f => f.startsWith('story-') && f.endsWith('.md'))
+    : [];
+
+  const stories = storyFiles.map(f => ({
+    file: f,
+    content: fs.readFileSync(path.join(featDir, f), 'utf8'),
+  }));
+
+  const historyPath = path.join(base, '.claude', 'pipeline-history.json');
+  let history = [];
+  if (fs.existsSync(historyPath)) {
+    try {
+      history = JSON.parse(fs.readFileSync(historyPath, 'utf8'));
+    } catch (_) {
+      history = [];
+    }
+  }
+
+  const lastRun = history.filter(e => e.slug === slug).sort((a, b) =>
+    (b.completedAt || '').localeCompare(a.completedAt || '')
+  )[0];
+
+  return {
+    slug,
+    featureId,
+    spec: specContent,
+    stories,
+    history: history.filter(e => e.slug === slug),
+    lastRunStatus: lastRun ? lastRun.status : null,
+    featureName: slug,
+  };
+}
+
+async function applySpecDiff(specPath, newContent, featureId) {
+  if (newContent === null || newContent === undefined) {
+    throw new Error('abort: null diff provided — no changes applied');
+  }
+  _writeFeatureId(specPath, newContent, featureId);
+}
+
+function buildRefinementPayload(opts) {
+  const {
+    slug,
+    featureId,
+    storyChangesPath = null,
+    testChangesPath = null,
+    specDiff = null,
+    noCommit = false,
+  } = opts || {};
+
+  return {
+    slug,
+    featureId,
+    storyChangesPath: storyChangesPath || null,
+    testChangesPath: testChangesPath || null,
+    specDiff: specDiff || null,
+    commitSkipped: Boolean(noCommit),
+  };
+}
+
+function linkParentRun(slug, history) {
+  const slugRuns = (history || [])
+    .filter(e => e.slug === slug)
+    .sort((a, b) => (b.completedAt || '').localeCompare(a.completedAt || ''));
+
+  const latest = slugRuns[0] || null;
+
+  return {
+    parentRunId: latest ? latest.runId : null,
+    type: 'refinement',
+    featureId: latest ? latest.featureId : null,
+  };
+}
+
+function isTechnicalFeature(stories) {
+  return stories.length === 0;
+}
+
+function filterAffectedStories(stories, changedSlugs) {
+  return stories.filter(f => {
+    const name = path.basename(f, '.md').replace(/^story-/, '');
+    return changedSlugs.some(s => name === s || f.includes(s));
+  });
+}
+
+function buildStoryChanges(entries) {
+  return (entries || []).map(e => ({
+    file: e.file,
+    reason: e.reason,
+    isNew: Boolean(e.isNew),
+  }));
+}
+
+function buildChangeSummary(opts) {
+  const { specPath, affectedStories, testChangesPath } = opts || {};
+  return {
+    specPath: specPath || null,
+    affectedStories: Array.isArray(affectedStories) ? affectedStories : [],
+    testChangesPath: testChangesPath || null,
+  };
+}
+
+function isPauseBypassable(_flags) {
+  return false;
+}
+
+module.exports = {
+  parseRefinementArgs,
+  loadRefinementContext,
+  applySpecDiff,
+  buildRefinementPayload,
+  linkParentRun,
+  isTechnicalFeature,
+  filterAffectedStories,
+  buildStoryChanges,
+  buildChangeSummary,
+  isPauseBypassable,
+};