claudecode-omc 5.6.8 → 5.11.0

package/bundled/upstream/ecc/skills/react-testing/SKILL.md

@@ -0,0 +1,423 @@
+---
+name: react-testing
+description: React component testing with React Testing Library, Vitest/Jest, MSW for network mocking, accessibility assertions with axe, and the decision boundary between component tests and Playwright/Cypress end-to-end runs. Use when writing or fixing tests for React components, hooks, or pages.
+origin: ECC
+---
+
+# React Testing
+
+Comprehensive React testing patterns for behavior-focused component tests, custom hook tests, accessibility assertions, and network-level mocking.
+
+## When to Activate
+
+- Writing tests for React components, custom hooks, or pages
+- Adding test coverage to legacy untested components
+- Migrating from Enzyme or class-component-era patterns to React Testing Library
+- Setting up Vitest or Jest for a new React project
+- Mocking HTTP requests in tests
+- Asserting accessibility violations
+- Deciding which tests belong in RTL vs Playwright Component Testing vs full E2E
+
+## Core Principle
+
+Test what the user sees and does, not implementation details.
+
+A test should:
+
+- Render the component with the same providers it has in production
+- Interact with it via accessible queries (role, label) and `userEvent`
+- Assert visible output and observable side effects (callback fired, request sent)
+
+A test should NOT:
+
+- Inspect component state, props passed to children, or which hooks were called
+- Mock React itself or framework hooks
+- Assert on the number of renders or DOM structure beyond what affects users
+
+## Library Choice
+
+| Runner | When | Note |
+|---|---|---|
+| **Vitest** | Vite, Remix, modern setups | Faster, native ESM, Jest-compatible API |
+| **Jest** | Next.js, CRA, established repos | Default for many React projects |
+| **Playwright Component Testing** | Real browser engine needed | Use when JSDOM lacks the required feature |
+| **Cypress Component Testing** | Real browser, Cypress already in use | Alternative to Playwright CT |
+
+Pick one. Do not run RTL + Vitest AND Playwright CT in the same repo unless you have a clear lane separation.
+
+## Query Priority
+
+React Testing Library exposes queries in three tiers — use top-down:
+
+1. **Accessible to everyone**: `getByRole`, `getByLabelText`, `getByPlaceholderText`, `getByText`, `getByDisplayValue`
+2. **Semantic**: `getByAltText`, `getByTitle`
+3. **Test IDs (escape hatch)**: `getByTestId`
+
+```tsx
+// Best
+screen.getByRole("button", { name: /save/i });
+
+// OK for inputs
+screen.getByLabelText("Email");
+
+// Last resort
+screen.getByTestId("save-btn");
+```
+
+Variants:
+
+- `getBy*` — throws if no match
+- `queryBy*` — returns `null` (use for "assert absence")
+- `findBy*` — async, returns a Promise (use for elements that appear after async work)
+
+## User Interaction with `userEvent`
+
+```tsx
+import userEvent from "@testing-library/user-event";
+
+test("submits the form", async () => {
+  const user = userEvent.setup();
+  const onSubmit = vi.fn();
+  render(<UserForm onSubmit={onSubmit} />);
+
+  await user.type(screen.getByLabelText("Email"), "user@example.com");
+  await user.click(screen.getByRole("button", { name: /save/i }));
+
+  expect(onSubmit).toHaveBeenCalledWith({ email: "user@example.com" });
+});
+```
+
+- Always `await` userEvent calls
+- Call `userEvent.setup()` once per test, reuse the returned `user`
+- `userEvent` simulates a real browser sequence; `fireEvent` dispatches a single synthetic event — prefer `userEvent`
+
+## Async Patterns
+
+```tsx
+// Element that appears after async work
+expect(await screen.findByText("Loaded")).toBeInTheDocument();
+
+// Side effect assertion
+await waitFor(() => expect(saveSpy).toHaveBeenCalled());
+
+// Element that should disappear
+await waitForElementToBeRemoved(() => screen.queryByText("Loading"));
+```
+
+Never `setTimeout` + assertion — flaky. Use the matchers above.
+
+## Network Mocking with MSW
+
+Mock Service Worker mocks at the network layer. The component, hooks, and fetch library all behave exactly as in production.
+
+### Setup
+
+```ts
+// test/setup.ts
+import { setupServer } from "msw/node";
+import { http, HttpResponse } from "msw";
+
+export const handlers = [
+  http.get("/api/users/:id", ({ params }) =>
+    HttpResponse.json({ id: params.id, name: "Alice" }),
+  ),
+  http.post("/api/users", async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: "new-id", ...body }, { status: 201 });
+  }),
+];
+
+export const server = setupServer(...handlers);
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+Configure `onUnhandledRequest: "error"` so any unmocked request fails the test loudly — silent passes are worse than red.
+
+### Per-test override
+
+```tsx
+test("renders error on 500", async () => {
+  server.use(
+    http.get("/api/users/:id", () => new HttpResponse(null, { status: 500 })),
+  );
+  render(<UserPage id="1" />);
+  expect(await screen.findByText(/something went wrong/i)).toBeInTheDocument();
+});
+```
+
+## Provider Wrapping
+
+Wrap providers once in a `test-utils.tsx`:
+
+```tsx
+// test-utils.tsx
+import { render, RenderOptions } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+export function renderWithProviders(
+  ui: React.ReactElement,
+  options?: RenderOptions,
+) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ThemeProvider theme={lightTheme}>
+        <MemoryRouter>{ui}</MemoryRouter>
+      </ThemeProvider>
+    </QueryClientProvider>,
+    options,
+  );
+}
+
+export * from "@testing-library/react";
+```
+
+Then `import { renderWithProviders, screen } from "test-utils"` in every test file.
+
+## Custom Hook Testing
+
+```tsx
+import { renderHook, act } from "@testing-library/react";
+
+test("useCounter increments and decrements", () => {
+  const { result } = renderHook(() => useCounter(0));
+
+  expect(result.current.count).toBe(0);
+
+  act(() => result.current.increment());
+  expect(result.current.count).toBe(1);
+
+  act(() => result.current.decrement());
+  expect(result.current.count).toBe(0);
+});
+
+test("useCounter accepts initial value", () => {
+  const { result } = renderHook(() => useCounter(10));
+  expect(result.current.count).toBe(10);
+});
+
+test("useUser fetches user data", async () => {
+  // Instantiate QueryClient ONCE per test outside the wrapper so it survives re-renders.
+  // Creating it inside the wrapper closure resets cache state on every render, producing flaky tests.
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  const { result } = renderHook(() => useUser("1"), { wrapper });
+
+  await waitFor(() => expect(result.current.isSuccess).toBe(true));
+  expect(result.current.data).toEqual({ id: "1", name: "Alice" });
+});
+```
+
+- Wrap state-changing calls in `act`
+- Test through the hook's public API only
+- For hooks that use context, pass a `wrapper`
+
+## Accessibility Assertions
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"; // or vitest-axe
+expect.extend(toHaveNoViolations);
+
+test("UserCard has no a11y violations", async () => {
+  const { container } = render(<UserCard user={mockUser} />);
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+Run axe in component tests for every interactive component. Catches:
+
+- Missing labels on form inputs
+- Invalid ARIA usage
+- Poor color contrast (limited — JSDOM has no real CSS engine, so this works for inline styles only; visual contrast belongs in Playwright)
+- Missing alt text on images
+- Heading order violations
+
+Cross-link: [skills/accessibility/SKILL.md](../accessibility/SKILL.md) for the broader a11y testing playbook.
+
+## When NOT to Use Snapshot Tests
+
+Snapshots of rendered output:
+
+- Break on every styling change
+- Get rubber-stamped during review
+- Test implementation detail (DOM structure), not behavior
+
+Acceptable snapshot uses:
+
+- Pure data serialization functions (`formatInvoice(invoice)` -> stable string)
+- Generated config files (e.g., webpack config output)
+
+For visual regression on components, use Playwright/Cypress screenshots or Percy/Chromatic — actual visual diffs, not DOM strings.
+
+## When to Reach for Playwright / Cypress
+
+JSDOM (used by Vitest/Jest) cannot:
+
+- Render real layout (flexbox, grid, viewport queries)
+- Run native browser animation, CSS transitions
+- Test scrolling behavior, drag-and-drop, paste from clipboard
+- Handle iframes, popups, downloads, cross-origin flows
+- Run real network in a controlled environment with full DevTools support
+
+For any of those, use Playwright Component Testing (component test in real browser) or full E2E. See [e2e-testing skill](../e2e-testing/SKILL.md).
+
+Decision boundary:
+
+- A hook, a presentational component, a form with logic -> RTL
+- A component whose layout matters or that uses browser APIs not in JSDOM -> Playwright CT
+- A full user flow across multiple pages -> Playwright/Cypress E2E
+
+## Coverage Targets
+
+| Layer | Target |
+|---|---|
+| Pure utilities | >=90% |
+| Custom hooks | >=85% |
+| Presentational components | >=80% — behavior, not lines |
+| Container components | >=70% — golden paths + error states |
+| Pages | E2E covered separately; smoke test minimum |
+
+Configure via `vitest.config.ts` / `jest.config.js`:
+
+```ts
+// vitest.config.ts
+test: {
+  coverage: {
+    provider: "v8",
+    reporter: ["text", "html", "lcov"],
+    thresholds: {
+      lines: 80,
+      functions: 80,
+      branches: 70,
+      statements: 80,
+    },
+  },
+}
+```
+
+## Anti-Patterns
+
+- `container.querySelector("...")` — bypasses accessibility queries, lets tests pass when real users would fail
+- Asserting on number of renders — implementation detail
+- `jest.mock("react", ...)` — never mock React. Refactor the component instead
+- Mocking child components by default — tests the integration, not isolation. Mock only when the child has heavy side effects
+- Ignoring `act()` warnings — they signal real bugs (state update after unmount, missing async wrapping)
+- Sharing mutable state across tests — flakes when test order changes
+- Tests that pass with `it.skip()` removed — your test does not actually assert what you think
+
+## TDD Workflow
+
+```
+RED     -> Write failing test for the next requirement
+GREEN   -> Write minimal component code to pass
+REFACTOR -> Improve the component, tests stay green
+REPEAT  -> Next requirement
+```
+
+For new components:
+
+1. Define the component's prop type and signature
+2. Write the first test for the simplest case
+3. Verify it fails for the right reason
+4. Implement just enough to pass
+5. Add the next test case
+6. Refactor when the third similar test reveals a pattern
+
+## Test Commands
+
+```bash
+# Vitest
+vitest                            # watch
+vitest run                        # one-shot
+vitest run --coverage             # with coverage
+vitest run path/to/file.test.tsx  # single file
+
+# Jest
+jest --watch
+jest --coverage
+jest path/to/file.test.tsx
+
+# CI mode
+CI=true vitest run --coverage
+```
+
+## Related
+
+- Rules: [rules/react/testing.md](../../rules/react/testing.md)
+- Skills: [react-patterns](../react-patterns/SKILL.md), [accessibility](../accessibility/SKILL.md), [e2e-testing](../e2e-testing/SKILL.md), [tdd-workflow](../tdd-workflow/SKILL.md)
+- Agents: `react-reviewer` (reviews test quality during code review), `tdd-guide` (enforces TDD process)
+- Commands: `/react-test`, `/react-review`
+
+## Examples
+
+### Form submission with MSW and userEvent
+
+```tsx
+test("submits user form and shows success", async () => {
+  server.use(
+    http.post("/api/users", () =>
+      HttpResponse.json({ id: "1", name: "Alice" }, { status: 201 }),
+    ),
+  );
+
+  const user = userEvent.setup();
+  renderWithProviders(<UserForm />);
+
+  await user.type(screen.getByLabelText("Name"), "Alice");
+  await user.type(screen.getByLabelText("Email"), "alice@example.com");
+  await user.click(screen.getByRole("button", { name: /save/i }));
+
+  expect(await screen.findByText(/saved successfully/i)).toBeInTheDocument();
+});
+```
+
+### Testing an error boundary
+
+```tsx
+function Broken() {
+  throw new Error("boom");
+}
+
+test("error boundary renders fallback", () => {
+  // Suppress React's console.error noise for the expected throw, then restore so
+  // the spy does not leak across tests and hide real errors elsewhere.
+  const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  try {
+    render(
+      <ErrorBoundary fallback={<div>Something went wrong</div>}>
+        <Broken />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText("Something went wrong")).toBeInTheDocument();
+  } finally {
+    errorSpy.mockRestore();
+  }
+});
+```
+
+### Testing a Suspense boundary
+
+```tsx
+test("shows loading then content", async () => {
+  renderWithProviders(
+    <Suspense fallback={<div>Loading...</div>}>
+      <UserDetail id="1" />
+    </Suspense>,
+  );
+
+  expect(screen.getByText("Loading...")).toBeInTheDocument();
+  expect(await screen.findByText("Alice")).toBeInTheDocument();
+});
+```

package/bundled/upstream/ecc/skills/recsys-pipeline-architect/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: recsys-pipeline-architect
+description: Design composable recommendation, ranking, and feed pipelines using the six-stage Source→Hydrator→Filter→Scorer→Selector→SideEffect framework popularized by xAI's open-sourced For You algorithm. Use this skill whenever the user is building any system that picks "the top K items for a (user, context)" — social feeds, content CMSs, RAG rerankers, task prioritizers, notification triage, search reranking, ad ranking.
+origin: community
+---
+
+# recsys-pipeline-architect
+
+A spec-and-scaffold skill for building composable recommendation, ranking, and feed pipelines. It encodes the **six-stage pattern** — Source → Hydrator → Filter → Scorer → Selector → SideEffect — popularized by xAI's open-sourced [For You algorithm](https://github.com/xai-org/x-algorithm) (Apache 2.0). This skill is an independent reimplementation of the pattern (MIT) — no code copied from the original.
+
+Upstream: <https://github.com/mturac/recsys-pipeline-architect>
+
+## When to Use
+
+- User wants to build any system that picks "the top K items for a user/context"
+- User asks "how should I rank X" or describes a feed/personalization problem
+- User has a scoring function and needs the pipeline plumbing around it
+- User wants to migrate from a single relevance score to multi-action prediction with tunable weights
+- User is wrapping an LLM/ML scorer and needs filters, hydrators, side-effects, and a runnable scaffold in their stack (TypeScript / Go / Python)
+- Triggers: "recommendation system", "feed algorithm", "ranking pipeline", "for you feed", "candidate pipeline", "content recommender", "pipeline architecture for recsys", "RAG retrieval reranker"
+
+## When NOT to Use
+
+- Model architecture work (transformer design, two-tower retrieval, embedding training) — this skill is plumbing *around* the model, not the model itself
+- Pure ML training pipelines — the scoring function is the user's responsibility
+- Operating a deployed pipeline (monitoring, autoscaling) — out of scope
+
+## The six-stage framework
+
+| # | Stage | Job | Parallel? |
+|---|---|---|---|
+| 1 | **Source** | Fetch candidates from one or more origins | Yes — multiple sources run in parallel |
+| 2 | **Hydrator** | Enrich each candidate with metadata needed for filtering and scoring | Yes — independent hydrators run in parallel |
+| 3 | **Filter** | Drop candidates that should never be shown (blocked, expired, duplicate, ineligible) | Sequential — each filter sees fewer items |
+| 4 | **Scorer** | Assign each surviving candidate one or more scores | Sequential — later scorers see earlier scores |
+| 5 | **Selector** | Sort by final score, return top K | Single op |
+| 6 | **SideEffect** | Cache served IDs, log impressions, emit events, update counters | Async — must never block the response |
+
+### Why this exact order
+
+- Sources before hydration: know what candidates exist before paying to enrich them
+- Hydration before filtering: many filters need metadata the source did not provide
+- Filtering before scoring: scoring is the expensive stage; drop the ineligible first
+- Scorer chain (not single scorer): real systems compose ML scoring + diversity reranking + business rules
+- Selector after scoring: keeps scoring deterministic and cacheable
+- SideEffects last and async: side effects must never block the user response
+
+## Workflow when invoked
+
+Walk the user through these eight steps:
+
+1. **Clarify the use case** (one round, three questions): items being ranked? input context? language/runtime?
+2. **Identify the candidate sources**: usually in-network (followed/owned/subscribed) + out-of-network (ML retrieval / trending / similar-to-liked)
+3. **List required hydrations**: for each filter and scorer, what data does it need that the source did not provide?
+4. **List the filters**: duplicate, self, age, block/mute, previously-served, eligibility. Order matters — cheap before expensive.
+5. **Design the scorer chain**: primary (ML) → combiner (multi-action with weights) → diversity → business rules
+6. **Selector**: sort descending by final score, take top K (or stratified mix for in-network/out-of-network)
+7. **SideEffects**: cache served IDs, emit impression events, update counters, log analytics — all fire-and-forget
+8. **Generate the scaffold** in the user's stack
+
+## Key trade-offs to surface (don't default silently)
+
+### 1. Single score vs multi-action prediction
+
+- **Single score**: train one model to predict relevance. To change behavior → retrain.
+- **Multi-action**: predict `P(action)` for many actions (read, like, share, skip, report), combine with weights at serving time. To change behavior → change weights. No retraining.
+
+The X For You system uses multi-action with both positive and negative weights. Recommend multi-action when the user expects to tune frequently.
+
+### 2. Candidate isolation in scoring
+
+- **Isolated**: each candidate scored independently. Deterministic, cacheable.
+- **Joint**: candidates attend to each other during scoring (e.g., transformer over batch). More expressive but non-deterministic across batches.
+
+Default to isolation. Joint only when there's a specific reason (e.g., explicit batch-aware diversity).
+
+### 3. Online vs offline
+
+- **Request-time (online)**: pipeline runs on each request. Latency budget: 100–300ms. Default.
+- **Pre-computed (offline batch)**: pipeline runs periodically, results cached. Lower latency, lower freshness.
+- **Hybrid**: candidate retrieval offline, ranking online.
+
+## Hard rules
+
+1. **Do not invent benchmark numbers.** "How much faster?" → "depends on workload, run it yourself."
+2. **Attribution discipline.** When the pattern is referenced, attribute as "popularized by xAI's open-sourced For You algorithm" / `github.com/xai-org/x-algorithm` (Apache 2.0).
+3. **No trademark use.** Do not name the user's artifact "X-like" or use "For You" branding. Pattern is free; brand is not. Suggested naming: "candidate pipeline", "feed pipeline", "ranking pipeline", "recsys pipeline".
+4. **Surface trade-offs.** Multi-action vs single, isolation vs joint, online vs offline — never default silently.
+5. **The generated scaffold must run.** No pseudocode passing as code.
+6. **Filter order matters.** Cheap before expensive. Universal before user-specific.
+7. **Side effects never block.** Wrap in fire-and-forget patterns (goroutines / promises without await / asyncio tasks).
+
+## Anti-Patterns
+
+- Scoring before filtering (wastes compute on candidates that will be dropped anyway)
+- Synchronous side effects (cache writes / impression emits blocking the response)
+- A single "relevance" score when the product needs to tune for multiple objectives (engagement vs safety vs diversity vs ads)
+- Joint scoring as default (non-deterministic, harder to cache, doesn't compose with reranking stages)
+- Generating pseudocode "for illustration" — the scaffold must actually run
+
+## Upstream contents
+
+The upstream repository at <https://github.com/mturac/recsys-pipeline-architect> ships:
+
+- Full `SKILL.md` with the complete 8-step workflow
+- 5 load-on-demand reference docs: interfaces in 4 languages (TS/Go/Python/Rust), multi-action scoring pattern, candidate isolation, filter cookbook (12 patterns), scorer cookbook (weighted sum, MMR, diversity penalty, position debiasing)
+- 3 runnable example scaffolds, every one green on its test suite:
+  - Strapi v5 plugin (TypeScript / Jest — 3/3 pass)
+  - Zentra-compatible pipeline (Go with generics — 3/3 pass)
+  - PMAI task prioritizer (Python / FastAPI / pytest — 3/3 pass)
+- v0.1.0 release tagged
+- MIT license; pattern attributed to xAI X For You algorithm (Apache 2.0)
+
+Install via skills.sh: `npx skills add mturac/recsys-pipeline-architect`

package/bundled/upstream/ecc/skills/recursive-decision-ledger/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: recursive-decision-ledger
+description: Use when the user asks for repeated rollouts, marked decision processes, high-dimensional search, stochastic optimization, local-optima exploration, ensemble comparison, or recursive reasoning with a visible evidence trail.
+origin: ECC
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Recursive Decision Ledger
+
+Use this skill when the user is trying to force deeper computation through
+repeated rollouts or "Prime Gauss" style recursive prompting. Preserve the useful
+part: repeated trials, prior memory, fresh information, and explicit marks.
+Remove the unsafe part: pretending the loop proves certainty.
+
+## Ledger Contract
+
+Every rollout should record:
+
+- rollout id and timestamp;
+- prior accepted winner and prior watchlist;
+- fresh information ingested;
+- search space size;
+- model families or heuristics used;
+- trial count and effective trial count;
+- top candidates;
+- decision marks;
+- coherence marks against the prior ledger;
+- promotion gate result.
+
+Prefer JSONL for append-only ledgers and Markdown for human summaries.
+
+## Rollout Loop
+
+1. Load the prior ledger.
+2. Capture new information at time-step zero.
+3. Run the bounded search.
+4. Mark each candidate: accept, watch, reject, decay watch, or needs replay.
+5. Compare winners against prior winners and latest marked rollout.
+6. Downgrade candidates when drift, tail risk, stale data, or failed replay
+   invalidates the previous mark.
+7. Append artifacts before summarizing.
+
+## Coherence Mark
+
+Include a compact coherence mark:
+
+```text
+Ensemble matches prior winner: true
+Recursive matches prior winner: false
+Latest rollout match: true
+Live promotion allowed: false
+Reason: replay and freshness gates not satisfied
+```
+
+## Promotion Rules
+
+For trading, capital allocation, production deploys, migrations, or destructive
+ops, recursive confidence is not approval.
+
+Default to paper, dry-run, read-only, preview, or staged mode unless the user
+explicitly approves the live action and the repo/service gate supports it.
+
+Promote only when:
+
+- the candidate beats the prior accepted winner on the chosen metric;
+- correctness and replay checks pass;
+- risk limits are explicit;
+- the evidence is durable;
+- the user has approved the live step when needed.
+
+## Summary Shape
+
+Lead with the decision, not the drama:
+
+```text
+Rollout 15 complete. The prior winner still holds, but edge deteriorated 17%.
+Status: watch, not live. Next gate: 20 replay fills with fresh orderbook age
+below threshold.
+```