murmur8 3.5.0

package/.blueprint/features/feature_compressed-feedback/FEATURE_SPEC.md

@@ -0,0 +1,136 @@
+# Feature Specification — Compressed Feedback Prompts
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Current feedback prompts are verbose (~10 lines, ~200 tokens per stage)
+- Feedback is collected at 3 points: Cass→Alex, Nigel→Cass, Codey→Nigel
+- Total overhead: ~600 tokens per pipeline run
+- Compressed prompts achieve same result with ~3 lines each
+
+---
+
+## 2. Scope
+### In Scope
+- Rewrite feedback prompt sections to be more concise
+- Maintain same output format (JSON with rating, issues, recommendation)
+- Ensure feedback quality is not degraded
+
+### Out of Scope
+- Changing feedback data structure
+- Removing feedback collection
+- Changing quality gate thresholds
+
+---
+
+## 3. Actors Involved
+
+| Actor | Feedback Role |
+|-------|--------------|
+| Cass | Rates Alex's feature spec |
+| Nigel | Rates Cass's user stories |
+| Codey | Rates Nigel's tests |
+
+---
+
+## 4. Behaviour Overview
+
+**Current verbose prompt (~10 lines):**
+```
+FIRST, before writing stories, evaluate Alex's feature spec:
+- Rating (1-5): How clear and complete is the spec?
+- Issues: List any problems (e.g., "missing-error-handling", "unclear-scope")
+- Recommendation: "proceed" | "pause" | "revise"
+
+Output your feedback as:
+FEEDBACK: { "rating": N, "issues": [...], "recommendation": "..." }
+```
+
+**Compressed prompt (~3 lines):**
+```
+FEEDBACK FIRST: Rate prior stage 1-5, list issues (e.g., unclear-scope), recommend proceed|pause|revise.
+Format: FEEDBACK: {"rating":N,"issues":["..."],"rec":"proceed|pause|revise"}
+Then continue with your task.
+```
+
+**Key outcomes:**
+- ~400 fewer tokens per pipeline run (3 stages × ~130 token savings)
+- Same feedback data collected
+- Same quality gate functionality
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- No state changes
+- Feedback format unchanged
+- Quality gate logic unchanged
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description |
+|------|-------------|
+| Same output format | JSON structure must remain compatible with feedback.js |
+| Abbreviations allowed | "rec" instead of "recommendation" in output |
+| Examples condensed | One inline example instead of multiple lines |
+
+---
+
+## 7. Dependencies
+
+- SKILL.md feedback sections updated
+- `src/feedback.js` may need to accept abbreviated keys ("rec" → "recommendation")
+- No other module changes
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** ~400 token reduction per run
+- **Clarity:** Compressed prompts must still be unambiguous
+- **Risk:** Agents may misinterpret terse instructions
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- Agents can parse terse instructions correctly
+- Abbreviated JSON keys are acceptable
+- Feedback quality won't degrade with shorter prompts
+
+**Open Questions:**
+- Should we A/B test compressed vs verbose prompts?
+- Is "rec" acceptable or should we keep "recommendation"?
+- Do we need to update feedback.js to normalize keys?
+
+---
+
+## 10. Impact on System Specification
+
+- No impact on system specification
+- Feedback behaviour unchanged
+- Quality gates unchanged
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+- Rewrite Cass feedback prompt (rates Alex)
+- Rewrite Nigel feedback prompt (rates Cass)
+- Rewrite Codey feedback prompt (rates Nigel)
+- Update feedback.js if key normalization needed
+
+**Expected story boundaries:**
+- One story for prompt compression (all 3 stages)
+- One story for feedback.js updates if needed
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+| 2026-02-25 | Initial spec | Token efficiency improvement | Claude |

package/.blueprint/features/feature_compressed-feedback/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,40 @@
+# Implementation Plan — Compressed Feedback Prompts
+
+## Summary
+
+Compress verbose feedback prompts (~10 lines) to terse format (~3 lines) across three pipeline stages (Cass, Nigel, Codey). Update `src/feedback.js` to normalize the abbreviated "rec" key to "recommendation" and add a parsing function for extracting feedback JSON from agent output.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `SKILL.md` | Modify | Compress feedback prompts in Steps 6.5, 7.5, 8.5 |
+| `src/feedback.js` | Modify | Add key normalization and output parsing functions |
+
+## Implementation Steps
+
+1. **Add `normalizeFeedbackKeys()` to feedback.js** — Function that converts `{rec: "..."}` to `{recommendation: "..."}` while preserving existing full key.
+
+2. **Add `parseFeedbackFromOutput()` to feedback.js** — Regex-based parser to extract `FEEDBACK: {...}` JSON from agent output text.
+
+3. **Update `validateFeedback()` in feedback.js** — Accept both "rec" and "recommendation" keys by checking either before validation.
+
+4. **Export new functions from feedback.js** — Add `normalizeFeedbackKeys` and `parseFeedbackFromOutput` to module.exports.
+
+5. **Compress Step 6.5 prompt in SKILL.md** — Replace Cass→Alex verbose prompt with:
+   ```
+   FEEDBACK FIRST: Rate Alex's spec 1-5, list issues (e.g., unclear-scope), recommend proceed|pause|revise.
+   Format: FEEDBACK: {"rating":N,"issues":["..."],"rec":"proceed|pause|revise"}
+   Then continue with your task.
+   ```
+
+6. **Compress Step 7.5 prompt in SKILL.md** — Replace Nigel→Cass verbose prompt with similar terse format.
+
+7. **Compress Step 8.5 prompt in SKILL.md** — Replace Codey→Nigel verbose prompt with similar terse format.
+
+8. **Run tests** — Execute `node --test test/feature_compressed-feedback.test.js` to verify implementation.
+
+## Risks/Questions
+
+- **Agent interpretation:** Terse prompts may occasionally confuse agents; monitor initial runs for correct feedback format.
+- **Key preference:** If both "rec" and "recommendation" appear, current implementation prefers "recommendation" — this matches test expectations.

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 murmur8 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 `murmur8 insights --feedback` after sufficient runs
+2. Insights module calculates agent calibration (how predictive is their feedback of actual outcomes)
+3. User runs `murmur8 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
+  - `murmur8 feedback-config` (view)
+  - `murmur8 feedback-config set <key> <value>`
+  - `murmur8 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