source_monitor 0.7.0 → 0.8.0

data/.vbw-planning/milestones/default/phases/01-coverage-analysis-quick-wins/PLAN-02-SUMMARY.md

@@ -1,64 +0,0 @@
-# Plan 02 Summary: rubocop-audit-and-fix
-
-## Status: complete
-
-## Result
-
-The codebase already passes RuboCop with zero offenses against the `rubocop-rails-omakase` ruleset. No code changes were required.
-
-## Tasks Completed
-
-| Task | Name | Result |
-|------|------|--------|
-| 1 | rubocop-audit-categorize-violations | 341 files inspected, 0 offenses |
-| 2 | apply-safe-rubocop-autocorrect | No-op (no violations to fix) |
-| 3 | fix-remaining-rubocop-violations | No-op (no violations to fix) |
-| 4 | configure-rubocop-exclusions-for-phase3 | No-op (Metrics cops disabled in omakase) |
-| 5 | validate-rubocop-zero-offenses | All checks pass |
-
-## Violation Counts
-
-- **Before:** 0 offenses (341 files inspected)
-- **After:** 0 offenses (341 files inspected)
-
-## Commit
-
-No commit created -- no code changes were needed.
-
-## Verification Results
-
-| Check | Result |
-|-------|--------|
-| `bin/rubocop -f simple` | 341 files inspected, no offenses detected |
-| `bin/rubocop -f github` | Exit 0 |
-| `bin/rails test` | 473 runs, 1927 assertions, 0 failures, 0 errors, 0 skips |
-| Coverage baseline (`config/coverage_baseline.json`) | 2328 lines (unchanged) |
-
-## Key Findings
-
-1. **Omakase config is minimal by design.** The `rubocop-rails-omakase` gem enables only 45 cops (out of 775 available). It focuses on essential layout and style rules, not metrics or complex analysis.
-
-2. **Metrics cops are all disabled.** `Metrics/ClassLength`, `Metrics/MethodLength`, `Metrics/BlockLength`, and all other Metrics cops are set to `Enabled: false` in the omakase config. This means the large files (FeedFetcher 627 lines, Configuration 655 lines, ImportSessionsController 792 lines) do not trigger any violations. No `.rubocop.yml` exclusions were needed.
-
-3. **Plan 01 was the key enabler.** The frozen_string_literal pragma work (Plan 01, commit 5f02db8, 113 files) was likely the primary source of violations. After that was completed, the remaining code was already compliant with the 45 enabled cops.
-
-4. **Enabled cop categories:**
-   - Layout (27 cops): indentation, spacing, whitespace
-   - Style (12 cops): string literals, hash syntax, parentheses, semicolons
-   - Lint (4 cops): string coercion, require parentheses, syntax, URI escape
-   - Performance (1 cop): flat_map
-   - Migration (1 cop): department name
-
-## Deviations
-
-| ID | Description | Impact |
-|----|-------------|--------|
-| DEVN-01 | Tasks 2-4 were no-ops because no violations existed | None -- plan designed for worst case, actual state was already compliant |
-| DEVN-01 | No git commit created (no code changes) | None -- the success criteria (zero offenses, tests pass) are satisfied without changes |
-| DEVN-01 | No `.rubocop.yml` exclusions added for Phase 3 files | None -- Metrics cops are disabled in omakase, so exclusions would be meaningless |
-
-## REQ-14 Status
-
-**REQ-14 (Audit and fix any RuboCop violations against omakase ruleset): SATISFIED**
-
-The audit confirms zero violations exist. The CI lint job (`bin/rubocop -f github`) exits 0.

data/.vbw-planning/milestones/default/phases/01-coverage-analysis-quick-wins/PLAN-02.md

@@ -1,137 +0,0 @@
----
-phase: 1
-plan: 2
-title: rubocop-audit-and-fix
-wave: 2
-depends_on: [1]
-skills_used: []
-must_haves:
-  truths:
-    - "`bin/rubocop` exits 0 with zero offenses (verified by `bin/rubocop -f simple` output showing `no offenses detected`)"
-    - "All existing tests pass (`bin/rails test` exits 0 with no new failures)"
-    - "CI lint job would pass (`bin/rubocop -f github` exits 0)"
-  artifacts:
-    - "All Ruby files in app/, lib/, test/, config/, db/ comply with rubocop-rails-omakase rules"
-    - "`.rubocop.yml` may have additional targeted exclusions if auto-generated files legitimately violate rules"
-  key_links:
-    - "REQ-14 fully satisfied by this plan"
-    - "Depends on Plan 01 (frozen_string_literal already resolved -- largest category of violations removed)"
----
-
-# Plan 02: rubocop-audit-and-fix
-
-## Objective
-
-Audit the entire codebase with RuboCop using the `rubocop-rails-omakase` configuration and fix all violations, achieving zero offenses. This satisfies REQ-14 and ensures the CI lint job passes cleanly.
-
-## Context
-
-<context>
-@.vbw-planning/REQUIREMENTS.md -- REQ-14: RuboCop audit against omakase ruleset
-@.vbw-planning/codebase/CONVENTIONS.md -- Rails omakase style guide, existing patterns
-@.rubocop.yml -- inherits from rubocop-rails-omakase, excludes test/dummy/db/schema.rb
-@Gemfile -- rubocop-rails-omakase gem included
-@bin/rubocop -- wrapper script that forces config path
-@.github/workflows/ci.yml -- lint job runs `bin/rubocop -f github`
-
-**Decomposition rationale:** This plan depends on Plan 01 because `Style/FrozenStringLiteralComment` is typically the most voluminous cop violation. By completing Plan 01 first, this plan deals with a much smaller and more varied set of violations that require more careful, contextual fixes.
-
-**Current state:**
-- The project uses `rubocop-rails-omakase` as its base ruleset (inherits the gem's rubocop.yml)
-- Only one exclusion exists: `test/dummy/db/schema.rb`
-- After Plan 01 completes, `Style/FrozenStringLiteralComment` violations will be resolved
-- Remaining violations are unknown until the audit is run, but likely categories include:
-  - `Style/StringLiterals` (single vs double quotes)
-  - `Layout/*` (indentation, spacing, line length)
-  - `Metrics/*` (method/class length -- may need exclusions for large files targeted in Phase 3)
-  - `Naming/*` (variable/method naming conventions)
-  - `Rails/*` cops from the omakase set
-- Large files (FeedFetcher 627 lines, Configuration 655 lines, ImportSessionsController 792 lines) may trigger `Metrics/ClassLength` or `Metrics/MethodLength` -- these should be addressed with targeted `.rubocop.yml` exclusions since Phase 3 handles the actual refactoring
-
-**Constraints:**
-- Fix violations using RuboCop auto-correct where safe (`rubocop -a` for safe corrections, `-A` for aggressive only when reviewed)
-- Do NOT refactor large files to satisfy Metrics cops -- instead exclude them in `.rubocop.yml` with a comment referencing Phase 3
-- Preserve all existing behavior -- style-only changes
-- The `test/dummy/db/schema.rb` exclusion must remain (Rails-generated)
-- Test files in `test/tmp/` are not git-tracked and not subject to RuboCop
-</context>
-
-## Tasks
-
-### Task 1: Run RuboCop audit and categorize violations
-
-- **name:** rubocop-audit-categorize-violations
-- **files:** (no files modified -- analysis only)
-- **action:** Run `bin/rubocop -f json -o tmp/rubocop_report.json` and `bin/rubocop -f simple` to get a complete picture of all violations. Categorize them by: (a) auto-correctable with `-a` (safe), (b) auto-correctable with `-A` (unsafe, needs review), (c) manual fix required, (d) should be excluded (Metrics cops on large files destined for Phase 3 refactoring). Document the count and category of each cop violation type.
-- **verify:** The audit report exists and lists all violations. Categorization is complete.
-- **done:** Full understanding of the violation landscape. Clear plan for which files need which type of fix.
-
-### Task 2: Apply safe auto-corrections
-
-- **name:** apply-safe-rubocop-autocorrect
-- **files:** All Ruby files flagged by RuboCop safe auto-correct
-- **action:** Run `bin/rubocop -a` to apply all safe auto-corrections across the codebase. This handles cops like `Style/StringLiterals`, `Layout/TrailingWhitespace`, `Layout/EmptyLineAfterMagicComment`, `Layout/SpaceInsideBlockBraces`, etc. Review the diff to confirm no behavioral changes -- only formatting/style changes. If any auto-correction looks wrong, revert that specific change and handle it manually in Task 3.
-- **verify:** Run `git diff --stat` to see scope of changes. Run `bin/rails test` to confirm no test regressions. Run `bin/rubocop -f simple` to see remaining violations after safe auto-correct.
-- **done:** All safe auto-correctable violations are fixed. Test suite still passes.
-
-### Task 3: Fix remaining violations manually
-
-- **name:** fix-remaining-rubocop-violations
-- **files:** Files with violations that were not auto-correctable or were unsafe auto-corrections
-- **action:** For each remaining violation:
-  - **Style cops**: Fix manually following the omakase conventions (single quotes for simple strings, double quotes when interpolation needed, etc.)
-  - **Layout cops**: Fix indentation, spacing, alignment manually
-  - **Naming cops**: Rename variables/methods to comply (ensure test references are updated)
-  - **Rails cops**: Fix any Rails-specific violations (e.g., `Rails/HttpPositionalArguments`)
-  - If a violation is in a file that is inherently non-compliant due to its nature (e.g., a migration with unusual structure), add a targeted inline `# rubocop:disable` comment with an explanation
-- **verify:** Run `bin/rubocop -f simple` after each batch of fixes. The violation count should decrease monotonically. Run `bin/rails test` after all manual fixes.
-- **done:** All non-Metrics violations are resolved either by code changes or justified inline disables.
-
-### Task 4: Configure exclusions for large files (Phase 3 targets)
-
-- **name:** configure-rubocop-exclusions-for-phase3
-- **files:**
-  - `.rubocop.yml`
-- **action:** If `Metrics/ClassLength`, `Metrics/MethodLength`, or `Metrics/BlockLength` violations remain for the three large files targeted for refactoring in Phase 3, add targeted exclusions to `.rubocop.yml`:
-  ```yaml
-  # Phase 3 refactoring targets -- remove exclusions after extraction
-  Metrics/ClassLength:
-    Exclude:
-      - "lib/source_monitor/fetching/feed_fetcher.rb"
-      - "lib/source_monitor/configuration.rb"
-      - "app/controllers/source_monitor/import_sessions_controller.rb"
-  ```
-  Add a comment explaining these are temporary exclusions that will be removed in Phase 3. Do NOT exclude any other files -- only the three identified large files.
-- **verify:** Run `bin/rubocop` and confirm it exits 0 with zero offenses. The exclusions should only cover the Phase 3 target files.
-- **done:** `.rubocop.yml` has targeted, documented exclusions. Zero RuboCop offenses across the entire codebase.
-
-### Task 5: Final validation and CI readiness check
-
-- **name:** validate-rubocop-zero-offenses
-- **files:** (no files modified -- validation only)
-- **action:** Run the full validation suite: (1) `bin/rubocop -f simple` -- must show `no offenses detected`. (2) `bin/rubocop -f github` -- must exit 0 (this is what CI runs). (3) `bin/rails test` -- full test suite must pass. (4) Verify the coverage baseline has not grown (run `wc -l config/coverage_baseline.json` and confirm it is still approximately 2328 lines -- style changes should not affect coverage).
-- **verify:**
-  - `bin/rubocop` exits 0
-  - `bin/rubocop -f github` exits 0
-  - `bin/rails test` exits 0
-  - Coverage baseline line count has not increased
-- **done:** Zero RuboCop violations. CI-ready. REQ-14 satisfied.
-
-## Verification
-
-1. `bin/rubocop -f simple` outputs `no offenses detected`
-2. `bin/rubocop -f github` exits 0 (CI lint format)
-3. `bin/rails test` exits 0 with no regressions
-4. Coverage baseline (`config/coverage_baseline.json`) has not grown in line count
-
-## Success Criteria
-
-- [x] Zero RuboCop violations against the omakase ruleset (REQ-14)
-- [x] Any `.rubocop.yml` exclusions are limited to Phase 3 target files with documenting comments
-- [x] CI lint job (`bin/rubocop -f github`) passes
-- [x] No test regressions
-- [x] No behavioral changes -- all fixes are style/formatting only
-
-## Phase 1 Coverage Note
-
-Phase 1 success criterion #3 ("Coverage baseline shrinks by at least 10%") is not directly addressed by Plans 01 or 02, which focus on code quality (REQ-13, REQ-14). The coverage baseline may shrink slightly if RuboCop fixes remove dead branches or simplify code paths. After Plan 02 completes, regenerate the baseline with `bin/update-coverage-baseline` and measure the delta. The 10% reduction target (from 2328 uncovered lines to ~2095 or fewer) will primarily be achieved in Phase 2 when dedicated test coverage plans execute.

data/.vbw-planning/milestones/default/phases/02-critical-path-test-coverage/PLAN-01-SUMMARY.md

@@ -1,67 +0,0 @@
-# PLAN-01 Summary: feed-fetcher-tests
-
-## Status: COMPLETE
-
-## Commit
-
-- **Hash:** `8d4e8d3`
-- **Message:** `test(feed-fetcher): close coverage gaps for retry, errors, headers, entries, helpers [dev-plan01]`
-- **Files changed:** 1 file, 734 insertions
-
-## Tasks Completed
-
-### Task 1: Test retry strategy and circuit breaker transitions
-- Added tests for reset_retry_state!, apply_retry_strategy!, circuit breaker open/close
-- Verified first timeout sets fetch_retry_attempt to 1
-- Verified exhausting retries opens circuit (sets fetch_circuit_opened_at, fetch_circuit_until)
-- Verified successful fetch resets retry state
-- Tested RetryPolicy error handling fallback
-
-### Task 2: Test Faraday error wrapping and connection failures
-- Tested Faraday::ConnectionFailed raises ConnectionError with original_error preserved
-- Tested Faraday::SSLError raises ConnectionError
-- Tested Faraday::ClientError with response hash builds HTTPError via build_http_error_from_faraday
-- Tested generic Faraday::Error raises FetchError
-- Tested non-Faraday StandardError wrapped in UnexpectedResponseError
-
-### Task 3: Test Last-Modified header handling and request headers
-- Tested If-Modified-Since header sent when source.last_modified is set
-- Tested Last-Modified response header parsed and stored on source
-- Tested malformed Last-Modified headers silently ignored
-- Tested custom_headers from source passed through to request
-- Tested ETag and Last-Modified preserved on 304 responses
-
-### Task 4: Test entry processing edge cases and error normalization
-- Tested feed without entries returns zero counts
-- Tested Events.run_item_processors called for each entry
-- Tested Events.after_item_created called only for created items
-- Tested normalize_item_error extracts guid via entry_id/id fallbacks
-- Tested safe_entry_title returns nil for entries without title
-
-### Task 5: Test jitter, interval helpers, and metadata management
-- Tested jitter_offset returns 0 when interval_seconds <= 0
-- Tested jitter_offset uses jitter_proc when provided
-- Tested body_digest returns nil for blank body, SHA256 for non-blank
-- Tested updated_metadata preserves existing metadata
-- Tested configured_seconds, extract_numeric edge cases
-
-## Deviations
-
-None -- plan executed as specified.
-
-## Verification Results
-
-| Check | Result |
-|-------|--------|
-| `bin/rails test test/lib/source_monitor/fetching/feed_fetcher_test.rb` | All tests pass |
-| `bin/rails test` | 760 runs, 2626 assertions, 0 failures, 0 errors, 0 skips |
-
-## Success Criteria
-
-- [x] 48 new tests added (734 lines)
-- [x] All retry/circuit breaker branches tested
-- [x] All Faraday error wrapping branches tested
-- [x] All header handling branches tested
-- [x] Entry processing and error normalization branches tested
-- [x] Jitter, interval helpers, and metadata management tested
-- [x] REQ-01 substantially satisfied

data/.vbw-planning/milestones/default/phases/02-critical-path-test-coverage/PLAN-01.md

@@ -1,142 +0,0 @@
----
-phase: 2
-plan: 1
-title: feed-fetcher-tests
-wave: 1
-depends_on: []
-skills_used: []
-must_haves:
-  truths:
-    - "Running `bin/rails test test/lib/source_monitor/fetching/feed_fetcher_test.rb` exits 0 with zero failures"
-    - "Coverage report shows lib/source_monitor/fetching/feed_fetcher.rb has fewer than 50 uncovered lines (down from 245)"
-    - "All new tests use WebMock stubs or VCR cassettes -- no real HTTP requests"
-    - "Running `bin/rails test` exits 0 with no regressions"
-  artifacts:
-    - "test/lib/source_monitor/fetching/feed_fetcher_test.rb -- extended with new test methods covering retry strategy, error handling, header management, entry processing, and helper methods"
-  key_links:
-    - "REQ-01 substantially satisfied -- FeedFetcher branch coverage above 80%"
----
-
-# Plan 01: feed-fetcher-tests
-
-## Objective
-
-Close the coverage gap in `lib/source_monitor/fetching/feed_fetcher.rb` (currently 245 uncovered lines out of 627). The existing test file covers basic RSS/Atom/JSON fetching, 304 handling, timeout/HTTP/parsing failures, and adaptive interval mechanics. This plan targets the remaining uncovered branches: retry strategy application, circuit breaker state transitions, connection error wrapping, last_modified header handling, entry processing edge cases, jitter computation, and private helper methods.
-
-## Context
-
-<context>
-@lib/source_monitor/fetching/feed_fetcher.rb -- 627 lines, the core fetch pipeline
-@lib/source_monitor/fetching/retry_policy.rb -- RetryPolicy with Decision struct
-@lib/source_monitor/fetching/fetch_error.rb -- error hierarchy (TimeoutError, ConnectionError, HTTPError, ParsingError, UnexpectedResponseError)
-@test/lib/source_monitor/fetching/feed_fetcher_test.rb -- existing test file with 12 tests covering success, 304, timeout, HTTP 404, parsing failure, adaptive intervals
-@config/coverage_baseline.json -- lists 245 uncovered lines for feed_fetcher.rb
-@test/test_helper.rb -- test infrastructure (WebMock, VCR, create_source!, with_queue_adapter)
-
-**Decomposition rationale:** FeedFetcher is the single largest coverage gap (245 lines). It is tested in isolation from ItemCreator (which has its own plan). The uncovered code falls into distinct categories that can each be addressed as a focused task: (1) retry/circuit breaker logic, (2) Faraday error wrapping and connection failures, (3) header and metadata management, (4) entry processing edge cases, (5) jitter and interval helpers. Each task adds test methods to the existing test file.
-
-**Trade-offs considered:**
-- Could split FeedFetcher tests across multiple test files (e.g., feed_fetcher_retry_test.rb), but keeping them in one file matches the existing codebase convention and avoids confusion.
-- Could use mocks for RetryPolicy, but testing the integration between FeedFetcher and RetryPolicy provides higher confidence.
-
-**What constrains the structure:**
-- Tests must use WebMock stubs (no real HTTP)
-- All tests go in the existing test file to avoid file proliferation
-- The `jitter: ->(_) { 0 }` pattern from existing tests should be reused to make interval assertions deterministic
-- Tests need `travel_to` for time-sensitive assertions
-</context>
-
-## Tasks
-
-### Task 1: Test retry strategy and circuit breaker transitions
-
-- **name:** test-retry-and-circuit-breaker
-- **files:**
-  - `test/lib/source_monitor/fetching/feed_fetcher_test.rb`
-- **action:** Add tests covering lines 262-298 (reset_retry_state!, apply_retry_strategy!) and lines 267-290 (retry/circuit decisions). Specifically:
-  1. Test that a first timeout failure sets fetch_retry_attempt to 1 (retry decision with wait)
-  2. Test that exhausting retry attempts opens the circuit (sets fetch_circuit_opened_at, fetch_circuit_until, next_fetch_at)
-  3. Test that a successful fetch after retries resets retry state (fetch_retry_attempt=0, circuit fields nil)
-  4. Test that apply_retry_strategy! handles StandardError by logging and setting defaults (lines 291-298) -- simulate by stubbing RetryPolicy to raise
-  5. Test that retry decision adjusts next_fetch_at to the minimum of current and retry time (line 283)
-  Use WebMock stubs: first stub raises Faraday::TimeoutError to trigger retries, then stub success for recovery tests. Set source.fetch_retry_attempt manually to simulate multiple failures.
-- **verify:** `bin/rails test test/lib/source_monitor/fetching/feed_fetcher_test.rb -n /retry|circuit/` exits 0
-- **done:** Lines 262-298 covered. Source retry fields verified in assertions.
-
-### Task 2: Test Faraday error wrapping and connection failures
-
-- **name:** test-faraday-error-wrapping
-- **files:**
-  - `test/lib/source_monitor/fetching/feed_fetcher_test.rb`
-- **action:** Add tests covering lines 77-86 (perform_fetch error wrapping) and lines 405-417 (build_http_error_from_faraday). Specifically:
-  1. Test that Faraday::ConnectionFailed raises SourceMonitor::Fetching::ConnectionError with original_error preserved
-  2. Test that Faraday::SSLError raises ConnectionError
-  3. Test that Faraday::ClientError with response hash builds HTTPError via build_http_error_from_faraday (lines 405-417) with correct status, message, and ResponseWrapper
-  4. Test that generic Faraday::Error raises FetchError
-  5. Test that a non-Faraday StandardError is wrapped in UnexpectedResponseError (lines 52-54)
-  Use WebMock's `to_raise` for each error type. Assert the result.error class, message, and original_error.
-- **verify:** `bin/rails test test/lib/source_monitor/fetching/feed_fetcher_test.rb -n /connection|ssl|client_error|unexpected|faraday/i` exits 0
-- **done:** Lines 77-86 and 405-417 covered. All Faraday error types correctly wrapped.
-
-### Task 3: Test Last-Modified header handling and request headers
-
-- **name:** test-last-modified-and-headers
-- **files:**
-  - `test/lib/source_monitor/fetching/feed_fetcher_test.rb`
-- **action:** Add tests covering lines 97-104 (request_headers with custom_headers, etag, last_modified), lines 203-215 and 228-240 (response Last-Modified parsing and storage), and lines 349-355 (parse_http_time). Specifically:
-  1. Test that If-Modified-Since header is sent when source.last_modified is set
-  2. Test that Last-Modified response header is parsed and stored on source
-  3. Test that malformed Last-Modified headers are silently ignored (parse_http_time returns nil for invalid dates, line 353)
-  4. Test that custom_headers from source are passed through to the request (lines 98)
-  5. Test that both ETag and Last-Modified are preserved on 304 not_modified responses (lines 228-234)
-  Use WebMock to verify request headers via `.with(headers: {...})` and return specific response headers.
-- **verify:** `bin/rails test test/lib/source_monitor/fetching/feed_fetcher_test.rb -n /last_modified|custom_header|if_modified/i` exits 0
-- **done:** Lines 97-104, 203-215, 228-240, 349-355 covered.
-
-### Task 4: Test entry processing edge cases and error normalization
-
-- **name:** test-entry-processing-edges
-- **files:**
-  - `test/lib/source_monitor/fetching/feed_fetcher_test.rb`
-- **action:** Add tests covering lines 520-567 (process_feed_entries) and lines 603-624 (normalize_item_error, safe_entry_guid, safe_entry_title). Specifically:
-  1. Test that a feed without entries (feed that doesn't respond_to :entries) returns zero counts (line 529)
-  2. Test that Events.run_item_processors is called for each entry (line 542)
-  3. Test that Events.after_item_created is called only for created items (line 547), not updated ones
-  4. Test that normalize_item_error extracts guid via entry_id (line 615-616), falls back to id (line 617-618), and handles entries without either
-  5. Test that safe_entry_title returns nil when entry doesn't respond_to :title (line 623)
-  Use a simple XML feed fixture with known entries. Mock ItemCreator to control created vs updated results. Use Notifications subscriptions to verify event dispatch.
-- **verify:** `bin/rails test test/lib/source_monitor/fetching/feed_fetcher_test.rb -n /entry_processing|item_processor|normalize_error|safe_entry/i` exits 0
-- **done:** Lines 520-567, 603-624 covered.
-
-### Task 5: Test jitter, interval helpers, and metadata management
-
-- **name:** test-jitter-and-interval-helpers
-- **files:**
-  - `test/lib/source_monitor/fetching/feed_fetcher_test.rb`
-- **action:** Add tests covering lines 490-518 (jitter_offset, adjusted_interval_with_jitter, body_digest, updated_metadata) and lines 569-600 (configured_seconds, configured_positive, configured_non_negative, extract_numeric, fetching_config). Specifically:
-  1. Test jitter_offset returns 0 when interval_seconds <= 0 (line 505)
-  2. Test jitter_offset uses jitter_proc when provided (line 506)
-  3. Test jitter_offset computes random jitter within expected range when no proc given
-  4. Test body_digest returns nil for blank body (line 515), returns SHA256 for non-blank
-  5. Test updated_metadata preserves existing metadata, removes dynamic_fetch_interval_seconds key, adds last_feed_signature
-  6. Test configured_seconds returns default when minutes_value is nil or non-positive (lines 570-571)
-  7. Test extract_numeric handles Numeric, responds_to :to_f, and non-numeric values (lines 590-596)
-  These are private methods -- test them through the public `call` method by configuring specific fetching settings and verifying the resulting source state. Alternatively, use `send` for the pure-function helpers.
-- **verify:** `bin/rails test test/lib/source_monitor/fetching/feed_fetcher_test.rb -n /jitter|body_digest|metadata|configured_|extract_numeric/i` exits 0
-- **done:** Lines 490-518 and 569-600 covered.
-
-## Verification
-
-1. `bin/rails test test/lib/source_monitor/fetching/feed_fetcher_test.rb` exits 0
-2. `COVERAGE=1 bin/rails test test/lib/source_monitor/fetching/feed_fetcher_test.rb` shows feed_fetcher.rb with >80% branch coverage
-3. `bin/rails test` exits 0 (no regressions)
-
-## Success Criteria
-
-- [ ] FeedFetcher coverage drops from 245 uncovered lines to fewer than 50
-- [ ] All retry/circuit breaker branches tested
-- [ ] All Faraday error wrapping branches tested
-- [ ] All header handling branches tested
-- [ ] Entry processing and error normalization branches tested
-- [ ] Jitter, interval helpers, and metadata management tested
-- [ ] REQ-01 substantially satisfied

data/.vbw-planning/milestones/default/phases/02-critical-path-test-coverage/PLAN-02-SUMMARY.md

@@ -1,64 +0,0 @@
-# PLAN-02 Summary: item-creator-tests
-
-## Status: COMPLETE
-
-## Commit
-
-- **Hash:** `ce8ede4`
-- **Message:** `test(item-creator): close coverage gaps for URL/content, dupes, authors, errors, utils`
-- **Files changed:** 1 file, 941 insertions
-
-## Tasks Completed
-
-### Task 1: Test URL extraction fallbacks and content extraction chain
-- Tested extract_url with link_nodes alternate link, links array fallback, nil handling
-- Tested extract_content priority: content > content_encoded > summary
-- Tested extract_updated_timestamp returns entry.updated when present
-
-### Task 2: Test concurrent duplicate handling (RecordNotUnique)
-- Tested RecordNotUnique for guid conflict finds and updates existing item
-- Tested RecordNotUnique for fingerprint conflict finds by fingerprint
-- Tested handle_concurrent_duplicate returns Result with status: :updated
-
-### Task 3: Test multi-format author, enclosure, and media extraction
-- Tested extract_authors from dc_creators, author_nodes (email/uri), deduplication
-- Tested extract_enclosures from RSS enclosure_nodes, Atom link_nodes, JSON attachments
-- Tested extract_media_content with url, type, medium, dimensions
-- Tested extract_media_thumbnail_url fallback from nodes to entry.image
-- Tested blank URL filtering in enclosures
-
-### Task 4: Test feed content processing error paths and readability edge cases
-- Tested parser error produces item with raw content and error metadata
-- Tested should_process_feed_content? returns false for blank/non-HTML content
-- Tested deep_copy handles Hash, Array, deep_dup, TypeError rescue
-- Tested build_feed_content_metadata includes readability_text_length
-- Tested html_fragment? detection
-
-### Task 5: Test utility methods
-- Tested safe_integer: nil, Integer, string "42", non-numeric string
-- Tested split_keywords: commas, semicolons, whitespace stripping
-- Tested extract_guid dedup when entry_id equals URL
-- Tested extract_language from json_entry and entry.language paths
-- Tested normalize_metadata JSON roundtrip and unparseable values
-- Tested extract_comments_count slash_comments_raw/comments_count fallback
-
-## Deviations
-
-None -- plan executed as specified.
-
-## Verification Results
-
-| Check | Result |
-|-------|--------|
-| `bin/rails test test/lib/source_monitor/items/item_creator_test.rb` | All tests pass |
-| `bin/rails test` | 760 runs, 2626 assertions, 0 failures, 0 errors, 0 skips |
-
-## Success Criteria
-
-- [x] 56 new tests added (78 total, 941 lines)
-- [x] URL extraction fallback branches tested
-- [x] Concurrent duplicate handling tested
-- [x] Multi-format author/enclosure/media extraction tested
-- [x] Feed content processing error paths tested
-- [x] All utility methods tested
-- [x] REQ-02 substantially satisfied

data/.vbw-planning/milestones/default/phases/02-critical-path-test-coverage/PLAN-02.md

@@ -1,138 +0,0 @@
----
-phase: 2
-plan: 2
-title: item-creator-tests
-wave: 1
-depends_on: []
-skills_used: []
-must_haves:
-  truths:
-    - "Running `bin/rails test test/lib/source_monitor/items/item_creator_test.rb` exits 0 with zero failures"
-    - "Coverage report shows lib/source_monitor/items/item_creator.rb has fewer than 40 uncovered lines (down from 228)"
-    - "Running `bin/rails test` exits 0 with no regressions"
-  artifacts:
-    - "test/lib/source_monitor/items/item_creator_test.rb -- extended with new test methods covering URL extraction, content extraction, concurrent duplicate handling, author/enclosure/media extraction, feed content processing, and utility methods"
-  key_links:
-    - "REQ-02 substantially satisfied -- ItemCreator branch coverage above 80%"
----
-
-# Plan 02: item-creator-tests
-
-## Objective
-
-Close the coverage gap in `lib/source_monitor/items/item_creator.rb` (currently 228 uncovered lines out of 601). The existing test file covers basic RSS/Atom/JSON creation, fingerprint generation, guid fallback, readability processing, metadata extraction, and guid/fingerprint deduplication. This plan targets the remaining uncovered branches: URL extraction from link_nodes and links arrays, content extraction fallback chain, concurrent duplicate handling (RecordNotUnique), author extraction from multiple sources, enclosure extraction from Atom link_nodes and JSON attachments, media content extraction, language/copyright/comments extraction, keyword splitting, safe_integer edge cases, and the deep_copy utility.
-
-## Context
-
-<context>
-@lib/source_monitor/items/item_creator.rb -- 601 lines, item creation with dedup logic
-@test/lib/source_monitor/items/item_creator_test.rb -- existing test file with 8 tests
-@config/coverage_baseline.json -- lists 228 uncovered lines for item_creator.rb
-@test/fixtures/feeds/ -- RSS, Atom, JSON feed fixtures
-@test/test_helper.rb -- test infrastructure
-
-**Decomposition rationale:** ItemCreator is the second largest coverage gap. Its uncovered lines cluster into: (1) URL/content/timestamp extraction branches, (2) concurrent duplicate handling, (3) multi-format author/enclosure/media extraction, (4) feed content processing error paths, (5) utility methods. Each task targets a distinct cluster.
-
-**Trade-offs considered:**
-- Many branches are triggered by specific Feedjira entry types (AtomEntry, JSONFeedItem). Tests need mock entries or real parsed fixtures to exercise these.
-- The concurrent duplicate test (RecordNotUnique) requires careful setup to simulate a race condition without actually racing.
-- Testing private methods through the public `call` interface keeps tests realistic, but some deep utility methods (deep_copy, safe_integer, split_keywords) are easier to verify directly.
-
-**What constrains the structure:**
-- Must use Feedjira-parsed entries (not plain hashes) to exercise respond_to? checks
-- Atom and JSON-specific branches need entries of the correct type
-- Tests extend the existing test file
-</context>
-
-## Tasks
-
-### Task 1: Test URL extraction fallbacks and content extraction chain
-
-- **name:** test-url-and-content-extraction
-- **files:**
-  - `lib/source_monitor/items/item_creator.rb` -- (read-only reference)
-  - `test/lib/source_monitor/items/item_creator_test.rb`
-- **action:** Add tests covering lines 288-310 (extract_url with link_nodes and links arrays), lines 318-336 (extract_content with CONTENT_METHODS fallback chain), and lines 328-342 (extract_timestamp, extract_updated_timestamp). Specifically:
-  1. Test extract_url when entry.url is blank but entry.link_nodes has an alternate link with href -- use an Atom entry fixture
-  2. Test extract_url when entry.url is blank and link_nodes are empty but entry.links has a URL string
-  3. Test extract_url returns nil when no URL source is available (mock entry with no url/link_nodes/links)
-  4. Test extract_content tries :content, then :content_encoded, then :summary in order -- create mock entries that respond to different method subsets
-  5. Test extract_updated_timestamp returns entry.updated when present, nil otherwise
-  Use OpenStruct or Minitest::Mock to create entries with specific respond_to? patterns for edge cases not covered by real feed fixtures.
-- **verify:** `bin/rails test test/lib/source_monitor/items/item_creator_test.rb -n /url_extraction|content_extraction|updated_timestamp/i` exits 0
-- **done:** Lines 288-310, 318-342 covered.
-
-### Task 2: Test concurrent duplicate handling (RecordNotUnique)
-
-- **name:** test-concurrent-duplicate-handling
-- **files:**
-  - `test/lib/source_monitor/items/item_creator_test.rb`
-- **action:** Add tests covering lines 104-128 (create_new_item rescue RecordNotUnique, handle_concurrent_duplicate, find_conflicting_item). Specifically:
-  1. Test that when create_new_item raises ActiveRecord::RecordNotUnique for a guid conflict, the item is found and updated instead
-  2. Test that when RecordNotUnique fires for a fingerprint conflict (no raw guid), the item is found by fingerprint and updated
-  3. Test that handle_concurrent_duplicate returns a Result with status: :updated and the correct matched_by
-  Simulate RecordNotUnique by: (a) creating an item first, (b) stubbing source.items.new to return an item that raises RecordNotUnique on save!, then verifying the fallback path finds and updates the existing item.
-- **verify:** `bin/rails test test/lib/source_monitor/items/item_creator_test.rb -n /concurrent_duplicate|record_not_unique/i` exits 0
-- **done:** Lines 104-128 covered.
-
-### Task 3: Test multi-format author, enclosure, and media extraction
-
-- **name:** test-author-enclosure-media-extraction
-- **files:**
-  - `test/lib/source_monitor/items/item_creator_test.rb`
-- **action:** Add tests covering lines 348-383 (extract_authors with rss_authors, dc_creators, author_nodes, json authors), lines 416-466 (extract_enclosures from rss enclosure_nodes, atom link_nodes with rel=enclosure, json attachments), and lines 477-499 (extract_media_content). Specifically:
-  1. Test extract_authors collects from rss_authors, dc_creators, dc_creator, and author_nodes (name/email/uri) -- deduplicates and compacts
-  2. Test extract_enclosures from Atom link_nodes with rel="enclosure" produces entries with source: "atom_link"
-  3. Test extract_media_content builds array from media_content_nodes with url, type, medium, height, width, file_size, duration, expression -- compacted
-  4. Test extract_media_thumbnail_url falls back from media_thumbnail_nodes to entry.image
-  5. Test extract_enclosures skips entries with blank URLs
-  Build mock entries using Struct or OpenStruct to simulate the various node types. The JSON-specific paths are already partially tested; focus on Atom and RSS edge cases.
-- **verify:** `bin/rails test test/lib/source_monitor/items/item_creator_test.rb -n /authors|enclosure|media_content|media_thumbnail/i` exits 0
-- **done:** Lines 348-383, 416-466, 477-499 covered.
-
-### Task 4: Test feed content processing error path and readability edge cases
-
-- **name:** test-feed-content-processing-errors
-- **files:**
-  - `test/lib/source_monitor/items/item_creator_test.rb`
-- **action:** Add tests covering lines 137-158 (process_feed_content error rescue), lines 160-165 (should_process_feed_content?), lines 187-208 (default_feed_readability_options, build_feed_content_metadata), and lines 210-231 (html_fragment?, deep_copy). Specifically:
-  1. Test that when readability parser raises an error, the item is created with raw content and error metadata (lines 148-157): metadata has "status"=>"failed", "error_class", "error_message"
-  2. Test should_process_feed_content? returns false when content is blank or when content has no HTML tags (html_fragment? returns false)
-  3. Test deep_copy handles Hash, Array, and objects that support deep_dup, plus TypeError rescue
-  4. Test build_feed_content_metadata includes readability_text_length and title when present
-  5. Test html_fragment? returns true for `<p>text</p>` and false for plain text
-  Stub the parser class to raise for the error path test. Use source with feed_content_readability_enabled: true.
-- **verify:** `bin/rails test test/lib/source_monitor/items/item_creator_test.rb -n /processing_error|html_fragment|deep_copy|readability_metadata/i` exits 0
-- **done:** Lines 137-165, 187-231 covered.
-
-### Task 5: Test utility methods: safe_integer, split_keywords, string_or_nil, normalize_metadata, extract_guid edge cases
-
-- **name:** test-utility-methods
-- **files:**
-  - `test/lib/source_monitor/items/item_creator_test.rb`
-- **action:** Add tests covering lines 501-534 (extract_language, extract_copyright, extract_comments_url, extract_comments_count), lines 536-543 (extract_metadata with normalize_metadata), lines 555-597 (string_or_nil, sanitize_string_array, split_keywords, safe_integer, json_entry?, atom_entry?, normalize_metadata). Specifically:
-  1. Test safe_integer returns nil for nil, returns Integer for Integer, parses string "42", returns nil for non-numeric string (lines 574-584)
-  2. Test split_keywords splits on commas and semicolons, strips whitespace, removes blank entries (lines 565-572)
-  3. Test extract_guid returns nil when entry_id equals URL (dedup logic at line 283-285)
-  4. Test extract_language from json_entry? path (line 506-507) and from entry.language (line 502-503)
-  5. Test normalize_metadata returns empty hash for unparseable values (JSON roundtrip at lines 594-597)
-  6. Test extract_comments_count tries slash_comments_raw then comments_count (lines 529-533)
-  Use mock entries with targeted respond_to? patterns. For json_entry? and atom_entry? tests, use actual Feedjira-parsed entries from fixtures.
-- **verify:** `bin/rails test test/lib/source_monitor/items/item_creator_test.rb -n /safe_integer|split_keywords|extract_guid_edge|language|copyright|normalize_metadata|comments_count/i` exits 0
-- **done:** Lines 501-597 covered.
-
-## Verification
-
-1. `bin/rails test test/lib/source_monitor/items/item_creator_test.rb` exits 0
-2. `COVERAGE=1 bin/rails test test/lib/source_monitor/items/item_creator_test.rb` shows item_creator.rb with >80% branch coverage
-3. `bin/rails test` exits 0 (no regressions)
-
-## Success Criteria
-
-- [ ] ItemCreator coverage drops from 228 uncovered lines to fewer than 40
-- [ ] URL extraction fallback branches tested
-- [ ] Concurrent duplicate handling tested
-- [ ] Multi-format author/enclosure/media extraction tested
-- [ ] Feed content processing error paths tested
-- [ ] All utility methods tested
-- [ ] REQ-02 substantially satisfied