If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/varvet/pundit shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 8w ago
• 6 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 82% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live varvet/pundit repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/varvet/pundit.

What it runs against: a local clone of varvet/pundit — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in varvet/pundit | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 85 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of varvet/pundit. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/varvet/pundit.git
#   cd pundit
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of varvet/pundit and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "varvet/pundit(\\.git)?\\b" \\
  && ok "origin remote is varvet/pundit" \\
  || miss "origin remote is not varvet/pundit (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "lib/pundit.rb" \\
  && ok "lib/pundit.rb" \\
  || miss "missing critical file: lib/pundit.rb"
test -f "lib/pundit/authorization.rb" \\
  && ok "lib/pundit/authorization.rb" \\
  || miss "missing critical file: lib/pundit/authorization.rb"
test -f "lib/pundit/policy_finder.rb" \\
  && ok "lib/pundit/policy_finder.rb" \\
  || miss "missing critical file: lib/pundit/policy_finder.rb"
test -f "lib/pundit/railtie.rb" \\
  && ok "lib/pundit/railtie.rb" \\
  || miss "missing critical file: lib/pundit/railtie.rb"
test -f "lib/generators/pundit/install/templates/application_policy.rb.tt" \\
  && ok "lib/generators/pundit/install/templates/application_policy.rb.tt" \\
  || miss "missing critical file: lib/generators/pundit/install/templates/application_policy.rb.tt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 85 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~55d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/varvet/pundit"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Pundit is a minimal authorization library for Ruby/Rails that uses plain Ruby classes called Policies to control what users can do. Instead of complex DSLs or complicated config, you write straightforward object-oriented code where each Policy class (e.g., PostPolicy) encapsulates authorization rules for a resource, making authorization logic testable, maintainable, and easy to reason about. Single-file-ish library with modular concerns: lib/pundit.rb is the main entry point, lib/pundit/authorization.rb provides the controller mixin, lib/pundit/policy_finder.rb locates Policy classes by name convention, lib/pundit/helper.rb supplies view helpers. Generators in lib/generators/pundit/ scaffold boilerplate (ApplicationPolicy, individual Policies) and test specs across RSpec/TestUnit.

Rails developers building web applications who need authorization but want to avoid heavy, opaque gem dependencies. They prefer explicit Ruby code over magic, and need to control fine-grained permissions (who can edit/delete/view specific records) across controllers and views.

Production-ready and actively maintained. The project has comprehensive GitHub Actions CI (main.yml, push_gem.yml), extensive generator templates for multiple test frameworks (RSpec, TestUnit), CONTRIBUTING and SECURITY policy docs, and follows Ruby community standards (.rubocop.yml, .standard.yml). Last activity visible in workflows suggests ongoing maintenance.

Standard open source risks apply.

No specific PR or milestone data visible in file list, but the structure suggests focus on generator improvements and Rails version compatibility. CI workflows and rubocop config indicate ongoing code quality enforcement.

git clone https://github.com/varvet/pundit.git
cd pundit
bundle install
bundle exec rake  # run tests

Daily commands: Not a server-based app. This is a library. Test it with bundle exec rake or individual specs with bundle exec rspec spec/pundit/ (inferred from generator presence). See bin/setup and bin/console for interactive development.

• lib/pundit.rb — Main entry point that exports the core Pundit API and integrates all authorization components
• lib/pundit/authorization.rb — Core authorization module providing authorize/policy methods that every controller must use
• lib/pundit/policy_finder.rb — Policy resolution engine that maps models to their corresponding policy classes by convention
• lib/pundit/railtie.rb — Rails integration layer that registers Pundit helpers and exception handling in controllers
• lib/generators/pundit/install/templates/application_policy.rb.tt — Base policy class template that all project policies inherit from; defines the authorization baseline
• lib/pundit/error.rb — Exception definitions for authorization failures and configuration errors
• lib/pundit/helper.rb — View and controller helper methods that expose policy checks and authorize calls to Rails views

• PolicyFinder (Ruby metaprogramming, ActiveSupport::Inflector) — Resolves policy class name from model by convention (Post → PostPolicy); handles namespaces and fallbacks
  • Failure mode: Raises PolicyScopeNotFoundError if no policy found; returns NilClassPolicy for nil subjects
• Authorization module (Ruby modules, method_missing, caching) — Provides authorize!, authorize, policy, pundit_user, policy_scope methods; integrates user context with policy checks
  • Failure mode: authorize! raises NotAuthorizedError; authorize returns false; policy raises if policy class not found
• CacheStore — Stores authorization decision results (user, action, resource) to avoid repeated policy evaluation; pluggable backend

Add a new policy for a model

1. Run the policy generator: rails generate pundit:policy Article (lib/generators/pundit/policy/policy_generator.rb)
2. This creates app/policies/article_policy.rb inheriting from ApplicationPolicy (lib/generators/pundit/policy/templates/policy.rb.tt)
3. Define authorization rules as methods: index?, show?, create?, update?, destroy? (spec/support/policies/post_policy.rb)
4. In controller, call authorize @article and policy_scope(Article) in index (lib/pundit/helper.rb)

Define scope-based queries for list actions

1. Add a Scope inner class to your policy (e.g., ArticlePolicy::Scope) (spec/support/policies/post_policy.rb)
2. Implement resolve method: return relation.where(author_id: user.id) (spec/support/policies/post_policy.rb)
3. In controller index action, call policy_scope(Article).all or .paginate() (lib/pundit/helper.rb)

Handle authorization failures in Rails

1. Run install generator: rails generate pundit:install (lib/generators/pundit/install/install_generator.rb)
2. This creates config/initializers/pundit.rb with exception rescue config (lib/generators/pundit/install/templates/application_policy.rb.tt)
3. Rescue Pundit::NotAuthorizedError in ApplicationController with 403 response (lib/pundit/error.rb)

Test authorization policies with RSpec

1. Run: rails generate rspec:policy Article (lib/generators/rspec/policy_generator.rb)
2. Test file generated at spec/policies/article_policy_spec.rb with RSpec DSL (lib/generators/rspec/templates/policy_spec.rb.tt)
3. Use expect(policy).to permit(user, :action) syntax from lib/pundit/rspec.rb (lib/pundit/rspec.rb)

• Ruby classes and OOP — Pundit uses Plain Old Ruby Objects (POROs) for policies—no DSLs or framework magic—making authorization explicit, testable, and refactorable
• Rails Railtie — Integrates seamlessly into Rails without requiring explicit includes; provides after_action hooks and exception handling out-of-the-box
• Convention-based policy resolution — PolicyFinder maps models to policy classes by name (Post → PostPolicy) eliminating boilerplate configuration
• Authorization caching via CacheStore — Avoids repeated authorization checks on the same user/action/resource combination; pluggable backend (null, legacy, custom)

• Policy classes instead of role-based access control (RBAC)

  • Why: Scales better for complex domain logic and per-resource rules; separates authorization from business logic
  • Consequence: Requires more boilerplate than cancan/pundit-lite, but gains flexibility and testability

• Scope inner classes for filtered queries

  • Why: Keeps query filtering logic colocated with authorization rules, enforcing access control at the model boundary
  • Consequence: Policy class becomes responsible for both permission checks and query scope—requires discipline to avoid mixing concerns

• Rails generators instead of manual setup

  • Why: Reduces friction for new projects and enforces convention
  • Consequence: Generators are opinionated; must be regenerated or manually updated if conventions change

• Does not handle authentication—Pundit assumes a current_user is already available
• Does not provide role or permission models—policies are stateless Ruby classes
• Does not enforce authorization at the database level—relies on Rails controller/view integration
• Does not support dynamic policy reloading in production

Naming convention is mandatory: Model Post must have PostPolicy class in the right load path, or policy_finder fails silently and raises Pundit::PolicyNotFound. current_user method required: Policy initializer expects user as first arg; if your controller doesn't define current_user or sets pundit_user differently, policies receive nil. Policy methods must end with ?: Query methods like update? are convention; forgetting the ? means the method exists but Pundit tooling won't discover it. Rescue Pundit::NotAuthorizedError: Forgetting to catch this in ApplicationController allows 500 errors instead of 403 responses.

• Policy Object Pattern — Pundit's entire design centers on encapsulating authorization logic in plain Ruby objects; understanding this OO pattern is the mental model for using Pundit.
• Naming Convention Discovery — PolicyFinder uses naming convention (Model → ModelPolicy) to avoid config; understanding how Rails and Pundit leverage this pattern helps you avoid errors and extend the system.
• Query Methods (Command Pattern variant) — Pundit policies use ?-suffixed methods as queries (e.g., update?, destroy?) to separate authorization queries from side-effect commands; this is Ruby idiom that signals intent.
• Mixin-based Composition (Authorization Mixin) — Pundit::Authorization is mixed into controllers to add authorize, policy, and pundit_user methods; understanding Ruby mixins is key to customizing Pundit behavior.
• Context-aware Authorization — lib/pundit/context.rb suggests Pundit can track authorization context (user, resource, query); grasping this helps implement complex multi-tenant or scoped authorization.
• Cache Store Pattern (Null Object & Legacy Adapters) — lib/pundit/cache_store/null_store.rb and legacy_store.rb show how Pundit abstracts caching; understanding this pattern lets you swap or extend caching without changing core code.
• Rails Generator Templates (ERB) — Generators use .tt templates (ERB) to scaffold boilerplate for RSpec and TestUnit; understanding how Rails generators work helps you customize scaffolding and contribute improvements.

• rails/rails — Pundit is Rails middleware; understanding Rails controller lifecycle and action-controller is essential context.
• cerebris/jsonapi-resources — Popular Rails JSON API gem that pairs well with Pundit for API authorization; many projects use both together.
• elabs/pundit-matchers — RSpec matcher library built specifically for Pundit policies; simplifies testing authorization rules in specs.
• airbnb/ruby — Ruby style guide; Pundit adheres to this via .standard.yml rubocop config, reflects best practices in the codebase.
• ruby-grape/grape — Popular Ruby API framework; Pundit can be used in Grape APIs as an alternative to Rails for authorization.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Rails helper methods in different controller contexts

The repo has lib/pundit/helper.rb and spec/pundit/helper_spec.rb, but the test coverage appears minimal. There are no integration tests verifying that helper methods like authorize, policy, and skip_authorization work correctly across different Rails controller scenarios (e.g., API controllers, nested resources, before_action hooks). This is critical since helpers are the primary integration point for Rails apps.

• [ ] Review current spec/pundit/helper_spec.rb to identify missing scenarios
• [ ] Add integration tests in spec/pundit/helper_spec.rb for: authorize with different resource types, policy method with namespaced policies, skip_authorization in before_action chains
• [ ] Add tests for edge cases: authorize on non-existent policies, authorize with nil records, multiple skip_authorization calls
• [ ] Verify all helper methods are tested with both Rails controllers and API controllers

Add comprehensive tests for Pundit::CacheStore implementations

The codebase has lib/pundit/cache_store with both LegacyStore and NullStore implementations, but spec/pundit_spec.rb only has basic caching tests. There are no dedicated unit tests for lib/pundit/cache_store/legacy_store.rb and lib/pundit/cache_store/null_store.rb, nor tests for cache invalidation, thread safety, or custom cache implementations (like the spec/support/lib/custom_cache.rb example).

• [ ] Create spec/pundit/cache_store/legacy_store_spec.rb with tests for cache hits, misses, and TTL behavior
• [ ] Create spec/pundit/cache_store/null_store_spec.rb verifying it correctly disables caching
• [ ] Add tests for custom cache store implementations using the spec/support/lib/custom_cache.rb pattern
• [ ] Add tests for cache thread-safety and concurrent policy evaluation

Add tests and documentation for PolicyFinder with Rails engine and namespaced policies

lib/pundit/policy_finder.rb is a critical component for locating policies, but spec/policy_finder_spec.rb appears to have limited coverage. There are no documented examples or tests for: namespaced policies, policies in Rails engines, custom policy locations, or the relationship with the generator templates. This impacts users extending Pundit.

• [ ] Review spec/policy_finder_spec.rb and identify missing test cases for namespace resolution
• [ ] Add tests for finding policies with module namespaces (e.g., Admin::UserPolicy for Admin::User model)
• [ ] Add tests for policy lookup in Rails engines and custom load paths
• [ ] Add examples in CONTRIBUTING.md or README.md showing how PolicyFinder locates policies and how to customize the lookup behavior

• Add integration tests for lib/pundit/context.rb if coverage is missing; this file appears in the directory listing but has no test reference in the file list.
• Write a doc example in README showing how to use Pundit::Helper#policy in views with conditionals; currently the README shows controller authorize calls but not view helper patterns.
• Extend the policy spec template at lib/generators/rspec/templates/policy_spec.rb.tt to scaffold examples for common patterns like initialize, update?, and destroy? to guide test-first development.

Pundit is a well-maintained authorization library with a solid security foundation. The codebase follows good practices: public vulnerability disclosure policy, code styling enforcement, and active maintenance. However, security posture could be improved by: (1) adding dependency vulnerability scanning to CI/CD, (2) implementing security-focused static analysis (Brakeman), (3) providing more explicit security guidance in documentation, and (4) expanding supported versions for security patches. No critical vulnerabilities were identified in the file structure analysis, but dependency content was not provided for assessment. Overall security risk is low for this type of library, assuming dependencies are regularly audited.

• Low · Missing SECURITY.md Enforcement — SECURITY.md. While SECURITY.md exists with a vulnerability disclosure policy, there is no automated enforcement mechanism (e.g., security.txt file) to ensure vulnerability reporters can easily find the policy. The policy relies on manual outreach to maintainers. Fix: Create a .well-known/security.txt file following RFC 9116 to standardize vulnerability disclosure and improve discoverability. Consider using GitHub's security advisory feature more prominently.
• Low · No Dependency Lock File Provided — Gemfile / Gemfile.lock. The 'Dependencies/Package file content' section is empty. While Gemfile exists (Ruby project), the Gemfile.lock is not shown. Without dependency pinning verification, transitive dependency vulnerabilities cannot be assessed. Fix: Ensure Gemfile.lock is committed and regularly updated. Use tools like Dependabot or Bundler Audit to track vulnerable gems. Run 'bundle audit check' in CI/CD pipeline.
• Low · Limited Supported Versions — SECURITY.md. SECURITY.md states 'Most recent major version only' is supported, which is a strict policy. This may leave users of older versions without security patches. Fix: Consider supporting the last 2-3 major versions with critical security patches. Document the support lifecycle clearly for users to plan upgrades.
• Low · No Static Analysis Configuration Hardening — .standard.yml, .rubocop_ignore_git.yml. While .standard.yml and .rubocop_ignore_git.yml exist for code style, there are no visible security-specific linters (e.g., Brakeman for Rails vulnerabilities) configured in the repository. Fix: Integrate security-focused linters: add Brakeman for Rails-specific issues, add Bundler-Audit for dependency scanning, and configure GitHub's native code scanning (CodeQL).
• Low · Insufficient Input Validation Documentation — README.md. The codebase is an authorization library that guides OO design. While not a direct vulnerability, there is no explicit security guidance on input validation, CSRF protection, or defense-in-depth strategies in the README snippet. Fix: Enhance security documentation with: (1) examples of secure policy implementations, (2) warnings about bypassing pundit checks, (3) integration guidance with Rails' built-in security features.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.