diff --git a/.axiom/axiom_config.yaml b/.axiom/axiom_config.yaml index c2e527b6..1e224239 100644 --- a/.axiom/axiom_config.yaml +++ b/.axiom/axiom_config.yaml @@ -1,6 +1,8 @@ +# #region AxiomConfig [C:5] [TYPE Block] [SEMANTICS config,axiom,indexing] +# @BRIEF Axiom engine configuration — anchor format, indexing rules, tag schema. +# @RATIONALE Single source of truth for the semantic indexing engine. All descriptions in English per MLA token efficiency. Complexity rules use a global tag catalog rather than per-tier duplication (all tags allowed at all tiers per SSOT protocol). + # #region AnchorConfig [C:3] [TYPE Block] [SEMANTICS config,anchor] -# @BRIEF Якорный синтаксис — глобальный формат и переопределения по директориям. -# @RELATION BINDS_TO -> [Std.Semantics.Core] anchor: format: region overrides: @@ -9,7 +11,7 @@ anchor: syntax: {} # #endregion AnchorConfig -# #region IndexingConfig [C:2] [TYPE Block] [SEMANTICS config,indexing] +# #region IndexingConfig [C:3] [TYPE Block] [SEMANTICS config,indexing] indexing: include: [] exclude: @@ -26,712 +28,354 @@ indexing: - '*.yml' - '*.json' - '*.toml' - - '*.md' source_dirs: - src - tests + - routes doc_dirs: - docs - specs + - .opencode + - .specify + - .opencode/agents + - .opencode/skills + - .opencode/command + - .specify/memory + - .specify/templates # #endregion IndexingConfig -# #region ComplexityRules [C:5] [TYPE Block] [SEMANTICS config,rules,validation] -# @BRIEF Уровни сложности C1-C5 — описательные сигналы, не gatekeeper-правила. -# @RELATION BINDS_TO -> [Std.Semantics.Core] -# @INVARIANT Каждый тэг в required/suggested списках обязан иметь определение в TagSchema. -# @RATIONALE Tiers are descriptive signals, not gatekeepers. Any tag is welcomed at any tier. -# @PRE/@POST on a C2 utility is informative, not a violation. -# @RATIONALE/@REJECTED are universally welcomed — decision memory at all levels. -# @REJECTED Old forbidden lists per tier caused agents to remove useful documentation tags. -# No tag is forbidden at any tier. Let agents document what needs documenting. -complexity_rules: - '1': - required: [] - suggested: - - ACTION - - ATOM - - BRIEF - - STATE - - PURPOSE - - C - - COMPLEXITY - - EXAMPLE - - ERROR - - RAISES - - THROWS - - PRE - - POST - - RATIONALE - - REJECTED - - INVARIANT - - DATA_CONTRACT - - SIDE_EFFECT - - RELATION - - LAYER - - PUBLIC_API - - SEMANTICS - - STATUS - - DEPRECATED - - REPLACED_BY - - TEST_CONTRACT - - TEST_EDGE - - TEST_INVARIANT - - TEST_FIXTURE - - TEST_SCENARIO - - UX_STATE - - UX_FEEDBACK - - UX_RECOVERY - - UX_REACTIVITY - - RESTRICTION - '2': - required: [] - suggested: - - ACTION - - ATOM - - BRIEF - - STATE - - PURPOSE - - C - - COMPLEXITY - - EXAMPLE - - ERROR - - RAISES - - THROWS - - PRE - - POST - - RATIONALE - - REJECTED - - INVARIANT - - DATA_CONTRACT - - SIDE_EFFECT - - RELATION - - LAYER - - PUBLIC_API - - SEMANTICS - - STATUS - - DEPRECATED - - REPLACED_BY - - TEST_CONTRACT - - TEST_EDGE - - TEST_INVARIANT - - TEST_FIXTURE - - TEST_SCENARIO - - UX_STATE - - UX_FEEDBACK - - UX_RECOVERY - - UX_REACTIVITY - - RESTRICTION - '3': - required: [] - suggested: - - ACTION - - ATOM - - BRIEF - - STATE - - PURPOSE - - C - - COMPLEXITY - - EXAMPLE - - ERROR - - RAISES - - THROWS - - PRE - - POST - - RATIONALE - - REJECTED - - INVARIANT - - DATA_CONTRACT - - SIDE_EFFECT - - RELATION - - LAYER - - PUBLIC_API - - SEMANTICS - - STATUS - - DEPRECATED - - REPLACED_BY - - TEST_CONTRACT - - TEST_EDGE - - TEST_INVARIANT - - TEST_FIXTURE - - TEST_SCENARIO - - UX_STATE - - UX_FEEDBACK - - UX_RECOVERY - - UX_REACTIVITY - - RESTRICTION - '4': - required: [] - suggested: - - ACTION - - ATOM - - BRIEF - - STATE - - PURPOSE - - C - - COMPLEXITY - - EXAMPLE - - ERROR - - RAISES - - THROWS - - PRE - - POST - - RATIONALE - - REJECTED - - INVARIANT - - DATA_CONTRACT - - SIDE_EFFECT - - RELATION - - LAYER - - PUBLIC_API - - SEMANTICS - - STATUS - - DEPRECATED - - REPLACED_BY - - TEST_CONTRACT - - TEST_EDGE - - TEST_INVARIANT - - TEST_FIXTURE - - TEST_SCENARIO - - UX_STATE - - UX_FEEDBACK - - UX_RECOVERY - - UX_REACTIVITY - - RESTRICTION - '5': - required: [] - suggested: - - ACTION - - ATOM - - BRIEF - - STATE - - PURPOSE - - C - - COMPLEXITY - - EXAMPLE - - ERROR - - RAISES - - THROWS - - PRE - - POST - - RATIONALE - - REJECTED - - INVARIANT - - DATA_CONTRACT - - SIDE_EFFECT - - RELATION - - LAYER - - PUBLIC_API - - SEMANTICS - - STATUS - - DEPRECATED - - REPLACED_BY - - TEST_CONTRACT - - TEST_EDGE - - TEST_INVARIANT - - TEST_FIXTURE - - TEST_SCENARIO - - UX_STATE - - UX_FEEDBACK - - UX_RECOVERY - - UX_REACTIVITY - - RESTRICTION -# #endregion ComplexityRules - -# #region ComplexityRules [C:3] [TYPE Block] [SEMANTICS config,adr,override] -# @BRIEF Типоспецифичные подсказки — не переопределяют базовые complexity_rules, а дополняют их (union). -# @RELATION BINDS_TO -> [Std.Semantics.Core] -# @RATIONALE Per-type suggestions are additive — they don't restrict base complexity_rules. -# All tags remain informational at any type/level per SSOT protocol. -# @REJECTED Restrictive contract_type_overrides caused schema_tag_not_for_contract_type warnings. -# Removed; base complexity_rules already cover all tags. -# @REJECTED Keeping this section empty as placeholder — type-specific suggestions are -# unnecessary since all tags are informational per protocol. -contract_type_overrides: {} -# #endregion ComplexityRules +# #region GlobalTagCatalog [C:5] [TYPE Block] [SEMANTICS config,tags,global] +# @BRIEF All recognized @-tags — informational, allowed at any tier (C1-C5) per SSOT protocol. +# @INVARIANT Every tag in this catalog has a definition. No tag is forbidden at any tier. +# @RATIONALE Per-tier duplication eliminated — tiers are descriptive, not gatekeeping. +# A single global catalog enforces the rule: all tags allowed everywhere. +global_tags: + allowed: + - ACTION + - ATOM + - BRIEF + - STATE + - PURPOSE + - EXAMPLE + - ERROR + - RAISES + - THROWS + - PRE + - POST + - RATIONALE + - REJECTED + - INVARIANT + - DATA_CONTRACT + - SIDE_EFFECT + - RELATION + - LAYER + - PUBLIC_API + - SEMANTICS + - STATUS + - DEPRECATED + - REPLACED_BY + - TEST_CONTRACT + - TEST_EDGE + - TEST_INVARIANT + - TEST_FIXTURE + - TEST_SCENARIO + - UX_STATE + - UX_FEEDBACK + - UX_RECOVERY + - UX_REACTIVITY + - UX_TEST + - RESTRICTION + - PARAM + - RETURN + - YIELDS + - TEST + - DEBT + - NOTE + - PROPERTY + - TYPEDEF + - CONSTRAINT + - CONTRACT + - CRITICAL_TRACE + - FRAGILE + - INVARIANT_VIOLATION + - VALIDATION + - TEST_DATA +# #endregion GlobalTagCatalog # #region TagSchema [C:5] [TYPE Block] [SEMANTICS config,tags,schema] tags: C: type: string multiline: false - description: 'DEPRECATED. Канонический формат сложности — [C:N] в заголовке #region. @C больше не использовать.' - alias_for: COMPLEXITY deprecated: true deprecated_since: '2026-05-19' - contract_types: - - Module - - Function - - Class - - Component - - Block - - Skill - - Agent + alias_for: COMPLEXITY + description: 'DEPRECATED. Use [C:N] in #region header line. @C no longer used.' protected: true orthogonal: false decision_memory: false COMPLEXITY: type: string multiline: false - description: 'Уровень сложности (1-5). Канонический формат — [C:N] в заголовке анкора #region. @COMPLEXITY как тэг допускается для обратной совместимости, но [C:N] предпочтителен.' enum: ['1','2','3','4','5'] - contract_types: - - Module - - Function - - Class - - Component - - Block - - Skill - - Agent + description: 'Complexity tier (1-5). Canonical format is [C:N] in the #region anchor header. @COMPLEXITY as a tag is accepted for backward compatibility, but [C:N] is preferred.' protected: true orthogonal: false decision_memory: false ACTION: type: string multiline: true - description: 'Действие модели (model action). Документирует публичный метод модели, изменяющий состояние. Svelte 5 Model тег.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'Model action. Documents a public model method that mutates state. Svelte 5 Model tag.' ATOM: type: string multiline: false - description: 'Атом состояния модели. Документирует атомарное поле $state. Svelte 5 Model тег.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'Model state atom. Documents an atomic $state field. Svelte 5 Model tag.' BRIEF: type: string multiline: true - description: 'Назначение контракта. Канонический формат для описания PURPOSE. Универсально опциональный. Хороший тон — иметь @BRIEF на любой функции.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'Contract purpose. Canonical format for describing what the contract does. Recommended on every function. Preferred over legacy @PURPOSE.' PURPOSE: type: string multiline: true alias_for: BRIEF - description: 'Алиас для BRIEF (legacy). Используй @BRIEF в новом коде.' - contract_types: [] + description: 'Alias for BRIEF (legacy). Use @BRIEF in new code.' + STATE: + type: string + multiline: true + description: 'UX FSM state. Documents possible screen states. Svelte 5 Model tag.' EXAMPLE: type: string multiline: true - description: 'Пример использования. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'Usage example.' ERROR: type: string multiline: true - description: 'Исключение. @ERROR ValueError. Алиасы: RAISES, THROWS. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'Exception. @ERROR ValueError. Aliases: RAISES, THROWS.' RAISES: type: string multiline: true alias_for: ERROR - description: 'Алиас для ERROR.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'Alias for ERROR.' THROWS: type: string multiline: true - description: 'Исключение. @THROWS ValueError. Алиас для ERROR. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false alias_for: ERROR + description: 'Alias for ERROR.' DEPRECATED: type: string multiline: true - description: 'Метка устаревания. @DEPRECATED v2.5. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: false + description: 'Deprecation marker. @DEPRECATED v2.5.' decision_memory: true REPLACED_BY: type: string multiline: false - description: 'Ссылка на замену. @REPLACED_BY NewService.run.' is_reference: true - contract_types: [] - protected: false - orthogonal: false + description: 'Replacement pointer. @REPLACED_BY NewService.run.' decision_memory: true SEMANTICS: type: array multiline: false separator: ',' - description: 'Семантические маркеры для поиска. Ортогональный.' - contract_types: [] - protected: false + description: 'Semantic keywords for DSA Indexer search. Orthogonal. Survivability-critical: same-domain contracts must share primary keyword.' orthogonal: true - decision_memory: false SIDE_EFFECT: type: string multiline: false - description: 'Побочные эффекты (I/O, DB, API, сеть). Рекомендуется на функциях с side effects.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false - STATE: - type: string - multiline: true - description: 'Состояние конечного автомата UX. Документирует возможные состояния экрана. Svelte 5 Model тег.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'Side effects (I/O, DB, API, network). Recommended on functions with mutations.' STATUS: type: string multiline: false - description: 'Статус: ACTIVE, DEPRECATED, EXPERIMENTAL.' - contract_types: [] - protected: false + description: 'Status: ACTIVE, DEPRECATED, EXPERIMENTAL.' orthogonal: true - decision_memory: false TEST_CONTRACT: type: string multiline: false - description: Что проверяет тест. Ортогональный. - contract_types: [Function, Block] - protected: false + description: 'What the test verifies. Orthogonal.' orthogonal: true - decision_memory: false TEST_EDGE: type: string multiline: false - description: Краевой случай. Ортогональный. - contract_types: [Function, Block] - protected: false + description: 'Edge case scenario. Orthogonal. Minimum 3 per production contract: missing_field, invalid_type, external_fail.' orthogonal: true - decision_memory: false TEST_FIXTURE: type: string multiline: false - description: Тестовая фикстура. Ортогональный. - contract_types: [Block] - protected: false + description: 'Test fixture. Orthogonal. Use hardcoded values — never algorithmic computation that mirrors implementation.' orthogonal: true - decision_memory: false TEST_INVARIANT: type: string multiline: false - description: Инвариант теста. Ортогональный. - contract_types: [Module, Function] - protected: false + description: 'Test invariant mapping. @TEST_INVARIANT: name -> VERIFIED_BY: [test_name]. Orthogonal.' orthogonal: true - decision_memory: false TEST_SCENARIO: type: string multiline: false - description: Сценарий теста. Ортогональный. - contract_types: [Function, Block] - protected: false + description: 'Test scenario. Orthogonal.' orthogonal: true - decision_memory: false UX_FEEDBACK: type: string multiline: false - description: Формат обратной связи. Component. - contract_types: [Component] - protected: false + description: 'UX feedback format (Toast, Shake, RedBorder, Modal). Component only.' orthogonal: true - decision_memory: false UX_REACTIVITY: type: string multiline: false - description: Реактивная модель. Component. - contract_types: [Component] - protected: false + description: 'Reactive model declaration. Component only.' orthogonal: true - decision_memory: false UX_RECOVERY: type: string multiline: false - description: Стратегия восстановления. Component. - contract_types: [Component] - protected: false + description: 'Recovery strategy after error/degraded state. Component only.' orthogonal: true - decision_memory: false UX_STATE: type: string multiline: false - description: Конечный автомат UX. Рекомендуется для компонентов с множественными состояниями. - contract_types: [Component] - protected: false - orthogonal: false - decision_memory: false + description: 'UX FSM state mapping. Recommended for multi-state components. Example: @UX_STATE Loading -> Spinner visible, btn disabled.' RELATION: type: string multiline: false - description: 'Графовая зависимость. Описывает связь между контрактами. Рекомендуется на любой функции/модуле с внешними зависимостями.' is_reference: true + description: 'Graph dependency edge. Links contracts. Recommended on any function/module with external dependencies.' allowed_predicates: [DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, BINDS_TO, CALLED_BY, VERIFIES, USES, CONTAINS, BELONGS_TO, ASSOCIATED_WITH] - contract_types: [] - protected: false - orthogonal: false - decision_memory: false PRE: type: string multiline: true - description: 'Предусловия. Рекомендуется на функциях с нетривиальными входными требованиями.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'Preconditions. Enforce via explicit if/raise guards — NEVER use assert. Recommended on functions with non-trivial input requirements.' POST: type: string multiline: true - description: 'Гарантии результата. Рекомендуется на функциях с нетривиальными постусловиями.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false - PUBLIC_API: - type: string - multiline: false - description: 'Публичный API контракта: какие классы/функции являются точками входа. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false + description: 'Output guarantees. Cascading protection: do NOT alter @POST without verifying upstream @RELATION CALLS consumers.' RATIONALE: type: string multiline: true - description: 'Обоснование архитектурного решения. Универсально опциональный (C1+). Decision Memory. Хлебные крошки для следующего разработчика — объясни ПОЧЕМУ сделан этот выбор.' - contract_types: [] - protected: false - orthogonal: false + description: 'Architectural decision rationale. WHY this implementation was chosen. Decision Memory — prevents regression loops.' decision_memory: true REJECTED: type: string multiline: true - description: 'Отвергнутая альтернатива и причина отказа. Универсально опциональный (C1+). Decision Memory. Предотвращает повторение ошибок — задокументируй ЧТО пробовали и ПОЧЕМУ не сработало.' - contract_types: [] - protected: false - orthogonal: false + description: 'Rejected alternative and disqualification reason. WHAT was tried and WHY it failed. Decision Memory — active guardrail against re-implementation.' decision_memory: true DATA_CONTRACT: type: string multiline: false - description: 'DTO-маппинг (Input→Output). Универсально опциональный. Полезен на любом контракте с чёткими типами входа/выхода.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'DTO mapping: Input -> Output. Recommended on any contract with clear input/output types. Critical for cross-stack alignment (backend Pydantic <-> frontend TypeScript).' INVARIANT: type: string multiline: true - description: 'Инвариант — условие, истинное всегда. Универсально опциональный (C1+). Документируй неуничтожимые гарантии на любом уровне.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'Invariant — condition always true. Documents unbreakable guarantees at any level.' UX_TEST: type: string multiline: false - description: 'Тестовый сценарий для browser-валидации UX. Component.' - contract_types: [Component] - protected: false + description: 'Browser-verifiable UX test scenario. Component only.' orthogonal: true - decision_memory: false - TYPE: - type: string - multiline: false - description: 'Тип контракта или компонента. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false LAYER: type: string multiline: false - description: 'Слой архитектуры: Core, Domain, API, UI, Service, Infrastructure, Plugin, Tests. Универсально опциональный.' - enum: [Core, Domain, API, UI, Service, Infrastructure, Plugin, Tests, Infra, UI (Tests), Frontend, Atom, Feature, Page, Component, Application, App, Widget, Panel, Store, Layout] - contract_types: - - Module - - Skill - - Agent - protected: false + description: 'Architecture layer: Core, Domain, API, UI, Service, Infrastructure, Plugin, Tests.' + enum: [Core, Domain, API, UI, Service, Infrastructure, Plugin, Tests, Infra, Frontend, Feature, Page, Component, Widget, Panel, Store, Layout] orthogonal: true - decision_memory: false RESTRICTION: type: string multiline: true - description: 'Ограничение контракта (например, EXAMPLES ONLY — не переопределять правила из SSOT). Универсально опциональный.' - contract_types: [] - protected: false + description: 'Contract restriction (e.g., EXAMPLES ONLY — do not redefine rules from SSOT).' orthogonal: true - decision_memory: false PARAM: type: string multiline: true - description: 'Параметр функции. Документирует ожидаемый аргумент. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'Function parameter documentation.' RETURN: type: string multiline: true - description: 'Возвращаемое значение. Документирует тип и условия возврата. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false + description: 'Return value documentation.' YIELDS: type: string multiline: true - description: 'Генерируемое значение генератора. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: false - decision_memory: false - TEST: - type: string - multiline: true - description: 'Описание тестового сценария. Используется в тестовых контрактах. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false - DEBT: - type: string - multiline: true - description: 'Задокументированный технический долг. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false - NOTE: - type: string - multiline: true - description: 'Примечание для разработчиков. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false - PROPERTY: - type: string - multiline: true - description: 'Свойство/поле объекта. JSDoc-style. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false - TYPEDEF: - type: string - multiline: true - description: 'Определение типа. JSDoc-style. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false + description: 'Generator yield value documentation.' RETURNS: type: string multiline: true alias_for: RETURN - description: 'Алиас для RETURN. JSDoc-style. Универсально опциональный.' - contract_types: [] - protected: false + description: 'Alias for RETURN (JSDoc-style).' + TEST: + type: string + multiline: true + description: 'Test scenario description.' + orthogonal: true + DEBT: + type: string + multiline: true + description: 'Documented technical debt.' + orthogonal: true + NOTE: + type: string + multiline: true + description: 'Developer note.' + orthogonal: true + PROPERTY: + type: string + multiline: true + description: 'Object property/field (JSDoc-style).' + orthogonal: true + TYPEDEF: + type: string + multiline: true + description: 'Type definition (JSDoc-style).' orthogonal: true - decision_memory: false UI_STATE: type: string multiline: false alias_for: UX_STATE - description: 'Алиас для UX_STATE (legacy). Используй @UX_STATE в новом коде. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false - - TEST_DATA: - type: string - multiline: true - description: 'Тестовые данные или фикстура. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false - CONSTRAINT: - type: string - multiline: true - alias_for: INVARIANT - description: 'Алиас для INVARIANT. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false - CONTRACT: - type: string - multiline: true - description: 'Описание контракта или соглашения. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false - CRITICAL_TRACE: - type: string - multiline: true - description: 'Критический trace-маркер для отладки. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false - FRAGILE: - type: string - multiline: true - description: 'Хрупкий код/тест — может сломаться от изменений. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false - INVARIANT_VIOLATION: - type: string - multiline: true - description: 'Задокументированное нарушение инварианта. Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false - THROW: - type: string - multiline: true - alias_for: ERROR - description: 'Алиас для ERROR (JSDoc-style). Универсально опциональный.' - contract_types: [] - protected: false - orthogonal: true - decision_memory: false + description: 'Alias for UX_STATE (legacy). Use @UX_STATE in new code.' UX_REATIVITY: type: string multiline: false alias_for: UX_REACTIVITY - description: 'Опечатка для UX_REACTIVITY (legacy). Используй @UX_REACTIVITY. Универсально опциональный.' - contract_types: [] - protected: false + description: 'Typo alias for UX_REACTIVITY (legacy). Use @UX_REACTIVITY.' + TEST_DATA: + type: string + multiline: true + description: 'Test data or fixture.' orthogonal: true - decision_memory: false + CONSTRAINT: + type: string + multiline: true + alias_for: INVARIANT + description: 'Alias for INVARIANT.' + CONTRACT: + type: string + multiline: true + description: 'Contract or agreement description.' + orthogonal: true + CRITICAL_TRACE: + type: string + multiline: true + description: 'Critical trace marker for debugging.' + orthogonal: true + FRAGILE: + type: string + multiline: true + description: 'Fragile code/test — may break from changes.' + orthogonal: true + INVARIANT_VIOLATION: + type: string + multiline: true + description: 'Documented invariant violation.' + orthogonal: true + THROW: + type: string + multiline: true + alias_for: ERROR + description: 'Alias for ERROR (JSDoc-style).' VALIDATION: type: string multiline: false - description: 'Правило валидации. Универсально опциональный.' - contract_types: [] - protected: false + description: 'Validation rule.' + orthogonal: true + PUBLIC_API: + type: string + multiline: false + description: 'Public API surface — which classes/functions are entry points.' orthogonal: true - decision_memory: false - # #endregion TagSchema # #region InfrastructureConfig [C:2] [TYPE Block] [SEMANTICS config,embedding,http] @@ -747,3 +391,5 @@ doc_stripped_output: null doc_symbol_types: null tier_thresholds: {} # #endregion InfrastructureConfig + +# #endregion AxiomConfig diff --git a/.opencode/agents/python-coder.md b/.opencode/agents/python-coder.md index 4c3c7502..723ff44c 100644 --- a/.opencode/agents/python-coder.md +++ b/.opencode/agents/python-coder.md @@ -34,7 +34,7 @@ Your attention mechanism compresses context in a hybrid pipeline (see `semantics 4. **Copy‑paste regression.** You see similar code → copy it. If the original had `@REJECTED fallback to SQLite` but HCA 128× erased those tokens from your attention, you silently re‑implement the forbidden path. `@REJECTED` in the anchor header is a dense token that survives all compression layers. -**This project now:** 3658 contracts, 1627 orphans (44%), 206 unresolved edges. Every orphan contract is invisible to the DSA Indexer — the attention pipeline literally cannot route queries to it. +**Pre-training note:** `#region`, `@brief`, `@see` appear millions of times in training — you recognize them natively. `@RATIONALE`, `@REJECTED`, `@DATA_CONTRACT`, `@RELATION` are **custom tags learned only through in-context examples in this prompt and loaded skills.** Every `@RATIONALE` you read in a code contract is in-context fine-tuning. Consistency is paramount: planner-generated format must match implementation format. ## Protocol Reference Load and follow these skills (MANDATORY): diff --git a/.opencode/command/speckit.plan.md b/.opencode/command/speckit.plan.md index 471f8fe0..19a89a09 100644 --- a/.opencode/command/speckit.plan.md +++ b/.opencode/command/speckit.plan.md @@ -184,28 +184,27 @@ Generate its full `#region` header in `contracts/modules.md` under its parent mo **Minimal header for C3 API endpoints:** ``` #region Domain.Resource.Action [C:3] [TYPE Function] [SEMANTICS domain,action] -@BRIEF One-line purpose. -@RELATION DEPENDS_ON -> [DependencyService] -@RELATION DEPENDS_ON -> [DTO:RequestSchema] +# @ingroup Domain +# @BRIEF One-line purpose. +# @RELATION DEPENDS_ON -> [DependencyService] +# @RELATION DEPENDS_ON -> [DTO:RequestSchema] ``` **Full header for C4/C5 orchestration & cross-stack functions:** ``` #region Domain.Resource.Action [C:4] [TYPE Function] [SEMANTICS domain,action] -@BRIEF One-line purpose. -@PRE Precondition 1 (verifiable by guard clause). -@PRE Precondition 2. -@POST Output guarantee 1 (testable assertion). -@POST Output guarantee 2. -@SIDE_EFFECT State mutation, I/O, or external call. -@SIDE_EFFECT Logging (REASON/REFLECT/EXPLORE markers required). -@RELATION DEPENDS_ON -> [ServiceDependency] -@RELATION DEPENDS_ON -> [DTO:InputSchema] -@DATA_CONTRACT InputDTO -> OutputDTO -@RATIONALE Why this implementation approach. -@REJECTED What alternative was considered and forbidden. -@TEST_EDGE: scenario_name -> Expected failure behavior. -@TEST_EDGE: scenario_name -> Expected failure behavior. +# @ingroup Domain +# @BRIEF One-line purpose. +# @PRE Precondition 1 (verifiable by guard clause). +# @POST Output guarantee 1 (testable assertion). +# @SIDE_EFFECT State mutation, I/O, or external call. +# @SIDE_EFFECT Logging (REASON/REFLECT/EXPLORE markers required). +# @RELATION DEPENDS_ON -> [ServiceDependency] +# @RELATION DEPENDS_ON -> [DTO:InputSchema] +# @DATA_CONTRACT InputDTO -> OutputDTO +# @RATIONALE Why this implementation approach. +# @REJECTED What alternative was considered and forbidden. +# @TEST_EDGE: scenario_name -> Expected failure behavior. ``` **Screen Model actions (Svelte `.svelte.ts`):** diff --git a/.opencode/skills/semantics-core/SKILL.md b/.opencode/skills/semantics-core/SKILL.md index e624b090..8809c8eb 100644 --- a/.opencode/skills/semantics-core/SKILL.md +++ b/.opencode/skills/semantics-core/SKILL.md @@ -18,6 +18,52 @@ description: Reference manual for GRACE-Poly v2.6 — syntax formats, complexity **Agent prompts are thin shims:** they describe the agent's role, cognitive frame (specific failure modes for their stack), verification commands, and escalation format. They do NOT redefine tiers, tags, or syntax. Agent-specific cognitive framing lives in each agent's prompt and is not duplicated here. +### 0.1 Pre-Training Frequency & Tag Familiarity + +Not all GRACE tags are equal in the model's training data. Understanding which tags the model has seen millions of times vs. which it learns only through in-context examples is critical for protocol design. + +#### Pre-training native (Doxygen/JSDoc — millions of examples) + +| Tag | Doxygen/JSDoc equivalent | Training context | +|-----|-------------------------|-----------------| +| `@BRIEF` | `@brief` | All C/C++/Python/Rust Doxygen projects, all JS/TS JSDoc projects | +| `@defgroup` | `@defgroup GroupName Description` | Module-level grouping in Doxygen (LLVM, OpenCV, ROS) | +| `@ingroup` | `@ingroup GroupName` | Child membership in Doxygen groups | +| `@see` | `@see`, `@sa` | Cross-references — the model's native link mechanism | +| `@deprecated` | `@deprecated` | Deprecation markers in Doxygen and JSDoc | +| `@note`, `@warning` | `@note`, `@warning` | Advisory annotations | + +**Rule:** These tags trigger pre-trained recognition. Use them as structural anchors. `@defgroup` on modules + `@ingroup` on children is the strongest domain-grouping signal the model natively understands. + +#### Pre-training weak (formal verification — thousands of examples) + +| Tag | Context | Model recognition | +|-----|---------|-------------------| +| `@PRE` | Eiffel, Ada 2012, JML, ACSL | Understands "precondition" but not in documentation context | +| `@POST` | Eiffel, Ada 2012, JML, ACSL | Understands "postcondition" — weaker signal than `@brief` | +| `@INVARIANT` | Eiffel, Dafny, formal methods | Understands the word — but Doxygen `@invariant` is for formal verification, not general docs | + +**Rule:** These have semantic recognition from the word itself, but weak pre-training. Examples in agent prompts accelerate learning. + +#### Pure in-context learning (zero pre-training examples) + +| Tag | Closest pre-training analog | Why it's custom | +|-----|---------------------------|-----------------| +| `@RATIONALE` | `@note` | No documentation system has "architectural decision rationale" as a tag | +| `@REJECTED` | `@deprecated` (for removed), `@warning` | No system records "considered and rejected alternative" | +| `@SIDE_EFFECT` | None | No documentation system tags side effects explicitly | +| `@DATA_CONTRACT` | `@param` / `@returns` | No system has "DTO mapping Input→Output" as a tag | +| `@RELATION` | `@see` (link only) | No system has typed edges with predicates (DEPENDS_ON, CALLS...) | +| `@UX_STATE` | None | UX state machines exist in no documentation system | +| `@UX_FEEDBACK` | None | — | +| `@UX_RECOVERY` | None | — | +| `@UX_REACTIVITY` | None | — | +| `@UX_TEST` | `@test` (Doxygen) | Doxygen's `@test` is for test cases, not UX interaction scenarios | +| `@TEST_EDGE` | None | Edge case documentation exists nowhere | +| `@TEST_INVARIANT` | None | — | + +**Rule:** Every appearance of these tags in agent prompts and skill examples is **critical training material.** The model has zero pre-trained knowledge of their format. Consistency across planner → coder → QA examples is paramount — deviation in one agent creates confusion in all others. In-context examples MUST be canonical and unchanging. + ## I. GLOBAL INVARIANTS (specification) - **[INV_1]:** Every function, class, and module MUST have a `#region`/`#endregion` contract. Naked code is unreviewable. @@ -33,13 +79,22 @@ description: Reference manual for GRACE-Poly v2.6 — syntax formats, complexity ### Primary — Region (recommended for Python, JS/TS, Rust) ```python -# #region ContractId [C:N] [TYPE TypeName] [SEMANTICS tag1,tag2] +# #region Domain.Name [C:N] [TYPE Module] [SEMANTICS tag1,tag2] +# @defgroup Domain One-line description of this domain. # ← groups children + serves as @BRIEF +# @RELATION ... + +# #region Domain.Name.Action [C:N] [TYPE Function] [SEMANTICS domain,action] +# @ingroup Domain # @BRIEF One-line description # @RELATION PREDICATE -> [TargetId] - -# #endregion ContractId + +# #endregion Domain.Name.Action + +# #endregion Domain.Name ``` +**Module contracts:** `@defgroup` replaces `@BRIEF` — it declares the group AND describes what the domain does. Child contracts: `@ingroup` on line 2 joins the group; `@BRIEF` on line 3 describes the specific contract. + ### Legacy — DEF (permanently recognized) ```python // [DEF:ContractId:Type] @@ -200,13 +255,26 @@ Contract IDs MUST use dot-separated domain prefixes with 2-3 levels of hierarchy ### ATTN_3 — SEMANTIC GROUPING (DSA Lightning Indexer) -The DSA Indexer scores compressed records by keyword match against the query. `@SEMANTICS` keywords are your index keys: +The DSA Indexer scores compressed records by keyword match against the query. Two complementary mechanisms: +**`[SEMANTICS ...]` in anchor (CSA 4× density):** - All contracts in the `auth` domain MUST share `[SEMANTICS auth, ...]`. - `grep "@SEMANTICS.*auth"` → Indexer scores all auth records high. -- If one auth contract uses `@SEMANTICS login` and another `@SEMANTICS authentication`, the Indexer may fail to group them. +- If one auth contract uses `[SEMANTICS login]` and another `[SEMANTICS authentication]`, the Indexer may fail to group them. -**Rule:** Identical domain = identical primary keyword in `@SEMANTICS`. Secondary keywords can vary. +**`@ingroup Domain` on line 2 (HCA 128× pre-training):** +- The model has seen `@ingroup` in Doxygen millions of times as a grouping mechanism. +- Adding `@ingroup Auth` on line 2 (after the anchor) provides pre-training-recognized DSA grouping. +- **Recommended for all new C3+ contracts.** Not required for C1/C2 inside a parent module with `@ingroup`. + +Example — both mechanisms reinforce each other: +``` +#region Core.Auth.Login [C:4] [TYPE Function] [SEMANTICS auth,login,token] +# @ingroup Auth +# @BRIEF Authenticate user by credentials. +``` + +**Rule:** Identical domain = identical primary keyword in `[SEMANTICS ...]` AND identical `@ingroup Domain`. They target different compression layers (CSA vs HCA) and don't conflict — the keyword repetition amplifies the DSA score. ### ATTN_4 — FRACTAL BOUNDARIES (Sliding Window) @@ -224,6 +292,9 @@ When Axiom MCP is down, these grep patterns exploit the DSA Indexer's keyword se # Find all contracts in a domain (Indexer matches @SEMANTICS keywords) grep -r "@SEMANTICS.*" src/ +# Find all contracts in a @defgroup (pre-training-recognized Doxygen pattern) +grep -r "@ingroup.*" src/ + # Find API type binding (cross-stack traceability) grep -r "@DATA_CONTRACT.*" src/ @@ -232,6 +303,9 @@ awk '/#region /,/#endregion /' file.py # Find all contracts BIND_TO a store grep -r "BINDS_TO.*\[\]" src/ + +# Find cross-references by @see (pre-training-recognized — alternative to @RELATION for simple links) +grep -r "@see.*" src/ ``` #endregion Std.Semantics.Core diff --git a/.opencode/skills/semantics-python/SKILL.md b/.opencode/skills/semantics-python/SKILL.md index ea7520bc..77d7b1c9 100644 --- a/.opencode/skills/semantics-python/SKILL.md +++ b/.opencode/skills/semantics-python/SKILL.md @@ -81,10 +81,11 @@ def format_timestamp(ts: datetime) -> str: ### C3 (Flow) — Module with nested functions, service layer ```python # #region Migration.Dashboard [C:3] [TYPE Module] [SEMANTICS migration,dashboard] -# @BRIEF Dashboard migration service — export/import dashboards with validation. +# @defgroup Migration Dashboard export/import with validation. # @LAYER Service # #region Migration.Dashboard.Migrate [C:3] [TYPE Function] [SEMANTICS migration,dashboard] +# @ingroup Migration # @BRIEF Migrate a single dashboard from source to target Superset instance. # @RELATION DEPENDS_ON -> [SupersetClient] # @RELATION DEPENDS_ON -> [DashboardValidator] @@ -102,6 +103,7 @@ def migrate_dashboard(source_client, target_client, dashboard_id: str, db_mappin ### C4 (Orchestration) — Stateful operations with belief runtime ```python # #region Migration.RunTask [C:4] [TYPE Function] [SEMANTICS migration,task,state] +# @ingroup Migration # @BRIEF Execute a full migration task with rollback capability and progress reporting. # @PRE Database connection is established. Task record exists with valid migration plan. # @POST Task status updated to COMPLETED or FAILED. Migration audit log written. @@ -139,6 +141,7 @@ async def run_migration_task(task_id: str, db_session) -> dict: ### C5 (Critical) — With decision memory ```python # #region Index.Rebuild [C:5] [TYPE Function] [SEMANTICS indexing,recovery,semantic] +# @ingroup Index # @BRIEF Rebuild the full semantic index from source with atomic swap and rollback. # @PRE Workspace root is accessible. Source files exist. # @POST New index atomically swapped; old preserved for rollback. diff --git a/.opencode/skills/semantics-svelte/SKILL.md b/.opencode/skills/semantics-svelte/SKILL.md index 1d6914db..c4a1fbf3 100644 --- a/.opencode/skills/semantics-svelte/SKILL.md +++ b/.opencode/skills/semantics-svelte/SKILL.md @@ -91,6 +91,7 @@ Models use the **`.svelte.ts`** extension (not plain `.ts`) because they rely on ```typescript // frontend/src/lib/models/UsersListModel.svelte.ts // #region Users.ListModel [C:4] [TYPE Model] [SEMANTICS users,list,screen-model] +// @ingroup Users // @BRIEF State model for the user list screen — declares atoms, invariants, and actions. // @INVARIANT Changing filter (search, role, status) resets pagination to page 1. // @INVARIANT Deleting a user removes it from the list and decrements total count atomically. diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md index 0df92d98..baa1a7fd 100644 --- a/.specify/templates/plan-template.md +++ b/.specify/templates/plan-template.md @@ -96,10 +96,11 @@ Every contract generated in Phase 1 MUST pass these checks (from `semantics-core ### Anchor Syntax (canonical) -- Python: `# #region ContractId [C:N] [TYPE TypeName] [SEMANTICS tags]` / `# #endregion ContractId` -- Svelte markup: `` / `` -- Svelte/TypeScript model: `// #region ModelName [C:N] [TYPE Model] [SEMANTICS tags]` / `// #endregion ModelName` -- Markdown/ADR: `## @{ ContractId [C:N] [TYPE TypeName]` / `## @} ContractId` +- Python: `# #region Domain.Name [C:N] [TYPE TypeName] [SEMANTICS tags]` / `# #endregion Domain.Name` +- Svelte markup: `` / `` +- Svelte/TypeScript model: `// #region Domain.Name [C:N] [TYPE Model] [SEMANTICS tags]` / `// #endregion Domain.Name` +- Markdown/ADR: `## @{ Domain.Name [C:N] [TYPE TypeName]` / `## @} Domain.Name` +- **For modules: `@defgroup Domain Description` on line 2 declares the group.** Child contracts use `@ingroup Domain` to join. - **Legacy `[DEF:id:Type]` syntax is deprecated** — use `#region` format exclusively. - **Model files use `.svelte.ts` extension** — canonical format for contracts with Svelte reactive primitives.