161 lines
13 KiB
Markdown
161 lines
13 KiB
Markdown
# 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 отдельно.
|