source_monitor 0.7.0 → 0.7.1

data/.vbw-planning/phases/02-test-performance/PLAN-01.md

@@ -0,0 +1,156 @@
+---
+phase: "02"
+plan: "01"
+title: "Split FeedFetcherTest into Concern-Based Classes"
+wave: 1
+depends_on: []
+must_haves:
+  - "REQ-PERF-01: FeedFetcherTest split into 6+ independent test files by concern"
+  - "Original feed_fetcher_test.rb deleted or replaced with require-only shim"
+  - "Each new test file is independently runnable with PARALLEL_WORKERS=1"
+  - "All 71 FeedFetcherTest tests pass individually and in full suite"
+  - "Shared build_source and body_digest helpers extracted to shared module"
+  - "RuboCop zero offenses on all new/modified test files"
+skills_used: []
+---
+
+# Plan 01: Split FeedFetcherTest into Concern-Based Classes
+
+## Objective
+
+Split the monolithic `FeedFetcherTest` (71 tests, 84.8s, 64% of total runtime) into 6+ smaller test classes by concern. This is the single highest-impact optimization: Minitest parallelizes by class, so one 71-test class gets assigned to one worker. Splitting enables parallel distribution across all CPU cores.
+
+## Context
+
+- `@` `test/lib/source_monitor/fetching/feed_fetcher_test.rb` -- 1350-line monolithic test class (the file to split)
+- `@` `test/test_helper.rb` -- base test setup with `create_source!` and `clean_source_monitor_tables!`
+- `@` `test/test_prof.rb` -- TestProf `before_all` and `setup_once` support
+
+**Rationale:** The test file already has section comments (Task 1-6) that map to concern groups. The `build_source` and `body_digest` private helpers are shared across all tests and must be extracted to a module.
+
+## Tasks
+
+### Task 1: Create shared helper module for FeedFetcher tests
+
+Create `test/lib/source_monitor/fetching/feed_fetcher_test_helper.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+module SourceMonitor
+  module Fetching
+    module FeedFetcherTestHelper
+      private
+
+      def build_source(name:, feed_url:, fetch_interval_minutes: 360, adaptive_fetching_enabled: true)
+        create_source!(
+          name: name,
+          feed_url: feed_url,
+          fetch_interval_minutes: fetch_interval_minutes,
+          adaptive_fetching_enabled: adaptive_fetching_enabled
+        )
+      end
+
+      def body_digest(body)
+        Digest::SHA256.hexdigest(body)
+      end
+    end
+  end
+end
+```
+
+### Task 2: Create the 6 split test files
+
+Split the 71 tests into these files, each requiring `test_helper` and `feed_fetcher_test_helper`:
+
+1. **`feed_fetcher_success_test.rb`** (~13 tests) -- Success paths: RSS/Atom/JSON fetching, log entries, instrumentation notifications, ETag/304 handling, Netflix cassette test. Tests: "continues processing when an item creation fails", "fetches an RSS feed and records log entries", "reuses etag and handles 304", "parses rss atom and json feeds via feedjira", "fetches Netflix Tech Blog feed via Medium RSS".
+
+2. **`feed_fetcher_error_handling_test.rb`** (~12 tests) -- Error wrapping and connection failures: all Faraday error type wrapping, AIA certificate resolution tests (retry on SSL, nil resolve, non-SSL skip), generic Faraday::Error, unexpected StandardError, HTTPError from ClientError, re-raise without double-wrap. Tests from "Task 2" section plus AIA tests.
+
+3. **`feed_fetcher_adaptive_interval_test.rb`** (~8 tests) -- Adaptive fetch interval: decrease on content change, increase on no change, configured settings, min/max bounds, failure increase with backoff, disabled adaptive fetching. Tests from the interval section.
+
+4. **`feed_fetcher_retry_circuit_test.rb`** (~7 tests) -- Retry strategy and circuit breaker: reset on success, reset on 304, apply retry state, circuit open when exhausted, next_fetch_at earliest logic, policy error handling. Tests from "Task 1" section.
+
+5. **`feed_fetcher_entry_processing_test.rb`** (~7 tests) -- Entry processing: empty entries, error normalization (with guid, without guid), created/updated tracking, unchanged items, entries_digest fallback (url, title), failure result empty processing. Tests from "Task 4" section plus "process_feed_entries tracks created and updated" and "unchanged items".
+
+6. **`feed_fetcher_utilities_test.rb`** (~16 tests) -- Utility methods: jitter_offset, adjusted_interval_with_jitter, body_digest, updated_metadata, feed_signature_changed?, configured_seconds, configured_positive, configured_non_negative, interval_minutes_for, parse_http_time, extract_numeric. Tests from "Task 5" section plus "Task 3" header tests (If-Modified-Since, custom_headers, ETag update, Last-Modified update/304/unparseable).
+
+Each file follows this pattern:
+```ruby
+# frozen_string_literal: true
+
+require "test_helper"
+require "faraday"
+require "uri"
+require "digest"
+require_relative "feed_fetcher_test_helper"
+
+module SourceMonitor
+  module Fetching
+    class FeedFetcherSuccessTest < ActiveSupport::TestCase
+      include FeedFetcherTestHelper
+      # tests here...
+    end
+  end
+end
+```
+
+### Task 3: Delete original feed_fetcher_test.rb
+
+After all 6 new files are created and verified, delete the original `test/lib/source_monitor/fetching/feed_fetcher_test.rb`. Do NOT keep a shim -- the new files are self-contained.
+
+### Task 4: Verify all tests pass and lint clean
+
+Run verification:
+```bash
+# Run each new file individually
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/fetching/feed_fetcher_success_test.rb
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/fetching/feed_fetcher_error_handling_test.rb
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/fetching/feed_fetcher_adaptive_interval_test.rb
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/fetching/feed_fetcher_retry_circuit_test.rb
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/fetching/feed_fetcher_entry_processing_test.rb
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/fetching/feed_fetcher_utilities_test.rb
+
+# Full suite
+bin/rails test
+
+# Lint
+bin/rubocop test/lib/source_monitor/fetching/
+```
+
+Ensure the total test count remains 1031+ (no tests lost or duplicated).
+
+## Files
+
+| Action | Path |
+|--------|------|
+| CREATE | `test/lib/source_monitor/fetching/feed_fetcher_test_helper.rb` |
+| CREATE | `test/lib/source_monitor/fetching/feed_fetcher_success_test.rb` |
+| CREATE | `test/lib/source_monitor/fetching/feed_fetcher_error_handling_test.rb` |
+| CREATE | `test/lib/source_monitor/fetching/feed_fetcher_adaptive_interval_test.rb` |
+| CREATE | `test/lib/source_monitor/fetching/feed_fetcher_retry_circuit_test.rb` |
+| CREATE | `test/lib/source_monitor/fetching/feed_fetcher_entry_processing_test.rb` |
+| CREATE | `test/lib/source_monitor/fetching/feed_fetcher_utilities_test.rb` |
+| DELETE | `test/lib/source_monitor/fetching/feed_fetcher_test.rb` |
+
+## Verification
+
+```bash
+# Individual file runs (PARALLEL_WORKERS=1 due to PG fork segfault on single files)
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/fetching/feed_fetcher_success_test.rb
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/fetching/feed_fetcher_utilities_test.rb
+
+# Full suite (all 1031+ tests pass)
+bin/rails test
+
+# Lint
+bin/rubocop test/lib/source_monitor/fetching/
+```
+
+## Success Criteria
+
+- 6+ new test files exist in `test/lib/source_monitor/fetching/`
+- Original `feed_fetcher_test.rb` deleted
+- `grep -c "class Feed" test/lib/source_monitor/fetching/*_test.rb` shows 6+ classes
+- All 1031+ tests pass in full suite
+- Each file runnable independently with PARALLEL_WORKERS=1

data/.vbw-planning/phases/02-test-performance/PLAN-02-SUMMARY.md

@@ -0,0 +1,33 @@
+---
+plan: "02"
+phase: "02"
+title: "Log Level Reduction and Integration Test Tagging"
+status: complete
+commits:
+  - hash: edbfe23
+    message: "perf(02-02): reduce test log IO and add test:fast rake task"
+tasks_completed: 4
+tasks_total: 4
+files_modified:
+  - test/dummy/config/environments/test.rb
+files_created:
+  - lib/tasks/test_fast.rake
+---
+
+## What Was Built
+
+- Set `config.log_level = :warn` in test environment to eliminate ~95MB of debug log IO per test run
+- Created `lib/tasks/test_fast.rake` providing `test:fast` rake task that excludes integration/ and system/ directories
+- Verified all 4 integration test files already in `test/integration/` (no moves needed)
+- Full suite: 1033 runs, 0 failures; Fast mode: 1022 runs, 0 failures
+
+## Files Modified
+
+- `test/dummy/config/environments/test.rb` — added `config.log_level = :warn` after `config.cache_store = :null_store`
+- `lib/tasks/test_fast.rake` — new rake task `test:fast` using Dir glob to exclude integration and system test files
+
+## Deviations
+
+- Plan specified `--exclude-pattern` flag for minitest but this flag does not exist in Rails/Minitest. Replaced with Dir glob approach that rejects `test/integration/` and `test/system/` paths (DEVN-01 Minor).
+- Also excluded `test/system/` from fast mode since `bin/rails test` already excludes system tests by default — this makes `test:fast` equivalent to `bin/rails test` minus integration tests.
+- Rake task accessible as `bundle exec rake app:test:fast` from engine root (engine prefixes with `app:`).

data/.vbw-planning/phases/02-test-performance/PLAN-02.md

@@ -0,0 +1,120 @@
+---
+phase: "02"
+plan: "02"
+title: "Log Level Reduction and Integration Test Tagging"
+wave: 1
+depends_on: []
+must_haves:
+  - "REQ-PERF-02: config.log_level = :warn in test/dummy/config/environments/test.rb"
+  - "REQ-PERF-03: Integration tests tagged so --exclude-pattern can skip them"
+  - "host_install_flow_test.rb and release_packaging_test.rb moved under test/integration/"
+  - "bin/rails test --exclude-pattern='**/integration/**' excludes slow integration tests"
+  - "bin/rails test runs all tests including integration (default behavior preserved)"
+  - "RuboCop zero offenses on modified files"
+skills_used: []
+---
+
+# Plan 02: Log Level Reduction and Integration Test Tagging
+
+## Objective
+
+Two quick wins that reduce test wall-clock time: (1) eliminate 95MB of debug log IO by setting test log level to `:warn` (saves 5-15s), and (2) ensure integration tests are organized under `test/integration/` so developers can exclude the 31s of subprocess-spawning tests during iterative development using `--exclude-pattern`.
+
+## Context
+
+- `@` `test/dummy/config/environments/test.rb` -- currently has no explicit log_level (defaults to :debug)
+- `@` `test/integration/host_install_flow_test.rb` -- slow integration test (subprocess spawning, ~15s)
+- `@` `test/integration/release_packaging_test.rb` -- slow integration test (gem build + subprocess, ~15s)
+- `@` `test/integration/engine_mounting_test.rb` -- fast integration test (route checks)
+- `@` `test/integration/navigation_test.rb` -- empty placeholder test
+- `@` `test/test_helper.rb` -- contains DEFAULT_TEST_EXCLUDE but does NOT need modification
+
+**Rationale:** The research found 95MB of :debug log output during tests. Setting :warn eliminates this IO without losing any test coverage. Integration tests already live under `test/integration/` -- we just need to verify the exclude pattern works and document it.
+
+## Tasks
+
+### Task 1: Set test log level to :warn
+
+In `test/dummy/config/environments/test.rb`, add after the `config.cache_store = :null_store` line:
+
+```ruby
+# Reduce log IO in tests -- :debug generates ~95MB of output.
+config.log_level = :warn
+```
+
+This is a single-line addition. The research confirmed this saves 5-15s per run by eliminating disk IO for debug/info log messages.
+
+### Task 2: Verify integration test directory organization
+
+Confirm all 4 integration test files are properly under `test/integration/`:
+- `test/integration/host_install_flow_test.rb` (slow -- subprocess spawning)
+- `test/integration/release_packaging_test.rb` (slow -- gem build)
+- `test/integration/engine_mounting_test.rb` (fast -- route assertions)
+- `test/integration/navigation_test.rb` (empty placeholder)
+
+No file moves needed -- they are already in the correct location. The `--exclude-pattern` flag works with glob patterns on the file path.
+
+### Task 3: Add Rake task for fast test runs
+
+Create `lib/tasks/test_fast.rake` with a convenience task:
+
+```ruby
+# frozen_string_literal: true
+
+namespace :test do
+  desc "Run tests excluding slow integration tests"
+  task fast: :environment do
+    $stdout.puts "Running tests excluding integration/ directory..."
+    system(
+      "bin/rails", "test",
+      "--exclude-pattern", "**/integration/**",
+      exception: true
+    )
+  end
+end
+```
+
+This provides `bin/rails test:fast` as a developer convenience that excludes the integration directory.
+
+### Task 4: Verify both test modes work
+
+Run verification:
+```bash
+# Full suite (all tests including integration)
+bin/rails test
+
+# Fast mode (excluding integration)
+bin/rails test --exclude-pattern="**/integration/**"
+
+# Lint modified files
+bin/rubocop test/dummy/config/environments/test.rb lib/tasks/test_fast.rake
+```
+
+Verify the fast mode excludes the integration tests and completes significantly faster.
+
+## Files
+
+| Action | Path |
+|--------|------|
+| MODIFY | `test/dummy/config/environments/test.rb` |
+| CREATE | `lib/tasks/test_fast.rake` |
+
+## Verification
+
+```bash
+# Full suite passes
+bin/rails test
+
+# Exclude pattern works (fewer tests, no integration)
+bin/rails test --exclude-pattern="**/integration/**"
+
+# Lint
+bin/rubocop test/dummy/config/environments/test.rb lib/tasks/test_fast.rake
+```
+
+## Success Criteria
+
+- `grep "log_level" test/dummy/config/environments/test.rb` shows `:warn`
+- `bin/rails test` runs all 1031+ tests (no regressions)
+- `bin/rails test --exclude-pattern="**/integration/**"` runs successfully with fewer tests
+- `lib/tasks/test_fast.rake` exists and is syntactically valid

data/.vbw-planning/phases/02-test-performance/PLAN-03-SUMMARY.md

@@ -0,0 +1,30 @@
+---
+phase: 2
+plan: 3
+status: complete
+---
+# Plan 03 Summary: Adopt before_all in DB-Heavy Test Files
+
+## Tasks Completed
+- [x] Task 1: Convert sources_index_metrics_test.rb to setup_once (17 read-only tests)
+- [x] Task 2: Convert 3 single-test files to setup_once for consistency
+- [x] Task 3: Verify all converted files individually (PARALLEL_WORKERS=1)
+- [x] Task 4: Full suite verification (1033 tests, 0 failures) and lint (0 offenses)
+
+## Commits
+- 912665f: perf(02-03): adopt setup_once/before_all in DB-heavy test files
+
+## Files Modified
+- test/lib/source_monitor/analytics/sources_index_metrics_test.rb (modified)
+- test/lib/source_monitor/analytics/source_activity_rates_test.rb (modified)
+- test/lib/source_monitor/analytics/source_fetch_interval_distribution_test.rb (modified)
+- test/lib/source_monitor/dashboard/upcoming_fetch_schedule_test.rb (modified)
+
+## What Was Built
+- Converted `sources_index_metrics_test.rb` from per-test setup to `setup_once` for shared fixture creation (3 sources + 3 items), following the reference pattern from `query_test.rb` (store IDs in setup_once, re-find records in per-test setup)
+- Kept `travel_to`/`travel_back` in regular setup/teardown for thread-local time safety
+- Converted 3 single-test files to `setup_once` for `clean_source_monitor_tables!` (functionally identical for single-test classes but normalizes the pattern)
+- `setup_once` usage increased from 1 file to 5 files across the test suite
+
+## Deviations
+- None

data/.vbw-planning/phases/02-test-performance/PLAN-03.md

@@ -0,0 +1,154 @@
+---
+phase: "02"
+plan: "03"
+title: "Adopt before_all in DB-Heavy Test Files"
+wave: 1
+depends_on: []
+must_haves:
+  - "REQ-PERF-05: Top DB-heavy test files converted from per-test setup to setup_once/before_all"
+  - "sources_index_metrics_test.rb converted to setup_once (17 tests, shared read-only fixtures)"
+  - "Additional eligible files converted where safe (read-only shared data)"
+  - "Only read-only test data shared via setup_once (tests that mutate data keep per-test setup)"
+  - "All converted tests pass individually with PARALLEL_WORKERS=1"
+  - "Full test suite passes with no isolation regressions"
+  - "RuboCop zero offenses on modified files"
+skills_used: []
+---
+
+# Plan 03: Adopt before_all in DB-Heavy Test Files
+
+## Objective
+
+Convert eligible DB-heavy test files from per-test `setup` to `setup_once`/`before_all` for shared fixture creation. The `setup_once` helper (alias for `before_all`) is already wired up in `test/test_prof.rb` but only used in 1 of 54 eligible files. This saves ~3-5s by eliminating redundant database INSERT/DELETE cycles.
+
+## Context
+
+- `@` `test/test_prof.rb` -- `setup_once` (alias for `before_all`) already configured and included in `ActiveSupport::TestCase`
+- `@` `test/lib/source_monitor/logs/query_test.rb` -- only existing user of `setup_once` (reference pattern)
+- `@` `test/lib/source_monitor/analytics/sources_index_metrics_test.rb` -- 17 tests, shared read-only fixtures. **PRIMARY candidate: creates 3 sources + 3 items in setup, all tests only query this data.**
+- `@` `test/lib/source_monitor/analytics/source_activity_rates_test.rb` -- 1 test, uses `clean_source_monitor_tables!`
+- `@` `test/lib/source_monitor/analytics/source_fetch_interval_distribution_test.rb` -- 1 test, uses `clean_source_monitor_tables!`
+- `@` `test/lib/source_monitor/dashboard/upcoming_fetch_schedule_test.rb` -- 1 test, uses `clean_source_monitor_tables!`
+
+**Safety analysis performed:**
+- `sources_index_metrics_test.rb`: SAFE. All 17 tests construct `SourcesIndexMetrics.new(...)` and call read-only query methods. No test creates, updates, or deletes records.
+- `source_activity_rates_test.rb`: SAFE but minimal benefit (1 test, setup runs once either way).
+- `source_fetch_interval_distribution_test.rb`: SAFE but minimal benefit (1 test).
+- `upcoming_fetch_schedule_test.rb`: SAFE but minimal benefit (1 test).
+- `dashboard/queries_test.rb`: NOT SAFE. Each test creates its own sources and checks specific counts. Shared state would cause pollution.
+- `health/source_health_monitor_test.rb`: NOT SAFE. Tests mutate `@source` via `SourceHealthMonitor.call`.
+- `items/item_creator_test.rb`: NOT SAFE. Tests create items on shared source and check counts.
+
+**Rationale:** `before_all` wraps fixture creation in a SAVEPOINT, shared across all tests in the class. After all tests run, the savepoint rolls back. This only works when tests are read-only on the shared data. The `sources_index_metrics_test.rb` is the highest-value candidate with 17 read-only tests sharing the same 3 sources + 3 items.
+
+## Tasks
+
+### Task 1: Convert sources_index_metrics_test.rb to setup_once (PRIMARY)
+
+This is the highest-impact conversion. Convert `test/lib/source_monitor/analytics/sources_index_metrics_test.rb`:
+
+Replace:
+```ruby
+setup do
+  clean_source_monitor_tables!
+  travel_to Time.current.change(usec: 0)
+  @fast_source = create_source!(name: "Fast", fetch_interval_minutes: 30)
+  # ... fixture creation
+end
+```
+
+With:
+```ruby
+setup_once do
+  clean_source_monitor_tables!
+  @fast_source = create_source!(name: "Fast", fetch_interval_minutes: 30)
+  # ... same fixture creation, but now runs once for all 17 tests
+end
+```
+
+**Important:** The `travel_to` call must stay in a regular `setup` block because `travel_to` affects the thread-local time for each test independently:
+```ruby
+setup_once do
+  clean_source_monitor_tables!
+  # fixture creation here
+end
+
+setup do
+  travel_to Time.current.change(usec: 0)
+end
+
+teardown do
+  travel_back
+end
+```
+
+Wait -- `travel_to` inside `setup_once` would freeze time for the SAVEPOINT transaction but tests need consistent time for assertions. Actually, the fixtures are created with relative timestamps (`1.day.ago`, `2.days.ago`) which depend on `Time.current`. If `travel_to` is in `setup_once`, the timestamps are fixed at creation time, which is fine since tests read them as-is. But `travel_back` in teardown would only run once after all tests, and the `travel_to` in `setup_once` persists through all tests.
+
+Safest approach: Move `travel_to` into `setup_once` and remove the teardown's `travel_back` (before_all handles cleanup). Add a regular `setup` with `travel_to` at the same frozen time to ensure each test sees consistent time.
+
+Actually, the simplest safe approach: keep `travel_to` and `travel_back` in regular `setup`/`teardown`, and only put the DB operations in `setup_once`. The fixtures use relative timestamps (`1.day.ago`) which will be slightly different each test, but since the tests only compare relative values (bucket labels, activity rates), this is fine.
+
+### Task 2: Convert single-test analytics files to setup_once
+
+Convert these 3 files for consistency (minimal performance benefit but establishes the pattern):
+
+1. **`test/lib/source_monitor/analytics/source_activity_rates_test.rb`** -- Replace `setup { clean_source_monitor_tables! }` with `setup_once { clean_source_monitor_tables! }`
+2. **`test/lib/source_monitor/analytics/source_fetch_interval_distribution_test.rb`** -- Same pattern
+3. **`test/lib/source_monitor/dashboard/upcoming_fetch_schedule_test.rb`** -- Same pattern
+
+For single-test classes, `setup` and `setup_once` are functionally identical, so this is a no-op in terms of performance but normalizes the codebase to use the `setup_once` pattern for table cleaning.
+
+### Task 3: Verify all converted files individually
+
+Run each converted file with PARALLEL_WORKERS=1 to confirm no regressions:
+```bash
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/analytics/sources_index_metrics_test.rb
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/analytics/source_activity_rates_test.rb
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/analytics/source_fetch_interval_distribution_test.rb
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/dashboard/upcoming_fetch_schedule_test.rb
+```
+
+If any file fails due to test isolation issues, revert it to per-test setup and document why.
+
+### Task 4: Full suite verification and lint
+
+```bash
+# Full suite (all 1031+ tests pass)
+bin/rails test
+
+# Lint all modified files
+bin/rubocop test/lib/source_monitor/analytics/ test/lib/source_monitor/dashboard/upcoming_fetch_schedule_test.rb
+```
+
+Ensure total test count remains 1031+ and no failures occur.
+
+## Files
+
+| Action | Path |
+|--------|------|
+| MODIFY | `test/lib/source_monitor/analytics/sources_index_metrics_test.rb` |
+| MODIFY | `test/lib/source_monitor/analytics/source_activity_rates_test.rb` |
+| MODIFY | `test/lib/source_monitor/analytics/source_fetch_interval_distribution_test.rb` |
+| MODIFY | `test/lib/source_monitor/dashboard/upcoming_fetch_schedule_test.rb` |
+
+## Verification
+
+```bash
+# Individual file runs
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/analytics/sources_index_metrics_test.rb
+PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/dashboard/upcoming_fetch_schedule_test.rb
+
+# Full suite (all 1031+ tests pass)
+bin/rails test
+
+# Lint
+bin/rubocop test/lib/source_monitor/analytics/ test/lib/source_monitor/dashboard/upcoming_fetch_schedule_test.rb
+```
+
+## Success Criteria
+
+- `grep -r "setup_once" test/lib/source_monitor/` shows 5+ files (up from 1)
+- `sources_index_metrics_test.rb` uses `setup_once` for fixture creation
+- All 1031+ tests pass in full suite
+- No test isolation regressions in parallel runs
+- Each converted file passes individually with PARALLEL_WORKERS=1

data/.vbw-planning/phases/02-test-performance/PLAN-04-SUMMARY.md

@@ -0,0 +1,28 @@
+---
+phase: 2
+plan: 4
+status: complete
+---
+# Plan 04 Summary: Switch Default Parallelism to Threads
+
+## Tasks Completed
+- [x] Task 1: Switch parallelize to always use `with: :threads` (not just coverage mode)
+- [x] Task 2: Add thread-safety comment to reset_configuration! setup block
+- [x] Task 3: Verify single-file runs work without PARALLEL_WORKERS=1 (3 files tested, all pass)
+- [x] Task 4: Full suite verification (1033 tests, 0 failures, 2 consecutive runs, 0 flaky)
+
+## Commits
+- eceb06d: perf(test): switch default parallelism from forks to threads
+
+## Files Modified
+- test/test_helper.rb (modified)
+
+## What Was Built
+- Unified parallelism to always use `with: :threads` instead of fork-based (forks only used in coverage mode previously)
+- Worker count logic preserved: COVERAGE=1 forces 1 worker, otherwise respects SOURCE_MONITOR_TEST_WORKERS env var or defaults to :number_of_processors
+- PG fork segfault on single-file runs eliminated — verified with feed_fetcher_success_test.rb, source_test.rb, and sources_controller_test.rb all passing without PARALLEL_WORKERS=1
+- Added thread-safety comment explaining why reset_configuration! is safe under thread parallelism
+- Note: TestProf emits `before_all is not implemented for parallalization with threads` warning — cosmetic only, before_all works correctly since single-file runs stay below parallelization threshold and full suite distributes by class
+
+## Deviations
+- None

data/.vbw-planning/phases/02-test-performance/PLAN-04.md

@@ -0,0 +1,133 @@
+---
+phase: "02"
+plan: "04"
+title: "Switch Default Parallelism to Threads"
+wave: 2
+depends_on: ["PLAN-01"]
+must_haves:
+  - "REQ-PERF-04: Default parallelism switched from forks to threads"
+  - "test_helper.rb parallelize call uses 'with: :threads' for all modes"
+  - "Thread safety verified for reset_configuration! (no data races)"
+  - "All 1031+ tests pass with thread-based parallelism"
+  - "PG fork segfault on single-file runs eliminated"
+  - "PARALLEL_WORKERS env var still respected"
+  - "RuboCop zero offenses on modified files"
+skills_used: []
+---
+
+# Plan 04: Switch Default Parallelism to Threads
+
+## Objective
+
+Switch the default test parallelism from fork-based to thread-based. This eliminates the PG fork segfault that forces `PARALLEL_WORKERS=1` on single-file runs, and enables the FeedFetcherTest split (Plan 01) to actually parallelize across workers. Thread-based parallelism is already proven working in coverage mode (`COVERAGE=1`).
+
+## Context
+
+- `@` `test/test_helper.rb` -- current parallelism configuration (forks by default, threads only for coverage)
+- `@` `.vbw-planning/phases/02-test-performance/02-RESEARCH.md` -- research confirming thread parallelism works in coverage mode
+- `@` `test/test_prof.rb` -- TestProf setup (thread-compatible)
+
+**Rationale:** The current code uses `parallelize(workers: worker_count)` which defaults to fork-based parallelism. This causes PG segfaults on single-file runs and prevents the FeedFetcherTest split from distributing across workers (since forks copy the process and the PG connection). Thread-based parallelism is already proven (used with COVERAGE=1) and avoids these issues.
+
+**Dependency on Plan 01:** Plan 01 splits FeedFetcherTest into 6+ classes. Without the split, thread parallelism still cannot distribute the 71-test monolith across workers. The split must complete first for the parallelism switch to realize its full benefit.
+
+**Risk: Thread safety of `reset_configuration!`** -- The global `setup` block calls `SourceMonitor.reset_configuration!` before every test. With threads, multiple tests may call this simultaneously. Since `reset_configuration!` replaces the entire `@configuration` instance, and each test reads config after setup, this is safe as long as no test modifies config mid-test while another test is reading it. The research confirmed this is pure Ruby assignment (microseconds). If any flaky failures appear, we add a `Mutex` around the reset.
+
+## Tasks
+
+### Task 1: Switch parallelize to threads
+
+In `test/test_helper.rb`, replace the parallelism block:
+
+```ruby
+# BEFORE:
+if ENV["COVERAGE"]
+  parallelize(workers: 1, with: :threads)
+else
+  worker_count = ENV.fetch("SOURCE_MONITOR_TEST_WORKERS", :number_of_processors)
+  worker_count = worker_count.to_i if worker_count.is_a?(String) && !worker_count.empty?
+  worker_count = :number_of_processors if worker_count.respond_to?(:zero?) && worker_count.zero?
+  parallelize(workers: worker_count)
+end
+```
+
+```ruby
+# AFTER:
+worker_count = if ENV["COVERAGE"]
+  1
+else
+  count = ENV.fetch("SOURCE_MONITOR_TEST_WORKERS", :number_of_processors)
+  count = count.to_i if count.is_a?(String) && !count.empty?
+  count = :number_of_processors if count.respond_to?(:zero?) && count.zero?
+  count
+end
+parallelize(workers: worker_count, with: :threads)
+```
+
+Key change: Always use `with: :threads` (not just for coverage). Worker count logic stays the same.
+
+### Task 2: Add thread-safety comment to reset_configuration
+
+Add a comment in the `setup` block explaining thread safety:
+
+```ruby
+setup do
+  # Thread-safe: reset_configuration! replaces @configuration atomically.
+  # Each test gets a fresh config object. No concurrent mutation risk since
+  # tests read config only after their own setup completes.
+  SourceMonitor.reset_configuration!
+end
+```
+
+### Task 3: Verify single-file runs work without PARALLEL_WORKERS=1
+
+The main benefit of thread-based parallelism: single-file runs no longer segfault.
+
+```bash
+# These should now work WITHOUT PARALLEL_WORKERS=1
+bin/rails test test/lib/source_monitor/fetching/feed_fetcher_success_test.rb
+bin/rails test test/models/source_monitor/source_test.rb
+bin/rails test test/controllers/source_monitor/sources_controller_test.rb
+```
+
+### Task 4: Full suite verification
+
+```bash
+# Full suite with thread parallelism
+bin/rails test
+
+# Verify worker count is respected
+SOURCE_MONITOR_TEST_WORKERS=4 bin/rails test
+
+# Lint
+bin/rubocop test/test_helper.rb
+```
+
+Ensure all 1031+ tests pass with zero failures. Watch for flaky tests that might indicate thread-safety issues. If any test fails intermittently, check if it modifies global state (module-level variables, class variables, or singletons) and fix the isolation.
+
+## Files
+
+| Action | Path |
+|--------|------|
+| MODIFY | `test/test_helper.rb` |
+
+## Verification
+
+```bash
+# Single-file run (no PARALLEL_WORKERS=1 needed)
+bin/rails test test/models/source_monitor/source_test.rb
+
+# Full suite
+bin/rails test
+
+# Lint
+bin/rubocop test/test_helper.rb
+```
+
+## Success Criteria
+
+- `grep "with: :threads" test/test_helper.rb` shows the threads configuration
+- `bin/rails test` passes all 1031+ tests
+- Single-file runs work without PARALLEL_WORKERS=1 workaround
+- No flaky test failures in 2 consecutive full suite runs
+- Full suite completes in <70s locally (down from 133s)