@ryuenn3123/agentic-senior-core 6.15.1 → 6.16.1

package/.agents/plugins/agentic-senior-core/skills/asc-reference/references/database.md

@@ -0,0 +1,97 @@
+# Database Engineering: Indexing, Transactions & Migrations
+
+Relational and document databases underpin application state. High-traffic systems fail most frequently at the database boundary.
+
+---
+
+## 1. Indexing Strategies & Query Optimization
+
+Indexes turn full table scans ($O(N)$) into logarithmic tree lookups ($O(\log N)$). Unindexed queries are the primary source of production latency spikes.
+
+### 1.1 Index Placement Rules
+- **Foreign Keys:** Always index foreign key columns (`author_id`, `org_id`). Database engines do not automatically index foreign keys, leading to full table scans during cascade checks and joins.
+- **Filter & Sort Predicates:** Index columns present in `WHERE`, `ORDER BY`, and `GROUP BY` clauses.
+- **Leftmost Prefix Rule for Composite Indexes:** An index on `(org_id, status, created_at)` accelerates:
+  - `WHERE org_id = ?`
+  - `WHERE org_id = ? AND status = ?`
+  - `WHERE org_id = ? AND status = ? ORDER BY created_at`
+  - *It does NOT accelerate:* `WHERE status = ?` alone. Order columns by cardinality and filter frequency.
+
+### 1.2 Partial Indexes
+Save index size and write overhead by indexing only active rows:
+```sql
+-- Accelerates lookups for active users without indexing millions of deleted rows
+CREATE INDEX idx_users_active_email ON users (email) WHERE deleted_at IS NULL;
+```
+
+---
+
+## 2. N+1 Query Prevention
+
+Never execute database queries inside an application loop:
+
+```typescript
+// BANNED: 1 initial query + N separate queries for authors
+const posts = await db.posts.findMany();
+for (const post of posts) {
+  post.author = await db.users.findUnique({ where: { id: post.authorId } });
+}
+
+// ENFORCED: 1 query with join or batch preload
+const posts = await db.posts.findMany({
+  include: { author: true }
+});
+```
+
+---
+
+## 3. Transaction Boundaries & Concurrency Control
+
+Any operation modifying more than one table, or reading state to calculate a mutation, must be guarded by an ACID transaction.
+
+### 3.1 Lost Update Prevention (Pessimistic Locking)
+When decrementing balances or claiming inventory, reading then writing in two queries creates a race condition:
+
+```sql
+-- BANNED: Two concurrent requests read balance = 100, both deduct 50, final balance 50 instead of 0
+SELECT balance FROM accounts WHERE id = 1;
+UPDATE accounts SET balance = balance - 50 WHERE id = 1;
+
+-- ENFORCED: Pessimistic Row Lock inside transaction
+BEGIN;
+SELECT balance FROM accounts WHERE id = 1 FOR UPDATE;
+-- Validate balance >= 50
+UPDATE accounts SET balance = balance - 50 WHERE id = 1;
+COMMIT;
+```
+
+---
+
+## 4. Zero-Downtime Migrations: The Expand-and-Contract Pattern
+
+Never perform breaking schema alterations (renaming columns, changing column types, deleting columns) in a single deployment step. Use the Expand-and-Contract pattern across three deployments:
+
+```
+Deployment 1 (Expand)        Deployment 2 (Migrate & Read)    Deployment 3 (Contract)
+──────────────────────       ────────────────────────────     ───────────────────────
+Add new column `new_col`     Application writes both cols     Drop old column `old_col`
+Application writes both      Reads from `new_col`             Remove dual-write logic
+Backfill historical data     All code points to `new_col`     Migration complete
+```
+
+### 4.1 Migration Invariants
+- **Non-blocking Index Creation:** In PostgreSQL, always use `CREATE INDEX CONCURRENTLY` to avoid locking the table against writes. Set a statement lock timeout: `SET lock_timeout = '5s'`.
+- **Never Edit Merged Migrations:** Once a migration has been committed and run in shared environments, treat it as immutable. Author a new corrective migration instead.
+- **Reversibility:** Every migration must provide a valid `down` step that reverses schema modifications cleanly.
+
+---
+
+## 5. Data Types: Precision & Time
+
+1. **Monetary Amounts:**
+   - **Strictly Banned:** `FLOAT`, `DOUBLE`, `REAL`. Floating-point arithmetic produces rounding inaccuracies (`0.1 + 0.2 = 0.30000000000000004`).
+   - **Enforced:** Integer minor units (e.g. storing USD as integer cents: `$19.99` $\to$ `1999`) or exact fixed-point `NUMERIC(18, 4)`.
+2. **Timestamps:**
+   - Store all timestamps in UTC with timezone: `TIMESTAMPTZ` (Postgres) or ISO-8601 UTC strings (`2026-11-04T10:00:00Z`).
+   - Never store naive local times without timezone offset.
+

package/.agents/plugins/agentic-senior-core/skills/asc-reference/references/infrastructure.md

@@ -0,0 +1,102 @@
+# Infrastructure, Containers & CI/CD Engineering
+
+Robust infrastructure isolates workloads, prevents credential leakage, scales predictably, and fails gracefully.
+
+---
+
+## 1. Container Architecture & Docker Hygiene
+
+Containers must be minimal, stateless, secure, and reproducible.
+
+### 1.1 Multi-Stage Build Pattern
+Separate compilation dependencies from runtime artifacts to produce lightweight, hardened production images:
+
+```dockerfile
+# Stage 1: Build & Dependencies
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --ignore-scripts
+COPY . .
+RUN npm run build && npm prune --production
+
+# Stage 2: Hardened Minimal Runtime
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+
+# Security: Run as unprivileged non-root user
+USER node
+
+# Copy only production artifacts
+COPY --chown=node:node --from=builder /app/package.json ./
+COPY --chown=node:node --from=builder /app/node_modules ./node_modules
+COPY --chown=node:node --from=builder /app/dist ./dist
+
+EXPOSE 3000
+CMD ["node", "dist/server.js"]
+```
+
+### 1.2 Container Security Rules
+1. **Never run as root:** Always specify `USER node`, `USER 10001:10001`, or an unprivileged system user. Root access inside a container increases the severity of container-escape vulnerabilities.
+2. **Zero baked secrets:** Never copy `.env`, private SSH keys, or cloud access tokens into image layers. Pass secrets at runtime via environment variables or secret managers.
+3. **Comprehensive `.dockerignore`:** Always ignore `.git`, `node_modules`, `.env*`, test coverage reports, and scratch directories.
+
+---
+
+## 2. 12-Factor Configuration & Startup Validation
+
+Store all configuration in environment variables. Applications must validate configuration at boot time and fail immediately if required values are missing.
+
+### 2.1 Startup Validation Schema
+```typescript
+import { z } from 'zod';
+
+const EnvSchema = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'production']),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  REDIS_URL: z.string().url(),
+  API_SECRET_KEY: z.string().min(32),
+});
+
+// Fail fast before opening ports or listening to queues
+export const env = EnvSchema.parse(process.env);
+```
+
+- **Fail Fast:** If `DATABASE_URL` is missing, the application must crash with exit code 1 immediately with a descriptive error. Never start partially and fail on the first incoming user request.
+
+---
+
+## 3. Observability & Health Probes
+
+### 3.1 Separate Liveness and Readiness Probes
+Kubernetes and container orchestrators need distinct signals:
+- **Liveness Probe (`/healthz`):** Is the process running and not deadlocked? Returns `200 OK`. If failing, the orchestrator restarts the container.
+- **Readiness Probe (`/readyz`):** Can the container accept external traffic? Checks database connectivity, cache warming, and migration status. If failing, traffic is redirected without restarting the process.
+
+### 3.2 Structured JSON Logging
+Production logs must be formatted as single-line JSON objects to enable ingestion and querying by log aggregators:
+
+```json
+{
+  "timestamp": "2026-11-04T10:14:02.184Z",
+  "level": "info",
+  "message": "Deployment completed",
+  "trace_id": "c4b9-482a-912b",
+  "project_id": "proj_9021",
+  "duration_ms": 342
+}
+```
+
+- Always inject correlation/trace IDs to trace requests across microservices.
+- **Never log PII or credentials:** Sanitize passwords, tokens, API keys, and credit card numbers before logging.
+
+---
+
+## 4. Deterministic CI/CD Pipelines
+
+1. **Deterministic Lockfiles:** Always use lockfile-enforced installation (`npm ci`, `poetry install --no-root`, `cargo check --locked`).
+2. **Pipeline Caching:** Cache package manager directories (`~/.npm`, `~/.cache/pip`, `~/.cargo`) across pipeline runs.
+3. **Fail-Closed Pipelines:** CI must halt immediately upon test failures, linter errors, or type errors. Never permit broken builds to deploy to staging or production.
+

package/.agents/plugins/agentic-senior-core/skills/asc-reference/references/resilience.md

@@ -0,0 +1,87 @@
+# Service Resilience: Timeouts, Backoff & Circuit Breakers
+
+Distributed systems fail continuously. Resilience engineering ensures failures in one dependency do not cause cascading outages across the entire application ecosystem.
+
+---
+
+## 1. Network Timeouts: The Zero-Hang Rule
+
+Every outbound network call (HTTP, RPC, database, cache) must specify an explicit timeout. A network call without a timeout will eventually hang indefinitely under socket partition, exhausting application worker threads.
+
+- **Connection Timeout:** Time allowed to establish the TCP connection (e.g., 2,000ms).
+- **Read Timeout:** Time allowed for the remote service to return the response body (e.g., 5,000ms).
+- **Total Request Timeout:** Upper bound on the entire lifecycle (e.g., 8,000ms).
+
+```typescript
+// Enforced: Explicit timeout with AbortSignal
+const controller = new AbortController();
+const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+try {
+  const response = await fetch('https://api.external.com/v1/rates', {
+    signal: controller.signal,
+  });
+  return await response.json();
+} finally {
+  clearTimeout(timeoutId);
+}
+```
+
+---
+
+## 2. Exponential Backoff with Full Jitter
+
+When a network operation fails transiently, retrying immediately floods the struggling service (the "thundering herd" problem).
+
+### 2.1 The Full Jitter Formula
+$$T = \text{random}(0, \min(T_{\max}, T_{\text{base}} \times 2^{\text{attempt}}))$$
+
+```typescript
+function calculateJitteredBackoff(attempt: number, baseMs = 100, maxMs = 5000): number {
+  const exponential = Math.min(maxMs, baseMs * Math.pow(2, attempt));
+  return Math.floor(Math.random() * exponential);
+}
+```
+
+### 2.2 Retry Conditions
+- **Only retry idempotent operations:** Safe to retry `GET`, `PUT`, `DELETE`, or requests carrying a verified `Idempotency-Key`.
+- **Never retry non-idempotent `POST` requests without idempotency keys:** Retrying a non-idempotent payment charge will charge the customer twice.
+- **Retry transient status codes only:** Retry `503 Service Unavailable`, `504 Gateway Timeout`, or network connection reset (`ECONNRESET`). Never retry client validation errors (`400`, `401`, `403`, `422`).
+
+---
+
+## 3. Circuit Breaker State Machine
+
+Prevent a failing downstream dependency from bringing down upstream services by short-circuiting calls when the failure rate exceeds a threshold:
+
+```
+          ┌────────────────────────────────────────┐
+          │                                        │
+          ▼                                        │
+    ┌───────────┐      Failure threshold reached   │ Probe succeeds
+    │  CLOSED   │ ───────────────────────────────► │
+    └───────────┘                                  │
+          ▲                                        ▼
+          │         Cooldown timer elapsed   ┌───────────┐
+          │       ┌───────────────────────── │   OPEN    │
+          │       ▼                          └───────────┘
+    ┌───────────┐
+    │ HALF-OPEN │ ───────────────────────────────► Trip on probe failure
+    └───────────┘
+```
+
+1. **Closed (Normal):** Requests pass through. Metrics track consecutive failures.
+2. **Open (Tripped):** When error rate exceeds threshold (e.g. 5 failures within 10s), the circuit trips. All calls fail fast immediately without making network calls.
+3. **Half-Open (Trial):** After a cooldown period (e.g. 30s), a limited number of probe requests are allowed through. If successful, the circuit resets to Closed; if failing, it trips back to Open.
+
+---
+
+## 4. Hard vs. Soft Dependency Classification
+
+Classify external dependencies into two categories before writing fallback code:
+
+| Category | Definition | Operational Response |
+|---|---|---|
+| **Hard Dependency** | Core system cannot complete the transaction without it (e.g., Primary database for auth). | Fail fast, roll back local transactions, return structured RFC 9457 error with actionable explanation. |
+| **Soft Dependency** | Secondary feature that enriches experience but is not critical to the core transaction (e.g., Recommendations, avatar image fetch). | Fall back to static safe defaults, stale cache (`stale-while-revalidate`), or degraded mode with zero disruption to the primary journey. |
+

package/.agents/plugins/agentic-senior-core/skills/asc-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: asc-review
 description: >
-  Trigger this skill when the user is: reviewing pull requests, checking recent changes, auditing security, scanning for vulnerabilities, threat modeling, or detecting duplicate code. Trigger when the user says: "review this code", "check this PR", "what's wrong with this", "look at my changes", "is this production-ready", "find bugs", "audit this", "security check", "find vulnerabilities", "check for XSS", "check for SQL injection", "OWASP check", "check auth", "find duplicate code", "check for clones", "audit for duplication", "review PR ini", "cek kodingan saya", "cari celah keamanan", "cari kode duplikat". Covers Code Review, Security Audit, and Duplicate Detection.
+  Trigger this skill when the user is: reviewing pull requests, checking recent changes, auditing security, scanning for vulnerabilities, threat modeling, or detecting duplicate code. Trigger when the user says: "review this code", "check this PR", "what's wrong with this", "look at my changes", "is this production-ready", "find bugs", "audit this", "security check", "find vulnerabilities", "check for XSS", "check for SQL injection", "OWASP check", "check auth", "find duplicate code", "check for clones", "audit for duplication", "review PR ini", "cek kodingan saya", "cari celah keamanan", "cari kode duplikat".
 ---
 
 # Quality & Security Assurance Playbook (`asc-review`)
@@ -12,14 +12,27 @@ Grounded in: OWASP Top 10 (2025), OWASP ASVS v5.0, OWASP Agentic Applications (A
 
 ---
 
-## Mode 1: Production Code Review
+## 1. Claim Verification Gate
+
+Never accept claims of correctness or test coverage without fresh execution evidence:
+
+| Claim | Requires (Sufficient Evidence) | NOT Sufficient (Invalid Evidence) |
+|---|---|---|
+| *"Code works / Bug fixed."* | A reproduction test failed before the fix, passes with it, and full test suite passes. | *"The code looks correct."*<br>*"It compiled without warnings."* |
+| *"All tests pass."* | Fresh test suite run in the current session with exit code 0 and 0 failures. | *"Tests passed in a previous turn."*<br>*"I only modified a comment."* |
+| *"Zero security vulnerabilities."* | Parameterized query checks, auth checks, and dependency audit tool output. | *"I used an ORM so it's safe."* |
+| *"No duplicate code."* | Lexical or token dedup scan with Rule of Three enforcement. | *"I don't recall copying this."* |
+
+---
+
+## 2. Mode 1: Production Code Review
 
 Use when reviewing PRs, diffs, commits, or newly written feature code.
 
 ### Review Procedure
 1. **Scope Inspection**: Run `git diff --stat` (or `git status`) to inspect modified files and line deltas.
-2. **Test-Change Correlation**: For every modified application logic file, verify that a corresponding test was updated. If logic changed without tests, report as a missing test finding.
-3. **Deterministic Verification**: Run project linter and test suite (`ascx test` / `npm test`).
+2. **Test-Change Correlation**: For every modified application logic file, verify that a corresponding test was updated. If logic changed without tests, flag as missing test coverage.
+3. **Deterministic Verification**: Run project linter and test suite (`ascx test` / `npm test`). Confirm exit code 0 fresh.
 4. **Severity Priority Order**:
    - **Severity 1 (Critical)**: Correctness, data corruption, auth/permission bypass, security sinks, PII leakage.
    - **Severity 2 (High)**: Action feedback failures (hanging spinners, unhandled mutations, missing error boundaries), unhandled async rejections, missing remote timeouts.
@@ -28,7 +41,7 @@ Use when reviewing PRs, diffs, commits, or newly written feature code.
 
 ---
 
-## Mode 2: Security & Vulnerability Audit
+## 3. Mode 2: Security & Vulnerability Audit
 
 Use when assessing trust boundaries, reviewing auth systems, running threat models, or auditing external dependencies.
 
@@ -48,7 +61,7 @@ Use when assessing trust boundaries, reviewing auth systems, running threat mode
 
 ---
 
-## Mode 3: Clone & Code Duplication Audit
+## 4. Mode 3: Clone & Code Duplication Audit
 
 Use when evaluating copy-paste repetition or consolidating duplicated logic across a repository.
 
@@ -61,7 +74,7 @@ Use when evaluating copy-paste repetition or consolidating duplicated logic acro
 
 ---
 
-## Output Format for Findings
+## 5. Output Format for Findings
 
 Report findings ordered strictly by severity with file and line references:
 

package/.agents/plugins/agentic-senior-core/skills/asc-test/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: asc-test
+description: >
+  Trigger this skill when the user is: writing unit tests, integration tests, E2E tests, UAT checklists, reproducing bugs, fixing flaky tests, or verifying test coverage. Also trigger when the user says: "write a test", "TDD", "add tests", "verify this bug", "flaky test", "test this endpoint", "E2E test", "playwright", "UAT", "regression test", "bikin tes", "cara ngetes", "tes gagal terus". Also trigger when creating or editing files matching: `*.test.*`, `*.spec.*`, `tests/*`, `__tests__/*`, or `e2e/*`.
+---
+
+# Testing, TDD, Verification & UAT Router
+
+Staff-grade testing playbook and verification gates. Enforces test-first discipline and routes deep testing guidance on demand.
+
+---
+
+## 1. The Iron Law of TDD
+
+> **THE IRON LAW:** No production code shall be written without a failing test first.
+
+Every feature, bugfix, or refactor must follow the Red-Green-Refactor sequence:
+1. **RED:** Write a minimal failing test. Execute it and confirm it fails for the expected reason.
+2. **GREEN:** Write the minimum production code necessary to make the test pass.
+3. **REFACTOR:** Clean up code structure while keeping the test suite green.
+
+---
+
+## 2. The Verification Gate & Pre-Flight Ingestion (BLOCKING)
+
+> [!IMPORTANT]
+> **Reference Path Resolution:**
+> Reference files do NOT reside in the user workspace root. They are located adjacent to this `SKILL.md` file:
+> `<skill_directory>/references/<file>.md`
+> Prepend this skill's directory path when calling `read_file`.
+
+Before writing tests, running suites, or claiming verification:
+1. **Mandatory Ingestion (BLOCKING GATE):** Call `read_file` on the tier reference matching your testing requirement BEFORE taking action:
+   - Writing unit tests / TDD cycle ➔ `references/tdd-cycle.md`
+   - Behavior testing, boundary isolation, mocks/fakes ➔ `references/test-design.md`
+   - Playwright browser tests, locators, page objects ➔ `references/e2e-playwright.md`
+   - Acceptance criteria, UAT checklists, edge case quads ➔ `references/uat.md`
+   - Bug reproduction, root-cause verification, regression proof ➔ `references/regression-proof.md`
+   - Flaky tests, timing race conditions, 50-run stress loop ➔ `references/flaky-tests.md`
+   *Do NOT write test assertions or declare claims until this reference is loaded.*
+
+2. **Never make a claim regarding test status without fresh execution evidence:**
+
+```
+┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
+│ 1. IDENTIFY CMD  │ ───► │  2. RUN FRESH    │ ───► │ 3. CONFIRM CLAIM │
+└──────────────────┘      └──────────────────┘      └──────────────────┘
+Locate exact test         Execute runner, read      State pass/fail with
+command in project        exit code directly        raw exit code & logs
+```
+
+1. **Identify the Command:** Determine the exact test command from `package.json`, `Makefile`, `pytest.ini`, or project manifests.
+2. **Execute Fresh:** Run the command in the current turn. Past execution results or assumptions are invalid.
+3. **Confirm Claim:** Read the raw exit code and failed assertion count before reporting results.
+
+---
+
+## 3. Rationalization Prevention Table
+
+| Rationalization | Fallacy | Operational Rule |
+|---|---|---|
+| *"The change is too trivial to test."* | Trivial changes cause silent regressions. | Write the test. If it takes 2 minutes to write the fix, it takes 2 minutes to write the test. |
+| *"I'll write tests after the code works."* | Tests written after mirror bugs. | Write the failing assertion before implementing the behavior. |
+| *"It's just UI / frontend wiring."* | Visual wiring has state logic. | Form validation, button states, and error handling are pure logic and testable. |
+| *"Mocking this dependency is too hard."* | Architecture smells. | Difficulty in testing indicates tight coupling. Extract pure functions or use in-memory fakes. |
+| *"Tests take too long to run."* | Slowness masks bugs. | Run the focused sub-suite during development; run the full suite before handoff. |
+
+---
+
+## 4. Testing Decision Tree
+
+Select the lowest testing tier that validates the requirement:
+
+```
+                       Is this pure business logic or algorithm?
+                                     │
+                     ┌───────────────┴───────────────┐
+                    YES                              NO
+                     │                               │
+             ┌───────────────┐        Does it involve database, cache, or HTTP APIs?
+             │ 1. UNIT TEST  │                       │
+             └───────────────┘               ┌───────┴───────┐
+                                            YES              NO
+                                             │               │
+                                     ┌───────────────┐   Does it involve browser UI or
+                                     │2. INTEGRATION │   multi-step user journeys?
+                                     └───────────────┘       │
+                                                     ┌───────┴───────┐
+                                                    YES              NO
+                                                     │               │
+                                             ┌───────────────┐ ┌───────────┐
+                                             │ 3. E2E (TEST) │ │  4. UAT   │
+                                             └───────────────┘ └───────────┘
+```
+
+---
+
+## 5. On-Demand Reference Library
+
+> [!IMPORTANT]
+> **Resolution Note:** All paths below are relative to this `SKILL.md` file's parent folder (`.../skills/asc-test/`). Prepend this skill's directory path when calling `read_file`.
+
+| Testing Domain / Trigger | Mandatory Reference Path |
+|---|---|
+| Red-Green-Refactor mechanics & whole-suite checks | `references/tdd-cycle.md` |
+| Behavior testing, boundary isolation & mocking | `references/test-design.md` |
+| Playwright E2E, reconnaissance & locator hierarchy | `references/e2e-playwright.md` |
+| Given/When/Then acceptance criteria & edge case quad | `references/uat.md` |
+| 3-step bugfix verification & regression proof | `references/regression-proof.md` |
+| Flakiness root causes & 50-run stress loop | `references/flaky-tests.md` |
+
+---
+
+## 6. Verification & Handoff Sweep
+
+Before declaring any coding or testing task complete:
+1. **Reference Compliance:** Confirm constraints from the loaded `references/*.md` file were applied.
+2. **Regression Proof:** For bugfixes, confirm the test failed without the fix and passes with it.
+3. **Whole-Suite Run:** Execute the full test suite (`ascx npm test` or project test runner); confirm exit code 0.
+4. **No Assertions Weakened:** Verify no existing test assertions were deleted or commented out to simulate success.
+5. **Hermetic State:** Ensure tests clean up temporary files, database records, and environment variables.
+

package/.agents/plugins/agentic-senior-core/skills/asc-test/references/e2e-playwright.md

@@ -0,0 +1,89 @@
+# End-to-End (E2E) & Playwright Testing
+
+E2E browser tests verify integrated user journeys across the full application stack (HTML, CSS, JS, network, database).
+
+---
+
+## 1. Reconnaissance Before Action
+
+Never write browser test steps by guessing selectors or UI timing.
+
+```
+┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
+│ 1. RECONNAISSANCE│ ───► │  2. VERIFY DOM   │ ───► │   3. EXECUTE     │
+└──────────────────┘      └──────────────────┘      └──────────────────┘
+Navigate to route         Capture rendered DOM      Target resilient
+Wait for networkidle      or test snapshot          user-facing locator
+```
+
+### 1.1 The Inspection Protocol
+1. **Navigate and Settle:** Navigate to the target URL and wait for asynchronous network activity to stabilize (`networkidle` or specific locator hydration).
+2. **Inspect Rendered State:** Extract the accessibility tree or screenshot to inspect the actual DOM elements currently visible to users.
+3. **Select Resilient Locators:** Use Playwright's user-facing locator hierarchy:
+   - Priority 1: `page.getByRole('button', { name: 'Deploy' })`
+   - Priority 2: `page.getByLabel('Work email')`
+   - Priority 3: `page.getByPlaceholder('Search repositories...')`
+   - Priority 4: `page.getByTestId('billing-summary-table')`
+   - **Banned:** Brittle internal CSS class selectors: `page.locator('.sc-bdVaJa > div:nth-child(2)')` or compiled Tailwind classes `page.locator('.p-4.border.rounded-xl')`.
+
+---
+
+## 2. The Ban on Arbitrary Sleep Delays
+
+Hardcoded time delays are the primary cause of flaky CI builds and slow test runs.
+
+- **Strictly Banned:**
+  ```typescript
+  // BANNED: Flaky, slow, and non-deterministic
+  await page.waitForTimeout(5000);
+  await new Promise(r => setTimeout(r, 3000));
+  ```
+
+- **Enforced: Auto-waiting and State Assertions:**
+  Playwright automatically waits for elements to be actionable (visible, stable, enabled) before clicking or filling.
+  ```typescript
+  // ENFORCED: Waits dynamically up to timeout, proceeds immediately upon readiness
+  await expect(page.getByRole('dialog')).toBeVisible();
+  await page.getByRole('button', { name: 'Confirm deletion' }).click();
+  await expect(page.getByText('Repository deleted')).toBeVisible();
+  ```
+
+---
+
+## 3. Web Server Lifecycle Management
+
+E2E tests require a running backend or frontend server.
+
+### 3.1 Playwright `webServer` Configuration
+Configure the web server within `playwright.config.ts` so Playwright manages process startup and teardown automatically:
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  webServer: {
+    command: 'npm run start',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120 * 1000,
+  },
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+  },
+});
+```
+
+### 3.2 Ephemeral Test Ports
+When running tests in parallel or in multi-branch environments, avoid hardcoded port conflicts:
+- Bind dev/test servers to port `0` or assign dynamic test ports via environment variables (`PORT=3100`).
+
+---
+
+## 4. Test State Setup: API Seeding Over UI Form Clicking
+
+Do not use browser UI steps to set up prerequisite data for every test.
+
+- **Slow & Brittle:** Logging in via UI form $\to$ clicking through 5 wizards $\to$ creating a project $\to$ finally testing the billing page.
+- **Fast & Resilient:** Seed prerequisite users, workspaces, or API keys directly via database fixtures or HTTP API calls (`request.post('/api/test/seed')`), then navigate straight to the billing page.
+

package/.agents/plugins/agentic-senior-core/skills/asc-test/references/flaky-tests.md

@@ -0,0 +1,96 @@
+# Flaky Tests Diagnosis & Remediation
+
+A flaky test is a test that exhibits both passing and failing results under identical code and execution configurations. Flaky tests erode team trust in CI and mask real production defects.
+
+---
+
+## 1. The Five Root Causes of Flakiness
+
+```
+┌────────────────────────────────────────────────────────┐
+│             THE 5 FLAKINESS ROOT CAUSES                │
+├────────────────────────────────────────────────────────┤
+│ 1. Asynchronous Race Conditions (Unawaited Promises)   │
+│ 2. Shared Mutable State (Polluted Databases or Globals)│
+│ 3. Time, Date & Timezone Leaks                         │
+│ 4. Non-Deterministic Collection Ordering               │
+│ 5. Network Latency & Port Collisions                   │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Root Cause Diagnostics & Remediation
+
+### 2.1 Asynchronous Race Conditions
+- **Symptom:** Test occasionally fails with `Cannot read property of undefined` or misses an assertion before background work finishes.
+- **Root Cause:** A fire-and-forget Promise or unawaited async operation.
+- **Remediation:** Always `await` every asynchronous call:
+  ```typescript
+  // FLAKY: Background work runs concurrently with test teardown
+  service.processQueue();
+  expect(queue.isEmpty()).toBe(true);
+
+  // DETERMINISTIC: Await completion before asserting
+  await service.processQueue();
+  expect(queue.isEmpty()).toBe(true);
+  ```
+
+### 2.2 Shared Mutable State
+- **Symptom:** Test passes when run alone, but fails when run as part of the full suite.
+- **Root Cause:** A preceding test inserted records into a database, set a global variable, or modified an in-memory cache without cleanup.
+- **Remediation:** Ensure hermetic isolation in `beforeEach` and `afterEach`:
+  ```typescript
+  afterEach(async () => {
+    await db.clean();
+    sinon.restore();
+    delete process.env.FEATURE_FLAG;
+  });
+  ```
+
+### 2.3 Time, Date & Timezone Sensitivity
+- **Symptom:** Tests fail at midnight, on month boundaries, during Daylight Saving Time (DST) transitions, or in CI runners located in UTC.
+- **Root Cause:** Direct invocation of `new Date()` or `Date.now()` without frozen timers.
+- **Remediation:** Freeze time deterministically:
+  ```typescript
+  // Use fake timers locked to a fixed UTC epoch
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-15T12:00:00Z'));
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+  ```
+
+### 2.4 Non-Deterministic Collection Ordering
+- **Symptom:** Array equality assertions fail intermittently: `Expected [1, 2], Received [2, 1]`.
+- **Root Cause:** SQL `SELECT` queries without an explicit `ORDER BY`, or iterating over JavaScript `Set` / Go `map`.
+- **Remediation:** Sort collections or compare using set equivalence:
+  ```typescript
+  // FLAKY: Relies on non-guaranteed database return order
+  expect(results.map(r => r.id)).toEqual(['id-1', 'id-2']);
+
+  // DETERMINISTIC: Explicit sorting before comparison
+  expect(results.map(r => r.id).sort()).toEqual(['id-1', 'id-2']);
+  ```
+
+---
+
+## 3. The 50-Run Stress Loop Protocol
+
+When investigating a suspected flaky test, stress-test it in isolation:
+
+```bash
+# Bash / PowerShell stress loop
+for ($i=1; $i -le 50; $i++) {
+  ascx npm test -- -t "SuspectedFlakySuite"
+  if ($LASTEXITCODE -ne 0) {
+    Write-Host "Flake detected on iteration $i"
+    break
+  }
+}
+```
+
+A test is verified fixed only when it passes 50 consecutive runs under randomized order without failure.
+