test(P9): document and guard Java Kotlin boundaries

Author: Arbousier1

CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+MahjongPaper currently mixes Java and Kotlin deliberately. Keep the split visible when adding production code.
+
+## Java/Kotlin Boundary
+
+Use Java by default for Paper/Bukkit integration, plugin bootstrap, commands, table/session orchestration, rendering, UI, database, runtime scheduling, CraftEngine compatibility, configuration, i18n, and metrics.
+
+Use Kotlin only where it keeps rule or data-heavy code clearer:
+
+- pure Riichi rule logic, scoring helpers, and state models under `src/main/kotlin/top/ellan/mahjong/riichi`
+- GB native request/response DTOs under `src/main/kotlin/top/ellan/mahjong/gb/jni`
+- future pure algorithm or serialization model packages, after updating `ArchitectureBoundaryTest` and this document in the same change
+
+Production Kotlin should not import Bukkit, Paper, Kyori UI/presentation APIs, CraftEngine compatibility classes, plugin bootstrap classes, database services, runtime schedulers, or table/session coordinator internals. Tests may use Kotlin freely.
+
+## Package Boundaries
+
+Keep these dependency directions in mind:
+
+- `bootstrap` wires services and entry points; avoid reaching into command/render/ui internals.
+- `command` talks to the public table and service surface through `MahjongCommandContext`.
+- `table` owns session orchestration and may call render/UI services through narrow interfaces.
+- `render` owns display entity specs/layout and must stay free of `table` and `bootstrap`.
+- `riichi` and `gb` should stay rules-focused and free of platform/presentation dependencies.
+- `compat` hides CraftEngine and Paper reflection details behind service facades.
+
+If a new feature needs to cross one of these boundaries, prefer introducing a small DTO or interface near the caller instead of importing a concrete internal class from another layer.
+
+## Build Logic
+
+Keep root `build.gradle.kts` focused on task wiring. Resource generation, native helper logic, and bundle generation belong in `buildSrc`.

README.md

@@ -4,6 +4,7 @@
 
 Chinese documentation: [README.zh-CN.md](./README.zh-CN.md)
 Chinese gameplay and operations wiki: [docs/wiki.zh-CN.md](./docs/wiki.zh-CN.md)
+Contributor notes: [CONTRIBUTING.md](./CONTRIBUTING.md)
 
 `MahjongPaper` is a Paper plugin rewrite of `MahjongCraft` built around:
 

README.zh-CN.md

@@ -3,6 +3,7 @@
 > 本项目完全由 AI 创作。
 
 英文说明见 [README.md](./README.md)。
+贡献与代码边界说明见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
 
 `MahjongPaper` 是 `MahjongCraft` 的 Paper 插件重写版本，当前主要基于：
 

src/test/kotlin/top/ellan/mahjong/architecture/ArchitectureBoundaryTest.kt

@@ -120,6 +120,22 @@ class ArchitectureBoundaryTest {
         )
     }
 
+    @Test
+    fun `production kotlin stays in rules and native model packages`() {
+        val violations = sourceFiles("src/main/kotlin")
+            .filter { file ->
+                allowedProductionKotlinRoots.none { root ->
+                    file.normalize().startsWith(root)
+                }
+            }
+            .map { projectRoot.relativize(it) }
+
+        assertTrue(
+            violations.isEmpty(),
+            "Production Kotlin should stay in rule or serialization-model packages; update CONTRIBUTING.md and this allowlist for deliberate new roots:\n${violations.joinToString("\n")}"
+        )
+    }
+
     private companion object {
         val projectRoot: Path = Path.of("").toAbsolutePath()
         val forbiddenRuleImports = listOf(
@@ -153,6 +169,10 @@ class ArchitectureBoundaryTest {
             "import top.ellan.mahjong.table.core.MahjongTableSession",
             "import top.ellan.mahjong.table.core.TableFinalStanding"
         )
+        val allowedProductionKotlinRoots = listOf(
+            "src/main/kotlin/top/ellan/mahjong/riichi",
+            "src/main/kotlin/top/ellan/mahjong/gb/jni"
+        ).map { projectRoot.resolve(it).normalize() }
 
         fun sourceFiles(vararg roots: String): List<Path> = roots.flatMap { root ->
             val rootPath = projectRoot.resolve(root)