docs(specs): start token-efficient agent pilot

openspec/changes/optimize-agent-token-workflow/design.md

@@ -0,0 +1,212 @@
+## Context
+
+WealthLedger уже разделяет нормативные change artifacts, durable engineering
+policy и компактные agent entrypoints, но root routing сейчас безусловно требует
+несколько широких документов до определения стадии и affected areas. В длинных
+сессиях широкие reads, verbose command results и последовательные независимые
+tool calls накапливаются в conversation history и повторно передаются каждому
+следующему model call. При этом OpenSpec уже предоставляет естественные
+checkpoint: каждый planning artifact создаётся отдельно, проходит structural
+gate и требует явного approval.
+
+Изменение должно использовать эти существующие boundaries, не создавать второй
+context map, не переносить normative policy в session summary и не превращать
+нестабильные показатели локальных rollout logs в completion gate. Workspace root
+не является Git-репозиторием, поэтому compact root routing обновляется локально,
+а versioned authority и as-built описание принадлежат `specs` и `docs`.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- сделать approved artifact естественной границей новой agent-сессии;
+- заменить blanket documentation reads на stage- и area-aware routing с явными
+  условиями обязательного on-demand чтения;
+- уменьшить избегаемые model/tool round-trips и объём переносимых успешных logs,
+  не теряя evidence для диагностики, verification и review;
+- провести ограниченный pilot на 10 post-change SDD-фазах и оценить resource
+  usage вместе с качеством результата;
+- сохранить рекомендации guidance до отдельного evidence-backed решения о hard
+  guardrail.
+
+**Non-Goals:**
+
+- менять artifact graph, approvals, canonical gates, semantic verification или
+  independent review;
+- внедрять telemetry proxy, новый session-log parser, внешнюю интеграцию либо
+  обязательную зависимость;
+- автоматически создавать, закрывать или переносить Codex tasks;
+- оптимизировать системный prompt, model selection, pricing или provider quota;
+- гарантировать одинаковый расход для несопоставимых по сложности фаз;
+- продвигать numeric token budget в completion blocker в рамках этого change.
+
+## Decisions
+
+### Durable policy, lazy playbook и compact routing имеют разных владельцев
+
+Canonical Specs сохраняют только наблюдаемые инварианты: stage-scoped context,
+approval-preserving handoff, сохранность evidence и совместную оценку ресурса с
+качеством. Engineering governance фиксирует устойчивое различие guidance и hard
+guardrail. Отдельный development playbook описывает операционные приёмы и pilot
+protocol; он загружается только для agent workflow work или при диагностике
+расхода. Root `AGENTS.md` остаётся коротким router: сначала stage и affected
+areas, затем conditional pointers к governance, architecture, glossary и audit
+material. Repository-local entrypoints сохраняют canonical gates и boundaries.
+
+Такое разделение предотвращает повторение подробного playbook в каждом agent
+prefix. Альтернатива — поместить все правила batching и budgets прямо в root
+`AGENTS.md` — отклонена, потому что увеличивает обязательный context каждой
+сессии и смешивает routing с объясняющей policy. Полностью удалить pointers тоже
+нельзя: agent должен иметь однозначный путь к authority при появлении
+релевантного вопроса.
+
+### Canonical artifact является handoff interface, но не доказательством approval
+
+После явного approval Proposal, Delta Specs, Design или Tasks следующая фаза
+может начинаться в новой Codex task. Минимальный handoff state содержит change
+identity, последний явно approved artifact, текущую фазу, affected areas,
+unresolved blockers и следующий разрешённый outcome. Planning content не
+копируется: новая task получает его из canonical OpenSpec store. Для перехода
+Apply → independent verification дополнительно передаётся фактический scope
+изменений и доступное evidence.
+
+Handoff остаётся сообщением пользователя или conversation state, а не новым
+versioned файлом. Наличие artifact без доступного явного approval не позволяет
+переходить дальше: агент повторно запрашивает решение Change Owner. Это сохраняет
+существующий approval contract и устраняет соблазн использовать summary как
+параллельный authority.
+
+Альтернатива — продолжать весь lifecycle в одной task и полагаться только на
+automatic compaction — отклонена: compaction наступает после накопления затрат и
+не совпадает с semantic boundaries SDD. Обязательная новая task после любого
+короткого действия также отклонена: стартовый context может быть дороже
+продолжения; boundary применяется после завершённого artifact или другого
+наблюдаемого milestone.
+
+### Evidence batching происходит только до следующего смыслового решения
+
+Agent сначала формирует bounded evidence set. Независимые read-only lookups,
+status checks и scoped source reads получают одним batch, если ни один результат
+не определяет следующий вызов. Discovery начинается с поиска identity или
+символа, затем читает найденные ranges. Diff discovery начинается с scope и
+paths, затем раскрывает relevant content. Успешный command result сохраняет
+command identity, exit status и существенную summary; verbose output не
+переносится полностью, если он не нужен следующему решению.
+
+Dependent calls, side effects, approval boundaries и semantic judgment остаются
+последовательными. Failure или неоднозначная summary расширяет diagnostics;
+canonical verification и reviewer получают весь relevant evidence. Soft output
+budgets помогают выбрать форму результата, но никогда не обрезают единственный
+диагностический сигнал.
+
+Альтернатива — blanket limit на строки или tool tokens — отклонена: статический
+cap может скрыть причину failure или material diff. Альтернатива всегда сохранять
+полный output — отклонена из-за доказанного накопления нерелевантного context.
+
+### Pilot измеряет фазу, resource usage и delivery quality совместно
+
+Immutable snapshot текущего session audit сохраняет baseline и его ограничения.
+После активации guidance pilot собирает 10 завершённых SDD-фаз как минимум из
+двух changes. Для каждого наблюдения фиксируются phase type, workload scope,
+cumulative input, model calls, context-depth indicators, tool-output volume,
+canonical-gate outcome, fix cycles и review findings. Незавершённые или
+прерванные попытки не включаются в denominator completed-phase efficiency, но
+учитываются отдельно как outcome, чтобы экономия не достигалась отбрасыванием
+неудач.
+
+Сравнение выполняется внутри одинаковых phase types и близкого scope, когда это
+возможно; общий aggregate сопровождается caveat о неоднородности задач. Успехом
+считается направленное уменьшение resource usage без ухудшения gate success,
+rework и findings. Результат pilot может подтвердить guidance, потребовать её
+пересмотра или дать основание для отдельного Proposal о детерминированном
+guardrail. Текущий change не повышает threshold автоматически.
+
+Change остаётся active до накопления и оценки 10 post-change фаз. Это увеличивает
+его календарную длительность, но позволяет завершить change с наблюдаемым
+результатом вместо предположения. Другие changes могут выполняться во время
+окна наблюдения и становятся источником pilot data.
+
+### Measurement не вводит новый runtime или parser
+
+Pilot использует provider-counted usage и существующую процедуру анализа rollout
+sessions. Raw rollout data не коммитится; versioned docs получают только
+агрегированные показатели, scope, метод и caveats. Любая стоимость или quota
+интерпретация отделяется от token counts и не объявляется причинно доказанной без
+provider contract.
+
+## Delivery Map
+
+| Area | Status | Architectural outcome or N/A reason |
+| --- | --- | --- |
+| frontend | `N/A` | Application behavior, frontend agent routing и canonical frontend gate не меняются. |
+| backend | `N/A` | Backend behavior, data, API contract, backend agent routing и canonical backend gate не меняются. |
+| specs | `affected` | Canonical lifecycle и engineering-governance requirements получают token-efficient context, handoff, evidence и pilot invariants; change проходит существующий planning lifecycle и sync. |
+| docs | `affected` | Durable engineering policy, lifecycle documentation, lazy operational playbook, development index, immutable baseline snapshot и pilot result описывают фактически активированный workflow без копирования planning artifacts. |
+
+Workspace root routing обновляется локально как orchestration outcome и не
+получает фиктивный repository commit.
+
+### Contract Gate Decision
+
+| Gate | Status | Reason |
+| --- | --- | --- |
+| runtime-openapi | `N/A` | Ни frontend, ни backend, ни публичный API contract не изменяются. |
+
+## Solution Assessment
+
+| Option | Fit and maturity | Security / operating cost | Constraints / migration cost | Decision |
+| --- | --- | --- | --- | --- |
+| Existing provider rollout usage plus project audit protocol | Уже доступные фактические session counters; достаточно для ограниченного pilot | Нет нового data path или runtime dependency; ручная классификация требует дисциплины | Формат usage может меняться, поэтому метод и caveats фиксируются вместе с результатом | Выбрано для pilot |
+| Project-owned rollout parser and token gate | Может автоматизировать повторный отчёт | Создаёт shared observability tooling и maintenance burden вокруг private/unstable local format | Потребует fixtures, compatibility policy и ложится в обязательный local workflow до доказанной ценности | Отклонено до повторяемой потребности |
+| External telemetry proxy or agent-cost platform | Зрелые варианты дают dashboards и cross-provider attribution | Меняет execution/data boundary, требует подключения, конфигурации и постоянной эксплуатации | Избыточно для локального pet-project pilot и не решает orchestration само по себе | Отклонено |
+| Только субъективная оценка скорости работы | Нулевая стоимость внедрения | Не создаёт privacy или runtime риска | Не позволяет отличить реальное улучшение от ощущения и не выполняет утверждённые Specs | Отклонено |
+
+Выбранный вариант переиспользует существующие данные и не создаёт custom
+observability subsystem. Trigger повторной оценки tooling: не менее двух
+последовательных pilot cycles требуют одинаковой ручной обработки либо native
+usage перестаёт давать необходимые counters.
+
+## Risks / Trade-offs
+
+- **Lazy context может скрыть обязательную authority.** Root routing сохраняет
+  явные triggers для domain, architecture, audit и gate questions; при появлении
+  такого вопроса relevant authority загружается до решения.
+- **Batch может объединить зависимые действия.** Guidance ограничивает batching
+  заранее независимыми read-only calls; side effects и adaptive discovery
+  остаются последовательными.
+- **Compact output может скрыть failure.** Любой non-zero или неоднозначный
+  result расширяет diagnostics, а review сохраняет full relevant scope.
+- **Новая task может потерять approval.** Handoff требует явного owner decision;
+  при отсутствии подтверждения workflow повторно запрашивает approval.
+- **Фазы различаются по сложности.** Pilot сохраняет phase type и scope,
+  сравнивает близкие наблюдения и публикует ограничения aggregate.
+- **Долгий pilot задерживает archive.** Guidance начинает действовать до archive,
+  а фиксированное окно 10 фаз ограничивает длительность и предотвращает
+  бессрочное наблюдение.
+- **Метрики могут стимулировать сокращение качества.** Gate outcomes, fix cycles,
+  interrupted attempts и review findings имеют равный статус с token usage.
+
+## Migration Plan
+
+1. Синхронизировать durable policy, lifecycle description и lazy operational
+   playbook с утверждёнными Specs; сохранить immutable baseline и measurement
+   protocol без raw session data.
+2. Перевести root routing с blanket reads на stage/area-first conditional
+   pointers, сохранив existing authority, SDD approvals и canonical gates.
+3. Активировать guidance для последующих agent phases и начать фиксированное
+   окно из 10 наблюдений минимум по двум changes.
+4. Сопоставить resource и quality outcomes, документировать ограничения и не
+   продвигать numeric threshold автоматически.
+5. После завершения pilot выполнить affected-area gates, semantic verification,
+   independent review и обычный sync/archive lifecycle.
+
+### Rollback Contract
+
+| Field | Decision |
+| --- | --- |
+| Status | `N/A` |
+| Reason | Изменение затрагивает обратимые instructions и документацию, не меняет auth/security behavior, данные, migration или public contract; откат выполняется обычным revert affected commits и восстановлением предыдущего локального root routing. |
+| Trigger | N/A |
+| Actions | N/A |
+| Data safety | N/A — пользовательские и runtime данные не создаются и не изменяются. |
+| Verification | N/A |