murmur8 4.5.1 → 4.7.0

package/.blueprint/features/feature_pipeline-telemetry/story-telemetry-activation.md

@@ -0,0 +1,54 @@
+# Story — Telemetry Activation & Configuration
+
+### User story
+As a platform administrator, I want to activate pipeline telemetry by setting a URL in `.env` so that murmur8 sends structured execution data to my observability endpoint without requiring code changes.
+
+---
+
+### Context / scope
+- Configuration via `.env` file at project root and/or real environment variables
+- Activation is determined solely by the presence of `MURMUR8_TELEMETRY_URL`
+- Absence of the URL means telemetry is fully inactive — no output, no side effects
+
+---
+
+### Acceptance criteria
+
+**AC-1 — Telemetry inactive when URL is absent**
+- Given `MURMUR8_TELEMETRY_URL` is not set in `.env` or in the process environment,
+- When a pipeline run completes,
+- Then no HTTP request is made, no queue file is created, and no output is produced.
+
+**AC-2 — Telemetry active when URL is set in `.env`**
+- Given `MURMUR8_TELEMETRY_URL` is set to a valid URL in `.env`,
+- When a pipeline run completes,
+- Then `src/telemetry.js` POSTs the payload to that URL.
+
+**AC-3 — Real environment variable takes precedence over `.env`**
+- Given `MURMUR8_TELEMETRY_URL` is set to `https://env-value.example.com` in the process environment,
+- And `.env` contains `MURMUR8_TELEMETRY_URL=https://dotenv-value.example.com`,
+- When telemetry resolves the endpoint,
+- Then the request is sent to `https://env-value.example.com` (the process env value).
+
+**AC-4 — API key sent as Authorization header when set**
+- Given `MURMUR8_TELEMETRY_KEY` is set (in `.env` or environment),
+- When the telemetry POST is made,
+- Then the request includes the header `Authorization: Bearer <key>`.
+
+**AC-5 — Authorization header omitted when key is absent**
+- Given `MURMUR8_TELEMETRY_KEY` is not set,
+- When the telemetry POST is made,
+- Then no `Authorization` header is included in the request.
+
+**AC-6 — Same precedence rule applies to API key**
+- Given `MURMUR8_TELEMETRY_KEY` is set in both the process environment and `.env` with different values,
+- When telemetry resolves the key,
+- Then the process environment value is used.
+
+---
+
+### Out of scope
+- Opt-out flag (absence of URL is the opt-out mechanism)
+- Validating or enforcing HTTPS on the configured URL
+- Telemetry for non-pipeline CLI commands (`history`, `queue`, etc.)
+- Any third-party `.env` parsing library (manual parsing only)

package/.blueprint/features/feature_pipeline-telemetry/story-telemetry-config-command.md

@@ -0,0 +1,52 @@
+# Story — telemetry-config CLI Command
+
+### User story
+As a platform administrator, I want to run `murmur8 telemetry-config` to view the current telemetry configuration so that I can confirm the endpoint is configured correctly and check the failed-send queue depth — without exposing the API key in plaintext.
+
+---
+
+### Context / scope
+- New CLI command: `murmur8 telemetry-config` (registered in `bin/cli.js`, handled by `src/commands/telemetry-config.js`)
+- Reads configuration from `.env` and process environment (same precedence rules as telemetry module)
+- Displays configured URL; masks the API key; shows failed queue depth
+
+---
+
+### Acceptance criteria
+
+**AC-1 — Command displays configured URL**
+- Given `MURMUR8_TELEMETRY_URL` is set,
+- When `murmur8 telemetry-config` is run,
+- Then the output includes the full configured URL.
+
+**AC-2 — API key is masked in output**
+- Given `MURMUR8_TELEMETRY_KEY` is set to a non-empty value,
+- When `murmur8 telemetry-config` is run,
+- Then the output displays the key in masked form (e.g. `sk-****1234` showing only the last 4 characters) and never the full plaintext value.
+
+**AC-3 — Key shown as "not set" when absent**
+- Given `MURMUR8_TELEMETRY_KEY` is not configured,
+- When `murmur8 telemetry-config` is run,
+- Then the output indicates no key is configured (e.g. `not set`).
+
+**AC-4 — Command shows telemetry as inactive when URL is absent**
+- Given `MURMUR8_TELEMETRY_URL` is not set,
+- When `murmur8 telemetry-config` is run,
+- Then the output clearly indicates telemetry is inactive (e.g. `status: inactive`).
+
+**AC-5 — Failed queue depth is displayed**
+- Given `.claude/telemetry-failed.json` exists with N entries,
+- When `murmur8 telemetry-config` is run,
+- Then the output includes the number of queued failed sends (e.g. `failed queue: 3 entries`).
+
+**AC-6 — Failed queue shown as zero when file is absent**
+- Given `.claude/telemetry-failed.json` does not exist,
+- When `murmur8 telemetry-config` is run,
+- Then the output shows a failed queue depth of 0.
+
+---
+
+### Out of scope
+- A `--test` flag to send a synthetic ping to the endpoint
+- Editing or clearing configuration via this command (read-only display)
+- Displaying the full contents of the failed send queue

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