ui_guardrails 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b29232255e89ade665ffe0aa02661183fbf71c5918c53704d8241293be757454
-  data.tar.gz: 5d3cf78b2091bb6e781f6bd563976c9bc1c583a8269309ce897ed90d8eae3b3b
+  metadata.gz: bcb56bb52cb2fe3e2d0bd155eaf5b8563177588b53d34af57f4d125653cd6f47
+  data.tar.gz: 5803d7480e71fe72cc6964bd424333fb888709d73104f215430a520d09cc4b49
 SHA512:
-  metadata.gz: 99aa335b527770be65aa661262461ec9b9cc0e1a9f1f2b70153b804b584c5f3de497c0e38f18183d6eac1977d343506d99f42685a49c3bbe3e953781ba3cd176
-  data.tar.gz: 894f7504d9e0f559b79051645f7f2c29de05215de57b2f4e04f78f9eb0bb4145568d13bd593123be401a15f626b9c3872174467dd78920a4ce3f265709bb3712
+  metadata.gz: 18bb8c26caf6971a74cc2a0d585acbcf57fbd27b1f703bc0fcedfa4d038724d0362623addcf06723e152f2f4cd4234829a88ba720dfcf0042a79c027067c27bb
+  data.tar.gz: b559b93cc20faa99f6af5b7a806117ea5925d6dacee2df064cac8e2fe4499d7763277ce0c6a47944f4c77dd7373d091fd01bba65e21a09b3e1dcd56193628d71

data/README.md

@@ -97,6 +97,7 @@ APPLY=1 bundle exec rake guardrails:audit
 | `guardrails:tokens` | Parses your color and type-scale tokens (CSS vars / SCSS vars / Tailwind v3 config / Tailwind v4 `@theme`), reports hex literals in stylesheets that should reference a token. |
 | `guardrails:a11y:deep` | Reads axe-core JSON output and folds it into the unified report. Doesn't run axe itself (no Capybara / headless Chrome runtime deps) — point it at axe output your existing tooling produces. |
 | `guardrails:visual:deep` | Consumes screenshot-diff tool output (snap_diff-capybara today; BackstopJS in flight, [#15](https://github.com/meticulous/guardrails/issues/15)) and reports visual regressions. Same parse-only design — your existing test toolchain runs screenshots; Guardrails reports. |
+| `guardrails:hooks:install` | Adds Guardrails to coding agents' hooks (Claude Code, Codex, Cursor, Gemini CLI), so drift an agent introduces goes back to it while it works. See [Coding agent hooks](#coding-agent-hooks). |
 
 ---
 
@@ -228,6 +229,23 @@ Works on the same line or the preceding line, in Ruby `#` comments, ERB `<%# %>`
 
 **No-fix policy**: emoji contribute to `guardrails:icons` exit code (part of Result#violations?). Dead icons stay reporting-only — deleting a file is a human decision.
 
+### Detectors from other gems
+
+Other gems add detectors to `guardrails:audit` with `Guardrails::Report::Detectors.register(name, klass)`. They run after the built-ins and show up in the text report, the summary, `FORMAT=json` (under `extensions.<name>`), `FORMAT=html` and the TUI. The class answers:
+
+| Method | Does |
+| --- | --- |
+| `.enabled?(env:)` | Whether this audit runs it, from the audit's env vars or the gem's own config |
+| `.max_severity` | The most serious severity it reports; `SEVERITY=` above that skips it without running it |
+| `.new(root:, output:, style:)` | Built like the built-in detectors |
+| `#run` | Returns its result and prints its own section to `output` |
+| `#categories(result)` | `Report::Category`s for the TUI, HTML and JSON findings |
+| `#summary_entry(result)` | A `Report::Summary::Entry` for the rollup |
+| `#to_h(result)` | Its `FORMAT=json` fragment |
+| `#failing?(result)` | Its own exit-code rule |
+
+Registration checks the class has all of these. Detectors only read what's already on disk; they never capture or call an API, because the TUI re-runs every detector on each `r`. ui_guardrails-browser registers its heuristic review this way.
+
 ---
 
 ## Output
@@ -275,6 +293,35 @@ The editor is `$GUARDRAILS_EDITOR`, then `$VISUAL`, then `$EDITOR`. VS Code-fami
 
 ---
 
+## Coding agent hooks
+
+```bash
+bundle exec rake guardrails:hooks:install                  # Claude Code
+AGENT=claude,codex bundle exec rake guardrails:hooks:install
+AGENT=all bundle exec rake guardrails:hooks:install        # Claude Code, Codex, Cursor, Gemini CLI
+```
+
+This adds Guardrails to each agent's project hook config. It keeps whatever else is in that file and is safe to run again. Each hook calls `guardrails-hook <agent> <event>`, which runs only the parse-only checks: view drift (raw colours, Tailwind arbitrary values, inline styles, helper recommendations) and static a11y. A typical call takes a fraction of a second.
+
+It reports only what the agent introduced. A template is compared with its version at `HEAD`, so drift that was already there isn't the agent's to fix. Findings are matched by content, so a finding on a line that moved isn't counted as new.
+
+| When | What happens |
+| --- | --- |
+| After the agent edits a template | The drift it just introduced goes back to it as context. Nothing is blocked. |
+| When it tries to finish | New **errors** in any template changed since `HEAD` send it back to work, once per turn. Warnings alone don't. |
+| When a session starts | Notes from other gems (ui_guardrails-browser adds open visual-review rejections). |
+
+| Agent | Config | Notes |
+| --- | --- | --- |
+| Claude Code | `.claude/settings.json` | `PostToolUse`, `Stop`, `SessionStart` |
+| Codex | `.codex/hooks.json` | Same events. Edits arrive as patches, so file names come from the patch. Trust the hooks in `/hooks` once. |
+| Cursor | `.cursor/hooks.json` | `stop` and `sessionStart` only: Cursor's after-edit output doesn't reliably reach the model, so the stop check covers every changed template. Cursor also runs `.claude/settings.json` hooks; the hook recognises Cursor's input and doesn't run twice. |
+| Gemini CLI | `.gemini/settings.json` | `AfterTool` (`write_file`, `replace`), `AfterAgent`, `SessionStart` |
+
+The hook never breaks the agent's turn: if anything goes wrong it prints `{}`, explains on stderr, and exits 0. Other gems add to the same events with `Guardrails::Hooks.register(name, contributor)`, shipped at `lib/guardrails/hook_contributors/<name>.rb` so the hook finds them without booting the app.
+
+---
+
 ## CI
 
 The audit task is a single shell command:

data/doc/ROADMAP.md

@@ -132,7 +132,10 @@ The planned roadmap ended at V2. Running the gem on real codebases (Patchvault:
 | Emoji + glyph icon detection | ✅ shipped (1.5.0) | `Guardrails::Icons::EmojiScan` catches emoji pictographs and Unicode-dingbat glyphs used as UI iconography — grapheme-cluster iteration (VS16 / ZWJ / flag / keycap count as one), range-first single-codepoint classification, per-file-type comment masking (Prism for Ruby, `<%# %>` for ERB, `//` `/* */` for JS/SCSS, `#` for YAML), `guardrails-ok: emoji` inline marker (first inline-escape convention in the gem), `allow_files` + `allow_chars` config, `SUGGEST=1` sprite-name hints. `guardrails:icons` also flipped to blocking — exit 1 on inline SVGs, unknown sprite refs, or emoji icons. |
 | Lookbook panel on the new data layer | not started | The auto-registered panel still renders from its own `ComponentReport`; it could render `Report::Finding`s and pick up suggestions for free. Icons findings could also flow through — the panel doesn't list icon findings today. |
 | Icons on the new data layer | not started | Icons stays outside `Report::Run` — its rake task calls `Icons.new(root:).run` directly. Migrating gets it into the TUI + HTML report for free but changes the rake shape; hold until there's demand. |
-| CI test workflow | not started | Specs only run inside the release workflow, on one Ruby. A PR-time matrix (3.4 + head) would catch floor regressions before tag time. |
+| Visual-diff adapter registry | ✅ shipped (1.6.0) | `Guardrails::VisualDiff.register_adapter` lets other gems add adapters; the name is checked when the adapter is built. `VisualDiff::Finding` gains `status`, `comment`, `regions`, `extra_details`. First consumer: ui_guardrails-browser's `:browser` adapter. |
+| Coding agent hooks | ✅ shipped (1.7.0) | `rake guardrails:hooks:install` wires Claude Code, Codex, Cursor and Gemini CLI to `guardrails-hook`: drift an agent introduces (compared with `HEAD`) goes back to it after each edit, and new errors send it back once when it tries to finish. Other gems contribute through `Guardrails::Hooks.register`; ui_guardrails-browser adds visual-review rejections. |
+| Detector registry | ✅ shipped (1.7.0) | `Guardrails::Report::Detectors.register(name, klass)` adds a detector to `Report::Run`, so it reaches the text report, summary, JSON (under `extensions`), HTML and TUI. Each decides when it's on (`enabled?(env:)`), how serious it can get (`max_severity`, so `SEVERITY=` skips it), and when it fails. First consumer: ui_guardrails-browser's heuristic review. |
+| CI test workflow | ✅ shipped | `.github/workflows/test.yml` runs `bundle exec rspec` (including the `examples/demo` integration spec) and `gem build` on every pull request and push to `main`, on Ruby 3.4 (the floor) and 4.0. Floor regressions and packaging mistakes surface on the PR instead of at tag time. |
 
 ---
 

data/doc/VISUAL-DIFF.md

@@ -61,6 +61,22 @@ With `enabled = true`, `rake guardrails:audit` always runs the visual-diff check
 
 Env always overrides Configuration.
 
+## Adapters from other gems
+
+`Guardrails.configuration.visual_diff.adapter` names a registered adapter. snap_diff is built in; other gems register theirs:
+
+```ruby
+Guardrails::VisualDiff.register_adapter(:browser) do |root:, config:|
+  MyAdapter.new(root: root) # #collect returns Guardrails::VisualDiff::Finding objects
+end
+```
+
+`config` is `Guardrails.configuration.visual_diff`. The name is checked when the adapter is built, so a host initializer can set `adapter = :browser` before the gem that registers it loads. An unregistered name fails with the registered ones listed.
+
+Besides the fields below, adapter findings can set `status` (`"changed"`, `"new"`, ...), `comment`, `regions` (`[{ x:, y:, w:, h: }]`) and `extra_details` (`[[label, value], ...]`). They show up as report details, and a finding with a `status` but no ratio is titled `[changed] scenario`. As with snap_diff, a finding with `mismatch_ratio: nil` always fails.
+
+[ui_guardrails-browser](https://github.com/meticulous/guardrails-browser) registers `:browser`, which reports unresolved items from its own capture and review loop.
+
 ## How the snap_diff adapter works
 
 The snap_diff-capybara gem commits baseline screenshots to git under `doc/screenshots/<name>.png` and, on test failure, writes a sibling `<name>.diff.png` (changed pixels in red) plus a `<name>.heatmap.diff.png` (variance density). Tests fail on baseline mismatches in CI, so the diff files are an artifact of "this regression slipped through to the artifact directory."

data/exe/guardrails-hook

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Called by a coding agent's hooks: `guardrails-hook <agent> <event>`,
+# with the agent's hook input on stdin. `rake guardrails:hooks:install`
+# writes the agent configuration that calls it.
+require "guardrails"
+require "guardrails/hooks/runner"
+
+result = Guardrails::Hooks::Runner.call(agent: ARGV[0], event: ARGV[1], stdin: $stdin.read, env: ENV)
+$stdout.write(result.stdout)
+$stderr.write(result.stderr)
+exit result.exit_code

data/lib/guardrails/a11y_audit.rb

@@ -62,6 +62,18 @@ module Guardrails
       )]
     end
 
+    # One template's findings without printing. `content` scans a
+    # version that isn't on disk (see Audit#scan_source).
+    def scan_source(path, content = nil)
+      scan_file(Pathname(path).expand_path(@root), content)
+    end
+
+    # Whether a full run would scan this file.
+    def covers?(path)
+      relative = Pathname(path).expand_path(@root).relative_path_from(@root).to_s
+      SCAN_PATTERNS.any? { |pattern| File.fnmatch?(pattern, relative, File::FNM_PATHNAME) }
+    end
+
     private
 
     FRAMING = [
@@ -77,8 +89,8 @@ module Guardrails
         .uniq
     end
 
-    def scan_file(path)
-      content = File.read(path, encoding: Encoding::UTF_8)
+    def scan_file(path, content = nil)
+      content ||= File.read(path, encoding: Encoding::UTF_8)
       lines = content.lines
       result = ErbParser.parse(content)
       @current_document = result.document

data/lib/guardrails/audit.rb

@@ -123,6 +123,25 @@ module Guardrails
       end
     end
 
+    # One template's violations, above the severity floor, without
+    # printing. `content` scans a version that isn't on disk (the
+    # agent hooks compare a file with its version at HEAD). Doesn't
+    # check scan_paths or ignores; ask `covers?` first.
+    def scan_source(path, content = nil)
+      scan_file(Pathname(path).expand_path(@root), content).select do |v|
+        Report::Severity.include?(SEVERITY_FOR_TYPE.fetch(v.type, :warning), @min_severity)
+      end
+    end
+
+    # Whether a full run would scan this file: a template under one of
+    # the scan paths that isn't ignored.
+    def covers?(path)
+      path = Pathname(path).expand_path(@root)
+      return false unless path.to_s.end_with?(".html.erb")
+
+      scan_paths.any? { |dir| path.to_s.start_with?("#{@root.join(dir)}/") } && !ignored?(path)
+    end
+
     private
 
     def load_audit_config
@@ -164,8 +183,8 @@ module Guardrails
       end
     end
 
-    def scan_file(file)
-      content = File.read(file, encoding: Encoding::UTF_8)
+    def scan_file(file, content = nil)
+      content ||= File.read(file, encoding: Encoding::UTF_8)
       original_lines = content.lines
       ast_result = ErbParser.parse(content)
 

data/lib/guardrails/configuration.rb

@@ -44,8 +44,9 @@ module Guardrails
       DEFAULT_ADAPTER       = :snap_diff
       DEFAULT_SNAP_DIFF_DIR = "doc/screenshots"
       DEFAULT_THRESHOLD     = 0.0 # any non-zero mismatch fails
-      KNOWN_ADAPTERS        = %i[snap_diff backstop].freeze
 
+      # `backstop_json` is reserved for the BackstopJS adapter and unused
+      # until it lands; kept so initializers that already set it still load.
       attr_accessor :enabled, :adapter, :snap_diff_dir, :backstop_json, :threshold
 
       def initialize
@@ -56,16 +57,14 @@ module Guardrails
         @threshold     = DEFAULT_THRESHOLD
       end
 
+      # Whether the name is a registered adapter is checked when the
+      # adapter is built (VisualDiff#adapter), not here: an adapter from
+      # another gem may register after this initializer runs.
       def adapter=(value)
         raise ArgumentError, "visual_diff.adapter cannot be nil" if value.nil?
         raise ArgumentError, "visual_diff.adapter cannot be blank" if value.respond_to?(:strip) && value.strip.empty?
 
-        sym = value.to_sym
-        unless KNOWN_ADAPTERS.include?(sym)
-          raise ArgumentError,
-                "Unknown visual_diff adapter #{value.inspect}; expected one of #{KNOWN_ADAPTERS.inspect}"
-        end
-        @adapter = sym
+        @adapter = value.to_sym
       end
 
       def threshold=(value)

data/lib/guardrails/hooks/adapters.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Guardrails
+  module Hooks
+    # One per coding agent: where its hook config lives, which of its
+    # events map to Guardrails' edit / stop / session_start, how to read
+    # its hook input, and the exact output shape it expects. The shapes
+    # differ enough (Codex rejects unknown keys, Cursor continues a turn
+    # with `followup_message`) that each agent gets its own.
+    module Adapters
+      # Claude Code: `.claude/settings.json`. PostToolUse output reaches
+      # the model as `additionalContext`; Stop blocks with
+      # `decision: "block"`.
+      class Claude
+        def name = "claude"
+        def config_path = ".claude/settings.json"
+        def config_extra = {}
+
+        def config_entries(command)
+          {
+            "PostToolUse" => [group(command.call("edit"), matcher: "Edit|Write|MultiEdit", timeout: 30)],
+            "Stop" => [group(command.call("stop"), timeout: 60)],
+            "SessionStart" => [group(command.call("session_start"), matcher: "startup|resume|clear|compact", timeout: 30)]
+          }
+        end
+
+        # Hook commands run in the session's directory, which may not be
+        # the app's; Claude Code and Gemini CLI set the project's.
+        def command_prefix = %(cd "$CLAUDE_PROJECT_DIR" && )
+
+        def project_dir(input, env)
+          env["CLAUDE_PROJECT_DIR"] || input["cwd"]
+        end
+
+        def files(input, _root)
+          [input.dig("tool_input", "file_path")].compact
+        end
+
+        def continued?(input)
+          input["stop_hook_active"] == true
+        end
+
+        def output(kind, outcome)
+          case kind
+          when :stop then outcome.block ? { "decision" => "block", "reason" => outcome.message } : {}
+          when :edit then context("PostToolUse", outcome)
+          else context("SessionStart", outcome)
+          end
+        end
+
+        private
+
+        def context(event_name, outcome)
+          return {} if outcome.notes.empty?
+
+          { "hookSpecificOutput" => { "hookEventName" => event_name, "additionalContext" => outcome.message } }
+        end
+
+        def group(command, matcher: nil, timeout: nil)
+          hook = { "type" => "command", "command" => command }
+          hook["timeout"] = timeout if timeout
+          matcher ? { "matcher" => matcher, "hooks" => [hook] } : { "hooks" => [hook] }
+        end
+      end
+
+      # Codex CLI: `.codex/hooks.json`, same events and nesting as Claude
+      # Code. Every edit is an `apply_patch` call whose input is the raw
+      # patch, so file names come from its headers. Codex rejects output
+      # keys it doesn't know, and treats empty stdout on Stop as invalid.
+      class Codex < Claude
+        PATCH_FILE = /^\*\*\* (?:Add File|Update File|Move to): (.+)$/
+
+        def name = "codex"
+        def config_path = ".codex/hooks.json"
+
+        def config_entries(command)
+          super.merge("PostToolUse" => [group(command.call("edit"), matcher: "^apply_patch$", timeout: 30)])
+        end
+
+        # Codex runs hooks in the session's directory; Bundler finds the
+        # app's Gemfile from there.
+        def command_prefix = ""
+
+        def project_dir(input, _env)
+          input["cwd"]
+        end
+
+        def files(input, _root)
+          patch = input.dig("tool_input", "command")
+          return [] unless patch.is_a?(String)
+
+          patch.scan(PATCH_FILE).flatten.map(&:strip).map { |file| File.expand_path(file, input["cwd"] || Dir.pwd) }
+        end
+      end
+
+      # Cursor: `.cursor/hooks.json` (version 1). Its after-edit output
+      # doesn't reliably reach the model, so Cursor gets the stop and
+      # session-start hooks; the stop hook covers every template changed
+      # since HEAD. `followup_message` becomes the next user message.
+      class Cursor
+        def name = "cursor"
+        def config_path = ".cursor/hooks.json"
+        def config_extra = { "version" => 1 }
+        def command_prefix = ""
+
+        def config_entries(command)
+          {
+            "stop" => [{ "command" => command.call("stop"), "timeout" => 60 }],
+            "sessionStart" => [{ "command" => command.call("session_start"), "timeout" => 30 }]
+          }
+        end
+
+        def project_dir(input, env)
+          Array(input["workspace_roots"]).first || env["CURSOR_PROJECT_DIR"] || env["CLAUDE_PROJECT_DIR"]
+        end
+
+        def files(input, _root)
+          [input["file_path"]].compact
+        end
+
+        # A turn the user aborted, or one a stop hook already continued,
+        # isn't sent back again.
+        def continued?(input)
+          input["loop_count"].to_i.positive? || (input.key?("status") && input["status"] != "completed")
+        end
+
+        def output(kind, outcome)
+          case kind
+          when :stop then outcome.block ? { "followup_message" => outcome.message } : {}
+          else outcome.notes.empty? ? {} : { "additional_context" => outcome.message }
+          end
+        end
+      end
+
+      # Gemini CLI: `.gemini/settings.json`. AfterTool appends
+      # `additionalContext` to the tool result; AfterAgent blocks with
+      # `decision: "block"`. Timeouts are in milliseconds.
+      class Gemini < Claude
+        def name = "gemini"
+        def config_path = ".gemini/settings.json"
+        def command_prefix = %(cd "$GEMINI_PROJECT_DIR" && )
+
+        def config_entries(command)
+          {
+            "AfterTool" => [group(command.call("edit"), matcher: "write_file|replace", timeout: 30_000)],
+            "AfterAgent" => [group(command.call("stop"), timeout: 60_000)],
+            "SessionStart" => [group(command.call("session_start"), matcher: "startup|resume|clear", timeout: 30_000)]
+          }
+        end
+
+        def project_dir(input, env)
+          env["GEMINI_PROJECT_DIR"] || input["cwd"]
+        end
+
+        def files(input, _root)
+          file = input.dig("tool_input", "file_path")
+          file ? [File.expand_path(file, input["cwd"] || Dir.pwd)] : []
+        end
+
+        def output(kind, outcome)
+          case kind
+          when :stop then outcome.block ? { "decision" => "block", "reason" => outcome.message } : {}
+          else outcome.notes.empty? ? {} : { "hookSpecificOutput" => { "additionalContext" => outcome.message } }
+          end
+        end
+
+        private
+
+        def group(command, matcher: nil, timeout: nil)
+          super.tap { |entry| entry["hooks"].first["name"] = "guardrails" }
+        end
+      end
+
+      ALL = [Claude.new, Codex.new, Cursor.new, Gemini.new].to_h { |adapter| [adapter.name, adapter] }.freeze
+
+      def self.fetch(name)
+        ALL.fetch(name.to_s) do
+          raise Error, "Unknown agent #{name.inspect}; expected one of #{ALL.keys.join(", ")}"
+        end
+      end
+
+      # Cursor also runs the hooks in `.claude/settings.json`, with
+      # Cursor's own input. The input says who's calling.
+      def self.cursor_input?(input)
+        input.key?("cursor_version") || input.key?("conversation_id")
+      end
+    end
+  end
+end

data/lib/guardrails/hooks/config_file.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module Guardrails
+  module Hooks
+    # Adds Guardrails' hook commands to an agent's JSON config without
+    # touching anything else in it: other settings, and other hooks on
+    # the same events, stay as they were. Running it twice changes
+    # nothing the second time.
+    class ConfigFile
+      attr_reader :path
+
+      def initialize(path)
+        @path = Pathname(path)
+      end
+
+      # `entries` maps an event name to the list entries to add under
+      # `hooks.<event>` (each a Hash in the agent's own shape). An entry
+      # counts as present when one with the same command is there.
+      # `extra` merges top-level keys that must be set (Cursor's
+      # `version`). Returns true when the file changed.
+      def add(entries, extra: {})
+        config = read
+        before = JSON.generate(config)
+        extra.each { |key, value| config[key] = value unless config.key?(key) }
+        hooks = (config["hooks"] ||= {})
+        raise Error, "#{@path}: `hooks` isn't an object" unless hooks.is_a?(Hash)
+
+        entries.each do |event, list|
+          existing = (hooks[event] ||= [])
+          raise Error, "#{@path}: `hooks.#{event}` isn't a list" unless existing.is_a?(Array)
+
+          list.each { |entry| existing << entry unless commands(existing).include?(command(entry)) }
+        end
+        return false if JSON.generate(config) == before
+
+        @path.dirname.mkpath
+        @path.write("#{JSON.pretty_generate(config)}\n")
+        true
+      end
+
+      private
+
+      def read
+        return {} unless @path.file?
+
+        text = @path.read
+        return {} if text.strip.empty?
+
+        config = JSON.parse(text)
+        raise Error, "#{@path} isn't a JSON object" unless config.is_a?(Hash)
+
+        config
+      rescue JSON::ParserError => e
+        raise Error, "#{@path} isn't valid JSON (#{e.message.lines.first.strip}); fix it or add the hooks by hand"
+      end
+
+      # Commands in a list of entries, flat (`{"command": ...}`) or
+      # grouped (`{"matcher": ..., "hooks": [{"command": ...}]}`).
+      def commands(list)
+        list.flat_map { |entry| entry.is_a?(Hash) ? [entry["command"], *Array(entry["hooks"]).map { |h| h["command"] if h.is_a?(Hash) }] : [] }.compact
+      end
+
+      def command(entry)
+        entry["command"] || Array(entry["hooks"]).filter_map { |h| h["command"] }.first
+      end
+    end
+  end
+end

data/lib/guardrails/hooks/drift.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "open3"
+require "pathname"
+require "stringio"
+require_relative "../audit"
+require_relative "../a11y_audit"
+
+module Guardrails
+  module Hooks
+    # The drift a coding agent introduced: what the parse-only checks
+    # (Audit, A11yAudit) find in a template now, minus what they find in
+    # the same file at HEAD. Drift that was already there isn't the
+    # agent's to fix unless someone asks, so the hooks never mention it.
+    #
+    # Lines move as a file is edited, so findings are matched by
+    # category and snippet, once per occurrence: a template that had two
+    # raw colours at HEAD and has three now has one new one.
+    class Drift
+      Item = Struct.new(:file, :line, :category, :severity, :title, :suggestion, :snippet, keyword_init: true) do
+        def to_s
+          text = "#{file}:#{line} #{title}"
+          suggestion ? "#{text} (#{suggestion})" : text
+        end
+
+        def error?
+          severity == :error
+        end
+
+        def key
+          [category, snippet.to_s.strip]
+        end
+      end
+
+      def initialize(root:)
+        @root = Pathname(root).expand_path
+        @audit = Audit.new(root: @root, output: StringIO.new)
+        @a11y = A11yAudit.new(root: @root, output: StringIO.new)
+      end
+
+      # New findings in the given files (absolute or relative to root).
+      def introduced(files)
+        files.filter_map { |file| relative(file) }.uniq.flat_map { |file| introduced_in(file) }
+      end
+
+      # Templates changed since HEAD, or untracked, relative to root.
+      # Empty outside a git repository.
+      def changed_files
+        (git("diff", "--name-only", "--relative", "HEAD") + git("ls-files", "--others", "--exclude-standard"))
+          .uniq.select { |file| file.end_with?(".html.erb") && @root.join(file).file? }
+      end
+
+      private
+
+      def introduced_in(file)
+        return [] unless @root.join(file).file?
+
+        now = findings(file, nil)
+        return now if now.empty?
+
+        before = head_content(file)
+        return now if before.nil?
+
+        remaining = findings(file, before).map(&:key).tally
+        now.reject do |item|
+          next false unless remaining.fetch(item.key, 0).positive?
+
+          remaining[item.key] -= 1
+          true
+        end
+      end
+
+      def findings(file, content)
+        categories = []
+        categories += @audit.categories(@audit.scan_source(file, content)) if @audit.covers?(file)
+        categories += @a11y.categories(@a11y.scan_source(file, content)) if @a11y.covers?(file)
+        categories.flat_map(&:findings).map do |finding|
+          Item.new(file: file, line: finding.location&.line, category: finding.category, severity: finding.severity,
+                   title: finding.title, suggestion: finding.suggestion, snippet: finding.snippet)
+        end
+      end
+
+      def head_content(file)
+        out, status = Open3.capture2("git", "show", "HEAD:./#{file}", chdir: @root.to_s, err: File::NULL)
+        status.success? ? out.force_encoding(Encoding::UTF_8) : nil
+      rescue SystemCallError
+        nil
+      end
+
+      def git(*args)
+        out, status = Open3.capture2("git", *args, chdir: @root.to_s, err: File::NULL)
+        status.success? ? out.lines.map(&:chomp).reject(&:empty?) : []
+      rescue SystemCallError
+        []
+      end
+
+      # nil for a file outside the app.
+      def relative(file)
+        relative = Pathname(file).expand_path(@root).relative_path_from(@root).to_s
+        relative unless relative.start_with?("..")
+      end
+    end
+  end
+end

data/lib/guardrails/hooks/installer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../hooks"
+require_relative "adapters"
+require_relative "config_file"
+
+module Guardrails
+  module Hooks
+    # Writes each agent's hook config for `rake guardrails:hooks:install`,
+    # merged into what's there.
+    class Installer
+      Change = Struct.new(:agent, :path, :changed, keyword_init: true)
+
+      def initialize(root:, agents:)
+        @root = Pathname(root)
+        @adapters = agents.map { |agent| Adapters.fetch(agent) }
+      end
+
+      def call
+        @adapters.map do |adapter|
+          path = @root.join(adapter.config_path)
+          command = ->(event) { "#{adapter.command_prefix}#{executable} #{adapter.name} #{event}" }
+          changed = ConfigFile.new(path).add(adapter.config_entries(command), extra: adapter.config_extra)
+          Change.new(agent: adapter.name, path: path.relative_path_from(@root).to_s, changed: changed)
+        end
+      end
+
+      private
+
+      # `bundle exec` when the app's Gemfile has the gem; the bare
+      # executable for sidecar installs.
+      def executable
+        gemfile = @root.join("Gemfile")
+        bundled = gemfile.file? && gemfile.read.match?(/^\s*gem\s+["']ui_guardrails["']/)
+        bundled ? "bundle exec guardrails-hook" : "guardrails-hook"
+      end
+    end
+  end
+end

data/lib/guardrails/hooks/runner.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../hooks"
+require_relative "adapters"
+
+module Guardrails
+  module Hooks
+    # `guardrails-hook <agent> <event>`: reads the agent's hook input,
+    # runs the checks for the event, and answers in the agent's shape.
+    #
+    # It never breaks the agent's turn. Any failure prints `{}` (every
+    # agent accepts it as "nothing to say") with the error on stderr,
+    # and exits 0.
+    class Runner
+      Result = Struct.new(:stdout, :stderr, :exit_code, keyword_init: true)
+      EVENTS = { "edit" => :edit, "stop" => :stop, "session_start" => :session_start }.freeze
+      QUIET = Result.new(stdout: "{}\n", stderr: "", exit_code: 0).freeze
+
+      def self.call(**kwargs)
+        new(**kwargs).call
+      end
+
+      def initialize(agent:, event:, stdin:, env: ENV)
+        @agent = agent
+        @event = event
+        @stdin = stdin
+        @env = env
+      end
+
+      def call
+        kind = EVENTS.fetch(@event.to_s) do
+          raise Error, "Unknown event #{@event.inspect}; expected #{EVENTS.keys.join(", ")}"
+        end
+        input = parse(@stdin)
+        adapter = adapter_for(input)
+        return QUIET unless adapter
+
+        root = root_for(input, adapter)
+        event = Event.new(kind: kind, root: root, files: adapter.files(input, root),
+                          continued: adapter.continued?(input))
+        Hooks.load_contributors
+        Result.new(stdout: "#{JSON.generate(adapter.output(kind, Hooks.check(event)))}\n", stderr: "", exit_code: 0)
+      rescue StandardError, ScriptError => e
+        Result.new(stdout: QUIET.stdout, stderr: "guardrails-hook: #{e.class}: #{e.message}\n", exit_code: 0)
+      end
+
+      private
+
+      # Strips the byte-order mark Cursor sends on Windows.
+      def parse(text)
+        text = text.to_s.dup.force_encoding(Encoding::UTF_8).delete_prefix("")
+        return {} if text.strip.empty?
+
+        input = JSON.parse(text)
+        input.is_a?(Hash) ? input : {}
+      end
+
+      # Cursor runs `.claude/settings.json` hooks too, with its own
+      # input. When the project has Cursor hooks of its own, that call
+      # is a duplicate and does nothing; otherwise it's answered as
+      # Cursor.
+      def adapter_for(input)
+        adapter = Adapters.fetch(@agent)
+        return adapter unless adapter.name != "cursor" && Adapters.cursor_input?(input)
+
+        cursor = Adapters.fetch("cursor")
+        root = root_for(input, cursor)
+        own = Pathname(root).join(cursor.config_path)
+        own.file? && own.read.include?("guardrails-hook") ? nil : cursor
+      end
+
+      # The app is where the Gemfile is when run with `bundle exec`;
+      # otherwise the agent's project directory.
+      def root_for(input, adapter)
+        gemfile = @env["BUNDLE_GEMFILE"].to_s
+        return Pathname(gemfile).dirname.expand_path unless gemfile.empty?
+
+        Pathname(adapter.project_dir(input, @env) || Dir.pwd).expand_path
+      end
+    end
+  end
+end

data/lib/guardrails/hooks.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../guardrails"
+require_relative "hooks/drift"
+require_relative "hooks/config_file"
+
+module Guardrails
+  # Coding-agent hooks (Claude Code, Codex, Cursor, Gemini CLI): drift
+  # the agent introduces is reported back to it while it works, and it
+  # isn't allowed to end its turn with new errors. Adapters translate
+  # each agent's hook input and output; the checks here don't know
+  # which agent is asking.
+  #
+  #   - edit: after the agent edits files, the drift it introduced in
+  #     them, as context for its next step
+  #   - stop: when it tries to finish, new errors in any template
+  #     changed since HEAD send it back to work, once
+  #   - session_start: context for a new session, from contributors
+  #
+  # Other gems contribute to the same events with `Hooks.register`
+  # (ui_guardrails-browser adds visual-review rejections). A gem ships
+  # its contributor at `lib/guardrails/hook_contributors/<name>.rb`,
+  # which the runner loads, so hooks work without booting the app.
+  module Hooks
+    # One hook call, whatever the agent. `continued` is true when a
+    # stop hook has already sent the agent back once this turn.
+    Event = Struct.new(:kind, :root, :files, :continued, keyword_init: true) do
+      def files
+        self[:files] || []
+      end
+    end
+
+    # What to tell the agent. `notes` reach it as context; with
+    # `block`, a stop is refused and the notes are the reason.
+    Outcome = Struct.new(:notes, :block, keyword_init: true) do
+      def self.none
+        new(notes: [], block: false)
+      end
+
+      def notes
+        self[:notes] || []
+      end
+
+      def message
+        notes.join("\n\n")
+      end
+
+      def merge(other)
+        return self if other.nil?
+
+        Outcome.new(notes: notes + other.notes, block: block || other.block)
+      end
+    end
+
+    KINDS = %i[edit stop session_start].freeze
+
+    @contributors = {}
+
+    class << self
+      # A contributor answers any of `on_edit(event)`, `on_stop(event)`
+      # and `on_session_start(event)` with an Outcome or nil.
+      def register(name, contributor)
+        @contributors[name.to_sym] = contributor
+      end
+
+      def unregister(name)
+        @contributors.delete(name.to_sym)
+      end
+
+      def contributors
+        @contributors.dup
+      end
+
+      # Loads contributors shipped by other gems on the load path. One
+      # that fails to load is skipped, with the error on stderr.
+      def load_contributors
+        Gem.find_files("guardrails/hook_contributors/*.rb").each do |path|
+          require path
+        rescue StandardError, ScriptError => e
+          warn "guardrails-hook: couldn't load #{path}: #{e.class}: #{e.message}"
+        end
+      end
+
+      # Guardrails' own checks, then each contributor's. A contributor
+      # that raises is skipped, so the rest still reach the agent.
+      def check(event)
+        outcome = case event.kind
+                  when :edit then on_edit(event)
+                  when :stop then on_stop(event)
+                  else Outcome.none
+                  end
+        method = :"on_#{event.kind}"
+        @contributors.reduce(outcome) do |result, (name, contributor)|
+          next result unless contributor.respond_to?(method)
+
+          result.merge(contributor.public_send(method, event))
+        rescue StandardError, ScriptError => e
+          warn "guardrails-hook: #{name}: #{e.class}: #{e.message}"
+          result
+        end
+      end
+
+      private
+
+      def on_edit(event)
+        items = Drift.new(root: event.root).introduced(event.files)
+        return Outcome.none if items.empty?
+
+        Outcome.new(notes: [describe(items, "Guardrails found drift you just introduced:")], block: false)
+      end
+
+      # Sent back once: a second refusal in the same turn could loop on
+      # a finding the agent can't fix.
+      def on_stop(event)
+        return Outcome.none if event.continued
+
+        drift = Drift.new(root: event.root)
+        items = drift.introduced(drift.changed_files)
+        return Outcome.none unless items.any?(&:error?)
+
+        Outcome.new(notes: [describe(items, "Fix the drift this change introduced before finishing:")], block: true)
+      end
+
+      def describe(items, heading)
+        lines = items.sort_by { |item| [item.error? ? 0 : 1, item.file, item.line.to_i] }
+                     .map { |item| "- [#{item.severity}] #{item}" }
+        ([heading] + lines).join("\n")
+      end
+    end
+  end
+end

data/lib/guardrails/report/detectors.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "summary"
+
+module Guardrails
+  module Report
+    # Detectors other gems add to `rake guardrails:audit`, run after the
+    # built-ins. ui_guardrails-browser registers its heuristic review
+    # here.
+    #
+    #     Guardrails::Report::Detectors.register(:heuristics, HeuristicsDetector)
+    #
+    # A registered detector class answers:
+    #
+    #   .enabled?(env:)       whether this audit runs it; env is the
+    #                         audit's environment (ENV or a Hash)
+    #   .max_severity         the most serious severity it reports, so
+    #                         SEVERITY= can skip it instead of running it
+    #                         and discarding everything
+    #   .new(root:, output:, style:)
+    #   #run                  returns its result and prints its own
+    #                         section to output
+    #   #categories(result)   Report::Categories; detail labels unique,
+    #                         values strings
+    #   #summary_entry(result)  a Summary::Entry for the rollup
+    #   #to_h(result)         its FORMAT=json fragment, under
+    #                         `extensions.<name>`
+    #   #failing?(result)     its own exit-code rule
+    #
+    # Detectors only read what's already on disk. They never capture
+    # or call an API: the TUI re-runs every detector on each `r`.
+    module Detectors
+      CLASS_METHODS = %i[enabled? max_severity].freeze
+      INSTANCE_METHODS = %i[run categories summary_entry to_h failing?].freeze
+
+      @registered = {}
+
+      class << self
+        def register(name, detector_class)
+          missing = CLASS_METHODS.reject { |m| detector_class.respond_to?(m) }.map { |m| ".#{m}" } +
+                    INSTANCE_METHODS.reject { |m| detector_class.method_defined?(m) }.map { |m| "##{m}" }
+          unless missing.empty?
+            raise ArgumentError, "#{detector_class} can't be registered as a detector; it's missing #{missing.join(", ")}"
+          end
+          unless Summary::SEVERITY_ORDER.include?(detector_class.max_severity)
+            raise ArgumentError, "#{detector_class}.max_severity must be one of #{Summary::SEVERITY_ORDER.inspect}"
+          end
+
+          @registered[name.to_sym] = detector_class
+        end
+
+        def unregister(name)
+          @registered.delete(name.to_sym)
+        end
+
+        def registered
+          @registered.dup
+        end
+
+        # The registered detectors this environment switches on.
+        def enabled(env)
+          @registered.select { |_name, detector_class| detector_class.enabled?(env: env) }
+        end
+      end
+    end
+  end
+end

data/lib/guardrails/report/finding.rb

@@ -43,9 +43,19 @@ module Guardrails
         {
           category: category, severity: severity, title: title, suggestion: suggestion,
           locations: locations.map(&:to_h), snippet: snippet,
-          details: details.to_h, auto_fix: auto_fix || false
+          details: details_hash, auto_fix: auto_fix || false
         }
       end
+
+      # `details` allows a label more than once (two screenshots, several
+      # regions). A plain `to_h` kept only the last value; a repeated
+      # label collects its values into an array instead. Labels that
+      # appear once stay scalars, so existing JSON doesn't change.
+      def details_hash
+        details.each_with_object({}) do |(label, value), hash|
+          hash[label] = hash.key?(label) ? Array(hash[label]) << value : value
+        end
+      end
     end
 
     # A named group of findings plus the framing paragraph that

data/lib/guardrails/report/run.rb

@@ -14,6 +14,7 @@ require_relative "../visual_diff"
 require_relative "summary"
 require_relative "finding"
 require_relative "severity"
+require_relative "detectors"
 require_relative "../configuration"
 
 module Guardrails
@@ -70,7 +71,8 @@ module Guardrails
             suggest: truthy?(env["SUGGEST"]), apply: truthy?(env["APPLY"]),
             axe_json: env["AXE_JSON"], visual_diff: visual_diff_on,
             similarity: similarity, patterns: patterns, classitis: classitis,
-            min_severity: Severity.parse(env["SEVERITY"]))
+            min_severity: Severity.parse(env["SEVERITY"]),
+            extensions: Detectors.enabled(env))
       end
 
       def self.truthy?(value)
@@ -82,11 +84,15 @@ module Guardrails
       # ANSI decisions against the terminal, or the report body prints
       # plain while the summary around it is colored. Pass nil to get
       # uncolored output (what JSON mode wants — the body is discarded).
+      #
+      # `extensions` maps names to registered detector classes (see
+      # Detectors); `from_env` passes the ones the environment enables.
       def initialize(root:, style: nil, suggest: false, apply: false,
                      axe_json: nil, visual_diff: false,
                      similarity: {}, patterns: {}, classitis: {},
-                     min_severity: Severity::DEFAULT)
+                     min_severity: Severity::DEFAULT, extensions: {})
         @min_severity = min_severity
+        @extension_classes = extensions
         @root = Pathname(root)
         @style = style
         @suggest = suggest
@@ -121,9 +127,22 @@ module Guardrails
         @a11y_deep = @a11y_deep_runner ? detect(@a11y_deep_runner) : []
         @visual_diff_runner = @visual_diff_on ? VisualDiff.new(**common) : nil
         @visual_diff = @visual_diff_runner ? detect(@visual_diff_runner) : []
+        # Registered detectors run last, and only when they can report
+        # something at or above the severity floor.
+        @extensions = @extension_classes.filter_map do |name, detector_class|
+          next unless wanted?(detector_class.max_severity)
+
+          detector = detector_class.new(**common)
+          [name.to_sym, detector, detect(detector)]
+        end
         self
       end
 
+      # [name, detector, result] for each registered detector that ran.
+      def extensions
+        @extensions || []
+      end
+
       # Severities this run didn't look at (empty by default).
       def muted_severities
         Severity.muted(@min_severity)
@@ -168,12 +187,34 @@ module Guardrails
                 unit: "candidates", action: "consider extracting partials"),
           entry("class-itis", classitis.length, :suggestion,
                 unit: "clusters", action: "consider extracting component / @apply")
-        ]
+        ] + extensions.map { |_name, detector, result| detector.summary_entry(result) }
       end
 
-      # FORMAT=json payload. Shape is a public contract — unchanged
-      # since 1.0.0.
+      # FORMAT=json payload. Shape is a public contract: the keys below
+      # are unchanged since 1.0.0, and registered detectors only add an
+      # `extensions` key, present when one ran.
       def to_h
+        built_in.tap do |hash|
+          hash[:extensions] = extensions.to_h { |name, detector, result| [name, detector.to_h(result)] } if extensions.any?
+        end
+      end
+
+      # Exit-code contract: each detector fails on its own rule. Built-in
+      # errors and warnings fail on any finding, and so do similar
+      # partials; cross-codebase patterns and class-itis never fail.
+      # Deep a11y and visual diff fail when a finding crosses their
+      # threshold. Registered detectors decide for themselves.
+      def failing?
+        violations.any? || stimulus.violations? || similarity.any? ||
+          view_components.violations? || a11y.any? ||
+          (@a11y_deep_runner&.any_failing?(a11y_deep) || false) ||
+          (@visual_diff_runner&.any_failing?(visual_diff) || false) ||
+          extensions.any? { |_name, detector, result| detector.failing?(result) }
+      end
+
+      private
+
+      def built_in
         {
           summary: {
             violations: violations.length,
@@ -207,19 +248,6 @@ module Guardrails
         }
       end
 
-      # Exit-code contract: any error or warning fails; the suggestion-
-      # tier pattern / class-itis detectors don't. Deep a11y and visual
-      # diff only fail when a finding crosses their configured
-      # threshold, and are no-ops when not opted into.
-      def failing?
-        violations.any? || stimulus.violations? || similarity.any? ||
-          view_components.violations? || a11y.any? ||
-          (@a11y_deep_runner&.any_failing?(a11y_deep) || false) ||
-          (@visual_diff_runner&.any_failing?(visual_diff) || false)
-      end
-
-      private
-
       # Runs a detector and remembers the pair, so `categories` can ask
       # each detector to normalize its own result later — only
       # front-ends that want findings-as-data pay for building them.

data/lib/guardrails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Guardrails
-  VERSION = "1.5.0"
+  VERSION = "1.7.0"
 end

data/lib/guardrails/visual_diff.rb

@@ -14,7 +14,9 @@ module Guardrails
   #
   # Adapter selection comes from `Guardrails.configuration.visual_diff.adapter`
   # (default `:snap_diff`, the Rails-native baselines-in-git workflow).
-  # BackstopJS support tracked in issue #15.
+  # Other gems add adapters with `VisualDiff.register_adapter`; the
+  # ui_guardrails-browser gem registers `:browser`. BackstopJS support
+  # tracked in issue #15.
   class VisualDiff
     # Normalized across every adapter. Fields adapter-specific shapes
     # don't supply are nil — consumers should not assume presence.
@@ -30,6 +32,10 @@ module Guardrails
       :diff_path,       # relative path to the diff image, nil when no diff exists
       :url,             # optional — set by adapters whose scenarios carry URLs (BackstopJS)
       :selector,        # optional — same
+      :status,          # optional — adapter's review state, e.g. "changed", "new", "rejected"
+      :comment,         # optional — a reviewer's note on the change
+      :regions,         # optional — changed areas, [{ x:, y:, w:, h: }, ...]
+      :extra_details,   # optional — more [label, value] pairs for the report
       keyword_init: true
     ) do
       def to_h
@@ -37,6 +43,34 @@ module Guardrails
       end
     end
 
+    @adapters = {}
+
+    class << self
+      # Adds an adapter under `name`. The block builds it:
+      #
+      #     Guardrails::VisualDiff.register_adapter(:browser) do |root:, config:|
+      #       MyAdapter.new(root: root)
+      #     end
+      #
+      # `config` is `Guardrails.configuration.visual_diff`. The adapter's
+      # `#collect` returns `VisualDiff::Finding`s; a finding with
+      # `mismatch_ratio: nil` always fails, one with a ratio fails above
+      # the threshold.
+      def register_adapter(name, &factory)
+        raise ArgumentError, "register_adapter needs a block that builds the adapter" unless factory
+
+        @adapters[name.to_sym] = factory
+      end
+
+      def adapters
+        @adapters.keys
+      end
+
+      def adapter_factory(name)
+        @adapters[name]
+      end
+    end
+
     def initialize(root:, output: $stdout,
                    adapter: nil, threshold: nil, style: nil)
       @root = Pathname(root)
@@ -82,8 +116,7 @@ module Guardrails
             title: "#{ratio_label(f)} #{f.scenario}#{f.viewport ? " (#{f.viewport})" : ""}",
             suggestion: SUGGESTION,
             locations: [f.diff_path, f.baseline_path].compact.map { |path| Report::Location.new(file: path) },
-            details: [["baseline", f.baseline_path], ["diff", f.diff_path], ["url", f.url], ["selector", f.selector]]
-                     .reject { |_, v| v.nil? }
+            details: details_for(f)
           )
         }
       )]
@@ -100,19 +133,27 @@ module Guardrails
     SUGGESTION = "compare baseline ↔ diff; accept the new baseline or fix the regression"
 
     def ratio_label(finding)
-      finding.mismatch_ratio.nil? ? "[diff present]" : "[#{(finding.mismatch_ratio * 100).round(2)}% mismatch]"
+      return "[#{(finding.mismatch_ratio * 100).round(2)}% mismatch]" unless finding.mismatch_ratio.nil?
+
+      finding.status ? "[#{finding.status}]" : "[diff present]"
+    end
+
+    def details_for(finding)
+      regions = finding.regions&.map { |r| "#{r[:x] || r["x"]},#{r[:y] || r["y"]} #{r[:w] || r["w"]}x#{r[:h] || r["h"]}" }
+      [["baseline", finding.baseline_path], ["current", finding.current_path], ["diff", finding.diff_path],
+       ["url", finding.url], ["selector", finding.selector], ["status", finding.status],
+       ["comment", finding.comment], ["regions", regions&.join("; ")]]
+        .reject { |_, v| v.nil? || v == "" } + Array(finding.extra_details)
     end
 
     def adapter
-      case @adapter_name
-      when :snap_diff
-        SnapDiff.new(
-          root: @root,
-          dir: Guardrails.configuration.visual_diff.snap_diff_dir
-        )
-      else
-        raise ArgumentError, "Unknown visual_diff adapter: #{@adapter_name.inspect}"
+      factory = self.class.adapter_factory(@adapter_name)
+      unless factory
+        raise ArgumentError,
+              "Unknown visual_diff adapter: #{@adapter_name.inspect}; registered: #{self.class.adapters.inspect}"
       end
+
+      factory.call(root: @root, config: Guardrails.configuration.visual_diff)
     end
 
     def coerce_adapter(value)
@@ -149,9 +190,14 @@ module Guardrails
         @output.puts "    #{@style.location("diff:     #{f.diff_path}")}" if f.diff_path
         @output.puts "    #{@style.location("url:      #{f.url}")}" if f.url
         @output.puts "    #{@style.location("selector: #{f.selector}")}" if f.selector
+        @output.puts "    #{@style.location("comment:  #{f.comment}")}" if f.comment
       end
     end
   end
 end
 
 require_relative "visual_diff/snap_diff"
+
+Guardrails::VisualDiff.register_adapter(:snap_diff) do |root:, config:|
+  Guardrails::VisualDiff::SnapDiff.new(root: root, dir: config.snap_diff_dir)
+end

data/lib/tasks/guardrails.rake

@@ -134,4 +134,27 @@ namespace :guardrails do
     root = defined?(Rails) ? Rails.root : Pathname(Dir.pwd)
     Guardrails::Tokens.new(root: root).run
   end
+
+  namespace :hooks do
+    desc "Add Guardrails to coding agents' hooks (AGENT=claude,codex,cursor,gemini or all; default claude)"
+    task :install do
+      require "guardrails/hooks/installer"
+      root = defined?(Rails) ? Rails.root : Pathname(Dir.pwd)
+      agents = ENV.fetch("AGENT", "claude").split(",").map(&:strip).reject(&:empty?)
+      agents = Guardrails::Hooks::Adapters::ALL.keys if agents == ["all"]
+
+      begin
+        changes = Guardrails::Hooks::Installer.new(root: root, agents: agents).call
+      rescue Guardrails::Error => e
+        abort e.message
+      end
+
+      changes.each do |change|
+        puts "#{change.changed ? "Added hooks to" : "Already set up:"} #{change.path} (#{change.agent})"
+      end
+      agents = changes.map(&:agent)
+      puts "Codex runs project hooks once you trust them in /hooks." if agents.include?("codex")
+      puts "Cursor and Gemini CLI run project hooks in trusted folders only." if agents.intersect?(%w[cursor gemini])
+    end
+  end
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: ui_guardrails
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.7.0
 platform: ruby
 authors:
 - John Athayde
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -69,7 +69,8 @@ description: 'Opinionated auditing and enforcement for design-system consistency
   component inventory, icon sprites, type scale, and color token management.'
 email:
 - jmpa@meticulous.com
-executables: []
+executables:
+- guardrails-hook
 extensions: []
 extra_rdoc_files: []
 files:
@@ -83,6 +84,7 @@ files:
 - doc/ROADMAP.md
 - doc/UPSTREAM-snap_diff-issue-draft.md
 - doc/VISUAL-DIFF.md
+- exe/guardrails-hook
 - lib/guardrails.rb
 - lib/guardrails/a11y_audit.rb
 - lib/guardrails/a11y_deep.rb
@@ -94,6 +96,12 @@ files:
 - lib/guardrails/cross_codebase_patterns.rb
 - lib/guardrails/erb_parser.rb
 - lib/guardrails/hex_normalizer.rb
+- lib/guardrails/hooks.rb
+- lib/guardrails/hooks/adapters.rb
+- lib/guardrails/hooks/config_file.rb
+- lib/guardrails/hooks/drift.rb
+- lib/guardrails/hooks/installer.rb
+- lib/guardrails/hooks/runner.rb
 - lib/guardrails/icons.rb
 - lib/guardrails/icons/emoji_scan.rb
 - lib/guardrails/init.rb
@@ -106,6 +114,7 @@ files:
 - lib/guardrails/lookbook/views/lookbook_panels/_guardrails.html.erb
 - lib/guardrails/partial_similarity.rb
 - lib/guardrails/railtie.rb
+- lib/guardrails/report/detectors.rb
 - lib/guardrails/report/finding.rb
 - lib/guardrails/report/html.rb
 - lib/guardrails/report/html/template.html.erb