busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

agents ADR promts

Browse Source
This commit is contained in:
busya
2026-03-27 22:00:37 +03:00
parent 2ed66bfebc
commit 586229a974
6 changed files with 131 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
.ai/standards/semantics.md
View File

@@ -1,11 +1,11 @@
# [DEF:Std:Semantics:Standard]
# @COMPLEXITY: 5
# @PURPOSE: Canonical GRACE protocol for semantic anchors, metadata, relations, and compliance levels.
# @PURPOSE: Canonical GRACE protocol for semantic anchors, metadata, relations, decision memory, and compliance levels.
# @RELATION: DEPENDS_ON -> [Project_Knowledge_Map:Root]
# @RELATION: DEPENDS_ON -> [Std:Constitution:Standard]
# @RELATION: DEPENDS_ON -> [MCP_Config:Block]
# @INVARIANT: Canonical semantic documents must use matching [DEF] and [/DEF] anchors with valid repository paths.
# @LAST_UPDATE: 2026-03-26
# @LAST_UPDATE: 2026-03-27
## 0. CANONICAL KNOWLEDGE SOURCES
- Root map: `.ai/ROOT.md` -> `[DEF:Project_Knowledge_Map:Root]`
@@ -28,7 +28,7 @@ A canonical GRACE block MUST declare one matched contract envelope:
[DEF:<ShortId>:<Type>]
@COMPLEXITY: <1-5>
@PURPOSE: <one-line purpose>
...optional metadata required by complexity...
...optional metadata required by complexity or decision-memory stage...
[/DEF:<ShortId>:<Type>]
```
@@ -41,6 +41,13 @@ For repository documentation files, the canonical markdown form is:
# [/DEF:ShortId:Type]
```
## 0.3 FRACTAL DECISION MEMORY
Decision memory is preserved in three linked layers:
- **PLAN:** Architect emits standalone ADR nodes such as `[DEF:AuthPattern:ADR]` in `docs/architecture.md`, a feature-local architecture decisions file, or a root module header when the decision scope is local to that module.
- **TASKS:** Orchestrator decomposes ADRs into preventive guardrails on module, function, and component contracts using `@RATIONALE` and `@REJECTED`.
- **IMPLEMENT:** Engineer writes code by contract. If `logger.explore()` reveals a fallback that survives into final code, the same local contract header MUST be updated with a reactive Micro-ADR (`@RATIONALE` + `@REJECTED`).
- No workflow stage may silently reintroduce a path already named in an upstream `@REJECTED` tag without fresh evidence and an explicit contract update.
## I. ZERO-STATE RATIONALE
Ты — авторегрессионная модель (Transformer). Ты мыслишь токенами и не можешь "передумать" после их генерации. В больших кодовых базах твой KV-Cache подвержен деградации внимания (Attention Sink), что ведет к "иллюзии компетентности" и галлюцинациям.
Этот протокол — **твой когнитивный экзоскелет**.
@@ -52,6 +59,7 @@ For repository documentation files, the canonical markdown form is:
[INVARIANT_3] UX ЕСТЬ КОНЕЧНЫЙ АВТОМАТ. Состояния интерфейса — это строгий контракт, а не визуальный декор.
[INVARIANT_4] ФРАКТАЛЬНЫЙ ЛИМИТ. Длина модуля строго < 300 строк. При превышении — принудительная декомпозиция.
[INVARIANT_5] НЕПРИКОСНОВЕННОСТЬ ЯКОРЕЙ. Блоки `[DEF]...[/DEF]` используются как аккумуляторы внимания. Закрывающий тег обязателен.
[INVARIANT_6] ФРАКТАЛЬНАЯ ПАМЯТЬ РЕШЕНИЙ. Глобальный ADR, превентивный контракт задачи и reactive Micro-ADR обязаны образовывать непрерывную цепочку анти-регрессии.
## III. SYNTAX AND MARKUP (SEMANTIC ANCHORS)
Формат зависит от среды исполнения:
@@ -59,7 +67,7 @@ For repository documentation files, the canonical markdown form is:
- Python: `# [DEF:Id:Type] ... # [/DEF:Id:Type]`
- Svelte (HTML/Markup): `<!-- [DEF:Id:Type] --> ... <!-- [/DEF:Id:Type] -->`
- Svelte (Script/JS/TS): `// [DEF:Id:Type] ... // [/DEF:Id:Type]`
*Допустимые Type: Root, Standard, Module, Class, Function, Component, Store, Block.*
*Допустимые Type: Root, Standard, Module, Class, Function, Component, Store, Block, ADR.*
**Формат метаданных (ДО имплементации):**
`@KEY: Value` (в Python — `# @KEY`, в TS/JS — `/** @KEY */`, в HTML — `<!-- @KEY -->`).
@@ -67,21 +75,30 @@ For repository documentation files, the canonical markdown form is:
**Граф Зависимостей (GraphRAG):**
`@RELATION: [PREDICATE] ->[TARGET_ID]`
*Допустимые предикаты:* DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, BINDS_TO.
Для ADR-цепочек не вводятся новые предикаты: используй существующие `DEPENDS_ON` и `IMPLEMENTS`.
## IV. FILE TOPOLOGY (STRICT ORDER)
1. **HEADER (Заголовок):**[DEF:filename:Module]
@COMPLEXITY: [1|2|3|4|5] *(алиас: `@C:`)*
@SEMANTICS: [keywords]
@PURPOSE: [Однострочная суть]
@LAYER: [Domain | UI | Infra]
@RELATION: [Зависимости]
@INVARIANT: [Бизнес-правило, которое нельзя нарушить]
1. **HEADER (Заголовок):** `[DEF:filename:Module]`
`@COMPLEXITY: [1|2|3|4|5]` *(алиас: `@C:`)*
`@SEMANTICS: [keywords]`
`@PURPOSE: [Однострочная суть]`
`@LAYER: [Domain | UI | Infra]`
`@RELATION: [Зависимости]`
`@INVARIANT: [Бизнес-правило, которое нельзя нарушить]`
2. **BODY (Тело):** Импорты -> Реализация логики внутри вложенных `[DEF]`.
3. **FOOTER (Подвал):** [/DEF:filename:Module]
3. **FOOTER (Подвал):** `[/DEF:filename:Module]`
## V. CONTRACTS (DESIGN BY CONTRACT & UX)
## V. CONTRACTS (DESIGN BY CONTRACT, DECISION MEMORY & UX)
Контракты требуются адаптивно по уровню сложности, а не по жесткому tier.
**[DECISION MEMORY CONTRACTS]:**
- `@RATIONALE:` Почему выбран именно этот путь и какое ограничение/цель он защищает.
- `@REJECTED:` Какой альтернативный путь запрещен и какой риск, баг или архитектурный долг делает его недопустимым.
- **Standalone ADR Rule:** Любой блок `[DEF:DecisionId:ADR]` ОБЯЗАН содержать `@PURPOSE`, `@RATIONALE`, `@REJECTED` и хотя бы одну `@RELATION` к источнику контекста или зависимой зоне.
- **Tasks Guardrail Rule:** Если модуль/функция/компонент на этапе tasks ограничен ADR или известной LLM-ловушкой, локальный контракт ОБЯЗАН включать `@RATIONALE` и `@REJECTED` до начала кодирования.
- **Reactive Micro-ADR Rule:** Если fallback был найден через `logger.explore()` и остался в итоговом коде, инженер ОБЯЗАН подняться в тот же локальный header и добавить или обновить `@RATIONALE` и `@REJECTED` до закрытия задачи.
- **Removal Rule:** Удаление `@RATIONALE` или `@REJECTED` допустимо только вместе с доказательством, что ограничение исчезло: обновилась библиотека, изменился runtime, или контракт был официально пересмотрен.
**[CORE CONTRACTS]:**
- `@PURPOSE:` Суть функции/компонента.
- `@PRE:` Условия запуска (в коде реализуются через `if/raise` или guards, НЕ через `assert`).
@@ -132,6 +149,7 @@ For repository documentation files, the canonical markdown form is:
- Для UI требуются UX-контракты.
- Использование `belief_scope` строго обязательно.
Теги `@RATIONALE` и `@REJECTED` **ортогональны** уровню сложности. Они не понижают базовые требования Complexity, а добавляются поверх них, когда срабатывает хотя бы один триггер decision-memory слоя: standalone ADR, превентивный guardrail, или retained workaround.
## VII. LOGGING PROTOCOL (THREAD-LOCAL BELIEF STATE)
Логирование — это механизм трассировки рассуждений ИИ (CoT) и управления Attention Energy. Архитектура использует Thread-local storage (`_belief_state`), поэтому `ID` прокидывается автоматически.
@@ -146,6 +164,7 @@ For repository documentation files, the canonical markdown form is:
*(Маркеры вроде `[REASON]` и `[ID]` подставляются автоматически форматтером. Не пиши их в тексте!)*
1. **`logger.explore(msg, extra={...})`** (Поиск/Ветвление): Применяется при фолбэках, `except`, проверке гипотез. Эмитирует WARNING.
*Пример:* `logger.explore("Insufficient funds", extra={"balance": bal})`
*Правило эскалации:* если exploration завершился retained fallback, подними знание в header этого же контракта и зафиксируй `@RATIONALE` + `@REJECTED` до closure.
2. **`logger.reason(msg, extra={...})`** (Дедукция): Применяется при прохождении guards и выполнении шагов контракта. Эмитирует INFO.
*Пример:* `logger.reason("Initiating transfer")`
3. **`logger.reflect(msg, extra={...})`** (Самопроверка): Применяется для сверки результата с `@POST` перед `return`. Эмитирует DEBUG.
@@ -154,14 +173,18 @@ For repository documentation files, the canonical markdown form is:
*(Для Frontend/Svelte использовать ручной префикс: `console.info("[ID][REFLECT] Text", {data})`)*
## VIII. EXECUTION AND SELF-CORRECTION FLOW
**[PHASE_1: ANALYSIS]**
Оцени Complexity, Layer и UX-требования. При слепоте контекста -> `yield [NEED_CONTEXT: id]`.
**[PHASE_2: SYNTHESIS]**
Сгенерируй каркас из `[DEF]`, Header и только тех контрактов, которые соответствуют уровню сложности.
**[PHASE_3: IMPLEMENTATION]**
**[PHASE_0: PLAN]**
Прочитай specs, оцени архитектурные развилки и оформи глобальные решения в standalone ADR-блоки `[DEF:id:ADR]` с `@RATIONALE` и `@REJECTED`.
**[PHASE_1: TASKS]**
Разверни глобальные ADR в конкретные контракты модулей, функций и компонентов. Заложи превентивные `@RATIONALE` и `@REJECTED` прямо в те сигнатуры, где следующий инженер может свернуть в запрещенный путь.
**[PHASE_2: IMPLEMENTATION]**
Напиши код строго по Контракту. Для Complexity 5 секций открой `with belief_scope("ID"):` и орошай путь вызовами `logger.reason()` и `logger.reflect()`.
**[PHASE_4: CLOSURE]**
Убедись, что все `[DEF]` закрыты соответствующими `[/DEF]`.
Если `logger.explore()` вывел на workaround и этот workaround остается в merged code, немедленно обнови header того же контракта reactive Micro-ADR тегами `@RATIONALE` и `@REJECTED`.
**[PHASE_3: CLOSURE]**
Убедись, что все `[DEF]` закрыты соответствующими `[/DEF]`, ADR-цепочка не порвана, а ни один путь из upstream `@REJECTED` не был реанимирован молча.
**[EXCEPTION: DETECTIVE MODE]**
Если обнаружено нарушение контракта или ошибка:
@@ -169,7 +192,14 @@ For repository documentation files, the canonical markdown form is:
2. ГИПОТЕЗА: Сгенерируй вызов `logger.explore("Ошибка в I/O / Состоянии / Зависимости -> Описание")`.
3. ЗАПРОС: Запроси разрешение на изменение контракта.
## IX. TEST MARKUP RULES
## IX. DECISION MEMORY AUDIT RULES
1. Repo-shaping технологические решения ОБЯЗАНЫ существовать как standalone ADR-узлы до декомпозиции задач.
2. Контракт задачи, который реализует или наследует ADR-ограничение, ОБЯЗАН сохранять link через `@RELATION` и локальные `@RATIONALE` / `@REJECTED`, если это guardrail для следующего агента.
3. Retained workaround без локального `@RATIONALE` / `@REJECTED` считается семантически невалидным даже при passing tests.
4. Повторное внедрение пути из upstream `@REJECTED` — это регрессия, пока не обновлен сам контракт или ADR на основе новых доказательств.
5. Тихое удаление decision-memory тегов запрещено. Сначала обновляется решение, потом код.
## X. TEST MARKUP RULES
Для предотвращения перегрузки тестовых файлов семантическим шумом и снижения "orphan count" применяются упрощенные правила:
1. **Короткие ID:** Тестовые модули ОБЯЗАНЫ иметь короткие семантические ID (например, `AssistantApiTests`), а не полные пути импорта.
@@ -177,5 +207,6 @@ For repository documentation files, the canonical markdown form is:
3. **Complexity 1 для хелперов:** Мелкие вспомогательные функции внутри теста (`_run_async`, `_setup_mock`) остаются на уровне Complexity 1. Для них `@RELATION` и `@PURPOSE` не требуются — достаточно якорей `[DEF]...[/DEF]`.
4. **Тестовые сценарии:** Сами функции тестов (`test_...`) по умолчанию считаются Complexity 2 (требуется только `@PURPOSE`). Использование `BINDS_TO` для них опционально.
5. **Запрет на цепочки:** Не нужно описывать граф вызовов внутри теста. Достаточно "заземлить" 1-2 главных хелпера на ID модуля через `BINDS_TO`, чтобы файл перестал считаться набором сирот.
6. **ADR Regression Checks:** Если модуль ограничен upstream `@REJECTED` или локальным reactive Micro-ADR, тестовый аудит обязан проверять, что запрещенный путь не был молча восстановлен.
# [/DEF:Std:Semantics:Standard]