ariadna 1.3.0 → 2.0.0

data/data/commands/ariadna/verify-work.md

@@ -1,39 +1,34 @@
 ---
 name: ariadna:verify-work
-description: Validate built features through conversational UAT
+description: Validate built features against phase goals — goal-backward, not task-backward
 argument-hint: "[phase number, e.g., '4']"
 allowed-tools:
   - Read
+  - Write
+  - Edit
   - Bash
   - Glob
   - Grep
-  - Edit
-  - Write
   - Task
 ---
 <objective>
-Validate built features through conversational testing with persistent state.
-
-Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation. When issues are found, automatically diagnose, plan fixes, and prepare for execution.
+Confirm that what was built delivers the phase goal, not merely that tasks were completed. Produces VERIFICATION.md with pass/fail/gap status and feeds gaps back into planning.
 
-Output: {phase}-UAT.md tracking all test results. If issues found: diagnosed gaps, verified fix plans ready for /ariadna:execute-phase
+Spawn `ariadna-verifier` to check goal achievement against the actual codebase.
 </objective>
 
-<execution_context>
-@~/.claude/ariadna/workflows/verify-work.md
-@~/.claude/ariadna/templates/UAT.md
-</execution_context>
-
 <context>
-Phase: $ARGUMENTS (optional)
-- If provided: Test specific phase (e.g., "4")
-- If not provided: Check for active sessions or prompt for phase
+Phase: $ARGUMENTS (optional — checks active session or prompts if omitted)
 
-@.ariadna_planning/STATE.md
-@.ariadna_planning/ROADMAP.md
+Follow the workflow in `~/.claude/ariadna/workflows/verify-work.md` end-to-end.
 </context>
 
 <process>
-Execute the verify-work workflow from @~/.claude/ariadna/workflows/verify-work.md end-to-end.
-Preserve all workflow gates (session management, test presentation, diagnosis, fix planning, routing).
+1. Run `ariadna-tools init verify-work "$PHASE_ARG"` to load context as JSON.
+2. If `has_verification: true`, offer to re-verify or show existing report.
+3. Spawn `ariadna-verifier`; verifier checks `must_haves` from plan frontmatter against files on disk.
+4. On completion: update `memory/progress.md` and STATE.md.
+5. If `gaps_found`: display gap summary and offer `/ariadna:plan-phase {N} --gaps`.
+6. If `human_needed`: list items for manual testing; wait for confirmation before marking verified.
+7. If `passed`: mark phase verified in STATE.md and ROADMAP.md.
 </process>

data/data/skills/rails-backend/API.md

@@ -0,0 +1,138 @@
+# Rails Backend: API Design
+
+JSON responses, serialization, pagination, versioning, and webhook patterns.
+
+---
+
+## Philosophy
+
+The application is primarily Turbo/Hotwire, but controllers respond to JSON where needed. The same domain model methods serve both formats — no separate API layer.
+
+```ruby
+def create
+  @card.gild
+
+  respond_to do |format|
+    format.turbo_stream { render_card_replacement }
+    format.json { head :no_content }
+  end
+end
+```
+
+---
+
+## RESTful URL Design
+
+State changes are modeled as resources, never custom actions:
+
+```
+POST   /:account_id/boards/:board_id/cards/:card_id/closure    → close card
+DELETE /:account_id/boards/:board_id/cards/:card_id/closure    → reopen card
+POST   /:account_id/boards/:board_id/cards/:card_id/goldness   → gild card
+POST   /:account_id/boards/:board_id/cards/:card_id/assignments → assign user
+```
+
+The `{account_id}` path segment is the multi-tenancy key — middleware extracts it to set `Current.account`.
+
+---
+
+## Standard JSON Response Patterns
+
+```ruby
+format.json { head :no_content }                                          # Success, no body
+format.json { render json: @card }                                        # Success with resource
+format.json { render json: @card, status: :created, location: @card }    # Created
+format.json { render json: @card.errors, status: :unprocessable_entity } # Validation failure
+format.json { head :forbidden }                                           # Not authorized
+```
+
+---
+
+## Serialization
+
+Keep serialization out of models. Use a dedicated serializer object for complex shapes:
+
+```ruby
+class CardSerializer
+  def initialize(card)
+    @card = card
+  end
+
+  def as_json
+    {
+      id: @card.number,      # Always expose number as public ID, never database id
+      title: @card.title,
+      closed: @card.closed?,
+      golden: @card.golden?,
+      creator: { id: @card.creator.id, name: @card.creator.name }
+    }
+  end
+end
+
+render json: CardSerializer.new(@card).as_json
+```
+
+**Always expose `number` as the public card identifier, not `id`.**
+
+---
+
+## Pagination in API Responses
+
+```ruby
+def index
+  set_page_and_extract_portion_from Current.account.cards.active.ordered
+
+  respond_to do |format|
+    format.json do
+      render json: {
+        cards: @page.records.map { |c| CardSerializer.new(c).as_json },
+        meta: {
+          page: @page.number,
+          last_page: @page.last?,
+          next_page: @page.last? ? nil : @page.next_param,
+          total: @page.recordset.records_count
+        }
+      }
+    end
+  end
+end
+```
+
+For large datasets (100k+ rows), use cursor-based pagination:
+
+```ruby
+set_page_and_extract_portion_from Event.all, ordered_by: { created_at: :desc, id: :desc }
+```
+
+---
+
+## Versioning
+
+Namespace routes and controllers when versioning is needed:
+
+```ruby
+# config/routes.rb
+namespace :api do
+  namespace :v1 do
+    resources :boards do
+      resources :cards
+    end
+  end
+end
+```
+
+Controllers in `app/controllers/api/v1/` reuse the same domain model methods. Only serialization and routing differ between versions.
+
+---
+
+## Webhook Events
+
+Webhooks are driven by the event system. Events carry a `particulars` JSON hash with action-specific context:
+
+```ruby
+event.action      # => "card_board_changed"
+event.eventable   # => the Card record
+event.particulars # => { "old_board" => "Project A", "new_board" => "Project B" }
+```
+
+Delivery is handled by `Webhook::DeliveryJob` — decoupled from request handling via `after_create_commit` on the Event model.

data/data/skills/rails-backend/CONTROLLERS.md

@@ -0,0 +1,154 @@
+# Rails Backend: Controllers
+
+HTTP boundary conventions — thin controllers, RESTful resource modeling, concerns, pagination.
+
+---
+
+## Thin Controllers
+
+Controllers have exactly 3 responsibilities: **setup, call model, respond.** No business logic.
+
+```ruby
+class Cards::GoldnessesController < ApplicationController
+  include CardScoped  # Sets @card and @board via before_action
+
+  def create
+    @card.gild         # Single model method call
+
+    respond_to do |format|
+      format.turbo_stream { render_card_replacement }
+      format.json { head :no_content }
+    end
+  end
+
+  def destroy
+    @card.ungild
+    respond_to { |f| f.turbo_stream { render_card_replacement } }
+  end
+end
+```
+
+That's the entire controller. Must not contain business logic, build complex queries, or directly manipulate multiple models.
+
+---
+
+## RESTful Resource Nesting
+
+Model every state change as a resource. Never add custom action methods.
+
+```ruby
+# Bad: custom actions
+resources :cards do
+  post :close
+  post :gild
+end
+
+# Good: each state change is its own resource
+resources :cards do
+  scope module: :cards do
+    resource :closure   # POST creates (close), DELETE destroys (reopen)
+    resource :goldness  # POST creates (gild), DELETE destroys (ungild)
+    resource :pin
+    resource :watch
+    resources :assignments
+    resources :comments
+  end
+end
+```
+
+**Rule of thumb**: If the action creates, updates, or destroys something — that "something" is the resource.
+- Close card → creates `Closure`
+- Gild card → creates `Goldness`
+- Assign user → creates `Assignment`
+
+---
+
+## Controller Concerns
+
+Extract repeated `before_action` patterns:
+
+```ruby
+module CardScoped
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :set_card, :set_board
+  end
+
+  private
+    def set_card
+      # Cards found by :number (user-facing ID), scoped to accessible cards
+      @card = Current.user.accessible_cards.find_by!(number: params[:card_id])
+    end
+
+    def set_board = @board = @card.board
+
+    def render_card_replacement
+      render turbo_stream: turbo_stream.replace(
+        [@card, :card_container],
+        partial: "cards/container",
+        method: :morph,
+        locals: { card: @card.reload }
+      )
+    end
+end
+
+module BoardScoped
+  extend ActiveSupport::Concern
+  included do
+    before_action :set_board
+  end
+  private
+    def set_board = @board = Current.user.boards.find(params[:board_id])
+    def ensure_admin = head(:forbidden) unless Current.user.can_administer_board?(@board)
+end
+```
+
+Create a controller concern when 3+ controllers share the same `before_action` or resource loading.
+
+---
+
+## Pagination
+
+Use `geared_pagination` — one call, variable-speed page sizes (15 → 30 → 50 → 100):
+
+```ruby
+def index
+  set_page_and_extract_portion_from Current.account.cards.active.ordered
+  # Sets @page with records, page number, last? flag, next_param
+end
+```
+
+Cursor-based for large datasets (100k+ rows):
+
+```ruby
+set_page_and_extract_portion_from Event.all,
+  ordered_by: { created_at: :desc, id: :desc }  # O(1) seeks, no OFFSET
+```
+
+Never use manual `limit`/`offset`. Never build a custom pagination service object.
+
+---
+
+## Error Handling and Strong Parameters
+
+```ruby
+# Raise on missing resource — Rails rescues with 404
+@card = Current.user.accessible_cards.find_by!(number: params[:card_id])
+
+# Validation failure
+def create
+  if @board.update(board_params)
+    redirect_to @board
+  else
+    render :edit, status: :unprocessable_entity
+  end
+end
+
+private
+  def card_params
+    params.require(:card).permit(:title, :description, :column_id, tag_ids: [])
+  end
+```
+
+Never use `permit!`. Always permit only what's needed for the action.

data/data/skills/rails-backend/JOBS.md

@@ -0,0 +1,132 @@
+# Rails Backend: Jobs
+
+ActiveJob patterns — ultra-thin jobs, _now/_later naming, automatic multi-tenancy, retry logic.
+
+---
+
+## Core Rule
+
+Jobs are thin wrappers around model methods. **All business logic belongs in models.** A job should be 3-6 lines.
+
+```ruby
+# Good
+class NotifyRecipientsJob < ApplicationJob
+  def perform(notifiable) = notifiable.notify_recipients
+
+# Bad: 50 lines of logic that can't be called synchronously or tested easily
+class NotifyRecipientsJob < ApplicationJob
+  def perform(comment)
+    # logic that belongs in comment.notify_recipients
+  end
+end
+```
+
+---
+
+## The _now/_later Pattern
+
+For every async operation, create a matched pair on the model plus a job class:
+
+```ruby
+# In the model/concern:
+module Notifiable
+  extend ActiveSupport::Concern
+
+  included do
+    after_create_commit :notify_recipients_later  # Trigger async after commit
+  end
+
+  def notify_recipients                           # Synchronous — call from anywhere
+    Notifier.for(self)&.notify
+  end
+
+  private
+    def notify_recipients_later                   # Async wrapper
+      NotifyRecipientsJob.perform_later self
+    end
+end
+
+# Job:
+class NotifyRecipientsJob < ApplicationJob
+  def perform(notifiable) = notifiable.notify_recipients
+end
+```
+
+### Why
+
+```ruby
+# Async vs sync is explicit:
+comment.notify_recipients        # Synchronous — use in console, tests, other methods
+comment.notify_recipients_later  # Async — enqueues job
+
+# Synchronous method enables:
+# - Fast unit tests (no queue)
+# - Rails console usage
+# - Calling from other model methods
+```
+
+---
+
+## Job Examples
+
+```ruby
+class Webhook::DeliveryJob < ApplicationJob
+  queue_as :webhooks
+  def perform(delivery) = delivery.deliver
+end
+
+class ExportAccountDataJob < ApplicationJob
+  queue_as :backend
+  def perform(export) = export.build
+end
+```
+
+---
+
+## Multi-Tenancy in Jobs
+
+A global `ActiveJob` extension handles tenant context transparently. **Never pass account manually.**
+
+```ruby
+# Don't do this:
+SomeJob.perform_later(record, account: Current.account)
+
+# Do this — account captured automatically at enqueue time:
+SomeJob.perform_later(record)
+```
+
+How it works:
+- **On enqueue**: captures `Current.account` (serialized as GlobalID)
+- **On execute**: wraps `perform` in `Current.with_account(@account) { ... }`
+
+All queries inside `perform` have `Current.account` set correctly. Jobs are always enqueued `after_transaction_commit` — prevents jobs for rolled-back records.
+
+---
+
+## Recurring Jobs
+
+```yaml
+# config/recurring.yml
+auto_postpone_cards:
+  schedule: "50 * * * *"   # Every hour at :50
+  command: "Card.auto_postpone_all_due"
+```
+
+Commands call class methods on models — consistent with keeping logic in models.
+
+---
+
+## Retry Logic
+
+```ruby
+class ImportJob < ApplicationJob
+  retry_on Net::TimeoutError, wait: :polynomially_longer, attempts: 5
+  discard_on ActiveJob::DeserializationError  # Record deleted before job ran
+
+  def perform(import) = import.run
+end
+```
+
+- `retry_on` for transient failures (network timeouts, rate limits)
+- `discard_on` for permanent failures where retrying is pointless
+- Keep retry configuration on the job class; keep the work in model methods

data/data/skills/rails-backend/MODELS.md

@@ -0,0 +1,213 @@
+# Rails Backend: Models
+
+ActiveRecord patterns, concern architecture, associations, scoping, and callbacks.
+
+---
+
+## Concern Architecture
+
+Concerns are the most distinctive pattern. Models compose behavior from focused modules.
+
+**Shared concerns** (`app/models/concerns/`) — reusable across 3+ unrelated models, adjective naming: `Eventable`, `Notifiable`, `Searchable`, `Attachments`
+
+**Model-specific concerns** (`app/models/card/`, `app/models/board/`) — namespaced, tightly coupled: `Card::Closeable`, `Card::Golden`, `Board::Accessible`
+
+### Anatomy
+
+```ruby
+module Card::Closeable
+  extend ActiveSupport::Concern  # Required first line
+
+  included do
+    has_one :closure, dependent: :destroy
+    scope :closed, -> { joins(:closure) }
+    scope :open,   -> { where.missing(:closure) }
+  end
+
+  def closed? = closure.present?
+  def open?   = !closed?
+
+  def close(user: Current.user)
+    unless closed?
+      transaction do
+        create_closure! user: user
+        track_event :closed, creator: user
+      end
+    end
+  end
+
+  private
+    # Private helpers indented under private
+end
+```
+
+### Concern Composition
+
+```ruby
+class Card < ApplicationRecord
+  include Assignable, Attachments, Closeable, Eventable, Golden, Mentions,
+    Notifiable, Postponable, Searchable, Storage::Tracked, Taggable, Watchable
+
+  belongs_to :board
+  belongs_to :account, default: -> { board.account }  # board declared first
+  belongs_to :creator, class_name: "User", default: -> { Current.user }
+end
+```
+
+### When to Create
+
+- **Shared concern**: 3+ unrelated models, cross-cutting behavior (events, search, notifications)
+- **Model-specific**: 50+ lines of cohesive behavior for one model feature
+- **Don't create**: 1-2 simple methods, just grouping unrelated methods
+
+### Template Method Pattern
+
+Base concerns define override points; model-specific concerns customize them:
+
+```ruby
+module Eventable
+  private
+    def should_track_event? = true                                    # Override point
+    def eventable_prefix = self.class.name.demodulize.underscore      # Override point
+end
+
+module Card::Eventable
+  extend ActiveSupport::Concern
+  include ::Eventable
+  private
+    def should_track_event? = published?   # Override: only track published cards
+end
+```
+
+### Concerns Delegate Complexity to Plain Ruby Objects
+
+```ruby
+module Notifiable
+  included do
+    after_create_commit :notify_recipients_later
+  end
+  def notify_recipients = Notifier.for(self)&.notify  # Delegates to Notifier hierarchy
+end
+```
+
+---
+
+## Intention-Revealing APIs
+
+Always provide both query forms, use imperative verbs, delegate for readability:
+
+```ruby
+def closed? = closure.present?    # Positive check
+def open?   = !closed?            # Negative check
+
+def close  /  def reopen          # not: set_closed / remove_closure
+def gild   /  def ungild          # not: make_golden / remove_golden
+
+def closed_by = closure&.user     # Delegates — not: closure&.user in callers
+def closed_at = closure&.created_at
+```
+
+Multi-step operations: transactions wrap everything; async ops go outside:
+
+```ruby
+def close(user: Current.user)
+  transaction do
+    create_closure! user: user
+    track_event :closed, creator: user  # Inside transaction
+  end
+end
+```
+
+---
+
+## Smart Association Defaults
+
+```ruby
+belongs_to :board                                          # Declare before use
+belongs_to :account, default: -> { board.account }        # Derives from parent
+belongs_to :creator, class_name: "User", default: -> { Current.user }
+# Card.create!(board:, title:) — account and creator set automatically
+```
+
+Use for `account` (multi-tenancy) and `creator`/`user` (from `Current.user`).
+
+---
+
+## Scopes That Tell Stories
+
+Business names, not SQL names. Always use `-> { }` lambdas:
+
+```ruby
+scope :closed, -> { joins(:closure) }
+scope :open,   -> { where.missing(:closure) }
+scope :closed_by, ->(users) { closed.where(closures: { user_id: Array(users) }) }
+
+# Conditional scope maps UI concepts — keeps conditionals out of controllers:
+scope :indexed_by, ->(index) do
+  case index
+  when "closed" then closed
+  when "golden" then golden
+  else all
+  end
+end
+
+# Named preloading scope — prevents N+1:
+scope :preloaded, -> {
+  preload(:column, :tags, :closure, :goldness, board: [:entropy, :columns])
+    .with_rich_text_description_and_embeds
+}
+```
+
+---
+
+## Callbacks
+
+**Use for:** required data on create, async triggers, touching associations.
+**Don't use for:** business logic, complex orchestration, anything callers want to skip.
+
+```ruby
+before_create :assign_number                                        # Set required data
+after_create_commit :notify_recipients_later                        # After commit (not after_create)
+after_save   -> { board.touch }, if: :published?                    # Simple one-liners as lambdas
+after_update :handle_board_change, if: :saved_change_to_board_id?  # Conditional
+```
+
+Use `_commit` variants for async jobs — prevents running for rolled-back records.
+
+---
+
+## Event Tracking
+
+Call `track_event` inside transactions; auto-prefixed by model name:
+
+```ruby
+transaction do
+  create_closure! user: user
+  track_event :closed, creator: user   # Produces "card_closed"
+end
+
+transaction do
+  update!(board: new_board)
+  track_event "board_changed", particulars: { old_board: name_was, new_board: new_board.name }
+end
+```
+
+---
+
+## Concern Reference
+
+| Shared | Key API |
+|--------|---------|
+| `Eventable` | `track_event(action, **particulars)` |
+| `Notifiable` | `notify_recipients`, `notify_recipients_later` |
+| `Searchable` | auto-indexes on save |
+| `Storage::Tracked` | auto-tracks on attachment changes |
+
+| Card | Key API |
+|------|---------|
+| `Card::Closeable` | `close`, `reopen`, `closed?`, `open?` |
+| `Card::Golden` | `gild`, `ungild`, `golden?` |
+| `Card::Assignable` | `assign(user)`, `unassign(user)` |
+| `Card::Postponable` | `postpone`, `resume`, `auto_postpone` |
+| `Card::Triageable` | `triage_into(column)`, `send_back_to_triage` |
+| `Card::Watchable` | `watch`, `unwatch`, `watched_by?(user)` |