Cap the SDK's Kotlin at the version embedded in Gradle

claude/agents/dependency-audit.md

@@ -3,10 +3,11 @@ name: dependency-audit
 description: >
   Audits changes to dependency declarations under
   `buildSrc/src/main/kotlin/io/spine/dependency/` — catches accidental
-  version downgrades, BOM mismatches, missing deprecation markers, copyright
-  drift, and convention drift. Use proactively whenever a diff touches that
-  directory, or when the user asks "audit this dependency bump". Read-only;
-  does not run builds.
+  version downgrades, BOM mismatches, versions above the Kotlin version cap,
+  missing deprecation markers, copyright drift, and convention drift. Use
+  proactively whenever a diff touches that directory or
+  `buildSrc/build.gradle.kts`, or when the user asks "audit this dependency
+  bump". Read-only; does not run builds.
 tools: Read, Grep, Glob, Bash
 model: haiku
 ---
@@ -15,10 +16,13 @@ Follow the `dependency-audit` skill exactly:
 
 - Skill: `.agents/skills/dependency-audit/SKILL.md`
 - The skill owns the per-area checks (version sanity, naming and structure,
-  deprecation discipline, convention drift, cross-cutting) and the output
-  format (Must fix / Should fix / Nits + one-line verdict).
+  deprecation discipline, convention drift, cross-cutting, Kotlin version cap)
+  and the output format (Must fix / Should fix / Nits + one-line verdict).
 - Read-only: use `Read`, `Grep`, `Glob`, and `Bash` solely for `git diff`,
-  `git grep`, and related read-only inspection. Do not run builds.
+  `git grep`, and related read-only inspection. For the Kotlin-cap check,
+  that includes running the `kotlin-version-cap` skill's script, which reads
+  the Gradle cache and makes plain GETs of `config`'s wrapper properties and
+  of artifact POM and `.module` files. Do not run builds.
 - **Be fast.** Fetch the full unified diff once, work from it, and `Read`
   individual files only when the skill's step 2 budget allows. Issue
   independent `Grep`/`Bash` calls in parallel within a single response;

claude/commands/bump-gradle.md

@@ -2,7 +2,9 @@
 description: >
   Upgrade the Gradle wrapper to the latest release.
 argument-hint: "[gradle-version]"
-allowed-tools: Read, Edit, Bash(./gradlew:*), Bash(git status:*), Bash(git diff:*), WebFetch
+allowed-tools: >-
+  Read, Edit, Bash(./gradlew:*), Bash(git status:*), Bash(git diff:*), WebFetch,
+  Bash(python3 .agents/skills/kotlin-version-cap/scripts/kotlin_cap.py:*)
 model: sonnet
 ---
 
@@ -14,3 +16,6 @@ Follow the `bump-gradle` skill exactly:
   truth for the latest version. Do NOT rely on remembered Gradle versions.
 - If the user supplied a version: $ARGUMENTS, use it; otherwise read it from the release notes.
 - Commit the wrapper change and dependency report change in separate commits per the skill.
+- Report which Kotlin the new Gradle embeds and how the bump moves the Kotlin
+  version cap (the `kotlin-version-cap` skill). Never raise Kotlin in
+  the same change.

claude/commands/dependency-update.md

@@ -5,7 +5,8 @@ description: >
 argument-hint: "[--dry-run] [paths...]"
 allowed-tools: >-
   Read, Edit, Write, Grep, Glob, WebFetch, Bash(git status:*),
-  Bash(git diff:*), Bash(./gradlew build:*), Bash(./gradlew clean build:*)
+  Bash(git diff:*), Bash(./gradlew build:*), Bash(./gradlew clean build:*),
+  Bash(python3 .agents/skills/kotlin-version-cap/scripts/kotlin_cap.py:*)
 model: sonnet
 ---
 
@@ -18,6 +19,11 @@ Follow the `dependency-update` skill exactly:
   `// https://...` or KDoc `@see`). If no URL, fall back to Maven Central
   AND back-fill the URL comment.
 - Filter out snapshots, RCs, alphas, betas, milestones, EAPs, and `-dev` builds.
+- Apply the Kotlin version cap (the `kotlin-version-cap` skill): never
+  raise Kotlin above the Kotlin embedded in the Gradle version of `config`'s
+  wrapper, and never adopt a release that requires a newer Kotlin than that.
+  Report held-back versions under "Capped" and values already above the cap under
+  "Above the cap".
 - Apply the edit. Do NOT commit; emit the report described in the skill.
 - Flag `local/` (Spine SDK) updates separately so the user can decide whether to bump in lockstep.
 - After the run, suggest the user review the diff and run `./gradlew build`

claude/commands/pre-pr.md

@@ -30,7 +30,8 @@ Follow the `pre-pr` skill exactly:
     the build), or a `.kt`/`.kts`/`.java` diff that also touches comment
     lines. See the skill for the exact conditions.
   - `dependency-audit` when any file under
-    `buildSrc/src/main/kotlin/io/spine/dependency/` changed.
+    `buildSrc/src/main/kotlin/io/spine/dependency/` or
+    `buildSrc/build.gradle.kts` changed.
   - `check-links` when a Hugo site exists (a Hugo config under `docs/` or
     `site/`) and the diff touches files under the site directory or
     `lychee.toml`. Honor the `check-links.ok` sentinel short-circuit from

guidelines/_TOC.md

@@ -39,3 +39,5 @@
 33. [Raise test coverage](../skills/raise-coverage/SKILL.md)
 34. [Kotlin JVM tester](../skills/kotlin-jvm-tester/SKILL.md) — how to write JVM tests
     in Kotlin for Spine: naming, structure, helpers, and Java coexistence
+35. [Kotlin version cap](../skills/kotlin-version-cap/SKILL.md) — the SDK's Kotlin never
+    exceeds the Kotlin embedded in the Gradle version of `config`'s wrapper