gennady 0.6.0 → 0.7.0

package/dist/ai/directives/infra/storybook-setup.xml

@@ -0,0 +1,153 @@
+<StorybookSetupRules keywords="storybook, setup, mcp, agentic-init, install, addon-test, agents-md" type="infra-rules" ver="2.0">
+  <Mission>
+    Define how an execution-agent installs and configures Storybook for an agent-first project. The agent runs the official initializer, follows its generated guidance, installs the MCP/test addon set, registers the MCP server with the agent runner, and updates `AGENTS.md` so the integration is discoverable without chat context.
+
+    **Base axiom:** Storybook's value for an agentic project is mechanical — preview URL + MCP tools + run-story-tests. If any one of those three is missing, the integration is not «partially working»; it is broken in a way that silently fails later. The setup directive optimises for «all three present and verified» on first installation, not for fast partial scaffolds.
+
+    Companion (runtime usage after setup): `ai/directives/testing/storybook-usage.xml`.
+  </Mission>
+
+  <Belief_State>
+    <Axiom id="AX_SB_INIT_VIA_OFFICIAL_INSTALLER">
+      Storybook installation starts with the official initializer (`npx storybook@latest init`). Manually scaffolding `.storybook/main.*`, `.storybook/preview.*`, or hand-editing build config before running `init` is forbidden — the initializer is the source of truth for the framework detection, plugin set, and TS configuration that the project's framework currently requires.
+
+      The init is interactive: when it prompts about framework, builder, or feature opt-ins, the agent answers based on observed project state (existing `vite.config.*`, `package.json` scripts, framework deps), not on assumptions.
+    </Axiom>
+
+    <Axiom id="AX_SB_FOLLOW_GENERATED_GUIDE">
+      After `init` completes, the generated setup notes (`storybook` CLI output + any `.storybook/` README or onboarding file) are normative. The agent does NOT improvise alternative configuration, alternative entry points, or alternative scripts; it follows the generated guide and only deviates with explicit operator confirmation. Drift between the installer's intent and the project's actual config is the most common source of «Storybook used to work» tickets.
+    </Axiom>
+
+    <Axiom id="AX_SB_MCP_IS_MANDATORY">
+      For an agent-first project, the MCP integration (test/preview addon exposing tools the agent runner can call) is NOT optional. Without MCP, the agent cannot fetch component docs, preview stories, or run story tests programmatically — Storybook becomes a human-only GUI tool and loses its value in the workflow.
+
+      Setup is incomplete until the MCP addon is installed AND the MCP server is registered with the agent runner AND at least one MCP tool call returns a non-error response.
+    </Axiom>
+
+    <Axiom id="AX_SB_AGENTS_MD_UPDATED_AS_PART_OF_SETUP">
+      Setup ends with an `AGENTS.md` update making the integration discoverable: which MCP tools exist, story-file conventions adopted, tags reserved (e.g. `ai-generated`), pointer to the runtime usage directive. Skipping the `AGENTS.md` step turns the integration into tribal knowledge — every later agent must rediscover it from scratch.
+    </Axiom>
+
+    <Axiom id="AX_SB_VERIFY_BEFORE_HANDOFF">
+      Setup is verified end-to-end before being declared complete:
+      1. `storybook dev` boots without errors and serves the preview URL.
+      2. At least one MCP tool call to the registered server succeeds.
+      3. `run-story-tests` (or the project's equivalent) passes on at least one story.
+
+      Any of the three failing → setup is not done; the failure is surfaced to the operator with the exact error rather than masked as «mostly working».
+    </Axiom>
+
+    <Axiom id="AX_SB_BROWSER_PREREQ_HANDLED">
+      Story tests run in a real browser (typically Chromium via Playwright). If the project does not already install Playwright browsers, the setup MUST add the install step (`npx playwright install chromium`, or the framework's equivalent) and verify the browser is available before declaring done. A missing browser turns the first story-test run into a confusing failure.
+    </Axiom>
+
+    <Axiom id="AX_SB_NO_PARALLEL_TEST_HARNESSES">
+      Story-level tests use ONE harness — the test addon shipped/recommended with Storybook for the project's framework. Introducing a parallel harness (e.g., a custom Vitest project that mounts stories outside the addon) fragments the project's testing surface and creates two report channels for the same component contract. If the project already has a chosen Storybook test addon, the agent reuses it; if not, the agent installs the official one and stops there.
+    </Axiom>
+  </Belief_State>
+
+  <Definitions>
+    <Definition id="DEF_SB_MCP_SERVER">
+      An MCP-compliant server exposing Storybook capabilities (documentation retrieval, story preview, story-test execution) to an agent runner. Realised by the Storybook test/MCP addon plus runner-side registration.
+    </Definition>
+    <Definition id="DEF_SB_TEST_ADDON">
+      The Storybook addon that provides programmatic story execution and assertions (current canonical: `@storybook/experimental-addon-test` family or its successor). Used by both human-side test runs and the MCP server.
+    </Definition>
+  </Definitions>
+
+  <Setup_Steps>
+    <Step id="STEP_SB_1_RUN_INIT">
+      Run `npx storybook@latest init` and answer prompts based on observed project structure. Do NOT pre-scaffold `.storybook/` before this step.
+      Ref: AX_SB_INIT_VIA_OFFICIAL_INSTALLER.
+    </Step>
+    <Step id="STEP_SB_2_APPLY_GENERATED_GUIDE">
+      Apply every manual step in the initializer's generated guide / onboarding doc verbatim. Surface deviations to the operator before applying them.
+      Ref: AX_SB_FOLLOW_GENERATED_GUIDE.
+    </Step>
+    <Step id="STEP_SB_3_INSTALL_TEST_ADDON">
+      Install the Storybook test/MCP addon recommended for the framework: `npx storybook add @storybook/experimental-addon-test` (or its current canonical successor). Confirm the addon appears in `package.json` and in `.storybook/main.*` addons array.
+      Ref: AX_SB_MCP_IS_MANDATORY, AX_SB_NO_PARALLEL_TEST_HARNESSES.
+    </Step>
+    <Step id="STEP_SB_4_INSTALL_BROWSER">
+      If a story-test browser is not already installed, run `npx playwright install chromium` (or the project's equivalent install step) and verify availability.
+      Ref: AX_SB_BROWSER_PREREQ_HANDLED.
+    </Step>
+    <Step id="STEP_SB_5_REGISTER_MCP_SERVER">
+      Register the Storybook MCP server in the agent runner's MCP configuration (command, args, env). Restart / reload the runner if it requires it.
+      Ref: AX_SB_MCP_IS_MANDATORY.
+    </Step>
+    <Step id="STEP_SB_6_VERIFY_END_TO_END">
+      Boot `storybook dev`, confirm preview URL responds; make at least one MCP tool call; run `run-story-tests` on one story. All three must succeed.
+      Ref: AX_SB_VERIFY_BEFORE_HANDOFF.
+    </Step>
+    <Step id="STEP_SB_7_UPDATE_AGENTS_MD">
+      Add a Storybook section to `AGENTS.md`: MCP tools available, story-file conventions (`*.stories.ts` location, naming), reserved tags (`ai-generated`), pointer to `testing/storybook-usage.xml`.
+      Ref: AX_SB_AGENTS_MD_UPDATED_AS_PART_OF_SETUP.
+    </Step>
+  </Setup_Steps>
+
+  <Anti_Patterns>
+    <Anti_Pattern id="AP_SB_MANUAL_SCAFFOLD_BEFORE_INIT">
+      <Bad>Agent hand-creates `.storybook/main.ts` with a guess at the framework integration, copies a preset from another project, and runs `storybook dev` to «see if it works».</Bad>
+      <Why_Bad>Bypasses the official initializer (`AX_SB_INIT_VIA_OFFICIAL_INSTALLER`). The initializer's framework detection is the single source of truth for the current Storybook version's expected config; a hand-rolled main file drifts from it on the first minor upgrade and produces opaque «works on the laptop, fails in CI» symptoms.</Why_Bad>
+      <Good>Delete the hand-rolled `.storybook/`, run `npx storybook@latest init`, answer prompts based on observed project state, then follow the generated guide verbatim.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SB_NO_MCP_INTEGRATION">
+      <Bad>Agent installs base Storybook, gets `storybook dev` running, and marks the ticket done without installing the test/MCP addon or registering the MCP server.</Bad>
+      <Why_Bad>Storybook present but unreachable by agents (`AX_SB_MCP_IS_MANDATORY`). Every subsequent component task must either rediscover props from source code or fall back to human-driven preview. The integration is structurally incomplete; calling it «done» misrepresents project state.</Why_Bad>
+      <Good>Install the recommended test/MCP addon (`STEP_SB_3_INSTALL_TEST_ADDON`), register the MCP server with the agent runner (`STEP_SB_5_REGISTER_MCP_SERVER`), and verify at least one MCP tool call returns a non-error response.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SB_VERIFY_SKIPPED">
+      <Bad>Agent finishes the install steps and reports «Storybook configured» based solely on `npm install` exit code, without booting `storybook dev` or running any story test.</Bad>
+      <Why_Bad>Setup declared complete without end-to-end verification (`AX_SB_VERIFY_BEFORE_HANDOFF`). Misses Playwright browser missing, MCP server not registered, addon misconfigured, port conflict — all of which compile fine but break the first real use.</Why_Bad>
+      <Good>Boot `storybook dev` and confirm preview URL responds; call one MCP tool; run `run-story-tests` on one story. If any fails, surface the exact error to the operator before marking the ticket complete.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SB_AGENTS_MD_SKIPPED">
+      <Bad>Setup verified end-to-end, but `AGENTS.md` not updated — no mention of Storybook tooling, MCP tools, or story conventions.</Bad>
+      <Why_Bad>Integration becomes tribal knowledge (`AX_SB_AGENTS_MD_UPDATED_AS_PART_OF_SETUP`). Next agent on the project must rediscover the entire integration from chat history or trial-and-error. Defeats the «discoverable without chat context» principle that justifies `AGENTS.md` in the first place.</Why_Bad>
+      <Good>Append a Storybook section to `AGENTS.md`: MCP tool names, story-file location and naming conventions, reserved tags (e.g. `ai-generated`), pointer to `testing/storybook-usage.xml`.</Good>
+    </Anti_Pattern>
+  </Anti_Patterns>
+
+  <Verification_Hooks>
+    <Hook id="HOOK_SB_PREVIEW_BOOTS">
+      <Purpose>Storybook dev server boots without errors and serves the preview.</Purpose>
+      <Command>npx storybook dev --ci --quiet &amp; PID=$!; sleep 8; curl -fsS http://localhost:6006/index.json > /dev/null; STATUS=$?; kill $PID 2>/dev/null; wait $PID 2>/dev/null; exit $STATUS</Command>
+      <Expected>Exit 0. Non-zero indicates the preview did not boot within the timeout or the index endpoint is unreachable.</Expected>
+    </Hook>
+    <Hook id="HOOK_SB_ADDON_PRESENT">
+      <Purpose>Test/MCP addon is listed in Storybook config.</Purpose>
+      <Command>find .storybook -maxdepth 2 -type f \( -name 'main.ts' -o -name 'main.js' -o -name 'main.mts' \) -print0 | xargs -0 grep -nE 'addon-test|addon-mcp' || true</Command>
+      <Expected>At least one match. Empty output means the addon is not registered in `.storybook/main.*`.</Expected>
+    </Hook>
+    <Hook id="HOOK_SB_AGENTS_MD_MENTIONS_STORYBOOK">
+      <Purpose>`AGENTS.md` mentions Storybook so the integration is discoverable.</Purpose>
+      <Command>test -f AGENTS.md &amp;&amp; grep -nE 'Storybook|storybook' AGENTS.md || echo MISSING</Command>
+      <Expected>At least one match in `AGENTS.md`. `MISSING` (file absent) or empty output is a setup gap.</Expected>
+    </Hook>
+    <Hook id="HOOK_SB_PLAYWRIGHT_BROWSER_PRESENT">
+      <Purpose>Chromium is installed for story tests.</Purpose>
+      <Command>npx playwright install --dry-run chromium 2>&amp;1 | grep -E "browser is already installed|is downloaded" || echo MISSING</Command>
+      <Expected>Output indicates Chromium is already installed. `MISSING` means the browser still needs `npx playwright install chromium`.</Expected>
+    </Hook>
+  </Verification_Hooks>
+
+  <Reward_Criteria>
+    ✅ Storybook installed via the official initializer; generated guide applied verbatim.
+    ✅ Test/MCP addon installed and present in `.storybook/main.*`.
+    ✅ MCP server registered in the agent runner; at least one MCP tool call succeeds.
+    ✅ Required browser (Chromium / equivalent) installed before story-test runs.
+    ✅ End-to-end verification: `storybook dev` boots, MCP tool call returns, `run-story-tests` passes on one story.
+    ✅ `AGENTS.md` updated with Storybook section: MCP tools, story conventions, reserved tags, pointer to `testing/storybook-usage.xml`.
+
+    ❌ Hand-scaffolded `.storybook/` config bypassing the initializer.
+    ❌ Storybook installed without the test/MCP addon.
+    ❌ MCP server not registered with the agent runner.
+    ❌ Setup declared done without booting `storybook dev` or running a story test.
+    ❌ `AGENTS.md` not updated; integration left as tribal knowledge.
+    ❌ Parallel story-test harness introduced alongside the official addon.
+  </Reward_Criteria>
+</StorybookSetupRules>

package/dist/ai/directives/knowledge.xml

@@ -0,0 +1,206 @@
+<AiKnowledge ver="2.0">
+  <Directives>
+    <Sdd>
+      <SddSetup>
+        <File>ai/directives/sdd/setup.directive.xml</File>
+        <Purpose>Creates or updates specs/README.md — Vision and Scope Graph. Sole owner of the Portal. Idempotent.</Purpose>
+        <Triggers>new project · add scope · change project vision · register scope after discovery</Triggers>
+        <SkipWhen>designing a specific scope · module decomposition · task scaffolding</SkipWhen>
+        <Preconditions>None</Preconditions>
+      </SddSetup>
+      <SddDiscovery>
+        <File>ai/directives/sdd/discovery.directive.xml</File>
+        <Purpose>Scope-level discovery session. Creates or evolves specs/[scope]/[scope].spec.md. Branches by scope-type: infrastructure, contracts, library, product.</Purpose>
+        <Triggers>design scope · raw idea for service/SDK/CLI/app · bootstrap infra tooling · refine or pivot existing scope</Triggers>
+        <SkipWhen>approved spec exists and operator wants module decomposition · bug fix or local refactor · project-level vision change</SkipWhen>
+        <Preconditions>greenfield: none. refine/pivot: specs/[scope]/[scope].spec.md exists</Preconditions>
+      </SddDiscovery>
+      <SddModuleDecomposition>
+        <File>ai/directives/sdd/module-decomposition.directive.xml</File>
+        <Purpose>Decomposes a product or library scope into module specs with closed-world entity inventory, public surfaces, DbC contracts (Ports / Adapters / Services).</Purpose>
+        <Triggers>discovery complete · split into modules · build module map · list all entities · produce DbC · Ports and Adapters</Triggers>
+        <SkipWhen>scope spec missing or not approved · discovery still open · scope-type is infrastructure or contracts · tasks already generated</SkipWhen>
+        <Preconditions>specs/[scope]/[scope].spec.md with scope-type=product or library</Preconditions>
+      </SddModuleDecomposition>
+      <SddTaskScaffolding>
+        <File>ai/directives/sdd/task-scaffolding.directive.xml</File>
+        <Purpose>Builds DAG of compact task tickets from scope graph. Each ticket includes BDD, Effective Rules, Verification, Execution Log template.</Purpose>
+        <Triggers>all scope specs ready · break into tasks · build DAG · produce execution plan · scaffold tickets</Triggers>
+        <SkipWhen>module specs lack contracts · discovery or module-decomp not closed · tasks already generated</SkipWhen>
+        <Preconditions>specs/README.md Scope Graph ✅; coding rule files exist for each language</Preconditions>
+      </SddTaskScaffolding>
+      <SddPhaseExecution>
+        <File>ai/directives/sdd/phase-execution-protocol.xml</File>
+        <Purpose>Execute ONE phase of ONE task ticket, dispatched by sdd-execute orchestrator. Read only what the phase needs; write only Target Files; emit typed Handoff for next phase / audit.</Purpose>
+        <Triggers>orchestrator dispatches phase · phase ID + ticket path provided in prompt</Triggers>
+        <SkipWhen>operator invokes directly without orchestrator · no phase ID</SkipWhen>
+        <Preconditions>ticket has section 2 Phases Overview + section 3 Phases block for target phase ID; prior-phase Handoffs (if any) recorded in current Round</Preconditions>
+      </SddPhaseExecution>
+      <SddAudit>
+        <File>ai/directives/sdd/audit.directive.xml</File>
+        <Purpose>Post-execution verification. Compares spec ↔ ticket ↔ code. Detects drift, gaps, rules violations. Output: ephemeral findings routed to spec/ticket.</Purpose>
+        <Triggers>audit · drift detection · post-implementation review · verify implementation · end of epic before merge</Triggers>
+        <SkipWhen>no executed tasks · Execution Log empty · no spec to compare</SkipWhen>
+        <Preconditions>spec exists; ticket with non-empty Execution Log; code committed</Preconditions>
+      </SddAudit>
+    </Sdd>
+  </Directives>
+  <Rules>
+    <CheckPhaseOrder>typecheck test lint format</CheckPhaseOrder>
+
+    <Coding>
+      <Rule id="result-conventions">
+        <File>ai/directives/coding/result-conventions.xml</File>
+        <Purpose>ESLint enforcement of Result pattern conventions: no second generic, no object literals, no isErr short-circuit, no bare throw unknown.</Purpose>
+        <Triggers>Target Files use Result from @tessell/core/result · task touches error-handling code · task adds new DML / service methods</Triggers>
+        <SkipWhen>Config-only task; no Result usage in target files</SkipWhen>
+        <ActivationHint>Before writing or reviewing any file that returns or propagates Result</ActivationHint>
+        <CheckPhase>lint</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+      </Rule>
+      <Rule id="typescript-rules">
+        <File>ai/directives/coding/typescript-rules.xml</File>
+        <Purpose>Writing code in the chosen language: typing, DbC, patterns, anti-patterns.</Purpose>
+        <Triggers>Target Files include source code files (not config)</Triggers>
+        <SkipWhen>Config-only task; infra-setup task without code files</SkipWhen>
+        <ActivationHint>Before editing or creating any source code file</ActivationHint>
+        <CheckPhase>typecheck</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+      </Rule>
+      <Rule id="svelte5-runes">
+        <File>ai/directives/coding/svelte5-runes.xml</File>
+        <Purpose>Writing Svelte 5 components with runes ($state, $derived, $effect, $props, $bindable). Inherits typescript-rules; adds Svelte-specific reactivity, template syntax, component structure. Prevents React-pattern code in .svelte files.</Purpose>
+        <Triggers>creating .svelte file · writing Svelte component · using runes · .svelte.ts module</Triggers>
+        <SkipWhen>pure TypeScript without Svelte · React/Vue project · backend server code</SkipWhen>
+        <ActivationHint>Before editing or creating any .svelte, .svelte.ts, or .svelte.js file. Inherits from typescript-rules — read both.</ActivationHint>
+        <CheckPhase>typecheck</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+        <CrossRef id="typescript-rules">Parent directive: inherits all TypeScript rules for language baseline.</CrossRef>
+        <CrossRef id="sveltekit-rules">SvelteKit projects also activate sveltekit-rules (inherits from this directive).</CrossRef>
+      </Rule>
+      <Rule id="sveltekit-rules">
+        <File>ai/directives/coding/sveltekit-rules.xml</File>
+        <Purpose>Writing SvelteKit applications: file-based routing (+page, +layout, +server), server load functions, form actions, hooks, adapters, $app modules. Inherits svelte5-runes + typescript-rules transitively.</Purpose>
+        <Triggers>creating SvelteKit route · load function · form actions · hooks.server.ts · server/client boundary</Triggers>
+        <SkipWhen>standalone Svelte without SvelteKit · pure component library · non-SvelteKit project</SkipWhen>
+        <ActivationHint>Before writing SvelteKit route files or server logic. Inherits from svelte5-runes — read both.</ActivationHint>
+        <CheckPhase>typecheck</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+        <CrossRef id="svelte5-runes">Parent directive: inherits all Svelte 5 runes rules.</CrossRef>
+        <CrossRef id="typescript-rules">Transitive parent: inherits TypeScript rules through svelte5-runes.</CrossRef>
+      </Rule>
+    </Coding>
+    <Testing>
+      <Rule id="testing-common">
+        <File>ai/directives/testing/common.xml</File>
+        <Purpose>Shared testing core inherited by every runner-specific directive: contract boundary, case flow, phase anchors, unified context + factory, BDD mapping, snapshot operator-confirm, file budget.</Purpose>
+        <Triggers>any runner-specific testing rule activates</Triggers>
+        <SkipWhen>no test files in scope</SkipWhen>
+        <ActivationHint>Auto-read whenever node-test or vitest-rules activates. Runner-specific files only state deltas.</ActivationHint>
+        <CheckPhase>test</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+      </Rule>
+      <Rule id="vitest-rules">
+        <File>ai/directives/testing/vitest-rules.xml</File>
+        <Purpose>Writing tests on Vitest runner.</Purpose>
+        <Triggers>Target Test Files present AND stack uses Vitest</Triggers>
+        <SkipWhen>Stack uses a different test runner; no test files in scope</SkipWhen>
+        <ActivationHint>Before writing or modifying test files. Inherits testing-common.</ActivationHint>
+        <CheckPhase>test</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+        <CrossRef id="testing-common">Parent directive: read first for case flow, anchors, unified context, BDD mapping.</CrossRef>
+      </Rule>
+      <Rule id="node-test">
+        <File>ai/directives/testing/node-test.xml</File>
+        <Purpose>Writing tests on node:test runner.</Purpose>
+        <Triggers>Target Test Files present AND stack uses node:test</Triggers>
+        <SkipWhen>Stack uses a different test runner; no test files in scope</SkipWhen>
+        <ActivationHint>Before writing or modifying test files. Inherits testing-common.</ActivationHint>
+        <CheckPhase>test</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+        <CrossRef id="testing-common">Parent directive: read first for case flow, anchors, unified context, BDD mapping.</CrossRef>
+      </Rule>
+      <Rule id="playwright-cli">
+        <File>ai/directives/testing/playwright-cli.xml</File>
+        <Purpose>Exploring web apps through Playwright CLI: AX Tree vision, aria snapshots, screenshots, trace viewer, codegen. Gives the agent eyes and hands for browser exploration.</Purpose>
+        <Triggers>developing UI component · building a page · verifying visual layout · debugging failing e2e test · capturing aria snapshots</Triggers>
+        <SkipWhen>pure backend logic · CLI command implementation · API endpoint without UI</SkipWhen>
+        <ActivationHint>BEFORE writing any e2e test — explore the page first. Also when an e2e test fails and the agent needs to see what rendered.</ActivationHint>
+        <CheckPhase>test</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+        <CrossRef id="playwright-e2e">Transition to playwright-e2e when exploration complete.</CrossRef>
+      </Rule>
+      <Rule id="playwright-e2e">
+        <File>ai/directives/testing/playwright-e2e.xml</File>
+        <Purpose>Writing Playwright E2E tests: aria-snapshot-first contracts, role-based locators, fixture-based POM, auth via storageState, network mocking.</Purpose>
+        <Triggers>writing e2e test · creating browser test · adding Playwright spec · testing user flow</Triggers>
+        <SkipWhen>unit test · integration test without browser · exploration not done (use playwright-cli first)</SkipWhen>
+        <ActivationHint>AFTER playwright-cli exploration. Before writing Playwright spec files.</ActivationHint>
+        <CheckPhase>test</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+        <CrossRef id="playwright-cli">MUST run playwright-cli exploration first.</CrossRef>
+      </Rule>
+      <Rule id="storybook-usage">
+        <File>ai/directives/testing/storybook-usage.xml</File>
+        <Purpose>Using Storybook MCP tools: reading manifests (component docs, props, stories), writing stories, running tests, self-verifying component rendering.</Purpose>
+        <Triggers>developing UI component · using design system · creating story · fixing component bug · verifying component renders</Triggers>
+        <SkipWhen>pure backend/CLI logic · no Storybook · MCP not installed (use storybook-setup first)</SkipWhen>
+        <ActivationHint>Whenever working with UI components — BEFORE writing code, call MCP tools to check documented props.</ActivationHint>
+        <CheckPhase>test</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+        <CrossRef id="storybook-setup">MUST have Storybook + MCP running. If unreachable, invoke storybook-setup.</CrossRef>
+      </Rule>
+      <Rule id="svelte-testing">
+        <File>ai/directives/testing/svelte-testing.xml</File>
+        <Purpose>Testing Svelte 5 components: .svelte.test.ts extension, $effect.root isolation, flushSync for DOM, mount/unmount, @testing-library/svelte. Inherits node-test + vitest-rules.</Purpose>
+        <Triggers>writing Svelte component test · testing runes · mounting Svelte component · Storybook interaction test for Svelte</Triggers>
+        <SkipWhen>pure TS logic test without runes · E2E test with Playwright · non-Svelte project</SkipWhen>
+        <ActivationHint>Before writing .svelte.test.ts. Inherits from node-test.xml and vitest-rules.xml.</ActivationHint>
+        <CheckPhase>test</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+        <CrossRef id="node-test">Inherits general testing rules (phase anchors, learning briefs, contract coverage).</CrossRef>
+        <CrossRef id="vitest-rules">Inherits Vitest-specific rules (unified context, mock discipline).</CrossRef>
+        <CrossRef id="svelte5-runes">Runes knowledge required (.svelte.test.ts, $effect.root, flushSync).</CrossRef>
+      </Rule>
+    </Testing>
+    <Infra>
+      <Rule id="eslint-setup">
+        <File>ai/directives/infra/eslint-setup.xml</File>
+        <Purpose>Configuring a linter: severity policy, autofix, config format, formatter integration.</Purpose>
+        <Triggers>Task configures linter · installs linter · sets lint rules</Triggers>
+        <SkipWhen>Coding/testing task that only RUNS lint, does not configure it</SkipWhen>
+        <ActivationHint>Before writing linter config or modifying lint rules</ActivationHint>
+        <CheckPhase>lint</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+      </Rule>
+      <Rule id="git-setup">
+        <File>ai/directives/infra/git-setup.xml</File>
+        <Purpose>Configuring VCS: ignore baseline, branches, commits, hooks, secrets discipline.</Purpose>
+        <Triggers>Task bootstraps repo · configures VCS ignore file · sets up hooks · commit convention</Triggers>
+        <SkipWhen>Task only commits code changes (does not configure VCS itself)</SkipWhen>
+        <ActivationHint>Before writing VCS ignore file or configuring hooks</ActivationHint>
+        <CheckPhase></CheckPhase>
+        <RequiresVerification></RequiresVerification>
+      </Rule>
+      <Rule id="nodejs-npm-setup">
+        <File>ai/directives/infra/nodejs-npm-setup.xml</File>
+        <Purpose>Runtime + package manager setup: version pinning, single package manager, module system, mandatory check script.</Purpose>
+        <Triggers>Task writes package manager manifest · runtime version file · sets engines · chooses package manager</Triggers>
+        <SkipWhen>Task does not touch package manager manifest or runtime config</SkipWhen>
+        <ActivationHint>Before writing package manager manifest or runtime version file</ActivationHint>
+        <CheckPhase></CheckPhase>
+        <RequiresVerification></RequiresVerification>
+      </Rule>
+      <Rule id="storybook-setup">
+        <File>ai/directives/infra/storybook-setup.xml</File>
+        <Purpose>Installing Storybook + MCP server: agentic init, MCP addon, Vitest addon, agent registration, AGENTS.md update. Bootstraps component development environment.</Purpose>
+        <Triggers>install Storybook · add Storybook to project · configure MCP server · bootstrap UI toolchain</Triggers>
+        <SkipWhen>no UI components · Storybook already installed + MCP confirmed running</SkipWhen>
+        <ActivationHint>When project needs Storybook for first time. Follow agentic init: npx storybook@latest init.</ActivationHint>
+        <CheckPhase>test</CheckPhase>
+        <RequiresVerification>check-command</RequiresVerification>
+        <CrossRef id="storybook-usage">After setup (MCP running, manifest accessible), transition to storybook-usage.</CrossRef>
+      </Rule>
+    </Infra>
+  </Rules>
+</AiKnowledge>

package/dist/ai/directives/perf-auditor/perf-auditor.directive.xml

@@ -0,0 +1,75 @@
+<PerfAuditor keywords="performance, audit, optimization, cpu, memory, latency, event_lag, fps, gc, oom" type="directive" ver="2.0">
+  <Mission>
+    Автономный ИИ-аудитор производительности. Сканирует код, находит узкие места, **сам подгружает соответствующие Rulebooks** для проверки гипотез, верифицирует safety рефакторинга и выдаёт инструкции для DevAgent.
+
+    **Target hardware:** Mid-range Mobile/Desktop, 4–8 GB RAM. Фокус: снижение GC pauses, устранение O(n²), контроль Event Loop и backpressure. **Без изменения бизнес-логики.**
+  </Mission>
+
+  <Belief_State>
+    <Axiom id="AX_AUTONOMOUS_RESEARCH">Не делаешь выводов «из головы». Обнаружив паттерн, ОБЯЗАН открыть соответствующий Rulebook из `<Knowledge_Base_Index>`, изучить его правила/tradeoff/guardrails, и только потом принимать решение.</Axiom>
+    <Axiom id="AX_NO_CODE_GENERATION">Не пишешь код. Финальный артефакт — набор семантически привязанных инструкций для DevAgent.</Axiom>
+    <Axiom id="AX_SEMANTIC_SAFETY">Если применение правила может изменить поведение (порядок элементов, обработка ошибок, мутабельность) и не можешь доказать обратное → отклони как False Positive.</Axiom>
+    <Axiom id="AX_TARGET_HARDWARE">На 4–8 GB RAM аллокация объектов важнее микро-CPU-оптимизаций. Избегай промежуточных массивов и утечек памяти.</Axiom>
+  </Belief_State>
+
+  <Input_Contract>
+    **Принимается:** TS/JS файлы; папки/модули/diff/набор файлов на аудит; контекст (hot path, latency-жалобы, event-loop lag, memory spikes, OOM, FPS drops).
+
+    **Scope rules:**
+    - Diff передан → приоритет изменённым участкам; соседний код только для доказательства safety.
+    - Файл/папка без hot-path-маркера → определи участки с performance-impact: циклы, коллекции, I/O, async orchestration, caching, listeners, timers.
+    - Не аудируешь бизнес-логику. Только performance-risk и refactoring safety.
+    - Не предлагай оптимизации ради микро-выигрыша без видимого latency/memory benefit на target hardware.
+
+    **Исключено:** generated code, fixtures, snapshots, vendor artifacts, тестовые helper'ы — если оператор явно не указал их источником проблемы. Не предлагай rewriting архитектуры, если локальная оптимизация решает.
+  </Input_Contract>
+
+  <Knowledge_Base_Index>
+    Агент использует `Signals` чтобы понять, какой Rulebook грузить на Шаге 2.
+
+    <Rulebook file="./rules/data-structures.xml">
+      <Description>Array vs Set vs Map, TypedArrays, Queues.</Description>
+      <Signals>`.includes()` / `.indexOf()` в циклах; `{}` как словарь с динамическими ключами или частые `delete`; `array.shift()` / `unshift()` для очередей; математика над огромными числовыми массивами.</Signals>
+    </Rulebook>
+    <Rulebook file="./rules/memory-gc.xml">
+      <Description>Утечки памяти, GC pressure, замыкания, таймеры, DOM-ссылки.</Description>
+      <Signals>Глобальные переменные / кэши без очистки (LRU/TTL); `setInterval`, `addEventListener` без сохранения ссылок для очистки; `new RegExp` / `Intl.DateTimeFormat` внутри циклов; `...spread` / `.concat()` / `.slice()` в горячих циклах.</Signals>
+    </Rulebook>
+    <Rulebook file="./rules/async-latency.xml">
+      <Description>Concurrency, backpressure, Promise.all, Event Loop blocks.</Description>
+      <Signals>`await` в `for`/`while` (последовательное выполнение); `Promise.all` на массивах неизвестной/большой длины; `fs.readFile` целиком или потоки без `drain`/`pause`; fetch без `AbortController`; рекурсивные retry без exponential backoff.</Signals>
+    </Rulebook>
+    <Rulebook file="./rules/iteration-fusion.xml">
+      <Description>Слияние циклов (fusion), early exit, избегание промежуточных аллокаций.</Description>
+      <Signals>Цепочки `.filter(...).map(...)` или `.map(...).flat()`; `.filter(...)[0]` / `.filter(...).length > 0`; результат `.map()`/`.filter()` не используется; `forEach` с `return` для early exit.</Signals>
+    </Rulebook>
+  </Knowledge_Base_Index>
+
+  <Execution_Plan>
+    <Step id="1_INITIAL_SCAN">Анализ кода. Сопоставь структуру с `<Signals>` в `<Knowledge_Base_Index>`. Составь список подозрений (Code Smells).</Step>
+    <Step id="2_LOAD_RULEBOOKS">Открой и прочитай ТОЛЬКО релевантные Rulebooks. Порядок попыток: 1) прямое чтение файла по `file=`, 2) tool/read_file по этому пути, 3) fallback на эквивалентный локальный file-fetch. Не ссылайся на Rulebook, который фактически не прочитал в этом запуске.</Step>
+    <Step id="3_DEEP_VERIFICATION">Для каждого подозрения: проверь по релевантным секциям Rulebook (`Performance_Mechanism`, `Safety_Guardrails`, `Directive_Template` или эквивалентам). Явно проверь premature optimization / false positive по guardrails. Докажи семантическую safety («`filter()[0]` → `find()` безопасно: нужен только первый элемент»). Отбрось не прошедшие.</Step>
+    <Step id="4_REPORT_GENERATION">Сформируй `<Performance_Audit_Report>` для DevAgent — только верифицированные директивы.</Step>
+  </Execution_Plan>
+
+  <Output_Contract>
+    Финальный ответ содержит ТОЛЬКО `<Verification_Log>` и `<Performance_Audit_Report>` в этом порядке. Запрещено писать блоки кода с готовым решением — только семантические якоря и инструкции.
+
+    ```xml
+    <Verification_Log>
+      Краткий лог рассуждений Шага 3: что подтвердилось, что отброшено как False Positive и почему.
+      Если подтверждённых нарушений нет — всё равно заполни и явно перечисли отклонённые гипотезы.
+    </Verification_Log>
+
+    <Performance_Audit_Report>
+      <!-- Если нет подтверждённых нарушений — пустой отчёт с пометкой `No verified findings`. -->
+      <Finding rulebook_ref="[Rulebook name]">
+        <Location file="[Path]" semantic_anchor="[например: 'Внутри метода processData, цикл for-of по orders']" />
+        <Issue_Description>В чём проблема (со ссылкой на механизмы из Rulebook: O(n²), GC-аллокации, backpressure).</Issue_Description>
+        <Safety_Proof>Доказательство, что рефакторинг не сломает логику (по Guardrails из Rulebook).</Safety_Proof>
+        <Dev_Agent_Directive>Строгий приказ для DevAgent. Пример: «Извлеки массив X в `new Set()` до цикла. Внутри цикла замени `.includes` на `.has()`».</Dev_Agent_Directive>
+      </Finding>
+    </Performance_Audit_Report>
+    ```
+  </Output_Contract>
+</PerfAuditor>

package/dist/ai/directives/perf-auditor/rules/async-latency.xml

@@ -0,0 +1,101 @@
+<Rulebook id="rulebook_async_latency" type="knowledge_base">
+  <Primary_Goal>
+    Предоставить Аудитору критерии для выявления проблем с конкурентностью, отсутствием обратного давления (Backpressure), блокировками Event Loop и неэффективным управлением сетевыми/дисковыми ресурсами.
+  </Primary_Goal>
+  <Belief_State>
+    <Axiom id="AX_BACKPRESSURE_IS_LAW">Чтение данных быстрее, чем их может обработать потребитель, накапливает бесконечный буфер в RAM. Игнорирование Backpressure — это прямой путь к OOM на устройствах с 4-8 GB памяти.</Axiom>
+    <Axiom id="AX_CONCURRENCY_LIMITS">ОС и железо имеют лимиты на открытые сокеты и дескрипторы. Запуск неограниченного числа параллельных задач убивает систему быстрее, чем последовательное выполнение.</Axiom>
+    <Axiom id="AX_LATENCY_STACKING">Последовательный `await` независимых задач складывает их задержки (Latency). Параллельный запуск сводит общую задержку к самой медленной задаче.</Axiom>
+  </Belief_State>
+  <Rules_Registry>
+    <!-- ПРАВИЛО 1: Отсутствие контроля параллелизма -->
+    <Rule id="ASYNC_UNBOUNDED_PROMISE_ALL">
+      <Trigger_Signals>
+        - Вызов `Promise.all(arr.map(...))` или `Promise.allSettled(...)`, где `arr` — массив неизвестного или потенциально большого размера.
+      </Trigger_Signals>
+      <Performance_Mechanism>
+        Запуск тысяч промисов одновременно перегружает Event Loop, исчерпывает пул соединений (database/network meltdown) и вызывает пик потребления памяти (все ответы сохраняются в RAM одновременно).
+      </Performance_Mechanism>
+      <Safety_Guardrails>
+        <Guardrail condition="KNOWN_SMALL_ARRAY">Если размер массива жестко ограничен бизнес-логикой (например, `['user', 'admin'].map(...)`), игнорировать.</Guardrail>
+      </Safety_Guardrails>
+      <Directive_Template>
+        "Неограниченный параллелизм. Замени `Promise.all` на пакетную обработку (batching) через цикл `for` с нарезкой массива (например, по 10 элементов) или используй библиотеку контроля конкурентности (например, `p-limit`)."
+      </Directive_Template>
+    </Rule>
+    <!-- ПРАВИЛО 2: Лишняя последовательность (Sequential Await) -->
+    <Rule id="ASYNC_SEQUENTIAL_AWAIT">
+      <Trigger_Signals>
+        - Несколько операторов `await` идут подряд в одном блоке кода.
+        - Использование `await` внутри цикла `for...of` при вызове независимых API.
+      </Trigger_Signals>
+      <Performance_Mechanism>
+        Ожидание завершения первой задачи перед стартом второй удваивает время ответа (Latency) и заставляет CPU простаивать в ожидании I/O.
+      </Performance_Mechanism>
+      <Safety_Guardrails>
+        <Guardrail condition="DATA_DEPENDENCY">Если второй `await` использует результат первого (например, `const user = await getUser(); const posts = await getPosts(user.id);`), оптимизация невозможна. Отклонить.</Guardrail>
+        <Guardrail condition="ORDER_REQUIREMENT">Если важен строгий порядок выполнения на сервере (например, транзакции), отклонить.</Guardrail>
+      </Safety_Guardrails>
+      <Directive_Template>
+        "Последовательное выполнение независимых задач. Оберни эти вызовы в `Promise.all([...])` для параллельного выполнения и снижения Latency."
+      </Directive_Template>
+    </Rule>
+    <!-- ПРАВИЛО 3: Игнорирование Backpressure (Потоки) -->
+    <Rule id="ASYNC_NO_BACKPRESSURE">
+      <Trigger_Signals>
+        - Чтение файлов целиком: `fs.readFile`, `fs.promises.readFile`, `Buffer.concat()`.
+        - Чтение HTTP-ответов целиком: `await response.text()` или `.json()` для огромных payload.
+        - Использование `readable.on('data', chunk => writable.write(chunk))` без проверки возвращаемого значения `write()` и вызова `pause()`.
+      </Trigger_Signals>
+      <Performance_Mechanism>
+        Полная буферизация загружает весь объем данных в RAM. В Node.js это может увеличить потребление памяти с 50 MB до 1.5 GB. Потоки (Streams) с Backpressure держат в памяти только один чанк (chunk).
+      </Performance_Mechanism>
+      <Safety_Guardrails>
+        <Guardrail condition="SMALL_PAYLOAD">Если файл или ответ гарантированно мал (конфиги, мелкие JSON), `readFile` или `.json()` допустимы. Игнорировать.</Guardrail>
+      </Safety_Guardrails>
+      <Directive_Template>
+        "Игнорирование Backpressure. Замени чтение файла целиком на `fs.createReadStream` (или Web Streams). Для трансформации используй `stream.pipeline` или асинхронные итераторы `for await...of`."
+      </Directive_Template>
+    </Rule>
+    <!-- ПРАВИЛО 4: Утечки ресурсов при отмене (Missing Cancellation) -->
+    <Rule id="ASYNC_MISSING_CANCELLATION">
+      <Trigger_Signals>
+        - Вызовы `fetch()` без передачи `signal: AbortSignal`.
+        - Долгие асинхронные операции, которые не отменяются при размонтировании компонента или таймауте.
+      </Trigger_Signals>
+      <Performance_Mechanism>
+        Если пользователь ушел со страницы (или запрос отменен логикой), а `fetch` продолжает скачивать данные, это тратит трафик, батарею и CPU. Неотмененные промисы держат в памяти замыкания (Memory Leak).
+      </Performance_Mechanism>
+      <Safety_Guardrails>
+        <Guardrail condition="FIRE_AND_FORGET">Если запрос обязан завершиться на сервере в любом случае (например, отправка аналитики или логов), отмена не нужна. Игнорировать.</Guardrail>
+      </Safety_Guardrails>
+      <Directive_Template>
+        "Отсутствует механизм отмены. Создай `new AbortController()`, передай его `signal` в `fetch` и вызови `.abort()` в функции очистки (cleanup) или по таймауту."
+      </Directive_Template>
+    </Rule>
+    <!-- ПРАВИЛО 5: Шторм повторов и высокочастотные события (Retry Storm / Flooding) -->
+    <Rule id="ASYNC_HIGH_FREQUENCY_FLOOD">
+      <Trigger_Signals>
+        - `catch` блок внутри цикла с немедленным повторным вызовом `await` (retry без задержки).
+        - Подписки на события `scroll`, `mousemove`, `resize` без использования debounce/throttle.
+        - `setInterval` с очень коротким таймингом для поллинга сервера.
+      </Trigger_Signals>
+      <Performance_Mechanism>
+        Синхронные или высокочастотные ретраи при падении сервиса создают лавинообразную нагрузку (Retry Storm), окончательно убивая сервер. Обработка каждого пикселя скролла вызывает Layout Thrashing и роняет FPS до нуля.
+      </Performance_Mechanism>
+      <Safety_Guardrails>
+        <Guardrail condition="ANIMATION_FRAME">Если подписка идет через `requestAnimationFrame` для плавной отрисовки, throttle может испортить анимацию. Игнорировать.</Guardrail>
+      </Safety_Guardrails>
+      <Directive_Template>
+        "Высокочастотный флуд. Для поллинга/ретраев: добавь экспоненциальную задержку (Exponential Backoff). Для UI-событий: оберни обработчик в функцию `throttle` или `debounce`."
+      </Directive_Template>
+    </Rule>
+  </Rules_Registry>
+  <Verification_Protocol>
+    При получении сигнала от Оркестратора:
+    1. Найди `<Rule>`.
+    2. Жестко проверь `<Guardrail>`. В правиле `ASYNC_SEQUENTIAL_AWAIT` критически важно убедиться в ОТСУТСТВИИ зависимости данных между вызовами. Если есть малейшее подозрение на зависимость — отбрось триггер.
+    3. Зафиксируй логику в `<Verification_Log>`.
+    4. Сформируй приказ для DevAgent через `<Directive_Template>`.
+  </Verification_Protocol>
+</Rulebook>