From 72c3a8a6683b95f7e734044fdabe568668097c33 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Wed, 26 Aug 2026 00:42:35 +0300 Subject: [PATCH] docs: record SDD audit remediation --- ...ve-openspec-sdd-and-local-orchestration.md | 24 +- audits/2026-08-26-wealth-ledger-sdd/README.md | 26 + .../deepseek-result.md | 178 ++++++ .../gemini-result.md | 117 ++++ .../kimi-result.md | 530 ++++++++++++++++++ .../qwen-result.md | 118 ++++ .../zai-result.md | 85 +++ audits/README.md | 1 + development/audit-remediation.md | 62 +- development/engineering-governance.md | 46 +- .../openspec-authority-and-lifecycle.md | 50 +- package.json | 2 +- 12 files changed, 1229 insertions(+), 10 deletions(-) create mode 100644 audits/2026-08-26-wealth-ledger-sdd/README.md create mode 100644 audits/2026-08-26-wealth-ledger-sdd/deepseek-result.md create mode 100644 audits/2026-08-26-wealth-ledger-sdd/gemini-result.md create mode 100644 audits/2026-08-26-wealth-ledger-sdd/kimi-result.md create mode 100644 audits/2026-08-26-wealth-ledger-sdd/qwen-result.md create mode 100644 audits/2026-08-26-wealth-ledger-sdd/zai-result.md diff --git a/adr/010-native-openspec-sdd-and-local-orchestration.md b/adr/010-native-openspec-sdd-and-local-orchestration.md index 35100c7..053ba2c 100644 --- a/adr/010-native-openspec-sdd-and-local-orchestration.md +++ b/adr/010-native-openspec-sdd-and-local-orchestration.md @@ -4,16 +4,36 @@ status: accepted # Native OpenSpec SDD и минимальная local orchestration -WealthLedger использует project-local schema `wealth-ledger-sdd` OpenSpec 1.10 с последовательностью `Proposal → Delta Specs → Design → Tasks → Apply` и тонкий dispatcher существующих repository gates. Это сохраняет один lifecycle authority в `specs/openspec`, выражает проектные approval boundaries нативными extension points и не вводит второй workflow engine или monorepo control plane для четырёх независимых Git-репозиториев. +WealthLedger использует project-local schema `wealth-ledger-sdd` version 2 с +последовательностью `Proposal → Delta Specs → Design → Tasks → Apply`, один exact +OpenSpec CLI contract из `.cli-version` и тонкие non-mutating verifiers. Это +сохраняет один lifecycle authority в `specs/openspec`, выражает approval +boundaries нативными extension points и не вводит второй workflow engine или +monorepo control plane для четырёх независимых Git-репозиториев. ## Рассмотренные варианты - Встроенная `spec-driven` schema отклонена: она не выражает обязательный переход Specs перед Design и не задаёт Delivery Map или проектные роли артефактов. - Отдельный workflow engine или custom generator отклонён: он создал бы конкурирующий формат и lifecycle authority. - Nx, Turborepo, Bazel, Make или just отклонены для текущего масштаба: workspace не имеет общего dependency graph, build cache или CI, а репозитории уже владеют canonical gates. +- Patch-only, programmatic generator и symlink для root agent projection + отклонены из-за upstream text fragility, второго transformation engine либо + tool/filesystem portability. Выбран committed canonical source tree с + explicit atomic sync и exact drift check. ## Последствия -OpenSpec CLI закреплён exact version contract, а upgrade требует staged generation и проверки generated root `.opencode` projection. Dispatcher знает четыре workspace area, но не реализует build или test logic: он только валидирует Delivery Map и делегирует в repo-owned commands. Approval identity остаётся человеческим workflow constraint, потому что schema моделирует порядок артефактов, но не личность утвердившего. +OpenSpec CLI закреплён exact version contract; новая stable release не включает +auto-upgrade, а смена contract является отдельным SDD change со staged +compatibility fixtures. Project-owned commands и skills имеют versioned source +в `specs`, root `.opencode` является derived projection. Planning verifier до +approval проверяет только детерминированную структуру: capability set, Delivery +Map, rollback, task area и Requirement coverage. + +Dispatcher знает четыре workspace area, но не реализует build или test logic: +он делегирует repo-owned commands. Approval identity остаётся человеческим +workflow constraint, потому что schema моделирует порядок артефактов, но не +личность утвердившего. Semantic review по-прежнему не заменяется structural +checks. Решение пересматривается, если OpenSpec перестанет поддерживать нужный artifact graph, появится обязательный общий CI/build graph или стоимость последовательной локальной orchestration станет существенной. В этих случаях новый ADR сравнивает native evolution с внешним engine либо monorepo platform. diff --git a/audits/2026-08-26-wealth-ledger-sdd/README.md b/audits/2026-08-26-wealth-ledger-sdd/README.md new file mode 100644 index 0000000..1ea2cc3 --- /dev/null +++ b/audits/2026-08-26-wealth-ledger-sdd/README.md @@ -0,0 +1,26 @@ +# Multi-source assessment схемы WealthLedger SDD + +Дата фиксации snapshot: 2026-08-26. + +Этот каталог — неизменяемый source snapshot пяти независимых внешних +модельных оценок schema `wealth-ledger-sdd`. Отчёты содержат claims и +рекомендации внешних моделей, но не являются authority проекта и не заменяют +OpenSpec requirements, engineering governance, ADR или проверенное as-built +состояние. Принятые решения и текущая remediation находятся только в +[live registry](../../development/audit-remediation.md). + +Исходные файлы перенесены byte-for-byte из unversioned workspace folder +`sdd-audit`. До удаления исходной папки для каждого файла были сопоставлены +byte count, `cmp` и SHA-256; все пять сравнений прошли. + +| Source report | Bytes | SHA-256 | +| --- | ---: | --- | +| [DeepSeek](deepseek-result.md) | 19,319 | `2d50f4c195507ceb079d69489c03f1ea8a81185e2594dd51ff6a293ab8198db8` | +| [Gemini](gemini-result.md) | 10,371 | `af95a4c208c993621a6c15102a1e26684eee6c2966b166f6ba23b600d0e33696` | +| [Kimi](kimi-result.md) | 23,100 | `31d423903cde2d7c1feb711cc625c77864964bb66cfd0cacb734c5c6bbdddd17` | +| [Qwen](qwen-result.md) | 11,035 | `1b6582efe55b7044d2bebc9c1a146df1963e4103c5517c259ccf617d6d2b4f14` | +| [Z.AI](zai-result.md) | 8,391 | `0bdb7785087c8d1b6fe532d578804aa498bfc90935623d79c1003cd1899d5bad` | + +Суммарный размер raw evidence: 72,216 bytes. Snapshot files не редактируются +при изменении triage или remediation status; новый аудит создаёт новый каталог +и обновляет тот же live registry. diff --git a/audits/2026-08-26-wealth-ledger-sdd/deepseek-result.md b/audits/2026-08-26-wealth-ledger-sdd/deepseek-result.md new file mode 100644 index 0000000..79df176 --- /dev/null +++ b/audits/2026-08-26-wealth-ledger-sdd/deepseek-result.md @@ -0,0 +1,178 @@ +# Анализ схемы Spec‑Driven Development (openspec) для pet‑проектов + +## 1. Введение + +Данный документ содержит оценку пользовательской схемы `schema.yaml`, предназначенной для организации процесса **Spec‑Driven Development (SDD)** с использованием фреймворка `openspec`. Схема описывает жизненный цикл изменения: от формулирования намерения (`proposal`) до реализации (`tasks`) и выполнения (`apply`). Анализ выполнен на основе предоставленных артефактов (`proposal.md`, `spec.md`, `design.md`, `tasks.md`) и самой схемы. + +**Общая оценка:** схема **качественная, продуманная и функциональная**. Она соответствует лучшим практикам SDD, обеспечивает чёткое разделение уровней абстракции и поддерживает эволюционное развитие спецификаций. Однако присутствуют области, которые можно улучшить для повышения удобства работы, автоматизации и снижения когнитивной нагрузки на AI‑агента. + +--- + +## 2. Сильные стороны схемы + +- **Чёткое разделение артефактов** + Каждый артефакт решает свою задачу: + - `proposal` — *почему* и *что* (бизнес‑намерение); + - `specs` — *какое наблюдаемое поведение* (контракт); + - `design` — *как архитектурно* (решения); + - `tasks` — *что конкретно сделать* (реализация). + Это предотвращает смешивание уровней и упрощает коммуникацию между участниками. + +- **Поведенческий фокус в спецификациях** + Требования формулируются с использованием `SHALL/MUST` и сопровождаются сценариями в формате **WHEN‑THEN**, что делает их проверяемыми и независимыми от реализации. + +- **Поддержка дельт** + Операции `ADDED`, `MODIFIED`, `REMOVED` и `RENAMED` позволяют аккуратно эволюционировать существующие возможности, сохраняя историю изменений. + +- **Учёт архитектурных решений** + В `design` присутствуют обязательные разделы: `Delivery Map` (привязка к областям), `Contract Gate Decision` (для API), `Solution Assessment` (для сравнения готовых решений). Это способствует принятию обоснованных технических решений. + +- **Практичные задачи** + `tasks` разбиты на выполнимые шаги с указанием верификации (команды, наблюдаемые результаты). Задачи привязаны к областям из Delivery Map, что обеспечивает покрытие всех affected‑зон. + +- **Интеграция с `openspec`** + Использование `store`, `planningHome.root`, флага `skip_specs` и явной инструкции по архивации показывает глубокое понимание инструмента и его особенностей. + +--- + +## 3. Замечания и области для улучшения + +### 3.1. Избыточная детализация инструкций +Инструкции для каждого артефакта содержат много пояснений (повторяющиеся правила, подробное описание `planningHome.root`, форматирования). Это усложняет восприятие AI и увеличивает вероятность ошибок при генерации. + +**Риск:** AI может пропустить важное правило из‑за большого объёма текста. + +### 3.2. Отсутствие машинной валидации формата +Хотя инструкции описывают правильный синтаксис (например, ровно 4 `#` для сценариев), нет автоматической проверки на этапе генерации. AI может случайно отклониться от ожидаемого формата, и ошибка обнаружится только при валидации `openspec validate`. + +**Риск:** увеличение итераций на исправление. + +### 3.3. Недостаточная поддержка многокомпонентных изменений +В схеме не указано, как обрабатывать изменения, затрагивающие **несколько репозиториев** (например, синхронизация API‑контрактов между бэкендом и фронтендом). Упоминается только `Delivery Map` с областями, но нет явных разделов для координации версий, порядка деплоя или обратной совместимости. + +**Риск:** несогласованность при параллельной разработке. + +### 3.4. Размытые критерии для `Solution Assessment` +Требуется включать этот раздел, когда изменение вводит или существенно заменяет "дорогостоящее необратимое решение". Однако триггеры перечислены в скобках (auth, storage, external integration и т.п.), но они не формализованы. AI может пропустить необходимость анализа, если не распознает ситуацию. + +**Риск:** принятие неоптимальных технических решений без сравнения альтернатив. + +### 3.5. Отсутствие явного этапа утверждения спецификаций +После создания `specs` нет артефакта или флага, обозначающего их утверждение владельцем (например, `status: draft | approved`). В `proposal` требуется утверждение, но для `specs` – нет. Это может привести к тому, что `design` будет писаться по неутверждённым требованиям. + +**Риск:** переделки при изменении требований на поздних этапах. + +### 3.6. Избыточность при модификации требований +Инструкция требует копировать **полное** содержание существующего требования (включая все сценарии) в секцию `MODIFIED`. Это увеличивает объём дельты и риск рассинхронизации (например, если в исходном требовании позже появится изменение, а дельта этого не отразит). Хотя такой подход безопасен для архивации, он громоздкий. + +**Риск:** ошибки копирования и потери изменений. + +### 3.7. Отсутствие примеров для сложных сценариев +В инструкции приведён только простой пример для нового требования. Нет примеров для `MODIFIED` (с полным копированием), для `RENAMED`, для `design` с заполненным `Solution Assessment` или для `tasks` с перекрёстными зависимостями. + +**Риск:** AI может неправильно интерпретировать формат, особенно для модификаций. + +### 3.8. Неполное описание процесса `apply` +В секции `apply` указано "работать с pending tasks и отмечать выполненные", но не описаны завершающие шаги: проверка всех задач, запуск тестов, обновление документации, создание коммита/PR, архивация изменения в `openspec` store. Это оставляет пространство для неполного завершения. + +**Риск:** незавершённые изменения, потерянные артефакты. + +### 3.9. Слабая трассируемость между артефактами +Хотя в `tasks` сказано "ссылаться на specs и design", нет явного механизма привязки задач к конкретным требованиям или архитектурным решениям. Например, не указано, какая задача реализует какой requirement. + +**Риск:** сложно проверить полноту покрытия и проследить impact изменения. + +--- + +## 4. Предложения по улучшению + +### 4.1. Упростить инструкции, вынеся общие правила в отдельный файл +- Создать `_rules.md` (или `.openspec-rules.md`) в корне проекта, где описать: + - общие требования к форматированию; + - правила работы с `planningHome.root`; + - пояснения по `skip_specs` и дельта‑операциям. +- В `schema.yaml` для каждого артефакта оставить только **специфичные** для него инструкции, ссылаясь на общие правила. + +**Плюсы:** уменьшение объёма инструкций, снижение когнитивной нагрузки на AI, централизованное обновление правил. + +### 4.2. Добавить машинную валидацию формата при генерации +- Интегрировать проверку сгенерированных файлов через `openspec validate --strict` (или внешний валидатор) перед сохранением. +- В инструкции добавить шаг: "После генерации выполни `openspec validate --strict` и исправь ошибки". + +**Плюсы:** автоматическое обнаружение синтаксических ошибок, сокращение циклов доработки. + +### 4.3. Явно определить процесс для кросс‑репозиторных изменений +- В `design` добавить раздел **Cross‑repo Dependencies**, где перечислять: + - затронутые репозитории и их версии; + - необходимый порядок деплоя; + - требования к обратной совместимости (если применимо). +- При необходимости создать отдельный артефакт `integration-plan.md`, который включается в change. + +**Плюсы:** синхронизация разработки, снижение риска несовместимости. + +### 4.4. Формализовать критерии для включения `Solution Assessment` +- Сделать раздел обязательным для всех изменений, кроме тех, что помечены как `trivial` (например, исправление опечаток, рефакторинг без изменения поведения). +- В инструкции перечислить **конкретные области**, требующие анализа, в виде чек‑листа: + - [ ] Аутентификация/авторизация + - [ ] Хранилище данных (схема, миграции) + - [ ] Внешние интеграции (новые API, сторонние сервисы) + - [ ] Кэширование + - [ ] Конкурентность + - [ ] Наблюдаемость (логи, метрики, трейсинг) + - [ ] Инфраструктура (новые компоненты, изменение конфигурации) +- Если ни один пункт не затронут, раздел можно пропустить с пометкой `N/A` и кратким обоснованием. + +**Плюсы:** единообразие, предотвращение пропусков. + +### 4.5. Добавить этап утверждения спецификаций +- Ввести артефакт `approval.md` или поле `status` в начале каждого `spec.md` (например, `## Status: Draft | Approved`). +- В цепочке зависимостей указать, что `design` может начинаться только после того, как все дельта‑спецификации помечены как `Approved` (владельцем продукта или техническим лидом). +- Это можно реализовать через ручную проверку или через CI‑шаг, требующий комментария. + +**Плюсы:** прозрачность, снижение риска переделок. + +### 4.6. Оптимизировать модификацию требований (альтернатива копированию) +- Вместо полного копирования разрешить указывать **изменения** в формате diff (например, с использованием маркеров `<<<` / `>>>` или просто явное описание изменений). +- При архивации автоматически применять эти изменения к базовому `spec.md` с помощью скрипта слияния. +- Однако это требует более сложной обработки. Если такой возможности нет, то сохранить текущий подход, но добавить рекомендацию использовать **внешние инструменты** для поиска и копирования (например, `openspec show`). + +**Плюсы:** уменьшение дублирования, снижение ошибок. + +### 4.7. Добавить примеры для всех типов дельт и сложных ситуаций +- В инструкцию или в отдельный файл `_examples.md` включить примеры: + - **MODIFIED** с полным копированием существующего требования и его изменением. + - **RENAMED** с указанием FROM/TO. + - **REMOVED** с Reason и Migration. + - **design** с заполненным `Solution Assessment` (например, выбор между готовым и кастомным решением). + - **tasks** с перекрёстными зависимостями между репозиториями. + +**Плюсы:** уменьшение неоднозначности для AI, повышение качества генерируемых артефактов. + +### 4.8. Дополнить процесс `apply` завершающими шагами +- В секцию `apply` добавить: + - После завершения всех задач: запустить полный набор тестов (CI‑пайплайн). + - Проверить, что все артефакты соответствуют актуальному состоянию кода. + - Создать коммит с изменениями в коде и обновлёнными спецификациями. + - Выполнить `openspec archive ` для переноса дельт в основной `specs` store. + - Удалить директорию изменения или обновить статус в системе отслеживания задач. + +**Плюсы:** гарантированное завершение, предотвращение потери изменений. + +### 4.9. Ввести трассируемость через мета‑данные в задачах +- Добавить в каждую задачу поля (в виде комментариев или меток), например: + - `implements: ` – ссылка на конкретное требование. + - `related-to: ` – ссылка на решение в design. +- Это можно сделать через формат: `- [ ] 1.1 Implement export feature (implements: export-data, related: design#cache-decision)` +- Или вынести в отдельную колонку, если используется система управления задачами. + +**Плюсы:** прослеживаемость, упрощение ревью и аудита. + +--- + +## 5. Заключение + +Предоставленная схема является **надёжной и работоспособной** основой для SDD в pet‑проектах и даже в небольших командах. Она грамотно использует возможности `openspec` и обеспечивает дисциплину в разработке. Предложенные улучшения направлены на **снижение когнитивной нагрузки, повышение автоматизации и устранение потенциальных пробелов** при работе с несколькими репозиториями и сложными изменениями. + +Рекомендуется внедрять улучшения поэтапно, начиная с наиболее критичных (например, добавление валидации и формализация `Solution Assessment`), а затем дорабатывать процесс по мере накопления опыта. + +Данный анализ может быть использован как руководство по дальнейшему развитию вашей SDD‑системы. diff --git a/audits/2026-08-26-wealth-ledger-sdd/gemini-result.md b/audits/2026-08-26-wealth-ledger-sdd/gemini-result.md new file mode 100644 index 0000000..d37fc8d --- /dev/null +++ b/audits/2026-08-26-wealth-ledger-sdd/gemini-result.md @@ -0,0 +1,117 @@ +# Анализ схемы Spec-Driven Development (wealth-ledger-sdd) и рекомендации по улучшению + +## 1. Общий обзор и контекст + +Представленная схема **wealth-ledger-sdd** реализует Spec-Driven Development (SDD) поверх фреймворка `openspec`. Конфигурация рассчитана на работу AI-агента из общей корневoй директории, объединяющей несколько отдельных репозиториев, с хранением спецификаций в изолированном хранилище (`openspec store`). + +Пайплайн планирования состоит из 4 последовательных этапов: +1. **Proposal** (`proposal.md`) — продуктовое и бизнес-обоснование («Зачем» и «Что меняется на верхнем уровне»). +2. **Specs** (`specs/**/*.md`) — контракты наблюдаемого поведения системы («ЧТО система делает»). +3. **Design** (`design.md`) — техническая архитектура и решения по реализации («КАК сделать»). +4. **Tasks** (`tasks.md`) — атомарный чек-лист задач для выполнения («ЧТО СДЕЛАТЬ конкретно»). + +--- + +## 2. Анализ сильных сторон (Strengths) + +* **Строгая синтаксическая дисциплина для LLM:** + Инструкции к артефакту `specs` содержат четкие предохранители против специфических багов генерации Markdown у AI-моделей (например, строго 4 хештега `#### Scenario:` и нормативные глаголы `SHALL`/`MUST`). Это гарантирует предсказуемый парсинг артефактов со стороны OpenSpec CLI. +* **Изоляция планирования от продуктового кода:** + Использование переменной `planningHome.root` гарантирует корректную работу с `wealth-ledger-specs` store. Репозитории сервисов не засоряются промежуточными черновиками и файлами планирования. +* **Защита от избыточной работы (Build-vs-Buy Control):** + Обязательный раздел `Solution Assessment` в `design.md` предотвращает попытки AI «изобретать велосипед» при добавлении авторизации, кеширования, интеграций или инфраструктурных утилит. +* **Прагматичная стратегия тестирования:** + Инструкция к `tasks.md` явно задает зоны, где тесты обязательны (финансы, безопасность, персистентность, публичные контракты), и запрещает избыточные unit-тесты для DTO, тонких адаптеров и декларативных структур. +* **Четкое разделение ответственности между этапами:** + Запрет на упоминание технологий в `proposal.md` предотвращает преждевременное принятие архитектурных решений до согласования целей бизнеса. + +--- + +## 3. Анализ узких мест и рисков в мультирепозиторной среде + +* **Неопределенность адресации файлов в мультирепо (File Path Ambiguity):** + В текущих шаблонах `tasks.md` и `design.md` отсутствуют явные требования указывать имя репозитория. В рабочей директории с десятком сервисов задача вида `Modify user.service.ts` приведет к ошибкам адресации или поиску файла по всем подпапкам. +* **Размытый фокус затронутых репозиториев на старте:** + В `proposal.md` есть секция `Impact`, но нет явного списка целевых сервисов. Агент может не рассчитать требуемый контекст и пропустить смежный сервис на этапе проектирования контрактов. +* **Высокий оверхед на мелкие изменения (Fast-Track overhead):** + Полный 4-этапный цикл избыточен для локального рефакторинга или точечного багфикса. Хотя параметр `skip_specs: true` предусмотрен, генерация `design.md` и `proposal.md` для однострочных правок влечет лишние затраты токенов и времени. +* **Риск раздувания контекстного окна (Context Window Bloat):** + Запуск AI-агента из единого корня открывает ему доступ ко всему коду всех проектов. Без явных ограничений в промпте и конфигурации агент может считывать лишние репозитории, исчерпывая лимит контекста. + +--- + +## 4. Предложения по улучшению (Improvement Proposals) + +### 4.1. Внедрение явной мультирепозиторной адресации + +#### А. Секция Target Repositories в `proposal.md` +Добавьте в шаблон `proposal.md` секцию, фиксирующую список затронутых репозиториев: + +```markdown +## Target Repositories + + +- ``: <роль репозитория в данном изменении> +``` + +#### Б. Строгий формат задач в `tasks.md` +Обновите инструкцию артефакта `tasks` в `schema.yaml`, обязывая AI указывать путь к репозиторию: + +```yaml +# В инструкции tasks в schema.yaml: +- Каждая задача MUST указывать целевой репозиторий в формате: `- [ ] X.Y [] ` +``` + +Пример сгенерированной задачи: +```markdown +- [ ] 1.1 [auth-service] Add standard JWT validation middleware and verify auth test suite passes +- [ ] 1.2 [frontend-app] Update API client DTO types to align with new contract +``` + +--- + +### 4.2. Организация Fast-Track сценария для точечных правок + +Для оптимизации работы над некрупными задачами рекомендуется предусмотреть ускоренный пайплайн. + +1. **Если изменение не меняет внешнее поведение:** + В `.openspec.yaml` устанавливается `skip_specs: true`. +2. **Сокращенный Design:** + В инструкцию `design` добавьте правило: если `Delivery Map` затрагивает только 1 репозиторий и `runtime-openapi` равен `N/A`, разделы `Solution Assessment` и `Migration Plan` можно опускать. + +--- + +### 4.3. Усиление Contract Gate Decision + +В мультирепозиторном окружении изменение контракта API в одном сервисе сразу требует обновления клиента в другом. Уточните таблицу `Contract Gate Decision` в `design.md`: + +```markdown +### Contract Gate Decision + +| Gate | Status | Affected Repositories | Reason | +| --- | --- | --- | --- | +| runtime-openapi | `required` / `N/A` | `backend-api`, `frontend-web` | | +| internal-proto | `required` / `N/A` | `billing-service`, `orders-service` | | +``` + +--- + +### 4.4. Оптимизация контекста AI-агента + +При запуске агента из общего корня настройте файл `.aiignore` (или `.cursorignore` / `.windsurfignore` в зависимости от используемого CLI/IDE) в корневой папке: + +1. Исключите тяжелые бинарники, папки сборки и зависимости (`**/node_modules`, `**/dist`, `**/target`, `**/.git`). +2. Запретите агенту просматривать репозитории, не указанные в `Target Repositories` для текущей задачи. + +--- + +## 5. Итоговая оценка качества схемы + +| Критерий | Оценка (1-5) | Комментарий | +| --- | --- | --- | +| **LLM-friendly (предсказуемость)** | **5/5** | Отличные предохранители против сбоев синтаксиса и парсинга Markdown. | +| **Архитектурная строгость** | **5/5** | Баланс между бизнес-целями, specs и архитектурным проектированием. | +| **Мультирепозиторная адаптация** | **3.5/5** | Требует добавления явных указателей путей репозиториев в `tasks` и `proposal`. | +| **Эффективность по скорости/токенам** | **4/5** | Отлично для фич, требует Fast-Track сценария для мелких правок. | + +**Вердикт:** Схема находится на очень высоком уровне разработки. После внесения точечных правок по мультирепозиторной адресации и фильтрации контекста она станет эталонной для мультисервисной Spec-Driven разработки. diff --git a/audits/2026-08-26-wealth-ledger-sdd/kimi-result.md b/audits/2026-08-26-wealth-ledger-sdd/kimi-result.md new file mode 100644 index 0000000..741ebed --- /dev/null +++ b/audits/2026-08-26-wealth-ledger-sdd/kimi-result.md @@ -0,0 +1,530 @@ +# Анализ openspec SDD-схемы: wealth-ledger-sdd + +> **Версия схемы:** 1 +> **Автор анализа:** AI-ассистент +> **Дата:** 2026-08-25 + +--- + +## 1. Общая оценка + +**B+ / «Готова к использованию, есть куда расти»** + +Схема представляет собой зрелый, хорошо структурированный Spec-Driven Development workflow для pet-проектов с multi-repo архитектурой и выделенным specs-store. Pipeline `proposal → specs → design → tasks` с жёстким разделением ответственности между фазами — это правильный фундамент. Схема явно ориентирована на работу с AI-агентом: чёткие prompts, машиночитаемые форматы, парсимый прогресс. + +--- + +## 2. Что сделано сильно + +### 2.1. Чёткое разделение ответственности между фазами + +Каждая фаза имеет строгое назначение: + +| Фаза | Ответственность | Что исключено | +|------|----------------|---------------| +| **Proposal** | «Почему» и «что» — намерение, проблема, scope | Технологии, библиотеки, API, имена файлов | +| **Specs** | Behavior contract — наблюдаемое поведение | Внутренние классы/функции, шаги реализации | +| **Design** | Архитектурные решения и rationale | Построчная инструкция, список правок | +| **Tasks** | Конкретные действия с verification | Архитектурные обоснования | + +Это защищает от классической ошибки: выбор технологий на этапе «намерения». + +### 2.2. Delta-операции в specs + +Поддержка четырёх операций — **ADDED**, **MODIFIED**, **REMOVED**, **RENAMED** — делает specs пригодными для эволюции, а не только для greenfield-разработки. Особенно сильно: + +- **MODIFIED** требует полного копирования блока requirement — защита от потери деталей при архивации в openspec. +- **REMOVED** требует **Reason** и **Migration** — забота о обратной совместимости. + +### 2.3. Строгие правила формата specs + +- **SHALL/MUST** для нормативных требований (исключение `should/may`) +- **#### Scenario** с ровно 4 хэшами — с учётом silent fail это критически важное правило +- **WHEN/THEN** структура — проверяемые сценарии +- **Обязательный `Purpose`** для новых capability (50+ символов под strict-валидацию) + +Это делает specs одновременно человекочитаемыми и пригодными для валидации. + +### 2.4. Contract Gate Decision в Design + +Выделенное внимание к `runtime-openapi` — признак зрелого подхода. В multi-repo setup, где API-контракты разделяют frontend и backend, это предотвращает рассинхронизацию сторон контракта. + +### 2.5. Правильная работа с Open Questions + +Критерий «если вопрос меняет specs, подход или tasks — решай сейчас, не откладывай» — это ловушка, в которую попадают многие шаблоны. Ты её явно обозначил. + +### 2.6. Tasks с обязательным verification + +Каждая задача должна иметь **planned verification action** — команда, проверка наблюдаемого поведения или delivered artifact. Это DoD на уровне отдельной задачи. + +Также хорошо сформулировано исключение: «Не требуй отдельный unit test только из-за изменения файла». DTO без логики, thin adapters, declarative structures проверяются существующим integration gate. + +### 2.7. Apply phase с отслеживанием прогресса + +Парсинг checkbox'ов (`- [ ]`) для отслеживания — прагматичное решение для AI-агента. Нет необходимости в сложном state machine. + +### 2.8. Интеграция с openspec store + +Схема корректно учитывает store-aware пути (`planningHome.root`), не предполагает repo-relative структуру. Это критично для multi-repo setup с выделенным specs-репозиторием. + +--- + +## 3. Области для улучшения + +### 3.1. Нет review gates между фазами + +В `schema.yaml` есть `requires` (specs требует proposal), но нет явного **checkpoint'а утверждения**. + +**Риск:** AI-агент может сгенерировать Design до реального review specs. В pet-проектах, где «владелец продукта» — это сам разработчик, риск ещё выше: нет естественного барьера «кто-то другой должен посмотреть». + +**Проявление:** +- Design создаётся с непроверенными предположениями +- Tasks строятся на неверных specs +- Regression: приходится переписывать несколько фаз + +### 3.2. Нет traceability между specs и tasks + +Нет механизма проверки, что каждый requirement из specs покрыт задачей в tasks.md. Сейчас это держится в голове разработчика (или AI-агента). + +**Риск:** +- Пропущенные requirements +- «Лишние» задачи, не связанные с specs +- Невозможность аудита completeness change'а + +### 3.3. Spec.md template неполный + +В `spec.md` template есть только `## ADDED Requirements`. Но в instruction к specs описаны 4 операции. Для **MODIFIED** и **REMOVED** шаблоны сложнее — их стоит добавить в template с примерами. + +**Риск:** AI-агент или разработчик может неправильно оформить MODIFIED (например, внести частичные изменения вместо полного блока), что приведёт к потере деталей при архивации. + +### 3.4. Нет «Definition of Done» для change целиком + +Когда change считается завершённым? Когда все tasks checked? А кто проверяет, что реализация соответствует specs? + +**Риск:** +- Change считается «готовым», но specs не покрыты +- Нет единого артефакта, который можно было бы archive'ить как evidence + +### 3.5. Нет управления зависимостями между changes + +В multi-repo setup с shared specs store рано или поздно появится change B, который блокируется change A. Сейчас это не выразимо в схеме. + +**Риск:** +- Параллельная работа над конфликтующими changes +- Merge-конфликты в specs-store +- Нарушение порядка архивации + +### 3.6. Нет приоритизации и sizing'а в tasks + +Даже минимальная маркировка `S/M/L` помогает AI-агенту планировать сессии и разработчику — оценивать объём. + +### 3.7. Нет явного механизма для «тёплого» отката + +Если change реализован, но вызывает regression — как откатить? Схема описывает forward-only flow. + +**Риск:** +- Data migration без rollback-стратегии +- Breaking changes в public API без deprecation period +- Security-изменения, которые сложно отменить + +### 3.8. Apply phase — неясность с «context files» + +В multi-repo setup «read context files» требует понимания, какие именно файлы релевантны. Сейчас это оставлено на усмотрение AI. + +**Риск:** +- AI читает лишние файлы — контекст переполняется +- AI пропускает релевантные файлы — решения принимаются на неполных данных + +--- + +## 4. Предложения по улучшению + +### 4.1. Добавить review gate между specs и design + +**Формат:** Новый артефакт или секция в существующих файлах. + +**Вариант A — отдельный артефакт `review.md`:** + +```yaml +# schema.yaml +- id: review + generates: review.md + description: Checkpoint before design — verify specs completeness and correctness + template: review.md + requires: [specs] +``` + +**Содержимое `review.md`:** + +```markdown +## Specs Review Checklist + +- [ ] Каждый capability из Proposal имеет соответствующий spec-файл +- [ ] Все requirements используют SHALL/MUST (нет should/may) +- [ ] Каждый requirement имеет хотя бы один scenario +- [ ] Все scenarios используют ровно 4 уровня заголовков (`####`) +- [ ] Для MODIFIED requirements скопирован полный блок (не частично) +- [ ] Для REMOVED requirements указаны Reason и Migration +- [ ] В specs отсутствуют технические детали (имена классов, библиотеки) +- [ ] New capabilities имеют секцию `## Purpose` (50+ символов) +- [ ] `skip_specs: true` установлен только при отсутствии behavior changes + +## Review Decision + +- [ ] **APPROVED** — переходим к Design +- [ ] **REJECTED** — возврат к Specs, причина: +``` + +**Вариант B — inline в `schema.yaml`:** + +Добавить в `design` артефакт поле `prerequisites`: + +```yaml +- id: design + generates: design.md + # ... + prerequisites: + - type: review + artifact: specs + checklist: review.md +``` + +**Рекомендация:** Вариант A — проще для AI-агента (явный файл, явный checklist). + +--- + +### 4.2. Добавить traceability: specs → tasks + +**Формат:** Convention в tasks.md + опциональный артефакт `traceability.md`. + +**Convention в tasks.md:** + +```markdown +## 2. Core Implementation + +- [ ] 2.1 Implement user export + **Spec:** `specs/data-export/spec.md#requirement-user-can-export-data` + **Verification:** `npm test data-export` + +- [ ] 2.2 Add CSV formatting utilities + **Spec:** `specs/data-export/spec.md#requirement-export-format` + **Verification:** unit tests cover quoting and delimiters +``` + +**Автоматический артефакт `traceability.md`** (генерируется AI-агентом после tasks): + +```markdown +## Traceability Matrix + +| Spec Requirement | Task | Status | +|------------------|------|--------| +| data-export#user-can-export-data | 2.1 | ⬜ | +| data-export#export-format | 2.2 | ⬜ | + +## Orphan Tasks (no spec link) +- 3.1 Update README — **INFO:** docs-only, no spec required + +## Uncovered Requirements +- data-export#error-handling — **WARNING:** no task linked +``` + +**Рекомендация:** Начать с convention (ручная ссылка в tasks), затем добавить автоматическую генерацию traceability.md. + +--- + +### 4.3. Дополнить spec.md template примерами для всех delta-операций + +**Текущий template** (`spec.md`) содержит только `## ADDED Requirements`. + +**Предлагаемый полный template:** + +```markdown +## Purpose + + +## ADDED Requirements + +### Requirement: + + +#### Scenario: +- **WHEN** +- **THEN** + +## MODIFIED Requirements + +### Requirement: + + +#### Scenario: +- **WHEN** +- **THEN** + +## REMOVED Requirements + +### Requirement: +**Reason:** +**Migration:** + +## RENAMED Requirements + +### Requirement: +**FROM:** +**TO:** +``` + +**Почему это важно:** AI-агент, следуя template, будет генерировать корректные MODIFIED-блоки. Без примера риск частичного копирования высок. + +--- + +### 4.4. Добавить Definition of Done для change целиком + +**Новый артефакт `done.md`:** + +```yaml +# schema.yaml +- id: done + generates: done.md + description: Completion evidence and verification summary + template: done.md + requires: [tasks] +``` + +**Содержимое `done.md`:** + +```markdown +## Completion Evidence + +### Specs Coverage +- [ ] All requirements from delta specs have corresponding tasks +- [ ] All tasks are completed and verified +- [ ] Traceability matrix has no uncovered requirements + +### Verification Summary +| Area | Gate | Status | Evidence | +|------|------|--------|----------| +| Backend | `npm test` | ✅ | All tests pass | +| Frontend | `npm run build` | ✅ | Build succeeds | +| API Contract | `runtime-openapi` | ✅ | Schema matches implementation | + +### Regression Check +- [ ] Existing specs не нарушены (`openspec validate`) +- [ ] Existing tests не сломаны + +### Archive Ready +- [ ] All artifacts saved in canonical store +- [ ] `.openspec.yaml` обновлён +``` + +**Альтернатива:** Добавить как секцию в `tasks.md` в конце, но отдельный артефакт лучше для AI-агента (явный финальный checkpoint). + +--- + +### 4.5. Добавить управление зависимостями между changes + +**Добавить в proposal.md template:** + +```markdown +## Dependencies + +### Blocked By + +- [ ] `change-id-1`: + +### Blocks + +- `change-id-2`: + +### Related + +- `change-id-3`: +``` + +**В `schema.yaml` добавить валидацию:** + +```yaml +validation: + dependencies: + check_store: true # проверять, что blocked-by changes завершены +``` + +--- + +### 4.6. Добавить sizing в tasks + +**Convention в tasks.md:** + +```markdown +## 2. Core Implementation + +- [ ] 2.1 Implement user export + **Size:** M (2-4 часа) + **Spec:** `specs/data-export#user-can-export-data` + **Verification:** `npm test data-export` +``` + +**Размеры:** +- **S** — до 1 часа (config change, DTO, простой adapter) +- **M** — 2-4 часа (новая feature, refactoring с тестами) +- **L** — 1-2 дня (сложная интеграция, data migration) +- **XL** — требует декомпозиции + +**Польза:** AI-агент может планировать сессии (не брать L-задачу в конце дня), разработчик — оценивать объём change. + +--- + +### 4.7. Усилить rollback-стратегию + +**Добавить в design.md template обязательную секцию:** + +```markdown +## Rollback Plan + + + +### Rollback Trigger + + +### Rollback Steps +1. +2. + +### Data Safety + + +### Rollback Verification + +``` + +**В `schema.yaml` добавить условие:** + +```yaml +- id: design + # ... + required_sections: + - Rollback Plan # если change трогает migration/api/auth +``` + +--- + +### 4.8. Добавить context mapping для multi-repo + +**Новый артефакт `context.yaml` (в корне change или в repo):** + +```yaml +# .openspec/context.yaml +repositories: + - name: backend + path: ../backend + relevant_paths: + - src/api/** + - src/domain/** + - src/infrastructure/** + ignore_paths: + - src/api/__tests__/** + + - name: frontend + path: ../frontend + relevant_paths: + - src/components/** + - src/services/** + + - name: specs-store + path: ../wealth-ledger-specs + relevant_paths: + - openspec/specs/** + - openspec/changes/** +``` + +**Интеграция в schema.yaml:** + +```yaml +apply: + requires: [tasks] + tracks: tasks.md + context_source: .openspec/context.yaml + instruction: | + Read context files according to context.yaml mapping. + Prioritize files matching relevant_paths of affected repositories. +``` + +**Польза:** AI-агент знает, какие файлы читать, а не сканирует всё подряд. Экономия токенов и точность контекста. + +--- + +### 4.9. Добавить convention для commit messages + +При архивации change в specs-store и реализации в code repos полезна связь через commit messages. + +**Convention:** + +``` +[openspec:] : + +Refs: specs//proposal.md +``` + +Примеры: +``` +[openspec:wl-42] feat: add CSV export for user data + +Refs: specs/wl-42/proposal.md +``` + +``` +[openspec:wl-42] spec: update export format requirements + +Refs: specs/wl-42/specs/data-export/spec.md +``` + +**Польза:** Git history связывает код с specs. При `git blame` можно найти обоснование изменения. + +--- + +## 5. Итоговая таблица оценок + +| Критерий | Оценка | Комментарий | +|----------|--------|-------------| +| **Разделение concerns** | A | Отлично, 4 фазы с чёткими границами | +| **Проверяемость specs** | A | WHEN/THEN, SHALL/MUST, 4-level headers | +| **Защита от деградации** | B+ | Хорошие правила, но нет review gates | +| **Traceability** | C+ | Нет связи specs→tasks, нет completeness check | +| **Полнота workflow** | B | Нет DoD, rollback, cross-change deps | +| **AI-агент friendliness** | A | Чёткие prompts, парсимый формат, чёткие границы | +| **Интеграция с openspec** | A− | Хорошо, но store-aware пути требуют ручного контекста | +| **Multi-repo поддержка** | B | Есть store, но нет context mapping и cross-repo deps | +| **Эволюционность** | B+ | Delta-ops хороши, но нет dependency management | +| **Документированность** | A | Подробные instructions в schema.yaml | + +--- + +## 6. Топ-3 приоритета для доработки + +### 🥇 Приоритет 1: Добавить review gate между specs и design +**Почему:** Самый дешёвый способ предотвратить каскадные ошибки. Без него AI-агент может построить Design на неверных specs, и переделывать придётся всё. +**Сложность:** Низкая (новый template-файл + одна строка в schema.yaml) +**ROI:** Очень высокий + +### 🥈 Приоритет 2: Дополнить spec.md template примерами MODIFIED/REMOVED/RENAMED +**Почему:** Сейчас это «незаявленная функциональность» — AI-агент может генерировать неверный формат. При архивации в openspec это приведёт к потере деталей. +**Сложность:** Очень низкая (расширить template) +**ROI:** Высокий + +### 🥉 Приоритет 3: Добавить traceability (convention specs→tasks) +**Почему:** Гарантирует, что ни один requirement не потерян. Для pet-проекта — это главный способ держать качество без полноценного QA. +**Сложность:** Средняя (convention + опциональная автоматизация) +**ROI:** Высокий + +--- + +## 7. Заключение + +Схема **wealth-ledger-sdd** — это продуманный, прагматичный SDD-фреймворк, явно выросший из реальных потребностей multi-repo pet-проекта. Основные сильные стороны — разделение concerns, проверяемость specs и ориентация на AI-агента. + +Главные риски — отсутствие review gates и traceability — не критичны для pet-проекта, но станут болевыми точками при росте сложности или переходе к командной работе. Три предложенных приоритета (review gate, полный spec template, traceability) решают 80% рисков при минимальных затратах. + +Схема готова к использованию «как есть» и имеет чёткий путь эволюции. + +--- + +*Анализ подготовлен на основе файлов: schema.yaml, proposal.md, spec.md, design.md, tasks.md* diff --git a/audits/2026-08-26-wealth-ledger-sdd/qwen-result.md b/audits/2026-08-26-wealth-ledger-sdd/qwen-result.md new file mode 100644 index 0000000..740a6c5 --- /dev/null +++ b/audits/2026-08-26-wealth-ledger-sdd/qwen-result.md @@ -0,0 +1,118 @@ +# Анализ и оценка кастомной схемы OpenSpec SDD (`wealth-ledger-sdd`) + +## Общее резюме +Ваша кастомная схема `wealth-ledger-sdd` — это **великолепный, глубоко проработанный артефакт**. Видно, что вы прошли через реальные боли работы с AI-агентами в парадигме SDD (Spec-Driven Development) и решили их не на уровне "магии промптов", а на уровне строгой архитектуры и контрактов. + +Особенно впечатляет то, как вы учли специфику работы LLM: защита от галлюцинаций, предотвращение смешения слоев абстракции и жесткие требования к форматированию. + +**Общая оценка: 9.5 / 10** + +Вы создали **Enterprise-grade SDD фреймворк для AI-агентов**. То, как вы проработали edge-cases (форматирование хэшей, копирование блоков, разделение store и repo) — это уровень senior-архитектора, который уже "набил шишки" в продакшене. + +--- + +## 🌟 Сильные стороны (Что сделано блестяще) + +### 1. Защита от типичных галлюцинаций и ошибок LLM +* **Правило `#### Scenario`:** Вы явно указали, что сценарии должны использовать ровно 4 хэша, иначе валидация упадет. Это спасает от молчаливых ошибок парсинга. +* **Правило `MODIFIED Requirements`:** Требование копировать *весь* блок требования, а не переписывать его частично, решает огромную проблему LLM, которые любят "терять" контекст или сценарии при модификации. +* **Запрет на технологии в Proposal:** Жесткое ограничение "MUST NOT включать технологии... Эти решения появляются только после Delta Specs". Это не дает AI-агенту преждевременно скатиться в написание кода или выбор фреймворков. + +### 2. Идеальная трассируемость (Traceability) +Секция `Capabilities` в `proposal.md` — это **сердце вашей схемы**. Она создает жесткий контракт между "Зачем/Что" (Proposal) и "Как себя ведет" (Specs). AI не сможет написать спецификацию для фичи, которая не была заявлена в намерениях. + +### 3. Учет вашей архитектуры (Multi-repo + Store) +Инструкции в `specs` и `apply` явно оперируют понятием `` и каноническими путями. Это критически важно для вашего сценария с отдельным репозиторием под спеки и `openspec store`. Вы заранее решили проблему того, куда агент должен писать файлы, исключая путаницу между рабочими директориями. + +### 4. Разделение "Что" (Specs) и "Как" (Design) +* `specs` описывают только наблюдаемое поведение (контракт). +* `design` описывает архитектуру, Delivery Map и риски. + Это классический SDD, но реализованный так, что AI физически не может смешать их в одну кучу из-за разных шаблонов и инструкций. + +### 5. Верификация в `tasks.md` +Требование указывать `planned verification action` для каждой задачи — это киллер-фича. AI-агенты часто пишут задачи в стиле "Сделать Х", а потом не знают, как проверить, что Х сделано. Ваша схема заставляет его сразу думать о тестах или командах проверки. + +--- + +## ⚠️ Точки роста и потенциальные проблемы + +Несмотря на высочайшее качество, схема имеет несколько мест, которые могут стать "бутылочным горлышком" или избыточными в контексте пет-проектов. + +### 1. Избыточность (Over-engineering) для пет-проектов +В `design.md` есть секции: `Solution Assessment`, `Contract Gate Decision`, `Migration Plan`. +* **Проблема:** Для небольших фич в пет-проектах AI будет тратить огромное количество токенов, генерируя заглушки вроде "N/A, так как это не затрагивает API" или выдумывая несуществующие риски миграции. Это замедляет работу и засоряет контекст. + +### 2. Отсутствие явного цикла итераций (Feedback Loop) +Схема линейна: `proposal` → `specs` → `design` → `tasks` → `apply`. +* **Проблема:** Что если на этапе `design` архитектор (или AI) поймет, что требования из `specs` технически невозможны или слишком дороги? Или что если во время `apply` выяснится, что `specs` были неполными? + +### 3. Обработка блокеров в фазе `apply` +В `apply` написано: *"Pause if you hit blockers or need clarification."* +* **Проблема:** AI-агент может просто остановиться и вывести текст в консоль, но как вам (владельцу) отследить этот блокер? Как агент поймет, что он должен делать дальше? + +### 4. Токенозатратность инструкций +Инструкции в `schema.yaml` очень подробные. Это отлично для точности, но при передаче в системный промпт или контекст LLM они могут съедать тысячи токенов на каждый вызов. + +--- + +## 💡 Предложения по улучшению + +Ниже приведены конкретные правки, которые можно внести в `schema.yaml` и шаблоны, чтобы сделать схему еще более устойчивой и экономичной. + +### 1. Сделайте энтерпрайз-секции в `design.md` условными +Чтобы AI не тратил токены на отписки, добавьте в `instruction` для `design` следующее правило: + +```text +Include `Solution Assessment` ONLY if the change introduces auth, storage, +or external integrations. Include `Migration Plan` ONLY if it breaks backward +compatibility. Include `Contract Gate Decision` ONLY if both API contract +sides change. Otherwise, omit these sections entirely or mark them as N/A +with a single word reason to save context. +``` + +### 2. Введите механизм артефактов для блокеров и ревизий +Добавьте в `apply` и `design` правила создания явных артефактов вместо простого "паузы": + +```text +In `apply`: If blocked, DO NOT guess or just pause. Create a `blocker.md` +in the change directory detailing the exact error, the task that failed, +and proposed solutions. Then halt execution. + +In `design` or `apply`: If a spec-level behavior change is required because +the original specs were technically impossible or incomplete, STOP. Generate +a `revision-request.md` explaining why specs must change, and pause for +owner approval before modifying specs. +``` + +### 3. Уточните правила тестирования в `tasks.md` +Вы написали: "Автоматические тесты обязательны для security/privacy...". Сделайте это правило более предсказуемым для AI: + +```text +If a task modifies existing logic, it MUST include a regression test. +If it adds new logic, it MUST include a happy-path test. +Do not write tests for DTOs without logic, declarative structures, +or thin adapters unless they contain branching or transformation. +``` + +### 4. Добавьте "Definition of Done" для фазы `apply` +Чтобы агент четко понимал, когда он закончил работу, добавьте в конец `instruction` для `apply`: + +```text +The `apply` phase is complete ONLY when all tasks in `tasks.md` are marked +`[x]`, all planned verification actions have passed, and a brief +`Completion Summary` (listing executed verifications and final state) +is appended to the bottom of `tasks.md`. +``` + +### 5. Оптимизация токенов (Advanced) +Если вы используете это через API, попробуйте вынести общие правила (например, "никогда не пиши код в specs", "используй SHALL/MUST") в отдельный базовый системный промпт (System Prompt), а в `schema.yaml` оставьте только уникальные для каждого артефакта дельты и специфичные правила форматирования. + +--- + +## Заключение + +Ваш подход с выделенным репозиторием под спеки и `openspec store` в связке с этой кастомной схемой — это **передовой край (bleeding edge)** использования AI для разработки. + +Единственное, за чем нужно следить по мере развития пет-проектов — это **баланс между строгостью и оверхедом**. Если вы заметите, что AI-агент начинает "уставать" (генерировать отписки в `N/A` секциях или терять нить из-за объема контекста), просто примените советы из раздела "Предложения по улучшению", чтобы сделать схему более гибкой. + +Отличная работа! diff --git a/audits/2026-08-26-wealth-ledger-sdd/zai-result.md b/audits/2026-08-26-wealth-ledger-sdd/zai-result.md new file mode 100644 index 0000000..c1846e2 --- /dev/null +++ b/audits/2026-08-26-wealth-ledger-sdd/zai-result.md @@ -0,0 +1,85 @@ +# Анализ SDD-схемы WealthLedger (OpenSpec) + +## Общая оценка + +Схема представляет собой **зрелый, продакшн-готовный пайплайн** управления AI-ассистентом. Конфигурация решает главную проблему применения LLM в разработке — преждевременное погружение в имплементацию и галлюцинации. Выстроен идеальный конвейер: от бизнес-намерения (Proposal) через поведенческий контракт (Specs) к архитектуре (Design) и чеклисту (Tasks), с жесткой защитой границ каждого этапа. + +--- + +## Сильные стороны (Уровень "A+") + +### 1. Защита от смешивания уровней (Level Slippage) +Директивы вида `MUST NOT включать технологии...` в Proposal и `Не включай в specs: Internal class/function names` — золотой стандарт промпт-инжиниринга для SDD. LLM обожают смешивать *Why*, *What* и *How*. В данной схеме уровни изолированы максимально жестко. + +### 2. Глубокое понимание квирков OpenSpec +Конфигурация написана человеком, который реально дебажил поведение агента с фреймворком: +- Требование ровно 4 решеток (`####`) для сценариев (критично для парсинга). +- Грамотная работа с `planningHome.root` вместо хардкода путей (правильный подход для работы со store). +- Разделение логики для `## Purpose` (добавляется только для новых capability, запрещается для дельт). +- Корректная обработка флага `skip_specs: true`. + +### 3. Эвристика "Solution Assessment" +Ограничение триггеров для создания раздела (auth, security, storage, observability и т.д.) — отличное архитектурное решение. Оно не дает ИИ писать бесполезные простыни текста для тривиальных фич, но принуждает к глубокому анализу там, где цена ошибки высока. + +### 4. Анти-галлюцинации в фазе Apply +Правило `MUST NOT записывать ещё не наблюдённые результаты как выполненные` спасает от классической ошибки агентов, когда они ставят галочку `- [x]` и пишут "Created file X", хотя файла еще нет в файловой системе. + +--- + +## Потенциальные риски и узкие места + +### 1. Переполнение контекста (Context Window Bleed) +Инструкции к артефактам `specs` и `design` очень объемны и содержат много edge-cases. При сложной фиче ИИ будет удерживать в контексте исходники репозиториев, Proposal и эти инструкции. Есть риск, что в конце генерации он "забудет" форматирование (например, начнет использовать `###` вместо `####` для сценариев). + +### 2. Неявная мультирепозиторность в Tasks +Агент запускается из папки с несколькими репозиториями, однако в инструкциях к `tasks.md` нет требования указывать целевой репозиторий. ИИ может сгенерировать таск "Создать модель User", не уточнив, идет ли это в `wealth-ledger-api`, `wealth-ledger-shared` или фронтенд. + +### 3. Отсутствие механических стоп-кадров (Human-in-the-loop) +Текстом заявлено: *"Design формируется только после явного owner approval Delta Specs"*. Но в YAML-схеме нет жесткого триггера остановки. В agentic-цикле ИИ может проинтерпретировать это как "я сам одобряю и иду дальше", нарушив весь смысл воркфлоу. + +--- + +## Предложения по улучшению + +### 1. Добавить принудительный префикс репозитория в Tasks +Для устранения неоднозначности в мультирепо-структуре, дополните инструкцию для `tasks`: + +```yaml +task_repo_rule: | + Для каждой задачи указывай целевой репозиторий в квадратных скобках в начале: + `- [ ] 1.1 [repo: wealth-ledger-api] Создать эндпоинт... и верифицировать...` + Если задача затрагивает несколько репо, разбей её на подзадачи. + Запрещено оставлять таски без указания репозитория. +``` + +2. Внедрить явные "Стоп-кадры" между фазами + Добавьте блок остановки в конец инструкций артефактов proposal, specs и design, чтобы принудительно разорвать агентный цикл: + +```yaml +stop_condition: | + STOP_PROTOCOL: После генерации этого артефакта НЕМЕДЛЕННО ОСТАНОВИСЬ. + Не продолжай генерацию следующих артефактов. + Выведи ровно одну строку: "[ARTIFACT_ID] готов. Ожидаю approve/reject." + Возобновление работы возможно только после явного ответа пользователя. +``` +3. Упростить инструкцию про planningHome.root + Текущее описание резолвинга путей занимает 4 предложения. LLM лучше справляются с короткими императивами, чем с логическими объяснениями "почему так". Рекомендуется сократить в specs: + +```yaml +root_path_instruction: | + Используй ТОЛЬКО абсолютный путь из поля planningHome.root + (полученный из ответа `openspec instructions --json`) для чтения существующих спецификаций. + Никогда не используй относительные пути вида `./openspec/specs/` для чтения. +``` +4. Добавить обработку ошибок валидации в apply + В текущем блоке apply указано "Сначала проверь exact OpenSpec version contract", но не прописано поведение при ошибке валидации (которая часто бывает из-за кривого markdown от ИИ). Расширьте apply: + +```yaml +apply_error_handling: | + Если при выполнении `openspec validate` возникает ошибка: + 1. Внимательно прочитай текст ошибки (обычно это неверное количество # или отсутствующий Purpose). + 2. Автоматически исправь сгенерированные файлы согласно ошибке. + 3. Запусти валидацию повторно. + НЕ проси пользователя исправлять технические ошибки формата OpenSpec вручную. +``` +Итог: Доработав эти 4 аспекта (особенно пункты 1 и 2), вы получите эталонный, полностью автономный и безопасный SDD-движок для разработки через AI. diff --git a/audits/README.md b/audits/README.md index e381e91..47848e5 100644 --- a/audits/README.md +++ b/audits/README.md @@ -7,3 +7,4 @@ - [Аудит 13.08.2026](audit-13-08-2026.md) - [Аудит 20.08.2026](audit-20-08-2026.md) - [Аудит 24.08.2026](audit-24-08-2026.md) +- [Multi-source assessment WealthLedger SDD 26.08.2026](2026-08-26-wealth-ledger-sdd/README.md) diff --git a/development/audit-remediation.md b/development/audit-remediation.md index 641612e..4e5cad4 100644 --- a/development/audit-remediation.md +++ b/development/audit-remediation.md @@ -7,6 +7,12 @@ ## Правила работы - Каждая audit-derived запись имеет один статус: `planned`, `active`, `done`, `deferred` или `accepted`. +- Каждое уникальное external claim дополнительно имеет независимый triage + disposition: `confirmed`, `already-covered`, `rejected` или `deferred`. + Повтор одного underlying claim в нескольких reports получает один Audit ID со + ссылкой на каждый source. Disposition не является remediation status: + `confirmed` ещё может быть active, а `rejected` — accepted как проверенное + решение ничего не внедрять. - Одновременно допускается не более одного `active` remediation change. Пока он существует, продолжается только он. При наличии `planned` ровно одна запись отмечается следующей рекомендуемой задачей, но она не запускается параллельно active change. - `done` требует даты, archive path OpenSpec change, commit для каждого затронутого Git-репозитория и точных non-mutating verification commands с observed results. - `deferred` и `accepted` требуют даты, rationale и review trigger либо ссылки на явное решение владельца. @@ -16,18 +22,68 @@ - Bootstrap change: [`2026-08-23-establish-audit-remediation-workflow`](../../specs/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/) — `archived`; это process foundation и не закрывает ни одного Audit ID. - Последний завершённый audit remediation change: [`2026-08-24-harden-agent-sdd-governance`](../../specs/openspec/changes/archive/2026-08-24-harden-agent-sdd-governance/) — `archived`; AUD24-01 и AUD24-03–AUD24-09, а также A-14–A-16 и A-18 закрыты. -- Единственный active change: отсутствует. +- Единственный active change: [`harden-openspec-sdd-quality`](../../specs/openspec/changes/harden-openspec-sdd-quality/) для SDD26-01–SDD26-03, SDD26-09, SDD26-12, SDD26-17, SDD26-21 и SDD26-28–SDD26-30. ## Текущая задача -Создать `assess-auth-platform-options` для AUD24-02. +Завершить `harden-openspec-sdd-quality` без параллельного remediation change. ## Следующая рекомендуемая задача -`assess-auth-platform-options` для AUD24-02. Change применяет Solution Assessment к существующей реализации и зрелым auth platforms, включая Better Auth, и не предрешает миграцию. +После terminal completion текущего active change вернуть +`assess-auth-platform-options` для AUD24-02. Change применяет Solution +Assessment к существующей реализации и зрелым auth platforms, включая Better +Auth, и не предрешает миграцию. ## Реестр findings +### Multi-source assessment WealthLedger SDD 26.08.2026 + +Raw external reports и checksums находятся в +[immutable snapshot set](../audits/2026-08-26-wealth-ledger-sdd/README.md). +Сокращения источников: [D] — DeepSeek, [G] — Gemini, [K] — Kimi, [Q] — Qwen, +[Z] — Z.AI. Ни одна внешняя рекомендация сама по себе не является project +authority. + +| Audit ID | Нормализованный claim | Sources | Disposition | Remediation status | Evidence, rationale или review trigger | +| --- | --- | --- | --- | --- | --- | +| SDD26-01 | Снизить instruction bloat и устранить конкурирующих владельцев общих правил. | [D], [G], [Q], [Z] | confirmed | active | [`harden-openspec-sdd-quality`](../../specs/openspec/changes/harden-openspec-sdd-quality/): schema v2 владеет semantics, templates — shape, config — только facts/language, scripts — hard invariants; отдельный `_rules.md` не вводится. | +| SDD26-02 | Проверять planning format машинно до approval и автоматически исправлять технические ошибки. | [D], [Z] | confirmed | active | Текущий change поставляет stage-aware non-mutating verifier, controlled-invalid fixtures и format-only retry path. | +| SDD26-03 | Каждая task должна иметь однозначную delivery area; multi-repo implementation нужно разделять. | [D], [G], [Z] | confirmed | active | Schema v2 использует `[frontend\|backend\|specs\|docs\|workspace]`; planning verifier отклоняет owner из `N/A` area. | +| SDD26-04 | Добавить `Target Repositories` уже в Proposal. | [G] | rejected | accepted | 2026-08-26; Proposal остаётся owner-readable intent без implementation topology. Полный scope repositories определяется позже через обязательную Design Delivery Map. | +| SDD26-05 | Явно координировать порядок и совместимость multi-repository delivery. | [D], [G] | already-covered | accepted | 2026-08-26; Delivery Map, Contract Gate Decision, Migration Plan и workspace dispatcher уже задают owners, порядок, совместимость API и canonical gates. | +| SDD26-06 | Формализовать trigger для Solution Assessment. | [D] | already-covered | accepted | 2026-08-26; [engineering governance](engineering-governance.md#build-versus-buy) и schema перечисляют auth, security, storage, integrations, observability, caching, concurrency и shared tooling. | +| SDD26-07 | Не допускать Design/Apply по неутверждённым artifacts. | [D], [K], [Z] | already-covered | accepted | 2026-08-26; human approval хранится в разговоре, one-artifact entrypoints останавливаются, downstream approvals каскадно инвалидируются. Фиктивный `approval.md` или status field не создаётся. | +| SDD26-08 | Разрешить partial/diff `MODIFIED` вместо полного requirement block. | [D] | rejected | accepted | 2026-08-26; native OpenSpec archive semantics требуют полного `MODIFIED`; собственный merge format создал бы второй transformation engine и риск потери scenarios. | +| SDD26-09 | Дать компактные примеры сложных delta operations. | [D], [K] | confirmed | active | Schema v2 добавляет `MODIFIED`, `REMOVED` и `RENAMED` examples, сохраняя minimal ADDED-first template. | +| SDD26-10 | Генерировать в `spec.md` placeholders всех delta sections. | [K] | rejected | accepted | 2026-08-26; пустые sections повышают шум и риск неверной операции. Complex forms принадлежат instructions/examples, а template остаётся минимальным. | +| SDD26-11 | Явно определить DoD, verification и archive после Apply. | [D], [K], [Q] | already-covered | accepted | 2026-08-26; [engineering governance](engineering-governance.md#verify-archive-и-completion-evidence), workspace dispatcher, semantic verification, independent review и hard archive blockers уже образуют terminal protocol. Completion Evidence создаётся после факта, не в Tasks. | +| SDD26-12 | Связать каждую task с точными Delta Requirements и отклонять uncovered requirements. | [D], [K] | confirmed | active | Schema v2 использует native identity `capability path — exact Requirement heading`; planning verifier проверяет ссылки и полное покрытие без собственного ID namespace. | +| SDD26-13 | Добавить Fast Track или сокращённую вторую schema для мелких fixes. | [G] | rejected | accepted | 2026-08-26; один lifecycle сохраняет предсказуемые approvals и archive blockers. Пропорциональность обеспечивают `skip_specs`, conditional assessment/rollback и узкие tasks. | +| SDD26-14 | Ограничивать agent context через tool-specific `.aiignore` и список repos из Proposal. | [G] | rejected | accepted | 2026-08-26; это не portable OpenSpec invariant. Context ограничивается Delivery Map, task owner и targeted reads; dependencies/build outputs уже исключаются локальными tool/repository rules. Пересмотреть при наблюдаемом context exhaustion. | +| SDD26-15 | Ввести общий `blocked_by`/`blocks` graph между changes. | [K] | deferred | deferred | Review trigger: первый реальный случай двух одновременно необходимых changes с доказанной ordering dependency, которую нельзя выразить текущим single-active-remediation rule. | +| SDD26-16 | Добавить priority и sizing в Tasks. | [K] | rejected | accepted | 2026-08-26; Tasks уже dependency-ordered и ограничены одной рабочей сессией. Оценочные points не защищают observable invariant и создают неподтверждённую точность. | +| SDD26-17 | Для труднообратимых changes нужен проверяемый rollback contract. | [K] | confirmed | active | Design template и planning verifier требуют trigger/actions/data safety/verification для risk cases либо конкретный `N/A` reason. | +| SDD26-18 | Добавить отдельный multi-repo context mapping file. | [K] | already-covered | accepted | 2026-08-26; native `openspec instructions ... --json` уже возвращает `planningHome`, `contextFiles`, `artifactPaths` и config context. Второй context map дублировал бы CLI state. | +| SDD26-19 | Зафиксировать commit-message convention в schema. | [K] | rejected | accepted | 2026-08-26; commit style не меняет artifact correctness и принадлежит repository delivery policy только при появлении отдельного проверяемого требования. | +| SDD26-20 | Сделать enterprise sections условными, чтобы снизить overhead. | [Q] | already-covered | accepted | 2026-08-26; Solution Assessment уже conditional, rollback допускает содержательный `N/A`; Delivery Map и Contract Gate Decision остаются обязательными, потому что защищают multi-repo scope. | +| SDD26-21 | Добавить явный feedback loop из Design/Apply в ранний затронутый artifact. | [Q] | confirmed | active | Schema v2 и agent entrypoints маршрутизируют intent→Proposal, behavior→Specs, architecture/rollback→Design, decomposition→Tasks и инвалидируют downstream approvals. | +| SDD26-22 | Создавать `blocker.md` и `revision-request.md` при каждом blocker/revision. | [Q] | rejected | accepted | 2026-08-26; новые workflow artifacts не поддерживаются native schema и быстро устаревают. Наблюдаемое основание сообщается Change Owner в разговоре; durable artifact добавится только при реальном повторяемом trigger. | +| SDD26-23 | Требовать regression test для любой изменённой логики и happy-path test для любой новой. | [Q] | already-covered | accepted | 2026-08-26; [risk-based testing](engineering-governance.md#risk-based-testing) требует tests для существенных рисков и regressions, но осознанно отклоняет универсальные малоценные tests ради каждого logic/file change. | +| SDD26-24 | Добавлять Completion Summary в конец Tasks. | [Q] | rejected | accepted | 2026-08-26; Tasks содержат только planned work. Observed results и commits появляются после выполнения в verification/archive evidence, иначе checklist смешивает план и факты. | +| SDD26-25 | Требовать точный текстовый `STOP_PROTOCOL` после каждого artifact. | [Z] | rejected | accepted | 2026-08-26; обязательная остановка и явный approval уже enforced entrypoints. Фиксация одной строки ответа хрупка и не усиливает identity или semantic approval. | +| SDD26-26 | Сократить explanation `planningHome.root` до короткого imperative. | [Z] | rejected | accepted | 2026-08-26; пояснение предотвращает ошибочное вычисление path при store-backed и local modes OpenSpec 1.10. После удаления duplicate config rules instruction source остаётся приемлемым; пересмотреть при измеренном context regression. | +| SDD26-27 | Добавить дополнительные contract gates вроде `internal-proto`. | [G] | deferred | deferred | Review trigger: появление второго реального межсервисного committed contract, для которого `runtime-openapi` и repository gates недостаточны. До этого generic gate будет speculative. | +| SDD26-28 | Root project-owned agent projection должна восстанавливаться из versioned authority. | local triage | confirmed | active | Обнаружено локально: root `.opencode` не принадлежит Git repository. Текущий change добавляет canonical source, atomic sync и exact drift verifier в `specs`. | +| SDD26-29 | Exact OpenSpec version должна быть единым compatibility contract, а не вечным literal в scripts/fixtures. | local triage | confirmed | active | `.cli-version` остаётся единственным current contract; markers/verifiers выводят expected value из него, новая stable не включает auto-upgrade. | +| SDD26-30 | Raw multi-source evidence и triage должны быть versioned раздельно. | local triage | confirmed | active | Пять reports сохранены byte-for-byte в [snapshot set](../audits/2026-08-26-wealth-ledger-sdd/README.md); этот live registry хранит dispositions и statuses отдельно. | + +[D]: ../audits/2026-08-26-wealth-ledger-sdd/deepseek-result.md +[G]: ../audits/2026-08-26-wealth-ledger-sdd/gemini-result.md +[K]: ../audits/2026-08-26-wealth-ledger-sdd/kimi-result.md +[Q]: ../audits/2026-08-26-wealth-ledger-sdd/qwen-result.md +[Z]: ../audits/2026-08-26-wealth-ledger-sdd/zai-result.md + ### Аудит 13.08.2026 | Audit ID | Текущий статус | Связь и следующее действие | Terminal evidence или trigger | diff --git a/development/engineering-governance.md b/development/engineering-governance.md index 0bfb288..14ee7e7 100644 --- a/development/engineering-governance.md +++ b/development/engineering-governance.md @@ -14,6 +14,10 @@ **Enforceable Engineering Invariant** — обязательное правило с детерминированной non-mutating локальной проверкой, нарушение которой блокирует завершение change. Непроверяемое предпочтение является guidance, а не hard guardrail. +**Planning structural gate** — stage-aware проверка доступной формы и ссылочной +целостности текущего planning artifact до запроса approval. Она не оценивает +качество rationale и не является semantic approval. + ## Последовательность SDD Каждый versioned change проходит один граф: @@ -25,10 +29,21 @@ Proposal → Delta Specs → Design → Tasks → Apply → Verify → Archive - Proposal формулирует намерение, границы и ожидаемый результат без технологий, API, файлов и зависимостей. - Delta Specs описывают изменение наблюдаемого поведения и инвариантов без изменений кода. - Design объясняет архитектурный способ реализации крупными частями, риски и альтернативы; он не является построчной инструкцией. -- Tasks — implementation checklist, достаточный для выполнения Design и Specs. Он содержит планируемые проверки, но не будущие результаты, commits или post-archive bookkeeping. +- Tasks — implementation checklist, достаточный для выполнения Design и Specs. + Каждый checkbox объявляет ровно одну area, `Covers` ссылается на native + identity `capability path — exact Requirement heading` либо объясняет `N/A`, + а `Verification` задаёт планируемую проверку. Tasks не содержат будущие + результаты, commits или post-archive bookkeeping. AI-агент готовит только текущий разрешённый артефакт, показывает его Change Owner и останавливается. Downstream artifact создаётся только после явного approval. Если новая сессия не может подтвердить approval из доступного контекста, агент запрашивает его повторно. +До запроса approval агент запускает доступный stage planning gate и сам +исправляет технические ошибки формата. Полный change validation не объявляется +успешным, пока downstream artifacts отсутствуют. Форматное исправление без +изменения intent, behavior, decisions или task scope не требует reapproval; +семантическое изменение возвращает workflow к самому раннему затронутому +artifact. + Изменение принятого upstream artifact инвалидирует approval зависимых артефактов: Proposal — Specs, Design и Tasks; Specs — Design и Tasks; Design — Tasks. Tasks не могут неявно расширять scope или менять поведение и архитектуру: работа возвращается к соответствующему upstream artifact. ## Delivery Map и multi-repository delivery @@ -42,6 +57,12 @@ Design каждого change оценивает все четыре област Change остаётся active, пока каждая affected область не реализована и не прошла свой canonical gate. Design содержит Contract Gate Decision: `runtime-openapi` имеет статус `required`, когда изменение затрагивает frontend и backend стороны API contract, иначе `N/A` с конкретной причиной. Успех одного репозитория не компенсирует отсутствие или failure другого. +Task owner выбирается только из `frontend`, `backend`, `specs`, `docs` и +`workspace`. Repository owner нельзя использовать для area со статусом `N/A`; +cross-repository implementation разбивается на отдельные tasks. `workspace` +владеет только orchestration и verification, но не подменяет repository-owned +implementation или canonical gates. + ## Risk-based testing Автоматизированный тест обязателен, когда изменение затрагивает хотя бы один существенный риск: @@ -75,6 +96,17 @@ Solution Assessment сравнивает применимые варианты Собственная реализация допустима, только если подходящего решения нет или доказана существенная несовместимость. Тогда Design фиксирует проверенные варианты, конкретные gaps, принятые риски и trigger повторного рассмотрения. Для обратимого изменения вне перечисленных областей отдельная формальная оценка не создаётся ради процесса. +## Rollback contract + +Design фиксирует status `required`, trigger, actions, data safety и verification, +если change меняет auth/security behavior, data integrity или migration, public +contract либо другое существенно труднообратимое решение. Contract учитывает +данные и compatibility, созданные после delivery, и не может зависеть от нового +неутверждённого архитектурного решения. + +Для обратимого change вне этих рисков status `N/A` содержит конкретную причину. +Отдельный rollback artifact не создаётся ради процесса. + ## Single Source of Truth | Вид знания | Authoritative location | @@ -85,6 +117,7 @@ Solution Assessment сравнивает применимые варианты | Текущее устройство и поставленные возможности | `docs/architecture` и `docs/features` | | Устойчивые архитектурные решения и причины | `docs/adr` | | Инженерная policy и completion evidence | `docs/development` | +| Canonical source project-owned agent commands и skills | `specs/agent-projection/opencode` | | Компактная маршрутизация AI-агентов | root и repository-local `AGENTS.md` | `docs` описывает только фактическое текущее состояние и не пересказывает Proposal, Delta Specs, Design или Tasks другим форматом. `AGENTS.md` не копирует архитектуру или feature documentation: он направляет к authority и перечисляет только применимые hard constraints и canonical commands. @@ -104,6 +137,17 @@ CI пока отсутствует, поэтому обязательные gate Hard guardrail должен иметь исполняемую локальную проверку. Правило без надёжной проверки помечается как guidance и учитывается в review, но не выдаётся за автоматический запрет. Новые frameworks, checkers и thresholds добавляются только после оценки поддерживаемого решения, maintenance cost и реально защищаемого риска. +Root `.opencode/commands` и `.opencode/skills` являются derived projection. +Изменения вносятся в versioned source под `specs`, распространяются explicit +atomic sync и проверяются exact file/content comparison; package manifests, +dependencies и machine-local state не являются authority inputs. + +Текущая exact OpenSpec CLI version читается только из +`specs/openspec/.cli-version`. Новая stable release не меняет contract +автоматически. Upgrade выполняется отдельным SDD change после isolated проверки +schema, agent projection, canonical store и positive/negative fixtures; +историческое evidence сохраняет фактическую прежнюю version. + ## Verify, archive и Completion Evidence Structural validation OpenSpec проверяет schema и форму артефактов, но не соответствие реализации. До archive обязательны: diff --git a/development/openspec-authority-and-lifecycle.md b/development/openspec-authority-and-lifecycle.md index 732aa86..a11a255 100644 --- a/development/openspec-authority-and-lifecycle.md +++ b/development/openspec-authority-and-lifecycle.md @@ -19,10 +19,15 @@ bash specs/scripts/verify-openspec-version.sh ``` Несовпадение version блокирует операцию до чтения или изменения store. +Публикация новой stable версии не меняет этот contract автоматически. Upgrade +выполняется отдельным SDD change после staged проверки schema, instructions, +project-owned projection, store resolution и hard blockers; historical archives +не переписываются. ## Project-local schema -Новые changes по умолчанию используют schema `wealth-ledger-sdd` из `specs/openspec/schemas/wealth-ledger-sdd`. Её граф: +Новые changes по умолчанию используют schema `wealth-ledger-sdd` version 2 из +`specs/openspec/schemas/wealth-ledger-sdd`. Её граф: ```text proposal → specs → design → tasks → apply @@ -30,6 +35,18 @@ proposal → specs → design → tasks → apply OpenSpec обеспечивает structural order, а явное решение Change Owner — переход между артефактами. Agent создаёт один текущий artifact и останавливается для approval. Роли артефактов и cascade rules определены в governance policy; исполняемые templates и instructions принадлежат schema. +До запроса approval выполняется доступная stage-aware проверка: + +```bash +bash specs/scripts/verify-openspec-planning.sh +``` + +Proposal проверяется без ложного объявления полного change success; по мере +появления Specs, Design и Tasks добавляются strict validation, Delivery Map, +rollback, area ownership и exact Requirement coverage. Технический format +failure исправляется и проверяется повторно; structural success не означает +approval. + Project-local schema проверяется из `specs`: ```bash @@ -41,9 +58,30 @@ openspec schema which wealth-ledger-sdd --json ## Agent entrypoints и обновление OpenSpec -Root `.opencode` — generated local projection OpenSpec 1.10 с минимальными WealthLedger overlays: fixed store, one-artifact-at-a-time и hard archive blockers. Она не является SSOT, потому что workspace root не versioned. +Canonical source WealthLedger-owned OpenCode commands и skills находится в +`specs/agent-projection/opencode`. Root `.opencode/commands` и +`.opencode/skills` — derived local projection с минимальными overlays: fixed +store, one-artifact-at-a-time, stage planning gate, Apply feedback routing и +hard archive blockers. Package manifests, installed dependencies и machine-local +state не входят в source. -`openspec update` не запускается напрямую из workspace root. Новую upstream version сначала генерируют в isolated staging, сравнивают с projection, переносят upstream delta и повторно накладывают project overlays. После этого обязательно выполняют authority fixtures; permissive archive, conditional store selection и второй `openspec` root считаются failures. +Projection восстанавливается и проверяется из workspace root: + +```bash +bash specs/scripts/sync-agent-projection.sh +bash specs/scripts/verify-agent-projection.sh +``` + +Sync выполняет verified cutover и восстанавливает прежнее local state при +ошибке. Verifier non-mutating сравнивает required file set и contents и получает +expected `generatedBy` marker из `.cli-version`. + +`openspec update` не запускается напрямую из workspace root. Новую upstream +version сначала генерируют в isolated staging, сравнивают с canonical source, +переносят upstream delta и повторно накладывают минимальные project overlays. +После этого sync обновляет derived root, а authority fixtures проверяют marker, +missing/content drift, permissive archive, conditional store selection и второй +`openspec` root как failures. ## Реализация и проверка change @@ -55,10 +93,16 @@ bash specs/scripts/verify-workspace-change.sh `specs` проверяется всегда. Dispatcher читает явный Contract Gate Decision из Design и сравнивает backend runtime OpenAPI с committed frontend snapshot только при `runtime-openapi: required`; этот status допустим лишь при affected frontend и backend. Child failure блокирует общий результат; fallback и auto-fix отсутствуют. +Перед affected-area gates dispatcher повторяет planning verifier. Tasks имеют +формат `X.Y [area] action` и indented `Covers`/`Verification`; каждый Delta +Requirement покрывается точной ссылкой хотя бы один раз, а `workspace` остаётся +только owner orchestration/verification. + Перед archive отдельно подтверждаются structural и semantic gates: ```bash bash specs/scripts/verify-openspec-authority.sh +bash specs/scripts/verify-agent-projection.sh openspec validate --type change --strict --store wealth-ledger-specs openspec validate --specs --strict --store wealth-ledger-specs ``` diff --git a/package.json b/package.json index 1ce937c..8ecb37d 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,7 @@ }, "scripts": { "runtime:check": "node scripts/verify-node-version.mjs", - "lint": "markdownlint-cli2 \"**/*.md\" \"#node_modules\"", + "lint": "markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#audits/2026-08-26-wealth-ledger-sdd/*-result.md\"", "verify": "npm run runtime:check && npm run lint && git diff --check" }, "devDependencies": {