@schilling.mark.a/software-methodology 1.0.0

package/green-implementation/references/common-rejections.md

@@ -0,0 +1,180 @@
+# Common PR Rejections
+
+This file tracks patterns that repeatedly cause PR rejections. Each entry
+comes from actual reviewer feedback captured via `record_pr_feedback` in the
+MCP server. When a pattern appears 3+ times, it gets added here.
+
+Update this file as part of the PDCA Act step. Every entry here should also
+have a corresponding automated rule in `team-standards.json`.
+
+---
+
+## Architecture Violations
+
+### HttpClient in Components
+
+**Frequency:** Very common
+**Rule:** `arch-001`
+
+Reviewers reject any component that imports or injects `HttpClient`.
+All HTTP calls go through services.
+
+```typescript
+// ❌ Always rejected
+import { HttpClient } from '@angular/common/http';
+@Component({ ... })
+export class MyComponent {
+  constructor(private http: HttpClient) {}
+}
+
+// ✅ Fix
+@Component({ ... })
+export class MyComponent {
+  constructor(private myService: MyService) {}
+}
+```
+
+### Business Logic in Component Templates
+
+**Frequency:** Common
+
+Complex expressions in templates are flagged. Move logic to
+component properties or service methods.
+
+```typescript
+// ❌ Rejected — logic in template
+<div *ngIf="users.filter(u => u.role === 'admin' && u.active).length > 0">
+
+// ✅ Fix — computed property
+get hasActiveAdmins(): boolean {
+  return this.users.some(u => u.role === 'admin' && u.active);
+}
+// Template: *ngIf="hasActiveAdmins"
+```
+
+---
+
+## Naming
+
+### Hungarian Notation
+
+**Frequency:** Very common
+**Rule:** `naming-001`
+
+Team uses plain camelCase. Type prefixes (str, arr, int, bool, obj)
+are always flagged.
+
+### Missing Observable Suffix
+
+**Frequency:** Common
+**Rule:** `naming-002`
+
+Any property typed as `Observable<T>` must end with `$`.
+
+---
+
+## Error Handling
+
+### Empty Catch Blocks
+
+**Frequency:** Very common
+**Rule:** `err-001`
+
+Swallowing errors silently is always rejected. Log the error and
+either re-throw or handle it meaningfully.
+
+### switchMap Without catchError
+
+**Frequency:** Common (added after PR feedback)
+**Rule:** `rxjs-001` (if added)
+
+Inner observables in switchMap that don't handle errors kill the
+outer stream. Reviewers flag this because it causes silent failures
+in production that are extremely hard to debug.
+
+---
+
+## Testing
+
+### Raw Selectors in Test Files
+
+**Frequency:** Very common
+**Rule:** `test-001`
+
+Any `page.getByTestId()`, `page.locator()`, or `page.getByRole()` directly
+in a `.spec.ts` file is rejected. All selectors must be in Page Object classes.
+
+### Hard-Coded Test Credentials
+
+**Frequency:** Common
+**Rule:** `test-002`
+
+Hard-coded email addresses, passwords, or API keys in test files are
+always flagged. Use fixtures or test data builders.
+
+### Manual Waits
+
+**Frequency:** Common
+**Rule:** `pw-001`
+
+`page.waitForTimeout()` is always rejected. Use web-first assertions
+that auto-wait.
+
+---
+
+## Security
+
+### console.log in Production Code
+
+**Frequency:** Very common
+**Rule:** `sec-001`
+
+Any `console.log`, `console.warn`, or `console.error` in production
+code (non-test files) is rejected. Use LoggerService.
+
+### innerHTML Assignment
+
+**Frequency:** Occasional
+**Rule:** `sec-002`
+
+Direct `element.innerHTML = ...` creates XSS vulnerabilities.
+Use Angular's `[innerHTML]` binding with DomSanitizer.
+
+---
+
+## Style
+
+### Magic Numbers
+
+**Frequency:** Common
+**Rule:** `style-001`
+
+Numeric literals other than 0, 1, -1 are flagged. Extract to
+named constants.
+
+```typescript
+// ❌ Rejected
+if (retries >= 3) { ... }
+if (items.length > 50) { ... }
+
+// ✅ Fix
+const MAX_RETRIES = 3;
+const MAX_DISPLAY_ITEMS = 50;
+if (retries >= MAX_RETRIES) { ... }
+if (items.length > MAX_DISPLAY_ITEMS) { ... }
+```
+
+---
+
+## Adding New Entries
+
+When a PR is rejected for a pattern not listed here:
+
+1. Call `record_pr_feedback` in the MCP server
+2. Determine if the pattern can be caught by regex → `add_rule`
+3. Add an entry here with:
+   - **Frequency** — how often this has been flagged
+   - **Rule** — the corresponding team-standards.json rule ID
+   - **✅/❌ examples** — concrete code showing right vs wrong
+4. Update the corresponding section in SKILL.md if the summary
+   table doesn't already cover it

package/green-implementation/references/playwright-patterns.md

@@ -0,0 +1,321 @@
+# Playwright & Page Object Model Patterns
+
+## Page Object Structure
+
+### Base Page Object
+
+Every page object extends a base class that provides common utilities.
+
+```typescript
+// tests/helpers/base.page.ts
+import { type Page, type Locator, expect } from '@playwright/test';
+
+export abstract class BasePage {
+  constructor(protected readonly page: Page) {}
+
+  /** Navigate to this page's URL */
+  abstract goto(): Promise<void>;
+
+  /** Assert the page loaded correctly */
+  abstract expectLoaded(): Promise<void>;
+
+  /** Common: wait for Angular stability */
+  protected async waitForAngular(): Promise<void> {
+    await this.page.waitForLoadState('networkidle');
+  }
+}
+```
+
+### Feature Page Object
+
+```typescript
+// tests/helpers/user-list.page.ts
+import { type Page, type Locator, expect } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class UserListPage extends BasePage {
+  // ─── Locators (user-facing preferred) ──────────────
+  readonly heading = this.page.getByRole('heading', { name: 'Users' });
+  readonly searchInput = this.page.getByLabel('Search users');
+  readonly userRows = this.page.getByRole('row').filter({ hasNot: this.page.getByRole('columnheader') });
+  readonly addUserButton = this.page.getByRole('button', { name: 'Add user' });
+  readonly loadingSpinner = this.page.getByTestId('loading-spinner');
+  readonly emptyState = this.page.getByText('No users found');
+  readonly errorBanner = this.page.getByRole('alert');
+  readonly paginationNext = this.page.getByRole('button', { name: 'Next page' });
+
+  constructor(page: Page) {
+    super(page);
+  }
+
+  // ─── Navigation ────────────────────────────────────
+  async goto(): Promise<void> {
+    await this.page.goto('/users');
+    await this.waitForAngular();
+  }
+
+  async expectLoaded(): Promise<void> {
+    await expect(this.heading).toBeVisible();
+  }
+
+  // ─── Actions (named after user intent) ─────────────
+  async searchFor(term: string): Promise<void> {
+    await this.searchInput.fill(term);
+    // Wait for debounced search to complete
+    await this.page.waitForResponse(resp =>
+      resp.url().includes('/api/users') && resp.status() === 200
+    );
+  }
+
+  async selectUser(name: string): Promise<void> {
+    await this.page.getByRole('row').filter({ hasText: name }).click();
+  }
+
+  async goToNextPage(): Promise<void> {
+    await this.paginationNext.click();
+    await this.waitForAngular();
+  }
+
+  // ─── Assertions (high-level, readable) ─────────────
+  async expectUserCount(count: number): Promise<void> {
+    await expect(this.userRows).toHaveCount(count);
+  }
+
+  async expectUserVisible(name: string): Promise<void> {
+    await expect(this.page.getByRole('row').filter({ hasText: name })).toBeVisible();
+  }
+
+  async expectEmptyState(): Promise<void> {
+    await expect(this.emptyState).toBeVisible();
+  }
+
+  async expectError(message: string): Promise<void> {
+    await expect(this.errorBanner).toContainText(message);
+  }
+}
+```
+
+### Rules for Page Objects
+
+1. **Locators are properties, not methods** — declare them in the class body
+2. **Actions are named after user intent** — `searchFor()`, `selectUser()`, not `fillSearchInput()`
+3. **Assertions belong in the PO** — `expectUserCount()`, not raw `expect()` in test files
+4. **No test logic in POs** — no conditionals, no test data creation
+5. **One PO per page/major section** — don't create POs for individual components unless reused across pages
+
+## Test File Structure
+
+### Tests Call Page Object Methods Only
+
+```typescript
+// tests/acceptance/users/user-search.spec.ts
+import { test } from '@playwright/test';
+import { UserListPage } from '../../helpers/user-list.page';
+
+test.describe('User Search', () => {
+  let userList: UserListPage;
+
+  test.beforeEach(async ({ page }) => {
+    userList = new UserListPage(page);
+    await userList.goto();
+    await userList.expectLoaded();
+  });
+
+  test('should filter users by name when searching', async () => {
+    // Given the user list is loaded (beforeEach)
+
+    // When I search for "Mark"
+    await userList.searchFor('Mark');
+
+    // Then I should see only matching users
+    await userList.expectUserVisible('Mark Schilling');
+    await userList.expectUserCount(1);
+  });
+
+  test('should show empty state when no results match', async () => {
+    await userList.searchFor('zzzznonexistent');
+    await userList.expectEmptyState();
+  });
+
+  test('should show error when search API fails', async ({ page }) => {
+    // Simulate API failure
+    await page.route('**/api/users**', route => route.abort());
+    await userList.searchFor('anything');
+    await userList.expectError('Search unavailable');
+  });
+});
+```
+
+### What NEVER Appears in Test Files
+
+```typescript
+// ❌ Raw selectors in test file — move to Page Object
+await page.getByTestId('search-input').fill('Mark');
+await page.locator('.user-row').first().click();
+
+// ❌ Manual waits — use web-first assertions
+await page.waitForTimeout(2000);
+
+// ❌ Hard-coded credentials
+const email = 'admin@example.com';
+const password = 'Secret123!';
+
+// ❌ CSS/XPath selectors
+await page.locator('#user-list > div:nth-child(2)').click();
+```
+
+## Locator Priority
+
+Use the most user-facing locator available:
+
+| Priority | Locator | When |
+|---|---|---|
+| 1st | `getByRole()` | Buttons, links, headings, lists, rows |
+| 2nd | `getByLabel()` | Form inputs with labels |
+| 3rd | `getByText()` | Visible text content |
+| 4th | `getByPlaceholder()` | Inputs without visible labels |
+| 5th | `getByTestId()` | No user-facing way to identify the element |
+| Avoid | `locator('.class')` | Fragile — breaks on CSS changes |
+| Never | `locator('#id')` or XPath | Extremely fragile |
+
+## Assertions
+
+### Web-First Only (Auto-Waiting)
+
+```typescript
+// ✅ These auto-wait for the condition to be true
+await expect(locator).toBeVisible();
+await expect(locator).toHaveText('Welcome');
+await expect(locator).toHaveCount(5);
+await expect(locator).toBeEnabled();
+await expect(locator).toHaveAttribute('href', '/users');
+await expect(page).toHaveURL(/\/dashboard/);
+
+// ❌ NEVER use manual waits
+await page.waitForTimeout(2000);       // Arbitrary delay
+await page.waitForSelector('.loaded'); // CSS selector
+```
+
+### Negative Assertions
+
+```typescript
+// ✅ Assert something is NOT visible
+await expect(locator).not.toBeVisible();
+await expect(locator).toBeHidden();
+
+// ✅ Assert count is zero
+await expect(locator).toHaveCount(0);
+```
+
+## Test Data
+
+### Fixture Pattern
+
+```typescript
+// tests/fixtures/user.fixtures.ts
+import { type User } from '../../src/app/users/user.model';
+
+export class UserFixtures {
+  static readonly VALID_USER: Readonly<User> = {
+    id: 'test-user-001',
+    name: 'Test User',
+    email: 'test@example.com',
+    role: 'viewer',
+  };
+
+  static readonly ADMIN_USER: Readonly<User> = {
+    id: 'test-admin-001',
+    name: 'Test Admin',
+    email: 'admin@example.com',
+    role: 'admin',
+  };
+
+  static createUser(overrides: Partial<User> = {}): User {
+    return {
+      ...UserFixtures.VALID_USER,
+      id: `test-${Date.now()}`,
+      ...overrides,
+    };
+  }
+}
+```
+
+### API Mocking for Deterministic Tests
+
+```typescript
+// ✅ Mock API responses for predictable test data
+test.beforeEach(async ({ page }) => {
+  await page.route('**/api/users', route =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([
+        UserFixtures.VALID_USER,
+        UserFixtures.ADMIN_USER,
+      ]),
+    })
+  );
+});
+```
+
+## Feature Flags (LaunchDarkly)
+
+### Testing Feature Flag Variants
+
+```typescript
+// tests/helpers/feature-flags.ts
+export async function setFeatureFlag(
+  page: Page,
+  flagKey: string,
+  value: boolean | string | number
+): Promise<void> {
+  await page.route('**/sdk/evalx/**', async route => {
+    const response = await route.fetch();
+    const body = await response.json();
+    body[flagKey] = { ...body[flagKey], value };
+    await route.fulfill({ response, body: JSON.stringify(body) });
+  });
+}
+
+// In test
+test('should show new dashboard when feature flag enabled', async ({ page }) => {
+  await setFeatureFlag(page, 'new-dashboard', true);
+  const dashboard = new DashboardPage(page);
+  await dashboard.goto();
+  await dashboard.expectNewLayoutVisible();
+});
+
+test('should show legacy dashboard when feature flag disabled', async ({ page }) => {
+  await setFeatureFlag(page, 'new-dashboard', false);
+  const dashboard = new DashboardPage(page);
+  await dashboard.goto();
+  await dashboard.expectLegacyLayoutVisible();
+});
+```
+
+## File Organization
+
+```
+tests/
+├── acceptance/                # Outer loop — one dir per domain
+│   ├── users/
+│   │   ├── user-list.spec.ts
+│   │   ├── user-search.spec.ts
+│   │   └── user-create.spec.ts
+│   └── auth/
+│       ├── login.spec.ts
+│       └── logout.spec.ts
+├── unit/                      # Inner loop — mirrors src/ structure
+│   └── users/
+│       ├── user.service.spec.ts
+│       └── user.model.spec.ts
+├── fixtures/                  # Shared test data
+│   ├── user.fixtures.ts
+│   └── auth.fixtures.ts
+└── helpers/                   # Page objects + utilities
+    ├── base.page.ts
+    ├── user-list.page.ts
+    ├── login.page.ts
+    ├── feature-flags.ts
+    └── test-data-builder.ts
+```

package/green-implementation/references/rxjs-patterns.md

@@ -0,0 +1,161 @@
+# RxJS Implementation Patterns
+
+## Operator Safety Rules
+
+### switchMap Must Have catchError
+
+Every `switchMap` creates an inner observable. If that inner observable errors
+without a `catchError`, the entire outer stream dies silently.
+
+```typescript
+// ✅ CORRECT — error handled inside switchMap
+this.searchTerm$.pipe(
+  debounceTime(300),
+  distinctUntilChanged(),
+  switchMap(term =>
+    this.searchService.search(term).pipe(
+      catchError(error => {
+        this.logger.error('Search failed', { term, error });
+        return of({ results: [], error: 'Search unavailable' });
+      })
+    )
+  )
+);
+
+// ❌ REJECTED — inner observable error kills the stream
+this.searchTerm$.pipe(
+  debounceTime(300),
+  switchMap(term => this.searchService.search(term))
+);
+```
+
+This applies to all higher-order mapping operators:
+`switchMap`, `mergeMap`, `concatMap`, `exhaustMap`.
+
+### Prefer async/await Over .then() Chains
+
+```typescript
+// ✅ CORRECT
+async onSubmit(): Promise<void> {
+  try {
+    const result = await firstValueFrom(this.userService.saveUser(this.form.value));
+    this.router.navigate(['/users', result.id]);
+  } catch (error: unknown) {
+    this.handleError(error);
+  }
+}
+
+// ❌ REJECTED — .then() chains
+onSubmit(): void {
+  this.userService.saveUser(this.form.value)
+    .toPromise()
+    .then(result => this.router.navigate(['/users', result.id]))
+    .then(() => this.notification.show('Saved'))
+    .catch(error => this.handleError(error));
+}
+```
+
+Exception: when working inside a purely reactive pipeline (e.g., a store effect
+or an interceptor), use operators like `tap` and `catchError` instead of
+async/await. The rule is about component/service methods that call observables,
+not about replacing operators inside pipes.
+
+## Common Reactive Patterns
+
+### Combining Multiple Data Sources
+
+```typescript
+// ✅ combineLatest — emits when any source changes
+readonly viewModel$ = combineLatest([
+  this.userService.getUsers(),
+  this.filterService.activeFilter$,
+  this.sortService.activeSort$,
+]).pipe(
+  map(([users, filter, sort]) => ({
+    users: this.applyFilter(users, filter),
+    filter,
+    sort,
+    count: users.length,
+  }))
+);
+```
+
+### Loading State Pattern
+
+```typescript
+// ✅ Track loading, error, and data in one stream
+readonly state$ = this.loadTrigger$.pipe(
+  switchMap(() =>
+    this.userService.getUsers().pipe(
+      map(users => ({ loading: false, error: null, users })),
+      catchError(error => of({ loading: false, error: error.message, users: [] as User[] })),
+      startWith({ loading: true, error: null, users: [] as User[] })
+    )
+  )
+);
+```
+
+### Form Value Changes
+
+```typescript
+// ✅ Debounced reactive form search
+this.searchControl.valueChanges.pipe(
+  debounceTime(300),
+  distinctUntilChanged(),
+  filter((term): term is string => term !== null && term.length >= 2),
+  switchMap(term =>
+    this.searchService.search(term).pipe(
+      catchError(() => of([]))
+    )
+  ),
+  takeUntilDestroyed(this.destroyRef)
+).subscribe(results => this.results = results);
+```
+
+## Operators to Prefer
+
+| Situation | Use | Avoid |
+|---|---|---|
+| Cancel previous on new emission | `switchMap` | `mergeMap` (causes race conditions) |
+| Queue sequential requests | `concatMap` | `mergeMap` (unordered) |
+| Ignore while processing | `exhaustMap` | `switchMap` (cancels work) |
+| Wait for first value then complete | `firstValueFrom()` | `.toPromise()` (deprecated) |
+| Take one value | `first()` or `take(1)` | Subscribing without unsubscribe |
+| Side effects in a pipe | `tap()` | Nested subscribes |
+
+## Anti-Patterns
+
+### Never Nest Subscribes
+
+```typescript
+// ❌ Nested subscribe — callback hell, memory leaks
+this.route.params.subscribe(params => {
+  this.userService.getUserById(params['id']).subscribe(user => {
+    this.roleService.getRoles(user.roleId).subscribe(roles => {
+      this.roles = roles;
+    });
+  });
+});
+
+// ✅ Flatten with operators
+this.route.params.pipe(
+  switchMap(params => this.userService.getUserById(params['id'])),
+  switchMap(user => this.roleService.getRoles(user.roleId).pipe(
+    catchError(() => of([]))
+  )),
+  takeUntilDestroyed(this.destroyRef)
+).subscribe(roles => this.roles = roles);
+```
+
+### Never Subscribe Just to Assign
+
+```typescript
+// ❌ Subscribe to assign — use async pipe instead
+ngOnInit() {
+  this.userService.getUsers().subscribe(users => this.users = users);
+}
+
+// ✅ Let Angular manage the subscription
+users$ = this.userService.getUsers();
+// Template: *ngIf="users$ | async as users"
+```