From 04a07b390f73412a5d376c0051253da25481f1a3 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Mon, 7 Sep 2026 22:22:13 +0300 Subject: [PATCH] Implement bounded SDD planning and apply context --- AGENTS.md | 19 ++++----- .../optimize-session-oriented-sdd-v2/tasks.md | 40 +++++++++---------- .../schemas/wealth-ledger-sdd/schema.yaml | 17 ++++++-- 3 files changed, 44 insertions(+), 32 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ec65fde..9c3bcb5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,26 +2,25 @@ ## Назначение и authority -Этот репозиторий — единственный versioned SDD authority. Shared SDD policy, -common reading pointers, audit routing и `../references/**` policy задаёт root -`AGENTS.md`. +Этот репозиторий — единственный versioned authority для change artifacts. +Workspace layout и reference policy — в root `AGENTS.md`. Canonical OpenSpec store — `wealth-ledger-specs`, физический root от workspace — `specs/openspec` (локально `openspec`). OpenSpec commands, читающие или изменяющие change, всегда получают `--store wealth-ledger-specs`. -Proposal, Delta Specs, Design, Tasks, changes и archives хранятся в `openspec`. -`docs` хранит as-built state и Completion Evidence, но не копию change artifacts. +Proposal, Delta Specs, Design, Tasks, changes, Completion Evidence и archives +хранятся в `openspec`; `docs` владеет as-built документацией и общей policy. ## Workflow и verification -Новые changes используют project-local schema `wealth-ledger-sdd`. Артефакты создаются по -одному после approval Change Owner. Lifecycle: +Новые changes используют project-local schema `wealth-ledger-sdd`. +Для planning, implementation, validation и завершения читай canonical lifecycle: [`../docs/development/openspec-authority-and-lifecycle.md`](../docs/development/openspec-authority-and-lifecycle.md). Сначала определить current stage и capability paths через native OpenSpec instruction; читать main specs и supporting docs только для этих paths и -affected areas. Подробный token-efficient routing загружается по необходимости +affected areas. Recovery и выбор relevant evidence определяет context discipline из [`../docs/development/agent-token-efficiency.md`](../docs/development/agent-token-efficiency.md), а не дублируется в schema instructions. @@ -33,7 +32,9 @@ openspec validate --type change --strict --store wealth-ledger-specs openspec validate --specs --strict --store wealth-ledger-specs ``` -Structural validation не заменяет semantic verification и independent read-only review. Tasks отмечаются только после выполненной работы; archive не допускает unchecked tasks или verification override. +Под Node 22: если локальной `.nvmrc` нет, активировать frontend `.nvmrc` +через `nvm use --silent` до перехода в specs. Native structural gate проверяет +форму; terminal safeguards определяет canonical lifecycle, доступный без skills. ## Boundaries diff --git a/openspec/changes/optimize-session-oriented-sdd-v2/tasks.md b/openspec/changes/optimize-session-oriented-sdd-v2/tasks.md index 6db47dc..5ff51a9 100644 --- a/openspec/changes/optimize-session-oriented-sdd-v2/tasks.md +++ b/openspec/changes/optimize-session-oriented-sdd-v2/tasks.md @@ -1,74 +1,74 @@ ## 1. OpenSpec-native planning and Apply context -- [ ] 1.1 [specs] Обновить project-local `wealth-ledger-sdd` schema metadata и зависимость Tasks с `design` на `design + specs`, чтобы native Tasks instructions возвращали утверждённый Design и все Delta Specs, необходимые для exact `Covers` +- [x] 1.1 [specs] Обновить project-local `wealth-ledger-sdd` schema metadata и зависимость Tasks с `design` на `design + specs`, чтобы native Tasks instructions возвращали утверждённый Design и все Delta Specs, необходимые для exact `Covers` - **Covers:** `agent-sdd-session-workflow` — `Продолжение workflow восстанавливает только нужный контекст`; `agent-sdd-session-workflow` — `Handoff не заменяет canonical OpenSpec authority` - **Verification:** `openspec instructions tasks --change optimize-session-oriented-sdd-v2 --store wealth-ledger-specs` возвращает dependency paths Design и Delta Specs без дополнительных planning artifacts; `openspec schema validate wealth-ledger-sdd --verbose` -- [ ] 1.2 [specs] Дополнить только `apply.instruction` bounded Implementation semantics: выбирать связный batch pending Tasks, сохранять checkpoint при remaining work и выдавать `READY_FOR_VALIDATION` только после завершения всех implementation-owned Tasks и релевантных checks +- [x] 1.2 [specs] Дополнить только `apply.instruction` bounded Implementation semantics: выбирать связный batch pending Tasks, сохранять checkpoint при remaining work и выдавать `READY_FOR_VALIDATION` только после завершения всех implementation-owned Tasks и релевантных checks - **Covers:** `agent-sdd-session-workflow` — `Implementation сохраняет ограниченные checkpoints` - **Verification:** `openspec instructions apply --change optimize-session-oriented-sdd-v2 --store wealth-ledger-specs` различает checkpoint и `READY_FOR_VALIDATION`, сохраняет чтение CLI-resolved `contextFiles` и не запускает Validation или Finalization ## 2. Vendor-neutral engineering authority -- [ ] 2.1 [docs] Обновить engineering lifecycle authority: зафиксировать bounded Specification approvals, нормальный Implementation checkpoint, независимую Validation и Finalization, которая потребляет только актуальный input-bound `PASS` +- [x] 2.1 [docs] Обновить engineering lifecycle authority: зафиксировать bounded Specification approvals, нормальный Implementation checkpoint, независимую Validation и Finalization, которая потребляет только актуальный input-bound `PASS` - **Covers:** `agent-sdd-session-workflow` — `Каждая agent-сессия имеет одну SDD-роль`; `agent-sdd-session-workflow` — `Implementation сохраняет ограниченные checkpoints`; `agent-sdd-session-workflow` — `Validation остаётся независимой и без побочных исправлений`; `agent-sdd-session-workflow` — `Finalization требует успешной независимой Validation` - **Verification:** Scoped documentation review прослеживает каждую transition и blocker к одной ответственной роли без повторной Validation или side-effect repair -- [ ] 2.2 [docs] Обновить authority context discipline для recovery из одного актуального envelope, fingerprint-bound approval, bounded evidence reads и запрета копировать canonical artifacts в handoff +- [x] 2.2 [docs] Обновить authority context discipline для recovery из одного актуального envelope, fingerprint-bound approval, bounded evidence reads и запрета копировать canonical artifacts в handoff - **Covers:** `agent-sdd-session-workflow` — `Продолжение workflow восстанавливает только нужный контекст`; `agent-sdd-session-workflow` — `Handoff не заменяет canonical OpenSpec authority` - **Verification:** Scoped documentation review подтверждает порядок canonical outcome → immutable record → state pointer, invalidation при fingerprint mismatch и чтение старых records только для конкретного расследования -- [ ] 2.3 [docs] Перенести durable completion semantics к canonical archive и согласовать remediation registry и documentation indexes с ссылкой на archived Completion Evidence без отдельного evidence store +- [x] 2.3 [docs] Перенести durable completion semantics к canonical archive и согласовать remediation registry и documentation indexes с ссылкой на archived Completion Evidence без отдельного evidence store - **Covers:** `project-documentation` — `Completion Evidence сохраняет фактическое завершение change`; `project-documentation` — `OpenSpec change закрывается только после полной верификации`; `project-documentation` — `Документация процесса содержит remediation registry` - **Verification:** Scoped link and ownership review подтверждает, что registry сохраняет source audit, status, related change и next task, а completed entry ссылается на canonical archive вместо дублирования commits и gate results ## 3. Active repository entrypoints -- [ ] 3.1 [frontend] Свести frontend active instructions к ссылке на vendor-neutral lifecycle/context authorities, frontend boundaries и canonical local gate без копии shared SDD policy +- [x] 3.1 [frontend] Свести frontend active instructions к ссылке на vendor-neutral lifecycle/context authorities, frontend boundaries и canonical local gate без копии shared SDD policy - **Covers:** `agent-sdd-session-workflow` — `Активные инструкции согласованы и независимы от agent runtime` - **Verification:** Frontend entrypoint остаётся достаточным для выбора canonical workflow и local gate без обращения к optional skill или vendor-specific command -- [ ] 3.2 [backend] Свести backend active instructions к ссылке на vendor-neutral lifecycle/context authorities, backend boundaries и canonical local gate без копии shared SDD policy +- [x] 3.2 [backend] Свести backend active instructions к ссылке на vendor-neutral lifecycle/context authorities, backend boundaries и canonical local gate без копии shared SDD policy - **Covers:** `agent-sdd-session-workflow` — `Активные инструкции согласованы и независимы от agent runtime` - **Verification:** Backend entrypoint остаётся достаточным для выбора canonical workflow и local gate без обращения к optional skill или vendor-specific command -- [ ] 3.3 [specs] Согласовать specs active instructions с canonical lifecycle authority, fixed store, one-artifact approvals, native stage routing и specs gate без дублирования общей policy +- [x] 3.3 [specs] Согласовать specs active instructions с canonical lifecycle authority, fixed store, one-artifact approvals, native stage routing и specs gate без дублирования общей policy - **Covers:** `agent-sdd-session-workflow` — `Активные инструкции согласованы и независимы от agent runtime` - **Verification:** Specs entrypoint направляет к `wealth-ledger-specs`, native OpenSpec instructions и canonical validation без обязательного runtime adapter -- [ ] 3.4 [docs] Согласовать docs active instructions с canonical lifecycle authority, as-built ownership, remediation routing и docs gate без дублирования общей policy +- [x] 3.4 [docs] Согласовать docs active instructions с canonical lifecycle authority, as-built ownership, remediation routing и docs gate без дублирования общей policy - **Covers:** `agent-sdd-session-workflow` — `Активные инструкции согласованы и независимы от agent runtime`; `project-documentation` — `Документация процесса содержит remediation registry` - **Verification:** Docs entrypoint однозначно различает canonical planning authority, as-built documentation и remediation registry и не требует optional runtime adapter -- [ ] 3.5 [workspace] Свести root routing и optional command entrypoints к vendor-neutral authorities, fixed canonical store и repository-local boundaries +- [x] 3.5 [workspace] Свести root routing и optional command entrypoints к vendor-neutral authorities, fixed canonical store и repository-local boundaries - **Covers:** `N/A` — workspace orchestration реализует утверждённое Design-разделение canonical core и optional adapters, но не добавляет самостоятельного observable requirement - **Verification:** Из root entrypoint можно определить SDD phase, canonical authority и affected repository gates без vendor-specific command tree ## 4. Optional session adapters -- [ ] 4.1 [workspace] Обновить `.agents/skills/sdd-session/SKILL.md` и `.agents/skills/sdd-session/references/workflow-protocol.md`: добавить observed approval status, artifact identity и стабильный fingerprint в navigation envelope, downstream invalidation, безопасный recovery legacy state и точный phase routing +- [x] 4.1 [workspace] Обновить `.agents/skills/sdd-session/SKILL.md` и `.agents/skills/sdd-session/references/workflow-protocol.md`: добавить observed approval status, artifact identity и стабильный fingerprint в navigation envelope, downstream invalidation, безопасный recovery legacy state и точный phase routing - **Covers:** `N/A` — workspace navigation adapter технически реализует утверждённые Design decisions для approval recovery, тогда как normative behavior принадлежит canonical specs - **Verification:** Контролируемые `sdd-session` protocol scenarios показывают продолжение при совпадающем fingerprint, повторный запрос при отсутствии binding, invalidation при изменении artifact и маршрутизацию ровно в одну роль -- [ ] 4.2 [workspace] Обновить `.agents/skills/sdd-specification/SKILL.md` для пар `Proposal + Delta Specs` и `Design + Tasks`, сохранив отдельную explicit approval boundary перед каждым downstream artifact и запрет перехода к Implementation до approval Tasks +- [x] 4.2 [workspace] Обновить `.agents/skills/sdd-specification/SKILL.md` для пар `Proposal + Delta Specs` и `Design + Tasks`, сохранив отдельную explicit approval boundary перед каждым downstream artifact и запрет перехода к Implementation до approval Tasks - **Covers:** `N/A` — optional Specification orchestration проецирует approved canonical lifecycle и не создаёт отдельного requirement surface - **Verification:** `sdd-specification` scenarios проходят четыре approval boundaries, разрешают bounded продолжение внутри одной роли и останавливаются до Implementation без отдельного approval Tasks -- [ ] 4.3 [workspace] Обновить `.agents/skills/sdd-implementation/SKILL.md` для выбора связного batch, фиксации completed/remaining Tasks и checkpoint outcome без ложного blocker или преждевременного `READY_FOR_VALIDATION` +- [x] 4.3 [workspace] Обновить `.agents/skills/sdd-implementation/SKILL.md` для выбора связного batch, фиксации completed/remaining Tasks и checkpoint outcome без ложного blocker или преждевременного `READY_FOR_VALIDATION` - **Covers:** `N/A` — optional Implementation orchestration реализует approved checkpoint architecture, а observable invariant остаётся в canonical spec - **Verification:** `sdd-implementation` scenarios различают checkpoint с remaining implementation work и `READY_FOR_VALIDATION` только после завершения всех implementation-owned Tasks и релевантных checks -- [ ] 4.4 [workspace] Обновить `.agents/skills/sdd-validation/SKILL.md`: сохранить read-only boundary относительно production implementation, planning artifacts и Tasks и связать `PASS`, `FAIL`, `SPEC_ISSUE` с identity проверенных planning/delivery inputs +- [x] 4.4 [workspace] Обновить `.agents/skills/sdd-validation/SKILL.md`: сохранить read-only boundary относительно production implementation, planning artifacts и Tasks и связать `PASS`, `FAIL`, `SPEC_ISSUE` с identity проверенных planning/delivery inputs - **Covers:** `N/A` — optional Validation orchestration реализует approved independent-verdict architecture без нового spec-level behavior - **Verification:** `sdd-validation` scenarios не выполняют repair mutations, сохраняют input binding и направляют каждый verdict к Finalization, Implementation либо самой ранней Specification boundary -- [ ] 4.5 [workspace] Обновить `.agents/skills/sdd-finalization/SKILL.md`: проверять свежесть `PASS`, точно маршрутизировать blockers и формировать Completion Evidence внутри active canonical change только из уже существующих фактов перед archive +- [x] 4.5 [workspace] Обновить `.agents/skills/sdd-finalization/SKILL.md`: проверять свежесть `PASS`, точно маршрутизировать blockers и формировать Completion Evidence внутри active canonical change только из уже существующих фактов перед archive - **Covers:** `N/A` — optional Finalization orchestration реализует approved completion mechanics; normative archive safeguards принадлежат canonical specs - **Verification:** `sdd-finalization` scenarios блокируют missing/stale `PASS`, unchecked implementation task и incomplete evidence, не повторяют актуальную Validation, архивируют Completion Evidence вместе с change и оставляют retryable completion failure в Finalization ## 5. Affected-area gates and workflow consistency -- [ ] 5.1 [frontend] Выполнить frontend canonical gate после изменения repository-local active instructions +- [x] 5.1 [frontend] Выполнить frontend canonical gate после изменения repository-local active instructions - **Covers:** `N/A` — это обязательная проверка affected frontend delivery, а не самостоятельное observable behavior - **Verification:** `npm run verify` под frontend `.nvmrc` -- [ ] 5.2 [backend] Выполнить backend canonical gate после изменения repository-local active instructions +- [x] 5.2 [backend] Выполнить backend canonical gate после изменения repository-local active instructions - **Covers:** `N/A` — это обязательная проверка affected backend delivery, а не самостоятельное observable behavior - **Verification:** `npm run verify` под backend `.nvmrc` -- [ ] 5.3 [specs] Выполнить native strict validation schema, active change и main specs в canonical store после реализации specs-owned work +- [x] 5.3 [specs] Выполнить native strict validation schema, active change и main specs в canonical store после реализации specs-owned work - **Covers:** `N/A` — это обязательный canonical gate affected specs delivery и structural proof, не новое requirement - **Verification:** `openspec schema validate wealth-ledger-sdd --verbose`; `openspec validate optimize-session-oriented-sdd-v2 --type change --strict --store wealth-ledger-specs`; `openspec validate --specs --strict --store wealth-ledger-specs` -- [ ] 5.4 [docs] Выполнить docs canonical gate и scoped local-link review после изменения governance, context authority и remediation navigation +- [x] 5.4 [docs] Выполнить docs canonical gate и scoped local-link review после изменения governance, context authority и remediation navigation - **Covers:** `N/A` — это обязательная проверка affected docs delivery и ссылочной целостности, а не самостоятельное observable behavior - **Verification:** `npm run verify` под docs `.nvmrc`; scoped review изменённых local links -- [ ] 5.5 [workspace] Проверить согласованность всех active entrypoints и достижимость canonical planning, implementation, validation и finalization outcomes без optional runtime adapters +- [x] 5.5 [workspace] Проверить согласованность всех active entrypoints и достижимость canonical planning, implementation, validation и finalization outcomes без optional runtime adapters - **Covers:** `N/A` — cross-area orchestration проверяет vendor-neutral delivery согласно Design, но не подменяет independent Validation и не создаёт новый requirement - **Verification:** Из clean shell пройти routing для каждой SDD-роли через canonical docs, native OpenSpec instructions и repository gates без вызова optional skills/commands; выполнить scoped semantic review против approved Delta Specs и Design diff --git a/openspec/schemas/wealth-ledger-sdd/schema.yaml b/openspec/schemas/wealth-ledger-sdd/schema.yaml index 9ef7dcb..f0ead9f 100644 --- a/openspec/schemas/wealth-ledger-sdd/schema.yaml +++ b/openspec/schemas/wealth-ledger-sdd/schema.yaml @@ -1,5 +1,5 @@ name: wealth-ledger-sdd -version: 3 +version: 4 description: WealthLedger SDD workflow - proposal → specs → design → tasks → apply artifacts: - id: proposal @@ -175,6 +175,7 @@ artifacts: architecture, вернись к Specs или Design и инвалидируй Tasks approval. requires: - design + - specs apply: requires: [ tasks ] @@ -187,8 +188,18 @@ apply: - Прочитай каждый path из `contextFiles`, возвращённых native OpenSpec apply instructions, затем applicable repository-local `AGENTS.md` affected areas. Не вычисляй planning paths и не создавай второй context map. - - Выполняй pending tasks по dependencies. Запускай planned Verification и - отмечай checkbox только после observed success. + - Выбирай связный ограниченный batch pending implementation-owned Tasks по + dependencies. Запускай relevant planned Verification и отмечай checkbox + только после observed success. + - Если implementation-owned работа остаётся, сохрани checkpoint с completed + и remaining Tasks, observed checks и одним следующим Implementation outcome. + Remaining work сама по себе не blocker. READY_FOR_VALIDATION допустим + только после всех implementation-owned Tasks и успешных relevant checks. + Независимая Validation и Finalization выполняются в своих ролях по + canonical lifecycle authority; Apply их не запускает. + - При recovery соблюдай artifact approval binding и повторно используй + актуальные результаты checks по canonical context authority; state или + planning completeness сами по себе approval не подтверждают. - Feedback routing: intent/scope → Proposal; observable behavior → Delta Specs; architecture/rollback → Design; decomposition/ownership/coverage → Tasks. Останови downstream work, сообщи evidence и инвалидируй approvals от