ariadna 1.3.0 → 2.0.0

data/data/ariadna/references/rails-conventions.md

@@ -1,416 +0,0 @@
-<rails_conventions>
-
-Pre-baked Rails knowledge for Ariadna planning and execution agents. This document replaces generic research for standard Rails projects, encoding well-known conventions, patterns, and pitfalls so agents don't need to web-search for common Rails patterns.
-
-<standard_stack>
-
-## Standard Rails Stack (2025)
-
-| Layer | Technology | Notes |
-|-------|-----------|-------|
-| Framework | Rails 8+ | Defaults to SQLite in dev, includes Solid Queue/Cache/Cable |
-| Database | PostgreSQL (production) | SQLite for dev/test is fine for most projects |
-| Background Jobs | Solid Queue | Rails 8 default, replaces Sidekiq for most cases |
-| Caching | Solid Cache | Rails 8 default, database-backed cache |
-| WebSockets | Action Cable + Solid Cable | Rails 8 default |
-| Real-time UI | Turbo (Hotwire) | Turbo Drive, Frames, Streams |
-| JS Sprinkles | Stimulus (Hotwire) | Controllers for interactive behavior |
-| CSS | Tailwind CSS or Propshaft | Rails 8 defaults to Propshaft asset pipeline |
-| Auth | Rails 8 built-in authentication (`has_secure_password` + auth generator) | No external gems needed |
-| Email | Action Mailer | Built-in |
-| File Upload | Active Storage | Built-in |
-| API | Rails API mode or Jbuilder | Built-in |
-| Testing | Minitest | Rails default, use fixtures not factories |
-| Linting | RuboCop + rubocop-rails | Standard community linting |
-
-**What NOT to use (and why):**
-- Devise unless explicitly requested by the user — Rails 8 auth generator + `has_secure_password` covers signup, login, password reset, session management out of the box
-- Pundit/CanCanCan unless explicitly requested — `before_action` checks + `Current` context handle authorization for most apps without adding a gem
-- acts_as_tenant — use `Current.account` scoping with explicit scopes (see backend guide); no gem needed for path-based multi-tenancy
-- Factories (FactoryBot) when fixtures suffice — fixtures are faster, declarative, and Rails-native
-- RSpec unless the project already uses it — Minitest is simpler and Rails-native
-- Webpacker/Shakapacker — replaced by importmap-rails or jsbundling-rails
-- Sprockets — replaced by Propshaft in Rails 8
-- Redis for jobs/cache — Solid Queue/Cache use the database, simpler ops
-
-</standard_stack>
-
-<rails_defaults_first>
-
-## Rails Defaults First (Opinionated)
-
-For new projects, ALWAYS start with Rails built-in solutions. Only introduce external gems when the user explicitly requests them or requirements demonstrably exceed what Rails provides.
-
-| Need | Rails Default | External Gem (only if explicitly requested) |
-|------|--------------|---------------------------------------------|
-| Authentication | `has_secure_password` + Rails 8 auth generator | Devise |
-| Authorization | `before_action` + `Current` context | Pundit, CanCanCan |
-| Multi-tenancy | `Current.account` + explicit scoping | acts_as_tenant |
-| Background Jobs | Solid Queue | Sidekiq |
-| Caching | Solid Cache | Redis |
-| WebSockets | Solid Cable | Redis + AnyCable |
-| Testing | Minitest + fixtures | RSpec + FactoryBot |
-
-**Why:** External gems add dependencies, upgrade burden, and conceptual overhead. Rails 8 ships with excellent defaults that cover 90% of use cases. Starting with built-ins keeps the app simple and maintainable.
-
-**The rule:** Never recommend Devise, Pundit, acts_as_tenant, or similar gems as the default choice for new projects. If the user hasn't asked for them, use Rails built-ins. If the user asks for "authentication", build it with `has_secure_password`. If they ask for "authorization", use `before_action` checks. If they ask for "multi-tenancy", use `Current.account` scoping.
-
-</rails_defaults_first>
-
-<architecture_patterns>
-
-## Rails Architecture Patterns
-
-### MVC Foundation
-- **Models:** Business logic lives here. Validations, scopes, callbacks, associations.
-- **Controllers:** Thin. Receive request, call model, render response. 7 RESTful actions max.
-- **Views:** ERB templates. Logic delegated to presenters or helpers.
-
-### Concern-Driven Architecture
-```
-app/models/concerns/
-  shared/           # Cross-model concerns (Trackable, Searchable)
-  model_name/       # Model-specific concerns (User::Authenticatable)
-```
-
-**When to extract a concern:**
-- Behavior reused across 2+ models → shared concern
-- Model file exceeds ~100 lines → model-specific concern
-- Logical grouping of related methods → named concern
-
-### Service Objects (When Needed)
-Use plain Ruby objects in `app/services/` for:
-- Multi-model operations (CreateOrderWithPayment)
-- External API integrations (StripeChargeService)
-- Complex business processes spanning multiple steps
-
-**Don't use for:** Simple CRUD, single-model operations, or anything a model method handles.
-
-### Presenter Pattern
-Plain Ruby classes for complex view logic:
-```ruby
-# app/models/dashboard_presenter.rb (NOT app/presenters/)
-class DashboardPresenter
-  include ActionView::Helpers::TagHelper
-
-  def initialize(user)
-    @user = user
-  end
-
-  def greeting
-    "Welcome, #{@user.name}"
-  end
-end
-```
-
-### RESTful Resource Design
-- Prefer creating new controllers over adding custom actions
-- `POST /messages/:id/archive` → `ArchivesController#create`
-- Nest resources max 1 level: `/posts/:post_id/comments`
-- Use `concerns` in routes for shared resource patterns
-
-### Current Attributes
-```ruby
-# app/models/current.rb
-class Current < ActiveSupport::CurrentAttributes
-  attribute :user, :session, :account
-end
-```
-Set in `ApplicationController`, access everywhere. No parameter passing for auth context.
-
-</architecture_patterns>
-
-<common_pitfalls>
-
-## Common Rails Pitfalls (with Prevention)
-
-### 1. N+1 Queries
-**Problem:** Loading associated records in a loop.
-**Prevention:** Use `includes`, `preload`, or `eager_load` in controllers. Add `strict_loading` to models in development.
-```ruby
-# Bad
-@posts = Post.all  # then post.comments in view
-
-# Good
-@posts = Post.includes(:comments, :author).all
-```
-
-### 2. Missing Database Indexes
-**Prevention:** Always add indexes for:
-- Foreign keys (`add_index :posts, :user_id`)
-- Columns used in `where` clauses
-- Columns used in `order` clauses
-- Unique constraints (`add_index :users, :email, unique: true`)
-
-### 3. Mass Assignment Vulnerabilities
-**Prevention:** Always use `strong_parameters` in controllers.
-```ruby
-def post_params
-  params.require(:post).permit(:title, :body, :published)
-end
-```
-
-### 4. Callback Hell
-**Prevention:** Limit callbacks to:
-- `before_validation` for normalization (strip whitespace, downcase email)
-- `after_create_commit` for async side effects (send email, broadcast)
-- Avoid `after_save` chains that trigger cascading updates
-
-### 5. Fat Controllers
-**Prevention:** Controllers should only:
-1. Authenticate/authorize
-2. Load/build the resource
-3. Call save/update/destroy
-4. Respond with redirect or render
-
-### 6. Missing Validations
-**Prevention:** Validate at model level, not just in forms:
-- Presence on required fields
-- Uniqueness with database-level constraint
-- Format for emails, URLs, phone numbers
-- Numericality for quantities, prices
-
-### 7. Unscoped Queries (Multi-tenancy)
-**Prevention:** Always scope queries to current user/account:
-```ruby
-# Bad
-Post.find(params[:id])
-
-# Good
-Current.user.posts.find(params[:id])
-```
-
-### 8. Missing Error Handling
-**Prevention:** Add `rescue_from` in `ApplicationController`:
-```ruby
-rescue_from ActiveRecord::RecordNotFound, with: :not_found
-rescue_from ActionController::ParameterMissing, with: :bad_request
-```
-
-### 9. Synchronous External Calls
-**Prevention:** Always use background jobs for:
-- Sending emails
-- Calling external APIs
-- Processing uploads
-- Generating reports
-
-### 10. Missing CSRF Protection
-**Prevention:** Rails enables CSRF by default. Don't disable `protect_from_forgery`. For API endpoints, use token auth instead.
-
-</common_pitfalls>
-
-<testing_patterns>
-
-## Rails Testing Patterns (Minitest)
-
-### Test Organization
-```
-test/
-  models/           # Unit tests for models
-  controllers/      # Integration tests for request/response
-  system/           # Browser-based end-to-end tests
-  helpers/          # Helper method tests
-  jobs/             # Background job tests
-  mailers/          # Mailer tests
-  fixtures/         # YAML test data
-  test_helper.rb    # Shared setup
-```
-
-### Fixtures Over Factories
-```yaml
-# test/fixtures/users.yml
-alice:
-  name: Alice
-  email: alice@example.com
-  password_digest: <%= BCrypt::Password.create('password') %>
-
-bob:
-  name: Bob
-  email: bob@example.com
-  password_digest: <%= BCrypt::Password.create('password') %>
-```
-
-**Why fixtures:** Faster (loaded once per test suite), declarative, Rails-native, no external gem needed.
-
-### Model Test Pattern
-```ruby
-class UserTest < ActiveSupport::TestCase
-  setup do
-    Current.session = sessions(:alice_session) # Always set Current context
-  end
-
-  test "validates email presence" do
-    user = User.new(name: "Test")
-
-    assert_not user.valid?
-    assert_includes user.errors[:email], "can't be blank"
-  end
-
-  test "creates user with valid attributes" do
-    assert_difference "User.count", 1 do
-      User.create!(name: "New", email: "new@example.com", password: "password")
-    end
-  end
-end
-```
-
-### Controller Test Pattern (Integration)
-```ruby
-class PostsControllerTest < ActionDispatch::IntegrationTest
-  setup do
-    @user = users(:alice)
-    sign_in @user  # Helper method
-  end
-
-  test "index returns posts" do
-    get posts_url
-
-    assert_response :success
-    assert_select "h2", posts(:first).title
-  end
-
-  test "create redirects on success" do
-    assert_difference "Post.count", 1 do
-      post posts_url, params: { post: { title: "New", body: "Content" } }
-    end
-    assert_redirected_to post_url(Post.last)
-  end
-end
-```
-
-### System Test Pattern
-```ruby
-class UserFlowsTest < ApplicationSystemTestCase
-  test "user can sign up and create a post" do
-    visit new_registration_url
-    fill_in "Name", with: "Test User"
-    fill_in "Email", with: "test@example.com"
-    fill_in "Password", with: "password123"
-    click_on "Sign up"
-
-    assert_text "Welcome, Test User"
-
-    click_on "New Post"
-    fill_in "Title", with: "My First Post"
-    fill_in "Body", with: "Hello world"
-    click_on "Create Post"
-
-    assert_text "My First Post"
-  end
-end
-```
-
-### Key Testing Conventions
-- Use `assert_difference` for state changes, not just boolean checks
-- Set `Current.session` in setup blocks for multi-tenancy
-- Test happy path and one key failure path per method
-- Use `assert_select` for HTML assertions in controller tests
-- Run `bin/rails test` (not `rspec`) for the full suite
-
-</testing_patterns>
-
-<domain_templates>
-
-## Rails Task Templates for Planning
-
-These templates help the planner agent decompose common Rails work into well-structured tasks.
-
-### Add Model
-```
-Tasks:
-1. Create migration + model with validations, associations, and concerns
-   Files: db/migrate/xxx_create_[model].rb, app/models/[model].rb
-2. Add model tests + fixtures
-   Files: test/models/[model]_test.rb, test/fixtures/[model].yml
-```
-
-### Add Controller (with views)
-```
-Tasks:
-1. Add routes + controller with RESTful actions
-   Files: config/routes.rb, app/controllers/[model]_controller.rb
-2. Add views (index, show, new, edit, _form partial)
-   Files: app/views/[model]/*.html.erb
-3. Add controller tests
-   Files: test/controllers/[model]_controller_test.rb
-```
-
-### Add Authentication
-```
-Tasks:
-1. Generate auth scaffold (Rails 8: bin/rails generate authentication)
-   or: Add User model with has_secure_password, Session model, SessionsController
-   Files: app/models/user.rb, app/models/session.rb, app/controllers/sessions_controller.rb
-2. Add auth views (login, registration)
-   Files: app/views/sessions/*.html.erb, app/views/registrations/*.html.erb
-3. Add auth tests
-   Files: test/controllers/sessions_controller_test.rb, test/models/user_test.rb
-```
-
-### Add Background Job
-```
-Tasks:
-1. Create job class + model method it delegates to
-   Files: app/jobs/[name]_job.rb, app/models/[model].rb
-2. Add job tests
-   Files: test/jobs/[name]_job_test.rb
-```
-
-### Add Mailer
-```
-Tasks:
-1. Create mailer + views
-   Files: app/mailers/[name]_mailer.rb, app/views/[name]_mailer/*.html.erb
-2. Add mailer tests
-   Files: test/mailers/[name]_mailer_test.rb
-```
-
-### Add Turbo/Hotwire Feature
-```
-Tasks:
-1. Add Turbo Frame wrapping to target views + controller turbo_stream responses
-   Files: app/views/[model]/*.html.erb, app/controllers/[model]_controller.rb
-   Conventions: 422 for validation errors, 303 for redirects, dom_id for frame IDs
-2. Add Stimulus controller (if interactive behavior needed)
-   Files: app/javascript/controllers/[name]_controller.js
-   Conventions: static values/targets/outlets first, connect/disconnect symmetry
-3. Add Turbo Stream broadcasts (if real-time updates needed)
-   Files: app/models/[model].rb (after_create_commit callbacks)
-   Conventions: prefer default stream actions, broadcast_append_to/replace_to
-4. Add system test for Turbo/Stimulus behavior
-   Files: test/system/[feature]_test.rb
-```
-
-</domain_templates>
-
-<known_domains>
-
-## Known Rails Domains (Skip Research)
-
-These domains are well-understood in Rails and don't need web research:
-
-| Domain | Key Patterns | Research Needed? |
-|--------|-------------|-----------------|
-| Models & Migrations | ActiveRecord, validations, associations, concerns | No |
-| Controllers & Routes | RESTful resources, before_action, strong params | No |
-| Views & Templates | ERB, partials, layouts, content_for | No |
-| Authentication | Rails 8 auth generator, has_secure_password | No |
-| Authorization | before_action + Current context, hand-rolled | No |
-| Background Jobs | Solid Queue, ActiveJob | No |
-| Email | Action Mailer, letter_opener | No |
-| File Uploads | Active Storage | No |
-| Real-time | Action Cable, Turbo Streams | No |
-| Testing | Minitest, fixtures, system tests | No |
-| API Mode | Jbuilder, API-only controllers, token auth | No |
-| Caching | Fragment caching, Russian doll, Solid Cache | No |
-| Search | pg_search, Ransack | Maybe (depends on complexity) |
-| Payments | Stripe, Pay gem | Yes (API details change) |
-| External APIs | Third-party integrations | Yes (API-specific) |
-| Novel Gems | Unfamiliar libraries | Yes |
-| Infrastructure | Docker, Kamal, deployment | Maybe |
-
-**Heuristic:** If all phase requirements map to "No" domains, skip research automatically. If any requirement maps to "Yes", consider `--research` flag.
-
-</known_domains>
-
-</rails_conventions>

data/data/ariadna/references/tdd.md

@@ -1,267 +0,0 @@
-<overview>
-TDD is about design quality, not coverage metrics. The red-green-refactor cycle forces you to think about behavior before implementation, producing cleaner interfaces and more testable code.
-
-**Principle:** If you can describe the behavior as `assert_equal expected, fn(input)` before writing `fn`, TDD improves the result.
-
-**Key insight:** TDD work is fundamentally heavier than standard tasks—it requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. TDD features get dedicated plans to ensure full context is available throughout the cycle.
-</overview>
-
-<when_to_use_tdd>
-## When TDD Improves Quality
-
-**TDD candidates (create a TDD plan):**
-- Business logic with defined inputs/outputs
-- API endpoints with request/response contracts
-- Data transformations, parsing, formatting
-- Validation rules and constraints
-- Algorithms with testable behavior
-- State machines and workflows
-- Utility functions with clear specifications
-
-**Skip TDD (use standard plan with `type="auto"` tasks):**
-- UI layout, styling, visual components
-- Configuration changes
-- Glue code connecting existing components
-- One-off scripts and migrations
-- Simple CRUD with no business logic
-- Exploratory prototyping
-
-**Heuristic:** Can you write `assert_equal expected, fn(input)` before writing `fn`?
-→ Yes: Create a TDD plan
-→ No: Use standard plan, add tests after if needed
-</when_to_use_tdd>
-
-<tdd_plan_structure>
-## TDD Plan Structure
-
-Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cycle.
-
-```markdown
----
-phase: XX-name
-plan: NN
-type: tdd
----
-
-<objective>
-[What feature and why]
-Purpose: [Design benefit of TDD for this feature]
-Output: [Working, tested feature]
-</objective>
-
-<context>
-@.ariadna_planning/PROJECT.md
-@.ariadna_planning/ROADMAP.md
-@relevant/source/files.rb
-</context>
-
-<feature>
-  <name>[Feature name]</name>
-  <files>[source file, test file]</files>
-  <behavior>
-    [Expected behavior in testable terms]
-    Cases: input → expected output
-  </behavior>
-  <implementation>[How to implement once tests pass]</implementation>
-</feature>
-
-<verification>
-[Test command that proves feature works]
-</verification>
-
-<success_criteria>
-- Failing test written and committed
-- Implementation passes test
-- Refactor complete (if needed)
-- All 2-3 commits present
-</success_criteria>
-
-<output>
-After completion, create SUMMARY.md with:
-- RED: What test was written, why it failed
-- GREEN: What implementation made it pass
-- REFACTOR: What cleanup was done (if any)
-- Commits: List of commits produced
-</output>
-```
-
-**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD—use a standard plan and add tests after.
-</tdd_plan_structure>
-
-<execution_flow>
-## Red-Green-Refactor Cycle
-
-**RED - Write failing test:**
-1. Create test file following project conventions
-2. Write test describing expected behavior (from `<behavior>` element)
-3. Run test - it MUST fail
-4. If test passes: feature exists or test is wrong. Investigate.
-5. Commit: `test({phase}-{plan}): add failing test for [feature]`
-
-**GREEN - Implement to pass:**
-1. Write minimal code to make test pass
-2. No cleverness, no optimization - just make it work
-3. Run test - it MUST pass
-4. Commit: `feat({phase}-{plan}): implement [feature]`
-
-**REFACTOR (if needed):**
-1. Clean up implementation if obvious improvements exist
-2. Run tests - MUST still pass
-3. Only commit if changes made: `refactor({phase}-{plan}): clean up [feature]`
-
-**Result:** Each TDD plan produces 2-3 atomic commits.
-</execution_flow>
-
-<test_quality>
-## Good Tests vs Bad Tests
-
-**Test behavior, not implementation:**
-- Good: "returns formatted date string"
-- Bad: "calls formatDate helper with correct params"
-- Tests should survive refactors
-
-**One concept per test:**
-- Good: Separate tests for valid input, empty input, malformed input
-- Bad: Single test checking all edge cases with multiple assertions
-
-**Descriptive names:**
-- Good: "should reject empty email", "returns null for invalid ID"
-- Bad: "test1", "handles error", "works correctly"
-
-**No implementation details:**
-- Good: Test public API, observable behavior
-- Bad: Mock internals, test private methods, assert on internal state
-</test_quality>
-
-<framework_setup>
-## Test Framework Setup (If None Exists)
-
-When executing a TDD plan but no test framework is configured, set it up as part of the RED phase:
-
-**1. Detect project type:**
-```bash
-# Ruby
-if [ -f Gemfile ] || [ -f *.gemspec ]; then echo "ruby"; fi
-
-# Python
-if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi
-
-# Go
-if [ -f go.mod ]; then echo "go"; fi
-
-# Rust
-if [ -f Cargo.toml ]; then echo "rust"; fi
-```
-
-**2. Install minimal framework:**
-| Project | Framework | Install |
-|---------|-----------|---------|
-| Ruby | Minitest (recommended) | Built-in (stdlib) |
-| Ruby on Rails | Minitest (recommended) | Built-in (Rails default) |
-| Ruby | RSpec (alternative) | `bundle add rspec --group test` |
-| Python | pytest | `pip install pytest` |
-| Go | testing | Built-in |
-| Rust | cargo test | Built-in |
-
-**3. Create config if needed:**
-- Minitest: `test/test_helper.rb` with requires
-- RSpec (if using RSpec): `.rspec` and `spec/spec_helper.rb` via `rspec --init`
-- Rails: `test/test_helper.rb` (generated by default)
-- pytest: `pytest.ini` or `pyproject.toml` section
-
-**4. Verify setup:**
-```bash
-# Run empty test suite - should pass with 0 tests
-bundle exec rake test  # Ruby (Minitest)
-bundle exec rspec      # Ruby (if using RSpec)
-bin/rails test         # Rails
-pytest                 # Python
-go test ./...          # Go
-cargo test             # Rust
-```
-
-**5. Create first test file:**
-Follow project conventions for test location:
-- `test/` directory at root (Minitest — recommended Ruby convention)
-- `spec/` directory at root (RSpec)
-- `test/models/`, `test/controllers/` etc. (Rails convention)
-
-Framework setup is a one-time cost included in the first TDD plan's RED phase.
-</framework_setup>
-
-<error_handling>
-## Error Handling
-
-**Test doesn't fail in RED phase:**
-- Feature may already exist - investigate
-- Test may be wrong (not testing what you think)
-- Fix before proceeding
-
-**Test doesn't pass in GREEN phase:**
-- Debug implementation
-- Don't skip to refactor
-- Keep iterating until green
-
-**Tests fail in REFACTOR phase:**
-- Undo refactor
-- Commit was premature
-- Refactor in smaller steps
-
-**Unrelated tests break:**
-- Stop and investigate
-- May indicate coupling issue
-- Fix before proceeding
-</error_handling>
-
-<commit_pattern>
-## Commit Pattern for TDD Plans
-
-TDD plans produce 2-3 atomic commits (one per phase):
-
-```
-test(08-02): add failing test for email validation
-
-- Tests valid email formats accepted
-- Tests invalid formats rejected
-- Tests empty input handling
-
-feat(08-02): implement email validation
-
-- Regex pattern matches RFC 5322
-- Returns boolean for validity
-- Handles edge cases (empty, null)
-
-refactor(08-02): extract regex to constant (optional)
-
-- Moved pattern to EMAIL_REGEX constant
-- No behavior changes
-- Tests still pass
-```
-
-**Comparison with standard plans:**
-- Standard plans: 1 commit per task, 2-4 commits per plan
-- TDD plans: 2-3 commits for single feature
-
-Both follow same format: `{type}({phase}-{plan}): {description}`
-
-**Benefits:**
-- Each commit independently revertable
-- Git bisect works at commit level
-- Clear history showing TDD discipline
-- Consistent with overall commit strategy
-</commit_pattern>
-
-<context_budget>
-## Context Budget
-
-TDD plans target **~40% context usage** (lower than standard plans' ~50%).
-
-Why lower:
-- RED phase: write test, run test, potentially debug why it didn't fail
-- GREEN phase: implement, run test, potentially iterate on failures
-- REFACTOR phase: modify code, run tests, verify no regressions
-
-Each phase involves reading files, running commands, analyzing output. The back-and-forth is inherently heavier than linear task execution.
-
-Single feature focus ensures full quality throughout the cycle.
-</context_budget>