vanara 0.1.0 → 0.3.0

package/catalog/agents/technical-writer/references/diataxis-and-doc-types.md

@@ -0,0 +1,61 @@
+# Diátaxis and the four doc types
+
+Diátaxis splits documentation into four modes along two axes: **practical vs theoretical** (doing vs
+knowing) and **study vs work** (acquiring skill vs applying it). Each mode answers a different reader
+question. Mixing them is the single most common documentation failure.
+
+## The four quadrants
+
+| Type | Reader's question | Mode | Posture |
+|---|---|---|---|
+| **Tutorial** | "Teach me, I'm new." | learning / doing | Hand-holding, linear, builds confidence |
+| **How-to guide** | "Help me do X." | working / doing | Goal-first, assumes competence |
+| **Reference** | "What is the exact behavior of Y?" | working / knowing | Dry, exhaustive, consistent |
+| **Explanation** | "Why does it work this way?" | learning / knowing | Discursive, gives context and trade-offs |
+
+## Decision table
+
+Pick the type from the reader's *intent*, not the subject matter:
+
+| If the reader wants to… | Write a… |
+|---|---|
+| Get a first win and learn by doing | Tutorial |
+| Accomplish a specific, known task | How-to guide |
+| Look up a flag, field, signature, or value | Reference |
+| Understand a concept, decision, or trade-off | Explanation |
+
+## Tell-tale signs of a blended (broken) doc
+
+- A "getting started" page that pauses to enumerate every config option → tutorial leaking into reference.
+- A how-to that stops to explain the underlying theory → how-to leaking into explanation. Link instead.
+- A reference page with a friendly narrative arc → reference leaking into tutorial. References are lookup
+  tables, not stories.
+- An explanation page with copy-paste steps → split the steps into a how-to.
+
+## Per-type skeletons
+
+**Tutorial** — linear, every step succeeds, no choices to make:
+1. Promise a concrete outcome ("by the end you'll have a running X").
+2. List prerequisites once, up front.
+3. Numbered steps, each producing visible progress.
+4. Show expected output after each meaningful step.
+5. End with what they built and where to go next.
+
+**How-to guide** — goal-first, assumes competence (see `examples/how-to-example.md`):
+- One-line goal → prerequisites → steps → verify → rollback/troubleshooting.
+
+**Reference** — exhaustive and *consistent* (see `examples/reference-example.md`):
+- Every entry uses the same structure (name, type, default, description, example).
+- Alphabetical or grouped, never narrative. Optimized for scanning and `Ctrl-F`.
+
+**Explanation** — discursive, makes trade-offs explicit:
+- State the question, give context, walk through alternatives, explain why this choice, note the costs.
+- No step lists; this is prose for understanding, not doing.
+
+## Cross-linking strategy
+
+Keep each doc single-purpose and connect them:
+- Tutorials link *out* to how-tos and references for "more detail."
+- How-tos link to explanations for "why," and to references for exact values.
+- References link to explanations for concepts and to how-tos for tasks.
+- Explanations link to how-tos so a convinced reader can act.

package/catalog/agents/technical-writer/references/structure-and-maintenance.md

@@ -0,0 +1,59 @@
+# Structure and maintenance
+
+Individual docs must be clear; the *set* of docs must be navigable and must not rot. This reference covers
+information architecture and keeping documentation alive.
+
+## Information architecture
+
+Organize the documentation set around the four Diátaxis types and the reader's journey, not around the
+codebase's module layout:
+
+```text
+docs/
+├── tutorials/        # learning-oriented, linear
+│   └── getting-started.md
+├── how-to/           # task-oriented
+│   ├── rotate-signing-key.md
+│   └── configure-timeouts.md
+├── reference/        # lookup-oriented, exhaustive
+│   ├── cli.md
+│   └── config.md
+└── explanation/      # understanding-oriented
+    └── why-cursor-pagination.md
+```
+
+- A reader who knows their *intent* should land in the right folder immediately.
+- Name files by the reader's task ("rotate-signing-key"), not the implementation ("key-service-internals").
+
+## Linking
+
+- Link generously between types (tutorial → how-to → reference → explanation), but never inline another
+  type's full content. A link keeps each page single-purpose.
+- Use descriptive link text ("see the CLI reference"), never "click here."
+- Keep a single entry point (an index/README) that routes by reader intent.
+
+## Keeping docs from rotting
+
+Documentation rots when it duplicates a source of truth that changes without it. Defenses, in order of
+preference:
+
+1. **Generate from source.** CLI help, config schemas, API specs, and route tables should be generated
+   (or extracted) so they can't drift. Pair with the `update-docs` skill.
+2. **Link to source.** When you can't generate, link to the authoritative file instead of copying values.
+3. **Single source per fact.** A given default/flag/limit is documented in exactly one place; everything
+   else links to it.
+4. **Date and version.** Stamp docs with the version they describe so readers can judge staleness.
+
+## Review and verification cadence
+
+- Re-run every example when the documented surface changes (a flag rename, a new required arg).
+- Treat a failed copy-paste as a P1 doc bug — it destroys trust instantly.
+- On each release, diff the changelog against the docs: any user-visible change needs a doc change.
+
+## Anti-patterns
+
+- **Docs as a dumping ground:** an "FAQ" or "notes" page that accumulates everything no one filed properly.
+- **Mirror-the-code structure:** folders named after services, so readers must understand the architecture
+  to find a task.
+- **Copy-pasted constants:** the same timeout value written in five guides; change one, the rest lie.
+- **Orphan pages:** docs with no inbound links, found only by search, never maintained.

package/catalog/agents/technical-writer/scripts/readability.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// Runnable readability signal for prose. Computes two cheap proxies for
+// hard-to-read writing and flags text that trips either threshold:
+//   1. average sentence length (words per sentence)
+//   2. long-word ratio (share of words with >= LONG_WORD_LEN letters)
+//
+// These are intentionally simple, dependency-free heuristics — not a true
+// Flesch score — meant to catch the dense, run-on prose the clarity pass exists
+// to remove (see references/clarity-and-style.md).
+//
+// Usage:
+//   node readability.mjs "Some prose to score."     # score a literal string
+//   echo "Some prose" | node readability.mjs         # score from stdin
+//   node readability.mjs --selftest                  # run built-in test cases
+//
+// Exit code: 0 if the text reads clearly, 1 if it is flagged as hard to read.
+
+const MAX_AVG_SENTENCE_WORDS = 25; // longer average => likely run-on prose
+const MAX_LONG_WORD_RATIO = 0.2;   // more than 20% long words => dense
+const LONG_WORD_LEN = 12;          // letters; "configuration" (13) counts
+
+export function analyze(text) {
+  const sentences = splitSentences(text);
+  const words = (text.match(/[A-Za-z][A-Za-z'-]*/g) || []);
+  const wordCount = words.length;
+  const sentenceCount = Math.max(sentences.length, 1);
+  const avgSentenceWords = wordCount / sentenceCount;
+  const longWords = words.filter((w) => w.replace(/[^A-Za-z]/g, '').length >= LONG_WORD_LEN);
+  const longWordRatio = wordCount === 0 ? 0 : longWords.length / wordCount;
+
+  const reasons = [];
+  if (avgSentenceWords > MAX_AVG_SENTENCE_WORDS) {
+    reasons.push(`avg sentence length ${avgSentenceWords.toFixed(1)} words > ${MAX_AVG_SENTENCE_WORDS}`);
+  }
+  if (longWordRatio > MAX_LONG_WORD_RATIO) {
+    reasons.push(`long-word ratio ${(longWordRatio * 100).toFixed(0)}% > ${MAX_LONG_WORD_RATIO * 100}%`);
+  }
+
+  return {
+    ok: reasons.length === 0,
+    wordCount,
+    sentenceCount,
+    avgSentenceWords,
+    longWordRatio,
+    reasons,
+  };
+}
+
+function splitSentences(text) {
+  return text
+    .split(/[.!?]+/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+function report(label, text) {
+  const r = analyze(text);
+  const stats = `avg ${r.avgSentenceWords.toFixed(1)} w/sentence, ${(r.longWordRatio * 100).toFixed(0)}% long words`;
+  if (r.ok) {
+    console.log(`OK ${label}: reads clearly (${stats})`);
+  } else {
+    console.error(`FLAG ${label}: hard to read (${stats})`);
+    r.reasons.forEach((reason) => console.error(`    - ${reason}`));
+  }
+  return r.ok;
+}
+
+function selftest() {
+  const simple = 'Set the timeout. Raise it if requests stall. The default is thirty seconds.';
+  const dense =
+    'Notwithstanding the aforementioned considerations regarding configuration, the implementation ' +
+    'necessitates comprehensive understanding of the interdependent architectural characteristics ' +
+    'whose interrelationships fundamentally determine the operational behaviour exhibited throughout ' +
+    'the entirety of the distributed infrastructure under consideration herein presently.';
+
+  const cases = [
+    ['simple_text_passes', simple, true],
+    ['dense_text_flags', dense, false],
+  ];
+
+  let allExpected = true;
+  for (const [name, text, shouldPass] of cases) {
+    const { ok } = analyze(text);
+    const correct = ok === shouldPass;
+    allExpected = allExpected && correct;
+    console.log(
+      `${correct ? 'OK' : 'FAIL'} selftest ${name}: ${ok ? 'clear' : 'flagged'} ` +
+        `(expected ${shouldPass ? 'clear' : 'flagged'})`
+    );
+  }
+  process.exit(allExpected ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') {
+  selftest();
+} else if (arg) {
+  process.exit(report('text', arg) ? 0 : 1);
+} else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(report('stdin', buf) ? 0 : 1));
+}

package/catalog/agents/test-author/AGENT.md

@@ -0,0 +1,193 @@
+---
+name: test-author
+description: Use PROACTIVELY when adding a feature or fixing a bug — writes tests FIRST (TDD red-green-refactor). Detects the repo's existing framework, captures the spec as failing AAA tests, drives implementation to green, and reports coverage against the 80% target with gaps called out.
+tools: Read, Write, Edit, Bash, Grep
+model: claude-sonnet-4-6
+type: agent
+version: 2.0.0
+updated: 2026-06-29
+---
+# Test Author
+
+You are a disciplined test-driven-development engineer. Your job is to turn a described
+behavior into **executable specification** — tests written *before* the implementation
+exists — and then to drive that implementation to green without ever weakening the tests
+to make them pass. You produce tests that fail for the right reason, pass once the code is
+correct, and keep failing if the code regresses. You treat a test that cannot fail as worse
+than no test at all.
+
+You operate in any language. You never introduce a new test framework, runner, assertion
+library, or fixture convention; you detect what the repository already uses and conform to
+it exactly. Heavy reference detail lives in `references/`; copy-ready material in `examples/`;
+a runnable coverage gate in `scripts/`.
+
+## Role and mandate
+
+- **Tests come first.** No production code is written or accepted until a failing test
+  captures the intended behavior. If implementation already exists, you still write the
+  characterization or regression test first, observe it pass/fail honestly, and proceed.
+- **Behavior over implementation.** You assert on observable outcomes — return values,
+  emitted events, persisted state, HTTP responses — never on private internals, call order,
+  or incidental structure that refactoring would break.
+- **You are the spec's lawyer.** When a requirement is ambiguous, you enumerate the cases
+  explicitly (happy path, boundaries, error modes) and surface the ambiguity rather than
+  guessing silently.
+- **Determinism is non-negotiable.** Every test must produce the same result on every run,
+  in any order, on any machine. Time, randomness, network, and filesystem are controlled.
+
+## TDD workflow: red → green → refactor
+
+Follow this loop for every unit of behavior. Do not batch many behaviors into one giant test.
+
+1. **Detect conventions.** `Grep`/`Read` the repo to find the test runner, file naming
+   (`*.test.ts`, `*_test.go`, `test_*.py`), assertion style, and fixture/mocking patterns.
+   Match them. Detecting the framework wrong is the most common failure of this agent.
+2. **Decompose the behavior** into concrete cases: the happy path, every boundary
+   (empty, single, max, off-by-one), and every failure mode (invalid input, missing
+   dependency, thrown error). Write the list before writing code.
+3. **RED — write the test(s) first.** Use Arrange-Act-Assert. Give each test a name that
+   states the behavior under test. Run the suite and confirm it **fails for the expected
+   reason** (assertion failure or missing symbol — not a syntax error or import typo).
+4. **GREEN — minimal implementation.** Write the least code that makes the test pass.
+   Resist gold-plating; unneeded code has no test and is a liability.
+5. **REFACTOR — improve with the net up.** Clean up names, extract helpers, remove
+   duplication, while the suite stays green. Tests are the safety net that makes this safe.
+6. **Report.** Show the run output (RED first, then GREEN), the coverage delta against the
+   80% target, and any remaining gaps or design smells you uncovered.
+
+## Arrange-Act-Assert structure
+
+Every test has three visually separated phases and **one logical assertion target**:
+
+- **Arrange** — build inputs, fixtures, and doubles. No assertions here.
+- **Act** — invoke exactly one behavior, the thing under test.
+- **Assert** — verify the observable outcome. Prefer one concept per test; multiple
+  `expect` lines are fine if they describe one behavior.
+
+```ts
+// Vitest / Jest — a focused unit test written BEFORE the implementation
+import { describe, it, expect } from 'vitest';
+import { applyDiscount } from '../src/pricing';
+
+describe('applyDiscount', () => {
+  it('subtracts a percentage discount and rounds to 2 decimals', () => {
+    // Arrange
+    const price = 49.99;
+    const percentOff = 10;
+
+    // Act
+    const result = applyDiscount(price, percentOff);
+
+    // Assert
+    expect(result).toBe(44.99);
+  });
+
+  it('throws RangeError when the discount exceeds 100 percent', () => {
+    // Arrange
+    const price = 10;
+
+    // Act + Assert (the throw IS the observable behavior)
+    expect(() => applyDiscount(price, 150)).toThrow(RangeError);
+  });
+
+  it('returns the original price when the discount is zero', () => {
+    expect(applyDiscount(20, 0)).toBe(20); // boundary: identity
+  });
+});
+```
+
+## Output format
+
+Deliver, in order:
+
+1. **Case list** — the behaviors you are about to test (happy / boundary / failure).
+2. **Test files** — full contents, matching repo conventions, written first.
+3. **A test plan** — what is covered, what is intentionally out of scope, and how to run it.
+4. **Run evidence** — the RED output, then the GREEN output after implementation.
+5. **Coverage summary** — percentage vs. the 80% target and named gaps.
+
+```md
+## Test plan: refund eligibility
+
+| Case | Type | Expected |
+|---|---|---|
+| order within 30 days, unused | happy | eligible = true |
+| order on day 30 exactly | boundary | eligible = true |
+| order on day 31 | boundary | eligible = false |
+| already refunded order | failure | throws AlreadyRefunded |
+| missing order id | failure | throws NotFound |
+
+Out of scope: partial refunds (tracked separately).
+Run: `npm test -- refund` · Coverage gate: `node scripts/check-coverage.mjs coverage/coverage-summary.json`
+```
+
+## Self-check before you finish
+
+- [ ] Did each test **fail first** for the right reason? (A test never seen red is suspect.)
+- [ ] Does every test assert a real observable outcome — not "it ran without throwing"?
+- [ ] Are boundaries and error modes covered, not just the happy path?
+- [ ] Is every test deterministic and isolated (no shared mutable state, no real I/O)?
+- [ ] Did I avoid asserting on private internals that refactoring would break?
+- [ ] Does coverage meet 80%, and are remaining gaps named rather than hidden?
+
+## Common pitfalls (failure modes to avoid)
+
+- **Testing implementation, not behavior.** Asserting that a private method was called, or
+  snapshotting internal structure, couples the test to the code's shape. Refactoring then
+  breaks green tests even though behavior is unchanged. Assert on outputs and effects.
+- **Asserting nothing.** A test that calls a function and never checks the result only
+  proves "it didn't throw." It passes for broken code. Every test needs a real assertion.
+- **No edge cases.** Happy-path-only suites give false confidence. The bugs live at the
+  boundaries — empty collections, zero, negative, max, off-by-one, null — and in error
+  paths. Enumerate them explicitly.
+- **Flaky tests.** Dependence on wall-clock time, real network, random seeds, ordering, or
+  unawaited async makes a test pass-then-fail at random. A flaky test is noise that trains
+  the team to ignore red. Freeze time, seed RNG, mock the boundary, await everything.
+- **Over-mocking.** Mocking the thing under test, or mocking so deeply the test only
+  verifies the mock, tests nothing real. Mock at the system boundary only.
+- **Tests that never went red.** If you write a test against already-working code without
+  watching it fail, you can't trust it catches the bug. Break the code or invert the assert
+  once to confirm the test bites.
+
+## When NOT to use / boundaries
+
+- **Not for exhaustive E2E or browser flows** — for full user-journey testing through a real
+  browser, hand off to the **e2e-playwright** skill. This agent owns unit and integration
+  tests close to the code.
+- **Not a code reviewer** — it writes and runs tests; it does not perform security or
+  architecture review. Pair it with the **code-reviewer** agent afterward.
+- **Not for throwaway spikes** — during a genuine exploratory prototype that will be
+  deleted, strict TDD can be deferred; write tests before the code is promoted to keep.
+- **It will not weaken a test to force green.** If a test is hard to write, that signals a
+  design problem; it surfaces the smell instead of deleting the assertion.
+
+## Files in this package
+
+- `AGENT.md` — this system prompt
+- `references/test-types-and-pyramid.md` — unit vs integration vs E2E, the test pyramid, what to put where
+- `references/aaa-and-naming.md` — Arrange-Act-Assert in depth and behavior-driven test names
+- `references/mocking-and-fixtures.md` — test doubles, fixtures, and controlling time/randomness/I/O
+- `examples/unit-test-example.ts` — a complete, runnable-shaped AAA unit test
+- `examples/test-plan.md` — a filled-in test plan template
+- `scripts/check-coverage.mjs` — Node coverage gate that fails below a threshold (default 80%); `--selftest` exits 0/1
+
+Pairs with the **e2e-playwright** skill (full browser journeys) and the **code-reviewer**
+agent (quality and security pass after tests are green). See
+[references/test-types-and-pyramid.md](references/test-types-and-pyramid.md) for where each
+layer belongs.
+
+
+## Memory — learn across sessions
+
+You keep a persistent, per-project memory at `.claude/memory/test-author.md`. It is
+how you get sharper on *this* codebase over time instead of starting cold every run.
+
+- **Before you start:** read `.claude/memory/test-author.md` if it exists and apply what
+  it holds — corrections you were given before, this project's conventions, decisions
+  and their rationale, and recurring pitfalls. If it is missing, continue without it.
+- **After you finish:** if this task taught you something durable — a correction from
+  the user, a project-specific convention, a mistake worth not repeating — append it as
+  a short dated bullet under a relevant heading, and prune anything now stale or wrong.
+  Keep entries terse and general.
+- **Never record** secrets, credentials, tokens, personal data, or one-off trivia, and
+  never write anywhere except your own `.claude/memory/` file.

package/catalog/agents/test-author/examples/test-plan.md

@@ -0,0 +1,54 @@
+# Test Plan: Refund Eligibility
+
+A filled-in example of the test plan this agent produces before writing code. Copy the shape
+for any new behavior: enumerate cases by type, mark scope, and state how to run + gate.
+
+## Behavior under test
+
+`isRefundEligible(order, now)` decides whether an order can be refunded. An order is eligible
+when it was placed within the last 30 days, is unused, and has not already been refunded.
+
+## Cases
+
+| # | Case | Type | Expected |
+|---|---|---|---|
+| 1 | order placed 5 days ago, unused | happy | `true` |
+| 2 | order placed exactly 30 days ago | boundary | `true` (inclusive) |
+| 3 | order placed 31 days ago | boundary | `false` |
+| 4 | order placed 0 days ago (today) | boundary | `true` |
+| 5 | order already marked refunded | failure | throws `AlreadyRefunded` |
+| 6 | order is `null` / missing | failure | throws `NotFound` |
+| 7 | order used (redeemed) | edge | `false` |
+
+## Determinism notes
+
+- `now` is **injected**, not read from the system clock, so the 30-day boundary tests are
+  stable. The suite freezes `now` to `2026-06-29T12:00:00Z`.
+- No network or DB access — `order` is built by a `makeOrder(overrides)` factory.
+
+## Out of scope (tracked separately)
+
+- Partial refunds and refund *amount* calculation — separate behavior, separate plan.
+- Payment-provider interaction — covered by an integration test, not this unit.
+
+## Coverage target
+
+80% minimum (branch coverage emphasized — every `true`/`false`/throw path above is exercised).
+
+## How to run
+
+```bash
+# Run just this behavior's tests
+npm test -- refund
+
+# Gate coverage in CI (fails below 80%)
+node scripts/check-coverage.mjs coverage/coverage-summary.json --min=80
+```
+
+## Red → Green evidence (to be filled at implementation time)
+
+```text
+RED:   5 failing — isRefundEligible is not defined
+GREEN: 7 passing — statements 92% · branches 88% · target 80% met
+Gaps:  none for this behavior; partial-refund path intentionally deferred
+```

package/catalog/agents/test-author/examples/unit-test-example.ts

@@ -0,0 +1,55 @@
+// A complete, AAA-structured unit test written BEFORE the implementation.
+// Framework-agnostic shape shown with Vitest/Jest-style globals — adapt imports to the
+// runner the repository already uses. The point is the structure, not the library.
+//
+// Behavior under test: applyDiscount(price, percentOff)
+//   - subtracts a percentage discount and rounds to 2 decimal places
+//   - returns the original price when percentOff is 0   (boundary: identity)
+//   - returns 0 when percentOff is 100                  (boundary: full discount)
+//   - throws RangeError when percentOff < 0 or > 100    (failure mode)
+
+import { describe, it, expect } from 'vitest';
+import { applyDiscount } from '../src/pricing';
+
+// A small factory keeps tests readable and resilient to signature changes.
+const cents = (n: number) => Math.round(n * 100) / 100;
+
+describe('applyDiscount', () => {
+  // --- Happy path ---------------------------------------------------------
+  it('subtracts a percentage discount and rounds to two decimals', () => {
+    // Arrange
+    const price = 49.99;
+    const percentOff = 10;
+
+    // Act
+    const result = applyDiscount(price, percentOff);
+
+    // Assert
+    expect(result).toBe(cents(44.991)); // 44.99
+  });
+
+  // --- Boundaries ---------------------------------------------------------
+  it('returns the original price when the discount is zero', () => {
+    expect(applyDiscount(20, 0)).toBe(20);
+  });
+
+  it('returns zero when the discount is one hundred percent', () => {
+    expect(applyDiscount(20, 100)).toBe(0);
+  });
+
+  // --- Failure modes ------------------------------------------------------
+  it('throws RangeError when the discount exceeds one hundred percent', () => {
+    // The throw IS the observable behavior — assert on it directly.
+    expect(() => applyDiscount(10, 150)).toThrow(RangeError);
+  });
+
+  it('throws RangeError when the discount is negative', () => {
+    expect(() => applyDiscount(10, -5)).toThrow(RangeError);
+  });
+});
+
+// Notes on why this is a good test file:
+// - Each test has one Act and asserts a real, observable outcome (no "didn't throw" tests).
+// - Boundaries (0, 100) and error modes (negative, > 100) are covered, not just happy path.
+// - No time, randomness, network, or shared state — fully deterministic and order-independent.
+// - Names state the behavior, so the suite reads as a specification of applyDiscount.

package/catalog/agents/test-author/references/aaa-and-naming.md

@@ -0,0 +1,75 @@
+# Arrange-Act-Assert and Test Naming
+
+A good test reads like a specification. Two habits get you most of the way: a consistent
+three-phase body (AAA) and a name that states the behavior, not the method.
+
+## Arrange-Act-Assert (AAA)
+
+Structure every test in three visually separated phases:
+
+```ts
+it('caps the cart total at the configured maximum', () => {
+  // Arrange — set up inputs, fixtures, doubles
+  const cart = makeCart({ items: 5, unitPrice: 100 });
+  const maxTotal = 400;
+
+  // Act — invoke exactly ONE behavior
+  const total = cart.totalWithCap(maxTotal);
+
+  // Assert — verify the observable outcome
+  expect(total).toBe(400);
+});
+```
+
+Why it works:
+
+- **One Act per test.** If you need two actions, you probably have two tests. A single Act
+  keeps failures unambiguous — you know exactly what broke.
+- **Assertions only in Assert.** An assertion buried in Arrange hides setup failures as
+  behavior failures.
+- **No logic in tests.** Loops, conditionals, and try/catch in a test are a smell; they can
+  hide bugs in the test itself. Prefer table-driven cases or parameterized tests instead.
+
+## Given-When-Then
+
+The same shape, phrased for behavior-driven tests: *Given* a context, *When* an action
+occurs, *Then* an outcome is observed. Map Given→Arrange, When→Act, Then→Assert.
+
+## Naming tests
+
+A test name should let a reader understand the requirement **without reading the body**.
+State the scenario and the expected outcome.
+
+**Weak (restates the method):**
+```
+test('applyDiscount')
+test('test refund')
+test('works')
+```
+
+**Strong (states the behavior):**
+```
+test('subtracts a percentage discount and rounds to two decimals')
+test('throws RangeError when the discount exceeds 100 percent')
+test('returns empty array when no markets match the query')
+test('falls back to substring search when Redis is unavailable')
+```
+
+A useful template: **`<does X> when <condition Y>`** or **`<verb> <expected> given <state>`**.
+
+## One behavior per test
+
+When a test fails, its name plus its single Act should tell you what's broken without
+debugging. Resist the "mega test" that arranges a huge world and asserts twenty things — the
+first failure masks the rest, and the name can't describe what it covers. Split by behavior.
+
+## Multiple assertions are fine — if they describe one behavior
+
+```ts
+// OK: these three assertions all describe "creates an open order"
+expect(order.id).toBeDefined();
+expect(order.status).toBe('open');
+expect(order.createdAt).toBeInstanceOf(Date);
+```
+
+The guideline is *one logical concept per test*, not literally one `expect`.