orchestr8 2.5.0 → 2.6.0

package/.blueprint/features/feature_pipeline-history/story-display-history.md

@@ -0,0 +1,75 @@
+# Story — Display Pipeline History
+
+## User story
+
+As a developer using orchestr8, I want to view recent pipeline runs via CLI so that I can review execution history and identify patterns.
+
+---
+
+## Context / scope
+
+- New CLI command: `orchestr8 history`
+- Displays tabular list of recent pipeline executions
+- Per FEATURE_SPEC.md:Section 6 (Rule: Display Limit Default), shows last 10 runs by default
+- Requires `.claude/pipeline-history.json` to exist with valid entries
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Display recent runs**
+- Given `.claude/pipeline-history.json` contains history entries,
+- When I run `orchestr8 history`,
+- Then I see a list of the 10 most recent runs showing: slug, status, date, total duration.
+
+**AC-2 — Display all runs with flag**
+- Given `.claude/pipeline-history.json` contains more than 10 entries,
+- When I run `orchestr8 history --all`,
+- Then I see all history entries (not truncated to 10).
+
+**AC-3 — Empty history message**
+- Given `.claude/pipeline-history.json` is empty or does not exist,
+- When I run `orchestr8 history`,
+- Then I see a message: "No pipeline history found."
+
+**AC-4 — Corrupted file handling**
+- Given `.claude/pipeline-history.json` contains invalid JSON,
+- When I run `orchestr8 history`,
+- Then I see a warning: "History file is corrupted. Run 'orchestr8 history clear' to reset."
+- And the command exits with code 0 (non-blocking).
+
+**AC-5 — Status colour coding**
+- Given history entries with different statuses,
+- When displayed in the terminal,
+- Then `success` entries show in green, `failed` in red, `paused` in yellow.
+
+**AC-6 — Most recent first ordering**
+- Given multiple history entries,
+- When displayed,
+- Then entries are ordered by `completedAt` descending (most recent first).
+
+---
+
+## CLI output format
+
+```
+Pipeline History (showing 10 of 25 runs)
+
+  SLUG              STATUS    DATE                  DURATION
+  user-auth         success   2026-02-24 10:15:00   15m 32s
+  payment-flow      failed    2026-02-24 09:45:00   8m 12s (failed at: nigel)
+  checkout-page     paused    2026-02-23 16:30:00   5m 00s (paused at: cass)
+  ...
+
+Run 'orchestr8 history --all' to see all entries.
+Run 'orchestr8 history --stats' for aggregate statistics.
+```
+
+---
+
+## Out of scope
+
+- Filtering by status (e.g., `--status=failed`)
+- Filtering by date range
+- Pagination beyond simple `--all` flag
+- Detailed per-stage breakdown in list view (use `--stats` for that)

package/.blueprint/features/feature_pipeline-history/story-record-execution.md

@@ -0,0 +1,76 @@
+# Story — Record Pipeline Execution
+
+## User story
+
+As a developer using orchestr8, I want pipeline execution data to be automatically recorded during runs so that I have historical data for later analysis.
+
+---
+
+## Context / scope
+
+- Applies to all pipeline invocations via `/implement-feature`
+- Recording occurs at stage boundaries: alex, cass, nigel, codey-plan, codey-implement
+- Data persisted to `.claude/pipeline-history.json`
+- Per FEATURE_SPEC.md:Section 5 (State & Lifecycle), recording creates new history entries without altering pipeline flow
+
+---
+
+## Acceptance criteria
+
+**AC-1 — History entry created on pipeline completion**
+- Given I invoke `/implement-feature "my-feature"`,
+- When the pipeline completes successfully,
+- Then a history entry is appended to `.claude/pipeline-history.json` with status `success`.
+
+**AC-2 — History entry created on pipeline failure**
+- Given I invoke `/implement-feature "my-feature"`,
+- When a stage fails during execution,
+- Then a history entry is appended with status `failed` and the failing stage recorded.
+
+**AC-3 — History entry created on pipeline pause**
+- Given I invoke `/implement-feature "my-feature" --pause-after=cass`,
+- When the pipeline pauses after the specified stage,
+- Then a history entry is appended with status `paused` and stages completed up to the pause point.
+
+**AC-4 — Timestamps recorded per stage**
+- Given a pipeline run completes (success, failure, or pause),
+- When the history entry is created,
+- Then each completed stage has `startedAt` and `completedAt` timestamps in ISO 8601 format.
+
+**AC-5 — History file created if absent**
+- Given `.claude/pipeline-history.json` does not exist,
+- When a pipeline run completes,
+- Then the file is created with an array containing the single history entry.
+
+**AC-6 — Recording failure does not abort pipeline**
+- Given the history file cannot be written (e.g., permissions error),
+- When a pipeline run completes,
+- Then a warning is logged but the pipeline completes normally.
+
+---
+
+## History entry structure
+
+```json
+{
+  "slug": "my-feature",
+  "status": "success" | "failed" | "paused",
+  "startedAt": "2026-02-24T10:00:00.000Z",
+  "completedAt": "2026-02-24T10:15:00.000Z",
+  "stages": {
+    "alex": { "startedAt": "...", "completedAt": "...", "durationMs": 120000 },
+    "cass": { "startedAt": "...", "completedAt": "...", "durationMs": 90000 },
+    ...
+  },
+  "failedStage": "nigel" | null
+}
+```
+
+---
+
+## Out of scope
+
+- Real-time metrics streaming during execution
+- Detailed error logs or stack traces (only stage-level status)
+- Modifying past history entries
+- History file rotation or size management

package/.blueprint/features/feature_pipeline-history/story-show-statistics.md

@@ -0,0 +1,85 @@
+# Story — Show Pipeline Statistics
+
+## User story
+
+As a developer using orchestr8, I want to see aggregate statistics about pipeline performance so that I can identify bottlenecks and improvement opportunities.
+
+---
+
+## Context / scope
+
+- New CLI flag: `orchestr8 history --stats`
+- Computes statistics from all entries in `.claude/pipeline-history.json`
+- Per FEATURE_SPEC.md:Section 6 (Rule: Statistics Aggregation), statistics are computed on-read
+- Per FEATURE_SPEC.md:Section 4 (User-visible outcomes): success rate, avg duration, common failure stage
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Display success rate**
+- Given history contains both successful and failed runs,
+- When I run `orchestr8 history --stats`,
+- Then I see the success rate as a percentage (e.g., "Success rate: 85% (17/20 runs)").
+
+**AC-2 — Display average duration per stage**
+- Given history contains completed runs,
+- When I run `orchestr8 history --stats`,
+- Then I see average duration for each stage (alex, cass, nigel, codey-plan, codey-implement).
+
+**AC-3 — Display total average duration**
+- Given history contains completed runs,
+- When I run `orchestr8 history --stats`,
+- Then I see the average total pipeline duration across all successful runs.
+
+**AC-4 — Display most common failure stage**
+- Given history contains failed runs,
+- When I run `orchestr8 history --stats`,
+- Then I see the stage that has failed most frequently (e.g., "Most common failure: nigel (3 failures)").
+
+**AC-5 — Handle ties in failure stage**
+- Given multiple stages have equal failure counts,
+- When I run `orchestr8 history --stats`,
+- Then all tied stages are listed (e.g., "Most common failures: cass, nigel (2 each)").
+
+**AC-6 — No failures message**
+- Given history contains only successful runs,
+- When I run `orchestr8 history --stats`,
+- Then I see "No failures recorded" instead of failure stage data.
+
+**AC-7 — Insufficient data message**
+- Given history is empty or has no completed runs,
+- When I run `orchestr8 history --stats`,
+- Then I see "Insufficient data for statistics. Complete at least one pipeline run."
+
+---
+
+## CLI output format
+
+```
+Pipeline Statistics (based on 25 runs)
+
+  METRIC                    VALUE
+  Success rate              85% (17/20 completed runs)
+  Total runs                25 (17 success, 5 failed, 3 paused)
+  Avg pipeline duration     12m 45s
+
+  STAGE           AVG DURATION    FAILURES
+  alex            2m 30s          0
+  cass            1m 45s          1
+  nigel           3m 00s          3
+  codey-plan      1m 15s          0
+  codey-implement 4m 15s          1
+
+  Most common failure: nigel (3 failures)
+```
+
+---
+
+## Out of scope
+
+- Median duration (per FEATURE_SPEC.md:Section 9 open question)
+- Percentile calculations (p50, p90, p99)
+- Time-range filtering for statistics
+- Graphical visualisations
+- Export to external formats

package/.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md

@@ -0,0 +1,288 @@
+# Feature Specification — Pipeline Insights
+
+## 1. Feature Intent
+
+**Why this feature exists.**
+
+- **Problem being addressed:** The pipeline-history feature captures execution data but provides only basic statistics. Users cannot identify optimization opportunities—such as bottleneck stages, failure patterns, or performance trends—without manual analysis of the raw history data.
+- **User need:** Developers want actionable recommendations to improve pipeline efficiency. They need to understand which stages are slowest, why failures occur, and whether the pipeline is improving or degrading over time.
+- **System purpose alignment:** Per SYSTEM_SPEC.md:Section 8 (Cross-Cutting Concerns:Observability), the system aims for observability via queue status and agent summaries. Per SYSTEM_SPEC.md:Section 2 (Business & Domain Context), orchestr8 seeks to provide "structured processes to guide AI-generated code." This feature extends observability into actionable intelligence, enabling users to optimize their development workflow.
+
+> This feature builds upon the existing pipeline-history feature (`.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`) without modifying history recording. It is a read-only analysis layer.
+
+---
+
+## 2. Scope
+
+### In Scope
+
+- New CLI command `orchestr8 insights` that analyzes `.claude/pipeline-history.json`
+- Bottleneck detection: Identify which stage consistently takes longest
+- Failure pattern analysis: Determine which stages fail most and correlate with feature characteristics
+- Anomaly detection: Flag runs that deviate significantly from average durations
+- Trend analysis: Track whether pipeline performance is improving or degrading over time
+- Agent performance comparison: Compare stage durations and success rates across agents
+- Flag support for filtering analysis types (`--bottlenecks`, `--failures`, `--json`)
+- Human-readable recommendations based on detected patterns
+
+### Out of Scope
+
+- Modifying pipeline-history recording logic (that feature is separate)
+- Machine learning or complex statistical models (simple heuristics only)
+- Automatic remediation or pipeline configuration changes
+- Integration with external analytics platforms
+- Predictive modelling of future pipeline performance
+- Feature-type classification (assumes slugs are opaque identifiers)
+
+---
+
+## 3. Actors Involved
+
+### Human User
+
+- **Can do:** Invoke `orchestr8 insights` to view optimization recommendations; filter by analysis type; export as JSON for programmatic use
+- **Cannot do:** Modify the analysis thresholds or algorithms; act on recommendations automatically
+
+### Insights Analyzer (internal component)
+
+- **Can do:** Read history file; compute statistics; generate recommendations; output formatted reports
+- **Cannot do:** Write to history file; modify pipeline configuration; alter agent behaviour
+
+---
+
+## 4. Behaviour Overview
+
+### Happy-path behaviour
+
+1. User runs `orchestr8 insights` after accumulating several pipeline runs
+2. System reads `.claude/pipeline-history.json` and validates data sufficiency
+3. System performs analysis across four dimensions: bottlenecks, failures, anomalies, trends
+4. System generates human-readable report with recommendations
+5. User reviews recommendations and decides which to act upon
+
+### Key alternatives or branches
+
+- **Insufficient data:** If fewer than 3 runs exist, display message: "Insufficient data for insights. Complete at least 3 pipeline runs."
+- **No failures:** If all runs succeeded, omit failure analysis section; note "No failures recorded"
+- **Filtered analysis:** If `--bottlenecks` or `--failures` flag provided, display only that section
+- **JSON output:** If `--json` flag provided, output structured JSON instead of formatted text
+- **Corrupted history:** If history file is corrupted, display warning and exit gracefully
+
+### User-visible outcomes
+
+- Identification of the slowest pipeline stage with percentage of total time
+- List of stages with high failure rates and potential contributing factors
+- Flagged anomalous runs that deviated significantly from norms
+- Trend indicators showing improvement or degradation over recent runs
+- Actionable recommendations for each identified issue
+
+---
+
+## 5. State & Lifecycle Interactions
+
+### States entered
+
+- None. This feature is stateless and read-only.
+
+### States modified
+
+- None. This feature does not modify any system state.
+
+### This feature is:
+
+- **Not state-creating:** Does not persist analysis results
+- **Not state-transitioning:** Does not alter pipeline flow
+- **Not state-constraining:** Does not block any operations
+
+This is a pure read-only analysis feature that operates on existing history data.
+
+---
+
+## 6. Rules & Decision Logic
+
+### Rule: Bottleneck Detection
+
+- **Description:** Identify the stage that consumes the largest proportion of total pipeline time
+- **Inputs:** Stage durations from successful runs
+- **Outputs:** Stage name, average duration, percentage of total pipeline time
+- **Algorithm:** Calculate mean duration per stage; identify stage with highest mean; compute as percentage of sum
+- **Threshold:** Report as bottleneck if stage accounts for >35% of total pipeline time
+- **Deterministic:** Yes
+
+### Rule: Failure Pattern Analysis
+
+- **Description:** Identify stages with disproportionate failure rates and correlate with feature characteristics
+- **Inputs:** All history entries with status `failed`; feature slugs
+- **Outputs:** Failure rate per stage; most common failure stage; correlation hints
+- **Algorithm:** Count failures by stage; compute failure rate as failures/total runs for that stage; identify features with repeated failures
+- **Threshold:** Report as concerning if failure rate >15%
+- **Deterministic:** Yes
+
+### Rule: Anomaly Detection
+
+- **Description:** Flag individual runs where stage duration deviates significantly from average
+- **Inputs:** Stage durations from all runs; calculated means and standard deviations
+- **Outputs:** List of anomalous runs with stage, actual duration, expected duration
+- **Algorithm:** Calculate mean and standard deviation per stage; flag if duration > mean + 2*stddev
+- **Threshold:** 2 standard deviations above mean
+- **Scope:** Last 10 runs only (to limit output)
+- **Deterministic:** Yes
+
+### Rule: Trend Analysis
+
+- **Description:** Determine if pipeline performance is improving or degrading over time
+- **Inputs:** All history entries, sorted chronologically
+- **Outputs:** Success rate trend (improving/stable/degrading); duration trend (improving/stable/degrading)
+- **Algorithm:** Compare metrics from first half vs second half of history; compute percentage change
+- **Thresholds:** Improving if >10% better; degrading if >10% worse; stable otherwise
+- **Minimum data:** Requires at least 6 runs to compute trends
+- **Deterministic:** Yes
+
+### Rule: Agent Performance Comparison
+
+- **Description:** Compare duration and success metrics across agent stages
+- **Inputs:** All history entries with stage data
+- **Outputs:** Ranked list of stages by average duration; success rate per stage
+- **Algorithm:** Aggregate durations and success/failure counts per stage; rank by mean duration
+- **Deterministic:** Yes
+
+### Rule: Recommendation Generation
+
+- **Description:** Generate actionable recommendations based on detected patterns
+- **Inputs:** Analysis results from all rules above
+- **Outputs:** Human-readable recommendation strings
+- **Logic:**
+  - If bottleneck stage is >40% of time → "Consider simplifying {stage} requirements or splitting features"
+  - If failure rate >20% on a stage → "Review {stage} agent configuration or specification clarity"
+  - If anomalies detected → "Investigate flagged runs for unusual feature complexity"
+  - If degrading trend → "Review recent changes to agent specifications or system spec"
+- **Deterministic:** Yes (same inputs produce same recommendations)
+
+---
+
+## 7. Dependencies
+
+### System components
+
+- `src/history.js` — Must expose `readHistoryFile()` function; currently exports this
+- `bin/cli.js` — Must register new `insights` command
+- `.claude/pipeline-history.json` — Must exist with entries from pipeline-history feature
+
+### Upstream features
+
+- **pipeline-history** (`.blueprint/features/feature_pipeline-history/`) — This feature depends entirely on history data recorded by pipeline-history. The history entry schema (slug, status, stages, timestamps, durations) must be stable.
+
+### External systems
+
+- None
+
+### Operational dependencies
+
+- File system read access to `.claude/pipeline-history.json`
+
+---
+
+## 8. Non-Functional Considerations
+
+### Performance sensitivity
+
+- Analysis is computed on-demand from full history file
+- ASSUMPTION: History files contain <500 entries; O(n) algorithms acceptable
+- No caching required; each invocation recomputes from scratch
+
+### Audit/logging needs
+
+- None. This feature is read-only and does not produce persistent outputs.
+
+### Error tolerance
+
+- If history file is missing, display "No history found. Run some pipelines first."
+- If history file is corrupted, display warning and exit gracefully
+- If insufficient data for specific analysis, skip that section with explanation
+
+### Security implications
+
+- Feature slugs may reveal project information; output to terminal only
+- JSON output should not include sensitive data beyond what is already in history file
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+
+- ASSUMPTION: The history entry schema from pipeline-history is stable: `{ slug, status, stages, completedAt, totalDurationMs }`
+- ASSUMPTION: Stage names are fixed: `alex`, `cass`, `nigel`, `codey-plan`, `codey-implement`
+- ASSUMPTION: 2 standard deviations is an appropriate anomaly threshold for this domain
+- ASSUMPTION: 6 runs provides sufficient data for meaningful trend analysis
+- ASSUMPTION: Users will act on recommendations manually; no automation required
+
+### Open Questions
+
+- Should anomaly detection consider stage-specific thresholds rather than uniform 2-stddev?
+- Should trend analysis use a sliding window rather than first-half/second-half comparison?
+- Should there be a `--verbose` flag for more detailed analysis output?
+- Should the feature support analysis of a specific time range (e.g., last 30 days)?
+
+---
+
+## 10. Impact on System Specification
+
+### Alignment assessment
+
+This feature **reinforces existing system assumptions**:
+
+- Per SYSTEM_SPEC.md:Section 8 (Observability), the system already aims for visibility into pipeline execution
+- Per SYSTEM_SPEC.md:Section 5 (Core Domain Concepts), the queue and pipeline concepts are well-defined
+- This feature adds an intelligence layer without altering core pipeline behaviour
+
+### No contradictions identified
+
+The feature does not alter:
+
+- Agent roles or boundaries
+- Pipeline flow or stage order
+- Artifact structures or handoff mechanisms
+- History recording behaviour (defers entirely to pipeline-history feature)
+
+### Minor extension to system spec
+
+The following addition to SYSTEM_SPEC.md:Section 5 (Core Domain Concepts) may be warranted:
+
+> **Pipeline Insights** — An analysis layer that examines historical pipeline data to identify bottlenecks, failure patterns, anomalies, and trends. Provides recommendations for pipeline optimization without modifying pipeline behaviour.
+
+This is flagged as a **non-breaking extension** for consideration.
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story themes
+
+1. **Bottleneck analysis** — Identifying and reporting the slowest pipeline stages
+2. **Failure pattern analysis** — Analyzing failure frequency and generating recommendations
+3. **Anomaly detection** — Flagging runs that deviate significantly from averages
+4. **Trend analysis** — Computing and displaying performance trends over time
+5. **JSON output** — Supporting programmatic consumption of insights data
+
+### Expected story boundaries
+
+- Core insights engine (statistics computation) may be shared across stories
+- Each analysis type (bottlenecks, failures, anomalies, trends) is a candidate for separate story
+- JSON output support could be combined with any analysis story or kept separate
+- CLI command registration is infrastructure supporting all stories
+
+### Areas needing careful story framing
+
+- The threshold values (35% for bottleneck, 15% for failure rate, 2-stddev for anomaly) should be explicitly stated in acceptance criteria
+- The minimum data requirements (3 runs for basic insights, 6 runs for trends) need clear edge case handling
+- The recommendation text generation needs precise acceptance criteria for consistent output
+- Handling of ties in "most common failure stage" should be explicit
+
+---
+
+## 12. Change Log (Feature-Level)
+
+| Date       | Change                                | Reason                                    | Raised By |
+|------------|---------------------------------------|-------------------------------------------|-----------|
+| 2026-02-24 | Initial feature specification created | Extend pipeline-history with actionable insights | Alex |

package/.blueprint/features/feature_pipeline-insights/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,65 @@
+# Implementation Plan — Pipeline Insights
+
+## Summary
+
+This feature adds a new `orchestr8 insights` CLI command that performs read-only analysis of pipeline history data. It computes bottleneck detection, failure patterns, anomaly detection, and trend analysis, outputting human-readable recommendations or JSON. The implementation creates a new `src/insights.js` module that reuses `readHistoryFile()` from the existing `src/history.js`.
+
+---
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/insights.js` | Create | Core analysis engine with all computation logic |
+| `bin/cli.js` | Modify | Register `insights` command and route flags |
+
+---
+
+## Implementation Steps
+
+1. **Create `src/insights.js` scaffold** - Export main `displayInsights(options)` function that reads history via `readHistoryFile()` and validates minimum data (3 runs).
+
+2. **Implement bottleneck analysis** - Calculate average duration per stage across successful runs; identify stage with highest mean; compute percentage of total; flag if >35%; generate recommendation if >40%.
+
+3. **Implement failure pattern analysis** - Count failures by stage; compute failure rate per stage; identify most common failure stage; list features with repeated failures; flag if rate >15%; generate recommendation if >20%.
+
+4. **Implement anomaly detection** - Calculate mean and stddev per stage from all runs; evaluate last 10 runs; flag any stage duration exceeding mean + 2*stddev; include slug, stage, actual, expected, deviation in output.
+
+5. **Implement trend analysis** - Require 6+ runs; split history into first and second halves; compare success rates and average durations; classify as improving/stable/degrading based on 10% threshold; show percentage change.
+
+6. **Implement output formatters** - Create `formatTextOutput(analysis)` for human-readable output and `formatJsonOutput(analysis)` for structured JSON; handle section filtering based on flags.
+
+7. **Handle edge cases** - Missing history file returns "No history found"; corrupted file shows warning; insufficient data (<3 runs) shows appropriate message; no failures omits failure section with "No failures recorded".
+
+8. **Register CLI command** - In `bin/cli.js`, import `displayInsights` from `src/insights.js`; add `insights` command with flag parsing for `--bottlenecks`, `--failures`, `--json`.
+
+9. **Run tests and verify** - Execute `node --test test/feature_pipeline-insights.test.js` after each file change; ensure all tests pass.
+
+10. **Final cleanup** - Verify output formatting matches AC requirements; ensure recommendations use exact wording from spec.
+
+---
+
+## Key Functions
+
+**In `src/insights.js`:**
+- `displayInsights(options)` - Main entry point; orchestrates analysis and output
+- `analyzeBottlenecks(history)` - Returns `{ stage, avgDurationMs, percentage, isBottleneck, recommendation }`
+- `analyzeFailures(history)` - Returns `{ failuresByStage, mostCommonStage, repeatedFeatures, recommendation }`
+- `detectAnomalies(history)` - Returns `{ anomalies: [{slug, stage, actual, expected, deviation}], recommendation }`
+- `analyzeTrends(history)` - Returns `{ successRate: {trend, change}, duration: {trend, change}, recommendation }`
+- `formatTextOutput(analysis, sections)` - Formats analysis as human-readable text
+- `formatJsonOutput(analysis, sections)` - Formats analysis as JSON object
+- `calculateMean(values)` - Helper: compute arithmetic mean
+- `calculateStdDev(values, mean)` - Helper: compute population standard deviation
+
+**In `bin/cli.js`:**
+- Extend `parseFlags()` to recognize `--bottlenecks`, `--failures`, `--json`
+- Add `insights` command entry in `commands` object
+
+---
+
+## Risks/Questions
+
+- **History schema assumption**: Implementation assumes `stages` is an object with `{name: {durationMs}}` structure per test-spec.md. If actual schema differs, adapter logic may be needed.
+- **Tie-breaking**: Per test-spec.md, ties in "most common failure stage" resolved by first occurrence. Implementation should use stable sort or maintain insertion order.
+- **Standard deviation formula**: Using population stddev (N divisor) per test-spec.md assumption, not sample stddev (N-1).

package/.blueprint/features/feature_pipeline-insights/story-anomaly-detection.md

@@ -0,0 +1,71 @@
+# Story — Anomaly Detection
+
+## User story
+
+As a developer, I want to identify pipeline runs where stage durations deviated significantly from normal so that I can investigate unusual behaviour and understand outliers.
+
+---
+
+## Context / scope
+
+- User has accumulated enough history data to establish baseline metrics
+- Analysis uses statistical deviation (mean + 2*stddev) to identify anomalies
+- Scope limited to last 10 runs to keep output manageable
+- This is a read-only analysis; no pipeline state is modified
+- Route: `orchestr8 insights` (anomaly section included by default)
+
+Per FEATURE_SPEC.md:Section 6 (Rule: Anomaly Detection):
+- Threshold: 2 standard deviations above mean
+- Scope: Last 10 runs only
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Detect anomalous stage durations**
+- Given the history file contains at least 3 pipeline runs,
+- When the user runs `orchestr8 insights`,
+- Then the output includes an "Anomalies" section listing any runs where a stage duration exceeded mean + 2*stddev.
+
+**AC-2 — Display anomaly details**
+- Given an anomalous run is detected,
+- When the analysis completes,
+- Then the output shows: feature slug, stage name, actual duration, expected duration (mean), and deviation factor.
+
+**AC-3 — Limit scope to recent runs**
+- Given the history contains more than 10 runs,
+- When anomaly detection is performed,
+- Then only the most recent 10 runs are evaluated for anomalies.
+
+**AC-4 — Generate recommendation when anomalies found**
+- Given one or more anomalous runs are detected,
+- When the analysis completes,
+- Then the output includes the recommendation: "Investigate flagged runs for unusual feature complexity".
+
+**AC-5 — No anomalies detected**
+- Given all recent runs have stage durations within 2 standard deviations of the mean,
+- When the user runs `orchestr8 insights`,
+- Then the anomalies section displays: "No anomalies detected in recent runs."
+
+**AC-6 — Insufficient data for statistics**
+- Given the history file contains fewer than 3 runs,
+- When anomaly detection is attempted,
+- Then it is skipped with explanation: "Insufficient data for anomaly detection."
+
+---
+
+## Out of scope
+
+- Configurable standard deviation threshold
+- Stage-specific anomaly thresholds
+- Anomaly detection for failure counts (only duration-based)
+- Historical anomaly tracking beyond last 10 runs
+- Automatic investigation or drill-down into anomalous 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`