aw-spec-cli 0.1.9 → 0.1.11

package/assets/guardrails/technology/java-spring/ai-rules.md

@@ -0,0 +1,505 @@
+# AI Operational Rules
+
+> Common technology guardrails for Java/Spring applications built from the AppWeaver Java foundation.
+>
+> Technology-specific and domain-agnostic. Applies to all AI agents and all commands unless a higher-priority project rule explicitly overrides it.
+
+AI agents MUST treat the **project constitution**, **AppWeaver Java foundation architecture**, and **applicable technology guardrails** as the authoritative source of truth.
+
+AI agents MUST NOT replace established AppWeaver conventions with generic Java, Spring, DDD, or architectural assumptions.
+
+---
+
+## 1. Source-of-Truth Hierarchy
+
+When multiple sources provide conflicting guidance, AI agents MUST resolve them in the following order:
+
+1. **Project Constitution**
+2. **AppWeaver Java Foundation Architecture and Package Structure**
+3. **Applicable Technology Guardrails**
+4. **Application/Module-Specific Rules**
+5. **Existing Repository Implementation and Established Conventions**
+6. **Generic Java/Spring Framework Defaults**
+7. **AI Agent's Pre-trained Assumptions**
+
+Higher-priority rules MUST NOT be overridden by lower-priority conventions.
+
+---
+
+## 2. AppWeaver Java Foundation
+
+The application MUST follow the predefined AppWeaver Java foundation.
+
+The mandatory production Java source root is:
+
+`backend/src/main/java/io/appweaver/`
+
+The foundation defines the following four top-level architectural packages:
+
+```text
+backend/src/main/java/io/appweaver/
+├── adapter/
+├── application/
+├── domain/
+└── infrastructure/
+```
+
+These four packages are the authoritative top-level production package structure.
+
+### Package rules
+
+* All generated production Java code MUST be placed under one of the four approved top-level packages:
+
+  * `io.appweaver.adapter`
+  * `io.appweaver.application`
+  * `io.appweaver.domain`
+  * `io.appweaver.infrastructure`
+* AI agents MUST NOT create another top-level package directly under `io.appweaver`.
+* AI agents MUST NOT introduce alternative structures such as:
+
+  * `controller`
+  * `service`
+  * `repository`
+  * `model`
+  * `feature`
+  * `features`
+  * `vertical-slice`
+  * `common`
+  * or another top-level architectural package.
+* Subpackages MAY be created underneath the four approved packages when required by the established Java foundation and module structure.
+* AI agents MUST inspect the existing repository structure before deciding where new code belongs.
+* AI agents MUST preserve the existing module and package organization.
+* AI agents MUST NOT reorganize the foundation package structure as part of an unrelated feature change.
+* Test source structure MUST follow the existing project conventions.
+
+If a requested implementation cannot be placed correctly within the established foundation structure, the AI agent MUST request clarification rather than inventing an alternative structure.
+
+---
+
+## 3. Modular Monolith Architecture
+
+The Java application follows a **Modular Monolith** architecture.
+
+The application is a single deployable application containing internally separated modules.
+
+AI agents MUST preserve module boundaries.
+
+Each module MUST maintain ownership of its applicable:
+
+* domain model
+* application/use-case logic
+* ports and contracts
+* adapters
+* infrastructure implementation
+* persistence concerns
+
+AI agents MUST NOT:
+
+* introduce microservices unless explicitly requested
+* introduce distributed communication between modules unless explicitly required
+* directly access another module's internal domain objects
+* directly access another module's repositories or persistence implementations
+* bypass another module's public application contracts or ports
+* introduce dependencies that violate the established module dependency direction
+
+Cross-module interaction MUST use the mechanisms defined by the project's architecture.
+
+---
+
+## 4. Hexagonal Architecture
+
+The application follows the established **Hexagonal Architecture / Ports and Adapters** model.
+
+AI agents MUST preserve the separation between:
+
+* domain/business logic
+* application/use-case logic
+* inbound adapters
+* outbound adapters
+* infrastructure/framework concerns
+
+Business rules MUST NOT become dependent on infrastructure-specific implementation details unless explicitly permitted by the foundation.
+
+AI agents MUST NOT introduce a competing architectural model such as:
+
+* Vertical Slice Architecture
+* traditional layered architecture
+* controller-service-repository architecture as the primary architectural model
+* MVC-centric domain design
+* another package-oriented architecture
+
+The predefined Java foundation remains authoritative.
+
+---
+
+## 5. Repository and Context Inspection
+
+Before generating or modifying code, AI agents MUST inspect the relevant existing implementation.
+
+At minimum, AI agents SHOULD determine:
+
+* the owning module
+* the relevant domain model
+* the applicable application/use case
+* existing ports
+* existing adapters
+* existing infrastructure components
+* existing DTOs/contracts
+* existing validation
+* existing exception handling
+* existing cross-cutting capabilities
+* existing tests
+* applicable configuration
+
+AI agents MUST confirm existing symbol signatures through repository search rather than inferring them from generic framework knowledge.
+
+Existing AppWeaver abstractions MUST be reused when applicable.
+
+AI agents MUST NOT recreate an abstraction that already exists in the foundation or relevant module.
+
+---
+
+## 6. Code Generation Rules
+
+AI agents MUST generate only the components required by the requested behavior and applicable architecture.
+
+AI agents MUST NOT assume that every use case requires:
+
+* Command
+* Query
+* Handler
+* Specification
+* DTO
+* Mapper
+* Service
+* Repository
+* Integration test
+* or any other component
+
+These components MUST be created only when required by the application's architecture, use case, or established conventions.
+
+AI agents MUST:
+
+* prefer existing abstractions
+* follow existing naming conventions
+* follow existing visibility conventions
+* follow existing validation conventions
+* follow existing exception conventions
+* follow existing transaction conventions
+* follow existing persistence conventions
+* follow existing mapping conventions
+* use Java and Spring capabilities appropriately
+
+AI agents MUST NOT introduce speculative abstractions such as:
+
+* single-implementation interfaces without an architectural requirement
+* unnecessary generic wrappers
+* duplicate framework abstractions
+* abstractions created solely for theoretical future requirements
+
+This follows **YAGNI** unless the constitution or architecture explicitly requires otherwise.
+
+---
+
+## 7. Dependency Rules
+
+AI agents MUST NOT introduce new top-level dependencies unless explicitly approved or required by an existing project standard.
+
+Before introducing a dependency, AI agents MUST verify whether the required capability is already provided by:
+
+* Java
+* Spring Boot
+* Spring Framework
+* Spring Data
+* JPA/Hibernate
+* an existing AppWeaver abstraction
+* an already-approved project dependency
+
+AI agents MUST NOT introduce a dependency merely to duplicate functionality already available through the established technology stack.
+
+New dependencies MUST comply with the project's dependency-management and security standards.
+
+---
+
+## 8. AppWeaver Cross-Cutting Capabilities
+
+AppWeaver provides a common set of reusable cross-cutting technology guardrails.
+
+The following guardrails are part of the AppWeaver Java technology foundation:
+
+* `authorization.md`
+* `domain_abstraction.md`
+* `global_exception_handler.md`
+* `logging.md`
+* `problem_details.md`
+* `result_mapping.md`
+
+These guardrails define **available standardized implementations and extension mechanisms**.
+
+### Important applicability rule
+
+The existence of a cross-cutting guardrail does **NOT** mean that every application MUST enable or use that capability.
+
+An application MUST use a cross-cutting capability when:
+
+* the application's requirements require it;
+* the project constitution requires it;
+* the application architecture explicitly enables it; or
+* the relevant technology standard declares it applicable.
+
+AI agents MUST determine applicability from the project's requirements, constitution, architecture, and existing implementation.
+
+AI agents MUST NOT automatically add or activate every available cross-cutting capability merely because the guardrail exists.
+
+### When a capability is applicable
+
+When an application requires one of these capabilities, AI agents MUST:
+
+* use the corresponding AppWeaver guardrail;
+* reuse the provided implementation and abstractions;
+* follow its documented extension points;
+* integrate new application code with the existing mechanism;
+* preserve its established behavior;
+* avoid creating duplicate implementations.
+
+AI agents MUST NOT silently replace an applicable AppWeaver cross-cutting capability with a custom implementation.
+
+AI agents MUST NOT create feature-specific copies of a foundation-level cross-cutting concern when an approved AppWeaver implementation already exists.
+
+AI agents MUST NOT globally disable an applicable cross-cutting capability without explicit authorization.
+
+### Examples
+
+If authorization is required:
+
+* use `authorization.md` and its established mechanism;
+* do not create a separate authorization framework or custom authorization mechanism.
+
+If global exception handling is required:
+
+* use `global_exception_handler.md`;
+* do not create another global exception handler.
+
+If Problem Details is required:
+
+* follow `problem_details.md`;
+* do not introduce an unrelated error-response format.
+
+If logging is required:
+
+* follow `logging.md`;
+* do not create a parallel logging abstraction or logging framework.
+
+If a capability is not required by the application, AI agents MUST NOT introduce it merely for completeness.
+
+---
+
+## 9. Cross-Cutting Boundary Rules
+
+Cross-cutting concerns MUST be implemented at the appropriate foundation/application level defined by their respective guardrail.
+
+AI agents MUST NOT duplicate cross-cutting behavior inside individual modules when the AppWeaver foundation already provides the applicable mechanism.
+
+AI agents MUST NOT bypass established cross-cutting mechanisms through:
+
+* direct framework-specific alternatives
+* local duplicate implementations
+* feature-specific global handlers
+* ad-hoc response formats
+* ad-hoc logging mechanisms
+* unauthorized security checks
+* direct access to internal infrastructure
+
+Module-specific behavior MAY extend a cross-cutting capability when the corresponding guardrail explicitly supports extension.
+
+---
+
+## 10. Testing Rules
+
+Production changes MUST include appropriate automated tests according to the project's testing standards.
+
+Tests MUST correspond to the responsibility of the code being changed.
+
+Where applicable:
+
+* domain behavior SHOULD be tested independently of infrastructure;
+* application/use-case behavior SHOULD be tested independently of external infrastructure;
+* adapters SHOULD have appropriate integration tests;
+* infrastructure integrations SHOULD be covered by appropriate integration testing.
+
+AI agents MUST NOT create unnecessary tests solely to satisfy a fixed test-count requirement.
+
+AI agents MUST NOT remove or weaken existing tests merely to make an implementation pass.
+
+When modifying existing behavior, affected tests MUST be updated accordingly.
+
+Test-first development SHOULD be followed when required by the project development standards.
+
+---
+
+## 11. Database and Migration Rules
+
+AI agents MAY create database migration files using the application's approved migration mechanism when a schema change is required.
+
+Migrations MUST:
+
+* follow the approved migration framework;
+* follow existing naming and versioning conventions;
+* be deterministic;
+* be compatible with the application's deployment process;
+* avoid unintended data loss.
+
+AI agents MUST NOT execute database migrations against shared or production environments autonomously.
+
+Destructive migrations MUST receive the required project review before deployment.
+
+AI agents MUST NOT introduce a second migration framework when an approved framework already exists.
+
+---
+
+## 12. Transaction and Consistency Rules
+
+Transaction boundaries MUST follow the application's established architecture and transaction rules.
+
+AI agents MUST NOT introduce transactions merely to simplify implementation.
+
+AI agents MUST NOT use transactions to bypass module boundaries.
+
+AI agents MUST NOT introduce cross-module consistency mechanisms that contradict the application's domain or architecture rules.
+
+Where consistency requirements span modules, AI agents MUST follow the project's established integration and consistency mechanism.
+
+---
+
+## 13. Security and Sensitive Data
+
+AI agents MUST NOT:
+
+* embed passwords or credentials in source code;
+* embed API keys or access tokens;
+* embed private keys;
+* embed production connection strings;
+* hard-code production secrets;
+* hard-code production credentials;
+* expose secrets through logs;
+* expose sensitive information through API responses;
+* expose sensitive information through exception messages.
+
+AI agents MUST refuse or request clarification when a request requires introducing such information.
+
+AI agents MUST preserve established security controls.
+
+AI agents MUST NOT disable authentication, authorization, or other security controls globally.
+
+---
+
+## 14. Cross-Cutting Security and Operational Controls
+
+Where these controls exist in the application, AI agents MUST preserve them:
+
+* authentication
+* authorization
+* audit handling
+* correlation/request context
+* structured logging
+* sensitive-data masking
+* tenancy controls
+* soft-delete behavior
+* validation
+* security interceptors
+* other established operational controls
+
+AI agents MUST NOT disable these controls globally merely to make a feature work.
+
+If a feature legitimately requires an exception to an existing control, the AI agent MUST follow the extension mechanism defined by the applicable guardrail rather than bypassing the control.
+
+---
+
+## 15. Change Scope
+
+AI-generated changes MUST remain within the scope explicitly requested.
+
+AI agents MUST NOT perform unrelated:
+
+* refactoring
+* package restructuring
+* architecture changes
+* dependency upgrades
+* framework migrations
+* naming changes
+* formatting changes across unrelated files
+
+Drive-by refactoring is forbidden.
+
+If an implementation requires an architectural change, the AI agent MUST identify that requirement rather than silently making the architectural change.
+
+---
+
+## 16. Backward Compatibility
+
+AI agents SHOULD preserve existing API and behavioral compatibility unless a breaking change is explicitly requested or required by an approved architectural change.
+
+Breaking changes MUST NOT be introduced implicitly.
+
+When an API contract, persistence contract, module contract, or shared abstraction must change, affected consumers MUST be identified and handled according to the project's compatibility rules.
+
+---
+
+## 17. Comments and Documentation
+
+AI agents MUST NOT add comments solely to explain standard Java, Spring, DDD, or architectural decisions already defined by the project standards.
+
+The constitution, architecture documentation, and technology guardrails are the authoritative sources for those decisions.
+
+Comments MAY be added when they explain:
+
+* non-obvious implementation behavior;
+* important technical constraints;
+* security-sensitive behavior;
+* compatibility requirements;
+* complex algorithms;
+* unavoidable framework-specific behavior.
+
+---
+
+## 18. Refusal and Clarification Conditions
+
+AI agents MUST refuse or request clarification when a requested change would:
+
+* violate a **NON-NEGOTIABLE** constitutional principle;
+* violate the AppWeaver Java foundation architecture;
+* create production code outside the approved foundation package structure;
+* violate module boundaries;
+* introduce an unauthorized architectural pattern;
+* bypass an applicable AppWeaver cross-cutting capability;
+* replace an established AppWeaver abstraction without approval;
+* introduce an unauthorized dependency;
+* embed secrets or production credentials;
+* disable authentication or authorization globally;
+* disable applicable security or operational controls globally;
+* require an architectural change that has not been explicitly approved;
+* require direct access to another module's internal implementation;
+* require behavior that contradicts a higher-priority project rule.
+
+When the conflict can be resolved by an existing project rule or established implementation, the AI agent MUST follow that rule rather than inventing a new solution.
+
+---
+
+## 19. Core Principle
+
+AI agents MUST generate code that is **consistent with the existing AppWeaver Java foundation**, not code based on a generic interpretation of how a Java/Spring application should be structured.
+
+The AI agent MUST preserve:
+
+* the predefined Java foundation package structure;
+* the Modular Monolith architecture;
+* the Hexagonal Architecture / Ports and Adapters model;
+* module boundaries;
+* established AppWeaver abstractions;
+* applicable cross-cutting capabilities;
+* existing project conventions;
+* and higher-priority constitutional rules.
+
+The presence of a guardrail defines an **approved capability and its implementation standard**. It does not, by itself, make that capability mandatory for every application.
+
+An application-specific requirement determines whether an available cross-cutting capability is applicable.