@namewta/speculo 0.7.4 → 0.7.5

package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/App.test.ts

@@ -0,0 +1,2 @@
+import { describe, expect, it } from 'vitest'
+describe('fixture', () => { it('works', () => expect(true).toBe(true)) })

package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/App.vue

@@ -0,0 +1,7 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+const props = defineProps<{ title: string }>()
+const count = ref(0)
+const label = computed(() => `${props.title}: ${count.value}`)
+</script>
+<template><button type="button" @click="count++">{{ label }}</button></template>

package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/main.ts

@@ -0,0 +1,4 @@
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import App from './App.vue'
+createApp(App).use(createPinia()).mount('#app')

package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "module": "ESNext",
+    "target": "ES2022"
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.vue"
+  ]
+}

package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/vite.config.ts

@@ -0,0 +1,2 @@
+import { defineConfig } from 'vite'
+export default defineConfig({})

package/template/skills/engineering-standards-builder/manifest.txt

@@ -0,0 +1,112 @@
+examples/fallback/kotlin-gradle/build.gradle.kts
+examples/fallback/kotlin-gradle/expected.json
+examples/fallback/kotlin-gradle/src/main/kotlin/example/App.kt
+examples/go/service/.golangci.yml
+examples/go/service/cmd/api/main.go
+examples/go/service/expected.json
+examples/go/service/go.mod
+examples/go/service/internal/service/service_test.go
+examples/go/service/internal/service/service.go
+examples/java/spring-boot-maven/expected.json
+examples/java/spring-boot-maven/pom.xml
+examples/java/spring-boot-maven/src/main/java/dev/speculo/orders/OrdersApplication.java
+examples/java/spring-boot-maven/src/test/java/dev/speculo/orders/OrdersApplicationTest.java
+examples/polyglot/monorepo/.github/workflows/ci.yml
+examples/polyglot/monorepo/apps/web/package.json
+examples/polyglot/monorepo/apps/web/src/App.vue
+examples/polyglot/monorepo/apps/web/tsconfig.json
+examples/polyglot/monorepo/expected.json
+examples/polyglot/monorepo/package.json
+examples/polyglot/monorepo/pnpm-workspace.yaml
+examples/polyglot/monorepo/services/orders/pom.xml
+examples/polyglot/monorepo/services/orders/src/main/java/dev/speculo/orders/OrdersApplication.java
+examples/polyglot/monorepo/services/worker/go.mod
+examples/polyglot/monorepo/services/worker/main.go
+examples/README.md
+examples/rust/workspace/Cargo.toml
+examples/rust/workspace/crates/cli/Cargo.toml
+examples/rust/workspace/crates/cli/src/main.rs
+examples/rust/workspace/crates/core/Cargo.toml
+examples/rust/workspace/crates/core/src/lib.rs
+examples/rust/workspace/expected.json
+examples/rust/workspace/rust-toolchain.toml
+examples/typescript/react-vite/expected.json
+examples/typescript/react-vite/package.json
+examples/typescript/react-vite/src/App.test.tsx
+examples/typescript/react-vite/src/App.tsx
+examples/typescript/react-vite/src/main.tsx
+examples/typescript/react-vite/tsconfig.json
+examples/typescript/vue-vite/expected.json
+examples/typescript/vue-vite/package.json
+examples/typescript/vue-vite/src/App.test.ts
+examples/typescript/vue-vite/src/App.vue
+examples/typescript/vue-vite/src/main.ts
+examples/typescript/vue-vite/tsconfig.json
+examples/typescript/vue-vite/vite.config.ts
+README.md
+references/go/00-detection-and-scope.md
+references/go/01-language-and-idioms.md
+references/go/02-modules-packages-and-layout.md
+references/go/03-errors-context-and-concurrency.md
+references/go/04-testing-tooling-quality-gates.md
+references/go/README.md
+references/java/00-detection-and-scope.md
+references/java/01-language-packages-and-api.md
+references/java/02-build-modules-and-dependencies.md
+references/java/03-errors-nullability-resources-concurrency.md
+references/java/04-testing-tooling-quality-gates.md
+references/java/frameworks/spring-boot.md
+references/java/README.md
+references/rules/00-governance-and-precedence.md
+references/rules/01-project-discovery.md
+references/rules/02-evidence-topology-and-scope.md
+references/rules/03-interview-and-decisions.md
+references/rules/04-architecture-and-dependency-boundaries.md
+references/rules/05-files-directories-and-naming.md
+references/rules/06-apis-errors-resources-and-concurrency.md
+references/rules/07-documentation-and-comments.md
+references/rules/08-testing-strategy.md
+references/rules/09-security-configuration-and-data.md
+references/rules/10-performance-observability-and-i18n.md
+references/rules/11-tooling-quality-gates-and-ci.md
+references/rules/12-git-review-and-delivery.md
+references/rules/13-adoption-exceptions-and-ratchets.md
+references/rules/14-generation-contract.md
+references/rules/15-validation-contract.md
+references/rules/16-language-adapter-contract.md
+references/rules/README.md
+references/rust/00-detection-and-scope.md
+references/rust/01-language-api-and-safety.md
+references/rust/02-crates-workspaces-and-layout.md
+references/rust/03-errors-ownership-and-concurrency.md
+references/rust/04-testing-tooling-quality-gates.md
+references/rust/README.md
+references/typescript/00-detection-and-scope.md
+references/typescript/01-language-and-type-system.md
+references/typescript/02-modules-packages-and-runtime-boundaries.md
+references/typescript/03-functions-async-errors-resources.md
+references/typescript/04-testing-tooling-quality-gates.md
+references/typescript/app-types/cli.md
+references/typescript/app-types/library.md
+references/typescript/frameworks/react.md
+references/typescript/frameworks/vue.md
+references/typescript/README.md
+references/typescript/runtimes/browser.md
+references/typescript/runtimes/electron.md
+references/typescript/runtimes/node.md
+scripts/discover-project.mjs
+scripts/self-test.mjs
+scripts/sync-manifest.mjs
+scripts/validate-builder.mjs
+scripts/validate-generated-skill.mjs
+SKILL.md
+templates/compatibility/agents-typescript--standards.md
+templates/compatibility/agents-typescript-standards.md
+templates/compatibility/claude-engineering-standards.md
+templates/compatibility/claude-typescript-standards.md
+templates/project-skill/references/project/00-project-profile.md.template
+templates/project-skill/references/project/01-module-map.md.template
+templates/project-skill/references/project/02-decisions-and-exceptions.md.template
+templates/project-skill/references/project/review-checklist.md.template
+templates/project-skill/SKILL.md.template
+templates/README.md

package/template/skills/engineering-standards-builder/references/go/00-detection-and-scope.md

@@ -0,0 +1,37 @@
+# Go：检测、版本与作用域
+
+## 信号
+
+- `go.mod`、`go.work`、`go.sum`；
+- `.go` 源码和 package 声明；
+- `cmd/`、`internal/`、可执行 `package main`；
+- CI 中 `go test`、`go vet`、race、fuzz、lint、build；
+- `golangci-lint`、staticcheck、govulncheck 等配置；
+- code generation 指令与生成标记。
+
+`go.work` 是 Workspace 事实，不等于发布时依赖合同；每个 `go.mod` 是独立 module scope。
+
+## 版本
+
+记录 `go`/`toolchain` directive、CI Go 版本和最低支持范围。不得根据 Builder 环境升级 directive 或自动执行 `go mod tidy`。
+
+## Module scope
+
+- 每个 `go.mod` 建立 module；
+- `go.work` 建立 Workspace 关系；
+- package 由目录和 package clause 交叉验证；
+- command 由 `package main` 和入口确认；
+- generated/vendor/testdata 排除或单独标记。
+
+## 访谈触发
+
+- 多 module 是否共同治理；
+- 哪些 package 属于外部 public API；
+- `internal` 迁移和消费者兼容；
+- `cmd`/应用布局冲突；
+- context、goroutine、error wrapping 与 lint 基线。
+
+## 官方依据
+
+- [Go module layout](https://go.dev/doc/modules/layout)
+- [Go workspaces](https://go.dev/ref/mod#workspaces)

package/template/skills/engineering-standards-builder/references/go/01-language-and-idioms.md

@@ -0,0 +1,34 @@
+# Go：语言与惯用法
+
+## 清晰与零值
+
+- 优先简单控制流、早返回和有用零值；不为模拟其他语言层次引入抽象。
+- package 名短、小写、表达能力；调用点 `package.Symbol` 可读，不重复 stutter。
+- exported identifier、package 和重要约束使用 Go doc 完整句。
+- 小接口由消费者定义；不要为每个 concrete type 预先创建接口。
+- 接口返回 concrete type 在可行时更易演进；只有调用者需要替换行为时暴露接口。
+
+## 数据与 API
+
+- struct 字段和构造器表达不变量；零值不可用时提供构造并文档化。
+- slice/map/channel 的 nil 与 empty 语义在 public API、JSON 和数据库边界明确。
+- 复制含 mutex 或资源 owner 的值会破坏语义；选择 pointer/value receiver 时考虑 identity、大小和一致性。
+- 不把 `interface{}`/`any` 当默认数据模型；在外部边界验证并转换。
+- 泛型用于真实跨类型算法/容器，不取代清晰 domain types 或小接口。
+
+## 控制流
+
+- `defer` 用于成对清理并关注循环中的生命周期；
+- type assertion/check、comma-ok 和 exhaustive-ish switch 处理未知值；
+- `init` 最小化，避免隐式 I/O、goroutine 和注册顺序；
+- package global mutable state 仅在有明确同步、生命周期和测试重置时。
+
+## 生成代码
+
+- `go generate` 不是自动构建步骤；记录 generator、输入和运行方式。
+- 生成文件包含标准标记、与手写代码分离并由 freshness 检查验证（若提交）。
+
+## 官方依据
+
+- [Effective Go](https://go.dev/doc/effective_go)
+- [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments)

package/template/skills/engineering-standards-builder/references/go/02-modules-packages-and-layout.md

@@ -0,0 +1,34 @@
+# Go：Module、Package 与目录
+
+## Module
+
+- module path 是 public import contract；变更需要消费者和版本迁移。
+- 应用、可发布库和独立生命周期可以拆 module，不因目录数量随意多 module。
+- `replace` 记录本地开发/迁移目的；发布前验证不会依赖不可用本地路径。
+- major version module path、tags 和 package compatibility 按 Go module 规则。
+
+## Package
+
+- package 围绕单一能力和共同变化组织；避免 `util`、`common`、`models` 垃圾场。
+- 导入方向无循环；需要共享时先判断能力归属，再提取稳定合同。
+- `internal` 用于编译器可执行的私有边界；只有确认外部消费者后迁移现有 public package。
+- `cmd/<name>` 保存薄入口，业务逻辑进入可测试 package。
+- `pkg/` 不是官方强制目录；只在仓库明确用它表达可复用 public package 时保留。
+- `testdata`、`embed` 资源和平台文件命名遵循 Go tool 语义。
+
+## 多平台与 Build Tags
+
+- 文件后缀和 build tags 的目标平台、feature 和测试矩阵明确。
+- 平台实现共享接口但不隐藏不可测试差异；至少在支持平台 CI 编译。
+- cgo 使用范围、交叉编译和资源所有权单独记录。
+
+## 依赖
+
+- 标准库优先但不以“零依赖”为目的；新模块评估 API、维护、安全和 transitive graph。
+- `go mod tidy` 只在有意修改依赖时执行并审查 diff。
+- public package 不暴露不必要第三方类型，避免锁定消费者。
+
+## 官方依据
+
+- [Organizing a Go module](https://go.dev/doc/modules/layout)
+- [Go Modules Reference](https://go.dev/ref/mod)

package/template/skills/engineering-standards-builder/references/go/03-errors-context-and-concurrency.md

@@ -0,0 +1,38 @@
+# Go：错误、Context 与并发
+
+## Error
+
+- error 是普通返回值；调用者检查并处理，不用 panic 表达可预期失败。
+- 使用 `%w` 包装保留 cause；`errors.Is/As` 检查语义，不依赖字符串匹配。
+- sentinel、typed error 和 opaque error 依据调用者真正需要的分支选择。
+- 增加操作/对象上下文但避免每层重复同一信息。
+- 只记录一次；库通常返回，应用边界决定日志/协议/退出码。
+- panic 仅用于无法继续的不变量或程序员错误；服务边界 recovery 不得假装状态仍安全。
+
+## Context
+
+- `context.Context` 作为第一个参数传入请求范围函数；不存入 struct，不传 nil。
+- 不用 context 传普通可选参数；value 只承载请求范围、跨 API 边界的数据。
+- 派生 context 的 cancel function 必须调用；deadline/cancellation 传播到 I/O 和 goroutine。
+- 不在后台工作中盲目继承已取消 request context；显式定义任务 owner 和生命周期。
+
+## Goroutine 与 Channel
+
+- 每个 goroutine 的启动点能说明何时退出、谁等待、如何取消、错误去向。
+- 不启动 fire-and-forget goroutine，除非由进程级 supervisor 管理并可观测。
+- channel ownership 和 close 责任清楚；通常由发送方/拥有方关闭，不靠 receiver 猜测。
+- buffered channel 容量是 backpressure 设计，不是掩盖死锁的补丁。
+- `select` 处理取消、关闭和默认分支；避免 busy loop。
+- shared map/state 使用 mutex、channel ownership 或 immutable snapshot；规则基于简洁和测量。
+
+## 资源与 Shutdown
+
+- HTTP body、file、rows、ticker、listener、server、worker pool 都关闭；处理 close error 的业务意义。
+- server shutdown 定义停止接收、等待 in-flight、deadline 和强制终止。
+- `sync.Once`、WaitGroup、errgroup 等只在语义匹配时使用；Add/Wait 生命周期可证明。
+
+## 官方依据
+
+- [Go `context` package](https://pkg.go.dev/context)
+- [Go Code Review Comments: Goroutine Lifetimes](https://go.dev/wiki/CodeReviewComments#goroutine-lifetimes)
+- [Go errors](https://go.dev/blog/go1.13-errors)

package/template/skills/engineering-standards-builder/references/go/04-testing-tooling-quality-gates.md

@@ -0,0 +1,46 @@
+# Go：测试、工具链与质量门禁
+
+## 格式与静态检查
+
+- `gofmt` 是基础格式合同；imports 使用项目当前工具。
+- `go vet`、staticcheck、golangci-lint 等按仓库配置运行，不无差别启用所有规则。
+- lint exclude 最小化且有原因和删除条件。
+- `govulncheck` 或依赖安全工具仅在项目已采用/确认时成为门禁。
+
+## 测试
+
+- `*_test.go` 与被测 package 同目录；选择 same-package 或 external-package 测试表达白盒/消费者视角。
+- table-driven test 用于输入矩阵，不为了模板化牺牲可读失败信息。
+- helper 使用 `t.Helper()`，资源使用 `t.Cleanup()`；并行测试不共享无保护状态。
+- integration test 的 build tags、环境、容器和超时明确。
+- HTTP、文件、数据库和并发测试覆盖取消、错误和清理。
+- example test 用于可执行文档和 public API。
+
+## Race、Fuzz 与 Benchmark
+
+- 并发代码和高风险模块使用 `go test -race`，按资源成本配置 PR/夜间范围。
+- parser、协议和边界转换使用 fuzz；失败 corpus 保留为回归输入。
+- benchmark 只在有性能合同或优化决策时添加，记录环境和比较方法。
+- 不用 coverage 数字替代行为和竞争测试。
+
+## 门禁
+
+记录真实 module/workspace 工作目录和命令，例如：
+
+```text
+gofmt check
+go vet ./...
+go test ./...
+go test -race ./...   # 若项目门禁存在
+go test -fuzz=...     # 按专门任务
+staticcheck/golangci-lint
+go build ./...
+```
+
+不得假定每个仓库都支持 `./...` 或相同 tags。
+
+## 官方依据
+
+- [Go testing package](https://pkg.go.dev/testing)
+- [Go fuzzing](https://go.dev/doc/security/fuzz/)
+- [Go race detector](https://go.dev/doc/articles/race_detector)

package/template/skills/engineering-standards-builder/references/go/README.md

@@ -0,0 +1,9 @@
+# Go 适配器
+
+当 Project Inventory 识别到 Go module/workspace 或 Go 源码时读取：
+
+- [检测、版本与作用域](00-detection-and-scope.md)
+- [语言与惯用法](01-language-and-idioms.md)
+- [Module、Package 与目录](02-modules-packages-and-layout.md)
+- [错误、Context 与并发](03-errors-context-and-concurrency.md)
+- [测试、工具链与质量门禁](04-testing-tooling-quality-gates.md)

package/template/skills/engineering-standards-builder/references/java/00-detection-and-scope.md

@@ -0,0 +1,40 @@
+# Java：检测、版本与作用域
+
+## 信号
+
+- `pom.xml`、`.mvn/`、Maven Wrapper；
+- `settings.gradle*`、`build.gradle*`、`gradle.properties`、Gradle Wrapper；
+- `src/*/java`、`module-info.java`；
+- toolchain、compiler release/source/target、CI JDK；
+- Spring Boot plugin/starter 与应用注解；
+- formatter、Checkstyle、Spotless、PMD、Error Prone、JaCoCo、ArchUnit 等配置。
+
+只看到 `.java` 文件可判定语言，但构建模块、JDK 和框架必须由构建文件/源码入口交叉确认。
+
+## 版本与构建事实
+
+记录：
+
+- JDK/toolchain 和目标 bytecode；
+- Maven/Gradle 及 Wrapper 版本；
+- parent/BOM/version catalog；
+- 多模块图与 source sets；
+- JPMS 是否启用；
+- 测试平台和 CI lifecycle；
+- Spring Boot 大版本与 Java 基线。
+
+不得根据本机 JDK 推断项目版本，也不得同时生成 Maven 与 Gradle 命令，除非 scope 确实分别使用。
+
+## 访谈触发
+
+- Maven/Gradle 共存边界不清；
+- JDK 升级目标影响 API、虚拟线程、records 或 module；
+- package-by-feature 与既有分层发生真实冲突；
+- nullability/exception/public API 策略不一致；
+- formatter/style profile 或质量插件准备统一。
+
+## 官方依据
+
+- [Maven standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html)
+- [Gradle multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html)
+- [Java language and API documentation](https://docs.oracle.com/en/java/)

package/template/skills/engineering-standards-builder/references/java/01-language-packages-and-api.md

@@ -0,0 +1,35 @@
+# Java：语言、包与公开 API
+
+## Package 与目录
+
+- package 名小写、稳定并与源码路径一致；模块根遵循实际 build source set。
+- 顶层 package 反映组织/产品所有权；Spring scanning 等框架约束由适配器处理。
+- 在模块内部优先按稳定业务能力组织；controller/service/repository 的层次不是所有 Java 项目的强制目录。
+- package-private、protected、public 使用最小可见性；内部实现不因测试便利而公开。
+- JPMS 项目显式 exports/opens/requires；反射框架所需 `opens` 限定最小范围。
+
+## 类型与 API
+
+- public API 使用领域类型、不可变值和明确泛型；不泄漏 persistence/framework internals。
+- records、sealed types、pattern matching 等仅在项目 JDK 和兼容范围支持时使用。
+- collection 返回值明确所有权和可变性；避免返回内部可变集合。
+- `Optional` 主要用于可能缺失的返回值，是否用于字段/参数遵循项目和框架兼容事实。
+- equals/hashCode/toString 与 identity/value 语义一致；实体和代理类型特别验证。
+- 构造器、工厂和 builder 依据不变量与可读性选择，不为每个简单对象自动生成 builder。
+
+## 命名与文档
+
+- class/interface/record、method、constant、test 遵循现有 formatter/style profile。
+- public package/type/method 的 Javadoc 记录失败、线程安全、nullability、副作用和兼容性。
+- 缩写、DTO/entity/value object 的命名表达边界，不把所有传输对象泛称 `Data` 或 `Model`。
+
+## DTO、领域与持久化
+
+- 外部 transport、领域模型和持久化实体在耦合成本出现时分离。
+- 映射集中在边界，可测试且不静默丢字段。
+- annotation 不应让核心领域依赖不必要的 Web/数据库框架；是否接受框架耦合由模块目标决定。
+
+## 官方依据
+
+- [Java API design guidance in JDK documentation](https://docs.oracle.com/en/java/javase/)
+- [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)（可选 style profile，不是 Java 唯一官方规范）

package/template/skills/engineering-standards-builder/references/java/02-build-modules-and-dependencies.md

@@ -0,0 +1,39 @@
+# Java：构建、模块与依赖
+
+## Maven
+
+- 使用 Wrapper 时以 Wrapper 为 canonical；CI 与本地命令一致。
+- parent、dependencyManagement/BOM 与 pluginManagement 职责清楚；子模块不重复漂移版本。
+- lifecycle phase 与 plugin execution 可追溯；不把需要执行的验证只放在手工 profile。
+- scope（compile/runtime/test/provided/annotation processor）反映真实所有权。
+- 聚合模块和可发布模块区分；module graph 不形成循环。
+
+## Gradle
+
+- 使用 Wrapper；settings 定义参与构建的项目。
+- convention plugin/version catalog 用于稳定共享逻辑，避免根脚本复制所有子项目配置。
+- API/implementation/runtimeOnly/testImplementation 等 configuration 准确表达暴露边界。
+- task 输入、输出与缓存正确；不要依赖 task 执行顺序副作用。
+- composite build、included build 和多项目边界按仓库事实生成。
+
+## 依赖
+
+- 新依赖评估维护、许可证、安全、启动/包体和已有替代；
+- 禁止未使用或重复功能依赖；
+- 依赖版本冲突通过 BOM/platform/resolution evidence 处理，不随意 force 最新；
+- annotation processor、agent 和 build plugin 属于供应链边界；
+- 公开库避免把内部实现依赖泄漏给消费者。
+
+## 生成代码
+
+- generated source root 与手写源码分离；
+- 生成器版本和输入锁定；
+- CI 验证 freshness（若提交生成物）；
+- 不手改生成文件；例外在生成器边界解决。
+
+## 官方依据
+
+- [Maven POM reference](https://maven.apache.org/pom.html)
+- [Maven lifecycle](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html)
+- [Gradle multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html)
+- [Gradle dependency management](https://docs.gradle.org/current/userguide/core_dependency_management.html)

package/template/skills/engineering-standards-builder/references/java/03-errors-nullability-resources-concurrency.md

@@ -0,0 +1,36 @@
+# Java：错误、空值、资源与并发
+
+## Exception
+
+- checked/unchecked 选择遵循模块现有 public contract；不要把所有异常统一包装为无信息 RuntimeException。
+- 只在可恢复、映射协议或增加边界上下文时 catch；保留 cause。
+- 领域错误、HTTP/RPC 映射、用户消息和日志分层。
+- 不 catch `Throwable` 或吞掉中断/取消；确需边界捕获时恢复 interrupt 状态并安全终止。
+- public API 文档化可观察失败和 retry/idempotency 语义。
+
+## Nullability
+
+- 在 module/package 层采用一致 annotation/analysis 体系；工具不一致时不要混合多套含义。
+- 外部/反射/ORM 边界验证 null；内部模型优先用构造不变量和精确类型。
+- 不通过到处 `Objects.requireNonNull` 掩盖边界设计问题。
+- `Optional`、nullable annotation、空集合按语义使用，不用 sentinel 值。
+
+## 资源与事务
+
+- `AutoCloseable` 资源使用 try-with-resources 或结构化 owner；关注 close failure 和 suppressed exception。
+- stream、JDBC、HTTP client response、file channel、executor 和临时文件有关闭策略。
+- transaction 边界位于用例/服务边界，明确 rollback 和外部副作用顺序；不要跨慢网络调用长期持有事务。
+- 锁、线程池和 scheduler 不在每次请求临时创建且忘记关闭。
+
+## 并发
+
+- 共享状态明确同步、不可变或 confinement 策略。
+- executor/线程/虚拟线程由应用边界管理；虚拟线程只有在项目 JDK、框架和阻塞模型适用时生成规则。
+- Future/CompletionStage 定义失败、超时、取消和执行器；不在 common pool 隐式执行阻塞工作。
+- 中断是取消信号，不静默清除。
+- 并发测试覆盖 race、超时、重复提交和 shutdown。
+
+## 官方依据
+
+- [Java try-with-resources](https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html)
+- [Java concurrency APIs](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/concurrent/package-summary.html)

package/template/skills/engineering-standards-builder/references/java/04-testing-tooling-quality-gates.md

@@ -0,0 +1,36 @@
+# Java：测试、工具链与质量门禁
+
+## 测试布局
+
+- 使用构建系统真实 source sets；典型 Maven/Gradle Java 项目将 production 与 test 源分离。
+- 单元测试不启动完整容器；framework slice、集成、契约和 E2E 按风险选择。
+- 数据库、消息和外部协议高风险路径优先真实兼容实现或 Testcontainers，而不是过度 mock。
+- 测试拥有并清理文件、端口、容器、executor 和数据库数据；并行执行不共享无保护状态。
+- parameterized/property tests 用于边界组合；缺陷修复有回归用例。
+
+## 工具链
+
+从构建事实选择：
+
+- formatter：Spotless、google-java-format、项目 formatter；
+- style/static：Checkstyle、PMD、SpotBugs、Error Prone、NullAway 等；
+- test：JUnit Platform、Mockito、AssertJ、Testcontainers 等；
+- coverage：JaCoCo 或项目工具；
+- architecture：ArchUnit/JPMS/build graph；
+- dependency/security：项目已有插件。
+
+不要同时引入功能重叠工具；style profile 必须与 formatter 一致。
+
+## 门禁
+
+- Maven 记录 Wrapper 命令和 lifecycle/profile；
+- Gradle 记录 Wrapper task；
+- PR 与发布门禁区分；
+- integration test 需要的服务、容器和环境明确；
+- flaky quarantine 有 owner 和到期；
+- 新规则对存量采用模块/错误数量 Ratchet。
+
+## 官方依据
+
+- [JUnit 5 User Guide](https://junit.org/junit5/docs/current/user-guide/)
+- [Testcontainers for Java](https://java.testcontainers.org/)

package/template/skills/engineering-standards-builder/references/java/README.md

@@ -0,0 +1,10 @@
+# Java 适配器
+
+当 Project Inventory 在某个 scope 识别到 Java 时读取：
+
+- [检测、版本与作用域](00-detection-and-scope.md)
+- [语言、包与公开 API](01-language-packages-and-api.md)
+- [构建、模块与依赖](02-build-modules-and-dependencies.md)
+- [错误、空值、资源与并发](03-errors-nullability-resources-concurrency.md)
+- [测试、工具链与质量门禁](04-testing-tooling-quality-gates.md)
+- [Spring Boot](frameworks/spring-boot.md)（仅识别到时）

package/template/skills/engineering-standards-builder/references/java/frameworks/spring-boot.md

@@ -0,0 +1,74 @@
+# Spring Boot 规范适配器
+
+只对明确使用 Spring Boot 的 Java scope 生成。先识别 Boot 大版本、Servlet/Reactive、Maven/Gradle、Web/Data/Messaging/Security 技术和部署模型。
+
+## 应用与 package
+
+- 主应用类放在能覆盖 intended component/entity scanning 的根 package；避免 default package。
+- 多应用或模块化系统显式限定 scan/import，不依赖过宽 classpath 扫描。
+- 目录可按 feature 或稳定模块组织；controller/service/repository 分层只作为局部角色，不强制整个仓库按技术层平铺。
+- configuration、adapter、domain 和 application 边界由依赖方向和测试验证。
+
+## 配置
+
+- 使用 Boot externalized configuration；记录 property source 优先级和环境覆盖方式。
+- 相关配置聚合为类型安全 `@ConfigurationProperties`，启动时验证必填、范围和格式。
+- secret 不进入默认配置或日志；profile 不复制业务逻辑。
+- 条件化 bean 和 auto-configuration 写明触发条件、back-off 和测试。
+
+## Web/API
+
+- controller 负责 transport、验证、认证上下文和错误映射，不承载核心业务流程。
+- request/response DTO 与领域/实体的耦合按 API 生命周期决定。
+- Bean Validation 在边界使用；跨字段/领域不变量由领域服务或明确 validator 处理。
+- `@ControllerAdvice`/problem details 等错误合同统一且不泄露内部信息。
+- Servlet 与 WebFlux 模型不混用阻塞/非阻塞假设；线程上下文和 backpressure 按实际 stack。
+
+## Service、事务与数据
+
+- transaction 边界围绕用例；明确 propagation、rollback 和 read-only 语义。
+- 不在事务中无界等待远程 I/O；跨系统一致性使用项目确认的 outbox/saga/idempotency 策略。
+- repository 暴露领域需要的查询，而非让上层依赖 ORM 细节。
+- lazy loading、N+1、分页、锁和 batch 用真实集成测试/指标验证。
+- migration 工具和 schema 变更按 expand/migrate/contract 或项目策略执行。
+
+## 依赖注入与生命周期
+
+- 优先构造器注入；依赖显式且便于测试。
+- Bean scope、线程安全和可变状态一致；singleton bean 不保存请求可变状态。
+- scheduler、listener、executor、client 和连接池配置 owner、超时、关闭和 observability。
+- application event 不作为隐藏业务事务保证；跨进程事件使用明确协议。
+
+## 测试
+
+- 纯领域/服务单元测试不启动 Spring。
+- MVC/WebFlux/Data/Security 等使用适用 test slice；slice 选择来自实际依赖，不复制固定清单。
+- `@SpringBootTest` 用于需要完整上下文的集成路径，不作为所有测试默认。
+- 数据库、消息、缓存等兼容性重要时使用 Testcontainers 或项目真实环境。
+- 随机端口、动态属性、上下文缓存和测试数据隔离明确。
+- 配置绑定、条件 Bean、错误映射、事务和安全边界有测试。
+
+## Actuator 与可观测性
+
+仅在项目采用时生成：
+
+- health/readiness 不泄露敏感信息；
+- metrics/traces/log correlation 使用项目观测体系；
+- endpoint 暴露最小化并受认证/网络边界保护；
+- 自定义 health indicator 不进行无界慢调用。
+
+## 访谈触发
+
+- package-by-feature 与当前分层迁移；
+- MVC/WebFlux 或阻塞/非阻塞边界；
+- transaction/outbox/error contract；
+- test slice 与 Testcontainers 门禁；
+- profile/configuration properties 统一；
+- Boot/JDK 大版本升级。
+
+## 官方依据
+
+- [Spring Boot: Structuring Your Code](https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html)
+- [Spring Boot: Externalized Configuration](https://docs.spring.io/spring-boot/reference/features/external-config.html)
+- [Spring Boot: Testing](https://docs.spring.io/spring-boot/reference/testing/index.html)
+- [Spring Boot: Testcontainers](https://docs.spring.io/spring-boot/reference/testing/testcontainers.html)