snitcher_reports 0.2.0

data/lib/snitcher/anomaly.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Snitcher
+  # An immutable, deterministic signal flagged by an anomaly rule (a fact, not an opinion).
+  # Rendered as a report section and exposed in the fact payload via #to_h.
+  Anomaly = Data.define(:code, :severity, :title, :description, :data) do
+    def severity_rank
+      self.class::SEVERITIES.index(severity) || -1
+    end
+
+    def to_h
+      { code: code, severity: severity, title: title, description: description, data: data }
+    end
+
+    def to_json(...)
+      to_h.to_json(...)
+    end
+  end
+
+  # Ordered least → most severe; index gives the rank used for sorting.
+  Anomaly::SEVERITIES = %i[info warning critical].freeze
+end

data/lib/snitcher/anomaly_context.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Snitcher
+  # Read-only view over a report's items + period + working-hours config, exposing the
+  # memoized aggregates rules need. Keeps rules small and consistent.
+  class AnomalyContext
+    TICKET_SOURCES = %i[jira clickup linear].freeze
+
+    attr_reader :items, :since, :until_time, :working_hours
+
+    def initialize(items:, since: nil, until_time: nil, working_hours: nil)
+      @items = items
+      @since = since
+      @until_time = until_time
+      @working_hours = working_hours
+    end
+
+    def non_meeting_items = @non_meeting_items ||= MeetingsAggregator.non_meeting_items(items)
+    def commit_items      = @commit_items ||= items.select { |i| i.source == :git }
+    def ticket_items      = @ticket_items ||= items.select { |i| TICKET_SOURCES.include?(i.source) }
+    def total_tracked_seconds = @total_tracked_seconds ||= non_meeting_items.sum { |i| i.time_spent_seconds || 0 }
+    def meeting_seconds = @meeting_seconds ||= MeetingsAggregator.total_seconds(items)
+
+    def period?
+      !since.nil? && !until_time.nil? && until_time > since
+    end
+
+    # Available working seconds in the period; nil when capacity can't be computed.
+    def available_seconds
+      return nil unless working_hours && since && until_time
+      return @available_seconds if defined?(@available_seconds)
+
+      @available_seconds = WorkingHoursCalculator.seconds_between(since, until_time, working_hours)
+    end
+
+    # Dates (Date) with at least one completed non-meeting item.
+    def active_dates
+      @active_dates ||= non_meeting_items.filter_map { |i| i.completed_at&.to_date }.to_set
+    end
+
+    # Working dates expected in the period (work_days minus holidays when configured).
+    def expected_working_dates
+      return [] unless period?
+
+      @expected_working_dates ||= begin
+        last_inclusive = (until_time - TimeFormatter::SECONDS_PER_DAY).to_date
+        (since.to_date..last_inclusive).select do |date|
+          work_days.include?(date.wday) && !holiday_dates.include?(date)
+        end
+      end
+    end
+
+    private
+
+    def work_days
+      @work_days ||= (working_hours && working_hours[:work_days]) ||
+                     WorkingHoursCalculator::DEFAULT_WORK_DAYS
+    end
+
+    def holiday_dates
+      @holiday_dates ||= begin
+        region = working_hours && working_hours[:holidays_region]
+        if region && period?
+          years = (since.year..(until_time - TimeFormatter::SECONDS_PER_DAY).year)
+          years.flat_map { |y| HolidayRegionResolver.holidays_for_year(region.to_sym, y) }
+               .to_set { |h| h[:date] }
+        else
+          Set.new
+        end
+      rescue StandardError => e
+        warn "[anomaly] Failed to load holidays for region #{region.inspect}: #{e.message}" if ENV['DEBUG']
+        Set.new
+      end
+    end
+  end
+end

data/lib/snitcher/anomaly_detector.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Snitcher
+  # Runs registered deterministic rules over a report's data. Each rule is isolated: a rule that
+  # raises is logged and skipped (mirrors Orchestrator#fetch) so one bad rule never breaks a report.
+  class AnomalyDetector
+    RULES = [
+      AnomalyRules::CommitsWithoutClosedTickets,
+      AnomalyRules::TimeAboveAvailability,
+      AnomalyRules::InactiveWorkingDays,
+      AnomalyRules::EstimateOverrun,
+      AnomalyRules::ExcessiveMeetingTime
+    ].freeze
+
+    def initialize(items, since: nil, until_time: nil, working_hours: nil, rules: RULES)
+      @context = AnomalyContext.new(items: items, since: since, until_time: until_time,
+                                    working_hours: working_hours)
+      @rules = rules
+    end
+
+    # @return [Array<Anomaly>] most-severe first
+    def detect
+      @rules.flat_map do |rule|
+        rule.call(@context)
+      rescue StandardError => e
+        warn "[anomaly:#{rule}] Error: #{e.class}: #{e.message}"
+        warn "  Backtrace: #{e.backtrace.first(5).join("\n            ")}" if ENV['DEBUG']
+        []
+      end.sort_by { |a| -a.severity_rank }
+    end
+  end
+end

data/lib/snitcher/anomaly_rules/base.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Snitcher
+  # Deterministic anomaly rules. Each inspects an AnomalyContext and returns zero or more Anomaly.
+  # Add a rule: subclass Base, implement #call, register in AnomalyDetector::RULES.
+  module AnomalyRules
+    class Base
+      def self.call(context) = new(context).call
+
+      def initialize(context)
+        @context = context
+      end
+
+      def call
+        raise NotImplementedError, "#{self.class} must implement #call"
+      end
+
+      private
+
+      attr_reader :context
+
+      def anomaly(code:, severity:, title:, description:, data: {})
+        Anomaly.new(code: code, severity: severity, title: title, description: description, data: data)
+      end
+
+      def format_duration(seconds) = TimeFormatter.format_duration(seconds)
+    end
+  end
+end

data/lib/snitcher/anomaly_rules/commits_without_closed_tickets.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Snitcher
+  module AnomalyRules
+    # Meaningful commit activity not reflected by any closed ticket (untracked work / tickets
+    # never moved to done).
+    class CommitsWithoutClosedTickets < Base
+      MIN_COMMITS = 3
+
+      def call
+        commits = context.commit_items.size
+        tickets = context.ticket_items.size
+        return [] unless commits >= MIN_COMMITS && tickets.zero?
+
+        [anomaly(code: :commits_without_closed_tickets, severity: :warning,
+                 title: 'Commits without closed tickets',
+                 description: "#{commits} commits recorded but no tickets were closed in this period.",
+                 data: { commits: commits, closed_tickets: tickets })]
+      end
+    end
+  end
+end

data/lib/snitcher/anomaly_rules/estimate_overrun.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Snitcher
+  module AnomalyRules
+    # Tickets whose logged/calculated time greatly exceeds their estimate. Only Linear exposes an
+    # estimate, in story points, so points are converted to an expected duration via a heuristic.
+    class EstimateOverrun < Base
+      SECONDS_PER_POINT = 4 * 3_600 # ~4h per story point
+      OVERRUN_RATIO = 1.5
+
+      def call
+        results = context.ticket_items.filter_map do |item|
+          m = item.metadata
+          estimate = m && (m[:estimate] || m['estimate'])
+          actual = item.time_spent_seconds
+          next unless estimate&.positive? && actual&.positive?
+
+          expected = estimate * SECONDS_PER_POINT
+          next unless actual > expected * OVERRUN_RATIO
+
+          anomaly(code: :estimate_overrun, severity: :warning,
+                  title: 'Time well above estimate',
+                  description: "#{item.external_id} took #{format_duration(actual)} " \
+                               "vs ~#{format_duration(expected)} expected for #{estimate} point(s).",
+                  data: { external_id: item.external_id, estimate_points: estimate,
+                          time_spent_seconds: actual, expected_seconds: expected })
+        end
+
+        if ENV.fetch('DEBUG', nil) && results.empty? && context.ticket_items.any?
+          warn '[anomaly:estimate_overrun] Skipped — no items with estimate data (Linear-only rule)'
+        end
+
+        results
+      end
+    end
+  end
+end

data/lib/snitcher/anomaly_rules/excessive_meeting_time.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Snitcher
+  module AnomalyRules
+    # High meeting load — meetings taking up more than half of the available working time in the
+    # period. Expressed as a share of working time (not an absolute weekly figure) so it scales
+    # naturally to how many days a person works: 50% of a 5-day week, 50% of a 4-day week, etc.
+    # May itself explain other signals (e.g. low ticket throughput), so it's flagged as a warning.
+    # Skipped without a usable period.
+    class ExcessiveMeetingTime < Base
+      MEETING_LOAD_RATIO = 0.5 # flag when meetings exceed 50% of available working time
+      DEFAULT_HOURS_PER_DAY = 8 # assumed working day length when working_hours isn't configured
+
+      def call
+        return [] unless context.period?
+
+        available = available_working_seconds
+        return [] if available.nil? || available <= 0
+
+        meeting_seconds = context.meeting_seconds
+        return [] if meeting_seconds <= available * MEETING_LOAD_RATIO
+
+        ratio = meeting_seconds.to_f / available
+        [anomaly(code: :excessive_meeting_time, severity: :warning,
+                 title: 'High meeting load',
+                 description: "Meetings take up #{(ratio * 100).round}% of working time " \
+                              "(#{format_duration(meeting_seconds)} of #{format_duration(available)} " \
+                              'available); may also explain other signals.',
+                 data: { meeting_seconds: meeting_seconds, available_seconds: available,
+                         ratio: ratio.round(2) })]
+      end
+
+      private
+
+      # Working capacity for the period. Uses the precise working-hours calculation when configured,
+      # else falls back to expected working days (Mon–Fri by default) at 8h each.
+      def available_working_seconds
+        context.available_seconds ||
+          (context.expected_working_dates.size * DEFAULT_HOURS_PER_DAY * TimeFormatter::SECONDS_PER_HOUR)
+      end
+    end
+  end
+end

data/lib/snitcher/anomaly_rules/inactive_working_days.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Snitcher
+  module AnomalyRules
+    # Working days within the period with no recorded activity. work_days/holidays from
+    # working_hours when present, else Monday–Friday. Skipped without a usable period.
+    class InactiveWorkingDays < Base
+      MAX_LISTED = 5
+
+      def call
+        return [] unless context.period?
+
+        active = context.active_dates
+        inactive = context.expected_working_dates.reject { |d| active.include?(d) }
+        return [] if inactive.empty?
+
+        [anomaly(code: :inactive_working_days, severity: :info,
+                 title: 'Working days without activity',
+                 description: build_description(inactive),
+                 data: { count: inactive.size, dates: inactive.map(&:iso8601) })]
+      end
+
+      private
+
+      def build_description(inactive)
+        listed = inactive.first(MAX_LISTED).map(&:iso8601).join(', ')
+        suffix = inactive.size > MAX_LISTED ? ", +#{inactive.size - MAX_LISTED} more" : ''
+        "#{inactive.size} working day(s) with no recorded activity: #{listed}#{suffix}."
+      end
+    end
+  end
+end

data/lib/snitcher/anomaly_rules/time_above_availability.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Snitcher
+  module AnomalyRules
+    # Logged time significantly above working-hours availability. Skipped without working_hours.
+    class TimeAboveAvailability < Base
+      WARNING_RATIO = 1.10
+      CRITICAL_RATIO = 1.50
+
+      def call
+        available = context.available_seconds
+        return [] if available.nil? || available <= 0
+
+        tracked = context.total_tracked_seconds
+        ratio = tracked.to_f / available
+        return [] if ratio <= WARNING_RATIO
+
+        [anomaly(code: :time_above_availability,
+                 severity: ratio > CRITICAL_RATIO ? :critical : :warning,
+                 title: 'Logged time above availability',
+                 description: "Logged #{format_duration(tracked)} vs ~#{format_duration(available)} " \
+                              "available for this period (#{(ratio * 100).round}%).",
+                 data: { tracked_seconds: tracked, available_seconds: available, ratio: ratio.round(2) })]
+      end
+    end
+  end
+end

data/lib/snitcher/client.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Snitcher
+  # Embeddable facade for host applications. Build one Client from a config file and
+  # org-level ENV credentials, then call #work_report per user or #work_reports to fan
+  # out over several users in one call. Wraps ReportService + Orchestrator, and renders
+  # any format Report supports — a host never has to assemble an Orchestrator itself.
+  #
+  # @example
+  #   snitcher = Snitcher.new(config_path: "config/snitcher.yml")
+  #   snitcher.work_report(user_email: "alice@corp.com", from: "2026-07-01", to: "2026-07-14")
+  #   # => { metadata:, anomalies:, items:, summary: }
+  #   snitcher.work_report(user_email: "alice@corp.com", from: "2026-07-01", format: :html)
+  #   # => { metadata: { report_path: ".../alice-at-corp.com_2026-07-01_2026-08-27.html", ... }, ... }
+  #   snitcher.work_reports(user_emails: %w[alice@corp.com bob@corp.com], from: "2026-07-01")
+  #   # => { "alice@corp.com" => { metadata:, anomalies:, items:, summary: }, "bob@corp.com" => { ... } }
+  class Client
+    # Sources that serve multi-user reports with any configuration. google_calendar is
+    # absent because it needs a service account. Ask .multi_user_sources for the effective
+    # list, which depends on the credentials that are configured right now.
+    MULTI_USER_SOURCES = %i[git jira clickup linear].freeze
+
+    # Kept in step with #warn_single_user_sources: the operator reads one on stderr, the host
+    # reads the other in metadata[:failed_sources], and the two must not disagree. Names the
+    # setting to change, per the contract in Sources::Source#unavailable_reason.
+    SINGLE_USER_ERROR = 'cannot serve a multi-user report with the configured credentials; set ' \
+                        "#{Sources::GoogleCalendar::SERVICE_ACCOUNT_ENV} to report on several " \
+                        'users from Google Calendar'.freeze
+
+    # The sources to build an orchestrator from, paired with the ones dropped on the way.
+    # A Data object rather than a two-element Array: both values are Arrays and would be
+    # silently swappable at the call site.
+    ResolvedSources = Data.define(:requested, :unavailable)
+
+    # A source is multi-user when one set of organization credentials can serve any
+    # requested user. Sources may opt out at runtime — google_calendar does when only
+    # OAuth is configured, since one refresh token cannot honour a per-user request.
+    # Sources that do not answer the predicate are multi-user unconditionally.
+    def self.multi_user_source?(source_name)
+      source_class = Orchestrator::SOURCE_MAP[source_name]
+      return false unless source_class
+      return true unless source_class.respond_to?(:multi_user_capable?)
+
+      source_class.multi_user_capable?
+    end
+
+    # The sources that can serve a multi-user report with the credentials configured now.
+    def self.multi_user_sources
+      Orchestrator::SOURCE_MAP.keys.select { |name| multi_user_source?(name) }
+    end
+
+    def initialize(config_path: Configuration::DEFAULT_CONFIG_FILE)
+      @configuration = Configuration.new(config_path)
+    end
+
+    # Generates a work report for one user. user_email may be omitted to fall back to the
+    # per-source default identity (sources.<name>.user) from the config file.
+    # @param format [Symbol, String] one of Report::FORMATS. :markdown and :html are
+    #   written to disk; :hash (the default) returns the payload.
+    # @param narrative [String, nil] prose summary rendered as an Overview section by the
+    #   markdown and html formats. The gem generates none — a host that has a model
+    #   available passes its own text in.
+    # @param output_dir [String, nil] directory for a saved document, overriding
+    #   `output_dir` from the config file.
+    # @param output_path [String, nil] exact file path for a saved document, overriding
+    #   both output_dir and the generated filename.
+    # @return [Hash] { metadata:, anomalies:, items:, summary: } — the same shape for every
+    #   format. A saved format sets metadata[:report_path] and metadata[:report_format].
+    # rubocop:disable-next Metrics/ParameterLists -- keyword args are self-documenting
+    def work_report(from:, user_email: nil, to: nil, sources: nil, include_anomalies: true,
+                    format: :hash, narrative: nil, output_dir: nil, output_path: nil)
+      fmt = ReportService.normalize_format(format)
+      resolved = resolve_sources(sources)
+      orchestrator = Orchestrator.new(sources: resolved.requested, configuration: @configuration,
+                                      unavailable: resolved.unavailable)
+      ReportService.call(
+        user_email: user_email, from: from, to: to,
+        include_anomalies: include_anomalies, format: fmt, narrative: narrative,
+        output_dir: output_dir, output_path: output_path,
+        orchestrator: orchestrator, configuration: @configuration
+      )
+    end
+
+    # Generates work reports for several users in one call, reusing a single
+    # Orchestrator. Returns a Hash keyed by the requested email; a user whose
+    # report fails (e.g. an invalid email or a source error that escapes the
+    # Orchestrator) gets an { error:, error_class: } entry instead of aborting
+    # the batch. Batch-wide input errors (empty user_emails, unknown source,
+    # unknown format) raise before any report runs.
+    # @param user_emails [Array<String>] one or more work emails
+    # @param format [Symbol, String] as in #work_report; applies to every user. A saved
+    #   format writes one document per user, each named after that user.
+    # @param narrative [Hash{String => String}, String, nil] per-user prose keyed by the
+    #   requested email, or one String applied to every report
+    # @param output_dir [String, nil] directory for the saved documents. There is no
+    #   output_path counterpart: one path for a batch would have every user overwrite
+    #   the same file.
+    # @return [Hash{String => Hash}] { email => report | { error:, error_class: } }.
+    #   Every value is a Hash: the payload for a user whose report ran (carrying
+    #   metadata[:report_path] for a saved format), or { error:, error_class: } for one
+    #   that failed — so a caller tells the two apart by looking for :error, never by
+    #   checking the value's type.
+    # rubocop:disable-next Metrics/ParameterLists -- keyword args are self-documenting
+    def work_reports(user_emails:, from:, to: nil, sources: nil, include_anomalies: true,
+                     format: :hash, narrative: nil, output_dir: nil)
+      emails = Array(user_emails).map { |e| e.to_s.strip }.reject(&:empty?)
+      raise ArgumentError, 'user_emails must contain at least one email' if emails.empty?
+
+      fmt = ReportService.normalize_format(format)
+      resolved = resolve_sources(sources)
+      orchestrator = Orchestrator.new(sources: resolved.requested, configuration: @configuration,
+                                      unavailable: resolved.unavailable)
+
+      emails.to_h do |email|
+        payload = begin
+          ReportService.call(
+            user_email: email, from: from, to: to,
+            include_anomalies: include_anomalies, format: fmt,
+            narrative: narrative_for(narrative, email), output_dir: output_dir,
+            orchestrator: orchestrator, configuration: @configuration
+          )
+        rescue StandardError => e
+          { error: e.message, error_class: e.class.name }
+        end
+        [email, payload]
+      end
+    end
+
+    private
+
+    # One person's narrative out of the batch argument. A Hash is looked up by the
+    # requested email (a missing entry simply means no Overview for that user); a plain
+    # String is text that applies to everyone.
+    def narrative_for(narrative, email)
+      narrative.is_a?(Hash) ? (narrative[email] || narrative[email.to_sym]) : narrative
+    end
+
+    # Resolves the requested sources to a ResolvedSources pairing an explicit, validated
+    # symbol list with the ones dropped along the way (warning when a source is dropped).
+    # nil / "" / "all" expand to every known source, then go through the same multi-user
+    # rejection as an explicit list — so a source that cannot serve a multi-user report
+    # with the credentials configured now is recorded as unavailable there too, never
+    # dropped without a trace. requested is [] only when the host explicitly requested
+    # exclusively unsupported sources — an empty Orchestrator, i.e. an empty report.
+    def resolve_sources(sources)
+      keys = Orchestrator::SOURCE_MAP.keys
+      list = Array(sources).flat_map { |s| s.to_s.split(',') }.map(&:strip).reject(&:empty?)
+
+      requested =
+        if list.empty? || list.include?('all')
+          keys
+        else
+          syms = list.map(&:to_sym)
+          invalid = syms - keys
+          if invalid.any?
+            raise ArgumentError,
+                  "Unknown source(s): #{invalid.join(', ')}. Available: #{keys.join(', ')}"
+          end
+          syms
+        end
+
+      rejected = requested.reject { |name| self.class.multi_user_source?(name) }
+      warn_single_user_sources(rejected) if rejected.any?
+      ResolvedSources.new(
+        requested: requested - rejected,
+        unavailable: rejected.map { |name| { source: name, error: SINGLE_USER_ERROR } }
+      )
+    end
+
+    def warn_single_user_sources(rejected)
+      warn "[Snitcher] #{rejected.join(', ')} cannot serve multi-user reports with the " \
+           'configured credentials and is skipped. Set ' \
+           "#{Sources::GoogleCalendar::SERVICE_ACCOUNT_ENV} to report on several users " \
+           'from Google Calendar.'
+    end
+  end
+end

data/lib/snitcher/configuration.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Snitcher
+  # Manages per-project configuration stored in .snitcher.yml.
+  #
+  # The configuration file stores status mappings that allow the app to work with
+  # non-English workspaces (Polish, German, etc.).
+  #
+  # @example File format
+  #   version: 1
+  #   sources:
+  #     clickup:
+  #       done_statuses: ["Zamkniete", "Done"]
+  #       in_progress_statuses: ["W trakcie"]
+  #     jira:
+  #       done_statuses: ["Zrobione"]
+  #
+  # @example Usage
+  #   config = Configuration.new
+  #   config.statuses_for(:clickup, :done) # => ["Zamkniete", "Done"]
+  #
+  class Configuration
+    DEFAULT_CONFIG_FILE = '.snitcher.yml'
+
+    attr_reader :config_path
+
+    def initialize(config_path = DEFAULT_CONFIG_FILE)
+      @config_path = config_path
+      @data = load_config
+    end
+
+    def exists?
+      File.exist?(@config_path)
+    end
+
+    def version
+      @data['version'] || 1
+    end
+
+    # Returns source-specific config hash, e.g. configuration.source(:clickup)
+    # @param source_name [Symbol] :jira, :clickup, :linear
+    # @return [Hash] source configuration or empty hash
+    def source(source_name)
+      (@data.dig('sources', source_name.to_s) || {}).transform_keys(&:to_sym)
+    end
+
+    # Returns array of status names for a given source and category
+    # @param source_name [Symbol] :jira, :clickup, :linear
+    # @param category [Symbol] :done, :in_progress, :todo
+    # @return [Array<String>] status names or empty array
+    def statuses_for(source_name, category)
+      key = "#{category}_statuses"
+      source(source_name)[key.to_sym] || []
+    end
+
+    # Returns the work-email => git-email(s) identity map from sources.git.emails.
+    # Values are normalized to arrays, since one person may commit under several
+    # addresses (work laptop, personal, GitHub noreply).
+    # @return [Hash{String=>Array<String>}] empty hash when unconfigured
+    def git_emails
+      (source(:git)[:emails] || {}).to_h { |work, git| [work.to_s, Array(git).map(&:to_s)] }
+    end
+
+    # Directory that saved markdown/html reports are written to (top-level `output_dir`).
+    # @return [String, nil] the configured directory, or nil to use ReportWriter's default
+    def output_dir
+      dir = @data['output_dir']
+      return nil if dir.nil?
+
+      dir = dir.to_s.strip
+      dir.empty? ? nil : dir
+    end
+
+    # Returns working hours configuration (top-level, not source-specific).
+    # Validates timezone and field formats lazily on first access.
+    # @param user_email [String, nil] resolve one person's hours (working_hours.people);
+    #   nil returns the shared block that applies to everyone else
+    # @return [Hash, nil] working hours config with symbolized keys, or nil if not configured
+    def working_hours(user_email: nil)
+      working_hours_config.for(user_email)
+    end
+
+    # The hours configured for one person specifically, nil when they are not named under
+    # working_hours.people. Lets Orchestrator tell "this person is different" from "everyone
+    # gets the shared block", so it never clobbers a working_hours handed straight to
+    # Orchestrator.new(config:).
+    # @param user_email [String, nil]
+    # @return [Hash, nil]
+    def working_hours_override(user_email)
+      working_hours_config.override_for(user_email)
+    end
+
+    # Returns source config with global working_hours merged in.
+    # @param source_name [Symbol] :jira, :clickup, :linear
+    # @return [Hash] source config, potentially including :working_hours key
+    def source_with_working_hours(source_name)
+      src = source(source_name)
+      wh = working_hours
+      src[:working_hours] = wh if wh
+      src
+    end
+
+    private
+
+    def working_hours_config
+      @working_hours_config ||= WorkingHoursConfig.new(@data['working_hours'])
+    end
+
+    def load_config
+      # No error if file missing — backward compatible behavior (existing behavior preserved)
+      return {} unless File.exist?(@config_path)
+
+      # Use safe_load without Symbol permission to prevent potential DoS attacks.
+      # Keys are transformed to symbols in #source method after loading.
+      YAML.safe_load_file(@config_path, permitted_classes: []) || {}
+    rescue Psych::SyntaxError => e
+      warn "[Snitcher] Warning: Invalid .snitcher.yml syntax: #{e.message}"
+      {}
+    end
+  end
+end