source_monitor 0.11.1 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f700fdb3be3b317a91a05f04e32cd285fcb13d1acb39d3a79fb5da1da4781a0
-  data.tar.gz: 5304f346c91cb7435663e2d8cef0f12743c334d1218cf2f6fb830df127a404ba
+  metadata.gz: d460ce01dd1453813fe455bde15c1b8fc2eb6954ca20ff4bf7599b55480c98d5
+  data.tar.gz: 16e5903aa483ba06cc092b08a8148edc3050a3830cd4dda42abfbca3d1cab25f
 SHA512:
-  metadata.gz: 9689c88dc3dd352c86d91dc2e48a1555e9f2fd8cdde11ba20288532ae3287994fd844ab07dbda5e63fc4435dca9f5900008efb9fbf4d394d5dcfc2b139e5bbb1
-  data.tar.gz: 99850f35657ee948728143e17f07c69ebe4591a41612cbe3ae637113d1ec2a5f7c569158a350eaf6c5f3f05e0024103a013f3ec479210f0efa291db8841b399c
+  metadata.gz: 20a4b8a80f4a861d8ea7e543e4cd90e31709bf9a4d504cf40059375fa439f5d5dd3803bb6ad133d50c75dfe50ee42cfd0913cae66ea41422df1473710493bb5c
+  data.tar.gz: ae82ac7575c31e93839bbe48c309a71f57cc1ac91ecd67a4f7690d978be459459abcdafb554fad36e98ff0cdcc424133f6a77f4f756fdfbaf6e11b22c8c9ce27

data/.claude/commands/rails-audit.md

@@ -0,0 +1,77 @@
+# Rails Best Practices Audit
+
+Perform a comprehensive Rails best practices audit of the entire codebase. Use the rails-specific skills and agents to identify opportunities to simplify, refactor, and align with Rails conventions ("the Rails Way").
+
+## Usage
+
+```
+/rails-audit                    # Full audit of entire codebase
+/rails-audit models only        # Scope to specific layer
+/rails-audit --changed-only     # Only audit changed files (git diff)
+```
+
+## Instructions
+
+Launch a team of agents in parallel to explore the codebase across multiple dimensions. Each agent should use the relevant rails skills (see CLAUDE.md Skill Catalog) and search the web for best practices when skills are insufficient.
+
+### Agent 1: Models & Concerns (rails-review agent)
+- Fat-model anti-patterns: models doing too much vs. missing scopes/validations
+- Concern hygiene: single-purpose? overused? should any be model methods?
+- Business logic placement: logic in controllers/services that belongs in models
+- ActiveRecord anti-patterns: raw SQL where scopes suffice, missing `includes`/`preload`
+- Missing validations, unnecessary callbacks, state management patterns
+- Check for state-as-records pattern compliance (booleans vs. state records)
+
+### Agent 2: Controllers & Routes (rails-review agent)
+- Everything-is-CRUD compliance: custom actions that should be separate resources
+- Business logic leaking into controllers
+- Strong parameters, before_actions, proper response handling
+- RESTful route compliance (no custom `member`/`collection` verbs)
+- Controller concerns: well-focused or kitchen-sink?
+
+### Agent 3: Services, Jobs & Pipeline (rails-review agent)
+- Service objects: single-responsibility, Result pattern compliance
+- Job shallowness: jobs should only deserialize + delegate, no business logic
+- Service objects that should be model methods or concerns (< 3 models = model method)
+- Pipeline stages: consolidation opportunities, error handling
+- Query objects: are complex queries properly extracted?
+
+### Agent 4: Views, Frontend & Hotwire (rails-review agent)
+- Turbo Frame/Stream best practices
+- Stimulus controllers: small, focused, one behavior each
+- View logic that should be presenters (SimpleDelegator) or ViewComponents
+- Tailwind CSS patterns: repeated utility groups that should be components
+- Partial organization and reuse
+
+### Agent 5: Testing & Quality (rails-review agent)
+- Test DRYness: repeated setup that should be helpers
+- Factory helper consistency (`create_source!`, etc.)
+- Testing behavior vs. implementation
+- Missing coverage patterns (validations, scopes, edge cases)
+- Test isolation and parallel-safety
+
+## Output
+
+Produce a markdown file at `RAILS_AUDIT.md` in the project root with:
+
+```markdown
+# Rails Best Practices Audit — [date]
+
+## Executive Summary
+[High-level findings count by severity]
+
+## Findings by Category
+
+### Category Name
+#### Finding Title
+- **Severity:** high/medium/low
+- **File(s):** `path/to/file.rb:line_number`
+- **Current:** [what it does now]
+- **Recommended:** [what it should do, with code example if helpful]
+- **Rationale:** [why this is better, link to Rails convention]
+- **Effort:** quick (< 30 min) / short (< 2 hrs) / medium (< 1 day) / large (> 1 day)
+```
+
+Sort findings within each category by severity (high first), then by effort (quick first).
+
+$ARGUMENTS

data/.claude/commands/release.md

@@ -26,7 +26,8 @@ These are real issues encountered in previous releases. Each step below accounts
 9. **ESLint browser globals**: Any JS file using browser APIs (MutationObserver, requestAnimationFrame, cancelAnimationFrame, IntersectionObserver, etc.) MUST declare them with a `/* global ... */` comment at the top. ESLint's `no-undef` rule in CI will reject them otherwise.
 10. **Diff coverage rescue paths**: Every `rescue`/fallback/error handling branch in changed source code needs test coverage. Common blind spots: `rescue StandardError => e` logging, `rescue URI::InvalidURIError` returning nil, fallback `false` returns. Write targeted tests for these BEFORE creating the release commit.
 11. **Zsh glob nomatch**: Commands like `rm -f *.gem` fail in zsh when no files match. Always use `rm -f *.gem 2>/dev/null || true` or check existence first with `ls`.
-12. **Documentation drift**: Features, config options, and behavioral changes often land across milestone work without corresponding doc updates. The Documentation Audit step (Step 4) catches this -- check `docs/`, `README.md`, skill reference files (`sm-*/reference/`), and the initializer template against the actual source code. In v0.9.x, 14 files needed updates that would have been missed without this step.
+12. **Documentation drift**: Features, config options, and behavioral changes often land across milestone work without corresponding doc updates. Step 4 now spawns agents to both audit AND fix all stale docs automatically. In v0.9.x, 14 files needed updates; in v0.12.0, 7 files were stale (README version refs, docs/setup version refs, docs/upgrade missing section, 4 skill references). Always assume docs are stale.
+13. **test-coverage script health_suite**: The `bin/test-coverage` script runs a second "health_suite" pass with specific test files. If you add new test files for health/service classes, you MUST add them to the `TARGETED_TESTS` array in `bin/test-coverage` or SimpleCov's merged report will show 0% coverage for those files even though the main suite covers them. In v0.12.0, `source_health_check_orchestrator_test.rb` showed 31% coverage on CI despite 100% locally because it wasn't in the health_suite list.
 
 ## Step 1: Git Hygiene
 
@@ -114,54 +115,76 @@ The changelog follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) f
    - Insert the new versioned entry immediately after the `## [Unreleased]` block and before the previous release entry.
    - Preserve all existing entries below.
 
-## Step 4: Documentation Audit
+## Step 4: Documentation Update (Mandatory)
 
-Verify that all project documentation reflects the current state of the codebase. Changes made since the last release (or during milestone work) may have introduced features, configuration options, bug fixes, or behavioral changes that need to be documented.
+**This step is NON-OPTIONAL.** Every release MUST update all documentation to reflect the current codebase state. Documentation drift is the #1 blind spot in milestone-based work — in v0.9.x, 14 files needed updates; in v0.12.0, 7 files were stale. Always assume docs are stale and verify.
 
-1. **Gather what changed** since the last release tag:
-   ```
-   git diff vPREVIOUS..HEAD --name-only -- lib/ app/ config/
-   ```
-   This shows which source files changed. Use this to identify features/fixes that may need documentation.
-
-2. **Check these documentation files against the changes:**
-
-   | File | What to verify |
-   |------|---------------|
-   | `CHANGELOG.md` | Has an `[Unreleased]` or versioned entry covering all user-facing changes |
-   | `README.md` | Version references match, feature descriptions current, gem version in install instructions |
-   | `docs/configuration.md` | All config options documented, new settings included, env vars listed |
-   | `docs/deployment.md` | Worker/queue descriptions match current queues and job assignments |
-   | `docs/troubleshooting.md` | Covers known failure modes from recent changes |
-   | `docs/upgrade.md` | Has upgrade section for this version with action items |
-   | `docs/setup.md` | Setup steps still accurate |
-
-3. **Check skills reference files** (engine-specific documentation for Claude Code):
-
-   | Skill Reference | What to verify |
-   |----------------|---------------|
-   | `sm-configure/reference/configuration-reference.md` | All config settings and their defaults |
-   | `sm-configuration-setting/reference/settings-catalog.md` | Settings catalog with types, defaults, descriptions |
-   | `sm-job/reference/job-conventions.md` | Queue names, job assignments, concurrency defaults |
-   | `sm-pipeline-stage/reference/completion-handlers.md` | Pipeline handler code matches actual implementation |
-   | `sm-upgrade/reference/version-history.md` | Version transition notes for the new release |
-   | `sm-host-setup/reference/initializer-template.md` | Initializer template shows all configurable options |
-
-4. **For each file that is stale or missing coverage**:
-   - Update it to reflect the current codebase behavior.
-   - For config docs: read the actual settings classes in `lib/source_monitor/configuration/` to verify defaults.
-   - For job docs: read `app/jobs/source_monitor/` to verify queue assignments.
-   - For upgrade notes: summarize breaking changes, new config, and action items.
-
-5. **If all documentation is already up to date**, report:
-   ```
-   Documentation Audit: All files current. No updates needed.
-   ```
-   If updates were made, report:
-   ```
-   Documentation Audit: Updated N files.
-     - <file>: <what was updated>
-   ```
+### 4a. Gather what changed
+
+```
+git log vPREVIOUS..HEAD --oneline --no-merges
+git diff vPREVIOUS..HEAD --name-only -- lib/ app/ config/
+```
+
+Summarize the key changes: new classes, extracted services, new components, new model methods, new migrations, config changes, breaking changes.
+
+### 4b. Spawn Explore agent to audit all docs
+
+Spawn an Explore agent (subagent_type: "Explore", thoroughness: "very thorough") to compare documentation against the actual source code. The agent MUST check ALL of these files:
+
+**Project docs:**
+
+| File | What to verify |
+|------|---------------|
+| `README.md` | Version references match new version, feature descriptions current, install instructions accurate |
+| `docs/setup.md` | Version references match, setup steps accurate |
+| `docs/upgrade.md` | Has upgrade section for THIS version with migrations, action items, breaking changes |
+| `docs/configuration.md` | All config options documented, defaults match source code |
+| `docs/deployment.md` | Worker/queue descriptions match current queues and job assignments |
+| `docs/troubleshooting.md` | Covers known failure modes from recent changes |
+
+**Skills reference files** (engine-specific documentation for Claude Code):
+
+| Skill Reference | What to verify |
+|----------------|---------------|
+| `sm-configure/reference/configuration-reference.md` | All config settings and their defaults |
+| `sm-configuration-setting/reference/settings-catalog.md` | Settings catalog with types, defaults, descriptions |
+| `sm-job/reference/job-conventions.md` | Queue names, job assignments, concurrency defaults, service class delegation |
+| `sm-pipeline-stage/reference/completion-handlers.md` | Pipeline handler code matches actual implementation |
+| `sm-upgrade/reference/version-history.md` | Version transition notes for the new release |
+| `sm-host-setup/reference/initializer-template.md` | Initializer template shows all configurable options |
+| `sm-architecture/reference/module-map.md` | All modules, classes, components, presenters listed |
+| `sm-domain-model/reference/model-graph.md` | All model methods, validations, scopes, associations |
+
+The Explore agent should output a structured report: files that are current, files that need updates (with specific stale content), and what each update should contain.
+
+### 4c. Spawn Docs agent to fix all stale files
+
+Based on the Explore agent's report, spawn a Docs agent (subagent_type: "vbw:vbw-docs", model: "sonnet") to update ALL stale files. The Docs agent MUST:
+
+- Read each file before editing (targeted edits, not full rewrites)
+- Update version references to the new release version
+- Add upgrade section for this version (migrations, action items, breaking changes)
+- Update module maps, model graphs, job conventions to reflect current source code
+- Add entries for any new classes, components, concerns, or model methods
+
+### 4d. Verify and report
+
+After the Docs agent completes, verify all files were updated:
+```
+git diff --name-only  # Should show the updated doc files
+```
+
+Report:
+```
+Documentation Update: Updated N files.
+  - <file>: <what was updated>
+```
+
+If the Explore agent found 0 stale files, report:
+```
+Documentation Update: All files current. No updates needed.
+```
 
 Do NOT commit documentation updates separately -- they will be included in the single release commit in Step 7.
 

data/.claude/skills/sm-architecture/reference/module-map.md

@@ -79,6 +79,7 @@ Complete module tree with each module's responsibility.
 |--------|------|----------------|
 | `EntryNormalizer` | `import_sessions/entry_normalizer.rb` | Normalize OPML entries to standard format |
 | `HealthCheckBroadcaster` | `import_sessions/health_check_broadcaster.rb` | Broadcast health check progress via Turbo Streams |
+| `HealthCheckUpdater` | `import_sessions/health_check_updater.rb` | Service delegated to by ImportSessionHealthCheckJob; runs checks and broadcasts |
 
 ### Jobs
 
@@ -104,6 +105,7 @@ Complete module tree with each module's responsibility.
 |--------|------|----------------|
 | `Sanitizable` | `models/sanitizable.rb` | `sanitizes_string_attributes`, `sanitizes_hash_attributes` class methods |
 | `UrlNormalizable` | `models/url_normalizable.rb` | `normalizes_urls`, `validates_url_format` class methods |
+| `SetSource` | `models/set_source.rb` | Controller concern: resolves and assigns `@source` from params before actions |
 
 ### Scrapers (Scraper Adapters)
 
@@ -123,6 +125,7 @@ Complete module tree with each module's responsibility.
 | `ItemScraper` | `scraping/item_scraper.rb` | Scrape a single item |
 | `ItemScraper::AdapterResolver` | `scraping/item_scraper/adapter_resolver.rb` | Select scraper adapter for a source |
 | `ItemScraper::Persistence` | `scraping/item_scraper/persistence.rb` | Save scrape results to ItemContent |
+| `Runner` | `scraping/runner.rb` | Service delegated to by ScrapeItemJob; orchestrates state, scraping, and logging |
 | `BulkSourceScraper` | `scraping/bulk_source_scraper.rb` | Scrape all pending items for a source |
 | `BulkResultPresenter` | `scraping/bulk_result_presenter.rb` | Format bulk scrape results |
 | `State` | `scraping/state.rb` | Track scraping state per source |
@@ -150,6 +153,7 @@ Complete module tree with each module's responsibility.
 |--------|------|----------------|
 | `SourceHealthMonitor` | `health/source_health_monitor.rb` | Calculate rolling success rate, update health_status |
 | `SourceHealthCheck` | `health/source_health_check.rb` | Perform HTTP health check on a source |
+| `SourceHealthCheckOrchestrator` | `health/source_health_check_orchestrator.rb` | Service delegated to by SourceHealthCheckJob; coordinates check, logging, and broadcasting |
 | `SourceHealthReset` | `health/source_health_reset.rb` | Reset health state for a source |
 | `ImportSourceHealthCheck` | `health/import_source_health_check.rb` | Health check for import session sources |
 
@@ -182,6 +186,34 @@ Complete module tree with each module's responsibility.
 | `Verification::ActionCableVerifier` | `setup/verification/action_cable_verifier.rb` | Verify Action Cable setup |
 | `Verification::TelemetryLogger` | `setup/verification/telemetry_logger.rb` | Log setup telemetry |
 
+### Favicons
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `Favicons::Discoverer` | `favicons/discoverer.rb` | Multi-strategy favicon discovery (direct, HTML parsing, Google API) |
+| `Favicons::Fetcher` | `favicons/fetcher.rb` | Service delegated to by FaviconFetchJob; guards, discovers, and attaches favicon |
+
+### Images
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `Images::Processor` | `images/processor.rb` | Service delegated to by DownloadContentImagesJob; downloads and attaches content images via Active Storage |
+
+### ViewComponents
+
+| Component | File | Responsibility |
+|-----------|------|----------------|
+| `StatusBadgeComponent` | `app/components/source_monitor/status_badge_component.rb` | Renders a colored status badge for health_status values |
+| `IconComponent` | `app/components/source_monitor/icon_component.rb` | Renders consistent inline SVG or CSS icons |
+| `FilterDropdownComponent` | `app/components/source_monitor/filter_dropdown_component.rb` | Renders filter dropdown menus for sources/items index |
+
+### Presenters
+
+| Presenter | File | Responsibility |
+|-----------|------|----------------|
+| `SourceDetailsPresenter` | `app/presenters/source_monitor/source_details_presenter.rb` | View-specific formatting for source detail pages (SimpleDelegator over Source) |
+| `SourcesFilterPresenter` | `app/presenters/source_monitor/sources_filter_presenter.rb` | Formats filter state and option lists for the sources index |
+
 ### Other
 
 | Module | File | Responsibility |

data/.claude/skills/sm-domain-model/reference/model-graph.md

@@ -112,4 +112,45 @@ Source has a `type` column for potential STI subclassing but it is not actively
 |--------|--------|-------|-------|
 | Source | `items_count` | Item | Only counts active (non-deleted) items |
 
-The counter is decremented manually during `soft_delete!` and can be recalculated via `reset_items_counter!`.
+The counter is decremented manually during `soft_delete!` and **incremented** during `restore!`. Both operations update `items_count` atomically. Use `reset_items_counter!` to recalculate from scratch if the counter drifts.
+
+## Model Methods (v0.12.0+)
+
+### Source.enable_scraping!(ids)
+
+Bulk-enables scraping for a list of source IDs:
+
+```ruby
+Source.enable_scraping!([1, 2, 3])
+# Sets scraping_enabled = true for each source in the list
+```
+
+Use case: enabling scraping on a filtered set of sources from the dashboard or a rake task.
+
+### Item#restore!
+
+Reverses a soft delete. Symmetric counterpart to `soft_delete!`:
+
+```ruby
+item.restore!
+# Clears deleted_at, increments source.items_count
+```
+
+After `restore!`, the item re-enters the `:items` (active) association and the source counter cache reflects the change.
+
+### health_status Validation
+
+As of v0.12.0, `health_status` is validated against the four permitted values. Assigning an unrecognized value raises a validation error:
+
+```ruby
+source.health_status = "healthy"  # invalid -- was removed in 0.11.0
+source.valid?                      # => false
+source.errors[:health_status]      # => ["is not included in the list"]
+```
+
+Permitted values: `"working"`, `"declining"`, `"improving"`, `"failing"`.
+
+## Schema Notes (v0.12.0)
+
+- **Composite indexes on log tables:** `sourcemon_fetch_logs`, `sourcemon_scrape_logs`, and `sourcemon_health_check_logs` now have composite indexes on `(source_id, created_at)` to improve log query performance on busy sources.
+- **health_status default alignment:** The `health_status` column default on `sourcemon_sources` was updated to `"working"` (previously `"healthy"`, a removed value) to match the four-value enum added in v0.11.0.

data/.claude/skills/sm-job/reference/job-conventions.md

@@ -113,7 +113,7 @@ Notable patterns:
 
 ### Worker Job (ScrapeItemJob)
 
-Demonstrates lifecycle logging:
+Demonstrates shallow delegation to a service class:
 
 ```ruby
 class ScrapeItemJob < ApplicationJob
@@ -121,35 +121,18 @@ class ScrapeItemJob < ApplicationJob
   discard_on ActiveJob::DeserializationError
 
   def perform(item_id)
-    log("job:start", item_id: item_id)
     item = Item.includes(:source).find_by(id: item_id)
     return unless item
 
-    source = item.source
-    unless source&.scraping_enabled?
-      log("job:skipped_scraping_disabled", item: item)
-      Scraping::State.clear_inflight!(item)
-      return
-    end
-
-    Scraping::State.mark_processing!(item)
-    Scraping::ItemScraper.new(item:, source:).call
-    log("job:completed", item: item, status: item.scrape_status)
-  rescue StandardError => error
-    log("job:error", item: item, error: error.message)
-    Scraping::State.mark_failed!(item)
-    raise
-  ensure
-    Scraping::State.clear_inflight!(item) if item
+    Scraping::Runner.new(item: item).call
   end
 end
 ```
 
 Notable patterns:
-- `includes(:source)` prevents N+1 query
-- Lifecycle state management (`mark_processing!`, `clear_inflight!`)
-- Error re-raise after state cleanup
-- Structured JSON logging at each stage
+- Job body is deserialization + delegation only
+- All business logic (state management, scraping, logging) lives in `Scraping::Runner`
+- `includes(:source)` prevents N+1 query before handing off to the service
 
 ### Scheduling Job (ScheduleFetchesJob)
 
@@ -168,7 +151,7 @@ end
 
 ### Lightweight Fetch Job (FaviconFetchJob)
 
-Demonstrates multi-strategy cascade with guard clauses:
+Demonstrates shallow delegation with guard clause:
 
 ```ruby
 class FaviconFetchJob < ApplicationJob
@@ -178,23 +161,19 @@ class FaviconFetchJob < ApplicationJob
   def perform(source_id)
     source = Source.find_by(id: source_id)
     return unless source
-    return unless should_fetch?(source)
 
-    result = Favicons::Discoverer.new(source: source).call
-    attach_favicon(source, result) if result.success?
+    Favicons::Fetcher.new(source: source).call
   end
 end
 ```
 
 Notable patterns:
-- Multiple guard clauses: source exists, Active Storage defined, no existing favicon, outside cooldown period
-- Uses `Favicons::Discoverer` service with 3-strategy cascade (direct `/favicon.ico`, HTML parsing, Google API)
-- Failed attempts tracked in source `metadata` JSONB (`favicon_last_attempted_at`) for retry cooldown
+- Job contains only lookup + delegation — guard clauses and discovery strategy cascade live in `Favicons::Fetcher`
 - Graceful degradation: host apps without Active Storage never enqueue this job
 
 ### Broadcast Job (SourceHealthCheckJob)
 
-Demonstrates result broadcasting:
+Demonstrates shallow delegation with result broadcasting:
 
 ```ruby
 class SourceHealthCheckJob < ApplicationJob
@@ -205,21 +184,48 @@ class SourceHealthCheckJob < ApplicationJob
     source = Source.find_by(id: source_id)
     return unless source
 
-    result = Health::SourceHealthCheck.new(source: source).call
-    broadcast_outcome(source, result)
-    result
-  rescue StandardError => error
-    record_unexpected_failure(source, error) if source
-    broadcast_outcome(source, nil, error) if source
-    nil
+    Health::SourceHealthCheckOrchestrator.new(source: source).call
   end
 end
 ```
 
 Notable patterns:
-- Always broadcasts UI update (success or failure)
-- Creates log record even for unexpected failures
-- Returns nil on error instead of re-raising (health checks are non-critical)
+- Job body is lookup + delegation only
+- Broadcasting, logging, and error handling live in `Health::SourceHealthCheckOrchestrator`
+- Returns nil on missing source; orchestrator handles nil-on-error (health checks are non-critical)
+
+## Shallow Delegation Pattern
+
+As of v0.12.0, five maintenance jobs delegate entirely to dedicated service classes. Jobs contain only deserialization and delegation — no business logic.
+
+| Job | Service Class |
+|-----|---------------|
+| `ScrapeItemJob` | `Scraping::Runner` |
+| `DownloadContentImagesJob` | `Images::Processor` |
+| `FaviconFetchJob` | `Favicons::Fetcher` |
+| `SourceHealthCheckJob` | `Health::SourceHealthCheckOrchestrator` |
+| `ImportSessionHealthCheckJob` | `ImportSessions::HealthCheckUpdater` |
+
+**Why this pattern:**
+- Jobs are the transport mechanism, not the behavior container.
+- Service classes are unit-testable without ActiveJob infrastructure.
+- Future pipeline changes (e.g., calling the same logic synchronously) require no job changes.
+
+**Template for new jobs:**
+
+```ruby
+class MyJob < ApplicationJob
+  source_monitor_queue :maintenance
+  discard_on ActiveJob::DeserializationError
+
+  def perform(record_id)
+    record = MyModel.find_by(id: record_id)
+    return unless record
+
+    MyNamespace::MyService.new(record: record).call
+  end
+end
+```
 
 ## _later / _now Naming Convention
 

data/.claude/skills/sm-upgrade/reference/version-history.md

@@ -2,6 +2,25 @@
 
 Version-specific migration notes for each major/minor version transition. Agents should reference this file when guiding users through multi-version upgrades.
 
+## 0.11.x to 0.12.0
+
+**Key changes:**
+- 2 new migrations: composite indexes on `sourcemon_fetch_logs`, `sourcemon_scrape_logs`, and `sourcemon_health_check_logs` (on `source_id, created_at`), and `health_status` column default corrected to `"working"`.
+- 5 background jobs extracted to service classes: `ScrapeItemJob` -> `Scraping::Runner`, `DownloadContentImagesJob` -> `Images::Processor`, `FaviconFetchJob` -> `Favicons::Fetcher`, `SourceHealthCheckJob` -> `Health::SourceHealthCheckOrchestrator`, `ImportSessionHealthCheckJob` -> `ImportSessions::HealthCheckUpdater`. Job arguments and queue assignments are unchanged.
+- New ViewComponents: `StatusBadgeComponent`, `IconComponent`, `FilterDropdownComponent`.
+- New presenters: `SourceDetailsPresenter`, `SourcesFilterPresenter`.
+- New model methods: `Source.enable_scraping!(ids)`, `Item#restore!`, `health_status` validation against the 4 permitted values.
+
+**Action items:**
+1. Copy and run migrations:
+   ```bash
+   bin/rails source_monitor:install:migrations
+   bin/rails db:migrate
+   ```
+2. No breaking changes -- all existing initializer configuration and job interfaces remain valid.
+3. No configuration changes required.
+4. ViewComponents and presenters are available for use in custom views but are not required.
+
 ## 0.10.2 to 0.11.0
 
 **Key changes:**

data/CHANGELOG.md

@@ -15,6 +15,63 @@ All notable changes to this project are documented below. The format follows [Ke
 
 - No unreleased changes yet.
 
+## [0.12.1] - 2026-03-15
+
+### Documentation
+- Updated README, docs/setup, docs/upgrade with v0.12.0 version references and upgrade guide
+- Updated 4 skill references (sm-job, sm-architecture, sm-domain-model, sm-upgrade) for service class extractions, new components, and model methods
+- Improved `/release` command: Step 4 now spawns agents to automatically audit AND fix all stale docs before every release
+
+## [0.12.0] - 2026-03-15
+
+### Added
+- `StatusBadgeComponent` for unified status badge rendering across all views
+- `IconComponent` with named icon registry replacing inline SVGs
+- `SourceDetailsPresenter` and `SourcesFilterPresenter` for view formatting
+- `FilterDropdownComponent` for reusable filter dropdowns
+- `SetSource` controller concern eliminating duplication across 7 controllers
+- `rescue_from ActiveRecord::RecordNotFound` with Turbo-aware 404 handling
+- `Source.enable_scraping!` class method for bulk enablement
+- `Item#restore!` with counter cache symmetry to `soft_delete!`
+- `Source` health_status inclusion validation and scraping scopes
+- Modal accessibility: `role="dialog"`, `aria-modal`, focus trapping via `inert`
+- Logs index Turbo Frame for partial page updates on filter/pagination
+- Missing controller tests for FetchLogsController and ScrapeLogsController
+- Date range scopes and composite indexes on Loggable concern
+- Result structs for completion handlers (EventPublisher, RetentionHandler, FollowUpHandler)
+- Transient vs fatal error classification in FaviconFetchJob and DownloadContentImagesJob
+- SharedLoggableTests module for consistent log model testing
+- TEST_CONVENTIONS.md documenting testing patterns
+
+### Fixed
+- LogCleanupJob now cascades deletes to LogEntry records preventing orphaned rows
+- `health_status` default aligned between model (`working`) and database
+- Swallowed exceptions in `Scraping::State` and pipeline rescue blocks now log warnings
+- Pagination tests use `clean_source_monitor_tables!` instead of `Source.destroy_all` for parallel safety
+- `fallback_user_id` guarded behind `Rails.env.development?` to prevent engine writing to host-app tables
+- Dashboard GC pressure reduced from SolidQueue data accumulation
+- Deadlock rescue added to 4 jobs
+
+### Changed
+- **5 jobs extracted to service classes** (shallow delegation pattern):
+  - `ScrapeItemJob` → `Scraping::Runner` (73→21 lines)
+  - `DownloadContentImagesJob` → `Images::Processor` (95→16 lines)
+  - `FaviconFetchJob` → `Favicons::Fetcher` (94→16 lines)
+  - `SourceHealthCheckJob` → `Health::SourceHealthCheckOrchestrator` (85→16 lines)
+  - `ImportSessionHealthCheckJob` → `ImportSessions::HealthCheckUpdater` (99→32 lines)
+- Duplicated scrape rate-limiting consolidated (removed from ScrapeItemJob, kept in Enqueuer)
+- `sync_log_entry` callback consolidated into Loggable concern (removed from 3 models)
+- `ItemScrapesController` extracted from Items#scrape for CRUD compliance
+- FetchFeedJob retry/circuit-breaker logic extracted to RetryOrchestrator service
+- Favicon cooldown logic moved from controller to Source model
+- Import step dispatch refactored to handler registry pattern
+- 30 backward-compatibility forwarding methods removed from FeedFetcher and ItemCreator
+- `Images::Downloader` uses `HTTP.client` instead of raw Faraday (respects proxy/SSL config)
+- `CloudflareBypass` limited to 1 UA rotation attempt with per-attempt timeout
+- Dashboard stats split into per-stat Turbo Streams for granular updates
+- Test factory helpers centralized into ModelFactories module
+- System tests refactored to shared base class with SystemTestHelpers
+
 ## [0.11.1] - 2026-03-13
 
 ### Fixed

data/CLAUDE.md

@@ -4,8 +4,8 @@
 
 ## Active Context
 
-**Last shipped:** ui-fixes-and-smart-scraping (5 phases, 22 plans)
-**Next action:** /vbw:vibe to plan Phase 01 (Ultimate Turbo Modal Integration)
+**Last shipped:** rails-audit-and-refactoring (7 phases, 30 plans)
+**Next action:** /vbw:vibe to start new work
 
 ## Key Decisions