Bump Base and Validation

.agents/_TOC.md

@@ -13,4 +13,9 @@
 11. [Advanced safety rules](advanced-safety-rules.md)
 12. [Refactoring guidelines](refactoring-guidelines.md)
 13. [Common tasks](common-tasks.md)
-14. [Java to Kotlin conversion](java-kotlin-conversion.md)
+14. [Java to Kotlin conversion](skills/java-to-kotlin/SKILL.md)
+15. [Dependency update](skills/dependency-update/SKILL.md)
+16. [Documentation review](skills/review-docs/SKILL.md)
+17. [Pre-PR checklist](skills/pre-pr/SKILL.md)
+18. [Kotlin code review](skills/kotlin-review/SKILL.md)
+19. [Dependency audit](skills/dependency-audit/SKILL.md)

.agents/coding-guidelines.md

@@ -33,7 +33,7 @@
 - Reflection unless specifically requested
 
 ## Text formatting
- - ✅ Remove double empty lines in the code.
+ - ✅ Replace double empty lines with a single empty line in the code.
  - ✅ Remove trailing space characters in the code.
 
 [spine-docs]: https://github.com/SpineEventEngine/documentation/wiki

.agents/project-structure-expectations.md

@@ -17,5 +17,5 @@ build.gradle.kts # Kotlin-based build configuration
 settings.gradle.kts # Project structure and settings
 README.md # Project overview
 AGENTS.md # Entry point for LLM agent instructions
-version.gradle.kts # Declares the project version. 
+version.gradle.kts # Declares the project version in versioned Gradle Build Tools repos.
 ```

.agents/quick-reference-card.md

@@ -3,7 +3,6 @@
 ```
 🔑 Key Information:
 - Kotlin/Java project with CQRS architecture
-- Use ChatGPT for documentation, Codex for code generation, GPT-4o for complex analysis
 - Follow coding guidelines in Spine Event Engine docs
 - Always include tests with code changes
 - Version bump required for all PRs

.agents/skills/bump-gradle/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: bump-gradle
+description: >
+  Update the Gradle wrapper version used by this repository. Use when asked to
+  upgrade Gradle, bump the Gradle wrapper, move the project to the latest
+  Gradle release from the official release notes, run the Gradle build, and
+  commit Gradle wrapper and dependency report changes separately.
+---
+
+# Bump Gradle
+
+Use the official Gradle release notes as the source of truth for both the
+latest version and the wrapper update command:
+
+https://docs.gradle.org/current/release-notes.html#upgrade-instructions
+
+Always check that page at task time. Do not rely on remembered Gradle versions.
+
+## Checklist
+
+1. Work from the target repository root.
+
+   Confirm `./gradlew` and `gradle/wrapper/gradle-wrapper.properties` exist
+   before changing anything. Inspect `git status --short` and preserve unrelated
+   user changes. If Gradle wrapper files are already modified, inspect the diff
+   and continue only when those edits are part of the same requested Gradle
+   bump; otherwise ask before overwriting or staging them.
+
+2. Read the latest Gradle version from the release notes.
+
+   Open the Upgrade instructions section at the URL above. Use the version in
+   the release heading and the wrapper command shown there. They should agree;
+   if they do not, stop and report the mismatch.
+
+3. Run the wrapper update command.
+
+   Substitute the version from the release notes:
+
+   ```bash
+   ./gradlew wrapper --gradle-version=GRADLE_VERSION && ./gradlew wrapper
+   ```
+
+   For example, if the release notes say Gradle `9.5.1`, run:
+
+   ```bash
+   ./gradlew wrapper --gradle-version=9.5.1 && ./gradlew wrapper
+   ```
+
+4. Run the build.
+
+   ```bash
+   ./gradlew clean build
+   ```
+
+   If the wrapper update or build fails, do not commit partial changes. Report
+   the failing command and the relevant error output.
+
+5. Commit only Gradle-related files.
+
+   Inspect `git status --short` and `git diff --name-only`. Stage only files
+   created or updated by the Gradle wrapper bump, normally:
+
+   ```text
+   gradle/wrapper/gradle-wrapper.properties
+   gradle/wrapper/gradle-wrapper.jar
+   gradlew
+   gradlew.bat
+   ```
+
+   Include other Gradle-owned files only when they are directly required by the
+   wrapper update and are clearly part of the same change. Do not stage
+   dependency reports or unrelated build output in this commit.
+
+   Commit with the exact subject, replacing `GRADLE_VERSION`:
+
+   ```text
+   Bump Gradle -> `GRADLE_VERSION`
+   ```
+
+   Example:
+
+   ```bash
+   git commit -m 'Bump Gradle -> `9.5.1`'
+   ```
+
+   If no Gradle-related files changed, do not create an empty commit; report
+   that the wrapper was already current after verification.
+
+6. Commit dependency reports separately when the build updates them.
+
+   Stage only generated dependency report files. In repositories using this
+   config, the usual paths are:
+
+   ```text
+   docs/dependencies/pom.xml
+   docs/dependencies/dependencies.md
+   ```
+
+   Include other changed files only when they are clearly generated dependency
+   reports from the build. Commit them separately with:
+
+   ```text
+   Update dependency reports
+   ```
+
+7. Verify the final branch state.
+
+   Confirm the recent commit subjects and make sure no owned Gradle bump or
+   dependency report changes remain unstaged:
+
+   ```bash
+   git log --format=%s -2
+   git status --short
+   ```
+
+   Leave unrelated pre-existing user changes alone and mention them separately
+   in the final response.

.agents/skills/bump-gradle/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bump Gradle"
+  short_description: "Update the Gradle wrapper safely"
+  default_prompt: "Use $bump-gradle to update this repository to the latest Gradle wrapper version from the official release notes, build, and split Gradle/report commits."

.agents/skills/bump-version/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: bump-version
+description: >
+  Bump the project version in `version.gradle.kts` following the Spine SDK
+  versioning policy. Use when starting a new branch, before opening a PR, or
+  when CI rejects a branch for a missing/insufficient version increment. Covers
+  locating the published version value, choosing the increment, committing the
+  bump, rebuilding reports, and resolving version conflicts.
+---
+
+# Bump the project version
+
+The authoritative policy is [Spine SDK Versioning][version-policy]. In this
+skill's target repository, CI runs the `Version Guard` workflow, which invokes
+`checkVersionIncrement` through `IncrementGuard`. The task fails if the current
+project version already exists in the Maven repository. It does not compare git
+branches or inspect commit subjects; the checks below are agent-side guardrails.
+
+## Checklist
+
+1. Work from the target repository root.
+
+   Confirm `version.gradle.kts` exists before editing. If it is absent, stop and
+   report that this skill does not apply to the current checkout.
+
+   Inspect `git status --short` before changing files. Preserve unrelated user
+   changes and stage only the version/report files this workflow owns.
+
+2. Locate `version.gradle.kts` and update the value that feeds
+   `versionToPublish`.
+
+   The published version may be a literal:
+
+   ```kotlin
+   val versionToPublish: String by extra("2.0.0-SNAPSHOT.182")
+   ```
+
+   Or it may come from another variable:
+
+   ```kotlin
+   val compilerVersion: String by extra("2.0.0-SNAPSHOT.043")
+   val versionToPublish by extra(compilerVersion)
+   ```
+
+   In the second case, update the source value (`compilerVersion` here), not
+   only the `versionToPublish` alias.
+
+3. Choose the increment.
+
+   For the normal snapshot-line PR, increment the trailing snapshot number by
+   one: `2.0.0-SNAPSHOT.182` -> `2.0.0-SNAPSHOT.183`. Preserve existing
+   zero-padding: `2.0.0-SNAPSHOT.009` -> `2.0.0-SNAPSHOT.010`.
+
+   For a breaking snapshot-line PR, advance to the next multiple of 10 that is
+   strictly greater than the current value: `.187` -> `.190`, and `.180` ->
+   `.190`.
+
+   For release-line work, follow the [policy][version-policy]: urgent fixes bump `PATCH`;
+   feature work or significant fixes bump `MINOR` and reset `PATCH` to `0`.
+
+4. Commit only the `version.gradle.kts` change with this subject:
+
+   ```text
+   Bump version -> `2.0.0-SNAPSHOT.183`
+   ```
+
+   Use the actual new version in the subject. Do not include unrelated files in
+   this commit.
+
+5. Run the build to verify the bump and regenerate reports:
+
+   ```bash
+   ./gradlew clean build
+   ```
+
+   Repos using this config commonly finalize `generatePom` and
+   `mergeAllLicenseReports` after `build`, which updates
+   `docs/dependencies/pom.xml` and `docs/dependencies/dependencies.md` when
+   those reports are configured.
+
+6. If `docs/dependencies/pom.xml` or `docs/dependencies/dependencies.md` changed,
+   commit those generated files separately:
+
+   ```text
+   Update dependency reports
+   ```
+
+   If the PR has the `License Reports` workflow, make sure the branch modifies
+   `docs/dependencies/pom.xml` and `docs/dependencies/dependencies.md`.
+
+7. Validate the branch state.
+
+   ```bash
+   BASE=master
+   git fetch --quiet origin "$BASE"
+   RANGE="$(git merge-base HEAD origin/$BASE)..HEAD"
+   git log --format=%s "$RANGE" | grep '^Bump version ->'
+   git diff --name-only "$RANGE" -- version.gradle.kts | grep '^version.gradle.kts$'
+   ```
+
+   Use the actual merge target for `BASE` when it is not `master`.
+   Also confirm `git status --short` has no uncommitted changes created by the
+   version bump or report regeneration.
+
+## Conflict Rule
+
+When merging a base branch into a feature branch:
+
+- If the base branch version is lower, keep the feature branch version.
+- If the base branch version is greater than or equal to the feature branch
+  version, set the feature branch version to `base + 1`, or apply the breaking
+  change rounding rule.
+
+Do not require a completely clean worktree if unrelated user changes are
+present. Instead, make sure no uncommitted changes were created by the version
+bump or report regeneration.
+
+[version-policy]: https://github.com/SpineEventEngine/documentation/wiki/Versioning

.agents/skills/bump-version/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bump Version"
+  short_description: "Bump Spine project versions safely"
+  default_prompt: "Use $bump-version to bump the project version in version.gradle.kts, commit the version change, rebuild dependency reports, and verify the branch."

.agents/skills/dependency-audit/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: dependency-audit
+description: >
+  Audit changes to dependency declarations under
+  `buildSrc/src/main/kotlin/io/spine/dependency/` — catches accidental
+  version downgrades, BOM mismatches, missing deprecation markers when
+  artifacts are renamed or removed, copyright drift, and convention drift.
+  Use whenever a diff touches that directory, or when asked to "audit
+  this dependency bump". Read-only; does not run builds.
+---
+
+# Dependency audit (repo-specific)
+
+You are the dependency auditor for a Spine Event Engine repo. All managed
+dependencies live under:
+
+    buildSrc/src/main/kotlin/io/spine/dependency/
+
+organized by sub-package:
+
+- `lib/` — third-party runtime libraries (Kotlin, Guava, Protobuf, gRPC, …).
+- `local/` — Spine SDK artifacts (Base, CoreJvm, ModelCompiler, …).
+- `test/` — testing libraries (JUnit, Kotest, AssertK, Truth, Jacoco, Kover).
+- `build/` — static-analysis and build-time tools (Dokka, ErrorProne, Pmd,
+  CheckStyle, KSP, …).
+- `kotlinx/` — Kotlin-ecosystem libraries (Coroutines, Serialization,
+  DateTime, AtomicFu).
+- `boms/` — BOM declarations.
+
+Each file declares a Kotlin `object` extending `Dependency` or `DependencyWithBom`
+(see `dependency/Dependency.kt`). The shape is:
+
+    object Kotest {
+        const val version = "6.1.11"
+        const val group   = "io.kotest"
+        const val assertions = "$group:kotest-assertions-core:$version"
+        // …
+    }
+
+## How to run an audit
+
+1. **Scope the diff.**
+   - Run `git diff --stat <base>...HEAD -- 'buildSrc/src/main/kotlin/io/spine/dependency/**'`
+     (or `--staged` if the user is mid-commit) and read the file list.
+   - If the diff is empty, ask the user which files to audit.
+
+2. **Read each changed file fully.** Don't trust the hunk in isolation —
+   `version` constants are often referenced elsewhere in the same file (e.g.
+   `runtimeVersion` reused as `embeddedVersion`).
+
+3. **Run the checks below in order. Stop the audit and surface a finding the
+   moment any check fails.**
+
+## Checks
+
+### A. Version sanity
+- **No silent downgrade.** Compare the old and new `version` value as semver.
+  A decrease (`2.0.0 -> 1.9.0`) or a snapshot regression (`-SNAPSHOT.183` ->
+  `.182`) is a Must-fix unless the commit message explicitly justifies it.
+- **Snapshot vs. release consistency.** If `version` switches from a release
+  (`2.0.0`) to a snapshot (`2.0.1-SNAPSHOT.001`), confirm the consuming code
+  isn't pinned to the release elsewhere via `grep -r '<libName>:<oldVersion>'`.
+- **BOM ↔ component agreement.** For objects extending `DependencyWithBom`,
+  check that `bom` references the same version as `version` (e.g. Kotlin's
+  `kotlin-bom:$runtimeVersion`).
+
+### B. Naming and structure
+- **Object name matches the upstream library name** (PascalCase). New files
+  must follow the convention of neighbors (e.g. `lib/Foo.kt` declares
+  `object Foo`).
+- **No type names in property names** (`fooList`, `barObject`) — this is in
+  `.agents/coding-guidelines.md`.
+- **Module constants use `"$group:<artifact>:$version"`**, not hardcoded
+  Maven coordinates. Catch copy-paste like `"io.kotest:kotest-assertions-core:6.1.11"`.
+
+### C. Deprecation discipline
+When an artifact is **renamed or removed**:
+- The old `const val` must stay with `@Deprecated("…", ReplaceWith("…"))`
+  or `@Deprecated("…")` (see `Kotest.frameworkApi` and `Kotest.datatest` for
+  the established style).
+- If the diff deletes a `const val` outright, grep the repo with
+  `git grep '<oldName>'` to confirm no caller is left behind. If callers exist,
+  this is a Must-fix.
+
+### D. Convention drift
+- **Copyright header year.** Every changed file should have a current-year
+  copyright line. If a file was edited but its copyright says `2024`, flag it
+  (the user can run `/update-copyright` to fix).
+- **GitHub URL comment.** New `lib/` and `kotlinx/` files conventionally
+  start with `// https://github.com/<owner>/<repo>` above the object.
+  Recommend it if missing.
+- **`@Suppress("unused", "ConstPropertyName")` on the object.** This is the
+  established style for constant-heavy declarations.
+
+### E. Cross-cutting checks
+- **`local/` deps don't leak.** Spine SDK artifacts in `local/` should not be
+  declared in `lib/` or `test/` (and vice versa).
+- **No mixing Groovy and Kotlin DSL.** All Gradle code in `buildSrc/` must be
+  `.kt` or `.gradle.kts`. Catch any `.gradle` file slipping in.
+
+## Output format
+
+Three sections, in this order:
+
+- **Must fix** — version downgrades, missing deprecation markers on removed
+  symbols, broken callers, BOM/version mismatches.
+- **Should fix** — convention drift, missing deprecation `ReplaceWith`,
+  missing copyright update, missing URL comment, naming oddities.
+- **Nits** — formatting, ordering, doc-comment polish.
+
+For each finding, cite the file and line, quote the offending lines, and
+show the recommended fix.
+
+End with a one-line verdict: `APPROVE`, `APPROVE WITH CHANGES`, or
+`REQUEST CHANGES`.