@gian-tiaga/eda 2.0.0 → 3.1.0

package/lib/install.js

@@ -19,6 +19,22 @@ const SKILLS_SRC = path.join(PACKAGE_ROOT, 'skills');
 const AGENTS_SRC = path.join(PACKAGE_ROOT, 'agents');
 const PACKAGE_JSON_PATH = path.join(PACKAGE_ROOT, 'package.json');
 const SETTINGS_RELATIVE_PATH = 'docs/settings.yaml';
+const ARTIFACTS_RELATIVE_PATH = 'docs/artifacts';
+const ARTIFACT_DIRECTORY_NAMES = [
+  'aims',
+  'automations',
+  'executions',
+  'fixes',
+  'manual-tests',
+  'plan-review-fixes',
+  'plan-reviews',
+  'plans',
+  'project-starts',
+  'researches',
+  'review-fixes',
+  'reviews',
+  'roadmaps'
+];
 const TARGET_CHOICES = [
   { value: 'claude', label: 'Claude Code', dir: '.claude/skills/' },
   { value: 'codex', label: 'Codex CLI', dir: '.codex/skills/' }
@@ -34,7 +50,19 @@ const RETIRED_SKILLS = [
   'eda-start'
 ];
 const RETIRED_AGENTS = [
-  'eda-commit-context'
+  'eda-commit-context',
+  'eda-plan-review-requirements',
+  'eda-plan-review-rules',
+  'eda-plan-review-architecture',
+  'eda-plan-review-feasibility',
+  'eda-plan-review-execution',
+  'eda-plan-review-verification',
+  'eda-plan-review-api',
+  'eda-plan-review-database',
+  'eda-plan-review-security',
+  'eda-plan-review-frontend',
+  'eda-plan-review-performance',
+  'eda-plan-review-previous'
 ];
 const MANIFEST_FILE = 'eda-manifest.json';
 const SETTINGS_VERSION = 3;
@@ -170,114 +198,6 @@ const DEFAULT_REVIEW_AGENTS = Object.fromEntries(REVIEW_AGENT_DEFINITIONS.map(ag
     }
   }
 ]));
-const PLAN_REVIEW_AGENT_DEFINITIONS = [
-  {
-    key: 'requirements',
-    description: 'Проверяет соответствие плана задаче, scope, критериям готовности и применимым business-требованиям.',
-    auto: 'Эта базовая проверка по умолчанию запускается всегда.',
-    mode: 'always',
-    claude: 'sonnet',
-    codex: 'gpt-5.6-terra'
-  },
-  {
-    key: 'rules',
-    description: 'Проверяет соблюдение AGENTS.md, CLAUDE.md и docs/rules.md.',
-    auto: 'Эта базовая проверка по умолчанию запускается всегда.',
-    mode: 'always',
-    claude: 'haiku',
-    codex: 'gpt-5.6-luna'
-  },
-  {
-    key: 'architecture',
-    description: 'Проверяет архитектурные границы, зависимости и соответствие docs/arch.md.',
-    auto: 'Эта базовая проверка по умолчанию запускается всегда.',
-    mode: 'always',
-    claude: 'opus',
-    codex: 'gpt-5.6-sol'
-  },
-  {
-    key: 'feasibility',
-    description: 'Проверяет реализуемость плана относительно фактического кода и отсутствие скрытого исследования.',
-    auto: 'Эта базовая проверка по умолчанию запускается всегда.',
-    mode: 'always',
-    claude: 'opus',
-    codex: 'gpt-5.6-sol'
-  },
-  {
-    key: 'execution',
-    description: 'Проверяет связность фаз, ID задач, зависимости и размер работы для одного исполнителя.',
-    auto: 'Эта базовая проверка по умолчанию запускается всегда.',
-    mode: 'always',
-    claude: 'sonnet',
-    codex: 'gpt-5.6-terra'
-  },
-  {
-    key: 'verification',
-    description: 'Проверяет тесты, команды проверок, ошибки, логирование, документацию и эксплуатационную готовность.',
-    auto: 'Эта базовая проверка по умолчанию запускается всегда.',
-    mode: 'always',
-    claude: 'sonnet',
-    codex: 'gpt-5.6-terra'
-  },
-  {
-    key: 'api',
-    description: 'Проверяет API, DTO, события, очереди, внешние интеграции и совместимость контрактов.',
-    auto: 'В auto запускается при изменении API, событий, очередей или внешних интеграций.',
-    mode: 'auto',
-    claude: 'sonnet',
-    codex: 'gpt-5.6-terra'
-  },
-  {
-    key: 'database',
-    description: 'Проверяет схему данных, миграции, backfill, индексы, транзакции и rollback.',
-    auto: 'В auto запускается при изменении хранения, моделей, SQL, схем или миграций.',
-    mode: 'auto',
-    claude: 'opus',
-    codex: 'gpt-5.6-sol'
-  },
-  {
-    key: 'security',
-    description: 'Проверяет auth, permissions, внешний ввод, секреты, персональные данные и опасные операции.',
-    auto: 'В auto запускается для auth, permissions, внешнего ввода, секретов и чувствительных данных.',
-    mode: 'auto',
-    claude: 'opus',
-    codex: 'gpt-5.6-sol'
-  },
-  {
-    key: 'frontend',
-    description: 'Проверяет пользовательский сценарий, состояния UI, ошибки, accessibility и адаптивность.',
-    auto: 'В auto запускается для компонентов, стилей, клиентских маршрутов и состояния UI.',
-    mode: 'auto',
-    claude: 'sonnet',
-    codex: 'gpt-5.6-terra'
-  },
-  {
-    key: 'performance',
-    description: 'Проверяет нагрузку, запросы, конкурентность, кеши и горячие пути.',
-    auto: 'В auto запускается для запросов, пакетной обработки, кешей, конкурентности и горячих путей.',
-    mode: 'auto',
-    claude: 'opus',
-    codex: 'gpt-5.6-sol'
-  },
-  {
-    key: 'previous',
-    description: 'Проверяет закрытие findings предыдущей связанной итерации plan-review.',
-    auto: 'В auto запускается только при наличии связанной цепочки review/fix для текущего SHA-256 плана.',
-    mode: 'auto',
-    claude: 'haiku',
-    codex: 'gpt-5.6-luna'
-  }
-];
-const DEFAULT_PLAN_REVIEW_AGENTS = Object.fromEntries(PLAN_REVIEW_AGENT_DEFINITIONS.map(agent => [
-  agent.key,
-  {
-    mode: agent.mode,
-    model: {
-      claude: agent.claude,
-      codex: agent.codex
-    }
-  }
-]));
 const ORHESTRA_STEP_DEFINITIONS = [
   {
     id: 'plan',
@@ -343,11 +263,10 @@ const DEFAULT_SETTINGS = {
     loggingStrategy: 'ask_each_time'
   },
   planReview: {
-    threshold: 95,
-    agents: DEFAULT_PLAN_REVIEW_AGENTS
+    threshold: 100
   },
   planPolish: {
-    limit: 3
+    limit: 2
   },
   review: {
     agents: DEFAULT_REVIEW_AGENTS
@@ -431,11 +350,11 @@ const ORHESTRA_POLISH_LIMIT_CHOICES = [1, 2, 3, 5, 10].map(value => ({
   value,
   name: `${value} ${value === 1 ? 'итерация' : value < 5 ? 'итерации' : 'итераций'}`
 }));
-const PLAN_REVIEW_THRESHOLD_CHOICES = [90, 95, 100].map(value => ({
+const PLAN_REVIEW_THRESHOLD_CHOICES = [80, 90, 100].map(value => ({
   value,
   name: `${value}/100`
 }));
-const PLAN_POLISH_LIMIT_CHOICES = [1, 2, 3, 5, 10].map(value => ({
+const PLAN_POLISH_LIMIT_CHOICES = [1, 2, 3].map(value => ({
   value,
   name: `${value} ${value === 1 ? 'итерация' : value < 5 ? 'итерации' : 'итераций'}`
 }));
@@ -542,6 +461,7 @@ export async function update({ cwd, input = process.stdin, output = process.stdo
     return;
   }
   output.write(`Найдены установленные среды: ${targets.join(', ')}\n`);
+  await migrateArtifactDirectories(cwd, output);
   await configureSettings(cwd, { input, output });
   await syncPackage(cwd, targets, output, { action: 'update' });
 }
@@ -611,6 +531,7 @@ export async function updateAll({
       }
 
       output.write(`Найдены установленные среды: ${targets.join(', ')}\n`);
+      await migrateArtifactDirectories(projectDir, output);
       const projectSettingsPath = path.join(projectDir, SETTINGS_RELATIVE_PATH);
       if (resolvedSettingsMode === 'skip' && await fileExists(projectSettingsPath)) {
         const existingContent = await fs.readFile(projectSettingsPath, 'utf8');
@@ -793,15 +714,6 @@ export async function askSettings({
     target[property] = await selectPrompt({ message, choices, default: target[property] }, { input, output });
   }
 
-  if (requestedSections.has('plan-review')) {
-    settings.planReview.agents = await askPlanReviewAgentSettings({
-      input,
-      output,
-      selectPrompt,
-      seedAgents: settings.planReview.agents,
-      missingKeys
-    });
-  }
   if (requestedSections.has('review')) {
     settings.review.agents = await askReviewAgentSettings({
       input,
@@ -833,25 +745,6 @@ export async function askReviewAgentSettings({
   });
 }
 
-export async function askPlanReviewAgentSettings({
-  input = process.stdin,
-  output = process.stdout,
-  selectPrompt = select,
-  seedAgents = DEFAULT_PLAN_REVIEW_AGENTS,
-  missingKeys = null
-} = {}) {
-  return askAgentSettings({
-    input,
-    output,
-    selectPrompt,
-    definitions: PLAN_REVIEW_AGENT_DEFINITIONS,
-    seedAgents,
-    missingKeys,
-    keyPrefix: 'planReview.agents',
-    label: 'plan-review'
-  });
-}
-
 async function askAgentSettings({ input, output, selectPrompt, definitions, seedAgents, missingKeys, keyPrefix, label }) {
   const configuredAgents = structuredClone(seedAgents);
   const shouldAsk = key => missingKeys === null || missingKeys.has(key);
@@ -1010,6 +903,92 @@ async function findInstalledProjects(rootDir, maxDepth) {
   return projects;
 }
 
+async function migrateArtifactDirectories(cwd, output = process.stdout) {
+  const docsDir = path.join(cwd, 'docs');
+  const artifactsDir = path.join(cwd, ARTIFACTS_RELATIVE_PATH);
+  const legacyDirectories = [];
+
+  for (const directoryName of ARTIFACT_DIRECTORY_NAMES) {
+    const legacyPath = path.join(docsDir, directoryName);
+    const legacyStat = await lstatIfExists(legacyPath);
+    if (!legacyStat) continue;
+    if (!legacyStat.isDirectory() || legacyStat.isSymbolicLink()) {
+      throw new Error(`Ожидался каталог артефактов: ${legacyPath}`);
+    }
+    legacyDirectories.push({ directoryName, legacyPath });
+  }
+
+  if (legacyDirectories.length === 0) {
+    return { migratedDirectories: 0, movedFiles: 0, discardedFiles: 0 };
+  }
+
+  const artifactsStat = await lstatIfExists(artifactsDir);
+  if (artifactsStat && (!artifactsStat.isDirectory() || artifactsStat.isSymbolicLink())) {
+    throw new Error(`Ожидался каталог артефактов: ${artifactsDir}`);
+  }
+  await fs.mkdir(artifactsDir, { recursive: true });
+
+  const result = {
+    migratedDirectories: legacyDirectories.length,
+    movedFiles: 0,
+    discardedFiles: 0
+  };
+  for (const { directoryName, legacyPath } of legacyDirectories) {
+    await mergeArtifactEntry(legacyPath, path.join(artifactsDir, directoryName), result);
+  }
+
+  output.write(
+    `Артефакты перенесены в ${ARTIFACTS_RELATIVE_PATH}/: каталогов ${result.migratedDirectories}, `
+    + `файлов перемещено ${result.movedFiles}, конфликтующих старых файлов удалено ${result.discardedFiles}.\n`
+  );
+  return result;
+}
+
+async function mergeArtifactEntry(sourcePath, destinationPath, result) {
+  const sourceStat = await fs.lstat(sourcePath);
+  const destinationStat = await lstatIfExists(destinationPath);
+
+  if (!destinationStat) {
+    result.movedFiles += await countArtifactFiles(sourcePath, sourceStat);
+    await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+    await fs.rename(sourcePath, destinationPath);
+    return;
+  }
+
+  const mergeDirectories = sourceStat.isDirectory()
+    && !sourceStat.isSymbolicLink()
+    && destinationStat.isDirectory()
+    && !destinationStat.isSymbolicLink();
+  if (!mergeDirectories) {
+    result.discardedFiles += await countArtifactFiles(sourcePath, sourceStat);
+    await fs.rm(sourcePath, { recursive: true, force: true });
+    return;
+  }
+
+  const entries = await fs.readdir(sourcePath, { withFileTypes: true });
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    await mergeArtifactEntry(
+      path.join(sourcePath, entry.name),
+      path.join(destinationPath, entry.name),
+      result
+    );
+  }
+  await fs.rmdir(sourcePath);
+}
+
+async function countArtifactFiles(entryPath, entryStat = null) {
+  const stat = entryStat ?? await fs.lstat(entryPath);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) return 1;
+
+  let count = 0;
+  const entries = await fs.readdir(entryPath, { withFileTypes: true });
+  for (const entry of entries) {
+    count += await countArtifactFiles(path.join(entryPath, entry.name));
+  }
+  return count;
+}
+
 async function ensureSettings(cwd, { input = process.stdin, output = process.stdout } = {}) {
   const settingsPath = path.join(cwd, SETTINGS_RELATIVE_PATH);
   const existingContent = await readFileIfExists(settingsPath);
@@ -1144,13 +1123,6 @@ function migrateSettingsContent(content) {
 
   const planReview = objectValue(raw['plan-review']);
   transfer('planReview.threshold', planReview.threshold, score, value => { settings.planReview.threshold = value; });
-  transferAgentSettings({
-    rawAgents: objectValue(planReview.agents),
-    settingsAgents: settings.planReview.agents,
-    definitions: PLAN_REVIEW_AGENT_DEFINITIONS,
-    prefix: 'planReview.agents',
-    missingKeys
-  });
 
   const planPolish = objectValue(raw['plan-polish']);
   transfer('planPolish.limit', planPolish.limit, positiveInt, value => { settings.planPolish.limit = value; });
@@ -1295,11 +1267,6 @@ ${onFailureThen}
         # Модель для Codex.
         codex: ${configured.model.codex}`;
   }).join('\n\n');
-  const planReviewAgents = formatAgents(
-    PLAN_REVIEW_AGENT_DEFINITIONS,
-    settings.planReview.agents,
-    DEFAULT_PLAN_REVIEW_AGENTS
-  );
   const reviewAgents = formatAgents(REVIEW_AGENT_DEFINITIONS, settings.review.agents, DEFAULT_REVIEW_AGENTS);
 
   return `version: ${SETTINGS_VERSION}
@@ -1329,7 +1296,7 @@ plan:
   # Включает кросс-CLI ревью в eda-plan.
   # true | false
   strict: ${settings.plan.strict ? 'true' : 'false'}
-  # Запускает один eda-plan-review и при необходимости один eda-plan-review-fix.
+  # Запускает изолированный цикл eda-plan-polish.
   # true | false
   review: ${settings.plan.review !== false ? 'true' : 'false'}
   # Задаёт размер плана.
@@ -1346,12 +1313,9 @@ plan:
   logging_strategy: ${settings.plan.loggingStrategy}
 
 plan-review:
-  # План готов только без обязательных findings и при score не ниже этого порога.
+  # Доля закрытых пунктов чек-листа, при которой план считается готовым.
   # 1..100
   threshold: ${settings.planReview.threshold}
-  # Каждая проверка имеет собственный режим запуска и модели для обеих сред.
-  agents:
-${planReviewAgents}
 
 plan-polish:
   # Максимальное число подтверждающих review-итераций.
@@ -1369,7 +1333,7 @@ send-review:
   close_previous_reviews: ${settings.sendReview.closePreviousReviews ? 'true' : 'false'}
 
 discover-automations:
-  # Добавляет docs/plans/ в обычный запуск eda-discover-automations.
+  # Добавляет docs/artifacts/plans/ в обычный запуск eda-discover-automations.
   # true | false
   include_plans: ${settings.discoverAutomations.includePlans ? 'true' : 'false'}
 `;

package/package.json

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

package/skills/eda-aim/SKILL.md

@@ -28,7 +28,7 @@ aim:
 
 В автоматическом режиме основной агент сам выбирает ответ на рабочие вопросы по рекомендации субагента и фактам проекта. Это не отменяет одно обязательное подтверждение человеком точного списка целей до создания нового файла.
 
-Если пользователь передал существующий файл из `docs/aims/`, продолжай его с текущего статуса. Не создавай второй файл для той же цели.
+Если пользователь передал существующий файл из `docs/artifacts/aims/`, продолжай его с текущего статуса. Не создавай второй файл для той же цели.
 
 ## Пакетные агенты
 
@@ -59,7 +59,7 @@ aim:
 
 ## Файл цели
 
-После подтверждения `eda-aim-planner` создаёт `docs/aims/{YYYY-MM-DD}_{HH-MM}_{slug}.md`. Файл должен оставаться коротким и содержать только цель и фактический журнал:
+После подтверждения `eda-aim-planner` создаёт `docs/artifacts/aims/{YYYY-MM-DD}_{HH-MM}_{slug}.md`. Файл должен оставаться коротким и содержать только цель и фактический журнал:
 
 ```markdown
 # <Короткое название>

package/skills/eda-business/SKILL.md

@@ -5,7 +5,7 @@ description: 'Создаёт и обновляет согласованное о
 
 # Скил: Бизнес-логика (eda-business)
 
-Создаёшь и поддерживаешь согласованную бизнес-документацию проекта: короткое оглавление `docs/business.md` и самостоятельные тематические карточки в `docs/business/`. Документы отвечают на вопросы «что должен делать продукт», «для кого», «по каким правилам» и «какой результат считается правильным», но не проектируют техническую реализацию.
+Создаёшь и поддерживаешь согласованную бизнес-документацию проекта: короткое оглавление `docs/business.md` и самостоятельные тематические карточки в `docs/business/`. Каждая карточка подробно фиксирует значимые решения своей темы, но не засоряется сведениями соседних тем и деталями конкретной реализации.
 
 ## Вход из сообщения пользователя
 
@@ -22,11 +22,16 @@ description: 'Создаёт и обновляет согласованное о
 1. **Только business-документация.** Меняй лишь `docs/business.md` и Markdown-файлы непосредственно в `docs/business/`. Не правь код, настройки, правила, архитектуру, планы, тесты или другие документы.
 2. **Целевое поведение.** Карточки фиксируют согласованные требования и бизнес-логику, даже если код пока им не соответствует. Фактические отличия вынеси в последний раздел `Расхождения с реализацией`.
 3. **Никаких догадок как фактов.** Код помогает найти существующие сценарии и вопросы, но не подтверждает продуктовые решения сам по себе.
-4. **Одна тема за раз.** После согласования общего списка полностью проработай текущую тему и получи подтверждение её содержания до записи, затем переходи к следующей.
+4. **Одна тема за раз.** После согласования общего списка полно опиши и подтверди значимые решения текущей темы до записи, затем переходи к следующей.
 5. **В индекс — только готовое.** Не записывай предложенные, незавершённые или спорные темы в `docs/business.md` и не создавай для них черновые карточки.
 6. **Самодостаточные карточки.** Основной текст не должен требовать чтения исходного кода, плана или внешнего материала, чтобы понять бизнес-правило.
-7. **Не проектируй реализацию.** Не назначай классы, таблицы, endpoints, очереди, библиотеки, модули или порядок технических изменений.
+7. **Не проектируй конкретную реализацию.** Не назначай язык, фреймворк, библиотеку, конкретную СУБД, схему данных, классы, функции, внутренние модули или порядок технических изменений.
 8. **Сохраняй подтверждённое.** При обновлении не удаляй и не ослабляй существующее правило, не переименовывай и не удаляй карточку без явного решения пользователя.
+9. **Полнота без шума.** Зафиксируй все подтверждённые детали, которые меняют целевое поведение темы: правила, выбранные алгоритмы, состояния, переходы, ограничения, исключения и наблюдаемые результаты. Не сокращай сложную тему ради краткости; убирай повторы, общие рассуждения и факты, не влияющие на правило.
+10. **Строгая граница темы.** Карточка описывает только названную тему. Сведения о соседнем домене, внутреннем модуле или другой карточке опускай; если у них есть самостоятельное бизнес-значение, предложи отдельную тему, но не включай её в текущую.
+11. **`about` — только обзор.** Это не сводная бизнес-спецификация и не каталог остальных карточек. Кратко опиши сам проект и перечисли его основные пользовательские возможности; не раскладывай их по модулям и не детализируй правила, сценарии и исключения других тем.
+12. **Карточка не привязана к коду.** Код, тесты и конфиги используй для поиска вопросов и проверки текущего поведения, но пиши карточку устойчивым предметным языком. Не включай пути и строки исходников, имена классов, функций, файлов и внутренних модулей — в том числе в `about` и `Расхождения с реализацией`.
+13. **Алгоритм допустим, стек — нет.** Фиксируй выбранный функциональный или security-механизм, если он определяет поведение продукта: например, JWT либо непрозрачные токены с хранением в базе данных, правила выпуска, срока действия, обновления и отзыва. Не регламентируй язык, framework, библиотеку, конкретную СУБД, таблицы и способ программной сборки механизма, если это не отдельное подтверждённое ограничение продукта.
 
 ## Интерактивные вопросы
 
@@ -43,7 +48,7 @@ description: 'Создаёт и обновляет согласованное о
 
 ### 1. Прочитать существующий контекст
 
-Прочитай `docs/business.md` и только карточки, которые относятся к текущей теме. Затем изучи релевантные README, стартовые документы, правила, архитектуру, пользовательские сценарии, routes, модели, тесты и историю, достаточные для понимания фактического поведения.
+Прочитай `docs/business.md` и только карточки, которые относятся к текущей теме. Затем изучи минимальный набор релевантных источников, достаточный для понимания именно этой темы. Для `about` обычно достаточно основного README, метаданных проекта и пользовательских точек входа; не обходи каждый внутренний модуль, route, модель или тест.
 
 Не загружай все карточки и весь код без необходимости. Разделяй:
 
@@ -54,60 +59,61 @@ description: 'Создаёт и обновляет согласованное о
 
 ### 2. Выбрать темы при пустом вызове
 
-Если тема не задана, составь короткий список только из реально применимых тем. Для каждой укажи, что именно будет описано и почему тема нужна проекту. Не используй обязательный универсальный набор: `auth`, `posts`, `payments` и другие названия допустимы только при наличии соответствующего поведения.
+Если тема не задана, составь короткий список только из реально применимых и непересекающихся тем. Для каждой одной фразой укажи, что именно будет описано. Не используй обязательный универсальный набор и не создавай тему для каждого технического модуля: `auth`, `posts`, `payments` и другие названия допустимы только при наличии самостоятельных правил продукта.
 
 Покажи список через `AskUserQuestion` и попроси подтвердить его или изменить. До подтверждения ничего не записывай. После ответа прорабатывай темы последовательно. Если работа прервана, следующий пустой вызов заново анализирует индекс и предлагает только отсутствующие или требующие актуализации темы.
 
 ### 3. Согласовать текущую тему
 
-Собери достаточную бизнес-спецификацию:
+Сначала сформулируй суть темы в одном-двух предложениях. Затем собери все конкретные решения, необходимые для полного описания целевого поведения этой темы. Требования, термины, сценарии, состояния, ограничения, исключения и критерии приёмки добавляй по смыслу, а не ради заполнения универсального чеклиста. Не пропускай значимую конкретику только потому, что карточка получится длинной.
 
-- назначение и границы темы;
-- участники, роли и значимые термины;
-- требования, правила и инварианты;
-- основные сценарии и порядок бизнес-действий;
-- состояния, переходы, ограничения и исключения;
-- ошибки и пограничные случаи, видимые пользователю или внешнему потребителю;
-- проверяемые критерии приёмки.
+Например, карточка аутентификации может подробно фиксировать выбранный вид токенов, их выпуск, срок действия, обновление, отзыв, завершение сессий и значимые ошибки. В ней допустимо выбрать JWT или токены, хранящиеся в базе данных, но не следует назначать язык, framework, библиотеку, конкретную СУБД, таблицы, классы и файлы.
 
-Для `about` вместо детального алгоритма зафиксируй назначение проекта, аудиторию, решаемую проблему, границы, ключевые возможности, основные пользовательские сценарии и общие бизнес-ограничения.
+Для `about` подготовь короткое описание проекта и компактный список его основных возможностей. Не включай аудиторию, решаемую проблему, границы, общие ограничения или пользовательские сценарии отдельными разделами, если пользователь их явно не запросил и они не нужны для самого краткого описания. Не упоминай устройство внутренних модулей и не пересказывай содержимое тематических карточек.
 
-Сравни целевое поведение с реализацией. Подготовь отдельный список подтверждённых расхождений с точными путями и строками, когда они доступны. Отсутствие реализации также является расхождением, если требование уже подтверждено.
+Сравни с реализацией только подтверждённые правила непосредственно текущей темы. Расхождение описывай как отличие наблюдаемого поведения от целевого, без ссылок на исходники и без пересказа устройства кода. В `Расхождения с реализацией` не добавляй наблюдения о соседних модулях, случайно замеченные дефекты, технический долг и неполноту других карточек. Для `about` не перечисляй пофункциональные расхождения: они относятся к отдельным тематическим карточкам. Если прямого существенного расхождения по теме нет, напиши `Известных расхождений не обнаружено.`
 
-Покажи человеку собранное содержание и запроси итоговое подтверждение через `AskUserQuestion`. Если остаётся спорное решение, сначала закрой его отдельным вопросом. Не записывай карточку до подтверждения.
+Покажи человеку короткий текст будущей карточки целиком и запроси итоговое подтверждение через `AskUserQuestion`. Если остаётся спорное решение, сначала закрой его отдельным вопросом. Не записывай карточку до подтверждения.
 
 ### 4. Записать карточку и индекс
 
 Используй стабильное имя файла в lowercase ASCII kebab-case: `docs/business/<topic>.md`.
 
-Обычная тематическая карточка:
+У обычной тематической карточки нет обязательного набора содержательных разделов. Выбирай структуру по сложности темы и фиксируй в ней всю значимую подтверждённую конкретику без лишних разделов, например:
 
 ```markdown
 # <Название темы>
 
-## Назначение и границы
-<что покрывает тема и что не покрывает>
+<краткое описание темы>
 
-## Участники и термины
-<роли и доменные понятия>
+## Правила
 
-## Требования и правила
-<согласованные требования и инварианты>
+- <только необходимые согласованные правила>
 
-## Сценарии и алгоритмы
-<пошаговое бизнес-поведение без технической реализации>
+## Расхождения с реализацией
+
+<подтверждённые отличия с доказательствами либо «Известных расхождений не обнаружено.»>
+```
+
+Если отдельный раздел `Правила` не нужен, не создавай его. Для сложной темы добавь столько смысловых разделов, сколько требуется, чтобы не смешивать правила, алгоритмы, состояния, исключения и критерии. Для простой темы не создавай пустые или формальные разделы.
 
-## Состояния и исключения
-<переходы, ограничения, ошибки и пограничные случаи>
+Для `about.md` используй простой обзорный формат:
 
-## Критерии приёмки
-<наблюдаемые условия корректного поведения>
+```markdown
+# О проекте
+
+<краткое описание проекта>
+
+## Основные возможности
+
+- <возможность на уровне пользователя>
 
 ## Расхождения с реализацией
-<подтверждённые отличия с доказательствами либо «Известных расхождений не обнаружено.»>
+
+Известных расхождений не обнаружено.
 ```
 
-Для `about.md` используй подходящие смысловые разделы из шага 3, но всегда оставляй последним `## Расхождения с реализацией`.
+Сохраняй `Расхождения с реализацией` последним разделом любой карточки.
 
 Создай или обнови `docs/business.md` как короткое оглавление только существующих согласованных карточек:
 
@@ -116,7 +122,7 @@ description: 'Создаёт и обновляет согласованное о
 
 | Описание | Карточка |
 |---|---|
-| Назначение проекта, аудитория и основные возможности | [О проекте](business/about.md) |
+| Краткое описание проекта и основные возможности | [О проекте](business/about.md) |
 | Регистрация, вход, восстановление доступа и права пользователей | [Авторизация](business/auth.md) |
 ```
 
@@ -128,6 +134,11 @@ description: 'Создаёт и обновляет согласованное о
 
 - индекс содержит только существующие согласованные карточки и ровно две колонки `Описание` и `Карточка`;
 - новая или обновлённая карточка соответствует подтверждённому содержанию;
+- карточка не содержит сведений о соседних темах и не раздута необязательными разделами;
+- `about` остаётся коротким обзором проекта и его основных возможностей без описания внутренних модулей;
+- сложная тема подробно фиксирует все значимые подтверждённые правила, алгоритмы, состояния и исключения;
+- текст карточки не ссылается на файлы, строки, классы, функции и внутренние модули текущей реализации;
+- выбранный механизм поведения отделён от языка, framework, библиотеки, конкретной СУБД и схемы реализации;
 - каждое правило однозначно и проверяемо на уровне поведения;
 - техническая реализация не выдана за бизнес-требование;
 - раздел `Расхождения с реализацией` последний и отделяет целевое состояние от текущего;
@@ -142,6 +153,10 @@ description: 'Создаёт и обновляет согласованное о
 - Записывать неподтверждённые темы или черновики в индекс.
 - Выводить бизнес-правило только из текущего кода и сразу считать его целевым.
 - Подменять карточку исследованием, roadmap, архитектурой или планом реализации.
+- Сокращать сложную тему до общего описания и терять подтверждённые правила или алгоритмы.
+- Переписывать в карточку структуру кода, пути, строки, классы, функции и внутренние модули.
+- Использовать `about` как сводку всех доменов, модулей, правил и расхождений проекта.
+- Переносить в текущую карточку подробности и расхождения соседней темы «для контекста».
 - Создавать ссылки из индекса на отсутствующие файлы.
 - Молча удалять, переименовывать или ослаблять подтверждённые требования.
 - Сохранять business-документацию вне `docs/business.md` и `docs/business/`.