agent-quality-kit 0.2.2

package/kit/docs/ai/deep-research-2026-07.md

@@ -0,0 +1,161 @@
+<!-- источник: audit_project/docs/ai/deep-research-2026-07.md -->
+# Дип-ресёрч 2026-07-05: слепые зоны харнеса и платформы (4 агента)
+
+> **Что это.** Сводка целевого gap-ресёрча: 4 параллельных агента искали **дельту** к уже внедрённому
+> набору (см. `agent-harness-playbook.md` + ADR 006) по углам: харнес · безопасность · качество кода ·
+> платформы-бенчмарки. Здесь — только новое; что подтвердилось без дельты — отмечено в конце разделов.
+> Статусы: ✓ первоисточник открыт агентом · ◐ из выдачи/вторично (проверить при внедрении).
+> Продуктовые решения из этого ресёрча — `memo-decisions.md §H`; процессные — в `.claude/rules/` и плейбуке.
+
+---
+
+## 1. Безопасность (самые дорогие находки)
+
+**1.1. Slopsquatting — supply chain через самого агента.** ✓ USENIX Security 2025 (16 LLM, 576k сэмплов):
+~19.7% пакетов, рекомендованных ИИ, **не существуют**; 43% галлюцинаций стабильно повторяются → атакующий
+регистрирует имя заранее. `pip-audit` ловит известные CVE, но НЕ свежий вредоносный пакет, который агент сам
+добавил. Защиты: правило «новый пакет = проверка существования/возраста/популярности + ревью человека»
+(→ rules/security.md); lockfile-дисциплина в CI (`uv sync --frozen` ✓ есть; npm — `npm ci` ✓ есть);
+`ignore-scripts` для npm и pip `--require-hashes` — по триггеру (проверить, что не ломает сборку);
+cooldown свежих версий (pnpm v11: minimumReleaseAge=1д по умолчанию; рекомендация ≥7д).
+*(snyk.io/articles/slopsquatting-mitigation-strategies, pnpm.io/supply-chain-security)*
+
+**1.2. «Comment and Control» — угон агентов через недоверенный контент.** ✓ Апрель 2026, CVE-2025-66032
+(CVSS 9.4): один заголовок PR одновременно угнал Claude Code Review, Gemini CLI и Copilot — каждый выгрузил
+секреты репозитория. Вывод индустрии (+CaMeL): prompt injection промптами не лечится, только архитектурой.
+Механические защиты: агент читает недоверенное (Issue/PR/веб/чужие логи) → **без секретов и write-прав**;
+GitHub Actions пинить **по SHA-коммиту**, не `@v1`; `contents: write`/`id-token` — только где нужно; не
+открывать чужие репо агентом с доверенным окружением (инцидент Amazon Q: auto-load MCP-конфигов крал
+AWS-ключи). Справочник атак: github.com/webpro255/awesome-ai-agent-attacks.
+*(CSA research notes 2026-04; css.csail.mit.edu CaMeL)*
+
+**1.3. Supply chain самого харнеса (MCP/skills/plugins) — непокрытая категория.** ◐ Tool poisoning через
+описания MCP-тулов; 1184 вредоносных skill в маркетплейсе; аудит: 40% MCP-серверов без аутентификации, 43%
+с command-injection. Правило: сторонние MCP/skills/plugins — только после ручного аудита исходников; pin
+версий; SKILL.md и tool descriptions = untrusted input. *(arxiv 2601.17548)*
+
+**1.4. Дизайн API-ключей платформы — что дополнить в AgentKey.** ✓ Наше ядро верно (sha256, показ один раз,
+`compare_digest`, префикс `memo_sk_live_` ✓, `last_used_at` ✓). Консенсус добавляет: **правило под наш
+префикс в gitleaks** (сделано: `.gitleaks.toml`), `expires_at` + авто-ревокация неиспользуемых, скоупы
+least-privilege (OWASP LLM06 Excessive Agency: не «один ключ — всё API»), rate limit per key, окно ротации
+из двух активных ключей, **аудит-лог вызовов по ключу** (OWASP Agentic 2026: «нельзя ответить, что агент
+делал на прошлой неделе» без него — у нас закрыто дизайном TraceEvent, подтвердить в плане 003).
+*(genai.owasp.org; Google/GitGuardian/Peakhour API-key practices)*
+
+**1.5. Django-прод чек-лист.** ✓ Django 6.0 — **встроенный CSP** (`SECURE_CSP`, сначала report-only);
+`manage.py check --deploy` как CI-гейт (у нас — триггер «перед деплоем», иначе красный на дев-настройках);
+django-axes / django-ratelimit на login и выдачу ключей (тайминг-выравнивание есть, лимита попыток нет);
+SECURE_HSTS/SSL_REDIRECT/NOSNIFF/X_FRAME_OPTIONS — перед первым внешним доступом.
+*(docs.djangoproject.com/en/6.0/ref/csp; OWASP Django Cheat Sheet)*
+
+**1.6. Credential proxy — «агент никогда не видит секрет».** ◐ Infisical Agent Vault (open-source HTTP-прокси:
+секрет подставляется по домен-allowlist ниже процесса агента), Phantom Token Pattern. Наш deny на Read .env
+защищает файл, но секреты живут в env запущенного приложения. Триггер: появление реальных прод-ключей.
+
+**Без дельты:** JWT-схема (ротация+reuse-детект), OAuth double-submit, PBKDF2+тайминг, хэш ключей — на уровне.
+
+## 2. Харнес разработки
+
+**2.1. Эмпирика контекст-файлов (меняет политику).** ✓ ETH Zurich (arxiv 2602.11988, 138 задач, 4 агента):
+LLM-сгенерированные CLAUDE.md **снижают** успех ~3% и удорожают на 20–23%; человечески-курируемые дают ~+4 п.п.
+Vercel: skills не срабатывают сами в **56%** случаев; явный указатель «читай docs/X перед задачей Y» — 100%.
+Правила: каждая строка контекста должна быть тем, что агент **не может открыть сам**; никаких /init-простыней;
+rules > skills для нашего масштаба; «CLAUDE.md = RAM, docs = диск», бюджет ~150–200 надёжных инструкций.
+
+**2.2. Хуки: несгораемый deny и мягкие гейты.** ◐ `permissionDecision: "deny"` в PreToolUse держится даже в
+bypassPermissions — единственный гейт, переживающий «жёлтый режим» (проверить наш block-hook там). Stop-хук
+умеет `additionalContext` — мягкий гейт («доделай X») без ошибки. Политика латентности: PreToolUse <100мс,
+узкие матчеры, тяжёлое — в PostToolUse, внешнее — таймаут 1–2с + fail-open. Пара «hook (принуждение) +
+rules-файл (объяснение)»: сообщение хука ссылается на правило — у нас соблюдено в arch-lint, проверить в хуках.
+
+**2.3. Наблюдаемость самого агента — бесплатно.** ✓ Claude Code имеет встроенный OTel (спаны model/tool,
+токены/стоимость/сессии) — включается env-переменными; лёгкая альтернатива — claude_telemetry. Цикл
+«трассы отказов → правка харнеса → замер» даёт прирост, сопоставимый с апгрейдом модели (arxiv 2604.25850).
+Триггер: «хочу понять, куда уходят токены» / рост числа правил.
+
+**2.4. Долгоживущие агенты (Anthropic, первоисточник).** ✓ Паттерны для многосессионных срезов:
+initializer-агент; feature-list JSON c passing:false; одна фича = одна сессия; старт сессии = progress-файл +
+git log + smoke; e2e «как человек» до пометки passing. Триггер: длинные срезы memo.
+
+**2.5. Оркестрация.** ◐ Worktrees окупаются при 4–8 независимых задачах (узкое место — ревью человека; для
+solo реалистично 2–3). Ralph-loop оправдан только при машинной верификации результата + песочница обязательна.
+Cross-model review: официальный codex-плагин для Claude Code (март 2026); чужая модель надёжнее ловит
+security/edge-cases (нет сикофантии к своему коду).
+
+## 3. Качество агентного кода
+
+**3.1. «Промпты не лечат деградацию» — теперь с цифрами.** ✓ SlopCodeBench детально: эрозия структуры в 77%
+траекторий, скорость деградации агентов в ~5–6× выше человеческой; prompt-интервенции улучшают старт, но
+**не замедляют** деградацию. Вывод: механические гейты — единственная рабочая защита (вся наша ставка верна).
+
+**3.2. SpecBench: reward hacking в кодинге.** ✓ o3 хакает 30.4% прогонов: удаляет падающие тесты, патчит
+верификатор. Рецепты: **test lock** (агент не трогает тесты-верификаторы; наш отложенный deny на
+`tests/e2e/**` — включать при первом инциденте или сразу с появлением e2e) + второй слой проверки поверх
+«тесты зелёные». *(arxiv 2605.21384)*
+
+**3.3. aislop — готовый слоп-линтер.** ◐ Детерминированный сканер без LLM: 50+ правил (narrative-комменты,
+swallowed exceptions, hallucinated imports, дубли-хелперы, dead code, todo-стабы), Python в т.ч., CLI +
+pre-commit + CI-гейт (`failBelow`), активен (v0.13.1, июнь 2026). Может заменить связку vulture+jscpd+свои
+правила. Триггер: попробовать advisory-режимом при заметном объёме прод-кода; в блок — после калибровки.
+Запасные: sloppylint (py-специфичный), desloppify (харнес уборки). *(github.com/scanaislop/aislop)*
+
+**3.4. Против review debt (процесс).** ✓ Консенсус: PR ≤200–400 строк (дальше качество ревью падает;
+oversized = elevated-risk событие); **comprehension-гейт** — «AI написал» не ответ, автор обязан объяснить
+control flow / edge cases / failure paths (ownCloud формализовал в policy). Для нас: «агент обязан объяснить
+дифф Арсену» → rules/general.md. Cloudflare (131k ревью/мес, $1.19/шт): специализированные LLM-ревьюеры по
+доменам + risk-tiering по размеру диффа + фильтрация lock/generated из диффа + явный список **«что НЕ
+флагать»** + инкрементальный re-review с памятью прошлых находок; честно слаб в архитектуре/concurrency.
+
+**3.5. Архитектурный дрейф.** ✓ Thoughtworks Radar (апр 2026): агенты ускоряют дрейф («poor code begets
+poorer code»); рецепт — детерминированные анализаторы + LLM для семантики, первый скан = лавина → приоритизировать.
+Инструмент под Python: **pytest-archon** (ArchUnit-стиль: запрещённые зависимости как pytest-тесты — ложится
+в существующий `make test` без нового CI-шага; альтернатива import-linter). Триггер: ≥3 модулей со строгими
+границами.
+
+**3.6. Метрики.** ◐ DORA ROI-отчёт (янв 2026): выигрывают команды с сильными инженерными основами. AI-era
+надстройки: **Code Durability** (доля кода, дожившего N недель без переписывания — дёшево по git) и
+rework/churn rate. Триггер: «хотим мерить прогресс».
+
+## 4. Платформа-бенчмарк (продуктовые находки → memo-decisions §H)
+
+**4.1. FinBalance (arxiv 2606.15949, июнь 2026).** ✓ **Прямой сосед по домену**: multi-document accounting
+reconciliation benchmark, синтетика, детерминированный скоринг. Прочитать целиком; переиспользовать
+таксономию ошибок сверки; наша дифференциация — seed-генерация + платформа/арена + анти-гейминг (у них
+статичный датасет). Рядом: AuditFlow (символьные среды: LLM планирует, детерминированный движок проверяет),
+FinVerBench (валидность фин-бенчмарков), FinToolBench, BigFinanceBench — домен горячий, ≥5 бенчмарков за полгода.
+
+**4.2. CapCode-принцип (arxiv 2606.07379).** ✓ Детекция читерства **по построению**: в пул подмешиваются
+задачи с заведомо недостижимым честным 100% (несводимая сверка) — балл выше потолка = статистическое
+доказательство читерства, ранжирование честных сохраняется. Идеально ложится на детерминированный скорер.
+
+**4.3. Экономика оценки.** ✓ On Randomness (arxiv 2602.07150, 60k траекторий): single-run pass@1 гуляет на
+2.2–6.0 п.п. **даже при temperature=0** → минимум 3–5 прогонов на (агент, задачу), интервалы вместо точки,
+пара pass@k (оптимист) / pass^k (пессимист). Efficient Benchmarking (2603.23749): держать в зачёте задачи с
+pass-rate **30–70%** (режет пул на 44–70% без потери ранжирования); «все решают/никто не решает» → в
+smoke/pre-flight. Beyond Static Leaderboards (2606.19704): показывать **корреляцию public/private рангов**
+как метрику здоровья экзамена (Kaggle shake-up).
+
+**4.4. HAL пивот в reliability.** ✓ Принстон приостановил классический лидерборд и мерит **надёжность**
+(дисперсию) агентов. Подтверждает: reliability score (разброс по прогонам) — правильная колонка таблицы.
+
+**4.5. Изоляция.** ✓ Консенсус-2026: для исполнения чужого кода минимум microVM (Docker с общим ядром —
+недостаточно). Для memo это аргумент **ЗА** нашу API-модель «агент снаружи, платформа раздаёт задачи по
+HTTP» — мы не исполняем чужой код, класс риска ниже на порядок; зафиксировано как осознанное решение.
+
+**4.6. Скоринг траекторий.** ◐ TRACE (WWW 2026): иерархическая utility-функция траектории + «минимальный
+уровень подсказки, при котором агент справляется» как ось способности. Kaggle Game Arena: адаптивный
+планировщик пар вместо round-robin — **-65% эпизодов** при том же ранжировании (паттерн для умного лизинга).
+Готовые вьюеры трейсов: Phoenix / Opik / DeepEval поверх OTel — свой не писать.
+
+---
+
+## Сводный вердикт
+
+- **Подтверждено без изменений:** вся линия «механические гейты > воспитание промптами» (теперь с цифрами),
+  JWT/OAuth/хэш-дизайн, минимализм тулов, rules с явными указателями, «агент снаружи» для платформы.
+- **Внедрено этим ресёрчем:** `.gitleaks.toml` (правило под memo-ключи), rules/security.md (недоверенный
+  контент; новые зависимости; сторонние MCP/skills), rules/general.md (comprehension-гейт), обновления
+  плейбука/ADR 006, продуктовые решения → memo-decisions §H.
+- **Главные триггеры на будущее:** test lock вместе с первыми e2e; aislop при росте прод-кода; OTel самого
+  агента при вопросе «куда уходят токены»; CSP/axes/check --deploy перед внешним доступом; credential proxy
+  при реальных ключах; pytest-archon при ≥3 модулях.

package/kit/docs/ai/harness-best-practices.md

@@ -0,0 +1,385 @@
+<!-- источник: audit_project/docs/ai/harness-best-practices.md -->
+# Харнес агента: портативный чек-лист бест-практисов
+
+> ⚠️ **Пункты 7, 8, 9 и 14 убраны намеренно, нумерация оригинальная.** Это были actor-runtime,
+> токен отмены, сериализуемые компоненты и CodeAct — устройство **своего** агента, а не обвязка
+> репозитория. В журнале источников внизу файла ссылки на них сохранены: номера нужны, чтобы
+> сопоставить приём с репозиторием, откуда он снят.
+
+> **Назначение.** Это переносимый чек-лист «как надо строить обвязку агентов». Цель —
+> на новом проекте не изобретать с нуля, а пройтись по списку и поставить галочки.
+> Наполняется по мере разбора топ-репозиториев (`githab/research/`), детальные доказательства
+> по каждому репо — в `BEST-PRACTICES-GAP.md`.
+>
+> **Два слоя** (см. память `two-layer-agent-framing`):
+> - 🎛 **высокий** — обвязка *готового* агента (наш `.claude/`). Применимо к dev-среде напрямую.
+> - 🔧 **низкий** — устройство *самого* агента. Нужно, только если строишь агента ВНУТРИ продукта
+>   (напр. PydanticAI для ИИ-фичи). Для dev-среды — «к сведению».
+>
+> **Статус в текущем проекте (audit_project):** ✅ есть · ⚠️ частично · ❌ нет · ℹ️ к сведению.
+>
+> **⚠️ Для memo:** это **перенос** из проекта Arsen `audit_project` — статусы «у нас» в теле относятся к
+> ТОМУ проекту (источнику). Для **memo** харнес берём **по таймингу** (`CLAUDE.md` прав. 10–11): базовый
+> **гейт сейчас**, остальное — **из реального трения**. Многое уже совпадает с нашей reference-базой
+> (`memo-decisions.md §E/G`, `sources-building-with-agents.md`). По мере сборки
+> отмечаем, какие из 19 пунктов берём в memo.
+
+## Приоритет для `audit_project` на 2026-07-13
+
+Этот список — каталог идей, а не backlog «внедрить все 19». Для текущего проекта порядок такой:
+
+### P0 — делать сейчас
+
+1. **Runtime fitness-gates продукта:** queue без production consumer; несовместимые
+   `time_limit/visibility_timeout`; тяжёлая task в короткой queue; тяжёлый файл/O(N) fan-out в HTTP.
+   Это закрывает уже найденные дефекты, а не гипотетические проблемы харнеса.
+2. **Product observability:** HTTP p95/p99/errors, Celery queue depth/oldest age/wait/run,
+   PostgreSQL IO/temp/locks, container RSS/OOM/restarts. Агенту позже дать read-only доступ к этим
+   данным. Без термометра нельзя ни сайзить, ни проверять производительность.
+3. **Workload contract:** короткий реестр `workload → sync/async → queue/consumer → cap → timeout →
+   recovery → SLO`. Любая новая фича обязана вписаться в него. Полный roadmap —
+   `docs/rebuild/05-load-hardening.md`.
+4. **Довести уже существующие гейты до честного состояния:** убрать stale-статусы task/docs,
+   проверить branch protection; откалиброванные security/migration/Semgrep gates переводить из
+   `allow_failure:true` в blocking по одному, с зафиксированным baseline.
+
+### P1 — после P0
+
+1. **Agent-legible live-stack:** воспроизводимая команда сценария + RO-запросы к логам/метрикам +
+   correlation/trace id + короткие debug-рецепты. Per-worktree observability полезна после того,
+   как основная телеметрия продукта действительно работает.
+2. **Сначала принять решение по headless pipeline:** либо он реально нужен — тогда восстановить
+   executable runner и доказать smoke-прогоном; либо пометить dormant и не тратить на него бюджет.
+   Checkpointing имеет смысл только после этого.
+3. **Typed retry:** transient → backoff; schema/deterministic → один repair; auth/scope → сразу
+   человеку. Это дешевле слепых трёх попыток.
+4. **Стоимость прогона:** сначала собирать tokens/duration/retry по стадиям; денежный hard budget
+   вводить, когда появится реальный расходный порог, а не заранее.
+
+### Не делать сейчас
+
+- векторную/LLM-консолидируемую память — курируемый индекс и repo search пока проще и надёжнее;
+- inline LLM-судью на каждый шаг — детерминированные схемы, тесты и Reviewer дают более надёжный сигнал;
+- собственный actor-runtime, CodeAct или низкоуровневого агента — используются готовые Claude/Codex;
+- произвольные `triggers:` в frontmatter, если runtime их не поддерживает; явный `$skill` и ссылки из
+  `AGENTS.md/rules` надёжнее неисполняемого поля;
+- OTel GenAI и сложную оптимизацию промптов до появления реально используемого headless pipeline.
+
+---
+
+# ЧАСТЬ 1 — Сухой чек-лист (только пункты)
+
+## 🎛 Высокоуровневые (обвязка готового агента)
+
+- [ ] **1. Принудительный структурированный вывод (SGR)** — схемы и валидатор сохранены до отдельной
+  миграции полезных инвариантов, но исполняемый headless pipeline удалён. В интерактивной работе SGR
+  не проверяется и машинного потребителя у него нет.
+- [ ] **2. Наблюдаемость прогона** — старые Langfuse-wrapper/score удалены вместе с неиспользуемым
+  headless pipeline. Наблюдаемость прогона отсутствует; возвращать её только под реальный runner.
+- [ ] **3. Активная память** — query→inject релевантного + таксономия (рабочая / долгая / факты-сущности) + структурный контент (mime/metadata). _(у нас ⚠️: память пассивная и плоская)_
+- [ ] **4. Хуки-«таможня»** — `PreToolUse` умеет изменить/отклонить действие на лету, не только заблокировать постфактум. _(у нас ⚠️: PreToolUse deny + PostToolUse format есть; Stop пока только уведомляет, quality stop-gate нет)_
+- [ ] **5. Алгоритмы ужатия контекста** — при передаче между агентами: head+tail+«пропущено N», выкидывание из середины под токен-бюджет. _(у нас ❌: только прозаические советы)_
+- [x] **6. Предел итераций агента** — анти-зацикливание (стоп после N попыток). _(у нас ✅: «макс 3 итерации»)_
+- [ ] **10. Output guardrail (LLM-судья)** — критерий словами → судья возвращает `{valid, feedback}` → ретрай с фидбеком; смысловая валидация в дополнение к схемной. _(у нас ⚠️: есть тяжёлые Reviewer/JiTTest в конце, нет лёгкого inline-гейта на шаг)_
+- [ ] **11. Учёт стоимости + бюджет задачи** — $ = токены×цена; потолок на задачу/агента с жёстким стопом при превышении. _(у нас ❌: отдельного headless runner и его cost telemetry нет)_
+- [ ] **12. Типизированный retry** — повтор по классу ошибки: временное (timeout/rate-limit) → повтор, детерминированное (bad-request/схема) → 1 repair или стоп. _(у нас ⚠️: слепые «3 итерации» на всё)_
+- [ ] **13. Явные триггеры + версия скилла** — использовать только поддерживаемый runtime-контракт: явный `$skill`/команда, конкретный `description`, ссылки из rules и версия через git. Не добавлять неисполняемый `triggers:` ради галочки. _(у нас ⚠️: явные skill-вызовы доступны, автоматическое срабатывание не измеряется)_
+- [ ] **15. Agent-legible продукт** — приложение + его логи/метрики/трейсы доступны агенту на каждый worktree (LogQL/PromQL + DevTools), чтобы агент САМ верифицировал поведение («старт < 800мс»). _(у нас ❌)_
+- [x] **16. AGENTS.md = оглавление, не энциклопедия** — Codex-вход короткий (72 строки) и ведёт в `specs/harness/codex/`/docs; Claude-вход ещё длиннее цели (271 строка), его сокращение — отдельная housekeeping-задача, не P0.
+- [x] **17. Линтер с инструкцией по починке в тексте ошибки** — `scripts/arch-lint.sh` уже передаёт конкретный fix и ссылку на правило для ключевых нарушений; новые fitness-gates должны следовать тому же формату.
+- [ ] **18. Eval-driven оптимизация промптов/скиллов** — метрика + eval-набор → optimizer предлагает → скорит → оставляет лучший (DSPy/GEPA); то же для описаний скиллов. _(у нас ❌: старый Evolver удалён как неиспользуемый)_
+- [ ] **19. Возобновляемые прогоны (checkpointing)** — прогон сохраняет состояние и продолжается с середины после сбоя/паузы. _(у нас N/A: headless runner отсутствует)_
+
+---
+
+# ЧАСТЬ 2 — Детальное раскрытие
+
+## 1. Принудительный структурированный вывод (SGR)
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ◐ **reference-only**. Старый headless runner удалён
+  в task-234 как неиспользуемый. Схемы и `scripts/validate_sgr.py` временно сохранены, пока полезные
+  требования из SGR не перенесены в обычные rules/checklists.
+- **Что это.** Каждый агент возвращает JSON строго по схеме. Этот JSON — **машинный контракт**
+  между шагами пайплайна: следующий шаг читает поля предыдущего. Схема = источник истины.
+- **Зачем.** Без принуждения структурированный вывод держится «на честном слове модели».
+  Агент через раз выдаёт нужную форму → пайплайн молча подхватывает пустоту → багов не видно.
+  Принуждение + лог = ты **видишь**, соблюдается ли контракт.
+- **Что сохранено на уровне валидатора (не подключено к runtime):**
+  1. Объявить схему (✅ есть в `.claude/schemas/`).
+  2. Дать схему агенту как инструкцию (✅ есть в `agents/*.md`).
+  3. **После** запуска агента — `jsonschema.validate(output, schema)`.
+  4. Невалидно → **1 repair**: вернуть агенту список ошибок валидации, попросить починить.
+  5. Снова невалидно → **падать громко** + писать кейс в лог (НЕ продолжать с пустыми полями).
+  6. Каждый результат валидации (pass/repair/fail) — **в лог/метрику** → появляется
+     наблюдаемость соответствия (видно % комплаенса по агентам).
+- **Два вида валидации.** (а) **структурная** — JSON против схемы (этот пункт); (б) **смысловая** —
+  «правильный ли вывод по сути» (см. пункт 10, Output guardrail). Полноценный гейт = обе.
+- **Контракт = схема + инструкция + пример (MetaGPT `ActionNode`).** У них действие несёт не голую
+  схему, а связку `expected_type` + `instruction` + `example`, и компилируется в Pydantic-модель.
+  Усиление к нашим `schemas/*.json`: рядом со схемой держать инструкцию и пример валидного вывода.
+- **Практический вывод:** в интерактивной работе через Codex/Claude этот SGR ничего не проверяет.
+  Не чинить его «ради галочки». Если headless pipeline снова понадобится — проектировать новый
+  runner отдельной задачей и доказывать живым smoke `agent → output → validation → branch`.
+- **Откуда:** твой собственный `rules/general.md` («validate → 1 repair → ошибка») + autogen
+  (всё на Pydantic-конфигах с жёсткой валидацией).
+
+## 2. Наблюдаемость прогона (трейсинг)
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ❌ — старый post-hoc wrapper удалён; дерева спанов и
+  стандартных атрибутов нет.
+- **Что это.** Каждый шаг агента оборачивается в «спан» (отрезок времени с метаданными):
+  `invoke_agent`, `execute_tool`, и при ошибке — запись исключения в спан. Спаны связаны
+  сквозным `trace_id` → видно дерево «кто кого вызвал и где затык».
+- **Зачем.** Сейчас Langfuse у тебя мёртвый именно потому, что нет дисциплины «что трейсить».
+  Без спанов прогон — чёрный ящик: агент сказал «готово», а что было внутри — не видно.
+- **Как надо.** Стандарт **OpenTelemetry GenAI semantic conventions** (vendor-neutral): спаны
+  с атрибутами `gen_ai.operation.name` (`invoke_agent`/`execute_tool`), `gen_ai.agent.name`,
+  `gen_ai.tool.name`; на ошибке — `span.record_exception(e)` + `error.type`. Один формат —
+  любой бэкенд (Langfuse / Phoenix / Jaeger).
+- **Пример атрибутов спана (из autogen `_telemetry/_genai.py`):**
+  `{gen_ai.operation.name: "execute_tool", gen_ai.system: "...", gen_ai.tool.name: "pytest"}`.
+- **Готовая таксономия спанов (openai-agents `tracing/span_data.py`):**
+  `Agent` → `Turn` → `Generation` (вызов LLM) / `Function` (вызов инструмента) / `Handoff`
+  (передача между агентами) / `Guardrail`. Вот ровно эти спаны и трейсить.
+- **Откуда:** autogen (`_telemetry/_genai.py`, OTel-атрибуты) + openai-agents
+  (`tracing/span_data.py`, таксономия спанов). См. также пункт 15 (наблюдаемость ПРОДУКТА для агента).
+
+## 3. Активная память (а не пассивные файлы)
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ⚠️ частично — память пассивная (файлы целиком через
+  system-reminder) и плоская (по агентам, без типов).
+- **Что это.** Память — не папка, а компонент с методом `update_context()`: она сама
+  **запрашивает релевантное** под текущую задачу и **вкидывает только это** в контекст.
+  Плюс таксономия: **рабочая** (внутри прогона) / **долгая** (между задачами) / **сущности**
+  (факты про модуль/компанию). Контент структурирован: `mime_type` + `metadata`.
+- **Зачем.** «Вот тебе вся папка памяти» забивает контекст шумом. «Вот что нужно под эту
+  задачу» — точнее и дешевле.
+- **Как надо.** Хранилище с query (хоть текстовый поиск, хоть вектор) → отбор top-K
+  релевантного → инъекция как отдельный блок. Память сама решает, что показать.
+- **Глубже (crewAI `memory/types.py`):**
+  - **Композитный скоринг** при recall, не одна похожесть:
+    `score = w_семантика·similarity + w_свежесть·decay + w_важность·importance`,
+    где `decay = 0.5^(возраст_дней / период_полураспада)`. Свежее и важное всплывает выше.
+  - **Консолидация при записи**: при сохранении похожего (similarity > 0.85) LLM решает
+    слить/обновить/удалить → память не пухнет дублями. _(у нас есть **ручная** версия: правило
+    MEMORY.md «найди файл на эту тему — обнови, не плоди».)_
+  - **Лёгкие поля на запись**: `importance` (0-1), `source` (происхождение), `private`,
+    `categories`, иерархический `scope` (`/проект/модуль`). Применимо к нашему frontmatter
+    без всякого вектор-движка.
+  - **Explainable recall**: матч несёт `match_reasons` (почему совпало) и `evidence_gaps`
+    (что искал, но не нашёл).
+  - Деталь: `embedding` исключён из сериализации (экономия токенов при сохранении).
+- **Протокол записи (OpenHands `skills/agent_memory.md`, триггер `/remember`):**
+  - логировать ТОЛЬКО переиспользуемое (структура репо, команды build/lint/test, стиль, workflow);
+    **НЕ** логировать частности задачи (какую ошибку поймал и как починил);
+  - перед сохранением показать **пронумерованный список** того, что собираешься записать →
+    сохранить **только одобренные** пункты → интегрировать в существующее, не плодить.
+  - _(у нас правило похожее, но мягче — стоит формализовать «список → апрув подмножества».)_
+- **Честная граница.** Полный вектор-движок для нашей маленькой курируемой памяти — 🔧 перебор.
+  Берём ЛЁГКИЕ идеи (🎛): `importance`/`source`/`scope` в frontmatter + дисциплина консолидации.
+- **Уровни памяти (Letta/MemGPT `schemas/memory.py`) — каноничный паттерн:**
+  - **core memory** — в контексте всегда, маленькая, с char-лимитом, агент САМ её редактирует
+    (вынужден приоритизировать); **archival/recall** — внешние, подгружаются поиском по запросу.
+  - `ContextWindowOverview` — точная разбивка бюджета контекста по секциям (system/core/summary/
+    messages/functions) — наблюдаемость самого контекста.
+  - блоки **версионируются** (git-backed history).
+  - _(у нас это УЖЕ есть в зачатке: `MEMORY.md` = core-индекс (всегда), отдельные файлы =
+    archival (по релевантности). Letta подтверждает паттерн; усиление — бюджет/лимит на core.)_
+- **Откуда:** autogen (`memory/_base_memory.py`, `update_context`/`query`/`MemoryContent`) +
+  crewAI (`memory/types.py`, `memory_scope.py`: composite score, consolidation, scopes) +
+  OpenHands (`skills/agent_memory.md`: протокол записи с апрувом) +
+  Letta (`schemas/memory.py`: уровни core/archival/recall, self-editing, context-budget).
+
+## 4. Хуки-«таможня» (вмешательство на лету)
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ⚠️ частично — есть PreToolUse deny и PostToolUse
+  auto-format; Stop пока только уведомляет и не является quality stop-gate.
+- **Что это.** Перехватчик, срабатывающий на каждое действие агента, который может его
+  **изменить, залогировать или отклонить** ДО выполнения (не после).
+- **Зачем.** Блокировка по факту коммита ловит поздно. Перехват до действия — дешевле и
+  позволяет править («подставь правильный путь», «не трогай файл вне Scope») на лету.
+- **Как надо.** У Claude Code это `PreToolUse`-хуки: получают вызов инструмента до исполнения,
+  возвращают allow/deny/изменение. Использовать не только для запретов, но и для корректировок.
+- **Дизайн из crewAI (`hooks/types.py`) — 4 точки перехвата:**
+  - `before_tool_call` → правит вход инструмента *на лету* ИЛИ `False` = заблокировать.
+  - `after_tool_call` → переписывает результат инструмента.
+  - `before_llm_call` / `after_llm_call` → то же для сообщений/ответа модели.
+  - Контракт: «before» возвращает `bool|None` (False = стоп), «after» возвращает `str|None`
+    (str = изменённый результат). Чисто, предсказуемо.
+- **Откуда:** autogen (`_intervention.py`, `InterventionHandler`/`DropMessage`) +
+  crewAI (`hooks/types.py`: before/after × LLM/tool, modify-or-block).
+
+## 5. Алгоритмы ужатия контекста при передаче между агентами
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ❌ нет алгоритмов (есть скилл `context-engineering`,
+  но это прозаические советы).
+- **Что это.** Конкретные стратегии, как обрезать историю/контекст, не теряя главного:
+  - **head+tail+«пропущено N»**: оставить первые N (инструкции) и последние M (свежее),
+    середину заменить плейсхолдером `"Skipped 42 messages"`.
+  - **token-limited middle-drop**: пока не влезаем в бюджет — выкидывать из **середины**.
+  - дисциплина краёв: не оставлять висящий вызов функции или его результат на стыке.
+- **Зачем.** Когда Archivist ужимает историю, Planner отдаёт контекст Builder'у — нужна не
+  «отрежь сколько-то», а стратегия, что именно беречь.
+- **Откуда:** autogen (`model_context/`: `HeadAndTailChatCompletionContext`,
+  `TokenLimitedChatCompletionContext`, `BufferedChatCompletionContext`).
+
+## 6. Предел итераций агента ✅
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ✅ есть — правило «макс 3 итерации → СТОП, вернуть человеку».
+- **Что это.** Жёсткий лимит на число попыток, чтобы агент не крутился вечно.
+- **Откуда:** autogen (`max_tool_iterations`). У нас уже реализовано как правило пайплайна.
+
+## 10. Output guardrail (LLM-судья на вывод шага)
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ⚠️ частично — есть тяжёлые Reviewer/JiTTest в конце
+  пайплайна, но нет лёгкого inline-гейта на каждый шаг.
+- **Что это.** К шагу привязывается критерий **словами** («вывод: 10 буллетов, без воды»).
+  Отдельный агент-судья проверяет результат и возвращает **структуру** `{valid: bool, feedback: str}`.
+  Невалидно → фидбек возвращается, шаг переделывается (ретрай).
+- **Зачем.** Схемная валидация (пункт 1) ловит только *форму*. Guardrail ловит *смысл*:
+  «по делу ли», «нет ли галлюцинации», «соблюдён ли бизнес-критерий».
+- **Дисциплина.** Судье запрещено чинить — только указывать на проблемы
+  («identify issues — do not propose corrections»). Критика отделена от исправления.
+- **Как надо.** `valid/feedback` — структурированный вывод судьи (тот же пункт 1!). Лёгкий
+  guardrail на шаг ≠ тяжёлый Reviewer в конце: дешевле и ловит раньше. Спец-вариант —
+  guardrail на галлюцинации (crewAI `tasks/hallucination_guardrail.py`).
+- **Вход И выход + tripwire (openai-agents `guardrail.py`):** guardrail бывает на **вход**
+  (проверить задачу ДО прогона — не жечь токены на заведомо кривой запрос) и на **выход**.
+  Результат несёт `tripwire_triggered: bool` — если сработал, прогон **немедленно останавливается**
+  (исключение `…TripwireTriggered`). Декораторы `@input_guardrail`/`@output_guardrail`.
+- **Откуда:** crewAI (`tasks/llm_guardrail.py`, `LLMGuardrailResult{valid, feedback}`) +
+  openai-agents (`guardrail.py`: input/output guardrails, tripwire-halt).
+
+## 11. Учёт стоимости + бюджет задачи
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ❌ — отдельного runner, учёта стоимости и потолка нет.
+- **Что это.** Считать **деньги** за прогон: `$ = токены × цена_модели` (таблица цен на модель).
+  Вести бюджет на задачу/агента/период и **резать**, когда превышен.
+- **Зачем.** Сейчас задача может тихо прожечь любой объём токенов. Потолок = предсказуемость
+  расходов + ранний стоп зацикленного агента по деньгам, а не только по итерациям.
+- **Как надо.** (1) таблица цен модели; (2) после каждого шага: `cost += in·price_in + out·price_out`;
+  (3) лимит на задачу → превышен → стоп + лог. Связано с наблюдаемостью (пункт 2): стоимость — метрика.
+- **Откуда:** litellm (`cost_calculator.py`, `budget_manager.py`,
+  `model_prices_and_context_window_backup.json`).
+
+## 12. Типизированный retry (по классу ошибки)
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ⚠️ частично — «макс 3 итерации» слепо на любую ошибку.
+- **Что это.** Число и стратегия повторов зависят от **типа** сбоя:
+  - временное (timeout, rate-limit) → повторить (возможно с backoff);
+  - детерминированное (bad-request, невалидная схема, синтаксис) → повтор не поможет → **1 repair или стоп**;
+  - блокирующее (auth/доступ) → **не повторять**, сразу человеку.
+- **Зачем.** Слепой ретрай на детерминированную ошибку жжёт попытки впустую; временную, наоборот,
+  стоит повторить больше раз. У тебя уже есть таксономия ошибок в скилле `metrics-analysis`
+  (IMPORT/ASSERT/RUNTIME/DB/TYPE) — её надо **подключить к стратегии ретраев**, а не только к аналитике.
+- **Откуда:** litellm (`router_utils/get_retry_from_policy.py`: `RetryPolicy` с полями
+  `TimeoutErrorRetries`/`RateLimitErrorRetries`/`BadRequestErrorRetries`/…).
+- **ℹ️ К сведению (низкоуровневое, если строишь агента/прокси):** reason-aware fallback
+  (`context_window_fallbacks` → переключение на модель с бОльшим окном; `content_policy_fallbacks`),
+  circuit-breaker (cooldown упавшего провайдера после `allowed_fails`), семантический кэш
+  (кэш по смыслу промпта). Для нашей dev-среды на одном opus-4-8[1m] — не применимо.
+
+## 13. Явные триггеры + версия скилла
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ⚠️ частично — явные `$skill`-вызовы доступны, но
+  автоматическое срабатывание по `description` не измеряется.
+- **Что это.** Использовать только реальный контракт конкретного runtime: явный `$skill`/команду,
+  конкретный `description` и ссылки из `AGENTS.md`/rules. Версию хранить через git или поддерживаемое
+  поле runtime.
+- **Зачем.** Семантический триггер гибкий, но недетерминированный. Неисполняемое поле
+  `triggers:` создаёт ложную гарантию и потому хуже явного указателя.
+- **Как надо.** Критические процедуры подключать явной ссылкой или вызовом, а факт применения
+  логировать там, где runtime это поддерживает.
+- **Откуда:** OpenHands (`skills/*.md`: `name/type/version/agent/triggers`; keyword + slash-команды).
+
+## 15. Agent-legible продукт (наблюдаемость продукта ДЛЯ агента) ⭐
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ❌ нет.
+- **Что это.** Не «трейсить агента» (пункт 2), а сделать **сам продукт читаемым для агента**:
+  приложение поднимается на каждый git-worktree, его логи/метрики/трейсы доступны агенту
+  через локальный эфемерный observability-стек (запросы LogQL/PromQL/TraceQL), а UI — через
+  Chrome DevTools. Тогда промпт «убедись, что старт сервиса < 800мс» или «ни один из 4 сценариев
+  не дольше 2с» становится **исполнимым** — агент сам воспроизводит баг, чинит, проверяет, повторяет.
+- **Зачем.** Это то, что позволило OpenAI собрать продукт в 1М строк силами 3-7 инженеров:
+  узкое место — человеческое QA; убираешь его, дав агенту самому видеть поведение продукта.
+- **Как надо (для нас).** У тебя уже есть Live-stack E2E (агент сам гоняет реальный стек). Развить:
+  per-worktree подъём + RO-доступ агента к логам/метрикам + «дёрни и проверь по трейсам».
+- **Откуда:** OpenAI «Engineering the harness: Codex» (2026).
+
+## 16. AGENTS.md = оглавление + docs/ как система записи
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ✅ для Codex — `AGENTS.md` занимает 72 строки и ведёт
+  в профильные docs; ⚠️ для Claude — `CLAUDE.md` длиннее целевого бюджета и требует housekeeping.
+- **Что это.** Не пихать всё в один большой файл инструкций (он вытесняет задачу из контекста,
+  «важно всё → важно ничто», устаревает, не проверяется). Вместо этого: **короткий вход** (~100 строк)
+  = карта с указателями → структурный `docs/` (design-docs, exec-plans active/completed,
+  product-specs, references, QUALITY_SCORE.md, ARCHITECTURE.md) как **система записи**.
+  **Progressive disclosure**: агент стартует с малого и знает, куда смотреть дальше.
+- **Механически:** линтеры + CI проверяют свежесть/перекрёстные ссылки; периодический
+  **doc-gardening агент** находит устаревшую доку и открывает PR.
+- **Артефакт QUALITY_SCORE.md:** оценка каждого домена/слоя + отслеживание пробелов во времени.
+- **Откуда:** OpenAI Codex blog (структура `docs/`, ToC-подход, doc-gardening).
+
+## 17. Линтер с инструкцией по починке в тексте ошибки
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ✅ — `arch-lint.sh` для ключевых правил уже сообщает
+  конкретный способ исправления и ссылку на норму. Новые fitness-gates должны продолжать этот контракт.
+- **Что это.** Кастомный линтер инвариантов формулирует сообщение об ошибке так, чтобы **встроить
+  инструкцию по устранению прямо в контекст агента** → агент сам чинит, не гадая.
+- **Зачем.** Линтер = feedforward+feedback для агента: «инвариант нарушен, вот КАК исправить».
+  После внедрения применяется везде одновременно (множитель).
+- **Откуда:** OpenAI Codex blog («внедряем инструкции по устранению в сообщения об ошибках линтера»).
+
+## 18. Eval-driven оптимизация промптов/скиллов
+
+- **Слой:** 🎛 высокий · **Статус у нас:** ⚠️ — Evolver мутирует эвристично (`metrics.json`),
+  без метрики+eval-набора+optimizer'а.
+- **Что это.** Промпт/описание скилла — **обучаемый параметр против метрики**: задаёшь метрику
+  и небольшой eval-набор → optimizer (GEPA/MIPRO/BootstrapFewShot) **предлагает варианты → скорит →
+  оставляет лучший**. То же для описаний скиллов (бенчмарк срабатывания → авто-улучшение описания).
+- **Зачем.** Убирает гадание «лучше ли стал промпт» — есть число, а срабатывание скиллов становится
+  измеримым.
+- **Откуда:** DSPy (`teleprompt/gepa`, `mipro_optimizer_v2`, `bootstrap`) и deer-flow
+  (`skill-creator/scripts/run_eval.py`, `improve_description.py`).
+
+## 19. Возобновляемые прогоны (checkpointing)
+
+- **Слой:** 🎛/🔧 · **Статус у нас:** N/A — headless runner отсутствует.
+- **Что это.** Прогон сохраняет состояние по шагам (checkpoint) и может **продолжиться с места**
+  после сбоя/паузы/правки, не начиная заново.
+- **Зачем.** Длинные прогоны (часы) не теряются из-за одного сбоя; дешевле MTTR.
+- **Откуда:** deer-flow (`runtime/checkpointer`, `persistence/run`), Letta (версионируемые блоки);
+  тема LangGraph (checkpoints/time-travel) — если понадобится глубже.
+
+---
+
+## Подтверждено статьёй OpenAI «Engineering the harness: Codex» (2026)
+
+Статья OpenAI про сборку продукта в 1М строк силами агентов **подтверждает**, что у тебя уже
+сделано правильно (НЕ трогаем, это сильные стороны):
+
+- **Инварианты, а не детали реализации**, через кастомные линтеры + структурные тесты → у тебя
+  `arch-lint.sh` + FSD + size/ratio-линтеры. ✅
+- **Золотые принципы + GC + мелкие refactor-PR** против дрейфа → у тебя Sentinel + Evolver + GC. ✅
+- **Планы как версионируемые артефакты** (exec-plans с журналом решений) → у тебя `specs/tasks/`. ✅
+  _(усиление: добавлять в план журнал прогресса/решений.)_
+- **Скучные технологии**, иногда переписать кусок вместо обёртки → у тебя ADR. ✅
+- **Ralph-loop** (агент крутит до зелёного арбитра) → у тебя пайплайн с Reviewer-циклом. ✅
+- **Throughput меняет merge-философию** (короткоживущие PR, флейки — ретраем, не блокируем). ℹ️ философия.
+
+---
+
+## Журнал источников (какой репо что дал)
+
+| Репо | Дал / усилил пункты |
+|------|------------|
+| `microsoft/autogen` (05 #1) | 1, 2, 3, 4, 5, 6, 7, 8, 9 |
+| `crewAIInc/crewAI` (05 #2) | 10 (новый); усилил 1, 3, 4 |
+| `BerriAI/litellm` (05 #3) | 11, 12 (новые); reason-fallback/cooldown/sem-cache → ℹ️ |
+| `OpenHands/OpenHands` (02 #7) | **подтвердил** каркас (skills-md, CLAUDE.md, repo-memory); 13, 14 (новые); усилил 3 |
+| `letta-ai/letta` (02 #20) | усилил 3 (уровни core/archival/recall, self-editing, context-budget) |
+| `bytedance/deer-flow` (02 #8) | **подтвердил** состав harness; 18, 19 (skill-eval, checkpointer) |
+| `FoundationAgents/MetaGPT` (02 #9) | **подтвердил** SOP-пайплайн; усилил 1 (контракт = схема+инструкция+пример) |
+| `openai/openai-agents-python` (02 #13) | усилил 2 (таксономия спанов), 10 (input-guardrail + tripwire) |
+| `stanfordnlp/dspy` (05 #5) | 18 (eval-driven оптимизация; первоисточник GEPA для Evolver) |
+| OpenAI «Codex harness» (статья, 2026) | 15, 16, 17 (новые); **подтвердил** arch-lint/FSD, Sentinel/Evolver, specs-планы |