source_monitor 0.13.1 → 0.14.0

data/docs/goals/engine-hardening/goal.md

@@ -0,0 +1,97 @@
+# Engine Hardening: auth defaults, notification scoping, gem packaging
+
+## Objective
+
+Implement the three specced engine-hardening issues end-to-end and verified:
+
+- #129 — Fail-closed engine access when no auth handler is configured (+ explicit `open_access`/demo opt-in)
+- #130 — Scope notification toasts to prevent cross-user leakage (request-flash path AND background-broadcast path)
+- #131 — Exclude `.claude` internals from the packaged gem, keep `sm-*` skills
+
+Each issue's acceptance-criteria checkboxes must be satisfied and the repo gates must be green.
+
+## Original Request
+
+"these 3 issues" — referring to #129, #130, #131, which were just broken out of umbrella #128 (PRD #127) and given codebase-validated Technical Specs via `issues-to-specs`.
+
+## Intake Summary
+
+- Input shape: `existing_plan` — each issue already has a `## Technical Spec` with behavior slices, tracer bullet, posture, and acceptance-criteria mapping.
+- Audience: SourceMonitor engine maintainer (dchuk) + host apps consuming the `source_monitor` gem.
+- Authority: `requested` — user wants the work implemented.
+- Proof type: `test`
+- Completion proof: every acceptance-criteria checkbox on #129/#130/#131 checked, and all four gates green.
+- Goal oracle: the four repo gates plus the new behavior-slice tests added per issue, mapped back to each issue's acceptance criteria.
+- Likely misfire: (1) declaring done after planning/discovery only; (2) shipping #129 fail-closed without the `open_access` opt-in + dummy-app update landing together, breaking the dummy app and existing controller tests; (3) entangling all three fixes in one commit instead of one coherent commit per issue; (4) "fixing" #130 by deleting toasts rather than scoping/decontextualizing them.
+- Blind spots considered: #129 is an intentional breaking change needing a CHANGELOG/upgrade note; #130 has TWO global-stream leak paths (`ApplicationController#broadcast_flash_toasts` for request flashes AND `Broadcaster#broadcast_toast` for background events) — both must be addressed; the three issues are independent (no blocker ordering) but each is its own vertical slice + commit; CI diff-coverage gate requires tests for every new rescue/fallback branch.
+- Existing plan facts: the three GitHub issues and their Technical Specs are the authoritative plan. Preserve them; validate against current HEAD before writing.
+
+## Goal Oracle
+
+The oracle for this goal is:
+
+`rbenv exec bin/rails test` (incl. new per-issue behavior tests) + `rbenv exec bin/rubocop` + `rbenv exec bin/brakeman --no-pager` + `cd test/dummy && rbenv exec bundle exec rails zeitwerk:check`, ALL green, with each acceptance-criteria checkbox on #129/#130/#131 satisfied by a named test or evidence.
+
+The PM must keep comparing task receipts to this oracle. A passing single issue is not full completion — all three issues must be implemented, verified, and their checkboxes mapped to evidence before `full_outcome_complete: true`.
+
+## Goal Kind
+
+`existing_plan`
+
+## Current Tranche
+
+Continuous execution. Validate the three specs against HEAD, then implement one coherent reversible Worker package per issue (suggested order: #131 packaging → #130 notifications → #129 auth, lowest-to-highest blast radius), verifying each package against the gates before advancing. Review only at the final completion boundary unless a package's verification is rejected or its behavior turns out ambiguous. Finish only when all three issues are implemented, verified, and audited complete.
+
+## Non-Negotiable Constraints
+
+- Follow project conventions in `CLAUDE.md`: Minitest (no RSpec/FactoryBot), `create_source!`/`with_inline_jobs` helpers, `SourceMonitor.reset_configuration!` per test, Tailwind/Hotwire, RuboCop omakase, Brakeman clean.
+- One coherent commit per issue (auto_commit is on); do not entangle the three fixes.
+- #129 fail-closed enforcement and its `open_access`/demo opt-in + dummy-app update + CHANGELOG note must land together in the same package.
+- #130 must address BOTH leak paths; request flashes stay response-local, background operational toasts are scoped or stripped of per-user/request context. Do not delete the toast feature.
+- #131 must only touch gemspec file-selection + one packaging test; do not change gem metadata or dependencies.
+- No new runtime dependency. No schema changes. Preserve existing public config/handler API shape.
+- Run the full local CI equivalent (all four gates) before considering any package done; write tests for every new rescue/fallback branch (CI diff-coverage gate).
+- Never read/output protected files (`config/master.key`, `.env*`, credentials, `*.key`/`*.pem`).
+
+## Stop Rule
+
+Stop only when a final audit proves all three issues are implemented, verified, and their acceptance criteria are satisfied.
+
+Do not stop after plan validation or after a single issue's package passes — advance to the next issue's package.
+
+Mark a specific package blocked (with a receipt) only if it genuinely needs owner input (e.g. confirming the `open_access` opt-in name, or whether background toasts should exist at all); keep doing the other safe local packages meanwhile.
+
+## Slice Sizing
+
+One Worker package per issue is the natural vertical slice — each delivers a verified, independently-committable outcome mapped to a real issue. #131 is small but legitimately isolated (gemspec + one test); it is not a "tiny task" anti-pattern. Each Worker completes its whole issue (code + tests + docs/CHANGELOG where the spec requires) before handing back.
+
+## Canonical Board
+
+Machine truth lives at:
+
+`docs/goals/engine-hardening/state.yaml`
+
+If this charter and `state.yaml` disagree, `state.yaml` wins.
+
+## Run Command
+
+```text
+/goal Follow docs/goals/engine-hardening/goal.md.
+```
+
+## PM Loop
+
+On every `/goal` continuation:
+
+1. Read this charter.
+2. Read `state.yaml`.
+3. Run the bundled GoalBuddy update checker when available; mention a newer version without blocking.
+4. Re-check intake: original request, existing-plan facts, authority, proof, blind spots, likely misfire.
+5. Work only on the active board task.
+6. Assign Scout, Judge, Worker, or PM according to the task.
+7. Write a compact task receipt.
+8. Update the board.
+9. If safe local work remains, activate the next Worker package and continue.
+10. Record any operator-escalation issue/PR decision in a receipt; `state.yaml` stays authoritative.
+11. Review only at final completion (or rejected verification / ambiguity), not after every Worker.
+12. Finish only with a Judge/PM audit receipt that maps all three issues' criteria + the four gates back to the original outcome and records `full_outcome_complete: true`.

data/docs/goals/engine-hardening/notes/T001-spec-validation.md

@@ -0,0 +1,37 @@
+# T001 — Judge spec validation (full receipt)
+
+Decision: **approved_with_notes** · go for T002 · full_outcome_complete: false · sequence #131 -> #130 -> #129 OK · parallel NOT allowed (T003 & T004 share application_controller.rb; safe only serially).
+
+## Per-issue
+
+### #131 (packaging) — spec_valid: true, no material drift
+- `source_monitor.gemspec:25-31` reject list omits `.claude/`; line 30 `Dir[".claude/skills/sm-*/**/*"]` re-adds 39 sm-* files.
+- Currently **64 non-sm `.claude` files ship** (agents/commands/hooks/agent-memory + ~17 non-sm skills).
+- Adding `.claude/` to reject list is correct + sufficient.
+- `test/integration/release_packaging_test.rb:65` already runs `gem build source_monitor.gemspec`, proving gemspec loads from repo root → new `test/gemspec_packaging_test.rb` is safe.
+
+### #130 (notifications) — spec_valid: true, with drift
+- **DRIFT:** spec said "no broadcaster test file"; `test/lib/source_monitor/realtime/broadcaster_test.rb` ALREADY EXISTS (19KB), already stubs `Turbo::StreamsChannel.broadcast_append_to` and tests `broadcast_toast` (lines 151-189). Worker **extends**, not creates.
+- Both leak paths confirmed: (a) `application_controller.rb:63-79` `broadcast_flash_toasts` after_action → `Realtime.broadcast_toast` per flash; (b) `broadcaster.rb:66-85` `broadcast_toast` → `NOTIFICATION_STREAM = "source_monitor_notifications"`.
+- Layout subscribes globally: `application.html.erb:15`. `StreamResponder#toast` (`stream_responder.rb:43-54`) is response-local (good).
+- **Two extra background `broadcast_toast` call sites the spec missed:** `lib/source_monitor/health/source_health_check_orchestrator.rb:57` and `lib/source_monitor/fetching/feed_fetcher/source_updater.rb:196` (auto-pause). Both source-operational → fit the "keep global, context-free" default; Worker should be aware.
+
+### #129 (auth) — spec_valid: true, with critical drift
+- **DRIFT (critical):** dummy-initializer-only opt-in does NOT keep suite green. `test/test_helper.rb:85-89` calls `SourceMonitor.reset_configuration!` in EVERY test setup (rebuilds `Configuration.new` at `lib/source_monitor.rb:236`), wiping the dummy initializer's `open_access` per-test. `test/test_helper.rb` was NOT in #129's named files.
+- Silent no-op confirmed: `authentication.rb:42-46` `call_handler` returns early when handler nil. before_actions `application_controller.rb:7-8`. `authentication_settings.rb:39-44` `reset!` present (add `open_access` reset there).
+- ~24 of 26 controller/integration test files hit real engine routes with NO handler and expect 200 → all 403 under fail-closed unless the shared harness opts in.
+- Must flip `test/controllers/source_monitor/application_controller_test.rb:28-31` ("skips authentication when host has not configured it" asserts `:success`) → assert `:forbidden`.
+
+Tests relying on implicit open access (must be handled via test_helper open_access enablement):
+sources, dashboard, items, source_fetches, health, bulk_scrape_enablements, fetch_logs, item_scrapes, logs, scrape_logs, source_bulk_scrapes, source_favicon_fetches, source_health_checks, source_health_resets, source_retries, source_scrape_tests, sources_favicon, sources_sort controllers; integration: engine_mounting, navigation, favicon_integration.
+
+## Required board updates (PM applied)
+1. T004 allowed_files += `test/test_helper.rb` (enable open_access in per-test setup). **Most important** — without it the suite can't pass.
+2. T004 must flip `application_controller_test.rb:28-31` → `:forbidden`.
+3. T003: extend existing `broadcaster_test.rb`; aware of the two extra background toast sites.
+4. T003 & T004 serial-only (shared application_controller.rb).
+
+## Owner questions (all non-blocking, workable defaults)
+- #130: keep background toasts global+context-free (default) vs remove entirely.
+- #129: opt-in name `open_access` (default, adjustable).
+- #129: enable open_access in test_helper (default, lowest churn) vs per-file configure_authentication.

data/docs/goals/engine-hardening/state.yaml

@@ -0,0 +1,324 @@
+# GoalBuddy v2 state.yaml
+# Board truth lives here. goal.md is the editable charter; notes/ holds long receipts only.
+
+version: 2
+
+goal:
+  title: "Engine Hardening: auth defaults, notification scoping, gem packaging"
+  slug: "engine-hardening"
+  kind: existing_plan # specific | open_ended | existing_plan | recovery | audit
+  tranche: "Validate 3 specs against HEAD, then implement one verified Worker package per issue (#131 -> #130 -> #129), then audit all three complete."
+  status: done # active | blocked | done
+  oracle:
+    signal: "rbenv exec bin/rails test + rbenv exec bin/rubocop + rbenv exec bin/brakeman --no-pager + (cd test/dummy && rbenv exec bundle exec rails zeitwerk:check) ALL green, with every acceptance-criteria checkbox on #129/#130/#131 mapped to a named test or evidence."
+    cadence: "after each Worker package and at final audit"
+    final_proof: "Three done Worker receipts (one per issue) with green gate commands, plus a Judge/PM audit mapping each issue's criteria to evidence."
+  intake:
+    original_request: "these 3 issues (#129, #130, #131)"
+    interpreted_outcome: "Implement and verify all three engine-hardening issues; satisfy each issue's acceptance criteria with the repo gates green."
+    input_shape: existing_plan
+    audience: "SourceMonitor engine maintainer + host apps consuming the gem"
+    authority: requested
+    proof_type: test
+    completion_proof: "All acceptance-criteria checkboxes on #129/#130/#131 satisfied AND all four repo gates green."
+    likely_misfire: "Declaring done after planning; or shipping #129 fail-closed without the open_access opt-in + dummy update, breaking the dummy app/tests; or entangling all 3 in one commit; or deleting toasts instead of scoping them in #130."
+    blind_spots_considered:
+      - "#129 is an intentional breaking change needing a CHANGELOG/upgrade note + dummy-app opt-in landing together."
+      - "#130 has TWO global-stream leak paths: ApplicationController#broadcast_flash_toasts (request flashes) AND Broadcaster#broadcast_toast (background events). Both must be fixed."
+      - "Issues are independent (no blocker ordering) but each is its own vertical slice + commit."
+      - "CI diff-coverage gate requires a test for every new rescue/fallback branch."
+    existing_plan_facts:
+      - "GitHub issue #131: exclude .claude/ from gemspec git ls-files filter, keep .claude/skills/sm-*; add test/gemspec_packaging_test.rb. Spec validated against source_monitor.gemspec lines 23-31 (.claude/ NOT in reject list)."
+      - "GitHub issue #130: StreamResponder#toast is already response-local; leaks are ApplicationController#broadcast_flash_toasts and Realtime::Broadcaster#broadcast_toast -> global 'source_monitor_notifications' stream subscribed by every tab via layouts/source_monitor/application.html.erb:15. Add test/lib/source_monitor/realtime/broadcaster_test.rb (none exists yet)."
+      - "GitHub issue #129: Security::Authentication.authenticate!/authorize! call_handler is a silent no-op when handler nil. authentication_configured? predicate already exists. Add open_access opt-in on Configuration::AuthenticationSettings (reset in reset!), enforce in Security::Authentication, deny via :forbidden following ApplicationController#record_not_found multi-format pattern. Dummy initializer (test/dummy/config/initializers/source_monitor.rb) currently sets NO auth handler -> must opt into open_access. AuthenticationHelpers#configure_authentication covers the handler-honored path."
+      - "Source: issues #129/#130/#131 carry full ## Technical Spec sections written by issues-to-specs; parent umbrella #128; PRD #127."
+
+rules:
+  pm_owns_state: true
+  one_active_task: true
+  max_write_workers: 1
+  no_implementation_without_worker_or_pm_task: true
+  no_completion_without_judge_or_pm_audit: true
+  planning_is_not_completion: true
+  queued_required_worker_blocks_completion: true
+  continuous_until_full_outcome: true
+  missing_input_or_credentials_do_not_stop_goal: true
+  preserve_and_validate_existing_plan: true
+  intake_misfire_must_be_audited: true
+  goal_pressure_requires_oracle: true
+  no_completion_on_weak_proof: true
+  slice_policy:
+    max_consecutive_tiny_tasks: 2
+    prefer_vertical_slices: true
+    judge_picks_largest_safe_slice: true
+    worker_completes_whole_slice: true
+
+agents:
+  # installed | bundled_not_installed | missing | unknown
+  scout: installed       # ~/.claude/agents/goal-scout.md verified
+  worker: installed      # ~/.claude/agents/goal-worker.md verified
+  judge: installed       # ~/.claude/agents/goal-judge.md verified
+
+visual_board:
+  # none | local | unknown
+  selected: local
+  local:
+    status: live # not_requested | starting | live | generated | blocked
+    url: "http://goalbuddy.localhost:41737/engine-hardening/"
+    command: "npx goalbuddy board docs/goals/engine-hardening"
+
+active_task: null
+
+tasks:
+  - id: T001
+    type: judge
+    assignee: Judge
+    status: done
+    reasoning_hint: medium
+    objective: "Validate the three issue Technical Specs against current HEAD, confirm the leak paths / fail-open behavior / gemspec filter still match the code, and confirm the Worker package sequence and allowed_files for T002-T004."
+    inputs:
+      - "GitHub issues #129, #130, #131 (## Technical Spec sections)"
+      - "source_monitor.gemspec"
+      - "lib/source_monitor/security/authentication.rb"
+      - "lib/source_monitor/configuration/authentication_settings.rb"
+      - "app/controllers/source_monitor/application_controller.rb"
+      - "lib/source_monitor/realtime/broadcaster.rb"
+      - "lib/source_monitor/turbo_streams/stream_responder.rb"
+      - "app/views/layouts/source_monitor/application.html.erb"
+      - "test/dummy/config/initializers/source_monitor.rb"
+    constraints:
+      - "Read-only. Do not edit implementation files."
+      - "Preserve the issue specs as plan facts; only flag conflicts with HEAD."
+      - "Do not collapse the three issues into one package; keep one Worker package per issue."
+    expected_output:
+      - "Per-issue: spec still valid? any drift from HEAD?"
+      - "Confirmed allowed_files + verify commands for T002 (#131), T003 (#130), T004 (#129)"
+      - "Any owner question needed before a package can proceed (e.g. open_access naming)"
+      - "Go/no-go to start T002"
+    receipt:
+      result: done
+      decision: approved_with_notes
+      full_outcome_complete: false
+      note: notes/T001-spec-validation.md
+      summary: "All 3 specs valid vs HEAD (evidence cited). go for T002. Two critical board updates applied: T004 +test/test_helper.rb (reset_configuration! wipes dummy open_access per-test; ~24 tests would 403) and flip application_controller_test.rb:28-31 to :forbidden; T003 extends existing broadcaster_test.rb (spec wrongly said it was missing) + aware of 2 extra background toast sites. Sequence #131->#130->#129 OK; T003/T004 serial-only (shared application_controller.rb)."
+      owner_questions_blocking: []
+
+  - id: T002
+    type: worker
+    assignee: Worker
+    status: done
+    reasoning_hint: medium
+    objective: "Implement #131: exclude .claude/ internals from the packaged gem while keeping .claude/skills/sm-*; add a packaging test."
+    allowed_files:
+      - "source_monitor.gemspec"
+      - "test/gemspec_packaging_test.rb"
+    verify:
+      - "rbenv exec bin/rails test test/gemspec_packaging_test.rb"
+      - "rbenv exec bin/rubocop"
+    stop_if:
+      - "Need files outside allowed_files."
+      - "git ls-files unavailable in the test env (use stubbed file-list approach per spec risk note)."
+      - "Verification fails twice."
+    receipt:
+      result: done
+      changed_files:
+        - source_monitor.gemspec
+        - test/gemspec_packaging_test.rb
+      commands:
+        - cmd: "bin/rails test test/gemspec_packaging_test.rb"
+          status: pass
+        - cmd: "bin/rubocop (505 files)"
+          status: pass
+      summary: "Added '.claude/' to the gemspec reject-prefix list; existing Dir[.claude/skills/sm-*] re-include keeps only sm-* skills. New test/gemspec_packaging_test.rb asserts no .claude internals ship, only sm-* under .claude/, sm-host-setup present, app/+lib/ intact. spec.files: 427 total, 54 .claude (all sm-*), 0 non-sm .claude. Committed 846d612, Closes #131."
+      notes: "IMPORTANT for later tasks: 'rbenv exec bin/rails' fails (rbenv exec resolves via PATH, not relative path). Use 'bin/rails'/'bin/rubocop' directly (already rbenv-shimmed) or 'rbenv exec rails'. Live HEAD has 54 sm-* skill files (T001 said 39); test does not hard-code count."
+
+  - id: T003
+    type: worker
+    assignee: Worker
+    status: done
+    reasoning_hint: medium
+    objective: "Implement #130: stop request flashes broadcasting to the global notification stream (keep them response-local) and scope or decontextualize background Broadcaster toasts; EXTEND the existing broadcaster test to prove no cross-user leakage. Do not delete the toast feature."
+    constraints:
+      - "T001 finding: test/lib/source_monitor/realtime/broadcaster_test.rb ALREADY EXISTS (stubs Turbo::StreamsChannel.broadcast_append_to) -- EXTEND it, do not recreate."
+      - "Two leak paths to fix: (a) ApplicationController#broadcast_flash_toasts:63-79 (request flashes -> global) keep response-local; (b) Broadcaster#broadcast_toast:66-85 (background fetch/scrape) keep global but context-free OR scope per spec default."
+      - "Be aware of 2 more background broadcast_toast call sites (source_health_check_orchestrator.rb:57, source_updater.rb:196 auto-pause) -- source-operational, context-free is fine."
+      - "Serial-only with T004 (shared application_controller.rb); never run in parallel."
+    allowed_files:
+      - "lib/source_monitor/realtime/broadcaster.rb"
+      - "app/controllers/source_monitor/application_controller.rb"
+      - "lib/source_monitor/turbo_streams/stream_responder.rb"
+      - "app/views/layouts/source_monitor/application.html.erb"
+      - "test/lib/source_monitor/realtime/broadcaster_test.rb"
+      - "test/controllers/source_monitor/**"
+    verify:
+      - "rbenv exec bin/rails test test/lib/source_monitor/realtime/broadcaster_test.rb"
+      - "rbenv exec bin/rails test"
+      - "rbenv exec bin/rubocop"
+    stop_if:
+      - "Need files outside allowed_files."
+      - "Scoped-stream vs context-free-global decision turns out ambiguous beyond the spec default (escalate to owner)."
+      - "Verification fails twice."
+    receipt:
+      result: done
+      changed_files:
+        - app/controllers/source_monitor/application_controller.rb
+        - app/views/layouts/source_monitor/application.html.erb
+        - test/controllers/source_monitor/application_controller_test.rb
+        - test/lib/source_monitor/realtime/broadcaster_test.rb
+      commands:
+        - cmd: "bin/rails test test/lib/source_monitor/realtime/broadcaster_test.rb"
+          status: pass
+        - cmd: "bin/rails test (full suite, 1736 runs)"
+          status: pass
+        - cmd: "bin/rubocop (505 files)"
+          status: pass
+      summary: "Removed the after_action broadcasting request flashes to the global ActionCable stream. Request flashes now render inline on HTML loads (source_monitor_flash_toasts helper into existing #source_monitor_notifications container) and append to the turbo_stream response body -- reaching only the requesting tab. Background operational broadcast_toast left global + context-free (decision: source-operational data, not per-user). Fixed a flash.discard timing bug that wiped flashes across redirects. Committed c4e5626, Closes #130."
+      notes: "Did not touch broadcaster.rb or stream_responder.rb (in allowed_files but unneeded -- the leak was the controller after_action). Background toast posture = keep global, context-free (documented default; not scoped per-session, avoiding over-engineering)."
+
+  - id: T004
+    type: worker
+    assignee: Worker
+    status: done
+    reasoning_hint: high
+    objective: "Implement #129: fail-closed engine access by default when no auth handler is configured; add explicit open_access/demo opt-in; opt the dummy app AND the test harness in; honor configured handlers; update docs/initializer template + CHANGELOG. Land enforcement + opt-in + dummy/test-harness update together."
+    constraints:
+      - "CRITICAL (T001 finding): dummy initializer alone is NOT enough -- test/test_helper.rb:85-89 runs SourceMonitor.reset_configuration! every test, wiping open_access. MUST enable open_access in test/test_helper.rb setup (or per-file) or ~24 controller/integration tests will 403."
+      - "Flip test/controllers/source_monitor/application_controller_test.rb:28-31 (currently asserts :success with no auth) to assert :forbidden -- this is the explicit fail-closed assertion."
+      - "Add a test that open_access=true restores 200, and that configured handlers (AuthenticationHelpers#configure_authentication) still allow access."
+      - "Reset open_access in AuthenticationSettings#reset! (authentication_settings.rb:39-44)."
+      - "Serial-only with T003 (shared application_controller.rb); never run in parallel."
+    allowed_files:
+      - "lib/source_monitor/security/authentication.rb"
+      - "lib/source_monitor/configuration/authentication_settings.rb"
+      - "app/controllers/source_monitor/application_controller.rb"
+      - "test/dummy/config/initializers/source_monitor.rb"
+      - "test/test_helper.rb"
+      - "test/lib/source_monitor/configuration/authentication_settings_test.rb"
+      - "test/controllers/source_monitor/**"
+      - "test/integration/**"
+      - "lib/generators/**"
+      - "docs/**"
+      - "CHANGELOG.md"
+    verify:
+      - "rbenv exec bin/rails test"
+      - "rbenv exec bin/rubocop"
+      - "rbenv exec bin/brakeman --no-pager"
+      - "cd test/dummy && rbenv exec bundle exec rails zeitwerk:check"
+    stop_if:
+      - "Need files outside allowed_files."
+      - "open_access opt-in naming/posture needs owner confirmation (escalate, do not guess past the spec default)."
+      - "Existing tests rely on implicit open access in a way the spec did not anticipate."
+      - "Verification fails twice."
+    receipt:
+      result: done
+      changed_files:
+        - lib/source_monitor/security/authentication.rb
+        - lib/source_monitor/configuration/authentication_settings.rb
+        - app/controllers/source_monitor/application_controller.rb
+        - test/dummy/config/initializers/source_monitor.rb
+        - test/test_helper.rb
+        - test/lib/source_monitor/configuration/authentication_settings_test.rb
+        - test/controllers/source_monitor/application_controller_test.rb
+        - test/controllers/source_monitor/source_favicon_fetches_controller_test.rb
+        - test/controllers/source_monitor/sources_controller_favicon_test.rb
+        - test/integration/source_monitor/favicon_integration_test.rb
+        - lib/generators/source_monitor/install/templates/source_monitor.rb.tt
+        - docs/configuration.md
+        - docs/deployment.md
+        - docs/setup.md
+        - CHANGELOG.md
+      commands:
+        - cmd: "bin/rails test (1741 runs, 0 failures)"
+          status: pass
+        - cmd: "bin/rubocop (505 files)"
+          status: pass
+        - cmd: "bin/brakeman --no-pager (0 warnings)"
+          status: pass
+        - cmd: "cd test/dummy && bin/rails zeitwerk:check"
+          status: pass
+      summary: "Fail-closed engine access. open_access bool (default false, reset in reset!) on AuthenticationSettings. Security::Authentication.access_denied_by_default? denies when no handler configured AND open_access false; configured handlers short-circuit. ApplicationController enforce_source_monitor_access_default first before_action renders :forbidden (html/turbo_stream/json, mirrors record_not_found) and halts chain. test_helper opts open_access=true after reset_configuration!; 3 self-resetting test files re-opt-in; application_controller_test flips to :forbidden + adds open_access on/off + handler tests. Install template, docs, CHANGELOG (BREAKING) updated. Committed 1dc03fe, Closes #129."
+      notes: "REQUIRED FOLLOW-UP -> T005: sm-* skill references (sm-configure, sm-host-setup) document the auth config DSL but live under .claude/skills/ (outside T004 allowed_files). Project CLAUDE.md 'Skills & docs alignment' rule requires them updated in the SAME PR when engine config changes. Created T005 to satisfy this."
+
+  - id: T005
+    type: worker
+    assignee: Worker
+    status: done
+    reasoning_hint: medium
+    objective: "Satisfy the project 'Skills & docs alignment' maintenance rule: update the sm-* skill references that document the authentication config DSL to reflect the new fail-closed default and the open_access opt-in (from #129)."
+    constraints:
+      - "Only update skill content that documents authentication/config defaults; do not alter unrelated skill text."
+      - "Match the wording/posture already used in docs/configuration.md + the install template (fail-closed default; open_access = true is demo/non-production only)."
+      - "Note: #131 excludes .claude internals from the gem EXCEPT .claude/skills/sm-*, so these skills DO still ship -- the maintenance rule applies."
+    allowed_files:
+      - ".claude/skills/sm-configure/**"
+      - ".claude/skills/sm-host-setup/**"
+    verify:
+      - "grep -ril 'open_access' .claude/skills/sm-configure .claude/skills/sm-host-setup"
+      - "bin/rubocop"
+    stop_if:
+      - "Need files outside allowed_files."
+      - "An sm-* skill has no authentication/config section to update (report which, then proceed with the ones that do)."
+    receipt:
+      result: done
+      changed_files:
+        - .claude/skills/sm-configure/SKILL.md
+        - .claude/skills/sm-configure/reference/configuration-reference.md
+        - .claude/skills/sm-host-setup/SKILL.md
+        - .claude/skills/sm-host-setup/reference/initializer-template.md
+        - .claude/skills/sm-host-setup/reference/setup-checklist.md
+      commands:
+        - cmd: "grep -ril open_access .claude/skills/sm-configure .claude/skills/sm-host-setup (5 files)"
+          status: pass
+        - cmd: "bin/rubocop (505 files)"
+          status: pass
+      summary: "Updated sm-configure + sm-host-setup skills to document fail-closed default + open_access opt-in, mirroring docs/ and the install template. Auth sections only; unrelated content untouched. Committed 834560c, Refs #129."
+      notes: "Satisfies the CLAUDE.md Skills & docs alignment maintenance rule for the #129 config change."
+
+  - id: T999
+    type: judge
+    assignee: Judge
+    status: done
+    reasoning_hint: high
+    objective: "Audit whether all three issues (#129, #130, #131) are implemented and verified, mapping each issue's acceptance criteria to test/evidence and confirming all four gates are green."
+    inputs:
+      - "T002, T003, T004 receipts"
+      - "Acceptance criteria on #129, #130, #131"
+      - "Last verification (all four gates)"
+      - "Current dirty diff"
+    constraints:
+      - "Do not implement."
+      - "Reject completion if any required Worker package is still queued/active or any gate is red."
+      - "Reject completion if any acceptance-criteria checkbox lacks evidence."
+      - "Map completion back to the original 3-issue outcome."
+    expected_output:
+      - "complete | not_complete"
+      - "full_outcome_complete: true | false"
+      - "per-issue criteria -> evidence map"
+      - "missing evidence / next task if not complete"
+    receipt:
+      result: done
+      decision: complete
+      full_outcome_complete: true
+      gates:
+        tests: "pass (1741 runs, 0 failures/errors/skips)"
+        rubocop: "pass (505 files, 0 offenses)"
+        brakeman: "pass (0 warnings)"
+        zeitwerk: "pass"
+      summary: "Independent audit re-ran 68 targeted tests + evaluated gemspec directly. All acceptance criteria on #131/#130/#129 map to committed code with tests that genuinely assert the behavior. #131: spec.files has 0 non-sm .claude files, 54 sm-* files, sm-host-setup present; packaging test asserts both. #130: global broadcast_flash_toasts after_action removed, replaced with response-local delivery, proven by assert_empty broadcast_calls; background toasts still render. #129: enforce_source_monitor_access_default is FIRST before_action, renders :forbidden and halts chain; tests cover deny-by-default / open_access / configured-handler / default+reset; dummy+harness+docs+template+CHANGELOG+sm-* skills all updated. No gaps."
+      missing_evidence: []
+      next_task_if_not_complete: null
+
+checks:
+  dirty_fingerprint: "branch harden-engine-access-129-131; 5 issue commits (846d612 #131, c4e5626 #130, 1dc03fe #129, 834560c skills); work committed, tree clean except board"
+  last_verification:
+    result: pass
+    task: T999-pre-audit (PM ran all four gates on combined branch)
+    commands:
+      - cmd: "bin/rails test"
+        status: "pass — 1741 runs, 5301 assertions, 0 failures, 0 errors, 0 skips"
+      - cmd: "bin/rubocop"
+        status: "pass — 505 files, 0 offenses"
+      - cmd: "bin/brakeman --no-pager"
+        status: "pass — 0 warnings"
+      - cmd: "cd test/dummy && bin/rails zeitwerk:check"
+        status: "pass — All is good!"

data/docs/setup.md

@@ -18,8 +18,8 @@ This guide consolidates the new guided installer, verification commands, and rol
 Run these commands inside your host Rails application before invoking the guided workflow:
 
 ```bash
-bundle add source_monitor --version "~> 0.13.1"
-# or add gem "source_monitor", "~> 0.13.1" to Gemfile manually
+bundle add source_monitor --version "~> 0.14.0"
+# or add gem "source_monitor", "~> 0.14.0" to Gemfile manually
 bundle install
 ```
 
@@ -109,7 +109,7 @@ Prefer to script each step or plug SourceMonitor into an existing deployment che
 6. **Start workers** with `bin/rails solid_queue:start` (or your process manager). The install generator automatically configures recurring jobs in `config/recurring.yml` for fetch scheduling, scraping, and cleanup. They'll run with `bin/dev` or `bin/jobs`.
    - **Procfile.dev:** The generator automatically patches `Procfile.dev` with a `jobs:` entry for Solid Queue. Verify the file contains `jobs: bundle exec rake solid_queue:start` after running the generator.
    - **Recurring schedule:** The generator automatically patches `config/queue.yml` dispatchers with `recurring_schedule: config/recurring.yml`. Verify the key is present after running the generator.
-7. **Review the initializer** and tune queue names, HTTP timeouts, scraping adapters, retention limits, authentication hooks, and Mission Control integration. The [configuration reference](configuration.md) details every option.
+7. **Review the initializer** and tune queue names, HTTP timeouts, scraping adapters, retention limits, authentication hooks, and Mission Control integration. The [configuration reference](configuration.md) details every option. **Important:** the engine is fail-closed by default — configure `config.authentication.authenticate_with` / `authorize_with`, otherwise engine routes return `403 Forbidden`. For non-production demos only, you may set `config.authentication.open_access = true`.
 8. **Verify the install**: run `bin/source_monitor verify` to ensure Solid Queue workers and Action Cable are healthy, then visit the mount path to trigger a fetch manually. Enable telemetry if you want JSON logs recorded for support.
 
 ### Host Compatibility Matrix

data/docs/upgrade.md

@@ -46,6 +46,33 @@ If a removed option raises an error (`SourceMonitor::DeprecatedOptionError`), yo
 
 ## Version-Specific Notes
 
+### Upgrading to 0.14.0
+
+**What changed:**
+- **BREAKING — Fail-closed engine access by default** (#129). SourceMonitor now returns `403 Forbidden` on every mounted route unless the host app has configured an authentication or authorization handler. Previously routes were publicly accessible when no handler was configured.
+- **Request flashes are delivered response-local** (#130). Flash toasts are no longer broadcast to the global `source_monitor_notifications` ActionCable stream (which every connected tab subscribed to); they now render inline on full-page loads and append to the turbo_stream response, reaching only the requesting tab. Background operational toasts remain global but carry no per-user request context.
+- **Gem package excludes `.claude` internals** (#131). Only `.claude/skills/sm-*` SourceMonitor skills are packaged; agents, hooks, agent-memory, `settings.json`, commands, and non-`sm-*` skills are excluded.
+
+**Upgrade steps:**
+```bash
+bundle update source_monitor
+bin/rails source_monitor:upgrade
+```
+
+**Action required (BREAKING):**
+Open `config/initializers/source_monitor.rb`. If neither `config.authentication.authenticate_with` nor `config.authentication.authorize_with` is configured, the engine will return `403` on all routes after upgrade. Either:
+- configure a handler to gate the engine with your host auth stack:
+  ```ruby
+  config.authentication.authenticate_with :authenticate_user!
+  config.authentication.authorize_with ->(controller) { controller.current_user&.admin? }
+  ```
+- or, for local demos/sandboxes only, explicitly opt into public access:
+  ```ruby
+  config.authentication.open_access = true # NOT for production
+  ```
+
+No database migrations are required. The flash and packaging changes apply transparently.
+
 ### Upgrading to 0.13.1
 
 **What changed:**

data/lib/generators/source_monitor/install/templates/source_monitor.rb.tt

@@ -52,6 +52,10 @@ SourceMonitor.configure do |config|
   config.mission_control_dashboard_path = nil
 
   # ---- 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.
+  #
   # Hook SourceMonitor into your host application's authentication stack. Each
   # handler can be a Symbol (invoked on the controller) or a callable that will
   # receive the controller instance.
@@ -59,6 +63,12 @@ SourceMonitor.configure do |config|
   # config.authentication.authorize_with -> { authorize!(:manage, :source_monitor) }
   # config.authentication.current_user_method = :current_admin
   # config.authentication.user_signed_in_method = :admin_signed_in?
+  #
+  # Explicit opt-in for open/unauthenticated access. Leave this commented out
+  # in production. Only enable it for local demos or sandboxes where the engine
+  # routes are deliberately public.
+  # WARNING: non-production / demo only -- this disables the fail-closed guard.
+  # config.authentication.open_access = true
 
   # ---- HTTP client -------------------------------------------------------
   # Tune the Faraday client SourceMonitor uses for fetches/scrapes.

data/lib/source_monitor/configuration/authentication_settings.rb

@@ -22,7 +22,7 @@ module SourceMonitor
       end
 
       attr_reader :authenticate_handler, :authorize_handler
-      attr_accessor :current_user_method, :user_signed_in_method
+      attr_accessor :current_user_method, :user_signed_in_method, :open_access
 
       def initialize
         reset!
@@ -41,6 +41,10 @@ module SourceMonitor
         @authorize_handler = nil
         @current_user_method = nil
         @user_signed_in_method = nil
+        # Fail-closed by default: when no handler is configured the engine
+        # denies access. Set to true to opt into open/demo access. This is a
+        # technical opt-in flag, not business state.
+        @open_access = false
       end
 
       private

data/lib/source_monitor/security/authentication.rb

@@ -31,6 +31,16 @@ module SourceMonitor
         config.authenticate_handler.present? || config.authorize_handler.present?
       end
 
+      # Fail-closed predicate. The engine denies access when the host app has
+      # configured no authentication/authorization handler AND has not
+      # explicitly opted into open access. Configured handlers always win: when
+      # a handler is present the handler decides and this returns false.
+      def self.access_denied_by_default?(_controller = nil)
+        return false if authentication_configured?
+
+        !SourceMonitor.config.authentication.open_access
+      end
+
       def self.authorize_configured?
         SourceMonitor.config.authentication.authorize_handler.present?
       end

data/lib/source_monitor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SourceMonitor
-  VERSION = "0.13.1"
+  VERSION = "0.14.0"
 end

data/source_monitor.gemspec

@@ -23,11 +23,16 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     tracked_files = `git ls-files -z`.split("\x0")
     tracked_files.reject do |file|
-      file.start_with?(".ai/", ".github/", ".vbw-planning/", "coverage/", "node_modules/", "pkg/", "spec/", "test/", "tmp/", "vendor/", "examples/", "bin/")
+      file.start_with?(".ai/", ".github/", ".vbw-planning/", "coverage/", "node_modules/", "pkg/", "spec/", "test/", "tmp/", "vendor/", "examples/", "bin/") ||
+        # Exclude all .claude internals (agents, hooks, agent-memory, settings,
+        # commands) but keep the intended SourceMonitor sm-* skills. Driven from
+        # git ls-files (inside Dir.chdir) so packaging is CWD-independent --- a
+        # bare Dir[] glob here returned nothing on CI when another test had
+        # changed the process working directory.
+        (file.start_with?(".claude/") && !file.start_with?(".claude/skills/sm-"))
     end
   end
   spec.files += [ "CHANGELOG.md" ].select { |path| File.exist?(File.join(__dir__, path)) }
-  spec.files += Dir[".claude/skills/sm-*/**/*"]
   spec.files.uniq!
 
   spec.require_paths = [ "lib" ]