Update mongock skills to add more examples

[jabrena]

User Story: Update Mongock skills to add migration-safety examples

As a maintainer of Java Enterprise cursor rules
I want to improve the Spring Boot, Quarkus, and Micronaut Mongock skills with richer migration examples and safety guidance
So that agents can recommend code-first MongoDB migrations that are framework-compatible, idempotent, testable, and safer for production data

Acceptance Criteria

See: skills-generator/src/test/resources/gherkin/skills/*-mongodb-migrations-mongock.feature

Notes

Apply the same improvement pattern used for Flyway issue #895:

• Add explicit Mongock antipattern guidance for unsafe data migrations.
• Add framework-specific examples for Spring Boot, Quarkus, and Micronaut.
• Cover safe rollout techniques similar to expand, migrate, contract, adapted to document migrations.
• Add testing guidance that verifies real Mongock execution, changelog records, and physical side effects.
• Keep edits in XML sources under skills-generator/src/main/resources/; do not edit generated skills/ directly.

Implementation targets:

• skills-generator/src/main/resources/skill-references/316-frameworks-spring-mongodb-migrations-mongock.xml
• skills-generator/src/main/resources/skill-references/416-frameworks-quarkus-mongodb-migrations-mongock.xml
• skills-generator/src/main/resources/skill-references/516-frameworks-micronaut-mongodb-migrations-mongock.xml
• Related skill indexes and Gherkin acceptance files for 316, 416, and 516

Gherkin Acceptance Criteria

Feature: Improve Mongock migration skill examples

@acceptance-test
Scenario: Add framework-specific Mongock migration examples
Given the Spring Boot, Quarkus, and Micronaut Mongock skills exist
When the Mongock skill references are updated
Then each skill includes framework-compatible dependency, runner, configuration, ChangeUnit, and testing examples
And each skill documents compatibility risks before recommending a runner or extension

@integration-test
Scenario: Document Mongock migration antipatterns
Given a skill user requests MongoDB data migrations with Mongock
When the skill reviews or proposes migration changes
Then it warns against editing applied ChangeUnits, non-idempotent updates, mutable domain-model coupling, unsafe startup backfills, hidden lock failures, and unverified runner assumptions

@integration-test
Scenario: Document safe document migration rollout techniques
Given a MongoDB schema or document-shape change needs production rollout
When the skill recommends a migration approach
Then it explains an expand, migrate, contract style workflow adapted for MongoDB documents
And it prefers small forward-only ChangeUnits with explicit verification over one destructive migration

@integration-test
Scenario: Verify migrations with real MongoDB execution
Given a project uses Mongock migrations
When tests are added or reviewed
Then the skill recommends real MongoDB verification with Testcontainers, Dev Services, or framework-native test support where feasible
And tests assert Mongock changelog execution plus at least one physical side effect

INVEST Validation

• Independent: The Mongock skill improvements can be delivered without changing the Flyway skills.
• Negotiable: Exact example wording and whether supplemental reference files are added can be refined during implementation.
• Valuable: Maintainers get safer, more practical Mongock guidance across all supported frameworks.
• Estimable: Scope is limited to three Mongock skill references, related indexes, Gherkin acceptance files, and local generated skill validation.
• Small: The work fits in one iteration because it improves existing skills rather than adding a new skill family.
• Testable: Completion can be verified with XML validation, skills-generator build, generated local skill inspection, and the listed acceptance prompts.

[jabrena]

Additional implementation ideas for Mongock-oriented guidance

To mirror the Flyway improvement while keeping the content idiomatic for MongoDB and NoSQL, the Mongock skills should focus less on ordered SQL scripts and more on document-shape evolution, idempotent data repair, runner compatibility, and operational safety.

1. Mongock antipatterns reference

Add explicit examples of risky Mongock migration patterns:

• Editing an already-applied @ChangeUnit instead of creating a new ordered change.
• Using repositories, domain records, DTOs, or framework mappers inside migrations, which can break old migrations after the application model evolves.
• Writing non-idempotent updates such as blind $inc, array appends, or broad updateMany operations without predicates that make reruns safe.
• Assuming transactions are available when MongoDB is running as a standalone node or when the migration touches large collections where transaction cost is too high.
• Running long backfills automatically during application startup without considering probes, rollout windows, lock duration, or partial completion recovery.
• Hiding lock acquisition failures in clustered deployments.
• Using framework-specific dependency coordinates without verifying runner compatibility first, especially Spring Boot 4.x, Quarkus platform alignment, and Micronaut runner availability.
• Testing only that the application context starts, without proving Mongock executed the expected changes.

2. NoSQL parallel-change workflow

Adapt the Flyway parallel-change idea to MongoDB document migrations:

• Expand: add new optional fields, new embedded structures, new collections, or new indexes while keeping old readers and writers working.
• Migrate: backfill documents incrementally with idempotent predicates, dual-write or tolerate both old and new document shapes, and verify counts before and after the change.
• Contract: remove old fields, old embedded structures, obsolete indexes, or compatibility code only after all deployed versions and existing documents have moved to the new shape.

Useful MongoDB examples:

• Rename a field with $set + $unset while supporting both old and new names during rollout.
• Split one embedded document into multiple fields or collections without losing historical data.
• Convert scalar values to arrays or nested objects using guarded predicates.
• Add a new required field by first backfilling it, then enforcing validation or application-level requirements later.
• Replace business status values with a compatibility window where both meanings are understood.
• Add indexes in a separate migration before code paths depend on them.

3. Framework-specific runner examples

Each framework skill can keep a shared conceptual model but show different wiring:

• Spring Boot: make Spring Boot 4.x guidance very explicit: prefer mongock-standalone plus mongodb-sync-v4-driver; do not recommend mongock-springboot-v3 for Boot 4. Show MongoDatabase injection in @ChangeUnit methods and @ServiceConnection for Testcontainers.
• Quarkus: document quarkus-mongock compatibility checks, quarkus.mongock.* properties, default-client limitations, and how @ChangeUnit classes access CDI-managed MongoClient safely when normal injection is not available.
• Micronaut: document the standalone runner pattern, mongodb.database configuration, TestPropertyProvider for dynamic Testcontainers URIs, and the impact of adding MongoDB auto-configuration to existing @MicronautTest classes.

4. Migration verification examples

Add testing examples that prove behavior rather than only startup:

• Assert mongockChangeLog contains EXECUTED entries for the expected change IDs.
• Assert a physical side effect, such as a field backfill, index creation, collection creation, or document-shape conversion.
• Seed pre-migration documents that represent old production shapes, then verify the migrated shape.
• Verify idempotency by making the predicate safe for reruns and, where feasible, demonstrating that repeated execution does not duplicate array entries or corrupt counters.
• Use real MongoDB infrastructure through Testcontainers, Quarkus Dev Services, or framework-native test support instead of mocks for migration tests.

5. Acceptance criteria ideas

The Gherkin acceptance files for 316, 416, and 516 could assert that the generated skills:

• Read the main Mongock reference plus any antipatterns or NoSQL parallel-change supplemental references.
• Explain runner compatibility before recommending dependencies.
• Include at least one MongoDB document-shape migration example.
• Warn against mutable domain-model coupling inside @ChangeUnits.
• Require idempotent operations and explicit ordering.
• Require real MongoDB verification of both changelog records and side effects.
• Distinguish startup execution from controlled migration jobs for long-running backfills.

This would make issue #902 the Mongock/NoSQL counterpart to the Flyway safety work from issue #895 while preserving the different migration model: MongoDB documents evolve by shape, predicates, backfills, indexes, and compatibility windows rather than only by schema DDL scripts.