@aacombarro89/praxis 0.1.8 → 0.1.10

package/packages/layer1/session-handoff/rules.md

@@ -2,7 +2,7 @@
 
 Work outlives a single session: at a natural boundary in a verified state —
 never mid-edit — capture context before it's lost. Write handoffs by running
-`/praxis-handoff`, not by hand; it's the next session's only briefing.
+`{{workflow:praxis-handoff}}`, not by hand; it's the next session's only briefing.
 
 ## Delegated execution
 
@@ -11,5 +11,5 @@ neither requiring parallelism: **independent workstreams** (specifiable up
 front, no mid-flight coordination) and **context/budget isolation** (a
 context-heavy or mechanical run worth its own context and a lighter tier —
 holds even for one sequential stream). Name the split at plan time. Produce
-each brief with `/praxis-handoff`, not by hand, and verify a returned
+each brief with `{{workflow:praxis-handoff}}`, not by hand, and verify a returned
 workstream against its success criterion before integrating it.

package/packages/layer1/upkeep/commands/upkeep.md

@@ -4,18 +4,21 @@ argument-hint: [optional-area-to-focus]
 allowed-tools: Bash(npx @aacombarro89/praxis@latest check:*), Bash(npx @aacombarro89/praxis@latest sync:*), Bash(npx @aacombarro89/praxis check:*), Bash(npx @aacombarro89/praxis sync:*), Bash(praxis check:*), Bash(praxis sync:*)
 ---
 
-Focus: $ARGUMENTS — if empty, cover all three passes at a high level.
+Focus: {{arguments}} — if empty, cover all three passes at a high level.
 
 This is the single entry point for "is my methodology layer still current
 with reality?" It sequences three existing checks rather than re-implementing
 them — restating their logic here would duplicate content that drifts
 independently of its canonical home.
 
-1. **Deterministic drift.** Run `praxis check` if the CLI is on PATH; otherwise
+1. **Deterministic drift.** Run `praxis check` if the CLI is on PATH. Otherwise
    fall back to `npx @aacombarro89/praxis@latest check` (pin `@latest` — a bare
    `npx @aacombarro89/praxis` can silently reuse a stale cached build). If it
    reports file drift, run `praxis sync` (or `npx @aacombarro89/praxis@latest
-   sync`) to fix it. Surface managed-block conflicts or broken anchors as-is.
+   sync`) to fix it. Surface managed-block conflicts, shared-project parity
+   drift, or broken anchors as-is. `sync` fixes generated artifacts but must
+   never choose a winner between project-owned `CLAUDE.md` and `AGENTS.md`
+   blocks; route that drift to the instruction pass below.
    This step needs no LLM judgment — do it first so the semantic passes below
    build on a known-good baseline. **If the CLI is unavailable even via npx,
    skip only this step and proceed with steps 2 and 3 — do not skip the entire
@@ -27,10 +30,10 @@ independently of its canonical home.
    invalid-manifest message), the check did not fully run — report that as a
    failure, never as "0 checked, all fine".** A stale npx-cached CLI is the usual
    cause; re-run pinned to `@latest`, and note the version if it still lags.
-2. **Instruction layer.** Perform the update defined by `/praxis-instructions`,
+2. **Instruction layer.** Perform the update defined by `{{workflow:praxis-instructions}}`,
    scoped to the focus above. Follow that command's own steps; do not
    re-derive them here.
-3. **Wiki.** Perform the wiki maintenance defined by `/praxis-wiki`, scoped to
+3. **Wiki.** Perform the wiki maintenance defined by `{{workflow:praxis-wiki}}`, scoped to
    the focus above — it files newly-authored knowledge and lints existing pages,
    and no-ops when there is nothing to do. Follow that command's own steps; do
    not re-derive them here. (Full delegation, symmetric with the audit pass —

package/packages/layer1/upkeep/rules.md

@@ -1,10 +1,14 @@
 ## Upkeep
 
-The methodology layer (instructions, wiki, emitted `.claude/` files) drifts
+The methodology layer (instructions, wiki, emitted agent files) drifts
 from project reality like code drifts from docs. When work reveals drift, or
-produces new durable knowledge to file, run `/praxis-upkeep` — the single
-front gate sequencing `praxis check`, `/praxis-instructions`, and
-`/praxis-wiki` — rather than fixing it ad hoc or piecemeal.
+produces new durable knowledge to file, run `{{workflow:praxis-upkeep}}` — the single
+front gate sequencing `praxis check`, `{{workflow:praxis-instructions}}`, and
+`{{workflow:praxis-wiki}}` — rather than fixing it ad hoc or piecemeal.
+
+When Claude Code and Codex coexist, this gate covers both native instruction
+surfaces. Keep their project-owned shared sections synchronized while preserving
+target-specific guidance; never make one surface import or replace the other.
 
 Run all three passes through the gate even when only one looks like it has
 work — skipping straight to a sub-skill is the piecemeal use this rule

package/packages/layer1/wiki-memory/commands/wiki.md

@@ -10,8 +10,8 @@ You are curating a durable knowledge wiki for this project: linked markdown page
 of long-lived knowledge that a future session reads instead of re-deriving. This
 is the agent's cross-session memory **of the project** — version-controlled and
 shared with the team. It is NOT a per-session handoff (transient — that is
-`/praxis-handoff`) and NOT the authored instruction layer (`CLAUDE.md`,
-`.claude/rules` — that is `/praxis-instructions`).
+`{{workflow:praxis-handoff}}`) and NOT the authored agent instruction layer
+(that is `{{workflow:praxis-instructions}}`).
 
 The wiki has two kinds of durable knowledge:
 - **Derived summaries** compress code, config, and canonical docs. The underlying
@@ -21,7 +21,7 @@ The wiki has two kinds of durable knowledge:
   diverge, surface the drift for human judgment instead of silently overwriting
   one with the other.
 
-Focus: $ARGUMENTS — if empty, refresh and lint the whole wiki at a high level.
+Focus: {{arguments}} — if empty, refresh and lint the whole wiki at a high level.
 
 ## Phase 1 — Locate or create the wiki
 
@@ -31,8 +31,8 @@ Use the first of these that already exists; otherwise create the first one
 2. `wiki/`
 3. `.praxis/wiki/`
 
-- Existing entries: !`ls -R docs/wiki wiki .praxis/wiki 2>/dev/null || true`
-- Today (for log entries, do not guess): !`date +%Y-%m-%d`
+- Existing entries: {{shell:ls -R docs/wiki wiki .praxis/wiki 2>/dev/null || true}}
+- Today (for log entries, do not guess): {{shell:date +%Y-%m-%d}}
 
 Front the wiki with two entry-point files; create them if missing:
 - `index.md` — a catalog of every page: a link and a one-line summary each.
@@ -81,7 +81,7 @@ Health-check the wiki and fix what you can (ask before large deletions):
 - **Contradictions** — derived summaries that disagree with current code/config
   lose to the source; fix the wiki. Canonical-intent entries are different: if
   code and intent diverge, report the drift and route it to a decision/update
-  step (or `/praxis-instructions` for instruction-layer changes) instead of deciding
+  step (or `{{workflow:praxis-instructions}}` for instruction-layer changes) instead of deciding
   automatically. Two wiki entries that disagree resolve to the more recent /
   authoritative / better-supported claim, with the resolution noted.
 - **Stale claims** — derived facts the current code has invalidated: fix or

package/packages/layer1/wiki-memory/rules.md

@@ -2,13 +2,13 @@
 
 Knowledge outlives a single conversation. Keep a durable, in-repo knowledge
 wiki — linked markdown pages a future session reads instead of re-deriving —
-distinct from a handoff (transient) and from `CLAUDE.md`/`.claude/rules`
-(authored instructions). At the start of a task, read the wiki's `index.md`
+distinct from a handoff (transient) and from authored agent instructions
+(the instruction layer). At the start of a task, read the wiki's `index.md`
 and follow the links that bear on the work.
 
 When you learn something durable — an architecture fact, a gotcha, a decision,
 a workflow — file or update it, and periodically lint the wiki for
-contradictions and staleness. Do this by running `/praxis-wiki`, not by hand.
+contradictions and staleness. Do this by running `{{workflow:praxis-wiki}}`, not by hand.
 When reconciling the methodology layer after a change, enter through
-`/praxis-upkeep`; call `/praxis-wiki` directly only for a deliberate single
+`{{workflow:praxis-upkeep}}`; call `{{workflow:praxis-wiki}}` directly only for a deliberate single
 pass (e.g. first-run bootstrap).

package/packages/layer2/node-recipes/rules.md

@@ -12,23 +12,22 @@ Layer 1 rules (think before coding, simplicity first, surgical changes,
 goal-driven execution) apply unchanged — this file adds only what is
 Node-specific.
 
-- **Mirror the nearest module.** Before adding a feature, open the closest
-  existing file that already does the same kind of thing (a sibling in the same
-  directory, an adjacent route/command/service). Copy its structure — imports,
-  exports, error handling, naming — rather than inventing a new shape. The
-  prior art is the template; matching it is verifiable, following prose is not.
-- **One module, one responsibility.** A new `.ts` file exports the smallest
-  coherent unit. Keep pure logic separate from I/O (filesystem, network, process)
-  so the logic is testable without mocks — mirror how the existing modules here
-  already split the two.
-- **Use the platform and installed deps before adding one.** Node stdlib (`node:fs`,
-  `node:path`, `node:crypto`, `fetch`) and a dependency already in
-  `package.json` cover most needs. A new dependency for what a few lines do is
-  debt; justify it against what is already imported in neighbouring files.
-- **Types are the contract.** Type the inputs and outputs at module boundaries;
-  validate external/untrusted input where it enters (a schema validator if the
-  repo already uses one, e.g. zod). Don't re-validate data already typed and
-  checked upstream.
-- **ESM vs CJS, follow the repo.** Match the module system, import extensions
-  (`.js` specifiers under `"type": "module"`), and `tsconfig` target already in
+- **ESM vs CJS, follow the repo.** Match the module system, `.js` import
+  specifiers under `"type": "module"`, and the `tsconfig` target already in
   use — don't introduce a second convention.
+- **Every promise is handled.** `await` it, `return` it, or explicitly `void`
+  it with a comment explaining why. A floating promise swallows its rejection
+  and its ordering.
+- **Never silence the type checker.** No `any`, no `as` cast, no non-null `!`
+  to make an error disappear. Fix the type; a suppressed error is a runtime
+  bug deferred.
+- **Prefer the platform before a dependency.** `node:`-prefixed builtins
+  (`node:fs/promises`, `node:path`, `node:crypto`) and global `fetch` cover
+  most needs; justify a new dependency against what neighbouring files
+  already import.
+- **Throw `Error` subclasses, never strings.** Attach `cause` when
+  re-throwing, and handle `error` events on child processes and streams — an
+  unhandled one crashes the process.
+- **Validate untrusted input where it enters.** Use the repo's validator
+  (e.g. zod) with a non-throwing parse (`safeParse`-style) at the boundary;
+  don't re-validate data already typed and checked upstream.

package/packages/layer2/node-testing/rules.md

@@ -4,34 +4,29 @@ paths: ["**/*.ts", "**/*.tsx", "**/*.test.ts", "**/*.spec.ts"]
 
 ## Node/TypeScript test-layer recipe (Layer 2)
 
-Choosing *where* a test belongs matters as much as writing it. Pick the layer
-that fails for the right reason, and mirror the repo's existing tests of that
-kind for structure and fixtures.
+Choosing *where* a test belongs matters as much as writing it: pick unit,
+integration, or conformance/end-to-end by what could actually break —
+unit for a single module's logic, integration for real seams (filesystem, a
+spawned process, a built artifact), conformance/e2e for rails the whole tool
+must honour. Then mirror the nearest existing test of that same layer for its
+runner, file location, naming, and fixtures rather than inventing a new shape.
 
 Layer 1 rules (think before coding, simplicity first, surgical changes,
 goal-driven execution) apply unchanged — this file adds only what is
 Node-testing-specific.
 
-- **Harness before features.** A rule that matters has a test. Write (or extend)
-  the test that pins the new behaviour *before or with* the code that satisfies
-  it — never land logic whose only check is "it looked right". Make the failing
-  test the prompt: it states what is missing.
-- **Pick the layer by what could break.**
-  - *Unit* — pure logic, branches, parsing, a single module's contract. Fast, no
-    I/O, no fixtures. Default here; most logic belongs at this layer.
-  - *Integration* — two or more modules composed, or real I/O (filesystem, a
-    spawned process, a built artifact). Use when the bug would live in the seam
-    between units, not inside one.
-  - *Conformance / end-to-end* — an invariant the whole tool must honour, or a
-    contract a future change must not break. Use for the rails, not for every
-    feature.
-- **Mirror the existing suite.** Find the nearest test of the same layer and copy
-  its setup — the test runner already in `package.json` (e.g. vitest/jest), its
-  file location and naming convention, how it builds fixtures and asserts. Don't
-  introduce a second runner or a new fixture style.
-- **Assert behaviour, not implementation.** Test observable inputs→outputs and
-  error cases at the boundary; avoid asserting private internals that refactors
-  will churn. One clear failing assertion beats five brittle ones.
-- **No new framework for one test.** The repo's installed runner and plain
-  assertions cover almost everything. Reach for a new testing dependency only
-  when the existing one demonstrably cannot express the check.
+- **One runner in `package.json`.** Use whichever of vitest or jest the repo
+  already has; don't add a second runner or a new assertion library for what
+  plain `expect` calls already cover.
+- **Await the assertion chain.** `await` or `return` a promise-returning
+  assertion (e.g. `expect(promise).rejects...`) — a test whose promise
+  resolves after the test function returns asserts nothing and passes falsely.
+- **Restore fake timers.** Pair `vi.useFakeTimers()`/`jest.useFakeTimers()`
+  with a restore in teardown, and never mix fake timers with a real
+  `setTimeout` await inside the same test.
+- **Reset mocks between tests.** No shared mutable module state leaking across
+  cases; restore spies/mocks in `afterEach` so test order can't change the
+  outcome.
+- **Temp dir for real-filesystem tests.** Use `fs.mkdtemp` (or the repo's tmp
+  helper) and clean up in teardown; never write into the repo tree or a fixed
+  path on disk.

package/packages/layer2/python-backend-recipes/rules.md

@@ -12,26 +12,22 @@ Layer 1 rules (think before coding, simplicity first, surgical changes,
 goal-driven execution) apply unchanged — this file adds only what is
 Python-specific.
 
-- **Mirror the nearest module.** Before adding a feature, open the closest
-  existing file that already does the same kind of thing (a sibling in the same
-  directory, an adjacent route/handler/service). Copy its structure — imports,
-  class/function layout, error handling, naming — rather than inventing a new
-  shape. The prior art is the template; matching it is verifiable, following
-  prose is not.
-- **One module, one responsibility.** A new `.py` file exports the smallest
-  coherent unit. Keep pure logic separate from I/O (filesystem, network, database)
-  so the logic is testable without mocks — mirror how the existing modules here
-  already split the two.
-- **Use the stdlib and installed deps before adding one.** Python stdlib
-  (`pathlib`, `dataclasses`, `typing`, `json`, `os`) and a dependency already in
-  `pyproject.toml` / `requirements*.txt` cover most needs. A new dependency for
-  what a few lines do is debt; justify it against what is already imported in
-  neighbouring files.
-- **Type hints are the contract.** Annotate inputs and outputs at module
-  boundaries; validate external/untrusted input where it enters (a schema
-  validator if the repo already uses one, e.g. pydantic). Don't re-validate data
-  already typed and checked upstream.
 - **Follow the repo's packaging conventions.** Match the module layout, import
-  style (absolute vs relative), and packaging already in use — don't introduce a
-  second convention. If the project uses `src/` layout, honour it; if it uses
-  flat packages, honour that.
+  style (absolute vs relative), and `src/` vs flat packaging already in use —
+  don't introduce a second convention.
+- **No mutable default arguments.** A `[]` or `{}` default is shared across
+  every call; use a `None` sentinel and build the value inside the function
+  body.
+- **Never swallow exceptions.** No bare `except:`; catch the narrowest
+  exception type and either handle it or re-raise with `raise ... from e` to
+  keep the chain.
+- **Timezone-aware datetimes.** Use `datetime.now(timezone.utc)`, not naive
+  `datetime.now()` — a naive datetime is a latent bug at every boundary it
+  crosses.
+- **No blocking calls inside `async def`.** `requests`, `time.sleep`, and sync
+  DB drivers stall the event loop; use the async equivalent or run it in an
+  executor.
+- **Parameterized queries only.** Pass values as query parameters; never build
+  SQL with f-strings or `%` interpolation.
+- **Context managers for resources.** Open files, connections, and locks with
+  `with` so they close on every path, including exceptions.

package/packages/layer2/python-testing/rules.md

@@ -4,34 +4,28 @@ paths: ["**/*.py", "**/test_*.py", "**/*_test.py"]
 
 ## Python test-layer recipe (Layer 2)
 
-Choosing *where* a test belongs matters as much as writing it. Pick the layer
-that fails for the right reason, and mirror the repo's existing tests of that
-kind for structure and fixtures.
+Choosing *where* a test belongs matters as much as writing it: pick unit,
+integration, or end-to-end by what could actually break — unit for a single
+module's logic, integration for real seams (filesystem, a spawned process, a
+database), end-to-end for an invariant the whole application must honour.
+Then mirror the nearest existing test of that same layer for its location
+(`tests/` or alongside), `test_*.py` naming, and `conftest.py` fixtures rather
+than inventing a new shape.
 
 Layer 1 rules (think before coding, simplicity first, surgical changes,
 goal-driven execution) apply unchanged — this file adds only what is
 Python-testing-specific.
 
-- **Harness before features.** A rule that matters has a test. Write (or extend)
-  the test that pins the new behaviour *before or with* the code that satisfies
-  it — never land logic whose only check is "it looked right". Make the failing
-  test the prompt: it states what is missing.
-- **Pick the layer by what could break.**
-  - *Unit* — pure logic, branches, parsing, a single module's contract. Fast, no
-    I/O, no fixtures. Default here; most logic belongs at this layer.
-  - *Integration* — two or more modules composed, or real I/O (filesystem, a
-    spawned process, a database). Use when the bug would live in the seam between
-    units, not inside one.
-  - *End-to-end* — an invariant the whole application must honour, or a contract
-    a future change must not break. Use for the rails, not for every feature.
-- **Mirror the existing suite.** Find the nearest test of the same layer and copy
-  its setup — `pytest` is the default, its file location (`tests/` or alongside
-  source), naming convention (`test_*.py`), how it builds fixtures (`conftest.py`,
-  `@pytest.fixture`) and asserts. Don't introduce a second runner or a new fixture
-  style.
-- **Assert behaviour, not implementation.** Test observable inputs→outputs and
-  error cases at the boundary; avoid asserting private internals that refactors
-  will churn. One clear failing assertion beats five brittle ones.
-- **No new framework for one test.** The repo's installed runner and plain
-  `assert` statements cover almost everything. Reach for a new testing dependency
-  only when the existing one demonstrably cannot express the check.
+- **Plain `assert` with pytest.** Let pytest's assertion rewriting report the
+  values; don't wrap checks in `unittest` assert methods or add a second
+  runner.
+- **Prefer builtin fixtures.** Reach for `tmp_path`, `monkeypatch`, `capsys`
+  over hand-rolled setup/teardown code — they clean up after themselves.
+- **Parametrize instead of copy-paste.** Use `@pytest.mark.parametrize` for
+  the same body run over many inputs, not duplicated test functions.
+- **Default fixtures to function scope.** Widen to `module`/`session` scope
+  only for an expensive read-only resource; a wider scope shares mutable
+  state across tests that expect isolation.
+- **Assert error paths with `pytest.raises`.** Use
+  `with pytest.raises(Err, match=...)` and assert on the message so the wrong
+  error can't pass silently.

package/packages/layer2/react-components/rules.md

@@ -13,32 +13,37 @@ Layer 1 rules (think before coding, simplicity first, surgical changes,
 goal-driven execution) apply unchanged — this file adds only what is
 React-specific.
 
-- **Mirror the nearest component.** Before adding a component, open the closest
-  existing one that does the same kind of thing (a sibling in the same directory
-  or feature folder). Copy its structure — file layout, how it exports, how it
-  receives and passes props, where state lives — rather than inventing a new
-  shape. The prior art is the template; matching it is verifiable, following
-  prose is not.
 - **Props typed at the boundary.** Every component declares an explicit props
-  interface or type at the top of its file. Accept the minimum props needed; no
-  catch-all `[key: string]: unknown`. Children are explicit when the component
-  uses them.
+  interface or type at the top of its file. Accept the minimum props needed;
+  no catch-all `[key: string]: unknown`.
 - **Composition over configuration.** Prefer a small focused component used in
   multiple arrangements over a large one with a boolean-flag API. When a
-  component's props grow into a switch statement, split into two components that
-  share a common primitive.
-- **Native HTML elements before a component library.** A `<button>`, `<label>`,
-  or `<ul>` is always the first option. Reach for a library component only when
-  the native element demonstrably cannot satisfy the requirement — and then use
-  whichever library the repo already imports, not a new one.
-- **Accessibility is non-negotiable.** Every interactive element is reachable by
-  keyboard and has a visible focus style. Form inputs have associated `<label>`
-  elements (via `htmlFor`/`id` or wrapping). Non-decorative images have
-  descriptive `alt` text. Custom interactive elements carry the correct ARIA
-  `role` and `aria-*` attributes. These are not optional polish; ship them with
-  the component.
-- **Follow the repo's hooks and state conventions.** Use `useState`/`useReducer`
-  at the level state is first needed, and lift only when a sibling needs it.
-  Match whatever custom-hook patterns the repo already uses; don't introduce a
-  new global-state solution for a single component's needs. Mirror how the
-  existing components here manage side effects and data fetching.
+  component's props grow into a switch statement, split into two components
+  that share a common primitive.
+- **Native HTML elements before a component library.** A `<button>`,
+  `<label>`, or `<ul>` is always the first option. Reach for a library
+  component only when the native element demonstrably cannot satisfy the
+  requirement — and then use whichever library the repo already imports.
+- **Accessibility is non-negotiable.** Every interactive element is reachable
+  by keyboard and has a visible focus style. Form inputs have associated
+  `<label>` elements. Non-decorative images have descriptive `alt` text.
+  Custom interactive elements carry the correct ARIA `role` and `aria-*`
+  attributes.
+- **Follow the repo's hooks and state conventions.** Use
+  `useState`/`useReducer` at the level state is first needed, and lift only
+  when a sibling needs it. Don't introduce a new global-state library for a
+  single component's needs.
+- **You might not need an effect.** Derive values during render instead of
+  mirroring props/state into state; an effect is for synchronizing with an
+  external system, not for computing from existing state.
+- **Name the effect callback.** `useEffect(function syncScrollPosition() { … },
+  [deps])` — a named function makes the effect's intent legible and gives it a
+  real name in stack traces and React DevTools instead of an anonymous arrow.
+- **Every subscription effect returns its cleanup.** A listener, timer, or
+  subscription set up in an effect is torn down in the function the effect
+  returns.
+- **`key` is stable identity, not the array index.** Keys must survive
+  reordering; index keys corrupt state on insert or remove.
+- **No `memo`/`useMemo`/`useCallback` by default.** Add memoization only
+  against a measured problem; premature memoization is complexity with no
+  payoff.

package/packages/layer2/react-testing/rules.md

@@ -4,36 +4,27 @@ paths: ["**/*.test.tsx", "**/*.test.jsx", "**/*.spec.tsx", "**/*.spec.jsx"]
 
 ## React test-layer recipe (Layer 2)
 
-Choosing *where* a test belongs matters as much as writing it. Pick the layer
-that fails for the right reason, and mirror the repo's existing tests of that
-kind for structure and setup.
+Choosing *where* a test belongs matters as much as writing it: pick unit
+render, integration, or end-to-end by what could actually break — a single
+component in isolation, two or more components (or a component wired to a
+real hook/context/store), or a full user journey in a real browser reserved
+for critical paths. Then mirror the nearest existing test's RTL setup,
+provider wrapping, runner, and naming rather than inventing a new shape.
 
 Layer 1 rules (think before coding, simplicity first, surgical changes,
 goal-driven execution) apply unchanged — this file adds only what is
 React-testing-specific.
 
-- **Test behaviour, not implementation.** Query by roles and user-visible text
-  (`getByRole`, `getByLabelText`, `getByText`) — not by CSS class, component
-  display name, or internal state. A test that breaks on a classname rename
-  without catching a real regression is noise; a test that catches a missing
-  label is signal.
-- **Pick the layer by what could break.**
-  - *Unit render* — a single component in isolation: does it render the right
-    output for a given set of props, show/hide the right elements, respond to
-    user events? Default here for most component logic.
-  - *Integration* — two or more components composed, or a component wired to a
-    real hook/context/store. Use when the bug would live in the seam between
-    components, not inside one.
-  - *End-to-end* — a full user journey in a real browser. Use only for the
-    critical paths that no unit or integration test can protect; reserve for the
-    rails, not for every feature.
-- **Use React Testing Library.** The repo's RTL setup (`render`, `screen`,
-  `userEvent`, `fireEvent`) covers almost everything. Mirror the nearest
-  existing test file for setup, cleanup, and how it wraps providers. Don't
-  introduce a second render helper or a separate component-testing framework.
-- **Mirror the existing suite.** Copy the nearest test file's structure —
-  runner, file naming, directory location, how it imports the component under
-  test, how it sets up providers or mocks. Consistency beats cleverness.
-- **No new framework for one test.** RTL and the repo's installed runner (e.g.
-  vitest/jest) cover almost every component test need. Reach for a new dependency
-  only when the existing tooling demonstrably cannot express the check.
+- **Query by role, label, or text.** Use `getByRole`, `getByLabelText`,
+  `getByText` — never CSS class, a test id where a role exists, or internal
+  component state. A test that breaks on a classname rename without catching
+  a regression is noise.
+- **Interactions go through `userEvent`.** Await it
+  (`await userEvent.click(...)`); prefer it over `fireEvent`, which skips the
+  events real users trigger.
+- **Await async UI with `findBy*`.** Use `findByRole`/`findByText` (or
+  `waitFor`) for content that appears after an effect; never put a
+  side-effecting call inside `waitFor`.
+- **Wrap renders with the repo's provider helper.** Mirror how the nearest
+  test supplies context, store, or router rather than rendering the bare
+  component.