docs(specs): archive OpenSpec resilience change

2026-08-26 10:11:34 +03:00
parent 8462a3ba75
commit 779a1e1305
8 changed files with 87 additions and 5 deletions
@@ -83,7 +83,7 @@ Workspace SHALL предоставлять один non-mutating локальн

 ### Requirement: Tasks трассируются к утверждённым требованиям

-Каждый checkbox Tasks MUST содержать coverage reference: одну или несколько пар из точного capability path и точного Requirement heading либо `N/A` с конкретной причиной для работы, которая не реализует spec-level behavior. Каждый Requirement из Delta Specs MUST быть покрыт хотя бы одной task. Planning validation MUST отклонять отсутствующее покрытие, ссылку на несуществующий capability или Requirement и пустую причину `N/A`. Traceability SHALL использовать нативную идентичность requirement и MUST NOT вводить параллельный namespace собственных requirement IDs.
+Каждый checkbox Tasks MUST содержать coverage reference: одну или несколько пар из точного capability path и точного Requirement heading либо `N/A` с конкретной причиной для работы, которая не реализует spec-level behavior. Причина `N/A` MUST объяснять отсутствие самостоятельного observable behavior, техническую необходимость задачи и её связь с утверждённым Design или delivery; однословная категория или неразрешённый placeholder не являются достаточной причиной. Каждый Requirement из Delta Specs MUST быть покрыт хотя бы одной task. Planning validation MUST отклонять отсутствующее покрытие, ссылку на несуществующий capability или Requirement, пустую причину `N/A` и неразрешённый placeholder. Содержательная достаточность непустой причины SHALL оцениваться semantic approval и independent review и MUST NOT выдаваться за детерминированный hard guardrail. Traceability SHALL использовать нативную идентичность requirement и MUST NOT вводить параллельный namespace собственных requirement IDs.

 #### Scenario: Delta requirement покрыт реализацией

@@ -93,7 +93,17 @@ Workspace SHALL предоставлять один non-mutating локальн
 #### Scenario: Задача не меняет spec-level behavior

 - **WHEN** task обновляет infrastructure, documentation или verification без самостоятельного requirement
- **THEN** coverage reference содержит `N/A` и конкретно объясняет отсутствие spec-level связи
+- **THEN** coverage reference содержит `N/A` и конкретно объясняет техническую необходимость задачи и её связь с утверждённым Design или delivery
+
+#### Scenario: N/A содержит placeholder
+
+- **WHEN** coverage reference оставляет template placeholder вместо фактической причины
+- **THEN** planning validation блокирует approval Tasks и указывает незавершённую metadata
+
+#### Scenario: N/A содержит непустую слабую причину
+
+- **WHEN** coverage reference формально заполнена, но не объясняет необходимость задачи или её связь с утверждённым change
+- **THEN** semantic review запрашивает уточнение без представления эвристической текстовой оценки как hard guardrail

 #### Scenario: Requirement остался без задачи

@@ -35,7 +35,7 @@ Versioned SDD change SHALL проходить последовательност

 ### 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. Если несоответствие обнаружено во время Design или Apply, downstream-работа MUST остановиться, а Change Owner MUST получить наблюдаемое основание возврата и решения, требуемые на выбранном уровне. Механическое исправление синтаксиса или формата, которое не меняет утверждённые намерение, поведение, архитектурные решения или состав задач, MUST пройти повторную structural validation и MUST NOT само по себе инвалидировать approvals.
+Изменение утверждённого 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. Если несоответствие обнаружено во время Design или Apply, downstream-работа MUST остановиться, а Change Owner MUST получить наблюдаемое основание возврата и решения, требуемые на выбранном уровне. Механическое исправление синтаксиса или формата, которое не меняет утверждённые намерение, поведение, архитектурные решения или состав задач, MUST пройти повторную structural validation и MUST NOT само по себе инвалидировать approvals. Исправление Markdown heading, опечатки без изменения нормативного смысла или выравнивания таблицы MAY считаться механическим; изменение формулировки Requirement, добавление или удаление Scenario, изменение выбранного архитектурного решения либо planned Verification задачи MUST NOT считаться механическим.

 #### Scenario: После Design изменилось намерение

@@ -57,6 +57,11 @@ Versioned SDD change SHALL проходить последовательност
 - **WHEN** утверждённый artifact содержит исправимую синтаксическую или formatting-ошибку без изменения его смысла
 - **THEN** workflow исправляет ошибку, повторяет structural validation и сохраняет действующие approvals

+#### Scenario: Меняется planned Verification
+
+- **WHEN** исправление Tasks меняет способ, которым должна подтверждаться поставка
+- **THEN** workflow рассматривает изменение как semantic task-scope change и повторно запрашивает approval Tasks
+
 ### 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, текущей директории или глобального значения по умолчанию машины.

@@ -145,14 +150,81 @@ Project-owned archive workflow MUST отклонять archive, если отс

 ### Requirement: Planning artifact проверяется до запроса approval

-Каждый создаваемый planning artifact SHALL пройти все применимые на его текущем этапе non-mutating structural checks до запроса approval Change Owner. Если полный change validation ещё заблокирован отсутствующими downstream artifacts, workflow MUST выполнить доступные проверки текущего artifact и явно оставить недоступную проверку незавершённой, а не заявлять общий успех. Техническая ошибка проверяемого формата SHALL исправляться и проверяться повторно без передачи ручного исправления Change Owner; structural success MUST NOT подменять semantic approval.
+Каждый создаваемый planning artifact SHALL пройти все применимые на его текущем этапе non-mutating structural checks до запроса approval Change Owner. Если полный change validation ещё заблокирован отсутствующими downstream artifacts, workflow MUST выполнить доступные проверки текущего artifact и явно оставить недоступную проверку незавершённой, а не заявлять общий успех. Planning verifier MUST выдавать различимые результаты для нарушения artifact validation, некорректного invocation и environment failure. Только диагностированная техническая ошибка проверяемого artifact SHALL исправляться в artifact и проверяться повторно без передачи ручного исправления Change Owner; invocation или environment failure MUST NOT приводить к изменению planning artifact. Structural success MUST NOT подменять semantic approval.

 #### Scenario: Текущий artifact имеет проверяемое нарушение

 - **WHEN** сгенерированный planning artifact нарушает обязательный формат или ссылочную целостность, доступные для проверки на текущем этапе
- **THEN** workflow исправляет нарушение и повторяет structural checks до запроса owner approval
+- **THEN** workflow сообщает artifact validation failure, исправляет указанное нарушение и повторяет structural checks до запроса owner approval
+
+#### Scenario: Verifier вызван некорректно
+
+- **WHEN** planning verifier получает отсутствующий или недопустимый input
+- **THEN** он сообщает invocation failure, а агент исправляет вызов без изменения planning artifact
+
+#### Scenario: Проверка блокируется окружением
+
+- **WHEN** verifier не может выполнить проверку из-за отсутствующего runtime, command или иного environment prerequisite
+- **THEN** он сообщает environment failure, агент сохраняет planning artifact неизменным и диагностирует prerequisite либо передаёт точную блокирующую ошибку Change Owner

 #### Scenario: Downstream artifacts ещё отсутствуют

 - **WHEN** Proposal создан, а Delta Specs, Design и Tasks ещё не существуют
 - **THEN** workflow сообщает результат доступных Proposal checks и не представляет отсутствующую full-change validation как успешную
+
+### Requirement: Project schema сохраняет заметные самодостаточные правила
+
+Project schema SHALL показывать обязательные правила текущей стадии до
+поддерживающих пояснений и SHALL сохранять нормативную семантику artifact graph,
+artifact boundaries и feedback routing внутри schema. Она MUST NOT зависеть от
+global agent prompt или параллельного файла правил для корректного выполнения
+workflow. Поясняющий текст SHALL использовать основной язык project artifacts,
+сохраняя exact OpenSpec headings, tokens, commands и normative keywords без
+перевода. Сокращение или перегруппировка instructions MUST NOT удалять
+действующий lifecycle invariant.
+
+#### Scenario: Агент получает instruction текущего artifact
+
+- **WHEN** OpenSpec возвращает agent instruction для разрешённой стадии
+- **THEN** обязательные правила этой стадии доступны до подробностей и достаточны без внешнего prompt с дублирующей policy
+
+#### Scenario: Instructions сокращаются
+
+- **WHEN** повторяющийся или поясняющий текст удаляется либо переносится внутри project schema
+- **THEN** каждый ранее действующий artifact boundary, approval gate и feedback route остаётся представлен ровно одним authoritative правилом
+
+### Requirement: Delta Spec template не предрешает операцию
+
+Исходная форма Delta Spec SHALL быть применима к `ADDED`, `MODIFIED`, `REMOVED`
+и `RENAMED` requirements и MUST NOT создавать активный пустой раздел или
+предварительно выбирать одну delta operation. Она SHALL сообщать допустимые
+формы operations и отдельное правило `Purpose` для новой capability, не
+заставляя существующую capability начинать с `ADDED Requirements`.
+
+#### Scenario: Изменяется существующий requirement
+
+- **WHEN** агент получает исходную форму Delta Spec для существующей capability
+- **THEN** форма позволяет выбрать `MODIFIED Requirements` без удаления заранее созданного активного `ADDED Requirements`
+
+#### Scenario: Delta использует одну операцию
+
+- **WHEN** change требует только одну из поддерживаемых delta operations
+- **THEN** сохранённый artifact содержит только применимую operation и не содержит пустых sections остальных видов
+
+### Requirement: Apply читает только разрешённый planning context
+
+Apply SHALL прочитать каждый artifact path из `contextFiles`, возвращённых
+OpenSpec для текущего change, а затем применимые локальные routing instructions
+каждой affected delivery area. Агент MUST NOT вычислять planning context paths
+самостоятельно или требовать отдельный project context mapping, дублирующий
+CLI-resolved state.
+
+#### Scenario: OpenSpec возвращает contextFiles
+
+- **WHEN** агент начинает Apply утверждённого change
+- **THEN** он читает все объявленные CLI paths и локальные instructions affected areas до выполнения pending tasks
+
+#### Scenario: У change нет отдельного context map
+
+- **WHEN** CLI уже разрешил planning artifacts и affected areas имеют локальные routing instructions
+- **THEN** Apply использует эти authorities и не блокируется отсутствием второго context mapping artifact