18 KiB
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
- Синхронизировать durable policy, lifecycle description и lazy operational playbook с утверждёнными Specs; сохранить immutable baseline и measurement protocol без raw session data.
- Перевести root routing с blanket reads на stage/area-first conditional pointers, сохранив existing authority, SDD approvals и canonical gates.
- Активировать guidance для последующих agent phases и начать фиксированное окно из 10 наблюдений минимум по двум changes.
- Сопоставить resource и quality outcomes, документировать ограничения и не продвигать numeric threshold автоматически.
- После завершения 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 |