source_monitor 0.13.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d863378a0fb5338b1b1fe89c40c0c0ab9705b3ce60c45889eabf1ed626d27cf1
-  data.tar.gz: d3a56da362430857991b85ab2b24ef10b5e2641dc312ecbe2a302bdca1a8352b
+  metadata.gz: 55bf050a9f74f18ed354d7d751f868bc98dc8bc5da59c3da6ce5e0aa0cedc833
+  data.tar.gz: 37a5906b19541de00ef3b860f266a1c7a12e737da58d1a7b80cb806a191936d5
 SHA512:
-  metadata.gz: 885cf285ecc91bf09f2bca2bd9f384cea7f36e1c966a0a74a20d7f87a9df8f69da79dd8363762111c3e206dfe1668ddbefc46cdda71c4e83eaeb138099e74a25
-  data.tar.gz: b38579d624e4e66f5f051ce3aab2e61249fb549310e73e1959cdc0d67aef7fb63ff7c18232563269b2e826c5eb08f2a01bb5cf78f992df90bba3a0649d4d7a21
+  metadata.gz: 0c0109e46a1ec8691592fd304095c833d5d78b9091ffa216e72011040a8683be820016dd51b4a2185d17b9780761410918297f9f4fdeb2fd31d1e952575fbf99
+  data.tar.gz: 9016293bb6d6339026ed811689db2a4f1b87cd90fb60bb7f270113fc698c9714f9935f2aec704c1581b3ef6b61137b2df5c5b21e0ecd8b2bea69be987152057f

data/.claude/skills/sm-configuration-setting/reference/settings-catalog.md

@@ -157,6 +157,7 @@ Has `reset!` method. The `adapter=` setter validates against `VALID_ADAPTERS`.
 | `authorize_handler` | Handler/nil | `nil` | Authorization handler |
 | `current_user_method` | Symbol/nil | `nil` | Method name for current user |
 | `user_signed_in_method` | Symbol/nil | `nil` | Method name for signed-in check |
+| `open_access` | Boolean | `false` | Opt out of the fail-closed access guard (demo/non-production only); ignored when a handler is configured |
 
 Has `reset!` method.
 

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

@@ -66,10 +66,17 @@ config.http.retry_max = 3
 ```
 
 ### Authentication (Devise)
+SourceMonitor is **fail-closed by default**: with no `authenticate_with`/`authorize_with`
+handler configured, every engine route returns `403 Forbidden`. Configure a handler
+to protect the dashboard (the handler decides access and bypasses the fail-closed guard):
 ```ruby
 config.authentication.authenticate_with :authenticate_user!
 config.authentication.authorize_with ->(c) { c.current_user&.admin? }
 ```
+For local demos/sandboxes only, opt out of the fail-closed guard (non-production):
+```ruby
+config.authentication.open_access = true # default: false -- demo/non-production only
+```
 
 ### Image Downloads (Active Storage)
 ```ruby
@@ -167,7 +174,7 @@ end
 - [ ] Initializer exists at `config/initializers/source_monitor.rb`
 - [ ] Queue names match `config/queue.yml` (or `config/solid_queue.yml`) entries
 - [x] Dispatcher config includes `recurring_schedule: config/recurring.yml` (handled by install generator)
-- [ ] Authentication hooks configured for host auth system
+- [ ] Authentication decision made: configure `authenticate_with`/`authorize_with` (fail-closed default) OR set `config.authentication.open_access = true` for demos only
 - [ ] HTTP timeouts appropriate for target feeds
 - [ ] Retention policy set for production
 - [ ] Workers restarted after configuration changes

data/.claude/skills/sm-configure/reference/configuration-reference.md

@@ -283,10 +283,17 @@ config.realtime.solid_cable.connects_to = { database: { writing: :cable } }
 
 Class: `SourceMonitor::Configuration::AuthenticationSettings`
 
+**Fail-closed by default.** When no `authenticate_with`/`authorize_with` handler is
+configured and `open_access` is `false`, the engine denies every route with
+`403 Forbidden` (see `SourceMonitor::Security::Authentication.access_denied_by_default?`).
+Configuring either handler makes the handler authoritative and bypasses the
+fail-closed guard.
+
 | Setting | Type | Default | Description |
 |---|---|---|---|
 | `current_user_method` | Symbol/nil | `nil` | Controller method to get current user |
 | `user_signed_in_method` | Symbol/nil | `nil` | Controller method to check sign-in status |
+| `open_access` | Boolean | `false` | Opt out of the fail-closed guard so engine routes are public. **Demo/non-production only.** Ignored when a handler is configured. |
 
 ### Methods
 
@@ -312,6 +319,10 @@ config.authentication.authorize_with ->(controller) {
 config.authentication.authorize_with do
   redirect_to root_path unless current_user&.admin?
 end
+
+# Open access (demo/non-production only) -- disables the fail-closed guard.
+# Leave commented/false in production. A configured handler always wins.
+config.authentication.open_access = true # default: false
 ```
 
 ---

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

@@ -119,7 +119,7 @@ After installation, review and customize the initializer. Key areas:
 | Section | Purpose |
 |---|---|
 | Queue settings | Queue names, concurrency, namespace |
-| Authentication | `authenticate_with`, `authorize_with` hooks |
+| Authentication | **Fail-closed by default** -- configure `authenticate_with`/`authorize_with` hooks, or set `open_access = true` for demos only |
 | HTTP client | Timeouts, proxy, retries |
 | Fetching | Adaptive scheduling intervals and factors |
 | Health | Auto-pause/resume thresholds |
@@ -152,7 +152,17 @@ SOURCE_MONITOR_SETUP_TELEMETRY=true bin/source_monitor verify
 # Logs to log/source_monitor_setup.log
 ```
 
-## Devise Integration
+## Authentication (Fail-Closed by Default)
+
+SourceMonitor is **fail-closed by default**: with no `authenticate_with`/`authorize_with`
+handler configured, every engine route (including create/update/delete/enqueue actions)
+returns `403 Forbidden`. You must make one of two choices during setup:
+
+1. **Configure a handler** (recommended) -- the handler decides access and bypasses the
+   fail-closed guard.
+2. **Set `config.authentication.open_access = true`** -- opts out of the guard so routes
+   are public. **Demo/non-production only.** A configured handler always takes precedence
+   over this flag.
 
 When Devise is detected, the guided installer offers to wire authentication hooks:
 
@@ -238,6 +248,6 @@ end
 - [x] `Procfile.dev` includes `jobs:` entry for Solid Queue (handled by generator)
 - [x] Dispatcher config includes `recurring_schedule: config/recurring.yml` (handled by generator)
 - [ ] Solid Queue workers started
-- [ ] Authentication hooks configured in initializer
+- [ ] Authentication decision made (engine is fail-closed by default): handler configured via `authenticate_with`/`authorize_with`, OR `config.authentication.open_access = true` for demos only
 - [ ] `bin/source_monitor verify` passes
 - [ ] Dashboard accessible at mount path

data/.claude/skills/sm-host-setup/reference/initializer-template.md

@@ -57,7 +57,12 @@ SourceMonitor.configure do |config|
   # ===========================================================================
   # Authentication
   # ===========================================================================
+  # SECURITY: SourceMonitor is FAIL-CLOSED by default. If you do not configure
+  # an authentication or authorization handler below, every engine route
+  # (including create/update/delete/enqueue actions) returns 403 Forbidden.
   # Handlers: Symbol (invoked on controller) or callable (receives controller).
+  # As soon as a handler is configured it decides access and the fail-closed
+  # guard no longer applies.
 
   # Authenticate before accessing any SourceMonitor page.
   # config.authentication.authenticate_with :authenticate_user!
@@ -71,6 +76,12 @@ SourceMonitor.configure do |config|
   # config.authentication.current_user_method = :current_user
   # config.authentication.user_signed_in_method = :user_signed_in?
 
+  # Explicit opt-in for open/unauthenticated access. Leave commented out in
+  # production. Only enable for local demos or sandboxes where engine routes
+  # are deliberately public.
+  # WARNING: non-production / demo only -- this disables the fail-closed guard.
+  # config.authentication.open_access = true
+
   # ===========================================================================
   # HTTP Client
   # ===========================================================================

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

@@ -57,6 +57,10 @@ bin/rails db:migrate
 
 ## Phase 5: Configure Authentication
 
+**Fail-closed by default.** With no handler configured, every engine route returns
+`403 Forbidden`. Make one of two choices: configure a handler (recommended) OR opt into
+open access for demos only.
+
 Edit `config/initializers/source_monitor.rb`:
 
 ```ruby
@@ -68,10 +72,14 @@ SourceMonitor.configure do |config|
   }
   config.authentication.current_user_method = :current_user
   config.authentication.user_signed_in_method = :user_signed_in?
+
+  # OR, for local demos/sandboxes only (non-production) -- opt out of the
+  # fail-closed guard so routes are public. A configured handler always wins.
+  # config.authentication.open_access = true
 end
 ```
 
-- [ ] Authentication hook configured
+- [ ] Authentication decision made: handler configured (fail-closed default) OR `open_access = true` set for demos only
 - [ ] Authorization hook configured (if needed)
 
 ## Phase 6: Configure Workers

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

@@ -2,6 +2,32 @@
 
 Version-specific migration notes for each major/minor version transition. Agents should reference this file when guiding users through multi-version upgrades.
 
+## 0.14.0 to 0.15.0
+
+**Key changes:**
+- **Security:** Rails bumped to 8.1.3 (security release), picking up fixes for five CVEs including XSS in tag/DebugExceptions helpers, an Active Storage path-traversal, and a NumberConverter issue.
+- **ViewComponent 4.x:** the `view_component` dependency widens from `>= 3.0, < 4.0` to `>= 3.0, < 5.0`, allowing host apps to resolve ViewComponent 4.x (engine lockfile resolves to 4.5.0). Engine components use only stable APIs unaffected by v4.
+- **Solid Queue 1.4.0:** bumped from 1.3.1 with race-condition and supervisor stability fixes; dynamic recurring tasks are opt-in.
+- **Documentation:** engine conventions consolidated into `AGENTS.md`; `CLAUDE.md` now points to it.
+
+**Action items:**
+1. `bundle update source_monitor`
+2. `bin/rails source_monitor:upgrade`
+3. No migrations or breaking config/API changes.
+4. If the host app has ViewComponent 3.x customizations (custom components, previews), test after upgrading and consult ViewComponent v4 migration guides if needed.
+
+## 0.13.1 to 0.14.0
+
+**Key changes:**
+- **BREAKING — Fail-closed by default** (#129): engine routes return `403 Forbidden` unless `config.authentication.authenticate_with` or `config.authentication.authorize_with` is configured, OR `config.authentication.open_access = true` is explicitly set (non-production only).
+- **Request flashes response-local** (#130): flash toasts no longer broadcast to the global `source_monitor_notifications` ActionCable stream; rendered inline on HTML loads and appended on turbo_stream responses instead. Background operational toasts stay global but context-free.
+- **Gem package excludes `.claude` internals** (#131): only `.claude/skills/sm-*` shipped; agents, hooks, `settings.json`, commands, and non-`sm-*` skills excluded.
+
+**Action items:**
+1. `bundle update source_monitor`
+2. **Action required (auth):** in `config/initializers/source_monitor.rb`, ensure at least one of `authenticate_with`, `authorize_with`, or `open_access = true` (demo/sandbox only). Without one, all engine routes return `403`.
+3. No migrations or other breaking API changes; flash/packaging changes apply transparently.
+
 ## 0.12.4 to 0.13.0
 
 **Key changes:**

data/AGENTS.md

@@ -1,47 +1,74 @@
 # Repository Guidelines
 
-Refer to `CLAUDE.md` for project conventions and skills catalog.
+This file is the **canonical engine convention reference, shared across all AI coding agents** (Claude Code, Codex, etc.). It is the single source of truth for tech stack, architecture, testing, quality gates, CI, security, and commands.
+
+`CLAUDE.md` holds only Claude Code-specific context (working-memory header, VBW commands, and the `.claude/` agent/skill catalogs) and references this file for conventions. When a convention changes, edit it **here**, not in `CLAUDE.md`.
 
 Use rbenv for all ruby and bundler/gem commands, not the system ruby.
 
-## Contribution Workflow
+## Tech Stack
 
-- 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`.
-- 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.
-- Merge via the PR UI (squash or rebase as agreed) after approval; avoid rewriting shared history post-push.
-- Tag releases only after the release PR merges, then follow the checklist in `CHANGELOG.md`.
+| Layer | Technology |
+|-------|------------|
+| Ruby | 4.0+ |
+| Rails | 8.x |
+| Testing | Minitest (no fixtures -- uses factory helpers + WebMock/VCR) |
+| Authorization | Host app responsibility (mountable engine); **fail-closed by default** (#129) |
+| Jobs | Solid Queue |
+| Frontend | Hotwire (Turbo + Stimulus) + Tailwind CSS |
+| Linting | RuboCop (omakase) + Brakeman |
+| Database | PostgreSQL only |
 
-## Library Documentation
+## Project Structure & Module Organization
 
-- Use Context7 MCP constantly to look up fresh documentation for any task you're looking to complete, especially tasks that rely on using libraries or gems
+The engine follows the Rails mountable layout generated by `rails plugin new source_monitor --mountable`. Runtime code lives under `app/` (controllers, jobs, views) and is namespaced as `SourceMonitor`. Long-lived services, adapters, and instrumentation helpers belong in `lib/source_monitor/`. Generator templates and install scripts reside in `lib/generators/source_monitor/`. Tests sit in `test/`, with fixtures under `test/fixtures/feeds/`, and the dummy host app in `test/dummy/` for integration coverage. Keep shared UI assets under `app/assets/` and engine configuration in `config/initializers/`.
 
-### Project Dependencies & context7 links
+## Architecture Conventions
 
-- Feedjirra - https://context7.com/feedjira/feedjira
+### Models First
+- Business logic lives in models. Use concerns for horizontal sharing.
+- Service objects ONLY for operations spanning 3+ models or external integrations.
+- Query objects for complex queries that don't fit a single scope.
+- Presenters (SimpleDelegator) for view-specific formatting.
 
-## Project Structure & Module Organization
+### Everything-is-CRUD Routing
+- Prefer creating a new resource over adding custom actions.
+- `POST /posts/:id/publications` over `POST /posts/:id/publish`.
+- RESTful routes only; no `member` or `collection` blocks with custom verbs.
 
-The engine follows the Rails mountable layout generated by `rails plugin new source_monitor --mountable`. Runtime code lives under `app/` (controllers, jobs, views) and is namespaced as `SourceMonitor`. Long-lived services, adapters, and instrumentation helpers belong in `lib/source_monitor/`. Generator templates and install scripts reside in `lib/generators/source_monitor/`. Tests sit in `test/`, with fixtures under `test/fixtures/feeds/`, and the dummy host app in `test/dummy/` for integration coverage. Keep shared UI assets under `app/assets/` and engine configuration in `config/initializers/`.
+### State as Records
+- Track business state transitions as separate records (who/when/why).
+- Boolean columns ONLY for technical flags (e.g., `email_verified`, `open_access`).
 
-## Build, Test, and Development Commands
+### Jobs
+- Shallow jobs: call `_later` or `_now` methods on models/services.
+- Jobs contain only deserialization + delegation. No business logic.
+- Use Solid Queue recurring jobs for scheduled work.
 
-Run `bin/setup` to install gems, prepare the dummy database, and compile Tailwind. Use `bin/rails test` (or `bundle exec rake test`) for the full MiniTest suite, including system tests through the dummy app. During feature work, `bin/dev` starts the dummy app with Solid Queue workers and Tailwind watcher. Trigger a feed ingest locally with `bin/rails runner 'SourceMonitor::FetchFeeds.call'` once the fetcher service lands.
+### Frontend
+- Turbo Frames for partial page updates.
+- Turbo Streams for real-time broadcasts.
+- Stimulus controllers: small, focused, one behavior each.
+- Tailwind CSS utility classes; extract components for repeated patterns.
 
-## Background Job Defaults
+## Coding Style & Naming Conventions
 
-- SourceMonitor ensures Solid Queue is the default adapter when the host app is still using the async adapter, but respects any explicit `ActiveJob` configuration already in place. Override queues/concurrency via `SourceMonitor.configure`.
-- Queue names are namespaced (`source_monitor_fetch`/`source_monitor_scrape` by default) and automatically honor host `queue_name_prefix`. Use `SourceMonitor.queue_name(:fetch)` helpers inside jobs.
-- Dashboard queue metrics read directly from Solid Queue tables via `SourceMonitor::Jobs::SolidQueueMetrics`. Host apps must install the Solid Queue migrations (reuse the engine's `20251009140000_create_solid_queue_tables.rb` or run `rails solid_queue:install`) for the card to surface ready/scheduled/failed counts; otherwise the UI falls back to an availability warning. Mission Control remains optional for deeper drill-downs.
-- The dummy host keeps Solid Queue tables in the primary database via `20251009140000_create_solid_queue_tables.rb`. Real apps can either reuse that migration or run `rails solid_queue:install` to manage a dedicated queue database—Mission Control expects one of those setups before it can surface data.
-- Recurring schedules live in `config/recurring.yml`, scheduling `SourceMonitor::ScheduleFetchesJob` each minute plus the scraping scheduler every two minutes. Override the schedule path with `bin/jobs --recurring_schedule_file=...` (or `SOLID_QUEUE_RECURRING_SCHEDULE_FILE`) and disable recurring runners with `SOLID_QUEUE_SKIP_RECURRING=true` or `bin/jobs --skip-recurring`.
-- Hosts that need to wrap Solid Queue command execution can set `config.recurring_command_job_class` in the generated initializer to point at their custom job class.
+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 `bin/rubocop` (configured via `.rubocop.yml`) before opening a PR. For views, stick with ERB and Tailwind utility classes.
+
+Sub-module extraction pattern: create `module/submodule.rb` with `require_relative`, lazy accessors, and forwarding methods for backward compatibility. The project uses Ruby autoload for `lib/` modules (not Zeitwerk).
+
+## Clean Coding Principles
+
+- **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.**
 
 ## Configuration DSL
 
-- `SourceMonitor.configure` now exposes structured namespaces:
+- `SourceMonitor.configure` exposes structured namespaces:
+  - `config.authentication` gates the engine. With no `authenticate_with`/`authorize_with` handler configured, the engine is **fail-closed** and returns `403`. Set `config.authentication.open_access = true` (default `false`) only for local demos/sandboxes — never production.
   - `config.http` for Faraday timeouts, retry policy, proxy, and default headers. Per the [Faraday retry docs](https://github.com/lostisland/faraday/blob/main/docs/middleware/index.md), middleware options map 1:1 to the settings we surface (max retries, interval, backoff, statuses).
   - `config.scrapers` registers/overrides adapters by name; adapters must inherit from `SourceMonitor::Scrapers::Base` and are discovered before constant lookup.
   - `config.retention` supplies global defaults for `items_retention_days`, `max_items`, and the pruning strategy (`:destroy` or `:soft_delete`). Runtimes treat blank source fields as “inherit from config”.
@@ -57,29 +84,109 @@ Run `bin/setup` to install gems, prepare the dummy database, and compile Tailwin
 - `SourceMonitor::ItemCleanupJob` batches retention pruning across sources and can soft delete records (`rake source_monitor:cleanup:items` honours `SOFT_DELETE=true`, `SOURCE_IDS=1,2`). `SourceMonitor::LogCleanupJob` prunes old fetch/scrape logs (`rake source_monitor:cleanup:logs`, override `FETCH_LOG_DAYS` / `SCRAPE_LOG_DAYS`).
 - Nightly recurring entries in `config/recurring.yml` enqueue both cleanup jobs by default; adjust schedules or disable via Solid Queue overrides as needed.
 
-## Coding Style & Naming Conventions
+## Background Job Defaults
 
-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.
+- SourceMonitor ensures Solid Queue is the default adapter when the host app is still using the async adapter, but respects any explicit `ActiveJob` configuration already in place. Override queues/concurrency via `SourceMonitor.configure`.
+- Queue names are namespaced (`source_monitor_fetch`/`source_monitor_scrape` by default) and automatically honor host `queue_name_prefix`. Use `SourceMonitor.queue_name(:fetch)` helpers inside jobs.
+- Dashboard queue metrics read directly from Solid Queue tables via `SourceMonitor::Jobs::SolidQueueMetrics`. Host apps must install the Solid Queue migrations (reuse the engine's `20251009140000_create_solid_queue_tables.rb` or run `rails solid_queue:install`) for the card to surface ready/scheduled/failed counts; otherwise the UI falls back to an availability warning. Mission Control remains optional for deeper drill-downs.
+- The dummy host keeps Solid Queue tables in the primary database via `20251009140000_create_solid_queue_tables.rb`. Real apps can either reuse that migration or run `rails solid_queue:install` to manage a dedicated queue database—Mission Control expects one of those setups before it can surface data.
+- Recurring schedules live in `config/recurring.yml`, scheduling `SourceMonitor::ScheduleFetchesJob` each minute plus the scraping scheduler every two minutes. Override the schedule path with `bin/jobs --recurring_schedule_file=...` (or `SOLID_QUEUE_RECURRING_SCHEDULE_FILE`) and disable recurring runners with `SOLID_QUEUE_SKIP_RECURRING=true` or `bin/jobs --skip-recurring`.
+- Hosts that need to wrap Solid Queue command execution can set `config.recurring_command_job_class` in the generated initializer to point at their custom job class.
+
+## Build, Test, and Development Commands
+
+Run `bin/setup` to install gems, prepare the dummy database, and compile Tailwind. During feature work, `bin/dev` starts the dummy app with Solid Queue workers and Tailwind watcher.
+
+```bash
+bin/dev                     # Start dev server
+bin/rails test              # Run the MiniTest suite (NOT a substitute for CI -- see below)
+bin/rubocop                 # Check style
+bin/rubocop -a              # Auto-fix style
+bin/brakeman --no-pager     # Security scan
+bin/rails db:migrate        # Run migrations
+```
+
+The dummy host app runs on **port 3002** (`cd test/dummy && bin/rails server -p 3002`).
+
+## Testing
 
-## Testing Guidelines
+- **Framework:** Minitest. NEVER use RSpec or FactoryBot. Name files with `_test.rb` and wrap suites in `module SourceMonitor`. Tests live in `test/models`, `test/controllers`, `test/system`, `test/lib`, `test/integration`.
+- **Helpers:** `create_source!` factory, `with_inline_jobs`, `with_queue_adapter`.
+- **HTTP:** WebMock disables external HTTP; VCR for recorded cassettes under `test/vcr_cassettes/` (record new fixtures with descriptive names like `source_fetch_success.yml`).
+- **Config isolation:** `test/test_helper.rb` calls `SourceMonitor.reset_configuration!` in every test's setup (rebuilding a fresh `Configuration`), so any config a test relies on must be set in setup, not the dummy initializer.
+- **Coverage:** Target >90% for new services; cover every model validation, scope, public method, and controller action, plus regression tests for bug fixes.
+- **Parallelism:** Coverage runs need `COVERAGE=1 PARALLEL_WORKERS=1` with **threads** (not forks) to avoid a PG segfault and SimpleCov data loss. Scope queries to a specific source/item to prevent cross-test contamination in parallel runs.
+- **Automate what you can:** Anything verifiable programmatically (config defaults, job enqueue behavior, controller responses) should be a test, not a manual checkpoint.
+
+## Quality Gates
+
+- `bin/rubocop` — zero offenses before commit (omakase: only ~45/775 cops enabled, all Metrics cops disabled — no file-size enforcement).
+- `bin/brakeman --no-pager` — zero warnings before merge.
+- `bin/rails test` — all tests pass.
+- `yarn build` — rebuild JS assets if any `.js` files changed (ESLint runs in CI).
+- No N+1 queries (use `includes`/`preload`).
+- No hardcoded credentials (use Rails credentials or ENV).
+
+### Pre-Push CI Checklist (run ALL before pushing to GitHub)
+
+Before pushing any branch (especially release branches), run the full CI equivalent locally:
+
+1. `bin/rubocop` — catches Ruby lint issues.
+2. `bin/test-coverage` — **this is what CI's `test` job actually runs.** Do NOT rely on `bin/rails test` to predict CI: `bin/rails test` uses a different harness/seed and does NOT run the diff-coverage gate, so it can be green (e.g. 1741/0) while CI fails. `bin/test-coverage` runs the real seed, the second `health_suite` pass, and the host-app-template test that **changes the process CWD mid-suite** (see gemspec note below).
+3. `bundle exec ruby bin/check-diff-coverage` — run AFTER `bin/test-coverage` (it reads `coverage/.resultset.json`). Reproduces the CI diff-coverage gate locally (threshold 90% on changed `app/`/`lib/` lines vs `origin/main`). This is the only way to know the gate passes before pushing.
+4. `bin/brakeman --no-pager` — catches security issues.
+5. `yarn build` — rebuilds JS and catches ESLint issues (CI runs ESLint separately).
+
+If legitimate coverage gaps remain after new code paths, refresh the baseline: `bin/test-coverage` then `bin/update-coverage-baseline`, and commit the regenerated `config/coverage_baseline.json`.
+
+**Why:** CI failures cost ~5 min per round-trip. Hard-won lessons:
+- **CI runs `bin/test-coverage`, not `bin/rails test`** — replicate the gate locally with steps 2 + 3. (v0.14.0: a green local `bin/rails test` masked a CI `bin/test-coverage` failure.)
+- **Diff coverage covers EVERY changed `app/`/`lib/` line**, including defensive/edge branches with no natural caller. If a branch can't be reached through a normal engine route (e.g. the `#130` turbo_stream flash-append, which only fires when a turbo_stream request carries a Rails flash), add a **test-only probe controller in the dummy app** (pattern: `test/dummy/app/controllers/test_support_controller.rb` + a route in `test/dummy/config/routes.rb`); subclass `SourceMonitor::ApplicationController` if the branch lives in the engine's filter chain.
+- Every `rescue`/fallback/error path in new source code needs test coverage.
+- **Gemspec packaging must be CWD-independent.** Do NOT use a bare `Dir[...]` glob in `source_monitor.gemspec` for file selection — it resolves against the process CWD, and during `bin/test-coverage` a sibling test chdir's into a generated host app, so the glob returns nothing and files silently drop from the package (v0.14.0 `#131`). Drive packaging from `git ls-files` inside the existing `Dir.chdir(File.expand_path(__dir__))` block.
+- JS files need `/* global */` declarations for browser APIs (MutationObserver, requestAnimationFrame, etc.); ESLint `no-undef` rejects them otherwise. Run `yarn build` after JS changes to sync sourcemaps.
+
+## Contribution Workflow
 
-MiniTest drives coverage (`test/models`, `test/controllers`, `test/system`). Name files with `_test.rb` and wrap suites in `module SourceMonitor`. Add VCR cassettes under `test/vcr_cassettes/` when touching HTTP clients, and record new fixtures with descriptive names like `source_fetch_success.yml`. Target >90% coverage for new services and include regression tests for bug fixes. Use `bin/rails test test/system` before changing UI flows.
+- 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`.
+- 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, test + diff coverage, release_verification) to succeed before merging.
+- Merge via the PR UI (squash or rebase as agreed) after approval; avoid rewriting shared history post-push.
+- Tag releases only after the release PR merges, then follow the checklist in `CHANGELOG.md`. There are TWO version files — `lib/source_monitor/version.rb` AND the top-level `VERSION` — and both must match; run `bundle install` after a bump so `Gemfile.lock` stays in sync (CI runs `--frozen`).
 
 ## 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, 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.
+Use Conventional Commit subjects in the format `type(scope): description`, e.g., `fix(fetch): resolve advisory lock contention`. Group unrelated work into separate commits. PRs should describe context, summarise the slice delivered, and list validation steps (`bin/test-coverage`, 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
 
-## Security & Configuration Tips
+### Protected files (NEVER read or output)
+- `.env`, `.env.*`
+- `config/master.key`, `config/credentials.yml.enc`
+- `.kamal/secrets`
+- Any `*.pem` / `*.key` files
 
+### Forbidden operations
+- `git push --force` to main/master/production
+- `git reset --hard` without explicit user confirmation
+- `rm -rf` on root, home, or parent directories
+- `chmod 777`
+
+### General
 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 Principles
+## Maintenance: Skills & Docs Alignment
 
-- **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.**
+Whenever engine code changes (models, configuration, pipeline, jobs, migrations, scrapers, events, health rules, or dashboard), the corresponding `sm-*` skill and its `reference/` files MUST be updated **in the same PR** so skills always reflect current engine behavior. Releases must also audit `README.md`, `docs/` (especially `docs/upgrade.md`), and the install initializer template against the source code.
+
+## Library Documentation
+
+- Use Context7 MCP constantly to look up fresh documentation for any task, especially tasks that rely on libraries or gems.
+
+### Project Dependencies & context7 links
+
+- Feedjira - https://context7.com/feedjira/feedjira
 
 ## Claude Code Skills
 
@@ -92,4 +199,4 @@ bin/rails source_monitor:skills:all            # All skills
 bin/rails source_monitor:skills:remove         # Remove all sm-* skills
 ```
 
-See `CLAUDE.md` for the full skills catalog and usage details.
+See `CLAUDE.md` for the full skills catalog (consumer vs. contributor) and the `.claude/` agent catalog.

data/CHANGELOG.md

@@ -13,6 +13,35 @@ All notable changes to this project are documented below. The format follows [Ke
 
 ## [Unreleased]
 
+- No unreleased changes yet.
+
+## [0.15.0] - 2026-06-18
+
+### Security
+- Bump Rails to 8.1.3 via the 8.1.2.1 security release (#104), picking up fixes for five CVEs including XSS in tag/DebugExceptions helpers, an Active Storage path-traversal, and a NumberConverter issue.
+
+### Changed
+- **Allow ViewComponent 4.x** (#96). The `view_component` dependency constraint widens from `>= 3.0, < 4.0` to `>= 3.0, < 5.0`, so host apps can now resolve ViewComponent 4.x (the engine's lockfile moves to 4.5.0). The engine's components use only stable ViewComponent APIs and are unaffected by the v4 upgrade — but a host app on its own ViewComponent 3.x customizations should review the v4 upgrade notes before running `bundle update`.
+- Bump Solid Queue to 1.4.0 (#102) — race-condition and supervisor stability fixes; the new dynamic recurring-tasks feature is opt-in and off by default.
+- Bump nokolexbor to 0.6.4 (#103) and json to 2.19.2 (#99).
+- Development/CI dependency bumps: test-prof 1.6.0 (#101), webmock 3.26.2 (#100), brakeman 8.0.4 (#88), selenium-webdriver 4.41.0 (#78), stackprof 0.2.28 (#71), and the GitHub Actions artifact actions (#87, #86).
+
+### Documentation
+- Consolidate engine conventions into `AGENTS.md` as the canonical, cross-agent reference; `CLAUDE.md` now points to it instead of duplicating content (#134).
+
+## [0.14.0] - 2026-05-28
+
+### Security (BREAKING)
+- **Fail-closed engine access by default** (#129). When the host app has configured no authentication/authorization handler, every mounted SourceMonitor route now returns `403 Forbidden` instead of being publicly accessible. Previously `authenticate!`/`authorize!` were silent no-ops when unconfigured, so create/update/delete/enqueue routes were public by omission.
+  - **Migration:** Configure a handler — `config.authentication.authenticate_with` and/or `config.authentication.authorize_with` — to gate the engine with your host auth stack. Configured handlers are honored exactly as before.
+  - **Demo opt-in:** To intentionally keep routes public (local demos/sandboxes only), set `config.authentication.open_access = true` (default `false`). Do not enable this in production.
+
+### Fixed
+- **Request flashes no longer leak across users** (#130). Request flash toasts were broadcast to a global ActionCable stream (`source_monitor_notifications`) that every connected browser tab subscribed to, so one user's flash could appear on every user's screen. Flashes are now delivered response-local — rendered inline on full-page HTML loads and appended to the turbo_stream response otherwise — reaching only the requesting tab. Background operational toasts (fetch/scrape completion) remain global but carry no per-user request context.
+
+### Changed
+- **Gem package no longer ships `.claude` internals** (#131). The packaged gem now excludes `.claude` agents, hooks, agent-memory, `settings.json`, commands, and non-`sm-*` skills; only the intended `.claude/skills/sm-*` SourceMonitor skills are shipped. Packaging is also now CWD-independent so the skill files are included deterministically.
+
 ## [0.13.1] - 2026-05-28
 
 ### Fixed