# Token-efficient agent workflow

## Authority и границы

Этот документ — 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 сохранён в
[аудите сессий 26.08.2026](../audits/codex-sessions-token-audit-2026-08-26.md).
Raw logs и числовые token budgets не становятся delivery gates. Экономия
контекста не оправдывает пропуск relevant authority или ослабление verification.

## Routing context

До supporting reads определите текущую роль, разрешённый outcome и affected
repositories. Прочитайте их local `AGENTS.md` для boundaries и canonical gates,
затем только применимую authority:

| Trigger | Context |
| --- | --- |
| Planning или Implementation | Native instruction и каждый возвращённый context file; применимые материалы через canonical Design |
| 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 |

В новой роли canonical artifacts читаются заново только в необходимом scope.
В том же context повторно читаются изменившиеся relevant inputs. История чата
не заменяет artifact и не является обязательным prerequisite.

## Recovery и handoff

При наличии session adapter mutable state является единственным navigation
pointer. Прочитайте только его текущий self-contained immutable record, затем
phase-specific authority. Без adapter тот же актуальный envelope передаётся
в доступном рабочем контексте; отдельный versioned verdict или planning store
ради handoff не создаётся.

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.

Первичное `approved` записывается только после явного решения Change Owner,
со ссылкой на наблюдённый источник решения, artifact identity и fingerprint.
При recovery совпадение позволяет продолжить без повторного approval. Отсутствие
binding, включая legacy state, требует явного решения; mismatch сбрасывает
approval изменённого artifact и всех downstream artifacts. Approval status
сохраняет наблюдение, но не доказывает личность или решение владельца сам по себе.

Порядок сохранения: `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 и Tasks — соответствующий canonical файл. Design — его Markdown
  и все перечисленные применимые материалы, включая exact immutable reuse
  inputs. Перечень разрешается из Design, без параллельного visual registry;
  missing, ambiguous или изменённый материал блокирует dependent outcome по
  [UI/UX policy](engineering-governance.md#uiux-пакет-design). Сам Design не
  содержит собственного digest. 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

Один 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 отдельно.