ui_guardrails 1.6.0 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0bae61006af0fcdb91d543ab37539ed5f01bc653faa3a1732b56ee4f450d075
-  data.tar.gz: ee1b11b2668ee764377741beeac44b50e9507029c1469b5db866f1aa1e61ac93
+  metadata.gz: 32e83a5c20961feae0830c519f4bf0b3363bcd4774d4644bab49053ce02c8cd5
+  data.tar.gz: 8fbaaa46298c2ea2805b2b291354d36cf521fd6f11f948290d62e2796bbafb24
 SHA512:
-  metadata.gz: fe558c786b8286a5f5766c265e1b40b581ef139d05a4b989744ee6d98e1b2dc5d885fc9c1470853d393b23d9c10d99be70c5a1cd7127da6afab653aa0bee21ee
-  data.tar.gz: 89651a0654dcd990829f37e402c9a7b8d214573acf655c54c7460a3708cf7d6d1c8e4f34bdae064fb8b676faa0d02d96fa624d94c8bec492cedc86e967973e86
+  metadata.gz: 88fe2925e7787c6b0a63861d142f9d53e5e832395c7b22e7515400954f9a16f57dab73c2fa318b3df516ee5fa12af3e104604bd63125a08eb403eb3ed93f083d
+  data.tar.gz: 9ed0ec91a1310da006bf525c05163cec82e730c17838d22ba6e5c2ed2ab7607241541769dda5c60f9a7e2681b587bc5747d2116ddbef156e952bd6f079d8cbae

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. The installed command ends in `|| echo '{}'`, so the same holds when the hook can't start at all. That happens on a branch whose Gemfile doesn't have the gem, since the agent's config usually isn't tracked by git and outlives the branch. Running the install again replaces an earlier install's hooks instead of adding new ones beside them. 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

@@ -133,6 +133,8 @@ The planned roadmap ended at V2. Running the gem on real codebases (Patchvault:
 | 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. |
 | 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/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/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,97 @@
+# 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; an
+      # older form of the same Guardrails hook is replaced.
+      # `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 do |entry|
+            wanted = command(entry)
+            next if commands(existing).include?(wanted)
+
+            identity = wanted.to_s[OURS]
+            remove(existing, identity) if identity
+            existing << entry
+          end
+        end
+        return false if JSON.generate(config) == before
+
+        @path.dirname.mkpath
+        @path.write("#{JSON.pretty_generate(config)}\n")
+        true
+      end
+
+      private
+
+      # An earlier install of the same hook, whatever its exact command:
+      # reinstalling replaces it rather than adding a second.
+      OURS = /guardrails-hook \w+ \w+/
+
+      # Takes out the hook with this identity and any group it leaves
+      # empty; the user's own hooks, in the same group or not, stay.
+      def remove(list, identity)
+        list.reject! do |entry|
+          next false unless entry.is_a?(Hash)
+          next true if entry["command"].to_s.include?(identity)
+          next false unless entry["hooks"].is_a?(Array)
+
+          before = entry["hooks"].size
+          entry["hooks"].reject! { |hook| hook.is_a?(Hash) && hook["command"].to_s.include?(identity) }
+          entry["hooks"].empty? && before.positive?
+        end
+      end
+
+      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,43 @@
+# 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)
+          # Falls back to `{}`, the answer every agent reads as "nothing to
+          # say", when the hook can't start at all: a branch without the
+          # gem in its Gemfile, or a missing project directory.
+          command = ->(event) { "(#{adapter.command_prefix}#{executable} #{adapter.name} #{event}) || echo '{}'" }
+          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/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.6.0"
+  VERSION = "1.7.1"
 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.6.0
+  version: 1.7.1
 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