tribunal-kit 2.4.6 → 3.1.0

package/.agent/skills/plan-writing/SKILL.md

@@ -1,188 +1,84 @@
 ---
 name: plan-writing
-description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
+description: Technical design and implementation planning mastery. Writing structured execution checklists, dependency mapping, establishing rollback protocols, segmenting monolithic tasks, writing ADRs (Architecture Decision Records), and defining verification criteria. Use when transitioning from ideation to coordinated execution.
 allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Task Planning Standards
-
-> A plan is not a promise. It is a map.
-> Maps get updated when the terrain doesn't match them.
+# Plan Writing — Execution Blueprints Mastery
 
 ---
 
-## When to Write a Plan
+## 1. The Implementation Plan Structure (ADR-Lite)
 
-Write a plan before implementation when:
-- The task touches more than 2 files in non-trivial ways
-- The task has dependencies (thing B can't start until thing A is done)
-- The task involves a risky operation (migration, data transformation, breaking change)
-- The team needs to review the approach before time is spent implementing it
+Before altering multiple files or introducing a new system architecture, a rigid `implementation_plan.md` MUST be generated and approved. 
 
-Skip the formal plan for: single-function fixes, typo corrections, config tweaks.
+**Core Sections:**
+1. **Objective Context:** 2-sentence summary of the requested goal.
+2. **Architectural Handoff:** (What stack, what libraries, what constraints).
+3. **Dependency Tree Execution Order:** (Cannot build frontend UI until backend API exists).
+4. **File Blueprint:** Exact files expected to be touched (`[NEW] src/api/user.ts`, `[MODIFY] src/db/schema.prisma`).
+5. **Verification Protocol:** Exactly how the agent/human will prove the task is completed successfully.
 
 ---
 
-## Plan Structure
-
-```markdown
-# Plan: [Feature or Task Name]
-
-## Goal
-One sentence: what outcome does this achieve?
-
-## Context
-- Why is this being done?
-- What problem does it solve or what requirement does it satisfy?
-- What exists today that this changes?
-
-## Approach
-High-level strategy. Enough detail for someone unfamiliar with the code to understand the direction.
-Not implementation details — those go in the tasks.
-
-## Tasks
+## 2. Segmenting Monolithic Tasks (Chunking)
 
-### Phase 1 — [Name] (prerequisite for Phase 2)
-- [ ] Task 1.1: Description
-- [ ] Task 1.2: Description (depends on 1.1)
+LLMs degrade significantly when asked to process >10 file alterations across multiple directories simultaneously. The Plan Writer must break work into logical, isolated "Waves."
 
-### Phase 2 — [Name] (can run after Phase 1 is complete)
-- [ ] Task 2.1: Description
-- [ ] Task 2.2: Description
-
-## Verification
-How will we know this is done and working?
-- [ ] Specific behavior that can be tested
-- [ ] Metric or log line that confirms success
-- [ ] Edge case that must not regress
-
-## Risks and Open Questions
-- [Risk]: What might go wrong, and what's the mitigation?
-- [Open]: What decision hasn't been made yet that could change this plan?
-
-## Files That Will Change
-- `path/to/file.ts` — what changes
-- `path/to/schema.sql` — what changes
-```
-
----
-
-## Dependency Notation
-
-When tasks have a strict order, mark it:
-
-```
-Task A — (no dependencies, do first)
-Task B — (requires A complete)
-Task C — (can run parallel with B)
-Task D — (requires B and C complete)
+```markdown
+### Wave 1: Data Layer (The Foundation)
+1. Add `Subscription` model to Prisma schema.
+2. Generate migration (`npx prisma migrate dev`).
+3. Add mock seed data.
+
+### Wave 2: API Layer (The Bridge)
+1. Build `/api/subscriptions/route.ts` with explicit Zod validation.
+2. Write Vitest logic enforcing authorization roles.
+
+### Wave 3: UI Layer (The Implementation)
+1. Build `SubscriptionCard.tsx`.
+2. Connect to API using MSW mocked tests first.
+3. Integrate into main dashboard.
 ```
 
-This prevents teams from working on D while B is still broken.
-
----
-
-## Task Granularity
-
-Each task should be:
-- Completable in one session by one person
-- Independently reviewable (a PR could represent one task)
-- Testable: there is a concrete way to know if it's done
-
-**Too vague:** "Implement the auth system"
-**Right size:** "Add `POST /api/auth/login` endpoint with JWT issuance and Zod validation"
-
----
-
-## Updating the Plan
-
-Plans are living documents:
-
-- Mark tasks `[x]` when complete, not when started
-- Add `[!]` to blocked tasks with a note on what is blocking
-- When an assumption proves wrong, update the approach section — don't silently deviate from the plan
+*Crucial:* Each wave MUST be executable and testable independently. Do not begin Wave 2 until Wave 1 passes Verification Protocols.
 
 ---
 
-## Verification Criteria Rules
+## 3. Rollback & Contingency Planning
 
-Verification criteria are not optional. For each task:
+No plan survives first contact with the compiler. The plan must implicitly include safe-fail procedures.
 
-- At least one must be **observable** (you can see it, not just believe it)
-- At least one must cover a **failure mode** (what should NOT happen)
-
-```
-✅ Observable: `POST /api/users` returns 201 with a user ID in the response body
-✅ Failure mode: `POST /api/users` with a duplicate email returns 409, not 500
-```
+- **Non-Destructive Defaults:** If a schema migration fails, how do we revert? (e.g., explicit instruction to backup SQLite DB locally before operations).
+- **Graceful Feature Toggles:** Is the new feature walled behind an environment variable (`ENABLE_NEW_DASHBOARD=true`) so it can be disabled instantly if it crashes in production?
 
 ---
 
-## 🛑 Verification-Before-Completion (VBC) Protocol
+## 4. The `task.md` Execution Ledger
 
-**CRITICAL:** Every plan must integrate a strict "evidence-based closeout" state machine for its tasks.
-- ❌ **Forbidden:** Writing vague verification steps like "Check that it looks right," "Ensure the code makes sense," or "Verify the logic."
-- ✅ **Required:** Verification criteria MUST demand **concrete terminal/compiler evidence** (e.g., test success logs, CLI execution outputs, compiler success states, or network trace results). Explicitly state that an agent CANNOT consider the task complete until it captures this hard evidence.
+Unlike the high-level `implementation_plan.md`, the `task.md` serves as the live, mutating execution state.
 
----
+```markdown
+# Current Objective: Upgrade Authentication
 
-## Output Format
+## Pre-Flight
+- [x] Dump existing environment variables locally
+- [x] Verify current tests pass (Baseline health)
 
-When this skill produces a recommendation or design decision, structure your output as:
+## Wave 1 (OAuth Scaffold)
+- [/] Install auth.js dependencies
+- [ ] Connect Google Provider inside `[...nextauth].ts`
 
+## Wave 2 (Database Mappings)
+- [ ] Update Users table to handle polymorphic OAuth links
 ```
-━━━ Plan Writing Recommendation ━━━━━━━━━━━━━━━━
-Decision:    [what was chosen / proposed]
-Rationale:   [why — one concise line]
-Trade-offs:  [what is consciously accepted]
-Next action: [concrete next step for the user]
-─────────────────────────────────────────────────
-Pre-Flight:  ✅ All checks passed
-             or ❌ [blocking item that must be resolved first]
-```
-
 
+*Rules:*
+- `[ ]` = Unstarted
+- `[/]` = In Progress (Current Focus)
+- `[x]` = Verified Complete
 
 ---
-
-## 🤖 LLM-Specific Traps
-
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
-
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
-
----
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
-
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before confirming output:
-```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
-```
-
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

package/.agent/skills/platform-engineer/SKILL.md

@@ -1,135 +1,89 @@
 ---
 name: platform-engineer
-description: Senior platform engineer with deep expertise in building internal developer platforms, self-service infrastructure, and developer portals. Reduces cognitive load and accelerates software delivery.
+description: Platform Engineering and Internal Developer Portal (IDP) mastery. Golden Paths, self-service infrastructure, cognitive load reduction, GitOps synchronization (ArgoCD/Flux), Terraform/OpenTofu architecture, and standardized service scaffolding. Use when designing system-wide development workflows or standardizing infrastructure processes.
 allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Platform Engineer - Claude Code Sub-Agent
-
-You are a senior platform engineer with deep expertise in building internal developer platforms, self-service infrastructure, and developer portals. Your focus spans platform architecture, GitOps workflows, service catalogs, and developer experience optimization with emphasis on reducing cognitive load and accelerating software delivery.
-
-## Configuration & Context Assessment
-When invoked:
-1. Query context manager for existing platform capabilities and developer needs
-2. Review current self-service offerings, golden paths, and adoption metrics
-3. Analyze developer pain points, workflow bottlenecks, and platform gaps
-4. Implement solutions maximizing developer productivity and platform adoption
+# Platform Engineering — Developer Experience Mastery
 
 ---
 
-## The Platform Excellence Checklist
-- Self-service rate exceeding 90%
-- Provisioning time under 5 minutes
-- Platform uptime 99.9%
-- API response time < 200ms
-- Documentation coverage 100%
-- Developer onboarding < 1 day
-- Golden paths established
-- Feedback loops active
+## 1. The "Golden Path" Architecture
 
----
+A developer should not have to write a Dockerfile, configure a CI pipeline, request AWS permissions, or setup Prometheus dashboards to launch a new microservice.
 
-## Core Architecture Decision Framework
+The Platform Engineer establishes **Golden Paths**: pre-approved, automated templates that bundle security and infrastructure out-of-the-box.
 
-### Platform Operations & GitOps Implementation
-*   **Platform Architecture:** Multi-tenant platform design, Resource isolation strategies, Cost allocation tracking, Compliance automation.
-*   **GitOps:** Repository structure design, PR automation workflows, Secret management, Multi-cluster synchronization.
-*   **Infrastructure Abstraction:** Crossplane compositions, Terraform modules, Operator patterns, State reconciliation.
+**Example: Local Service Scaffolding (Backstage / Cookiecutter)**
+Instead of cloning complex repos, the developer runs:
+`platform create my-service --stack node-express --db postgres`
 
-### Developer Experience & Self-Service
-*   **Developer Experience:** Self-service portal design, Onboarding automation, IDE integration plugins, CLI tool development.
-*   **Self-Service Capabilities:** Environment provisioning, Database creation, Service deployment, Access management.
-*   **Service Catalog:** Backstage implementation, Software templates, Component registry, Tech radar maintenance.
-
-### Golden Paths & Platform APIs
-*   **Golden Paths:** Service scaffolding, CI/CD pipeline templates, Security scanning integration, Best practices enforcement.
-*   **Platform APIs:** RESTful API design, Event streaming setup, Rate limiting implementation, SDK generation.
-*   **Developer Enablement:** Documentation portals, Success tracking, Workshop delivery.
+This command:
+1. Generates the standard Node/Express repo.
+2. Applies the unified corporate CI/CD GitHub Action.
+3. Configures default Datadog/OpenTelemetry observability metrics.
+4. Generates a Terraform blueprint to provision the RDS Postgres instance.
 
 ---
 
-## Output Format
-
-When this skill produces a recommendation or design decision, structure your output as:
-
-```
-━━━ Platform Engineer Recommendation ━━━━━━━━━━━━━━━━
-Decision:    [what was chosen / proposed]
-Rationale:   [why — one concise line]
-Trade-offs:  [what is consciously accepted]
-Next action: [concrete next step for the user]
-─────────────────────────────────────────────────
-Pre-Flight:  ✅ All checks passed
-             or ❌ [blocking item that must be resolved first]
+## 2. GitOps (Declarative State Synchronization)
+
+Platform Engineers do not log into AWS consoles to click buttons. They do not run `kubectl apply` from their laptops.
+
+They push code to Git. A continuous reconciliation loop (e.g., ArgoCD) syncs the live infrastructure to match the Git repository mathematically.
+
+```yaml
+# GitOps standard architecture (ArgoCD)
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: auth-service
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: 'https://github.com/mycorp/infrastructure-ops'
+    path: k8s/auth-service
+    targetRevision: HEAD # Automatically deploys any merge to main
+  destination:
+    server: 'https://kubernetes.default.svc'
+    namespace: auth-prod
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true # If manual changes occur on cluster, force-reverts back to Git state
 ```
 
-
 ---
 
-## 🏛️ Tribunal Integration (Anti-Hallucination)
+## 3. Infrastructure as Code (IaC) Modules
 
-**Slash command: `/tribunal-backend`**
-**Active reviewers: `logic` · `security`**
+Platform Engineers build reusable Terraform/Tofu modules, hiding extreme complexity from product developers.
 
-### ❌ Forbidden AI Tropes in Platform Engineering
-1. **Platform Monoliths** — never design internal platforms as tightly coupled monoliths; mandate decoupled, API-first self-service modules.
-2. **Missing Golden Path Flexibility** — do not generate developer templates that lock teams into specific versions without an override mechanism (Golden Path vs. Golden Cage).
-3. **Ticket-Ops Paradigms** — do not design processes that require Jira/ITSM ticket approvals for routine environment provisioning; push towards self-service automation.
-4. **Ignoring Platform Docs** — never omit READMEs, interactive API docs, or Backstage catalog entries for newly created internal services.
-5. **Over-Abstraction Without Need** — avoid wrapping standard tools (like native Kubernetes YAML or pure Terraform) in complex proprietary CLI abstractions unless developer cognitive load dictates it.
+```hcl
+# The Platform Engineer writes the complex module (e.g., VPC, Subnets, IAM, KMS Encryptions)
+# The Product Developer simply consumes the module cleanly:
 
-### ✅ Pre-Flight Self-Audit
+module "product_database" {
+  source  = "github.com/mycorp/tf-modules/secure-rds"
+  version = "v1.2.0"
 
-Review these questions before generating platform engineering architecture or IDPs:
-```text
-✅ Did I design the workflow as a true self-service process that eliminates manual hand-offs?
-✅ Does the GitOps flow include automated checks for secrets and compliance before syncing?
-✅ Are the Golden Path templates extensible and versioned?
-✅ Have I properly isolated resources in the multi-tenant architecture proposal?
-✅ Are there built-in mechanisms for cost-visibility and telemetry tracking on generated developer environments?
+  app_name      = "checkout-service"
+  capacity      = "medium"           # Abstracts complex instance sizing
+  needs_replica = true               # Abstracts failover architecture
+}
 ```
 
-
 ---
 
-## 🤖 LLM-Specific Traps
+## 4. Reducing Cognitive Load
 
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+DevOps asked product developers to learn Kubernetes, Helm, Terraform, CI/CD, and AWS IAM. The load was too high.
+Platform Engineering hides the Kubernetes complexity behind a portal (e.g., Backstage) or a declarative wrapper (e.g., Score).
 
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+Ensure your infrastructure proposals abstract away the YAML mechanics. Give the developer a simple SLA: *"Push to the `main` branch, and the platform guarantees deployment, logs, and metrics within 3 minutes."*
 
 ---
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
-
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before confirming output:
-```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
-```
-
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

package/.agent/skills/playwright-best-practices/SKILL.md

@@ -1,81 +1,128 @@
----
-name: playwright-best-practices
-description: End-to-end testing expert specializing in Playwright. Focuses on robust selectors, auto-waiting, parallelization, and reducing flaky tests.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-30
-applies-to-model: claude-3-7-sonnet, gemini-2.5-pro
----
-
-# Playwright Best Practices
-
-You are an expert in End-to-End (E2E) testing utilizing Playwright. Your goal is to write deterministic, resilient, and fast testing suites that provide extreme confidence in application behavior.
-
-## Core Directives
-
-1. **Locator Strategy:**
-   - Always prefer user-facing locators: `getByRole`, `getByText`, `getByLabel`.
-   - Never use XPath or highly coupled CSS selectors (e.g., `.container > div > span`) unless absolutely necessary.
-   - For components needing strict test-binding, use `data-testid` via `getByTestId`.
-
-2. **Auto-Waiting & Assertions:**
-   - Playwright automatically waits for elements to be actionable. Never insert explicit `page.waitForTimeout(5000)` unless debugging.
-   - Use web-first assertions: `await expect(locator).toBeVisible()`, `await expect(locator).toHaveText()`. Do not use standard Node.js assertions `assert(true)` for DOM state.
-
-3. **Authentication & Setup:**
-   - Utilize global setup (`globalSetup` or `test.beforeAll`) for authentication.
-   - Save the authentication state (cookies/local storage) into a reusable state file (e.g., `playwright/.auth/user.json`) to skip login UI flows during testing.
-
-4. **Parallelization & Structure:**
-   - Group related tests logically using `test.describe`.
-   - Keep tests independent. Tests should not rely on state mutated by previous tests.
-   - Clean up data after tests using `test.afterEach` or isolated contexts.
-
-## Output Format
-
-When creating or modifying tests:
-1. Explain the User Journey being tested.
-2. Outline the steps and assertions.
-3. Provide the full test code incorporating the best practices above.
+---
+name: playwright-best-practices
+description: Playwright End-to-End (E2E) testing mastery. Resilient selectors, auto-waiting mechanisms, parallel test execution, mocking network requests, fixture management, and cross-browser CI configurations. Use when configuring, deploying, or writing E2E web tests.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0.0
+last-updated: 2026-04-02
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
 
+# Playwright E2E — Bulletproof Testing Mastery
 
 ---
 
-## 🤖 LLM-Specific Traps
+## 1. Resilience & Auto-Waiting
+
+Playwright automatically waits for elements to be actionable (visible, stable, not obscured).
 
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+```typescript
+// ❌ FLAKY: Hardcoded sleeps. Fails on slow CI, wastes time on fast local rings.
+await page.waitForTimeout(3000); 
 
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+// ❌ FLAKY: CSS selectors tied to layout/styling changes
+await page.locator('.btn-primary > span').click();
+
+// ✅ ROBUST: Playwright auto-waits for actionability based on user-centric selectors
+await page.getByRole('button', { name: "Submit Checkout" }).click();
+
+// ✅ ROBUST: Testing for expected states 
+await expect(page.getByText('Order confirmed')).toBeVisible();
+```
+
+### The Selector Hierarchy (Best to Worst)
+1. `page.getByRole()` — Checks accessibility simultaneously.
+2. `page.getByText()` — Finds elements by raw text values.
+3. `page.getByTestId()` — Resilient to text/translation updates (`data-testid`).
+4. `page.locator('css')` — Brittle, bound to DOM structures. Use only as last resort.
 
 ---
 
-## 🏛️ Tribunal Integration (Anti-Hallucination)
+## 2. Test Isolation & Fixtures
 
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
+Do not cascade tests (where Test B requires Test A to pass first). Playwright gives every test a blank browser context isolated from the rest.
 
-### ❌ Forbidden AI Tropes
+```typescript
+import { test, expect } from '@playwright/test';
 
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+// ❌ BAD: Cascading state
+test.describe('Dashboard', () => {
+  test('Login', async ({ page }) => {
+    await login(page); // Next test assumes this succeeded
+  });
+  test('Action', async ({ page }) => {
+    await page.getByRole('button', { name: 'Save' }).click(); 
+  });
+});
 
-### ✅ Pre-Flight Self-Audit
+// ✅ GOOD: Isolated tests via beforeEach or Custom Fixtures
+test.beforeEach(async ({ page }) => {
+  // Login directly via API to bypass slow UI login, seeding cookies
+  await performFastApiLogin(page);
+  await page.goto('/dashboard');
+});
 
-Review these questions before confirming output:
+test('Should save settings', async ({ page }) => {
+  await page.getByRole('button', { name: 'Save' }).click();
+  await expect(page.getByRole('alert')).toHaveText('Saved successfully');
+});
 ```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
+
+---
+
+## 3. Network Mocking
+
+E2E tests that rely on external 3rd party APIs (Stripe, SendGrid) will fail randomly due to network latency outside your control.
+
+```typescript
+test('Should block invalid credit cards', async ({ page }) => {
+  // Intercept the outgoing request to the payment processor
+  await page.route('**/api/v1/charge*', async route => {
+    // Return a mocked failure response immediately
+    const json = { status: 'declined', message: 'Insufficient funds' };
+    await route.fulfill({ status: 400, json });
+  });
+
+  await page.getByRole('button', { name: 'Purchase' }).click();
+  await expect(page.getByText('Insufficient funds')).toBeVisible();
+});
 ```
 
-### 🛑 Verification-Before-Completion (VBC) Protocol
+---
+
+## 4. Configuration for CI/CD
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,   // Run tests concurrently
+  forbidOnly: !!process.env.CI, // Fail build if `.only` was left in code
+  retries: process.env.CI ? 2 : 0, // Retry flakes on CI only
+  workers: process.env.CI ? 1 : undefined, // Reduce CI overload
+  reporter: 'html',
 
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+  use: {
+    trace: 'on-first-retry', // Record trace viewer ONLY on failure to save space
+    video: 'retain-on-failure',
+    baseURL: 'http://localhost:3000',
+  },
+
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+    // Mobile Viewport Example
+    { name: 'Mobile Safari', use: { ...devices['iPhone 13'] } },
+  ],
+
+  // Spin up local server before running tests
+  webServer: {
+    command: 'npm run build && npm run start',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+---