Lots of clean up

Author: pidster

.github/README.github.md

@@ -9,31 +9,39 @@ This directory contains repository-level configuration and assets that tailor Gi
 
 Audience: maintainers and contributors configuring Copilot or repository automation.
 
+Scope: This README documents the `.github/` directory only. For project-wide overview and concepts, see the root [README.md](../README.md) (especially “Copying Copilot Customisations”).
+
 ### Copying Copilot Customisations
 
-The custom chatmodes, instructions and prompts can be copied into the same directory structure of another repository. Each file has comments that explain the approach, structure and content of each file.
+The custom chat modes, instructions, and prompts are designed to be portable across repositories with the same directory layout. For general guidance and caveats, see the root [README: “Copying Copilot Customisations”](../README.md#7-copying-copilot-customisations).
 
-Each of these files contains **HTML comments** that explain the funtionality, intent and any prompting methods used to reinforce instructions to the AI assistant. **Read the raw source code** to see this information.
+Most files contain **HTML comments** inlined with additional context (functionality, intent, and prompting techniques). View the raw source to see these notes.
 
 ## GitHub Copilot Customisation
 
-The [copilot-instructions.md](copilot-instructions.md) file contains the main instructions for Github Copilot.
+The [copilot-instructions.md](copilot-instructions.md) file contains the main instructions for GitHub Copilot.
+
+It defines mandatory development workflows (branching, commit and PR conventions), coding standards, and review/quality gates using clear, machine-parseable XML-style tags (for example, <CRITICAL_REQUIREMENT/>). Copilot and other AI assistants use these rules to stay consistent with your team’s process.
+
+Key SSOT anchors:
+- Quality & Coverage Policy: [copilot-instructions.md#quality-policy](./copilot-instructions.md#quality-policy)
+- Branching & Workflow, Naming, Commit Conventions: see relevant sections in the same file
 
-It defines mandatory development workflows (branching, commit and PR conventions), coding standards, and review/quality gates using clear, machine-parseable XML-style tags (for example, <CRITICAL_REQUIREMENT/>). Copilot and other AI assistants use these rules to stay consistent with your team’s process. See also:
+See also:
 - Project overview in [README.md](../README.md)
 - Agent context in [AGENTS.md](../AGENTS.md)
 
 ### Custom Chat Modes
 
 - [Custom Chat Modes](./chatmodes/README.md)
 
-Chat Modes provide specialized behaviors in Copilot Chat (e.g., Developer, Code Review, Documentation, Testing, Planner). Each mode documents its persona, process, constraints, and available tools. Pick a mode in Copilot Chat to bias the assistant for the task at hand. Files live under `./chatmodes/` and use the `.chatmode.md` extension.
+Chat Modes provide specialized behaviors in Copilot Chat (e.g., Developer, Code Review, Documentation, Testing, Planner). Each mode documents its persona, process, constraints, and available tools. Files live under `./chatmodes/` and use the `.chatmode.md` extension.
 
 ### Custom Instructions
 
 - [Custom Instructions](./instructions/README.md)
 
-Instruction files are small, focused rule sets with optional frontmatter (e.g., `applyTo`) that scope guidance to specific files or languages. They help Copilot generate code and docs that match project standards. Notable files include:
+Instruction files are small, focused rule sets with optional frontmatter (e.g., `applyTo`) that scope guidance to specific files or languages. They help Copilot generate code and docs that match project standards. Notable files include (SSOTs):
 - `backend.instructions.md` (Java/Python/C# backends)
 - `frontend.instructions.md` (TypeScript/React conventions)
 - `docs.instructions.md` (applies to all `**/*.md`)
@@ -47,7 +55,7 @@ Reusable prompts act like slash commands in Copilot Chat (e.g., `/write-adr`, `/
 
 ## GitHub Actions Customisation
 
-The `./workflows/` folder holds GitHub Actions. It’s currently empty and ready for CI/CD jobs (for example: lint Markdown, validate instruction frontmatter, run tests). Add workflow files as needed following standard GitHub Actions practices.
+The `./workflows/` folder holds GitHub Actions. It’s currently empty and ready for CI/CD jobs (for example: lint Markdown, validate instruction frontmatter, run tests). Add workflow files as needed following standard GitHub Actions practices. Prefer referencing SSOT anchors (e.g., Quality Policy) in validation jobs.
 
 References:
 - GitHub Actions docs: https://docs.github.com/actions

.github/copilot-instructions.md

@@ -108,6 +108,7 @@ AI assistants MUST follow trunk-based development with lightweight, short-lived
 - Commit frequency: Minimum 1 commit per day of active work
 - PR size: Target ≤ 400 lines of code changes per PR
 - Review requirement: At least 1 human reviewer approval required
+ - Review turnaround: Initial review feedback target ≤ 1 business day for typical PRs
 </WORKFLOW_ENFORCEMENT>
 
 <!--
@@ -142,6 +143,7 @@ AI assistants MUST use these exact naming patterns for branches and pull request
 - `refactor/` - Code refactoring without functional changes
 - `test/` - Test additions or modifications
 - `chore/` - Maintenance tasks (dependencies, build scripts)
+ - `plan/` - Planning artifacts and proposals
 
 **Examples:**
 - ✅ `feature/add-user-authentication`
@@ -343,6 +345,51 @@ AI assistants MUST follow these coding standards and reference project-specific
 
 ---
 
+<!--
+==============================================================================
+QUALITY & COVERAGE POLICY SECTION
+==============================================================================
+PURPOSE: Define a single source of truth (SSOT) for test coverage and quality
+targets across the repository. Eliminates conflicting mandates in chat modes.
+REINFORCEMENT TECHNIQUES:
+- Stable HTML anchor for cross-file references
+- Tiered numeric targets with clear enforcement and exception process
+- Directive language (MUST/SHOULD) to enable automation
+==============================================================================
+-->
+
+<a name="quality-policy"></a>
+## Quality & Coverage Policy
+
+Principles:
+- Tiered Targets: Apply realistic thresholds by test type and importance.
+- Quality > Percentage: Prefer meaningful assertions and coverage of error/security paths over chasing a numeric score.
+- Transparency: Exceptions must be explicit and justified in the PR.
+
+Tiered Targets:
+- Core domain logic: target ≥ 95% line/branch coverage
+- Integrations/adapters: target ≥ 85%
+- Generated scaffolds and spikes: opportunistic; may be exempt if tagged and justified in PR
+
+Enforcement:
+- Global threshold: CI fails if overall repository coverage < 90%
+- Module threshold: CI fails if any core module drops below its target (≥ 95%)
+
+Critical Coverage (must be 100%):
+- Hot paths (performance- or user-critical flows)
+- Error and exception paths (including negative and edge-case handling)
+- Security-relevant logic (authn/authz, input validation, data protection)
+
+Exceptions:
+- Use a PR footer section titled "Coverage Exception:" explaining scope, rationale, and risk mitigation
+- Obtain at least one reviewer acknowledgment of the exception in review comments
+
+References:
+- Chat modes (Developer/Tester) MUST reference this section instead of hardcoding numeric targets.
+- Project-specific overrides, if any, MUST be documented here to remain authoritative.
+
+---
+
 <!--
 ==============================================================================
 REPOSITORY OVERVIEW SECTION

.github/instructions/backend.instructions.md

@@ -15,6 +15,21 @@ Follow idiomatic practices for the chosen programming language and framework. Pr
 - **Error Handling**: Implement robust error handling and logging to ensure system stability and ease of debugging.
 - **Configuration Management**: Externalize configuration from code. Use environment variables or configuration files. Do not commit secrets to version control.
 
+<a name="backend-architecture"></a>
+## Architecture & Structure
+
+Adopt a simple, layered architecture to keep boundaries clear and testable:
+- Entry (HTTP/CLI/Queue) → Controller/Handler → Service (business logic) → Repository (data access) → External systems.
+- Keep DTOs separate from domain models; map at edges.
+- Inject dependencies through constructors. Avoid singletons and global state.
+
+Language-specific notes:
+- Spring Boot: Controllers (`@RestController`) → Services (`@Service`) → Repos (`@Repository`). Use packages by feature when helpful.
+- Django: Views/ViewSets → Services (plain modules) → ORM Models/Managers. Keep fat models thin services as needed; avoid business logic in views.
+- ASP.NET Core: Controllers → Services (DI) → Repositories (EF Core). Prefer interfaces for services/repositories for testability.
+
+Testing guidance: unit-test services with fakes; integration-test controllers and repositories. See `.github/copilot-instructions.md#quality-policy` for coverage expectations.
+
 ## Language-Specific Guidelines
 
 ### Java
@@ -32,6 +47,18 @@ Follow idiomatic practices for the chosen programming language and framework. Pr
 5.  **REST APIs**: Use `@RestController` for creating RESTful services and DTOs (Data Transfer Objects) to decouple API contracts from domain models.
 6.  **Security**: Use Spring Security for authentication and authorization.
 
+##### Example: Global Exception Handler (Spring)
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+	@ExceptionHandler(EntityNotFoundException.class)
+	public ResponseEntity<ApiError> handleNotFound(EntityNotFoundException ex) {
+		return ResponseEntity.status(HttpStatus.NOT_FOUND)
+				.body(new ApiError("not_found", ex.getMessage()));
+	}
+}
+```
+
 ### Python
 
 - **Dependency Management**: Use `pip` with `requirements.txt` or a tool like Poetry or Pipenv.
@@ -45,12 +72,42 @@ Follow idiomatic practices for the chosen programming language and framework. Pr
 - **Settings**: Manage settings for different environments carefully (e.g., `settings/base.py`, `settings/dev.py`, `settings/prod.py`).
 - **Security**: Use Django's built-in security features (e.g., CSRF protection, XSS protection).
 
+##### Example: Logging Errors via Middleware (Django)
+```python
+# core/middleware.py
+class ErrorLoggingMiddleware:
+	def __init__(self, get_response):
+		self.get_response = get_response
+
+	def __call__(self, request):
+		return self.get_response(request)
+
+	def process_exception(self, request, exception):
+		import logging
+		logger = logging.getLogger(__name__)
+		logger.exception("Unhandled error", extra={"path": request.path})
+		return None  # let default handlers run
+```
+
+Add to `MIDDLEWARE` in settings to enable.
+
 #### Flask
 
 - **Project Structure**: Use Blueprints to organize larger applications.
 - **ORM**: Use SQLAlchemy with Flask-SQLAlchemy for database interactions.
 - **Configuration**: Use instance folders for configuration.
 
+##### Example: Error Handler (Flask)
+```python
+from flask import Flask, jsonify
+
+app = Flask(__name__)
+
+@app.errorhandler(ValueError)
+def handle_value_error(err):
+	return jsonify({"error": "invalid_input", "message": str(err)}), 400
+```
+
 ### C#/.NET
 
 - **Project Structure**: Follow the standard .NET project structure.
@@ -66,6 +123,19 @@ Follow idiomatic practices for the chosen programming language and framework. Pr
 4.  **API Development**: Use controllers for API endpoints and follow RESTful principles.
 5.  **Security**: Use ASP.NET Core Identity for authentication and authorization.
 
+##### Example: Centralized Exception Handling (ASP.NET Core)
+```csharp
+// In Program.cs
+app.UseExceptionHandler(appError =>
+{
+	appError.Run(async context =>
+	{
+		context.Response.StatusCode = StatusCodes.Status500InternalServerError;
+		await context.Response.WriteAsJsonAsync(new { error = "internal_error" });
+	});
+});
+```
+
 <!-- Removed duplicated placeholder sections to avoid conflicts; guidance above already covers Flask, Django, and ASP.NET Core. -->
 
 ## API Development
@@ -74,9 +144,61 @@ Follow idiomatic practices for the chosen programming language and framework. Pr
 2. **Request/Response Formats**: Follow the API guidelines for request/response formats (e.g., JSON).
 3. **Versioning**: Implement the API versioning strategy defined in the docs to ensure backward compatibility.
 
+Return consistent error shapes (code, message, correlationId) and map exceptions to appropriate status codes. Do not leak stack traces to clients.
+
 ## Performance Optimization
 
 1. **Caching**: Implement caching strategies to reduce database load and improve response times.
 2. **Database Optimization**: Optimize database queries and use indexing where appropriate.
 3. **Asynchronous Processing**: Use asynchronous processing for long-running tasks to improve API responsiveness.
 
+<a name="backend-error-handling"></a>
+## Error Handling
+
+- Fail fast on invalid inputs; validate at boundaries (controllers) and in domain invariants.
+- Map known exception types to stable error responses; emit machine-parsable `code` fields.
+- Use global exception handling (Spring `@ControllerAdvice`, Django middleware, Flask `errorhandler`, ASP.NET Core `UseExceptionHandler`).
+- Log errors with context (no secrets/PII), include correlation/trace IDs, and prefer structured logs (JSON).
+- Tests must cover error and exception paths (see `.github/copilot-instructions.md#quality-policy`).
+
+<a name="backend-observability"></a>
+## Observability
+
+- Logging: structured, leveled logs; include correlation/trace IDs.
+	- Spring: use SLF4J + MDC; Micrometer for metrics (`@Timed`).
+	- Python: stdlib `logging` with structured formatter; expose health endpoints.
+	- .NET: `ILogger<T>` with scopes; OpenTelemetry exporters for traces/metrics.
+- Metrics: instrument hot paths, DB calls, external requests; standard RED/USE metrics.
+- Tracing: propagate trace headers (W3C TraceContext). Use OpenTelemetry SDKs where available.
+
+Examples:
+```java
+// Spring: add correlation ID to MDC
+try (MDC.MDCCloseable c = MDC.putCloseable("correlationId", cid)) {
+	log.info("Processing request");
+}
+```
+
+```csharp
+// .NET: log scope with correlation id
+using (logger.BeginScope(new Dictionary<string, object>{{"correlationId", cid}}))
+{
+		logger.LogInformation("Processing request");
+}
+```
+
+<a name="backend-security"></a>
+## Security Essentials
+
+- Authentication & Authorization: enforce least privilege; guard all sensitive endpoints.
+- Input validation & output encoding: prevent injection and XSS; use parameterized queries only.
+- Secrets management: never commit secrets; load from env/managed secret stores; rotate regularly.
+- Transport security: enforce HTTPS; set secure headers (HSTS, CSP, X-Frame-Options, X-Content-Type-Options).
+- CSRF/CORS: configure appropriately for web apps and APIs.
+- Dependency hygiene: pin versions; scan with SCA tools; review transitive risks.
+- Data protection: avoid logging PII/secrets; encrypt at rest/in transit where applicable.
+
+References:
+- Branch/PR workflow and conventions: `.github/copilot-instructions.md`.
+- Coverage and critical-path rules: `.github/copilot-instructions.md#quality-policy`.
+

.github/instructions/bdd-tests.instructions.md

@@ -18,6 +18,20 @@ SECTION PURPOSE: Set global conventions for feature files.
 3. Prefer concrete, observable behavior over implementation details.
 4. Keep steps business-readable; avoid UI selectors or technical jargon.
 
+<a name="bdd-naming"></a>
+### Naming & File Structure
+- Filenames: `feature-name.feature` (kebab-case), matching the Feature title slug.
+- Feature titles: imperative, business behavior oriented (e.g., "Sign in to account").
+- Scenario titles: describe outcome (e.g., "Login fails with invalid password").
+- Step definitions: use domain language; keep glue thin and reusable.
+
+<a name="bdd-background-state-tags"></a>
+### Background, State, and Tags
+- Background: only shared, immutable setup. Avoid modifying global state here.
+- State isolation: each scenario sets its own preconditions; no order dependence.
+- Tags: use `@smoke`, `@regression`, `@wip`, `@negative`, `@slow` to group and control execution.
+- Data: prefer Scenario Outline for variations; keep example tables compact and meaningful.
+
 <!--
 SECTION PURPOSE: Define the minimal contract for a good Scenario.
 PROMPTING: Checklist for scenario completeness and clarity.
@@ -28,6 +42,8 @@ PROMPTING: Checklist for scenario completeness and clarity.
 - Steps follow Given-When-Then order; And is used only to add detail.
 - Preconditions are explicit; no hidden state from previous scenarios.
 - Data examples: use Scenario Outline when testing variations.
+- Avoid hidden UI details and timing assumptions; assert observable outcomes.
+- Keep nouns/verbs consistent across features.
 
 <!--
 SECTION PURPOSE: Enforce machine-checkable constraints to keep specs healthy.
@@ -67,6 +83,50 @@ Feature: User login
       | alice    | wrong    |
       | bob      | bad      |
 
+<a name="bdd-good-vs-bad"></a>
+## Good vs Bad Scenarios
+
+Example 1: Clear, behavior-focused vs UI-coupled
+
+Good:
+```
+Scenario: Add item to cart updates total
+  Given a priced item exists
+  And my cart is empty
+  When I add the item to my cart
+  Then my cart total should equal the item price
+```
+
+Bad:
+```
+Scenario: Click add button updates total
+  Given I click the button with id "#add-btn"
+  And I wait 3 seconds
+  Then the element ".total" text should be "$9.99"
+```
+
+Example 2: Single outcome vs multiple assertions
+
+Good:
+```
+Scenario: Payment declined shows error
+  Given my card is blocked
+  When I attempt to pay
+  Then I should see a decline message
+```
+
+Bad:
+```
+Scenario: Payment declined does many things
+  Given my card is blocked
+  When I attempt to pay
+  Then I should see a decline message
+  And my order is cancelled
+  And my basket is emptied
+  And an email is sent
+```
+Rationale: Split into separate scenarios to keep each focused and reliable.
+
 <!--
 SECTION PURPOSE: Encourage living docs and CI-ready behavior.
 -->
@@ -76,3 +136,5 @@ SECTION PURPOSE: Encourage living docs and CI-ready behavior.
 2. Implement the step definitions minimally to pass.
 3. Add edge case scenarios and Scenario Outlines; keep steps reusable.
 4. Wire into CI to run on PRs and gate merges on failures.
+5. Tag scenarios appropriately and configure CI to run fast suites on PRs (e.g., `@smoke`) and full suites nightly.
+6. Keep step definitions DRY; refactor when duplication creeps in.

.github/instructions/docs.instructions.md

@@ -161,6 +161,7 @@ Prompting techniques: Concise quality checklist that is easy to verify automatic
 Purpose: Visualize the documentation workflow and decision points.
 Prompting techniques: Mermaid diagram with loopbacks and explicit approval gate to reinforce process.
 -->
+<a name="documentation-process-flow"></a>
 ## Documentation Process (Flow)
 
 ```mermaid

AGENTS.md

@@ -13,6 +13,7 @@ This file provides general instructions and context for all AI agents working in
 - Use this file to understand the project’s goals, structure, and best practices.
 - Reference configuration and documentation files for deeper context.
 - For Copilot-specific instructions, see `.github/copilot-instructions.md`.
+- Authoritative workflow rules (branching, commits, PRs, coverage policy) live in `.github/copilot-instructions.md` — link to it instead of duplicating.
 - Other AI Agents should consider `.github/copilot-instructions.md` as informative, but not supersede their own custom instruction files, if present.
 - It's critical to stop and alert the user if an AI finds conflicting instructions.
 - The assistant must never use emoji's to decorate its responses to the user
@@ -24,4 +25,4 @@ This file provides general instructions and context for all AI agents working in
 - Agent todo items MUST be maintained as a Markdown checkbox list only in `plans/TODO.md`, not in any other agent-specific file.
 - Source code will be stored in the `src` directory.
 
-This file may repeat some context from other docs to ensure agents have the information they need.
+This file intentionally stays minimal; prefer linking to SSOT docs (see `README.md` Appendix: SSOT Source Map) over copying content.