docs(openspec): add Mongock migration guidance spec

documentation/openspec/changes/improve-mongock-migration-guidance/design.md

@@ -0,0 +1,101 @@
+## Context
+
+Issue #902 asks maintainers to improve the Mongock skills for all supported frameworks so users receive better examples and safer advice when adding MongoDB data migrations. The issue was shaped as a user story for maintainers and expanded with MongoDB-oriented implementation ideas:
+
+- Add explicit Mongock antipattern guidance.
+- Adapt the Flyway safety pattern from issue #895 to NoSQL document evolution.
+- Add framework-specific runner and configuration examples.
+- Add verification guidance that proves Mongock executed and changed real MongoDB state.
+
+The repository already has separate Mongock skills for Spring Boot, Quarkus, and Micronaut. The implementation should keep each framework's runner and test wiring local while adding shared migration-safety concepts consistently.
+
+## Decisions
+
+### Target Skill References
+
+Update the three framework-specific Mongock reference XML files and, if the detailed guidance becomes too large for the main references, add focused supplemental references for each framework:
+
+- `316-frameworks-spring-mongodb-migrations-mongock.xml`
+- Optional: `316-frameworks-spring-mongodb-migrations-mongock-antipatterns.xml`
+- Optional: `316-frameworks-spring-mongodb-migrations-mongock-document-evolution.xml`
+- `416-frameworks-quarkus-mongodb-migrations-mongock.xml`
+- Optional: `416-frameworks-quarkus-mongodb-migrations-mongock-antipatterns.xml`
+- Optional: `416-frameworks-quarkus-mongodb-migrations-mongock-document-evolution.xml`
+- `516-frameworks-micronaut-mongodb-migrations-mongock.xml`
+- Optional: `516-frameworks-micronaut-mongodb-migrations-mongock-antipatterns.xml`
+- Optional: `516-frameworks-micronaut-mongodb-migrations-mongock-document-evolution.xml`
+
+No new skill id is required. The improvement belongs inside the existing framework-specific Mongock skills.
+
+### Mongock Antipattern Guidance
+
+Each Mongock skill should include guidance that helps agents identify risky MongoDB migrations before recommending code changes.
+
+The guidance should cover:
+
+- Editing an already-applied `@ChangeUnit` instead of creating a new ordered change.
+- Using repositories, domain records, DTOs, mappers, or mutable application services inside migrations.
+- Non-idempotent updates such as blind `$inc`, array appends, or broad `updateMany` operations without guarded predicates.
+- Long backfills during application startup without considering probes, rollout windows, lock duration, partial completion, or recovery.
+- Assuming transactions are available or cheap in standalone MongoDB, large collections, or multi-document updates.
+- Hiding lock acquisition failures in clustered deployments.
+- Recommending framework-specific runner coordinates without verifying compatibility first.
+- Testing only application startup without proving Mongock changelog records and physical side effects.
+
+### NoSQL Document Evolution Technique
+
+Each Mongock skill should explain expand, migrate, contract as a MongoDB document migration workflow:
+
+- Expand: add optional fields, embedded structures, collections, or indexes while old readers and writers still work.
+- Migrate: backfill documents with idempotent predicates, tolerate or dual-write old and new shapes, and verify counts before and after the migration.
+- Contract: remove old fields, obsolete embedded structures, unused indexes, old collections, or compatibility code only after all deployed code and existing documents have moved to the new shape.
+
+Examples should include MongoDB-specific cases:
+
+- Field rename using `$set` plus `$unset` while readers tolerate old and new field names during rollout.
+- Scalar-to-array or scalar-to-object conversion with guarded predicates.
+- Embedded document split or merge without losing historical data.
+- New required field introduced as optional, backfilled, then enforced later.
+- Status or enum value replacement with a compatibility window.
+- Index creation as a separate migration before application code depends on it.
+
+### Framework-Specific Guidance
+
+Shared safety guidance should remain consistent, but examples must respect framework differences:
+
+- Spring Boot: explicitly distinguish Spring Boot 3.x and 4.x runner choices. For Spring Boot 4.x, use `mongock-standalone` plus `mongodb-sync-v4-driver`, and avoid `mongock-springboot-v3`. Show `MongoDatabase` usage in `@ChangeUnit` methods and `@ServiceConnection` for Testcontainers.
+- Quarkus: verify `quarkus-mongock` compatibility with the active Quarkus platform, document `quarkus.mongock.*` properties, default-client limits, and safe access to CDI-managed MongoDB clients when normal injection does not work inside `@ChangeUnit` classes.
+- Micronaut: document standalone runner wiring, `mongodb.database` configuration, `TestPropertyProvider` for Testcontainers URIs, and the impact of adding MongoDB auto-configuration to existing `@MicronautTest` classes.
+
+### Testing Guidance
+
+Mongock verification should prove migration behavior, not only application startup.
+
+The skills should recommend:
+
+- Running migrations against real MongoDB infrastructure through Testcontainers, Quarkus Dev Services, or framework-native test support.
+- Seeding pre-migration documents that represent old production shapes.
+- Asserting `mongockChangeLog` contains `EXECUTED` records for expected change IDs.
+- Asserting physical side effects such as field backfills, index creation, collection creation, or document-shape conversion.
+- Checking idempotency for guarded predicates and avoiding duplicated array entries, repeated increments, or corrupted counters.
+- Separating long-running backfills from automatic startup execution when operationally safer.
+
+### Source and Generated Output Boundaries
+
+Implementation must edit XML sources under `skills-generator/src/main/resources/skill-references/`, update `skills-generator/src/main/resources/skills.xml` if supplemental references are added, and update relevant skill index workflow steps so agents read every required reference. Generated `.agents/skills` output should be regenerated for local validation only. Public `skills/` release output should not be refreshed unless a later release task explicitly requests it.
+
+## Validation Strategy
+
+- Validate changed XML files with `xmllint --noout`.
+- Run `./mvnw clean install -pl skills-generator` to regenerate local skills into `.agents/skills` without refreshing public `skills/`.
+- Inspect generated local Mongock skills:
+  - `.agents/skills/316-frameworks-spring-mongodb-migrations-mongock/SKILL.md`
+  - `.agents/skills/416-frameworks-quarkus-mongodb-migrations-mongock/SKILL.md`
+  - `.agents/skills/516-frameworks-micronaut-mongodb-migrations-mongock/SKILL.md`
+- Check `skills-generator/src/test/resources/gherkin/skills/acceptance-tests-prompts-skills.md` before promoting. Run only listed prompts for changed skills if any are present.
+- Run `./mvnw clean verify -pl skills-generator`.
+- Run `openspec validate --all`.
+
+## Open Questions
+
+- Whether to add supplemental reference XML files or keep the new guidance inside the existing three references can be decided during implementation based on readability and generated skill size.

documentation/openspec/changes/improve-mongock-migration-guidance/proposal.md

@@ -0,0 +1,48 @@
+## Why
+
+GitHub issue [#902](https://github.com/jabrena/cursor-rules-java/issues/902) requests richer Mongock guidance across the framework-specific MongoDB migration skills. The current Spring Boot, Quarkus, and Micronaut Mongock skills cover runner setup, `@ChangeUnit` classes, lock behavior, and basic MongoDB-backed verification, but they need more explicit NoSQL migration-safety guidance and more examples focused on document-shape evolution.
+
+Maintainers need these skills to help users avoid subtle MongoDB data migration failures such as non-idempotent updates, unsafe document reshaping, domain-model coupling inside old migrations, long startup backfills, hidden lock failures, and unverified runner compatibility.
+
+## What Changes
+
+- Add Mongock antipattern guidance to the Spring Boot, Quarkus, and Micronaut Mongock skill references.
+- Add NoSQL document migration technique guidance that adapts the expand, migrate, contract pattern for MongoDB documents, indexes, embedded structures, and collections.
+- Add testing guidance that verifies real Mongock execution, changelog records, physical side effects, and idempotent document updates.
+- Keep the change scoped to XML skill source updates and local generated skill validation; public `skills/` release output remains out of scope unless a release profile is intentionally run later.
+
+## Capabilities
+
+### New Capabilities
+
+- `mongock-migration-skill-guidance`: Adds cross-framework Mongock migration safety guidance for MongoDB and NoSQL document evolution.
+
+### Modified Capabilities
+
+None.
+
+## Source and Derivation
+
+- Source artifact: GitHub issue [#902](https://github.com/jabrena/cursor-rules-java/issues/902).
+- Supporting source artifact: maintainer-authored issue comment with MongoDB-oriented improvement ideas.
+- Related pattern source: GitHub issue [#895](https://github.com/jabrena/cursor-rules-java/issues/895) and OpenSpec change `improve-flyway-migration-guidance`, used as a structural precedent only.
+- Existing 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`
+- Supporting acceptance targets:
+  - `skills-generator/src/test/resources/gherkin/skills/316-frameworks-spring-mongodb-migrations-mongock.feature`
+  - `skills-generator/src/test/resources/gherkin/skills/416-frameworks-quarkus-mongodb-migrations-mongock.feature`
+  - `skills-generator/src/test/resources/gherkin/skills/516-frameworks-micronaut-mongodb-migrations-mongock.feature`
+  - `skills-generator/src/test/resources/gherkin/skills/acceptance-tests-prompts-skills.md`
+- Derivation direction: issue #902 -> OpenSpec change artifacts -> XML skill source implementation -> local generated skill validation.
+
+## Change Boundary Assessment
+
+This is one OpenSpec change because the issue describes one reviewable outcome: improve Mongock migration guidance consistently across all framework-specific MongoDB migration skills. Although three XML reference files and three acceptance feature files may be affected, they share the same value, review boundary, and validation path.
+
+The change is not split by framework because that would create one-change-per-file decomposition without independent user value.
+
+## Impact
+
+XML skill references, skill indexes, `skills.xml` registrations if supplemental references are added, Gherkin acceptance scenarios, local generated `.agents/skills` output, and OpenSpec artifacts may be affected. Generated `.cursor/rules/`, public `skills/`, and `docs/` must not be edited directly. Public `skills/` should only change through the documented release profile when release output is intentionally in scope.

documentation/openspec/changes/improve-mongock-migration-guidance/specs/mongock-migration-skill-guidance/spec.md

@@ -0,0 +1,103 @@
+## ADDED Requirements
+
+### Requirement: Cross-framework Mongock migration safety guidance
+
+The repository MUST improve the Spring Boot, Quarkus, and Micronaut Mongock skills with guidance that helps users avoid MongoDB data-loss and production-safety migration mistakes.
+
+#### Scenario: Framework Mongock skills include migration antipattern guidance
+
+- **GIVEN** maintainers update the framework-specific Mongock skill references
+- **WHEN** the generated local Mongock skills are inspected
+- **THEN** `316-frameworks-spring-mongodb-migrations-mongock` includes Mongock antipattern guidance
+- **AND** `416-frameworks-quarkus-mongodb-migrations-mongock` includes Mongock antipattern guidance
+- **AND** `516-frameworks-micronaut-mongodb-migrations-mongock` includes Mongock antipattern guidance
+- **AND** the guidance addresses MongoDB document-shape, idempotency, runner compatibility, lock, and verification risks
+
+#### Scenario: Mongock antipattern guidance covers risky document migrations
+
+- **GIVEN** a user asks for help adding or reviewing a Mongock migration
+- **WHEN** a Mongock skill identifies migration risks
+- **THEN** it warns about editing applied `@ChangeUnit` classes, mutable domain-model coupling, non-idempotent updates, broad unguarded `updateMany` operations, unsafe array appends, blind counter increments, hidden lock failures, long startup backfills, unverified transaction assumptions, and runner compatibility assumptions
+- **AND** it recommends checking production-like MongoDB documents before applying migrations that can lose, duplicate, corrupt, or reinterpret document data
+
+### Requirement: NoSQL document evolution technique guidance
+
+The Mongock skills MUST explain expand, migrate, contract as a MongoDB document migration technique for backward-compatible NoSQL evolution.
+
+#### Scenario: Explain document-shape expand, migrate, contract
+
+- **GIVEN** a migration changes MongoDB document shape or data interpretation
+- **WHEN** a Mongock skill recommends a safer migration technique
+- **THEN** it explains the Expand step as adding optional fields, embedded structures, collections, or indexes while old readers and writers still work
+- **AND** it explains the Migrate step as backfilling documents with idempotent predicates, tolerating or dual-writing old and new shapes, and verifying counts before and after the migration
+- **AND** it explains the Contract step as removing old fields, obsolete embedded structures, unused indexes, old collections, or compatibility code only after all deployed code and existing documents have moved to the new shape
+- **AND** it applies the technique to MongoDB scenarios such as field renames, scalar-to-array conversions, embedded document changes, new required fields, status value changes, and index rollout
+
+### Requirement: Framework-compatible Mongock runner guidance
+
+The Mongock skills MUST recommend runner, driver, configuration, and execution choices that are compatible with the active framework and MongoDB client model.
+
+#### Scenario: Spring Boot Mongock guidance distinguishes Boot 3 and Boot 4
+
+- **GIVEN** a Spring Boot project needs Mongock migrations
+- **WHEN** `316-frameworks-spring-mongodb-migrations-mongock` recommends dependencies and runner wiring
+- **THEN** it verifies the Spring Boot major version before selecting a runner
+- **AND** it recommends `mongock-standalone` plus `mongodb-sync-v4-driver` for Spring Boot 4.x
+- **AND** it warns against `mongock-springboot-v3` on Spring Boot 4.x
+- **AND** it shows a `@ChangeUnit` pattern based on stable MongoDB collection operations rather than mutable repositories or domain records
+
+#### Scenario: Quarkus Mongock guidance verifies Quarkiverse compatibility
+
+- **GIVEN** a Quarkus project needs Mongock migrations
+- **WHEN** `416-frameworks-quarkus-mongodb-migrations-mongock` recommends dependencies and runner wiring
+- **THEN** it verifies `quarkus-mongock` compatibility with the active Quarkus platform before applying changes
+- **AND** it documents `quarkus.mongock.*` configuration and startup versus controlled execution trade-offs
+- **AND** it warns about default-client and CDI injection limitations where applicable
+- **AND** it shows a `@ChangeUnit` pattern that uses stable MongoDB collection operations
+
+#### Scenario: Micronaut Mongock guidance uses verified runner wiring
+
+- **GIVEN** a Micronaut project needs Mongock migrations
+- **WHEN** `516-frameworks-micronaut-mongodb-migrations-mongock` recommends dependencies and runner wiring
+- **THEN** it verifies whether a compatible Micronaut-specific runner exists before recommending one
+- **AND** it documents the standalone runner pattern when no compatible runner is available
+- **AND** it documents `mongodb.database` configuration and startup versus controlled execution trade-offs
+- **AND** it shows a `@ChangeUnit` pattern based on `MongoDatabase` and stable MongoDB collection operations
+
+### Requirement: Mongock verification beyond application startup
+
+The Mongock skills MUST recommend verification that proves migration behavior, changelog execution, and document changes, not only that the application context starts.
+
+#### Scenario: Verify real Mongock execution and document side effects
+
+- **GIVEN** a Mongock migration changes MongoDB documents, collections, or indexes
+- **WHEN** the skill recommends tests
+- **THEN** it recommends running Mongock against real MongoDB infrastructure through Testcontainers, Quarkus Dev Services, or framework-native test support where feasible
+- **AND** it recommends seeding pre-migration documents that represent old production shapes
+- **AND** it recommends asserting `mongockChangeLog` contains `EXECUTED` records for expected change IDs
+- **AND** it recommends asserting at least one physical side effect such as field backfill, index creation, collection creation, or document-shape conversion
+- **AND** it recommends idempotency checks for migrations whose predicates must make reruns safe
+
+### Requirement: Mongock acceptance scenario coverage
+
+The repository MUST update Gherkin acceptance scenarios and prompt inventory entries so the improved Mongock guidance is validated for every affected skill.
+
+#### Scenario: Acceptance scenarios cover improved Mongock guidance
+
+- **GIVEN** the Mongock skill references are improved
+- **WHEN** the related Gherkin acceptance files are inspected
+- **THEN** `316-frameworks-spring-mongodb-migrations-mongock.feature` expects the Spring Boot Mongock skill to include NoSQL migration-safety guidance
+- **AND** `416-frameworks-quarkus-mongodb-migrations-mongock.feature` expects the Quarkus Mongock skill to include NoSQL migration-safety guidance
+- **AND** `516-frameworks-micronaut-mongodb-migrations-mongock.feature` expects the Micronaut Mongock skill to include NoSQL migration-safety guidance
+- **AND** `acceptance-tests-prompts-skills.md` lists prompts for every changed Mongock skill
+
+### Requirement: Source and generated-output boundaries
+
+The implementation MUST edit XML sources and validate generated local skill output without directly editing generated legacy or release outputs.
+
+#### Scenario: Preserve generated-output ownership
+
+- **WHEN** implementation files are reviewed
+- **THEN** `.cursor/rules/` is not edited directly
+- **AND** public `skills/` release output is not edited manually
+- **AND** public `skills/` is refreshed only through the release profile when release output is intentionally in scope