orchestr8 2.4.0 → 2.6.0

package/.blueprint/features/feature_feedback-loop/FEATURE_SPEC.md

@@ -0,0 +1,347 @@
+# Feature Specification — Agent Feedback Loop
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- **Problem being addressed:** The orchestr8 pipeline executes sequentially but lacks intra-stage feedback. Agents cannot assess the quality of upstream artifacts, leading to silent propagation of poor-quality specifications, stories, or tests through the pipeline.
+- **User need:** Developers want visibility into how each agent perceives the quality of inputs from previous stages. When quality is low, the pipeline should pause for human review rather than proceeding with flawed inputs.
+- **System alignment:** Per SYSTEM_SPEC.md:Section 7 (Governing Rules), agents are expected to "flag deviations" and "not silently alter specifications". This feature operationalises that principle by requiring explicit quality assessment at each stage boundary.
+
+> This feature introduces a quality feedback mechanism that integrates with existing history, insights, and retry modules to create a closed-loop quality system.
+
+---
+
+## 2. Scope
+
+### In Scope
+
+- Feedback collection schema and data structure for agent assessments
+- Feedback capture at each stage boundary (Cass on Alex, Nigel on Cass, Codey on Nigel)
+- Quality gate logic: pause pipeline if feedback rating falls below threshold
+- Configuration management for feedback thresholds (`.claude/feedback-config.json`)
+- Storage of feedback in pipeline history entries
+- Insights extension: correlation analysis between feedback scores and outcomes
+- Retry integration: mapping feedback issues to retry strategies
+- CLI commands for feedback configuration and analysis
+
+### Out of Scope
+
+- Feedback from Alex (no prior stage to assess within the pipeline)
+- Automatic remediation based on feedback (human review required)
+- Cross-pipeline feedback aggregation (each run is independent)
+- Natural language feedback parsing (structured schema only)
+- Feedback on auto-commit stage (no agent assessment)
+
+---
+
+## 3. Actors Involved
+
+### Human User
+
+- **Can do:** View feedback thresholds; modify threshold configuration; view feedback correlation insights; review and approve paused pipelines
+- **Cannot do:** Directly inject feedback into history; bypass quality gates without explicit action
+
+### Cass (Story Writer Agent)
+
+- **Can do:** Provide feedback on Alex's feature specification before writing stories
+- **Feedback target:** Feature specification quality, completeness, clarity
+
+### Nigel (Tester Agent)
+
+- **Can do:** Provide feedback on Cass's user stories before writing tests
+- **Feedback target:** Story quality, acceptance criteria testability, scope clarity
+
+### Codey (Developer Agent)
+
+- **Can do:** Provide feedback on Nigel's test specification before planning/implementing
+- **Feedback target:** Test coverage, implementation feasibility, specification clarity
+
+### Pipeline Orchestrator (SKILL.md implementation)
+
+- **Can do:** Collect feedback from agents; evaluate against thresholds; persist to history; trigger quality gates
+- **Cannot do:** Override human decisions on paused pipelines
+
+### History Module (src/history.js)
+
+- **Extended by:** New `feedback` field in stage entries
+- **Maintains:** Backward compatibility with existing entries (no feedback = null)
+
+### Insights Module (src/insights.js)
+
+- **Extended by:** New `--feedback` analysis mode
+- **Provides:** Calibration scoring, issue pattern correlation
+
+### Retry Module (src/retry.js)
+
+- **Extended by:** Feedback-informed strategy selection
+- **Consumes:** Issue patterns from feedback to recommend targeted strategies
+
+---
+
+## 4. Behaviour Overview
+
+### Happy Path: Feedback Collection and Proceeding
+
+1. Alex completes feature specification
+2. Orchestrator spawns Cass with explicit instruction to provide feedback on Alex's output
+3. Cass writes feedback object (rating, confidence, issues, recommendation) to designated output
+4. Orchestrator reads feedback and evaluates against configured threshold (default: 3.0)
+5. Rating >= threshold: pipeline proceeds, feedback stored in history
+6. Cass proceeds to write user stories
+7. Pattern repeats for Nigel (feedback on Cass) and Codey (feedback on Nigel)
+8. On completion, all feedback is persisted in history entry
+
+### Alternative: Quality Gate Triggers Pause
+
+1. Agent provides feedback with rating < configured threshold
+2. Agent's recommendation is "pause" or "revise"
+3. Orchestrator pauses pipeline before current agent's main work
+4. User is prompted: "Quality gate triggered. {Agent} rated previous stage {rating}/5. Issues: {issues}. (review/proceed/abort)"
+5. User can review upstream artifacts, request revision, or proceed anyway
+6. Decision and feedback are recorded in history
+
+### Alternative: Dynamic Threshold Adjustment
+
+1. User runs `orchestr8 insights --feedback` after sufficient runs
+2. Insights module calculates agent calibration (how predictive is their feedback of actual outcomes)
+3. User runs `orchestr8 feedback-config set minRating 3.5` to adjust threshold based on data
+4. Future runs use updated threshold
+
+### Alternative: Retry with Feedback-Informed Strategy
+
+1. Pipeline fails at a stage (e.g., Codey cannot implement)
+2. Retry module examines feedback chain for the failed run
+3. Feedback issues are mapped to strategies:
+   - "missing-error-handling" → `add-context`
+   - "too-complex" → `simplify-prompt`
+   - "too-many-stories" → `reduce-stories`
+4. Recommended strategy reflects feedback analysis
+5. User accepts or chooses alternative
+
+---
+
+## 5. State & Lifecycle Interactions
+
+### States Entered
+
+- **feedback_pending:** After upstream agent completes, before downstream agent provides feedback
+- **quality_gate_paused:** When feedback triggers quality gate (rating < threshold)
+
+### States Exited
+
+- **feedback_pending → in_progress:** When feedback is recorded and threshold is met
+- **quality_gate_paused → in_progress:** When user chooses to proceed
+- **quality_gate_paused → paused:** When user requests review/revision
+
+### States Modified
+
+- Pipeline history entries gain `stages[].feedback` field
+- Queue entries may include temporary feedback data during execution
+
+### Lifecycle Classification
+
+- **State-creating:** Creates feedback_pending state at each stage boundary
+- **State-constraining:** Quality gates can block progression
+- **State-transitioning:** Moves between feedback states based on ratings
+
+---
+
+## 6. Rules & Decision Logic
+
+### Rule 1: Feedback Schema Validation
+
+- **Description:** All feedback must conform to the defined schema
+- **Inputs:** Agent feedback output
+- **Outputs:** Validated feedback object or validation error
+- **Type:** Deterministic
+
+```json
+{
+  "about": "alex|cass|nigel",
+  "rating": 1-5,
+  "confidence": 0.0-1.0,
+  "issues": ["issue-code", ...],
+  "recommendation": "proceed|pause|revise"
+}
+```
+
+### Rule 2: Quality Gate Evaluation
+
+- **Description:** Compare feedback rating against threshold to determine if pipeline should pause
+- **Inputs:** Feedback rating, configured threshold, recommendation
+- **Outputs:** Boolean (shouldPause)
+- **Type:** Deterministic
+
+```
+shouldPause = (rating < minRatingThreshold) OR (recommendation === "pause")
+```
+
+### Rule 3: Issue-to-Strategy Mapping
+
+- **Description:** Map feedback issue codes to retry strategies
+- **Inputs:** List of issue codes from feedback chain
+- **Outputs:** Prioritised list of recommended strategies
+- **Type:** Deterministic with configurable mappings
+
+Default mappings:
+| Issue Code | Strategy |
+|------------|----------|
+| `missing-error-handling` | `add-context` |
+| `unclear-scope` | `simplify-prompt` |
+| `too-complex` | `simplify-prompt` |
+| `too-many-stories` | `reduce-stories` |
+| `untestable-criteria` | `simplify-tests` |
+| `missing-edge-cases` | `add-context` |
+
+### Rule 4: Agent Calibration Calculation
+
+- **Description:** Measure correlation between agent feedback and eventual pipeline outcomes
+- **Inputs:** Historical feedback ratings, pipeline outcomes (success/failed)
+- **Outputs:** Calibration score per agent (0.0 = uncorrelated, 1.0 = perfect predictor)
+- **Type:** Deterministic (statistical calculation)
+
+```
+calibration[agent] = correlation(feedback_ratings[agent], outcome_success_binary)
+```
+
+### Rule 5: Threshold Recommendation
+
+- **Description:** Suggest optimal threshold based on historical data
+- **Inputs:** All feedback/outcome pairs, desired false positive/negative balance
+- **Outputs:** Recommended minRating threshold
+- **Type:** Deterministic
+
+---
+
+## 7. Dependencies
+
+### System Components
+
+- **src/history.js:** Extended to store feedback in history entries
+  - New field: `stages[stage].feedback` containing feedback object
+  - Backward compatible: existing entries without feedback are valid
+
+- **src/insights.js:** Extended with feedback analysis functions
+  - New function: `analyzeFeedbackCorrelation(history)`
+  - New CLI flag: `--feedback` for feedback-specific analysis
+
+- **src/retry.js:** Extended with feedback-informed strategy selection
+  - New function: `mapIssuesToStrategies(issues, config)`
+  - Modified: `shouldRetry()` to consider feedback chain
+
+- **bin/cli.js:** New command registration
+  - `orchestr8 feedback-config` (view)
+  - `orchestr8 feedback-config set <key> <value>`
+  - `orchestr8 insights --feedback`
+
+### File Dependencies
+
+- **`.claude/feedback-config.json`:** Configuration storage
+- **`.claude/pipeline-history.json`:** Extended schema for feedback storage
+
+### Agent Specification Dependencies
+
+- Agent prompts (in SKILL.md or agent specs) must include feedback collection instructions
+- Feedback schema must be communicated to agents in their task prompts
+
+---
+
+## 8. Non-Functional Considerations
+
+### Performance
+
+- Feedback collection adds one structured output per stage (minimal overhead)
+- Quality gate evaluation is O(1) comparison
+- Calibration calculation is O(n) over history entries
+
+### Resilience
+
+- If feedback collection fails, pipeline proceeds with warning (degraded mode)
+- Missing feedback in history is treated as neutral (no quality gate effect)
+- Invalid feedback schema triggers warning but does not block pipeline
+
+### Audit/Logging
+
+- All feedback is persisted in history for retrospective analysis
+- Quality gate decisions are logged with timestamp and user action
+
+### Security
+
+- Feedback file is gitignored (contains project-specific assessments)
+- No sensitive data expected in feedback (ratings, codes, recommendations only)
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+
+- ASSUMPTION: Agents can reliably produce structured feedback in the specified schema
+- ASSUMPTION: Feedback ratings are comparable across agents and runs
+- ASSUMPTION: Issue codes will emerge from practice and can be standardised iteratively
+- ASSUMPTION: Correlation analysis requires 10+ completed runs for meaningful results
+
+### Open Questions
+
+- Should feedback influence agent prompts proactively (not just on retry)?
+- How should conflicting feedback (high rating but "pause" recommendation) be handled?
+- Should there be feedback severity levels (blocking vs advisory)?
+- What feedback should Codey provide about Codey-plan (within same agent)?
+
+---
+
+## 10. Impact on System Specification
+
+### Reinforces Existing Assumptions
+
+- Per SYSTEM_SPEC.md:Section 7, agents must "flag deviations" - feedback formalises this
+- Per SYSTEM_SPEC.md:Section 8, failure handling already supports pause/review - quality gates extend this
+
+### Stretches Existing Assumptions
+
+- History module shifts from pure observability to operational dependency (also noted in adaptive-retry)
+- Agent boundaries are subtly extended: agents now assess peer outputs, not just produce artifacts
+- Pipeline flow gains conditional branches (quality gates) beyond explicit `--pause-after`
+
+### Potential Contradiction
+
+The system spec states pipelines are "sequential" (Section 7). Quality gates introduce conditional pauses that may feel like interruptions. However, this is consistent with the existing `--pause-after` mechanism and does not fundamentally alter sequence.
+
+**Flagged for consideration:** Should SYSTEM_SPEC.md:Section 6 be updated to explicitly acknowledge quality gates as a pipeline flow modifier?
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story Themes
+
+1. **Feedback Collection:** Agents provide structured feedback on upstream artifacts
+2. **Quality Gates:** Pipeline pauses when feedback indicates quality concerns
+3. **Configuration Management:** User can view and modify feedback thresholds
+4. **History Integration:** Feedback is stored in pipeline history entries
+5. **Insights Extension:** Feedback correlation analysis and calibration scoring
+6. **Retry Integration:** Feedback issues inform retry strategy selection
+
+### Expected Story Boundaries
+
+- Feedback schema definition and validation as foundational story
+- Quality gate logic as separate story (depends on schema)
+- CLI configuration commands as separate story (parallel track)
+- History integration as separate story (depends on schema)
+- Insights extension as separate story (depends on history integration)
+- Retry integration as separate story (depends on insights correlation)
+
+### Areas Needing Careful Story Framing
+
+- Feedback collection happens *within* agent execution; must not disrupt agent focus
+- Quality gate UX: user prompt must clearly explain situation and options
+- Issue code taxonomy: start with small set, plan for iterative expansion
+- Calibration display: statistical concepts must be presented accessibly
+
+---
+
+## 12. Change Log (Feature-Level)
+
+| Date       | Change                                | Reason                          | Raised By |
+|------------|---------------------------------------|---------------------------------|-----------|
+| 2026-02-24 | Initial feature specification created | Feature request for agent feedback system | Alex |

package/.blueprint/features/feature_feedback-loop/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,71 @@
+# Implementation Plan — Feedback Loop Feature
+
+## Summary
+
+This feature adds a quality feedback mechanism where downstream agents (Cass, Nigel, Codey) assess upstream artifacts before proceeding. Implementation requires a new `src/feedback.js` module for schema validation, quality gate logic, configuration management, and insights analysis. The existing `src/history.js`, `src/insights.js`, and `src/retry.js` modules need extensions to store, analyze, and act on feedback data.
+
+---
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/feedback.js` | Create | Core feedback logic: validation, quality gates, config management |
+| `src/history.js` | Modify | Add `storeStageFeedback()` and extend entry schema |
+| `src/insights.js` | Modify | Add feedback analysis: `analyzeFeedbackCorrelation()`, calibration |
+| `src/retry.js` | Modify | Add `mapIssuesToStrategies()` for feedback-informed retries |
+| `bin/cli.js` | Modify | Register `feedback-config` command and `insights --feedback` flag |
+| `src/index.js` | Modify | Export feedback module |
+
+---
+
+## Implementation Steps
+
+1. **Create `src/feedback.js` with schema validation** — Implement `validateFeedback()` per FEATURE_SPEC.md:Rule 1. Schema: `{about, rating, confidence, issues, recommendation}`. Return `{valid, errors}`.
+
+2. **Add quality gate logic to `src/feedback.js`** — Implement `shouldPause(feedback, config)` per FEATURE_SPEC.md:Rule 2. Returns true if `rating < minRatingThreshold` OR `recommendation === "pause"`.
+
+3. **Add config management to `src/feedback.js`** — Implement `getDefaultConfig()`, `readConfig()`, `writeConfig()`, `setConfigValue()`. Default: `{minRatingThreshold: 3.0, enabled: true, issueMappings: {...}}`.
+
+4. **Extend `src/history.js`** — Add `storeStageFeedback(slug, stage, feedback)` to persist feedback at `stages[stage].feedback`. Ensure backward compatibility (missing feedback = null).
+
+5. **Add calibration calculation to `src/insights.js`** — Implement `calculateCalibration(agent, history)` per FEATURE_SPEC.md:Rule 4. Return null if <10 runs with feedback, else correlation score 0-1.
+
+6. **Add issue correlation to `src/insights.js`** — Implement `correlateIssues(history)` to map issue codes to failure rates. Return `{issueCode: failureCorrelation}`.
+
+7. **Add threshold recommendation to `src/insights.js`** — Implement `recommendThreshold(history)` to suggest optimal minRatingThreshold based on historical data.
+
+8. **Extend `src/retry.js`** — Add `mapIssuesToStrategies(issues, config)` using default mappings from FEATURE_SPEC.md:Rule 3.
+
+9. **Register CLI commands in `bin/cli.js`** — Add `feedback-config` (view), `feedback-config set <key> <value>`, and `--feedback` flag to `insights` command.
+
+10. **Wire exports in `src/index.js`** — Export feedback module for orchestrator integration.
+
+---
+
+## Key Functions
+
+**src/feedback.js:**
+- `validateFeedback(feedback)` — Schema validation, returns `{valid, errors}`
+- `shouldPause(feedback, config)` — Quality gate evaluation
+- `getDefaultConfig()` / `readConfig()` / `writeConfig(config)` — Config I/O
+- `setConfigValue(key, value)` — CLI config setter with validation
+- `displayConfig()` — Pretty-print current config
+
+**src/insights.js (new):**
+- `calculateCalibration(agent, history)` — Agent calibration score
+- `correlateIssues(history)` — Issue-to-failure correlation
+- `recommendThreshold(history)` — Optimal threshold suggestion
+- `displayFeedbackInsights(options)` — CLI output for `--feedback`
+
+**src/retry.js (new):**
+- `mapIssuesToStrategies(issues, config)` — Feedback-informed strategy selection
+
+---
+
+## Risks/Questions
+
+- **Agent prompt integration**: Feedback collection requires agent prompts (in SKILL.md) to include feedback instructions. This is orchestrator-level work outside core modules.
+- **Calibration metric**: Tests use simple accuracy (predicted vs actual). May need Pearson correlation for better calibration measure in production.
+- **Issue taxonomy**: Starting with 6 issue codes per FEATURE_SPEC.md:Rule 3. Plan for iterative expansion.
+- **Conflicting signals**: Per FEATURE_SPEC.md:Section 9, high rating + "pause" recommendation is unresolved. Recommend: recommendation takes precedence.

package/.blueprint/features/feature_feedback-loop/story-feedback-collection.md

@@ -0,0 +1,63 @@
+# Story — Feedback Collection
+
+## User Story
+
+As a **pipeline orchestrator**, I want **downstream agents to provide structured feedback on upstream artifacts** so that **quality issues are surfaced explicitly at each stage boundary**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 4, feedback is collected at each stage boundary (Cass on Alex, Nigel on Cass, Codey on Nigel)
+- Feedback uses a defined schema with rating, confidence, issues, and recommendation
+- Feedback is captured before the downstream agent begins its main work
+- Per SYSTEM_SPEC.md:Section 7, agents must "flag deviations" — this story operationalises that principle
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — Feedback schema structure**
+- Given an agent is spawned to provide feedback,
+- When the agent completes feedback output,
+- Then the feedback object contains:
+  - `about`: agent name being assessed (alex|cass|nigel)
+  - `rating`: integer 1-5
+  - `confidence`: float 0.0-1.0
+  - `issues`: array of issue codes (may be empty)
+  - `recommendation`: one of "proceed", "pause", or "revise"
+
+**AC-2 — Cass provides feedback on Alex**
+- Given Alex has completed a feature specification,
+- When Cass is spawned for story writing,
+- Then Cass first produces a feedback object with `about: "alex"` assessing the feature spec quality.
+
+**AC-3 — Nigel provides feedback on Cass**
+- Given Cass has completed user stories,
+- When Nigel is spawned for test writing,
+- Then Nigel first produces a feedback object with `about: "cass"` assessing story quality and testability.
+
+**AC-4 — Codey provides feedback on Nigel**
+- Given Nigel has completed test specifications,
+- When Codey is spawned for planning/implementation,
+- Then Codey first produces a feedback object with `about: "nigel"` assessing test coverage and implementation feasibility.
+
+**AC-5 — Feedback validation**
+- Given an agent produces a feedback object,
+- When the orchestrator reads the feedback,
+- Then the feedback is validated against the schema,
+- And invalid feedback triggers a warning but does not block the pipeline (per FEATURE_SPEC.md:Section 8, degraded mode).
+
+**AC-6 — Feedback persisted to history**
+- Given feedback is collected from an agent,
+- When the stage completes,
+- Then the feedback is stored in the history entry at `stages[stage].feedback`.
+
+---
+
+## Out of Scope
+
+- Feedback from Alex (no prior stage to assess)
+- Feedback on auto-commit stage
+- Natural language feedback parsing (structured schema only)
+- Automatic remediation based on feedback

package/.blueprint/features/feature_feedback-loop/story-feedback-config.md

@@ -0,0 +1,61 @@
+# Story — Feedback Configuration
+
+## User Story
+
+As a **developer**, I want **CLI commands to view and modify feedback thresholds** so that **I can tune quality gate sensitivity based on my project's needs**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 7, configuration is stored in `.claude/feedback-config.json`
+- Per FEATURE_SPEC.md:Section 7, new CLI commands: `orchestr8 feedback-config` and `orchestr8 feedback-config set <key> <value>`
+- Parallel track to quality gates — configuration can be set independently
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — View feedback configuration**
+- Given the user runs `orchestr8 feedback-config`,
+- When the command executes,
+- Then the current configuration is displayed including:
+  - `minRatingThreshold` (default: 3.0)
+  - `enabled` (default: true)
+  - Any custom issue-to-strategy mappings
+
+**AC-2 — Set threshold value**
+- Given the user runs `orchestr8 feedback-config set minRating <value>`,
+- When the value is a number between 1.0 and 5.0,
+- Then the threshold is updated in `.claude/feedback-config.json`,
+- And a confirmation message is displayed.
+
+**AC-3 — Invalid threshold rejected**
+- Given the user runs `orchestr8 feedback-config set minRating <value>`,
+- When the value is outside 1.0-5.0 range or not a number,
+- Then an error message is displayed,
+- And the configuration is not modified.
+
+**AC-4 — Enable/disable feedback system**
+- Given the user runs `orchestr8 feedback-config set enabled <true|false>`,
+- When the command executes,
+- Then the `enabled` flag is updated,
+- And when disabled, feedback collection and quality gates are skipped.
+
+**AC-5 — Configuration file created on first set**
+- Given `.claude/feedback-config.json` does not exist,
+- When the user runs a `feedback-config set` command,
+- Then the file is created with default values plus the specified override.
+
+**AC-6 — Configuration file is gitignored**
+- Given a project is initialised with orchestr8,
+- When feedback configuration is created,
+- Then `.claude/feedback-config.json` is included in gitignore patterns.
+
+---
+
+## Out of Scope
+
+- Per-agent threshold configuration (single global threshold for MVP)
+- Custom issue code definition via CLI
+- Configuration import/export

package/.blueprint/features/feature_feedback-loop/story-feedback-insights.md

@@ -0,0 +1,63 @@
+# Story — Feedback Insights
+
+## User Story
+
+As a **developer**, I want **correlation analysis between feedback scores and pipeline outcomes** so that **I can understand how predictive agent feedback is and tune thresholds accordingly**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 7, extends `src/insights.js` with feedback analysis functions
+- Per FEATURE_SPEC.md:Section 6 (Rule 4), calculates agent calibration as correlation between ratings and outcomes
+- Depends on feedback being stored in history (story-feedback-collection.md)
+- Per FEATURE_SPEC.md:Section 9, requires 10+ completed runs for meaningful results
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — Feedback analysis command**
+- Given the user runs `orchestr8 insights --feedback`,
+- When sufficient history exists (10+ completed runs with feedback),
+- Then a feedback analysis report is displayed.
+
+**AC-2 — Agent calibration scoring**
+- Given the feedback analysis runs,
+- When calibration is calculated per agent,
+- Then each agent receives a calibration score (0.0-1.0):
+  - 0.0 = feedback uncorrelated with outcomes
+  - 1.0 = perfect predictor of success/failure
+- And the score is displayed as "Cass calibration: 0.72" format.
+
+**AC-3 — Issue pattern correlation**
+- Given feedback history contains issue codes,
+- When the analysis runs,
+- Then issue codes are correlated with failure outcomes,
+- And frequently predictive issues are highlighted (e.g., "`unclear-scope` preceded 80% of failures").
+
+**AC-4 — Threshold recommendation**
+- Given sufficient calibration data exists,
+- When the analysis runs,
+- Then a recommended `minRatingThreshold` is suggested based on historical data,
+- And the recommendation balances false positives (unnecessary pauses) and false negatives (missed quality issues).
+
+**AC-5 — Insufficient data handling**
+- Given the user runs `orchestr8 insights --feedback`,
+- When fewer than 10 completed runs with feedback exist,
+- Then a message is displayed: "Insufficient data for feedback analysis. {N}/10 runs with feedback available."
+
+**AC-6 — Retry strategy mapping**
+- Given feedback analysis identifies predictive issue patterns,
+- When the user views insights,
+- Then issue-to-strategy mappings are displayed (per FEATURE_SPEC.md:Rule 3),
+- And the user can see which retry strategies are recommended for common issues.
+
+---
+
+## Out of Scope
+
+- Cross-pipeline feedback aggregation (each project is independent)
+- Real-time calibration updates during pipeline execution
+- Natural language interpretation of feedback patterns
+- Automatic threshold adjustment (user must run `feedback-config set`)

package/.blueprint/features/feature_feedback-loop/story-quality-gates.md

@@ -0,0 +1,57 @@
+# Story — Quality Gates
+
+## User Story
+
+As a **developer**, I want **the pipeline to pause when feedback indicates quality concerns** so that **I can review and address issues before proceeding with flawed inputs**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 4 (Alternative: Quality Gate Triggers Pause), pipeline pauses when rating < threshold or recommendation is "pause"
+- Default threshold is 3.0 (per FEATURE_SPEC.md:Section 4)
+- Depends on feedback collection (story-feedback-collection.md)
+- Per SYSTEM_SPEC.md:Section 8, failure handling already supports pause/review — quality gates extend this
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — Quality gate evaluation**
+- Given feedback is collected from an agent,
+- When the orchestrator evaluates the feedback,
+- Then `shouldPause` is true if:
+  - `rating < minRatingThreshold`, OR
+  - `recommendation === "pause"`
+
+**AC-2 — Pipeline pauses on quality gate trigger**
+- Given `shouldPause` evaluates to true,
+- When the quality gate is triggered,
+- Then the pipeline pauses before the current agent begins its main work,
+- And the user is prompted with: "Quality gate triggered. {Agent} rated previous stage {rating}/5. Issues: {issues}. (review/proceed/abort)"
+
+**AC-3 — User can proceed past quality gate**
+- Given the pipeline is paused at a quality gate,
+- When the user chooses "proceed",
+- Then the pipeline continues with the current agent's main work,
+- And the decision is recorded in history.
+
+**AC-4 — User can abort at quality gate**
+- Given the pipeline is paused at a quality gate,
+- When the user chooses "abort",
+- Then the pipeline stops,
+- And the feature is moved to the failed list with reason "quality_gate_abort".
+
+**AC-5 — User can review at quality gate**
+- Given the pipeline is paused at a quality gate,
+- When the user chooses "review",
+- Then the pipeline remains paused,
+- And the user can examine upstream artifacts before deciding to proceed or abort.
+
+---
+
+## Out of Scope
+
+- Automatic remediation or revision of upstream artifacts
+- Multiple threshold levels per agent (single global threshold for MVP)
+- Bypassing quality gates without explicit user action