@raishin/vanguard-frontier-agentic 3.0.2 → 3.1.0

package/skills/frontend/frontend-testing-strategy-review/metadata.json

@@ -0,0 +1,27 @@
+{
+  "id": "frontend-testing-strategy-review",
+  "name": "Frontend Testing Strategy Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews unit/component/integration/E2E test-pyramid shape, coverage of critical user journeys, and flaky-test governance for a frontend codebase using Vitest/Jest, Testing Library, and Playwright/Cypress, loading framework-specific reference guidance only when needed.",
+  "source_type": "original",
+  "official_docs": [
+    "https://playwright.dev/docs/best-practices",
+    "https://vitest.dev/guide/",
+    "https://testing-library.com/docs/queries/about/#priority",
+    "https://docs.cypress.io/app/core-concepts/best-practices"
+  ],
+  "security_notes": "Never accept or request real credentials/session tokens for test fixtures; require synthetic data or mocked network layers (MSW, cy.intercept, Playwright route interception). Flag any test-only auth/CSRF bypass flag that could ship enabled in a production build as a hard-gate finding.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/frontend-testing-strategy-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/frontend-testing-strategy-review/references/e2e-framework-review.md

@@ -0,0 +1,39 @@
+# Playwright and Cypress E2E Review
+
+Use this reference for E2E-layer specifics: locator/selector strategy, web-first assertions and retry semantics, test isolation, and evidence requirements for a Cypress↔Playwright migration decision. For where an assertion belongs in the pyramid at all, see `pyramid-shape-and-coverage.md`. For root-causing an already-flaky E2E test, see `flaky-test-governance.md`.
+
+> Version note: Playwright and Cypress config APIs and CLI flags evolve across majors. Verify exact option names/defaults against the installed version via Context7 (`/microsoft/playwright`, `/cypress-io/cypress-documentation`) or the official docs before citing a config shape in a report.
+
+## Officially grounded design points
+
+**Playwright:**
+- Web-first assertions (`expect(locator).toHaveText(...)`, `.toBeVisible()`, etc.) auto-retry against the locator until the condition is met or a timeout is reached — this is the documented mechanism that removes the need for manual waits/sleeps. A test using a bare `page.locator(...)` value comparison instead of an `expect(locator).to...` assertion is not benefiting from this retry behavior.
+- `TestConfig.retries` (default `0`) controls CI-level retry-on-failure; `TestConfig.repeatEach` reruns a test N times and is documented specifically as a flaky-test debugging aid, not a production resilience setting.
+- Test isolation is a core design property — each test gets a fresh browser context by default; a suite that shares page/context state across tests (e.g. via a module-level `let page` reused without a `beforeEach` reset) is fighting the framework's isolation model and is a common source of order-dependent flake.
+
+**Cypress:**
+- `cy.get(...)` and other commands automatically retry/query until the element appears or a timeout is hit — this is native, not something the test author needs to add.
+- Cypress's own best-practices docs explicitly name `cy.wait(<fixed-ms>)` before an assertion as an anti-pattern to avoid; the documented fix is to let the trailing `.should(...)`/assertion retry instead of inserting a fixed delay.
+- Cypress's own best-practices docs recommend a dedicated `data-cy` (or equivalent `data-*`) attribute for element selection over tag/class/id selectors, specifically because tag/class/id are coupled to styling/behavior and churn independently of test intent.
+
+## Non-negotiable design rules
+
+1. **Selector strategy is accessibility-first, then a stable test hook — never CSS structure.** Prefer role/label/text queries (see `unit-component-framework-review.md` for the Testing Library query-priority list, which applies to E2E-adjacent component checks too); for pure E2E flows where role/label queries are impractical, a dedicated, styling-independent test attribute (`data-testid` for Playwright, `data-cy` for Cypress, per each tool's own convention) is the documented fallback — not `nth-child`, generated class names, or brittle text matches on copy that changes with content/locale.
+2. **No fixed waits before an assertion.** Any `page.waitForTimeout(...)` or `cy.wait(<ms>)` placed immediately before an assertion (rather than waiting on a genuine external event — a specific network response, a route change) is a flake-risk anti-pattern per both tools' own guidance. Replace with the framework's auto-retrying assertion.
+3. **Mock or intercept the network at a defined boundary; do not silently mix real and mocked calls.** `cy.intercept()` / Playwright route interception should be applied consistently for a given test — a test that mocks the primary API call but lets a background analytics/tracking call hit the real network (or vice versa) introduces nondeterminism unrelated to the behavior under test.
+4. **Reserve E2E for the small set of genuinely cross-system critical journeys.** Do not let E2E become the default place to add "one more assertion" because it's easiest to write against a running app — see `pyramid-shape-and-coverage.md` for the layer-selection rule.
+5. **State isolation between tests is the framework's job — don't fight it.** Don't reuse a `page`/session across tests for speed in a way that reintroduces order dependency; use the framework's fixture/hook lifecycle (Playwright fixtures, Cypress `beforeEach`) for setup/teardown instead of manual sharing.
+
+## Cypress → Playwright (or the reverse) migration evidence bar
+
+Do not recommend a framework switch on preference alone. Require, at minimum:
+
+- a **measured baseline**: current suite wall-clock duration in CI, current flake rate (failures not reproducible on rerun, over a stated window), and any hard blocker (e.g. multi-tab/multi-origin testing needs, which the tools support differently) driving the request,
+- an explicit statement of **what does not migrate automatically** — custom commands/plugins, CI parallelization config, visual-regression tooling integration, and existing flaky-test workarounds all need to be re-authored, not copy-pasted,
+- a **rollback path** — can the old suite keep running in parallel (even read-only, non-blocking) until the new one has proven equivalent coverage over some number of CI runs, or is this a hard cutover with no fallback if the new suite has gaps.
+
+A migration proposal missing a measured baseline or a rollback path is a rewrite driven by framework fanboyism, not evidence — push back and ask for the baseline before endorsing it.
+
+## Response discipline
+
+When reviewing E2E tests, cite the specific selector/wait/isolation pattern found (with file reference) rather than a general "selectors could be better" statement, and label whether the claim about framework retry/isolation behavior is `documentation-based` (grounded via Context7/official docs this session) or `inference`.

package/skills/frontend/frontend-testing-strategy-review/references/flaky-test-governance.md

@@ -0,0 +1,55 @@
+# Flaky-Test Diagnosis and Governance
+
+Use this reference when triaging a flaky or slow suite, reviewing quarantine (`.skip`/`fixme`/retry) usage, or setting a flake-tracking policy.
+
+## What people get wrong
+
+The naive response to a flaky test is:
+
+> "Add a retry / bump the timeout / skip it for now, we'll fix it later."
+
+That treats the symptom and destroys the signal. A retry that makes a flaky test "pass" does not make the underlying condition go away — it either hides a real race condition in the app, or hides a bad test that will keep costing CI time and eroding trust in red builds ("it's probably just flaky" is how real regressions ship).
+
+## Two root-cause categories — diagnose which one before prescribing a fix
+
+**1. Flaky because of the test:**
+- missing `await` on an async assertion or interaction,
+- a fixed sleep/wait (`cy.wait(3000)`, `await new Promise(r => setTimeout(r, 500))`) racing against real timing instead of waiting on a condition,
+- an unstable selector (nth-child, generated class name, text that changes with content/locale) that matches the wrong element or none, intermittently,
+- test-order dependency (shared mutable fixture/module state leaking between tests),
+- unmocked network call racing against a mocked one, or a mock that isn't reset between tests.
+
+**Fix:** correct the test. Playwright and Cypress both provide auto-retrying, web-first assertions (e.g. `expect(locator).toHaveText(...)`, `cy.get(...).should(...)`) specifically so a fixed wait is never necessary — Cypress's own best-practices guidance explicitly frames `cy.wait(<ms>)` before an assertion as the anti-pattern to replace with a retrying assertion. Prefer a stable, semantic selector (role/label/text, or a dedicated test-id attribute intentionally isolated from styling/behavior, e.g. Cypress's documented `data-cy` convention) over structural/CSS selectors.
+
+**2. Flaky because of the app:**
+- a genuine race condition (UI renders before data resolves, double-submit possible, state update ordering depends on network timing),
+- a timing-dependent bug that only manifests under CI load/latency, not locally.
+
+**Fix:** this is a production bug wearing a test-flake costume. The test correctly caught it. Do not "fix" this by adding a retry to the test — that ships the bug and just makes the test stop catching it. Escalate as an app defect finding, not a test-infra finding.
+
+Do not accept "just retry it" as a fix without first determining which category applies. A retry that happens to make a test-side-race pass is masking a bug in the test; a retry that makes an app-side race pass is masking a bug in the product.
+
+## Quarantine governance
+
+Treat every `.skip`, `it.skip`, `describe.skip`, `test.fixme`, `xit`, or Cypress config-level `retries` override used to suppress a known-flaky test as a **tracked liability**, not a resolved state. For each instance found, the finding must record:
+
+- **owner** — who is responsible for un-quarantining it,
+- **reason** — why it's flaky (from the root-cause categories above, if known; "unknown" is an acceptable but explicit answer),
+- **expiry/tracking** — a linked issue or a stated re-review date; a skip with no linked issue and no date is an **untracked liability** and should be flagged as such, at elevated severity if the skipped test covers a critical user journey (see `pyramid-shape-and-coverage.md`).
+
+A quarantine with none of the above is worse than an honestly-failing test: it produces false confidence in a currently-green suite.
+
+## Playwright-specific retry configuration
+
+Playwright's `TestConfig.retries` sets a maximum retry count for failed tests (default `0`, no retries) and `TestConfig.repeatEach` reruns each test N times, which the official docs frame explicitly as a *debugging* tool for flaky tests, not a permanent fix. A production CI config with `retries` set above 0 is a legitimate resilience buffer against genuine infra noise (network blips in a real CI runner) — but retries silently masking a *reproducible* failure (fails 100% of the time without the retry) is a different problem and should be flagged separately from noise-tolerance retries.
+
+> Verify the exact current default and config shape for `retries`/`repeatEach` against the installed Playwright version via Context7 or `official_docs` before citing a specific number in a report — these are config surface, not folklore.
+
+## Response discipline
+
+When reporting a flaky-test finding, state:
+
+- which root-cause category it falls into (test-side vs app-side), with the specific evidence (missing await, fixed wait, unstable selector, or a described race condition),
+- current quarantine status and whether it is tracked (owner + expiry) or untracked,
+- whether the flaky test covers a critical user journey (elevates severity if so — see `pyramid-shape-and-coverage.md`),
+- the minimal fix (stabilize the test) vs the escalation (file an app-defect finding) — do not conflate the two into a single "add retries" recommendation.

package/skills/frontend/frontend-testing-strategy-review/references/pyramid-shape-and-coverage.md

@@ -0,0 +1,62 @@
+# Test Pyramid Shape and Critical-Path Coverage
+
+Use this reference when classifying the unit:component:E2E ratio of a suite, deciding which layer a given assertion belongs at, or auditing whether critical user journeys actually have coverage.
+
+## What people get wrong
+
+The naive story is:
+
+> "We have 2,000 tests and 85% coverage, so the suite is solid."
+
+That number says nothing about shape or what those tests actually assert. Two failure patterns hide behind a healthy-looking coverage number:
+
+1. **Ice-cream-cone shape** — few unit tests, a moderate component layer, and a huge, slow, brittle E2E layer that re-proves logic the unit layer should own. This is slow CI, high flake surface, and expensive maintenance for marginal confidence gain.
+2. **Hollow pyramid** — lots of unit tests, but they assert on implementation details (internal state, private methods, snapshot diffs of unrelated markup) instead of behavior, so a real regression in user-facing behavior can still ship green.
+
+Coverage percentage cannot distinguish either failure from a healthy suite. Only reading the tests can.
+
+## Classifying the shape
+
+Count actual test files/cases per layer, don't accept a verbal estimate:
+
+- **Unit** — pure functions, reducers, utility/hook logic in isolation, no DOM rendering.
+- **Component** — a single component rendered with Testing Library (or framework-equivalent), asserting on rendered output/accessibility tree and user interaction, network mocked.
+- **Integration** — multiple components/modules wired together (e.g. a form + its validation + a mocked API layer), still no real browser.
+- **E2E** — real (or real-enough) browser, real routing, hits a running app (locally or staging), via Playwright/Cypress.
+
+A commonly cited healthy shape is unit-heavy, E2E-light — many more fast, isolated tests than slow, full-stack ones — but do not apply a fixed ratio as a hard gate; the right shape depends on the codebase's actual risk surface (a form-heavy app has a legitimately larger component layer than a data-pipeline-heavy one). Flag a shape as a *finding* when:
+
+- E2E test count is a large fraction of total tests but the app's core logic is stateless/computational (should be unit-tested instead), or
+- there are numerous integration/E2E tests re-asserting something a unit test already covers with no additional confidence gained, or
+- the unit layer is large but assertion inspection shows most assertions target internal state/props rather than rendered/observable behavior.
+
+## Deciding which layer an assertion belongs at
+
+- **Business logic, formatting, validation rules, reducers/selectors** → unit. If it doesn't need a DOM, don't give it one.
+- **"Does this component render correctly given these props/state, and can a user interact with it?"** → component, with network/API mocked.
+- **"Do these pieces work together" (form + validation + submit handler + mocked API)** → integration.
+- **"Does the real critical journey work end-to-end through real routing/auth/persistence?"** → E2E, reserved for a *small number* of the highest-value flows, not every page.
+
+Push back when a user proposes writing an E2E test for something a unit or component test can cover — the E2E test costs more (runtime, flakiness surface, infra) for the same assertion.
+
+## Critical-user-journey coverage audit
+
+A "critical user journey" is a flow whose failure has direct revenue, compliance, or trust impact — auth (login/signup/logout/password reset), checkout/payment, core conversion action (the thing the product exists to let users do), and any flow with a regulatory obligation (consent capture, data export/deletion).
+
+For each critical journey, verify presence of assertions on:
+
+- **the happy path**, obviously, but that alone is not sufficient;
+- **error states** — network failure, validation rejection, expired session, rate limiting — does the suite prove the user sees a recoverable error, or does it stop at the happy path and assume errors "probably work"?
+- **loading/pending states** — is there an assertion the UI shows a loading indicator and doesn't allow a double-submit, or is this untested?
+- **accessibility tree for the interactive path** — for a critical flow, are the interactive elements queried via role/label (proving they're actually reachable via assistive tech), or only via test-id/class (which proves nothing about usability)?
+
+A journey with only a happy-path E2E test and no error-state coverage is a **coverage gap**, not "covered." State this explicitly in the finding rather than crediting partial coverage as complete.
+
+## Response discipline
+
+When reporting pyramid shape or coverage gaps, cite the evidence:
+
+- file/directory counts (e.g. "14 `*.spec.ts` under `e2e/`, 6 under `src/**/*.test.ts`"), or
+- a CI coverage/test-report artifact if the user provided one.
+
+Do not report a ratio or gap you inferred from the user's description alone without inspecting the actual test files — label such a claim `inference` and say so.

package/skills/frontend/frontend-testing-strategy-review/references/unit-component-framework-review.md

@@ -0,0 +1,35 @@
+# Vitest and Testing Library Unit/Component Review
+
+Use this reference for unit/component-layer specifics: query priority (`getByRole` over test IDs), mocking boundaries, and coverage-threshold configuration. For where an assertion belongs in the pyramid at all, see `pyramid-shape-and-coverage.md`.
+
+> Version note: Vitest and Testing Library config/query APIs evolve across majors (e.g. Vitest's coverage-threshold `perFile` inheritance behavior changed across versions). Verify exact option names/defaults against the installed version via Context7 (`/vitest-dev/vitest`, `/testing-library/testing-library-docs`) or the official docs before citing a config shape or migration-breaking change in a report.
+
+## Officially grounded design points
+
+**Testing Library query priority (documented, not a style opinion):**
+
+Testing Library's own docs define an explicit priority order, and a review should measure component tests against it directly:
+
+1. **Queries accessible to everyone** — top priority, because they reflect both visual and assistive-technology user experience: `getByRole` (the primary choice — it exposes name/role/state exactly as the accessibility tree does), `getByLabelText` (form fields), `getByPlaceholderText` (secondary, for inputs), `getByText` (non-interactive elements), `getByDisplayValue` (current form value).
+2. **Semantic queries** — lower priority than accessible queries; use when an accessible query isn't practical.
+3. **Test IDs** — documented as the *last resort*, specifically because a `data-testid` proves nothing about whether a real user (including one using assistive technology) can actually find/use the element.
+
+A component test suite that predominantly uses `getByTestId`/`container.querySelector` where `getByRole`/`getByLabelText` would work is a **finding**, not a style nit — it means the tests are not verifying the thing that actually matters (can a user, including an AT user, interact with this), and it silently permits an accessibility regression (e.g. a missing accessible name) to pass a test that only checked a test-id existed.
+
+Custom test-id queries built via `queryHelpers.queryByAttribute` are supported for a project's own attribute convention (e.g. `data-test-id` instead of `data-testid`), but the priority order still applies — a custom test-id query is still a last resort, not a replacement for role/label queries.
+
+**Vitest coverage thresholds:**
+
+Vitest's `coverage.thresholds` config supports global thresholds (`lines`, `functions`, `branches`, `statements`), per-glob-pattern thresholds (each pattern requiring `perFile: true` explicitly to apply per-file, since patterns do not inherit the top-level `perFile` setting), and negative-number thresholds meaning "no more than N uncovered items" rather than a percentage. A reviewed config claiming a threshold is enforced should be checked against these actual semantics — e.g. a glob-pattern threshold block without its own `perFile: true` will NOT enforce per-file coverage even if the top-level config has `perFile: true`, because glob patterns do not inherit it.
+
+## Non-negotiable design rules
+
+1. **Assert on rendered/observable behavior, not implementation detail.** A component test that reaches into instance state, calls a private method, or snapshot-diffs unrelated markup churn (e.g. a full-component snapshot that breaks on any unrelated style change) is brittle and doesn't prove user-facing correctness — see the "hollow pyramid" failure mode in `pyramid-shape-and-coverage.md`.
+2. **Query by role/label first; test-id is the last resort, not the default.** Apply the Testing Library priority order above as a hard review criterion, not a suggestion.
+3. **Mock at the network boundary, not inside application logic.** Component/integration tests should mock the API layer (MSW, or an injected fetch client) rather than mocking internal application functions, so the test still exercises real component logic/wiring and doesn't silently pass after a refactor that keeps the mocked function's shape but breaks real integration.
+4. **Coverage thresholds are a floor, not a target.** A threshold catches *regression below a floor*; it does not prove the newly-added code at 100% coverage actually asserts on error/loading states (see `pyramid-shape-and-coverage.md`). Do not treat "coverage threshold met" as equivalent to "critical path covered."
+5. **Watch-mode/local dev ergonomics should not leak into CI config.** Settings tuned for fast local iteration (e.g. skipping type-checking, relaxed isolation) need an explicit, separate CI config — verify the CI config path, don't assume local config is what runs in the pipeline.
+
+## Response discipline
+
+When reviewing unit/component tests, cite the specific query/mock/assertion pattern found (with file reference), state which Testing Library priority tier the primary queries fall into, and label whether a coverage-threshold or config-semantics claim is `documentation-based` (grounded via Context7/official docs this session) or `inference`.

package/skills/frontend/graphql-client-security-review/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: graphql-client-security-review
+description: Statically review GraphQL client configuration (Apollo Client, and urql/similar clients by analogy) for production-enabled devtools/introspection exposure, a normalized cache left uncleared across user sessions, missing persisted-query allowlisting against client-driven query abuse, auth headers attached with no CSRF protection, and sensitive fields cached unmasked -- grounded in Apollo Client's own configuration and security-relevant documentation.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-03"
+  category: security
+---
+
+# GraphQL Client Security Review
+
+## Purpose
+
+Review GraphQL client setup code -- client construction, link chains, and cache configuration -- for five documented, security-critical defect classes: production-reachable devtools/schema introspection, a normalized cache that survives a user logout or account switch, client-driven query abuse with no server-side allowlist, an authorization header attached with no accompanying CSRF protection, and sensitive fields written into the normalized cache with no masking policy. This skill exists so the review stays anchored to these five concrete, greppable sinks instead of drifting into a general "is this GraphQL app well-architected" review.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review an Apollo Client (or comparable GraphQL client) instantiation for production security posture,
+- assess whether a logout/session-switch flow correctly clears client-side GraphQL cache state,
+- investigate a report that one user's cached GraphQL data appeared in another user's session on the same device,
+- audit a GraphQL client's link chain for unallowlisted, client-driven query risk (excessive nesting, alias-based amplification, arbitrary ad hoc documents reaching the server),
+- check whether an auth-header link (`SetContextLink` or equivalent middleware) exposes GraphQL mutations to CSRF,
+- review cache `typePolicies` (or equivalent) for whether sensitive fields (payment data, `cvv`, SSNs, tokens) are masked before being normalized into the cache.
+
+Do not use this skill for:
+
+- GraphQL server-side schema/resolver authorization review (field-level permission checks, resolver-level access control) -- this skill is scoped to the client, not the server; the server-side defect class needs a different review entirely,
+- general Apollo Client / urql architecture or performance review with no security angle (cache normalization strategy quality, fetch-policy tuning, pagination design) -- use a general frontend-architecture review for that,
+- a bug that requires live traffic reproduction (capturing a real cross-user cache leak, load-testing a query-cost exploit against a live server) to confirm exploitation -- static analysis proves the structural risk in the client configuration, not that it has already been exploited in production.
+
+## Context7 Documentation Protocol
+
+- Resolve the Apollo Client library ID with `resolve-library-id` (matched result: `/apollographql/apollo-client`) before citing any client-configuration, cache-reset, or link-chain claim.
+- `/apollographql/apollo-client` is Apollo Client's own docs-and-source repository. Use `query-docs` against it to ground claims about `connectToDevTools` behavior, `resetStore`/`clearStore` semantics, `SetContextLink` header-injection patterns, and `PersistedQueryLink` allowlisting -- these are `repo evidence` when confirmed there.
+- urql is not currently resolvable in Context7. Treat urql-specific findings as `documentation-based` (urql's own published docs) or `inference` (reasoning by analogy from Apollo Client's documented behavior), and say so explicitly -- never state a urql API detail as `repo evidence` without a Context7-confirmed source.
+- Read `package.json` first to confirm which GraphQL client (and version) is actually in use before applying any client-specific API name -- `resetStore`/`clearStore` and `SetContextLink` are Apollo Client APIs; do not apply them to a urql or graphql-request codebase without confirming the equivalent construct first.
+- If Context7 is unavailable, fall back to the `official_docs` URLs in this skill's `metadata.json` and label the claim `documentation-based, unverified against current release`.
+
+## Lean operating rules
+
+- All five defect classes default to HIGH severity. This is a security-scoped skill: do not downgrade a production-reachable devtools finding, an uncleared cache after logout, an unallowlisted query surface, a CSRF-less auth header, or an unmasked sensitive cached field to MEDIUM just because it has not been observed exploited yet -- the risk is in the structure, not in whether someone has already hit it.
+- Trace every finding to a concrete file:line and a concrete data-flow or configuration path. A finding that says "the cache might leak" or "this could be a CSRF risk" without showing the specific `connectToDevTools` literal, the specific logout handler missing `resetStore`/`clearStore`, or the specific header-construction code is not a valid finding -- it is a guess.
+- `connectToDevTools` set to an unconditional `true` (or simply always-on with no environment gate) is a HIGH finding regardless of whether the current deployment happens to be a staging environment -- flag the structural exposure, not just today's environment. `connectToDevTools` correctly gated on a build-time environment check (development-only) is not a finding.
+- Do not approve a logout or account-switch handler unless it visibly calls `client.resetStore()` or `client.clearStore()` (or the equivalent for the client library in use) on the exact path between the auth-invalidation call and the navigation/redirect that follows. A cache-clearing call that exists elsewhere in the codebase, in a different handler, does not clear this bar for the specific logout path under review.
+- Check every link-chain construction for a `PersistedQueryLink` (or equivalent allowlisting mechanism) between the application's operations and the transport link. A client wired directly to a raw HTTP link with no persisted-query allowlist is a MEDIUM-to-HIGH finding depending on whether the endpoint is public/unauthenticated (higher) or requires an authenticated session to reach (lower, but still a finding) -- an authenticated session does not eliminate cost-abuse risk from a legitimate-but-malicious authenticated client.
+- Check every `SetContextLink`/auth-header-injection link for whether it attaches an anti-CSRF header (commonly `x-csrf-token` or an equivalent named header) alongside the `authorization` header. A token-only header construction with no CSRF header is a MEDIUM-to-HIGH finding when the same token can also travel via an automatically-attached credential (a cookie-backed session, a same-site credentialed fetch) -- if the token is exclusively attached by explicit client code with no cookie-based fallback anywhere in the auth flow, state that explicitly and do not manufacture a CSRF finding where the attack surface does not exist.
+- Check cache `typePolicies` (or equivalent field-policy mechanism) for every sensitive field type (payment data, `cvv`, SSNs, auth tokens, other PII) that flows through a query in scope. A sensitive field with no masking `read()` policy, normalized into an `InMemoryCache` (or equivalent) with no field-level exclusion, is a HIGH finding -- it is visible in the devtools cache inspector for the life of the cache entry regardless of whether devtools happen to be enabled in the current build.
+- Never execute, build, or run application code, and never send live GraphQL requests, as part of this review; this is a static-review skill (Read/Grep/Glob only).
+- Load only the reference needed for the concern in scope.
+
+## References
+
+Load these only when needed:
+
+- [Review workflow and findings contract](references/workflow-and-output.md) -- use for the step-by-step review procedure, the five-defect-class decision tree, and the required output shape.
+- [Cache lifecycle and query-surface risk](references/cache-lifecycle-and-query-surface.md) -- load only when reviewing cache clearing on logout, `typePolicies` masking of sensitive fields, or `PersistedQueryLink` allowlisting of the client's query surface.
+- [Devtools exposure and CSRF-less auth headers](references/devtools-and-auth-header-risk.md) -- load only when reviewing `connectToDevTools` configuration or a `SetContextLink`/auth-header-injection link for CSRF protection.
+
+## Response minimum
+
+Return, at minimum:
+
+- the client construction, link chain, cache configuration, and/or logout handler(s) in scope,
+- ranked findings with file:line evidence, defect category (`devtools-exposure`, `cache-not-cleared`, `unallowlisted-query-surface`, `csrf-less-auth-header`, or `unmasked-sensitive-field`), the concrete configuration or data-flow trace, and a fix sketch matching Apollo Client's documented pattern,
+- for every cache-clearing finding, an explicit statement of whether `resetStore()` or `clearStore()` is present on the traced logout path -- never approve on the assumption one exists elsewhere,
+- for every sensitive-field finding, an explicit statement of whether a `typePolicies` masking `read()` policy is present for that exact field -- never approve on the assumption the field is handled safely downstream,
+- evidence level per finding (`repo evidence`, `documentation-based`, or `inference`), with structural risk findings explicitly labeled as structural risk, not as confirmed-exploited,
+- verdict (approve / approve-with-notes / block),
+- open questions or scope the review could not cover (e.g., "confirming actual query-cost abuse requires live load testing against the GraphQL server, not static review of the client").

package/skills/frontend/graphql-client-security-review/metadata.json

@@ -0,0 +1,29 @@
+{
+  "id": "graphql-client-security-review",
+  "name": "GraphQL Client Security Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Statically reviews Apollo Client (and urql-equivalent) GraphQL client configuration for production devtools/introspection exposure, normalized cache not cleared across user sessions, missing persisted-query allowlisting against client-driven query abuse, auth headers attached without CSRF protection, and sensitive fields normalized into the cache unmasked -- grounded in Apollo Client's own configuration, authentication, and caching documentation.",
+  "source_type": "original",
+  "official_docs": [
+    "https://www.apollographql.com/docs/react/development-testing/developer-tooling",
+    "https://www.apollographql.com/docs/react/networking/authentication",
+    "https://www.apollographql.com/docs/react/api/link/apollo-link-context",
+    "https://www.apollographql.com/docs/react/caching/advanced-topics",
+    "https://www.apollographql.com/docs/react/api/link/persisted-queries",
+    "https://owasp.org/www-project-top-ten/"
+  ],
+  "security_notes": "This skill's entire scope is security-critical: production-enabled devtools expose full schema introspection and the normalized cache inspector, an uncleared cache after logout is a cross-user/cross-tenant data-exposure defect, unallowlisted client-driven queries are a denial-of-service/cost-abuse vector, an auth header with no CSRF token weakens mutation-endpoint protection, and unmasked sensitive fields in the normalized cache are exposed to the devtools inspector for the life of the cache entry. Every finding in this skill defaults to HIGH severity unless proven otherwise with concrete configuration evidence. Static-review-only skill: it reads and greps GraphQL client setup, link chains, and cache configuration but never executes, builds, or runs application code, and never sends live GraphQL requests.",
+  "last_verified": "2026-07-03",
+  "path": "skills/frontend/graphql-client-security-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/graphql-client-security-review/references/cache-lifecycle-and-query-surface.md

@@ -0,0 +1,107 @@
+# Cache Lifecycle and Query-Surface Risk
+
+Use this reference when reviewing cache clearing on logout, `typePolicies` masking of sensitive fields, or `PersistedQueryLink` allowlisting of the client's query surface.
+
+## What people get wrong
+
+The naive assumption is:
+
+> "We call the logout API and redirect to `/login` -- the user is logged out, so we're done."
+
+Wrong for a normalized-cache GraphQL client. Apollo Client's `InMemoryCache` (and equivalents) persists query results across the lifetime of the JavaScript process, not just the lifetime of a single request. If the server-side session is invalidated but the client-side cache is never told to forget what it knows, the previous user's cached data remains resolvable by whatever renders next -- a shared device, a fast re-login by a different account, or a client-side-only account switch with no full page reload. Redirecting to a login page does not clear an in-memory cache; only an explicit call does.
+
+A parallel naive assumption applies to the query surface:
+
+> "Our GraphQL endpoint requires authentication, so a client can't do anything malicious with it."
+
+Also wrong. Requiring authentication limits *who* can send a query, not *what* they can send once authenticated. A legitimate, authenticated client (or a compromised/malicious one using valid credentials) can still send arbitrarily deep, alias-heavy, or otherwise expensive queries if nothing on the client or server constrains the query surface to a known-safe set.
+
+## Officially grounded rules
+
+Apollo Client's own networking/authentication documentation states directly (`repo evidence` via Context7 `/apollographql/apollo-client`):
+
+- **Reset the store on logout.** The documented pattern calls `client.resetStore()` from the logout handler, immediately after the application's own logout call, specifically so the UI reflects the logged-out state and stale data from the previous session is not retained.
+- **`resetStore()` clears the cache and refetches active queries; `clearStore()` clears the cache without refetching.** Choose based on whether an immediate refetch of currently-mounted queries is desired (`resetStore()`) or whether the app is about to unmount/navigate away entirely and a refetch would be wasted work (`clearStore()`). Either call clears the previous session's normalized cache entries -- the choice is about refetch behavior, not about whether the cache gets cleared.
+- **`PersistedQueryLink` allowlists the client's query surface.** Chaining a `PersistedQueryLink` ahead of the transport link (e.g. `persistedQueryLink.concat(httpLink)`) restricts the operations the client can send to a build-time manifest of pre-registered, reviewed query documents, rather than allowing arbitrary ad hoc documents to reach the server.
+
+## Non-negotiable design rules
+
+### 1. Trace the logout path to its actual end, not to the redirect
+
+Do not treat a call to `navigate('/login')` or `window.location.assign('/login')` as evidence the session is cleaned up. Follow the handler line by line: does it call `resetStore()`/`clearStore()` on the client instance *before or as part of* the logout flow? A redirect with no cache-clearing call leaves the cache populated for whatever renders next in that same JS process.
+
+### 2. A cache-clearing call elsewhere in the codebase does not clear this finding
+
+If `resetStore()` is called somewhere in the app (e.g., in a settings-reset flow unrelated to auth), that does not establish the logout handler under review clears the cache. Trace the specific handler.
+
+### 3. Persisted-query allowlisting is a structural control, not a performance optimization
+
+Treat the absence of `PersistedQueryLink` (or an equivalent allowlist) as a security finding, not merely a caching/performance suggestion, when the endpoint accepts arbitrary client-authored documents. The finding's severity scales with reachability: a public, unauthenticated endpoint with no allowlist is higher severity than an authenticated one, but authentication alone does not clear the finding.
+
+### 4. Sensitive fields need field-level masking, not just cache-level access control
+
+A GraphQL client cache has no user-level access control of its own -- anything normalized into it is readable by any code running in that JS context (including the devtools inspector, if enabled). The only client-side control for a sensitive field is a `typePolicies` (or equivalent) `read()` policy that strips the value before it is stored, or simply never requesting the field in the first place.
+
+## Minimal safe implementation patterns
+
+Cache clearing on logout (`repo evidence`, Apollo Client's own authentication docs):
+
+```javascript
+async function handleLogout(client) {
+  await logoutAPI();
+  await client.resetStore(); // clears cache, refetches active queries
+  navigate('/login');
+}
+```
+
+Persisted-query allowlisting on the link chain:
+
+```javascript
+import { PersistedQueryLink } from "@apollo/client/link/persisted-queries";
+
+const persistedQueryLink = new PersistedQueryLink({
+  generatePersistedQueryIdsFromManifest: () =>
+    import("./persisted-query-manifest.json")
+});
+
+const client = new ApolloClient({
+  link: persistedQueryLink.concat(httpLink),
+  cache: new InMemoryCache()
+});
+```
+
+Masking a sensitive field via `typePolicies`:
+
+```javascript
+const cache = new InMemoryCache({
+  typePolicies: {
+    CreditCard: {
+      fields: {
+        cvv: {
+          read() {
+            return undefined; // never persisted into the normalized cache
+          }
+        }
+      }
+    }
+  }
+});
+```
+
+## Adversarial checklist
+
+Before clearing a logout/session-teardown handler:
+
+- Does the handler call `resetStore()` or `clearStore()` (or the client-specific equivalent) on the exact path being reviewed -- not somewhere else in the codebase?
+- Is the cache-clearing call ordered so it actually runs before the user could plausibly see stale cached data (before or immediately after the redirect, not in a code path that could be skipped)?
+- If the app supports multiple concurrent sessions/accounts (account switching without a full logout), does switching accounts also clear or scope the cache appropriately?
+
+Before clearing a query-surface finding:
+
+- Is there a `PersistedQueryLink` (or equivalent) between application code and the transport link, or can arbitrary documents reach the server?
+- If no allowlist exists, is the endpoint gated by anything else that meaningfully bounds query cost (server-side query complexity/depth limiting)? If the review scope is client-only, state explicitly that server-side limits are out of scope and unverified.
+
+Before clearing a sensitive-field finding:
+
+- Does the field have a `typePolicies` `read()` masking policy on the exact type/field being queried?
+- Is the field requested by any query in scope at all -- if not, state explicitly that it was checked and found not reachable, rather than omitting it silently.

package/skills/frontend/graphql-client-security-review/references/devtools-and-auth-header-risk.md

@@ -0,0 +1,83 @@
+# Devtools Exposure and CSRF-less Auth Headers
+
+Use this reference when reviewing `connectToDevTools` configuration or a `SetContextLink`/auth-header-injection link for CSRF protection.
+
+## What people get wrong
+
+The naive assumption for devtools is:
+
+> "The Apollo Client Devtools extension only does anything if someone actually opens it, so leaving `connectToDevTools` on is harmless."
+
+Wrong. `connectToDevTools` controls whether the client *establishes the bridge* the devtools extension connects to -- it is the exposure surface, independent of whether anyone happens to have the extension open at a given moment. An unconditional `connectToDevTools: true` in a production bundle means any user (or any script running in that browser context) with the extension installed can inspect the full schema via introspection and browse the entire normalized cache, including anything a sensitive-field masking review would otherwise catch.
+
+The naive assumption for auth headers is:
+
+> "We attach the token as an `authorization` header, not a cookie, so CSRF doesn't apply to us."
+
+Partially wrong. CSRF is a risk specifically when a credential is attached to a request *automatically*, without explicit action by the calling code, most commonly via a cookie the browser sends on every same-origin (or lenient SameSite) request. If the `authorization` header is the *only* mechanism carrying the credential, and nothing else in the auth flow relies on a cookie, CSRF genuinely may not apply -- but this must be confirmed by tracing the full auth flow, not assumed from the header name alone. Many real apps use a hybrid: a cookie-backed refresh mechanism or a cookie-backed session alongside header-based bearer tokens, at which point the header alone is not the whole story.
+
+## Officially grounded rules
+
+Apollo Client's own documentation states directly (`repo evidence` via Context7 `/apollographql/apollo-client`):
+
+- **`connectToDevTools` explicitly enables the devtools bridge**, and Apollo Client's own developer-tooling documentation shows it being set for use in production builds as an explicit, deliberate override of the client's default (development-only) behavior -- meaning the safe default is to *not* set it to an unconditional `true`.
+- **`SetContextLink` (and the older `ApolloLink`-based context-setting pattern) is the documented mechanism for attaching an `authorization` header** to every outgoing request, retrieving the token via an async lookup and merging it into `prevContext.headers`. Apollo Client's documentation demonstrates the auth-header pattern itself but does not prescribe a CSRF-token header as part of the core library -- CSRF protection is application-level responsibility layered on top of the same context-setting mechanism.
+
+## Non-negotiable design rules
+
+### 1. Any unconditional `connectToDevTools: true` is a finding, regardless of stated deployment target
+
+Do not accept "this is only for our staging environment" as clearing the finding unless the review can independently verify the specific file/build path never reaches production. The construct itself -- not the current deployment claim -- is what a static review evaluates.
+
+### 2. Trace the full auth flow before ruling a CSRF finding in or out
+
+Do not judge a `SetContextLink` auth-header link in isolation. Check: is the token *ever* also carried by a cookie anywhere in this app's auth flow (a refresh-token cookie, a session cookie set alongside the bearer-token flow)? If yes, the header-only mutation-request pattern with no CSRF header is a genuine finding, because an attacker's cross-site form/fetch could ride the cookie's default browser-attached credential even though the header is not itself auto-attached. If the token is exclusively attached by explicit client-side code with no cookie-backed fallback anywhere in the flow, state this explicitly as the reason no CSRF finding applies -- do not silently omit the check.
+
+### 3. A CSRF header must be on the same context-construction path as the auth header
+
+If an anti-CSRF header exists in the codebase but is added by a different link, a different request path, or a different client instance than the one under review, that does not clear the finding for the specific `SetContextLink` construction being reviewed.
+
+## Minimal safe implementation patterns
+
+Devtools gated to development only (`repo evidence`, contrasted directly against Apollo Client's own production-enablement example):
+
+```javascript
+const client = new ApolloClient({
+  uri: "/graphql",
+  cache: new InMemoryCache(),
+  connectToDevTools: process.env.NODE_ENV === 'development'
+});
+```
+
+Auth header with CSRF protection attached on the same path:
+
+```typescript
+import { SetContextLink } from "@apollo/client/link/context";
+
+const withToken = new SetContextLink(async (prevContext, operation) => {
+  const token = await AsyncTokenLookup();
+  const csrfToken = await getCsrfToken();
+  return {
+    headers: {
+      ...prevContext.headers,
+      authorization: `Bearer ${token}`,
+      'x-csrf-token': csrfToken
+    }
+  };
+});
+```
+
+## Adversarial checklist
+
+Before clearing a devtools finding:
+
+- Is `connectToDevTools` gated on an environment check that demonstrably evaluates to `false` in a production build, or is it an unconditional literal?
+- If gated, does the gate reference a value the review can actually verify (a well-known bundler env substitution) rather than a custom flag whose production value is unknown?
+
+Before clearing a CSRF finding on an auth-header link:
+
+- Does any part of this app's auth flow rely on a cookie (refresh token, session identifier) alongside or instead of the header?
+- Is there a named anti-CSRF header (e.g. `x-csrf-token`) attached on the exact same context-construction path as the `authorization` header, or only "a CSRF utility exists somewhere in this codebase"?
+- Would a state-changing GraphQL mutation succeed if only the automatically-attached credential (if any) were present, with no explicit client-side header set by an attacker's cross-site request?
+
+If any answer is unclear or reveals a gap, the finding stands at HIGH (devtools) or MEDIUM-to-HIGH (CSRF, per reachability) -- do not soften it to "worth double-checking."

package/skills/frontend/graphql-client-security-review/references/workflow-and-output.md

@@ -0,0 +1,53 @@
+# Review Workflow and Findings Contract
+
+Use this reference for the step-by-step review procedure and the required output shape. Load the other two references only for the specific defect class the client code under review actually raises.
+
+## Prerequisites
+
+- Read `package.json` first to confirm which GraphQL client library (Apollo Client, urql, graphql-request, or other) and version are in use. Apollo Client APIs (`connectToDevTools`, `resetStore`, `clearStore`, `SetContextLink`, `PersistedQueryLink`) do not transfer 1:1 to other clients -- confirm the equivalent construct before applying Apollo-specific guidance to a non-Apollo codebase.
+- Identify every place the client is instantiated (`new ApolloClient({...})` or equivalent) -- a codebase may construct more than one client (e.g., an authenticated client and a public client), and each needs its own review pass.
+
+## Workflow
+
+1. **Locate every client instantiation.** For each, read the full construction call, including every option passed.
+2. **Check `connectToDevTools`.** Is it an unconditional `true`, absent (defaulting per the client's own behavior), or gated on an environment check? See `references/devtools-and-auth-header-risk.md`.
+3. **Locate every logout / account-switch / session-teardown handler.** For each, trace whether `resetStore()` or `clearStore()` (or the equivalent for the client in use) is called on the path between the auth-invalidation call and any subsequent navigation. See `references/cache-lifecycle-and-query-surface.md`.
+4. **Trace the link chain for persisted-query allowlisting.** Locate the `link` option passed to the client. Determine whether a `PersistedQueryLink` (or equivalent allowlisting link) sits between the application code and the transport link, or whether arbitrary client-authored query documents reach the transport link unfiltered. See `references/cache-lifecycle-and-query-surface.md`.
+5. **Trace every auth-header-injection link** (`SetContextLink`, an `ApolloLink` middleware, or equivalent). Determine whether an anti-CSRF header (e.g. `x-csrf-token`) is attached alongside the `authorization` header, and whether the same auth token could also be attached automatically via a cookie-backed session. See `references/devtools-and-auth-header-risk.md`.
+6. **Enumerate cache `typePolicies` (or equivalent field-policy config) against every sensitive field reachable by a query in scope.** For fields carrying payment data, `cvv`, SSNs, tokens, or other PII, check for a masking `read()` policy that prevents the raw value from being normalized into the cache. See `references/cache-lifecycle-and-query-surface.md`.
+7. **Produce ranked findings** using the output contract below.
+
+## Decision tree
+
+- `connectToDevTools: true` (or any construction that is unconditionally on, with no environment gate) → **HIGH** finding, devtools/introspection exposure. Cite Apollo Client's own devtools-configuration documentation (`repo evidence` via Context7 `/apollographql/apollo-client`).
+- `connectToDevTools` gated on a build-time environment check (e.g. `process.env.NODE_ENV === 'development'`) → not a finding.
+- A logout/session-teardown handler invalidates the server-side session but never calls `resetStore()`/`clearStore()` on that same path → **HIGH** finding, cross-user cache exposure risk on the client. The risk is structural (shared device, fast re-login, profile switch) regardless of whether it has been reported as an incident.
+- A logout handler calls `resetStore()`/`clearStore()` on the exact traced path → not a finding.
+- Client's link chain wires application operations directly to a transport link (`HttpLink` or equivalent) with no `PersistedQueryLink` (or equivalent allowlist) in between → **MEDIUM-to-HIGH** finding depending on reachability (public/unauthenticated endpoint is higher; requiring an authenticated session is still a finding, since a legitimate-but-malicious authenticated client can still abuse an unallowlisted surface).
+- Client's link chain includes a persisted-query allowlisting link between application code and the transport link → not a finding.
+- Auth-header-injection link attaches `authorization` with no anti-CSRF header, and the same token or an equivalent session credential can also travel automatically (cookie-backed) → **MEDIUM-to-HIGH** finding depending on whether the mutation surface is state-changing.
+- Auth-header-injection link attaches both `authorization` and an anti-CSRF header (e.g. `x-csrf-token`), or the token is exclusively attached by explicit client code with no cookie-based fallback anywhere in the auth flow (state this explicitly) → not a finding.
+- A sensitive field (payment data, `cvv`, SSN, token, other PII) reachable by an in-scope query has no masking `read()` policy in `typePolicies` (or equivalent) and is normalized into the cache as-is → **HIGH** finding, unmasked sensitive data cached -- visible in the devtools inspector for the life of the entry regardless of the current devtools-enablement finding.
+- The same sensitive field has a masking `read()` policy (or the field is never requested by any in-scope query) → not a finding, but state this explicitly rather than omitting the field from the review.
+
+## Output contract
+
+Every response from this skill must return:
+
+1. **Scope** -- the client instantiation(s), link chain(s), cache configuration, and/or logout handler(s) reviewed.
+2. **Ranked findings** -- each with file:line, defect category (`devtools-exposure` / `cache-not-cleared` / `unallowlisted-query-surface` / `csrf-less-auth-header` / `unmasked-sensitive-field`), the concrete configuration or data-flow trace (naming every hop), and a fix sketch matching Apollo Client's documented pattern.
+3. **Cache-clearing status per logout finding** -- an explicit statement of whether `resetStore()`/`clearStore()` is present on the traced path; never infer one exists elsewhere.
+4. **Masking status per sensitive-field finding** -- an explicit statement of whether a `typePolicies` masking policy is present for that exact field; never infer downstream handling is safe.
+5. **Evidence level per finding** -- `repo evidence`, `documentation-based`, or `inference`. Label structural risk findings as structural risk explicitly -- do not imply confirmed exploitation without live evidence (e.g., a captured cross-user cache read, a load-test reproduction of query-cost abuse).
+6. **Verdict** -- approve / approve-with-notes / block.
+7. **Open questions or out-of-scope items** -- e.g., "confirming actual query-cost abuse requires live load testing against the GraphQL server, not static review," or "server-side field-level authorization is out of scope for this client-focused skill -- recommend a server-side resolver review if that surface is in question."
+
+## When to push back
+
+Push back if the user asks to:
+
+- approve `connectToDevTools: true` because "it's only in the staging build" without a visible environment gate on that exact literal -- staging today is production tomorrow, and the construct itself is what is being reviewed,
+- approve a logout handler because "the cache clears itself on reload" -- a reload is not guaranteed (SPA navigation without a full page reload, a shared-device profile switch) and the handler under review is what must demonstrably clear it,
+- treat an authenticated-only GraphQL endpoint as immune to unallowlisted-query-surface risk -- an authenticated session does not prevent a legitimate-but-malicious client from sending expensive, unallowlisted queries,
+- clear a CSRF finding on the assumption that "the token is in a header, so cookies aren't involved" without checking whether any part of the auth flow also relies on a cookie-backed session,
+- skip masking review for a sensitive field because "we'll disable devtools in production" -- the unmasked cache entry is a data-exposure risk independent of whether devtools happen to be reachable in the environment being reviewed.