murmur8 4.5.0 → 4.6.0

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

@@ -0,0 +1,229 @@
+# Feature Specification — Feedback Module Test Suite
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- **Problem being addressed:** The `src/feedback.js` module provides foundational logic for the agent feedback loop — schema validation, quality gate evaluation, key normalisation, config management, and feedback parsing. No test file directly imports and exercises this module's exported API. Existing tests (feature_feedback-loop, feature_compressed-feedback) re-implement helper logic inline rather than testing the real module, leaving the production code untested.
+- **User need:** Developers maintaining or extending `src/feedback.js` need confidence that the exported functions behave correctly and that regressions are caught immediately by the test suite.
+- **System alignment:** Per SYSTEM_SPEC.md:Section 7 (Implementation Rules), "tests are contracts" and the suite must be green before a feature is considered complete. Untested production modules violate this principle and expose the pipeline to silent breakage.
+
+> This feature creates a direct unit-test harness for `src/feedback.js`, closing the coverage gap introduced by the feedback-loop and compressed-feedback features.
+
+---
+
+## 2. Scope
+
+### In Scope
+
+- Unit tests that `require('../src/feedback')` and call its exported functions directly
+- Coverage of all exported functions:
+  - `validateFeedback(feedback)` — schema validation
+  - `normalizeFeedbackKeys(feedback)` — `rec` → `recommendation` normalisation
+  - `parseFeedbackFromOutput(output)` — regex extraction and JSON parsing
+  - `shouldPause(feedback, config)` — quality gate decision logic
+  - `getDefaultConfig()` — default config shape and values
+  - `readConfig()` — file read with fallback to defaults
+  - `writeConfig(config)` — file write
+  - `setConfigValue(key, value)` — validated config mutation
+  - `resetConfig()` — restores defaults
+  - `displayConfig()` — smoke test (no crash, correct output shape)
+- File system isolation using `tmp` directories, matching the pattern established by `feature_feedback-loop.test.js`
+- Edge cases: corrupt config file, missing config file, boundary rating values, both `rec` and `recommendation` keys present
+
+### Out of Scope
+
+- Testing agent prompt text (covered by feature_compressed-feedback)
+- Integration tests spanning multiple modules (covered by feature_feedback-loop)
+- Testing `displayConfig` output formatting exhaustively (smoke test only)
+- Testing the insights calibration or issue-correlation logic (covered by feature_feedback-loop:Feedback Insights)
+
+---
+
+## 3. Actors Involved
+
+### Developer / Test Runner
+
+- **Can do:** Run `node --test test/feature_feedback-test.test.js` to verify `src/feedback.js` behaviour
+- **Cannot do:** Modify production code via test execution
+
+### src/feedback.js (module under test)
+
+- **Provides:** All exported functions listed in Section 2
+- **Constrained by:** Existing call sites; test must not require API changes
+
+### File System (test isolation)
+
+- **Provides:** Temporary directories for config file read/write tests
+- **Pattern:** `fs.mkdtempSync` setup / `fs.rmSync` teardown per describe block
+
+---
+
+## 4. Behaviour Overview
+
+### Happy Path: All Exported Functions Are Tested
+
+1. Test file imports `src/feedback.js` module
+2. Each exported function has one or more test cases covering:
+   - Correct inputs → expected outputs
+   - Boundary inputs → correct handling
+   - Invalid inputs → appropriate rejection or graceful degradation
+3. File system tests use isolated `tmp` directories to avoid cross-test pollution
+4. `process.chdir` is restored after each file-system test group
+5. All tests pass green; CI accepts the file
+
+### Alternative: Config File Corruption
+
+1. Test writes deliberately malformed JSON to the config file path
+2. `readConfig()` catches the parse error and returns defaults
+3. No exception propagates; test asserts returned value equals `getDefaultConfig()`
+
+### Alternative: Boundary Rating Validation
+
+1. Tests cover ratings 1, 5 (valid boundaries) and 0, 6 (invalid outside range)
+2. Tests cover `rating: 3.5` (non-integer, invalid) and `rating: 3` (integer, valid)
+3. `validateFeedback` returns `{ valid: false, errors: [...] }` for all invalid cases
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- **State-creating:** None — the test file does not introduce new runtime state
+- **State-constrained:** Tests manage transient file system state (tmp directories)
+- **Module lifecycle:** `require('../src/feedback')` is resolved once per test file run; config file paths are relative and resolved against `process.cwd()` which tests temporarily redirect
+
+**Key constraint:** `src/feedback.js` uses a module-level constant `CONFIG_FILE = '.claude/feedback-config.json'` resolved relative to `process.cwd()`. Tests must `process.chdir(testDir)` before any call that reads/writes config, and restore `process.cwd()` in teardown.
+
+---
+
+## 6. Rules & Decision Logic
+
+### Rule 1: Direct Module Import Required
+
+- **Description:** Tests must import the real `src/feedback.js` rather than re-implementing its logic
+- **Rationale:** Inline reimplementation does not catch bugs in production code
+- **Inputs:** `require('../src/feedback')`
+- **Outputs:** Live module reference
+- **Type:** Structural constraint
+
+### Rule 2: Isolated File System Per Describe Block
+
+- **Description:** Each describe block that touches the config file must set up and tear down its own `tmp` directory
+- **Inputs:** `fs.mkdtempSync`, `process.chdir`
+- **Outputs:** Isolated state per describe block
+- **Type:** Deterministic
+
+### Rule 3: Boundary Coverage for Rating
+
+- **Description:** Rating validation must be tested at values 0, 1, 3, 5, 6 and non-integer 3.5
+- **Type:** Deterministic
+
+### Rule 4: Dual-Key Normalisation Coverage
+
+- **Description:** `normalizeFeedbackKeys` must be tested for: `rec` only, `recommendation` only, both present (recommendation wins), neither present
+- **Type:** Deterministic
+
+### Rule 5: Parse-and-Validate Pipeline
+
+- **Description:** At least one test must chain `parseFeedbackFromOutput` → `normalizeFeedbackKeys` → `validateFeedback` to verify the end-to-end extraction path works against the real module
+- **Type:** Integration within module boundary
+
+---
+
+## 7. Dependencies
+
+### System Components
+
+- **src/feedback.js:** Module under test — no modifications required
+- **node:test, node:assert:** Node.js built-in test runner and assertions (Node 18+)
+- **fs, path, os:** Standard library for file system isolation
+
+### File Dependencies
+
+- Input: `src/feedback.js` (read-only from test perspective)
+- Output: `test/feature_feedback-test.test.js` (new file)
+
+### Existing Test Patterns
+
+- Isolation pattern from `test/feature_feedback-loop.test.js` (setupTestDir / teardownTestDir)
+- Module import pattern from `test/feature_theme-adoption.test.js` and `test/feature_config-factory.test.js`
+
+---
+
+## 8. Non-Functional Considerations
+
+### Performance
+
+- All tests are synchronous file system operations on tmp dirs; expected runtime < 100ms total
+
+### Maintainability
+
+- Tests are structured to mirror `src/feedback.js` exported API, making it easy to add tests as the module evolves
+- Describe block names match function groups: `validateFeedback`, `normalizeFeedbackKeys`, `parseFeedbackFromOutput`, `shouldPause`, `Config Management`
+
+### Error Tolerance
+
+- Tmp directory teardown uses `{ force: true }` to tolerate partial cleanup on test failure
+
+### No Side Effects
+
+- Tests do not modify any project-level `.claude/` files; all file I/O is confined to `tmp` directories
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+
+- ASSUMPTION: `src/feedback.js` exports are stable; no API changes are required to make it testable
+- ASSUMPTION: `process.chdir` correctly redirects the module's relative path resolution for `CONFIG_FILE`
+- ASSUMPTION: Node.js 18+ is available (required by SYSTEM_SPEC.md:Section 2)
+- ASSUMPTION: `displayConfig` writes to stdout; smoke test asserts it does not throw
+
+### Open Questions
+
+- Should `displayConfig` be tested with a captured stdout mock, or is a non-throw assertion sufficient? (INFERRED: non-throw is sufficient for this feature)
+- Should `setConfigValue` with unknown keys be tested? (INFERRED: yes, as the function throws a typed error that should be verified)
+- Are there any async code paths in `src/feedback.js`? (INFERRED: no — all operations are synchronous based on current implementation)
+
+---
+
+## 10. Impact on System Specification
+
+### Reinforces Existing Assumptions
+
+- Per SYSTEM_SPEC.md:Section 7, "tests are contracts" and "green suite required" — this feature closes a gap where contracts were implied but not enforced
+- Per SYSTEM_SPEC.md:Section 8 (Traceability), tests that directly import production modules create a firmer traceability chain than tests using reimplemented helpers
+
+### No Contradiction
+
+This feature introduces no new behaviour, state, or API. It adds test coverage for existing production code. No system spec update is required.
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story Themes
+
+1. **Direct Module Tests:** Tests that import and exercise `validateFeedback`, `normalizeFeedbackKeys`, `parseFeedbackFromOutput`, and `shouldPause` via the real module
+2. **Config Management Tests:** Tests for `readConfig`, `writeConfig`, `setConfigValue`, `resetConfig`, and `getDefaultConfig` with file system isolation
+3. **End-to-End Parse Pipeline:** A chained test covering `parseFeedbackFromOutput` → `normalizeFeedbackKeys` → `validateFeedback` as an integrated path
+
+### Expected Story Boundaries
+
+- Story 1: Validation and normalisation functions (no file system needed)
+- Story 2: Config management functions (file system isolation required)
+- Story 3: Parse pipeline (combines Stories 1 and 2 patterns)
+
+### Areas Needing Careful Story Framing
+
+- `process.chdir` usage must be clearly framed as test infrastructure, not production behaviour
+- The distinction between this test file and `feature_feedback-loop.test.js` must be explicit: this tests the real module; that uses inline helpers
+- `displayConfig` story should be framed as a smoke test, not a full output assertion
+
+---
+
+## 12. Change Log (Feature-Level)
+
+| Date       | Change                              | Reason                                  | Raised By |
+|------------|-------------------------------------|-----------------------------------------|-----------|
+| 2026-05-19 | Initial feature specification       | Close test coverage gap for src/feedback.js | Alex  |

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

@@ -0,0 +1,25 @@
+# Implementation Plan — feedback-test
+
+## Summary
+
+This feature adds a test suite for `src/feedback.js`. All 34 tests were written and verified green by Nigel prior to this planning phase — `src/feedback.js` already exports every required function and no production code changes are needed. Implementation is test-only: the test file and its artifact already exist and pass.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `test/feature_feedback-test.test.js` | Already created (Nigel) | 34 tests covering all exported feedback functions |
+| `test/artifacts/feature_feedback-test/test-spec.md` | Already created (Nigel) | AC-to-test-ID mapping and assumptions |
+| `src/feedback.js` | No change required | All required exports already present and correct |
+
+## Implementation Steps
+
+1. **Verify tests pass as-is** — Run `node --test test/feature_feedback-test.test.js` to confirm all 34 tests are green. Addresses all test IDs (T-VN-*, T-CM-*, T-PP-*).
+
+2. **No production code changes needed** — `src/feedback.js` already exports `validateFeedback`, `normalizeFeedbackKeys`, `parseFeedbackFromOutput`, `shouldPause`, `getDefaultConfig`, `readConfig`, `writeConfig`, `setConfigValue`, `displayConfig`, and `resetConfig` with correct behaviour.
+
+3. **Commit the new test artefacts** — Stage and commit `test/feature_feedback-test.test.js` and `test/artifacts/feature_feedback-test/test-spec.md` along with this plan.
+
+## Risks / Questions
+
+- None. Nigel confirmed all 34 tests pass against the unmodified production file before handoff.

package/.blueprint/features/feature_feedback-test/handoff-alex.md

@@ -0,0 +1,20 @@
+## Handoff Summary
+**For:** Cass
+**Feature:** feedback-test
+
+### Key Decisions
+- Scope is unit tests for `src/feedback.js` exclusively — the production module is imported directly, not reimplemented inline
+- All nine exported functions are covered: `validateFeedback`, `normalizeFeedbackKeys`, `parseFeedbackFromOutput`, `shouldPause`, `getDefaultConfig`, `readConfig`, `writeConfig`, `setConfigValue`, `resetConfig`
+- File system tests use `tmp` directory isolation with `process.chdir` (matching `feature_feedback-loop.test.js` pattern)
+- `displayConfig` is smoke-tested only (non-throw assertion); full stdout capture is out of scope
+- One chained integration test covers the full parse pipeline: `parseFeedbackFromOutput` → `normalizeFeedbackKeys` → `validateFeedback`
+
+### Files Created
+- .blueprint/features/feature_feedback-test/FEATURE_SPEC.md
+
+### Open Questions
+- Whether `displayConfig` warrants stdout capture mocking (deferred; non-throw is sufficient for now)
+- Async paths in `src/feedback.js`: inferred none exist, but Cass should confirm before writing stories
+
+### Critical Context
+The key distinction from existing feedback tests: `feature_feedback-loop.test.js` and `feature_compressed-feedback.test.js` both re-implement feedback logic as inline helpers — they do not import `src/feedback.js`. This feature exists precisely to test the real production module. Stories must keep this boundary clear. The output file is `test/feature_feedback-test.test.js` and must use `require('../src/feedback')`.

package/.blueprint/features/feature_feedback-test/handoff-cass.md

@@ -0,0 +1,21 @@
+## Handoff Summary
+**For:** Nigel
+**Feature:** feedback-test
+
+### Key Decisions
+- Split into three stories matching Alex's expected boundaries: validation/normalisation (pure), config management (file I/O), and parse pipeline (chained integration)
+- `normalizeFeedbackKeys` with both `rec` and `recommendation` present: production code does NOT delete `rec` when `recommendation` already exists — both keys are preserved; ACs reflect actual implementation
+- File system isolation pattern documented explicitly per `feature_feedback-loop.test.js`; `process.chdir` restore is mandatory in teardown
+- `displayConfig` framed as smoke test (no-throw only); no stdout capture required
+- All functions confirmed synchronous — no async/await needed in tests
+
+### Files Created
+- .blueprint/features/feature_feedback-test/story-validation-normalisation.md
+- .blueprint/features/feature_feedback-test/story-config-management.md
+- .blueprint/features/feature_feedback-test/story-parse-pipeline.md
+
+### Open Questions
+- None
+
+### Critical Context
+Output file is `test/feature_feedback-test.test.js` using `require('../src/feedback')` — not inline reimplementations. `CONFIG_FILE` is resolved relative to `process.cwd()`; all config tests must `chdir` into a `tmp` dir before calling any read/write function. Story-parse-pipeline covers Rule 5 (chained integration test) from FEATURE_SPEC.md. Rating boundary values to test: 0, 1, 3, 5, 6, 3.5.

package/.blueprint/features/feature_feedback-test/handoff-nigel.md

@@ -0,0 +1,20 @@
+## Handoff Summary
+**For:** Codey
+**Feature:** feedback-test
+
+### Key Decisions
+- Tests import `require('../src/feedback')` directly — no inline reimplementation anywhere
+- Config tests use `before`/`after` (not `beforeEach`/`afterEach`) since all config tests share one tmp dir with sequential state
+- `normalizeFeedbackKeys` dual-key test asserts both keys are preserved (production does NOT delete `rec` when `recommendation` already exists)
+- `displayConfig` covered as smoke test only (no stdout capture)
+- All 34 tests are synchronous; no async/await used
+
+### Files Created
+- test/artifacts/feature_feedback-test/test-spec.md
+- test/feature_feedback-test.test.js
+
+### Open Questions
+- None
+
+### Critical Context
+All 34 tests pass green (`node --test test/feature_feedback-test.test.js`). No changes to `src/feedback.js` are required — the existing exports satisfy all ACs. The Config Management describe block uses a single shared tmp dir (`before`/`after`), so tests within it run sequentially and depend on one another for state (e.g. T-CM-4.1 leaves a modified config file that T-CM-5.1 then resets). Codey need not modify production code; this feature is test-only.

package/.blueprint/features/feature_feedback-test/story-config-management.md

@@ -0,0 +1,103 @@
+# Story: Config Management Functions
+
+## User Story
+
+As a developer maintaining `src/feedback.js`,
+I want direct unit tests for `getDefaultConfig`, `readConfig`, `writeConfig`, `setConfigValue`, `resetConfig`, and `displayConfig`,
+so that config persistence logic in the production module is verified against real file I/O in an isolated environment.
+
+---
+
+## Acceptance Criteria
+
+**Given** `getDefaultConfig()` is called,
+**When** the function returns,
+**Then** the result has `minRatingThreshold: 3.0`, `enabled: true`, and an `issueMappings` object containing all six standard mappings defined in `src/feedback.js`.
+
+**Given** a `tmp` directory is set as `process.cwd()` and no config file exists there,
+**When** `readConfig()` is called,
+**Then** it returns a value equal to `getDefaultConfig()` and does not throw.
+
+**Given** a `tmp` directory is set as `process.cwd()` and `.claude/feedback-config.json` contains valid JSON,
+**When** `readConfig()` is called,
+**Then** it returns the parsed config object matching the written content.
+
+**Given** a `tmp` directory is set as `process.cwd()` and `.claude/feedback-config.json` contains malformed JSON (e.g. `{bad json`),
+**When** `readConfig()` is called,
+**Then** it returns `getDefaultConfig()` and does not throw.
+
+**Given** a `tmp` directory is set as `process.cwd()`,
+**When** `writeConfig(config)` is called with a valid config object,
+**Then** `.claude/feedback-config.json` is created at the expected path and its content parses back to the original config object.
+
+**Given** a `tmp` directory is set as `process.cwd()` and a config file exists,
+**When** `setConfigValue('minRatingThreshold', '4.5')` is called,
+**Then** `readConfig()` returns a config with `minRatingThreshold: 4.5`.
+
+**Given** a `tmp` directory is set as `process.cwd()`,
+**When** `setConfigValue('enabled', 'false')` is called,
+**Then** `readConfig()` returns a config with `enabled: false`.
+
+**Given** a `tmp` directory is set as `process.cwd()`,
+**When** `setConfigValue` is called with an unknown key (e.g. `'nonExistentKey'`),
+**Then** it throws an `Error` whose message contains `'Unknown config key'`.
+
+**Given** a `tmp` directory is set as `process.cwd()` and a modified config file exists,
+**When** `resetConfig()` is called,
+**Then** `readConfig()` returns a value equal to `getDefaultConfig()`.
+
+**Given** a `tmp` directory is set as `process.cwd()`,
+**When** `displayConfig()` is called,
+**Then** it does not throw (smoke test only — output format is not asserted).
+
+---
+
+## File System Isolation Pattern
+
+Each describe block that exercises config file I/O must follow this pattern:
+
+```
+before(): testDir = fs.mkdtempSync(os.tmpdir() + path.sep + 'feedback-test-')
+          originalCwd = process.cwd()
+          process.chdir(testDir)
+
+after():  process.chdir(originalCwd)
+          fs.rmSync(testDir, { recursive: true, force: true })
+```
+
+This mirrors the isolation pattern in `test/feature_feedback-loop.test.js`.
+
+The `CONFIG_FILE` constant in `src/feedback.js` is `.claude/feedback-config.json`, resolved relative to `process.cwd()`. Tests must `chdir` before calling any function that reads or writes config.
+
+---
+
+## `setConfigValue` Invalid Input Cases
+
+| key                   | value     | Expected behaviour                              |
+|-----------------------|-----------|-------------------------------------------------|
+| `minRatingThreshold`  | `'0.5'`   | throws — below minimum (1.0)                    |
+| `minRatingThreshold`  | `'5.5'`   | throws — above maximum (5.0)                    |
+| `minRatingThreshold`  | `'abc'`   | throws — not a number                           |
+| `enabled`             | `'yes'`   | throws — not `'true'` or `'false'`              |
+| `nonExistentKey`      | `'val'`   | throws — unknown key                            |
+
+---
+
+## Out of Scope
+
+- Testing `displayConfig` output format or colour rendering
+- Testing stdout mock/capture for `displayConfig`
+- Testing `validateFeedback`, `normalizeFeedbackKeys`, `parseFeedbackFromOutput`, `shouldPause` (covered in story-validation-normalisation.md)
+- End-to-end pipeline chain (covered in story-parse-pipeline.md)
+- Any modification of `src/feedback.js` production code
+- Modifying project-level `.claude/` files
+
+---
+
+## Implementation Notes
+
+- Import: `const { getDefaultConfig, readConfig, writeConfig, setConfigValue, resetConfig, displayConfig } = require('../src/feedback')`
+- Also import: `fs`, `os`, `path` for file system isolation
+- Group under a single `describe('Config Management', ...)` or per-function sub-describes
+- `displayConfig` reads config via `readConfig()`, so it also requires `chdir` setup
+- See: `.blueprint/features/feature_feedback-test/FEATURE_SPEC.md` for full rules and constraints

package/.blueprint/features/feature_feedback-test/story-parse-pipeline.md

@@ -0,0 +1,65 @@
+# Story: End-to-End Parse Pipeline
+
+## User Story
+
+As a developer maintaining `src/feedback.js`,
+I want an integrated test that chains `parseFeedbackFromOutput` → `normalizeFeedbackKeys` → `validateFeedback` using the real production module,
+so that the complete feedback extraction and validation path is verified end-to-end within the module boundary.
+
+---
+
+## Acceptance Criteria
+
+**Given** an agent output string containing a valid `FEEDBACK: { "rating": 4, "issues": [], "rec": "proceed" }` block,
+**When** the output is passed to `parseFeedbackFromOutput`, the result to `normalizeFeedbackKeys`, and that result to `validateFeedback`,
+**Then** `parseFeedbackFromOutput` returns a non-null object, `normalizeFeedbackKeys` returns an object with `recommendation: 'proceed'` (not `rec`), and `validateFeedback` returns `{ valid: true, errors: [] }`.
+
+**Given** an agent output string containing `FEEDBACK: { "rating": 2, "issues": ["unclear-scope"], "rec": "pause" }`,
+**When** the same three-step chain is applied,
+**Then** `validateFeedback` returns `{ valid: true, errors: [] }` (both `rec`-normalised recommendation and rating are valid), and the normalised object has `recommendation: 'pause'`.
+
+**Given** an agent output string with `FEEDBACK: { "rating": 0, "issues": [], "recommendation": "proceed" }`,
+**When** the three-step chain is applied,
+**Then** `validateFeedback` returns `{ valid: false, errors: [...] }` with an error referencing the invalid rating.
+
+**Given** an agent output string with no `FEEDBACK:` marker,
+**When** `parseFeedbackFromOutput` is called,
+**Then** it returns `null` and the pipeline terminates at that stage (normalisation and validation are not called with null).
+
+---
+
+## Pipeline Sequence (Explicit)
+
+```
+input: raw output string
+  └─► parseFeedbackFromOutput(output)
+        → null           → pipeline terminates (no further steps)
+        → parsed object  → continue
+            └─► normalizeFeedbackKeys(parsed)
+                  → normalised object
+                      └─► validateFeedback(normalised)
+                            → { valid, errors }
+```
+
+All three functions are called on the real `src/feedback.js` module export. No step reimplements logic inline.
+
+---
+
+## Out of Scope
+
+- File system I/O (not required for this pipeline — all functions are in-memory)
+- `shouldPause` integration (not part of the parse pipeline; covered in story-validation-normalisation.md)
+- Config management functions (covered in story-config-management.md)
+- Any modification of `src/feedback.js` production code
+- Exhaustive permutations of each step (those are covered in story-validation-normalisation.md)
+
+---
+
+## Implementation Notes
+
+- Import: `const { parseFeedbackFromOutput, normalizeFeedbackKeys, validateFeedback } = require('../src/feedback')`
+- Group under `describe('Parse Pipeline', ...)` or similar
+- No file system setup required — all three functions operate on in-memory values
+- This story's tests serve as the single chained integration test called for in FEATURE_SPEC.md:Rule 5
+- The `rec` → `recommendation` normalisation step is critical: the raw parsed object uses `rec`, and `validateFeedback` accepts both keys — but the test should verify normalisation works correctly in the chain
+- See: `.blueprint/features/feature_feedback-test/FEATURE_SPEC.md` for Rule 5 context

package/.blueprint/features/feature_feedback-test/story-validation-normalisation.md

@@ -0,0 +1,99 @@
+# Story: Validation and Normalisation Functions
+
+## User Story
+
+As a developer maintaining `src/feedback.js`,
+I want direct unit tests for `validateFeedback`, `normalizeFeedbackKeys`, `parseFeedbackFromOutput`, and `shouldPause`,
+so that regressions in the production module are caught immediately by the test suite without relying on inline reimplementations.
+
+---
+
+## Acceptance Criteria
+
+**Given** a feedback object with a valid integer rating (1–5), an array of strings as issues, and a valid recommendation (`proceed`, `pause`, or `revise`),
+**When** `validateFeedback(feedback)` is called,
+**Then** it returns `{ valid: true, errors: [] }`.
+
+**Given** a feedback object with a rating of `0` (below range), `6` (above range), `3.5` (non-integer), or a value that is not a number,
+**When** `validateFeedback(feedback)` is called,
+**Then** it returns `{ valid: false, errors: [...] }` containing an appropriate error message for each invalid rating.
+
+**Given** a feedback object where `issues` is not an array, or contains non-string elements,
+**When** `validateFeedback(feedback)` is called,
+**Then** it returns `{ valid: false, errors: [...] }` containing an error message describing the issues field violation.
+
+**Given** a feedback object with `rec` key only (no `recommendation` key),
+**When** `normalizeFeedbackKeys(feedback)` is called,
+**Then** it returns an object with `recommendation` set to the `rec` value and no `rec` key present.
+
+**Given** a feedback object with both `rec` and `recommendation` keys,
+**When** `normalizeFeedbackKeys(feedback)` is called,
+**Then** `recommendation` retains its original value (wins over `rec`) and `rec` is not deleted (both remain as-is per the production implementation).
+
+**Given** an agent output string containing a `FEEDBACK: { ... }` JSON block with valid content,
+**When** `parseFeedbackFromOutput(output)` is called,
+**Then** it returns the parsed feedback object.
+
+**Given** a feedback object with `recommendation: 'pause'` and a rating above `minRatingThreshold`,
+**When** `shouldPause(feedback, config)` is called,
+**Then** it returns `true`.
+
+**Given** a feedback object with `recommendation: 'proceed'` and a rating below `minRatingThreshold`,
+**When** `shouldPause(feedback, config)` is called,
+**Then** it returns `true` (rating-based gate triggers independently of recommendation).
+
+---
+
+## Test Boundary Details
+
+### `validateFeedback` — rating boundary values to test
+| Value | Expected valid |
+|-------|---------------|
+| 0     | false         |
+| 1     | true          |
+| 3     | true          |
+| 5     | true          |
+| 6     | false         |
+| 3.5   | false         |
+
+### `normalizeFeedbackKeys` — key scenarios to test
+| Scenario                              | Expected result                          |
+|---------------------------------------|------------------------------------------|
+| `rec` only                            | Renamed to `recommendation`; `rec` removed |
+| `recommendation` only                 | Unchanged                                |
+| Both `rec` and `recommendation`       | Both keys preserved; `recommendation` value unchanged |
+| Neither `rec` nor `recommendation`    | Object returned unchanged                |
+
+### `parseFeedbackFromOutput` — scenarios to test
+| Input                                 | Expected result   |
+|---------------------------------------|-------------------|
+| Valid `FEEDBACK: { ... }` block       | Parsed object     |
+| No `FEEDBACK:` marker                 | `null`            |
+| Malformed JSON after `FEEDBACK:`      | `null`            |
+
+### `shouldPause` — scenarios to test
+| rating | minRatingThreshold | recommendation | Expected |
+|--------|--------------------|----------------|----------|
+| 4      | 3.0                | 'proceed'      | false    |
+| 2      | 3.0                | 'proceed'      | true     |
+| 4      | 3.0                | 'pause'        | true     |
+| 2      | 3.0                | 'pause'        | true     |
+
+---
+
+## Out of Scope
+
+- Config file system interaction (covered in story-config-management.md)
+- End-to-end parse pipeline chain (covered in story-parse-pipeline.md)
+- `displayConfig` output assertion (smoke-tested in story-config-management.md)
+- Any modification of `src/feedback.js` production code
+- Testing agent prompt text or insights correlation logic
+
+---
+
+## Implementation Notes
+
+- Import: `const { validateFeedback, normalizeFeedbackKeys, parseFeedbackFromOutput, shouldPause } = require('../src/feedback')`
+- No file system setup required for this story — all functions are pure or in-memory
+- Describe block names should match function names: `validateFeedback`, `normalizeFeedbackKeys`, `parseFeedbackFromOutput`, `shouldPause`
+- See: `.blueprint/features/feature_feedback-test/FEATURE_SPEC.md` for full rules