orchestr8 2.5.0 → 2.6.1

package/.blueprint/features/feature_agent-guardrails/story-citation-requirements.md

@@ -0,0 +1,50 @@
+# Story — Citation Requirements
+
+## User story
+
+As a user of orchestr8, I want all agent assertions to cite their source files so that I can trace claims back to authoritative inputs and verify correctness.
+
+---
+
+## Context / scope
+
+- Applies to all agents: Alex, Cass, Nigel, Codey
+- Per FEATURE_SPEC.md section 6, Rule 2: "All assertions about requirements, behaviour, or domain knowledge must cite their source"
+- Per SYSTEM_SPEC.md section 8: "Traceability" is a cross-cutting concern
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Standard citation format used**
+- Given an agent makes an assertion about requirements or behaviour,
+- When the assertion is included in output,
+- Then the assertion includes a citation in one of the standard formats: "Per [filename]: [claim]" or "[filename:section] states...".
+
+**AC-2 — Section-level citations where feasible**
+- Given an agent cites a source file with multiple sections,
+- When the assertion relates to a specific section,
+- Then the citation includes the section reference (e.g., "FEATURE_SPEC.md section 6" or "story-login.md:AC-3").
+
+**AC-3 — Assumptions distinguished from cited facts**
+- Given an agent includes both cited facts and assumptions in output,
+- When the output is reviewed,
+- Then assumptions are clearly labelled (e.g., "ASSUMPTION:" prefix) and distinguishable from cited assertions.
+
+**AC-4 — Domain knowledge grounded in business context**
+- Given an agent makes assertions about business or domain concepts,
+- When those concepts are defined in `.business_context/` files,
+- Then the assertion cites the specific business context file (e.g., ".business_context/glossary.md defines...").
+
+**AC-5 — Traceable chain maintained**
+- Given a downstream artifact (story, test, code) references upstream artifacts,
+- When the reference is made,
+- Then it includes sufficient citation to trace back to the source (story cites feature spec, test cites story, implementation cites test).
+
+---
+
+## Out of scope
+
+- Automated citation validation tooling
+- Link checking or broken reference detection
+- Citation index or cross-reference reports

package/.blueprint/features/feature_agent-guardrails/story-confidentiality.md

@@ -0,0 +1,50 @@
+# Story — Confidentiality
+
+## User story
+
+As a user of orchestr8, I want agents to treat business context and project content as confidential so that sensitive information is not leaked in outputs or exposed to external services.
+
+---
+
+## Context / scope
+
+- Applies to all agents: Alex, Cass, Nigel, Codey
+- Per FEATURE_SPEC.md section 6, Rule 3: "Agents must treat `.business_context/` content as confidential and prevent data leakage"
+- Per FEATURE_SPEC.md section 9, Open Question 3: "treat all project content as confidential by default"
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Business context not exposed verbatim**
+- Given an agent processes content from `.business_context/` directory,
+- When the agent produces output artifacts,
+- Then the output does not reproduce confidential details verbatim; instead it uses generic descriptions or summarises appropriately.
+
+**AC-2 — External entities not referenced by name**
+- Given an agent is aware of external projects, companies, or implementations from business context,
+- When producing output,
+- Then the agent does not reference these external entities by name in specifications, stories, or code comments.
+
+**AC-3 — No external service exposure**
+- Given an agent is processing project content,
+- When external services would expose project data (e.g., external APIs, logging services),
+- Then the agent does not use such services and keeps all processing local to the pipeline.
+
+**AC-4 — Self-contained outputs**
+- Given an agent produces an output artifact,
+- When the artifact is reviewed in isolation,
+- Then it does not require access to confidential business context to be understood; it is self-contained.
+
+**AC-5 — Confidentiality conflict escalation**
+- Given an output would require exposing confidential details,
+- When no acceptable redaction or generalisation is possible,
+- Then the agent flags the conflict and escalates to the user for guidance before proceeding.
+
+---
+
+## Out of scope
+
+- Encryption or access control mechanisms for business context files
+- Audit logging of confidential data access
+- Data loss prevention (DLP) tooling integration

package/.blueprint/features/feature_agent-guardrails/story-escalation-protocol.md

@@ -0,0 +1,55 @@
+# Story — Escalation Protocol
+
+## User story
+
+As a user of orchestr8, I want agents to escalate to me when they encounter ambiguity or missing information so that I can provide guidance rather than agents guessing incorrectly.
+
+---
+
+## Context / scope
+
+- Applies to all agents: Alex, Cass, Nigel, Codey
+- Per FEATURE_SPEC.md section 6, Rule 5: "Agents must escalate to the user under defined conditions rather than proceeding with guesses"
+- Per SYSTEM_SPEC.md section 7: "No silent changes: Agents flag deviations; do not silently alter specifications"
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Escalation on missing critical information**
+- Given information required for a task is not present in provided inputs,
+- When the information cannot be safely assumed (domain-specific, policy-related, or high-impact),
+- Then the agent escalates to the user with a clear question explaining what information is needed and why.
+
+**AC-2 — Escalation on significant ambiguity**
+- Given inputs are ambiguous in a way that significantly affects output,
+- When multiple interpretations are possible,
+- Then the agent lists the possible interpretations and asks the user to clarify before proceeding.
+
+**AC-3 — Escalation on source conflict**
+- Given different input sources contain conflicting information,
+- When the conflict cannot be resolved by recency or specificity rules,
+- Then the agent flags the conflict, cites both sources, and asks the user to resolve.
+
+**AC-4 — Escalation on confidentiality concern**
+- Given a task would require violating confidentiality constraints,
+- When no acceptable alternative approach exists,
+- Then the agent explains the concern and requests user guidance.
+
+**AC-5 — Explicit assumptions when escalation not warranted**
+- Given information is missing but a safe default exists,
+- When the assumption is low-risk and reversible,
+- Then the agent may proceed with an explicit assumption labelled as "ASSUMPTION:" or "NOTE: Assuming..." rather than escalating.
+
+**AC-6 — Anti-hallucination preference**
+- Given an agent lacks information to answer a question,
+- When asked to produce content,
+- Then the agent states "This information is not available in the provided inputs" rather than inventing an answer.
+
+---
+
+## Out of scope
+
+- Automated escalation routing or ticketing
+- Escalation SLAs or response time requirements
+- Multi-user escalation workflows

package/.blueprint/features/feature_agent-guardrails/story-source-restrictions.md

@@ -0,0 +1,50 @@
+# Story — Source Restrictions
+
+## User story
+
+As a user of orchestr8, I want agents to use only information from explicitly provided inputs so that outputs are grounded in authoritative sources and not hallucinated from training data or external content.
+
+---
+
+## Context / scope
+
+- Applies to all agents: Alex, Cass, Nigel, Codey
+- This is a behavioural constraint, not a runtime enforcement mechanism
+- Per FEATURE_SPEC.md section 6, Rule 1: "Agents must use ONLY information from explicitly provided inputs"
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Allowed sources are used**
+- Given an agent is processing a task,
+- When the agent produces output,
+- Then the output is derived exclusively from allowed sources: system specification, feature specifications, user stories, test artifacts, implementation code, business context, templates, and agent specifications.
+
+**AC-2 — Prohibited sources are not used**
+- Given an agent is processing a task,
+- When the agent encounters a gap in provided inputs,
+- Then the agent does not reference social media, forums, blog posts, web searches, external APIs, or external project implementations to fill that gap.
+
+**AC-3 — Training data not used for domain facts**
+- Given an agent needs domain-specific information (business rules, project requirements),
+- When that information is not present in provided inputs,
+- Then the agent does not use its training data to invent or assume domain facts; instead it flags the gap explicitly.
+
+**AC-4 — External references not introduced**
+- Given an agent is writing output artifacts,
+- When the output references patterns, examples, or implementations,
+- Then those references are to files within the project, not to external companies, products, or open-source projects.
+
+**AC-5 — Gap handling triggers assumption or escalation**
+- Given required information is not available in allowed sources,
+- When the agent cannot proceed without this information,
+- Then the agent either declares an explicit assumption (labelled as such) or escalates to the user.
+
+---
+
+## Out of scope
+
+- Runtime validation or filtering of agent outputs
+- Technical enforcement mechanisms (content blockers, API restrictions)
+- Monitoring infrastructure for source compliance

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.