You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by zh...@apache.org on 2026/08/04 01:36:40 UTC
(shardingsphere) branch master updated: Add evidence-backed ShardingSphere design audit skill (#39326)
This is an automated email from the ASF dual-hosted git repository.
terrymanu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new 0980e85bf63 Add evidence-backed ShardingSphere design audit skill (#39326)
0980e85bf63 is described below
commit 0980e85bf639060fe42adb87dfbed0c89de47fae
Author: Liang Zhang <zh...@apache.org>
AuthorDate: Tue Aug 4 09:36:34 2026 +0800
Add evidence-backed ShardingSphere design audit skill (#39326)
* Add evidence-backed ShardingSphere design audit skill
* Add evidence-backed ShardingSphere design audit skill
* Add evidence-backed ShardingSphere design audit skill
---
.codex/skills/audit-shardingsphere-design/SKILL.md | 171 +++++++++++++++++++++
.../audit-shardingsphere-design/agents/openai.yaml | 21 +++
.../references/design-smells.md | 98 ++++++++++++
.../references/finding-model.md | 117 ++++++++++++++
.../references/spi-plugin-design.md | 152 ++++++++++++++++++
.../references/test-design.md | 77 ++++++++++
6 files changed, 636 insertions(+)
diff --git a/.codex/skills/audit-shardingsphere-design/SKILL.md b/.codex/skills/audit-shardingsphere-design/SKILL.md
new file mode 100644
index 00000000000..3742c1b8f1d
--- /dev/null
+++ b/.codex/skills/audit-shardingsphere-design/SKILL.md
@@ -0,0 +1,171 @@
+---
+name: audit-shardingsphere-design
+description: >-
+ Audit an Apache ShardingSphere module or the entire repository for evidence-backed
+ design problems without changing code; default to the entire repository when no scope is
+ provided. Use for module responsibility and dependency direction, every kind of SPI/plugin
+ implementation including database, feature and algorithm plugins, coupling and extensibility,
+ over-design and duplication, repository coding standards and style, or production and test
+ design. Do not use for PR/diff review or implementation.
+---
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Audit ShardingSphere Design
+
+## Objective
+
+Find current, material design problems that an experienced ShardingSphere engineer can
+verify and act on. Review a named Maven module or the complete repository. Include production
+and test code by default. When the invocation provides no scope, review the complete repository
+without asking for one. Explain the minimum correction direction, but never modify code or produce
+a patch.
+
+## Boundaries
+
+- Review the current source tree, not a PR or diff.
+- Do not edit files, install Skills, or require another Skill at runtime.
+- Do not audit historical problems. Use history only when the repository instructions require
+ it to verify a removal claim or when current evidence cannot establish a contract.
+- Do not report compatibility and evolution as a standalone category. Discuss compatibility
+ only as the impact of a current public API, SPI, loading, registration, or configuration issue.
+- Treat every production SPI implementation as a plugin. Do not assume all plugin categories
+ have the same ownership or placement rule.
+- Do not call code safely removable without the complete evidence required by repository rules.
+
+## Required References
+
+Read these files directly from this Skill before classifying findings:
+
+- Always read [finding-model.md](references/finding-model.md) for proof, priority,
+ confidence, and output rules.
+- Always read [design-smells.md](references/design-smells.md) for responsibility,
+ coupling, complexity, duplication, and style criteria.
+- Read [spi-plugin-design.md](references/spi-plugin-design.md) whenever the scope contains
+ an SPI declaration, implementation, loader, registration, or plugin consumer.
+- Read [test-design.md](references/test-design.md) when tests exist in the selected scope.
+
+## Workflow
+
+1. Resolve the scope as one or more Maven modules or the entire repository. If the user provides
+ no scope after invoking the Skill, select the entire repository immediately and do not ask a
+ clarifying question. If the user gives a file or package, map it to its owning module and include
+ the minimum consuming modules needed to judge ownership. For an aggregator or the whole
+ repository, enumerate leaf Maven modules and review them in bounded partitions; account for
+ every leaf module rather than substituting a sample. Do not switch to PR scope.
+2. Read the applicable `AGENTS.md`, `CODE_OF_CONDUCT.md`, module POMs, registrations, and the
+ closest maintained production and test precedents. Treat written rules as authority and
+ nearby code as evidence of project idiom, not as automatic proof that a pattern is good.
+3. Map each examined behavior to its owner, callers, dependencies, extension axis, SPI contract,
+ implementations, registrations, packaging path, and tests. Trace cross-module behavior end
+ to end before judging placement or coupling.
+4. Discover candidates across all applicable capability groups:
+ - module responsibility and dependency direction;
+ - SPI/plugin contract, placement, isolation, loading, and category-specific design;
+ - coupling, knowledge leakage, and extension cost;
+ - unnecessary conceptual surface, indirection, duplication, and misplaced reuse;
+ - explicit coding rules plus the project's readability, simplicity, consistency, and
+ abstraction principles;
+ - production-owned test behavior, boundaries, mocks, and SPI loading.
+5. Apply the proof gate in `finding-model.md`. Inspect the strongest counter-evidence. Reject
+ checklist matches that do not demonstrate a real consequence in this codebase.
+6. Consolidate findings that share one root cause and correction boundary. Rank findings by
+ impact, scope, and confidence; do not rank by how easy they are to describe.
+7. Return the report defined below. If no candidate passes the proof gate, say that no confirmed
+ design problem was found and list any material evidence limitation without inventing findings.
+ If an aggregate scope cannot be completed, return `Review incomplete`, preserve confirmed
+ findings as partial facts, and identify the unreviewed modules; never present partial coverage
+ as a complete repository or module conclusion.
+
+## Judgment Rules
+
+- Prefer repository contracts and actual dependency paths over package-name intuition.
+- Separate an explicit standards violation from a semantic style problem. Prove semantic style
+ problems through reduced readability, inconsistent abstraction, needless concepts, or a
+ maintained precedent that better expresses the same responsibility.
+- Treat one implementation, one caller, a wrapper, a factory, or an interface as a signal only.
+ Report over-design only when the concept lacks a real stable boundary and adds demonstrated
+ navigation, state, dependency, testing, or extension cost.
+- Distinguish useful reuse from forced unification. Share stable semantics owned by one module;
+ keep real database, feature, or algorithm differences inside their plugins.
+- Treat unverified indirect use as unresolved. Inspect registrations, `ServiceLoader`, project
+ loaders, reflection, generated resources, Maven scopes, tests, packaging, and runtime consumers
+ before making unused or removal claims.
+- Keep optional external Skills outside the decision path. Their availability must not change
+ the scope, proof standard, or output.
+
+## Output Contract
+
+Write the report in the same natural language as the user's audit request. An explicit output
+language wins. For a mixed-language request without an explicit choice, use the language of the
+user's instructions rather than identifiers or quoted code. If the invocation contains only the
+Skill name or a scope, use the language of the surrounding conversation, or English when none is
+available. Translate headings and field labels as well as the finding text; keep code identifiers
+and repository paths unchanged.
+
+Start with the reviewed scope and a one-sentence conclusion. Then list confirmed findings in
+priority order. Apply the self-contained finding rules in `finding-model.md` and use this shape for
+every finding:
+
+```markdown
+### [P1|P2|P3] Concise problem title
+
+- Location: repository-relative file and line, or the smallest responsible module
+- Capability: one capability group from the workflow
+- Evidence: applicable exact code, dependency, registration, rule, or maintained precedent
+- Path: the relevant owner, caller, dependency, loading, registration, and packaging path
+- Problem: the violated responsibility, contract, or project principle
+- Impact: current maintenance, extension, correctness, packaging, or test consequence
+- Direction: the smallest correction boundary, naming what stays, moves, or changes and how to
+ verify the preserved behavior, without patch content
+- Counter-evidence: the strongest alternative explanation checked and why it does not reverse the
+ finding
+- Confidence: High or Medium, with the reason
+```
+
+Use `P1` for a confirmed wrong ownership or contract that creates broad or immediate risk, `P2`
+for a material extension or maintenance cost, and `P3` for a localized but non-trivial clarity,
+consistency, or test-design problem. Do not publish low-confidence candidates as findings.
+
+End with:
+
+- `Coverage`: capability groups and modules actually examined.
+- `Not findings`: important candidates rejected by counter-evidence, only when this helps prevent
+ the same false positive from recurring.
+- `Evidence limits`: facts that could materially change the conclusion.
+
+Keep the report concise. Do not add a generic checklist, praise unaffected code, or recommend a
+large redesign when a smaller ownership correction addresses the evidence. A finding must explain
+the concrete project problem and correction without requiring the reader to infer the meaning of a
+smell label or ask a follow-up question.
+
+## Completion Gate
+
+Before returning the report, verify that:
+
+- every finding traces a complete relevant path and cites current repository evidence;
+- every finding identifies a concrete consequence and minimum correction boundary;
+- every finding is self-contained and explains project-specific terms that are necessary to
+ understand the problem;
+- every leaf module in an aggregate scope is accounted for, or the result is explicitly incomplete;
+- SPI findings apply the correct category profile rather than a universal placement rule, and SPI
+ placement findings satisfy the reporting contract in `spi-plugin-design.md`;
+- style findings distinguish written rules from engineering judgment;
+- test findings protect production-owned behavior rather than coverage appearance;
+- no finding depends on another Skill, a single regex match, or an unverified deletion premise;
+- the report covers every applicable capability group and contains no patch or source edit.
diff --git a/.codex/skills/audit-shardingsphere-design/agents/openai.yaml b/.codex/skills/audit-shardingsphere-design/agents/openai.yaml
new file mode 100644
index 00000000000..890d7d04a0a
--- /dev/null
+++ b/.codex/skills/audit-shardingsphere-design/agents/openai.yaml
@@ -0,0 +1,21 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+interface:
+ display_name: "Audit ShardingSphere Design"
+ short_description: "Find evidence-backed design and SPI problems"
+ default_prompt: "Use $audit-shardingsphere-design to audit the entire ShardingSphere repository for evidence-backed design, SPI plugin, style, and test problems without changing code."
diff --git a/.codex/skills/audit-shardingsphere-design/references/design-smells.md b/.codex/skills/audit-shardingsphere-design/references/design-smells.md
new file mode 100644
index 00000000000..935350f45b5
--- /dev/null
+++ b/.codex/skills/audit-shardingsphere-design/references/design-smells.md
@@ -0,0 +1,98 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Design Smells
+
+## Capability Map
+
+| Capability | Examine | Report only when |
+|---|---|---|
+| Module responsibility | Owners, boundaries and dependency direction | Behavior sits outside its owner or defeats a module boundary |
+| Coupling and extensibility | Concrete-type, state, configuration and lifecycle knowledge | One variant forces unrelated core or peer-plugin changes |
+| Complexity and reuse | Concepts, indirection, representations and duplicate change points | A concept owns no needed behavior, state or contract and creates real cost |
+| Standards and style | Written rules, intent, consistency and abstraction level | Code breaks a rule or materially obscures its responsibility |
+
+## Module Responsibility
+
+Derive a module's purpose from its POM, public contracts, package structure, consumers, and
+maintained peers. Trace behavior rather than judging directory names. Look for:
+
+- core or shared modules that know concrete variant classes, configuration keys, or lifecycle;
+- implementation modules that redefine policy owned by a shared contract;
+- dependencies flowing from an abstraction owner to a concrete implementation without a
+ packaging or bootstrap reason;
+- API modules containing runtime orchestration, mutable state, or implementation details;
+- callers reaching across the intended public boundary because the owner exposes the wrong
+ contract or data shape.
+
+Do not report a class merely because another directory looks more attractive. Demonstrate the
+responsibility mismatch and the dependency or change consequence.
+
+## Coupling and Extensibility
+
+Use a real supported variation as the extension test. Ask which files must change to add another
+database, feature, algorithm, provider, or protocol implementation. Strong smells include:
+
+- central `switch`, `if`, type check, or concrete-class lookup repeated for plugin identities;
+- plugin-specific properties or result types leaking into neutral callers;
+- one plugin importing another plugin instead of depending on a shared owned contract;
+- global mutable registries or lifecycle assumptions coupling otherwise independent plugins;
+- a supposedly optional plugin required to compile or package the core path.
+
+Branching is not automatically wrong. Keep branches that implement policy genuinely owned by the
+central component, especially when the set is closed by contract rather than extensible by SPI.
+
+## Over-Design and Conceptual Surface
+
+For every questioned abstraction, identify the production behavior, state, invariant, or public
+contract it owns. Then identify the stable variation it represents. A candidate becomes a finding
+when neither exists and the abstraction adds cross-file navigation, construction paths, states,
+representations, tests of wiring, or dependency edges.
+
+Treat these as signals, not verdicts: one implementation, one caller, an interface, a factory, a
+wrapper, a DTO, a private helper, or a strategy name. Framework contracts, SPI loading, public API
+stability, security boundaries, and genuinely clearer ownership can justify them.
+
+Prefer the smallest conceptual surface, not mechanically fewer lines. Do not recommend inlining a
+name or extraction that materially explains intent.
+
+## Duplication and Reuse
+
+Distinguish repeated text from repeated responsibility. Report duplication when the same stable
+rule must change in several places and one clear owner can express it without importing plugin
+differences. Do not unify code that only looks similar but varies by database semantics, feature
+contract, algorithm behavior, lifecycle, exception contract, or release cadence.
+
+Prefer direct reuse, then composition or delegation, then an existing extension point. A new
+shared abstraction must own a stable concept; reducing line count alone does not justify it.
+
+## Standards and Style Essence
+
+First identify explicit violations of `CODE_OF_CONDUCT.md`, applicable `AGENTS.md`, Checkstyle, or
+established public API/SPI documentation requirements. State the exact rule.
+
+Review semantic style separately. Apply the project's development philosophy:
+
+- **Readability:** Intent is visible from names and a direct control flow.
+- **Simplicity:** Every concept and line has a current purpose; minimal does not mean compressed.
+- **Consistency:** Similar responsibilities use the same maintained idiom unless semantics differ.
+- **Abstraction:** Methods, classes, packages, and modules stay at one coherent level.
+- **Cleanliness:** Remove parallel representations and accidental complexity, not useful domain
+ language.
+
+Do not turn personal taste or generic clean-code slogans into findings. Cite the concrete reading,
+change, ownership, or consistency cost and the closest applicable project evidence.
diff --git a/.codex/skills/audit-shardingsphere-design/references/finding-model.md b/.codex/skills/audit-shardingsphere-design/references/finding-model.md
new file mode 100644
index 00000000000..038074c5076
--- /dev/null
+++ b/.codex/skills/audit-shardingsphere-design/references/finding-model.md
@@ -0,0 +1,117 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Finding Model
+
+## Candidate and Finding
+
+Treat a naming pattern, directory placement, dependency, abstraction, duplicate block, or rule
+match as a candidate. Publish it as a finding only when all of these conditions hold:
+
+1. **Observation:** Identify the exact current code, registration, dependency, contract, test,
+ or written project rule.
+2. **Path:** Trace the relevant caller-to-owner or contract-to-loader-to-implementation path far
+ enough to establish responsibility and consequence.
+3. **Principle:** Name the concrete module responsibility, SPI contract, dependency direction,
+ repository rule, or design principle that the code violates.
+4. **Consequence:** Demonstrate current correctness risk, knowledge leakage, packaging risk,
+ extension cost, duplicated change points, navigation cost, or misleading test protection.
+5. **Counter-evidence:** Inspect the strongest fact that could make the design intentional, such
+ as framework requirements, public contracts, another variation, packaging, or nearby owners.
+6. **Correction boundary:** Identify the smallest responsibility or dependency that must change.
+
+Reject the candidate when it is only a preference, a theoretical future risk, or a pattern name
+without a demonstrated consequence.
+
+## Self-Contained Finding Gate
+
+A confirmed finding must be understandable and actionable without a follow-up question. Explain
+the issue in current ShardingSphere terms rather than using a smell label as the conclusion. Every
+finding must answer:
+
+1. **Where:** Which concrete class, resource, POM, registration, module, or line owns the problem.
+2. **How it is reached:** Which caller, dependency, loader, registration, packaging, or test path
+ establishes the behavior.
+3. **Why it is wrong:** Which specific responsibility, dependency direction, SPI contract, written
+ rule, or maintained project principle is violated.
+4. **What it causes:** Which current correctness, maintenance, extension, packaging, navigation, or
+ test-protection consequence follows from that path.
+5. **What must change:** Which responsibility stays, which concrete artifacts move or change, and
+ which behavior must remain verified. Prove current ownership wrong independently from whether
+ the correct owner already exists. Do not invent a target module name or hierarchy. When no
+ existing module can own the behavior without violating responsibility or dependency direction,
+ require current variation and packaging evidence that a new boundary is necessary; describe
+ its responsibility and variation axis, and cite maintained precedents when available.
+6. **Why the alternative explanation fails:** Which framework, bootstrap, compatibility,
+ packaging, closed-set, default-implementation, or nearby-precedent justification was checked.
+
+Define contextual phrases such as `shared module`, `core policy`, `plugin-specific behavior`, or
+`wrong owner` through the actual consumers and dependencies. If any answer that could reverse the
+conclusion is missing, keep the item as a candidate or evidence limitation rather than a finding.
+
+## Evidence Quality
+
+Prefer evidence in this order:
+
+1. Applicable `AGENTS.md`, `CODE_OF_CONDUCT.md`, public API/SPI contracts, and module POMs.
+2. Complete current production paths, registrations, resources, packaging, and tests.
+3. Closest maintained precedents with the same variation axis and runtime role.
+4. Engineering inference explicitly connected to the observations above.
+
+Do not use one regex match, one direct-reference search, package names alone, or generic design
+maxims as sufficient proof. When sources conflict, report the conflict and lower confidence.
+
+## Priority
+
+- **P1:** Confirmed wrong ownership, dependency direction, SPI contract, registration, or plugin
+ leakage with broad or immediate correctness, packaging, or extension impact.
+- **P2:** Material maintenance or extension cost across multiple types, modules, or change paths.
+- **P3:** Localized but non-trivial clarity, consistency, abstraction, or test-design problem.
+
+Priority combines consequence, affected scope, and likelihood. It does not measure effort or
+personal preference. Consolidate symptoms that require the same correction into one finding.
+
+## Confidence
+
+- **High:** The full relevant path, violated contract, consequence, and counter-evidence are all
+ directly supported by current repository facts.
+- **Medium:** The path and consequence are supported, but one non-decisive ownership or runtime
+ detail remains inferred.
+- **Low:** A missing consumer, runtime, packaging, contract, or intent fact could reverse the
+ conclusion. Keep it out of findings and list it only as an evidence limitation when material.
+
+## Removal Boundary
+
+Do not equate absence of direct references with unused code. Before calling an artifact safely
+removable, inspect semantic and indirect consumers, including overrides, reflection, generated
+code, SPI and `ServiceLoader` registrations, Maven scopes and profiles, test JARs, packaging,
+distributions, tests, E2E, and external contracts. Follow the repository's required history and
+controlled-removal gates.
+
+Without that evidence, use `suspected unnecessary design` or `purpose unresolved`. Recommend
+simplifying the responsibility, not deleting the artifact. Ordinary audits do not investigate
+history merely to find old problems.
+
+## Reporting Discipline
+
+- Cite repository-relative paths and tight line locations when available.
+- Separate observed facts from inference in the evidence text.
+- Explain why the issue matters to the next engineer who changes or extends the code.
+- Give a concrete correction boundary, not a patch, new class hierarchy, or speculative target
+ architecture. Name affected classes, dependencies, registrations, or resources when the evidence
+ requires them.
+- Omit generic compliments, exhaustive candidate logs, and findings that failed the proof gate.
diff --git a/.codex/skills/audit-shardingsphere-design/references/spi-plugin-design.md b/.codex/skills/audit-shardingsphere-design/references/spi-plugin-design.md
new file mode 100644
index 00000000000..d5716b94672
--- /dev/null
+++ b/.codex/skills/audit-shardingsphere-design/references/spi-plugin-design.md
@@ -0,0 +1,152 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# SPI Plugin Design
+
+- [Model](#model)
+- [Common Plugin Invariants](#common-plugin-invariants)
+- [Category Profiles](#category-profiles)
+- [High-Value Smells](#high-value-smells)
+- [SPI Placement Finding Contract](#spi-placement-finding-contract)
+
+## Model
+
+Treat every production implementation of an SPI as a plugin, regardless of whether it represents
+a database, feature, algorithm, provider, protocol, loader, or another extension category. Treat
+the SPI contract, neutral loader, and registration infrastructure as the extension mechanism, not
+as plugin implementations.
+
+This model does not require every implementation to have its own Maven module. Judge module
+granularity from the real variation axis, dependency direction, independent packaging needs, and
+maintained project structure.
+
+## Common Plugin Invariants
+
+Check every SPI category for these invariants:
+
+1. The contract expresses a stable variation needed by production behavior, not type distinction,
+ test convenience, formal symmetry, or anticipated reuse alone.
+2. The contract and loader remain neutral to concrete plugin classes and plugin-only data shapes.
+3. Core callers depend on the contract. Plugins depend on the contract or shared owned behavior;
+ peer plugins do not depend on each other for convenience.
+4. Registration, type identity, loader selection, Maven dependencies, and packaged resources
+ agree. A source-level implementation that cannot be discovered or packaged is incomplete.
+5. Configuration validation, lifecycle, state, and failure handling belong at the boundary that
+ owns them and do not leak one plugin's assumptions into all callers.
+6. Shared behavior stays with its real owner, while variant behavior stays inside the plugin.
+
+Trace `contract -> loader/registry -> registration -> implementation -> caller -> package` before publishing a placement or coupling finding.
+
+## Category Profiles
+
+### Database and Dialect Plugins
+
+Use this profile when behavior varies by database type, dialect, supported version, protocol, or
+database capability. Keep database-neutral policy in its owning core and isolate real dialect
+differences in maintained database or dialect modules. Check derived databases for intentional
+reuse of shared semantics without erasing their plugin identities.
+
+A database-specific implementation in `infra`, `kernel`, or another shared module is a candidate,
+not an automatic finding. Prove that the shared module now knows a database variant, that a
+maintained dialect module can own it without reversing dependencies or that no current module can
+own it and the evidence requires a new database-plugin boundary, and that the correction preserves
+registration and packaging. For a new boundary, name the responsibility and variation axis rather
+than inventing a module path or hierarchy. Conversely, keep an infrastructure-owned extension in
+infrastructure when the variation itself is infrastructure behavior rather than a database plugin.
+
+### Feature or Function Plugins
+
+Use this profile when selection varies by a product feature, rule, transaction mode, authority
+provider, governance behavior, function, protocol capability, or another functional type. Derive
+ownership from the feature's API/core/type structure. Keep feature-neutral orchestration in the
+feature owner and concrete behavior in the corresponding type or provider module.
+
+Do not force a feature plugin into a database module merely because it consumes database metadata.
+When a plugin varies by both feature and database, place the implementation at the narrowest
+maintained boundary that owns both axes without making core depend on the implementation.
+
+### Algorithm Plugins
+
+Use this profile when behavior is selected by algorithm type and properties. Keep algorithm
+contracts, shared property semantics, and common validation in their owners. Keep concrete
+strategies in algorithm type modules and prevent neutral callers from branching on their classes.
+
+Small implementations are valid plugins; do not report them as over-designed merely because the
+algorithm is simple. Report abstraction overhead only when extra contracts or wrappers do not
+serve loading, configuration, behavior, or a stable algorithm family.
+
+### Other SPI Plugins
+
+Do not squeeze an unknown SPI into the three profiles above. Identify its actual selection key,
+variation reason, lifecycle, packaging boundary, and consumer. Apply the common invariants and
+derive category-specific ownership from maintained peers with the same runtime role.
+
+## High-Value Smells
+
+- Core code imports, constructs, casts to, or branches on concrete plugin classes.
+- A plugin implementation sits in a shared module and makes that module depend on variant-only
+ configuration, libraries, resources, or release behavior.
+- The SPI returns an implementation-specific DTO or exposes lifecycle methods needed by only one
+ plugin.
+- Adding one plugin requires edits to unrelated plugin modules or repeated central registries.
+- Registration points to the wrong implementation, duplicates an identity, or is absent from the
+ artifact that must provide it.
+- Common code copied across plugins is stable owner behavior, or shared code contains variant
+ branches that should remain inside plugins.
+
+For every smell, inspect counterexamples such as framework discovery constraints, bootstrap-owned
+registries, deliberately closed sets, default implementations, and distribution assembly. Report
+the issue only when those facts do not justify the design.
+
+## SPI Placement Finding Contract
+
+Do not publish a statement such as `a database plugin implementation is packaged in a shared core
+module` as a finding by itself. It names only a candidate smell. For every plugin placement
+finding, report:
+
+1. The concrete SPI implementation, current module, and tight source location.
+2. Why the current module is shared or neutral, proven through its POM, consumers, public contract,
+ and maintained peers rather than its directory name.
+3. The complete `contract -> loader/registry -> registration -> implementation -> caller ->
+ package` path, including variant-only dependencies, configuration, or resources.
+4. The current consequence, such as requiring a neutral caller to change for another plugin,
+ forcing a shared artifact to carry plugin-only dependencies, or preventing independent
+ packaging.
+5. The maintained module that should own the implementation and the evidence for that ownership;
+ or, when no current module can own it without violating responsibility or dependency direction,
+ the evidence that a new boundary is necessary and the responsibility and variation axis that
+ boundary owns.
+6. The minimum correction boundary:
+ - what contract, neutral loader, and genuinely shared behavior remain in the current owner;
+ - what implementation, dependency, registration, configuration, or resource moves;
+ - what caller, distribution assembly, or packaging declaration changes; and
+ - what loading, selection, compatibility, and runtime behavior must be verified.
+7. The strongest counterexample checked, including infrastructure-owned variation, bootstrap
+ assembly, deliberately closed sets, default implementations, and dependency reversal.
+
+Use actual repository identifiers to summarize `Current ownership`. Summarize `Expected ownership`
+with an existing module when one is proven, or with an evidence-backed responsibility boundary when
+no existing module can own the behavior. For a new boundary, do not invent a module name, path, or
+hierarchy; explain why current owners are invalid, name the implementation, dependencies,
+registrations, and resources it would own, and state the required packaging or assembly changes.
+For example, a proven database placement issue may keep the SPI contract and neutral loader in a
+shared module, move the database implementation, registration, resources, and dedicated
+dependencies to the maintained database plugin module or a proven new database-plugin boundary,
+and keep explicit plugin inclusion in the distribution assembly. This is only a structure for
+reporting; derive every named move from the current repository. If the report cannot identify these
+facts, retain the item as a candidate or evidence limitation rather than asking the reader to infer
+the problem.
diff --git a/.codex/skills/audit-shardingsphere-design/references/test-design.md b/.codex/skills/audit-shardingsphere-design/references/test-design.md
new file mode 100644
index 00000000000..14ce637a8c0
--- /dev/null
+++ b/.codex/skills/audit-shardingsphere-design/references/test-design.md
@@ -0,0 +1,77 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Test Design
+
+## Purpose
+
+Judge whether tests protect meaningful production-owned behavior and its boundaries. Do not turn
+coverage percentage, test count, or conformance to a preferred test shape into a design finding.
+Apply `CODE_OF_CONDUCT.md` and the applicable `AGENTS.md` test rules first.
+
+## Capability Areas
+
+### Behavioral Value
+
+Confirm that each test can fail for a realistic regression in computation, decisions, validation,
+transformation, state transitions, error handling, or an external contract owned by the production
+subject. Look for tests that only prove constants, accessors, delegation, wiring, Java, Lombok,
+Mockito, a parser library, or private implementation shape.
+
+Do not report a simple test merely because it is small. Demonstrate that it protects no owned or
+externally visible behavior, duplicates another scenario, or asserts the collaborator instead of
+the subject.
+
+### Ownership and Boundaries
+
+Check that tests exercise behavior through the nearest owning public API. Collaborator rules
+belong in the collaborator's tests; cross-module behavior belongs in an explicitly scoped contract,
+integration, or E2E test. Flag production visibility, constructors, hooks, or abstractions added
+only to make tests convenient.
+
+Require precise scenarios and assertions at important correct, boundary, and error paths. Do not
+recommend testing every branch when a branch is only framework wiring or cannot represent a
+meaningful regression.
+
+### Isolation and Mocks
+
+Check whether tests remain automatic, independent, and repeatable. Mock heavy external boundaries
+and unrelated deep object graphs, but do not mock away the production decision being tested. Look
+for fragile call-order assertions, deep setup for unrelated collaborators, shared mutable state,
+environment dependencies, and static resources that are not released.
+
+Prefer direct mocks and the nearest stable boundary. Treat a helper or fixture as a smell only
+when it creates a test-only API, hides the scenario, duplicates thin delegation, or crosses module
+ownership for convenience.
+
+### SPI and Plugin Tests
+
+Obtain `TypedSPI` and `DatabaseTypedSPI` implementations through the project loader by default.
+Check registration, type selection, properties, failure contracts, and the concrete behavior owned
+by each plugin. Do not accept interface-only tests or direct construction when it bypasses the
+loading contract the production path relies on.
+
+Do not require a dedicated test for a pass-through plugin type with no owned behavior merely for
+structural symmetry. If the type has no meaningful contract to test, question the production type
+before adding a coverage-only test.
+
+## Reporting
+
+Tie every test finding to the production regression that can currently escape or to the production
+design distorted for testing. State the smallest correction direction without generating tests or
+patches. Keep explicit naming, assertion, Mockito, and JUnit rule violations separate from semantic
+test-design findings.