agentic-team 0.0.0-stage → 6.1.0

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

@@ -0,0 +1,29 @@
+---
+name: best-practices
+description: "Web application hardening — security headers, CSP, input handling, browser compatibility. Use for any phase preparing a web app for production."
+---
+
+# Skill: Best Practices
+
+## When to Use
+Phase involves web application security, compatibility, or production hardening.
+
+## Checklist
+- [ ] HTTPS everywhere — no mixed HTTP/HTTPS content
+- [ ] Content Security Policy (CSP) header configured
+- [ ] Security headers set: X-Frame-Options, X-Content-Type-Options, Referrer-Policy
+- [ ] No vulnerable dependencies (`npm audit` clean)
+- [ ] Feature detection, not browser detection (`if ('fetch' in window)` not `if (isChrome)`)
+- [ ] Valid HTML5 doctype, charset first in `<head>`
+- [ ] Viewport meta tag present: `<meta name="viewport" content="width=device-width, initial-scale=1">`
+- [ ] Passive event listeners for scroll/touch events
+- [ ] No `innerHTML` with user input — use `textContent` or sanitize
+- [ ] All user input validated + sanitized on both client and server
+
+## Common Mistakes
+- Mixed HTTP/HTTPS content → browsers block mixed requests
+- XSS via `innerHTML` or `dangerouslySetInnerHTML` without sanitization
+- Synchronous XHR blocking main thread → use `fetch` with async/await
+- Browser detection (`navigator.userAgent`) → breaks on new browsers, use feature detection
+- Missing security headers → easy attack vectors
+- Using `eval()` or `new Function()` with user input → code injection

package/template/skills/code-optimizer/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: code-optimizer
+description: "Performance work — query shape, memory, bundle, hot paths. Use for any phase that optimises existing code rather than adding behaviour."
+---
+
+# Skill: Code Optimizer
+
+## When to Use
+Phase involves performance optimization, refactoring for speed, or audit of existing code performance.
+
+## Checklist
+- [ ] **Database:** N+1 queries eliminated, proper indexes on WHERE/JOIN columns, connection pooling configured
+- [ ] **Memory:** No unbounded caches/arrays, streams used for large data, event listeners cleaned up
+- [ ] **Algorithmic:** No nested loops over large datasets (O(n^2)), use Map/Set for lookups instead of Array.find
+- [ ] **I/O:** Parallel fetch with `Promise.all` where independent, no sequential awaits for unrelated data
+- [ ] **Bundle:** No barrel file imports (`import { x } from './utils'`), use direct imports for tree-shaking
+- [ ] **Dead Code:** Remove unused imports, functions, files — verify with `npx tsc --noEmit` + grep
+- [ ] **Caching:** Expensive computations cached (LRU, memoize), HTTP cache headers set for static assets
+- [ ] **Rendering:** Avoid layout thrashing (batch DOM reads before writes), use `content-visibility: auto` for offscreen content
+
+## Common Mistakes
+- Sequential `await` for independent promises → use `Promise.all([a(), b(), c()])`
+- Importing from barrel files (`index.ts` re-exports) → prevents tree-shaking, bloats bundle
+- Array.find/filter in loops → O(n*m), convert to Map/Set for O(1) lookup
+- Missing database indexes on frequently queried columns → full table scans
+- Unbounded in-memory caches → memory leak over time, use LRU with max size
+- Not cleaning up event listeners, intervals, subscriptions → memory leak

package/template/skills/core-web-vitals/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: core-web-vitals
+description: "Frontend performance against LCP, INP and CLS. Use for any phase targeting page experience metrics or a Lighthouse score."
+---
+
+# Skill: Core Web Vitals
+
+## When to Use
+Phase involves frontend performance optimization targeting Google's page experience metrics.
+
+## Checklist
+- [ ] **LCP (Largest Contentful Paint) <= 2.5s:**
+  - Preload LCP image with `<link rel="preload" fetchpriority="high">`
+  - Inline critical CSS (< 14KB)
+  - No render-blocking JavaScript in `<head>` (defer or async)
+  - Server response time (TTFB) < 800ms
+- [ ] **INP (Interaction to Next Paint) <= 200ms:**
+  - No long tasks (> 50ms) on main thread — break up with `requestIdleCallback` or `scheduler.yield()`
+  - Event handlers return quickly — defer heavy work
+  - Avoid forced synchronous layouts (read then write DOM, not interleaved)
+- [ ] **CLS (Cumulative Layout Shift) <= 0.1:**
+  - All images/videos have explicit `width` and `height` or `aspect-ratio`
+  - No content injected above existing content after load
+  - Fonts use `font-display: swap` with `size-adjust` to minimize shift
+  - Reserve space for dynamic content (ads, embeds, lazy content)
+
+## Common Mistakes
+- Images without dimensions → causes layout shift on load
+- Web fonts blocking text rendering → use `font-display: swap`
+- Client-side rendering for LCP element → server-render or prerender it
+- Synchronous third-party scripts in `<head>` → blocks rendering
+- Dynamic banners/modals pushing content down → reserve space or use overlay

package/template/skills/crud-api/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: crud-api
+description: "Creating a resource with standard create/read/update/delete routes. Use for any phase adding a new REST or RPC resource."
+---
+
+# Skill: CRUD API
+
+## When to Use
+Phase involves creating a new resource with standard create/read/update/delete operations.
+
+## Checklist
+- [ ] Define resource schema (Zod or equivalent validation)
+- [ ] Create migration for DB table
+- [ ] Implement endpoints: POST (create), GET (list + detail), PUT/PATCH (update), DELETE
+- [ ] Add input validation on all mutation endpoints
+- [ ] Add pagination on list endpoint (cursor-based preferred over offset)
+- [ ] Add filtering and sorting on list endpoint
+- [ ] Return consistent error format (status code + message + details)
+- [ ] Add proper HTTP status codes: 201 (created), 200 (success), 404 (not found), 422 (validation)
+- [ ] Test all CRUD operations + edge cases (not found, duplicate, invalid input)
+
+## Common Mistakes
+- No pagination on list endpoints (will crash with large datasets)
+- Using offset pagination (slow on large tables) → use cursor-based
+- Not validating request body → runtime crashes
+- Returning 200 for everything → use semantic HTTP codes
+- DELETE without checking ownership → authorization bypass
+
+## Patterns
+- Schema → Type → Validation → Migration flow
+- Repository pattern for DB access (separate query logic from handler)
+- Consistent error response: `{ error: { code, message, details } }`

package/template/skills/debug/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: debug
+description: "Investigating a bug whose cause is not obvious — unexpected behaviour, a production incident, a flaky test. Use when the fix is not yet known."
+---
+
+# Skill: Debug
+
+## When to Use
+Phase involves investigating a complex bug, unexpected behavior, or production issue that isn't immediately obvious.
+
+## Checklist
+- [ ] **Document current state:** exact error message, steps to reproduce, expected vs actual behavior
+- [ ] **Map the system:** trace the execution path from input to error — which files, functions, APIs are involved?
+- [ ] **Gather evidence BEFORE hypothesizing:** read logs, check git blame, inspect network requests, check env vars
+- [ ] **Form hypotheses:** list 2-3 possible causes ranked by likelihood
+- [ ] **Test each hypothesis minimally:** change ONE thing, observe result, revert if wrong
+- [ ] **Check external factors:** dependency versions, API changes, environment differences (dev vs prod)
+- [ ] **Verify the fix:** reproduce the original bug, apply fix, confirm it's resolved, check for regressions
+- [ ] **Document root cause:** what happened, why, and what prevents it from recurring
+
+## Common Mistakes
+- Assuming the bug is where the error appears → trace upstream, the root cause is often elsewhere
+- Changing multiple things at once → can't tell which change fixed it
+- Not reproducing before fixing → you might fix a different bug
+- Treating your own code with less skepticism → YOUR code is the most likely source
+- Proposing fixes without evidence → "I think it might be X" without testing is guessing
+- Not checking if the bug exists in other environments → might be env-specific
+- Fixing the symptom, not the cause → bug will return in a different form

package/template/skills/deployment/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: deployment
+description: "Getting a service to production and back again — health, release gating, smoke, rollback, migrations. Use for any phase that touches CI/CD, containers, environment configuration, or a deploy."
+---
+
+# Skill: Deployment
+
+Implements `.claude/rules/observability.orchestra.md`. Read it first; this is
+the working checklist.
+
+## The fact everything else follows from
+
+**Nothing here protects a release except being able to undo it.**
+
+There is no percentage canary on the platforms this stack targets. What
+stands between a broken build and every user is three things, in order: the
+healthcheck that decides whether the new deployment is promoted, a smoke test
+against the real URL afterwards, and putting the last good commit back when
+that smoke fails.
+
+Rollback is the same path as a normal deploy, deliberately. An untested
+recovery path is not a recovery path.
+
+## Health is two endpoints
+
+| Endpoint | Question | Cost | Fails when |
+|---|---|---|---|
+| `/health` | is the process up? | no dependencies | it doesn't answer |
+| `/ready` | can it serve? | probes every dependency | **503**, naming the one that failed |
+
+The platform healthcheck points at **`/ready`**. This is load-bearing: the
+previous deployment keeps serving until the new one answers 200, so a
+readiness probe that returns 200 with an unreachable database does not
+mislead a dashboard — it promotes a broken release.
+
+- [ ] `/ready` probes every dependency the service cannot serve without
+- [ ] it answers 503 and names the failed dependency, not a bare status
+- [ ] there is a test that **makes it fail** — a probe that cannot fail is
+      worse than none
+- [ ] adding a dependency adds its probe and its failing test in the same
+      change
+- [ ] `healthcheckPath` in the platform config points at `/ready`, not
+      `/health`
+
+## Releasing
+
+- [ ] deploy is gated on the healthcheck, with an overlap window so the old
+      instance drains rather than being cut
+- [ ] a smoke test runs against the deployed URL, not against localhost
+- [ ] the smoke failing triggers rollback, and the rollback is exercised
+- [ ] the `last-good-deploy` tag moves **only after the smoke passes** — so
+      it always names a release observed working, never one that merely
+      deployed
+- [ ] release and commit sha reach the error monitor and every log line
+
+## Environment
+
+- [ ] every variable is read through one validating schema, and boot fails
+      loudly when a required one is missing
+- [ ] `.env.example` is **generated from that schema**, never written beside
+      it — a hand-kept example is wrong the first time somebody forgets, and
+      a new engineer trusts it anyway
+- [ ] `.env` gitignored, always
+- [ ] a secret that was ever committed is rotated; deleting the commit is not
+      the fix
+
+## Migrations
+
+- [ ] run automatically on deploy, never by hand
+- [ ] forward-compatible with the previous release, because both run at once
+      during the overlap window
+- [ ] a destructive change is two deploys: stop using the column, then drop
+      it
+
+## Containers
+
+- [ ] multi-stage build, runtime stage carries no build tooling
+- [ ] non-root user
+- [ ] `.dockerignore` covers `node_modules`, `.git`, test output
+- [ ] SIGTERM drains in-flight requests before exit — the overlap window is
+      wasted if the process dies instantly
+
+## Feature flags
+
+A risky change ships dark. The lookup must never be able to take the service
+down: bounded by a timeout, failures reported and answered with the flag's
+own fallback rather than thrown into a handler. For a kill switch the
+fallback is **false** — if we cannot ask whether a risky path is allowed, the
+answer is no.
+
+Flags live in one typed registry. A string literal at a call site is how they
+rot.
+
+## Common mistakes
+
+- **A readiness probe that returns a constant.** It passes review, passes
+  CI, and promotes a release with a dead database.
+- Pointing the platform healthcheck at `/health`. Liveness answers yes while
+  nothing works.
+- Rolling back by hand through a dashboard. The path nobody scripted is the
+  path nobody can run at 3am.
+- Tagging the deploy as good when it deployed, rather than when it was
+  observed working.
+- Secrets in the image, or in a build argument, which is the same thing.

package/template/skills/error-handling/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: error-handling
+description: "What to do when something fails — typed errors, propagation, what the user sees, and degrading instead of crashing. Use for any phase that adds a failure path, a catch, or an error response."
+---
+
+# Skill: Error Handling
+
+The rule is in `.claude/rules/observability.orchestra.md` and a check
+enforces it: **a catch either handles the error meaningfully or reports it and
+rethrows.** `scripts/policy-check.mjs` fails the gate on an empty catch and on
+a catch whose only body is a log.
+
+That check proves a catch is not empty. It cannot tell whether the user got a
+correct outcome. This skill is about the part that needs a person.
+
+## The fact everything else follows from
+
+**"Handled" means the caller gets a correct outcome — not that the crash was
+hidden.**
+
+```ts
+try {
+  await chargeCard(order);
+} catch (e) {
+  reportError(e);
+  return { ok: true };   // the gate passes. the customer was not charged.
+}
+```
+
+Reported, rethrown-shaped, and wrong. Nothing downstream can tell the
+difference between a payment that succeeded and one that vanished. Deciding
+which of those two this is, is the entire job.
+
+## Three kinds of failure, three different answers
+
+| Kind | Example | Answer |
+|---|---|---|
+| **Expected** | invalid input, not found, conflict | Not exceptional. Return it as a value or throw a typed error the boundary maps to a status. |
+| **Transient** | timeout, 503 from a provider, deadlock | Retry if idempotent, with backoff and a bound. Then give up deliberately. |
+| **A bug** | undefined is not a function, a broken invariant | Do not catch it here. Let it reach the boundary, be reported with its stack, and answer 500. |
+
+The most common mistake is treating the third as the first: a broad `catch`
+around a whole handler turns every bug into a polite message and the defect
+is never seen again.
+
+## Typed at the boundary
+
+The backend stack ships `AppError` with a closed `ErrorCode` union, and
+`toErrorBody` maps it to a status and a body. Use it.
+
+```ts
+throw new AppError("not_found", "Order not found");
+```
+
+- **Never throw a bare `Error` across a route boundary.** It becomes a 500,
+  which tells the caller nothing and pages someone for a 404.
+- **Never let internal detail into the response.** `toErrorBody` returns the
+  minimum for anything unrecognised, deliberately — a stack trace in a body
+  is an information leak, and the message often contains a query.
+- The code is a **closed union**, not a string. A new failure mode is a new
+  member and a new status, decided once, rather than a literal invented at a
+  call site.
+
+Adding a code is a real decision: it is part of the API contract, and a
+client will branch on it.
+
+## Validate once, at the edge
+
+Parse input at the boundary and let everything inside work with a type that
+cannot be invalid. A function that re-checks its arguments is a function that
+does not trust its own signature — and the check will disagree with the
+schema eventually.
+
+That is why the boundary owns validation and the interior does not:
+`.claude/rules/security.orchestra.md` puts it in the same place for the same
+reason.
+
+## Keep the cause
+
+```ts
+throw new AppError("internal", "could not load order");           // no
+throw new Error("could not load order", { cause: original });      // yes
+```
+
+Wrapping is fine; discarding is not. The original stack is the only thing
+that says which line failed. When you rethrow, carry the cause; when you
+report, report the cause too.
+
+## What the user sees
+
+Two audiences, two texts, and they are rarely the same string.
+
+- **The user** gets something actionable: what happened, and what they can do.
+  Not an error code alone, and never a stack.
+- **The operator** gets the detail, in the log, with the correlation id — so
+  a user quoting `x-request-id` from a bug report leads straight to the line.
+  The request logger echoes that header back for exactly this reason.
+
+If a screen can fail, it has a failure state, and the failure state has a way
+forward. `.claude/skills/review/SKILL.md` treats a missing one as a finding.
+
+## Degrading instead of failing
+
+Some dependencies are not required to answer. Say so explicitly, and say what
+the answer is without them.
+
+```ts
+// Recommendations are a nice-to-have; the page renders without them.
+const recommended = await getRecommendations(userId).catch((e) => {
+  report(e);
+  return [];
+});
+```
+
+This is the one place an error is swallowed, and it carries a comment saying
+why failure is acceptable — the exception named in the observability rule.
+Two conditions, both required:
+
+1. The feature is genuinely optional to the outcome.
+2. The failure is still **reported**, so "optional" does not quietly become
+   "permanently broken".
+
+For anything gating a risky path the fallback is **false** — the same
+direction the feature-flag registry falls, and for the same reason.
+
+## Failure paths are tested, not assumed
+
+- Every catch you write has a test that reaches it. An untested error path is
+  usually a broken error path — it is the code least likely to have been run
+  even once.
+- Provider failures are faked **at the HTTP boundary**, never by mocking your
+  own wrapper: the wrapper is where a provider's change bites you, so mocking
+  it tests nothing. `.claude/rules/testing-standards.orchestra.md`.
+- The cases worth writing: a 500 from the provider, a timeout, a malformed
+  body, and the retry that eventually gives up.
+
+Coverage will not tell you these exist. Mutation testing would, which is why
+it is wired even while it waits on the compiler.
+
+## Anti-patterns
+
+- **`catch (e) { report(e) }` in a write path.** The caller now believes the
+  write happened.
+- **Catching to convert everything to `null`.** The caller has no idea
+  whether "nothing" means empty or broken.
+- **One broad try/catch wrapping an entire handler.** It catches your bugs
+  along with the expected failures, and turns both into the same response.
+- **Retrying a non-idempotent write.** This is how a customer gets charged
+  twice.
+- **A message that names the wrong actor.** "Something went wrong" when the
+  input was invalid sends the user looking in the wrong place.
+- **Logging and rethrowing at every level.** One failure, six lines, and none
+  of them the one with the stack. Report where you handle it, not on the way
+  past.

package/template/skills/frontend-design/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: frontend-design
+description: "Building UI that looks deliberate rather than generic — typography, colour, spacing, motion. Use for any phase where visual quality is part of the acceptance criteria."
+---
+
+# Skill: Frontend Design
+
+## When to Use
+Phase involves building UI that needs to look polished, professional, and distinctive — not generic.
+
+## Checklist
+- [ ] **Bold aesthetic direction:** commit to a clear visual concept — not timid, not generic
+- [ ] **Distinctive typography:** avoid overused fonts (Inter, Roboto, Arial) — choose fonts with character
+- [ ] **Cohesive color scheme:** limited palette (3-5 colors) with sharp accent colors
+- [ ] **Intentional layout:** use asymmetry, overlap, or diagonal elements where appropriate — not everything grid-aligned
+- [ ] **Layered shadows:** multiple transparent shadows instead of solid borders (`box-shadow: 0 1px 2px rgba(0,0,0,0.1), 0 4px 12px rgba(0,0,0,0.05)`)
+- [ ] **Concentric border radius:** outer radius = inner radius + padding (nested elements)
+- [ ] **Micro-interactions:** hover states, focus transitions, loading animations — all < 300ms
+- [ ] **Staggered enter animations:** split elements, ~100ms delay between each
+- [ ] **Font smoothing:** `-webkit-font-smoothing: antialiased` for crisp text
+- [ ] **Tabular numbers:** `font-variant-numeric: tabular-nums` for data tables and counters
+- [ ] **Optical alignment:** icons and text optically centered, not geometrically
+
+## Common Mistakes
+- Generic AI-slop aesthetics → every AI tool produces the same look, be distinctive
+- Solid borders everywhere → layered transparent shadows look more refined
+- Geometric centering for icons → optical centering looks correct to the eye
+- Harsh easing functions → use `cubic-bezier(0.4, 0, 0.2, 1)` for natural motion
+- Missing exit animations → enter with animation, exit abruptly looks broken
+- System fonts without thought → typography is 80% of visual quality

package/template/skills/fullstack-infrastructure/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: fullstack-infrastructure
+description: "TypeScript and React conventions that hold in any app — types, hooks, rendering, data flow, performance, i18n. Which libraries, which structure and which tooling are decided by .orchestra/stacks/, not here. Use when writing TypeScript or React in any app."
+---
+
+# TypeScript & React Conventions
+
+What is true regardless of which stack scaffolded the app.
+
+## What this file does not decide
+
+It used to carry a tech stack table and a monorepo tree of its own, naming an
+ORM, an auth scheme, an HTTP client and a component kit. Every one of those is
+decided somewhere that can enforce it, and a skill restating a choice is a
+second source of truth: whichever the agent reads last wins, and nothing
+notices when they drift apart.
+
+| Question | Answered by |
+|---|---|
+| Which libraries, package manager, tooling | `.orchestra/stacks/<stack>/setup.sh` — it installs them |
+| Where a new file goes | `.claude/skills/project-structure/SKILL.md` |
+| Where a component comes from | the web `stack.md`, and `src/components/README.md` |
+| What "handled" means for an error | `.claude/skills/error-handling/SKILL.md` |
+| Testing, commits, security, observability | `.claude/rules/*.orchestra.md` |
+
+What the stacks scaffold today, for orientation only: Drizzle rather than
+Prisma, server-side sessions rather than JWT, `fetch` in
+`src/integrations/<provider>/` rather than an Axios wrapper class, feature-first
+`src/features/<domain>/` rather than a layer-first tree.
+
+**If this file ever disagrees with a stack, the stack is right** — it is the
+thing that actually ran.
+
+## TypeScript
+
+- `strict`, with no per-file exemptions.
+- No `any`. Use `unknown` and narrow it — `any` disables the checker at
+  exactly the boundary you added it to guard.
+- `interface` for object shapes, `type` for unions and intersections.
+- Discriminated unions for anything with states. A boolean pair that can
+  express `loading && error` is a bug waiting for a screenshot.
+- Explicit return types on exported functions. Inference is fine inside a
+  module and a liability across one — a return type that changes silently is
+  a breaking change nobody reviewed.
+- Prefer a union of literals to an enum. It erases at compile time and
+  narrows without an import.
+
+## React
+
+- Function components only.
+- Custom hooks are prefixed `use` — the linter's rules-of-hooks check keys
+  off the name, so a mis-named hook is simply unchecked.
+- `useMemo` and `useCallback` where a measurement says they help. Applied by
+  reflex they add allocation and a dependency array to get wrong.
+- Composition over prop drilling. Context for what is genuinely ambient
+  (theme, locale, session), not to avoid passing two props.
+- Stable keys from the data. An array index makes React reuse the wrong node
+  the first time the list reorders, and the bug looks like corrupted state.
+- `React.lazy` with `Suspense` at route boundaries.
+
+## Data flow
+
+- **Server cache and client state are different things.** Copying a response
+  into a client store gives you two truths and a stale one.
+- Every backend call goes through a wrapper in `src/integrations/<provider>/`
+  — never a raw client call from a component. That is where the timeout, the
+  retry bound and the error mapping live, and it is the only place a test can
+  hold. See `.claude/skills/project-structure/SKILL.md`.
+- Which cache or store library, if any, is the stack's decision. If a project
+  adopts one, it goes in the stack's `setup.sh` so it is installed and
+  covered — not named here.
+
+## Classes vs functions
+
+**Class** when there is lifecycle to hold: an SDK that needs init and
+teardown, or shared configuration across calls.
+**Function** when it is stateless and single-purpose — `formatDate`,
+`slugify`.
+
+Prefer writing a small utility to adding a dependency for it. Reach for a
+package when the implementation is genuinely hard — dates, time zones,
+collation — not when it is twelve lines.
+
+## Performance
+
+- Lazy load routes and anything heavy below the fold.
+- Virtualize long lists.
+- Debounce or throttle high-frequency events at the source, not in the
+  handler.
+- Derive loading and error state from the request, not from booleans set by
+  hand in three places.
+
+## Environment variables
+
+Validated at startup against a schema, so the process refuses to boot on bad
+configuration rather than failing on the first request that needs it.
+
+`.env.example` is **generated from that schema**, never written beside it —
+see `.claude/rules/security.orchestra.md`.
+
+## i18n
+
+Ask whether it is needed before the first string is written; retrofitting
+means touching every component.
+
+When it is: every user-facing string is a key, namespaced by feature. No
+concatenated sentences — word order is not universal, and a sentence built
+from three fragments cannot be translated correctly into most languages.

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

@@ -0,0 +1,100 @@
+---
+name: ios-testing
+description: "Testing strategy for native iOS apps — Swift, SwiftUI, XCTest and XCUITest. Use for any phase that writes or changes tests in a native iOS app."
+---
+
+# Skill: iOS Testing
+
+## The fact everything else follows from
+
+**A unit test does not prove the app launches.**
+
+An iOS app dies for reasons no XCTest sees: a missing Info.plist key, an
+entitlement the provisioning profile lacks, a `@main` that throws before the
+first view, a bundle resource that was never copied. The suite is green and
+the app crashes on the splash screen.
+
+So the launch test is not the top of a pyramid you get to later. It is the
+first test worth writing.
+
+## The layers
+
+| Layer | What belongs here | Runs on |
+|---|---|---|
+| Unit | Pure logic and view models — no UIKit, no SwiftUI | Host, fast |
+| View | SwiftUI views: state transitions and the accessibility tree | Simulator |
+| Integration | The real networking stack, stubbed at the transport | Simulator |
+| UI (XCUITest) | 3–5 journeys, one of them launch | Real simulator |
+| Build | `xcodebuild` for a device architecture | The gate |
+
+## Stub the transport, not your client
+
+```swift
+final class StubProtocol: URLProtocol { /* … */ }
+
+let config = URLSessionConfiguration.ephemeral
+config.protocolClasses = [StubProtocol.self]
+let session = URLSession(configuration: config)
+```
+
+Register a `URLProtocol` subclass and the real `URLSession` runs — your
+request building, your headers, your decoding, your error mapping.
+
+Injecting a `MockAPIClient` instead tests the mock. The client is the thing
+that breaks when the API changes, so it is the thing that must stay in the
+test.
+
+## Query the accessibility tree
+
+```swift
+app.buttons["Add water"].tap()          // yes — the accessible name
+app.buttons["btn_add_water"].tap()      // no — an identifier nobody hears
+```
+
+XCUITest resolves elements through the accessibility tree, which is the same
+tree VoiceOver uses. Query by label and **a control with no accessible name
+fails the test** — accessibility becomes something the suite enforces.
+
+Use `accessibilityIdentifier` only where the visible label genuinely changes
+with locale or data, and keep the label correct anyway.
+
+## Swift Testing for units, XCTest for UI
+
+`import Testing` with `@Test` and `#expect` is the current framework for unit
+and view tests — clearer failures, real parameterised cases, native async.
+
+XCUITest is still XCTest. Do not try to unify them.
+
+Both need `await` discipline: a `@MainActor` view model tested from a
+non-isolated context passes locally and races in CI.
+
+## Never
+
+- **Snapshot tests as the main assertion.** A recorded PNG changes with every
+  OS point release, gets re-recorded without being read, and passes while the
+  button does nothing. Assert state and the accessibility tree instead.
+- Testing that SwiftUI re-renders, or that `NavigationStack` navigates.
+  Assert that the action fires with the right argument.
+- Sleeping to wait. `XCTestExpectation` and `waitForExistence(timeout:)`
+  exist; a `sleep` is a flake with a delay.
+- A simulator-only definition of done. The simulator has no memory pressure,
+  no thermal throttling, no real camera and a different keyboard.
+
+## The build is part of the suite
+
+Build for a **device** architecture in the gate, not only the simulator.
+Simulator builds are x86/arm64-host and skip code signing, so a missing
+entitlement, an unsupported architecture or a bad bitcode setting only
+appears when a real build is attempted.
+
+A release build additionally runs optimisation and dead-code stripping,
+which is where `#if DEBUG` mistakes surface.
+
+## Release risk
+
+An App Store release cannot be rolled back. There is no equivalent of an
+over-the-air JavaScript update unless one was deliberately built.
+
+That makes phased release and a server-side kill switch part of the testing
+strategy rather than an operational afterthought — see
+`.claude/rules/observability.orchestra.md`.