docs: record SDD audit remediation

This commit is contained in:
2026-08-26 00:42:35 +03:00
parent 4dbff85654
commit 72c3a8a668
12 changed files with 1229 additions and 10 deletions
+59 -3
View File
@@ -7,6 +7,12 @@
## Правила работы
- Каждая audit-derived запись имеет один статус: `planned`, `active`, `done`, `deferred` или `accepted`.
- Каждое уникальное external claim дополнительно имеет независимый triage
disposition: `confirmed`, `already-covered`, `rejected` или `deferred`.
Повтор одного underlying claim в нескольких reports получает один Audit ID со
ссылкой на каждый source. Disposition не является remediation status:
`confirmed` ещё может быть active, а `rejected` — accepted как проверенное
решение ничего не внедрять.
- Одновременно допускается не более одного `active` remediation change. Пока он существует, продолжается только он. При наличии `planned` ровно одна запись отмечается следующей рекомендуемой задачей, но она не запускается параллельно active change.
- `done` требует даты, archive path OpenSpec change, commit для каждого затронутого Git-репозитория и точных non-mutating verification commands с observed results.
- `deferred` и `accepted` требуют даты, rationale и review trigger либо ссылки на явное решение владельца.
@@ -16,18 +22,68 @@
- Bootstrap change: [`2026-08-23-establish-audit-remediation-workflow`](../../specs/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/) — `archived`; это process foundation и не закрывает ни одного Audit ID.
- Последний завершённый audit remediation change: [`2026-08-24-harden-agent-sdd-governance`](../../specs/openspec/changes/archive/2026-08-24-harden-agent-sdd-governance/) — `archived`; AUD24-01 и AUD24-03–AUD24-09, а также A-14–A-16 и A-18 закрыты.
- Единственный active change: отсутствует.
- Единственный active change: [`harden-openspec-sdd-quality`](../../specs/openspec/changes/harden-openspec-sdd-quality/) для SDD26-01–SDD26-03, SDD26-09, SDD26-12, SDD26-17, SDD26-21 и SDD26-28–SDD26-30.
## Текущая задача
Создать `assess-auth-platform-options` для AUD24-02.
Завершить `harden-openspec-sdd-quality` без параллельного remediation change.
## Следующая рекомендуемая задача
`assess-auth-platform-options` для AUD24-02. Change применяет Solution Assessment к существующей реализации и зрелым auth platforms, включая Better Auth, и не предрешает миграцию.
После terminal completion текущего active change вернуть
`assess-auth-platform-options` для AUD24-02. Change применяет Solution
Assessment к существующей реализации и зрелым auth platforms, включая Better
Auth, и не предрешает миграцию.
## Реестр findings
### Multi-source assessment WealthLedger SDD 26.08.2026
Raw external reports и checksums находятся в
[immutable snapshot set](../audits/2026-08-26-wealth-ledger-sdd/README.md).
Сокращения источников: [D] — DeepSeek, [G] — Gemini, [K] — Kimi, [Q] — Qwen,
[Z] — Z.AI. Ни одна внешняя рекомендация сама по себе не является project
authority.
| Audit ID | Нормализованный claim | Sources | Disposition | Remediation status | Evidence, rationale или review trigger |
| --- | --- | --- | --- | --- | --- |
| SDD26-01 | Снизить instruction bloat и устранить конкурирующих владельцев общих правил. | [D], [G], [Q], [Z] | confirmed | active | [`harden-openspec-sdd-quality`](../../specs/openspec/changes/harden-openspec-sdd-quality/): schema v2 владеет semantics, templates — shape, config — только facts/language, scripts — hard invariants; отдельный `_rules.md` не вводится. |
| SDD26-02 | Проверять planning format машинно до approval и автоматически исправлять технические ошибки. | [D], [Z] | confirmed | active | Текущий change поставляет stage-aware non-mutating verifier, controlled-invalid fixtures и format-only retry path. |
| SDD26-03 | Каждая task должна иметь однозначную delivery area; multi-repo implementation нужно разделять. | [D], [G], [Z] | confirmed | active | Schema v2 использует `[frontend\|backend\|specs\|docs\|workspace]`; planning verifier отклоняет owner из `N/A` area. |
| SDD26-04 | Добавить `Target Repositories` уже в Proposal. | [G] | rejected | accepted | 2026-08-26; Proposal остаётся owner-readable intent без implementation topology. Полный scope repositories определяется позже через обязательную Design Delivery Map. |
| SDD26-05 | Явно координировать порядок и совместимость multi-repository delivery. | [D], [G] | already-covered | accepted | 2026-08-26; Delivery Map, Contract Gate Decision, Migration Plan и workspace dispatcher уже задают owners, порядок, совместимость API и canonical gates. |
| SDD26-06 | Формализовать trigger для Solution Assessment. | [D] | already-covered | accepted | 2026-08-26; [engineering governance](engineering-governance.md#build-versus-buy) и schema перечисляют auth, security, storage, integrations, observability, caching, concurrency и shared tooling. |
| SDD26-07 | Не допускать Design/Apply по неутверждённым artifacts. | [D], [K], [Z] | already-covered | accepted | 2026-08-26; human approval хранится в разговоре, one-artifact entrypoints останавливаются, downstream approvals каскадно инвалидируются. Фиктивный `approval.md` или status field не создаётся. |
| SDD26-08 | Разрешить partial/diff `MODIFIED` вместо полного requirement block. | [D] | rejected | accepted | 2026-08-26; native OpenSpec archive semantics требуют полного `MODIFIED`; собственный merge format создал бы второй transformation engine и риск потери scenarios. |
| SDD26-09 | Дать компактные примеры сложных delta operations. | [D], [K] | confirmed | active | Schema v2 добавляет `MODIFIED`, `REMOVED` и `RENAMED` examples, сохраняя minimal ADDED-first template. |
| SDD26-10 | Генерировать в `spec.md` placeholders всех delta sections. | [K] | rejected | accepted | 2026-08-26; пустые sections повышают шум и риск неверной операции. Complex forms принадлежат instructions/examples, а template остаётся минимальным. |
| SDD26-11 | Явно определить DoD, verification и archive после Apply. | [D], [K], [Q] | already-covered | accepted | 2026-08-26; [engineering governance](engineering-governance.md#verify-archive-и-completion-evidence), workspace dispatcher, semantic verification, independent review и hard archive blockers уже образуют terminal protocol. Completion Evidence создаётся после факта, не в Tasks. |
| SDD26-12 | Связать каждую task с точными Delta Requirements и отклонять uncovered requirements. | [D], [K] | confirmed | active | Schema v2 использует native identity `capability path — exact Requirement heading`; planning verifier проверяет ссылки и полное покрытие без собственного ID namespace. |
| SDD26-13 | Добавить Fast Track или сокращённую вторую schema для мелких fixes. | [G] | rejected | accepted | 2026-08-26; один lifecycle сохраняет предсказуемые approvals и archive blockers. Пропорциональность обеспечивают `skip_specs`, conditional assessment/rollback и узкие tasks. |
| SDD26-14 | Ограничивать agent context через tool-specific `.aiignore` и список repos из Proposal. | [G] | rejected | accepted | 2026-08-26; это не portable OpenSpec invariant. Context ограничивается Delivery Map, task owner и targeted reads; dependencies/build outputs уже исключаются локальными tool/repository rules. Пересмотреть при наблюдаемом context exhaustion. |
| SDD26-15 | Ввести общий `blocked_by`/`blocks` graph между changes. | [K] | deferred | deferred | Review trigger: первый реальный случай двух одновременно необходимых changes с доказанной ordering dependency, которую нельзя выразить текущим single-active-remediation rule. |
| SDD26-16 | Добавить priority и sizing в Tasks. | [K] | rejected | accepted | 2026-08-26; Tasks уже dependency-ordered и ограничены одной рабочей сессией. Оценочные points не защищают observable invariant и создают неподтверждённую точность. |
| SDD26-17 | Для труднообратимых changes нужен проверяемый rollback contract. | [K] | confirmed | active | Design template и planning verifier требуют trigger/actions/data safety/verification для risk cases либо конкретный `N/A` reason. |
| SDD26-18 | Добавить отдельный multi-repo context mapping file. | [K] | already-covered | accepted | 2026-08-26; native `openspec instructions ... --json` уже возвращает `planningHome`, `contextFiles`, `artifactPaths` и config context. Второй context map дублировал бы CLI state. |
| SDD26-19 | Зафиксировать commit-message convention в schema. | [K] | rejected | accepted | 2026-08-26; commit style не меняет artifact correctness и принадлежит repository delivery policy только при появлении отдельного проверяемого требования. |
| SDD26-20 | Сделать enterprise sections условными, чтобы снизить overhead. | [Q] | already-covered | accepted | 2026-08-26; Solution Assessment уже conditional, rollback допускает содержательный `N/A`; Delivery Map и Contract Gate Decision остаются обязательными, потому что защищают multi-repo scope. |
| SDD26-21 | Добавить явный feedback loop из Design/Apply в ранний затронутый artifact. | [Q] | confirmed | active | Schema v2 и agent entrypoints маршрутизируют intent→Proposal, behavior→Specs, architecture/rollback→Design, decomposition→Tasks и инвалидируют downstream approvals. |
| SDD26-22 | Создавать `blocker.md` и `revision-request.md` при каждом blocker/revision. | [Q] | rejected | accepted | 2026-08-26; новые workflow artifacts не поддерживаются native schema и быстро устаревают. Наблюдаемое основание сообщается Change Owner в разговоре; durable artifact добавится только при реальном повторяемом trigger. |
| SDD26-23 | Требовать regression test для любой изменённой логики и happy-path test для любой новой. | [Q] | already-covered | accepted | 2026-08-26; [risk-based testing](engineering-governance.md#risk-based-testing) требует tests для существенных рисков и regressions, но осознанно отклоняет универсальные малоценные tests ради каждого logic/file change. |
| SDD26-24 | Добавлять Completion Summary в конец Tasks. | [Q] | rejected | accepted | 2026-08-26; Tasks содержат только planned work. Observed results и commits появляются после выполнения в verification/archive evidence, иначе checklist смешивает план и факты. |
| SDD26-25 | Требовать точный текстовый `STOP_PROTOCOL` после каждого artifact. | [Z] | rejected | accepted | 2026-08-26; обязательная остановка и явный approval уже enforced entrypoints. Фиксация одной строки ответа хрупка и не усиливает identity или semantic approval. |
| SDD26-26 | Сократить explanation `planningHome.root` до короткого imperative. | [Z] | rejected | accepted | 2026-08-26; пояснение предотвращает ошибочное вычисление path при store-backed и local modes OpenSpec 1.10. После удаления duplicate config rules instruction source остаётся приемлемым; пересмотреть при измеренном context regression. |
| SDD26-27 | Добавить дополнительные contract gates вроде `internal-proto`. | [G] | deferred | deferred | Review trigger: появление второго реального межсервисного committed contract, для которого `runtime-openapi` и repository gates недостаточны. До этого generic gate будет speculative. |
| SDD26-28 | Root project-owned agent projection должна восстанавливаться из versioned authority. | local triage | confirmed | active | Обнаружено локально: root `.opencode` не принадлежит Git repository. Текущий change добавляет canonical source, atomic sync и exact drift verifier в `specs`. |
| SDD26-29 | Exact OpenSpec version должна быть единым compatibility contract, а не вечным literal в scripts/fixtures. | local triage | confirmed | active | `.cli-version` остаётся единственным current contract; markers/verifiers выводят expected value из него, новая stable не включает auto-upgrade. |
| SDD26-30 | Raw multi-source evidence и triage должны быть versioned раздельно. | local triage | confirmed | active | Пять reports сохранены byte-for-byte в [snapshot set](../audits/2026-08-26-wealth-ledger-sdd/README.md); этот live registry хранит dispositions и statuses отдельно. |
[D]: ../audits/2026-08-26-wealth-ledger-sdd/deepseek-result.md
[G]: ../audits/2026-08-26-wealth-ledger-sdd/gemini-result.md
[K]: ../audits/2026-08-26-wealth-ledger-sdd/kimi-result.md
[Q]: ../audits/2026-08-26-wealth-ledger-sdd/qwen-result.md
[Z]: ../audits/2026-08-26-wealth-ledger-sdd/zai-result.md
### Аудит 13.08.2026
| Audit ID | Текущий статус | Связь и следующее действие | Terminal evidence или trigger |
+45 -1
View File
@@ -14,6 +14,10 @@
**Enforceable Engineering Invariant** — обязательное правило с детерминированной non-mutating локальной проверкой, нарушение которой блокирует завершение change. Непроверяемое предпочтение является guidance, а не hard guardrail.
**Planning structural gate** — stage-aware проверка доступной формы и ссылочной
целостности текущего planning artifact до запроса approval. Она не оценивает
качество rationale и не является semantic approval.
## Последовательность SDD
Каждый versioned change проходит один граф:
@@ -25,10 +29,21 @@ Proposal → Delta Specs → Design → Tasks → Apply → Verify → Archive
- Proposal формулирует намерение, границы и ожидаемый результат без технологий, API, файлов и зависимостей.
- Delta Specs описывают изменение наблюдаемого поведения и инвариантов без изменений кода.
- Design объясняет архитектурный способ реализации крупными частями, риски и альтернативы; он не является построчной инструкцией.
- Tasks — implementation checklist, достаточный для выполнения Design и Specs. Он содержит планируемые проверки, но не будущие результаты, commits или post-archive bookkeeping.
- Tasks — implementation checklist, достаточный для выполнения Design и Specs.
Каждый checkbox объявляет ровно одну area, `Covers` ссылается на native
identity `capability path — exact Requirement heading` либо объясняет `N/A`,
а `Verification` задаёт планируемую проверку. Tasks не содержат будущие
результаты, commits или post-archive bookkeeping.
AI-агент готовит только текущий разрешённый артефакт, показывает его Change Owner и останавливается. Downstream artifact создаётся только после явного approval. Если новая сессия не может подтвердить approval из доступного контекста, агент запрашивает его повторно.
До запроса approval агент запускает доступный stage planning gate и сам
исправляет технические ошибки формата. Полный change validation не объявляется
успешным, пока downstream artifacts отсутствуют. Форматное исправление без
изменения intent, behavior, decisions или task scope не требует reapproval;
семантическое изменение возвращает workflow к самому раннему затронутому
artifact.
Изменение принятого upstream artifact инвалидирует approval зависимых артефактов: Proposal — Specs, Design и Tasks; Specs — Design и Tasks; Design — Tasks. Tasks не могут неявно расширять scope или менять поведение и архитектуру: работа возвращается к соответствующему upstream artifact.
## Delivery Map и multi-repository delivery
@@ -42,6 +57,12 @@ Design каждого change оценивает все четыре област
Change остаётся active, пока каждая affected область не реализована и не прошла свой canonical gate. Design содержит Contract Gate Decision: `runtime-openapi` имеет статус `required`, когда изменение затрагивает frontend и backend стороны API contract, иначе `N/A` с конкретной причиной. Успех одного репозитория не компенсирует отсутствие или failure другого.
Task owner выбирается только из `frontend`, `backend`, `specs`, `docs` и
`workspace`. Repository owner нельзя использовать для area со статусом `N/A`;
cross-repository implementation разбивается на отдельные tasks. `workspace`
владеет только orchestration и verification, но не подменяет repository-owned
implementation или canonical gates.
## Risk-based testing
Автоматизированный тест обязателен, когда изменение затрагивает хотя бы один существенный риск:
@@ -75,6 +96,17 @@ Solution Assessment сравнивает применимые варианты
Собственная реализация допустима, только если подходящего решения нет или доказана существенная несовместимость. Тогда Design фиксирует проверенные варианты, конкретные gaps, принятые риски и trigger повторного рассмотрения. Для обратимого изменения вне перечисленных областей отдельная формальная оценка не создаётся ради процесса.
## Rollback contract
Design фиксирует status `required`, trigger, actions, data safety и verification,
если change меняет auth/security behavior, data integrity или migration, public
contract либо другое существенно труднообратимое решение. Contract учитывает
данные и compatibility, созданные после delivery, и не может зависеть от нового
неутверждённого архитектурного решения.
Для обратимого change вне этих рисков status `N/A` содержит конкретную причину.
Отдельный rollback artifact не создаётся ради процесса.
## Single Source of Truth
| Вид знания | Authoritative location |
@@ -85,6 +117,7 @@ Solution Assessment сравнивает применимые варианты
| Текущее устройство и поставленные возможности | `docs/architecture` и `docs/features` |
| Устойчивые архитектурные решения и причины | `docs/adr` |
| Инженерная policy и completion evidence | `docs/development` |
| Canonical source project-owned agent commands и skills | `specs/agent-projection/opencode` |
| Компактная маршрутизация AI-агентов | root и repository-local `AGENTS.md` |
`docs` описывает только фактическое текущее состояние и не пересказывает Proposal, Delta Specs, Design или Tasks другим форматом. `AGENTS.md` не копирует архитектуру или feature documentation: он направляет к authority и перечисляет только применимые hard constraints и canonical commands.
@@ -104,6 +137,17 @@ CI пока отсутствует, поэтому обязательные gate
Hard guardrail должен иметь исполняемую локальную проверку. Правило без надёжной проверки помечается как guidance и учитывается в review, но не выдаётся за автоматический запрет. Новые frameworks, checkers и thresholds добавляются только после оценки поддерживаемого решения, maintenance cost и реально защищаемого риска.
Root `.opencode/commands` и `.opencode/skills` являются derived projection.
Изменения вносятся в versioned source под `specs`, распространяются explicit
atomic sync и проверяются exact file/content comparison; package manifests,
dependencies и machine-local state не являются authority inputs.
Текущая exact OpenSpec CLI version читается только из
`specs/openspec/.cli-version`. Новая stable release не меняет contract
автоматически. Upgrade выполняется отдельным SDD change после isolated проверки
schema, agent projection, canonical store и positive/negative fixtures;
историческое evidence сохраняет фактическую прежнюю version.
## Verify, archive и Completion Evidence
Structural validation OpenSpec проверяет schema и форму артефактов, но не соответствие реализации. До archive обязательны:
@@ -19,10 +19,15 @@ bash specs/scripts/verify-openspec-version.sh
```
Несовпадение version блокирует операцию до чтения или изменения store.
Публикация новой stable версии не меняет этот contract автоматически. Upgrade
выполняется отдельным SDD change после staged проверки schema, instructions,
project-owned projection, store resolution и hard blockers; historical archives
не переписываются.
## Project-local schema
Новые changes по умолчанию используют schema `wealth-ledger-sdd` из `specs/openspec/schemas/wealth-ledger-sdd`. Её граф:
Новые changes по умолчанию используют schema `wealth-ledger-sdd` version 2 из
`specs/openspec/schemas/wealth-ledger-sdd`. Её граф:
```text
proposal → specs → design → tasks → apply
@@ -30,6 +35,18 @@ proposal → specs → design → tasks → apply
OpenSpec обеспечивает structural order, а явное решение Change Owner — переход между артефактами. Agent создаёт один текущий artifact и останавливается для approval. Роли артефактов и cascade rules определены в governance policy; исполняемые templates и instructions принадлежат schema.
До запроса approval выполняется доступная stage-aware проверка:
```bash
bash specs/scripts/verify-openspec-planning.sh <change>
```
Proposal проверяется без ложного объявления полного change success; по мере
появления Specs, Design и Tasks добавляются strict validation, Delivery Map,
rollback, area ownership и exact Requirement coverage. Технический format
failure исправляется и проверяется повторно; structural success не означает
approval.
Project-local schema проверяется из `specs`:
```bash
@@ -41,9 +58,30 @@ openspec schema which wealth-ledger-sdd --json
## Agent entrypoints и обновление OpenSpec
Root `.opencode` — generated local projection OpenSpec 1.10 с минимальными WealthLedger overlays: fixed store, one-artifact-at-a-time и hard archive blockers. Она не является SSOT, потому что workspace root не versioned.
Canonical source WealthLedger-owned OpenCode commands и skills находится в
`specs/agent-projection/opencode`. Root `.opencode/commands` и
`.opencode/skills` — derived local projection с минимальными overlays: fixed
store, one-artifact-at-a-time, stage planning gate, Apply feedback routing и
hard archive blockers. Package manifests, installed dependencies и machine-local
state не входят в source.
`openspec update` не запускается напрямую из workspace root. Новую upstream version сначала генерируют в isolated staging, сравнивают с projection, переносят upstream delta и повторно накладывают project overlays. После этого обязательно выполняют authority fixtures; permissive archive, conditional store selection и второй `openspec` root считаются failures.
Projection восстанавливается и проверяется из workspace root:
```bash
bash specs/scripts/sync-agent-projection.sh
bash specs/scripts/verify-agent-projection.sh
```
Sync выполняет verified cutover и восстанавливает прежнее local state при
ошибке. Verifier non-mutating сравнивает required file set и contents и получает
expected `generatedBy` marker из `.cli-version`.
`openspec update` не запускается напрямую из workspace root. Новую upstream
version сначала генерируют в isolated staging, сравнивают с canonical source,
переносят upstream delta и повторно накладывают минимальные project overlays.
После этого sync обновляет derived root, а authority fixtures проверяют marker,
missing/content drift, permissive archive, conditional store selection и второй
`openspec` root как failures.
## Реализация и проверка change
@@ -55,10 +93,16 @@ bash specs/scripts/verify-workspace-change.sh <change>
`specs` проверяется всегда. Dispatcher читает явный Contract Gate Decision из Design и сравнивает backend runtime OpenAPI с committed frontend snapshot только при `runtime-openapi: required`; этот status допустим лишь при affected frontend и backend. Child failure блокирует общий результат; fallback и auto-fix отсутствуют.
Перед affected-area gates dispatcher повторяет planning verifier. Tasks имеют
формат `X.Y [area] action` и indented `Covers`/`Verification`; каждый Delta
Requirement покрывается точной ссылкой хотя бы один раз, а `workspace` остаётся
только owner orchestration/verification.
Перед archive отдельно подтверждаются structural и semantic gates:
```bash
bash specs/scripts/verify-openspec-authority.sh
bash specs/scripts/verify-agent-projection.sh
openspec validate <change> --type change --strict --store wealth-ledger-specs
openspec validate --specs --strict --store wealth-ledger-specs
```