@gian-tiaga/eda 0.5.1 → 0.5.3

package/README.md

@@ -19,7 +19,7 @@ npm install -g @gian-tiaga/eda
 eda init
 ```
 
-Установщик покажет чекбоксы: стрелками выбираешь среду, пробелом отмечаешь, Enter продолжает. Можно поставить Claude Code, Codex CLI или обе среды сразу. Если `docs/settings.yaml` ещё нет, установщик также предложит выбрать настройки скилов и создаст этот файл. В конце `eda init` пишет, сколько скилов установлено.
+Установщик покажет чекбоксы: стрелками выбираешь среду, пробелом отмечаешь, Enter продолжает. Можно поставить Claude Code, Codex CLI или обе среды сразу. Если `docs/settings.yaml` ещё нет, установщик также предложит выбрать настройки скилов и создаст этот файл. В конце `eda init` пишет, какие скилы реально установлены или изменились.
 
 ---
 
@@ -28,8 +28,8 @@ eda init
 | Скил | Что делает | Куда складывает |
 |---|---|---|
 | `eda-roadmap` | Создаёт roadmap-файл: список будущих задач с короткими, понятными и недвусмысленными описаниями без деталей реализации, файлов, библиотек, API и пошагового плана | `docs/roadmaps/` |
-| `eda-explore` | Исследует тему до конкретного результата: описание проблемы, релевантная архитектура, закрытые развилки, риски внутри решений и короткий выбранный вариант решения без плана. Если нужны пакеты или ПО — проверяет актуальные стабильные версии через context7 или web search | `docs/researches/` |
-| `eda-plan` | Пишет план реализации через стандартный Plan Mode хост-агента. Подтягивает контекст из `docs/rules.md`, `docs/arch.md`, при желании — релевантное исследование. Затем три параллельных модели (слабая, средняя, мощная) проверяют план на реалистичность, пропущенные шаги и нарушения правил — главный планировщик сам решает, что применить | `docs/plans/` |
+| `eda-explore` | Исследует тему до конкретного результата: описание проблемы, релевантная архитектура, закрытые развилки, риски внутри решений и короткий выбранный вариант решения без плана. В дефолтном режиме ведёт исследование как диалог: факты собирает сам, а значимые развилки выносит тебе с рекомендацией. Если нужны пакеты или ПО — проверяет актуальные стабильные версии через context7 или web search | `docs/researches/` |
+| `eda-plan` | Пишет план реализации через стандартный Plan Mode хост-агента. Подтягивает контекст из `docs/rules.md`, `docs/arch.md`, при желании — релевантное исследование. В плане явно фиксирует контракты БД/API, если задача их затрагивает. Затем три параллельных модели (слабая, средняя, мощная) проверяют план на реалистичность, пропущенные шаги и нарушения правил — главный планировщик сам решает, что применить | `docs/plans/` |
 | `eda-execute` | Выполняет план. Спрашивает, где работать (текущая ветка, новая ветка, отдельный worktree). Тесты пишет внутри каждого шага. В конце — полный прогон тестов и линтеров | `docs/executions/` |
 | `eda-fix` | Делает обычные фиксы по короткому контексту, баг-репорту или файлу плана. Перед правками читает правила и архитектуру, добавляет нужные тесты, прогоняет проверки и сохраняет историю правок | `docs/fixes/` |
 | `eda-review` | Делает код-ревью с оценкой 0–100 и сверкой с планом работ, но в файл пишет только проблемы: ошибки, недоделки, неточности, нарушения правил/архитектуры, риски и недостающие тесты. Не перечисляет выполненную работу. Затем параллельные специализированные агенты проверяют выполнение плана, архитектуру, правила и при включённой настройке качество кода. В строгом режиме — ещё и кросс-ревью между Claude и Codex | `docs/reviews/` |
@@ -71,7 +71,7 @@ defaults:
   # Задаёт размер плана по умолчанию для eda-plan.
   # normal | short | ask_each_time
   plan_size: normal
-  # Определяет, как eda-explore и eda-plan принимают существенные решения.
+  # Определяет, как eda-explore ведёт исследовательские развилки, а eda-plan принимает существенные решения.
   # autonomous | recommend_and_ask | ask_each_time
   decision_mode: recommend_and_ask
   # Задаёт стратегию тестов по умолчанию для eda-plan.
@@ -95,7 +95,7 @@ review:
 Что означают настройки:
 - `defaults.strict` — включает strict-режим по умолчанию для `eda-explore`, `eda-plan` и `eda-review`.
 - `defaults.plan_size` — размер плана для `eda-plan`: `normal`, `short` или `ask_each_time`.
-- `defaults.decision_mode` — как `eda-explore` и `eda-plan` принимают существенные решения: `autonomous` выбирает сам, `recommend_and_ask` рекомендует и спрашивает, `ask_each_time` спрашивает по каждой значимой развилке.
+- `defaults.decision_mode` — как `eda-explore` ведёт исследовательские развилки, а `eda-plan` принимает существенные решения: `autonomous` выбирает сам, `recommend_and_ask` рекомендует и спрашивает по значимым развилкам, `ask_each_time` спрашивает по каждой развилке, которая влияет на ход работы или итоговый выбор.
 - `defaults.test_strategy` — стратегия тестов для `eda-plan`: `after_each_phase`, `tdd_each_phase`, `end_of_plan` или `ask_each_time`.
 - `defaults.logging_strategy` — стратегия логирования для `eda-plan`: `debug_precise`, `standard` или `ask_each_time`.
 - `automate.include_plans` — добавляет `docs/plans/` в обычный запуск `eda-automate`.
@@ -137,7 +137,7 @@ automate может запускаться от review, fix-by-review или fix
 
 ```bash
 eda init      # выбрать Claude Code / Codex / обе среды и установить скилы
-eda update    # обновить скилы, показать их количество и создать docs/settings.yaml, если его ещё нет
+eda update    # обновить скилы, показать реально изменившиеся и создать docs/settings.yaml, если его ещё нет
 eda --version # показать версию установленного пакета
 eda --help    # справка
 ```
@@ -160,7 +160,7 @@ eda update           # синхронизировать скилы в текущ
 | **Claude Code** | `<project>/.claude/skills/<skill>/SKILL.md` — отдельная папка на каждый скил |
 | **Codex CLI** | `<project>/.codex/skills/<skill>/SKILL.md` — отдельная папка на каждый скил |
 
-`eda update` идемпотентно перезаписывает файлы в обеих папках и в конце пишет, сколько скилов обновлено. При обновлении старые файлы Codex-формата `<project>/.codex/skills/<skill>.md`, созданные версиями `eda` до этой структуры, удаляются. Если ты хочешь подправить скил локально — лучше копию сделай рядом, а не прямо в `.claude/skills/` или `.codex/skills/`, иначе при следующем `update` твои правки потеряются.
+`eda update` идемпотентно перезаписывает файлы в обеих папках и в конце пишет только те скилы, содержимое которых реально изменилось относительно установленной копии. При обновлении старые файлы Codex-формата `<project>/.codex/skills/<skill>.md`, созданные версиями `eda` до этой структуры, удаляются. Если ты хочешь подправить скил локально — лучше копию сделай рядом, а не прямо в `.claude/skills/` или `.codex/skills/`, иначе при следующем `update` твои правки потеряются.
 
 `AGENTS.md` (как и любые другие файлы в корне проекта) установщик **не трогает**. Если хочешь, чтобы Codex автоматически подгружал скилы, дай ему знать сам — например, одной строкой в `AGENTS.md`: «следуй инструкциям из `.codex/skills/`».
 

package/lib/install.js

@@ -218,12 +218,22 @@ async function syncSkills(cwd, targets, output = process.stdout, { action = 'upd
   }
   output.write(`Скилы для установки: ${skills.map(s => s.name).join(', ')}\n`);
 
-  if (targets.includes('claude')) await installToClaude(cwd, skills, output);
-  if (targets.includes('codex')) await installToCodex(cwd, skills, output);
+  const changedSkills = new Set();
+  if (targets.includes('claude')) {
+    const result = await installToClaude(cwd, skills, output);
+    for (const skillName of result.changedSkills) changedSkills.add(skillName);
+  }
+  if (targets.includes('codex')) {
+    const result = await installToCodex(cwd, skills, output);
+    for (const skillName of result.changedSkills) changedSkills.add(skillName);
+  }
   await removeRetiredSkills(cwd, targets);
 
   const actionLabel = action === 'install' ? 'Установлено' : 'Обновлено';
-  output.write(`${actionLabel} ${formatSkillCount(skills.length)}.\n`);
+  const changedSkillNames = skills
+    .map(skill => skill.name)
+    .filter(skillName => changedSkills.has(skillName));
+  output.write(formatChangedSkills(actionLabel, changedSkillNames));
   output.write('\nГотово.\n');
 }
 
@@ -260,7 +270,7 @@ defaults:
   # Задаёт размер плана по умолчанию для eda-plan.
   # normal | short | ask_each_time
   plan_size: ${settings.planSize}
-  # Определяет, как eda-explore и eda-plan принимают существенные решения.
+  # Определяет, как eda-explore ведёт исследовательские развилки, а eda-plan принимает существенные решения.
   # autonomous | recommend_and_ask | ask_each_time
   decision_mode: ${settings.decisionMode}
   # Задаёт стратегию тестов по умолчанию для eda-plan.
@@ -285,26 +295,52 @@ review:
 async function installToClaude(cwd, skills, output = process.stdout) {
   const dst = path.join(cwd, '.claude/skills');
   await fs.mkdir(dst, { recursive: true });
+  const changedSkills = [];
   for (const skill of skills) {
     const skillDir = path.join(dst, skill.name);
     await fs.mkdir(skillDir, { recursive: true });
     const content = await fs.readFile(skill.path, 'utf-8');
-    await fs.writeFile(path.join(skillDir, 'SKILL.md'), content);
+    const changed = await writeSkillFile(path.join(skillDir, 'SKILL.md'), content);
+    if (changed) changedSkills.push(skill.name);
   }
-  output.write(`  ✓ Claude Code: ${dst} (${formatSkillCount(skills.length)})\n`);
+  output.write(`  ✓ Claude Code: ${dst} (изменилось ${formatSkillCount(changedSkills.length)})\n`);
+  return { changedSkills };
 }
 
 async function installToCodex(cwd, skills, output = process.stdout) {
   const dst = path.join(cwd, '.codex/skills');
   await fs.mkdir(dst, { recursive: true });
+  const changedSkills = [];
   for (const skill of skills) {
     const skillDir = path.join(dst, skill.name);
     await fs.mkdir(skillDir, { recursive: true });
     const content = await fs.readFile(skill.path, 'utf-8');
-    await fs.writeFile(path.join(skillDir, 'SKILL.md'), content);
+    const changed = await writeSkillFile(path.join(skillDir, 'SKILL.md'), content);
+    if (changed) changedSkills.push(skill.name);
     await removeObsoleteCodexFile(dst, skill.name);
   }
-  output.write(`  ✓ Codex CLI: ${dst} (${formatSkillCount(skills.length)})\n`);
+  output.write(`  ✓ Codex CLI: ${dst} (изменилось ${formatSkillCount(changedSkills.length)})\n`);
+  return { changedSkills };
+}
+
+async function writeSkillFile(filePath, content) {
+  const previousContent = await readFileIfExists(filePath);
+  await fs.writeFile(filePath, content);
+  return previousContent !== content;
+}
+
+async function readFileIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf-8');
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err;
+    return null;
+  }
+}
+
+function formatChangedSkills(actionLabel, skillNames) {
+  if (skillNames.length === 0) return `${actionLabel} 0 скилов.\n`;
+  return `${actionLabel} ${formatSkillCount(skillNames.length)}: ${skillNames.join(', ')}.\n`;
 }
 
 function formatSkillCount(count) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gian-tiaga/eda",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Набор скилов eda-* для Claude Code и Codex CLI: roadmap, explore, plan, execute, fix, review, fix-by-review, send-review, commit, docs, automate",
   "type": "module",
   "bin": {

package/skills/eda-explore.md

@@ -1,6 +1,6 @@
 ---
 name: eda-explore
-description: 'Исследует тему или задачу до конкретного результата: проясняет проблему, архитектуру, развилки, связанные риски и короткий выбранный вариант решения без плана реализации. Работает read-only, задаёт блокирующие вопросы, когда без ответа нельзя выбрать решение, а существенные решения подтверждает по `defaults.decision_mode` из `docs/settings.yaml`. Если исследование касается пакетов, библиотек, CLI, сервисов или другого ПО, проверяет актуальные стабильные версии через context7, если он доступен, или через web search по официальным источникам. Итог сохраняет в docs/researches/. Кросс-ревью соседним агентом (Claude ↔ Codex) включается флагом `strict` или настройкой `defaults.strict: true` в `docs/settings.yaml`.'
+description: 'Исследует тему или задачу до конкретного результата: проясняет проблему, архитектуру, развилки, риски и короткий выбранный вариант решения без плана реализации. Работает read-only и ведёт исследование как диалог: факты собирает сам, а значимые развилки выносит пользователю по `defaults.decision_mode` из `docs/settings.yaml`. Если исследование касается пакетов, библиотек, CLI, сервисов или другого ПО, проверяет актуальные стабильные версии через context7, если он доступен, или через web search по официальным источникам. Итог сохраняет в docs/researches/. Кросс-ревью соседним агентом (Claude ↔ Codex) включается флагом `strict` или настройкой `defaults.strict: true`.'
 ---
 
 # Скил: Исследователь решений (eda-explore)
@@ -20,7 +20,7 @@ description: 'Исследует тему или задачу до конкре
 
 Текст рядом с вызовом скилла в текущем сообщении пользователя — главный вход. Сначала разбери именно его: тему, задачу, путь к файлу, режим, ограничения и прямые указания.
 
-Если входа достаточно, продолжай без подтверждения. `AskUserQuestion` задавай только если входа нет, он противоречивый, найдено несколько равных вариантов или есть риск исследовать не то. Старое обсуждение в истории не считай входом, если пользователь не связал его с текущим вызовом явно.
+Если входа достаточно, не спрашивай подтверждение самой темы. `AskUserQuestion` на этом этапе задавай только если входа нет, он противоречивый, найдено несколько равных вариантов или есть риск исследовать не то. Это не отменяет обязательные вопросы по исследовательским развилкам ниже. Старое обсуждение в истории не считай входом, если пользователь не связал его с текущим вызовом явно.
 
 ## Настройки проекта
 
@@ -37,24 +37,28 @@ description: 'Исследует тему или задачу до конкре
 | Ключ | Значения | Что значит |
 |---|---|---|
 | `defaults.decision_mode` | `autonomous` | Агент сам выбирает по коду, правилам, архитектуре, источникам и рискам, затем записывает причину. |
-| `defaults.decision_mode` | `recommend_and_ask` | Агент исследует варианты, рекомендует один, но по существенным решениям задаёт блокирующий вопрос до финализации. |
-| `defaults.decision_mode` | `ask_each_time` | Агент спрашивает по каждой значимой развилке, даже если есть сильная рекомендация. |
+| `defaults.decision_mode` | `recommend_and_ask` | Дефолт. Агент сам собирает факты, рекомендует вариант и спрашивает пользователя по каждой значимой развилке исследования до финализации. |
+| `defaults.decision_mode` | `ask_each_time` | Агент спрашивает по каждой развилке, которая влияет на направление исследования или итоговый выбор, даже если есть сильная рекомендация. |
 
 Если `defaults.decision_mode` отсутствует или неизвестен, считай его `recommend_and_ask`.
 
-Существенные решения — это решения, которые меняют архитектуру, зависимости, стоимость, безопасность, эксплуатацию или будущую миграцию проекта. Всегда считай существенными:
+Значимая исследовательская развилка — это выбор, который меняет направление исследования, итоговую рекомендацию, границы задачи, архитектуру, зависимости, стоимость, безопасность, эксплуатацию, совместимость или будущую миграцию проекта. Не спрашивай о фактах, которые можно выяснить через код, документы или источники; спрашивай о выборе, предпочтении или компромиссе.
+
+Всегда считай значимыми:
 - выбор нового пакета, библиотеки, фреймворка, SDK, CLI или сервиса;
 - выбор базы данных, ORM/query builder, очереди, кэша, storage, search, background jobs;
 - миграции данных, изменение схемы, формат хранения или стратегия совместимости;
 - auth, permissions, payments, crypto, secrets, персональные данные и другие security-sensitive решения;
 - cloud/provider choices, managed services, лицензии, cost/lock-in и SLA;
 - архитектурные паттерны, затрагивающие несколько модулей или публичные контракты.
+- продуктовый компромисс между скоростью, качеством, UX, стоимостью, сроком или объёмом;
+- выбор, который влияет на то, какой результат будет передан в `eda-plan`.
 
 ## Главные правила
 
 1. **Никаких правок кода.** Запись только в `docs/researches/`.
 2. **Итог — конкретика.** Нельзя заканчивать абстрактными описаниями, списком возможностей или «можно выбрать один из вариантов».
-3. **Развилки закрывай по `decision_mode`.** Обычные локальные развилки можно выбрать по коду, правилам, архитектуре, источникам и рискам. Существенные решения в `recommend_and_ask` и `ask_each_time` подтверждай у пользователя до финализации. Если выбор зависит только от пользователя — задай блокирующий вопрос в любом режиме.
+3. **Развилки закрывай по `decision_mode`.** В `recommend_and_ask` значимые развилки исследования подтверждай у пользователя до финализации: сначала собери факты, затем дай рекомендацию и варианты. В `ask_each_time` спрашивай ещё чаще: по каждой развилке, которая влияет на ход исследования или итоговый выбор. В `autonomous` выбирай сам, если выбор можно обосновать кодом, правилами, архитектурой, источниками и рисками. Мелкие локальные решения, которые не меняют смысл исследования и легко обратимы, выбирай сам и не создавай шум.
 4. **Риски вплетай в исследование.** Не создавай отдельный обязательный раздел или этап рисков. Если риск влияет на выбор, источник, ограничение или будущую проверку, фиксируй его рядом с соответствующим решением: что может пойти не так и как это учитывается — снимаем, принимаем или выносим за рамки.
 5. **Версии проверяй.** Если речь о пакетах, библиотеках, CLI, сервисах или другом ПО, а версия не задана контекстом, проверь последнюю стабильную версию через context7, если он доступен, или через web search по официальным источникам.
 6. **Прочитай `docs/rules.md` и `docs/arch.md`**, если есть, и используй их как рамку.
@@ -94,19 +98,21 @@ description: 'Исследует тему или задачу до конкре
 
 ### 3. Закрыть развилки
 
-Собери все существенные развилки: архитектурные, продуктовые, технические, миграционные, по зависимостям и совместимости.
+Собери все значимые развилки: архитектурные, продуктовые, технические, миграционные, по зависимостям и совместимости.
+
+Не начинай с вопросов, если можно сначала быстро собрать факты. После первичного контекста сгруппируй близкие развилки в пакет из 1–3 вопросов, чтобы пользователь принимал решения осознанно, а диалог не распадался на мелочи.
 
 Для каждой развилки:
 - перечисли варианты;
 - выбери один вариант или подготовь рекомендацию;
 - запиши источник и причину выбора;
 - если у варианта есть важный риск, опиши его здесь же и сразу зафиксируй, как он влияет на выбранное решение;
-- если развилка существенная и `decision_mode: recommend_and_ask` — задай `AskUserQuestion`: 2–3 варианта, первым рекомендованный, короткая причина рекомендации, вариант «свой вариант», фраза «Я продолжу только после ответа.»;
-- если развилка значимая и `decision_mode: ask_each_time` — задай `AskUserQuestion` даже при сильной рекомендации;
+- если развилка значимая и `decision_mode: recommend_and_ask` — задай `AskUserQuestion`: 2–3 варианта, первым рекомендованный, короткая причина рекомендации, вариант «свой вариант», фраза «Я продолжу только после ответа.»;
+- если развилка влияет на ход исследования или итоговый выбор и `decision_mode: ask_each_time` — задай `AskUserQuestion` даже при сильной рекомендации;
 - если `decision_mode: autonomous` и выбор можно обосновать кодом, правилами, архитектурой, источниками и рисками — выбери сам и запиши почему;
 - если выбрать нельзя без пользовательского решения — задай `AskUserQuestion` и не продолжай финализацию.
 
-Не прячь существенный выбор внутри текста. Например, если нужен пакет для базы данных, сначала сравни 2–3 подходящих варианта, затем в `recommend_and_ask` спроси подтверждение выбора пакета/БД до записи финального решения.
+Не прячь значимый выбор внутри текста. Например, если нужен пакет для базы данных, сначала сравни 2–3 подходящих варианта, затем в `recommend_and_ask` спроси подтверждение выбора пакета/БД до записи финального решения.
 
 Если по ходу исследования находится высокий риск без понятного решения, это блокер: задай `AskUserQuestion` или заверши со статусом `blocked`. Не выноси риски в отдельную секцию ради формы; они должны естественно лежать в `Решении`, причинах выбора, ограничениях, проверках версий или итоговом выводе.
 
@@ -143,7 +149,7 @@ sources:
 - объяснение, почему выбран этот вариант, а не альтернативы.
 
 ## Ответы на вопросы
-Вопросы, которые были заданы в процессе исследования, и ответы пользователя. Если вопросов не было — «Не требовались.»
+Вопросы и развилки, которые были вынесены пользователю в процессе исследования, а также ответы пользователя. Если вопросов не было — «Не требовались.»
 
 ## Итог
 Короткая конкретика: что делать дальше на уровне подхода, без плана реализации.
@@ -154,7 +160,7 @@ Quality gate перед сохранением:
 - в `Суть` чётко описано, что исследовали и какая проблема решается;
 - в `Решение` есть выбранный вариант решения, а не набор равных альтернатив;
 - в `Решение` есть описание архитектуры или явно сказано, почему архитектурный слой не затронут;
-- в `Ответы на вопросы` записаны все вопросы, заданные пользователю в процессе исследования, и ответы на них, чтобы `eda-plan` не задавал их повторно;
+- в `Ответы на вопросы` записаны все вопросы и пользовательские выборы по развилкам, заданные в процессе исследования, чтобы `eda-plan` не задавал их повторно;
 - в `Итог` есть короткая конкретика, что делать дальше на уровне подхода, без пошагового плана;
 - нет незакрытых развилок;
 - нет рисков, которые перечислены отдельно от решения и никак не влияют на выбор, ограничения или будущие проверки;

package/skills/eda-plan.md

@@ -95,6 +95,8 @@ description: 'Пишет план реализации по тексту ряд
 - выбор нового пакета, библиотеки, фреймворка, SDK, CLI или сервиса;
 - выбор базы данных, ORM/query builder, очереди, кэша, storage, search, background jobs;
 - миграции данных, изменение схемы, формат хранения или стратегия совместимости;
+- новые или изменённые схемы таблиц: поля, типы, связи, индексы, уникальные ограничения;
+- новые или изменённые API/внешние контракты: маршруты, auth/permissions, request/query/body, response, ошибки и статус-коды;
 - auth, permissions, payments, crypto, secrets, персональные данные и другие security-sensitive решения;
 - cloud/provider choices, managed services, лицензии, cost/lock-in и SLA;
 - архитектурные паттерны, затрагивающие несколько модулей или публичные контракты.
@@ -179,6 +181,8 @@ Research подтягивай так:
 До Plan Mode закрой существенные решения:
 - выпиши существенные развилки, которые следуют из задачи и контекста;
 - если research содержит подтверждённый ответ пользователя по развилке — используй его и запиши как подтверждённое решение;
+- если задача меняет БД или API/внешний контракт, проверь, подтверждены ли конкретные схемы таблиц или API-контракты пользователем в текущем сообщении, правилах, архитектуре или research с подтверждённым ответом пользователя;
+- если конкретные схемы БД или API-контракты не подтверждены явно, до Plan Mode задай блокирующий вопрос и получи подтверждение пользователя; не проектируй таблицы и маршруты молча внутри Plan Mode;
 - если `decision_mode: autonomous` и выбор можно обосновать кодом, правилами, архитектурой, источниками и рисками — выбери сам и запиши почему;
 - если `decision_mode: recommend_and_ask` — задай `AskUserQuestion`: 2–3 варианта, первым рекомендованный, короткая причина рекомендации, вариант «свой вариант», фраза «Я продолжу только после ответа.»;
 - если `decision_mode: ask_each_time` — задай `AskUserQuestion` по каждой значимой развилке, даже при сильной рекомендации;
@@ -231,11 +235,10 @@ Research подтягивай так:
 6. Пары «вопрос → ответ» из этапа 3 и подтверждения существенных решений из research.
 7. Ссылки на `docs/rules.md`, `docs/arch.md`, исследование (без пересказа — Plan Mode прочитает сам) и явное требование строго следовать правилам и архитектуре.
 8. Инструкция: «все вопросы пользователю — только по разделу "Интерактивные вопросы", никаких догадок и продолжения без ответа».
-9. Инструкция: «финальный план должен иметь раздел "Целевой алгоритм", фазы с целью/результатом/проверкой и не должен смешивать исследование с планом исполнения».
-10. Инструкция: «стратегии тестов и логирования обязательны: они должны быть отражены в решениях, фазах, проверках, разделах "Тесты" и "Логирование"».
-11. Инструкция: «если `plan_size: short`, план обязан уложиться в 1–2 фазы, компактный ревьюируемый объём и объяснение ожидаемого объёма изменений».
-12. Инструкция: «если нужны пакеты или ПО, используй только конкретные версии; если версия не задана контекстом, она должна быть проверена через context7 или поиск и указана с источником».
-13. Инструкция: «не добавляй неподтверждённые существенные решения в финальный план; если они возникли внутри Plan Mode, остановись и спроси пользователя».
+9. Инструкция: «финальный план должен быть нормализован в обязательную структуру из этапа 5 и не должен смешивать исследование с планом исполнения».
+10. Инструкция: «зафиксированные стратегии тестов и логирования должны быть применены в плане, а не просто записаны в YAML».
+11. Инструкция: «если `plan_size: short`, соблюдай ограничения короткого плана из раздела "Размер плана"».
+12. Инструкция: «не добавляй неподтверждённые существенные решения в финальный план; если они возникли внутри Plan Mode, остановись и спроси пользователя».
 
 Не выходи, пока пользователь не подтвердил план.
 
@@ -278,6 +281,18 @@ sources:
 ## Целевой алгоритм
 Пошаговое описание целевого поведения системы от входного события до финального состояния. Это обзор всей картины, не список файлов.
 
+## Контракты реализации
+
+### Данные и БД
+Если БД не меняется: `Не затрагивается`.
+
+Если меняется, явно укажи таблицы, поля, типы, обязательность, default, связи, индексы, уникальные ограничения, миграции и совместимость со старыми данными. Backfill и rollback укажи, если они нужны.
+
+### API и внешние контракты
+Если API и внешние контракты не меняются: `Не затрагивается`.
+
+Если меняются, явно укажи метод и путь, auth/permissions, request/query/body, response, ошибки и статус-коды. Webhooks, events, queues и внешние сервисы укажи, если они есть.
+
 ## Фазы выполнения
 
 ### 1. <Название фазы>
@@ -310,8 +325,12 @@ sources:
 - Риски не выносятся в отдельный обязательный раздел. Закрытые риски из research, контекста и мета-ревью должны быть встроены туда, где они исполняются: в `Принятые решения`, фазы, сценарии тестирования, проверки, логирование или эксплуатационные шаги.
 - Существенные решения в `Принятых решениях` имеют источник подтверждения или явное обоснование автономного выбора.
 - В `Целевой алгоритм` попадает сквозная картина процесса.
+- В `Контракты реализации` попадают схемы данных, БД, API и внешние контракты. Если область не затрагивается, напиши `Не затрагивается`.
+- Если план меняет БД, `Данные и БД` обязаны явно описывать таблицы, поля, типы, обязательность/default, связи, индексы/unique, миграции и совместимость со старыми данными.
+- Если план меняет API или внешний контракт, `API и внешние контракты` обязаны явно описывать method/path, auth/permissions, request/query/body, response, ошибки/status codes и внешние каналы при наличии.
 - В `Фазы выполнения` попадают только исполнимые шаги.
 - Каждая фаза обязана иметь `Цель`, `Что сделать`, `Результат`, `Сценарии тестирования`, `Проверка`.
+- В фазах нельзя ограничиваться общими формулировками вроде «обновить UI», «добавить сервис», «реализовать логику». Если фаза затрагивает UI, опиши пользовательский сценарий, состояния успеха/ошибки и видимый результат. Если фаза затрагивает внутреннюю логику, опиши ответственность изменяемых частей, поток данных, новые состояния/ошибки и существующие места, которые нужно адаптировать.
 - Отдельный раздел порядка выполнения не нужен: линейный порядок задаётся номерами фаз и шагами внутри фаз.
 - `test_strategy` обязан менять структуру фаз: TDD — тесты в начале фаз, after_each_phase — тесты после каждой фазы, end_of_plan — отдельная финальная фаза тестов.
 - `logging_strategy` обязан быть отражён в целевом алгоритме, фазах и отдельном разделе `Логирование`.
@@ -321,8 +340,12 @@ sources:
 
 Перед сохранением проверь quality gate:
 - есть `Целевой алгоритм`;
+- есть `Контракты реализации` с подразделами `Данные и БД` и `API и внешние контракты`;
+- если задача затрагивает БД, схема данных не пропущена и не заменена общими словами;
+- если задача затрагивает API или внешний контракт, маршруты/контракты не пропущены и не заменены общими словами;
 - фазы идут в реалистичном порядке реализации;
 - у каждой фазы есть цель, результат, сценарии тестирования и проверка;
+- UI и внутренняя логика в фазах описаны через конкретное поведение, поток данных, состояния и ошибки, если задача их затрагивает;
 - нет неразрешённых формулировок «выбрать», «решить», «можно так или так», «предпочтительно», «при необходимости»;
 - текст написан простым языком: без лишнего жаргона, непояснённых сокращений и тяжёлых терминов;
 - мета-уровень не смешан с шагами исполнения;