murmur8 3.5.0

package/.blueprint/features/feature_pipeline-insights/story-bottleneck-analysis.md

@@ -0,0 +1,75 @@
+# Story — Bottleneck Analysis
+
+## User story
+
+As a developer, I want to identify which pipeline stage consistently takes the longest so that I can focus optimization efforts where they will have the greatest impact.
+
+---
+
+## Context / scope
+
+- User has executed multiple pipeline runs via `/implement-feature`
+- History data exists in `.claude/pipeline-history.json`
+- This is a read-only analysis; no pipeline state is modified
+- Route: `murmur8 insights` or `murmur8 insights --bottlenecks`
+
+Per FEATURE_SPEC.md:Section 6 (Rule: Bottleneck Detection):
+- Bottleneck threshold: >35% of total pipeline time
+- Recommendation threshold: >40% of total pipeline time
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Display bottleneck stage**
+- Given the history file contains at least 3 successful pipeline runs,
+- When the user runs `murmur8 insights`,
+- Then the output includes a "Bottlenecks" section identifying the stage with the highest average duration.
+
+**AC-2 — Show percentage of total time**
+- Given a bottleneck stage is identified,
+- When the analysis completes,
+- Then the output displays the stage name, average duration in milliseconds, and percentage of total pipeline time.
+
+**AC-3 — Bottleneck threshold reporting**
+- Given a stage accounts for more than 35% of total pipeline time,
+- When the analysis completes,
+- Then that stage is flagged as a bottleneck in the output.
+
+**AC-4 — Generate recommendation for severe bottleneck**
+- Given a stage accounts for more than 40% of total pipeline time,
+- When the analysis completes,
+- Then the output includes the recommendation: "Consider simplifying {stage} requirements or splitting features".
+
+**AC-5 — Filter to bottlenecks only**
+- Given the user runs `murmur8 insights --bottlenecks`,
+- When the analysis completes,
+- Then only the bottleneck analysis section is displayed (other analysis types are omitted).
+
+**AC-6 — Insufficient data handling**
+- Given the history file contains fewer than 3 runs,
+- When the user runs `murmur8 insights`,
+- Then the output displays: "Insufficient data for insights. Complete at least 3 pipeline runs."
+
+**AC-7 — Missing history file handling**
+- Given no history file exists at `.claude/pipeline-history.json`,
+- When the user runs `murmur8 insights`,
+- Then the output displays: "No history found. Run some pipelines first."
+
+---
+
+## Out of scope
+
+- Modifying the history file or pipeline configuration
+- Customizing the 35%/40% threshold values
+- Providing automated remediation
+- Stage-specific threshold configuration
+- Analysis of partial/in-progress runs
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

package/.blueprint/features/feature_pipeline-insights/story-failure-patterns.md

@@ -0,0 +1,75 @@
+# Story — Failure Pattern Analysis
+
+## User story
+
+As a developer, I want to analyze which pipeline stages fail most frequently so that I can identify systemic issues and improve pipeline reliability.
+
+---
+
+## Context / scope
+
+- User has executed multiple pipeline runs, some of which have failed
+- History data includes entries with `status: "failed"` and associated stage information
+- This is a read-only analysis; no pipeline state is modified
+- Route: `murmur8 insights` or `murmur8 insights --failures`
+
+Per FEATURE_SPEC.md:Section 6 (Rule: Failure Pattern Analysis):
+- Failure rate threshold: >15% is reported as concerning
+- Recommendation threshold: >20% triggers specific recommendation
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Display failure rates per stage**
+- Given the history file contains at least 3 pipeline runs with at least one failure,
+- When the user runs `murmur8 insights`,
+- Then the output includes a "Failure Patterns" section showing failure rate for each stage that has experienced failures.
+
+**AC-2 — Identify most common failure stage**
+- Given failures exist in the history,
+- When the analysis completes,
+- Then the output identifies the stage with the highest failure count as the "most common failure stage".
+
+**AC-3 — Flag concerning failure rates**
+- Given a stage has a failure rate greater than 15%,
+- When the analysis completes,
+- Then that stage is flagged as having a concerning failure rate.
+
+**AC-4 — Generate recommendation for high failure rate**
+- Given a stage has a failure rate greater than 20%,
+- When the analysis completes,
+- Then the output includes the recommendation: "Review {stage} agent configuration or specification clarity".
+
+**AC-5 — Identify features with repeated failures**
+- Given the same feature slug has failed multiple times,
+- When the analysis completes,
+- Then those features are listed as correlation hints (e.g., "Feature 'complex-auth' has failed 3 times").
+
+**AC-6 — Filter to failures only**
+- Given the user runs `murmur8 insights --failures`,
+- When the analysis completes,
+- Then only the failure pattern analysis section is displayed (other analysis types are omitted).
+
+**AC-7 — No failures recorded**
+- Given all pipeline runs in history have status "completed" (no failures),
+- When the user runs `murmur8 insights`,
+- Then the failure analysis section displays: "No failures recorded" and is omitted from recommendations.
+
+---
+
+## Out of scope
+
+- Automatic correlation with feature complexity metrics
+- Root cause analysis beyond stage identification
+- Failure notification or alerting
+- Retry or remediation automation
+- Classification of failure types (timeout vs error vs abort)
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

package/.blueprint/features/feature_pipeline-insights/story-json-output.md

@@ -0,0 +1,75 @@
+# Story — JSON Output
+
+## User story
+
+As a developer, I want to export pipeline insights as structured JSON so that I can integrate the analysis with other tools or process the data programmatically.
+
+---
+
+## Context / scope
+
+- User wants machine-readable output instead of human-readable text
+- JSON output contains all the same analysis data as text output
+- Enables integration with CI/CD pipelines, dashboards, or custom tooling
+- This is a read-only analysis; no pipeline state is modified
+- Route: `murmur8 insights --json`
+
+Per FEATURE_SPEC.md:Section 4 (Key alternatives or branches):
+- `--json` flag produces structured JSON instead of formatted text
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Output JSON when flag provided**
+- Given the history file contains valid pipeline data,
+- When the user runs `murmur8 insights --json`,
+- Then the output is valid JSON (parseable by `JSON.parse()`).
+
+**AC-2 — Include bottleneck data in JSON**
+- Given bottleneck analysis completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes a `bottlenecks` object with: `stage`, `averageDurationMs`, `percentageOfTotal`, `isBottleneck`, `recommendation` (if applicable).
+
+**AC-3 — Include failure data in JSON**
+- Given failure analysis completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes a `failures` object with: `failuresByStage` (array), `mostCommonFailureStage`, `featuresWithRepeatedFailures` (array), `recommendation` (if applicable).
+
+**AC-4 — Include anomaly data in JSON**
+- Given anomaly detection completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes an `anomalies` object with: `detected` (array of anomalous runs), `recommendation` (if applicable).
+
+**AC-5 — Include trend data in JSON**
+- Given trend analysis completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes a `trends` object with: `successRate` (trend + percentage), `duration` (trend + percentage), `recommendation` (if applicable).
+
+**AC-6 — Combine JSON with filter flags**
+- Given the user runs `murmur8 insights --json --bottlenecks`,
+- When the analysis completes,
+- Then the JSON output includes only the `bottlenecks` section (other analysis types are omitted).
+
+**AC-7 — Handle insufficient data in JSON**
+- Given there is insufficient data for analysis,
+- When `--json` flag is provided,
+- Then the JSON output includes an `error` field with the appropriate message (e.g., `{"error": "Insufficient data for insights. Complete at least 3 pipeline runs."}`).
+
+---
+
+## Out of scope
+
+- Exporting JSON to a file (output to stdout only)
+- JSON schema validation or versioning
+- Compressed or minified JSON output options
+- Integration with specific external platforms
+- Historical JSON output comparison
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

package/.blueprint/features/feature_pipeline-insights/story-trend-analysis.md

@@ -0,0 +1,78 @@
+# Story — Trend Analysis
+
+## User story
+
+As a developer, I want to track whether pipeline performance is improving or degrading over time so that I can understand the impact of changes and maintain development efficiency.
+
+---
+
+## Context / scope
+
+- User has accumulated sufficient history to compare earlier vs later runs
+- Analysis compares first half vs second half of history data
+- Requires minimum 6 runs to compute meaningful trends
+- This is a read-only analysis; no pipeline state is modified
+- Route: `murmur8 insights` (trends section included by default)
+
+Per FEATURE_SPEC.md:Section 6 (Rule: Trend Analysis):
+- Improving: >10% better in second half
+- Degrading: >10% worse in second half
+- Stable: within 10% variance
+- Minimum data: 6 runs required
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Display success rate trend**
+- Given the history file contains at least 6 pipeline runs,
+- When the user runs `murmur8 insights`,
+- Then the output includes a "Trends" section showing success rate trend as "improving", "stable", or "degrading".
+
+**AC-2 — Display duration trend**
+- Given the history file contains at least 6 pipeline runs,
+- When the user runs `murmur8 insights`,
+- Then the output includes average duration trend as "improving" (faster), "stable", or "degrading" (slower).
+
+**AC-3 — Calculate trend by comparing halves**
+- Given the history contains N runs (where N >= 6),
+- When trend analysis is performed,
+- Then the first N/2 runs are compared against the last N/2 runs to determine trend direction.
+
+**AC-4 — Apply threshold for trend classification**
+- Given the percentage change between halves is calculated,
+- When classifying the trend,
+- Then >10% improvement shows "improving", >10% degradation shows "degrading", and within 10% shows "stable".
+
+**AC-5 — Generate recommendation for degrading trend**
+- Given either success rate or duration trend is "degrading",
+- When the analysis completes,
+- Then the output includes the recommendation: "Review recent changes to agent specifications or system spec".
+
+**AC-6 — Insufficient data for trends**
+- Given the history file contains fewer than 6 runs,
+- When trend analysis is attempted,
+- Then it is skipped with explanation: "Insufficient data for trend analysis. Need at least 6 runs."
+
+**AC-7 — Show percentage change**
+- Given trend analysis completes successfully,
+- When the output is displayed,
+- Then the percentage change for both success rate and duration is shown alongside the trend indicator.
+
+---
+
+## Out of scope
+
+- Sliding window trend analysis (uses fixed first-half/second-half)
+- Time-based trend analysis (e.g., last 30 days)
+- Per-stage trend analysis
+- Trend visualization or charting
+- Predictive modelling of future performance
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

package/.blueprint/features/feature_shared-guardrails/FEATURE_SPEC.md

@@ -0,0 +1,119 @@
+# Feature Specification — Shared Guardrails
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- The same guardrails section (~45 lines, ~400 tokens) is duplicated verbatim in all 4 agent specification files
+- This wastes ~1,200 tokens per pipeline run (4 agents reading identical content)
+- Extracting to a shared file reduces token usage and ensures consistency when guardrails are updated
+
+---
+
+## 2. Scope
+### In Scope
+- Extract guardrails section to `.blueprint/agents/GUARDRAILS.md`
+- Update all agent specs to reference the shared file
+- Ensure agents still read and apply guardrails
+
+### Out of Scope
+- Changing the content of guardrails
+- Agent-specific guardrail variations (all agents use same guardrails currently)
+
+---
+
+## 3. Actors Involved
+
+| Actor | Can Do | Cannot Do |
+|-------|--------|-----------|
+| Alex | Read shared guardrails, apply to outputs | Modify guardrails |
+| Cass | Read shared guardrails, apply to outputs | Modify guardrails |
+| Nigel | Read shared guardrails, apply to outputs | Modify guardrails |
+| Codey | Read shared guardrails, apply to outputs | Modify guardrails |
+
+---
+
+## 4. Behaviour Overview
+
+**Happy path:**
+1. Pipeline invokes agent (e.g., Alex)
+2. Agent reads slim spec file which references `GUARDRAILS.md`
+3. Agent reads `GUARDRAILS.md` once
+4. Agent applies guardrails to all outputs
+
+**Key outcomes:**
+- Identical guardrail enforcement as before
+- ~1,200 fewer tokens per pipeline run
+- Single source of truth for guardrail updates
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- No state changes — this is a structural refactor
+- Agent behaviour is unchanged
+- Pipeline flow is unchanged
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description |
+|------|-------------|
+| Single source | All agents reference the same `GUARDRAILS.md` file |
+| Read once | Each agent reads guardrails once per invocation |
+| No override | Agent specs cannot override shared guardrails |
+
+---
+
+## 7. Dependencies
+
+- All 4 agent specification files must be updated
+- SKILL.md agent prompts may need adjustment if they reference guardrails directly
+- `src/init.js` and `src/update.js` must handle the new file during init/update
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** Reduces token usage by ~1,200 per run
+- **Maintainability:** Single file to update when guardrails change
+- **Consistency:** Eliminates risk of guardrails drifting between agents
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- All agents will continue to use identical guardrails
+- Agents can follow file references (read file X when spec says "see file X")
+
+**Open Questions:**
+- Should agent prompts explicitly include guardrails content, or trust agents to read the reference?
+
+---
+
+## 10. Impact on System Specification
+
+- Reinforces existing system assumptions (guardrails apply to all agents)
+- No contradiction with system spec
+- No system spec change required
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+- Extract guardrails to shared file
+- Update agent specs to reference shared file
+- Update init/update commands to handle new file
+
+**Expected story boundaries:**
+- One story for file extraction and agent spec updates
+- One story for init/update command changes
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+| 2026-02-25 | Initial spec | Token efficiency improvement | Claude |

package/.blueprint/features/feature_shared-guardrails/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,34 @@
+# Implementation Plan — Shared Guardrails
+
+## Summary
+
+Extract the duplicated ~45-line guardrails section from all 4 agent specifications into a new `.blueprint/agents/GUARDRAILS.md` file, then update each agent spec to reference the shared file instead of containing inline guardrails. No code changes required in init.js or update.js since they already copy the entire `agents/` directory.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `.blueprint/agents/GUARDRAILS.md` | Create | New shared guardrails file containing extracted content |
+| `.blueprint/agents/AGENT_SPECIFICATION_ALEX.md` | Modify | Remove inline guardrails, add reference to GUARDRAILS.md |
+| `.blueprint/agents/AGENT_BA_CASS.md` | Modify | Remove inline guardrails, add reference to GUARDRAILS.md |
+| `.blueprint/agents/AGENT_TESTER_NIGEL.md` | Modify | Remove inline guardrails, add reference to GUARDRAILS.md |
+| `.blueprint/agents/AGENT_DEVELOPER_CODEY.md` | Modify | Remove inline guardrails, add reference to GUARDRAILS.md |
+
+## Implementation Steps
+
+1. **Create GUARDRAILS.md** - Extract the guardrails section (lines 169-210 from AGENT_SPECIFICATION_ALEX.md) into new file at `.blueprint/agents/GUARDRAILS.md`. Content includes: Allowed Sources, Prohibited Sources, Citation Requirements, Assumptions vs Facts, Confidentiality, Escalation Protocol.
+
+2. **Update AGENT_SPECIFICATION_ALEX.md** - Remove the inline `## Guardrails` section (lines 169-210). Add reference: `## Guardrails\n\nRead and apply the shared guardrails from: `.blueprint/agents/GUARDRAILS.md``
+
+3. **Update AGENT_BA_CASS.md** - Remove inline guardrails section (lines 383-425). Add same reference format.
+
+4. **Update AGENT_TESTER_NIGEL.md** - Remove inline guardrails section (lines 174-216). Add same reference format.
+
+5. **Update AGENT_DEVELOPER_CODEY.md** - Remove inline guardrails section (lines 426-468). Add same reference format.
+
+6. **Run tests** - Execute `node --test test/feature_shared-guardrails.test.js` to verify all ACs pass.
+
+## Risks/Questions
+
+- ASSUMPTION: Claude agents can follow file references and will read GUARDRAILS.md when instructed. Per story-extract-guardrails.md:Notes, this is a documented assumption.
+- No code changes needed in src/init.js or src/update.js since `agents/` is already in the UPDATABLE array (per story-update-init-commands.md:Notes).

package/.blueprint/features/feature_shared-guardrails/story-extract-guardrails.md

@@ -0,0 +1,60 @@
+# Story — Extract Guardrails to Shared File
+
+## User story
+As a framework maintainer, I want to extract the duplicated guardrails section from all agent specification files into a single shared GUARDRAILS.md file so that guardrails are maintained in one place and token usage is reduced.
+
+---
+
+## Context / scope
+- Affects all 4 agent specifications (Alex, Cass, Nigel, Codey)
+- Guardrails section is currently ~45 lines / ~400 tokens per agent
+- New file location: `.blueprint/agents/GUARDRAILS.md`
+- This is a structural refactor; agent behaviour remains unchanged
+
+Per FEATURE_SPEC.md:Section 1: "The same guardrails section (~45 lines, ~400 tokens) is duplicated verbatim in all 4 agent specification files"
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Shared guardrails file exists**
+- Given the `.blueprint/agents/` directory,
+- When the shared guardrails feature is implemented,
+- Then a new file `GUARDRAILS.md` exists at `.blueprint/agents/GUARDRAILS.md`
+- And it contains the complete guardrails content (Allowed Sources, Prohibited Sources, Citation Requirements, Assumptions vs Facts, Confidentiality, Escalation Protocol sections).
+
+**AC-2 — Agent specs reference shared file**
+- Given each agent specification file (AGENT_SPECIFICATION_ALEX.md, AGENT_BA_CASS.md, AGENT_TESTER_NIGEL.md, AGENT_DEVELOPER_CODEY.md),
+- When the shared guardrails feature is implemented,
+- Then the inline guardrails section is removed from each file
+- And each file contains a reference to read `.blueprint/agents/GUARDRAILS.md`.
+
+**AC-3 — Guardrails content is identical**
+- Given the new `GUARDRAILS.md` file,
+- When comparing its content to the original inline guardrails,
+- Then the content is identical (no additions, removals, or modifications to guardrail rules).
+
+**AC-4 — Agent specs remain functional**
+- Given an agent (e.g., Alex) reads its specification file,
+- When the specification references `GUARDRAILS.md`,
+- Then the agent can locate and read the shared guardrails file
+- And the agent applies all guardrails to its outputs.
+
+**AC-5 — No duplicate guardrails remain**
+- Given all 4 agent specification files,
+- When searching for guardrails sections,
+- Then no file contains inline guardrails content (only the reference to the shared file).
+
+---
+
+## Out of scope
+- Modifying the content of guardrails (per FEATURE_SPEC.md:Section 2)
+- Agent-specific guardrail variations
+- Changes to init/update commands (covered in separate story)
+- Modifying agent prompts in SKILL.md
+
+---
+
+## Notes
+- Per FEATURE_SPEC.md:Section 6, agents cannot override shared guardrails
+- Per FEATURE_SPEC.md:Section 9, ASSUMPTION: Agents can follow file references (read file X when spec says "see file X")

package/.blueprint/features/feature_shared-guardrails/story-update-init-commands.md

@@ -0,0 +1,63 @@
+# Story — Update Init/Update Commands for Shared Guardrails
+
+## User story
+As a user installing or updating murmur8, I want the init and update commands to correctly handle the new GUARDRAILS.md file so that the shared guardrails are properly distributed to target projects.
+
+---
+
+## Context / scope
+- Affects `src/init.js` (initialization command)
+- Affects `src/update.js` (update command)
+- New file `.blueprint/agents/GUARDRAILS.md` must be included in both operations
+- Existing behaviour for other files remains unchanged
+
+Per FEATURE_SPEC.md:Section 7: "src/init.js and src/update.js must handle the new file during init/update"
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Init copies GUARDRAILS.md**
+- Given a user runs `murmur8 init` in a new project,
+- When the `.blueprint/agents/` directory is copied,
+- Then the `GUARDRAILS.md` file is included in the copied content
+- And the file is placed at `.blueprint/agents/GUARDRAILS.md` in the target project.
+
+**AC-2 — Update replaces GUARDRAILS.md**
+- Given a user runs `murmur8 update` in an existing project,
+- When the `.blueprint/agents/` directory is updated,
+- Then the `GUARDRAILS.md` file is replaced with the latest version from the package
+- And the file is placed at `.blueprint/agents/GUARDRAILS.md` in the target project.
+
+**AC-3 — Update preserves user content directories**
+- Given a user runs `murmur8 update`,
+- When the update process completes,
+- Then `features/` and `system_specification/` directories remain untouched
+- And only `agents/`, `templates/`, and `ways_of_working/` are replaced.
+
+**AC-4 — Agent specs with references are copied**
+- Given the agent specification files now reference `GUARDRAILS.md`,
+- When init or update copies the agent specs,
+- Then all agent specs (AGENT_*.md) are copied with their guardrails references intact
+- And no orphaned guardrails references exist (GUARDRAILS.md is always present when agent specs reference it).
+
+**AC-5 — Backward compatibility**
+- Given an existing project with old agent specs (containing inline guardrails),
+- When a user runs `murmur8 update`,
+- Then the old agent specs are replaced with new specs referencing GUARDRAILS.md
+- And the new GUARDRAILS.md file is added to the project.
+
+---
+
+## Out of scope
+- Changes to the guardrails content itself
+- Changes to SKILL.md agent prompts
+- Changes to queue management or pipeline flow
+- User content migration (users do not have custom guardrails)
+
+---
+
+## Notes
+- Per SYSTEM_SPEC.md:Section 8, the update command replaces framework directories while preserving user content
+- The `agents/` directory is listed in UPDATABLE array in `src/update.js`, so GUARDRAILS.md will be handled automatically once it exists in the source
+- No code changes are expected in init.js or update.js since they copy entire directories; the change is purely in the source assets