source_monitor 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69576ecf67e1a978b29bbc96f594a01cd33c7e5510600f696bb5aca1cf5c0740
-  data.tar.gz: a1d42ffe1fc8339e0657c915cdaf1765fe9518659978a20ad8a18a9861823145
+  metadata.gz: e63143dd784f79d378752978f534b36c122eec15264e8adf13cfcb994ca222cf
+  data.tar.gz: 04caa4a25e233c9520950697729efdad586770d6fba3fa00ba7369cbca9763ec
 SHA512:
-  metadata.gz: 2a3a5c00b0803cf7bef974d5b9507519221a00794a6f17398674e089221d1102fe4fef1b2e2d7cdecd30d3b9e9b0f44f50f62b04ebb46c96df7a9f3a52710fac
-  data.tar.gz: 1ec0ec3676faa8055c984be855b0e89096c47a9b59eabc5aeba5d806e00f70a8e098ad61c4daa707114e0570bd2c655cd853896524f3855e01bedd29491eaade
+  metadata.gz: 27bddd52129b5341906ebc67a7b86e259df8d0da671622b9271d1eab83cf214c1478e8674953d0eb20c8bd4bcb9b9257fc03261e4b061bd6f6d8c59d5a591ddb
+  data.tar.gz: b74f078deff1add84247e4fd0377d76ef026b1a2cee7b9808a252a2140507057d62a0be5c786c10f8e2e90e327a88717af211502850de797ece0ace895a822f7

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

@@ -12,7 +12,7 @@ Guides integration of the SourceMonitor engine into a host Rails application.
 
 - Adding SourceMonitor to a new or existing Rails 8 host app
 - Troubleshooting a broken installation
-- Re-running setup after upgrading the gem
+- Re-running setup after upgrading the gem (see also: `sm-upgrade` skill for full upgrade workflow)
 - Rolling back the engine from a host app
 
 ## Prerequisites
@@ -202,6 +202,7 @@ config.authentication.user_signed_in_method = :user_signed_in?
 - `docs/setup.md` -- Complete setup workflow documentation
 - `docs/configuration.md` -- Configuration reference
 - `docs/troubleshooting.md` -- Common issues and fixes
+- `sm-upgrade` skill -- Upgrade workflow for gem version updates
 
 ## Testing
 
@@ -209,6 +210,7 @@ After setup, verify with:
 1. `bin/source_monitor verify` -- Checks Solid Queue and Action Cable
 2. Visit the mount path in browser -- Dashboard should load
 3. Create a source and trigger "Fetch Now" -- Validates end-to-end
+4. For subsequent gem updates, use `bin/source_monitor upgrade` -- see the `sm-upgrade` skill
 
 Optional system test for host apps using Devise:
 ```ruby

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

@@ -0,0 +1,102 @@
+---
+name: sm-upgrade
+description: Use when upgrading SourceMonitor to a new gem version, including CHANGELOG review, running the upgrade command, interpreting verification results, and handling configuration deprecations.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# sm-upgrade: Gem Upgrade Workflow
+
+Guides AI agents through upgrading SourceMonitor in a host Rails application after a new gem version is released. Covers CHANGELOG review, running the upgrade command, interpreting verification results, handling deprecation warnings, and resolving common edge cases.
+
+## When to Use
+
+- Host app is updating the source_monitor gem version in Gemfile
+- User reports deprecation warnings after a gem update
+- User wants to know what changed between versions
+- Troubleshooting a broken upgrade
+- Migrating configuration after breaking changes
+
+## Prerequisites
+
+| Requirement | How to Check |
+|---|---|
+| Existing SourceMonitor installation | `cat .source_monitor_version` or check `config/initializers/source_monitor.rb` |
+| Access to CHANGELOG.md | Bundled with gem: `bundle show source_monitor` then read CHANGELOG.md |
+| Current gem version known | `grep source_monitor Gemfile.lock` |
+
+## Upgrade Workflow
+
+1. **Review CHANGELOG** -- Read `CHANGELOG.md` in the gem source. Identify changes between the current installed version (from `.source_monitor_version` or `Gemfile.lock`) and the target version. Focus on Added, Changed, Fixed, Removed sections. Flag any breaking changes or deprecation notices.
+2. **Update Gemfile** -- Bump the version constraint in the host app's Gemfile: `gem "source_monitor", "~> X.Y"`. Run `bundle update source_monitor`.
+3. **Run the upgrade command** -- `bin/source_monitor upgrade`. This automatically: detects the version change via `.source_monitor_version` marker, copies new migrations, re-runs the install generator (idempotent), runs the full verification suite.
+4. **Run database migrations** -- `bin/rails db:migrate` if the upgrade command copied new migrations.
+5. **Handle deprecation warnings** -- If the configure block in the initializer uses deprecated options, Rails logger will show warnings at boot. Read each warning, identify the replacement, update the initializer. See `sm-configure` skill for configuration reference.
+6. **Run verification** -- `bin/source_monitor verify` to confirm all checks pass.
+7. **Restart processes** -- Restart web server and Solid Queue workers to pick up the new version.
+
+## Interpreting Upgrade Results
+
+The upgrade command runs 4 verification checks automatically:
+
+| Check | OK | Failure | Fix |
+|---|---|---|---|
+| PendingMigrations | All engine migrations present | Missing migrations need copying | `bin/rails db:migrate` |
+| SolidQueue | Workers running | Workers not detected | Start Solid Queue workers via `Procfile.dev` or `bin/rails solid_queue:start` |
+| RecurringSchedule | Tasks registered | Tasks missing from dispatcher | Re-run generator or check `config/queue.yml` |
+| ActionCable | Adapter configured | No production adapter | Configure Solid Cable or Redis adapter |
+
+## Handling Deprecation Warnings
+
+The deprecation framework uses two severity levels:
+
+- **`:warning`** -- Option renamed. The old name still works but logs a deprecation message. Update the initializer to use the new option name. The message includes the replacement path.
+- **`:error`** -- Option removed. Using the old name raises `SourceMonitor::DeprecatedOptionError`. You must remove or replace the option before the app can boot.
+
+Pattern for fixing deprecations:
+
+1. Read the deprecation message (logged to `Rails.logger` or raised as an error)
+2. Find the replacement option path in the message
+3. Update `config/initializers/source_monitor.rb`
+4. Restart and verify the warning is gone
+
+Example deprecation message:
+```
+[SourceMonitor] DEPRECATION: 'http.old_option' was deprecated in v0.5.0 and replaced by 'http.new_option'.
+```
+
+## Edge Cases
+
+- **First install (no `.source_monitor_version` file):** Upgrade command treats this as a version change and runs the full workflow. Safe to run on first install.
+- **Same version (no change):** Command reports "Already up to date (vX.Y.Z)" and exits cleanly.
+- **Skipped versions (e.g., 0.2.0 to 0.4.0):** Read all CHANGELOG sections between the two versions. Multiple migrations may need running.
+- **Failed verification after upgrade:** Read the verification output. Most common: pending migrations (run `db:migrate`), missing Solid Queue workers (start workers), stale recurring schedule (re-run generator).
+- **Custom scrapers or event handlers:** Check CHANGELOG for API changes in `Scrapers::Base` or event callback signatures.
+
+## Key Source Files
+
+| File | Purpose |
+|---|---|
+| `lib/source_monitor/setup/upgrade_command.rb` | Upgrade orchestrator |
+| `lib/source_monitor/setup/cli.rb` | CLI entry point (`bin/source_monitor upgrade`) |
+| `lib/source_monitor/setup/verification/runner.rb` | Verification runner (4 verifiers) |
+| `lib/source_monitor/configuration/deprecation_registry.rb` | Deprecation framework |
+| `CHANGELOG.md` | Version history (Keep a Changelog format) |
+| `.source_monitor_version` | Version marker in host app root |
+
+## References
+
+- `docs/upgrade.md` -- Human-readable upgrade guide
+- `docs/setup.md` -- Initial setup documentation
+- `docs/troubleshooting.md` -- Common issues and fixes
+- `sm-host-setup` skill -- Initial installation workflow
+- `sm-configure` skill -- Configuration reference for updating deprecated options
+
+## Checklist
+
+- [ ] CHANGELOG reviewed for version range
+- [ ] Gemfile updated and `bundle update source_monitor` run
+- [ ] `bin/source_monitor upgrade` completed successfully
+- [ ] Database migrations applied if needed
+- [ ] Deprecation warnings addressed in initializer
+- [ ] `bin/source_monitor verify` passes all checks
+- [ ] Web server and workers restarted

data/.claude/skills/sm-upgrade/reference/upgrade-workflow.md

@@ -0,0 +1,92 @@
+# Upgrade Workflow Reference
+
+Detailed step-by-step reference for AI agents guiding host app developers through SourceMonitor gem upgrades.
+
+## Pre-Upgrade Checklist
+
+1. Identify current version: `grep source_monitor Gemfile.lock` or `cat .source_monitor_version`
+2. Identify target version: check RubyGems or GitHub releases
+3. Read CHANGELOG.md between those versions (in gem source: `bundle show source_monitor` to find gem path, then read CHANGELOG.md)
+4. Note any breaking changes, removed options, or new required configuration
+
+## CHANGELOG Parsing Guide
+
+- Format: [Keep a Changelog](https://keepachangelog.com)
+- Each version has a `## [X.Y.Z] - YYYY-MM-DD` header
+- Subsections: Added, Changed, Fixed, Removed, Deprecated, Security
+- For multi-version jumps, read ALL sections between current and target
+- Key things to flag:
+  - **Removed** entries -- breaking changes, must address before upgrading
+  - **Changed** entries -- behavioral changes, review for impact
+  - **Deprecated** entries -- action needed now or in a future version
+- Example: To upgrade from 0.3.1 to 0.4.0, read sections [0.3.2], [0.3.3], and [0.4.0]
+
+## Upgrade Command Internals
+
+How `bin/source_monitor upgrade` works internally:
+
+1. Reads `.source_monitor_version` from host app root (nil if first run)
+2. Compares stored version against `SourceMonitor::VERSION` (current gem version)
+3. If same: returns "Already up to date" with exit 0
+4. If different:
+   a. `MigrationInstaller.install` -- copies new engine migrations to `db/migrate/`
+   b. `InstallGenerator.run` -- re-runs the install generator (idempotent: skips existing routes, initializer, etc.)
+   c. `Verification::Runner.call` -- runs all 4 verifiers
+   d. Writes current version to `.source_monitor_version`
+5. Prints verification summary and exits (0 = all OK, 1 = any failure)
+
+Source: `lib/source_monitor/setup/upgrade_command.rb`
+
+## Post-Upgrade Verification
+
+The verification runner (`lib/source_monitor/setup/verification/runner.rb`) executes 4 verifiers in sequence:
+
+### PendingMigrationsVerifier
+
+Checks that all SourceMonitor migrations in the gem have corresponding files in host `db/migrate/`. Warns if any are missing or not yet run.
+
+**Fix:** `bin/rails db:migrate`
+
+### SolidQueueVerifier
+
+Checks that Solid Queue workers are running. Provides remediation guidance mentioning `Procfile.dev` for `bin/dev` users.
+
+**Fix:** Start workers via `bin/rails solid_queue:start` or ensure `Procfile.dev` has a `jobs:` entry.
+
+### RecurringScheduleVerifier
+
+Checks that SourceMonitor recurring tasks (ScheduleFetchesJob, scrape scheduling, cleanup jobs) are registered in Solid Queue. Verifies that `config/recurring.yml` exists and `config/queue.yml` dispatchers have `recurring_schedule: config/recurring.yml`.
+
+**Fix:** Re-run `bin/rails generate source_monitor:install` to patch `config/queue.yml` and create `config/recurring.yml`.
+
+### ActionCableVerifier
+
+Checks that Action Cable is configured with a production-ready adapter (Solid Cable or Redis). Development mode uses async adapter by default, which is not suitable for production.
+
+**Fix:** Add `solid_cable` gem or configure Redis adapter in `config/cable.yml`.
+
+## Troubleshooting Common Upgrade Issues
+
+### "Already up to date" but expected changes
+
+- Check that `bundle update source_monitor` actually pulled the new version
+- Verify `Gemfile.lock` shows the expected version: `grep source_monitor Gemfile.lock`
+- If the `.source_monitor_version` marker was manually edited, delete it and re-run `bin/source_monitor upgrade`
+
+### Migrations fail
+
+- Check for conflicting migration timestamps
+- Remove duplicate migration files from `db/migrate/` (keep the newer one)
+- Re-run `bin/rails db:migrate`
+
+### Deprecation errors at boot
+
+- Option was removed (`:error` severity)
+- Read the error message for the replacement option path
+- Update `config/initializers/source_monitor.rb` before restarting
+- Consult `docs/configuration.md` if unsure which option to use
+
+### Generator fails
+
+- Usually safe to re-run manually: `bin/rails generate source_monitor:install`
+- The generator is idempotent -- it skips existing routes, initializer, and config entries

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

@@ -0,0 +1,68 @@
+# Version-Specific Upgrade Notes
+
+Version-specific migration notes for each major/minor version transition. Agents should reference this file when guiding users through multi-version upgrades.
+
+## 0.3.x to 0.4.0
+
+**Released:** 2026-02-12
+
+**Key changes:**
+- Install generator now auto-patches `Procfile.dev` and `queue.yml` dispatcher config
+- New Active Storage image download feature (opt-in via `config.images.download_to_active_storage`)
+- SSL certificate store configuration added to HTTPSettings
+- RecurringScheduleVerifier and SolidQueueVerifier enhanced with better remediation messages
+- Netflix Tech Blog VCR cassette regression test added
+
+**Action items:**
+1. Re-run `bin/source_monitor upgrade` (or `bin/rails generate source_monitor:install`) to get Procfile.dev and queue.yml patches
+2. If using Active Storage image downloads, add `config.images.download_to_active_storage = true` to initializer
+3. If experiencing SSL certificate errors, new `config.http.ssl_ca_file`, `config.http.ssl_ca_path`, and `config.http.ssl_verify` settings are available
+4. No breaking changes -- all existing configuration remains valid
+
+## 0.2.x to 0.3.0
+
+**Released:** 2026-02-10
+
+**Key changes:**
+- Major refactoring: FeedFetcher, Configuration, ImportSessionsController, ItemCreator all extracted into smaller modules
+- Ruby autoload replaces eager requires in `lib/source_monitor.rb`
+- LogEntry no longer uses hard-coded table name
+- Skills system added (14 `sm-*` skills)
+- Upgraded to Ruby 4.0.1 and Rails 8.1.2
+
+**Action items:**
+1. If you monkey-patched or referenced internal classes (FeedFetcher internals, Configuration nested classes), check that your references still resolve
+2. Run `bin/source_monitor upgrade` to copy any new migrations
+3. Optionally install skills: `bin/rails source_monitor:skills:install`
+4. No configuration changes required -- public API unchanged
+
+## 0.1.x to 0.2.0
+
+**Released:** 2025-11-25
+
+**Key changes:**
+- OPML import wizard added with multi-step flow
+- ImportHistory model and migrations added
+- Health check enqueuing and Turbo Stream updates during wizard
+
+**Action items:**
+1. Copy and run new migrations: `bin/rails railties:install:migrations FROM=source_monitor && bin/rails db:migrate`
+2. No configuration changes required
+
+## Future Versions
+
+Template for documenting future upgrades:
+
+```
+## X.Y.Z to A.B.C
+Released: YYYY-MM-DD
+
+Key changes:
+- ...
+
+Action items:
+1. ...
+
+Deprecations:
+- `old_option` replaced by `new_option` (warning in A.B.C, removal planned for D.E.F)
+```

data/.vbw-planning/SHIPPED.md

@@ -26,3 +26,38 @@
 
 Location: `.vbw-planning/milestones/default/`
 Tag: `milestone/default`
+
+---
+
+## upgrade-assurance (2026-02-12 to 2026-02-13)
+
+**Goal:** Give host app developers confidence that gem updates go smoothly -- automated migration detection, upgrade command, config validation, and AI-assisted upgrade guidance.
+
+### Metrics
+
+| Metric | Value |
+|--------|-------|
+| Phases | 3 |
+| Plans completed | 3 |
+| Tasks completed | 14 |
+| Commits | 12 |
+| Requirements satisfied | 5/5 (REQ-26 through REQ-30) |
+| Tests | 1003 (up from 973) |
+
+### Phases
+
+1. Upgrade Command & Migration Verifier (1 plan, 5 tasks)
+2. Configuration Deprecation Framework (1 plan, 4 tasks)
+3. Upgrade Skill & Documentation (1 plan, 5 tasks)
+
+### Key Decisions
+
+- 3 phases: command, config, skill -- each independently valuable
+- `.source_monitor_version` marker file for version tracking
+- Deprecation registry with :warning and :error severities
+- sm-upgrade as a consumer skill (installed by default)
+
+### Archive
+
+Location: `.vbw-planning/milestones/upgrade-assurance/`
+Tag: `milestone/upgrade-assurance`

data/.vbw-planning/config.json

@@ -10,5 +10,26 @@
   "max_tasks_per_plan": 5,
   "agent_teams": true,
   "model_profile": "quality",
-  "model_overrides": {}
+  "model_overrides": {},
+  "context_compiler": true,
+  "v3_delta_context": false,
+  "v3_context_cache": false,
+  "v3_plan_research_persist": false,
+  "v3_metrics": false,
+  "v3_contract_lite": false,
+  "v3_lock_lite": false,
+  "v3_validation_gates": false,
+  "v3_smart_routing": false,
+  "v3_event_log": false,
+  "v3_schema_validation": false,
+  "v3_snapshot_resume": false,
+  "v3_lease_locks": false,
+  "v3_event_recovery": false,
+  "v3_monorepo_routing": false,
+  "v2_hard_contracts": false,
+  "v2_hard_gates": false,
+  "v2_typed_protocol": false,
+  "v2_role_isolation": false,
+  "v2_two_phase_completion": false,
+  "v2_token_budgets": false
 }

data/.vbw-planning/milestones/generator-enhancements/SHIPPED.md

@@ -0,0 +1,40 @@
+# Shipped: generator-enhancements
+
+**Shipped:** 2026-02-12
+**Tag:** milestone/generator-enhancements
+**Release:** v0.4.0
+
+## Summary
+
+Made the install generator and verification suite catch the two most common host-app setup failures: missing Procfile.dev jobs entry and missing recurring_schedule dispatcher wiring. Also added dashboard UX improvements, Active Storage image downloads, and SSL certificate store configuration.
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Phases | 7 (Phase 0-6) |
+| Plans completed | 7 |
+| Tasks completed | 34 |
+| Commits | ~26 |
+| Tests | 973 (up from 841) |
+| New requirements satisfied | 10 (REQ-16 through REQ-25) |
+
+## Phases
+
+1. Phase 0: Documentation Gaps (quick fix)
+2. Phase 1: Install Generator Steps (Procfile.dev + Queue Config)
+3. Phase 2: Recurring Schedule Verifier
+4. Phase 3: Skills & Documentation Alignment
+5. Phase 4: Dashboard UX Improvements
+6. Phase 5: Active Storage Image Downloads
+7. Phase 6: Netflix Feed Investigation (SSL cert store fix)
+
+## Key Decisions
+
+- Docs-first approach: shipped doc fixes before code changes
+- Always create/patch Procfile.dev for maximum hand-holding
+- Target queue.yml only (Rails 8 default)
+- External links open new tab with visual indicator icon
+- Fetch log URL display: domain for RSS, item URL for scrapes
+- Image downloads via background job to ItemContent (opt-in)
+- SSL fix: general cert store config, not Netflix-specific

data/.vbw-planning/milestones/upgrade-assurance/REQUIREMENTS.md

@@ -0,0 +1,80 @@
+<!-- VBW REQUIREMENTS TEMPLATE (ARTF-06) -- Structured requirements with traceability -->
+<!-- Created by Architect agent during /vbw scope -->
+
+# SourceMonitor Requirements
+
+Defined: 2026-02-09
+Core value: Drop-in Rails engine for feed monitoring, content scraping, and operational dashboards.
+
+## v1 Requirements
+
+### Test Coverage
+
+- [ ] **REQ-01**: Close coverage gaps in `FeedFetcher` -- add tests for uncovered branches in the fetch pipeline
+- [ ] **REQ-02**: Close coverage gaps in `ItemCreator` -- add tests for item creation edge cases
+- [ ] **REQ-03**: Close coverage gaps in `Configuration` -- test nested settings classes and edge cases
+- [ ] **REQ-04**: Close coverage gaps in `Dashboard::Queries` -- test dashboard query logic
+- [ ] **REQ-05**: Close coverage gaps in `Broadcaster` -- test realtime broadcasting logic
+- [ ] **REQ-06**: Close coverage gaps in `BulkSourceScraper` -- test bulk scraping workflows
+- [ ] **REQ-07**: Close coverage gaps in `SourcesIndexMetrics` -- test analytics calculations
+
+### Refactoring
+
+- [ ] **REQ-08**: Extract `FeedFetcher` (627 lines) into focused single-responsibility classes
+- [ ] **REQ-09**: Extract `Configuration` (655 lines) nested settings classes into separate files
+- [ ] **REQ-10**: Extract `ImportSessionsController` (792 lines) wizard steps into step-specific concerns or service objects
+- [ ] **REQ-11**: Fix `LogEntry` hard-coded table name to use configurable prefix system
+- [ ] **REQ-12**: Replace eager 102+ require statements in `lib/source_monitor.rb` with autoloading
+
+### Code Quality
+
+- [ ] **REQ-13**: Ensure frozen_string_literal is consistent across all Ruby files
+- [ ] **REQ-14**: Audit and fix any RuboCop violations against omakase ruleset
+- [ ] **REQ-15**: Ensure all models, controllers, and service objects follow Rails conventions
+
+### Generator Enhancements
+
+- [ ] **REQ-16**: Install generator patches `Procfile.dev` with a `jobs:` entry for Solid Queue
+- [ ] **REQ-17**: Install generator patches queue config dispatcher with `recurring_schedule: config/recurring.yml`
+- [ ] **REQ-18**: Guided workflow (`Setup::Workflow`) integrates both new generator steps
+- [ ] **REQ-19**: `RecurringScheduleVerifier` checks that recurring tasks are registered with Solid Queue
+- [ ] **REQ-20**: `SolidQueueVerifier` remediation suggests `Procfile.dev` when workers not detected
+- [ ] **REQ-21**: Skills and documentation updated to reflect automated Procfile.dev and recurring_schedule setup
+
+### Dashboard UX
+
+- [ ] **REQ-22**: Fetch logs show source URL for both success and failure entries on the dashboard
+- [ ] **REQ-23**: Dashboard links to sources and items are clickable and open in a new tab
+
+### Active Storage Image Downloads
+
+- [ ] **REQ-24**: Configurable option to download inline images from items to Active Storage instead of loading from source
+
+### Feed Compatibility
+
+- [ ] **REQ-25**: Investigate and fix failing fetch for Netflix Tech Blog feed (https://netflixtechblog.com/feed)
+
+### Upgrade Assurance
+
+- [ ] **REQ-26**: `bin/source_monitor upgrade` command detects version changes, copies new migrations, re-runs generator, and runs verification
+- [ ] **REQ-27**: `PendingMigrationsVerifier` checks for unmigrated SourceMonitor tables in the verification suite
+- [ ] **REQ-28**: Configuration deprecation framework warns on stale, renamed, or removed initializer options at boot time
+- [ ] **REQ-29**: `sm-upgrade` AI skill teaches agents how to handle gem updates with CHANGELOG parsing and step-by-step guidance
+- [ ] **REQ-30**: Upgrade guide documentation (`docs/upgrade.md`) with version-specific instructions
+
+## v2 Requirements
+
+- [ ] **REQ-XX**: Improve optional dependency loading with clear error messages
+- [ ] **REQ-XX**: Add database index verification tooling
+- [ ] **REQ-XX**: Document health check endpoint response format
+
+## Out of Scope
+
+| Item | Reason |
+|------|--------|
+| Multi-database support (MySQL/SQLite) | PostgreSQL-only simplifies development |
+| Built-in authentication | Host app responsibility |
+
+## Traceability
+
+Requirement-to-phase mapping is tracked in ROADMAP.md.

data/.vbw-planning/milestones/upgrade-assurance/ROADMAP.md

@@ -0,0 +1,75 @@
+<!-- VBW ROADMAP -- Phase decomposition with requirement mapping -->
+<!-- Created during /vbw scope -->
+
+# SourceMonitor Upgrade Assurance Roadmap
+
+**Milestone:** upgrade-assurance
+**Goal:** Give host app developers confidence that gem updates go smoothly -- automated migration detection, upgrade command, config validation, and AI-assisted upgrade guidance.
+
+## Phases
+
+1. [x] Phase 1: Upgrade Command & Migration Verifier
+2. [x] Phase 2: Configuration Deprecation Framework
+3. [x] Phase 3: Upgrade Skill & Documentation
+
+## Phase Details
+
+### Phase 1: Upgrade Command & Migration Verifier
+
+**Goal:** Add `bin/source_monitor upgrade` that detects version changes since last install, copies new migrations, re-runs the idempotent generator, runs verification, and reports what changed. Also add a `PendingMigrationsVerifier` to the existing verification suite.
+
+**Requirements:** REQ-26, REQ-27
+
+**Success Criteria:**
+- `bin/source_monitor upgrade` compares stored version marker against `SourceMonitor::VERSION`
+- If version changed: copies new migrations, re-runs generator, runs `bin/source_monitor verify`
+- If no version change: reports "Already up to date" with current version
+- `PendingMigrationsVerifier` checks `db:migrate:status` for unmigrated SourceMonitor migrations
+- Verifier integrated into `bin/source_monitor verify` and the upgrade flow
+- Version marker stored in host app (e.g., `.source_monitor_version` or DB-backed)
+- `bin/rails test` passes, RuboCop clean
+
+### Phase 2: Configuration Deprecation Framework
+
+**Goal:** Add a lightweight framework that warns host app developers when their initializer uses config options that have been renamed, removed, or have changed defaults. Warnings appear at boot time via Rails logger.
+
+**Requirements:** REQ-28
+
+**Success Criteria:**
+- Engine maintains a deprecation registry (option name, version deprecated, replacement if any)
+- At configuration load time, deprecated option usage triggers a Rails.logger.warn with actionable message
+- Removed options that are still referenced raise a clear error with migration path
+- Framework is opt-in for engine developers (simple DSL to register deprecations)
+- Zero false positives on current valid configuration
+- `bin/rails test` passes, RuboCop clean
+
+### Phase 3: Upgrade Skill & Documentation
+
+**Goal:** Create an `sm-upgrade` AI skill that guides agents through post-update workflows, and write a versioned upgrade guide for human developers.
+
+**Requirements:** REQ-29, REQ-30
+
+**Success Criteria:**
+- `sm-upgrade` skill covers: reading CHANGELOG between versions, running upgrade command, interpreting results, handling edge cases
+- Skill references the upgrade command and verification suite
+- `docs/upgrade.md` includes: general upgrade steps, version-specific notes (0.3.x → 0.4.x), troubleshooting
+- Skills installer updated to include `sm-upgrade` in consumer set
+- Existing `sm-host-setup` skill cross-references upgrade flow
+
+## Progress
+
+| Phase | Status | Plans |
+|-------|--------|-------|
+| 1 | Complete | PLAN-01 (5 tasks, 5 commits) |
+| 2 | Complete | PLAN-01 (4 tasks, 3 commits) |
+| 3 | Complete | PLAN-01 (5 tasks, 4 commits) |
+
+## Requirement Mapping
+
+| REQ | Phase | Description |
+|-----|-------|-------------|
+| REQ-26 | 1 | Upgrade command with version detection and auto-remediation |
+| REQ-27 | 1 | PendingMigrationsVerifier in verification suite |
+| REQ-28 | 2 | Config deprecation framework with boot-time warnings |
+| REQ-29 | 3 | sm-upgrade AI skill for agent-guided updates |
+| REQ-30 | 3 | Upgrade guide documentation |

data/.vbw-planning/milestones/upgrade-assurance/STATE.md

@@ -0,0 +1,29 @@
+<!-- VBW STATE -- Current milestone progress -->
+
+# State
+
+**Milestone:** upgrade-assurance
+**Current Phase:** All phases complete
+**Status:** Ready to archive
+**Date:** 2026-02-13
+
+## Progress
+
+- Phase 1: Complete (1 plan, 5 tasks, 5 commits) -- QA PASS 34/34
+- Phase 2: Complete (1 plan, 4 tasks, 3 commits)
+- Phase 3: Complete (1 plan, 5 tasks, 4 commits) -- QA PASS 37/38
+
+## Decisions
+
+| Decision | Date | Rationale |
+|----------|------|-----------|
+| 3 phases: command, config, skill | 2026-02-12 | Each independently valuable; command is foundational |
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Phases | 3 |
+| Plans completed | 3 |
+| Tasks completed | 14 |
+| Tests | 1003 |