Merge branch 'main' into feat/seeder-build-pipeline

Author: mimartin12

.claude/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing Claude Context to This Repo
+
+Every time you catch Claude making the same mistake twice, explain the same convention in chat, or hand a teammate a mental map they didn't have — that's knowledge worth encoding. This guide covers what belongs in this repo's `.claude/`, where to put it, and how to land it alongside the code it describes.
+
+## When to contribute here vs. elsewhere
+
+Ask: **is this knowledge specific to this codebase, or generic enough to work across repos?**
+
+- **Specific to this codebase** → contribute here, in `.claude/`.
+  Example: "how we add a new cipher type," "how our feature-flag system works."
+- **Generic, reusable across repos** → [`bitwarden/ai-plugins`](https://github.com/bitwarden/ai-plugins) — persona plugins (e.g., a code-review agent), tool integrations, or shared utilities.
+
+When unsure, keep it here. Promoting up to `ai-plugins` later is easier than pulling it back — see its [CONTRIBUTING.md](https://github.com/bitwarden/ai-plugins/blob/main/CONTRIBUTING.md) when you're ready.
+
+## Choose scope, then shape
+
+### 1. Scope — where does it apply?
+
+This is a monorepo. Claude loads every `CLAUDE.md` and `CLAUDE.local.md` by [walking up from the working directory](https://code.claude.com/docs/en/memory#how-claude-md-files-load) — looking in each ancestor directly, not in a nested `.claude/` subdirectory. Files below the working directory (including nested `.claude/skills/`) are loaded lazily when Claude reads into that subtree. Use that hierarchy:
+
+- **Applies everywhere in this repo** → root `CLAUDE.md` or `.claude/skills/`
+- **Applies only within one app, library, utility, or subtree** → nested `CLAUDE.md` or `.claude/skills/` in that directory
+
+Push rules as deep as they'll go — keeping app-specific rules local saves context for everyone else's sessions, not just yours.
+
+For rules that should apply only to certain file types (e.g., all `*Controller.cs` files), use [`.claude/rules/<name>.md` with a `paths:` frontmatter glob](https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/) instead of a nested `CLAUDE.md`.
+
+### 2. Shape — how should Claude use it?
+
+| You want to…                                            | Use                                                                                              |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| State a rule Claude must always follow in its scope     | `CLAUDE.md`                                                                                      |
+| State a rule that applies only to certain file globs    | `.claude/rules/<name>.md` with `paths:` frontmatter                                              |
+| Teach a procedure Claude invokes on demand              | `.claude/skills/<name>/SKILL.md`                                                                 |
+| Give Claude a specialized subagent with its own context | `.claude/agents/<name>.md` (YAML frontmatter; `name` + `description` required)                   |
+| Add a user-invocable slash command                      | `.claude/commands/<name>.md`                                                                     |
+| Trigger a shell script on a Claude Code event           | _We have them, but no strict project enforcement yet — register yours in `settings.local.json`._ |
+
+Rule of thumb: **if Claude only needs it sometimes, it's a skill.** Once a `CLAUDE.md` loads, it stays in context for the rest of the session — keep each one lean, especially the root.
+
+## Security conventions
+
+Skills and agents that touch vault data, authentication, or cryptography must use Bitwarden's [Core Vocabulary](https://contributing.bitwarden.com/architecture/security/definitions) (Vault Data, Protected Data, Secure Channel, etc.) and re-state the zero-knowledge invariant inline. **Subagents run in a fresh context** and do not inherit this repo's `CLAUDE.md` — include the relevant definitions directly in the agent's system prompt.
+
+## What good contributions look like
+
+- **Grounded in the code.** Real files, real patterns, real commands.
+  If it could apply to any repo, it belongs in `ai-plugins`.
+- **Describes the "what" and "why," not the "who."**
+  Avoid team-persona framing. Describe the domain and its constraints; the team is an implementation detail.
+- **Short and specific.**
+  2,000 words of general advice isn't a skill.
+- **Active voice, direct language.**
+  "Invoke this skill when..." — not "This skill may be invoked when..."
+- **Reviewed like code.**
+  Teams of domain experts own `.claude/` in their areas — they're the ones shaping how Claude behaves for everyone who works there, so treat changes with the same seriousness as source.
+
+## Anti-patterns
+
+- **Team-persona agents** ("Team ABC engineer").
+  If a team's process is unique enough to warrant a persona, that's an SDLC signal to address, not a persona to encode.
+- **Root-level rules that only matter in one subtree.**
+  If it applies to `util/Seeder` only, put it in `util/Seeder/CLAUDE.md`.
+- **Duplicating `ai-plugins` content.**
+  Check existing plugin skills before writing a new one.
+- **Generic advice disguised as repo-local knowledge.**
+  "Write good tests" isn't repo-specific.
+  "Our integration tests must hit a real database because…" is.
+
+## Building a contribution
+
+The Claude Code ecosystem moves fast — last session's habits may already be out of date. Here's the workflow we follow.
+
+### 1. Start with the canonical docs
+
+A quick refresh before you begin goes a long way — the rules shift more often than you'd think:
+
+- [How Claude Code Works](https://code.claude.com/docs/en/how-claude-code-works) — the mental model.
+- [Best Practices for Claude Code](https://code.claude.com/docs/en/best-practices) — what Anthropic recommends.
+- [Extend Claude Code](https://code.claude.com/docs/en/features-overview) — what you can build (skills, agents, commands, hooks).
+- [The Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) - a must read for skill building
+
+### 2. Survey the landscape
+
+A quick skim of both goes a long way:
+
+- This repo's [`.claude/`](.) tree.
+- [`bitwarden/ai-plugins`](https://github.com/bitwarden/ai-plugins).
+
+Try to match the voice you see. "Invoke when the user asks to X" — not "This skill may be invoked when X." Direct, active, specific. Your contribution should read like the neighbors.
+
+### 3. Build iteratively
+
+When you're authoring a skill, start with `/skill-creator:skill-creator`. It runs an iterative loop — draft → test against evals → review outputs → refine — with benchmark stats and a side-by-side reviewer. You end up with a skill that's been exercised against concrete inputs before you open the PR.
+
+For agents, commands, hooks, and `CLAUDE.md` entries, start from an existing one in the repo and adapt it. No need to invent a new structure when a neighbor already solves the shape problem.
+
+### 4. Validate before you push
+
+- Run a local Bitwarden Claude Code review with `/bitwarden-code-review:code-review-local` — it writes findings to files so you can fix them before pushing, without posting anything to GitHub.
+- When you raise the PR, apply the `ai-review` label. Our reusable GitHub workflow watches for it and runs a Claude Code review automatically; without the label, the review doesn't fire.

.claude/skills/implementing-dapper-queries/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: implementing-dapper-queries
+description: Implementing Dapper repository methods and stored procedures for MSSQL at Bitwarden. Use when creating or modifying Dapper repositories, writing stored procedures, or working with MSSQL-specific data access in the server repo. Also use when writing MSSQL migration scripts under `util/Migrator/DbScripts/` or touching SSDT schema under `src/Sql/dbo/`.
+---
+
+## Repository Pattern
+
+All Dapper implementations live in `src/Infrastructure/Dapper/Repositories/`. Each repository class implements an interface from `src/Core/` and uses stored procedures for all database operations. The repository method is intentionally thin — it maps C# parameters to SQL parameters and maps result sets back to domain objects.
+
+### Stored procedures over inline SQL
+
+The default pattern is stored procedures for all Dapper database operations. Some exceptions exist where inline SQL is used — these are provided automatically by the repository base class and parent patterns, not written ad-hoc in individual repository methods.
+
+## Workflow
+
+1. **Define/update the stored procedure** in `src/Sql/dbo/Stored Procedures/` — use plain `CREATE PROCEDURE` (SSDT syntax)
+2. **Create a migration script** in `util/Migrator/DbScripts/` that deploys it — use `CREATE OR ALTER PROCEDURE` (idempotent)
+3. **Implement the repository method** in `src/Infrastructure/Dapper/Repositories/` using `DapperServiceProvider` to call the procedure
+4. **Write integration tests** using `[DatabaseData]` attribute
+
+The stored procedure is the source of truth for MSSQL query behavior. The Dapper repository method is thin — it maps parameters and results.
+
+### Stored procedure naming convention
+
+Procedures follow `{Entity}_{Action}` pattern: `User_Create`, `Cipher_ReadManyByUserId`, `Organization_DeleteById`. Tooling and code generation rely on this convention to map repository methods to their procedures.
+
+## Key Decisions That Trip Up AI Assistants
+
+### `CREATE OR ALTER` vs `CREATE PROCEDURE` — depends on file location
+
+Bitwarden maintains two copies of every stored procedure in different contexts with different toolchain constraints:
+
+| Context                | Location                         | Required syntax             |
+| ---------------------- | -------------------------------- | --------------------------- |
+| **SSDT schema source** | `src/Sql/dbo/Stored Procedures/` | `CREATE PROCEDURE` (plain)  |
+| **Migration script**   | `util/Migrator/DbScripts/`       | `CREATE OR ALTER PROCEDURE` |
+
+**Why they differ:**
+
+- **SSDT projects** do not support `CREATE OR ALTER` — using it produces build errors. SSDT manages object lifecycle through its own deployment model, so each source file must contain a bare `CREATE PROCEDURE`.
+- **Migration scripts** must be idempotent because they may be re-run. `CREATE OR ALTER` works whether the procedure exists or not. Never use bare `CREATE PROCEDURE` in a migration.
+
+### SSDT table files require `GO` batch separators
+
+In `src/Sql/dbo/Tables/`, SSDT requires a `GO` batch separator between `CREATE TABLE` and any subsequent `CREATE INDEX` or `CREATE NONCLUSTERED INDEX` statements.
+
+```sql
+-- CORRECT — GO separates DDL statements for SSDT
+CREATE TABLE [dbo].[Example] (
+    [Id] UNIQUEIDENTIFIER NOT NULL,
+    [Name] NVARCHAR(256) NOT NULL,
+    CONSTRAINT [PK_Example] PRIMARY KEY CLUSTERED ([Id] ASC)
+)
+GO
+
+CREATE NONCLUSTERED INDEX [IX_Example_Name]
+    ON [dbo].[Example] ([Name] ASC)
+GO
+```
+
+### New parameters must be nullable with defaults
+
+When adding parameters to existing stored procedures, always use `@NewParam DATATYPE = NULL`. Existing callers don't pass the new parameter — without a default, they break.
+
+### NOT NULL columns: use inline defaults, not ALTER-UPDATE-ALTER
+
+Adding a NOT NULL column by first adding it nullable, updating all rows, then altering to NOT NULL causes a full table scan. Instead, use `ADD [Column] INT NOT NULL CONSTRAINT DF_Table_Column DEFAULT 0` — this is a metadata-only operation in SQL Server. **This is the single most common mistake AI assistants make with Bitwarden migrations.**
+
+### Never create indexes on large tables in migration scripts
+
+Creating indexes on `dbo.Cipher`, `dbo.OrganizationUser`, or other large tables in migration scripts can cause outages. Never specify `ONLINE = ON` in scripts — production handles this automatically, and the option fails on unsupported SQL Server editions. Large index operations belong in `DbScripts_manual`.
+
+### Use defaults only for numeric types
+
+Use defaults for `BIT`, `TINYINT`, `INT`, `BIGINT`. Never use defaults for `VARCHAR`, `NVARCHAR`, or MAX types. SQL Server handles these differently and defaults on strings create unexpected behavior with EF Core migrations.
+
+### Views require metadata refresh
+
+After modifying a table, any views that reference it have stale metadata. Call `sp_refreshview` on affected views. After altering views, call `sp_refreshsqlmodule` on dependent procedures. This is the most frequently forgotten step.
+
+### GUID columns use `UNIQUEIDENTIFIER`
+
+All entity IDs are `UNIQUEIDENTIFIER` populated by `CoreHelpers.GenerateComb()` in application code, not by SQL Server. Never use `NEWID()` or `NEWSEQUENTIALID()` in stored procedures.
+
+## EF Parity Requirement
+
+Every stored procedure's behavior must be exactly replicated in the EF Core implementation. When writing a new stored procedure, think about how the EF implementation will reproduce the same filtering, ordering, and side effects. If a stored procedure does something complex (e.g., conditional updates, multi-table operations), document the expected behavior clearly so the EF implementation can match it.
+
+## Critical Rules
+
+These are the most frequently violated conventions. Claude cannot fetch the linked docs at runtime, so these are inlined here:
+
+- **`SET NOCOUNT ON`** at the start of every stored procedure
+- **Parameter naming:** `@ParamName` in PascalCase, matching C# property names
+- **Migration scripts must be idempotent** — use `CREATE OR ALTER` in `util/Migrator/DbScripts/`; use plain `CREATE PROCEDURE` in SSDT source (`src/Sql/dbo/`)
+- **Constraint naming:** `PK_TableName`, `FK_Child_Parent`, `IX_Table_Column`, `DF_Table_Column`
+- **Stored procedure file naming:** one procedure per file, named `{Entity}_{Action}.sql`
+
+## Examples
+
+### Stored procedure creation — SSDT source vs migration script
+
+```sql
+-- SSDT source file: src/Sql/dbo/Stored Procedures/User_ReadById.sql
+-- Use plain CREATE PROCEDURE (SSDT does not support CREATE OR ALTER)
+CREATE PROCEDURE [dbo].[User_ReadById]
+    @Id UNIQUEIDENTIFIER
+AS
+BEGIN
+    SET NOCOUNT ON
+    SELECT * FROM [dbo].[User] WHERE [Id] = @Id
+END
+```
+
+```sql
+-- Migration script: util/Migrator/DbScripts/YYYY-MM-DD_00_AddUser_ReadById.sql
+-- Use CREATE OR ALTER for idempotency
+CREATE OR ALTER PROCEDURE [dbo].[User_ReadById]
+    @Id UNIQUEIDENTIFIER
+AS
+BEGIN
+    SET NOCOUNT ON
+    SELECT * FROM [dbo].[User] WHERE [Id] = @Id
+END
+```
+
+### Adding a NOT NULL column
+
+```sql
+-- CORRECT — metadata-only operation, no table scan
+ALTER TABLE [dbo].[Organization]
+    ADD [UseCustomPermissions] BIT NOT NULL CONSTRAINT DF_Organization_UseCustomPermissions DEFAULT 0
+
+-- WRONG — causes full table scan on large tables
+ALTER TABLE [dbo].[Organization] ADD [UseCustomPermissions] BIT NULL
+UPDATE [dbo].[Organization] SET [UseCustomPermissions] = 0
+ALTER TABLE [dbo].[Organization] ALTER COLUMN [UseCustomPermissions] BIT NOT NULL
+```
+
+### Adding parameters to existing procedures
+
+```sql
+-- CORRECT — existing callers won't break
+CREATE OR ALTER PROCEDURE [dbo].[Cipher_Create]
+    @Id UNIQUEIDENTIFIER,
+    @NewField NVARCHAR(MAX) = NULL  -- default protects existing callers
+
+-- WRONG — breaks all existing callers immediately
+CREATE OR ALTER PROCEDURE [dbo].[Cipher_Create]
+    @Id UNIQUEIDENTIFIER,
+    @NewField NVARCHAR(MAX)  -- no default = required parameter
+```
+
+## Further Reading
+
+- [SQL code style](https://contributing.bitwarden.com/contributing/code-style/sql/)
+- [Database migrations (MSSQL)](https://contributing.bitwarden.com/contributing/database-migrations/mssql)