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/bensheldon/good_job 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 the board

• Last commit 3w ago
• 24+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 62% 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 bensheldon/good_job repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bensheldon/good_job.

What it runs against: a local clone of bensheldon/good_job — 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 bensheldon/good_job | 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 ≤ 48 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bensheldon/good_job. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bensheldon/good_job.git
#   cd good_job
#
# 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 bensheldon/good_job and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "bensheldon/good_job(\\.git)?\\b" \\
  && ok "origin remote is bensheldon/good_job" \\
  || miss "origin remote is not bensheldon/good_job (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 "app/models/good_job/execution.rb" \\
  && ok "app/models/good_job/execution.rb" \\
  || miss "missing critical file: app/models/good_job/execution.rb"
test -f "app/models/good_job/job.rb" \\
  && ok "app/models/good_job/job.rb" \\
  || miss "missing critical file: app/models/good_job/job.rb"
test -f "lib/good_job/engine.rb" \\
  && ok "lib/good_job/engine.rb" \\
  || miss "missing critical file: lib/good_job/engine.rb"
test -f "lib/good_job/adapter.rb" \\
  && ok "lib/good_job/adapter.rb" \\
  || miss "missing critical file: lib/good_job/adapter.rb"
test -f "lib/good_job/performer.rb" \\
  && ok "lib/good_job/performer.rb" \\
  || miss "missing critical file: lib/good_job/performer.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 48 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~18d)"
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/bensheldon/good_job"
  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).

GoodJob is a multithreaded, PostgreSQL-backed Active Job adapter for Ruby on Rails that executes enqueued jobs using database-native advisory locks and LISTEN/NOTIFY for low-latency polling. It replaces Delayed::Job or Sidekiq for teams preferring to eliminate Redis and keep job state in their existing Postgres database, supporting async/await, queues, priorities, retries, timeouts, cron scheduling, and batches with zero external dependencies. Rails engine structure under app/ with isolated layers: app/controllers/ handles dashboard HTTP endpoints, app/models/ (not listed but inferred) manages GoodJob::Job, app/views/ (implied) for Web UI in HTML/ERB, lib/good_job/ for core job execution and scheduling logic, config/ for initializer configuration. Database state lives in a dedicated good_jobs table with Postgres advisory locks and LISTEN/NOTIFY pubsub.

Rails developers and DevOps teams running production applications who want a simple, Postgres-only job queue without managing Redis or separate background job infrastructure; particularly solo founders and full-stack teams optimizing operational complexity over massive job volumes (1M+/day scale still supported).

Production-ready and actively maintained. The repo shows a mature Ruby gem with 762K lines of Ruby code, comprehensive test coverage (visible .rspec config and CI via .github/workflows/test.yml), regular GitHub Actions CI/CodeQL security scanning, and structured releases tracked in CHANGELOG.md. This is a battle-tested gem used in production Rails applications.

Low risk for core functionality; single maintainer (bensheldon) creates potential maintainability concern, though the gem has established community and regular updates. Rails version lock constraints and Postgres version requirements are non-negotiable (check .ruby-version and Gemfile). No significant breaking change history visible, but monitor CHANGELOG.md for any Active Job API changes in new Rails versions.

Active development visible via test.yml CI runs and codeql-analysis.yml security scanning. Recent work appears focused on dashboard features (multiple chart types in app/charts/), performance metrics (MetricsController), batch job support (batches_controller.rb), and cron scheduling (cron_entries_controller.rb). Dependabot.yml indicates automated dependency updates.

Clone the repo, run bundle install (see Gemfile), set up a Postgres database (see .devcontainer/docker-compose.yml for local dev setup), run rails db:create db:migrate, then rails s to start the Rails app with GoodJob embedded, or bundle exec good_job to run a standalone worker process.

Daily commands: Development: bundle install && rails db:setup && rails s (starts Rails app with GoodJob in same process). Separate worker: bundle exec good_job start (standalone process listening for jobs). Tests: bundle exec rspec (RSpec configured in .rspec). Dashboard: Visit http://localhost:3000/good_job after Rails starts.

• app/models/good_job/execution.rb — Core job execution model that represents individual job runs; essential for understanding how GoodJob processes enqueued tasks.
• app/models/good_job/job.rb — Primary Job model wrapping executions; critical for understanding the job lifecycle and queries.
• lib/good_job/engine.rb — Rails engine initialization and configuration entry point; defines how GoodJob integrates with Rails applications.
• lib/good_job/adapter.rb — ActiveJob adapter implementation; essential for understanding how jobs are enqueued and processed.
• lib/good_job/performer.rb — Executes individual jobs; core logic for job execution, error handling, and retry mechanisms.
• app/models/concerns/good_job/advisory_lockable.rb — PostgreSQL advisory lock abstraction for job locking; critical for understanding concurrency control.
• lib/good_job/scheduler.rb — Manages job scheduling and polling; essential for understanding multithreaded job processing architecture.

• Adapter (Ruby, ActiveJob, ActiveRecord) — Enqueues ActiveJob jobs into GoodJob; implements ActiveJob::QueueAdapters interface
  • Failure mode: Enqueue failures (DB down) bubble to Rails; job lost if not retried by caller
• Scheduler (Ruby Threads, PostgreSQL advisory locks, Concurrent::ThreadPoolExecutor) — Polls database for ready jobs, acquires advisory locks, spawns Performer threads
  • Failure mode: Polling hangs → jobs not processed; lock contention → jobs delayed; thread pool full → backlog
• Performer (Ruby, ActiveRecord, error hooks) — Executes a single job, handles exceptions, records results, manages retries
  • Failure mode: Uncaught exception → job marked failed; retry exhausted → discarded; timeout → hung thread
• Job/Execution Models (ActiveRecord, PostgreSQL) — Persistent state of jobs and execution attempts; queries, scopes, lifecycle hooks
  • Failure mode: Schema mismatch → ORM errors; missing indexes → slow queries; data corruption → incons

Add a New Dashboard Page/Widget

1. Create a new controller in app/controllers/good_job/ extending ApplicationController (app/controllers/good_job/application_controller.rb)
2. Create a filter class in app/filters/good_job/ if filtering is needed (app/filters/good_job/base_filter.rb)
3. Create views in app/views/good_job/<controller_name>/ using Bootstrap components (app/views/good_job/)
4. If charting, create chart class in app/charts/good_job/ extending BaseChart (app/charts/good_job/base_chart.rb)
5. Add Stimulus JS controller in app/frontend/good_job/modules/ for interactivity (app/frontend/good_job/modules/)

Add Custom Job Execution Logic or Callbacks

1. Extend Performer or override perform_job in lib/good_job/performer.rb (lib/good_job/performer.rb)
2. Add error event handling via Execution model and ErrorEvents concern (app/models/concerns/good_job/error_events.rb)
3. Register callbacks in lib/good_job/engine.rb or via GoodJob.on_* hooks (lib/good_job/engine.rb)

Add a New Job Status or Filtering Option

1. Modify Execution or Job model to add new status constant and database scope (app/models/good_job/execution.rb)
2. Update JobsFilter to handle new filter parameter (app/filters/good_job/jobs_filter.rb)
3. Update JobsController index query and view to display new status (app/controllers/good_job/jobs_controller.rb)

• PostgreSQL — Provides advisory locks for safe distributed job claiming, efficient querying, and single external dependency vs. Redis
• Multithreading (Scheduler + Performer threads) — Enables concurrent job processing and polling without separate worker processes; scales within a single Rails instance
• ActiveRecord & Rails Engine — Native Rails integration via ActiveJob adapter; leverages existing app infrastructure and migrations
• Stimulus.js + Bootstrap — Minimal JavaScript framework for lightweight, progressive dashboard UI without heavy build requirements

• Single PostgreSQL database as job queue vs. external queue (Redis, RabbitMQ)

  • Why: Reduces operational complexity and external dependencies; simplifies deployment for Rails apps
  • Consequence: Database becomes critical single point of failure; connection pool contention at high throughput; less suitable for microservices

• Multithreaded polling in-process vs. separate worker processes/services

  • Why: Simpler deployment; no worker management overhead; suits small-to-medium workloads
  • Consequence: Scaling beyond one app instance requires coordination; memory contention in a single process; harder to isolate job failures

• Discrete Execution model vs. monolithic Job

  • Why: Allows rich retry/replay semantics and detailed execution history per attempt
  • Consequence: Additional database complexity; more rows to manage; slightly higher query complexity for job status

• Built-in admin dashboard vs. external UI

  • Why: Self-contained; no external service dependency; instant visibility into job state
  • Consequence: Adds code maintenance burden; dashboard features tied to core release cycle

• Multi-process distributed worker scaling (use separate runner processes or dedicated job service for that)
• Real-time pub/sub or websocket job notifications (polling-based dashboard updates only)
• Cross-database or multi-shard job coordination
• Job dependency graphs or complex workflow orchestration (sequential or batched only)
• Non-ActiveJob job enqueue APIs (ActiveJob interface only)

Postgres required: No support for SQLite or other databases; advisory locks are Postgres-specific. Rails version coupling: GoodJob version must align with Rails version (check Gemfile for rails ~> X.Y). Database migrations: Must run rails db:migrate after gem installation; uses standard Rails migration directory. Concurrent::Ruby: Uses thread pools; ensure your job code is thread-safe (no global state, ActiveRecord connection pooling). LISTEN/NOTIFY: Requires a Postgres connection that stays open; if your Postgres drops the connection, polling falls back to interval-based queries (slower). Environment variable: Check .env-example for GOOD_JOB_* config vars (queue names, max threads, polling interval, etc.). Cleanup: The good_jobs table grows indefinitely; use GoodJob's built-in job retention/cleanup feature or run manual vacuum.

• PostgreSQL Advisory Locks — GoodJob uses session-level advisory locks to guarantee exactly-once job execution across multiple worker processes without requiring distributed consensus; understanding lock acquisition and release is critical for debugging 'job executed twice' bugs
• LISTEN/NOTIFY (PostgreSQL Pub/Sub) — GoodJob uses LISTEN/NOTIFY to wake sleeping worker threads the moment a job is enqueued, eliminating constant polling and reducing job latency; misconfigured NOTIFY channels cause workers to revert to slow polling
• Active Job Adapter Pattern — GoodJob is an Active Job queue adapter implementing Rails' pluggable backend pattern; understanding how ActiveJob::QueueAdapter interface maps to GoodJob's Job model and Performer is essential for extending or debugging job behavior
• Thread Pool Executor (Concurrent::Ruby) — GoodJob spawns a thread pool (configurable max threads) to process jobs concurrently within a single OS process; knowledge of thread safety, connection pooling, and executor lifecycle is mandatory to avoid race conditions
• Job Serialization & Deserialization — GoodJob stores job payloads as JSON in the good_jobs table and reconstructs the original ActiveJob object at execution time; serialization bugs cause 'cannot find job class' or 'parameter type mismatch' errors in production
• Batch Processing & Job Dependencies — GoodJob supports job batches (enqueue multiple jobs as a unit) with completion callbacks; understanding batch state management and the good_job_batches table schema enables features like 'run after N jobs complete'
• Cron Scheduling (Cron Entries) — GoodJob includes built-in cron scheduling (good_job/cron_entries_controller.rb) to repeat jobs on intervals without external tools like rufus-scheduler; understanding cron expression parsing and timezone handling prevents missed or duplicate scheduled executions

• collectiveidea/delayed_job — Direct predecessor; GoodJob is explicitly inspired by Delayed::Job's Active Job adapter design but uses Postgres locks instead of timestamps
• que-rb/que — Close alternative Postgres-backed job queue; GoodJob borrowed Que's LISTEN/NOTIFY pattern for low-latency polling
• sidekiq/sidekiq — Market leader in Rails job queues using Redis; GoodJob explicitly targets teams who want to avoid Redis dependency
• rails/rails — Core dependency; GoodJob implements ActiveJob::QueueAdapter interface; changes to Active Job API directly affect GoodJob
• ruby-concurrency/concurrent-ruby — Core dependency for thread pools and multithreading safety; GoodJob's execution model depends entirely on Concurrent::Ruby's thread executor

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 comprehensive filter tests for GoodJob::BatchesFilter and GoodJob::JobsFilter

The app/filters directory contains BaseFilter, BatchesFilter, and JobsFilter classes, but there's no visible test coverage in the file structure. These filters are critical for the web UI's search/filtering functionality. Adding unit tests would ensure filtering logic (queue selection, status filtering, date ranges) works correctly across database queries and prevents regressions.

• [ ] Create spec/filters/good_job/batches_filter_spec.rb with tests for batch filtering (status, created_at ranges, batch_id searches)
• [ ] Create spec/filters/good_job/jobs_filter_spec.rb with tests for job filtering (queue selection, job status, scheduled vs finished, error handling)
• [ ] Create spec/filters/good_job/base_filter_spec.rb with tests for base filter behavior and query chaining
• [ ] Add edge case tests (empty filters, invalid date ranges, SQL injection attempts)

Add missing frontend controller tests for app/frontend/good_job/modules

The frontend modules (async_values_controller.js, live_poll_controller.js, chart_controller.js, theme_controller.js) handle critical UI behaviors like live polling, theme switching, and form interactions. Without visible tests, refactoring risks breaking the dashboard. Adding Stimulus controller tests would ensure reliability and make future maintenance safer.

• [ ] Set up JavaScript testing framework (Vitest or Jest) in package.json if not already present
• [ ] Create tests/javascript/modules/live_poll_controller.test.js testing polling intervals, request handling, and connection failures
• [ ] Create tests/javascript/modules/theme_controller.test.js testing theme persistence and DOM updates
• [ ] Create tests/javascript/modules/async_values_controller.test.js testing async data loading and error states

Add test coverage for app/charts directory chart generation logic

The charts directory (BaseChart, PerformanceIndexChart, ScheduledByQueueChart) generates dashboard visualizations from job data. Without visible tests, chart data transformations, aggregations, and edge cases (empty data, outliers) could silently fail. Adding unit tests ensures accurate metrics reporting.

• [ ] Create spec/charts/good_job/base_chart_spec.rb testing chart initialization, data structure expectations, and helper methods
• [ ] Create spec/charts/good_job/performance_index_chart_spec.rb testing metric calculations (success rates, avg execution times) with fixture data
• [ ] Create spec/charts/good_job/scheduled_by_queue_chart_spec.rb testing queue aggregation and edge cases (zero jobs, many queues)
• [ ] Add fixtures with realistic job data spanning multiple days/queues for chart calculations

• Add integration tests for the performance_index_chart.rb under app/charts/good_job/; currently no test coverage visible in file list for charting logic. Start by creating spec/charts/good_job/performance_index_chart_spec.rb with data fixtures.
• Expand app/filters/good_job/base_filter.rb documentation and add a JobsFilter subclass that filters jobs by creation date range; the filter framework exists but is sparsely populated (only batches_filter.rb listed).
• Add Prometheus metrics export endpoint to app/controllers/good_job/metrics_controller.rb so monitoring tools can scrape job queue depth, processing time, and error rates; skeleton controller exists but likely has minimal implementation.

• Medium · Potential SQL Injection in Active Record Queries — app/filters/good_job/base_filter.rb, app/filters/good_job/jobs_filter.rb, app/filters/good_job/batches_filter.rb. The codebase includes filterable concerns and filters (app/filters/good_job/) that process user input to filter database records. Without proper parameterization, these could be vulnerable to SQL injection if raw SQL or unsafe query construction is used. Fix: Ensure all database queries use parameterized queries with proper Active Record methods (where, pluck, etc.). Avoid string interpolation or concatenation with user input. Use Arel for complex query building.
• Medium · Potential XSS Vulnerability in Views — app/views/ (not fully visible but critical for any Rails view rendering job data). The frontend includes user-facing views that display job data, batch information, and logs. If job parameters, error messages, or exception details are not properly escaped, XSS attacks could occur. Fix: Ensure all dynamic content in ERB templates is HTML-escaped by default. Use <%= %> for escaped output, never use <%== %> for user-controlled content. Validate and sanitize all user inputs server-side.
• Medium · Missing CSRF Protection Configuration — app/controllers/good_job/application_controller.rb, app/controllers/good_job/jobs_controller.rb, app/controllers/good_job/pauses_controller.rb. The application includes multiple controllers (app/controllers/good_job/) that perform state-changing operations (pause, resume, delete jobs). If CSRF tokens are not properly configured, cross-site request forgery attacks are possible. Fix: Verify CSRF protection is enabled in ApplicationController with protect_from_forgery. Ensure all state-changing requests (POST, PUT, DELETE) require valid CSRF tokens in form submissions.
• Medium · Insufficient Access Control on Admin Dashboard — app/controllers/good_job/application_controller.rb (base controller). The GoodJob UI provides access to job execution, batches, and process information. Without proper authentication and authorization checks, unauthorized users could view sensitive job data or manipulate job execution. Fix: Implement robust authentication and authorization checks. Verify that GoodJob routes are properly mounted with middleware that authenticates and authorizes users. Consider using a before_action filter to check user permissions.
• Low · Potential Information Disclosure via Error Messages — app/models/concerns/good_job/error_events.rb. The application handles job execution errors and displays them in the UI. Detailed error messages could leak sensitive information about the application's internal structure, database, or file paths. Fix: Sanitize error messages before displaying them in the UI. Log full errors server-side but show users generic error messages. Use proper exception handling with Rails logger.
• Low · Potential Timing Attack in Advisory Locking — app/models/concerns/good_job/advisory_lockable.rb. Advisory locks are used for concurrency control (app/models/concerns/good_job/advisory_lockable.rb). If timing differences in lock acquisition/release are observable, they could leak information about system state. Fix: Ensure advisory lock operations complete in constant time where possible. Avoid exposing timing information in logs or metrics. Use appropriate lock timeouts.
• Low · Missing Security Headers Configuration — app/controllers/good_job/application_controller.rb. The web UI does not appear to have explicit security headers configuration visible (Content-Security-Policy, X-Frame-Options, etc.). Fix: Configure security headers in the Rails application. Set CSP to restrict script sources, X-Frame-Options to prevent clickjacking, X-Content-Type-Options to prevent MIME sniffing, and other protective headers.
• Low · Client-Side JavaScript Security — app/frontend/good_job/modules/async_values_controller.js, form_controller.js. Frontend JavaScript modules (app/frontend/good_job/modules/) interact with the backend. If not properly validated, client-side manipulation could bypass server-side checks. Fix: Never trust client-side validation. All security decisions must be enforced server-side. Validate all parameters, permissions,

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.