vanara 0.1.0 → 0.2.0

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,177 @@
+---
+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.

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`.

package/catalog/agents/test-author/references/mocking-and-fixtures.md

@@ -0,0 +1,94 @@
+# Mocking, Fixtures, and Determinism
+
+Tests must be **isolated** (independent of each other) and **deterministic** (same result
+every run). That means controlling everything that crosses a boundary or varies between runs:
+time, randomness, network, filesystem, and shared collaborators.
+
+## Test doubles — know which one you need
+
+| Double | Purpose |
+|---|---|
+| **Dummy** | Filler passed to satisfy a signature; never used. |
+| **Stub** | Returns canned answers to calls made during the test. |
+| **Spy** | A stub that also records how it was called. |
+| **Mock** | A double with pre-set expectations that verifies interactions. |
+| **Fake** | A working but lightweight implementation (in-memory DB, fake clock). |
+
+Reach for the **simplest** double that does the job. Prefer **fakes and stubs** over strict
+mocks: asserting on exact call sequences couples the test to implementation and makes
+refactoring break green tests.
+
+## Mock at the boundary, only the boundary
+
+```ts
+// GOOD: mock the HTTP client (a true external boundary)
+const httpGet = vi.fn().mockResolvedValue({ status: 200, body: { rate: 1.1 } });
+const rate = await fetchExchangeRate(httpGet, 'USD', 'EUR');
+expect(rate).toBe(1.1);
+```
+
+```ts
+// BAD: mocking the function under test leaves nothing real to verify
+const fetchExchangeRate = vi.fn().mockResolvedValue(1.1); // tests the mock, not the code
+```
+
+Over-mocking is a top cause of tests that pass while the system is broken. If a test is
+almost entirely mock setup, you are testing the mock framework. Either widen the unit or move
+the check to an integration test with a real collaborator.
+
+## Controlling time
+
+Wall-clock time is the most common flakiness source. Inject a clock or freeze it:
+
+```ts
+import { vi } from 'vitest';
+
+vi.useFakeTimers();
+vi.setSystemTime(new Date('2026-06-29T12:00:00Z'));
+
+expect(isExpired(token)).toBe(false);
+
+vi.advanceTimersByTime(60_000); // jump 60s deterministically
+expect(isExpired(token)).toBe(true);
+
+vi.useRealTimers(); // always restore
+```
+
+Never assert on `Date.now()` or sleep with real timeouts — that makes tests slow and racy.
+
+## Controlling randomness
+
+Seed the RNG or inject it. A test that depends on `Math.random()` passes-then-fails at random:
+
+```ts
+const rng = () => 0.42;               // injected, deterministic
+expect(pickWinner(players, rng)).toBe('alice');
+```
+
+## Fixtures and factories
+
+- **Factories over literals.** A `makeOrder(overrides)` helper keeps tests readable and
+  resilient — when a required field is added, you change the factory once, not 50 tests.
+- **Build only what the test needs.** Override just the fields relevant to the behavior;
+  let the factory default the rest. This makes the *intent* of each test obvious.
+- **Isolate state.** Reset shared resources (DB rows, in-memory stores, module mocks) in
+  `beforeEach`/`afterEach` so tests can run in any order. Order-dependent tests are a bug.
+
+```ts
+function makeOrder(overrides = {}) {
+  return { id: 'ord_1', status: 'open', total: 100, createdAt: new Date(0), ...overrides };
+}
+
+it('marks a paid order as fulfilled', () => {
+  const order = makeOrder({ status: 'paid' }); // only the relevant field is set
+  expect(fulfill(order).status).toBe('fulfilled');
+});
+```
+
+## Determinism checklist
+
+- [ ] No real network, filesystem, or DB in unit tests (use fakes/stubs).
+- [ ] Time and randomness are frozen or injected.
+- [ ] No shared mutable state leaks between tests; setup/teardown resets it.
+- [ ] All async work is awaited — no dangling promises or unhandled timers.
+- [ ] The suite passes when run in a randomized order.

package/catalog/agents/test-author/references/test-types-and-pyramid.md

@@ -0,0 +1,60 @@
+# Test Types and the Test Pyramid
+
+Not all tests are equal. Choosing the right *level* for a given behavior is the difference
+between a suite that gives fast, reliable signal and one that is slow, flaky, and ignored.
+
+## The pyramid
+
+```
+        /\        E2E / UI        few, slow, high-confidence, brittle
+       /  \
+      /----\      Integration     some, medium speed, real collaborators
+     /      \
+    /--------\    Unit             many, fast, isolated, cheap
+```
+
+Push the bulk of your assertions **down** to the unit level where they are fast and stable.
+Use the higher levels sparingly to prove the pieces wire together, not to re-test logic that
+unit tests already cover. An inverted pyramid (mostly E2E) is slow and flaky.
+
+## Unit tests
+
+- **Scope:** one function, method, or class in isolation. Collaborators that cross a process
+  or I/O boundary are replaced with doubles.
+- **Cost:** milliseconds. Run thousands on every save.
+- **Owns:** business logic, pure functions, edge cases, error branches, algorithms.
+- **Rule of thumb:** if a behavior can be tested at the unit level, test it there.
+
+## Integration tests
+
+- **Scope:** several real units working together, or one unit against a real adjacent
+  dependency (a database, an in-memory queue, a local HTTP server).
+- **Cost:** tens to hundreds of milliseconds. Often need setup/teardown.
+- **Owns:** the seams — ORM queries against a real schema, repository wiring, serialization,
+  framework request/response handling, transaction behavior.
+- **Avoid:** re-testing branch logic here that a unit test already covers; keep these about
+  the *wiring*, not the *rules*.
+
+## End-to-end (E2E) tests
+
+- **Scope:** the whole system through its real entry point — a browser, a CLI, a public API.
+- **Cost:** seconds. Slow, infrastructure-heavy, the most prone to flakiness.
+- **Owns:** a handful of critical user journeys (sign up, checkout, the money path).
+- **Hand off:** browser-driven E2E belongs to the **e2e-playwright** skill, not this agent.
+
+## What goes where — a decision guide
+
+| Question | Level |
+|---|---|
+| Does `applyDiscount(49.99, 10)` round correctly? | Unit |
+| Does an invalid percentage throw `RangeError`? | Unit |
+| Does the repository persist and re-read an order from Postgres? | Integration |
+| Does `POST /orders` return `201` with a `Location` header? | Integration |
+| Can a user add to cart and complete checkout in the browser? | E2E |
+
+## Coverage as a signal, not a goal
+
+The 80% target is a floor that flags untested regions, not a trophy. 100% line coverage with
+assertion-free tests proves nothing. Chase **branch and behavior** coverage — every error
+path and boundary — over raw line percentage. Use `scripts/check-coverage.mjs` to gate the
+floor in CI, and read the uncovered lines to find the cases you forgot.