feat: harden OpenSpec agent resilience
This commit is contained in:
@@ -0,0 +1,185 @@
|
||||
## 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 |
|
||||
Reference in New Issue
Block a user