Основные концепции

AWR хранит факты о работе проекта вне любого отдельного диалога агента, поэтому работа переживает потерю контекста, смену агентов и перезапуски. Эта статья объясняет пять идей, лежащих в основе этой модели; команды из Быстрого старта и процедуры из Ежедневного рабочего процесса после этого читаются естественно.

Основной принцип: ваши исходные файлы (реестры, планы) авторитетны, а всё, что хранит среда выполнения — сессии, захваты, свидетельства — является проверяемой проекцией этих фактов. AWR никогда не выдумывает недостающее намерение и никогда не позволяет транскрипту диалога подменять записанный факт.

Факты проекта: исходный реестр

Исходный реестр AWR — это небольшой рабочий контракт, который вы храните в обычных файлах проекта: YAML-реестр вроде work-ledger.yaml или существующий Markdown-реестр (*-ledger.md), который остаётся для AWR доступным только для чтения и редактируется в исходном файле. Реестр фиксирует два вида фактов:

• Цели — чего проект пытается достичь, с критериями успеха. Цели могут быть draft, candidate или needs_confirmation, когда есть неуверенность, и active или confirmed, когда они подкреплены исходным материалом или указанием пользователя. AWR проверяет объявление; он не удостоверяет, что цель соответствует тому, что имел в виду человек.
• Элементы работы — задачи, описанные ниже.

Минимальный реестр выглядит так:

goals:
  - id: search
    title: Let readers find documents
    status: active
    summary: The user requested search in the existing portal; see README.md.
    success_criteria: [Readers find a requested document]
work_items:
  - id: search-api
    title: Add document search
    status: ready
    goal: search
    acceptance: [A matching query returns the requested document]
    next_action: Implement the search handler using the current document index

Вы подводите эти файлы под управление AWR с помощью init. Ничего не записывается, пока вы не примете предпросмотр:

awr --project /absolute/project init
awr --project /absolute/project init --accept
awr --project /absolute/project intake inspect --json

Init никогда не перезаписывает существующие файлы, а инспекция лишь обновляет перестраиваемый кэш проекций — никогда не ваши цели, файлы задач или состояние выполнения.

Задачи: элементы работы

Элемент работы — одна задача в реестре. Его ключевые поля — те, которые AWR может реально проверить:

• acceptance — критерии завершения: что должно быть наблюдаемо истинным, когда задача выполнена. Отчёт о завершении позже проверяется именно по этим критериям.
• next_action — сохранённый следующий шаг и самое ценное поле для восстановления: оно позволяет свежей сессии продолжить без перечитывания истории.
• Вспомогательные поля: summary, goal, kind, paths, tags, priority, depends_on, owner и milestone.

Задачу вы создаёте из JSON-черновика, в котором указаны только явно известные факты:

awr work create --input draft.json

Создание всегда даёт черновик. Отсутствующие цели или обязательные факты остаются видимыми, и черновик не даёт разрешения что-либо выполнять или завершать; его применение — отдельный явный шаг.

AWR также сообщает состояния организации на уровне проекта, такие как not_initialized, needs_organization, ready, blocked, awaiting_verification, completed и closed_without_completion. Два важнее всего в повседневной работе: ready означает, что хотя бы у одной задачи есть объявленная в источнике цель, критерии приёмки, следующее действие и разрешённые предварительные условия; awaiting_verification означает, что реестр говорит, что задачи выполнены, но их отчёты о приёмке ещё не все проверены.

Контрольные точки и сессии

Сессия — рабочая привязка одного агента к элементу работы. Контрольная точка — долговременная запись о том, где эта сессия находится: сохранённое следующее действие, открытые петли и фактическая дельта событий и источников AWR — не копия диалога.

Когда сессия клиента начинается или возобновляется после компактификации, AWR возвращает контекст восстановления, построенный из контрольной точки. Когда ход останавливается или завершается, изменённое следующее действие и открытые петли сохраняются до того, как могут быть потеряны:

awr client progress --client codex --external-session CLIENT_ID \
  --next-action "Apply the reviewer corrections" --open-loop "Independent review remains"

Дублирующиеся события с неизменённой работой переиспользуют свою контрольную точку; продолженный ход с изменённым прогрессом создаёт новую. Одна честная граница: нативный hook-адаптер, автоматизирующий это, сейчас установлен только для Codex. Другие хосты используют L0-биндер (--client generic), который привязывает диалог хоста к активной сессии AWR без установки хуков. Адаптер никогда не читает тела транскриптов — он записывает то, что вы ему сообщаете, а не то, что сказала модель.

Захваты и передача

Захват — явная блокировка, которую сессия удерживает перед выполнением задачи. AWR требует получить захват сессии до выполнения, а завершение проверяет его повторно — так два агента не работают незаметно над одной и той же задачей.

Передача перемещает работу от одной сессии или клиента преемнику. Вы возобновляете сессию явно, с проверками ревизий и переходом к преемнику:

awr session resume --from-session AWR_SESSION_ID --agent successor \
  --provider generic --model selected-model --no-claim --expected-revision REVISION

Или привяжите новый диалог клиента к его предшественнику:

awr client bind --client generic --external-session NEW_CLIENT_ID \
  --work INTAKE-001 --from-session AWR_PREDECESSOR_ID

Передача перемещает записанные факты — состояние реестра, контрольные точки, историю выполнения — а не память процесса. Хуки завершения работы носят совещательный характер: они никогда не освобождают захваты и не завершают сессии — это остаётся вашей явной ответственностью при передаче.

Доставка и приёмка

Приёмка — место, где AWR сознательно строг. Задача не выполнена потому, что кто-то написал status: completed в реестре. Она выполнена, когда зарегистрированный отчёт о завершении подтверждается по текущим критериям приёмки реестра.

Отчёт о завершении фиксирует реально выполненную команду, реально проверенную область, время и именованные проверки — каждая соответствует точному критерию приёмки и описывает наблюдаемый результат, а не предполагаемый:

{
  "version": 1,
  "work_item": "WORK",
  "source_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "command": "the command or verification procedure actually executed",
  "scope": ["the scope actually verified"],
  "verified_at": 1,
  "checks": [{
    "name": "independent check name",
    "passed": true,
    "details": "the observed outcome, not an intended result",
    "criteria": ["an exact current source acceptance criterion"]
  }]
}

Перед завершением вы проводите предварительную проверку отчёта:

awr work prepare-completion WORK --report report.json --evidence-key KEY \
  --source-sha FULL_SHA --level locally_verified

Предварительная проверка не выполняет никаких команд, не регистрирует свидетельств и не завершает задач — она читает байты отчёта и возвращает аргументы свидетельства и отображение на приёмку. Само завершение — отдельная запись, которая перепроверяет захваты, зависимости, свежесть источника и байты отчёта; изменение отчёта после предварительной проверки аннулирует его дайджест. Объявленное в источнике завершение само по себе никогда не даёт проверенной квитанции, и source_completed и verified_completed остаются отдельными счётчиками в отчётах о статусе.

Одна задача от начала до конца

Свяжем всё вместе на задаче поиска из реестра выше:

1. Факты. Вы выполняете awr --project /absolute/project init --accept; реестр с целью search и элементом работы search-api становится авторитетным.
2. Задача. Элемент работы несёт критерии приёмки и следующее действие, поэтому проект сообщает ready.
3. Сессия и захват. Вы готовите работу из одного снимка, затем получаете захват сессии до того, как трогать код:

   awr work prepare search-api --session AWR_SESSION_ID --source-sha FULL_SHA

4. Контрольная точка. По мере работы вы сохраняете прогресс через awr client progress, чтобы следующее действие и открытые петли пережили сбой или компактификацию.
5. Передача (при необходимости). Преемник возобновляет работу через awr session resume --from-session … и получает те же факты без воспроизведения истории чата.
6. Доставка. Вы пишете отчёт, чьи проверки соответствуют точным критериям приёмки, проводите его предварительную проверку через awr work prepare-completion и только затем записываете завершение. Статус теперь показывает задачу как проверенную относительно SHA источника, а не просто отмеченную выполненной.

Куда двигаться дальше

• Быстрый старт — прогоните эти концепции в первый раз.
• Ежедневный рабочий процесс — рутинный цикл подготовки, захвата, контрольной точки и завершения.