docs: simplify OpenSpec agent entrypoints
This commit is contained in:
@@ -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 остаётся человеческим
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 <change> --type change --strict --store wealth-ledger-specs
|
||||
openspec validate --specs --strict --store wealth-ledger-specs
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user