CLAUDE.md@examples/multimodule · git:20260920.e596793 · 2026-09-20 · sha256 440feee48f49e143
CLAUDE.md@examples/multimodule git:20260920.e596793A
Immutable. This exact content never changes and is served at /api/v1/blob/440feee48f49e143.
# CLAUDE.md
Hand-authored notes for this example live outside the markers and must survive regeneration.
The section between the VIBETAGS markers below is generated by the annotation processor from
the annotations in `core/`, `engine/`, and `cli/` — build with `mvn clean verify` to populate
or refresh it.
<!-- VIBETAGS-START -->
<!-- VIBETAGS-MODULE: cli -->
<!-- # Generated by VibeTags | https://github.com/PIsberg/vibetags -->
<project_guardrails>
<locked_files>
</locked_files>
<contextual_instructions>
</contextual_instructions>
<audit_requirements>
<file path="com.example.multimodule.cli.MultiModuleCli">
<vulnerability_check>Path Traversal</vulnerability_check>
</file>
</audit_requirements>
<rule>
If you are asked to modify any file listed in <audit_requirements>, you must first silently analyze your proposed code for the listed <vulnerability_check> items. If your code introduces these vulnerabilities, you must rewrite it before displaying it to the user.
</rule>
<contract_signatures>
<element path="com.example.multimodule.cli.MultiModuleCli.run(java.lang.String[])">
<reason>Public CLI surface; flags are documented downstream</reason>
</element>
</contract_signatures>
<rule>You may refactor the internal logic of elements listed in <contract_signatures>, but you MUST NOT change their public signatures: method names, parameter types, parameter order, return types, or checked exceptions.</rule>
<test_driven_requirements>
<element path="com.example.multimodule.cli.MultiModuleCli">
<coverage_goal>100</coverage_goal>
<frameworks>JUNIT_5</frameworks>
<test_location>src/test/java/com/example/multimodule/cli</test_location>
</element>
</test_driven_requirements>
<rule>For any element listed in <test_driven_requirements>, you MUST provide both the implementation change AND the corresponding test code update in a single response. Changes without tests are incomplete and must not be proposed. Every name under <applies-to> in a <test_driven_default> block inherits that block's coverage goal, frameworks, and test-location convention (with {path} standing for the element's package path).</rule>
<idempotent_elements>
<element path="com.example.multimodule.cli.MultiModuleCli.outputPath(java.lang.String,java.lang.String)">
<idempotent>true</idempotent>
<reason>Derives output path from inputs only</reason>
</element>
</idempotent_elements>
<rule>Operations listed in <idempotent_elements> must remain idempotent. Never introduce side effects that cause repeated invocations to produce different results.</rule>
<pure_functions>
<file path="com.example.multimodule.cli.MultiModuleCli.outputPath(java.lang.String,java.lang.String)">
<policy>Pure function: no side effects, deterministic.</policy>
</file>
</pure_functions>
<rule>Methods in <pure_functions> must remain mathematically pure. Side effects, mutations of class/static state, or blocking operations are strictly forbidden.</rule>
</project_guardrails>
<rule>Never propose edits to files listed in <locked_files>.</rule>
## Inherited Guardrails (dependencies)
These come from packages this project depends on. They constrain how the dependency may be used; they are not editable from here.
- `com.example.multimodule.core` (from se.deversity.vibetags.example:multimodule-core:1.0)
- @AISecure: aspect=Node identity is a security boundary: never build an IrNode from unvalidated external input, and never expose its raw id in a URL or log line.
## Inherited Context (dependencies)
Conventions the dependency's authors documented. Follow them unless this project's own rules above say otherwise.
- `com.example.multimodule.core` (from se.deversity.vibetags.example:multimodule-core:1.0)
- @AIContext: avoids=Adding mutable state, framework annotations, or a dependency on any sibling module.; focus=Immutable IR data model shared across every module of the reactor.
- @AIThreadSafe: note=Every type in this package is safe to publish across threads without synchronization.; strategy=IMMUTABLE
<!-- VIBETAGS-MODULE-END: cli -->
<!-- VIBETAGS-MODULE: core -->
<!-- # Generated by VibeTags | https://github.com/PIsberg/vibetags -->
<project_guardrails>
<locked_files>
<file path="com.example.multimodule.core.IrNode">
<reason>Core IR node: structural changes break every downstream module</reason>
</file>
</locked_files>
<contextual_instructions>
<file path="com.example.multimodule.core">
<focus>Immutable IR data model shared across every module of the reactor.</focus>
<avoids>Adding mutable state, framework annotations, or a dependency on any sibling module.</avoids>
</file>
</contextual_instructions>
<thread_safe_elements>
<element path="com.example.multimodule.core">
<strategy>IMMUTABLE</strategy>
<note>Every type in this package is safe to publish across threads without synchronization.</note>
</element>
</thread_safe_elements>
<rule>Elements listed in <thread_safe_elements> are explicitly designed to be thread-safe via the named strategy. Any modification MUST preserve the synchronization invariant and document its reasoning in the change description.</rule>
<immutable_types>
<type path="com.example.multimodule.core.IrGraph">
</type>
</immutable_types>
<rule>Types listed in <immutable_types> are immutable by design. Never introduce non-final fields, setters, or methods that mutate instance state.</rule>
<security_elements>
<element path="com.example.multimodule.core">
<aspect>Node identity is a security boundary: never build an IrNode from unvalidated external input, and never expose its raw id in a URL or log line.</aspect>
</element>
</security_elements>
<rule>Elements listed in <security_elements> are security-critical. Never weaken their security properties. Every proposed change must be explicitly reviewed for security impact.</rule>
<domain_model_elements>
<file path="com.example.multimodule.core.IrNode">
<domain_model_boundary>Pure Domain Model</domain_model_boundary>
</file>
</domain_model_elements>
<rule>Classes in <domain_model_elements> are pure domain models. Do not import or reference database or web framework dependencies (Spring, Hibernate, JPA, Jackson).</rule>
</project_guardrails>
<rule>Never propose edits to files listed in <locked_files>.</rule>
<!-- # Generated by VibeTags | https://github.com/PIsberg/vibetags -->
<project_guardrails>
<locked_files>
<file path="com.example.multimodule.core.IrGraphFixturesTest">
<reason>The golden graphs below are the layout engine's recorded output for the 1.0 release. Regenerating them makes the suite agree with the current engine instead of with the release it is meant to protect.</reason>
</file>
</locked_files>
<contextual_instructions>
</contextual_instructions>
</project_guardrails>
<rule>Never propose edits to files listed in <locked_files>.</rule>
Guardrails for test code are in TESTING.md. Read it before modifying anything under a test source set.
<!-- VIBETAGS-MODULE-END: core -->
<!-- VIBETAGS-MODULE: engine -->
<!-- # Generated by VibeTags | https://github.com/PIsberg/vibetags -->
<project_guardrails>
<locked_files>
</locked_files>
<contextual_instructions>
</contextual_instructions>
<thread_safe_elements>
<element path="com.example.multimodule.engine.LayoutEngine">
<strategy>SYNCHRONIZED</strategy>
<note>Stateless; safe to share across render threads</note>
</element>
</thread_safe_elements>
<rule>Elements listed in <thread_safe_elements> are explicitly designed to be thread-safe via the named strategy. Any modification MUST preserve the synchronization invariant and document its reasoning in the change description.</rule>
<extensible_patterns>
<file path="com.example.multimodule.engine.LayoutEngine">
<extension_pattern>STRATEGY_PATTERN</extension_pattern>
</file>
</extensible_patterns>
<rule>Respect extensibility guidelines for elements in <extensible_patterns>. Implement strategy/visitor extensions rather than expanding branch conditional logic.</rule>
</project_guardrails>
<rule>Never propose edits to files listed in <locked_files>.</rule>
## Inherited Guardrails (dependencies)
These come from packages this project depends on. They constrain how the dependency may be used; they are not editable from here.
- `com.example.multimodule.core` (from se.deversity.vibetags.example:multimodule-core:1.0)
- @AISecure: aspect=Node identity is a security boundary: never build an IrNode from unvalidated external input, and never expose its raw id in a URL or log line.
## Inherited Context (dependencies)
Conventions the dependency's authors documented. Follow them unless this project's own rules above say otherwise.
- `com.example.multimodule.core` (from se.deversity.vibetags.example:multimodule-core:1.0)
- @AIContext: avoids=Adding mutable state, framework annotations, or a dependency on any sibling module.; focus=Immutable IR data model shared across every module of the reactor.
- @AIThreadSafe: note=Every type in this package is safe to publish across threads without synchronization.; strategy=IMMUTABLE
<!-- VIBETAGS-MODULE-END: engine -->
<!-- VIBETAGS-MODULE: showcase -->
<!-- # Generated by VibeTags | https://github.com/PIsberg/vibetags -->
<project_guardrails>
<locked_files>
<file path="com.example.payment.PaymentProcessor">
<reason>Tied to legacy database schema v2.3. Changes will break production payment processing. Contact the payments team before modifying.</reason>
</file>
<file path="com.example.security.SecurityConfig">
<reason>CRITICAL: Security configuration managed by DevOps team. Any changes require security review and approval ticket SEC-XXXX</reason>
</file>
<file path="com.example.security.SecurityConfig.getEncryptionAlgorithm()">
<reason>Encryption algorithm tied to compliance requirements (PCI-DSS)</reason>
</file>
<file path="com.example.security.SecurityConfig.getKeyRotationHours()">
<reason>Key rotation period mandated by company policy</reason>
</file>
<file path="com.example.security.SecurityConfig.getMaxLoginAttempts()">
<reason>Max login attempts set by security team to prevent brute force</reason>
</file>
<file path="com.example.security.SecurityConfig.validateToken(java.lang.String)">
<reason>Token validation must match auth server exactly. Changes will break all client authentication</reason>
</file>
<file path="com.example.service.OrderService.calculateTax(java.lang.String,double)">
<reason>Tax calculation uses Avalara API integration. Credentials and endpoint configuration managed by finance team.</reason>
</file>
<file path="com.example.service.OrderService.processPayment(java.lang.String,double)">
<reason>Payment processing uses Stripe API v2024.10. Changes require PCI compliance review.</reason>
</file>
<file path="com.example.service.OrderService.validateOrder(java.util.Map<java.lang.String,java.lang.Object>)">
<reason>Order validation implements 47 business rules. Last changed in Q2 2024 after 3-month testing cycle. DO NOT MODIFY without running full test suite.</reason>
</file>
</locked_files>
<contextual_instructions>
<file path="com.example.security.SecurityConfig">
<focus>This class is READ-ONLY for AI assistants. Do not suggest modifications.</focus>
<avoids>Any changes to encryption algorithms, key sizes, or validation logic</avoids>
</file>
<file path="com.example.service.InventoryService">
<focus>Maintain inventory consistency across concurrent requests. All stock updates must be atomic.</focus>
<avoids>Non-atomic read-modify-write sequences, unsynchronized shared state</avoids>
</file>
<file path="com.example.service.NotificationService">
<focus>Implement notification delivery with retry logic and error handling</focus>
<avoids>Hard-coded credentials, synchronous blocking calls</avoids>
</file>
<file path="com.example.service.OrderService">
<focus>Maintain transactional integrity. All database operations must use proper transaction management.</focus>
<avoids>Raw SQL queries, direct database connections without connection pooling</avoids>
</file>
<file path="com.example.service.PricingService">
<focus>Optimize pricing calculations for accuracy and throughput. Internal algorithms may use any efficient approach.</focus>
<avoids>Floating-point arithmetic for monetary values — use BigDecimal internally, but note that the contract-frozen signatures use double for backwards compatibility</avoids>
</file>
<file path="com.example.strategy.PaymentStrategy">
<focus>Follow the Strategy pattern strictly. Each payment method should be a separate strategy class implementing this interface.</focus>
<avoids>Monolithic if-else chains, hard-coded payment logic, single class handling all payment types</avoids>
</file>
<file path="com.example.utils.StringParser">
<focus>Optimize for memory usage over CPU speed. Minimize object allocations and avoid creating intermediate string objects.</focus>
<avoids>java.util.regex, String.split(), StringBuilder in loops</avoids>
</file>
</contextual_instructions>
<audit_requirements>
<file path="com.example.database.DatabaseConnector">
<vulnerability_check>SQL Injection</vulnerability_check>
<vulnerability_check>Thread Safety issues</vulnerability_check>
</file>
</audit_requirements>
<rule>
If you are asked to modify any file listed in <audit_requirements>, you must first silently analyze your proposed code for the listed <vulnerability_check> items. If your code introduces these vulnerabilities, you must rewrite it before displaying it to the user.
</rule>
<ignored_elements>
<file path="com.example.internal.GeneratedMetadata">
<reason>Auto-generated at build time. Manual edits are overwritten on every build.</reason>
</file>
</ignored_elements>
<rule>Never reference or suggest changes to any element listed in <ignored_elements>. Treat these as if they do not exist.</rule>
<implementation_tasks>
<task path="com.example.NotificationService">
<instructions>Implement email sending via SMTP and push notifications via FCM. Ensure retry logic and rate limiting are applied.</instructions>
</task>
<task path="com.example.payment.PaymentProcessor">
<instructions>Implement support for new crypto payments without breaking legacy flow.</instructions>
</task>
<task path="com.example.service.NotificationService.getDeliveryStatus(java.lang.String)">
<instructions>Implement delivery status tracking. Return status: PENDING, SENT, DELIVERED, FAILED. Include timestamp and error message if failed.</instructions>
</task>
<task path="com.example.service.NotificationService.queueNotification(java.lang.String,java.lang.String,java.lang.String,int)">
<instructions>Implement a notification queue using a BlockingQueue or similar structure. Support batch processing and priority levels (LOW, MEDIUM, HIGH, CRITICAL).</instructions>
</task>
<task path="com.example.service.NotificationService.sendEmail(java.lang.String,java.lang.String,java.lang.String)">
<instructions>Implement email sending using JavaMail API or similar. Include HTML template support and attachment handling. Add retry logic for transient failures (max 3 retries with exponential backoff).</instructions>
</task>
<task path="com.example.service.NotificationService.sendPushNotification(java.lang.String,java.lang.String,java.lang.String)">
<instructions>Implement push notification using Firebase Cloud Messaging. Support both Android and iOS. Include notification payload customization.</instructions>
</task>
<task path="com.example.service.NotificationService.sendSMS(java.lang.String,java.lang.String)">
<instructions>Implement SMS sending via Twilio or AWS SNS. Include phone number validation. Handle rate limiting (max 10 SMS per minute per user).</instructions>
</task>
<task path="com.example.service.OrderService.calculateDiscount(java.lang.String,java.lang.String)">
<instructions>Implement discount calculation supporting: percentage discounts, fixed amount discounts, buy-one-get-one-free, and tiered discounts based on cart value. Apply maximum one discount per order unless overridden by admin.</instructions>
</task>
<task path="com.example.service.OrderService.generateOrderConfirmation(java.lang.String)">
<instructions>Generate order confirmation email content including: order summary, itemized list, shipping address, estimated delivery date, and customer support contact information. Support HTML and plain text formats.</instructions>
</task>
<task path="com.example.service.OrderService.searchOrders(java.util.Map<java.lang.String,java.lang.String>,int,int)">
<instructions>Implement order search with filters: date range, status, customer ID, minimum/maximum amount. Support pagination (default 20 items per page). Return results sorted by creation date descending.</instructions>
</task>
<task path="com.example.service.OrderService.updateOrderStatus(java.lang.String,java.lang.String)">
<instructions>Implement order status workflow: CREATED -> PAYMENT_PENDING -> PAYMENT_CONFIRMED -> PROCESSING -> SHIPPED -> DELIVERED. Support status history tracking with timestamps. Allow cancellation only before SHIPPED status.</instructions>
</task>
<task path="com.example.strategy.PaymentStrategy.executePayment(double)">
<instructions>Implement payment execution specific to the payment method (credit card, PayPal, cryptocurrency, etc.). Return transaction ID on success.</instructions>
</task>
<task path="com.example.strategy.PaymentStrategy.validatePaymentMethod()">
<instructions>Validate payment method specific data (card numbers, email addresses, wallet addresses, etc.). Return true if valid, false otherwise.</instructions>
</task>
<task path="com.example.strategy.impl.CreditCardStrategy.executePayment(double)">
<instructions>Implement credit card payment processing via Stripe or similar payment gateway. Include: card tokenization, 3D Secure authentication, and proper error handling for declined cards. Return transaction ID on success.</instructions>
</task>
<task path="com.example.strategy.impl.CreditCardStrategy.validatePaymentMethod()">
<instructions>Implement Luhn algorithm validation for card number, expiry date validation (must be future date), and CVV format check (3-4 digits). Return true only if all validations pass.</instructions>
</task>
</implementation_tasks>
<pii_guardrails>
<element path="com.example.database.DatabaseConnector.password">
<reason>Database credential - never log or include in error messages</reason>
</element>
<element path="com.example.database.DatabaseConnector.username">
<reason>Database credential - never log or include in error messages</reason>
</element>
<element path="com.example.service.InventoryService.customerId">
<reason>Customer identifiers linked to purchase history — PII under GDPR</reason>
</element>
<element path="com.example.service.NotificationService.sendEmail(java.lang.String,java.lang.String,java.lang.String)">
<reason>Email address is PII under GDPR - never log the recipient address</reason>
</element>
<element path="com.example.service.NotificationService.sendSMS(java.lang.String,java.lang.String)">
<reason>Phone number is PII - never log the destination number</reason>
</element>
<element path="com.example.service.OrderService.generateOrderConfirmation(java.lang.String)">
<reason>Output contains customer shipping address and contact details (PII)</reason>
</element>
<element path="com.example.strategy.impl.CreditCardStrategy.cardNumber">
<reason>PCI-DSS cardholder data - never log or expose in suggestions</reason>
</element>
<element path="com.example.strategy.impl.CreditCardStrategy.cvv">
<reason>PCI-DSS security code - never log or expose in suggestions</reason>
</element>
<element path="com.example.strategy.impl.CreditCardStrategy.expiryDate">
<reason>PCI-DSS cardholder data - never log or expose in suggestions</reason>
</element>
</pii_guardrails>
<rule>
Never include runtime values of elements listed in <pii_guardrails> in logs, console output, external API calls, test fixtures, mock data, or code suggestions. Treat their values as strictly confidential.
</rule>
<core_elements>
<element path="com.example.security.SecurityConfig">
<sensitivity>Critical</sensitivity>
<note>This is a security manager. Any single-line change can compromise the entire project.</note>
</element>
<element path="com.example.service.InventoryService.releaseReservation(java.lang.String)">
<sensitivity>High</sensitivity>
<note>Must be called as the exact inverse of reserveStock. Pair changes to both methods together.</note>
</element>
<element path="com.example.service.InventoryService.reserveStock(java.lang.String,int,java.lang.String)">
<sensitivity>Critical</sensitivity>
<note>Reservation logic handles concurrent requests via optimistic locking. Took 18 months to get right under high load — do not refactor without running the full concurrency test suite.</note>
</element>
</core_elements>
<rule>Elements listed in <core_elements> are well-tested core components. Make changes with extreme caution and verify comprehensive test coverage before proposing modifications.</rule>
<performance_constraints>
<element path="com.example.payment.PaymentProcessor">
<constraint>HFT-level requirements: O(1) processing time expected. No database lookups in processing loop.</constraint>
</element>
<element path="com.example.service.InventoryService.bulkRestock(java.util.List<java.util.Map<java.lang.String,java.lang.Object>>)">
<constraint>Must process 10 000 SKU updates/second. O(n) acceptable; O(n log n) only if unavoidable; O(n²) is forbidden.</constraint>
</element>
<element path="com.example.service.InventoryService.getAvailableStock(java.lang.String)">
<constraint>O(1) lookup required. Must complete in <2ms p99. No database calls permitted; reads from in-memory cache only.</constraint>
</element>
<element path="com.example.service.PricingService.calculatePrice(java.lang.String,int,java.lang.String)">
<constraint>Must complete in <5ms p99. Called on every cart update.</constraint>
</element>
</performance_constraints>
<rule>Elements listed in <performance_constraints> are on a hot path. Never introduce O(n²) or worse complexity. Always reason about time and space complexity before suggesting changes.</rule>
<contract_signatures>
<element path="com.example.service.PricingService.applyPromoCode(java.lang.String,double,java.lang.String)">
<reason>Promotions-service depends on this exact method signature for its async price-adjustment events. Changing parameter types would break the event deserialization.</reason>
</element>
<element path="com.example.service.PricingService.calculatePrice(java.lang.String,int,java.lang.String)">
<reason>Signature locked by OpenAPI v2 contract. checkout-service and mobile-app bind to this exact signature. A type change is a breaking API change.</reason>
</element>
<element path="com.example.service.PricingService.getBulkPricing(java.util.List<java.lang.String>,int)">
<reason>B2B portal contract v1.2 — the List<Map<String,Object>> structure is serialized directly to JSON. Changing the return type breaks portal parsing.</reason>
</element>
</contract_signatures>
<rule>You may refactor the internal logic of elements listed in <contract_signatures>, but you MUST NOT change their public signatures: method names, parameter types, parameter order, return types, or checked exceptions.</rule>
<test_driven_requirements>
<element path="com.example.service.OrderService.calculateDiscount(java.lang.String,java.lang.String)">
<coverage_goal>100</coverage_goal>
<frameworks>JUNIT_5, ASSERTJ</frameworks>
<mock_policy>Use fixed prices — no external pricing calls in unit tests</mock_policy>
</element>
<element path="com.example.service.OrderService.updateOrderStatus(java.lang.String,java.lang.String)">
<coverage_goal>95</coverage_goal>
<frameworks>JUNIT_5, MOCKITO</frameworks>
<test_location>src/test/java/com/example/service/OrderServiceTest.java</test_location>
<mock_policy>Mock OrderRepository and EventPublisher; use real state machine logic</mock_policy>
</element>
</test_driven_requirements>
<rule>For any element listed in <test_driven_requirements>, you MUST provide both the implementation change AND the corresponding test code update in a single response. Changes without tests are incomplete and must not be proposed. Every name under <applies-to> in a <test_driven_default> block inherits that block's coverage goal, frameworks, and test-location convention (with {path} standing for the element's package path).</rule>
<thread_safe_elements>
<element path="com.example.concurrent.SessionCache">
<strategy>LOCK_FREE</strategy>
<note>All mutations go through ConcurrentHashMap; never introduce a synchronized block on the cache map.</note>
</element>
</thread_safe_elements>
<rule>Elements listed in <thread_safe_elements> are explicitly designed to be thread-safe via the named strategy. Any modification MUST preserve the synchronization invariant and document its reasoning in the change description.</rule>
<immutable_types>
<type path="com.example.config.AsyncTestConfig">
<note>Used by every test runner; safe to share across threads without copies.</note>
</type>
</immutable_types>
<rule>Types listed in <immutable_types> are immutable by design. Never introduce non-final fields, setters, or methods that mutate instance state.</rule>
<deprecated_elements>
<element path="com.example.legacy.OldPaymentApi">
<replaced_by>com.example.payment.PaymentProcessor</replaced_by>
<migration_guide>Switch callers to PaymentProcessor.charge(). The new API uses Money instead of double.</migration_guide>
<deadline>v2.0 (2026-Q4)</deadline>
</element>
</deprecated_elements>
<rule>Elements listed in <deprecated_elements> are scheduled for removal. Do not extend them. When working with code that calls them, suggest migrating to the listed replacement.</rule>
<observability_instrumentation>
<element path="com.example.metrics.OrderMetrics.recordOrderPlaced(java.lang.String,boolean)">
<metric>orders.placed.total</metric>
<metric>orders.placed.failed</metric>
<trace>order.place</trace>
<log>OrderPlaced</log>
<log>OrderPlacementFailed</log>
<note>Watched by the Orders SLO dashboard (https://grafana.internal/d/orders-slo).</note>
</element>
</observability_instrumentation>
<rule>Elements listed in <observability_instrumentation> publish metrics, traces, or log statements that downstream dashboards and alerts depend on. Never remove or rename instrumentation without flagging the corresponding dashboard update.</rule>
<regulatory_elements>
<element path="com.example.compliance.GdprService">
<standard>GDPR</standard>
<clause>Art. 17</clause>
<description>Right to erasure — when invoked, deletes ALL PII for the given user across every connected store.</description>
</element>
<element path="com.example.compliance.GdprService.exportUserData(java.lang.String)">
<standard>GDPR</standard>
<clause>Art. 20</clause>
<description>Right to data portability — exports the user's data in a machine-readable format.</description>
</element>
</regulatory_elements>
<rule>Elements listed in <regulatory_elements> implement specific regulatory clauses. Any change MUST document its compliance impact and MUST NOT weaken the requirement.</rule>
<test_isolation_elements>
<element path="com.example.config.ParallelTestSettings">
<isolation>strict</isolation>
<reason>Tests here bind to fixed port 8080; a shared static counter caused flaky CI in build #4471 — keep cases isolated</reason>
</element>
</test_isolation_elements>
<rule>For elements in <test_isolation_elements>, all generated or modified tests MUST run in complete isolation (no shared state, external resource conflicts, or order dependencies).</rule>
<legacy_bridge_elements>
<element path="com.example.legacy.LegacyBridgeService">
<refactor>prohibited</refactor>
<reason>Mirrors a quirk in the upstream mainframe wire format (KEY=…;VAL=… with no escaping); 'modernizing' it broke the EBCDIC gateway in 2023</reason>
</element>
</legacy_bridge_elements>
<rule>Do not modernise, elegant-ize, or refactor structural patterns of elements in <legacy_bridge_elements>. Only modify internal business logic as explicitly requested.</rule>
<architecture_elements>
<element path="com.example.service.LayeredDomainService">
<belongs_to>domain</belongs_to>
<cannot_reference>infrastructure</cannot_reference>
<cannot_reference>ui</cannot_reference>
</element>
</architecture_elements>
<rule>Respect layered architectural constraints in <architecture_elements>. Boundary crossing references are strictly prohibited.</rule>
<public_api_elements>
<element path="com.example.service.PublicPaymentController">
<api>public</api>
<reason>Consumed by three external partner integrations pinned to v1; signature or return-shape changes are a breaking release and need a /v2 endpoint instead</reason>
</element>
</public_api_elements>
<rule>Elements in <public_api_elements> expose public API. Preserve public signature, Javadoc, and backwards compatibility without exceptions.</rule>
<strict_exceptions_elements>
<element path="com.example.service.TransactionalPaymentService">
<exceptions>strict</exceptions>
<reason>A bare catch(Exception) here once swallowed a TransactionRolledbackException and double-charged customers; only catch the specific types you handle</reason>
</element>
</strict_exceptions_elements>
<rule>Catching or throwing generic Exception/Throwable is strictly prohibited in <strict_exceptions_elements>. Precise or custom exceptions required.</rule>
<strict_types_elements>
<element path="com.example.payment.PaymentDetails">
<types>strict</types>
<reason>Currency math broke in INC-4412 when a double leaked into amount; keep money as BigDecimal and never widen these fields to Object/Map</reason>
</element>
</strict_types_elements>
<rule>Loose typing (Object, Map<String, Object>, raw types) is strictly prohibited in <strict_types_elements>. Enforce type safety.</rule>
<internationalized_elements>
<element path="com.example.utils.I18nMessageHelper">
<i18n>required</i18n>
<reason>Ships in 11 locales; a hardcoded English string here shipped to the German build last quarter and failed the l10n audit — always resolve via the bundle</reason>
</element>
</internationalized_elements>
<rule>Do not hardcode user-facing strings in <internationalized_elements>. Resolve all text via localization resource/message bundles.</rule>
<strict_classpath_elements>
<element path="com.example.utils.StrictUtility">
<classpath>strict</classpath>
<reason>Runs inside the locked-down payment sandbox where the SecurityManager forbids reflection and custom classloaders; dynamic loading throws at runtime</reason>
</element>
</strict_classpath_elements>
<rule>Dynamic class loading, custom classloaders, reflection hacks, or unverified external code are prohibited in <strict_classpath_elements>.</rule>
<schema_safe_elements>
<element path="com.example.database.UserEntity">
<schema>safe</schema>
<reason>Maps to the users table replicated to the billing read-model; renaming a column or changing a type needs a backward-compatible Flyway migration first</reason>
</element>
</schema_safe_elements>
<rule>Database or contract schema / serialization safety must be preserved in <schema_safe_elements>. Do not alter structures without migration paths.</rule>
<idempotent_elements>
<element path="com.example.compliance.GdprService.deleteAllUserData(java.lang.String)">
<idempotent>true</idempotent>
<reason>Deleting a user's data multiple times must produce the same result as deleting once — must not throw on second invocation.</reason>
</element>
</idempotent_elements>
<rule>Operations listed in <idempotent_elements> must remain idempotent. Never introduce side effects that cause repeated invocations to produce different results.</rule>
<feature_flag_elements>
<element path="com.example.service.InventoryService.sendLowStockAlert(java.lang.String,int)">
<flag>inventory.push-alerts.enabled</flag>
<default_value>false</default_value>
</element>
</feature_flag_elements>
<rule>Elements listed in <feature_flag_elements> are gated by a feature flag. Always preserve the flag check — never assume the flag is always active.</rule>
<security_elements>
<element path="com.example.security.SecurityConfig">
<aspect>authentication</aspect>
</element>
</security_elements>
<rule>Elements listed in <security_elements> are security-critical. Never weaken their security properties. Every proposed change must be explicitly reviewed for security impact.</rule>
<access_limitations>
<file path="com.example.service.NewAnnotationsShowcase.executeSecureDatabaseWipe()">
<allowed_callers>com.example.service.PricingService, com.example.payment.PaymentProcessor</allowed_callers>
</file>
</access_limitations>
<rule>Do not invoke elements in <access_limitations> from outside their specified allowed caller packages or classes.</rule>
<sandbox_only_elements>
<file path="com.example.service.NewAnnotationsShowcase.SandboxTestHelper">
<policy>Sandbox or test only. Do not invoke from production.</policy>
<reason>Spins up an in-memory mock DB and seeds fake credentials; a prod call path once imported this in a hotfix and leaked test data into staging</reason>
</file>
</sandbox_only_elements>
<rule>Elements in <sandbox_only_elements> belong exclusively to sandbox or test environments. Never import or invoke them in production code paths.</rule>
<memory_budget_elements>
<file path="com.example.service.NewAnnotationsShowcase.calculateFastFibonacci(int)">
<allocation_policy>ZERO_ALLOCATION</allocation_policy>
</file>
</memory_budget_elements>
<rule>Avoid runtime heap object allocations, autoboxing, or dynamic overhead within classes/methods in <memory_budget_elements>.</rule>
<pure_functions>
<file path="com.example.service.NewAnnotationsShowcase.calculateFastFibonacci(int)">
<policy>Pure function: no side effects, deterministic.</policy>
<reason>Memoized elsewhere on the assumption it is referentially transparent; adding logging or a cache mutation here would corrupt those callers</reason>
</file>
</pure_functions>
<rule>Methods in <pure_functions> must remain mathematically pure. Side effects, mutations of class/static state, or blocking operations are strictly forbidden.</rule>
<domain_model_elements>
<file path="com.example.service.NewAnnotationsShowcase.ImmutableProductPrice">
<domain_model_boundary>Pure Domain Model</domain_model_boundary>
<allowed_imports>java.math.BigDecimal</allowed_imports>
</file>
</domain_model_elements>
<rule>Classes in <domain_model_elements> are pure domain models. Do not import or reference database or web framework dependencies (Spring, Hibernate, JPA, Jackson).</rule>
<extensible_patterns>
<file path="com.example.service.NewAnnotationsShowcase.TaxCalculatorStrategy">
<extension_pattern>STRATEGY_PATTERN</extension_pattern>
</file>
</extensible_patterns>
<rule>Respect extensibility guidelines for elements in <extensible_patterns>. Implement strategy/visitor extensions rather than expanding branch conditional logic.</rule>
<sanitization_elements>
<file path="com.example.service.NewAnnotationsShowcase.executeDatabaseQuery(java.lang.String)#sqlRawInput">
<sanitization_types>SQL_INJECTION</sanitization_types>
</file>
</sanitization_elements>
<rule>Strict input sanitization is mandatory for elements in <sanitization_elements>. Raw input must pass through approved filters before hitting queries or renderers.</rule>
<secure_logging_elements>
<file path="com.example.service.NewAnnotationsShowcase.registerUserSession(java.lang.String,java.lang.String,java.lang.String)#creditCardNumber">
<logging_policy>MASK_CREDIT_CARD</logging_policy>
</file>
<file path="com.example.service.NewAnnotationsShowcase.registerUserSession(java.lang.String,java.lang.String,java.lang.String)#passwordRaw">
<logging_policy>HASH</logging_policy>
</file>
</secure_logging_elements>
<rule>Sensitive variables in <secure_logging_elements> must never be printed or logged in raw form. Enforce secure masking or hashing.</rule>
<explain_elements>
<file path="com.example.service.NewAnnotationsShowcase.runComplexMatrixMath(double[][],double[][])">
<explanation_required>HIGH</explanation_required>
</file>
</explain_elements>
<rule>Any modification to elements in <explain_elements> requires an explicit, structured Chain-of-Thought markdown description of changes and complexity analysis.</rule>
<prototype_elements>
<file path="com.example.service.NewAnnotationsShowcase.DraftKafkaIntegrationSpike">
<status>Experimental Prototype</status>
<reason>Throwaway spike for the Q3 Kafka evaluation — no error handling or back-pressure on purpose; do not let production services depend on it</reason>
</file>
</prototype_elements>
<rule>Classes in <prototype_elements> are experimental prototypes. Strict rules are relaxed locally, but production classes must never import or depend on them.</rule>
<sunset_elements>
<file path="com.example.service.NewAnnotationsShowcase.deprecatedLegacyCalculatePrice(double,double)">
<sunset_ticket>DEBT-742</sunset_ticket>
<replacement_target>com.example.service.PricingService</replacement_target>
</file>
</sunset_elements>
<rule>Do not introduce *new* references or calls to sunset elements in <sunset_elements>. Migrate callers to their modern replacements.</rule>
<temporary_workarounds>
<file path="com.example.service.NewAnnotationsShowcase.temporaryUpstreamBypass()">
<temporary_expiration>2028-12-31</temporary_expiration>
<temporary_reason>Hotfix workaround until upstream payment provider updates their API.</temporary_reason>
</file>
</temporary_workarounds>
<rule>Elements in <temporary_workarounds> are short-lived stubs or hotfixes that must be refactored or deleted before their designated expiration date.</rule>
<generated_elements>
<element path="com.example.service.EvidenceBasedShowcase">
<from>src/main/resources/openapi/checkout.yaml</from>
<edit-instead>src/main/resources/openapi/checkout.yaml</edit-instead>
<regenerate-with>mvn generate-sources</regenerate-with>
</element>
</generated_elements>
<rule>Elements in <generated_elements> are machine-generated: read them to understand behavior, but never edit them — changes are silently overwritten. Apply the change to the named source and regenerate instead.</rule>
<load_bearing_elements>
<element path="com.example.service.EvidenceBasedShowcase.settledOrderIds">
<invariant>Settled orders stay in the list until the reconciliation job drains it</invariant>
<breaks-if>Clearing eagerly drops in-flight settlements and silently under-reports revenue</breaks-if>
<suppress-audit>true</suppress-audit>
</element>
</load_bearing_elements>
<rule>Elements in <load_bearing_elements> look redundant or over-defensive but are deliberate. You may refactor them, but the stated invariant must survive; do not "clean up" the oddity itself.</rule>
<banned_apis>
<element path="com.example.service.EvidenceBasedShowcase.totalWithTax(java.math.BigDecimal,java.math.BigDecimal)">
<forbidden>java.lang.System.out, java.util.Date, java.lang.Double</forbidden>
<use-instead>the injected org.slf4j.Logger, java.time.Instant, and java.math.BigDecimal</use-instead>
<reason>Console output bypasses structured logging; Date and Double are unsafe for money and time</reason>
</element>
</banned_apis>
<rule>The APIs listed in <banned_apis> compile at those elements but are prohibited there. Use the stated replacement; if none is given, ask rather than substituting an equivalent.</rule>
<thread_affinity_elements>
<element path="com.example.service.EvidenceBasedShowcase.refreshCartBadge()">
<affinity>the checkout-ui thread only</affinity>
<marshal-via>CheckoutDispatcher.runOnUiThread</marshal-via>
<symptom-if-violated>Cart totals render stale under load; no exception is thrown</symptom-if-violated>
</element>
</thread_affinity_elements>
<rule>Elements in <thread_affinity_elements> are safe on exactly one thread — the opposite of thread-safe. Never add locks or synchronization to "make them safe"; marshal the call onto the required thread instead.</rule>
<mirrored_elements>
<element path="com.example.service.EvidenceBasedShowcase.CATALOG_VERSION">
<mirror>pom.xml:<version></mirror>
<mirror>README.md version badge</mirror>
<mirror>docs/CHANGELOG.md</mirror>
<reason>The release version is duplicated across build config, docs, and the badge</reason>
<enforced-by>ProjectFactsConsistencyTest</enforced-by>
</element>
</mirrored_elements>
<rule>Elements in <mirrored_elements> are duplicated at the listed sites. They may change freely, but every mirror must change in the same commit — a partial edit desyncs silently and no compiler will catch it.</rule>
</project_guardrails>
<rule>Never propose edits to files listed in <locked_files>.</rule>
<!-- VIBETAGS-MODULE-END: showcase -->
<!-- VIBETAGS-MODULE: tests -->
<!-- # Generated by VibeTags | https://github.com/PIsberg/vibetags -->
<project_guardrails>
<locked_files>
</locked_files>
<contextual_instructions>
</contextual_instructions>
</project_guardrails>
<rule>Never propose edits to files listed in <locked_files>.</rule>
## Inherited Guardrails (dependencies)
These come from packages this project depends on. They constrain how the dependency may be used; they are not editable from here.
- `com.example.multimodule.core` (from se.deversity.vibetags.example:multimodule-core:1.0)
- @AISecure: aspect=Node identity is a security boundary: never build an IrNode from unvalidated external input, and never expose its raw id in a URL or log line.
## Inherited Context (dependencies)
Conventions the dependency's authors documented. Follow them unless this project's own rules above say otherwise.
- `com.example.multimodule.core` (from se.deversity.vibetags.example:multimodule-core:1.0)
- @AIContext: avoids=Adding mutable state, framework annotations, or a dependency on any sibling module.; focus=Immutable IR data model shared across every module of the reactor.
- @AIThreadSafe: note=Every type in this package is safe to publish across threads without synchronization.; strategy=IMMUTABLE
<!-- VIBETAGS-MODULE-END: tests -->
<!-- VIBETAGS-END -->