specs/openspec/changes/archive/2026-08-26-harden-openspec-sdd-agent-resilience/design.md

Context

Project-local schema v2 уже владеет SDD semantics, а stage-aware verifier проверяет artifact graph, coverage и Delivery Map. При этом обязательные правила распределены внутри длинных instructions, единый Delta Spec template начинает с ADDED Requirements, а planning failures не имеют общего явного разделения на artifact, invocation и environment причины. OpenSpec CLI 1.10.0 остаётся project version contract; schema API имеет experimental status, поэтому решение должно сохранять native graph и не вводить новый workflow engine.

Шесть second-round reports находятся как локальный неversioned corpus. Они содержат повторы прежних claims, предложения, противоречащие действующей policy, и неполный provenance. Existing remediation workflow уже определяет immutable snapshot и отдельный live triage, поэтому новый формат evidence не требуется.

Goals / Non-Goals

Goals:

• Сохранить project schema единственным владельцем artifact semantics, сделав Critical Rules первыми и устранив повторяющийся explanation text.
• Сохранить один native artifact graph и сделать Delta Spec scaffold нейтральным к operation.
• Дать planning verifier устойчивую taxonomy отказов и оставить semantic качество N/A rationale на human review boundary.
• Использовать уже разрешённый CLI context и существующую repository routing policy без второго mapping authority.
• Зафиксировать второй review corpus и его triage в существующей audit model.

Non-Goals:

• Универсализация topology за пределы WealthLedger.
• Persistent approval state, дополнительные review/done/solution artifacts или cross-change dependency graph.
• CI, commit convention, task sizing, Success Metrics либо schema changelog.
• Числовой quality threshold для instruction size, checksum или byte-count gate для audit reports.
• Изменение application runtime, данных или API contract.

Decisions

1. Сохранить текущие authority boundaries и выпустить schema v3

Schema продолжает владеть normative agent semantics; templates владеют исходной формой artifacts, project config содержит только устойчивый context, scripts реализуют детерминированные hard invariants, а durable docs описывает as-built process. Каждая artifact instruction начинается с компактного блока Critical Rules, после которого идут только stage-specific details. Пояснения приводятся по-русски, а exact OpenSpec tokens, headings, commands и SHALL/MUST сохраняются на английском.

Material instruction, template и verifier contract change повышает schema version до 3. Исторический rationale остаётся в canonical change, archive, registry и Git history; отдельный changelog не создаётся.

2. Сделать Delta Spec scaffold operation-neutral

Единый template не может знать, новая capability или существующая и какая delta operation требуется. Поэтому он не создаёт активные operation headings, а через Markdown comments показывает выбор из ADDED, MODIFIED, REMOVED, RENAMED и условный Purpose. Агент добавляет только применимые sections. Компактная shape guidance перемещается из длинной Specs instruction в template comments; semantic rules полного MODIFIED, полей REMOVED и формата RENAMED остаются в schema.

3. Ввести три machine-distinguishable класса planning failure

Verifier использует стабильные категории результата:

• artifact-validation с exit 1 — artifact существует, но нарушает проверяемую форму или ссылочную целостность; разрешено исправить только указанное нарушение;
• invocation с exit 2 — неверное число аргументов, имя или неразрешимый change; исправляется вызов, а не artifact;
• environment с exit 3 — отсутствует или несовместим runtime, CLI либо другой prerequisite; сначала диагностируется окружение, artifact не меняется.

Project instruction ссылается на эти категории и не вводит retry counter. Unexpected internal failure остаётся blocking result и не маскируется под artifact validation.

4. Разделить structural и semantic качество N/A

Hard guardrail отклоняет пустую причину, одиночный separator и неразрешённый template placeholder. Instruction и template требуют объяснить отсутствие самостоятельного observable behavior, техническую необходимость и связь с утверждённым Design или delivery. Смысл непустого rationale оценивают Change Owner и independent review; blacklist слов и эвристический natural-language checker не добавляются.

5. Использовать CLI-resolved context

Apply instruction прямо требует прочитать все paths из contextFiles, возвращённых native OpenSpec instructions, затем applicable local routing instructions affected areas. Он не вычисляет planning paths и не требует нового context map. Это сохраняет portable CLI state единственным владельцем resolved artifact context.

6. Включить review corpus без дополнительной integrity ceremony

Шесть reports переносятся в новый immutable audit snapshot set без изменения их текста. Короткий index перечисляет sources и известные provenance ограничения; checksum, byte-count manifest и отдельный validation framework не добавляются. Live registry дедуплицирует claims против существующих Audit IDs: повторы получают existing evidence/rationale, а действительно residual gaps — новые follow-up records, связанные с этим change.

7. Проверять сохранение invariants, а не оптимизировать цифру

Verification сопоставляет принятые lifecycle invariants с одним authoritative owner, проверяет compliant и controlled-invalid cases для новых hard guards и фиксирует наблюдаемое удаление duplication. Instruction length может быть сообщена как diagnostic, но не становится blocking threshold. Внешний model score не является completion evidence.

Delivery Map

Area	Status	Architectural outcome or N/A reason
frontend	N/A	Client behavior, implementation и local gate не меняются.
backend	N/A	API behavior, implementation и local gate не меняются.
specs	affected	Schema v3, planning verifier, templates, fixtures и canonical Delta Specs поставляют новый workflow contract.
docs	affected	Второй audit snapshot, live triage и as-built lifecycle documentation отражают поставленный process.

Contract Gate Decision

Gate	Status	Reason
runtime-openapi	N/A	Ни backend runtime contract, ни frontend committed client snapshot не меняются.

Solution Assessment

Change существенно меняет shared agent tooling, поэтому применён обязательный build-versus-buy review.

Option	Fit and maturity	Security / operating cost	Constraints / migration cost	Decision
Native project OpenSpec schema, templates и existing verifier	Полностью сохраняет используемый OpenSpec 1.10.0 graph и уже поставленные project gates.	Не добавляет runtime или data surface; поддерживается текущими local gates.	Требует узкой правки project-owned contracts и controlled fixtures; active changes остаются совместимыми по artifact IDs.	Selected.
Global agent prompt или внешний common-rules file	Может сократить schema text, но загрузка зависит от agent framework и не гарантируется native OpenSpec.	Создаёт competing authority и постоянную стоимость синхронизации.	Потребовал бы projection/versioning discipline и миграцию всех entrypoints.	Rejected.
Дополнительный workflow framework или новые approval/context/done artifacts	Может хранить больше machine-readable state, но дублирует native graph и решает неподтверждённые risks.	Увеличивает process surface и число stale states без security benefit.	Высокая миграционная и эксплуатационная стоимость; конфликт с утверждённой governance.	Rejected.

Native project-local schema выбрана потому, что текущий OpenSpec 1.10.0 contract уже предоставляет используемую extension boundary для artifacts, templates и instructions, а external prompt и дополнительные state artifacts не выполняют утверждённые authority constraints. Review trigger: несовместимое изменение native schema API либо появление поддерживаемого OpenSpec mechanism для общих typed rules и failure classification.

Risks / Trade-offs

• При сокращении потеряется обязательное правило. Mitigation: inventory действующих invariants, authority fixtures и semantic comparison до/после.
• Neutral scaffold даст слишком мало shape guidance. Mitigation: commented operation menu и controlled deltas для всех четырёх operations.
• Failure будет отнесён не к той категории. Mitigation: отдельные controlled failures для artifact, invocation и environment paths; неожиданный failure остаётся blocking.
• Непустой, но слабый N/A пройдёт structural gate. Это осознанный trade-off: semantic approval и independent review остаются владельцами смысла, чтобы эвристика не выдавала false confidence.
• Schema v3 применяется к текущему active change. Mitigation: artifact IDs и dependency graph не меняются; current change повторно проходит planning и strict schema/change validation после migration.

Migration Plan

1. Сначала обновить normative schema contract и operation-neutral template, сохранив artifact IDs и dependency graph.
2. Затем обновить verifier taxonomy и controlled fixtures, после чего повторно проверить active change новым contract.
3. Перенести review corpus в immutable docs snapshot, выполнить deduplicated triage и синхронизировать as-built lifecycle wording.
4. Выполнить canonical gates affected areas, semantic verification и independent read-only review до archive.

Rollback Contract

Field	Decision
Status	N/A
Reason	Изменение обратимо в versioned tooling/docs, не меняет auth, данные, migration или public contract и не требует отдельного rollback contract.
Trigger	N/A
Actions	N/A
Data safety	N/A; application data не затрагиваются.
Verification	N/A