test(solution): Improve Ploch.Data testing experience and code coverage across all projects

.aiassistant/review_guidelines.md

@@ -0,0 +1,238 @@
+# Ploch.Data Review Guidelines
+
+Use these guidelines when reviewing staged or pending changes in this
+repository. Review every change as if it may ship as a public NuGet
+package and be consumed outside this repository. Prioritise
+correctness, regression risk, compatibility, package-boundary safety,
+test coverage, and documentation over cosmetic feedback.
+
+## Core Review Priorities
+
+1. Find bugs, regressions, unsafe changes, and unintended breaking
+   changes first.
+2. Protect provider-agnostic abstractions from EF Core or
+   provider-specific leakage.
+3. Protect external-consumer behaviour, especially package APIs, DI
+   registration, persisted state, and SampleApp packaging.
+4. Treat missing tests, missing documentation, and missing validation as
+   real findings when behaviour or public surface changes.
+5. Avoid low-value nits already enforced by analyzers or formatters
+   unless they hide a real maintenance problem.
+
+## How To Write Findings
+
+- Order findings by severity: blocker, high, medium, low.
+- Each finding should explain the problem, impact, affected file or
+  area, and what kind of correction is expected.
+- Prefer precise, actionable comments over broad stylistic advice.
+- Distinguish required fixes from optional improvements.
+- State verification gaps explicitly when tests or builds that should
+  have run are not evident.
+- Use British English in review comments and suggested text.
+
+## Repository-Specific Review Checks
+
+### Architecture And Package Boundaries
+
+- Preserve the separation between provider-agnostic packages and EF Core
+  or provider-specific implementations.
+- Do not allow EF Core types, provider-specific behaviour, or migration
+  concerns to leak into abstractions intended to stay
+  provider-agnostic.
+- Keep changes targeted. Flag repo-wide refactors unless the task
+  clearly requires cross-package changes.
+- When shared abstractions, DI registration, or common extension points
+  change, review downstream impact across core packages, provider
+  packages, integration-testing packages, and `samples/SampleApp`.
+- Protect business-facing abstractions from architecture drift.
+
+### Generic Repository And Unit Of Work Usage
+
+- Consumers should use the narrowest repository interface that satisfies
+  the use case.
+- `IUnitOfWork` should be introduced only when multiple entity types or
+  explicit transaction control are required.
+- Complex reusable query logic should prefer the Specification pattern
+  rather than duplicated inline LINQ or unnecessary `IQueryable`
+  exposure.
+- Flag repository changes that weaken typed IDs, blur read/write
+  separation, or make transaction boundaries unclear.
+
+### Domain Model Expectations
+
+- Entities should remain simple POCO classes, not business-logic
+  containers.
+- Entities should implement the appropriate `Ploch.Data.Model`
+  interfaces such as `IHasId<TId>`, `INamed`, `IHasDescription`, audit
+  interfaces, or hierarchy interfaces instead of re-declaring common
+  concepts ad hoc.
+- Category and tag entities should use the provided base types rather
+  than custom reimplementations.
+- Navigation properties, audit properties, nullability, and collection
+  defaults should match existing patterns.
+
+### EF Core And Data-Project Conventions
+
+- `DbContext` configuration should use
+  `ApplyConfigurationsFromAssembly`; do not move entity configuration
+  inline into the context.
+- Keep one internal configuration class per entity.
+- Delete behaviour must be explicit; do not rely on EF Core defaults for
+  important relationships.
+- Enum persistence should stay readable and consistent, typically
+  string-based where the repository already expects that.
+- Provider-specific migrations belong only in provider-specific
+  projects, not in the base data project.
+- Generated migration files and snapshots should not be manually edited
+  without a strong reason.
+
+### Public API And Compatibility
+
+- Review all public surface changes as potential breaking changes,
+  including public types, methods, properties, constructors,
+  interfaces, DI registration surface, configuration keys, package IDs,
+  serialised or persisted state, and migration behaviour.
+- If behaviour or public API changed, expect corresponding documentation
+  updates and, for user-visible changes, release notes updates.
+- Maintain backwards compatibility for stored state. If stored schema or
+  persisted behaviour changes, ensure the change is deliberate and
+  migration-safe.
+- Flag silent behavioural changes even when signatures stay the same.
+
+### SampleApp Consumer Safety
+
+- Treat `samples/SampleApp` as an external consumer of published
+  packages.
+- Never allow manual `PackageReference` to `ProjectReference` swaps in
+  SampleApp `.csproj` files.
+- SampleApp build configuration must remain self-contained and must not
+  import parent repository build configuration, other than the existing
+  conditional `ProjectReferences.props` mechanism.
+- If new Ploch.Data packages are added, ensure `ProjectReferences.props`
+  is updated.
+- If published package versions change, ensure
+  `samples/SampleApp/Directory.Packages.props` stays correct.
+- Flag any change that would make the sample app work only in solution
+  mode but not as a standalone consumer.
+
+## Testing And Validation
+
+- New behaviour, bug fixes, and regression-prone refactors should come
+  with tests.
+- When behaviour crosses repositories, EF Core mappings, DI
+  registration, or provider selection, expect broader verification than
+  a single unit test.
+- Tests should follow repository conventions: xUnit v3,
+  FluentAssertions, AutoFixture where helpful, observable behaviour over
+  implementation details, positive and negative cases, and names such as
+  `MethodName_should_explain_what_it_should_do`.
+- Integration tests are preferred when a change spans repositories,
+  EF Core, specifications, or Unit of Work behaviour.
+- If the review cannot confirm appropriate verification, call out the
+  gap explicitly. Relevant validation commands often include:
+- `dotnet build Ploch.Data.slnx`
+- `dotnet test`
+- `dotnet build Ploch.Data.slnx -p:UsePlochProjectReferences=true`
+- `dotnet build Ploch.Data.SampleApp.slnx`
+
+## Documentation And Release Hygiene
+
+- All public types and members should have XML documentation comments
+  with the appropriate tags for the member kind.
+- XML documentation should be clear, accurate, and written in British
+  English.
+- For public methods and non-obvious APIs, expect `<summary>`,
+  `<param>`, `<returns>`, `<exception>`, and `<example>` tags where
+  appropriate.
+- Public API or behaviour changes should be reflected in the relevant
+  markdown documentation in `docs/`, package README content, or other
+  referenced documentation.
+- User-visible features, significant fixes, and breaking changes should
+  update `RELEASE_NOTES.md` or the appropriate change-log material.
+- Flag stale documentation describing removed or renamed APIs.
+
+## Commit Metadata When Visible
+
+- If the proposed commit message is visible to the reviewer, ensure it
+  follows Conventional Commits.
+- Every commit should reference a GitHub issue with `Refs: #<issue>`.
+- Breaking changes should be explicit in both the commit header and the
+  `BREAKING CHANGE:` footer.
+- Do not invent missing issue references. Missing issue linkage should
+  be reported as a process problem.
+
+## Code Quality And Safety Checks
+
+- Prefer minimal, readable, maintainable code over clever or
+  over-engineered solutions.
+- Always build the entire solution using `dotnet build Ploch.Data.slnx` and
+  make sure **there are no new warnings** produced by static code analyzers.
+  If there are, you need to address them. Some of them might be false positive,
+  in this case you can disable them temporarily in code using for example
+  ```csharp
+  #pragma warning disable CA2200 // Rethrow to preserve stack details
+  ...
+  #pragma warning restore CA2200
+  ```
+
+  Keep in mind that there are other ways of disabling those warnings. If this
+  is a false positive in many places, then it might make sense to disable
+  it in `.editorconfig` file.
+  But either way, the golden rule is **THERE MUST NOT BE EVEN A SINGLE NEW WARNING**.
+- Remove dead code, temporary workarounds, debug code, and commented-out
+  implementations unless there is a clear justification.
+- Fail fast on unrecoverable errors. Silent failure, swallowed
+  exceptions, or low-context logging should be treated as review issues.
+- Logging should use appropriate levels and enough context to diagnose
+  failures. Repository-style messages such as `[ModuleName] Message`
+  should be preferred where practical.
+- Handle nullability and optionality explicitly; do not assume non-null
+  values without justification.
+- Avoid nested ternaries and avoid introducing complexity that obscures
+  intent.
+- Never allow real PII, secrets, connection strings, API keys, or other
+  sensitive data to be committed. Test and example data must be fake or
+  anonymised.
+
+## Dependency Review
+
+- Prefer fixed, explicit dependency versions and the centralised package
+  management patterns already used by the repository.
+- For dependency upgrades, expect evidence that changelogs, migration
+  guidance, and downstream impact were considered.
+- Dependency updates that change runtime behaviour, build behaviour, or
+  packaging should trigger corresponding test and documentation
+  scrutiny.
+
+## Do Not Waste Review Bandwidth On
+
+- Formatting or whitespace already enforced by `.editorconfig`,
+  analyzers, or formatters.
+- Generic style opinions that conflict with established repository
+  patterns.
+- Alternative designs that are merely different unless the current
+  change introduces real risk, inconsistency, or maintenance cost.
+- Superficial suggestions that ignore package boundaries,
+  external-consumer behaviour, or repository conventions.
+
+## High-Risk Smells That Should Almost Always Be Called Out
+
+- Provider-specific logic added to provider-agnostic packages.
+- Public API changes without tests, docs, or release note updates.
+- `DbContext` changes without corresponding configuration or migration
+  scrutiny.
+- Repository or Unit of Work changes that obscure transaction boundaries
+  or weaken typed IDs.
+- SampleApp project file edits that bypass the
+  `PackageReference`-to-`ProjectReference` switching mechanism.
+- Changes that only validate one build mode when both standalone and
+  solution-mode consumer behaviour matter.
+- New public members without XML documentation.
+- Behavioural changes merged without explicit verification evidence.
+
+## Final Review Stance
+
+Default to protecting long-term maintainability and external-consumer
+safety. If a change is technically valid but creates architecture drift,
+consumer risk, hidden breakage, or undocumented behaviour, treat it as a
+real review finding rather than a minor note.

.aiassistant/rules/agent.md

@@ -0,0 +1,75 @@
+---
+apply: always
+---
+
+# Agent Behaviour Specification
+
+## Pre-Code Workflow
+
+Before analysing, investigating, or modifying any code:
+
+1. Fetch relevant rules (repo/package + patterns). In Cursor, use `fetch_rules` tool.
+2. Read the README and locate linked spec files and relevant documentation.
+3. Review all relevant specs and docs.
+4. Create a complete TODO list that includes:
+   - Implementation tasks
+   - Automated testing (unit, visual regression, e2e as appropriate)
+   - Manual verification step (e.g. "Manually verify changes in browser", "Test CLI command", "send request via curl")
+   - Updating any snapshots if they exist (e.g. visual regressions will have baseline images)
+
+## When to Stop and Confirm
+
+Stop and ask the user before implementing changes that may violate or need more information to stay compliant around:
+
+- **Legal or regulatory rules:** SCA, PCI-DSS, GDPR.
+- **Security:** Authentication, session handling, encryption, sensitive data.
+- **Business logic:** Permissions, account access, financial limits, payment flows.
+- **Data access:** Queries that could expose PII or sensitive data.
+- **Specification conflicts:** When the request conflicts with linked spec files.
+
+If unsure whether a change falls into these categories, stop and ask.
+
+## Post-Code Workflow
+
+After implementing changes, **before reporting completion**, you MUST complete BOTH:
+
+1. **Automated testing** — Run relevant tests (unit, integration, visual, e2e). Check project-specific rules, `package.json` scripts, or infer from context. Code compilation alone is insufficient. When working with visual regressions, make sure to update snapshots after you're happy with your changes.
+2. **Manual verification** — Verify like a developer or user would. e.g. For web code, use browser MCP tools to navigate to the app, sign in if needed, and visually confirm the change works. For CLI tools, run commands. For APIs, send requests.
+
+**CRITICAL**: Never report completion until BOTH automated AND manual verification pass. If either cannot be performed:
+
+- Explicitly state which verification is blocked and why
+- Ask the user how to proceed
+- Do NOT mark tasks as complete — leave them as "pending verification"
+
+## Pull Requests
+
+- **Complete testing before creating PR:** Finish ALL automated and manual verification BEFORE creating a pull request. A PR signals the work is ready for review.
+- **PR body must follow template:** When creating a PR, read `.github/pull_request_template.md` first (if it exists) and structure the body accordingly. Include ticket links, remove inapplicable sections (e.g. incident links for non-incidents), and add developer testing notes.
+- **Never create a placeholder PR:** Only create a PR when implementation and all verification steps are complete.
+
+### CI Check Gate (Mandatory)
+
+After pushing changes or creating/updating a PR, you **must** monitor CI checks and resolve any failures before considering the work complete:
+
+1. **Observe checks:** After pushing, use `gh pr checks <PR-number> --watch` (or `gh run list` / `gh run view`) to monitor the status of all CI checks (build, test, SonarCloud, etc.).
+2. **On failure — investigate:** If any check fails, retrieve the logs (`gh run view <run-id> --log-failed`) to identify the root cause. Do not guess — read the actual failure output.
+3. **Fix and push:** Make the necessary code changes to resolve the failure, commit with an appropriate conventional commit message, and push again.
+4. **Re-observe:** After pushing the fix, monitor the checks again. Repeat the investigate-fix-push cycle until **all checks pass**.
+5. **PR comments:** After checks pass, also review any automated PR comments (e.g. SonarCloud quality gate, Codacy, bot feedback). If they flag issues that should be addressed, fix those too.
+6. **Only then declare complete:** Work is not done until all CI checks are green and automated PR feedback has been addressed.
+
+**Do not:**
+
+- Ignore or dismiss failing checks.
+- Mark work as complete while checks are still running or failing.
+- Assume a failure is "flaky" without evidence — investigate first.
+- Push multiple speculative fixes without reading the failure logs.
+
+## Standards
+
+- Use British English.
+- Run commands yourself.
+- Clean up after modifications.
+- Use browser MCPs if available when testing web code.
+- **Never amend commits** unless the user explicitly asks. Always create new commits.

.aiassistant/rules/branch-naming.md

@@ -0,0 +1,41 @@
+---
+apply: always
+---
+
+# Branch Naming Standards
+
+## Pattern
+
+```
+<change-type>/<issue-number>-<brief-description>
+```
+
+## Change Types
+
+| Type | When |
+|------|------|
+| `feature` | New feature or capability |
+| `fix` | Bug fix |
+| `chore` | Maintenance, config, housekeeping |
+| `refactor` | Code restructuring without behaviour change |
+| `docs` | Documentation only |
+| `test` | Adding or updating tests only |
+| `perf` | Performance improvement |
+| `ci` | CI/CD pipeline changes |
+| `build` | Build system changes |
+
+## Rules
+
+- `<issue-number>` is the GitHub issue number (digits only, no `#` prefix).
+- `<brief-description>` is lowercase, hyphen-separated, max 5 words. Summarise the change, not the issue title verbatim.
+- Always derive the change type from the nature of the work, not the issue label alone.
+- If the issue has no clear type from labels, infer from the title and description.
+
+## Examples
+
+- `feature/72-dbcontext-creation-lifecycle-plugins`
+- `fix/187-duplicate-entity-concurrent-upsert`
+- `chore/210-nbgv-versioning-fetch-depth`
+- `refactor/205-extract-shared-audit-logic`
+- `docs/215-update-serialization-readme`
+- `test/220-add-repository-edge-case-tests`

.aiassistant/rules/code-quality.md

@@ -0,0 +1,18 @@
+---
+apply: always
+---
+
+# Code Quality Standards
+
+- Write minimal, readable, maintainable code.
+- Split responsibilities across modules following existing conventions.
+- Remove unused code.
+- Minimise state; derive values when possible.
+- Handle all possibilities; don't assume optionality.
+- Error handling: fail fast on unrecoverable errors; no silent failures. Always log. For user-initiated actions, show user feedback.
+- Comments: explain "why" for non-obvious logic.
+- Logging: Use appropriate levels - error for unrecoverable failures, warn for recoverable issues with fallbacks, info for important state changes, debug for logic flow (not spammy). Include context in messages. Format: `[ModuleName] Message`.
+- Maintain backward compatibility for stored state; implement migrations when required.
+- Clean up local data on logout.
+- Avoid nested ternaries.
+- Never commit PII or potential PII to source code (names, emails, phone numbers, addresses, etc.). Use anonymised or fake data for tests and examples.