Token-efficient agent workflow

Authority и границы

Этот документ — vendor-neutral authority для context discipline: recovery, fingerprint bindings, bounded reads и observed evidence. Lifecycle ownership принадлежит Engineering governance, native команды — OpenSpec lifecycle. Эти процедуры выполняются без обязательных skills, session adapter, telemetry или service.

Исходный наблюдаемый baseline сохранён в аудите сессий 26.08.2026. 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. Сам 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 изменение.

Детерминированное представление

Для каждого 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 не создаётся.
Только для 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.
Рассчитайте lowercase SHA-256 hex digest payload каждого существующего entry. Отсортируйте entries по UTF-8 bytes workspace-relative path. Непредставимые в UTF-8 paths требуют явного разрешения input issue, а не замены символов.
Соберите 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 отдельно.

13 KiB Raw Blame History Unescape Escape