agentic-team 0.0.0-stage → 6.1.0

package/template/rules/pull-request.orchestra.md

@@ -0,0 +1,213 @@
+# Pull Requests
+
+**One task, one PR.** Always — there is no mode in which work reaches the
+user any other way.
+
+One per milestone is the failure this rule exists to prevent, and it happened
+anyway: the diff spans every phase, no reviewer can hold it, and the design
+table has one row while the milestone has ten screens — so the screenshots get
+dropped and nobody notices. A PR is one task, one commit, one screen.
+
+## Body
+
+Use the repo's PR template. Keep it short — the reader wants to know what
+changed and whether it is safe, not how you got there.
+
+- **What** — one or two sentences
+- **Why** — link the milestone or task
+- **Design** — required for any UI change: expected and implemented, side by
+  side, in the template's table. Any deliberate difference is stated with
+  its reason. "Close enough" is not a reason.
+
+  One PR is one task is one screen, so the table has one row and an empty
+  cell has no excuse. The implemented image is the task's `design_capture`,
+  committed under `designs/.captures/` **in this branch** — `gh` cannot
+  upload an image, so a screenshot outside the branch cannot appear here. If
+  it could not be captured, the cell carries the reason. An empty cell reads
+  as a pass nobody observed.
+- **Verification** — the checklist, actually checked
+
+Do not paste the diff into the description. Do not narrate your process.
+Do not paste the acceptance criteria. Read the body back as the colleague
+who will review it: a table of files, a `path:line`, a list of what was
+checked — those came from a tool, and the reader wanted a person.
+
+## Mechanism
+
+The `gh` CLI. Check it before relying on it:
+
+```bash
+gh auth status   # not authenticated → stop and tell the user, do not work around it
+```
+
+Open with a body file, never an inline string — the body contains newlines,
+a table, and backticks:
+
+```bash
+gh pr create --title "#<task-id> - <subject>" --body-file .git/PR_BODY.md
+```
+
+## Naming
+
+| | Shape | Example |
+|---|---|---|
+| Branch | `<git-user>/<task-id>-<slug>` | `sulhadin/123-add-login` |
+| PR title | `#<task-id> - <subject>` | `#123 - Add login` |
+
+The id goes in both so the board finds the work without anyone pasting a link,
+and it is the tracker's own id — a GitHub issue number or a ClickUp task id. With `tracker.provider: none` there is no id, so the branch drops
+that segment and the title is the subject alone.
+
+**The title is not conventional-commit form**, and that is deliberate. A task
+PR accumulates commits — the implementation, then whatever review asked for —
+and each of those *is* conventional. The squash collapses them, and its
+subject is the one place the board's id has to appear.
+
+That squashed subject still passes the scaffolded `commit-msg` hook, which
+accepts `#<task-id> - <subject>` alongside the conventional form for exactly
+this case. Without that, the delivery flow would produce the one commit the
+repo's own gate rejects.
+
+Record the returned URL. Lead reports it and stores it in `context.md`, so a
+later session can find the PR without searching.
+
+Reading the change is `gh pr diff <n>`, and a diff read straight into
+context spends four lines per file on the `diff --git`/`index`/`---`/`+++`
+header. Pipe it — or any `git diff` / `git show` — through
+`.orchestra/scripts/compact-diff.awk`; it replaces those four with one and
+touches nothing else, so every hunk line comes through as git wrote it.
+
+Reading review feedback is also `gh`, and it is two different calls — a
+review body and inline line comments are separate objects, and reading only
+one loses half the feedback:
+
+```bash
+gh pr view <n> --json reviews,comments
+gh api repos/{owner}/{repo}/pulls/<n>/comments
+```
+
+Never poll in a loop. Fetch when the user says the review is ready.
+
+## Review cycle
+
+The review happens **on the pull request**, not in a file beside it. Findings
+land inline, on the line they are about, and the engineer answers them on the
+thread. Nothing about the conversation lives only on somebody's disk.
+
+The loop is: reviewer comments → a fresh engineer with the phase's identity
+fixes, replies and resolves → re-review. Max rounds is `thresholds.stuck_retry_limit`,
+counted by `.claude/hooks/review-rounds.sh`. On exhaustion the user decides
+whether another round is worth it — say what is still open rather than going
+round again.
+
+**An engineer answers, not lead.** It reads the code, the diff and the thread
+before it replies. A thread answered from a summary is a thread answered
+wrong. It is a new engineer each round rather than the one that wrote the
+code, because a resumed agent re-reads its whole history on every call.
+
+### Posting the review — one call, every finding
+
+```bash
+cat > .git/REVIEW.json <<'JSON'
+{
+  "event": "COMMENT",
+  "body": "changes-requested — two or three sentences",
+  "comments": [
+    { "path": "src/auth/session.ts", "line": 42, "side": "RIGHT",
+      "body": "[blocking] The session id is compared with ===, which is not constant time.\n\nUse `crypto.timingSafeEqual` over the two buffers." }
+  ]
+}
+JSON
+gh api repos/{owner}/{repo}/pulls/<n>/reviews --input .git/REVIEW.json
+```
+
+One review, not one call per finding — each separate call is a separate
+notification.
+
+**`COMMENT`, never `APPROVE` or `REQUEST_CHANGES`.** The same account authored
+the pull request and GitHub refuses to let an author approve their own.
+
+So the verdict travels as a **label**, which is the part GitHub will let the
+author set and the part everything else can read — the board, a filter, a
+human scanning the list, and the next agent.
+
+| Label | Means |
+|---|---|
+| `review:changes-requested` | unresolved findings; the engineer is up |
+| `review:approved` | nothing blocking; the task can move on |
+
+```bash
+# once per repo, idempotent — the scaffold does this
+gh label create review:changes-requested -c D93F0B -d "Reviewer found blocking issues" -f
+gh label create review:approved          -c 0E8A16 -d "Reviewer found nothing blocking" -f
+
+# one state at a time, so the two can never both be on
+gh pr edit <n> --add-label review:changes-requested --remove-label review:approved
+```
+
+The label is the handshake between reviewer and engineer, and it is what lead
+reads to decide the next move. The review body still carries the summary, but
+a body has to be parsed and a label does not — and a run that dies between
+rounds can pick up exactly where it left off by asking the pull request what
+state it is in.
+
+Every inline comment names the problem in a sentence and says what to do
+instead. A comment that only objects makes the next agent guess.
+
+### Reading the threads
+
+REST returns comments; only GraphQL carries the thread id and whether it is
+resolved, and both are needed to answer one.
+
+```bash
+gh api graphql -f query='
+  query($o:String!,$r:String!,$n:Int!) {
+    repository(owner:$o, name:$r) { pullRequest(number:$n) {
+      reviewThreads(first:50) { nodes {
+        id isResolved path line
+        comments(first:20) { nodes { body author { login } } }
+      } } } } }' -f o={owner} -f r={repo} -F n=<n>
+```
+
+### Answering and resolving
+
+Reply on the thread, then resolve it. A few words on what was done and the
+commit id — the diff says the rest.
+
+```bash
+gh api graphql -f query='
+  mutation($t:ID!, $b:String!) {
+    addPullRequestReviewThreadReply(input:{pullRequestReviewThreadId:$t, body:$b}) {
+      comment { id } } }' -f t=<thread-id> -f b="Fixed with timingSafeEqual — a1b2c3d"
+
+gh api graphql -f query='
+  mutation($t:ID!) {
+    resolveReviewThread(input:{threadId:$t}) { thread { isResolved } } }' -f t=<thread-id>
+```
+
+Resolve only what you actually addressed. A thread resolved without a fix is
+worse than one left open, because the next reader believes it.
+
+If you did something other than what was asked, say why in the reply. If you
+disagree, say so and leave the thread open — resolving a disagreement is not
+answering it.
+
+Never poll in a loop. A human review is fetched when the user says it is
+ready.
+
+## Who merges
+
+Decided by the `--auto` flag on `/orchestra:start`, and by nothing else.
+
+| | Who merges | What follows |
+|---|---|---|
+| normal | **the human**, squashing | lead waits; a task whose `depends_on` is unmerged does not start |
+| `--auto` | lead, squash-merging | commit link posted on the tracker task, status moved, branch deleted |
+
+Outside `--auto`, **never merge your own PR unless explicitly told to.**
+
+**Never stack a branch on an unmerged branch** to avoid waiting. The human
+squashes, so the parent's commits reappear in the child's diff until it is
+rebased, and an agent doing that on every task will get it wrong. Waiting is
+the honest cost of reviewing per task — say what is open and what is blocked
+rather than stalling silently.

package/template/rules/role-boundaries.orchestra.md

@@ -0,0 +1,117 @@
+# Role Boundary Enforcement
+
+Before writing ANY file, check your role's ownership scope.
+
+## Ownership Map
+
+| Role | Can Write | Everything Else |
+|------|-----------|----------------|
+| Orchestrator | `.orchestra/roles/`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `.orchestra/stacks/`, `.orchestra/trackers/`, `.orchestra/scripts/`, `.claude/agents/`, `.claude/hooks/`, `.claude/rules/*.orchestra.md`, `.claude/skills/*/SKILL.md`, `.claude/commands/orchestra/`, `CLAUDE.md`, `docs/` | Refuse |
+| PM | `.orchestra/milestones/*` (prd, milestone, grooming, phases) | Refuse |
+| Lead | `.orchestra/milestones/*/context.md` | Refuse |
+| Scaffolder | `.orchestra/config.yml` (verification, tracker, observability keys only), scaffolded app files, repo config | Refuse |
+| Tracker | Tracker id frontmatter in `.orchestra/milestones/*` | Refuse |
+| Sub-agents | Only what phase `## Scope` defines | Refuse |
+| Reviewer | Review verdict in phase file only | Refuse |
+
+Some entries on the Orchestrator's list are **not** blocked by the hook below,
+each for its own reason. `.orchestra/blueprints/` is where `/orchestra
+blueprint` writes, `.orchestra/config.yml` is merged rather than overwritten,
+and `CLAUDE.md` keeps everything outside the orchestra section for the user —
+the installer preserves all three on upgrade, so an edit there is not lost
+work. `docs/` is not installed into a project at all; it is this repo's own
+documentation, so in an installed copy there is nothing under that name to
+protect and blocking it would only block the user's own docs.
+
+They stay on the ownership map because a role should still not reach into
+them. They are simply not things a hook can decide.
+
+## Enforced, not asked for
+
+Three `PreToolUse` hooks. The first blocks Write and Edit against installed
+system files. The second holds a session inside the role it declared. The
+third caps review rounds per phase.
+
+### The system-file hook
+
+Two questions decide it, and neither is "which role is running": a slash
+command is a markdown prompt and cannot export anything a hook could read on
+its own, so a guard built only on the role would never fire.
+
+**Which repo is this?** In the orchestrator repo these files are source, and
+the hook allows everything. Elsewhere they are build output.
+
+**Did Orchestra put this file here?** `.orchestra/.installed.json` records
+every file the installer wrote, and the hook blocks exactly that list.
+
+The manifest exists because the answer stopped being guessable. Rules carry a
+`.orchestra.md` suffix, so a system rule can be told from one you wrote.
+Skills lost that marker when they became directories, and a list of globs
+cannot tell a shipped skill from yours — so it blocked both, including the
+extension point `docs/skills.md` tells you to use, and including a stack's
+own `apps/<name>/.claude/` pack. The upgrade had the same blindness from the
+other side: a skill this project stops shipping looked like one you wrote, and
+survived forever. The manifest answers both, and retires what a new version no
+longer ships.
+
+**`.orchestra/config.yml` is never blocked.** It is merged on upgrade rather
+than overwritten, so an edit survives — and `/orchestra:setup` writes its
+verification keys, which `.orchestra/README.md` has always documented as an
+exception the hook did not implement.
+
+Neither are `.orchestra/milestones/`, `blueprints/`, roles you create, or
+skills and rules you write: none of them is in the manifest, because the
+installer preserves them.
+
+When it blocks: make the change in the orchestrator repo and reinstall, or —
+if it is genuinely project-specific — put it in the app's own `CLAUDE.md`, a
+project skill of your own, or `config.yml`, none of which is overwritten.
+
+### The role hook
+
+The ownership map above was prose, and a PM opened a pull request. So the
+role is now something a hook can read: each role command has the agent run
+one Bash line — `true # orchestra-role=product-manager` — and the hook, which
+sees every Bash call together with the session id Claude Code passes it,
+records the pair under `.orchestra/.sessions/`. Every later call in that
+session is judged against it. Two terminals are two sessions; the PM's marker
+never touches lead.
+
+What it refuses for the PM: a Write or Edit outside `.orchestra/milestones/`;
+`gh pr` in any form; a new branch; merge, rebase, cherry-pick, a hard reset,
+a force push; `git commit -a`; `git add` of anything but milestone files;
+any `Agent` launch other than `milestone-reviewer` and `tracker`; any
+`Workflow`; and a ClickUp task write carrying a status other than the
+backlog one. The last three came from one afternoon: the word "ultracode" in
+a message told the platform to use the Workflow tool, and a PM whose role
+said "cannot review code" ran a multi-agent code review, recommended itself
+for it, and opened the task straight into `in progress`. Lead and the
+Orchestrator are recorded and, for now, not restricted — lead's sub-agents
+write code in the same session, and a restriction there would block the
+work it exists to do.
+
+Two things are structural rather than hook-judged, because they do not
+depend on the role. `Workflow` is denied in the project's `settings.json`;
+no role runs one. The reviewer and the milestone reviewer carry
+`disallowedTools: [Write, Edit, NotebookEdit]` in their frontmatter; they
+review, and Claude Code removes the tools rather than asking them not to.
+
+No marker means no role, and nothing is refused. That is discussion mode.
+
+When it blocks, the message says why. Say so to the user and stop; the
+answer is never to find a command the pattern does not match.
+
+### The review-round hook
+
+`.claude/hooks/review-rounds.sh` counts reviewer launches per phase, from the
+`Phase:` line lead puts in every reviewer prompt, in
+`.orchestra/.sessions/review-rounds.json`. Past `thresholds.stuck_retry_limit`
+it refuses the launch until the prompt quotes the user's approval. The cap
+was prose, and a run read "loop until clean" as overriding it.
+
+## Rules
+
+- Check what file you'd write to, not what the user said
+- If user insists → still refuse: "Outside my scope as {role}. Use /orchestra:{command}."
+- Discussion mode (no role) → no restrictions
+- Reading → always allowed

package/template/rules/security.orchestra.md

@@ -0,0 +1,106 @@
+# Security
+
+Not a review checklist item — a property of the code as it is written.
+
+## OWASP is the reference
+
+When a security question has an OWASP answer, that answer is the one — the
+cheat sheets for how to do a specific thing, the ASVS for what a review
+should ask.
+
+It is named here rather than left implicit because "industry standard
+practice" resolves to whatever the model remembers, and what it remembers is
+usually a few years stale. Password storage is the clearest case: the
+recommended algorithm and its parameters have changed more than once, and a
+work factor written from memory is weaker than the one somebody thinks they
+configured.
+
+**So it is read at implementation time, not recalled**, the same as a library
+version — see `.claude/rules/dependency-upgrade.orchestra.md`. Quote the
+setting you took and where it came from, in a comment beside the code.
+
+Where the guidance offers several acceptable options, choosing among them is
+an engineering decision that gets written down with its reason. The scaffolded
+backend hashes with the 16 MiB scrypt parameters rather than OWASP's primary
+128 MiB set, because a login route allocating 128 MiB per attempt is the
+cheapest way to exhaust a small container — the comment says exactly that, and
+the numbers behind it were measured.
+
+Deviating without a reason is not an option this rule offers.
+
+## Secrets
+
+- Never in source. Never in a commit. Never in a log line, an error
+  message, or an analytics property.
+- Read from the environment. Fail loudly at boot when a required one is
+  missing — a service that starts without its credentials and fails on the
+  first request is harder to diagnose than one that refuses to start.
+- `.env` is gitignored in every project, always. `.env.example` is committed,
+  and it is **generated from the validating schema**, never written beside it
+  — a hand-kept example is wrong the first time somebody adds a variable and
+  forgets, and a new engineer trusts it anyway.
+- If a secret is ever committed, rotating it is the fix. Removing the commit
+  is not — assume it was scraped the moment it was pushed.
+
+**Enforced, not asked for.** gitleaks runs in its own workflow over the full
+history — a secret committed and later deleted is still leaked, so scanning
+the tip would miss every one of those — and in the pre-commit gate over
+staged changes, where it is still cheap to fix.
+
+## The rules a machine can check
+
+`scripts/policy-check.mjs` runs in the gate. These are the checks it makes
+that belong to this rule — it decides others too;
+`.claude/rules/performance.orchestra.md` and
+`.claude/rules/comments.orchestra.md` each list their own:
+
+| Check | What fails |
+|---|---|
+| `swallowed-error` | a catch that neither handles nor reports |
+| `query-by-testid` | `getByTestId` / `onNodeWithTag` in a test |
+| `mocked-database` | `vi.mock` / `jest.mock` aimed at a db module |
+| `interpolated-sql` | a template literal passed to query/execute/raw |
+
+Only checks that can be decided precisely live there. **Authorization on a
+route and PII in a log line cannot be**, so they stay review items below
+rather than becoming a check that cries wolf — a gate people learn to
+override is worse than no gate.
+
+## Input
+
+- Validate at the boundary, before anything else touches it.
+- Parameterised queries only. String-built SQL is a defect regardless of
+  where the input came from.
+- Escape on output according to the sink — HTML, SQL, and a shell command
+  need different treatment, and "it was already validated" is not one of
+  them.
+- Size limits on uploads and request bodies.
+
+## Authorisation
+
+- Checked on the route, not in a helper a future route can forget to call.
+- Deny by default. A new endpoint is closed until it is deliberately opened.
+- Never trust a client-supplied id to imply ownership — verify it.
+
+## Dependencies
+
+- Anything added is checked for maintenance, per
+  `.claude/rules/dependency-upgrade.orchestra.md`.
+- Audit runs in CI. A known critical vulnerability blocks the merge.
+- Prefer the platform over a package. The safest dependency is the one you
+  did not add.
+
+## Client-side
+
+- No secret ever reaches a client bundle. Anything in the browser or the app
+  binary is public.
+- Content Security Policy on web.
+- Certificate pinning where the threat model calls for it, not by reflex.
+
+## Data
+
+- Collect the minimum that answers the question.
+- PII never lands in logs, errors, or analytics — see
+  `.claude/rules/observability.orchestra.md`.
+- Encrypt in transit, always. At rest wherever the data would matter if the
+  disk were taken.

package/template/rules/stuck-detection.orchestra.md

@@ -0,0 +1,25 @@
+# Stuck Detection & Recovery
+
+You are **stuck** when any of these happen:
+- **Same error N times** (N = config.yml `thresholds.stuck_retry_limit`, default 3)
+- **Circular fix** — fixing issue A creates issue B, fixing B recreates A
+- **Verification loop** — verification gate fails max retries on the same check
+- **No progress** — reading files and running commands but not making meaningful code changes
+
+## Recovery Protocol
+
+1. **STOP immediately.** Do not attempt another fix.
+2. **Log** in context.md: phase name, symptom, attempts, root cause hypothesis.
+3. **Try a different approach** (ONE attempt):
+   - Same code fix failed? → entirely different implementation strategy
+   - Dependency broken? → alternative library
+   - Tests fail due to environment? → isolate the test
+4. **If different approach also fails** → escalate to user with options:
+   - Try specific alternative
+   - Skip this phase and continue
+   - Stop execution
+
+## Auto-Recovery (--auto mode)
+
+Try the different approach (step 3) automatically.
+If that also fails → set phase to `failed`, log everything, move to next phase.

package/template/rules/testing-standards.orchestra.md

@@ -0,0 +1,214 @@
+# Testing Standards
+
+**Code without tests is not done.** Write them as part of implementation,
+never as a follow-up phase.
+
+## The rule that decides what to test
+
+> If one of our functions calls into a third-party library, that function
+> has a test. When a dependency is bumped and its behaviour changes, the
+> test must fail.
+
+A green suite is the merge signal for dependency upgrades. That only works
+if the suite covers the seams where our code meets someone else's.
+
+Snapshot tests do not satisfy this. A snapshot passes while a handler
+silently stops firing — assert behaviour, not markup.
+
+## Backend — the shape
+
+The test pyramid is wrong for a backend. It comes from an era when starting
+a database took minutes. A backend is mostly plumbing — parse, validate,
+query, transform, respond — and the bugs live in the seams, not in pure
+functions.
+
+| Layer | How much | What |
+|---|---|---|
+| Unit | few | Pure logic only: date math, pricing, permissions, state machines. No I/O. |
+| **Integration** | **most of the suite** | Route level, through the real app, against a real database. |
+| External services | as needed | Faked at the HTTP boundary. |
+| E2E | a handful | Smoke: it boots, health is honest, signup and login work. |
+
+A route-level test covers routing, middleware, validation, auth, the
+handler, the query and serialisation in one assertion path. That is where
+the value is.
+
+### Never mock the database
+
+Mock it and you test your own mock. A fake repository returns exactly what
+you told it to; it cannot tell you the `WHERE` clause is wrong, the
+constraint is missing, or the transaction does not roll back.
+
+The database driver is a third-party library, so the rule above already
+forbids this.
+
+- Real database, in a container, **same major version as production**.
+- Never SQLite standing in for Postgres — different dialect, different
+  types, different constraint behaviour. You would be testing a database
+  you do not ship.
+- Run migrations against it. Migration testing comes free.
+- Isolation: each test in a transaction that is rolled back, or truncate
+  between tests. Never rely on ordering.
+- Each test creates the data it needs. A shared seed fixture is what makes
+  a suite unmaintainable somewhere around test three hundred.
+
+### Fake external services at the network boundary
+
+Intercept the HTTP call — MSW or a stub server. Do **not** mock your own
+`sendEmail()`.
+
+Mocking your own wrapper means the wrapper is never tested, and the wrapper
+is exactly where a provider's API change bites you.
+
+### Test data
+
+Synthetic, built by factories, created per test. Never a copy of production
+data — it carries PII and it drifts.
+
+## Coverage is a diagnostic, not a target
+
+A single global percentage stops measuring test quality the moment it
+becomes a gate. It measures test quantity instead, and it treats a design
+token file as equal to the module wrapping your database driver.
+
+Four gates replace it:
+
+| Gate | Value |
+|---|---|
+| Global coverage | **ratchet** — may never fall below what the branch already had |
+| Branch coverage of the lines this change touched | `testing.coverage.diff_branch_threshold` |
+| Modules that wrap a third-party library | **100%** |
+| Type-only files, tokens, generated code, entry points | excluded, not counted |
+
+The diff gate is the one that changes behaviour. It asks about the code
+being written now rather than the historical average.
+
+The seam gate is live from the first commit, because the location is a
+convention: anything wrapping a third party lives in
+`src/integrations/<provider>/`, so the glob is known before the first wrapper
+exists. It asks that the wrapper be **exercised**, not that a test file sit
+beside it — a route test driving it through a faked HTTP boundary satisfies
+it. Depth in `.claude/skills/project-structure/SKILL.md`.
+
+Do not chase the global number with unit tests. If the integration tests
+are real, coverage arrives on its own. If tests are being written to move a
+percentage, the gate has started doing harm — say so rather than complying.
+
+## Mutation testing
+
+Coverage says a line ran. Mutation says the line was **checked**.
+
+Stryker rewrites the code one small change at a time — `>` becomes `>=`,
+a return value is replaced — and runs the suite. If the tests still pass,
+nothing was actually asserting that behaviour.
+
+Runs on every pull request, over the files that pull request changed
+(`--mutate` with the changed paths, plus `--incremental`). A full run over
+everything is a scheduled job, not a gate — it takes hours.
+
+A suite at 95% line coverage with a 40% mutation score is decorative.
+
+Stryker reads the TypeScript compiler's JS API, which TypeScript 7 removed.
+On an app using TS 7 the scaffolder skips the install and says so — do not
+work around it by pinning TypeScript backwards. The gate turns on by itself
+once Stryker supports the new compiler.
+
+## Web — jsdom is not a browser
+
+It has no layout engine. `getBoundingClientRect` returns zeros, nothing
+scrolls, CSS is never applied, focus order is approximated. A component can
+be invisible, unclickable or overlapping another and every jsdom test still
+passes.
+
+Component tests therefore run in **real Chromium** via Vitest browser mode.
+Do not swap in jsdom because a test is awkward — the awkwardness is usually
+the bug.
+
+Query by role, never by test id: Testing Library resolves roles from the
+accessible tree, so a div-with-onClick fails the test and accessibility
+becomes something the suite enforces rather than something review notices.
+
+**axe runs as an assertion**, at two levels, because they see different
+failures. In a component test it checks the mounted subtree; in
+`e2e/a11y.spec.ts` it checks the built page, which is the only place contrast
+against the real background, landmark structure and heading order exist at
+all. Both are wired by the stack — accessibility is not a review checklist
+item here.
+
+Depth in `.claude/skills/web-testing/SKILL.md`.
+
+## Mobile is a different shape
+
+Jest does not run React Native — `jest-expo` runs components in Node against
+mocked native modules. The whole JS suite can be green while the app fails
+to build, crashes on launch, or works on one platform and not the other.
+
+So the device layer is not optional there, and two commands belong in the
+gate because nothing else can see what they see:
+
+```
+expo-doctor
+expo install --check
+```
+
+Depth in `.claude/skills/mobile-testing/SKILL.md`. Native iOS and Android
+have their own shapes again — `.claude/skills/ios-testing/SKILL.md` and
+`.claude/skills/android-testing/SKILL.md`.
+
+## Native has two more shapes
+
+**iOS:** a green unit suite does not prove the app launches. A missing
+Info.plist key, an entitlement the profile lacks, a `@main` that throws
+before the first view — no XCTest sees any of them. The launch test is the
+first test worth writing, not the last.
+
+**Android:** a passing debug build proves little about the release build. R8
+shrinks and obfuscates, a keep rule nobody wrote removes a class loaded by
+name, and the release APK crashes on launch with every test green. So
+`assembleRelease` is in the gate.
+
+Both query the accessibility tree rather than an identifier — XCUITest
+through accessible names, Compose through the semantics tree — for the same
+reason web and React Native query by role: it makes the suite enforce
+accessibility instead of review noticing it.
+
+Depth in `.claude/skills/ios-testing/SKILL.md` and
+`.claude/skills/android-testing/SKILL.md`.
+
+## The bundle has a budget, and it is a ratchet
+
+Same shape as the coverage ratchet: the committed baseline is whatever the
+build actually produced. It may fall and it may not rise.
+
+Nobody has to defend "why 180kB", and the build still fails the day a stray
+import pulls in a date library. Measured gzipped, because that is what a
+browser downloads.
+
+Deliberate growth is re-recorded on purpose, in its own commit, so it is a
+decision somebody made rather than a number that drifted.
+
+## A build is part of the suite
+
+`tsc --noEmit` accepts an app that fails to bundle, and neither tests nor
+lint ever load the bundler. The gate runs `build` for that reason, and a
+failure is fixed in the code — never by loosening the config.
+
+## Dependency upgrades
+
+- **minor and patch** green → merge, no changelog needed. That is what the
+  seam rule buys.
+- **major** → a human reads it. A major version is the maintainer stating
+  the contract changed, and some of what changed — default timeouts, retry
+  behaviour, performance — is not visible to any test.
+
+Never loosen a test to make a dependency PR green. See
+`.claude/rules/dependency-upgrade.orchestra.md`.
+
+## Always
+
+- Cover happy path, edge cases, and failure paths — a funnel that only
+  records success cannot tell you why people left.
+- Match the project's existing test style and naming.
+- Run the tests, then break the code and confirm they fail. A test that has
+  never failed has not been tested.
+- One assertion per concept. The test name states the scenario.