186 lines
13 KiB
Markdown
186 lines
13 KiB
Markdown
## 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 |
|