quality_gate 0.1.0

data/config/cops.yml

@@ -0,0 +1,37 @@
+QualityGate/AssociationDefaultBlockValue:
+  Description: 'Defer request-context association defaults in a callable.'
+  Enabled: false
+  VersionAdded: '0.1.0'
+  Safe: true
+
+QualityGate/PreferAfterSaveCommit:
+  Description: 'Use after_save_commit for literal create and update commit callbacks.'
+  Enabled: false
+  VersionAdded: '0.1.0'
+  Safe: true
+  SafeAutoCorrect: true
+
+QualityGate/PrivateOnlyConcern:
+  Description: 'Review concerns that expose only private instance behavior.'
+  Enabled: false
+  VersionAdded: '0.1.0'
+  Safe: false
+  ConcernPaths: []
+
+QualityGate/BroadcastInController:
+  Description: 'Review controller broadcasts for model ownership.'
+  Enabled: false
+  VersionAdded: '0.1.0'
+  Safe: false
+  Include:
+    - '**/app/controllers/**/*.rb'
+  AllowedMethods: []
+
+QualityGate/ControllerInstanceVariables:
+  Description: 'Limit a controller action to one instance variable (Sandi Metz rule four).'
+  Enabled: false
+  VersionAdded: '0.1.0'
+  Safe: true
+  Max: 1
+  Include:
+    - '**/app/controllers/**/*.rb'

data/config/reek.yml

@@ -0,0 +1,6 @@
+# Default Reek configuration shipped with quality_gate.
+# Used only when the host project has no .reek.yml of its own.
+detectors:
+  # Demanding a comment on every class pushes agents toward noise comments.
+  IrresponsibleModule:
+    enabled: false

data/config/rubocop.yml

@@ -0,0 +1,60 @@
+plugins:
+  - rubocop-rails
+  - rubocop-performance
+  - rubocop-minitest
+  - quality_gate/rubocop:
+      plugin_class_name: QualityGate::RuboCopPlugin
+
+AllCops:
+  NewCops: disable
+  TargetRubyVersion: "3.2"
+  Exclude:
+    - db/schema.rb
+    - bin/**/*
+    - node_modules/**/*
+    - vendor/**/*
+
+Metrics/CyclomaticComplexity:
+  # Catch branch-heavy methods before they become opaque.
+  Max: 6
+
+Metrics/AbcSize:
+  # Keep assignment, branch, and condition growth visible in review.
+  Max: 16
+
+# Sandi Metz rules one to three are plain RuboCop budgets. Rule four is
+# QualityGate/ControllerInstanceVariables, enabled at the bottom of this file.
+#
+# Test suites read as linear setup, action, assertion, so the length rules earn
+# nothing there. Exempt them from your own .rubocop.yml, not from here: a path in
+# an inherited gem config resolves against the gem directory, so "test/**/*"
+# written here would name this gem's tests and never yours.
+#
+#   Metrics/MethodLength:
+#     Exclude:
+#       - test/**/*
+#       - spec/**/*
+
+Metrics/MethodLength:
+  # Sandi Metz rule two: a method says one thing in five lines or fewer.
+  Max: 5
+
+Metrics/ClassLength:
+  # Sandi Metz rule one: a class stays under a hundred lines.
+  Max: 100
+
+Metrics/ParameterLists:
+  # Sandi Metz rule three: pass no more than four parameters.
+  Max: 4
+
+Style/Documentation:
+  # Library users should choose their own documentation style and coverage.
+  Enabled: false
+
+Metrics/BlockLength:
+  # Test cases and DSL blocks get noisy fast, so block length stays opt-in.
+  Enabled: false
+
+QualityGate/ControllerInstanceVariables:
+  # Sandi Metz rule four: a controller action instantiates one object.
+  Enabled: true

data/config/ruby.yml

@@ -0,0 +1,8 @@
+inherit_from: rubocop.yml
+
+# Plain Ruby projects do not load Rails or Rails-specific cops.
+Rails:
+  Enabled: false
+
+QualityGate/ControllerInstanceVariables:
+  Enabled: false

data/docs/codex.md

@@ -0,0 +1,31 @@
+# Codex and QualityGate
+
+Codex does not consume Claude Code `PostToolUse` or `Stop` hooks. The optional `.claude/settings.json`, `.claude/hooks/quality_gate_fast.rb`, and `.claude/hooks/quality_gate_verify_stop.rb` files are for Claude Code sessions and are installed only with `--agents`. In Codex, run the same gates manually or have the agent invoke them explicitly:
+
+- Run `bundle exec quality_gate fast` after Ruby edits.
+- Run `bundle exec quality_gate verify` before you finish a change.
+- Run `bundle exec quality_gate audit` before you merge security-sensitive work.
+
+Fix findings before you continue editing. Use `--format json` for structured results, and inspect `checks` alongside findings to see each tool's status and scope. Explicit selected paths must exist; a missing path is an input failure. A clean gate describes only its configured checks, not overall application correctness.
+
+Automatic Claude hooks can fail open or cap retries. An agent session ending is not proof of verification. CI should run the gate commands directly and enforce their exit status.
+
+Exit meanings stay the same in Codex and Claude Code:
+
+- Exit 0 means the gate ran clean.
+- Exit 1 means the gate reported findings and no tool failures.
+- Exit 2 means the gate could not complete cleanly because of invalid input, configuration, or another tool failure.
+
+If the automatic Claude Code hook becomes unavailable, inspect `log/quality_gate_hooks.jsonl`, run `bundle install`, and reinstall the generated integration with the setup command for your project.
+
+For a plain Ruby project, install or refresh the generated contract files with:
+
+```sh
+bundle exec quality_gate init --profile ruby --agents
+```
+
+For Rails:
+
+```sh
+bin/rails generate quality_gate:install --agents
+```

data/docs/dogfood-log.md

@@ -0,0 +1,47 @@
+# Validation guide
+
+The public acceptance fixtures exercise four representative incident classes with
+shipped defaults: N+1 queries, unsafe migrations, complexity creep, and untested
+changed code. The [incident catalogue](incidents.md) maps each class to its fixture,
+command, and expected finding. These fixtures test detection behavior; they do not
+establish compatibility with every application or dependency version.
+
+## Reproduce the checks
+
+After installing development dependencies, run the executable incident contracts:
+
+```sh
+bundle exec ruby -Itest test/acceptance/incident_catalog_test.rb
+```
+
+Run the complete test suite and aggregate coverage checks with:
+
+```sh
+COVERAGE=1 bundle exec rake test
+```
+
+Latency checks are opt-in because load and runtime configuration affect results:
+
+```sh
+QUALITY_GATE_ACCEPTANCE_TIMING=1 bundle exec ruby -Itest test/acceptance/latency_test.rb
+```
+
+The fixture budgets are below 2 seconds for a warm file-scoped `fast` run and below
+3 seconds for the installed hook round trip. These are test targets, not measured
+release guarantees. A skipped timing check provides no latency evidence.
+
+## Interpretation and limits
+
+A clean gate means its configured tools completed without reportable findings.
+A timeout, unavailable tool, skipped comparison, or unsupported dependency is not
+proof of clean application behavior. Inspect findings and warnings alongside exit
+status. The Stop hook can fail open when verification is unavailable; that outcome
+must not be counted as successful verification.
+
+Application initialization and third-party compatibility can prevent installation
+or checks from completing. Validate the generator, optional initializers, and all
+configured gates in the target application. Fixture results do not guarantee
+production compatibility, performance, reduced review time, or agent adoption.
+
+The public release includes reproducible fixture contracts rather than private
+application records. No current production cohort measurements are claimed.

data/docs/incidents.md

@@ -0,0 +1,18 @@
+# Incident catalogue
+
+These four executable examples preserve the defect classes covered by the acceptance tests.
+Each contract names the gate, detector, rule family, and message evidence that must catch the defect.
+
+| id | class | source | example | command | tool | rule | cause |
+|---|---|---|---|---|---|---|---|
+| n_plus_one | N+1 query | [Validation guide](dogfood-log.md#reproduce-the-checks) | test/fixtures/acceptance/n_plus_one | verify | test_suite | test_failure | USE eager loading |
+| unsafe_migration | Unsafe migration | [Validation guide](dogfood-log.md#reproduce-the-checks) | test/fixtures/acceptance/unsafe_migration | verify | test_suite | test_failure | Dangerous operation detected #strong_migrations |
+| complexity_creep | Complexity creep | [Validation guide](dogfood-log.md#reproduce-the-checks) | test/fixtures/acceptance/complexity_creep | fast | rubocop | Metrics/* | emitted metric name |
+| untested_change | Untested changed code | [Validation guide](dogfood-log.md#reproduce-the-checks) | test/fixtures/acceptance/untested_change | verify | undercover | uncovered_code | changed line range |
+
+## Capture the next escaped class
+
+A new escaped class is accepted only after its written source is recorded, a minimal fixture reproduces
+the defect with shipped defaults, and a failing expected-finding assertion names its tool, rule, and
+cause signature. Add the catalogue row only with those three pieces so documentation and execution
+cannot drift apart.

data/docs/releasing.md

@@ -0,0 +1,46 @@
+# Releasing Quality Gate
+
+Use Ruby 3.2 or newer and run these commands from the gem directory.
+
+```sh
+bin/setup
+bin/prepare_release
+```
+
+`bin/setup` installs the development bundle. `bin/prepare_release` runs the test
+suite and RuboCop, regenerates `llm.txt`, and builds
+`pkg/quality_gate-VERSION.gem`. It stops at the first failed prerequisite.
+Preparation only creates local files; publishing is a separate maintainer action.
+
+## Documentation
+
+`bin/generate_llm.rb` produces a deterministic index and short overview using an
+explicit list of public Markdown documents. It checks every linked document exists
+before replacing `llm.txt`. Run it after changing the documentation set and review
+the generated output. It requires only Ruby's standard library.
+
+## Executables
+
+The installed command lives in `exe/quality_gate`. The gemspec exposes it as
+`quality_gate`. Scripts in `bin/` are development tools and are excluded from the
+gem archive. `bin/console` opens an interactive session with the gem loaded.
+
+## Release checklist
+
+1. Update `lib/quality_gate/version.rb` and `CHANGELOG.md` for the intended release.
+2. Run `bin/prepare_release` and review the generated documentation and package.
+   Run `bundle exec quality_gate verify` to enforce the repository coverage budgets.
+   On the initial commit, Undercover cannot compare against a parent commit, so
+   local verification reports a skip and exits nonzero. CI accepts that skip only
+   on the root commit, with no other findings and clean test suite and SimpleCov
+   checks enforcing the configured aggregate line and branch coverage budgets. The
+   repository configuration remains unchanged during verification. Subsequent commits
+   run normal verification, including diff coverage; no extra baseline commit is required.
+3. Confirm the archive includes runtime code, configuration, licensing, and public
+   documentation, with no local paths, credentials, private logs, or internal plans.
+4. Commit the reviewed release in the public repository and tag the version.
+5. Publish the reviewed artifact with `gem push pkg/quality_gate-VERSION.gem`,
+   replacing `VERSION` with the actual release version. RubyGems MFA is required.
+
+The Rakefile also loads Bundler's gem tasks. Its `release` task can publish and
+push Git changes; use it only when those actions are intended.

data/exe/quality_gate

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "quality_gate"
+
+exit QualityGate::CLI.run(ARGV, dir: Dir.pwd)

data/lib/generators/quality_gate/install/install_generator.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../../../quality_gate/installation"
+
+if defined?(Rails::Generators::Base)
+  module QualityGate
+    # Defines the ordered command shell for installing Quality Gate into a Rails application.
+    class InstallGenerator < Rails::Generators::Base
+      include Installation
+
+      FILES = Installation::FILES
+      MARKER_START = Installation::MARKER_START
+      MARKER_END = Installation::MARKER_END
+      AGENT_TEMPLATE_PATHS = Installation.const_get(:AGENT_TEMPLATE_PATHS, false)
+      AGENT_CONTRACT_PATHS = Installation.const_get(:AGENT_CONTRACT_PATHS, false)
+      PRIOR_CLAUDE_SETTINGS = Installation.const_get(:PRIOR_CLAUDE_SETTINGS, false)
+      STRONG_MIGRATIONS_PROVENANCE = Installation.const_get(:STRONG_MIGRATIONS_PROVENANCE, false)
+      HOOK_MODE = Installation.const_get(:HOOK_MODE, false)
+      DEFAULT_AGENT_ARTIFACT_MODE = Installation.const_get(:DEFAULT_AGENT_ARTIFACT_MODE, false)
+      TEMPFILE_MODE = Installation.const_get(:TEMPFILE_MODE, false)
+      AGENT_CONTRACT_START = Installation.const_get(:AGENT_CONTRACT_START, false)
+      AGENT_CONTRACT_END = Installation.const_get(:AGENT_CONTRACT_END, false)
+      DirectoryOperations = Installation.const_get(:DirectoryOperations, false)
+
+      private_constant :AGENT_TEMPLATE_PATHS, :AGENT_CONTRACT_PATHS
+      private_constant :PRIOR_CLAUDE_SETTINGS
+      private_constant :STRONG_MIGRATIONS_PROVENANCE, :HOOK_MODE, :DEFAULT_AGENT_ARTIFACT_MODE, :TEMPFILE_MODE
+      private_constant :AGENT_CONTRACT_START, :AGENT_CONTRACT_END, :DirectoryOperations
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_initializers, type: :boolean, default: false
+      class_option :skip_coverage, type: :boolean, default: false
+      class_option :agents, type: :boolean, default: false
+
+      # Rails discovers generator tasks from methods declared on this class.
+      # Keep these forwarding methods so the shared module remains framework-neutral.
+      # rubocop:disable Lint/UselessMethodDefinition
+      def create_settings_file = super
+      def create_rules_file = super
+      def create_initializers = super
+      def inject_coverage = super
+      def create_agent_integration = super
+      def print_summary = super
+      # rubocop:enable Lint/UselessMethodDefinition
+
+      private
+
+      def create_new_file(relative_path, content)
+        create_file(relative_path, content, verbose: false)
+      end
+
+      def template_source_root
+        self.class.source_root
+      end
+
+      def template_for(name)
+        name
+      end
+
+      def test_helper_path
+        "test/test_helper.rb"
+      end
+    end
+  end
+end

data/lib/generators/quality_gate/install/templates/agents_section.md.tt

@@ -0,0 +1,15 @@
+<!-- quality_gate agent contract — start -->
+## Quality Gate agent contract
+
+Run `bundle exec quality_gate fast` after Ruby edits. Installed Claude Code hooks can run `bundle exec quality_gate verify` automatically at session end; other clients, including Codex, must run `bundle exec quality_gate verify` manually before you finish a change. Run `bundle exec quality_gate audit` before you merge security-sensitive work.
+
+Fix findings before you continue editing.
+
+- Exit 0 means the gate ran clean.
+- Exit 1 means the gate reported findings and no tool failures.
+- Exit 2 means the gate could not complete cleanly because of invalid input, configuration, or another tool failure.
+
+The default fast path keeps feedback tight with a 10-second RuboCop timeout. Verify and audit keep the broader suite work on the 120-second default timeout.
+
+If the automatic hook becomes unavailable, inspect `log/quality_gate_hooks.jsonl`, run `bundle install`, and reinstall the hook with `bin/rails generate quality_gate:install --agents`.
+<!-- quality_gate agent contract — end -->

data/lib/generators/quality_gate/install/templates/bullet.rb.tt

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bullet'
+
+Rails.application.config.after_initialize do
+  Bullet.enable = Rails.env.test? || Rails.env.development?
+  Bullet.raise = Rails.env.test?
+  Bullet.bullet_logger = Rails.env.development?
+  Bullet.rails_logger = Rails.env.development?
+end

data/lib/generators/quality_gate/install/templates/claude_settings.json.tt

@@ -0,0 +1,29 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/quality_gate_fast.rb",
+            "args": [],
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/quality_gate_verify_stop.rb",
+            "args": [],
+            "timeout": 300
+          }
+        ]
+      }
+    ]
+  }
+}

data/lib/generators/quality_gate/install/templates/hook_log_filesystem.rb.tt

@@ -0,0 +1,76 @@
+# Opens fixed hook-log paths relative to already-open directory descriptors.
+module HookLogFilesystem
+  extend self
+
+  O_DIRECTORY = File.const_defined?(:DIRECTORY) ? File::DIRECTORY : 0
+  O_NONBLOCK = File.const_defined?(:NONBLOCK) ? File::NONBLOCK : 0
+
+  def open_file(directory, name, flags, mode = 0)
+    fd = syscall(:openat, "int openat(int, const char*, int, int)", directory.fileno, name, flags, mode)
+    File.for_fd(fd).tap do |io|
+      io.close_on_exec = true if io.respond_to?(:close_on_exec=)
+    end
+  end
+
+  def open_directory(directory, name)
+    open_file(directory, name, File::RDONLY | File::NOFOLLOW | O_NONBLOCK | O_DIRECTORY)
+  end
+
+  def open_log_directory(directory)
+    open_directory(directory, "log")
+  rescue Errno::ENOENT
+    create_log_directory(directory)
+    open_directory(directory, "log")
+  end
+
+  def open_existing_log_directory(directory)
+    open_directory(directory, "log")
+  end
+
+  def open_log_file_for_read(directory)
+    flags = File::RDONLY | File::NOFOLLOW | O_NONBLOCK
+    open_file(directory, "quality_gate_hooks.jsonl", flags)
+  end
+
+  def open_log_file(directory)
+    open_existing_log_file(directory)
+  rescue Errno::ENOENT
+    begin
+      flags = log_file_flags | File::CREAT | File::EXCL
+      [open_file(directory, "quality_gate_hooks.jsonl", flags, 0o644), true]
+    rescue Errno::EEXIST
+      open_existing_log_file(directory)
+    end
+  end
+
+  def create_log_directory(directory)
+    syscall(:mkdirat, "int mkdirat(int, const char*, unsigned short)", directory.fileno, "log", 0o755)
+  rescue Errno::EEXIST
+    nil
+  end
+
+  private
+
+  def open_existing_log_file(directory)
+    [open_file(directory, "quality_gate_hooks.jsonl", log_file_flags), false]
+  end
+
+  def log_file_flags
+    File::WRONLY | File::APPEND | File::NOFOLLOW | O_NONBLOCK
+  end
+
+  def syscall(function_name, signature, *arguments)
+    importer.extern(signature) unless importer.respond_to?(function_name)
+    result = importer.public_send(function_name, *arguments)
+    return result unless result == -1
+
+    fail SystemCallError.new(function_name.to_s, Fiddle.last_error)
+  end
+
+  def importer
+    @importer ||= Module.new.tap do |mod|
+      mod.extend(Fiddle::Importer)
+      mod.dlload(Fiddle.dlopen(nil))
+    end
+  end
+end

data/lib/generators/quality_gate/install/templates/quality_gate.yml.tt

@@ -0,0 +1,42 @@
+# # Output format: "text" or "json".
+# format: text
+#
+# # Optional file paths passed to adapters; empty means no configured restriction.
+# files: []
+#
+# # Adapters run by each gate, in order.
+# adapters:
+#   fast:
+#     - rubocop
+#   verify:
+#     - reek
+#     - test_suite
+#     - undercover
+#   audit:
+#     - brakeman
+#     - bundler_audit
+#
+# # Command overrides by gate. Empty mappings use adapter defaults.
+# commands:
+#   fast: {}
+#   verify:
+#     test_suite:
+#       - bin/rails
+#       - test
+#   audit: {}
+#
+# # Command timeouts in seconds. Adapter-specific values override the default.
+# timeouts:
+#   default: 120
+#   rubocop: 10
+#   test_suite: 120
+#   undercover: 120
+#
+# # Aggregate SimpleCov budgets. Leave the entire mapping commented to disable coverage budgeting.
+# coverage:
+#
+# # Git ref or commit for Undercover; blank selects the comparison point automatically.
+# compare_point:
+#
+# # Explicit RuboCop config path; blank uses host config when present, otherwise the shipped config.
+# rubocop_config: