agents-cli-automation 1.0.19 → 1.0.21

package/src/templates/playwright-agent-api-db-ui.md

@@ -0,0 +1,2989 @@
+# Playwright Test Automation Framework
+
+**Name:** Playwright Agent - TypeScript Test Automation Framework
+
+**Description:** A comprehensive test automation framework built with Playwright and TypeScript for testing UI, API, and database layers. This framework demonstrates best practices for organizing test code, managing test data, implementing step definitions with Playwright BDD, and maintaining database state during testing. It provides examples of test-harness clients for database access, API calls, correlation tracking, and fixture management.
+
+---
+
+## BBC Business Context & Requirements
+
+### Scheduling Group Feature Overview
+
+**Business Context:**
+Scheduling Group is a new grouping function that allows Scheduling Teams within an Area to be grouped together. One Scheduling Team can be in more than one Scheduling Group. One Scheduling Group can have one or more Scheduling Teams in it. A Scheduling Team doesn't have to be in a Scheduling Group. Initially, this allows improvements such as presenting the Allocations Menu in a more coherent way and giving permissions to Scheduling Teams more efficiently.
+
+**Key Business Rules:**
+- Area Admin can manage Scheduling Groups only for their assigned Areas
+- System Admin can manage Scheduling Groups across all Areas
+- Scheduling Group Name is editable
+- Area is auto-filled and non-editable after initial selection
+- Allocations Menu: Yes/No toggle (default behavior TBD by business)
+- Associated Scheduling Teams fed from system (multiple teams per group)
+- History tracking required for all changes (audit trail)
+- Notes field for free-text annotations
+- Delete confirmation required with group name
+
+**Column Headings:**
+- **Actions**: Edit, Delete, History
+- **Area**: Non-editable after first choice
+- **Scheduling Group Name**: Editable
+- **Associated Scheduling Teams**: From system (multi-select)
+- **Allocations Menu**: Yes/No with hover tooltip
+- **Notes**: Editable, free text
+- **Last Amended Date**: From system (auto)
+- **Last Amended By**: From system (audit)
+
+### BBC User Stories
+
+| Reference | Role(s) | Function | Benefit |
+|-----------|---------|----------|---------|
+| NP035.01 | Area Admin, System Admin | View list of Scheduling Groups in Area | See which Scheduling Groups already exist |
+| NP035.02 | Area Admin, System Admin | Add NEW Scheduling Group in Area | Provide consistent and up-to-date group list |
+| NP035.03 | Area Admin, System Admin | Edit existing Scheduling Group in Area | Maintain and update group information |
+| NP035.04 | Area Admin, System Admin | Delete existing Scheduling Group in Area | Remove outdated or unnecessary groups |
+| NP035.05 | Area Admin, System Admin | View history of Scheduling Group changes | Track all amendments and audit trail |
+
+### Required Business Outcomes
+
+✅ Area Admin can View, Add, Edit, Delete Scheduling Groups for their Area  
+✅ System Admin can View, Add, Edit, Delete Scheduling Groups across all Areas  
+✅ History of changes available covering all column headings  
+✅ Columns are sortable and filterable  
+✅ Allocations Menu impacts visibility in menus (impacts orphaned teams consideration)  
+✅ Permission validation enforced (Area Admin limited to their areas)  
+✅ Audit trail captures who changed what and when  
+
+---
+
+## Folder Structure
+
+```
+automation-framework/
+├─ package.json
+├─ tsconfig.json
+├─ playwright.config.ts
+├─ .env
+│
+├─ configs/
+│   ├─ projects/
+│   │   ├─ ui.project.ts
+│   │   ├─ api.project.ts
+│   │   ├─ db.project.ts
+│   │   └─ integrated.project.ts
+│   ├─ environments/
+│   └─ global-setup.ts
+│
+├─ scripts/
+│   ├─ seed-db.ts
+│   ├─ reset-db.ts
+│   └─ run-wrapper.ts
+│
+├─ src/
+│   ├─ core/
+│   │   ├─ test-harness/
+│   │   │   ├─ dbClient.ts
+│   │   │   └─ wrapperClient.ts
+│   │   ├─ fixtures/
+│   │   │   └─ context.fixture.ts
+│   │   └─ utils/
+│   │       ├─ logger.ts
+│   │       └─ correlation.ts
+│   │
+│   ├─ modules/
+│   │   ├─ scheduling-group/
+│   │   │   ├─ features/
+│   │   │   │   └─ create-scheduling-group.feature
+│   │   │   ├─ steps/
+│   │   │   │   └─ createSchedulingGroup.steps.ts
+│   │   │   ├─ read-models/
+│   │   │   │   └─ schedule.read.ts
+│   │   │   ├─ queries/
+│   │   │   │   └─ schedule.mutations.ts
+│   │   │   ├─ contracts/
+│   │   │   │   └─ schedule.wrapper.contract.ts
+│   │   │   └─ test-data/
+│   │   │       └─ schedule.seed.ts
+│   │   └─ <future-module>/
+│   │
+│   └─ shared/
+│       ├─ constants/
+│       ├─ types/
+│       └─ data-factory/
+│
+├─ reports/
+└─ README.md
+```
+
+## Environment Configuration
+
+### .env
+
+```bash
+# Database
+DB_HOST=localhost
+DB_PORT=1433
+DB_USER=sa
+DB_PASSWORD=YourStrong@Passw0rd
+DB_NAME=AutomationTestDB
+
+# Wrapper / API
+WRAPPER_URL=http://localhost:4000/test-wrapper
+```
+
+## Core Components
+
+### Playwright Configuration – `playwright.config.ts`
+
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './src/modules',
+  testMatch: '**/*.spec.ts',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { open: 'never', outputFolder: './reports/html' }],
+    ['json', { outputFile: './reports/results.json' }],
+    ['junit', { outputFile: './reports/junit.xml' }],
+    ['list']
+  ],
+  use: {
+    baseURL: process.env.WRAPPER_URL || 'http://localhost:4000',
+    trace: 'on-first-retry',
+  },
+  projects: [
+    {
+      name: 'ui',
+      use: { ...devices['chromium'] },
+      testMatch: '**/ui/**/*.spec.ts',
+    },
+    {
+      name: 'api',
+      use: { baseURL: process.env.WRAPPER_URL || 'http://localhost:4000' },
+      testMatch: '**/api/**/*.spec.ts',
+    },
+    {
+      name: 'db',
+      testMatch: '**/db/**/*.spec.ts',
+    },
+    {
+      name: 'integrated',
+      use: { ...devices['chromium'] },
+      testMatch: '**/integrated/**/*.spec.ts',
+    },
+  ],
+});
+```
+
+**Integration with bddgen:**
+
+- **testDir**: Points to modules directory where bddgen generates step files
+- **testMatch**: Only runs `.spec.ts` files (not `.feature` or `.steps.ts` files)
+- **reporters**: Generates reports compatible with bddgen cucumber reports in `reports/` directory
+- **Complementary Role**: Playwright config handles browser automation and retries; Cucumber/bddgen handle BDD test orchestration
+- **Test Flow**: Feature files → bddgen generates steps → Cucumber runs steps → Playwright handles browser/API actions
+
+
+### TypeScript Configuration – `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "baseUrl": ".",
+    "paths": {
+      "@core/*": ["src/core/*"],
+      "@modules/*": ["src/modules/*"],
+      "@shared/*": ["src/shared/*"],
+      "@fixtures/*": ["src/core/fixtures/*"],
+      "@utils/*": ["src/core/utils/*"],
+      "@test-harness/*": ["src/core/test-harness/*"]
+    }
+  },
+  "include": ["src/**/*", "scripts/**/*", "configs/**/*"],
+  "exclude": ["node_modules", "dist", "reports", "src/modules/**/*.spec.ts"]
+}
+```
+
+## Core Components
+
+### DB Client – `core/test-harness/dbClient.ts`
+
+```typescript
+import { ConnectionPool, config as sqlConfig, Request } from "mssql";
+import dotenv from "dotenv";
+import { logger } from "../utils/logger";
+
+dotenv.config();
+
+let pool: ConnectionPool | null = null;
+
+const getPool = async (): Promise<ConnectionPool> => {
+  if (!pool) {
+    const config: sqlConfig = {
+      user: process.env.DB_USER,
+      password: process.env.DB_PASSWORD,
+      server: process.env.DB_HOST || "localhost",
+      port: parseInt(process.env.DB_PORT || "1433"),
+      database: process.env.DB_NAME,
+      options: {
+        encrypt: true,
+        trustServerCertificate: true,
+        enableKeepAlive: true,
+      },
+      pool: {
+        max: 10,
+        min: 2,
+        idleTimeoutMillis: 30000,
+      },
+    };
+
+    pool = new ConnectionPool(config);
+    await pool.connect();
+    logger.info("Database connection pool established");
+  }
+  return pool;
+};
+
+export const dbClient = {
+  query: async (queryStr: string, params?: Record<string, any>): Promise<any[]> => {
+    try {
+      const connection = await getPool();
+      const request = connection.request();
+
+      if (params) {
+        for (const key in params) {
+          const value = params[key];
+          request.input(key, value);
+        }
+      }
+
+      logger.debug("Executing query", { queryStr, params });
+      const result = await request.query(queryStr);
+      return result.recordset || [];
+    } catch (error) {
+      logger.error("Database query failed", error);
+      throw error;
+    }
+  },
+
+  execute: async (procedureName: string, params?: Record<string, any>): Promise<any> => {
+    try {
+      const connection = await getPool();
+      const request = connection.request();
+
+      if (params) {
+        for (const key in params) {
+          const value = params[key];
+          request.input(key, value);
+        }
+      }
+
+      logger.debug("Executing procedure", { procedureName, params });
+      const result = await request.execute(procedureName);
+      return result;
+    } catch (error) {
+      logger.error("Procedure execution failed", error);
+      throw error;
+    }
+  },
+
+  close: async () => {
+    if (pool) {
+      await pool.close();
+      pool = null;
+      logger.info("Database connection closed");
+    }
+  },
+};
+```
+
+### Wrapper Client / API Layer – `core/test-harness/wrapperClient.ts`
+
+```typescript
+import axios, { AxiosInstance, AxiosResponse } from "axios";
+import { utils } from "../utils/correlation";
+import { logger } from "../utils/logger";
+
+class WrapperClient {
+  private client: AxiosInstance;
+  private baseURL: string;
+
+  constructor(baseURL: string = process.env.WRAPPER_URL || "http://localhost:4000/test-wrapper") {
+    this.baseURL = baseURL;
+    this.client = axios.create({
+      baseURL: this.baseURL,
+      timeout: 30000,
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+  }
+
+  private getHeaders(user?: any): Record<string, string> {
+    const headers: Record<string, string> = {
+      "x-correlation-id": utils.getCorrelationId(),
+    };
+
+    if (user?.id) {
+      headers["x-test-user-id"] = user.id;
+    }
+
+    return headers;
+  }
+
+  async createSchedulingGroup(payload: any, user?: any): Promise<any> {
+    try {
+      logger.info("Creating Scheduling Group via Wrapper API", { payload, user });
+
+      const response: AxiosResponse = await this.client.post(
+        "/scheduling-groups",
+        payload,
+        { headers: this.getHeaders(user) }
+      );
+
+      logger.info("Scheduling Group created successfully", response.data);
+      return response.data;
+    } catch (error: any) {
+      logger.error("Failed to create Scheduling Group", error.response?.data || error.message);
+      throw error;
+    }
+  }
+
+  async getSchedulingGroup(groupId: number, user?: any): Promise<any> {
+    try {
+      logger.info("Getting Scheduling Group", { groupId });
+
+      const response: AxiosResponse = await this.client.get(
+        `/scheduling-groups/${groupId}`,
+        { headers: this.getHeaders(user) }
+      );
+
+      return response.data;
+    } catch (error: any) {
+      logger.error("Failed to get Scheduling Group", error.response?.data || error.message);
+      throw error;
+    }
+  }
+
+  async updateSchedulingGroup(groupId: number, payload: any, user?: any): Promise<any> {
+    try {
+      logger.info("Updating Scheduling Group", { groupId, payload });
+
+      const response: AxiosResponse = await this.client.put(
+        `/scheduling-groups/${groupId}`,
+        payload,
+        { headers: this.getHeaders(user) }
+      );
+
+      return response.data;
+    } catch (error: any) {
+      logger.error("Failed to update Scheduling Group", error.response?.data || error.message);
+      throw error;
+    }
+  }
+
+  async deleteSchedulingGroup(groupId: number, user?: any): Promise<any> {
+    try {
+      logger.info("Deleting Scheduling Group", { groupId });
+
+      const response: AxiosResponse = await this.client.delete(
+        `/scheduling-groups/${groupId}`,
+        { headers: this.getHeaders(user) }
+      );
+
+      return response.data;
+    } catch (error: any) {
+      logger.error("Failed to delete Scheduling Group", error.response?.data || error.message);
+      throw error;
+    }
+  }
+}
+
+export const wrapperClient = new WrapperClient();
+```
+
+### Utilities – `core/utils/correlation.ts`
+
+```typescript
+import { v4 as uuidv4 } from "uuid";
+import { logger } from "./logger";
+
+export const utils = {
+  getCorrelationId: (): string => uuidv4(),
+
+  normalizeTimestamps: (record: any) => {
+    if (record?.createdAt) record.createdAt = "<timestamp>";
+    if (record?.updatedAt) record.updatedAt = "<timestamp>";
+    if (record?.LastAmendedDate) record.LastAmendedDate = "<timestamp>";
+    return record;
+  },
+
+  log: (message: string, data?: any) => {
+    logger.info(message, data);
+  },
+
+  delay: async (milliseconds: number) => {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+  },
+
+  retry: async (fn: () => Promise<any>, retries: number = 3, delay: number = 1000) => {
+    let lastError;
+    for (let i = 0; i < retries; i++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+        logger.warn(`Retry attempt ${i + 1} failed, waiting ${delay}ms before next attempt`);
+        await utils.delay(delay);
+      }
+    }
+    throw lastError;
+  }
+};
+```
+
+### Logger – `core/utils/logger.ts`
+
+```typescript
+export const logger = {
+  info: (message: string, data?: any) => {
+    console.log(`[${new Date().toISOString()}] [INFO] ${message}`, data ? JSON.stringify(data) : "");
+  },
+
+  error: (message: string, error?: any) => {
+    console.error(`[${new Date().toISOString()}] [ERROR] ${message}`, error ? JSON.stringify(error) : "");
+  },
+
+  debug: (message: string, data?: any) => {
+    if (process.env.DEBUG) {
+      console.debug(`[${new Date().toISOString()}] [DEBUG] ${message}`, data ? JSON.stringify(data) : "");
+    }
+  },
+
+  warn: (message: string, data?: any) => {
+    console.warn(`[${new Date().toISOString()}] [WARN] ${message}`, data ? JSON.stringify(data) : "");
+  }
+};
+```
+
+### Fixtures – `core/fixtures/context.fixture.ts`
+
+```typescript
+export interface TestContext {
+  user: any;
+  payload: any;
+  response: any;
+  correlationId: string;
+  groupId?: number;
+  [key: string]: any;
+}
+
+export interface User {
+  id: string;
+  role: string;
+  name?: string;
+}
+
+export const contextProvider = {
+  getCurrentUser: async (): Promise<User> => {
+    return {
+      id: "default-system-admin",
+      role: "System Admin",
+      name: "Test Admin",
+    };
+  },
+
+  getAreaAdminUser: async (): Promise<User> => {
+    return {
+      id: "area-admin-user-1",
+      role: "Area Admin",
+      name: "Area Admin User",
+    };
+  },
+
+  getRegularUser: async (): Promise<User> => {
+    return {
+      id: "regular-user-1",
+      role: "Regular User",
+      name: "Regular Test User",
+    };
+  },
+
+  createTestContext: (): TestContext => {
+    return {
+      user: null,
+      payload: null,
+      response: null,
+      correlationId: "",
+    };
+  },
+
+  setupContextWithUser: async (context: TestContext, userType: "admin" | "area-admin" | "regular" = "admin"): Promise<TestContext> => {
+    switch (userType) {
+      case "area-admin":
+        context.user = await contextProvider.getAreaAdminUser();
+        break;
+      case "regular":
+        context.user = await contextProvider.getRegularUser();
+        break;
+      default:
+        context.user = await contextProvider.getCurrentUser();
+    }
+    return context;
+  },
+};
+```
+
+### Fixture Usage in BDD – How It Works
+
+Fixtures are injected into BDD steps through the **World context**. Here's how the integration works:
+
+```typescript
+// In Before hook - fixtures are initialized
+Before(async function (this: SchedulingGroupWorld) {
+  // contextProvider creates fresh context for each scenario
+  this.context = contextProvider.createTestContext();
+  this.user = await contextProvider.getCurrentUser();
+});
+
+// In Given steps - fixtures are accessed and configured
+Given("an Area Admin user is available", async function (this: SchedulingGroupWorld) {
+  // Use contextProvider to setup specific user type
+  this.user = await contextProvider.getAreaAdminUser();
+  this.context.user = this.user;
+});
+
+// In When/Then steps - use the injected context
+When("the user creates...", async function (this: SchedulingGroupWorld) {
+  // Access context set up by fixtures
+  const groupId = await schedulingGroupMutations.createSchedulingGroupStub(
+    this.context.payload,
+    this.user.id  // user from fixture
+  );
+});
+
+// In After hook - cleanup resources
+After(async function (this: SchedulingGroupWorld) {
+  // Context is automatically cleaned up
+  if (this.groupId) {
+    await schedulingGroupMutations.deleteSchedulingGroupStub(this.groupId);
+  }
+});
+```
+
+**Benefits of This Approach:**
+- ✅ Single source of truth for test data (builders)
+- ✅ Reusable user contexts across scenarios
+- ✅ Automatic lifecycle management (Before/After)
+- ✅ Type-safe context injection (World interface)
+- ✅ Clear separation between setup (fixtures) and execution (steps)
+```
+
+## Test Data & Database
+
+### Test Data Builder – `modules/scheduling-group/test-data/schedule.seed.ts`
+
+```typescript
+export interface SchedulingGroupPayload {
+  name: string;
+  areaId: number;
+  allocationsMenu: boolean;
+  notes: string;
+  teams: number[];
+}
+
+export const schedulingGroupBuilder = {
+  createValid: (): SchedulingGroupPayload => ({
+    name: `MorningNews_${Date.now()}`,
+    areaId: 101,
+    allocationsMenu: true,
+    notes: "Used for weekday planning",
+    teams: [201, 202],
+  }),
+
+  createWithCustomName: (name: string): SchedulingGroupPayload => ({
+    ...schedulingGroupBuilder.createValid(),
+    name,
+  }),
+
+  createWithCustomArea: (areaId: number): SchedulingGroupPayload => ({
+    ...schedulingGroupBuilder.createValid(),
+    areaId,
+  }),
+
+  createWithCustomTeams: (teams: number[]): SchedulingGroupPayload => ({
+    ...schedulingGroupBuilder.createValid(),
+    teams,
+  }),
+
+  createMinimal: (): SchedulingGroupPayload => ({
+    name: `TestGroup_${Date.now()}`,
+    areaId: 101,
+    allocationsMenu: false,
+    notes: "",
+    teams: [],
+  }),
+
+  createWithAllOptions: (overrides?: Partial<SchedulingGroupPayload>): SchedulingGroupPayload => ({
+    ...schedulingGroupBuilder.createValid(),
+    ...overrides,
+  }),
+};
+```
+
+### Read-Models – `modules/scheduling-group/read-models/schedule.read.ts`
+
+```typescript
+import { dbClient } from "@test-harness/dbClient";
+import { logger } from "@utils/logger";
+
+export const schedulingGroupRead = {
+  getByName: async (name: string): Promise<any> => {
+    try {
+      logger.info("Querying SchedulingGroup by name", { name });
+      const result = await dbClient.query(
+        `SELECT * FROM SchedulingGroup WHERE Name = @name`,
+        { name }
+      );
+      return result[0] || null;
+    } catch (error) {
+      logger.error("Failed to get SchedulingGroup by name", error);
+      throw error;
+    }
+  },
+
+  getById: async (id: number): Promise<any> => {
+    try {
+      logger.info("Querying SchedulingGroup by id", { id });
+      const result = await dbClient.query(
+        `SELECT * FROM SchedulingGroup WHERE Id = @id`,
+        { id }
+      );
+      return result[0] || null;
+    } catch (error) {
+      logger.error("Failed to get SchedulingGroup by id", error);
+      throw error;
+    }
+  },
+
+  getTeamsByGroupId: async (groupId: number): Promise<any[]> => {
+    try {
+      logger.info("Querying teams for SchedulingGroup", { groupId });
+      return await dbClient.query(
+        `SELECT * FROM SchedulingGroupTeam WHERE SchedulingGroupId = @groupId`,
+        { groupId }
+      );
+    } catch (error) {
+      logger.error("Failed to get teams for SchedulingGroup", error);
+      throw error;
+    }
+  },
+
+  getHistoryByGroupId: async (groupId: number): Promise<any[]> => {
+    try {
+      logger.info("Querying history for SchedulingGroup", { groupId });
+      return await dbClient.query(
+        `SELECT * FROM SchedulingGroupHistory WHERE SchedulingGroupId = @groupId ORDER BY LastAmendedDate DESC`,
+        { groupId }
+      );
+    } catch (error) {
+      logger.error("Failed to get history for SchedulingGroup", error);
+      throw error;
+    }
+  },
+
+  getAllGroups: async (): Promise<any[]> => {
+    try {
+      logger.info("Querying all SchedulingGroups");
+      return await dbClient.query(`SELECT * FROM SchedulingGroup`);
+    } catch (error) {
+      logger.error("Failed to get all SchedulingGroups", error);
+      throw error;
+    }
+  },
+
+  getByAreaId: async (areaId: number): Promise<any[]> => {
+    try {
+      logger.info("Querying SchedulingGroups by AreaId", { areaId });
+      return await dbClient.query(
+        `SELECT * FROM SchedulingGroup WHERE AreaId = @areaId`,
+        { areaId }
+      );
+    } catch (error) {
+      logger.error("Failed to get SchedulingGroups by AreaId", error);
+      throw error;
+    }
+  },
+};
+```
+
+### DB Stub / Invariants – `modules/scheduling-group/queries/schedule.mutations.ts`
+
+```typescript
+import { dbClient } from "@test-harness/dbClient";
+import { logger } from "@utils/logger";
+import { SchedulingGroupPayload } from "../test-data/schedule.seed";
+
+export const schedulingGroupMutations = {
+  // CREATE: Insert Scheduling Group with full audit trail
+  createSchedulingGroupStub: async (
+    payload: SchedulingGroupPayload,
+    userId: string,
+    correlationId?: string
+  ): Promise<number> => {
+    try {
+      logger.info("Creating SchedulingGroup stub in database", {
+        payload,
+        userId,
+        correlationId,
+      });
+
+      // Validation: Check for duplicate name in same area
+      const duplicate = await dbClient.query(
+        `SELECT COUNT(*) as cnt FROM SchedulingGroup WHERE AreaId = @areaId AND Name = @name`,
+        { areaId: payload.areaId, name: payload.name }
+      );
+      
+      if (duplicate[0]?.cnt > 0) {
+        logger.error("Duplicate SchedulingGroup name in area", { areaId: payload.areaId, name: payload.name });
+        throw new Error(
+          `Scheduling Group with name '${payload.name}' already exists in this Area`
+        );
+      }
+
+      // Validation: Check area exists
+      const area = await dbClient.query(
+        `SELECT Id FROM Area WHERE Id = @areaId`,
+        { areaId: payload.areaId }
+      );
+      if (!area.length) {
+        throw new Error(`Area with ID ${payload.areaId} does not exist`);
+      }
+
+      // Validation: Check all team IDs exist and belong to area
+      if (payload.teams.length > 0) {
+        const teamCount = await dbClient.query(
+          `SELECT COUNT(*) as cnt FROM SchedulingTeam WHERE AreaId = @areaId AND Id IN (${payload.teams.join(
+            ","
+          )})`,
+          { areaId: payload.areaId }
+        );
+        if (teamCount[0]?.cnt !== payload.teams.length) {
+          throw new Error(
+            `One or more team IDs do not exist in Area ${payload.areaId}`
+          );
+        }
+      }
+
+      // Create SchedulingGroup
+      const result = await dbClient.query(
+        `INSERT INTO SchedulingGroup (AreaId, Name, AllocationsMenu, Notes, LastAmendedBy, LastAmendedDate)
+         VALUES (@areaId, @name, @allocationsMenu, @notes, @userId, GETDATE());
+         SELECT SCOPE_IDENTITY() AS Id;`,
+        {
+          areaId: payload.areaId,
+          name: payload.name,
+          allocationsMenu: payload.allocationsMenu,
+          notes: payload.notes,
+          userId,
+        }
+      );
+
+      const groupId = result[0]?.Id;
+      if (!groupId) {
+        throw new Error("Failed to retrieve inserted Scheduling Group ID");
+      }
+      logger.info("SchedulingGroup created with Id", { groupId, correlationId });
+
+      // Link teams to group (many-to-many)
+      for (const teamId of payload.teams) {
+        await dbClient.query(
+          `INSERT INTO SchedulingGroupTeam (SchedulingGroupId, TeamId) VALUES (@groupId, @teamId)`,
+          { groupId, teamId }
+        );
+      }
+      logger.info("Teams linked to SchedulingGroup", {
+        groupId,
+        teamCount: payload.teams.length,
+        correlationId,
+      });
+
+      // Create audit history record
+      await dbClient.query(
+        `INSERT INTO SchedulingGroupHistory (SchedulingGroupId, AreaId, Name, AllocationsMenu, Notes, LastAmendedBy, LastAmendedDate, Operation)
+         VALUES (@groupId, @areaId, @name, @allocationsMenu, @notes, @userId, GETDATE(), 'CREATE')`,
+        {
+          groupId,
+          areaId: payload.areaId,
+          name: payload.name,
+          allocationsMenu: payload.allocationsMenu,
+          notes: payload.notes,
+          userId,
+        }
+      );
+      logger.info("Audit history record created", { groupId, correlationId });
+
+      return groupId;
+    } catch (error) {
+      logger.error("Failed to create SchedulingGroup stub", { error, correlationId });
+      throw error;
+    }
+  },
+
+  // UPDATE: Modify existing Scheduling Group with history tracking
+  updateSchedulingGroupStub: async (
+    groupId: number,
+    payload: Partial<SchedulingGroupPayload>,
+    userId: string,
+    correlationId?: string
+  ): Promise<void> => {
+    try {
+      logger.info("Updating SchedulingGroup stub in database", {
+        groupId,
+        payload,
+        userId,
+        correlationId,
+      });
+
+      // Fetch current state for history
+      const current = await dbClient.query(
+        `SELECT AreaId, Name, AllocationsMenu, Notes FROM SchedulingGroup WHERE Id = @groupId`,
+        { groupId }
+      );
+      if (!current.length) {
+        throw new Error(`SchedulingGroup with ID ${groupId} not found`);
+      }
+
+      const updates: string[] = [];
+      const params: Record<string, any> = { groupId, userId };
+
+      if (payload.name !== undefined) {
+        // Check for duplicate name if changing
+        if (payload.name !== current[0].Name) {
+          const duplicate = await dbClient.query(
+            `SELECT COUNT(*) as cnt FROM SchedulingGroup WHERE AreaId = @areaId AND Name = @name AND Id != @groupId`,
+            { areaId: current[0].AreaId, name: payload.name, groupId }
+          );
+          if (duplicate[0]?.cnt > 0) {
+            throw new Error(
+              `Another Scheduling Group with name '${payload.name}' already exists in this Area`
+            );
+          }
+        }
+        updates.push(`Name = @name`);
+        params.name = payload.name;
+      }
+
+      if (payload.allocationsMenu !== undefined) {
+        updates.push(`AllocationsMenu = @allocationsMenu`);
+        params.allocationsMenu = payload.allocationsMenu;
+      }
+
+      if (payload.notes !== undefined) {
+        updates.push(`Notes = @notes`);
+        params.notes = payload.notes;
+      }
+
+      if (updates.length > 0) {
+        updates.push(`LastAmendedBy = @userId`);
+        updates.push(`LastAmendedDate = GETDATE()`);
+
+        await dbClient.query(
+          `UPDATE SchedulingGroup SET ${updates.join(", ")} WHERE Id = @groupId`,
+          params
+        );
+        logger.info("SchedulingGroup updated", { groupId, correlationId });
+      }
+
+      // Update teams if provided
+      if (payload.teams !== undefined && payload.teams.length >= 0) {
+        // Remove old team mappings
+        await dbClient.query(
+          `DELETE FROM SchedulingGroupTeam WHERE SchedulingGroupId = @groupId`,
+          { groupId }
+        );
+        // Add new team mappings
+        for (const teamId of payload.teams) {
+          await dbClient.query(
+            `INSERT INTO SchedulingGroupTeam (SchedulingGroupId, TeamId) VALUES (@groupId, @teamId)`,
+            { groupId, teamId }
+          );
+        }
+        logger.info("Teams reassigned to SchedulingGroup", {
+          groupId,
+          teamCount: payload.teams.length,
+          correlationId,
+        });
+      }
+
+      // Create audit history record for update
+      const updated = await dbClient.query(
+        `SELECT AreaId, Name, AllocationsMenu, Notes FROM SchedulingGroup WHERE Id = @groupId`,
+        { groupId }
+      );
+
+      await dbClient.query(
+        `INSERT INTO SchedulingGroupHistory (SchedulingGroupId, AreaId, Name, AllocationsMenu, Notes, LastAmendedBy, LastAmendedDate, Operation, ChangeDetails)
+         VALUES (@groupId, @areaId, @name, @allocationsMenu, @notes, @userId, GETDATE(), 'UPDATE', @changes)`,
+        {
+          groupId,
+          areaId: updated[0].AreaId,
+          name: updated[0].Name,
+          allocationsMenu: updated[0].AllocationsMenu,
+          notes: updated[0].Notes,
+          userId,
+          changes: JSON.stringify({ before: current[0], after: updated[0] }),
+        }
+      );
+      logger.info("Audit history record created for update", { groupId, correlationId });
+    } catch (error) {
+      logger.error("Failed to update SchedulingGroup stub", { error, correlationId });
+      throw error;
+    }
+  },
+
+  // DELETE: Remove Scheduling Group with cascade cleanup
+  deleteSchedulingGroupStub: async (
+    groupId: number,
+    userId: string,
+    correlationId?: string
+  ): Promise<void> => {
+    try {
+      logger.info("Deleting SchedulingGroup stub from database", {
+        groupId,
+        userId,
+        correlationId,
+      });
+
+      // Verify group exists
+      const group = await dbClient.query(
+        `SELECT Id, Name FROM SchedulingGroup WHERE Id = @groupId`,
+        { groupId }
+      );
+      if (!group.length) {
+        throw new Error(`SchedulingGroup with ID ${groupId} not found`);
+      }
+
+      // Create audit history record for deletion (soft audit trail)
+      await dbClient.query(
+        `INSERT INTO SchedulingGroupHistory (SchedulingGroupId, AreaId, Name, AllocationsMenu, Notes, LastAmendedBy, LastAmendedDate, Operation)
+         SELECT Id, AreaId, Name, AllocationsMenu, Notes, @userId, GETDATE(), 'DELETE'
+         FROM SchedulingGroup WHERE Id = @groupId`,
+        { groupId, userId }
+      );
+      logger.info("Delete audit history record created", { groupId, correlationId });
+
+      // Delete team mappings (cascade)
+      await dbClient.query(
+        `DELETE FROM SchedulingGroupTeam WHERE SchedulingGroupId = @groupId`,
+        { groupId }
+      );
+      logger.info("Associated teams unlinked", { groupId, correlationId });
+
+      // Delete the group
+      const deleteResult = await dbClient.query(
+        `DELETE FROM SchedulingGroup WHERE Id = @groupId`,
+        { groupId }
+      );
+
+      logger.info("SchedulingGroup deleted successfully", {
+        groupId,
+        groupName: group[0].Name,
+        correlationId,
+      });
+    } catch (error) {
+      logger.error("Failed to delete SchedulingGroup stub", { error, correlationId });
+      throw error;
+    }
+  },
+
+  // Helper: Get list of groups for an area with permission check
+  getGroupsForArea: async (
+    areaId: number,
+    userId: string,
+    userRole: 'SYSTEM_ADMIN' | 'AREA_ADMIN' | 'VIEW_ONLY',
+    correlationId?: string
+  ): Promise<any[]> => {
+    try {
+      // Permission check: AREA_ADMIN can only see their areas, SYSTEM_ADMIN sees all
+      if (userRole === 'AREA_ADMIN') {
+        const hasPermission = await dbClient.query(
+          `SELECT COUNT(*) as cnt FROM AreaPermission WHERE UserId = @userId AND AreaId = @areaId AND PermissionType = 'AREA_ADMIN'`,
+          { userId, areaId }
+        );
+        if (!hasPermission[0]?.cnt) {
+          throw new Error(`Permission denied: Area Admin access to area ${areaId} required`);
+        }
+      }
+
+      const groups = await dbClient.query(
+        `SELECT 
+           sg.Id,
+           sg.AreaId,
+           a.Name as AreaName,
+           sg.Name,
+           sg.AllocationsMenu,
+           sg.Notes,
+           sg.LastAmendedDate,
+           sg.LastAmendedBy,
+           STRING_AGG(CAST(sgt.TeamId AS VARCHAR), ',') as AssociatedTeamIds
+         FROM SchedulingGroup sg
+         JOIN Area a ON sg.AreaId = a.Id
+         LEFT JOIN SchedulingGroupTeam sgt ON sg.Id = sgt.SchedulingGroupId
+         WHERE sg.AreaId = @areaId
+         GROUP BY sg.Id, sg.AreaId, a.Name, sg.Name, sg.AllocationsMenu, sg.Notes, sg.LastAmendedDate, sg.LastAmendedBy
+         ORDER BY sg.LastAmendedDate DESC`,
+        { areaId }
+      );
+
+      logger.info("Retrieved SchedulingGroups for area", {
+        areaId,
+        groupCount: groups.length,
+        correlationId,
+      });
+      return groups;
+    } catch (error) {
+      logger.error("Failed to get groups for area", { error, correlationId });
+      throw error;
+    }
+  },
+
+  // Helper: Get history for a group
+  getGroupHistory: async (groupId: number, correlationId?: string): Promise<any[]> => {
+    try {
+      const history = await dbClient.query(
+        `SELECT 
+           Id,
+           SchedulingGroupId,
+           AreaId,
+           Name,
+           AllocationsMenu,
+           Notes,
+           LastAmendedBy,
+           LastAmendedDate,
+           Operation,
+           ChangeDetails
+         FROM SchedulingGroupHistory
+         WHERE SchedulingGroupId = @groupId
+         ORDER BY LastAmendedDate DESC`,
+        { groupId }
+      );
+
+      logger.info("Retrieved SchedulingGroup history", {
+        groupId,
+        recordCount: history.length,
+        correlationId,
+      });
+      return history;
+    } catch (error) {
+      logger.error("Failed to get group history", { error, correlationId });
+      throw error;
+    }
+  },
+};
+```
+
+## Test Implementation
+
+### 6-Phase Testing Strategy for Scheduling Groups
+
+#### Phase 0 – Preparation (T0)
+
+**Objectives:**
+- Confirm test scope (happy path + permission variants)
+- Capture all business rules and constraints
+- Define seam strategy (DB stubs until API ready)
+- Document user impersonation approach
+
+**Deliverables:**
+1. **Test Scope Document:**
+   - Happy Path: Create Scheduling Group (System Admin, Area Admin perspectives)
+   - Permission Variants: System Admin (allowed all areas), Area Admin (area-restricted), View Only (denied)
+   - Edge Cases: Duplicate names, invalid areas, missing team mappings
+
+2. **Business Rules Checklist:**
+   - Area auto-fill from user's Area Admin permission
+   - Allocations Menu default behavior (currently TBD, document assumption)
+   - History tracks: name, area, teams, allocationsMenu, notes, lastAmendedBy, lastAmendedDate
+   - Delete confirmation message includes group name
+   - Editable vs read-only fields per role
+
+3. **Seam Strategy:**
+   - Until PHP API endpoints exist: Use DB-driven stored procedures or direct inserts
+   - Implement API abstraction layer supporting mock/real swap
+   - Document which table operations trigger audit (SchedulingGroupHistory)
+   - Decide: transaction-per-test (fast rollback) vs truncate+reseed per-suite
+
+#### Phase 1 – Test Environment Bootstrapping (T1)
+
+**Objectives:**
+- Create deterministic seed dataset with fixed IDs
+- Establish user impersonation mechanism
+- Document dependency order
+
+**Seed Dataset Structure:**
+```sql
+-- Stable test data with fixed IDs for reproducibility
+INSERT INTO Area (Id, Name) VALUES
+  (10001, 'Test Area - North'),
+  (10002, 'Test Area - South');
+
+INSERT INTO SchedulingTeam (Id, Name, AreaId) VALUES
+  (20001, 'Morning Team', 10001),
+  (20002, 'Afternoon Team', 10001),
+  (20003, 'Evening Team', 10002),
+  (20004, 'Night Team', 10002);
+
+-- Test users with roles (seeded before test run)
+INSERT INTO [User] (Id, Name, Email, Role) VALUES
+  (30001, 'SystemAdmin Test', 'sysadmin@test.local', 'SYSTEM_ADMIN'),
+  (30002, 'AreaAdmin North', 'areaadmin.north@test.local', 'AREA_ADMIN'),
+  (30003, 'AreaAdmin South', 'areaadmin.south@test.local', 'AREA_ADMIN'),
+  (30004, 'View Only User', 'readonly@test.local', 'VIEW_ONLY');
+
+-- Area permissions for Area Admins
+INSERT INTO AreaPermission (UserId, AreaId, PermissionType) VALUES
+  (30002, 10001, 'AREA_ADMIN'),
+  (30003, 10002, 'AREA_ADMIN');
+
+-- Optional: Pre-existing Scheduling Groups for list/edit/delete tests
+INSERT INTO SchedulingGroup (Id, AreaId, Name, AllocationsMenu, Notes, LastAmendedBy, LastAmendedDate) VALUES
+  (40001, 10001, 'Morning Group - North', 1, 'Groups morning teams in North Area', 30001, GETDATE()),
+  (40002, 10002, 'Evening Group - South', 0, 'Groups evening teams in South Area', 30001, GETDATE());
+```
+
+**User Impersonation Mechanism:**
+- **Primary:** x-test-user-id header (API requests, test-env only)
+- **Fallback:** Seeded DB roles with transaction isolation per test
+- **UI E2E:** SSO bypass for test users (configured in test container)
+
+**Dependency Order:**
+1. Areas created first (base entities)
+2. SchedulingTeams created with AreaId FK
+3. Users created
+4. AreaPermissions assigned
+5. Optional pre-existing SchedulingGroups inserted
+
+#### Phase 2 – API Abstraction & Interim Approach (T1.2 / T3.1)
+
+**Objectives:**
+- Define API client interface
+- Provide DB-driven stubs until real endpoints exist
+- Support correlation tracking and test headers
+
+**API Abstraction Layer:**
+```typescript
+// Until PHP API ready: interface + mock + DB stub implementation
+interface ISchedulingGroupClient {
+  create(payload: CreateSchedulingGroupDTO, userId: string): Promise<CreateResponse>;
+  getById(id: number, userId: string): Promise<SchedulingGroupDTO>;
+  update(id: number, payload: UpdateSchedulingGroupDTO, userId: string): Promise<void>;
+  delete(id: number, userId: string): Promise<void>;
+  list(areaId: number, userId: string): Promise<SchedulingGroupDTO[]>;
+  getHistory(groupId: number, userId: string): Promise<HistoryRecord[]>;
+}
+
+// Implementation: DB-driven (now) → API-driven (when endpoints ready)
+class SchedulingGroupApiClient implements ISchedulingGroupClient {
+  constructor(private mode: 'db-stub' | 'api', private dbClient: any, private httpClient: any) {}
+  
+  async create(payload: CreateSchedulingGroupDTO, userId: string): Promise<CreateResponse> {
+    const correlationId = utils.getCorrelationId();
+    logger.info('Creating SchedulingGroup', { payload, userId, correlationId });
+    
+    if (this.mode === 'db-stub') {
+      // Call stored procedure or direct insert (validates DB behavior now)
+      return await schedulingGroupMutations.createSchedulingGroupStub(payload, userId);
+    } else {
+      // Call real API endpoint (when available)
+      return await this.httpClient.post('/scheduling-groups', payload, {
+        headers: {
+          'x-correlation-id': correlationId,
+          'x-test-user-id': userId
+        }
+      });
+    }
+  }
+  
+  // ... other CRUD methods follow same pattern
+}
+```
+
+**Header Support:**
+- **x-correlation-id**: UUID generated per test for request tracing
+- **x-test-user-id**: User ID for permission validation in test-env (removed in prod)
+
+#### Phase 3 – Seed/Reset Automation (T2)
+
+**Objectives:**
+- Automate deterministic test data setup
+- Implement fast rollback mechanism
+- Document affected tables and cleanup order
+
+**Cleanup Order (Rollback Safe):**
+```typescript
+export const dbCleanup = {
+  resetSchedulingGroupTables: async () => {
+    // Order matters: delete children before parents
+    await dbClient.query(`DELETE FROM SchedulingGroupHistory`);
+    await dbClient.query(`DELETE FROM SchedulingGroupTeam`);
+    await dbClient.query(`DELETE FROM SchedulingGroup`);
+    // Keep Areas, Teams, Users, Permissions for next test
+  },
+  
+  fullReset: async () => {
+    // Only in isolated test suites; use resetSchedulingGroupTables in normal flows
+    await dbClient.query(`DELETE FROM SchedulingGroupHistory`);
+    await dbClient.query(`DELETE FROM SchedulingGroupTeam`);
+    await dbClient.query(`DELETE FROM SchedulingGroup`);
+    await dbClient.query(`DELETE FROM AreaPermission`);
+    await dbClient.query(`DELETE FROM [User]`);
+    await dbClient.query(`DELETE FROM SchedulingTeam`);
+    await dbClient.query(`DELETE FROM Area`);
+  },
+  
+  reseedTestData: async () => {
+    // Re-insert deterministic seed (IDs 10001+, 20001+, etc.)
+    await seedRunner.seed();
+  }
+};
+
+// Pre-test hook
+Before(async function (this: SchedulingGroupWorld) {
+  await dbCleanup.resetSchedulingGroupTables();
+  await dbCleanup.reseedTestData();
+  this.context = contextProvider.createTestContext();
+});
+
+// Post-test hook
+After(async function (this: SchedulingGroupWorld) {
+  if (this.groupId) {
+    await schedulingGroupMutations.deleteSchedulingGroupStub(this.groupId);
+  }
+  // Transaction will auto-rollback if test failed, else commit
+});
+```
+
+**Affected Tables:**
+- `SchedulingGroup` (main table)
+- `SchedulingGroupTeam` (many-to-many junction)
+- `SchedulingGroupHistory` (audit trail)
+- Potentially: `Area`, `SchedulingTeam`, `User` (seeded once, reused)
+- Potentially: `AreaPermission` (for permission tests)
+
+#### Phase 4 – Test Suites & Coverage (T3)
+
+**Objectives:**
+- Build DB-driven smoke tests (now, API pending)
+- Build permission matrix tests (parameterised)
+- Build UI E2E thin-client tests
+- Implement concurrency and negative test cases
+
+**4a. DB-Driven Smoke Test Suite:**
+```typescript
+Feature: Scheduling Group Creation - DB Smoke Tests
+
+  Background:
+    Given the test database is seeded with Areas, Teams, and Users
+    And correlation tracking is enabled
+
+  Scenario: System Admin creates Scheduling Group (happy path)
+    Given System Admin user is available
+    And a valid Scheduling Group payload is prepared with teams [20001, 20002]
+    When the user creates the Scheduling Group via DB stub
+    Then the Scheduling Group should exist in database with correct ID
+    And the allocationsMenu field should default to [TBD: true|false|null]
+    And the history record should capture create event with correct lastAmendedBy
+    And the associated teams should be linked in SchedulingGroupTeam junction table
+    And correlation ID should be logged in audit trail
+
+  Scenario: Area Admin creates Scheduling Group for their Area (permission check)
+    Given Area Admin (North) user is available
+    And Area Admin is assigned to Area [10001]
+    And a valid Scheduling Group payload is prepared for Area 10001
+    When the user creates the Scheduling Group via DB stub
+    Then the Scheduling Group should exist with AreaId = 10001
+    And lastAmendedBy should reflect the Area Admin's ID
+    And history should show Area Admin as the creator
+
+  Scenario: Area Admin cannot create group outside assigned Area (permission denied)
+    Given Area Admin (North) user is available (assigned to Area 10001)
+    And a valid Scheduling Group payload is prepared for Area 10002 (South)
+    When the user attempts to create the Scheduling Group via DB stub
+    Then the create operation should fail with [PermissionDenied | ForeignKeyViolation]
+    And no row should be inserted in SchedulingGroup table
+    And no row should be inserted in SchedulingGroupHistory
+
+  Scenario: Create with duplicate Scheduling Group name in same Area (business rule validation)
+    Given System Admin user is available
+    And a Scheduling Group with name [test-name] already exists in Area 10001
+    And a valid Scheduling Group payload with the same name for Area 10001
+    When the user creates the Scheduling Group via DB stub
+    Then the create operation should fail with [UniquenessViolation | BusinessRuleViolation]
+    And the error message should indicate duplicate name
+    And no new row should be inserted
+
+  Scenario: Create with invalid or missing team IDs (referential integrity)
+    Given System Admin user is available
+    And a valid Scheduling Group payload with non-existent team IDs [99999, 88888]
+    When the user creates the Scheduling Group via DB stub
+    Then the create operation should fail with [ForeignKeyViolation]
+    And no row should be inserted in SchedulingGroupTeam
+
+  Scenario: Edit (Update) existing Scheduling Group
+    Given System Admin user is available
+    And an existing Scheduling Group exists with name [old-name]
+    And a valid update payload with new name [new-name] and different teams
+    When the user updates the Scheduling Group via DB stub
+    Then the database record should reflect new name [new-name]
+    And the allocationsMenu field should be updated if provided
+    And the Notes field should be updated
+    And a new history record should be inserted capturing the change
+    And history should show lastAmendedBy and new lastAmendedDate
+
+  Scenario: Delete existing Scheduling Group
+    Given System Admin user is available
+    And an existing Scheduling Group with ID [40001] exists
+    When the user deletes the Scheduling Group via DB stub
+    Then the row should be removed from SchedulingGroup table
+    And all associated rows in SchedulingGroupTeam should be removed (cascade)
+    And a history record may be retained for audit (TBD: soft delete vs hard delete)
+    And the operation should complete without error
+
+  Scenario: View (Get) list of Scheduling Groups for an Area
+    Given a System Admin user is available
+    And multiple Scheduling Groups exist in Areas [10001, 10002]
+    When the user retrieves the list for Area 10001 via DB query
+    Then the result should include only groups where AreaId = 10001
+    And each result should include column data: name, allocationsMenu, notes, teams, lastAmendedDate, lastAmendedBy
+    And results should be ordered as specified (or default order documented)
+
+  Scenario: View history of changes to a Scheduling Group
+    Given System Admin user is available
+    And a Scheduling Group with multiple historical changes exists
+    When the user retrieves the history for this group
+    Then all history records should be returned in order (newest first)
+    And each record should include: old values (before), new values (after), timestamp, user who changed
+    And column headings should match SchedulingGroup table structure
+```
+
+**4b. Permission Matrix Test Suite (Parameterised):**
+```typescript
+Feature: Scheduling Group Permission Validation
+
+  Scenario Outline: Permission matrix for CRUD operations
+    Given a user with role [<USER_ROLE>]
+    And user is assigned to Area [<USER_AREA>]
+    And a Scheduling Group exists in Area [<GROUP_AREA>]
+    When the user attempts to [<ACTION>] the Scheduling Group
+    Then the operation result should be [<EXPECTED_RESULT>]
+
+    Examples:
+      | USER_ROLE     | USER_AREA | GROUP_AREA | ACTION | EXPECTED_RESULT       |
+      | SYSTEM_ADMIN  | ANY       | 10001      | CREATE | ALLOW                 |
+      | SYSTEM_ADMIN  | ANY       | 10001      | READ   | ALLOW                 |
+      | SYSTEM_ADMIN  | ANY       | 10001      | UPDATE | ALLOW                 |
+      | SYSTEM_ADMIN  | ANY       | 10001      | DELETE | ALLOW                 |
+      | AREA_ADMIN    | 10001     | 10001      | CREATE | ALLOW                 |
+      | AREA_ADMIN    | 10001     | 10001      | READ   | ALLOW                 |
+      | AREA_ADMIN    | 10001     | 10001      | UPDATE | ALLOW                 |
+      | AREA_ADMIN    | 10001     | 10001      | DELETE | ALLOW                 |
+      | AREA_ADMIN    | 10001     | 10002      | CREATE | DENY (Permission)     |
+      | AREA_ADMIN    | 10001     | 10002      | READ   | DENY (Permission)     |
+      | AREA_ADMIN    | 10001     | 10002      | UPDATE | DENY (Permission)     |
+      | AREA_ADMIN    | 10001     | 10002      | DELETE | DENY (Permission)     |
+      | VIEW_ONLY     | ANY       | ANY        | CREATE | DENY (Role)           |
+      | VIEW_ONLY     | ANY       | ANY        | READ   | ALLOW (List only)     |
+      | VIEW_ONLY     | ANY       | ANY        | UPDATE | DENY (Role)           |
+      | VIEW_ONLY     | ANY       | ANY        | DELETE | DENY (Role)           |
+```
+
+**4c. UI E2E Thin-Client Tests:**
+```typescript
+Feature: Scheduling Group UI E2E - Fast Path
+
+  Scenario: Area Admin logs in and creates Scheduling Group via UI
+    Given an Area Admin user with permissions for Area [10001]
+    When the user navigates to Admin > Admins > Scheduling Groups
+    Then the screen should display list of groups for their Area
+    And the "Add" button should be visible
+    When the user clicks "Add" and submits valid group details
+    Then the new group should appear in the grid
+    And the database should contain the new group with correct history
+    And correlation ID from UI request should match DB audit trail
+
+  Scenario: View group history modal opens with audit records
+    Given Area Admin is on Scheduling Groups list
+    And a group with multiple historical changes exists
+    When the user clicks the "History" icon for that group
+    Then a modal should show all amendments: columns, old→new values, timestamp, who
+    And records should be ordered newest first
+    And modal should close without side effects
+```
+
+**4d. Negative & Concurrency Tests:**
+```typescript
+Feature: Scheduling Group Negative & Concurrency
+
+  Scenario: Concurrent creates with same name (race condition)
+    Given two test sessions as System Admin
+    And both prepare identical group names for Area [10001]
+    When both sessions attempt create simultaneously
+    Then one should succeed, one should fail with UniquenessViolation
+    And only one row should exist in SchedulingGroup table
+    And history should show only one create event
+
+  Scenario: Delete while history is being queried (read consistency)
+    Given a group with history records exists
+    When one session deletes the group and another queries its history
+    Then both operations should complete without locks or deadlocks
+    And history should remain queryable (soft delete or cascading logic)
+```
+
+#### Phase 5 – Observability & Correlation (T1.1 / T4)
+
+**Objectives:**
+- Generate and track correlation IDs
+- Implement structured logging
+- Provide test output for fast triage
+
+**Correlation ID Flow:**
+```typescript
+export const utils = {
+  getCorrelationId: (): string => uuidv4(),
+  
+  logWithCorrelation: (correlationId: string, level: 'info'|'error'|'warn', message: string, data?: any) => {
+    // Structured log with correlation context
+    console.log(JSON.stringify({
+      timestamp: new Date().toISOString(),
+      correlationId,
+      level,
+      message,
+      ...data
+    }));
+  }
+};
+
+// In test
+Before(async function (this: SchedulingGroupWorld) {
+  this.context.correlationId = utils.getCorrelationId();
+  logger.info(`Test started with correlation ID: ${this.context.correlationId}`);
+});
+
+// When creating group
+When('the user creates...', async function (this: SchedulingGroupWorld) {
+  utils.logWithCorrelation(
+    this.context.correlationId,
+    'info',
+    'Attempting SchedulingGroup create',
+    { userId: this.user.id, areaId: this.context.payload.areaId }
+  );
+  const result = await apiClient.create(this.context.payload, this.user.id);
+  utils.logWithCorrelation(
+    this.context.correlationId,
+    'info',
+    'SchedulingGroup created',
+    { groupId: result.id, dbRow: await dbClient.query(...) }
+  );
+});
+```
+
+#### Phase 6 – CI & Release (T4)
+
+**Objectives:**
+- Define CI job flow
+- Establish gateways
+- Publish artifacts
+
+**CI Job Flow:**
+```yaml
+# Example GitHub Actions or similar
+name: Scheduling Group Tests
+
+on: [push, pull_request]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    services:
+      mssql:
+        image: mcr.microsoft.com/mssql/server:2019-latest
+        env:
+          SA_PASSWORD: TestPassword123!
+          ACCEPT_EULA: Y
+        options: >-
+          --health-cmd="/opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P TestPassword123! -Q 'SELECT 1'"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 3
+
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+      
+      - name: Install dependencies
+        run: npm install --legacy-peer-deps
+      
+      - name: Reset test database
+        run: npm run reset-db
+        env:
+          DB_HOST: localhost
+          DB_PORT: 1433
+          DB_USER: sa
+          DB_PASSWORD: TestPassword123!
+      
+      - name: Seed test data
+        run: npm run seed-db
+        env:
+          DB_HOST: localhost
+          DB_PORT: 1433
+          DB_USER: sa
+          DB_PASSWORD: TestPassword123!
+      
+      - name: Run API (DB-stub) tests
+        run: npm run bdd -- --tags @critical
+        env:
+          DB_HOST: localhost
+          DB_PORT: 1433
+          DB_USER: sa
+          DB_PASSWORD: TestPassword123!
+      
+      - name: Run UI smoke tests (optional)
+        run: npm run test:ui -- --project=ui
+        if: success()
+      
+      - name: Publish test reports
+        uses: actions/upload-artifact@v3
+        if: always()
+        with:
+          name: test-reports
+          path: reports/
+      
+      - name: Publish Playwright report
+        uses: actions/upload-artifact@v3
+        if: always()
+        with:
+          name: playwright-report
+          path: reports/html/
+```
+
+**Gateway Checks:**
+- ✅ All Phase 4 test suites pass (DB smoke, permission matrix, negative cases)
+- ✅ No destructive DB operations run against non-test environments
+- ✅ Correlation IDs present in logs for all operations
+- ✅ Test reports show repeatability (3 runs, same result)
+- ✅ Code review on test implementations and seed scripts
+
+---
+
+### Playwright BDD Integration Setup – `configs/global-setup.ts`
+
+```typescript
+import { chromium, FullConfig } from "@playwright/test";
+
+async function globalSetup(config: FullConfig) {
+  console.log("Running global setup for Playwright BDD...");
+  
+  // Initialize browser instance for BDD if needed
+  const browser = await chromium.launch();
+  await browser.close();
+  
+  console.log("Global setup completed");
+}
+
+export default globalSetup;
+```
+
+### Playwright BDD Concept
+
+Playwright BDD (Behavior-Driven Development) integrates Gherkin feature files with Playwright tests. This allows writing human-readable test scenarios that map to actual test code.
+
+**Key Benefits:**
+- **Readability**: Feature files are written in plain English using Gherkin syntax
+- **Collaboration**: Non-technical stakeholders can understand test scenarios
+- **Reusability**: Step definitions are reusable across multiple scenarios
+- **Maintainability**: Changes to logic only need to be made in step definitions
+- **Traceability**: Clear mapping between business requirements and test code
+
+**BDD Workflow:**
+1. Write Gherkin feature files describing business scenarios
+2. Define step implementations that map to Gherkin steps
+3. Use `Before` and `After` hooks to manage fixtures and context lifecycle
+4. Steps access shared context (TestContext) injected through BDD World
+5. Steps interact with test clients (DB, API, UI) to execute actions
+6. Assertions verify expected outcomes
+
+**Setting Up BDD with Playwright using bddgen:**
+
+The framework uses `bddgen` to automatically generate BDD step definitions from feature files. Install dependencies:
+
+```bash
+npm install --save-dev @cucumber/cucumber bddgen @cucumber/pretty-formatter
+```
+
+Create a `bddgen.config.js` configuration file in the project root:
+
+```javascript
+// bddgen.config.js
+module.exports = {
+  features: 'src/modules/**/*.feature',
+  steps: 'src/modules/**/steps',
+  language: 'typescript',
+  typescript: true,
+  requireModule: ['ts-node/register'],
+  formatters: {
+    progress: true,
+    html: 'reports/cucumber-report.html',
+    json: 'reports/cucumber-report.json'
+  }
+};
+```
+
+Create a `cucumber.js` configuration file in the project root:
+
+```javascript
+// cucumber.js
+module.exports = {
+  default: {
+    require: ['src/modules/**/*.steps.ts'],
+    requireModule: ['ts-node/register'],
+    format: ['progress', 'html:reports/cucumber-report.html', 'json:reports/cucumber-report.json'],
+    formatOptions: {
+      snippetInterface: 'async-await'
+    }
+  }
+};
+```
+
+**BDD Generation Workflow:**
+
+When running tests, `bddgen` automatically:
+1. Scans feature files in `src/modules/**/*.feature`
+2. Generates corresponding step definitions in `src/modules/**/steps`
+3. Creates TypeScript step stubs based on Gherkin syntax
+4. Integrates with Playwright test configuration
+
+No need to manually write step stubs - `bddgen` creates them automatically from your feature files.
+
+**Key BDD Concepts in This Framework:**
+
+- **World Interface**: Shared context across all steps in a scenario
+- **Before/After Hooks**: Initialize fixtures and cleanup resources
+- **Fixture Injection**: Access contextProvider to setup users and test data
+- **Scenario Isolation**: Each scenario gets fresh context and cleanup
+- **Automatic Step Generation**: bddgen automatically creates step definitions from feature files
+- **Test Pipeline**: Feature → bddgen → Step Definitions → Cucumber.js → Test Execution
+
+### BDD Generation with bddgen – Workflow
+
+**What is bddgen?**
+
+`bddgen` is a command-line tool that automatically generates TypeScript step definitions from Gherkin feature files. Instead of manually writing step stubs, bddgen scans your `.feature` files and creates matching step definitions in TypeScript.
+
+**Workflow:**
+
+```
+1. Create Feature Files
+   └─ src/modules/scheduling-group/features/create-scheduling-group.feature
+
+2. Run: npm run generate:bdd
+   └─ bddgen scans feature files for Given/When/Then steps
+
+3. Auto-generated Step Files
+   └─ src/modules/scheduling-group/steps/createSchedulingGroup.steps.ts
+      (with Before/After hooks, World interface, step stubs)
+
+4. Implement Step Logic
+   └─ Add fixture calls, API/DB operations
+   └─ Add assertions in Then steps
+
+5. Run: npm run bdd
+   └─ cucumber-js executes generated steps from feature files
+   └─ BDD reports generated to reports/ directory
+```
+
+**Configuration – `bddgen.config.js`:**
+
+```javascript
+module.exports = {
+  features: 'src/modules/**/*.feature',           // Where to find feature files
+  steps: 'src/modules/**/steps',                  // Where to generate step files
+  language: 'typescript',                         // Output language
+  typescript: true,                               // Use TypeScript syntax
+  requireModule: ['ts-node/register'],            // Enable TS support
+  formatters: {
+    progress: true,                               // Show progress in console
+    html: 'reports/cucumber-report.html',        // HTML report location
+    json: 'reports/cucumber-report.json'         // JSON report location
+  }
+};
+```
+
+**Generated Step Structure:**
+
+When bddgen processes your feature file, it automatically creates:
+
+```typescript
+// Auto-generated with Before/After hooks
+Before(async function (this: SchedulingGroupWorld) {
+  // Initialization code (you implement this)
+});
+
+After(async function (this: SchedulingGroupWorld) {
+  // Cleanup code (you implement this)
+});
+
+// Auto-generated step stubs from feature file
+Given("an Area Admin user is available", async function (this: SchedulingGroupWorld) {
+  // TODO: Implement this step
+});
+
+When("the user creates the Scheduling Group", async function (this: SchedulingGroupWorld) {
+  // TODO: Implement this step
+});
+
+Then("the result should be successful", async function (this: SchedulingGroupWorld) {
+  // TODO: Implement this step
+});
+```
+
+**Advantages of bddgen:**
+
+✅ **Automatic**: No manual step stub creation
+✅ **Fast**: Generates from feature files in seconds
+✅ **Type-Safe**: Creates TypeScript types from World interfaces
+✅ **Synchronized**: Steps always match feature file structure
+✅ **DRY**: Single source of truth in feature files
+
+**npm Scripts with bddgen:**
+
+```bash
+# Only generate BDD steps
+npm run generate:bdd
+
+# Generate + Run BDD tests
+npm run bdd
+
+# Generate + Run with watch mode
+npm run bdd:watch
+
+# Generate + Run all tests
+npm test
+
+# Generate + Run with debug
+npm run test:debug
+```
+
+**Important:** All test commands automatically call `npm run generate:bdd` before execution, ensuring your step definitions are always up-to-date with your feature files.
+
+### Step Definitions with Fixture Integration – `modules/scheduling-group/steps/createSchedulingGroup.steps.ts`
+
+```typescript
+import { Given, When, Then, Before, After, setDefaultTimeout } from "@cucumber/cucumber";
+import { Browser, BrowserContext, Page } from "@playwright/test";
+import { expect } from "@playwright/test";
+import { wrapperClient } from "@test-harness/wrapperClient";
+import { dbClient } from "@test-harness/dbClient";
+import { schedulingGroupMutations } from "../queries/schedule.mutations";
+import { schedulingGroupRead } from "../read-models/schedule.read";
+import { schedulingGroupBuilder } from "../test-data/schedule.seed";
+import { contextProvider, TestContext } from "@fixtures/context.fixture";
+import { utils } from "@utils/correlation";
+import { logger } from "@utils/logger";
+
+setDefaultTimeout(60 * 1000);
+
+// World interface for BDD context
+interface SchedulingGroupWorld {
+  context: TestContext;
+  user: any;
+  groupId?: number;
+  page?: Page;
+  browser?: Browser;
+  browserContext?: BrowserContext;
+}
+
+// Initialize context before each scenario
+Before(async function (this: SchedulingGroupWorld) {
+  logger.info("Setting up test context for scenario");
+  
+  this.context = contextProvider.createTestContext();
+  this.user = await contextProvider.getCurrentUser();
+  this.groupId = undefined;
+  
+  logger.info("Test context initialized", { user: this.user });
+});
+
+// Cleanup after each scenario
+After(async function (this: SchedulingGroupWorld) {
+  logger.info("Cleaning up test context");
+  
+  if (this.groupId) {
+    try {
+      await schedulingGroupMutations.deleteSchedulingGroupStub(this.groupId);
+      logger.info("Cleaned up created resources", { groupId: this.groupId });
+    } catch (error) {
+      logger.warn("Cleanup failed", error);
+    }
+  }
+  
+  if (this.page) {
+    await this.page.close();
+  }
+  
+  if (this.browserContext) {
+    await this.browserContext.close();
+  }
+});
+
+// Step definitions with fixture injection
+Given("an Area Admin user is available", async function (this: SchedulingGroupWorld) {
+  this.user = await contextProvider.getAreaAdminUser();
+  this.context.user = this.user;
+  
+  logger.info("Area Admin user set up", { user: this.user });
+});
+
+Given("a regular user is available", async function (this: SchedulingGroupWorld) {
+  this.user = await contextProvider.getRegularUser();
+  this.context.user = this.user;
+  
+  logger.info("Regular user set up", { user: this.user });
+});
+
+Given("a valid Scheduling Group payload is prepared", async function (this: SchedulingGroupWorld) {
+  this.context.payload = schedulingGroupBuilder.createValid();
+  
+  utils.log("Payload prepared", this.context.payload);
+});
+
+Given("a minimal Scheduling Group payload is prepared", async function (this: SchedulingGroupWorld) {
+  this.context.payload = schedulingGroupBuilder.createMinimal();
+  
+  utils.log("Minimal payload prepared", this.context.payload);
+});
+
+When("the user creates the Scheduling Group via DB stub", async function (this: SchedulingGroupWorld) {
+  expect(this.context.payload).toBeDefined();
+  expect(this.user).toBeDefined();
+  
+  this.groupId = await schedulingGroupMutations.createSchedulingGroupStub(
+    this.context.payload,
+    this.user.id
+  );
+  
+  this.context.groupId = this.groupId;
+  logger.info("Scheduling Group created via DB stub", { groupId: this.groupId });
+});
+
+When("the user creates the Scheduling Group via API", async function (this: SchedulingGroupWorld) {
+  expect(this.context.payload).toBeDefined();
+  expect(this.user).toBeDefined();
+  
+  this.context.response = await wrapperClient.createSchedulingGroup(
+    this.context.payload,
+    this.user
+  );
+  
+  this.groupId = this.context.response?.id;
+  logger.info("Scheduling Group created via API", { groupId: this.groupId });
+});
+
+Then("the Scheduling Group should exist in the database", async function (this: SchedulingGroupWorld) {
+  expect(this.context.payload).toBeDefined();
+  expect(this.groupId).toBeDefined();
+  
+  const record = await schedulingGroupRead.getById(this.groupId!);
+  
+  expect(record).toBeDefined();
+  expect(record.name).toBe(this.context.payload.name);
+});
+
+Then("the Scheduling Group should exist with correct invariants", async function (this: SchedulingGroupWorld) {
+  expect(this.context.payload).toBeDefined();
+  expect(this.groupId).toBeDefined();
+  
+  const record = await schedulingGroupRead.getByName(this.context.payload.name);
+  const normalized = utils.normalizeTimestamps(record);
+
+  expect(normalized).not.toBeNull();
+  expect(normalized.areaId).toBe(this.context.payload.areaId);
+  expect(normalized.allocationsMenu).toBe(this.context.payload.allocationsMenu);
+  expect(normalized.notes).toBe(this.context.payload.notes);
+
+  const teams = await schedulingGroupRead.getTeamsByGroupId(this.groupId!);
+  expect(teams.length).toBe(this.context.payload.teams.length);
+  expect(teams.map((t: any) => t.TeamId)).toEqual(this.context.payload.teams);
+
+  const history = await schedulingGroupRead.getHistoryByGroupId(this.groupId!);
+  expect(history.length).toBeGreaterThan(0);
+  expect(history[0].LastAmendedBy).toBe(this.user.id);
+});
+
+Then("the {string} should have {int} teams", async function (this: SchedulingGroupWorld, resource: string, expectedCount: number) {
+  expect(this.groupId).toBeDefined();
+  
+  const teams = await schedulingGroupRead.getTeamsByGroupId(this.groupId!);
+  expect(teams.length).toBe(expectedCount);
+});
+```
+
+### Feature File – `modules/scheduling-group/features/scheduling-group-crud.feature`
+
+```gherkin
+Feature: Scheduling Group CRUD Operations - Full Business Coverage
+
+  Background:
+    # Pre-seeded deterministic test data with fixed IDs
+    Given the test database is seeded with:
+      | Areas | AreaId | AreaName           |
+      | 10001 | Test Area - North  |
+      | 10002 | Test Area - South  |
+      | Teams | TeamId | TeamName      | AreaId |
+      | 20001 | Morning Team      | 10001  |
+      | 20002 | Afternoon Team    | 10001  |
+      | 20003 | Evening Team      | 10002  |
+      | Users | UserId | Role         |
+      | 30001 | SYSTEM_ADMIN       |
+      | 30002 | AREA_ADMIN (North) |
+      | 30003 | AREA_ADMIN (South) |
+      | 30004 | VIEW_ONLY          |
+    And correlation tracking is enabled
+
+  # ========== PHASE 4A: DB-DRIVEN SMOKE TESTS ==========
+  
+  Scenario: NP035.02 - System Admin creates new Scheduling Group (happy path)
+    Given System Admin user (30001) is available
+    And Area is set to 10001 (Test Area - North)
+    And a valid Scheduling Group payload with:
+      | Field            | Value              |
+      | Name             | Morning Shift Grp  |
+      | AllocationsMenu  | true               |
+      | Notes            | Groups morning teams for North |
+      | Teams            | [20001, 20002]     |
+    When the user creates the Scheduling Group via DB stub
+    Then the operation should succeed with returned groupId
+    And the SchedulingGroup table should contain:
+      | Column           | Expected Value         |
+      | AreaId           | 10001                  |
+      | Name             | Morning Shift Grp      |
+      | AllocationsMenu  | 1 (true)               |
+      | Notes            | Groups morning teams for North |
+      | LastAmendedBy    | 30001                  |
+    And the SchedulingGroupTeam table should link teams [20001, 20002]
+    And the SchedulingGroupHistory should record:
+      | Operation | Name               | AreaId | LastAmendedBy |
+      | CREATE    | Morning Shift Grp  | 10001  | 30001         |
+    And correlation ID should be captured in log entry
+
+  Scenario: NP035.02 - Area Admin creates Scheduling Group for assigned Area
+    Given Area Admin user (30002) is available and assigned to Area 10001
+    And a valid Scheduling Group payload with:
+      | Field            | Value           |
+      | Name             | Evening Shift   |
+      | AllocationsMenu  | false           |
+      | Notes            | Evening coverage |
+      | Teams            | [20001]         |
+    When the user creates the Scheduling Group via DB stub
+    Then the operation should succeed
+    And the SchedulingGroup should show LastAmendedBy = 30002 (Area Admin user ID)
+    And the SchedulingGroupHistory should record Area Admin (30002) as creator
+
+  Scenario: NP035.02 - Create with duplicate name should fail (business rule)
+    Given System Admin user (30001) is available
+    And a Scheduling Group with name "Duplicate Test" already exists in Area 10001
+    And a valid Scheduling Group payload with same name "Duplicate Test" for Area 10001
+    When the user attempts to create the Scheduling Group via DB stub
+    Then the operation should fail with error message containing "already exists"
+    And no row should be inserted in SchedulingGroup table
+    And no row should be inserted in SchedulingGroupHistory
+    And the database should remain in consistent state
+
+  Scenario: NP035.02 - Create with invalid/missing team IDs should fail (referential integrity)
+    Given System Admin user (30001) is available
+    And a valid Scheduling Group payload with non-existent team IDs [99999, 88888]
+    When the user attempts to create the Scheduling Group via DB stub
+    Then the operation should fail with ForeignKeyViolation error
+    And no row should be inserted in SchedulingGroup table
+
+  Scenario: NP035.02 - Create with invalid Area should fail (referential integrity)
+    Given System Admin user (30001) is available
+    And a valid Scheduling Group payload for non-existent Area 99999
+    When the user attempts to create the Scheduling Group via DB stub
+    Then the operation should fail with error "Area does not exist"
+    And no row should be inserted in SchedulingGroup table
+
+  Scenario: NP035.03 - Area Admin edits Scheduling Group in assigned Area
+    Given Area Admin user (30002) is available and assigned to Area 10001
+    And an existing Scheduling Group with ID 40001 in Area 10001
+    And an update payload with:
+      | Field            | New Value         |
+      | Name             | Updated Group     |
+      | AllocationsMenu  | true              |
+      | Notes            | Updated notes     |
+      | Teams            | [20002]           |
+    When the user updates the Scheduling Group via DB stub
+    Then the database record should reflect:
+      | Column           | Value             |
+      | Name             | Updated Group     |
+      | AllocationsMenu  | 1                 |
+      | Notes            | Updated notes     |
+      | LastAmendedBy    | 30002             |
+    And the SchedulingGroupTeam should now link only [20002]
+    And SchedulingGroupHistory should record UPDATE operation with before/after values
+
+  Scenario: NP035.04 - System Admin deletes Scheduling Group (including cascade cleanup)
+    Given System Admin user (30001) is available
+    And an existing Scheduling Group with ID 40001 and team links [20001, 20002]
+    When the user deletes the Scheduling Group via DB stub
+    Then the SchedulingGroup table should not contain row with ID 40001
+    And the SchedulingGroupTeam table should not contain rows for groupId 40001 (cascade delete)
+    And the SchedulingGroupHistory should retain audit record showing DELETE operation
+    And LastAmendedBy in history should show 30001 (System Admin user)
+
+  Scenario: NP035.01 - View list of Scheduling Groups for an Area
+    Given System Admin user (30001) is available
+    And multiple Scheduling Groups exist:
+      | GroupId | AreaId | Name                  | AllocationsMenu | Teams      |
+      | 40001   | 10001  | Morning Shift         | 1               | [20001]    |
+      | 40002   | 10001  | Afternoon Shift       | 0               | [20002]    |
+      | 40003   | 10002  | Evening Shift - South | 1               | [20003]    |
+    When the user retrieves groups for Area 10001 via DB query
+    Then the result should include only groups with AreaId = 10001: [40001, 40002]
+    And each result should contain all columns:
+      - AreaId, Name, AllocationsMenu, Notes, AssociatedTeamIds, LastAmendedDate, LastAmendedBy
+    And groups should be ordered by LastAmendedDate DESC (newest first)
+
+  Scenario: NP035.05 - View history of changes to a Scheduling Group
+    Given System Admin user (30001) is available
+    And a Scheduling Group with multiple historical changes:
+      | Timestamp | Operation | ChangeDetails          | User  |
+      | T1        | CREATE    | Initial creation       | 30001 |
+      | T2        | UPDATE    | Name changed           | 30002 |
+      | T3        | UPDATE    | AllocationsMenu toggled| 30001 |
+    When the user retrieves history for this group
+    Then history should contain all records in DESC order (newest first):
+      | Timestamp | Operation | User  |
+      | T3        | UPDATE    | 30001 |
+      | T2        | UPDATE    | 30002 |
+      | T1        | CREATE    | 30001 |
+    And each record should include: SchedulingGroupId, AreaId, Name, AllocationsMenu, Notes, LastAmendedBy, LastAmendedDate, Operation
+
+  # ========== PHASE 4B: PERMISSION MATRIX TESTS ==========
+
+  Scenario Outline: Permission matrix - CRUD access by user role and area assignment
+    Given a user with role [<USER_ROLE>]
+    And user is currently assigned to Area [<USER_AREA>]
+    And a Scheduling Group exists in Area [<GROUP_AREA>]
+    When the user attempts to [<ACTION>] the Scheduling Group
+    Then the operation result should be [<EXPECTED_RESULT>]
+    And if denied, the database state should remain unchanged (no side effects)
+
+    Examples:
+      | USER_ROLE   | USER_AREA | GROUP_AREA | ACTION | EXPECTED_RESULT    |
+      | SYSTEM_ADMIN| ANY       | 10001      | CREATE | ALLOW              |
+      | SYSTEM_ADMIN| ANY       | 10001      | READ   | ALLOW              |
+      | SYSTEM_ADMIN| ANY       | 10001      | UPDATE | ALLOW              |
+      | SYSTEM_ADMIN| ANY       | 10001      | DELETE | ALLOW              |
+      | SYSTEM_ADMIN| ANY       | 10002      | CREATE | ALLOW              |
+      | SYSTEM_ADMIN| ANY       | 10002      | DELETE | ALLOW              |
+      | AREA_ADMIN  | 10001     | 10001      | CREATE | ALLOW              |
+      | AREA_ADMIN  | 10001     | 10001      | READ   | ALLOW              |
+      | AREA_ADMIN  | 10001     | 10001      | UPDATE | ALLOW              |
+      | AREA_ADMIN  | 10001     | 10001      | DELETE | ALLOW              |
+      | AREA_ADMIN  | 10001     | 10002      | CREATE | DENY (Permission)  |
+      | AREA_ADMIN  | 10001     | 10002      | READ   | DENY (Permission)  |
+      | AREA_ADMIN  | 10001     | 10002      | UPDATE | DENY (Permission)  |
+      | AREA_ADMIN  | 10001     | 10002      | DELETE | DENY (Permission)  |
+      | VIEW_ONLY   | ANY       | ANY        | CREATE | DENY (Role)        |
+      | VIEW_ONLY   | ANY       | ANY        | UPDATE | DENY (Role)        |
+      | VIEW_ONLY   | ANY       | ANY        | DELETE | DENY (Role)        |
+      | VIEW_ONLY   | ANY       | ANY        | READ   | ALLOW              |
+
+  # ========== PHASE 4C: UI E2E TESTS ==========
+
+  Scenario: UI E2E - Area Admin navigates to Scheduling Groups screen and creates group
+    Given an Area Admin user (30002) authenticated for Area 10001
+    When the user navigates to Admin > Admins > Scheduling Groups
+    Then the screen should load successfully
+    And the user should be presented with:
+      - List of existing Scheduling Groups for Area 10001
+      - Column headers: Actions, Area, Scheduling Group Name, Associated Scheduling Teams, Allocations Menu, Notes, Last Amended Date, Last Amended By
+      - "Add" button (top-right or right-click context menu)
+    When the user clicks "Add" button
+    Then an Add dialog should open with fields:
+      - Area (auto-filled as 10001, non-editable)
+      - Scheduling Group Name (text input, editable)
+      - Associated Scheduling Teams (multi-select dropdown)
+      - Allocations Menu (toggle yes/no, default TBD)
+      - Notes (text area, optional)
+    When the user fills in and submits:
+      | Field                      | Value         |
+      | Scheduling Group Name      | New Test Grp  |
+      | Associated Scheduling Teams| Morning Team  |
+      | Allocations Menu           | Yes           |
+      | Notes                      | Test note     |
+    Then the dialog should close
+    And the new group should appear in the grid immediately
+    And database verification:
+      - SchedulingGroup table contains row with Name = "New Test Grp"
+      - SchedulingGroupTeam links the Morning Team
+      - SchedulingGroupHistory captures CREATE operation
+      - Correlation ID from UI request matches DB audit trail
+
+  Scenario: UI E2E - View history modal shows all amendments
+    Given Area Admin is on Scheduling Groups list
+    And a group with multiple historical changes exists
+    When the user clicks the "History" icon for that group
+    Then a history modal should open displaying:
+      | Column          | Content                |
+      | Timestamp       | ISO datetime           |
+      | Operation       | CREATE / UPDATE / DELETE |
+      | User Changed    | Full name + user ID    |
+      | Change Details  | Old values → New values |
+    And records should be ordered newest first
+    When the user closes the modal
+    Then focus should return to the grid without side effects
+
+  # ========== PHASE 4D: NEGATIVE & CONCURRENCY TESTS ==========
+
+  Scenario: Concurrency - Two creates with identical name (race condition)
+    Given two test sessions both as System Admin (30001)
+    And both sessions prepare identical group:
+      | Field  | Value              |
+      | AreaId | 10001              |
+      | Name   | Concurrent Test    |
+      | Teams  | [20001, 20002]     |
+    When both sessions attempt create simultaneously
+    Then one should succeed with returned groupId
+    And one should fail with error "already exists"
+    And database should contain exactly one row with Name = "Concurrent Test"
+    And SchedulingGroupHistory should record only one CREATE event
+
+  Scenario: Delete while history is being queried (read consistency)
+    Given a group with ID 40005 and history records exists
+    When one session executes DELETE and another queries history concurrently
+    Then both operations should complete without deadlock / timeout
+    And history should remain queryable post-delete (audit trail preserved)
+    And group should be removed from active SchedulingGroup table
+```
+
+## Database Scripts
+
+### Cucumber Configuration – `cucumber.js`
+
+```javascript
+module.exports = {
+  default: {
+    require: ['src/modules/**/*.steps.ts'],
+    requireModule: ['ts-node/register'],
+    format: [
+      'progress',
+      'html:reports/cucumber-report.html',
+      'json:reports/cucumber-report.json'
+    ],
+    formatOptions: {
+      snippetInterface: 'async-await'
+    },
+    parallel: 2,
+    retry: 0,
+    dryRun: false
+  }
+};
+```
+
+## Database Scripts
+
+### Seed Script – `scripts/seed-db.ts`
+
+```typescript
+import { dbClient } from "../src/core/test-harness/dbClient";
+
+async function seed() {
+  await dbClient.query(`INSERT INTO Area(Id, Name) VALUES (101, 'London')`);
+  await dbClient.query(`
+    INSERT INTO SchedulingTeam(Id, Name, AreaId) 
+    VALUES (201,'TeamA',101), (202,'TeamB',101)
+  `);
+  console.log("DB seeded successfully");
+}
+
+seed();
+```
+
+### Reset Script – `scripts/reset-db.ts`
+
+```typescript
+import { dbClient } from "../src/core/test-harness/dbClient";
+
+async function reset() {
+  await dbClient.query(`TRUNCATE TABLE SchedulingGroup`);
+  await dbClient.query(`TRUNCATE TABLE SchedulingGroupTeam`);
+  await dbClient.query(`TRUNCATE TABLE SchedulingGroupHistory`);
+  console.log("DB reset successfully");
+}
+
+reset();
+```
+
+## Package Configuration
+
+### package.json
+
+```json
+{
+  "name": "automation-framework",
+  "version": "1.0.0",
+  "description": "Playwright TypeScript Test Automation Framework",
+  "scripts": {
+    "seed-db": "ts-node scripts/seed-db.ts",
+    "reset-db": "ts-node scripts/reset-db.ts",
+    "apitest": "playwright test --project=api",
+    "uitest": "playwright test --project=ui",
+    "dbtest": "playwright test --project=db",
+    "test": "playwright test --project=integrated",
+    "test:debug": "playwright test --debug",
+    "test:ui": "playwright test --ui",
+    "pretest": "npm run reset-db && npm run seed-db"
+  },
+  "dependencies": {
+    "axios": "^1.7.0",
+    "dotenv": "^16.4.1",
+    "mssql": "^11.0.0",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@cucumber/cucumber": "^10.0.1",
+    "@playwright/test": "^1.47.0",
+    "@types/node": "^20.15.0",
+    "@types/uuid": "^9.0.8",
+    "bddgen": "^1.0.0",
+    "playwright": "^1.47.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.2"
+  }
+}
+```
+
+### Dependencies Overview
+
+#### Production Dependencies
+- **axios** (^1.7.0) - HTTP client for API requests
+- **dotenv** (^16.4.1) - Environment variable management
+- **mssql** (^11.0.0) - MSSQL database connection driver
+- **uuid** (^9.0.1) - UUID generation for correlation IDs
+
+#### Development Dependencies
+- **@playwright/test** (^1.47.0) - Playwright testing framework
+- **@types/node** (^20.15.0) - TypeScript types for Node.js
+- **@types/uuid** (^9.0.8) - TypeScript types for UUID
+- **@cucumber/cucumber** (^10.0.1) - BDD framework for Gherkin integration
+- **bddgen** (^1.0.0) - **⭐ Automatic BDD step generation from feature files**
+- **playwright** (^1.47.0) - Playwright browser automation
+- **ts-node** (^10.9.2) - TypeScript execution engine
+- **typescript** (^5.6.2) - TypeScript compiler
+
+#### What is bddgen?
+`bddgen` automates the creation of TypeScript step definitions from Gherkin feature files. When you run test commands, bddgen:
+1. Scans your `.feature` files
+2. Extracts Given/When/Then steps
+3. Generates TypeScript step definition files with proper types
+4. Creates Before/After hooks and World interface
+5. Eliminates manual step stub creation
+
+### package.json Scripts
+
+```json
+{
+  "scripts": {
+    "seed-db": "ts-node scripts/seed-db.ts",
+    "reset-db": "ts-node scripts/reset-db.ts",
+    "generate:bdd": "bddgen",
+    "apitest": "playwright test --project=api",
+    "uitest": "playwright test --project=ui",
+    "dbtest": "playwright test --project=db",
+    "test": "npm run generate:bdd && playwright test --project=integrated",
+    "test:debug": "npm run generate:bdd && playwright test --debug",
+    "test:ui": "npm run generate:bdd && playwright test --ui",
+    "bdd": "npm run generate:bdd && cucumber-js",
+    "bdd:report": "npm run generate:bdd && cucumber-js --format json:reports/cucumber-report.json",
+    "bdd:watch": "npm run generate:bdd && cucumber-js --watch",
+    "pretest": "npm run reset-db && npm run seed-db"
+  }
+}
+```
+
+## Running Tests
+
+### Complete BDD Testing Workflow with bddgen
+
+**Step-by-Step Execution Flow:**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. SETUP PHASE                                                  │
+│    └─ npm install --legacy-peer-deps                            │
+│    └─ npm run reset-db                                          │
+│    └─ npm run seed-db                                           │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 2. FEATURE FILE CREATION                                        │
+│    └─ Write .feature files in src/modules/**/features/          │
+│    └─ Define Given/When/Then scenarios in Gherkin syntax        │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 3. BDD GENERATION (Automatic or Manual)                         │
+│    └─ npm run generate:bdd                                      │
+│    └─ bddgen scans .feature files                              │
+│    └─ Generates .steps.ts files with step stubs                 │
+│    └─ Creates World interface and Before/After hooks           │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 4. STEP IMPLEMENTATION                                          │
+│    └─ Implement generated step functions                        │
+│    └─ Add fixture calls (contextProvider)                       │
+│    └─ Add API/DB operations                                     │
+│    └─ Add assertions in Then steps                              │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 5. TEST EXECUTION                                               │
+│    └─ npm run bdd (automatic bddgen)                            │
+│    └─ cucumber-js reads .feature files                         │
+│    └─ Executes matching step definitions                        │
+│    └─ Runs Before/After hooks for setup/cleanup               │
+│    └─ Injects World context into step functions                 │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 6. REPORT GENERATION                                            │
+│    └─ HTML report: reports/cucumber-report.html                │
+│    └─ JSON report: reports/cucumber-report.json                │
+│    └─ Progress output in console                                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Typical Test Session:**
+
+```bash
+# 1. Install and setup
+npm install --legacy-peer-deps
+npm run reset-db && npm run seed-db
+
+# 2. Run tests (bddgen runs automatically)
+npm run bdd
+
+# 3. View reports
+open reports/cucumber-report.html
+
+# 4. Watch mode for development
+npm run bdd:watch
+```
+
+### Installation & Setup
+
+1. **Install Dependencies:**
+   ```bash
+   npm install
+   ```
+
+   If you encounter peer dependency warnings or conflicts, use:
+   ```bash
+   npm install --legacy-peer-deps
+   ```
+
+   For a clean installation:
+   ```bash
+   rm -r node_modules package-lock.json
+   npm install
+   ```
+
+2. **Verify Installation:**
+   ```bash
+   npm list
+   ```
+
+3. **Configure Environment:**
+   - Copy or update `.env` file with your database and API credentials
+   - Ensure all required services (Database, API) are accessible
+
+4. **Reset the database:**
+   ```bash
+   npm run reset-db
+   ```
+
+5. **Seed the database:**
+   ```bash
+   npm run seed-db
+   ```
+
+6. **Run Tests:**
+
+   Generate BDD tests from feature files:
+   ```bash
+   npm run generate:bdd
+   ```
+
+   Run all integrated tests (auto-generates BDD):
+   ```bash
+   npm test
+   ```
+
+   Run BDD feature tests (auto-generates BDD):
+   ```bash
+   npm run bdd
+   ```
+
+   Run BDD tests with watch mode (auto-generates BDD):
+   ```bash
+   npm run bdd:watch
+   ```
+
+   Run API tests only:
+   ```bash
+   npm run apitest
+   ```
+
+   Run UI tests only:
+   ```bash
+   npm run uitest
+   ```
+
+   Run DB tests only:
+   ```bash
+   npm run dbtest
+   ```
+
+   Debug tests (auto-generates BDD):
+   ```bash
+   npm run test:debug
+   ```
+
+   Run tests with UI mode (auto-generates BDD):
+   ```bash
+   npm run test:ui
+   ```
+
+7. **View Test Reports:**
+   Check the `reports/` directory for generated reports:
+   - `reports/html/index.html` - Interactive HTML report
+   - `reports/results.json` - JSON test results
+   - `reports/junit.xml` - JUnit XML format for CI/CD
+
+### Troubleshooting Dependency Installation
+
+**Issue: Peer dependency conflicts**
+```bash
+npm install --legacy-peer-deps
+```
+
+**Issue: bddgen not found or failing**
+- Ensure bddgen is installed: `npm install --save-dev bddgen`
+- Verify `bddgen.config.js` exists in project root
+- Check that feature files exist in `src/modules/**/*.feature`
+- Verify `steps` directory exists: `src/modules/**/steps`
+- Clear generated files and regenerate: `npm run generate:bdd`
+
+**Issue: MSSQL connection errors**
+- Ensure MSSQL Server is running and accessible
+- Verify credentials in `.env` file
+- Check firewall settings
+
+**Issue: Playwright browser installation**
+```bash
+npx playwright install
+```
+
+**Issue: TypeScript compilation errors**
+```bash
+npm run test -- --config playwright.config.ts
+```
+
+**Issue: Module not found errors**
+- Ensure `baseUrl` and `paths` are correctly set in `tsconfig.json`
+- Clear TypeScript cache: `rm -rf dist/`
+- Reinstall dependencies: `npm install --legacy-peer-deps`
+
+**Issue: Generated step files not found**
+- Run `npm run generate:bdd` explicitly before tests
+- Verify bddgen output directory matches `cucumber.js` require path
+- Check that feature files have matching step pattern names
+
+### Node & NPM Version Requirements
+
+- **Node.js**: >= 16.x
+- **NPM**: >= 8.x
+- **TypeScript**: 5.6.2
+- **Playwright**: 1.47.0
+
+Check your versions:
+```bash
+node --version
+npm --version
+```
+
+## BDD Best Practices
+
+### Using Fixtures Effectively in BDD
+
+1. **Initialize Fixtures in Before Hooks:**
+   ```typescript
+   Before(async function (this: YourWorld) {
+     this.context = contextProvider.createTestContext();
+     this.user = await contextProvider.getCurrentUser();
+   });
+   ```
+
+2. **Access Fixtures in Given Steps:**
+   ```typescript
+   Given("a specific user type", async function (this: YourWorld) {
+     this.user = await contextProvider.getAreaAdminUser();
+     this.context.user = this.user;
+   });
+   ```
+
+3. **Use Fixtures in When/Then Steps:**
+   ```typescript
+   When("the user performs action", async function (this: YourWorld) {
+     // Access prepared fixture data
+     await action(this.context.payload, this.user);
+   });
+   ```
+
+4. **Cleanup Resources in After Hooks:**
+   ```typescript
+   After(async function (this: YourWorld) {
+     if (this.groupId) {
+       await schedulingGroupMutations.deleteSchedulingGroupStub(this.groupId);
+     }
+   });
+   ```
+
+### Writing Reusable BDD Steps
+
+- **Use parameterized steps** for flexibility:
+  ```typescript
+  Then("the {string} should have {int} items", async function (resource, count) {
+    // Implementation
+  });
+  ```
+
+- **Leverage fixtures for setup** instead of hardcoding values:
+  ```typescript
+  Given("a valid {string} payload", async function (resourceType) {
+    // Use builder based on resourceType
+  });
+  ```
+
+- **Separate concerns** between fixtures and steps:
+  - Fixtures: Create test data, setup users, initialize context
+  - Steps: Execute actions, make assertions
+
+### Avoiding Common BDD Pitfalls
+
+❌ **Don't:** Hardcode test data in steps
+```typescript
+// Bad
+const payload = { name: "HardcodedName", areaId: 101 };
+```
+
+✅ **Do:** Use builders from fixtures
+```typescript
+// Good
+const payload = schedulingGroupBuilder.createValid();
+```
+
+❌ **Don't:** Skip cleanup in After hooks
+```typescript
+// Bad - resources leak between scenarios
+After(async function () {
+  // Empty cleanup
+});
+```
+
+✅ **Do:** Always cleanup created resources
+```typescript
+// Good
+After(async function (this: YourWorld) {
+  if (this.groupId) {
+    await schedulingGroupMutations.deleteSchedulingGroupStub(this.groupId);
+  }
+});
+```
+
+❌ **Don't:** Share state between scenarios
+```typescript
+// Bad - scenarios depend on order
+```
+
+✅ **Do:** Use Before/After hooks for isolation
+```typescript
+// Good - each scenario is independent
+Before(async function () { /* initialize */ });
+After(async function () { /* cleanup */ });
+```
+
+## bddgen Best Practices & Workflow
+
+### Effective bddgen Usage
+
+1. **Feature-First Development:**
+   ```bash
+   # 1. Write feature file
+   cat > src/modules/users/features/user-creation.feature << 'EOF'
+   Feature: User Creation
+     Scenario: Create a new user
+       Given a new user form is ready
+       When the user submits valid data
+       Then a new user should be created
+   EOF
+   
+   # 2. Run bddgen to auto-generate steps
+   npm run generate:bdd
+   
+   # 3. Implement generated step functions
+   # Steps are now in src/modules/users/steps/userCreation.steps.ts
+   ```
+
+2. **Automatic Step Generation Workflow:**
+   ```bash
+   # All these commands auto-run bddgen before execution
+   npm run bdd              # Generate + Run BDD tests
+   npm run test              # Generate + Run all tests
+   npm run bdd:watch        # Generate + Watch for changes
+   npm test:debug           # Generate + Debug mode
+   
+   # Manual generation (if needed)
+   npm run generate:bdd     # Only generate without running tests
+   ```
+
+3. **Always Run Tests with npm Scripts:**
+   ```bash
+   # ✅ Correct - Uses bddgen automatically
+   npm run bdd
+   npm test
+   npm run bdd:watch
+   
+   # ❌ Avoid - Skips bddgen
+   npx cucumber-js
+   npx playwright test
+   ```
+
+4. **Keep Feature Files Synchronized:**
+   - Feature file names should match step file names (e.g., `user-creation.feature` → `userCreation.steps.ts`)
+   - When you rename a feature file, remove old step file and regenerate
+   - Use consistent naming conventions across features and steps
+
+5. **Directory Structure for bddgen:**
+   ```
+   src/modules/
+   ├── scheduling-group/
+   │   ├── features/
+   │   │   └── create-scheduling-group.feature       ← Feature files here
+   │   ├── steps/
+   │   │   └── createSchedulingGroup.steps.ts        ← Generated here
+   │   ├── read-models/
+   │   ├── queries/
+   │   └── test-data/
+   └── users/
+       ├── features/
+       │   └── user-management.feature
+       ├── steps/
+       │   └── userManagement.steps.ts
+       └── ...
+   ```
+
+### bddgen Configuration Best Practices
+
+**Avoid Common Issues:**
+
+❌ **Don't:** Run tests without bddgen
+```bash
+# Bad - steps not generated
+npx cucumber-js src/modules/**/features/*.feature
+```
+
+✅ **Do:** Use npm scripts that include bddgen
+```bash
+# Good - bddgen runs first
+npm run bdd
+```
+
+❌ **Don't:** Manually create step files
+```bash
+# Bad - might not match feature file structure
+# Manually writing src/modules/users/steps/userCreation.steps.ts
+```
+
+✅ **Do:** Let bddgen generate step files
+```bash
+# Good - accurate generation from feature files
+npm run generate:bdd
+```
+
+❌ **Don't:** Put feature files in wrong directory
+```bash
+# Bad - bddgen won't find them
+src/features/my-feature.feature
+```
+
+✅ **Do:** Follow directory structure
+```bash
+# Good - bddgen scans this location
+src/modules/scheduling-group/features/create-scheduling-group.feature
+```
+
+### Troubleshooting bddgen Issues
+
+**Issue: "bddgen command not found"**
+```bash
+# Solution: Install it
+npm install --save-dev bddgen
+```
+
+**Issue: No step files generated**
+- Check feature files exist in `src/modules/**/*.feature`
+- Verify `bddgen.config.js` exists in project root
+- Ensure `steps` directory exists: `src/modules/**/steps`
+- Run: `npm run generate:bdd` with verbose output
+
+**Issue: Generated steps don't match feature**
+- Check feature file has valid Gherkin syntax
+- Verify step text matches exactly (case-sensitive)
+- Remove old step files and regenerate: `npm run generate:bdd`
+
+**Issue: TypeScript errors in generated steps**
+- Verify `tsconfig.json` has correct `paths` configuration
+- Ensure all imports use `@` aliases: `import { logger } from "@utils/logger"`
+- Check that all referenced modules exist
+
+### Test Execution Flow Diagram
+
+```
+User runs: npm run bdd
+        ↓
+   npm scripts/pretest runs
+        ├─ npm run reset-db (clears DB)
+        └─ npm run seed-db (populates test data)
+        ↓
+   npm run generate:bdd executes
+        ├─ Scans src/modules/**/*.feature
+        ├─ Generates src/modules/**/steps/*.steps.ts
+        └─ Creates World interface + Before/After
+        ↓
+   cucumber-js launches
+        ├─ Requires src/modules/**/*.steps.ts
+        ├─ Parses .feature files
+        ├─ Matches steps to definitions
+        └─ Executes Before → Given → When → Then → After
+        ↓
+   Reports generated
+        ├─ reports/cucumber-report.html (visual)
+        └─ reports/cucumber-report.json (data)
+```
+
+## Acceptance Criteria & Implementation Roadmap
+
+### POC Acceptance Criteria (Phase 0-2)
+
+**Must Have:**
+- ✅ Seed runner creates deterministic test data with fixed IDs (Areas, Teams, Users)
+- ✅ Transaction-per-test isolation working (rollback on failure, commit on success)
+- ✅ Single DB-driven Create test (happy path) passes repeatedly 3+ times
+- ✅ Returned groupId matches database insert (invariant assertion)
+- ✅ AllocationMenu, Notes, Team mappings verified in DB post-create
+- ✅ SchedulingGroupHistory audit record created with correct operation + lastAmendedBy
+- ✅ Correlation ID fixture generates UUID and passes through logs
+- ✅ Branch with all Phase 0-1 code committed and CI green
+
+**Nice to Have (Early Velocity):**
+- Area Admin vs System Admin permission test runs (parameterised)
+- Delete operation with cascade cleanup verified
+- One UI E2E smoke test (login → create → assert list)
+
+### Phase-by-Phase Checklist
+
+**Phase 0 Complete When:**
+- [ ] Business rules document signed off (area auto-fill, allocationsMenu default, delete confirmation)
+- [ ] Test scope defined (CRUD + 3 user roles + edge cases)
+- [ ] Seam strategy agreed (DB stubs until API; mock-ready API abstraction)
+- [ ] Impersonation approach decided (header-based or DB role seed)
+
+**Phase 1 Complete When:**
+- [ ] Seed dataset (.sql or ts seed runner) committed
+- [ ] Fixed IDs used throughout (Areas 10001+, Teams 20001+, Users 30001+)
+- [ ] Test container or local DB accepts x-test-user-id header (or DB role assignment works)
+- [ ] Dependency order documented (Area → Team → User → AreaPermission → SchedulingGroup)
+
+**Phase 2 Complete When:**
+- [ ] API abstraction interface defined (ISchedulingGroupClient)
+- [ ] DB-stub implementation of all CRUD methods ready
+- [ ] API client supports x-correlation-id and x-test-user-id headers
+- [ ] Mock and real implementations can be swapped in config/tests
+
+**Phase 3 Complete When:**
+- [ ] Seed runner invoked in pretest hook automatically
+- [ ] resetSchedulingGroupTables(), fullReset() helpers tested
+- [ ] Before/After hooks handle transaction or reseed
+- [ ] Cleanup order verified (history, teams, group) to avoid FK violations
+
+**Phase 4 Complete When:**
+- [ ] All DB-driven smoke test scenarios pass (at least 10 scenarios)
+- [ ] Permission matrix parameterised tests run (18 scenarios × 4 actions)
+- [ ] UI E2E create + history view passes end-to-end
+- [ ] Negative tests (duplicate, missing FK, invalid area) all pass
+- [ ] Concurrency test passes 5+ times without flake
+
+**Phase 5 Complete When:**
+- [ ] Correlation ID generated per test and logged consistently
+- [ ] Request payload, response, and DB query results in structured logs
+- [ ] Logs include timestamp, correlationId, level, message, context
+- [ ] CI artifact includes logs with correlation IDs for triage
+
+**Phase 6 Complete When:**
+- [ ] CI job sequence: reset DB → seed → run tests → publish report
+- [ ] Gate: no merge unless all tests pass + report generated
+- [ ] Gating prevents deploy to prod (DB destructive ops require test env)
+- [ ] Team can run CI locally: `npm run reset-db && npm run seed-db && npm run bdd`
+
+### Next Recommended Single Action
+
+**Implement the seed + transaction fixture and a single DB-driven Create test:**
+
+1. **Create `scripts/seed-db-scheduling-group.ts`** (extends existing seed)
+   ```typescript
+   // Insert fixed-ID deterministic test data
+   // Areas (10001-10009), Teams (20001-20099), Users (30001-30099)
+   // Pre-existing SchedulingGroups for list/edit/delete tests
+   ```
+
+2. **Add Before/After hooks to `step/schedulingGroupCrud.steps.ts`**
+   ```typescript
+   Before(async function() {
+     await dbCleanup.resetSchedulingGroupTables();
+     // transaction starts or test isolation enabled
+   });
+   
+   After(async function() {
+     // cleanup created groups
+     // transaction commits/rollbacks
+   });
+   ```
+
+3. **Implement Phase 4A happy-path scenario:**
+   ```gherkin
+   Scenario: System Admin creates new Scheduling Group (happy path)
+     When the user creates the Scheduling Group via DB stub
+     Then database assertions verify groupId, name, teams, history
+   ```
+
+4. **Run locally:** `npm run bdd -- --tags @critical` (repeat 3x, should pass all 3)
+
+5. **Commit:** All seed, fixture, and first test to a branch; CI should pass
+
+**Estimated Effort:** 4-6 hours (seed setup, transaction wiring, one full scenario + assertions)
+**ROI:** Unblocks remaining 40+ scenarios; validates entire Phase 4 approach
+
+---
+
+## Framework Integration Summary
+
+**bddgen** + **Cucumber** + **Playwright** + **Fixtures** + **6-Phase Strategy** = Enterprise-Grade BDD Test Suite
+
+### How Everything Connects
+
+```
+1. Business Context (BBC)
+   ↓
+2. User Stories (NP035.01-05)
+   ↓
+3. Feature Files (Gherkin scenarios with @tags for phases)
+   ↓
+4. bddgen auto-generates Step Definitions + World interface
+   ↓
+5. Fixtures (contextProvider supplies users, correlation IDs, test data builders)
+   ↓
+6. Step Implementations (call mutations, read-models, API client)
+   ↓
+7. Database Client (parameterized queries, connection pooling, transaction handling)
+   ↓
+8. Mutation Helpers (create, update, delete with full audit + validation)
+   ↓
+9. Seed Runner (deterministic test data with fixed IDs)
+   ↓
+10. Before/After Hooks (cleanup, isolation, correlation context)
+    ↓
+11. Logger + Correlation (structured logs for triage)
+    ↓
+12. CI/CD (reset → seed → run → report)
+    ↓
+13. Acceptance Criteria Met ✅
+```
+
+### Configuration Files Recap
+
+- **`playwright.config.ts`**: Defines projects (ui, api, db, integrated); reporters; baseURL
+- **`tsconfig.json`**: Path aliases (@test-harness, @fixtures, @utils) for clean imports
+- **`bddgen.config.js`**: Scans .feature files, generates .steps.ts with proper structure
+- **`cucumber.js`**: Executes BDD, reports HTML/JSON, supports parallel + async-await
+- **`.env`**: Database and API credentials (test-env safe values)
+- **`package.json`**: Dependencies (mssql, axios, @playwright/test, @cucumber/cucumber, bddgen) + npm scripts
+
+### Key Dependencies When Tests Run
+
+```
+npm run bdd
+  ├─ npm run generate:bdd (bddgen scans features → generates steps)
+  ├─ npm run reset-db (clears SchedulingGroup* tables)
+  ├─ npm run seed-db (inserts deterministic Areas, Teams, Users, SchedulingGroups)
+  ├─ cucumber-js (requires .steps.ts, parses .feature files)
+  │   ├─ Before hook: context fixture setup + transaction start
+  │   ├─ Given/When/Then: call mutations/read-models with user context
+  │   ├─ Then assertions: DB invariant checks + history validation
+  │   └─ After hook: delete test artifacts + transaction rollback/commit
+  └─ Reports generated: reports/cucumber-report.html, .json
+```
+
+---
+
+## Summary
+
+This framework provides a **complete, enterprise-ready testing solution** for the Scheduling Group feature:
+
+✅ **Scope & Business Context**: BBC + 5 user stories fully documented  
+✅ **6-Phase Testing Strategy**: Phase 0-6 with clear deliverables & checklist  
+✅ **Seed Automation**: Deterministic, repeatable test data with fixed IDs  
+✅ **Database Abstraction**: Stubs → API-ready; mutations with audit trails  
+✅ **Permission Validation**: Parameterised matrix covering all role/area combinations  
+✅ **Observability**: Correlation IDs, structured logging, fast triage  
+✅ **BDD Scenarios**: 40+ scenarios covering happy path, edge cases, concurrency, UI  
+✅ **CI/CD Ready**: Reproducible test runs, gated pipeline, artifact publishing  
+✅ **Immediate Action**: Single ROI-high seed + first test provides fast feedback  
+
+**Framework is ready to onboard team and execute Phase 0 kick-off.**