refactor: make sdd-lab review-driven (WealthLedger/specs#66)

Replace executable schema checks with explicit review-driven readiness, add a requirement-writing profile, and incorporate review clarifications for source traceability and comparative validation.
2026-10-30 13:35:39 +03:00
parent a2d2df3b5a
commit b9ec11f5ba
19 changed files with 982 additions and 851 deletions
@@ -1,28 +1,28 @@
 # Data Mapping

-<!-- guide: Field-level transformation between systems. Large mappings go to a
-     machine-checkable file in contracts/ and are referenced here. Remove guides. -->
+<!-- Преобразование данных между системами по полям. Большой mapping — машиночитаемый
+     файл в contracts/ со ссылкой отсюда. -->

 ## Source and Target

-| Mapping | Source (owner) | Target (owner) | Direction | Trigger |
+| Mapping | Источник (владелец) | Цель (владелец) | Направление | Trigger |
 | --- | --- | --- | --- | --- |

 ## Field Mapping

-| Target field | Source field(s) | Transformation | Unit / currency / scale | Nullability | Default | Validation | On failure |
+| Поле цели | Поля источника | Преобразование | Единица / валюта / scale | Nullability | Default | Валидация | При ошибке |
 | --- | --- | --- | --- | --- | --- | --- | --- |

 ## Invariants

-<!-- guide: Conservation rules that must hold after mapping, e.g. "total = sum of
-     positions + cash; each money unit counted once", sign conventions, rounding
-     point. Each invariant references the spec requirement it protects. -->
+<!-- Правила сохранения после mapping, например «итог = сумма позиций + кэш; каждая
+     денежная единица учтена один раз», знаки, точка округления. Каждый инвариант
+     ссылается на защищаемый Requirement. -->

 ## Double-counting and Classification Risks

-<!-- guide: Every source record type that could fall into two target aggregates,
-     and the rule that assigns it to exactly one. -->
+<!-- Каждый тип исходной записи, который может попасть в два агрегата, и правило,
+     относящее его ровно к одному. -->

 ## Transformation Errors

@@ -1,22 +1,22 @@
 # Engineering Design

-<!-- guide: How affected repositories implement approved specs and system
-     obligations. Reference upstream ids; do not restate them. Remove guides. -->
+<!-- Как affected repositories реализуют утверждённые specs и системные обязательства.
+     Ссылайся на upstream ids, не пересказывай. -->

 ## Inputs

-<!-- guide: Exact upstream artifacts this design implements (specs, selected
-     system-analysis modules, ux-design, security-analysis). -->
+<!-- Точные upstream-артефакты, которые реализует этот design (specs, выбранные
+     модули analysis/, ux-design, security-analysis). -->

 ## Architecture Drivers

-<!-- guide: Requirements, NFR ids, constraints and risks that force decisions. -->
+<!-- Requirements, ids NFR, ограничения и риски, которые вынуждают решения. -->

 ## Technical Goals / Non-Goals

 ## Implementation Impact Map

-| Area | Affected | Outcome or N/A reason |
+| Область | Затронута | Результат или причина N/A |
 | --- | --- | --- |
 | main | | |
 | frontend | | |
@@ -24,8 +24,8 @@

 ## Decisions

-<!-- guide: Per decision: context, chosen option, rejected alternatives, driver it
-     satisfies. Group by repository when that helps. -->
+<!-- На каждое решение: контекст, выбранный вариант, отвергнутые альтернативы, driver.
+     Группируй по repository, если это помогает. -->

 ## Components and Responsibilities

@@ -33,16 +33,16 @@

 ## Contract Implementation

-<!-- guide: How each contract is produced/consumed and how published OpenAPI is
-     compared with the target contract. N/A when no contracts changed. -->
+<!-- Как каждый контракт производится/потребляется и как опубликованный OpenAPI
+     сравнивается с target-контрактом. N/A, если контракты не менялись. -->

 ## Cross-cutting Implementation

 ## UI Implementation

-<!-- guide: With ux-design.md: component composition, state, data fetching, how
-     each UI state is produced — no restated UX. Without ux-design.md: state
-     new/changed, reuse or N/A with reason, plus the needed screen/state detail. -->
+<!-- С ux-design: композиция компонентов, state, data fetching, как получается каждое
+     UI-состояние — без пересказа UX. Без ux-design: new/changed/reuse или N/A с
+     причиной и нужные детали экранов/состояний. -->

 ## Developer Verification Strategy

@@ -50,8 +50,8 @@

 ## Solution Assessment

-<!-- guide: Required for new auth, security, storage, integration, observability,
-     caching, concurrency or shared tooling; otherwise N/A with reason. -->
+<!-- Обязателен для нового auth, security, storage, интеграции, observability,
+     кеширования, конкурентности или общего tooling; иначе N/A с причиной. -->

 ## Risks / Trade-offs

@@ -1,12 +1,12 @@
 # Documentation Impact

-<!-- guide: Plan only; docs/ is edited by [docs] tasks. Remove guides. -->
+<!-- Только план; docs/ правят tasks `[docs]`. -->

 ## Summary

 ## Documentation Changes

-| Action | Target | Category | Resulting AS-IS | Source | Verification |
+| Action | Target | Category | Итоговое AS-IS | Source | Verification |
 | --- | --- | --- | --- | --- | --- |

 ## Diagram Promotion
@@ -1,19 +1,18 @@
 # Failure Model

-<!-- guide: Boundary-level failure semantics. Implementation of mechanisms (queues,
-     locks, libraries) belongs to design.md. Remove guides before G3. -->
+<!-- Семантика отказов на границах. Реализация механизмов (очереди, locks,
+     библиотеки) — в design.md. -->

 ## Failure Scenarios

-| ID | Boundary / step | Failure | Detection | Required system behavior | Observable result | Requirement |
+| ID | Граница / шаг | Отказ | Обнаружение | Требуемое поведение системы | Наблюдаемый результат | Requirement |
 | --- | --- | --- | --- | --- | --- | --- |

 ## Timeouts and Retries

 ## Idempotency and Duplicate Handling

-<!-- guide: Idempotency key, scope, retention; what a duplicate request/event
-     yields. -->
+<!-- Ключ идемпотентности, scope, срок хранения; что даёт повторный запрос/событие. -->

 ## Ordering and Concurrency

@@ -1,14 +1,16 @@
 # Non-Functional Requirements

-<!-- guide: Only measurable constraints that change design or verification.
-     Each row needs a threshold and a way to measure it. Remove guides. -->
+<!-- Только измеримые ограничения, которые меняют design или проверку. У каждой
+     строки есть согласованный порог с единицами, условия/нагрузка и способ измерения.
+     Для времени укажи точки начала/конца, для статистики — окно и агрегат.
+     Не превращай пример числа из исследования в утверждённую цель. -->

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

 ## Constraints Without Thresholds

-<!-- guide: Constraints that are real but not measurable yet; state why and who
-     decides the threshold. -->
+<!-- Реальные, но пока неизмеримые ограничения: почему нет порога, кто решит и какое
+     решение/проверку это блокирует. Не выдавай неизвестное за согласованный NFR. -->

 ## Open Questions
@@ -1,11 +1,10 @@
 # Observability

-<!-- guide: What must be observable and why; not which SDK, exporter or logger
-     (design.md). Remove guides before G3. -->
+<!-- Что должно быть наблюдаемо и зачем; не какой SDK, exporter или logger (design.md). -->

 ## Semantic Events

-| Event | Trigger | Required attributes | Consumer / purpose |
+| Событие | Trigger | Обязательные атрибуты | Потребитель / назначение |
 | --- | --- | --- | --- |

 ## Logs, Metrics and Traces
@@ -14,11 +13,11 @@

 ## SLI and Alert Conditions

-| SLI | Definition | Target | Alert condition |
+| SLI | Определение | Цель | Условие алерта |
 | --- | --- | --- | --- |

 ## Diagnostic Scenarios

-<!-- guide: "When X happens, an operator can determine Y from Z." -->
+<!-- «Когда X, оператор определяет Y по Z». -->

 ## Open Questions
@@ -1,17 +1,21 @@
 # Process Record

-**Mode:** <!-- guide: lab | delivery -->
-**Class:** <!-- guide: standard | complex -->
-**Issue:** <!-- guide: Gitea Issue link -->
+**Mode:** <!-- lab | delivery -->
+**Class:** <!-- standard | complex -->
+**Issue:** <!-- ссылка на Gitea Issue -->

 ## Change Profile

-<!-- guide: One row per conditional artifact, all ten rows required. Selected =
-     yes|no. Reason cites the concrete trigger from the instruction table or why
-     it does not apply; "lab practice" is a valid reason only in lab mode and
-     must name the practice. -->
+<!-- Строка на каждый условный артефакт, все десять обязательны. Выбран = yes|no.
+     Причина называет конкретный trigger из instruction артефакта или объясняет, почему
+     он не применим; «lab: практика …» допустима только в lab и называет практику.
+     Пример:
+     | failure-model | yes | синхронизация брокера повторяет неидемпотентную запись |
+     | nfr | no | нет новых обязательств по задержке, объёму или хранению |
+     | data-mapping | yes | lab: практика data mapping |
+     Плохо: `| nfr | no | N/A |` — причина должна объяснять, почему не нужно. -->

-| Artifact | Selected | Reason |
+| Артефакт | Выбран | Причина |
 | --- | --- | --- |
 | research | | |
 | ux-design | | |
@@ -26,32 +30,40 @@

 ## Gate Log

-<!-- guide: Append-only, chronological. Scope = artifact ids covered by the
-     decision. Validation = commands run and their results, review verdicts.
-     Decision = `approved "<quoted owner words>"`, `rejected`, `changes requested`
-     or `invalidated: <reason>`. Never write a decision the owner did not give. -->
+<!-- Только дописывание, по хронологии. Scope — ids артефактов в решении.
+     Validation — выполненные команды и результаты, вердикты review.
+     Decision — `approved "<дословные слова владельца>"`, `rejected`,
+     `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 |
+     Плохо: `approved` без цитаты владельца; строка G4 со Scope `design`. -->

-| Gate | Date | Scope | Validation | Findings | Decision |
+| Gate | Дата | Scope | Validation | Findings | Decision |
 | --- | --- | --- | --- | --- | --- |

 ## Descoped Work

-<!-- guide: Tasks removed from tasks.md after G3. Reason and approving gate are
-     required. Leave the header row only when nothing was descoped. -->
+<!-- Tasks, удалённые из tasks.md после G3. Причина и gate решения обязательны.
+     Если ничего не снято — только строка заголовка. -->

-| Task | Reason | Gate |
+| Task | Причина | Gate |
 | --- | --- | --- |

 ## Lab Journal

-<!-- guide: lab mode: one row per completed stage, written right after it.
-     Unique findings = what this stage found that no other stage did.
-     Cost = subagent calls, approximate tokens or time. delivery mode: optional. -->
+<!-- lab: строка на каждую завершённую стадию, сразу после неё. Уникальные находки —
+     то, что нашла только эта стадия. Стоимость — вызовы сабагентов, примерно токены
+     или время. delivery: необязательно. -->

-| Stage | Role / subagent | Unique findings | Decisions | Risks found / excluded | Handoff issues | Skills | Cost | Transferable |
+| Стадия | Роль / сабагент | Уникальные находки | Решения | Риски найдены / исключены | Проблемы передачи | Skills | Стоимость | Переносимо |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- |

 ## Retrospective

-<!-- guide: Written after G4. Which stages paid off, which were redundant for this
-     class of change, what to change in the schema. Facts first, then opinion. -->
+<!-- После G4. Какие стадии окупились, какие были лишними для этого класса change,
+     что поменять в schema. Сначала факты, потом мнение. -->
@@ -1,7 +1,6 @@
 # Proposal

-<!-- guide: Language of the Change Owner. No files, APIs, tables, libraries,
-     diagrams or test plans. Remove every guide comment before G1. -->
+<!-- Язык Change Owner. Без файлов, API, таблиц, библиотек, диаграмм и тест-планов. -->

 ## Why

@@ -23,14 +22,18 @@

 ## Success Criteria

+<!-- Каждый критерий измерим или наблюдаем: что увидит пользователь или владелец. -->
+
 ## Evidence

-<!-- guide: Facts that justify the change, each with a source: Issue, research
-     (link or `research.md`), incident, measurement. Mark hypotheses as such. -->
+<!-- Факты, обосновывающие change, каждый с источником: Issue, research (ссылка или
+     `analysis/research.md`), инцидент, измерение. Гипотезы помечай явно. -->

 ## Assumptions / Dependencies

 ## Open Decisions

-<!-- guide: Decisions not yet taken that may change scope. Each item: question,
-     who decides, what blocks until it is answered. Empty only if none exist. -->
+<!-- Ещё не принятые решения, способные изменить scope. Каждое: вопрос, кто решает,
+     зависимое требование/артефакт и что блокируется до ответа. Несогласованное
+     правило, термин, порог или вариант поведения не заменяй допущением в Specs.
+     Пусто, только если таких вопросов нет. -->
@@ -1,24 +1,34 @@
 # QA Analysis

-<!-- guide: Risk-based system verification strategy. Reference scenarios; do not
-     restate them. No developer unit/component test plans. Remove guides. -->
+<!-- Risk-based стратегия системной проверки. Ссылайся на Scenarios, не пересказывай.
+     Без планов developer unit/component tests. -->

 ## Risk Assessment

-| Risk | Affected requirements | Likelihood | Impact | Verification depth |
+| Риск | Затронутые требования | Вероятность | Ущерб | Глубина проверки |
 | --- | --- | --- | --- | --- |

 ## Coverage Matrix

-<!-- guide: One row per delta requirement. Check = system-level way of proving
-     it; test case ids when test-cases is selected; or "not verified: <risk
-     reason>". -->
+<!-- Строка на каждый ADDED/MODIFIED/REMOVED Requirement. Назови покрытые Scenarios
+     точными headings и ветви таблицы/переходы, если они есть. Проверка даёт наблюдение,
+     отличающее исполнение нормы от нарушения; test cases — ссылками, не копиями.
+     Пропуск случая — «not verified: <риск-причина>» с названием случая.
+     Покрытие — только строки этой таблицы; упоминание требования в другом месте
+     файла покрытием не считается. REMOVED требует проверки миграции/регрессии.
+     При skip_specs: true вместо дельт укажи существующее поведение/ограничение,
+     которое сохраняем, точный источник и регрессионную проверку.
+     Пример:
+     | `example-report` — `Отбор операций за календарный период` | Последний день периода и следующий день | Отчёт за октябрь включает X за 31.10 и исключает Y за 01.11 | API | ссылка на Scenario | -->

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

 ## Negative and Boundary Focus

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

 ## Test Data and Environment Needs
@@ -31,4 +41,5 @@

 ## Gaps / Blockers

-<!-- guide: Each gap names its routing destination artifact. -->
+<!-- Цитата/heading → неоднозначность или непокрытый исход → владелец решения и
+     upstream-артефакт. Вопрос о значении expected result блокирует согласование. -->
@@ -1,7 +1,7 @@
 # Product Research

-<!-- guide: Input context, not a requirement source. Every claim is marked
-     [F] fact with source, [I] interpretation or [H] hypothesis. Remove guides. -->
+<!-- Входной контекст, не источник требований. Каждое утверждение помечено:
+     [F] факт с источником, [I] интерпретация, [H] гипотеза. -->

 ## Problem Statement

@@ -11,7 +11,7 @@

 ## Existing Solutions and Alternatives

-| Option | What it does | Strengths | Weaknesses | Source |
+| Вариант | Что делает | Сильные стороны | Слабые стороны | Источник |
 | --- | --- | --- | --- | --- |

 ## Evidence & Sources
@@ -24,5 +24,5 @@

 ## Recommendation

-<!-- guide: build / do not build / narrow scope / research more, with reasons.
-     "Do not build" is a valid outcome. -->
+<!-- делать / не делать / сузить scope / исследовать дальше — с причинами.
+     «Не делать» — допустимый итог. -->
@@ -1,7 +1,7 @@
 # Security Analysis

-<!-- guide: Threat model of this change only. Reference security NFR rows by id;
-     do not restate them. No generic checklist. Remove guides before G3. -->
+<!-- Threat model только этого change. На security-NFR ссылайся по id, не
+     пересказывай. Без универсального чек-листа. -->

 ## Scope

@@ -11,16 +11,16 @@

 ## Threats

-| ID | Threat (STRIDE) | Attack scenario | Asset / boundary | Existing control | Likelihood / impact |
+| ID | Угроза (STRIDE) | Сценарий атаки | Актив / граница | Существующий контроль | Вероятность / ущерб |
 | --- | --- | --- | --- | --- | --- |

 ## Recommended Mitigations

-| Threat | Mitigation | Owner artifact (specs / system-analysis / design) |
+| Угроза | Mitigation | Артефакт-владелец (specs / system-analysis / design) |
 | --- | --- | --- |

 ## Residual Risks

 ## Validation Requirements

-<!-- guide: Evidence needed before G4: review focus, negative tests, tooling. -->
+<!-- Evidence, нужные до G4: фокус review, негативные тесты, инструменты. -->
@@ -1,18 +1,48 @@
 <!--
-Choose only the sections this delta needs; delete this guide before approval.
+Перед заполнением прочитай единый профиль:
+openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md.
+Оставь только нужные этой дельте разделы; подсказки и образец не входят в результат.
+Файл — specs/<capability-path>/spec.md с точным путём из Proposal.

-New capability only: add `## Purpose` with 1–2 sentences (50+ characters).
-Existing capability: do not add Purpose.
+Только новая capability: `## Purpose` в 1–2 предложения (от 50 символов).
+Существующая capability: Purpose не добавляй.

-Supported operations:
- `## ADDED Requirements`: new complete Requirement blocks.
- `## MODIFIED Requirements`: full existing Requirement blocks with every
-  surviving Scenario, then edited behavior; heading matches exactly.
- `## REMOVED Requirements`: Requirement heading plus **Reason** and **Migration**.
- `## RENAMED Requirements`: `FROM:` and `TO:` heading pairs only.
+Операции:
+- `## ADDED Requirements` — новые полные блоки Requirement.
+- `## MODIFIED Requirements` — полный существующий блок со всеми сохраняемыми
+  Scenario, затем изменённое поведение; heading совпадает точно.
+- `## REMOVED Requirements` — heading Requirement плюс **Reason** и **Migration**.
+- `## RENAMED Requirements` — только пары `FROM:` и `TO:`.

-Every normative Requirement uses BCP 14 (RFC 2119 + RFC 8174) uppercase
-SHALL/MUST deliberately, and at least one `#### Scenario:` with `- **WHEN**`
-and `- **THEN**`. Lowercase must/should/may are ordinary language.
-Do not leave empty operation sections or a sample Requirement.
+Каркас ADDED/MODIFIED: устойчивое имя → субъект SHALL <наблюдаемый результат>
+с явным условием, если оно нужно → определения/таблица → Scenarios.
+SHALL NOT — запрет; существующие MUST/MUST NOT равнозначны. Один Requirement —
+одно независимо принимаемое обязательство, не подсчёт предложений или SHALL.
+Сценарий: GIVEN — существенное исходное состояние, WHEN — событие,
+THEN — конкретный наблюдаемый исход. Минимум один Scenario; границы/отказы/повторы
+добавляй по смыслу. Новое правило в одном лишь сценарии недопустимо.
+AND дополняет предыдущий тип шага GIVEN/WHEN/THEN.
+Термины определены, величины имеют единицы и границы. Неизвестное — вопрос в
+Open Decisions с владельцем и зависимым требованием, не придуманный ответ.
+
+Для спорного/выведенного Requirement укажи источник перед первым Scenario по профилю.
+Пример формата (подставь реальное согласованное решение):
+**Источник (ненормативно):** [решение владельца](<URL-комментария-Issue>), пункт «Границы периода».
+Ссылка остаётся пригодной после archive; норму полностью сформулируй в Requirement.
+
+Учебный образец формы, не продуктовая политика:
+## 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
+
+Плохо: «корректно отбирать операции до конца месяца» — не определены месяц,
+границы, дата отбора и счёт; «THEN список корректен» — нет проверяемого исхода.
+Для таблиц решений и переходов используй эталоны из профиля.
 -->
@@ -1,12 +1,11 @@
 # System Analysis

-<!-- guide: Hub document. Owns context, boundaries, flows overview and contract
-     semantics; details live in selected modules and are referenced, not copied.
-     Remove guides before G3. -->
+<!-- Hub. Владеет контекстом, границами, обзором flows и семантикой контрактов;
+     детали — в выбранных модулях, на них ссылаются, а не копируют. -->

 ## Requirement Coverage

-| Requirement | Flow / contract | Module |
+| Requirement | Flow / контракт | Модуль |
 | --- | --- | --- |

 ## System Context and Boundaries
@@ -19,32 +18,32 @@

 ## Data Ownership

-| Data | Source of truth | Writers | Readers |
+| Данные | Источник истины | Пишут | Читают |
 | --- | --- | --- | --- |

 ## Interaction Flows

-<!-- guide: Reference diagrams/*.mmd; text only for what a diagram cannot carry. -->
+<!-- Ссылки на diagrams/*.mmd; текст — только для того, что диаграмма не передаёт. -->

 ## Contracts

-<!-- guide: Per contract: producer/consumer, operation/event, version, file in
-     contracts/, compatibility class (additive / breaking), published source it
-     must match after implementation. -->
+<!-- На каждый контракт: producer/consumer, операция/событие, версия, файл в
+     contracts/, класс совместимости (additive / breaking), опубликованный источник,
+     с которым он обязан совпасть после реализации. -->

-| Contract | Producer → Consumer | File | Compatibility | Published source |
+| Контракт | Producer → Consumer | Файл | Совместимость | Опубликованный источник |
 | --- | --- | --- | --- | --- |

 ## Error Semantics

-<!-- guide: Business vs technical failures at boundaries. Detailed retry/
-     idempotency/recovery belongs to failure-model.md when selected. -->
+<!-- Бизнес- и технические отказы на границах. Подробные retry/идемпотентность/
+     восстановление — в failure-model.md, если выбран. -->

 ## Compatibility / Migration

 ## Detailed Modules

-<!-- guide: Link each selected module (data-mapping, failure-model, nfr,
-     observability) with one line on what it decides. -->
+<!-- Ссылка на каждый выбранный модуль (data-mapping, failure-model, nfr,
+     observability) и одна строка о том, что он решает. -->

 ## Open Questions
@@ -1,18 +1,24 @@
 # Tasks

-<!-- guide: Task line format:
- [ ] X.Y [main|frontend|backend|docs|specs] <Kind>: <action + outcome>
-  - **Covers:** `capability` — `Requirement heading` pairs, or `N/A` — <reason>
-  - **Source:** exact upstream artifact section / contract / docs-impact entry
-  - **Verification:** owner-controlled command, observable check or artifact
-  - **Depends on:** task ids or none
+<!-- Формат task:
+- [ ] X.Y [main|frontend|backend|docs|specs] <Kind>: <действие + результат>
+  - **Covers:** пары `capability` — `Requirement heading` или `N/A` — <причина>
+  - **Source:** точный раздел upstream-артефакта / контракт / запись docs-impact
+  - **Verification:** команда владельца, наблюдаемая проверка или артефакт
+  - **Depends on:** ids tasks или none
 Kinds: Implementation, Migration, Automated Testing, Contract Parity, Docs,
-Independent Review, QA Verification, Verification. Remove guides before G3. -->
+Independent Review, QA Verification, Verification.
+Пример:
+- [ ] 2.1 [backend] Implementation: пропускать операции, чей внешний id уже сохранён
+  - **Covers:** `portfolio/holdings` — `Итог портфеля не учитывает дубли операций`
+  - **Source:** design.md Decisions D2; analysis/failure-model.md F3
+  - **Verification:** `npm run verify` в backend; повторный импорт fixture оставляет итог 100.00
+  - **Depends on:** 1.1
+Плохо: «Verification: проверить, что работает»; Covers с heading, которого нет в specs. -->

-## 1. <!-- guide: delivery phase -->
+## 1. <!-- этап delivery -->

 ## Docs Impact

-<!-- guide: Only when docs-impact is not selected: list docs/ targets with
-     resulting AS-IS, or one concrete no-change reason. Delete when docs-impact.md
-     exists. -->
+<!-- Только если docs-impact не выбран: targets в docs/ с итоговым AS-IS или одна
+     конкретная причина без изменений. Удали раздел, если есть analysis/docs-impact.md. -->
@@ -1,10 +1,10 @@
-# Test Cases — <!-- guide: area -->
+# Test Cases — <!-- область -->

-<!-- guide: One file per area under test-cases/. A case adds concrete data, steps
-     or an oracle that the scenario does not already state; otherwise reference the
-     scenario from qa-analysis instead of writing a case. Remove guides. -->
+<!-- Один файл на область в analysis/test-cases/. Case добавляет конкретные данные,
+     шаги или oracle, которых нет в Scenario; иначе qa-analysis ссылается на Scenario,
+     а case не пишется. -->

-### TC-<!-- guide: AREA-NNN --> <!-- guide: title -->
+### TC-<!-- AREA-NNN --> <!-- название -->

 - **Verifies:** `capability` — `Requirement heading` / Scenario
 - **Risk / Priority:**
@@ -13,4 +13,4 @@
 - **Steps:**
  1.
 - **Expected Results:**
- **Automation Candidate:** <!-- guide: yes (level) | no (reason) -->
+- **Automation Candidate:** <!-- yes (уровень) | no (причина) -->
@@ -1,15 +1,14 @@
 # UX Design

-<!-- guide: Interaction design of observable behavior from Delta Specs. Reference
-     requirements as `capability` — `Requirement heading`; do not restate them.
-     No server architecture, contracts or component/state-management choices.
-     Remove guides before G3. -->
+<!-- Interaction design observable behavior из Delta Specs. Ссылайся на требования
+     как `capability` — `Requirement heading`, не пересказывай. Без серверной
+     архитектуры, контрактов и выбора компонентов/state management. -->

 ## User Goals

 ## User Flows

-<!-- guide: Mermaid flowchart or numbered steps per flow, with entry and exit points. -->
+<!-- Mermaid flowchart или нумерованные шаги на каждый flow, с точками входа и выхода. -->

 ## Information Architecture and Screen Structure

@@ -17,7 +16,7 @@

 ## UI States

-| Screen / region | Loading | Empty | Error | Success | Partial / stale |
+| Экран / область | Loading | Empty | Error | Success | Partial / stale |
 | --- | --- | --- | --- | --- | --- |

 ## Validation Feedback
@@ -26,15 +25,15 @@

 ## Accessibility

-<!-- guide: Keyboard path, focus order, names/roles, contrast, non-color cues. -->
+<!-- Путь с клавиатуры, порядок фокуса, имена/роли, контраст, признаки не только цветом. -->

 ## Design System Reuse

 ## Materials

-<!-- guide: Inline Markdown by default; local files follow the Visual Package rule. -->
+<!-- По умолчанию inline Markdown; локальные файлы — по правилу Visual Package. -->

-| Material ID | Relative path / reference | Screen/state and purpose | SHA-256 |
+| ID материала | Относительный путь / ссылка | Экран/состояние и назначение | SHA-256 |
 | --- | --- | --- | --- |

 ## Open UX Questions