aw-spec-cli 0.1.10 → 0.1.11

package/assets/guardrails/technology/java-spring/persistence.md

@@ -0,0 +1,316 @@
+# Persistence Standards
+
+> Java/Spring persistence standards using Spring Data JPA, Hibernate, and PostgreSQL.
+
+> This document defines generic persistence behavior and practices. Architecture, module boundaries, folder structure, and domain-modeling rules are governed by their respective standards.
+
+---
+
+## 1. JPA / Hibernate Conventions
+
+- JPA entity mapping MUST use standard Jakarta Persistence annotations such as `@Entity`, `@Table`, `@Column`, `@Id`, and `@Version` where applicable.
+
+- Persistence mappings MUST accurately represent the database schema and MUST NOT rely on implicit behavior that can cause schema ambiguity.
+
+- Java time types SHOULD be preferred over legacy date/time APIs.
+
+- Time-based database columns MUST use a timezone-safe representation appropriate for the selected database. For PostgreSQL, `TIMESTAMP WITH TIME ZONE` (`timestamptz`) SHOULD be used for timestamps representing an absolute point in time.
+
+- JPA/Hibernate-specific annotations MUST be used only where they provide a clear persistence concern.
+
+- Persistence configuration MUST NOT introduce business behavior that belongs in the domain model.
+
+---
+
+## 2. Repository and Data Access Rules
+
+- Repository abstractions MUST expose only the persistence operations required by the application.
+
+- Spring Data repositories SHOULD be preferred over unnecessary custom persistence infrastructure.
+
+- Complex or reusable query logic SHOULD use Spring Data JPA `Specification` where appropriate.
+
+- Direct `EntityManager` usage SHOULD be limited to persistence operations that cannot be expressed cleanly through the repository abstraction.
+
+- Persistence queries MUST NOT contain business rules that belong in the domain model.
+
+- Repository methods SHOULD remain focused and avoid becoming general-purpose data-access objects.
+
+- Queries MUST retrieve only the data required by the operation where practical.
+
+- N+1 query patterns MUST be avoided.
+
+---
+
+## 3. Specification and Query Rules
+
+- Spring Data JPA `Specification` MAY be used for dynamic and composable query predicates. :contentReference[oaicite:0]{index=0}
+
+- Specifications SHOULD be used when multiple optional criteria need to be combined dynamically.
+
+- Specifications SHOULD remain focused on persistence/query criteria rather than business decisions.
+
+- Specifications SHOULD be composable using operations such as `.and()` and `.or()`.
+
+- Paging and sorting SHOULD use Spring Data's `Pageable` and `Sort` mechanisms where applicable.
+
+- Queries MUST avoid unnecessary joins, eager loading, and unbounded result sets.
+
+- Native SQL MAY be used when required for database-specific functionality or when it provides a significant persistence benefit that cannot be expressed appropriately through JPA.
+
+- Native queries MUST remain maintainable and MUST NOT bypass required business invariants.
+
+---
+
+## 4. Entity Lifecycle and State
+
+- JPA entities MUST provide the constructors required by the persistence provider.
+
+- Entity state changes MUST be persisted through the normal JPA transaction lifecycle.
+
+- Persistence entities MUST NOT expose unnecessary mutable state solely for persistence convenience.
+
+- Lazy loading SHOULD be preferred for relationships unless eager loading is explicitly justified.
+
+- `FetchType.EAGER` MUST NOT be used by default for relationships.
+
+- Collection relationships SHOULD be configured deliberately to avoid accidental large object graphs.
+
+- Cascade operations MUST be explicitly selected based on the lifecycle relationship between persisted objects.
+
+- `orphanRemoval = true` MUST only be used when the child lifecycle is fully owned by the parent persistence relationship.
+
+---
+
+## 5. Concurrency Handling
+
+- Optimistic locking SHOULD be used where concurrent updates can cause lost-update problems.
+
+- JPA optimistic locking SHOULD use `@Version` on an appropriate numeric or supported version field.
+
+- The persistence provider MUST manage the version value rather than application code manually incrementing it.
+
+- Applications MUST handle optimistic locking failures according to the application's error-handling policy.
+
+- Pessimistic locking MAY be used when optimistic locking is insufficient and the concurrency requirement justifies it.
+
+- Locking strategies MUST be selected based on the actual consistency requirement rather than applied indiscriminately. Spring Data JPA supports explicit lock modes through `@Lock`. :contentReference[oaicite:1]{index=1}
+
+---
+
+## 6. Soft Delete
+
+- Soft delete MAY be used when records must remain physically stored while being excluded from normal application queries.
+
+- A soft-delete implementation SHOULD use an explicit deletion-state field such as `deletedAt` or an equivalent representation.
+
+- Soft-delete filtering MUST be applied consistently to normal queries.
+
+- Hard deletion MUST NOT be used where retention, regulatory, or business requirements require logical deletion.
+
+- Administrative or reporting access to soft-deleted data MUST use an explicitly defined persistence mechanism.
+
+- Soft-delete behavior MUST NOT accidentally apply to entities that are not intended to be soft-deletable.
+
+- Database-level retention and physical deletion policies are separate concerns and MUST be handled explicitly.
+
+---
+
+## 7. Auditing
+
+- Persistence auditing MAY be implemented using Spring Data JPA auditing facilities.
+
+- Creation and modification timestamps SHOULD use appropriate Java time types.
+
+- Creator and modifier information MAY be captured where required by the application.
+
+- Audit fields SHOULD be populated automatically through the configured persistence auditing mechanism rather than duplicated across application code. Spring Data JPA provides auditing support for creation/modification metadata. :contentReference[oaicite:2]{index=2}
+
+- Audit metadata MUST NOT be modified manually unless the application's requirements explicitly require such behavior.
+
+- Auditing configuration MUST remain separate from business-domain rules.
+
+---
+
+## 8. Transaction and Persistence Context Rules
+
+- Database modifications MUST execute within an appropriate transaction boundary.
+
+- Transactions SHOULD be kept as short as practical.
+
+- Long-running transactions MUST be avoided unless explicitly required.
+
+- Persistence entities SHOULD NOT be accessed after the persistence context is no longer available.
+
+- Lazy-loading behavior MUST be considered when designing transaction boundaries.
+
+- Open-session/open-entity-manager behavior MUST NOT be relied upon to hide incorrect transaction boundaries.
+
+- Read-only operations SHOULD use read-only transaction semantics where supported and appropriate.
+
+---
+
+## 9. Database and Schema Management
+
+- Database schema changes MUST be managed through the project's approved migration mechanism.
+
+- Flyway SHOULD be used when it is the project's approved migration tool.
+
+- Hibernate schema generation MUST NOT be used as the primary production schema-management mechanism.
+
+- In higher environments, Hibernate schema validation SHOULD be used instead of automatic schema mutation.
+
+- Schema migrations MUST be deterministic and repeatable across environments.
+
+- Migrations MUST be tested against a clean database.
+
+- Database constraints SHOULD be used where they provide meaningful data-integrity guarantees.
+
+- Indexes MUST be introduced based on actual query and constraint requirements.
+
+- Database naming conventions MUST remain consistent across the application.
+
+---
+
+## 10. PostgreSQL Standards
+
+- PostgreSQL SHOULD be the default relational database when PostgreSQL is the project's approved production provider.
+
+- PostgreSQL-specific features MAY be used when they provide a clear requirement or operational benefit.
+
+- Database-specific behavior MUST be documented when it prevents straightforward portability.
+
+- SQL types MUST be selected deliberately rather than relying on implicit database conversions.
+
+- UUIDs, timestamps, numeric values, JSON/JSONB, and other PostgreSQL-specific types MUST use mappings appropriate to their intended semantics.
+
+- Database queries SHOULD be validated against the PostgreSQL version used by the application.
+
+---
+
+## 11. Testing Persistence
+
+- Persistence behavior MUST be covered by integration tests where unit tests cannot adequately validate JPA/Hibernate behavior.
+
+- PostgreSQL integration tests SHOULD use Testcontainers or an equivalent real PostgreSQL environment.
+
+- H2 or other in-memory databases SHOULD NOT be used to validate PostgreSQL-specific persistence behavior.
+
+- Persistence tests SHOULD verify:
+
+  - Entity mappings
+  - Repository queries
+  - Constraints
+  - Transactions
+  - Optimistic locking where applicable
+  - Migration compatibility
+  - Soft-delete behavior where applicable
+
+- Database migrations MUST be tested against a fresh database during CI where schema changes are introduced.
+
+---
+
+## 12. Performance
+
+- Persistence performance MUST be considered for queries operating on potentially large datasets.
+
+- N+1 queries MUST be identified and eliminated where they affect application behavior or performance.
+
+- Unbounded queries MUST be avoided for potentially large datasets.
+
+- Pagination SHOULD be used for large result sets.
+
+- Fetch joins, entity graphs, projections, or other optimized retrieval strategies MAY be used where justified.
+
+- Database indexes SHOULD support frequently executed filtering, joining, ordering, and uniqueness requirements.
+
+- Persistence logging MUST NOT expose sensitive data.
+
+- Query optimization SHOULD be based on measured behavior rather than speculative optimization.
+
+---
+
+## 13. Mapping and Persistence Boundaries
+
+- Persistence entities MUST NOT be treated as generic API response objects.
+
+- Database-specific types SHOULD NOT leak into unrelated application contracts.
+
+- Persistence-specific annotations and configuration MUST remain associated with persistence concerns.
+
+- Conversion between persistence representations and application/domain representations MUST be explicit where the representations differ.
+
+- Attribute converters MAY be used for custom persistence mappings when they provide a clear and maintainable solution.
+
+- Reflection-heavy persistence mapping SHOULD be avoided unless required by the selected persistence framework.
+
+---
+
+## 14. Prohibited Persistence Practices
+
+The following practices are prohibited unless explicitly justified and approved:
+
+1. Automatic production schema mutation through Hibernate `ddl-auto=update` or equivalent.
+
+2. Unbounded queries against potentially large tables.
+
+3. Default use of `FetchType.EAGER` for relationships.
+
+4. N+1 query patterns that can reasonably be avoided.
+
+5. Manual manipulation of optimistic-lock version values.
+
+6. Persistence queries that implement business rules that belong elsewhere.
+
+7. Hard-coded database credentials or connection secrets.
+
+8. Database access outside the application's approved persistence mechanism.
+
+9. Use of H2 as proof of PostgreSQL-specific production behavior.
+
+10. Unnecessary native SQL when an appropriate JPA/Spring Data solution is available.
+
+11. Persistence configuration that silently changes business behavior.
+
+12. Unnecessary custom persistence frameworks or abstractions.
+
+---
+
+## 15. Quality Gates
+
+- Persistence tests MUST pass.
+
+- Database migrations MUST apply successfully to a fresh database.
+
+- Hibernate/JPA validation MUST pass where schema validation is configured.
+
+- Repository and query tests MUST pass for changed persistence behavior.
+
+- Optimistic-locking behavior MUST be tested where concurrency control is required.
+
+- PostgreSQL compatibility MUST be verified for PostgreSQL-specific queries or features.
+
+- No hard-coded database credentials or secrets may be present.
+
+- Persistence changes SHOULD be reviewed for query performance and migration impact.
+
+---
+
+## 16. Implementation Boundary
+
+This rule defines generic Java/Spring persistence behavior.
+
+The following remain implementation decisions unless explicitly required elsewhere:
+
+- Exact entity class names
+- Exact repository class names
+- Exact package structure
+- Exact database table names
+- Exact migration filenames
+- Exact Hibernate configuration
+- Exact connection-pool configuration
+- Exact indexing strategy
+- Exact query implementation
+- Exact Testcontainers configuration
+
+Persistence implementation MUST follow the applicable project architecture, DDD, security, API, and domain-specific standards without duplicating those standards here.

package/assets/guardrails/technology/java-spring/problem_details.md

@@ -0,0 +1,98 @@
+# Problem Details Component Architectural Specification (Rule)
+
+## 1. Purpose
+
+The purpose of the Problem Details component is to standardize the HTTP error representation returned by the Project Management application.
+
+It provides a boundary between application-level error information and HTTP-specific error representation, converting application errors and exceptions into a standardized HTTP error response.
+
+The Domain and Application layers MUST NOT depend on HTTP-specific Problem Details types.
+
+---
+
+## 2. Component Responsibilities
+
+The component MUST provide reusable implementation for:
+
+- Mapping application-level error representations to Problem Details.
+- Mapping appropriate exceptions to Problem Details.
+- Representing multiple errors where supported.
+- Representing validation errors.
+- Providing configurable diagnostic metadata.
+- Providing configurable stack-trace exposure.
+- Providing standardized default title/status behavior.
+- Providing externalized configuration.
+- Protecting sensitive information from HTTP error responses.
+- Consuming existing tracing/correlation context when available.
+
+The component MUST NOT own:
+
+- Business rules or Domain error semantics.
+- Validation execution.
+- Result Mapping logic.
+- Exception generation.
+- Logging, Metrics, or Distributed tracing.
+- Authentication/authorization decisions.
+- Business audit logging.
+
+---
+
+## 3. Standard Problem Details Representation
+
+The component MUST use the application's approved standard Problem Details representation, which SHOULD align with the established Java/Spring HTTP Problem Details mechanism.
+
+The representation SHOULD support the standard Problem Details fields, as applicable:
+
+- `type`
+- `title`
+- `status`
+- `detail`
+- `instance`
+
+Application-specific diagnostic information MAY be represented through extensions when justified, such as:
+
+- trace ID
+- correlation ID
+- error ID
+- tenant ID
+- validation errors
+- other approved diagnostic metadata
+
+The component MUST NOT make every possible extension mandatory or invent unnecessary mandatory fields.
+
+---
+
+## 4. Error and Exception Mapping
+
+The component MUST support mapping appropriate application-level error representations and exceptions into standardized Problem Details responses.
+
+It MUST distinguish between information useful for internal diagnostics and information safe to expose to API consumers.
+
+Exception messages MUST NOT automatically be assumed to be safe for external exposure.
+
+The component MUST NOT expose internal implementation details or sensitive exception information unintentionally.
+
+Stack traces MUST be configurable and MUST NOT be exposed in production by default.
+
+The component MUST NOT generate business exceptions.
+
+---
+
+## 5. Validation Integration
+
+Problem Details MUST support the representation of validation failures, but it MUST NOT perform validation itself.
+
+Validation remains a separate cross-cutting concern.
+
+The Problem Details component MAY consume validation errors and represent them in the standardized HTTP response.
+
+The responsibility boundary MUST remain:
+
+```text
+Validation
+    ↓
+Validation error
+    ↓
+Problem Details
+    ↓
+Standardized HTTP error response

package/assets/guardrails/technology/java-spring/result_mapping.md

@@ -0,0 +1,48 @@
+# Result Mapping Component Architectural Specification (Rule)
+
+## 1. Purpose
+
+The purpose of the Result Mapping component is to provide a standardized mechanism for converting application-level Result objects into HTTP responses.
+
+The component MUST keep application Result semantics separate from HTTP response construction.
+
+---
+
+## 2. Component Responsibilities
+
+The component MUST provide reusable behavior for:
+
+- Mapping generic application Results containing a value to HTTP responses.
+- Mapping non-generic application Results to HTTP responses.
+- Determining the HTTP response outcome based on the Result's established success/failure state.
+- Returning the contained value for successful generic Results.
+- Returning a successful response without a body for successful non-generic Results.
+- Delegating failed Results to the Problem Details component.
+- Providing a Result Mapper contract and concrete implementation where the reusable mapping capability requires an explicit contract.
+- Providing framework/dependency-injection registration for the mapper.
+- Providing exception-to-Result conversion where this behavior is part of the application's established Result model.
+
+The component MUST NOT own:
+
+- Business rules or Domain error semantics.
+- Problem Details construction or HTTP error representation.
+- Validation, Logging, Metrics, or Distributed tracing.
+- Authentication or authorization decisions.
+- Business audit logging.
+
+---
+
+## 3. Result Mapping Behavior
+
+The mapper MUST evaluate the established success/failure state of the Result.
+
+### 3.1 Successful Generic Result
+
+When a generic Result represents success, the contained Result value MUST become the HTTP response body.
+
+```text
+Result<T>
+    ↓
+HTTP Success Response
+    ↓
+Result value as response body

package/assets/guardrails/technology/java-spring/technology-constitution.md

@@ -0,0 +1,168 @@
+# Technology Constitution — java-spring (domain-agnostic base)
+
+> The technology-only governance base for this stack corpus. It heads the set mapped under
+> `## /aw-spec-constitution` in a project's `tech-rule-bindings.md` — this file, then the
+> standard technical rules beside it, then the project team's `technical-requirements.md` —
+> which `/aw-spec-orch constitution` ratifies into `.aw-spec/memory/constitution.technical.md`.
+
+This file is domain-agnostic on purpose: the constitution command loads it *before* the domain
+is selected, and that ordering is what keeps the technical half free of domain material. The
+project's three constitutional SETS are siblings, never merged here — each is headed by
+its own base file:
+
+| Source | Ratified into | Principle series |
+|---|---|---|
+| `technology-constitution.md` (this file) | `constitution.technical.md` | I–XV |
+| `domain-constitution.md` | `constitution.domain.md` | XVI+ |
+| the lane corpus's `ui-constitution.md` | `constitution.ui.md` | UX-* |
+
+- Core Principles **I–XV** below are domain-agnostic and reused across every project that maps this corpus.
+- **PROJECT IDENTITY**, **REGULATORY REGIME**, domain principles (**XVI+**), domain folder
+  additions and governance-override values are **not** filled here — they come from
+  `domain-constitution.md`.
+- **Experience principles (UX-\*)** are not filled here — they come from the lane corpus's
+  `ui-constitution.md`.
+
+This content is the supreme engineering authority for the service lane: where any other
+engineering guidance in the repository disagrees, this document wins. It stays slim and
+authoritative — the detailed rules live in the technical rule files each principle cites.
+
+## Runtime Style
+
+A Modular Monolith built to evolve into independent services. It uses Hexagonal
+Architecture (Ports and Adapters), Domain-Driven Design, CQRS where appropriate,
+and Specification-Driven Development in a Spring Boot environment. Each module
+owns its domain model, application use cases, ports, and adapters. Cross-cutting
+concerns are provided through the appropriate infrastructure capabilities; business
+logic lives inside aggregates and application use cases within their owning module.
+
+## Core Principles (domain-agnostic)
+
+> Essence only — the full rules live in the cited rule file.
+
+### I — Modular Monolith (NON-NEGOTIABLE)
+Single deployable Spring Boot service partitioned into logical modules; each module = Domain/Features/Persistence/Shared; no cross-module Domain coupling; no horizontal service layers across boundaries.
+→ `guardrails/technology/java-spring/modular-monolith.md`
+
+### II — Hexagonal Architecture Dependency Rule (NON-NEGOTIABLE)
+Dependencies flow inward toward the Domain and Application core. Inbound Adapters
+depend on Inbound Ports/Application use cases, while Outbound Ports are implemented
+by Infrastructure Adapters. Domain and Application code MUST NOT depend on Infrastructure,
+HTTP, or framework-specific concerns. Endpoints call application use cases/ports,
+never repositories or persistence adapters directly.
+→ `guardrails/technology/java-spring/clean-architecture.md`
+
+### III — Domain-Driven Design with Rich Aggregates (NON-NEGOTIABLE)
+Access entities through aggregate roots; strongly-typed IDs; sealed validating value objects; immutable domain events; invariants enforced in the aggregate; transaction boundary = aggregate boundary.
+→ `guardrails/technology/java-spring/domain-driven-design.md`, `guardrails/technology/java-spring/domain_abstraction.md`
+
+### IV — Standardized Result Mapping (NON-NEGOTIABLE)
+All application logic returns standard result types rather than throwing business exceptions for control flow; errors are returned as explicit failures and mapped to HTTP responses.
+→ `guardrails/technology/java-spring/result_mapping.md`
+
+### V — Specification-Driven Persistence (NON-NEGOTIABLE)
+Data access logic and query composition live in Domain Specifications; no ad-hoc SQL or JPQL in handlers; no cross-aggregate JPA navigation joins; reference parents by strongly-typed ID.
+→ `guardrails/technology/java-spring/persistence.md`
+
+### VI — Immutable Contracts at the Edge
+Shared DTOs mapped explicitly; no automatic reflection mappers (e.g. strict mapping rules); DTOs are immutable; external projections stay parallel.
+→ `guardrails/technology/java-spring/clean-architecture.md`
+
+### VII — Standardized Global Exception Handling (NON-NEGOTIABLE)
+System-level and unhandled exceptions are caught centrally and formatted according to RFC 7807 Problem Details; standard error payload structure across all APIs.
+→ `guardrails/technology/java-spring/problem_details.md`, `guardrails/technology/java-spring/global_exception_handler.md`
+
+### VIII — Multi-Tenant & Robust Persistence
+Provider-aware persistence with PostgreSQL; transactional integrity via Spring `@Transactional` bounded to application services; cross-cutting soft-delete/audit behaviors; hard delete forbidden for retention-protected data.
+→ `guardrails/technology/java-spring/persistence.md`
+
+### IX — Security by Default & Zero Trust (NON-NEGOTIABLE)
+Explicit role-based and scope-based authorization via Spring Security; external IdP only; zero trust networks; sensitive data encrypted in transit and at rest; strict TLS and CORS policies.
+→ `guardrails/technology/java-spring/zero-trust.md`, `guardrails/technology/java-spring/authorization.md`
+
+### X — Observability is a First-Class Citizen (NON-NEGOTIABLE)
+Structured logging using SLF4J with an approved logging backend; never log secrets
+or sensitive data; available trace, span, and correlation context is included in
+logs through the established context-propagation mechanism. Logging MUST remain
+separate from distributed tracing, metrics, and business audit logging.
+→ `guardrails/technology/java-spring/logging.md`
+
+### XI — Cloud-Native Orchestration via Spring Boot
+Spring Boot acts as the composition root; backing services are referenced via externalized configuration (12-Factor App); no hard-coded connection strings/ports.
+
+### XII — REST API Standards
+Internal REST (Spring MVC `@RestController`, kebab routes); standard paging; versioned breaking changes via explicit API versioning policies; machine-readable contracts (OpenAPI).
+→ `guardrails/technology/java-spring/api-versioning.md`
+
+### XIII — Test-First Engineering
+Tests for every aggregate behavior/value object/specification/handler/endpoint; deterministic testing; contract changes ship with test updates in the same commit.
+→ `guardrails/technology/java-spring/testing.md`
+
+### XIV — Data Integration Layer / Single Source of Truth (NON-NEGOTIABLE)
+Authoritative system of record; consumers use the REST API / published projections / Domain Events only; no direct DB access from external services; inbound feeds flow through Interop adapters.
+→ `guardrails/technology/java-spring/api-versioning.md`
+
+### XV — Evolutionary Path to Microservices
+Modules own their aggregates, application services, ports, adapters, persistence,
+and DTOs. Cross-module communication occurs through application service interfaces
+or application/domain events. Modules MUST NOT access another module's repositories
+or domain internals. Per-module schemas are recommended to support future extraction;
+service extraction requires an approved architectural amendment.
+→ `guardrails/technology/java-spring/modular-monolith.md`
+
+> **Domain principles (XVI and beyond) are supplied by `domain-constitution.md`.**
+> **Experience principles (UX-\*) are supplied by the lane corpus's `ui-constitution.md`.**
+
+## Mandatory Folder Structure
+
+Governed by the technical rule files; this file does not duplicate the tree.
+
+- Technology layout (src/tests/helm/docs, module = Domain/Features/Persistence/Shared):
+  `guardrails/technology/java-spring/folder-structure.md`
+- Domain-specific additions (Interop adapters, domain test fixtures, regulatory controls):
+  supplied by `domain-constitution.md` + the active domain corpus's `folder-structure.domain.md`
+- The frontend lane's layout lives entirely under its own root and is supplied by that lane's
+  own corpus, `guardrails/technology/nextjs/ui-constitution.md`. Nothing here applies to it.
+
+Project names use the `<SampleProjectName>` placeholder. Cross-cutting files (e.g. `pom.xml` / `build.gradle`, application properties) MUST stay at the same level they occupy in the standard template.
+
+## Conventions, Forbidden Patterns, AI Rules, Quality Gates
+
+Governed in full by the technical rule files; this file does not duplicate them.
+
+- Naming & coding conventions, the Forbidden Patterns, and the CI Quality Gates:
+  `guardrails/technology/java-spring/coding-standards.md`
+- Package governance (approved/banned packages, supply-chain, licensing):
+  `guardrails/technology/java-spring/dependency-policy.md`
+- AI operational rules (generation, context loading, refusal conditions):
+  `guardrails/technology/java-spring/ai-rules.md` — the domain half extends this with domain-specific masking,
+  code-set and refusal rules
+
+## Governance
+
+- This constitution supersedes all other engineering documentation in the repository. Where they
+  disagree, this document wins; a rule file that contradicts a principle here is the file that
+  gets corrected.
+- Amendments are proposed via pull request that modifies this file (and the affected rule
+  files), includes a migration plan for non-compliant code, bumps the version per the policy
+  below, and is approved per the roles named in `domain-constitution.md`'s Governance Overrides
+  (at minimum one Principal Engineer + the domain's mandatory approver).
+- Versioning follows SemVer applied to governance:
+  - **MAJOR** — removal or weakening of a NON-NEGOTIABLE principle, or a backward-incompatible
+    change to the Mandatory Folder Structure.
+  - **MINOR** — addition of a new principle, new mandatory section, or new bounded context.
+  - **PATCH** — clarifications, wording fixes, non-semantic edits.
+- This file versions independently of `domain-constitution.md` and `ui-constitution.md`.
+- Compliance review happens on every PR. Reviewers MUST cite the principle number when
+  requesting changes.
+- A quarterly architecture and security review MUST audit a random sample of modules against
+  this constitution and file remediation tickets for any deviation.
+- Runtime guidance files MUST carry a single pointer to the ratified constitution and MUST NOT
+  duplicate or paraphrase its rules.
+- Domain-specific governance overrides (approver roles, regulatory review triggers, control
+  mappings) are supplied by `domain-constitution.md`.
+
+## Ratification Metadata
+
+> Carried into `constitution.technical.md` at ratification; the constitution command owns the
+> version bump from there.