{"owner":"apache","repo":"shardingsphere","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# ShardingSphere Codex Development Guide\n\nThis repository guide is written for Codex. Keep only stable, repository-wide\nrules here and rely on Codex for ordinary coding competence. Follow every\nexplicit rule literally; do not replace a repository rule with general judgment\nunless that rule authorizes it. Paths are relative to the repository root.\n\n## Instruction Sources\n\n1. `CODE_OF_CONDUCT.md` is the authority for contribution, Java, and unit-test\n   style. Inspect the applicable section before changing code or tests and\n   record it when it controls a decision.\n2. Before Maven, E2E, Proxy startup, database clients, IDE/MCP run\n   configurations, commands likely to output more than 100 lines, or large\n   structured analysis, read or reuse\n   `.codex/context/token-efficiency.md` and follow its Mandatory Execution\n   Contract.\n3. Use repository Skills for specialized workflows instead of reproducing their\n   detailed instructions here.\n4. Keep task-specific notes in the task, issue, or PR. Do not add session notes\n   to this file.\n\n### Changing This Guide\n\nFor changes to this guide, use `.codex/harness/agents/`. `cases.toml` is the\nsource of the harness catalog: each case records its group, purpose, enforcement\nphase, and whether the ordinary completion loop rechecks it. Run\n`python3 .codex/harness/agents/run.py --list-cases` to render the table.\n\n1. Treat every explicit requirement, prohibition, exception, authorization\n   boundary, and verification step as an independent policy capability.\n2. Before editing, build an old-to-new capability ledger and classify every\n   capability as exactly preserved, changed with the user's explicit\n   authorization in the current task, or restored before handoff.\n3. Reconcile every deleted or weakened rule explicitly. A replacement is\n   equivalent only when it preserves the same trigger, required or forbidden\n   action, scope, exceptions, and verification obligation. A positive general\n   rule does not replace a specific negative prohibition. Ordinary Codex competence,\n   implication, nearby prose, a Skill, or a canary is not evidence that any\n   explicit rule is preserved. Partial or implicit coverage is a regression.\n4. Never remove, weaken, merge away, or broaden an exception to a capability\n   unless the user explicitly authorizes that exact policy change. When\n   equivalence is uncertain, keep the existing rule.\n5. Before editing, capture a V0 policy baseline; then change one coherent\n   instruction group.\n6. Count a canary as passing only when its decision matches, every required\n   action and reason is present, and every action outside its complete\n   allowed-action set is absent. A partial forbidden-action list is\n   insufficient.\n7. Run all policy canaries and reject any critical regression. When the user\n   explicitly authorizes a case-contract change, name only that case with\n   `--authorized-contract-change`; every other changed or removed critical\n   contract remains a regression.\n8. Compare pass rate, duration, input tokens, and uncached input tokens with V0.\n   Accept only candidates that preserve correctness; efficiency improvements\n   count only after quality gates pass.\n9. If the same failure appears twice, add a focused case instead of generic\n   prose. Stop after five candidates or when no measurable improvement remains.\n10. After the canaries pass, complete the applicable simplification, internal\n    candidate review, finding-fix, and re-review steps in the Completion Loop\n    before handoff.\n\n## Response Style\n\n- Use plain language and the shortest response that fully answers the request.\n- Do not add details unless the user requests them or they are necessary.\n- When details are necessary, put a self-contained concise answer above a line\n  containing only `---` and the details below it. Omit the separator when no\n  details follow.\n\n## Authority and Safety\n\n- Answer, explain, review, diagnose, audit, and plan requests are read-only.\n  Inspect and report; do not edit the reviewed target.\n- Change, build, implement, and fix requests authorize the smallest in-scope\n  local production and test code edits plus non-destructive verification.\n  Documentation, configuration, scripts, generated artifacts, file deletion,\n  Docker cleanup, and system changes require explicit authorization in the\n  current task. A request that names the exact non-code target is authorization\n  for that target; do not ask again unless another gate below applies.\n- Preserve unrelated working-tree changes. Inspect `git status --short` before\n  editing and never discard work whose ownership is uncertain.\n\n### Git Is Read-Only by Default\n\nThe user owns every Git state change. Codex may use read-only Git commands such\nas `status`, `diff`, `show`, `log`, `blame`, `grep`, and `ls-files`.\n\nCodex may run a Git state-changing command only when the current request\nexplicitly authorizes that exact operation and its exact target. The\nauthorization applies only to that operation in the current task; it does not\nauthorize prerequisite, follow-up, adjacent, or future Git writes. Resolve the\ntarget with read-only inspection first and report the completed operation.\n\nWithout that exact authorization, never run a Git command that changes the\nindex, working tree, refs, remotes, branches, tags, stashes, worktrees, or\nsubmodules. This prohibition includes `add`, `commit`, `push`, `fetch`, `pull`,\n`merge`, `rebase`, `reset`, `restore`, `checkout`, `switch`, `clean`,\n`cherry-pick`, `revert`, branch or tag mutation, stash mutation, worktree\nmutation, and `submodule update`. Do not stage changes or use Git as a rollback\nmechanism.\n\nWhen a requested Git write lacks exact authorization, complete any separately\nauthorized local work, then provide a commit message or exact manual next step.\nProceed with the allowed parts of the request; omit the unauthorized Git\nmutation rather than refusing the entire task. A request for only a commit\nmessage is not authorization to commit.\n\n### Remote Writes and Sensitive Data\n\n- A local coding request never authorizes updating an issue, PR, review,\n  repository, deployment, production API, connector, cloud task, message, or\n  other remote state. Perform a remote write only when the current request\n  explicitly names the action and exact target.\n- For GitHub access, use the first configured token in this order: `GH_TOKEN`,\n  then `GITHUB_TOKEN`; check it without printing, logging, persisting, or\n  otherwise exposing its value. When a token is available, call the GitHub API\n  directly and do not search for, inspect, or invoke `gh`; use `gh` only when\n  neither token is configured.\n- Do not transmit credentials, tokens, private keys, private logs, proprietary\n  source, personal data, connection strings, or other sensitive repository data\n  outside the active user-authorized Codex task, including to websites, search\n  queries, connectors, plugins, MCP servers, review services, or external tools.\n  Redact sensitive values from commands, summaries, and retained artifacts.\n- Do not invoke an additional Codex task or external review service. The policy\n  harness in `.codex/harness/agents/` is the only exception: it may run a\n  separate isolated Codex task only with synthetic, non-sensitive policy cases\n  in a read-only, ephemeral environment. Do not include source, logs, task data,\n  or sensitive values in its prompt. Otherwise perform bounded self-review in\n  the active user-authorized Codex task.\n\n### Destructive and High-Risk Local Actions\n\nBefore deleting files or data, bulk-editing non-code artifacts, removing Docker\ncontainers, changing global configuration, permissions, or packages, or\nperforming another destructive local action:\n\n1. Resolve and inspect the exact targets with read-only commands.\n2. State the impact and whether recovery is reliable.\n3. Obtain explicit confirmation unless the user already authorized those exact\n   resolved targets and a reliable recovery path exists.\n\nA reliable recovery path is a verified backup or source plus concrete restore\nsteps, or a deterministic rebuild or re-download whose origin has been\nconfirmed. Git is a recovery path only when the current task separately\nauthorizes the exact restore operation. If the only copy would be lost, the\nsource is unknown, or recovery has not been verified, state that there is no\nreliable rollback and confirm again before acting. Never imply that an\nirreversible action is recoverable.\n\nFor Docker cleanup, distinguish reproducible images and containers from\npersistent volumes or local data. When Docker cleanup is in scope, Codex may\nremove images that inspection proves unused and reproducible without another\nconfirmation. This exception does not authorize removing containers, volumes,\nor local data, or an image whose source or reproducibility is uncertain.\n\nUse this prompt when confirmation is required:\n\n```text\nDangerous operation detected!\nOperation type: [specific action]\nScope of impact: [exact targets]\nRecovery: [verified steps, or \"no reliable rollback\"]\nRisk assessment: [potential consequence]\nPlease confirm whether to continue.\n```\n\n## Evidence, Scope, and Planning\n\nMaintain independent technical judgment. Do not agree with or adopt a\nuser-supplied premise, diagnosis, design, or conclusion merely because the user\nproposed or prefers it; treat it as a claim to evaluate. When such a claim could\nmaterially affect correctness, scope, compatibility, safety, or cost,\ndistinguish verified evidence from inference, assumption, and preference;\ninspect contradictions, missing constraints, unsupported causal links, and\nplausible alternatives.\n\nIf evidence contradicts the user's premise or is insufficient for the proposed\naction, say so before acting and state the decisive evidence, likely impact,\nand the minimum viable alternative, additional check, or decision needed. Do\nnot add generic caveats, expand scope or authority, or delay straightforward\nauthorized work merely to demonstrate skepticism.\n\nBefore editing:\n\n1. Restate the verifiable goal, non-goals, user-forbidden tools or APIs, and\n   coverage or output constraints.\n2. Inspect the affected code, tests, contracts, configuration, registrations,\n   module boundaries, closest maintained precedent, and applicable\n   instructions.\n3. Identify behavior owners, reuse opportunities, compatibility impact,\n   expected changed files, prohibited paths, required tests, and scoped\n   verification.\n4. Convert these items into a compact acceptance checklist and a 3–10 step plan\n   for non-trivial work.\n\n### Strict Scope and Task-Delta Gate\n\nApply this gate to every file-changing task and action, including changes made\nby formatters, generators, scripts, Skills, and review fixes, except a\nstandalone restoration or rollback governed by its existing gates.\n\nFor this gate, an active task is one independent, verifiable user objective,\nnot the permanent lifetime of a UI conversation. It includes every later turn\nand correction for that objective, including after a handoff. Only after the\nprevious objective is complete and the user explicitly requests an independent\nobjective may Codex capture a new baseline and freeze a new boundary. When a\nuser request could reasonably be either a follow-up or an independent\nobjective, remain read-only and confirm the task boundary before writing. An\nagent finding, review result, failure, or mention of another module is not an\nindependent objective and does not create that ambiguity.\n\n1. Derive the acceptance checklist only from user-requested outcomes, direct\n   prerequisites proven by inspected evidence, and focused regression\n   protection required by the Test Rules. Do not turn an agent-proposed\n   cleanup, refactor, generalization, consistency improvement, or adjacent fix\n   into an acceptance criterion.\n2. Treat a prerequisite as direct only when omitting it would prevent the\n   requested behavior, compilation, or scoped verification and no smaller\n   in-boundary alternative exists. Relevance, repository evidence, a test\n   failure, or a review finding may prove that expansion is required, but does\n   not authorize that expansion.\n3. Before the first write, record the pre-task working-tree baseline, including\n   the existing status and relevant diffs, then freeze the allowed files and\n   the allowed change intent for each file. An allowed file does not authorize\n   unrelated hunks in that file.\n4. For a file-changing request that is authorized to proceed, use initial\n   read-only analysis and, before the first write, derive the smallest owning\n   module or repository-path set from the user request and inspected evidence,\n   whether or not the user named it, then freeze it as the hard write allowlist\n   for the active Codex task. Later user turns, follow-up changes, reviews,\n   failures, and further inspection in that task do not reset or expand it.\n   Inspection and verification outside it remain read-only. Never edit any\n   other module, including a sibling, shared, dependency, parent, root, or\n   consuming module. Its code, tests, resources, configuration, build files,\n   and generated sources remain outside the write boundary unless the user\n   explicitly authorizes the exact additional module or path and its change\n   intent before the edit. Treat that authorization as an append-only\n   expansion: map it to an acceptance criterion, freeze only the smallest newly\n   authorized path and intent, and retain the original task baseline. Never\n   rebaseline an active task, infer whole-module authorization from an exact\n   file authorization, or treat an added path as blanket authorization. A\n   direct prerequisite does not self-authorize expansion. The allowlist is a\n   maximum boundary, not blanket authorization or a reason to repeat completed\n   work; every later edit still needs an unsatisfied acceptance criterion. Do\n   not repeat completed edits, checks, or reviews unless an authorized\n   in-boundary edit invalidates them.\n5. When the request makes the boundary clear, infer and freeze it without\n   asking the user to repeat it. The checklist is the maximum change boundary.\n   Every changed file and task-introduced hunk must map directly to one\n   acceptance criterion and be necessary to satisfy it.\n6. After each file-changing action, inspect the paths and hunks that action may\n   have changed before continuing. Tool-produced changes are task changes and\n   receive no scope exemption.\n7. If evidence proves that work outside the frozen boundary is required, stop\n   before that edit. Report the blocking evidence, smallest additional scope,\n   exact files or contracts, and consequence of declining it, then request\n   confirmation. Until expansion is authorized, limit outside-boundary work to\n   the read-only evidence needed for that report; do not start its design or\n   implementation workflow. Report other out-of-scope findings without fixing\n   them.\n8. After the last file-changing action, audit the task-introduced delta against\n   the pre-task baseline, not merely the aggregate working-tree diff. Preserve\n   every pre-existing user change and every later delta that cannot be proven\n   to result from a current-task write. Absence from the baseline does not prove\n   task ownership. Treat an unattributed delta as user-owned, do not overwrite,\n   format, remove, or roll it back, and stop the affected write path to report\n   the conflict. Remove only proven current-task changes that lack a direct\n   acceptance-criterion mapping; if precise removal is unsafe or a tool keeps\n   recreating them, stop and report the blocker.\n9. Hand off only when the audited task delta is the smallest correct change.\n   Summarize each remaining file as `file -> changed behavior -> acceptance\n   criterion -> necessity` so the user can verify the scope directly.\n\n### Unused and Removal Conclusions\n\nApply this gate to every analysis or change that classifies code, dependencies,\nconfiguration, resources, test support, or another repository artifact as\nunused or removable.\n\n1. Distinguish absence of direct references from complete unused evidence. A\n   single text or regex search, or a production-only search, proves at most that\n   no direct reference was found and cannot justify a removal recommendation.\n2. Inspect semantic and indirect consumers appropriate to the artifact,\n   including reflection, generated code, registrations, SPI and `ServiceLoader`,\n   JDBC driver discovery, Maven scopes, profiles, plugins and transitive\n   dependencies, build/test/runtime classpaths, test JARs, packaging and\n   distributions, tests, E2E, and external consumers.\n3. Inspect Git history and linked issue, pull-request, CI, and failure evidence\n   for prior additions, removals, and restorations. A prior removal failure\n   makes the artifact indirectly required unless same-boundary evidence proves\n   that the failure was unrelated or that the dependency is obsolete.\n4. Classify each examined artifact as directly used, indirectly required,\n   purpose unresolved, or a verified removal candidate. Use purpose unresolved\n   when evidence is incomplete. Use verified removal candidate only after a\n   controlled removal experiment, or equivalent existing evidence, covers the\n   affected compilation, tests, packaging, and runtime paths.\n\nChanges to public contracts, SPIs, extension or loading contracts, class or\nmethod `final`, visibility, inheritance, constructors or signatures, module\ndependencies, or shared-code ownership are architecture changes. Before such a\nchange, report:\n\n- current behavior and owner;\n- direct-reuse and delegation analysis;\n- compatibility impact;\n- minimum affected files and tests.\n\nAn exact architecture change explicitly requested by the user is authorized\nafter that report. If materially different ownership, architecture, or\ncompatibility choices remain unresolved, obtain confirmation. Adding,\nchanging, or removing an SPI always follows this gate.\n\nIf the user rejects a design, stop patching it. Remove only current-task changes\nthat are provably part of the rejected design, preserve unrelated work, and\nredesign from the last confirmed boundary. Restore through precise file edits\nunless the current task separately authorizes the exact Git restore operation.\n\n## Implementation Rules\n\n### Codex Design Style\n\nApply this section to every production, test, script, or other implementation\ncreated or changed within the authorized boundary. Treat an in-scope violation\nin the effective candidate as a required finding and fix it before handoff; do\nnot expand scope or rewrite unrelated existing code.\n\n- Within already-authorized designs, resolve trade-offs in this order: semantic\n  and contract correctness; correct behavior and module ownership; verified\n  compatibility and real boundaries; minimal conceptual surface and local\n  readability; consistency with maintained nearby code and direct reuse;\n  testability; then optional extensibility, formal symmetry, or structural\n  completeness. A lower-priority concern must not compromise a higher-priority\n  one. This order does not override authority, safety, scope, or architecture\n  gates.\n- Preserve existing architecture by default. Prefer direct reuse, then\n  composition or delegation, then an existing extension point. Do not invent a\n  boundary when no maintained precedent exists.\n- Use the smallest clear implementation and minimize conceptual surface rather\n  than line count. Prefer one readable local flow with the fewest independently\n  meaningful types, states, representations, execution paths, and cross-file\n  hops. Every added line, helper, abstraction, identifier, literal, guard, copy,\n  wrapper, and configuration entry must serve production behavior, a public\n  contract, regression protection, diagnostics, safety, readability, or removal\n  of real duplication. Do not add code for formal symmetry, coverage appearance,\n  structural completeness, hypothetical reuse, or test convenience. Avoid\n  unnecessary locals, thin wrappers, helpers, comments, guards, and copies;\n  inline single-use locals unless a name improves readability. Keep a name,\n  local variable, or extraction when it materially clarifies intent; do not\n  compress code mechanically.\n- A new abstraction must own production behavior, state, or a contract that\n  existing types cannot express and must represent a real, stable variation or\n  boundary. Define the narrowest contract, keep common behavior in its owner,\n  and isolate only true implementation or dialect differences. Forwarding,\n  renaming, multiple callers, readability alone, direct test value, symmetry,\n  type distinction, shorter call sites, test convenience, and anticipated reuse\n  are insufficient. Reuse alone never authorizes changing `final`, visibility,\n  inheritance, or shared-code ownership. Do not wrap a simple internal two-path\n  flow in marker interfaces, result hierarchies, or DTO-style helpers unless\n  they define a stable boundary, keep the owner readable, or remove meaningful\n  duplication. This rule does not bypass the architecture-change gate.\n- Do not introduce package-private top-level helper types by default. Keep a\n  small single-owner helper private and nested; add a top-level helper only when\n  the approved production behavior, state, or contract cannot reasonably be\n  owned by an existing type.\n- Do not add production types, widen visibility, remove `final`, or change\n  constructors or signatures for test convenience. Avoid accumulating multiple\n  nested collaborators inside one owner.\n- Keep only constructors with distinct production semantics or framework,\n  reflection, serialization, or SPI requirements. Update callers explicitly\n  instead of adding convenience or compatibility overloads. Before adding or\n  changing a constructor, inspect nearby production conventions for visibility,\n  Lombok, validation, and tests. Before handoff, scan changed call sites for\n  unused or compatibility-only constructors.\n- Before declaring code unused, inspect semantic usages and repository-wide\n  references, including method references, generated accessors, overrides,\n  reflection, registrations, tests, E2E, and external consumers.\n- Inspect every usage match; a single regex or production-only search is not\n  sufficient evidence. Make the change converge on one coherent model: correct\n  or replace the existing owner before adding a parallel path, then remove\n  superseded in-scope representations, paths, adapters, shims, tests,\n  configuration, and other obsolete code after verifying usages and contracts.\n  Keep coexistence only for a verified compatibility contract. If convergence\n  exceeds the acceptance checklist or file-type authorization, stop at the\n  existing gate. Do not leave placeholders, TODO implementations, speculative\n  compatibility shims, or test-only production hooks.\n- When adding a database, dialect, plugin, or module, reuse the applicable\n  framework and extension mechanisms. Keep derived dialects aligned with shared\n  behavior and isolate only real differences. If no maintained precedent\n  exists, record the search evidence before using the architecture gate.\n- Reuse or create an SPI only when its contract matches the required production\n  behavior. One caller, one implementation, code sharing, type distinction,\n  symmetry, anticipated reuse, or test convenience does not establish an SPI\n  contract.\n\n### Validation and Exceptions\n\n- Add runtime validation only at real external, public, persisted, parsed, SPI,\n  reflection, shared-state, or asynchronous boundaries, or for a concrete\n  diagnostic benefit. Do not recheck invariants guaranteed by callers or\n  upstream contracts.\n- Prefer `ShardingSpherePreconditions` with lazy exception suppliers when the\n  module can use it and the resulting control flow preserves the required\n  exception type, message, timing, and cause.\n- Keep a manual throw when the module cannot depend on `infra/exception`, the\n  code is inside `ShardingSpherePreconditions`, a caller-facing exception\n  contract requires it, or a precondition wrapper would obscure necessary\n  control flow. Do not replace manual throws mechanically, and record the\n  concrete reason for keeping one.\n- When an edit removes the last checked-exception source from a private or\n  internal method, remove the stale `throws` declaration and update callers.\n  Keep checked exceptions on public or overridden methods only when a\n  caller-facing, framework, external API, or compatibility contract requires\n  them. Never widen to generic `Exception` or `Throwable`.\n\n### Repository Style\n\n- Apply the `CODE_OF_CONDUCT.md` Lombok preference to touched boilerplate when\n  generated semantics are equivalent. Use narrow annotations; never use broad\n  annotations such as `@Data` unless every generated behavior is required.\n  Before replacing a public constructor or accessor, verify its generated\n  signature, access, parameter order, annotations, and reflection or\n  serialization behavior. Keep a manual member when Lombok would change or\n  obscure logic, documentation, validation, defaults, side effects,\n  compatibility, framework semantics, or a public contract.\n- Keep public API and SPI Javadocs required by the code of conduct. Beyond that,\n  document only caller or implementer obligations not expressed by code. Do not\n  restate names, signatures, visible collection properties, or inherited\n  contracts unless an override adds a new obligation.\n- Keep declarations near first use. Do not mark local, loop, resource, or\n  lambda variables `final`; use `final` only for method, constructor, and\n  `catch` parameters when applicable.\n- Declare collections by the least-specific required contract. Do not copy or\n  wrap collections without an owned mutability, snapshot, isolation, or public\n  contract reason. Record the concrete reason for every explicit copy or\n  wrapper. Use `Collection` for common iteration, size, or emptiness operations;\n  use `List` only for positional, ordered, duplicate-preserving, or required API\n  semantics; use `Set` only for uniqueness or set semantics. Do not declare a\n  concrete collection type unless its implementation-specific API is required.\n  In tests, create a mutable copy only when that instance is mutated or\n  mutability is the scenario.\n- Add a YAML anchor only when aliases in the same file remove meaningful\n  duplication.\n- Use repository-relative paths, configuration, or temporary directories in\n  code, tests, scripts, and Skills; never hard-code a local workspace path.\n- Add the ASF license header to new source files and keep implementation intent\n  and reviewer-relevant rationale transparent.\n- Account for compatibility, security, time and space complexity, I/O, memory,\n  resource lifecycle, concurrency, and boundary failures when the affected\n  path makes them relevant.\n\n## Test Rules\n\n- Test behavior owned by the production class: computation, decisions,\n  validation, transformation, state transitions, error handling, or external\n  contracts. Each test must fail for a realistic regression that matters. Do\n  not add a dedicated test for a pass-through, constant, accessor, or wiring\n  method unless that behavior is itself a documented public or externally\n  visible contract.\n- Never add tests whose subject is another test case, a test class or method,\n  test fixture, mock helper, test utility, or other test-only code. Test only\n  the production behavior that the test-only code supports. Test-support code\n  distributed as an independent artifact with an external contract is\n  production code for this rule.\n- Do not add tests that only prove constants, accessors, delegation, wiring,\n  Java, Lombok, Mockito, parsers, collection libraries, framework behavior, or\n  private implementation shape. Contract literals are exceptions only when no\n  broader behavior can protect them. Never add a test solely to increase a\n  coverage number. Do not duplicate an existing scenario unless the new test\n  covers a new branch, input class, edge case, contract, calculation path, or\n  failure mode.\n- Do not test collaborator rules through the current class. Mock the nearest\n  stable boundary and test the collaborator rule in its owner. Cross-layer\n  behavior belongs in an explicitly scoped integration, contract, or E2E test.\n- Give each behavior-owning public production method focused coverage. Each\n  test method covers one scenario and invokes the target public method at most\n  once; repeat only when the same scenario requires additional assertions. Do\n  not create interface-only tests; exercise concrete implementations.\n- Every new public production type requires direct focused tests, except\n  exception types covered by `Exception Tests`. Broad workflow tests do not\n  replace them unless they explicitly exercise that type's public behavior. If\n  a pure pass-through public type has no meaningful owned or external contract\n  to test, do not add the type merely for structural completeness.\n- Default to direct Mockito mocks. Use a private helper only for repeated local\n  setup and a standalone fixture only for a stable external or packaged test\n  boundary. Give fixtures the narrowest practical visibility, keep them in the\n  nearest owning test package or module, and do not create cross-module test\n  APIs for convenience. Delete or inline thin mock wrappers.\n- Obtain SPI implementations through the project loader by default. Use\n  `Plugins.getMemberAccessor()` for permitted field access; direct reflection\n  APIs and reflective invocation of private methods are forbidden. If the class\n  under test implements `TypedSPI` or `DatabaseTypedSPI`, instantiate it through\n  `TypedSPILoader` or `DatabaseTypedSPILoader`, not with `new`.\n- Prefer `AutoMockExtension` and its static or construction mocking support.\n  Use direct `mockStatic` or `mockConstruction` only when the extension cannot\n  apply and the reason is recorded; scope it with try-with-resources. When a\n  class is listed in `@StaticMockSettings`, do not call `mockStatic` or\n  `mockConstruction` for it; stub it through `when(...)`.\n- Do not mix Mockito matchers with raw arguments in one invocation. Mock\n  databases, caches, registries, network calls, time, and other heavy external\n  dependencies instead of constructing deep unrelated object graphs.\n- Every unit-test class must be named `<ProductionClassName>Test`, using the\n  exact simple name of the production class it directly tests. This class-name\n  rule is mandatory and is independent of scenario-focused test-method naming.\n- Parameterized tests must set `name = \"{0}\"`. Keep test names concise and\n  scenario-focused, following `CODE_OF_CONDUCT.md`; avoid `ReturnsXXX` and\n  wording that restates the expected result instead of naming the scenario.\n- Use JUnit 5 and Mockito. Keep setup, action, and assertions distinct; reset\n  static state between scenarios and reuse existing swappers or helpers for\n  complex configuration.\n- When a coverage target is stated, list every branch or path before coding and\n  map each one to exactly one planned test. Add cases until every declared\n  branch is covered or explicitly waived, update the map when code changes, and\n  verify with JaCoCo when coverage is uncertain. Document unreachable code\n  instead of adding redundant tests.\n\n### Exception Tests\n\n- Do not add dedicated tests for exception classes that only declare\n  constructors or format and forward their arguments to a tested superclass.\n  Add direct tests only for owned validation, branching, calculation,\n  conversion, or a known regression.\n\n## Specialized Workflows\n\n### Repository Workflows\n\nUse the matching repository Skill when its trigger applies:\n\n- Issue diagnosis and copy-ready maintainer replies: `$analyze-issue`.\n- Unit-test generation or systematic coverage work: `$gen-ut`.\n- PR correctness, side effects, mergeability, GitHub review replies, or the\n  pre-handoff review of an authorized implementation targeting an existing PR:\n  `$review-pr`. For pre-handoff review, use its Local Candidate Preflight Mode.\n\nIf a matching repository Skill is unavailable, apply an equivalent manual\nchecklist, record the fallback in the plan or final response, and continue\nwithout installing it. Do not create a new Skill merely to hold task-specific\ninstructions.\n\n### Optional Cross-Cutting Skills\n\nThe Skills in this subsection are optional workflow accelerators, not\nprerequisites. Availability alone is not a trigger. When an optional Skill is\navailable and its trigger below applies, prefer it and use only the smallest\nmatching Skill set. If it is unavailable, skip the Skill itself and continue\nwith the applicable repository gates and ordinary workflow. Do not install,\ncreate, reconstruct, or treat the absence of an optional Skill as a blocker.\nMention the absence only when the user explicitly requested the Skill or it\nleaves a material residual risk.\n\nSkipping a Skill never waives compatibility, correctness, security, scope,\nverification, or completion requirements. Using a Skill never expands the\nfrozen task scope, allowed modules or files, acceptance checklist, write or\nremote authority, Git authority, or tool permissions. This guide prevails when\na Skill conflicts with it.\n\n- Implementation or review whose correctness depends on the current version of\n  an external framework or library: use `$source-driven-development` when\n  available. Identify the applicable version from repository dependency\n  metadata, verify the relevant decision against authoritative primary\n  documentation, record the source, and mark anything that cannot be verified\n  as unverified. This verification remains required without the Skill. Do not\n  invoke it for version-independent local logic.\n- Designing, adding, or changing a public API, SPI, extension, loading or\n  registration contract, module boundary, externally visible interface, or\n  cross-module type contract: use `$api-and-interface-design` when available\n  before implementation. Apply the Architecture change and Contract and Impact\n  gates whether or not the Skill is available; using it does not authorize the\n  change or expand the confirmed scope.\n- An unexpected test, build, runtime, or behavior failure: use\n  `$debugging-and-error-recovery` when available. Stop unrelated implementation,\n  preserve evidence, reproduce, localize, reduce, identify the root cause, and\n  verify the result. Add focused regression protection only when the root cause\n  is an in-scope production defect and the test protects meaningful owned\n  behavior; do not add a test for an environment, infrastructure, or unrelated\n  failure. A failure never authorizes an out-of-boundary fix or a Git write.\n- An explicit performance requirement, reproducible reported slowness or\n  suspected regression, profiling evidence, or a requested change that can\n  materially alter the cost of a confirmed performance-sensitive path: use\n  `$performance-optimization` when available to measure first. A path being\n  high-volume by itself is not a trigger. Freeze the workload, metric,\n  environment, and baseline; identify the owning bottleneck before editing;\n  test one hypothesis at a time; and repeat the same measurement with\n  correctness checks. Keep a change only when the improvement exceeds\n  run-to-run variance and correctness remains intact. Remove neutral, worse,\n  or incorrect current-task experiments. Record attempts in the task unless an\n  exact file or remote target is separately authorized. Do not optimize by\n  intuition or follow adjacent hotspots outside the frozen boundary.\n- After scoped behavior and checks pass, when the effective task delta contains\n  concrete unnecessary complexity or a review identifies it: use\n  `$code-simplification` when available on that delta only. Preserve behavior\n  exactly and never perform a drive-by refactor or gain Git authority from the\n  Skill. Do not invoke it merely because the Completion Loop is running or when\n  the candidate is already clear.\n- An explicit user request to threat model a repository or path, enumerate\n  threats or abuse paths, or perform AppSec threat modeling: use\n  `$security-threat-model` when available. Do not invoke it for an ordinary\n  architecture summary, code review, security check, or non-security design.\n  The request remains read-only unless the user also authorizes the exact\n  output file; the Skill's default artifact creation grants no write authority.\n- A non-trivial decision involving module boundaries, public contracts,\n  unfamiliar code, or high-risk behavior, or a branching invariant that is not\n  directly established by types, existing tests, or an explicit contract and\n  whose failure would materially affect correctness, compatibility, security,\n  or another high-risk behavior: use `$doubt-driven-development` when available\n  only within the active task. An ordinary branch is not a trigger. The\n  prohibition on additional Codex tasks and external review overrides its\n  fresh-context and cross-model steps. Perform bounded adversarial self-review\n  instead and do not report the full Skill as completed.\n\nDo not include sensitive repository data in external searches.\n\n## Contract and Impact Gates\n\n- For a public or externally visible identifier, search all affected reference\n  surfaces: APIs, SQL, configuration and YAML keys, SPIs, errors, CLI commands,\n  resources, documentation, examples, distributions, tests, E2E, and\n  baselines. Exclude `.git` and `target`. If a compatibility alias remains,\n  state whether it is discoverable; if it must stay hidden, protect that\n  contract with a focused test or check.\n- Name the affected database engines and dialects and preserve backward\n  compatibility for their supported versions unless an exact compatibility\n  break is authorized.\n- For errors, logs, HTTP or JSON payloads, CLI output, and exception conversion,\n  test the complete external output when it could expose credentials, tokens,\n  connection strings, SQL, paths, or user data.\n- Regenerate or verify affected snapshots, golden files, fingerprints, SQL\n  cases, descriptors, schemas, and agent-visible metadata with the existing\n  project tool.\n- Determine affected GitHub Actions from changed-file path filters and job\n  commands. Run the local equivalent when practical; otherwise record the\n  narrower check and residual risk. Do not update remote workflow state.\n- When runtime paths change, record relevant engine or dialect compatibility\n  and a performance baseline or guardrail. When governance, registry,\n  observability, or agent integrations are touched, state their impact.\n\n## Runtime Triage\n\n- For Proxy startup, prefer the existing IDE/MCP `Bootstrap` configuration or a\n  scoped `proxy` package with explicit upstream modules. Record the\n  configuration path, mode, ports, command, and exit code.\n- For JDBC smoke tests, use a current-source IDE/MCP run or a focused `jdbc`\n  module test with explicit upstream modules and datasource setup.\n- Keep standalone `server.yaml` and affected cluster `mode/` configuration\n  behavior aligned; call out default changes.\n- For startup, routing, or runtime failures, inspect `proxy/logs/` and relevant\n  `target/surefire-reports`; correlate decisive lines with configuration,\n  metadata freshness, parser dialect, and the owning data-flow step. For routing\n  failures, also inspect feature-rule configuration and report the SQL, relevant\n  configuration, owning module, and focused test. Do not edit generated output.\n- For a sandbox or network denial, report the command, failure, and safe\n  alternative or required authorization.\n- When an E2E, integration, client smoke, or Docker smoke fails, hangs, or times\n  out, stop rerunning. Classify it as environment, classpath, stale snapshot,\n  dependency, test design, protocol implementation, data setup, assertion\n  logic, or external-service behavior, then record evidence and minimum fix\n  scope before changing code or configuration. Complete deterministic\n  prerequisites such as classpath consistency, stale-bytecode checks, dependency\n  alignment, or required evidence capture before running one matching sentinel;\n  if it fails unexpectedly, return to analysis.\n\n## Verification and Commands\n\nRun the narrowest meaningful checks first. Derive explicit Maven modules from\nchanged owners, affected tests, and consuming runtime modules.\n\n- Focused test:\n  `./mvnw -pl <module> -DskipITs -Dspotless.skip=true\n  -Dtest=<FullyQualifiedTestClassName>\n  -Dsurefire.failIfNoSpecifiedTests=false test`\n- Scoped tests: `./mvnw test -pl <explicit-module-set>`\n- Scoped package:\n  `./mvnw -pl <explicit-module-set> -DskipTests package`\n- Coverage:\n  `./mvnw -pl <explicit-module-set> -Djacoco.skip=false test jacoco:report`\n- Full build: `./mvnw clean install -B -T1C -Pcheck`\n\nPrefer current-source IDE/MCP runs or explicit `-pl` module sets. Use `-am`\nonly when dependency freshness, missing reactor artifacts, or CI equivalence\ncannot otherwise be established, normally once per unchanged task state. For\nmulti-module checks, verify lower-level changed owners before their higher-level\nconsumers.\n\nKeep background unit tests under 60 seconds. Capture high-volume output\naccording to `.codex/context/token-efficiency.md`; report commands, exit codes,\nand decisive log excerpts instead of dumping raw logs.\n\nFor every user-forbidden tool, API, assertion, or pattern, run a scoped final\nsearch and report the command and result. Do not rely only on plan compliance.\n\nAfter the last file-changing action:\n\n1. Run `./mvnw spotless:apply -Pcheck -T1C` for code or documentation changes.\n2. Run `./mvnw checkstyle:check -Pcheck -T1C` when production, test, or\n   project-rule files changed.\n3. Do not manually reformat afterward. Any later edit invalidates formatting\n   and requires the applicable checks again.\n\n## Completion Loop\n\nFor an authorized change, build, implement, or fix request, excluding a\nstandalone restoration or rollback:\n\n1. Compare the task-introduced delta with the recorded pre-edit baseline, the\n   read-only `git diff`, surrounding context, and the acceptance checklist.\n2. Confirm every task-introduced file and hunk is necessary, expected changed\n   files contain only their frozen change intent, prohibited paths have zero\n   task delta, direct reuse was considered, architecture changes were\n   authorized, and every test protects owned behavior. Inspect Java changes for\n   newly added local-variable `final`, scan changed code and Skills for local\n   absolute paths, and remove only current-task violations.\n3. Treat scripts, searches, formatting, compilation, and passing tests as\n   evidence, not proof of semantic compliance. Judge the final behavior,\n   contracts, architecture, and user request directly; fix every safe in-scope\n   violation instead of reporting it as an accepted risk.\n4. Apply `$code-simplification` under Optional Cross-Cutting Skills only when\n   its concrete complexity trigger is present and the Skill is available. Do\n   not invoke it merely because this loop is running; a clear task delta or an\n   unavailable Skill does not block handoff.\n5. Review the effective local candidate against the same code-correctness gates\n   used by `$review-pr`: root cause and fix mapping, affected behavior, side\n   effects and regressions, contracts and architecture, test validity, and\n   adversarial cases. Apply `$code-review-and-quality` when available, or its\n   equivalent review, for the general quality axes; it does not replace these\n   shared correctness gates.\n6. When the implementation targets an existing PR, also apply `$review-pr` in\n   Local Candidate Preflight Mode before handoff. PR-specific public-head and\n   remote-evidence checks remain part of formal PR review.\n7. Fix every safe in-scope required finding, rerun invalidated checks, and\n   repeat the applicable reviews. If a finding requires scope expansion, an\n   unresolved architecture choice, or a high-risk action, stop at its existing\n   authorization gate instead of fixing it automatically.\n8. Hand off and propose a commit message only after one complete applicable\n   review pass finds zero new required issues. Before that review passes, do not\n   hand off or propose a commit message. Do not defer a locally discoverable\n   required finding to a later formal PR review.\n9. Stop when no required in-scope finding remains. Do not iterate for optional\n   polish, broad cleanup, or risky refactoring.\n\nIf a report or verdict is disproved, fix the highest-leverage rule, schema,\nvalidator, prompt, or regression case before correcting the artifact, unless\nthe user explicitly requests a one-off correction.\n\nThe final response must lead with the outcome and include changed files and\nrationale, commands with exit codes, verification status, remaining risks, and\nthe next action only when one is still required. When Git commit authorization\nis absent, provide a proposed commit message without staging or committing.\n"},"files":{"AGENTS.md":"# ShardingSphere Codex Development Guide\n\nThis repository guide is written for Codex. Keep only stable, repository-wide\nrules here and rely on Codex for ordinary coding competence. Follow every\nexplicit rule literally; do not replace a repository rule with general judgment\nunless that rule authorizes it. Paths are relative to the repository root.\n\n## Instruction Sources\n\n1. `CODE_OF_CONDUCT.md` is the authority for contribution, Java, and unit-test\n   style. Inspect the applicable section before changing code or tests and\n   record it when it controls a decision.\n2. Before Maven, E2E, Proxy startup, database clients, IDE/MCP run\n   configurations, commands likely to output more than 100 lines, or large\n   structured analysis, read or reuse\n   `.codex/context/token-efficiency.md` and follow its Mandatory Execution\n   Contract.\n3. Use repository Skills for specialized workflows instead of reproducing their\n   detailed instructions here.\n4. Keep task-specific notes in the task, issue, or PR. Do not add session notes\n   to this file.\n\n### Changing This Guide\n\nFor changes to this guide, use `.codex/harness/agents/`. `cases.toml` is the\nsource of the harness catalog: each case records its group, purpose, enforcement\nphase, and whether the ordinary completion loop rechecks it. Run\n`python3 .codex/harness/agents/run.py --list-cases` to render the table.\n\n1. Treat every explicit requirement, prohibition, exception, authorization\n   boundary, and verification step as an independent policy capability.\n2. Before editing, build an old-to-new capability ledger and classify every\n   capability as exactly preserved, changed with the user's explicit\n   authorization in the current task, or restored before handoff.\n3. Reconcile every deleted or weakened rule explicitly. A replacement is\n   equivalent only when it preserves the same trigger, required or forbidden\n   action, scope, exceptions, and verification obligation. A positive general\n   rule does not replace a specific negative prohibition. Ordinary Codex competence,\n   implication, nearby prose, a Skill, or a canary is not evidence that any\n   explicit rule is preserved. Partial or implicit coverage is a regression.\n4. Never remove, weaken, merge away, or broaden an exception to a capability\n   unless the user explicitly authorizes that exact policy change. When\n   equivalence is uncertain, keep the existing rule.\n5. Before editing, capture a V0 policy baseline; then change one coherent\n   instruction group.\n6. Count a canary as passing only when its decision matches, every required\n   action and reason is present, and every action outside its complete\n   allowed-action set is absent. A partial forbidden-action list is\n   insufficient.\n7. Run all policy canaries and reject any critical regression. When the user\n   explicitly authorizes a case-contract change, name only that case with\n   `--authorized-contract-change`; every other changed or removed critical\n   contract remains a regression.\n8. Compare pass rate, duration, input tokens, and uncached input tokens with V0.\n   Accept only candidates that preserve correctness; efficiency improvements\n   count only after quality gates pass.\n9. If the same failure appears twice, add a focused case instead of generic\n   prose. Stop after five candidates or when no measurable improvement remains.\n10. After the canaries pass, complete the applicable simplification, internal\n    candidate review, finding-fix, and re-review steps in the Completion Loop\n    before handoff.\n\n## Response Style\n\n- Use plain language and the shortest response that fully answers the request.\n- Do not add details unless the user requests them or they are necessary.\n- When details are necessary, put a self-contained concise answer above a line\n  containing only `---` and the details below it. Omit the separator when no\n  details follow.\n\n## Authority and Safety\n\n- Answer, explain, review, diagnose, audit, and plan requests are read-only.\n  Inspect and report; do not edit the reviewed target.\n- Change, build, implement, and fix requests authorize the smallest in-scope\n  local production and test code edits plus non-destructive verification.\n  Documentation, configuration, scripts, generated artifacts, file deletion,\n  Docker cleanup, and system changes require explicit authorization in the\n  current task. A request that names the exact non-code target is authorization\n  for that target; do not ask again unless another gate below applies.\n- Preserve unrelated working-tree changes. Inspect `git status --short` before\n  editing and never discard work whose ownership is uncertain.\n\n### Git Is Read-Only by Default\n\nThe user owns every Git state change. Codex may use read-only Git commands such\nas `status`, `diff`, `show`, `log`, `blame`, `grep`, and `ls-files`.\n\nCodex may run a Git state-changing command only when the current request\nexplicitly authorizes that exact operation and its exact target. The\nauthorization applies only to that operation in the current task; it does not\nauthorize prerequisite, follow-up, adjacent, or future Git writes. Resolve the\ntarget with read-only inspection first and report the completed operation.\n\nWithout that exact authorization, never run a Git command that changes the\nindex, working tree, refs, remotes, branches, tags, stashes, worktrees, or\nsubmodules. This prohibition includes `add`, `commit`, `push`, `fetch`, `pull`,\n`merge`, `rebase`, `reset`, `restore`, `checkout`, `switch`, `clean`,\n`cherry-pick`, `revert`, branch or tag mutation, stash mutation, worktree\nmutation, and `submodule update`. Do not stage changes or use Git as a rollback\nmechanism.\n\nWhen a requested Git write lacks exact authorization, complete any separately\nauthorized local work, then provide a commit message or exact manual next step.\nProceed with the allowed parts of the request; omit the unauthorized Git\nmutation rather than refusing the entire task. A request for only a commit\nmessage is not authorization to commit.\n\n### Remote Writes and Sensitive Data\n\n- A local coding request never authorizes updating an issue, PR, review,\n  repository, deployment, production API, connector, cloud task, message, or\n  other remote state. Perform a remote write only when the current request\n  explicitly names the action and exact target.\n- For GitHub access, use the first configured token in this order: `GH_TOKEN`,\n  then `GITHUB_TOKEN`; check it without printing, logging, persisting, or\n  otherwise exposing its value. When a token is available, call the GitHub API\n  directly and do not search for, inspect, or invoke `gh`; use `gh` only when\n  neither token is configured.\n- Do not transmit credentials, tokens, private keys, private logs, proprietary\n  source, personal data, connection strings, or other sensitive repository data\n  outside the active user-authorized Codex task, including to websites, search\n  queries, connectors, plugins, MCP servers, review services, or external tools.\n  Redact sensitive values from commands, summaries, and retained artifacts.\n- Do not invoke an additional Codex task or external review service. The policy\n  harness in `.codex/harness/agents/` is the only exception: it may run a\n  separate isolated Codex task only with synthetic, non-sensitive policy cases\n  in a read-only, ephemeral environment. Do not include source, logs, task data,\n  or sensitive values in its prompt. Otherwise perform bounded self-review in\n  the active user-authorized Codex task.\n\n### Destructive and High-Risk Local Actions\n\nBefore deleting files or data, bulk-editing non-code artifacts, removing Docker\ncontainers, changing global configuration, permissions, or packages, or\nperforming another destructive local action:\n\n1. Resolve and inspect the exact targets with read-only commands.\n2. State the impact and whether recovery is reliable.\n3. Obtain explicit confirmation unless the user already authorized those exact\n   resolved targets and a reliable recovery path exists.\n\nA reliable recovery path is a verified backup or source plus concrete restore\nsteps, or a deterministic rebuild or re-download whose origin has been\nconfirmed. Git is a recovery path only when the current task separately\nauthorizes the exact restore operation. If the only copy would be lost, the\nsource is unknown, or recovery has not been verified, state that there is no\nreliable rollback and confirm again before acting. Never imply that an\nirreversible action is recoverable.\n\nFor Docker cleanup, distinguish reproducible images and containers from\npersistent volumes or local data. When Docker cleanup is in scope, Codex may\nremove images that inspection proves unused and reproducible without another\nconfirmation. This exception does not authorize removing containers, volumes,\nor local data, or an image whose source or reproducibility is uncertain.\n\nUse this prompt when confirmation is required:\n\n```text\nDangerous operation detected!\nOperation type: [specific action]\nScope of impact: [exact targets]\nRecovery: [verified steps, or \"no reliable rollback\"]\nRisk assessment: [potential consequence]\nPlease confirm whether to continue.\n```\n\n## Evidence, Scope, and Planning\n\nMaintain independent technical judgment. Do not agree with or adopt a\nuser-supplied premise, diagnosis, design, or conclusion merely because the user\nproposed or prefers it; treat it as a claim to evaluate. When such a claim could\nmaterially affect correctness, scope, compatibility, safety, or cost,\ndistinguish verified evidence from inference, assumption, and preference;\ninspect contradictions, missing constraints, unsupported causal links, and\nplausible alternatives.\n\nIf evidence contradicts the user's premise or is insufficient for the proposed\naction, say so before acting and state the decisive evidence, likely impact,\nand the minimum viable alternative, additional check, or decision needed. Do\nnot add generic caveats, expand scope or authority, or delay straightforward\nauthorized work merely to demonstrate skepticism.\n\nBefore editing:\n\n1. Restate the verifiable goal, non-goals, user-forbidden tools or APIs, and\n   coverage or output constraints.\n2. Inspect the affected code, tests, contracts, configuration, registrations,\n   module boundaries, closest maintained precedent, and applicable\n   instructions.\n3. Identify behavior owners, reuse opportunities, compatibility impact,\n   expected changed files, prohibited paths, required tests, and scoped\n   verification.\n4. Convert these items into a compact acceptance checklist and a 3–10 step plan\n   for non-trivial work.\n\n### Strict Scope and Task-Delta Gate\n\nApply this gate to every file-changing task and action, including changes made\nby formatters, generators, scripts, Skills, and review fixes, except a\nstandalone restoration or rollback governed by its existing gates.\n\nFor this gate, an active task is one independent, verifiable user objective,\nnot the permanent lifetime of a UI conversation. It includes every later turn\nand correction for that objective, including after a handoff. Only after the\nprevious objective is complete and the user explicitly requests an independent\nobjective may Codex capture a new baseline and freeze a new boundary. When a\nuser request could reasonably be either a follow-up or an independent\nobjective, remain read-only and confirm the task boundary before writing. An\nagent finding, review result, failure, or mention of another module is not an\nindependent objective and does not create that ambiguity.\n\n1. Derive the acceptance checklist only from user-requested outcomes, direct\n   prerequisites proven by inspected evidence, and focused regression\n   protection required by the Test Rules. Do not turn an agent-proposed\n   cleanup, refactor, generalization, consistency improvement, or adjacent fix\n   into an acceptance criterion.\n2. Treat a prerequisite as direct only when omitting it would prevent the\n   requested behavior, compilation, or scoped verification and no smaller\n   in-boundary alternative exists. Relevance, repository evidence, a test\n   failure, or a review finding may prove that expansion is required, but does\n   not authorize that expansion.\n3. Before the first write, record the pre-task working-tree baseline, including\n   the existing status and relevant diffs, then freeze the allowed files and\n   the allowed change intent for each file. An allowed file does not authorize\n   unrelated hunks in that file.\n4. For a file-changing request that is authorized to proceed, use initial\n   read-only analysis and, before the first write, derive the smallest owning\n   module or repository-path set from the user request and inspected evidence,\n   whether or not the user named it, then freeze it as the hard write allowlist\n   for the active Codex task. Later user turns, follow-up changes, reviews,\n   failures, and further inspection in that task do not reset or expand it.\n   Inspection and verification outside it remain read-only. Never edit any\n   other module, including a sibling, shared, dependency, parent, root, or\n   consuming module. Its code, tests, resources, configuration, build files,\n   and generated sources remain outside the write boundary unless the user\n   explicitly authorizes the exact additional module or path and its change\n   intent before the edit. Treat that authorization as an append-only\n   expansion: map it to an acceptance criterion, freeze only the smallest newly\n   authorized path and intent, and retain the original task baseline. Never\n   rebaseline an active task, infer whole-module authorization from an exact\n   file authorization, or treat an added path as blanket authorization. A\n   direct prerequisite does not self-authorize expansion. The allowlist is a\n   maximum boundary, not blanket authorization or a reason to repeat completed\n   work; every later edit still needs an unsatisfied acceptance criterion. Do\n   not repeat completed edits, checks, or reviews unless an authorized\n   in-boundary edit invalidates them.\n5. When the request makes the boundary clear, infer and freeze it without\n   asking the user to repeat it. The checklist is the maximum change boundary.\n   Every changed file and task-introduced hunk must map directly to one\n   acceptance criterion and be necessary to satisfy it.\n6. After each file-changing action, inspect the paths and hunks that action may\n   have changed before continuing. Tool-produced changes are task changes and\n   receive no scope exemption.\n7. If evidence proves that work outside the frozen boundary is required, stop\n   before that edit. Report the blocking evidence, smallest additional scope,\n   exact files or contracts, and consequence of declining it, then request\n   confirmation. Until expansion is authorized, limit outside-boundary work to\n   the read-only evidence needed for that report; do not start its design or\n   implementation workflow. Report other out-of-scope findings without fixing\n   them.\n8. After the last file-changing action, audit the task-introduced delta against\n   the pre-task baseline, not merely the aggregate working-tree diff. Preserve\n   every pre-existing user change and every later delta that cannot be proven\n   to result from a current-task write. Absence from the baseline does not prove\n   task ownership. Treat an unattributed delta as user-owned, do not overwrite,\n   format, remove, or roll it back, and stop the affected write path to report\n   the conflict. Remove only proven current-task changes that lack a direct\n   acceptance-criterion mapping; if precise removal is unsafe or a tool keeps\n   recreating them, stop and report the blocker.\n9. Hand off only when the audited task delta is the smallest correct change.\n   Summarize each remaining file as `file -> changed behavior -> acceptance\n   criterion -> necessity` so the user can verify the scope directly.\n\n### Unused and Removal Conclusions\n\nApply this gate to every analysis or change that classifies code, dependencies,\nconfiguration, resources, test support, or another repository artifact as\nunused or removable.\n\n1. Distinguish absence of direct references from complete unused evidence. A\n   single text or regex search, or a production-only search, proves at most that\n   no direct reference was found and cannot justify a removal recommendation.\n2. Inspect semantic and indirect consumers appropriate to the artifact,\n   including reflection, generated code, registrations, SPI and `ServiceLoader`,\n   JDBC driver discovery, Maven scopes, profiles, plugins and transitive\n   dependencies, build/test/runtime classpaths, test JARs, packaging and\n   distributions, tests, E2E, and external consumers.\n3. Inspect Git history and linked issue, pull-request, CI, and failure evidence\n   for prior additions, removals, and restorations. A prior removal failure\n   makes the artifact indirectly required unless same-boundary evidence proves\n   that the failure was unrelated or that the dependency is obsolete.\n4. Classify each examined artifact as directly used, indirectly required,\n   purpose unresolved, or a verified removal candidate. Use purpose unresolved\n   when evidence is incomplete. Use verified removal candidate only after a\n   controlled removal experiment, or equivalent existing evidence, covers the\n   affected compilation, tests, packaging, and runtime paths.\n\nChanges to public contracts, SPIs, extension or loading contracts, class or\nmethod `final`, visibility, inheritance, constructors or signatures, module\ndependencies, or shared-code ownership are architecture changes. Before such a\nchange, report:\n\n- current behavior and owner;\n- direct-reuse and delegation analysis;\n- compatibility impact;\n- minimum affected files and tests.\n\nAn exact architecture change explicitly requested by the user is authorized\nafter that report. If materially different ownership, architecture, or\ncompatibility choices remain unresolved, obtain confirmation. Adding,\nchanging, or removing an SPI always follows this gate.\n\nIf the user rejects a design, stop patching it. Remove only current-task changes\nthat are provably part of the rejected design, preserve unrelated work, and\nredesign from the last confirmed boundary. Restore through precise file edits\nunless the current task separately authorizes the exact Git restore operation.\n\n## Implementation Rules\n\n### Codex Design Style\n\nApply this section to every production, test, script, or other implementation\ncreated or changed within the authorized boundary. Treat an in-scope violation\nin the effective candidate as a required finding and fix it before handoff; do\nnot expand scope or rewrite unrelated existing code.\n\n- Within already-authorized designs, resolve trade-offs in this order: semantic\n  and contract correctness; correct behavior and module ownership; verified\n  compatibility and real boundaries; minimal conceptual surface and local\n  readability; consistency with maintained nearby code and direct reuse;\n  testability; then optional extensibility, formal symmetry, or structural\n  completeness. A lower-priority concern must not compromise a higher-priority\n  one. This order does not override authority, safety, scope, or architecture\n  gates.\n- Preserve existing architecture by default. Prefer direct reuse, then\n  composition or delegation, then an existing extension point. Do not invent a\n  boundary when no maintained precedent exists.\n- Use the smallest clear implementation and minimize conceptual surface rather\n  than line count. Prefer one readable local flow with the fewest independently\n  meaningful types, states, representations, execution paths, and cross-file\n  hops. Every added line, helper, abstraction, identifier, literal, guard, copy,\n  wrapper, and configuration entry must serve production behavior, a public\n  contract, regression protection, diagnostics, safety, readability, or removal\n  of real duplication. Do not add code for formal symmetry, coverage appearance,\n  structural completeness, hypothetical reuse, or test convenience. Avoid\n  unnecessary locals, thin wrappers, helpers, comments, guards, and copies;\n  inline single-use locals unless a name improves readability. Keep a name,\n  local variable, or extraction when it materially clarifies intent; do not\n  compress code mechanically.\n- A new abstraction must own production behavior, state, or a contract that\n  existing types cannot express and must represent a real, stable variation or\n  boundary. Define the narrowest contract, keep common behavior in its owner,\n  and isolate only true implementation or dialect differences. Forwarding,\n  renaming, multiple callers, readability alone, direct test value, symmetry,\n  type distinction, shorter call sites, test convenience, and anticipated reuse\n  are insufficient. Reuse alone never authorizes changing `final`, visibility,\n  inheritance, or shared-code ownership. Do not wrap a simple internal two-path\n  flow in marker interfaces, result hierarchies, or DTO-style helpers unless\n  they define a stable boundary, keep the owner readable, or remove meaningful\n  duplication. This rule does not bypass the architecture-change gate.\n- Do not introduce package-private top-level helper types by default. Keep a\n  small single-owner helper private and nested; add a top-level helper only when\n  the approved production behavior, state, or contract cannot reasonably be\n  owned by an existing type.\n- Do not add production types, widen visibility, remove `final`, or change\n  constructors or signatures for test convenience. Avoid accumulating multiple\n  nested collaborators inside one owner.\n- Keep only constructors with distinct production semantics or framework,\n  reflection, serialization, or SPI requirements. Update callers explicitly\n  instead of adding convenience or compatibility overloads. Before adding or\n  changing a constructor, inspect nearby production conventions for visibility,\n  Lombok, validation, and tests. Before handoff, scan changed call sites for\n  unused or compatibility-only constructors.\n- Before declaring code unused, inspect semantic usages and repository-wide\n  references, including method references, generated accessors, overrides,\n  reflection, registrations, tests, E2E, and external consumers.\n- Inspect every usage match; a single regex or production-only search is not\n  sufficient evidence. Make the change converge on one coherent model: correct\n  or replace the existing owner before adding a parallel path, then remove\n  superseded in-scope representations, paths, adapters, shims, tests,\n  configuration, and other obsolete code after verifying usages and contracts.\n  Keep coexistence only for a verified compatibility contract. If convergence\n  exceeds the acceptance checklist or file-type authorization, stop at the\n  existing gate. Do not leave placeholders, TODO implementations, speculative\n  compatibility shims, or test-only production hooks.\n- When adding a database, dialect, plugin, or module, reuse the applicable\n  framework and extension mechanisms. Keep derived dialects aligned with shared\n  behavior and isolate only real differences. If no maintained precedent\n  exists, record the search evidence before using the architecture gate.\n- Reuse or create an SPI only when its contract matches the required production\n  behavior. One caller, one implementation, code sharing, type distinction,\n  symmetry, anticipated reuse, or test convenience does not establish an SPI\n  contract.\n\n### Validation and Exceptions\n\n- Add runtime validation only at real external, public, persisted, parsed, SPI,\n  reflection, shared-state, or asynchronous boundaries, or for a concrete\n  diagnostic benefit. Do not recheck invariants guaranteed by callers or\n  upstream contracts.\n- Prefer `ShardingSpherePreconditions` with lazy exception suppliers when the\n  module can use it and the resulting control flow preserves the required\n  exception type, message, timing, and cause.\n- Keep a manual throw when the module cannot depend on `infra/exception`, the\n  code is inside `ShardingSpherePreconditions`, a caller-facing exception\n  contract requires it, or a precondition wrapper would obscure necessary\n  control flow. Do not replace manual throws mechanically, and record the\n  concrete reason for keeping one.\n- When an edit removes the last checked-exception source from a private or\n  internal method, remove the stale `throws` declaration and update callers.\n  Keep checked exceptions on public or overridden methods only when a\n  caller-facing, framework, external API, or compatibility contract requires\n  them. Never widen to generic `Exception` or `Throwable`.\n\n### Repository Style\n\n- Apply the `CODE_OF_CONDUCT.md` Lombok preference to touched boilerplate when\n  generated semantics are equivalent. Use narrow annotations; never use broad\n  annotations such as `@Data` unless every generated behavior is required.\n  Before replacing a public constructor or accessor, verify its generated\n  signature, access, parameter order, annotations, and reflection or\n  serialization behavior. Keep a manual member when Lombok would change or\n  obscure logic, documentation, validation, defaults, side effects,\n  compatibility, framework semantics, or a public contract.\n- Keep public API and SPI Javadocs required by the code of conduct. Beyond that,\n  document only caller or implementer obligations not expressed by code. Do not\n  restate names, signatures, visible collection properties, or inherited\n  contracts unless an override adds a new obligation.\n- Keep declarations near first use. Do not mark local, loop, resource, or\n  lambda variables `final`; use `final` only for method, constructor, and\n  `catch` parameters when applicable.\n- Declare collections by the least-specific required contract. Do not copy or\n  wrap collections without an owned mutability, snapshot, isolation, or public\n  contract reason. Record the concrete reason for every explicit copy or\n  wrapper. Use `Collection` for common iteration, size, or emptiness operations;\n  use `List` only for positional, ordered, duplicate-preserving, or required API\n  semantics; use `Set` only for uniqueness or set semantics. Do not declare a\n  concrete collection type unless its implementation-specific API is required.\n  In tests, create a mutable copy only when that instance is mutated or\n  mutability is the scenario.\n- Add a YAML anchor only when aliases in the same file remove meaningful\n  duplication.\n- Use repository-relative paths, configuration, or temporary directories in\n  code, tests, scripts, and Skills; never hard-code a local workspace path.\n- Add the ASF license header to new source files and keep implementation intent\n  and reviewer-relevant rationale transparent.\n- Account for compatibility, security, time and space complexity, I/O, memory,\n  resource lifecycle, concurrency, and boundary failures when the affected\n  path makes them relevant.\n\n## Test Rules\n\n- Test behavior owned by the production class: computation, decisions,\n  validation, transformation, state transitions, error handling, or external\n  contracts. Each test must fail for a realistic regression that matters. Do\n  not add a dedicated test for a pass-through, constant, accessor, or wiring\n  method unless that behavior is itself a documented public or externally\n  visible contract.\n- Never add tests whose subject is another test case, a test class or method,\n  test fixture, mock helper, test utility, or other test-only code. Test only\n  the production behavior that the test-only code supports. Test-support code\n  distributed as an independent artifact with an external contract is\n  production code for this rule.\n- Do not add tests that only prove constants, accessors, delegation, wiring,\n  Java, Lombok, Mockito, parsers, collection libraries, framework behavior, or\n  private implementation shape. Contract literals are exceptions only when no\n  broader behavior can protect them. Never add a test solely to increase a\n  coverage number. Do not duplicate an existing scenario unless the new test\n  covers a new branch, input class, edge case, contract, calculation path, or\n  failure mode.\n- Do not test collaborator rules through the current class. Mock the nearest\n  stable boundary and test the collaborator rule in its owner. Cross-layer\n  behavior belongs in an explicitly scoped integration, contract, or E2E test.\n- Give each behavior-owning public production method focused coverage. Each\n  test method covers one scenario and invokes the target public method at most\n  once; repeat only when the same scenario requires additional assertions. Do\n  not create interface-only tests; exercise concrete implementations.\n- Every new public production type requires direct focused tests, except\n  exception types covered by `Exception Tests`. Broad workflow tests do not\n  replace them unless they explicitly exercise that type's public behavior. If\n  a pure pass-through public type has no meaningful owned or external contract\n  to test, do not add the type merely for structural completeness.\n- Default to direct Mockito mocks. Use a private helper only for repeated local\n  setup and a standalone fixture only for a stable external or packaged test\n  boundary. Give fixtures the narrowest practical visibility, keep them in the\n  nearest owning test package or module, and do not create cross-module test\n  APIs for convenience. Delete or inline thin mock wrappers.\n- Obtain SPI implementations through the project loader by default. Use\n  `Plugins.getMemberAccessor()` for permitted field access; direct reflection\n  APIs and reflective invocation of private methods are forbidden. If the class\n  under test implements `TypedSPI` or `DatabaseTypedSPI`, instantiate it through\n  `TypedSPILoader` or `DatabaseTypedSPILoader`, not with `new`.\n- Prefer `AutoMockExtension` and its static or construction mocking support.\n  Use direct `mockStatic` or `mockConstruction` only when the extension cannot\n  apply and the reason is recorded; scope it with try-with-resources. When a\n  class is listed in `@StaticMockSettings`, do not call `mockStatic` or\n  `mockConstruction` for it; stub it through `when(...)`.\n- Do not mix Mockito matchers with raw arguments in one invocation. Mock\n  databases, caches, registries, network calls, time, and other heavy external\n  dependencies instead of constructing deep unrelated object graphs.\n- Every unit-test class must be named `<ProductionClassName>Test`, using the\n  exact simple name of the production class it directly tests. This class-name\n  rule is mandatory and is independent of scenario-focused test-method naming.\n- Parameterized tests must set `name = \"{0}\"`. Keep test names concise and\n  scenario-focused, following `CODE_OF_CONDUCT.md`; avoid `ReturnsXXX` and\n  wording that restates the expected result instead of naming the scenario.\n- Use JUnit 5 and Mockito. Keep setup, action, and assertions distinct; reset\n  static state between scenarios and reuse existing swappers or helpers for\n  complex configuration.\n- When a coverage target is stated, list every branch or path before coding and\n  map each one to exactly one planned test. Add cases until every declared\n  branch is covered or explicitly waived, update the map when code changes, and\n  verify with JaCoCo when coverage is uncertain. Document unreachable code\n  instead of adding redundant tests.\n\n### Exception Tests\n\n- Do not add dedicated tests for exception classes that only declare\n  constructors or format and forward their arguments to a tested superclass.\n  Add direct tests only for owned validation, branching, calculation,\n  conversion, or a known regression.\n\n## Specialized Workflows\n\n### Repository Workflows\n\nUse the matching repository Skill when its trigger applies:\n\n- Issue diagnosis and copy-ready maintainer replies: `$analyze-issue`.\n- Unit-test generation or systematic coverage work: `$gen-ut`.\n- PR correctness, side effects, mergeability, GitHub review replies, or the\n  pre-handoff review of an authorized implementation targeting an existing PR:\n  `$review-pr`. For pre-handoff review, use its Local Candidate Preflight Mode.\n\nIf a matching repository Skill is unavailable, apply an equivalent manual\nchecklist, record the fallback in the plan or final response, and continue\nwithout installing it. Do not create a new Skill merely to hold task-specific\ninstructions.\n\n### Optional Cross-Cutting Skills\n\nThe Skills in this subsection are optional workflow accelerators, not\nprerequisites. Availability alone is not a trigger. When an optional Skill is\navailable and its trigger below applies, prefer it and use only the smallest\nmatching Skill set. If it is unavailable, skip the Skill itself and continue\nwith the applicable repository gates and ordinary workflow. Do not install,\ncreate, reconstruct, or treat the absence of an optional Skill as a blocker.\nMention the absence only when the user explicitly requested the Skill or it\nleaves a material residual risk.\n\nSkipping a Skill never waives compatibility, correctness, security, scope,\nverification, or completion requirements. Using a Skill never expands the\nfrozen task scope, allowed modules or files, acceptance checklist, write or\nremote authority, Git authority, or tool permissions. This guide prevails when\na Skill conflicts with it.\n\n- Implementation or review whose correctness depends on the current version of\n  an external framework or library: use `$source-driven-development` when\n  available. Identify the applicable version from repository dependency\n  metadata, verify the relevant decision against authoritative primary\n  documentation, record the source, and mark anything that cannot be verified\n  as unverified. This verification remains required without the Skill. Do not\n  invoke it for version-independent local logic.\n- Designing, adding, or changing a public API, SPI, extension, loading or\n  registration contract, module boundary, externally visible interface, or\n  cross-module type contract: use `$api-and-interface-design` when available\n  before implementation. Apply the Architecture change and Contract and Impact\n  gates whether or not the Skill is available; using it does not authorize the\n  change or expand the confirmed scope.\n- An unexpected test, build, runtime, or behavior failure: use\n  `$debugging-and-error-recovery` when available. Stop unrelated implementation,\n  preserve evidence, reproduce, localize, reduce, identify the root cause, and\n  verify the result. Add focused regression protection only when the root cause\n  is an in-scope production defect and the test protects meaningful owned\n  behavior; do not add a test for an environment, infrastructure, or unrelated\n  failure. A failure never authorizes an out-of-boundary fix or a Git write.\n- An explicit performance requirement, reproducible reported slowness or\n  suspected regression, profiling evidence, or a requested change that can\n  materially alter the cost of a confirmed performance-sensitive path: use\n  `$performance-optimization` when available to measure first. A path being\n  high-volume by itself is not a trigger. Freeze the workload, metric,\n  environment, and baseline; identify the owning bottleneck before editing;\n  test one hypothesis at a time; and repeat the same measurement with\n  correctness checks. Keep a change only when the improvement exceeds\n  run-to-run variance and correctness remains intact. Remove neutral, worse,\n  or incorrect current-task experiments. Record attempts in the task unless an\n  exact file or remote target is separately authorized. Do not optimize by\n  intuition or follow adjacent hotspots outside the frozen boundary.\n- After scoped behavior and checks pass, when the effective task delta contains\n  concrete unnecessary complexity or a review identifies it: use\n  `$code-simplification` when available on that delta only. Preserve behavior\n  exactly and never perform a drive-by refactor or gain Git authority from the\n  Skill. Do not invoke it merely because the Completion Loop is running or when\n  the candidate is already clear.\n- An explicit user request to threat model a repository or path, enumerate\n  threats or abuse paths, or perform AppSec threat modeling: use\n  `$security-threat-model` when available. Do not invoke it for an ordinary\n  architecture summary, code review, security check, or non-security design.\n  The request remains read-only unless the user also authorizes the exact\n  output file; the Skill's default artifact creation grants no write authority.\n- A non-trivial decision involving module boundaries, public contracts,\n  unfamiliar code, or high-risk behavior, or a branching invariant that is not\n  directly established by types, existing tests, or an explicit contract and\n  whose failure would materially affect correctness, compatibility, security,\n  or another high-risk behavior: use `$doubt-driven-development` when available\n  only within the active task. An ordinary branch is not a trigger. The\n  prohibition on additional Codex tasks and external review overrides its\n  fresh-context and cross-model steps. Perform bounded adversarial self-review\n  instead and do not report the full Skill as completed.\n\nDo not include sensitive repository data in external searches.\n\n## Contract and Impact Gates\n\n- For a public or externally visible identifier, search all affected reference\n  surfaces: APIs, SQL, configuration and YAML keys, SPIs, errors, CLI commands,\n  resources, documentation, examples, distributions, tests, E2E, and\n  baselines. Exclude `.git` and `target`. If a compatibility alias remains,\n  state whether it is discoverable; if it must stay hidden, protect that\n  contract with a focused test or check.\n- Name the affected database engines and dialects and preserve backward\n  compatibility for their supported versions unless an exact compatibility\n  break is authorized.\n- For errors, logs, HTTP or JSON payloads, CLI output, and exception conversion,\n  test the complete external output when it could expose credentials, tokens,\n  connection strings, SQL, paths, or user data.\n- Regenerate or verify affected snapshots, golden files, fingerprints, SQL\n  cases, descriptors, schemas, and agent-visible metadata with the existing\n  project tool.\n- Determine affected GitHub Actions from changed-file path filters and job\n  commands. Run the local equivalent when practical; otherwise record the\n  narrower check and residual risk. Do not update remote workflow state.\n- When runtime paths change, record relevant engine or dialect compatibility\n  and a performance baseline or guardrail. When governance, registry,\n  observability, or agent integrations are touched, state their impact.\n\n## Runtime Triage\n\n- For Proxy startup, prefer the existing IDE/MCP `Bootstrap` configuration or a\n  scoped `proxy` package with explicit upstream modules. Record the\n  configuration path, mode, ports, command, and exit code.\n- For JDBC smoke tests, use a current-source IDE/MCP run or a focused `jdbc`\n  module test with explicit upstream modules and datasource setup.\n- Keep standalone `server.yaml` and affected cluster `mode/` configuration\n  behavior aligned; call out default changes.\n- For startup, routing, or runtime failures, inspect `proxy/logs/` and relevant\n  `target/surefire-reports`; correlate decisive lines with configuration,\n  metadata freshness, parser dialect, and the owning data-flow step. For routing\n  failures, also inspect feature-rule configuration and report the SQL, relevant\n  configuration, owning module, and focused test. Do not edit generated output.\n- For a sandbox or network denial, report the command, failure, and safe\n  alternative or required authorization.\n- When an E2E, integration, client smoke, or Docker smoke fails, hangs, or times\n  out, stop rerunning. Classify it as environment, classpath, stale snapshot,\n  dependency, test design, protocol implementation, data setup, assertion\n  logic, or external-service behavior, then record evidence and minimum fix\n  scope before changing code or configuration. Complete deterministic\n  prerequisites such as classpath consistency, stale-bytecode checks, dependency\n  alignment, or required evidence capture before running one matching sentinel;\n  if it fails unexpectedly, return to analysis.\n\n## Verification and Commands\n\nRun the narrowest meaningful checks first. Derive explicit Maven modules from\nchanged owners, affected tests, and consuming runtime modules.\n\n- Focused test:\n  `./mvnw -pl <module> -DskipITs -Dspotless.skip=true\n  -Dtest=<FullyQualifiedTestClassName>\n  -Dsurefire.failIfNoSpecifiedTests=false test`\n- Scoped tests: `./mvnw test -pl <explicit-module-set>`\n- Scoped package:\n  `./mvnw -pl <explicit-module-set> -DskipTests package`\n- Coverage:\n  `./mvnw -pl <explicit-module-set> -Djacoco.skip=false test jacoco:report`\n- Full build: `./mvnw clean install -B -T1C -Pcheck`\n\nPrefer current-source IDE/MCP runs or explicit `-pl` module sets. Use `-am`\nonly when dependency freshness, missing reactor artifacts, or CI equivalence\ncannot otherwise be established, normally once per unchanged task state. For\nmulti-module checks, verify lower-level changed owners before their higher-level\nconsumers.\n\nKeep background unit tests under 60 seconds. Capture high-volume output\naccording to `.codex/context/token-efficiency.md`; report commands, exit codes,\nand decisive log excerpts instead of dumping raw logs.\n\nFor every user-forbidden tool, API, assertion, or pattern, run a scoped final\nsearch and report the command and result. Do not rely only on plan compliance.\n\nAfter the last file-changing action:\n\n1. Run `./mvnw spotless:apply -Pcheck -T1C` for code or documentation changes.\n2. Run `./mvnw checkstyle:check -Pcheck -T1C` when production, test, or\n   project-rule files changed.\n3. Do not manually reformat afterward. Any later edit invalidates formatting\n   and requires the applicable checks again.\n\n## Completion Loop\n\nFor an authorized change, build, implement, or fix request, excluding a\nstandalone restoration or rollback:\n\n1. Compare the task-introduced delta with the recorded pre-edit baseline, the\n   read-only `git diff`, surrounding context, and the acceptance checklist.\n2. Confirm every task-introduced file and hunk is necessary, expected changed\n   files contain only their frozen change intent, prohibited paths have zero\n   task delta, direct reuse was considered, architecture changes were\n   authorized, and every test protects owned behavior. Inspect Java changes for\n   newly added local-variable `final`, scan changed code and Skills for local\n   absolute paths, and remove only current-task violations.\n3. Treat scripts, searches, formatting, compilation, and passing tests as\n   evidence, not proof of semantic compliance. Judge the final behavior,\n   contracts, architecture, and user request directly; fix every safe in-scope\n   violation instead of reporting it as an accepted risk.\n4. Apply `$code-simplification` under Optional Cross-Cutting Skills only when\n   its concrete complexity trigger is present and the Skill is available. Do\n   not invoke it merely because this loop is running; a clear task delta or an\n   unavailable Skill does not block handoff.\n5. Review the effective local candidate against the same code-correctness gates\n   used by `$review-pr`: root cause and fix mapping, affected behavior, side\n   effects and regressions, contracts and architecture, test validity, and\n   adversarial cases. Apply `$code-review-and-quality` when available, or its\n   equivalent review, for the general quality axes; it does not replace these\n   shared correctness gates.\n6. When the implementation targets an existing PR, also apply `$review-pr` in\n   Local Candidate Preflight Mode before handoff. PR-specific public-head and\n   remote-evidence checks remain part of formal PR review.\n7. Fix every safe in-scope required finding, rerun invalidated checks, and\n   repeat the applicable reviews. If a finding requires scope expansion, an\n   unresolved architecture choice, or a high-risk action, stop at its existing\n   authorization gate instead of fixing it automatically.\n8. Hand off and propose a commit message only after one complete applicable\n   review pass finds zero new required issues. Before that review passes, do not\n   hand off or propose a commit message. Do not defer a locally discoverable\n   required finding to a later formal PR review.\n9. Stop when no required in-scope finding remains. Do not iterate for optional\n   polish, broad cleanup, or risky refactoring.\n\nIf a report or verdict is disproved, fix the highest-leverage rule, schema,\nvalidator, prompt, or regression case before correcting the artifact, unless\nthe user explicitly requests a one-off correction.\n\nThe final response must lead with the outcome and include changed files and\nrationale, commands with exit codes, verification status, remaining risks, and\nthe next action only when one is still required. When Git commit authorization\nis absent, provide a proposed commit message without staging or committing.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# ShardingSphere Codex Development Guide\n\nThis repository guide is written for Codex. Keep only stable, repository-wide\nrules here and rely on Codex for ordinary coding competence. Follow every\nexplicit rule literally; do not replace a repository rule with general judgment\nunless that rule authorizes it. Paths are relative to the repository root.\n\n## Instruction Sources\n\n1. `CODE_OF_CONDUCT.md` is the authority for contribution, Java, and unit-test\n   style. Inspect the applicable section before changing code or tests and\n   record it when it controls a decision.\n2. Before Maven, E2E, Proxy startup, database clients, IDE/MCP run\n   configurations, commands likely to output more than 100 lines, or large\n   structured analysis, read or reuse\n   `.codex/context/token-efficiency.md` and follow its Mandatory Execution\n   Contract.\n3. Use repository Skills for specialized workflows instead of reproducing their\n   detailed instructions here.\n4. Keep task-specific notes in the task, issue, or PR. Do not add session notes\n   to this file.\n\n### Changing This Guide\n\nFor changes to this guide, use `.codex/harness/agents/`. `cases.toml` is the\nsource of the harness catalog: each case records its group, purpose, enforcement\nphase, and whether the ordinary completion loop rechecks it. Run\n`python3 .codex/harness/agents/run.py --list-cases` to render the table.\n\n1. Treat every explicit requirement, prohibition, exception, authorization\n   boundary, and verification step as an independent policy capability.\n2. Before editing, build an old-to-new capability ledger and classify every\n   capability as exactly preserved, changed with the user's explicit\n   authorization in the current task, or restored before handoff.\n3. Reconcile every deleted or weakened rule explicitly. A replacement is\n   equivalent only when it preserves the same trigger, required or forbidden\n   action, scope, exceptions, and verification obligation. A positive general\n   rule does not replace a specific negative prohibition. Ordinary Codex competence,\n   implication, nearby prose, a Skill, or a canary is not evidence that any\n   explicit rule is preserved. Partial or implicit coverage is a regression.\n4. Never remove, weaken, merge away, or broaden an exception to a capability\n   unless the user explicitly authorizes that exact policy change. When\n   equivalence is uncertain, keep the existing rule.\n5. Before editing, capture a V0 policy baseline; then change one coherent\n   instruction group.\n6. Count a canary as passing only when its decision matches, every required\n   action and reason is present, and every action outside its complete\n   allowed-action set is absent. A partial forbidden-action list is\n   insufficient.\n7. Run all policy canaries and reject any critical regression. When the user\n   explicitly authorizes a case-contract change, name only that case with\n   `--authorized-contract-change`; every other changed or removed critical\n   contract remains a regression.\n8. Compare pass rate, duration, input tokens, and uncached input tokens with V0.\n   Accept only candidates that preserve correctness; efficiency improvements\n   count only after quality gates pass.\n9. If the same failure appears twice, add a focused case instead of generic\n   prose. Stop after five candidates or when no measurable improvement remains.\n10. After the canaries pass, complete the applicable simplification, internal\n    candidate review, finding-fix, and re-review steps in the Completion Loop\n    before handoff.\n\n## Response Style\n\n- Use plain language and the shortest response that fully answers the request.\n- Do not add details unless the user requests them or they are necessary.\n- When details are necessary, put a self-contained concise answer above a line\n  containing only `---` and the details below it. Omit the separator when no\n  details follow.\n\n## Authority and Safety\n\n- Answer, explain, review, diagnose, audit, and plan requests are read-only.\n  Inspect and report; do not edit the reviewed target.\n- Change, build, implement, and fix requests authorize the smallest in-scope\n  local production and test code edits plus non-destructive verification.\n  Documentation, configuration, scripts, generated artifacts, file deletion,\n  Docker cleanup, and system changes require explicit authorization in the\n  current task. A request that names the exact non-code target is authorization\n  for that target; do not ask again unless another gate below applies.\n- Preserve unrelated working-tree changes. Inspect `git status --short` before\n  editing and never discard work whose ownership is uncertain.\n\n### Git Is Read-Only by Default\n\nThe user owns every Git state change. Codex may use read-only Git commands such\nas `status`, `diff`, `show`, `log`, `blame`, `grep`, and `ls-files`.\n\nCodex may run a Git state-changing command only when the current request\nexplicitly authorizes that exact operation and its exact target. The\nauthorization applies only to that operation in the current task; it does not\nauthorize prerequisite, follow-up, adjacent, or future Git writes. Resolve the\ntarget with read-only inspection first and report the completed operation.\n\nWithout that exact authorization, never run a Git command that changes the\nindex, working tree, refs, remotes, branches, tags, stashes, worktrees, or\nsubmodules. This prohibition includes `add`, `commit`, `push`, `fetch`, `pull`,\n`merge`, `rebase`, `reset`, `restore`, `checkout`, `switch`, `clean`,\n`cherry-pick`, `revert`, branch or tag mutation, stash mutation, worktree\nmutation, and `submodule update`. Do not stage changes or use Git as a rollback\nmechanism.\n\nWhen a requested Git write lacks exact authorization, complete any separately\nauthorized local work, then provide a commit message or exact manual next step.\nProceed with the allowed parts of the request; omit the unauthorized Git\nmutation rather than refusing the entire task. A request for only a commit\nmessage is not authorization to commit.\n\n### Remote Writes and Sensitive Data\n\n- A local coding request never authorizes updating an issue, PR, review,\n  repository, deployment, production API, connector, cloud task, message, or\n  other remote state. Perform a remote write only when the current request\n  explicitly names the action and exact target.\n- For GitHub access, use the first configured token in this order: `GH_TOKEN`,\n  then `GITHUB_TOKEN`; check it without printing, logging, persisting, or\n  otherwise exposing its value. When a token is available, call the GitHub API\n  directly and do not search for, inspect, or invoke `gh`; use `gh` only when\n  neither token is configured.\n- Do not transmit credentials, tokens, private keys, private logs, proprietary\n  source, personal data, connection strings, or other sensitive repository data\n  outside the active user-authorized Codex task, including to websites, search\n  queries, connectors, plugins, MCP servers, review services, or external tools.\n  Redact sensitive values from commands, summaries, and retained artifacts.\n- Do not invoke an additional Codex task or external review service. The policy\n  harness in `.codex/harness/agents/` is the only exception: it may run a\n  separate isolated Codex task only with synthetic, non-sensitive policy cases\n  in a read-only, ephemeral environment. Do not include source, logs, task data,\n  or sensitive values in its prompt. Otherwise perform bounded self-review in\n  the active user-authorized Codex task.\n\n### Destructive and High-Risk Local Actions\n\nBefore deleting files or data, bulk-editing non-code artifacts, removing Docker\ncontainers, changing global configuration, permissions, or packages, or\nperforming another destructive local action:\n\n1. Resolve and inspect the exact targets with read-only commands.\n2. State the impact and whether recovery is reliable.\n3. Obtain explicit confirmation unless the user already authorized those exact\n   resolved targets and a reliable recovery path exists.\n\nA reliable recovery path is a verified backup or source plus concrete restore\nsteps, or a deterministic rebuild or re-download whose origin has been\nconfirmed. Git is a recovery path only when the current task separately\nauthorizes the exact restore operation. If the only copy would be lost, the\nsource is unknown, or recovery has not been verified, state that there is no\nreliable rollback and confirm again before acting. Never imply that an\nirreversible action is recoverable.\n\nFor Docker cleanup, distinguish reproducible images and containers from\npersistent volumes or local data. When Docker cleanup is in scope, Codex may\nremove images that inspection proves unused and reproducible without another\nconfirmation. This exception does not authorize removing containers, volumes,\nor local data, or an image whose source or reproducibility is uncertain.\n\nUse this prompt when confirmation is required:\n\n```text\nDangerous operation detected!\nOperation type: [specific action]\nScope of impact: [exact targets]\nRecovery: [verified steps, or \"no reliable rollback\"]\nRisk assessment: [potential consequence]\nPlease confirm whether to continue.\n```\n\n## Evidence, Scope, and Planning\n\nMaintain independent technical judgment. Do not agree with or adopt a\nuser-supplied premise, diagnosis, design, or conclusion merely because the user\nproposed or prefers it; treat it as a claim to evaluate. When such a claim could\nmaterially affect correctness, scope, compatibility, safety, or cost,\ndistinguish verified evidence from inference, assumption, and preference;\ninspect contradictions, missing constraints, unsupported causal links, and\nplausible alternatives.\n\nIf evidence contradicts the user's premise or is insufficient for the proposed\naction, say so before acting and state the decisive evidence, likely impact,\nand the minimum viable alternative, additional check, or decision needed. Do\nnot add generic caveats, expand scope or authority, or delay straightforward\nauthorized work merely to demonstrate skepticism.\n\nBefore editing:\n\n1. Restate the verifiable goal, non-goals, user-forbidden tools or APIs, and\n   coverage or output constraints.\n2. Inspect the affected code, tests, contracts, configuration, registrations,\n   module boundaries, closest maintained precedent, and applicable\n   instructions.\n3. Identify behavior owners, reuse opportunities, compatibility impact,\n   expected changed files, prohibited paths, required tests, and scoped\n   verification.\n4. Convert these items into a compact acceptance checklist and a 3–10 step plan\n   for non-trivial work.\n\n### Strict Scope and Task-Delta Gate\n\nApply this gate to every file-changing task and action, including changes made\nby formatters, generators, scripts, Skills, and review fixes, except a\nstandalone restoration or rollback governed by its existing gates.\n\nFor this gate, an active task is one independent, verifiable user objective,\nnot the permanent lifetime of a UI conversation. It includes every later turn\nand correction for that objective, including after a handoff. Only after the\nprevious objective is complete and the user explicitly requests an independent\nobjective may Codex capture a new baseline and freeze a new boundary. When a\nuser request could reasonably be either a follow-up or an independent\nobjective, remain read-only and confirm the task boundary before writing. An\nagent finding, review result, failure, or mention of another module is not an\nindependent objective and does not create that ambiguity.\n\n1. Derive the acceptance checklist only from user-requested outcomes, direct\n   prerequisites proven by inspected evidence, and focused regression\n   protection required by the Test Rules. Do not turn an agent-proposed\n   cleanup, refactor, generalization, consistency improvement, or adjacent fix\n   into an acceptance criterion.\n2. Treat a prerequisite as direct only when omitting it would prevent the\n   requested behavior, compilation, or scoped verification and no smaller\n   in-boundary alternative exists. Relevance, repository evidence, a test\n   failure, or a review finding may prove that expansion is required, but does\n   not authorize that expansion.\n3. Before the first write, record the pre-task working-tree baseline, including\n   the existing status and relevant diffs, then freeze the allowed files and\n   the allowed change intent for each file. An allowed file does not authorize\n   unrelated hunks in that file.\n4. For a file-changing request that is authorized to proceed, use initial\n   read-only analysis and, before the first write, derive the smallest owning\n   module or repository-path set from the user request and inspected evidence,\n   whether or not the user named it, then freeze it as the hard write allowlist\n   for the active Codex task. Later user turns, follow-up changes, reviews,\n   failures, and further inspection in that task do not reset or expand it.\n   Inspection and verification outside it remain read-only. Never edit any\n   other module, including a sibling, shared, dependency, parent, root, or\n   consuming module. Its code, tests, resources, configuration, build files,\n   and generated sources remain outside the write boundary unless the user\n   explicitly authorizes the exact additional module or path and its change\n   intent before the edit. Treat that authorization as an append-only\n   expansion: map it to an acceptance criterion, freeze only the smallest newly\n   authorized path and intent, and retain the original task baseline. Never\n   rebaseline an active task, infer whole-module authorization from an exact\n   file authorization, or treat an added path as blanket authorization. A\n   direct prerequisite does not self-authorize expansion. The allowlist is a\n   maximum boundary, not blanket authorization or a reason to repeat completed\n   work; every later edit still needs an unsatisfied acceptance criterion. Do\n   not repeat completed edits, checks, or reviews unless an authorized\n   in-boundary edit invalidates them.\n5. When the request makes the boundary clear, infer and freeze it without\n   asking the user to repeat it. The checklist is the maximum change boundary.\n   Every changed file and task-introduced hunk must map directly to one\n   acceptance criterion and be necessary to satisfy it.\n6. After each file-changing action, inspect the paths and hunks that action may\n   have changed before continuing. Tool-produced changes are task changes and\n   receive no scope exemption.\n7. If evidence proves that work outside the frozen boundary is required, stop\n   before that edit. Report the blocking evidence, smallest additional scope,\n   exact files or contracts, and consequence of declining it, then request\n   confirmation. Until expansion is authorized, limit outside-boundary work to\n   the read-only evidence needed for that report; do not start its design or\n   implementation workflow. Report other out-of-scope findings without fixing\n   them.\n8. After the last file-changing action, audit the task-introduced delta against\n   the pre-task baseline, not merely the aggregate working-tree diff. Preserve\n   every pre-existing user change and every later delta that cannot be proven\n   to result from a current-task write. Absence from the baseline does not prove\n   task ownership. Treat an unattributed delta as user-owned, do not overwrite,\n   format, remove, or roll it back, and stop the affected write path to report\n   the conflict. Remove only proven current-task changes that lack a direct\n   acceptance-criterion mapping; if precise removal is unsafe or a tool keeps\n   recreating them, stop and report the blocker.\n9. Hand off only when the audited task delta is the smallest correct change.\n   Summarize each remaining file as `file -> changed behavior -> acceptance\n   criterion -> necessity` so the user can verify the scope directly.\n\n### Unused and Removal Conclusions\n\nApply this gate to every analysis or change that classifies code, dependencies,\nconfiguration, resources, test support, or another repository artifact as\nunused or removable.\n\n1. Distinguish absence of direct references from complete unused evidence. A\n   single text or regex search, or a production-only search, proves at most that\n   no direct reference was found and cannot justify a removal recommendation.\n2. Inspect semantic and indirect consumers appropriate to the artifact,\n   including reflection, generated code, registrations, SPI and `ServiceLoader`,\n   JDBC driver discovery, Maven scopes, profiles, plugins and transitive\n   dependencies, build/test/runtime classpaths, test JARs, packaging and\n   distributions, tests, E2E, and external consumers.\n3. Inspect Git history and linked issue, pull-request, CI, and failure evidence\n   for prior additions, removals, and restorations. A prior removal failure\n   makes the artifact indirectly required unless same-boundary evidence proves\n   that the failure was unrelated or that the dependency is obsolete.\n4. Classify each examined artifact as directly used, indirectly required,\n   purpose unresolved, or a verified removal candidate. Use purpose unresolved\n   when evidence is incomplete. Use verified removal candidate only after a\n   controlled removal experiment, or equivalent existing evidence, covers the\n   affected compilation, tests, packaging, and runtime paths.\n\nChanges to public contracts, SPIs, extension or loading contracts, class or\nmethod `final`, visibility, inheritance, constructors or signatures, module\ndependencies, or shared-code ownership are architecture changes. Before such a\nchange, report:\n\n- current behavior and owner;\n- direct-reuse and delegation analysis;\n- compatibility impact;\n- minimum affected files and tests.\n\nAn exact architecture change explicitly requested by the user is authorized\nafter that report. If materially different ownership, architecture, or\ncompatibility choices remain unresolved, obtain confirmation. Adding,\nchanging, or removing an SPI always follows this gate.\n\nIf the user rejects a design, stop patching it. Remove only current-task changes\nthat are provably part of the rejected design, preserve unrelated work, and\nredesign from the last confirmed boundary. Restore through precise file edits\nunless the current task separately authorizes the exact Git restore operation.\n\n## Implementation Rules\n\n### Codex Design Style\n\nApply this section to every production, test, script, or other implementation\ncreated or changed within the authorized boundary. Treat an in-scope violation\nin the effective candidate as a required finding and fix it before handoff; do\nnot expand scope or rewrite unrelated existing code.\n\n- Within already-authorized designs, resolve trade-offs in this order: semantic\n  and contract correctness; correct behavior and module ownership; verified\n  compatibility and real boundaries; minimal conceptual surface and local\n  readability; consistency with maintained nearby code and direct reuse;\n  testability; then optional extensibility, formal symmetry, or structural\n  completeness. A lower-priority concern must not compromise a higher-priority\n  one. This order does not override authority, safety, scope, or architecture\n  gates.\n- Preserve existing architecture by default. Prefer direct reuse, then\n  composition or delegation, then an existing extension point. Do not invent a\n  boundary when no maintained precedent exists.\n- Use the smallest clear implementation and minimize conceptual surface rather\n  than line count. Prefer one readable local flow with the fewest independently\n  meaningful types, states, representations, execution paths, and cross-file\n  hops. Every added line, helper, abstraction, identifier, literal, guard, copy,\n  wrapper, and configuration entry must serve production behavior, a public\n  contract, regression protection, diagnostics, safety, readability, or removal\n  of real duplication. Do not add code for formal symmetry, coverage appearance,\n  structural completeness, hypothetical reuse, or test convenience. Avoid\n  unnecessary locals, thin wrappers, helpers, comments, guards, and copies;\n  inline single-use locals unless a name improves readability. Keep a name,\n  local variable, or extraction when it materially clarifies intent; do not\n  compress code mechanically.\n- A new abstraction must own production behavior, state, or a contract that\n  existing types cannot express and must represent a real, stable variation or\n  boundary. Define the narrowest contract, keep common behavior in its owner,\n  and isolate only true implementation or dialect differences. Forwarding,\n  renaming, multiple callers, readability alone, direct test value, symmetry,\n  type distinction, shorter call sites, test convenience, and anticipated reuse\n  are insufficient. Reuse alone never authorizes changing `final`, visibility,\n  inheritance, or shared-code ownership. Do not wrap a simple internal two-path\n  flow in marker interfaces, result hierarchies, or DTO-style helpers unless\n  they define a stable boundary, keep the owner readable, or remove meaningful\n  duplication. This rule does not bypass the architecture-change gate.\n- Do not introduce package-private top-level helper types by default. Keep a\n  small single-owner helper private and nested; add a top-level helper only when\n  the approved production behavior, state, or contract cannot reasonably be\n  owned by an existing type.\n- Do not add production types, widen visibility, remove `final`, or change\n  constructors or signatures for test convenience. Avoid accumulating multiple\n  nested collaborators inside one owner.\n- Keep only constructors with distinct production semantics or framework,\n  reflection, serialization, or SPI requirements. Update callers explicitly\n  instead of adding convenience or compatibility overloads. Before adding or\n  changing a constructor, inspect nearby production conventions for visibility,\n  Lombok, validation, and tests. Before handoff, scan changed call sites for\n  unused or compatibility-only constructors.\n- Before declaring code unused, inspect semantic usages and repository-wide\n  references, including method references, generated accessors, overrides,\n  reflection, registrations, tests, E2E, and external consumers.\n- Inspect every usage match; a single regex or production-only search is not\n  sufficient evidence. Make the change converge on one coherent model: correct\n  or replace the existing owner before adding a parallel path, then remove\n  superseded in-scope representations, paths, adapters, shims, tests,\n  configuration, and other obsolete code after verifying usages and contracts.\n  Keep coexistence only for a verified compatibility contract. If convergence\n  exceeds the acceptance checklist or file-type authorization, stop at the\n  existing gate. Do not leave placeholders, TODO implementations, speculative\n  compatibility shims, or test-only production hooks.\n- When adding a database, dialect, plugin, or module, reuse the applicable\n  framework and extension mechanisms. Keep derived dialects aligned with shared\n  behavior and isolate only real differences. If no maintained precedent\n  exists, record the search evidence before using the architecture gate.\n- Reuse or create an SPI only when its contract matches the required production\n  behavior. One caller, one implementation, code sharing, type distinction,\n  symmetry, anticipated reuse, or test convenience does not establish an SPI\n  contract.\n\n### Validation and Exceptions\n\n- Add runtime validation only at real external, public, persisted, parsed, SPI,\n  reflection, shared-state, or asynchronous boundaries, or for a concrete\n  diagnostic benefit. Do not recheck invariants guaranteed by callers or\n  upstream contracts.\n- Prefer `ShardingSpherePreconditions` with lazy exception suppliers when the\n  module can use it and the resulting control flow preserves the required\n  exception type, message, timing, and cause.\n- Keep a manual throw when the module cannot depend on `infra/exception`, the\n  code is inside `ShardingSpherePreconditions`, a caller-facing exception\n  contract requires it, or a precondition wrapper would obscure necessary\n  control flow. Do not replace manual throws mechanically, and record the\n  concrete reason for keeping one.\n- When an edit removes the last checked-exception source from a private or\n  internal method, remove the stale `throws` declaration and update callers.\n  Keep checked exceptions on public or overridden methods only when a\n  caller-facing, framework, external API, or compatibility contract requires\n  them. Never widen to generic `Exception` or `Throwable`.\n\n### Repository Style\n\n- Apply the `CODE_OF_CONDUCT.md` Lombok preference to touched boilerplate when\n  generated semantics are equivalent. Use narrow annotations; never use broad\n  annotations such as `@Data` unless every generated behavior is required.\n  Before replacing a public constructor or accessor, verify its generated\n  signature, access, parameter order, annotations, and reflection or\n  serialization behavior. Keep a manual member when Lombok would change or\n  obscure logic, documentation, validation, defaults, side effects,\n  compatibility, framework semantics, or a public contract.\n- Keep public API and SPI Javadocs required by the code of conduct. Beyond that,\n  document only caller or implementer obligations not expressed by code. Do not\n  restate names, signatures, visible collection properties, or inherited\n  contracts unless an override adds a new obligation.\n- Keep declarations near first use. Do not mark local, loop, resource, or\n  lambda variables `final`; use `final` only for method, constructor, and\n  `catch` parameters when applicable.\n- Declare collections by the least-specific required contract. Do not copy or\n  wrap collections without an owned mutability, snapshot, isolation, or public\n  contract reason. Record the concrete reason for every explicit copy or\n  wrapper. Use `Collection` for common iteration, size, or emptiness operations;\n  use `List` only for positional, ordered, duplicate-preserving, or required API\n  semantics; use `Set` only for uniqueness or set semantics. Do not declare a\n  concrete collection type unless its implementation-specific API is required.\n  In tests, create a mutable copy only when that instance is mutated or\n  mutability is the scenario.\n- Add a YAML anchor only when aliases in the same file remove meaningful\n  duplication.\n- Use repository-relative paths, configuration, or temporary directories in\n  code, tests, scripts, and Skills; never hard-code a local workspace path.\n- Add the ASF license header to new source files and keep implementation intent\n  and reviewer-relevant rationale transparent.\n- Account for compatibility, security, time and space complexity, I/O, memory,\n  resource lifecycle, concurrency, and boundary failures when the affected\n  path makes them relevant.\n\n## Test Rules\n\n- Test behavior owned by the production class: computation, decisions,\n  validation, transformation, state transitions, error handling, or external\n  contracts. Each test must fail for a realistic regression that matters. Do\n  not add a dedicated test for a pass-through, constant, accessor, or wiring\n  method unless that behavior is itself a documented public or externally\n  visible contract.\n- Never add tests whose subject is another test case, a test class or method,\n  test fixture, mock helper, test utility, or other test-only code. Test only\n  the production behavior that the test-only code supports. Test-support code\n  distributed as an independent artifact with an external contract is\n  production code for this rule.\n- Do not add tests that only prove constants, accessors, delegation, wiring,\n  Java, Lombok, Mockito, parsers, collection libraries, framework behavior, or\n  private implementation shape. Contract literals are exceptions only when no\n  broader behavior can protect them. Never add a test solely to increase a\n  coverage number. Do not duplicate an existing scenario unless the new test\n  covers a new branch, input class, edge case, contract, calculation path, or\n  failure mode.\n- Do not test collaborator rules through the current class. Mock the nearest\n  stable boundary and test the collaborator rule in its owner. Cross-layer\n  behavior belongs in an explicitly scoped integration, contract, or E2E test.\n- Give each behavior-owning public production method focused coverage. Each\n  test method covers one scenario and invokes the target public method at most\n  once; repeat only when the same scenario requires additional assertions. Do\n  not create interface-only tests; exercise concrete implementations.\n- Every new public production type requires direct focused tests, except\n  exception types covered by `Exception Tests`. Broad workflow tests do not\n  replace them unless they explicitly exercise that type's public behavior. If\n  a pure pass-through public type has no meaningful owned or external contract\n  to test, do not add the type merely for structural completeness.\n- Default to direct Mockito mocks. Use a private helper only for repeated local\n  setup and a standalone fixture only for a stable external or packaged test\n  boundary. Give fixtures the narrowest practical visibility, keep them in the\n  nearest owning test package or module, and do not create cross-module test\n  APIs for convenience. Delete or inline thin mock wrappers.\n- Obtain SPI implementations through the project loader by default. Use\n  `Plugins.getMemberAccessor()` for permitted field access; direct reflection\n  APIs and reflective invocation of private methods are forbidden. If the class\n  under test implements `TypedSPI` or `DatabaseTypedSPI`, instantiate it through\n  `TypedSPILoader` or `DatabaseTypedSPILoader`, not with `new`.\n- Prefer `AutoMockExtension` and its static or construction mocking support.\n  Use direct `mockStatic` or `mockConstruction` only when the extension cannot\n  apply and the reason is recorded; scope it with try-with-resources. When a\n  class is listed in `@StaticMockSettings`, do not call `mockStatic` or\n  `mockConstruction` for it; stub it through `when(...)`.\n- Do not mix Mockito matchers with raw arguments in one invocation. Mock\n  databases, caches, registries, network calls, time, and other heavy external\n  dependencies instead of constructing deep unrelated object graphs.\n- Every unit-test class must be named `<ProductionClassName>Test`, using the\n  exact simple name of the production class it directly tests. This class-name\n  rule is mandatory and is independent of scenario-focused test-method naming.\n- Parameterized tests must set `name = \"{0}\"`. Keep test names concise and\n  scenario-focused, following `CODE_OF_CONDUCT.md`; avoid `ReturnsXXX` and\n  wording that restates the expected result instead of naming the scenario.\n- Use JUnit 5 and Mockito. Keep setup, action, and assertions distinct; reset\n  static state between scenarios and reuse existing swappers or helpers for\n  complex configuration.\n- When a coverage target is stated, list every branch or path before coding and\n  map each one to exactly one planned test. Add cases until every declared\n  branch is covered or explicitly waived, update the map when code changes, and\n  verify with JaCoCo when coverage is uncertain. Document unreachable code\n  instead of adding redundant tests.\n\n### Exception Tests\n\n- Do not add dedicated tests for exception classes that only declare\n  constructors or format and forward their arguments to a tested superclass.\n  Add direct tests only for owned validation, branching, calculation,\n  conversion, or a known regression.\n\n## Specialized Workflows\n\n### Repository Workflows\n\nUse the matching repository Skill when its trigger applies:\n\n- Issue diagnosis and copy-ready maintainer replies: `$analyze-issue`.\n- Unit-test generation or systematic coverage work: `$gen-ut`.\n- PR correctness, side effects, mergeability, GitHub review replies, or the\n  pre-handoff review of an authorized implementation targeting an existing PR:\n  `$review-pr`. For pre-handoff review, use its Local Candidate Preflight Mode.\n\nIf a matching repository Skill is unavailable, apply an equivalent manual\nchecklist, record the fallback in the plan or final response, and continue\nwithout installing it. Do not create a new Skill merely to hold task-specific\ninstructions.\n\n### Optional Cross-Cutting Skills\n\nThe Skills in this subsection are optional workflow accelerators, not\nprerequisites. Availability alone is not a trigger. When an optional Skill is\navailable and its trigger below applies, prefer it and use only the smallest\nmatching Skill set. If it is unavailable, skip the Skill itself and continue\nwith the applicable repository gates and ordinary workflow. Do not install,\ncreate, reconstruct, or treat the absence of an optional Skill as a blocker.\nMention the absence only when the user explicitly requested the Skill or it\nleaves a material residual risk.\n\nSkipping a Skill never waives compatibility, correctness, security, scope,\nverification, or completion requirements. Using a Skill never expands the\nfrozen task scope, allowed modules or files, acceptance checklist, write or\nremote authority, Git authority, or tool permissions. This guide prevails when\na Skill conflicts with it.\n\n- Implementation or review whose correctness depends on the current version of\n  an external framework or library: use `$source-driven-development` when\n  available. Identify the applicable version from repository dependency\n  metadata, verify the relevant decision against authoritative primary\n  documentation, record the source, and mark anything that cannot be verified\n  as unverified. This verification remains required without the Skill. Do not\n  invoke it for version-independent local logic.\n- Designing, adding, or changing a public API, SPI, extension, loading or\n  registration contract, module boundary, externally visible interface, or\n  cross-module type contract: use `$api-and-interface-design` when available\n  before implementation. Apply the Architecture change and Contract and Impact\n  gates whether or not the Skill is available; using it does not authorize the\n  change or expand the confirmed scope.\n- An unexpected test, build, runtime, or behavior failure: use\n  `$debugging-and-error-recovery` when available. Stop unrelated implementation,\n  preserve evidence, reproduce, localize, reduce, identify the root cause, and\n  verify the result. Add focused regression protection only when the root cause\n  is an in-scope production defect and the test protects meaningful owned\n  behavior; do not add a test for an environment, infrastructure, or unrelated\n  failure. A failure never authorizes an out-of-boundary fix or a Git write.\n- An explicit performance requirement, reproducible reported slowness or\n  suspected regression, profiling evidence, or a requested change that can\n  materially alter the cost of a confirmed performance-sensitive path: use\n  `$performance-optimization` when available to measure first. A path being\n  high-volume by itself is not a trigger. Freeze the workload, metric,\n  environment, and baseline; identify the owning bottleneck before editing;\n  test one hypothesis at a time; and repeat the same measurement with\n  correctness checks. Keep a change only when the improvement exceeds\n  run-to-run variance and correctness remains intact. Remove neutral, worse,\n  or incorrect current-task experiments. Record attempts in the task unless an\n  exact file or remote target is separately authorized. Do not optimize by\n  intuition or follow adjacent hotspots outside the frozen boundary.\n- After scoped behavior and checks pass, when the effective task delta contains\n  concrete unnecessary complexity or a review identifies it: use\n  `$code-simplification` when available on that delta only. Preserve behavior\n  exactly and never perform a drive-by refactor or gain Git authority from the\n  Skill. Do not invoke it merely because the Completion Loop is running or when\n  the candidate is already clear.\n- An explicit user request to threat model a repository or path, enumerate\n  threats or abuse paths, or perform AppSec threat modeling: use\n  `$security-threat-model` when available. Do not invoke it for an ordinary\n  architecture summary, code review, security check, or non-security design.\n  The request remains read-only unless the user also authorizes the exact\n  output file; the Skill's default artifact creation grants no write authority.\n- A non-trivial decision involving module boundaries, public contracts,\n  unfamiliar code, or high-risk behavior, or a branching invariant that is not\n  directly established by types, existing tests, or an explicit contract and\n  whose failure would materially affect correctness, compatibility, security,\n  or another high-risk behavior: use `$doubt-driven-development` when available\n  only within the active task. An ordinary branch is not a trigger. The\n  prohibition on additional Codex tasks and external review overrides its\n  fresh-context and cross-model steps. Perform bounded adversarial self-review\n  instead and do not report the full Skill as completed.\n\nDo not include sensitive repository data in external searches.\n\n## Contract and Impact Gates\n\n- For a public or externally visible identifier, search all affected reference\n  surfaces: APIs, SQL, configuration and YAML keys, SPIs, errors, CLI commands,\n  resources, documentation, examples, distributions, tests, E2E, and\n  baselines. Exclude `.git` and `target`. If a compatibility alias remains,\n  state whether it is discoverable; if it must stay hidden, protect that\n  contract with a focused test or check.\n- Name the affected database engines and dialects and preserve backward\n  compatibility for their supported versions unless an exact compatibility\n  break is authorized.\n- For errors, logs, HTTP or JSON payloads, CLI output, and exception conversion,\n  test the complete external output when it could expose credentials, tokens,\n  connection strings, SQL, paths, or user data.\n- Regenerate or verify affected snapshots, golden files, fingerprints, SQL\n  cases, descriptors, schemas, and agent-visible metadata with the existing\n  project tool.\n- Determine affected GitHub Actions from changed-file path filters and job\n  commands. Run the local equivalent when practical; otherwise record the\n  narrower check and residual risk. Do not update remote workflow state.\n- When runtime paths change, record relevant engine or dialect compatibility\n  and a performance baseline or guardrail. When governance, registry,\n  observability, or agent integrations are touched, state their impact.\n\n## Runtime Triage\n\n- For Proxy startup, prefer the existing IDE/MCP `Bootstrap` configuration or a\n  scoped `proxy` package with explicit upstream modules. Record the\n  configuration path, mode, ports, command, and exit code.\n- For JDBC smoke tests, use a current-source IDE/MCP run or a focused `jdbc`\n  module test with explicit upstream modules and datasource setup.\n- Keep standalone `server.yaml` and affected cluster `mode/` configuration\n  behavior aligned; call out default changes.\n- For startup, routing, or runtime failures, inspect `proxy/logs/` and relevant\n  `target/surefire-reports`; correlate decisive lines with configuration,\n  metadata freshness, parser dialect, and the owning data-flow step. For routing\n  failures, also inspect feature-rule configuration and report the SQL, relevant\n  configuration, owning module, and focused test. Do not edit generated output.\n- For a sandbox or network denial, report the command, failure, and safe\n  alternative or required authorization.\n- When an E2E, integration, client smoke, or Docker smoke fails, hangs, or times\n  out, stop rerunning. Classify it as environment, classpath, stale snapshot,\n  dependency, test design, protocol implementation, data setup, assertion\n  logic, or external-service behavior, then record evidence and minimum fix\n  scope before changing code or configuration. Complete deterministic\n  prerequisites such as classpath consistency, stale-bytecode checks, dependency\n  alignment, or required evidence capture before running one matching sentinel;\n  if it fails unexpectedly, return to analysis.\n\n## Verification and Commands\n\nRun the narrowest meaningful checks first. Derive explicit Maven modules from\nchanged owners, affected tests, and consuming runtime modules.\n\n- Focused test:\n  `./mvnw -pl <module> -DskipITs -Dspotless.skip=true\n  -Dtest=<FullyQualifiedTestClassName>\n  -Dsurefire.failIfNoSpecifiedTests=false test`\n- Scoped tests: `./mvnw test -pl <explicit-module-set>`\n- Scoped package:\n  `./mvnw -pl <explicit-module-set> -DskipTests package`\n- Coverage:\n  `./mvnw -pl <explicit-module-set> -Djacoco.skip=false test jacoco:report`\n- Full build: `./mvnw clean install -B -T1C -Pcheck`\n\nPrefer current-source IDE/MCP runs or explicit `-pl` module sets. Use `-am`\nonly when dependency freshness, missing reactor artifacts, or CI equivalence\ncannot otherwise be established, normally once per unchanged task state. For\nmulti-module checks, verify lower-level changed owners before their higher-level\nconsumers.\n\nKeep background unit tests under 60 seconds. Capture high-volume output\naccording to `.codex/context/token-efficiency.md`; report commands, exit codes,\nand decisive log excerpts instead of dumping raw logs.\n\nFor every user-forbidden tool, API, assertion, or pattern, run a scoped final\nsearch and report the command and result. Do not rely only on plan compliance.\n\nAfter the last file-changing action:\n\n1. Run `./mvnw spotless:apply -Pcheck -T1C` for code or documentation changes.\n2. Run `./mvnw checkstyle:check -Pcheck -T1C` when production, test, or\n   project-rule files changed.\n3. Do not manually reformat afterward. Any later edit invalidates formatting\n   and requires the applicable checks again.\n\n## Completion Loop\n\nFor an authorized change, build, implement, or fix request, excluding a\nstandalone restoration or rollback:\n\n1. Compare the task-introduced delta with the recorded pre-edit baseline, the\n   read-only `git diff`, surrounding context, and the acceptance checklist.\n2. Confirm every task-introduced file and hunk is necessary, expected changed\n   files contain only their frozen change intent, prohibited paths have zero\n   task delta, direct reuse was considered, architecture changes were\n   authorized, and every test protects owned behavior. Inspect Java changes for\n   newly added local-variable `final`, scan changed code and Skills for local\n   absolute paths, and remove only current-task violations.\n3. Treat scripts, searches, formatting, compilation, and passing tests as\n   evidence, not proof of semantic compliance. Judge the final behavior,\n   contracts, architecture, and user request directly; fix every safe in-scope\n   violation instead of reporting it as an accepted risk.\n4. Apply `$code-simplification` under Optional Cross-Cutting Skills only when\n   its concrete complexity trigger is present and the Skill is available. Do\n   not invoke it merely because this loop is running; a clear task delta or an\n   unavailable Skill does not block handoff.\n5. Review the effective local candidate against the same code-correctness gates\n   used by `$review-pr`: root cause and fix mapping, affected behavior, side\n   effects and regressions, contracts and architecture, test validity, and\n   adversarial cases. Apply `$code-review-and-quality` when available, or its\n   equivalent review, for the general quality axes; it does not replace these\n   shared correctness gates.\n6. When the implementation targets an existing PR, also apply `$review-pr` in\n   Local Candidate Preflight Mode before handoff. PR-specific public-head and\n   remote-evidence checks remain part of formal PR review.\n7. Fix every safe in-scope required finding, rerun invalidated checks, and\n   repeat the applicable reviews. If a finding requires scope expansion, an\n   unresolved architecture choice, or a high-risk action, stop at its existing\n   authorization gate instead of fixing it automatically.\n8. Hand off and propose a commit message only after one complete applicable\n   review pass finds zero new required issues. Before that review passes, do not\n   hand off or propose a commit message. Do not defer a locally discoverable\n   required finding to a later formal PR review.\n9. Stop when no required in-scope finding remains. Do not iterate for optional\n   polish, broad cleanup, or risky refactoring.\n\nIf a report or verdict is disproved, fix the highest-leverage rule, schema,\nvalidator, prompt, or regression case before correcting the artifact, unless\nthe user explicitly requests a one-off correction.\n\nThe final response must lead with the outcome and include changed files and\nrationale, commands with exit codes, verification status, remaining risks, and\nthe next action only when one is still required. When Git commit authorization\nis absent, provide a proposed commit message without staging or committing.\n","category":"root","tokens":11241}]}