Bootstrap copied BFF and local accounts with public Sendico contracts (#34)

backend/AGENTS.md

@@ -1,15 +1,95 @@
-# BFF guidelines
+# Backend Agent Guidelines
 
-Follow root AGENTS.md. This is an independent Go module; Sendico is an external
-provider, not a local module dependency. Never add sibling-path replacements,
-shared database access or internal Sendico discovery/messaging dependencies.
+These instructions extend the repository-wide rules in the root `AGENTS.md`
+and apply whenever a task adds or modifies backend code, including Go and
+protobuf files under `backend/`.
 
-Keep HTTP DTOs/mappers, application models/use cases and provider adapters distinct.
-Resolve ownership from the authenticated SXCHNGE principal and server-side mappings.
-Only adapters may expose provider transport types internally. Adapted code belongs
-to SXCHNGE; record source revision and changes in PROVENANCE.md.
+Before completing the task, review the entire backend diff produced by the
+current task, fix every in-scope issue found, and then perform the required
+validation. Use the
+[`$review-backend-change`](../.agents/skills/review-backend-change/SKILL.md)
+skill to perform this completion workflow.
 
-Review the complete backend contribution before delivery. Run `make test-backend`
-and `make lint-backend` at the repository root. Add behavioral tests for changed
-boundaries and failure paths. Errors returned publicly must be stable typed codes;
-never expose raw provider errors, secrets, document contents or credentials.
+## Reuse existing definitions
+
+- Search the repository before introducing a protobuf message, enum, Go struct,
+  interface, or shared domain type.
+- Reuse or extend the canonical existing definition when its semantics match.
+  Do not create parallel representations or conversion layers for the same
+  concept without a clear architectural reason.
+- Avoid naming stutter in packages, types, fields, parameters, and access paths.
+  Each nested name should add meaning instead of repeating its parent context.
+  For example, prefer a concise path such as `payment.Details.ID` over
+  `payment.Payment.PaymentID`.
+
+## Use the project error model
+
+- Do not introduce `fmt.Errorf` or `errors.New`. Use the constructors and
+  wrapping helpers in `backend/pkg/merrors`.
+- Preserve the underlying cause when adding context by using an appropriate
+  `merrors` wrapping helper.
+- When no suitable project error exists, add the smallest generally useful
+  definition or helper to `backend/pkg/merrors` instead of creating an ad hoc error
+  elsewhere.
+
+## Keep modules cohesive and names concise
+
+- Review touched files for excessive size, mixed responsibilities, duplicated
+  logic, and poor separation of concerns.
+- Refactor oversized contributions into focused, cohesive files or packages.
+  Do not split code mechanically; organize it along clear domain or
+  architectural boundaries.
+- Avoid repeating directory or package context in child directory and file
+  names. For example, prefer `payment/widget.dart` over
+  `payment/payment_widget.dart`.
+
+## Review implementation quality
+
+- Review the current task's backend contribution for correctness, readability,
+  maintainability, testability, and consistency with the surrounding
+  architecture.
+- Keep public APIs and module boundaries small and intentional. Remove
+  unnecessary indirection, duplication, dead code, and speculative abstractions.
+- Add or update tests for changed behavior, edge cases, and failure paths.
+- Fix all findings caused by the current task before reporting completion.
+
+## Review logging
+
+- Ensure the contribution has sufficient structured logging at meaningful
+  operational and domain boundaries. Include useful identifiers and context,
+  but never log credentials, secrets, or sensitive payment data.
+- Follow the repository's logging style and use levels consistently:
+  - `Debug`: fine-grained runtime execution tracking useful during debugging.
+  - `Info`: important payment-domain events, module-boundary operations,
+    effective module configuration, and noteworthy but expected deviations from
+    the usual path.
+  - `Warn`: runtime errors and unexpected conditions from which the service can
+    continue or which are returned to a caller.
+  - `Error`: unrecoverable failures that cause, or imminently lead to, service
+    or component termination.
+- Avoid logging the same error repeatedly at multiple layers. Log it where the
+  layer has enough context to make the event actionable.
+
+## Required validation
+
+- From the repository root, run `make test` and `make lint-backend`, plus every
+  applicable command from the root `AGENTS.md` change-scoped security
+  requirements, after all review fixes are complete.
+- All commands must succeed before the task is reported as complete. Fix
+  failures introduced by the current task; do not silently skip, suppress, or
+  weaken checks.
+- Report the commands run and their outcomes in the final response. If an
+  external or environmental blocker prevents a command from running, report
+  the exact command, failure, and blocker explicitly; do not claim successful
+  validation.
+
+## SXCHNGE provider boundary
+
+SXCHNGE owns auth, sessions and customer management. SXCHNGE is one organization
+inside Sendico. Copied BFF components are locally owned and may diverge.
+Use only Sendico's public HTTP API for platform operations. Never import sibling
+Sendico modules or access its database, internal gRPC APIs, discovery or message
+bus. Keep the pinned public wire contract separate from local DTOs and models.
+Resolve the configured provider organization and customer resource ownership on
+the server. Never treat all customers as the backend integration principal.
+Use the copied structured logger, injected at operational boundaries.