Document portable SDD workflow and Storybook catalog

development/agent-token-efficiency.md

@@ -1,81 +1,155 @@
 # Token-efficient agent workflow
 
-## Статус и границы
+## Authority и границы
 
-Эта инструкция описывает действующий guidance для сокращения повторной передачи
-agent context. Она не меняет SDD lifecycle, approvals, canonical gates, semantic
-verification или independent review и не является hard guardrail.
+Этот документ — vendor-neutral authority для context discipline: recovery,
+fingerprint bindings, bounded reads и observed evidence. Lifecycle ownership
+принадлежит [Engineering governance](engineering-governance.md), native команды
+— [OpenSpec lifecycle](openspec-authority-and-lifecycle.md). Эти процедуры
+выполняются без обязательных skills, session adapter, telemetry или service.
 
-Исходный baseline сохранён в
-[аудите Codex-сессий 26.08.2026](../audits/codex-sessions-token-audit-2026-08-26.md).
-Raw rollout logs не коммитятся. Числовой budget не блокирует delivery без
-отдельного утверждённого change, детерминированной non-mutating проверки и
-controlled positive/negative evidence.
-
-Guidance ниже остаётся non-blocking: он не заменяет required authority или
-verification и не повышается до hard guardrail без отдельного evidence-backed
-change.
+Исходный наблюдаемый baseline сохранён в
+[аудите сессий 26.08.2026](../audits/codex-sessions-token-audit-2026-08-26.md).
+Raw logs и числовые token budgets не становятся delivery gates. Экономия
+контекста не оправдывает пропуск relevant authority или ослабление verification.
 
 ## Routing context
 
-До чтения supporting documentation агент определяет:
+До supporting reads определите текущую роль, разрешённый outcome и affected
+repositories. Прочитайте их local `AGENTS.md` для boundaries и canonical gates,
+затем только применимую authority:
 
-1. тип работы и текущую SDD-фазу, если change versioned;
-2. affected repositories и их canonical gates;
-3. capability или source identity, нужные для следующего решения.
-
-После этого загружается только применимый context:
-
-| Trigger | Обязательный context |
+| Trigger | Context |
 | --- | --- |
-| Versioned SDD planning или Apply | Native OpenSpec instruction, возвращённые `contextFiles` и локальные `AGENTS.md` affected areas |
-| Engineering policy, approval, testing, delivery или archive | Релевантный раздел `engineering-governance.md` |
-| Cross-service flow или архитектурная граница | `architecture/system-overview.md` и применимые ADR/feature docs |
-| Domain или API semantics | Релевантный термин `architecture/domain-glossary.md` и canonical contract/spec |
-| Работа по известному Audit ID | Найденная через поиск запись и связанное evidence в `audit-remediation.md` |
-| Диагностика agent token usage или этот pilot | Этот playbook и применимый dated audit snapshot |
+| Planning или Implementation | Native instruction и каждый возвращённый context file |
+| Approval, роль, testing, Delivery Map или completion | Релевантный раздел governance |
+| Cross-area architecture | `architecture/system-overview.md`, нужные ADR/feature docs |
+| Domain или API semantics | Термин в `architecture/domain-glossary.md`, canonical contract/spec |
+| Известный Audit ID | Найденная запись `audit-remediation.md` и её source/evidence |
+| Validation | Approved artifacts, delivery inventory, relevant checks и findings |
+| Finalization | Текущий независимый verdict с binding и существующие delivery facts |
 
-Supporting material загружается on demand, если возникший вопрос меняет
-семантику, архитектуру, audit disposition или обязательный gate. Guidance нельзя
-использовать как основание пропустить необходимую authority.
+В новой роли canonical artifacts читаются заново только в необходимом scope.
+В том же context повторно читаются изменившиеся relevant inputs. История чата
+не заменяет artifact и не является обязательным prerequisite.
 
-## Handoff между agent-сессиями
+## Recovery и handoff
 
-Approved planning artifact, завершённый implementation slice или verification
-outcome являются естественной границей новой Codex task. Минимальный handoff:
+При наличии session adapter mutable state является единственным navigation
+pointer. Прочитайте только его текущий self-contained immutable record, затем
+phase-specific authority. Без adapter тот же актуальный envelope передаётся
+в доступном рабочем контексте; отдельный versioned verdict или planning store
+ради handoff не создаётся.
 
-```text
-Change: <identity>
-Approved through: <explicitly approved artifact>
-Current phase: <phase>
-Affected areas: <areas>
-Unresolved blockers: <none or list>
-Next allowed outcome: <one outcome>
-```
+Envelope содержит только change identity, текущую роль/outcome, affected areas,
+observed approval bindings, completed/remaining task IDs, краткие observed checks,
+blockers и один следующий допустимый outcome. Для продолжения после Validation
+он также сохраняет её verdict, relevant inventory и fingerprint; Finalization
+retry не должен требовать восстановления цепочки старых records. Requirements,
+Design, Tasks и acceptance scenarios остаются в canonical OpenSpec.
 
-Planning content не копируется: новая task читает его из canonical OpenSpec
-store. Если явный approval недоступен в новой task, агент повторно запрашивает
-его и не выводит решение владельца только из наличия artifact.
+Первичное `approved` записывается только после явного решения Change Owner,
+со ссылкой на наблюдённый источник решения, artifact identity и fingerprint.
+При recovery совпадение позволяет продолжить без повторного approval. Отсутствие
+binding, включая legacy state, требует явного решения; mismatch сбрасывает
+approval изменённого artifact и всех downstream artifacts. Approval status
+сохраняет наблюдение, но не доказывает личность или решение владельца сам по себе.
 
-Для handoff Apply → Verify дополнительно передаются фактический scope изменённых
-areas и unresolved failures. Полная история tool calls не передаётся.
+Порядок сохранения: `canonical outcome → immutable record → state pointer`.
+Сначала создаётся новый record; существующие records не перезаписываются. Перед
+заменой pointer проверяется, что исходный state не изменён другим участником.
+Конфликт или неполная запись остаются видимыми и не разрешаются last-write-wins.
+Старые records читаются только для расследования конкретного текущего расхождения.
+
+## Fingerprints
+
+Fingerprint имеет вид `sha256:<64 lowercase hex digits>` и связывает observation
+с содержимым, а не только с именем файла, временем изменения или Git HEAD.
+Одинаковая процедура применяется к approval artifact, gate inputs и PASS;
+отличаются только scope и явно указанная ниже нормализация task progress.
+
+### Scope и inventory
+
+До проверки сохраните reviewed inventory: workspace-relative точные пути и
+релевантные directory roots, их явные exclusions, назначение набора и список
+входящих files. Directory roots должны включать новые files, способные изменить
+проверяемый результат; произвольный список только уже известных изменённых files
+недостаточен. Scope покрывает все actual inputs gate/review, включая dependency
+и config files. Unrelated concurrent change исключается по объяснённой границе,
+а не потому, что мешает получить прежний fingerprint.
+
+- Proposal, Design и Tasks — соответствующий canonical файл. Delta Specs —
+  полный разрешённый native CLI набор `specs/**/spec.md` этого change; при
+  сравнении membership запрашивается заново, чтобы обнаружить additions/removals.
+- PASS включает raw approved planning artifacts, relevant main baseline,
+  проверенные delivery files affected areas и local unversioned instructions,
+  если они входят в change. Runtime/gate command и environment prerequisites
+  сохраняются рядом с fingerprint как observed metadata.
+- Для каждого Git repository candidate paths получают через
+  `git ls-files --cached --others --exclude-standard -z`, затем пересекают
+  с reviewed roots/paths и de-duplicate. Это включает tracked и nonignored
+  untracked, staged и unstaged working content. Workspace-owned paths вне Git
+  перечисляются явно; relevant ignored inputs также включаются явно.
+- При сравнении заново раскрываются те же roots и добавляются paths из прежнего
+  inventory: исчезнувший файл остаётся entry `missing`, новый входит в набор.
+  Directory names не хешируются отдельно. Пути используют `/`, относительно
+  workspace, без `.`/`..`, абсолютного host prefix и повторов.
+- Собственные navigation state, phase records и
+  `changes/<change>/completion-evidence.md` исключаются из self-hash. Exclusions
+  относятся к конкретному change, не ко всем `.agents`, `.opencode` или specs.
+  Ожидаемые archive/sync/evidence/registry mutations проверяются отдельно как
+  completion outputs; ими нельзя скрыть новое implementation изменение.
+
+### Детерминированное представление
+
+1. Для каждого entry прочитайте текущие bytes из working tree. `file` получает
+   mode `100755`, если установлен хотя бы один executable bit, иначе `100644`.
+   `symlink` получает mode `120000`, payload — bytes самого link target без
+   разыменования. Для отсутствующего прежнего path используйте kind `missing`,
+   mode `-`, digest `-`. Unresolved Git conflicts, unreadable inputs и special
+   files блокируют binding; приблизительный fingerprint не создаётся.
+2. Только для **approval Tasks** замените ASCII prefix `b"- [x] "` на `b"- [ ] "`
+   у строк canonical task checkbox (`X.Y [area]` после prefix). Другие bytes,
+   whitespace, строки, `Covers` и `Verification` не меняются. Во всех остальных
+   наборах, включая gate/PASS и их Tasks, используется raw payload. Таким образом
+   observed progress не отменяет approval содержания, но остаётся виден review.
+3. Рассчитайте lowercase SHA-256 hex digest payload каждого существующего entry.
+   Отсортируйте entries по UTF-8 bytes workspace-relative path. Непредставимые
+   в UTF-8 paths требуют явного разрешения input issue, а не замены символов.
+4. Соберите byte stream: ASCII prefix `wealth-ledger-input-v1` и один NUL byte,
+   затем для каждого entry UTF-8 fields `path`, `kind`, `mode`, `digest`, каждый
+   с завершающим NUL. Пробелы, JSON, newline separators и BOM не добавляются.
+   SHA-256 этого stream с prefix `sha256:` — fingerprint всего набора.
+
+Inventory и fingerprint не содержат копии исходных artifacts. Если review
+зависит от содержимого symlink target, target включается отдельным input;
+хеширование только ссылки не подтверждает внешнее содержимое. Перенос файлов,
+изменение mode, content или membership меняют binding. Commit/staging без
+изменения этих данных его не меняют. Relevant input mutation инвалидирует PASS;
+изменение planning approval fingerprint дополнительно применяет cascade policy.
+
+## Повторное использование evidence
+
+Сохранённый успешный gate повторно используется при совпадении его input scope,
+fingerprint и relevant environment prerequisites. Evidence сохраняет exact
+command, cwd, exit status и достаточный observed result. Неизвестный scope или
+отсутствующий binding не доказывают неизменность. Нельзя заменить full gate
+результатом проверки части файлов.
+
+Validation независимо оценивает свежесть gates и semantic/acceptance behavior;
+успех Implementation tests сам по себе не даёт независимый PASS. Finalization
+сверяет последний PASS до terminal mutations и потребляет его без повторения
+неизменившихся checks. Expected archive move, approved semantic sync и создание
+Completion Evidence проверяются как новые completion outputs; их effect не
+переписывает сохранённое описание проверенного delivery input.
 
 ## Evidence batching
 
-Один evidence batch заканчивается перед следующим смысловым решением:
-
-- заранее независимые read-only lookups выполняются вместе;
-- adaptive discovery, side effects и approval boundaries остаются
-  последовательными;
-- discovery начинается с `rg` или другого identity search, затем читает
-  релевантный диапазон;
-- diff сначала сужается через status/stat/name-only, затем раскрывает affected
-  paths;
-- successful command result сохраняет exact command identity, exit status и
-  существенную summary;
-- failure или неоднозначная summary расширяет diagnostics до достаточной причины;
-- semantic verification и reviewer всегда получают полный relevant evidence.
-
-Статический лимит строк или tool tokens не применяется: он может скрыть
-единственный диагностический сигнал. Compact output — способ убрать заведомо
-нерелевантный шум, а не обрезать доказательства.
+Один batch заканчивается перед следующим смысловым решением. Независимые
+read-only inputs получают вместе; adaptive discovery, side effects и approvals
+остаются последовательными. Начните с `rg`/identity search или Git status/stat,
+затем раскройте relevant paths. Successful output сохраняет команду, exit status
+и существенный outcome; failure, semantic verification и review получают весь
+relevant evidence. Произвольный лимит строк не должен скрывать диагностический
+сигнал. Контекст оценивается вместе с качеством checks, findings и rework,
+а не по сокращению tokens отдельно.