jattac.libs.web.zest-button 1.2.9 → 1.4.0

package/docs/guidelines/AI_KNOWLEDGE.md

@@ -0,0 +1,213 @@
+# AI Knowledge Graph
+
+Purpose:
+
+Maintain a continuously evolving architectural memory of this repository.
+
+This document is not documentation for humans.
+
+It is persistent memory for future AI agents.
+
+---
+
+Every completed task MUST update this file if new knowledge is discovered.
+
+This MUST happen BEFORE implementation and AGAIN after implementation.
+
+---
+
+# Format
+
+Every component entry MUST follow this format:
+
+```
+## [ComponentName]
+
+### Purpose
+
+[One sentence describing what this component does]
+
+### Location
+
+[File path]
+
+### Callers
+
+[List of components that call this component]
+
+### Callees
+
+[List of components that this component calls]
+
+### Dependencies
+
+[List of external dependencies]
+
+### Publishes
+
+[List of events published]
+
+### Consumes
+
+[List of events consumed]
+
+### Configuration
+
+[Configuration sources and settings]
+
+### Database
+
+[Tables, queries, connections]
+
+### Known Invariants
+
+[Business rules that MUST NOT change]
+
+### Known Pitfalls
+
+[Things that are easy to break]
+
+### Thread Safety
+
+[Concurrency considerations]
+
+### Transaction Boundaries
+
+[Transaction scope and isolation]
+
+### Security Assumptions
+
+[Authentication, authorization assumptions]
+
+### Performance Characteristics
+
+[Known performance traits]
+
+### Test Coverage
+
+[What is tested, what is not]
+```
+
+---
+
+# Entry Rules
+
+Every component discovered during implementation MUST be added.
+
+Every component modified during implementation MUST be updated.
+
+Never remove information unless proven obsolete.
+
+Prefer appending.
+
+Repository knowledge compounds over time.
+
+---
+
+# Example
+
+## PaymentService
+
+### Purpose
+
+Creates payment records.
+
+### Location
+
+src/Services/PaymentService.cs
+
+### Callers
+
+OrderController
+
+InvoiceService
+
+### Callees
+
+PaymentRepository
+
+EventBus
+
+EmailService
+
+### Dependencies
+
+Newtonsoft.Json
+
+Stripe SDK
+
+### Publishes
+
+PaymentCreated
+
+PaymentFailed
+
+### Consumes
+
+OrderPlaced
+
+RefundRequested
+
+### Configuration
+
+PaymentSettings:MaxRetries (appsettings.json)
+
+PaymentSettings:StripeKey (secrets)
+
+### Database
+
+Payments table
+
+PaymentAuditLog table
+
+### Known Invariants
+
+Payment amount is immutable after settlement.
+
+Payment status transitions are one-way: Pending → Settled or Pending → Failed.
+
+### Known Pitfall
+
+Registration occurs through reflection. Do not remove the Register method.
+
+### Thread Safety
+
+Payment processing is serialized per payment ID.
+
+### Transaction Boundaries
+
+Payment creation and event publishing are in separate transactions.
+
+### Security Assumptions
+
+Stripe key must never appear in logs.
+
+### Performance Characteristics
+
+Payment creation is synchronous. Event handlers are asynchronous.
+
+### Test Coverage
+
+Unit tests for PaymentService.
+Integration tests for PaymentRepository.
+No tests for EmailService (mocked).
+
+---
+
+# Cross-References
+
+When a component is modified, check all components that reference it.
+
+Update their entries if the modification affects their behaviour.
+
+---
+
+# Maintenance
+
+Never delete entries unless the component has been removed from the codebase.
+
+Never delete known invariants unless explicitly instructed.
+
+Never delete known pitfalls unless they have been resolved.
+
+When in doubt, append rather than modify.

package/docs/guidelines/AI_PITFALLS.md

@@ -0,0 +1,245 @@
+# Common AI Failure Modes
+
+Never do the following.
+
+---
+
+# Understanding Failures
+
+Delete code because it appears unused.
+
+Assume an event has no consumers.
+
+Assume tests are complete.
+
+Assume absence of references means safe removal.
+
+Assume you understand code you have not read.
+
+Assume you understand a call chain you have not fully traced.
+
+Assume you know all consumers of a method.
+
+Assume you know all callers of a method.
+
+Assume existing behaviour is incorrect without evidence.
+
+Guess business intent.
+
+Claim certainty without evidence.
+
+---
+
+# Modification Failures
+
+Rewrite working code to match personal preference.
+
+Replace architecture while implementing features.
+
+Modify unrelated files.
+
+Change formatting of unrelated code.
+
+Rename APIs without instruction.
+
+Rename symbols without instruction.
+
+Reorder methods without instruction.
+
+Reorder imports without instruction.
+
+Move files without instruction.
+
+Modernise code without instruction.
+
+---
+
+# Addition Failures
+
+Add code you think is needed but was not requested.
+
+Add comments you think are helpful but were not requested.
+
+Add logging you think is useful but was not requested.
+
+Add error handling you think is necessary but was not requested.
+
+Add null checks or defensive code you think is prudent but was not requested.
+
+Add TODO comments about code you think needs improvement.
+
+Add comments about code that needs refactoring.
+
+Add try-catch blocks "just in case."
+
+Add blanket exception handling.
+
+Add null-forgiving operators to silence warnings.
+
+Add #pragma disable to silence warnings.
+
+Add SuppressMessage attributes.
+
+Add Obsolete attributes.
+
+Add InternalsVisibleTo for test projects.
+
+---
+
+# Dependency Failures
+
+Upgrade package versions to "fix" or "improve."
+
+Add packages you think are needed.
+
+Remove packages you think are unused.
+
+Change SDK versions.
+
+Change tool versions.
+
+---
+
+# Configuration Failures
+
+Modify build or CI configuration to "improve" it.
+
+Modify database schema or migrations to "fix" something.
+
+Modify configuration files to "improve" defaults.
+
+Modify environment variables.
+
+Modify secrets or secret references.
+
+Modify Docker files or container configurations.
+
+---
+
+# Testing Failures
+
+Claim tests pass without showing output.
+
+Claim build succeeds without showing output.
+
+Skip tests.
+
+Disable tests.
+
+Mark tests as ignored.
+
+Modify tests to make them pass.
+
+Change test expectations to match broken behaviour.
+
+Add tests that do not assert specific values.
+
+Add tests that only verify "does not throw."
+
+Add tests that depend on execution order.
+
+Add tests that depend on external state.
+
+Add tests that do not clean up after themselves.
+
+---
+
+# Code Quality Failures
+
+Change method signatures to "improve" them.
+
+Change return types to be "more correct."
+
+Change access modifiers to make things testable.
+
+Make private things public for testing.
+
+Add async/await where it was not present.
+
+Change synchronous code to asynchronous.
+
+Add ConfigureAwait(false) everywhere.
+
+Add methods that do not belong in the current class.
+
+Add classes that do not belong in the current module.
+
+Add abstractions without clear need.
+
+Add interfaces without clear need.
+
+Add base classes without clear need.
+
+---
+
+# Process Failures
+
+Proceed with implementation when you have not fully read the code you are modifying.
+
+Proceeding with incomplete understanding of the call chain.
+
+Proceeding when you have unresolved questions.
+
+Modify files that are not directly required by the task.
+
+Refactoring code during feature work or bug fixes.
+
+Reordering code for "clarity" during feature work.
+
+Reformatting code during feature work.
+
+Renaming things during feature work.
+
+Squashing errors silently.
+
+Swallowing exceptions.
+
+Ignoring failing tests.
+
+Skipping blast radius analysis.
+
+Forgetting to update ai-knowledge.md.
+
+Forgetting to update decision-log.md.
+
+Forgetting to produce a change manifest.
+
+Forgetting to report test output.
+
+---
+
+# Communication Failures
+
+Report completion without showing test output.
+
+Report completion without producing a change manifest.
+
+Report completion without performing self review.
+
+Report completion with unresolved uncertainties.
+
+Report completion with FAIL items in the self review.
+
+Claim success without evidence.
+
+Understate risks.
+
+Hide unknowns.
+
+Overstate confidence.
+
+---
+
+# Always
+
+Always prefer explicit reasoning over assumptions.
+
+Always preserve behaviour over elegance.
+
+Always explain WHY each change was made.
+
+Always trace changes to specific user requirements.
+
+Always read before you write.
+
+Always stop when uncertain.

package/docs/guidelines/AI_STYLE_GUIDE.md

@@ -0,0 +1,162 @@
+# AI Style Guide
+
+Never introduce a second pattern when one already exists.
+
+Prefer existing abstractions.
+
+Respect existing project structure.
+
+Do not rename symbols without instruction.
+
+Keep methods cohesive.
+
+Avoid speculative abstractions.
+
+One responsibility per class.
+
+Do not optimise prematurely.
+
+Use explicit names over clever names.
+
+Prefer readability over brevity.
+
+---
+
+# Naming
+
+Use the same naming conventions as existing code.
+
+Do not introduce new naming patterns.
+
+Match the capitalisation style of existing code (camelCase, PascalCase, snake_case).
+
+Match the abbreviation style of existing code.
+
+---
+
+# File Structure
+
+Place new files in the same directories as similar existing files.
+
+Do not create new directory structures.
+
+Do not reorganise files.
+
+Do not move files.
+
+---
+
+# Method Length
+
+If a method exceeds ~30 lines, consider whether it should be split.
+
+But only if the existing codebase demonstrates that pattern.
+
+Do not split methods that are shorter than surrounding code.
+
+---
+
+# Class Length
+
+If a class exceeds ~300 lines, consider whether it should be split.
+
+But only if the existing codebase demonstrates that pattern.
+
+Do not split classes that are smaller than surrounding code.
+
+---
+
+# Parameters
+
+If a method has more than 4 parameters, consider whether a parameter object is appropriate.
+
+But only if the existing codebase demonstrates that pattern.
+
+Do not introduce parameter objects for methods that have fewer parameters than surrounding code.
+
+---
+
+# Error Handling
+
+Use the same error handling patterns as existing code.
+
+Do not introduce new patterns.
+
+Do not add error handling that does not exist in surrounding code.
+
+---
+
+# Logging
+
+Use the same logging patterns as existing code.
+
+Do not introduce new patterns.
+
+Do not add logging that does not exist in surrounding code.
+
+---
+
+# Configuration
+
+Use the same configuration patterns as existing code.
+
+Do not introduce new patterns.
+
+---
+
+# Comments
+
+Use the same comment style as existing code.
+
+Do not introduce new styles.
+
+Do not add comments unless explicitly requested.
+
+---
+
+# Formatting
+
+Match the formatting of surrounding code exactly.
+
+Do not reformat unrelated code.
+
+Do not change whitespace in unrelated code.
+
+Do not change line breaks in unrelated code.
+
+Do not change indentation in unrelated code.
+
+---
+
+# Imports
+
+Use the same import style as existing code.
+
+Do not reorder imports.
+
+Do not add imports unless explicitly required by the change.
+
+Do not remove imports unless the removed import is no longer used.
+
+---
+
+# Access Modifiers
+
+Use the same access modifier patterns as existing code.
+
+Do not change access modifiers unless explicitly required.
+
+Do not make private things public for testing.
+
+Do not make things internal for convenience.
+
+---
+
+# Project-Specific Style — Lattice Admin Web
+
+## Copy rules
+
+- All page titles, subtitles, labels, and helper text must be written for business users and operations staff
+- Never use technical terms like "table-driven", "SQL INSERT", "endpoint", "schema", or backend implementation details in any user-facing string
+- Subtitle of `PageContainer` should describe what the page does and why it matters to the user, not how it works internally
+- Instruction panels in forms should explain field purpose in plain business language