opencode-skills-collection 3.1.9 → 3.1.11

package/bundled-skills/drizzle-migration-conflict/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: drizzle-migration-conflict
+description: "Diagnose, repair, and prevent Drizzle Kit migration conflicts involving generated SQL, snapshots, journals, merge queues, and team workflows."
+category: databases
+risk: critical
+source: community
+source_repo: chaunsin/agent-skills
+source_type: community
+date_added: "2026-06-29"
+author: chaunsin
+tags: [drizzle, migrations, database, ci, merge-conflicts]
+tools: [git, python, rg]
+license: "Apache-2.0"
+license_source: "https://github.com/chaunsin/agent-skills/blob/master/LICENSE"
+---
+
+# Drizzle Migration Conflict
+
+Use this skill to help a user diagnose, repair, and prevent Drizzle Kit migration conflicts in a
+multi-developer repository. Drizzle migrations encode both SQL and migration snapshots, so the safe
+answer depends on the current migration directory shape, the Drizzle Kit version, and the git state.
+
+## When to Use This Skill
+
+- Use when Drizzle migration files, `_journal.json`, or `snapshot.json` conflict after a pull, merge, rebase, or PR update.
+- Use when `drizzle-kit check` reports non-commutative migrations or migration folder conflicts.
+- Use when a team wants a safe repair flow for generated Drizzle migrations after schema changes converge.
+- Use when designing CI or merge-queue policy to prevent repeated Drizzle migration conflicts.
+
+## Safety rules
+
+- Start in read-only diagnosis mode unless the user explicitly asks to fix files.
+- Do not run `drizzle-kit migrate`, `drizzle-kit push`, database seed scripts, or any command that
+  connects to a live database unless the user explicitly requests it and the target is clear.
+- Treat `drizzle-kit check`, project typechecks, and tests as command execution that may load project
+  config, environment variables, or scripts. Inspect scripts/config first, and require an explicit
+  non-production or disposable target before any DB-backed validation.
+- Do not delete migration files, rewrite `_journal.json`, or run `git checkout --ours`,
+  `git checkout --theirs`, `git restore`, or `rm` unless the user has confirmed the exact side and
+  files to change.
+- Do not recommend `drizzle-kit push` as the production solution for migration conflicts; it skips
+  the auditable migration history that teams need.
+- Treat `--ignore-conflicts` as an exception for a known false positive, not as the normal fix.
+- Preserve schema source code changes unless the user explicitly asks to discard them. Conflict
+  repair normally discards generated migrations and regenerates them from the merged schema.
+- If `ours` and `theirs` could mean different branches depending on merge direction, ask the user to
+  identify the parent branch before suggesting checkout commands.
+
+## Required references
+
+- Read `references/sources.md` when the answer depends on current Drizzle behavior, official
+  guidance, or one of the preserved external links.
+- Read `references/conflict-resolution.md` before recommending a repair flow.
+- Read `references/ci-policy.md` before proposing CI, merge queue, or team workflow changes.
+- Read `references/report-template.md` before writing a diagnostic report.
+
+## Source references
+
+The full list of official docs, Drizzle GitHub discussions, community scripts, and merge-queue
+references lives in `references/sources.md` with trust levels and caveats. Read that file whenever
+the answer depends on current Drizzle behavior. Re-verify the official docs and the most relevant
+discussion when the project's `drizzle-kit` major version changes, since migration internals
+(snapshot format, journal shape, `drizzle-kit check` semantics) have shifted between releases.
+
+## Mode selection
+
+Classify the task first:
+
+1. **Diagnose** - The user has a conflict or failed `drizzle-kit check` and wants to understand it.
+2. **Repair** - The user explicitly asks to fix or regenerate migration files.
+3. **CI hardening** - The user wants to prevent future conflicts in PRs or merge queues.
+4. **Explain** - The user wants a conceptual answer or a team playbook.
+
+When the mode is not explicit, choose Diagnose.
+
+Each mode unlocks a specific set of actions. Do not cross these boundaries without an explicit upgrade:
+
+- **Diagnose** - read-only only. Run `git status`, `git ls-files -u`, the helper script, and file
+  inspection. Do not run `drizzle-kit check`, typechecks, tests, or any write command. Report
+  findings and the proposed repair path, but do not execute it.
+- **Repair** - adds file writes and `drizzle-kit generate`/`check` execution, each gated by the
+  Safety rules and explicit confirmation of the exact files and side (`ours`/`theirs`) to change.
+- **CI hardening** - adds proposing or editing CI/workflow files. Do not run migration commands
+  against the user's database to validate the workflow; validate the workflow syntax and logic only.
+- **Explain** - conceptual only. No commands against the repo beyond optional read-only inspection.
+
+## Repository discovery
+
+Collect repo facts before giving commands:
+
+```bash
+git status --short
+git rev-parse --show-toplevel
+git rev-parse --abbrev-ref HEAD
+git ls-files -u
+rg --files -g 'drizzle.config.*' -g 'package.json' -g 'pnpm-lock.yaml' -g 'yarn.lock' -g 'package-lock.json'
+```
+
+Then inspect the relevant files:
+
+- `drizzle.config.*` for `out`, `schema`, dialect, and config shape.
+- `package.json` scripts for the project-approved `generate`, `check`, and `migrate` commands.
+- `package.json` dependencies or lockfile snippets for `drizzle-kit` and `drizzle-orm` versions.
+- The migration output directory, either from config or common names like `drizzle/`, `migrations/`,
+  or `src/db/migrations/`.
+
+If this skill's helper script is available, run it in read-only mode:
+
+```bash
+python3 <skill-dir>/scripts/check_drizzle_migrations.py --root .
+```
+
+Resolve `<skill-dir>` to the installed skill directory before running. Check these locations in order
+and use the first that contains `scripts/check_drizzle_migrations.py`:
+
+1. The target repository's vendored copy: `<repo-root>/skills/drizzle-migration-conflict`.
+2. The Claude Code skills directory: `~/.claude/skills/drizzle-migration-conflict`.
+3. Any other install location reported by the user's environment.
+
+If none of these resolve, fall back to the manual `git`/`rg` inspection commands above and tell the
+user the helper script was not found. Use `--config <file>` and `--migrations-dir <dir>` when the
+project has multiple Drizzle configs or outputs. The script never connects to a database and never
+writes files; it only reads migration directories and reports structural issues.
+
+## Migration structure decision
+
+Identify the structure before proposing a fix:
+
+- **Legacy structure**: `<out>/meta/_journal.json`, `<out>/meta/*_snapshot.json`, and root-level
+  migration SQL files such as `<out>/0003_name.sql`.
+- **Folder-based structure**: each migration is a directory containing `migration.sql` and
+  `snapshot.json`.
+- **Unknown or mixed structure**: stop and report ambiguity. Do not guess a destructive repair.
+
+## Recommended repair principles
+
+- Resolve schema source conflicts first. The regenerated migration must reflect the merged schema,
+  not one side's stale snapshot.
+- Treat the parent or target branch migration history as the source of truth when repairing a feature
+  branch after updating from that branch.
+- Prefer discarding and regenerating generated migration artifacts over hand-editing journal or
+  snapshot files.
+- After regeneration, validate in tiers: database-free structural checks first; then `drizzle-kit
+  check` only after confirming its config/env cannot point at production; then project tests only
+  after inspecting the scripts and any database targets.
+- If the user asks to apply changes, state exactly which files will be changed before performing the
+  write.
+
+## Output rules
+
+- Use the user's language when practical, but keep command snippets and file paths literal.
+- State the detected migration structure and selected mode.
+- Separate confirmed conflicts from assumptions and missing evidence.
+- Give a safe default path first, then optional automation or CI hardening.
+- For destructive steps, label them as "requires confirmation" and explain what will be lost.
+- Never echo secrets. When inspecting `drizzle.config.*`, `.env`, or environment variables, do not
+  include database URLs, passwords, tokens, or connection strings in the report. Reference them as
+  `<redacted>` or describe only whether they point at a production-like target.
+- Use the conclusion values from `references/report-template.md` for diagnostic reports:
+  `NO_CONFLICT_FOUND`, `SAFE_TO_REGENERATE`, `NEEDS_USER_CONFIRMATION`, or `BLOCKED_BY_AMBIGUITY`.
+
+## Limitations
+
+- This skill cannot guarantee that a regenerated migration is production-safe without review against the target database state and deployment process.
+- It does not run DB-backed migration commands unless the user explicitly confirms the target and the command.
+- It is focused on Drizzle Kit migration conflicts, not general schema design or application-query optimization.
+
+## Test prompts
+
+Use these prompts to validate the skill behavior:
+
+- "My Drizzle `_journal.json` and `0003_snapshot.json` conflict during merge. Tell me what to do."
+- "We upgraded to the migration folder layout and `drizzle-kit check` reports a non-commutative conflict."
+- "Design CI so our team stops merging broken Drizzle migrations."
+- "Can I solve this production Drizzle migration conflict with `drizzle-kit push`?"
+- "Use the links in the skill to re-check the current official Drizzle migration conflict guidance."
+- "We're halfway through moving from the legacy flat layout to folder-based migrations. How do we handle a conflict during the transition?"
+- "Our `drizzle.config.ts` sets `out` from `process.env.MIGRATIONS_DIR`, and the helper says no out directory was found. What now?"
+- "`drizzle-kit check` keeps failing on a migration we know commutes. Can we just always pass `--ignore-conflicts`?"

package/bundled-skills/drizzle-migration-conflict/references/ci-policy.md

@@ -0,0 +1,87 @@
+# CI and Team Policy
+
+Use this reference when the user wants to prevent Drizzle migration conflicts in pull requests,
+protected branches, or GitHub merge queues.
+
+## Recommended layers
+
+1. **Local developer habit**
+   - Pull or merge the parent branch before generating a migration.
+   - Generate migrations once schema source conflicts are resolved.
+   - Run `drizzle-kit check` only after confirming its config/env do not target production.
+2. **Pull request check**
+   - Run the project's normal static checks.
+   - Run `drizzle-kit check` or the package script that wraps it with explicit non-production config.
+   - Run the read-only helper script to catch legacy journal/snapshot mismatches.
+3. **Merge queue check**
+   - If GitHub merge queue is enabled, run the same check on `merge_group` events.
+   - Do not assume a successful PR check means the queued merge result is still conflict-free.
+
+## GitHub Actions skeleton
+
+Adapt package manager, config path, migration directory, and script location to the target
+repository. The helper script must be vendored or copied into the repository before CI can run it.
+Never point CI migration checks at production credentials.
+
+```yaml
+name: drizzle-migration-check
+
+on:
+  pull_request:
+  merge_group:
+
+jobs:
+  drizzle-migration-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - run: pnpm install --frozen-lockfile
+      # Run only with a non-production or disposable DATABASE_URL if the config requires one.
+      - run: pnpm exec drizzle-kit check --config drizzle.config.ts
+      # Example assumes the helper was copied to scripts/check_drizzle_migrations.py.
+      - run: python3 scripts/check_drizzle_migrations.py --root . --config drizzle.config.ts --migrations-dir drizzle
+```
+
+If the repository does not vendor this skill, copy the helper script into the repo or run an
+equivalent read-only check from the CI tooling repository. In multi-config repositories, pass the
+same config and matching migration directory to both Drizzle Kit and the helper script.
+
+The helper script exits with: `0` when all checked directories are clean, `1` when any error or
+warning issue is found, and `2` when no migration directory was discovered at all. A CI step that
+runs the script should fail the job on a non-zero exit, but treat exit `2` as "nothing to check"
+only if the repo is expected to have no Drizzle migrations; otherwise exit `2` usually means
+detection missed the migration directory and the config should be passed explicitly.
+
+## What merge queue does and does not solve
+
+Merge queue can serialize the final merge order and test a temporary merge result. It does not
+rewrite Drizzle migrations, re-run `drizzle-kit generate`, or choose which branch's snapshots are
+correct. The check should fail when generated migration history is inconsistent, then the developer
+updates the branch and regenerates migrations.
+
+## Policy recommendations
+
+- Require one migration-generation point per PR after schema conflicts are resolved.
+- Treat migration artifacts as generated but reviewable files: do not silently rewrite them in CI.
+- Require `drizzle-kit check` or an equivalent conflict check before merge.
+- In legacy projects, reject duplicate migration numbers and journal/snapshot drift.
+- In folder-based projects, reject incomplete migration directories and failed commutativity checks.
+- Keep production migration execution separate from PR validation.
+
+## When CI should fail
+
+Fail the job when any of these are true:
+
+- `_journal.json` contains duplicate `idx` or `tag` values.
+- A journal entry references a missing SQL file or snapshot.
+- Root SQL or snapshot files exist but are not referenced by the journal in a legacy output.
+- Migration files contain Git conflict markers.
+- A folder-based migration directory is missing `migration.sql` or `snapshot.json`.
+- `drizzle-kit check` reports a non-commutative migration conflict.

package/bundled-skills/drizzle-migration-conflict/references/conflict-resolution.md

@@ -0,0 +1,163 @@
+# Conflict Resolution Playbook
+
+Use this playbook after collecting repo facts. The goal is to preserve schema intent while replacing
+stale generated migration artifacts with a migration generated from the merged schema.
+
+## Decision tree
+
+1. Is the repository currently in a merge or rebase?
+   - Check `git status --short` and `git ls-files -u`.
+   - If yes, identify whether the user is merging the parent branch into a feature branch, rebasing a
+     feature branch, or merging a feature branch into the parent branch.
+2. Which migration structure is present?
+   - Legacy: `meta/_journal.json`, `meta/*_snapshot.json`, root SQL files.
+   - Folder-based: migration directories with `migration.sql` and `snapshot.json`.
+   - Mixed or unknown: stop and ask for the intended migration output path.
+   - Transitioning (legacy artifacts plus a partial move to folder-based): do not repair until the
+     user confirms the target structure. Treat the legacy artifacts and the folder-based artifacts
+     as one logical history only after the intended end state is clear; otherwise a repair could
+     discard the wrong side.
+3. Are schema source files already resolved?
+   - If not, resolve those first or tell the user the migration cannot be regenerated safely yet.
+4. Is the user asking for diagnosis or repair?
+   - Diagnosis stays read-only.
+   - Repair can include file changes only after the exact generated files to discard are understood.
+
+## Read-only inspection commands
+
+```bash
+git status --short
+git ls-files -u
+rg --files -g 'drizzle.config.*' -g 'package.json'
+rg -n "drizzle-kit|drizzle-orm|db:generate|db:check|migrate" package.json pnpm-lock.yaml yarn.lock package-lock.json 2>/dev/null
+python3 <skill-dir>/scripts/check_drizzle_migrations.py --root .
+```
+
+If `rg` is not available, use `find` and `grep` equivalents. Resolve `<skill-dir>` to the installed
+skill directory before running the helper. Check in order and use the first match that contains
+`scripts/check_drizzle_migrations.py`: the target repo's vendored
+`skills/drizzle-migration-conflict`, then `~/.claude/skills/drizzle-migration-conflict`, then any
+user-reported install location. If none resolve, fall back to the `git`/`rg` inspection commands
+above and tell the user the helper was not found.
+
+## Legacy structure repair
+
+Legacy Drizzle output usually looks like this:
+
+```text
+drizzle/
+  0000_initial.sql
+  0001_add_user.sql
+  meta/
+    _journal.json
+    0000_snapshot.json
+    0001_snapshot.json
+```
+
+Safe flow for a feature branch updated from the parent branch:
+
+1. Resolve schema source conflicts first.
+2. Keep the parent branch's migration history as the baseline.
+3. Discard generated migration files created on the feature branch after it diverged from the parent
+   branch.
+4. Re-run the project-approved `drizzle-kit generate` script from `package.json`.
+5. Validate the regenerated history.
+
+Do not hand-edit `_journal.json` or snapshot JSON unless the user explicitly asks for an emergency
+manual repair and accepts the risk. The next generated migration depends on those snapshots.
+
+### Ours/theirs warning
+
+`ours` and `theirs` change meaning with merge direction:
+
+| Situation | `ours` usually means | `theirs` usually means | Safe guidance |
+| --- | --- | --- | --- |
+| On feature branch, merging parent branch into it | current feature branch | parent branch being merged in | Parent branch is often `theirs`, but verify before checkout. |
+| On parent branch, merging feature branch into it | current parent branch | feature branch | Parent branch is often `ours`, but verify before checkout. |
+| Rebase | meaning can be unintuitive | meaning can be unintuitive | Avoid shorthand; use explicit branch/path restore if possible. |
+
+When in doubt, ask which branch should be the migration-history source of truth. Do not guess.
+
+## Folder-based structure repair
+
+Folder-based Drizzle output usually looks like this:
+
+```text
+drizzle/
+  20260618120000_add_user/
+    migration.sql
+    snapshot.json
+```
+
+Safe flow:
+
+1. Inspect the Drizzle config and env first, then run `drizzle-kit check` or the project script
+   wrapping it only with a non-production target.
+2. If it reports a non-commutative migration conflict, identify the conflicting migration and any
+   later migrations based on it.
+3. Remove or regenerate only the generated migration artifacts that are downstream of the conflict,
+   after user confirmation.
+4. Re-run `drizzle-kit generate` from the merged schema.
+5. Re-run the helper script, and re-run `drizzle-kit check` only after confirming the config/env
+   target is still non-production.
+
+Use `--ignore-conflicts` only for a known false positive after reviewing why the migrations commute
+or why the check is wrong. Include that decision in the report.
+
+## Validation after regeneration
+
+Run validation in tiers so the agent does not accidentally touch a live database or run arbitrary
+project scripts.
+
+### Database-free checks
+
+```bash
+python3 <skill-dir>/scripts/check_drizzle_migrations.py --root . --migrations-dir <migration-dir>
+```
+
+### Loads project config or environment
+
+Run `drizzle-kit check` only after inspecting `drizzle.config.*`, package scripts, and relevant env
+variables. Confirm that any database URL or credentials point to a non-production or disposable
+target before executing it. Work through this checklist before running the command:
+
+1. Read `drizzle.config.*` and note any `url`, `dbCredentials`, `credentials`, or connection fields.
+   Determine whether they are literal, read from `process.env`, or loaded via `dotenv`.
+2. Identify which env vars feed those fields (common names: `DATABASE_URL`, `DB_URL`,
+   `POSTGRES_URL`, `DRIZZLE_DATABASE_URL`). Check `.env`, `.env.local`, and the package script's
+   environment for their values without echoing secrets.
+3. If a value points at a production host (named `prod`/`production`, a managed cluster endpoint,
+   or a host the user identifies as live), stop and ask for a disposable target. Do not run the check.
+4. If `drizzle-kit check` needs a real connection for the configured dialect, prefer overriding the
+   URL inline with a disposable/local database, or use a config that disables connection (some
+   dialects allow a schema-only check). If neither is possible, fall back to the database-free
+   helper script and report that `drizzle-kit check` could not be run safely.
+5. Only after the target is confirmed non-production, run the project-approved check command.
+
+```bash
+# Project script names vary; inspect package.json first.
+# Override with a disposable DATABASE_URL only if the config requires a connection.
+DATABASE_URL=postgres://localhost/disposable pnpm exec drizzle-kit check --config <drizzle-config>
+```
+
+### Project tests
+
+Run typechecks or tests only after inspecting the script definitions. Tests may run migrations,
+connect to databases, mutate fixtures, or start services.
+
+```bash
+pnpm typecheck
+pnpm test
+```
+
+Avoid live database commands unless the user names a disposable database or explicitly requests a
+migration run.
+
+## Anti-patterns
+
+- Running `drizzle-kit push` to bypass migration history in production.
+- Keeping both sides' generated migrations and manually renumbering files without regenerating from
+  the merged schema.
+- Resolving `_journal.json` by accepting both sides without verifying SQL and snapshot pairs.
+- Using `git checkout --theirs drizzle/` without understanding merge direction.
+- Ignoring `drizzle-kit check` with `--ignore-conflicts` as the default team workflow.

package/bundled-skills/drizzle-migration-conflict/references/report-template.md

@@ -0,0 +1,69 @@
+# Report Template
+
+Use this template for diagnosis and repair recommendations. Keep reports short and evidence-based.
+
+## Conclusion values
+
+- `NO_CONFLICT_FOUND` - No migration conflict or structural inconsistency was found from available
+  evidence.
+- `SAFE_TO_REGENERATE` - The conflict is understood, schema source is resolved, and the recommended
+  next step is to discard generated artifacts and regenerate migrations.
+- `NEEDS_USER_CONFIRMATION` - A repair path exists, but a destructive step or branch-side decision
+  requires confirmation.
+- `BLOCKED_BY_AMBIGUITY` - The migration structure, source-of-truth branch, schema state, or
+  migration directory cannot be determined safely.
+
+## Template
+
+````markdown
+# Drizzle Migration Conflict Report
+
+Conclusion: <NO_CONFLICT_FOUND | SAFE_TO_REGENERATE | NEEDS_USER_CONFIRMATION | BLOCKED_BY_AMBIGUITY>
+Mode: <diagnose | repair | ci-hardening | explain>
+
+## Detected Structure
+- Migration directory: `<path>`
+- Structure: <legacy | folder-based | mixed | unknown>
+- Drizzle Kit version: <version or unable to verify>
+- Git state: <clean | dirty | active merge | active rebase | unable to verify>
+
+## Conflict State
+- <confirmed conflict or inconsistency with file paths>
+- <journal/snapshot/SQL mismatch, non-commutative check, or conflict marker evidence>
+
+## Recommended Path
+- <safe next step>
+- <why this path preserves schema intent and migration history>
+
+## Commands
+```bash
+# Read-only commands first.
+<commands>
+
+# Destructive commands only if confirmed by the user.
+<commands requiring confirmation>
+```
+
+## Files At Risk
+- `<path>` - <why it may be discarded or regenerated>
+
+## Validation
+- <drizzle-kit check or project script>
+- <helper script command>
+- <typecheck/test command if relevant>
+
+## Unable To Verify
+- <missing version, unavailable branch, unknown migration path, or external docs not refreshed>
+````
+
+## Reporting rules
+
+- Put destructive commands in a clearly labeled block.
+- Do not output `--ours` or `--theirs` commands unless the merge/rebase direction, source-of-truth
+  branch, and exact file paths are confirmed. Otherwise use `BLOCKED_BY_AMBIGUITY`.
+- If the project has multiple Drizzle configs, report each output independently.
+- If no conflict is found but the worktree is dirty, state that uncommitted files were not repaired.
+- Do not include clean checklist categories that are irrelevant to the user's conflict.
+- Redact secrets. Never include database URLs, passwords, tokens, or connection strings in the
+  report. When a config or env value matters, describe only whether it points at a production-like
+  target and write the value as `<redacted>`.

package/bundled-skills/drizzle-migration-conflict/references/sources.md

@@ -0,0 +1,51 @@
+# Source References
+
+Last verified: 2026-06-18.
+
+Use this file when an answer depends on upstream Drizzle behavior, community scripts, or CI platform
+behavior. Drizzle Kit migration internals can change, so prefer current official docs and the
+project's installed `drizzle-kit` version over memory when resolving a real conflict.
+
+## Official and semi-official Drizzle sources
+
+| Source | Link | Use | Trust level |
+| --- | --- | --- | --- |
+| Discussion 1104 | https://github.com/drizzle-team/drizzle-orm/discussions/1104 | Original team-collaboration conflict thread for legacy `_journal.json` and snapshot conflicts. Useful for understanding why parallel generated migrations diverge. | Drizzle GitHub discussion; useful but may include outdated comments. |
+| Discussion 2832 | https://github.com/drizzle-team/drizzle-orm/discussions/2832 | Migration folder structure redesign and reasoning. Use to understand why the old flat structure is git-hostile. | Drizzle GitHub discussion; design context may predate current release behavior. |
+| Discussion 5005 | https://github.com/drizzle-team/drizzle-orm/discussions/5005 | Commutative migration checking, `drizzle-kit check`, and conflict behavior in newer Drizzle Kit versions. | High value for current direction; verify against installed version. |
+| Discussion 5581 | https://github.com/drizzle-team/drizzle-orm/discussions/5581 | Practical parent-branch-as-source-of-truth repair workflow. | Community workflow; good playbook, still verify against repo state. |
+| Generate docs | https://orm.drizzle.team/docs/drizzle-kit-generate | How Drizzle Kit derives migrations from schema and snapshots. | Official docs. |
+| Check docs | https://orm.drizzle.team/docs/drizzle-kit-check | Migration consistency checking for team workflows. | Official docs. |
+| Migration overview | https://orm.drizzle.team/docs/migrations | General migration concepts and current official migration overview. | Official docs. |
+
+## Community scripts
+
+These scripts are reference material only. Do not copy their destructive behavior into a generic
+agent workflow without dry-run mode and explicit user confirmation.
+
+| Source | Link | Use | Caveat |
+| --- | --- | --- | --- |
+| Legacy undo script | https://gist.github.com/anthonyjoeseph/102c0e3ea8496fe111029a8b8a95cc3a | Shows a merge-time undo workflow for legacy Drizzle migration artifacts. | Assumes legacy structure and uses git/file operations that can discard local generated files. |
+| Legacy repair script | https://gist.github.com/anthonyjoeseph/6b99beb34d494acd1dfc83a192ed9388 | Detects duplicate legacy migration numbers and can repair by removing orphaned generated files. | `FORCE_FIX` is destructive; adapt only the read-only checks unless the user confirms. |
+| Earlier repair variant | https://gist.github.com/gburtini/7e34842c567dd80ee834de74e7b79edd | Useful for historical context and comparing conflict-detection logic. | Earlier variant had caveats fixed by later forks; do not rely on it alone. |
+
+## CI and merge queue sources
+
+| Source | Link | Use | Caveat |
+| --- | --- | --- | --- |
+| GitHub merge queue docs | https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue | Explains merge queue behavior and why required checks must also run for `merge_group` events. | Merge queue serializes merging; it does not regenerate Drizzle migrations by itself. |
+
+## Version-sensitive guidance
+
+Before giving high-confidence advice for a live repository:
+
+1. Check the local `drizzle-kit` version from `package.json` and the lockfile first.
+2. Check whether the migration output uses the legacy flat structure or the folder-based structure.
+3. If command execution is acceptable and dependencies are already installed, use a local-only
+   package-manager command. Prefer `pnpm exec drizzle-kit --version`,
+   `yarn exec drizzle-kit --version`, or `npm exec --no-install drizzle-kit -- --version`. Do not
+   use plain `npx` for version probing because it can download or resolve a different package.
+4. If online browsing is available and the user asks for current guidance, re-open the official docs
+   and the discussion most relevant to the installed version.
+5. If a local result conflicts with these sources, trust the local repository state and report the
+   mismatch explicitly.