source_monitor 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8348a9154458260c8b6a3c3dfdeea65e8327b9d7a48dd6c1a2fbe36f9f1bf46
-  data.tar.gz: 2d56c477bc1191f4f505645f9f9f23fceaa1f15d1fd065e5032ac2d40ae3c0d3
+  metadata.gz: ae2bf8e389d7c36d4f7061a13f7f4bb213c8365408f9d0c1fb818ea25b385ff7
+  data.tar.gz: a3b8b537ea6bb06251edbc53a203d9c9e9c20a1d555679a722f00ff62eef9967
 SHA512:
-  metadata.gz: 5f875810a4a5e53aae8ec0609e0ab86a3a97ba8661826de6dcd8cf3abd3091f3e4838d8c301ed0f962da0c5849123f8a1fa7c2614e5341126753a8556a0d6fce
-  data.tar.gz: 50a7007476a9b989af9bfe989bc758a9febbc80478c541995044e1a6fd55fe54736520f643ca00845de57a4d5fc5ccfe1d83dd7994affff7530a3cd692f6fb96
+  metadata.gz: 418df72b1757e7a941e645e171d00f012072c5f2974352851015cc3501adf6a546703a0b3cc38c35de7f1d6034b05c4bf13ce162815640a609612d395a40ac3d
+  data.tar.gz: bef273caaf974979aa4a9e5dce7c4b0043efa47149a0b3f2bcba80874f7b3ff303e5f4672e90ab176d79306a4085ff6ed692f883709a37490e7df279595803e7

data/.claude/agent-memory/vbw-vbw-dev/MEMORY.md

@@ -0,0 +1,34 @@
+# VBW Dev Agent Memory
+
+## Project: source_monitor
+- Rails engine gem for RSS/feed monitoring
+- Ruby 3.4.4, Rails 8.x
+- Test suite: 473 tests via `bin/rails test` (takes ~76 seconds)
+- RuboCop uses `rubocop-rails-omakase` base config
+
+## Key Learnings
+
+### Shell/Bash in zsh
+- `!` in zsh inline scripts causes `command not found` errors. Use `case` statements instead of `if ! ...` patterns.
+- Use `IFS= read -r` when reading filenames from pipes to handle edge cases.
+
+### RuboCop scope vs git scope
+- RuboCop inspects ALL Ruby-like files (Gemfile, Rakefile, .gemspec, .rake, bin/*, config.ru), not just `.rb` files.
+- `git ls-files -- '*.rb'` only matches `.rb` extensions. Plans scoped to `.rb` files may miss RuboCop violations in non-`.rb` Ruby files.
+- `test/tmp/` contains untracked generated Rails app templates. These are NOT git-tracked but RuboCop scans them unless excluded.
+
+### File structure
+- `test/lib/tmp/install_generator/` contains test fixtures (1 tracked file: `config/initializers/source_monitor.rb`)
+- `test/tmp/host_app_template_*` directories are generated test artifacts, not git-tracked
+- `.rubocop.yml` is at project root, inherits from `rubocop-rails-omakase`
+
+### Frozen string literal pragma
+- Completed in commit `5f02db8` -- 113 files modified
+- Added `test/tmp/**/*` to RuboCop exclude list
+
+### RuboCop omakase ruleset details
+- Only 45 cops enabled (out of 775 available)
+- ALL Metrics cops disabled (ClassLength, MethodLength, BlockLength, etc.)
+- After frozen_string_literal fix, codebase had zero remaining violations
+- No `.rubocop.yml` exclusions needed for large files since Metrics cops are off
+- Plan 02 completed with no code changes required

data/.claude/agent-memory/vbw-vbw-lead/MEMORY.md

@@ -0,0 +1,49 @@
+# Lead Agent Memory -- SourceMonitor
+
+## Project Quick Facts
+- Rails 8 engine, Ruby 3.4+, PostgreSQL-only
+- 325 git-tracked Ruby files, 130 test files
+- Coverage baseline: 2328 uncovered lines in config/coverage_baseline.json
+- RuboCop: rubocop-rails-omakase, config at .rubocop.yml
+- CI: .github/workflows/ci.yml (lint, security, test, release-verify, nightly profiling)
+- Large files: FeedFetcher (627), Configuration (655), ImportSessionsController (792)
+
+## Phase 1 Findings
+- 98 git-tracked .rb files missing frozen_string_literal (out of 325)
+- Breakdown: app/(5), lib/(24), test/(43 non-dummy), test/dummy/(22), config/(1), db/migrate/(4)
+- test/tmp/ is NOT git-tracked (generated by install_generator tests) -- exclude from changes
+- test/lib/tmp/install_generator/config/initializers/source_monitor.rb IS tracked and already has pragma
+- bin/rubocop wrapper forces --config .rubocop.yml
+- Phase 1 criterion #3 (10% coverage shrink) not addressed by plans 01/02 -- noted for future
+
+## Phase 2 Planning Insights
+- Coverage baseline.json has 2117 uncovered lines across 105 files (not 2328 -- that was line count)
+- Top 7 files account for ~743 uncovered lines (35% of total)
+- FeedFetcher: 245 uncovered, 12 existing tests, uses VCR+WebMock
+- ItemCreator: 228 uncovered, 8 existing tests, needs mock entries for Atom/JSON branches
+- Configuration: 94 uncovered, 5 existing tests, ~12 nested settings classes
+- Dashboard::Queries: 66 uncovered, 7 existing tests, uses raw SQL + Cache
+- BulkSourceScraper: 66 uncovered, 6 existing tests, ActiveJob test adapter
+- Broadcaster: 48 uncovered, NO existing test file -- needs creation
+- SourcesIndexMetrics: 34 uncovered, 3 existing tests
+- All 5 Phase 2 plans are Wave 1 (no inter-plan dependencies, no file conflicts)
+- Testing main files will indirectly cover supporting files (retry_policy, fetch_error, state, enqueuer, etc.)
+- Broadcaster tests need Turbo::StreamsChannel stubs -- no full Action Cable required
+- 50% coverage target requires ~1059 lines covered; direct plans target ~630, rest from indirect
+
+## Phase 4 Planning Insights
+- 3 plans: conventions-audit (wave 1), item-creator-extraction (wave 1), final-verification (wave 2)
+- SourcesController has dead `fetch`/`retry` methods (leftover from Phase 3 CRUD extraction)
+- ImportSessionsController `new` and `create` are byte-for-byte identical
+- 4 RuboCop violations in db/migrate/20260210204022_add_composite_index_to_log_entries.rb
+- Duplicate test: test/controllers/concerns/ vs test/controllers/source_monitor/concerns/
+- ItemCreator at 601 lines is the last file over 300 lines -- extract to entry_parser + content_extractor
+- Coverage baseline still at 2117 uncovered (not regenerated since Phase 1) -- must regenerate
+- 60% reduction target: at most 847 uncovered lines
+- dashboard/queries.rb (356) and application_helper.rb (346) are near 300 but acceptable as view/query code
+- `bin/update-coverage-baseline` requires `COVERAGE=1 bin/rails test` first
+
+## Bash/Shell Notes
+- zsh on macOS -- `!` in shell conditionals causes `command not found` errors
+- Use `case` statements instead of `if ! grep` patterns in zsh
+- git ls-files piped to while loops works reliably for file enumeration

data/.claude/commands/release.md

@@ -0,0 +1,212 @@
+# Release: PR, CI, Merge, and Gem Build
+
+Orchestrate a full release cycle for the source_monitor gem. This command handles changelog generation, version bumping, PR creation, CI monitoring, auto-merge on success, release tagging, and gem build with push instructions.
+
+## Inputs
+
+- `$ARGUMENTS` -- Optional: version bump description or release notes summary. If empty, derive from commits since last tag.
+
+## Step 1: Git Hygiene
+
+Run these checks. If ANY fail, STOP and report the issue to the user.
+
+1. **Working tree clean**: `git status --porcelain` must be empty. If not, list the dirty files and ask the user whether to commit, stash, or abort.
+2. **On main branch**: `git branch --show-current` must be `main`. If not, ask the user if they want to continue from the current branch or switch.
+3. **Fetch latest**: `git fetch origin main`
+4. **Up to date with remote**: Compare `git rev-parse HEAD` with `git rev-parse origin/main`. If behind, ask the user whether to pull.
+5. **No unpushed commits**: Compare local HEAD with `origin/main`. If ahead, note how many commits are unpushed -- these will be included in the PR.
+
+Report a summary:
+```
+Git Status:
+  Branch: main
+  Clean: yes
+  Synced with origin: yes
+  Unpushed commits: N
+```
+
+## Step 2: Version Check
+
+1. Read `lib/source_monitor/version.rb` to get the current VERSION.
+2. Read the latest git tag with `git tag --sort=-v:refname | head -1`.
+3. If the VERSION matches the latest tag (e.g., both are `0.3.2`), the version hasn't been bumped. Ask the user:
+   - "Current version is X.Y.Z which already has a tag. What should the new version be?"
+   - Offer options: patch (X.Y.Z+1), minor (X.Y+1.0), major (X+1.0.0), or custom.
+   - Update `lib/source_monitor/version.rb` with the new version.
+4. If VERSION is ahead of the latest tag, proceed with the current version.
+
+Store the release version for later steps. Do NOT commit yet -- that happens after the changelog is updated.
+
+## Step 3: Update CHANGELOG.md
+
+The changelog follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format. The file is at `CHANGELOG.md` in the project root.
+
+1. **Gather commit history** since the last tag:
+   ```
+   git log vPREVIOUS..HEAD --oneline --no-merges
+   ```
+2. **Categorize commits** into Keep a Changelog sections based on commit prefixes and content:
+   - `feat:`, `add:` --> **Added**
+   - `fix:`, `bugfix:` --> **Fixed**
+   - `chore:`, `refactor:`, `perf:` --> **Changed**
+   - `docs:` --> **Documentation** (only include if substantive)
+   - `BREAKING:` or `!:` --> **Breaking Changes** (at the top)
+   - `remove:`, `deprecate:` --> **Removed**
+   - Skip merge commits, version bumps, and CI-only changes.
+   - If `$ARGUMENTS` was provided, use it to inform/supplement the categorization.
+
+3. **Draft the changelog entry** and present it to the user for review:
+   ```
+   ## [X.Y.Z] - YYYY-MM-DD
+
+   ### Added
+   - <items>
+
+   ### Fixed
+   - <items>
+
+   ### Changed
+   - <items>
+   ```
+   Each bullet should be a concise, user-facing description (not a raw commit message). Consolidate related commits into single bullets where it makes sense.
+
+4. **Ask the user to approve** the changelog entry. Offer to edit if they want changes.
+
+5. **Write the entry** into `CHANGELOG.md`:
+   - Replace the `## [Unreleased]` section contents with `- No unreleased changes yet.`
+   - Insert the new versioned entry immediately after the `## [Unreleased]` block and before the previous release entry.
+   - Preserve all existing entries below.
+
+## Step 4: Commit Version Bump + Changelog
+
+Once both `lib/source_monitor/version.rb` (if changed) and `CHANGELOG.md` are updated:
+
+1. Stage the changed files:
+   ```
+   git add lib/source_monitor/version.rb CHANGELOG.md
+   ```
+2. Create a single commit:
+   ```
+   chore: bump version to X.Y.Z and update changelog
+   ```
+   If only the changelog changed (version was already bumped), use:
+   ```
+   chore: update changelog for vX.Y.Z release
+   ```
+
+## Step 5: Create Release Branch and PR
+
+1. Create a release branch: `git checkout -b release/vX.Y.Z`
+2. Push the branch: `git push -u origin release/vX.Y.Z`
+3. Generate a PR body from the new CHANGELOG.md entry (use the entry written in Step 3, not raw commits).
+4. Create the PR using `gh pr create`:
+   - Title: `Release vX.Y.Z`
+   - Body format:
+     ```
+     ## Release vX.Y.Z
+
+     <paste the CHANGELOG.md entry content here>
+
+     ### Release Checklist
+     - [x] Version bumped in `lib/source_monitor/version.rb`
+     - [x] CHANGELOG.md updated
+     - [ ] CI passes (lint, security, test, release_verification)
+
+     ---
+     Auto-generated release PR by `/release` command.
+     ```
+   - Base: `main`
+5. Report the PR URL to the user.
+
+## Step 6: Monitor CI Pipeline
+
+Poll the CI status using `gh pr checks <PR_NUMBER> --watch` or repeated `gh pr checks <PR_NUMBER>` calls. The CI has 4 required jobs: `lint`, `security`, `test`, `release_verification`.
+
+1. Tell the user: "Monitoring CI pipeline for PR #N... This typically takes 3-5 minutes."
+2. Poll with `gh pr checks <PR_NUMBER>` every 30 seconds, up to 15 minutes.
+3. After each poll, report progress if any jobs completed.
+
+### If CI PASSES (all checks green):
+
+Continue to Step 7.
+
+### If CI FAILS:
+
+1. Get the failure details: `gh pr checks <PR_NUMBER>` to identify which jobs failed.
+2. For each failed job, fetch the log summary:
+   ```
+   gh run view <RUN_ID> --log-failed | tail -50
+   ```
+3. Present to the user:
+   ```
+   CI Failed on PR #N
+
+   Failed Jobs:
+   - <job_name>: <brief summary of failure>
+
+   Log excerpt:
+   <relevant log lines>
+   ```
+4. Ask the user what to do:
+   - "Fix the issues and re-push" -- Help fix the issues, commit, push, and restart CI monitoring
+   - "Close the PR and abort" -- Close the PR, delete the branch, switch back to main
+   - "Investigate manually" -- Stop and let the user handle it
+
+## Step 7: Auto-Merge PR
+
+Once CI is green:
+
+1. Merge the PR: `gh pr merge <PR_NUMBER> --merge --delete-branch`
+2. Switch back to main and pull: `git checkout main && git pull origin main`
+3. Report: "PR #N merged successfully."
+
+## Step 8: Tag the Release
+
+1. Create an annotated tag:
+   ```
+   git tag -a vX.Y.Z -m "Release vX.Y.Z"
+   ```
+2. Push the tag: `git push origin vX.Y.Z`
+3. Create a GitHub release from the tag:
+   ```
+   gh release create vX.Y.Z --title "vX.Y.Z" --notes "<changelog entry from Step 3>"
+   ```
+4. Report the release URL.
+
+## Step 9: Build the Gem
+
+1. Clean any old gem files: remove any `source_monitor-*.gem` files in the project root.
+2. Build the gem: `gem build source_monitor.gemspec`
+3. Verify the gem was built: check for `source_monitor-X.Y.Z.gem` in the project root.
+4. Show the gem contents summary: `gem spec source_monitor-X.Y.Z.gem | head -30`
+
+## Step 10: Gem Push Instructions
+
+Present the final instructions to the user:
+
+```
+Release vX.Y.Z Complete!
+
+  Git tag:    vX.Y.Z (pushed)
+  GitHub:     <release URL>
+  Gem built:  source_monitor-X.Y.Z.gem
+
+To publish to RubyGems:
+
+  gem push source_monitor-X.Y.Z.gem
+
+You'll be prompted for your RubyGems OTP code (check your authenticator app).
+The gem has `rubygems_mfa_required` enabled, so the OTP is mandatory.
+
+After pushing, verify at:
+  https://rubygems.org/gems/source_monitor/versions/X.Y.Z
+```
+
+Do NOT run `gem push` automatically -- always let the user handle the OTP-protected push manually.
+
+## Error Recovery
+
+- If any step fails unexpectedly, report what happened and where things stand.
+- If a release branch already exists, ask the user whether to reuse or recreate it.
+- If the tag already exists, skip tagging and inform the user.
+- Always leave the user on the `main` branch in a clean state when possible.

data/.claude/skills/sm-host-setup/SKILL.md

@@ -61,7 +61,7 @@ bin/source_monitor install --yes
 gem "source_monitor", "~> 0.3.0"  # in Gemfile
 bundle install
 
-# 2. Run the install generator
+# 2. Run the install generator (mounts engine, creates initializer, configures recurring jobs)
 bin/rails generate source_monitor:install --mount-path=/source_monitor
 
 # 3. Copy engine migrations
@@ -70,7 +70,7 @@ bin/rails railties:install:migrations FROM=source_monitor
 # 4. Apply migrations
 bin/rails db:migrate
 
-# 5. Start background workers
+# 5. Start background workers (recurring jobs configured automatically in config/recurring.yml)
 bin/rails solid_queue:start
 
 # 6. Verify
@@ -86,7 +86,7 @@ gem "source_monitor", github: "dchuk/source_monitor"
 
 ## What the Install Generator Does
 
-The generator (`SourceMonitor::Generators::InstallGenerator`) performs two actions:
+The generator (`SourceMonitor::Generators::InstallGenerator`) performs three actions:
 
 1. **Mounts the engine** in `config/routes.rb`:
    ```ruby
@@ -97,6 +97,9 @@ The generator (`SourceMonitor::Generators::InstallGenerator`) performs two actio
 2. **Creates the initializer** at `config/initializers/source_monitor.rb`:
    Uses the template at `lib/generators/source_monitor/install/templates/source_monitor.rb.tt`. Skips if the file already exists.
 
+3. **Configures recurring jobs** in `config/recurring.yml`:
+   Adds entries for `ScheduleFetchesJob` (every minute), scrape scheduling (every 2 minutes), `ItemCleanupJob` (2am daily), and `LogCleanupJob` (3am daily). If the file doesn't exist, creates it with `default: &default` and environment sections. If it exists, merges entries without overwriting. Skips if SourceMonitor entries are already present.
+
 Re-running the generator is safe and idempotent.
 
 ## Post-Install Configuration
@@ -217,6 +220,7 @@ end
 - [ ] `bundle install` completed
 - [ ] Install generator ran (`bin/rails generate source_monitor:install`)
 - [ ] Engine migrations copied and applied
+- [ ] Recurring jobs configured in `config/recurring.yml`
 - [ ] Solid Queue workers started
 - [ ] Authentication hooks configured in initializer
 - [ ] `bin/source_monitor verify` passes

data/.claude/skills/sm-host-setup/reference/setup-checklist.md

@@ -39,6 +39,7 @@ bin/rails generate source_monitor:install --mount-path=/source_monitor
 Verify after running:
 - [ ] `config/routes.rb` contains `mount SourceMonitor::Engine, at: "/source_monitor"`
 - [ ] `config/initializers/source_monitor.rb` exists
+- [ ] `config/recurring.yml` contains SourceMonitor recurring job entries
 
 ## Phase 4: Database Setup
 
@@ -75,6 +76,8 @@ end
 
 ## Phase 6: Configure Workers
 
+The install generator automatically configures recurring jobs in `config/recurring.yml` (fetch scheduling, scrape scheduling, item cleanup, log cleanup). These run automatically with `bin/dev` or `bin/jobs`.
+
 Ensure `config/solid_queue.yml` (or equivalent) includes the SourceMonitor queues:
 
 ```yaml

data/.claude/skills/sm-job/SKILL.md

@@ -159,15 +159,16 @@ SourceMonitor.queue_name(:fetch)  # => "source_monitor_fetch"
 
 ### Recurring Jobs
 
-ScheduleFetchesJob is typically configured as a recurring job in `config/recurring.yml`:
-
-```yaml
-production:
-  schedule_fetches:
-    class: SourceMonitor::ScheduleFetchesJob
-    schedule: every 1 minute
-    queue: source_monitor_fetch
-```
+The install generator (`bin/rails generate source_monitor:install`) automatically configures these recurring jobs in `config/recurring.yml`:
+
+| Job | Schedule |
+|-----|----------|
+| `SourceMonitor::ScheduleFetchesJob` | every minute |
+| `SourceMonitor::Scraping::Scheduler.run` | every 2 minutes |
+| `SourceMonitor::ItemCleanupJob` | at 2am every day |
+| `SourceMonitor::LogCleanupJob` | at 3am every day |
+
+These run automatically with `bin/dev` or `bin/jobs`. If you need to customize, edit `config/recurring.yml` directly.
 
 ## Retry Policies
 

data/.gitignore

@@ -15,3 +15,7 @@
 /app/assets/builds/*
 !/app/assets/builds/.keep
 !/app/assets/builds/source_monitor/
+.vbw-planning/.cost-ledger.json
+.vbw-planning/.notification-log.jsonl
+.vbw-planning/.session-log.jsonl
+.vbw-planning/.hook-errors.log

data/AGENTS.md

@@ -1,13 +1,13 @@
 # Repository Guidelines
 
-refer to ./ai/project_overview.md for full scope of this project
+Refer to `CLAUDE.md` for project conventions and skills catalog.
 
-use rbenv for all ruby and bundler/gem commands, not the system ruby
+Use rbenv for all ruby and bundler/gem commands, not the system ruby.
 
 ## Contribution Workflow
 
 - Treat the engine like any external contributor would: no direct commits to `main`.
-- Before writing code, branch off the latest `origin/main` (use a descriptive `feature/` or `bugfix/` prefix) and open a draft PR on `github.com/dchuk/source_monitor` referencing the active `.ai/tasks.md` slice.
+- Before writing code, branch off the latest `origin/main` (use a descriptive `feature/` or `bugfix/` prefix) and open a draft PR on `github.com/dchuk/source_monitor`.
 - Push early and often to that branch so history stays visible; keep commits scoped and rebases local to your branch only.
 - Move the PR out of draft once tests pass and the slice is ready for review; request at least one review and wait for all CI jobs (lint, security, Rails tests + diff coverage) to succeed before merging.
 - The `test` job enforces diff coverage via `bin/check-diff-coverage`; if legitimate gaps remain after new code paths, refresh `config/coverage_baseline.json` by running `bin/test-coverage` followed by `bin/update-coverage-baseline` on the updated branch and commit the regenerated baseline.
@@ -59,7 +59,7 @@ Run `bin/setup` to install gems, prepare the dummy database, and compile Tailwin
 
 ## Coding Style & Naming Conventions
 
-Use two-space indentation and Ruby 3.3 syntax. Keep engine classes under the `SourceMonitor::` namespace; new modules should mirror their directory, e.g., `lib/source_monitor/fetching/pipeline.rb`. Favor service objects ending in `Service`, jobs ending in `Job`, and background channels ending in `Channel`. Rails defaults handle formatting, but run `bundle exec rubocop` (configured via `.rubocop.yml`) before opening a PR. For views, stick with ERB and Tailwind utility classes.
+Use two-space indentation and Ruby 4.0+ syntax. Keep engine classes under the `SourceMonitor::` namespace; new modules should mirror their directory, e.g., `lib/source_monitor/fetching/pipeline.rb`. Favor service objects ending in `Service`, jobs ending in `Job`, and background channels ending in `Channel`. Rails defaults handle formatting, but run `bundle exec rubocop` (configured via `.rubocop.yml`) before opening a PR. For views, stick with ERB and Tailwind utility classes.
 
 ## Testing Guidelines
 
@@ -67,66 +67,29 @@ MiniTest drives coverage (`test/models`, `test/controllers`, `test/system`). Nam
 
 ## Commit & Pull Request Guidelines
 
-Adopt imperative commit messages in the format `scope: action`, e.g., `sources: enforce URL normalization`. Group unrelated work into separate commits. PRs should describe context, summarise the slice delivered, list validation steps (`bin/rails test`, manual fetch run), and reference roadmap items from `.ai/tasks.md`. Include screenshots or console output when altering UI or background jobs. Request at least one review and ensure CI completes before merge.
+Adopt imperative commit messages in the format `scope: action`, e.g., `sources: enforce URL normalization`. Group unrelated work into separate commits. PRs should describe context, summarise the slice delivered, and list validation steps (`bin/rails test`, manual fetch run). Include screenshots or console output when altering UI or background jobs. Request at least one review and ensure CI completes before merge.
 
 ## Security & Configuration Tips
 
 Store secrets (API keys, webhook tokens) in `config/credentials/` and never commit plain-text values. When adding HTTP endpoints or webhooks, default to Solid Queue middleware for retries and respect the allowlist in `config/source_monitor.yml`. Document new environment variables in `config/application.yml.sample` and call out any migrations that impact host apps.
 
-# Clean coding guidelines
+## Clean Coding Principles
 
-Object Orientated Design: You should write code that embraces change. Here’s how…
+- **SRP**: Classes and methods should have a single responsibility.
+- **DRY**: Avoid duplication; changes should only need one edit.
+- **Depend on behaviour, not data**: Wrap instance variables in methods (`attr_reader`); use Struct for data structures.
+- **Minimise dependencies**: Use dependency injection, encapsulate external messages, prefer hash arguments.
+- **Depend on things that change less often than you do.**
 
-SRP: A class should do the smallest possible useful thing; it should have a single responsibility. A class that has more than one responsibility is difficult to reuse. SRP requires that a class be cohesive, that everything the class does be highly related to its purpose. A class that is easy to reuse will make the application easier to change.
+## Claude Code Skills
 
-Methods, like classes, should have a single responsibility. All of the same reasons apply, having just one responsibility makes them easy to change and easy to reuse.
+SourceMonitor ships 14 engine-specific Claude Code skills (`sm-*` prefix) covering the domain model, configuration DSL, pipeline stages, testing conventions, and more. Skills are distributed with the gem and installed into `.claude/skills/` via rake tasks:
 
-DRY: DRY code tolerates change because any change in behaviour can be made by changing code in just one place.
+```bash
+bin/rails source_monitor:skills:install        # Consumer skills (host app integration)
+bin/rails source_monitor:skills:contributor     # Contributor skills (engine development)
+bin/rails source_monitor:skills:all            # All skills
+bin/rails source_monitor:skills:remove         # Remove all sm-* skills
+```
 
-Depend on behaviour not data:
-
-Hide instance variables by wrapping them in a method, an attr_reader. The method changes a variable from data ( which is referenced all over) to behaviour (which is defined once). This means if you need to adjust the data you only have to make a change in one place.
-
-Hide data structures using the Struct class.
-
-Minimise Dependencies: An object depends on another object if, when one object changes, the other might be forced to change in turn. An object has a dependency when it knows:
-
-The name of another class.
-
-The name of a message that it intends to send to someone other than self.
-
-The arguments that a message requires.
-
-The order of those arguments.
-
-Dependency Injection: Addresses the first dependency. It decouples two objects by moving the creation of object_A outside of object_B eg:
-
-object_A.new(1,2,object_B.new)
-
-Encapsulation: Addresses the second dependency. Create wrapper methods so that external messages are isolated in one place. The wrapper method is called throughout the class, rather than sending messages externally.
-
-Use hashes for initialization arguments: this addresses the final dependencies.
-
-Depend on things that change less often than you do
-
-## Agent Notes (2025-10-08)
-
-- Finished roadmap section 05.03 (structured fetch error handling). Added `SourceMonitor::Fetching::FetchError` hierarchy, expanded `FeedFetcher` error handling, and ensured instrumentation payloads include success/error context.
-- Fetch attempts now always create `FetchLog` records and update `Source` failure state; added MiniTest coverage for timeout, HTTP 404, and malformed feed scenarios.
-- Relevant tests: `bundle exec rails test test/lib/source_monitor/fetching/feed_fetcher_test.rb` and full suite via `bundle exec rails test` (both passing).
-- Next roadmap item is 05.04 (not started). Untracked tmp dir `test/lib/tmp` can be safely ignored if it reappears.
-
-## Agent Notes (2025-10-09)
-
-- Introduced `SourceMonitor::Scrapers::Base`, establishing the scraper adapter contract and Result object. Subclasses merge default, source, and invocation settings (HashWithIndifferentAccess) and must return a Result with status/html/content/metadata. Use `SourceMonitor::Scrapers::Base.call(item:, source:, settings:, http:)` to execute adapters.
-- Added Readability scraper adapter leveraging SourceMonitor::HTTP, Nokolexbor, and ruby-readability. Supports override selectors via `scrape_settings[:selectors]`, records extraction metadata including strategy and inferred status, and returns structured failure results on HTTP errors.
-- Extracted scraper HTTP fetching and parsing into dedicated collaborators (`SourceMonitor::Scrapers::Fetchers::HttpFetcher` and `SourceMonitor::Scrapers::Parsers::ReadabilityParser`). The adapter now orchestrates these services, simplifying future parser additions while keeping failure metadata consistent.
-- Added Readability scraper adapter leveraging SourceMonitor::HTTP, Nokolexbor, and ruby-readability. Supports override selectors via `scrape_settings[:selectors]`, records extraction metadata including strategy and inferred status, and returns structured failure results on HTTP errors.
-- Phase 07.03 complete: introduced `SourceMonitor::ItemContent` table with one-to-one association, virtual accessors on `Item`, and migration that backfills existing scraped data while dropping legacy columns. Clearing both fields now removes the content row. Run `bundle exec rails db:migrate` in host apps after upgrading.
-- Phase 07.04 complete: added `SourceMonitor::Scraping::ItemScraper` service with log recording, manual scrape controls in the item admin, and a dedicated scraping configuration section on the source form. Item show page now highlights content comparisons, status badges, and recent scrape errors. System coverage updated to exercise the manual scraping flow.
-- Phase 08.02 complete: created `SourceMonitor::FetchFeedJob`, introduced `SourceMonitor::Fetching::FetchRunner` with Postgres advisory locking, and added a temporary `ScrapeItemJob` stub so new items from auto-scrape sources are queued with `scrape_status` set to `pending`. Manual fetch UI now reuses the runner, and tests cover job retry behavior plus follow-up scraping enqueue (`bundle exec rails test test/lib/source_monitor/fetching/fetch_runner_test.rb`, `bundle exec rails test test/jobs/source_monitor/fetch_feed_job_test.rb`, and `bundle exec rails test test/lib/source_monitor/fetching/feed_fetcher_test.rb`).
-- Phase 08.03 complete: implemented `SourceMonitor::Scraping::Enqueuer` with deduplication/auto-scrape guards, promoted `SourceMonitor::ScrapeItemJob` to execute `ItemScraper`, and updated the manual item view to enqueue jobs instead of running scrapes inline. Added unit coverage for the enqueuer/job plus refreshed the manual scrape system test (`bundle exec rails test test/lib/source_monitor/scraping/enqueuer_test.rb test/jobs/source_monitor/scrape_item_job_test.rb test/system/items_test.rb test/lib/source_monitor/fetching/fetch_runner_test.rb`).
-- Phase 08.04 complete: manual "Fetch Now" now queues `FetchFeedJob` via `FetchRunner.enqueue`, dashboard shows live queue metrics from `SourceMonitor::Jobs::Visibility`, and optional Mission Control link appears when configured. System tests updated to assert job enqueues (`test/system/sources_test.rb`, `test/system/items_test.rb`, `test/system/dashboard_test.rb`); run `bundle exec rails test test/system` after UI tweaks.
-- Install generator now also creates `config/initializers/source_monitor.rb` with documented defaults for queue settings, metrics, and Mission Control hooks. Update the initializer if future configuration options are added.
-- `SourceMonitor.mission_control_dashboard_path` now validates that the configured path exists before rendering a dashboard link, preventing 404s when Mission Control isn't mounted yet. Template comments outline how to mount the engine when enabling it.
-- `test/dummy/bin/dev` now runs the Rails server with `BUNDLE_GEMFILE` pointing at the dummy app, so dummy-only gems (like mission_control-jobs) load correctly while the Tailwind watcher still uses the engine's Gemfile.
+See `CLAUDE.md` for the full skills catalog and usage details.

data/CHANGELOG.md

@@ -15,6 +15,28 @@ All notable changes to this project are documented below. The format follows [Ke
 
 - No unreleased changes yet.
 
+## [0.3.3] - 2026-02-11
+
+### Fixed
+
+- Added missing `recurring.yml` configuration to the install generator so host apps get Solid Queue recurring job config on install.
+- Fixed YAML alias parsing in install generator so merging into existing `recurring.yml` files with `<<: *default` anchors works correctly.
+
+### Changed
+
+- Updated `sm-host-setup` and `sm-job` skills to reflect latest conventions.
+- Updated setup documentation with current installation steps.
+
+## [0.3.2] - 2026-02-10
+
+### Fixed
+
+- Updated README, AGENTS.md, CONTRIBUTING.md, and docs/ to reflect v0.3.1 changes (Ruby 4.0+, gem version refs, skills system documentation).
+- Replaced stale `.ai/` references with `CLAUDE.md` and `AGENTS.md` across all docs.
+- Corrected `SOURCE_MONITOR_TEST_WORKERS` env var to `PARALLEL_WORKERS` in CONTRIBUTING.md.
+- Removed historical agent development notes from AGENTS.md.
+- Condensed verbose clean coding guidelines into concise bullet summary.
+
 ## [0.3.1] - 2026-02-10
 
 ### Added

data/CLAUDE.md

@@ -45,7 +45,7 @@ Run /vbw:help for all commands.
 
 | Layer | Technology |
 |-------|------------|
-| Ruby | 3.4+ |
+| Ruby | 4.0+ |
 | Rails | 8.x |
 | Testing | Minitest (no fixtures -- uses factory helpers + WebMock/VCR) |
 | Authorization | Host app responsibility (mountable engine) |

data/CONTRIBUTING.md

@@ -4,7 +4,7 @@ This project ships each roadmap slice behind a fast, reliable test loop. The not
 
 ## Test Suite Expectations
 
-- **Fast feedback:** run `bundle exec rake app:test:smoke` for unit, helper, and job coverage before pushing. Use `SOURCE_MONITOR_TEST_WORKERS=1` locally when profiling failures for determinism.
+- **Fast feedback:** run `bundle exec rake app:test:smoke` for unit, helper, and job coverage before pushing. Use `PARALLEL_WORKERS=1` locally when profiling failures for determinism.
 - **Full validation:** continue to run `bundle exec rails test` (or `bin/test-coverage` in CI) before marking a slice ready for review.
 - **Background jobs:** the default adapter is `:test`. Switch to inline execution only for the precise block that needs it via `with_inline_jobs { ... }`; never flip the global adapter.
 - **Database usage:** prefer transactional fixtures over manual `delete_all`. Reach for `setup_once` (TestProf’s `before_all`) when immutable data can be shared safely across examples.
@@ -13,16 +13,16 @@ This project ships each roadmap slice behind a fast, reliable test loop. The not
 ## Performance Profiling
 
 - **Local commands:**
-  - `TAG_PROF=type SOURCE_MONITOR_TEST_WORKERS=1 bundle exec rails test`
-  - `EVENT_PROF=sql.active_record SOURCE_MONITOR_TEST_WORKERS=1 bundle exec rails test`
-  - `TEST_STACK_PROF=1 SOURCE_MONITOR_TEST_WORKERS=1 bundle exec rails test test/integration`
+  - `TAG_PROF=type PARALLEL_WORKERS=1 bundle exec rails test`
+  - `EVENT_PROF=sql.active_record PARALLEL_WORKERS=1 bundle exec rails test`
+  - `TEST_STACK_PROF=1 PARALLEL_WORKERS=1 bundle exec rails test test/integration`
 - **CI automation:** a scheduled `profiling` workflow runs the commands above nightly, archives `tmp/test_prof`, and applies guardrails via `bin/check-test-prof-metrics` (suite ≤ 80s, integration ≤ 35s, DB time ≤ 5s). Failures block the job so regressions surface quickly.
 
 ## Code Review Checklist
 
 Before approval, verify that the changes:
 
-1. Avoid unnecessary database persistence (`build_stubbed`/test doubles over `.create` when assertions allow).
+1. Avoid unnecessary database persistence (test doubles over `.create` when assertions allow).
 2. Share heavy setup with `setup_once` or helper memoization instead of per-test rebuilds.
 3. Scope inline job execution to `with_inline_jobs { ... }` blocks—no suite-wide adapter swaps.
 4. Keep new or modified system specs lean, relying on lower-level coverage when UI is not essential.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    source_monitor (0.3.1)
+    source_monitor (0.3.3)
       cssbundling-rails (~> 1.4)
       faraday (~> 2.9)
       faraday-follow_redirects (~> 0.4)