From eb0a96e27c072e53f5c01db5a810502c104e8e6c Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Wed, 26 Aug 2026 00:52:55 +0300 Subject: [PATCH] docs: simplify OpenSpec agent entrypoints --- ...ve-openspec-sdd-and-local-orchestration.md | 15 ++++----- development/audit-remediation.md | 4 +-- development/engineering-governance.md | 13 ++++---- .../openspec-authority-and-lifecycle.md | 32 ++++++------------- 4 files changed, 24 insertions(+), 40 deletions(-) diff --git a/adr/010-native-openspec-sdd-and-local-orchestration.md b/adr/010-native-openspec-sdd-and-local-orchestration.md index 053ba2c..7eb742d 100644 --- a/adr/010-native-openspec-sdd-and-local-orchestration.md +++ b/adr/010-native-openspec-sdd-and-local-orchestration.md @@ -16,19 +16,18 @@ monorepo control plane для четырёх независимых Git-репо - Встроенная `spec-driven` schema отклонена: она не выражает обязательный переход Specs перед Design и не задаёт Delivery Map или проектные роли артефактов. - Отдельный workflow engine или custom generator отклонён: он создал бы конкурирующий формат и lifecycle authority. - Nx, Turborepo, Bazel, Make или just отклонены для текущего масштаба: workspace не имеет общего dependency graph, build cache или CI, а репозитории уже владеют canonical gates. -- Patch-only, programmatic generator и symlink для root agent projection - отклонены из-за upstream text fragility, второго transformation engine либо - tool/filesystem portability. Выбран committed canonical source tree с - explicit atomic sync и exact drift check. +- Versioned source tree, patch-only, programmatic generator и symlink для root + agent entrypoints отклонены для текущего масштаба: они добавляют отдельный + projection lifecycle поверх уже достаточных schema, docs и scripts. ## Последствия OpenSpec CLI закреплён exact version contract; новая stable release не включает auto-upgrade, а смена contract является отдельным SDD change со staged -compatibility fixtures. Project-owned commands и skills имеют versioned source -в `specs`, root `.opencode` является derived projection. Planning verifier до -approval проверяет только детерминированную структуру: capability set, Delivery -Map, rollback, task area и Requirement coverage. +compatibility fixtures. Root `.opencode` остаётся локальным non-authority +entrypoint, а hard constraints проверяются через authority verifier. Planning +verifier до approval проверяет только детерминированную структуру: capability +set, Delivery Map, rollback, task area и Requirement coverage. Dispatcher знает четыре workspace area, но не реализует build или test logic: он делегирует repo-owned commands. Approval identity остаётся человеческим diff --git a/development/audit-remediation.md b/development/audit-remediation.md index fc53441..7e7fa51 100644 --- a/development/audit-remediation.md +++ b/development/audit-remediation.md @@ -73,7 +73,7 @@ authority. | 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 | done | 2026-08-26; root `.opencode` projection получает canonical source, atomic sync и exact drift verifier в `specs`. | +| SDD26-28 | Root project-owned agent projection должна восстанавливаться из versioned authority. | local triage | confirmed | done | 2026-08-26; superseded by follow-up cleanup: root `.opencode` остаётся local non-authority entrypoint без versioned projection source; hard constraints остаются в schema, docs и authority verifier. | | SDD26-29 | Exact OpenSpec version должна быть единым compatibility contract, а не вечным literal в scripts/fixtures. | local triage | confirmed | done | 2026-08-26; `.cli-version` остаётся единственным current contract; markers/verifiers выводят expected value из него, новая stable не включает auto-upgrade. | | SDD26-30 | Raw multi-source evidence и triage должны быть versioned раздельно. | local triage | confirmed | done | 2026-08-26; пять reports сохранены byte-for-byte в [snapshot set](../audits/2026-08-26-wealth-ledger-sdd/README.md); live registry хранит dispositions и statuses отдельно. | @@ -172,7 +172,7 @@ Change синхронизирован в canonical specs и архивирова - Delivery Map: frontend `N/A`, backend `N/A`, specs affected, docs affected; runtime OpenAPI contract gate `N/A`, потому что application runtime API и generated client не менялись. - Затронутые Git-репозитории: specs `a8b2c4eed988f7e1a7b3d6b7188bbe6791f00e2a` (`feat: harden OpenSpec SDD workflow`), docs delivery `72c3a8a6683b95f7e734044fdabe568668097c33` (`docs: record SDD audit remediation`); terminal evidence фиксируется следующим docs commit. - Pre-archive `bash specs/scripts/verify-workspace-change.sh harden-openspec-sdd-quality` под Node 22.21.0 — passed: Delivery Map verified frontend/backend `N/A`, specs/docs affected, runtime-openapi `N/A`; OpenSpec CLI 1.10.0 verified; planning coverage 9/9; schema valid; change valid; main specs 20/20; authority verified; docs `npm run verify` passed with 36 Markdown files and 0 issues. -- Controlled fixture suites: `bash specs/scripts/verify-agent-projection.test.sh` — passed; `bash specs/scripts/verify-openspec-authority.test.sh` — passed with expected controlled-negative failures. +- Controlled fixture suites: `bash specs/scripts/verify-agent-projection.test.sh` — passed at delivery time; follow-up cleanup later removed the projection layer. `bash specs/scripts/verify-openspec-authority.test.sh` — passed with expected controlled-negative failures. - Archive: `openspec archive harden-openspec-sdd-quality -y --store wealth-ledger-specs` — updated `audit-remediation-workflow`, `engineering-change-governance`, `multi-repository-delivery` and `openspec-authority-and-lifecycle`; archived as `2026-08-26-harden-openspec-sdd-quality`. - Post-archive verification: `openspec validate --specs --strict --store wealth-ledger-specs` — 20 passed, 0 failed; `bash specs/scripts/verify-openspec-authority.sh` — passed; `openspec schema validate wealth-ledger-sdd --verbose` — passed; `PATH=/Users/ksv741/.nvm/versions/node/v22.21.0/bin:$PATH npm run verify` in `docs` — passed. - Semantic verification: Proposal, all 9 Delta Spec requirements, 28 scenarios, Design and 18/18 tasks matched implementation. Independent read-only review found no Critical or Important findings. diff --git a/development/engineering-governance.md b/development/engineering-governance.md index 14ee7e7..e241ea8 100644 --- a/development/engineering-governance.md +++ b/development/engineering-governance.md @@ -117,8 +117,7 @@ contract либо другое существенно труднообратим | Текущее устройство и поставленные возможности | `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` | +| Компактная маршрутизация AI-агентов и локальные entrypoints | root/repository-local `AGENTS.md` и workspace `.opencode` | `docs` описывает только фактическое текущее состояние и не пересказывает Proposal, Delta Specs, Design или Tasks другим форматом. `AGENTS.md` не копирует архитектуру или feature documentation: он направляет к authority и перечисляет только применимые hard constraints и canonical commands. @@ -137,15 +136,15 @@ 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. +Root `.opencode/commands` и `.opencode/skills` являются локальными +non-authority entrypoints. Они должны соблюдать fixed store, version preflight, +one-artifact approvals и hard archive blockers, но не имеют отдельного +versioned projection source. Текущая exact OpenSpec CLI version читается только из `specs/openspec/.cli-version`. Новая stable release не меняет contract автоматически. Upgrade выполняется отдельным SDD change после isolated проверки -schema, agent projection, canonical store и positive/negative fixtures; +schema, agent workflow, canonical store и positive/negative fixtures; историческое evidence сохраняет фактическую прежнюю version. ## Verify, archive и Completion Evidence diff --git a/development/openspec-authority-and-lifecycle.md b/development/openspec-authority-and-lifecycle.md index a11a255..c72419d 100644 --- a/development/openspec-authority-and-lifecycle.md +++ b/development/openspec-authority-and-lifecycle.md @@ -21,7 +21,7 @@ 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 +agent workflow, store resolution и hard blockers; historical archives не переписываются. ## Project-local schema @@ -58,29 +58,16 @@ openspec schema which wealth-ledger-sdd --json ## Agent entrypoints и обновление OpenSpec -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. - -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`. +Root `.opencode/commands` и `.opencode/skills` — локальные non-authority +entrypoints. Они удобны для работы агента, но не являются SDD source of truth и +не имеют отдельного versioned projection source. Нормативный contract хранится +в schema, `AGENTS.md`, governance и non-mutating scripts. `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 и второй +version сначала проверяют в isolated staging и повторно накладывают минимальные +project constraints: fixed store, one-artifact-at-a-time, stage planning gate, +Apply feedback routing и hard archive blockers. Authority fixtures проверяют +version preflight, permissive archive, conditional store selection и второй `openspec` root как failures. ## Реализация и проверка change @@ -102,7 +89,6 @@ Requirement покрывается точной ссылкой хотя бы о ```bash bash specs/scripts/verify-openspec-authority.sh -bash specs/scripts/verify-agent-projection.sh openspec validate --type change --strict --store wealth-ledger-specs openspec validate --specs --strict --store wealth-ledger-specs ```