gennady 0.6.0 → 0.7.0

package/dist/ai/directives/testing/common.xml

@@ -0,0 +1,234 @@
+<TestingCommon keywords="testing, ai_first_tests, contract_testing, case_flow, phase_anchors, unified_context, factory, mocks, bdd_mapping, snapshots, isolation" type="testing-rules" ver="1.0">
+  <Mission>
+    Shared testing core for every runner-specific directive (`testing/node-test`, `testing/vitest-rules`, future Jest/Pytest/Go directives). Defines: what a test must protect, how the case body is structured for the next agent to read, how dependencies are isolated, how BDD scenarios in a ticket map to `it` cases.
+
+    Runner-specific directives reference this file under `Inherited_Baseline` and only state the differences (assertion API, mocking surface, lifecycle vocabulary, snapshot location).
+
+    **A test is executable learning context.** Title, structural anchors, intent comments must reveal what is under protection, what must not regress, where the scenario is fragile. Tests are CODE — they obey the same machine-first annotation language as production code (`coding/typescript-rules`). The repo reads as one system.
+  </Mission>
+
+  <Belief_State>
+
+    <!-- ── Contract boundary ──────────────────────────────────────────────── -->
+
+    <Axiom id="AX_CONTRACT_OVER_IMPLEMENTATION">
+      Test the public contract; never inspect protected/private state of the SUT. A refactor that preserves behavior must not break the test suite. Applies uniformly to:
+      - state-returning methods → assert returned value;
+      - emitters / subscriptions → assert emitted event payload via a public listener; do NOT inspect listener arrays or registration mechanics;
+      - cancellation APIs → assert observable signal (`aborted`, `reason`, downstream reaction); do NOT inspect controller wiring;
+      - lifecycle hooks → assert the side effect at the public boundary, not internal counters.
+
+      Tests bound to internals become an obligation for every refactor and lose the ability to catch real regressions.
+    </Axiom>
+
+    <Axiom id="AX_ISOLATION_THROUGH_PUBLIC_BOUNDARY">
+      Isolate the SUT by stubbing its external dependencies and exercising it through its public surface. Determinism comes from controlling inputs at the boundary, not from reaching past the boundary to set internal state.
+    </Axiom>
+
+    <!-- ── Case flow + anchors ────────────────────────────────────────────── -->
+
+    <Axiom id="AX_CASE_FLOW">
+      Canonical case pattern: `SETUP → TRIGGER → OBSERVE → ASSERT` (`CLEANUP` when needed). Keep only the phases that add clarity. `AAA` is a useful short form — not a law. Forced empty phases are noise; merging obvious phases (`TRIGGER_AND_ASSERT` around `assert.rejects` / `rejects.toThrow`) is allowed and preferred over a fake split.
+
+      TRIGGER and ASSERT are mandatory in every non-trivial case (trigger crosses the contract boundary; assert verifies it).
+    </Axiom>
+
+    <Axiom id="AX_PHASE_ANCHORS">
+      **Wrap each present phase that carries ≥2 statements OR encodes local policy** (retry, fallback, aggregation, fixture build) in paired anchors:
+
+      ```
+      // #region START_[CASE]_[PHASE]_[INTENT]
+      ...phase body...
+      // #endregion END_[CASE]_[PHASE]_[INTENT]
+      ```
+
+      PHASE ∈ {`SETUP`, `TRIGGER`, `OBSERVE`, `ASSERT`, `CLEANUP`}.
+
+      **Skip anchors when the phase is a single statement with no hidden policy.** A one-line `await assert.rejects(...)` covering both TRIGGER and ASSERT does NOT need an anchor — title + the call already expose intent. Anchors around trivial one-liners are ritual noise that erodes the signal of anchors on truly non-trivial phases.
+
+      Anchors are machine grammar for refactoring: they let the next agent cut and replace phases by pairs without an AST.
+    </Axiom>
+
+    <Axiom id="AX_TEST_ANCHOR_NAMING">
+      Anchor names describe intent, not raw syntax. `START_FETCH_ITEM_OBSERVE_RETRY_SUMMARY` — yes; `START_FETCH_ITEM_ASSERT_2` — no. Uppercase, high-signal tokens. CASE = short scenario id; INTENT = what this phase is about.
+    </Axiom>
+
+    <!-- ── Brief ──────────────────────────────────────────────────────────── -->
+
+    <Axiom id="AX_IT_OPENING_BRIEF">
+      Open the `it` body with a 1–3 line brief **when the title alone does not convey invariant / failure mode / non-goal**. Brief never duplicates the title — it adds what the title cannot.
+
+      Closed vocabulary (machine-first payload): `purpose`, `consumer`, `invariant`, `side effect`, `failure mode`, `non-goal`, `contract`, `observation focus`.
+
+      Skip the brief on cases where title + direct input + a single assertion already expose the scenario. A brief on a self-evident case is noise that weakens the signal of briefs on hard cases.
+    </Axiom>
+
+    <!-- ── Assertion shape ────────────────────────────────────────────────── -->
+
+    <Axiom id="AX_DEFAULT_DIRECT_ASSERTION_PROTOCOL">
+      Start with the simplest direct assertion on the real contract surface. Introduce an OBSERVE phase with an aggregated `actual` object only when a single rich diff genuinely beats several isolated assertions (composite contract: returned value + emitted log + side-effect summary). Do NOT fragment one coherent shape into many tiny assertions; do NOT force aggregation when orthogonal observations read more clearly standalone. The criterion is **diagnostic clarity of the failure report**.
+
+      Concrete assertion API (`strictEqual` / `toBe`, `deepStrictEqual` / `toEqual`, `throws` / `toThrow`, etc.) lives in the runner-specific directive.
+    </Axiom>
+
+    <Axiom id="AX_PARTIAL_STRING_VIA_MATCH">
+      Partial string / error-message checks go through regex match (`assert.match` / `toMatch`), never through boolean fold (`includes`, `toContain`). Match shows the real value in the failure output; boolean fold loses context.
+    </Axiom>
+
+    <Axiom id="AX_RESULT_UNWRAP_ON_SUCCESS_PATHS">
+      If the SUT returns `Result<T>`, use `unwrap()` / `unwrapSync()` on success paths to collapse «check success + extract value» into one call. The assert then focuses solely on the business shape.
+    </Axiom>
+
+    <Axiom id="AX_FOCUSED_ERROR_ASSERTIONS">
+      Error cases use a focused set: domain error class via `instanceof` AND a stable message fragment via regex match. Do NOT strict-equal a dynamic error message (correlation ids, timestamps) — flaky failures with no diagnostic signal.
+    </Axiom>
+
+    <!-- ── Unified context + factory ──────────────────────────────────────── -->
+
+    <Axiom id="AX_ONE_UNIFIED_CONTEXT_PER_FILE">
+      **Each test file defines exactly ONE context shape** — a single `XxxContext` type and a single factory `createXxxContext(overrides?)` (or, when teardown required, a single lifecycle context object built in `beforeEach` and disposed in `afterEach`).
+
+      Every case in the file consumes this same context. New requirements extend the existing shape and factory through optional fields and overrides; they do NOT spawn parallel `createOrderContextHappy` / `createOrderContextFailing` factories or sibling `let`s in the describe.
+
+      A nested `describe` MAY introduce its own narrower context only when its sub-group has lifecycle needs that cannot be expressed as overrides on the parent; the exception must be obvious from the diff.
+
+      Why: test files stay small and predictable — one shape applies to every case, new tests almost always add an override, marginal cost per case stays flat.
+    </Axiom>
+
+    <Axiom id="AX_PREFER_FACTORY_OVER_HOOKS">
+      Default preparation = the file's single factory called inside the case. Each case constructs the exact context it needs by `createXxxContext({ ... overrides })` at the top of the case, destructures only the fields it uses, and proceeds. Per-case dependencies become visible at the call site; no scrolling to a hook; no shared mutable `let` populated in `beforeEach`.
+
+      `beforeEach` is reserved for setup that REQUIRES teardown (see `AX_HOOKS_ONLY_FOR_LIFECYCLE`).
+    </Axiom>
+
+    <Axiom id="AX_HOOKS_ONLY_FOR_LIFECYCLE">
+      `beforeEach` / `afterEach` are reserved for context that REQUIRES teardown — open resources (timers, sockets, file handles, DB connections), global stubs (env, globals), module mocks, fake timers, fixture filesystems, in-process servers.
+
+      A justified hook MUST follow the **single-context shape**: hook builds ONE context object and `afterEach` disposes it. Cases consume properties off that single object — no pile of `let sut, let saveOrder, let publish` in describe scope.
+    </Axiom>
+
+    <Axiom id="AX_NO_DESCRIBE_LET_PILEUP">
+      `describe`-scope MUST NOT host mutable `let` variables populated by hooks. Static fixtures (frozen constants, fixture paths, factory definitions, type aliases) are allowed. Anything mutable per-case lives either inside the case (factory result) or inside the SINGLE lifecycle context object exposed by the hook. Mutable describe-scope state is the structural source of inter-test leakage.
+    </Axiom>
+
+    <!-- ── Mocking discipline ─────────────────────────────────────────────── -->
+
+    <Axiom id="AX_MOCK_AS_LAST_RESORT">
+      Prefer real modules with dependency injection over module-level mocks. A SUT that accepts its collaborators as constructor or function arguments is tested by passing test doubles directly through those seams — no module-level mocking needed.
+
+      Module-level mocking is allowed ONLY when ALL of:
+      1. Dependency is genuinely external (network, FS, process, OS time, randomness, third-party SDKs touching the network).
+      2. No available injection seam in the SUT (refactoring to add one is out of scope).
+      3. Case carries an explicit justification comment naming the dependency and why injection is unavailable.
+
+      Mocks of pure in-process neighboring modules are forbidden by default. Every mock freezes an assumption about another module's behavior; injection keeps the seam observable in the type system.
+    </Axiom>
+
+    <Axiom id="AX_NO_FALSIFICATION_VIA_MOCKS">
+      A test MUST NOT mock the very module that contains the SUT, its direct collaborator under test, or the contract method being verified. Mocking the SUT or its co-tested collaborator turns the test into a tautology — it asserts the mock instead of production code. Non-negotiable; most common form of fabricated green tests in agent-written suites.
+    </Axiom>
+
+    <Axiom id="AX_FIXTURE_IO_POLICY">
+      Reading fixture files is allowed. Writing files inside unit tests is NOT. Writes from a test make the runtime stateful, break parallelism, and leave artifacts in FS that mutate between runs.
+    </Axiom>
+
+    <!-- ── Snapshots ──────────────────────────────────────────────────────── -->
+
+    <Axiom id="AX_SNAPSHOT_USAGE_GATE">
+      Snapshots ONLY for large stable serializable outputs (generated text, HTML, JSON documents, codegen). Do NOT replace scalar or small-object equality with a snapshot — failure shows a diff of snapshot blobs instead of the actual mismatch, and manual review of every scalar change is ceremony with no payoff.
+    </Axiom>
+
+    <Axiom id="AX_SNAPSHOT_OPERATOR_CONFIRM">
+      **Execution-agent MUST NOT update existing snapshots autonomously.** Forbidden: running snapshot-update flags (`vitest -u`, `--update`); editing snapshot literals to make a test pass; deleting snapshot files.
+
+      Allowed: writing the FIRST snapshot for a NEW test (operator reviews in PR/diff). For any change to an existing snapshot the agent stops, presents old vs new content, and waits for explicit operator confirmation. Auto-update is the most direct path an agent has to fabricate a green test.
+    </Axiom>
+
+    <!-- ── File shape + scenario hygiene ──────────────────────────────────── -->
+
+    <Axiom id="AX_FILE_NAME_AND_DEFAULT_SHAPE">
+      File naming: `[subject].test.ts`. Default shape: `describe(subject)` → optional shared hooks → nested `describe(method)` → `it(case)`. A `Test Graph` header comment (map of cases) is RECOMMENDED for multi-method or non-trivial files, OPTIONAL for tiny focused ones.
+    </Axiom>
+
+    <Axiom id="AX_TEST_FILE_SIZE_BUDGET">
+      **Soft target: ≤300 code-LOC per test file. Hard ceiling: 500.** Split axes in priority order: (1) by SUT method — `[subject].[method].test.ts`, sharing factory via a sibling `[subject].test-context.ts`; (2) by scenario family — `[subject].error-paths.test.ts` separate from happy-paths. After a split each file STILL holds exactly one context shape (`AX_ONE_UNIFIED_CONTEXT_PER_FILE`).
+
+      Why: instruction-following degrades with file size. Past 500 LOC the agent loses structure between read/edit cycles → fabricated green tests slip in.
+    </Axiom>
+
+    <Axiom id="AX_ONE_TEST_ONE_SCENARIO">
+      One `it` covers one scenario. Duplicate cases that prove the same behavior create false confidence in coverage and double maintenance cost when the contract changes.
+    </Axiom>
+
+    <Axiom id="AX_TESTS_NO_HUMAN_NARRATION">
+      Never write step-by-step narration like `Step 1`, `Step 2` inside a case. Phase anchors already make the steps machine-visible. Comments only where they increase recoverable intent; do not duplicate the title, assertion text, or obvious setup facts.
+    </Axiom>
+
+    <Axiom id="AX_ENGLISH_ONLY_NAMES_AND_COMMENTS">
+      Test titles, comments, anchors, helper variable names — English only. Mixed languages break grep and comprehension.
+    </Axiom>
+
+    <Axiom id="AX_NO_FOCUSED_OR_SKIPPED_TESTS_ON_MERGE">
+      `it.only` / `describe.only` / `it.skip` / `describe.skip` / `it.todo` MUST NOT be present in committed code unless paired with an inline reference to a tracked deferred-ownership task. A focused `.only` silently disables the rest of the suite; a stray `.skip` rots into a coverage hole.
+    </Axiom>
+
+    <!-- ── Coverage + finalization ────────────────────────────────────────── -->
+
+    <Axiom id="AX_COVERAGE_BY_CONTRACT_NOT_BY_LINE">
+      Measure CONTRACT coverage, not line coverage. Mandatory minimum per public method/function:
+      1. ≥1 happy-path scenario.
+      2. ≥1 boundary scenario (boundary value, edge of input domain) when contract has boundary semantics.
+      3. ≥1 failure-path scenario per declared `@throws` / rejected promise.
+
+      Ignored: thin pass-through wrappers without hidden policy, type-only constructs, dead branches excluded by `AX_MINIMAL_ERROR_SURFACE` in coding-rules.
+    </Axiom>
+
+    <Axiom id="AX_COVERAGE_REPORT_BLOCKER_EXPLICIT">
+      Type-check or coverage cannot run because of an environment / project blocker → declare the blocker EXPLICITLY; do not simulate success. A silent skip turns the completion gate into fiction.
+    </Axiom>
+
+    <Axiom id="AX_VERIFY_AND_FINALIZE">
+      Finalizing a test = re-checking isolation, naming, anchor pairing, snapshot placement, and the diagnostic quality of failures, then running type-check + tests with coverage. Blocker → declared EXPLICITLY.
+    </Axiom>
+
+  </Belief_State>
+
+  <Definitions>
+    <Definition id="DEF_NON_TRIVIAL_CASE">
+      A case is non-trivial if any of: async behavior with setup; retries / fallbacks / errors; emitted events or external side effects; more than one meaningful observation; nested control flow that another agent could misread at a glance. Non-trivial cases are candidates for opening brief and phase anchors per the thresholds in `AX_PHASE_ANCHORS` and `AX_IT_OPENING_BRIEF`.
+    </Definition>
+    <Definition id="DEF_PHASE_ANCHOR_FORMAT">
+      `// #region START_[CASE]_[PHASE]_[INTENT]` and paired `// #endregion END_[CASE]_[PHASE]_[INTENT]`. PHASE ∈ {`SETUP`, `TRIGGER`, `OBSERVE`, `ASSERT`, `CLEANUP`}. CASE = uppercase short scenario id; INTENT = uppercase intent token.
+    </Definition>
+    <Definition id="DEF_TEST_PAYLOAD_VOCAB">
+      Closed vocabulary for intent comments inside tests: `purpose`, `consumer`, `invariant`, `side effect`, `failure mode`, `non-goal`, `contract`, `observation focus`. Same base as production code (`coding/typescript-rules`), plus test-specific `contract` and `observation focus`.
+    </Definition>
+    <Definition id="DEF_UNIFIED_CONTEXT">
+      The single per-file `XxxContext` type plus its single factory `createXxxContext(overrides?)` (or the single `beforeEach`/`afterEach`-managed lifecycle object). Every case in the file uses this one shape. New scenarios extend it via optional fields and overrides rather than introducing parallel structures.
+    </Definition>
+    <Definition id="DEF_INJECTION_SEAM">
+      A constructor parameter, function argument, or factory option of the SUT through which a collaborator can be supplied from outside. Tests use injection seams to pass test doubles without resorting to module-level mocks.
+    </Definition>
+  </Definitions>
+
+  <BDD_Mapping_Hint>
+    Public contract between `task-scaffolding` and any execution-agent writing tests under a runner-specific directive that inherits this file.
+
+    - **`BDD_CANONICAL_CASE_NAME_BINDING`** — canonical case name from ticket MUST be used verbatim as the `it(...)` title. Execution-agent changes a name → MUST update `Test Scenario Coverage` in the ticket BEFORE closing.
+    - **`BDD_SCENARIO_TO_IT`** — one BDD scenario → one `it(...)` case (1:1). Don't merge scenarios; don't split a scenario without explicit derivation.
+    - **`BDD_FEATURE_TO_DESCRIBE`** — `Feature: [Component Behavior]` → outer `describe(...)` (or semantically equivalent SUT name). Each `Scenario:` → separate `it(...)`.
+    - **`BDD_GIVEN_WHEN_THEN_TO_CASE_FLOW`** — `Given` → SETUP phase (or `beforeEach` if shared and lifecycle-bound). `When` → TRIGGER. `Then` → ASSERT. `And` after `Then` → additional assertion in ASSERT or a separate OBSERVE if aggregation justified.
+    - **`BDD_ERROR_SCENARIO_BINDING`** — error / rejection scenario → assert-throws / assert-rejects (runner-specific API). Assert message via regex match (`AX_PARTIAL_STRING_VIA_MATCH`). Domain error class → assert both `instanceof` AND message pattern.
+    - **`BDD_VERIFICATION_SURFACE_GUARDRAIL`** — `Test Scenario Coverage` carries a `Runtime Fidelity` marker. Tests under this directive cover ONLY `contract-only` and `simulation-backed`. `runtime-hook-required` and `e2e-required` are out of scope; record deferred coverage owner EXPLICITLY in Execution Log.
+    - **`BDD_DEFERRED_OWNERSHIP_HONESTY`** — BDD scenario cannot be materialized at this runner level → silent skipping forbidden; add deferred-ownership reference in `Test Scenario Coverage`.
+  </BDD_Mapping_Hint>
+
+  <Workflow_Outline>
+    <Step id="WF_1_DERIVE_SCENARIOS">Read contract + ticket's `Test Scenario Coverage`. Derive happy-path, boundary, failure scenarios. BDD scenarios are normative source of case names.</Step>
+    <Step id="WF_2_DEFINE_UNIFIED_CONTEXT">Define ONE `XxxContext` type and ONE factory at top of file. Teardown required → ONE lifecycle context object in `beforeEach`/`afterEach`. Choose ONE preparation path for the whole file.</Step>
+    <Step id="WF_3_BUDGET_CHECK">Estimate file size for planned cases. Projection >300 LOC → plan a split now (by method or scenario family); unified context survives the split.</Step>
+    <Step id="WF_4_IMPLEMENT_CASES">For each `it`: decide if title alone conveys intent (skip brief) or not (add brief from closed vocab). Wrap phases ≥2 statements or carrying policy in anchors; skip anchors on one-liners. Pass stubs through injection seams.</Step>
+    <Step id="WF_5_CHOOSE_DIAGNOSTIC_ASSERTIONS">Simplest direct assertion first. Aggregate into OBSERVE only when one rich diff beats several isolated assertions.</Step>
+    <Step id="WF_6_VERIFY_AND_FINALIZE">Re-check unified context, anchor pairing, snapshot placement, no ungated mocks. Run type-check + tests with coverage. Blocker → declared EXPLICITLY.</Step>
+  </Workflow_Outline>
+</TestingCommon>

package/dist/ai/directives/testing/node-test.xml

@@ -0,0 +1,288 @@
+<NodeTestRules keywords="node-test, runner, assertions, native_mock_fn, http_mock_agent, snapshot_files" type="testing-rules" ver="3.0">
+  <Mission>
+    Node.js built-in `node:test` runner (`node --test`) specifics on top of [`testing/common`](./common.xml). Only the deltas are stated here: assertion API mapping, native `mock.fn()` usage, HTTP mock-agent harness, snapshot file location.
+
+    Read `testing/common.xml` first. Everything about contract boundary, case flow, phase anchors, unified context, factory-over-hooks, BDD mapping, snapshot operator-confirm, file budget — lives there.
+  </Mission>
+
+  <Inherited_Baseline>
+    All axioms in [`testing/common`](./common.xml) `Belief_State` apply here UNCHANGED — reader-agent treats them as binding under this directive. `BDD_Mapping_Hint`, `Definitions`, `Workflow_Outline` likewise inherited. This file only adds node:test-specific overrides and patterns.
+  </Inherited_Baseline>
+
+  <Belief_State>
+
+    <Axiom id="AX_ASSERT_API_CHOICE">
+      Pick the simplest direct match by shape (node:test assert API):
+      - `assert.strictEqual(actual, expected)` — scalars and reference identity.
+      - `assert.deepStrictEqual(actual, expected)` — structured results (deep, type-strict).
+      - `assert.throws(fn, matcher)` / `await assert.rejects(promise, matcher)` — thrown failures.
+      - `assert.match(str, regex)` — partial string / error-message checks (per inherited `AX_PARTIAL_STRING_VIA_MATCH`).
+      - `t.assert.snapshot(value)` / `t.assert.fileSnapshot(value, path)` — ONLY for large stable serializable outputs (per inherited `AX_SNAPSHOT_USAGE_GATE`).
+
+      Each function has a unique diagnostic signature. A mismatched choice (snapshot for a scalar, `includes` on a message) degrades the failure report.
+
+      Forbidden idioms: `assert.ok(x.includes(y))` on error messages → use `assert.match`. Manual `let threw = false; try {...} catch {...} assert.ok(threw)` → use `assert.throws` / `assert.rejects`.
+    </Axiom>
+
+    <Axiom id="AX_PREFER_NATIVE_MOCK_FN">
+      Use `mock.fn()` from `node:test` for tracking calls and stubbed behavior on injected collaborators. Native API requires no extra dependencies and integrates with the runner (cleanup, assertion helpers).
+
+      Common surface:
+      - `const fn = mock.fn(async () => 'ok')` — create stub with implementation.
+      - `fn.mock.callCount()` / `fn.mock.calls[i].arguments` — interaction assertions.
+      - `mock.module('pkg', { namedExports: {...} })` — module-level mocking (gated by inherited `AX_MOCK_AS_LAST_RESORT` + `AX_NO_FALSIFICATION_VIA_MOCKS`).
+    </Axiom>
+
+    <Axiom id="AX_HTTP_MOCK_AGENT_PATTERN">
+      For HTTP-heavy tests where injection is not feasible:
+      - Use `setupMockAgent()` from `utils/test/mock-http.ts`; call `cleanup()` in `afterEach`.
+      - Request-specific intercepts go INSIDE the case `SETUP` phase, not the shared hook.
+      - If the SUT uses `axios`, set `axios.defaults.adapter = 'fetch'` in shared setup so the mock agent sees the requests.
+
+      Default posture (per inherited `AX_MOCK_AS_LAST_RESORT`): inject an HTTP client / `request` port into the SUT and stub it with `mock.fn()`. Mock-agent harness is for code that already exists without an injection seam.
+    </Axiom>
+
+    <Axiom id="AX_SNAPSHOT_FILE_LOCATION">
+      `t.assert.snapshot()` / `t.assert.fileSnapshot()` outputs live in a dedicated `snapshots/` directory next to the test area. Updates go ONLY through the runner's snapshot-update flow under inherited `AX_SNAPSHOT_OPERATOR_CONFIRM` — manual edits to snapshot files are forbidden (they enable silent contract drift).
+    </Axiom>
+
+  </Belief_State>
+
+  <Test_Patterns>
+    <Pattern id="PT_DIRECT_SCALAR_CASE">
+      <Intent>Trivial scalar case without an opening brief: title + direct input + a single assertion already expose the scenario. Anchors omitted on the one-line TRIGGER and ASSERT phases per `AX_PHASE_ANCHORS`; kept only on SETUP because it has its own intent.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        import { describe, it } from 'node:test';
+        import assert from 'node:assert/strict';
+        import { unwrap } from '#shared/result.ts';
+
+        describe('SlugBuilder', () => {
+            it('should build a lowercase slug from the title', async () => {
+                const input = { title: 'Hello World', separator: '-' };
+                const slug = await unwrap(builder.build(input));
+                assert.strictEqual(slug, 'hello-world');
+            });
+        });
+        ```
+      </Snippet>
+      <Why>Title + direct input + single `strictEqual` make the scenario self-evident → brief skipped. Each phase is one statement with no hidden policy → anchors skipped. Phase grammar still readable for the next agent because the three lines naturally map SETUP/TRIGGER/ASSERT.</Why>
+    </Pattern>
+
+    <Pattern id="PT_ASYNC_RETRY_WITH_BRIEF">
+      <Intent>Async scenario with retry policy: opening brief records invariant + failure mode; phase anchors separate multi-line SETUP, the TRIGGER call, and the composite ASSERT with main + orthogonal observation.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        import { describe, it, beforeEach, afterEach } from 'node:test';
+        import assert from 'node:assert/strict';
+        import { setupMockAgent } from '#utils/test/mock-http.ts';
+
+        describe('VendorClient', () => {
+            let mockEnv: ReturnType<typeof setupMockAgent>;
+            let client: VendorClient;
+
+            beforeEach(() => {
+                mockEnv = setupMockAgent();
+                client = new VendorClient({ baseUrl: 'https://vendor.test' });
+            });
+
+            afterEach(() => { mockEnv.cleanup(); });
+
+            it('should retry once and return the normalized payload', async () => {
+                // contract: one transient failure is tolerated before success is returned
+                // failure mode: do not wrap the returned result into a synthetic summary object
+
+                // #region START_FETCH_ITEM_SETUP_MOCKS
+                const url = 'https://vendor.test/items/42';
+                const tracker = mockEnv.interceptMultiple('GET', url, [
+                    () => ({ status: 503, body: 'Service Unavailable' }),
+                    () => ({ status: 200, body: { id: 42, name: 'Keyboard', inStock: true } }),
+                ]);
+                // #endregion END_FETCH_ITEM_SETUP_MOCKS
+
+                const result = await client.fetchItem(url);
+
+                // #region START_FETCH_ITEM_ASSERT_RESULT
+                assert.deepStrictEqual(result, {
+                    ok: true,
+                    status: 200,
+                    data: { id: 42, name: 'Keyboard', inStock: true },
+                });
+                assert.strictEqual(tracker.getAttemptCount(), 2);
+                // #endregion END_FETCH_ITEM_ASSERT_RESULT
+            });
+        });
+        ```
+      </Snippet>
+      <Why>Brief reveals retry invariant; SETUP has multiple statements + intercept policy → anchored; TRIGGER is a single call → no anchor; ASSERT carries two related observations → anchored. Orthogonal `attemptCount` lives next to the main contract assertion without aggregation noise.</Why>
+    </Pattern>
+
+    <Pattern id="PT_ERROR_PATH_WITH_ASSERT_REJECTS">
+      <Intent>Error-path scenario: focused assertions via `assert.rejects()` + `assert.match()` on a stable message fragment; no `try/catch + flag` antipatterns.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        import { describe, it } from 'node:test';
+        import assert from 'node:assert/strict';
+
+        describe('VendorClient#reserveStock', () => {
+            it('should reject with VendorStockError when upstream reports OUT_OF_STOCK', async () => {
+                // contract: domain error class + recognizable message preserves cause-chain
+                // failure mode: do NOT assert full error.message — it carries a dynamic correlation id
+
+                // #region START_RESERVE_STOCK_SETUP_MOCKS
+                const idempotencyKey = '550e8400-e29b-41d4-a716-446655440000';
+                mockEnv.interceptOnce('POST', '/v2/reservations', () => ({
+                    status: 409,
+                    body: { code: 'OUT_OF_STOCK' },
+                }));
+                // #endregion END_RESERVE_STOCK_SETUP_MOCKS
+
+                await assert.rejects(
+                    () => client.reserveStock(idempotencyKey),
+                    (error: unknown) => {
+                        assert.ok(error instanceof VendorStockError);
+                        assert.match((error as Error).message, /\[VendorClient#reserveStock\] .*OUT_OF_STOCK/);
+                        return true;
+                    }
+                );
+            });
+        });
+        ```
+      </Snippet>
+      <Why>Combined TRIGGER+ASSERT via `assert.rejects` is intentional — forced phase split would yield an empty TRIGGER. The single `rejects` call needs no anchor; SETUP has multiple lines + interception policy → anchored.</Why>
+    </Pattern>
+
+    <Pattern id="PT_MOCK_FN_INTERACTION_CONTRACT">
+      <Intent>Native `mock.fn()` for tracking calls on injected collaborators + assertions on interaction contract without inspecting SUT internals.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        import { describe, it, mock } from 'node:test';
+        import assert from 'node:assert/strict';
+
+        describe('OrderLifecycle#settleCharge', () => {
+            it('should persist order in PAID state and emit settled event after successful charge', async () => {
+                // observation focus: persistence call args + emitted event payload, not pipeline internals
+
+                // #region START_SETTLE_CHARGE_SETUP_DOUBLES
+                const repoSave = mock.fn(async (_order: Order) => {});
+                const onSettled = mock.fn();
+                const lifecycle = new OrderLifecycle({ saveOrder: repoSave });
+                lifecycle.on('settled', onSettled);
+                // #endregion END_SETTLE_CHARGE_SETUP_DOUBLES
+
+                await lifecycle.settleCharge('ord-1');
+
+                // #region START_SETTLE_CHARGE_ASSERT_INTERACTIONS
+                assert.strictEqual(repoSave.mock.callCount(), 1);
+                assert.deepStrictEqual(repoSave.mock.calls[0].arguments[0], {
+                    id: 'ord-1',
+                    state: 'PAID',
+                });
+
+                assert.strictEqual(onSettled.mock.callCount(), 1);
+                assert.deepStrictEqual(onSettled.mock.calls[0].arguments[0], {
+                    type: 'order.settled',
+                    detail: { orderId: 'ord-1' },
+                });
+                // #endregion END_SETTLE_CHARGE_ASSERT_INTERACTIONS
+            });
+        });
+        ```
+      </Snippet>
+      <Why>Demonstrates `AX_PREFER_NATIVE_MOCK_FN` and contract-boundary observation of an emitted event (per inherited `AX_CONTRACT_OVER_IMPLEMENTATION`). Multi-statement SETUP and multi-statement ASSERT anchored; single-line TRIGGER is not.</Why>
+    </Pattern>
+
+    <Pattern id="PT_FIXTURE_AND_OBSERVE_AGGREGATION">
+      <Intent>Composite contract (generated text + observability milestone) where an OBSERVE phase normalizes result + side-effect log into one diagnostic slice. Justified case for aggregation per inherited `AX_DEFAULT_DIRECT_ASSERTION_PROTOCOL`.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        import { describe, it, beforeEach } from 'node:test';
+        import assert from 'node:assert/strict';
+        import { readFileSync } from 'node:fs';
+
+        describe('CodegenPipeline#renderModule', () => {
+            let pipeline: CodegenPipeline;
+
+            beforeEach(() => {
+                pipeline = new CodegenPipeline({ logger: createMemoryLogger() });
+            });
+
+            it('should produce normalized output and emit a single info-level milestone log', async () => {
+                // contract: pipeline emits exactly one info log per successful render
+                // failure mode: do not snapshot scalar log count — it hides the actual milestone shape
+
+                const inputSpec = JSON.parse(readFileSync('test/fixtures/render-module.input.json', 'utf8'));
+                const output = await pipeline.renderModule(inputSpec);
+
+                // #region START_RENDER_MODULE_OBSERVE_AGGREGATE
+                // observation focus: text + milestone collapsed into one diff for a richer failure report
+                const actual = {
+                    text: output.text,
+                    milestones: pipeline.logger.records
+                        .filter((r) => r.level === 'info')
+                        .map((r) => r.message),
+                };
+                // #endregion END_RENDER_MODULE_OBSERVE_AGGREGATE
+
+                assert.deepStrictEqual(actual, {
+                    text: '/* generated module */\nexport const value = 42;\n',
+                    milestones: ['[CodegenPipeline#renderModule] [rendering → rendered] ok'],
+                });
+            });
+        });
+        ```
+      </Snippet>
+      <Why>Aggregation in OBSERVE justified: a single `deepStrictEqual` shows drift in both text and milestones. SETUP and TRIGGER are one-liners → no anchors; OBSERVE has aggregation policy → anchored. Fixture read allowed, write forbidden (inherited `AX_FIXTURE_IO_POLICY`).</Why>
+    </Pattern>
+  </Test_Patterns>
+
+  <Anti_Patterns>
+    <Anti_Pattern id="AP_PRIVATE_INSPECTION">
+      <Bad>Test inspects `client._inflightCount` (protected/internal field) via `@ts-expect-error` to bypass encapsulation.</Bad>
+      <Why_Bad>Violates inherited `AX_CONTRACT_OVER_IMPLEMENTATION`. A refactor renaming `_inflightCount` to `_pending` breaks the test without changing the contract.</Why_Bad>
+      <Good>Subscribe to `client.on('reservation.requested', e => events.push(e))` and assert `events.length` + `events[0].idempotencyKey`. Public lifecycle event is the observable.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_TRY_CATCH_FLAG_ANTIPATTERN">
+      <Bad>`let threw = false; try { await client.reserveStock(''); } catch (e) { threw = true; assert.ok((e as Error).message.includes('idempotency')); } assert.ok(threw);`</Bad>
+      <Why_Bad>Manual try/catch + boolean flag instead of `assert.rejects()` (`AX_ASSERT_API_CHOICE`). `includes()` on error message (inherited `AX_PARTIAL_STRING_VIA_MATCH`). Test can silently pass if the code stops throwing — `threw` stays false, only fallback gate is `assert.ok(threw)`.</Why_Bad>
+      <Good>`await assert.rejects(() => client.reserveStock(''), (error) => { assert.match((error as Error).message, /idempotency.*empty|empty.*idempotency/i); return true; });`</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SHARED_MUTABLE_STATE_AND_NON_ENGLISH_NARRATION">
+      <Bad>`const cart = new Cart()` shared between tests; test names in Russian («добавляет товар»); `Шаг 1: добавляем` / `Шаг 2: проверяем` comments; second test depends on state from first.</Bad>
+      <Why_Bad>Shared mutable state breaks isolation (inherited `AX_NO_DESCRIBE_LET_PILEUP`); creates order dependency. Non-English names/comments (inherited `AX_ENGLISH_ONLY_NAMES_AND_COMMENTS`). Step-by-step human narration (inherited `AX_TESTS_NO_HUMAN_NARRATION`).</Why_Bad>
+      <Good>Single context factory `createCartContext(overrides?)` called inside each case; English titles like `should expose count = 1 after a single add`; direct assertions.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SNAPSHOT_FOR_SCALAR">
+      <Bad>`it('returns 42', (t) => { const result = compute(); t.assert.snapshot(result); });`</Bad>
+      <Why_Bad>Snapshot for a scalar — violates inherited `AX_SNAPSHOT_USAGE_GATE`. Failure shows diff of snapshot blobs instead of «42 ≠ 41».</Why_Bad>
+      <Good>`assert.strictEqual(result, 42)` — direct, clear, no snapshot file overhead.</Good>
+    </Anti_Pattern>
+  </Anti_Patterns>
+
+  <Verification_Hooks>
+    <Hook id="HOOK_RUN_TESTS">
+      <Command>npm test</Command>
+      <Expected>Exit 0; all cases pass; no `.skip` / `.todo` without explicit deferred-ownership in the ticket.</Expected>
+    </Hook>
+    <Hook id="HOOK_RUN_SINGLE_FILE">
+      <Command>node --test path/to/subject.test.ts</Command>
+      <Expected>Exit 0; targeted file passes.</Expected>
+    </Hook>
+    <Hook id="HOOK_COVERAGE">
+      <Command>node --test --experimental-test-coverage</Command>
+      <Expected>Exit 0; report shows public methods with ≥1 happy + ≥1 boundary (when applicable) + ≥1 failure-path per inherited `AX_COVERAGE_BY_CONTRACT_NOT_BY_LINE`. Coverage cannot run → declare blocker EXPLICITLY.</Expected>
+    </Hook>
+    <Hook id="HOOK_TYPECHECK_BEFORE_TEST">
+      <Command>npx tsc --noEmit</Command>
+      <Expected>Exit 0; no TS errors.</Expected>
+    </Hook>
+    <Hook id="HOOK_NO_FORBIDDEN_TEST_PATTERNS">
+      <Purpose>Smoke-grep for forbidden idioms: human narration `Step N`, `includes(` on error message, manual try-catch flag.</Purpose>
+      <Command>rg --no-heading -n "Step \d|\.message.*\.includes\(|let\s+threw\s*=" -t ts --glob '**/*.test.ts'</Command>
+      <Expected>Empty on new/changed test files.</Expected>
+    </Hook>
+  </Verification_Hooks>
+</NodeTestRules>