docs: establish workspace engineering conventions

AGENTS.md

@@ -1,29 +1,31 @@
-# WealthLedger
+# WealthLedger workspace
 
-## Workspace
+`frontend`, `backend`, `docs`, `specs` и root — независимые Git-репозитории.
+Root tracking ограничен allowlist; локальные данные и nested repos в него
+не добавляются. `references/**`, dated audits и архивы — read-only.
+Структура/запуск — в [README](README.md).
 
-`frontend`, `backend`, `docs` и `specs` — независимые Git-репозитории.
-Root — отдельный Git-репозиторий `WealthLedger/main`; команды Git выполняй
-из нужного repo. Root tracking ограничен allowlist в `.gitignore`;
-вложенные repos и локальные данные в main не добавляй, включая `git add -f`.
-Структура checkout и запуск — в [README](README.md).
-`references/**`, dated audits и архивы — read-only источники.
+Начни с результата задачи и affected areas. Прочитай local AGENTS затронутого
+repo; проследи поведение/инварианты и найди owner с 1–3 примерами до реализации.
+Код показывает механизм, а случайный аналог не переопределяет контракт.
+Работай напрямую; OpenSpec/SDD lifecycle нужен только по явному запросу.
 
-## Работа
-
-1. Начинай с задачи пользователя, ожидаемого результата и affected areas. Работай напрямую: OpenSpec/SDD artifacts, approvals и archive не являются prerequisite. Используй прежний SDD workflow только по явному запросу.
-2. Прочитай local `AGENTS.md` affected repo. Для frontend/backend прочитай его `.ai/CONVENTIONS.md` и `.ai/SOURCES.md`, затем только темы, которые активируют задача, пути или обнаруженная граница.
-3. До выбора реализации проследи поведение и инварианты, найди ближайший существующий owner и 1–3 подходящих примера. Код показывает реализацию; документированный контракт не выводится из случайного аналога.
-4. Выбирай простейшее полное решение у ответственного владельца. Новая abstraction или dependency требует текущей потребности; посторонний рефакторинг оставляй отдельно.
-5. Выбирай тип знания по задаче через [вход docs](docs/README.md): новая функция или межрепозиторное поведение → соответствующая область, спецификации, нужные ADR, затем реализация; ошибка с неясным ожиданием → спецификация, docs, код и тесты; архитектурное изменение → архитектура/ADR, затронутые спецификации и код. Локальная ошибка сборки, линтера или очевидный implementation bug → инструкции и код нужного repo; документация → docs/AGENTS.md и CONTRIBUTING.md. Расширяй контекст по конкретному пробелу; missing required source или конфликт требований сообщи до зависимого решения.
-6. При новой границе и перед завершением повтори routing по actual staged, unstaged и новым файлам. Сохраняй чужие изменения; уточнение контекста не расширяет задачу.
-7. Проверь результат по задаче, рискованным случаям и local gates. Сохрани краткие команды/результаты; сообщи оставшиеся ограничения. Успех lint/tests не заменяет semantic review.
+| Задача / граница | Прочитать |
+| --- | --- |
+| Frontend / backend | [Frontend](frontend/AGENTS.md) / [Backend](backend/AGENTS.md), затем только активированные темы |
+| Docs / specs | [Docs AGENTS](docs/AGENTS.md) / [Specs AGENTS](specs/AGENTS.md) |
+| Новая функция, неясное ожидание, межрепозиторное поведение | [Docs entry](docs/README.md) → нужная область/spec/ADR; локальный build/lint bug начинает с repo instructions/code |
+| Новый helper/hook/wrapper/pattern, refactor, выбор scope | [Code health / change scope](.ai/conventions/code-health.md) |
+| Dependency или tooling | [Dependencies](.ai/conventions/dependencies.md), [guardrails](.ai/conventions/guardrails.md) |
+| Нетривиальные tests | [Test Intent](.ai/conventions/testing.md) и local Testing |
+| Git, ветка, commit, PR, tracking | [Git](.ai/conventions/git.md) |
+| Release/hotfix, main↔develop, release config/CI refs | [Release process](README.md#релизы-и-ветки) |
+| Migration существующих conventions findings | [Audit/plan](.ai/migrations/conventions-v1/plan.md) |
 
 Перед Node-командой активируй `.nvmrc` affected repo через `nvm use --silent`.
-
-## Ветки и релизы
-
-Новая работа — в отдельной ветке от `develop`, затем PR в `develop`.
-Прямой push в `main` запрещён. Commits и заголовки PR — Conventional Commits.
-Перед release/hotfix, merge между `main` и `develop`, изменением release-конфигурации
-или CI refs прочитай [процесс релиза](README.md#релизы-и-ветки).
+При новой границе и перед завершением повтори routing по staged/unstaged/new
+files; сохраняй чужие изменения. Missing required source или конфликт требований
+сообщи до зависимого решения. После code diff выполни
+[Boy Scout review](.ai/conventions/code-health.md#boy-scout-review); проверь результат
+по рискам и [relevant gates](.ai/conventions/guardrails.md#выбор-финального-gate).
+Сохрани краткие команды/результаты и ограничения; успех lint не заменяет semantic review.