gennady 0.6.0 → 0.7.0

package/dist/ai/directives/testing/storybook-usage.xml

@@ -0,0 +1,173 @@
+<StorybookUsageRules keywords="storybook, mcp, component-development, stories, play-function, ai-generated, self-verify" type="testing-rules" ver="2.0">
+  <Mission>
+    Canonical rules for using an installed Storybook instance to develop and test UI components. Every execution-agent MUST use the MCP integration as the primary source for component documentation, stories, and tests. Hand-written guesses about component props are forbidden — the prop surface comes from `get-documentation` (or its current MCP equivalent), not from memory.
+
+    **Base axiom:** Storybook is the project's executable component spec. A story IS the contract; running a story IS the verification step. Authoring without consulting the MCP-exposed spec produces stories that compile but fail at first render — the self-healing loop then chases its own tail. So the order is fixed: read spec → write story → run story tests → fix → re-run.
+
+    Companion (one-time installation): `ai/directives/infra/storybook-setup.xml`.
+  </Mission>
+
+  <Belief_State>
+    <Axiom id="AX_SB_USE_NEVER_HALLUCINATE_PROPS">
+      Component props, slot/snippet names, exported events, and tags ALWAYS come from the MCP documentation channel before a story is written or edited. Inferring props from name, by analogy with another component, or from chat history is forbidden — hallucinated props pass TypeScript narrowing if the type is loose and fail silently at story render time, burning the self-healing loop on a problem the MCP would have answered immediately.
+    </Axiom>
+
+    <Axiom id="AX_SB_USE_MCP_FIRST">
+      MCP tools are the primary source for everything Storybook-related: discovering documentation, reading component props, reading existing stories, executing story tests. Source-code reading is a FALLBACK reserved for when MCP returns an explicit «not available» or incomplete data. Falling back to source must be acknowledged in a story comment naming the MCP gap.
+    </Axiom>
+
+    <Axiom id="AX_SB_USE_ONE_STORY_ONE_CONCEPT">
+      Each story exposes ONE concept: one variant, one state, one interaction flow. Combining «logged-in user opens modal AND submits form AND sees error» into a single story collapses three contracts into one diff. When tests fail, the failure cannot be attributed; when the contract shifts, three concepts get tangled in one edit.
+    </Axiom>
+
+    <Axiom id="AX_SB_USE_PLAY_FOR_INTERACTION">
+      Any story that exercises user behaviour (click, type, drag, navigation) MUST attach a `play` function asserting the resulting state. A story without `play` for an interactive scenario is documentation only — it provides no executable contract and the self-verification loop has nothing to assert against. `play` uses the project's chosen interaction API (`userEvent`, `step`, framework-provided utilities) consistently.
+    </Axiom>
+
+    <Axiom id="AX_SB_USE_AI_GENERATED_TAG">
+      Every agent-authored story carries the reserved tag (project canonical: `'ai-generated'`) in its `tags` array. This separates machine-authored from human-authored stories so human curators can audit, batch-update, or selectively re-test the agent output without scanning every file. Stripping or omitting the tag from an agent-authored story is forbidden.
+    </Axiom>
+
+    <Axiom id="AX_SB_USE_COMPOSE_EXISTING_FIRST">
+      When an existing story already covers the base variant the new scenario extends, the new story composes its args from the existing one (`args: { ...ExistingStory.args, fieldToChange: newValue }`) rather than restating the full argument map. Restating duplicates a structure that should drift in only one place; the duplicate becomes the source of truth-drift on the first prop rename.
+    </Axiom>
+
+    <Axiom id="AX_SB_USE_SELF_VERIFY_BEFORE_HANDOFF">
+      A story task is not complete until `run-story-tests` (the project's MCP-exposed runner) passes for every story in the affected component file — not just the new one. A new story may break an existing one through a shared mock or a shared decorator; running only the new story hides those breakages.
+
+      `run-story-tests` failure is NEVER silenced by deleting the failing story or by adding `.skip` — the failure is fixed (component or story), surfaced as a real blocker, or paired with a tracked deferred-ownership reference.
+    </Axiom>
+
+    <Axiom id="AX_SB_USE_COMPONENT_CHANGE_TRIGGERS_STORY_RUN">
+      A component edit MUST be followed by `run-story-tests` on every story owned by that component. A story failure after a component edit is, by definition, a regression — either the component contract changed (story must be updated and the change documented) or the edit broke the contract unintentionally (component must be fixed). Either path is acceptable; ignoring the failure is not.
+    </Axiom>
+
+    <Axiom id="AX_SB_USE_NO_PARALLEL_RENDER_HARNESS">
+      Component rendering for testing goes through the project's chosen Storybook harness, not through a parallel render path (custom Vitest project mounting the component bypassing the addon, ad-hoc puppet scripts). Parallel harnesses duplicate the render contract and drift the first time a decorator is added; the drift surfaces as «works in Storybook, fails in tests» (or vice versa) with no audit trail.
+    </Axiom>
+  </Belief_State>
+
+  <Definitions>
+    <Definition id="DEF_SB_MCP_TOOLS">
+      MCP tools exposed by the Storybook integration (canonical naming subject to addon version): `list-all-documentation`, `get-documentation`, `get-documentation-for-story`, `get-storybook-story-instructions`, `preview-stories`, `run-story-tests`. Exact names live in `AGENTS.md` per `storybook-setup`.
+    </Definition>
+    <Definition id="DEF_SB_STORY_CANONICAL_FORM">
+      Canonical agent-authored story: `export const VariantName: Story = { args: { ...ExistingStory.args, ...overrides }, tags: ['ai-generated', ...domainTags], play: async ({ canvasElement, step }) => { ... } }`. `play` is required when the story exercises any user interaction.
+    </Definition>
+  </Definitions>
+
+  <Code_Patterns>
+    <Pattern id="PT_SB_COMPOSED_STORY_WITH_PLAY">
+      <Intent>New variant composes args from an existing story, carries the `ai-generated` tag, and asserts behaviour through `play`.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        import type { Meta, StoryObj } from '@storybook/svelte';
+        import { expect, userEvent, within } from '@storybook/test';
+        import Button from './Button.svelte';
+
+        const meta: Meta<typeof Button> = {
+          component: Button,
+          tags: ['autodocs'],
+        };
+        export default meta;
+
+        type Story = StoryObj<typeof meta>;
+
+        export const Primary: Story = {
+          args: { label: 'Submit', variant: 'primary' },
+        };
+
+        export const DisabledClickDoesNothing: Story = {
+          args: { ...Primary.args, disabled: true },
+          tags: ['ai-generated'],
+          play: async ({ canvasElement, step }) => {
+            const canvas = within(canvasElement);
+            const button = canvas.getByRole('button', { name: 'Submit' });
+            await step('Click is a no-op when disabled', async () => {
+              await userEvent.click(button);
+              await expect(button).toBeDisabled();
+            });
+          },
+        };
+        ```
+      </Snippet>
+      <Why>One concept (disabled-click no-op); args composed from `Primary.args`; `ai-generated` tag present; `play` asserts the contract through role-based query.</Why>
+    </Pattern>
+  </Code_Patterns>
+
+  <Anti_Patterns>
+    <Anti_Pattern id="AP_SB_HALLUCINATED_PROPS">
+      <Bad>Agent writes `<Button label="Go" intent="ghost" size="xl">` based on what «buttons usually have», without consulting MCP; story compiles because props are typed as `Record<string, unknown>` but renders as the default variant.</Bad>
+      <Why_Bad>Props guessed instead of retrieved via MCP (`AX_SB_USE_NEVER_HALLUCINATE_PROPS`). Compiles cleanly, fails at render or silently produces the wrong variant — the failure is then chased through the self-healing loop instead of being answered up-front by `get-documentation`.</Why_Bad>
+      <Good>Call `get-documentation` on `Button`, read the actual prop schema (e.g. `label`, `variant`, `disabled`), write the story using the documented props only. If MCP returns incomplete data, comment in the story noting the gap and fall back to reading source.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SB_MISSING_PLAY_ON_INTERACTION">
+      <Bad>Story named `OpensModalOnClick` consists only of `args: { ... }` and no `play` function; the user-flow concept is documentation, not an executable contract.</Bad>
+      <Why_Bad>Interactive story without `play` (`AX_SB_USE_PLAY_FOR_INTERACTION`). The self-verification loop has nothing to assert against; `run-story-tests` will pass trivially without exercising the flow that the story name claims to verify.</Why_Bad>
+      <Good>Add `play: async ({ canvasElement, step }) => { const canvas = within(canvasElement); await userEvent.click(canvas.getByRole('button', { name: 'Open' })); await expect(canvas.getByRole('dialog')).toBeVisible(); }`.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SB_MISSING_AI_TAG">
+      <Bad>Agent-authored story carries `tags: ['autodocs']` only — no `'ai-generated'`.</Bad>
+      <Why_Bad>Reserved agent-authorship tag missing (`AX_SB_USE_AI_GENERATED_TAG`). Human curators can no longer batch-audit machine output or distinguish it from hand-curated stories; the tag's purpose is to make agent provenance discoverable.</Why_Bad>
+      <Good>`tags: ['autodocs', 'ai-generated']`. Composition with other tags is fine; omission of `'ai-generated'` from agent-authored stories is not.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SB_SKIP_SELF_VERIFY">
+      <Bad>Agent writes a new story, runs only `npx tsc --noEmit`, sees no type error, and marks the task complete without invoking `run-story-tests`.</Bad>
+      <Why_Bad>Self-verification skipped (`AX_SB_USE_SELF_VERIFY_BEFORE_HANDOFF`). Type-check covers the prop schema but not the runtime render or the `play` assertions; the story may explode at first execution. The MCP-exposed runner is exactly the channel that catches this in seconds.</Why_Bad>
+      <Good>After authoring: `run-story-tests` on every story in the affected component file. Green run → handoff. Red run → fix the story or the component, re-run, repeat until green.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SB_REWRITE_INSTEAD_OF_COMPOSE">
+      <Bad>New `Disabled` story restates the full `args: { label, variant, size, icon, ariaLabel, ... }` map identical to `Primary.args` except for one field.</Bad>
+      <Why_Bad>Args restated instead of composed (`AX_SB_USE_COMPOSE_EXISTING_FIRST`). The duplicated map drifts the first time `Primary.args` gains or renames a field — the `Disabled` story silently falls behind without any test failure pointing at it.</Why_Bad>
+      <Good>`args: { ...Primary.args, disabled: true }`. Composition makes the diff visible and keeps the variant aligned with the base.</Good>
+    </Anti_Pattern>
+  </Anti_Patterns>
+
+  <Workflow_Outline>
+    <Step id="WF_SB_1_RETRIEVE_DOCS">Call `get-documentation` (and `get-documentation-for-story` when extending an existing variant) for the target component. Read prop schema, existing variants, exposed events.</Step>
+    <Step id="WF_SB_2_PICK_BASE_OR_NEW">If an existing story matches the base variant, compose args from it. Otherwise author from documented props only.</Step>
+    <Step id="WF_SB_3_AUTHOR_ONE_CONCEPT_PER_STORY">One story = one concept. Add `'ai-generated'` tag. Interactive scenarios get a `play` function asserting the post-state.</Step>
+    <Step id="WF_SB_4_RUN_STORY_TESTS">Invoke `run-story-tests` for every story in the affected file. Failure → fix component or story, re-run, repeat.</Step>
+    <Step id="WF_SB_5_VERIFY_AND_FINALIZE">Before handoff: tests green; props confirmed via MCP; tag present; one concept per story; existing stories not regressed. Environment blocker → declared EXPLICITLY.</Step>
+  </Workflow_Outline>
+
+  <Verification_Hooks>
+    <Hook id="HOOK_SB_RUN_STORY_TESTS">
+      <Purpose>Story tests pass for the affected component file via the project's MCP-exposed runner (script name from `package.json`).</Purpose>
+      <Command>npm run test-storybook -- --url http://localhost:6006</Command>
+      <Expected>Exit 0; all stories in scope pass. Non-zero requires fix or explicit deferred-ownership reference.</Expected>
+    </Hook>
+    <Hook id="HOOK_SB_AI_TAG_PRESENT">
+      <Purpose>Every story file modified by the agent has at least one story tagged `'ai-generated'`.</Purpose>
+      <Command>find . -name '*.stories.*' -not -path '*/node_modules/*' -print0 | xargs -0 grep -lE "tags:\s*\[[^]]*'ai-generated'" || echo MISSING</Command>
+      <Expected>For agent-touched story files, the path appears in output. `MISSING` after an agent-authored story task means the reserved tag was not applied.</Expected>
+    </Hook>
+    <Hook id="HOOK_SB_INTERACTIVE_STORIES_HAVE_PLAY">
+      <Purpose>Stories whose name implies an interaction (`OnClick`, `OpensModal`, `Submits`, `Toggles`) carry a `play` function.</Purpose>
+      <Command>find . -name '*.stories.*' -not -path '*/node_modules/*' -print0 | xargs -0 grep -nE 'export const [A-Z][A-Za-z]*(Click|Submits|Opens|Toggles|Types|Drags)' || true</Command>
+      <Expected>Manual review: every match resolves to a story whose body contains `play:`. Matches without `play` are violations.</Expected>
+    </Hook>
+  </Verification_Hooks>
+
+  <Reward_Criteria>
+    ✅ Props, events, slots/snippets retrieved via MCP before any story is written; source-code fallback annotated when used.
+    ✅ Each story expresses one concept; multiple variants live as multiple stories.
+    ✅ Interactive stories carry a `play` function asserting the post-interaction state.
+    ✅ Every agent-authored story carries the `'ai-generated'` tag.
+    ✅ New variants compose `args` from the closest existing story rather than restating the full map.
+    ✅ `run-story-tests` green for every story in the affected component file before handoff.
+    ✅ Component edits trigger a re-run of all owned stories; regressions surface as fix or explicit deferred-ownership.
+
+    ❌ Hallucinated props, events, or variant names.
+    ❌ Interactive story without a `play` function.
+    ❌ Agent-authored story missing the `'ai-generated'` tag.
+    ❌ Args restated in full when composition with an existing story would suffice.
+    ❌ Task marked complete without running `run-story-tests`.
+    ❌ Story failure silenced by `.skip` or deletion instead of fixed or escalated.
+    ❌ Parallel render harness introduced beside the project's chosen Storybook addon.
+  </Reward_Criteria>
+</StorybookUsageRules>

package/dist/ai/directives/testing/svelte-testing.xml

@@ -0,0 +1,237 @@
+<SvelteTestingRules keywords="svelte, testing, vitest, svelte-testing-library, flushSync, effect-root, mount, unmount, jsdom" type="testing-rules" ver="2.0">
+  <Mission>
+    Canonical rules for testing Svelte 5 components on the Vitest runner with `@testing-library/svelte`. Every execution-agent MUST mount components through testing-library `render()`, flush pending effects via `flushSync()` before assertions, and unmount in cleanup so state cannot leak across cases.
+
+    **Base axiom:** a Svelte 5 component is a tree of reactive primitives backed by a compile-time effect graph. A test that asserts the DOM without first flushing the effect graph is asserting an arbitrary intermediate state — sometimes green, sometimes red, never trustworthy. So discipline is non-negotiable: render → mutate → `flushSync` → assert → cleanup.
+
+    Scope: unit/integration tests for `.svelte` components and `.svelte.ts` modules. Out of scope: end-to-end browser tests (covered by `playwright-e2e`) and Storybook-driven story tests (covered by `storybook-usage`).
+
+    Test files use the `.svelte.test.ts` extension so the Svelte plugin processes their imports.
+  </Mission>
+
+  <Depends_On>
+    - ai/directives/testing/vitest-rules.xml
+    - ai/directives/coding/svelte5-runes.xml
+  </Depends_On>
+
+  <Belief_State>
+    <Axiom id="AX_SVELTE_TEST_FILE_EXTENSION">
+      Component test files use the `.svelte.test.ts` extension — the Svelte-aware Vitest convention. Plain `.test.ts` does NOT receive Svelte plugin processing; importing a `.svelte` component from such a file produces opaque compile or runtime errors. Naming is the contract that tells the toolchain «this file must go through the Svelte compiler».
+    </Axiom>
+
+    <Axiom id="AX_SVELTE_TEST_FLUSH_BEFORE_ASSERT">
+      After any state mutation (user event, prop change, direct state write, simulated time advance) the test MUST call `flushSync()` from `svelte` before asserting on the DOM. `flushSync` forces pending `$effect` callbacks and DOM updates to run synchronously; without it the assertion runs against an intermediate, often stale, DOM.
+
+      Async helpers like `userEvent` may flush implicitly in some scenarios — relying on that implicit flush is fragile. Explicit `flushSync()` after the mutation is the discipline.
+    </Axiom>
+
+    <Axiom id="AX_SVELTE_TEST_EFFECT_ROOT_OUTSIDE_COMPONENT">
+      Tests exercising `$effect` directly (not through a mounted component) MUST run inside `$effect.root(() => { ... })` and dispose of its returned cleanup. `$effect` outside a component context is illegal; `$effect.root` provides the disposal boundary that makes it legal AND that prevents effects from leaking into subsequent tests.
+
+      For component tests, `@testing-library/svelte` `render()` already establishes a component context — explicit `$effect.root` is needed only for direct rune testing in `.svelte.ts` modules.
+    </Axiom>
+
+    <Axiom id="AX_SVELTE_TEST_MOUNT_AND_CLEANUP">
+      Every component mount MUST be paired with cleanup. Either:
+      - rely on testing-library's auto-cleanup (when the Vitest config enables it), OR
+      - register `afterEach(() => cleanup())` explicitly.
+
+      Skipping cleanup leaves mounted components in the document between cases; subsequent queries return stale matches and inter-test isolation collapses.
+    </Axiom>
+
+    <Axiom id="AX_SVELTE_TEST_LIBRARY_FOR_RENDERING">
+      Component rendering and querying go through `@testing-library/svelte`: `render(Component, { props })` for mounting; `screen.getByRole` / `getByLabelText` / `getByText` for querying. Direct `document.querySelector` / `container.querySelector` is forbidden as the default — it bypasses the accessibility-aware query layer that protects the test from CSS-coupling.
+
+      Reserved exception: an element with no semantic role AND no test-id where a selector is the only way to reach it; in that case the selector is paired with a comment naming the missing semantic.
+    </Axiom>
+
+    <Axiom id="AX_SVELTE_TEST_ROLE_QUERIES_PREFERRED">
+      Within the testing-library query surface, prefer role-based queries (`getByRole`, `getByLabelText`, `getByPlaceholderText`) over text-only queries. Role queries express the user-perceived contract; text queries are fragile to copy changes that have no contract impact.
+    </Axiom>
+
+    <Axiom id="AX_SVELTE_TEST_JSDOM_ENVIRONMENT">
+      The test runner environment is `jsdom` (or the equivalent browser-like environment the project standardised on). Mixing `jsdom` with `node` between files in the same suite is forbidden — one environment per project. The Svelte plugin is registered with Vitest so `.svelte` imports compile correctly during tests.
+    </Axiom>
+
+    <Axiom id="AX_SVELTE_TEST_PREFER_STORY_TESTS_WHEN_AVAILABLE">
+      If the project has a working Storybook integration with a story-test addon, prefer authoring story-level tests over manual `render()` calls — stories already document props and behaviour, and the story-test addon reuses them as executable contracts. Manual `render()` tests are reserved for cases that have no natural story counterpart (e.g. pure `.svelte.ts` reactive modules, error boundaries hard to express as a story variant).
+    </Axiom>
+
+    <Axiom id="AX_SVELTE_TEST_NO_DIRECT_DOM_QUERY">
+      `container.querySelector('.some-class')` and `document.getElementById(...)` are forbidden as the default DOM query. They couple the test to CSS class names and DOM structure — neither of which is part of the component contract. The accessibility-aware testing-library queries are the contract surface.
+    </Axiom>
+
+    <Axiom id="AX_SVELTE_TEST_INHERITED_VITEST_RULES">
+      All Vitest discipline applies unchanged: single unified context per file, factory-over-hooks for non-lifecycle setup, file-size budget, no `vi.mock` without operator confirm, no auto snapshot updates, explicit imports from `vitest`. This directive only adds Svelte-specific overlays — it does NOT relax inherited rules.
+    </Axiom>
+  </Belief_State>
+
+  <Definitions>
+    <Definition id="DEF_SVELTE_TEST_FILE">
+      A file matching `*.svelte.test.ts` — processed by the Svelte plugin during Vitest's transform stage. Plain `.test.ts` is not a Svelte test file.
+    </Definition>
+    <Definition id="DEF_FLUSH_BOUNDARY">
+      The synchronous point after a state mutation at which `$effect` callbacks and DOM updates run. `flushSync()` from `svelte` forces this boundary explicitly. Assertions placed before the boundary observe stale state.
+    </Definition>
+  </Definitions>
+
+  <Code_Patterns>
+    <Pattern id="PT_SVELTE_TEST_RENDER_AND_ASSERT">
+      <Intent>Minimal render + role-based query + assertion. No state mutation, so no `flushSync` needed.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        // Counter.svelte.test.ts
+        import { afterEach, describe, expect, it } from 'vitest';
+        import { cleanup, render, screen } from '@testing-library/svelte';
+        import Counter from './Counter.svelte';
+
+        afterEach(() => cleanup());
+
+        describe('Counter', () => {
+          it('should render the initial count from props', () => {
+            render(Counter, { props: { initial: 5, label: 'Count' } });
+            expect(screen.getByRole('button')).toHaveTextContent('Count: 5');
+          });
+        });
+        ```
+      </Snippet>
+      <Why>`.svelte.test.ts` extension; explicit `cleanup` in `afterEach`; role-based query; no mutation so no flush boundary.</Why>
+    </Pattern>
+
+    <Pattern id="PT_SVELTE_TEST_USER_INTERACTION_WITH_FLUSH">
+      <Intent>User interaction triggers state mutation → `flushSync` → role-based assertion of the resulting DOM.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        import { afterEach, describe, expect, it } from 'vitest';
+        import { cleanup, render, screen } from '@testing-library/svelte';
+        import userEvent from '@testing-library/user-event';
+        import { flushSync } from 'svelte';
+        import Counter from './Counter.svelte';
+
+        afterEach(() => cleanup());
+
+        describe('Counter#increment', () => {
+          it('should increment on click and reflect the new count', async () => {
+            render(Counter, { props: { initial: 0, label: 'Count' } });
+            const button = screen.getByRole('button');
+
+            await userEvent.click(button);
+            flushSync();
+
+            expect(button).toHaveTextContent('Count: 1');
+          });
+        });
+        ```
+      </Snippet>
+      <Why>`userEvent.click` is the mutation; explicit `flushSync()` forces effect graph to settle before the assertion runs.</Why>
+    </Pattern>
+
+    <Pattern id="PT_SVELTE_TEST_EFFECT_ROOT_FOR_RUNES">
+      <Intent>Testing a `.svelte.ts` reactive module directly — outside any component — via `$effect.root`.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        // counter-store.svelte.test.ts
+        import { describe, expect, it } from 'vitest';
+        import { flushSync } from 'svelte';
+        import { createCounter } from './counter-store.svelte';
+
+        describe('createCounter', () => {
+          it('should publish derived doubled value reactively', () => {
+            const cleanup = $effect.root(() => {
+              const counter = createCounter(2);
+              let observed = 0;
+              $effect(() => { observed = counter.doubled; });
+              flushSync();
+              expect(observed).toBe(4);
+
+              counter.increment();
+              flushSync();
+              expect(observed).toBe(6);
+            });
+            cleanup();
+          });
+        });
+        ```
+      </Snippet>
+      <Why>`$effect.root` provides the disposal boundary required for `$effect` outside a component; `flushSync` between mutation and assertion; explicit `cleanup()` disposes the root.</Why>
+    </Pattern>
+  </Code_Patterns>
+
+  <Anti_Patterns>
+    <Anti_Pattern id="AP_SVELTE_TEST_PLAIN_TS_EXTENSION">
+      <Bad>File named `Counter.test.ts` imports `Counter.svelte`; Vitest fails with «Cannot find module» or compiles the component as plain TS and explodes at first runtime use.</Bad>
+      <Why_Bad>Plain `.test.ts` extension for a Svelte component test (`AX_SVELTE_TEST_FILE_EXTENSION`). The Svelte plugin's file-pattern rule does not match; the test file bypasses Svelte compilation entirely. The error is opaque because the failure happens during transform, not at a useful assertion point.</Why_Bad>
+      <Good>Rename to `Counter.svelte.test.ts`. No code change required; the toolchain now routes the file through the Svelte plugin.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SVELTE_TEST_NO_FLUSH">
+      <Bad>`await userEvent.click(button); expect(button).toHaveTextContent('Count: 1');` — assertion immediately after the mutation, no `flushSync`.</Bad>
+      <Why_Bad>Mutation asserted before the effect graph settles (`AX_SVELTE_TEST_FLUSH_BEFORE_ASSERT`). Sometimes green (when the implicit microtask flush happened to run), sometimes red, never trustworthy. Order-dependent flakiness for the next agent to debug.</Why_Bad>
+      <Good>`await userEvent.click(button); flushSync(); expect(button).toHaveTextContent('Count: 1');` — explicit boundary makes the assertion deterministic.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SVELTE_TEST_NO_EFFECT_ROOT">
+      <Bad>In a `.svelte.test.ts` for a `.svelte.ts` module: `const c = createCounter(); $effect(() => { observed = c.doubled; }); flushSync();` — `$effect` invoked outside any root.</Bad>
+      <Why_Bad>`$effect` without component context AND without `$effect.root` (`AX_SVELTE_TEST_EFFECT_ROOT_OUTSIDE_COMPONENT`). The runtime throws «effect_orphan» (or equivalent) the moment the effect tries to register. Even if it survives, there is no disposal — the effect leaks into the next test.</Why_Bad>
+      <Good>Wrap in `$effect.root`: `const cleanup = $effect.root(() => { ... $effect(...) ... }); flushSync(); cleanup();` — root provides the disposal boundary; explicit `cleanup()` runs after the assertion.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SVELTE_TEST_NO_CLEANUP">
+      <Bad>Multiple `render(Component, ...)` calls across cases; no `afterEach(() => cleanup())`; testing-library auto-cleanup not enabled in config.</Bad>
+      <Why_Bad>Mount without paired cleanup (`AX_SVELTE_TEST_MOUNT_AND_CLEANUP`). DOM accumulates between cases; `getByRole` starts returning matches from a previous test's mount, producing «works alone, fails in suite» symptoms that are hard to attribute.</Why_Bad>
+      <Good>Either enable testing-library auto-cleanup in `vitest.config.ts`, or explicitly `afterEach(() => cleanup())` in the file.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SVELTE_TEST_DIRECT_QUERYSELECTOR">
+      <Bad>`const button = container.querySelector('.submit-btn'); expect(button.textContent).toBe('Go');`</Bad>
+      <Why_Bad>Direct DOM query coupled to a CSS class (`AX_SVELTE_TEST_NO_DIRECT_DOM_QUERY`, `AX_SVELTE_TEST_ROLE_QUERIES_PREFERRED`). `.submit-btn` is implementation detail with no contract status. Refactor that renames the class turns the test red without any behavioural change.</Why_Bad>
+      <Good>`expect(screen.getByRole('button', { name: 'Go' })).toBeInTheDocument();` — role + accessible name, the contract surface a user perceives.</Good>
+    </Anti_Pattern>
+  </Anti_Patterns>
+
+  <Verification_Hooks>
+    <Hook id="HOOK_SVELTE_TEST_RUN">
+      <Purpose>Run Svelte component tests via Vitest in one-shot mode.</Purpose>
+      <Command>npx vitest run</Command>
+      <Expected>Exit 0; all `.svelte.test.ts` files pass.</Expected>
+    </Hook>
+    <Hook id="HOOK_SVELTE_TEST_EXTENSION_DISCIPLINE">
+      <Purpose>Detect Svelte component imports inside plain `.test.ts` files.</Purpose>
+      <Command>find . -name '*.test.ts' -not -name '*.svelte.test.ts' -not -path '*/node_modules/*' -print0 | xargs -0 grep -lE "from\s+['\"][^'\"]+\.svelte['\"]" || true</Command>
+      <Expected>Empty output. Matches must be renamed to `*.svelte.test.ts`.</Expected>
+    </Hook>
+    <Hook id="HOOK_SVELTE_TEST_HAS_FLUSH_AFTER_USEREVENT">
+      <Purpose>Smoke-grep for likely flush gaps — `userEvent` immediately followed by an assertion with no `flushSync`.</Purpose>
+      <Command>find . -name '*.svelte.test.ts' -not -path '*/node_modules/*' -print0 | xargs -0 grep -nE 'userEvent\.|fireEvent\.' || true</Command>
+      <Expected>Manual review: each match is followed within a few lines by `flushSync()` (or by an `await` on an async helper that documents its own flush).</Expected>
+    </Hook>
+    <Hook id="HOOK_SVELTE_TEST_NO_DIRECT_DOM_QUERIES">
+      <Purpose>Detect direct DOM queries in component tests.</Purpose>
+      <Command>find . -name '*.svelte.test.ts' -not -path '*/node_modules/*' -print0 | xargs -0 grep -nE '(container|document)\.(querySelector|getElementById)' || true</Command>
+      <Expected>Empty output. Matches must migrate to `screen.getByRole` / `getByLabelText` / `getByText`, or carry a comment naming the missing semantic that forced a selector fallback.</Expected>
+    </Hook>
+    <Hook id="HOOK_SVELTE_TEST_HAS_CLEANUP">
+      <Purpose>Every `.svelte.test.ts` either enables auto-cleanup in config or registers `afterEach(() => cleanup())`.</Purpose>
+      <Command>find . -name '*.svelte.test.ts' -not -path '*/node_modules/*' -print0 | xargs -0 grep -LE "cleanup\(\)|globals:\s*true.*cleanup" || true</Command>
+      <Expected>Empty output (every file has cleanup). Matches indicate files without cleanup wiring; reconcile with `vitest.config.ts` if auto-cleanup is enabled project-wide.</Expected>
+    </Hook>
+  </Verification_Hooks>
+
+  <Reward_Criteria>
+    ✅ Test files use the `.svelte.test.ts` extension; `.test.ts` is reserved for non-Svelte tests.
+    ✅ Components mount via `@testing-library/svelte` `render()`; cleanup paired (explicit `afterEach` or auto-cleanup).
+    ✅ State mutation followed by `flushSync()` before any DOM assertion.
+    ✅ `$effect` outside a component runs inside `$effect.root` with explicit disposal.
+    ✅ Role-based queries (`getByRole`, `getByLabelText`, `getByPlaceholderText`) are the default; text queries are secondary.
+    ✅ Story-level tests preferred when a Storybook integration exists and a natural story counterpart is available.
+    ✅ Inherited Vitest rules honoured: unified context per file, no `vi.mock` without operator confirm, no auto snapshot updates, file-size budget, explicit imports from `vitest`.
+
+    ❌ Component imports inside a plain `.test.ts` file.
+    ❌ Assertion immediately after a mutation with no `flushSync()`.
+    ❌ `$effect` used outside a component context without `$effect.root` and disposal.
+    ❌ Component mounted without paired cleanup.
+    ❌ `container.querySelector` / `document.getElementById` as the default DOM query.
+    ❌ Manual `render()` in a project that already maintains a story counterpart for the scenario.
+    ❌ Any inherited Vitest rule relaxed (mock without confirm, hidden snapshot update, oversized file, etc.).
+  </Reward_Criteria>
+</SvelteTestingRules>