spec: add requirement-writing profile to sdd-lab (WealthLedger/specs#66)

2026-10-30 13:34:19 +03:00
parent d5a0e942a3
commit 4c13b1863f
7 changed files with 320 additions and 38 deletions
@@ -118,6 +118,13 @@ artifacts:
      Шаблоны: HTML-комментарии в шаблонах — подсказки для автора. В готовом артефакте их
      нет; удаляй до gate этого артефакта.

+      Качество требований: единый профиль для автора и reviewer —
+      `openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md`. До утверждения Specs
+      автор проходит нормоконтроль и смысловую проверку набора из раздела Review;
+      назначенный по режиму reviewer перепроверяет их на существующем G2/G3.
+      Результат — в Validation и Findings Gate Log. Вопрос, меняющий норму или ожидаемый
+      результат, блокирует gate; предпочтение стиля само по себе не блокирует.
+
      Change Profile (обязательная таблица, все 10 строк):
      - `yes` — только при конкретном trigger из instruction артефакта; в lab допустим
        `yes` с названной практикой («lab: практика data mapping»).
@@ -196,6 +203,9 @@ artifacts:
        approved содержит дословную цитату и непустую Validation.
      - [ ] Specs: нет дублей `### Requirement:` в одном файле; MODIFIED/REMOVED/RENAMED
        FROM ссылаются на существующий canonical heading.
+      - [ ] Для предъявляемых на gate Specs пройдены оба прохода Review из
+        spec-writing.md: качество требований и полнота/согласованность итогового набора;
+        нет нерешённых вопросов о нормативном поведении.
      - [ ] test-cases: ids `TC-` уникальны, у каждого case есть Verifies в формате ссылки.
      - [ ] Каждый файл `analysis/contracts/` и `analysis/diagrams/` упомянут в
        `analysis/*.md`; JSON/YAML-контракты синтаксически валидны.
@@ -220,10 +230,11 @@ artifacts:

      Independent Review (lab — на каждом gate; delivery — минимум G4):
      - G1: product-analyst ищет в проблеме и scope противоречия и скрытые решения.
-      - G2: qa-engineer — тестируемость; independent-reviewer — противоречия с canonical
-        specs и пропущенные error/boundary случаи.
+      - G2: qa-engineer — тестируемость; independent-reviewer — оба прохода Review из
+        spec-writing.md для delta и итогового набора с canonical specs.
      - G3: independent-reviewer — согласованность specs ↔ analysis ↔ design ↔
-        qa-analysis ↔ tasks; security-reviewer, если выбран security-analysis.
+        qa-analysis ↔ tasks; без G2 также профиль Specs; security-reviewer, если выбран
+        security-analysis.
      - G4: independent-reviewer — код против утверждённых артефактов; qa-engineer —
        системная проверка по qa-analysis.
      - Reviewer не исправляет артефакт; findings идут по правилам обратной связи.
@@ -262,15 +273,27 @@ artifacts:
      - G1 approved; используются только capabilities из Proposal.
      - Для существующей capability прочитай canonical spec целиком.
      - `skip_specs: true` — spec-файлы не создаются.
+      - Прочитай `openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md`: это единый
+        профиль написания и ревью, включая эталоны, а не необязательные советы.

      Правила:
-      - Один Requirement = одно устойчивое observable behavior или инвариант.
-      - BCP 14 по политике `config.yaml`: uppercase SHALL/MUST — только для обязательств.
-      - У каждого Requirement ≥1 `#### Scenario:` с конкретными WHEN/THEN.
+      - Путь дельты — `specs/<capability-path>/spec.md`, capability-path точно из Proposal.
+      - Один Requirement = одно независимо принимаемое наблюдаемое обязательство или
+        инвариант. Единый атомарный результат не дроби по числу SHALL.
+      - Новая норма: субъект + SHALL / SHALL NOT + результат с явным условием, если оно
+        нужно. MUST / MUST NOT равнозначны; BCP 14 — по политике `config.yaml`.
+      - Общая норма, нужные определения/таблицы, затем ≥1 `#### Scenario:` для
+        ADDED/MODIFIED: GIVEN по необходимости, конкретные WHEN/THEN. Scenario не
+        создаёт новую норму. Существующие headings и сохраняемые Scenarios не теряй.
+      - Термины бери из затронутых specs и предоставленного глоссария; новое определение
+        размещай внутри владеющего Requirement, а не только в исследовании или примере.
      - Бизнес-правила, инварианты (сохранение суммы, однократный учёт денег, знак и
-        точка округления) и граничные случаи — явные Requirements/Scenarios.
+        точка округления), единицы и существенные границы — явные нормы и Scenarios.
+        Для ветвлений/жизненного цикла используй таблицы по профилю, без дублирования
+        правил прозой. Неизвестные пороги и политики не выдумывай.
      - Допущение не оформляется как факт: неизвестное правило → вопрос в Open
-        Decisions Proposal, а не выдуманный Requirement.
+        Decisions Proposal с владельцем и зависимым требованием; зависимый gate ждёт
+        решения. Наблюдение в коде не подменяет согласованное намерение.
      - Не дели Requirements по repositories; имена систем/транспорт/endpoints —
        в system-analysis, если сама их identity не внешнее обязательство.

@@ -291,7 +314,9 @@ artifacts:
      Обратная связь: намерение/scope/capabilities → Proposal; системы/контракты/
      mappings → system-analysis; детали взаимодействия → ux-design.

-      Проверка: `openspec validate <change> --strict --store wealth-ledger-specs`.
+      Проверка: `openspec validate <change> --strict --store wealth-ledger-specs`, затем
+      оба прохода Review из spec-writing.md. Успех CLI не доказывает полноту смысла;
+      проверяй delta вместе с получающимся canonical набором.
    requires:
      - process-record

@@ -445,8 +470,12 @@ artifacts:

      Правила:
      - Каждый NFR: id, порог, способ измерения, обоснование/источник.
+      - Для численного порога определи единицы, условия/нагрузку, точки начала и конца
+        измерения, окно или агрегат по необходимости. Контекст измерения нужен,
+        чтобы разные авторы и QA проверяли одно обязательство.
      - Нет порога — раздел Constraints Without Thresholds с владельцем решения; числа
-        не выдумывай.
+        не выдумывай. Если от порога зависит design или приёмка, вопрос блокирует
+        соответствующий gate до решения.
      - Security-NFR живут здесь; security-analysis ссылается на них по id.

      Не включай: механизмы достижения (design), семантику отказов (failure-model),
@@ -572,10 +601,14 @@ artifacts:
      Назначение:
      Что проверить на уровне системы, чтобы доказать соответствие Specs и выбранным
      analysis-модулям, и с какой глубиной — по риску.
+      Прочитай `openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md`: ожидаемый исход
+      берётся из нормы, а не из догадки QA или фактического поведения реализации.

      Глубина (условные разделы внутри обязательного артефакта):
-      - Всегда: Risk Assessment, Coverage Matrix (строка на каждый delta Requirement),
-        Gaps / Blockers.
+      - Всегда: Risk Assessment, Coverage Matrix (строка на каждый ADDED/MODIFIED/REMOVED
+        Requirement с указанием Scenarios/ветвей правила и способа проверки), Gaps /
+        Blockers. При `skip_specs: true` матрица фиксирует существующее поведение или
+        согласованное ограничение для регрессии и его источник, без выдуманных дельт.
      - Delivery standard: остальные разделы — только при наличии содержания; пустые
        удаляй, не пиши N/A.
      - Lab или complex: все разделы; Cross-system Verification обязателен при выбранных
@@ -589,6 +622,9 @@ artifacts:
        неопределённый flow/ошибка/контракт → пробел в system-analysis.
      - Ссылайся на Scenarios, не переписывай их. Отдельные test cases — только через
        артефакт `test-cases`.
+      - По риску проверь существенные границы, строки таблиц, переходы, повторы,
+        конкуренцию и отсутствие запрещённых побочных эффектов. Пропуск проверки —
+        явное `not verified: <риск-причина>` для названного случая в матрице, не молчание.
      - Планы проверок отделены от результатов: результаты фиксируются на G4.
      - Automation: black-box кандидаты API/E2E; QA repo пока нет — `deferred until QA
        repo exists`.
@@ -0,0 +1,220 @@
+# Spec Writing Profile
+
+Профиль написания и ревью требований `wealth-ledger-sdd-lab`. Цель — одинаковое
+понимание поведения разными авторами, разработчиками и QA, а не дословно одинаковые
+документы. Это адаптация инженерных практик, не заявление о соответствии стандартам.
+
+## Scope
+
+Автор и reviewer читают профиль перед подготовкой или согласованием Specs. Правила
+применяются к новым и изменяемым требованиям; весь canonical store ради стиля не
+переписывается. Пути, delta-операции и gates задаёт `schema.yaml`.
+
+Specs определяют наблюдаемое поведение. Обоснования и открытые решения — в Proposal,
+межсистемные детали — в `analysis/`, механизмы — в design, способы доказательства —
+в QA. Ни один downstream-артефакт не вводит новое поведение молча.
+
+## Writing Rules
+
+1. **Основание.** Каждое обязательство следует из согласованного намерения или
+   существующего контракта. Наблюдение в коде, гипотеза и пример — не решение
+   владельца. Неизвестное запиши в Open Decisions: вопрос, кто решает, зависимое
+   требование и что блокируется. Несогласованные числа и варианты не становятся нормой.
+2. **Термины.** Используй названия из затронутых canonical specs и предоставленного
+   проектного глоссария. Один термин — одно значение в названном контексте. «Счёт»,
+   «брокерский счёт» и «учётная запись» не взаимозаменяемы. Новый или спорный термин
+   определи в теле владеющего им Requirement; остальные требования ссылаются на него.
+   Определение должно различать случаи, а не заменять слово синонимом. Общие термины
+   передаются в глоссарий через Docs Impact; новый файл словаря на каждый change не нужен.
+3. **Атомарность.** Один Requirement — одно независимо принимаемое обязательство.
+   Если одну часть можно принять, а другую отклонить — раздели. Связанные условия,
+   сохранность данных при отказе и единый атомарный результат остаются вместе.
+   Число союзов или SHALL не определяет атомарность.
+4. **Явная норма.** Назови субъект, условие применимости и наблюдаемый результат.
+   Для нового обязательства предпочитай SHALL / SHALL NOT; существующие MUST /
+   MUST NOT равнозначны и сохраняются. SHOULD / MAY не заменяют неопределённый исход:
+   допустимая вариативность и исключения должны быть согласованы и описаны.
+   «Корректно», «быстро», «при необходимости», «и/или», «и т. д.» без определения —
+   повод уточнить правило. Краткость не оправдывает потерю условий.
+5. **Величины и границы.** Для расчёта задай входы, формулу, знак, валюту, точность
+   и момент округления, если они влияют на результат. Для периода — включительность
+   границ, дату/время учёта и часовой пояс; для порога — сравнение и точку отсчёта.
+   Различай ноль, отсутствие значения и неизвестный результат. Не добавляй допуск,
+   таймаут или округление без источника только ради измеримости.
+6. **Свобода реализации.** Описывай «что», а не внутренние классы, библиотеки или
+   алгоритм. Если внутренний механизм можно заменить без изменения внешнего
+   обязательства, это design. Внешний формат или протокол допустим в Specs, когда
+   именно он является согласованным обязательством, а не удобством реализации.
+
+## Requirement and Scenario
+
+Порядок блока: `### Requirement:` с устойчивым именем → общая норма → нужные
+определения/таблица → `#### Scenario:`. Для новых требований используй короткое имя
+на русском; существующие headings сохраняй для native delta-сопоставления.
+
+Выбирай форму по смыслу (адаптация EARS, не дополнительный синтаксис OpenSpec):
+
+| Смысл | Каркас нормы |
+| --- | --- |
+| Постоянное свойство | Система SHALL … |
+| Реакция на событие | При … система SHALL … |
+| Зависимость от состояния | Пока … система SHALL … |
+| Ошибка или исключение | Если … система SHALL … |
+
+У ADDED/MODIFIED Requirement минимум один Scenario. GIVEN нужен, когда исходное
+состояние влияет на результат; WHEN задаёт событие; THEN — наблюдаемый исход с
+определённым ожидаемым значением или составом, не «работает правильно». AND уточняет
+тот же исход. Шаги не описывают внутренние вызовы и селекторы UI.
+
+Сначала общее правило, затем различающие примеры: основной путь, существенная
+граница, иной исход, отказ, повтор или конкуренция — по применимости. Каждый сценарий
+добавляет новый класс поведения. Не вводи правило только в Scenario и не переписывай
+правило целиком для каждой комбинации данных. Сценарии показывают следствия нормы,
+но несколько примеров не доказывают универсальный инвариант.
+
+## Representation
+
+| Когда прозы недостаточно | Представление и обязательные уточнения |
+| --- | --- |
+| Взаимодействуют несколько условий | Таблица решений: область входов, смысл «любое», политика совпадений (одна строка / первая / все), результат отсутствия совпадений или объяснение полноты |
+| Результат зависит от истории | Переходы: исходное состояние, событие/условие, новое состояние, видимый эффект; существенные повторы и недопустимые переходы |
+| Должно сохраняться свойство | Инвариант/формула с областью действия и единицами; примеры нуля, знака и округления по применимости |
+
+Нормативная таблица находится внутри Requirement до первого Scenario и вводится
+фразой с SHALL. Она — единственное определение правила, а не копия соседней прозы.
+Неоднозначные пересечения строк — дефект, если явно не задан приоритет или сбор
+результатов. Таблица безусловно не нужна каждому требованию. Внутренние состояния
+реализации и межсистемные схемы остаются в analysis/design.
+
+## Examples
+
+Учебные примеры формы, не продуктовые решения WealthLedger. В реальном change
+периоды, состояния и исходы берутся из его согласованных входов.
+
+### Condition and Boundary
+
+```markdown
+## ADDED Requirements
+
+### Requirement: Отбор операций за календарный период
+При формировании отчёта система SHALL включать все и только операции выбранного
+счёта, дата учёта которых входит в выбранный период включительно по Europe/Moscow.
+
+#### Scenario: Последний день периода и следующий день
+- **GIVEN** выбран период 01.10.2026–31.10.2026 и счёт A
+- **AND** на счёте A есть операции X с датой учёта 31.10.2026 и Y с датой 01.11.2026
+- **WHEN** формируется отчёт
+- **THEN** отчёт включает X и не включает Y
+```
+
+Плохо: «Система SHALL корректно отбирать операции до конца месяца» — не определены
+месяц, границы, дата отбора и счёт. «THEN список корректен» не позволяет проверить исход.
+
+### Decision Table
+
+```markdown
+## ADDED Requirements
+
+### Requirement: Различимость неполного и пустого итога
+Система SHALL представлять итог расчёта по таблице. «Полнота» означает получение
+всех данных выбранной выборки; «есть записи» — наличие хотя бы одной записи.
+Оба условия логические. Совпадает ровно одна строка; «любое» означает оба значения.
+Покрыты все комбинации.
+
+| Полнота подтверждена | Есть записи | Видимый итог |
+| --- | --- | --- |
+| Нет | Любое | Недоступен, без числового итога |
+| Да | Нет | Ноль и пояснение пустого результата |
+| Да | Да | Рассчитанный итог |
+
+#### Scenario: Известная часть не становится окончательной суммой
+- **GIVEN** известна одна запись на 100 RUB, но полнота выборки не подтверждена
+- **WHEN** пользователь просматривает результат
+- **THEN** итог обозначен как недоступный, не показан ни как 100 RUB, ни как ноль
+```
+
+Плохо: строки «нет данных → 0» и «данные не полны → недоступно» без определения
+«нет данных» — одному входу могут соответствовать два разных результата.
+
+### State Transition
+
+```markdown
+## ADDED Requirements
+
+### Requirement: Отмена формирования отчёта
+При запросе отмены система SHALL изменять состояние формирования отчёта по таблице.
+Область правила — состояния «Ожидает», «Отменён», «Готов»; начальное — «Ожидает».
+Совпадает ровно одна строка. Таблица определяет только событие отмены.
+
+| До | После | Результат отмены |
+| --- | --- | --- |
+| Ожидает | Отменён | Отмена подтверждена, отчёт не будет сформирован |
+| Отменён | Отменён | Отмена подтверждена без повторного эффекта |
+| Готов | Готов | Отмена отклонена, готовый отчёт сохранён |
+
+#### Scenario: Повтор отмены
+- **GIVEN** формирование отчёта уже отменено
+- **WHEN** пользователь снова запрашивает отмену
+- **THEN** отмена подтверждена, состояние остаётся «Отменён»
+```
+
+Плохо: «повтор ничего не делает» — не определён результат для пользователя.
+
+## Review
+
+Используй два прохода на существующем gate Specs (G2 или G3), не новый gate.
+Автор выполняет самопроверку; назначенный по режиму reviewer перепроверяет независимо.
+
+| Проход | Что проверить |
+| --- | --- |
+| Нормоконтроль | Native headings/операции; термины и единицы; явные субъект/условие/исход; атомарность; корректные ссылки; Scenario с проверяемым THEN |
+| Смысл и набор | Необходимость и происхождение норм; основной путь, альтернативы, отказы и границы; повторы/конкуренция/сохранность по риску; непротиворечивость таблиц и итогового baseline; отсутствие выдуманных решений |
+
+Проверь не только delta, но и получающийся набор вместе с canonical specs:
+сохранились ли действующие ограничения, исключения, инварианты и сценарии? MODIFIED
+заменяет полный блок; редакторское улучшение не разрешает удалить прежний сценарий
+или незаметно переименовать Requirement.
+
+Профиль не отменяет ограничений установленного CLI. При предупреждении о длине
+сократи повторения или раздели действительно независимые обязательства; не убирай
+условия и не прячь норму в комментарий/код ради успешного `--strict`.
+
+Контрольный вопрос: «Назови существенную ошибочную реализацию и наблюдение, которым
+это требование отличит её от соответствующей». Если ответ зависит от догадки,
+укажи точную неопределённость. Это эвристика ревью, не доказательство полноты.
+
+Finding: **файл/heading + цитата → нарушенное правило → два возможных толкования
+или недостающий исход → вопрос владельцу/адресат исправления**. Reviewer возвращает
+находки, не переписывает текст по вкусу. Пример: «до конца месяца» → неясна правая
+граница → операция в последний день включается или исключается → уточнить в Specs.
+Нерешённый вопрос, меняющий требование или ожидаемый результат, блокирует его gate;
+косметическое предпочтение не блокирует. Validation и Findings — в существующем
+Gate Log, без нового отчёта на каждый Requirement.
+
+### Trial
+
+Для проверки эффекта дай одним и тем же авторам/моделям одинаковые входы: простое
+правило, ветвление, повтор/состояние и MODIFIED. До сравнения зафиксируй согласованные
+исходы и намеренно оставленные неизвестные. Сравни ответы независимых читателей на
+контрольные вопросы, пропуски и выдуманные нормы, время уточнения и ревью. Совпадение
+формулировок и успешный CLI не считаются доказательством одинакового понимания.
+
+## Sources and Adaptation
+
+Из девяти исследований `sdd-spec-quality/*.md` и трёх сводок `result/*.pdf` выбраны
+правила с понятной пользой для ручного Markdown-процесса. Первоисточники проверены
+30.10.2026; критерии адаптированы, а не перенесены как обязательная сертификация.
+
+| Источник | Что взято и где предел |
+| --- | --- |
+| [NASA SE Handbook, Appendix C, C.2–C.4](https://www.nasa.gov/reference/appendix-c-how-to-write-a-good-requirement/) | Необходимость, одна мысль, «что, а не как», проверяемость и согласованность; не сертификационный комплект документов |
+| [INCOSE GtWR v4 Summary, с. 2–3](https://www.incose.org/wp-content/uploads/legacy/working-groups/requirements-wg/guidetowritingrequirements/incose_rwg_gtwr_v4_summary_sheet.pdf) | C1/C3/C5/C7 для отдельного требования, C10–C14 для набора; R4/R7/R33–R36 — термины, величины, время. Полный платный Guide не заявлен как проверенный |
+| [EARS, автор методики](https://alistairmavin.com/ears/) | Каркасы условия/события/состояния/ошибки; русский язык — адаптация, не буквальная английская грамматика |
+| [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.html), [8174 §2](https://www.rfc-editor.org/rfc/rfc8174.html#section-2) | Значения uppercase SHALL/MUST и запретов; наличие ключевого слова само по себе не гарантирует качество |
+| [Cucumber, Given/When/Then](https://cucumber.io/docs/gherkin/reference/) | Исходное состояние, событие, наблюдаемый исход; Markdown Scenario не становится исполняемым Gherkin-тестом |
+
+Из предложений не приняты: жёсткие лимиты слов/сценариев, подсчёт SHALL вместо
+атомарности, обязательные REQ-ID и скрытые атрибуты, JSON-first, новые линтеры и gates.
+Из нормоконтроля конструкторской документации заимствовано разделение проверки формы
+и смысла; соответствие ГОСТ, DO-178C или ISO/IEC/IEEE 29148 не заявляется. Таблицы и
+инварианты используются по риску; обязательная формальная модель каждому change не нужна.
@@ -1,13 +1,16 @@
 # Non-Functional Requirements

 <!-- Только измеримые ограничения, которые меняют design или проверку. У каждой
-     строки есть порог и способ измерения. -->
+     строки есть согласованный порог с единицами, условия/нагрузка и способ измерения.
+     Для времени укажи точки начала/конца, для статистики — окно и агрегат.
+     Не превращай пример числа из исследования в утверждённую цель. -->

-| ID | Категория | Требование | Порог | Измерение / evidence | Обоснование / источник |
-| --- | --- | --- | --- | --- | --- |
+| ID | Категория | Требование | Порог и единицы | Условия измерения | Измерение / evidence | Обоснование / источник |
+| --- | --- | --- | --- | --- | --- | --- |

 ## Constraints Without Thresholds

-<!-- Реальные, но пока неизмеримые ограничения: почему нет порога и кто его решит. -->
+<!-- Реальные, но пока неизмеримые ограничения: почему нет порога, кто решит и какое
+     решение/проверку это блокирует. Не выдавай неизвестное за согласованный NFR. -->

 ## Open Questions
@@ -36,6 +36,8 @@
     `changes requested` или `invalidated: <причина>`. Никогда не записывай решение,
     которого владелец не давал. ПОСЛЕДНЯЯ строка gate — его состояние; более поздняя
     rejected / changes requested / invalidated снимает этот gate и все последующие.
+     Для Specs: Validation отмечает нормоконтроль и смысловую проверку набора по
+     spec-writing.md; Findings — конкретные неясности/пропуски и их разрешение.
     Пример:
     | G1 | 2026-10-29 | proposal, change-profile | `openspec validate` OK; readiness: plan OK | product-analyst: 1 major — закрыт в Open Decisions | approved "ок, идём дальше" (сессия) |
     | G2 | 2026-10-30 | specs | `openspec validate --strict` OK; readiness: plan OK | qa-engineer: в Scenario нет значения THEN | changes requested |
@@ -34,4 +34,6 @@
 ## Open Decisions

 <!-- Ещё не принятые решения, способные изменить scope. Каждое: вопрос, кто решает,
-     что блокируется до ответа. Пусто, только если таких нет. -->
+     зависимое требование/артефакт и что блокируется до ответа. Несогласованное
+     правило, термин, порог или вариант поведения не заменяй допущением в Specs.
+     Пусто, только если таких вопросов нет. -->
@@ -10,19 +10,25 @@

 ## Coverage Matrix

-<!-- Строка на каждый delta Requirement. Проверка — системный способ доказать его;
-     ids test cases, если выбран test-cases; либо «not verified: <риск-причина>».
+<!-- Строка на каждый ADDED/MODIFIED/REMOVED Requirement. Назови покрытые Scenarios
+     точными headings и ветви таблицы/переходы, если они есть. Проверка даёт наблюдение,
+     отличающее исполнение нормы от нарушения; test cases — ссылками, не копиями.
+     Пропуск случая — «not verified: <риск-причина>» с названием случая.
     Покрытие — только строки этой таблицы; упоминание требования в другом месте
     файла покрытием не считается. REMOVED требует проверки миграции/регрессии.
+     При skip_specs: true вместо дельт укажи существующее поведение/ограничение,
+     которое сохраняем, точный источник и регрессионную проверку.
     Пример:
-     | `portfolio/holdings` — `Итог портфеля не учитывает дубли операций` | повторный импорт того же файла брокера, итог не меняется | API | TC-HOLD-001 |
-     | `portfolio/holdings` — `Портфель показывает валюту` | not verified: только отображение, проверено ревью Scenario; риск низкий | — | — | -->
+     | `example-report` — `Отбор операций за календарный период` | Последний день периода и следующий день | Отчёт за октябрь включает X за 31.10 и исключает Y за 01.11 | API | ссылка на Scenario | -->

-| Requirement | Проверка | Уровень | Test cases |
-| --- | --- | --- | --- |
+| Requirement / регрессионный baseline | Сценарии / ветви правила | Проверка / ожидаемое наблюдение | Уровень | Test cases |
+| --- | --- | --- | --- | --- |

 ## Negative and Boundary Focus

+<!-- Границы до/на/после порога, отказ, повтор, конкуренция, сохранность данных —
+     только применимое. Ссылайся на нормы, не придумывай исходы. -->
+
 ## Cross-system Verification

 ## Test Data and Environment Needs
@@ -34,3 +40,6 @@
 ## Regression Impact

 ## Gaps / Blockers
+
+<!-- Цитата/heading → неоднозначность или непокрытый исход → владелец решения и
+     upstream-артефакт. Вопрос о значении expected result блокирует согласование. -->
@@ -1,5 +1,8 @@
 <!--
-Оставь только нужные этой дельте разделы; комментарий удали до approval.
+Перед заполнением прочитай единый профиль:
+openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md.
+Оставь только нужные этой дельте разделы; подсказки и образец не входят в результат.
+Файл — specs/<capability-path>/spec.md с точным путём из Proposal.

 Только новая capability: `## Purpose` в 1–2 предложения (от 50 символов).
 Существующая capability: Purpose не добавляй.
@@ -11,22 +14,29 @@
 - `## REMOVED Requirements` — heading Requirement плюс **Reason** и **Migration**.
 - `## RENAMED Requirements` — только пары `FROM:` и `TO:`.

-Каждый нормативный Requirement осознанно использует BCP 14 (RFC 2119 + RFC 8174)
-uppercase SHALL/MUST и минимум один `#### Scenario:` с `- **WHEN**` и
-`- **THEN**`. Строчные «must/should/may» — обычный язык.
-Не оставляй пустые разделы операций и образцы.
+Каркас ADDED/MODIFIED: устойчивое имя → субъект SHALL <наблюдаемый результат>
+с явным условием, если оно нужно → определения/таблица → Scenarios.
+SHALL NOT — запрет; существующие MUST/MUST NOT равнозначны. Один Requirement —
+одно независимо принимаемое обязательство, не подсчёт предложений или SHALL.
+Сценарий: GIVEN — существенное исходное состояние, WHEN — событие,
+THEN — конкретный наблюдаемый исход. Минимум один Scenario; границы/отказы/повторы
+добавляй по смыслу. Новое правило в одном лишь сценарии недопустимо.
+Термины определены, величины имеют единицы и границы. Неизвестное — вопрос в
+Open Decisions с владельцем и зависимым требованием, не придуманный ответ.

-Пример:
+Учебный образец формы, не продуктовая политика:
 ## ADDED Requirements
-### Requirement: Итог портфеля не учитывает дубли операций
-Система SHALL учитывать каждый идентификатор операции брокера в итоге портфеля
-не более одного раза.
+### Requirement: Отбор операций за календарный период
+При формировании отчёта система SHALL включать все и только операции выбранного
+счёта, дата учёта которых входит в выбранный период включительно по Europe/Moscow.

-#### Scenario: Одна операция импортирована дважды
- **WHEN** операция `op-1` на 100.00 RUB импортирована дважды
- **THEN** итог портфеля увеличивается ровно на 100.00 RUB
+#### Scenario: Последний день периода и следующий день
+- **GIVEN** выбран период 01.10.2026–31.10.2026 и счёт A
+- **AND** на счёте A есть операции X с датой учёта 31.10.2026 и Y с датой 01.11.2026
+- **WHEN** формируется отчёт
+- **THEN** отчёт включает X и не включает Y

-Плохо: «Система SHALL корректно обрабатывать дубли» — нет наблюдаемого критерия;
-«THEN итог правильный» — нет ожидаемого значения; один Requirement на импорт,
-отображение и экспорт сразу — раздели по поведению.
+Плохо: «корректно отбирать операции до конца месяца» — не определены месяц,
+границы, дата отбора и счёт; «THEN список корректен» — нет проверяемого исхода.
+Для таблиц решений и переходов используй эталоны из профиля.
 -->