672 lines
44 KiB
YAML
672 lines
44 KiB
YAML
name: wealth-ledger-sdd-lab
|
||
version: 1
|
||
description: Experimental Engineering Lab workflow - proposal + change profile → specs → selected analysis modules → design ∥ qa-analysis → tasks → apply, with 4 decision gates
|
||
|
||
# CLI contract (OpenSpec 1.13.1): an artifact is complete when its `generates` path exists;
|
||
# `requires` is a hard edge; there is no conditional artifact. Conditional artifacts below are
|
||
# therefore never required by a mandatory artifact or by apply. Selection, ordering of selected
|
||
# artifacts, gates and archive readiness are checked by `check.cjs` in this schema directory.
|
||
|
||
artifacts:
|
||
- id: proposal
|
||
generates: proposal.md
|
||
description: Change Owner intent, scope, capabilities, evidence and open decisions
|
||
template: proposal.md
|
||
instruction: |
|
||
Owner: Change Owner; draft — product-analyst. Gate: G1 Product Decision.
|
||
|
||
Purpose:
|
||
Proposal фиксирует, зачем нужно изменение, какой результат ожидается, где
|
||
проходит scope и какие решения ещё не приняты. Это не requirements, не system
|
||
analysis и не design.
|
||
|
||
Start of the lab lifecycle (обязательно до записи):
|
||
- Change создаётся явно: `openspec new change <name> --schema wealth-ledger-sdd-lab
|
||
--store wealth-ledger-specs`. Schema не становится default и не применяется к
|
||
существующим changes.
|
||
- Small (локальный fix, известное behavior) не идёт в OpenSpec: правка canonical spec
|
||
в том же Issue. Lab schema принимает только Standard и Complex.
|
||
- Если существует research (`research.md` в change, Issue, внешний отчёт), прочитай
|
||
его выводы; Proposal ссылается на research в **Evidence**, а не копирует его.
|
||
Research может закончиться решением не делать change — тогда change не создаётся.
|
||
- Общий протокол (Change Profile, gates, делегирование сабагентам, `check.cjs`) —
|
||
instruction artifact `process-record`; он действует на каждой стадии.
|
||
|
||
Read First:
|
||
- Релевантные canonical specs из `specs/openspec/specs/` и AS-IS pages `docs/`
|
||
(`overview.md`, `architecture/`, `domains/`, `integrations/`, `adr/`, `design/`).
|
||
- Code-level реализацию не исследуй глубже, чем нужно для scope/impact.
|
||
|
||
Critical Rules:
|
||
- Один Proposal = одно связное намерение; независимо поставляемое разделяй.
|
||
- Capabilities перечисляют каждую новую/изменяемую behavior spec точным path.
|
||
Если observable behavior не меняется — `.openspec.yaml: skip_specs: true`.
|
||
- Breaking observable behavior помечай **BREAKING**.
|
||
- Evidence разделяет факты (с источником) и гипотезы.
|
||
- Open Decisions: вопрос, кто решает, что блокирует. Вопрос, меняющий scope или
|
||
capabilities, решается до G1.
|
||
|
||
MUST NOT Include:
|
||
- files/classes/functions/tables/ORM entities; libraries/frameworks/transport;
|
||
endpoint/payload/error-code contracts; diagrams; test plans; tasks/PR plan;
|
||
пиксельные UI-детали.
|
||
|
||
Feedback Routing: research gap → research; всё остальное возвращается сюда.
|
||
|
||
Validation:
|
||
- `openspec validate <change> --store wealth-ledger-specs` (Why/What Changes);
|
||
structural success не является approval.
|
||
- Затем создай `process-record.md` (Change Profile) и предъяви G1 оба файла вместе.
|
||
requires: []
|
||
|
||
- id: research
|
||
generates: research.md
|
||
description: Optional product research used as input context; never approved as a requirement source
|
||
template: research.md
|
||
instruction: |
|
||
Owner: product-researcher. Conditional: создавай только если Change Profile выбрал
|
||
`research`. Не требуется ни одним artifact и не блокирует apply. Не входит в gates:
|
||
это входной контекст, не утверждаемый artifact.
|
||
|
||
Trigger: новый продуктовый функционал, незнакомая предметная область, конкуренты и
|
||
альтернативы, проверка гипотезы, высокая продуктовая неопределённость.
|
||
Если исследование уже существует вне change (Issue, `audit-results/`, отчёт),
|
||
не копируй его: Proposal ссылается на источник, Change Profile ставит `no` + ссылку.
|
||
Исследование, начатое до решения о change, живёт вне OpenSpec до G1.
|
||
|
||
Critical Rules:
|
||
- Каждое утверждение: [F] факт с источником, [I] интерпретация или [H] гипотеза.
|
||
- Не выдумывай источники, цифры и пользователей; нет данных — так и напиши.
|
||
- Recommendation допускает «не делать» и «сузить scope».
|
||
|
||
MUST NOT Include: окончательные requirements, обязательные архитектурные решения,
|
||
contracts, tasks.
|
||
|
||
Feedback Routing: выводы потребляет Proposal (Evidence, Scope, Open Decisions).
|
||
requires: []
|
||
|
||
- id: process-record
|
||
generates: process-record.md
|
||
description: Change Profile, gate decisions, descoped work and lab journal for the change
|
||
template: process-record.md
|
||
instruction: |
|
||
Owner: основной агент (оркестратор). Change Profile утверждает Change Owner на G1.
|
||
Это журнал процесса, а не planning authority: он не содержит requirements,
|
||
contracts или design.
|
||
|
||
## Общий протокол lab schema (действует на каждой стадии)
|
||
|
||
Modes and Classes:
|
||
- **Mode** `lab` — целенаправленная практика: G2 обязателен, независимая проверка
|
||
на каждом gate, Lab Journal после каждой стадии, Retrospective перед archive,
|
||
условные artifacts можно выбирать ради названной практики.
|
||
- **Mode** `delivery` — минимально достаточный процесс: artifacts только по
|
||
risk-триггеру, qa-analysis компактный, Lab Journal необязателен.
|
||
- **Class** `standard` | `complex`. Complex: межсистемно, деньги/синхронизация/
|
||
данные, необратимые миграции или высокая неопределённость. Mode и Class
|
||
независимы.
|
||
|
||
Change Profile (обязательная таблица, все 10 строк):
|
||
- `yes` только при конкретном trigger из instruction artifact; в lab допустим
|
||
`yes` с названной практикой («lab: data mapping practice»).
|
||
- `no` с конкретной причиной. Пустой документ с «N/A» вместо `no` запрещён.
|
||
- Profile меняется только решением Change Owner, записанным строкой Gate Log
|
||
со scope `change-profile`; уже утверждённые gates при этом инвалидируются.
|
||
- Выбранный условный input пишется до artifact, который его потребляет
|
||
(research, ux-design, system-analysis и modules, security-analysis — до design,
|
||
qa-analysis и tasks; test-cases, docs-impact — до tasks).
|
||
|
||
Deterministic checks — `check.cjs` (из `specs/`):
|
||
`node openspec/schemas/wealth-ledger-sdd-lab/check.cjs <plan|apply|archive> <change>`.
|
||
Он единственный владелец правил profile/порядка/gates/readiness; не дублируй их
|
||
проверку вручную, а читай его вывод. `plan` — после каждого artifact; `apply` —
|
||
перед apply; `archive` — перед native archive. Exit 1 = нарушение artifact,
|
||
exit 2 = ошибка вызова/окружения (не исправляй artifact из-за неё).
|
||
|
||
Next artifact:
|
||
- `openspec status` показывает невыбранные условные artifacts как `ready`, а
|
||
`isPlanningComplete` остаётся `false`, пока они не созданы. Это ограничение CLI:
|
||
не создавай artifact только потому, что он `ready`.
|
||
- Следующий artifact = `note: next artifact` из `check.cjs plan`.
|
||
|
||
Decision Gates (Gate Log, append-only):
|
||
| 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 и выбранные модули входят в G2, чтобы системные
|
||
обязательства были согласованы до design (contract-first).
|
||
- Решение gate явно разрешает draft следующего пакета artifacts. Approval
|
||
перечисляет каждый artifact id в Scope и дословно цитирует слова Change Owner
|
||
из текущей сессии или комментария Issue (укажи ссылку). Никогда не записывай
|
||
решение, которого владелец не давал; существование файла или строки Gate Log
|
||
не является approval — `check.cjs` проверяет только форму записи.
|
||
- Каждый gate различает: Artifact Validation (CLI + `check.cjs`), Independent
|
||
Review (findings) и Decision Approval (владелец). Validation и Findings
|
||
заполняются до запроса решения.
|
||
- Семантическое изменение утверждённого artifact: строка `invalidated: <reason>`
|
||
для gate, покрывающего самый ранний затронутый artifact (это снимает и все
|
||
последующие gates), затем повторное approval по порядку. Механические правки
|
||
(опечатка, формат) не инвалидируют.
|
||
- Release Approval находится вне OpenSpec (release-it, Gitea); G4 его не заменяет.
|
||
|
||
Independent Review (lab — на каждом gate; delivery — минимум G4):
|
||
- G1: product-analyst проверяет проблему/scope на противоречия и скрытые решения.
|
||
- G2: qa-engineer — testability; independent-reviewer — противоречия с canonical
|
||
specs и пропущенные error/boundary cases.
|
||
- G3: independent-reviewer — согласованность specs ↔ system-analysis ↔ design ↔
|
||
qa-analysis ↔ tasks; security-reviewer, если выбран security-analysis.
|
||
- G4: independent-reviewer — код против approved artifacts; qa-engineer — system
|
||
verification по qa-analysis.
|
||
- Reviewer не исправляет artifact; findings маршрутизируются по Feedback Routing.
|
||
|
||
Delegation to subagents:
|
||
- Сабагент — самостоятельный профессионал: не знает OpenSpec, gates и других
|
||
сабагентов. Основной агент выбирает роль, пишет Task Brief, получает результат,
|
||
размещает его в artifact, проверяет согласованность и выносит вопросы человеку.
|
||
- Task Brief: профессиональная цель («спроектируй межсистемные взаимодействия
|
||
для …», не «создай artifact system-analysis»); точные входные файлы/разделы;
|
||
ограничения из MUST NOT Include artifact, сформулированные профессионально;
|
||
ожидаемые разделы ответа; правило «неизвестное — вернуть вопросом, не
|
||
выдумывать».
|
||
- Сабагент не принимает решений за другие роли; конфликт с upstream возвращается
|
||
как finding.
|
||
|
||
Lab Journal (lab): строка после каждой стадии — уникальные находки (что нашла
|
||
только эта стадия), решения, риски, проблемы передачи контекста, skills, стоимость
|
||
(вызовы, токены/время), что переносимо на крупные проекты. Не пиши ожидаемые
|
||
результаты заранее.
|
||
requires:
|
||
- proposal
|
||
|
||
- id: specs
|
||
generates: "specs/**/*.md"
|
||
description: Normative black-box behavioral deltas, business rules and invariants
|
||
template: spec.md
|
||
instruction: |
|
||
Owner: product-analyst (requirements engineering). Gate: G2 (lab/complex) или G3.
|
||
Reviewers: qa-engineer (testability), independent-reviewer (consistency).
|
||
|
||
Purpose:
|
||
Delta Specs — нормативный black-box contract: что система обязана делать для
|
||
пользователя или внешнего наблюдателя. После archive становятся canonical specs.
|
||
|
||
Preconditions:
|
||
- G1 approved; используются только capabilities из Proposal.
|
||
- Для existing capability прочитай canonical spec целиком.
|
||
- `skip_specs: true` — spec files не создаются.
|
||
|
||
Critical Rules:
|
||
- Один Requirement = одно устойчивое observable behavior/invariant.
|
||
- BCP 14 по policy `config.yaml`: uppercase SHALL/MUST только для обязательств.
|
||
- Каждый Requirement имеет ≥1 `#### Scenario:` с конкретными WHEN/THEN.
|
||
- Бизнес-правила, инварианты (например, сохранение суммы, однократный учёт денег,
|
||
знак и точка округления) и граничные случаи — явные Requirements/Scenarios.
|
||
- Допущение не оформляется как факт: неизвестное правило → вопрос в Proposal
|
||
Open Decisions, а не выдуманный Requirement.
|
||
- Не дели Requirements по repositories; system names/transport/endpoints —
|
||
System Analysis, если сама их identity не является внешним обязательством.
|
||
|
||
Delta Operations:
|
||
- `ADDED`; `MODIFIED` — ПОЛНЫЙ existing block со всеми scenarios, heading точно;
|
||
`REMOVED` — **Reason** и **Migration**; `RENAMED` — `FROM:`/`TO:`.
|
||
- Новая capability: `## Purpose` 1–2 предложения (≥50 символов).
|
||
- Не оставляй пустые operation sections.
|
||
|
||
Reference Format (используется всеми downstream artifacts и `check.cjs`):
|
||
`` `capability-path` — `Requirement heading` `` — точный heading.
|
||
|
||
MUST NOT Include: implementation details, поведение вне Proposal, «корректно»/
|
||
«быстро»/«удобно» без критерия, противоречия canonical specs.
|
||
|
||
Feedback Routing: intent/scope/capabilities → Proposal; systems/contracts/
|
||
mappings → позже System Analysis; interaction details → UX Design.
|
||
|
||
Validation: `openspec validate <change> --strict --store wealth-ledger-specs`.
|
||
requires:
|
||
- process-record
|
||
|
||
- id: ux-design
|
||
generates: ux-design.md
|
||
description: Optional interaction design of approved behavior; part of the Design package
|
||
template: ux-design.md
|
||
instruction: |
|
||
Owner: ux-designer. Conditional: только если Change Profile выбрал `ux-design`.
|
||
Gate: G3 вместе с design (единый Design package, отдельного UX approval нет).
|
||
|
||
Trigger: новые экраны, существенное изменение пользовательского сценария,
|
||
редизайн, сложные формы, многосостоянийный интерфейс. Иначе UI описывается в
|
||
разделе UI Implementation `design.md` (reuse или N/A с причиной).
|
||
|
||
Authority:
|
||
- ux-design.md — UX-часть единого Design package (не отдельный planning
|
||
authority и не отдельный approval): внутри пакета он один владеет flows, IA,
|
||
состояниями, feedback, responsive и a11y. design.md ссылается на него и
|
||
фиксирует только инженерную реализацию UI.
|
||
- Observable behavior остаётся в Specs; UX не вводит новое behavior. Состояние или
|
||
ошибка, которых нет в Specs, — finding → Specs.
|
||
|
||
Critical Rules:
|
||
- Ссылайся на Requirements, не пересказывай их.
|
||
- UI States покрывает loading/empty/error/success/partial только там, где они
|
||
реально возможны.
|
||
- Visual materials следуют правилу Visual Package из instruction `design`.
|
||
- Используй существующую design system (`docs/design/`, `frontend` UI kit) прежде
|
||
нового паттерна; отклонение обоснуй.
|
||
|
||
MUST NOT Include: серверная архитектура, contracts, component tree, state
|
||
management, data fetching.
|
||
|
||
Feedback Routing: behavior → Specs; реализуемость → Design; данные/ошибки
|
||
интеграции → System Analysis.
|
||
requires:
|
||
- specs
|
||
|
||
- id: system-analysis
|
||
generates: system-analysis/system-analysis.md
|
||
description: Optional hub of cross-system context, boundaries, flows, data ownership and contracts
|
||
template: system-analysis.md
|
||
instruction: |
|
||
Owner: system-analyst. Conditional: только если Change Profile выбрал
|
||
`system-analysis`. Gate: G2 для complex, иначе G3.
|
||
|
||
Trigger: новый/изменённый межсистемный contract (HTTP API, внешняя интеграция,
|
||
event), изменение data ownership, несколько систем в одном flow, сложная
|
||
миграция/coexistence. Изменение внутри одного repo без contract — не trigger.
|
||
|
||
Structure (hub + modules; каждый module — отдельный выбор Change Profile):
|
||
- `system-analysis/system-analysis.md` — context, boundaries, As-Is/To-Be, impact,
|
||
responsibilities, data ownership, flows overview, contract semantics, error
|
||
semantics на границах, compatibility, ссылки на modules.
|
||
- `system-analysis/contracts/` — machine-readable target contracts
|
||
(OpenAPI/AsyncAPI/JSON Schema/Proto). Не отдельный artifact: принадлежит hub.
|
||
- `system-analysis/diagrams/*.mmd` — Mermaid sequence/state/data-flow, только
|
||
если помогают понять поведение. Каждый файл упоминается в hub или module.
|
||
- Modules: `data-mapping.md`, `failure-model.md`, `nfr.md`, `observability.md`.
|
||
- Расширения (audit, fraud, feature toggles, CMS, внешние системы) добавляются
|
||
новым module только при реальном requirement; schema их не предопределяет.
|
||
|
||
Contract Authority (сохранено из v2):
|
||
- Новый/изменённый contract определяется в `contracts/` до implementation.
|
||
- Backend-generated OpenAPI остаётся executable/runtime source после реализации
|
||
и MUST быть semantic-compatible с approved target contract до G4.
|
||
- Не создавай второй вечный canonical OpenAPI в `specs/`; target contract остаётся
|
||
в archived change. Mismatch generated ↔ target возвращает change сюда.
|
||
- Для existing HTTP API прочитай текущий backend-generated OpenAPI
|
||
(`frontend/src/shared/api/spec/openapi.json` — опубликованный snapshot).
|
||
- Каждый contract помечает compatibility: additive | breaking (+ migration).
|
||
|
||
Critical Rules:
|
||
- Не вводи observable behavior молча: gap → Specs и повторный G2/G3.
|
||
- Hub не копирует содержимое modules; module не копирует hub.
|
||
- Нет internal classes/modules/DB tables/developer tests.
|
||
|
||
Feedback Routing: behavior → Specs; internal implementation → Design;
|
||
verification → QA Analysis.
|
||
requires:
|
||
- specs
|
||
|
||
- id: data-mapping
|
||
generates: system-analysis/data-mapping.md
|
||
description: Optional field-level mapping, transformations and conservation invariants between systems
|
||
template: data-mapping.md
|
||
instruction: |
|
||
Owner: system-analyst; reviewer — database-specialist при изменении хранения.
|
||
Conditional: только если выбран `data-mapping` (требует `system-analysis`).
|
||
|
||
Trigger: преобразование данных между системами или моделями (внешний API →
|
||
domain, domain → API, агрегаты), денежные суммы, валюты, знаки, агрегаты,
|
||
классификация записей по группам.
|
||
|
||
Critical Rules:
|
||
- Каждое target-поле: source, transformation, unit/currency/scale, nullability,
|
||
default, validation, поведение при ошибке.
|
||
- Invariants: правила сохранения (сумма частей = итог, каждая денежная единица
|
||
учитывается ровно в одном агрегате), знаковые соглашения, точка округления —
|
||
со ссылкой на защищаемый Requirement. Нет Requirement — finding → Specs.
|
||
- Double-counting: каждый тип исходной записи, который может попасть в два
|
||
агрегата, и правило, относящее его ровно к одному.
|
||
- Большой mapping — machine-checkable файл в `contracts/` со ссылкой отсюда.
|
||
|
||
MUST NOT Include: ORM/SQL/код mappers, retry/idempotency (failure-model).
|
||
|
||
Feedback Routing: инвариант без Requirement → Specs; ownership → hub;
|
||
реализация → Design.
|
||
requires:
|
||
- system-analysis
|
||
|
||
- id: failure-model
|
||
generates: system-analysis/failure-model.md
|
||
description: Optional boundary failure semantics - timeouts, retries, idempotency, partial failure and recovery
|
||
template: failure-model.md
|
||
instruction: |
|
||
Owner: system-analyst; reviewer — reliability-specialist.
|
||
Conditional: только если выбран `failure-model` (требует `system-analysis`).
|
||
|
||
Trigger: внешняя интеграция, фоновая синхронизация, повторяемые операции,
|
||
многошаговая запись, возможны дубликаты/out-of-order/частичный отказ.
|
||
|
||
Critical Rules:
|
||
- Каждый failure scenario: граница, отказ, обнаружение, требуемое поведение
|
||
системы, observable результат, Requirement.
|
||
- Idempotency: ключ, scope, срок хранения, результат повторного запроса/события.
|
||
- Partial failure: что остаётся согласованным, compensation или recovery.
|
||
- Обязательства формулируются на границе систем; механизм (lock, queue,
|
||
transaction) — Design.
|
||
|
||
MUST NOT Include: численные SLO (nfr), выбор библиотек, код.
|
||
|
||
Feedback Routing: новое user-visible поведение при отказе → Specs; механизм →
|
||
Design; проверка → QA Analysis.
|
||
requires:
|
||
- system-analysis
|
||
|
||
- id: nfr
|
||
generates: system-analysis/nfr.md
|
||
description: Optional measurable non-functional requirements with thresholds and evidence
|
||
template: nfr.md
|
||
instruction: |
|
||
Owner: system-analyst; reviewer — reliability-specialist.
|
||
Conditional: только если выбран `nfr` (требует `system-analysis`).
|
||
|
||
Trigger: значимые performance/availability/capacity/retention/security
|
||
constraints, которые меняют design или verification.
|
||
|
||
Critical Rules:
|
||
- Каждый NFR: id, threshold, способ измерения, rationale/источник.
|
||
- Без threshold — раздел Constraints Without Thresholds с владельцем решения;
|
||
не выдумывай числа.
|
||
- Security-NFR живут здесь; security-analysis ссылается на них по id.
|
||
|
||
MUST NOT Include: механизмы достижения (Design), failure semantics
|
||
(failure-model), события наблюдаемости (observability).
|
||
requires:
|
||
- system-analysis
|
||
|
||
- id: observability
|
||
generates: system-analysis/observability.md
|
||
description: Optional semantic observability obligations - events, signals, correlation, SLI and alerts
|
||
template: observability.md
|
||
instruction: |
|
||
Owner: system-analyst; reviewer — reliability-specialist.
|
||
Conditional: только если выбран `observability` (требует `system-analysis`).
|
||
|
||
Trigger: фоновые/асинхронные процессы, финансовые расчёты или синхронизация,
|
||
где оператор должен отличать успех, частичный успех и отказ; новые SLI.
|
||
|
||
Critical Rules:
|
||
- Semantic events с trigger и обязательными атрибутами (например,
|
||
`code=1 → NO_MONEY`); correlation через границы систем.
|
||
- Diagnostic scenarios: «когда X, оператор определяет Y по Z».
|
||
- SLI/alerts — только с определением и целевым значением; цель из nfr — ссылкой.
|
||
|
||
MUST NOT Include: SDK/exporter/logger/инфраструктура (Design), секреты и
|
||
персональные данные в атрибутах.
|
||
requires:
|
||
- system-analysis
|
||
|
||
- id: security-analysis
|
||
generates: security-analysis.md
|
||
description: Optional change-scoped threat model with mitigations and residual risks
|
||
template: security-analysis.md
|
||
instruction: |
|
||
Owner: security-reviewer. Conditional: только если выбран `security-analysis`.
|
||
Gate: G3; validation requirements проверяются на G4.
|
||
|
||
Trigger: authentication/authorization, токены и секреты, новая trust boundary,
|
||
sensitive/financial personal data, внешняя интеграция, изменение модели доступа.
|
||
Не создавай для изменений без этих признаков.
|
||
|
||
Inputs: Specs; system-analysis (hub, nfr) если выбран; существующие ADR и
|
||
`docs/architecture/cross-cutting/`.
|
||
|
||
Critical Rules:
|
||
- Threat model только этого change (STRIDE как способ поиска, не как чек-лист).
|
||
- Каждая mitigation назначена artifact-владельцу: observable требование → Specs,
|
||
межсистемное обязательство → System Analysis, механизм → Design.
|
||
- Security-NFR не дублируй: ссылайся на id из `nfr.md`.
|
||
- Residual risks явно принимает Change Owner на G3.
|
||
|
||
MUST NOT Include: универсальный security checklist, эксплуатация внешних систем,
|
||
секреты.
|
||
requires:
|
||
- specs
|
||
|
||
- id: design
|
||
generates: design.md
|
||
description: Engineering design of how affected repositories implement approved behavior and system obligations
|
||
template: design.md
|
||
instruction: |
|
||
Owner: solution-architect; reviewers — affected frontend/backend engineers,
|
||
database-specialist при миграциях. Gate: G3.
|
||
|
||
Purpose:
|
||
Как affected repositories реализуют свою сторону approved Specs и выбранных
|
||
system-analysis/ux-design/security-analysis. Не повторный system analysis.
|
||
|
||
Preconditions:
|
||
- Все выбранные research, ux-design, system-analysis и modules,
|
||
security-analysis уже существуют (`check.cjs plan` без errors). Complex:
|
||
system-analysis утверждён на G2.
|
||
- Upstream contracts/sequences/mappings — входные ограничения.
|
||
|
||
Critical Rules:
|
||
- Не добавляй observable behavior; не меняй system contracts. Нереализуемый
|
||
contract → System Analysis, а не private contract здесь.
|
||
- Каждое существенное решение ссылается на driver: Requirement, NFR id, failure
|
||
id, threat id или constraint. Новая технология/компонент без driver запрещены.
|
||
- UI: при ux-design.md — только инженерная реализация (composition, state, data
|
||
fetching, производство каждого UI state); без ux-design.md — раздел UI
|
||
Implementation даёт new/changed/reuse/N/A с причиной и нужные экраны/состояния.
|
||
Неизменяемый UI и N/A не требуют макетов.
|
||
- Visual Package (единые правила для ux-design.md и UI Implementation): версия
|
||
пакета; для reuse — immutable locator (store ID + path от OpenSpec root),
|
||
применимая часть и отличия; локальные PNG/SVG под `visuals/` с relative path,
|
||
purpose и SHA-256; SVG самодостаточен (без scripts, handlers, внешних
|
||
fonts/assets); mutable внешняя ссылка не является утверждённой версией.
|
||
ux-design.md и design.md — один Design package с одним approval на G3.
|
||
- Solution Assessment обязателен для нового auth, security, storage, external
|
||
integration, observability, caching, concurrency, shared tooling или иного
|
||
дорогого необратимого решения; иначе N/A + reason.
|
||
- Rollback contract обязателен для security, destructive migration, public
|
||
contract и труднообратимых решений.
|
||
- Developer verification определяют implementation owners; QA matrix не копируй.
|
||
- ADR Candidates: только долгоживущие архитектурные решения с alternatives.
|
||
|
||
MUST NOT Include: approved sequences/contracts/mappings (ссылки, не копии);
|
||
UX flows/states при наличии ux-design.md; QA coverage; docs plan; tasks/PR plan;
|
||
длинный production code.
|
||
|
||
Feedback Routing: intent → Proposal; behavior → Specs; interaction → UX Design;
|
||
contracts/mappings/failure semantics/semantic observability → System Analysis;
|
||
threats → Security Analysis.
|
||
requires:
|
||
- specs
|
||
|
||
- id: qa-analysis
|
||
generates: qa-analysis.md
|
||
description: Risk-based system verification strategy independent from developer-owned tests
|
||
template: qa-analysis.md
|
||
instruction: |
|
||
Owner: qa-engineer. Gate: G3. Может выполняться параллельно с design.
|
||
|
||
Purpose:
|
||
Что нужно проверить на уровне системы, чтобы доказать соответствие Specs и
|
||
выбранным system-analysis modules, и с какой глубиной — по риску.
|
||
|
||
Depth (условные секции внутри обязательного artifact):
|
||
- Всегда: Risk Assessment, Coverage Matrix (строка на каждый delta Requirement),
|
||
Gaps / Blockers.
|
||
- Delivery standard: остальные разделы только при наличии содержания; удаляй
|
||
пустые разделы, не пиши N/A.
|
||
- Lab или complex: все разделы; Cross-system Verification обязателен при
|
||
выбранном system-analysis, failure-model или data-mapping (каждый failure id
|
||
и invariant имеет проверку или обоснованный risk-based отказ).
|
||
|
||
Critical Rules:
|
||
- QA проверяет system behavior, не устройство кода; не предписывай unit/component
|
||
tests, mocks, coverage percentage.
|
||
- Не создавай behavior: неопределённый expected result → gap в Specs;
|
||
неопределённый flow/error/contract → gap в System Analysis.
|
||
- Ссылайся на Scenarios, не переписывай их. Отдельные test cases — только через
|
||
artifact `test-cases`.
|
||
- Планы проверок отделены от результатов: результаты фиксируются на G4, не здесь.
|
||
- Automation: black-box API/E2E кандидаты; QA repo пока нет — `deferred until QA
|
||
repo exists`.
|
||
|
||
Feedback Routing: behavior → Specs; contracts/failures → System Analysis;
|
||
testability hooks → Design (как need, без проектирования).
|
||
requires:
|
||
- specs
|
||
|
||
- id: test-cases
|
||
generates: "test-cases/*.md"
|
||
description: Optional explicit test design for high-risk scenarios that need concrete data, steps or oracles
|
||
template: test-cases.md
|
||
instruction: |
|
||
Owner: qa-engineer. Conditional: только если выбран `test-cases`. Gate: G3.
|
||
|
||
Trigger: финансовые расчёты, сложные бизнес-сценарии, значимые интеграции,
|
||
много ошибок и граничных случаев, критичное пользовательское поведение — когда
|
||
проверка требует конкретных данных, шагов или oracle, которых нет в Scenario.
|
||
|
||
Critical Rules:
|
||
- Один файл на область: `test-cases/<area>.md`; id `TC-<AREA>-<NNN>` уникален.
|
||
- Каждый case: Verifies (reference format), Risk/Priority, Preconditions, Test
|
||
Data, Steps, Expected Results, Automation Candidate.
|
||
- Case добавляет информацию сверх Scenario (числа, комбинации, порядок событий,
|
||
расчётный oracle). Если не добавляет — не пиши case; coverage matrix ссылается
|
||
на Scenario.
|
||
- Не копируй acceptance criteria дословно; expected result выводится из
|
||
Requirement, а не придумывается. Неопределённость → gap в Specs.
|
||
- qa-analysis Coverage Matrix ссылается на TC ids.
|
||
requires:
|
||
- qa-analysis
|
||
|
||
- id: docs-impact
|
||
generates: docs-impact.md
|
||
description: Optional promotion plan from change knowledge to canonical AS-IS documentation
|
||
template: docs-impact.md
|
||
instruction: |
|
||
Owner: documentation-engineer. Conditional: только если выбран `docs-impact`.
|
||
Gate: G3.
|
||
|
||
Trigger: несколько docs targets, новый ADR, перенос diagrams, изменение
|
||
architecture/integration pages, lab-практика Documentation Impact Analysis.
|
||
Иначе — раздел `## Docs Impact` в tasks.md (targets или конкретная no-change
|
||
причина).
|
||
|
||
Canonical Documentation Model: `docs/` — AS-IS (`overview.md`, `glossary.md`,
|
||
`architecture/`, `architecture/cross-cutting/`, `domains/`, `integrations/`,
|
||
`adr/`, `design/`). Accepted ADR не переписывается.
|
||
|
||
Critical Rules:
|
||
- Promote только знание, полезное после завершения change; без migration diary.
|
||
- Не копируй machine-readable contract в docs как второй source of truth.
|
||
- Каждая entry: Action, exact Target (существующий path проверен), Category,
|
||
Resulting AS-IS, Source, Verification.
|
||
- Diagram promotion по умолчанию — нет.
|
||
- docs-impact не редактирует `docs/`; Tasks создаёт `[docs]` items.
|
||
requires:
|
||
- design
|
||
|
||
- id: tasks
|
||
generates: tasks.md
|
||
description: Dependency-ordered, repository-owned delivery checklist with verification, review and parity tasks
|
||
template: tasks.md
|
||
instruction: |
|
||
Owner: основной агент (delivery coordination); reviewers — affected engineers.
|
||
Gate: G3.
|
||
|
||
Preconditions:
|
||
- design и qa-analysis существуют; все выбранные условные artifacts существуют
|
||
(`check.cjs plan` без errors).
|
||
- Для complex/lab: G2 approved до записи tasks.
|
||
|
||
Task Format:
|
||
`- [ ] X.Y [main|frontend|backend|docs|specs] <Kind>: <action + outcome>`
|
||
с полями **Covers**, **Source**, **Verification**, **Depends on**.
|
||
Kinds: Implementation, Migration, Automated Testing, Contract Parity, Docs,
|
||
Independent Review, QA Verification, Verification.
|
||
|
||
Required Tasks (только релевантные; `check.cjs` проверяет отмеченные *):
|
||
- Implementation/Automated Testing per repository по Design.
|
||
- Migration: при изменении хранения — backup/rollback и проверка на копии данных.
|
||
- * Contract Parity: при наличии `system-analysis/contracts/` — сравнение
|
||
backend-generated OpenAPI/runtime с target contract.
|
||
- Docs: из docs-impact или раздела `## Docs Impact`.
|
||
- * Independent Review: read-only review реализации против approved artifacts.
|
||
- QA Verification: system checks по qa-analysis (и test-cases).
|
||
- Security: проверки из security-analysis Validation Requirements, если выбран.
|
||
- Native sync/archive не является task; canonical specs не правятся task'ом.
|
||
|
||
Critical Rules:
|
||
- Одна task = один repository + один independently reviewable outcome.
|
||
- * Каждый ADDED/MODIFIED Requirement появляется в Covers хотя бы одной task.
|
||
- Covers использует reference format; неизвестный heading — ошибка `check.cjs`.
|
||
- `[qa]` запрещён, пока QA repo не существует.
|
||
- Не создавай ceremonial tasks; нерелевантная Kind не нужна.
|
||
- Descope после G3: удали task из tasks.md и запиши в process-record
|
||
`Descoped Work` с причиной и gate решения владельца.
|
||
|
||
MUST NOT Include: новое behavior/contract/design/QA/docs decision (→ upstream
|
||
artifact), commits/branches, будущие результаты.
|
||
|
||
Feedback Routing: semantic change → самый ранний затронутый artifact,
|
||
инвалидируя его gate и последующие.
|
||
requires:
|
||
- design
|
||
- qa-analysis
|
||
|
||
apply:
|
||
requires:
|
||
- tasks
|
||
tracks: tasks.md
|
||
instruction: |
|
||
Apply реализует approved plan и не переоткрывает upstream decisions без feedback cycle.
|
||
|
||
Preconditions (CLI проверяет только наличие tasks.md, остальное — `check.cjs`):
|
||
- `check.cjs apply <change>` = OK (G1, G2 для lab/complex, G3; каждый
|
||
существующий artifact утверждён на своём gate; выбранные artifacts существуют).
|
||
- Перед зависимой UI-работой проверь наличие и SHA-256 материалов из таблицы
|
||
Materials (ux-design.md или UI Implementation design.md).
|
||
- Store `wealth-ledger-specs`; protocol — instruction `process-record`.
|
||
|
||
Context Loading: `contextFiles` из apply instructions, затем `AGENTS.md` только
|
||
affected repositories, затем relevant upstream sections для каждой task.
|
||
|
||
Execution:
|
||
- Pending tasks по dependency order; один repository на task; delegate по роли
|
||
(frontend-engineer, backend-engineer, database-specialist) с Task Brief.
|
||
- Checkbox отмечается только после observed success Verification.
|
||
- Contract Parity: backend-generated OpenAPI semantic-compatible с target contract.
|
||
- Independent Review выполняет independent-reviewer (read-only) по полному diff
|
||
против approved artifacts; Major findings исправляются или возвращаются в gate.
|
||
- QA Verification выполняет qa-engineer по qa-analysis; результаты — в Gate Log G4.
|
||
- Lab: строка Lab Journal после implementation, review и QA.
|
||
|
||
Before archive (G4 Delivery Acceptance):
|
||
- Все tasks `[x]`; descoped — только через `Descoped Work`.
|
||
- Validation G4: developer checks, parity, review verdict, QA results, docs.
|
||
- Lab: Retrospective заполнен.
|
||
- `check.cjs archive <change>` = OK (включает все apply-проверки), затем `openspec archive <change>
|
||
--store wealth-ledger-specs`. Никогда `--no-validate`. `--yes` подавляет и
|
||
подтверждение spec updates, и предупреждение о незакрытых tasks, поэтому
|
||
допустим только сразу после успешного `check.cjs archive` (в non-TTY агентской
|
||
среде без него archive не выполняется).
|
||
|
||
Sync / Archive Semantics: native archive обновляет canonical specs;
|
||
system-analysis, contracts и process-record остаются в archived change; `docs/`
|
||
меняются только `[docs]` tasks; значимые решения — immutable ADR.
|
||
|
||
Feedback Routing:
|
||
- intent/scope → Proposal; behavior/invariants → Specs; interaction → UX Design;
|
||
systems/contracts/mappings/failures/NFR/semantic observability → System Analysis
|
||
и modules; threats → Security Analysis; internal implementation → Design;
|
||
verification → QA Analysis/Test Cases; docs → Docs Impact; decomposition → Tasks.
|
||
- При semantic conflict останови downstream work, сообщи evidence, инвалидируй
|
||
gates от самого раннего затронутого artifact.
|