Eliminate duplicated error placeholders

.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/version-policy.md

@@ -1,30 +1,15 @@
 # Version policy
 
-## We use semver
-The version of the project is kept in the `version.gradle.kts` file in the root of the project.
+The project follows the [Spine SDK Versioning policy][wiki-versioning].
+The version is kept in `version.gradle.kts` at the project root and follows
+[Semantic Versioning 2.0.0][semver] with Spine-specific extensions
+(snapshot `NUMBER`, patch, and flavor suffixes).
 
-The version numbers in these files follow the conventions of
-[Semantic Versioning 2.0.0](https://semver.org/).
+PRs without a version bump fail CI.
 
-## Quick checklist for versioning
-1. Increment the patch version in `version.gradle.kts`.
-   Retain zero-padding if applicable:
-    - Example: `"2.0.0-SNAPSHOT.009"` → `"2.0.0-SNAPSHOT.010"`
-2. Commit the version bump separately with this comment:
-   ```text
-   Bump version → `$newVersion`
-   ``` 
-3. Rebuild using `./gradlew clean build`.
-4. Update `pom.xml`, `dependencies.md` and commit changes with: `Update dependency reports`
+For the bump procedure — version-number selection, the commit-message
+convention, the rebuild, dependency-report updates, and conflict resolution —
+use the [`bump-version`](skills/bump-version/SKILL.md) skill.
 
-Remember: PRs without version bumps will fail CI (conflict resolution detailed above).
-
-## Resolving conflicts in `version.gradle.kts`
-A branch conflict over the version number should be resolved as described below.
- * If a merged branch has a number which is less than that of the current branch, the version of
-   the current branch stays.
- * If the merged branch has the number which is greater or equal to that of the current branch,
-   the number should be increased by one.
-
-## When to bump the version?
- - When a new branch is created.
+[semver]: https://semver.org/
+[wiki-versioning]: https://github.com/SpineEventEngine/documentation/wiki/Versioning

.github/workflows/ensure-reports-updated.yml

@@ -20,6 +20,6 @@ jobs:
           # Check out the `config` submodule to fetch the required script file.
           submodules: true
 
-      - name: Check that both `pom.xml` and license report files are modified
+      - name: Check that dependency report files are modified
         shell: bash
         run: chmod +x ./config/scripts/ensure-reports-updated.sh && ./config/scripts/ensure-reports-updated.sh

.gitignore

@@ -135,4 +135,6 @@ pubspec.lock
 # Python cache
 __pycache__/
 *.pyc
+
+# Claude working files
 /.claude/worktrees/

buildSrc/src/main/kotlin/io/spine/gradle/report/license/LicenseReporter.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025, TeamDev. All rights reserved.
+ * Copyright 2026, TeamDev. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,7 +43,7 @@ import org.gradle.kotlin.dsl.the
  *
  * Transitive dependencies are included.
  *
- * The output file is placed to the root folder of the root Gradle project.
+ * The output file is placed under `docs/dependencies` of the root Gradle project.
  *
  * Usage:
  *
@@ -146,7 +146,7 @@ object LicenseReporter {
 
     /**
      * Merges the license reports from all [sourceProjects] into a single file under
-     * the [rootProject]'s root directory.
+     * the [rootProject]'s dependency report directory.
      */
     private fun mergeReports(
         sourceProjects: Iterable<Project>,
@@ -165,7 +165,8 @@ object LicenseReporter {
             }
         println("Merging the license reports from all projects.")
         val mergedContent = paths.joinToString("\n\n\n") { (File(it)).readText() }
-        val output = File("${rootProject.rootDir}/${Paths.outputFilename}")
+        val output = Paths.outputFile(rootProject.rootDir, Paths.outputFilename)
+        output.parentFile.mkdirs()
         output.writeText(mergedContent)
     }
 }

buildSrc/src/main/kotlin/io/spine/gradle/report/license/Paths.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025, TeamDev. All rights reserved.
+ * Copyright 2026, TeamDev. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,15 +26,23 @@
 
 package io.spine.gradle.report.license
 
+import java.io.File
+
 /**
- * Filesystem paths used by [LicenseReporter].
+ * Filesystem paths used by [LicenseReporter] and
+ * [PomGenerator][io.spine.gradle.report.pom.PomGenerator].
  */
 internal object Paths {
 
+    /**
+     * The directory in the root project to which dependency reports are written.
+     */
+    internal const val outputDirectory = "docs/dependencies"
+
     /**
      * The output filename of the license report.
      *
-     * The file with this name is placed to the root folder of the root Gradle project —
+     * The file with this name is placed under [outputDirectory] of the root Gradle project —
      * as the result of the [LicenseReporter] work.
      *
      * Its contents describe the licensing information for each of the Java dependencies
@@ -46,4 +54,10 @@ internal object Paths {
      * The path to a directory, to which a per-project report is generated.
      */
     internal const val relativePath = "reports/dependency-license/dependency"
+
+    /**
+     * Obtains a dependency report file under [outputDirectory] of the root project directory.
+     */
+    internal fun outputFile(rootDirectory: File, filename: String): File =
+        rootDirectory.resolve(outputDirectory).resolve(filename)
 }