murmur8 4.6.0 → 4.7.1

package/.blueprint/features/feature_refine-feature-skill/FEATURE_SPEC.md

@@ -0,0 +1,180 @@
+# Feature Specification — Refine Feature Skill
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- After running `/implement-feature`, the result may not match user intent — tests pass but behaviour is wrong, scope was misunderstood, or new information changes requirements
+- Users need a structured path to refine an existing feature without starting from scratch
+- This supports the system purpose of iterative, AI-assisted feature development
+
+---
+
+## 2. Scope
+### In Scope
+- New `/refine-feature [slug]` skill that initiates a refinement pipeline
+- Alex reads existing spec, stories, and test output to build context, then converses with the user to identify changes
+- Alex presents a proposed spec diff; user approves before changes are applied
+- Cass updates affected story files and produces `story-changes.md`
+- Nigel updates affected tests and produces `test-changes.md`
+- Mandatory pause before Codey implements — user must confirm
+- Codey implements changes using the same test-first approach
+- Telemetry: `parentRunId` field linking this run to the run being refined; artifact diffs instead of full files
+- SKILL.md written to project root; copied to `.claude/commands/refine-feature.md` on `murmur8 init`
+
+### Out of Scope
+- Branching or forking a feature into two separate features
+- Rolling back a feature (separate concern)
+- Bulk-refining multiple features in one invocation
+- Changing the featureId (it must be preserved across refinements)
+
+---
+
+## 3. Actors Involved
+
+**User**
+- Provides the slug of the feature to refine
+- Engages in freeform conversation with Alex about what needs to change (feedback, error logs, test output)
+- Reviews and approves/rejects the proposed spec diff
+- Confirms before Codey implements
+
+**Alex**
+- Reads existing FEATURE_SPEC.md, story-*.md, test output, and pipeline history
+- Converses with user to understand what changed or was wrong
+- Identifies minimal set of spec changes needed
+- Presents diff; updates FEATURE_SPEC.md only after approval
+
+**Cass**
+- Reads `story-changes.md` produced by Alex
+- Updates only affected story files (not all stories)
+- Produces `story-changes.md` summarising what changed and why
+
+**Nigel**
+- Reads `story-changes.md` to understand scope of change
+- Updates only affected test cases
+- Produces `test-changes.md` summarising what changed
+
+**Codey**
+- Receives explicit user confirmation before starting
+- Implements changes to pass updated tests
+- Uses the same test-first incremental approach as the main pipeline
+
+---
+
+## 4. Behaviour Overview
+
+### Happy Path
+1. User runs `/refine-feature [slug]`
+2. Alex reads existing artifacts and presents a brief summary of current state
+3. Alex asks: "What needs to change?"
+4. User provides feedback (freeform: description, logs, error output, screenshots)
+5. Alex identifies changes and presents a proposed diff to FEATURE_SPEC.md
+6. User approves → Alex writes updated FEATURE_SPEC.md (featureId preserved)
+7. Cass updates affected stories and writes `story-changes.md`
+8. Nigel updates affected tests and writes `test-changes.md`
+9. Pipeline pauses: user sees summary of changes across spec/stories/tests
+10. User confirms → Codey implements, runs tests, iterates until passing
+11. Pipeline commits (unless `--no-commit`) and records refinement in history
+
+### Key Alternatives
+- User rejects Alex's proposed diff → Alex revises and re-presents
+- User aborts at any stage → clean exit, no partial writes
+- No stories exist (technical feature) → Cass stage skipped; Nigel works from spec diff directly
+- Tests already pass after spec change → Codey stage skipped with note
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- State-transitioning: moves an existing feature from a completed/deployed state back into active refinement
+- Reads but does not replace existing artifacts until user approves diff
+- After refinement, artifacts reflect the refined state; originals not preserved (git history provides rollback)
+- Refinement history is a chain: each run's `parentRunId` points to the previous run's `runId`
+
+---
+
+## 6. Rules & Decision Logic
+
+**R1: featureId preservation**
+- The existing `featureId` in FEATURE_SPEC.md YAML frontmatter must never be changed
+- Input: existing spec; Output: updated spec with same featureId
+
+**R2: parentRunId linkage**
+- Every refinement run must include `parentRunId` = the `runId` of the run being refined
+- If no prior run exists in history for this slug, `parentRunId` = null (graceful)
+- Input: pipeline history for slug; Output: parentRunId in telemetry payload
+
+**R3: Mandatory pause before Codey**
+- Codey must never run without explicit user confirmation
+- Applies regardless of flags (no `--yes` bypass for this gate)
+
+**R4: Cass skipped for technical features**
+- If the original feature was classified as technical (no stories exist), Cass is skipped
+- Nigel works from the spec diff directly
+
+**R5: Artifact diff in telemetry**
+- Refinement telemetry sends diffs (before/after) rather than full artifact content
+- Keeps payload size proportional to the change, not the total feature size
+
+---
+
+## 7. Dependencies
+
+- `src/telemetry.js` — existing telemetry module; refinements add `parentRunId` field
+- `src/history.js` — existing history module; refinements are recorded with `type: "refinement"`
+- `src/classifier.js` — determines whether Cass stage runs
+- `src/diff-preview.js` — used for pre-commit diff review
+- `src/feedback.js` — quality gates between stages (same thresholds)
+- `.blueprint/agents/AGENT_SPECIFICATION_ALEX.md` — Alex agent spec
+- `.blueprint/agents/AGENT_BA_CASS.md` — Cass agent spec
+- `.blueprint/agents/AGENT_TESTER_NIGEL.md` — Nigel agent spec
+- `.blueprint/agents/AGENT_DEVELOPER_CODEY.md` — Codey agent spec
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Token efficiency**: Alex reads existing artifacts selectively — handoff summaries first, full spec only if needed
+- **Audit**: all refinements recorded in pipeline history; parentRunId chain enables full lineage
+- **Safety**: mandatory pause before Codey prevents accidental overwrites on approval
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- The feature being refined already has a FEATURE_SPEC.md
+- featureId exists in YAML frontmatter (if not, it should be added before refinement proceeds)
+- Git is available for diff display and commit
+
+**Open Questions:**
+- Should a `--no-pause` flag be allowed to skip the Codey confirmation? (Current decision: no, always pause)
+- Should `story-changes.md` and `test-changes.md` be committed alongside the updated files, or deleted after? (Current decision: commit them as refinement audit trail)
+
+---
+
+## 10. Impact on System Specification
+
+This feature reinforces the system's core model of iterative, agent-assisted development. It stretches the pipeline slightly by adding a conversation phase (Alex ↔ user) before spec writing, but does not contradict any existing system assumptions.
+
+No system spec changes required.
+
+---
+
+## 11. Handover to BA (Cass)
+
+Story themes:
+- Initiating a refinement: user provides slug, Alex reads context
+- Conversation and approval: user provides feedback, Alex proposes diff, user approves
+- Story propagation: Cass updates affected stories, produces story-changes.md
+- Test propagation: Nigel updates affected tests, produces test-changes.md
+- Implementation confirmation: mandatory pause, user confirms, Codey implements
+- Telemetry lineage: parentRunId chain, artifact diffs
+
+Story boundaries: each stage transition (user→Alex, Alex→Cass, Cass→Nigel, Nigel→pause, pause→Codey) is a natural story boundary.
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-05-19 | Initial spec | New feature design | Steve Newman |

package/.blueprint/features/feature_refine-feature-skill/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,47 @@
+# Implementation Plan — refine-feature-skill
+
+## Summary
+Create `src/refine.js` exporting 10 pure helper functions tested by Nigel's 25-test suite. Add `src/commands/refine.js` CLI handler and wire the command into `bin/cli.js` and `src/index.js`. Write `REFINE_SKILL.md` at project root.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/refine.js` | Create | All 10 pure helper functions |
+| `src/commands/refine.js` | Create | CLI handler for `murm refine` / `refine-feature` command |
+| `src/index.js` | Modify | Export refine module functions |
+| `bin/cli.js` | Modify | Register `refine-feature` command |
+| `REFINE_SKILL.md` | Create | Skill definition for /refine-feature |
+
+## Implementation Steps
+
+1. **Create `src/refine.js`** — implement all 10 functions:
+   - `parseRefinementArgs(argv)` → `{ slug }` from argv[3] or null
+   - `loadRefinementContext(slug, baseDir)` → reads FEATURE_SPEC.md (throws if missing), story-*.md files, .claude/pipeline-history.json; extracts/writes featureId; returns `{ spec, stories, history, featureId, slug }`
+   - `applySpecDiff(specPath, newContent, featureId)` → throws on null; writes spec with YAML frontmatter containing featureId
+   - `buildRefinementPayload(opts)` → returns plain object with storyChangesPath, testChangesPath, specDiff, commitSkipped
+   - `linkParentRun(slug, history)` → finds most recent entry for slug by completedAt; returns `{ parentRunId, type: 'refinement', featureId }`
+   - `isTechnicalFeature(stories)` → returns `stories.length === 0`
+   - `filterAffectedStories(stories, changedSlugs)` → filters by slug contained in filename
+   - `buildStoryChanges(entries)` → returns entries array (passthrough with validation)
+   - `buildChangeSummary(opts)` → returns `{ specPath, affectedStories, testChangesPath }`
+   - `isPauseBypassable(_flags)` → always returns `false`
+
+2. **Run tests** after writing src/refine.js — expect 25/25 to pass
+
+3. **Create `src/commands/refine.js`** — CLI handler that calls loadRefinementContext and orchestrates the pipeline flow (stub-level for now; skill handles orchestration)
+
+4. **Modify `src/index.js`** — add require + exports for refine module
+
+5. **Modify `bin/cli.js`** — register `refine-feature` command routing to `src/commands/refine.js`
+
+6. **Create `REFINE_SKILL.md`** — skill definition with full `/refine-feature` pipeline documented
+
+7. **Run full test suite** — `node --test` to verify no regressions
+
+## Key Implementation Notes
+
+- `loadRefinementContext`: use `fs.readdirSync` to find `story-*.md` files; parse YAML frontmatter with simple regex (no deps); if no featureId in frontmatter, generate UUID v4 and write it back (same pattern as telemetry's `ensureFeatureId`)
+- `applySpecDiff`: ensure YAML frontmatter block always starts the file; preserve featureId even if newContent doesn't include it
+- `linkParentRun`: sort history by `completedAt` descending, take first matching slug; if no match, parentRunId = null
+- UUID generation: use `crypto.randomUUID()` (Node 18+, no deps needed)

package/.blueprint/features/feature_refine-feature-skill/handoff-alex.md

@@ -0,0 +1,19 @@
+## Handoff Summary
+**For:** Cass
+**Feature:** refine-feature-skill
+
+### Key Decisions
+- Skill is `/refine-feature [slug]` — a separate skill from `/implement-feature`, not a flag
+- Alex stage is conversation-based (reads existing artifacts, chats with user, proposes diff) rather than fresh spec creation
+- Hard pause before Codey is mandatory — no `--yes` bypass
+- Telemetry uses `parentRunId` to form a linked chain of refinements; `featureId` is preserved
+- Cass skipped if original feature had no stories (technical classification)
+
+### Files Created
+- .blueprint/features/feature_refine-feature-skill/FEATURE_SPEC.md
+
+### Open Questions
+- None
+
+### Critical Context
+The six story themes map cleanly to pipeline stages: (1) initiation, (2) conversation + approval, (3) story propagation via Cass, (4) test propagation via Nigel, (5) mandatory pause + Codey confirmation, (6) telemetry lineage. Each story should have testable ACs focused on the observable behaviour at that stage boundary.

package/.blueprint/features/feature_refine-feature-skill/handoff-cass.md

@@ -0,0 +1,26 @@
+## Handoff Summary
+**For:** Nigel
+**Feature:** refine-feature-skill
+
+### Stories Written (6)
+- story-initiation.md — skill invocation, artifact loading, featureId capture/creation
+- story-conversation-approval.md — freeform feedback, diff proposal loop, approval gate, clean abort
+- story-story-propagation.md — Cass updates affected stories only, produces story-changes.md, skipped for technical features
+- story-test-propagation.md — Nigel updates affected tests only, produces test-changes.md, uses spec diff when Cass skipped
+- story-codey-confirmation.md — mandatory pre-Codey pause, no flag bypass, test-first implementation, conditional commit
+- story-telemetry-lineage.md — parentRunId chain, type:"refinement", artifact diffs in telemetry, change files committed as audit trail
+
+### Key Constraints for Nigel
+- Every AC is independently testable; prefer unit/integration tests over end-to-end
+- featureId preservation (AC-6 in initiation, AC-6 in conversation-approval, AC-4 in telemetry) must be verified as a cross-cutting invariant
+- The no-flag-bypass rule (AC-2 in codey-confirmation) is safety-critical — test it explicitly with `--yes` and similar flags
+- Cass-skip path (technical features) is tested in both story-propagation and test-propagation stories
+- parentRunId = null graceful path (AC-2 in telemetry) must be a distinct test case
+
+### Files Created
+- story-initiation.md
+- story-conversation-approval.md
+- story-story-propagation.md
+- story-test-propagation.md
+- story-codey-confirmation.md
+- story-telemetry-lineage.md

package/.blueprint/features/feature_refine-feature-skill/handoff-nigel.md

@@ -0,0 +1,30 @@
+## Handoff Summary
+**For:** Codey
+**Feature:** refine-feature-skill
+
+### Tests Written
+- File: `test/feature_refine-feature-skill.test.js`
+- Spec: `test/artifacts/feature_refine-feature-skill/test-spec.md`
+- Total tests: 25 across 6 describe blocks (one per story)
+
+### Coverage
+| Story | ACs covered | Test IDs |
+|---|---|---|
+| story-initiation.md | AC-1,2,3,4,5,6 | RF-IN-1…6 |
+| story-conversation-approval.md | AC-3,5,6 | RF-CA-3,5,6 |
+| story-story-propagation.md | AC-1,3,4,5,6 | RF-SP-1,3,4,5,6 |
+| story-test-propagation.md | AC-1,3,5 | RF-TP-1,3,5 |
+| story-codey-confirmation.md | AC-2,4,6 | RF-CC-2,4,6 |
+| story-telemetry-lineage.md | AC-1,2,3,4,7 | RF-TL-1,2,3,4,7 |
+
+### Key Assumptions for Codey
+- `src/refine.js` exports all 10 pure functions listed in test-spec.md
+- `loadRefinementContext(slug, baseDir)` accepts a base directory for testability
+- `applySpecDiff(specPath, newContent, featureId)` — null newContent = abort (throws)
+- `linkParentRun(slug, historyArray)` is pure; no file I/O
+- `isPauseBypassable` always returns `false`; no flags override it
+
+### Files to Create
+- `src/refine.js` — all pure helper functions
+- `src/commands/refine.js` — CLI handler wiring
+- `REFINE_SKILL.md` and `.claude/commands/refine-feature.md`

package/.blueprint/features/feature_refine-feature-skill/story-codey-confirmation.md

@@ -0,0 +1,41 @@
+# Story: Mandatory Pause and Codey Confirmation
+
+**As a** developer reviewing the proposed changes to spec, stories, and tests
+**I want** to see a consolidated summary of all changes before Codey begins implementation, and to give explicit confirmation before any code is touched
+**So that** I retain full control and cannot accidentally trigger implementation via a flag or shortcut
+
+## Acceptance Criteria
+
+### AC-1: Pipeline pauses before Codey with a change summary
+**Given** Nigel has produced `test-changes.md`
+**When** the pipeline reaches the pre-Codey gate
+**Then** the pipeline displays a summary showing: files changed in spec, stories affected, and tests added/modified, then waits for explicit user input before proceeding
+
+### AC-2: No flag or option bypasses the pre-Codey pause
+**Given** the pre-Codey gate is active
+**When** the user invokes `/refine-feature` with any combination of flags (including `--yes`, `--no-pause`, or any other flag)
+**Then** the pipeline still pauses and requires explicit confirmation; no flag silently bypasses this gate
+
+### AC-3: User confirmation triggers Codey implementation
+**Given** the pre-Codey change summary is displayed
+**When** the user confirms (e.g., types "yes" or "proceed")
+**Then** Codey begins implementation using the updated tests as its acceptance target
+
+### AC-4: User abort at pre-Codey gate exits cleanly
+**Given** the pre-Codey change summary is displayed
+**When** the user aborts (e.g., types "cancel" or "no")
+**Then** the pipeline exits cleanly; all spec, story, and test file writes that have already occurred are preserved; no code changes are made
+
+### AC-5: Codey uses test-first incremental approach
+**Given** the user has confirmed at the pre-Codey gate
+**When** Codey implements changes
+**Then** Codey runs the updated tests first, implements code changes incrementally to make them pass, and iterates until all updated tests pass
+
+### AC-6: Pipeline commits after successful implementation unless --no-commit
+**Given** Codey has completed implementation and all tests pass
+**When** the pipeline finishes
+**Then** changes are committed to git unless the `--no-commit` flag was supplied, in which case the pipeline exits with a message indicating commit was skipped
+
+## Out of Scope
+- Codey making spec or story changes (those are locked before this gate)
+- Any automated or timed confirmation; confirmation must be an explicit user action

package/.blueprint/features/feature_refine-feature-skill/story-conversation-approval.md

@@ -0,0 +1,41 @@
+# Story: Conversation and Spec Diff Approval
+
+**As a** developer providing feedback on a completed feature
+**I want** to describe what is wrong or what has changed to Alex in freeform language, then review a proposed diff before anything is written
+**So that** spec changes are driven by my intent and I cannot accidentally overwrite existing work
+
+## Acceptance Criteria
+
+### AC-1: Alex accepts freeform feedback input
+**Given** Alex has presented the current-state summary
+**When** the user provides feedback in any form (plain text, error logs, test output, screenshots)
+**Then** Alex accepts the input without requiring a specific format and proceeds to analyse it
+
+### AC-2: Alex presents a proposed diff to FEATURE_SPEC.md
+**Given** Alex has analysed the user's feedback
+**When** Alex has identified the minimal set of spec changes required
+**Then** Alex presents the proposed changes as a clearly labelled before/after diff and asks the user to approve or reject
+
+### AC-3: User approval triggers spec write
+**Given** Alex has presented the proposed diff
+**When** the user explicitly approves the diff
+**Then** Alex writes the updated `FEATURE_SPEC.md` with the changes applied, preserving the original featureId
+
+### AC-4: User rejection triggers revision loop
+**Given** Alex has presented the proposed diff
+**When** the user rejects the diff or requests changes
+**Then** Alex revises the proposed diff based on the user's clarification and presents an updated version; no files are written until approval is given
+
+### AC-5: User abort exits cleanly with no writes
+**Given** the conversation is in progress at any point before approval
+**When** the user aborts (e.g., types "cancel" or "abort")
+**Then** the pipeline exits cleanly, no files are modified, and the user receives confirmation that no changes were made
+
+### AC-6: featureId is unchanged after spec write
+**Given** the user has approved the proposed diff
+**When** Alex writes the updated `FEATURE_SPEC.md`
+**Then** the featureId in the YAML frontmatter is identical to the value read at initiation
+
+## Out of Scope
+- Automated approval via a `--yes` flag for this gate
+- Approving changes to story or test files at this stage (those are handled by Cass and Nigel)

package/.blueprint/features/feature_refine-feature-skill/story-initiation.md

@@ -0,0 +1,42 @@
+# Story: Refinement Initiation
+
+**As a** developer who has run `/implement-feature` and found the result does not fully match intent
+**I want** to run `/refine-feature [slug]` and have Alex load all existing artifacts for that feature
+**So that** I can start a targeted refinement without duplicating work already done
+
+## Acceptance Criteria
+
+### AC-1: Skill exists and accepts a slug argument
+**Given** murmur8 has been initialised in a project
+**When** the user runs `/refine-feature some-feature`
+**Then** the `/refine-feature` skill is recognised as a valid command and begins execution with `some-feature` as the target slug
+
+### AC-2: Missing FEATURE_SPEC.md produces a clear error
+**Given** no `FEATURE_SPEC.md` exists for the given slug
+**When** the user runs `/refine-feature missing-slug`
+**Then** the pipeline exits with a message indicating the spec was not found and no files are modified
+
+### AC-3: Alex reads existing artifacts before engaging the user
+**Given** a feature with an existing `FEATURE_SPEC.md`, one or more `story-*.md` files, and pipeline history
+**When** the refinement skill starts
+**Then** Alex reads the spec, all story files, and the most recent pipeline history entry for the slug before prompting the user
+
+### AC-4: Alex presents a current-state summary before asking for feedback
+**Given** Alex has loaded all existing artifacts
+**When** the context-loading phase completes
+**Then** Alex presents a brief summary (feature name, current scope, last run status) and then asks: "What needs to change?"
+
+### AC-5: featureId is read from YAML frontmatter
+**Given** `FEATURE_SPEC.md` contains a `featureId` in its YAML frontmatter
+**When** Alex initialises the refinement session
+**Then** the featureId value is captured and preserved for all subsequent writes in this run
+
+### AC-6: Missing featureId is added before refinement proceeds
+**Given** `FEATURE_SPEC.md` exists but has no `featureId` in its YAML frontmatter
+**When** the refinement skill starts
+**Then** Alex adds a new featureId to the frontmatter before proceeding, and logs that it was added
+
+## Out of Scope
+- Running refinement on multiple features in a single invocation
+- Forking or branching a feature into two separate features
+- Rolling back a feature to a previous state

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

@@ -0,0 +1,42 @@
+# Story: Story Propagation via Cass
+
+**As a** developer who has approved a spec diff
+**I want** Cass to update only the affected user story files and produce a `story-changes.md` summary
+**So that** stories stay in sync with the refined spec without unnecessary churn to unchanged stories
+
+## Acceptance Criteria
+
+### AC-1: Cass is skipped for technical features
+**Given** the original feature was classified as technical (no `story-*.md` files exist for the slug)
+**When** the refinement pipeline reaches the Cass stage
+**Then** the Cass stage is skipped and the pipeline proceeds directly to Nigel; a note is recorded in the run output
+
+### AC-2: Cass reads the spec diff not the full spec
+**Given** Alex has written an updated `FEATURE_SPEC.md`
+**When** Cass starts
+**Then** Cass reads `story-changes.md` (produced by Alex) to understand the scope of change before reading the full spec
+
+### AC-3: Only affected story files are updated
+**Given** a feature with multiple existing `story-*.md` files
+**When** Cass has identified which stories are affected by the spec diff
+**Then** Cass updates only those story files; stories not affected by the diff are left unchanged
+
+### AC-4: Cass produces a `story-changes.md` file
+**Given** Cass has completed updating stories
+**When** the Cass stage finishes
+**Then** a `story-changes.md` file exists in the feature directory listing which stories were changed and a brief reason for each change
+
+### AC-5: Cass does not delete existing stories without cause
+**Given** an existing story that is unaffected by the spec diff
+**When** Cass completes
+**Then** that story file is present and unmodified
+
+### AC-6: New stories are created if the spec diff adds new scope
+**Given** the approved diff introduces new user-facing behaviour not covered by any existing story
+**When** Cass processes the diff
+**Then** Cass creates a new `story-[slug].md` file for the new scope and lists it in `story-changes.md`
+
+## Out of Scope
+- Cass making changes to test files (that is Nigel's responsibility)
+- Cass engaging in conversation with the user about story scope
+- Bulk-updating all stories regardless of diff scope

package/.blueprint/features/feature_refine-feature-skill/story-telemetry-lineage.md

@@ -0,0 +1,47 @@
+# Story: Telemetry Lineage via parentRunId
+
+**As a** developer or team lead reviewing a feature's evolution over multiple refinements
+**I want** each refinement run to record a `parentRunId` linking it to the run it refines
+**So that** I can trace the full chain of refinements for any feature from pipeline history
+
+## Acceptance Criteria
+
+### AC-1: Refinement run records parentRunId in history
+**Given** a pipeline history entry exists for the slug being refined
+**When** the refinement run completes
+**Then** the history entry for this refinement run contains a `parentRunId` field set to the `runId` of the most recent prior run for that slug
+
+### AC-2: parentRunId is null when no prior history exists
+**Given** no pipeline history entry exists for the slug being refined
+**When** the refinement run records its history entry
+**Then** the `parentRunId` field is present and set to `null`; the run is not aborted or errored because of missing history
+
+### AC-3: Refinement run is recorded with type "refinement"
+**Given** a refinement run completes (successfully or with user abort)
+**When** the history entry is written
+**Then** the entry contains `"type": "refinement"` to distinguish it from original `"type": "implementation"` runs
+
+### AC-4: featureId is identical to the original run's featureId
+**Given** an original implementation run recorded a featureId for a slug
+**When** a refinement run for the same slug records its history entry
+**Then** the featureId in the refinement history entry is the same value as in the original run
+
+### AC-5: Telemetry payload uses artifact diffs, not full files
+**Given** spec, story, and test files were updated during the refinement
+**When** telemetry is emitted
+**Then** the payload contains before/after diffs for each changed artifact rather than the full file contents
+
+### AC-6: story-changes.md and test-changes.md are committed as audit trail
+**Given** Cass produced `story-changes.md` and/or Nigel produced `test-changes.md`
+**When** the pipeline commits at the end of a successful refinement
+**Then** both change summary files are included in the commit alongside the updated spec, story, and test files
+
+### AC-7: parentRunId chain is traversable across multiple refinements
+**Given** a feature has been refined three times, each run recording a parentRunId pointing to the previous
+**When** a developer queries the history for that slug
+**Then** the history entries can be ordered into a chain: run-1 ← run-2 ← run-3 ← run-4 via parentRunId links
+
+## Out of Scope
+- Visualising the refinement chain in the CLI (a future feature)
+- Preserving original artifact files alongside refined versions (git history provides rollback)
+- Changing the featureId at any point in the chain

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,58 @@
 # 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. 
+AI coding tools can be a black box. You describe what you want, magic 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. Agents Alex, Cass, Nigel, and Codey run 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 and building upon it.
 
-## 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` flag. This is useful when an idea is still fuzzy, you can 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. You can discuss with Alex whats not right, provide error logs, or user feedback. Alex reads what was built, and describes what needs to change, and 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.
+
+### Turning it up to 11
+
+If you using the skill with Claude Code or Github Copilot, or via an npx command, you can run multiple of these pipelines at the same time, working independantly on features in parallel. The pipeline look at whats required and work out how multiple fetaures can be delivered at the same time withough Nigel 1, 2, and 3 treading on each others toes in the code base. The pipeline runs EXACTLY the same way... just mutiple of them at the same time! 
+
+## 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 +71,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 |

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.6.0",
+  "version": "4.7.1",
   "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/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');
@@ -209,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/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,
+};