name: wealth-ledger-sdd-lab version: 1 description: Экспериментальный Engineering Lab workflow — proposal + Change Profile → specs → выбранные analysis-артефакты → design ∥ qa-analysis → tasks → apply, 4 decision gates # Контракт OpenSpec CLI: артефакт завершён, когда существует путь `generates`; `requires` — жёсткое ребро; # условных артефактов в CLI нет. Поэтому условные артефакты ниже не требуются ни обязательными # артефактами, ни apply. Выбор, порядок, gates и готовность — ручной Readiness Checklist в # instruction `process-record`. Исполняемых проверок у schema нет: gates рекомендательные, их # соблюдение обеспечивают основной агент и independent reviewer, а не CLI. # Раскладка change: в корне — proposal, process-record, specs/, design, tasks; # вся аналитика — в `analysis/`. artifacts: - id: proposal generates: proposal.md description: Намерение Change Owner — зачем, результат, scope, capabilities, evidence, открытые решения template: proposal.md instruction: | Владелец: Change Owner; черновик — product-analyst. Gate: G1 Product Decision. Назначение: Proposal фиксирует, зачем нужно изменение, какой результат ожидается, где проходит scope и какие решения ещё не приняты. Это не requirements, не system analysis и не design. Старт lab lifecycle (до первой записи): - Change создаётся явно: `openspec new change --schema wealth-ledger-sdd-lab --store wealth-ledger-specs`. Schema не становится default и не применяется к существующим changes. - Small не идёт в OpenSpec: fix восстанавливает поведение, уже описанное canonical spec (spec не меняется или уточняется без изменения смысла), — правка в том же Issue. Fix, меняющий canonical behavior, — минимум `delivery` `standard`. Lab schema принимает только Standard и Complex. - Если есть research (`analysis/research.md`, Issue, внешний отчёт), прочитай его выводы; Proposal ссылается на него в **Evidence**, а не копирует. Research может закончиться решением не делать change — тогда change не создаётся. - Общий протокол (Change Profile, gates, Readiness Checklist, делегирование) — instruction `process-record`; он действует на каждой стадии. Прочитай его до первой записи: `openspec instructions process-record`. Прочитай сначала: - Релевантные canonical specs из `specs/openspec/specs/` и AS-IS страницы `docs/` (`overview.md`, `architecture/`, `domains/`, `integrations/`, `adr/`, `design/`). - Код изучай не глубже, чем нужно для scope и impact. Правила: - Один Proposal = одно связное намерение; независимо поставляемое разделяй. - Capabilities перечисляют каждую новую или изменяемую behavior spec точным path. Если observable behavior не меняется — `.openspec.yaml: skip_specs: true`. - Ломающее observable behavior помечай **BREAKING**. - Evidence разделяет факты (с источником) и гипотезы. - Open Decisions: вопрос, кто решает, что блокирует. Вопрос, меняющий scope или capabilities, решается до G1. Не включай: файлы/классы/функции/таблицы/ORM-сущности; библиотеки/фреймворки/ транспорт; контракты endpoint/payload/error-code; диаграммы; тест-планы; tasks/ план PR; пиксельные детали UI. Обратная связь: пробел в research → research; остальное возвращается сюда. Проверка: - `openspec validate --store wealth-ledger-specs` (Why/What Changes); структурный успех не является approval. - Затем создай `process-record.md` (Change Profile) и предъяви на G1 оба файла. requires: [] - id: research generates: analysis/research.md description: Необязательное продуктовое исследование — входной контекст, не источник требований template: research.md instruction: | Владелец: product-researcher. Условный, пишется до proposal: research — вход Proposal, поэтому создаётся раньше `proposal.md`, а не по Change Profile (Profile появляется позже и лишь фиксирует факт: `yes` — `analysis/research.md` есть в change, `no` — ссылка на внешний источник или причина). Не требуется ни одним артефактом и не блокирует apply. В gates не входит: это контекст, не утверждаемый артефакт. Trigger: новый продуктовый функционал, незнакомая предметная область, конкуренты и альтернативы, проверка гипотезы, высокая продуктовая неопределённость. Исследование уже есть вне change (Issue, `audit-results/`, отчёт) — не копируй, Proposal ссылается на источник. Research понадобился после G1 (новая неопределённость) — это Open Decision в Proposal: research дописывается, Proposal обновляется, G1 инвалидируется. Правила: - Каждое утверждение помечено: [F] факт с источником, [I] интерпретация, [H] гипотеза. - Не выдумывай источники, цифры и пользователей; нет данных — так и напиши. - Рекомендация допускает «не делать» и «сузить scope». Не включай: окончательные requirements, обязательные архитектурные решения, контракты, tasks. Обратная связь: выводы потребляет Proposal (Evidence, Scope, Open Decisions). requires: [] - id: process-record generates: process-record.md description: Change Profile, решения gates, снятая работа и lab-журнал change template: process-record.md instruction: | Владелец: основной агент (оркестратор). Change Profile утверждает Change Owner на G1. Это журнал процесса, а не planning authority: requirements, контрактов и design здесь нет. ## Общий протокол lab schema (действует на каждой стадии) Режимы и классы: - **Mode** `lab` — целенаправленная практика: G2 обязателен, independent review на каждом gate, Lab Journal после каждой стадии, Retrospective перед archive; условные артефакты можно выбирать ради названной практики. - **Mode** `delivery` — минимально достаточный процесс: артефакты только по risk-trigger, qa-analysis компактный, Lab Journal необязателен. - **Class** `standard` | `complex`. Complex: межсистемно, деньги/синхронизация/ данные, необратимые миграции или высокая неопределённость. Mode и Class независимы. Шаблоны: 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»). - `no` — с конкретной причиной. Пустой документ с «N/A» вместо `no` запрещён. - Profile меняется только решением Change Owner: строка текущего gate (G1–G3) со Scope `change-profile`; все последующие gates при этом инвалидируются. - Выбранный условный вход пишется раньше потребителя: research — до proposal; ux-design, system-analysis, data-mapping, failure-model, nfr, observability, security-analysis — до design, qa-analysis и tasks; test-cases, docs-impact — до tasks. Граница контроля: - CLI проверяет только существование файлов и структуру delta specs. Profile, порядок, gates и готовность — Readiness Checklist ниже: его проходит основной агент, independent reviewer gate перепроверяет. Скриптов у schema нет. - Checklist — не approval и не замена review: он ловит форму, смысл — reviewer. - Результат checklist пишется в колонку Validation Gate Log (`readiness: plan OK` | `readiness: apply OK` | список нарушений). Следующий артефакт: - `openspec status` показывает невыбранные условные артефакты как `ready`, а `isPlanningComplete` остаётся `false`, пока они не созданы. Это ограничение CLI: не создавай артефакт только потому, что он `ready`. - Следующий артефакт — первый ещё не созданный и разрешённый последним approved gate в порядке: proposal → process-record → specs → выбранные ux-design / system-analysis и модули / security-analysis → design ∥ qa-analysis → выбранные test-cases / docs-impact → tasks. Decision Gates (Gate Log, только дописывание): | Gate | Scope | Когда | | --- | --- | --- | | G1 Product Decision | proposal, change-profile | всегда | | G2 Requirements Baseline | specs (+ system-analysis и модули для complex) | lab или complex | | G3 Solution Approval | остальное planning, включая tasks | всегда | | G4 Delivery Acceptance | implementation, review, QA, parity, docs | перед archive | - Без G2 (delivery standard) specs входят в Scope G3. - Complex: выбранные system-analysis, data-mapping, failure-model, nfr, observability входят в G2, чтобы системные обязательства были согласованы до design (contract-first). Hub не обязателен: утверждается только выбранное. - Каждый артефакт утверждается только на своём gate: proposal — G1; change-profile — G1 (позднее изменение — G2/G3); specs — G2 (без G2 — G3); system-analysis и модули — G2 для complex, иначе G3 (или G2, если он есть); остальное planning — G3. Approval на чужом gate не засчитывается. Scope G1–G3 содержит только эти ids; неизвестный id — ошибка записи. Scope G4 — implementation, review, QA, parity, docs. - Решение gate явно разрешает черновик следующего пакета артефактов. Approval перечисляет каждый id в Scope и дословно цитирует слова Change Owner из текущей сессии или комментария Issue (со ссылкой). Никогда не записывай решение, которого владелец не давал; существование файла или строки Gate Log — не approval. - Состояние gate = его ПОСЛЕДНЯЯ строка в Gate Log. `rejected`, `changes requested` и `invalidated: <причина>` снимают approval этого gate и всех последующих; новое approval — по порядку. Прежний approved выше в журнале не действует. - Каждый gate разделяет: Artifact Validation (CLI + Readiness Checklist), Independent Review (findings) и Decision Approval (владелец). Validation и Findings заполняются до запроса решения. - Смысловое изменение утверждённого артефакта: строка `invalidated: <причина>` для gate, покрывающего самый ранний затронутый артефакт (снимает и все последующие), затем повторное approval по порядку. Механические правки (опечатка, формат) не инвалидируют. - Release Approval — вне OpenSpec (release-it, Gitea); G4 его не заменяет. Readiness Checklist (проходи целиком; любой пункт «нет» — нарушение): plan — после каждого артефакта: - [ ] `**Mode:**` = lab|delivery, `**Class:**` = standard|complex, Issue указан. - [ ] Change Profile: ровно 10 строк, Selected = yes|no, Reason непустой; `yes` в delivery называет trigger, в lab — trigger или практику. - [ ] Нет файлов невыбранных условных артефактов; `skip_specs: true` ⇔ нет `specs/`. - [ ] Каждый выбранный условный вход существует раньше потребителя (см. Change Profile). - [ ] В артефактах, предъявляемых на gate, нет HTML-комментариев шаблона. - [ ] Каждая ссылка `` `capability` — `Requirement` `` указывает на heading из delta или canonical spec; после RENAMED — только на новое имя. - [ ] Gate Log: артефакт засчитан только на своём gate; в Scope нет неизвестных ids; Scope G1 включает `change-profile`; состояние gate — по последней строке; каждое 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-контракты синтаксически валидны. apply — plan плюс: - [ ] Существуют proposal, process-record, specs (или `skip_specs: true`), design, qa-analysis, tasks и все выбранные условные артефакты. - [ ] Текущее состояние approved: G1; G2 (lab или complex); G3. Каждый существующий артефакт (кроме research и process-record) входит в approved Scope. - [ ] С момента approval нет смысловых правок утверждённых артефактов без `invalidated`. - [ ] Каждый ADDED/MODIFIED/REMOVED Requirement имеет строку в Coverage Matrix qa-analysis и хотя бы одну task с ним в Covers. Упоминание вне матрицы и Covers — не покрытие. REMOVED покрывается проверкой миграции/регрессии. - [ ] В tasks есть Independent Review; Contract Parity при наличии `analysis/contracts/`; раздел `## Docs Impact` в tasks.md, если docs-impact `no`. - [ ] Descoped Work: каждая строка с причиной и gate G3/G4. archive — apply плюс: - [ ] Все tasks `[x]` или перенесены в Descoped Work. - [ ] Состояние G4 — approved; Validation G4 содержит verify, review, QA, parity (если есть контракты), docs. - [ ] Lab: Retrospective заполнена. Independent Review (lab — на каждом gate; delivery — минимум G4): - G1: product-analyst ищет в проблеме и scope противоречия и скрытые решения. - G2: qa-engineer — тестируемость; independent-reviewer — оба прохода Review из spec-writing.md для delta и итогового набора с canonical specs. - G3: independent-reviewer — согласованность specs ↔ analysis ↔ design ↔ qa-analysis ↔ tasks; без G2 также профиль Specs; security-reviewer, если выбран security-analysis. - G4: independent-reviewer — код против утверждённых артефактов; qa-engineer — системная проверка по qa-analysis. - Reviewer не исправляет артефакт; findings идут по правилам обратной связи. Делегирование сабагентам: - Сабагент — самостоятельный профессионал: не знает OpenSpec, gates и других сабагентов. Основной агент выбирает роль, пишет Task Brief, получает результат, размещает его в артефакте, проверяет согласованность и выносит вопросы человеку. - Task Brief: профессиональная цель («спроектируй межсистемные взаимодействия для …», а не «создай artifact system-analysis»); точные входные файлы и разделы; ограничения из «Не включай» артефакта, сформулированные профессионально; ожидаемые разделы ответа; правило «неизвестное — вернуть вопросом, не выдумывать». - Сабагент не принимает решений за другие роли; конфликт с upstream возвращается как finding. Lab Journal (lab): строка после каждой стадии — уникальные находки (что нашла только эта стадия), решения, риски, проблемы передачи контекста, skills, стоимость (вызовы, токены/время), что переносимо на крупные проекты. Не пиши ожидаемые результаты заранее. requires: - proposal - id: specs generates: "specs/**/*.md" description: Нормативные black-box дельты поведения, бизнес-правила и инварианты template: spec.md instruction: | Владелец: product-analyst (requirements engineering). Gate: G2 (lab/complex) или G3. Reviewers: qa-engineer (тестируемость), independent-reviewer (согласованность). Назначение: Delta Specs — нормативный black-box контракт: что система обязана делать для пользователя или внешнего наблюдателя. После archive становятся canonical specs. Предусловия: - G1 approved; используются только capabilities из Proposal. - Для существующей capability прочитай canonical spec целиком. - `skip_specs: true` — spec-файлы не создаются. - Прочитай `openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md`: это единый профиль написания и ревью, включая эталоны, а не необязательные советы. Правила: - Путь дельты — `specs//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, а не только в исследовании или примере. - Бизнес-правила, инварианты (сохранение суммы, однократный учёт денег, знак и точка округления), единицы и существенные границы — явные нормы и Scenarios. Для ветвлений/жизненного цикла используй таблицы по профилю, без дублирования правил прозой. Неизвестные пороги и политики не выдумывай. - Допущение не оформляется как факт: неизвестное правило → вопрос в Open Decisions Proposal с владельцем и зависимым требованием; зависимый gate ждёт решения. Наблюдение в коде не подменяет согласованное намерение. - Не дели Requirements по repositories; имена систем/транспорт/endpoints — в system-analysis, если сама их identity не внешнее обязательство. Delta-операции: - `ADDED`; `MODIFIED` — ПОЛНЫЙ существующий блок со всеми scenarios, heading точно; `REMOVED` — **Reason** и **Migration**; `RENAMED` — `FROM:`/`TO:`. - Новая capability: `## Purpose` 1–2 предложения (≥50 символов). - Не оставляй пустые разделы операций. Формат ссылки (для всех downstream артефактов и Readiness Checklist): `` `capability-path` — `Requirement heading` `` — heading точно. Пример: `` `portfolio/holdings` — `Итог портфеля не учитывает дубли операций` ``. Переименование heading после G2 — это RENAMED + invalidation; ссылки обновляются. Не включай: детали реализации, поведение вне Proposal, «корректно»/«быстро»/ «удобно» без критерия, противоречия canonical specs. Обратная связь: намерение/scope/capabilities → Proposal; системы/контракты/ mappings → system-analysis; детали взаимодействия → ux-design. Проверка: `openspec validate --strict --store wealth-ledger-specs`, затем оба прохода Review из spec-writing.md. Успех CLI не доказывает полноту смысла; проверяй delta вместе с получающимся canonical набором. requires: - process-record - id: ux-design generates: analysis/ux-design.md description: Необязательный interaction design утверждённого поведения; часть Design package template: ux-design.md instruction: | Владелец: ux-designer. Условный: только если Change Profile выбрал `ux-design`. Gate: G3 вместе с design (единый Design package, отдельного UX approval нет). Trigger: новые экраны, существенное изменение пользовательского сценария, редизайн, сложные формы, многосостоянийный интерфейс. Иначе UI описывается в разделе UI Implementation `design.md` (reuse или N/A с причиной). Полномочия: - ux-design — UX-часть единого Design package (не отдельный approval): внутри пакета он один владеет flows, IA, состояниями, feedback, responsive и a11y. design.md ссылается на него и фиксирует только инженерную реализацию UI. - Observable behavior остаётся в Specs; UX не вводит новое поведение. Состояние или ошибка, которых нет в Specs, — finding → Specs. Правила: - Ссылайся на Requirements, не пересказывай их. - UI States — loading/empty/error/success/partial только там, где они реально возможны. - Визуальные материалы — по правилу Visual Package из instruction `design`. - Используй существующую design system (`docs/design/`, UI kit `frontend`) прежде нового паттерна; отклонение обоснуй. Не включай: серверную архитектуру, контракты, дерево компонентов, state management, data fetching. Обратная связь: поведение → Specs; реализуемость → design; данные/ошибки интеграции → system-analysis. requires: - specs - id: system-analysis generates: analysis/system-analysis.md description: Необязательный hub межсистемного контекста — границы, flows, владение данными, контракты template: system-analysis.md instruction: | Владелец: system-analyst. Условный: только если Change Profile выбрал `system-analysis`. Gate: G2 для complex, иначе G3. Trigger: новый или изменённый межсистемный контракт (HTTP API, внешняя интеграция, event), изменение владения данными, несколько систем в одном flow, сложная миграция/coexistence. Изменение внутри одного repo без контракта — не trigger. Структура (hub + модули; каждый модуль — отдельный выбор Change Profile, hub для модуля не обязателен): - `analysis/system-analysis.md` — контекст, границы, As-Is/To-Be, impact, ответственности, владение данными, обзор flows, семантика контрактов и ошибок на границах, совместимость, ссылки на модули. - `analysis/contracts/` — машиночитаемые target-контракты (OpenAPI/AsyncAPI/ JSON Schema/Proto). Не отдельный артефакт: принадлежит hub. - `analysis/diagrams/*.mmd` — Mermaid sequence/state/data-flow, только если помогают понять поведение. Каждый файл упомянут в hub или модуле. - Модули: `data-mapping.md`, `failure-model.md`, `nfr.md`, `observability.md`. - Расширения (audit, fraud, feature toggles, CMS, внешние системы) — новым модулем только при реальном requirement; schema их не предопределяет. Полномочия контракта (из v2): - Новый или изменённый контракт определяется в `analysis/contracts/` до реализации. - Backend-generated OpenAPI остаётся исполняемым runtime-источником после реализации и MUST быть семантически совместим с утверждённым target-контрактом до G4. - Не создавай второй вечный canonical OpenAPI в `specs/`; target-контракт остаётся в архивном change. Расхождение generated ↔ target возвращает change сюда. - Для существующего HTTP API прочитай текущий backend-generated OpenAPI (`frontend/src/shared/api/spec/openapi.json` — опубликованный snapshot). - Каждый контракт помечает совместимость: additive | breaking (+ migration). Правила: - Не вводи observable behavior молча: пробел → Specs и повторный G2/G3. - Hub не копирует модули; модуль не копирует hub. - Нет внутренних классов/модулей/таблиц БД/developer tests. Обратная связь: поведение → Specs; внутренняя реализация → design; проверка → qa-analysis. requires: - specs - id: data-mapping generates: analysis/data-mapping.md description: Необязательный поле-в-поле mapping, преобразования и инварианты сохранения между системами template: data-mapping.md instruction: | Владелец: system-analyst; reviewer — database-specialist при изменении хранения. Условный: только если выбран `data-mapping`; hub не обязателен. Trigger: преобразование данных между системами или моделями (внешний API → domain, domain → API, агрегаты), денежные суммы, валюты, знаки, классификация записей по группам. Правила: - Каждое target-поле: источник, преобразование, unit/валюта/scale, nullability, default, валидация, поведение при ошибке. - Инварианты: правила сохранения (сумма частей = итог, каждая денежная единица учтена ровно в одном агрегате), знаки, точка округления — со ссылкой на защищаемый Requirement. Нет Requirement — finding → Specs. - Двойной учёт: каждый тип исходной записи, который может попасть в два агрегата, и правило, относящее его ровно к одному. - Большой mapping — машиночитаемый файл в `analysis/contracts/` со ссылкой отсюда. Не включай: ORM/SQL/код mappers, retry/idempotency (failure-model). Обратная связь: инвариант без Requirement → Specs; владение данными → hub; реализация → design. requires: - specs - id: failure-model generates: analysis/failure-model.md description: Необязательная семантика отказов на границах — таймауты, повторы, идемпотентность, частичный отказ, восстановление template: failure-model.md instruction: | Владелец: system-analyst; reviewer — reliability-specialist. Условный: только если выбран `failure-model`; hub не обязателен. Trigger: внешняя интеграция, фоновая синхронизация, повторяемые операции, многошаговая запись, возможны дубли/out-of-order/частичный отказ. Правила: - Каждый сценарий отказа: граница, отказ, обнаружение, требуемое поведение системы, observable результат, Requirement. - Идемпотентность: ключ, scope, срок хранения, результат повторного запроса/события. - Частичный отказ: что остаётся согласованным, компенсация или восстановление. - Обязательства формулируются на границе систем; механизм (lock, очередь, транзакция) — design. Не включай: численные SLO (nfr), выбор библиотек, код. Обратная связь: новое видимое пользователю поведение при отказе → Specs; механизм → design; проверка → qa-analysis. requires: - specs - id: nfr generates: analysis/nfr.md description: Необязательные измеримые нефункциональные требования с порогами и способом измерения template: nfr.md instruction: | Владелец: system-analyst; reviewer — reliability-specialist. Условный: только если выбран `nfr`; hub не обязателен. Trigger: значимые ограничения performance/availability/capacity/retention/security, которые меняют design или проверку. Правила: - Каждый NFR: id, порог, способ измерения, обоснование/источник. - Для численного порога определи единицы, условия/нагрузку, точки начала и конца измерения, окно или агрегат по необходимости. Контекст измерения нужен, чтобы разные авторы и QA проверяли одно обязательство. - Нет порога — раздел Constraints Without Thresholds с владельцем решения; числа не выдумывай. Если от порога зависит design или приёмка, вопрос блокирует соответствующий gate до решения. - Security-NFR живут здесь; security-analysis ссылается на них по id. Не включай: механизмы достижения (design), семантику отказов (failure-model), события наблюдаемости (observability). requires: - specs - id: observability generates: analysis/observability.md description: Необязательные обязательства наблюдаемости — события, сигналы, корреляция, SLI и алерты template: observability.md instruction: | Владелец: system-analyst; reviewer — reliability-specialist. Условный: только если выбран `observability`; hub не обязателен. Trigger: фоновые/асинхронные процессы, финансовые расчёты или синхронизация, где оператор должен различать успех, частичный успех и отказ; новые SLI. Правила: - Семантические события с trigger и обязательными атрибутами (например, `code=1 → NO_MONEY`); корреляция через границы систем. - Диагностические сценарии: «когда X, оператор определяет Y по Z». - SLI/алерты — только с определением и целевым значением; цель из nfr — ссылкой. Не включай: SDK/exporter/logger/инфраструктуру (design), секреты и персональные данные в атрибутах. requires: - specs - id: security-analysis generates: analysis/security-analysis.md description: Необязательная threat model этого change — mitigations и остаточные риски template: security-analysis.md instruction: | Владелец: security-reviewer. Условный: только если выбран `security-analysis`. Gate: G3; требования к проверке исполняются на G4. Trigger: authentication/authorization, токены и секреты, новая trust boundary, чувствительные/финансовые персональные данные, внешняя интеграция, изменение модели доступа. Без этих признаков не создавай. Входы: Specs; system-analysis и nfr, если выбраны; существующие ADR и `docs/architecture/cross-cutting/`. Правила: - Threat model только этого change (STRIDE — способ поиска, не чек-лист). - Каждая mitigation назначена владельцу: observable требование → Specs, межсистемное обязательство → system-analysis, механизм → design. - Security-NFR не дублируй: ссылайся на id из `nfr.md`. - Остаточные риски явно принимает Change Owner на G3. Не включай: универсальный security checklist, эксплуатацию внешних систем, секреты. requires: - specs - id: design generates: design.md description: Инженерный design — как affected repositories реализуют утверждённое поведение и системные обязательства template: design.md instruction: | Владелец: solution-architect; reviewers — affected frontend/backend engineers, database-specialist при миграциях. Gate: G3. Назначение: Как affected repositories реализуют свою сторону утверждённых Specs и выбранных analysis-артефактов. Это не повторный system analysis. Предусловия: - Все выбранные условные входы из `analysis/` уже существуют (Readiness Checklist `plan` без нарушений). Complex: выбранные system-analysis и модули утверждены на G2. - Протокол (gates, checklist, обратная связь) — instruction `process-record`; Change Profile в `process-record.md` определяет, какие входы читать. - Upstream контракты/sequences/mappings — входные ограничения. Глубина: - Delivery standard: Inputs, Implementation Impact Map, Decisions и Risks / Trade-offs обязательны; остальные разделы — только при наличии содержания (Solution Assessment и Rollback — по их trigger ниже); пустые удаляй, не пиши N/A. - Lab или complex: все разделы шаблона; N/A — с причиной в одну строку. Правила: - Не добавляй observable behavior и не меняй системные контракты. Нереализуемый контракт → system-analysis, а не private-контракт здесь. - Каждое существенное решение ссылается на driver: Requirement, id NFR, failure, threat или ограничение. Новая технология/компонент без driver запрещены. - UI: при ux-design — только инженерная реализация (композиция, state, data fetching, как получается каждое UI-состояние); без ux-design — раздел UI Implementation: new/changed/reuse/N/A с причиной и нужные экраны/состояния. Неизменяемый UI и N/A макетов не требуют. - Visual Package (единое правило для ux-design и UI Implementation): версия пакета; для reuse — неизменяемый locator (store ID + path от OpenSpec root), применимая часть и отличия; локальные PNG/SVG в `visuals/` с относительным путём, назначением и SHA-256; SVG самодостаточен (без scripts, handlers, внешних шрифтов/ресурсов); изменяемая внешняя ссылка не является утверждённой версией. ux-design и design — один Design package с одним approval на G3. - Solution Assessment обязателен для нового auth, security, storage, внешней интеграции, observability, кеширования, конкурентности, общего tooling или иного дорогого необратимого решения; иначе N/A + причина. - Rollback обязателен для security, разрушающей миграции, публичного контракта и труднообратимых решений. - Developer verification определяют implementation owners; QA-матрицу не копируй. - ADR Candidates: только долгоживущие архитектурные решения с альтернативами. Не включай: утверждённые sequences/контракты/mappings (ссылки, не копии); UX flows/ состояния при наличии ux-design; QA-покрытие; план docs; tasks/план PR; длинный production-код. Обратная связь: намерение → Proposal; поведение → Specs; взаимодействие → ux-design; контракты/mappings/отказы/наблюдаемость → system-analysis и модули; угрозы → security-analysis. requires: - specs - id: qa-analysis generates: analysis/qa-analysis.md description: Risk-based стратегия системной проверки, независимая от developer tests template: qa-analysis.md instruction: | Владелец: qa-engineer. Gate: G3. Может выполняться параллельно с design. Назначение: Что проверить на уровне системы, чтобы доказать соответствие Specs и выбранным analysis-модулям, и с какой глубиной — по риску. Прочитай `openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md`: ожидаемый исход берётся из нормы, а не из догадки QA или фактического поведения реализации. Глубина (условные разделы внутри обязательного артефакта): - Всегда: Risk Assessment, Coverage Matrix (строка на каждый ADDED/MODIFIED/REMOVED Requirement с указанием Scenarios/ветвей правила и способа проверки), Gaps / Blockers. При `skip_specs: true` матрица фиксирует существующее поведение или согласованное ограничение для регрессии и его источник, без выдуманных дельт. - Delivery standard: остальные разделы — только при наличии содержания; пустые удаляй, не пиши N/A. - Lab или complex: все разделы; Cross-system Verification обязателен при выбранных system-analysis, failure-model или data-mapping (каждый failure id и инвариант имеет проверку или обоснованный risk-based отказ). Правила: - QA проверяет поведение системы, не устройство кода; не предписывай unit/component tests, mocks, процент покрытия. - Не создавай поведение: неопределённый ожидаемый результат → пробел в Specs; неопределённый flow/ошибка/контракт → пробел в system-analysis. - Ссылайся на Scenarios, не переписывай их. Отдельные test cases — только через артефакт `test-cases`. - По риску проверь существенные границы, строки таблиц, переходы, повторы, конкуренцию и отсутствие запрещённых побочных эффектов. Пропуск проверки — явное `not verified: <риск-причина>` для названного случая в матрице, не молчание. - Планы проверок отделены от результатов: результаты фиксируются на G4. - Automation: black-box кандидаты API/E2E; QA repo пока нет — `deferred until QA repo exists`. Обратная связь: поведение → Specs; контракты/отказы → system-analysis; testability hooks → design (как потребность, без проектирования). requires: - specs - id: test-cases generates: "analysis/test-cases/*.md" description: Необязательный явный test design для рискованных сценариев, которым нужны конкретные данные, шаги или oracle template: test-cases.md instruction: | Владелец: qa-engineer. Условный: только если выбран `test-cases`. Gate: G3. Trigger: финансовые расчёты, сложные бизнес-сценарии, значимые интеграции, много ошибок и граничных случаев, критичное пользовательское поведение — когда проверке нужны конкретные данные, шаги или oracle, которых нет в Scenario. Правила: - Один файл на область: `analysis/test-cases/.md`; id `TC--` уникален. - Каждый case: Verifies (формат ссылки), риск/приоритет, предусловия, тестовые данные, шаги, ожидаемый результат, кандидат в автоматизацию. - Case добавляет информацию сверх Scenario (числа, комбинации, порядок событий, расчётный oracle). Не добавляет — не пиши case; Coverage Matrix ссылается на Scenario. - Не копируй acceptance criteria дословно; ожидаемый результат выводится из Requirement, а не придумывается. Неопределённость → пробел в Specs. - Coverage Matrix qa-analysis ссылается на TC ids. requires: - qa-analysis - id: docs-impact generates: analysis/docs-impact.md description: Необязательный план переноса знаний change в canonical AS-IS документацию template: docs-impact.md instruction: | Владелец: documentation-engineer. Условный: только если выбран `docs-impact`. Gate: G3. Trigger: несколько docs targets, новый ADR, перенос диаграмм, изменение страниц architecture/integration, lab-практика Documentation Impact Analysis. Иначе — раздел `## Docs Impact` в tasks.md (targets или конкретная причина без изменений). Модель документации: `docs/` — AS-IS (`overview.md`, `glossary.md`, `architecture/`, `architecture/cross-cutting/`, `domains/`, `integrations/`, `adr/`, `design/`). Принятый ADR не переписывается. Правила: - Переносится только знание, полезное после завершения change; без дневника миграции. - Не копируй машиночитаемый контракт в docs вторым источником истины. - Каждая запись: Action, точный Target (существующий path проверен), Category, итоговое AS-IS, Source, Verification. - Перенос диаграмм по умолчанию — нет. - docs-impact не редактирует `docs/`; tasks создают пункты `[docs]`. requires: - design - id: tasks generates: tasks.md description: Упорядоченный по зависимостям delivery checklist по repositories с проверками, review и parity template: tasks.md instruction: | Владелец: основной агент (координация delivery); reviewers — affected engineers. Gate: G3. Предусловия: - design и qa-analysis существуют; все выбранные условные артефакты существуют (Readiness Checklist `plan` без нарушений). - Для complex/lab: G2 approved до записи tasks. - Протокол (gates, checklist, Descoped Work) — instruction `process-record`. Формат task: `- [ ] X.Y [main|frontend|backend|docs|specs] : <действие + результат>` с полями **Covers**, **Source**, **Verification**, **Depends on**. Kinds: Implementation, Migration, Automated Testing, Contract Parity, Docs, Independent Review, QA Verification, Verification. Обязательные tasks (только релевантные; отмеченные * проверяет Readiness Checklist): - Implementation/Automated Testing по каждому repository согласно design. - Migration: при изменении хранения — backup/rollback и проверка на копии данных. - * Contract Parity: при наличии `analysis/contracts/` — сравнение backend-generated OpenAPI/runtime с target-контрактом. - Docs: из docs-impact или раздела `## Docs Impact`. - * Independent Review: read-only review реализации против утверждённых артефактов. - QA Verification: системные проверки по qa-analysis (и test-cases). - Security: проверки из Validation Requirements security-analysis, если выбран. - Native sync/archive — не task; canonical specs задачами не правятся. Правила: - Одна task = один repository + один независимо проверяемый результат. - * Каждый ADDED/MODIFIED/REMOVED Requirement есть в Covers хотя бы одной task (REMOVED — task миграции/регрессии). - Covers в формате ссылки; неизвестный heading — нарушение checklist. - У каждой task все четыре поля; Verification — наблюдаемая команда или результат, а не «проверить, что работает». - `[qa]` запрещён, пока QA repo не существует. - Не создавай церемониальные tasks; нерелевантный Kind не нужен. - Снятие после G3: удали task из tasks.md и запиши в `Descoped Work` process-record с причиной и gate решения владельца. Не включай: новое поведение/контракт/design/QA/docs-решение (→ upstream артефакт), commits/branches, будущие результаты. Обратная связь: смысловое изменение → самый ранний затронутый артефакт с инвалидацией его gate и последующих. requires: - design - qa-analysis apply: requires: - tasks tracks: tasks.md instruction: | Apply реализует утверждённый план и не переоткрывает upstream-решения без цикла обратной связи. Предусловия (CLI проверяет только наличие tasks.md, остальное — вручную): - Readiness Checklist `apply` (instruction `process-record`) пройден целиком и записан в Validation последней строки G3; любое нарушение блокирует apply. Главное: все обязательные и выбранные артефакты существуют; текущее состояние G1, G2 (lab/complex), G3 — approved по последней строке. - Перед зависимой UI-работой проверь наличие и SHA-256 материалов из таблицы Materials (ux-design или UI Implementation в design). - Store `wealth-ledger-specs`; протокол — instruction `process-record`. Загрузка контекста: `contextFiles` из apply instructions, затем `AGENTS.md` только affected repositories, затем нужные upstream-разделы для каждой task. Выполнение: - Незакрытые tasks — в порядке зависимостей; один repository на task; делегируй по роли (frontend-engineer, backend-engineer, database-specialist) с Task Brief. - Checkbox отмечается только после наблюдаемого успеха Verification. - Contract Parity: backend-generated OpenAPI семантически совместим с target-контрактом. - Independent Review выполняет independent-reviewer (read-only) по полному diff против утверждённых артефактов; Major findings исправляются или возвращаются в gate. - QA Verification выполняет qa-engineer по qa-analysis; результаты — в Gate Log G4. - Lab: строка Lab Journal после implementation, review и QA. - Снятие task — только решением владельца с записью в Descoped Work. Перед archive (G4 Delivery Acceptance): - Все tasks `[x]`; снятые — только через `Descoped Work`. - Validation G4: developer checks, parity, вердикт review, результаты QA, docs. - Lab: Retrospective заполнена. - Readiness Checklist `archive` пройден и записан в Validation G4, затем `openspec archive --store wealth-ledger-specs`. Никогда `--no-validate`. `--yes` подавляет и подтверждение обновления specs, и предупреждение о незакрытых tasks, поэтому допустим только сразу после пройденного checklist `archive` (в non-TTY агентской среде без него archive не выполняется). Семантика sync/archive: native archive обновляет canonical specs; `analysis/`, контракты и process-record остаются в архивном change; `docs/` меняются только tasks `[docs]`; значимые решения — неизменяемый ADR. Обратная связь: - намерение/scope → Proposal; поведение/инварианты → Specs; взаимодействие → ux-design; системы/контракты/mappings/отказы/NFR/наблюдаемость → system-analysis и модули; угрозы → security-analysis; внутренняя реализация → design; проверка → qa-analysis/test-cases; docs → docs-impact; декомпозиция → tasks. - При смысловом конфликте останови downstream-работу, приложи evidence, инвалидируй gates начиная с самого раннего затронутого артефакта.