llms-full.txt@examples/multimodule ยท git:20260914.d4d016c ยท 2026-09-14 ยท sha256 e4df733a1793c396
llms-full.txt@examples/multimodule git:20260914.d4d016cA
Immutable. This exact content never changes and is served at /api/v1/blob/e4df733a1793c396.
<!-- VIBETAGS-START --> <!-- VIBETAGS-MODULE: cli --> # VibeTags Multi-Module Example โ AI Guardrail Rules > Complete AI guardrail configuration generated from source annotations by VibeTags. This document contains the full set of AI guardrail rules for this project. AI tools with large context windows (such as Windsurf Cascade, Claude 4.6, or Gemini 1.5 Pro) may load this file directly instead of fetching individual documentation pages. ## Locked Files (Do Not Edit) The following files are locked. AI tools MUST NOT propose modifications to them. ## Contextual Rules These files have specific context and focus areas for AI assistance. ## Mandatory Security Audit Requirements When writing or modifying the following files, perform a security audit for the listed vulnerabilities before displaying any code to the user. ### com.example.multimodule.cli.MultiModuleCli - **Required Checks**: Path Traversal ## ๐ Contract-Frozen Signatures The following elements have frozen public API signatures. Internal implementation may be changed, but you MUST NOT alter method names, parameter types, parameter order, return types, or checked exceptions. ### com.example.multimodule.cli.MultiModuleCli.run(java.lang.String[]) - **Reason**: Public CLI surface; flags are documented downstream ## ๐งช Test-Driven Requirements The following elements require a matching test update whenever their logic is modified. Changes without tests are incomplete. ### com.example.multimodule.cli.MultiModuleCli - **Coverage Goal**: 100% - **Frameworks**: JUNIT_5 - **Test Location**: src/test/java/com/example/multimodule/cli ## โป๏ธ Idempotency Guarantees These operations are idempotent โ calling multiple times must produce the same result as calling once. ### com.example.multimodule.cli.MultiModuleCli.outputPath(java.lang.String,java.lang.String) - Idempotency guaranteed. Multiple invocations must produce the same result as a single invocation. - **Reason**: Derives output path from inputs only ## Deterministic Pure Functions The following elements must remain pure functions without side effects or mutations. ### com.example.multimodule.cli.MultiModuleCli.outputPath(java.lang.String,java.lang.String) - **Requirement**: Mathematically pure function. No side effects. ## 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 --> # VibeTags Multi-Module Example โ AI Guardrail Rules > Complete AI guardrail configuration generated from source annotations by VibeTags. This document contains the full set of AI guardrail rules for this project. AI tools with large context windows (such as Windsurf Cascade, Claude 4.6, or Gemini 1.5 Pro) may load this file directly instead of fetching individual documentation pages. ## Locked Files (Do Not Edit) The following files are locked. AI tools MUST NOT propose modifications to them. ### com.example.multimodule.core.IrNode - **Reason**: Core IR node: structural changes break every downstream module ## Contextual Rules These files have specific context and focus areas for AI assistance. ### com.example.multimodule.core - **Focus**: Immutable IR data model shared across every module of the reactor. - **Avoid**: Adding mutable state, framework annotations, or a dependency on any sibling module. ## ๐งต Thread-Safe by Design These elements are explicitly designed to be thread-safe via the named strategy. Preserve the synchronization invariant on every change. ### com.example.multimodule.core - **Strategy**: IMMUTABLE - **Note**: Every type in this package is safe to publish across threads without synchronization. ## โ๏ธ Immutable Types The following types are immutable. Never introduce non-final fields, setters, or mutating methods. ### com.example.multimodule.core.IrGraph - Immutable type โ never introduce non-final fields, setters, or mutating methods. ## ๐ Security-Critical Code These elements are security-critical. Do not weaken security properties. Every change requires security review. ### com.example.multimodule.core - Security-critical code (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.). - Never weaken security properties. Every change requires explicit security review. ## Framework-Free Domain Entities The following elements are pure Domain Models. Do not import Spring, JPA/Hibernate, Jackson, or other framework packages. ### com.example.multimodule.core.IrNode - **Domain Boundary**: Framework-agnostic Domain Entity. <!-- VIBETAGS-MODULE-END: core --> <!-- VIBETAGS-MODULE: engine --> # VibeTags Multi-Module Example โ AI Guardrail Rules > Complete AI guardrail configuration generated from source annotations by VibeTags. This document contains the full set of AI guardrail rules for this project. AI tools with large context windows (such as Windsurf Cascade, Claude 4.6, or Gemini 1.5 Pro) may load this file directly instead of fetching individual documentation pages. ## Locked Files (Do Not Edit) The following files are locked. AI tools MUST NOT propose modifications to them. ## Contextual Rules These files have specific context and focus areas for AI assistance. ## ๐งต Thread-Safe by Design These elements are explicitly designed to be thread-safe via the named strategy. Preserve the synchronization invariant on every change. ### com.example.multimodule.engine.LayoutEngine - **Strategy**: SYNCHRONIZED - **Note**: Stateless; safe to share across render threads ## open-closed Extension Patterns The following elements require extension using polymorphic patterns (Strategy/Visitor). Do not append branch conditionals. ### com.example.multimodule.engine.LayoutEngine - **Extension Design**: STRATEGY_PATTERN. Use polymorphism. ## 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 --> # VibeTags Multi-Module Example โ AI Guardrail Rules > Complete AI guardrail configuration generated from source annotations by VibeTags. This document contains the full set of AI guardrail rules for this project. AI tools with large context windows (such as Windsurf Cascade, Claude 4.6, or Gemini 1.5 Pro) may load this file directly instead of fetching individual documentation pages. ## Locked Files (Do Not Edit) The following files are locked. AI tools MUST NOT propose modifications to them. ### com.example.payment.PaymentProcessor - **Reason**: Tied to legacy database schema v2.3. Changes will break production payment processing. Contact the payments team before modifying. ### com.example.security.SecurityConfig - **Reason**: CRITICAL: Security configuration managed by DevOps team. Any changes require security review and approval ticket SEC-XXXX ### com.example.security.SecurityConfig.getEncryptionAlgorithm() - **Reason**: Encryption algorithm tied to compliance requirements (PCI-DSS) ### com.example.security.SecurityConfig.getKeyRotationHours() - **Reason**: Key rotation period mandated by company policy ### com.example.security.SecurityConfig.getMaxLoginAttempts() - **Reason**: Max login attempts set by security team to prevent brute force ### com.example.security.SecurityConfig.validateToken(java.lang.String) - **Reason**: Token validation must match auth server exactly. Changes will break all client authentication ### com.example.service.OrderService.calculateTax(java.lang.String,double) - **Reason**: Tax calculation uses Avalara API integration. Credentials and endpoint configuration managed by finance team. ### com.example.service.OrderService.processPayment(java.lang.String,double) - **Reason**: Payment processing uses Stripe API v2024.10. Changes require PCI compliance review. ### 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. ## Contextual Rules These files have specific context and focus areas for AI assistance. ### com.example.security.SecurityConfig - **Focus**: This class is READ-ONLY for AI assistants. Do not suggest modifications. - **Avoid**: Any changes to encryption algorithms, key sizes, or validation logic ### com.example.service.InventoryService - **Focus**: Maintain inventory consistency across concurrent requests. All stock updates must be atomic. - **Avoid**: Non-atomic read-modify-write sequences, unsynchronized shared state ### com.example.service.NotificationService - **Focus**: Implement notification delivery with retry logic and error handling - **Avoid**: Hard-coded credentials, synchronous blocking calls ### com.example.service.OrderService - **Focus**: Maintain transactional integrity. All database operations must use proper transaction management. - **Avoid**: Raw SQL queries, direct database connections without connection pooling ### com.example.service.PricingService - **Focus**: Optimize pricing calculations for accuracy and throughput. Internal algorithms may use any efficient approach. - **Avoid**: Floating-point arithmetic for monetary values โ use BigDecimal internally, but note that the contract-frozen signatures use double for backwards compatibility ### com.example.strategy.PaymentStrategy - **Focus**: Follow the Strategy pattern strictly. Each payment method should be a separate strategy class implementing this interface. - **Avoid**: Monolithic if-else chains, hard-coded payment logic, single class handling all payment types ### com.example.utils.StringParser - **Focus**: Optimize for memory usage over CPU speed. Minimize object allocations and avoid creating intermediate string objects. - **Avoid**: java.util.regex, String.split(), StringBuilder in loops ## Mandatory Security Audit Requirements When writing or modifying the following files, perform a security audit for the listed vulnerabilities before displaying any code to the user. ### com.example.database.DatabaseConnector - **Required Checks**: SQL Injection, Thread Safety issues ## Ignored Elements The following elements must be completely excluded from AI context. Treat them as non-existent. ### com.example.internal.GeneratedMetadata - Excluded from AI context entirely - treat as non-existent - Reason: Auto-generated at build time. Manual edits are overwritten on every build. ## Implementation Tasks The following elements are in draft mode and need implementation. ### com.example.NotificationService - **Instructions**: Implement email sending via SMTP and push notifications via FCM. Ensure retry logic and rate limiting are applied. ### com.example.payment.PaymentProcessor - **Instructions**: Implement support for new crypto payments without breaking legacy flow. ### 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. ### 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). ### 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). ### 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. ### 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). ### 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. ### 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. ### 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. ### 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. ### 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. ### com.example.strategy.PaymentStrategy.validatePaymentMethod() - **Instructions**: Validate payment method specific data (card numbers, email addresses, wallet addresses, etc.). Return true if valid, false otherwise. ### 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. ### 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. ## PII / Privacy Guardrails Never include runtime values of the following elements in logs, console output, external API calls, test fixtures, or mock data. ### com.example.database.DatabaseConnector.password - **Reason**: Database credential - never log or include in error messages ### com.example.database.DatabaseConnector.username - **Reason**: Database credential - never log or include in error messages ### com.example.service.InventoryService.customerId - **Reason**: Customer identifiers linked to purchase history โ PII under GDPR ### 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 ### com.example.service.NotificationService.sendSMS(java.lang.String,java.lang.String) - **Reason**: Phone number is PII - never log the destination number ### com.example.service.OrderService.generateOrderConfirmation(java.lang.String) - **Reason**: Output contains customer shipping address and contact details (PII) ### com.example.strategy.impl.CreditCardStrategy.cardNumber - **Reason**: PCI-DSS cardholder data - never log or expose in suggestions ### com.example.strategy.impl.CreditCardStrategy.cvv - **Reason**: PCI-DSS security code - never log or expose in suggestions ### com.example.strategy.impl.CreditCardStrategy.expiryDate - **Reason**: PCI-DSS cardholder data - never log or expose in suggestions ## ๐ง Core Functionality The following elements are well-tested core functionality. Make changes with extreme caution. ### com.example.security.SecurityConfig - **Sensitivity**: Critical - **Note**: This is a security manager. Any single-line change can compromise the entire project. ### com.example.service.InventoryService.releaseReservation(java.lang.String) - **Sensitivity**: High - **Note**: Must be called as the exact inverse of reserveStock. Pair changes to both methods together. ### com.example.service.InventoryService.reserveStock(java.lang.String,int,java.lang.String) - **Sensitivity**: Critical - **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. ## โก Performance Constraints The following elements are on a hot-path and have strict time/space complexity constraints. ### com.example.payment.PaymentProcessor - **Constraint**: HFT-level requirements: O(1) processing time expected. No database lookups in processing loop. ### 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. ### 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. ### com.example.service.PricingService.calculatePrice(java.lang.String,int,java.lang.String) - **Constraint**: Must complete in <5ms p99. Called on every cart update. ## ๐ Contract-Frozen Signatures The following elements have frozen public API signatures. Internal implementation may be changed, but you MUST NOT alter method names, parameter types, parameter order, return types, or checked exceptions. ### 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. ### 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. ### 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. ## ๐งช Test-Driven Requirements The following elements require a matching test update whenever their logic is modified. Changes without tests are incomplete. ### com.example.service.OrderService.calculateDiscount(java.lang.String,java.lang.String) - **Coverage Goal**: 100% - **Frameworks**: JUNIT_5, ASSERTJ - **Mock Policy**: Use fixed prices โ no external pricing calls in unit tests ### com.example.service.OrderService.updateOrderStatus(java.lang.String,java.lang.String) - **Coverage Goal**: 95% - **Frameworks**: JUNIT_5, MOCKITO - **Test Location**: src/test/java/com/example/service/OrderServiceTest.java - **Mock Policy**: Mock OrderRepository and EventPublisher; use real state machine logic ## ๐งต Thread-Safe by Design These elements are explicitly designed to be thread-safe via the named strategy. Preserve the synchronization invariant on every change. ### com.example.concurrent.SessionCache - **Strategy**: LOCK_FREE - **Note**: All mutations go through ConcurrentHashMap; never introduce a synchronized block on the cache map. ## โ๏ธ Immutable Types The following types are immutable. Never introduce non-final fields, setters, or mutating methods. ### com.example.config.AsyncTestConfig - Immutable type โ never introduce non-final fields, setters, or mutating methods. - **Note**: Used by every test runner; safe to share across threads without copies. ## โ ๏ธ Deprecated Elements The following elements are deprecated. Suggest migration to the named replacement for any caller and do not extend them. ### com.example.legacy.OldPaymentApi - **Replaced by**: com.example.payment.PaymentProcessor - **Migration**: Switch callers to PaymentProcessor.charge(). The new API uses Money instead of double. - **Deadline**: v2.0 (2026-Q4) ## ๐ก Observability Instrumentation The following elements emit metrics, traces, or log statements that downstream dashboards and alerts depend on. ### com.example.metrics.OrderMetrics.recordOrderPlaced(java.lang.String,boolean) - **Metrics**: orders.placed.total, orders.placed.failed - **Traces**: order.place - **Logs**: OrderPlaced, OrderPlacementFailed - **Note**: Watched by the Orders SLO dashboard (https://grafana.internal/d/orders-slo). ## ๐ Regulatory Compliance The following elements implement specific regulatory clauses. Document compliance impact for every change and never weaken the requirement. ### com.example.compliance.GdprService - **Standard**: GDPR - **Clause**: Art. 17 - **Description**: Right to erasure โ when invoked, deletes ALL PII for the given user across every connected store. ### com.example.compliance.GdprService.exportUserData(java.lang.String) - **Standard**: GDPR - **Clause**: Art. 20 - **Description**: Right to data portability โ exports the user's data in a machine-readable format. ## Strict Test Isolation AI tools must enforce strict isolation when generating or modifying tests for these elements. ### com.example.config.ParallelTestSettings - Enforce strict test isolation and thread safety. Do not share mutable state between parallel test cases. ## Legacy Compatibility Bridge These elements are legacy or compatibility bridges. Do not restructure or modernize them. ### com.example.legacy.LegacyBridgeService - Legacy compatibility bridge. Do not refactor structural patterns. Only modify internal business logic as explicitly requested. ## Architectural Boundary Constraints Strict architectural layering must be respected. No illegal references or imports. ### com.example.service.LayeredDomainService - **Belongs to Layer**: domain - **Prohibited References**: infrastructure, ui ## Public API Surface Protection These elements expose public API surfaces. Preserve signatures, Javadocs, and backward compatibility. ### com.example.service.PublicPaymentController - Public API surface. Preserve signature, Javadoc, and behavior without breaking backwards compatibility. ## Strict Exception Handling Precise and robust exception handling must be enforced. No catching or throwing generic Exception. ### com.example.service.TransactionalPaymentService - Enforce precise exception handling. Prohibit catching or throwing generic Exceptions/Throwables. Use specific or custom exceptions. ## Strict Type Safety Type safety must be strictly preserved. Loose or erased types are prohibited. ### com.example.payment.PaymentDetails - Prohibit loose typing. Use strongly-typed transfer objects or domain models instead of Object or Map<String, Object>. ## Internationalization Mandate User-facing strings must not be hardcoded; resolve them via localized resources. ### com.example.utils.I18nMessageHelper - Internationalization mandate. Prohibit hardcoding user-facing strings; all user-visible text must be localized. ## Strict Classpath Integrity Dynamic runtime class loading and reflections are strictly prohibited. ### com.example.utils.StrictUtility - Strict classpath integrity. Prohibit dynamic runtime class loading, reflections, or external JAR injection. ## Schema & Serialization Safety Schema and serialization compatibility must be strictly preserved. ### com.example.database.UserEntity - Schema and serialization safety. Restrict changing serialization formats, database fields, or API models without a migration path. ## โป๏ธ Idempotency Guarantees These operations are idempotent โ calling multiple times must produce the same result as calling once. ### com.example.compliance.GdprService.deleteAllUserData(java.lang.String) - Idempotency guaranteed. Multiple invocations must produce the same result as a single invocation. - **Reason**: Deleting a user's data multiple times must produce the same result as deleting once โ must not throw on second invocation. ## ๐ฉ Feature Flag Gated Code These elements are gated behind a feature flag. Preserve the flag check and handle both enabled and disabled code paths. ### com.example.service.InventoryService.sendLowStockAlert(java.lang.String,int) - Feature flag: 'inventory.push-alerts.enabled' (default: false) - Preserve the flag check. Never assume the flag is always active. Test both enabled and disabled code paths. ## ๐ Security-Critical Code These elements are security-critical. Do not weaken security properties. Every change requires security review. ### com.example.security.SecurityConfig - Security-critical code (aspect: authentication). - Never weaken security properties. Every change requires explicit security review. ## Access Limitations The following elements have strict caller access limits. AI must not invoke them from outside the allowed boundaries. ### com.example.service.NewAnnotationsShowcase.executeSecureDatabaseWipe() - **Allowed Callers**: com.example.service.PricingService, com.example.payment.PaymentProcessor ## Sandbox & Test Exclusion The following elements are strictly sandbox/test code. Production code must never import or reference them. ### com.example.service.NewAnnotationsShowcase.SandboxTestHelper - **Scope**: Sandbox/testing environments only. Never use in production. ## Memory Allocation Budgets The following elements have strict heap allocation, autoboxing, or garbage budgets. Optimize allocations carefully. ### com.example.service.NewAnnotationsShowcase.calculateFastFibonacci(int) - **Memory Policy**: ZERO_ALLOCATION ## Deterministic Pure Functions The following elements must remain pure functions without side effects or mutations. ### com.example.service.NewAnnotationsShowcase.calculateFastFibonacci(int) - **Requirement**: Mathematically pure function. No side effects. ## Framework-Free Domain Entities The following elements are pure Domain Models. Do not import Spring, JPA/Hibernate, Jackson, or other framework packages. ### com.example.service.NewAnnotationsShowcase.ImmutableProductPrice - **Domain Boundary**: Framework-agnostic Domain Entity. - **Allowed Packages**: java.math.BigDecimal ## open-closed Extension Patterns The following elements require extension using polymorphic patterns (Strategy/Visitor). Do not append branch conditionals. ### com.example.service.NewAnnotationsShowcase.TaxCalculatorStrategy - **Extension Design**: STRATEGY_PATTERN. Use polymorphism. ## Mandatory Input Sanitization The following parameters/fields must go through strict sanitizers before hitting queries or renderers. ### com.example.service.NewAnnotationsShowcase.executeDatabaseQuery(java.lang.String)#sqlRawInput - **Sanitization Requirement**: SQL_INJECTION ## Secure Logging Masking The following sensitive elements must be masked, hashed, or omitted from log/stdout streams. ### com.example.service.NewAnnotationsShowcase.registerUserSession(java.lang.String,java.lang.String,java.lang.String)#creditCardNumber - **Secure Logging Policy**: MASK_CREDIT_CARD ### com.example.service.NewAnnotationsShowcase.registerUserSession(java.lang.String,java.lang.String,java.lang.String)#passwordRaw - **Secure Logging Policy**: HASH ## Required Chain-of-Thought Explanations Any change made to these elements requires a step-by-step mathematical/architectural proof of correctness in the PR/walkthrough. ### com.example.service.NewAnnotationsShowcase.runComplexMatrixMath(double[][],double[][]) - **Explanation Needed**: Yes, Chain-of-Thought (Complexity: HIGH) ## Experimental Prototype Stubs Strict QA constraints and tests are relaxed for these elements, but production classes must never import them. ### com.example.service.NewAnnotationsShowcase.DraftKafkaIntegrationSpike - **Scope**: Experimental Prototype. Bypasses strict validation rules. ## Sunset Deprecated APIs Strictly sunset under deprecation. Introducing *new* references or calls to these elements is forbidden. ### com.example.service.NewAnnotationsShowcase.deprecatedLegacyCalculatePrice(double,double) - **Sunset Status**: Active (Forbid new calls) - **JIRA Ticket**: DEBT-742 - **Replacement**: com.example.service.PricingService ## Temporary Code Workarounds Temporary stubs or hacks that must be refactored or removed before their expiration limit. ### com.example.service.NewAnnotationsShowcase.temporaryUpstreamBypass() - **Temporal Expiration**: 2028-12-31 - **Reason**: Hotfix workaround until upstream payment provider updates their API. ## Generated Code โ Edit The Source These elements are machine-generated and hand edits are silently overwritten. Read them freely; never write them. ### com.example.service.EvidenceBasedShowcase - Machine-generated from `src/main/resources/openapi/checkout.yaml`. - Hand edits are silently overwritten on the next regeneration. - Edit `src/main/resources/openapi/checkout.yaml` instead. - Regenerate with: `mvn generate-sources` - Still read this element to understand behaviour โ only never write it. ## Load-Bearing Oddities These look wrong, redundant, or over-defensive and are deliberate. Refactoring is allowed only while the stated invariant survives. ### com.example.service.EvidenceBasedShowcase.settledOrderIds - This code is deliberate, not accidental. - **Invariant**: Settled orders stay in the list until the reconciliation job drains it - **Breaks if changed**: Clearing eagerly drops in-flight settlements and silently under-reports revenue - Audit tooling should stop reporting this element โ the oddity is by design. - Edits are allowed as long as the invariant survives. ## Banned APIs The following APIs compile at these elements but are prohibited there. Use the sanctioned replacement. ### com.example.service.EvidenceBasedShowcase.totalWithTax(java.math.BigDecimal,java.math.BigDecimal) - **Banned here**: java.lang.System.out, java.util.Date, java.lang.Double - **Sanctioned route**: the injected org.slf4j.Logger, java.time.Instant, and java.math.BigDecimal - **Reason**: Console output bypasses structured logging; Date and Double are unsafe for money and time - These symbols compile, so the compiler will not stop you. The ban is a project rule. ## Thread Affinity (Not Thread-Safe) These elements are safe on exactly one thread. Do not add locks โ marshal the call onto the required thread instead. ### com.example.service.EvidenceBasedShowcase.refreshCartBadge() - **Thread affinity**: the checkout-ui thread only - This is the inverse of thread-safety: safe on one thread, unsafe on every other. - Do NOT add synchronization to "fix" this โ move the call, do not lock it. - **Marshal via**: CheckoutDispatcher.runOnUiThread - **Symptom if violated**: Cart totals render stale under load; no exception is thrown ## Mirrored Elements These are duplicated elsewhere. They may change freely, but a partial change silently desyncs a mirror no compiler checks. ### com.example.service.EvidenceBasedShowcase.CATALOG_VERSION - **Must stay in sync with**: - pom.xml:<version> - README.md version badge - docs/CHANGELOG.md - **Reason**: The release version is duplicated across build config, docs, and the badge - **Enforced by**: ProjectFactsConsistencyTest - The element itself is free to change; changing only one side is the bug. <!-- VIBETAGS-MODULE-END: showcase --> <!-- VIBETAGS-MODULE: tests --> # VibeTags Multi-Module Example โ AI Guardrail Rules > Complete AI guardrail configuration generated from source annotations by VibeTags. This document contains the full set of AI guardrail rules for this project. AI tools with large context windows (such as Windsurf Cascade, Claude 4.6, or Gemini 1.5 Pro) may load this file directly instead of fetching individual documentation pages. ## Locked Files (Do Not Edit) The following files are locked. AI tools MUST NOT propose modifications to them. ## Contextual Rules These files have specific context and focus areas for AI assistance. ## 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 -->