aw-spec-cli 0.1.10 → 0.1.11

package/assets/guardrails/technology/java-spring/dependency-policy.md

@@ -0,0 +1,91 @@
+# Java Dependency Policy
+
+> Pure technology (domain-agnostic). See also: `coding-standards.md`, `ai-rules.md`.
+
+## Dependency Governance
+
+- Dependencies MUST be declared in the approved Java build files, normally `pom.xml` for Maven projects.
+- Dependency versions MUST be controlled consistently through the project parent, dependency management, Maven properties, or an approved BOM.
+- New production dependencies MUST have a clear architectural purpose and an identified owning layer.
+- Generated code MUST NOT introduce new top-level dependencies unless the specification, design, or explicit developer instruction authorizes them.
+- Dependencies MUST NOT bypass hexagonal boundaries or make the domain depend on infrastructure frameworks.
+- Unused, duplicate, abandoned, or overlapping dependencies MUST be removed.
+
+## Approved Technology Defaults
+
+- Runtime: Java 21 or the Java version declared by the active AppWeaver Java foundation.
+- Application framework: Spring Boot.
+- Web/API: Spring Web or Spring MVC, with explicit REST contracts.
+- Validation: Jakarta Bean Validation for request shape validation.
+- Persistence: PostgreSQL for production unless an approved architecture decision states otherwise.
+- ORM/persistence adapters: Spring Data JPA and Hibernate inside infrastructure only.
+- Migrations: Flyway unless an approved project decision selects another migration tool.
+- Testing: JUnit 5, Mockito, Spring Boot Test, and Testcontainers where applicable.
+- API documentation: OpenAPI-compatible tooling where API contracts are exposed.
+- Observability: SLF4J-compatible structured logging, Micrometer metrics, health checks, and OpenTelemetry-compatible tracing where required.
+
+## Layer Ownership
+
+- Domain MAY depend only on Java language/runtime APIs and approved domain-safe libraries.
+- Domain MUST NOT depend on Spring, JPA, Hibernate, database drivers, HTTP clients, messaging clients, logging implementations, or external SDKs.
+- Application MAY depend on domain types and application-owned ports/contracts.
+- Application MUST NOT depend directly on persistence implementations or external service SDKs.
+- Inbound adapters MAY depend on Spring Web, validation, security, and API documentation libraries.
+- Outbound adapters MAY depend on persistence, messaging, HTTP client, cloud, or vendor SDK libraries needed to implement output ports.
+- Infrastructure configuration MAY wire frameworks, transactions, repositories, security, observability, and external clients.
+
+## Preferred Practices
+
+- Prefer standard Spring Boot starters already present in the foundation over introducing alternative frameworks.
+- Prefer explicit mapping code over reflection-based object mapping.
+- Prefer small, focused dependencies over broad utility libraries.
+- Prefer Java standard library features when they satisfy the requirement cleanly.
+- Prefer mature, maintained libraries with active security updates.
+- Prefer dependencies that integrate cleanly with Maven, Spring Boot, testing, observability, and CI.
+
+## Banned or Restricted Dependencies
+
+- Reflection-based mapping frameworks are restricted and require explicit approval.
+- Alternate web frameworks, persistence frameworks, mediator frameworks, or dependency injection containers are restricted unless an architecture decision approves them.
+- Libraries that require domain objects to inherit framework base classes or carry framework annotations are forbidden for domain use.
+- Dependencies that exfiltrate telemetry, analytics, or customer data by default are forbidden.
+- Dependencies with incompatible licenses are forbidden.
+- Libraries with known unresolved critical vulnerabilities MUST NOT be introduced.
+- Snapshot, local, or unpublished dependencies MUST NOT be used in production builds without explicit approval.
+
+## Supply Chain Rules
+
+- New dependencies MUST be reviewed for license, maintenance status, vulnerability history, transitive dependency risk, and operational impact.
+- Dependency updates SHOULD be small, reviewable, and tested.
+- Transitive dependencies MUST be monitored for vulnerabilities.
+- Build plugins MUST be governed with the same care as runtime dependencies.
+- Dependency repositories MUST be trusted and approved.
+- Credentials for artifact repositories MUST NOT be committed to source control.
+
+## Versioning Rules
+
+- Dependency versions MUST be reproducible in CI.
+- Version ranges are forbidden for production dependencies.
+- Major version upgrades require compatibility review and regression testing.
+- Security patches SHOULD be applied promptly after impact assessment.
+- The project MUST avoid mixing incompatible Spring Boot, Spring Framework, Hibernate, Jakarta, and Java versions.
+
+## AI / AW-Spec Rules
+
+- AI-generated changes MUST reuse existing dependencies and framework patterns where possible.
+- AI MUST NOT add Maven dependencies, plugins, repositories, or BOMs without explicit authority from the specification, design, or developer instruction.
+- AI MUST NOT introduce a dependency to avoid writing straightforward application code.
+- AI MUST keep dependency usage within the owning layer.
+- AI MUST update tests and documentation when an approved dependency changes behavior or public contracts.
+
+## Quality Gates
+
+- Maven dependency resolution MUST succeed in CI.
+- Tests MUST pass after dependency changes.
+- Vulnerability and license checks SHOULD pass where configured.
+- Static checks SHOULD verify that forbidden dependencies do not appear in domain modules or packages.
+- The dependency tree SHOULD be reviewed when adding production dependencies.
+
+## Related
+
+See also: `coding-standards.md` · `ai-rules.md`

package/assets/guardrails/technology/java-spring/domain-driven-design.md

@@ -0,0 +1,467 @@
+# Domain-Driven Design Standards (Tactical Patterns)
+
+> Domain-focused and technology-agnostic DDD standards.
+>
+> Business-specific aggregate definitions and domain rules belong in the relevant
+> domain specification files.
+
+---
+
+## 1. Ubiquitous Language
+
+- Each bounded context MUST use a consistent ubiquitous language.
+- Domain concepts MUST use terminology that reflects the business domain.
+- Terms with different meanings in different bounded contexts MUST NOT be treated as the same concept without an explicit translation.
+- Technical implementation terminology MUST NOT replace established domain terminology.
+- Business-specific terminology MUST be defined in the relevant domain specification rather than this generic standard.
+
+---
+
+## 2. Bounded Contexts
+
+- A bounded context defines a clear boundary around a domain model and its ubiquitous language.
+- Domain models MUST remain internally consistent within their bounded context.
+- A domain model MUST NOT directly depend on another bounded context's internal domain model.
+- Communication between bounded contexts MUST use explicitly defined contracts or translation mechanisms.
+- Shared concepts MUST be introduced only when they genuinely represent the same concept across the relevant contexts.
+- Business-specific bounded-context definitions belong in the relevant domain specification.
+
+---
+
+## 3. Aggregate Design
+
+- An Aggregate is a consistency boundary containing one or more related domain objects.
+- Every Aggregate MUST have exactly one Aggregate Root.
+- The Aggregate Root is the only object through which external code may modify the Aggregate.
+- Aggregate boundaries MUST be designed around business invariants and transactional consistency requirements.
+- Aggregates SHOULD remain as small as practical.
+- An Aggregate MUST NOT contain objects merely because they are conceptually related if they do not require the same consistency boundary.
+- Cross-aggregate references SHOULD use identity rather than direct object references.
+- Aggregates MUST protect their internal state from uncontrolled external mutation.
+
+### Aggregate Root Responsibilities
+
+An Aggregate Root SHOULD:
+
+1. Enforce business invariants.
+2. Control the lifecycle of child entities.
+3. Coordinate state changes within the Aggregate.
+4. Protect the Aggregate's internal state.
+5. Raise domain events for significant externally observable state changes where required.
+
+---
+
+## 4. Aggregate Invariants
+
+- Business invariants MUST be enforced within the domain model.
+- An Aggregate MUST NOT allow a state that violates one of its invariants.
+- Invariants MUST be enforced regardless of which application use case invokes the Aggregate.
+- Public methods that mutate domain state MUST preserve the Aggregate's invariants.
+- Validation performed at an API or application boundary MUST NOT be considered a replacement for domain invariant enforcement.
+- Business rules that require multiple domain objects within the same consistency boundary SHOULD be enforced by the Aggregate Root.
+
+---
+
+## 5. Entity
+
+- An Entity is a domain object whose identity distinguishes it from other objects of the same type.
+- Entity identity MUST remain stable throughout the Entity lifecycle.
+- Entity equality MUST be based on identity rather than mutable attributes.
+- Mutable domain attributes MUST NOT be used as the basis of Entity identity.
+- Entities MUST protect state changes through intention-revealing domain operations where business rules apply.
+- Entities SHOULD NOT expose unrestricted setters when doing so would allow invalid domain state.
+
+---
+
+## 6. Child Entities
+
+- Child Entities belong to the lifecycle of their Aggregate.
+- Child Entities MUST NOT be independently modified in a way that bypasses Aggregate invariants.
+- Creation, modification, and removal of child Entities SHOULD be controlled by the Aggregate Root.
+- Child Entities MAY enforce their own local invariants.
+- Aggregate-level invariants MUST remain the responsibility of the Aggregate Root.
+- Child Entity identity MUST remain distinct from the identity of the Aggregate Root.
+
+---
+
+## 7. Value Objects
+
+Value Objects represent descriptive domain concepts whose identity is determined by their values.
+
+Value Objects SHOULD follow these rules:
+
+- They MUST be immutable.
+- They MUST be compared by value rather than identity.
+- They SHOULD validate themselves when created.
+- Invalid Value Objects MUST NOT be created.
+- They SHOULD expose meaningful domain behavior rather than being treated as generic data containers.
+- Their implementation MUST NOT expose mutable internal state.
+- Value Objects SHOULD use meaningful domain names rather than generic wrappers such as `StringValue` or `GenericCode`.
+
+Example:
+
+```java
+public final class ProjectCode {
+
+    private final String value;
+
+    private ProjectCode(String value) {
+        if (value == null || value.isBlank()) {
+            throw new DomainException("Project code cannot be blank.");
+        }
+
+        this.value = value.strip().toUpperCase();
+    }
+
+    public static ProjectCode from(String value) {
+        return new ProjectCode(value);
+    }
+
+    public String value() {
+        return value;
+    }
+
+    @Override
+    public boolean equals(Object other) {
+        return other instanceof ProjectCode that
+            && value.equals(that.value);
+    }
+
+    @Override
+    public int hashCode() {
+        return value.hashCode();
+    }
+
+    @Override
+    public String toString() {
+        return value;
+    }
+}
+````
+
+---
+
+## 8. Strongly Typed Domain Identifiers
+
+* Aggregate Roots and Entities SHOULD use dedicated domain identifier types when the domain benefits from stronger type safety.
+* A domain identifier MUST represent one specific identity concept.
+* Different identity concepts MUST NOT be interchangeable merely because they use the same underlying primitive type.
+* Identifier equality MUST be value-based.
+* Identifiers MUST NOT contain business behavior unrelated to identity.
+* Identifier creation MUST reject invalid or missing values.
+* The underlying representation of an identifier is an implementation concern and MUST NOT determine the domain semantics.
+
+Example:
+
+```java
+public final class ProjectId {
+
+    private final UUID value;
+
+    private ProjectId(UUID value) {
+        this.value = Objects.requireNonNull(value);
+    }
+
+    public static ProjectId from(UUID value) {
+        return new ProjectId(value);
+    }
+
+    public static ProjectId generate() {
+        return new ProjectId(UUID.randomUUID());
+    }
+
+    public UUID value() {
+        return value;
+    }
+
+    @Override
+    public boolean equals(Object other) {
+        return other instanceof ProjectId that
+            && value.equals(that.value);
+    }
+
+    @Override
+    public int hashCode() {
+        return value.hashCode();
+    }
+}
+```
+
+---
+
+## 9. Domain Events
+
+* A Domain Event represents a significant business occurrence that has already happened.
+* Domain Events MUST be expressed in domain terms.
+* Domain Events SHOULD be immutable.
+* Domain Events SHOULD contain the information required by consumers to understand the occurrence without exposing internal Aggregate state.
+* Domain Events SHOULD use past-tense naming.
+
+Examples:
+
+* `ProjectCreated`
+
+* `BookingConfirmed`
+
+* `FlightCancelled`
+
+* `PaymentReceived`
+
+* Domain Events SHOULD be raised by the domain model when the corresponding business state transition occurs.
+
+* The domain model is responsible for representing and collecting domain events.
+
+* Publishing, transporting, persisting, retrying, or delivering events to external systems is outside the responsibility of the domain model.
+
+* Domain event dispatch mechanisms MUST NOT change the business meaning of the event.
+
+---
+
+## 10. Domain Services
+
+A Domain Service SHOULD be used only when:
+
+* The behavior is genuinely part of the domain.
+* The behavior does not naturally belong to a single Entity, Value Object, or Aggregate.
+* The behavior represents a meaningful domain operation.
+* Moving the behavior into an Entity or Value Object would make the model less coherent.
+
+Domain Services:
+
+* MUST contain domain behavior rather than application orchestration.
+* MUST NOT become general-purpose utility classes.
+* MUST NOT contain infrastructure concerns.
+* MUST NOT be used merely to avoid placing behavior inside an appropriate Aggregate.
+* SHOULD remain stateless where practical.
+
+---
+
+## 11. Repositories
+
+* Repositories represent a domain-oriented means of obtaining and storing Aggregates.
+* A Repository abstraction SHOULD exist for Aggregate Roots when persistence access is required by the domain model.
+* Repository operations SHOULD be expressed using domain concepts and domain identifiers.
+* Repository abstractions MUST NOT expose persistence-specific implementation details.
+* A Repository MUST NOT be used to bypass Aggregate boundaries.
+* Repositories SHOULD return Aggregates rather than individual child entities when the child belongs to an Aggregate.
+* Query operations that do not require loading an Aggregate MAY use dedicated query/read-model mechanisms.
+
+---
+
+## 12. Domain Specifications
+
+A Specification represents a reusable business predicate or domain rule.
+
+* Specifications SHOULD be used when a business rule is meaningful, reusable, and independently composable.
+* Specifications MUST express domain concepts rather than persistence implementation details.
+* Specifications MAY be combined when the domain requires logical composition of business rules.
+* Specifications MUST NOT become a generic query abstraction for unrelated technical concerns.
+* Persistence-specific query specifications belong outside the domain model unless they directly represent a domain concept.
+
+---
+
+## 13. Domain Exceptions
+
+* Domain exceptions MAY be used when a domain operation violates a business rule or invariant.
+* Domain exceptions MUST describe domain failures rather than infrastructure failures.
+* Domain exceptions SHOULD contain stable, meaningful messages suitable for controlled translation at an application boundary.
+* Domain code MUST NOT create HTTP-specific exceptions.
+* Domain code MUST NOT expose database, persistence, framework, or transport errors as domain concepts.
+* Infrastructure failures MUST NOT be disguised as domain rule violations.
+
+Example:
+
+```java
+public class DomainException extends RuntimeException {
+
+    public DomainException(String message) {
+        super(message);
+    }
+}
+```
+
+---
+
+## 14. Encapsulation
+
+* Domain state MUST be protected from uncontrolled modification.
+* Public setters SHOULD NOT be used for business state changes.
+* State-changing operations SHOULD express business intent.
+
+Prefer:
+
+```java
+booking.confirm();
+```
+
+over:
+
+```java
+booking.setStatus(CONFIRMED);
+```
+
+* Domain methods SHOULD represent meaningful business actions.
+* Aggregates SHOULD expose only the information and operations required by their consumers.
+* Collections owned by Aggregates MUST NOT expose mutable internal collections directly.
+* Internal domain collections SHOULD be exposed through read-only views where required.
+
+---
+
+## 15. Rich Domain Model
+
+* Business decisions SHOULD live in the domain model.
+* Application services SHOULD orchestrate domain operations rather than reproduce domain rules.
+* Controllers, DTOs, repositories, and infrastructure components MUST NOT become the primary location for domain decisions.
+* Anemic domain models SHOULD be avoided when the domain contains meaningful business behavior.
+* Simple data-only domain objects MAY remain simple when no meaningful behavior or invariant belongs to them.
+* Domain behavior MUST be placed where the corresponding business responsibility naturally belongs.
+
+---
+
+## 16. Immutability
+
+* Value Objects MUST be immutable.
+* Domain Events SHOULD be immutable.
+* Domain identifiers SHOULD be immutable.
+* Mutable state in Entities and Aggregates MUST be changed only through controlled domain operations.
+* Domain objects SHOULD avoid exposing mutable collections or mutable internal objects.
+* Immutability MUST be preferred where it does not conflict with legitimate Aggregate lifecycle requirements.
+
+---
+
+## 17. Time and External State
+
+* Domain logic SHOULD avoid directly depending on system time when deterministic behavior and testing are important.
+* When the current time affects a business decision, the time source SHOULD be supplied through an appropriate abstraction or application boundary.
+* Domain logic SHOULD NOT directly access databases, HTTP services, message brokers, environment variables, or other external systems.
+* External information required for a domain decision SHOULD be supplied through an appropriate domain/application boundary.
+
+---
+
+## 18. Cross-Aggregate Interaction
+
+* Aggregates MUST remain independently consistent.
+* One Aggregate MUST NOT directly mutate another Aggregate.
+* Cross-Aggregate operations SHOULD be coordinated by an application-level operation or domain event where appropriate.
+* References between Aggregates SHOULD use identifiers rather than direct mutable object navigation.
+* A business process spanning multiple Aggregates MUST NOT assume that all Aggregates form one consistency boundary.
+* If immediate consistency across multiple Aggregates is required, the Aggregate boundaries SHOULD be reconsidered before introducing coordination logic.
+
+---
+
+## 19. Cross-Bounded-Context Interaction
+
+* A bounded context MUST NOT directly modify another bounded context's domain objects.
+* Each bounded context owns its own domain model.
+* Communication between bounded contexts MUST use explicit contracts.
+* Anti-Corruption Layers SHOULD be used when an external domain model must be translated into the local domain model.
+* Shared concepts MUST NOT be used merely to avoid defining appropriate context-specific models.
+* Domain models MUST NOT become coupled simply because two contexts happen to use similar terminology.
+
+---
+
+## 20. Domain Modeling Guidelines
+
+When introducing a new domain concept:
+
+1. Identify the business concept it represents.
+2. Determine whether it is an Entity, Value Object, Aggregate, Aggregate Root, Domain Event, or Domain Service.
+3. Identify the invariants that must always hold.
+4. Define the responsibility of the concept.
+5. Determine its lifecycle and ownership.
+6. Determine whether it belongs inside an existing Aggregate or requires a separate Aggregate.
+7. Identify the domain events produced by significant state transitions.
+8. Avoid introducing abstractions that do not represent a genuine domain concept.
+
+---
+
+## 21. Anti-Patterns
+
+The following patterns are forbidden or strongly discouraged:
+
+| Anti-pattern                                                  | Reason                                              |
+| ------------------------------------------------------------- | --------------------------------------------------- |
+| Anemic domain model when meaningful business behavior exists  | Moves business decisions away from the domain model |
+| Public setters for business state                             | Allows invalid state transitions                    |
+| Primitive obsession for important domain concepts             | Weakens domain semantics and type safety            |
+| Cross-Aggregate direct mutation                               | Breaks Aggregate boundaries                         |
+| Treating an entire bounded context as one Aggregate           | Creates excessive coupling and consistency scope    |
+| Using Value Objects as mutable DTOs                           | Violates Value Object semantics                     |
+| Using Entities as generic data containers                     | Weakens domain behavior and encapsulation           |
+| Generic utility classes containing domain rules               | Hides domain responsibilities                       |
+| Infrastructure logic inside domain concepts                   | Couples the domain to external concerns             |
+| Domain logic inside controllers                               | Makes business behavior dependent on transport      |
+| Domain logic inside persistence implementations               | Couples business behavior to storage                |
+| Using Domain Events as generic integration messages           | Blurs domain and integration responsibilities       |
+| Creating abstractions without domain meaning                  | Adds unnecessary complexity                         |
+| Direct cross-bounded-context domain object sharing            | Couples independent models                          |
+| Using repositories to manipulate child entities independently | Bypasses Aggregate boundaries                       |
+
+---
+
+## 22. DDD Quality Criteria
+
+A domain model SHOULD satisfy the following criteria:
+
+* [ ] Ubiquitous language is clear and consistent.
+* [ ] Bounded-context boundaries are explicit.
+* [ ] Aggregate boundaries are based on business consistency requirements.
+* [ ] Every Aggregate has a clear Aggregate Root.
+* [ ] Aggregate invariants are enforced by the domain model.
+* [ ] Entities use identity-based semantics.
+* [ ] Value Objects use value-based semantics.
+* [ ] Value Objects are immutable.
+* [ ] Domain Events represent meaningful business occurrences.
+* [ ] Domain Services are used only where domain behavior does not naturally belong elsewhere.
+* [ ] Repository abstractions operate around Aggregate boundaries.
+* [ ] Cross-Aggregate mutation is avoided.
+* [ ] Cross-bounded-context coupling is minimized.
+* [ ] Domain state is properly encapsulated.
+* [ ] Infrastructure concerns are not represented as domain concepts.
+* [ ] No unnecessary domain abstractions have been introduced.
+
+---
+
+## 23. Scope
+
+This document defines **generic DDD tactical modeling standards only**.
+
+It does not define:
+
+* Project folder or package structure.
+* Hexagonal or Clean Architecture layer structure.
+* Spring Boot configuration.
+* JPA entity mapping strategy.
+* Database schema or migration strategy.
+* REST/API design.
+* Security configuration.
+* Dependency management.
+* Testing framework configuration.
+* Infrastructure adapter implementation.
+
+Those concerns MUST be defined in their respective technology, architecture, API, security, persistence, or project-specific standards.
+
+```
+
+### Important change
+
+I deliberately removed the old sections that prescribed things such as:
+
+- `domain / application / infrastructure / api` package structure
+- Hexagonal dependency diagrams
+- `@EntityScan`
+- `@EnableJpaAuditing`
+- `@SQLRestriction`
+- `@Transactional`
+- `JpaRepository`
+- `ApplicationEventPublisher`
+- JPA `AttributeConverter`
+- Spring `@Service`, `@Repository`, `@RestControllerAdvice`
+- `spring.jpa.open-in-view`
+- `ddl-auto`
+- infrastructure implementation examples
+
+Those belong in the **architecture/technology-specific guardrails**, not in the generic DDD standard.
+
+This version should therefore work much better with your separation of **architecture rules vs. DDD rules vs. Java coding rules**.
+```