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/mbleigh/acts-as-taggable-on 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 2mo ago
• 40+ active contributors
• Distributed ownership (top contributor 41% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{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 mbleigh/acts-as-taggable-on repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mbleigh/acts-as-taggable-on.

What it runs against: a local clone of mbleigh/acts-as-taggable-on — 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 mbleigh/acts-as-taggable-on | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 102 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mbleigh/acts-as-taggable-on(\\.git)?\\b" \\
  && ok "origin remote is mbleigh/acts-as-taggable-on" \\
  || miss "origin remote is not mbleigh/acts-as-taggable-on (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/acts-as-taggable-on.rb" \\
  && ok "lib/acts-as-taggable-on.rb" \\
  || miss "missing critical file: lib/acts-as-taggable-on.rb"
test -f "lib/acts-as-taggable-on/taggable/core.rb" \\
  && ok "lib/acts-as-taggable-on/taggable/core.rb" \\
  || miss "missing critical file: lib/acts-as-taggable-on/taggable/core.rb"
test -f "lib/acts-as-taggable-on/tag.rb" \\
  && ok "lib/acts-as-taggable-on/tag.rb" \\
  || miss "missing critical file: lib/acts-as-taggable-on/tag.rb"
test -f "lib/acts-as-taggable-on/tagging.rb" \\
  && ok "lib/acts-as-taggable-on/tagging.rb" \\
  || miss "missing critical file: lib/acts-as-taggable-on/tagging.rb"
test -f "lib/acts-as-taggable-on/taggable/tag_list.rb" \\
  && ok "lib/acts-as-taggable-on/taggable/tag_list.rb" \\
  || miss "missing critical file: lib/acts-as-taggable-on/taggable/tag_list.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 102 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~72d)"
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/mbleigh/acts-as-taggable-on"
  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).

ActsAsTaggableOn is a Rails plugin that adds flexible, context-aware tagging to any ActiveRecord model. Unlike simpler tagging gems, it supports multiple independent tag 'contexts' (e.g., a User can have 'skills', 'interests', and 'sports' tags simultaneously), tag ownership, custom tag parsing, and complex queries (all tags, any tags, exclude tags). It's built on top of a join-table pattern via the Tagging model linking Tag records to any taggable model. Modular plugin architecture under lib/acts-as-taggable-on/: lib/taggable/ contains core functionality (core.rb), features (caching.rb, ownership.rb, related.rb), and query builders (tagged_with_query/). The tagging persistence layer uses three main models: Tag (lib/tag.rb), Tagging (lib/tagging.rb, the join model), and includes parser/utility modules. Database schema is defined in db/migrate/1_setup_acts_as_taggable_on.rb; configuration is engine-based (lib/engine.rb).

Rails developers building applications with complex tagging requirements—social networks needing multi-faceted user profiles, content platforms with multiple taxonomy systems, or any app where a single 'tags' field is insufficient. Primary users are backend engineers and Rails maintainers contributing to open-source projects.

This is a mature, production-ready gem actively maintained and widely used in the Rails ecosystem. It has a complete test suite (.rspec present), GitHub Actions CI/CD workflow (spec.yml), support for Rails 7.1–8.1 (gemfiles/ directory), and an established changelog. However, with a single maintainer (mbleigh) and infrequent recent activity visible, it shows signs of stable maintenance rather than rapid feature development.

Low-to-moderate risk for new code; this is battle-tested in production Rails apps. Key risks: single-maintainer project (mbleigh), potential Rails version compatibility gaps if not proactively updated, and the join-table approach can create N+1 queries if not eager-loaded carefully. No evident dependency bloat—core gem appears lightweight—but schema migrations are required at install time, making upgrades slightly less trivial than gems without database changes.

No specific recent commits or active PRs visible in provided data. The project appears in maintenance mode, with gemfiles/ showing support for newer Rails versions (7.1–8.1) indicating some ongoing compatibility work. The presence of Appraisals and docker-compose.yml suggests CI/compatibility testing infrastructure is active but not highlighted by recent commit activity.

Clone the repo, install dependencies, and run tests: git clone https://github.com/mbleigh/acts-as-taggable-on.git && cd acts-as-taggable-on && bundle install && bundle exec rspec. For use in a Rails app, add gem 'acts-as-taggable-on' to Gemfile, run bundle, then rake acts_as_taggable_on_engine:install:migrations && rails db:migrate to install schema.

Daily commands: Clone and bundle, then run the test suite: bundle exec rspec. For integration into a Rails app: add gem to Gemfile, bundle, run rake acts_as_taggable_on_engine:install:migrations, then rails db:migrate. No dev server needed—it's a gem, not an app. Use docker-compose.yml for isolated development: docker-compose up (if services are defined).

• lib/acts-as-taggable-on.rb — Main entry point that loads the entire gem and initializes the Rails engine for acts-as-taggable-on functionality.
• lib/acts-as-taggable-on/taggable/core.rb — Core module that defines the acts_as_taggable macro and handles the fundamental tagging behavior for models.
• lib/acts-as-taggable-on/tag.rb — Tag model definition that represents individual tags and their associations with tagged objects.
• lib/acts-as-taggable-on/tagging.rb — Tagging model that acts as the join table between tags and taggable objects, supporting ownership and context.
• lib/acts-as-taggable-on/taggable/tag_list.rb — TagList class that parses and manages tag string representations, handling serialization and deserialization.
• db/migrate/1_setup_acts_as_taggable_on.rb — Database schema migration that creates the essential tags and taggings tables required by the gem.
• lib/acts-as-taggable-on/engine.rb — Rails engine class that registers the gem within the Rails application and loads migrations.

Add a custom tag parser for a new format

1. Create a new parser class inheriting from GenericParser in lib/acts-as-taggable-on/ (lib/acts-as-taggable-on/generic_parser.rb)
2. Implement the parse(tag_list) method to return an array of tag strings (lib/acts-as-taggable-on/default_parser.rb)
3. Register the parser in your Rails initializer by setting ActsAsTaggableOn.default_parser = YourParserClass (lib/acts-as-taggable-on/engine.rb)
4. Add tests for your parser class in spec/acts_as_taggable_on/ (spec/acts_as_taggable_on/default_parser_spec.rb)

Add owned tags to a taggable model

1. Ensure your model includes acts_as_taggable macro in the model definition (lib/acts-as-taggable-on/taggable/core.rb)
2. Define a tagger (user) model with acts_as_tagger (lib/acts-as-taggable-on/taggable/core.rb)
3. Add tags using tag_list_on(context)= with ownership: @object.tag_list_on(:skills) = @user.tag(@object, with: 'ruby,rails', on: :skills) (lib/acts-as-taggable-on/taggable/ownership.rb)
4. Query owned tags using @object.owned_taggings_on(:skills, @user) (lib/acts-as-taggable-on/taggable/ownership.rb)

Implement tag caching for a model

1. Add tag_list_cache_on(context_name) columns to your model's database table (lib/acts-as-taggable-on/taggable/caching.rb)
2. Include caching behavior by adding acts_as_taggable with cache_type option in your model (lib/acts-as-taggable-on/taggable/core.rb)
3. The cache is automatically updated when tags are assigned: @object.tag_list = 'new,tags' (lib/acts-as-taggable-on/taggable/caching.rb)
4. Verify cache invalidation in tests using spec/acts_as_taggable_on/caching_spec.rb as reference (spec/acts_as_taggable_on/caching_spec.rb)

Query objects by tags using find_tagged_with

1. Use tagged_with(:tags) to find objects tagged with any of the specified tags (lib/acts-as-taggable-on/taggable/tagged_with_query/any_tags_query.rb)
2. Use tagged_with(:tags, match: :all) to find objects tagged with ALL specified tags (lib/acts-as-taggable-on/taggable/tagged_with_query/all_tags_query.rb)
3. Use tagged_with(:tags, exclude: true) to exclude objects with specified tags (lib/acts-as-taggable-on/taggable/tagged_with_query/exclude_tags_query.rb)
4. Chain with other scopes: Article.tagged_with('ruby').where(published: true) (lib/acts-as-taggable-on/taggable/tagged_with_query/query_base.rb)

• Polymorphic Associations (ActiveRecord) — Allows any model to be taggable without requiring model-specific join tables; single tags table serves all models
• Rails Engines — Encapsulates migrations, initializers, and gem configuration as a self-contained Rails engine for easy installation
• Pluggable Parser Architecture — Allows developers to customize tag string parsing (comma-delimited, quoted, custom formats) without modifying core code
• Tag Ownership via Tagger Model — Tracks which user created which tag on which object, enabling multi-user tagging workflows with attribution
• Query Objects Pattern — Encapsulates complex ActiveRecord queries (all_tags, any_tags, exclude) as separate classes for maintainability and composability

• Polymorphic taggings table instead of per-model join tables
  • Why: Simplifies gem integration; a single taggings table serves all taggable models
  • Consequence: Taggings queries use string-based polymorphic conditions (taggable_type, taggable_id) which can be slower than native foreign keys; requires careful index

Database migrations are required; the gem won't work without running rake acts_as_taggable_on_engine:install:migrations and rails db:migrate. The tagging join table can trigger N+1 queries if you don't eager-load Tagging associations (use .includes(:taggings, :tags)). Tag parsing depends on parser choice (DefaultParser vs GenericParser, configured in initializer)—wrong parser can break tag splitting. The gem modifies models at include time, so acts_as_taggable must be called inside the model class definition, not dynamically. No apparent API versioning or deprecation warnings in the README, so breaking changes in updates may affect dependent code.

• Polymorphic Association — ActsAsTaggableOn uses a polymorphic join table (Tagging model with taggable_type/taggable_id) to tag any model without creating dedicated join tables per model. Essential for understanding how the gem scales to multiple taggable types.
• ActiveRecord STI (Single Table Inheritance) — The plugin may use STI patterns for Tagger models (users, groups) to unify tag ownership logic. Understanding STI helps when extending ownership features.
• Named Scopes / Scope Chains — Tagged_with queries are built via Arel and scope chains (e.g., Model.tagged_with('ruby').tagged_with('rails', on: :skills)). Understanding scope composition is critical for building complex queries.
• Mixin / Module Inclusion Pattern — The gem's DSL is implemented via mixins (Taggable::Core, Taggable::Caching, etc.) included into models. Understanding Ruby mixins and method lookup is essential for extending the gem.
• Query Builder / Strategy Pattern — Tagged_with_query/ directory uses a strategy pattern (AllTagsQuery, AnyTagsQuery, ExcludeTagsQuery subclass QueryBase) to generate different SQL. Learning this pattern helps when adding new query types.
• Database Indexing Strategy — The join table schema (db/migrate/1_setup_acts_as_taggable_on.rb) is heavily indexed for performance (taggable_id, taggable_type, tag_id). Understanding index design prevents N+1 queries and slow tag searches.
• Dirty Tracking / ActiveModel::Dirty — The gem supports 'dirty objects' (mentioned in README), using Rails' built-in dirty tracking to detect tag changes before saving. Critical for implementing tag change callbacks.

• rails-tagging/rails-tagging — Alternative tagging gem for Rails with similar multi-context support; compare approach and feature parity.
• radar/paranoia — Soft-delete gem often used alongside acts-as-taggable-on to preserve tag history and prevent accidental data loss.
• rails/rails — Rails framework itself; acts-as-taggable-on depends on its ActiveRecord and Engine APIs—understanding Rails internals helps debug integration.
• thoughtbot/factory_bot — Test factory gem frequently used in Rails projects to seed taggable models during testing; common pairing in test suites.
• presidentbeef/brakeman — Security scanner for Rails apps; acts-as-taggable-on processes user-supplied tag input, so understanding XSS/injection risks is relevant.

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 integration tests for tagged_with_query module across Rails versions

The repo supports Rails 7.1-8.1 (via gemfiles/) but lacks dedicated tests for the complex tagged_with_query system (all_tags_query.rb, any_tags_query.rb, exclude_tags_query.rb, query_base.rb). With multiple Rails versions and query types, edge cases around SQL generation and ActiveRecord behavior likely exist. Creating version-specific test cases would catch regressions early and document expected behavior.

• [ ] Create spec/acts_as_taggable_on/taggable/tagged_with_query/all_tags_query_spec.rb with tests for multi-tag matching across Rails versions
• [ ] Create spec/acts_as_taggable_on/taggable/tagged_with_query/any_tags_query_spec.rb testing OR logic and performance
• [ ] Create spec/acts_as_taggable_on/taggable/tagged_with_query/exclude_tags_query_spec.rb for negation logic
• [ ] Add appraisal integration to run these specs against all gemfiles/activerecord_*.gemfile versions
• [ ] Test edge cases: empty tag lists, special characters, case sensitivity, duplicate tag handling

Add tagging ownership and tag context integration tests

The codebase includes ownership (lib/acts-as-taggable-on/taggable/ownership.rb) and dynamic context support, but spec/acts_as_taggable_on/acts_as_tagger_spec.rb and spec/acts_as_taggable_on/tagging_spec.rb may not cover the intersection of these features. A user should be able to tag with ownership in different contexts without data leakage or permission issues. Comprehensive integration tests would validate this critical feature combination.

• [ ] Review existing ownership.rb and tagger.rb to identify untested code paths
• [ ] Create spec/acts_as_taggable_on/taggable/ownership_integration_spec.rb testing ownership + context combinations
• [ ] Add tests for: owned tags in custom contexts, listing tags by owner in a specific context, removing owned tags from contexts
• [ ] Test edge case: same tag with different owners in same context on same object
• [ ] Verify tagger_spec.rb covers all ownership methods (tagger_id, remove_tag with tagger, etc.)

Implement and test the tag_list_type.rb custom Rails attribute type

lib/acts-as-taggable-on/taggable/tag_list_type.rb exists but appears to be a Rails 5.0+ attribute type abstraction with limited visibility in specs. This is critical for serialization/deserialization in modern Rails. There's likely no dedicated test file for this type, meaning edge cases around dirty tracking, type casting, and database round-trips may be untested.

• [ ] Create spec/acts_as_taggable_on/taggable/tag_list_type_spec.rb
• [ ] Test cast(), deserialize(), serialize() methods with various inputs: nil, empty array, string, array of tags
• [ ] Add tests for dirty tracking integration: verify changed? and changes methods work correctly
• [ ] Test database round-trip: store and retrieve tags via tag_list_type attribute
• [ ] Test interaction with tag parser configuration (default vs generic parser)
• [ ] Verify behavior across Rails 7.1-8.1 via appraisals

• Add comprehensive RSpec tests for lib/acts-as-taggable-on/taggable/tag_list_type.rb—this file appears in the structure but has no obvious test file. Writing specs for TagListType behavior would improve coverage.
• Improve documentation for custom parser creation—lib/acts-as-taggable-on/generic_parser.rb and default_parser.rb exist but README only mentions tag parsers in passing. Add a cookbook example showing how to write a custom parser (e.g., for hashtag-style parsing).
• Add Rails 8.0 / 8.1 compatibility tests and update gemfiles if needed—gemfiles/activerecord_8.0.gemfile and 8.1 exist but no spec.yml matrix entries visible. Ensure CI tests all Rails versions and update CHANGELOG with any compatibility notes.

• High · SQL Injection Risk in Tagged With Query — lib/acts-as-taggable-on/taggable/tagged_with_query/. The file structure indicates dynamic SQL query construction in lib/acts-as-taggable-on/taggable/tagged_with_query/ directory. Tag-based queries that accept user input could be vulnerable to SQL injection if tag names or contexts are not properly parameterized. The presence of multiple query builder classes (all_tags_query.rb, any_tags_query.rb, exclude_tags_query.rb) suggests complex query construction that may concatenate user input. Fix: Audit all query construction in this directory to ensure parameterized queries are used exclusively. Verify that tag values and contexts are bound as parameters, not concatenated into SQL strings. Use ActiveRecord's built-in query methods (where, select, etc.) with placeholders.
• High · XSS Risk in Tags Helper — lib/acts-as-taggable-on/tags_helper.rb. The presence of lib/acts-as-taggable-on/tags_helper.rb suggests view helper functions that likely output tag data. If tag names or user-provided tag data are rendered in views without proper HTML escaping, they could enable stored XSS attacks, as tag content is user-controlled. Fix: Ensure all tag output in views is properly HTML-escaped. Use Rails' safe_join, sanitize, or similar methods when rendering tags. Validate that ERB templates use <%= %> (auto-escaped) rather than <%== %> for tag content. Implement Content Security Policy (CSP) headers.
• Medium · Missing Input Validation in Tag Parser — lib/acts-as-taggable-on/default_parser.rb, lib/acts-as-taggable-on/generic_parser.rb. The tag parsers (default_parser.rb and generic_parser.rb) process user-supplied tag input. Without proper validation and sanitization, malformed or malicious input could cause issues. Tag names may need length limits, character restrictions, or other validation logic. Fix: Implement strict input validation for tag names including: maximum length enforcement, allowed character whitelisting, prevention of control characters, and handling of Unicode edge cases. Add validation at the model level using ActiveRecord validators.
• Medium · Hardcoded Database Credentials in Docker Compose — docker-compose.yml. The docker-compose.yml file contains hardcoded database credentials (POSTGRES_PASSWORD: postgres, MYSQL_ALLOW_EMPTY_PASSWORD: true). While this is a development configuration, it establishes poor security practices and the file may be checked into version control, exposing credential patterns. Fix: Use environment variables or .env files (excluded from git) for database credentials. For development, use strong default credentials or document the need to configure them. Never commit real production credentials. Consider using docker-compose.override.yml for local overrides.
• Medium · Exposed Database Ports in Docker Compose — docker-compose.yml. The docker-compose.yml exposes database ports 5432 (PostgreSQL) and 3306 (MySQL) directly to localhost without network isolation. If docker-compose is used in production or on shared systems, this could allow unauthorized database access. Fix: Remove port mappings for databases in production configurations. For development, bind only to localhost (127.0.0.1:5432). Use networks defined in docker-compose for inter-service communication instead of exposing ports. Implement firewall rules if ports must be exposed.
• Medium · Potential Migration SQL Injection — db/migrate/1_setup_acts_as_taggable_on.rb. The migration file db/migrate/1_setup_acts_as_taggable_on.rb creates database schema. If this migration accepts external parameters or constructs SQL dynamically, it could be vulnerable to injection attacks during installation. Fix: Review the migration to ensure all table creation uses ActiveRecord's DSL (create_table, add_column, etc.) without dynamic SQL construction. Avoid string interpolation in migration files. Use change method instead of up/down when possible for reversibility.
• Low · Outdated PostgreSQL Docker Image — docker-. The docker-compose.yml specifies PostgreSQL version 10, which reached end-of-life in October 2022. This version no longer receives security updates, increasing vulnerability to known exploits. Fix: undefined

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.