source_monitor 0.3.3 → 0.4.0

data/.vbw-planning/STATE.md

@@ -0,0 +1,43 @@
+<!-- VBW STATE -- Current milestone progress -->
+
+# State
+
+**Milestone:** generator-enhancements
+**Current Phase:** All phases complete
+**Status:** Ready for archive
+**Date:** 2026-02-12
+
+## Progress
+
+- Phase 0: Complete (quick fix ea788ea)
+- Phase 1: Complete (1 plan, 5 tasks, 4 commits)
+- Phase 2: Complete (1 plan, 5 tasks, 1 commit)
+- Phase 3: Complete (1 plan, 5 tasks, 1 commit) -- QA PASS
+- Phase 4: Complete (1 plan, 5 tasks, 5 commits) -- QA PASS 23/23
+- Phase 5: Complete (2 plans, 9 tasks, 9 commits) -- QA PASS 34/34
+- Phase 6: Complete (1 plan, 5 tasks, 5 commits) -- QA PASS 18/18
+
+## Decisions
+
+| Decision | Date | Rationale |
+|----------|------|-----------|
+| Docs-first approach | 2026-02-11 | Shipped doc fixes before code changes to unblock users immediately |
+| 3 phases for code changes | 2026-02-11 | Generator steps, verification, then docs alignment -- each independently testable |
+| Always create/patch Procfile.dev | 2026-02-11 | Maximum hand-holding for host app setup |
+| Target queue.yml only | 2026-02-11 | Rails 8 default, no legacy naming support |
+| External links open new tab with icon | 2026-02-12 | Consistent UX for all external URLs across dashboard, logs, sources, items |
+| Fetch log URL display: domain for RSS, item URL for scrapes | 2026-02-12 | User requested contextual URL display based on event type |
+| Image downloads via background job to ItemContent | 2026-02-12 | Content images only, opt-in via config.images.download_to_active_storage |
+| SSL fix: general cert store config, not Netflix-specific | 2026-02-12 | OpenSSL::X509::Store#set_default_paths on every Faraday connection |
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Phases | 7 (Phase 0-6) |
+| Plans completed | 7 (across all phases) |
+| Tasks completed | 34 |
+| Commits | ~26 |
+| Tests | 973 (up from 841) |
+| RuboCop | 389 files, 0 offenses |
+| Brakeman | 0 warnings |

data/.vbw-planning/config.json

@@ -8,5 +8,7 @@
   "visual_format": "unicode",
   "compaction_trigger": 130000,
   "max_tasks_per_plan": 5,
-  "agent_teams": true
+  "agent_teams": true,
+  "model_profile": "quality",
+  "model_overrides": {}
 }

data/.vbw-planning/discovery.json

@@ -19,6 +19,8 @@
     "User wants comprehensive cleanup, not surface-level",
     "Public API changes are acceptable for convention alignment",
     "Tests should be updated to match any changes, not removed",
-    "All layers: models, controllers, services, dead code"
+    "All layers: models, controllers, services, dead code",
+    "Generator should be maximally helpful -- create files rather than just warn",
+    "Target Rails 8 defaults (queue.yml) rather than supporting legacy naming"
   ]
 }

data/.vbw-planning/phases/01-generator-steps/01-CONTEXT.md

@@ -0,0 +1,33 @@
+# Phase 1 Context: Install Generator Steps
+
+## User Vision
+Enhance the install generator to automatically handle the two most common Solid Queue setup failures in host apps: missing Procfile.dev jobs entry and missing recurring_schedule dispatcher wiring.
+
+## Essential Features
+- Generator creates Procfile.dev if missing (with web: and jobs: entries)
+- Generator patches existing Procfile.dev to add jobs: entry (idempotent)
+- Generator patches config/queue.yml dispatcher with recurring_schedule: config/recurring.yml
+- Both steps integrated into the guided Setup::Workflow
+
+## Technical Preferences
+- **Procfile.dev:** Always create/patch -- maximum hand-holding. Create if missing, patch if exists.
+- **Queue config:** Target `config/queue.yml` (Rails 8 default). Don't worry about legacy `solid_queue.yml` naming.
+- Follow existing generator patterns (idempotent, skip-if-present, say_status output)
+
+## Boundaries
+- Don't modify any other config files (cable.yml, database.yml, etc.)
+- Don't modify the initializer template
+- Don't change existing generator steps (routes, initializer, recurring.yml)
+- Don't add verification logic here (that's Phase 2)
+
+## Acceptance Criteria
+- `bin/rails generate source_monitor:install` creates Procfile.dev with web: + jobs: when none exists
+- `bin/rails generate source_monitor:install` adds jobs: line to existing Procfile.dev without duplicating
+- `bin/rails generate source_monitor:install` adds recurring_schedule to queue.yml dispatcher
+- `bin/source_monitor install` (guided) runs both new steps
+- All existing generator tests still pass
+- New tests cover: fresh Procfile.dev, existing with entry, existing without entry, missing queue.yml
+
+## Decisions Made
+- Create Procfile.dev if missing (not just warn)
+- Target config/queue.yml only (Rails 8 default), not solid_queue.yml

data/.vbw-planning/phases/01-generator-steps/01-VERIFICATION.md

@@ -0,0 +1,86 @@
+# PLAN-01 Verification Report
+
+## Verdict: PASS
+
+**Verified by:** QA agent (deep tier, 30 checks)
+**Date:** 2026-02-11
+
+---
+
+## Functional Verification
+
+| # | Check | Result | Notes |
+|---|-------|--------|-------|
+| 1 | Generator tests pass | PASS | 20 runs, 109 assertions, 0 failures, 0 errors |
+| 2 | Workflow tests pass | PASS | 8 runs, 22 assertions, 0 failures, 0 errors |
+| 3 | Full test suite passes | PASS | 867 runs, 2898 assertions, 0 failures, 0 errors |
+| 4 | RuboCop clean | PASS | 376 files inspected, no offenses detected |
+| 5 | Brakeman clean | PASS | 0 warnings, 0 errors |
+
+## Code Review Checks
+
+| # | Check | Result | Notes |
+|---|-------|--------|-------|
+| 6 | Public method order correct | PASS | Order is: `add_routes_mount` (L17), `create_initializer` (L24), `configure_recurring_jobs` (L36), `patch_procfile_dev` (L52), `configure_queue_dispatcher` (L70), `print_next_steps` (L90) |
+| 7 | `patch_procfile_dev` handles 3 cases | PASS | Create (L64-66), append (L62-63), skip (L57-60) |
+| 8 | `configure_queue_dispatcher` handles 4 cases | PASS | Missing file (L73-76), already configured (L80-83), needs patching (L85-87), no dispatchers (L254-256 via `add_recurring_schedule_to_dispatchers!`) |
+| 9 | Private methods/constants in private section | PASS | `PROCFILE_JOBS_ENTRY` (L104), `RECURRING_SCHEDULE_VALUE` (L201), `DEFAULT_DISPATCHER` (L203), `queue_config_has_recurring_schedule?` (L209), `add_recurring_schedule_to_dispatchers!` (L229) -- all after `private` on L102 |
+| 10 | `frozen_string_literal: true` on all new files | PASS | `procfile_patcher.rb` (L1), `queue_config_patcher.rb` (L1) both have it |
+| 11 | Idempotency: both steps safe to run multiple times | PASS | `patch_procfile_dev`: checks `/^jobs:/` before acting; `configure_queue_dispatcher`: checks `has_recurring_schedule?` before acting. Test `test_does_not_duplicate_jobs_entry_when_rerun` explicitly verifies. |
+| 12 | `YAML.safe_load` uses `aliases: true` | PASS | Generator L78: `YAML.safe_load(File.read(queue_path), aliases: true)`. QueueConfigPatcher L24: `YAML.safe_load(path.read, aliases: true)` |
+| 13 | ProcfilePatcher matches `/^jobs:/` regex | PASS | Both generator (L57) and ProcfilePatcher (L17) use `/^jobs:/` regex |
+| 14 | QueueConfigPatcher recursive dispatcher search | PASS | `has_recurring_schedule?` (L36-53) recursively iterates `parsed.each_value`, checks nested hashes, and also checks top-level `dispatchers` key for flat configs |
+| 15 | Workflow has both new kwargs with defaults | PASS | `procfile_patcher: ProcfilePatcher.new` (L40), `queue_config_patcher: QueueConfigPatcher.new` (L41) |
+| 16 | Workflow calls patchers in correct position | PASS | Called at L73-74, after `initializer_patcher.ensure_navigation_hint` (L72) and before devise check (L76) |
+| 17 | Autoload entries in `lib/source_monitor.rb` | PASS | `ProcfilePatcher` (L164), `QueueConfigPatcher` (L165) both present in `Setup` module autoloads |
+| 18 | No hardcoded paths or env-specific assumptions | PASS | Paths are relative to `destination_root` (generator) or injected via constructor kwargs (patcher classes). No absolute paths. |
+| 19 | Test isolation (no cross-test contamination) | PASS | Generator tests use `prepare_destination` in setup. Workflow tests use Spy/Mock objects for all collaborators. No shared state. WORKER_SUFFIX handles parallel workers. |
+| 20 | `say_status` calls use correct symbols | PASS | `:create` (L66), `:append` (L63), `:skip` (L58, L74, L81), `:info` (L91-99) -- all correct |
+
+## Edge Case Verification
+
+| # | Check | Result | Notes |
+|---|-------|--------|-------|
+| 21 | Procfile.dev has `jobs:` with different content | PASS | Regex `/^jobs:/` matches any line starting with `jobs:` regardless of the command after it. Correctly skips without overwriting. |
+| 22 | queue.yml nested environments with different dispatchers | PASS | `queue_config_has_recurring_schedule?` recursively walks all hash values. `add_recurring_schedule_to_dispatchers!` processes all nested dispatcher arrays under any env key. Both handle flat and nested configs. |
+| 23 | queue.yml empty/nil after parsing | PASS | L78: `|| {}` ensures nil YAML parse result becomes empty hash. `queue_config_has_recurring_schedule?({})` returns false. `add_recurring_schedule_to_dispatchers!({})` adds default dispatcher section. |
+| 24 | Procfile.dev has trailing newlines | PASS | When appending (L62), uses `puts("", PROCFILE_JOBS_ENTRY)` which adds a blank line before the jobs entry. This handles trailing newlines gracefully -- the blank line acts as separator. |
+| 25 | queue.yml dispatchers is empty array | PASS | If `dispatchers: []`, the `any?` check in `has_recurring_schedule?` returns false (no items to check). `add_recurring_schedule_to_dispatchers!` iterates the empty array (no-op) but sets `found_dispatchers = true` since the key exists. This means an empty dispatchers array stays empty with no recurring_schedule added. **Minor note**: This is a debatable edge case -- an empty dispatchers array means the user intentionally has no dispatchers, so not adding one is reasonable behavior. |
+
+## Requirements Verification
+
+| # | Check | Result | Notes |
+|---|-------|--------|-------|
+| 26 | REQ-16: Generator patches Procfile.dev | PASS | `patch_procfile_dev` creates/appends/skips as needed. 4 tests cover all scenarios. |
+| 27 | REQ-17: Generator patches queue.yml | PASS | `configure_queue_dispatcher` patches/skips/handles-missing as needed. 4 tests cover all scenarios. |
+| 28 | REQ-18: Workflow integrates both | PASS | `workflow.rb` L73-74 calls both patchers. Workflow test L96-97 verifies both are called. |
+| 29 | Test count increased | PASS | Was 841, now 867 (+26 tests: 8 new generator tests + 18 other additions from this phase) |
+| 30 | No regressions in existing tests | PASS | Full suite: 867 runs, 2898 assertions, 0 failures, 0 errors |
+
+---
+
+## Issues Found
+
+### Minor (non-blocking)
+
+1. **Empty dispatchers array edge case (Check #25)**: If `queue.yml` has `dispatchers: []`, the code sees `found_dispatchers = true` (the key exists) but doesn't add any recurring_schedule since there are no dispatcher hashes to iterate. This means the empty array is left as-is. This is arguably correct behavior (respecting user intent), but worth documenting.
+
+2. **Generator test count**: The plan expected "11 existing + 8 new = 19" but the actual count is 20 (12 existing + 8 new). The plan summary correctly notes 20. The 12th existing test was likely the `test_outputs_next_steps_with_doc_links` test that was already present. No issue -- just a plan estimate mismatch.
+
+### None (blocking)
+
+No blocking issues found.
+
+---
+
+## Risk Assessment
+
+**Risk level: LOW**
+
+- All 867 tests pass with 0 failures
+- RuboCop and Brakeman clean
+- Both new generator steps follow established idempotent patterns
+- Workflow integration is minimal (2 unconditional patcher calls)
+- New files are self-contained with no side effects
+- Test coverage includes all happy paths, skip paths, and edge cases
+- No security concerns (file operations are scoped to destination_root)

data/.vbw-planning/phases/01-generator-steps/PLAN-01-SUMMARY.md

@@ -0,0 +1,61 @@
+# PLAN-01 Summary: procfile-queue-generator-steps
+
+## Status: COMPLETE
+
+## What was done
+
+### Task 1: Add Procfile.dev generator step
+- Added `patch_procfile_dev` public method to `InstallGenerator` (between `configure_recurring_jobs` and `print_next_steps`)
+- Handles 3 cases: create new file, append to existing, skip if already present
+- Added `PROCFILE_JOBS_ENTRY` private constant
+- Updated `print_next_steps` with Procfile.dev info message
+
+### Task 2: Add queue.yml dispatcher step
+- Added `configure_queue_dispatcher` public method to `InstallGenerator` (between `patch_procfile_dev` and `print_next_steps`)
+- Handles 4 cases: missing file, already configured, needs patching, no dispatchers key
+- Added private helpers: `queue_config_has_recurring_schedule?`, `add_recurring_schedule_to_dispatchers!`
+- Added `RECURRING_SCHEDULE_VALUE` and `DEFAULT_DISPATCHER` private constants
+
+### Task 3: Add 8 generator tests
+- 4 Procfile.dev tests: create, append, skip, no-duplicate
+- 4 queue.yml tests: patch dispatchers, skip when configured, skip when missing, add default dispatcher
+- All 20 generator tests pass (12 existing + 8 new)
+
+### Task 4: Add workflow helpers and integration
+- Created `lib/source_monitor/setup/procfile_patcher.rb` (lightweight Pathname-based helper)
+- Created `lib/source_monitor/setup/queue_config_patcher.rb` (YAML parsing with recursive dispatcher search)
+- Modified `lib/source_monitor/setup/workflow.rb`: added 2 new kwargs, wired into `run` after `initializer_patcher` and before devise check
+- Added autoload entries in `lib/source_monitor.rb`
+- Updated all 8 workflow tests with new collaborator spies
+
+### Task 5: Full suite verification
+- 867 test runs, 2898 assertions, 0 failures, 0 errors
+- RuboCop: 376 files, 0 offenses
+- Brakeman: 0 warnings
+
+## Files modified
+- `lib/generators/source_monitor/install/install_generator.rb` -- 2 new public methods, 4 private helpers/constants
+- `test/lib/generators/install_generator_test.rb` -- 8 new tests
+- `lib/source_monitor/setup/procfile_patcher.rb` -- NEW
+- `lib/source_monitor/setup/queue_config_patcher.rb` -- NEW
+- `lib/source_monitor/setup/workflow.rb` -- 2 new kwargs, 2 new patcher calls
+- `test/lib/source_monitor/setup/workflow_test.rb` -- added patcher spies to all tests
+- `lib/source_monitor.rb` -- 2 new autoload entries
+
+## Commits
+1. `af59468` feat(generator): add Procfile.dev patching step to install generator
+2. `29250af` feat(generator): add queue.yml dispatcher step to install generator
+3. `96365b9` feat(generator): add 8 tests for Procfile.dev and queue.yml steps
+4. `4393d17` feat(generator): add workflow helpers and wire patchers into guided install
+
+## Acceptance criteria met
+- Generator creates Procfile.dev with web: + jobs: entries when none exists (REQ-16)
+- Generator appends jobs: entry to existing Procfile.dev without duplicating (REQ-16)
+- Generator skips Procfile.dev when jobs: entry already present (REQ-16 idempotency)
+- Generator patches queue.yml dispatchers with recurring_schedule (REQ-17)
+- Generator skips queue.yml when recurring_schedule already configured (REQ-17 idempotency)
+- Generator handles missing queue.yml gracefully (REQ-17 edge case)
+- Guided workflow runs both patchers after generator step (REQ-18)
+- All existing tests continue to pass (no regressions)
+- 8 new generator tests cover all scenarios
+- RuboCop clean, Brakeman clean

data/.vbw-planning/phases/01-generator-steps/PLAN-01.md

@@ -0,0 +1,380 @@
+---
+phase: 1
+plan: "01"
+title: procfile-queue-generator-steps
+type: execute
+wave: 1
+depends_on: []
+cross_phase_deps: []
+autonomous: true
+effort_override: thorough
+skills_used: []
+files_modified:
+  - lib/generators/source_monitor/install/install_generator.rb
+  - test/lib/generators/install_generator_test.rb
+  - lib/source_monitor/setup/procfile_patcher.rb
+  - lib/source_monitor/setup/queue_config_patcher.rb
+  - lib/source_monitor/setup/workflow.rb
+  - test/lib/source_monitor/setup/workflow_test.rb
+must_haves:
+  truths:
+    - "Running `bin/rails test test/lib/generators/install_generator_test.rb` exits 0 with 0 failures"
+    - "Running `bin/rails test test/lib/source_monitor/setup/workflow_test.rb` exits 0 with 0 failures"
+    - "Running `bin/rubocop lib/generators/source_monitor/install/install_generator.rb lib/source_monitor/setup/procfile_patcher.rb lib/source_monitor/setup/queue_config_patcher.rb lib/source_monitor/setup/workflow.rb` exits 0 with no offenses"
+    - "Running the generator against an empty destination creates a Procfile.dev with both `web:` and `jobs:` lines"
+    - "Running the generator against an existing Procfile.dev that has no `jobs:` line appends one"
+    - "Running the generator against an existing Procfile.dev that already has a `jobs:` line skips with say_status :skip"
+    - "Running the generator against a queue.yml with dispatchers but no recurring_schedule adds it"
+    - "Running the generator against a queue.yml that already has recurring_schedule skips"
+  artifacts:
+    - path: "lib/generators/source_monitor/install/install_generator.rb"
+      provides: "Procfile.dev and queue.yml generator steps"
+      contains: "def patch_procfile_dev"
+    - path: "lib/generators/source_monitor/install/install_generator.rb"
+      provides: "queue.yml dispatcher patching"
+      contains: "def configure_queue_dispatcher"
+    - path: "test/lib/generators/install_generator_test.rb"
+      provides: "Tests for both new generator steps"
+      contains: "test_creates_procfile_dev_when_none_exists"
+    - path: "lib/source_monitor/setup/procfile_patcher.rb"
+      provides: "Workflow helper for Procfile.dev patching"
+      contains: "class ProcfilePatcher"
+    - path: "lib/source_monitor/setup/queue_config_patcher.rb"
+      provides: "Workflow helper for queue.yml patching"
+      contains: "class QueueConfigPatcher"
+    - path: "lib/source_monitor/setup/workflow.rb"
+      provides: "Workflow integration of both new steps"
+      contains: "procfile_patcher"
+  key_links:
+    - from: "install_generator.rb#patch_procfile_dev"
+      to: "REQ-16"
+      via: "Generator patches Procfile.dev with jobs: entry"
+    - from: "install_generator.rb#configure_queue_dispatcher"
+      to: "REQ-17"
+      via: "Generator patches queue config with recurring_schedule"
+    - from: "workflow.rb"
+      to: "REQ-18"
+      via: "Guided workflow integrates both new steps"
+---
+<objective>
+Add two new idempotent steps to the install generator (Procfile.dev patching and queue.yml dispatcher wiring) and integrate both into the guided Setup::Workflow. All steps must follow existing generator conventions: idempotent, skip-if-present, say_status output. REQ-16, REQ-17, REQ-18.
+</objective>
+<context>
+@lib/generators/source_monitor/install/install_generator.rb -- The existing generator with 3 public steps: add_routes_mount, create_initializer, configure_recurring_jobs. New steps must be added as public methods BEFORE print_next_steps (Rails generators execute public methods in definition order). Each step follows the pattern: check-if-already-done -> skip with say_status :skip OR perform action with say_status :create/:append. The recurring jobs step is the best pattern to follow -- it handles both fresh-file and existing-file cases with YAML parsing.
+
+@test/lib/generators/install_generator_test.rb -- 11 existing tests using Rails::Generators::TestCase. Tests use `run_generator` to execute, `assert_file` to check contents, and manually create pre-existing files in `destination_root` to test idempotent skip paths. The WORKER_SUFFIX pattern handles parallel test isolation. New tests should follow the same patterns.
+
+@lib/source_monitor/setup/workflow.rb -- The guided installer. Collaborators are injected via constructor kwargs with defaults. The `run` method calls them in sequence. New patchers should be added AFTER `install_generator.run` (which runs the generator) and BEFORE `verifier.call`. Two new kwargs needed: `procfile_patcher:` and `queue_config_patcher:`.
+
+@lib/source_monitor/setup/install_generator.rb -- Existing wrapper that shells out to `bin/rails generate source_monitor:install`. The generator handles Procfile.dev and queue.yml, so the workflow helpers only need to handle the guided-mode post-generator patching if the generator didn't run (edge case) OR to provide explicit say-status output in the guided flow. However, since the workflow already delegates to the generator, the simplest approach is to add the patching logic directly to the generator (which the workflow already calls) and add lightweight workflow helpers that handle standalone guided-mode usage.
+
+@test/lib/source_monitor/setup/workflow_test.rb -- Uses Spy objects and Minitest::Mock for all collaborators. New patchers need Spy instances in test setup. Existing test "run orchestrates all installers" expects a specific prompter call count -- adding new steps MUST NOT add new prompter calls (the patching is unconditional, no user prompt needed).
+
+@.vbw-planning/phases/01-generator-steps/01-CONTEXT.md -- Phase context with user decisions and acceptance criteria.
+
+**Rationale:** The generator is the primary entry point -- both `bin/rails g source_monitor:install` and the guided workflow funnel through it. Adding the steps directly to the generator ensures both paths are covered. The workflow helpers provide explicit visibility in the guided flow.
+
+**Key design decisions:**
+1. Procfile.dev default content: `web: bin/rails server -p 3000\njobs: bundle exec rake solid_queue:start` (standard Rails 8 Procfile.dev pattern)
+2. The `jobs:` line check should match any line starting with `jobs:` (case-sensitive, anchored to line start)
+3. Queue.yml patching targets any dispatcher block under any environment key and adds `recurring_schedule: config/recurring.yml` if not present
+4. Queue.yml patching must handle both `default: &default` with env aliases AND flat per-environment configs
+5. If queue.yml does not exist, skip with a helpful message (the file is Rails-generated; creating it from scratch could conflict with the host app's queue backend choice)
+</context>
+<tasks>
+<task type="auto">
+  <name>add-procfile-dev-generator-step</name>
+  <files>
+    lib/generators/source_monitor/install/install_generator.rb
+  </files>
+  <action>
+Add a new public method `patch_procfile_dev` to InstallGenerator, placed AFTER `configure_recurring_jobs` and BEFORE `print_next_steps`. This ensures Rails generators execute it in the correct order.
+
+The method must:
+1. Build the Procfile.dev path: `File.join(destination_root, "Procfile.dev")`
+2. If the file exists AND already contains a line matching `/^jobs:/` -> `say_status :skip, "Procfile.dev (jobs entry already present)", :yellow` and return
+3. If the file exists but has no `jobs:` line -> append `\njobs: bundle exec rake solid_queue:start\n` to the file, then `say_status :append, "Procfile.dev", :green`
+4. If the file does not exist -> create it with content:
+   ```
+   web: bin/rails server -p 3000
+   jobs: bundle exec rake solid_queue:start
+   ```
+   Then `say_status :create, "Procfile.dev", :green`
+
+Add a private constant for the jobs line:
+```ruby
+PROCFILE_JOBS_ENTRY = "jobs: bundle exec rake solid_queue:start"
+```
+
+Update `print_next_steps` to mention Procfile.dev:
+```ruby
+say_status :info,
+  "Procfile.dev configured -- run bin/dev to start both web server and Solid Queue workers.",
+  :green
+```
+  </action>
+  <verify>
+Read the modified file and confirm: (a) `patch_procfile_dev` is defined between `configure_recurring_jobs` and `print_next_steps`, (b) it handles all 3 cases (create, append, skip), (c) the PROCFILE_JOBS_ENTRY constant is in the private section.
+  </verify>
+  <done>
+The generator has a `patch_procfile_dev` method that creates, appends to, or skips Procfile.dev depending on current state. The method follows the same idempotent pattern as `configure_recurring_jobs`.
+  </done>
+</task>
+<task type="auto">
+  <name>add-queue-config-generator-step</name>
+  <files>
+    lib/generators/source_monitor/install/install_generator.rb
+  </files>
+  <action>
+Add a new public method `configure_queue_dispatcher` to InstallGenerator, placed AFTER `patch_procfile_dev` and BEFORE `print_next_steps`.
+
+The method must:
+1. Build the queue.yml path: `File.join(destination_root, "config/queue.yml")`
+2. If the file does not exist -> `say_status :skip, "config/queue.yml (file not found -- create it or run rails app:update to generate)", :yellow` and return
+3. Read and parse the YAML with `YAML.safe_load(File.read(path), aliases: true)`
+4. If the parsed content already contains `recurring_schedule` anywhere in any dispatcher entry -> `say_status :skip, "config/queue.yml (recurring_schedule already configured)", :yellow` and return
+5. Otherwise, find dispatcher entries and add `"recurring_schedule" => "config/recurring.yml"` to each one. The structure is:
+   - Environment-based: `{ "default" => { "dispatchers" => [{ "polling_interval" => 1 }] } }`
+   - Or flat: `{ "dispatchers" => [{ "polling_interval" => 1 }] }`
+6. Write back the modified YAML and `say_status :append, "config/queue.yml (added recurring_schedule to dispatchers)", :green`
+
+Add a private helper `queue_config_has_recurring_schedule?(parsed)` that recursively checks if any hash value under `dispatchers` contains `recurring_schedule`.
+
+Add a private helper `add_recurring_schedule_to_dispatchers!(parsed)` that walks the parsed hash and adds `"recurring_schedule" => "config/recurring.yml"` to each dispatcher hash that lacks it.
+
+**Important edge case:** If the queue.yml has no `dispatchers` key at any level, add a default dispatcher section:
+```yaml
+dispatchers:
+  - polling_interval: 1
+    batch_size: 500
+    recurring_schedule: config/recurring.yml
+```
+
+Write back using `YAML.dump` (the file is machine-managed YAML, not hand-formatted like recurring.yml).
+  </action>
+  <verify>
+Read the modified file and confirm: (a) `configure_queue_dispatcher` is defined between `patch_procfile_dev` and `print_next_steps`, (b) it handles all cases (missing file, already configured, needs patching, no dispatchers key), (c) helper methods are private.
+  </verify>
+  <done>
+The generator has a `configure_queue_dispatcher` method that patches queue.yml dispatchers with recurring_schedule. It handles missing files, already-configured files, and files needing patching.
+  </done>
+</task>
+<task type="auto">
+  <name>add-generator-tests</name>
+  <files>
+    test/lib/generators/install_generator_test.rb
+  </files>
+  <action>
+Add the following tests to InstallGeneratorTest, following existing patterns:
+
+**Procfile.dev tests:**
+
+1. `test_creates_procfile_dev_when_none_exists` -- Run generator, assert Procfile.dev exists with both `web:` and `jobs:` lines.
+
+2. `test_appends_jobs_entry_to_existing_procfile_dev` -- Create a Procfile.dev with only `web: bin/rails server -p 3000`, run generator, assert file now contains `jobs:` line AND still contains `web:` line.
+
+3. `test_skips_procfile_dev_when_jobs_entry_already_present` -- Create a Procfile.dev with `web:` and `jobs:` lines, run generator, capture output, assert output contains "skip".
+
+4. `test_does_not_duplicate_jobs_entry_when_rerun` -- Run generator twice, assert Procfile.dev contains exactly 1 line matching `/^jobs:/`.
+
+**Queue config tests:**
+
+5. `test_patches_queue_yml_dispatcher_with_recurring_schedule` -- Create a config/queue.yml with dispatchers section (no recurring_schedule), run generator, assert file contains `recurring_schedule`.
+
+6. `test_skips_queue_yml_when_recurring_schedule_already_present` -- Create a config/queue.yml that already has `recurring_schedule: config/recurring.yml` in the dispatcher, run generator, capture output, assert output contains "skip".
+
+7. `test_skips_queue_yml_when_file_missing` -- Do NOT create config/queue.yml, run generator, capture output, assert output contains "skip" and "not found".
+
+8. `test_adds_default_dispatcher_when_none_exists_in_queue_yml` -- Create a config/queue.yml with queues but no dispatchers section, run generator, assert file now contains both `dispatchers` and `recurring_schedule`.
+
+For queue.yml tests, create realistic YAML content matching the Rails 8 default structure (from host_app_harness.rb):
+```yaml
+default: &default
+  dispatchers:
+    - polling_interval: 1
+      batch_size: 500
+  workers:
+    - queues: "*"
+      threads: 3
+      polling_interval: 0.1
+
+development:
+  <<: *default
+
+test:
+  <<: *default
+
+production:
+  <<: *default
+```
+
+Use `File.join(destination_root, "config")` + `FileUtils.mkdir_p` to create pre-existing files, matching the pattern from `test_merges_into_existing_recurring_yml_with_default_key`.
+  </action>
+  <verify>
+Run `PARALLEL_WORKERS=1 bin/rails test test/lib/generators/install_generator_test.rb` and confirm all tests pass (existing + new). Run `bin/rubocop test/lib/generators/install_generator_test.rb` and confirm no offenses.
+  </verify>
+  <done>
+8 new tests covering all Procfile.dev and queue.yml scenarios. All 19 tests (11 existing + 8 new) pass. RuboCop clean.
+  </done>
+</task>
+<task type="auto">
+  <name>add-workflow-helpers-and-integration</name>
+  <files>
+    lib/source_monitor/setup/procfile_patcher.rb
+    lib/source_monitor/setup/queue_config_patcher.rb
+    lib/source_monitor/setup/workflow.rb
+    test/lib/source_monitor/setup/workflow_test.rb
+  </files>
+  <action>
+**Create `lib/source_monitor/setup/procfile_patcher.rb`:**
+
+Follow the pattern from `install_generator.rb` (the setup wrapper, not the Rails generator). This is a lightweight wrapper that patches Procfile.dev in the host app's root directory. Since the Rails generator already handles this when run via `bin/rails g source_monitor:install`, this helper exists for guided workflow usage where explicit step visibility is desired.
+
+```ruby
+# frozen_string_literal: true
+
+module SourceMonitor
+  module Setup
+    class ProcfilePatcher
+      JOBS_ENTRY = "jobs: bundle exec rake solid_queue:start"
+
+      def initialize(path: "Procfile.dev")
+        @path = Pathname.new(path)
+      end
+
+      def patch
+        if path.exist?
+          content = path.read
+          return false if content.match?(/^jobs:/)
+          path.open("a") { |f| f.puts("", JOBS_ENTRY) }
+        else
+          path.write("web: bin/rails server -p 3000\n#{JOBS_ENTRY}\n")
+        end
+        true
+      end
+
+      private
+
+      attr_reader :path
+    end
+  end
+end
+```
+
+**Create `lib/source_monitor/setup/queue_config_patcher.rb`:**
+
+```ruby
+# frozen_string_literal: true
+
+require "yaml"
+
+module SourceMonitor
+  module Setup
+    class QueueConfigPatcher
+      RECURRING_SCHEDULE_VALUE = "config/recurring.yml"
+
+      def initialize(path: "config/queue.yml")
+        @path = Pathname.new(path)
+      end
+
+      def patch
+        return false unless path.exist?
+
+        parsed = YAML.safe_load(path.read, aliases: true) || {}
+        return false if has_recurring_schedule?(parsed)
+
+        add_recurring_schedule!(parsed)
+        path.write(YAML.dump(parsed))
+        true
+      end
+
+      private
+
+      attr_reader :path
+
+      # (include the same recursive helpers as the generator)
+    end
+  end
+end
+```
+
+**Modify `lib/source_monitor/setup/workflow.rb`:**
+
+1. Add `require_relative "procfile_patcher"` and `require_relative "queue_config_patcher"` at the top (after existing require_relative lines).
+2. Add two new kwargs to `initialize`: `procfile_patcher: ProcfilePatcher.new` and `queue_config_patcher: QueueConfigPatcher.new`.
+3. Store them as instance variables and add to `attr_reader`.
+4. In the `run` method, call both AFTER `initializer_patcher.ensure_navigation_hint` and BEFORE the devise check:
+   ```ruby
+   procfile_patcher.patch
+   queue_config_patcher.patch
+   ```
+   These are unconditional (no user prompt -- maximum hand-holding per user decision).
+
+**Modify `test/lib/source_monitor/setup/workflow_test.rb`:**
+
+1. In the "run orchestrates all installers" test: add `procfile_patcher = Spy.new(true)` and `queue_config_patcher = Spy.new(true)`, pass them to `Workflow.new`, and assert `assert_equal :patch, procfile_patcher.calls.first.first` and `assert_equal :patch, queue_config_patcher.calls.first.first`.
+2. In ALL other tests that construct a Workflow: add `procfile_patcher: Spy.new(true)` and `queue_config_patcher: Spy.new(true)` kwargs to prevent test failures from missing the new required collaborators (they have defaults, but the Spy pattern is used for isolation).
+  </action>
+  <verify>
+Run `PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/setup/workflow_test.rb` and confirm all tests pass. Run `bin/rubocop lib/source_monitor/setup/procfile_patcher.rb lib/source_monitor/setup/queue_config_patcher.rb lib/source_monitor/setup/workflow.rb` and confirm no offenses.
+  </verify>
+  <done>
+Two new workflow helper classes created. Workflow.rb wires both patchers into the guided install flow. All workflow tests pass with the new collaborators injected. RuboCop clean.
+  </done>
+</task>
+<task type="auto">
+  <name>full-suite-verification</name>
+  <files>
+    lib/generators/source_monitor/install/install_generator.rb
+    test/lib/generators/install_generator_test.rb
+    lib/source_monitor/setup/workflow.rb
+    test/lib/source_monitor/setup/workflow_test.rb
+  </files>
+  <action>
+Run the full test suite and linting to confirm no regressions:
+
+1. `PARALLEL_WORKERS=1 bin/rails test test/lib/generators/install_generator_test.rb test/lib/source_monitor/setup/workflow_test.rb` -- all targeted tests pass
+2. `bin/rails test` -- full suite passes with 841+ runs and 0 failures
+3. `bin/rubocop` -- zero offenses
+4. Review the final state of all modified files to confirm:
+   - Generator public methods are in correct order: add_routes_mount, create_initializer, configure_recurring_jobs, patch_procfile_dev, configure_queue_dispatcher, print_next_steps
+   - All new private methods and constants are in the private section
+   - Workflow constructor has all collaborators with sensible defaults
+   - Workflow.run calls patchers in correct position (after generator, before verifier)
+
+If any test failures or RuboCop offenses are found, fix them before completing.
+  </action>
+  <verify>
+`bin/rails test` exits 0 with 841+ runs, 0 failures. `bin/rubocop` exits 0 with 0 offenses. `bin/brakeman --no-pager` exits 0 with 0 warnings.
+  </verify>
+  <done>
+Full test suite passes. RuboCop clean. Brakeman clean. All REQ-16, REQ-17, REQ-18 acceptance criteria met.
+  </done>
+</task>
+</tasks>
+<verification>
+1. `PARALLEL_WORKERS=1 bin/rails test test/lib/generators/install_generator_test.rb` -- 19+ tests pass (11 existing + 8 new)
+2. `PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/setup/workflow_test.rb` -- all workflow tests pass
+3. `bin/rails test` -- 841+ runs, 0 failures
+4. `bin/rubocop` -- 0 offenses
+5. `bin/brakeman --no-pager` -- 0 warnings
+6. `grep -n 'def patch_procfile_dev' lib/generators/source_monitor/install/install_generator.rb` returns a match
+7. `grep -n 'def configure_queue_dispatcher' lib/generators/source_monitor/install/install_generator.rb` returns a match
+8. `grep -n 'procfile_patcher' lib/source_monitor/setup/workflow.rb` returns matches in initialize and run
+9. `grep -n 'queue_config_patcher' lib/source_monitor/setup/workflow.rb` returns matches in initialize and run
+</verification>
+<success_criteria>
+- Generator creates Procfile.dev with web: + jobs: entries when none exists (REQ-16)
+- Generator appends jobs: entry to existing Procfile.dev without duplicating (REQ-16)
+- Generator skips Procfile.dev when jobs: entry already present (REQ-16 idempotency)
+- Generator patches queue.yml dispatchers with recurring_schedule (REQ-17)
+- Generator skips queue.yml when recurring_schedule already configured (REQ-17 idempotency)
+- Generator handles missing queue.yml gracefully (REQ-17 edge case)
+- Guided workflow runs both patchers after generator step (REQ-18)
+- All existing tests continue to pass (no regressions)
+- 8+ new generator tests cover all scenarios
+- RuboCop clean, Brakeman clean
+</success_criteria>
+<output>
+.vbw-planning/phases/01-generator-steps/PLAN-01-SUMMARY.md
+</output>