chore: harden SDD governance workflow
This commit is contained in:
@@ -7,27 +7,35 @@
|
||||
## Requirements
|
||||
|
||||
### Requirement: Реестр remediation отделён от снимка аудита
|
||||
Система SHALL хранить неизменяемый versioned audit snapshot в `docs/audits` и durable remediation registry в `docs/development`. Snapshot SHALL оставаться source of facts; registry SHALL хранить только текущее состояние remediation. Каждая запись registry MUST ссылаться на Audit ID и не дублировать полный текст finding, если он уже содержится в snapshot.
|
||||
Система SHALL создавать отдельный неизменяемый versioned audit snapshot в `docs/audits` для каждого завершённого аудита и SHALL поддерживать один актуальный durable remediation registry в `docs/development`, охватывающий findings всех audit snapshots. Каждый snapshot SHALL оставаться source of facts своего аудита и MUST NOT редактироваться для отражения последующей remediation. Registry SHALL хранить текущее состояние, связанный canonical change, следующее действие и completion evidence каждой записи, MUST ссылаться на однозначный Audit ID и исходный snapshot и MUST NOT дублировать полный текст finding, если он уже содержится в snapshot.
|
||||
|
||||
#### Scenario: Агент открывает работу по аудиту в новой сессии
|
||||
- **WHEN** агент получает задачу устранить или продолжить audit finding
|
||||
- **THEN** он находит linked registry, исходный Audit ID, текущий статус, связанный OpenSpec change и следующее действие без повторной интерпретации всего аудита
|
||||
- **WHEN** агент получает задачу устранить или продолжить finding из любого завершённого аудита
|
||||
- **THEN** он находит в едином registry исходный snapshot и Audit ID, текущий статус, связанный OpenSpec change, evidence и следующее действие без повторной интерпретации всех аудитов
|
||||
|
||||
#### Scenario: Проводится повторный аудит
|
||||
- **WHEN** новый аудит завершён после предыдущего audit snapshot
|
||||
- **THEN** система добавляет новый immutable snapshot и обновляет тот же live registry, не переписывая предыдущий snapshot и не создавая конкурирующий registry
|
||||
|
||||
#### Scenario: Обновляется прогресс remediation
|
||||
- **WHEN** работа по finding меняет статус
|
||||
- **THEN** versioned audit snapshot не редактируется, а изменение фиксируется только в registry с датой и необходимым evidence
|
||||
- **THEN** versioned audit snapshots не редактируются, а изменение фиксируется только в live registry с датой и необходимым evidence
|
||||
|
||||
### Requirement: Registry задаёт однозначный статус и следующий change
|
||||
Каждая audit-derived запись SHALL иметь ровно один статус из `planned`, `active`, `done`, `deferred` или `accepted`. Registry MUST содержать не более одного `active` change и ровно одну следующую рекомендуемую задачу, пока остаются findings со статусом `planned`.
|
||||
Каждая audit-derived запись SHALL иметь ровно один статус из `planned`, `active`, `done`, `deferred` или `accepted`. `planned` MUST означать согласованную работу, которую можно начать без внешнего review trigger; запись, ожидающая версии зависимости, внешнего события или отдельного решения владельца, MUST иметь статус `deferred` с условием пересмотра. Registry MUST содержать не более одного `active` remediation change и ровно одну следующую рекомендуемую задачу, пока существуют findings со статусом `planned`.
|
||||
|
||||
#### Scenario: В рабочей области нет активного remediation change
|
||||
- **WHEN** агент открывает registry и все незакрытые findings имеют статус `planned`
|
||||
- **WHEN** агент открывает registry и все незакрытые немедленно исполнимые findings имеют статус `planned`
|
||||
- **THEN** он может выбрать ровно одну строку, отмеченную как следующая рекомендуемая задача, и создать связанный canonical OpenSpec change
|
||||
|
||||
#### Scenario: В рабочей области уже есть активный remediation change
|
||||
- **WHEN** registry содержит запись со статусом `active`
|
||||
- **THEN** агент продолжает связанный change и не создаёт второй remediation change без явного решения владельца
|
||||
|
||||
#### Scenario: Finding зависит от будущего trigger
|
||||
- **WHEN** remediation нельзя обоснованно начать до указанной версии зависимости, внешнего события или решения владельца
|
||||
- **THEN** registry хранит статус `deferred`, rationale и проверяемое условие пересмотра вместо представления finding как готового `planned` work
|
||||
|
||||
### Requirement: Terminal status подтверждён проверяемым evidence
|
||||
Registry SHALL NOT представлять finding как `done` без даты, archive path связанного OpenSpec change, commit identifiers для каждого затронутого Git-репозитория и точных non-mutating verification commands с результатами. Архивированный audit-derived change MUST иметь все tasks завершёнными до archive; completion evidence после archive MUST быть отдельной записью registry или history, а не незакрытым task в archived change. Статусы `deferred` и `accepted` MUST содержать дату, rationale и условие пересмотра либо ссылку на явное решение владельца.
|
||||
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# engineering-change-governance Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Определяет соразмерные и проверяемые правила инженерных решений AI-агентов, чтобы WealthLedger переиспользовал зрелые решения, тестировал существенные риски и локально отклонял код, нарушающий инварианты проекта.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Готовые решения оцениваются до собственной реализации
|
||||
|
||||
Изменение, которое вводит или существенно заменяет механизм авторизации, безопасности, хранения данных, внешней интеграции, наблюдаемости, кэширования, конкурентного доступа либо общей инфраструктуры и tooling, MUST до утверждения архитектурного решения оценить существующие поддерживаемые решения. Оценка MUST сравнивать применимые варианты по соответствию требованиям, зрелости, безопасности, эксплуатационной стоимости, ограничениям и стоимости миграции. Собственная реализация SHALL допускаться только когда подходящего готового решения нет либо его существенная несовместимость явно зафиксирована вместе с рисками такого выбора. Для изменений вне перечисленных областей отдельная оценка MUST NOT быть обязательной без конкретного риска или дорогостоящего необратимого решения.
|
||||
|
||||
#### Scenario: Существует совместимое зрелое решение
|
||||
|
||||
- **WHEN** change затрагивает одну из обязательных для оценки областей и найдено поддерживаемое решение, удовлетворяющее требованиям без неприемлемых ограничений
|
||||
- **THEN** архитектурное решение использует это решение либо явно объясняет, почему его совокупная стоимость или риск выше выбранной альтернативы
|
||||
|
||||
#### Scenario: Подходящего решения нет
|
||||
|
||||
- **WHEN** рассмотренные зрелые решения не выполняют существенные требования или создают неприемлемый риск
|
||||
- **THEN** собственная реализация допускается только после фиксации проверенных вариантов, конкретных разрывов, принятых рисков и условия повторного пересмотра
|
||||
|
||||
#### Scenario: Изменение не требует solution assessment
|
||||
|
||||
- **WHEN** change не относится к обязательным областям и не содержит отдельного дорогостоящего или необратимого решения
|
||||
- **THEN** отсутствие формальной оценки готовых решений не блокирует SDD lifecycle и не создаёт дополнительный артефакт ради процесса
|
||||
|
||||
### Requirement: Тестирование определяется риском поведения
|
||||
|
||||
План изменения MUST требовать автоматизированные тесты для security- и privacy-sensitive поведения, денежных расчётов, целостности и миграции данных, конкурентного доступа, публичных контрактов, критических пользовательских сценариев и подтверждённых регрессий. Изменение MUST NOT требовать новый тест только из-за появления или изменения файла. Простые декларативные структуры, DTO без собственной логики, тонкие адаптеры, прямолинейная оркестрация, hygiene scripts и поведение сторонней библиотеки SHALL проверяться существующим контрактным или интеграционным gate без отдельного unit test, если они не содержат самостоятельного ветвления, преобразования, инварианта либо ранее найденной регрессии. Существующий frontend coverage gate SHALL использоваться только как anti-regression constraint, а не как основание создавать малоценные тесты. Backend MUST NOT получать общий числовой coverage threshold только ради симметрии или процессного соответствия; такой gate требует отдельного утверждённого обоснования защищаемого риска.
|
||||
|
||||
#### Scenario: Изменяется критический инвариант
|
||||
|
||||
- **WHEN** change меняет безопасность, денежный результат, целостность данных, конкурентное поведение, публичный контракт, критический journey или исправляет регрессию
|
||||
- **THEN** checklist содержит тест соответствующего уровня, который наблюдаемо подтверждает новый или исправленный результат
|
||||
|
||||
#### Scenario: Добавлен простой служебный скрипт
|
||||
|
||||
- **WHEN** скрипт только последовательно запускает существующие проверяемые команды, не содержит самостоятельной бизнес-логики, ветвления или преобразования данных
|
||||
- **THEN** отдельный unit test для скрипта не является обязательным, а корректность результата подтверждается выполнением самого локального gate
|
||||
|
||||
#### Scenario: Coverage можно повысить только малоценным тестом
|
||||
|
||||
- **WHEN** новый тест повторял бы декларативную структуру или внутреннее поведение зависимости и не защищал бы самостоятельный риск проекта
|
||||
- **THEN** агент не создаёт такой тест только ради процента coverage и сохраняет существующий anti-regression threshold
|
||||
|
||||
#### Scenario: Backend не имеет числового coverage threshold
|
||||
|
||||
- **WHEN** обязательные risk-based тесты backend проходят, а отдельный измеримый риск для общего coverage threshold не утверждён
|
||||
- **THEN** отсутствие глобального числового threshold не считается пробелом и не блокирует change
|
||||
|
||||
### Requirement: Enforceable Engineering Invariant имеет локальную проверку
|
||||
|
||||
Каждое правило, обозначенное как обязательный Enforceable Engineering Invariant, MUST иметь детерминированную non-mutating локальную проверку и MUST блокировать завершение работы при нарушении. Такие инварианты SHALL охватывать применимые правила стиля проекта, статическую корректность, архитектурные границы, публичные контракты, безопасность и критические доменные ограничения. Рекомендация, которую невозможно надёжно проверить локально, MUST быть обозначена как guidance и MUST NOT выдаваться за hard guardrail. Проверка самого hard guardrail MUST иметь evidence, что она отклоняет хотя бы одно контролируемое репрезентативное нарушение; это evidence MUST NOT превращаться в требование unit-тестировать каждый вспомогательный скрипт.
|
||||
|
||||
#### Scenario: Агент пишет код не в стиле проекта
|
||||
|
||||
- **WHEN** изменение нарушает проверяемое правило форматирования, lint, типов, импортных границ или публичного контракта проекта
|
||||
- **THEN** обязательный локальный gate завершается с ошибкой и работа не считается завершённой
|
||||
|
||||
#### Scenario: Правило является только рекомендацией
|
||||
|
||||
- **WHEN** команда не может определить детерминированную локальную проверку сформулированного предпочтения
|
||||
- **THEN** правило документируется как guidance, а агент не использует его как самостоятельную причину объявить корректную реализацию невалидной
|
||||
|
||||
#### Scenario: Добавляется новый hard guardrail
|
||||
|
||||
- **WHEN** change объявляет новое правило блокирующим
|
||||
- **THEN** completion evidence подтверждает как успешный compliant case, так и обнаружение контролируемого representative violation
|
||||
@@ -0,0 +1,63 @@
|
||||
# multi-repository-delivery Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Определяет полную поставку одного SDD-изменения через независимые frontend, backend, specs и docs репозитории без потерянных областей, фиктивных коммитов и преждевременного статуса done.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Каждый change содержит полный Delivery Map
|
||||
|
||||
Каждый versioned change MUST оценивать delivery areas `frontend`, `backend`, `specs` и `docs` и для каждой области указывать `affected` либо `N/A` с конкретной причиной. `specs` SHALL быть affected для каждого versioned SDD change. `docs` SHALL быть affected для каждой поставленной пользовательской фичи; для технического или процессного change она MAY быть `N/A` только когда фактическая устойчивая документация не изменяется. `frontend` и `backend` SHALL быть affected только когда меняется их поведение, контракт, реализация или обязательный локальный gate. Пустой коммит MUST NOT использоваться для имитации участия незатронутого репозитория.
|
||||
|
||||
#### Scenario: Фича затрагивает клиент и API
|
||||
|
||||
- **WHEN** change меняет пользовательский поток и соответствующее API-поведение
|
||||
- **THEN** Delivery Map отмечает frontend, backend, specs и docs как affected и описывает ожидаемый результат каждой области без реализации по файлам
|
||||
|
||||
#### Scenario: Область не затронута
|
||||
|
||||
- **WHEN** поведение, контракт, реализация, guardrails и фактическая документация области не меняются
|
||||
- **THEN** Delivery Map содержит проверяемую причину `N/A`, а delivery не требует пустого коммита этого репозитория
|
||||
|
||||
### Requirement: Частичная multi-repository delivery не считается завершённой
|
||||
|
||||
Change MUST оставаться active, пока каждая affected область не реализована и не прошла свои обязательные локальные gates. Успех одной области MUST NOT позволять архивировать change, если другая affected область отсутствует, не проверена либо не соответствует согласованному поведению. После archive change MUST NOT получить terminal status `done`, пока фактические результаты всех четырёх delivery areas не представлены в Completion Evidence.
|
||||
|
||||
#### Scenario: Backend готов, а frontend ещё не реализован
|
||||
|
||||
- **WHEN** Delivery Map помечает frontend и backend как affected, но завершён и проверен только backend
|
||||
- **THEN** change остаётся active и не может быть архивирован
|
||||
|
||||
#### Scenario: Все affected области готовы
|
||||
|
||||
- **WHEN** каждая affected область реализована, согласована по общим контрактам и прошла требуемые локальные gates
|
||||
- **THEN** change может перейти к семантической верификации и archive, после которого формируется Completion Evidence для terminal status
|
||||
|
||||
### Requirement: Completion Evidence содержит только наблюдённые результаты
|
||||
|
||||
Completion Evidence MUST создаваться после выполнения работы и MUST связывать canonical change с commit identifier каждого изменённого Git-репозитория, точными выполненными non-mutating verification commands и их наблюдёнными результатами. Для каждой области с `N/A` evidence SHALL сохранять согласованную причину отсутствия изменения. Planned commands, ожидаемые результаты, незавершённые checklist items и предполагаемые commit identifiers MUST NOT представляться как completion evidence.
|
||||
|
||||
#### Scenario: Change готовится к terminal status
|
||||
|
||||
- **WHEN** implementer заявляет, что multi-repository change завершён
|
||||
- **THEN** reviewer может сопоставить Delivery Map с фактическими commits, результатами gates и причинами `N/A` для всех четырёх областей
|
||||
|
||||
#### Scenario: Команда ещё не была выполнена
|
||||
|
||||
- **WHEN** verification command только запланирована или её результат не сохранён
|
||||
- **THEN** она остаётся implementation checklist item и не засчитывается как Completion Evidence
|
||||
|
||||
### Requirement: Общий локальный verifier сохраняет gates репозиториев
|
||||
|
||||
Workspace SHALL предоставлять один non-mutating локальный verification entrypoint для multi-repository delivery. Он MUST проверять совместимость runtime до application gates, запускать канонический gate каждой selected affected области и сохранять их ошибки как blocking result. Общий verifier MUST NOT заменять или ослаблять локальные gates независимых репозиториев.
|
||||
|
||||
#### Scenario: Запущен неподдерживаемый runtime
|
||||
|
||||
- **WHEN** multi-repository verifier запускается с runtime, не соответствующим объявленному проектом контракту
|
||||
- **THEN** проверка завершается ошибкой до получения вводящего в заблуждение результата application tests
|
||||
|
||||
#### Scenario: Один repository gate завершается ошибкой
|
||||
|
||||
- **WHEN** общий verifier проверяет несколько affected областей и канонический gate одной из них не проходит
|
||||
- **THEN** общий результат является неуспешным и явно указывает failing area без обхода её локального gate
|
||||
@@ -5,6 +5,48 @@
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: SDD-артефакты имеют непересекающиеся полномочия
|
||||
|
||||
Proposal SHALL выражать причину, намерение, границы и ожидаемый эффект change языком владельца и MUST NOT содержать решения по технологиям, структуре кода, файлам, API или зависимостям. Delta Specs SHALL определять только добавленное, изменённое или удалённое наблюдаемое поведение и инварианты системы без описания изменений кода. Design SHALL объяснять архитектурный способ выполнения утверждённых Specs, существенные решения, риски и альтернативы крупными частями и MUST NOT становиться построчной инструкцией реализации. Tasks SHALL быть implementation checklist, достаточным для выполнения Design и Specs, и MUST NOT содержать ещё не наблюдённые completion results, commit identifiers или post-archive bookkeeping. Completion Evidence SHALL фиксироваться только после фактической реализации и верификации и MUST NOT подменять planning artifact.
|
||||
|
||||
#### Scenario: Product Owner формулирует Proposal
|
||||
|
||||
- **WHEN** владелец описывает требуемое изменение, не зная структуры кода и файлов
|
||||
- **THEN** Proposal остаётся полноценным утверждаемым намерением без необходимости принимать архитектурные решения
|
||||
|
||||
#### Scenario: Агент подготавливает Tasks
|
||||
|
||||
- **WHEN** Proposal, Delta Specs и Design уже утверждены
|
||||
- **THEN** Tasks перечисляет конкретные действия реализации и проверки, но не заявляет будущие результаты уже выполненными
|
||||
|
||||
### Requirement: Artifact graph применяет последовательные approval gates
|
||||
|
||||
Versioned SDD change SHALL проходить последовательность `Proposal → Delta Specs → Design → Tasks → Apply`. AI-агент MAY подготовить черновик текущего разрешённого артефакта, но MUST NOT считать его утверждённым самостоятельно или создавать downstream artifact до явного решения Change Owner. Для change, определяющего продуктовое поведение, Change Owner SHALL быть Product Owner; для технического или процессного change — Engineering Owner. Каждый из четырёх planning artifacts MUST существовать и быть утверждён до Apply.
|
||||
|
||||
#### Scenario: Proposal ещё не утверждён
|
||||
|
||||
- **WHEN** AI-агент завершил черновик Proposal, но Change Owner не дал явного согласия
|
||||
- **THEN** Delta Specs, Design и Tasks остаются недоступны для создания
|
||||
|
||||
#### Scenario: Delta Specs утверждены
|
||||
|
||||
- **WHEN** Change Owner явно подтверждает Delta Specs после утверждённого Proposal
|
||||
- **THEN** Design становится следующим разрешённым planning artifact, а Tasks и Apply остаются заблокированы
|
||||
|
||||
### Requirement: Изменение upstream artifact требует каскадной проверки
|
||||
|
||||
Изменение утверждённого Proposal MUST инициировать повторную проверку Delta Specs, Design и Tasks; изменение утверждённых Delta Specs MUST инициировать повторную проверку Design и Tasks; изменение утверждённого Design MUST инициировать повторную проверку Tasks. Изменение Tasks MUST NOT неявно менять scope, наблюдаемое поведение или архитектурные решения upstream artifacts; при таком обнаружении workflow SHALL вернуть работу к соответствующему upstream artifact и его approval gate.
|
||||
|
||||
#### Scenario: После Design изменилось намерение
|
||||
|
||||
- **WHEN** владелец меняет scope или ожидаемый эффект Proposal
|
||||
- **THEN** зависимые Delta Specs, Design и Tasks теряют прежнее подтверждение до повторной согласованной проверки
|
||||
|
||||
#### Scenario: Task вводит новое поведение
|
||||
|
||||
- **WHEN** implementation checklist требует поведение, которого нет в утверждённых Delta Specs
|
||||
- **THEN** агент не расширяет scope через Tasks и возвращает change к Delta Specs
|
||||
|
||||
### Requirement: Канонический authority OpenSpec задан явно
|
||||
WealthLedger SHALL использовать зарегистрированный store `wealth-ledger-specs` с физическим OpenSpec root `specs/openspec` как единственный поддерживаемый authority для versioned SDD artifacts. Каждый project-owned OpenSpec entrypoint и documented OpenSpec command MUST явно выбирать `--store wealth-ledger-specs`; он MUST NOT выбирать store из ближайшего root, текущей директории или глобального значения по умолчанию машины.
|
||||
|
||||
@@ -38,13 +80,45 @@ Canonical store и policy расположения artifacts SHALL иметь do
|
||||
- **WHEN** project-owned OpenSpec entrypoint допускает выбор nearest-root или global-default
|
||||
- **THEN** verifier завершается ошибкой и указывает non-compliant entrypoint
|
||||
|
||||
### Requirement: OpenSpec tooling имеет проверяемый version contract
|
||||
|
||||
SDD workflow MUST объявлять поддерживаемую версию OpenSpec CLI и проверять фактическую версию до команд, читающих или изменяющих canonical change. Несовместимая либо неопределённая версия MUST давать actionable blocking result и MUST NOT приводить к молчаливому изменению artifact graph, templates или project-owned entrypoints.
|
||||
|
||||
#### Scenario: Версия CLI соответствует контракту
|
||||
|
||||
- **WHEN** агент начинает работу с canonical change поддерживаемой версией OpenSpec
|
||||
- **THEN** workflow продолжает работу с объявленной схемой и canonical store
|
||||
|
||||
#### Scenario: Версия CLI не соответствует контракту
|
||||
|
||||
- **WHEN** доступная версия OpenSpec не совпадает с объявленным совместимым контрактом
|
||||
- **THEN** локальная preflight-проверка блокирует SDD-операцию и сообщает ожидаемую и фактическую версии
|
||||
|
||||
### Requirement: Structural и semantic verification являются разными gates
|
||||
|
||||
OpenSpec structural validation SHALL проверять schema, artifact graph и формальную корректность specs, но MUST NOT считаться доказательством соответствия реализации. До terminal status change MUST пройти semantic verification реализации против Proposal, Delta Specs, Design и Tasks, а затем независимый read-only review. Если основной agent entrypoint semantic verification недоступен, workflow SHALL использовать versioned эквивалентную процедуру с теми же входными артефактами, категориями проверки и наблюдаемым evidence.
|
||||
|
||||
#### Scenario: Structural validation прошла без ошибок
|
||||
|
||||
- **WHEN** все planning artifacts формально валидны, но реализация ещё не сопоставлена с ними
|
||||
- **THEN** change не получает terminal status только на основании structural validation
|
||||
|
||||
#### Scenario: Slash workflow недоступен агенту
|
||||
|
||||
- **WHEN** среда не предоставляет установленный semantic verification entrypoint
|
||||
- **THEN** агент выполняет документированную эквивалентную read-only проверку и сохраняет её результат вместо пропуска gate
|
||||
|
||||
### Requirement: Archive блокируется незавершёнными tasks
|
||||
Project-owned archive workflow MUST отклонять archive, пока его `tasks.md` содержит любой unchecked task. Post-archive bookkeeping MUST NOT появляться как unchecked task; он SHALL фиксироваться через детерминированное completion evidence после успешного archive.
|
||||
Project-owned archive workflow MUST отклонять archive, если отсутствует требуемый planning artifact, любой обязательный artifact не утверждён, `tasks.md` отсутствует или содержит unchecked task, semantic verification либо независимый read-only review не завершены успешно, или любая affected delivery area не реализована и не прошла обязательные pre-archive gates. Workflow MUST NOT предлагать confirmation override для этих blocking conditions. Post-archive bookkeeping MUST NOT появляться как unchecked task; он SHALL фиксироваться через детерминированное Completion Evidence после успешного archive, после чего связанная delivery может получить terminal status.
|
||||
|
||||
#### Scenario: Change имеет unchecked task
|
||||
- **WHEN** implementer запрашивает archive и остаётся хотя бы один unchecked task
|
||||
- **THEN** workflow не архивирует change и сообщает incomplete tasks как blocking condition
|
||||
- **THEN** workflow не архивирует change и сообщает incomplete tasks как blocking condition без возможности confirmation override
|
||||
|
||||
#### Scenario: Change не прошёл required verification
|
||||
- **WHEN** planning artifacts и tasks завершены, но semantic verification, independent review, implementation или pre-archive gate affected area отсутствуют либо неуспешны
|
||||
- **THEN** workflow не архивирует change и перечисляет недостающие blocking conditions
|
||||
|
||||
#### Scenario: Change завершил все tasks
|
||||
- **WHEN** каждый task отмечен и required verification успешно завершена
|
||||
- **WHEN** каждый planning artifact утверждён, каждый task отмечен, required verification, implementation и pre-archive gates всех affected areas успешно завершены
|
||||
- **THEN** workflow допускает archive и фиксирует его результат через определённый completion-evidence path без создания post-archive task
|
||||
|
||||
@@ -6,6 +6,20 @@
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Completion Evidence сохраняет фактическое завершение change
|
||||
|
||||
Durable development documentation SHALL хранить для завершённого change ссылку на canonical OpenSpec archive, Delivery Map, commit identifiers изменённых репозиториев, точные выполненные verification commands, их наблюдённые результаты и итог independent read-only review. Completion Evidence MUST создаваться из фактов после выполнения работы, MUST быть доступно из устойчивого index или registry и MUST NOT дублироваться как unchecked task либо планируемый результат внутри archived change.
|
||||
|
||||
#### Scenario: Участник проверяет основание terminal status
|
||||
|
||||
- **WHEN** участник открывает evidence завершённого change в новой сессии
|
||||
- **THEN** он может проследить связь от change и Delivery Map к фактическим commits, локальным gates и independent review без восстановления контекста из чата
|
||||
|
||||
#### Scenario: Реализация ещё продолжается
|
||||
|
||||
- **WHEN** часть commands, commits или review ещё не существует
|
||||
- **THEN** documentation не представляет ожидаемые значения как Completion Evidence и change остаётся незавершённым
|
||||
|
||||
### Requirement: Важные архитектурные решения фиксируются в ADR
|
||||
Репозиторий docs SHALL содержать ADR для выбора локального хранилища, API-контракта, gRPC-интеграции T-Bank, хранения T-Bank токенов, устойчивости upstream-вызовов, auth-сессий и frontend-кэша. Каждый ADR MUST описывать контекст, решение и последствия.
|
||||
|
||||
@@ -39,15 +53,19 @@
|
||||
- **THEN** registry обновляется с archive path, commits затронутых репозиториев и результатами exact verification commands
|
||||
|
||||
### Requirement: Durable documentation is not a parallel SDD store
|
||||
Репозиторий `docs` SHALL хранить только долговечную architecture, development, feature, audit и remediation documentation вместе с completion evidence. Change-specific requirements, designs, delta specifications и tasks MUST храниться только в canonical OpenSpec store и MUST NOT создаваться как framework-specific planning artifacts в `docs`.
|
||||
Репозиторий `docs` SHALL хранить только долговечную architecture, development, feature, audit и remediation documentation вместе с completion evidence. Документация MUST описывать фактическое текущее состояние поставленной системы и MUST NOT представлять планируемое или частично реализованное поведение как доступное. Change-specific requirements, proposals, designs, delta specifications и tasks MUST храниться только в canonical OpenSpec store и MUST NOT пересказываться в `docs` как параллельная спецификация в другом формате. Docs SHALL обновляться после реализации и проверки соответствующей области; она MAY ссылаться на canonical OpenSpec change, но MUST сохранять собственную as-built задачу и не копировать его нормативный текст.
|
||||
|
||||
#### Scenario: Change требует постоянной документации
|
||||
- **WHEN** завершённый change должен оставить устойчивое объяснение решения или evidence
|
||||
- **THEN** documentation фиксирует реализованное решение или completion evidence и ссылается на canonical OpenSpec change без дублирования его requirements, design или tasks
|
||||
- **THEN** documentation фиксирует реализованное состояние или completion evidence и ссылается на canonical OpenSpec change без дублирования его requirements, design или tasks
|
||||
|
||||
#### Scenario: Agent планирует незавершённый change
|
||||
- **WHEN** агент создаёт requirements, design или tasks для незавершённого изменения
|
||||
- **THEN** он сохраняет их под `specs/openspec` и не создаёт framework-specific planning document в `docs`
|
||||
- **THEN** он сохраняет их под `specs/openspec` и не создаёт framework-specific planning document или описание будущего поведения в `docs`
|
||||
|
||||
#### Scenario: Реализация расходится с прежней документацией
|
||||
- **WHEN** проверенный change изменяет поставленное поведение, архитектурную границу или устойчивое решение
|
||||
- **THEN** affected docs обновляется до фактического текущего состояния до terminal status и не сохраняет прежнее утверждение как действующее
|
||||
|
||||
### Requirement: Устойчивая документация имеет доступные фактические точки входа
|
||||
Репозиторий `docs` SHALL содержать indexes архитектуры, разработки и фич,
|
||||
|
||||
@@ -7,24 +7,11 @@
|
||||
## Requirements
|
||||
|
||||
### Requirement: Репозитории содержат локальные инструкции для AI-агентов
|
||||
Система SHALL содержать обзорный `AGENTS.md` в корне рабочей области и
|
||||
отдельный `AGENTS.md` в репозиториях frontend, backend, specs и docs.
|
||||
Инструкции MUST описывать назначение области, локальные команды проверки,
|
||||
границы ответственности и связь с SDD-артефактами. Каждая инструкция MUST
|
||||
объявлять `wealth-ledger-specs` и `specs/openspec` как canonical OpenSpec
|
||||
authority, требовать явный `--store wealth-ledger-specs` для поддерживаемых
|
||||
OpenSpec операций и запрещать versioned framework-specific planning artifacts
|
||||
вне canonical store. Локальные инструкции MUST направлять агента к durable
|
||||
documentation, относящейся к его области, и к durable remediation registry,
|
||||
когда задача связана с findings технического аудита. Backend instructions MUST
|
||||
различать non-mutating verification commands и явные auto-fix commands.
|
||||
Система SHALL содержать обзорный `AGENTS.md` в корне рабочей области и отдельный `AGENTS.md` в репозиториях frontend, backend, specs и docs. Корневая инструкция MUST содержать только общую карту workspace, Single Source of Truth, cross-repository workflow и общие hard constraints; локальная инструкция MUST добавлять относящиеся к своему репозиторию команды, проверяемые правила стиля и границ, не копируя изменчивые требования, архитектуру или feature documentation. Инструкции MUST описывать назначение области, канонический non-mutating verification entrypoint, границы ответственности и ссылки на authoritative SDD и durable documentation. Каждая инструкция MUST объявлять `wealth-ledger-specs` и `specs/openspec` как canonical OpenSpec authority, требовать явный `--store wealth-ledger-specs` для поддерживаемых OpenSpec операций и запрещать versioned framework-specific planning artifacts вне canonical store. Локальные инструкции MUST направлять агента к durable documentation, относящейся к его области, и к durable remediation registry, когда задача связана с findings технического аудита. Enforceable Engineering Invariants MUST быть сформулированы как проверяемые обязательные правила; непроверяемые предпочтения MUST быть отделены как guidance. Backend instructions MUST различать non-mutating verification commands и явные auto-fix commands.
|
||||
|
||||
#### Scenario: Агент начинает работу в отдельном репозитории
|
||||
- **WHEN** агент открывает любой из репозиториев frontend, backend, specs или
|
||||
docs
|
||||
- **THEN** он может определить локальные правила работы, canonical OpenSpec
|
||||
authority, источник связанных спецификаций и относящийся к области durable
|
||||
documentation из `AGENTS.md` этого репозитория
|
||||
- **WHEN** агент открывает любой из репозиториев frontend, backend, specs или docs
|
||||
- **THEN** он может определить локальные правила работы, канонический verification entrypoint, проверяемый стиль и границы, canonical OpenSpec authority и относящийся к области durable documentation без чтения дублирующих требований
|
||||
|
||||
#### Scenario: Агент получает audit-derived задачу из отдельного репозитория
|
||||
- **WHEN** задача ссылается на finding технического аудита
|
||||
@@ -33,8 +20,11 @@ documentation, относящейся к его области, и к durable re
|
||||
|
||||
#### Scenario: Агент выбирает backend quality gate
|
||||
- **WHEN** агент читает backend instructions перед локальной проверкой
|
||||
- **THEN** он запускает документированные non-mutating lint/typecheck commands
|
||||
и не получает auto-fix как неявный quality gate
|
||||
- **THEN** он запускает документированный канонический non-mutating gate и не получает auto-fix как неявную часть verification
|
||||
|
||||
#### Scenario: Архитектурное устройство изменилось
|
||||
- **WHEN** durable architecture documentation обновлена после поставленного change
|
||||
- **THEN** `AGENTS.md` продолжает ссылаться на authoritative документ и не требует синхронного копирования его описательного содержимого
|
||||
|
||||
### Requirement: Корень рабочей области не хранит delivery-plan файл
|
||||
Корень рабочей области MUST NOT содержать `MVP.md` или другой versioned
|
||||
@@ -72,3 +62,17 @@ Frontend MUST включать TypeScript strict mode для application source
|
||||
#### Scenario: Agent проверяет frontend перед завершением задачи
|
||||
- **WHEN** агент запускает documented frontend verification или его typecheck stage
|
||||
- **THEN** проверка выполняет strict TypeScript compilation application и Vite tooling source и сообщает non-zero exit code при strict diagnostic
|
||||
|
||||
### Requirement: Application repositories имеют канонический локальный gate
|
||||
|
||||
Frontend и backend SHALL предоставлять по одному каноническому non-mutating verification entrypoint, который проверяет все обязательные для соответствующего репозитория Enforceable Engineering Invariants. Каждый entrypoint MUST отклонять неподдерживаемый Node runtime до запуска зависимых application checks, MUST возвращать ненулевой результат при ошибке любого обязательного stage и MUST быть одинаковым для человека, AI-агента и общего workspace verifier. Отдельные auto-fix commands MUST NOT использоваться как verification entrypoint.
|
||||
|
||||
#### Scenario: Агент завершает frontend-изменение
|
||||
|
||||
- **WHEN** агент считает frontend implementation готовой
|
||||
- **THEN** он запускает один documented frontend gate и получает совокупный non-mutating результат всех обязательных frontend checks
|
||||
|
||||
#### Scenario: Агент запускает backend gate с неверным Node
|
||||
|
||||
- **WHEN** фактическая major/minor версия Node не соответствует объявленному runtime contract backend
|
||||
- **THEN** gate завершается ошибкой до application checks и сообщает ожидаемую и фактическую версии
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# user-authentication Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Позволяет пользователю создать и восстановить личную сессию, чтобы его данные и будущие подключения к брокеру были доступны только ему.
|
||||
|
||||
Reference in New Issue
Block a user