Document portable SDD workflow and Storybook catalog

development/engineering-governance.md

@@ -10,7 +10,10 @@
 
 **Delivery Map** — решение по каждой области `frontend`, `backend`, `specs` и `docs`: `affected` с ожидаемым результатом либо `N/A` с конкретной проверяемой причиной.
 
-**Completion Evidence** — созданная после реализации и archive запись о фактической поставке: Delivery Map, archive path, commits изменённых репозиториев, точные verification commands с наблюдёнными результатами и итог independent read-only review.
+**Completion Evidence** — запись существующих delivery commits, фактической
+Delivery Map, точных verification commands с observed results и independent
+review. Finalization создаёт её внутри canonical change до archive; она
+архивируется вместе с change.
 
 **Enforceable Engineering Invariant** — обязательное правило с детерминированной non-mutating локальной проверкой, нарушение которой блокирует завершение change. Непроверяемое предпочтение является guidance, а не hard guardrail.
 
@@ -35,40 +38,74 @@ Proposal → Delta Specs → Design → Tasks → Apply → Verify → Archive
   а `Verification` задаёт планируемую проверку. Tasks не содержат будущие
   результаты, commits или post-archive bookkeeping.
 
-AI-агент готовит только текущий разрешённый артефакт, показывает его Change Owner и останавливается. Downstream artifact создаётся только после явного approval. Если новая сессия не может подтвердить approval из доступного контекста, агент запрашивает его повторно.
+### Роли и approvals
+
+Сессия исполняет одну роль: Discovery, Specification, Implementation, Validation
+или Finalization. Создание record и ожидание решения сами по себе не требуют
+новой сессии той же роли. Переход к другой роли требует независимого контекста.
+
+Specification поддерживает две bounded progression: `Proposal + Delta Specs`
+и `Design + Tasks`. Перед каждым downstream artifact требуется отдельное явное
+решение Change Owner:
+
+| Approval неизменившегося artifact | Следующий разрешённый outcome |
+| --- | --- |
+| Proposal | Delta Specs в той же Specification-сессии |
+| Delta Specs | Завершение первой пары; следующая Specification-сессия начинает Design |
+| Design | Tasks в той же Specification-сессии |
+| Tasks | Implementation в следующей роли |
+
+Сохранённый observed approval повторно используется только при совпадении
+identity и fingerprint. State не является самостоятельным доказательством
+решения владельца. Отсутствующее либо legacy approval binding требует явного
+решения; наличие файла не доказывает approval. Recovery и fingerprint procedure
+определены в [context authority](agent-token-efficiency.md).
 
 До запроса approval агент запускает доступный stage planning gate и сам
 исправляет технические ошибки формата. Полный change validation не объявляется
-успешным, пока downstream artifacts отсутствуют. Форматное исправление без
-изменения intent, behavior, decisions или task scope не требует reapproval;
-семантическое изменение возвращает workflow к самому раннему затронутому
-artifact.
+успешным, пока downstream artifacts отсутствуют. Несовпадение fingerprint
+утверждённого artifact сбрасывает его approval и downstream approvals;
+изменение возвращается к самой ранней затронутой planning boundary. Отметки
+выполнения Tasks не изменяют утверждённое содержание и нормализуются только
+для approval fingerprint.
 
 Изменение принятого upstream artifact инвалидирует approval зависимых артефактов: Proposal — Specs, Design и Tasks; Specs — Design и Tasks; Design — Tasks. Tasks не могут неявно расширять scope или менять поведение и архитектуру: работа возвращается к соответствующему upstream artifact.
 
-## Token-efficient agent execution
+### Implementation, Validation и Finalization
 
-Agent workflow сначала определяет текущую SDD-фазу и affected delivery areas,
-затем загружает canonical artifacts, локальные routing instructions и только
-применимую supporting authority. Полная история предыдущей agent-сессии и
-отдельный handoff artifact не являются prerequisite: после явного approval
-следующая фаза восстанавливается из canonical OpenSpec change и компактного
-handoff state. Если доступный context не подтверждает approval, решение Change
-Owner запрашивается повторно.
+Implementation выполняет связный batch approved Tasks и отмечает только
+фактически завершённую работу после релевантных checks. Если implementation-owned
+работа остаётся, нормальный outcome — `CHECKPOINT` с продолжением Implementation;
+это не blocker. `READY_FOR_VALIDATION` требует завершения всей такой работы и
+успеха её проверок. Проблема intent направляется к Proposal, observable behavior
+— к Delta Specs, архитектуры — к Design, декомпозиции — к Tasks.
 
-Независимые read-only evidence следует получать одним batch до следующего
-смыслового решения. Compact successful output сохраняет command identity, exit
-status и существенный outcome; failure, semantic verification и independent
-review получают достаточные diagnostics и полный relevant scope. Эти правила и
-числовые budgets являются guidance, пока отдельный утверждённый change не
-предоставит детерминированную non-mutating проверку и controlled evidence нового
-hard guardrail.
+Validation независимо проверяет affected gates, semantic и acceptance behavior,
+применимые edge cases и выполняет independent read-only review. Она не меняет
+production implementation, planning artifacts или Tasks. Эти проверки не
+остаются implementation checkboxes. Результат `PASS`, `FAIL` или `SPEC_ISSUE`
+привязан к проверенным planning/delivery inputs по
+[context authority](agent-token-efficiency.md#fingerprints).
 
-Эффективность оценивается на завершённую SDD-фазу вместе с gate outcomes, fix
-cycles, interrupted attempts и review findings. Меньший token usage при большем
-rework или худшем verification result не считается улучшением. Операционный
-routing, handoff envelope и pilot protocol находятся в lazy
-[Token-efficient agent workflow](agent-token-efficiency.md).
+| Результат / blocker | Ответственная следующая роль |
+| --- | --- |
+| Validation PASS на актуальных inputs | Finalization |
+| Implementation finding или unchecked implementation-owned Task | Implementation |
+| Planning issue / SPEC_ISSUE | Specification, самая ранняя затронутая boundary |
+| Отсутствующий либо устаревший PASS | Validation |
+| Retryable archive/evidence/environment failure при корректных inputs | Finalization |
+
+Finalization потребляет актуальный PASS и выполняет только completion mechanics.
+Она не повторяет неизменившуюся Validation и не исправляет implementation или
+planning. При blocker сохраняется observed cause и точный маршрут продолжения.
+
+## Context authority
+
+[Token-efficient agent workflow](agent-token-efficiency.md) единолично определяет
+bounded reads, fingerprint bindings, handoff, evidence reuse и batching.
+Обязательные safeguards этой policy действуют с любым agent runtime; skills,
+commands и session adapters необязательны. Числовые token budgets и telemetry
+не являются условием delivery.
 
 ## Delivery Map и multi-repository delivery
 
@@ -135,13 +172,14 @@ contract либо другое существенно труднообратим
 
 | Вид знания | Authoritative location |
 | --- | --- |
-| Намерение, требования, Design, Tasks, changes и archives | `specs/openspec` |
+| Намерение, требования, Design, Tasks, changes, Completion Evidence и archives | `specs/openspec` |
 | Исполняемое поведение | `frontend` и `backend` code и risk-based tests |
 | Публичный API contract | backend runtime OpenAPI и committed frontend snapshot |
 | Текущее устройство и поставленные возможности | `docs/architecture` и `docs/features` |
 | Устойчивые архитектурные решения и причины | `docs/adr` |
-| Инженерная policy и completion evidence | `docs/development` |
-| Компактная маршрутизация AI-агентов и локальные entrypoints | root/repository-local `AGENTS.md` и workspace `.opencode` |
+| Инженерная policy и context discipline | `docs/development` |
+| Компактная маршрутизация и локальные boundaries | root/repository-local `AGENTS.md` |
+| Необязательные runtime adapters и navigation | локальные skills, commands и session records |
 
 `docs` описывает только фактическое текущее состояние и не пересказывает Proposal, Delta Specs, Design или Tasks другим форматом. `AGENTS.md` не копирует архитектуру или feature documentation: он направляет к authority и перечисляет только применимые hard constraints и canonical commands.
 
@@ -160,12 +198,9 @@ CI пока отсутствует, поэтому обязательные gate
 
 Hard guardrail должен иметь исполняемую локальную проверку. Правило без надёжной проверки помечается как guidance и учитывается в review, но не выдаётся за автоматический запрет. Новые frameworks, checkers и thresholds добавляются только после оценки поддерживаемого решения, maintenance cost и реально защищаемого риска.
 
-Root `.opencode/commands` и `.opencode/skills` являются локальными
-non-authority entrypoints. Они должны соблюдать fixed store, one-artifact
-approvals и hard archive blockers, но не имеют отдельного versioned projection
-source.
-
-OpenSpec schema и changes валидируются native CLI с явным canonical store.
+Native команды и completion procedure описаны в
+[OpenSpec lifecycle](openspec-authority-and-lifecycle.md). Они не требуют
+optional runtime adapters.
 
 ## Verify, archive и Completion Evidence
 
@@ -173,8 +208,23 @@ Structural validation OpenSpec проверяет schema и форму арте
 
 1. успешные canonical gates всех affected areas;
 2. native strict validation completed change и main specs из canonical store;
-3. semantic verification реализации против Proposal, Delta Specs, Design и Tasks;
+3. semantic и acceptance verification против approved Proposal, Delta Specs,
+   Design и Tasks;
 4. independent read-only review без Critical и Important findings;
-5. завершённый checklist без unchecked tasks.
+5. завершённые implementation-owned Tasks и необходимая as-built документация;
+6. актуальный input-bound PASS независимой Validation и существующие delivery
+   commits для каждой affected repository area.
 
-Archive не имеет confirmation override для этих blockers. После успешного archive применяется двухфазная фиксация: сначала commits поставленных изменений и archive/sync, затем Completion Evidence с уже существующими delivery commit IDs, после чего отдельный final docs commit сохраняет evidence. Evidence ссылается на предшествующий as-built docs commit, если docs affected; при `N/A` сохраняет причину и не выдумывает implementation commit. Собственный final evidence commit не может ссылаться сам на себя и сообщается итогом archive workflow. Только фактические commits, выполненные команды и наблюдённые результаты могут быть evidence; planned значения и предположения не считаются завершением.
+Archive не имеет confirmation override для этих blockers. Completion Evidence
+создаётся в `specs/openspec/changes/<change>/completion-evidence.md` после
+существования всех перечисленных фактов и архивируется вместе с change.
+Evidence содержит Delivery Map, существующие commit identifiers, exact
+commands/observed results и независимый verdict с привязкой к inputs. Для
+`N/A` сохраняется конкретная причина без фиктивного commit или gate.
+
+Собственный evidence/archive commit не ссылается сам на себя: его идентификатор
+сообщается после фиксации. Отсутствующие факты не заменяются placeholders,
+unchecked Tasks или отдельным docs evidence store. При `docs: N/A` запись
+Completion Evidence не требует docs-мутации. Registry хранит ссылку на
+canonical archive и evidence; прежние датированные evidence и ссылки остаются
+историческими и не переносятся задним числом.