fraim-framework 2.0.26 → 2.0.30

package/registry/rules/agent-testing-guidelines.md

@@ -1,502 +1,502 @@
-# Rule: agent-testing-guidelines
- 
-**Path:** `rules/agent-testing-guidelines.md`
- 
----
- 
-# AI Agent Testing & Validation Guidelines
- 
-## INTENT
-To ensure all work is thoroughly validated. To ensure agents provide **real, reproducible, end‑to‑end evidence** that fixes work — never “looks good” claims.
- 
-## PRINCIPLES
-- **Reproduce → Fix → Prove**: Show failing evidence first, then passing evidence after the fix.
-- **Regression Test Verification**: ALWAYS verify regression tests fail with bug and pass with fix. Never create tests that pass/fail in both scenarios.
-- **Test what matters**: Follow the test plan. Test the functionality that you have changed. Do not mock core functionality being tested.
-- **Keep it simple**: Tests must be minimal but complete, covering all relevant scenarios. Use boilerplate tests and mocks to reduce duplication. Prefer simple unit tests over complex integration tests.
-- **Be complete**: No Placeholder Tests `// TODO` or empty/disabled test bodies are forbidden. Do not assume failing test cases are not important. Always watch for server logs for errors.
-- **Be efficient**: Tests should create objects they need, test core functionality, then delete any objects they create, close server/database connections.
-- **Be resilient**: When a tool fails, investigate alternative approaches before giving up. Check for existing working examples in the project before claiming a tool is broken.
-- **Be truthful**: NEVER CLAIM SUCCESS WITHOUT RUNNING TESTS. Always run tests and show results before claiming they pass.
-- **Backup with Evidence, Not Assertions**: Include evidence of passing tests in the PR before submitting for review.
-- **Complete Test Ownership**: When you write tests, you own ALL failures until ALL tests pass. No exceptions, no categorizations, no "not my problem" rationalizations. If you wrote the test, you fix ALL its failures before claiming completion.
-- **Avoid Duplicates; Find Gaps**: Do not add redundant tests that restate existing coverage. Before adding/removing tests, identify what behavior is currently covered and what is missing, then add/merge tests to close gaps (not inflate count).
-
-## UI E2E (Playwright) — MANDATORY RULES
-
-These rules exist because UI failures often show up as “timeouts” unless you instrument and assert correctly.
-
-- **Headless by default**: `chromium.launch({ headless: true })` unless explicitly debugging.
-- **Prefer DOM truth over network truth**: Assert user-visible state changes (selectors/text) instead of relying on `page.waitForResponse()` predicates.
-- **Instrument failures**: Every Playwright E2E must attach:
-  - `page.on('requestfailed', …)` to print method/url/errorText
-  - `page.on('response', …)` to log HTTP >= 400
-- **Server bootstrap is explicit**: If a test depends on the dev server, it must either:
-  - auto-start it (preferred), or
-  - fail fast with an exact command and URL (`http://localhost:PORT/...`)
-- **Stable selectors only**: Use `data-role`/`data-ashley-component` selectors. Do not use nth-child or layout-dependent selectors.
-- **Optional UI stays optional**: Never re-enable product UI just to satisfy a test. Gate the test behavior or verify via API/DB instead.
-- **Manual UI verification uses Playwright MCP**: When asked to “pop the browser” or confirm a UI bugfix, use Playwright MCP tools (navigate/click/snapshot) and capture the resulting DOM snapshot as evidence.
-
-## FAILING TEST TRIAGE (DO NOT DELETE FIRST)
-
-**Rule**: A failing test is a signal until proven otherwise. You may only delete/skip a test after completing triage and ensuring coverage remains.
-
-### Required triage steps (in order)
-1. **Reproduce twice**: Re-run the failing test at least 2x (same commit) and capture `test.log`/output.
-2. **Classify the failure**:
-   - **Product bug** (test reveals a real functional gap): fix product code; keep the test.
-   - **Test bug** (wrong selector/assumption/incorrect fixture): fix the test; keep the test.
-   - **Flake** (timing/overlays/network): stabilize the test OR rewrite it to a more deterministic layer (unit/integration). Do not delete until replaced.
-3. **Prove redundancy before deletion**:
-   - Point to an existing test that asserts the *same* behavior (or strengthen an existing test to do so).
-   - If you delete a test, you MUST add/merge equivalent coverage elsewhere in the same PR.
-
-### Allowed outcomes
-- **Fix product** (preferred): keep test; it becomes the regression guardrail.
-- **Fix test**: keep test; align with real UX/DOM and intended behavior.
-- **Replace test**: move the assertion to a more reliable layer (e.g., unit test for UI validation logic, API test for backend behavior). Delete only after replacement is merged and passing.
-
-### Prohibited outcomes
-- ❌ Deleting a failing test to “unblock” without proving redundancy
-- ❌ Deleting a failing test when it is the only check for a behavior
-- ❌ Creating “dupe tests” instead of strengthening the existing one
-- ❌ Converting a failing test into a no-op (skipping, loosening assertions) without replacement
-
-## 🚨 MANDATORY ENFORCEMENT PROTOCOLS
-
-### **ANTI-LYING ENFORCEMENT**
-**RULE**: Before claiming ANY test result, you MUST:
-1. Run the exact test command
-2. Show the complete output (not summary)
-3. Verify exit code is 0
-4. State what was actually tested
-
-**VIOLATION CONSEQUENCES**:
-- Immediate task termination
-- Mandatory apology to user
-- Must re-run tests with evidence before continuing
-- Cannot claim "tests pass" without showing actual output
-
-### **TEST SCOPE PRECISION ENFORCEMENT**
-**RULE**: When testing specific functionality:
-- Use targeted commands: `npm run test-failing`, `npm run test-smoke`, etc.
-- NEVER run entire test suites unless explicitly requested
-- Always specify exact test file/function being tested
-
-**VIOLATION CONSEQUENCES**:
-- Must re-run with correct scope
-- Cannot proceed until targeted test is run
-- Must show evidence of correct test scope
-
-### **ANTI-PATTERN DETECTION ENFORCEMENT**
-**RULE**: Before creating any test, you MUST answer these questions:
-
-1. **Am I testing runtime behavior or code structure?**
-   - Runtime behavior = Executing code, checking outcomes (API calls, service methods, state changes)
-   - Code structure = Reading files, checking if strings exist (`fs.readFileSync()` to verify code)
-   - ❌ Code structure checks are NOT tests - they're static analysis
-
-2. **Am I testing the real behavior or a mock?**
-   - Real behavior = Actual API calls, actual service methods
-   - Mock = Only if mocking dependencies, NOT the thing being tested
-   - ❌ Mocking what you're testing is an anti-pattern
-
-3. **Does this test actually validate the fix?**
-   - Would test fail if functionality was broken?
-   - Does test check observable outcomes (database state, API responses, logs)?
-   - ❌ Tests that pass regardless of behavior are invalid
-
-4. **Am I repeating a documented anti-pattern?**
-   - Checked retrospectives for similar mistakes?
-   - Verified test approach doesn't match anti-patterns?
-   - ❌ Repeating documented mistakes (like Issue #723) is prohibited
-
-**MANDATORY VALIDATION**:
-Before writing test code, you MUST:
-1. Answer all 4 questions above
-2. Show answers in your response
-3. Verify answers don't indicate anti-patterns
-4. If ANY answer indicates anti-pattern → STOP, cannot proceed
-
-**VIOLATION CONSEQUENCES**:
-- If mocking what you're testing → STOP immediately
-- If testing code structure instead of runtime behavior → STOP immediately
-- If repeating documented anti-pattern → STOP immediately
-- Must redesign test to validate actual behavior
-- Cannot proceed until test validates functionality
-
-### **FAILURE CASCADE PREVENTION ENFORCEMENT**
-**RULE**: When one approach fails:
-1. STOP - don't try another approach immediately
-2. ANALYZE - why did it fail?
-3. ADMIT - what went wrong?
-4. ASK - for guidance if stuck
-5. FIX - only after understanding the problem
-
-**VIOLATION CONSEQUENCES**:
-- Must pause and analyze failure
-- Cannot try new approach without understanding first failure
-- Must ask user for guidance if stuck
-- Cannot compound errors with more attempts
-
-
-## CORE TESTING PROCEDURE
-
-### 1. Analyze Before Implementing
-**CRITICAL**: Always analyze the codebase thoroughly before making changes:
-- Use `grep_search` to find all dependencies and usage patterns
-- Use `find_by_name` to locate related files and patterns
-- Use `Read` to understand existing implementations
-- Document findings with real code examples and line numbers
-- **NEVER** make changes based on assumptions
-
-### 2. Identify Code Changes
-Before committing, determine the full scope of files that have been modified, created, or deleted.
-
-### 3. **MANDATORY BUILD VERIFICATION - DO THIS BEFORE TESTS**
-
-**🚨 CRITICAL: Run build BEFORE running any tests**
-
-```bash
-# ALWAYS run this first, before any test execution:
-npm run build
-
-# Verify exit code is 0:
-echo $?  # Must output: 0
-```
-
-**Why this is mandatory**:
-- Catches TypeScript compilation errors immediately
-- Prevents wasting time running tests that will fail anyway
-- Catches function signature mismatches
-- Verifies all imports resolve correctly
-- **If build fails, tests are meaningless**
-
-**PROHIBITED**:
-- ❌ Running tests before build
-- ❌ Assuming build works without running it
-- ❌ Claiming "tests passing" when build fails
-- ❌ Ignoring build errors as "probably unrelated"
-
-**REQUIRED**:
-- ✅ Run `npm run build` first, every time
-- ✅ Fix ALL build errors before running tests
-- ✅ Verify exit code is 0
-- ✅ Never proceed to tests if build fails
-
-**Special Case - BAML Files**:
-If you edited ANY `.baml` file, see `.ai-agents/rules/baml-workflow.md` for the mandatory 3-step workflow that must be completed BEFORE running build.
-
-### 3.5. **MANDATORY PRE-TEST CREATION CHECKLIST - BLOCKS TEST WRITING**
-
-**🚨 CRITICAL: Complete this checklist BEFORE writing ANY test code**
-
-**You CANNOT create `test-*.ts` files until ALL items are checked:**
-
-- [ ] **FUNCTIONAL VALIDATION COMPLETE**: Completed Section 4 below with curl/API tests and have evidence
-- [ ] **STRUCTURAL VALIDATION**: Confirmed test file imports `BaseTestCase` and uses `runTests(...)` (verify with `grep`)
-- [ ] **RETROSPECTIVE REVIEW**: Searched `retrospectives/` for testing mistakes (grep -r "anti-pattern\|testing.*fail" retrospectives/)
-- [ ] **ANTI-PATTERN REVIEW**: Read lines 609-780 of this file (anti-pattern section)
-- [ ] **TEST TYPE VERIFIED**: Confirmed I'm testing runtime behavior (executing code), not code structure (reading files)
-
-**VIOLATION CONSEQUENCES**:
-- If ANY item unchecked → STOP immediately, cannot create test files
-- Must show evidence of functional validation (curl outputs, logs) before proceeding
-- User will reject tests that skip this checklist
-
-**VERIFICATION REQUIRED**:
-Before creating any `test-*.ts` file, you MUST display this checklist with all items checked and show functional validation evidence.
-
-### 4. **MANDATORY FUNCTIONAL VALIDATION - DO THIS BEFORE WRITING TESTS**
-
-**🚨 CRITICAL: Validate the feature actually works before writing tests**
-
-**For ANY feature with API endpoints (especially CRUD operations):**
-
-```bash
-# Get the dynamic port (based on issue number in branch name)
-PORT=$(node -e "const {getPort} = require('./src/utils/git-utils'); console.log(getPort());")
-
-# 1. Test CREATE operation
-curl -X POST http://localhost:$PORT/endpoint \
-  -H "x-executive-id: exec-ID" \
-  -d '{"field":"value"}' | grep success
-
-# 2. Verify state in database/downstream systems
-curl http://localhost:$PORT/endpoint | grep "expected-value"
-grep "Created" server.log | tail -5
-
-# 3. Test UPDATE operation and TIME IT
-time curl -X POST http://localhost:$PORT/endpoint \
-  -H "x-executive-id: exec-ID" \
-  -d '{"field":"updated-value"}'
-# MUST complete < 5 seconds
-
-# 4. Verify old state REPLACED (not duplicated)
-curl http://localhost:$PORT/endpoint | grep "old-value"
-# Should be empty (old value gone)
-
-# 5. Check server.log for expected operations
-grep "Updated\|Deleted.*old\|Created.*new" server.log | tail -10
-
-# 6. Test DELETE operation
-curl -X DELETE http://localhost:$PORT/endpoint/ID
-curl http://localhost:$PORT/endpoint | grep "ID"
-# Should be empty (deleted)
-
-# 7. Verify downstream cleanup (calendar events, cache, etc.)
-# For calendar features: verify events deleted from calendar
-# For cache features: verify cache invalidated
-```
-
-**Why this is mandatory:**
-- Tests can pass while feature is broken
-- Must validate ACTUAL behavior, not just test behavior
-- Must verify state changes in ALL systems (DB, calendar, cache)
-- Must catch performance issues (slow operations)
-- Must verify cleanup (no orphaned data)
-
-**PROHIBITED:**
-- ❌ Writing tests without validating feature works first
-- ❌ Assuming UPDATE works because CREATE works
-- ❌ Assuming DELETE cleans up downstream systems
-- ❌ Not timing operations to catch performance bugs
-- ❌ Only checking database, ignoring downstream systems
-
-**REQUIRED**:
-- ✅ Test ALL CRUD operations with curl before writing tests
-- ✅ Time operations to verify performance (< 5s)
-- ✅ Verify state in ALL systems (DB + calendar + logs)
-- ✅ Test with existing data (update scenarios)
-- ✅ Verify cleanup (delete operations)
-- ✅ **SHOW EVIDENCE**: Display curl outputs, server logs, database state BEFORE creating test files
-- ✅ **BLOCK TEST CREATION**: Cannot write `test-*.ts` files until functional validation complete and evidence shown
-
-**Issue #393 Example:**
-What went wrong: Implemented `updateWorkHours()` but didn't test it with curl.
-Result: Updated database but didn't create calendar events.
-Prevention: `curl -X POST /work-hours` twice, check server.log for calendar creation both times.
-
-### 5. Locate Relevant Tests
-- For each modified source file (e.g., in `src/`), search the codebase for corresponding test files
-- Test files follow the naming convention `test-*.ts` or `*.test.ts`
-- A good method is to search for test files that `import` or `require` the modified source file
-
-### 5.5. **MANDATORY RETROSPECTIVE REVIEW BEFORE TEST CREATION**
-
-**🚨 CRITICAL: Review retrospectives for testing mistakes before writing tests**
-
-**REQUIRED ACTION** (must complete before writing ANY test code):
-1. **Search retrospectives**: `grep -r "anti-pattern\|testing.*fail\|test.*wrong" retrospectives/`
-2. **Read mandatory retrospective**: `retrospectives/integration-testing-anti-pattern.md` (MANDATORY - documents this exact mistake)
-3. **Verify test approach**: Check that your planned test doesn't match any documented anti-pattern
-
-**PROHIBITED:**
-- ❌ Writing tests without checking retrospectives
-- ❌ Ignoring documented anti-patterns
-- ❌ Repeating documented anti-patterns (like Issue #723)
-
-**ENFORCEMENT:**
-- If you create tests that match a documented anti-pattern → Immediate rejection
-- Must show evidence of retrospective review before test creation
-
-### 6. Execute Tests
-- **ONLY after functional validation AND build pass**, run the specific test files you have identified
-- Use the `npm test -- <test-file-name.ts>` command to run individual tests
-- If multiple modules are affected, run all relevant test files
-
-### 6.5. **COMPLETE TEST OWNERSHIP - MANDATORY**
-**🚨 CRITICAL: When you write tests, you own ALL failures until ALL tests pass**
-
-**RULE**: If you wrote the test, you fix ALL its failures before claiming completion. No exceptions.
-
-**PROHIBITED**:
-- ❌ "Fixed X issue, but Y failures are not my problem"
-- ❌ "Y failures are functional issues, not [the issue I was asked to fix]"
-- ❌ Categorizing failures as "my problem" vs "not my problem"
-- ❌ Claiming partial completion while tests are failing
-
-**REQUIRED**:
-- ✅ Run ALL tests you wrote before claiming completion
-- ✅ Verify ALL tests pass: `grep "not ok" test.log` returns empty
-- ✅ Fix ALL failures, regardless of failure type
-- ✅ Report complete status: "Fixed X, but Y still failing - investigating now" (not "Fixed X" while Y fails)
-- ✅ Only claim completion when ALL tests pass
-
-**Enforcement**:
-- Before claiming test work complete, verify: `grep -E "^(ok|not ok)" test.log | grep "not ok"` returns empty
-- If any test fails, it's your problem to fix - no exceptions
-- User should never have to remind you: "fix your own tests"
-
-**Reference**: See `retrospectives/retrospective-test-ownership-and-completion-responsibility.md` for detailed analysis of this failure pattern.
-
-### 7. Verify and Fix
-- Careful…22488 tokens truncated…es Checklist
-- [ ] Verify database connection is working
-- [ ] Check database exists and is accessible
-- [ ] Verify collection/table exists
-- [ ] Test simple query to confirm connectivity
-- [ ] After write operations, query to verify data persisted
-- [ ] Check data matches expected schema
-- [ ] Verify indexes and constraints are correct
-
-### API Issues Checklist
-- [ ] Identify exact endpoint URL and method
-- [ ] Test with curl before writing code/tests
-- [ ] Verify endpoint returns expected status code
-- [ ] Check response body structure
-- [ ] Test with required headers
-- [ ] Verify authentication/authorization works
-- [ ] Test error cases (invalid data, missing params)
-
-### UI Issues Checklist
-- [ ] Open browser with Playwright (headless: false)
-- [ ] Navigate to the page manually
-- [ ] Take screenshots at each step
-- [ ] Inspect elements to identify selectors
-- [ ] Try interactions manually (click, type, etc)
-- [ ] Verify expected behavior occurs
-- [ ] Check for JavaScript errors in console
-- [ ] Only then write automated tests
-
-### Test Writing Checklist
-- [ ] Mock dependencies, NOT the code being tested
-- [ ] Test actual implementation, not mocks
-- [ ] Validate service interactions occurred
-- [ ] Verify correct parameters were passed
-- [ ] Check actual return values
-- [ ] Confirm expected side effects
-- [ ] Test error cases and edge cases
-
-## ENFORCEMENT
-
-These rules are **MANDATORY** and enforced through the following implemented mechanisms:
-
-### 1. ESLint Configuration
-**Status**: ✅ **IMPLEMENTED** in `.eslintrc.js`
-
-The following rules enforce type safety:
-```javascript
-'@typescript-eslint/no-explicit-any': 'error',
-'@typescript-eslint/consistent-type-assertions': ['error', {
-  assertionStyle: 'as',
-  objectLiteralTypeAssertions: 'never'
-}]
-```
-
-### 2. Quality Check Script
-**Status**: ✅ **IMPLEMENTED** in `.ai-agents/scripts/code-quality-check.sh`
-
-Automated script that checks for violations at three points:
-- **pre-commit mode**: Checks staged files before commit
-- **pre-pr mode**: Comprehensive checks before creating PR
-- **ci mode**: Runs in GitHub Actions on every PR
-
-Checks performed:
-- ❌ BLOCKS: `as any` type bypassing
-- ❌ BLOCKS: TypeScript compilation errors
-- ⚠️ WARNS: Linter issues
-- ⚠️ WARNS: Uncommitted changes (pre-pr/ci)
-- ⚠️ WARNS: Unpushed commits (pre-pr)
-- ⚠️ WARNS: Unaddressed PR comments (pre-pr)
-
-### 3. GitHub Actions Workflow
-**Status**: ✅ **IMPLEMENTED** in `.github/workflows/code-quality-gate.yml`
-
-Automatically runs on every pull request:
-- Executes quality check script in CI mode
-- Posts results as PR comment
-- Blocks merge if critical checks fail
-
-### PR Review Checklist
-
-When reviewing PRs, verify:
-- [ ] No `as any` type bypassing without documented justification
-- [ ] All commands use timeout scripts (check for bare `npm`, `curl`, etc.)
-- [ ] All previous PR comments have been addressed
-- [ ] Linter shows no errors
-- [ ] Database changes verified with direct queries (vidence in PR)
-- [ ] API changes tested with curl (vidence in PR)
-- [ ] UI changes explored with browser (screenshots in PR)
-- [ ] Tests validate behavior, not just absence of exceptions
-- [ ] Changes made thoughtfully with clear rationale
-
-## QUALITY GATES
-
-The rules above are enforced through automated quality gates using `.ai-agents/scripts/code-quality-check.sh`.
-
-### When Quality Gates Run
-
-1. **Pre-commit** (optional): Checks staged files before committing
-2. **Pre-PR** (REQUIRED): Validates work before marking ready for review - see `.ai-agents/workflows/implement.md` Step 6
-3. **CI** (automatic): Runs on every pull request via GitHub Actions
-
-### What Gets Checked
-
-| Check | Pre-Commit | Pre-PR | CI |
-|-------|------------|--------|-----|
-| `as any` type bypassing | ❌ BLOCKS | ❌ BLOCKS | ❌ BLOCKS |
-| TypeScript compilation | ❌ BLOCKS | ❌ BLOCKS | ❌ BLOCKS |
-| Linter issues | ⚠️ WARNS | ⚠️ WARNS | ⚠️ WARNS |
-| Uncommitted changes | N/A | ⚠️ WARNS | ⚠️ WARNS |
-| Unpushed commits | N/A | ⚠️ WARNS | N/A |
-| PR comments addressed | N/A | ⚠️ WARNS | N/A |
-
-### For Agents
-
-**REQUIRED**: Before marking work ready for review, follow Step 6 in `.ai-agents/workflows/implement.md`:
-- Run `bash .ai-agents/scripts/code-quality-check.sh pre-pr`
-- Fix any critical failures (❌)
-- Document any warnings (⚠️) in evidence
-- Include quality gate output in implementation evidence
-
-### Rule 10: OAuth Multi-Provider Debugging
-
-**CRITICAL**: When debugging OAuth flows with multiple providers (Google, Microsoft):
-
-**Logging Requirements:**
-- **MUST** log which provider is being used: `console.log('🔍 Using provider:', provider)`
-- **MUST** log redirect_uri in authorization: `console.log('🔍 Authorization redirect_uri:', redirectUri)`
-- **MUST** log redirect_uri in token exchange: `console.log('🔍 Token exchange redirect_uri:', redirectUri)`
-- **MUST** log provider extraction from state: `console.log('🔍 Provider from state:', provider || 'MISSING')`
-
-**Provider Extraction:**
-- **MUST** extract `provider` from OAuth state in **ALL** parsing paths (JSON, base64)
-- **MUST** fail explicitly if provider missing from state (don't default silently)
-- **MUST** verify provider matches between authorization and token exchange
-
-**Redirect URI Consistency:**
-- **MUST** use helper function for redirect_uri construction (don't construct inline)
-- **MUST** use same helper in both authorization and token exchange endpoints
-- **MUST** verify redirect_uri matches exactly (Microsoft is strict about this)
-
-**Testing:**
-- **MUST** test with both providers (Google and Microsoft)
-- **MUST** test with stricter provider (Microsoft) first
-- **MUST** check logs to confirm correct provider is being used
-
-**Common Pitfall:**
-- Error: "invalid_grant: Malformed auth code" when provider isn't extracted from state
-- Root cause: Microsoft login using Google provider because provider defaulted
-- Fix: Extract `provider = stateData.provider` in ALL state parsing paths
-
-**Reference**: See `retrospectives/oauth-microsoft-login-fix-retrospective.md` for detailed analysis.
-
-## SUMMARY
-
-**Code Quality**: Use proper types, run linters, use timeouts, respond to feedback
-
-**Database Debugging**: Always verify connection and query directly
-
-**API Debugging**: Test with curl before writing code
-
-**UI Debugging**: Open browser and explore before automating
-
-**Test Quality**: Mock dependencies, validate behavior, not just exceptions
-
-**Thoughtful Action**: Think, analyze, plan, then act - don't react impulsively
-
-**OAuth Multi-Provider**: Always extract provider from OAuth state, use helper functions for redirect_uri, test with Microsoft first
-
-**Enforcement**: Automated via quality gates (pre-commit, pre-PR, CI) using `.ai-agents/scripts/code-quality-check.sh`
+# Rule: agent-testing-guidelines
+ 
+**Path:** `rules/agent-testing-guidelines.md`
+ 
+---
+ 
+# AI Agent Testing & Validation Guidelines
+ 
+## INTENT
+To ensure all work is thoroughly validated. To ensure agents provide **real, reproducible, end‑to‑end evidence** that fixes work — never “looks good” claims.
+ 
+## PRINCIPLES
+- **Reproduce → Fix → Prove**: Show failing evidence first, then passing evidence after the fix.
+- **Regression Test Verification**: ALWAYS verify regression tests fail with bug and pass with fix. Never create tests that pass/fail in both scenarios.
+- **Test what matters**: Follow the test plan. Test the functionality that you have changed. Do not mock core functionality being tested.
+- **Keep it simple**: Tests must be minimal but complete, covering all relevant scenarios. Use boilerplate tests and mocks to reduce duplication. Prefer simple unit tests over complex integration tests.
+- **Be complete**: No Placeholder Tests `// TODO` or empty/disabled test bodies are forbidden. Do not assume failing test cases are not important. Always watch for server logs for errors.
+- **Be efficient**: Tests should create objects they need, test core functionality, then delete any objects they create, close server/database connections.
+- **Be resilient**: When a tool fails, investigate alternative approaches before giving up. Check for existing working examples in the project before claiming a tool is broken.
+- **Be truthful**: NEVER CLAIM SUCCESS WITHOUT RUNNING TESTS. Always run tests and show results before claiming they pass.
+- **Backup with Evidence, Not Assertions**: Include evidence of passing tests in the PR before submitting for review.
+- **Complete Test Ownership**: When you write tests, you own ALL failures until ALL tests pass. No exceptions, no categorizations, no "not my problem" rationalizations. If you wrote the test, you fix ALL its failures before claiming completion.
+- **Avoid Duplicates; Find Gaps**: Do not add redundant tests that restate existing coverage. Before adding/removing tests, identify what behavior is currently covered and what is missing, then add/merge tests to close gaps (not inflate count).
+
+## UI E2E (Playwright) — MANDATORY RULES
+
+These rules exist because UI failures often show up as “timeouts” unless you instrument and assert correctly.
+
+- **Headless by default**: `chromium.launch({ headless: true })` unless explicitly debugging.
+- **Prefer DOM truth over network truth**: Assert user-visible state changes (selectors/text) instead of relying on `page.waitForResponse()` predicates.
+- **Instrument failures**: Every Playwright E2E must attach:
+  - `page.on('requestfailed', …)` to print method/url/errorText
+  - `page.on('response', …)` to log HTTP >= 400
+- **Server bootstrap is explicit**: If a test depends on the dev server, it must either:
+  - auto-start it (preferred), or
+  - fail fast with an exact command and URL (`http://localhost:PORT/...`)
+- **Stable selectors only**: Use `data-role`/`data-ashley-component` selectors. Do not use nth-child or layout-dependent selectors.
+- **Optional UI stays optional**: Never re-enable product UI just to satisfy a test. Gate the test behavior or verify via API/DB instead.
+- **Manual UI verification uses Playwright MCP**: When asked to “pop the browser” or confirm a UI bugfix, use Playwright MCP tools (navigate/click/snapshot) and capture the resulting DOM snapshot as evidence.
+
+## FAILING TEST TRIAGE (DO NOT DELETE FIRST)
+
+**Rule**: A failing test is a signal until proven otherwise. You may only delete/skip a test after completing triage and ensuring coverage remains.
+
+### Required triage steps (in order)
+1. **Reproduce twice**: Re-run the failing test at least 2x (same commit) and capture `test.log`/output.
+2. **Classify the failure**:
+   - **Product bug** (test reveals a real functional gap): fix product code; keep the test.
+   - **Test bug** (wrong selector/assumption/incorrect fixture): fix the test; keep the test.
+   - **Flake** (timing/overlays/network): stabilize the test OR rewrite it to a more deterministic layer (unit/integration). Do not delete until replaced.
+3. **Prove redundancy before deletion**:
+   - Point to an existing test that asserts the *same* behavior (or strengthen an existing test to do so).
+   - If you delete a test, you MUST add/merge equivalent coverage elsewhere in the same PR.
+
+### Allowed outcomes
+- **Fix product** (preferred): keep test; it becomes the regression guardrail.
+- **Fix test**: keep test; align with real UX/DOM and intended behavior.
+- **Replace test**: move the assertion to a more reliable layer (e.g., unit test for UI validation logic, API test for backend behavior). Delete only after replacement is merged and passing.
+
+### Prohibited outcomes
+- ❌ Deleting a failing test to “unblock” without proving redundancy
+- ❌ Deleting a failing test when it is the only check for a behavior
+- ❌ Creating “dupe tests” instead of strengthening the existing one
+- ❌ Converting a failing test into a no-op (skipping, loosening assertions) without replacement
+
+## 🚨 MANDATORY ENFORCEMENT PROTOCOLS
+
+### **ANTI-LYING ENFORCEMENT**
+**RULE**: Before claiming ANY test result, you MUST:
+1. Run the exact test command
+2. Show the complete output (not summary)
+3. Verify exit code is 0
+4. State what was actually tested
+
+**VIOLATION CONSEQUENCES**:
+- Immediate task termination
+- Mandatory apology to user
+- Must re-run tests with evidence before continuing
+- Cannot claim "tests pass" without showing actual output
+
+### **TEST SCOPE PRECISION ENFORCEMENT**
+**RULE**: When testing specific functionality:
+- Use targeted commands: `npm run test-failing`, `npm run test-smoke`, etc.
+- NEVER run entire test suites unless explicitly requested
+- Always specify exact test file/function being tested
+
+**VIOLATION CONSEQUENCES**:
+- Must re-run with correct scope
+- Cannot proceed until targeted test is run
+- Must show evidence of correct test scope
+
+### **ANTI-PATTERN DETECTION ENFORCEMENT**
+**RULE**: Before creating any test, you MUST answer these questions:
+
+1. **Am I testing runtime behavior or code structure?**
+   - Runtime behavior = Executing code, checking outcomes (API calls, service methods, state changes)
+   - Code structure = Reading files, checking if strings exist (`fs.readFileSync()` to verify code)
+   - ❌ Code structure checks are NOT tests - they're static analysis
+
+2. **Am I testing the real behavior or a mock?**
+   - Real behavior = Actual API calls, actual service methods
+   - Mock = Only if mocking dependencies, NOT the thing being tested
+   - ❌ Mocking what you're testing is an anti-pattern
+
+3. **Does this test actually validate the fix?**
+   - Would test fail if functionality was broken?
+   - Does test check observable outcomes (database state, API responses, logs)?
+   - ❌ Tests that pass regardless of behavior are invalid
+
+4. **Am I repeating a documented anti-pattern?**
+   - Checked retrospectives for similar mistakes?
+   - Verified test approach doesn't match anti-patterns?
+   - ❌ Repeating documented mistakes (like Issue #723) is prohibited
+
+**MANDATORY VALIDATION**:
+Before writing test code, you MUST:
+1. Answer all 4 questions above
+2. Show answers in your response
+3. Verify answers don't indicate anti-patterns
+4. If ANY answer indicates anti-pattern → STOP, cannot proceed
+
+**VIOLATION CONSEQUENCES**:
+- If mocking what you're testing → STOP immediately
+- If testing code structure instead of runtime behavior → STOP immediately
+- If repeating documented anti-pattern → STOP immediately
+- Must redesign test to validate actual behavior
+- Cannot proceed until test validates functionality
+
+### **FAILURE CASCADE PREVENTION ENFORCEMENT**
+**RULE**: When one approach fails:
+1. STOP - don't try another approach immediately
+2. ANALYZE - why did it fail?
+3. ADMIT - what went wrong?
+4. ASK - for guidance if stuck
+5. FIX - only after understanding the problem
+
+**VIOLATION CONSEQUENCES**:
+- Must pause and analyze failure
+- Cannot try new approach without understanding first failure
+- Must ask user for guidance if stuck
+- Cannot compound errors with more attempts
+
+
+## CORE TESTING PROCEDURE
+
+### 1. Analyze Before Implementing
+**CRITICAL**: Always analyze the codebase thoroughly before making changes:
+- Use `grep_search` to find all dependencies and usage patterns
+- Use `find_by_name` to locate related files and patterns
+- Use `Read` to understand existing implementations
+- Document findings with real code examples and line numbers
+- **NEVER** make changes based on assumptions
+
+### 2. Identify Code Changes
+Before committing, determine the full scope of files that have been modified, created, or deleted.
+
+### 3. **MANDATORY BUILD VERIFICATION - DO THIS BEFORE TESTS**
+
+**🚨 CRITICAL: Run build BEFORE running any tests**
+
+```bash
+# ALWAYS run this first, before any test execution:
+npm run build
+
+# Verify exit code is 0:
+echo $?  # Must output: 0
+```
+
+**Why this is mandatory**:
+- Catches TypeScript compilation errors immediately
+- Prevents wasting time running tests that will fail anyway
+- Catches function signature mismatches
+- Verifies all imports resolve correctly
+- **If build fails, tests are meaningless**
+
+**PROHIBITED**:
+- ❌ Running tests before build
+- ❌ Assuming build works without running it
+- ❌ Claiming "tests passing" when build fails
+- ❌ Ignoring build errors as "probably unrelated"
+
+**REQUIRED**:
+- ✅ Run `npm run build` first, every time
+- ✅ Fix ALL build errors before running tests
+- ✅ Verify exit code is 0
+- ✅ Never proceed to tests if build fails
+
+**Special Case - BAML Files**:
+If you edited ANY `.baml` file, see `get_fraim_file({ path: "rules/baml-workflow.md" })` for the mandatory 3-step workflow that must be completed BEFORE running build.
+
+### 3.5. **MANDATORY PRE-TEST CREATION CHECKLIST - BLOCKS TEST WRITING**
+
+**🚨 CRITICAL: Complete this checklist BEFORE writing ANY test code**
+
+**You CANNOT create `test-*.ts` files until ALL items are checked:**
+
+- [ ] **FUNCTIONAL VALIDATION COMPLETE**: Completed Section 4 below with curl/API tests and have evidence
+- [ ] **STRUCTURAL VALIDATION**: Confirmed test file imports `BaseTestCase` and uses `runTests(...)` (verify with `grep`)
+- [ ] **RETROSPECTIVE REVIEW**: Searched `retrospectives/` for testing mistakes (grep -r "anti-pattern\|testing.*fail" retrospectives/)
+- [ ] **ANTI-PATTERN REVIEW**: Read lines 609-780 of this file (anti-pattern section)
+- [ ] **TEST TYPE VERIFIED**: Confirmed I'm testing runtime behavior (executing code), not code structure (reading files)
+
+**VIOLATION CONSEQUENCES**:
+- If ANY item unchecked → STOP immediately, cannot create test files
+- Must show evidence of functional validation (curl outputs, logs) before proceeding
+- User will reject tests that skip this checklist
+
+**VERIFICATION REQUIRED**:
+Before creating any `test-*.ts` file, you MUST display this checklist with all items checked and show functional validation evidence.
+
+### 4. **MANDATORY FUNCTIONAL VALIDATION - DO THIS BEFORE WRITING TESTS**
+
+**🚨 CRITICAL: Validate the feature actually works before writing tests**
+
+**For ANY feature with API endpoints (especially CRUD operations):**
+
+```bash
+# Get the dynamic port (based on issue number in branch name)
+PORT=$(node -e "const {getPort} = require('./src/utils/git-utils'); console.log(getPort());")
+
+# 1. Test CREATE operation
+curl -X POST http://localhost:$PORT/endpoint \
+  -H "x-executive-id: exec-ID" \
+  -d '{"field":"value"}' | grep success
+
+# 2. Verify state in database/downstream systems
+curl http://localhost:$PORT/endpoint | grep "expected-value"
+grep "Created" server.log | tail -5
+
+# 3. Test UPDATE operation and TIME IT
+time curl -X POST http://localhost:$PORT/endpoint \
+  -H "x-executive-id: exec-ID" \
+  -d '{"field":"updated-value"}'
+# MUST complete < 5 seconds
+
+# 4. Verify old state REPLACED (not duplicated)
+curl http://localhost:$PORT/endpoint | grep "old-value"
+# Should be empty (old value gone)
+
+# 5. Check server.log for expected operations
+grep "Updated\|Deleted.*old\|Created.*new" server.log | tail -10
+
+# 6. Test DELETE operation
+curl -X DELETE http://localhost:$PORT/endpoint/ID
+curl http://localhost:$PORT/endpoint | grep "ID"
+# Should be empty (deleted)
+
+# 7. Verify downstream cleanup (calendar events, cache, etc.)
+# For calendar features: verify events deleted from calendar
+# For cache features: verify cache invalidated
+```
+
+**Why this is mandatory:**
+- Tests can pass while feature is broken
+- Must validate ACTUAL behavior, not just test behavior
+- Must verify state changes in ALL systems (DB, calendar, cache)
+- Must catch performance issues (slow operations)
+- Must verify cleanup (no orphaned data)
+
+**PROHIBITED:**
+- ❌ Writing tests without validating feature works first
+- ❌ Assuming UPDATE works because CREATE works
+- ❌ Assuming DELETE cleans up downstream systems
+- ❌ Not timing operations to catch performance bugs
+- ❌ Only checking database, ignoring downstream systems
+
+**REQUIRED**:
+- ✅ Test ALL CRUD operations with curl before writing tests
+- ✅ Time operations to verify performance (< 5s)
+- ✅ Verify state in ALL systems (DB + calendar + logs)
+- ✅ Test with existing data (update scenarios)
+- ✅ Verify cleanup (delete operations)
+- ✅ **SHOW EVIDENCE**: Display curl outputs, server logs, database state BEFORE creating test files
+- ✅ **BLOCK TEST CREATION**: Cannot write `test-*.ts` files until functional validation complete and evidence shown
+
+**Issue #393 Example:**
+What went wrong: Implemented `updateWorkHours()` but didn't test it with curl.
+Result: Updated database but didn't create calendar events.
+Prevention: `curl -X POST /work-hours` twice, check server.log for calendar creation both times.
+
+### 5. Locate Relevant Tests
+- For each modified source file (e.g., in `src/`), search the codebase for corresponding test files
+- Test files follow the naming convention `test-*.ts` or `*.test.ts`
+- A good method is to search for test files that `import` or `require` the modified source file
+
+### 5.5. **MANDATORY RETROSPECTIVE REVIEW BEFORE TEST CREATION**
+
+**🚨 CRITICAL: Review retrospectives for testing mistakes before writing tests**
+
+**REQUIRED ACTION** (must complete before writing ANY test code):
+1. **Search retrospectives**: `grep -r "anti-pattern\|testing.*fail\|test.*wrong" retrospectives/`
+2. **Read mandatory retrospective**: `retrospectives/integration-testing-anti-pattern.md` (MANDATORY - documents this exact mistake)
+3. **Verify test approach**: Check that your planned test doesn't match any documented anti-pattern
+
+**PROHIBITED:**
+- ❌ Writing tests without checking retrospectives
+- ❌ Ignoring documented anti-patterns
+- ❌ Repeating documented anti-patterns (like Issue #723)
+
+**ENFORCEMENT:**
+- If you create tests that match a documented anti-pattern → Immediate rejection
+- Must show evidence of retrospective review before test creation
+
+### 6. Execute Tests
+- **ONLY after functional validation AND build pass**, run the specific test files you have identified
+- Use the `npm test -- <test-file-name.ts>` command to run individual tests
+- If multiple modules are affected, run all relevant test files
+
+### 6.5. **COMPLETE TEST OWNERSHIP - MANDATORY**
+**🚨 CRITICAL: When you write tests, you own ALL failures until ALL tests pass**
+
+**RULE**: If you wrote the test, you fix ALL its failures before claiming completion. No exceptions.
+
+**PROHIBITED**:
+- ❌ "Fixed X issue, but Y failures are not my problem"
+- ❌ "Y failures are functional issues, not [the issue I was asked to fix]"
+- ❌ Categorizing failures as "my problem" vs "not my problem"
+- ❌ Claiming partial completion while tests are failing
+
+**REQUIRED**:
+- ✅ Run ALL tests you wrote before claiming completion
+- ✅ Verify ALL tests pass: `grep "not ok" test.log` returns empty
+- ✅ Fix ALL failures, regardless of failure type
+- ✅ Report complete status: "Fixed X, but Y still failing - investigating now" (not "Fixed X" while Y fails)
+- ✅ Only claim completion when ALL tests pass
+
+**Enforcement**:
+- Before claiming test work complete, verify: `grep -E "^(ok|not ok)" test.log | grep "not ok"` returns empty
+- If any test fails, it's your problem to fix - no exceptions
+- User should never have to remind you: "fix your own tests"
+
+**Reference**: See `retrospectives/retrospective-test-ownership-and-completion-responsibility.md` for detailed analysis of this failure pattern.
+
+### 7. Verify and Fix
+- Careful…22488 tokens truncated…es Checklist
+- [ ] Verify database connection is working
+- [ ] Check database exists and is accessible
+- [ ] Verify collection/table exists
+- [ ] Test simple query to confirm connectivity
+- [ ] After write operations, query to verify data persisted
+- [ ] Check data matches expected schema
+- [ ] Verify indexes and constraints are correct
+
+### API Issues Checklist
+- [ ] Identify exact endpoint URL and method
+- [ ] Test with curl before writing code/tests
+- [ ] Verify endpoint returns expected status code
+- [ ] Check response body structure
+- [ ] Test with required headers
+- [ ] Verify authentication/authorization works
+- [ ] Test error cases (invalid data, missing params)
+
+### UI Issues Checklist
+- [ ] Open browser with Playwright (headless: false)
+- [ ] Navigate to the page manually
+- [ ] Take screenshots at each step
+- [ ] Inspect elements to identify selectors
+- [ ] Try interactions manually (click, type, etc)
+- [ ] Verify expected behavior occurs
+- [ ] Check for JavaScript errors in console
+- [ ] Only then write automated tests
+
+### Test Writing Checklist
+- [ ] Mock dependencies, NOT the code being tested
+- [ ] Test actual implementation, not mocks
+- [ ] Validate service interactions occurred
+- [ ] Verify correct parameters were passed
+- [ ] Check actual return values
+- [ ] Confirm expected side effects
+- [ ] Test error cases and edge cases
+
+## ENFORCEMENT
+
+These rules are **MANDATORY** and enforced through the following implemented mechanisms:
+
+### 1. ESLint Configuration
+**Status**: ✅ **IMPLEMENTED** in `.eslintrc.js`
+
+The following rules enforce type safety:
+```javascript
+'@typescript-eslint/no-explicit-any': 'error',
+'@typescript-eslint/consistent-type-assertions': ['error', {
+  assertionStyle: 'as',
+  objectLiteralTypeAssertions: 'never'
+}]
+```
+
+### 2. Quality Check Script
+**Status**: ✅ **IMPLEMENTED** in `get_fraim_file({ path: "scripts/code-quality-check.sh" })`
+
+Automated script that checks for violations at three points:
+- **pre-commit mode**: Checks staged files before commit
+- **pre-pr mode**: Comprehensive checks before creating PR
+- **ci mode**: Runs in GitHub Actions on every PR
+
+Checks performed:
+- ❌ BLOCKS: `as any` type bypassing
+- ❌ BLOCKS: TypeScript compilation errors
+- ⚠️ WARNS: Linter issues
+- ⚠️ WARNS: Uncommitted changes (pre-pr/ci)
+- ⚠️ WARNS: Unpushed commits (pre-pr)
+- ⚠️ WARNS: Unaddressed PR comments (pre-pr)
+
+### 3. GitHub Actions Workflow
+**Status**: ✅ **IMPLEMENTED** in `.github/workflows/code-quality-gate.yml`
+
+Automatically runs on every pull request:
+- Executes quality check script in CI mode
+- Posts results as PR comment
+- Blocks merge if critical checks fail
+
+### PR Review Checklist
+
+When reviewing PRs, verify:
+- [ ] No `as any` type bypassing without documented justification
+- [ ] All commands use timeout scripts (check for bare `npm`, `curl`, etc.)
+- [ ] All previous PR comments have been addressed
+- [ ] Linter shows no errors
+- [ ] Database changes verified with direct queries (vidence in PR)
+- [ ] API changes tested with curl (vidence in PR)
+- [ ] UI changes explored with browser (screenshots in PR)
+- [ ] Tests validate behavior, not just absence of exceptions
+- [ ] Changes made thoughtfully with clear rationale
+
+## QUALITY GATES
+
+The rules above are enforced through automated quality gates using `get_fraim_file({ path: "scripts/code-quality-check.sh" })`.
+
+### When Quality Gates Run
+
+1. **Pre-commit** (optional): Checks staged files before committing
+2. **Pre-PR** (REQUIRED): Validates work before marking ready for review - see `get_fraim_file({ path: "workflows/product-building/implement.md" })` Step 6
+3. **CI** (automatic): Runs on every pull request via GitHub Actions
+
+### What Gets Checked
+
+| Check | Pre-Commit | Pre-PR | CI |
+|-------|------------|--------|-----|
+| `as any` type bypassing | ❌ BLOCKS | ❌ BLOCKS | ❌ BLOCKS |
+| TypeScript compilation | ❌ BLOCKS | ❌ BLOCKS | ❌ BLOCKS |
+| Linter issues | ⚠️ WARNS | ⚠️ WARNS | ⚠️ WARNS |
+| Uncommitted changes | N/A | ⚠️ WARNS | ⚠️ WARNS |
+| Unpushed commits | N/A | ⚠️ WARNS | N/A |
+| PR comments addressed | N/A | ⚠️ WARNS | N/A |
+
+### For Agents
+
+**REQUIRED**: Before marking work ready for review, follow "Quality Gate Validation" in `get_fraim_file({ path: "workflows/product-building/implement.md" })`:
+- Run `get_fraim_file({ path: "scripts/code-quality-check.sh" })` with argument `pre-pr`
+- Fix any critical failures (❌)
+- Document any warnings (⚠️) in evidence
+- Include quality gate output in implementation evidence
+
+### Rule 10: OAuth Multi-Provider Debugging
+
+**CRITICAL**: When debugging OAuth flows with multiple providers (Google, Microsoft):
+
+**Logging Requirements:**
+- **MUST** log which provider is being used: `console.log('🔍 Using provider:', provider)`
+- **MUST** log redirect_uri in authorization: `console.log('🔍 Authorization redirect_uri:', redirectUri)`
+- **MUST** log redirect_uri in token exchange: `console.log('🔍 Token exchange redirect_uri:', redirectUri)`
+- **MUST** log provider extraction from state: `console.log('🔍 Provider from state:', provider || 'MISSING')`
+
+**Provider Extraction:**
+- **MUST** extract `provider` from OAuth state in **ALL** parsing paths (JSON, base64)
+- **MUST** fail explicitly if provider missing from state (don't default silently)
+- **MUST** verify provider matches between authorization and token exchange
+
+**Redirect URI Consistency:**
+- **MUST** use helper function for redirect_uri construction (don't construct inline)
+- **MUST** use same helper in both authorization and token exchange endpoints
+- **MUST** verify redirect_uri matches exactly (Microsoft is strict about this)
+
+**Testing:**
+- **MUST** test with both providers (Google and Microsoft)
+- **MUST** test with stricter provider (Microsoft) first
+- **MUST** check logs to confirm correct provider is being used
+
+**Common Pitfall:**
+- Error: "invalid_grant: Malformed auth code" when provider isn't extracted from state
+- Root cause: Microsoft login using Google provider because provider defaulted
+- Fix: Extract `provider = stateData.provider` in ALL state parsing paths
+
+**Reference**: See `retrospectives/oauth-microsoft-login-fix-retrospective.md` for detailed analysis.
+
+## SUMMARY
+
+**Code Quality**: Use proper types, run linters, use timeouts, respond to feedback
+
+**Database Debugging**: Always verify connection and query directly
+
+**API Debugging**: Test with curl before writing code
+
+**UI Debugging**: Open browser and explore before automating
+
+**Test Quality**: Mock dependencies, validate behavior, not just exceptions
+
+**Thoughtful Action**: Think, analyze, plan, then act - don't react impulsively
+
+**OAuth Multi-Provider**: Always extract provider from OAuth state, use helper functions for redirect_uri, test with Microsoft first
+
+**Enforcement**: Automated via quality gates (pre-commit, pre-PR, CI) using `get_fraim_file({ path: "scripts/code-quality-check.sh" })`