agentic-team 0.0.0-stage → 6.1.0

package/template/skills/mobile-testing/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: mobile-testing
+description: "Testing strategy for React Native and Expo apps. Use for any phase that writes or changes tests in a mobile app, or that adds an e2e flow."
+---
+
+# Skill: Mobile Testing
+
+## The fact everything else follows from
+
+**Jest does not run React Native.** The `jest-expo` preset runs components in
+Node against mocked native modules.
+
+On a backend, an integration test exercises the real thing. Here, the
+equivalent test exercises a simulation. The whole JS suite can be green while
+the app fails to build, crashes on launch, or works on iOS and not Android.
+
+So the device layer is not the optional top of a pyramid. It is where the
+risk actually lives.
+
+## The layers
+
+| Layer | What belongs here | Runs against |
+|---|---|---|
+| Pure logic | Calculations, conversions, date and streak logic, reducers — extracted **out** of components into plain modules | Node |
+| Components (RNTL) | Render, interact, assert behaviour | Node, **mocked natives** |
+| API seam (MSW) | Our own backend, faked at the network layer | Node |
+| E2E (Maestro) | 5–10 flows, no more | **Real simulator/emulator** |
+| The build | `expo-doctor`, `expo install --check`, a native build | CI |
+
+## Where mobile bugs actually come from
+
+| Failure | Caught by |
+|---|---|
+| Does not build, or crashes on launch | the build, then e2e |
+| Native module version off the SDK | `expo install --check` |
+| Fine on iOS, broken on Android | e2e on both |
+| Permission denied, backgrounded mid-request | e2e |
+| Offline or flaky network | MSW |
+| Stored data breaks on app upgrade | a dedicated migration test |
+| Small screen, large accessibility font | e2e or manual |
+| A notification that never arrives | nothing automated — a device |
+
+Very little of that column says "component test". Weight the effort
+accordingly.
+
+The last row is the honest one: permission, token refresh, the background
+handler and a deep link from a terminated app are all mocked into success by
+`jest-expo`. Depth in `.claude/skills/push-notifications/SKILL.md`.
+
+## Query by role, never by testID
+
+```ts
+screen.getByRole("button", { name: "Add water" });   // yes
+screen.getByTestId("add-water-btn");                 // no
+```
+
+RNTL resolves roles from `accessibilityRole` and the accessible name. Query
+that way and **a missing accessibility prop becomes a failing test** —
+accessibility stops being a review checklist item and becomes enforced by the
+suite. A `testID` proves nothing about whether a screen reader can use the
+screen.
+
+## Extract the logic out of the component
+
+A component test that exercises clamping, rounding or formatting is testing
+a pure function through three layers of render. Move the function to a plain
+module: it gets faster, it can be mutation-tested, and the component test
+shrinks to "renders what the module returned".
+
+## E2E — Maestro, not Detox
+
+Maestro is YAML flows and needs no native build knowledge. Detox is more
+capable and a great deal more setup; not worth it below a large team. Maestro
+is a CLI, installed by its own installer — not an npm package.
+
+Keep the suite small and end-to-end in the real sense:
+
+1. launch → sign in
+2. the core action of the app, once
+3. the screen reflects it
+4. kill and relaunch — the data is still there
+
+Step 4 catches storage and migration bugs that nothing else sees.
+
+## Never
+
+- Snapshot tests. Huge, meaningless, and "updated" reflexively. A snapshot
+  passes while the handler stops firing.
+- Testing that React Navigation navigates. Assert that pressing the control
+  calls navigate with the right target; the library's own behaviour is not
+  ours to test.
+- Chasing coverage through screen composition files. The value sits in the
+  logic modules and the e2e flows.
+
+## Release risk splits in two
+
+- **JS-only change** — ships over the air (EAS Update). The JS suite really
+  is the gate, and a bad one rolls back in minutes.
+- **Native change** — SDK, a plugin, a native dependency. Needs a build and a
+  device test, and it **cannot be rolled back** once it is in a store.
+
+Treat the second kind as a different category of change, not a bigger one.

package/template/skills/observability/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: observability
+description: "Wire error monitoring, structured logging, and analytics into an app. Use when setting up a new app, before first release, or when instrumenting a milestone's KPIs."
+---
+
+# Wiring observability
+
+Mandatory before first release. See
+`.claude/rules/observability.orchestra.md` and
+`.claude/rules/analytics-kpi.orchestra.md` for the rules this implements.
+
+## Order
+
+1. **Error monitoring first.** It is the thing you need most on the day
+   something breaks, and the thing hardest to add under pressure.
+2. **Structured logging** — server side.
+3. **Analytics** — once the KPIs are known. Instrumenting before you know
+   what you are measuring produces events nobody reads.
+
+## Error monitoring checklist
+
+- [ ] SDK initialised as early as the app's lifecycle allows
+- [ ] release tagged with version **and** commit sha
+- [ ] symbols uploaded in CI — source maps, dSYMs, mapping files
+- [ ] environment set, so staging noise does not drown production signal
+- [ ] PII scrubbing configured **before** the first event is sent
+- [ ] a deliberate test error verified end to end, in the dashboard
+- [ ] alerting routed somewhere a human actually reads
+
+An error monitor nobody has seen an event from is not wired. Prove it.
+
+## Logging checklist
+
+- [ ] JSON output, one event per line
+- [ ] correlation id per request, on every line for that request
+- [ ] levels used honestly — `error` means someone should look
+- [ ] no secrets, no PII, no full request bodies
+- [ ] `debug` off in production
+
+## Health checklist
+
+Two endpoints, because they answer different questions. `/health` says the
+process is up; `/ready` says it can serve. The platform healthcheck points at
+readiness, so this is the thing that decides whether a release is promoted.
+
+- [ ] `/health` cheap, no dependencies
+- [ ] `/ready` probes every dependency the service cannot serve without
+- [ ] it answers 503 and **names** the dependency that failed
+- [ ] a test makes it fail — a readiness check that cannot fail is worse
+      than none
+- [ ] a new dependency adds its probe and its failing test in the same change
+- [ ] the platform's `healthcheckPath` points at `/ready`
+
+## Feature flag checklist
+
+A flag exists to protect the service, so the lookup must never be able to
+take it down.
+
+- [ ] one typed registry — no string literal at a call site
+- [ ] every lookup bounded by a timeout
+- [ ] a failed lookup is reported and answered with the flag's fallback,
+      never thrown into a handler
+- [ ] a kill switch falls back to **false**: if we cannot ask whether the
+      risky path is allowed, the answer is no
+
+## Analytics checklist
+
+- [ ] event names and payloads in one typed schema module per app
+- [ ] call sites import from the schema — no string literals
+- [ ] naming convention picked once: `object_action`
+- [ ] view event per screen or route
+- [ ] start, success, **and failure with a reason code** on critical flows
+- [ ] no PII in properties
+- [ ] consent gate respected before anything is sent
+- [ ] tests assert the event fires once with the right shape
+- [ ] events observed actually arriving before the milestone closes
+
+## Common failures
+
+**Instrumenting the wrapper, not the action.** An event fired three layers
+from the user eventually fires for the wrong reason. Instrument where the
+action happens.
+
+**Only tracking success.** A funnel with no failure events tells you people
+left but never why — which is the only thing you wanted to know.
+
+**Swallowing the error you just reported.** Report and rethrow, or handle it
+so the user gets a correct outcome. Hiding a crash is not handling it.
+
+**Shipping without verifying.** Untested instrumentation is usually broken
+instrumentation. Send one real event and look at it.

package/template/skills/project-structure/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: project-structure
+description: "Where a new file goes — the three questions that decide it, and why third-party wrappers have a fixed home. Use whenever creating a module, component, hook or utility rather than editing an existing one."
+---
+
+# Skill: Project Structure
+
+## The fact everything else follows from
+
+**"Where does this go?" answered by judgement produces a different answer
+every time.**
+
+Nobody is wrong individually. One phase puts the Stripe call in the handler,
+the next puts it in `utils/`, a third writes a `PaymentService`. Six
+milestones later the same concern lives in four places, and no gate noticed —
+because none of it is a defect, it is drift.
+
+So the answer is a procedure, not a preference.
+
+## Three questions, in order
+
+Take the first one that is true.
+
+| Question | Where | What follows |
+|---|---|---|
+| **Does it call a third party's SDK or HTTP API?** | `src/integrations/<provider>/` | Coverage held at **100%** |
+| **Does more than one feature use it?** | `src/lib/` | Needs a doc comment with an example |
+| **Otherwise** | `src/features/<domain>/` | Nothing outside may import its internals |
+
+Feature-first, including on the backend. A layer-first tree — `controllers/`,
+`services/`, `models/` — spreads one change across four directories and gives
+you no place to draw a boundary: `services/` has no owner, so nothing stops
+one domain reaching into another. See
+`.claude/skills/architecture/SKILL.md` on what makes a boundary real.
+
+**Before creating anything, look in `src/lib/` and the feature you are in.**
+The duplicate that costs is the one written by someone who did not know the
+first existed.
+
+## Why integrations has a fixed home
+
+Two reasons, and neither of them is swappability.
+
+**The test suite needs something to hold.** The rule is that a function
+calling into a third-party library has a test, so that a dependency bump which
+changes behaviour turns the suite red — that is what makes a green Dependabot
+PR a merge signal. Called inline across a dozen handlers, there is no function
+to test and the bump goes green.
+
+**The policy is applied once.** Timeout, bounded retry, circuit breaker,
+mapping the provider's errors into ours, keeping the key out of the logs.
+Spread across a dozen call sites you will miss one, and the one you miss is
+the one that hangs.
+
+### It is a seam, not an abstraction
+
+| | Seam wrapper | Abstraction wrapper |
+|---|---|---|
+| Exists for | somewhere to test, one place for policy | pretending the vendor is interchangeable |
+| Shape | thin; this app's types, this app's needs | provider-neutral, lowest common denominator |
+| Justified by | the testing rule, today | a migration that may never happen |
+
+A seam wrapper is allowed to look obviously like the provider it wraps. It
+should. The abstraction version is what
+`.claude/rules/code-standards.orchestra.md` forbids — one implementation, and
+a guess about the future.
+
+**Migration is the secondary benefit, and it is version upgrades, not vendor
+swaps.** A major with a renamed method touches one file instead of twelve.
+That happens several times a year; a vendor swap mostly never does.
+
+### The 100% asks for exercise, not a test file
+
+An integration test that drives the wrapper through a faked HTTP boundary
+satisfies it completely. Do not add a unit test beside the wrapper to repeat
+what a route test already covers — that is writing a test to move a number,
+which the testing rule tells you to refuse rather than comply with.
+
+Fake the provider at the **network** boundary, never by mocking the wrapper.
+Mocking the wrapper means the wrapper is never tested, and the wrapper is the
+thing that breaks when the provider changes.
+
+## Components
+
+Two levels, not four. Atoms-elements-molecules-organisms sounds precise and
+is not: nobody places `FormField` the same way twice, and the folders drift
+into an argument.
+
+| Level | Contains | May import |
+|---|---|---|
+| **Primitives** — `src/design/` | Button, Input, Text. No business logic, no data fetching. | other primitives only |
+| **Compositions** — beside the feature that uses them | Anything that knows what the app does | primitives, and their own feature |
+
+The rule worth keeping from atomic design is the **import direction**: a
+primitive never imports a composition. That one is checkable by reading a
+diff. The taxonomy is not.
+
+A component used by a second feature moves up to shared — on the second use,
+not in anticipation of it.
+
+## Types live beside what they describe
+
+A global `types/` becomes a file everything imports, which is the opposite of
+a boundary. A type that describes a feature's data lives in that feature; a
+type crossing a boundary lives with the interface that defines it.
+
+## Signs the structure has stopped working
+
+- A change to one behaviour touches four directories.
+- Two features import each other.
+- `lib/` is the biggest directory in the app.
+- The same provider's SDK is imported in more than one place.
+- A file is named for a technical role — `helpers`, `managers`, `services` —
+  rather than for what it does.

package/template/skills/push-notifications/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: push-notifications
+description: "Delivering push to iOS and Android — permission timing, token lifecycle, payload choice, deep links, and why none of it can be tested in a JS runner. Use for any phase that sends, receives, or routes a notification."
+---
+
+# Skill: Push Notifications
+
+## The fact everything else follows from
+
+**Nothing in the JS test suite can tell you push works.**
+
+`jest-expo` runs components in Node against mocked native modules, so the
+permission call, the token callback, the background handler and the deep link
+are all mocked into success. The suite is green and the notification never
+arrives.
+
+Push needs a build with your own credentials, on a real device, with the app
+in each of three states — foreground, background, terminated. Anything less
+tests the mock. This is the same reason the device layer is not optional in
+`.claude/skills/mobile-testing/SKILL.md`.
+
+Resolve the SDK's current API and constraints from its own docs at
+implementation time. This area changes across SDK releases, and a handler
+signature written from memory compiles and silently never fires.
+
+## Permission is a product decision, not a setup step
+
+The prompt can be shown **once**. A denial is close to permanent — the system
+stops presenting the dialog, and the only route back is Settings.
+
+| When you ask | Roughly what you get |
+|---|---|
+| On first launch, cold | 15–20% |
+| After onboarding | 40–50% |
+| At the moment the user turns on a feature that needs it | 70–80% |
+
+So: explain the value, or better, ask at the moment the user does something
+that obviously requires it. Never on launch.
+
+- After a denial, do not re-prompt. Offer a route to Settings instead.
+- iOS provisional authorisation delivers quietly with no prompt at all —
+  worth considering when the value is not yet obvious to the user.
+- Android 13+ needs a runtime permission of its own. Treat it as a real
+  prompt with the same timing rules, not a manifest entry.
+
+## The token is a lifecycle, not a value
+
+The single most common defect: a token cached once and never refreshed, so
+delivery quietly stops for users who reinstalled.
+
+1. **Take it from the callback**, every launch. Never from storage as the
+   source of truth.
+2. **Refresh replaces it.** The refresh callback is not optional — the token
+   changes on reinstall, restore, and at the platform's discretion.
+3. **Key it by device, and associate a user.** One user has several devices;
+   one device may see several users. A token with no user cannot be targeted;
+   a token with no device id produces duplicates.
+4. **Delete on rejection.** When the provider says the device is not
+   registered, that token is dead. Keeping it means a growing share of your
+   sends fail, and your delivery rate becomes a number nobody trusts.
+5. **Treat it as opaque.** No parsing, no format assumptions.
+
+A push token identifies a device belonging to a person. It never goes in a
+log line, an error report, or an analytics property — see
+`.claude/rules/security.orchestra.md`.
+
+## Payload: visible or data-only
+
+This is the choice that decides whether your handler runs at all.
+
+| You want | Payload | Because |
+|---|---|---|
+| The user to see something now | **Visible** | Delivery is prioritised and the system displays it |
+| To sync in the background | **Data-only** | A visible payload is handled by the system, not your code |
+| Your own notification UI | **Data-only** | You build and post it |
+
+Two constraints that bite:
+
+- **Silent delivery is best-effort.** The OS may delay or drop it — battery,
+  Doze, Low Power Mode. Never carry something time-critical this way.
+- **The background handler has seconds, not minutes.** Enqueue the work and
+  return. Doing the work inline gets the process killed mid-write.
+
+On Android, a notification channel must exist before anything appears at all,
+and a notification icon must be white-on-transparent — a coloured one renders
+as a white square, which reads as a bug in your app.
+
+## Foreground, background, terminated
+
+Three states, three code paths, and they are handled in different places.
+A notification that works in the foreground and does nothing from terminated
+is the normal outcome of testing only one.
+
+Deep linking is where this shows up first: opening from a terminated state
+means the route is resolved **before** your navigation tree exists. Buffer
+the target and apply it once navigation is ready, rather than dropping it.
+
+Every one of the three gets tested by hand on a device before the phase
+closes. There is no substitute.
+
+## The send side
+
+Sending is a third-party seam, so it has a test —
+`.claude/rules/testing-standards.orchestra.md`. Fake the provider **at the
+HTTP boundary**, never by mocking your own `sendPush()`, because the wrapper
+is exactly what breaks when the provider changes.
+
+Treat it like any other outbound call: timeout, bounded retry with jitter on
+transient failures only, and a reported failure rather than a swallowed one.
+See `.claude/skills/architecture/SKILL.md`.
+
+- **A send is not a delivery.** Accepted by the provider means queued. Record
+  the two separately or your funnel is fiction.
+- **Batch and rate-limit your own sends.** A fan-out that hits the provider
+  as fast as it can is throttled, and the throttling arrives as partial
+  failure.
+- **Never send in a loop over users inside a request handler.** Queue it.
+
+## Measuring it
+
+Push is a feature with a funnel, so it is instrumented like one —
+`.claude/rules/analytics-kpi.orchestra.md`:
+
+- permission asked, granted, denied
+- token registered, refreshed, rejected
+- sent, delivered, opened
+- and the **failure** at each step, with a reason code
+
+Without the failure events you will know engagement dropped and never why.
+No PII in any of those properties, and the token is never a property.
+
+## Anti-patterns
+
+- **Asking on first launch.** You spend the one prompt you get on a user who
+  does not yet know what the app does.
+- **Re-prompting after denial.** The system ignores it; the user does not.
+- **Caching the token long-term.** Delivery stops silently for reinstalls.
+- **A visible payload when you needed the background handler.** The system
+  displays it and your code never runs.
+- **Relying on silent push for anything time-critical.** Delivery is not
+  guaranteed and you will not be told.
+- **Heavy work in the background handler.** The process is killed partway.
+- **Skipping the notification channel.** Nothing appears at all on modern
+  Android, with no error anywhere.
+- **Shipping without testing the terminated state.** It is the state most
+  users are actually in.

package/template/skills/react-best-practices/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: react-best-practices
+description: "React and Next.js implementation patterns — data fetching, boundaries, imports, state. Use for any phase writing React components."
+---
+
+# Skill: React Best Practices
+
+## When to Use
+Phase involves React or Next.js frontend development.
+
+## Checklist
+- [ ] **No waterfall fetches:** use `Promise.all` for parallel data, `Suspense` boundaries for streaming
+- [ ] **Direct imports:** never import from barrel files (`index.ts`) — import from exact module path
+- [ ] **Server components by default:** only add `"use client"` when state/effects/browser APIs needed
+- [ ] **Lazy load heavy components:** `next/dynamic` or `React.lazy` for below-the-fold content
+- [ ] **Memoize expensive renders:** `React.memo` for components with stable props, `useMemo` for expensive computations
+- [ ] **Primitive dependencies in hooks:** avoid objects/arrays in `useEffect` deps — extract primitive values
+- [ ] **No duplicate serialization:** don't pass same data as both prop and context
+- [ ] **Parallel route fetching:** use `Promise.all` in `loader`/`getServerSideProps`, not sequential `await`
+- [ ] **SWR/React Query for client data:** deduplication, caching, revalidation built-in
+- [ ] **Passive event listeners:** `{ passive: true }` for scroll/touch handlers
+- [ ] **Hoist static JSX:** constant JSX outside component body to avoid re-creation on render
+- [ ] **Use `Map`/`Set` for lookups:** not `Array.find()` in render paths
+
+## Common Mistakes
+- Sequential `await` in data fetching → blocks waterfall, use `Promise.all`
+- Barrel file imports → prevents tree-shaking, entire module loaded
+- `"use client"` on everything → loses server component benefits (streaming, zero bundle)
+- Complex objects in `useEffect` dependencies → infinite re-render loop
+- Event listeners without cleanup → memory leak in `useEffect`
+- Fetching in `useEffect` without SWR/React Query → no dedup, no cache, race conditions

package/template/skills/realtime/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: realtime
+description: "Pushing updates to a connected client — choosing between polling, SSE and WebSocket, authenticating the connection, surviving reconnects, and what changes when there is more than one instance. Use for any phase adding live updates, presence, or a subscription."
+---
+
+# Skill: Realtime
+
+## The fact everything else follows from
+
+**A connection is state, and state is what makes a service hard to deploy.**
+
+A stateless service scales by adding an instance and deploys by replacing
+one. A connection breaks both: the client is pinned to an instance, a deploy
+drops every connection at once, and an event published on instance A never
+reaches a subscriber on instance B.
+
+None of that is a reason to avoid realtime. It is a reason to be sure you
+need it, and to decide the multi-instance answer **before** the second
+instance exists — retrofitting it is a rewrite.
+
+## Choose the cheapest thing that works
+
+Work down. Take the first row that is genuinely true.
+
+| If | Use | Why |
+|---|---|---|
+| Updates are seconds-stale-tolerant, or rare | **Polling** | No connection state, no deploy problem, works through every proxy |
+| Server → client only: feeds, progress, notifications, streamed output | **SSE** | Plain HTTP, reconnects and resumes by itself, no protocol to operate |
+| Genuinely bidirectional and low latency: collaboration, presence, games | **WebSocket** | Only case that pays for the state |
+
+Most "realtime" requirements are SSE requirements. A chat that only receives
+is server-to-client. Reaching for WebSocket first buys you connection
+management you did not need.
+
+**SSE's resume is the reason to prefer it.** The browser reconnects on its
+own and sends the last event id it saw; give every event an id and a client
+that missed a minute can be caught up. With WebSocket you write that
+yourself, and most implementations do not.
+
+## Authenticate the handshake
+
+The upgrade request is the only place authorisation happens. After it, you
+have a socket with no request cycle to check anything against.
+
+- Authenticate **during** the handshake, and reject before the upgrade
+  completes. Never accept first and check on the first message.
+- **The browser WebSocket API cannot set headers.** Pass a short-lived,
+  single-use ticket obtained over normal HTTP — never the session token in
+  the query string, which lands in every access log.
+- **A token that expires mid-connection matters.** Decide now: close and let
+  the client reconnect, or re-authenticate in-band. Both are fine. Neither
+  happening is a connection authorised by a credential that expired hours ago.
+- Authorise **per subscription**, not once at connect. Joining a room is an
+  authorisation decision, and it is the one most often forgotten.
+
+## Assume every connection dies
+
+Because they do — a tunnel closes, a phone changes network, a proxy times out
+an idle socket, or you deployed.
+
+- **Heartbeat both ways.** A TCP connection can be dead for minutes while
+  both sides believe it is open. Ping, expect a pong, close when it does not
+  arrive.
+- **The client reconnects with exponential backoff and jitter.** Without
+  jitter, a deploy disconnects everyone at once and they all return at once —
+  you knock over the instance that just came up.
+- **Reconnect is not resume.** State the recovery: replay from the last event
+  id, or refetch and replace. "The client will have missed some messages" is
+  a bug that reads as flakiness.
+- **Cap the retries, then say so.** A client that reconnects forever in the
+  background is a battery complaint. Surface a disconnected state and let the
+  user retry.
+
+## Bound everything
+
+An open socket is an invitation, and none of these have a safe default.
+
+- Maximum message size, enforced on receive.
+- Maximum messages per second, per connection — rate limiting at the socket,
+  not just at the HTTP edge.
+- Maximum connections per user, and per instance.
+- Maximum subscriptions per connection.
+- A send queue that **drops or disconnects** when the client stops reading,
+  rather than buffering until the process runs out of memory. This is the
+  failure that takes the service down, and it looks like a memory leak.
+
+Never do synchronous work per message on the event loop. One expensive
+handler stalls every other connection on that instance.
+
+## More than one instance
+
+The moment there are two, an event published on one has to reach subscribers
+on the other. Pick the mechanism deliberately:
+
+- **A pub/sub backplane** — every instance subscribes, every instance
+  forwards to its own connections. Simple, and the usual answer.
+- **A dedicated realtime service** — worth it when the connection count and
+  the request load have genuinely different shapes.
+
+Either way the backplane is now a dependency the service cannot serve
+without, so **it gets a readiness probe** — see
+`.claude/rules/observability.orchestra.md`. A service accepting connections
+it can never deliver to is worse than one refusing them.
+
+Sticky sessions are a workaround, not a design. They break on deploy, they
+unbalance load, and they hide the problem until the day you scale.
+
+## Deploys disconnect everybody
+
+This is normal and it is survivable, if it is designed:
+
+- Close connections **gracefully** on SIGTERM — send a close frame so clients
+  reconnect on purpose instead of timing out. The draining window exists for
+  this; see `.claude/skills/deployment/SKILL.md`.
+- Client backoff with jitter spreads the return.
+- The reconnect path is the same one used after a network drop, so it is
+  already tested.
+
+## Testing it
+
+- The **protocol** is a third-party seam: connect, authenticate, subscribe,
+  receive, reconnect — tested against a real server, not a mocked client.
+  `.claude/rules/testing-standards.orchestra.md`.
+- The **failure paths** are the point: rejected handshake, expired
+  credential, dropped connection mid-stream, a subscription the user is not
+  allowed to make.
+- **Never `sleep` and assert.** Wait for the event; a sleep is a flake with a
+  delay.
+- Instrument connect, disconnect with reason, reconnect, and messages
+  dropped. A realtime feature with no disconnect-reason metric cannot be
+  debugged from the outside.
+
+## Anti-patterns
+
+- **WebSocket where SSE would do.** You now operate a protocol for a feature
+  that only pushes.
+- **Authenticating after the upgrade.** The connection existed before anyone
+  checked.
+- **The session token in the query string.** It is in the access log of every
+  hop.
+- **No heartbeat.** Dead connections accumulate and are counted as users.
+- **Unbounded server-side buffering.** Reads as a memory leak, is actually a
+  slow client.
+- **Broadcasting to everyone and filtering on the client.** Every client
+  receives data it is not allowed to see; the filter is decoration.
+- **Assuming one instance.** Works perfectly until the day it matters.