lex-cognitive-blindspot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 70f03cdc2eef30b1868b9f42870fb55b50ad4ebbdfebfcfe21c745a00ef7a838
+  data.tar.gz: 07bf45977e84481f64ce514a200eeb2f6b10c7495079204df988865dc61da9db
+SHA512:
+  metadata.gz: 31569326fc31e1fb955be407e857f748e3f52824451b584f59052c15f3748a34948139d2c91653c32d6a064ea6195806eb8d60751a79dea9d6acd83f82abc18e
+  data.tar.gz: 70ecbaac03f808079e9ca8385a2bfe62538f869b94eba230e09d096150a19f745b7c3de92951be703771c09d7f83155d818a162811dee5047c44ced83bcd47d7

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,2 @@
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,40 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+
+Style/Documentation:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'

data/CLAUDE.md

@@ -0,0 +1,81 @@
+# lex-cognitive-blindspot
+
+**Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Johari Window for AI. Tracks unknown-unknowns, manages knowledge boundaries, and scores agent awareness with blindspot acknowledgement and mitigation strategies. Models the progression from unknown-unknown (active blindspot) to known-unknown (acknowledged) to mitigated to resolved.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-blindspot`
+- **Version**: `0.1.0`
+- **Module**: `Legion::Extensions::CognitiveBlindspot`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_blindspot/
+  cognitive_blindspot.rb
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    blindspot.rb
+    knowledge_boundary.rb
+    blindspot_engine.rb
+  runners/
+    cognitive_blindspot.rb
+```
+
+## Key Constants
+
+From `helpers/constants.rb`:
+
+- `DISCOVERY_METHODS` — `%i[error_analysis peer_feedback cross_domain_check contradiction_detection confidence_calibration external_audit self_reflection unknown]`
+- `MAX_BLINDSPOTS` = `300`, `MAX_BOUNDARIES` = `50`
+- `DEFAULT_SEVERITY` = `0.5`, `SEVERITY_BOOST` = `0.1`
+- `AWARENESS_THRESHOLD` = `0.6`
+- `SEVERITY_LABELS` — `0.8+` = `:critical`, `0.6` = `:high`, `0.4` = `:moderate`, `0.2` = `:low`, below = `:negligible`
+- `AWARENESS_LABELS` — `0.8+` = `:highly_aware` through below `0.2` = `:unaware`
+- `COVERAGE_LABELS` — `0.8+` = `:comprehensive` through below `0.2` = `:minimal`
+- `STATUS_LABELS` — describes each state: `active` = unknown-unknown, `acknowledged` = known-unknown, `mitigated` = partial coverage, `resolved` = fully addressed
+
+## Runners
+
+All methods in `Runners::CognitiveBlindspot`:
+
+- `register_blindspot(domain:, discovered_by:, description:, severity: DEFAULT_SEVERITY)` — records a new blindspot in `active` state
+- `acknowledge_blindspot(blindspot_id:)` — transitions from `active` to `acknowledged` (unknown-unknown -> known-unknown)
+- `mitigate_blindspot(blindspot_id:, boost: SEVERITY_BOOST)` — applies mitigation; reduces severity by boost amount
+- `resolve_blindspot(blindspot_id:)` — marks as fully resolved
+- `set_knowledge_boundary(domain:, confidence:, coverage_estimate:)` — establishes a domain-level knowledge boundary
+- `detect_boundary_gap(domain:, error_occurred: false)` — checks if errors in a domain indicate boundary gaps
+- `active_blindspots_report` — all unacknowledged or unresolved blindspots
+- `most_severe_report(limit: 5)` — top blindspots by severity
+- `mitigation_strategies_report(domain: nil)` — recommended strategies per domain
+- `coverage_report` — all knowledge boundaries with coverage estimates
+- `johari_report` — full Johari Window breakdown: known-knowns, known-unknowns, unknown-unknowns counts
+- `awareness_score_report` — scalar awareness score, label, and awareness gap
+
+## Helpers
+
+- `BlindspotEngine` — stores blindspots and knowledge boundaries; computes awareness score as ratio of acknowledged/mitigated/resolved to total.
+- `Blindspot` — individual blindspot with `domain`, `discovered_by`, `description`, `severity`, `status`. State machine: `active` -> `acknowledged` -> `mitigated` -> `resolved`.
+- `KnowledgeBoundary` — domain-level confidence and coverage estimate; gap detection on error events.
+
+## Integration Points
+
+- `lex-cognitive-debugging` detects reasoning errors; those errors are natural inputs to `register_blindspot` (via `discovered_by: :error_analysis`).
+- `lex-tick` can call awareness score checks in the `identity_entropy_check` phase to flag low-awareness domains.
+- `detect_boundary_gap` is meant to be called when errors occur — the caller passes `error_occurred: true` to trigger gap analysis for the relevant domain.
+
+## Development Notes
+
+- Blindspot state progression is one-directional: `active` -> `acknowledged` -> `mitigated` -> `resolved`. No regression.
+- `awareness_score` is computed as `(acknowledged + mitigated + resolved) / total_blindspots`. An agent with no registered blindspots returns `0.0` (unaware, not aware).
+- `johari_report` maps: `active` = unknown-unknown quadrant; `acknowledged/mitigated` = known-unknown quadrant; no explicit known-known tracking (that would require a separate knowledge model).

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-rspec'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-blindspot (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-cognitive-blindspot!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,40 @@
+# lex-cognitive-blindspot
+
+Cognitive blindspot detection for LegionIO agents. Johari Window for AI — tracks unknown-unknowns, manages knowledge boundaries, and scores agent awareness with blindspot acknowledgement and mitigation strategies.
+
+## What It Does
+
+Models the progression from unknown-unknown (active blindspot: the agent doesn't know what it doesn't know) to known-unknown (acknowledged: now visible but not addressed) to mitigated (partial coverage) to resolved. Discovery methods include error analysis, peer feedback, contradiction detection, confidence calibration, and self-reflection.
+
+A parallel knowledge boundary system tracks domain-level confidence and coverage estimates, with gap detection triggered by error events in a domain.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveBlindspot::Client.new
+
+spot = client.register_blindspot(
+  domain: :temporal_reasoning,
+  discovered_by: :error_analysis,
+  description: 'Consistently misjudges elapsed time in multi-step plans',
+  severity: 0.7
+)
+
+client.acknowledge_blindspot(blindspot_id: spot[:id])
+client.mitigate_blindspot(blindspot_id: spot[:id], boost: 0.15)
+
+client.johari_report
+client.awareness_score_report
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-blindspot.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_blindspot/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-blindspot'
+  spec.version       = Legion::Extensions::CognitiveBlindspot::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'Cognitive blindspot detection for LegionIO agents'
+  spec.description   = 'Johari Window for AI — tracks unknown-unknowns, ' \
+                       'manages knowledge boundaries, and scores agent awareness ' \
+                       'with blindspot acknowledgement and mitigation strategies.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-blindspot'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = spec.homepage
+  spec.metadata['documentation_uri']   = "#{spec.homepage}/blob/main/README.md"
+  spec.metadata['changelog_uri']       = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['bug_tracker_uri']     = "#{spec.homepage}/issues"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:test|spec|features)/})
+    end
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/cognitive_blindspot/client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveBlindspot
+      class Client
+        include Runners::CognitiveBlindspot
+
+        def engine
+          @engine ||= Helpers::BlindspotEngine.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_blindspot/helpers/blindspot.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveBlindspot
+      module Helpers
+        class Blindspot
+          include Constants
+
+          attr_reader :id, :domain, :discovered_by, :severity, :description,
+                      :status, :created_at, :acknowledged_at, :mitigated_at, :resolved_at
+
+          def initialize(domain:, discovered_by:, description:, severity: DEFAULT_SEVERITY)
+            @id             = SecureRandom.uuid
+            @domain         = domain.to_sym
+            @discovered_by  = discovered_by.to_sym
+            @description    = description.to_s
+            @severity       = severity.to_f.clamp(0.0, 1.0)
+            @status         = :active
+            @created_at     = Time.now.utc
+            @acknowledged_at = nil
+            @mitigated_at   = nil
+            @resolved_at    = nil
+          end
+
+          def severity_label
+            Constants.label_for(SEVERITY_LABELS, @severity) || :negligible
+          end
+
+          def active?
+            @status == :active
+          end
+
+          def acknowledged?
+            @status == :acknowledged || @status == :mitigated || @status == :resolved
+          end
+
+          def resolved?
+            @status == :resolved
+          end
+
+          def acknowledge!
+            return self if @status != :active
+
+            @status          = :acknowledged
+            @acknowledged_at = Time.now.utc
+            self
+          end
+
+          def mitigate!(boost: SEVERITY_BOOST)
+            acknowledge! if @status == :active
+            @status        = :mitigated
+            @mitigated_at  = Time.now.utc
+            @severity      = (@severity - boost).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def resolve!
+            acknowledge! if @status == :active
+            @status      = :resolved
+            @resolved_at = Time.now.utc
+            self
+          end
+
+          def boost_severity!(amount: SEVERITY_BOOST)
+            @severity = (@severity + amount).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def to_h
+            {
+              id:              @id,
+              domain:          @domain,
+              discovered_by:   @discovered_by,
+              description:     @description,
+              severity:        @severity,
+              severity_label:  severity_label,
+              status:          @status,
+              active:          active?,
+              acknowledged:    acknowledged?,
+              resolved:        resolved?,
+              created_at:      @created_at,
+              acknowledged_at: @acknowledged_at,
+              mitigated_at:    @mitigated_at,
+              resolved_at:     @resolved_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_blindspot/helpers/blindspot_engine.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveBlindspot
+      module Helpers
+        class BlindspotEngine
+          include Constants
+
+          attr_reader :awareness_score
+
+          def initialize
+            @blindspots      = {}
+            @boundaries      = {}
+            @awareness_score = 1.0
+          end
+
+          def register_blindspot(domain:, discovered_by:, description:, severity: DEFAULT_SEVERITY)
+            prune_blindspots_if_needed
+            blindspot = Blindspot.new(domain: domain, discovered_by: discovered_by,
+                                      description: description, severity: severity)
+            @blindspots[blindspot.id] = blindspot
+            recalculate_awareness
+            blindspot
+          end
+
+          def acknowledge_blindspot(blindspot_id:)
+            blindspot = @blindspots.fetch(blindspot_id, nil)
+            return { found: false, blindspot_id: blindspot_id } unless blindspot
+
+            blindspot.acknowledge!
+            recalculate_awareness
+            { found: true, blindspot_id: blindspot_id, status: blindspot.status,
+              awareness_score: @awareness_score.round(10) }
+          end
+
+          def mitigate_blindspot(blindspot_id:, boost: SEVERITY_BOOST)
+            blindspot = @blindspots.fetch(blindspot_id, nil)
+            return { found: false, blindspot_id: blindspot_id } unless blindspot
+
+            blindspot.mitigate!(boost: boost)
+            recalculate_awareness
+            { found: true, blindspot_id: blindspot_id, status: blindspot.status,
+              severity: blindspot.severity, awareness_score: @awareness_score.round(10) }
+          end
+
+          def resolve_blindspot(blindspot_id:)
+            blindspot = @blindspots.fetch(blindspot_id, nil)
+            return { found: false, blindspot_id: blindspot_id } unless blindspot
+
+            blindspot.resolve!
+            recalculate_awareness
+            { found: true, blindspot_id: blindspot_id, status: blindspot.status,
+              awareness_score: @awareness_score.round(10) }
+          end
+
+          def set_boundary(domain:, confidence: 0.5, coverage_estimate: 0.5)
+            prune_boundaries_if_needed
+            existing = boundary_for_domain(domain)
+            return update_boundary!(existing, confidence, coverage_estimate) if existing
+
+            boundary = KnowledgeBoundary.new(domain: domain, confidence: confidence,
+                                             coverage_estimate: coverage_estimate)
+            @boundaries[boundary.id] = boundary
+            boundary
+          end
+
+          def detect_boundary_gap(domain:, error_occurred: false)
+            boundary = boundary_for_domain(domain)
+            return { gap_detected: false, domain: domain, reason: :no_boundary } unless boundary
+
+            { gap_detected: boundary.gap_detected?(error_occurred: error_occurred),
+              domain: domain, confidence: boundary.confidence,
+              coverage: boundary.coverage_estimate }
+          end
+
+          def blindspots_by_domain(domain)
+            d = domain.to_sym
+            @blindspots.values.select { |b| b.domain == d }
+          end
+
+          def active_blindspots       = @blindspots.values.select(&:active?)
+          def acknowledged_blindspots = @blindspots.values.select { |b| b.status == :acknowledged }
+          def resolved_blindspots     = @blindspots.values.select(&:resolved?)
+
+          def most_severe(limit: 5)
+            @blindspots.values.sort_by { |b| -b.severity }.first(limit)
+          end
+
+          def mitigation_strategies(domain: nil)
+            spots = domain ? blindspots_by_domain(domain) : @blindspots.values
+            spots.select(&:active?).map do |b|
+              { blindspot_id: b.id, domain: b.domain, severity: b.severity, strategy: strategy_for(b) }
+            end
+          end
+
+          def coverage_report  = @boundaries.values.map(&:to_h)
+          def awareness_label  = Constants.label_for(AWARENESS_LABELS, @awareness_score) || :unaware
+          def awareness_gap    = (1.0 - @awareness_score).clamp(0.0, 1.0).round(10)
+
+          def johari_report
+            { total_blindspots:   @blindspots.size,
+              active:             active_blindspots.size,
+              acknowledged:       acknowledged_blindspots.size,
+              resolved:           resolved_blindspots.size,
+              awareness_score:    @awareness_score.round(10),
+              awareness_label:    awareness_label,
+              awareness_gap:      awareness_gap,
+              boundaries_tracked: @boundaries.size,
+              most_severe:        most_severe(limit: 3).map(&:to_h) }
+          end
+
+          def to_h
+            { total_blindspots: @blindspots.size,
+              active:           active_blindspots.size,
+              acknowledged:     acknowledged_blindspots.size,
+              resolved:         resolved_blindspots.size,
+              awareness_score:  @awareness_score.round(10),
+              awareness_label:  awareness_label }
+          end
+
+          private
+
+          def update_boundary!(boundary, confidence, coverage_estimate)
+            boundary.update_confidence!(confidence)
+            boundary.update_coverage!(coverage_estimate)
+            boundary
+          end
+
+          def boundary_for_domain(domain)
+            d = domain.to_sym
+            @boundaries.values.find { |b| b.domain == d }
+          end
+
+          def recalculate_awareness
+            total = @blindspots.size.to_f
+            return @awareness_score = 1.0 if total.zero?
+
+            not_active = @blindspots.values.count { |b| !b.active? }.to_f
+            @awareness_score = (not_active / total).clamp(0.0, 1.0).round(10)
+          end
+
+          def strategy_for(blindspot)
+            case blindspot.severity
+            when (0.8..) then :immediate_external_audit
+            when (0.6...0.8) then :cross_domain_check
+            when (0.4...0.6) then :peer_feedback
+            else :self_reflection
+            end
+          end
+
+          def prune_blindspots_if_needed
+            return if @blindspots.size < MAX_BLINDSPOTS
+
+            target = resolved_blindspots.min_by(&:created_at) ||
+                     @blindspots.values.min_by(&:severity)
+            @blindspots.delete(target.id) if target
+          end
+
+          def prune_boundaries_if_needed
+            return if @boundaries.size < MAX_BOUNDARIES
+
+            oldest = @boundaries.values.min_by(&:created_at)
+            @boundaries.delete(oldest.id) if oldest
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_blindspot/helpers/constants.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveBlindspot
+      module Helpers
+        module Constants
+          MAX_BLINDSPOTS  = 300
+          MAX_BOUNDARIES  = 50
+          DEFAULT_SEVERITY = 0.5
+          SEVERITY_BOOST   = 0.1
+          AWARENESS_THRESHOLD = 0.6
+
+          DISCOVERY_METHODS = %i[
+            error_analysis peer_feedback cross_domain_check
+            contradiction_detection confidence_calibration
+            external_audit self_reflection unknown
+          ].freeze
+
+          SEVERITY_LABELS = {
+            (0.8..)     => :critical,
+            (0.6...0.8) => :high,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :low,
+            (..0.2)     => :negligible
+          }.freeze
+
+          AWARENESS_LABELS = {
+            (0.8..)     => :highly_aware,
+            (0.6...0.8) => :aware,
+            (0.4...0.6) => :partially_blind,
+            (0.2...0.4) => :mostly_blind,
+            (..0.2)     => :unaware
+          }.freeze
+
+          COVERAGE_LABELS = {
+            (0.8..)     => :comprehensive,
+            (0.6...0.8) => :substantial,
+            (0.4...0.6) => :partial,
+            (0.2...0.4) => :limited,
+            (..0.2)     => :minimal
+          }.freeze
+
+          STATUS_LABELS = {
+            active:       'Unknown unknown — not yet surfaced to awareness',
+            acknowledged: 'Known unknown — surfaced, not yet mitigated',
+            mitigated:    'Known unknown — mitigated with partial coverage',
+            resolved:     'Known unknown — fully addressed'
+          }.freeze
+
+          def self.label_for(labels, value)
+            match = labels.find { |range, _| range.cover?(value) }
+            match&.last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_blindspot/helpers/knowledge_boundary.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveBlindspot
+      module Helpers
+        class KnowledgeBoundary
+          include Constants
+
+          attr_reader :id, :domain, :confidence, :coverage_estimate, :created_at, :updated_at
+
+          def initialize(domain:, confidence: 0.5, coverage_estimate: 0.5)
+            @id               = SecureRandom.uuid
+            @domain           = domain.to_sym
+            @confidence       = confidence.to_f.clamp(0.0, 1.0)
+            @coverage_estimate = coverage_estimate.to_f.clamp(0.0, 1.0)
+            @created_at       = Time.now.utc
+            @updated_at       = Time.now.utc
+          end
+
+          def coverage_label
+            Constants.label_for(COVERAGE_LABELS, @coverage_estimate) || :minimal
+          end
+
+          def gap_detected?(error_occurred: false)
+            error_occurred && @confidence >= AWARENESS_THRESHOLD
+          end
+
+          def update_confidence!(new_confidence)
+            @confidence  = new_confidence.to_f.clamp(0.0, 1.0)
+            @updated_at  = Time.now.utc
+            self
+          end
+
+          def update_coverage!(new_coverage)
+            @coverage_estimate = new_coverage.to_f.clamp(0.0, 1.0)
+            @updated_at        = Time.now.utc
+            self
+          end
+
+          def to_h
+            {
+              id:                @id,
+              domain:            @domain,
+              confidence:        @confidence,
+              coverage_estimate: @coverage_estimate,
+              coverage_label:    coverage_label,
+              created_at:        @created_at,
+              updated_at:        @updated_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_blindspot/runners/cognitive_blindspot.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveBlindspot
+      module Runners
+        module CognitiveBlindspot
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def register_blindspot(domain:, discovered_by:, description:,
+                                 severity: nil, **)
+            sev = severity || Helpers::Constants::DEFAULT_SEVERITY
+            spot = engine.register_blindspot(
+              domain:        domain,
+              discovered_by: discovered_by,
+              description:   description,
+              severity:      sev
+            )
+            { success: true }.merge(spot.to_h)
+          end
+
+          def acknowledge_blindspot(blindspot_id:, **)
+            result = engine.acknowledge_blindspot(blindspot_id: blindspot_id)
+            return { success: false, error: 'blindspot not found' } unless result[:found]
+
+            { success: true }.merge(result)
+          end
+
+          def mitigate_blindspot(blindspot_id:, boost: nil, **)
+            b = boost || Helpers::Constants::SEVERITY_BOOST
+            result = engine.mitigate_blindspot(blindspot_id: blindspot_id, boost: b)
+            return { success: false, error: 'blindspot not found' } unless result[:found]
+
+            { success: true }.merge(result)
+          end
+
+          def resolve_blindspot(blindspot_id:, **)
+            result = engine.resolve_blindspot(blindspot_id: blindspot_id)
+            return { success: false, error: 'blindspot not found' } unless result[:found]
+
+            { success: true }.merge(result)
+          end
+
+          def set_knowledge_boundary(domain:, confidence: 0.5, coverage_estimate: 0.5, **)
+            boundary = engine.set_boundary(
+              domain:            domain,
+              confidence:        confidence,
+              coverage_estimate: coverage_estimate
+            )
+            { success: true }.merge(boundary.to_h)
+          end
+
+          def detect_boundary_gap(domain:, error_occurred: false, **)
+            result = engine.detect_boundary_gap(domain: domain, error_occurred: error_occurred)
+            { success: true }.merge(result)
+          end
+
+          def active_blindspots_report(**)
+            spots = engine.active_blindspots
+            { success: true, count: spots.size, blindspots: spots.map(&:to_h) }
+          end
+
+          def most_severe_report(limit: 5, **)
+            spots = engine.most_severe(limit: limit)
+            { success: true, limit: limit, blindspots: spots.map(&:to_h) }
+          end
+
+          def mitigation_strategies_report(domain: nil, **)
+            strategies = engine.mitigation_strategies(domain: domain)
+            { success: true, count: strategies.size, strategies: strategies }
+          end
+
+          def coverage_report(**)
+            boundaries = engine.coverage_report
+            { success: true, count: boundaries.size, boundaries: boundaries }
+          end
+
+          def johari_report(**)
+            engine.johari_report
+          end
+
+          def awareness_score_report(**)
+            score = engine.awareness_score
+            {
+              success:         true,
+              awareness_score: score.round(10),
+              awareness_label: engine.awareness_label,
+              awareness_gap:   engine.awareness_gap
+            }
+          end
+
+          def blindspot_stats(**)
+            engine.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_blindspot/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveBlindspot
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/cognitive_blindspot.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'cognitive_blindspot/version'
+require_relative 'cognitive_blindspot/helpers/constants'
+require_relative 'cognitive_blindspot/helpers/blindspot'
+require_relative 'cognitive_blindspot/helpers/knowledge_boundary'
+require_relative 'cognitive_blindspot/helpers/blindspot_engine'
+require_relative 'cognitive_blindspot/runners/cognitive_blindspot'
+require_relative 'cognitive_blindspot/client'
+
+module Legion
+  module Extensions
+    module CognitiveBlindspot
+      extend Legion::Extensions::Core if defined?(Legion::Extensions::Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-blindspot
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Johari Window for AI — tracks unknown-unknowns, manages knowledge boundaries,
+  and scores agent awareness with blindspot acknowledgement and mitigation strategies.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- lex-cognitive-blindspot.gemspec
+- lib/legion/extensions/cognitive_blindspot.rb
+- lib/legion/extensions/cognitive_blindspot/client.rb
+- lib/legion/extensions/cognitive_blindspot/helpers/blindspot.rb
+- lib/legion/extensions/cognitive_blindspot/helpers/blindspot_engine.rb
+- lib/legion/extensions/cognitive_blindspot/helpers/constants.rb
+- lib/legion/extensions/cognitive_blindspot/helpers/knowledge_boundary.rb
+- lib/legion/extensions/cognitive_blindspot/runners/cognitive_blindspot.rb
+- lib/legion/extensions/cognitive_blindspot/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-blindspot
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-blindspot
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-blindspot
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-blindspot/blob/main/README.md
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-blindspot/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-blindspot/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Cognitive blindspot detection for LegionIO agents
+test_files: []