@gian-tiaga/eda 3.2.2 → 3.3.1

package/MIGRATION.md

@@ -1,4 +1,4 @@
-# Миграция на eda 3.2
+# Миграция на eda 3.3
 
 Версия 3.0 перенесла все рабочие результаты скилов в `docs/artifacts/`; постоянная документация проекта остаётся непосредственно в `docs/`. Версия 3.1 дополнительно переработала проверку плана, ревью кода и циклы полировки. Версия 3.2 обновила commit-flow и расположение проектных Codex-скиллов. В npm 3.0 не публиковалась, поэтому переход с 2.x выполняется сразу на актуальную версию 3.x.
 
@@ -75,7 +75,7 @@ docs/
 
 ## Настройки
 
-Версия npm-пакета и версия схемы настроек независимы: в eda 3.2 актуальным остаётся `docs/settings.yaml` с `version: 3`.
+Версия npm-пакета и версия схемы настроек независимы: в eda 3.3 актуальным остаётся `docs/settings.yaml` с `version: 3`.
 
 Установщик по-прежнему сохраняет полный валидный v3 байт-в-байт — кроме случая, когда в файле остались устаревшие ключи: тогда он перезаписывает файл без вопросов и печатает, что именно убрал. Старый, неизвестный или неполный YAML нормализуется: известные валидные значения переносятся, а отсутствующие спрашиваются в TTY или получают defaults без TTY.
 
@@ -97,7 +97,7 @@ docs/
 - старые рабочие каталоги исчезли из `docs/`, а файлы находятся в `docs/artifacts/`;
 - `docs/business.md`, `docs/business/`, `docs/references.md`, `docs/references/`, `docs/arch.md` и `docs/rules.md` остались на месте;
 - `docs/settings.yaml` содержит `version: 3`;
-- `eda --version` выводит версию `3.2.x`;
+- `eda --version` выводит версию `3.3.x`;
 - в `docs/settings.yaml` нет секции `plan-review.agents` и аргумента `threshold N` у шага `eda-polish`;
 - в `.claude/agents/` и `.codex/agents/` не осталось файлов `eda-plan-review-*`;
 - Claude-скиллы установлены в `.claude/skills/`, Codex-скиллы — в `.agents/skills/`, агенты — в `.claude/agents/` и `.codex/agents/`.

package/README.md

@@ -56,7 +56,7 @@ eda update-all ~/Code
 | `eda-review` | Оркестрирует отдельные read-only проверки корректности, архитектуры, правил, references, business-правил, плана, качества, тестов, безопасности, производительности, frontend/UI/UX, API, БД, документации и предыдущих ревью. Сохраняет только доказанные дефекты, которые обязательно исправить; косметические и спекулятивные предложения отбрасывает. Любая находка даёт `changes-required`, а чистое ревью — `clean` и 100/100. Без аргументов ревьюит `git diff HEAD` | `docs/artifacts/reviews/` |
 | `eda-fix-by-review` | Применяет все находки из ревью с учётом правил, архитектуры и применимых карточек. Спрашивает только при неоднозначности, конфликте, расширении scope или рискованном действии. В конце ссылается на отчёт прямо в файле ревью | `docs/artifacts/review-fixes/` |
 | `eda-manual-test` | Делает ручную smoke/acceptance-проверку после изменений: основной чеклист строит по выполненной задаче и связанному плану/issue/review/fix-отчёту, затем сверяет фактический diff. Применимая business-карточка может добавить только относящийся к задаче инвариант или сценарий; несвязанные карточки не загружаются. Не правит код, не пишет автотесты и не коммитит | `docs/artifacts/manual-tests/` |
-| `eda-polish` | Оркестрирует доводку изменений: запускает полное `eda-review`, затем `eda-fix-by-review` и повторяет цикл до `clean`, отсутствия находок и оценки не ниже 95/100 либо до лимита 5 итераций. Все находки исправляются. Каждый шаг идёт в изолированном нативном субагенте. Не коммитит | `docs/artifacts/reviews/`, `docs/artifacts/review-fixes/` |
+| `eda-polish` | Оркестрирует доводку изменений: запускает полное `eda-review`, затем `eda-fix-by-review` и повторяет цикл до `clean` и отсутствия находок либо до лимита 5 итераций. Все находки исправляются, score остаётся справочным. Каждый шаг идёт в изолированном нативном субагенте. Не коммитит | `docs/artifacts/reviews/`, `docs/artifacts/review-fixes/` |
 | `eda-send-review` | На `sonnet` / `gpt-5.6-terra` отправляет ревью на GitHub PR через `gh` всегда в едином формате: общий комментарий-сводка плюс комментарии к строкам кода. Без явно указанного типа использует `comment`; `approve` и `request-changes` берёт только из контекста текущего вызова. По настройке может скрыть предыдущие сводки eda-send-review и зарезолвить их inline-треды. По умолчанию шлёт все пункты. Claude-модель закрепляется при установке; Codex-модель хранится как рекомендуемый будущий override | (комментарий в PR) |
 | `eda-commit` | Работает как лёгкий оркестратор одного `haiku` / `gpt-5.6-luna` агента: тот сам собирает git-контекст, делит выбранный состав на логические коммиты, пишет сообщения, точечно коммитит и выполняет явно заданные push/PR/merge-действия. С явным контекстом охватывает указанный состав; без контекста берёт все tracked-изменения и содержательные untracked-файлы, кроме очевидных кэшей и локальных служебных артефактов. В Claude Code сам оркестратор закреплён за `haiku`; в Codex остаётся на активной модели сессии из-за отсутствия per-skill override. При вероятном секрете агент блокируется до индексации затронутой группы. После любого push всегда возвращает ссылку — на существующий PR или на его создание — и спрашивает, создавать ли PR, если его нет. Если продолжение не задано, предлагает применимые варианты | (git, опционально GitHub PR) |
 | `eda-worktree` | На `haiku` / `gpt-5.6-luna` создаёт через пакетного агента git worktree рядом с основным проектом в папке `{name}-work-{n}` и одноимённую ветку. Базу берёт из аргумента или спрашивает | соседняя папка `{name}-work-{n}` |
@@ -114,7 +114,7 @@ eda update-all ~/Code
 | `eda-review-documentation` | `haiku`, read-only | `gpt-5.6-luna`, read-only | Проверяет обязательные обновления документации |
 | `eda-review-previous-reviews` | `haiku`, read-only | `gpt-5.6-luna`, read-only | Перепроверяет незакрытые удалённые замечания |
 
-Агенты устанавливаются отдельно от скилов. Модели review-агентов в таблице — сбалансированные defaults; `docs/settings.yaml` или прямое указание пользователя может заменить модель конкретной проверки на текущий запуск. `eda-aim` последовательно разделяет согласование, выполнение и независимую проверку, а при необходимости использует установленные скилы только в отдельных изолированных субагентах; основной агент передаёт вопросы и структурированные результаты. `eda-commit` сохраняет исходный запрос и целиком передаёт сбор контекста, выбор файлов, коммит и разрешённое продолжение одному простому агенту. `eda-worktree` и `eda-merge-worktree` передают одному специализированному агенту git-операцию, обрабатывают его вопрос или результат и сами команды не выполняют. `eda-review` параллельно запускает только применимые review-агенты; полный prompt каждой роли хранится в агенте, а скил отвечает за выбор, retry и агрегацию.
+Агенты устанавливаются отдельно от скилов. Модели review-агентов в таблице — сбалансированные defaults; `docs/settings.yaml` или прямое указание пользователя может заменить модель конкретной проверки на текущий запуск. `eda-aim` последовательно разделяет согласование, выполнение и независимую проверку, а при необходимости использует установленные скилы только в отдельных изолированных субагентах; основной агент передаёт вопросы и структурированные результаты. `eda-commit` сохраняет исходный запрос и целиком передаёт сбор контекста, выбор файлов, коммит и разрешённое продолжение одному простому агенту. `eda-worktree` и `eda-merge-worktree` передают одному специализированному агенту git-операцию, обрабатывают его вопрос или результат и сами команды не выполняют. `eda-review` параллельно запускает только применимые review-агенты; полный prompt каждой роли хранится в агенте, а скил отвечает за выбор, retry и агрегацию. В Claude Code установленный `eda-review` всегда выполняется через `context: fork`, в том числе из `eda-polish`. В Codex шаги polish и специализированные review-агенты запускаются с `fork_turns: "none"`, без наследования истории. Все выбранные проверки отправляются одним нативным параллельным пакетом без ручных партий и shell-опроса.
 
 Для Claude Code установленные `eda-commit`, `eda-worktree` и `eda-merge-worktree` получают `model: haiku`. В Codex у скилов пока нет отдельного per-skill model override: основной поток остаётся на выбранной пользователем модели, но он выполняет только лёгкую оркестрацию, а содержательная работа `eda-commit` и worktree-операций закреплена за `gpt-5.6-luna`.
 
@@ -487,7 +487,7 @@ eda update-all ~/Code
 
 ## 📁 Структура и установка компонентов
 
-Исходники скилов лежат в `skills/<skill>/SKILL.md`. Дополнительные ресурсы скила можно хранить рядом; `skill.json` содержит только платформенные настройки и в проект пользователя не копируется. `models.codex` можно хранить как зарезервированную настройку для будущего per-skill override, но текущий Codex renderer её не добавляет в `SKILL.md`.
+Исходники скилов лежат в `skills/<skill>/SKILL.md`. Дополнительные ресурсы скила можно хранить рядом; `skill.json` содержит только платформенные настройки и в проект пользователя не копируется. Поля `claude.context: fork` и `claude.agent` renderer добавляет только во front matter Claude-копии скила. `models.codex` можно хранить как зарезервированную настройку для будущего per-skill override, но текущий Codex renderer её не добавляет в `SKILL.md`.
 
 Исходники агентов лежат в `agents/<agent>/agent.json` и `prompt.md`. Установщик рендерит единый агентный контракт в нативный формат выбранной среды.
 

package/lib/catalog.js

@@ -62,6 +62,18 @@ function validateSkillConfig(skillName, config) {
   if (config.models && typeof config.models !== 'object') {
     throw new Error(`Скил ${skillName}: models должен быть объектом.`);
   }
+  if (config.claude && (typeof config.claude !== 'object' || Array.isArray(config.claude))) {
+    throw new Error(`Скил ${skillName}: claude должен быть объектом.`);
+  }
+  if (config.claude?.context && config.claude.context !== 'fork') {
+    throw new Error(`Скил ${skillName}: claude.context поддерживает только fork.`);
+  }
+  if (config.claude?.agent && (typeof config.claude.agent !== 'string' || !config.claude.agent.trim())) {
+    throw new Error(`Скил ${skillName}: claude.agent должен быть непустой строкой.`);
+  }
+  if (config.claude?.agent && config.claude.context !== 'fork') {
+    throw new Error(`Скил ${skillName}: claude.agent требует claude.context fork.`);
+  }
 }
 
 function validateAgent(directoryName, agent, prompt) {

package/lib/renderers/claude-skill.js

@@ -1,11 +1,19 @@
 export function renderClaudeSkill(content, config = {}) {
   const model = config.models?.claude;
-  if (!model) return content;
+  const context = config.claude?.context;
+  const agent = config.claude?.agent;
+  const fields = [
+    model && `model: ${model}`,
+    context && `context: ${context}`,
+    agent && `agent: ${agent}`
+  ].filter(Boolean);
+
+  if (fields.length === 0) return content;
 
   const closingMarker = content.indexOf('\n---', 4);
   if (!content.startsWith('---\n') || closingMarker === -1) {
-    throw new Error('Не удалось добавить Claude model override: некорректный front matter скила.');
+    throw new Error('Не удалось добавить настройки Claude: некорректный front matter скила.');
   }
 
-  return `${content.slice(0, closingMarker)}\nmodel: ${model}${content.slice(closingMarker)}`;
+  return `${content.slice(0, closingMarker)}\n${fields.join('\n')}${content.slice(closingMarker)}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gian-tiaga/eda",
-  "version": "3.2.2",
+  "version": "3.3.1",
   "description": "Пакет скилов и специализированных агентов eda-* для Claude Code и Codex CLI",
   "type": "module",
   "bin": {

package/skills/eda-plan/SKILL.md

@@ -57,7 +57,7 @@ description: 'Создаёт понятный исполнимый план ре
 7. План не отклоняется от `docs/rules.md`, `docs/arch.md` и карточек. Если нужное решение им противоречит, план сначала меняет сам документ: добавь отдельный пункт `Обновить правила` или `Обновить архитектуру: <тема и изменение>` до зависимой реализации. Отклонения «с причиной в докблоке» не бывает — она разводит код и документацию.
 8. Не переформулируй запрос пользователя перед Plan Mode: передавай оригинал, ответы на вопросы и найденную рамку.
 9. План сохраняется до любой включённой проверки.
-10. План фиксирует решения, границы, контракты и критерии приёмки. Он не фиксирует реализацию: сигнатуры чужих методов, формулы, приведения типов, порядок строк внутри метода, форму классов. Если утверждение можно проверить только запуском кода, оно относится к code review, а не к плану.
+10. План фиксирует решения, границы, контракты и критерии приёмки. Формулы и компактный псевдокод допустимы, когда они точнее прозы задают бизнес-правило, контракт, инвариант или критерий приёмки, например `retryAt = now + 5 minutes`. Сам формульный синтаксис не превращает контракт в деталь реализации. Не фиксируй сигнатуры чужих методов, приведения типов, порядок строк внутри метода, форму классов и внутренние вычисления, которые не задают наблюдаемое поведение. Если утверждение можно проверить только по конкретному коду, оно относится к code review, а не к плану.
 11. Не пересказывай прозой то, что уже лежит рядом: правила, архитектуру и кодовые примеры карточек. Ссылайся на них.
 12. Один факт — одно место. Поведение описано в `Целевом алгоритме`, контракты — в `Контрактах реализации`, фаза на них опирается и не повторяет их.
 13. План доводится до первой точки, где результат можно запустить и проверить целиком. Дальше планируй следующей вехой, на фактах.
@@ -186,7 +186,7 @@ Quality gate перед сохранением и после каждой вкл
 - каждый отсутствующий, неполный или расширяемый пункт целевого поведения покрыт отдельной задачей `Дополнить бизнесовые правила` до зависимой реализации; для чисто технических изменений такая задача не добавлена;
 - план строго следует `docs/rules.md` и `docs/arch.md`, а также применимым reference-карточкам; там, где нужно другое поведение, есть отдельный пункт на изменение самого документа до зависимой реализации;
 - каждая фаза имеет цель, что сделать, результат и проверку и выполнима одним агентом за один проход;
-- в фазах нет сигнатур, формул, приведений типов и пересказа карточек;
+- в плане нет сигнатур, приведений типов, формы классов, внутренних вычислений без контрактного смысла и пересказа карточек; формулы, задающие обязательное поведение, не удалены только из-за формы записи;
 - ни один факт не описан в двух разделах;
 - `test_strategy` и `logging_strategy` применены;
 - пакеты имеют конкретные версии или ссылку на существующий lock;
@@ -233,7 +233,7 @@ codex exec "Прочитай $PLAN_FILE, docs/rules.md, docs/arch.md и прим
 
 - Править код, миграции, конфиги или зависимости.
 - Считать `docs/rules.md` и `docs/arch.md` просто контекстом для ознакомления.
-- Писать в план сигнатуры чужих методов, формулы, приведения типов и форму классов.
+- Писать в план сигнатуры чужих методов, приведения типов, форму классов и формулы внутренних вычислений, которые не задают бизнес-правило, контракт, инвариант или критерий приёмки.
 - Пересказывать прозой правила, архитектуру и кодовые примеры карточек.
 - Отклоняться от правил и архитектуры «с причиной» вместо того, чтобы менять сам документ.
 - Разбивать фазы на задачи с идентификаторами и графом зависимостей.

package/skills/eda-plan-review/SKILL.md

@@ -44,7 +44,7 @@ Read-only проверка одного плана по списку ниже.
 | 7 | Пакеты, библиотеки и сервисы имеют конкретные версии или ссылку на существующий lock |
 | 8 | Есть `Целевой алгоритм` и `Контракты реализации` с подразделами `Данные и БД` и `API и внешние контракты` |
 | 9 | Ни один факт не описан в двух разделах |
-| 10 | В плане нет сигнатур чужих методов, формул, приведений типов и пересказа кодовых примеров карточек |
+| 10 | В плане нет сигнатур чужих методов, приведений типов, формы классов, внутренних вычислений без контрактного смысла и пересказа кодовых примеров карточек; формулы, задающие обязательное поведение, допустимы |
 | 11 | У каждой фазы есть цель, что сделать, результат и проверка |
 | 12 | Каждая фаза выполнима одним агентом за один проход вместе с её проверками |
 | 13 | Команды в `Проверке` фазы существуют к моменту её выполнения или создаются в этой же фазе |
@@ -69,6 +69,10 @@ Read-only проверка одного плана по списку ниже.
 
 Пункт не касается: условных веток («при ошибке — повтор» это описание ветки, а не модальность) и умолчаний, заданных `rules.md` или карточкой — их повторять в плане не нужно.
 
+### Как проверять пункт 10
+
+Сам по себе формульный синтаксис не является основанием для `fail`. Формула или компактный псевдокод допустимы, если они точнее прозы задают бизнес-правило, контракт, инвариант или критерий приёмки. Например, `retryAt = now + 5 minutes` фиксирует обязательный момент повторной обработки и остаётся в плане. Ставь `fail` только за внутренние вычисления и кодовые детали, которые не меняют наблюдаемое поведение и не нужны исполнителю для однозначного результата.
+
 ## Правила проверки
 
 1. Не правь план, код и документацию. Не запускай тесты, линтеры, сборку, миграции и внешние запросы.

package/skills/eda-plan-review-fix/SKILL.md

@@ -21,7 +21,7 @@ description: 'Закрывает проваленные пункты чек-ли
 4. Закрой каждый пункт со статусом `fail`. Пункты `pass` и `n/a` не трогай. Своих замечаний не добавляй: чего нет в отчёте, того нет в работе.
 5. **План не растёт.** Сначала ищи, что удалить или заменить, и только потом — что дописать. Прирост объёма за один fix не больше 3%; если пункт иначе не закрывается, остановись и верни `blocked: пункт требует роста плана` с объяснением.
 6. Не повторяй один факт в двух разделах: поведение живёт в `Целевом алгоритме`, контракты — в `Контрактах реализации`, фаза на них ссылается.
-7. Не добавляй в план сигнатуры чужих методов, формулы, приведения типов, форму классов и пересказ карточек — это те же пункты 9 и 10 чек-листа, только с другой стороны.
+7. Не добавляй в план сигнатуры чужих методов, приведения типов, форму классов, внутренние вычисления без контрактного смысла и пересказ карточек — это те же пункты 9 и 10 чек-листа, только с другой стороны. Не удаляй и не переписывай только из-за формы записи формулу, которая задаёт бизнес-правило, контракт, инвариант или критерий приёмки.
 8. Продуктовый выбор, конфликт с business, rules или architecture и расширение scope не решай сам: собери все такие случаи и задай один блокирующий вопрос до любых правок.
 9. Не правь код, конфиги, зависимости, миграции и другие документы. Не запускай проверки проекта.
 

package/skills/eda-polish/SKILL.md

@@ -16,6 +16,8 @@ description: 'Итеративно ревьюит и исправляет изм
 ## Правила
 
 1. Каждый вызов `eda-review` и `eda-fix-by-review` запускай отдельным изолированным субагентом. Основной агент не делает их работу.
+   - В Claude Code вызывай установленный `eda-review` именно через `Skill`: его отрендеренная копия содержит `context: fork` и сама создаёт изолированный review-runner. Не читай инструкцию `eda-review` в текущий контекст, не воспроизводи её процедуру самостоятельно и не запускай `eda-review-*` агентов напрямую из полировщика.
+   - В Codex каждый вызов `eda-review` и `eda-fix-by-review` запускай через `spawn_agent` с `fork_turns: "none"`. Не оставляй `fork_turns` по умолчанию и не используй `"all"`: субагент получает только самодостаточное task-сообщение и явно указанные пути к артефактам.
 2. Если нативные субагенты недоступны, остановись; не заменяй шаги CLI-процессами.
 3. Успех требует одновременно: полный review со статусом `reviewed` или `reviewed-with-warnings`, `result: clean` и ноль находок. Score — только справочное число, условием завершения он не является.
 4. Любая находка обязательно исправляется. Отклонить находку может только `eda-fix-by-review` и только при её фактической неверности.

package/skills/eda-review/SKILL.md

@@ -96,7 +96,7 @@ description: 'Проводит полное read-only ревью diff, ветк
 - `previous_reviews` → `eda-review-previous-reviews`;
 - остальные → `eda-review-<check>`.
 
-В Claude Code запускай установленный custom agent через `Agent` tool. В Codex запускай установленный custom agent через `spawn_agent` или аналог. Передай выбранную модель как runtime override. Если хост не умеет применить выбранную модель или нативные субагенты недоступны, остановись: не выполняй роли главным агентом и не создавай отдельные CLI-процессы.
+В Claude Code запускай установленный custom agent через `Agent` tool. Установленная Claude-копия самого `eda-review` выполняется с `context: fork`, поэтому review-оркестрация не должна оставаться в контексте вызвавшего `eda-polish` или другого скила. В Codex каждого установленного custom agent запускай через `spawn_agent` с `fork_turns: "none"`; не оставляй `fork_turns` по умолчанию и не передавай историю review-runner. Передай выбранную модель как runtime override. Если хост не умеет применить выбранную модель или нативные субагенты недоступны, остановись: не выполняй роли главным агентом и не создавай отдельные CLI-процессы.
 
 ### Технические остановки субагентов
 
@@ -111,7 +111,11 @@ description: 'Проводит полное read-only ревью diff, ветк
 
 Ожидание слота и один технический retry не считаются повторной содержательной проверкой агента.
 
-Запусти все выбранные проверки одним параллельным пакетом; если хост ограничивает concurrency, разреши ему поставить лишние задачи в очередь. Каждому агенту передай только:
+Сначала сформируй весь набор выбранных проверок, затем отправь все вызовы одним параллельным пакетом в одном ответе ассистента. Не дели проверки заранее на волны, партии или последовательные группы и не жди завершения части агентов перед запуском остальных. Если хост ограничивает concurrency, разреши нативному механизму поставить лишние задачи в очередь; повторный запуск допустим только после фактической ошибки лимита по правилам технических остановок выше.
+
+Ожидай результаты только нативным механизмом субагентов и их уведомлениями о завершении; в Codex используй `wait_agent`. Не используй Bash, shell-циклы, `sleep`, опрос файлов или артефактов и фиксированные таймауты для ожидания агентов. После отправки всего пакета собирай ответы по мере нативного завершения.
+
+Каждому агенту передай только:
 
 ```text
 Рабочая директория: <cwd>

package/skills/eda-review/skill.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "claude": {
+    "context": "fork",
+    "agent": "general-purpose"
+  }
+}