current_scope 0.2.0 → 0.3.1

data/lib/current_scope/configuration.rb

@@ -17,7 +17,11 @@ module CurrentScope
     # EMPTY BY DEFAULT — SoD is opt-in. The engine's baseline is scoped RBAC;
     # many hosts want nothing to do with four-eyes. Enable it by listing the
     # actions to gate, e.g. `config.sod_actions = %w[approve]`.
-    attr_accessor :sod_actions
+    #
+    # Matched as STRINGS against the key's action segment (see Resolver#sod_action?).
+    # Use the writer below — a plain Symbol list ([:approve]) used to silently
+    # disable the veto (#91). Same shape as collection_read_actions=.
+    attr_reader :sod_actions
 
     # Which identities the separation-of-duties veto weighs:
     #   :either  (default) — veto if the effective subject OR (while
@@ -26,7 +30,56 @@ module CurrentScope
     #                        record.
     #   :subject           — veto only on the effective subject.
     # The two are identical when not impersonating (actor == subject).
-    attr_accessor :sod_identity
+    # See the validating writer below — an unknown value must not silently
+    # narrow the veto.
+    attr_reader :sod_identity
+
+    SOD_IDENTITY_MODES = %i[either subject].freeze
+
+    # Normalizing writer for sod_actions (#91). The resolver matches with
+    # include?(permission.split("#").last) — a String — so symbols never match
+    # and silently turn the fraud control off. Normalize symbols to strings,
+    # reject non-String/Symbol elements and full keys (same honesty as
+    # collection_read_actions=), freeze the list.
+    def sod_actions=(value)
+      elements = Array(value)
+
+      if (bad = elements.reject { |e| e.is_a?(String) || e.is_a?(Symbol) }).any?
+        raise ConfigurationError,
+              "config.sod_actions takes action NAMES (strings or symbols); got " \
+              "#{bad.map(&:inspect).join(', ')}. Write e.g. %w[approve] or [:approve]."
+      end
+
+      actions = elements.map(&:to_s)
+
+      if (keyed = actions.grep(/#/)).any?
+        raise ConfigurationError,
+              "config.sod_actions is matched on the ACTION segment of a key — " \
+              "#{keyed.map(&:inspect).join(', ')} can never match. Write \"approve\", " \
+              "not \"reports#approve\"."
+      end
+
+      @sod_actions = actions.freeze
+    end
+
+    # Validating writer, same contract as enforcement=: the resolver compares
+    # `== :either`, so a typo (`:both`, `:actor`) would otherwise silently
+    # behave as :subject — narrowing the fraud control with no signal. Raise at
+    # assignment naming the closed set; the previous mode stands.
+    def sod_identity=(value)
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+
+      unless SOD_IDENTITY_MODES.include?(mode)
+        raise ConfigurationError,
+              "config.sod_identity = #{value.inspect} is not a mode. " \
+              "Use :either (default — the veto binds the effective subject AND, " \
+              "while impersonating, the real actor, so impersonation can never " \
+              "approve the actor's own record) or :subject (weigh only the " \
+              "effective subject)."
+      end
+
+      @sod_identity = mode
+    end
 
     # When false (the default), an impersonated session is read-only: any
     # non-GET/HEAD request is denied while a real actor acts as a different
@@ -42,10 +95,11 @@ module CurrentScope
     # See the custom writer.
     attr_reader :allow_mutations_while_impersonating
 
-    # Env var that opts a PRODUCTION deploy into impersonated writes. Any value
-    # (even "false" or "0" — presence is what counts) lifts the production
-    # refusal; unset in production means allow_mutations_while_impersonating=true
-    # raises at boot. development/test/staging never consult it.
+    # Env var that opts a PRODUCTION deploy into impersonated writes. The VALUE
+    # is what counts: a truthy value ("1", "true", "yes"…) lifts the production
+    # refusal; unset, "", "false", "0", "off" all mean "not opted in" — an
+    # operator writing `…=false` in a deploy manifest gets what they said, not
+    # the opposite. development/test/staging never consult it.
     PROD_MUTATIONS_ENV = "CURRENT_SCOPE_ALLOW_PROD_IMPERSONATION_MUTATIONS"
 
     # Regexps matched against controller paths to keep infrastructure
@@ -69,6 +123,15 @@ module CurrentScope
     #   - a Proc   — subject -> String, e.g. ->(u) { "#{u.first_name} #{u.last_name}" }
     #   - nil (default) — best-effort, people-first: email, else name, else
     #     first+last, else the generic current_scope_label / "Class #id".
+    #
+    # A Proc should be TOTAL — it runs for every subject the admin can see,
+    # including ones with nil or blank attributes, so `->(u) { u.email.upcase }`
+    # is a trap the first time someone is invited but hasn't filled in an email.
+    # Nothing here is load-bearing enough to break a page over, so a label that
+    # raises (or a Symbol the subject can't answer) degrades to the default chain
+    # for that subject and logs once — it never errors the page and never affects
+    # an authorization decision. If subject labels look wrong, check the log:
+    # a silent fallback is exactly what a broken label looks like from the UI.
     attr_accessor :subject_label
 
     # Break-glass override for the SoD veto. Default false — OFF preserves v0.1
@@ -93,8 +156,98 @@ module CurrentScope
     # record's route key like any permission, so it's editable in the role grid —
     # never a hardcoded role. Must NOT be listed in sod_actions (it isn't an SoD
     # action; keeping it out also bounds the bypass re-entrancy).
+    #
+    # It isn't a routable action, so the catalog injects it rather than deriving
+    # it: the grid shows a column for it ONLY when allow_sod_bypass is on, and
+    # only on controllers that route an action listed in sod_actions. With the
+    # flag off it isn't grantable at all — nothing to tick, and the key is
+    # rejected if assigned. (#21)
     attr_accessor :sod_bypass_permission
 
+    # Action names whose RECORD-LESS gate derives its answer from the scoped
+    # list (#65): for these, the check asks scope_for — the same id-narrowed
+    # query the list renders from — so a scoped full_access grant opens
+    # exactly the collections that would show it records, and gate and list
+    # agree by construction. Matched like sod_actions, on the action segment
+    # of the key ("index" in "reports#index").
+    #
+    # DEFAULT ["index"] — the #65 fix is on out of the box. Set [] to restore
+    # the pre-#65 record-less semantics (never a released posture on their
+    # own — #19/#50/#65 ship together): explicit ticks still open type-bound
+    # record-less gates, a scoped full_access role opens none, and the
+    # gate/list disagreement #65 describes comes back with it.
+    #
+    # LIST-NARROWING READS ONLY. The full_access safety argument is that the
+    # answer is derived from record ids — WHICH records the subject holds —
+    # so it is only sound for actions with a list side. Naming a mutating or
+    # non-idempotent action here ("create", "destroy_all") hands scoped
+    # full_access holders that action on the whole TYPE off a grant on one
+    # record: the #49 escalation, reintroduced by config. Custom read-shaped
+    # actions (export, search) are the intended additions.
+    #
+    # The declared current_scope_model is trusted here the way
+    # current_scope_record already is — a wrong declaration plus a scoped
+    # full_access grant of the declared type opens that controller's listed
+    # reads, so review the declaration like the record hook.
+    attr_reader :collection_read_actions
+
+    # Normalizing writer: the list is matched as STRINGS, so [:index] matching
+    # nothing would silently un-fix #65. Normalize rather than raise for shape
+    # (nil ⇒ [], symbols ⇒ strings — unambiguous), but two inputs get a voice,
+    # because a silently-inert or silently-widened security knob is the failure
+    # this writer exists to prevent:
+    #
+    #   - a full KEY ("reports#index") RAISES — the list is matched on the
+    #     action segment and applies to every controller, so a keyed member
+    #     can never match (silently inert) and stripping it to "index" would
+    #     silently widen a deliberately controller-scoped intent. Neither
+    #     reading is honest; say so at assignment.
+    #   - a canonical mutating action name (create/update/destroy) WARNS —
+    #     the #49 escalation shape, reintroduced by config. A warning, not a
+    #     raise: custom action names make any blocklist partial, and the
+    #     report-mode precedent (warn_report_mode_in_production) is the
+    #     house style for "legal but almost certainly not what you meant".
+    #   - an element that is not a String/Symbol RAISES — Array({ index: true })
+    #     is [[:index, true]], and .to_s on that pair is "[:index, true]": a
+    #     member that can never match, silently REPLACING the default and
+    #     un-fixing #65 with no signal (0.3.0 release-gate finding). Only
+    #     action names have an unambiguous string form; anything else says so
+    #     at assignment.
+    def collection_read_actions=(value)
+      elements = Array(value)
+
+      if (bad = elements.reject { |e| e.is_a?(String) || e.is_a?(Symbol) }).any?
+        raise ConfigurationError,
+              "config.collection_read_actions takes action NAMES (strings or symbols); got " \
+              "#{bad.map(&:inspect).join(', ')}. A Hash or nested array would coerce to a " \
+              "member that can never match an action, silently restoring the pre-#65 " \
+              "record-less semantics. Write e.g. %w[index export]."
+      end
+
+      actions = elements.map(&:to_s)
+
+      if (keyed = actions.grep(/#/)).any?
+        raise ConfigurationError,
+              "config.collection_read_actions is matched on the ACTION segment of a key and " \
+              "applies to every controller that routes it — #{keyed.map(&:inspect).join(', ')} " \
+              "can never match. Write \"index\", not \"reports#index\"; there is no " \
+              "per-controller form of this list."
+      end
+
+      warn_on_mutating_collection_reads(actions)
+      # Frozen so in-place mutation (config.collection_read_actions << :export)
+      # cannot bypass the writer — a symbol appended in place would silently
+      # never match, a "#" key would dodge the raise, and a mutating name would
+      # dodge the warning. FrozenError is loud; assign a new list instead.
+      @collection_read_actions = actions.freeze
+    end
+
+    # Canonical mutating / bulk-write action names the collection_read writer
+    # warns about. Includes destroy_all/update_all — the docs' escalation
+    # examples — so those cannot reintroduce #49 via config with no signal.
+    # Custom names still evade any partial blocklist; that ceiling is deliberate.
+    MUTATING_ACTION_NAMES = %w[create update destroy destroy_all update_all].freeze
+
     # Tri-state: false | true (default) | :strict — controls
     # CurrentScope::Event.record!.
     #   false   — record! is a silent no-op; hosts that don't want the ledger
@@ -108,16 +261,91 @@ module CurrentScope
     #             boundary events have no mutation to roll back — a raise there
     #             is a loud 500 on a mis-migrated host.)
     # Read as `== :strict`, never `== true` — don't flatten the tri-state.
-    attr_accessor :audit
-
-    # A5 (opt-in, dev/test aid): when true, the gate logs a nudge if an SoD
-    # action is gated with a nil record and the request is allowed — i.e. the
-    # SoD veto was silently skipped because current_scope_record returned nil on
-    # a member action. Off by default; prod behavior never changes. Emitted from
-    # the Guard seam (not the shared resolver), so it doesn't fire on advisory
-    # allowed_to?/scope_for calls.
+    # See the validating writer below — a misspelled :strict must not silently
+    # downgrade an audit-mandatory host to best-effort.
+    attr_reader :audit
+
+    AUDIT_MODES = [ false, true, :strict ].freeze
+
+    # Validating writer, same contract as enforcement=: because record! checks
+    # `== :strict`, a typo (`:strixt`) is truthy and would silently behave as
+    # plain true — the host believes unaudited mutations roll back while they
+    # commit. Raise at assignment naming the closed set; the previous mode
+    # stands.
+    def audit=(value)
+      # ENV can only carry strings, and two of the three modes are booleans —
+      # normalize the boolean spellings before symbolizing ("strict" → :strict).
+      mode = case value
+      when "true" then true
+      when "false" then false
+      else value.respond_to?(:to_sym) ? value.to_sym : value
+      end
+
+      unless AUDIT_MODES.include?(mode)
+        raise ConfigurationError,
+              "config.audit = #{value.inspect} is not a mode. " \
+              "Use false (record! is a silent no-op — no ledger), " \
+              "true (append a row per event, degrade gracefully if the events " \
+              "table is missing), or :strict (a missing events table RAISES so " \
+              "a mutation-wrapping transaction rolls back rather than " \
+              "committing an unaudited grant)."
+      end
+
+      @audit = mode
+    end
+
+    # --- Dev diagnostics (#41) ----------------------------------------------
+    #
+    # Four failure modes this engine has that are SILENT and silent in the bad
+    # direction: the thing that went wrong looks exactly like the thing going
+    # right. Each is a cheap log line in dev/test and costs nothing in prod.
+    #
+    # All four default ON in development and test, OFF in production — and off
+    # entirely when Rails isn't loaded. The default is the point: a diagnostic
+    # nobody knows about is a diagnostic nobody benefits from, and these
+    # protect against mistakes you make while WRITING the app, which is exactly
+    # when dev/test is where you are. A host can force any of them either way.
+    #
+    # Every one is LOG-ONLY. No decision, exception, header, or audit row
+    # changes because of them, in any environment.
+
+    # The gate logs a nudge when an SoD action is gated with no record and the
+    # request is ALLOWED — i.e. the veto was skipped because current_scope_record
+    # returned nil (or was never declared) on a member action. The gem's #1
+    # foot-gun: the veto silently not running looks identical to the veto passing.
+    #
+    # Emitted from the Guard seam (not the shared resolver), so it never fires on
+    # advisory allowed_to?/scope_for calls.
     attr_accessor :warn_on_nil_sod_record
 
+    # The gate logs a nudge when a request is DENIED :no_grant, the controller
+    # declared no current_scope_record hook at all, and the subject holds a
+    # scoped grant that WOULD have applied had the hook returned the record.
+    #
+    # That combination is a controller with member actions that forgot the hook.
+    # It fails closed — correctly — but the 403 is indistinguishable from "you
+    # were never granted this", so the person debugging it goes looking at their
+    # grants, which are fine, instead of at their controller, which isn't.
+    attr_accessor :warn_on_inert_scoped_grant
+
+    # CurrentScope.permission_key logs a nudge when short-form derivation
+    # (`allowed_to?(:show, report)`) resolves to a DIFFERENT key than the one the
+    # current controller's gate enforces — the documented namespaced/custom-named
+    # controller foot-gun. The view then shows a link that 403s, or hides one that
+    # would have worked: the gate and the view disagree, silently, and the symptom
+    # shows up nowhere near the cause.
+    attr_accessor :warn_on_cross_controller_derivation
+
+    # The gate logs a nudge when a request is DENIED :model_undeclared — a
+    # declared collection action (current_scope_record returned nil) whose
+    # controller names no current_scope_model, while the subject holds a scoped
+    # grant ticking the key. The record-less branch had no type to bind that
+    # grant to, so it failed closed (#50) — correctly, but the 403 looks like
+    # "never granted" while the fix is one line in the controller. The same
+    # flag gates the :model_invalid nudge — the hook was declared but returned
+    # something unusable ("Report" for Report); one failure family, one knob.
+    attr_accessor :warn_on_undeclared_collection_model
+
     # How the role-editor grid folds RESTful actions into columns. An ordered
     # Hash of { column_label => [action names] }: ticking a group column grants
     # every routed action in it. The default collapses the seven RESTful verbs
@@ -129,13 +357,92 @@ module CurrentScope
     # actions shows a blank cell, never a shifted one.
     attr_accessor :permission_grid_groups
 
+    # :enforce (default) | :report — what the gate DOES with a denial. (#37)
+    #
+    # The adoption ramp. A host retrofitting this engine onto an existing app
+    # has a controller suite that goes red the moment the gate is mounted: it is
+    # fail-closed, and nothing is granted yet. Report mode lets them mount the
+    # gate, run their app, and read what WOULD have been denied out of the
+    # ledger — turning a big-bang cutover into a list of grants to seed.
+    #
+    #   :enforce — deny means 403. The only production posture.
+    #   :report  — a MISSING GRANT is logged and allowed through instead. Every
+    #              other denial still refuses.
+    #
+    # Report mode is NOT an off switch and never reaches the things that would
+    # make it one: the separation-of-duties veto still refuses, and the
+    # management console answers to its own full-access check rather than this
+    # gate, so no enforcement setting can hand out the UI where grants are made.
+    attr_reader :enforcement
+
+    ENFORCEMENT_MODES = %i[enforce report].freeze
+
+    # Validating writer: an unknown value here is the worst kind of config
+    # mistake — the host believes it is enforcing while it is not. Fail at boot,
+    # naming what's allowed. Accepts a String so ENV["..."] works; anything that
+    # can't be a mode (nil from an unset ENV var, a number, a collection) raises
+    # ConfigurationError rather than NoMethodError, and the previous mode stands.
+    def enforcement=(value)
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+
+      unless ENFORCEMENT_MODES.include?(mode)
+        raise ConfigurationError,
+              "config.enforcement = #{value.inspect} is not a mode. " \
+              "Use :enforce (deny means 403 — the production posture) or " \
+              ":report (log what WOULD be denied and allow it through, to seed " \
+              "grants before cutting over). Report mode is for adoption only: " \
+              "it never lifts the separation-of-duties veto and never opens the " \
+              "management console."
+      end
+
+      warn_report_mode_in_production if mode == :report && production?
+      @enforcement = mode
+    end
+
+    # True only in report mode. A predicate, so callers can't express "not
+    # enforcing" — the modes are a closed set, not a boolean.
+    def report_only? = @enforcement == :report
+
+    # :raise | :warn — what the opt-in GatingTripwire mixin (A4) does when it
+    # catches an action that completed without running the gate.
+    #
+    #   :raise — fail loudly. Default in development/test: an ungated action is
+    #            a hole you want CI to go red on, not one to discover in an audit.
+    #   :warn  — log once per controller#action and let the response through, so
+    #            a real app can inventory its ungated surface without 500ing.
+    #
+    # A closed two-mode set, like enforcement — not a boolean, and no :off:
+    # not including the mixin is off.
+    attr_reader :gating_tripwire
+
+    GATING_TRIPWIRE_MODES = %i[raise warn].freeze
+
+    # Validating writer, same contract as enforcement=: an unknown value raises
+    # at assignment naming both modes, and the previous mode stands. Accepts a
+    # String so ENV["..."] works.
+    def gating_tripwire=(value)
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+
+      unless GATING_TRIPWIRE_MODES.include?(mode)
+        raise ConfigurationError,
+              "config.gating_tripwire = #{value.inspect} is not a mode. " \
+              "Use :raise (an ungated action fails loudly — the dev/test posture) " \
+              "or :warn (log it once per controller#action and let the response " \
+              "through, to inventory an app's ungated surface). There is no :off — " \
+              "not including CurrentScope::GatingTripwire is off."
+      end
+
+      @gating_tripwire = mode
+    end
+
     def initialize
       @user_method = :current_user
       @actor_method = nil
-      @sod_actions = []
+      @sod_actions = [].freeze
       @sod_identity = :either
       @allow_sod_bypass = false
       @sod_bypass_permission = "bypass_sod"
+      @collection_read_actions = [ "index" ].freeze
       @allow_mutations_while_impersonating = false
       @excluded_controllers = [
         %r{\Arails/}, %r{\Aactive_storage/}, %r{\Aaction_mailbox/},
@@ -144,7 +451,18 @@ module CurrentScope
       @parent_controller = "::ApplicationController"
       @subject_class = "User"
       @audit = true
-      @warn_on_nil_sod_record = false
+      @enforcement = :enforce
+      # Reuses diagnostics_default_on? for its env split and bare-Ruby safety
+      # ONLY — do NOT carry over the diagnostics flags' emit/silence reading.
+      # There, false means stay quiet; here, false means :warn, which EMITS.
+      # The inversion is deliberate: the tripwire mixin is opt-in, so a
+      # production host that included it is asking for the ungated inventory —
+      # the env decides only whether a hit 500s (dev/test) or logs (elsewhere).
+      @gating_tripwire = diagnostics_default_on? ? :raise : :warn
+      @warn_on_nil_sod_record = diagnostics_default_on?
+      @warn_on_inert_scoped_grant = diagnostics_default_on?
+      @warn_on_cross_controller_derivation = diagnostics_default_on?
+      @warn_on_undeclared_collection_model = diagnostics_default_on?
       @permission_grid_groups = {
         "read"    => %w[index show],
         "create"  => %w[new create],
@@ -159,7 +477,7 @@ module CurrentScope
     # silently letting a real actor mutate data as someone else. Assigning false
     # (or leaving the default) is always allowed.
     def allow_mutations_while_impersonating=(value)
-      if value && production? && !ENV.key?(PROD_MUTATIONS_ENV)
+      if value && production? && !prod_mutations_opt_in?
         raise ConfigurationError,
               "config.allow_mutations_while_impersonating = true is refused in " \
               "production: letting a real actor write as the subject they " \
@@ -167,13 +485,88 @@ module CurrentScope
               "Keep it false so impersonated sessions stay read-only in " \
               "production, or — only if writes under act-as are genuinely " \
               "required (e.g. a live public showcase) — set ENV[\"#{PROD_MUTATIONS_ENV}\"] " \
-              "to opt in explicitly. development, test, and staging are unaffected."
+              "to a truthy value (\"1\"/\"true\") to opt in explicitly; \"false\", " \
+              "\"0\", and empty mean not opted in. development, test, and staging " \
+              "are unaffected."
       end
       @allow_mutations_while_impersonating = value
     end
 
     private
 
+    # The env var's VALUE means what it says — presence alone is not consent.
+    # ActiveModel's boolean cast maps "false"/"0"/"f"/"off" to false and "" to
+    # nil; anything else present is truthy. Only reached when production? is
+    # already true, so Rails (and ActiveModel) are loaded — a bare-Ruby
+    # Configuration.new never gets here.
+    def prod_mutations_opt_in?
+      !!ActiveModel::Type::Boolean.new.cast(ENV[PROD_MUTATIONS_ENV])
+    end
+
+    # Report mode in production is DELIBERATELY allowed — surveying real traffic
+    # is the most honest way to find out what to grant, and a staging run won't
+    # show you the flows your actual users take. Refusing it here would break the
+    # feature's best use case.
+    #
+    # But "we are not enforcing authorization" is not a state a production app
+    # should be in silently, or for long. The failure mode is quiet: nothing
+    # breaks, no one is refused, and the temporary survey becomes the permanent
+    # posture because nothing ever reminded anyone. So it says so at boot, once,
+    # where a deploy log will keep it.
+    #
+    # ponytail: a warn, not a raise. Unlike allow_mutations_while_impersonating
+    # (which has an env-gate refusal) this has a legitimate production use and a
+    # deliberate exit — the host is mid-migration, and the loud reminder is the
+    # right amount of friction.
+    def warn_report_mode_in_production
+      message = "[CurrentScope] config.enforcement = :report in PRODUCTION — " \
+                "authorization is NOT being enforced. Missing grants are logged " \
+                "as access.would_deny and the request is ALLOWED THROUGH. This is " \
+                "an adoption ramp, not a production posture: seed the grants the " \
+                "ledger names, then set config.enforcement = :enforce."
+
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      else
+        # Boot order: an initializer can run before the logger exists. Say it
+        # anyway — a warning nobody sees is the thing this method exists to
+        # prevent.
+        warn(message)
+      end
+    end
+
+    # Mirrors warn_report_mode_in_production: a legal posture that is almost
+    # never what the host meant says so once, loudly, where a boot log keeps
+    # it. Warn in every env — unlike report mode this misconfiguration is as
+    # wrong in development as in production.
+    def warn_on_mutating_collection_reads(actions)
+      mutating = actions & MUTATING_ACTION_NAMES
+      return if mutating.empty?
+
+      message = "[CurrentScope] config.collection_read_actions includes " \
+                "#{mutating.map(&:inspect).join(', ')} — this list is for LIST-NARROWING READS. " \
+                "A mutating action here hands scoped full_access holders that action on every " \
+                "record of its type off a grant on ONE record (the #49 escalation shape). " \
+                "Remove it unless that is genuinely intended."
+
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      else
+        warn(message)
+      end
+    end
+
+    # Diagnostics are on where you are while writing the app, off where they'd
+    # be noise on someone else's dime. `local?` is Rails' own name for
+    # "development or test", so a host with a staging env that reports itself as
+    # neither gets prod behaviour — the conservative side for a log line.
+    #
+    # Mirrors the production? guard below: a bare-Ruby Configuration.new with no
+    # Rails must not raise, and gets false (no logger to warn to anyway).
+    def diagnostics_default_on?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.local?
+    end
+
     def production?
       defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
     end

data/lib/current_scope/engine.rb

@@ -9,6 +9,13 @@ module CurrentScope
     config.to_prepare do
       CurrentScope.reset_catalog!
       CurrentScope.reset_scopeable_registry!
+      # The cross-controller nudge warns once per site; a reload can change what's
+      # routed, so a stale latch would hide a divergence the edit just created.
+      CurrentScope.reset_cross_controller_warnings!
+      # Same reason for the tripwire's :warn latch: a reload can change whether a
+      # controller#action is gated, and a stale latch would hand a dev running
+      # :warn a false all-clear right after the edit.
+      CurrentScope::GatingTripwire.reset_warnings!
     end
   end
 end

data/lib/current_scope/gating_reflection.rb

@@ -0,0 +1,62 @@
+module CurrentScope
+  # Answers one question about a controller path: is it PROVEN that
+  # current_scope_check! never runs there? True only when the callback is
+  # ABSENT from the class's callback chain — the one thing the chain states
+  # unconditionally. Everything else is false:
+  #
+  #   - callback present and unconditional → gated → false
+  #   - callback present wearing a condition (skip_before_action only:) →
+  #     UNPROVABLE without evaluating ActionFilter internals, which this class
+  #     must never do (KTD-3) → false. The naive any?/none? presence check
+  #     inverts exactly here — see the ProblemFrame characterization in
+  #     test/gating_reflection_test.rb — and per-action guessing is how a
+  #     fail-open gets reported as gated.
+  #   - no controller class routed at that path → nothing to prove → false
+  #
+  # Absence is an EFFECT, not a cause: a bare skip_before_action, an inherited
+  # bare skip (#62), and never including Guard at all are the same verdict,
+  # because the chain looks the same. That is deliberate — the question is
+  # "does the gate run?", not "why not?".
+  #
+  # Named beside GatingTripwire: both interrogate the same subject (is this
+  # action gated?), the tripwire at request time, this one by reflection.
+  class GatingReflection
+    def ungated?(controller_path)
+      klass = controller_class_for(controller_path)
+      # A controller without the callbacks API at all (a bare ActionController::
+      # Metal without AbstractController::Callbacks) cannot run a before_action
+      # — the gate PROVABLY never runs there. Without this check the reflection
+      # would raise NoMethodError instead of answering. (#79 review)
+      return true unless klass.respond_to?(:_process_action_callbacks)
+
+      klass
+        ._process_action_callbacks
+        .none? { |callback| callback.kind == :before && callback.filter == :current_scope_check! }
+    rescue ActionDispatch::MissingController
+      # A routed path with no controller class (a scaffolding leftover, a
+      # not-yet-written controller) proves nothing about gating. Silent false,
+      # matching the prove-or-stay-silent discipline of
+      # warn_on_cross_controller_derivation.
+      false
+    end
+
+    private
+
+    # Rails owns the path→class rule — camelize, namespacing, the Controller
+    # suffix, and crucially the NameError triage: a missing CONTROLLER constant
+    # becomes MissingController (rescued above), while a NameError raised from
+    # inside the controller's own broken body re-raises as-is and must
+    # PROPAGATE out of ungated? (a blanket rescue NameError would silently
+    # report a broken controller as gated). Hand-rolling camelize+constantize
+    # would have to reimplement that triage and would drift. (KTD-2)
+    #
+    # controller_class_for lives on Request, so a throwaway request object is
+    # the price of asking. Built lazily and memoized here, NEVER in initialize:
+    # the role-save path constructs a GatingReflection it may never ask — any
+    # failure in construction would 500 role saves. (KTD-8)
+    def controller_class_for(controller_path)
+      @request ||= ActionDispatch::Request.new({})
+      @request.controller_class_for(controller_path)
+    end
+  end
+end

data/lib/current_scope/gating_tripwire.rb

@@ -21,9 +21,30 @@ module CurrentScope
   # chain (render/redirect) — so an action that renders straight from a
   # before_action escapes the tripwire. It is a strong dev/test aid, not total
   # coverage (Grape/Rack endpoints are out of reach for the same reason).
+  # What a catch DOES is config.gating_tripwire (:raise in dev/test, :warn
+  # elsewhere) — :warn logs each ungated controller#action once instead of
+  # 500ing, so a real app can inventory its ungated surface.
   module GatingTripwire
     extend ActiveSupport::Concern
 
+    class << self
+      # The :warn latch. ponytail: a plain Set, not a Mutex — worst case under
+      # a race is one extra line, and a flood is the thing being prevented.
+      # Per-SITE, not per-process (unlike Guard.ledger_warning_emitted?): the
+      # point of :warn is an inventory, so every distinct controller#action
+      # must get its own line.
+      def warning_unseen?(site)
+        @warned ||= Set.new
+        @warned.add?(site) ? true : false
+      end
+
+      # Cleared on engine to_prepare — a reload can change whether a site is
+      # gated, so a stale latch is a false all-clear — and by tests.
+      def reset_warnings!
+        @warned = nil
+      end
+    end
+
     included do
       after_action :current_scope_verify_gated!
     end
@@ -43,11 +64,21 @@ module CurrentScope
       # controller carrying only this mixin (no Guard) never sets it.
       return if instance_variable_defined?(:@current_scope_checked) && @current_scope_checked
 
-      raise CurrentScope::ConfigurationError,
-            "\"#{controller_path}##{action_name}\" completed without running current_scope_check! — " \
-            "this controller is not gated by CurrentScope::Guard. Include CurrentScope::Guard on its " \
-            "base controller, or mark this action public with " \
-            "`current_scope_skip_tripwire! only: :#{action_name}`."
+      raise CurrentScope::ConfigurationError, current_scope_tripwire_message if CurrentScope.config.gating_tripwire == :raise
+
+      # :warn — same remediation text, once per controller#action. The latch
+      # check comes first so an already-warned site (every request after the
+      # first, on a fail-open that keeps serving traffic) pays no string build.
+      return unless GatingTripwire.warning_unseen?("#{controller_path}##{action_name}")
+
+      Rails.logger&.warn("[CurrentScope] #{current_scope_tripwire_message}")
+    end
+
+    def current_scope_tripwire_message
+      "\"#{controller_path}##{action_name}\" completed without running current_scope_check! — " \
+        "this controller is not gated by CurrentScope::Guard. Include CurrentScope::Guard on its " \
+        "base controller, or mark this action public with " \
+        "`current_scope_skip_tripwire! only: :#{action_name}`."
     end
   end
 end