@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/standards/luminary-matching.md

@@ -0,0 +1,105 @@
+---
+tier: lite
+description: Bassclef core picks luminaries for variant generation via a single LLM call to the configured model provider.
+---
+
+# Luminary Matching — Bassclef Core LLM Pick
+
+Bassclef core picks luminaries for variant generation via a **single LLM call** to the configured model provider. The model reads the operator's intent paragraph plus a compact catalog summary (slug + primary domain + name) and returns N slugs whose perspective fits the UX + interaction patterns the intent implies.
+
+No separate embedding vendor. No second-stage judge. One call, one provider, one model key — the same key the consumer is already using for everything else.
+
+Adopters running the optional two-repo pattern (per `standards/operator-private-discipline.md`) who want richer signal (embedding shortlist + LLM judge) layer their own `/extract-intent` skill in their operator-private sibling via `additionalDirectories`. When loaded, that skill takes precedence and bassclef core stays oblivious.
+
+## Rule
+
+Bassclef core's luminary picker uses:
+
+- The operator's intent text (from `InputArtifact.intent` or a paragraph supplied at dispatch)
+- The catalog at `state/luminary-implementations/*.json` (slug + primary_domain + name only)
+- The configured model provider (`config/model-routing.yaml`)
+
+It does NOT use:
+
+- Separate embedding APIs
+- Keyword/regex/grep scoring as the primary path
+- Pre-computed embeddings cache
+
+## When matching fires
+
+Any composer or skill that needs to ground variant generation in named luminaries:
+
+- `/launch` Phase 3.5 — variants pre-grounded
+- `/stage` Phase 3.5 — same
+- `/riff-prototypes` — when invoked standalone (no upstream grounding artifact)
+- `/luminary recommend` — when LLM picker is available
+
+The picker fires once per intent. Variant generation in Phase 4 reads its output and assigns luminaries to the N luminary-driven variants. The Anthropic baseline always lands regardless.
+
+## Adapter — `lib/luminary-pick.sh`
+
+The adapter exposes:
+
+```bash
+luminary_pick "<intent text>" <N> <output_json_path>   # full pipeline
+luminary_pick_status                                   # report LIVE or OFFLINE
+```
+
+Output JSON shape:
+
+```json
+{
+  "matched_luminaries": ["alan-cooper", "edward-tufte", "jakob-nielsen"],
+  "rationale": "Cooper for goal-directed flows; Tufte for data density; Nielsen for findability.",
+  "picker_version": "bassclef-llm-pick-1.0"
+}
+```
+
+## Modes
+
+| Mode | Trigger | Behavior |
+|---|---|---|
+| **LIVE** | `ANTHROPIC_API_KEY` set | Single LLM call; returns matched slugs |
+| **OFFLINE** | Key missing or LLM call fails | Picker refuses; downstream falls back to `/luminary recommend` signal scoring |
+
+## Fallback path
+
+If the LLM picker refuses or errors:
+
+1. Composer logs the refusal
+2. Falls back to `/luminary recommend` signal scoring (keyword + Garrett-plane + primary-domain coverage)
+3. Continues with variant generation against the signal-scored picks
+
+Operator can also opt into the signal-scoring path explicitly via `/riff-prototypes --use-signal-scoring` to skip the LLM call entirely.
+
+## Operator-private override (optional two-repo pattern)
+
+Adopters running the optional two-repo pattern (per `standards/operator-private-discipline.md`) can layer their own `/extract-intent` skill — operator-private substrate that ships richer signal (embedding shortlist + LLM judge) — via `additionalDirectories` injection. When that skill is present:
+
+- `/launch`, `/stage`, `/riff-prototypes` prefer the operator-private `extracted_intent_grounding.matched_luminaries`
+- bassclef-core's `/pick-luminaries` becomes a fallback path
+- bassclef core stays oblivious to whether the operator-private override is loaded
+
+This is the SENTINEL_bassclef_pattern: the operator-private sibling is a superset of bassclef-core. Operators load both and get the upgraded experience; cold adopters load only bassclef and get the LLM-pick default.
+
+## Composes with
+
+- `lib/luminary-pick.sh` — the adapter
+- `.claude/skills/pick-luminaries/SKILL.md` — operator-callable wrapper
+- `state/luminary-implementations/*.json` — catalog manifest
+- `config/model-routing.yaml` — provider selection
+- `/launch` Phase 3.5 + `/stage` Phase 3.5 + `/riff-prototypes` — consumers
+
+## Override + escape hatches
+
+- `/riff-prototypes --luminaries=<slug1>,<slug2>,...` — operator pin (skips picker entirely)
+- `/riff-prototypes --use-signal-scoring` — skip LLM pick; use `/luminary recommend` signal scoring
+- `LUMINARY_PICK_MODEL=<id>` — override the default Haiku-4-5 model
+
+## Sources read
+
+- bassclef#476 LR8.10/8.11 — luminary catalog + traceability
+- bassclef#944 — Voyage matcher excision; replaces ADR-017's two-vendor pipeline with this LLM-pick approach
+- docs/iteration-bets/2026-06-13a-cold-adopter-unboxing-arc.md — parent goal (WU-3)
+- `standards/model-routing-discipline.md` — provider selection mechanism this adapter uses
+

package/dist/lite/standards/luminary-problem-patterns.md

@@ -0,0 +1,481 @@
+---
+tier: lite
+description: "Auto-generated. Do not hand-edit. Re-run via: bash scripts/luminary-problem-patterns-aggregate.sh"
+---
+
+# Luminary problem-pattern catalog
+
+**Auto-generated.** Do not hand-edit. Re-run via:
+```
+bash scripts/luminary-problem-patterns-aggregate.sh
+```
+
+This index reads every `.claude/luminaries/*.md` file's frontmatter and
+extracts the `solves_problems_brownfield`, `solves_problems_greenfield`,
+and `anti_patterns` arrays. The agent reads this index when running
+`/luminary recommend` against a plain-English problem statement.
+
+## Coverage
+
+- **20 / 77** luminaries have problem-pattern frontmatter
+- Backfill tracker: `docs/luminary-problem-pattern-backfill.md`
+
+## Catalog (alphabetical by slug)
+
+### Aarron Walter (`aarron-walter`)
+
+- **Domain:** ux | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- Existing product feels functional but cold — users complete tasks without engagement
+- Microcopy is generic; brand voice doesn't come through
+- Empty states, error states, and waiting states feel like dead ends instead of moments
+
+**Solves (greenfield — 0→1 design):**
+- Designing a new consumer product where personality should differentiate from day one
+- Building microcopy + tone-of-voice as core design elements, not decoration
+- Planning a product where emotional engagement matters as much as task completion
+- Designing empty/error/waiting states as moments of brand expression in a fresh build
+
+**Anti-patterns (when NOT to channel):**
+- Regulated, clinical, or compliance-heavy surfaces — Walter is too playful
+- Power-tool or data-dense surfaces where personality slows the user down
+
+---
+
+### Abby Covert (`abby-covert`)
+
+- **Domain:** ux | **Depth:** stub
+
+**Solves (brownfield — existing UI):**
+- Content exists but users can't make sense of how it relates
+- Labels are inconsistent across surfaces; same thing has different names
+- Information architecture is a mess but team can't see it
+
+**Solves (greenfield — 0→1 design):**
+- Starting a content-heavy or knowledge-base product where taxonomy must precede screens
+- Designing IA before any UI for a multi-domain app
+- Building a sense-making system where labeling discipline is a first-class concern
+- Designing a product where 'naming things consistently' will be a recurring discipline
+
+**Anti-patterns (when NOT to channel):**
+- Single-screen or single-task tools
+- Pure visual or motion work
+
+---
+
+### Alan Cooper (`alan-cooper`)
+
+- **Domain:** ux | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- Existing UI exposes the system's structure when users want their workflow
+- Power users keep retracing the same multi-step path through the current UI
+- Persona research surfaces a goal but the existing UI optimizes for novice exploration
+- App is feature-rich but each user wants only one slice for their job
+
+**Solves (greenfield — 0→1 design):**
+- Designing a workflow-heavy app for returning users with named goals
+- Building a product where personas + scenarios should drive the UI before any screen sketch
+- Planning a tool for power users who need their job-specific slice surfaced from day one
+- Mid-complexity product where personas keep early design decisions grounded in real users
+
+**Anti-patterns (when NOT to channel):**
+- Truly simple consumer apps — Cooper overweights workflow modeling
+- First-launch novelty experiences — goal-directed assumes a returning user
+- Pure marketing or storytelling surfaces
+
+---
+
+### Anthropic frontend-design skill — BASELINE COMPOSES-WITH, NOT A LUMINARY
+
+Anthropic's `frontend-design` skill is the implicit baseline default adopters get from plain Claude. Bassclef's authoring skills (`/frontend-design`, `/riff-prototypes`, `/launch`, `/visual-review`) declare `composes_baseline: anthropic-frontend-design` in their frontmatter and extend the baseline with luminary-pair commitment, design tokens, and visual-review discipline.
+
+This baseline is not a luminary catalog entry; it ships with the upstream skill catalog Anthropic publishes. Bassclef extends; bassclef does not author the baseline. Adopters firing plain Claude (no bassclef substrate) inherit the baseline's typography + color + motion + spatial-composition guidance for free.
+
+See `.claude/skills/frontend-design/SKILL.md` for bassclef's baseline composition declaration and the specific extensions bassclef adds.
+
+---
+
+### Apple Human Interface Guidelines (HIG) (`apple-hig`)
+
+- **Domain:** visual | **Depth:** stub
+
+**Solves (brownfield — existing UI):**
+- Existing app fights iOS / macOS conventions instead of feeling native
+- Design has too many ideas competing for attention; restraint would clarify
+- Brand identity is overpowering platform conventions in the current UI
+- Polish is missing — corners, transitions, depth feel cheap
+
+**Solves (greenfield — 0→1 design):**
+- Designing an app for one specific Apple platform where native fit is a value
+- Building a product where restraint and platform conventions matter more than expression
+- Planning a polished consumer app on iOS / macOS / iPadOS
+- Designing for a platform whose users expect HIG-shaped affordances by default
+
+**Anti-patterns (when NOT to channel):**
+- Cross-platform brand-led design where native fit isn't the goal
+- Highly differentiated brand surfaces — Apple HIG forces convention over voice
+
+---
+
+### BJ Fogg (`bj-fogg`)
+
+- **Domain:** ux | **Depth:** stub
+
+**Solves (brownfield — existing UI):**
+- Users sign up but don't return; existing onboarding doesn't form a habit
+- Notifications fire but don't drive the right action
+- Existing onboarding tour overwhelms instead of landing a tiny first success
+
+**Solves (greenfield — 0→1 design):**
+- Designing a behavior-change product (fitness, habit, learning) where motivation × ability × trigger must align
+- Building an onboarding flow that lands a tiny first success on day one
+- Planning a product whose retention will depend on habit formation
+- Designing notification logic where the right trigger fires the right action from launch
+
+**Anti-patterns (when NOT to channel):**
+- Power-tool surfaces where the user already has motivation
+- B2B or compliance-heavy surfaces where behavior change isn't the goal
+
+---
+
+### Brad Frost (`brad-frost`)
+
+- **Domain:** visual | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- Existing component library is a flat dump with gaps in mid-level molecules and organisms
+- Designers and engineers describe components inconsistently
+- Pattern library exists but doesn't compose into actual pages
+
+**Solves (greenfield — 0→1 design):**
+- Designing a fresh design system from atoms upward
+- Building a component hierarchy that will scale across many surfaces
+- Planning a system where pattern composition is a first-class discipline from day one
+- Designing a token + component + template + page taxonomy for a new product
+
+**Anti-patterns (when NOT to channel):**
+- Single-screen prototypes — atomic design is for systems
+- Marketing one-offs or campaign pages
+
+---
+
+### Dieter Rams (`dieter-rams`)
+
+- **Domain:** visual | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- Existing design has accumulated features and visual elements that don't earn their place
+- Each component does too much; honest functional expression would simplify
+- Aesthetic feels dated because of decoration, not because of underlying function
+
+**Solves (greenfield — 0→1 design):**
+- Designing a product where less-but-better is the explicit value
+- Building a tool whose visual identity should follow function, not lead it
+- Planning a long-lived product where ruthless reduction will be a recurring discipline
+- Designing a fresh product where every element must justify its presence from day one
+
+**Anti-patterns (when NOT to channel):**
+- Maximalist or expressive brand surfaces
+- Storytelling or narrative-driven surfaces
+
+---
+
+### Don Norman (`don-norman`)
+
+- **Domain:** ux | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- Users keep clicking the wrong thing or missing a button; affordances are unclear
+- Interface error messages punish the user rather than help them recover
+- Mental model and system model have diverged — users predict wrong outcomes
+- Mode visibility is missing; users don't know what state they're in
+
+**Solves (greenfield — 0→1 design):**
+- Designing a new control surface where affordance language must be self-evident from first encounter
+- Building a tool whose error model should help users recover, not punish
+- Planning a product where mappings between control and effect must feel natural from day one
+- Designing a system where visibility of state is a first-class concern
+
+**Anti-patterns (when NOT to channel):**
+- Designs whose primary value is delight or emotional resonance — Norman optimizes for clarity, not joy
+- Highly abstract or conceptual UIs where direct manipulation isn't the model
+
+---
+
+### Edward Tufte (`edward-tufte`)
+
+- **Domain:** visual | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- UI shows many numbers or trends in compressed space and legibility is breaking down
+- Dashboard has accumulated decoration and chart-junk; signal is buried
+- Multi-dimensional data displays are letting one dimension drown out others
+- Users decode the chart before understanding the message
+
+**Solves (greenfield — 0→1 design):**
+- Planning a dashboard, financial report, or analytics UI that must show dense data clearly from day one
+- Designing a surface where multiple quantitative dimensions need to coexist without one drowning the others
+- Building a tool for domain experts who read data faster than narrative
+- Need small multiples or sparklines as the main display element in the new design
+
+**Anti-patterns (when NOT to channel):**
+- Sparse, narrative-heavy surfaces — Tufte over-compresses
+- Consumer-emotional or marketing surfaces — Tufte reads as cold
+- First-time onboarding flows — density assumes domain familiarity
+
+---
+
+### Ellen Lupton (`ellen-lupton`)
+
+- **Domain:** visual | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- Page reads as a wall of undifferentiated text
+- Visual hierarchy is broken — every element claims equal importance
+- Typography is inconsistent across pages or feels chosen by accident
+- Reading rhythm is broken by mis-set line height, measure, or contrast
+
+**Solves (greenfield — 0→1 design):**
+- Designing a content-heavy product where reading rhythm is core to the experience
+- Setting type scale and hierarchy from scratch for a new brand or system
+- Planning a long-form or editorial surface where typeface choice carries voice
+- Building a fresh product where brand voice should come through in the typeface from day one
+
+**Anti-patterns (when NOT to channel):**
+- Pure data-density surfaces — Tufte is a better fit than Lupton
+- Engineering-internal tools where readability beats voice
+
+---
+
+### Erika Hall (`erika-hall`)
+
+- **Domain:** ux | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- Team is shipping based on assumptions, not evidence about users
+- Research is happening but findings don't reach decisions
+- Discovery work is being skipped because of velocity pressure
+
+**Solves (greenfield — 0→1 design):**
+- Starting a new product and need contextual inquiry to ground the thesis
+- Designing discovery research before any UI is sketched
+- Building a research practice into the team's discipline from day one
+- Designing a product where 'we don't know what users actually do' is the first risk to retire
+
+**Anti-patterns (when NOT to channel):**
+- Late-stage refinement work where research is already done
+- Engineering-only surfaces where users aren't directly relevant
+
+---
+
+### Google Material Design (`google-material`)
+
+- **Domain:** visual | **Depth:** stub
+
+**Solves (brownfield — existing UI):**
+- Existing component library lacks systematic spacing, color, type tokens
+- Cross-platform consistency is breaking; surfaces look like different products
+- Theming and dynamic color aren't working across user preferences
+
+**Solves (greenfield — 0→1 design):**
+- Designing a multi-surface system where systematic tokens and density tiers are needed from the start
+- Building cross-platform consistency without bespoke per-platform polish
+- Planning a product where theming + accessibility are core, not retrofitted
+- Designing component density tiers (compact / standard / comfortable) into the system from day one
+
+**Anti-patterns (when NOT to channel):**
+- Highly distinctive brand surfaces — Material genericizes
+- Premium or differentiated visual identity work
+
+---
+
+### Jakob Nielsen (`jakob-nielsen`)
+
+- **Domain:** ux | **Depth:** stub
+
+**Solves (brownfield — existing UI):**
+- Existing UI needs structured expert evaluation against usability heuristics
+- Usability violations are happening but team has no checklist to catch them
+- Standardization across the product matters but discipline is loose
+
+**Solves (greenfield — 0→1 design):**
+- Building a new product and want heuristic review baked into the design discipline
+- Designing checkpoints where heuristic evaluation can fire before user testing
+- Planning a product where standardization across surfaces will be a measurable goal
+- Setting up an evaluation framework for a product about to launch
+
+**Anti-patterns (when NOT to channel):**
+- Generative or first-pass design — Nielsen evaluates, doesn't ideate
+- Brand or emotional surfaces where heuristics miss the point
+
+---
+
+### Jenifer Tidwell (`jenifer-tidwell`)
+
+- **Domain:** ux | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- Common interaction in current UI is being reinvented when proven patterns exist
+- Designer is choosing novel solutions where well-known answers are better
+- Existing design lacks shared vocabulary for interaction choices across team
+
+**Solves (greenfield — 0→1 design):**
+- Composing a new app from proven interaction patterns instead of inventing each one
+- Need a vocabulary to communicate interaction choices to engineering on a fresh build
+- Building complex flows; want to compose from named patterns first, novel last
+- Designing a multi-flow product where interaction patterns must be consistent from day one
+
+**Anti-patterns (when NOT to channel):**
+- Bleeding-edge novel interactions — Tidwell catalogs proven patterns, not invents new ones
+- Pure visual or brand-driven surfaces
+
+---
+
+### Jesse James Garrett (`jesse-james-garrett`)
+
+- **Domain:** ux | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- Project mixes strategy, scope, structure, skeleton, and surface decisions in one conversation
+- Surface decisions are over-determining structural choices in the existing UI
+- Team can't agree on which decisions belong at which level
+
+**Solves (greenfield — 0→1 design):**
+- Starting a multi-surface product where the five planes should sequence design decisions
+- Building a UX strategy that decomposes work into orderable layers from day one
+- Planning a product where strategy precedes scope precedes structure precedes skeleton precedes surface
+- Designing a multi-month product where UX governance needs explicit decision-tier vocabulary
+
+**Anti-patterns (when NOT to channel):**
+- Tactical UI fixes where the five planes is overhead
+- Single-page or single-screen work
+-   - **Strategy** — user needs + product objectives. What success means.
+-   - **Scope** — functional specifications + content requirements. What
+-   - **Structure** — interaction design + information architecture. How
+-   - **Skeleton** — interface design, navigation design, information
+-   - **Surface** — sensory design (visual, auditory). How it looks and
+
+---
+
+### Luke Wroblewski (`luke-wroblewski`)
+
+- **Domain:** ux | **Depth:** stub
+
+**Solves (brownfield — existing UI):**
+- Existing form has many fields and abandonment is high
+- Mobile experience is desktop-first squeezed into small screens
+- Input types, validation, and progressive disclosure aren't optimized for thumbs
+
+**Solves (greenfield — 0→1 design):**
+- Designing a mobile-first product where forms are core to the value
+- Planning input surfaces where progressive disclosure must be designed from the start
+- Building for mobile users where thumb-zone economy matters
+- Designing form flows where staged input (now / later / never-asked) is a first-class concern
+
+**Anti-patterns (when NOT to channel):**
+- Read-only data display — Wroblewski is for input
+- Desktop-power-tool surfaces where mobile isn't primary
+
+---
+
+### Peter Morville (`peter-morville`)
+
+- **Domain:** ux | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- Users can't find content that exists in the product
+- Information architecture has no consistent labeling or hierarchy
+- Search returns results but not the RIGHT results
+- Navigation grew organically and now no one knows the full structure
+
+**Solves (greenfield — 0→1 design):**
+- Designing a content-heavy product where findability will be core from day one
+- Planning the IA before screens for a multi-section app
+- Building search + browse surfaces where wayfinding is a first-class concern
+- Designing a product for an audience where findability matters more than discoverability
+
+**Anti-patterns (when NOT to channel):**
+- Single-screen tools or focused workflows — Morville is for multi-page IA
+- Brand or marketing surfaces where wayfinding isn't the job
+
+---
+
+### Sophia V. Prater (`sophia-prater`)
+
+- **Domain:** ux | **Depth:** full
+
+**Solves (brownfield — existing UI):**
+- Existing multi-entity app where users mentally model objects but UI exposes screens or processes
+- Same entity appears in many flows but isn't unified as a concept
+- Navigation doesn't reflect the domain's noun structure
+
+**Solves (greenfield — 0→1 design):**
+- Designing a CRUD-heavy or domain-rich product where entity relationships should drive the UI
+- Planning IA from the domain model first, not from process flows
+- Building an app where users will mentally manipulate objects and the UI should match from day one
+- Designing a multi-entity product where consistent entity expression matters across surfaces
+
+**Anti-patterns (when NOT to channel):**
+- Process-driven workflows where actions matter more than objects
+- Single-entity tools or marketing surfaces
+
+---
+
+### Steve Krug (`steve-krug`)
+
+- **Domain:** ux | **Depth:** stub
+
+**Solves (brownfield — existing UI):**
+- Existing interface forces users to read or think more than the task warrants
+- User testing keeps surfacing the same friction points but team can't see them
+- Self-evident affordances are missing in the current UI; users hesitate before every click
+- Navigation, labels, and structure aren't immediately obvious
+
+**Solves (greenfield — 0→1 design):**
+- Designing a consumer or low-engagement product where 'don't make me think' is the bar
+- Building a new public-facing surface where usability is the core differentiator
+- Planning a tool that needs to be self-evident from first encounter
+- Designing a product whose audience will not invest effort to learn the interface
+
+**Anti-patterns (when NOT to channel):**
+- Power-user tools where complexity is the value
+- Domain-expert surfaces where 'don't make me think' undersells the user
+
+---
+
+## How `/luminary recommend` consumes this
+
+The agent reads this aggregate as one of its signal sources when ranking
+luminaries against an operator's plain-English problem statement. The
+modality of the operator's input (brownfield refactor vs greenfield
+concept) determines which array is matched:
+
+- Operator input mentions "existing UI", "current product", "today's
+  app" → match against `solves_problems_brownfield` arrays
+- Operator input mentions "designing", "planning", "building",
+  "0→1", "from scratch" → match against `solves_problems_greenfield`
+  arrays
+- Ambiguous input → match against both, weighted by signal strength
+
+`anti_patterns` always subtract from a luminary's score when the
+operator's input matches an entry — regardless of modality.
+
+## Schema (per luminary file)
+
+```yaml
+solves_problems_brownfield:
+  - "Plain-English symptom statement (~80 chars)"
+  - "..."
+solves_problems_greenfield:
+  - "Plain-English opportunity statement (~80 chars)"
+  - "..."
+anti_patterns:
+  - "When NOT to channel (Welch INSTEAD-block)"
+  - "..."
+```
+
+All three fields are optional during backfill (LR6 onward). A luminary
+with no problem-pattern frontmatter doesn't appear in this aggregate
+but remains in the catalog for `/luminary` browsing.

package/dist/lite/standards/migration-discipline/active-record.md

@@ -0,0 +1,50 @@
+---
+tier: lite
+description: The ActiveRecord sibling of .claude/rules/schema-management.md.
+---
+
+# ActiveRecord (Rails) — migration discipline
+
+The ActiveRecord sibling of `.claude/rules/schema-management.md`. Loads when adopter's `tech_stack.orm` is `active-record`.
+
+## Non-negotiable rule
+
+**NEVER edit `db/schema.rb` (or `db/structure.sql`) by hand.** Those files are derived artifacts — Rails regenerates them after every migration. Hand-editing them ships drift the moment another developer runs `rails db:migrate`.
+
+## Workflow
+
+1. Generate the migration: `rails generate migration DescriptiveName field:type field:type`
+2. Review the generated file in `db/migrate/` — Rails generators are good but not infallible; manual edits often required for:
+   - Foreign keys + cascading deletes
+   - Add-index on large tables (`algorithm: :concurrently` for Postgres)
+   - Compound conditions on `add_column` (`null: false, default: ...`)
+3. Apply locally: `rails db:migrate`
+4. Commit the migration file AND the regenerated `db/schema.rb` (or `db/structure.sql`)
+5. On deploy, CI runs `rails db:migrate`
+
+## After DB reset
+
+1. `rails db:setup` (runs migrations + seeds)
+2. Or `rails db:create db:migrate db:seed`
+
+## After merging a branch with schema changes
+
+1. `rails db:migrate` — apply pending migrations
+2. Restart the Rails server — ActiveRecord caches schema metadata at boot
+3. Run the test suite (`bundle exec rspec` or `rails test`) — schema-coupled tests catch missed migrations
+
+## Drift check
+
+`rails db:migrate:status` lists every migration + its applied/pending state. Pending migrations = drift.
+
+## Common pitfalls
+
+- **`change_column` is one-way unless you write a reversible block** — manual `up` + `down` methods needed for non-reversible changes
+- **Large-table migrations block writes** — use `strong_migrations` gem to lint; index changes especially need `add_index :table, :col, algorithm: :concurrently` on Postgres
+- **`rake db:reset` in dev hides production migrations** — only re-runs from schema.rb; doesn't re-test migration files end-to-end
+
+## Sources
+
+- Rails Guides — Active Record Migrations (https://guides.rubyonrails.org/active_record_migrations.html)
+- strong_migrations gem (https://github.com/ankane/strong_migrations)
+- Rails discipline ported from Prisma shape; ActiveRecord's auto-regenerated schema.rb is the Ruby-ecosystem equivalent of Prisma client regeneration.

package/dist/lite/standards/migration-discipline/alembic.md

@@ -0,0 +1,43 @@
+---
+tier: lite
+description: The Alembic sibling of .claude/rules/schema-management.md for adopters using Alembic without SQLAlchemy ORM models (raw SQL migrations against a Python codebase).
+---
+
+# Alembic (standalone) — migration discipline
+
+The Alembic sibling of `.claude/rules/schema-management.md` for adopters using Alembic **without** SQLAlchemy ORM models (raw SQL migrations against a Python codebase). Loads when adopter's `tech_stack.orm` is `alembic`.
+
+For Alembic + SQLAlchemy autogen, see `sqlalchemy.md`.
+
+## Non-negotiable rule
+
+**NEVER apply DDL outside an Alembic revision.** Direct `psql` / `mysql` / `sqlite3` DDL in production bypasses the migration audit trail.
+
+## Workflow
+
+1. Author a migration: `alembic revision -m "descriptive_name"` (no `--autogenerate` — you write the SQL by hand)
+2. Edit the generated file in `versions/` — populate `upgrade()` + `downgrade()` with `op.execute(text("..."))` or `op.create_table(...)` calls
+3. Apply locally: `alembic upgrade head`
+4. Test the downgrade path: `alembic downgrade -1`, then `alembic upgrade head`
+5. Commit the migration file
+6. On deploy, CI runs `alembic upgrade head`
+
+## After merging a branch with schema changes
+
+1. `alembic upgrade head` — apply pending migrations locally
+2. Verify DB shape matches expectations (Alembic doesn't model anything; the schema lives in DDL)
+
+## Drift check
+
+Alembic doesn't auto-detect drift in standalone mode. The session-start hook compares `alembic current` against the latest revision in `versions/`. If they diverge, prompt to upgrade.
+
+## Common pitfalls
+
+- **Writing migrations that read application data** — migrations should be idempotent and avoid coupling to app-side queries; data backfills go in separate scripts
+- **Skipping downgrade implementation** — rollback path is mandatory for prod-grade work
+- **Out-of-order revisions** — when parallel branches both create revisions from the same parent, merge with `alembic merge`
+
+## Sources
+
+- Alembic docs (https://alembic.sqlalchemy.org/en/latest/)
+- Standalone-Alembic discipline adapted from Prisma migration shape; the universal commitments are the same.