gennady 0.6.0 → 0.7.0

package/ai/fw-draft/rules/dev/base/file-structure-rules.xml

@@ -0,0 +1,89 @@
+<!-- ai/framework/architecture/file_structure_rules.xml -->
+<File_Structure_Protocol id="CleanArchitecture_v1.1">
+    <Preamble>
+        Этот протокол определяет стандарт для организации файловой структуры любого проекта. Он основан на принципах Чистой Архитектуры (Ports & Adapters), что обеспечивает низкую связанность, высокую тестируемость и понятность кодовой базы.
+    </Preamble>
+    <Core_Philosophy>
+        <Rationale>
+            Код должен быть организован по бизнес-назначению, а не по техническому типу. Это позволяет любому разработчику (или другому AI-агенту) быстро понять, за что отвечает каждый компонент системы, и вносить изменения в одном месте, не затрагивая другие. Мы разделяем "что" делает система (домен, сервисы) от "как" она это делает (базы данных, фреймворки).
+        </Rationale>
+        <Directive>
+            Твоя задача — проектировать файловую структуру как набор независимых слоев с явными границами. Каждый файл и директория должны иметь единственную, четко определенную ответственность.
+        </Directive>
+    </Core_Philosophy>
+    <Layer_Definitions>
+        <Layer id="entities" directory_name="entities">
+            <Objective>Изолировать чистые, независимые сущности домена, типы данных и бизнес-ошибки.</Objective>
+            <Directive>
+                Каждый файл должен содержать одну логическую сущность или тесно связанную группу (например, `user_entity.py`, `order_errors.py`). Этот слой не должен иметь никаких зависимостей от других слоев.
+            </Directive>
+        </Layer>
+        <Layer id="ports" directory_name="ports">
+            <Objective>Определить контракты (интерфейсы) для взаимодействия с внешним миром без указания реализации.</Objective>
+            <Directive>
+                Здесь находятся только абстракции: интерфейсы репозиториев (`i_user_repository.py`), клиентов внешних API, систем уведомлений. Этот слой содержит только объявления, без кода реализации.
+            </Directive>
+            <Note>(Role in Ports & Adapters: Ports)</Note>
+        </Layer>
+        <Layer id="services" directory_name="services">
+            <Objective>Реализовать сценарии использования (use cases) и оркестрировать бизнес-логику.</Objective>
+            <Directive>
+                Сервисы зависят от абстракций (`ports`), а не от конкретных реализаций. Они оперируют доменными сущностями (`entities`). Имена файлов должны отражать бизнес-сценарий (`create_order_service.py`).
+            </Directive>
+        </Layer>
+        
+        <Layer id="infrastructure" directory_name="infrastructure">
+            <Objective>Предоставить конкретные реализации для исходящих портов и инкапсулировать все взаимодействия с внешним миром (сеть, файловая система, БД).</Objective>
+            <Directive>
+                Здесь находятся HTTP-клиенты, коннекторы к базам данных, реализации репозиториев (`gitlab_api_client.py`, `postgres_user_repository.py`). Этот код реализует интерфейсы из слоя `ports`.
+            </Directive>
+            <Note>(Role in Ports & Adapters: Driven Adapters)</Note>
+        </Layer>
+
+        <Layer id="interfaces" directory_name="interfaces">
+            <Objective>Определить точки входа в приложение (API-хендлеры, CLI-команды, обработчики событий).</Objective>
+            <Directive>
+                Этот слой является "переводчиком" внешних запросов в вызовы внутренних сервисов. Он отвечает за парсинг входящих данных, вызов соответствующего сервиса и форматирование ответа. Бизнес-логика здесь запрещена.
+            </Directive>
+            <Note>(Role in Ports & Adapters: Driving Adapters)</Note>
+        </Layer>
+        <Layer id="config" directory_name="config">
+            <Objective>Управлять конфигурацией приложения: сборка, валидация и предоставление доступа к настройкам.</Objective>
+            <Directive>
+                Этот слой использует `infrastructure` для чтения настроек из окружения или файлов и предоставляет типизированный, валидированный объект конфигурации для остальных частей приложения.
+            </Directive>
+        </Layer>
+    </Layer_Definitions>
+    <Scalability_And_Adoption>
+        <Rule id="MINIMAL_SET">
+            Для простых проектов обязательными являются только три слоя: `entities`, `services`, `infrastructure`. В этом случае сервисы могут напрямую зависеть от инфраструктуры.
+        </Rule>
+        <Rule id="WHEN_TO_ADD_PORTS">
+            Слой `ports` вводится тогда, когда появляется необходимость иметь несколько реализаций для одного контракта (например, для тестов (`in_memory_repository`) и для прода (`postgres_repository`)) или когда нужно строго отделить бизнес-логику от деталей реализации.
+        </Rule>
+    </Scalability_And_Adoption>
+    <Anti_Patterns_To_Avoid>
+        <Pattern id="MONOLITHIC_TYPES">
+            <Description>Создание общих файлов `types.py`, `models.py` или `schemas.py`, содержащих все типы данных проекта.</Description>
+            <Rationale>Это приводит к высокой связанности. Изменение одного типа требует модификации общего файла, затрагивая всю систему. Типы должны находиться в слое `entities` или рядом с модулем, который их использует.</Rationale>
+            <Directive>Распределяй определения данных по доменной принадлежности.</Directive>
+        </Pattern>
+        <Pattern id="DUMP_DIRECTORY">
+            <Description>Создание директории `utils` или `helpers` как "свалки" для всего, что не подошло в другие места.</Description>
+            <Rationale>Со временем такие директории становятся непредсказуемыми и сложными для навигации. Функция без побочных эффектов может остаться в `utils`, но если она работает с сетью или ФС, ее место — в `infrastructure`.</Rationale>
+            <Directive>Всегда классифицируй функцию по ее назначению и помещай в соответствующий слой.</Directive>
+        </Pattern>
+    </Anti_Patterns_To_Avoid>
+    <Testing_Strategy>
+        <Objective>Обеспечить четкое разделение исходного кода и тестов, сохраняя при этом понятную навигацию.</Objective>
+        <Directive>
+            Создай директорию для тестов (например, `tests/` или `__tests__/`) на том же уровне, что и директория с исходным кодом. Внутри этой директории **полностью воспроизведи (отзеркаль)** структуру исходников.
+        </Directive>
+        <Example>
+            Если есть файл `services/user/create_user.py`, то его тест должен находиться в `tests/services/user/test_create_user.py`.
+        </Example>
+        <Rationale>
+            Такой подход позволяет мгновенно находить тесты для любого модуля и сразу понимать, какой слой и компонент системы проверяется.
+        </Rationale>
+    </Testing_Strategy>
+</File_Structure_Protocol>

package/ai/fw-draft/rules/dev/typescript/contacts.xml

@@ -0,0 +1,194 @@
+<JSDOC_AS_CONTACTS hint="Правила оформления контактов в коде через JSDoc">
+  <Tag_Order>Строгий порядок в JSDoc: @purpose → @consumer → @invariant → @pre → @param → @throws → @returns → @post → @sideEffect</Tag_Order>
+  <TypeScript_Rules>
+    <Rule id="type_vs_interface">Для структур данных (объекты, DTO, ответы API, нормализованные модели) использовать type. interface — только для сущностей, которые наследуют или расширяют (несколько классов реализуют один контракт). Классы ошибок (extends Error) остаются class.</Rule>
+    <Rule id="naming_domain">Типы, относящиеся к внешней системе или домену (API, сервис), должны иметь префикс в имени (напр. ApiResource, ExternalServiceDto, VendorOrder). Внутренние утилитные типы без внешнего домена — без префикса.</Rule>
+  </TypeScript_Rules>
+  <TypeScript_Conventions hint="Node 22+, совместимость с декораторами">
+    <Convention id="no_enum">Не использовать enum. Вместо: const + as const или union type.</Convention>
+    <Convention id="no_constructor_modifiers">Не использовать модификаторы в конструкторе (public, private). Явное объявление полей в теле класса.</Convention>
+    <Convention id="no_private">Не использовать private / #private field. Вместо: protected _field с префиксом _.</Convention>
+    <Convention id="no_readonly_param">readonly — в объявлении поля, не в параметре конструктора.</Convention>
+  </TypeScript_Conventions>
+  <Tag_Dictionary hint="Полный реестр допустимых JSDoc-тегов для контрактов">
+    <Tag name="@purpose" type="mandatory">
+      <Definition>Телеологическое назначение. Зачем эта сущность существует в бизнес-логике?</Definition>
+      <Condition_Use>ВСЕГДА для любых экспортируемых (export) сущностей (классы, методы, типы, интерфейсы, константы).</Condition_Use>
+      <Format>@purpose {Глагол} {Объект} {Контекст}.</Format>
+    </Tag>
+    <Tag name="@consumer" type="contextual">
+      <Definition>Кто является клиентом этого API? (Другие модули, UI, внешние системы).</Definition>
+      <Condition_Use>Для корневых сущностей (классы, модули) и публичных методов API.</Condition_Use>
+      <Condition_Skip>Для внутренних утилитных типов или методов.</Condition_Skip>
+      <Format>@consumer {ModuleName}, {SystemName}</Format>
+    </Tag>
+    <Tag name="@param" type="functional">
+      <Definition>Описание входящего аргумента: одно связное описание бизнес-роли и границ валидности. Для параметров-объектов описывается их общая роль, без дублирования описания внутренних полей.</Definition>
+      <Condition_Use>ВСЕГДА, если у функции есть аргументы.</Condition_Use>
+      <Condition_Skip>Если функция не принимает аргументов.</Condition_Skip>
+      <Format mode="required">@param {name} {Одно связное описание: что это и допустимые границы}.</Format>
+      <Format mode="optional">@param [{name}] {Одно связное описание}.</Format>
+    </Tag>
+    <Tag name="@returns" type="functional">
+      <Definition>Бизнес-цель результата: зачем вызывающему нужен результат. Для асинхронных функций описывает значение, которым успешно разрешается Promise.</Definition>
+      <Condition_Use>ВСЕГДА, если функция возвращает значение (не void/never).</Condition_Use>
+      <Condition_Skip>Если функция возвращает void.</Condition_Skip>
+      <Format>@returns {Цель результата для вызывающего}.</Format>
+    </Tag>
+    <Tag name="@pre" type="logic">
+      <Definition>Предпословие. Состояние системы или окружения (не связанное с простой валидацией аргументов), которое ДОЛЖНО быть истинным ДО вызова.</Definition>
+      <Condition_Use>Если есть скрытые требования к окружению или состоянию системы, не дублирующие @param.</Condition_Use>
+      <Condition_Skip>Если дублирует @param или требования только из типов TypeScript.</Condition_Skip>
+      <Format>@pre {Состояние системы/окружения}.</Format>
+    </Tag>
+    <Tag name="@post" type="logic">
+      <Definition>Постусловие. Гарантированное состояние системы ПОСЛЕ успешного выполнения.</Definition>
+      <Condition_Use>Если метод меняет стейт или даёт гарантию, не выраженную в @returns (напр. неизменность аргумента, порядок элементов).</Condition_Use>
+      <Condition_Skip>Если дублирует @returns или @param; для чистых функций без дополнительных гарантий.</Condition_Skip>
+      <Format>@post {Факт об изменении состояния или гарантия}.</Format>
+    </Tag>
+    <Tag name="@invariant" type="logic">
+      <Definition>Условие, которое всегда остается истинным для жизни сущности. Для внешних сервисов описывает SLA, политику обработки ошибок (Error Policy) и стратегию повторных запросов (Retry Policy).</Definition>
+      <Condition_Use>Для Классов/Интерфейсов с состоянием или клиентов внешних систем.</Condition_Use>
+      <Condition_Skip>Для функций-утилит (stateless).</Condition_Skip>
+      <Format>@invariant {Условие целостности или Политика}.</Format>
+    </Tag>
+    <Tag name="@sideEffect" type="critical">
+      <Definition>Любое взаимодействие с внешним миром (IO, Network, Logs, Events , etc).</Definition>
+      <Condition_Use>ВСЕГДА, если метод не является чистой функцией.</Condition_Use>
+      <Condition_Skip>Если метод только вычисляет и возвращает данные.</Condition_Skip>
+      <Format>@sideEffect {Тип действия}: {Описание}.</Format>
+    </Tag>
+    <Tag name="@throws" type="critical">
+      <Definition>Описание исключительной ситуации. Для асинхронных функций описывает причину отклонения (reject) Promise.</Definition>
+      <Condition_Use>Если метод может выбросить ошибку (throw) или вернуть Rejected Promise.</Condition_Use>
+      <Condition_Skip>Если метод гарантированно безопасен (never throws).</Condition_Skip>
+      <Format>@throws {ErrorType | RejectedPromiseReason} {Условие возникновения}.</Format>
+    </Tag>
+    <Tag name="@see" type="linking">
+      <Definition>Ссылка на определение контракта (Interface/Spec/Type), который реализует этот код.</Definition>
+      <Condition_Use>При реализации интерфейса или наследовании, чтобы не дублировать описание.</Condition_Use>
+      <Condition_Skip>Если это первичное определение контракта.</Condition_Skip>
+      <Format>@see {TypeName#method} in path/from/project/root</Format>
+    </Tag>
+    <Tag name="@example" type="optional">
+      <Definition>Пример использования кода.</Definition>
+      <Condition_Use>Если логика вызова неочевидна или требует сложной подготовки данных.</Condition_Use>
+      <Condition_Skip>Для тривиальных методов (get/set).</Condition_Skip>
+      <Format>@example {Code block}</Format>
+    </Tag>
+    <Tag name="@deprecated" type="lifecycle">
+      <Definition>Маркер устаревшего кода.</Definition>
+      <Condition_Use>Если метод планируется к удалению. Обязательно указать альтернативу.</Condition_Use>
+      <Condition_Skip>Для актуального кода.</Condition_Skip>
+      <Format>@deprecated Используй {NewMethod} вместо этого.</Format>
+    </Tag>
+  </Tag_Dictionary>
+  <Usage_Patterns hint="Как применять теги к разным сущностям">
+    <Pattern id="PATTERN_SPECIFICATION_TYPE" appliesTo="type, interface (data)">
+      <Context>Определение типа данных (type) или контракта данных (interface).</Context>
+      <Rule>Данные: type с @purpose; при принадлежности к домену/API — префикс в имени. Логика: pre/post только если не дублируют param/returns.</Rule>
+      <Example>
+        /**
+         * @purpose Описывает элемент каталога внешнего сервиса — идентификатор и дочерние элементы.
+         * @consumer catalog-service, export-module.
+         */
+        export type ApiCatalogItem = { id: string; children: ApiCatalogItem[]; };
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_SYSTEM_INTERFACE" appliesTo="interface (service), class (client)">
+      <Context>Интерфейс или Клиент к внешней системе (API, DB, IO). Ненадежная среда.</Context>
+      <Rule>Обязательно: 1. Иерархия ошибок (Base → Network/Auth/Domain). 2. @invariant с описанием Resilience Policy (Retry, Rate Limits, Timeout).</Rule>
+      <Example>
+        /**
+         * @purpose Клиент для работы с платежным шлюзом.
+         * @consumer billing-service
+         * @invariant Error Policy: Все сетевые ошибки оборачиваются в PaymentNetworkError.
+         * @invariant Retry Policy: Идемпотентные методы (GET) повторяются 3 раза с экспоненциальной задержкой.
+         * @invariant Rate Limit: Не более 100 rps (контролируется клиентом).
+         */
+        export interface PaymentGateway { ... }
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_IMPLEMENTATION_LINK" appliesTo="const, class, method">
+      <Context>Реализация сущности, которая уже описана во внешнем контракте (implements Interface).</Context>
+      <Rule>Не дублируй логику. Используй @purpose (кратко), @consumer и @see.</Rule>
+      <Example>
+        /**
+         * @purpose Реализация трансформации для мобильных устройств.
+         * @consumer MobileApp
+         * @see {UserTransformer} in features/users/contracts.ts
+         */
+        export const mobileUserTransformer: UserTransformer = (u) => { ... };
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_CLASS_METHOD" appliesTo="method">
+      <Context>Метод класса. Если реализует интерфейс — @see. Иначе — полный контракт.</Context>
+      <Example>
+        /**
+         * @purpose Списание средств.
+         * @pre Система должна быть в режиме read-write (не maintenance).
+         * @param amount Сумма к списанию (положительное число).
+         * @throws {NoFundsError} Если баланс недостаточен.
+         */
+        public pay(amount: number): void { ... }
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_FUNCTION_PARAM_RETURNS" appliesTo="function">
+      <Context>Стандартная функция. @param не дублирует поля типа.</Context>
+      <Example good="@param id Идентификатор сущности (непустая строка или положительное число). @returns Данные для отображения в UI или передачи в следующий слой."/>
+      <Example bad="@param id Смысл: идентификатор. Валидность: непустая строка. @returns UserDto с заполненными полями."/>
+    </Pattern>
+    <Pattern id="PATTERN_EXPORTED_CONSTANT" appliesTo="const">
+      <Context>Публичные константы, особенно объекты конфигурации.</Context>
+      <Rule>Опиши @purpose (зачем этот конфиг) и @invariant (ограничения значений).</Rule>
+      <Example>
+        /**
+         * @purpose Глобальные настройки ретраев для HTTP.
+         * @invariant maxRetries должно быть меньше 5.
+         */
+        export const RETRY_CONFIG = { ... };
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_ASYNC_FUNCTION" appliesTo="function, method">
+      <Context>Асинхронная функция, возвращающая Promise.</Context>
+      <Rule>@returns описывает значение при успешном resolve. @throws описывает причину (Error) при reject.</Rule>
+      <Example>
+        /**
+         * @purpose Загружает данные пользователя с сервера.
+         * @param userId ID пользователя для загрузки (UUIDv4).
+         * @throws {UserNotFoundError} Если пользователь с таким ID не найден.
+         * @returns {Promise<ApiUser>} Данные пользователя для внутреннего использования в системе.
+         * @sideEffect Network: GET-запрос к /api/users/{userId}
+         */
+        export async function fetchUser(userId: string): Promise<ApiUser> { ... }
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_GENERIC_FUNCTION" appliesTo="function, method">
+      <Context>Обобщенная (generic) функция с параметризованными типами.</Context>
+      <Rule>В @param и @returns следует описать роль обобщенного типа T.</Rule>
+      <Example>
+        /**
+         * @purpose Оборачивает любые входные данные в стандартизированный объект ответа.
+         * @param data Данные любого типа {T}, которые будут помещены в поле `payload`.
+         * @returns {ApiResponse<T>} Стандартизированный объект ответа, содержащий исходные данные.
+         */
+        export function wrapInApiResponse<T>(data: T): ApiResponse<T> { ... }
+      </Example>
+    </Pattern>
+  </Usage_Patterns>
+  <Validation_Checklist hint="Критерии качества контракта">
+    <Check>Экспортируемая сущность: есть @purpose; для корневых типов и публичного API — @consumer при необходимости.</Check>
+    <Check>Класс/модуль с состоянием: есть @invariant.</Check>
+    <Check>Внешний сервис (Client/Interface): определен @invariant с иерархией ошибок и Retry Policy.</Check>
+    <Check>@param — одно связное описание. Для объектов описание полей не дублируется из типа.</Check>
+    <Check>@returns — бизнес-цель результата для вызывающего, а не перечисление типа.</Check>
+    <Check>Порядок тегов соблюдён: purpose → consumer → invariant → pre → param → throws → returns → post → sideEffect.</Check>
+    <Check>@pre и @post не дублируют @param/@returns; только если добавляют новую информацию.</Check>
+    <Check>Метод с побочными эффектами: есть @post или @sideEffect.</Check>
+    <Check>Реализация внешнего типа: есть @see с путем от корня.</Check>
+    <Check>Структуры данных объявлены через type; interface только при наследовании/реализации.</Check>
+    <Check>Типы внешнего домена/API имеют префикс в имени.</Check>
+    <Check>Асинхронность: @returns описывает успех, @throws — ошибку (reject).</Check>
+  </Validation_Checklist>
+</JSDOC_AS_CONTACTS>

package/dist/ai/agents/agent-resolve-conflicts.xml

@@ -0,0 +1,6 @@
+<!-- @file: Agent directive for conflict resolution -->
+<!-- @consumers: resolve-conflicts command -->
+<!-- @tasks: TSK-33 -->
+<Agent name="agent-resolve-conflicts" type="directive" ver="0.1">
+  <Mission>Resolve merge conflicts with confidence scoring.</Mission>
+</Agent>

package/dist/ai/agents/agent-review-verifier.xml

@@ -0,0 +1,6 @@
+<!-- @file: Agent directive for review verification -->
+<!-- @consumers: review-verify command -->
+<!-- @tasks: TSK-33 -->
+<Agent name="agent-review-verifier" type="directive" ver="0.1">
+  <Mission>Verify review results against code changes.</Mission>
+</Agent>

package/dist/ai/directives/architecture/README.md

@@ -0,0 +1,21 @@
+# Architecture rules
+
+Architectural patterns constraining HOW components compose and depend on each other.
+
+Distinct from `coding/` (language-level rules) and `quality/` (cross-cutting code quality).
+
+## Currently available
+
+_(none yet)_
+
+## Planned
+
+- `ports-adapters.xml` — hexagonal architecture: ports as abstractions, adapters as implementations, dependency direction (business logic depends on ports, not adapters).
+- `ddd.xml` — Domain-Driven Design tactical patterns: aggregates, entities vs value objects, domain events, bounded contexts.
+- `event-sourcing.xml` — event-sourced state: append-only event log, projections, eventual consistency.
+- `cqrs.xml` — command/query separation: write models vs read models.
+- `layered.xml` — classic n-tier (presentation / application / domain / infrastructure).
+
+## How they're activated
+
+Architecture rules are referenced from `discovery` §4.5 Project-Wide Rules (when chosen at project level) or from domain spec §9 Domain Rules Additions (when scoped to one domain). They typically activate `now` per `AX_RULE_ACTIVATION_DEFAULTS` — strong opinions deserve operator buy-in.

package/dist/ai/directives/coding/README.md

@@ -0,0 +1,23 @@
+# Coding rules
+
+Language-specific rules for HOW to write code: syntax preferences, naming, error handling, comment style, language idioms.
+
+Distinct from:
+
+- `runtimes/` — runtime SETUP (Node version, package manager).
+- `quality/` — cross-language quality (binary lint severity, formatting delegation).
+- `architecture/` — composition patterns.
+
+## Currently available
+
+- [`typescript-rules.xml`](typescript-rules.xml) — TypeScript writing conventions.
+- [`svelte5-runes.xml`](svelte5-runes.xml) — Svelte 5 runes: $state, $derived, $effect, $props, template syntax. **Inherits typescript-rules.**
+- [`sveltekit-rules.xml`](sveltekit-rules.xml) — SvelteKit fullstack: routing, load, form actions, hooks, $app modules. **Inherits svelte5-runes + typescript-rules.**
+
+## Planned
+
+- `react-rules.xml` — React component patterns, hooks discipline, JSX conventions.
+- `go-rules.xml` — Go idioms, error handling, package layout.
+- `python-rules.xml` — Python style (PEP 8 + project-specific tightening), type hints, dataclasses vs Pydantic.
+- `rust-rules.xml` — Rust idioms, error handling (`Result`, `?` operator), lifetimes & borrowing patterns.
+- `css-rules.xml` — CSS naming (BEM / utility-first), specificity discipline.

package/dist/ai/directives/coding/result-conventions.xml

@@ -0,0 +1,55 @@
+<ResultConventions keywords="result, error-handling, isErr, TessellError, unwrap, success, fail" type="coding-rule" ver="1.0">
+  <Mission>
+    Invariants for the Result pattern from @tessell/core/result. Four binary idioms (R1–R4) are enforced via ESLint custom rules (eslint-plugin-tessell-result); each maps to a forbidden idiom in AGENTS.md that survived code review and was caught retroactively. One architectural convention (AX_RESULT_PUBLIC_BOUNDARY) is code-review-only — not mechanically detectable.
+  </Mission>
+
+  <Belief_State>
+    <Axiom id="AX_NO_RESULT_SECOND_GENERIC">
+      `Result<T, ConcreteError>` is forbidden. No method can guarantee it only throws one error class — library and runtime code can throw anything. Use `Result<T>` only.
+      Exception: when the second arg is a type parameter of the enclosing generic declaration (function / type alias / class) — that is a constraint, not a pinned class. Detection: AST walk up to nearest TSTypeParameterDeclaration; skip if name appears there.
+      Autofix: remove second type argument.
+    </Axiom>
+
+    <Axiom id="AX_NO_RESULT_OBJECT_LITERAL">
+      Manual `{ ok: true, data: x, error: null }` and `{ ok: false, data: null, error: e }` are forbidden. Always use `success(x)` / `fail(e)`.
+      Rationale: bypasses the contract, breaks silently if Result shape evolves.
+      Autofix: ok===true → success(data_value); ok===false → fail(error_value).
+    </Axiom>
+
+    <Axiom id="AX_NO_RESULT_ISERR_SHORT_CIRCUIT">
+      `if (isErr(r)) return r` and `if (!isOk(r)) return r` are forbidden. Use `unwrap + try/catch` — that is the whole point of the convention.
+      No autofix: requires restructuring the surrounding function, not a one-line substitution.
+    </Axiom>
+
+    <Axiom id="AX_NO_BARE_THROW_UNKNOWN">
+      `throw catchBinding` without wrapping in `TessellError.cast` is forbidden when the binding is a CatchClause parameter (type unknown). Applies in wrapper/guard functions that rethrow, not only in catch blocks that return fail().
+      Detection: scope analysis — ThrowStatement whose argument resolves to a CatchClause parameter, regardless of variable name (cause, err, e, error).
+      No autofix: the fallback message is context-dependent.
+    </Axiom>
+
+    <Axiom id="AX_RESULT_PUBLIC_BOUNDARY" enforcement="convention">
+      Result is the transport form of error across the public / port boundary — not an internal control-flow primitive. Public surface (port interface methods, exported factory return types, closures returned from factories) MUST return `Result<T>`. Inside the same class:
+      - protected/private async helpers with I/O → throw; the public caller wraps in try/catch and returns `fail(error)` (per AX_CATCH_LOG_RECOVER in typescript-rules).
+      - pure helpers (predicates, classifiers) → honest return type (`Error | null`, scalar, enum literal); not Result.
+      - Result in protected is permitted only when the helper carries a typed `kind` the public call-site immediately unwraps — and even then, throw is usually cleaner because it avoids the `Result → unwrapSync → throw → catch → re-emit` double-packaging pattern.
+
+      Rationale: mixing Result and null-pattern in helpers of one class produces structural noise (two error-channel styles in one surface) and double-packaging. The convention keeps Result as a boundary artifact, not an internal one.
+
+      Not ESLint-enforced. The public/private boundary is not mechanically detectable: closures returned from factories (e.g. `defineDataStorageQuery → (storage, params) => Promise<Result<R>>`) are public-by-intent but private-by-syntax, and methods on factory-returned object literals (e.g. `defineDataOperation`) are not visible as class members. Enforced via code review and this directive.
+    </Axiom>
+
+    <Axiom id="AX_CONFIGURABLE_NAMES">
+      Every rule that matches function or type names accepts an options object with configurable identifiers: resultTypeName, isErrFn, isOkFn, successFn, failFn, castFn.
+      Defaults match @tessell/core/result exports. On package rename — update config, not the rule.
+    </Axiom>
+  </Belief_State>
+
+  <Reward_Criteria>
+    - R1 flags `Result<T, DataStorageError>`, autofixes to `Result<T>`. Does NOT flag `Result<T, E>` where E is a type parameter of the enclosing generic.
+    - R2 flags `{ ok: true, data: x, error: null }`, autofixes to `success(x)`.
+    - R3 flags `if (isErr(r)) return r` with no autofix; error message cites `unwrap + try/catch`.
+    - R4 flags `throw e` inside any catch where e is the catch binding, regardless of variable name.
+    - R3 and R4 carry explanatory comment in eslint.config.ts (non-autofix path per eslint-setup AX_CUSTOM_PLUGINS_OBEY_META_POLICY).
+    - Each rule has Vitest tests: positive case, negative case, edge case (R1: type param exception; R4: non-catch-binding throw not flagged).
+  </Reward_Criteria>
+</ResultConventions>