From 42fd8940dcd2fcfba5ed7f34d6265f289b049659 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Wed, 26 Aug 2026 16:44:02 +0300 Subject: [PATCH] docs: activate token-efficient agent workflow --- audits/README.md | 1 + .../codex-sessions-token-audit-2026-08-26.md | 756 ++++++++++++++++++ development/README.md | 1 + development/agent-token-efficiency.md | 101 +++ development/engineering-governance.md | 24 + .../openspec-authority-and-lifecycle.md | 20 + package.json | 2 +- 7 files changed, 904 insertions(+), 1 deletion(-) create mode 100644 audits/codex-sessions-token-audit-2026-08-26.md create mode 100644 development/agent-token-efficiency.md diff --git a/audits/README.md b/audits/README.md index cc64493..81f513b 100644 --- a/audits/README.md +++ b/audits/README.md @@ -9,3 +9,4 @@ - [Аудит 24.08.2026](audit-24-08-2026.md) - [Multi-source assessment WealthLedger SDD 26.08.2026](2026-08-26-wealth-ledger-sdd/README.md) - [Повторный multi-source review WealthLedger SDD v2 26.08.2026](2026-08-26-wealth-ledger-sdd-v2-review/README.md) +- [Аудит расхода токенов Codex-сессий 26.08.2026](codex-sessions-token-audit-2026-08-26.md) diff --git a/audits/codex-sessions-token-audit-2026-08-26.md b/audits/codex-sessions-token-audit-2026-08-26.md new file mode 100644 index 0000000..b8f4981 --- /dev/null +++ b/audits/codex-sessions-token-audit-2026-08-26.md @@ -0,0 +1,756 @@ +# Codex Sessions Token Audit + +Дата анализа: 2026-08-26 + +## Контекст + +Анализ выполнен по rollout-сессиям Codex за день для pet-проекта, где используется: + +- SDD (Spec-Driven Development); +- OpenSpec; +- `AGENTS.md`; +- skills; +- subagents; +- многошаговый workflow от discovery/design до implementation/review. + +Цель аудита — понять, почему Codex расходует лимиты слишком быстро, определить основные источники token usage и сформировать практические направления оптимизации процесса разработки. + +--- + +# Executive Summary + +Разобраны все 9 rollout-файлов. Fork/subagent-сессии были учтены отдельно, чтобы не посчитать унаследованную историю дважды. + +Главный вывод: + +> **Проблема действительно есть, и она почти не связана с генерацией кода как таковой. Основной расход создаёт большое количество последовательных model ↔ tool циклов на уже разросшемся контексте.** + +## Общая статистика + +| Работа | Model calls | Input | Cached input | Uncached input | Output | +|---|---:|---:|---:|---:|---:| +| Аудит SDD/OpenSpec + subagents | **254** | **26.51M** | 25.70M | 812K | 112K | +| Выбор UI skill | 2 | 53K | 4K | 49K | 1K | +| Редизайн карточки акции + Curie | **120** | **13.37M** | 12.90M | 469K | 41K | +| Редизайн операций + Faraday | **182** | **20.95M** | 20.42M | 534K | 80K | +| **Итого** | **558** | **60.88M** | **59.02M** | **1.86M** | **234K** | + +Ключевые цифры: + +- **96.9% всего input — cached input**; +- всего около **3.1% input был новым**; +- output модели — около **0.38% относительно input**; +- reasoning — около **66K токенов**, то есть не является основным источником расхода; +- средний model call получал примерно **109 000 input-токенов**; +- из них в среднем: + - около **105 770 cached**; + - около **3 341 новых**. + +Иными словами, очередной `rg`, `sed`, `git diff` или другой tool call приводит к новому model call с огромным уже накопленным контекстом. + +--- + +# 1. Главная проблема — слишком много model round-trips + +В SDD-сессии: + +```text +254 model calls +26.51M input tokens +≈104K input / call +``` + +Карточка акции: + +```text +120 model calls +13.37M input +≈111K / call +``` + +Операции: + +```text +182 model calls +20.95M input +≈115K / call +``` + +Получается почти линейная зависимость: + +```text +большой context + × +много model calls + = +огромный cumulative input +``` + +Типичный дорогой паттерн: + +```text +model + ↓ +sed ... + ↓ +model ← опять ~130K input + ↓ +rg ... + ↓ +model ← опять ~140K + ↓ +git diff + ↓ +model ← опять ~150K + ↓ +sed ... + ↓ +model ← опять ~160K +``` + +Более экономный вариант: + +```text +model + ↓ +├─ rg ... +├─ git diff --stat +├─ sed relevant-range... +└─ ... + ↓ +model +``` + +То есть **batch/parallel tool calls — один из самых сильных рычагов оптимизации**. + +Хороший контрольный пример есть прямо в логах: сессия «какой skill выбрать» выполнила **8 tool calls всего за 2 model calls**. Это значительно более экономный паттерн. + +--- + +# 2. Контекст реально разрастается до 200K+ + +Максимальный input одного model call: + +| Сессия | Median | Max | Context window | +|---|---:|---:|---:| +| SDD/OpenSpec | ~128K | **216.5K** | 258.4K | +| Карточка акции | ~133K | **213.5K** | 258.4K | +| Операции | ~119K | **231.0K** | 258.4K | + +Одна из сессий дошла примерно до: + +```text +231K / 258K ≈ 89% context window +``` + +Codex уже был вынужден делать context compaction. + +Особенно показательно распределение cumulative input: + +- в основной SDD-сессии **83.6%** input пришлось на вызовы, где контекст уже был больше 100K; +- в карточке акции — **83.5%**; +- в операциях — **77.3%**. + +Если чисто математически ограничить model calls уровнем около 100K input, потенциально можно было бы убрать порядка: + +```text +~16.4M input tokens +``` + +Это не означает, что нужно вводить жёсткий hard-cap 100K, но цифра показывает масштаб проблемы. + +--- + +# 3. Длинная сессия «одна feature от начала до конца» слишком дорогая + +Текущий flow приблизительно выглядит так: + +```text +research + ↓ +design + ↓ +OpenSpec proposal + ↓ +delta specs + ↓ +design + ↓ +tasks + ↓ +implementation + ↓ +tests + ↓ +fix + ↓ +review + ↓ +docs + ↓ +archive +``` + +Если всё это живёт в одной conversation, implementation в конце тащит за собой: + +```text +весь research ++ старые tool outputs ++ обсуждение дизайна ++ предыдущие ответы ++ OpenSpec ++ прочитанный source code ++ git diff ++ test output ++ skills ++ instructions ++ ... +``` + +Хотя для конкретной операции, например: + +```text +исправить BrokerageOperationRow +``` + +большая часть этого контекста уже не нужна. + +## Рекомендуемый workflow + +Не отказываться от SDD. Наоборот, использовать OpenSpec как естественную границу контекста: + +```text +Session 1 — Discovery / Design + ↓ +proposal + specs + design + +Session 2 — Planning + ↓ +approved artifacts + ↓ +tasks.md + +Session 3 — Implementation + ↓ +читает только approved OpenSpec ++ affected source files + +Session 4 — Verification / Review + ↓ +git diff ++ approved specs/design/tasks + +Session 5 — Archive +``` + +Каждая следующая сессия получает **результат предыдущей в структурированной форме**, а не всю историю того, как к нему пришли. + +Это хорошо сочетается с SDD: артефакт становится интерфейсом между агентными сессиями. + +--- + +# 4. Слишком много полного чтения файлов + +В командах за день часто встречались: + +```text +SKILL.md 35 раз +tasks.md 35 +AGENTS.md 32 +spec.md 30 +git diff 24 +design.md 23 +proposal.md 21 +schema.yaml 20 +engineering-governance.md 15 +audit-remediation.md 16 +domain-glossary.md 11 +system-overview.md 10 +``` + +Это не означает, что каждый файл каждый раз читался полностью, но хорошо показывает характер поведения агента. + +Особенно заметна root-инструкция: + +> перед работой прочитать engineering-governance, system-overview и domain-glossary + +В результате каждый новый агент снова читает эти документы. + +Например, одни и те же governance-файлы читали: + +```text +root +Kierkegaard +Nash +Curie +Faraday +... +``` + +Это цена текущего governance-подхода. + +Сам `AGENTS.md` при этом небольшой — примерно 2230 символов. Его размер не является проблемой. + +## Что лучше изменить + +Вместо обязательного чтения нескольких больших документов перед любой работой: + +```text +AGENTS.md + +Before work: +1. Determine affected repositories. +2. Read their AGENTS.md. +3. Consult docs/development/engineering-governance.md + only for the relevant gate/policy. +4. Read system-overview only for cross-service/ + architectural changes. +5. Read domain-glossary only when domain semantics + are involved. +``` + +То есть сделать документацию **lazy context**, а не mandatory context. + +--- + +# 5. Некоторые tool outputs слишком большие + +В SDD-сессии встречались результаты команд размером: + +```text +40 137 chars +36 937 chars +34 621 chars +32 936 chars +32 874 chars +... +``` + +В одном случае: + +```text +Warning: truncated output +original token count: 15,592 +Total output lines: 1006 +``` + +То есть агент запросил больше тысячи строк. + +Другой пример: + +```bash +bash -x scripts/verify-openspec-planning.test.sh +``` + +дал: + +```text +566 lines +original token count: 14,118 +``` + +`bash -x` для обычной успешной verification — дорогой паттерн. + +## Более эффективный подход + +Вместо: + +```bash +sed -n '1,320p' file1 +sed -n '1,380p' file2 +sed -n '1,300p' file3 +``` + +лучше: + +```text +rg / symbol search + ↓ +identify relevant section + ↓ +sed -n '120,180p' +``` + +То есть `rg` должен быть основным инструментом discovery, а `sed` — точечным чтением найденного диапазона. + +--- + +# 6. `git diff` — ещё один заметный источник расхода + +`git diff` встречается минимум **24 раза**. + +Некоторые outputs достигают: + +```text +16K tokens +14K tokens +11K tokens +... +``` + +Иногда diff перечитывается почти целиком несколько раз. + +## Рекомендуемый стандарт + +```text +git status --short + ↓ +git diff --stat + ↓ +git diff --name-only + ↓ +только затем: +git diff -- path/to/relevant/file +``` + +Полный relevant diff имеет смысл один раз читать независимому reviewer. + +Нежелательно выполнять: + +```bash +git diff +``` + +на multi-repo workspace после большой реализации без предварительного narrowing. + +--- + +# 7. Subagents стоят токенов, но не являются главной проблемой + +После удаления унаследованных cumulative counters: + +## SDD audit + +Основной agent: + +```text +20.45M input +``` + +Kierkegaard: + +```text ++1.07M +``` + +Peirce: + +```text ++4.26M +``` + +Nash: + +```text ++0.73M +``` + +Итого: + +```text +26.51M +``` + +Subagents добавили примерно: + +```text +~6.06M input +≈23% workload +``` + +Это существенно, но запрещать subagents не стоит. + +У них есть важное преимущество: собственный context обычно меньше: + +```text +Kierkegaard max ~102K +Peirce max ~112K +Nash max ~79K +Curie max ~62K +Faraday max ~79K +``` + +Иногда выгоднее: + +```text +200K root + ↓ +spawn focused reviewer with 30–70K +``` + +чем заставлять root делать ещё несколько десятков model calls с 200K-контекстом. + +## Важное ограничение + +Subagent должен получать **узкую задачу**. + +Нежелательно без необходимости использовать: + +```text +fork_turns="all" +``` + +В первом SDD workflow именно этот режим использовался и требует оптимизации. + +--- + +# 8. Skills влияют, но не являются проблемой №1 + +Простой запрос: + +```text +какой skill мне использовать? +``` + +имел первый input примерно: + +```text +20 479 tokens +``` + +То есть в Codex Desktop уже существует около **20K+ стартового context overhead** до серьёзной работы. + +В него входят: + +- Codex app instructions; +- tool schemas; +- environment; +- plugin information; +- workspace state; +- AGENTS; +- другие системные данные. + +Например, только Codex app-context занимает около 35K символов, а список `recommended_plugins` — ещё примерно 6.7K символов. + +Это почти невозможно оптимизировать на уровне проекта. + +Но skills добавляют дополнительный overhead. + +`ui-ux-pro-max` инжектировал примерно: + +```text +~16 036 символов skill content +``` + +Первый model call после этого был около: + +```text +26 796 tokens +``` + +## Рекомендуемая структура больших skills + +```text +SKILL.md + ↓ +короткий orchestration/router + ↓ +references/ + ├── colors.md + ├── typography.md + ├── tables.md + ├── finance.md + └── ... +``` + +Reference-файлы читаются только при необходимости. + +Этот подход особенно полезен для собственных больших skills. + +--- + +# 9. Reasoning effort пока не стоит оптимизировать первым + +За весь набор: + +```text +Input 60,883,487 +Output 233,968 +Reasoning 66,327 +``` + +Reasoning составляет очень небольшую часть общего расхода. + +Даже сильное уменьшение reasoning не решит проблему с десятками миллионов input tokens. + +Для механических операций вроде: + +```text +npm test +lint +git status +mechanical implementation +``` + +high reasoning действительно может быть избыточным. + +Но по приоритету эта оптимизация значительно ниже context management. + +--- + +# 10. Реальный рост Codex quota + +В rollout записывается primary rate limit: + +```text +window_minutes: 10080 +``` + +10080 минут = 7 дней. + +За исследованный кусок дня показатель изменился примерно так: + +```text +начало первой сессии: 33% +после неё: 47% +после карточки: 53% +конец последней: 62% +``` + +То есть: + +```text +33% → 62% +``` + +или около: + +```text ++29 процентных пунктов 7-дневного лимита +``` + +Ощущение, что Codex слишком быстро расходует quota, подтверждается логами. + +--- + +# Приоритеты оптимизации + +| Priority | Изменение | Потенциальный эффект | +|---|---|---| +| 🔴 P0 | **Разделять длинную feature на SDD / implementation / review sessions** | Очень высокий | +| 🔴 P0 | **Сокращать количество model ↔ tool round-trips** | Очень высокий | +| 🔴 P0 | **Batch/parallel независимые tool calls** | Очень высокий | +| 🟠 P1 | Не читать governance/docs полностью перед каждой работой | Высокий | +| 🟠 P1 | `rg → targeted sed`, а не большие `sed/cat` | Высокий | +| 🟠 P1 | `git diff --stat/name-only → targeted diff` | Высокий | +| 🟠 P1 | Ограничивать test/build output | Средне-высокий | +| 🟡 P2 | Не использовать `fork_turns=all` без необходимости | Средний | +| 🟡 P2 | Большие skills разбить на lazy references | Средний | +| 🟢 P3 | Снижать reasoning для механической работы | Низкий относительно остального | + +--- + +# Предлагаемые token budgets + +Для дальнейшей разработки можно использовать ориентиры: + +```text +Healthy session + +initial context: 20–40K +normal working context: <100K +warning: >120K +restart/handoff: >150K + +model calls / phase: желательно <50 +tool output / call: желательно <3–5K tokens +``` + +Эти значения следует воспринимать как практические budgets для текущего workflow, а не как жёсткие ограничения Codex. + +--- + +# Основной принцип оптимизации + +Не стоит использовать compaction только как последнее средство. + +В SDD естественной точкой compaction/handoff должен стать **готовый артефакт**. + +Например: + +```text +долго обсуждали + ↓ +получили approved design.md + ↓ +старый разговор больше не нужен + ↓ +NEW SESSION + ↓ +Implement change X according to approved +proposal/specs/design/tasks +``` + +То есть: + +> **SDD artifact должен быть interface между агентными сессиями, а не только документацией внутри одной огромной сессии.** + +Это позволяет сохранить качество и одновременно удалить значительную часть исторического шума. + +Implementation-agent получает не всю историю обсуждений, а только авторитетные артефакты и необходимый код. + +--- + +# Предлагаемое направление: Token-Efficient SDD v2 + +Следующий этап оптимизации имеет смысл строить вокруг следующих вопросов: + +1. Где именно должны находиться границы Codex sessions. +2. Какие OpenSpec-артефакты должны передаваться между фазами. +3. Какие документы обязательны для чтения, а какие должны загружаться лениво. +4. Когда использовать root agent, а когда focused subagent. +5. Какой context передавать subagent. +6. Какие ограничения ввести для: + - `sed`; + - `cat`; + - `git diff`; + - test output; + - build output; + - debug tracing. +7. Как batch-ить независимые tool calls. +8. Когда автоматически рекомендовать завершить session и начать новую. +9. Какие token budgets использовать как guardrails. +10. Как измерять эффективность изменений по rollout-файлам. + +--- + +# Итог + +Текущая проблема не выглядит как: + +```text +Codex слишком много думает +``` + +или: + +```text +OpenSpec сам по себе слишком дорогой +``` + +Основная проблема выглядит так: + +```text +большой накопленный context + × +очень много model calls + × +повторное чтение больших outputs/files + = +огромный cumulative input usage +``` + +Поэтому максимальный эффект даст не сокращение качества спецификаций и не отказ от SDD, а изменение **agent execution model**: + +```text +короче sessions ++ artifact handoff ++ lazy context ++ targeted reads ++ narrow diffs ++ compact tool output ++ batched tool calls ++ focused subagents +``` + +Это должно стать основой следующей версии SDD workflow. diff --git a/development/README.md b/development/README.md index a34f906..9f0c12c 100644 --- a/development/README.md +++ b/development/README.md @@ -9,4 +9,5 @@ - [Audit remediation registry](audit-remediation.md) — текущий статус findings, следующий OpenSpec change и evidence завершённых улучшений. - [Engineering governance](engineering-governance.md) — Change Owner, SDD approvals, Delivery Map, risk-based testing, build-versus-buy и hard guardrails. - [OpenSpec authority и lifecycle](openspec-authority-and-lifecycle.md) — единственный SDD store, границы постоянной документации и условия archive. +- [Token-efficient agent workflow](agent-token-efficiency.md) — lazy context routing, session handoff, evidence batching и protocol активного pilot. - [Проверка runtime OpenAPI](runtime-openapi-verification.md) — отдельный read-only contract gate и его границы. diff --git a/development/agent-token-efficiency.md b/development/agent-token-efficiency.md new file mode 100644 index 0000000..b054c54 --- /dev/null +++ b/development/agent-token-efficiency.md @@ -0,0 +1,101 @@ +# Token-efficient agent workflow + +## Статус и границы + +Эта инструкция описывает действующий guidance для сокращения повторной передачи +agent context. Она не меняет SDD lifecycle, approvals, canonical gates, semantic +verification или independent review и не является hard guardrail. + +Исходный 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. + +## Routing context + +До чтения supporting documentation агент определяет: + +1. тип работы и текущую SDD-фазу, если change versioned; +2. affected repositories и их canonical gates; +3. capability или source identity, нужные для следующего решения. + +После этого загружается только применимый 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 | + +Supporting material загружается on demand, если возникший вопрос меняет +семантику, архитектуру, audit disposition или обязательный gate. Guidance нельзя +использовать как основание пропустить необходимую authority. + +## Handoff между agent-сессиями + +Approved planning artifact, завершённый implementation slice или verification +outcome являются естественной границей новой Codex task. Минимальный handoff: + +```text +Change: +Approved through: +Current phase: +Affected areas: +Unresolved blockers: +Next allowed outcome: +``` + +Planning content не копируется: новая task читает его из canonical OpenSpec +store. Если явный approval недоступен в новой task, агент повторно запрашивает +его и не выводит решение владельца только из наличия artifact. + +Для handoff Apply → Verify дополнительно передаются фактический scope изменённых +areas и unresolved failures. Полная история tool calls не передаётся. + +## 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 — способ убрать заведомо +нерелевантный шум, а не обрезать доказательства. + +## Pilot protocol + +Pilot change `optimize-agent-token-workflow` остаётся active до 10 завершённых +post-activation SDD-фаз минимум по двум changes. Для каждой попытки local +non-authority dataset содержит: + +- change identity, phase type и краткий workload scope; +- cumulative input, model calls, context-depth indicators и tool-output volume; +- canonical-gate outcome, fix cycles и independent-review findings; +- completed или interrupted outcome и причину interruption. + +Interrupted attempts учитываются отдельно и не исчезают из quality assessment. +Raw prompts, source contents и rollout logs в Git не добавляются. +Рабочий dataset хранится локально в workspace root как +`.agent-token-pilot.json`; workspace root не является Git-репозиторием, а файл +не является planning, handoff или documentation authority. + +Сравнение выполняется внутри одинаковых phase types и близкого scope, когда это +возможно. Aggregate сопровождается ограничениями неоднородности. Снижение +resource usage считается улучшением только без ухудшения gate success, rework и +review findings. Итоговый versioned report публикует method, scope, aggregates, +confounders и verdict; он не экстраполирует quota или стоимость без provider +contract. diff --git a/development/engineering-governance.md b/development/engineering-governance.md index e241ea8..350b346 100644 --- a/development/engineering-governance.md +++ b/development/engineering-governance.md @@ -46,6 +46,30 @@ artifact. Изменение принятого upstream artifact инвалидирует approval зависимых артефактов: Proposal — Specs, Design и Tasks; Specs — Design и Tasks; Design — Tasks. Tasks не могут неявно расширять scope или менять поведение и архитектуру: работа возвращается к соответствующему upstream artifact. +## Token-efficient agent execution + +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 запрашивается повторно. + +Независимые 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. + +Эффективность оценивается на завершённую 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). + ## Delivery Map и multi-repository delivery Design каждого change оценивает все четыре области: diff --git a/development/openspec-authority-and-lifecycle.md b/development/openspec-authority-and-lifecycle.md index 034847c..59e3b26 100644 --- a/development/openspec-authority-and-lifecycle.md +++ b/development/openspec-authority-and-lifecycle.md @@ -68,6 +68,26 @@ openspec schema which wealth-ledger-sdd --json `schema which` должен указывать project-local source. `specs/openspec/config.yaml` хранит default schema и компактный routing context, а не копию полной policy. +## Stage context и handoff + +До supporting reads agent определяет текущую OpenSpec-фазу и affected areas. +Native instruction и возвращённые `contextFiles` задают planning context; +repository-local `AGENTS.md` добавляет только routing и canonical gate своей +area. Architecture, glossary, audit registry и подробный operational playbook +загружаются по применимому trigger, а не blanket-набором перед любой задачей. + +После явного approval planning artifact следующая фаза может начаться в новой +Codex task. Handoff сохраняет change identity, последний approved artifact, +current phase, affected areas, unresolved blockers и один следующий outcome. +Содержание artifacts повторно не пересказывается и остаётся в canonical store. +Если явный approval нельзя подтвердить из новой task, agent повторно запрашивает +его до создания downstream artifact. + +Apply → Verify использует ту же boundary, добавляя фактический implementation +scope и unresolved failures без полной истории tool calls. Подробная форма +handoff и evidence-batching guidance описаны в +[Token-efficient agent workflow](agent-token-efficiency.md). + ## Agent entrypoints и обновление OpenSpec Root `.opencode/commands` и `.opencode/skills` — локальные non-authority diff --git a/package.json b/package.json index d15e121..3e03529 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,7 @@ }, "scripts": { "runtime:check": "node scripts/verify-node-version.mjs", - "lint": "markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#audits/2026-08-26-wealth-ledger-sdd/*-result.md\" \"#audits/2026-08-26-wealth-ledger-sdd-v2-review/*-audit.md\"", + "lint": "markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#audits/2026-08-26-wealth-ledger-sdd/*-result.md\" \"#audits/2026-08-26-wealth-ledger-sdd-v2-review/*-audit.md\" \"#audits/codex-sessions-token-audit-2026-08-26.md\"", "verify": "npm run runtime:check && npm run lint && git diff --check" }, "devDependencies": {